diff --git a/.gitignore b/.gitignore index 5d9007f05d44..08ec31762c07 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,5 @@ dev_guide/builds/images/chained-build.png.cache .gem bin commercial_package +.vscode +.vale diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 421c9e8214e0..000000000000 --- a/.travis.yml +++ /dev/null @@ -1,19 +0,0 @@ -language: python - -cache: pip - -sudo: required - -before_install: - - gem install asciidoctor - - gem install asciidoctor-diagram - -install: - - pip3 install pyyaml - - pip3 install aura.tar.gz - -script: - - python3 build.py --distro openshift-enterprise --product "OpenShift Container Platform" --version 4.7 --no-upstream-fetch && python3 makeBuild.py - -after_success: -- bash ./automerge.sh diff --git a/.travis.yml.old b/.travis.yml.old new file mode 100644 index 000000000000..c05f06b0ae16 --- /dev/null +++ b/.travis.yml.old @@ -0,0 +1,45 @@ +language: python +cache: + pip: true + directories: + - /home/travis/.rvm/gems +git: + depth: 2 +jobs: + allow_failures: + env: + - CAN_FAIL=true + + include: + - stage: cache-and-validate + name: "Create install cache and validate updated assemblies" + install: + - gem install asciidoctor asciidoctor-diagram rouge + - pip3 install pyyaml aura.tar.gz + script: + # Fail if Asciidoctor encounters errors. Run only if there are modified AsciiDoc files + - chmod +x ./scripts/check-asciidoctor-build.sh + - ./scripts/check-asciidoctor-build.sh || travis_terminate 1 + + - stage: build + name: "Build openshift-acs distro" + install: + - gem install asciidoctor asciidoctor-diagram rouge + - pip3 install pyyaml aura.tar.gz + script: + - python3 build.py --distro openshift-acs --product "Red Hat Advanced Cluster Security for Kubernetes" --version 4.1 --no-upstream-fetch && python3 makeBuild.py + + - stage: netlify + name: "Create Netlify preiview" + env: + - CAN_FAIL=true + language: minimal + if: type IN (pull_request) AND branch IN (rhacs-docs, rhacs-docs-4.1, rhacs-docs-4.2, rhacs-docs-4.3, rhacs-docs-4.4) + script: + - chmod +x autopreview.sh + - ./autopreview.sh + +stages: + - cache-and-validate + - build + - netlify diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000000..4746c2d9f605 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,30 @@ +StylesPath = .vale/styles + +MinAlertLevel = suggestion + +Packages = RedHat, AsciiDoc, OpenShiftAsciiDoc + +# Ignore files in dirs starting with `.` to avoid raising errors for `.vale/fixtures/*/testinvalid.adoc` files +[[!.]*.adoc] +BasedOnStyles = RedHat, AsciiDoc, OpenShiftAsciiDoc + +# Disabling rules (NO) +RedHat.ReleaseNotes = NO + +# Use local OpenShiftDocs Vocab terms +Vale.Terms = YES +Vale.Avoid = YES + +# Disable module specific rules +OpenShiftAsciiDoc.ModuleContainsParentAssemblyComment = NO +OpenShiftAsciiDoc.NoNestingInModules = NO +OpenShiftAsciiDoc.NoXrefInModules = NO +OpenShiftAsciiDoc.IdHasContextVariable = NO +OpenShiftAsciiDoc.NoTocInModules = NO + +# Optional: pass doc attributes to asciidoctor before linting +# Temp values are used for Prow CI comment linting only +[asciidoctor] +temp-ifdef = YES +temp-ifndef = NO +temp-ifeval = temp diff --git a/.yamllint b/.yamllint new file mode 100644 index 000000000000..db8d47ebf1ea --- /dev/null +++ b/.yamllint @@ -0,0 +1,11 @@ +--- +extends: relaxed +rules: + indentation: { spaces: 2, indent-sequences: false } + line-length: disable + colons: + max-spaces-before: 0 + max-spaces-after: 1 + empty-lines: disable + trailing-spaces: enable + new-line-at-end-of-file: enable diff --git a/_distro_map.yml b/_distro_map.yml index 46a417972f5d..23c318e520ee 100644 --- a/_distro_map.yml +++ b/_distro_map.yml @@ -1,183 +1,11 @@ --- -openshift-origin: - name: OKD - author: OKD Documentation Project - site: community - site_name: Documentation - site_url: https://docs.okd.io/ - branches: - master: - name: 4 - dir: latest - enterprise-3.2: - name: '1.2' - dir: '1.2' - enterprise-3.3: - name: '1.3' - dir: '1.3' - enterprise-3.4: - name: '1.4' - dir: '1.4' - enterprise-3.5: - name: '1.5' - dir: '1.5' - enterprise-3.6: - name: '3.6' - dir: '3.6' - enterprise-3.7: - name: '3.7' - dir: '3.7' - enterprise-3.9: - name: '3.9' - dir: '3.9' - enterprise-3.10: - name: '3.10' - dir: '3.10' - enterprise-3.11: - name: '3.11' - dir: '3.11' -openshift-online: - name: OpenShift Online - author: OpenShift Documentation Project - site: commercial - site_name: Documentation - site_url: https://docs.openshift.com/ - branches: - enterprise-3.11: - name: 'Pro' - dir: online/pro -openshift-enterprise: - name: OpenShift Container Platform - author: OpenShift Documentation Project - site: commercial - site_name: Documentation - site_url: https://docs.openshift.com/ - branches: - enterprise-3.0: - name: '3.0' - dir: enterprise/3.0 - distro-overrides: - name: OpenShift Enterprise - enterprise-3.1: - name: '3.1' - dir: enterprise/3.1 - distro-overrides: - name: OpenShift Enterprise - enterprise-3.2: - name: '3.2' - dir: enterprise/3.2 - distro-overrides: - name: OpenShift Enterprise - enterprise-3.3: - name: '3.3' - dir: container-platform/3.3 - enterprise-3.4: - name: '3.4' - dir: container-platform/3.4 - enterprise-3.5: - name: '3.5' - dir: container-platform/3.5 - enterprise-3.6: - name: '3.6' - dir: container-platform/3.6 - enterprise-3.7: - name: '3.7' - dir: container-platform/3.7 - enterprise-3.9: - name: '3.9' - dir: container-platform/3.9 - enterprise-3.10: - name: '3.10' - dir: container-platform/3.10 - enterprise-3.11: - name: '3.11' - dir: container-platform/3.11 - enterprise-4.1: - name: '4.1' - dir: container-platform/4.1 - enterprise-4.2: - name: '4.2' - dir: container-platform/4.2 - enterprise-4.3: - name: '4.3' - dir: container-platform/4.3 - enterprise-4.4: - name: '4.4' - dir: container-platform/4.4 - enterprise-4.5: - name: '4.5' - dir: container-platform/4.5 - enterprise-4.6: - name: '4.6' - dir: container-platform/4.6 - enterprise-4.7: - name: '4.7' - dir: container-platform/4.7 - enterprise-4.8: - name: '4.8' - dir: container-platform/4.8 -openshift-dedicated: - name: OpenShift Dedicated - author: OpenShift Documentation Project +openshift-acs: + name: Red Hat Advanced Cluster Security for Kubernetes + author: OpenShift documentation team site: commercial site_name: Documentation site_url: https://docs.openshift.com/ branches: - enterprise-3.11: - name: '3' - dir: dedicated/3 - enterprise-4.3: - name: '4' - dir: dedicated/4 - dedicated-4: + rhacs-docs: name: '' - dir: dedicated/ -openshift-aro: - name: Azure Red Hat OpenShift - author: OpenShift Documentation Project - site: commercial - site_name: Documentation - site_url: https://docs.openshift.com/ - branches: - enterprise-3.11: - name: '3' - dir: aro/3 - enterprise-4.3: - name: '4' - dir: aro/4 -openshift-rosa: - name: Red Hat OpenShift Service on AWS - author: OpenShift Documentation Project - site: commercial - site_name: Documentation - site_url: https://docs.openshift.com/ - branches: - dedicated-4: - name: '' - dir: rosa/ -partner-roks: - name: Red Hat OpenShift on IBM Cloud - author: OpenShift Documentation Project - site: commercial - site_name: Documentation - site_url: https://docs.openshift.com/ - branches: - enterprise-4.3: - name: '4' - dir: roks/4 -openshift-webscale: - name: OpenShift Container Platform - author: OpenShift Documentation Project - site: commercial - site_name: Documentation - site_url: https://docs.openshift.com/ - branches: - enterprise-4.4: - name: '4.4' - dir: container-platform-ocp/4.4 - enterprise-4.5: - name: '4.5' - dir: container-platform-ocp/4.5 - enterprise-4.7: - name: '4.7' - dir: container-platform-ocp/4.7 + dir: acs diff --git a/_javascripts/page-loader.js b/_javascripts/page-loader.js index c0b516a97e72..ca0a0cfe1fba 100644 --- a/_javascripts/page-loader.js +++ b/_javascripts/page-loader.js @@ -1,50 +1,125 @@ +let newLink = ""; +let newVersion = ""; +let currentVersion = ""; +let fileRequested = ""; + +const urlMappings = { + "openshift-acs": "https://docs.openshift.com/acs/", + "openshift-builds": "https://docs.openshift.com/builds/", + "openshift-enterprise": "https://docs.openshift.com/container-platform/", + "openshift-gitops": "https://docs.openshift.com/gitops/", + "openshift-lightspeed": "https://docs.openshift.com/lightspeed/", + "openshift-origin": "https://docs.okd.io/", + "openshift-pipelines": "https://docs.openshift.com/pipelines/", + "openshift-serverless": "https://docs.openshift.com/serverless/", + "openshift-telco": "https://docs.openshift.com/container-platform-telco/", +}; + function versionSelector(list) { + "use strict"; - // the version we want newVersion = list[list.selectedIndex].value; - // the new final link to load - newLink = ""; - - // the fileRequested - var fileRequested = ""; - - // spilt the current path - var pathArray = window.location.pathname.split( '/' ); - - // so we can get the current version - currentVersion = pathArray[2]; - - // if switching major versions, just take the user to the main landing page - // as files change a lot between major versions. - - if(currentVersion.charAt(0) === newVersion.charAt(0)) { - // the file path is just the version number + the end of the path - fileRequested = - window.location.pathname.substring( - window.location.pathname.lastIndexOf(currentVersion) + - currentVersion.length); + if (dk === "openshift-origin") { + currentVersion = window.location.pathname.split("/")[1]; } else { - fileRequested = "/welcome/index.html"; + currentVersion = window.location.pathname.split("/")[2]; } + let baseUrl = urlMappings[dk]; - // alert(fileRequested); + //Handle special OCP case + if (["3.0", "3.1", "3.2"].includes(newVersion) && dk === "openshift-enterprise") { + baseUrl = "https://docs.openshift.com/enterprise/"; + } - // in 3.3 and above, we changed to container-platform - if(newVersion == '3.0' || newVersion == '3.1' || newVersion == '3.2') { - newLink = "https://docs.openshift.com/enterprise/" + - newVersion + - fileRequested; + if ((dk === "openshift-enterprise" || dk === "openshift-origin") && currentVersion.charAt(0) !== newVersion.charAt(0)){ + fileRequested = "/welcome/index.html"; } else { - newLink = "https://docs.openshift.com/container-platform/" + - newVersion + - fileRequested; + const versionIndex = window.location.pathname.lastIndexOf(currentVersion) + currentVersion.length; + fileRequested = window.location.pathname.substring(versionIndex); } + newLink = `${baseUrl}${newVersion}${fileRequested}`; + // without doing async loads, there is no way to know if the path actually // exists - so we will just have to load - window.location = newLink; + // window.location = newLink; + // testing async validations + $.ajax({ + type: 'HEAD', + url: newLink, + success: function() { + window.location.href = newLink; + }, + error: function(jqXHR, exception) { + if(jqXHR.status == 404) { + list.value = currentVersion; + const confirmMessage = `This page doesn't exist in version ${newVersion}. Click OK to search the ${newVersion} docs OR Cancel to stay on this page.`; + if(confirm(confirmMessage)) { + let searchUrl; + if (["3.0", "3.1", "3.2"].includes(newVersion) && dk === "openshift-enterprise") { + searchUrl = `https://google.com/search?q=site:${baseUrl}${newVersion} ${document.title}`; + } else { + searchUrl = `https://google.com/search?q=site:${urlMappings[dk]}${newVersion} ${document.title}`; + } + window.location.href = searchUrl; + } else { + // do nothing, user doesn't want to search + } + } else { + window.location.href = newLink; // assumption here is that we can follow through with a redirect + } + } + }); +} + +// checks what language was selected and then sends the user to the portal for their localized version +function selectLang(langList) { + + var lang = langList[langList.selectedIndex].value; + var winPath = window.location.pathname; + + console.log("Lang: " + lang); + console.log("Win Path: " + winPath); + + var currentVersion = document.getElementById("version-selector").value; + console.log("CurrentVersion: " + currentVersion); + + // path for the file to reference on portal (the last bit removes .html) + var path = winPath.substring(winPath.lastIndexOf(currentVersion) + (currentVersion.length + 1), winPath.length - 5); + + var parts = path.split("/"); + + console.log(parts); + + // map things to html-single. While plain HTML is preferred, it is harder to map and get all anchors right. html-single ensures there is no 404 and the user at least lands on the right book + console.log(parts[parts.length-1]); + + var anchorid = parts[parts.length-1]; + var book = parts[0]; + + // add changed book names here + if(book == "updating") book = "updating_clusters"; + if(book == "virt") book = "openshift_virtualization"; + if(book == "post_installation_configuration") book = "post-installation_configuration"; + + // var section = parts[1].replace(/\_/g, "-"); // replace underscore with dash + // var section = subGroup.toLowerCase().replace(" ", "-"); + // console.log(section); + // var subsection = parts[2].replace(/\_/g, "-"); + // console.log(subsection); + + // path = book + "/" + section + "#" + subsection; + path = book + "#" + anchorid; + + console.log("Path: " + path); + + var portalBaseURL = "https://access.redhat.com/documentation"; + var finalURL = portalBaseURL + "/" + lang + "/openshift_container_platform/" + currentVersion + "/html-single/" + path; + + console.log("Final URL: " + finalURL); + window.location.href = finalURL; } @@ -87,8 +162,8 @@ function selectVersion(currentVersion) { // main file to edit is the file path after the version to the html at // the end. - // Example: https://docs.openshift.com/container-platform/4.4/updating/updating-cluster-between-minor.html - // file path is updating/updating-cluster-between-minor.adoc + // Example: https://docs.openshift.com/container-platform/4.4/updating/updating-cluster-within-minor.html + // file path is updating/updating-cluster-within-minor.adoc mainFileToEdit = window.location.pathname.substring( diff --git a/_snippets/glusterfs.adoc b/_snippets/glusterfs.adoc deleted file mode 100644 index bb6b2cbe2acc..000000000000 --- a/_snippets/glusterfs.adoc +++ /dev/null @@ -1,27 +0,0 @@ -//// -How to use this file: - -* Use `include::_snippets/glusterfs.adoc[]` to enable the variables on a given - page. -* When discussing the storage technology itself, just use "GlusterFS", e.g. - "GlusterFS volumes". It is incorrect to say, for example, "Red Hat Gluster - Storage volumes". -* When discussing the base project or product, use `{gluster}`. -* When discussing configurations of {gluster} that are managed by heketi, use - `{gluster-native}` if {gluster} is containerized and `{gluster-external}` if - it is not containerized. -//// -:gluster: GlusterFS -:gluster-native: Containerized GlusterFS -:gluster-external: External GlusterFS -:gluster-install-link: https://docs.gluster.org/en/latest/Install-Guide/Overview/ -:gluster-admin-link: https://docs.gluster.org/en/latest/Administrator%20Guide/overview/ -:gluster-role-link: https://github.com/openshift/openshift-ansible/tree/master/roles/openshift_storage_glusterfs -ifdef::openshift-enterprise,openshift-webscale[] -:gluster: Red Hat Gluster Storage -:gluster-native: Container-Native Storage -:gluster-external: Container-Ready Storage -:gluster-install-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/installation_guide/ -:gluster-admin-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/administration_guide/ -:cns-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/container-native_storage_for_openshift_container_platform/ -endif::[] diff --git a/_stylesheets/docs.css b/_stylesheets/docs.css index 433a38952bee..cdc1a0bff0b3 100644 --- a/_stylesheets/docs.css +++ b/_stylesheets/docs.css @@ -4,15 +4,30 @@ nav#main { .navbar.navbar-default.navbar-openshift.navbar-origin { background: - linear-gradient( - rgba(0, 61, 110, 0.34), - rgba(0, 61, 110, 0.34) - ), - url("https://github.com/_images/origin-masthead.jpg") 20% 25% repeat-x; + linear-gradient(rgba(0, 61, 110, 0.34), rgba(0, 61, 110, 0.34)), url("https://github.com/_images/origin-masthead.jpg") 20% 25% repeat-x; background-size: 150rem; border: 0; height: 90px; margin-bottom: 20px; + z-index: 10; +} + +/* fixed look and feel for OKD sidebar and toc update */ + +@media (min-width: 1425px) { + .navbar.navbar-default.navbar-openshift.navbar-origin { + width: 100%; + position: fixed; + z-index: 10; + } +} + +@media (max-width: 767px) { + .navbar-default .navbar-collapse, .navbar-default .navbar-form { + border-color: #dedede; + background: white; + filter: drop-shadow(0.6em 0.01em 0.2em); + } } .navbar.navbar-default.navbar-openshift .navbar-brand.origin { @@ -21,6 +36,23 @@ nav#main { margin-left: 20px; } +/* Styling for new page/section edit buttons */ +.edit-page-button { + z-index: 1; + /* Absolutely aligns element with next "relative" parent */ + position: absolute; + top: 15px; + /* 25px to match parent padding */ + right: 25px; +} +.edit-section-button { + z-index: 1; + float: right; + position: relative; + top: 5px; + right: 10px; +} + /* Tweaks for the Google-generated search widget */ .cse .gsc-control-cse, .gsc-control-cse, table.gsc-search-box td.gsc-input { padding: 0; @@ -30,7 +62,7 @@ td.gsc-clear-button { display: none; } -div.gsc-option-menu-container > div.gsc-selected-option-container { +div.gsc-option-menu-container>div.gsc-selected-option-container { width: auto !important } @@ -38,6 +70,21 @@ div.gsc-option-menu-container > div.gsc-selected-option-container { margin: 0 10px; } +/* target safari only hack: https://stackoverflow.com/a/25975282/6758654 */ +/* Addresses https://github.com/openshift/openshift-docs/issues/40909 */ +@media not all and (min-resolution:.001dpcm) { @supports (-webkit-appearance:none) and (stroke-color:transparent) { + #hc-search.wide { + z-index: 50; + margin-top: 28px; + margin-left: -15px; + } + + .sidebar.wide { + padding-top: 30px; + } +}} +/* end safari only */ + /* ------------------------------------------------------------ Image: "Spin" https://www.flickr.com/photos/eflon/3655695161/ Author: eflon https://www.flickr.com/photos/eflon/ @@ -48,15 +95,18 @@ License: https://creativecommons.org/licenses/by/2.0/ position: relative; bottom: -20px; } + .attribution .btn { color: #808080; - color: rgba(175,175,175, .65); + color: rgba(175, 175, 175, .65); font-size: 11px; } + .attribution .btn:hover { text-decoration: none; color: #aaa; } + .popover-content { font-size: 12px; line-height: 1.3; @@ -66,13 +116,15 @@ License: https://creativecommons.org/licenses/by/2.0/ /* Footer Edits 12/11/2015 */ @media screen and (max-width: 768px) { .footer-openshift { - height: 190px; + height: 190px; } } + .footer-openshift a { top: 0; margin-left: 0; } + .footer-origin-docs { padding: 20px; color: #ccc; @@ -82,15 +134,18 @@ License: https://creativecommons.org/licenses/by/2.0/ position: absolute; width: 100%; bottom: 0; + z-index: 999; } .footer-origin-docs a { text-decoration: none; } + #footer_social { text-align: center; margin: 10px 0 20px; } + #footer_social a { margin: 0 10px; } @@ -98,43 +153,52 @@ License: https://creativecommons.org/licenses/by/2.0/ #footer_logo { margin-left: 0; } + #powered_by_openshift img { text-align: center; } + #built_with_asciibinder img { width: 140px; } + @media screen and (min-width: 769px) { - body { - margin-bottom: 200px; - } + body { + margin-bottom: 200px; + } } + @media screen and (max-width: 768px) { .sidebar { border-right: 1px solid #e7e7e7; background: #fff; } - .footer-origin-docs, - .footer-openshift { - display: none; /* hide absolute positioned footer at mobile */ + + .footer-origin-docs, .footer-openshift { + display: none; + /* hide absolute positioned footer at mobile */ } - .visible-xs-block .footer-origin-docs, - .visible-xs-block .footer-openshift { + + .visible-xs-block .footer-origin-docs, .visible-xs-block .footer-openshift { /* show alternate footer positioned relative at mobile */ display: block; position: relative; margin-top: 50px; } + footer { text-align: center; } + footer img { margin: 10px 0; } + footer .text-right { text-align: center !important; } - #footer_social > a { + + #footer_social>a { top: 24px; } } @@ -178,6 +242,7 @@ span.clipboard-button:hover { color: #404040; } } + /* End ClipboardJS edits */ /* Collapsible content */ @@ -185,7 +250,8 @@ details { width: 100%; margin-bottom: 10px; } - details > summary { + +details>summary { font-size: 0.92em; padding: 4px 6px; background-color: #f9f9f9; @@ -193,21 +259,25 @@ details { box-shadow: 2px 2px 2px #8a8a8a; cursor: pointer; margin-top: 0.8em; + margin-bottom: 1.5em; display: list-item; } - details > div { + +details>div { border-radius: 0 0 5px 5px; background-color: #f9f9f9; padding: 4px 6px; - margin: 0.5em 0.7em; + margin: 0.5em 0.7em 1.5em 0.7em; box-shadow: 2px 2px 2px #8a8a8a; } + #collapsibleButtonDiv { position: relative; width: 100%; padding: 1em 0em; font-size: .92em; } + button[name="button-collapse-expand-all"] { position: absolute; right: 100px; @@ -215,8 +285,9 @@ button[name="button-collapse-expand-all"] { margin-right: 10px; z-index: 1; } + .span-collapse-expand-all { - display:inline-block; + display: inline-block; width: 100px; position: absolute; right: 0px; @@ -224,9 +295,11 @@ button[name="button-collapse-expand-all"] { text-align: justify; z-index: 1; } + .span-collapse-expand-all:hover { cursor: pointer; } + /* END Collapsible content */ .fa-inverse:hover { @@ -269,7 +342,7 @@ button[name="button-collapse-expand-all"] { .main h2, .main .h2 { border-top: 0px; - padding-top: 10px; + padding-top: 3px; margin-top: 0; } @@ -286,21 +359,22 @@ button[name="button-collapse-expand-all"] { padding: 2px 0 0 0; } -.ulist p, -.olist p { +.ulist p, .olist p { margin-bottom: 1em; } -.nav > li > a.hover{ +.nav>li>a.hover { background-color: none; } h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 { position: relative; text-transform: none; + overflow-wrap: break-word; + padding-right: 35px !important; } -h2 > a.anchor, h3 > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { +h2>a.anchor, h3>a.anchor, h4>a.anchor, h5>a.anchor, h6>a.anchor { display: block; font-weight: normal; margin-left: -1.5ex; @@ -309,10 +383,10 @@ h2 > a.anchor, h3 > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { text-decoration: none !important; visibility: hidden; width: 1.5ex; - z-index: 1001; + z-index: 2; } -h2 > a.anchor:before, h3 > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { +h2>a.anchor:before, h3>a.anchor:before, h4>a.anchor:before, h5>a.anchor:before, h6>a.anchor:before { content: "\f0c1"; display: block; font-family: FontAwesome; @@ -322,20 +396,11 @@ h2 > a.anchor:before, h3 > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor: padding-top: 0.2em; } -h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { +h4>a.anchor:before, h5>a.anchor:before, h6>a.anchor:before { font-size: 1em; } -h2:hover > a.anchor, -h2 > a.anchor:hover, -h3:hover > a.anchor, -h3 > a.anchor:hover, -h4:hover > a.anchor, -h4 > a.anchor:hover, -h5:hover > a.anchor, -h5 > a.anchor:hover, -h6:hover > a.anchor, -h6 > a.anchor:hover { +h2:hover>a.anchor, h2>a.anchor:hover, h3:hover>a.anchor, h3>a.anchor:hover, h4:hover>a.anchor, h4>a.anchor:hover, h5:hover>a.anchor, h5>a.anchor:hover, h6:hover>a.anchor, h6>a.anchor:hover { visibility: visible; } @@ -345,16 +410,240 @@ h6 > a.anchor:hover { padding-left: 25px; } +/* keyframe animation */ + + @keyframes fadein { + from { opacity: 0; } + to { opacity: 1; } + } + + /* Firefox < 16 */ + @-moz-keyframes fadein { + from { opacity: 0; } + to { opacity: 1; } + } + + /* Safari, Chrome and Opera > 12.1 */ + @-webkit-keyframes fadein { + from { opacity: 0; } + to { opacity: 1; } + } + + /* Internet Explorer */ + @-ms-keyframes fadein { + from { opacity: 0; } + to { opacity: 1; } + } + + /* Opera < 12.1 */ + @-o-keyframes fadein { + from { opacity: 0; } + to { opacity: 1; } + } + +/*fixed sidebar, navbar, and breadcrumb css */ +@media (min-width: 1425px) { + html { + scroll-padding-top: 155px; + /* height of fixed header */ + } + + body { + margin: 0px; + margin-bottom: 40px; + } -@media (min-width: 768px) { .main { - padding-left: 30px; + margin-top: 130px; + border-left: 0px solid #e7e7e7; + margin-left: 315px; + width: 800px; + } + + .sidebar { + font-weight: 300; + overflow-wrap: break-word; + position: fixed; + overflow-y: scroll; + z-index: 2; + width: 300px; + background-color: #fff; + margin-left: 5px; + display: flex; + flex-flow: column; + top: 190px; + bottom: 10px; + display: block; + -webkit-animation: fadein 0.35s ease-in; /* Safari, Chrome and Opera > 12.1 */ + -moz-animation: fadein 0.35s ease-in; /* Firefox < 16 */ + -ms-animation: fadein 0.35s ease-in; /* Internet Explorer */ + -o-animation: fadein 0.35s ease-in; /* Opera < 12.1 */ + animation: fadein 0.35s ease-in; + } + + #hc-search { + position: fixed; + top: 160px; + width: 358px; + } + + #hc-search-btn { + border: 1px solid lightgrey; + font-size: 12px; + height: 25px; + width: 31px; + } + + .breadcrumb { + margin: 0; + padding: 18px 0 10px; + font-size: 0.92em; + min-height: 65px; + position: fixed; + z-index: 2; + background-color: #fff; + width: 1400px; + margin-top: 60px; + margin-left: 5px; } + + .container { + width: 1440px; + position: relative; + } + + nav#main { + height: 90px; + position: fixed; + top: 0; + left: 0; + z-index: 5; + width: 100%; + } + +.page-header h1 { + font-size: 30px; + font-weight: 400; + letter-spacing: inherit; + color: inherit; + margin: 10px 0 0 0; + padding: 2px 0 15px 0; } -/* - * Sidebar - */ + #hc-modal-content { + height: 80vh; + margin: auto; + width: 80%; + z-index: 4; + background-color: white; + } + + footer#rh { + background-color: #000; + padding: 0px 0; + z-index: 5; + } + + .close-btn-sm { + display: none; + } + + /*side toc styling here */ + + #toc:before { + font-family: "RedHatText",Overpass,"Open Sans",Helvetica,Arial,sans-serif; + content: "TABLE OF CONTENTS"; + color: #545454; + font-size: 0.82em; + text-decoration: none; + text-align: left; + padding-bottom: 0.6em; + padding-top: 0.6em; + padding-left: 0.8em; + text-rendering: optimizeLegibility; + -webkit-font-smoothing: antialiased; + } + + #toc { + user-select: none; + float: right; + padding-top: 0.1em !important; + font-size: 0.8em; + overflow-wrap: break-word; + width: 300px; + position: fixed; + display: flex; + flex-flow: column; + top: 165px; + bottom: 1px; + margin-left: 780px; + height: auto; + max-height: 800px; + overflow-y: auto; + z-index: 2; + vertical-align: top; + border-left: solid; + border-width: 1px; + border-color: #E7E7E7; + -webkit-animation: fadein 0.35s ease-in; + -moz-animation: fadein 0.35s ease-in; + -ms-animation: fadein 0.35s ease-in; + -o-animation: fadein 0.35s ease-in; + animation: fadein 0.35s ease-in; + } + + #toc>ul { + margin-left: -2em !important; + list-style: outside none none !important; + height: inherit; + } + + #toc ul.sectlevel0>li>a { + list-style: outside none none !important; + } + + #toc ul.sectlevel2 { + margin-left: -20px; + } + + #toc ul.sectlevel0 ul.sectlevel1 { + margin-top: 0.2em; + list-style: outside none none !important; + } + + #toc ul { + font-family: "Open Sans", "DejaVu Sans", "Sans", sans-serif; + list-style-type: none; + margin-bottom: 0.2em !important; + } + + #toc li { + margin-bottom: 0.4em !important; + } + + #toc a:link { + text-decoration: none; + font-size: inherit; + } + + #toc a:hover { + text-decoration: underline; + } + + #toc a:active { + font-weight: bold; + } + + .toc-active { + font-weight: bold; + } + + #toctitle { + color: #7a2518; + } +} + +/*Sidebar*/ .nav-header { font-size: 18px; @@ -392,458 +681,479 @@ h6 > a.anchor:hover { padding-left: 50px; } -.nav-sidebar > li > a { +.nav-sidebar>li>a { padding: 7px 0; } -.nav-sidebar > li > a:focus, .nav-sidebar > li > a:hover { +.nav-sidebar>li>a:focus, .nav-sidebar>li>a:hover { background: transparent; } .sidebar { font-weight: 300; - display: none; padding-top: 13px; overflow-wrap: break-word; } -@media screen and (max-width: 767px) { - .sidebar { - padding-left: 30px; - padding-right: 0; +/*tablet browsers*/ + +@media (max-width: 1424px) { + html { + scroll-padding-top: 155px; + /* height of fixed header */ + } + + body { + margin: 0px; + margin-bottom: 40px; + } + + .main { + margin-top: 130px; + border-left: 0px solid #e7e7e7; + margin-left: 250px; + width: 54%; } -} -@media screen and (min-width: 768px) { .sidebar { - border-right: 1px solid #e7e7e7; + font-weight: 300; + overflow-wrap: break-word; + position: fixed; + overflow-y: scroll; + z-index: 2; + width: 263px; + background-color: #fff; + margin-left: 5px; + display: flex; + flex-flow: column; + top: 190px; + bottom: 10px; display: block; + -webkit-animation: fadein 0.35s ease-in; /* Safari, Chrome and Opera > 12.1 */ + -moz-animation: fadein 0.35s ease-in; /* Firefox < 16 */ + -ms-animation: fadein 0.35s ease-in; /* Internet Explorer */ + -o-animation: fadein 0.35s ease-in; /* Opera < 12.1 */ + animation: fadein 0.35s ease-in; } -} -/* - * Off Canvas - * -------------------------------------------------- - */ + #hc-search { + position: fixed; + top: 160px; + width: 305px; + } -body > .container { - overflow-x: hidden; -} + #hc-search-btn { + border: 1px solid lightgrey; + font-size: 12px; + height: 25px; + width: 30px; + padding: 1px; + } -.toggle-nav { - margin-right: 20px; -} + #hc-search-input { + border: 1px solid lightgrey; + font-size: 12px; + height: 25px; + } -@media screen and (max-width: 767px) { - .row-offcanvas { - position: relative; - -webkit-transition: all .25s ease-out; - -o-transition: all .25s ease-out; - transition: all .25s ease-out; + .breadcrumb { + margin: 0; + padding: 18px 0 10px; + font-size: 0.92em; + min-height: 65px; + position: fixed; + z-index: 2; + background-color: #fff; + width: 97%; + margin-top: 60px; + margin-left: 5px; } - .row-offcanvas-right { - right: 0; + .container { + width: 100%; + position: relative; } - .row-offcanvas-left { + nav#main { + height: 90px; + position: fixed; + top: 0; left: 0; + z-index: 5; + width: 100%; } - .row-offcanvas-right - .sidebar-offcanvas { - right: -75%; /* 8 columns */ +.page-header h1 { + font-size: 30px; + font-weight: 400; + letter-spacing: inherit; + color: inherit; + margin: 10px 0 0 0; + padding: 2px 0 15px 0; +} + + #hc-modal-content { + height: 80vh; + margin: auto; + width: 80%; + z-index: 4; + background-color: white; } - .row-offcanvas-left - .sidebar-offcanvas { - left: -75%; /* 8 columns */ + footer#rh { + background-color: #000; + padding: 0px 0; + z-index: 5; } - .row-offcanvas-right.active { - right: 75%; /* 8 columns */ + .close-btn-sm { + display: none; } - .row-offcanvas-left.active { - left: 75%; /* 8 columns */ + /*side toc styling here */ + + #toc:before { + font-family: "RedHatText",Overpass,"Open Sans",Helvetica,Arial,sans-serif; + content: "TABLE OF CONTENTS"; + color: #545454; + font-size: 0.82em; + text-decoration: none; + text-align: left; + padding-bottom: 0.6em; + padding-top: 0.6em; + padding-left: 0.8em; + text-rendering: optimizeLegibility; + -webkit-font-smoothing: antialiased; } - .sidebar-offcanvas { - overflow: hidden; - position: absolute; - top: 0; - width: 75%; /* 8 columns */ + #toc { + float: right; + padding-top: 0.1em !important; + font-size: 0.8em; + overflow-wrap: break-word; + width: 20%; + position: fixed; + display: flex; + flex-flow: column; + top: 165px; + bottom: 1px; + margin-left: 52%; + height: auto; + max-height: 800px; + overflow-y: auto; + z-index: 2; + vertical-align: top; + border-left: solid; + border-width: 1px; + border-color: #E7E7E7; + -webkit-animation: fadein 0.35s ease-in; + -moz-animation: fadein 0.35s ease-in; + -ms-animation: fadein 0.35s ease-in; + -o-animation: fadein 0.35s ease-in; + animation: fadein 0.35s ease-in; } -} - p { - margin: 0 0 0.92em; - font-size: 0.92em; - } + #toc>ul { + margin-left: -2em !important; + list-style: outside none none !important; + height: inherit; + } - /* for code lines inside tables*/ - table > tbody > tr > td> p > code { - white-space: pre-wrap; - word-wrap: break-word; - } + #toc ul.sectlevel0>li>a { + list-style: outside none none !important; + } - /* for codeblocks inside tables*/ -table > tbody > tr > td > div > div > div > pre { - white-space: pre-wrap; -} + #toc ul.sectlevel2 { + margin-left: -20px; + } - /* for column code lines inside tables*/ -table > tbody > tr > td > div > div > p > code { - white-space: pre-wrap; - word-wrap: break-word; -} + #toc ul.sectlevel0 ul.sectlevel1 { + margin-top: 0.2em; + list-style: outside none none !important; + } - /* Remnants of Asciidoctor default stylesheet - remove styles as needed */ + #toc ul { + font-family: "Open Sans", "DejaVu Sans", "Sans", sans-serif; + list-style-type: none; + margin-bottom: 0.2em !important; + } -#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { - max-width: none !important; -} - .left { - float: left !important; -} - .right { - float: right !important; -} - .text-left { - text-align: left !important; -} - .text-right { - text-align: right !important; -} - .text-center { - text-align: center !important; -} - .text-justify { - text-align: justify !important; -} - .hide { - display: none; -} - .subheader, #content #toctitle, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { - line-height: 1.4; - color: #7a2518; - font-weight: 300; - margin-top: 0.2em; - margin-bottom: 0.5em; -} - abbr, acronym { - text-transform: uppercase; - font-size: 90%; - color: #333333; - border-bottom: 1px dotted #dddddd; - cursor: help; -} - abbr { - text-transform: none; -} - blockquote { - margin: 0 0 1.25em; - padding: 0.5625em 1.25em 0 1.1875em; - border-left: 3px solid #487c58; -} - blockquote cite { - display: block; - font-size: inherit; - color: #454545; -} - blockquote cite:before { - content: "\2014 \0020"; -} - blockquote cite a, blockquote cite a:visited { - color: #454545; -} - blockquote, blockquote p { - line-height: 1.6; - color: #6e6e6e; -} - @media only screen and (min-width: 768px) { - #toctitle, .sidebarblock > .content > .title { - line-height: 1.4; - } - #toctitle, .sidebarblock > .content > .title { - font-size: 1.6875em; - } -} - table { - background: white; - margin-bottom: 1.25em; - border: solid 1px #dddddd; - font-size: 15px; + #toc li { + margin-bottom: 0.3em !important; + } + + #toc a:link { + text-decoration: none; + font-size: inherit; + } + + #toc a:hover { + text-decoration: underline; + } + + #toc a:active { + font-weight: bold; + } + + .toc-active { + font-weight: bold; + } + + #toctitle { + color: #7a2518; + } } - table thead, table tfoot { - background: whitesmoke; - font-weight: bold; + +/*Sidebar*/ + +.nav-header { + font-size: 18px; } - table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { - padding: 0.5em 0.625em 0.625em; - font-size: inherit; - color: #333333; - text-align: left; + +.nav-header ul { + font-size: 14px; } - table tr th, table tr td { - padding: 0.5625em 0.625em; - font-size: 14px; - color: #545454; - font-weight: 400; + +.nav-header ul li a { + display: block; + padding: 5px 20px 5px 25px; + font-size: 16px; + font-weight: normal; + line-height: 1.3; } - table tr.even, table tr.alt, table tr:nth-of-type(even) { - background: #f9f9f9; + +.nav-sidebar .fa { + text-align: center; + top: -1px; + width: 14px; } - table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { - display: table-cell; - line-height: 1.8; + +.nav-sidebar li a { + line-height: 1.3; + color: inherit; + font-size: 0.92em; } - .clearfix:before, .clearfix:after, .float-group:before, .float-group:after { - content: " "; - display: table; + +.nav-sidebar li a:hover { + color: #000; } - .clearfix:after, .float-group:after { - clear: both; + +.nav-sidebar ul li ul.nav-tertiary li a { + padding-left: 50px; } - *:not(pre) > code { - white-space: nowrap; - background-color: #f9f9f9; - border: 0 solid #dddddd; - -webkit-border-radius: 0px; - border-radius: 0px; - text-shadow: none; - line-height: 1; - font-weight: 400; /* normal */ - vertical-align: baseline; - padding: 2px 4px; -} - pre code { - text-shadow: none; -} - .keyseq { - color: #666666; -} - kbd:not(.keyseq) { - display: inline-block; - color: #333333; - font-size: 0.75em; - line-height: 1.4; - background-color: #f7f7f7; - border: 1px solid #ccc; - -webkit-border-radius: 3px; - border-radius: 3px; - -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; - box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; - margin: -0.15em 0.15em 0 0.15em; - padding: 0.2em 0.6em 0.2em 0.5em; - vertical-align: middle; - white-space: nowrap; + +.nav-sidebar>li>a { + padding: 7px 0; } - .keyseq kbd:first-child { - margin-left: 0; + +.nav-sidebar>li>a:focus, .nav-sidebar>li>a:hover { + background: transparent; } - .keyseq kbd:last-child { - margin-right: 0; + +.sidebar { + font-weight: 300; + padding-top: 13px; + overflow-wrap: break-word; } - .menuseq, .menu { - color: #1a1a1a; -} - b.button:before, b.button:after { - position: relative; - top: -1px; - font-weight: normal; -} - b.button:before { - content: "["; - padding: 0 3px 0 2px; -} - b.button:after { - content: "]"; - padding: 0 2px 0 3px; -} - p a > code:hover { - color: #561309; -} - #header, #content, #footnotes, #footer { - width: 100%; - margin-left: auto; - margin-right: auto; - margin-top: 0; - margin-bottom: 0; - max-width: 62.5em; - *zoom: 1; - position: relative; - padding-left: 0.9375em; - padding-right: 0.9375em; -} - #header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { - content: " "; - display: table; -} - #header:after, #content:after, #footnotes:after, #footer:after { - clear: both; -} - #content:before { - content: none; -} - #header { - margin-bottom: 2.5em; -} - #header > h1 { - color: black; - font-weight: 300; - border-bottom: 1px solid #d8d8d8; - margin-bottom: -28px; - padding-bottom: 32px; -} - #header span { - color: #6e6e6e; -} - #header #revnumber { - text-transform: capitalize; -} - #header br { - display: none; -} - #header br + span { - padding-left: 3px; -} - #header br + span:before { - content: "\2013 \0020"; -} - #header br + span.author { - padding-left: 0; -} - #header br + span.author:before { - content: ", "; -} - #toc { - border-bottom: 3px double #e5e5e5; - padding-top: 1em; - margin-bottom: 1.05em; -} - #toc > ul { - margin-left: 0.25em; + +/*mobile browsers*/ +@media screen and (max-width: 1007px) { + + .main{ + width: 100%; + margin-top: 165px; + margin-left: unset; + } + + nav#main { + height: 90px; + position: absolute; + top: 0; + left: 0; + z-index: 5; + width: 100%; + } + + .nav { + padding-top: 15px; + } + + #toc:before { + display: none; + } + + #toc { + float: unset; + padding-top: unset; + font-size: unset; + overflow-wrap: break-word; + width: unset; + position: unset; + display: unset; + flex-flow: unset; + top: 165px; + bottom: 1px; + margin-left: unset; + height: auto; + max-height: unset; + overflow-y: auto; + z-index: 2; + vertical-align: top; + border-left: unset; + border-width: 1px; + border-color: #E7E7E7; + -webkit-animation: fadein 0.35s ease-in; + -moz-animation: fadein 0.35s ease-in; + -ms-animation: fadein 0.35s ease-in; + -o-animation: fadein 0.35s ease-in; + animation: fadein 0.35s ease-in; + } + + #toc>ul { + font-size: 0.92em; + margin-left: unset !important; + } + + .toc-active { + font-weight: unset; + } + + .breadcrumb { + margin: 0; + padding: 3px 0 20px; + font-size: 0.92em; + top: 100px; + position: absolute; + width: 96%; + } + + .sidebar { + font-weight: 300; + overflow-wrap: break-word; + position: fixed; + overflow-y: scroll; + padding-top: 10px; + height: 100%; + border-right: 1px solid #e7e7e7; + display: block; + z-index: 9999; + width: 300px; + background-color: #fff; + filter: drop-shadow(0 0 0.15rem grey); + transition: all .3s ease; + display: none; + top: unset; + left: -5px; + } + + .breadcrumb { + margin: 0; + padding: 3px 0 20px; + font-size: 0.92em; + } + + .open-btn-sm { + margin-top: 30px; + font-size: 20px; + opacity: 90%; + position: fixed; + z-index: 9999; + filter: drop-shadow(0 0 0.1rem grey); + } + + .close-btn-sm { + border: 1px solid lightgrey; + font-size: 14px; + height: 25px; + width: 26px; + padding: 2px; + margin-bottom: 3px; + } + + .btn-close { + padding: 2px; + } + + .close-btn-sm { + display: unset; + } + + #hc-search { + top: 40px; + position: unset; + } + } - #toc ul.sectlevel0 > li > a { - font-style: italic; + +/* + * Off Canvas + * -------------------------------------------------- + */ + +body>.container { + overflow-x: hidden; } - #toc ul.sectlevel0 ul.sectlevel1 { - margin-left: 0; - margin-top: 0.5em; - margin-bottom: 0.5em; + +.toggle-nav { + margin-right: 20px; } - #toc ul { - font-family: "Open Sans", "DejaVu Sans", "Sans", sans-serif; - list-style-type: none; + +p { + margin: 0 0 0.92em; + font-size: 0.92em; } - #toc a { - text-decoration: none; - font-size: 0.92em; + +/* for code lines inside tables*/ +table>tbody>tr>td>p>code { + white-space: pre-wrap; + word-wrap: break-word; } - #toc a:active { - text-decoration: underline; + +/* for codeblocks inside tables*/ +table>tbody>tr>td>div>div>div>pre { + white-space: pre-wrap; } - #toctitle { - color: #7a2518; + +/* for column code lines inside tables*/ +table>tbody>tr>td>div>div>p>code { + white-space: pre-wrap; + word-wrap: break-word; } - @media only screen and (min-width: 768px) { - body.toc2 { - padding-left: 15em; - padding-right: 0; - } - #toc.toc2 { - background-color: #fafaf9; - position: fixed; - width: 15em; - left: 0; - top: 0; - border-right: 1px solid #e5e5e5; - border-bottom: 0; - z-index: 1000; - padding: 1.25em 1em; - height: 100%; - overflow: auto; - } - #toc.toc2 #toctitle { - margin-top: 0; - font-size: 1.2em; - } - #toc.toc2 > ul { - font-size: .90em; - margin-bottom: 0; - } - #toc.toc2 ul ul { - margin-left: 0; - padding-left: 1em; - } - #toc.toc2 ul.sectlevel0 ul.sectlevel1 { - padding-left: 0; - margin-top: 0.5em; - margin-bottom: 0.5em; - } - body.toc2.toc-right { - padding-left: 0; - padding-right: 15em; - } - body.toc2.toc-right #toc.toc2 { - border-right: 0; - border-left: 1px solid #e5e5e5; - left: auto; - right: 0; - } + +/* Remnants of Asciidoctor default stylesheet - remove styles as needed */ + +#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { + max-width: none !important; } - @media only screen and (min-width: 1280px) { - body.toc2 { - padding-left: 20em; - padding-right: 0; - } - #toc.toc2 { - width: 20em; - } - #toc.toc2 #toctitle { - font-size: 1.375em; - } - #toc.toc2 > ul { - font-size: 0.95em; - } - #toc.toc2 ul ul { - padding-left: 1.25em; - } - body.toc2.toc-right { - padding-left: 0; - padding-right: 20em; - } + +.left { + float: left !important; } - #content #toc { - border-style: solid; - border-width: 1px; - border-color: #e3e3dd; - margin-bottom: 1.25em; - padding: 1.25em; - background: #fafaf9; - border-width: 0; - -webkit-border-radius: 4px; - border-radius: 4px; + +.right { + float: right !important; } - #content #toc > :first-child { - margin-top: 0; + +.text-left { + text-align: left !important; } - #content #toc > :last-child { - margin-bottom: 0; + +.text-right { + text-align: right !important; } - #content #toctitle { - font-size: 1.375em; + +.text-center { + text-align: center !important; } - #footer { - max-width: 100%; - background-color: #333333; - padding: 1.25em; + +.text-justify { + text-align: justify !important; } - #footer-text { - color: #cccccc; - line-height: 1.44; + +.hide { + display: none; } + /* code blocks */ .audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .verseblock, .videoblock { margin-bottom: 1em; @@ -868,6 +1178,7 @@ table > tbody > tr > td > div > div > p > code { border: 0; background: none; width: 100%; + table-layout: fixed; } .admonitionblock.note { background: #4e9fde15; @@ -913,120 +1224,617 @@ table > tbody > tr > td > div > div > p > code { color: #404040; font-weight: bold; } - .admonitionblock.important td.content:before { - content: "IMPORTANT\a"; - white-space: pre; - color: #404040; - font-weight: bold; + +.subheader, #content #toctitle, .admonitionblock td.content>.title, .audioblock>.title, .exampleblock>.title, .imageblock>.title, .listingblock>.title, .literalblock>.title, .stemblock>.title, .openblock>.title, .paragraph>.title, .quoteblock>.title, table.tableblock>.title, .verseblock>.title, .videoblock>.title, .dlist>.title, .olist>.title, .ulist>.title, .qlist>.title, .hdlist>.title { + line-height: 1.4; + color: #7a2518; + font-weight: 300; + margin-top: 0.2em; + margin-bottom: 0.5em; } - .admonitionblock.warning td.content:before { - content: "WARNING\a"; - white-space: pre; - color: #404040; - font-weight: bold; + +abbr, acronym { + text-transform: uppercase; + font-size: 90%; + color: #333333; + border-bottom: 1px dotted #dddddd; + cursor: help; } - .admonitionblock.tip td.content:before { - content: "TIP\a"; - white-space: pre; - color: #404040; - font-weight: bold; + +abbr { + text-transform: none; } - .admonitionblock.caution td.content:before { - content: "CAUTION\a"; - white-space: pre; - color: #404040; - font-weight: bold; + +blockquote { + margin: 0 0 1.25em; + padding: 0.5625em 1.25em 0 1.1875em; + border-left: 3px solid #487c58; } - .admonitionblock > table td.content > :last-child > :last-child { - margin-bottom: 0; + +blockquote cite { + display: block; + font-size: inherit; + color: #454545; } - .exampleblock > .content { - border-style: solid; - border-width: 1px; - border-color: #e6e6e6; - margin-bottom: 1.25em; - padding: 1.25em; - background: white; - -webkit-border-radius: 4px; - border-radius: 4px; + +blockquote cite:before { + content: "\2014 \0020"; } - .exampleblock > .content > :first-child { - margin-top: 0; + +blockquote cite a, blockquote cite a:visited { + color: #454545; } - .exampleblock > .content > :last-child { - margin-bottom: 0; + +blockquote, blockquote p { + line-height: 1.6; + color: #6e6e6e; } - .exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6, .exampleblock > .content p { - color: #333333; + +@media only screen and (min-width: 768px) { + + #toctitle, .sidebarblock>.content>.title { + line-height: 1.4; + } + + #toctitle, .sidebarblock>.content>.title { + font-size: 1.6875em; + } } - .exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6 { - line-height: 1; - margin-bottom: 0.625em; + +table { + background: white; + margin-bottom: 1.25em; + border: solid 1px #dddddd; + font-size: 15px; } - .exampleblock > .content h1.subheader, .exampleblock > .content h2.subheader, .exampleblock > .content h3.subheader, .exampleblock > .content .subheader#toctitle, .sidebarblock.exampleblock > .content > .subheader.title, .exampleblock > .content h4.subheader, .exampleblock > .content h5.subheader, .exampleblock > .content h6.subheader { - line-height: 1.4; + +table thead, table tfoot { + background: whitesmoke; + font-weight: bold; } - .exampleblock.result > .content { - -webkit-box-shadow: 0 1px 8px #e3e3dd; - box-shadow: 0 1px 8px #e3e3dd; + +table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { + padding: 0.5em 0.625em 0.625em; + font-size: inherit; + color: #333333; + text-align: left; } - .sidebarblock { - border-style: solid; - border-width: 1px; - border-color: #e3e3dd; - margin-top: -1.0em; - margin-bottom: 1.6em; - padding: .5em; - background: #F1F3F5; - -webkit-border-radius: 4px; - border-radius: 4px; - overflow-x: auto; + +table tr th, table tr td { + padding: 0.5625em 0.625em; + font-size: 14px; + color: #545454; + font-weight: 400; } - .sidebarblock > :first-child { - margin-top: 0; + +table tr.even, table tr.alt, table tr:nth-of-type(even) { + background: #f9f9f9; } - .sidebarblock > :last-child { - margin-bottom: 0; + +table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { + display: table-cell; + line-height: 1.8; +} + +.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { + content: " "; + display: table; +} + +.clearfix:after, .float-group:after { + clear: both; +} + +*:not(pre)>code { + background-color: #f9f9f9; + border: 0 solid #dddddd; + -webkit-border-radius: 0px; + border-radius: 0px; + text-shadow: none; + line-height: 1; + font-weight: 400; + /* normal */ + vertical-align: baseline; + padding: 2px 4px; + word-wrap: break-word; +} + +pre code { + text-shadow: none; +} + +.keyseq { + color: #666666; +} + +kbd:not(.keyseq) { + display: inline-block; + color: #333333; + font-size: 0.75em; + line-height: 1.4; + background-color: #f7f7f7; + border: 1px solid #ccc; + -webkit-border-radius: 3px; + border-radius: 3px; + -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; + box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; + margin: -0.15em 0.15em 0 0.15em; + padding: 0.2em 0.6em 0.2em 0.5em; + vertical-align: middle; + white-space: nowrap; +} + +.keyseq kbd:first-child { + margin-left: 0; +} + +.keyseq kbd:last-child { + margin-right: 0; +} + +.menuseq, .menu { + color: #1a1a1a; +} + +b.button:before, b.button:after { + position: relative; + top: -1px; + font-weight: normal; } - .sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6, .sidebarblock p { - color: #333333; + +b.button:before { + content: "["; + padding: 0 3px 0 2px; } - .sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6 { - line-height: 1; - margin-bottom: 0.625em; + +b.button:after { + content: "]"; + padding: 0 2px 0 3px; } - .sidebarblock h1.subheader, .sidebarblock h2.subheader, .sidebarblock h3.subheader, .sidebarblock .subheader#toctitle, .sidebarblock > .content > .subheader.title, .sidebarblock h4.subheader, .sidebarblock h5.subheader, .sidebarblock h6.subheader { - line-height: 1.4; + +p a>code:hover { + color: #561309; } - .sidebarblock > .content > .title { - color: #7a2518; - margin-top: 0; - line-height: 1.6; + +#header, #content, #footnotes, #footer { + width: 100%; + margin-left: auto; + margin-right: auto; + margin-top: 0; + margin-bottom: 0; + max-width: 62.5em; + *zoom: 1; + position: relative; + padding-left: 0.9375em; + padding-right: 0.9375em; } - .exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { - margin-bottom: 0; + +#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { + content: " "; + display: table; +} + +#header:after, #content:after, #footnotes:after, #footer:after { + clear: both; +} + +#content:before { + content: none; +} + +#header { + margin-bottom: 2.5em; +} + +#header>h1 { + color: black; + font-weight: 300; + border-bottom: 1px solid #d8d8d8; + margin-bottom: -28px; + padding-bottom: 32px; +} + +#header span { + color: #6e6e6e; } + +#header #revnumber { + text-transform: capitalize; +} + +#header br { + display: none; +} + +#header br+span { + padding-left: 3px; +} + +#header br+span:before { + content: "\2013 \0020"; +} + +#header br+span.author { + padding-left: 0; +} + +#header br+span.author:before { + content: ", "; +} + +#toc { + padding-top: 1em; + margin-bottom: 1.05em; +} + +#toc>ul { + margin-left: 0.25em; +} + +#toc ul.sectlevel0 ul.sectlevel1 { + margin-left: 0; + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +#toc ul { + font-family: "Open Sans", "DejaVu Sans", "Sans", sans-serif; + list-style-type: none; +} + +#toc a { + text-decoration: none; + font-size: 0.92em; +} + +#toc a:active { + text-decoration: underline; +} + +#toctitle { + color: #7a2518; +} + +@media only screen and (min-width: 768px) { + body.toc2 { + padding-left: 15em; + padding-right: 0; + } + + #toc.toc2 { + background-color: #fafaf9; + position: fixed; + width: 15em; + left: 0; + top: 0; + border-right: 1px solid #e5e5e5; + border-bottom: 0; + z-index: 1000; + padding: 1.25em 1em; + height: 100%; + overflow: auto; + } + + #toc.toc2 #toctitle { + margin-top: 0; + font-size: 1.2em; + } + + #toc.toc2>ul { + font-size: .90em; + margin-bottom: 0; + } + + #toc.toc2 ul ul { + margin-left: 0; + padding-left: 1em; + } + + #toc.toc2 ul.sectlevel0 ul.sectlevel1 { + padding-left: 0; + margin-top: 0.5em; + margin-bottom: 0.5em; + } + + body.toc2.toc-right { + padding-left: 0; + padding-right: 15em; + } + + body.toc2.toc-right #toc.toc2 { + border-right: 0; + border-left: 1px solid #e5e5e5; + left: auto; + right: 0; + } +} + +@media only screen and (min-width: 1280px) { + body.toc2 { + padding-left: 20em; + padding-right: 0; + } + + #toc.toc2 { + width: 20em; + } + + #toc.toc2 #toctitle { + font-size: 1.375em; + } + + #toc.toc2>ul { + font-size: 0.95em; + } + + #toc.toc2 ul ul { + padding-left: 1.25em; + } + + body.toc2.toc-right { + padding-left: 0; + padding-right: 20em; + } +} + +#content #toc { + border-style: solid; + border-width: 1px; + border-color: #e3e3dd; + margin-bottom: 1.25em; + padding: 1.25em; + background: #fafaf9; + border-width: 0; + -webkit-border-radius: 4px; + border-radius: 4px; +} + +#content #toc> :first-child { + margin-top: 0; +} + +#content #toc> :last-child { + margin-bottom: 0; +} + +#content #toctitle { + font-size: 1.375em; +} + +#footer { + max-width: 100%; + background-color: #333333; + padding: 1.25em; +} + +#footer-text { + color: #cccccc; + line-height: 1.44; +} + +/* code blocks */ +.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .verseblock, .videoblock { + margin-bottom: 1em; +} + +.admonitionblock td.content>.title, .audioblock>.title, .exampleblock>.title, .imageblock>.title, .listingblock>.title, .literalblock>.title, .stemblock>.title, .openblock>.title, .paragraph>.title, .quoteblock>.title, table.tableblock>.title, .verseblock>.title, .videoblock>.title, .dlist>.title, .olist>.title, .ulist>.title, .qlist>.title, .hdlist>.title { + text-rendering: optimizeLegibility; + text-align: left; + font-family: "Noto Serif", "DejaVu Serif", "Serif", serif; + font-weight: normal; + font-style: italic; + font-size: 16px; +} + +table.tableblock>caption.title { + white-space: nowrap; + overflow: visible; + max-width: 0; +} + +table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p { + font-size: inherit; +} + +.admonitionblock>table { + border: 0; + background: none; + width: 100%; + table-layout: fixed; +} + +.admonitionblock.note { + background: #4e9fde15; + border-left: solid #4e9fde; +} + +.admonitionblock.important { + background: #ee210015; + border-left: solid #ee2100; +} + +.admonitionblock.warning { + background: #ec7a0915; + border-left: solid #ec7a09; +} + +.admonitionblock.caution { + background: #ec7a0915; + border-left: solid #ec7a09; +} + +.admonitionblock.tip { + background: #32859615; + border-left: solid #328596; +} + +.admonitionblock>table td.icon { + vertical-align: top; + text-align: center; + width: 80px; +} + +.admonitionblock>table td.icon img { + max-width: none; +} + +.admonitionblock>table td.icon .title { + font-weight: 300; + text-transform: uppercase; +} + +.admonitionblock>table td.content { + padding-left: 0; + padding-right: 1.25em; + color: #6e6e6e; + font-size: .85rem; +} + +.admonitionblock.note td.content:before { + content: "NOTE\a"; + white-space: pre; + color: #404040; + font-weight: bold; +} + +.admonitionblock.important td.content:before { + content: "IMPORTANT\a"; + white-space: pre; + color: #404040; + font-weight: bold; +} + +.admonitionblock.warning td.content:before { + content: "WARNING\a"; + white-space: pre; + color: #404040; + font-weight: bold; +} + +.admonitionblock.tip td.content:before { + content: "TIP\a"; + white-space: pre; + color: #404040; + font-weight: bold; +} + +.admonitionblock.caution td.content:before { + content: "CAUTION\a"; + white-space: pre; + color: #404040; + font-weight: bold; +} + +.admonitionblock>table td.content> :last-child> :last-child { + margin-bottom: 0; +} + +.exampleblock>.content { + border-style: solid; + border-width: 1px; + border-color: #e6e6e6; + margin-bottom: 1.25em; + padding: 1.25em; + background: white; + -webkit-border-radius: 4px; + border-radius: 4px; +} + +.exampleblock>.content> :first-child { + margin-top: 0; +} + +.exampleblock>.content> :last-child { + margin-bottom: 0; +} + +.exampleblock>.content h1, .exampleblock>.content h2, .exampleblock>.content h3, .exampleblock>.content #toctitle, .sidebarblock.exampleblock>.content>.title, .exampleblock>.content h4, .exampleblock>.content h5, .exampleblock>.content h6, .exampleblock>.content p { + color: #333333; +} + +.exampleblock>.content h1, .exampleblock>.content h2, .exampleblock>.content h3, .exampleblock>.content #toctitle, .sidebarblock.exampleblock>.content>.title, .exampleblock>.content h4, .exampleblock>.content h5, .exampleblock>.content h6 { + line-height: 1; + margin-bottom: 0.625em; +} + +.exampleblock>.content h1.subheader, .exampleblock>.content h2.subheader, .exampleblock>.content h3.subheader, .exampleblock>.content .subheader#toctitle, .sidebarblock.exampleblock>.content>.subheader.title, .exampleblock>.content h4.subheader, .exampleblock>.content h5.subheader, .exampleblock>.content h6.subheader { + line-height: 1.4; +} + +.exampleblock.result>.content { + -webkit-box-shadow: 0 1px 8px #e3e3dd; + box-shadow: 0 1px 8px #e3e3dd; +} + +.sidebarblock { + border-style: solid; + border-width: 1px; + border-color: #e3e3dd; + margin-top: -1.0em; + margin-bottom: 1.6em; + padding: .5em; + background: #F1F3F5; + -webkit-border-radius: 4px; + border-radius: 4px; + overflow-x: auto; +} + +.sidebarblock> :first-child { + margin-top: 0; +} + +.sidebarblock> :last-child { + margin-bottom: 0; +} + +.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock>.content>.title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6, .sidebarblock p { + color: #333333; +} + +.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock>.content>.title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6 { + line-height: 1; + margin-bottom: 0.625em; +} + +.sidebarblock h1.subheader, .sidebarblock h2.subheader, .sidebarblock h3.subheader, .sidebarblock .subheader#toctitle, .sidebarblock>.content>.subheader.title, .sidebarblock h4.subheader, .sidebarblock h5.subheader, .sidebarblock h6.subheader { + line-height: 1.4; +} + +.sidebarblock>.content>.title { + color: #7a2518; + margin-top: 0; + line-height: 1.6; +} + +.exampleblock>.content> :last-child> :last-child, .exampleblock>.content .olist>ol>li:last-child> :last-child, .exampleblock>.content .ulist>ul>li:last-child> :last-child, .exampleblock>.content .qlist>ol>li:last-child> :last-child, .sidebarblock>.content> :last-child> :last-child, .sidebarblock>.content .olist>ol>li:last-child> :last-child, .sidebarblock>.content .ulist>ul>li:last-child> :last-child, .sidebarblock>.content .qlist>ol>li:last-child> :last-child { + margin-bottom: 0; +} + /* For this only we do not want padding */ .listingblock pre.rouge, .listingblock pre.rouge code { padding: 0; } + /* source code appears in pre blocks */ - .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { - background-color: #f9f9f9; - border: 1px #aab7b8 solid; - padding: 1.75em 2em; - word-wrap: break-word; - color: #404040; - font-family: "Roboto Mono", monospace; -} - .literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { - overflow-x: auto; - white-space: pre; - word-wrap: normal; -} - .literalblock pre > code, .literalblock pre[class] > code, .listingblock pre > code, .listingblock pre[class] > code { - display: block; +.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { + background-color: #f9f9f9; + border: 1px #aab7b8 solid; + padding: 1.75em 2em; + word-wrap: break-word; + color: #404040; + font-family: "Roboto Mono", monospace; +} + +.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { + overflow-x: auto; + white-space: pre; + word-wrap: normal; } + +.literalblock pre>code, .literalblock pre[class]>code, .listingblock pre>code, .listingblock pre[class]>code { + display: block; +} + /* this adds overflow for code blocks */ /* negative padding undoes the parent padding for .iteralblock pre */ .listingblock pre.rouge code { @@ -1035,708 +1843,778 @@ table > tbody > tr > td > div > div > p > code { white-space: pre; overflow-x: auto; } - .listingblock > .content { - position: relative; + +.listingblock>.content { + position: relative; } - .listingblock:hover code[class*=" language-"]:before { - text-transform: uppercase; - font-size: 0.9em; - color: #999; - position: absolute; - top: 0.375em; - right: 0.375em; + +.listingblock:hover code[class*=" language-"]:before { + text-transform: uppercase; + font-size: 0.9em; + color: #999; + position: absolute; + top: 0.375em; + right: 0.375em; } - .listingblock:hover code.asciidoc:before { - content: "asciidoc"; + +.listingblock:hover code.asciidoc:before { + content: "asciidoc"; } - .listingblock:hover code.clojure:before { - content: "clojure"; + +.listingblock:hover code.clojure:before { + content: "clojure"; } - .listingblock:hover code.css:before { - content: "css"; + +.listingblock:hover code.css:before { + content: "css"; } - .listingblock:hover code.go:before { - content: "go"; + +.listingblock:hover code.go:before { + content: "go"; } - .listingblock:hover code.groovy:before { - content: "groovy"; + +.listingblock:hover code.groovy:before { + content: "groovy"; } - .listingblock:hover code.html:before { - content: "html"; + +.listingblock:hover code.html:before { + content: "html"; } - .listingblock:hover code.java:before { - content: "java"; + +.listingblock:hover code.java:before { + content: "java"; } - .listingblock:hover code.javascript:before { - content: "javascript"; + +.listingblock:hover code.javascript:before { + content: "javascript"; } - .listingblock:hover code.python:before { - content: "python"; + +.listingblock:hover code.python:before { + content: "python"; } - .listingblock:hover code.ruby:before { - content: "ruby"; + +.listingblock:hover code.ruby:before { + content: "ruby"; } - .listingblock:hover code.sass:before { - content: "sass"; + +.listingblock:hover code.sass:before { + content: "sass"; } - .listingblock:hover code.scss:before { - content: "scss"; + +.listingblock:hover code.scss:before { + content: "scss"; } - .listingblock:hover code.xml:before { - content: "xml"; + +.listingblock:hover code.xml:before { + content: "xml"; } - .listingblock:hover code.yaml:before { - content: "yaml"; + +.listingblock:hover code.yaml:before { + content: "yaml"; } - .listingblock.terminal pre .command:before { - content: attr(data-prompt); - padding-right: 0.5em; - color: #999; + +.listingblock.terminal pre .command:before { + content: attr(data-prompt); + padding-right: 0.5em; + color: #999; } - .listingblock.terminal pre .command:not([data-prompt]):before { - content: '$'; + +.listingblock.terminal pre .command:not([data-prompt]):before { + content: '$'; } - table.pyhltable { - border: 0; - margin-bottom: 0; + +table.pyhltable { + border: 0; + margin-bottom: 0; } - table.pyhltable td { - vertical-align: top; - padding-top: 0; - padding-bottom: 0; + +table.pyhltable td { + vertical-align: top; + padding-top: 0; + padding-bottom: 0; } - table.pyhltable td.code { - padding-left: .75em; - padding-right: 0; + +table.pyhltable td.code { + padding-left: .75em; + padding-right: 0; } - .highlight.pygments .lineno, table.pyhltable td:not(.code) { - color: #999; - padding-left: 0; - padding-right: .5em; - border-right: 1px solid #d8d8d8; + +.highlight.pygments .lineno, table.pyhltable td:not(.code) { + color: #999; + padding-left: 0; + padding-right: .5em; + border-right: 1px solid #d8d8d8; } - .highlight.pygments .lineno { - display: inline-block; - margin-right: .25em; + +.highlight.pygments .lineno { + display: inline-block; + margin-right: .25em; } - table.pyhltable .linenodiv { - background-color: transparent !important; - padding-right: 0 !important; + +table.pyhltable .linenodiv { + background-color: transparent !important; + padding-right: 0 !important; } - .quoteblock { - margin: 0 0 1.25em 0; - padding: 0.5625em 1.25em 0 1.1875em; - border-left: 3px solid #487c58; + +.quoteblock { + margin: 0 0 1.25em 0; + padding: 0.5625em 1.25em 0 1.1875em; + border-left: 3px solid #487c58; } - .quoteblock blockquote { - margin: 0 0 1.25em 0; - padding: 0 0 0.625em 0; - border: 0; + +.quoteblock blockquote { + margin: 0 0 1.25em 0; + padding: 0 0 0.625em 0; + border: 0; } - .quoteblock blockquote > .paragraph:last-child p { - margin-bottom: 0; + +.quoteblock blockquote>.paragraph:last-child p { + margin-bottom: 0; } - .quoteblock .attribution { - margin-top: -0.625em; - padding-bottom: 0.625em; - font-size: inherit; - color: #454545; - line-height: 1.6; + +.quoteblock .attribution { + margin-top: -0.625em; + padding-bottom: 0.625em; + font-size: inherit; + color: #454545; + line-height: 1.6; } - .quoteblock .attribution br { - display: none; + +.quoteblock .attribution br { + display: none; } - .quoteblock .attribution cite { - display: block; + +.quoteblock .attribution cite { + display: block; } - table.tableblock { - max-width: 100%; + +table.tableblock { + max-width: 100%; } - table.tableblock td .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { - margin-bottom: 0; + +table.tableblock td .paragraph:last-child p>p:last-child, table.tableblock th>p:last-child, table.tableblock td>p:last-child { + margin-bottom: 0; } - table.tableblock, th.tableblock, td.tableblock { - border: 0 solid #dddddd; + +table.tableblock, th.tableblock, td.tableblock { + border: 0 solid #dddddd; } - table.grid-all th.tableblock, table.grid-all td.tableblock { - border-width: 0 1px 1px 0; + +table.grid-all th.tableblock, table.grid-all td.tableblock { + border-width: 0 1px 1px 0; } - table.grid-all tfoot > tr > th.tableblock, table.grid-all tfoot > tr > td.tableblock { - border-width: 1px 1px 0 0; + +table.grid-all tfoot>tr>th.tableblock, table.grid-all tfoot>tr>td.tableblock { + border-width: 1px 1px 0 0; } - table.grid-cols th.tableblock, table.grid-cols td.tableblock { - border-width: 0 1px 0 0; + +table.grid-cols th.tableblock, table.grid-cols td.tableblock { + border-width: 0 1px 0 0; } - table.grid-all * > tr > .tableblock:last-child, table.grid-cols * > tr > .tableblock:last-child { - border-right-width: 0; + +table.grid-all *>tr>.tableblock:last-child, table.grid-cols *>tr>.tableblock:last-child { + border-right-width: 0; } - table.grid-rows th.tableblock, table.grid-rows td.tableblock { - border-width: 0 0 1px 0; + +table.grid-rows th.tableblock, table.grid-rows td.tableblock { + border-width: 0 0 1px 0; } - table.grid-all tbody > tr:last-child > th.tableblock, table.grid-all tbody > tr:last-child > td.tableblock, table.grid-all thead:last-child > tr > th.tableblock, table.grid-rows tbody > tr:last-child > th.tableblock, table.grid-rows tbody > tr:last-child > td.tableblock, table.grid-rows thead:last-child > tr > th.tableblock { - border-bottom-width: 0; + +table.grid-all tbody>tr:last-child>th.tableblock, table.grid-all tbody>tr:last-child>td.tableblock, table.grid-all thead:last-child>tr>th.tableblock, table.grid-rows tbody>tr:last-child>th.tableblock, table.grid-rows tbody>tr:last-child>td.tableblock, table.grid-rows thead:last-child>tr>th.tableblock { + border-bottom-width: 0; } - table.grid-rows tfoot > tr > th.tableblock, table.grid-rows tfoot > tr > td.tableblock { - border-width: 1px 0 0 0; + +table.grid-rows tfoot>tr>th.tableblock, table.grid-rows tfoot>tr>td.tableblock { + border-width: 1px 0 0 0; } - table.frame-all { - border-width: 1px; + +table.frame-all { + border-width: 1px; } - table.frame-sides { - border-width: 0 1px; + +table.frame-sides { + border-width: 0 1px; } - table.frame-topbot { - border-width: 1px 0; + +table.frame-topbot { + border-width: 1px 0; } - table.tableblock th.halign-left, table.tableblock td.halign-left { - text-align: left; + +table.tableblock th.halign-left, table.tableblock td.halign-left { + text-align: left; } - table.tableblock th.halign-right, table.tableblock td.halign-right { - text-align: right; + +table.tableblock th.halign-right, table.tableblock td.halign-right { + text-align: right; } - table.tableblock th.halign-center, table.tableblock td.halign-center { - text-align: center; + +table.tableblock th.halign-center, table.tableblock td.halign-center { + text-align: center; } - table.tableblock th.valign-top, table.tableblock td.valign-top { - vertical-align: top; + +table.tableblock th.valign-top, table.tableblock td.valign-top { + vertical-align: top; } - table.tableblock th.valign-bottom, table.tableblock td.valign-bottom { - vertical-align: bottom; + +table.tableblock th.valign-bottom, table.tableblock td.valign-bottom { + vertical-align: bottom; } - table.tableblock th.valign-middle, table.tableblock td.valign-middle { - vertical-align: middle; + +table.tableblock th.valign-middle, table.tableblock td.valign-middle { + vertical-align: middle; } - table thead th, table tfoot th { - font-weight: bold; + +table thead th, table tfoot th { + font-weight: bold; } - tbody tr th { - display: table-cell; - line-height: 1.6; - background: whitesmoke; + +tbody tr th { + display: table-cell; + line-height: 1.6; + background: whitesmoke; } - tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { - color: #333333; - font-weight: bold; + +tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { + color: #333333; + font-weight: bold; } - td > div.verse { - white-space: pre; + +td>div.verse { + white-space: pre; } - ul.unstyled, ol.unnumbered, ul.checklist, ul.none { - list-style-type: none; + +ul.unstyled, ol.unnumbered, ul.checklist, ul.none { + list-style-type: none; } - ul.unstyled, ol.unnumbered, ul.checklist { - margin-left: 0.625em; + +ul.unstyled, ol.unnumbered, ul.checklist { + margin-left: 0.625em; } - ul.checklist li > p:first-child > .fa-check-square-o:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { - margin-right: 0.25em; + +ul.checklist li>p:first-child>.fa-check-square-o:first-child, ul.checklist li>p:first-child>input[type="checkbox"]:first-child { + margin-right: 0.25em; } - ul.checklist li > p:first-child > input[type="checkbox"]:first-child { - position: relative; - top: 1px; + +ul.checklist li>p:first-child>input[type="checkbox"]:first-child { + position: relative; + top: 1px; } - ul.inline { - margin: 0 auto 0.625em auto; - margin-left: -1.375em; - margin-right: 0; - padding: 0; - list-style: none; - overflow: hidden; + +ul.inline { + margin: 0 auto 0.625em auto; + margin-left: -1.375em; + margin-right: 0; + padding: 0; + list-style: none; + overflow: hidden; } - ul.inline > li { - list-style: none; - float: left; - margin-left: 1.375em; - display: block; + +ul.inline>li { + list-style: none; + float: left; + margin-left: 1.375em; + display: block; } - ul.inline > li > * { - display: block; + +ul.inline>li>* { + display: block; } - .unstyled dl dt { - font-weight: normal; - font-style: normal; + +.unstyled dl dt { + font-weight: normal; + font-style: normal; } - ol.arabic { - list-style-type: decimal; + +ol.arabic { + list-style-type: decimal; } - ol.decimal { - list-style-type: decimal-leading-zero; + +ol.decimal { + list-style-type: decimal-leading-zero; } - ol.loweralpha { - list-style-type: lower-alpha; + +ol.loweralpha { + list-style-type: lower-alpha; } - ol.upperalpha { - list-style-type: upper-alpha; + +ol.upperalpha { + list-style-type: upper-alpha; } - ol.lowerroman { - list-style-type: lower-roman; + +ol.lowerroman { + list-style-type: lower-roman; } - ol.upperroman { - list-style-type: upper-roman; + +ol.upperroman { + list-style-type: upper-roman; } - ol.lowergreek { - list-style-type: lower-greek; + +ol.lowergreek { + list-style-type: lower-greek; } - .hdlist > table, .colist > table { - border: 0; - background: none; - margin-bottom: 0; + +.hdlist>table, .colist>table { + border: 0; + background: none; + margin-bottom: 0; + word-break: break-word; } - .hdlist > table > tbody > tr, .colist > table > tbody > tr { - background: none; + +.hdlist>table>tbody>tr, .colist>table>tbody>tr { + background: none; } - td.hdlist1 { - padding-right: .75em; - font-weight: bold; + +td.hdlist1 { + padding-right: .75em; + font-weight: bold; } - td.hdlist1, td.hdlist2 { - vertical-align: top; + +td.hdlist1, td.hdlist2 { + vertical-align: top; } - .literalblock + .colist, .listingblock + .colist { - margin-top: -0.5em; + +.literalblock+.colist, .listingblock+.colist { + margin-top: -0.5em; } - .colist > table tr > td:first-of-type { - padding: 0 .75em; - line-height: 1; - vertical-align: top + +.colist>table tr>td:first-of-type { + padding: 0 .75em; + line-height: 1; + vertical-align: top } - .colist > table tr > td:last-of-type { - padding: 0 0 0.5em 0; + +.colist>table tr>td:last-of-type { + padding: 0 0 0.5em 0; } + /* Fix subsequent paras for same bullet */ .colist .paragraph p { font-size: 14px; line-height: 1.8; margin: 0.5em 0; } + .colist .admonitionblock { margin-top: 0.5em; padding-top: 0.75em; } -.qanda > ol > li > p > em:only-child { - color: #1d4b8f; + +.qanda>ol>li>p>em:only-child { + color: #1d4b8f; } - .thumb, .th { - line-height: 0; - display: inline-block; - border: solid 4px white; - -webkit-box-shadow: 0 0 0 1px #dddddd; - box-shadow: 0 0 0 1px #dddddd; + +.thumb, .th { + line-height: 0; + display: inline-block; + border: solid 4px white; + -webkit-box-shadow: 0 0 0 1px #dddddd; + box-shadow: 0 0 0 1px #dddddd; } - .imageblock.left, .imageblock[style*="float: left"] { - margin: 0.25em 0.625em 1.25em 0; + +.imageblock.left, .imageblock[style*="float: left"] { + margin: 0.25em 0.625em 1.25em 0; } - .imageblock.right, .imageblock[style*="float: right"] { - margin: 0.25em 0 1.25em 0.625em; + +.imageblock.right, .imageblock[style*="float: right"] { + margin: 0.25em 0 1.25em 0.625em; } - .imageblock > .title { - margin-bottom: 0; + +.imageblock>.title { + margin-bottom: 0; } - .imageblock.thumb, .imageblock.th { - border-width: 6px; + +.imageblock.thumb, .imageblock.th { + border-width: 6px; } - .imageblock.thumb > .title, .imageblock.th > .title { - padding: 0 0.125em; + +.imageblock.thumb>.title, .imageblock.th>.title { + padding: 0 0.125em; } - .image.left, .image.right { - margin-top: 0.25em; - margin-bottom: 0.25em; - display: inline-block; - line-height: 0; + +.image.left, .image.right { + margin-top: 0.25em; + margin-bottom: 0.25em; + display: inline-block; + line-height: 0; } - .image.left { - margin-right: 0.625em; + +.image.left { + margin-right: 0.625em; } - .image.right { - margin-left: 0.625em; + +.image.right { + margin-left: 0.625em; } - a.image { - text-decoration: none; + +a.image { + text-decoration: none; } - span.footnote, span.footnoteref { - vertical-align: super; - font-size: 0.875em; + +span.footnote, span.footnoteref { + vertical-align: super; + font-size: 0.875em; } - span.footnote a, span.footnoteref a { - text-decoration: none; + +span.footnote a, span.footnoteref a { + text-decoration: none; } - span.footnote a:active, span.footnoteref a:active { - text-decoration: underline; + +span.footnote a:active, span.footnoteref a:active { + text-decoration: underline; } + .dlist dt { padding-bottom: 0.5em; } + /* This overrides the 0 margin from subdomain.css */ .dlist dd { margin-left: 1.5em; } - #footnotes { - padding-top: 0.75em; - padding-bottom: 0.75em; - margin-bottom: 0.625em; -} - #footnotes hr { - width: 20%; - min-width: 6.25em; - margin: -.25em 0 .75em 0; - border-width: 1px 0 0 0; -} - #footnotes .footnote { - padding: 0 0.375em; - line-height: 1.3; - font-size: 0.875em; - margin-left: 1.2em; - text-indent: -1.2em; - margin-bottom: .2em; -} - #footnotes .footnote a:first-of-type { - font-weight: bold; - text-decoration: none; -} - #footnotes .footnote:last-of-type { - margin-bottom: 0; -} - #content #footnotes { - margin-top: -0.625em; - margin-bottom: 0; - padding: 0.75em 0; -} - .gist .file-data > table { - border: none; - background: #fff; - width: 100%; - margin-bottom: 0; + +#footnotes { + padding-top: 0.75em; + padding-bottom: 0.75em; + margin-bottom: 0.625em; +} + +#footnotes hr { + width: 20%; + min-width: 6.25em; + margin: -.25em 0 .75em 0; + border-width: 1px 0 0 0; } - .gist .file-data > table td.line-data { - width: 99%; + +#footnotes .footnote { + padding: 0 0.375em; + line-height: 1.3; + font-size: 0.875em; + margin-left: 1.2em; + text-indent: -1.2em; + margin-bottom: .2em; } - div.unbreakable { - page-break-inside: avoid; + +#footnotes .footnote a:first-of-type { + font-weight: bold; + text-decoration: none; } - code { - color: #404040; - background-color: #e7e7e7; - font-weight: bold; - font-family: "Roboto Mono", monospace; + +#footnotes .footnote:last-of-type { + margin-bottom: 0; } - h5 { - color: #404040; + +#content #footnotes { + margin-top: -0.625em; + margin-bottom: 0; + padding: 0.75em 0; } - strong { - color: #404040; - font-weight: bold; + +.gist .file-data>table { + border: none; + background: #fff; + width: 100%; + margin-bottom: 0; } - a strong { - color: inherit; + +.gist .file-data>table td.line-data { + width: 99%; } - a code { - color: inherit; + +div.unbreakable { + page-break-inside: avoid; } - .replaceable { - font-style: italic; - font-family: inherit; + +code { + color: #404040; + background-color: #e7e7e7; + font-weight: bold; + font-family: "Roboto Mono", monospace; } - .parameter { - font-style: italic; - font-family: monospace; + +h5 { + color: #404040; +} + +strong { + color: #404040; + font-weight: bold; +} + +a strong { + color: inherit; } - .userinput { - font-weight: bold; - font-family: monospace; + +a code { + color: inherit; +} + +.replaceable { + font-style: italic; + font-family: inherit; } - .envar { - font-weight: bold; - font-family: monospace; - font-size: 90%; + +.parameter { + font-style: italic; + font-family: monospace; } - .sysitem { - font-weight: bold; - font-size: 90%; + +.userinput { + font-weight: bold; + font-family: monospace; } - .package { - font-weight: bold; - font-size: 90%; + +.envar { + font-weight: bold; + font-family: monospace; + font-size: 90%; } - .filename { - font-weight: bold; - font-style: italic; - font-size: 90%; + +.sysitem { + font-weight: bold; + font-size: 90%; +} + +.package { + font-weight: bold; + font-size: 90%; +} + +.filename { + font-weight: bold; + font-style: italic; + font-size: 90%; } - .big { - font-size: larger; + +.big { + font-size: larger; } - .small { - font-size: smaller; + +.small { + font-size: smaller; } - .underline { - text-decoration: underline; + +.underline { + text-decoration: underline; } - .overline { - text-decoration: overline; + +.overline { + text-decoration: overline; } - .line-through { - text-decoration: line-through; + +.line-through { + text-decoration: line-through; } - .aqua { - color: #00bfbf; + +.aqua { + color: #00bfbf; } - .aqua-background { - background-color: #00fafa; + +.aqua-background { + background-color: #00fafa; } - .black { - color: black; + +.black { + color: black; } - .black-background { - background-color: black; + +.black-background { + background-color: black; } - .blue { - color: #0000bf; + +.blue { + color: #0000bf; } - .blue-background { - background-color: #0000fa; + +.blue-background { + background-color: #0000fa; } - .fuchsia { - color: #bf00bf; + +.fuchsia { + color: #bf00bf; } - .fuchsia-background { - background-color: #fa00fa; + +.fuchsia-background { + background-color: #fa00fa; } - .gray { - color: #606060; + +.gray { + color: #606060; } - .gray-background { - background-color: #7d7d7d; + +.gray-background { + background-color: #7d7d7d; } - .green { - color: #006000; + +.green { + color: #006000; } - .green-background { - background-color: #007d00; + +.green-background { + background-color: #007d00; } - .lime { - color: #00bf00; + +.lime { + color: #00bf00; } - .lime-background { - background-color: #00fa00; + +.lime-background { + background-color: #00fa00; } - .maroon { - color: #600000; + +.maroon { + color: #600000; } - .maroon-background { - background-color: #7d0000; + +.maroon-background { + background-color: #7d0000; } - .navy { - color: #000060; + +.navy { + color: #000060; } - .navy-background { - background-color: #00007d; + +.navy-background { + background-color: #00007d; } - .olive { - color: #606000; + +.olive { + color: #606000; } - .olive-background { - background-color: #7d7d00; + +.olive-background { + background-color: #7d7d00; } - .purple { - color: #600060; + +.purple { + color: #600060; } - .purple-background { - background-color: #7d007d; + +.purple-background { + background-color: #7d007d; } - .red { - color: #bf0000; + +.red { + color: #bf0000; } - .red-background { - background-color: #fa0000; + +.red-background { + background-color: #fa0000; } - .silver { - color: #909090; + +.silver { + color: #909090; } - .silver-background { - background-color: #bcbcbc; + +.silver-background { + background-color: #bcbcbc; } - .teal { - color: #006060; + +.teal { + color: #006060; } - .teal-background { - background-color: #007d7d; + +.teal-background { + background-color: #007d7d; } - .white { - color: #bfbfbf; + +.white { + color: #bfbfbf; } - .white-background { - background-color: #fafafa; + +.white-background { + background-color: #fafafa; } - .yellow { - color: #bfbf00; + +.yellow { + color: #bfbf00; } - .yellow-background { - background-color: #fafa00; + +.yellow-background { + background-color: #fafa00; } - span.icon > .fa { - cursor: default; + +span.icon>.fa { + cursor: default; } - .admonitionblock td.icon [class^="fa icon-"] { - font-size: 2.5em; - cursor: default; - padding-top: .125em; + +.admonitionblock td.icon [class^="fa icon-"] { + font-size: 2.5em; + cursor: default; + padding-top: .125em; } - .admonitionblock td.icon .icon-note:before { - content: "\f05a"; - color: #4E9FDD; + +.admonitionblock td.icon .icon-note:before { + content: "\f05a"; + color: #4E9FDD; } - .admonitionblock td.icon .icon-tip:before { - content: "\f0eb"; - color: #2C8596; + +.admonitionblock td.icon .icon-tip:before { + content: "\f0eb"; + color: #2C8596; } - .admonitionblock td.icon .icon-warning:before { - content: "\f071"; - color: #ec7a08; + +.admonitionblock td.icon .icon-warning:before { + content: "\f071"; + color: #ec7a08; } - .admonitionblock td.icon .icon-caution:before { - content: "\f06d"; - color: #ec7a08; + +.admonitionblock td.icon .icon-caution:before { + content: "\f06d"; + color: #ec7a08; } - .admonitionblock td.icon .icon-important:before { - content: "\f06a"; - color: #e00; + +.admonitionblock td.icon .icon-important:before { + content: "\f06a"; + color: #e00; } - .conum[data-value] { - display: inline-block; - color: white !important; - background-color: #394b54; - -webkit-border-radius: 100px; - border-radius: 100px; - text-align: center; - width: 20px; - height: 20px; - font-size: 12px; - line-height: 20px; - font-family: "Open Sans", "Sans", sans-serif; - font-style: normal; - font-weight: bold; - text-indent: -1px; + +.conum[data-value] { + display: inline-block; + color: white !important; + background-color: #394b54; + -webkit-border-radius: 100px; + border-radius: 100px; + text-align: center; + width: 20px; + height: 20px; + font-size: 12px; + line-height: 20px; + font-family: "Open Sans", "Sans", sans-serif; + font-style: normal; + font-weight: bold; + text-indent: -1px; } - .conum[data-value] * { - color: white !important; + +.conum[data-value] * { + color: white !important; } - .conum[data-value] + b { - display: none; + +.conum[data-value]+b { + display: none; } - .conum[data-value]:after { - content: attr(data-value); + +.conum[data-value]:after { + content: attr(data-value); } - pre .conum[data-value] { - text-shadow: 0 0; - position: relative; - top: -2px; + +pre .conum[data-value] { + text-shadow: 0 0; + position: relative; + top: -2px; } - b.conum * { - color: inherit !important; + +b.conum * { + color: inherit !important; } - .conum:not([data-value]):empty { - display: none; + +.conum:not([data-value]):empty { + display: none; } - .print-only { - display: none !important; + +.print-only { + display: none !important; } - @media print { - @page { - margin: 1.25cm 0.75cm; - } - * { - -webkit-box-shadow: none !important; - box-shadow: none !important; - text-shadow: none !important; - } - a, a:visited { - color: inherit !important; - text-decoration: underline !important; - } - a[href^="http:"]:after, a[href^="https:"]:after { - content: " (" attr(href) ")"; - } - a[href^="#"], a[href^="#"]:visited, a[href^="mailto:"], a[href^="mailto:"]:visited { - text-decoration: none !important; - } - abbr[title]:after { - content: " (" attr(title) ")"; - } - pre, blockquote { - page-break-inside: avoid; - } - code { - color: #191919; - } - thead { - display: table-header-group; - } - tr, img { - page-break-inside: avoid; - } - img { - max-width: 100% !important; - } - p { - orphans: 3; - widows: 3; - } - h2, h3, #toctitle, .sidebarblock > .content > .title, #toctitle, .sidebarblock > .content > .title { - page-break-after: avoid; - } - #toc, .sidebarblock { - background: none !important; - } - #toc { - border-bottom: 1px solid #d8d8d8 !important; - padding-bottom: 0 !important; - } - .sect1 { - padding-bottom: 0 !important; - } - .sect1 + .sect1 { - border: none !important; - } - body.book #header { - text-align: center; - } - body.book #header > h1 { - border: none !important; - margin: 2.5em 0 1em 0; - padding: 0; - } - body.book #header span { - line-height: 1.6; - } - body.book #header br { - display: block; - } - body.book #header br + span { - padding-left: 0; - } - body.book #header br + span:before { - content: none !important; - } - body.book #toc { - border: none !important; - text-align: left !important; - padding: 0 !important; - } - #footer { - background: none !important; - } - #footer-text { - color: #333333 !important; - } - .hide-on-print { - display: none !important; - } - .print-only { - display: block !important; - } - .hide-for-print { - display: none !important; - } - .show-for-print { - display: inherit !important; - } + +.print-logo { + display: none; } diff --git a/_stylesheets/print.css b/_stylesheets/print.css new file mode 100644 index 000000000000..d58c9b108315 --- /dev/null +++ b/_stylesheets/print.css @@ -0,0 +1,461 @@ +/** print stylesheet for docs.openshift.com **/ + +@page { + size: auto; + margin: 20mm 15mm 15mm 10mm; +} + +body { + margin: 0px; +} + +#content, +#page { + width: 100%; + float: none; +} + +.main { + margin-top: 100px; +} + +::-webkit-scrollbar { + display: none; +} + +.clipboard-button-container { + display: none !important; +} + +.search-progress-indicator { + display: none; +} + +#hc-modal-content { + display: none; +} + +.open-btn-sm { + display: none !important; +} + +#toc, +.sidebarblock { + background: none !important; +} + +#toc { + border-bottom: 1px solid #d8d8d8 !important; + padding-bottom: 0 !important; + display: contents; +} + +#toc:before { + display: none; +} + +.sect1 { + padding-bottom: 0 !important; +} + +.sect1+.sect1 { + border: none !important; +} + +#footer { + background: none !important; +} + +#footer-text { + color: #333333 !important; +} + +.hide-on-print { + display: none !important; +} + +.print-only { + display: block !important; +} + +.hide-for-print { + display: none !important; +} + +.show-for-print { + display: inherit !important; +} + +.print-logo { + position: relative; + display: block !important; + height: 40px; + width: 220px; + top: 70px; + padding-bottom: 10px; +} + +.page-header { + padding: 0; + border: 0; + margin: 0; + height: unset; +} + +.page-header h1 { + font-size: 22pt; + padding: 0; + border: 0; + margin: 0; + margin-top: 20px; + margin-bottom: 25px; + height: 55px; + letter-spacing: unset; + font-weight: 400; +} + +h2, +h3, +h4 { + font-size: 18pt; + margin-top: 25px; +} + +h1, +h2, +h3, +h4, +h5, +h6 { + break-inside: avoid; + page-break-after: avoid; + break-after: avoid; + text-transform: unset; +} + +h2::after { + content: ""; + display: block; + height: 100px; + margin-bottom: -100px; +} + +h3::after { + content: ""; + display: block; + height: 100px; + margin-bottom: -100px; +} + +h2, +h3 { + padding-top: 20 px; +} + +#collapsibleButtonDiv { + display: none; +} + +b, +optgroup, +strong { + font-weight: 700; + padding: 3px; +} + +td, +th { + padding: 3px; + overflow: hidden; + text-overflow: ellipsis; + word-wrap: break-word; +} + +p, +a { + break-inside: avoid; +} + +.table { + table-layout: fixed; + font-size: 80%; +} + +caption { + padding-top: 8px; + padding-bottom: 8px; + font-style: italic; + font-size: initial; +} + +.admonitionblock { + break-inside: avoid; +} + +.admonitionblock.note { + border-left: solid #4e9fde; +} + +.admonitionblock.important { + border-left: solid #ee2100; +} + +.admonitionblock.warning { + border-left: solid #ec7a09; +} + +.admonitionblock.caution { + border-left: solid #ec7a09; +} + +.admonitionblock.tip { + border-left: solid #328596; +} + +.admonitionblock>table { + border: 0; + background: none; + width: 100%; + table-layout: fixed; + margin-bottom: 10px; + margin-top: 10px; +} + +.admonitionblock td.content>.title { + color: #7a2518; + font-weight: 400; + margin-top: 0; + margin-bottom: .25em +} + +.admonitionblock td.content>.title { + text-rendering: optimizeLegibility; + text-align: left; + font-family: "Noto Serif", "DejaVu Serif", serif; + font-size: 1rem; + font-style: italic +} + +.admonitionblock>table { + border-collapse: separate; + border: 0; + background: none; + width: 100%; + padding-top: 10px; + padding-bottom: 10px; +} + +.admonitionblock>table td.icon { + text-align: center; + width: 80px +} + +.admonitionblock>table td.icon img { + max-width: none +} + +.admonitionblock>table td.icon .title { + font-weight: bold; + font-family: "Open Sans", "DejaVu Sans", sans-serif; + text-transform: uppercase +} + +.admonitionblock>table td.content { + padding-left: 1.125em; + padding-right: 1.25em; + border-left: 1px solid #ddddd8; + color: rgba(0, 0, 0, .6) +} + +.admonitionblock>table td.content>:last-child>:last-child { + margin-bottom: 0 +} + +.admonitionblock td.icon [class^="fa icon-"] { + font-size: 2em; + text-shadow: 1px 1px 2px rgba(0, 0, 0, .5); + cursor: default +} + +.admonitionblock td.icon .icon-note:before { + content: "\f05a"; + color: #19407c +} + +.admonitionblock td.icon .icon-tip:before { + content: "\f0eb"; + text-shadow: 1px 1px 2px rgba(155, 155, 0, .8); + color: #111 +} + +.admonitionblock td.icon .icon-warning:before { + content: "\f071"; + color: #bf6900 +} + +.admonitionblock td.icon .icon-caution:before { + content: "\f06d"; + color: #bf3400 +} + +.admonitionblock td.icon .icon-important:before { + content: "\f06a"; + color: #bf0000 +} + +tr, +img { + break-inside: avoid; +} + +a[href]:after { + display: none; +} + +blockquote { + break-inside: avoid; +} + +img { + break-inside: avoid; + break-after: avoid; + max-width: 100% !important; +} + +dl { + break-before: avoid +} + +ul, +ol { + list-style: square; + margin-left: 2pt; + margin-bottom: 5pt; +} + +a:link, +a:visited, +a { + background: transparent; + text-align: left; + text-decoration: underline; +} + +a { + break-inside: avoid +} + +.entry iframe, +ins { + display: none; + width: 0 !important; + height: 0 !important; + overflow: hidden !important; + line-height: 0pt !important; + white-space: nowrap; +} + +.embed-youtube, +.embed-responsive { + position: absolute; + height: 0; + overflow: hidden; +} + +footer, +aside, +form, +button, +iframe, +span.clipboard-button, +.navbar, +.menu { + display: none; +} + +nav, +.sidebar, +.heading, +.site-title img, +.post-tags, +.readability, +.navbar.navbar-default.navbar-openshift { + display: none; +} + +p, +address, +li, +dt, +dd, +blockquote { + font-size: 100% +} + +p { + orphans: 3; + widows: 3; +} + +.listingblock pre.rouge code { + white-space: pre-wrap; + width: 100%; + display: inline-block; + margin-top: 4px; + margin-bottom: 4px; + margin-left: -6px; + word-break: break-word; + +} + +pre, pre code { + display: unset; + font-size: medium; +} + +pre code { + font-family: "Courier New", Courier, mono; + font-style: normal !important; + letter-spacing: 0; + text-rendering: optimizeSpeed; + word-wrap: break-word; + padding: 8px; + background: #d3d3d347 padding-box !important; + border-radius: 5px; +} + +pre { + margin: 0 0 10px; + word-break: break-all; + background-color: #f0f3f5; + border: 0; + border-radius: 4px; +} + +div.title { + font-weight: 600; + margin-top: 10px; + margin-bottom: 5px; +} + +#truste-consent-track, +#truste-consent-text, +.truste-banner, +.truste_overlay, +.truste_box_overlay, +.truste_titlee, +.mainContent { + display: none !important; +} + +* { + -webkit-box-shadow: none !important; + -webkit-print-color-adjust: exact; + print-color-adjust: exact; + box-shadow: none !important; + text-shadow: none !important; +} + +.breadcrumb { + display: none; +} \ No newline at end of file diff --git a/_templates/_nav_openshift.html.erb b/_templates/_nav_openshift.html.erb index e1e2ddb5f71c..7da260ff6e71 100644 --- a/_templates/_nav_openshift.html.erb +++ b/_templates/_nav_openshift.html.erb @@ -1,127 +1,29 @@
    <%- navigation.each.with_index do |topic_group, groupidx| -%> - - - -<%# group_id %> -<%# topic_group[:id] %> -<%# topic_id %> - - - <%- current_group = topic_group[:id] == group_id -%> -
  • - -<%# current_group %> -<%# topic_group[:id] %> -<%# group_id %> - - - - - <%= topic_group[:name] %> - - - - - - +
  • <%= topic_group[:name] %>
      - <%- topic_group[:topics].each.with_index do |topic, topicidx| -%> - - - <%- if not topic.has_key?(:topics) -%> - - - <%- current_topic = current_group && (topic[:id] == topic_id) -%> - -
    • <%= topic[:name] %>
      • - - <%- else -%> - - - <%- current_subgroup = topic[:id] == subgroup_id -%> - - - -
    • - - -  <%= topic[:name] %> - - - - +
    •  <%= topic[:name] %>
      • diff --git a/_templates/_page_openshift.html.erb b/_templates/_page_openshift.html.erb index 8502e13f54c7..6d825bf95a16 100644 --- a/_templates/_page_openshift.html.erb +++ b/_templates/_page_openshift.html.erb @@ -4,38 +4,214 @@ + <%= (distro_key == "openshift-webscale") ? '' : '' %> + <%= (distro_key == "openshift-dpu") ? '' : '' %> + <%= ((["3.0", "3.1", "3.2", "3.3", "3.4", "3.5", "3.6", "3.7", "3.9", "3.10", "4.1", "4.2", "4.3", "4.4", "4.5", "4.6", "4.7"].include?(version)) && distro_key == "openshift-enterprise") ? '' : '' %> <%= [topic_title, subgroup_title].compact.join(' - ') %> | <%= group_title %> | <%= distro %> <%= version %> - - - - - - - + + + + + + + + - <%= render("_templates/_analytics.html.erb", :distro_key => distro_key) %> + + + + + + + + + + <%= render("_templates/_topnav.html.erb", :distro_key => distro_key) %> <% - unsupported_versions = ["3.0", "3.1", "3.2", "3.3", "3.4", "3.5", "3.6", "3.7", "3.9", "3.10", "4.1", "4.2", "4.3", "4.4"]; + unsupported_versions = ["3.0", "3.1", "3.2", "3.3", "3.4", "3.5", "3.6", "3.7", "3.9", "3.10", "4.1", "4.2", "4.3", "4.4", "4.5", "4.6", "4.7", "4.8", "4.9", "4.10", "4.11", "4.13"]; + + unsupported_versions_acs = ["3.65", "3.66", "3.67", "3.68", "3.69", "3.70", "3.71", "3.72", "3.73", "3.74", "4.0", "4.1", "4.2", "4.3"]; + + unsupported_versions_serverless = ["1.28", "1.29", "1.30", "1.31"]; + + unsupported_versions_pipelines = ["1.10", "1.11", "1.12"]; + + unsupported_versions_gitops = ["1.8", "1.9", "1.10", "1.11"]; + + unsupported_versions_builds = []; + + unsupported_versions_origin = ["3.0", "3.1", "3.2", "3.3", "3.4", "3.5", "3.6", "3.7", "3.9", "3.10", "3.11", "4.1", "4.2", "4.3", "4.4", "4.5", "4.6", "4.7", "4.8", "4.9", "4.10", "4.11", "4.12"]; + %>
      -

      - -

      -
        + +
          + <% + unsupported = (unsupported_versions.include?(version) || + unsupported_versions_acs.include?(version) || + unsupported_versions_builds.include?(version) || + unsupported_versions_gitops.include?(version) || + unsupported_versions_origin.include?(version) + unsupported_versions_pipelines.include?(version) || + unsupported_versions_serverless.include?(version) + ); + + if (!["openshift-webscale", "openshift-dpu", "openshift-lightspeed", "openshift-service-mesh", "openshift-origin", "openshift-acs", "openshift-rosa", "openshift-dedicated"].include?(distro_key) || unsupported) + %> + +
          + Starting on March 12, 2025, OpenShift docs will only be available at docs.redhat.com. From that time on, docs.openshift.com links will automatically redirect to their locations on docs.redhat.com. + +
          +           + <% end %> + + <% if (distro_key == "openshift-webscale" || distro_key == "openshift-dpu") %> + + + + <% end %> + + <% if (distro_key == "openshift-lightspeed") %> + + + + <% end %> + + <% if (distro_key == "openshift-service-mesh") %> + + + + <% end %> + + <% if (distro_key == "openshift-acs") %> + +
          + Starting on March 12, 2025, OpenShift docs will only be available at docs.redhat.com. From that time on, docs.openshift.com links will automatically redirect to their locations on docs.redhat.com. + +
          +           + <% end %> + + <% if (distro_key == "openshift-dedicated") %> + +
          + Starting on March 12, 2025, OpenShift docs will only be available at docs.redhat.com. From that time on, docs.openshift.com links will automatically redirect to their locations on docs.redhat.com. + +
          +           + <% end %> + + <% if (distro_key == "openshift-rosa") %> + +
          + Starting on March 12, 2025, OpenShift docs will only be available at docs.redhat.com. From that time on, docs.openshift.com links will automatically redirect to their locations on docs.redhat.com. + +
          +           + <% end %> + + <% if ((version == "latest") &&(distro_key == "openshift-origin")) %> + + + + <% end %> + <% if ((unsupported_versions.include? version) && (distro_key == "openshift-enterprise")) %> + + + + + + <% end %> + + <% if ((unsupported_versions_acs.include? version) && (distro_key == "openshift-acs")) %> + + + + + + <% end %> + + <% if ((unsupported_versions_serverless.include? version) && (distro_key == "openshift-serverless")) %> + + + + + + <% end %> + + + <% if ((unsupported_versions_pipelines.include? version) && (distro_key == "openshift-pipelines")) %> + + + + + + <% end %> + + <% if ((unsupported_versions_builds.include? version) && (distro_key == "openshift-builds")) %> + + + + + + <% end %> + + + <% if ((unsupported_versions_gitops.include? version) && (distro_key == "openshift-gitops")) %> + + + + + + <% end %> + + <% if ((unsupported_versions_origin.include? version) && (distro_key == "openshift-origin")) %> + + + + + + <% end %> +
        1. - <%= site_name %> + + <%= site_name %>
          2. <%= breadcrumb_subgroup_block %> + <%= breadcrumb_subsubgroup_block %> - - <% if (distro_key != "openshift-origin" && distro_key != "openshift-aro") %> + <% if (distro_key != "openshift-origin" && distro_key != "openshift-aro" && distro_key != "openshift-acs" && distro_key != "openshift-serverless" && distro_key != "openshift-gitops" && distro_key != "openshift-pipelines" && distro_key != "openshift-builds" && distro_key != "openshift-lightspeed" && distro_key != "openshift-service-mesh" && distro_key != "openshift-telco") %> - /<%= repo_path %>"> - Page history - + /<%= repo_path %>">history <% unless (unsupported_versions.include? version) %> - / - "> - Open an issue + "> + bug_report + picture_as_pdf + <% if (version == "4.5") %> + / + + <% end %> <% end %> + <% elsif (distro_key == "openshift-acs") %> + + /<%= repo_path %>"> + history + + + <% unless (unsupported_versions_acs.include? version) %> + "> + bug_report + + + + picture_as_pdf + + <% end %> + + <% elsif (distro_key == "openshift-serverless") %> + + /<%= repo_path %>"> + history + + + <% unless (unsupported_versions_serverless.include? version) %> + "> + bug_report + + + + picture_as_pdf + + <% end %> + + <% elsif (distro_key == "openshift-pipelines") %> + + /<%= repo_path %>"> + history + + + <% unless (unsupported_versions_pipelines.include? version) %> + "> + bug_report + + + + picture_as_pdf + + <% end %> + + <% elsif (distro_key == "openshift-builds") %> + + /<%= repo_path %>"> + history + + + <% unless (unsupported_versions_builds.include? version) %> + "> + bug_report + + + + picture_as_pdf + + <% end %> + + <% elsif (distro_key == "openshift-gitops") %> + + /<%= repo_path %>"> + history + + + <% unless (unsupported_versions_gitops.include? version) %> + "> + bug_report + + + + picture_as_pdf + + <% end %> + <% end %>
        -
        +
        +
        + +
        - -
        -
        - × -
        -
        -
        -
        - -
        -
        +
        + <%= render("_templates/_nav_openshift.html.erb", :distro_key => distro_key, :navigation => navigation, :group_id => group_id, :topic_id => topic_id, :subgroup_id => subgroup_id, :subtopic_shim => subtopic_shim, :subsubgroup_id => subsubgroup_id) %> +
        +
        +
        + × +
        +
        +
        +
        +
        - <%= render("_templates/_nav_openshift.html.erb", :distro_key => distro_key, :navigation => navigation, :group_id => group_id, :topic_id => topic_id, :subgroup_id => subgroup_id, :subtopic_shim => subtopic_shim, :subsubgroup_id => subsubgroup_id) %> +
        +
        -

        <%= article_title %>

        +

        + <%= article_title %> +

        - <% if (version == "4.8") %> - This documentation is work in progress and might not be complete or fully tested. -
        - This documentation is work in progress and might not be complete or fully tested. -
        - <% end %> - <% - if (unsupported_versions.include? version) - %> - You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see [4] -
        - You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see [4] -
        - <% end %> <% if (distro_key == "openshift-aro" && version == "3") %> - -
        - Important -         - -

        Azure Red Hat OpenShift 3.11 will be retired 30 June 2022. Support for creation of new Azure Red Hat OpenShift 3.11 clusters continues through 30 November 2020. Following retirement, remaining Azure Red Hat OpenShift 3.11 clusters will be shut down to prevent security vulnerabilities.

        - -

        Follow this guide to create an Azure Red Hat OpenShift 4 cluster. If you have specific questions, please contact us

        -
        + +
        + Important +         +

        Azure Red Hat OpenShift 3.11 will be retired 30 June 2022. Support for creation of new Azure Red Hat OpenShift 3.11 clusters continues through 30 November 2020. Following retirement, remaining Azure Red Hat OpenShift 3.11 clusters will be shut down to prevent security vulnerabilities.

        +

        Follow this guide to create an Azure Red Hat OpenShift 4 cluster. If you have specific questions, please contact us

        +
        <% end %> <% if (distro_key == "openshift-aro" && version == "4") %> - -
        - Important -         -

        Azure Red Hat OpenShift is supported by Red Hat and Microsoft. As of February 2021, the documentation will be hosted by Microsoft and Red Hat as outlined below.

        -
        + +
        + Important +         +

        Azure Red Hat OpenShift is supported by Red Hat and Microsoft. As of February 2021, the documentation will be hosted by Microsoft and Red Hat as outlined below.

        +
        <% end %> - <%= content %>
        - - - - - + + + + - - - + + + + <%= render("_templates/_footer.html.erb", :distro_key => distro_key, :images_path => images_path) %> + + + + + + + + + + + + + + + + + + + + + + + + + - <%= render("_templates/_footer.html.erb", :distro_key => distro_key, :images_path => images_path) %> diff --git a/_topic_map.yml b/_topic_map.yml deleted file mode 100644 index 78c06593bbc5..000000000000 --- a/_topic_map.yml +++ /dev/null @@ -1,2940 +0,0 @@ -# This configuration file dictates the organization of the topic groups and -# topics on the main page of the doc site for this branch. Each record -# consists of the following: -# -# --- <= Record delimiter -# Name: Origin of the Species <= Display name of topic group -# Dir: origin_of_the_species <= Directory name of topic group -# Topics: -# - Name: The Majestic Marmoset <= Topic name -# File: the_majestic_marmoset <= Topic file under group dir +/- -# - Name: The Curious Crocodile <= Topic 2 name -# File: the_curious_crocodile <= Topic 2 file -# - Name: The Numerous Nematodes <= Sub-topic group name -# Dir: the_numerous_nematodes <= Sub-topic group dir -# Topics: -# - Name: The Wily Worm <= Sub-topic name -# File: the_wily_worm <= Sub-topic file under / -# - Name: The Acrobatic Ascarid <= Sub-topic 2 name -# File: the_acrobatic_ascarid <= Sub-topic 2 file under / -# -# The ordering of the records in this document determines the ordering of the -# topic groups and topics on the main page. - ---- -Name: About -Dir: welcome -Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -Topics: -- Name: Welcome - File: index -- Name: Learn more about OpenShift Container Platform - File: learn_more_about_openshift - Distros: openshift-enterprise -- Name: About OpenShift Kubernetes Engine - File: oke_about - Distros: openshift-enterprise -- Name: Legal notice - File: legal-notice ---- -Name: What's new? -Dir: whats_new -Distros: openshift-origin -Topics: -- Name: New features and enhancements - File: new-features -- Name: Deprecated features - File: deprecated-features ---- -Name: Getting started -Dir: getting_started -Distros: openshift-dedicated -Topics: -- Name: Accessing your services - File: accessing-your-services -- Name: Scaling your cluster - File: scaling-your-cluster -- Name: Deleting your cluster - File: deleting-your-cluster -- Name: Networking - File: dedicated-networking ---- -Name: Cloud infrastructure access -Dir: cloud_infrastructure_access -Distros: openshift-dedicated -Topics: -- Name: Understanding cloud infrastructure access - File: dedicated-understanding-aws -- Name: Accessing AWS infrastructure - File: dedicated-aws-access -- Name: Configuring AWS VPC peering - File: dedicated-aws-peering -- Name: Configuring AWS VPN - File: dedicated-aws-vpn -- Name: Configuring AWS Direct Connect - File: dedicated-aws-dc -- Name: Configuring a private cluster - File: dedicated-aws-private-cluster ---- -Name: Release notes -Dir: release_notes -Distros: openshift-enterprise -Topics: -- Name: OpenShift Container Platform 4.8 release notes - File: ocp-4-8-release-notes -- Name: Versioning policy - File: versioning-policy ---- -Name: Architecture -Dir: architecture -Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -Topics: -- Name: Product architecture - File: architecture -- Name: Installation and update - Distros: openshift-enterprise,openshift-origin - File: architecture-installation -- Name: The control plane - File: control-plane - Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -- Name: Understanding OpenShift development - File: understanding-development -- Name: Fedora CoreOS - File: architecture-rhcos - Distros: openshift-origin -- Name: Red Hat Enterprise Linux CoreOS - File: architecture-rhcos - Distros: openshift-enterprise -- Name: Admission plug-ins - File: admission-plug-ins - Distros: openshift-enterprise,openshift-aro ---- -Name: Administering a cluster -Dir: administering_a_cluster -Distros: openshift-dedicated -Topics: -- Name: The dedicated-admin role - File: dedicated-admin-role -- Name: The cluster-admin role - File: cluster-admin-role ---- -Name: Installing -Dir: installing -Distros: openshift-origin,openshift-enterprise -Topics: -- Name: Installation overview - File: index -- Name: Selecting an installation method and preparing a cluster - File: installing-preparing -- Name: Installing on AWS - Dir: installing_aws - Topics: - - Name: Preparing to install on AWS - File: preparing-to-install-on-aws - - Name: Configuring an AWS account - File: installing-aws-account - - Name: Manually creating IAM - File: manually-creating-iam - - Name: Installing a cluster quickly on AWS - File: installing-aws-default - - Name: Installing a cluster on AWS with customizations - File: installing-aws-customizations - - Name: Installing a cluster on AWS with network customizations - File: installing-aws-network-customizations - - Name: Installing a cluster on AWS into an existing VPC - File: installing-aws-vpc - - Name: Installing a private cluster on AWS - File: installing-aws-private - - Name: Installing a cluster on AWS into a government or secret region - File: installing-aws-government-region - - Name: Installing a cluster on AWS using CloudFormation templates - File: installing-aws-user-infra - - Name: Installing a cluster on AWS in a restricted network with user-provisioned infrastructure - File: installing-restricted-networks-aws - - Name: Uninstalling a cluster on AWS - File: uninstalling-cluster-aws -- Name: Installing on Azure - Dir: installing_azure - Topics: - - Name: Configuring an Azure account - File: installing-azure-account - - Name: Manually creating IAM - File: manually-creating-iam-azure - - Name: Installing a cluster quickly on Azure - File: installing-azure-default - - Name: Installing a cluster on Azure with customizations - File: installing-azure-customizations - - Name: Installing a cluster on Azure with network customizations - File: installing-azure-network-customizations - - Name: Installing a cluster on Azure into an existing VNet - File: installing-azure-vnet - - Name: Installing a private cluster on Azure - File: installing-azure-private - - Name: Installing a cluster on Azure into a government region - File: installing-azure-government-region - - Name: Installing a cluster on Azure using ARM templates - File: installing-azure-user-infra - - Name: Uninstalling a cluster on Azure - File: uninstalling-cluster-azure -- Name: Installing on GCP - Dir: installing_gcp - Topics: - - Name: Configuring a GCP project - File: installing-gcp-account - - Name: Manually creating IAM - File: manually-creating-iam-gcp - - Name: Installing a cluster quickly on GCP - File: installing-gcp-default - - Name: Installing a cluster on GCP with customizations - File: installing-gcp-customizations - - Name: Installing a cluster on GCP with network customizations - File: installing-gcp-network-customizations - - Name: Installing a cluster on GCP into an existing VPC - File: installing-gcp-vpc - - Name: Installing a private cluster on GCP - File: installing-gcp-private - - Name: Installing a cluster on GCP using Deployment Manager templates - File: installing-gcp-user-infra - - Name: Installing a cluster on GCP using Deployment Manager templates and a shared VPC - File: installing-gcp-user-infra-vpc - - Name: Installing a cluster on GCP in a restricted network with user-provisioned infrastructure - File: installing-restricted-networks-gcp - - Name: Uninstalling a cluster on GCP - File: uninstalling-cluster-gcp -- Name: Installing on bare metal - Dir: installing_bare_metal - Topics: - - Name: Installing a cluster on bare metal - File: installing-bare-metal - - Name: Installing a cluster on bare metal with network customizations - File: installing-bare-metal-network-customizations - - Name: Restricted network bare metal installation - File: installing-restricted-networks-bare-metal -- Name: Deploying installer-provisioned clusters on bare metal - Dir: installing_bare_metal_ipi - Distros: openshift-origin,openshift-enterprise - Topics: - - Name: Overview - File: ipi-install-overview - - Name: Prerequisites - File: ipi-install-prerequisites - - Name: Setting up the environment for an OpenShift installation - File: ipi-install-installation-workflow - - Name: Expanding the cluster - File: ipi-install-expanding-the-cluster - - Name: Troubleshooting - File: ipi-install-troubleshooting -- Name: Installing with z/VM on IBM Z and LinuxONE - Dir: installing_ibm_z - Distros: openshift-enterprise - Topics: - - Name: Installing a cluster with z/VM on IBM Z and LinuxONE - File: installing-ibm-z - - Name: Restricted network IBM Z installation with z/VM - File: installing-restricted-networks-ibm-z -- Name: Installing with RHEL KVM on IBM Z and LinuxONE - Dir: installing_ibm_z - Distros: openshift-enterprise - Topics: - - Name: Installing a cluster with RHEL KVM on IBM Z and LinuxONE - File: installing-ibm-z-kvm -- Name: Installing on IBM Power Systems - Dir: installing_ibm_power - Distros: openshift-enterprise - Topics: - - Name: Installing a cluster on IBM Power Systems - File: installing-ibm-power - - Name: Restricted network IBM Power Systems installation - File: installing-restricted-networks-ibm-power -- Name: Installing on OpenStack - Dir: installing_openstack - Topics: -# - Name: Installing a cluster on OpenStack -# File: installing-openstack-installer - - Name: Installing a cluster on OpenStack with customizations - File: installing-openstack-installer-custom - - Name: Installing a cluster on OpenStack with Kuryr - File: installing-openstack-installer-kuryr - - Name: Installing a cluster on OpenStack on your own infrastructure - File: installing-openstack-user - - Name: Installing a cluster on OpenStack with Kuryr on your own infrastructure - File: installing-openstack-user-kuryr - - Name: Installing a cluster on OpenStack in a restricted network - File: installing-openstack-installer-restricted - # - Name: Load balancing deployments on OpenStack - # File: installing-openstack-load-balancing - - Name: Uninstalling a cluster on OpenStack - File: uninstalling-cluster-openstack - - Name: Uninstalling a cluster on OpenStack from your own infrastructure - File: uninstalling-openstack-user -- Name: Installing on RHV - Dir: installing_rhv - Distros: openshift-enterprise,openshift-dedicated,openshift-online - Topics: - - Name: Installing a cluster quickly on RHV - File: installing-rhv-default - - Name: Installing a cluster on RHV with customizations - File: installing-rhv-customizations - - Name: Installing a cluster on RHV with user-provisioned infrastructure - File: installing-rhv-user-infra - - Name: Installing a cluster on RHV in a restricted network - File: installing-rhv-restricted-network - - Name: Uninstalling a cluster on RHV - File: uninstalling-cluster-rhv -- Name: Installing on oVirt - Dir: installing_rhv - Distros: openshift-origin - Topics: - - Name: Installing a cluster quickly on oVirt - File: installing-rhv-default - - Name: Installing a cluster on oVirt with customizations - File: installing-rhv-customizations - - Name: Installing a cluster on oVirt with user-provisioned infrastructure - File: installing-rhv-user-infra - - Name: Uninstalling a cluster on oVirt - File: uninstalling-cluster-rhv -- Name: Installing on vSphere - Dir: installing_vsphere - Topics: - - Name: Installing a cluster on vSphere - File: installing-vsphere-installer-provisioned - - Name: Installing a cluster on vSphere with customizations - File: installing-vsphere-installer-provisioned-customizations - - Name: Installing a cluster on vSphere with network customizations - File: installing-vsphere-installer-provisioned-network-customizations - - Name: Installing a cluster on vSphere with user-provisioned infrastructure - File: installing-vsphere - - Name: Installing a cluster on vSphere with user-provisioned infrastructure and network customizations - File: installing-vsphere-network-customizations - - Name: Installing a cluster on vSphere in a restricted network - File: installing-restricted-networks-installer-provisioned-vsphere - - Name: Installing a cluster on vSphere in a restricted network with user-provisioned infrastructure - File: installing-restricted-networks-vsphere - - Name: Uninstalling a cluster on vSphere that uses installer-provisioned infrastructure - File: uninstalling-cluster-vsphere-installer-provisioned - - Name: Using the vSphere Problem Detector Operator - File: using-vsphere-problem-detector-operator -- Name: Installing on VMC - Dir: installing_vmc - Topics: - - Name: Installing a cluster on VMC - File: installing-vmc - - Name: Installing a cluster on VMC with customizations - File: installing-vmc-customizations - - Name: Installing a cluster on VMC with network customizations - File: installing-vmc-network-customizations - - Name: Installing a cluster on VMC with user-provisioned infrastructure - File: installing-vmc-user-infra - - Name: Installing a cluster on VMC with user-provisioned infrastructure and network customizations - File: installing-vmc-network-customizations-user-infra - - Name: Installing a cluster on VMC in a restricted network with user-provisioned infrastructure - File: installing-restricted-networks-vmc-user-infra - - Name: Uninstalling a cluster on VMC - File: uninstalling-cluster-vmc -- Name: Installing on any platform - Dir: installing_platform_agnostic - Topics: - - Name: Installing a cluster on any platform - File: installing-platform-agnostic -- Name: Installation configuration - Dir: install_config - Topics: - - Name: Customizing nodes - File: installing-customizing - - Name: Creating a mirror registry for a restricted network - File: installing-restricted-networks-preparations - - Name: Configuring your firewall - File: configuring-firewall -- Name: Validating an installation - File: validating-an-installation -- Name: Troubleshooting installation issues - File: installing-troubleshooting -- Name: Support for FIPS cryptography - File: installing-fips - Distros: openshift-enterprise,openshift-dedicated,openshift-online ---- -Name: Post-installation configuration -Dir: post_installation_configuration -Distros: openshift-origin,openshift-enterprise -Topics: -- Name: Configuring a private cluster - Distros: openshift-enterprise,openshift-origin - File: configuring-private-cluster -- Name: Machine configuration tasks - File: machine-configuration-tasks -- Name: Cluster tasks - File: cluster-tasks -- Name: Node tasks - File: node-tasks -- Name: Network configuration - File: network-configuration -- Name: Storage configuration - File: storage-configuration -- Name: Preparing for users - File: preparing-for-users -- Name: Configuring alert notifications - File: configuring-alert-notifications ---- -Name: Updating clusters -Dir: updating -Distros: openshift-origin,openshift-enterprise -Topics: -- Name: Understanding the update service - File: understanding-the-update-service -- Name: Updating a cluster between minor versions - File: updating-cluster-between-minor -- Name: Updating a cluster within a minor version from the web console - File: updating-cluster -- Name: Updating a cluster within a minor version by using the CLI - File: updating-cluster-cli -- Name: Updating a cluster that includes RHEL compute machines - File: updating-cluster-rhel-compute - Distros: openshift-enterprise -- Name: Updating a restricted network cluster - File: updating-restricted-network-cluster - Distros: openshift-enterprise -# - Name: Troubleshooting an update -# File: updating-troubleshooting ---- -Name: Support -Dir: support -Distros: openshift-enterprise,openshift-online,openshift-dedicated,openshift-origin -Topics: -- Name: Getting support - File: getting-support - Distros: openshift-enterprise,openshift-dedicated -- Name: Remote health monitoring with connected clusters - Dir: remote_health_monitoring - Distros: openshift-enterprise,openshift-dedicated,openshift-origin - Topics: - - Name: About remote health monitoring - File: about-remote-health-monitoring - - Name: Showing data collected by remote health monitoring - File: showing-data-collected-by-remote-health-monitoring - - Name: Opting out of remote health reporting - File: opting-out-of-remote-health-reporting - - Name: Using Insights to identify issues with your cluster - File: using-insights-to-identify-issues-with-your-cluster -- Name: Gathering data about your cluster - File: gathering-cluster-data - Distros: openshift-enterprise,openshift-origin -- Name: Summarizing cluster specifications - File: summarizing-cluster-specifications - Distros: openshift-enterprise,openshift-origin -- Name: Troubleshooting - Dir: troubleshooting - Distros: openshift-enterprise,openshift-dedicated,openshift-origin - Topics: - - Name: Troubleshooting installations - File: troubleshooting-installations - - Name: Verifying node health - File: verifying-node-health - - Name: Troubleshooting CRI-O container runtime issues - File: troubleshooting-crio-issues - - Name: Troubleshooting operating system issues - File: troubleshooting-operating-system-issues - Distros: openshift-enterprise,openshift-origin - - Name: Troubleshooting Operator issues - File: troubleshooting-operator-issues - - Name: Investigating pod issues - File: investigating-pod-issues - - Name: Troubleshooting the Source-to-Image process - File: troubleshooting-s2i - - Name: Troubleshooting storage issues - File: troubleshooting-storage-issues - - Name: Troubleshooting Windows container workload issues - File: troubleshooting-windows-container-workload-issues - - Name: Investigating monitoring issues - File: investigating-monitoring-issues - - Name: Diagnosing OpenShift CLI (oc) issues - File: diagnosing-oc-issues ---- -Name: Web console -Dir: web_console -Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -Topics: -- Name: Accessing the web console - File: web-console -- Name: Viewing cluster information - File: using-dashboard-to-get-cluster-information - Distros: openshift-enterprise,openshift-origin -- Name: Configuring the web console - File: configuring-web-console - Distros: openshift-enterprise,openshift-origin -- Name: Customizing the web console - File: customizing-the-web-console - Distros: openshift-enterprise,openshift-origin -- Name: Developer perspective - File: odc-about-developer-perspective -- Name: Web terminal - File: odc-about-web-terminal -- Name: Disabling the web console - File: disabling-web-console - Distros: openshift-enterprise,openshift-origin -- Name: Creating quick start tutorials - File: creating-quick-start-tutorials - Distros: openshift-enterprise,openshift-origin ---- -Name: CLI tools -Dir: cli_reference -Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -Topics: -- Name: OpenShift CLI (oc) - Dir: openshift_cli - Topics: - - Name: Getting started with the OpenShift CLI - File: getting-started-cli - - Name: Configuring the OpenShift CLI - File: configuring-cli - - Name: Extending the OpenShift CLI with plug-ins - File: extending-cli-plugins - Distros: openshift-enterprise,openshift-origin - - Name: OpenShift CLI developer commands - File: developer-cli-commands - - Name: OpenShift CLI administrator commands - File: administrator-cli-commands - Distros: openshift-enterprise,openshift-origin - - Name: Usage of oc and kubectl commands - File: usage-oc-kubectl -- Name: Developer CLI (odo) - Dir: developer_cli_odo - Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online - Topics: - - Name: Understanding odo - File: understanding-odo - - Name: Installing odo - File: installing-odo - - Name: Creating and deploying applications with odo - Dir: creating_and_deploying_applications_with_odo - Topics: - - Name: Working with projects - File: working-with-projects - - Name: Creating a single-component application with odo - File: creating-a-single-component-application-with-odo - - Name: Creating a multicomponent application with odo - File: creating-a-multicomponent-application-with-odo - - Name: Creating an application with a database - File: creating-an-application-with-a-database - - Name: Creating a Java application with a database - File: creating-a-java-application-with-a-database - - Name: Using devfiles in odo - File: using-devfiles-in-odo - - Name: Working with storage - File: working-with-storage - - Name: Deleting applications - File: deleting-applications - - Name: Debugging applications in odo - File: debugging-applications-in-odo - - Name: Sample applications - File: sample-applications - - Name: Using odo in a restricted environment - Dir: using_odo_in_a_restricted_environment - Topics: - - Name: About odo in a restricted environment - File: about-odo-in-a-restricted-environment - - Name: Pushing the odo init image to the restricted cluster registry - File: pushing-the-odo-init-image-to-the-restricted-cluster-registry - - Name: Creating and deploying a component to the disconnected cluster - File: creating-and-deploying-a-component-to-the-disconnected-cluster - - Name: Creating instances of services managed by Operators - File: creating-instances-of-services-managed-by-operators - - Name: Managing environment variables in odo - File: managing-environment-variables-in-odo - - Name: Configuring the odo CLI - File: configuring-the-odo-cli - - Name: odo CLI reference - File: odo-cli-reference - - Name: odo architecture - File: odo-architecture - - Name: odo release notes - File: odo-release-notes -- Name: Helm CLI - Dir: helm_cli - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Getting started with Helm on OpenShift Container Platform - File: getting-started-with-helm-on-openshift-container-platform - - Name: Configuring custom Helm chart repositories - File: configuring-custom-helm-chart-repositories - - Name: Disabling Helm chart repositories - File: disabling-helm-chart-repositories -- Name: Knative CLI (kn) for use with OpenShift Serverless - File: kn-cli-tools - Distros: openshift-enterprise,openshift-origin -- Name: Pipelines CLI (tkn) - Dir: tkn_cli - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Installing tkn - File: installing-tkn - - Name: Configuring tkn - File: op-configuring-tkn - - Name: Basic tkn commands - File: op-tkn-reference -- Name: opm CLI - File: opm-cli - Distros: openshift-enterprise,openshift-origin -- Name: Operator SDK - Dir: osdk - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Installing the Operator SDK CLI - File: cli-osdk-install - - Name: Operator SDK CLI reference - File: cli-osdk-ref ---- -Name: Security and compliance -Dir: security -Distros: openshift-enterprise,openshift-origin,openshift-aro -Topics: -- Name: Compliance Operator - Dir: compliance_operator - Topics: - - Name: Installing the Compliance Operator - File: compliance-operator-installation - - Name: Compliance Operator scans - File: compliance-scans - - Name: Understanding the Compliance Operator - File: compliance-operator-understanding - - Name: Managing the Compliance Operator - File: compliance-operator-manage - - Name: Tailoring the Compliance Operator - File: compliance-operator-tailor - - Name: Retrieving Compliance Operator raw results - File: compliance-operator-raw-results - - Name: Managing Compliance Operator remediation - File: compliance-operator-remediation - - Name: Performing advanced Compliance Operator tasks - File: compliance-operator-advanced - - Name: Troubleshooting the Compliance Operator - File: compliance-operator-troubleshooting -- Name: File Integrity Operator - Dir: file_integrity_operator - Topics: - - Name: Understanding the File Integrity Operator - File: file-integrity-operator-understanding - - Name: Configuring the File Integrity Operator - File: file-integrity-operator-configuring - - Name: Performing advanced File Integrity Operator tasks - File: file-integrity-operator-advanced-usage - - Name: Troubleshooting the File Integrity Operator - File: file-integrity-operator-troubleshooting -- Name: Container security - Dir: container_security - Topics: - - Name: Understanding container security - File: security-understanding - - Name: Understanding host and VM security - File: security-hosts-vms - - Name: Hardening Red Hat Enterprise Linux CoreOS - File: security-hardening - Distros: openshift-enterprise,openshift-aro - - Name: Hardening Fedora CoreOS - File: security-hardening - Distros: openshift-origin - - Name: Understanding compliance - File: security-compliance - - Name: Securing container content - File: security-container-content - - Name: Using container registries securely - File: security-registries - - Name: Securing the build process - File: security-build - - Name: Deploying containers - File: security-deploy - - Name: Securing the container platform - File: security-platform - - Name: Securing networks - File: security-network - - Name: Securing attached storage - File: security-storage - - Name: Monitoring cluster events and logs - File: security-monitoring -- Name: Configuring certificates - Dir: certificates - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Replacing the default ingress certificate - File: replacing-default-ingress-certificate - - Name: Adding API server certificates - File: api-server - - Name: Securing service traffic using service serving certificates - File: service-serving-certificate -- Name: Certificate types and descriptions - Dir: certificate_types_descriptions - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: User-provided certificates for the API server - File: user-provided-certificates-for-api-server - - Name: Proxy certificates - File: proxy-certificates - - Name: Service CA certificates - File: service-ca-certificates - - Name: Node certificates - File: node-certificates - - Name: Bootstrap certificates - File: bootstrap-certificates - - Name: etcd certificates - File: etcd-certificates - - Name: OLM certificates - File: olm-certificates - - Name: User-provided certificates for default ingress - File: user-provided-certificates-for-default-ingress - - Name: Ingress certificates - File: ingress-certificates - - Name: Monitoring and cluster logging Operator component certificates - File: monitoring-and-cluster-logging-operator-component-certificates - - Name: Control plane certificates - File: control-plane-certificates -- Name: Viewing audit logs - File: audit-log-view -- Name: Configuring the audit log policy - File: audit-log-policy-config -- Name: Allowing JavaScript-based access to the API server from additional hosts - File: allowing-javascript-access-api-server - Distros: openshift-enterprise,openshift-origin -- Name: Encrypting etcd data - File: encrypting-etcd - Distros: openshift-enterprise,openshift-origin -- Name: Scanning pods for vulnerabilities - File: pod-vulnerability-scan - Distros: openshift-enterprise,openshift-origin ---- -Name: Authentication and authorization -Dir: authentication -Distros: openshift-enterprise,openshift-origin,openshift-dedicated -Topics: -- Name: Understanding authentication - File: understanding-authentication - Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -- Name: Understanding identity provider configuration - File: dedicated-understanding-authentication - Distros: openshift-dedicated -- Name: Configuring the internal OAuth server - File: configuring-internal-oauth -- Name: Configuring OAuth clients - File: configuring-oauth-clients -- Name: Managing user-owned OAuth access tokens - File: managing-oauth-access-tokens - Distros: openshift-enterprise,openshift-origin -- Name: Understanding identity provider configuration - File: understanding-identity-provider - Distros: openshift-enterprise,openshift-origin -- Name: Configuring identity providers - Dir: identity_providers - Topics: - - Name: Configuring an HTPasswd identity provider - File: configuring-htpasswd-identity-provider - Distros: openshift-enterprise,openshift-origin - - Name: Configuring a Keystone identity provider - File: configuring-keystone-identity-provider - Distros: openshift-enterprise,openshift-origin - - Name: Configuring an LDAP identity provider - File: configuring-ldap-identity-provider - - Name: Configuring a basic authentication identity provider - File: configuring-basic-authentication-identity-provider - Distros: openshift-enterprise,openshift-origin - - Name: Configuring a request header identity provider - File: configuring-request-header-identity-provider - Distros: openshift-enterprise,openshift-origin - - Name: Configuring a GitHub or GitHub Enterprise identity provider - File: configuring-github-identity-provider - - Name: Configuring a GitLab identity provider - File: configuring-gitlab-identity-provider - Distros: openshift-enterprise,openshift-origin - - Name: Configuring a Google identity provider - File: configuring-google-identity-provider - - Name: Configuring an OpenID Connect identity provider - File: configuring-oidc-identity-provider -- Name: Using RBAC to define and apply permissions - File: using-rbac -- Name: Removing the kubeadmin user - File: remove-kubeadmin - Distros: openshift-enterprise,openshift-origin -#- Name: Configuring LDAP failover -# File: configuring-ldap-failover -- Name: Understanding and creating service accounts - File: understanding-and-creating-service-accounts -- Name: Using service accounts in applications - File: using-service-accounts-in-applications -- Name: Using a service account as an OAuth client - File: using-service-accounts-as-oauth-client -- Name: Scoping tokens - File: tokens-scoping -- Name: Using bound service account tokens - File: bound-service-account-tokens -- Name: Managing security context constraints - File: managing-security-context-constraints - Distros: openshift-enterprise,openshift-origin -- Name: Impersonating the system:admin user - File: impersonating-system-admin - Distros: openshift-enterprise,openshift-origin -- Name: Syncing LDAP groups - File: ldap-syncing - Distros: openshift-enterprise,openshift-origin,openshift-dedicated -- Name: Creating and using config maps - File: configmaps - Distros: openshift-enterprise,openshift-origin,openshift-dedicated -- Name: Managing cloud provider credentials - Dir: managing_cloud_provider_credentials - Topics: - - Name: About the Cloud Credential Operator - File: about-cloud-credential-operator - - Name: Using mint mode - File: cco-mode-mint - - Name: Using passthrough mode - File: cco-mode-passthrough - - Name: Using manual mode - File: cco-mode-manual - - Name: Using manual mode with STS - File: cco-mode-sts ---- -Name: Networking -Dir: networking -Distros: openshift-enterprise,openshift-origin,openshift-dedicated -Topics: -- Name: Understanding networking - File: understanding-networking -- Name: Accessing hosts - File: accessing-hosts -- Name: Understanding the Cluster Network Operator - File: cluster-network-operator - Distros: openshift-enterprise,openshift-origin -- Name: Understanding the DNS Operator - File: dns-operator - Distros: openshift-enterprise,openshift-origin,openshift-dedicated -- Name: Understanding the Ingress Operator - File: ingress-operator - Distros: openshift-enterprise,openshift-origin -- Name: Verifying connectivity to an endpoint - File: verifying-connectivity-endpoint -- Name: Configuring the node port service range - File: configuring-node-port-service-range -- Name: Using SCTP - File: using-sctp - Distros: openshift-enterprise,openshift-origin -- Name: Configuring PTP hardware - File: configuring-ptp -- Name: Network policy - Dir: network_policy - Topics: - - Name: About network policy - File: about-network-policy - - Name: Creating a network policy - File: creating-network-policy - - Name: Viewing a network policy - File: viewing-network-policy - - Name: Editing a network policy - File: editing-network-policy - - Name: Deleting a network policy - File: deleting-network-policy - - Name: Defining a default network policy - File: default-network-policy - - Name: Configuring multitenant network policy - File: multitenant-network-policy -- Name: Multiple networks - Dir: multiple_networks - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Understanding multiple networks - File: understanding-multiple-networks - - Name: About virtual routing and forwarding - File: about-virtual-routing-and-forwarding - - Name: Attaching a pod to an additional network - File: attaching-pod - - Name: Removing a pod from an additional network - File: removing-pod - - Name: Configuring a bridge network - File: configuring-bridge - - Name: Configuring a host-device network - File: configuring-host-device - - Name: Configuring an ipvlan network - File: configuring-ipvlan - - Name: Configuring a macvlan network with basic customizations - File: configuring-macvlan-basic - - Name: Configuring a macvlan network - File: configuring-macvlan - - Name: Editing an additional network - File: edit-additional-network - - Name: Removing an additional network - File: remove-additional-network - - Name: Assigning a secondary network to a VRF - File: assigning-a-secondary-network-to-a-vrf -- Name: Hardware networks - Dir: hardware_networks - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: About Single Root I/O Virtualization (SR-IOV) hardware networks - File: about-sriov - - Name: Installing the SR-IOV Operator - File: installing-sriov-operator - - Name: Configuring the SR-IOV Operator - File: configuring-sriov-operator - - Name: Configuring an SR-IOV network device - File: configuring-sriov-device - - Name: Configuring an SR-IOV Ethernet network attachment - File: configuring-sriov-net-attach - - Name: Configuring an SR-IOV InfiniBand network attachment - File: configuring-sriov-ib-attach - - Name: Adding a pod to an SR-IOV network - File: add-pod - - Name: Using high performance multicast - File: using-sriov-multicast - - Name: Using DPDK and RDMA - File: using-dpdk-and-rdma -- Name: OpenShift SDN default CNI network provider - Dir: openshift_sdn - Topics: - - Name: About the OpenShift SDN default CNI network provider - File: about-openshift-sdn - - Name: Configuring egress IPs for a project - File: assigning-egress-ips - Distros: openshift-origin,openshift-enterprise - - Name: Configuring an egress firewall for a project - File: configuring-egress-firewall - - Name: Viewing an egress firewall for a project - File: viewing-egress-firewall - - Name: Editing an egress firewall for a project - File: editing-egress-firewall - - Name: Removing an egress firewall from a project - File: removing-egress-firewall - - Name: Considerations for the use of an egress router pod - File: using-an-egress-router - - Name: Deploying an egress router pod in redirect mode - File: deploying-egress-router-layer3-redirection - - Name: Deploying an egress router pod in HTTP proxy mode - File: deploying-egress-router-http-redirection - - Name: Deploying an egress router pod in DNS proxy mode - File: deploying-egress-router-dns-redirection - - Name: Configuring an egress router pod destination list from a config map - File: configuring-egress-router-configmap - - Name: Enabling multicast for a project - File: enabling-multicast - Distros: openshift-origin,openshift-enterprise - - Name: Disabling multicast for a project - File: disabling-multicast - Distros: openshift-origin,openshift-enterprise - - Name: Configuring multitenant isolation - File: multitenant-isolation - Distros: openshift-origin,openshift-enterprise - - Name: Configuring kube-proxy - File: configuring-kube-proxy - Distros: openshift-enterprise,openshift-origin -- Name: OVN-Kubernetes default CNI network provider - Dir: ovn_kubernetes_network_provider - Distros: openshift-origin,openshift-enterprise - Topics: - - Name: About the OVN-Kubernetes network provider - File: about-ovn-kubernetes - - Name: Migrate from the OpenShift SDN cluster network provider - File: migrate-from-openshift-sdn - - Name: Rollback to the OpenShift SDN cluster network provider - File: rollback-to-openshift-sdn - - Name: IPsec encryption configuration - File: about-ipsec-ovn - - Name: Configuring an egress firewall for a project - File: configuring-egress-firewall-ovn - - Name: Viewing an egress firewall for a project - File: viewing-egress-firewall-ovn - - Name: Editing an egress firewall for a project - File: editing-egress-firewall-ovn - - Name: Removing an egress firewall from a project - File: removing-egress-firewall-ovn - - Name: Configuring an egress IP address - File: configuring-egress-ips-ovn - - Name: Assigning an egress IP address - File: assigning-egress-ips-ovn - - Name: Considerations for the use of an egress router pod - File: using-an-egress-router-ovn - - Name: Deploying an egress router pod in redirect mode - File: deploying-egress-router-ovn-redirection - - Name: Enabling multicast for a project - File: enabling-multicast - - Name: Disabling multicast for a project - File: disabling-multicast - - Name: Configuring hybrid networking - File: configuring-hybrid-networking -- Name: Configuring Routes - Dir: routes - Topics: - - Name: Route configuration - File: route-configuration - - Name: Secured routes - File: secured-routes -- Name: Configuring ingress cluster traffic - Dir: configuring_ingress_cluster_traffic - Topics: - - Name: Overview - File: overview-traffic - Distros: openshift-enterprise,openshift-origin - - Name: Configuring ExternalIPs for services - File: configuring-externalip - Distros: openshift-enterprise,openshift-origin - - Name: Configuring ingress cluster traffic using an Ingress Controller - File: configuring-ingress-cluster-traffic-ingress-controller - - Name: Configuring ingress cluster traffic using a load balancer - File: configuring-ingress-cluster-traffic-load-balancer - Distros: openshift-enterprise,openshift-origin - - Name: Configuring ingress cluster traffic on AWS using a Network Load Balancer - File: configuring-ingress-cluster-traffic-aws-network-load-balancer - Distros: openshift-enterprise,openshift-origin - - Name: Configuring ingress cluster traffic using a service external IP - File: configuring-ingress-cluster-traffic-service-external-ip - Distros: openshift-enterprise,openshift-origin - - Name: Configuring ingress cluster traffic using a NodePort - File: configuring-ingress-cluster-traffic-nodeport - Distros: openshift-enterprise,openshift-origin - # Kubernetes NMState (TECHNOLOGY PREVIEW) -- Name: Kubernetes NMState - Dir: k8s_nmstate - Topics: - - Name: About the Kubernetes NMState Operator - File: k8s-nmstate-about-the-k8s-nmstate-operator - - Name: Observing node network state - File: k8s-nmstate-observing-node-network-state - - Name: Updating node network configuration - File: k8s-nmstate-updating-node-network-config - - Name: Troubleshooting node network configuration - File: k8s-nmstate-troubleshooting-node-network -- Name: Configuring the cluster-wide proxy - File: enable-cluster-wide-proxy - Distros: openshift-enterprise,openshift-origin -- Name: Configuring a custom PKI - File: configuring-a-custom-pki - Distros: openshift-enterprise,openshift-origin -- Name: Load balancing on OpenStack - File: load-balancing-openstack -- Name: Associating secondary interfaces metrics to network attachments - File: associating-secondary-interfaces-metrics-to-network-attachments ---- -Name: Storage -Dir: storage -Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -Topics: -- Name: Understanding ephemeral storage - File: understanding-ephemeral-storage - Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -- Name: Understanding persistent storage - File: understanding-persistent-storage - Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -- Name: Configuring persistent storage - Dir: persistent_storage - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Persistent storage using Amazon EFS - File: persistent-storage-efs - - Name: Persistent storage using AWS Elastic Block Store - File: persistent-storage-aws - - Name: Persistent storage using Azure Disk - File: persistent-storage-azure - - Name: Persistent storage using Azure File - File: persistent-storage-azure-file - - Name: Persistent storage using Cinder - File: persistent-storage-cinder - - Name: Persistent storage using Fibre Channel - File: persistent-storage-fibre - - Name: Persistent storage using FlexVolume - File: persistent-storage-flexvolume - - Name: Persistent storage using GCE Persistent Disk - File: persistent-storage-gce - - Name: Persistent storage using hostPath - File: persistent-storage-hostpath - - Name: Persistent Storage using iSCSI - File: persistent-storage-iscsi - - Name: Persistent storage using local volumes - File: persistent-storage-local - - Name: Persistent storage using NFS - File: persistent-storage-nfs - - Name: Persistent storage using Red Hat OpenShift Container Storage - File: persistent-storage-ocs - - Name: Persistent storage using VMware vSphere - File: persistent-storage-vsphere -- Name: Using Container Storage Interface (CSI) - Dir: container_storage_interface - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Configuring CSI volumes - File: persistent-storage-csi - - Name: CSI inline ephemeral volumes - File: ephemeral-storage-csi-inline - - Name: CSI volume snapshots - File: persistent-storage-csi-snapshots - - Name: CSI volume cloning - File: persistent-storage-csi-cloning - - Name: AWS Elastic Block Store CSI Driver Operator - File: persistent-storage-csi-ebs - - Name: GCP PD CSI Driver Operator - File: persistent-storage-csi-gcp-pd - - Name: OpenStack Cinder CSI Driver Operator - File: persistent-storage-csi-cinder - - Name: OpenStack Manila CSI Driver Operator - File: persistent-storage-csi-manila - - Name: Red Hat Virtualization CSI Driver Operator - File: persistent-storage-csi-ovirt -- Name: Expanding persistent volumes - File: expanding-persistent-volumes - Distros: openshift-enterprise,openshift-origin,openshift-dedicated -- Name: Dynamic provisioning - File: dynamic-provisioning - Distros: openshift-enterprise,openshift-origin ---- -Name: Registry -Dir: registry -Distros: openshift-enterprise,openshift-origin,openshift-dedicated -Topics: -- Name: Overview - File: architecture-component-imageregistry -- Name: Image Registry Operator in Openshift Container Platform - File: configuring-registry-operator - Distros: openshift-enterprise,openshift-origin -- Name: Setting up and configuring the registry - Dir: configuring_registry_storage - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Configuring the registry for AWS user-provisioned infrastructure - File: configuring-registry-storage-aws-user-infrastructure - - Name: Configuring the registry for GCP user-provisioned infrastructure - File: configuring-registry-storage-gcp-user-infrastructure -# - Name: Configuring the registry for OpenStack user-provisioned infrastructure -# File: configuring-registry-storage-openstack-user-infrastructure - - Name: Configuring the registry for Azure user-provisioned infrastructure - File: configuring-registry-storage-azure-user-infrastructure - - Name: Configuring the registry for bare metal - File: configuring-registry-storage-baremetal - - Name: Configuring the registry for vSphere - File: configuring-registry-storage-vsphere -- Name: Registry options - File: registry-options - Distros: openshift-enterprise,openshift-origin -- Name: Accessing the registry - File: accessing-the-registry -- Name: Exposing the registry - File: securing-exposing-registry - Distros: openshift-enterprise,openshift-origin ---- -Name: Operators -Dir: operators -Distros: openshift-enterprise,openshift-origin -Topics: -- Name: Understanding Operators - Dir: understanding - Topics: - - Name: What are Operators? - File: olm-what-operators-are - - Name: Packaging formats - File: olm-packaging-format - - Name: Common terms - File: olm-common-terms - - Name: Operator Lifecycle Manager (OLM) - Dir: olm - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Concepts - File: olm-understanding-olm - - Name: Architecture - File: olm-arch - - Name: Workflow - File: olm-workflow - - Name: Dependency resolution - File: olm-understanding-dependency-resolution - - Name: Operator groups - File: olm-understanding-operatorgroups - - Name: Operator conditions - File: olm-operatorconditions - - Name: Metrics - File: olm-understanding-metrics - - Name: Webhooks - File: olm-webhooks - - Name: OperatorHub - Distros: openshift-enterprise,openshift-origin - File: olm-understanding-operatorhub - - Name: CRDs - Dir: crds - Topics: - - Name: Extending the Kubernetes API with CRDs - File: crd-extending-api-with-crds - Distros: openshift-origin,openshift-enterprise - - Name: Managing resources from CRDs - File: crd-managing-resources-from-crds - Distros: openshift-origin,openshift-enterprise -- Name: User tasks - Dir: user - Topics: - - Name: Creating applications from installed Operators - File: olm-creating-apps-from-installed-operators - Distros: openshift-enterprise,openshift-origin,openshift-dedicated - - Name: Installing Operators in your namespace - File: olm-installing-operators-in-namespace - Distros: openshift-enterprise,openshift-origin -- Name: Administrator tasks - Dir: admin - Topics: - - Name: Adding Operators to a cluster - File: olm-adding-operators-to-cluster - Distros: openshift-enterprise,openshift-origin,openshift-dedicated - - Name: Upgrading installed Operators - File: olm-upgrading-operators - Distros: openshift-enterprise,openshift-origin,openshift-dedicated - - Name: Deleting Operators from a cluster - File: olm-deleting-operators-from-cluster - Distros: openshift-enterprise,openshift-origin,openshift-dedicated - - Name: Configuring proxy support - File: olm-configuring-proxy-support - Distros: openshift-enterprise,openshift-origin - - Name: Viewing Operator status - File: olm-status - Distros: openshift-enterprise,openshift-origin,openshift-dedicated - - Name: Managing Operator conditions - File: olm-managing-operatorconditions - Distros: openshift-origin,openshift-enterprise - - Name: Allowing non-cluster administrators to install Operators - File: olm-creating-policy - Distros: openshift-origin,openshift-enterprise - - Name: Managing custom catalogs - File: olm-managing-custom-catalogs - Distros: openshift-origin,openshift-enterprise - - Name: Using OLM on restricted networks - File: olm-restricted-networks - Distros: openshift-origin,openshift-enterprise -- Name: Developing Operators - Dir: operator_sdk - Distros: openshift-origin,openshift-enterprise - Topics: - - Name: About the Operator SDK - File: osdk-about - - Name: Installing the Operator SDK CLI - File: osdk-installing-cli - - Name: Go-based Operators - Dir: golang - Topics: - - Name: Getting started - File: osdk-golang-quickstart - - Name: Tutorial - File: osdk-golang-tutorial - - Name: Project layout - File: osdk-golang-project-layout - - Name: Ansible-based Operators - Dir: ansible - Topics: - - Name: Getting started - File: osdk-ansible-quickstart - - Name: Tutorial - File: osdk-ansible-tutorial - - Name: Project layout - File: osdk-ansible-project-layout - - Name: Ansible support - File: osdk-ansible-support - - Name: Kubernetes Collection for Ansible - File: osdk-ansible-k8s-collection - - Name: Using Ansible inside an Operator - File: osdk-ansible-inside-operator - - Name: Custom resource status management - File: osdk-ansible-cr-status - - Name: Helm-based Operators - Dir: helm - Topics: - - Name: Getting started - File: osdk-helm-quickstart - - Name: Tutorial - File: osdk-helm-tutorial - - Name: Project layout - File: osdk-helm-project-layout - - Name: Helm support - File: osdk-helm-support - - Name: Defining cluster service versions (CSVs) - File: osdk-generating-csvs - - Name: Working with bundle images - File: osdk-working-bundle-images - - Name: Validating Operators using the scorecard - File: osdk-scorecard - - Name: Configuring built-in monitoring with Prometheus - File: osdk-monitoring-prometheus - - Name: Configuring leader election - File: osdk-leader-election - - Name: Operator SDK CLI reference - File: osdk-cli-ref - - Name: Migrating to Operator SDK v0.1.0 - File: osdk-migrating-to-v0-1-0 - Distros: openshift-origin -- Name: Red Hat Operators reference - File: operator-reference ---- -Name: CI/CD -Dir: cicd -Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -Topics: -- Name: Builds - Dir: builds - Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online - Topics: - - Name: Understanding image builds - File: understanding-image-builds - - Name: Understanding build configurations - File: understanding-buildconfigs - - Name: Creating build inputs - File: creating-build-inputs - - Name: Managing build output - File: managing-build-output - - Name: Using build strategies - File: build-strategies - - Name: Custom image builds with Buildah - File: custom-builds-buildah - Distros: openshift-enterprise,openshift-origin - - Name: Performing basic builds - File: basic-build-operations - Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online - - Name: Triggering and modifying builds - File: triggering-builds-build-hooks - Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online - - Name: Performing advanced builds - File: advanced-build-operations - Distros: openshift-enterprise,openshift-origin - - Name: Using Red Hat subscriptions in builds - File: running-entitled-builds - Distros: openshift-enterprise,openshift-origin - - Name: Securing builds by strategy - File: securing-builds-by-strategy - Distros: openshift-enterprise,openshift-origin - - Name: Build configuration resources - File: build-configuration - Distros: openshift-enterprise,openshift-origin - - Name: Troubleshooting builds - File: troubleshooting-builds - Distros: openshift-enterprise,openshift-origin - - Name: Setting up additional trusted certificate authorities for builds - File: setting-up-trusted-ca - Distros: openshift-enterprise,openshift-origin,openshift-dedicated -- Name: Pipelines - Dir: pipelines - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Understanding OpenShift Pipelines - File: understanding-openshift-pipelines - - Name: Installing OpenShift Pipelines - File: installing-pipelines - - Name: Uninstalling OpenShift Pipelines - File: uninstalling-pipelines - - Name: Creating CI/CD solutions for applications using OpenShift Pipelines - File: creating-applications-with-cicd-pipelines - - Name: Working with Pipelines using the Developer perspective - File: working-with-pipelines-using-the-developer-perspective - - Name: OpenShift Pipelines release notes - File: op-release-notes -- Name: GitOps - Dir: gitops - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Understanding OpenShift GitOps - File: understanding-openshift-gitops - - Name: Getting started with OpenShift GitOps - File: getting-started-with-openshift-gitops ---- -Name: Images -Dir: openshift_images -Distros: openshift-enterprise,openshift-origin,openshift-dedicated,openshift-online -Topics: -- Name: Configuring the Cluster Samples Operator - File: configuring-samples-operator - Distros: openshift-enterprise,openshift-origin -- Name: Using the Cluster Samples Operator with an alternate registry - File: samples-operator-alt-registry - Distros: openshift-enterprise,openshift-origin -- Name: Understanding containers, images, and imagestreams - File: images-understand -- Name: Creating images - File: create-images -- Name: Managing images - Dir: managing_images - Topics: - - Name: Managing images overview - File: managing-images-overview - - Name: Tagging images - File: tagging-images - - Name: Image pull policy - File: image-pull-policy - - Name: Using image pull secrets - File: using-image-pull-secrets -- Name: Managing image streams - File: image-streams-manage - Distros: openshift-enterprise,openshift-origin -- Name: Using image streams with Kubernetes resources - File: using-imagestreams-with-kube-resources - Distros: openshift-enterprise,openshift-origin -- Name: Triggering updates on image stream changes - File: triggering-updates-on-imagestream-changes - Distros: openshift-enterprise,openshift-origin -- Name: Image configuration resources - File: image-configuration - Distros: openshift-enterprise,openshift-origin -- Name: Using templates - File: using-templates -- Name: Using Ruby on Rails - File: templates-using-ruby-on-rails -- Name: Using images - Dir: using_images - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Using images overview - File: using-images-overview - - Name: Configuring Jenkins images - File: images-other-jenkins - - Name: Jenkins agent - File: images-other-jenkins-agent ---- -Name: Applications -Dir: applications -Distros: openshift-enterprise,openshift-origin -Topics: -- Name: Projects - Dir: projects - Topics: - - Name: Working with projects - File: working-with-projects - - Name: Creating a project as another user - File: creating-project-other-user - Distros: openshift-enterprise,openshift-origin - - Name: Configuring project creation - File: configuring-project-creation - Distros: openshift-enterprise,openshift-origin -- Name: Application life cycle management - Dir: application_life_cycle_management - Topics: - - Name: Creating applications using the Developer perspective - File: odc-creating-applications-using-developer-perspective - - Name: Creating applications from installed Operators - File: creating-apps-from-installed-operators - - Name: Creating applications using the CLI - File: creating-applications-using-cli - - Name: Viewing application composition using the Topology view - File: odc-viewing-application-composition-using-topology-view - - Name: Editing applications - File: odc-editing-applications - - Name: Working with Helm charts using the Developer perspective - File: odc-working-with-helm-charts-using-developer-perspective - - Name: Deleting applications - File: odc-deleting-applications -- Name: Deployments - Dir: deployments - Topics: - - Name: Understanding Deployments and DeploymentConfigs - File: what-deployments-are - - Name: Managing deployment processes - File: managing-deployment-processes - - Name: Using deployment strategies - File: deployment-strategies - - Name: Using route-based deployment strategies - File: route-based-deployment-strategies -- Name: Quotas - Dir: quotas - Distros: openshift-origin,openshift-enterprise - Topics: - - Name: Resource quotas per project - File: quotas-setting-per-project - - Name: Resource quotas across multiple projects - File: quotas-setting-across-multiple-projects - Distros: openshift-enterprise,openshift-origin -- Name: Monitoring project and application metrics using the Developer perspective - File: odc-monitoring-project-and-application-metrics-using-developer-perspective -- Name: Monitoring application health - File: application-health -- Name: Working with quotas - File: working-with-quotas - Distros: openshift-online,openshift-dedicated -- Name: Idling applications - File: idling-applications - Distros: openshift-origin,openshift-enterprise -- Name: Pruning objects to reclaim resources - File: pruning-objects - Distros: openshift-origin,openshift-enterprise -- Name: Using the Red Hat Marketplace - File: red-hat-marketplace - Distros: openshift-origin,openshift-enterprise ---- -Name: Machine management -Dir: machine_management -Distros: openshift-origin,openshift-enterprise -Topics: -- Name: Creating machine sets - Dir: creating_machinesets - Distros: openshift-origin,openshift-enterprise - Topics: - - Name: Creating a machine set on AWS - File: creating-machineset-aws - - Name: Creating a machine set on Azure - File: creating-machineset-azure - - Name: Creating a machine set on GCP - File: creating-machineset-gcp - - Name: Creating a machine set on OpenStack - File: creating-machineset-osp - - Name: Creating a machine set on RHV - File: creating-machineset-rhv - Distros: openshift-enterprise - - Name: Creating a machine set on oVirt - File: creating-machineset-rhv - Distros: openshift-origin - - Name: Creating a machine set on vSphere - File: creating-machineset-vsphere -- Name: Manually scaling a machine set - File: manually-scaling-machineset -- Name: Modifying a machine set - File: modifying-machineset -- Name: Deleting a machine - File: deleting-machine -- Name: Applying autoscaling to a cluster - File: applying-autoscaling -- Name: Creating infrastructure machine sets - File: creating-infrastructure-machinesets -- Name: User-provisioned infrastructure - Dir: user_infra - Topics: - - Name: Adding a RHEL compute machine - File: adding-rhel-compute - Distros: openshift-enterprise - - Name: Adding more RHEL compute machines - File: more-rhel-compute - Distros: openshift-enterprise - - Name: Adding compute machines to vSphere - File: adding-vsphere-compute-user-infra - - Name: Adding compute machines to bare metal - File: adding-bare-metal-compute-user-infra -- Name: Deploying machine health checks - File: deploying-machine-health-checks ---- -Name: Nodes -Dir: nodes -Distros: openshift-enterprise,openshift-origin -Topics: -- Name: Working with pods - Dir: pods - Topics: - - Name: About Pods - File: nodes-pods-using - - Name: Viewing Pods - File: nodes-pods-viewing - - Name: Configuring a cluster for Pods - File: nodes-pods-configuring - Distros: openshift-enterprise,openshift-origin - - Name: Automatically scaling pods with the horizontal pod autoscaler - File: nodes-pods-autoscaling - - Name: Automatically adjust pod resource levels with the vertical pod autoscaler - File: nodes-pods-vertical-autoscaler - - Name: Providing sensitive data to Pods - File: nodes-pods-secrets - - Name: Using Device Manager to make devices available to nodes - File: nodes-pods-plugins - Distros: openshift-enterprise,openshift-origin - - Name: Including pod priority in Pod scheduling decisions - File: nodes-pods-priority - Distros: openshift-enterprise,openshift-origin - - Name: Placing pods on specific nodes using node selectors - File: nodes-pods-node-selectors - Distros: openshift-enterprise,openshift-origin -- Name: Controlling pod placement onto nodes (scheduling) - Dir: scheduling - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: About pod placement using the scheduler - File: nodes-scheduler-about - - Name: Configuring the default scheduler to control pod placement - File: nodes-scheduler-default - - Name: Scheduling pods using a scheduler profile - File: nodes-scheduler-profiles - - Name: Placing pods relative to other pods using pod affinity and anti-affinity rules - File: nodes-scheduler-pod-affinity - - Name: Controlling pod placement on nodes using node affinity rules - File: nodes-scheduler-node-affinity - - Name: Placing pods onto overcommited nodes - File: nodes-scheduler-overcommit - - Name: Controlling pod placement using node taints - File: nodes-scheduler-taints-tolerations - - Name: Placing pods on specific nodes using node selectors - File: nodes-scheduler-node-selectors - - Name: Controlling pod placement using pod topology spread constraints - File: nodes-scheduler-pod-topology-spread-constraints -# - Name: Placing a pod on a specific node by name -# File: nodes-scheduler-node-names -# - Name: Placing a pod in a specific project -# File: nodes-scheduler-node-projects -# - Name: Keeping your cluster balanced using the descheduler -# File: nodes-scheduler-descheduler - - Name: Evicting pods using the descheduler - File: nodes-descheduler -- Name: Using Jobs and DaemonSets - Dir: jobs - Topics: - - Name: Running background tasks on nodes automatically with daemonsets - File: nodes-pods-daemonsets - Distros: openshift-enterprise,openshift-origin - - Name: Running tasks in pods using jobs - File: nodes-nodes-jobs -- Name: Working with nodes - Dir: nodes - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Viewing and listing the nodes in your cluster - File: nodes-nodes-viewing - - Name: Working with nodes - File: nodes-nodes-working - - Name: Managing Nodes - File: nodes-nodes-managing - - Name: Managing the maximum number of Pods per Node - File: nodes-nodes-managing-max-pods - - Name: Using the Node Tuning Operator - File: nodes-node-tuning-operator - - Name: Understanding node rebooting - File: nodes-nodes-rebooting - - Name: Freeing node resources using garbage collection - File: nodes-nodes-garbage-collection - - Name: Allocating resources for nodes - File: nodes-nodes-resources-configuring - - Name: Allocating specific CPUs for nodes in a cluster - File: nodes-nodes-resources-cpus -# - Name: Monitoring for problems in your nodes -# File: nodes-nodes-problem-detector - - Name: Machine Config Daemon metrics - File: nodes-nodes-machine-config-daemon-metrics -- Name: Working with containers - Dir: containers - Topics: - - Name: Using containers - File: nodes-containers-using - - Name: Using Init Containers to perform tasks before a pod is deployed - File: nodes-containers-init - Distros: openshift-enterprise,openshift-origin - - Name: Using volumes to persist container data - File: nodes-containers-volumes - - Name: Mapping volumes using projected volumes - File: nodes-containers-projected-volumes - - Name: Allowing containers to consume API objects - File: nodes-containers-downward-api - - Name: Copying files to or from a container - File: nodes-containers-copying-files - - Name: Executing remote commands in a container - File: nodes-containers-remote-commands - - Name: Using port forwarding to access applications in a container - File: nodes-containers-port-forwarding - - Name: Using sysctls in containers - File: nodes-containers-sysctls -- Name: Working with clusters - Dir: clusters - Topics: - - Name: Viewing system event information in a cluster - File: nodes-containers-events - - Name: Analyzing cluster resource levels - File: nodes-cluster-resource-levels - Distros: openshift-enterprise,openshift-origin - - Name: Setting limit ranges - File: nodes-cluster-limit-ranges - - Name: Configuring cluster memory to meet container memory and risk requirements - File: nodes-cluster-resource-configure - Distros: openshift-enterprise,openshift-origin - - Name: Configuring your cluster to place pods on overcommited nodes - File: nodes-cluster-overcommit - Distros: openshift-enterprise,openshift-origin - - Name: Enabling features using FeatureGates - File: nodes-cluster-enabling-features - Distros: openshift-enterprise,openshift-origin -- Name: Remote worker nodes on the network edge - Dir: edge - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Using remote worker node at the network edge - File: nodes-edge-remote-workers ---- -Name: Windows Container Support for OpenShift -Dir: windows_containers -Distros: openshift-origin,openshift-enterprise -Topics: -- Name: Windows Container Support for OpenShift release notes - File: windows-containers-release-notes-2-x -- Name: Understanding Windows container workloads - File: understanding-windows-container-workloads -- Name: Enabling Windows container workloads - File: enabling-windows-container-workloads -- Name: Creating Windows MachineSet objects - Dir: creating_windows_machinesets - Topics: - - Name: Creating a Windows MachineSet object on AWS - File: creating-windows-machineset-aws - - Name: Creating a Windows MachineSet object on Azure - File: creating-windows-machineset-azure - - Name: Creating a Windows MachineSet object on vSphere - File: creating-windows-machineset-vsphere -- Name: Scheduling Windows container workloads - File: scheduling-windows-workloads -- Name: Windows node upgrades - File: windows-node-upgrades -- Name: Removing Windows nodes - File: removing-windows-nodes -- Name: Disabling Windows container workloads - File: disabling-windows-container-workloads ---- -Name: Sandboxed Container Support for OpenShift -Dir: sandboxed_containers -Distros: openshift-origin,openshift-enterprise -Topics: -- Name: Understanding OpenShift sandboxed containers - File: understanding-sandboxed-containers -- Name: Deploying sandboxed containers workloads - File: deploying-sandboxed-container-workloads -- Name: Disabling sandboxed container workloads - File: disabling-sandboxed-container-workloads ---- -Name: Logging -Dir: logging -Distros: openshift-enterprise,openshift-origin,openshift-dedicated -Topics: -- Name: Release notes - File: cluster-logging-release-notes -- Name: About Logging - File: cluster-logging -- Name: Installing Logging - File: cluster-logging-deploying - Distros: openshift-enterprise,openshift-origin -- Name: Installing the Logging and Elasticsearch Operators - File: dedicated-cluster-deploying - Distros: openshift-dedicated -- Name: Configuring your Logging deployment - Dir: config - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: About the Cluster Logging custom resource - File: cluster-logging-configuring-cr - - Name: Configuring the logging collector - File: cluster-logging-collector - - Name: Configuring the log store - File: cluster-logging-log-store - - Name: Configuring the log visualizer - File: cluster-logging-visualizer - - Name: Configuring Logging storage - File: cluster-logging-storage-considerations - - Name: Configuring CPU and memory limits for Logging components - File: cluster-logging-memory - - Name: Using tolerations to control Logging pod placement - File: cluster-logging-tolerations - - Name: Moving the Logging resources with node selectors - File: cluster-logging-moving-nodes - - Name: Configuring systemd-journald for Logging - File: cluster-logging-systemd - - Name: Configuring the log curator - File: cluster-logging-curator - - Name: Maintenance and support - File: cluster-logging-maintenance-support -- Name: Viewing logs for a specific resource - File: viewing-resource-logs -- Name: Viewing cluster logs in Kibana - File: cluster-logging-visualizer - Distros: openshift-enterprise,openshift-origin -# TODO: This file doesn't exist anymore - update if necessary for dedicated -# - Name: Viewing cluster logs using Kibana -# File: cluster-logging-kibana-interface -# Distros: openshift-dedicated -- Name: Forwarding logs to third party systems - File: cluster-logging-external - Distros: openshift-enterprise,openshift-origin -- Name: Collecting and storing Kubernetes events - File: cluster-logging-eventrouter - Distros: openshift-enterprise,openshift-origin -# - Name: Forwarding logs using ConfigMaps -# File: cluster-logging-external-configmap -# Distros: openshift-enterprise,openshift-origin -- Name: Updating Logging - File: cluster-logging-upgrading -- Name: Uninstalling Logging - File: cluster-logging-uninstall - Distros: openshift-dedicated -- Name: Viewing cluster dashboards - File: cluster-logging-dashboards -- Name: Troubleshooting Logging - Dir: troubleshooting - Distros: openshift-enterprise,openshift-origin - Topics: - - Name: Viewing Logging status - File: cluster-logging-cluster-status - - Name: Viewing the status of the log store - File: cluster-logging-log-store-status - - Name: Understanding Logging alerts - File: cluster-logging-alerts - - Name: Troubleshooting the log curator - File: cluster-logging-troubleshooting-curator - - Name: Collecting logging data for Red Hat Support - File: cluster-logging-must-gather -- Name: Uninstalling Logging - File: cluster-logging-uninstall -- Name: Exported fields - File: cluster-logging-exported-fields - Distros: openshift-enterprise,openshift-origin ---- -Name: Monitoring -Dir: monitoring -Distros: openshift-enterprise,openshift-origin -Topics: -- Name: Understanding the monitoring stack - File: understanding-the-monitoring-stack -- Name: Configuring the monitoring stack - File: configuring-the-monitoring-stack -- Name: Enabling monitoring for user-defined projects - File: enabling-monitoring-for-user-defined-projects -- Name: Managing metrics - File: managing-metrics -- Name: Managing alerts - File: managing-alerts -- Name: Reviewing monitoring dashboards - File: reviewing-monitoring-dashboards -- Name: Accessing third-party UIs - File: accessing-third-party-uis -- Name: Exposing custom application metrics for autoscaling - File: exposing-custom-application-metrics-for-autoscaling -- Name: Troubleshooting monitoring issues - File: troubleshooting-monitoring-issues ---- -Name: Metering -Dir: metering -Distros: openshift-enterprise -Topics: -- Name: About metering - File: metering-about-metering -- Name: Installing metering - File: metering-installing-metering -- Name: Upgrading metering - File: metering-upgrading-metering -- Name: Configuring metering - Dir: configuring_metering - Topics: - - Name: About configuring metering - File: metering-about-configuring - - Name: Common configuration options - File: metering-common-config-options - - Name: Configuring persistent storage - File: metering-configure-persistent-storage - - Name: Configuring the Hive metastore - File: metering-configure-hive-metastore - - Name: Configuring the reporting operator - File: metering-configure-reporting-operator - - Name: Configuring AWS billing correlation - File: metering-configure-aws-billing-correlation -- Name: Reports - Dir: reports - Topics: - - Name: About reports - File: metering-about-reports - - Name: Storage Locations - File: metering-storage-locations -- Name: Using metering - File: metering-using-metering -- Name: Examples of using metering - File: metering-usage-examples -- Name: Troubleshooting and debugging - File: metering-troubleshooting-debugging -- Name: Uninstalling metering - File: metering-uninstall ---- -Name: Scalability and performance -Dir: scalability_and_performance -Distros: openshift-origin,openshift-enterprise,openshift-webscale -Topics: -- Name: Recommended installation practices - File: recommended-install-practices - Distros: openshift-origin,openshift-enterprise -- Name: Recommended host practices - File: recommended-host-practices - Distros: openshift-origin,openshift-enterprise -- Name: Recommended cluster scaling practices - File: recommended-cluster-scaling-practices - Distros: openshift-origin,openshift-enterprise -- Name: Using the Node Tuning Operator - File: using-node-tuning-operator - Distros: openshift-origin,openshift-enterprise -- Name: Using Cluster Loader - File: using-cluster-loader - Distros: openshift-origin,openshift-enterprise -- Name: Using CPU Manager - File: using-cpu-manager - Distros: openshift-origin,openshift-enterprise -- Name: Using Topology Manager - File: using-topology-manager - Distros: openshift-origin,openshift-enterprise -- Name: Scaling the Cluster Monitoring Operator - File: scaling-cluster-monitoring-operator - Distros: openshift-origin,openshift-enterprise -- Name: Planning your environment according to object maximums - File: planning-your-environment-according-to-object-maximums - Distros: openshift-origin,openshift-enterprise -- Name: Optimizing storage - File: optimizing-storage - Distros: openshift-origin,openshift-enterprise -- Name: Optimizing routing - File: routing-optimization - Distros: openshift-origin,openshift-enterprise -- Name: Optimizing networking - File: optimizing-networking - Distros: openshift-origin,openshift-enterprise -- Name: What huge pages do and how they are consumed by apps - File: what-huge-pages-do-and-how-they-are-consumed-by-apps - Distros: openshift-origin,openshift-enterprise -- Name: Performance Addon Operator for low latency nodes - File: cnf-performance-addon-operator-for-low-latency-nodes - Distros: openshift-origin,openshift-enterprise - Distros: openshift-origin,openshift-enterprise -- Name: Provisioning and deploying a distributed unit (DU) - File: cnf-provisioning-and-deploying-a-distributed-unit - Distros: openshift-webscale ---- -Name: Backup and restore -Dir: backup_and_restore -Distros: openshift-origin,openshift-enterprise -Topics: -- Name: Backing up etcd data - File: backing-up-etcd -- Name: Replacing an unhealthy etcd member - File: replacing-unhealthy-etcd-member -- Name: Shutting down a cluster gracefully - File: graceful-cluster-shutdown -- Name: Restarting a cluster gracefully - File: graceful-cluster-restart -- Name: Disaster recovery - Dir: disaster_recovery - Topics: - - Name: About disaster recovery - File: about-disaster-recovery - - Name: Restoring to a previous cluster state - File: scenario-2-restoring-cluster-state - - Name: Recovering from expired control plane certificates - File: scenario-3-expired-certs ---- -Name: Migration Toolkit for Containers -Dir: migration -Distros: openshift-enterprise,openshift-origin -Topics: -- Name: Migrating from OpenShift Container Platform 3 - Dir: migrating_3_4 - Topics: - - Name: About migrating from OpenShift Container Platform 3 to 4 - File: about-migration - - Name: Planning your migration from OpenShift Container Platform 3 to 4 - File: planning-migration-3-to-4 - - Name: About the Migration Toolkit for Containers - File: migrating-application-workloads-3-4 - - Name: Deploying the Migration Toolkit for Containers - File: deploying-cam-3-4 - - Name: Upgrading the Migration Toolkit for Containers - File: upgrading-migration-tool-3-4 - - Name: Configuring a replication repository - File: configuring-replication-repository-3-4 - - Name: Migrating your applications - File: migrating-applications-with-cam-3-4 - - Name: Migrating your control plane settings - File: migrating-with-cpma - - Name: Troubleshooting - File: troubleshooting-3-4 -- Name: Migrating from OpenShift Container Platform 4.1 - Dir: migrating_4_1_4 - Distros: openshift-enterprise - Topics: - - Name: About the Migration Toolkit for Containers - File: migrating-application-workloads-4-1-4 - - Name: Deploying the Migration Toolkit for Containers - File: deploying-cam-4-1-4 - - Name: Upgrading the Migration Toolkit for Containers - File: upgrading-migration-tool-4-1-4 - - Name: Configuring a replication repository - File: configuring-replication-repository-4-1-4 - - Name: Migrating your applications - File: migrating-applications-with-cam-4-1-4 - - Name: Troubleshooting - File: troubleshooting-4-1-4 -- Name: Migrating from Openshift Container Platform 4.2 and later - Dir: migrating_4_2_4 - Distros: openshift-enterprise - Topics: - - Name: About the Migration Toolkit for Containers - File: migrating-application-workloads-4-2-4 - - Name: Deploying the Migration Toolkit for Containers - File: deploying-cam-4-2-4 - - Name: Upgrading the Migration Toolkit for Containers - File: upgrading-migration-tool-4-2-4 - - Name: Configuring a replication repository - File: configuring-replication-repository-4-2-4 - - Name: Migrating your applications - File: migrating-applications-with-cam-4-2-4 - - Name: Troubleshooting - File: troubleshooting-4-2-4 ---- -Name: API reference -Dir: rest_api -Distros: openshift-enterprise,openshift-origin -Topics: -- Name: API list - File: index -- Name: Common object reference - Dir: objects - Topics: - - Name: Index - File: index -- Name: Authorization APIs - Dir: authorization_apis - Topics: - - Name: About Authorization APIs - File: authorization-apis-index - - Name: 'LocalResourceAccessReview [authorization.openshift.io/v1]' - File: localresourceaccessreview-authorization-openshift-io-v1 - - Name: 'LocalSubjectAccessReview [authorization.openshift.io/v1]' - File: localsubjectaccessreview-authorization-openshift-io-v1 - - Name: 'ResourceAccessReview [authorization.openshift.io/v1]' - File: resourceaccessreview-authorization-openshift-io-v1 - - Name: 'SelfSubjectRulesReview [authorization.openshift.io/v1]' - File: selfsubjectrulesreview-authorization-openshift-io-v1 - - Name: 'SubjectAccessReview [authorization.openshift.io/v1]' - File: subjectaccessreview-authorization-openshift-io-v1 - - Name: 'SubjectRulesReview [authorization.openshift.io/v1]' - File: subjectrulesreview-authorization-openshift-io-v1 - - Name: 'TokenReview [authentication.k8s.io/v1]' - File: tokenreview-authentication-k8s-io-v1 - - Name: 'LocalSubjectAccessReview [authorization.k8s.io/v1]' - File: localsubjectaccessreview-authorization-k8s-io-v1 - - Name: 'SelfSubjectAccessReview [authorization.k8s.io/v1]' - File: selfsubjectaccessreview-authorization-k8s-io-v1 - - Name: 'SelfSubjectRulesReview [authorization.k8s.io/v1]' - File: selfsubjectrulesreview-authorization-k8s-io-v1 - - Name: 'SubjectAccessReview [authorization.k8s.io/v1]' - File: subjectaccessreview-authorization-k8s-io-v1 -- Name: Autoscale APIs - Dir: autoscale_apis - Topics: - - Name: About Autoscale APIs - File: autoscale-apis-index - - Name: 'ClusterAutoscaler [autoscaling.openshift.io/v1]' - File: clusterautoscaler-autoscaling-openshift-io-v1 - - Name: 'MachineAutoscaler [autoscaling.openshift.io/v1beta1]' - File: machineautoscaler-autoscaling-openshift-io-v1beta1 - - Name: 'HorizontalPodAutoscaler [autoscaling/v1]' - File: horizontalpodautoscaler-autoscaling-v1 -- Name: Config APIs - Dir: config_apis - Topics: - - Name: About Config APIs - File: config-apis-index - - Name: 'APIServer [config.openshift.io/v1]' - File: apiserver-config-openshift-io-v1 - - Name: 'Authentication [config.openshift.io/v1]' - File: authentication-config-openshift-io-v1 - - Name: 'Build [config.openshift.io/v1]' - File: build-config-openshift-io-v1 - - Name: 'ClusterOperator [config.openshift.io/v1]' - File: clusteroperator-config-openshift-io-v1 - - Name: 'ClusterVersion [config.openshift.io/v1]' - File: clusterversion-config-openshift-io-v1 - - Name: 'Console [config.openshift.io/v1]' - File: console-config-openshift-io-v1 - - Name: 'DNS [config.openshift.io/v1]' - File: dns-config-openshift-io-v1 - - Name: 'FeatureGate [config.openshift.io/v1]' - File: featuregate-config-openshift-io-v1 - - Name: 'HelmChartRepository [helm.openshift.io/v1beta1]' - File: helmchartrepository-helm-openshift-io-v1beta1 - - Name: 'Image [config.openshift.io/v1]' - File: image-config-openshift-io-v1 - - Name: 'Infrastructure [config.openshift.io/v1]' - File: infrastructure-config-openshift-io-v1 - - Name: 'Ingress [config.openshift.io/v1]' - File: ingress-config-openshift-io-v1 - - Name: 'Network [config.openshift.io/v1]' - File: network-config-openshift-io-v1 - - Name: 'OAuth [config.openshift.io/v1]' - File: oauth-config-openshift-io-v1 - - Name: 'OperatorHub [config.openshift.io/v1]' - File: operatorhub-config-openshift-io-v1 - - Name: 'Project [config.openshift.io/v1]' - File: project-config-openshift-io-v1 - - Name: 'Proxy [config.openshift.io/v1]' - File: proxy-config-openshift-io-v1 - - Name: 'Scheduler [config.openshift.io/v1]' - File: scheduler-config-openshift-io-v1 -- Name: Console APIs - Dir: console_apis - Topics: - - Name: About Console APIs - File: console-apis-index - - Name: 'ConsoleCLIDownload [console.openshift.io/v1]' - File: consoleclidownload-console-openshift-io-v1 - - Name: 'ConsoleExternalLogLink [console.openshift.io/v1]' - File: consoleexternalloglink-console-openshift-io-v1 - - Name: 'ConsoleLink [console.openshift.io/v1]' - File: consolelink-console-openshift-io-v1 - - Name: 'ConsoleNotification [console.openshift.io/v1]' - File: consolenotification-console-openshift-io-v1 - - Name: 'ConsoleQuickStart [console.openshift.io/v1]' - File: consolequickstart-console-openshift-io-v1 - - Name: 'ConsoleYAMLSample [console.openshift.io/v1]' - File: consoleyamlsample-console-openshift-io-v1 -- Name: Extension APIs - Dir: extension_apis - Topics: - - Name: About Extension APIs - File: extension-apis-index - - Name: 'APIService [apiregistration.k8s.io/v1]' - File: apiservice-apiregistration-k8s-io-v1 - - Name: 'CustomResourceDefinition [apiextensions.k8s.io/v1]' - File: customresourcedefinition-apiextensions-k8s-io-v1 - - Name: 'MutatingWebhookConfiguration [admissionregistration.k8s.io/v1]' - File: mutatingwebhookconfiguration-admissionregistration-k8s-io-v1 - - Name: 'ValidatingWebhookConfiguration [admissionregistration.k8s.io/v1]' - File: validatingwebhookconfiguration-admissionregistration-k8s-io-v1 -- Name: Image APIs - Dir: image_apis - Topics: - - Name: About Image APIs - File: image-apis-index - - Name: 'Image [image.openshift.io/v1]' - File: image-image-openshift-io-v1 - - Name: 'ImageSignature [image.openshift.io/v1]' - File: imagesignature-image-openshift-io-v1 - - Name: 'ImageStreamImage [image.openshift.io/v1]' - File: imagestreamimage-image-openshift-io-v1 - - Name: 'ImageStreamImport [image.openshift.io/v1]' - File: imagestreamimport-image-openshift-io-v1 - - Name: 'ImageStreamMapping [image.openshift.io/v1]' - File: imagestreammapping-image-openshift-io-v1 - - Name: 'ImageStream [image.openshift.io/v1]' - File: imagestream-image-openshift-io-v1 - - Name: 'ImageStreamTag [image.openshift.io/v1]' - File: imagestreamtag-image-openshift-io-v1 - - Name: 'ImageTag [image.openshift.io/v1]' - File: imagetag-image-openshift-io-v1 -- Name: Machine APIs - Dir: machine_apis - Topics: - - Name: About Machine APIs - File: machine-apis-index - - Name: 'ContainerRuntimeConfig [machineconfiguration.openshift.io/v1]' - File: containerruntimeconfig-machineconfiguration-openshift-io-v1 - - Name: 'ControllerConfig [machineconfiguration.openshift.io/v1]' - File: controllerconfig-machineconfiguration-openshift-io-v1 - - Name: 'KubeletConfig [machineconfiguration.openshift.io/v1]' - File: kubeletconfig-machineconfiguration-openshift-io-v1 - - Name: 'MachineConfigPool [machineconfiguration.openshift.io/v1]' - File: machineconfigpool-machineconfiguration-openshift-io-v1 - - Name: 'MachineConfig [machineconfiguration.openshift.io/v1]' - File: machineconfig-machineconfiguration-openshift-io-v1 - - Name: 'MachineHealthCheck [machine.openshift.io/v1beta1]' - File: machinehealthcheck-machine-openshift-io-v1beta1 - - Name: 'Machine [machine.openshift.io/v1beta1]' - File: machine-machine-openshift-io-v1beta1 - - Name: 'MachineSet [machine.openshift.io/v1beta1]' - File: machineset-machine-openshift-io-v1beta1 -- Name: Metadata APIs - Dir: metadata_apis - Topics: - - Name: About Metadata APIs - File: metadata-apis-index - - Name: 'Binding [core/v1]' - File: binding-core-v1 - - Name: 'ComponentStatus [core/v1]' - File: componentstatus-core-v1 - - Name: 'ConfigMap [core/v1]' - File: configmap-core-v1 - - Name: 'ControllerRevision [apps/v1]' - File: controllerrevision-apps-v1 - - Name: 'Event [events.k8s.io/v1]' - File: event-events-k8s-io-v1 - - Name: 'Event [core/v1]' - File: event-core-v1 - - Name: 'Lease [coordination.k8s.io/v1]' - File: lease-coordination-k8s-io-v1 - - Name: 'Namespace [core/v1]' - File: namespace-core-v1 -- Name: Monitoring APIs - Dir: monitoring_apis - Topics: - - Name: About Monitoring APIs - File: monitoring-apis-index - - Name: 'Alertmanager [monitoring.coreos.com/v1]' - File: alertmanager-monitoring-coreos-com-v1 - - Name: 'AlertmanagerConfig [monitoring.coreos.com/v1alpha1]' - File: alertmanagerconfig-monitoring-coreos-com-v1alpha1 - - Name: 'PodMonitor [monitoring.coreos.com/v1]' - File: podmonitor-monitoring-coreos-com-v1 - - Name: 'Probe [monitoring.coreos.com/v1]' - File: probe-monitoring-coreos-com-v1 - - Name: 'Prometheus [monitoring.coreos.com/v1]' - File: prometheus-monitoring-coreos-com-v1 - - Name: 'PrometheusRule [monitoring.coreos.com/v1]' - File: prometheusrule-monitoring-coreos-com-v1 - - Name: 'ServiceMonitor [monitoring.coreos.com/v1]' - File: servicemonitor-monitoring-coreos-com-v1 - - Name: 'ThanosRuler [monitoring.coreos.com/v1]' - File: thanosruler-monitoring-coreos-com-v1 -- Name: Network APIs - Dir: network_apis - Topics: - - Name: About Network APIs - File: network-apis-index - - Name: 'ClusterNetwork [network.openshift.io/v1]' - File: clusternetwork-network-openshift-io-v1 - - Name: 'Endpoints [core/v1]' - File: endpoints-core-v1 - - Name: 'EndpointSlice [discovery.k8s.io/v1beta1]' - File: endpointslice-discovery-k8s-io-v1beta1 - - Name: 'EgressNetworkPolicy [network.openshift.io/v1]' - File: egressnetworkpolicy-network-openshift-io-v1 - - Name: 'HostSubnet [network.openshift.io/v1]' - File: hostsubnet-network-openshift-io-v1 - - Name: 'Ingress [networking.k8s.io/v1]' - File: ingress-networking-k8s-io-v1 - - Name: 'IngressClass [networking.k8s.io/v1]' - File: ingressclass-networking-k8s-io-v1 - - Name: 'IPPool [whereabouts.cni.cncf.io/v1alpha1]' - File: ippool-whereabouts-cni-cncf-io-v1alpha1 - - Name: 'NetNamespace [network.openshift.io/v1]' - File: netnamespace-network-openshift-io-v1 - - Name: 'NetworkAttachmentDefinition [k8s.cni.cncf.io/v1]' - File: networkattachmentdefinition-k8s-cni-cncf-io-v1 - - Name: 'NetworkPolicy [networking.k8s.io/v1]' - File: networkpolicy-networking-k8s-io-v1 - - Name: 'PodNetworkConnectivityCheck [controlplane.operator.openshift.io/v1alpha1]' - File: podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1 - - Name: 'Route [route.openshift.io/v1]' - File: route-route-openshift-io-v1 - - Name: 'Service [core/v1]' - File: service-core-v1 -- Name: Node APIs - Dir: node_apis - Topics: - - Name: About Node APIs - File: node-apis-index - - Name: 'Node [core/v1]' - File: node-core-v1 - - Name: 'Profile [tuned.openshift.io/v1]' - File: profile-tuned-openshift-io-v1 - - Name: 'RuntimeClass [node.k8s.io/v1]' - File: runtimeclass-node-k8s-io-v1 - - Name: 'Tuned [tuned.openshift.io/v1]' - File: tuned-tuned-openshift-io-v1 -- Name: OAuth APIs - Dir: oauth_apis - Topics: - - Name: About OAuth APIs - File: oauth-apis-index - - Name: 'OAuthAccessToken [oauth.openshift.io/v1]' - File: oauthaccesstoken-oauth-openshift-io-v1 - - Name: 'OAuthAuthorizeToken [oauth.openshift.io/v1]' - File: oauthauthorizetoken-oauth-openshift-io-v1 - - Name: 'OAuthClientAuthorization [oauth.openshift.io/v1]' - File: oauthclientauthorization-oauth-openshift-io-v1 - - Name: 'OAuthClient [oauth.openshift.io/v1]' - File: oauthclient-oauth-openshift-io-v1 - - Name: 'UserOAuthAccessToken [oauth.openshift.io/v1]' - File: useroauthaccesstoken-oauth-openshift-io-v1 -- Name: Operator APIs - Dir: operator_apis - Topics: - - Name: About Operator APIs - File: operator-apis-index - - Name: 'Authentication [operator.openshift.io/v1]' - File: authentication-operator-openshift-io-v1 - - Name: 'CloudCredential [operator.openshift.io/v1]' - File: cloudcredential-operator-openshift-io-v1 - - Name: 'ClusterCSIDriver [operator.openshift.io/v1]' - File: clustercsidriver-operator-openshift-io-v1 - - Name: 'Console [operator.openshift.io/v1]' - File: console-operator-openshift-io-v1 - - Name: 'Config [operator.openshift.io/v1]' - File: config-operator-openshift-io-v1 - - Name: 'Config [imageregistry.operator.openshift.io/v1]' - File: config-imageregistry-operator-openshift-io-v1 - - Name: 'Config [samples.operator.openshift.io/v1]' - File: config-samples-operator-openshift-io-v1 - - Name: 'CSISnapshotController [operator.openshift.io/v1]' - File: csisnapshotcontroller-operator-openshift-io-v1 - - Name: 'DNS [operator.openshift.io/v1]' - File: dns-operator-openshift-io-v1 - - Name: 'DNSRecord [ingress.operator.openshift.io/v1]' - File: dnsrecord-ingress-operator-openshift-io-v1 - - Name: 'Etcd [operator.openshift.io/v1]' - File: etcd-operator-openshift-io-v1 - - Name: 'ImageContentSourcePolicy [operator.openshift.io/v1alpha1]' - File: imagecontentsourcepolicy-operator-openshift-io-v1alpha1 - - Name: 'ImagePruner [imageregistry.operator.openshift.io/v1]' - File: imagepruner-imageregistry-operator-openshift-io-v1 - - Name: 'IngressController [operator.openshift.io/v1]' - File: ingresscontroller-operator-openshift-io-v1 - - Name: 'KubeAPIServer [operator.openshift.io/v1]' - File: kubeapiserver-operator-openshift-io-v1 - - Name: 'KubeControllerManager [operator.openshift.io/v1]' - File: kubecontrollermanager-operator-openshift-io-v1 - - Name: 'KubeScheduler [operator.openshift.io/v1]' - File: kubescheduler-operator-openshift-io-v1 - - Name: 'KubeStorageVersionMigrator [operator.openshift.io/v1]' - File: kubestorageversionmigrator-operator-openshift-io-v1 - - Name: 'Network [operator.openshift.io/v1]' - File: network-operator-openshift-io-v1 - - Name: 'OpenShiftAPIServer [operator.openshift.io/v1]' - File: openshiftapiserver-operator-openshift-io-v1 - - Name: 'OpenShiftControllerManager [operator.openshift.io/v1]' - File: openshiftcontrollermanager-operator-openshift-io-v1 - - Name: 'OperatorPKI [network.operator.openshift.io/v1]' - File: operatorpki-network-operator-openshift-io-v1 - - Name: 'ServiceCA [operator.openshift.io/v1]' - File: serviceca-operator-openshift-io-v1 - - Name: 'Storage [operator.openshift.io/v1]' - File: storage-operator-openshift-io-v1 -- Name: OperatorHub APIs - Dir: operatorhub_apis - Topics: - - Name: About OperatorHub APIs - File: operatorhub-apis-index - - Name: 'CatalogSource [operators.coreos.com/v1alpha1]' - File: catalogsource-operators-coreos-com-v1alpha1 - - Name: 'ClusterServiceVersion [operators.coreos.com/v1alpha1]' - File: clusterserviceversion-operators-coreos-com-v1alpha1 - - Name: 'InstallPlan [operators.coreos.com/v1alpha1]' - File: installplan-operators-coreos-com-v1alpha1 - - Name: 'Operator [operators.coreos.com/v1]' - File: operator-operators-coreos-com-v1 - - Name: 'OperatorCondition [operators.coreos.com/v1]' - File: operatorcondition-operators-coreos-com-v1 - - Name: 'OperatorGroup [operators.coreos.com/v1]' - File: operatorgroup-operators-coreos-com-v1 - - Name: 'PackageManifest [packages.operators.coreos.com/v1]' - File: packagemanifest-packages-operators-coreos-com-v1 - - Name: 'Subscription [operators.coreos.com/v1alpha1]' - File: subscription-operators-coreos-com-v1alpha1 -- Name: Policy APIs - Dir: policy_apis - Topics: - - Name: About Policy APIs - File: policy-apis-index - - Name: 'PodDisruptionBudget [policy/v1beta1]' - File: poddisruptionbudget-policy-v1beta1 -- Name: Project APIs - Dir: project_apis - Topics: - - Name: About Project APIs - File: project-apis-index - - Name: 'Project [project.openshift.io/v1]' - File: project-project-openshift-io-v1 - - Name: 'ProjectRequest [project.openshift.io/v1]' - File: projectrequest-project-openshift-io-v1 -- Name: Provisioning APIs - Dir: provisioning_apis - Topics: - - Name: About Provisioning APIs - File: provisioning-apis-index - - Name: 'BareMetalHost [metal3.io/v1alpha1]' - File: baremetalhost-metal3-io-v1alpha1 - - Name: 'Provisioning [metal3.io/v1alpha1]' - File: provisioning-metal3-io-v1alpha1 -- Name: RBAC APIs - Dir: rbac_apis - Topics: - - Name: About RBAC APIs - File: rbac-apis-index - - Name: 'ClusterRoleBinding [rbac.authorization.k8s.io/v1]' - File: clusterrolebinding-rbac-authorization-k8s-io-v1 - - Name: 'ClusterRole [rbac.authorization.k8s.io/v1]' - File: clusterrole-rbac-authorization-k8s-io-v1 - - Name: 'RoleBinding [rbac.authorization.k8s.io/v1]' - File: rolebinding-rbac-authorization-k8s-io-v1 - - Name: 'Role [rbac.authorization.k8s.io/v1]' - File: role-rbac-authorization-k8s-io-v1 -- Name: Role APIs - Dir: role_apis - Topics: - - Name: About Role APIs - File: role-apis-index - - Name: 'ClusterRoleBinding [authorization.openshift.io/v1]' - File: clusterrolebinding-authorization-openshift-io-v1 - - Name: 'ClusterRole [authorization.openshift.io/v1]' - File: clusterrole-authorization-openshift-io-v1 - - Name: 'RoleBindingRestriction [authorization.openshift.io/v1]' - File: rolebindingrestriction-authorization-openshift-io-v1 - - Name: 'RoleBinding [authorization.openshift.io/v1]' - File: rolebinding-authorization-openshift-io-v1 - - Name: 'Role [authorization.openshift.io/v1]' - File: role-authorization-openshift-io-v1 -- Name: Schedule and quota APIs - Dir: schedule_and_quota_apis - Topics: - - Name: About Schedule and quota APIs - File: schedule-and-quota-apis-index - - Name: 'AppliedClusterResourceQuota [quota.openshift.io/v1]' - File: appliedclusterresourcequota-quota-openshift-io-v1 - - Name: 'ClusterResourceQuota [quota.openshift.io/v1]' - File: clusterresourcequota-quota-openshift-io-v1 - - Name: 'FlowSchema [flowcontrol.apiserver.k8s.io/v1alpha1]' - File: flowschema-flowcontrol-apiserver-k8s-io-v1alpha1 - - Name: 'LimitRange [core/v1]' - File: limitrange-core-v1 - - Name: 'PriorityClass [scheduling.k8s.io/v1]' - File: priorityclass-scheduling-k8s-io-v1 - - Name: 'PriorityLevelConfiguration [flowcontrol.apiserver.k8s.io/v1alpha1]' - File: prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1 - - Name: 'ResourceQuota [core/v1]' - File: resourcequota-core-v1 -- Name: Security APIs - Dir: security_apis - Topics: - - Name: About Security APIs - File: security-apis-index - - Name: 'CertificateSigningRequest [certificates.k8s.io/v1]' - File: certificatesigningrequest-certificates-k8s-io-v1 - - Name: 'CredentialsRequest [cloudcredential.openshift.io/v1]' - File: credentialsrequest-cloudcredential-openshift-io-v1 - - Name: 'PodSecurityPolicyReview [security.openshift.io/v1]' - File: podsecuritypolicyreview-security-openshift-io-v1 - - Name: 'PodSecurityPolicySelfSubjectReview [security.openshift.io/v1]' - File: podsecuritypolicyselfsubjectreview-security-openshift-io-v1 - - Name: 'PodSecurityPolicySubjectReview [security.openshift.io/v1]' - File: podsecuritypolicysubjectreview-security-openshift-io-v1 - - Name: 'RangeAllocation [security.openshift.io/v1]' - File: rangeallocation-security-openshift-io-v1 - - Name: 'Secret [core/v1]' - File: secret-core-v1 - - Name: 'SecurityContextConstraints [security.openshift.io/v1]' - File: securitycontextconstraints-security-openshift-io-v1 - - Name: 'ServiceAccount [core/v1]' - File: serviceaccount-core-v1 -- Name: Storage APIs - Dir: storage_apis - Topics: - - Name: About Storage APIs - File: storage-apis-index - - Name: 'CSIDriver [storage.k8s.io/v1]' - File: csidriver-storage-k8s-io-v1 - - Name: 'CSINode [storage.k8s.io/v1]' - File: csinode-storage-k8s-io-v1 - - Name: 'PersistentVolumeClaim [core/v1]' - File: persistentvolumeclaim-core-v1 - - Name: 'StorageClass [storage.k8s.io/v1]' - File: storageclass-storage-k8s-io-v1 - - Name: 'StorageState [migration.k8s.io/v1alpha1]' - File: storagestate-migration-k8s-io-v1alpha1 - - Name: 'StorageVersionMigration [migration.k8s.io/v1alpha1]' - File: storageversionmigration-migration-k8s-io-v1alpha1 - - Name: 'VolumeAttachment [storage.k8s.io/v1]' - File: volumeattachment-storage-k8s-io-v1 - - Name: 'VolumeSnapshot [snapshot.storage.k8s.io/v1]' - File: volumesnapshot-snapshot-storage-k8s-io-v1 - - Name: 'VolumeSnapshotClass [snapshot.storage.k8s.io/v1]' - File: volumesnapshotclass-snapshot-storage-k8s-io-v1 - - Name: 'VolumeSnapshotContent [snapshot.storage.k8s.io/v1]' - File: volumesnapshotcontent-snapshot-storage-k8s-io-v1 -- Name: Template APIs - Dir: template_apis - Topics: - - Name: About Template APIs - File: template-apis-index - - Name: 'BrokerTemplateInstance [template.openshift.io/v1]' - File: brokertemplateinstance-template-openshift-io-v1 - - Name: 'PodTemplate [core/v1]' - File: podtemplate-core-v1 - - Name: 'Template [template.openshift.io/v1]' - File: template-template-openshift-io-v1 - - Name: 'TemplateInstance [template.openshift.io/v1]' - File: templateinstance-template-openshift-io-v1 -- Name: User and group APIs - Dir: user_and_group_apis - Topics: - - Name: About User and group APIs - File: user-and-group-apis-index - - Name: 'Group [user.openshift.io/v1]' - File: group-user-openshift-io-v1 - - Name: 'Identity [user.openshift.io/v1]' - File: identity-user-openshift-io-v1 - - Name: 'UserIdentityMapping [user.openshift.io/v1]' - File: useridentitymapping-user-openshift-io-v1 - - Name: 'User [user.openshift.io/v1]' - File: user-user-openshift-io-v1 -- Name: Workloads APIs - Dir: workloads_apis - Topics: - - Name: About Workloads APIs - File: workloads-apis-index - - Name: 'BuildConfig [build.openshift.io/v1]' - File: buildconfig-build-openshift-io-v1 - - Name: 'Build [build.openshift.io/v1]' - File: build-build-openshift-io-v1 - - Name: 'CronJob [batch/v1beta1]' - File: cronjob-batch-v1beta1 - - Name: 'DaemonSet [apps/v1]' - File: daemonset-apps-v1 - - Name: 'Deployment [apps/v1]' - File: deployment-apps-v1 - - Name: 'DeploymentConfig [apps.openshift.io/v1]' - File: deploymentconfig-apps-openshift-io-v1 - - Name: 'Job [batch/v1]' - File: job-batch-v1 - - Name: 'Pod [core/v1]' - File: pod-core-v1 - - Name: 'ReplicationController [core/v1]' - File: replicationcontroller-core-v1 - - Name: 'PersistentVolume [core/v1]' - File: persistentvolume-core-v1 - - Name: 'ReplicaSet [apps/v1]' - File: replicaset-apps-v1 - - Name: 'StatefulSet [apps/v1]' - File: statefulset-apps-v1 ---- -Name: Service Mesh -Dir: service_mesh -Distros: openshift-enterprise -Topics: -- Name: Service Mesh 2.x - Dir: v2x - Topics: - - Name: Service Mesh 2.x release notes - File: servicemesh-release-notes - - Name: Service Mesh architecture - File: ossm-architecture - - Name: Service Mesh and Istio differences - File: ossm-vs-community - - Name: Preparing to install Service Mesh - File: preparing-ossm-installation - - Name: Installing Service Mesh - File: installing-ossm - - Name: Upgrading from 1.1 to 2.0 - File: upgrading-ossm - - Name: Customizing the installation - File: customizing-installation-ossm - - Name: Performance and scalability - File: ossm-performance-scalability - - Name: Deploying applications on Service Mesh - File: prepare-to-deploy-applications-ossm - - Name: Data visualization and observability - File: ossm-observability - - Name: Security - File: ossm-security - - Name: Traffic management - File: ossm-traffic-manage - - Name: Custom resources - File: ossm-custom-resources - - Name: Extensions - File: ossm-extensions - - Name: Using the 3scale Istio adapter - File: threescale-adapter - - Name: Removing Service Mesh - File: removing-ossm -- Name: Service Mesh 1.x - Dir: v1x - Topics: - - Name: Service Mesh 1.x release notes - File: servicemesh-release-notes - - Name: Service Mesh architecture - File: ossm-architecture - - Name: Service Mesh and Istio differences - File: ossm-vs-community - - Name: Preparing to install Service Mesh - File: preparing-ossm-installation - - Name: Installing Service Mesh - File: installing-ossm - - Name: Customizing the installation - File: customizing-installation-ossm - - Name: Deploying applications on Service Mesh - File: prepare-to-deploy-applications-ossm - - Name: Data visualization and observability - File: ossm-observability - - Name: Security - File: ossm-security - - Name: Traffic management - File: ossm-traffic-manage - - Name: Custom resources - File: ossm-custom-resources - - Name: Using the 3scale Istio adapter - File: threescale-adapter - - Name: Removing Service Mesh - File: removing-ossm ---- -Name: Jaeger -Dir: jaeger -Distros: openshift-enterprise -Topics: -- Name: Jaeger release notes - File: rhbjaeger-release-notes -- Name: Jaeger architecture - Dir: jaeger_arch - Topics: - - Name: Jaeger architecture - File: rhbjaeger-architecture -- Name: Jaeger installation - Dir: jaeger_install - Topics: - - Name: Installing Jaeger - File: rhbjaeger-installation - - Name: Configuring Jaeger - File: rhbjaeger-deploying - - Name: Upgrading Jaeger - File: rhbjaeger-updating - - Name: Removing Jaeger - File: rhbjaeger-removing ---- -Name: OpenShift Virtualization -Dir: virt -Distros: openshift-enterprise -Topics: -- Name: About OpenShift Virtualization - File: about-virt -- Name: OpenShift Virtualization release notes - File: virt-2-6-release-notes -- Name: Installing OpenShift Virtualization - Dir: install - Topics: - - Name: Preparing your OpenShift cluster for OpenShift Virtualization - File: preparing-cluster-for-virt - - Name: Specifying nodes for OpenShift Virtualization components - File: virt-specifying-nodes-for-virtualization-components - - Name: Installing OpenShift Virtualization using the web console - File: installing-virt-web - - Name: Installing OpenShift Virtualization using the CLI - File: installing-virt-cli - - Name: Installing the virtctl client - File: virt-installing-virtctl - - Name: Uninstalling OpenShift Virtualization using the web console - File: uninstalling-virt-web - - Name: Uninstalling OpenShift Virtualization using the CLI - File: uninstalling-virt-cli -- Name: Upgrading OpenShift Virtualization - File: upgrading-virt -- Name: Additional security privileges granted for kubevirt-controller and virt-launcher - File: virt-additional-security-privileges-controller-and-launcher -- Name: Using the CLI tools - File: virt-using-the-cli-tools -- Name: Virtual machines - Dir: virtual_machines - Topics: -###VIRTUAL MACHINE CHESS SALAD (silly name to highlight that the commented out assemblies need to be checked against merged filenams) - - Name: Creating virtual machines - File: virt-create-vms - - Name: Editing virtual machines - File: virt-edit-vms - - Name: Editing boot order - File: virt-edit-boot-order - - Name: Deleting virtual machines - File: virt-delete-vms - - Name: Managing virtual machine instances - File: virt-manage-vmis - - Name: Controlling virtual machines states - File: virt-controlling-vm-states - - Name: Accessing virtual machine consoles - File: virt-accessing-vm-consoles - - Name: Triggering virtual machine failover by resolving a failed node - File: virt-triggering-vm-failover-resolving-failed-node - - Name: Installing the QEMU guest agent on virtual machines - File: virt-installing-qemu-guest-agent - - Name: Viewing the QEMU guest agent information for virtual machines - File: virt-viewing-qemu-guest-agent-web - - Name: Managing config maps, secrets, and service accounts in virtual machines - File: virt-managing-configmaps-secrets-service-accounts - - Name: Installing VirtIO driver on an existing Windows virtual machine - File: virt-installing-virtio-drivers-on-existing-windows-vm - - Name: Installing VirtIO driver on a new Windows virtual machine - File: virt-installing-virtio-drivers-on-new-windows-vm - - Name: Advanced virtual machine management - Dir: advanced_vm_management - Topics: -#Advanced virtual machine configuration - - Name: Automating management tasks - File: virt-automating-management-tasks - - Name: EFI mode for virtual machines - File: virt-efi-mode-for-vms - - Name: Configuring PXE booting for virtual machines - File: virt-configuring-pxe-booting - - Name: Managing guest memory - File: virt-managing-guest-memory - - Name: Using huge pages with virtual machines - File: virt-using-huge-pages-with-vms - - Name: Enabling dedicated resources for a virtual machine - File: virt-dedicated-resources-vm - - Name: Scheduling virtual machines - File: virt-schedule-vms -# Importing virtual machines - - Name: Importing virtual machines - Dir: importing_vms - Topics: - - Name: TLS certificates for data volume imports - File: virt-tls-certificates-for-dv-imports - - Name: Importing virtual machine images with data volumes - File: virt-importing-virtual-machine-images-datavolumes - - Name: Importing virtual machine images to block storage with data volumes - File: virt-importing-virtual-machine-images-datavolumes-block - - Name: Importing a Red Hat Virtualization virtual machine - File: virt-importing-rhv-vm - - Name: Importing a VMware virtual machine or template - File: virt-importing-vmware-vm -# Cloning virtual machines - - Name: Cloning virtual machines - Dir: cloning_vms - Topics: - - Name: Enabling user permissions to clone data volumes across namespaces - File: virt-enabling-user-permissions-to-clone-datavolumes - - Name: Cloning a virtual machine disk into a new data volume - File: virt-cloning-vm-disk-into-new-datavolume - - Name: Cloning a virtual machine by using a data volume template - File: virt-cloning-vm-using-datavolumetemplate - - Name: Cloning a virtual machine disk into a new block storage data volume - File: virt-cloning-vm-disk-into-new-datavolume-block -# Virtual machine networking - - Name: Virtual machine networking - Dir: vm_networking - Topics: - - Name: Using the default pod network with OpenShift Virtualization - File: virt-using-the-default-pod-network-with-virt - - Name: Attaching a virtual machine to multiple networks - File: virt-attaching-vm-multiple-networks - - Name: Configuring IP addresses for virtual machines - File: virt-configuring-ip-for-vms - - Name: Configuring an SR-IOV network device for virtual machines - File: virt-configuring-sriov-device-for-vms - - Name: Defining an SR-IOV network - File: virt-defining-an-sriov-network - - Name: Attaching a virtual machine to an SR-IOV network - File: virt-attaching-vm-to-sriov-network - - Name: Viewing the IP address of NICs on a virtual machine - File: virt-viewing-ip-of-vm-nic - - Name: Using a MAC address pool for virtual machines - File: virt-using-mac-address-pool-for-vms -#A BETTER NAME THAN 'STORAGE 4 U' - - Name: Virtual machine disks - Dir: virtual_disks - Topics: - - Name: Features for storage - File: virt-features-for-storage - - Name: Configuring local storage for virtual machines - File: virt-configuring-local-storage-for-vms - - Name: Reserving PVC space for file system overhead - File: virt-reserving-pvc-space-fs-overhead - - Name: Configuring CDI to work with namespaces that have a compute resource quota - File: virt-configuring-cdi-for-namespace-resourcequota - - Name: Using preallocation for data volumes - File: virt-using-preallocation-for-datavolumes - - Name: Uploading local disk images by using the web console - File: virt-uploading-local-disk-images-web - - Name: Uploading local disk images by using the virtctl tool - File: virt-uploading-local-disk-images-virtctl - - Name: Uploading a local disk image to a block storage data volume - File: virt-uploading-local-disk-images-block - - Name: Managing offline virtual machine snapshots - File: virt-managing-offline-vm-snapshots - - Name: Moving a local virtual machine disk to a different node - File: virt-moving-local-vm-disk-to-different-node - - Name: Expanding virtual storage by adding blank disk images - File: virt-expanding-virtual-storage-with-blank-disk-images - - Name: Cloning a data volume using smart-cloning - File: virt-cloning-a-datavolume-using-smart-cloning - - Name: Storage defaults for data volumes - File: virt-storage-defaults-for-datavolumes - - Name: Creating and using boot sources - File: virt-creating-and-using-boot-sources - - Name: Using container disks with virtual machines - File: virt-using-container-disks-with-vms - - Name: Preparing CDI scratch space - File: virt-preparing-cdi-scratch-space - - Name: Re-using statically provisioned persistent volumes - File: virt-reusing-statically-provisioned-persistent-volumes - - Name: Deleting data volumes - File: virt-deleting-datavolumes -# Templates -- Name: Virtual machine templates - Dir: vm_templates - Topics: - - Name: Creating virtual machine templates - File: virt-creating-vm-template - - Name: Editing a virtual machine template - File: virt-editing-vm-template - - Name: Enabling dedicated resources for a virtual machine template - File: virt-dedicated-resources-vm-template - - Name: Deleting a virtual machine template - File: virt-deleting-vm-template -# Virtual machine live migration -- Name: Live migration - Dir: live_migration - Topics: - - Name: Virtual machine live migration - File: virt-live-migration - - Name: Live migration limits and timeouts - File: virt-live-migration-limits - - Name: Migrating a virtual machine instance to another node - File: virt-migrate-vmi - - Name: Monitoring live migration of a virtual machine instance - File: virt-monitor-vmi-migration - - Name: Cancelling the live migration of a virtual machine instance - File: virt-cancel-vmi-migration - - Name: Configuring virtual machine eviction strategy - File: virt-configuring-vmi-eviction-strategy -# Node maintenance mode -- Name: Node maintenance - Dir: node_maintenance - Topics: - - Name: Automatic renewal of TLS certificates - File: virt-automatic-certificates - - Name: Managing node labeling for obsolete CPU models - File: virt-managing-node-labeling-obsolete-cpu-models - - Name: Node maintenance mode - File: virt-node-maintenance - - Name: Setting a node to maintenance mode - File: virt-setting-node-maintenance - - Name: Resuming a node from maintenance mode - File: virt-resuming-node -# Node Networking -- Name: Node networking - Dir: node_network - Topics: - - Name: Observing node network state - File: virt-observing-node-network-state - - Name: Updating node network configuration - File: virt-updating-node-network-config - - Name: Troubleshooting node network configuration - File: virt-troubleshooting-node-network -# Logging, events, and monitoring -- Name: Logging, events, and monitoring - Dir: logging_events_monitoring - Topics: - - Name: Viewing logs - File: virt-logs - - Name: Viewing events - File: virt-events - - Name: Diagnosing data volumes using events and conditions - File: virt-diagnosing-datavolumes-using-events-and-conditions - - Name: Viewing information about virtual machine workloads - File: virt-viewing-information-about-vm-workloads - - Name: Monitoring virtual machine health - File: virt-monitoring-vm-health - - Name: Viewing cluster information - File: virt-using-dashboard-to-get-cluster-info - - Name: OpenShift cluster monitoring, logging, and Telemetry - File: virt-openshift-cluster-monitoring - - Name: Collecting OpenShift Virtualization data for Red Hat Support - File: virt-collecting-virt-data ---- -# OpenShift Serverless -Name: Serverless -Dir: serverless -Distros: openshift-enterprise -Topics: -# Release notes -- Name: Release Notes - File: serverless-release-notes -# Support -- Name: Support - File: serverless-support -# Intro / getting started -- Name: Getting started - File: serverless-getting-started -- Name: Installing the Knative CLI - File: installing-kn -# Admin guide -- Name: Administration guide - Dir: admin_guide - Topics: - #Installation - - Name: Installing OpenShift Serverless - File: installing-openshift-serverless - - Name: Installing Knative Serving - File: installing-knative-serving - - Name: Installing Knative Eventing - File: installing-knative-eventing - - Name: Advanced installation configuration options - File: serverless-install-config-options - - Name: Upgrading the OpenShift Serverless Operator - File: upgrading-serverless - - Name: Removing OpenShift Serverless - File: removing-openshift-serverless - # Eventing - - Name: Creating Eventing components - File: serverless-cluster-admin-eventing - # Serving - - Name: Creating Serving components - File: serverless-cluster-admin-serving - # Metering - - Name: Using metering with OpenShift Serverless - File: serverless-metering -# Architecture -- Name: Architecture - Dir: architecture - Topics: - - Name: Knative Serving - File: serverless-serving-architecture - - Name: Knative Eventing - File: serverless-event-architecture -# Apps -- Name: Creating and managing serverless applications - File: serving-creating-managing-apps -# HA -- Name: High availability on OpenShift Serverless - File: serverless-HA -# Tracing -- Name: Tracing requests - File: serverless-tracing -# Knative Serving -- Name: Knative Serving - Dir: knative_serving - Topics: -# Knative services - - Name: Configuring Knative Serving autoscaling - File: configuring-knative-serving-autoscaling - - Name: Cluster logging with OpenShift Serverless - File: cluster-logging-serverless - - Name: Splitting traffic between revisions - File: splitting-traffic-between-revisions-knative -# Knative Eventing -- Name: Knative Eventing workflows - Dir: event_workflows - Topics: -# Brokers - - Name: Broker and trigger workflows - File: serverless-using-brokers -# Channels - - Name: Channel workflows - File: serverless-channels -# Subscriptions - - Name: Using subscriptions - File: serverless-subs -# Event delivery - - Name: Event delivery - File: serverless-event-delivery -# Event sources -- Name: Event sources - Dir: event_sources - Topics: - - Name: Getting started with event sources - File: knative-event-sources - - Name: Listing event sources and event source types - File: serverless-listing-event-sources - - Name: Using ApiServerSource - File: serverless-apiserversource - - Name: Using PingSource - File: serverless-pingsource - - Name: Using SinkBinding - File: serverless-sinkbinding - - Name: Using a Kafka source - File: serverless-kafka-source -# Knative Kafka -- Name: Using Apache Kafka with OpenShift Serverless - File: serverless-kafka -# Networking -- Name: Networking - Dir: networking - Topics: - - Name: Mapping a custom domain name to a Knative service - File: serverless-domain-mapping - - Name: Configuring routes for Knative services - File: serverless-configuring-routes - - Name: Using Service Mesh with OpenShift Serverless - File: serverless-ossm - - Name: Using JSON Web Token authentication with Service Mesh and OpenShift Serverless - File: serverless-ossm-jwt - - Name: Using custom domains for Knative services with Service Mesh - File: serverless-ossm-custom-domains - - Name: Configuring TLS for a custom domain using Service Mesh - File: serverless-ossm-tls -# Monitoring -- Name: Monitoring - Dir: monitoring - Topics: - - Name: Monitoring serverless components - File: serverless-monitoring -# Integrations -- Name: Integrations - Dir: integrations - Topics: - - Name: Using NVIDIA GPU resources with serverless applications - File: gpu-resources diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml new file mode 100644 index 000000000000..89ae19f0d4a5 --- /dev/null +++ b/_topic_maps/_topic_map.yml @@ -0,0 +1,801 @@ +# This configuration file dictates the organization of the topic groups and +# topics on the main page of the doc site for this branch. Each record +# consists of the following: +# +# --- <= Record delimiter +# Name: Origin of the Species <= Display name of topic group +# Dir: origin_of_the_species <= Directory name of topic group +# Topics: +# - Name: The Majestic Marmoset <= Topic name +# File: the_majestic_marmoset <= Topic file under group dir +/- +# - Name: The Curious Crocodile <= Topic 2 name +# File: the_curious_crocodile <= Topic 2 file +# - Name: The Numerous Nematodes <= Sub-topic group name +# Dir: the_numerous_nematodes <= Sub-topic group dir +# Topics: +# - Name: The Wily Worm <= Sub-topic name +# File: the_wily_worm <= Sub-topic file under / +# - Name: The Acrobatic Ascarid <= Sub-topic 2 name +# File: the_acrobatic_ascarid <= Sub-topic 2 file under / +# +# The ordering of the records in this document determines the ordering of the +# topic groups and topics on the main page. + +--- +Name: About +Dir: welcome +Distros: openshift-acs +Topics: +- Name: Welcome + File: index +--- +Name: Release notes +Dir: release_notes +Distros: openshift-acs +Topics: +- Name: Red Hat Advanced Cluster Security for Kubernetes 4.8 + File: 48-release-notes +--- +Name: RHACS Cloud Service +Dir: cloud_service +Distros: openshift-acs +Topics: +- Name: Service description + File: rhacs-cloud-service-service-description +- Name: Overview of responsibilities for RHACS Cloud Service + File: acs-cloud-responsibility-matrix +- Name: RHACS Cloud Service architecture + File: acscs-architecture +- Name: Getting started with RHACS Cloud Service + File: getting-started-rhacs-cloud-ocp +- Name: Default resource requirements for RHACS Cloud Service + File: acscs-default-requirements +- Name: Recommended resource requirements for RHACS Cloud Service + File: acscs-recommended-requirements +- Name: Setting up RHACS Cloud Service with Red Hat OpenShift secured clusters + Dir: installing_cloud_ocp + Distros: openshift-acs + Topics: + - Name: Creating a RHACS Cloud Service instance on Red Hat Cloud + File: cloud-create-instance-ocp + - Name: Creating a project on your Red Hat OpenShift secured cluster + File: cloud-ocp-create-project + - Name: Generating an init bundle or cluster registration secret for secured clusters + File: init-bundle-cloud-ocp-generate + - Name: Applying an init bundle or cluster registration secret for secured clusters + File: init-bundle-cloud-ocp-apply + - Name: Installing the RHACS Operator for RHACS Cloud Service + File: cloud-install-operator + - Name: Installing secured cluster services from RHACS Cloud Service + File: install-secured-cluster-cloud-ocp + - Name: Configuring the proxy for secured cluster services in RHACS Cloud Service + File: configuring-the-proxy-for-secured-cluster-services-in-rhacs-cloud-service + - Name: Verifying installation of secured clusters + File: verify-installation-cloud-ocp +- Name: Setting up RHACS Cloud Service with Kubernetes secured clusters + Dir: installing_cloud_other + Distros: openshift-acs + Topics: + - Name: Creating a RHACS Cloud Service instance for Kubernetes clusters + File: cloud-create-instance-other + - Name: Generating an init bundle for Kubernetes secured clusters + File: init-bundle-cloud-other-generate + - Name: Applying an init bundle for Kubernetes secured clusters + File: init-bundle-cloud-other-apply + - Name: Installing secured cluster services from RHACS Cloud Service on Kubernetes clusters + File: install-secured-cluster-cloud-other + - Name: Verifying installation of secured clusters + File: verify-installation-cloud-other +- Name: Upgrading RHACS Cloud Service + Dir: upgrading-cloud + Distros: openshift-acs + Topics: + - Name: Upgrading secured clusters in RHACS Cloud Service by using the Operator + File: upgrade-cloudsvc-operator + - Name: Upgrading secured clusters in RHACS Cloud Service by using Helm charts + File: upgrade-cloudsvc-helm + - Name: Upgrading secured clusters in RHACS Cloud Service by using the roxctl CLI + File: upgrade-cloudsvc-roxctl +--- +Name: Architecture +Dir: architecture +Distros: openshift-acs +Topics: +- Name: RHACS architecture + File: acs-architecture +--- +Name: Installing +Dir: installing +Distros: openshift-acs +Topics: +- Name: High-level RHACS installation overview + File: acs-high-level-overview + Distros: openshift-acs +- Name: Default resource requirements for RHACS + File: acs-default-requirements + Distros: openshift-acs +- Name: Recommended resource requirements for RHACS + File: acs-recommended-requirements + Distros: openshift-acs +- Name: Installing RHACS on Red Hat OpenShift + Dir: installing_ocp + Distros: openshift-acs + Topics: + - Name: Installing Central services for RHACS on Red Hat OpenShift + File: install-central-ocp + - Name: Configuring Central configuration options for RHACS using the Operator + File: install-central-config-options-ocp + - Name: Generating and applying an init bundle or cluster registration secret for RHACS on Red Hat OpenShift + File: init-bundle-ocp + - Name: Installing Secured Cluster services for RHACS on Red Hat OpenShift + File: install-secured-cluster-ocp + - Name: Configuring Secured Cluster services options for RHACS using the Operator + File: install-secured-cluster-config-options-ocp + - Name: Verifying installation of RHACS on Red Hat OpenShift + File: verify-installation-rhacs-ocp +- Name: Installing RHACS on other platforms + Dir: installing_other + Distros: openshift-acs + Topics: + - Name: High-level overview of installing RHACS on other platforms + File: install-rhacs-other + - Name: Installing Central services for RHACS on other platforms + File: install-central-other + - Name: Generating and applying an init bundle or cluster registration secret for RHACS on other platforms + File: init-bundle-other + - Name: Installing Secured Cluster services for RHACS on other platforms + File: install-secured-cluster-other + - Name: Verifying installation of RHACS on other platforms + File: verify-installation-rhacs-other +- Name: Uninstalling Red Hat Advanced Cluster Security for Kubernetes + File: uninstall-acs +--- +Name: Configuring +Dir: configuration +Distros: openshift-acs +Topics: +- Name: Adding custom certificates + File: add-custom-certificates +- Name: Adding trusted certificate authorities + File: add-trusted-ca +- Name: Internal certificate authority rotation for RHACS + File: internal-certificate-authority-rotation-for-rhacs +- Name: Reissuing internal certificates + File: reissue-internal-certificates +- Name: Adding security notices + File: add-security-notices +- Name: Customizing platform components + File: customizing-platform-components +- Name: Enabling offline mode + File: enable-offline-mode +- Name: Enabling alert data retention + File: enable-alert-data-retention +- Name: Exposing the RHACS portal over HTTP + File: expose-portal-over-http +- Name: Configuring automatic upgrades for manifest-installed secured clusters + File: configure-automatic-upgrades +- Name: Configuring automatic removal of nonactive clusters + File: configure-inactive-cluster-deletion +- Name: Configuring a proxy for external network access + File: configure-proxy +- Name: Generating a diagnostic bundle + File: generate-diagnostic-bundle +- Name: Configuring endpoints + File: configure-endpoints +- Name: Monitoring + File: monitor-acs +- Name: Enabling audit logging + File: configure-audit-logging +- Name: Configuring API tokens + File: configure-api-token +- Name: Using RHACS with GitOps + File: using-rhacs-with-gitops +- Name: Using declarative configuration + File: declarative-configuration-using +- Name: Inviting users to your RHACS instance + File: inviting-users-to-your-rhacs-instance +- Name: Managing preview features + File: managing-preview-features +- Name: Configuring and integrating the RHACS plugin with Red Hat Developer Hub + File: configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub +--- +Name: Operating +Dir: operating +Distros: openshift-acs +Topics: +- Name: Viewing the dashboard + File: view-dashboard +- Name: Using Compliance Operator with RHACS + File: compliance-operator-rhacs +- Name: Managing compliance + Dir: manage-compliance + Topics: + - Name: Compliance feature overview + File: compliance-feature-overview + - Name: Using the compliance dashboard (deprecated) + File: using-the-compliance-dashboard + - Name: Using OpenShift compliance + File: using-openshift-compliance +- Name: Evaluating security risks + File: evaluate-security-risks +- Name: Using policies to provide security + Dir: manage_security_policies + Distros: openshift-acs + Topics: + - Name: About policies in RHACS + File: about-security-policies + - Name: Creating and modifying security policies + File: custom-security-policies + - Name: Using admission controller enforcement + File: use-admission-controller-enforcement + - Name: Managing policies as code + File: managing-policies-as-code + - Name: Security policy reference + File: security-policy-reference +- Name: Managing network policies + File: manage-network-policies +- Name: Build-time network policy tools + File: build-time-network-policy-tools +- Name: Visualizing external entities + File: visualizing-external-entities +- Name: Using Collector runtime configuration + File: using-collector-runtime-configuration +- Name: Auditing listening endpoints + File: audit-listening-endpoints +- Name: Reviewing cluster configuration + File: review-cluster-configuration +- Name: Examining images for vulnerabilities + File: examine-images-for-vulnerabilities +- Name: Verifying image signatures + File: verify-image-signatures +- Name: Managing vulnerabilities + Dir: manage-vulnerabilities + Topics: + - Name: Vulnerability management overview + File: vulnerability-management + - Name: Viewing and addressing vulnerabilities + File: common-vuln-management-tasks + - Name: Reporting vulnerabilities + File: vulnerability-reporting + - Name: Using the vulnerability management dashboard (deprecated) + File: vulnerability-management-dashboard + - Name: Scanning RHCOS node hosts + File: scan-rhcos-node-host + - Name: Generating SBOMs from scanned images + File: scanner-generate-sbom +- Name: Responding to violations + File: respond-to-violations +- Name: Using deployment collections + File: create-use-collections +- Name: Searching and filtering + File: search-filter +- Name: Managing user access + Dir: manage-user-access + Topics: + - Name: Managing RBAC in Red Hat Advanced Cluster Security for Kubernetes + File: manage-role-based-access-control-3630 + - Name: Enabling PKI authentication + File: enable-pki-authentication + - Name: Understanding authentication providers + File: understanding-authentication-providers + - Name: Configuring identity providers + Dir: configuring-identity-providers + Topics: + - Name: Configuring Okta Identity Cloud as a SAML 2.0 identity provider + File: configure-okta-identity-cloud + - Name: Configuring Google Workspace as an OIDC identity provider + File: configure-google-workspace-identity + - Name: Configuring OpenShift Container Platform OAuth server as an identity provider + File: configure-ocp-oauth + - Name: Connecting Azure AD to RHACS using SSO configuration + File: connecting-azure-ad-to-rhacs-using-sso-configuration + - Name: Removing the admin user + File: remove-admin-user + - Name: Configuring short-lived access + File: configure-short-lived-access + - Name: Understanding multi-tenancy + File: understanding-multi-tenancy +- Name: Using the system health dashboard + File: use-system-health-dashboard +- Name: Using the administration events page + File: using-the-administration-events-page +--- +Name: Integrating +Dir: integration +Distros: openshift-acs +Topics: +- Name: Integrating with image registries + File: integrate-with-image-registries +- Name: Integrating with CI systems + File: integrate-with-ci-systems +- Name: Integrating with PagerDuty + File: integrate-with-pagerduty +- Name: Integrating with Slack + File: integrate-with-slack +- Name: Integrating by using generic webhooks + File: integrate-using-generic-webhooks +- Name: Integrating with QRadar + File: integrate-with-qradar +- Name: Integrating with ServiceNow + File: integrate-with-servicenow +- Name: Integrating with Sumo Logic + File: integrate-with-sumologic +- Name: Integrating with Google Cloud Storage + File: integrate-with-google-cloud-storage +- Name: Integrating by using the syslog protocol + File: integrate-using-syslog-protocol +- Name: Integrating with Amazon S3 + File: integrate-with-amazon-s3 +- Name: Integrating with S3 API compatible services + File: integrate-with-s3-api-compatible-services +- Name: Integrating with Google Cloud Security Command Center + File: integrate-with-google-cloud-scc +- Name: Integrating with Splunk + File: integrate-with-splunk +- Name: Integrating with image vulnerability scanners + File: integrate-with-image-vulnerability-scanners +- Name: Integrating with Jira + File: integrate-with-jira +- Name: Integrating with email + File: integrate-with-email +- Name: Integrating with cloud management platforms + File: integrate-with-cloud-management-platforms +- Name: Integrating using short-lived tokens + File: integrate-using-short-lived-tokens +- Name: Integrating with Microsoft Sentinel notifier + File: integrating-with-microsoft-sentinel-notifier +--- +Name: Backup and restore +Dir: backup_and_restore +Distros: openshift-acs +Topics: +- Name: Backing up Red Hat Advanced Cluster Security for Kubernetes + File: backing-up-acs +- Name: Restoring from a backup + File: restore-acs +--- +Name: Upgrading +Dir: upgrading +Distros: openshift-acs +Topics: +- Name: Upgrading using the Operator + File: upgrade-operator +- Name: Upgrading using Helm charts + File: upgrade-helm +- Name: Upgrading using the roxctl CLI + File: upgrade-roxctl +--- +Name: roxctl CLI +Dir: cli +Distros: openshift-acs +Topics: +- Name: Installing the roxctl CLI + File: installing-the-roxctl-cli +- Name: Using the roxctl CLI + File: using-the-roxctl-cli +- Name: Managing secured clusters + File: managing-secured-clusters +- Name: Checking policy compliance + File: checking-policy-compliance +- Name: Debugging issues + File: debugging-issues +- Name: Image scanning by using the roxctl CLI + File: image-scanning-by-using-the-roxctl-cli +- Name: roxctl CLI command reference + Dir: command-reference + Topics: + - Name: roxctl + File: roxctl + - Name: roxctl central + File: roxctl-central + - Name: roxctl cluster + File: roxctl-cluster + - Name: roxctl collector + File: roxctl-collector + - Name: roxctl completion + File: roxctl-completion + - Name: roxctl declarative-config + File: roxctl-declarative-config + - Name: roxctl deployment + File: roxctl-deployment + - Name: roxctl helm + File: roxctl-helm + - Name: roxctl image + File: roxctl-image + - Name: roxctl netpol + File: roxctl-netpol + - Name: roxctl scanner + File: roxctl-scanner + - Name: roxctl sensor + File: roxctl-sensor + - Name: roxctl version + File: roxctl-version +--- +Name: Troubleshooting Collector +Dir: troubleshooting +Distros: openshift-acs +Topics: +- Name: Retrieving and analyzing the Collector logs and pod status + File: retrieving-and-analyzing-the-collector-logs-and-pod-status +- Name: Commonly occurring error conditions + File: commonly-occurring-error-conditions +--- +Name: Troubleshooting Central +Dir: troubleshooting_central +Distros: openshift-acs +Topics: +- Name: Backing up Central database by using the roxctl CLI + File: backing-up-central-database-by-using-the-roxctl-cli +- Name: Restoring Central database by using the roxctl CLI + File: restoring-central-database-by-using-the-roxctl-cli +--- +Name: Telemetry +Dir: telemetry +Distros: openshift-acs +Topics: +- Name: About Telemetry + File: about-telemetry +- Name: Opting out of Telemetry + File: opting-out-of-telemetry +--- +Name: Support +Dir: support +Distros: openshift-acs +Topics: +- Name: Getting support for Red Hat Advanced Cluster Security for Kubernetes + File: getting-support +--- +Name: API reference +Dir: rest_api +Distros: openshift-acs +Topics: + - Name: Administration Event Service + Dir: AdministrationEventService + Topics: + - Name: 'Administration Event Service' + File: AdministrationEventService + - Name: Administration Usage Service + Dir: AdministrationUsageService + Topics: + - Name: 'Administration Usage Service' + File: AdministrationUsageService + - Name: Alert Service + Dir: AlertService + Topics: + - Name: 'Alert Service' + File: AlertService + - Name: APIToken Service + Dir: APITokenService + Topics: + - Name: 'A P I Token Service' + File: APITokenService + - Name: Auth Provider Service + Dir: AuthProviderService + Topics: + - Name: 'Auth Provider Service' + File: AuthProviderService + - Name: Auth Service + Dir: AuthService + Topics: + - Name: 'Auth Service' + File: AuthService + - Name: Central Health Service + Dir: CentralHealthService + Topics: + - Name: 'Central Health Service' + File: CentralHealthService + - Name: Cloud Sources Service + Dir: CloudSourcesService + Topics: + - Name: 'Cloud Sources Service' + File: CloudSourcesService + - Name: Cluster CVEService + Dir: ClusterCVEService + Topics: + - Name: 'Cluster C V E Service' + File: ClusterCVEService + - Name: Cluster Init Service + Dir: ClusterInitService + Topics: + - Name: 'Cluster Init Service' + File: ClusterInitService + - Name: Clusters Service + Dir: ClustersService + Topics: + - Name: 'Clusters Service' + File: ClustersService + - Name: Collection Service + Dir: CollectionService + Topics: + - Name: 'Collection Service' + File: CollectionService + - Name: Compliance Integration Service + Dir: ComplianceIntegrationService + Topics: + - Name: 'Compliance Integration Service' + File: ComplianceIntegrationService + - Name: Compliance Management Service + Dir: ComplianceManagementService + Topics: + - Name: 'Compliance Management Service' + File: ComplianceManagementService + - Name: Compliance Profile Service + Dir: ComplianceProfileService + Topics: + - Name: 'Compliance Profile Service' + File: ComplianceProfileService + - Name: Compliance Results Service + Dir: ComplianceResultsService + Topics: + - Name: 'Compliance Results Service' + File: ComplianceResultsService + - Name: Compliance Results Stats Service + Dir: ComplianceResultsStatsService + Topics: + - Name: 'Compliance Results Stats Service' + File: ComplianceResultsStatsService + - Name: Compliance Rule Service + Dir: ComplianceRuleService + Topics: + - Name: 'Compliance Rule Service' + File: ComplianceRuleService + - Name: Compliance Scan Configuration Service + Dir: ComplianceScanConfigurationService + Topics: + - Name: 'Compliance Scan Configuration Service' + File: ComplianceScanConfigurationService + - Name: Compliance Service + Dir: ComplianceService + Topics: + - Name: 'Compliance Service' + File: ComplianceService + - Name: Config Service + Dir: ConfigService + Topics: + - Name: 'Config Service' + File: ConfigService + - Name: Credential Expiry Service + Dir: CredentialExpiryService + Topics: + - Name: 'Credential Expiry Service' + File: CredentialExpiryService + - Name: DBService + Dir: DBService + Topics: + - Name: 'D B Service' + File: DBService + - Name: Debug Service + Dir: DebugService + Topics: + - Name: 'Debug Service' + File: DebugService + - Name: Declarative Config Health Service + Dir: DeclarativeConfigHealthService + Topics: + - Name: 'Declarative Config Health Service' + File: DeclarativeConfigHealthService + - Name: Delegated Registry Config Service + Dir: DelegatedRegistryConfigService + Topics: + - Name: 'Delegated Registry Config Service' + File: DelegatedRegistryConfigService + - Name: Deployment Service + Dir: DeploymentService + Topics: + - Name: 'Deployment Service' + File: DeploymentService + - Name: Detection Service + Dir: DetectionService + Topics: + - Name: 'Detection Service' + File: DetectionService + - Name: Discovered Clusters Service + Dir: DiscoveredClustersService + Topics: + - Name: 'Discovered Clusters Service' + File: DiscoveredClustersService + - Name: External Backup Service + Dir: ExternalBackupService + Topics: + - Name: 'External Backup Service' + File: ExternalBackupService + - Name: Feature Flag Service + Dir: FeatureFlagService + Topics: + - Name: 'Feature Flag Service' + File: FeatureFlagService + - Name: Group Service + Dir: GroupService + Topics: + - Name: 'Group Service' + File: GroupService + - Name: GRPCPreferences Service + Dir: GRPCPreferencesService + Topics: + - Name: 'G R P C Preferences Service' + File: GRPCPreferencesService + - Name: Image CVEService + Dir: ImageCVEService + Topics: + - Name: 'Image C V E Service' + File: ImageCVEService + - Name: Image Integration Service + Dir: ImageIntegrationService + Topics: + - Name: 'Image Integration Service' + File: ImageIntegrationService + - Name: Image Service + Dir: ImageService + Topics: + - Name: 'Image Service' + File: ImageService + - Name: Integration Health Service + Dir: IntegrationHealthService + Topics: + - Name: 'Integration Health Service' + File: IntegrationHealthService + - Name: Listening Endpoints Service + Dir: ListeningEndpointsService + Topics: + - Name: 'Listening Endpoints Service' + File: ListeningEndpointsService + - Name: Metadata Service + Dir: MetadataService + Topics: + - Name: 'Metadata Service' + File: MetadataService + - Name: Mitre Attack Service + Dir: MitreAttackService + Topics: + - Name: 'Mitre Attack Service' + File: MitreAttackService + - Name: Namespace Service + Dir: NamespaceService + Topics: + - Name: 'Namespace Service' + File: NamespaceService + - Name: Network Baseline Service + Dir: NetworkBaselineService + Topics: + - Name: 'Network Baseline Service' + File: NetworkBaselineService + - Name: Network Graph Service + Dir: NetworkGraphService + Topics: + - Name: 'Network Graph Service' + File: NetworkGraphService + - Name: Network Policy Service + Dir: NetworkPolicyService + Topics: + - Name: 'Network Policy Service' + File: NetworkPolicyService + - Name: Node CVEService + Dir: NodeCVEService + Topics: + - Name: 'Node C V E Service' + File: NodeCVEService + - Name: Node Service + Dir: NodeService + Topics: + - Name: 'Node Service' + File: NodeService + - Name: Notifier Service + Dir: NotifierService + Topics: + - Name: 'Notifier Service' + File: NotifierService + - Name: Ping Service + Dir: PingService + Topics: + - Name: 'Ping Service' + File: PingService + - Name: Pod Service + Dir: PodService + Topics: + - Name: 'Pod Service' + File: PodService + - Name: Policy Category Service + Dir: PolicyCategoryService + Topics: + - Name: 'Policy Category Service' + File: PolicyCategoryService + - Name: Policy Service + Dir: PolicyService + Topics: + - Name: 'Policy Service' + File: PolicyService + - Name: Probe Upload Service + Dir: ProbeUploadService + Topics: + - Name: 'Probe Upload Service' + File: ProbeUploadService + - Name: Process Baseline Service + Dir: ProcessBaselineService + Topics: + - Name: 'Process Baseline Service' + File: ProcessBaselineService + - Name: Process Service + Dir: ProcessService + Topics: + - Name: 'Process Service' + File: ProcessService + - Name: Rbac Service + Dir: RbacService + Topics: + - Name: 'Rbac Service' + File: RbacService + - Name: Report Configuration Service + Dir: ReportConfigurationService + Topics: + - Name: 'Report Configuration Service' + File: ReportConfigurationService + - Name: Report Service + Dir: ReportService + Topics: + - Name: 'Report Service' + File: ReportService + - Name: Role Service + Dir: RoleService + Topics: + - Name: 'Role Service' + File: RoleService + - Name: Search Service + Dir: SearchService + Topics: + - Name: 'Search Service' + File: SearchService + - Name: Secret Service + Dir: SecretService + Topics: + - Name: 'Secret Service' + File: SecretService + - Name: Sensor Upgrade Service + Dir: SensorUpgradeService + Topics: + - Name: 'Sensor Upgrade Service' + File: SensorUpgradeService + - Name: Service Account Service + Dir: ServiceAccountService + Topics: + - Name: 'Service Account Service' + File: ServiceAccountService + - Name: Service Identity Service + Dir: ServiceIdentityService + Topics: + - Name: 'Service Identity Service' + File: ServiceIdentityService + - Name: Signature Integration Service + Dir: SignatureIntegrationService + Topics: + - Name: 'Signature Integration Service' + File: SignatureIntegrationService + - Name: Telemetry Service + Dir: TelemetryService + Topics: + - Name: 'Telemetry Service' + File: TelemetryService + - Name: User Service + Dir: UserService + Topics: + - Name: 'User Service' + File: UserService + - Name: Vulnerability Exception Service + Dir: VulnerabilityExceptionService + Topics: + - Name: 'Vulnerability Exception Service' + File: VulnerabilityExceptionService + - Name: Vulnerability Request Service + Dir: VulnerabilityRequestService + Topics: + - Name: 'Vulnerability Request Service' + File: VulnerabilityRequestService + - Name: Vuln Mgmt Service + Dir: VulnMgmtService + Topics: + - Name: 'Vuln Mgmt Service' + File: VulnMgmtService + - Name: Common Object Reference + Dir: CommonObjectReference + Topics: + - Name: 'Common Object Reference' + File: CommonObjectReference diff --git a/_unused_topics/README b/_unused_topics/README deleted file mode 100644 index 5636d8245a15..000000000000 --- a/_unused_topics/README +++ /dev/null @@ -1,2 +0,0 @@ -Placeholder file. Any modules that are not included will be placed here -by the `scripts/find_unused.py` script. diff --git a/_unused_topics/adding-new-devices.adoc b/_unused_topics/adding-new-devices.adoc deleted file mode 100644 index 84ec3221b6e7..000000000000 --- a/_unused_topics/adding-new-devices.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="adding-new-devices_{context}"] -= Adding new devices - -Adding a new device is semi-automatic. The provisioner periodically checks for new mounts in configured directories. Administrators must create a new subdirectory, mount a device, and allow Pods to use the device by applying the SELinux label, for example: - ----- -$ chcon -R unconfined_u:object_r:svirt_sandbox_file_t:s0 /mnt/local-storage/ ----- - -[WARNING] -==== -Omitting any of these steps may result in the wrong PV being created. -==== diff --git a/_unused_topics/architecture-new-content.adoc b/_unused_topics/architecture-new-content.adoc deleted file mode 100644 index 83d9ddbc1221..000000000000 --- a/_unused_topics/architecture-new-content.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture.adoc - -[id="architecture-updates_{context}"] -= Additional architecture content - -//Please add additional architecture content for the 4.0 release to this file. -//The docs team will edit the content and modularize it to fit the rest of -//the collection. \ No newline at end of file diff --git a/_unused_topics/builds-output-image-digest.adoc b/_unused_topics/builds-output-image-digest.adoc deleted file mode 100644 index ee610a5fda0b..000000000000 --- a/_unused_topics/builds-output-image-digest.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * unused_topics/builds-output-image-digest - -[id="builds-output-image-digest_{context}"] -= Output image digest - -Built images can be uniquely identified by their digest, which can -later be used to pull the image by digest regardless of its current tag. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -`Docker` and -endif::[] -`Source-to-Image (S2I)` builds store the digest in -`Build.status.output.to.imageDigest` after the image is pushed to a registry. -The digest is computed by the registry. Therefore, it may not always be present, -for example when the registry did not return a digest, or when the builder image -did not understand its format. - -.Built Image Digest After a Successful Push to the Registry -[source,yaml] ----- -status: - output: - to: - imageDigest: sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 ----- - -.Additional resources - -* link:https://docs.docker.com/registry/spec/api/#/content-digests[Docker Registry HTTP API V2: digest] -* link:https://docs.docker.com/engine/reference/commandline/pull/#/pull-an-image-by-digest-immutable-identifier[`docker pull`: pull the image by digest] diff --git a/_unused_topics/cluster-logging-collector-envvar.adoc b/_unused_topics/cluster-logging-collector-envvar.adoc deleted file mode 100644 index d1a96e696399..000000000000 --- a/_unused_topics/cluster-logging-collector-envvar.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-collector-envvar_{context}"] -= Configuring the logging collector using environment variables - -You can use environment variables to modify the configuration of the Fluentd log -collector. - -See the link:https://github.com/openshift/origin-aggregated-logging/blob/master/fluentd/README.md[Fluentd README] in Github for lists of the -available environment variables. - -.Prerequisites - -* Set OpenShift Logging to the unmanaged state. Operators in an unmanaged state are unsupported and the cluster administrator assumes full control of the individual component configurations and upgrades. - -.Procedure - -Set any of the Fluentd environment variables as needed: - ----- -$ oc set env ds/fluentd = ----- - -For example: - ----- -$ oc set env ds/fluentd BUFFER_SIZE_LIMIT=24 ----- diff --git a/_unused_topics/cluster-logging-configuring-node-selector.adoc b/_unused_topics/cluster-logging-configuring-node-selector.adoc deleted file mode 100644 index 35d910e88e96..000000000000 --- a/_unused_topics/cluster-logging-configuring-node-selector.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-configuring-node-selector_{context}"] -= Specifying a node for OpenShift Logging components using node selectors - -Each component specification allows the component to target a specific node. - -.Procedure - -. Edit the Cluster Logging custom resource (CR) in the `openshift-logging` project: -+ ----- -$ oc edit ClusterLogging instance ----- -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "nodeselector" -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - elasticsearch: - nodeSelector: <1> - logging: es - nodeCount: 1 - resources: - limits: - memory: 2Gi - requests: - cpu: 200m - memory: 2Gi - storage: - size: "20G" - storageClassName: "gp2" - redundancyPolicy: "ZeroRedundancy" - visualization: - type: "kibana" - kibana: - nodeSelector: <2> - logging: kibana - replicas: 1 - curation: - type: "curator" - curator: - nodeSelector: <3> - logging: curator - schedule: "*/10 * * * *" - collection: - logs: - type: "fluentd" - fluentd: - nodeSelector: <4> - logging: fluentd ----- -<1> Node selector for Elasticsearch. -<2> Node selector for Kibana. -<3> Node selector for Curator. -<4> Node selector for Fluentd. diff --git a/_unused_topics/cluster-logging-elasticsearch-admin.adoc b/_unused_topics/cluster-logging-elasticsearch-admin.adoc deleted file mode 100644 index b1b3843deb19..000000000000 --- a/_unused_topics/cluster-logging-elasticsearch-admin.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-elasticsearch-admin_{context}"] -= Performing administrative Elasticsearch operations - -An administrator certificate, key, and CA that can be used to communicate with and perform administrative operations on Elasticsearch are provided within the *elasticsearch* secret in the `openshift-logging` project. - -[NOTE] -==== -To confirm whether your OpenShift Logging installation provides these, run: ----- -$ oc describe secret elasticsearch -n openshift-logging ----- -==== - -. Connect to an Elasticsearch pod that is in the cluster on which you are attempting to perform maintenance. - -. To find a pod in a cluster use: -+ ----- -$ oc get pods -l component=elasticsearch -o name -n openshift-logging | head -1 ----- - -. Connect to a pod: -+ ----- -$ oc rsh ----- - -. Once connected to an Elasticsearch container, you can use the certificates mounted from the secret to communicate with Elasticsearch per its link:https://www.elastic.co/guide/en/elasticsearch/reference/2.3/indices.html[Indices APIs documentation]. -+ -Fluentd sends its logs to Elasticsearch using the index format *infra-00000x* or *app-00000x*. -+ -For example, to delete all logs for the openshift-logging index, *app-000001*, we can run: -+ ----- -$ curl --key /etc/elasticsearch/secret/admin-key \ ---cert /etc/elasticsearch/secret/admin-cert \ ---cacert /etc/elasticsearch/secret/admin-ca -XDELETE \ -"https://localhost:9200/app-000001" ----- diff --git a/_unused_topics/cluster-logging-exported-fields-collectd.adoc b/_unused_topics/cluster-logging-exported-fields-collectd.adoc deleted file mode 100644 index 75dfb4c71428..000000000000 --- a/_unused_topics/cluster-logging-exported-fields-collectd.adoc +++ /dev/null @@ -1,993 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-collectd_{context}"] -= `collectd` exported fields - -These are the `collectd` and `collectd-*` fields exported by the logging system and available for searching -from Elasticsearch and Kibana. - -[discrete] -[id="exported-fields-collectd_{context}"] -=== `collectd` Fields - -The following fields represent namespace metrics metadata. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interval` -|type: float - -The `collectd` interval. - -| `collectd.plugin` -|type: string - -The `collectd` plug-in. - -| `collectd.plugin_instance` -|type: string - -The `collectd` plugin_instance. - -| `collectd.type_instance` -|type: string - -The `collectd` `type_instance`. - -| `collectd.type` -|type: string - -The `collectd` type. - -| `collectd.dstypes` -|type: string - -The `collectd` dstypes. -|=== - -[discrete] -[id="exported-fields-collectd.processes_{context}"] -=== `collectd.processes` Fields - -The following field corresponds to the `collectd` processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_state` -|type: integer -The `collectd ps_state` type of processes plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_disk_ops_{context}"] -=== `collectd.processes.ps_disk_ops` Fields - -The `collectd` `ps_disk_ops` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_disk_ops.read` -|type: float - -`TODO` - -| `collectd.processes.ps_disk_ops.write` -|type: float - -`TODO` - -| `collectd.processes.ps_vm` -|type: integer - -The `collectd` `ps_vm` type of processes plug-in. - -| `collectd.processes.ps_rss` -|type: integer - -The `collectd` `ps_rss` type of processes plug-in. - -| `collectd.processes.ps_data` -|type: integer - -The `collectd` `ps_data` type of processes plug-in. - -| `collectd.processes.ps_code` -|type: integer - -The `collectd` `ps_code` type of processes plug-in. - -| `collectd.processes.ps_stacksize` -| type: integer - -The `collectd` `ps_stacksize` type of processes plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_cputime_{context}"] -=== `collectd.processes.ps_cputime` Fields - -The `collectd` `ps_cputime` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_cputime.user` -|type: float - -`TODO` - -| `collectd.processes.ps_cputime.syst` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_count_{context}"] -=== `collectd.processes.ps_count` Fields - -The `collectd` `ps_count` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_count.processes` -|type: integer - -`TODO` - -| `collectd.processes.ps_count.threads` -|type: integer - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_pagefaults_{context}"] -=== `collectd.processes.ps_pagefaults` Fields - -The `collectd` `ps_pagefaults` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_pagefaults.majflt` -|type: float - -`TODO` - -| `collectd.processes.ps_pagefaults.minflt` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_disk_octets_{context}"] -=== `collectd.processes.ps_disk_octets` Fields - -The `collectd ps_disk_octets` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_disk_octets.read` -|type: float - -`TODO` - -| `collectd.processes.ps_disk_octets.write` -|type: float - -`TODO` - -| `collectd.processes.fork_rate` -|type: float - -The `collectd` `fork_rate` type of processes plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.disk_{context}"] -=== `collectd.disk` Fields - -Corresponds to `collectd` disk plug-in. - -[discrete] -[id="exported-fields-collectd.disk.disk_merged_{context}"] -=== `collectd.disk.disk_merged` Fields - -The `collectd` `disk_merged` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_merged.read` -|type: float - -`TODO` - -| `collectd.disk.disk_merged.write` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.disk.disk_octets_{context}"] -=== `collectd.disk.disk_octets` Fields - -The `collectd` `disk_octets` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_octets.read` -|type: float - -`TODO` - -| `collectd.disk.disk_octets.write` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.disk.disk_time_{context}"] -=== `collectd.disk.disk_time` Fields - -The `collectd` `disk_time` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_time.read` -|type: float - -`TODO` - -| `collectd.disk.disk_time.write` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.disk.disk_ops_{context}"] -=== `collectd.disk.disk_ops` Fields - -The `collectd` `disk_ops` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_ops.read` -|type: float - -`TODO` - -| `collectd.disk.disk_ops.write` -|type: float - -`TODO` - -| `collectd.disk.pending_operations` -|type: integer - -The `collectd` `pending_operations` type of disk plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.disk.disk_io_time_{context}"] -=== `collectd.disk.disk_io_time` Fields - -The `collectd disk_io_time` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_io_time.io_time` -|type: float - -`TODO` - -| `collectd.disk.disk_io_time.weighted_io_time` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.interface_{context}"] -=== `collectd.interface` Fields - -Corresponds to the `collectd` interface plug-in. - -[discrete] -[id="exported-fields-collectd.interface.if_octets_{context}"] -=== `collectd.interface.if_octets` Fields - -The `collectd` `if_octets` type of interface plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interface.if_octets.rx` -|type: float - -`TODO` - -| `collectd.interface.if_octets.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.interface.if_packets_{context}"] -=== `collectd.interface.if_packets` Fields - -The `collectd` `if_packets` type of interface plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interface.if_packets.rx` -|type: float - -`TODO` - -| `collectd.interface.if_packets.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.interface.if_errors_{context}"] -=== `collectd.interface.if_errors` Fields - -The `collectd` `if_errors` type of interface plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interface.if_errors.rx` -|type: float - -`TODO` - -| `collectd.interface.if_errors.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.interface.if_dropped_{context}"] -=== collectd.interface.if_dropped Fields - -The `collectd` `if_dropped` type of interface plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interface.if_dropped.rx` -|type: float - -`TODO` - -| `collectd.interface.if_dropped.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt_{context}"] -=== `collectd.virt` Fields - -Corresponds to `collectd` virt plug-in. - -[discrete] -[id="exported-fields-collectd.virt.if_octets_{context}"] -=== `collectd.virt.if_octets` Fields - -The `collectd if_octets` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.if_octets.rx` -|type: float - -`TODO` - -| `collectd.virt.if_octets.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.if_packets_{context}"] -=== `collectd.virt.if_packets` Fields - -The `collectd` `if_packets` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.if_packets.rx` -|type: float - -`TODO` - -| `collectd.virt.if_packets.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.if_errors_{context}"] -=== `collectd.virt.if_errors` Fields - -The `collectd` `if_errors` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.if_errors.rx` -|type: float - -`TODO` - -| `collectd.virt.if_errors.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.if_dropped_{context}"] -=== `collectd.virt.if_dropped` Fields - -The `collectd` `if_dropped` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.if_dropped.rx` -|type: float - -`TODO` - -| `collectd.virt.if_dropped.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.disk_ops_{context}"] -=== `collectd.virt.disk_ops` Fields - -The `collectd` `disk_ops` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| collectd.virt.disk_ops.read -|type: float - -`TODO` - -| `collectd.virt.disk_ops.write` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.disk_octets_{context}"] -=== `collectd.virt.disk_octets` Fields - -The `collectd` `disk_octets` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.disk_octets.read` -|type: float - -`TODO` - -| `collectd.virt.disk_octets.write` -|type: float - -`TODO` - -| `collectd.virt.memory` -|type: float - -The `collectd` memory type of virt plug-in. - -| `collectd.virt.virt_vcpu` -|type: float - -The `collectd` `virt_vcpu` type of virt plug-in. - -| `collectd.virt.virt_cpu_total` -|type: float - -The `collectd` `virt_cpu_total` type of virt plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.CPU_{context}"] -=== `collectd.CPU` Fields - -Corresponds to the `collectd` CPU plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.CPU.percent` -|type: float - -The `collectd` type percent of plug-in CPU. -|=== - -[discrete] -[id="exported-fields-collectd.df_{context}"] -=== collectd.df Fields - -Corresponds to the `collectd` `df` plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.df.df_complex` -|type: float - -The `collectd` type `df_complex` of plug-in `df`. - -| `collectd.df.percent_bytes` -|type: float - -The `collectd` type `percent_bytes` of plug-in `df`. -|=== - -[discrete] -[id="exported-fields-collectd.entropy_{context}"] -=== `collectd.entropy` Fields - -Corresponds to the `collectd` entropy plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.entropy.entropy` -|type: integer - -The `collectd` entropy type of entropy plug-in. -|=== - -//// -[discrete] -[id="exported-fields-collectd.nfs_{context}"] -=== `collectd.nfs` Fields - -Corresponds to the `collectd` NFS plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.nfs.nfs_procedure` -|type: integer - -The `collectd` `nfs_procedure` type of nfs plug-in. -|=== -//// - -[discrete] -[id="exported-fields-collectd.memory_{context}"] -=== `collectd.memory` Fields - -Corresponds to the `collectd` memory plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.memory.memory` -|type: float - -The `collectd` memory type of memory plug-in. - -| `collectd.memory.percent` -|type: float - -The `collectd` percent type of memory plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.swap_{context}"] -=== `collectd.swap` Fields - -Corresponds to the `collectd` swap plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.swap.swap` -|type: integer - -The `collectd` swap type of swap plug-in. - -| `collectd.swap.swap_io` -|type: integer - -The `collectd swap_io` type of swap plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.load_{context}"] -=== `collectd.load` Fields - -Corresponds to the `collectd` load plug-in. - -[discrete] -[id="exported-fields-collectd.load.load_{context}"] -=== `collectd.load.load` Fields - -The `collectd` load type of load plug-in - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.load.load.shortterm` -|type: float - -`TODO` - -| `collectd.load.load.midterm` -|type: float - -`TODO` - -| `collectd.load.load.longterm` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.aggregation_{context}"] -=== `collectd.aggregation` Fields - -Corresponds to `collectd` aggregation plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.aggregation.percent` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.statsd_{context}"] -=== `collectd.statsd` Fields - -Corresponds to `collectd` `statsd` plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.statsd.host_cpu` -|type: integer - -The `collectd` CPU type of `statsd` plug-in. - -| `collectd.statsd.host_elapsed_time` -|type: integer - -The `collectd` `elapsed_time` type of `statsd` plug-in. - -| `collectd.statsd.host_memory` -|type: integer - -The `collectd` memory type of `statsd` plug-in. - -| `collectd.statsd.host_nic_speed` -|type: integer - -The `collectd` `nic_speed` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_rx` -|type: integer - -The `collectd` `nic_rx` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_tx` -|type: integer - -The `collectd` `nic_tx` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_rx_dropped` -|type: integer - -The `collectd` `nic_rx_dropped` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_tx_dropped` -|type: integer - -The `collectd` `nic_tx_dropped` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_rx_errors` -|type: integer - -The `collectd` `nic_rx_errors` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_tx_errors` -|type: integer - -The `collectd` `nic_tx_errors` type of `statsd` plug-in. - -| `collectd.statsd.host_storage` -|type: integer - -The `collectd` storage type of `statsd` plug-in. - -| `collectd.statsd.host_swap` -|type: integer - -The `collectd` swap type of `statsd` plug-in. - -| `collectd.statsd.host_vdsm` -|type: integer - -The `collectd` VDSM type of `statsd` plug-in. - -| `collectd.statsd.host_vms` -|type: integer - -The `collectd` VMS type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_tx_dropped` -|type: integer - -The `collectd` `nic_tx_dropped` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_rx_bytes` -|type: integer - -The `collectd` `nic_rx_bytes` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_tx_bytes` -|type: integer - -The `collectd` `nic_tx_bytes` type of `statsd` plug-in. - -| `collectd.statsd.vm_balloon_min` -|type: integer - -The `collectd` `balloon_min` type of `statsd` plug-in. - -| `collectd.statsd.vm_balloon_max` -|type: integer - -The `collectd` `balloon_max` type of `statsd` plug-in. - -| `collectd.statsd.vm_balloon_target` -|type: integer - -The `collectd` `balloon_target` type of `statsd` plug-in. - -| `collectd.statsd.vm_balloon_cur` -| type: integer - -The `collectd` `balloon_cur` type of `statsd` plug-in. - -| `collectd.statsd.vm_cpu_sys` -|type: integer - -The `collectd` `cpu_sys` type of `statsd` plug-in. - -| `collectd.statsd.vm_cpu_usage` -|type: integer - -The `collectd` `cpu_usage` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_read_ops` -|type: integer - -The `collectd` `disk_read_ops` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_write_ops` -|type: integer - -The collectd` `disk_write_ops` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_flush_latency` -|type: integer - -The `collectd` `disk_flush_latency` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_apparent_size` -|type: integer - -The `collectd` `disk_apparent_size` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_write_bytes` -|type: integer - -The `collectd` `disk_write_bytes` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_write_rate` -|type: integer - -The `collectd` `disk_write_rate` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_true_size` -|type: integer - -The `collectd` `disk_true_size` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_read_rate` -|type: integer - -The `collectd` `disk_read_rate` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_write_latency` -|type: integer - -The `collectd` `disk_write_latency` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_read_latency` -|type: integer - -The `collectd` `disk_read_latency` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_read_bytes` -|type: integer - -The `collectd` `disk_read_bytes` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_rx_dropped` -|type: integer - -The `collectd` `nic_rx_dropped` type of `statsd` plug-in. - -| `collectd.statsd.vm_cpu_user` -|type: integer - -The `collectd` `cpu_user` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_rx_errors` -|type: integer - -The `collectd` `nic_rx_errors` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_tx_errors` -|type: integer - -The `collectd` `nic_tx_errors` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_speed` -|type: integer - -The `collectd` `nic_speed` type of `statsd` plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.postgresql_{context}"] -=== `collectd.postgresql Fields` - -Corresponds to `collectd` `postgresql` plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.postgresql.pg_n_tup_g` -|type: integer - -The `collectd` type `pg_n_tup_g` of plug-in postgresql. - -| `collectd.postgresql.pg_n_tup_c` -|type: integer - -The `collectd` type `pg_n_tup_c` of plug-in postgresql. - -| `collectd.postgresql.pg_numbackends` -|type: integer - -The `collectd` type `pg_numbackends` of plug-in postgresql. - -| `collectd.postgresql.pg_xact` -|type: integer - -The `collectd` type `pg_xact` of plug-in postgresql. - -| `collectd.postgresql.pg_db_size` -|type: integer - -The `collectd` type `pg_db_size` of plug-in postgresql. - -| `collectd.postgresql.pg_blks` -|type: integer - -The `collectd` type `pg_blks` of plug-in postgresql. -|=== diff --git a/_unused_topics/cluster-logging-exported-fields-docker.adoc b/_unused_topics/cluster-logging-exported-fields-docker.adoc deleted file mode 100644 index 26d77f062ca0..000000000000 --- a/_unused_topics/cluster-logging-exported-fields-docker.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-container_{context}"] -= Container exported fields - -These are the Docker fields exported by OpenShift Logging available for searching from Elasticsearch and Kibana. -Namespace for docker container-specific metadata. The docker.container_id is the Docker container ID. - - -[discrete] -[id="pipeline_metadata.collector_{context}"] -=== `pipeline_metadata.collector` Fields - -This section contains metadata specific to the collector. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `pipeline_metadata.collector.hostname` -|FQDN of the collector. It might be different from the FQDN of the actual emitter -of the logs. - -| `pipeline_metadata.collector.name` -|Name of the collector. - -| `pipeline_metadata.collector.version` -|Version of the collector. - -| `pipeline_metadata.collector.ipaddr4` -|IP address v4 of the collector server, can be an array. - -| `pipeline_metadata.collector.ipaddr6` -|IP address v6 of the collector server, can be an array. - -| `pipeline_metadata.collector.inputname` -|How the log message was received by the collector whether it was TCP/UDP, or -imjournal/imfile. - -| `pipeline_metadata.collector.received_at` -|Time when the message was received by the collector. - -| `pipeline_metadata.collector.original_raw_message` -|The original non-parsed log message, collected by the collector or as close to the -source as possible. -|=== - -[discrete] -[id="exported-fields-pipeline_metadata.normalizer_{context}"] -=== `pipeline_metadata.normalizer` Fields - -This section contains metadata specific to the normalizer. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `pipeline_metadata.normalizer.hostname` -|FQDN of the normalizer. - -| `pipeline_metadata.normalizer.name` -|Name of the normalizer. - -| `pipeline_metadata.normalizer.version` -|Version of the normalizer. - -| `pipeline_metadata.normalizer.ipaddr4` -|IP address v4 of the normalizer server, can be an array. - -| `pipeline_metadata.normalizer.ipaddr6` -|IP address v6 of the normalizer server, can be an array. - -| `pipeline_metadata.normalizer.inputname` -|how the log message was received by the normalizer whether it was TCP/UDP. - -| `pipeline_metadata.normalizer.received_at` -|Time when the message was received by the normalizer. - -| `pipeline_metadata.normalizer.original_raw_message` -|The original non-parsed log message as it is received by the normalizer. - -| `pipeline_metadata.trace` -|The field records the trace of the message. Each collector and normalizer appends -information about itself and the date and time when the message was processed. -|=== diff --git a/_unused_topics/cluster-logging-kibana-console-launch.adoc b/_unused_topics/cluster-logging-kibana-console-launch.adoc deleted file mode 100644 index d7a36efb42a9..000000000000 --- a/_unused_topics/cluster-logging-kibana-console-launch.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-kibana-console.adoc -// * logging/cluster-logging-visualizer.adoc - -[id="cluster-logging-kibana-visualize_{context}"] -= Launching the Kibana interface - -The Kibana interface is a browser-based console -to query, discover, and visualize your Elasticsearch data through histograms, line graphs, -pie charts, heat maps, built-in geospatial support, and other visualizations. - -.Procedure - -To launch the Kibana interface: - -. In the {product-title} console, click *Monitoring* -> *Logging*. - -. Log in using the same credentials you use to log in to the {product-title} console. -+ -The Kibana interface launches. You can now: -+ -* Search and browse your data using the Discover page. -* Chart and map your data using the Visualize page. -* Create and view custom dashboards using the Dashboard page. -+ -Use and configuration of the Kibana interface is beyond the scope of this documentation. For more information, -on using the interface, see the link:https://www.elastic.co/guide/en/kibana/5.6/connect-to-elasticsearch.html[Kibana documentation]. diff --git a/_unused_topics/cluster-logging-log-forwarding-disable.adoc b/_unused_topics/cluster-logging-log-forwarding-disable.adoc deleted file mode 100644 index 680ea9b95686..000000000000 --- a/_unused_topics/cluster-logging-log-forwarding-disable.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-log-forwarding-disable_{context}"] -= Disabling the Log Forwarding feature - -To disable the Log Forwarding feature, remove the `clusterlogging.openshift.io/logforwardingtechpreview:enabled` parameter from the Cluster Logging custom resource (CR) and delete the `ClusterLogForwarder` CR. The container and node logs will be forwarded to the internal {product-title} Elasticsearch instance. - -[IMPORTANT] -==== -You cannot disable Log Forwarding by setting the `disableDefaultForwarding` to `false` in the `ClusterLogForwarder` CR. This prevents OpenShift Logging from sending logs to the specified endpoints *and* to default internal {product-title} Elasticsearch instance. -==== - -.Procedure - -To disable the Log Forwarding feature: - -. Edit the OpenShift Logging CR in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc edit ClusterLogging instance ----- - -. Remove the `clusterlogging.openshift.io/logforwardingtechpreview` annotation: -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - annotations: - clusterlogging.openshift.io/logforwardingtechpreview: enabled <1> - name: "instance" - namespace: "openshift-logging" -... ----- -<1> Remove this annotation. - -. Delete the `ClusterLogForwarder` CR: -+ -[source,terminal] ----- -$ oc delete LogForwarding instance -n openshift-logging ----- - diff --git a/_unused_topics/cluster-logging-uninstall-cluster-ops.adoc b/_unused_topics/cluster-logging-uninstall-cluster-ops.adoc deleted file mode 100644 index ec4c0d37eac0..000000000000 --- a/_unused_topics/cluster-logging-uninstall-cluster-ops.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-uninstall.adoc - -[id="cluster-logging-uninstall-ops_{context}"] -= Uninstall the infra cluster - -You can uninstall the infra cluster from OpenShift Logging. -After uninstalling, Fluentd no longer splits logs. - -.Procedure - -To uninstall the infra cluster: - -. - -. - -. diff --git a/_unused_topics/cnv-accessing-vmi-web.adoc b/_unused_topics/cnv-accessing-vmi-web.adoc deleted file mode 100644 index f733d2873fd5..000000000000 --- a/_unused_topics/cnv-accessing-vmi-web.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// - -[id="virt-accessing-vmi-web_{context}"] -= Connecting to a virtual machine with the web console - -You can connect to a virtual machine by using the web console. - -.Procedure - -. Ensure you are in the correct project. If not, click the *Project* -list and select the appropriate project. -. Click *Workloads* -> *Virtual Machines* to display the virtual -machines in the project. -. Select a virtual machine. -. In the *Overview* tab, click the `virt-launcher-` pod. -. Click the *Terminal* tab. If the terminal is blank, click the -terminal and press any key to initiate connection. diff --git a/_unused_topics/completing-installation.adoc b/_unused_topics/completing-installation.adoc deleted file mode 100644 index 911997c61e1a..000000000000 --- a/_unused_topics/completing-installation.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * TBD - -[id="completing-installation_{context}"] -= Completing and verifying the {product-title} installation - -When the bootstrap node is done with its work and has handed off control to the new {product-title} cluster, the bootstrap node is destroyed. The installation program waits for the cluster to initialize, creates a route to the {product-title} console, and presents the information and credentials you require to log in to the cluster. Here’s an example: - ----- -INFO Install complete!                                 - -INFO Run 'export KUBECONFIG=/home/joe/ocp/auth/kubeconfig' to manage the cluster with 'oc', the {product-title} CLI. - -INFO The cluster is ready when 'oc login -u kubeadmin -p 39RPg-y4c7V-n4bbn-vAF3M' succeeds (wait a few minutes). - -INFO Access the {product-title} web-console here: https://console-openshift-console.apps.mycluster.devel.example.com - -INFO Login to the console with user: kubeadmin, password: 39RPg-y4c7V-n4bbn-vAF3M ----- - -To access the {product-title} cluster from your web browser, log in as kubeadmin with the password (for example, 39RPg-y4c7V-n4bbn-vAF3M), using the URL shown: - -     https://console-openshift-console.apps.mycluster.devel.example.com - -To access the {product-title} cluster from the command line, identify the location of the credentials file (export the KUBECONFIG variable) and log in as kubeadmin with the provided password: ----- -$ export KUBECONFIG=/home/joe/ocp/auth/kubeconfig - -$ oc login -u kubeadmin -p 39RPg-y4c7V-n4bbn-vAF3M ----- - -At this point, you can begin using the {product-title} cluster. To understand the management of your {product-title} cluster going forward, you should explore the {product-title} control plane. diff --git a/_unused_topics/con-pod-reset-policy.adoc b/_unused_topics/con-pod-reset-policy.adoc deleted file mode 100644 index b317a1df6495..000000000000 --- a/_unused_topics/con-pod-reset-policy.adoc +++ /dev/null @@ -1,54 +0,0 @@ -[[nodes-configuring-nodes]] -= Understanding Pod restart policy -{product-author} -{product-version} -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title: - - -//from https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy -A Pod restart policy determines how {product-title} responds when containers in that Pod exit. -The policy applies to all containers in that Pod. - -The possible values are: - -* `Always` - Tries restarting a successfully exited container on the Pod continuously, with an exponential back-off delay (10s, 20s, 40s) until the Pod is restarted. The default is `Always`. -* `OnFailure` - Tries restarting a failed container on the Pod with an exponential back-off delay (10s, 20s, 40s) capped at 5 minutes. -* `Never` - Does not try to restart exited or failed containers on the Pod. Pods immediately fail and exit. - -//https://kubernetes-v1-4.github.io/docs/user-guide/pod-states/ -Once bound to a node, a Pod will never be bound to another node. This means that a controller is necessary in order for a Pod to survive node failure: - -[cols="3",options="header"] -|=== - -|Condition -|Controller Type -|Restart Policy - -|Pods that are expected to terminate (such as batch computations) -|xref:../../architecture/core_concepts/deployments.adoc#jobs[Job] -|`OnFailure` or `Never` - -|Pods that are expected to not terminate (such as web servers) -|xref:../../architecture/core_concepts/deployments.adoc#replication-controllers[Replication Controller] -| `Always`. - -|Pods that must run one-per-machine -|xref:../../dev_guide/daemonsets.adoc#dev-guide-daemonsets[Daemonset] -|Any -|=== - -If a container on a Pod fails and the restart policy is set to `OnFailure`, the Pod stays on the node and the container is restarted. If you do not want the container to -restart, use a restart policy of `Never`. - -//https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/#handling-pod-and-container-failures -If an entire Pod fails, {product-title} starts a new Pod. Developers must address the possibility that applications might be restarted in a new Pod. In particular, -applications must handle temporary files, locks, incomplete output, and so forth caused by previous runs. - -For details on how {product-title} uses restart policy with failed containers, see -the link:https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#example-states[Example States] in the Kubernetes documentation. - diff --git a/_unused_topics/configuration-resource-configure.adoc b/_unused_topics/configuration-resource-configure.adoc deleted file mode 100644 index a65a1d4bb2fc..000000000000 --- a/_unused_topics/configuration-resource-configure.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * TBD - - -[id="configuration-resource-configure_{context}"] -= Configure the Configuration Resource - -To configure the Configuration Resource, you customize the Custom Resource Definition (CRD) that controls its Operator and deploy it to your cluster. - -.Prerequisites -* Deploy an {product-title} cluster. -* Review the CRD for the resource and provision any resources that your changes require. -* Access to the right user to do this thing. - -.Procedure - -. From some specific computer, modify the CRD for the resource to describe your intended configuration. Save the file in `whatever-the-location-is`. - -. Run the following command to update the CRD in your cluster: -+ ----- -$ oc something or other -- <1> --<2> ----- -<1> The CRD file that contains customizations for your resource. -<2> However you specify the cluster you’re changing. - -. Confirm that the resource reflects your changes. Run the following command and review the output: -+ ----- -$ oc something or other - -Output -Output -Output ----- -+ -If the output includes , the resource redeployed on your cluster. diff --git a/_unused_topics/configuring-local-provisioner.adoc b/_unused_topics/configuring-local-provisioner.adoc deleted file mode 100644 index 1e46999679b0..000000000000 --- a/_unused_topics/configuring-local-provisioner.adoc +++ /dev/null @@ -1,54 +0,0 @@ -[id="configuring-local-provisioner_{context}"] -= Configuring the local provisioner - -{product-title} depends on an external provisioner to create PVs for local devices and to clean up PVs when they are not in use to enable reuse. - -.Prerequisites - -* All local volumes must be manually mounted before they can be consumed by {product-title} as PVs. - -[NOTE] -==== -The local volume provisioner is different from most provisioners and does not support dynamic provisioning. -==== - -[NOTE] -==== -The local volume provisioner requires administrators to preconfigure the local volumes on each node and mount them under discovery directories. The provisioner then manages the volumes by creating and cleaning up PVs for each volume. -==== - -.Procedure -. Configure the external provisioner using a ConfigMap to relate directories with storage classes, for example: -+ ----- - kind: ConfigMap -metadata: - name: local-volume-config -data: - storageClassMap: | - local-ssd: - hostDir: /mnt/local-storage/ssd - mountDir: /mnt/local-storage/ssd - local-hdd: - hostDir: /mnt/local-storage/hdd - mountDir: /mnt/local-storage/hdd ----- -<1> Name of the storage class. -<2> Path to the directory on the host. It must be a subdirectory of `*/mnt/local-storage*`. -<3> Path to the directory in the provisioner Pod. We recommend using the same directory structure as used on the host and `mountDir` can be omitted in this case. - -. Create a standalone namespace for the local volume provisioner and its configuration, for example: -+ ----- -$ oc new-project local-storage ----- - -With this configuration, the provisioner creates: - -* One PV with storage class `local-ssd` for every subdirectory mounted in the `*/mnt/local-storage/ssd*` directory -* One PV with storage class `local-hdd` for every subdirectory mounted in the `*/mnt/local-storage/hdd*` directory - -[WARNING] -==== -The syntax of the ConfigMap has changed between {product-title} 3.9 and 3.10. Since this feature is in Technology Preview, the ConfigMap is not automatically converted during the update. -==== diff --git a/_unused_topics/configuring-user-agent.adoc b/_unused_topics/configuring-user-agent.adoc deleted file mode 100644 index fa81389ca9bc..000000000000 --- a/_unused_topics/configuring-user-agent.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="configuring-user-agent"] -= Configuring the user agent -include::modules/common-attributes.adoc[] -:context: configuring-user-agent - -toc::[] - -include::modules/user-agent-overview.adoc[leveloffset=+1] - -include::modules/user-agent-configuring.adoc[leveloffset=+1] diff --git a/_unused_topics/customize-certificates-api-add-default.adoc b/_unused_topics/customize-certificates-api-add-default.adoc deleted file mode 100644 index a70aeb11709a..000000000000 --- a/_unused_topics/customize-certificates-api-add-default.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/api-server.adoc - -[id="add-default-api-server_{context}"] -= Add an API server default certificate - -To allow clients outside the cluster to validate the API server's -certificate, you can replace the default certificate -with one that is issued by a public or organizational CA. - -.Prerequisites - -* You must have a valid certificate and key in the PEM format. - -.Procedure - -. Create a secret that contains the certificate and key in the -`openshift-config` namespace. -+ ----- -$ oc create secret tls \//<1> - --cert= \//<2> - --key= \//<3> - -n openshift-config ----- -<1> `` is the name of the secret that will contain -the certificate. -<2> `` is the path to the certificate on your -local file system. -<3> `` is the path to the private key associated -with this certificate. - -. Update the API server to reference the created secret. -+ ----- -$ oc patch apiserver cluster \ - --type=merge -p \ - '{"spec": {"servingCerts": {"defaultServingCertificate": - {"name": ""}}}}' <1> ----- -<1> Replace `` with the name used for the secret in -the previous step. - -. Examine the `apiserver/cluster` object and confirm the secret is now -referenced. -+ ----- -$ oc get apiserver cluster -o yaml -... -spec: - servingCerts: - defaultServingCertificate: - name: -... ----- diff --git a/_unused_topics/deploying-local-provisioner.adoc b/_unused_topics/deploying-local-provisioner.adoc deleted file mode 100644 index bfef02c41d1f..000000000000 --- a/_unused_topics/deploying-local-provisioner.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="deploying-local-provisioner_{context}"] -= Deploying the local provisioner - -This paragraph is the procedure module introduction: a short description of the procedure. - -.Prerequisites - -* Before starting the provisioner, mount all local devices and create a ConfigMap with storage classes and their directories. - -.Procedure - -. Install the local provisioner from the `*local-storage-provisioner-template.yaml*` file. -. Create a service account that allows running Pods as a root user, using hostPath volumes, and using any SELinux context to monitor, manage, and clean local volumes, for example: -+ ----- -$ oc create serviceaccount local-storage-admin -$ oc adm policy add-scc-to-user privileged -z local-storage-admin ----- -+ -To allow the provisioner Pod to delete content on local volumes created by any Pod, root privileges and any SELinux context are required. hostPath is required to access the `*/mnt/local-storage*` path on the host. diff --git a/_unused_topics/exploring-cvo.adoc b/_unused_topics/exploring-cvo.adoc deleted file mode 100644 index 416394623c91..000000000000 --- a/_unused_topics/exploring-cvo.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * - -[id="exploring-cvo_{context}"] -= Exploring the CVO - -To see the current version that your cluster is on, type: - ----- -$ oc get clusterversion - -NAME    VERSION   AVAILABLE PROGRESSING SINCE STATUS -version 4.5.4 True      False       10h   Cluster version is 4.5.4 ----- - -Each release version is represented by a set of images. To see basic release information and a list of those images, type: - ----- -$ oc adm release info - -Name:          4.0.0-0.7 -Digest:        sha256:641c0e4f550af59ec20349187a31751ae5108270f13332d1771935520ebf34c1 -Created:   2019-03-05 13:33:12 -0500 EST -OS/Arch:   linux/amd64 -Manifests: 248 -Release Metadata: -  Version:  4.0.0-0.7 -  Upgrades: 4.0.0-0.6 -  Metadata: -        description: Beta 2 -Component Versions: -  Kubernetes 1.13.4 -Images: -  NAME                        DIGEST -  aws-machine-controllers     sha256:630e8118038ee97b8b3bbfed7d9b63e06c1346c606e11908064ea3f57bd9ff8e -  cli                         sha256:93e16a8c56ec4031b5fa68683f75910aad57b54160a1e6054b3d3e96d9a4b376 -  cloud-credential-operator   sha256:bbc8d586b2210ac44de554558fd299555e72fb662b6751589d69b173b03aa821 -…​ ----- - -To see the Operators managed on the control plane by the Cluster Version Operator, type: - ----- -$ oc get clusteroperator -NAME                                 VERSION  AVAILABLE PROGRESSING DEGRADED SINCE -cluster-autoscaler                            True      False       False   10h -cluster-storage-operator                      True      False       False   10h -console                                       True      False       False   10h -dns                                           True      False       False   10h -image-registry                                True      False       False   10h -ingress                                       True      False       False   10h -kube-apiserver                                True      False       False   10h -kube-controller-manager                       True      False       False   10h -kube-scheduler                                True      False       False   10h -machine-api                                   True      False       False   10h -machine-config                                True      False       False   10h -marketplace-operator                          True      False       False   10h -monitoring                                    True      False       False   156m -network                                       True      False       False   139m -node-tuning                                   True      False       False   10h -openshift-apiserver                           True      False       False   19m -openshift-authentication                      True      False       False   10h -openshift-cloud-credential-operator           True      False       False   10h -openshift-controller-manager                  True      False       False   10h -openshift-samples                             True      False       False   10h -operator-lifecycle-manager                    True      False       False   10h ----- - -While most of the Cluster Operators listed provide services to the {product-title} cluster, the machine-config Operator in particular is tasked with managing the {op-system} operating systems in the nodes. diff --git a/_unused_topics/identity-provider-create-CR.adoc b/_unused_topics/identity-provider-create-CR.adoc deleted file mode 100644 index 8014c4ae6ab6..000000000000 --- a/_unused_topics/identity-provider-create-CR.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-allow-all-identity-provider.adoc -// * authentication/identity_providers/configuring-deny-all-identity-provider.adoc -// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc -// * authentication/identity_providers/configuring-keystone-identity-provider.adoc -// * authentication/identity_providers/configuring-ldap-identity-provider.adoc -// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc -// * authentication/identity_providers/configuring-github-identity-provider.adoc -// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc -// * authentication/identity_providers/configuring-google-identity-provider.adoc -// * authentication/identity_providers/configuring-oidc-identity-provider.adoc - -[id="identity-provider-create-CR_{context}"] -= Creating the CR that describes an identity provider - -Before you can add an identity provider to your cluster, create a Custom -Resource (CR) that describes it. - -.Prerequisites - -* Create an {product-title} cluster. - -.Procedure - -Create a CR file to describe the identity provider. A generic file displaying -the structure is below. - ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: my_identity_provider <1> - mappingMethod: claim <2> - type: <3> - ... ----- -<1> A unique name defining the identity provider. This provider name is -prefixed to provider user names to form an identity name. -<2> Controls how mappings are established between this provider's identities and user objects. -<3> The type of identity provider to be configured. -+ -Provide the parameters that are required for your identity provider type. diff --git a/_unused_topics/identity-provider-provisioning-user-lookup-mapping.adoc b/_unused_topics/identity-provider-provisioning-user-lookup-mapping.adoc deleted file mode 100644 index 6d490d6ace10..000000000000 --- a/_unused_topics/identity-provider-provisioning-user-lookup-mapping.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * orphaned - -[id="identity-provider-provisioning-user-lookup-mapping_{context}"] -= Manually provisioning a user when using the lookup mapping method - -When using the `lookup` mapping method, user provisioning is done by an external system, via the API. -Typically, identities are automatically mapped to users during login. The 'lookup' mapping method automatically -disables this automatic mapping, which requires you to provision users manually. - - -.Procedure - -If you are using the `lookup` mapping method, use the following steps for each user after configuring -the identity provider: - -. Create an {product-title} User, if not created already: -+ ----- -$ oc create user ----- -+ -For example, the following command creates an {product-title} User `bob`: -+ ----- -$ oc create user bob ----- - -. Create an {product-title} Identity, if not created already. Use the name of the identity provider and -the name that uniquely represents this identity in the scope of the identity provider: -+ ----- -$ oc create identity : ----- -+ -The `` is the name of the identity provider in the master configuration, -as shown in the appropriate identity provider section below. -+ -For example, the following commands creates an Identity with identity provider `ldap_provider` and the identity provider user name `bob_s`. -+ ----- -$ oc create identity ldap_provider:bob_s ----- - -. Create a user/identity mapping for the created user and identity: -+ ----- -$ oc create useridentitymapping : ----- -+ -For example, the following command maps the identity to the user: -+ ----- -$ oc create useridentitymapping ldap_provider:bob_s bob ----- diff --git a/_unused_topics/installation-about-custom.adoc b/_unused_topics/installation-about-custom.adoc deleted file mode 100644 index 8e26117c63b6..000000000000 --- a/_unused_topics/installation-about-custom.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * orphaned - -[id="installation-about-custom_{context}"] -= About the custom installation - -You can use the {product-title} installation program to customize four levels -of the program: - -* {product-title} itself -* The cluster platform -* Kubernetes -* The cluster operating system - -Changes to {product-title} and its platform are managed and supported, but -changes to Kubernetes and the cluster operating system currently are not. If -you customize unsupported levels program levels, future installation and -upgrades might fail. - -When you select values for the prompts that the installation program presents, -you customize {product-title}. You can further modify the cluster platform -by modifying the `install-config.yaml` file that the installation program -uses to deploy your cluster. In this file, you can make changes like setting the -number of machines that the control plane uses, the type of virtual machine -that the cluster deploys, or the CIDR range for the Kubernetes service network. - -It is possible, but not supported, to modify the Kubernetes objects that are injected into the cluster. -A common modification is additional manifests in the initial installation. -No validation is available to confirm the validity of any modifications that -you make to these manifests, so if you modify these objects, you might render -your cluster non-functional. -[IMPORTANT] -==== -Modifying the Kubernetes objects is not supported. -==== - -Similarly it is possible, but not supported, to modify the -Ignition config files for the bootstrap and other machines. No validation is -available to confirm the validity of any modifications that -you make to these Ignition config files, so if you modify these objects, you might render -your cluster non-functional. - -[IMPORTANT] -==== -Modifying the Ignition config files is not supported. -==== - -To complete a custom installation, you use the installation program to generate -the installation files and then customize them. -The installation status is stored in a hidden -file in the asset directory and contains all of the installation files. diff --git a/_unused_topics/installation-creating-worker-machineset.adoc b/_unused_topics/installation-creating-worker-machineset.adoc deleted file mode 100644 index fab07717826c..000000000000 --- a/_unused_topics/installation-creating-worker-machineset.adoc +++ /dev/null @@ -1,144 +0,0 @@ -// Module included in the following assemblies: -// -// * none - -[id="installation-creating-worker-machineset_{context}"] -= Creating worker nodes that the cluster manages - -After your cluster initializes, you can create workers that are controlled by -a MachineSet in your Amazon Web Services (AWS) user-provisioned Infrastructure -cluster. - -.Prerequisites - -* Install a cluster on AWS using infrastructer that you provisioned. - -.Procedure - -. Optional: Launch worker nodes that are controlled by the machine API. -. View the list of MachineSets in the `openshift-machine-api` namespace: -+ ----- -$ oc get machinesets --namespace openshift-machine-api -NAME DESIRED CURRENT READY AVAILABLE AGE -test-tkh7l-worker-us-east-2a 1 1 11m -test-tkh7l-worker-us-east-2b 1 1 11m -test-tkh7l-worker-us-east-2c 1 1 11m ----- -+ -Note the `NAME` of each MachineSet. Because you use a different subnet than the -installation program expects, the worker MachineSets do not use the correct -network settings. You must edit each of these MachineSets. - -. Edit each worker MachineSet to provide the correct values for your cluster: -+ ----- -$ oc edit machineset --namespace openshift-machine-api test-tkh7l-worker-us-east-2a -o yaml -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - creationTimestamp: 2019-03-14T14:03:03Z - generation: 1 - labels: - machine.openshift.io/cluster-api-cluster: test-tkh7l - machine.openshift.io/cluster-api-machine-role: worker - machine.openshift.io/cluster-api-machine-type: worker - name: test-tkh7l-worker-us-east-2a - namespace: openshift-machine-api - resourceVersion: "2350" - selfLink: /apis/machine.openshift.io/v1beta1/namespaces/openshift-machine-api/machinesets/test-tkh7l-worker-us-east-2a - uid: e2a6c8a6-4661-11e9-a9b0-0296069fd3a2 -spec: - replicas: 1 - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: test-tkh7l - machine.openshift.io/cluster-api-machineset: test-tkh7l-worker-us-east-2a - template: - metadata: - creationTimestamp: null - labels: - machine.openshift.io/cluster-api-cluster: test-tkh7l - machine.openshift.io/cluster-api-machine-role: worker - machine.openshift.io/cluster-api-machine-type: worker - machine.openshift.io/cluster-api-machineset: test-tkh7l-worker-us-east-2a - spec: - metadata: - creationTimestamp: null - providerSpec: - value: - ami: - id: ami-07e0e0e0035b5a3fe <1> - apiVersion: awsproviderconfig.openshift.io/v1beta1 - blockDevices: - - ebs: - iops: 0 - volumeSize: 120 - volumeType: gp2 - credentialsSecret: - name: aws-cloud-credentials - deviceIndex: 0 - iamInstanceProfile: - id: test-tkh7l-worker-profile - instanceType: m4.large - kind: AWSMachineProviderConfig - metadata: - creationTimestamp: null - placement: - availabilityZone: us-east-2a - region: us-east-2 - publicIp: null - securityGroups: - - filters: - - name: tag:Name - values: - - test-tkh7l-worker-sg <2> - subnet: - filters: - - name: tag:Name - values: - - test-tkh7l-private-us-east-2a - tags: - - name: kubernetes.io/cluster/test-tkh7l - value: owned - userDataSecret: - name: worker-user-data - versions: - kubelet: "" -status: - fullyLabeledReplicas: 1 - observedGeneration: 1 - replicas: 1 ----- -<1> Specify the {op-system-first} AMI to use for your worker nodes. Use the same -value that you specified in the parameter values for your control plane and -bootstrap templates. -<2> Specify the name of the worker security group that you created in the form -`-worker-sg`. `` is the same -infrastructure name that you extracted from the Ignition config metadata, -which has the format `-`. - -//// -. Optional: Replace the `subnet` stanza with one that specifies the subnet -to deploy the machines on: -+ ----- -subnet: - filters: - - name: tag: <1> - values: - - test-tkh7l-private-us-east-2a <2> ----- -<1> Set the `` of the tag to `Name`, `ID`, or `ARN`. -<2> Specify the `Name`, `ID`, or `ARN` value for the subnet. This value must -match the `tag` type that you specify. -//// - -. View the machines in the `openshift-machine-api` namespace and confirm that -they are launching: -+ ----- -$ oc get machines --namespace openshift-machine-api -NAME INSTANCE STATE TYPE REGION ZONE AGE -test-tkh7l-worker-us-east-2a-hxlqn i-0e7f3a52b2919471e pending m4.4xlarge us-east-2 us-east-2a 3s ----- diff --git a/_unused_topics/installation-osp-troubleshooting.adoc b/_unused_topics/installation-osp-troubleshooting.adoc deleted file mode 100644 index 8b5bcff20bd9..000000000000 --- a/_unused_topics/installation-osp-troubleshooting.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * n/a - -[id="installation-osp-customizing_{context}"] - -= Troubleshooting {product-title} on OpenStack installations - -// Structure as needed in the end. This is very much a WIP. -// A few more troubleshooting and/or known issues blurbs incoming - -Unfortunately, there will always be some cases where {product-title} fails to install properly. In these events, it is helpful to understand the likely failure modes as well as how to troubleshoot the failure. - -This document discusses some troubleshooting options for {rh-openstack}-based -deployments. For general tips on troubleshooting the installation program, see the [Installer Troubleshooting](../troubleshooting.md) guide. - -== View instance logs - -{rh-openstack} CLI tools must be installed, then: - ----- -$ openstack console log show ----- - -== Connect to instances via SSH - -Get the IP address of the machine on the private network: -``` -openstack server list | grep master -| 0dcd756b-ad80-42f1-987a-1451b1ae95ba | cluster-wbzrr-master-1 | ACTIVE | cluster-wbzrr-openshift=172.24.0.21 | rhcos | m1.s2.xlarge | -| 3b455e43-729b-4e64-b3bd-1d4da9996f27 | cluster-wbzrr-master-2 | ACTIVE | cluster-wbzrr-openshift=172.24.0.18 | rhcos | m1.s2.xlarge | -| 775898c3-ecc2-41a4-b98b-a4cd5ae56fd0 | cluster-wbzrr-master-0 | ACTIVE | cluster-wbzrr-openshift=172.24.0.12 | rhcos | m1.s2.xlarge | -``` - -And connect to it using the control plane machine currently holding the API as a jumpbox: - -``` -ssh -J core@${floating IP address}<1> core@ -``` -<1> The floating IP address assigned to the control plane machine. diff --git a/_unused_topics/looking-inside-nodes.adoc b/_unused_topics/looking-inside-nodes.adoc deleted file mode 100644 index b9d6de96cf62..000000000000 --- a/_unused_topics/looking-inside-nodes.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// - -[id="looking-inside-openshift-nodes_{context}"] -= Looking inside {product-title} nodes - -Directly accessing a node is strongly discouraged. Nodes are meant to be managed entirely from the cluster and that are considered tainted if you log in to a node and change anything. That said, there might be times when you want to troubleshoot a problem on a node or simply go onto a node in a test environment to see how things work. - -For debugging purposes, the oc debug command lets you go inside any pod and look around. For nodes, in particular, you open a tools pod on the node, then chroot to the node’s host filesystem. At that point, you are effectively working on the node. Here’s how to do that: - ----- -$ oc get nodes - -NAME STATUS ROLES AGE VERSION - -ip-10-0-0-1.us-east-2.compute.internal Ready worker 3h19m v1.20.0 - -ip-10-0-0-39.us-east-2.compute.internal Ready master 3h37m v1.20.0 - -… - -$ oc debug nodes/ip-10-0-138-39.us-east-2.compute.internal - -Starting pod/ip-10-0-138-39us-east-2computeinternal-debug …​ ----- - ----- -$ oc debug nodes/ip-10-0-138-39.us-east-2.compute.internal - -Starting pod/ip-10-0-138-39us-east-2computeinternal-debug …​ - -To use host binaries, run chroot /host - -If you don’t see a command prompt, try pressing enter. - -sh-4.3# ----- - -As noted, you can change to the root of the node’s filesystem by typing chroot /host and running commands from the host on that filesystem as though you were logged in directly from the host. Here are some examples of commands you can run to see what is happening on the node: - -* crictl: This CRI-O client command provides many of the same operations for examining images images and containers that the docker CLI offers the Docker Container Engine. One difference is that crictl can also act on pods. If you are debugging issues with containers run the {product-title} users or the {product-title} control plane, crictl is the best tool to use. -* podman: Provides many of the same features as crictl and docker CLI tools, but requires no container engine. On a node, podman can be useful for debugging container issues if the CRI-O runtime isn’t working. -* skopeo: Copy, delete, and inspect container images with skopeo. -* rpm-ostree: Use e.g. rpm-ostree status to look at the operating system state. -* journalctl: The standard journalctl command can be very useful for querying the system journal for messages that provide information about applications running on the system. - -Because the nodes are {op-system} Linux-based systems, you can use standard Linux commands to explore the nodes as well. These include ps, netstat, ip, route, rpm, and many others. You can change to the /etc directory on the host and look into configuration files for services running directly on the host. For example, look at /etc/crio/crio.conf for CRI-O settings, /etc/resolv.conf for DNS server settings, and /etc/ssh for SSH service configuration and keys. - -If you are unable to reach the nodes with oc debug, because something is wrong with the {product-title} cluster, you might be able to debug the nodes by setting up a bastion host on the cluster. For information on setting up a bastion host for {product-title}, see https://github.com/eparis/ssh-bastion[ssh-bastion]. diff --git a/_unused_topics/machine-configs-and-pools.adoc b/_unused_topics/machine-configs-and-pools.adoc deleted file mode 100644 index d627624ec571..000000000000 --- a/_unused_topics/machine-configs-and-pools.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * TBD - -[id="machine-configs-and-pools_{context}"] -= Machine Configs and Machine Config Pools -Machine Config Pools manage a cluster of nodes and their corresponding -Machine Configs. Machine Configs contain configuration information for a -cluster. - -To list all Machine Config Pools that are known: - ----- -$ oc get machineconfigpools -NAME CONFIG UPDATED UPDATING DEGRADED -master master-1638c1aea398413bb918e76632f20799 False False False -worker worker-2feef4f8288936489a5a832ca8efe953 False False False ----- - -To list all Machine Configs: ----- -$ oc get machineconfig -NAME GENERATEDBYCONTROLLER IGNITIONVERSION CREATED OSIMAGEURL -00-master 4.0.0-0.150.0.0-dirty 2.2.0 16m -00-master-ssh 4.0.0-0.150.0.0-dirty 16m -00-worker 4.0.0-0.150.0.0-dirty 2.2.0 16m -00-worker-ssh 4.0.0-0.150.0.0-dirty 16m -01-master-kubelet 4.0.0-0.150.0.0-dirty 2.2.0 16m -01-worker-kubelet 4.0.0-0.150.0.0-dirty 2.2.0 16m -master-1638c1aea398413bb918e76632f20799 4.0.0-0.150.0.0-dirty 2.2.0 16m -worker-2feef4f8288936489a5a832ca8efe953 4.0.0-0.150.0.0-dirty 2.2.0 16m ----- - -To list all KubeletConfigs: - ----- -$ oc get kubeletconfigs ----- - -To get more detailed information about a KubeletConfig, including the reason for -the current condition: - ----- -$ oc describe kubeletconfig ----- - -For example: - ----- -# oc describe kubeletconfig set-max-pods - -Name: set-max-pods <1> -Namespace: -Labels: -Annotations: -API Version: machineconfiguration.openshift.io/v1 -Kind: KubeletConfig -Metadata: - Creation Timestamp: 2019-02-05T16:27:20Z - Generation: 1 - Resource Version: 19694 - Self Link: /apis/machineconfiguration.openshift.io/v1/kubeletconfigs/set-max-pods - UID: e8ee6410-2962-11e9-9bcc-664f163f5f0f -Spec: - Kubelet Config: <2> - Max Pods: 100 - Machine Config Pool Selector: <3> - Match Labels: - Custom - Kubelet: small-pods -Events: ----- - -<1> The name of the KubeletConfig. -<2> The user defined configuration. -<3> The Machine Config Pool selector to apply the KubeletConfig to. \ No newline at end of file diff --git a/_unused_topics/managing-dedicated-readers-group.adoc b/_unused_topics/managing-dedicated-readers-group.adoc deleted file mode 100644 index 511dc8313ab6..000000000000 --- a/_unused_topics/managing-dedicated-readers-group.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// administering_a_cluster/dedicated-admin-role.adoc - -[id="dedicated-managing-dedicated-readers-group_{context}"] -= Managing the dedicated-readers group - -Users with a `dedicated-reader` role are granted edit and view access to the -`dedicated-reader` project and view-only access to the other projects. - -To view a list of current dedicated readers by user name, you can use the -following command: - ----- -$ oc describe group dedicated-readers ----- - -To add a new member to the `dedicated-readers` group, if you have -`dedicated-admin` access: - ----- -$ oc adm groups add-users dedicated-readers ----- - -To remove an existing user from the `dedicated-readers` group, if you have -`dedicated-admin` access: - ----- -$ oc adm groups remove-users dedicated-readers ----- diff --git a/_unused_topics/metering-resources.adoc b/_unused_topics/metering-resources.adoc deleted file mode 100644 index 7b0f67114a9a..000000000000 --- a/_unused_topics/metering-resources.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-install-metering.adoc - -[id="metering-resources_{context}"] -= Metering resources - -Metering has many resources, which can be used to manage the deployment and installation of Metering, as well as the reporting functionality Metering provides. - -Metering is managed using the following CustomResourceDefinitions (CRDs): - -[cols="1,7"] -|=== - -|*MeteringConfig* |Configures the Metering stack for deployment. Contains customizations and configuration options to control each component that makes up the Metering stack. - -|*Reports* |Controls what query to use, when, and how often the query should be run, and where to store the results. - -|*ReportQueries* |Contains the SQL queries used to perform analysis on the data contained with in ReportDataSources. - -|*ReportDataSources* |Controls the data available to ReportQueries and Reports. Allows configuring access to different databases for use within Metering. - -|=== diff --git a/_unused_topics/monitoring-configuring-etcd-monitoring.adoc b/_unused_topics/monitoring-configuring-etcd-monitoring.adoc deleted file mode 100644 index 414b1e6455fd..000000000000 --- a/_unused_topics/monitoring-configuring-etcd-monitoring.adoc +++ /dev/null @@ -1,190 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/monitoring.adoc - -[id="configuring-etcd-monitoring_{context}"] -= Configuring etcd monitoring - -If the `etcd` service does not run correctly, successful operation of the whole {product-title} cluster is in danger. Therefore, it is reasonable to configure monitoring of `etcd`. - -.Procedure - -. Verify that the monitoring stack is running: -+ -[subs="quotes"] ----- -$ oc -n openshift-monitoring get pods -NAME READY STATUS RESTARTS AGE -alertmanager-main-0 3/3 Running 0 34m -alertmanager-main-1 3/3 Running 0 33m -alertmanager-main-2 3/3 Running 0 33m -cluster-monitoring-operator-67b8797d79-sphxj 1/1 Running 0 36m -grafana-c66997f-pxrf7 2/2 Running 0 37s -kube-state-metrics-7449d589bc-rt4mq 3/3 Running 0 33m -node-exporter-5tt4f 2/2 Running 0 33m -node-exporter-b2mrp 2/2 Running 0 33m -node-exporter-fd52p 2/2 Running 0 33m -node-exporter-hfqgv 2/2 Running 0 33m -prometheus-k8s-0 4/4 Running 1 35m -prometheus-k8s-1 0/4 ContainerCreating 0 21s -prometheus-operator-6c9fddd47f-9jfgk 1/1 Running 0 36m ----- - -. Open the configuration file for the cluster monitoring stack: -+ -[subs="quotes"] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -. Under `config.yaml: |+`, add the `etcd` section. -+ -.. If you run `etcd` in static pods on your master nodes, you can specify the `etcd` nodes using the selector: -+ -[subs="quotes"] ----- -... -data: - config.yaml: |+ - ... - *etcd: - targets: - selector: - openshift.io/component: etcd - openshift.io/control-plane: "true"* ----- -+ -.. If you run `etcd` on separate hosts, you must specify the nodes using IP addresses: -+ -[subs="quotes"] ----- -... -data: - config.yaml: |+ - ... - *etcd: - targets: - ips: - - "127.0.0.1" - - "127.0.0.2" - - "127.0.0.3"* ----- -+ -If `etcd` nodes IP addresses change, you must update this list. - -. Verify that the `etcd` service monitor is now running: -+ -[subs="quotes"] ----- -$ oc -n openshift-monitoring get servicemonitor -NAME AGE -alertmanager 35m -*etcd 1m* -kube-apiserver 36m -kube-controllers 36m -kube-state-metrics 34m -kubelet 36m -node-exporter 34m -prometheus 36m -prometheus-operator 37m ----- -+ -It might take up to a minute for the `etcd` service monitor to start. - -. Now you can navigate to the Web interface to see more information about status of `etcd` monitoring: -+ -.. To get the URL, run: -+ -[subs="quotes"] ----- -$ oc -n openshift-monitoring get routes -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -... -prometheus-k8s prometheus-k8s-openshift-monitoring.apps.msvistun.origin-gce.dev.openshift.com prometheus-k8s web reencrypt None ----- -+ -.. Using `https`, navigate to the URL listed for `prometheus-k8s`. Log in. - -. Ensure the user belongs to the `cluster-monitoring-view` role. This role provides access to viewing cluster monitoring UIs. For example, to add user `developer` to `cluster-monitoring-view`, run: - - $ oc adm policy add-cluster-role-to-user cluster-monitoring-view developer -+ - -. In the Web interface, log in as the user belonging to the `cluster-monitoring-view` role. - -. Click *Status*, then *Targets*. If you see an `etcd` entry, `etcd` is being monitored. -+ -image::etcd-no-certificate.png[] - -While `etcd` is being monitored, Prometheus is not yet able to authenticate against `etcd`, and so cannot gather metrics. To configure Prometheus authentication against `etcd`: - -. Copy the `/etc/etcd/ca/ca.crt` and `/etc/etcd/ca/ca.key` credentials files from the master node to the local machine: -+ -[subs="quotes"] ----- -$ ssh -i gcp-dev/ssh-privatekey cloud-user@35.237.54.213 -... ----- - -. Create the `openssl.cnf` file with these contents: -+ ----- -[ req ] -req_extensions = v3_req -distinguished_name = req_distinguished_name -[ req_distinguished_name ] -[ v3_req ] -basicConstraints = CA:FALSE -keyUsage = nonRepudiation, keyEncipherment, digitalSignature -extendedKeyUsage=serverAuth, clientAuth ----- - -. Generate the `etcd.key` private key file: -+ -[subs="quotes"] ----- -$ openssl genrsa -out etcd.key 2048 ----- - -. Generate the `etcd.csr` certificate signing request file: -+ -[subs="quotes"] ----- -$ openssl req -new -key etcd.key -out etcd.csr -subj "/CN=etcd" -config openssl.cnf ----- - -. Generate the `etcd.crt` certificate file: -+ -[subs="quotes"] ----- -$ openssl x509 -req -in etcd.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out etcd.crt -days 365 -extensions v3_req -extfile openssl.cnf ----- - -. Put the credentials into format used by {product-title}: -+ ----- -cat <<-EOF > etcd-cert-secret.yaml -apiVersion: v1 -data: - etcd-client-ca.crt: "$(cat ca.crt | base64 --wrap=0)" - etcd-client.crt: "$(cat etcd.crt | base64 --wrap=0)" - etcd-client.key: "$(cat etcd.key | base64 --wrap=0)" -kind: Secret -metadata: - name: kube-etcd-client-certs - namespace: openshift-monitoring -type: Opaque -EOF ----- -+ -This creates the *_etcd-cert-secret.yaml_* file - -. Apply the credentials file to the cluster: - ----- -$ oc apply -f etcd-cert-secret.yaml ----- - -. Visit the "Targets" page of the Web interface again. Verify that `etcd` is now being correctly monitored. It might take several minutes for changes to take effect. -+ -image::etcd-monitoring-working.png[] diff --git a/_unused_topics/monitoring-dead-mans-switch-pagerduty.adoc b/_unused_topics/monitoring-dead-mans-switch-pagerduty.adoc deleted file mode 100644 index d7a82d43d12e..000000000000 --- a/_unused_topics/monitoring-dead-mans-switch-pagerduty.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-monitoring-stack.adoc - -[id="dead-mans-switch-pagerduty_{context}"] -== Dead man's switch PagerDuty - -https://www.pagerduty.com/[PagerDuty] supports "Dead man's switch" through an integration called https://deadmanssnitch.com/[Dead Man's Snitch]. You can enable it. - -.Procedure - -* Add a `PagerDuty` configuration to the default `deadmansswitch` receiver. -+ -For example, you can configure Dead Man's Snitch to page the operator if the "Dead man's switch" alert is silent for 15 minutes. With the default Alertmanager configuration, the Dead man's switch alert is repeated every five minutes. If Dead Man's Snitch triggers after 15 minutes, it indicates that the notification has been unsuccessful at least twice. - -.Additional resources - -// FIXME describe the procedure instead of linking * To learn how to add a `PagerDuty` configuration to the default `deadmansswitch` receiver, see LINK. -* To learn how to configure Dead Man's Snitch for PagerDuty, see https://www.pagerduty.com/docs/guides/dead-mans-snitch-integration-guide/[Dead Man’s Snitch Integration Guide]. - diff --git a/_unused_topics/monitoring-dead-mans-switch.adoc b/_unused_topics/monitoring-dead-mans-switch.adoc deleted file mode 100644 index db473bd2202e..000000000000 --- a/_unused_topics/monitoring-dead-mans-switch.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-monitoring-stack.adoc - -[id="dead-mans-switch_{context}"] -== Dead man's switch - -{product-title} Monitoring ships with a "Dead man's switch" to ensure the availability of the monitoring infrastructure. - -The "Dead man's switch" is a simple Prometheus alerting rule that always triggers. The Alertmanager continuously sends notifications for the dead man's switch to the notification provider that supports this functionality. This also ensures that communication between the Alertmanager and the notification provider is working. - -This mechanism is supported by PagerDuty to issue alerts when the monitoring system itself is down. - diff --git a/_unused_topics/monitoring-enabling-dynamically-provisioned-storage.adoc b/_unused_topics/monitoring-enabling-dynamically-provisioned-storage.adoc deleted file mode 100644 index 3cb84b12da5c..000000000000 --- a/_unused_topics/monitoring-enabling-dynamically-provisioned-storage.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-monitoring-stack.adoc - -[id="enabling-dynamically-provisioned-storage_{context}"] -= Enabling dynamically-provisioned storage - -Instead of statically-provisioned storage, you can use dynamically-provisioned storage. - -.Procedure - -. To enable dynamic storage for Prometheus and Alertmanager, set the following parameters to `true` in the Ansible inventory file: -+ -* `openshift_cluster_monitoring_operator_prometheus_storage_enabled` (Default: false) -* `openshift_cluster_monitoring_operator_alertmanager_storage_enabled` (Default: false) -+ -. Optional: After you enable dynamic storage, you can also set the `storageclass` for the persistent volume claim for each component in the following parameters in the Ansible inventory file: -+ -* `openshift_cluster_monitoring_operator_prometheus_storage_class_name` (default: "") -* `openshift_cluster_monitoring_operator_alertmanager_storage_class_name` (default: "") -+ -Each of these variables applies only if its corresponding `storage_enabled` variable is set to `true`. - -.Additional resources - -* See https://kubernetes.io/docs/concepts/storage/dynamic-provisioning/[Dynamic Volume Provisioning] for details. - diff --git a/_unused_topics/monitoring-enabling-persistent-storage.adoc b/_unused_topics/monitoring-enabling-persistent-storage.adoc deleted file mode 100644 index b9bd16207584..000000000000 --- a/_unused_topics/monitoring-enabling-persistent-storage.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-monitoring-stack.adoc - -[id="enabling-persistent-storage_{context}"] -= Enabling persistent storage - -By default, persistent storage is disabled for both Prometheus time-series data and for Alertmanager notifications and silences. You can configure the cluster to persistently store any one of them or both. - -.Procedure - -* To enable persistent storage of Prometheus time-series data, set this variable to `true` in the Ansible inventory file: -+ -`openshift_cluster_monitoring_operator_prometheus_storage_enabled` -+ -To enable persistent storage of Alertmanager notifications and silences, set this variable to `true` in the Ansible inventory file: -+ -`openshift_cluster_monitoring_operator_alertmanager_storage_enabled` - diff --git a/_unused_topics/monitoring-full-list-of-configuration-variables.adoc b/_unused_topics/monitoring-full-list-of-configuration-variables.adoc deleted file mode 100644 index 738a34e63d21..000000000000 --- a/_unused_topics/monitoring-full-list-of-configuration-variables.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-monitoring-stack.adoc - -[id="full-list-of-configuration-variables_{context}"] -= Full list of configuration variables - -This table contains the full list of the inventory file variables for configuring the Cluster Monitoring Operator: - -.Cluster Monitoring Operator Ansible variables -[options="header"] -|=== - -|Variable |Description - -|`openshift_cluster_monitoring_operator_install` -| Deploy the Cluster Monitoring Operator if `true`. Otherwise, undeploy. This variable is set to `true` by default. - -|`openshift_cluster_monitoring_operator_prometheus_storage_capacity` -| The persistent volume claim size for each of the Prometheus instances. This variable applies only if `openshift_cluster_monitoring_operator_prometheus_storage_enabled` is set to `true`. Defaults to `50Gi`. - -|`openshift_cluster_monitoring_operator_alertmanager_storage_capacity` -| The persistent volume claim size for each of the Alertmanager instances. This variable applies only if `openshift_cluster_monitoring_operator_alertmanager_storage_enabled` is set to `true`. Defaults to `2Gi`. - -|`openshift_cluster_monitoring_operator_node_selector` -| Set to the desired, existing [node selector] to ensure that pods are placed onto nodes with specific labels. Defaults to `node-role.kubernetes.io/infra=true`. - -|`openshift_cluster_monitoring_operator_alertmanager_config` -| Configures Alertmanager. - -|`openshift_cluster_monitoring_operator_prometheus_storage_enabled` -| Enable persistent storage of Prometheus' time-series data. This variable is set to `false` by default. - -|`openshift_cluster_monitoring_operator_alertmanager_storage_enabled` -| Enable persistent storage of Alertmanager notifications and silences. This variable is set to `false` by default. - -|`openshift_cluster_monitoring_operator_prometheus_storage_class_name` -| If you enabled the `openshift_cluster_monitoring_operator_prometheus_storage_enabled` option, set a specific StorageClass to ensure that pods are configured to use the `PVC` with that `storageclass`. Defaults to `none`, which applies the default storage class name. - -|`openshift_cluster_monitoring_operator_alertmanager_storage_class_name` -| If you enabled the `openshift_cluster_monitoring_operator_alertmanager_storage_enabled` option, set a specific StorageClass to ensure that pods are configured to use the `PVC` with that `storageclass`. Defaults to `none`, which applies the default storage class name. -|=== - -.Additional resources - -// FIXME add link once doc is available -// Used to point to ../admin_guide/scheduling/node_selector.adoc[Advanced Scheduling and Node Selectors] -* See LINK for more information on node selectors. diff --git a/_unused_topics/monitoring-grouping-alerts.adoc b/_unused_topics/monitoring-grouping-alerts.adoc deleted file mode 100644 index ad71f4988995..000000000000 --- a/_unused_topics/monitoring-grouping-alerts.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-monitoring-stack.adoc - -[id="grouping-alerts_{context}"] -== Grouping alerts - -Once alerts are firing against the Alertmanager, it must be configured to know how to logically group them. This procedure shows how to configure alert grouping: - -.Procedure - -_FIXME get missing info and complete the procedure_ - -For this example, a new route will be added to reflect alert routing of the "frontend" team. - -. Add new routes. Multiple routes may be added beneath the original route, typically to define the receiver for the notification. This example uses a matcher to ensure that only alerts coming from the service `example-app` are used: -+ - global: - resolve_timeout: 5m - route: - group_wait: 30s - group_interval: 5m - repeat_interval: 12h - receiver: default - routes: - - match: - alertname: DeadMansSwitch - repeat_interval: 5m - receiver: deadmansswitch - - match: - service: example-app - routes: - - match: - severity: critical - receiver: team-frontend-page - receivers: - - name: default - - name: deadmansswitch -+ -The sub-route matches only on alerts that have a severity of `critical`, and sends them via the receiver called `team-frontend-page`. As the name indicates, someone should be paged for alerts that are critical. - - diff --git a/_unused_topics/monitoring-monitoring-overview.adoc b/_unused_topics/monitoring-monitoring-overview.adoc deleted file mode 100644 index 8b1096b717b0..000000000000 --- a/_unused_topics/monitoring-monitoring-overview.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/monitoring.adoc - -[id="monitoring-overview_{context}"] -= Monitoring overview - -{product-title} ships with a pre-configured, pre-installed, and self-updating monitoring stack that is based on the link:https://prometheus.io/[Prometheus] open source project and its wider eco-system. It provides monitoring of cluster components and ships with a set of alerts to immediately notify the cluster administrator about any occurring problems and a set of link:https://grafana.com/[Grafana] dashboards. - -The monitoring stack includes these components: - -* Cluster Monitoring Operator -* Prometheus Operator -* Prometheus -* Prometheus Adapter -* Alertmanager -* kube-state-metrics -* node-exporter -* Grafana - -The {product-title} Cluster Monitoring Operator (CMO) is the central component of the stack. It watches over the deployed monitoring components and resources and ensures that they are always up to date. - -The Prometheus Operator (PO) creates, configures, and manages Prometheus and Alertmanager instances. It also automatically generates monitoring target configurations based on familiar Kubernetes label queries. - -The Prometheus Adapter exposes cluster resource metrics (CPU and memory utilization) API for horizontal pod autoscaling. - -Node-exporter is an agent deployed on every node to collect metrics about it. - -The kube-state-metrics exporter agent converts Kubernetes objects to metrics consumable by Prometheus. - -All the components of the monitoring stack are monitored by the stack. Additionally, the stack monitors: - -* cluster-version-operator -* image-registry -* kube-apiserver -* kube-apiserver-operator -* kube-controller-manager -* kube-controller-manager-operator -* kube-scheduler -* kubelet -* monitor-sdn -* openshift-apiserver -* openshift-apiserver-operator -* openshift-controller-manager -* openshift-controller-manager-operator -* openshift-svcat-controller-manager-operator -* telemeter-client - -All these components are automatically updated. - -Other {product-title} framework components might be exposing metrics as well. See their respective documentation. - -[NOTE] -==== -To be able to deliver updates with guaranteed compatibility, configurability of the {product-title} Monitoring stack is limited to the explicitly available options. -==== - diff --git a/_unused_topics/monitoring-setting-persistent-storage-size.adoc b/_unused_topics/monitoring-setting-persistent-storage-size.adoc deleted file mode 100644 index 619f6133c9bc..000000000000 --- a/_unused_topics/monitoring-setting-persistent-storage-size.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-monitoring-stack.adoc - -[id="setting-persistent-storage-size_{context}"] -= Setting persistent storage size - -You can specify the size of the persistent volume claim for Prometheus and Alertmanager. - -.Procedure - -* Change these Ansible variables: -+ --- -* `openshift_cluster_monitoring_operator_prometheus_storage_capacity` (default: 50Gi) -* `openshift_cluster_monitoring_operator_alertmanager_storage_capacity` (default: 2Gi) --- -+ -Each of these variables applies only if its corresponding `storage_enabled` variable is set to `true`. - diff --git a/_unused_topics/monitoring-update-and-compatibility-guarantees.adoc b/_unused_topics/monitoring-update-and-compatibility-guarantees.adoc deleted file mode 100644 index 4f42970573fc..000000000000 --- a/_unused_topics/monitoring-update-and-compatibility-guarantees.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/monitoring.adoc - -[id="update-and-compatibility-guarantees_{context}"] -= Update and compatibility guarantees - -To be able to deliver updates with guaranteed compatibility, configurability of the {product-title} Monitoring stack is limited to the explicitly available options. This document describes known pitfalls of which types of configuration and customization are unsupported, as well as misuse of resources provided by {product-title} Monitoring. All configuration options described in this topic are explicitly supported. - -*Modification of {product-title} monitoring resources* - -The {product-title} Monitoring stack ensures its resources are _always_ in the state it expects them to be. If they are modified, {product-title} Monitoring will ensure that this will be reset. Nonetheless it is possible to pause this behavior, by setting the `paused` field in the `AppVersion` called `openshift-monitoring`. Setting the {product-title} Monitoring stack to be paused, stops all future updates and will cause modification of the otherwise managed resources. If resources are modified in an uncontrolled manner, this will cause undefined behavior during updates. - -To ensure compatible and functioning updates, the `paused` field must be set to `false` on upgrades. - -*Usage of resources created by {product-title} monitoring* - -{product-title} Monitoring creates a number of resources. These resources are not meant to be used by any other resources, as there are no guarantees about their backward compatibility. For example, a `ClusterRole` called `prometheus-k8s` is created, and has very specific roles that exist solely for the cluster monitoring Prometheus pods to be able to access the resources it requires access to. All of these resources have no compatibility guarantees going forward. While some of these resources may incidentally have the necessary information for RBAC purposes for example, they can be subject to change in any upcoming release, with no backward compatibility. - -If the `Role` or `ClusterRole` objects that are similar are needed, we recommend creating a new object that has exactly the permissions required for the case at hand, rather than using the resources created and maintained by {product-title} Monitoring. diff --git a/_unused_topics/mounting-local-volumes.adoc b/_unused_topics/mounting-local-volumes.adoc deleted file mode 100644 index c0278465a113..000000000000 --- a/_unused_topics/mounting-local-volumes.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="mounting-local-volumes_{context}"] -= Mounting local volumes - -This paragraph is the procedure module introduction: a short description of the procedure. - -.Prerequisites - -* All local volumes must be manually mounted before they can be consumed by {product-title} as PVs. - -.Procedure - -. Mount all volumes into the `*/mnt/local-storage//*` path: -+ ----- -# device name # mount point # FS # options # extra -/dev/sdb1 /mnt/local-storage/ssd/disk1 ext4 defaults 1 2 -/dev/sdb2 /mnt/local-storage/ssd/disk2 ext4 defaults 1 2 -/dev/sdb3 /mnt/local-storage/ssd/disk3 ext4 defaults 1 2 -/dev/sdc1 /mnt/local-storage/hdd/disk1 ext4 defaults 1 2 -/dev/sdc2 /mnt/local-storage/hdd/disk2 ext4 defaults 1 2 ----- -+ -Administrators must create local devices as needed using any method such as disk partition or LVM, create suitable file systems on these devices, and mount these devices using a script or /etc/fstab entries - -. Make all volumes accessible to the processes running within the Docker containers: -+ ----- -$ chcon -R unconfined_u:object_r:svirt_sandbox_file_t:s0 /mnt/local-storage/ ----- diff --git a/_unused_topics/nodes-cluster-disabling-features-list.adoc b/_unused_topics/nodes-cluster-disabling-features-list.adoc deleted file mode 100644 index 3dd61d49bb5c..000000000000 --- a/_unused_topics/nodes-cluster-disabling-features-list.adoc +++ /dev/null @@ -1,266 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-disabling-features.adoc - -[id="nodes-cluster-disabling-features-list_{context}"] -= List of feature gates - -Use the following list to determine the name of the feature you want to disable: - -[options="header"] -|=== -| Feature gate| Description | Default - -| *AdvancedAuditing* -| Enables a more general API auditing pipeline, which includes support for pluggable output backends and an audit policy specifying how different requests should be audited. -| True - -| *APIListChunking* -| Enables the API clients to retrieve LIST or GET resources from API server in chunks. -| True - -| *APIResponseCompression* -| Enables the compression of API responses for LIST or GET requests. -| False - -| *AppArmor* -| Enables AppArmor-based mandatory access control on Linux nodes when using Docker. For more information, see the link:https://kubernetes.io/docs/tutorials/clusters/apparmor/[Kubernetes AppArmor documentation]. -| True - -| *AttachVolumeLimit* -| Adds support for volume plugins to report node specific volume limits. -| True - -| *BalanceAttachedNodeVolumes* -| Includes volume count on node to be considered for balanced resource allocation while scheduling. A node which has closer CPU ,memory utilization, and volume count is favored by scheduler while making decisions. -| False - -| *BlockVolume* -| Enables the definition and consumption of raw block devices in pods. For more information, see -the link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/#raw-block-volume-support[Kubernetes Raw Block Volume Support]. -| False - -| *CPUManager* -| Enables Container-level CPU affinity support. -For more information, see Using CPU Manager. -| True - -| *CPUCFSQuotaPeriod* -| Enables nodes to change CPUCFSQuotaPeriod. -| False - -| *CRIcontainerLogRotation* -| Enables Container log rotation for the CRI Container runtime. -| True - -| *CSIBlockVolume* -| Enables CSI to use raw block storage volumes. -| False - -| *CSIDriverRegistry* -| Enables all logic related to the CSIDriver API object in csi.storage.k8s.io. -| False - -| *CSINodeInfo* -| Enables all logic related to the CSINodeInfo API object in csi.storage.k8s.io. -| False - -| *CSIPersistentVolume* -| Enables discovering and mounting volumes provisioned through a CSI (Container Storage Interface) compatible volume plugin. For more information, -see the link:https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/container-storage-interface.md[CSI Volume Plugins in Kubernetes Design Documentation]. -| True - -| *CustomPodDNS* -| Enables customizing the DNS settings for a pod using the *dnsConfig* property. -| True - -| *Debugcontainers* -| Enables running a debugging Container in a pod namespace to troubleshoot a running Pod. -| False - -| *DevicePlugins* -| Enables device plug-in-based resource provisioning on nodes. -| True - -| *DryRun* -| Allows requests to be processed but not stored, so that validation, merging, mutation can be tested without committing. -| False - -| *DynamicKubeletConfig* -| Enables the dynamic configuration in a cluster. -| True - -| *EnableEquivalenceClassCache* -| Enables the scheduler to cache equivalence of nodes when scheduling Pods. -| False - -| *ExpandPersistentVolumes* -| Enables the ability to Expand persistent volumes. -| True - -| *ExpandInUsePersistentVolumes* -| Enables the ability to expand persistent volumes' file system without unmounting volumes. -| False - -| *ExperimentalHostUserNamespaceDefaultingGate* -| Enables the disabling of user namespaces. This is for Containers that are using other host projects, host mounts, or Containers that are privileged or using specific non-project capabilities, such as MKNODE, SYS_MODULE, and so forth. This should only be enabled if user project remapping is enabled in the Docker daemon. -| False - -| *GCERegionalPersistentDisk* -| Enables the GCE Persistent Disk feature. -| True - -| *HugePages* -| Enables the allocation and consumption of pre-allocated huge pages. -| True - -| *HyperVcontainer* -| Enables Hyper-V isolation for Windows Containers. -| False - -| *Intializers* -| Enables the dynamic admission control as an extension to the built-in admission controllers. -| False - -| *KubeletPluginsWatcher* -| Enables probe based plugin watcher utility for discovering Kubelet plugins. -| True - -| *LocalStorageCapacityIsolation* -| Enables the consumption of local ephemeral storage and the `sizeLimit` property of an *emptyDir* volume. -| False - -| *Mountcontainers* -| Enables using utility Containers on the host as the volume mount. -| False - -| *MountPropagation* -| Enables sharing a volume mounted by one Container to other Containers or pods. -| True - -| *NodeLease* -| Kubelet uses the new Lease API to report node heartbeats, (Kube) Node Lifecycle Controller uses these heartbeats as a node health signal. -| False - -| *PersistentLocalVolumes* -| Enables the usage of local volume pods. Pod affinity has to be specified if requesting a local volume. -| True - -| *PodPriority* -| Enables the descheduling and preemption of pods based on their priorities. -| True - -| *PodReadinessGates* -| Supports Pod Readiness. -| True - -| *PodShareProcessNamespace* -| Allows all containers in a pod to share a process namespace. -| True - -| *ProcMountType* -| Enables control over ProcMountType for containers. -| False - -| *QOSReserved* -| Allows resource reservations at the QoS level preventing pods at lower QoS levels from bursting into resources requested at higher QoS levels (memory only for now). -| False - -| *ResourceLimitsPriorityFunction* -| Enables a scheduler priority function that assigns a lowest possible score of `1` to a node that satisfies at least one of the input pod CPU and memory limits. The intent is to break ties between nodes with same scores. -| False - -| *ResourceQuotaScopeSelectors* -| Enables resource quota scope selectors. -| True - -| *RotateKubeletClientCertificate* -| Enables the rotation of the client TLS certificate on the cluster. -| True - -| *RotateKubeletServerCertificate* -| Enables the rotation of the server TLS certificate on the cluster. -| True - -| *RunAsGroup* -| Enables control over the primary group ID set on the init processes of Containers. -| False - -| *RuntimeClass* -| Enables RuntimeClass, for selecting between multiple runtimes to run a pod. -| False - -| *ScheduleDaemonSetPods* -| Enables DaemonSet pods to be scheduled by the default scheduler instead of the DaemonSet controller. -| True - -| *SCTPSupport* -| Enables SCTP as new protocol for Service ports, NetworkPolicy, and ContainerPort in Pod/Containers definition. -| False - -| *ServiceNodeExclusion* -| Enables the exclusion of nodes from load balancers created by a cloud provider. -| False - -| *StorageObjectInUseProtection* -| Enables postponing the deletion of persistent volume or persistent volume claim objects if they are still being used. -| True - -| *StreamingProxyRedirects* -| Instructs the API server to intercept and follow redirects from the backend kubelet for streaming requests. -| True - -| *SupportIPVSProxyMode* -| Enables providing in-cluster service load balancing using IP virtual servers. -| True - -| *SupportPodPidsLimit* -| Enables support for limiting the number of processes (PIDs) running in a pod. -| True - -| *Sysctls* -| Enables pods to set sysctls on a pod. -| True - -| *TaintBasedEvictions* -| Enables evicting pods from nodes based on taints on nodes and tolerations on pods. -| False - -| *TaintNodesByCondition* -| Enables automatic tainting nodes based on node conditions. -| True - -| *TokenRequest* -| Enables the TokenRequest endpoint on service account resources. -| True - -| *TokenRequestProjection* -| Enables ServiceAccountTokenVolumeProjection support in ProjectedVolumes. -| True - -| *TTLAfterFinished* -| Allows TTL controller to clean up Pods and Jobs after they finish. -| False - -| *ValidateProxyRedirects* -| Controls whether the apiserver should validate that redirects are only followed to the same host. Only used if StreamingProxyRedirects is enabled. -| False - -| *VolumeScheduling* -| Enables volume-topology-aware scheduling and make the persistent volume claim (PVC) binding aware of scheduling decisions. It also enables the usage of local volumes types when used together with the *PersistentLocalVolumes* feature gate. -| True - -| *VolumeSnapshotDataSource* -| Enables volume snapshot data source support. -| False - -| *VolumeSubpath* -| Allows mounting a subpath of a volume in a container. Do not remove this feature gate even though it's GA. -| True - -| *VolumeSubpathEnvExpansion* -| Allows subpath environment variable substitution. Only applicable if the VolumeSubpath feature is also enabled. -| False - -|=== - diff --git a/_unused_topics/nodes-cluster-overcommit-node-memory.adoc b/_unused_topics/nodes-cluster-overcommit-node-memory.adoc deleted file mode 100644 index df87f582400a..000000000000 --- a/_unused_topics/nodes-cluster-overcommit-node-memory.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc - -[id="nodes-cluster-overcommit-node-memory_{context}"] - -= Reserving memory across quality of service tiers - -You can use the `qos-reserved` parameter to specify a percentage of memory to be reserved -by a pod in a particular QoS level. This feature attempts to reserve requested resources to exclude pods -from lower OoS classes from using resources requested by pods in higher QoS classes. - -By reserving resources for higher QOS levels, pods that do not have resource limits are prevented from encroaching on the resources -requested by pods at higher QoS levels. - -.Prerequisites - -. Obtain the label associated with the static Machine Config Pool CRD for the type of node you want to configure. -Perform one of the following steps: - -.. View the Machine Config Pool: -+ ----- -$ oc describe machineconfigpool ----- -+ -For example: -+ -[source,yaml] ----- -$ oc describe machineconfigpool worker - -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool -metadata: - creationTimestamp: 2019-02-08T14:52:39Z - generation: 1 - labels: - custom-kubelet: small-pods <1> ----- -<1> If a label has been added it appears under `labels`. - -.. If the label is not present, add a key/value pair: -+ ----- -$ oc label machineconfigpool worker custom-kubelet=small-pods ----- - -.Procedure - -. Create a Custom Resource (CR) for your configuration change. -+ -.Sample configuration for a disabling CPU limits -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: disable-cpu-units <1> -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: small-pods <2> - kubeletConfig: - cgroups-per-qos: - - true - cgroup-driver: - - 'systemd' - cgroup-root: - - '/' - qos-reserved: <3> - - 'memory=50%' ----- -<1> Assign a name to CR. -<2> Specify the label to apply the configuration change. -<3> Specifies how pod resource requests are reserved at the QoS level. -{product-title} uses the `qos-reserved` parameter as follows: -- A value of `qos-reserved=memory=100%` will prevent the `Burstable` and `BestEffort` QOS classes from consuming memory -that was requested by a higher QoS class. This increases the risk of inducing OOM -on `BestEffort` and `Burstable` workloads in favor of increasing memory resource guarantees -for `Guaranteed` and `Burstable` workloads. -- A value of `qos-reserved=memory=50%` will allow the `Burstable` and `BestEffort` QOS classes -to consume half of the memory requested by a higher QoS class. -- A value of `qos-reserved=memory=0%` -will allow a `Burstable` and `BestEffort` QoS classes to consume up to the full node -allocatable amount if available, but increases the risk that a `Guaranteed` workload -will not have access to requested memory. This condition effectively disables this feature. diff --git a/_unused_topics/nodes-containers-using-about.adoc b/_unused_topics/nodes-containers-using-about.adoc deleted file mode 100644 index 0213c6acecc1..000000000000 --- a/_unused_topics/nodes-containers-using-about.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-using.adoc - -[id="nodes-containers-using-about_{context}"] -= Understanding Containers - -The basic units of {product-title} applications are called _containers_. -link:https://access.redhat.com/articles/1353593[Linux container technologies] -are lightweight mechanisms for isolating running processes so that they are -limited to interacting with only their designated resources. - -Many application instances can be running in containers on a single host without -visibility into each others' processes, files, network, and so on. Typically, -each container provides a single service (often called a "micro-service"), such -as a web server or a database, though containers can be used for arbitrary -workloads. - -The Linux kernel has been incorporating capabilities for container technologies -for years. {product-title} and -Kubernetes add the ability to orchestrate containers across -multi-host installations. diff --git a/_unused_topics/nodes-containers-using-ssh.adoc b/_unused_topics/nodes-containers-using-ssh.adoc deleted file mode 100644 index 868386626226..000000000000 --- a/_unused_topics/nodes-containers-using-ssh.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-using.adoc - -[id="nodes-containers-using-ssh_{context}"] -= Opening a Remote Shell to Containers - -The `oc rsh` command allows you to locally access and manage tools that are on -the system. The secure shell (SSH) is the underlying technology and industry -standard that provides a secure connection to the application. Access to -applications with the shell environment is protected and restricted with -Security-Enhanced Linux (SELinux) policies. - -While in the remote shell, you can issue commands as if you are inside the -container and perform local operations like monitoring, debugging, and using CLI -commands specific to what is running in the container. - -For example, in a MySQL container, you can count the number of records in the -database by invoking the `mysql` command, then using the prompt to type in the `SELECT` command. You can -also use commands like `ps(1)` and `ls(1)` for validation. - -`BuildConfigs` and `DeployConfigs` map out how you want things to look and -pods (with containers inside) are created and dismantled as needed. Your changes -are not persistent. If you make changes directly within the container and that -container is destroyed and rebuilt, your changes will no longer exist. - -[NOTE] -==== -You can use the `oc exec` c to execute a command remotely. However, the `oc rsh` command provides an easier way -to keep a remote shell open persistently. -==== - -.Procedure - -. Open a console on a system networked to connect to the node where your pod is located. - -. Open a remote shell session to a container: -+ ----- -$ oc rsh ----- - -[NOTE] -==== -For help with usage, options, and to see examples: ----- -$ oc rsh -h ----- -==== diff --git a/_unused_topics/nodes-nodes-audit-log-advanced.adoc b/_unused_topics/nodes-nodes-audit-log-advanced.adoc deleted file mode 100644 index ed5d789df839..000000000000 --- a/_unused_topics/nodes-nodes-audit-log-advanced.adoc +++ /dev/null @@ -1,140 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-audit-log.adoc - -[id="nodes-nodes-audit-log-advanced_{context}"] -= Advanced Audit - -*DEPRECATED for the moment* - -The advanced audit feature provides several improvements over the -basic audit functionality, including fine-grained events filtering and multiple output back ends. - -To enable the advanced audit feature, provide the following values in the -`openshift_master_audit_config` parameter: - ----- -openshift_master_audit_config={"enabled": true, "auditFilePath": "/var/lib/origin/oscp-audit.log", "maximumFileRetentionDays": 14, "maximumFileSizeMegabytes": 500, "maximumRetainedFiles": 5, "policyFile": "/etc/origin/master/adv-audit.yaml", "logFormat":"json"} ----- - -[IMPORTANT] -==== -The policy file *_/etc/origin/master/adv-audit.yaml_* must be available on each master node. -==== - - -The following table contains additional options you can use. - -.Advanced Audit Configuration Parameters - -[cols="3a,6a",options="header"] -|=== -| Parameter Name | Description - -|`policyFile` -|Path to the file that defines the audit policy configuration. - -|`policyConfiguration` -|An embedded audit policy configuration. - -|`logFormat` -|Specifies the format of the saved audit logs. Allowed values are `legacy` (the -format used in basic audit), and `json`. - -|`webHookKubeConfig` -|Path to a `.kubeconfig`-formatted file that defines the audit webhook -configuration, where the events are sent to. - -|`webHookMode` -|Specifies the strategy for sending audit events. Allowed values are `block` -(blocks processing another event until the previous has fully processed) and -`batch` (buffers events and delivers in batches). -|=== - -[IMPORTANT] -==== -To enable the advanced audit feature, you must provide either `policyFile` *or* -`policyConfiguration` describing the audit policy rules: -==== - -.Sample Audit Policy Configuration -[source,yaml] ----- -apiVersion: audit.k8s.io/v1beta1 -kind: Policy -rules: - - # Do not log watch requests by the "system:kube-proxy" on endpoints or services - - level: None <1> - users: ["system:kube-proxy"] <2> - verbs: ["watch"] <3> - resources: <4> - - group: "" - resources: ["endpoints", "services"] - - # Do not log authenticated requests to certain non-resource URL paths. - - level: None - userGroups: ["system:authenticated"] <5> - nonResourceURLs: <6> - - "/api*" # Wildcard matching. - - "/version" - - # Log the request body of configmap changes in kube-system. - - level: Request - resources: - - group: "" # core API group - resources: ["configmaps"] - # This rule only applies to resources in the "kube-system" namespace. - # The empty string "" can be used to select non-namespaced resources. - namespaces: ["kube-system"] <7> - - # Log configmap and secret changes in all other namespaces at the metadata level. - - level: Metadata - resources: - - group: "" # core API group - resources: ["secrets", "configmaps"] - - # Log all other resources in core and extensions at the request level. - - level: Request - resources: - - group: "" # core API group - - group: "extensions" # Version of group should NOT be included. - - # A catch-all rule to log all other requests at the Metadata level. - - level: Metadata <1> - - # Log login failures from the web console or CLI. Review the logs and refine your policies. - - level: Metadata - nonResourceURLs: - - /login* <8> - - /oauth* <9> ----- -<1> There are four possible levels every event can be logged at: -+ -* `None` - Do not log events that match this rule. -+ -* `Metadata` - Log request metadata (requesting user, time stamp, resource, verb, -etc.), but not request or response body. This is the same level as the one used -in basic audit. -+ -* `Request` - Log event metadata and request body, but not response body. -+ -* `RequestResponse` - Log event metadata, request, and response bodies. -<2> A list of users the rule applies to. An empty list implies every user. -<3> A list of verbs this rule applies to. An empty list implies every verb. This is - Kubernetes verb associated with API requests (including `get`, `list`, `watch`, - `create`, `update`, `patch`, `delete`, `deletecollection`, and `proxy`). -<4> A list of resources the rule applies to. An empty list implies every resource. -Each resource is specified as a group it is assigned to (for example, an empty for -Kubernetes core API, batch, build.openshift.io, etc.), and a resource list from -that group. -<5> A list of groups the rule applies to. An empty list implies every group. -<6> A list of non-resources URLs the rule applies to. -<7> A list of namespaces the rule applies to. An empty list implies every namespace. -<8> Endpoint used by the web console. -<9> Endpoint used by the CLI. - -For more information on advanced audit, see the -link:https://kubernetes.io/docs/tasks/debug-application-cluster/audit[Kubernetes -documentation] - diff --git a/_unused_topics/nodes-nodes-resources-configuring-viewing.adoc b/_unused_topics/nodes-nodes-resources-configuring-viewing.adoc deleted file mode 100644 index 8c8b62e45eeb..000000000000 --- a/_unused_topics/nodes-nodes-resources-configuring-viewing.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-resources-configuring.adoc - -[id="nodes-nodes-resources-configuring-setting_{context}"] -= Viewing Node Allocatable Resources and Capacity - -As an administrator, you can view the current capacity and allocatable resources of a specific node. - -.Procedure - -To see a node's current capacity and allocatable resources: - -. Run the following command: - ----- -$ oc get node/ -o yaml ----- - -. Locate the following section in the output: -+ -[source,yaml] ----- -... -status: -... - allocatable: - cpu: "4" - memory: 8010948Ki - pods: "110" - capacity: - cpu: "4" - memory: 8010948Ki - pods: "110" -... ----- diff --git a/_unused_topics/nodes-nodes-working-adding.adoc b/_unused_topics/nodes-nodes-working-adding.adoc deleted file mode 100644 index 5efb65bc72ba..000000000000 --- a/_unused_topics/nodes-nodes-working-adding.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-working.adoc - -[id="nodes-nodes-working-adding_{context}"] -= Adding new nodes to your cluster - -//// -this entire section is obsolete for 4.0. nodes are added to the cluster using MachineSets in 4.0. -https://github.com/openshift/openshift-docs/pull/12964#discussion_r242781872 -//// diff --git a/_unused_topics/nodes-pods-daemonsets-pods.adoc b/_unused_topics/nodes-pods-daemonsets-pods.adoc deleted file mode 100644 index 74520493154b..000000000000 --- a/_unused_topics/nodes-pods-daemonsets-pods.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-daemonsets.adoc - -[id="nodes-pods-daemonsets-pods_{context}"] -= About Scheduling DaemonSets with the default scheduler - -In {product-title}, the scheduler selects the Node that a Pod runs on. However, in previous versions of {product-title}, DaemonSet pods were created and scheduled by the DaemonSet controller. - -The `ScheduleDaemonSetPods` feature, enabled by default, forces {product-title} to schedule DaemonSets using the default scheduler, instead of the DaemonSet controller. -The DaemonSet controller adds the `NodeAffinity` parameter to the DaemonSet pods, instead of the `.spec.nodeName` parameter. The default scheduler then binds the pod to the target host. If the DaemonSet pod is already configured for node affinity, the affinity is replaced. The DaemonSet controller only performs these operations when creating or modifying DaemonSet pods, and no changes are made to the `spec.template` parameter of the DaemonSet. - ----- -nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchFields: - - key: metadata.name - operator: In - values: - - target-host-name ----- - -In addition, the DaemonSet controller adds the `node.kubernetes.io/unschedulable:NoSchedule` toleration to DaemonSet Pods. The default scheduler ignores unschedulable Nodes when scheduling DaemonSet Pods. diff --git a/_unused_topics/nodes-pods-priority-examples.adoc b/_unused_topics/nodes-pods-priority-examples.adoc deleted file mode 100644 index 92d898eb2d3f..000000000000 --- a/_unused_topics/nodes-pods-priority-examples.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-priority.adoc - -[id="nodes-pods-priority-examples_{context}"] -= Pod priority example scenarios - -Pod priority and preemption assigns a priority to pods for scheduling. The scheduler will preempt (evict) lower-priority pods to schedule higher-priority pods. - -Typical preemption scenario:: -*Pod P* is a pending pod. - -. The scheduler locates *Node N*, where the removal of one or more pods enables *Pod P* to be scheduled on that node. - -. The scheduler deletes the lower-priority pods from the *Node N* and schedules *Pod P* on the node. - -. The `nominatedNodeName` field of *Pod P* is set to the name of *Node N*. - -[NOTE] -==== -*Pod P* is not necessarily scheduled to the nominated node. -==== - -Preemption and termination periods:: -The preempted pod has a long termination period. - -. The scheduler preempts a lower-priority pod on *Node N*. - -. The scheduler waits for the pod to gracefully terminate. - -. For other scheduling reasons, *Node M* becomes available. - -. The scheduler can then schedule *Pod P* on *Node M*. - -//// -Under consideration for future release -Pod priority and cross-node preemption:: -*Pod P* is being considered for *Node N*. - -. *Pod Q* is running on another node in the same zone as *Node N*. - -. *Pod P* has zone-wide anti-affinity with *Pod Q*, meaning *Pod P* cannot be scheduled in the same zone as *Pod Q*. -+ -There are no other cases of anti-affinity between *Pod P* and other pods in the zone. - -. To schedule *Pod P* on *Node N*, the scheduler must preempt *Pod Q* to remove the pod anti-affinity violation, allowing the scheduler to schedule *Pod P* on *Node N*. - -The scheduler can preempt *Pod Q*, but scheduler does not perform cross-node preemption. So, Pod P will be deemed unschedulable on Node N. -//// - diff --git a/_unused_topics/nodes-scheduler-node-antiaffinity-configuring.adoc b/_unused_topics/nodes-scheduler-node-antiaffinity-configuring.adoc deleted file mode 100644 index 662f7389bf94..000000000000 --- a/_unused_topics/nodes-scheduler-node-antiaffinity-configuring.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-affinity.adoc - -[id="nodes-scheduler-node-affinity-configuring_{context}"] -= Configuring node affinity rules - -You can configure two types of node affinity rules: required and preferred. - -== Configuring a required node affinity rule - -Required rules *must* be met before a pod can be scheduled on a node. - -.Procedure - -The following steps demonstrate a simple configuration that creates a node and a pod that the scheduler is required to place on the node. - -. Add a label to a node using the `oc label node` command: -+ ----- -$ oc label node node1 e2e-az-name=e2e-az1 ----- - -. In the pod specification, use the `nodeAffinity` stanza to configure the `requiredDuringSchedulingIgnoredDuringExecution` parameter: -+ -.. Specify the key and values that must be met. If you want the new pod to be scheduled on the node you edited, use the same `key` and `value` parameters as the label in the node. -+ -.. Specify an `operator`. The operator can be `In`, `NotIn`, `Exists`, `DoesNotExist`, `Lt`, or `Gt`. For example, use the operator `In` to require the label to be in the node: -+ ----- -spec: - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: e2e-az-name - operator: In - values: - - e2e-az1 - - e2e-az2 ----- - -. Create the pod: -+ ----- -$ oc create -f e2e-az2.yaml ----- - -== Configuring a Preferred Node Affinity Rule - -Preferred rules specify that, if the rule is met, the scheduler tries to enforce the rules, but does not guarantee enforcement. - -.Procedure - -The following steps demonstrate a simple configuration that creates a node and a pod that the scheduler tries to place on the node. - -. Add a label to a node using the `oc label node` command: -+ ----- -$ oc label node node1 e2e-az-name=e2e-az3 ----- - -. In the pod specification, use the `nodeAffinity` stanza to configure the `preferredDuringSchedulingIgnoredDuringExecution` parameter: -+ -.. Specify a weight for the node, as a number 1-100. The node with highest weight is preferred. -+ -.. Specify the key and values that must be met. If you want the new pod to be scheduled on the node you edited, use the same `key` and `value` parameters as the label in the node: -+ ----- - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 1 - preference: - matchExpressions: - - key: e2e-az-name - operator: In - values: - - e2e-az3 ----- - -. Specify an `operator`. The operator can be `In`, `NotIn`, `Exists`, `DoesNotExist`, `Lt`, or `Gt`. For example, use the operator `In` to require the label to be in the node. - -. Create the pod. -+ ----- -$ oc create -f e2e-az3.yaml ----- diff --git a/_unused_topics/nodes-scheduler-taints-tolerations-examples.adoc b/_unused_topics/nodes-scheduler-taints-tolerations-examples.adoc deleted file mode 100644 index df2518f4f07c..000000000000 --- a/_unused_topics/nodes-scheduler-taints-tolerations-examples.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-taints-tolerations.adoc - -[id="nodes-scheduler-taints-tolerations-examples_{context}"] -= Example taint and toleration scenarios - -Taints and tolerations are a flexible way to steer pods away from nodes or evict pods that should not be running on a node. A few of typical scenarios are: - -* Dedicating a node for a user -* Binding a user to a node -* Dedicating nodes with special hardware - -[id="nodes-scheduler-taints-tolerations-examples-user_{context}"] -== Dedicating a Node for a User - -You can specify a set of nodes for exclusive use by a particular set of users. - -.Procedure - -To specify dedicated nodes: - -. Add a taint to those nodes: -+ -For example: -+ ----- -$ oc adm taint nodes node1 dedicated=groupName:NoSchedule ----- - -. Add a corresponding toleration to the pods by writing a custom admission controller. -+ -Only the pods with the tolerations are allowed to use the dedicated nodes. - -[id="nodes-scheduler-taints-tolerations-examples-binding_{context}"] -== Binding a User to a Node - -You can configure a node so that particular users can use only the dedicated nodes. - -.Procedure - -To configure a node so that users can use only that node: - -. Add a taint to those nodes: -+ -For example: -+ ----- -$ oc adm taint nodes node1 dedicated=groupName:NoSchedule ----- - -. Add a corresponding toleration to the pods by writing a custom admission controller. -+ -The admission controller should add a node affinity to require that the pods can only schedule onto nodes labeled with the `key:value` label (`dedicated=groupName`). - -. Add a label similar to the taint (such as the `key:value` label) to the dedicated nodes. - -[id="nodes-scheduler-taints-tolerations-examples-special_{context}"] -== Nodes with Special Hardware - -In a cluster where a small subset of nodes have specialized hardware (for example GPUs), you can use taints and tolerations to keep pods that do not need the specialized hardware off of those nodes, leaving the nodes for pods that do need the specialized hardware. You can also require pods that need specialized hardware to use specific nodes. - -.Procedure - -To ensure pods are blocked from the specialized hardware: - -. Taint the nodes that have the specialized hardware using one of the following commands: -+ ----- -$ oc adm taint nodes disktype=ssd:NoSchedule -$ oc adm taint nodes disktype=ssd:PreferNoSchedule ----- - -. Adding a corresponding toleration to pods that use the special hardware using an admission controller. - -For example, the admission controller could use some characteristic(s) of the pod to determine that the pod should be allowed to use the special nodes by adding a toleration. - -To ensure pods can only use the specialized hardware, you need some additional mechanism. For example, you could label the nodes that have the special hardware and use node affinity on the pods that need the hardware. diff --git a/_unused_topics/nodes-scheduler-taints-tolerations-seconds.adoc b/_unused_topics/nodes-scheduler-taints-tolerations-seconds.adoc deleted file mode 100644 index a8a788cb0aa8..000000000000 --- a/_unused_topics/nodes-scheduler-taints-tolerations-seconds.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-taints-tolerations.adoc - -[id="nodes-scheduler-taints-tolerations-seconds_{context}"] -= Setting a default value for toleration seconds - -When using taints and tolerations, if taints are added to an existing node, non-matching pods on that node will be evicted. You can modify the time allowed before pods are evicted using the toleration seconds plug-in, which sets the eviction period at five minutes, by default. - -.Procedure - -To enable Default Toleration Seconds: - -Create an *AdmissionConfiguration* object: -+ ----- -kind: AdmissionConfiguration -apiVersion: apiserver.k8s.io/v1alpha1 -plugins: -- name: DefaultTolerationSeconds -...---- diff --git a/_unused_topics/pod-using-a-different-service-account.adoc b/_unused_topics/pod-using-a-different-service-account.adoc deleted file mode 100644 index 29794c9f858c..000000000000 --- a/_unused_topics/pod-using-a-different-service-account.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * orphaned - -[id="pod-using-a-different-service-account_{context}"] -= Running a pod with a different service account - -You can run a pod with a service account other than the default: - -.Prerequisites - -* Install the `oc` command line interface. -* Configure a service account. -* Create a DeploymentConfig. - -.Procedure - -. Edit the DeploymentConfig: -+ ----- -$ oc edit dc/ ----- - -. Add the `serviceAccount` and `serviceAccountName` parameters to the `spec` -field, and specify the service account that you want to use: -+ ----- -spec: - securityContext: {} - serviceAccount: - serviceAccountName: ----- diff --git a/_unused_topics/rbac-updating-policy-definitions.adoc b/_unused_topics/rbac-updating-policy-definitions.adoc deleted file mode 100644 index 1a2e45a62e90..000000000000 --- a/_unused_topics/rbac-updating-policy-definitions.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * orphaned - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[id="updating-policy-definitions_{context}"] -= Updating policy definitions - -During a cluster upgrade, and on every restart of any master, the -default cluster roles are automatically reconciled to restore any missing permissions. - -If you customized default cluster roles and want to ensure a role reconciliation -does not modify them, you must take the following actions. - -.Procedure - -. Protect each role from reconciliation: -+ ----- -$ oc annotate clusterrole.rbac --overwrite rbac.authorization.kubernetes.io/autoupdate=false ----- -+ -[WARNING] -==== -You must manually update the roles that contain this setting to include any new -or required permissions after upgrading. -==== - -. Generate a default bootstrap policy template file: -+ ----- -$ oc adm create-bootstrap-policy-file --filename=policy.json ----- -+ -[NOTE] -==== -The contents of the file vary based on the {product-title} version, but the file -contains only the default policies. -==== - -. Update the *_policy.json_* file to include any cluster role customizations. - -. Use the policy file to automatically reconcile roles and role bindings that -are not reconcile protected: -+ ----- -$ oc auth reconcile -f policy.json ----- - -. Reconcile Security Context Constraints: -+ ----- -# oc adm policy reconcile-sccs \ - --additive-only=true \ - --confirm ----- -endif::[] diff --git a/_unused_topics/rhcos-restore-node-scan-with-stackrox-scanner.adoc b/_unused_topics/rhcos-restore-node-scan-with-stackrox-scanner.adoc new file mode 100644 index 000000000000..a6b5fb0395a4 --- /dev/null +++ b/_unused_topics/rhcos-restore-node-scan-with-stackrox-scanner.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scan-rhcos-node-host.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="rhcos-restore-node-scan-stackrox-scanner_{context}"] += Restoring {op-system} node scanning with the StackRox Scanner + +[role="_abstract"] +If you use {ocp}, you can enable scanning of {op-system-first} nodes for vulnerabilities by using {rh-rhacs-first}. +This feature is available with both the StackRox Scanner and Scanner V4. +Follow this procedure if you want to use the StackRox Scanner to scan {op-system-first} nodes, +but you want to keep using Scanner V4 to scan other nodes. +//Should this module be deleted? Why would the user want to keep scanning nodes with StackRox scanner since Scanner V4 now scans nodes and is installed by default? + +.Prerequisites +* For scanning {op-system} node hosts of the secured cluster, you must have installed Secured Cluster services on {ocp} {ocp-supported-version} or later. For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. For life cycle support information for {product-title-short}, see the link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. + +.Procedure + +To enable node indexing, also known as node scanning, by using the StackRox Scanner: + +. Ensure that the StackRox Scanner is deployed in the Central cluster: ++ +[source,terminal] +---- +$ kubectl -n stackrox get deployment scanner scanner-db<1> +---- +<1> For {ocp}, use `oc` instead of `kubectl`. +. In the Central pod, on the `central` container, set `ROX_NODE_INDEX_ENABLED` to `false` by running the following command on the Central cluster: ++ +[source,terminal] +---- +$ kubectl -n stackrox set env deployment/central ROX_NODE_INDEX_ENABLED=false<1> +---- +<1> For {ocp}, use `oc` instead of `kubectl`. +. In the Collector Daemonset, in the `compliance` container, set `ROX_CALL_NODE_INVENTORY_ENABLED` to `true` by running the following command on all secured clusters where you want to enable node scanning: ++ +[source,terminal] +---- +$ kubectl -n stackrox set env daemonset/collector ROX_CALL_NODE_INVENTORY_ENABLED=true<1> +---- +<1> For {ocp}, use `oc` instead of `kubectl`. +. To verify that node scanning is working, examine the Central logs for the following message: ++ +[source,text] +---- +Scanned node inventory (id: ) with components. +---- ++ +where: + +:: Specifies the number of discovered components. +:: Specifies the name of the node. +:: Specifies the internal ID of the node. + diff --git a/_unused_topics/running-modified-installation.adoc b/_unused_topics/running-modified-installation.adoc deleted file mode 100644 index f2c75c4d0d68..000000000000 --- a/_unused_topics/running-modified-installation.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * TBD - -[id="running-modified-installation_{context}"] -= Running a modified {product-title} installation - -Running a default {product-title} {product-version} cluster is the best way to ensure that the {product-title} cluster you get will be easy to install, maintain, and upgrade going forward. However, because you may want to add to or change your {product-title} cluster, openshift-install offers several ways to modify the default installation or add to it later. These include: - -* Creating an install-config file: Changing the contents of the install-config file, to identify things like the cluster name and credentials, is fully supported. -* Creating ignition-config files: Viewing ignition-config files, which define how individual nodes are configured when they are first deployed, is fully supported. However, changing those files is not supported. -* Creating Kubernetes (manifests) and {product-title} (openshift) manifest files: You can view manifest files in the manifests and openshift directories to see how Kubernetes and {product-title} features are configured, respectively. Changing those files is not supported. - -Whether you want to change your {product-title} installation or simply gain a deeper understanding of the details of the installation process, the goal of this section is to step you through an {product-title} installation. Along the way, it covers: - -* The underlying activities that go on under the covers to bring up an {product-title} cluster -* Major components that are leveraged ({op-system}, Ignition, Terraform, and so on) -* Opportunities to customize the install process (install configs, Ignition configs, manifests, and so on) diff --git a/_unused_topics/security-context-constraints-restore-defaults.adoc b/_unused_topics/security-context-constraints-restore-defaults.adoc deleted file mode 100644 index 089b41a32468..000000000000 --- a/_unused_topics/security-context-constraints-restore-defaults.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * orphaned - -[id="security-context-constraints-restore-defaults_{context}"] -= Restoring the default Security Context Constraints - -If the default Security Context Constraints (SCCs) are not present when the -master restarts, they are created again. To reset SCCs to the default values or -update existing SCCs to new default definitions after an upgrade you can either: - -. Delete any SCC you want to reset and restart the master. -. Use the `oc adm policy reconcile-sccs` command. - -The `oc adm policy reconcile-sccs` command sets all SCC policies to the default -values but retains any additional users, groups, labels, annotations, and -priorities you set. - -To view which SCCs will be changed, you can run the command with no options or -by specifying your preferred output with the `-o ` option. - -After reviewing it is recommended that you back up your existing SCCs and then -use the `--confirm` option to persist the data. - -[NOTE] -==== -If you want to reset priorities and grants, use the `--additive-only=false` option. -==== - -[NOTE] -==== -If you customized settings other than priority, users, groups, labels, or annotations in an -SCC, you lose those settings when you reconcile. -==== diff --git a/_unused_topics/security-overview.adoc b/_unused_topics/security-overview.adoc deleted file mode 100644 index 2f5170e0e604..000000000000 --- a/_unused_topics/security-overview.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -// * orphaned - -[id="security-overview_{context}"] -= Security in {product-title} - -The {product-title} and Kubernetes APIs authenticate users who present -credentials and then authorizes them based on their role. Both developers and -administrators can be authenticated through a number of means, primarily -OAuth tokens and X.509 client certificates. OAuth tokens are signed with JSON -Web Algorithm _RS256_, which is RSA signature algorithm PKCS#1 v1.5 with SHA-256. - -Developers, the clients of the system, typically make REST API calls from a -client program like `oc` or to the {product-title} web console through their browser. -Both methods use OAuth bearer tokens for most communication. Infrastructure components. -like nodes, use client certificates that are generated by the system that contain their -identities. Infrastructure components that run in containers use a token that is -associated with their service account to connect to the API. - -Authorization is handled in the {product-title} policy engine, which defines -actions like `create pod` or `list services`, and groups them into roles in a -policy document. Roles are bound to users or groups by the user or group -identifier. When a user or service account attempts an action, the policy engine -checks for one or more of the roles assigned to the user, such as a cluster -administrator or administrator of the current project, before allowing it to -continue. - -ifdef::openshift-origin,openshift-online,openshift-enterprise,openshift-webscale[] -Since every container that runs on the cluster is associated with a service -account, it is also possible to associate secrets to those service accounts and have them -automatically delivered into the container. This secret delivery enables the infrastructure to -manage secrets for pulling and pushing images, builds, and the deployment -components and also allows application code to use those secrets. -endif::[] - -[id="architecture-overview-tls-support_{context}"] -== TLS Support - -All communication channels with the REST API, as well as between master -components such as etcd and the API server, are secured with TLS. TLS provides -strong encryption, data integrity, and authentication of servers with X.509 -server certificates and public key infrastructure. -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -By default, a new internal PKI is created for each deployment of -{product-title}. The internal PKI uses 2048 bit RSA keys and SHA-256 signatures. -endif::[] -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -Custom certificates for public hosts are supported as well. -endif::[] - -{product-title} uses Golang’s standard library implementation of -link:https://golang.org/pkg/crypto/tls/[*crypto/tls*] and does not depend on any -external crypto and TLS libraries. Additionally, the client depends on external -libraries for GSSAPI authentication and OpenPGP signatures. GSSAPI is typically -provided by either MIT Kerberos or Heimdal Kerberos, which both use OpenSSL's -libcrypto. OpenPGP signature verification is handled by libgpgme and GnuPG. - -The insecure versions SSL 2.0 and SSL 3.0 are unsupported and not available. The -{product-title} server and `oc` client only provide TLS 1.2 by default. TLS 1.0 -and TLS 1.1 can be enabled in the server configuration. Both server and client -prefer modern cipher suites with authenticated encryption algorithms and perfect -forward secrecy. Cipher suites with deprecated and insecure algorithms such as -RC4, 3DES, and MD5 are disabled. Some internal clients, like LDAP -authentication, have less restrict settings with TLS 1.0 to 1.2 and more cipher -suites enabled. - -.Supported TLS Versions -[cols="4*", options="header"] -|=== -|TLS Version -|{product-title} Server -|`oc` Client -|Other Clients - -|SSL 2.0 -|Unsupported -|Unsupported -|Unsupported - -|SSL 3.0 -|Unsupported -|Unsupported -|Unsupported - -|TLS 1.0 -|No footnoteref:[tlsconfig,Disabled by default, but can be enabled in the server configuration.] -|No footnoteref:[tlsconfig] -|Maybe footnoteref:[otherclient,Some internal clients, such as the LDAP client.] - -|TLS 1.1 -|No footnoteref:[tlsconfig] -|No footnoteref:[tlsconfig] -|Maybe footnoteref:[otherclient] - -|TLS 1.2 -|*Yes* -|*Yes* -|*Yes* - -|TLS 1.3 -|N/A footnoteref:[tls13,TLS 1.3 is still under development.] -|N/A footnoteref:[tls13] -|N/A footnoteref:[tls13] -|=== - -The following list of enabled cipher suites of {product-title}'s server and `oc` -client are sorted in preferred order: - -- `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305` -- `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305` -- `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` -- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` -- `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384` -- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` -- `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256` -- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` -- `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA` -- `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA` -- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA` -- `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA` -- `TLS_RSA_WITH_AES_128_GCM_SHA256` -- `TLS_RSA_WITH_AES_256_GCM_SHA384` -- `TLS_RSA_WITH_AES_128_CBC_SHA` -- `TLS_RSA_WITH_AES_256_CBC_SHA` diff --git a/_unused_topics/serverless-creating-kubeconfig-file.adoc b/_unused_topics/serverless-creating-kubeconfig-file.adoc deleted file mode 100644 index cecdb2fbba4f..000000000000 --- a/_unused_topics/serverless-creating-kubeconfig-file.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative-client.adoc - -[id="create-kubeconfig-file_{contect}"] -= Creating a `kubeconfig` file - -Use `kubeconfig` files to organize information about clusters, users, namespaces, and authentication mechanisms. The CLI tool uses `kubeconfig` files to communicate with the API server of a cluster. - -.Procedure -* Create a basic `kubeconfig` file from client certificates. Use the following command: - ----- -$ oc adm create-kubeconfig \ - --client-certificate=/path/to/client.crt \ - --client-key=/path/to/client.key \ - --certificate-authority=/path/to/ca.crt ----- \ No newline at end of file diff --git a/_unused_topics/serverless-rn-template-module.adoc b/_unused_topics/serverless-rn-template-module.adoc deleted file mode 100644 index 8f2838bae0e9..000000000000 --- a/_unused_topics/serverless-rn-template-module.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/release-notes.adoc - -[id="serverless-rn-_{context}"] -//update the to match the filename - -= Release Notes for Red Hat {ServerlessProductName} -// add a version, e.g. Technology Preview 1.0.0 - -[id="new-features-_{context}"] -== New features - -[id="fixed-issues-_{context}"] -== Fixed issues - -[id="known-issues-_{context}"] -== Known issues diff --git a/_unused_topics/service-accounts-adding-secrets.adoc b/_unused_topics/service-accounts-adding-secrets.adoc deleted file mode 100644 index 11d925ea62c7..000000000000 --- a/_unused_topics/service-accounts-adding-secrets.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-managing-secrets_{context}"] -== Managing secrets on a service account's pod - -In addition to providing API credentials, a pod's service account determines -which secrets the pod is allowed to use. - -Pods use secrets in two ways: - -* image pull secrets, providing credentials used to pull images for the pod's containers -* mountable secrets, injecting the contents of secrets into containers as files - -To allow a secret to be used as an image pull secret by a service account's -pods, run: - ----- -$ oc secrets link --for=pull ----- - -To allow a secret to be mounted by a service account's pods, run: - ----- -$ oc secrets link --for=mount ----- - -[NOTE] -==== -Limiting secrets to only the service accounts that reference them is disabled by -default. This means that if `serviceAccountConfig.limitSecretReferences` is set -to `false` (the default setting) in the master configuration file, mounting -secrets to a service account's pods with the `--for=mount` option is not -required. However, using the `--for=pull` option to enable using an image pull -secret is required, regardless of the -`serviceAccountConfig.limitSecretReferences` value. -==== - -This example creates and adds secrets to a service account: - ----- -$ oc create secret generic secret-plans \ - --from-file=plan1.txt \ - --from-file=plan2.txt -secret/secret-plans - -$ oc create secret docker-registry my-pull-secret \ - --docker-username=mastermind \ - --docker-password=12345 \ - --docker-email=mastermind@example.com -secret/my-pull-secret - -$ oc secrets link robot secret-plans --for=mount - -$ oc secrets link robot my-pull-secret --for=pull - -$ oc describe serviceaccount robot -Name: robot -Labels: -Image pull secrets: robot-dockercfg-624cx - my-pull-secret - -Mountable secrets: robot-token-uzkbh - robot-dockercfg-624cx - secret-plans - -Tokens: robot-token-8bhpp - robot-token-uzkbh ----- diff --git a/_unused_topics/service-accounts-managing-secrets.adoc b/_unused_topics/service-accounts-managing-secrets.adoc deleted file mode 100644 index cae0fb9bf790..000000000000 --- a/_unused_topics/service-accounts-managing-secrets.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-managing-secrets_{context}"] -= Managing allowed secrets - -You can use the service account's secrets in your application's pods for: - -* Image pull secrets, providing credentials used to pull images for the pod's containers -* Mountable secrets, injecting the contents of secrets into containers as files - -.Procedure - -. Create a secret: -+ ----- -$ oc create secret generic \ - --from-file=.txt - -secret/ ----- - -. To allow a secret to be used as an image pull secret by a service account's -pods, run: -+ ----- -$ oc secrets link --for=pull ----- - -. To allow a secret to be mounted by a service account's pods, run: -+ ----- -$ oc secrets link --for=mount ----- - -. Confirm that the secret was added to the service account: -+ ----- -$ oc describe serviceaccount -Name: -Labels: -Image pull secrets: robot-dockercfg-624cx - my-pull-secret - -Mountable secrets: robot-token-uzkbh - robot-dockercfg-624cx - secret-plans - -Tokens: robot-token-8bhpp - robot-token-uzkbh ----- - -//// -[NOTE] -==== -Limiting secrets to only the service accounts that reference them is disabled by -default. This means that if `serviceAccountConfig.limitSecretReferences` is set -to `false` (the default setting) in the master configuration file, mounting -secrets to a service account's pods with the `--for=mount` option is not -required. However, using the `--for=pull` option to enable using an image pull -secret is required, regardless of the -`serviceAccountConfig.limitSecretReferences` value. -==== -//// diff --git a/_unused_topics/understanding-installation.adoc b/_unused_topics/understanding-installation.adoc deleted file mode 100644 index dbd19c82853d..000000000000 --- a/_unused_topics/understanding-installation.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * TBD - -[id="understanding-installation_{context}"] -= Understanding {product-title} installation - -{product-title} installation is designed to quickly spin up an {product-title} cluster, with the user starting the cluster required to provide as little information as possible. diff --git a/_unused_topics/understanding-workers-masters.adoc b/_unused_topics/understanding-workers-masters.adoc deleted file mode 100644 index 969c5cc6fd70..000000000000 --- a/_unused_topics/understanding-workers-masters.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * - -[id="understanding-workers-masters_{context}"] -= Understanding {product-title} workers and masters - -With installation complete, the cluster is now fully in charge of managing itself. Management of worker (compute) and master (control plane) nodes is done from within the cluster. So, before moving on to what the {product-title} cluster does to help you develop and deploy applications, you should explore how an {product-title} cluster manages itself. For that, we focus on three things; workers, masters (the control plane) and Operators. - -To see which workers and masters are running on your cluster, type: - ----- -$ oc get nodes - -NAME STATUS ROLES AGE VERSION -ip-10-0-0-1.us-east-2.compute.internal Ready worker 4h20m v1.20.0 -ip-10-0-0-2.us-east-2.compute.internal Ready master 4h39m v1.20.0 -ip-10-0-0.3.us-east-2.compute.internal Ready worker 4h20m v1.20.0 -ip-10-0-0-4.us-east-2.compute.internal Ready master 4h39m v1.20.0 -ip-10-0-0-5.us-east-2.compute.internal Ready master 4h39m v1.20.0 -ip-10-0-0-6.us-east-2.compute.internal Ready worker 4h20m v1.20.0 ----- - -To see more information about internal and external IP addresses, the type of operating system ({op-system}), kernel version, and container runtime (CRI-O), add the `-o wide` option. - ----- -$ oc get nodes -o wide - -NAME                                       STATUS ROLES  AGE  VERSION  INTERNAL-IP   EXTERNAL-IP  OS-IMAGE             KERNEL-VERSION             CONTAINER-RUNTIME -ip-10-0-134-252.us-east-2.compute.internal Ready worker 17h v1.20.0 10.0.134.252 Red Hat CoreOS 4.0 3.10.0-957.5.1.el7.x86_64 cri-o://1.13.6-1.rhaos4.0.git2f0cb0d.el7 - -.... ----- diff --git a/_unused_topics/upgrade-cluster-version-definition.adoc b/_unused_topics/upgrade-cluster-version-definition.adoc deleted file mode 100644 index eb6a82098f45..000000000000 --- a/_unused_topics/upgrade-cluster-version-definition.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * none - -[id="upgrade-cluster-version-definition_{context}"] -= ClusterVersion definition - -You can review the `ClusterVersion` definition to see the update history -for your cluster. You can also apply overrides to this definition if your -cluster is not for production or during debugging. - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: ClusterVersion -metadata: - creationTimestamp: 2019-03-22T14:26:41Z - generation: 1 - name: version - resourceVersion: "16740" - selfLink: /apis/config.openshift.io/v1/clusterversions/version - uid: 82f9f2c4-4cae-11e9-90b7-06dc0f62ad38 -spec: - channel: stable-4.3 <1> - overrides: "" <2> - clusterID: 0b1cf91f-c3fb-4f9e-aa02-e0d70c71f6e6 - upstream: https://api.openshift.com/api/upgrades_info/v1/graph - status: <3> - availableUpdates: null <4> - conditions: <5> - - lastTransitionTime: 2019-05-22T07:13:26Z - status: "True" - type: RetrievedUpdates - - lastTransitionTime: 2019-05-22T07:13:26Z - message: Done applying 4.0.0-0.alpha-2019-03-22-124110 - status: "True" - type: Available - - lastTransitionTime: 2019-05-22T07:12:26Z - status: "False" - type: Failing - - lastTransitionTime: 2019-05-22T07:13:26Z - message: Cluster version is 4.0.0-0.alpha-2019-03-22-124110 - status: "False" - type: Progressing ----- -<1> Specify the channel to use to apply non-standard updates to the -cluster. If you do not change the value, the CVO uses the default channel. -+ -[IMPORTANT] -==== -The default channel contains stable updates. Do not modify the -`ClusterVersionSpec.channel` value on production clusters. If you update your -cluster from a different channel without explicit direction from Red Hat -support, your cluster is no longer supported. -==== -<2> A list of overrides for components that the CVO manages. Mark -components as `unmanaged` to prevent the CVO from creating or updating the object. -+ -[IMPORTANT] -==== -Set the `ClusterVersionSpec.overrides` parameter value only during cluster -debugging. Setting this value can prevent successful upgrades and is not -supported for production clusters. -==== -<3> The status of available updates and any in-progress updates. These values display -the version that the cluster is reconciling to, and the conditions -array reports whether the update succeeded, is in progress, or is failing. -All of the `ClusterVersionStatus` values are set by the cluster itself, and you -cannot modify them. -<4> The list of appropriate updates for the cluster. This list is empty if no -updates are recommended, the update service is unavailable, or you specified -an invalid channel. -<5> The condition of the CVO. This section contains both the reason that the -cluster entered its current condition and a message that provides more -information about the condition. - -* `Available` means that the upgrade to the `desiredUpdate` value completed. -* `Progressing` means that an upgrade is in progress. -* `Failing` means that an update is blocked by a temporary or permanent error. diff --git a/administering_a_cluster/cluster-admin-role.adoc b/administering_a_cluster/cluster-admin-role.adoc deleted file mode 100644 index 9e2d0203dbd7..000000000000 --- a/administering_a_cluster/cluster-admin-role.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="cluster-administrator-role"] -= The cluster-admin role -include::modules/common-attributes.adoc[] -:context: cluster-administrator - -toc::[] - -As an administrator of {product-title} with Customer Cloud Subscriptions (link:https://www.openshift.com/dedicated/ccs[CCS]), you can request additional permissions and access to the *cluster-admin* role within your organization's cluster. While logged into an account with the cluster-admin role, users have increased permissions to run privileged security contexts and install additional Operators for their environment. - -include::modules/dedicated-cluster-admin-enable.adoc[leveloffset=+1] - -include::modules/dedicated-cluster-admin-grant.adoc[leveloffset=+1] diff --git a/administering_a_cluster/dedicated-admin-role.adoc b/administering_a_cluster/dedicated-admin-role.adoc deleted file mode 100644 index 6d919e87a4c5..000000000000 --- a/administering_a_cluster/dedicated-admin-role.adoc +++ /dev/null @@ -1,52 +0,0 @@ -[id="dedicated-administrator-role"] -= The dedicated-admin role -include::modules/common-attributes.adoc[] -:context: dedicated-administrator - -toc::[] - -As an administrator of an {product-title} cluster, your account has additional -permissions and access to all user-created projects in your organization's -cluster. While logged in to an account with this role, the basic developer CLI -(the `oc` command) allows you increased visibility and management capabilities -over objects across projects, while the administrator CLI (commands under the -`oc adm` command) allow you to complete additional operations. - -[NOTE] -==== -While your account does have these increased permissions, the actual cluster -maintenance and host configuration is still performed by the OpenShift -Operations Team. If you would like to request a change to your cluster that you -cannot perform using the administrator CLI, open a support case on the -link:https://access.redhat.com/support/[Red Hat Customer Portal]. -==== - -include::modules/dedicated-logging-in-and-verifying-permissions.adoc[leveloffset=+1] - -include::modules/dedicated-managing-dedicated-administrators.adoc[leveloffset=+1] - -include::modules/dedicated-admin-granting-permissions.adoc[leveloffset=+1] - -include::modules/dedicated-managing-service-accounts.adoc[leveloffset=+1] - -include::modules/dedicated-managing-quotas-and-limit-ranges.adoc[leveloffset=+1] - -[id="osd-installing-operators-from-operatorhub_{context}"] -== Installing Operators from the OperatorHub - -{product-title} administrators can install Operators from a curated list -provided by the OperatorHub. This makes the Operator available to all developers -on your cluster to create Custom Resources and applications using that Operator. - -[NOTE] -==== -Privileged and custom Operators cannot be installed. -==== - -Administrators can only install Operators to the default `openshift-operators` -namespace, except for the Cluster Logging Operator, which requires the -`openshift-logging` namespace. - -.Additional resources - -* xref:../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[Adding Operators to a cluster] diff --git a/api-config.yaml b/api-config.yaml index aa8cddc66d66..6870f9a85d6e 100644 --- a/api-config.yaml +++ b/api-config.yaml @@ -231,10 +231,10 @@ apiMap: version: v1 plural: consolequickstarts namespaced: false - - kind: ConsoleYAMLSample + - kind: ConsoleYAMLample group: console.openshift.io version: v1 - plural: consoleyamlsamples + plural: consoleYAMLamples namespaced: false - name: Extension APIs resources: diff --git a/applications/PLACEHOLDER b/applications/PLACEHOLDER deleted file mode 100644 index 985a0e1895b7..000000000000 --- a/applications/PLACEHOLDER +++ /dev/null @@ -1,2 +0,0 @@ -Please leave this file until after Node PRs merge, as is it needed for the topic_yaml. Subtopics are not allowed, apparently, without at least one topic in the TOC - diff --git a/applications/application-health.adoc b/applications/application-health.adoc deleted file mode 100644 index a12106608679..000000000000 --- a/applications/application-health.adoc +++ /dev/null @@ -1,31 +0,0 @@ -:context: application-health -[id="application-health"] -= Monitoring application health by using health checks -include::modules/common-attributes.adoc[] - -toc::[] - - -In software systems, components can become unhealthy due to transient issues such as temporary connectivity loss, configuration errors, or problems with external dependencies. {product-title} applications have a number of options to detect and handle unhealthy containers. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/application-health-about.adoc[leveloffset=+1] - -include::modules/application-health-configuring.adoc[leveloffset=+1] - -include::modules/odc-monitoring-application-health-using-developer-perspective.adoc[leveloffset=+1] - -include::modules/odc-adding-health-checks.adoc[leveloffset=+1] - -include::modules/odc-editing-health-checks.adoc[leveloffset=+1] - -include::modules/odc-monitoring-health-checks.adoc[leveloffset=+1] - -.Additional Resources -* For details on switching to the *Developer* perspective in the web console, see xref:../web_console/odc-about-developer-perspective.adoc#odc-about-developer-perspective[About *Developer* perspective]. -* For details on adding health checks while creating and deploying an application, see *Advanced Options* in the xref:../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating applications using the Developer perspective] section. diff --git a/applications/application_life_cycle_management/creating-applications-using-cli.adoc b/applications/application_life_cycle_management/creating-applications-using-cli.adoc deleted file mode 100644 index 659af8fae33d..000000000000 --- a/applications/application_life_cycle_management/creating-applications-using-cli.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="creating-applications-using-cli"] -= Creating applications using the CLI -include::modules/common-attributes.adoc[] -:context: creating-applications-using-cli - -toc::[] - -You can create an {product-title} application from components that include -source or binary code, images, and templates by using the {product-title} -CLI. - -The set of objects created by `new-app` depends on the artifacts passed as -input: source repositories, images, or templates. - -include::modules/applications-create-using-cli-source-code.adoc[leveloffset=+1] - -include::modules/applications-create-using-cli-image.adoc[leveloffset=+1] - -include::modules/applications-create-using-cli-template.adoc[leveloffset=+1] - -include::modules/applications-create-using-cli-modify.adoc[leveloffset=+1] diff --git a/applications/application_life_cycle_management/creating-apps-from-installed-operators.adoc b/applications/application_life_cycle_management/creating-apps-from-installed-operators.adoc deleted file mode 100644 index eb225a957e9b..000000000000 --- a/applications/application_life_cycle_management/creating-apps-from-installed-operators.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="creating-apps-from-installed-operators"] -= Creating applications from installed Operators -include::modules/common-attributes.adoc[] -:context: creating-apps-from-installed-operators - -toc::[] - -_Operators_ are a method of packaging, deploying, and managing a Kubernetes -application. You can create applications on {product-title} using Operators that -have been installed by a cluster administrator. - -This guide walks developers through an example of creating applications from an -installed Operator using the {product-title} web console. - -.Additional resources - -* See the -xref:../../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Operators] -guide for more on how Operators work and how the Operator Lifecycle Manager is -integrated in {product-title}. - -include::modules/olm-creating-etcd-cluster-from-operator.adoc[leveloffset=+1] diff --git a/applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc b/applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc deleted file mode 100644 index 23728e00f4c9..000000000000 --- a/applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id="odc-creating-applications-using-developer-perspective"] -= Creating applications using the Developer perspective -include::modules/common-attributes.adoc[] -:context: odc-creating-applications-using-developer-perspective - -toc::[] - -The *Developer* perspective in the web console provides you the following options from the *+Add* view to create applications and associated services and deploy them on {product-title}: - -* *From Git*: Use this option to import an existing codebase in a Git repository to create, build, and deploy an application on {product-title}. -* *Container Image*: Use existing images from an image stream or registry to deploy it on to {product-title}. -* *From Dockerfile*: Import a dockerfile from your Git repository to build and deploy an application. -* *YAML*: Use the editor to add YAML or JSON definitions to create and modify resources. -* *From Catalog*: Explore the *Developer Catalog* to select the required applications, services, or source to image builders and add it to your project. -* *Database*: See the *Developer Catalog* to select the required database service and add it to your application. -* *Operator Backed*: Explore the *Developer Catalog* to select and deploy the required Operator-managed service. -* *Helm Chart*: Explore the *Developer Catalog* to select the required Helm chart to simplify deployment of applications and services. - -ifdef::openshift-enterprise,openshift-webscale[] -Note that certain options, such as *Pipelines*, *Event Source*, and *Import Virtual Machines*, are displayed only when the xref:../../cicd/pipelines/installing-pipelines.adoc#op-installing-pipelines-operator-in-web-console_installing-pipelines[OpenShift Pipelines], xref:../../serverless/admin_guide/installing-openshift-serverless.adoc#serverless-install-web-console_installing-openshift-serverless[OpenShift Serverless], and xref:../../virt/install/installing-virt-web.adoc#virt-subscribing-to-the-catalog_installing-virt-web[OpenShift Virtualization] Operators are installed, respectively. -endif::[] - -== Prerequisites -To create applications using the *Developer* perspective ensure that: - -* You have xref:../../web_console/web-console.adoc#web-console[logged in to the web console]. -* You are in the xref:../../web_console/odc-about-developer-perspective.adoc#odc-about-developer-perspective[*Developer* perspective]. -* You have created a project or have access to a project with the appropriate xref:../../authentication/using-rbac.adoc#default-roles_using-rbac[roles and permissions] to create applications and other workloads in {product-title}. - -ifdef::openshift-enterprise,openshift-webscale[] - -To create serverless applications, in addition to the preceding prerequisites, ensure that: - -* You have xref:../../serverless/admin_guide/installing-openshift-serverless.adoc#installing-openshift-serverless[installed the OpenShift Serverless Operator]. -* You have xref:../../serverless/admin_guide/installing-knative-serving.adoc#installing-knative-serving[created a `KnativeServing` resource in the `knative-serving` namespace]. - -endif::[] - -include::modules/odc-creating-sample-applications.adoc[leveloffset=+1] - -include::modules/odc-importing-codebase-from-git-to-create-application.adoc[leveloffset=+1] - -include::modules/odc-using-the-developer-catalog-to-add-services-or-components.adoc[leveloffset=+1] diff --git a/applications/application_life_cycle_management/odc-deleting-applications.adoc b/applications/application_life_cycle_management/odc-deleting-applications.adoc deleted file mode 100644 index b0932bc8b94d..000000000000 --- a/applications/application_life_cycle_management/odc-deleting-applications.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="odc-deleting-applications"] -= Deleting applications -include::modules/common-attributes.adoc[] -:context: odc-deleting-applications - -toc::[] - -You can delete applications created in your project. - -include::modules/odc-deleting-applications-using-developer-perspective.adoc[leveloffset=+1] diff --git a/applications/application_life_cycle_management/odc-editing-applications.adoc b/applications/application_life_cycle_management/odc-editing-applications.adoc deleted file mode 100644 index a3829fdd4737..000000000000 --- a/applications/application_life_cycle_management/odc-editing-applications.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="odc-editing-applications"] -= Editing applications -include::modules/common-attributes.adoc[] -:context: odc-editing-applications - -toc::[] - -You can edit the configuration and the source code of the application you create using the *Topology* view. - -== Prerequisites - -* You have xref:../../web_console/web-console.adoc#web-console[logged in to the web console] and have switched to the xref:../../web_console/odc-about-developer-perspective.adoc#odc-about-developer-perspective[*Developer* perspective]. -* You have the appropriate xref:../../authentication/using-rbac.adoc#default-roles_using-rbac[roles and permissions] in a project to create and modify applications in {product-title}. -* You have xref:../../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[created and deployed an application on {product-title} using the *Developer* perspective]. - -include::modules/odc-editing-source-code-using-developer-perspective.adoc[leveloffset=+1] - -include::modules/odc-editing-application-configuration-using-developer-perspective.adoc[leveloffset=+1] diff --git a/applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc b/applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc deleted file mode 100644 index 5727f0916e4e..000000000000 --- a/applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="odc-viewing-application-composition-using-topology-view"] -= Viewing application composition using the Topology view -include::modules/common-attributes.adoc[] -:context: viewing-application-composition-using-topology-view - -toc::[] - -The *Topology* view in the *Developer* perspective of the web console provides a visual representation of all the applications within a project, their build status, and the components and services associated with them. - -== Prerequisites -To view your applications in the *Topology* view and interact with them, ensure that: - -* You have xref:../../web_console/web-console.adoc#web-console[logged in to the web console]. -* You are in the xref:../../web_console/odc-about-developer-perspective.adoc#odc-about-developer-perspective[*Developer* perspective]. -* You have the appropriate xref:../../authentication/using-rbac.adoc#default-roles_using-rbac[roles and permissions] in a project to create applications and other workloads in {product-title}. -* You have xref:../../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[created and deployed an application on {product-title} using the *Developer* perspective]. - - -include::modules/odc-viewing-application-topology.adoc[leveloffset=+1] - -include::modules/odc-interacting-with-applications-and-components.adoc[leveloffset=+1] - -include::modules/odc-scaling-application-pods-and-checking-builds-and-routes.adoc[leveloffset=+1] - -include::modules/odc-grouping-multiple-components.adoc[leveloffset=+1] - -include::modules/odc-connecting-components.adoc[leveloffset=+1] - -include::modules/odc-labels-and-annotations-used-for-topology-view.adoc[leveloffset=+1] diff --git a/applications/application_life_cycle_management/odc-working-with-helm-charts-using-developer-perspective.adoc b/applications/application_life_cycle_management/odc-working-with-helm-charts-using-developer-perspective.adoc deleted file mode 100644 index 8474a38d02d2..000000000000 --- a/applications/application_life_cycle_management/odc-working-with-helm-charts-using-developer-perspective.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="odc-working-with-helm-charts-using-developer-perspective"] -= Working with Helm charts using the Developer perspective -include::modules/common-attributes.adoc[] -:context: working-with-helm-charts-using-developer-perspective - -toc::[] - - -include::modules/helm-understanding-helm.adoc[leveloffset=+1] - - -You can use the *Developer* perspective in the web console to select and install a chart from the Helm charts listed in the *Developer Catalog*. You can create a Helm release using these charts, upgrade, rollback, and uninstall the release. - - -== Prerequisites - -* You have logged in to the web console and have switched to the xref:../../web_console/odc-about-developer-perspective.adoc#odc-about-developer-perspective[*Developer* perspective]. - -include::modules/odc-installing-helm-charts.adoc[leveloffset=+1] - -include::modules/odc-upgrading-helm-release.adoc[leveloffset=+1] - -include::modules/odc-rolling-back-helm-release.adoc[leveloffset=+1] - -include::modules/odc-uninstalling-helm-release.adoc[leveloffset=+1] diff --git a/applications/deployments/deployment-strategies.adoc b/applications/deployments/deployment-strategies.adoc deleted file mode 100644 index d5ee2d1ff064..000000000000 --- a/applications/deployments/deployment-strategies.adoc +++ /dev/null @@ -1,52 +0,0 @@ -[id="deployment-strategies"] -= Using deployment strategies -include::modules/common-attributes.adoc[] -:context: deployment-strategies - -toc::[] - -A _deployment strategy_ is a way to change or upgrade an application. The aim is to make the change without downtime in a way that the user barely notices the improvements. - -Because the end user usually accesses the application through a route handled by a router, the deployment strategy can focus on `DeploymentConfig` object features or routing features. Strategies that focus on the deployment impact all routes that use the application. Strategies that use router features target individual routes. - -Many deployment strategies are supported through the `DeploymentConfig` object, and some additional strategies are supported through router features. Deployment strategies are discussed in this section. - - -//// -This link keeps breaking Travis for some reason. - -[NOTE] -==== -See -xref:../../applications/deployments/route-based-deployment-strategies.adoc#route-based-deployment-strategies[Using route-based deployment strategies] for more on these additional strategies. -==== -//// - -*Choosing a deployment strategy* - -Consider the following when choosing a deployment strategy: - -- Long-running connections must be handled gracefully. -- Database conversions can be complex and must be done and rolled back along with the application. -- If the application is a hybrid of microservices and traditional components, downtime might be required to complete the transition. -- You must have the infrastructure to do this. -- If you have a non-isolated test environment, you can break both new and old versions. - -A deployment strategy uses readiness checks to determine if a new pod is ready for use. If a readiness check fails, the `DeploymentConfig` object retries to run the pod until it times out. The default timeout is `10m`, a value set in `TimeoutSeconds` in `dc.spec.strategy.*params`. - -include::modules/deployments-rolling-strategy.adoc[leveloffset=+1] -include::modules/deployments-canary-deployments.adoc[leveloffset=+2] -include::modules/deployments-creating-rolling-deployment.adoc[leveloffset=+2] -include::modules/odc-starting-rolling-deployment.adoc[leveloffset=+2] -.Additional resources -- xref:../../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating and deploying applications on {product-title} using the *Developer* perspective] -- xref:../../applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc#odc-viewing-application-composition-using-topology-view[Viewing the applications in your project, verifying their deployment status, and interacting with them in the *Topology* view] - -include::modules/deployments-recreate-strategy.adoc[leveloffset=+1] -include::modules/odc-starting-recreate-deployment.adoc[leveloffset=+1] -.Additional resources -- xref:../../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating and deploying applications on {product-title} using the *Developer* perspective] -- xref:../../applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc#odc-viewing-application-composition-using-topology-view[Viewing the applications in your project, verifying their deployment status, and interacting with them in the *Topology* view] - -include::modules/deployments-custom-strategy.adoc[leveloffset=+1] -include::modules/deployments-lifecycle-hooks.adoc[leveloffset=+1] diff --git a/applications/deployments/managing-deployment-processes.adoc b/applications/deployments/managing-deployment-processes.adoc deleted file mode 100644 index 9a14757ec556..000000000000 --- a/applications/deployments/managing-deployment-processes.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="deployment-operations"] -= Managing deployment processes -include::modules/common-attributes.adoc[] -:context: deployment-operations - -toc::[] - -[id="deploymentconfig-operations"] -== Managing `DeploymentConfig` objects - -`DeploymentConfig` objects can be managed from the {product-title} web console's *Workloads* page or using the `oc` CLI. The following procedures show CLI usage unless otherwise stated. - -include::modules/deployments-starting-deployment.adoc[leveloffset=+2] -include::modules/deployments-viewing-deployment.adoc[leveloffset=+2] -include::modules/deployments-retrying-deployment.adoc[leveloffset=+2] -include::modules/deployments-rolling-back.adoc[leveloffset=+2] -include::modules/deployments-exec-cmd-in-container.adoc[leveloffset=+2] -include::modules/deployments-viewing-logs.adoc[leveloffset=+2] -include::modules/deployments-triggers.adoc[leveloffset=+2] -include::modules/deployments-setting-triggers.adoc[leveloffset=+3] -include::modules/deployments-setting-resources.adoc[leveloffset=+2] -include::modules/deployments-scaling-manually.adoc[leveloffset=+2] -include::modules/deployments-accessing-private-repos.adoc[leveloffset=+2] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/deployments-assigning-pods-to-nodes.adoc[leveloffset=+2] -endif::[] - -ifndef::openshift-online[] -include::modules/deployments-running-pod-svc-acct.adoc[leveloffset=+2] -endif::[] - -//// -== Managing Deployments - -Need docs on managing Deployment objects. -//// diff --git a/applications/deployments/route-based-deployment-strategies.adoc b/applications/deployments/route-based-deployment-strategies.adoc deleted file mode 100644 index aff5376e2c90..000000000000 --- a/applications/deployments/route-based-deployment-strategies.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="route-based-deployment-strategies"] -= Using route-based deployment strategies -include::modules/common-attributes.adoc[] -:context: route-based-deployment-strategies - -toc::[] - -Deployment strategies provide a way for the application to evolve. Some strategies use `DeploymentConfig` objects to make changes that are seen by users of all routes that resolve to the application. Other advanced strategies, such as the ones described in this section, use router features in conjunction with DeploymentConfig` objects to impact specific routes. - -//// -This link keeps breaking Travis for some reason. - -[NOTE] -==== -See -xref:../../applications/deployments/deployment-strategies.adoc#deployment-strategies[Using deployment strategies] -for more on the basic strategy types. -==== -//// - -The most common route-based strategy is to use a _blue-green deployment_. The new version (the green version) is brought up for testing and evaluation, while the users still use the stable version (the blue version). When ready, the users are switched to the green version. If a problem arises, you can switch back to the blue version. - -A common alternative strategy is to use _A/B versions_ that are both active at the same time and some users use one version, and some users use the other version. This can be used for experimenting with user interface changes and other features to get user feedback. It can also be used to verify proper operation in a production context where problems impact a limited number of users. - -A canary deployment tests the new version but when a problem is detected it quickly falls back to the previous version. This can be done with both of the above strategies. - -The route-based deployment strategies do not scale the number of pods in the services. To maintain desired performance characteristics the deployment configurations might have to be scaled. - -include::modules/deployments-proxy-shards.adoc[leveloffset=+1] -include::modules/deployments-n1-compatibility.adoc[leveloffset=+1] -include::modules/deployments-graceful-termination.adoc[leveloffset=+1] -include::modules/deployments-blue-green.adoc[leveloffset=+1] -include::modules/deployments-ab-testing.adoc[leveloffset=+1] -include::modules/deployments-ab-testing-lb.adoc[leveloffset=+2] diff --git a/applications/deployments/what-deployments-are.adoc b/applications/deployments/what-deployments-are.adoc deleted file mode 100644 index 66593b5cab70..000000000000 --- a/applications/deployments/what-deployments-are.adoc +++ /dev/null @@ -1,56 +0,0 @@ -[id="what-deployments-are"] -= Understanding `Deployment` and `DeploymentConfig` objects -include::modules/common-attributes.adoc[] -:context: what-deployments-are - -toc::[] - -The `Deployment` and `DeploymentConfig` API objects in {product-title} provide two similar but different methods for fine-grained management over common user applications. They are composed of the following separate API objects: - -* A `DeploymentConfig` or `Deployment` object, either of which describes the desired state of a particular component of the application as a pod template. -* `DeploymentConfig` objects involve one or more _replication controllers_, which contain a point-in-time record of the state of a deployment as a pod template. Similarly, `Deployment` objects involve one or more _replica sets_, a successor of replication controllers. -* One or more pods, which represent an instance of a particular version of an application. - -//// -Update when converted: - -.Additional resources - -xref:../../applications/deployments/advanced_deployment_strategies.adoc#graceful-termination[graceful shutdown] -xref:../../applications/basic_deployment_operations.adoc#triggers[Triggers] -xref:../../applications/deployment_strategies.adoc#strategies[strategies] -xref:../../applications/deployment_strategies.adoc#lifecycle-hooks[hooks] -xref:../../applications/basic_deployment_operations.adoc#rolling-back-a-deployment[rollbacks] -xref:../../applications/basic_deployment_operations.adoc#scaling[scaling] -xref:../../dev_guide/pod_autoscaling.adoc#dev-guide-pod-autoscaling[autoscaling] -//// - -[id="what-deployments-are-build-blocks"] -== Building blocks of a deployment - -Deployments and deployment configs are enabled by the use of native Kubernetes API objects `ReplicaSet` and `ReplicationController`, respectively, as their building blocks. - -Users do not have to manipulate replication controllers, replica sets, or pods owned by `DeploymentConfig` objects or deployments. The deployment systems ensure changes are propagated appropriately. - -[TIP] -==== -If the existing deployment strategies are not suited for your use case and you must run manual steps during the lifecycle of your deployment, then you should consider creating a custom deployment strategy. -==== - -The following sections provide further details on these objects. - -include::modules/deployments-replicationcontrollers.adoc[leveloffset=+2] -include::modules/deployments-replicasets.adoc[leveloffset=+2] - -include::modules/deployments-deploymentconfigs.adoc[leveloffset=+1] -include::modules/deployments-kube-deployments.adoc[leveloffset=+1] -include::modules/deployments-comparing-deploymentconfigs.adoc[leveloffset=+1] -//// -Update when converted: - -.Additional resources - -- xref:../../dev_guide/managing_images.adoc#dev-guide-managing-images[Imagestreams] -- xref:../../dev_guide/deployments/deployment_strategies.adoc#lifecycle-hooks[Lifecycle hooks] -- xref:../../dev_guide/deployments/deployment_strategies.adoc#custom-strategy[Custom deployment strategies] -//// diff --git a/applications/idling-applications.adoc b/applications/idling-applications.adoc deleted file mode 100644 index 223a827f713e..000000000000 --- a/applications/idling-applications.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="idling-applications"] -= Idling applications -include::modules/common-attributes.adoc[] -:context: idling-applications - -toc::[] - -Cluster administrators can idle applications to reduce resource consumption. This is useful when the cluster is deployed on a public cloud where cost is related to resource consumption. - -If any scalable resources are not in use, {product-title} discovers and idles them by scaling their replicas to `0`. The next time network traffic is directed to the resources, the resources are unidled by scaling up the replicas, and normal operation continues. - -Applications are made of services, as well as other scalable resources, such as deployment configs. The action of idling an application involves idling all associated resources. - -include::modules/idle-idling-applications.adoc[leveloffset=+1] -include::modules/idle-unidling-applications.adoc[leveloffset=+1] diff --git a/applications/odc-monitoring-project-and-application-metrics-using-developer-perspective.adoc b/applications/odc-monitoring-project-and-application-metrics-using-developer-perspective.adoc deleted file mode 100644 index ab7150f76739..000000000000 --- a/applications/odc-monitoring-project-and-application-metrics-using-developer-perspective.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="odc-monitoring-project-and-application-metrics-using-developer-perspective"] -= Monitoring project and application metrics using the Developer perspective -include::modules/common-attributes.adoc[] -:context: monitoring-project-and-application-metrics-using-developer-perspective - -toc::[] - - -The *Monitoring* view in the *Developer* perspective provides options to monitor your project or application metrics, such as CPU, memory, and bandwidth usage, and network related information. - -== Prerequisites - -* You have xref:../web_console/web-console.adoc#web-console-overview[logged in to the web console] and have switched to the xref:../web_console/odc-about-developer-perspective.adoc#odc-about-developer-perspective[*Developer* perspective]. -* You have xref:../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[created and deployed applications on {product-title}]. - -include::modules/odc-monitoring-your-project-metrics.adoc[leveloffset=+1] - -include::modules/odc-monitoring-your-application-metrics.adoc[leveloffset=+1] - -== Additional Resources -* xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Understanding the monitoring stack] diff --git a/applications/projects/configuring-project-creation.adoc b/applications/projects/configuring-project-creation.adoc deleted file mode 100644 index 768bcfe7ce04..000000000000 --- a/applications/projects/configuring-project-creation.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="configuring-project-creation"] -= Configuring project creation -include::modules/common-attributes.adoc[] -:context: configuring-project-creation - -toc::[] - -In {product-title}, _projects_ are used to group and isolate related objects. -When a request is made to create a new project using the web console or `oc -new-project` command, an endpoint in {product-title} is used to provision the -project according to a template, which can be customized. - -As -a cluster administrator, you can allow and configure how developers and service -accounts can create, or _self-provision_, their own projects. - -//// -ifdef::openshift-dedicated[] -A dedicated administrator is by default an administrator for all projects on the -cluster that are not managed by Red Hat Operations. -endif::[] -//// - -include::modules/about-project-creation.adoc[leveloffset=+1] -include::modules/modifying-template-for-new-projects.adoc[leveloffset=+1] -include::modules/disabling-project-self-provisioning.adoc[leveloffset=+1] -include::modules/customizing-project-request-message.adoc[leveloffset=+1] diff --git a/applications/projects/creating-project-other-user.adoc b/applications/projects/creating-project-other-user.adoc deleted file mode 100644 index 182274cdf0c8..000000000000 --- a/applications/projects/creating-project-other-user.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="creating-project-other-user"] -= Creating a project as another user -include::modules/common-attributes.adoc[] -:context: creating-project-other-user - -toc::[] - -Impersonation allows you to create a project as a different user. - -include::modules/authentication-api-impersonation.adoc[leveloffset=+1] - -include::modules/impersonation-project-creation.adoc[leveloffset=+1] diff --git a/applications/projects/images b/applications/projects/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/applications/projects/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/applications/projects/working-with-projects.adoc b/applications/projects/working-with-projects.adoc deleted file mode 100644 index 3d1e89f544ab..000000000000 --- a/applications/projects/working-with-projects.adoc +++ /dev/null @@ -1,41 +0,0 @@ -[id="working-with-projects"] -= Working with projects -include::modules/common-attributes.adoc[] -:context: projects - -toc::[] - -A _project_ allows a community of users to organize and manage their content in -isolation from other communities. - -[NOTE] -==== -Projects starting with `openshift-` and `kube-` are xref:../../authentication/using-rbac.adoc#rbac-default-projects_using-rbac[default projects]. These projects host cluster components that run as pods and other infrastructure components. As such, {product-title} does not allow you to create projects starting with `openshift-` or `kube-` using the `oc new-project` command. Cluster administrators can create these projects using the `oc adm new-project` command. -==== - -[NOTE] -==== -You cannot assign an SCC to pods created in one of the default namespaces: `default`, `kube-system`, `kube-public`, `openshift-node`, `openshift-infra`, and `openshift`. You cannot use these namespaces for running pods or services. -==== - -include::modules/creating-a-project-using-the-web-console.adoc[leveloffset=+1] - -include::modules/odc-creating-projects-using-developer-perspective.adoc[leveloffset=+1] - -include::modules/creating-a-project-using-the-CLI.adoc[leveloffset=+1] - -include::modules/viewing-a-project-using-the-web-console.adoc[leveloffset=+1] - -include::modules/viewing-a-project-using-the-CLI.adoc[leveloffset=+1] - -include::modules/odc-providing-project-permissions-using-developer-perspective.adoc[leveloffset=+1] - -include::modules/adding-to-a-project.adoc[leveloffset=+1] - -include::modules/checking-project-status-using-the-web-console.adoc[leveloffset=+1] - -include::modules/checking-project-status-using-the-CLI.adoc[leveloffset=+1] - -include::modules/deleting-a-project-using-the-web-console.adoc[leveloffset=+1] - -include::modules/deleting-a-project-using-the-CLI.adoc[leveloffset=+1] diff --git a/applications/pruning-objects.adoc b/applications/pruning-objects.adoc deleted file mode 100644 index 9dcff7f00133..000000000000 --- a/applications/pruning-objects.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="pruning-objects"] -= Pruning objects to reclaim resources -include::modules/common-attributes.adoc[] -:context: pruning-objects - -toc::[] - -Over time, API objects created in {product-title} can accumulate in the -cluster's etcd data store through normal user operations, such as when building -and deploying applications. - -Cluster administrators can periodically prune older versions of objects from the -cluster that are no longer required. For example, by pruning images you can delete -older images and layers that are no longer in use, but are still taking up disk -space. - -include::modules/pruning-basic-operations.adoc[leveloffset=+1] -include::modules/pruning-groups.adoc[leveloffset=+1] -include::modules/pruning-deployments.adoc[leveloffset=+1] -include::modules/pruning-builds.adoc[leveloffset=+1] -.Additional resources -- xref:../cicd/builds/advanced-build-operations.adoc#builds-build-pruning-advanced-build-operations[Performing advanced builds -> Pruning builds] - -include::modules/pruning-images.adoc[leveloffset=+1] -include::modules/pruning-images-manual.adoc[leveloffset=+1] -.Additional resources -- xref:../registry/accessing-the-registry.adoc#accessing-the-registry[Accessing the registry] -- xref:../registry/securing-exposing-registry.adoc#securing-exposing-registry[Exposing the registry] -- See -xref:../registry/configuring-registry-operator.adoc#configuring-registry-operator[Image -Registry Operator in {product-title}] for information on how to create a -registry route. - -include::modules/pruning-hard-pruning-registry.adoc[leveloffset=+1] -include::modules/pruning-cronjobs.adoc[leveloffset=+1] -.Additional resources -- xref:../nodes/jobs/nodes-nodes-jobs.adoc#nodes-nodes-jobs_nodes-nodes-jobs[Running tasks in pods using jobs] -- xref:../applications/quotas/quotas-setting-across-multiple-projects.adoc#setting-quotas-across-multiple-projects[Resource quotas across multiple projects] -- xref:../authentication/using-rbac.adoc#using-rbac[Using RBAC to define and apply permissions] diff --git a/applications/quotas/images b/applications/quotas/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/applications/quotas/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/applications/quotas/modules b/applications/quotas/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/applications/quotas/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/applications/quotas/quotas-setting-across-multiple-projects.adoc b/applications/quotas/quotas-setting-across-multiple-projects.adoc deleted file mode 100644 index 216aee8c5747..000000000000 --- a/applications/quotas/quotas-setting-across-multiple-projects.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="setting-quotas-across-multiple-projects"] -= Resource quotas across multiple projects -include::modules/common-attributes.adoc[] -:context: setting-quotas-across-multiple-projects - -toc::[] - -A multi-project quota, defined by a `ClusterResourceQuota` object, allows quotas to be shared across multiple projects. Resources used in each selected project are aggregated and that aggregate is used to limit resources across all the selected projects. - -This guide describes how cluster administrators can set and manage resource quotas across multiple projects. - -include::modules/quotas-selecting-projects.adoc[leveloffset=+1] -include::modules/quotas-viewing-clusterresourcequotas.adoc[leveloffset=+1] -include::modules/quotas-selection-granularity.adoc[leveloffset=+1] diff --git a/applications/quotas/quotas-setting-per-project.adoc b/applications/quotas/quotas-setting-per-project.adoc deleted file mode 100644 index 12df415ac621..000000000000 --- a/applications/quotas/quotas-setting-per-project.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="quotas-setting-per-project"] -= Resource quotas per project -include::modules/common-attributes.adoc[] -:context: quotas-setting-per-project - -toc::[] - -A _resource quota_, defined by a `ResourceQuota` object, provides constraints that limit aggregate resource consumption per project. It can limit the quantity of objects that can be created in a project by type, as well as the total amount of compute resources and storage that might be consumed by resources in that project. - -This guide describes how resource quotas work, how cluster administrators can set and manage resource quotas on a per project basis, and how developers and cluster administrators can view them. - -include::modules/quotas-resources-managed.adoc[leveloffset=+1] -include::modules/quotas-scopes.adoc[leveloffset=+1] -include::modules/quotas-enforcement.adoc[leveloffset=+1] -include::modules/quotas-requests-vs-limits.adoc[leveloffset=+1] -include::modules/quotas-sample-resource-quotas-def.adoc[leveloffset=+1] -include::modules/quotas-creating-a-quota.adoc[leveloffset=+1] -include::modules/quotas-creating-object-count-quotas.adoc[leveloffset=+2] -include::modules/setting-resource-quota-for-extended-resources.adoc[leveloffset=+2] -include::modules/quotas-viewing-quotas.adoc[leveloffset=+1] -include::modules/quotas-requiring-explicit-quota.adoc[leveloffset=+1] diff --git a/applications/red-hat-marketplace.adoc b/applications/red-hat-marketplace.adoc deleted file mode 100644 index 4f03f96f49e1..000000000000 --- a/applications/red-hat-marketplace.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="red-hat-marketplace"] -= Using the Red Hat Marketplace -include::modules/common-attributes.adoc[] -:context: red-hat-marketplace - -toc::[] - -The link:https://marketplace.redhat.com[Red Hat Marketplace] is an open cloud marketplace that makes it easy to discover and access certified software for container-based environments that run on public clouds and on-premises. - -include::modules/red-hat-marketplace-features.adoc[leveloffset=+1] diff --git a/applications/working-with-quotas.adoc b/applications/working-with-quotas.adoc deleted file mode 100644 index 7386b255f3fb..000000000000 --- a/applications/working-with-quotas.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="working-with-quotas"] -= Working with quotas -include::modules/common-attributes.adoc[] -:context: working-with-quotas - -toc::[] - -A _resource quota_, defined by a ResourceQuota object, provides constraints that -limit aggregate resource consumption per project. It can limit the quantity of -objects that can be created in a project by type, as well as the total amount of -compute resources and storage that may be consumed by resources in that project. - -An _object quota count_ places a defined quota on all standard namespaced resource -types. When using a resource quota, an object is charged against the quota if it -exists in server storage. These types of quotas are useful to protect against -exhaustion of storage resources. - -This guide describes how resource quotas work and how developers can work with -and view them. - -include::modules/quotas-viewing-quotas.adoc[leveloffset=+1] -include::modules/quotas-resources-managed.adoc[leveloffset=+1] -include::modules/quotas-scopes.adoc[leveloffset=+1] -include::modules/quotas-enforcement.adoc[leveloffset=+1] -include::modules/quotas-requests-vs-limits.adoc[leveloffset=+1] diff --git a/applications_and_projects/working-with-projects.adoc b/applications_and_projects/working-with-projects.adoc deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/architecture.png b/architecture.png new file mode 100644 index 000000000000..bb9b9a0d9fe7 Binary files /dev/null and b/architecture.png differ diff --git a/architecture/acs-architecture.adoc b/architecture/acs-architecture.adoc new file mode 100644 index 000000000000..eb0be33c3a2e --- /dev/null +++ b/architecture/acs-architecture.adoc @@ -0,0 +1,32 @@ +[id="acs-architecture"] += Red Hat Advanced Cluster Security for Kubernetes architecture +include::modules/common-attributes.adoc[] +:context: acs-architecture + +toc::[] + +Discover {product-title} architecture and concepts. + +include::modules/acs-architecture-overview.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../architecture/acs-architecture.adoc#external-components_acs-architecture[External components] +* xref:../operating/examine-images-for-vulnerabilities.adoc#enabling_scanner_v4_examine-images-for-vulnerabilities[Enabling Scanner V4] + +include::modules/acs-central-services-overview.adoc[leveloffset=+1] + +include::modules/con-vuln-sources.adoc[leveloffset=+2] + +include::modules/acs-secured-cluster-services-overview.adoc[leveloffset=+1] + +include::modules/acs-architecture-external-components.adoc[leveloffset=+1] + +include::modules/acs-architecture-interaction-between-services.adoc[leveloffset=+1] + +include::modules/acs-architecture-connections.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../installing/installing_ocp/install-central-ocp.html#install-central-operator-external-db_install-central-ocp[Installing Central with an external database using the Operator method] +* xref:../cli/command-reference/roxctl.adoc#roxctl-command-options_roxctl[roxctl command options] diff --git a/architecture/admission-plug-ins.adoc b/architecture/admission-plug-ins.adoc deleted file mode 100644 index 67bf668d81b9..000000000000 --- a/architecture/admission-plug-ins.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="admission-plug-ins"] -= Admission plug-ins -include::modules/common-attributes.adoc[] -:context: admission-plug-ins - -toc::[] - -// Concept modules -include::modules/admission-plug-ins-about.adoc[leveloffset=+1] - -include::modules/admission-plug-ins-default.adoc[leveloffset=+1] - -include::modules/admission-webhooks-about.adoc[leveloffset=+1] - -include::modules/admission-webhook-types.adoc[leveloffset=+1] - -// Procedure module -include::modules/configuring-dynamic-admission.adoc[leveloffset=+1] - -[id="admission-plug-ins-additional-resources"] -== Additional resources - -ifdef::openshift-enterprise,openshift-webscale[] -* xref:../networking/hardware_networks/configuring-sriov-operator.adoc#configuring-sriov-operator[Limiting custom network resources managed by the SR-IOV network device plug-in] -endif::[] - -* xref:../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations_dedicating_nodes-scheduler-taints-tolerations[Defining tolerations that enable taints to qualify which pods should be scheduled on a node] - -* xref:../nodes/pods/nodes-pods-priority.adoc#admin-guide-priority-preemption-names_nodes-pods-priority[Pod priority class validation] diff --git a/architecture/architecture-installation.adoc b/architecture/architecture-installation.adoc deleted file mode 100644 index 601f81e3d22c..000000000000 --- a/architecture/architecture-installation.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="architecture-installation"] -= Installation and update -include::modules/common-attributes.adoc[] -:context: architecture-installation - -toc::[] - -include::modules/installation-overview.adoc[leveloffset=+1] - -include::modules/supported-platforms-for-openshift-clusters.adoc[leveloffset=+2] - -include::modules/installation-process.adoc[leveloffset=+2] - -[discrete] -=== Installation scope - -The scope of the {product-title} installation program is intentionally narrow. It is designed for simplicity and ensured success. You can complete many more configuration tasks after installation completes. - -.Additional resources - -* See xref:../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Available cluster customizations] for details about {product-title} configuration resources. - -include::modules/update-service-overview.adoc[leveloffset=+1] - -include::modules/unmanaged-operators.adoc[leveloffset=+1] - -[id="architecture-installation-next-steps"] -== Next steps - -* xref:../installing/installing-preparing.adoc#installing-preparing[Selecting a cluster installation method and preparing it for users] diff --git a/architecture/architecture-rhcos.adoc b/architecture/architecture-rhcos.adoc deleted file mode 100644 index 90c77e103f65..000000000000 --- a/architecture/architecture-rhcos.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="architecture-rhcos"] -= {op-system-first} -include::modules/common-attributes.adoc[] -:context: architecture-rhcos - -toc::[] - -include::modules/rhcos-about.adoc[leveloffset=+1] -include::modules/ignition-config-viewing.adoc[leveloffset=+1] -include::modules/digging-into-machine-config.adoc[leveloffset=+1] diff --git a/architecture/architecture.adoc b/architecture/architecture.adoc deleted file mode 100644 index b30ae9e62130..000000000000 --- a/architecture/architecture.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="architecture"] -= {product-title} architecture -include::modules/common-attributes.adoc[] -:context: architecture - -toc::[] - -include::modules/architecture-platform-introduction.adoc[leveloffset=+1] - -include::modules/architecture-kubernetes-introduction.adoc[leveloffset=+2] - -include::modules/architecture-container-application-benefits.adoc[leveloffset=+2] - -include::modules/architecture-platform-benefits.adoc[leveloffset=+2] -//// -== User facing components -* Workloads (Deployments, Jobs, ReplicaSets, etc) -* Operator Lifecycle Manager -* xref:../cicd/builds/understanding-image-builds.adoc[Builds] - The build component -provides an API and infrastructure for producing new container images using a -variety of techniques including industry standard Dockerfiles and publishing -them to either the cluster image registry, or an external registry. It also -provides integration with Jenkins based pipeline continuous integration -workflows. -* xref:../registry/architecture-component-imageregistry.adoc[Image Registry] - -The image registry provides a scalable repository for storing and retrieving -container images that are produced by and run on the cluster. Image access is -integrated with the cluster’s role-based access controls and user authentication -system. -* xref:../openshift_images/images-understand.adoc[Image -streams] - The imagestream API provides an abstraction over container images -that exist in registries. It allows workloads to reference an image indirectly, -retains a history of the images that have been referenced, and allows -notification when an image is updated with a new version. -//// - -include::modules/cluster-entitlements.adoc[leveloffset=+2] diff --git a/architecture/argocd.adoc b/architecture/argocd.adoc deleted file mode 100644 index 8d45b22ec45e..000000000000 --- a/architecture/argocd.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="argocd"] -= Using ArgoCD with {product-title} -include::modules/common-attributes.adoc[] - -:context: argocd - -toc::[] - -[id="argocd-what"] -== What does ArgoCD do? - -ArgoCD is a declarative continuous delivery tool that leverages GitOps to maintain cluster resources. ArgoCD is implemented as a controller that continuously monitors application definitions and configurations defined in a Git repository and compares the specified state of those configurations with their live state on the cluster. Configurations that deviate from their specified state in the Git repository are classified as OutOfSync. ArgoCD reports these differences and allows administrators to automatically or manually resync configurations to the defined state. - -ArgoCD enables you to deliver global custom resources, like the resources that are used to configure {product-title} clusters. - -[id="argocd-support"] -== Statement of support - -Red Hat does not provide support for this tool. To obtain support for ArgoCD, see link:https://argoproj.github.io/argo-cd/SUPPORT/[Support] in the ArgoCD documentation. - -[id="argocd-documentation"] -== ArgoCD documentation - -For more information about using ArgoCD, see the link:https://argoproj.github.io/argo-cd/[ArgoCD documentation]. diff --git a/architecture/cicd_gitops.adoc b/architecture/cicd_gitops.adoc deleted file mode 100644 index 8ddca5d5678b..000000000000 --- a/architecture/cicd_gitops.adoc +++ /dev/null @@ -1,59 +0,0 @@ -[id="cicd_gitops"] -= The CI/CD methodology and practice -include::modules/common-attributes.adoc[] -:context: cicd_gitops - -toc::[] - -Using a _continuous integration/continuous delivery_ (CI/CD) methodology enables you to regularly deliver applications to customers by introducing automation into the stages of application development, from integration and testing phases to delivery and deployment. The CI/CD process is often referred to as a "CI/CD pipeline." The main concepts attributed to CI/CD are continuous integration, continuous delivery, and continuous deployment. - -[id="cicd_admin"] -== CI/CD for cluster administration and application configuration management - -_Continuous integration_ is an automation process for developers. Code changes to an application are regularly built, tested, and merged to a shared repository. - -_Continuous delivery_ and _continuous deployment_ are closely related concepts that are sometimes used interchangeably and refer to automation of the pipeline. -Continuous delivery uses automation to ensure that a developer’s changes to an application are tested and sent to a repository, where an operations team can deploy them to a production environment. Continuous deployment enables the release of changes, starting from the repository and ending in production. Continuous deployment speeds up application delivery and prevents the operations team from getting overloaded. - -[id="cicd_gitops_methodology"] -== The GitOps methodology and practice - -_GitOps_ is a set of practices that use Git pull requests to manage infrastructure and application configurations. The Git repository in GitOps is the only source of truth for system and application configuration. The repository contains the entire state of the system so that the trail of changes to the system state are visible and auditable. GitOps enables you to implement a DevOps methodology. - -You can use GitOps tooling to create repeatable and predictable processes for managing and recreating {product-title} clusters and applications. By using GitOps, you can address the issues of infrastructure and application configuration sprawl. It simplifies the propagation of infrastructure and application configuration changes across multiple clusters by defining your infrastructure and applications definitions as “code.” Implementing GitOps for your cluster configuration files can make automated installation easier and allow you to configure automated cluster customizations. You can apply the core principles of developing and maintaining software in a Git repository to the creation and management of your cluster and application configuration files. - -By using {product-title} to automate both your cluster configuration and container development process, you can pick and choose where and when to adopt GitOps practices. Using a CI pipeline that pairs with your GitOps strategy and execution plan is ideal. {product-title} provides the flexibility to choose when and how you integrate this methodology into your business practices and pipelines. - -With GitOps integration, you can declaratively configure and store your {product-title} cluster configuration - -GitOps works well with {product-title} because you can both declaratively configure clusters and store the state of the cluster configuration in Git. For more information, see xref:../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Available cluster customizations]. - -[id="cicd_gitops_cluster_administration"] -=== GitOps for single-cluster and multi-cluster administration - -Whether you need one or more independent or cooperative {product-title} clusters, you can use a GitOps strategy to manage the following tasks: - -* Ensure that the clusters have similar states for configuration, monitoring, or storage. -* Recover or recreate clusters from a known state. -* Create clusters with a known state. -* Apply or revert configuration changes to multiple {product-title} clusters. -* Associate templated configuration with different environments. - -[id="cicd_gitops_application_configuration"] -=== GitOps for application configuration management - -You can also use GitOps practices to manage application configuration. This practice ensures consistency in applications when you deploy them to different clusters in different environments, like development, stage, and production. Managing application configuration with GitOps is also beneficial when you must deploy applications across multiple clusters, whether on-cloud or on-premise, for availability and scalability purposes. - -You can use a GitOps strategy to: - -* Promote applications across clusters, from stage to production. -* Apply or revert application changes to multiple {product-title} clusters. - -[id="cicd_gitops_integrators"] -=== GitOps technology providers and integrators - -There are several community offerings and third-party vendors that provide a high level of integration with {product-title}. - -You can integrate GitOps into {product-title} with the following community partners and third-party integrators: - -* xref:../architecture/argocd.adoc#argocd[ArgoCD] diff --git a/architecture/control-plane.adoc b/architecture/control-plane.adoc deleted file mode 100644 index bad36c4db94a..000000000000 --- a/architecture/control-plane.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="control-plane"] -= The {product-title} control plane -include::modules/common-attributes.adoc[] -:context: control-plane - -toc::[] - -include::modules/understanding-control-plane.adoc[leveloffset=+1] - -include::modules/architecture-machine-roles.adoc[leveloffset=+2] - -include::modules/operators-overview.adoc[leveloffset=+2] - -include::modules/update-service-overview.adoc[leveloffset=+3] - -include::modules/understanding-machine-config-operator.adoc[leveloffset=+3] - -.Additional information - -For information on preventing the control plane machines from rebooting after the Machine Config Operator makes changes to the machine config, see xref:../support/troubleshooting/troubleshooting-operator-issues.adoc#troubleshooting-disabling-autoreboot-mco_troubleshooting-operator-issues[Disabling Machine Config Operator from automatically rebooting]. diff --git a/architecture/images b/architecture/images index 5e67573196d8..e4c5bd02a10a 120000 --- a/architecture/images +++ b/architecture/images @@ -1 +1 @@ -../images \ No newline at end of file +../images/ \ No newline at end of file diff --git a/architecture/modules b/architecture/modules index 464b823aca16..43aab75b53c9 120000 --- a/architecture/modules +++ b/architecture/modules @@ -1 +1 @@ -../modules \ No newline at end of file +../modules/ \ No newline at end of file diff --git a/architecture/snippets b/architecture/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/architecture/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/architecture/understanding-development.adoc b/architecture/understanding-development.adoc deleted file mode 100644 index 65e53bbfa669..000000000000 --- a/architecture/understanding-development.adoc +++ /dev/null @@ -1,386 +0,0 @@ -[id="understanding-development"] -= Understanding {product-title} development -include::modules/common-attributes.adoc[] -:context: understanding-development - -toc::[] - -To fully leverage the capability of containers when developing and running -enterprise-quality applications, ensure your environment is supported by tools -that allow containers to be: - -* Created as discrete microservices that can be connected to other -containerized, and non-containerized, services. For example, you might want to -join your application with a database or attach a monitoring application to it. - -* Resilient, so if a server crashes or needs to go down for maintenance or to be -decommissioned, containers can start on another machine. - -* Automated to pick up code changes automatically and then start and deploy new -versions of themselves. - -* Scaled up, or replicated, to have more instances serving clients as demand -increases and then spun down to fewer instances as demand declines. - -* Run in different ways, depending on the type of application. For example, one -application might run once a month to produce a report and then exit. Another -application might need to run constantly and be highly available to clients. - -* Managed so you can watch the state of your application and react when -something goes wrong. - -Containers’ widespread acceptance, and the resulting requirements for tools and -methods to make them enterprise-ready, resulted in many options for them. - -The rest of this section explains options for -assets you can create when you build and deploy containerized Kubernetes -applications in {product-title}. It also describes which approaches you might -use for different kinds of applications and development requirements. - -[id="developing-containerized-applications"] -== About developing containerized applications - -You can approach application development with containers in many ways, and -different approaches might be more appropriate for different situations. To -illustrate some of this variety, the series of approaches that is presented -starts with developing a single container and ultimately deploys that container -as a mission-critical application for a large enterprise. These approaches -show different tools, formats, and methods that you can employ with containerized -application development. This topic describes: - -* Building a simple container and storing it in a registry -* Creating a Kubernetes manifest and saving it to a Git repository -* Making an Operator to share your application with others - -[id="building-simple-container"] -== Building a simple container - -You have an idea for an application and you want to containerize it. - -First you require a tool for building a container, like buildah or docker, -and a file that describes what goes in your container, which is typically a -link:https://docs.docker.com/engine/reference/builder/[Dockerfile]. - -Next, you require a location to push the resulting container image so you can -pull it to run anywhere you want it to run. This location is a container -registry. - -Some examples of each of these components are installed by default on most -Linux operating systems, except for the Dockerfile, which you provide yourself. - -The following diagram displays the process of building and pushing an image: - -.Create a simple containerized application and push it to a registry -image::create-push-app.png[Creating and pushing a containerized application] - -If you use a computer that runs {op-system-base-full} as the operating -system, the process of creating a containerized application requires the -following steps: - -. Install container build tools: {op-system-base} contains a set of tools that includes -podman, buildah, and skopeo that you use to build and manage containers. -. Create a Dockerfile to combine base image and software: Information about -building your container goes into a file that is named `Dockerfile`. In that -file, you identify the base image you build from, the software packages you -install, and the software you copy into the container. You also identify -parameter values like network ports that you expose outside the container and -volumes that you mount inside the container. Put your Dockerfile and the -software you want to containerize in a directory on your {op-system-base} system. -. Run buildah or docker build: Run the `buildah build-using-dockerfile` or -the `docker build` command to pull your chosen base image to the local system and -create a container image that is stored locally. You can also build container images -without a Dockerfile by using buildah. -. Tag and push to a registry: Add a tag to your new container image that -identifies the location of the registry in which you want to store and share -your container. Then push that image to the registry by running the -`podman push` or `docker push` command. -. Pull and run the image: From any system that has a container client tool, -such as podman or docker, run a command that identifies your new image. -For example, run the `podman run ` or `docker run ` -command. Here `` is the name of your new container image, which -resembles `quay.io/myrepo/myapp:latest`. The registry might require credentials -to push and pull images. - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -For more details on the process of building container images, pushing them to -registries, and running them, see -xref:../cicd/builds/custom-builds-buildah.adoc#custom-builds-buildah[Custom image builds with Buildah]. -endif::openshift-origin,openshift-enterprise,openshift-webscale[] - -[id="container-build-tool-options"] -=== Container build tool options - -While the Docker Container Engine and `docker` command are popular tools -to work with containers, with {op-system-base} and many other Linux systems, you can -instead choose a different set of container tools that includes podman, skopeo, -and buildah. You can still use Docker Container Engine tools to create -containers that will run in {product-title} and any other container platform. - -Building and managing containers with buildah, podman, and skopeo results in -industry standard container images that include features tuned specifically -for ultimately deploying those containers in {product-title} or other Kubernetes -environments. These tools are daemonless and can be run without root privileges, -so there is less overhead in running them. - -When you ultimately run your containers in {product-title}, you use the -link:https://cri-o.io/[CRI-O] container engine. CRI-O runs on every worker and -master machine in an {product-title} cluster, but CRI-O is not yet supported as -a standalone runtime outside of {product-title}. - -[id="base-image-options"] -=== Base image options - -The base image you choose to build your application on contains a set of -software that resembles a Linux system to your application. When you build your -own image, your software is placed into that file system and sees that file -system as though it were looking at its operating system. Choosing this base -image has major impact on how secure, efficient and upgradeable your container -is in the future. - -Red Hat provides a new set of base images referred to as -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/getting_started_with_containers/index#using_red_hat_base_container_images_standard_and_minimal[Red Hat Universal Base Images] (UBI). -These images are based on Red Hat Enterprise Linux and are similar to base -images that Red Hat has offered in the past, with one major difference: they -are freely redistributable without a Red Hat subscription. As a result, you can -build your application on UBI images without having to worry about how they -are shared or the need to create different images for different environments. - -These UBI images have standard, init, and minimal versions. You can also use the -link:https://access.redhat.com/documentation/en-us/red_hat_software_collections/3/html-single/using_red_hat_software_collections_container_images/index[Red Hat Software Collections] -images as a foundation for applications that rely on specific runtime -environments such as Node.js, Perl, or Python. Special versions of some of -these runtime base images are referred to as Source-to-Image (S2I) images. With -S2I images, you can insert your code into a base image environment that is ready -to run that code. - -S2I images are available for you to use directly from the {product-title} web UI -by selecting *Catalog* -> *Developer Catalog*, as shown in the following figure: - -.Choose S2I base images for apps that need specific runtimes -image::developer-catalog.png[{product-title} Developer Catalog] - -[id="understanding-development-registry-options"] -=== Registry options - -Container registries are where you store container images so you can share them -with others and make them available to the platform where they ultimately run. -You can select large, public container registries that offer free accounts or a -premium version that offer more storage and special features. You can also -install your own registry that can be exclusive to your organization or -selectively shared with others. - -To get Red Hat images and certified partner images, you can draw from the -Red Hat Registry. The Red Hat Registry is represented by two locations: -`registry.access.redhat.com`, which is unauthenticated and deprecated, and -`registry.redhat.io`, which requires authentication. You can learn about the Red -Hat and partner images in the Red Hat Registry from the -link:https://catalog.redhat.com/software/containers/explore[Container images section of the Red Hat Ecosystem Catalog]. -Besides listing Red Hat container images, it also shows extensive information -about the contents and quality of those images, including health scores that are -based on applied security updates. - -Large, public registries include link:https://hub.docker.com/[Docker Hub] and -link:https://quay.io/[Quay.io]. The Quay.io registry is owned and managed by Red -Hat. Many of the components used in {product-title} are stored in Quay.io, -including container images and the Operators that are used to deploy -{product-title} itself. Quay.io also offers the means of storing other types of -content, including Helm charts. - -If you want your own, private container registry, {product-title} itself -includes a private container registry that is installed with {product-title} -and runs on its cluster. Red Hat also offers a private version of the Quay.io -registry called link:https://access.redhat.com/products/red-hat-quay[Red Hat Quay]. -Red Hat Quay includes geo replication, Git build triggers, Clair image scanning, -and many other features. - -All of the registries mentioned here can require credentials to download images -from those registries. Some of those credentials are presented on a cluster-wide -basis from {product-title}, while other credentials can be assigned to individuals. - -[id="creating-kubernetes-manifest-openshift"] -== Creating a Kubernetes manifest for {product-title} - -While the container image is the basic building block for a containerized -application, more information is required to manage and deploy that application -in a Kubernetes environment such as {product-title}. The typical next steps after -you create an image are to: - -* Understand the different resources you work with in Kubernetes manifests -* Make some decisions about what kind of an application you are running -* Gather supporting components -* Create a manifest and store that manifest in a Git repository so you can store -it in a source versioning system, audit it, track it, promote and deploy it -to the next environment, roll it back to earlier versions, if necessary, and -share it with others - -[id="understanding-kubernetes-pods"] -=== About Kubernetes pods and services - -While the container image is the basic unit with docker, the basic units that -Kubernetes works with are called -link:https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/[pods]. -Pods represent the next step in building out an application. A pod can contain -one or more than one container. The key is that the pod is the single unit -that you deploy, scale, and manage. - -Scalability and namespaces are probably the main items to consider when determining -what goes in a pod. For ease of deployment, you might want to deploy a container -in a pod and include its own logging and monitoring container in the pod. Later, -when you run the pod and need to scale up an additional instance, those other -containers are scaled up with it. For namespaces, containers in a pod share the -same network interfaces, shared storage volumes, and resource limitations, -such as memory and CPU, which makes it easier to manage the contents of the pod -as a single unit. Containers in a pod can also communicate with each other by -using standard inter-process communications, such as System V semaphores or -POSIX shared memory. - -While individual pods represent a scalable unit in Kubernetes, a -link:https://kubernetes.io/docs/concepts/services-networking/service/[service] -provides a means of grouping together a set of pods to create a complete, stable -application that can complete tasks such as load balancing. A service is also -more permanent than a pod because the service remains available from the same -IP address until you delete it. When the service is in use, it is requested by -name and the {product-title} cluster resolves that name into the IP addresses -and ports where you can reach the pods that compose the service. - -By their nature, containerized applications are separated from the operating -systems where they run and, by extension, their users. Part of your Kubernetes -manifest describes how to expose the application to internal and external -networks by defining -link:https://kubernetes.io/docs/concepts/services-networking/network-policies/[network policies] -that allow fine-grained control over communication with your containerized -applications. To connect incoming requests for HTTP, HTTPS, and other services -from outside your cluster to services inside your cluster, you can use an -link:https://kubernetes.io/docs/concepts/services-networking/ingress/[`Ingress`] -resource. - -If your container requires on-disk storage instead of database storage, which -might be provided through a service, you can add -link:https://kubernetes.io/docs/concepts/storage/volumes/[volumes] -to your manifests to make that storage available to your pods. You can configure -the manifests to create persistent volumes (PVs) or dynamically create volumes that -are added to your `Pod` definitions. - -After you define a group of pods that compose your application, you can define -those pods in -link:https://kubernetes.io/docs/concepts/workloads/controllers/deployment/[`Deployment`] -and xref:../applications/deployments/what-deployments-are.adoc#what-deployments-are[`DeploymentConfig`] objects. - -[id="application-types"] -=== Application types - -Next, consider how your application type influences how to run it. - -Kubernetes defines different types of workloads that are appropriate for -different kinds of applications. To determine the appropriate workload for your -application, consider if the application is: - -* Meant to run to completion and be done. An example is an application that -starts up to produce a report and exits when the report is complete. The -application might not run again then for a month. Suitable {product-title} -objects for these types of applications include -link:https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/[`Job`] -and https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/[`CronJob`] objects. -* Expected to run continuously. For long-running applications, you can write a -xref:../applications/deployments/what-deployments-are.adoc#deployments-kube-deployments[deployment]. -* Required to be highly available. If your application requires high -availability, then you want to size your deployment to have more than one -instance. A `Deployment` or `DeploymentConfig` object can incorporate a -link:https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/[replica set] -for that type of application. With replica sets, pods run across multiple nodes -to make sure the application is always available, even if a worker goes down. -* Need to run on every node. Some types of Kubernetes applications are intended -to run in the cluster itself on every master or worker node. DNS and monitoring -applications are examples of applications that need to run continuously on every -node. You can run this type of application as a -link:https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/[daemon set]. -You can also run a daemon set on a subset of nodes, based on node labels. -* Require life-cycle management. When you want to hand off your application so -that others can use it, consider creating an -link:https://coreos.com/operators/[Operator]. Operators let you build in -intelligence, so it can handle things like backups and upgrades automatically. -Coupled with the Operator Lifecycle Manager (OLM), cluster managers can expose -Operators to selected namespaces so that users in the cluster can run them. -* Have identity or numbering requirements. An application might have identity -requirements or numbering requirements. For example, you might be -required to run exactly three instances of the application and to name the -instances `0`, `1`, and `2`. A -https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/[stateful set] -is suitable for this application. Stateful sets are most useful for applications -that require independent storage, such as databases and zookeeper clusters. - -[id="supporting-components"] -=== Available supporting components - -The application you write might need supporting components, like a database or -a logging component. To fulfill that need, you might be able to obtain the -required component from the following Catalogs that are available in the -{product-title} web console: - -* OperatorHub, which is available in each {product-title} {product-version} -cluster. The OperatorHub makes Operators available from Red Hat, -certified Red Hat partners, and community members to the cluster operator. The -cluster operator can make those Operators available in all or selected -namespaces in the cluster, so developers can launch them and configure them -with their applications. -* Templates, which are useful for a one-off type of application, where the -lifecycle of a component is not important after it is installed. A template provides an easy -way to get started developing a Kubernetes application with minimal overhead. -A template can be a list of resource definitions, which could be `Deployment`, -`Service`, `Route`, or other objects. If you want to change names or resources, -you can set these values as parameters in the template. - -You can configure the supporting Operators and -templates to the specific needs of your development team and then make them -available in the namespaces in which your developers work. Many people add -shared templates to the `openshift` namespace because it is accessible from all -other namespaces. - -[id="applying-manifest"] -=== Applying the manifest - -Kubernetes manifests let you create a more complete picture of the components -that make up your Kubernetes applications. You write these manifests as YAML -files and deploy them by applying them to the cluster, for example, by running -the `oc apply` command. - -[id="manifest-next-steps"] -=== Next steps - -At this point, consider ways to automate your container development process. -Ideally, you have some sort of CI pipeline that builds the images and pushes -them to a registry. In particular, a GitOps pipeline integrates your container -development with the Git repositories that you use to store the software that -is required to build your applications. - -The workflow to this point might look like: - -* Day 1: You write some YAML. You then run the `oc apply` command to apply that -YAML to the cluster and test that it works. -* Day 2: You put your YAML container configuration file into your own Git -repository. From there, people who want to install that app, or help you improve -it, can pull down the YAML and apply it to their cluster to run the app. -* Day 3: Consider writing an Operator for your application. - -[id="develop-for-operators"] -== Develop for Operators - -Packaging and deploying your application as an Operator might be preferred -if you make your application available for others to run. As noted earlier, -Operators add a lifecycle component to your application that acknowledges that -the job of running an application is not complete as soon as it is installed. - -When you create an application as an Operator, you can build in your own -knowledge of how to run and maintain the application. You can build in features -for upgrading the application, backing it up, scaling it, or keeping track of -its state. If you configure the application correctly, maintenance tasks, -like updating the Operator, can happen automatically and invisibly to the -Operator's users. - -An example of a useful Operator is one that is set up to automatically back up -data at particular times. Having an Operator manage an application’s backup at -set times can save a system administrator from remembering to do it. - -Any application maintenance that has traditionally been completed manually, -like backing up data or rotating certificates, can be completed automatically -with an Operator. diff --git a/authentication/bound-service-account-tokens.adoc b/authentication/bound-service-account-tokens.adoc deleted file mode 100644 index 9efe9ee83c4b..000000000000 --- a/authentication/bound-service-account-tokens.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="bound-service-account-tokens"] -= Using bound service account tokens -include::modules/common-attributes.adoc[] -:context: bound-service-account-tokens - -toc::[] - -You can use bound service account tokens, which improves the ability to integrate with cloud provider identity access management (IAM) services, such as AWS IAM. - -// About bound service account tokens -include::modules/bound-sa-tokens-about.adoc[leveloffset=+1] - -// Configuring bound service account tokens using volume projection -include::modules/bound-sa-tokens-configuring.adoc[leveloffset=+1] - -// TODO: Verify distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated diff --git a/authentication/configmaps.adoc b/authentication/configmaps.adoc deleted file mode 100644 index 606d6ecfa0dd..000000000000 --- a/authentication/configmaps.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="configmaps"] -= Creating and using config maps -include::modules/common-attributes.adoc[] -:context: configmaps - -toc::[] - -The following sections define config maps and how to create and use them. - -include::modules/authentication-configmap-overview.adoc[leveloffset=+1] - -include::modules/authentication-configmap-create-from-console.adoc[leveloffset=+1] - -include::modules/authentication-configmap-create.adoc[leveloffset=+1] - -include::modules/authentication-configmap-creating-from-directories.adoc[leveloffset=+2] - -include::modules/authentication-configmap-creating-from-files.adoc[leveloffset=+2] - -include::modules/authentication-configmap-creating-from-literal-values.adoc[leveloffset=+2] - -[id="authentication-configmaps-consuming-configmap-in-pods"] -== Use Cases: Consuming ConfigMaps in pods - -The following sections describe some uses cases when consuming `ConfigMap` -objects in pods. - -include::modules/authentication-configmaps-use-case-consuming-in-env-vars.adoc[leveloffset=+2] - -include::modules/authentication-configmaps-use-case-setting-command-line-arguments.adoc[leveloffset=+2] - -include::modules/authentication-configmaps-use-case-consuming-in-volumes.adoc[leveloffset=+2] diff --git a/authentication/configuring-internal-oauth.adoc b/authentication/configuring-internal-oauth.adoc deleted file mode 100644 index 20aeaf32d9af..000000000000 --- a/authentication/configuring-internal-oauth.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="configuring-internal-oauth"] -= Configuring the internal OAuth server -include::modules/common-attributes.adoc[] -:context: configuring-internal-oauth - -toc::[] - -include::modules/oauth-server-overview.adoc[leveloffset=+1] - -include::modules/oauth-internal-tokens.adoc[leveloffset=+1] - -include::modules/oauth-internal-options.adoc[leveloffset=+1] - -include::modules/oauth-configuring-internal-oauth.adoc[leveloffset=+1] - -include::modules/oauth-configuring-token-inactivity-timeout.adoc[leveloffset=+1] - -include::modules/oauth-server-metadata.adoc[leveloffset=+1] - -include::modules/oauth-troubleshooting-api-events.adoc[leveloffset=+1] diff --git a/authentication/configuring-ldap-failover.adoc b/authentication/configuring-ldap-failover.adoc deleted file mode 100644 index f21c87f1f1bb..000000000000 --- a/authentication/configuring-ldap-failover.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="configuring-ldap-failover"] -= Configuring LDAP failover -include::modules/common-attributes.adoc[] -:context: sssd-ldap-failover - -toc::[] - -include::modules/ldap-failover-overview.adoc[] - -include::modules/ldap-failover-prereqs.adoc[leveloffset=+1] - -include::modules/ldap-failover-generate-certs.adoc[leveloffset=+1] - -include::modules/ldap-failover-configure-sssd.adoc[leveloffset=+1] - -include::modules/ldap-failover-configure-apache.adoc[leveloffset=+1] - -include::modules/ldap-failover-configure-openshift.adoc[leveloffset=+1] diff --git a/authentication/configuring-oauth-clients.adoc b/authentication/configuring-oauth-clients.adoc deleted file mode 100644 index 5138dc56a1ec..000000000000 --- a/authentication/configuring-oauth-clients.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="configuring-oauth-clients"] -= Configuring OAuth clients -include::modules/common-attributes.adoc[] -:context: configuring-oauth-clients - -toc::[] - -Several OAuth clients are created by default in {product-title}. You can also register and configure additional OAuth clients. - -// Default OAuth clients -include::modules/oauth-default-clients.adoc[leveloffset=+1] - -// Register an additional OAuth client -include::modules/oauth-register-additional-client.adoc[leveloffset=+1] - -// Configuring token inactivity timeout for OAuth clients -include::modules/oauth-configuring-token-inactivity-timeout-clients.adoc[leveloffset=+1] - -== Additional resources - -* xref:../rest_api/oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[OAuthClient [oauth.openshift.io/v1]] diff --git a/authentication/dedicated-understanding-authentication.adoc b/authentication/dedicated-understanding-authentication.adoc deleted file mode 100644 index 22e45b488120..000000000000 --- a/authentication/dedicated-understanding-authentication.adoc +++ /dev/null @@ -1,38 +0,0 @@ -[id="understanding-identity-provider"] -= Understanding identity provider configuration -include::modules/common-attributes.adoc[] -:context: understanding-identity-provider - -toc::[] - -include::modules/identity-provider-parameters.adoc[leveloffset=+1] - -[id="supported-identity-providers"] -== Supported identity providers - -You can configure the following types of identity providers: - -[cols="2a,8a",options="header"] -|=== - -|Identity provider -|Description - -|xref:../authentication/identity_providers/configuring-ldap-identity-provider.adoc#configuring-ldap-identity-provider[LDAP] -|Configure the `ldap` identity provider to validate user names and passwords -against an LDAPv3 server, using simple bind authentication. - -|xref:../authentication/identity_providers/configuring-github-identity-provider.adoc#configuring-github-identity-provider[GitHub or GitHub Enterprise] -|Configure a `github` identity provider to validate user names and passwords -against GitHub or GitHub Enterprise's OAuth authentication server. - -|xref:../authentication/identity_providers/configuring-google-identity-provider.adoc#configuring-google-identity-provider[Google] -|Configure a `google` identity provider using -link:https://developers.google.com/identity/protocols/OpenIDConnect[Google's OpenID Connect integration]. - -|xref:../authentication/identity_providers/configuring-oidc-identity-provider.adoc#configuring-oidc-identity-provider[OpenID Connect] -|Configure an `oidc` identity provider to integrate with an OpenID Connect -identity provider using an -link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]. - -|=== diff --git a/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc b/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc deleted file mode 100644 index 7ba6bb5c9cea..000000000000 --- a/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="configuring-basic-authentication-identity-provider"] -= Configuring a basic authentication identity provider -include::modules/common-attributes.adoc[] -:context: configuring-basic-authentication-identity-provider - -toc::[] - -Configure a `basic-authentication` identity provider for users to log in to -{product-title} with credentials validated against a remote identity provider. -Basic authentication is a generic back-end integration mechanism. - -include::modules/identity-provider-overview.adoc[leveloffset=+1] - -include::modules/identity-provider-about-basic-authentication.adoc[leveloffset=+1] - -include::modules/identity-provider-secret.adoc[leveloffset=+1] - -include::modules/identity-provider-config-map.adoc[leveloffset=+1] - -include::modules/identity-provider-basic-authentication-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] - -include::modules/example-apache-httpd-configuration.adoc[leveloffset=+1] - -include::modules/identity-provider-basic-authentication-troubleshooting.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-github-identity-provider.adoc b/authentication/identity_providers/configuring-github-identity-provider.adoc deleted file mode 100644 index 238c15d607ae..000000000000 --- a/authentication/identity_providers/configuring-github-identity-provider.adoc +++ /dev/null @@ -1,47 +0,0 @@ -[id="configuring-github-identity-provider"] -= Configuring a GitHub or GitHub Enterprise identity provider -include::modules/common-attributes.adoc[] -:context: configuring-github-identity-provider - -toc::[] - -Configure a `github` identity provider to validate user names and passwords -against GitHub or GitHub Enterprise's OAuth authentication server. OAuth -facilitates a token exchange flow between -{product-title} and GitHub or GitHub Enterprise. - -You can use the GitHub integration to connect to either GitHub or GitHub -Enterprise. For GitHub Enterprise integrations, you must provide the `hostname` -of your instance and can optionally provide a `ca` certificate bundle to use in -requests to the server. - -[NOTE] -==== -The following steps apply to both GitHub and GitHub Enterprise unless noted. -==== - -Configuring GitHub authentication allows users to log in to {product-title} with -their GitHub credentials. To prevent anyone with any GitHub user ID from logging -in to your {product-title} cluster, you can restrict access to only those in -specific GitHub organizations. - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -include::modules/identity-provider-overview.adoc[leveloffset=+1] -endif::openshift-origin,openshift-enterprise,openshift-webscale[] - -include::modules/identity-provider-registering-github.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/identity-provider-secret.adoc[leveloffset=+1] - -include::modules/identity-provider-config-map.adoc[leveloffset=+1] - -include::modules/identity-provider-github-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] -endif::[] diff --git a/authentication/identity_providers/configuring-gitlab-identity-provider.adoc b/authentication/identity_providers/configuring-gitlab-identity-provider.adoc deleted file mode 100644 index 8a9c530daab7..000000000000 --- a/authentication/identity_providers/configuring-gitlab-identity-provider.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="configuring-gitlab-identity-provider"] -= Configuring a GitLab identity provider -include::modules/common-attributes.adoc[] -:context: configuring-gitlab-identity-provider - -toc::[] - -Configure a `gitlab` identity provider to use -link:https://gitlab.com/[GitLab.com] or any other GitLab instance as an identity -provider. If you use GitLab version 7.7.0 to 11.0, you connect using the -link:http://doc.gitlab.com/ce/integration/oauth_provider.html[OAuth integration]. -If you use GitLab version 11.1 or later, you can use -link:https://docs.gitlab.com/ce/integration/openid_connect_provider.html[OpenID Connect] (OIDC) -to connect instead of OAuth. - - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -include::modules/identity-provider-overview.adoc[leveloffset=+1] -endif::openshift-origin,openshift-enterprise,openshift-webscale[] - -include::modules/identity-provider-secret.adoc[leveloffset=+1] - -include::modules/identity-provider-config-map.adoc[leveloffset=+1] - -include::modules/identity-provider-gitlab-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-google-identity-provider.adoc b/authentication/identity_providers/configuring-google-identity-provider.adoc deleted file mode 100644 index a0ff89cec3ee..000000000000 --- a/authentication/identity_providers/configuring-google-identity-provider.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="configuring-google-identity-provider"] -= Configuring a Google identity provider -include::modules/common-attributes.adoc[] -:context: configuring-google-identity-provider - -toc::[] - -Configure a `google` identity provider using -link:https://developers.google.com/identity/protocols/OpenIDConnect[Google's OpenID Connect integration]. - -[NOTE] -==== -Using Google as an identity provider requires users to get a token using -`/oauth/token/request` to use with command-line tools. -==== - -[WARNING] -==== -Using Google as an identity provider allows any Google user to authenticate to your server. -You can limit authentication to members of a specific hosted domain with the -`hostedDomain` configuration attribute. -==== - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -include::modules/identity-provider-overview.adoc[leveloffset=+1] -endif::openshift-origin,openshift-enterprise,openshift-webscale[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/identity-provider-secret.adoc[leveloffset=+1] - -include::modules/identity-provider-google-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] -endif::[] diff --git a/authentication/identity_providers/configuring-htpasswd-identity-provider.adoc b/authentication/identity_providers/configuring-htpasswd-identity-provider.adoc deleted file mode 100644 index 008735583e47..000000000000 --- a/authentication/identity_providers/configuring-htpasswd-identity-provider.adoc +++ /dev/null @@ -1,51 +0,0 @@ -[id="configuring-htpasswd-identity-provider"] -= Configuring an HTPasswd identity provider -include::modules/common-attributes.adoc[] -:context: configuring-htpasswd-identity-provider - -toc::[] - -[id="identity-provider-overview_{context}"] -== About identity providers in {product-title} - -By default, only a `kubeadmin` user exists on your cluster. To specify an -identity provider, you must create a Custom Resource (CR) that describes -that identity provider and add it to the cluster. - -[NOTE] -==== -{product-title} user names containing `/`, `:`, and `%` are not supported. -==== - -To define an HTPasswd identity provider you must perform the -following steps: - -. Create an `htpasswd` file to store the user and password information. -Instructions are provided for -xref:../../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#identity-provider-creating-htpasswd-file-linux_{context}[Linux] -and -xref:../../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#identity-provider-creating-htpasswd-file-windows_{context}[Windows]. -. xref:../../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#identity-provider-creating-htpasswd-secret_{context}[Create -an {product-title} secret to represent the `htpasswd` file]. -. xref:../../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#identity-provider-htpasswd-CR_{context}[Define the HTPasswd identity provider resource]. -. xref:../../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#add-identity-provider_{context}[Apply the resource to -the default OAuth configuration]. - -include::modules/identity-provider-creating-htpasswd-file-linux.adoc[leveloffset=+1] - -include::modules/identity-provider-creating-htpasswd-file-windows.adoc[leveloffset=+1] - -include::modules/identity-provider-htpasswd-secret.adoc[leveloffset=+1] - -include::modules/identity-provider-htpasswd-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] - -include::modules/identity-provider-htpasswd-update-users.adoc[leveloffset=+1] - -include::modules/identity-provider-configuring-using-web-console.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-keystone-identity-provider.adoc b/authentication/identity_providers/configuring-keystone-identity-provider.adoc deleted file mode 100644 index 72cc65125b8e..000000000000 --- a/authentication/identity_providers/configuring-keystone-identity-provider.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="configuring-keystone-identity-provider"] -= Configuring a Keystone identity provider -include::modules/common-attributes.adoc[] -:context: configuring-keystone-identity-provider - -toc::[] - -Configure the `keystone` identity provider to integrate -your {product-title} cluster with Keystone to enable shared authentication with -an OpenStack Keystone v3 server configured to store users in an internal -database. This configuration allows users to log in to {product-title} with -their Keystone credentials. - -http://docs.openstack.org/developer/keystone/[Keystone] is an OpenStack project -that provides identity, token, catalog, and policy services. - -You can configure the integration with Keystone so that the new {product-title} -users are based on either the Keystone user names or unique Keystone IDs. -With both methods, users log in by entering their Keystone user name and -password. Basing the {product-title} users off of the Keystone ID is more -secure. If you delete a Keystone user and create a new Keystone user with that -user name, the new user might have access to the old user's resources. - -include::modules/identity-provider-overview.adoc[leveloffset=+1] - -include::modules/identity-provider-secret.adoc[leveloffset=+1] - -include::modules/identity-provider-config-map.adoc[leveloffset=+1] - -include::modules/identity-provider-keystone-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] diff --git a/authentication/identity_providers/configuring-ldap-identity-provider.adoc b/authentication/identity_providers/configuring-ldap-identity-provider.adoc deleted file mode 100644 index dca4424ba96e..000000000000 --- a/authentication/identity_providers/configuring-ldap-identity-provider.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="configuring-ldap-identity-provider"] -= Configuring an LDAP identity provider -include::modules/common-attributes.adoc[] -:context: configuring-ldap-identity-provider - -toc::[] - -Configure the `ldap` identity provider to validate user names and passwords -against an LDAPv3 server, using simple bind authentication. - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -include::modules/identity-provider-overview.adoc[leveloffset=+1] -endif::openshift-origin,openshift-enterprise,openshift-webscale[] - -include::modules/identity-provider-about-ldap.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/identity-provider-ldap-secret.adoc[leveloffset=+1] - -include::modules/identity-provider-config-map.adoc[leveloffset=+1] - -include::modules/identity-provider-ldap-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] -endif::[] diff --git a/authentication/identity_providers/configuring-oidc-identity-provider.adoc b/authentication/identity_providers/configuring-oidc-identity-provider.adoc deleted file mode 100644 index 5473a20e33e1..000000000000 --- a/authentication/identity_providers/configuring-oidc-identity-provider.adoc +++ /dev/null @@ -1,102 +0,0 @@ -[id="configuring-oidc-identity-provider"] -= Configuring a OpenID Connect identity provider -include::modules/common-attributes.adoc[] -:context: configuring-oidc-identity-provider - -toc::[] - -Configure an `oidc` identity provider to integrate with an OpenID Connect -identity provider using an -link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]. - -ifdef::openshift-origin[] -You can link:https://www.keycloak.org/docs/latest/server_admin/index.html#openshift[configure a Keycloak] server as an OpenID -Connect identity provider for {product-title}. -endif::[] - -ifdef::openshift-enterprise,openshift-webscale[] -You can -link:https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/[configure Red Hat Single Sign-On] -as an OpenID Connect identity provider for {product-title}. -endif::[] - -[IMPORTANT] -==== -The Authentication Operator in {product-title} requires that the configured -OpenID Connect identity provider implements the -link:https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect Discovery] -specification. -==== - -[NOTE] -==== -`ID Token` and `UserInfo` decryptions are not supported. -==== - -By default, the `openid` scope is requested. If required, extra scopes can be -specified in the `extraScopes` field. - -Claims are read from the JWT `id_token` returned from the OpenID identity -provider and, if specified, from the JSON returned by the `UserInfo` URL. - -At least one claim must be configured to use as the user's identity. The -standard identity claim is `sub`. - -You can also indicate which claims to use as the user's preferred user name, -display name, and email address. If multiple claims are specified, the first one -with a non-empty value is used. The standard claims are: - -[cols="1,2",options="header"] -|=== - -|Claim -|Description - -|`sub` -|Short for "subject identifier." The remote identity for the user at the -issuer. - -|`preferred_username` -|The preferred user name when provisioning a user. A -shorthand name that the user wants to be referred to as, such as `janedoe`. Typically -a value that corresponding to the user's login or username in the authentication -system, such as username or email. - -|`email` -|Email address. - -|`name` -|Display name. - -|=== - -See the -link:http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims[OpenID claims documentation] -for more information. - -[NOTE] -==== -Using an OpenID Connect identity provider requires users to get a token using -`/oauth/token/request` to use with command-line tools. -==== - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -include::modules/identity-provider-overview.adoc[leveloffset=+1] -endif::openshift-origin,openshift-enterprise,openshift-webscale[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/identity-provider-secret.adoc[leveloffset=+1] - -include::modules/identity-provider-config-map.adoc[leveloffset=+1] - -include::modules/identity-provider-oidc-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] - -include::modules/identity-provider-configuring-using-web-console.adoc[leveloffset=+1] -endif::[] diff --git a/authentication/identity_providers/configuring-request-header-identity-provider.adoc b/authentication/identity_providers/configuring-request-header-identity-provider.adoc deleted file mode 100644 index abec4bb305c5..000000000000 --- a/authentication/identity_providers/configuring-request-header-identity-provider.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="configuring-request-header-identity-provider"] -= Configuring a request header identity provider -include::modules/common-attributes.adoc[] -:context: configuring-request-header-identity-provider - -toc::[] - -Configure a `request-header` identity provider to identify users from request -header values, such as `X-Remote-User`. It is typically used in combination with -an authenticating proxy, which sets the request header value. - -include::modules/identity-provider-overview.adoc[leveloffset=+1] - -include::modules/identity-provider-about-request-header.adoc[leveloffset=+1] - -include::modules/identity-provider-config-map.adoc[leveloffset=+1] - -include::modules/identity-provider-request-header-CR.adoc[leveloffset=+1] - -// Included here so that it is associated with the above module -.Additional resources - -* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers. - -include::modules/identity-provider-add.adoc[leveloffset=+1] - -[id="example-apache-auth-config-using-request-header"] -== Example Apache authentication configuration using request header - -This example configures an Apache authentication proxy for the {product-title} -using the request header identity provider. - -[discrete] -include::modules/identity-provider-apache-custom-proxy-configuration.adoc[leveloffset=+2] - -[discrete] -include::modules/identity-provider-configuring-apache-request-header.adoc[leveloffset=+2] diff --git a/authentication/images b/authentication/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/authentication/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/authentication/impersonating-system-admin.adoc b/authentication/impersonating-system-admin.adoc deleted file mode 100644 index d71f3165f69b..000000000000 --- a/authentication/impersonating-system-admin.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="impersonating-system-admin"] -= Impersonating the `system:admin` user -include::modules/common-attributes.adoc[] -:context: impersonating-system-admin - -toc::[] - -include::modules/authentication-api-impersonation.adoc[leveloffset=+1] - -include::modules/impersonation-system-admin-user.adoc[leveloffset=+1] - -include::modules/impersonation-system-admin-group.adoc[leveloffset=+1] diff --git a/authentication/ldap-syncing.adoc b/authentication/ldap-syncing.adoc deleted file mode 100644 index 62a4819db6f1..000000000000 --- a/authentication/ldap-syncing.adoc +++ /dev/null @@ -1,55 +0,0 @@ -[[ldap-syncing]] -= Syncing LDAP groups -include::modules/common-attributes.adoc[] -:context: ldap-syncing-groups - -toc::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -As an administrator, -endif::[] -ifdef::openshift-dedicated[] -As a xref:../authentication/understanding-and-creating-service-accounts.html#dedicated-admin-role-overview_{context}[dedicated administrator], -endif::[] -you can use groups to manage users, change -their permissions, and enhance collaboration. Your organization may have already -created user groups and stored them in an LDAP server. {product-title} can sync -those LDAP records with internal {product-title} records, enabling you to manage -your groups in one place. {product-title} currently supports group sync with -LDAP servers using three common schemas for defining group membership: RFC 2307, -Active Directory, and augmented Active Directory. - -For more information on configuring LDAP, see -xref:../authentication/identity_providers/configuring-ldap-identity-provider.adoc#configuring-ldap-identity-provider[Configuring an LDAP identity provider]. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[NOTE] -==== -You must have `cluster-admin` privileges to sync groups. -==== -endif::[] - -ifdef::openshift-dedicated[] -[NOTE] -==== -You must have `dedicated-admins` privileges to sync groups. -==== -endif::[] - -include::modules/ldap-syncing-about.adoc[leveloffset=+1] -include::modules/ldap-syncing-config-rfc2307.adoc[leveloffset=+2] -include::modules/ldap-syncing-config-activedir.adoc[leveloffset=+2] -include::modules/ldap-syncing-config-augmented-activedir.adoc[leveloffset=+2] -include::modules/ldap-syncing-running.adoc[leveloffset=+1] -include::modules/ldap-syncing-running-all-ldap.adoc[leveloffset=+2] -include::modules/ldap-syncing-running-openshift.adoc[leveloffset=+2] -include::modules/ldap-syncing-running-subset.adoc[leveloffset=+2] -include::modules/ldap-syncing-pruning.adoc[leveloffset=+1] -include::modules/ldap-syncing-examples.adoc[leveloffset=+1] -include::modules/ldap-syncing-rfc2307.adoc[leveloffset=+2] -include::modules/ldap-syncing-rfc2307-user-defined.adoc[leveloffset=+2] -include::modules/ldap-syncing-rfc2307-user-defined-error.adoc[leveloffset=+2] -include::modules/ldap-syncing-activedir.adoc[leveloffset=+2] -include::modules/ldap-syncing-augmented-activedir.adoc[leveloffset=+2] -include::modules/ldap-syncing-nesting.adoc[leveloffset=+2] -include::modules/ldap-syncing-spec.adoc[leveloffset=+1] diff --git a/authentication/managing-oauth-access-tokens.adoc b/authentication/managing-oauth-access-tokens.adoc deleted file mode 100644 index fcdc8348720a..000000000000 --- a/authentication/managing-oauth-access-tokens.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="managing-oauth-access-tokens"] -= Managing user-owned OAuth access tokens -include::modules/common-attributes.adoc[] -:context: managing-oauth-access-tokens - -toc::[] - -Users can review their own OAuth access tokens and delete any that are no longer needed. - -// Listing user-owned OAuth access tokens -include::modules/oauth-list-tokens.adoc[leveloffset=+1] - -// Viewing the details of a user-owned OAuth access token -include::modules/oauth-view-details-tokens.adoc[leveloffset=+1] - -// Deleting user-owned OAuth access tokens -include::modules/oauth-delete-tokens.adoc[leveloffset=+1] diff --git a/authentication/managing-security-context-constraints.adoc b/authentication/managing-security-context-constraints.adoc deleted file mode 100644 index 4b275ba4b206..000000000000 --- a/authentication/managing-security-context-constraints.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="managing-pod-security-policies"] -= Managing security context constraints -include::modules/common-attributes.adoc[] -:context: configuring-internal-oauth - -toc::[] - -include::modules/security-context-constraints-about.adoc[leveloffset=+1] - -// I should add a module about installing the OC command line. - -include::modules/security-context-constraints-pre-allocated-values.adoc[leveloffset=+1] - -include::modules/security-context-constraints-example.adoc[leveloffset=+1] - -include::modules/security-context-constraints-creating.adoc[leveloffset=+1] - -include::modules/security-context-constraints-rbac.adoc[leveloffset=+1] - -include::modules/security-context-constraints-command-reference.adoc[leveloffset=+1] diff --git a/authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc b/authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc deleted file mode 100644 index 05d96e84db83..000000000000 --- a/authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc +++ /dev/null @@ -1,89 +0,0 @@ -[id="about-cloud-credential-operator"] -= About the Cloud Credential Operator -include::modules/common-attributes.adoc[] -:context: about-cloud-credential-operator -:FeatureName: Support for Amazon Web Services Secure Token Service (AWS STS) - -toc::[] - -The Cloud Credential Operator (CCO) manages cloud provider credentials as custom resource definitions (CRDs). The CCO syncs on `CredentialsRequest` custom resources (CRs) to allow {product-title} components to request cloud provider credentials with the specific permissions that are required for the cluster to run. - -By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in several different modes. If no mode is specified, or the `credentialsMode` parameter is set to an empty string (`""`), the CCO operates in its default mode. - -== Modes - -By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in _mint_, _passthrough_, or _manual_ mode. These options provide transparency and flexibility in how the CCO uses cloud credentials to process `CredentialsRequest` CRs in the cluster, and allow the CCO to be configured to suit the security requirements of your organization. Not all CCO modes are supported for all cloud providers. - -* **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-mint.adoc#cco-mode-mint[Mint]**: In mint mode, the CCO uses the provided admin-level cloud credential to create new credentials for components in the cluster with only the specific permissions that are required. -+ -[NOTE] -==== -Mint mode is the default and recommended best practice setting for the CCO to use. -==== - -* **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-passthrough.adoc#cco-mode-passthrough[Passthrough]**: In passthrough mode, the CCO passes the provided cloud credential to the components that request cloud credentials. - -* **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc#cco-mode-manual[Manual]**: In manual mode, a user manages cloud credentials instead of the CCO. - -** **xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Manual with AWS STS]**: In manual mode, you can configure an AWS cluster to use Amazon Web Services Secure Token Service (AWS STS). With this configuration, the CCO uses temporary credentials for different components. -//Tech Preview only in 4.7, needs disclaimer. Move after mint when feature is GA -+ -include::modules/technology-preview.adoc[leveloffset=+0] - -.CCO mode support matrix -[cols="<.^2,^.^1,^.^1,^.^1"] -|==== -|Cloud provider |Mint |Passthrough |Manual - -|Amazon Web Services (AWS) -|X -|X -|X - - -|Microsoft Azure -|X -|X -|X - -|Google Cloud Platform (GCP) -|X -|X -|X - -|{rh-openstack-first} -| -|X -| - -|{rh-virtualization-first} -| -|X -| - -|VMware vSphere -| -|X -| - -|==== - -== Default behavior -For platforms on which multiple modes are supported (AWS, Azure, and GCP), when the CCO operates in its default mode, it checks the provided credentials dynamically to determine for which mode they are sufficient to process `CredentialsRequest` CRs. - -By default, the CCO determines whether the credentials are sufficient for mint mode, which is the preferred mode of operation, and uses those credentials to create appropriate credentials for components in the cluster. If the credentials are not sufficient for mint mode, it determines whether they are sufficient for passthrough mode. If the credentials are not sufficient for passthrough mode, the CCO cannot adequately process `CredentialsRequest` CRs. - -[NOTE] -==== -The CCO cannot verify whether Azure credentials are sufficient for passthrough mode. If Azure credentials are insufficient for mint mode, the CCO operates with the assumption that the credentials are sufficient for passthrough mode. -==== - -If the provided credentials are determined to be insufficient during installation, the installation fails. For AWS, the installer fails early in the process and indicates which required permissions are missing. Other providers might not provide specific information about the cause of the error until errors are encountered. - -If the credentials are changed after a successful installation and the CCO determines that the new credentials are insufficient, the CCO puts conditions on any new `CredentialsRequest` CRs to indicate that it cannot process them because of the insufficient credentials. - -To resolve insufficient credentials issues, provide a credential with sufficient permissions. If an error occurred during installation, try installing again. For issues with new `CredentialsRequest` CRs, wait for the CCO to try to process the CR again. As an alternative, you can manually create IAM for xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], and xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[GCP]. - -== Additional resources - -* xref:../../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Red Hat Operators reference page for the Cloud Credential Operator] diff --git a/authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc b/authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc deleted file mode 100644 index 65dee7d67dad..000000000000 --- a/authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="cco-mode-manual"] -= Using manual mode -include::modules/common-attributes.adoc[] -:context: cco-mode-manual -:FeatureName: Support for Amazon Web Services Secure Token Service (AWS STS) - -toc::[] - -Manual mode is supported for Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP). - -In manual mode, a user manages cloud credentials instead of the Cloud Credential Operator (CCO). To use this mode, you must examine the `CredentialsRequest` CRs in the release image for the version of {product-title} that you are running or installing, create corresponding credentials in the underlying cloud provider, and create Kubernetes Secrets in the correct namespaces to satisfy all `CredentialsRequest` CRs for the cluster's cloud provider. - -Using manual mode allows each cluster component to have only the permissions it requires, without storing an administrator-level credential in the cluster. This mode also does not require connectivity to the AWS public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade. - -For information about configuring your cloud provider to use manual mode, see _Manually creating IAM_ for xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], or xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[GCP]. - -include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1] - -[id="manual-mode-sts-blurb"] -== Manual mode with AWS STS - -You can configure an AWS cluster in manual mode to use xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Amazon Web Services Secure Token Service (AWS STS)]. With this configuration, the CCO uses temporary credentials for different components. - -include::modules/technology-preview.adoc[leveloffset=+0] - -== Additional resources - -* xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[Manually creating IAM for AWS] -* xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Manually creating IAM for Azure] -* xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[Manually creating IAM for GCP] -* xref:../../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#cco-mode-sts[Using manual mode with AWS STS] diff --git a/authentication/managing_cloud_provider_credentials/cco-mode-mint.adoc b/authentication/managing_cloud_provider_credentials/cco-mode-mint.adoc deleted file mode 100644 index b9c733c9e0b1..000000000000 --- a/authentication/managing_cloud_provider_credentials/cco-mode-mint.adoc +++ /dev/null @@ -1,70 +0,0 @@ -[id="cco-mode-mint"] -= Using mint mode -include::modules/common-attributes.adoc[] -:context: cco-mode-mint - -toc::[] - -Mint mode is supported for Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP). - -Mint mode is the default and recommended best practice setting for the Cloud Credential Operator (CCO) to use on the platforms for which it is supported. In this mode, the CCO uses the provided administrator-level cloud credential to create new credentials for components in the cluster with only the specific permissions that are required. - -If the credential is not removed after installation, it is stored and used by the CCO to process `CredentialsRequest` CRs for components in the cluster and create new credentials for each with only the specific permissions that are required. The continuous reconciliation of cloud credentials in mint mode allows actions that require additional credentials or permissions, such as upgrading, to proceed. - -If the requirement that mint mode stores the administrator-level credential in the cluster `kube-system` namespace does not suit the security requirements of your organization, see _Alternatives to storing administrator-level secrets in the kube-system project_ for xref:../../installing/installing_aws/manually-creating-iam.adoc#alternatives-to-storing-admin-secrets-in-kube-system_manually-creating-iam-aws[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#alternatives-to-storing-admin-secrets-in-kube-system_manually-creating-iam-azure[Azure], or xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#alternatives-to-storing-admin-secrets-in-kube-system_manually-creating-iam-gcp[GCP]. - -[id="mint-mode-permissions"] -== Mint mode permissions requirements -When using the CCO in mint mode, ensure that the credential you provide meets the requirements of the cloud on which you are running or installing {product-title}. If the provided credentials are not sufficient for mint mode, the CCO cannot create an IAM user. - -[id="mint-mode-permissions-aws"] -=== Amazon Web Services (AWS) permissions -The credential you provide for mint mode in AWS must have the following permissions: - -* `iam:CreateAccessKey` -* `iam:CreateUser` -* `iam:DeleteAccessKey` -* `iam:DeleteUser` -* `iam:DeleteUserPolicy` -* `iam:GetUser` -* `iam:GetUserPolicy` -* `iam:ListAccessKeys` -* `iam:PutUserPolicy` -* `iam:TagUser` -* `iam:SimulatePrincipalPolicy` - -[id="mint-mode-permissions-azure"] -=== Microsoft Azure permissions -The credential you provide for mint mode in Azure must have a service principal with the permissions specified in xref:../../installing/installing_azure/installing-azure-account.adoc#installation-azure-service-principal_installing-azure-account[Creating a service principal]. - -[id="mint-mode-permissions-gcp"] -=== Google Cloud Platform (GCP) permissions -The credential you provide for mint mode in GCP must have the following permissions: - -* `resourcemanager.projects.get` -* `serviceusage.services.list` -* `iam.serviceAccountKeys.create` -* `iam.serviceAccountKeys.delete` -* `iam.serviceAccounts.create` -* `iam.serviceAccounts.delete` -* `iam.serviceAccounts.get` -* `iam.roles.get` -* `resourcemanager.projects.getIamPolicy` -* `resourcemanager.projects.setIamPolicy` - -//Mint Mode with removal or rotation of the admin credential -include::modules/mint-mode-with-removal-of-admin-credential.adoc[leveloffset=+1] - -//Rotating cloud provider credentials manually -include::modules/manually-rotating-cloud-creds.adoc[leveloffset=+2] - -//Removing cloud provider credentials -include::modules/manually-removing-cloud-creds.adoc[leveloffset=+2] - - -== Additional resources - -* xref:../../installing/installing_aws/manually-creating-iam.adoc#alternatives-to-storing-admin-secrets-in-kube-system_manually-creating-iam-aws[Alternatives to storing administrator-level secrets in the kube-system project] for AWS -* xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#alternatives-to-storing-admin-secrets-in-kube-system_manually-creating-iam-azure[Alternatives to storing administrator-level secrets in the kube-system project] for Azure -* xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#alternatives-to-storing-admin-secrets-in-kube-system_manually-creating-iam-gcp[Alternatives to storing administrator-level secrets in the kube-system project] for GCP -* xref:../../installing/installing_azure/installing-azure-account.adoc#installation-azure-service-principal_installing-azure-account[Creating a service principal] in Azure diff --git a/authentication/managing_cloud_provider_credentials/cco-mode-passthrough.adoc b/authentication/managing_cloud_provider_credentials/cco-mode-passthrough.adoc deleted file mode 100644 index 2003199dbb2c..000000000000 --- a/authentication/managing_cloud_provider_credentials/cco-mode-passthrough.adoc +++ /dev/null @@ -1,100 +0,0 @@ -[id="cco-mode-passthrough"] -= Using passthrough mode -include::modules/common-attributes.adoc[] -:context: cco-mode-passthrough - -toc::[] - -Passthrough mode is supported for Amazon Web Services (AWS), Microsoft Azure, Google Cloud Platform (GCP), {rh-openstack-first}, {rh-virtualization-first}, and VMware vSphere. - -In passthrough mode, the Cloud Credential Operator (CCO) passes the provided cloud credential to the components that request cloud credentials. The credential must have permissions to perform the installation and complete the operations that are required by components in the cluster, but does not need to be able to create new credentials. The CCO does not attempt to create additional limited-scoped credentials in passthrough mode. - -[id="passthrough-mode-permissions"] -== Passthrough mode permissions requirements -When using the CCO in passthrough mode, ensure that the credential you provide meets the requirements of the cloud on which you are running or installing {product-title}. If the provided credentials the CCO passes to a component that creates a `CredentialsRequest` CR are not sufficient, that component will report an error when it tries to call an API that it does not have permissions for. - -[id="passthrough-mode-permissions-aws"] -=== Amazon Web Services (AWS) permissions -The credential you provide for passthrough mode in AWS must have all the requested permissions for all `CredentialsRequest` CRs that are required by the version of {product-title} you are running or installing. - -To locate the `CredentialsRequest` CRs that are required, see xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[Manually creating IAM for AWS]. - -[id="passthrough-mode-permissions-azure"] -=== Microsoft Azure permissions -The credential you provide for passthrough mode in Azure must have all the requested permissions for all `CredentialsRequest` CRs that are required by the version of {product-title} you are running or installing. - -To locate the `CredentialsRequest` CRs that are required, see xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Manually creating IAM for Azure]. - -[id="passthrough-mode-permissions-gcp"] -=== Google Cloud Platform (GCP) permissions -The credential you provide for passthrough mode in GCP must have all the requested permissions for all `CredentialsRequest` CRs that are required by the version of {product-title} you are running or installing. - -To locate the `CredentialsRequest` CRs that are required, see xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[Manually creating IAM for GCP]. - -[id="passthrough-mode-permissions-rhosp"] -=== {rh-openstack-first} permissions -To install an {product-title} cluster on {rh-openstack}, the CCO requires a credential with the permissions of a `member` user role. - -[id="passthrough-mode-permissions-rhv"] -=== {rh-virtualization-first} permissions -To install an {product-title} cluster on {rh-virtualization}, the CCO requires a credential with the following privileges: - -* `DiskOperator` -* `DiskCreator` -* `UserTemplateBasedVm` -* `TemplateOwner` -* `TemplateCreator` -* `ClusterAdmin` on the specific cluster that is targeted for {product-title} deployment - -[id="passthrough-mode-permissions-vsware"] -=== VMware vSphere permissions -To install an {product-title} cluster on VMware vSphere, the CCO requires a credential with the following vSphere privileges: - -.Required vSphere privileges -[cols="1,2"] -|==== -|Category |Privileges - -|Datastore -|_Allocate space_ - -|Folder -|_Create folder_, _Delete folder_ - -|vSphere Tagging -|All privileges - -|Network -|_Assign network_ - -|Resource -|_Assign virtual machine to resource pool_ - -|Profile-driven storage -|All privileges - -|vApp -|All privileges - -|Virtual machine -|All privileges - -|==== - -[id="passthrough-mode-maintenance"] -== Passthrough mode credential maintenance -If `CredentialsRequest` CRs change over time as the cluster is upgraded, you must manually update the passthrough mode credential to meet the requirements. To avoid credentials issues during an upgrade, check the `CredentialsRequest` CRs in the release image for the new version of {product-title} before upgrading. To locate the `CredentialsRequest` CRs that are required for your cloud provider, see _Manually creating IAM_ for xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], or xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[GCP]. - -[id="passthrough-mode-reduce-permissions"] -== Reducing permissions after installation -When using passthrough mode, each component has the same permissions used by all other components. If you do not reduce the permissions after installing, all components have the broad permissions that are required to run the installer. - -After installation, you can reduce the permissions on your credential to only those that are required to run the cluster, as defined by the `CredentialsRequest` CRs in the release image for the version of {product-title} that you are using. - -To locate the `CredentialsRequest` CRs that are required for AWS, Azure, or GCP and learn how to change the permissions the CCO uses, see _Manually creating IAM_ for xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[AWS], xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Azure], or xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[GCP]. - -== Additional resources - -* xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[Manually creating IAM for AWS] -* xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[Manually creating IAM for Azure] -* xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[Manually creating IAM for GCP] diff --git a/authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc b/authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc deleted file mode 100644 index 12570b78d0a1..000000000000 --- a/authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc +++ /dev/null @@ -1,764 +0,0 @@ -[id="cco-mode-sts"] -= Using manual mode with STS -include::modules/common-attributes.adoc[] -:context: cco-mode-sts - -toc::[] - -Manual mode with STS is available as a link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] for Amazon Web Services (AWS). - -:FeatureName: Support for AWS Secure Token Service (STS) -include::modules/technology-preview.adoc[leveloffset=+0] - -In manual mode with STS, the individual {product-title} cluster components use AWS Secure Token Service (STS) to assign components IAM roles that provide short-term, limited-privilege security credentials. These credentials are associated with IAM roles that are specific to each component that makes AWS API calls. - -Requests for new and refreshed credentials are automated by using an appropriately configured AWS IAM OpenID Connect (OIDC) identity provider, combined with AWS IAM roles. {product-title} signs service account tokens that are trusted by AWS IAM, and can be projected into a pod and used for authentication. Tokens are refreshed after one hour. - -//to-do: more detailed info on this flow - -.STS authentication flow -image::142_OpenShift_credentials_STS_0221.svg[Detailed authentication flow between AWS and the cluster when using AWS STS] -//to-do: improve alt-text - -Using manual mode with STS changes the content of the AWS credentials that are provided to individual {product-title} components. - -.AWS secret format using long-lived credentials - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - namespace: <1> - name: <2> -data: - aws_access_key_id: - aws_secret_access_key: ----- -<1> The namespace for the component. -<2> The name of the component secret. - -.AWS secret format with STS - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - namespace: <1> - name: <2> -data: - role_name: <3> - web_identity_token_file: <4> ----- -<1> The namespace for the component. -<2> The name of the component secret. -<3> The IAM role for the component. -<4> The path to the service account token inside the pod. By convention, this is `/var/run/secrets/openshift/serviceaccount/token` for {product-title} components. - -[id="sts-mode-installing"] -== Installing an {product-title} cluster configured for manual mode with STS - -To install a cluster that is configured to use the CCO in manual mode with STS in {product-title} version 4.7: - -* xref:#sts-mode-installing-manual-config[Create the required AWS resources] -* xref:#sts-mode-installing-manual-run-installer[Run the {product-title} installer] -* xref:#sts-mode-installing-verifying[Verify that the cluster is using short-lived credentials] - -//// -In {product-title} version 4.7, you can install a cluster that is configured to use the CCO in manual mode with STS by using one of two methods: - -* xref:#sts-mode-installing-preflight-config[Configuring a cluster with the `sts-preflight` tool] -* xref:#sts-mode-installing-manual-config[Configuring a cluster manually] - -After installing with either of these methods, the procedure for xref:#sts-mode-installing-verifying[verifying the installation] is the same. - -[id="sts-mode-installing-preflight-config"] -=== Configuring a cluster with the sts-preflight tool - -When xref:#sts-mode-installing[installing] an {product-title} cluster that is configured to use the CCO in manual mode with STS, you can use the `sts-preflight` tool to create the required AWS resources. - -This tool, which is hosted in an external repository, helps configure a cluster that uses STS mode while the feature is a link:https://access.redhat.com/support/offerings/techpreview[Technology Preview]. - -As an alternative, you can xref:#sts-mode-installing-manual-config[create the required AWS resources manually]. - -[id="sts-mode-installing-preflight-preparing"] -==== Preparing the installer - -.Prerequisites -* Obtain the pull secret for your cluster. -* Obtain the {product-title} version 4.7 installation binary. - -.Procedure - -. From the directory that contains the installation program, obtain details of the {product-title} release image that your `openshift-install` binary is built to use: -+ -[source,terminal] ----- -$ ./openshift-install version ----- -+ -.Example output -[source,terminal] ----- -./openshift-install 4.7.0 -built from commit 2d8b61dd8802058ffffcdc576e0cff67acebdb85 -release image registry.svc.ci.openshift.org/ocp/release@sha256:a322ab4941701452f428f5c138efb5354ad2aec33f6f7693f0a3033bfe257d8c ----- - -. Extract the AWS `CredentialsRequest` custom resources (CRs) from the release image: -+ -[source,terminal] ----- -$ mkdir credreqs ; oc adm release extract --cloud=aws --credentials-requests quay.io/openshift-release-dev/ocp-release:4..-x86_64 --to=./credreqs ; cat ./credreqs/*.yaml > credreqs.yaml ----- -+ -Where `` and `` are the numbers corresponding to the version of {product-title} you are installing. - -. Create the `install-config.yaml` file: -+ -[source,terminal] ----- -$ ./openshift-install create install-config ----- - -. Configure the cluster to install with the CCO in manual mode: -+ -[source,terminal] ----- -$ echo "credentialsMode: Manual" >> install-config.yaml ----- - -. Create install manifests: -+ -[source,terminal] ----- -$ ./openshift-install create manifests ----- - -[id="sts-mode-installing-preflight-using"] -==== Using the sts-preflight tool - -.Prerequisites -* Download and build the link:https://github.com/sjenning/sts-preflight[`sts-preflight` tool]. - -.Procedure - -. Using an AWS account with administrator-level permissions, run the following command to: -+ --- -** Generate public and private `ServiceAccount` object signing keys. -** Create an S3 bucket. -** Upload the OIDC config into the S3 bucket. -** Set up an IAM Identity Provider that trusts the S3 bucket. -** Create an IAM role with administrator rights to use for installation. -** Create IAM roles for each AWS `CredentialsRequest` CR. -+ -[source,terminal] ----- -$ ./sts-preflight create --infra-name --region --credentials-requests-to-roles ----- -+ -Where `` is a prefix the `sts-preflight` tool uses when naming the objects that are created in AWS. --- -+ -The files that are required by the installer are added to the `_output` directory. - -. The `sts-preflight` tool does not put conditions that allow only specific `ServiceAccount` objects to assume a role on the IAM roles that it creates. To restrict which identities can assume which role, you must manually modify the trust relationship of each role to add a corresponding condition. -+ -[NOTE] -==== -Role names that exceed 64 characters might be truncated. -==== - -.. Modify the trust relationship of the `-openshift-image-registry-installer-cloud-credentials` role to have the following condition: -+ -[source,json] ----- -"Condition": { - "StringEquals": { - "s3..amazonaws.com/-installer:sub": [ - "system:serviceaccount:openshift-image-registry:registry", - "system:serviceaccount:openshift-image-registry:cluster-image-registry-operator" - ] - } -} ----- - -.. Modify the trust relationship of the `-openshift-ingress-operator-cloud-credentials` role to have the following condition: -+ -[source,json] ----- -"Condition": { - "StringEquals": { - "s3..amazonaws.com/-installer:sub": [ - "system:serviceaccount:openshift-ingress-operator:ingress-operator" - ] - } -} ----- - -.. Modify the trust relationship of the `-openshift-cluster-csi-drivers-ebs-cloud-credentials` role to have the following condition: -+ -[source,json] ----- -"Condition": { - "StringEquals": { - "s3..amazonaws.com/-installer:sub": [ - "system:serviceaccount:openshift-cluster-csi-drivers:aws-ebs-csi-driver-operator", - "system:serviceaccount:openshift-cluster-csi-drivers:aws-ebs-csi-driver-controller-sa" - ] - } -} ----- - -.. Modify the trust relationship of the `-openshift-machine-api-aws-cloud-credentials` role to have the following condition: -+ -[source,json] ----- -"Condition": { - "StringEquals": { - "s3..amazonaws.com/-installer:sub": [ - "system:serviceaccount:openshift-machine-api:machine-api-controllers" - ] - } -} ----- - -. Copy the manifests that the `sts-preflight` tool created to the `manifests` directory in the same location as the `install-config.yaml` file: -+ -[source,terminal] ----- -$ cp _output/manifests/* /manifests/ ----- - -. Copy the private key for the `ServiceAccount` object signer to the same location as the `install-config.yaml` file: -+ -[source,terminal] ----- -$ cp -a _output/tls ----- - -. Create a token that is trusted by the OIDC identity provider: -+ -[source,terminal] ----- -$ ./sts-preflight token ----- -+ -This token is used to assume a role to get the credentials that are required to start the installation. The token is created in the `_output/token` directory. - -. Use the token to assume the installer role and create the credentials that are required for the {product-title} installation process. -+ -[source,terminal] ----- -$ ./sts-preflight assume ----- -+ -The output prints several `export` commands. - -. Run the `export` commands from the output of the previous step. -+ -[source,terminal] ----- -$ export AWS_ACCESS_KEY_ID= ----- -+ -[source,terminal] ----- -$ export AWS_SECRET_ACCESS_KEY= ----- -+ -[source,terminal] ----- -$ export AWS_SESSION_TOKEN= ----- - -[id="sts-mode-installing-preflight-run-installer"] -==== Running the installer - -. Run the {product-title} installer -+ -[source,terminal] ----- -$ ./openshift-install create cluster --log-level=debug ----- - -. Continue to xref:#sts-mode-installing-verifying[Verifying the installation]. - -[id="sts-mode-installing-manual-config"] -=== Configuring a cluster manually - -When xref:#sts-mode-installing[installing] an {product-title} cluster that is configured to use the CCO in manual mode with STS, you can manually create the required AWS resources. - -As an alternative, you can use the xref:#sts-mode-installing-preflight-config[`sts-preflight` tool] to create AWS resources. -//// - -[id="sts-mode-installing-manual-config"] -=== Creating AWS resources manually - -To install an {product-title} cluster that is configured to use the CCO in manual mode with STS, you must first manually create the required AWS resources. - -.Procedure - -. Generate a private key to sign the `ServiceAccount` object: -+ -[source,terminal] ----- -$ openssl genrsa -out sa-signer 4096 ----- - -. Generate a `ServiceAccount` object public key: -+ -[source,terminal] ----- -$ openssl rsa -in sa-signer -pubout -out sa-signer.pub ----- - -. Create an S3 bucket to hold the OIDC configuration: -+ -[source,terminal] ----- -$ aws s3api create-bucket --bucket --region --create-bucket-configuration LocationConstraint= ----- -+ -[NOTE] -==== -If the value of `` is `us-east-1`, do not specify the `LocationConstraint` parameter. -==== - -. Retain the S3 bucket URL: -+ -[source,terminal] ----- -OPENID_BUCKET_URL="https://.s3..amazonaws.com" ----- - -. Build an OIDC configuration: - -.. Create a file named `keys.json` that contains the following information: -+ -[source,json] ----- -{ - "keys": [ - { - "use": "sig", - "kty": "RSA", - "kid": "", - "alg": "RS256", - "n": "", - "e": "" - } - ] -} ----- -+ -Where: - -*** `` is generated from the public key with: -+ -[source,terminal] ----- -$ openssl rsa -in sa-signer.pub -pubin --outform DER | openssl dgst -binary -sha256 | openssl base64 | tr '/+' '_-' | tr -d '=' ----- -+ -This command converts the public key to DER format, performs a SHA-256 checksum on the binary representation, encodes the data with base64 encoding, and then changes the base64-encoded output to base64URL encoding. - -*** `` is generated from the public key with: -+ -[source,terminal] ----- -$ openssl rsa -pubin -in sa-signer.pub -modulus -noout | sed -e 's/Modulus=//' | xxd -r -p | base64 -w0 | tr '/+' '_-' | tr -d '=' ----- -+ -This command prints the modulus of the public key, extracts the hex representation of the modulus, converts the ASCII hex to binary, encodes the data with base64 encoding, and then changes the base64-encoded output to base64URL encoding. - -*** `` is generated from the public key with: -+ -[source,terminal] ----- -$ printf "%016x" $(openssl rsa -pubin -in sa-signer.pub -noout -text | grep Exponent | awk '{ print $2 }') | awk '{ sub(/(00)+/, "", $1); print $1 }' | xxd -r -p | base64 -w0 | tr '/+' '_-' | tr -d '=' ----- -+ -This command extracts the decimal representation of the public key exponent, prints it as hex with a padded `0` if needed, removes leading `00` pairs, converts the ASCII hex to binary, encodes the data with base64 encoding, and then changes the base64-encoded output to use only characters that can be used in a URL. - -.. Create a file named `openid-configuration` that contains the following information: -+ -[source,json] ----- -{ - "issuer": "$OPENID_BUCKET_URL", - "jwks_uri": "${OPENID_BUCKET_URL}/keys.json", - "response_types_supported": [ - "id_token" - ], - "subject_types_supported": [ - "public" - ], - "id_token_signing_alg_values_supported": [ - "RS256" - ], - "claims_supported": [ - "aud", - "exp", - "sub", - "iat", - "iss", - "sub" - ] -} ----- - -. Upload the OIDC configuration: -+ -[source,terminal] ----- -$ aws s3api put-object --bucket --key keys.json --body ./keys.json ----- -+ -[source,terminal] ----- -$ aws s3api put-object --bucket --key '.well-known/openid-configuration' --body ./openid-configuration ----- -+ -Where `` is the S3 bucket that was created to hold the OIDC configuration. - -. Allow the AWS IAM OIDC identity provider to read these files: -+ -[source,terminal] ----- -$ aws s3api put-object-acl --bucket --key keys.json --acl public-read ----- -+ -[source,terminal] ----- -$ aws s3api put-object-acl --bucket --key '.well-known/openid-configuration' --acl public-read ----- - -. Create an AWS IAM OIDC identity provider: - -.. Get the certificate chain from the server that hosts the OIDC configuration: -+ -[source,terminal] ----- -$ echo | openssl s_client -servername $.s3.$.amazonaws.com -connect $.s3.$.amazonaws.com:443 -showcerts 2>/dev/null | awk '/BEGIN/,/END/{ if(/BEGIN/){a++}; out="cert"a".pem"; print >out}' ----- - -.. Calculate the fingerprint for the certificate at the root of the chain: -+ -[source,terminal] ----- -$ export BUCKET_FINGERPRINT=$(openssl x509 -in cert.pem -fingerprint -noout | sed -e 's/.*Fingerprint=//' -e 's/://g') ----- -+ -Where `` is the highest number in the files that were saved. For example, if `2` is the highest number in the files that were saved, use `cert2.pem`. - -.. Create the identity provider: -+ -[source,terminal] ----- -$ aws iam create-open-id-connect-provider --url $OPENID_BUCKET_URL --thumbprint-list $BUCKET_FINGERPRINT --client-id-list openshift sts.amazonaws.com ----- - -.. Retain the returned ARN of the newly created identity provider. This ARN is later referred to as ``. - -. Generate IAM roles: - -.. Locate all `CredentialsRequest` CRs in this release image that target the cloud you are deploying on: -+ -[source,terminal] ----- -$ oc adm release extract quay.io/openshift-release-dev/ocp-release:4..-x86_64 --credentials-requests --cloud=aws ----- -+ -Where `` and `` are the numbers corresponding to the version of {product-title} you are installing. - -.. For each `CredentialsRequest` CR, create an IAM role of type `Web identity` using the previously created IAM Identity Provider that grants the necessary permissions and establishes a trust relationship that trusts the identity provider previously created. -+ -For example, for the openshift-machine-api-operator `CredentialsRequest` CR in `0000_30_machine-api-operator_00_credentials-request.yaml`, create an IAM role that allows an identity from the created OIDC provider created for the cluster, similar to the following: -+ -[source,json] ----- -{ - "Role": { - "Path": "/", - "RoleName": "openshift-machine-api-aws-cloud-credentials", - "RoleId": "ARSOMEROLEID", - "Arn": "arn:aws:iam::123456789012:role/openshift-machine-api-aws-cloud-credentials", - "CreateDate": "2021-01-06T15:54:13Z", - "AssumeRolePolicyDocument": { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Federated": "" - }, - "Action": "sts:AssumeRoleWithWebIdentity", - "Condition": { - "StringEquals": { - ".s3..amazonaws.com/$BUCKET_NAME:aud": "openshift" - } - } - } - ] - }, - "Description": "OpenShift role for openshift-machine-api/aws-cloud-credentials", - "MaxSessionDuration": 3600, - "RoleLastUsed": { - "LastUsedDate": "2021-02-03T02:51:24Z", - "Region": "" - } - } -} ----- -+ -Where `` is the returned ARN of the newly created identity provider. - -.. To further restrict the role such that only specific cluster `ServiceAccount` objects can assume the role, modify the trust relationship of each role by updating the `.Role.AssumeRolePolicyDocument.Statement[].Condition` field to the specific `ServiceAccount` objects for each component. - -*** Modify the trust relationship of the `cluster-image-registry-operator` role to have the following condition: -+ -[source,json] ----- -"Condition": { - "StringEquals": { - ".s3..amazonaws.com:sub": [ - "system:serviceaccount:openshift-image-registry:registry", - "system:serviceaccount:openshift-image-registry:cluster-image-registry-operator" - ] - } -} ----- - -*** Modify the trust relationship of the `openshift-ingress-operator` to have the following condition: -+ -[source,json] ----- -"Condition": { - "StringEquals": { - ".s3..amazonaws.com:sub": [ - "system:serviceaccount:openshift-ingress-operator:ingress-operator" - ] - } -} ----- - -*** Modify the trust relationship of the `openshift-cluster-csi-drivers` to have the following condition: -+ -[source,json] ----- -"Condition": { - "StringEquals": { - ".s3..amazonaws.com:sub": [ - "system:serviceaccount:openshift-cluster-csi-drivers:aws-ebs-csi-driver-operator", - "system:serviceaccount:openshift-cluster-csi-drivers:aws-ebs-csi-driver-controller-sa" - ] - } -} ----- - -*** Modify the trust relationship of the `openshift-machine-api` to have the following condition: -+ -[source,json] ----- -"Condition": { - "StringEquals": { - ".s3..amazonaws.com:sub": [ - "system:serviceaccount:openshift-machine-api:machine-api-controllers" - ] - } -} ----- - -. For each IAM role, attach an IAM policy to the role that reflects the required permissions from the corresponding `CredentialsRequest` objects. -+ -For example, for `openshift-machine-api`, attach an IAM policy similar to the following: -+ -[source,json] ----- -{ - "RoleName": "openshift-machine-api-aws-cloud-credentials", - "PolicyName": "openshift-machine-api-aws-cloud-credentials", - "PolicyDocument": { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "ec2:CreateTags", - "ec2:DescribeAvailabilityZones", - "ec2:DescribeDhcpOptions", - "ec2:DescribeImages", - "ec2:DescribeInstances", - "ec2:DescribeSecurityGroups", - "ec2:DescribeSubnets", - "ec2:DescribeVpcs", - "ec2:RunInstances", - "ec2:TerminateInstances", - "elasticloadbalancing:DescribeLoadBalancers", - "elasticloadbalancing:DescribeTargetGroups", - "elasticloadbalancing:RegisterInstancesWithLoadBalancer", - "elasticloadbalancing:RegisterTargets", - "iam:PassRole", - "iam:CreateServiceLinkedRole" - ], - "Resource": "*" - }, - { - "Effect": "Allow", - "Action": [ - "kms:Decrypt", - "kms:Encrypt", - "kms:GenerateDataKey", - "kms:GenerateDataKeyWithoutPlainText", - "kms:DescribeKey" - ], - "Resource": "*" - }, - { - "Effect": "Allow", - "Action": [ - "kms:RevokeGrant", - "kms:CreateGrant", - "kms:ListGrants" - ], - "Resource": "*", - "Condition": { - "Bool": { - "kms:GrantIsForAWSResource": true - } - } - } - ] - } -} ----- -. Prepare to run the {product-title} installer: - -.. Create the `install-config.yaml` file: -+ -[source,terminal] ----- -$ ./openshift-install create install-config ----- - -.. Configure the cluster to install with the CCO in manual mode: -+ -[source,terminal] ----- -$ echo "credentialsMode: Manual" >> install-config.yaml ----- - -.. Create install manifests: -+ -[source,terminal] ----- -$ ./openshift-install create manifests ----- - -.. Create a `tls` directory, and copy the private key generated previously there: -+ -[NOTE] -==== -The target file name must be `./tls/bound-service-account-signing-key.key`. -==== -+ -[source,terminal] ----- -$ mkdir tls ; cp ./tls/bound-service-account-signing-key.key ----- - -.. Create a custom `Authentication` CR with the file name `cluster-authentication-02-config.yaml`: -+ -[source,terminal] ----- -$ cat << EOF > manifests/cluster-authentication-02-config.yaml -apiVersion: config.openshift.io/v1 -kind: Authentication -metadata: - name: cluster -spec: - serviceAccountIssuer: $OPENID_BUCKET_URL -EOF ----- -//// -.. Locate all `CredentialsRequest` CRs in this release image that target the cloud you are deploying on: -+ -[source,terminal] ----- -$ oc adm release extract quay.io/openshift-release-dev/ocp-release:4..-x86_64 --credentials-requests --cloud=aws ----- -+ -Where `` and `` are the numbers corresponding to the version of {product-title} you are installing. -//// - -.. For each `CredentialsRequest` CR that is extracted from the release image, create a secret with the target namespace and target name that is indicated in each `CredentialsRequest`, substituting the AWS IAM role ARN created previously for each component: -+ -.Example secret manifest for `openshift-machine-api`: -+ -[source,terminal] ----- -$ cat manifests/openshift-machine-api-aws-cloud-credentials-credentials.yaml -apiVersion: v1 -stringData: - credentials: |- - [default] - role_arn = arn:aws:iam::123456789012:role/openshift-machine-api-aws-cloud-credentials - web_identity_token_file = /var/run/secrets/openshift/serviceaccount/token -kind: Secret -metadata: - name: aws-cloud-credentials - namespace: openshift-machine-api -type: Opaque ----- - -[id="sts-mode-installing-manual-run-installer"] -=== Running the installer - -. Run the {product-title} installer: -+ -[source,terminal] ----- -$ ./openshift-install create cluster ----- - -. Continue to xref:#sts-mode-installing-verifying[Verifying the installation]. - -[id="sts-mode-installing-verifying"] -=== Verifying the installation - -. Connect to the {product-title} cluster. - -. Verify that the cluster does not have `root` credentials: -+ -[source,terminal] ----- -$ oc get secrets -n kube-system aws-creds ----- -+ -The output should look similar to: -+ -[source,terminal] ----- -Error from server (NotFound): secrets "aws-creds" not found ----- - -. Verify that the components are assuming the IAM roles that are specified in the secret manifests, instead of using credentials that are created by the CCO: -+ -.Example command with the Image Registry Operator -[source,terminal] ----- -$ oc get secrets -n openshift-image-registry installer-cloud-credentials -o json | jq -r .data.credentials | base64 -d ----- -+ -The output should show the role and web identity token that are used by the component and look similar to: -+ -.Example output with the Image Registry Operator -[source,terminal] ----- -[default] -role_arn = arn:aws:iam::123456789:role/openshift-image-registry-installer-cloud-credentials -web_identity_token_file = /var/run/secrets/openshift/serviceaccount/token ----- diff --git a/authentication/managing_cloud_provider_credentials/images b/authentication/managing_cloud_provider_credentials/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/authentication/managing_cloud_provider_credentials/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/authentication/managing_cloud_provider_credentials/modules b/authentication/managing_cloud_provider_credentials/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/authentication/managing_cloud_provider_credentials/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/authentication/modules b/authentication/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/authentication/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/authentication/remove-kubeadmin.adoc b/authentication/remove-kubeadmin.adoc deleted file mode 100644 index 9a66a0c2b889..000000000000 --- a/authentication/remove-kubeadmin.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="removing-kubeadmin"] -= Removing the kubeadmin user -include::modules/common-attributes.adoc[] -:context: removing-kubeadmin - -toc::[] - -include::modules/authentication-kubeadmin.adoc[leveloffset=+1] - -include::modules/authentication-remove-kubeadmin.adoc[leveloffset=+1] diff --git a/authentication/tokens-scoping.adoc b/authentication/tokens-scoping.adoc deleted file mode 100644 index 060ddce00817..000000000000 --- a/authentication/tokens-scoping.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="tokens-scoping"] -= Scoping tokens -include::modules/common-attributes.adoc[] -:context: configuring-internal-oauth - -toc::[] - -include::modules/tokens-scoping-about.adoc[leveloffset=+1] diff --git a/authentication/understanding-and-creating-service-accounts.adoc b/authentication/understanding-and-creating-service-accounts.adoc deleted file mode 100644 index 4ef0374388ae..000000000000 --- a/authentication/understanding-and-creating-service-accounts.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="understanding-and-creating-service-accounts"] -= Understanding and creating service accounts -include::modules/common-attributes.adoc[] -:context: understanding-service-accounts - -toc::[] - -include::modules/service-accounts-overview.adoc[leveloffset=+1] - -include::modules/service-accounts-dedicated-admin-role.adoc[leveloffset=+1] - -include::modules/dedicated-admin-role-overview.adoc[leveloffset=+1] - -// include::modules/service-accounts-enabling-authentication.adoc[leveloffset=+1] - -include::modules/service-accounts-creating.adoc[leveloffset=+1] - -// include::modules/service-accounts-configuration-parameters.adoc[leveloffset=+1] - -include::modules/service-accounts-granting-roles.adoc[leveloffset=+1] diff --git a/authentication/understanding-authentication.adoc b/authentication/understanding-authentication.adoc deleted file mode 100644 index 402c04980512..000000000000 --- a/authentication/understanding-authentication.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="understanding-authentication"] -= Understanding authentication -include::modules/common-attributes.adoc[] -:context: understanding-authentication - -toc::[] - -For users to interact with {product-title}, they must first authenticate -to the cluster. The authentication layer identifies the user associated with requests to the -{product-title} API. The authorization layer then uses information about the -requesting user to determine if the request is allowed. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -As an administrator, you can configure authentication for {product-title}. -endif::[] - -include::modules/rbac-users.adoc[leveloffset=+1] - -include::modules/rbac-groups.adoc[leveloffset=+1] - -include::modules/rbac-api-authentication.adoc[leveloffset=+1] - -include::modules/oauth-server-overview.adoc[leveloffset=+2] - -include::modules/oauth-token-requests.adoc[leveloffset=+2] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/authentication-api-impersonation.adoc[leveloffset=+3] - -include::modules/authentication-prometheus-system-metrics.adoc[leveloffset=+3] -endif::[] diff --git a/authentication/understanding-certificates.adoc b/authentication/understanding-certificates.adoc deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/authentication/understanding-identity-provider.adoc b/authentication/understanding-identity-provider.adoc deleted file mode 100644 index 956423069eb2..000000000000 --- a/authentication/understanding-identity-provider.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id="understanding-identity-provider"] -= Understanding identity provider configuration -include::modules/common-attributes.adoc[] -:context: understanding-identity-provider - -toc::[] - -The {product-title} master includes a built-in OAuth server. Developers and -administrators obtain OAuth access tokens to authenticate themselves to the API. - -As an administrator, you can configure OAuth to specify an identity provider -after you install your cluster. - -include::modules/identity-provider-overview.adoc[leveloffset=+1] - -[id="supported-identity-providers"] -== Supported identity providers - -You can configure the following types of identity providers: - -[cols="2a,8a",options="header"] -|=== - -|Identity provider -|Description - -|xref:../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#configuring-htpasswd-identity-provider[HTPasswd] -|Configure the `htpasswd` identity provider to validate user names and passwords -against a flat file generated using -link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. - -|xref:../authentication/identity_providers/configuring-keystone-identity-provider.adoc#configuring-keystone-identity-provider[Keystone] -|Configure the `keystone` identity provider to integrate -your {product-title} cluster with Keystone to enable shared authentication with -an OpenStack Keystone v3 server configured to store users in an internal -database. - -|xref:../authentication/identity_providers/configuring-ldap-identity-provider.adoc#configuring-ldap-identity-provider[LDAP] -|Configure the `ldap` identity provider to validate user names and passwords -against an LDAPv3 server, using simple bind authentication. - -|xref:../authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc#configuring-basic-authentication-identity-provider[Basic authentication] -|Configure a `basic-authentication` identity provider for users to log in to -{product-title} with credentials validated against a remote identity provider. -Basic authentication is a generic backend integration mechanism. - -|xref:../authentication/identity_providers/configuring-request-header-identity-provider.adoc#configuring-request-header-identity-provider[Request header] -|Configure a `request-header` identity provider to identify users from request -header values, such as `X-Remote-User`. It is typically used in combination with -an authenticating proxy, which sets the request header value. - -|xref:../authentication/identity_providers/configuring-github-identity-provider.adoc#configuring-github-identity-provider[GitHub or GitHub Enterprise] -|Configure a `github` identity provider to validate user names and passwords -against GitHub or GitHub Enterprise's OAuth authentication server. - -|xref:../authentication/identity_providers/configuring-gitlab-identity-provider.adoc#configuring-gitlab-identity-provider[GitLab] -|Configure a `gitlab` identity provider to use -link:https://gitlab.com/[GitLab.com] or any other GitLab instance as an identity -provider. - -|xref:../authentication/identity_providers/configuring-google-identity-provider.adoc#configuring-google-identity-provider[Google] -|Configure a `google` identity provider using -link:https://developers.google.com/identity/protocols/OpenIDConnect[Google's OpenID Connect integration]. - -|xref:../authentication/identity_providers/configuring-oidc-identity-provider.adoc#configuring-oidc-identity-provider[OpenID Connect] -|Configure an `oidc` identity provider to integrate with an OpenID Connect -identity provider using an -link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]. - -|=== - -Once an identity provider has been defined, you can -xref:../authentication/using-rbac.adoc#authorization-overview_using-rbac[use RBAC to define and apply permissions]. - -include::modules/authentication-remove-kubeadmin.adoc[leveloffset=+1] - -include::modules/identity-provider-parameters.adoc[leveloffset=+1] - -include::modules/identity-provider-default-CR.adoc[leveloffset=+1] diff --git a/authentication/using-rbac.adoc b/authentication/using-rbac.adoc deleted file mode 100644 index c312f4ff3368..000000000000 --- a/authentication/using-rbac.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="using-rbac"] -= Using RBAC to define and apply permissions -include::modules/common-attributes.adoc[] -:context: using-rbac - -toc::[] - -include::modules/rbac-overview.adoc[leveloffset=+1] - -include::modules/rbac-projects-namespaces.adoc[leveloffset=+1] - -include::modules/rbac-default-projects.adoc[leveloffset=+1] - -include::modules/rbac-viewing-cluster-roles.adoc[leveloffset=+1] - -include::modules/rbac-viewing-local-roles.adoc[leveloffset=+1] - -include::modules/rbac-adding-roles.adoc[leveloffset=+1] - -include::modules/rbac-creating-local-role.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/rbac-creating-cluster-role.adoc[leveloffset=+1] -endif::[] - -include::modules/rbac-local-role-binding-commands.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/rbac-cluster-role-binding-commands.adoc[leveloffset=+1] - -include::modules/rbac-creating-cluster-admin.adoc[leveloffset=+1] -endif::[] diff --git a/authentication/using-service-accounts-as-oauth-client.adoc b/authentication/using-service-accounts-as-oauth-client.adoc deleted file mode 100644 index 3c68594babc9..000000000000 --- a/authentication/using-service-accounts-as-oauth-client.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="using-service-accounts-as-oauth-client"] -= Using a service account as an OAuth client -include::modules/common-attributes.adoc[] -:context: using-service-accounts-as-oauth-client - -toc::[] - -include::modules/service-accounts-as-oauth-clients.adoc[leveloffset=+1] diff --git a/authentication/using-service-accounts-in-applications.adoc b/authentication/using-service-accounts-in-applications.adoc deleted file mode 100644 index 231e068d6402..000000000000 --- a/authentication/using-service-accounts-in-applications.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="using-service-accounts"] -= Using service accounts in applications -include::modules/common-attributes.adoc[] -:context: using-service-accounts - -toc::[] - -include::modules/service-accounts-overview.adoc[leveloffset=+1] - -include::modules/service-accounts-default.adoc[leveloffset=+1] - -include::modules/service-accounts-creating.adoc[leveloffset=+1] - -// include::modules/service-accounts-using-credentials-inside-a-container.adoc[leveloffset=+1] - -include::modules/service-accounts-using-credentials-externally.adoc[leveloffset=+1] diff --git a/autopreview.sh b/autopreview.sh index 9e1f083ba6f4..188aa5727c91 100644 --- a/autopreview.sh +++ b/autopreview.sh @@ -1,28 +1,68 @@ #!/bin/bash -set -ev -ALLOWED_USERS=("aireilly" "mburke5678" "vikram-redhat" "abrennan89" "ahardin-rh" "kalexand-rh" "adellape" "bmcelvee" "ousleyp" "lamek" "JStickler" "rh-max" "bergerhoffer" "sheriff-rh" "jboxman" "bobfuru" "aburdenthehand" "boczkowska" "Preeticp" "neal-timpe" "codyhoag" "apinnick" "bgaydosrh" "lmandavi" "maxwelldb" "pneedle-rh" "lbarbeevargas" "jeana-redhat" "RichardHoch" "johnwilkins" "sjhala-ccs" "mgarrellRH" "SNiemann15" "sfortner-RH" "jonquilwilliams" "ktania46" "wking" " -jc-berger" "rishumehra" "iranzo" "abhatt-rh" "@mohit-sheth" "stoobie" "emarcusRH" "kquinn1204" "mikemckiernan" "skrthomas" "sagidlow" "rolfedh") +set -e + +# Define colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + USERNAME=${TRAVIS_PULL_REQUEST_SLUG::-15} -COMMIT_HASH="$(git rev-parse @~)" -mapfile -t FILES_CHANGED < <(git diff --name-only "$COMMIT_HASH") - -if [ "$TRAVIS_PULL_REQUEST" != "false" ] ; then #to make sure it only runs on PRs and not all merges - if [[ " ${ALLOWED_USERS[*]} " =~ " ${USERNAME} " ]]; then # to make sure it only runs on PRs from @openshift/team-documentation - if [ "${TRAVIS_PULL_REQUEST_BRANCH}" != "master" ] ; then # to make sure it does not run for direct master changes - if [[ " ${FILES_CHANGED[*]} " = *".adoc"* ]] || [[ " ${FILES_CHANGED[*]} " = *"_topic_map.yml"* ]] || [[ " ${FILES_CHANGED[*]} " = *"_distro_map.yml"* ]] ; then # to make sure this doesn't run for general modifications - echo "{\"PR_BRANCH\":\"${TRAVIS_PULL_REQUEST_BRANCH}\",\"BASE_REPO\":\"${TRAVIS_REPO_SLUG}\",\"PR_NUMBER\":\"${TRAVIS_PULL_REQUEST}\",\"USER_NAME\":\"${USERNAME}\",\"BASE_REF\":\"${TRAVIS_BRANCH}\",\"REPO_NAME\":\"${TRAVIS_PULL_REQUEST_SLUG}\"}" > buildset.json - curl -H 'Content-Type: application/json' --request POST --data @buildset.json "https://roomy-tungsten-cylinder.glitch.me/" - echo -e "\\n\\033[0;32m[✓] Sent request for building a preview.\\033[0m" + +if [[ "$USERNAME" == "openshift-cherrypick-robot" ]]; then + echo -e "${YELLOW}🤖 PR by openshift-cherrypick-robot. Skipping the preview.${NC}" + exit 0 +fi + +if [[ "$TRAVIS_PULL_REQUEST" ]]; then + # Check if modified files meet the conditions + COMMIT_HASH="$(git rev-parse @~)" + modified_files=$(git diff --name-only "$COMMIT_HASH") + send_request=false + + for file in $modified_files; do + if [[ $file == *.adoc || $file == "_topic_map.yml" || $file == "_distro_map.yml" || $file == "_topic_maps/"* ]]; then + send_request=true + break + fi + done + + if [ "$send_request" = true ]; then + # Build the JSON + json_data=$( + cat </dev/null; then + echo -e "${RED}❌😔 Curl request failed: Invalid data!${NC}" + echo -e "${YELLOW}$json_data${NC}" + exit 1 else - echo -e "\\n\\033[1;33m[!] No .adoc files modified, not building a preview.\\033[0m" + echo -e "${GREEN}✅🥳 $response${NC}" fi else - echo -e "\\n\\033[1;33m[!] Direct PR for master branch, not building a preview.\\033[0m" + echo -e "${RED}❌😬 Curl request failed: $response${NC}" + echo -e "${YELLOW}$json_data${NC}" + exit 1 fi + + echo -e "${GREEN}🚀🎉 Request sent successfully!${NC}" else - echo -e "\\n\\033[1;33m[!] ${USERNAME} is not a team member of @openshift/team-documentation, not building a preview.\\033[0m" + echo -e "${YELLOW}⚠️🤔 No .adoc files, _topic_map.yml, or _distro_map.yml modified. Skipping the preview.${NC}" fi else - echo -e "\\n\\033[1;33m[!] Not a PR, not building a preview.\\033[0m" + echo -e "${YELLOW}❗🙅‍♀️ Not a Pull request. Skipping the preview.${NC}" fi diff --git a/backup_and_restore/backing-up-acs.adoc b/backup_and_restore/backing-up-acs.adoc new file mode 100644 index 000000000000..9c5e9d8c30e6 --- /dev/null +++ b/backup_and_restore/backing-up-acs.adoc @@ -0,0 +1,66 @@ +:_mod-docs-content-type: ASSEMBLY +[id="backing-up-acs"] += Backing up Red Hat Advanced Cluster Security for Kubernetes +include::modules/common-attributes.adoc[] +:context: backing-up-acs + +toc::[] + +[role="_abstract"] +You can perform data backups for {product-title} and use these for data restoration in case of an infrastructure disaster or corrupt data. + +You can configure automatic backups for the Central database by integrating with xref:../integration/integrate-with-amazon-s3.adoc#perform-on-demand-backups-amazon-s3_integrate-with-amazon-s3[Amazon S3], xref:../integration/integrate-with-s3-api-compatible-services.adoc#perform-on-demand-backups-s3-api-compatible-services_integrate-with-s3-api-compatible-services[S3 API compatible services], or xref:../integration/integrate-with-google-cloud-storage.adoc#perform-on-demand-backups-google-cloud-storage_integrate-with-google-cloud-storage[Google Cloud Storage]. +You can perform on-demand backups of the Central database by using the `roxctl` CLI. +You can also back up your Central deployment using {product-title-short} Operator or Helm Chart installation methods. + +Depending on your requirements, you can create two types of backups: + +. A backup of the Central database: It includes {product-title-short} configurations, resources, events, and certificates. +In an unforeseen incident, such as database failure or data corruption, you can use the backup to recover and restore the Central database to its earlier functional state. +Doing this ensures the availability and integrity of essential data, allowing you to continue normal operations without significant disruptions or loss of critical information. +. A backup of all custom deployment configurations: If you installed {product-title-short} by using Helm charts or the {product-title-short} Operator, you can back up settings, parameters, and customizations specific to your installation. +When the {product-title-short} installation gets accidentally deleted, or you need to migrate it to another cluster or namespace, having a backup of the deployment configurations enables a seamless recovery process. +In addition, by restoring the custom settings from the backup, you can efficiently reinstate your Central installation's unique requirements and configurations, ensuring consistent and exact deployment of the system. + +//Back up considerations for external databases and cloud users +include::modules/backup-considerations-for-external-databases-and-cloud-users.adoc[leveloffset=+1] + +//Backing up your PostgreSQL database and certificates +include::modules/backing-up-your-postgresql-database-and-certificates.adoc[leveloffset=+2] + +Because backup files include secrets and certificates, you must securely store the backup files. + +[id="backing-up-central-db-roxctl"] +== Backing up Central database by using the roxctl CLI +Backing up the Central database is critical to ensure data integrity and system reliability. Regular backups of the database, containing necessary configurations, resources, events, and certificates, protect against database failures, corruption, and accidental data loss. + +You can use the `roxctl` CLI to take the backups by using the `backup` command. You require an API token or your administrator password to run this command. + +[NOTE] +==== +Red Hat supports backups for the Central database through integration with xref:../integration/integrate-with-amazon-s3.adoc#perform-on-demand-backups-amazon-s3_integrate-with-amazon-s3[Amazon S3] or xref:../integration/integrate-with-google-cloud-storage.adoc#perform-on-demand-backups-google-cloud-storage_integrate-with-google-cloud-storage[Google Cloud Storage]. + +Backing up to xref:../integration/integrate-with-s3-api-compatible-services.adoc#integrate-with-s3-api-compatible-services[S3 API compatible] storage is not guaranteed to work. Red Hat does not test and support every S3 API compatible provider for backing up {product-title-short}. +==== + +include::modules/on-demand-backups-roxctl-api.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage-user-access/manage-role-based-access-control-3630.adoc#rbac-system-roles-3630_manage-role-based-access-control[System roles] + +include::modules/on-demand-backups-roxctl-admin-pass.adoc[leveloffset=+2] + +[id="backing-up-central-deployment"] +== Backing up Central deployment +You can back up the deployment of a Central instance. +This can be useful if you want to migrate central to another namespace or cluster by using the same configuration values. + +[NOTE] +==== +Red{nbsp}Hat does not support backing up deployment configurations by using the `roxctl` CLI. You can use the `oc` or `kubectl` CLI to back up manifests related to your Central instance and restore the configuration. +==== + +include::modules/backup-deployment-config-operator.adoc[leveloffset=+2] + +include::modules/backup-deployment-config-helm.adoc[leveloffset=+2] \ No newline at end of file diff --git a/backup_and_restore/backing-up-etcd.adoc b/backup_and_restore/backing-up-etcd.adoc deleted file mode 100644 index 90d5a5e93655..000000000000 --- a/backup_and_restore/backing-up-etcd.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="backup-etcd"] -= Backing up etcd -include::modules/common-attributes.adoc[] -:context: backup-etcd - -toc::[] - -etcd is the key-value store for {product-title}, which persists the state of all -resource objects. - -Back up your cluster's etcd data regularly and store in a secure location -ideally outside the {product-title} environment. Do not take an etcd backup -before the first certificate rotation completes, which occurs 24 hours after -installation, otherwise the backup will contain expired certificates. It is also -recommended to take etcd backups during non-peak usage hours, as it is a -blocking action. - -Be sure to take an etcd backup after you upgrade your cluster. This is important because when you restore your cluster, you must use an etcd backup that was taken from the same z-stream release. For example, an {product-title} 4.7.2 cluster must use an etcd backup that was taken from 4.7.2. - -[IMPORTANT] -==== -Back up your cluster's etcd data by performing a single invocation of the backup script on a master host. Do not take a backup for each master host. -==== - -After you have an etcd backup, you can xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore to a previous cluster state]. - -You can perform the xref:../backup_and_restore/backing-up-etcd.adoc#backing-up-etcd-data_backup-etcd[etcd data backup process] -on any master host that has a running etcd instance. - -// Backing up etcd data -include::modules/backup-etcd.adoc[leveloffset=+1] diff --git a/backup_and_restore/disaster_recovery/about-disaster-recovery.adoc b/backup_and_restore/disaster_recovery/about-disaster-recovery.adoc deleted file mode 100644 index b290246b90be..000000000000 --- a/backup_and_restore/disaster_recovery/about-disaster-recovery.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="about-dr"] -= About disaster recovery -include::modules/common-attributes.adoc[] -:context: about-dr - -toc::[] - -The disaster recovery documentation provides information for administrators on -how to recover from several disaster situations that might occur with their -{product-title} cluster. As an administrator, you might need to follow one or -more of the following procedures to return your cluster to a working -state. - -xref:../../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[Restoring to a previous cluster state]:: -This solution handles situations where you want to restore your cluster to -a previous state, for example, if an administrator deletes something critical. -This also includes situations where you have lost the majority of your master hosts, leading to etcd quorum loss and the cluster going offline. As long as you have taken an etcd backup, you can follow this procedure to restore your cluster to a previous state. -+ -If applicable, you might also need to xref:../../backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc#dr-recovering-expired-certs[recover from expired control plane certificates]. -+ -[NOTE] -==== -If you have a majority of your masters still available and have an etcd quorum, then follow the procedure to xref:../../backup_and_restore/replacing-unhealthy-etcd-member.adoc#replacing-unhealthy-etcd-member[replace a single unhealthy etcd member]. -==== - -xref:../../backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc#dr-recovering-expired-certs[Recovering from expired control plane certificates]:: -This solution handles situations where your control plane certificates have -expired. For example, if you shut down your cluster before the first certificate -rotation, which occurs 24 hours after installation, your certificates will not -be rotated and will expire. You can follow this procedure to recover from -expired control plane certificates. diff --git a/backup_and_restore/disaster_recovery/images b/backup_and_restore/disaster_recovery/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/backup_and_restore/disaster_recovery/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/backup_and_restore/disaster_recovery/modules b/backup_and_restore/disaster_recovery/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/backup_and_restore/disaster_recovery/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc b/backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc deleted file mode 100644 index 6ad134bfe426..000000000000 --- a/backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="dr-restoring-cluster-state"] -= Restoring to a previous cluster state -include::modules/common-attributes.adoc[] -:context: dr-restoring-cluster-state - -toc::[] - -To restore the cluster to a previous state, you must have previously xref:../../backup_and_restore/backing-up-etcd.adoc#backing-up-etcd-data_backup-etcd[backed up etcd data] by creating a snapshot. You will use this snapshot to restore the cluster state. - -// Restoring to a previous cluster state -include::modules/dr-restoring-cluster-state.adoc[leveloffset=+1] diff --git a/backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc b/backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc deleted file mode 100644 index 9910dbe7d4c5..000000000000 --- a/backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="dr-recovering-expired-certs"] -= Recovering from expired control plane certificates -include::modules/common-attributes.adoc[] -:context: dr-recovering-expired-certs - -toc::[] - -// Recovering from expired control plane certificates -include::modules/dr-recover-expired-control-plane-certs.adoc[leveloffset=+1] diff --git a/backup_and_restore/graceful-cluster-restart.adoc b/backup_and_restore/graceful-cluster-restart.adoc deleted file mode 100644 index 11f0322f098d..000000000000 --- a/backup_and_restore/graceful-cluster-restart.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="graceful-restart-cluster"] -= Restarting the cluster gracefully -include::modules/common-attributes.adoc[] -:context: graceful-restart-cluster - -toc::[] - -This document describes the process to restart your cluster after a graceful shutdown. - -Even though the cluster is expected to be functional after the restart, the cluster might not recover due to unexpected conditions, for example: - -* etcd data corruption during shutdown -* Node failure due to hardware -* Network connectivity issues - -If your cluster fails to recover, follow the steps to xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore to a previous cluster state]. - -== Prerequisites - -* You have xref:../backup_and_restore/graceful-cluster-shutdown.adoc#graceful-shutdown-cluster[gracefully shut down your cluster]. - -// Restarting the cluster -include::modules/graceful-restart.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[Restoring to a previous cluster state] for how to use an etcd backup to restore if your cluster failed to recover after restarting. diff --git a/backup_and_restore/graceful-cluster-shutdown.adoc b/backup_and_restore/graceful-cluster-shutdown.adoc deleted file mode 100644 index 06952895a098..000000000000 --- a/backup_and_restore/graceful-cluster-shutdown.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="graceful-shutdown-cluster"] -= Shutting down the cluster gracefully -include::modules/common-attributes.adoc[] -:context: graceful-shutdown-cluster - -toc::[] - -This document describes the process to gracefully shut down your cluster. You might need to temporarily shut down your cluster for maintenance reasons, or to save on resource costs. - -== Prerequisites - -* Take an xref:../backup_and_restore/backing-up-etcd.adoc#backing-up-etcd-data_backup-etcd[etcd backup] prior to shutting down the cluster. - -// Shutting down the cluster -include::modules/graceful-shutdown.adoc[leveloffset=+1] - -.Additional resources - -* xref:../backup_and_restore/graceful-cluster-restart.adoc#graceful-restart-cluster[Restarting the cluster gracefully] diff --git a/backup_and_restore/replacing-unhealthy-etcd-member.adoc b/backup_and_restore/replacing-unhealthy-etcd-member.adoc deleted file mode 100644 index 954660445070..000000000000 --- a/backup_and_restore/replacing-unhealthy-etcd-member.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="replacing-unhealthy-etcd-member"] -= Replacing an unhealthy etcd member -include::modules/common-attributes.adoc[] -:context: replacing-unhealthy-etcd-member - -toc::[] - -This document describes the process to replace a single unhealthy etcd member. - -This process depends on whether the etcd member is unhealthy because the machine is not running or the node is not ready, or whether it is unhealthy because the etcd pod is crashlooping. - -[NOTE] -==== -If you have lost the majority of your master hosts, leading to etcd quorum loss, then you must follow the disaster recovery procedure to xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore to a previous cluster state] instead of this procedure. - -If the control plane certificates are not valid on the member being replaced, then you must follow the procedure to xref:../backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc#dr-recovering-expired-certs[recover from expired control plane certificates] instead of this procedure. - -If a master node is lost and a new one is created, the etcd cluster Operator handles generating the new TLS certificates and adding the node as an etcd member. -==== - -== Prerequisites - -* Take an xref:../backup_and_restore/backing-up-etcd.adoc#backing-up-etcd-data_backup-etcd[etcd backup] prior to replacing an unhealthy etcd member. - -// Identifying an unhealthy etcd member -include::modules/restore-identify-unhealthy-etcd-member.adoc[leveloffset=+1] - -// Determining the state of the unhealthy etcd member -include::modules/restore-determine-state-etcd-member.adoc[leveloffset=+1] - -== Replacing the unhealthy etcd member - -Depending on the state of your unhealthy etcd member, use one of the following procedures: - -* xref:../backup_and_restore/replacing-unhealthy-etcd-member.adoc#restore-replace-stopped-etcd-member_replacing-unhealthy-etcd-member[Replacing an unhealthy etcd member whose machine is not running or whose node is not ready] -* xref:../backup_and_restore/replacing-unhealthy-etcd-member.adoc#restore-replace-crashlooping-etcd-member_replacing-unhealthy-etcd-member[Replacing an unhealthy etcd member whose etcd pod is crashlooping] - -// Replacing an unhealthy etcd member whose machine is not running or whose node is not ready -include::modules/restore-replace-stopped-etcd-member.adoc[leveloffset=+2] - -// Replacing an unhealthy etcd member whose etcd pod is crashlooping -include::modules/restore-replace-crashlooping-etcd-member.adoc[leveloffset=+2] diff --git a/backup_and_restore/restore-acs.adoc b/backup_and_restore/restore-acs.adoc new file mode 100644 index 000000000000..d389d67fbd84 --- /dev/null +++ b/backup_and_restore/restore-acs.adoc @@ -0,0 +1,73 @@ +:_mod-docs-content-type: ASSEMBLY +[id="restore-acs"] += Restoring from a backup +include::modules/common-attributes.adoc[] +:context: restore-acs + +toc::[] + +[role="_abstract"] +You can restore {rh-rhacs-first} from an existing backup by using the `roxctl` command-line interface (CLI). + +Depending upon your requirements and the data you have backed up, you can restore from the following types of backups: + +. *Restore an external PostgreSQL database*: Use this to restore your {product-title-short} instance when you use an external PostgreSQL database. You can recover your system data while maintaining your existing database setup. + +. *Restore the Central certificates and redeploy Central*: Use this to restore the Central certificates and redeploy Central after a database restoration. This ensures that authentication certificates for secured clusters and API tokens remain valid. + +. *Restore Central database from the Central database backup*: Use this to recover from a database failure or data corruption event. You can restore and recover the Central database to its earlier functional state. + +. *Restore Central from the Central deployment backup*: Use this if you are migrating Central to another cluster or namespace. This option restores the configurations of your Central installation. + +//Restoring an external PostgreSQL database +include::modules/restoring-an-external-postgresql-database.adoc[leveloffset=+1] + +//Restoring the Central certificates and redeploying Central +include::modules/restoring-central-certificates-and-redeploying-central.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../backup_and_restore/restore-acs.adoc#restore-cert-roxctl_restore-acs[Restore certificates using the roxctl CLI] + +[id="restore-central-db-roxctl"] +== Restoring Central database by using the roxctl CLI +You can use the `roxctl` CLI to restore {product-title} by using the `restore` command. You require an API token or your administrator password to run this command. + +include::modules/restore-acs-roxctl-api.adoc[leveloffset=+2] + +include::modules/restore-acs-roxctl-admin-pass.adoc[leveloffset=+2] + +include::modules/resume-acs-restore.adoc[leveloffset=+2] + +[id="restore-central-deployment-roxctl"] +== Restoring Central deployment using the roxctl CLI +You can restore your Central deployment to its original configuration by using the backups you made. + +You must first restore certificates by using the `roxctl` CLI, and then restore the Central deployment by running the Central installation scripts. + +include::modules/restore-cert-roxctl.adoc[leveloffset=+2] +include::modules/install-central-roxctl.adoc[leveloffset=+2] + +include::modules/restore-deployment-config-operator.adoc[leveloffset=+1] + +include::modules/restore-deployment-config-helm.adoc[leveloffset=+1] + +[id="restore-central-another-cluster"] +== Restoring central to another cluster or namespace +You can use the backups of the {product-title-short} Central database and the deployment to restore Central to another cluster or namespace. + +The following list provides a high-level overview of installation steps: + +. Depending upon your installation method, you must first restore Central deployment by following the instructions in the following topics: ++ +[IMPORTANT] +==== +* Make sure to use the backed-up Central certificates so that secured clusters and API tokens issued by the old Central instance remain valid. +* If you are deploying to another namespace, you must change the namespace in backed-up resources or commands. +==== + +** xref:../backup_and_restore/restore-acs.adoc#restore-central-deployment-roxctl[Restoring Central deployment using the `roxctl` CLI] +** xref:../backup_and_restore/restore-acs.adoc#restore-deployment-config-operator_restore-acs[Restore Central deployment using the {product-title-short} Operator] +** xref:../backup_and_restore/restore-acs.adoc#restore-deployment-config-helm_restore-acs[Restore Central deployment using Helm] +. Restore Central database by following the instruction in the xref:../backup_and_restore/restore-acs.adoc#restore-central-db-roxctl[Restoring Central database by using the roxctl CLI] topic. +. If you have an external DNS entry pointing to your old {product-title-short} Central instance, you must reconfigure it to point to the new {product-title-short} Central instance that you create. \ No newline at end of file diff --git a/backup_and_restore/snippets b/backup_and_restore/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/backup_and_restore/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/build.py b/build.py index c11daf2cf6cc..e6b46f8442d4 100755 --- a/build.py +++ b/build.py @@ -22,6 +22,7 @@ import time import yaml import requests +import tempfile from aura import cli @@ -151,9 +152,25 @@ def find_build_config_file(): """ Finds the build config file to use, as it might be _topic_map.yml or _build_cfg.yml """ - config = os.path.abspath(os.path.join(CLONE_DIR, "_topic_map.yml")) + + # updated 23rd Nov to support files in _topic_maps folder + + # load everything from the _topic_maps folder + file_list = os.listdir(os.path.join(CLONE_DIR, "_topic_maps")) + + # create a temp file combining all values from that folder + # don't delete it immediately, and give it a suffix of swp which makes it ignored by git + with tempfile.NamedTemporaryFile(dir=CLONE_DIR, delete=False, suffix=".swp") as tmp: + for f in file_list: + with open(os.path.join(CLONE_DIR, "_topic_maps", f), "rb") as infile: + tmp.write(infile.read()) + + config = os.path.abspath(tmp.name) + log.info(config) + + # backup look for a single _topic_map in the cloned directory if not os.path.isfile(config): - config = os.path.abspath(os.path.join(CLONE_DIR, "_build_cfg.yml")) + config = os.path.abspath(os.path.join(CLONE_DIR, "_topic_map.yml")) return config @@ -164,7 +181,7 @@ def parse_build_config(config): """ config = os.path.expanduser(config) with open(config, "r") as f: - data = list(yaml.load_all(f)) + data = list(yaml.load_all(f,Loader=yaml.FullLoader)) for book in data: book_name = book['Name'] diff --git a/build_for_portal.py b/build_for_portal.py index e86962563ead..357bff6388ad 100644 --- a/build_for_portal.py +++ b/build_for_portal.py @@ -6,35 +6,47 @@ import configparser import filecmp import fnmatch -import logging import os import re import shutil import subprocess import sys +import tempfile import time -import yaml import requests +import yaml +import logging + +# See manual and pip3 install aura.tar.gz for logging from aura import cli cli.init_logging(False, True) -has_errors = False +list_of_errors = [] CLONE_DIR = "." -BASE_PORTAL_URL = "https://access.redhat.com/documentation/en-us/" +BASE_PORTAL_URL = "https://docs.redhat.com/en/documentation/" # ID_RE = re.compile("^\[(?:\[|id=\'|#)(.*?)(\'?,.*?)?(?:\]|\')?\]", re.M | re.DOTALL) -ID_RE = re.compile("^\[(?:\[|id=\'|#|id=\")(.*?)(\'?,.*?)?(?:\]|\'|\")?\]", re.M | re.DOTALL) -LINKS_RE = re.compile("(?:xref|link):([\./\w_-]*/?[\w_.-]*\.(?:html|adoc))?(#[\w_-]*)?(\[.*?\])", re.M | re.DOTALL) -EXTERNAL_LINK_RE = re.compile("[\./]*([\w_-]+)/[\w_/-]*?([\w_.-]*\.(?:html|adoc))", re.DOTALL) -INCLUDE_RE = re.compile("include::(.*?)\[(.*?)\]", re.M) +ID_RE = re.compile( + "^\[(?:\[|id='|#|id=\")(.*?)('?,.*?)?(?:\]|'|\")?\]", re.M | re.DOTALL +) +LINKS_RE = re.compile( + "(?:xref|link):([\./\w_-]*/?[\w_.-]*\.(?:html|adoc))?(#[\w_-]*)?(\[.*?\])", + re.M | re.DOTALL, +) +EXTERNAL_LINK_RE = re.compile( + "[\./]*([\w_-]+)/[\w_/-]*?([\w_.-]*\.(?:html|adoc))", re.DOTALL +) +INCLUDE_RE = re.compile(r"^include::(.*?)\[(.*?)\]", re.M) IFDEF_RE = re.compile(r"^if(n?)def::(.*?)\[\]", re.M) ENDIF_RE = re.compile(r"^endif::(.*?)\[\]\r?\n", re.M) COMMENT_CONTENT_RE = re.compile(r"^^////$.*?^////$", re.M | re.DOTALL) -TAG_CONTENT_RE = re.compile(r"//\s+tag::(.*?)\[\].*?// end::(.*?)\[\]", re.M | re.DOTALL) +COMMENTED_XREF_RE = re.compile(r"^//.*xref:.*$") +TAG_CONTENT_RE = re.compile( + r"//\s+tag::(.*?)\[\].*?// end::(.*?)\[\]", re.M | re.DOTALL +) CMP_IGNORE_FILES = [".git", ".gitignore", "README.md", "build.cfg"] -DEVNULL = open(os.devnull, 'wb') - +DEVNULL = open(os.devnull, "wb") MASTER_FILE_BASE = "= {title}\n\ :product-author: {product-author}\n\ @@ -45,17 +57,17 @@ :idseparator: -\n\ {preface-title}\n" -DOCINFO_BASE = "{title}\n\ +DOCINFO_BASE = '{title}\n\ {{product-title}}\n\ {{product-version}}\n\ Enter a short description here.\n\ \n\ - A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long.\n\ + A short overview and summary of the book\'s subject and purpose, traditionally no more than one paragraph long.\n\ \n\ \n\ {product-author}\n\ \n\ -\n" +\n' # A list of book titles, that still use the old drupal url format (ie includes the product/version in the book title part) # eg. openshift-enterprise/version-3.0/openshift-enterprise-30-getting-started vs openshift-enterprise/version-3.0/getting-started @@ -68,13 +80,11 @@ "Getting Started", "REST API Reference", "Using Images", - "What's New?" + "What's New?", ] # A mapping of upstream book/category names to CP book names -BOOK_NAME_OVERRIDES = { - "Administration": "Administrator Guide" -} +BOOK_NAME_OVERRIDES = {"Administration": "Administrator Guide"} # Lines that should be stripped out/ignored when cleaning the content IGNORE_LINES = [ @@ -82,24 +92,15 @@ "{product-version}\n", "{product-version]\n", "{Lucas Costi}\n", - "toc::[]\n" + "toc::[]\n", ] # Each MACRO in this list is omitted from the output # if the input appears as ':MACRO:' (colon, MACRO, colon). -IGNORE_MACROS = [ - "description", - "keywords", - "icons", - "data-uri", - "toc", - "toc-title" -] +IGNORE_MACROS = ["description", "keywords", "icons", "data-uri", "toc", "toc-title"] # Files where the title should be removed when building the all-in-one -ALL_IN_ONE_SCRAP_TITLE = [ - "welcome/index.adoc" -] +ALL_IN_ONE_SCRAP_TITLE = ["welcome/index.adoc"] # Files that should be commented out in the toc structure COMMENT_FILES = [ @@ -107,7 +108,7 @@ "creating_images/overview.adoc", "dev_guide/overview.adoc", "using_images/overview.adoc", - "rest_api/overview.adoc" + "rest_api/overview.adoc", ] # Map FILENAME to a map of TITLE to ID. In most of the cases the @@ -124,19 +125,44 @@ def setup_parser(): - parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter) - parser.add_argument("--distro", help="The distribution to build for", default="openshift-enterprise") + parser = argparse.ArgumentParser( + formatter_class=argparse.ArgumentDefaultsHelpFormatter + ) + parser.add_argument( + "--distro", help="The distribution to build for", default="openshift-enterprise" + ) parser.add_argument("--all-in-one", help=argparse.SUPPRESS, action="https://github.com/store_true") parser.add_argument("--title", help=argparse.SUPPRESS, default="Documentation") parser.add_argument("--product", default="OpenShift Enterprise") parser.add_argument("--version", default="3.0") parser.add_argument("--author", default="Red Hat OpenShift Documentation Team") - parser.add_argument("--upstream-url", help="The upstream source url", default="https://github.com/openshift/openshift-docs.git") - parser.add_argument("--upstream-branch", help="The upstream source branch", default="enterprise-3.0") - parser.add_argument("--branch", help="The GitLab branch to commit changes into", default="GA") - parser.add_argument("-p", "--push", help="Commit and push the changes into GitLab", action="https://github.com/store_true") - parser.add_argument("--no-clean", help="Don't clean the drupal-build directory before building", action="https://github.com/store_true") - parser.add_argument("--no-upstream-fetch", help="Don't fetch the upstream sources", action="https://github.com/store_true") + parser.add_argument( + "--upstream-url", + help="The upstream source url", + default="https://github.com/openshift/openshift-docs.git", + ) + parser.add_argument( + "--upstream-branch", help="The upstream source branch", default="enterprise-3.0" + ) + parser.add_argument( + "--branch", help="The GitLab branch to commit changes into", default="GA" + ) + parser.add_argument( + "-p", + "--push", + help="Commit and push the changes into GitLab", + action="https://github.com/store_true", + ) + parser.add_argument( + "--no-clean", + help="Don't clean the drupal-build directory before building", + action="https://github.com/store_true", + ) + parser.add_argument( + "--no-upstream-fetch", + help="Don't fetch the upstream sources", + action="https://github.com/store_true", + ) return parser @@ -144,9 +170,25 @@ def find_build_config_file(): """ Finds the build config file to use, as it might be _topic_map.yml or _build_cfg.yml """ - config = os.path.abspath(os.path.join(CLONE_DIR, "_topic_map.yml")) + + # updated 23rd Nov to support files in _topic_maps folder + + # load everything from the _topic_maps folder + file_list = os.listdir(os.path.join(CLONE_DIR, "_topic_maps")) + + # create a temp file combining all values from that folder + # don't delete it immediately, and give it a suffix of swp which makes it ignored by git + with tempfile.NamedTemporaryFile(dir=CLONE_DIR, delete=False, suffix=".swp") as tmp: + for f in file_list: + with open(os.path.join(CLONE_DIR, "_topic_maps", f), "rb") as infile: + tmp.write(infile.read()) + + config = os.path.abspath(tmp.name) + log.info(config) + + # backup look for a single _topic_map in the cloned directory if not os.path.isfile(config): - config = os.path.abspath(os.path.join(CLONE_DIR, "_build_cfg.yml")) + config = os.path.abspath(os.path.join(CLONE_DIR, "_topic_map.yml")) return config @@ -157,20 +199,28 @@ def parse_build_config(config): """ config = os.path.expanduser(config) with open(config, "r") as f: - data = list(yaml.load_all(f)) + data = list(yaml.load_all(f, Loader=yaml.FullLoader)) for book in data: - book_name = book['Name'] + book_name = book["Name"] if book_name in BOOK_NAME_OVERRIDES: - book['Name'] = BOOK_NAME_OVERRIDES[book_name] + book["Name"] = BOOK_NAME_OVERRIDES[book_name] return data -def iter_tree(node, distro, dir_callback=None, topic_callback=None, include_path=True, parent_dir="", depth=0): +def iter_tree( + node, + distro, + dir_callback=None, + topic_callback=None, + include_path=True, + parent_dir="", + depth=0, +): """ - Iterates over a build config tree starting from a specifc node, skipping content where the distro doesn't match. Additionally calls are - made to the dir_callback or topic_callback functions when a directory or topic is found. + Iterates over a build config tree starting from a specific node, skipping content where the distro doesn't match. + Additionally, calls are made to the dir_callback or topic_callback functions when a directory or topic is found. """ if "Topics" in node: if check_node_distro_matches(node, distro): @@ -183,7 +233,15 @@ def iter_tree(node, distro, dir_callback=None, topic_callback=None, include_path dir_callback(node, parent_dir, depth) for topic in node["Topics"]: - iter_tree(topic, distro, dir_callback, topic_callback, True, topics_dir, depth + 1) + iter_tree( + topic, + distro, + dir_callback, + topic_callback, + True, + topics_dir, + depth + 1, + ) elif check_node_distro_matches(node, distro): if topic_callback is not None: topic_callback(node, parent_dir, depth) @@ -197,7 +255,7 @@ def check_node_distro_matches(node, distro): if "Distros" not in node: return True else: - node_distros = [x.strip() for x in node['Distros'].split(",")] + node_distros = [x.strip() for x in node["Distros"].split(",")] for node_distro in node_distros: # Check for an exact match, or a glob match if node_distro == distro or fnmatch.fnmatchcase(distro, node_distro): @@ -211,30 +269,69 @@ def ensure_directory(directory): Creates DIRECTORY if it does not exist. """ if not os.path.exists(directory): - os.mkdir(directory) + os.makedirs(directory) + +def expand_huge_books(info): + """ + Finds nodes for huge books, creates new nodes for books from their top-level topics, + and then removes the nodes for huge books + """ + + # find all the huge books, sa defined by nodes + huge_book_nodes = [book for book in info["book_nodes"] + if os.path.exists(os.path.join(info["src_dir"],book["Dir"],"hugeBook.flag")) ] + + + for book in huge_book_nodes: + # save the directory in info + huge_book_dir = book["Dir"] + info["huge_book_dirs"].append(huge_book_dir) + # create the flag file in the book destination directory + book_dest_dir = os.path.join(info["dest_dir"], book["Dir"]) + ensure_directory(book_dest_dir) + with open(os.path.join(book_dest_dir,"hugeBook.flag"),"w") as fi: + fi.write("hugebook") + # make new book nodes for the second-level headings + for topic in book["Topics"]: + if "Dir" in topic.keys(): + info["book_nodes"].append(topic) + topic["Dir"] = huge_book_dir + "/" + topic["Dir"] + + # remove book nodes for huge books + for node_to_remove in huge_book_nodes: + info["book_nodes"].remove(node_to_remove) def build_master_files(info): """ Builds the master.adoc and docinfo.xml files for each guide specified in the config. """ - dest_dir = info['dest_dir'] - all_in_one = info['all_in_one'] + # change the huge books into sub-books + expand_huge_books(info) + + # TODO: Refactor. This does too much. + + dest_dir = info["dest_dir"] + all_in_one = info["all_in_one"] all_in_one_text = "" - for book in info['book_nodes']: - book_dest_dir = os.path.join(dest_dir, book['Dir']) + + for book in info["book_nodes"]: + + book_dest_dir = os.path.join(dest_dir, book["Dir"]) ensure_directory(book_dest_dir) book_info = dict(info) - book_info['title'] = book['Name'] + book_info["title"] = book["Name"] - master = generate_master_entry(book, book['Dir'], info['distro'], all_in_one, all_in_one=all_in_one) + master: str = generate_master_entry( + book, book["Dir"], info["distro"], all_in_one, all_in_one=all_in_one + ) # Save the content if not all_in_one: - master_file = os.path.join(book_dest_dir, 'master.adoc') - docinfo_file = os.path.join(book_dest_dir, 'docinfo.xml') + master_file = os.path.join(book_dest_dir, "master.adoc") + docinfo_file = os.path.join(book_dest_dir, "docinfo.xml") master_base = MASTER_FILE_BASE.format(**book_info) log.debug("Writing " + master_file) @@ -244,12 +341,15 @@ def build_master_files(info): with open(docinfo_file, "w") as f: f.write(DOCINFO_BASE.format(**book_info)) else: + # TODO: Do we ever use this? if all_in_one_text == "": # Remove the title for the first file in the book - master = master.replace("= " + book['Name'] + "\n", "") + master = master.replace("= " + book["Name"] + "\n", "") # Set the preface title from the first file in the book - first_file = os.path.join(info['src_dir'], book['Dir'], book['Topics'][0]['File'] + ".adoc") + first_file = os.path.join( + info["src_dir"], book["Dir"], book["Topics"][0]["File"] + ".adoc" + ) preface_title = None with open(first_file, "r") as f: line = f.readline() @@ -259,12 +359,13 @@ def build_master_files(info): break line = f.readline() if preface_title is not None: - info['preface-title'] = ":preface-title: " + preface_title + info["preface-title"] = ":preface-title: " + preface_title all_in_one_text += master + # TODO: And is this ever used? if all_in_one: - master_file = os.path.join(dest_dir, 'master.adoc') - docinfo_file = os.path.join(dest_dir, 'docinfo.xml') + master_file = os.path.join(dest_dir, "master.adoc") + docinfo_file = os.path.join(dest_dir, "docinfo.xml") master_base = MASTER_FILE_BASE.format(**info) @@ -276,15 +377,19 @@ def build_master_files(info): f.write(DOCINFO_BASE.format(**info)) -def generate_master_entry(node, book_dir, distro, include_name=True, all_in_one=False): +def generate_master_entry( + node: dict, book_dir: str, distro: str, include_name=True, all_in_one=False +): """ - Generates the master.adoc core content for a specific book/node. + Given a node (book dict), generate content for that node's master.adoc file. """ master_entries = [] def dir_callback(dir_node, parent_dir, depth): - if include_name or depth > 0: - master_entries.append("=" * (depth + 1) + " " + dir_node["Name"].replace("\\", "")) + if include_name or depth > 0: + master_entries.append( + "=" * (depth + 1) + " " + dir_node["Name"].replace("\\", "") + ) def topic_callback(topic_node, parent_dir, depth): book_file_path = os.path.join(parent_dir, topic_node["File"] + ".adoc") @@ -316,15 +421,15 @@ def reformat_for_drupal(info): - Fixes duplicate id's in the source content. - Fixes links that have been done incorrectly and should be cross references instead. """ - books = info['book_nodes'] - src_dir = info['src_dir'] - dest_dir = info['dest_dir'] - distro = info['distro'] + books = info["book_nodes"] + src_dir = info["src_dir"] + dest_dir = info["dest_dir"] + distro = info["distro"] # Build a mapping of files to ids # Note: For all-in-one we have to collect ids from all books first file_to_id_map = {} - if info['all_in_one']: + if info["all_in_one"]: book_ids = [] for book in books: book_ids.extend(collect_existing_ids(book, distro, src_dir)) @@ -334,34 +439,37 @@ def reformat_for_drupal(info): for book in books: book_ids = collect_existing_ids(book, distro, src_dir) file_to_id_map.update(build_file_to_id_map(book, distro, book_ids, src_dir)) - info['file_to_id_map'] = file_to_id_map + info["file_to_id_map"] = file_to_id_map # Reformat the data for book in books: - log.info("Processing %s", book['Dir']) - book_src_dir = os.path.join(src_dir, book['Dir']) - if info['all_in_one']: + log.info("Processing %s", book["Dir"]) + book_src_dir = os.path.join(src_dir, book["Dir"]) + + if info["all_in_one"]: images_dir = os.path.join(dest_dir, "images") else: - book_dest_dir = os.path.join(dest_dir, book['Dir']) + book_dest_dir = os.path.join(dest_dir, book["Dir"]) images_dir = os.path.join(book_dest_dir, "images") ensure_directory(images_dir) - log.debug("Copying source files for " + book['Name']) + log.debug("Copying source files for " + book["Name"]) copy_files(book, book_src_dir, src_dir, dest_dir, info) - log.debug("Copying images for " + book['Name']) + log.debug("Copying images for " + book["Name"]) copy_images(book, src_dir, images_dir, distro) + def copy_images(node, src_path, dest_dir, distro): """ Copy images over to the destination directory and flatten all image directories into the one top level dir. """ + def dir_callback(dir_node, parent_dir, depth): - node_dir = os.path.join(parent_dir, dir_node['Dir']) + node_dir = os.path.join(parent_dir, dir_node["Dir"]) src = os.path.join(node_dir, "images") if os.path.exists(src): @@ -377,8 +485,9 @@ def copy_files(node, book_src_dir, src_dir, dest_dir, info): Recursively copy files from the source directory to the destination directory, making sure to scrub the content, add id's where the content is referenced elsewhere and fix any links that should be cross references. """ + def dir_callback(dir_node, parent_dir, depth): - node_dest_dir = os.path.join(dest_dir, parent_dir, dir_node['Dir']) + node_dest_dir = os.path.join(dest_dir, parent_dir, dir_node["Dir"]) ensure_directory(node_dest_dir) def topic_callback(topic_node, parent_dir, depth): @@ -391,14 +500,24 @@ def topic_callback(topic_node, parent_dir, depth): # Copy the file copy_file(info, book_src_dir, src_file, dest_dir, dest_file) - iter_tree(node, info['distro'], dir_callback, topic_callback) + iter_tree(node, info["distro"], dir_callback, topic_callback) -def copy_file(info, book_src_dir, src_file, dest_dir, dest_file, include_check=True, tag=None, cwd=None): +def copy_file( + info, + book_src_dir, + src_file, + dest_dir, + dest_file, + include_check=True, + tag=None, + cwd=None, +): """ Copies a source file to destination, making sure to scrub the content, add id's where the content is referenced elsewhere and fix any links that should be cross references. Also copies any includes that are referenced, since they aren't included in _build_cfg.yml. """ + # It's possible that the file might have been created by another include, if so then just return if os.path.isfile(dest_file): return @@ -407,8 +526,8 @@ def copy_file(info, book_src_dir, src_file, dest_dir, dest_file, include_check=T parent_dir = os.path.dirname(dest_file) if not os.path.exists(parent_dir): os.makedirs(parent_dir) - #os.mknod(dest_file) - open(dest_file, 'w').close() + # os.mknod(dest_file) + open(dest_file, "w").close() # Scrub/fix the content content = scrub_file(info, book_src_dir, src_file, tag=tag, cwd=cwd) @@ -428,19 +547,30 @@ def copy_file(info, book_src_dir, src_file, dest_dir, dest_file, include_check=T key, value = re.split("\s*=\s*", meta, 2) include_vars[key] = value + # Determine the include src/dest paths include_file = os.path.join(os.path.dirname(book_src_dir), include_path) relative_path = os.path.relpath(include_file, os.path.dirname(src_file)) # If the path is in another book, copy it into this one relative_book_path = os.path.relpath(include_file, book_src_dir) + if relative_book_path.startswith("../"): - path, src_book_name = os.path.split(book_src_dir) - dest_include_dir = os.path.join(dest_dir, src_book_name, "includes") - relative_path = os.path.join(os.path.relpath(dest_include_dir, parent_dir), os.path.basename(include_file)) + src_book_relative_dir = os.path.relpath(book_src_dir,info["src_dir"]) + dest_include_dir = os.path.join(dest_dir, src_book_relative_dir, "includes") + relative_path = os.path.join( + os.path.relpath(dest_include_dir, parent_dir), + os.path.basename(include_file), + ) else: - dest_include_dir = os.path.abspath(os.path.join(os.path.dirname(dest_file), os.path.dirname(relative_path))) - dest_include_file = os.path.join(dest_include_dir, os.path.basename(include_file)) + dest_include_dir = os.path.abspath( + os.path.join( + os.path.dirname(dest_file), os.path.dirname(relative_path) + ) + ) + dest_include_file = os.path.join( + dest_include_dir, os.path.basename(include_file) + ) # Make sure we have a reference to the current working dir current_dir = cwd or os.path.dirname(src_file) @@ -448,19 +578,36 @@ def copy_file(info, book_src_dir, src_file, dest_dir, dest_file, include_check=T # Copy the file and fix the content if not os.path.isfile(dest_include_file): - copy_file(info, book_src_dir, include_file, dest_dir, dest_include_file, tag=include_tag, cwd=current_dir) + copy_file( + info, + book_src_dir, + include_file, + dest_dir, + dest_include_file, + tag=include_tag, + cwd=current_dir, + ) else: # The file has already been copied, so just fix the links for this tag - with open(dest_include_file, 'r') as f: + with open(dest_include_file, "r") as f: include_content = f.read() # Fix any links - include_content = fix_links(include_content, info, book_src_dir, include_file, tag=include_tag, cwd=cwd) + include_content = fix_links( + include_content, + info, + book_src_dir, + include_file, + tag=include_tag, + cwd=cwd, + ) with open(dest_include_file, "w") as f: f.write(include_content) - content = content.replace(include_text, include.expand("include::" + relative_path + "[\\2]")) + content = content.replace( + include_text, include.expand("include::" + relative_path + "[\\2]") + ) with open(dest_file, "w") as f: f.write(content) @@ -470,30 +617,44 @@ def scrub_file(info, book_src_dir, src_file, tag=None, cwd=None): """ Scrubs a file and returns the cleaned file contents. """ - base_src_file = src_file.replace(info['src_dir'] + "/", "") + base_src_file = src_file.replace(info["src_dir"] + "/", "") # added 1/Sep/2020 # to allow loading files like json and yaml from external sources, this # procedure loads the file recognizing that it starts with http # it then checks if it exists or not, and if it exists, returns the raw data # data that it finds. - if(base_src_file.startswith("https://raw.githubusercontent.com/openshift/")): + # modified 20/Aug/2024 to process https links which are preceded + # by an added directory (happens with hugeBook) + # Modified 05/Dec/2024 to allow for https links from openshift-kni repo. + + # Check for both allowed URL patterns + https_pos = base_src_file.find("https://raw.githubusercontent.com/openshift/") + https_kni_pos = base_src_file.find("https://raw.githubusercontent.com/openshift-kni/") + + if https_pos >= 0 or https_kni_pos >= 0: + # Ensure we start from the correct URL (either github or openshift-kni) + if https_kni_pos >= 0: + base_src_file = base_src_file[https_kni_pos:] + else: + base_src_file = base_src_file[https_pos:] + try: response = requests.get(base_src_file) - if(response): + if response: return response.text else: raise ConnectionError("Malformed URL") except Exception as exception: log.error("An include file wasn't found: %s", base_src_file) - has_errors = True + list_of_errors.append(f"An include file wasn't found: {base_src_file}") sys.exit(-1) # Get a list of predefined custom title ids for the file title_ids = TITLE_IDS.get(base_src_file, {}) # Read in the source content - with open(src_file, 'r') as f: + with open(src_file, "r") as f: src_file_content = f.readlines() # Scrub the content @@ -505,6 +666,9 @@ def scrub_file(info, book_src_dir, src_file, tag=None, cwd=None): if line.strip() == "" and not content_found: continue + # Replace lines containing commented xrefs + line = COMMENTED_XREF_RE.sub("// Removed commented line that contains an xref", line) + # Check if the line should be included in the output if include_line(line): content_found = True @@ -513,16 +677,24 @@ def scrub_file(info, book_src_dir, src_file, tag=None, cwd=None): if not header_found and line.strip() != "" and line.startswith("="): header_found = True - if info['all_in_one'] and base_src_file in ALL_IN_ONE_SCRAP_TITLE and line.startswith("= "): + if ( + info["all_in_one"] + and base_src_file in ALL_IN_ONE_SCRAP_TITLE + and line.startswith("= ") + ): continue # Add a section id if one doesn't exist, so we have something to link to - elif current_id is None and src_file in info['file_to_id_map']: - file_id = info['file_to_id_map'][src_file] + elif current_id is None and src_file in info["file_to_id_map"]: + file_id = info["file_to_id_map"][src_file] content += "[[" + file_id + "]]\n" # Add a custom title id, if one is needed elif line.startswith("=") and current_id is None: for title in title_ids: - title_re = r"^=+ " + title.replace(".", "\\.").replace("?", "\\?") + "( (anchor|\[).*?)?(\n)?$" + title_re = ( + r"^=+ " + + title.replace(".", "\\.").replace("?", "\\?") + + "( (anchor|\[).*?)?(\n)?$" + ) if re.match(title_re, line): content += "[[" + title_ids[title] + "]]\n" @@ -569,25 +741,42 @@ def fix_links(content, info, book_src_dir, src_file, tag=None, cwd=None): """ Fix any links that were done incorrectly and reference the output instead of the source content. """ - if info['all_in_one']: - content = fix_links(content, info['src_dir'], src_file, info) + if info["all_in_one"]: + content = _fix_links(content, info["src_dir"], src_file, info) else: # Determine if the tag should be passed when fixing the links. If it's in the same book, then process the entire file. If it's # outside the book then don't process it. if book_src_dir in src_file: content = _fix_links(content, book_src_dir, src_file, info, cwd=cwd) else: - content = _fix_links(content, book_src_dir, src_file, info, tag=tag, cwd=cwd) - + content = _fix_links( + content, book_src_dir, src_file, info, tag=tag, cwd=cwd + ) return content +def dir_to_book_name(dir,src_file,info): + # find a book name by the directory + for book in info["book_nodes"]: + if book["Dir"] == dir: + return(book["Name"]) + break + + log.error( + 'ERROR (%s): book not found for the directory %s', + src_file, + dir) + list_of_errors.append(f"ERROR ({src_file}): book not found for the directory {dir}") + return(dir) + def _fix_links(content, book_dir, src_file, info, tag=None, cwd=None): """ Fix any links that were done incorrectly and reference the output instead of the source content. """ + current_book_name = dir_to_book_name(os.path.relpath(book_dir,info["src_dir"]),src_file,info) + # TODO Deal with xref so that they keep the proper path. Atm it'll just strip the path and leave only the id - file_to_id_map = info['file_to_id_map'] + file_to_id_map = info["file_to_id_map"] current_dir = cwd or os.path.dirname(src_file) cleaned_content = remove_conditional_content(content, info, tag=tag) links = LINKS_RE.finditer(cleaned_content) @@ -598,36 +787,70 @@ def _fix_links(content, book_dir, src_file, info, tag=None, cwd=None): link_anchor = link.group(2) link_title = link.group(3) + # sanity check - is this a link to an external site? + # apparently the link macro CAN be used for internal links too, so just testing for http + # NOTE: a docs.openshift.com link would not process here corectly, anyway, so let it pass through + if ("http:" in link_text) or ("https:" in link_text): + continue + + fixed_link = "" # setting the scope of fixed_link outside the if statements if link_file is not None: fixed_link_file = link_file.replace(".html", ".adoc") - fixed_link_file_abs = os.path.abspath(os.path.join(current_dir, fixed_link_file)) + fixed_link_file_abs = os.path.abspath( + os.path.join(current_dir, fixed_link_file) + ) if fixed_link_file_abs in file_to_id_map: - # We are dealing with a cross reference to another book here - external_link = EXTERNAL_LINK_RE.search(link_file) - book_dir_name = external_link.group(1) + # We are dealing with a cross reference to a book here + full_relative_path = os.path.relpath(fixed_link_file_abs,info["src_dir"]) + + if full_relative_path[:2]=="..": + log.error( + 'ERROR (%s): link pointing outside source directory? %s', + src_file, + link_file) + list_of_errors.append(f'ERROR ({src_file}): link pointing outside source directory? {link_file}') + continue + split_relative_path = full_relative_path.split("/") + book_dir_name = split_relative_path[0] + if book_dir_name in info["huge_book_dirs"]: + book_dir_name = split_relative_path[0]+"/"+split_relative_path[1] # Find the book name - book_name = book_dir_name - for book in info['data']: - if check_node_distro_matches(book, info['distro']) and book['Dir'] == book_dir_name: - book_name = book['Name'] - break + book_name = dir_to_book_name(book_dir_name,src_file,info) - fixed_link_file = BASE_PORTAL_URL + build_portal_url(https://github.com/info,%20book_name) - if link_anchor is None: - fixed_link = "link:" + fixed_link_file + "#" + file_to_id_map[fixed_link_file_abs] + link_title + if book_name==current_book_name: + if link_anchor is None: + fixed_link = "xref:" + file_to_id_map[fixed_link_file_abs] + link_title + else: + fixed_link = "xref:" + link_anchor.replace("#", "") + link_title else: - fixed_link = "link:" + fixed_link_file + link_anchor + link_title + fixed_link_file = BASE_PORTAL_URL + build_portal_url(https://github.com/info,%20book_name) + if link_anchor is None: + fixed_link = ( + "link:" + + fixed_link_file + + "#" + + file_to_id_map[fixed_link_file_abs] + + link_title + ) + else: + fixed_link = "link:" + fixed_link_file + link_anchor + link_title else: # Cross reference or link that isn't in the docs suite fixed_link = link_text if EXTERNAL_LINK_RE.search(link_file) is not None: rel_src_file = src_file.replace(os.path.dirname(book_dir) + "/", "") - has_errors = True - log.error("ERROR (%s): \"%s\" appears to try to reference a file not included in the \"%s\" distro", rel_src_file, link_text.replace("\n", ""), info['distro']) + link_text_message = link_text.replace("\n", "") + log.error( + 'ERROR (%s): "%s" appears to try to reference a file not included in the "%s" distro', + rel_src_file, + link_text_message, + info["distro"], + ) + list_of_errors.append(f'ERROR ({rel_src_file})): {link_text_message} appears to try to reference a file not included in the {info["distro"]} distro') else: fixed_link = "xref:" + link_anchor.replace("#", "") + link_title @@ -650,9 +873,9 @@ def remove_conditional_content(content, info, tag=None): # Determine if we should strip the conditional content, based on the distro strip_content = False - if is_not_def and info['distro'] in ifdef_distros: + if is_not_def and info["distro"] in ifdef_distros: strip_content = True - elif not is_not_def and info['distro'] not in ifdef_distros: + elif not is_not_def and info["distro"] not in ifdef_distros: strip_content = True # Remove the conditional content @@ -720,7 +943,9 @@ def build_file_to_id_map(node, distro, existing_ids, path=""): def topic_callback(topic_node, parent_dir, depth): src_file = os.path.join(parent_dir, topic_node["File"] + ".adoc") - file_to_id_map[src_file] = build_file_id(topic_node["Name"], file_to_id_map, existing_ids) + file_to_id_map[src_file] = build_file_id( + topic_node["Name"], file_to_id_map, existing_ids + ) iter_tree(node, distro, topic_callback=topic_callback, parent_dir=path) return file_to_id_map @@ -741,7 +966,9 @@ def build_file_id(file_title, file_to_id_map, existing_ids): """ Generates a unique id for a file, based on its title. """ - file_id = base_id = re.sub(r"[\[\]\(\)#]", "", file_title.lower().replace("_", "-").replace(" ", "-")) + file_id = base_id = re.sub( + r"[\[\]\(\)#]", "", file_title.lower().replace("_", "-").replace(" ", "-") + ) count = 1 while file_id in existing_ids or file_id in list(file_to_id_map.values()): file_id = base_id + "-" + str(count) @@ -754,10 +981,17 @@ def build_portal_url(https://github.com/info,%20book_name): """ Builds a portal url path by escaping the content in the same way drupal does. """ - product = info['product'] - version = info['product-version'] + product = info["product"] + version = info["product-version"] - return generate_url_from_name(product) + "/" + generate_url_from_name(version) + "/html-single/" + generate_url_from_name(book_name) + "/" + return ( + generate_url_from_name(product) + + "/" + + generate_url_from_name(version) + + "/html-single/" + + generate_url_from_name(book_name) + + "/" + ) def replace_nbsp(val): @@ -765,14 +999,14 @@ def replace_nbsp(val): if val is not None: # Check if the string is unicode if isinstance(val, str): - return val.replace('\xa0', ' ') + return val.replace("\xa0", " ") else: - return val.replace('\xc2\xa0', ' ') + return val.replace("\xc2\xa0", " ") else: return None -def generate_url_from_name(name, delimiter='_'): +def generate_url_from_name(name, delimiter="_"): """ Generates a url fragment from a product, version or titles name. """ @@ -814,7 +1048,7 @@ def fetch_sources(url, branch, dir=None, clone_dirname=None): if dir is None: dir = os.getcwd() if clone_dirname is None: - clone_dirname = url.split('/')[-1].replace(".git", "") + clone_dirname = url.split("/")[-1].replace(".git", "") # If the dir already exists update the content, otherwise clone it clone_dir = os.path.abspath(os.path.join(dir, clone_dirname)) @@ -855,7 +1089,7 @@ def _sync_directories_dircmp(dcmp): shutil.rmtree(right) # Copy files that only exist in the source directory or files that have changed - for filename in dcmp.left_only+dcmp.common_files: + for filename in dcmp.left_only + dcmp.common_files: left = os.path.join(dcmp.left, filename) right = os.path.join(dcmp.right, filename) if os.path.isfile(left): @@ -877,8 +1111,14 @@ def commit_and_push_changes(git_dir, git_branch, git_upstream_branch): subprocess.check_call(add_cmd, cwd=git_dir) try: # Commit the changes - commit_cmd = ["git", "commit", "-m", "Merge branch 'upstream/" + git_upstream_branch + "' into " + git_branch, - "--author", "CCS OSE Build Script "] + commit_cmd = [ + "git", + "commit", + "-m", + "Merge branch 'upstream/" + git_upstream_branch + "' into " + git_branch, + "--author", + "CCS OSE Build Script ", + ] call_git_command(commit_cmd, cwd=git_dir, stderr=subprocess.STDOUT) # Push the changes push_cmd = ["git", "push"] @@ -909,7 +1149,7 @@ def parse_repo_config(config_file, distro, version): def main(): parser = setup_parser() args = parser.parse_args() - logging.basicConfig(format='%(message)s', level=logging.INFO, stream=sys.stdout) + logging.basicConfig(format="%(message)s", level=logging.INFO, stream=sys.stdout) # Copy down the latest files if not args.no_upstream_fetch: @@ -936,18 +1176,19 @@ def main(): os.makedirs(dest_dir) info = { - 'title': args.title, - 'product-author': args.author, - 'product-version': args.version, - 'product': args.product, - 'distro': args.distro, - 'src_dir': src_dir, - 'dest_dir': dest_dir, - 'data': data, - 'book_nodes': book_nodes, - 'all_in_one': args.all_in_one, - 'preface-title': "", - "upstream_branch": args.upstream_branch + "title": args.title, + "product-author": args.author, + "product-version": args.version, + "product": args.product, + "distro": args.distro, + "src_dir": src_dir, + "dest_dir": dest_dir, + "data": data, + "book_nodes": book_nodes, + "all_in_one": args.all_in_one, + "preface-title": "", + "upstream_branch": args.upstream_branch, + "huge_book_dirs": [] } # Build the master files @@ -957,12 +1198,12 @@ def main(): # Copy the original data and reformat for drupal reformat_for_drupal(info) - if has_errors: + if list_of_errors: sys.exit(1) if args.push: # Parse the repo urls - config_file = os.path.join(os.path.dirname(__file__), 'repos.ini') + config_file = os.path.join(os.path.dirname(__file__), "repos.ini") repo_urls = parse_repo_config(config_file, args.distro, args.version) # Make sure the base git dire exists @@ -972,7 +1213,7 @@ def main(): # Checkout the gitlab repo, copy the changes and push them back up for book_dir, gitlab_repo_url in list(repo_urls.items()): build_book_dir = os.path.join(dest_dir, book_dir) - git_dirname = gitlab_repo_url.split('/')[-1].replace(".git", "") + git_dirname = gitlab_repo_url.split("/")[-1].replace(".git", "") git_dir = os.path.join(base_git_dir, git_dirname) try: @@ -989,5 +1230,6 @@ def main(): sys.stdout.write(e.output) raise + if __name__ == "__main__": main() diff --git a/cicd/builds/advanced-build-operations.adoc b/cicd/builds/advanced-build-operations.adoc deleted file mode 100644 index 1d49a98d650f..000000000000 --- a/cicd/builds/advanced-build-operations.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="advanced-build-operations"] -= Performing advanced builds -include::modules/common-attributes.adoc[] -:context: advanced-build-operations - -toc::[] - -The following sections provide instructions for advanced build operations including -setting build resources and maximum duration, assigning builds to nodes, chaining -builds, build pruning, and build run policies. - -include::modules/builds-setting-build-resources.adoc[leveloffset=+1] - -include::modules/builds-setting-maximum-duration.adoc[leveloffset=+1] - -include::modules/builds-assigning-builds-to-nodes.adoc[leveloffset=+1] - -include::modules/builds-chaining-builds.adoc[leveloffset=+1] - -include::modules/builds-build-pruning.adoc[leveloffset=+1] - -include::modules/builds-build-run-policy.adoc[leveloffset=+1] diff --git a/cicd/builds/basic-build-operations.adoc b/cicd/builds/basic-build-operations.adoc deleted file mode 100644 index 371683af2206..000000000000 --- a/cicd/builds/basic-build-operations.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="basic-build-operations"] -= Performing basic builds -include::modules/common-attributes.adoc[] -:context: basic-build-operations - -toc::[] - -The following sections provide instructions for basic build operations including starting and canceling builds, deleting BuildConfigs, viewing build details, and accessing build logs. - -include::modules/builds-basic-start-build.adoc[leveloffset=+1] -include::modules/builds-basic-start-re-run.adoc[leveloffset=+2] -include::modules/builds-basic-start-logs.adoc[leveloffset=+2] -include::modules/builds-basic-start-environment-variable.adoc[leveloffset=+2] -include::modules/builds-basic-start-source.adoc[leveloffset=+2] -include::modules/builds-basic-cancel-build.adoc[leveloffset=+1] -include::modules/builds-basic-cancel-multiple.adoc[leveloffset=+2] -include::modules/builds-basic-cancel-all.adoc[leveloffset=+2] -include::modules/builds-basic-cancel-all-state.adoc[leveloffset=+2] -include::modules/builds-basic-delete-buildconfig.adoc[leveloffset=+1] -include::modules/builds-basic-view-build-details.adoc[leveloffset=+1] -include::modules/builds-basic-access-build-logs.adoc[leveloffset=+1] -include::modules/builds-basic-access-buildconfig-logs.adoc[leveloffset=+2] -include::modules/builds-basic-access-buildconfig-version-logs.adoc[leveloffset=+2] -include::modules/builds-basic-access-build-verbosity.adoc[leveloffset=+2] diff --git a/cicd/builds/build-configuration.adoc b/cicd/builds/build-configuration.adoc deleted file mode 100644 index 67d6d8cd08c7..000000000000 --- a/cicd/builds/build-configuration.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="build-configuration"] -= Build configuration resources -include::modules/common-attributes.adoc[] -:context: build-configuration - -toc::[] - -Use the following procedure to configure build settings. - -include::modules/builds-configuration-parameters.adoc[leveloffset=+1] - -include::modules/builds-configuration-file.adoc[leveloffset=+1] diff --git a/cicd/builds/build-strategies.adoc b/cicd/builds/build-strategies.adoc deleted file mode 100644 index 67772ce734ad..000000000000 --- a/cicd/builds/build-strategies.adoc +++ /dev/null @@ -1,71 +0,0 @@ -[id="build-strategies"] -= Using build strategies -include::modules/common-attributes.adoc[] -:context: build-strategies - -toc::[] - -The following sections define the primary supported build strategies, and how to -use them. - -include::modules/builds-strategy-docker-build.adoc[leveloffset=+1] - -include::modules/builds-strategy-docker-from-image.adoc[leveloffset=+2] - -include::modules/builds-strategy-dockerfile-path.adoc[leveloffset=+2] - -include::modules/builds-strategy-docker-environment-variables.adoc[leveloffset=+2] - -include::modules/builds-strategy-docker-build-arguments.adoc[leveloffset=+2] - -include::modules/builds-strategy-s2i-build.adoc[leveloffset=+1] - -include::modules/builds-strategy-s2i-incremental-builds.adoc[leveloffset=+2] - -include::modules/builds-strategy-s2i-override-builder-image-scripts.adoc[leveloffset=+2] - -include::modules/builds-strategy-s2i-environment-variables.adoc[leveloffset=+2] - -include::modules/builds-strategy-s2i-environment-files.adoc[leveloffset=+3] - -include::modules/builds-strategy-s2i-buildconfig-environment.adoc[leveloffset=+3] - -include::modules/builds-strategy-s2i-ignore-source-files.adoc[leveloffset=+2] - -include::modules/images-create-s2i.adoc[leveloffset=+2] - -include::modules/images-create-s2i-build.adoc[leveloffset=+3] - -include::modules/images-create-s2i-scripts.adoc[leveloffset=+3] - -include::modules/builds-strategy-custom-build.adoc[leveloffset=+1] - -include::modules/builds-strategy-custom-from-image.adoc[leveloffset=+2] - -include::modules/builds-strategy-custom-secrets.adoc[leveloffset=+2] - -include::modules/builds-strategy-custom-environment-variables.adoc[leveloffset=+2] - -include::modules/images-custom.adoc[leveloffset=+2] - -include::modules/builds-strategy-pipeline-build.adoc[leveloffset=+1] - -include::modules/builds-understanding-openshift-pipeline.adoc[leveloffset=+2] - -include::modules/builds-strategy-pipeline-providing-jenkinsfile.adoc[leveloffset=+2] - -include::modules/builds-strategy-pipeline-environment-variables.adoc[leveloffset=+2] - -include::modules/builds-strategy-pipeline-mapping-buildconfig-jenkins.adoc[leveloffset=+3] - -include::modules/builds-tutorial-pipeline.adoc[leveloffset=+2] - -//include::modules/builds-strategy-force-pull-procedure.adoc[leveloffset=+1] - -//include::modules/builds-strategy-docker-force-pull-example.adoc[leveloffset=+2] - -//include::modules/builds-strategy-s2i-force-pull-example.adoc[leveloffset=+2] - -include::modules/builds-strategy-secrets-web-console.adoc[leveloffset=+1] - -include::modules/builds-strategy-enable-pulling-pushing.adoc[leveloffset=+1] diff --git a/cicd/builds/creating-build-inputs.adoc b/cicd/builds/creating-build-inputs.adoc deleted file mode 100644 index 7be3e31fb1a0..000000000000 --- a/cicd/builds/creating-build-inputs.adoc +++ /dev/null @@ -1,83 +0,0 @@ -[id="creating-build-inputs"] -= Creating build inputs -include::modules/common-attributes.adoc[] -:context: creating-build-inputs - -toc::[] - -Use the following sections for an overview of build inputs, instructions on how -to use inputs to provide source content for builds to operate on, and how to use -build environments and create secrets. - -include::modules/builds-define-build-inputs.adoc[leveloffset=+1] - -include::modules/builds-dockerfile-source.adoc[leveloffset=+1] - -include::modules/builds-image-source.adoc[leveloffset=+1] - -include::modules/builds-source-code.adoc[leveloffset=+1] - -include::modules/builds-using-proxy-git-cloning.adoc[leveloffset=+2] - -include::modules/builds-adding-source-clone-secrets.adoc[leveloffset=+2] - -include::modules/builds-automatically-add-source-clone-secrets.adoc[leveloffset=+3] - -include::modules/builds-manually-add-source-clone-secrets.adoc[leveloffset=+3] - -include::modules/builds-gitconfig-file.adoc[leveloffset=+3] - -include::modules/builds-gitconfig-file-secured-git.adoc[leveloffset=+3] - -include::modules/builds-source-secret-basic-auth.adoc[leveloffset=+3] - -include::modules/builds-source-secret-ssh-key-auth.adoc[leveloffset=+3] - -include::modules/builds-source-secret-trusted-ca.adoc[leveloffset=+3] - -include::modules/builds-source-secret-combinations.adoc[leveloffset=+3] - -include::modules/builds-source-secret-combinations-ssh-gitconfig.adoc[leveloffset=+4] - -include::modules/builds-source-secret-combinations-gitconfig-ca.adoc[leveloffset=+4] - -include::modules/builds-source-secret-combinations-basic-auth-ca.adoc[leveloffset=+4] - -include::modules/builds-source-secret-combinations-basic-auth-gitconfig.adoc[leveloffset=+4] - -include::modules/builds-source-secret-combinations-basic-auth-gitconfig-ca.adoc[leveloffset=+4] - -include::modules/builds-binary-source.adoc[leveloffset=+1] - -include::modules/builds-input-secrets-configmaps.adoc[leveloffset=+1] - -include::modules/builds-adding-input-secrets-configmaps.adoc[leveloffset=+2] - -include::modules/builds-source-to-image.adoc[leveloffset=+2] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] - -include::modules/builds-docker-strategy.adoc[leveloffset=+2] - -include::modules/builds-custom-strategy.adoc[leveloffset=+2] -endif::[] - -include::modules/builds-using-external-artifacts.adoc[leveloffset=+1] - -include::modules/builds-docker-credentials-private-registries.adoc[leveloffset=+1] - -include::modules/builds-build-environment.adoc[leveloffset=+1] - -include::modules/builds-using-build-fields-as-environment-variables.adoc[leveloffset=+2] - -include::modules/builds-using-secrets-as-environment-variables.adoc[leveloffset=+2] - -include::modules/builds-secrets-overview.adoc[leveloffset=+1] - -include::modules/builds-creating-secrets.adoc[leveloffset=+2] - -include::modules/builds-using-secrets.adoc[leveloffset=+3] - -include::modules/builds-service-serving-certificate-secrets.adoc[leveloffset=+1] - -include::modules/builds-secrets-restrictions.adoc[leveloffset=+1] diff --git a/cicd/builds/custom-builds-buildah.adoc b/cicd/builds/custom-builds-buildah.adoc deleted file mode 100644 index 1c781ab64730..000000000000 --- a/cicd/builds/custom-builds-buildah.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="custom-builds-buildah"] -= Custom image builds with Buildah -include::modules/common-attributes.adoc[] -:context: custom-builds-buildah - -toc::[] - - -With {product-title} {product-version}, a docker socket will not be present on the host -nodes. This means the _mount docker socket_ option of a custom build is not -guaranteed to provide an accessible docker socket for use within a custom build -image. - -If you require this capability in order to build and push images, add the Buildah -tool your custom build image and use it to build and push the image within your -custom build logic. The following is an example of how to run custom builds with -Buildah. - -[NOTE] -==== -Using the custom build strategy requires permissions that normal users do -not have by default because it allows the user to execute arbitrary code inside -a privileged container running on the cluster. This level of access can be used -to compromise the cluster and therefore should be granted only to users who are -trusted with administrative privileges on the cluster. -==== - -== Prerequisites - -* Review how to xref:../../cicd/builds/securing-builds-by-strategy.adoc#securing-builds-by-strategy[grant custom build permissions]. - - -include::modules/builds-create-custom-build-artifacts.adoc[leveloffset=+1] -include::modules/builds-build-custom-builder-image.adoc[leveloffset=+1] -include::modules/builds-use-custom-builder-image.adoc[leveloffset=+1] diff --git a/cicd/builds/managing-build-output.adoc b/cicd/builds/managing-build-output.adoc deleted file mode 100644 index 0cf38282b022..000000000000 --- a/cicd/builds/managing-build-output.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="managing-build-output"] -= Managing build output -include::modules/common-attributes.adoc[] -:context: managing-build-output - -toc::[] - - -Use the following sections for an overview of and instructions for managing -build output. - -include::modules/builds-docker-source-build-output.adoc[leveloffset=+1] - -include::modules/builds-output-image-environment-variables.adoc[leveloffset=+1] - -include::modules/builds-output-image-labels.adoc[leveloffset=+1] diff --git a/cicd/builds/running-entitled-builds.adoc b/cicd/builds/running-entitled-builds.adoc deleted file mode 100644 index 29f9d4bdedef..000000000000 --- a/cicd/builds/running-entitled-builds.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="running-entitled-builds"] -= Using Red Hat subscriptions in builds -include::modules/common-attributes.adoc[] -:context: running-entitled-builds - -toc::[] - -Use the following sections to run entitled builds on {product-title}. - -include::modules/builds-create-imagestreamtag.adoc[leveloffset=+1] - -include::modules/builds-source-secrets-entitlements.adoc[leveloffset=+1] - -== Running builds with Subscription Manager - -include::modules/builds-strategy-docker-entitled-subman.adoc[leveloffset=+2] - -== Running builds with Red Hat Satellite subscriptions - -include::modules/builds-source-input-satellite-config.adoc[leveloffset=+2] - -include::modules/builds-strategy-docker-entitled-satellite.adoc[leveloffset=+2] - -include::modules/builds-strategy-docker-squash-layers.adoc[leveloffset=+1] - - -== Additional resources - -* See xref:../../openshift_images/image-streams-manage.adoc#image-streams-managing[Managing image streams] -for more information. diff --git a/cicd/builds/securing-builds-by-strategy.adoc b/cicd/builds/securing-builds-by-strategy.adoc deleted file mode 100644 index dd42c3367c98..000000000000 --- a/cicd/builds/securing-builds-by-strategy.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="securing-builds-by-strategy"] -= Securing builds by strategy -include::modules/common-attributes.adoc[] -:context: securing-builds-by-strategy - -toc::[] - -Builds in {product-title} are run in privileged containers. Depending on the build strategy used, if you have privileges, you can run builds to escalate their permissions on the cluster and host nodes. And as a security measure, it limits who can run builds and the strategy that is used for those builds. Custom builds are inherently less safe than source builds, because they can execute any code within a privileged container, and are disabled by default. Grant docker build permissions with caution, because a vulnerability in the Dockerfile processing logic could result in a privileges being granted on the host node. - -By default, all users that can create builds are granted permission to use the docker and Source-to-image (S2I) build strategies. Users with cluster administrator privileges can enable the custom build strategy, as referenced in the restricting build strategies to a user globally section. - -You can control who can build and which build strategies they can use by using an authorization policy. Each build strategy has a corresponding build subresource. A user must have permission to create a build and permission to create on the build strategy subresource to create builds using that strategy. Default roles are provided that grant the create permission on the build strategy subresource. - -.Build Strategy Subresources and Roles -[options="header"] -|=== - -|Strategy |Subresource |Role - -|Docker -|builds/docker -|system:build-strategy-docker - -|Source-to-Image -|builds/source -|system:build-strategy-source - -|Custom -|builds/custom -|system:build-strategy-custom - -|JenkinsPipeline -|builds/jenkinspipeline -|system:build-strategy-jenkinspipeline - -|=== - -include::modules/builds-disabling-build-strategy-globally.adoc[leveloffset=+1] -include::modules/builds-restricting-build-strategy-globally.adoc[leveloffset=+1] -include::modules/builds-restricting-build-strategy-to-user.adoc[leveloffset=+1] diff --git a/cicd/builds/setting-up-trusted-ca.adoc b/cicd/builds/setting-up-trusted-ca.adoc deleted file mode 100644 index d93c52ed7f3d..000000000000 --- a/cicd/builds/setting-up-trusted-ca.adoc +++ /dev/null @@ -1,51 +0,0 @@ -[id="setting-up-trusted-ca"] -= Setting up additional trusted certificate authorities for builds -include::modules/common-attributes.adoc[] -:context: setting-up-trusted-ca - -toc::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -Use the following sections to set up additional certificate authorities (CA) to be trusted by builds when pulling images from an image registry. - -The procedure requires a cluster administrator to create a `ConfigMap` and add additional CAs as keys in the `ConfigMap`. - -* The `ConfigMap` must be created in the `openshift-config` namespace. -* `domain` is the key in the `ConfigMap` and `value` is the PEM-encoded certificate. -** Each CA must be associated with a domain. The domain format is `hostname[..port]`. -* The `ConfigMap` name must be set in the `image.config.openshift.io/cluster` cluster scoped configuration resource's `spec.additionalTrustedCA` field. -//* No longer needs single PEM bundle - -include::modules/configmap-adding-ca.adoc[leveloffset=+1] - -== Additional resources - -* link:https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-a-configmap[Create a `ConfigMap`] -* link:https://kubectl.docs.kubernetes.io/guides/config_management/secrets_configmaps/[Secrets and `ConfigMaps`] -* xref:../../networking/configuring-a-custom-pki.adoc#configuring-a-custom-pki[Configuring a custom PKI] -endif::[] - - -ifdef::openshift-dedicated[] -Use the following sections to set up additional certificate authorities (CA) to be trusted by builds when pulling images from an image registry. - -The procedure requires a Dedicated administrator to create a `ConfigMap` and add additional CAs as keys in the `ConfigMap`. - -* The `ConfigMap` must be created in the `openshift-config` namespace. -* `domain` is the key in the `ConfigMap` and `value` is the PEM-encoded certificate. -** Each CA must be associated with a domain. The domain format is `hostname[..port]`. -* The `ConfigMap` name must be set in the `image.config.openshift.io/cluster` cluster scoped configuration resource's `spec.additionalTrustedCA` field. -//* No longer needs single PEM bundle - -[NOTE] -==== -{product-title} administrators are required to use the `registry-cas` `ConfigMap`. -==== - -include::modules/configmap-adding-ca.adoc[leveloffset=+1] - -== Additional resources - -* link:https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#create-a-configmap[Create a ConfigMap] -* link:https://kubectl.docs.kubernetes.io/guides/config_management/secrets_configmaps/[Secrets and ConfigMaps] -endif::[] diff --git a/cicd/builds/triggering-builds-build-hooks.adoc b/cicd/builds/triggering-builds-build-hooks.adoc deleted file mode 100644 index 85171adeaa81..000000000000 --- a/cicd/builds/triggering-builds-build-hooks.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="triggering-builds-build-hooks"] -= Triggering and modifying builds -include::modules/common-attributes.adoc[] -:context: triggering-builds-build-hooks - -toc::[] - -The following sections outline how to trigger builds and modify builds using build hooks. - -include::modules/builds-triggers.adoc[leveloffset=+1] - -include::modules/builds-webhook-triggers.adoc[leveloffset=+2] - -include::modules/builds-using-github-webhooks.adoc[leveloffset=+3] - -include::modules/builds-using-gitlab-webhooks.adoc[leveloffset=+3] - -include::modules/builds-using-bitbucket-webhooks.adoc[leveloffset=+3] - -include::modules/builds-using-generic-webhooks.adoc[leveloffset=+3] - -include::modules/builds-displaying-webhook-urls.adoc[leveloffset=+3] - -include::modules/builds-using-image-change-triggers.adoc[leveloffset=+2] - -include::modules/builds-configuration-change-triggers.adoc[leveloffset=+2] - -include::modules/builds-setting-triggers-manually.adoc[leveloffset=+3] - -include::modules/builds-build-hooks.adoc[leveloffset=+1] - -include::modules/builds-configuring-post-commit-build-hooks.adoc[leveloffset=+2] - -include::modules/builds-using-cli-post-commit-build-hooks.adoc[leveloffset=+2] diff --git a/cicd/builds/troubleshooting-builds.adoc b/cicd/builds/troubleshooting-builds.adoc deleted file mode 100644 index a09c425d9135..000000000000 --- a/cicd/builds/troubleshooting-builds.adoc +++ /dev/null @@ -1,12 +0,0 @@ -:context: troubleshooting-builds -[id="troubleshooting-builds_{context}"] -= Troubleshooting builds -include::modules/common-attributes.adoc[] - -toc::[] - -Use the following to troubleshoot build issues. - -include::modules/builds-troubleshooting-access-resources.adoc[leveloffset=+1] - -include::modules/builds-troubleshooting-service-certificate-generation.adoc[leveloffset=+1] diff --git a/cicd/builds/understanding-buildconfigs.adoc b/cicd/builds/understanding-buildconfigs.adoc deleted file mode 100644 index ac16a8327d76..000000000000 --- a/cicd/builds/understanding-buildconfigs.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="understanding-buildconfigs"] -= Understanding build configurations -include::modules/common-attributes.adoc[] -:context: understanding-builds - -toc::[] - -The following sections define the concept of a build, build configuration, and outline the primary build strategies available. - -include::modules/builds-buildconfig.adoc[leveloffset=+1] diff --git a/cicd/builds/understanding-image-builds.adoc b/cicd/builds/understanding-image-builds.adoc deleted file mode 100644 index f15c8c5755c5..000000000000 --- a/cicd/builds/understanding-image-builds.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="understanding-image-builds"] -= Understanding image builds -include::modules/common-attributes.adoc[] -:context: understanding-image-builds - -toc::[] - -include::modules/builds-about.adoc[leveloffset=+1] - -include::modules/builds-strategy-docker-build.adoc[leveloffset=+2] - -include::modules/builds-strategy-s2i-build.adoc[leveloffset=+2] - -include::modules/builds-strategy-custom-build.adoc[leveloffset=+2] - -include::modules/builds-strategy-pipeline-build.adoc[leveloffset=+2] diff --git a/cicd/gitops/getting-started-with-openshift-gitops.adoc b/cicd/gitops/getting-started-with-openshift-gitops.adoc deleted file mode 100644 index be276a31d2cd..000000000000 --- a/cicd/gitops/getting-started-with-openshift-gitops.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="getting-started-with-openshift-gitops"] -= Getting started with OpenShift GitOps -include::modules/common-attributes.adoc[] -:context: getting-started-with-openshift-gitops - -toc::[] - -Red Hat OpenShift GitOps uses Argo CD as the core declarative tool and adds other tooling to enable teams to implement GitOps workflows across clusters. -This section walks you through the process of launching Argo CD using the web console and logging into it. - -== Prerequisites - -* You must install the xref:../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[Red Hat OpenShift GitOps Operator] listed in the OpenShift OperatorHub by using the default installation options. - -//Procedure Module -include::modules/launching-the-operator-provided-argocd-instance.adoc[leveloffset=+1] diff --git a/cicd/gitops/images b/cicd/gitops/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/cicd/gitops/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/cicd/gitops/understanding-openshift-gitops.adoc b/cicd/gitops/understanding-openshift-gitops.adoc deleted file mode 100644 index 0f2cc3916517..000000000000 --- a/cicd/gitops/understanding-openshift-gitops.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="understanding-openshift-gitops"] -= Understanding OpenShift GitOps -include::modules/common-attributes.adoc[] -include::modules/gitops-document-attributes.adoc[] -:context: understanding-openshift-gitops - -toc::[] - -//Concept Module -include::modules/about-gitops.adoc[leveloffset=+1] - -//Concept Module -include::modules/about-redhat-openshift-gitops.adoc[leveloffset=+1] diff --git a/cicd/pipelines/creating-applications-with-cicd-pipelines.adoc b/cicd/pipelines/creating-applications-with-cicd-pipelines.adoc deleted file mode 100644 index b569822c45f6..000000000000 --- a/cicd/pipelines/creating-applications-with-cicd-pipelines.adoc +++ /dev/null @@ -1,65 +0,0 @@ -[id='creating-applications-with-cicd-pipelines'] -= Creating CI/CD solutions for applications using OpenShift Pipelines -include::modules/common-attributes.adoc[] -include::modules/pipelines-document-attributes.adoc[] -:context: creating-applications-with-cicd-pipelines - -toc::[] - -With {pipelines-title}, you can create a customized CI/CD solution to build, test, and deploy your application. - -To create a full-fledged, self-serving CI/CD pipeline for an application, you must perform the following tasks: - -* Create custom tasks, or install existing reusable tasks. -* Create and define the delivery pipeline for your application. -* Provide a storage volume or filesystem that is attached to a workspace for the pipeline execution using one of the following approaches: -** Specify a volume claim template that creates a persistent volume claim -** Specify a persistent volume claim -* Create a `PipelineRun` object to instantiate and invoke the pipeline. -* Add triggers to capture events in the source repository. - -This section uses the `pipelines-tutorial` example to demonstrate the preceding tasks. The example uses a simple application which consists of: - -* A front-end interface, `vote-ui`, with the source code in the link:https://github.com/openshift-pipelines/vote-ui/tree/pipelines-1.3[`ui-repo`] Git repository. -* A back-end interface, `vote-api`, with the source code in the link:https://github.com/openshift-pipelines/vote-api/tree/pipelines-1.3[`api-repo`] Git repository. -* The `apply-manifests` and `update-deployment` tasks in the link:https://github.com/openshift/pipelines-tutorial/tree/pipelines-1.3[`pipelines-tutorial`] Git repository. - -== Prerequisites - -* You have access to an {product-title} cluster. -* You have installed xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[OpenShift Pipelines] using the {pipelines-title} Operator listed in the OpenShift OperatorHub. Once installed, it is applicable to the entire cluster. -* You have installed xref:../../cli_reference/tkn_cli/installing-tkn.adoc#installing-tkn[OpenShift Pipelines CLI]. -* You have forked the front-end link:https://github.com/openshift-pipelines/vote-ui/tree/pipelines-1.3[`ui-repo`] and back-end link:https://github.com/openshift-pipelines/vote-api/tree/pipelines-1.3[`api-repo`] Git repositories using your GitHub ID, and have Administrator access to these repositories. -* Optional: You have cloned the link:https://github.com/openshift/pipelines-tutorial/tree/pipelines-1.3[`pipelines-tutorial`] Git repository. - - -include::modules/op-creating-project-and-checking-pipeline-service-account.adoc[leveloffset=+1] - -include::modules/op-creating-pipeline-tasks.adoc[leveloffset=+1] - -include::modules/op-assembling-a-pipeline.adoc[leveloffset=+1] - -include::modules/op-mirroring-images-to-run-pipelines-in-restricted-environment.adoc[leveloffset=+1] - -.Additional resources - -* xref:../../openshift_images/configuring-samples-operator.adoc#samples-operator-restricted-network-install[Configuring Samples Operator for a restricted cluster] - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installation-about-mirror-registry_installing-restricted-networks-preparations[Creating a cluster with a mirrored registry] - -* xref:../../cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster.adoc#mirroring-a-supported-builder-image_creating-and-deploying-a-component-to-the-disconnected-cluster[Mirroring a supported builder image] - -include::modules/op-running-a-pipeline.adoc[leveloffset=+1] - -include::modules/op-adding-triggers.adoc[leveloffset=+1] - -include::modules/op-creating-webhooks.adoc[leveloffset=+1] - -include::modules/op-triggering-a-pipelinerun.adoc[leveloffset=+1] - -[id="pipeline-addtl-resources"] -== Additional resources - -* For more details on pipelines in the *Developer* perspective, see the xref:../../cicd/pipelines/working-with-pipelines-using-the-developer-perspective.adoc#working-with-pipelines-using-the-developer-perspective[working with Pipelines in the *Developer* perspective] section. -* To learn more about Security Context Constraints (SCCs), see the xref:../../authentication/managing-security-context-constraints.adoc#managing-pod-security-policies[Managing Security Context Constraints] section. -* For more examples of reusable tasks, see the link:https://github.com/openshift/pipelines-catalog[OpenShift Catalog] repository. Additionally, you can also see the Tekton Catalog in the Tekton project. diff --git a/cicd/pipelines/images b/cicd/pipelines/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/cicd/pipelines/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/cicd/pipelines/installing-pipelines.adoc b/cicd/pipelines/installing-pipelines.adoc deleted file mode 100644 index 156ca6a3958f..000000000000 --- a/cicd/pipelines/installing-pipelines.adoc +++ /dev/null @@ -1,52 +0,0 @@ -[id="installing-pipelines"] -= Installing OpenShift Pipelines -include::modules/common-attributes.adoc[] -include::modules/pipelines-document-attributes.adoc[] -:context: installing-pipelines - -toc::[] - -This guide walks cluster administrators through the process of installing the {pipelines-title} Operator to an {product-title} cluster. - -// Prerequisites for installing OpenShift Operator -[discrete] -== Prerequisites - -* You have access to an {product-title} cluster using an account with `cluster-admin` permissions. - -* You have installed `oc` CLI. -* You have installed xref:../../cli_reference/tkn_cli/installing-tkn.adoc#installing-tkn[OpenShift Pipelines (`tkn`) CLI] on your local system. - -ifdef::openshift-origin[] -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in the xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#installation-obtaining-installer_installing-gcp-customizations[Obtaining the installation program] to install this Operator. -+ -If you have the pull secret, add the `redhat-operators` catalog to the OperatorHub custom resource (CR) as shown in xref:../../post_installation_configuration/preparing-for-users.adoc#olm-installing-operators-from-operatorhub-configure_post-install-preparing-for-users[Configuring {product-title} to use Red Hat Operators]. -endif::[] - - -//Installing Pipelines Operator using web console - -include::modules/op-installing-pipelines-operator-in-web-console.adoc[leveloffset=+1] - -// Installing Pipelines Operator using CLI - -include::modules/op-installing-pipelines-operator-using-the-cli.adoc[leveloffset=+1] - -// {pipelines-title} Operator in a restricted environment - -include::modules/op-pipelines-operator-in-restricted-environment.adoc[leveloffset=+1] - - -== Additional Resources - -* You can learn more about installing Operators on {product-title} in the xref:../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[adding Operators to a cluster] section. - -* For more information on using pipelines in a restricted environment see: - -** xref:../../creating-applications-with-cicd-pipelines.adoc#op-mirroring-images-to-run-pipelines-in-restricted-environment_creating-applications-with-cicd-pipelines[Mirroring images to run pipelines in a restricted environment] - -** xref:../../openshift_images/configuring-samples-operator.adoc#samples-operator-restricted-network-install[Configuring Samples Operator for a restricted cluster] - -** xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installation-about-mirror-registry_installing-restricted-networks-preparations[Creating a cluster with a mirrored registry] - -** xref:../../cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster.adoc#mirroring-a-supported-builder-image_creating-and-deploying-a-component-to-the-disconnected-cluster[Mirroring a supported builder image] diff --git a/cicd/pipelines/op-release-notes.adoc b/cicd/pipelines/op-release-notes.adoc deleted file mode 100644 index e5581d2feb09..000000000000 --- a/cicd/pipelines/op-release-notes.adoc +++ /dev/null @@ -1,58 +0,0 @@ -//OpenShift Pipelines Release Notes -include::modules/pipelines-document-attributes.adoc[] -[id="op-release-notes"] -= {pipelines-title} release notes -:context: op-release-notes -include::modules/common-attributes.adoc[] - -toc::[] - -{pipelines-title} is a cloud-native CI/CD experience based on the Tekton project which provides: - -* Standard Kubernetes-native pipeline definitions (CRDs). -* Serverless pipelines with no CI server management overhead. -* Extensibility to build images using any Kubernetes tool, such as S2I, Buildah, JIB, and Kaniko. -* Portability across any Kubernetes distribution. -* Powerful CLI for interacting with pipelines. -* Integrated user experience with the Developer perspective of the {product-title} web console. - -For an overview of {pipelines-title}, see xref:../../cicd/pipelines/understanding-openshift-pipelines.adoc#understanding-openshift-pipelines[Understanding OpenShift Pipelines]. - -[id="getting-support"] -== Pipelines support - -//// -The following compatibility matrix shows the support status and compatible versions for the various {pipelines-title} components: - -|=== -|{pipelines-title} | Support status | Pipelines | Triggers | CLI | Catalog | {product-title} - -| 1.4 -|General Availability (GA) - -|0.22 - -|0.12 - -|0.17 - -|0.22 - -|4.7 - -|=== -//// - -If you experience difficulty with a procedure described in this documentation, -visit the Red Hat Customer Portal to learn more about link:https://access.redhat.com/support/offerings/techpreview/[Red Hat Technology Preview features support scope]. - -For questions and feedback, you can send an email to the product team at pipelines-interest@redhat.com. - -// Modules included, most to least recent -include::modules/op-release-notes-1-3.adoc[leveloffset=+1] - -include::modules/op-release-notes-1-2.adoc[leveloffset=+1] - -include::modules/op-release-notes-1-1.adoc[leveloffset=+1] - -include::modules/op-release-notes-1-0.adoc[leveloffset=+1] diff --git a/cicd/pipelines/understanding-openshift-pipelines.adoc b/cicd/pipelines/understanding-openshift-pipelines.adoc deleted file mode 100644 index 482c6363bf26..000000000000 --- a/cicd/pipelines/understanding-openshift-pipelines.adoc +++ /dev/null @@ -1,50 +0,0 @@ -[id="understanding-openshift-pipelines"] -= Understanding OpenShift Pipelines -include::modules/common-attributes.adoc[] -include::modules/pipelines-document-attributes.adoc[] -:context: understanding-openshift-pipelines - -toc::[] - -:FeatureName: OpenShift Pipelines -include::modules/technology-preview.adoc[leveloffset=+1] - -{pipelines-title} is a cloud-native, continuous integration and continuous delivery (CI/CD) solution based on Kubernetes resources. It uses Tekton building blocks to automate deployments across multiple platforms by abstracting away the underlying implementation details. Tekton introduces a number of standard Custom Resource Definitions (CRDs) for defining CI/CD pipelines that are portable across Kubernetes distributions. - -//// -{pipelines-title} is a cloud-native, continuous integration and continuous delivery (CI/CD) solution based on Kubernetes resources. It uses link:https://tekton.dev[Tekton] building blocks to automate deployments across multiple platforms by abstracting away the underlying implementation details. Tekton introduces a number of standard Custom Resource Definitions (CRDs) for defining CI/CD pipelines that are portable across Kubernetes distributions. -//// -[id="op-key-features"] -== Key features - -* {pipelines-title} is a serverless CI/CD system that runs Pipelines with all the required dependencies in isolated containers. -* {pipelines-title} are designed for decentralized teams that work on microservice-based architecture. -* {pipelines-title} use standard CI/CD pipeline definitions that are easy to extend and integrate with the existing Kubernetes tools, enabling you to scale on-demand. -* You can use {pipelines-title} to build images with Kubernetes tools such as Source-to-Image (S2I), Buildah, Buildpacks, and Kaniko that are portable across any Kubernetes platform. -* You can use the {product-title} Developer Console to create Tekton resources, view logs of Pipeline runs, and manage pipelines in your {product-title} namespaces. - -//Main Concept Topic -include::modules/op-pipelines-concepts.adoc[leveloffset=+1] - -[id="op-detailed-concepts"] -== Detailed OpenShift Pipeline Concepts -This guide provides a detailed view of the various Pipeline concepts. - -//About Tasks -include::modules/op-about-tasks.adoc[leveloffset=+2] -//About TaskRun -include::modules/op-about-taskrun.adoc[leveloffset=+2] -//About Pipelines -include::modules/op-about-pipelines.adoc[leveloffset=+2] -//About PipelineRun -include::modules/op-about-pipelinerun.adoc[leveloffset=+2] -//About Workspace -include::modules/op-about-workspace.adoc[leveloffset=+2] -//About Triggers -include::modules/op-about-triggers.adoc[leveloffset=+2] - - -== Additional resources - -* For information on installing Pipelines, see xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[Installing OpenShift Pipelines]. -* For more details on creating custom CI/CD solutions, see xref:../../cicd/pipelines/creating-applications-with-cicd-pipelines.adoc#creating-applications-with-cicd-pipelines[Creating applications with CI/CD Pipelines]. diff --git a/cicd/pipelines/uninstalling-pipelines.adoc b/cicd/pipelines/uninstalling-pipelines.adoc deleted file mode 100644 index 2139e8292335..000000000000 --- a/cicd/pipelines/uninstalling-pipelines.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="uninstalling-pipelines"] -= Uninstalling OpenShift Pipelines -include::modules/common-attributes.adoc[] -include::modules/pipelines-document-attributes.adoc[] -:context: uninstalling-pipelines - -toc::[] - -Uninstalling the {pipelines-title} Operator is a two-step process: - -. Delete the Custom Resources (CRs) that were added by default when you installed the {pipelines-title} Operator. -. Uninstall the {pipelines-title} Operator. - -Uninstalling only the Operator will not remove the {pipelines-title} components created by default when the Operator is installed. - -include::modules/op-deleting-the-pipelines-component-and-custom-resources.adoc[leveloffset=+1] - -include::modules/op-uninstalling-the-pipelines-operator.adoc[leveloffset=+1] - -.Additional Resources - -* You can learn more about uninstalling Operators on {product-title} in the xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[deleting Operators from a cluster] section. diff --git a/cicd/pipelines/working-with-pipelines-using-the-developer-perspective.adoc b/cicd/pipelines/working-with-pipelines-using-the-developer-perspective.adoc deleted file mode 100644 index e5030cf6a4e8..000000000000 --- a/cicd/pipelines/working-with-pipelines-using-the-developer-perspective.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id='working-with-pipelines-using-the-developer-perspective'] -= Working with {pipelines-title} using the Developer perspective -include::modules/common-attributes.adoc[] -include::modules/pipelines-document-attributes.adoc[] - - -:context: working-with-pipelines-using-the-developer-perspective - -toc::[] - -You can use the *Developer* perspective of the {product-title} web console to create CI/CD Pipelines for your software delivery process. - - -In the *Developer* perspective: - -* Use the *Add* -> *Pipeline* -> *Pipeline Builder* option to create customized Pipelines for your application. -* Use the *Add* -> *From Git* option to create Pipelines using operator-installed Pipeline templates and resources while creating an application on {product-title}. - -After you create the Pipelines for your application, you can view and visually interact with the deployed Pipelines in the *Pipelines* view. You can also use the *Topology* view to interact with the Pipelines created using the *From Git* option. You need to apply custom labels to a Pipeline created using the *Pipeline Builder* to see it in the *Topology* view. - -[discrete] -== Prerequisites - -* You have access to an {product-title} cluster and have switched to the xref:../../web_console/odc-about-developer-perspective.adoc[Developer perspective] in the web console. -* You have the xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[OpenShift Pipelines Operator installed] in your cluster. -* You are a cluster administrator or a user with create and edit permissions. -* You have created a project. - - -include::modules/op-constructing-pipelines-using-pipeline-builder.adoc[leveloffset=+1] - -== Creating applications with OpenShift Pipelines - -To create Pipelines along with applications, use the *From Git* option in the *Add* view of the *Developer* perspective. For more information, see xref:../../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-importing-codebase-from-git-to-create-application_odc-creating-applications-using-developer-perspective[Creating applications using the Developer perspective]. - -include::modules/op-interacting-with-pipelines-using-the-developer-perspective.adoc[leveloffset=+1] - -include::modules/op-starting-pipelines.adoc[leveloffset=+1] - -include::modules/op-editing-pipelines.adoc[leveloffset=+1] - -include::modules/op-deleting-pipelines.adoc[leveloffset=+1] diff --git a/cli/checking-policy-compliance.adoc b/cli/checking-policy-compliance.adoc new file mode 100644 index 000000000000..dbea97928d26 --- /dev/null +++ b/cli/checking-policy-compliance.adoc @@ -0,0 +1,30 @@ +[id="checking-policy-compliance"] +:_mod-docs-content-type: ASSEMBLY += Checking policy compliance +include::modules/common-attributes.adoc[] +:context: checking-policy-compliance + +toc::[] + +[role="_abstract"] +You can use the `roxctl` CLI to check deployment YAML files and images for policy compliance. + +include::modules/setting-up-environment-variables.adoc[leveloffset=+1] + +include::modules/configuring-output-format.adoc[leveloffset=+1] + +include::modules/checking-deployment-yaml-files.adoc[leveloffset=+1] + +include::modules/checking-images.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-image.adoc[roxctl image] + +include::modules/checking-image-scan-results.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-image.adoc[roxctl image] \ No newline at end of file diff --git a/cli/command-reference/_attributes b/cli/command-reference/_attributes new file mode 120000 index 000000000000..20cc1dcb77bf --- /dev/null +++ b/cli/command-reference/_attributes @@ -0,0 +1 @@ +../../_attributes/ \ No newline at end of file diff --git a/cli_reference/developer_cli_odo/images b/cli/command-reference/images similarity index 100% rename from cli_reference/developer_cli_odo/images rename to cli/command-reference/images diff --git a/cli_reference/helm_cli/modules b/cli/command-reference/modules similarity index 100% rename from cli_reference/helm_cli/modules rename to cli/command-reference/modules diff --git a/cli/command-reference/roxctl-central.adoc b/cli/command-reference/roxctl-central.adoc new file mode 100644 index 000000000000..0a96287e21b7 --- /dev/null +++ b/cli/command-reference/roxctl-central.adoc @@ -0,0 +1,153 @@ +[id="roxctl-central"] +:_mod-docs-content-type: ASSEMBLY += roxctl central +include::modules/common-attributes.adoc[] +:context: roxctl-central + +toc::[] + +Commands related to the Central service. + +.Usage +[source,terminal] +---- +$ roxctl central [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`backup` +|Create a backup of the {rh-rhacs-first} database and the certificates. + +|`cert` +|Download the certificate chain for the Central service. + +|`crs` +|Generate a cluster registration secret (CRS) that allows communication between Central and secured clusters for the initial setup, to retrieve a list of CRSes, or to revoke a CRS. + +|`db` +|Control the database operations. + +|`debug` +|Debug the Central service. + +|`generate` +|Generate the required YAML configuration files containing the orchestrator objects for the deployment of Central. + +|`init-bundles` +|Initialize bundles for Central. + +|`login` +|Log in to the Central instance to obtain a token. + +|`userpki` +|Manage the user certificate authorization providers. + +|`whoami` +|Display information about the current user and their authentication method. +|=== + +//Options inherited from the parent command +:commandname: roxctl central +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl central backup +include::modules/roxctl-central-backup.adoc[leveloffset=+1] + + +//roxctl central cert +include::modules/roxctl-central-cert.adoc[leveloffset=+1] + +//roxctl crs +include::modules/roxctl-central-crs.adoc[leveloffset=+1] +include::modules/roxctl-central-crs-generate.adoc[leveloffset=+2] +include::modules/roxctl-central-crs-list.adoc[leveloffset=+2] +include::modules/roxctl-central-crs-revoke.adoc[leveloffset=+2] + +//roxctl central login +include::modules/roxctl-central-login.adoc[leveloffset=+1] + +//roxctl central whoami +include::modules/roxctl-central-whoami.adoc[leveloffset=+1] + +//roxctl central db +include::modules/roxctl-central-db.adoc[leveloffset=+1] + +include::modules/roxctl-central-db-restore.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-generate.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-generate-k8s.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-restore-cancel.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-restore-status.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-generate-k8s-pvc.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-generate-openshift.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-generate-k8s-hostpath.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-generate-openshift-pvc.adoc[leveloffset=+2] + +include::modules/roxctl-central-db-generate-openshift-hostpath.adoc[leveloffset=+2] + +//roxctl central debug +include::modules/roxctl-central-debug.adoc[leveloffset=+1] + +include::modules/roxctl-central-debug-db.adoc[leveloffset=+2] + +include::modules/roxctl-central-debug-log.adoc[leveloffset=+2] + +include::modules/roxctl-central-debug-dump.adoc[leveloffset=+2] + +include::modules/roxctl-central-debug-db-stats.adoc[leveloffset=+2] + +include::modules/roxctl-central-debug-authz-trace.adoc[leveloffset=+2] + +include::modules/roxctl-central-debug-db-stats-reset.adoc[leveloffset=+2] + +include::modules/roxctl-central-debug-download-diagnostics.adoc[leveloffset=+2] + +// /roxctl central generate +include::modules/roxctl-central-generate.adoc[leveloffset=+1] + +include::modules/roxctl-central-generate-k8s.adoc[leveloffset=+2] + +include::modules/roxctl-central-generate-k8s-pvc.adoc[leveloffset=+2] + +include::modules/roxctl-central-generate-openshift.adoc[leveloffset=+2] + +include::modules/roxctl-central-generate-interactive.adoc[leveloffset=+2] + +include::modules/roxctl-central-generate-k8s-hostpath.adoc[leveloffset=+2] + +include::modules/roxctl-central-generate-openshift-pvc.adoc[leveloffset=+2] + +include::modules/roxctl-central-generate-openshift-hostpath.adoc[leveloffset=+2] + +//roxctl central init-bundles +include::modules/roxctl-central-init-bundles.adoc[leveloffset=+1] + +include::modules/roxctl-central-init-bundles-list.adoc[leveloffset=+2] + +include::modules/roxctl-central-init-bundles-revoke.adoc[leveloffset=+2] + +include::modules/roxctl-central-init-bundles-fetch-ca.adoc[leveloffset=+2] + +include::modules/roxctl-central-init-bundles-generate.adoc[leveloffset=+2] + + +//roxctl central userpki +include::modules/roxctl-central-userpki.adoc[leveloffset=+1] + +include::modules/roxctl-central-userpki-list.adoc[leveloffset=+2] + +include::modules/roxctl-central-userpki-create.adoc[leveloffset=+2] + +include::modules/roxctl-central-userpki-delete.adoc[leveloffset=+2] \ No newline at end of file diff --git a/cli/command-reference/roxctl-cluster.adoc b/cli/command-reference/roxctl-cluster.adoc new file mode 100644 index 000000000000..c881f3bb49d1 --- /dev/null +++ b/cli/command-reference/roxctl-cluster.adoc @@ -0,0 +1,45 @@ +[id="roxctl-cluster"] +:_mod-docs-content-type: ASSEMBLY += roxctl cluster +include::modules/common-attributes.adoc[] +:context: roxctl-cluster + +toc::[] + +Commands related to a cluster. + +.Usage +[source,terminal] +---- +$ roxctl cluster [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`delete` +|Remove Sensor from Central. +|=== + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--retry-timeout duration` +|Set the retry timeout for API requests. A value of zero means the full request duration is awaited without retry. The default value is `20s`. + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== + + +//Options inherited from the parent command +:commandname: roxctl cluster +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl cluster delete +include::modules/roxctl-cluster-delete.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli/command-reference/roxctl-collector.adoc b/cli/command-reference/roxctl-collector.adoc new file mode 100644 index 000000000000..ad481c1bddbc --- /dev/null +++ b/cli/command-reference/roxctl-collector.adoc @@ -0,0 +1,34 @@ +[id="roxctl-collector"] +:_mod-docs-content-type: ASSEMBLY += roxctl collector +include::modules/common-attributes.adoc[] +:context: roxctl-collector + +toc::[] + +Commands related to the Collector service. + +.Usage +[source,terminal] +---- +$ roxctl collector [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`support-packages` +| Upload support packages for Collector. +|=== + +//Options inherited from the parent command +:commandname: roxctl collector +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl collector support-packages +include::modules/roxctl-collector-support-packages.adoc[leveloffset=+1] + +include::modules/roxctl-collector-support-packages-upload.adoc[leveloffset=+2] diff --git a/cli/command-reference/roxctl-completion.adoc b/cli/command-reference/roxctl-completion.adoc new file mode 100644 index 000000000000..a2a0651f1dfe --- /dev/null +++ b/cli/command-reference/roxctl-completion.adoc @@ -0,0 +1,38 @@ +[id="roxctl-completion"] +:_mod-docs-content-type: ASSEMBLY += roxctl completion +include::modules/common-attributes.adoc[] +:context: roxctl-completion + +toc::[] + +Generate shell completion scripts. + +.Usage +[source,terminal] +---- +$ roxctl completion [bash|zsh|fish|powershell] +---- + +.Supported shell types +[cols="2,2",options="header"] +|=== +|Shell type |Description + +|`bash` +|Generate a completion script for the Bash shell. + +|`zsh` +|Generate a completion script for the Zsh shell. + +|`fish` +|Generate a completion script for the Fish shell. + +|`powershell` +|Generate a completion script for the PowerShell shell. +|=== + +//Options inherited from the parent command +:commandname: roxctl completion +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: \ No newline at end of file diff --git a/cli/command-reference/roxctl-declarative-config.adoc b/cli/command-reference/roxctl-declarative-config.adoc new file mode 100644 index 000000000000..cd421b41c3e6 --- /dev/null +++ b/cli/command-reference/roxctl-declarative-config.adoc @@ -0,0 +1,62 @@ +[id="roxctl-declarative-config"] +:_mod-docs-content-type: ASSEMBLY += roxctl declarative-config +include::modules/common-attributes.adoc[] +:context: roxctl-declarative-config + +toc::[] + +Manage the declarative configuration. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`create` +|Create declarative configurations. + +|`lint` +| Lint an existing declarative configuration YAML file. +|=== + +//Options inherited from the parent command +:commandname: roxctl declarative-config +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl declarative-config lint +include::modules/roxctl-declarative-config-lint.adoc[leveloffset=+1] + +//roxctl declarative-config create +include::modules/roxctl-declarative-config-create.adoc[leveloffset=+1] + +include::modules/roxctl-declarative-config-create-role.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-notifier.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-access-scope.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-auth-provider.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-permission-set.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-notifier-splunk.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-notifier-generic.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-auth-provider-iap.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-auth-provider-oidc.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-auth-provider-saml.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-auth-provider-userpki.adoc[leveloffset=+2] + +include::modules/roxctl-declarative-config-create-auth-provider-openshift-auth.adoc[leveloffset=+2] \ No newline at end of file diff --git a/cli/command-reference/roxctl-deployment.adoc b/cli/command-reference/roxctl-deployment.adoc new file mode 100644 index 000000000000..1f42954abc80 --- /dev/null +++ b/cli/command-reference/roxctl-deployment.adoc @@ -0,0 +1,42 @@ +[id="roxctl-deployment"] +:_mod-docs-content-type: ASSEMBLY += roxctl deployment +include::modules/common-attributes.adoc[] +:context: roxctl-deployment + +toc::[] + +Commands related to deployments. + +.Usage +[source,terminal] +---- +$ roxctl deployment [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`check` +|Check the deployments for violations of the deployment time policy. +|=== + + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-t`, `--timeout duration` +|Set the timeout for API requests. This option represents the maximum duration of a request. The default value is `10m0s`. +|=== + +//Options inherited from the parent command +:commandname: roxctl deployment +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl deployment check +include::modules/roxctl-deployment-check.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli/command-reference/roxctl-helm.adoc b/cli/command-reference/roxctl-helm.adoc new file mode 100644 index 000000000000..1755332d9f0b --- /dev/null +++ b/cli/command-reference/roxctl-helm.adoc @@ -0,0 +1,38 @@ +[id="roxctl-helm"] +:_mod-docs-content-type: ASSEMBLY += roxctl helm +include::modules/common-attributes.adoc[] +:context: roxctl-helm + +toc::[] + +Commands related to {rh-rhacs-first} Helm Charts. + +.Usage +[source,terminal] +---- +$ roxctl helm [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`derive-local-values` +|Derive local Helm values from the cluster configuration. + +|`output` +|Output a Helm chart. +|=== + +//Options inherited from the parent command +:commandname: roxctl helm +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl helm output +include::modules/roxctl-helm-output.adoc[leveloffset=+1] + +//roxctl helm derive-local-values +include::modules/roxctl-helm-derive-local-values.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli/command-reference/roxctl-image.adoc b/cli/command-reference/roxctl-image.adoc new file mode 100644 index 000000000000..759df73440cd --- /dev/null +++ b/cli/command-reference/roxctl-image.adoc @@ -0,0 +1,53 @@ +[id="roxctl-image"] +:_mod-docs-content-type: ASSEMBLY += roxctl image +include::modules/common-attributes.adoc[] +:context: roxctl-image + +toc::[] + +Commands that you can run on a specific image. + +.Usage +[source,terminal] +---- +$ roxctl image [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`check` +|Check images for build time policy violations, and report them. + +|`sbom` +|Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource. + +|`scan` +|Scan the specified image, and return the scan results. +|=== + + +.Options +[cols="2,2",options="header"] +|=== + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `10m0s`. +|=== + +//Options inherited from the parent command +:commandname: roxctl image +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl image sbom +include::modules/roxctl-image-sbom.adoc[leveloffset=+1] + +//roxctl image scan +include::modules/roxctl-image-scan.adoc[leveloffset=+1] + +//roxctl image check +include::modules/roxctl-image-check.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli/command-reference/roxctl-netpol.adoc b/cli/command-reference/roxctl-netpol.adoc new file mode 100644 index 000000000000..395a1a9f64b5 --- /dev/null +++ b/cli/command-reference/roxctl-netpol.adoc @@ -0,0 +1,42 @@ +[id="roxctl-netpol"] +:_mod-docs-content-type: ASSEMBLY += roxctl netpol +include::modules/common-attributes.adoc[] +:context: roxctl-netpol + +toc::[] + +Commands related to the network policies. + +.Usage +[source,terminal] +---- +$ roxctl netpol [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`connectivity` +|Connectivity analysis of the network policy resources. + +|`generate` +|Recommend network policies based on the deployment information. +|=== + +//Options inherited from the parent command +:commandname: roxctl netpol +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl netpol generate +include::modules/roxctl-netpol-generate.adoc[leveloffset=+1] + +//roxctl netpol connectivity +include::modules/roxctl-netpol-connectivity.adoc[leveloffset=+1] + +include::modules/roxctl-netpol-connectivity-map.adoc[leveloffset=+2] + +include::modules/roxctl-netpol-connectivity-diff.adoc[leveloffset=+2] \ No newline at end of file diff --git a/cli/command-reference/roxctl-scanner.adoc b/cli/command-reference/roxctl-scanner.adoc new file mode 100644 index 000000000000..8a3ffb8487b0 --- /dev/null +++ b/cli/command-reference/roxctl-scanner.adoc @@ -0,0 +1,43 @@ +[id="roxctl-scanner"] +:_mod-docs-content-type: ASSEMBLY += roxctl scanner +include::modules/common-attributes.adoc[] +:context: roxctl-scanner + +toc::[] + +Commands related to the StackRox Scanner and Scanner V4 services. + +.Usage +[source,terminal] +---- +$ roxctl scanner [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`download-db` +| Download the offline vulnerability database for StackRox Scanner and Scanner V4. + +|`generate` +|Generate the required YAML configuration files to deploy the StackRox Scanner and Scanner V4. + +|`upload-db` +|Upload a vulnerability database for the StackRox Scanner and Scanner V4. +|=== + +//Options inherited from the parent command +:commandname: roxctl scanner +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl scanner generate +include::modules/roxctl-scanner-generate.adoc[leveloffset=+1] + +//roxctl scanner upload-db +include::modules/roxctl-scanner-upload-db.adoc[leveloffset=+1] + +include::modules/roxctl-scanner-download-db.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli/command-reference/roxctl-sensor.adoc b/cli/command-reference/roxctl-sensor.adoc new file mode 100644 index 000000000000..1424f5681f64 --- /dev/null +++ b/cli/command-reference/roxctl-sensor.adoc @@ -0,0 +1,61 @@ +[id="roxctl-sensor"] +:_mod-docs-content-type: ASSEMBLY += roxctl sensor +include::modules/common-attributes.adoc[] +:context: roxctl-sensor + +toc::[] + +Deploy {rh-rhacs-first} services in secured clusters. + +.Usage +[source,terminal] +---- +$ roxctl sensor [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`generate` +|Generate files to deploy {product-title-short} services in secured clusters. + +|`generate-certs` +|Download a YAML file with renewed certificates for Sensor, Collector, and Admission controller. + +|`get-bundle` +|Download a bundle with the files to deploy {product-title-short} services in a cluster. +|=== + + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--retry-timeout duration` +|Set the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== + +//Options inherited from the parent command +:commandname: roxctl sensor +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: + +//roxctl sensor generate +include::modules/roxctl-sensor-generate.adoc[leveloffset=+1] + +include::modules/roxctl-sensor-generate-k8s.adoc[leveloffset=+2] + +include::modules/roxctl-sensor-generate-openshift.adoc[leveloffset=+2] + +//roxctl sensor get-bundle +include::modules/roxctl-sensor-get-bundle.adoc[leveloffset=+1] + +//roxctl sensor generate-certs +include::modules/roxctl-sensor-generate-certs.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli/command-reference/roxctl-version.adoc b/cli/command-reference/roxctl-version.adoc new file mode 100644 index 000000000000..9bb3aa00e5bc --- /dev/null +++ b/cli/command-reference/roxctl-version.adoc @@ -0,0 +1,24 @@ +[id="roxctl-version"] +:_mod-docs-content-type: ASSEMBLY += roxctl version +include::modules/common-attributes.adoc[] +:context: roxctl-version + +toc::[] + +Display the current roxctl version. + +.Usage + +[source,terminal] +---- +$ roxctl version [flags] +---- + +//roxctl version command options +include::modules/roxctl-version-command-options.adoc[leveloffset=+1] + +//Options inherited from the parent command +:commandname: roxctl version +include::modules/options-inherited-from-the-parent-command.adoc[leveloffset=+1] +:!commandname: \ No newline at end of file diff --git a/cli/command-reference/roxctl.adoc b/cli/command-reference/roxctl.adoc new file mode 100644 index 000000000000..0399087eba26 --- /dev/null +++ b/cli/command-reference/roxctl.adoc @@ -0,0 +1,60 @@ +[id="roxctl"] +:_mod-docs-content-type: ASSEMBLY += roxctl +include::modules/common-attributes.adoc[] +:context: roxctl + +toc::[] + +Display the available commands and optional parameters for `roxctl` CLI. You must have an account with administrator privileges to use these commands. + +.Usage +[source,terminal] +---- +$ roxctl [command] [flags] +---- + +.Available commands +[cols="2,2",options="header"] +|=== +|Command |Description + +|`central` +|Commands related to the Central service. + +|`cluster` +|Commands related to a cluster. + +|`collector` +|Commands related to the Collector service. + +|`completion` +|Generate shell completion scripts. + +|`declarative-config` +|Manage declarative configuration. + +|`deployment` +|Commands related to deployments. + +|`helm` +|Commands related to {rh-rhacs-first} Helm Charts. + +|`image` +|Commands that you can run on a specific image. + +|`netpol` +|Commands related to network policies. + +|`scanner` +|Commands related to the Scanner service. + +|`sensor` +|Deploy {product-title-short} services in secured clusters. + +|`version` +|Display the current roxctl version. +|=== + +//roxctl command options +include::modules/roxctl-command-options.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli/command-reference/snippets b/cli/command-reference/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/cli/command-reference/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/cli/debugging-issues.adoc b/cli/debugging-issues.adoc new file mode 100644 index 000000000000..3e86697cb7c4 --- /dev/null +++ b/cli/debugging-issues.adoc @@ -0,0 +1,35 @@ +[id="debugging-issues"] +:_mod-docs-content-type: ASSEMBLY += Debugging issues +include::modules/common-attributes.adoc[] +:context: debugging-issues + +toc::[] + +[role="_abstract"] +Central saves information to its container logs. + +include::modules/setting-up-environment-variables.adoc[leveloffset=+1] + +include::modules/viewing-the-logs.adoc[leveloffset=+1] + +include::modules/viewing-current-log-level.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-central.adoc#roxctl-central-debug_roxctl-central[roxctl central debug] + +include::modules/changing-the-log-level.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-central.adoc#roxctl-central-debug_roxctl-central[roxctl central debug] + +include::modules/retrieving-debugging-information.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-central.adoc#roxctl-central-debug_roxctl-central[roxctl central debug] \ No newline at end of file diff --git a/cli/image-scanning-by-using-the-roxctl-cli.adoc b/cli/image-scanning-by-using-the-roxctl-cli.adoc new file mode 100644 index 000000000000..4c8958e0b599 --- /dev/null +++ b/cli/image-scanning-by-using-the-roxctl-cli.adoc @@ -0,0 +1,68 @@ +[id="image-scanning-by-using-the-roxctl-cli"] +:_mod-docs-content-type: ASSEMBLY += Image scanning by using the roxctl CLI +include::modules/common-attributes.adoc[] +:context: image-scanning-by-using-the-roxctl-cli + +toc::[] + +[role="_abstract"] +You can scan images stored in image registries, including cluster local registries such as the {ocp} integrated image registry by using the `roxctl` CLI. + +[id="scanning-images-by-using-a-remote-cluster_{context}"] +== Scanning images by using a remote cluster + +By specifying the appropriate cluster in the delegated scanning configuration or through the cluster parameter described in the following procedure, you can scan images from cluster local registries by using a remote cluster. + +[IMPORTANT] +==== +For more information about how to configure delegated image scanning, see xref:../operating/examine-images-for-vulnerabilities.adoc#accessing-delegated-image-scanning_examine-images-for-vulnerabilities[Accessing delegated image scanning]. +==== + +.Procedure + +* Run the following command to scan the specified image in a remote cluster: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl image scan \ + --image=__/__ \// <1> + --cluster=__ \// <2> + [flags] <3> +---- ++ +-- +<1> For ``, specify the registry where the image is located, for example, `image-registry.openshift-image-registry.svc:5000/`. +For ``, specify the name of the image you want to scan, for example, `default/image-stream:latest`. +<2> For ``, specify the name or ID of the remote cluster. For example, specify the name `remote`. +<3> Optional: For `[flags]`, you can specify parameters to modify the behavior of the command. ++ +For more information about optional parameters, see xref:../cli/image-scanning-by-using-the-roxctl-cli.adoc#roxctl-image-scan-command-options_image-scanning-by-using-the-roxctl-cli[roxctl image scan command options]. +-- ++ +.Example output ++ +[source,text,subs=attributes+] +---- +{ + "Id": "sha256:3f439d7d71adb0a0c8e05257c091236ab00c6343bc44388d091450ff58664bf9", <1> + "name": { <2> + "registry": "image-registry.openshift-image-registry.svc:5000", <3> + "remote": "default/image-stream", <4> + "tag": "latest", <5> + "fullName": "image-registry.openshift-image-registry.svc:5000/default/image-stream:latest" <6> + }, +[...] +---- ++ +-- +<1> A unique identifier for the image that serves as a fingerprint for the image. It helps ensure the integrity and authenticity of the image. +<2> Contains specific details about the image. +<3> The location of the image registry where the image is stored. +<4> The remote path to the image. +<5> The version or tag associated with this image. +<6> The complete name of the image, combining the registry, remote path, and tag. +-- + +//roxctl image scan command options +include::modules/roxctl-image-scan-command-options.adoc[leveloffset=+1] \ No newline at end of file diff --git a/jaeger/jaeger_arch/images b/cli/images similarity index 100% rename from jaeger/jaeger_arch/images rename to cli/images diff --git a/cli/installing-the-roxctl-cli.adoc b/cli/installing-the-roxctl-cli.adoc new file mode 100644 index 000000000000..877da625a960 --- /dev/null +++ b/cli/installing-the-roxctl-cli.adoc @@ -0,0 +1,27 @@ +[id="installing-the-roxctl-cli"] +:_mod-docs-content-type: ASSEMBLY += Installing the roxctl CLI +include::modules/common-attributes.adoc[] +:context: installing-roxctl-cli + +toc::[] + +[role="_abstract"] +`roxctl` is a command-line interface (CLI) for running commands on {rh-rhacs-first}. +You can install the `roxctl` CLI by downloading the binary or you can run the `roxctl` CLI from a container image. + + +[id="installing-the-roxctl-cli-by-downloading-the-binary_{context}"] +== Installing the roxctl CLI by downloading the binary + +You can install the `roxctl` CLI to interact with {product-title-short} from a command-line interface. You can install `roxctl` on Linux, Windows, or macOS. + +// Installing the CLI by downloading the binary +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+2] + +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+2] + +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+2] + +// Running the CLI by using a container image +include::modules/run-roxctl-from-container.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli/managing-secured-clusters.adoc b/cli/managing-secured-clusters.adoc new file mode 100644 index 000000000000..808fc0e3ef75 --- /dev/null +++ b/cli/managing-secured-clusters.adoc @@ -0,0 +1,20 @@ +[id="managing-secured-clusters"] +:_mod-docs-content-type: ASSEMBLY += Managing secured clusters +include::modules/common-attributes.adoc[] +:context: managing-secured-clusters + +toc::[] + +[role="_abstract"] +To secure a Kubernetes or an {ocp} cluster, you must deploy {rh-rhacs-first} services into the cluster. You can generate deployment files in the {product-title-short} portal by navigating to the *Platform Configuration -> Clusters* view, or you can use the `roxctl` CLI. + +include::modules/setting-up-environment-variables.adoc[leveloffset=+1] + +include::modules/generating-sensor-deployment-files.adoc[leveloffset=+1] + +include::modules/installing-sensor-by-using-the-generate-yaml-files.adoc[leveloffset=+1] + +include::modules/downloading-sensor-bundle-for-existing-clusters.adoc[leveloffset=+1] + +include::modules/deleting-cluster-integration.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cloud_providers/modules b/cli/modules similarity index 100% rename from cloud_providers/modules rename to cli/modules diff --git a/cli/snippets b/cli/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/cli/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/cli/using-the-roxctl-cli.adoc b/cli/using-the-roxctl-cli.adoc new file mode 100644 index 000000000000..5da04590635c --- /dev/null +++ b/cli/using-the-roxctl-cli.adoc @@ -0,0 +1,95 @@ +[id="using-the-roxctl-cli"] +:_mod-docs-content-type: ASSEMBLY += Using the roxctl CLI +include::modules/common-attributes.adoc[] +:context: using-roxctl-cli + +toc::[] + +include::modules/setting-up-environment-variables.adoc[leveloffset=+1] + +[id="getting-authentication-information_{context}"] +== Getting authentication information + +The following procedure describes how to use the `roxctl central whoami` command to retrieve information about your authentication status and user profile in Central. The example output illustrates the data you can expect to see, including user roles, access permissions, and various administrative functions. This step allows you to review your access and roles within Central. + +.Procedure + +* Run the following command to get information about your current authentication status and user information in Central: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl central whoami +---- ++ +.Example output ++ +[source,terminal,subs="+quotes"] +---- +UserID: + +User name: + +Roles: + APIToken creator, Admin, Analyst, Continuous Integration, Network Graph Viewer, None, Sensor Creator, Vulnerability Management Approver, Vulnerability Management Requester, Vulnerability Manager, Vulnerability Report Creator +Access: + rw Access + rw Administration + rw Alert + rw CVE + rw Cluster + rw Compliance + rw Deployment + rw DeploymentExtension + rw Detection + rw Image + rw Integration + rw K8sRole + rw K8sRoleBinding + rw K8sSubject + rw Namespace + rw NetworkGraph + rw NetworkPolicy + rw Node + rw Secret + rw ServiceAccount + rw VulnerabilityManagementApprovals + rw VulnerabilityManagementRequests + rw WatchedImage + rw WorkflowAdministration +---- ++ +Review the output to ensure that the authentication and user details are as expected. + +[id="authenticating-by-using-the-roxctl-cli_{context}"] +== Authenticating by using the roxctl CLI + +For authentication, you can use an API token, your administrator password, or the `roxctl central login` command. + +Follow these guidelines for the effective use of API tokens: + +* Use an API token in a production environment with continuous integration (CI). Each token is assigned specific access permissions, providing control over the actions it can perform. In addition, API tokens do not require interactive processes, such as browser-based logins, making them ideal for automated processes. These tokens have a time-to-live (TTL) value of 1 year, providing a longer validity period for seamless integration and operational efficiency. + +* Use your administrator password only for testing purposes. Do not use it in the production environment. + +* Use the `roxctl central login` command only for interactive, local uses. + +include::snippets/note-about-creating-tokens.adoc[] + +[role="_additional-resources"] +.Additional resources +* link:https://github.com/stackrox/contributions/blob/main/guides/cloud-provider-integrations/azure-service-principal-m2m-auth.md[Using Azure Entra ID service principals for machine to machine auth with RHACS] +* xref:../configuration/configure-api-token.adoc[Configuring API tokens] +* xref:../operating/manage-user-access/configure-short-lived-access.adoc#configure-short-lived-access[Configuring short-lived access] + +//Creating an API token +include::modules/create-api-token.adoc[leveloffset=+2] + +//Exporting and saving the API token +include::modules/cli-authentication.adoc[leveloffset=+2] + +//Using an authentication provider to authenticate with roxctl +include::modules/using-an-authentication-provider-to-authenticate-with-roxctl.adoc[leveloffset=+2] + +//Configuring and using the roxctl CLI in {product-title-managed-short} +include::modules/configuring-and-using-the-roxctl-cli-in-rhacs-cloud-service.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli_reference/developer_cli_odo/configuring-the-odo-cli.adoc b/cli_reference/developer_cli_odo/configuring-the-odo-cli.adoc deleted file mode 100644 index 75e50434fa96..000000000000 --- a/cli_reference/developer_cli_odo/configuring-the-odo-cli.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id='configuring-the-odo-cli'] -= Configuring the odo CLI -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: configuring-the-odo-cli - -toc::[] - -include::modules/developer-cli-odo-using-command-completion.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-ignoring-files-or-patterns.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating-instances-of-services-managed-by-operators.adoc b/cli_reference/developer_cli_odo/creating-instances-of-services-managed-by-operators.adoc deleted file mode 100644 index 7329406a0cf1..000000000000 --- a/cli_reference/developer_cli_odo/creating-instances-of-services-managed-by-operators.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id=creating-instances-of-services-managed-by-operators] -= Creating instances of services managed by Operators -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: creating-instances-of-services-managed-by-operators - -toc::[] - -Operators are a method of packaging, deploying, and managing Kubernetes services. With `{odo-title}`, you can create instances of services from the custom resource definitions (CRDs) provided by the Operators. You can then use these instances in your projects and link them to your components. - -To create services from an Operator, you must ensure that the Operator has valid values defined in its `metadata` to start the requested service. `{odo-title}` uses the `metadata.annotations.alm-examples` YAML file of an Operator to start -the service. If this YAML has placeholder values or sample values, a service cannot start. You can modify the YAML file and start the service with the modified values. To learn how to modify YAML files and start services from it, see xref:../../cli_reference/developer_cli_odo/creating-instances-of-services-managed-by-operators.adoc#creating-services-from-yaml-files_creating-instances-of-services-managed-by-operators[Creating services from YAML files]. - -== Prerequisites -* Install the `oc` CLI and log into the cluster. -** Note that the configuration of the cluster determines the services available to you. To access the Operator services, a cluster administrator must install the respective Operator on the cluster first. To learn more, see xref:../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-installing-operators-from-operatorhub_olm-adding-operators-to-a-cluster[Adding Operators to the cluster]. -* Install the `{odo-title}` CLI. - -include::modules/developer-cli-odo-creating-a-project.adoc[leveloffset=+1] -include::modules/developer-cli-odo-listing-available-services-from-the-operators-installed-on-the-cluster.adoc[leveloffset=+1] -include::modules/developer-cli-odo-creating-a-service-from-an-operator.adoc[leveloffset=+1] -include::modules/developer-cli-odo-creating-services-from-yaml-files.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-java-application-with-a-database.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-java-application-with-a-database.adoc deleted file mode 100644 index a749ab79b6be..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-java-application-with-a-database.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id=creating-a-java-application-with-a-database] -= Creating a Java application with a database -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: creating-a-java-application-with-a-database -toc::[] - -This example describes how to deploy a Java application by using devfile and connect it to a database service. - -.Prerequisites - -* A running cluster. -* `{odo-title}` is installed. -* A Service Binding Operator is installed in your cluster. To learn how to install Operators, contact your cluster administrator or see xref:../../../operators/user/olm-installing-operators-in-namespace.adoc#olm-installing-operators-from-operatorhub_olm-installing-operators-in-namespace[Installing Operators from OperatorHub]. -* A Dev4Devs PostgreSQL Operator Operator is installed in your cluster. To learn how to install Operators, contact your cluster administrator or see xref:../../../operators/user/olm-installing-operators-in-namespace.adoc#olm-installing-operators-from-operatorhub_olm-installing-operators-in-namespace[Installing Operators from OperatorHub]. - -include::modules/developer-cli-odo-creating-a-project.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-creating-a-database-with-odo.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-multicomponent-application-with-odo.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-multicomponent-application-with-odo.adoc deleted file mode 100644 index f478042a53e1..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-multicomponent-application-with-odo.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id='creating-a-multicomponent-application-with-odo'] -= Creating a multicomponent application with `{odo-title}` -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: creating-a-multicomponent-application-with-odo - -toc::[] - -`{odo-title}` allows you to create a multicomponent application, modify it, and link its components in an easy and automated way. - -This example describes how to deploy a multicomponent application - a shooter game. The application consists of a front-end Node.js component and a back-end Java component. - -.Prerequisites - -* `{odo-title}` is installed. -* You have a running cluster. Developers can use link:https://access.redhat.com/documentation/en-us/red_hat_codeready_containers/[CodeReady Containers (CRC)] to deploy a local cluster quickly. -* Maven is installed. - -include::modules/developer-cli-odo-creating-a-project.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-deploying-the-back-end-component.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-deploying-the-front-end-component.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-linking-both-components.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-exposing-the-components-to-the-public.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-modifying-the-running-application.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-deleting-an-application.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-single-component-application-with-odo.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-single-component-application-with-odo.adoc deleted file mode 100644 index 6add327b800a..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-single-component-application-with-odo.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id='creating-a-single-component-application-with-odo'] -= Creating a single-component application with `{odo-title}` -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: creating-a-single-component-application-with-odo - -toc::[] - -With `{odo-title}`, you can create and deploy applications on clusters. - -.Prerequisites - -* `{odo-title}` is installed. -* You have a running cluster. You can use link:https://access.redhat.com/documentation/en-us/red_hat_codeready_containers/[CodeReady Containers (CRC)] to deploy a local cluster quickly. - -include::modules/developer-cli-odo-creating-a-project.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-creating-and-deploying-a-nodejs-application-with-odo.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-modifying-your-application-code.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-adding-storage-to-the-application-components.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-adding-a-custom-builder-to-specify-a-build-image.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-connecting-your-application-to-multiple-services-using-openshift-service-catalog.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-deleting-an-application.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc deleted file mode 100644 index 9ae14e7e0cd6..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id=creating-an-application-with-a-database] -= Creating an application with a database -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: creating-an-application-with-a-database - -toc::[] - -This example describes how to deploy and connect a database to a front-end application. - -.Prerequisites - -* `{odo-title}` is installed. -* `oc` client is installed. -* You have a running cluster. Developers can use link:https://access.redhat.com/documentation/en-us/red_hat_codeready_containers/[CodeReady Containers (CRC)] to deploy a local cluster quickly. -* The Service Catalog is installed and enabled on your cluster. -+ -[NOTE] -==== -Service Catalog is deprecated on {product-title} 4 and later. -==== - -include::modules/developer-cli-odo-creating-a-project.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-deploying-the-front-end-component.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-deploying-a-database-in-interactive-mode.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-deploying-a-database-manually.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-connecting-the-database.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/debugging-applications-in-odo.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/debugging-applications-in-odo.adoc deleted file mode 100644 index f56d8c1dceb7..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/debugging-applications-in-odo.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id='debugging-applications-in-odo'] -= Debugging applications in `{odo-title}` -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: debugging-applications-in-odo - -toc::[] - -With `{odo-title}`, you can attach a debugger to remotely debug your application. This feature is only supported for NodeJS and Java components. - -Components created with `{odo-title}` run in the debug mode by default. A debugger agent runs on the component, on a specific port. To start debugging your application, you must start port forwarding and attach the local debugger bundled in your Integrated development environment (IDE). - -include::modules/developer-cli-odo-debugging-an-application.adoc[leveloffset=+1] -include::modules/developer-cli-odo-configuring-debugging-parameters.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/deleting-applications.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/deleting-applications.adoc deleted file mode 100644 index ac0d5bbbc737..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/deleting-applications.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id='deleting-applications'] -= Deleting applications -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: deleting-applications - -toc::[] - -You can delete applications and all components associated with the application in your project. - -include::modules/developer-cli-odo-deleting-an-application.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/modules b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/modules deleted file mode 120000 index 5be29a99c161..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/modules +++ /dev/null @@ -1 +0,0 @@ -../../../modules \ No newline at end of file diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/sample-applications.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/sample-applications.adoc deleted file mode 100644 index 8aa0b60d7891..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/sample-applications.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="sample-applications"] -= Sample applications -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: using-sample-applications - -toc::[] - -`{odo-title}` offers partial compatibility with any language or runtime listed within the OpenShift catalog of component types. For example: - -[source,terminal] ----- -NAME PROJECT TAGS -dotnet openshift 2.0,latest -httpd openshift 2.4,latest -java openshift 8,latest -nginx openshift 1.10,1.12,1.8,latest -nodejs openshift 0.10,4,6,8,latest -perl openshift 5.16,5.20,5.24,latest -php openshift 5.5,5.6,7.0,7.1,latest -python openshift 2.7,3.3,3.4,3.5,3.6,latest -ruby openshift 2.0,2.2,2.3,2.4,latest -wildfly openshift 10.0,10.1,8.1,9.0,latest ----- - -[NOTE] -==== -For `{odo-title}` Java and Node.js are the officially supported component types. -Run `odo catalog list components` to verify the officially supported component types. -==== - -To access the component over the web, create a URL using `odo url create`. - - - -include::modules/developer-cli-odo-sample-applications.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/using-devfiles-in-odo.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/using-devfiles-in-odo.adoc deleted file mode 100644 index 9e3a6e8a1d1f..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/using-devfiles-in-odo.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="using-devfiles-in-odo"] -= Using devfiles in {odo-title} -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: creating-applications-by-using-devfiles - -toc::[] - -include::modules/developer-cli-odo-about-devfiles-in-odo.adoc[leveloffset=+1] - -== Creating a Java application by using a devfile - -.Prerequisites - -* You have installed `{odo-title}`. -* You must know your ingress domain cluster name. Contact your cluster administrator if you do not know it. For example, `apps-crc.testing` is the cluster domain name for https://access.redhat.com/documentation/en-us/red_hat_codeready_containers/[Red Hat CodeReady Containers]. - -include::modules/developer-cli-odo-creating-a-project.adoc[leveloffset=+2] - -include::modules/developer-cli-odo-listing-available-devfile-components.adoc[leveloffset=+2] - -include::modules/developer-cli-odo-deploying-a-java-application-using-a-devfile.adoc[leveloffset=+2] - -include::modules/developer-cli-odo-converting-an-s2i-component-into-a-devfile-component.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-projects.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-projects.adoc deleted file mode 100644 index 68dbbee3a2ed..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-projects.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="working-with-projects"] -= Working with projects -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: working-with-projects - -toc::[] - -Project keeps your source code, tests, and libraries organized in a separate single unit. - -include::modules/developer-cli-odo-creating-a-project.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-storage.adoc b/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-storage.adoc deleted file mode 100644 index fe6bd2f3d94e..000000000000 --- a/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-storage.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id='working-with-storage'] -= Working with storage -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: working-with-storage - -toc::[] - -Persistent storage keeps data available between restarts of `{odo-title}`. - -include::modules/developer-cli-odo-adding-storage-to-the-application-components.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-switching-between-ephemeral-and-persistent-storage.adoc[leveloffset=+1] - -.Additional resources - -* xref:../../../storage/understanding-ephemeral-storage.adoc#storage-ephemeral-storage-overview_understanding-ephemeral-storage[Understanding ephemeral storage]. -* xref:../../../storage/understanding-persistent-storage.adoc#persistent-storage-overview_understanding-persistent-storage[Understanding persistent storage] diff --git a/cli_reference/developer_cli_odo/installing-odo.adoc b/cli_reference/developer_cli_odo/installing-odo.adoc deleted file mode 100644 index 35cd184ba09a..000000000000 --- a/cli_reference/developer_cli_odo/installing-odo.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id='installing-odo'] -= Installing odo -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: installing-odo - -toc::[] - -The following section describes how to install `{odo-title}` on different platforms using the CLI or the Visual Studio Code (VS Code) IDE. - -[NOTE] -==== -Currently, `{odo-title}` does not support installation in a restricted network environment. -==== - -You can also find the URL to the latest binaries from the {product-title} web console by clicking the *?* icon in the upper-right corner and selecting *Command Line Tools* - -include::modules/developer-cli-odo-installing-odo-on-linux.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-installing-odo-on-linux-on-ibm-power.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-installing-odo-on-linux-on-ibm-z.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-installing-odo-on-windows.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-installing-odo-on-macos.adoc[leveloffset=+1] - -include::modules/developer-cli-odo-installing-odo-on-vs-code.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/managing-environment-variables-in-odo.adoc b/cli_reference/developer_cli_odo/managing-environment-variables-in-odo.adoc deleted file mode 100644 index 8c387876a73b..000000000000 --- a/cli_reference/developer_cli_odo/managing-environment-variables-in-odo.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id='managing-environment-variables'] -= Managing environment variables -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: managing-environment-variables - -toc::[] - -`{odo-title}` stores component-specific configurations and environment variables in the `config` file. You can use the `odo config` command to set, unset, and list environment variables for components without the need to modify the `config` file. - -include::modules/developer-cli-odo-setting-and-unsetting-environment-variables.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/odo-architecture.adoc b/cli_reference/developer_cli_odo/odo-architecture.adoc deleted file mode 100644 index abe36a126cb2..000000000000 --- a/cli_reference/developer_cli_odo/odo-architecture.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="odo-architecture"] -= odo architecture -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: odo-architecture - -toc::[] - -This section describes `{odo-title}` architecture and how `{odo-title}` manages resources on a cluster. - -include::modules/developer-cli-odo-developer-setup.adoc[leveloffset=+1] -include::modules/developer-cli-odo-openshift-source-to-image.adoc[leveloffset=+1] -include::modules/developer-cli-odo-openshift-cluster-objects.adoc[leveloffset=+1] -include::modules/developer-cli-odo-push-workflow.adoc[leveloffset=+1] - -// == Additional resources diff --git a/cli_reference/developer_cli_odo/odo-cli-reference.adoc b/cli_reference/developer_cli_odo/odo-cli-reference.adoc deleted file mode 100644 index a155f753f15a..000000000000 --- a/cli_reference/developer_cli_odo/odo-cli-reference.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id='odo-cli-reference'] -= odo CLI reference -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: odo-cli-reference - -toc::[] - -include::modules/developer-cli-odo-basic-odo-cli-commands.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/odo-release-notes.adoc b/cli_reference/developer_cli_odo/odo-release-notes.adoc deleted file mode 100644 index 9a640280fb85..000000000000 --- a/cli_reference/developer_cli_odo/odo-release-notes.adoc +++ /dev/null @@ -1,72 +0,0 @@ -[id='odo-release-notes'] -= `{odo-title}` release notes -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: odo-release-notes - -toc::[] - -[id="odo-notable-improvements_{context}"] -== Notable changes and improvements in `{odo-title}` - -* `{odo-title}` integration with devfiles is no longer a Technology Preview feature and is now fully supported. To learn more, see xref:../../cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/using-devfiles-in-odo.adoc#creating-a-java-application-by-using-a-devfile[Creating applications by using devfiles]. - -* The default deployment mechanism in `{odo-title}` is the devfile deployment now. - -* Added documentation about converting S2I to devfile. See xref:../../cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/using-devfiles-in-odo.adoc#converting-an-s2i-component-into-a-devfile-component_creating-applications-by-using-devfiles[Converting an S2I component into a devfile component]. - -* Added commands to display JSON output for devfile components. - -* `odo debug` is no longer a Technology Preview feature and is now fully supported. -To learn more, see xref:../../cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/debugging-applications-in-odo.html#debugging-an-application_debugging-applications-in-odo[Debugging applications in odo]. - -* `{odo-title}` integration with Operators is no longer a Technology Preview feature and is now fully supported. To learn more, see xref:../../cli_reference/developer_cli_odo/creating-instances-of-services-managed-by-operators.adoc[Creating instances of services managed by Operators]. - -* `{odo-title}` now supports IBM Z. - -* Improved and enhanced output for many commands. - -[id="odo-getting-support_{context}"] -== Getting support - -.For Documentation - -If you find an error or have suggestions for improving the documentation, file an issue in link:http://bugzilla.redhat.com[Bugzilla]. Choose the *{product-title}* product type and the *Documentation* component type. - -.For Product - -If you find an error, encounter a bug, or have suggestions for improving the functionality of `{odo-title}`, file an issue in link:http://bugzilla.redhat.com[Bugzilla]. Choose the *Red Hat {odo-title} for {product-title}* product type. - -Provide as many details in the issue description as possible. - -//// -[id="odo-fixed-issues_{context}"] -== Fixed issues -//// - -[id="odo-known-issues_{context}"] -== Known issues - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1760574[Bug 1760574] A deleted namespace is listed in the `odo project get` command. - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1760586[Bug 1760586] The `odo delete` command starts an infinite loop after a project is deleted and a component name is set. - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1760588[Bug 1760588] The `odo service create` command crashes when run in Cygwin. - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1760590[Bug 1760590] In Git BASH for Windows, the `odo login -u developer` command does not hide a typed password when requested. - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1783188[Bug 1783188] In a disconnected cluster, the `odo component create` command throws an error `...tag not found...` despite the component being listed in the catalog list. - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1761440[Bug 1761440] It is not possible to create two Services of the same type in one project. - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1821643[Bug 1821643] `odo push` does not work on the .NET component tag 2.1+. -+ -Workaround: specify your .NET project file by running: -+ -[source,terminal] ----- -$ odo config set --env DOTNET_STARTUP_PROJECT= ----- - -//[id="odo-technology-preview_{context}"] -//== Technology Preview features `{odo-title}` diff --git a/cli_reference/developer_cli_odo/understanding-odo.adoc b/cli_reference/developer_cli_odo/understanding-odo.adoc deleted file mode 100644 index 37786b9af133..000000000000 --- a/cli_reference/developer_cli_odo/understanding-odo.adoc +++ /dev/null @@ -1,125 +0,0 @@ -[id="understanding-odo"] -= Understanding `odo` -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: understanding-odo - -toc::[] - -`{odo-title}` is a CLI tool for creating applications on {product-title} and Kubernetes. With `{odo-title}`, you can write, build, and debug applications on a cluster without the need to administer the cluster itself. -Creating deployment configurations, build configurations, service routes and other {product-title} or Kubernetes elements are all automated by `{odo-title}`. - -Existing tools such as xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-about-cli_cli-developer-commands[`oc`] are operations-focused and require a deep understanding of Kubernetes and {product-title} concepts. `{odo-title}` abstracts away complex Kubernetes and {product-title} concepts allowing developers to focus on what is most important to them: code. - -[id="odo-key-features"] -== Key features - -`{odo-title}` is designed to be simple and concise with the following key features: - -* Simple syntax and design centered around concepts familiar to developers, such as projects, applications, and components. -* Completely client based. No additional server other than {product-title} is required for deployment. -* Official support for Node.js and Java components. -* Partial compatibility with languages and frameworks such as Ruby, Perl, PHP, and Python. -* Detects changes to local code and deploys it to the cluster automatically, giving instant feedback to validate changes in real time. -* Lists all the available components and services from the cluster. - -== Core concepts - -Project:: -A project is your source code, tests, and libraries organized in a separate single unit. -Application:: -An application is a program designed for end users. An application consists of multiple microservices or components that work individually to build the entire application. -Examples of applications: a video game, a media player, a web browser. -Component:: -A component is a set of Kubernetes resources which host code or data. Each component can be run and deployed separately. -Examples of components: Node.js, Perl, PHP, Python, Ruby. -Service:: -A service is software that your component links to or depends on. -Examples of services: MariaDB, Jenkins, MySQL. -In `{odo-title}`, services are provisioned from the OpenShift Service Catalog and must be enabled within your cluster. - -[id="odo-supported-languages-and-images"] -=== Officially supported languages and corresponding container images - -.Supported languages, container images, package managers, and platforms -[options="header"] -|=== -|Language |Container image |Package manager |Platform -|*Node.js* -|https://access.redhat.com/containers/#/registry.access.redhat.com/rhscl/nodejs-10-rhel7[rhscl/nodejs-10-rhel7] -|NPM -|amd64, s390x, ppc64le - -| -|https://access.redhat.com/containers/#/registry.access.redhat.com/rhscl/nodejs-12-rhel7[rhscl/nodejs-12-rhel7] -|NPM -|amd64, s390x, ppc64le - -|*Java* -|https://access.redhat.com/containers/#/registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift[redhat-openjdk-18/openjdk18-openshift] -|Maven, Gradle -|amd64, s390x, ppc64le - -| -|https://access.redhat.com/containers/#/registry.access.redhat.com/openjdk/openjdk-11-rhel8[openjdk/openjdk-11-rhel8] -|Maven, Gradle -|amd64, s390x, ppc64le - -| -|https://access.redhat.com/containers/#/registry.access.redhat.com/openjdk/openjdk-11-rhel7[openjdk/openjdk-11-rhel7] -|Maven, Gradle -|amd64, s390x, ppc64le -|=== - -[id="odo-listing-available-images"] -==== Listing available container images - -[NOTE] -==== -The list of available container images is sourced from the cluster's internal container registry and external registries associated with the cluster. -==== - -To list the available components and associated container images for your cluster: - -. Log in to the cluster with `{odo-title}`: -+ -[source,terminal] ----- -$ odo login -u developer -p developer ----- - -. List the available `{odo-title}` supported and unsupported components and corresponding container images: -+ -[source,terminal] ----- -$ odo catalog list components ----- -+ -.Example output -[source,terminal] ----- -Odo Devfile Components: -NAME DESCRIPTION REGISTRY -java-maven Upstream Maven and OpenJDK 11 DefaultDevfileRegistry -java-openliberty Open Liberty microservice in Java DefaultDevfileRegistry -java-quarkus Upstream Quarkus with Java+GraalVM DefaultDevfileRegistry -java-springboot Spring Boot® using Java DefaultDevfileRegistry -nodejs Stack with NodeJS 12 DefaultDevfileRegistry - -Odo OpenShift Components: -NAME PROJECT TAGS SUPPORTED -java openshift 11,8,latest YES -dotnet openshift 2.1,3.1,latest NO -golang openshift 1.13.4-ubi7,1.13.4-ubi8,latest NO -httpd openshift 2.4-el7,2.4-el8,latest NO -nginx openshift 1.14-el7,1.14-el8,1.16-el7,1.16-el8,latest NO -nodejs openshift 10-ubi7,10-ubi8,12-ubi7,12-ubi8,latest NO -perl openshift 5.26-el7,5.26-ubi8,5.30-el7,latest NO -php openshift 7.2-ubi7,7.2-ubi8,7.3-ubi7,7.3-ubi8,latest NO -python openshift 2.7-ubi7,2.7-ubi8,3.6-ubi7,3.6-ubi8,3.8-ubi7,3.8-ubi8,latest NO -ruby openshift 2.5-ubi7,2.5-ubi8,2.6-ubi7,2.6-ubi8,2.7-ubi7,latest NO -wildfly openshift 10.0,10.1,11.0,12.0,13.0,14.0,15.0,16.0,17.0,18.0,19.0,20.0,8.1,9.0,latest NO ----- -+ -The `TAGS` column represents the available image versions, for example, `10` represents the `rhoar-nodejs/nodejs-10` container image. -To learn more about CLI commands, go to xref:../../cli_reference/developer_cli_odo/odo-cli-reference.adoc#basic-odo-cli-commands_odo-cli-reference[odo CLI reference]. diff --git a/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/about-odo-in-a-restricted-environment.adoc b/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/about-odo-in-a-restricted-environment.adoc deleted file mode 100644 index 8cf47ff11fd9..000000000000 --- a/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/about-odo-in-a-restricted-environment.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="about-odo-in-a-restricted-environment"] -= About {odo-title} in a restricted environment -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: about-odo-in-a-restricted-environment - -toc::[] - - -To run `{odo-title}` in a disconnected cluster or a cluster provisioned in a restricted environment, you must ensure that a cluster administrator has created a cluster with a mirrored registry. - - -To start working in a disconnected cluster, you must first xref:../../../cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/pushing-the-odo-init-image-to-the-restricted-cluster-registry.adoc#pushing-the-odo-init-image-to-a-mirror-registry_pushing-the-odo-init-image-to-the-restricted-cluster-registry[push the `odo` init image to the registry of the cluster] and then overwrite the `odo` init image path using the `ODO_BOOTSTRAPPER_IMAGE` environment variable. - - -After you push the `odo` init image, you must xref:../../../cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster.adoc#mirroring-a-supported-builder-image_creating-and-deploying-a-component-to-the-disconnected-cluster[mirror a supported builder image] from the registry, xref:../../../cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster.adoc#overwriting-the-mirror-registry_creating-and-deploying-a-component-to-the-disconnected-cluster[overwrite a mirror registry] and then xref:../../../cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster.adoc#creating-a-nodejs-application-with-odo_creating-and-deploying-a-component-to-the-disconnected-cluster[create your application]. A builder image is necessary to configure a runtime environment for your application and also contains the build tool needed to build your application, for example npm for Node.js or Maven for Java. A mirror registry contains all the necessary dependencies for your application. - -.Additional resources -ifdef::openshift-enterprise,openshift-webscale[] -* xref:../../../installing/install_config/installing-restricted-networks-preparations.adoc#installation-about-mirror-registry_installing-restricted-networks-preparations[Creating a mirror registry for installation in a restricted network] -endif::[] -* xref:../../../registry/accessing-the-registry.adoc#registry-accessing-directly_accessing-the-registry[Accessing the registry] diff --git a/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster.adoc b/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster.adoc deleted file mode 100644 index e9fd7242c6e6..000000000000 --- a/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="creating-and-deploying-a-component-to-the-disconnected-cluster"] -= Creating and deploying a component to the disconnected cluster -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: creating-and-deploying-a-component-to-the-disconnected-cluster - -toc::[] - -After you push the `init` image to a cluster with a mirrored registry, you must mirror a supported builder image for your application with the `oc` tool, overwrite the mirror registry using the environment variable, and then create your component. - -== Prerequisites - -* Install `oc` on the client operating system. -* xref:../../../cli_reference/developer_cli_odo/installing-odo.adoc#installing-odo-on-linux_installing-odo[Install `{odo-title}`] on the client operating system. -* Access to an restricted cluster with a configured internal registry or a mirror registry. -* xref:../../../cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/pushing-the-odo-init-image-to-the-restricted-cluster-registry.adoc#pushing-the-odo-init-image-to-a-mirror-registry_pushing-the-odo-init-image-to-the-restricted-cluster-registry[Push the `odo` init image to your cluster registry]. - -include::modules/developer-cli-odo-mirroring-a-supported-builder-image.adoc[leveloffset=+1] -include::modules/developer-cli-odo-overwriting-a-mirror-registry.adoc[leveloffset=+1] -include::modules/developer-cli-odo-creating-and-deploying-a-nodejs-application-with-odo.adoc[leveloffset=+1] diff --git a/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/modules b/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/modules deleted file mode 120000 index 7e8b50bee77a..000000000000 --- a/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/modules +++ /dev/null @@ -1 +0,0 @@ -../../../modules/ \ No newline at end of file diff --git a/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/pushing-the-odo-init-image-to-the-restricted-cluster-registry.adoc b/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/pushing-the-odo-init-image-to-the-restricted-cluster-registry.adoc deleted file mode 100644 index d35c93c54eca..000000000000 --- a/cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/pushing-the-odo-init-image-to-the-restricted-cluster-registry.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="pushing-the-odo-init-image-to-the-restricted-cluster-registry"] -= Pushing the {odo-title} init image to the restricted cluster registry -include::modules/developer-cli-odo-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: pushing-the-odo-init-image-to-the-restricted-cluster-registry - -toc::[] - -Depending on the configuration of your cluster and your operating system you can either push the `odo` init image to a mirror registry or directly to an internal registry. - -== Prerequisites - -* Install `oc` on the client operating system. -* xref:../../../cli_reference/developer_cli_odo/installing-odo.adoc#installing-odo-on-linux_installing-odo[Install `{odo-title}`] on the client operating system. -* Access to a restricted cluster with a configured internal registry or a mirror registry. - -include::modules/developer-cli-odo-pushing-the-odo-init-image-to-a-mirror-registry.adoc[leveloffset=+1] -include::modules/developer-cli-odo-pushing-the-odo-init-image-to-an-internal-registry-directly.adoc[leveloffset=+1] diff --git a/cli_reference/helm_cli/configuring-custom-helm-chart-repositories.adoc b/cli_reference/helm_cli/configuring-custom-helm-chart-repositories.adoc deleted file mode 100644 index 9fa19b7044d8..000000000000 --- a/cli_reference/helm_cli/configuring-custom-helm-chart-repositories.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="configuring-custom-helm-chart-repositories"] - -= Configuring custom Helm chart repositories -include::modules/common-attributes.adoc[] -:context: configuring-custom-helm-chart-repositories - -toc::[] - -The *Developer Catalog*, in the *Developer* perspective of the web console, displays the Helm charts available in the cluster. By default, it lists the Helm charts from the Red Hat Helm chart repository. For a list of the charts see link:https://redhat-developer.github.io/redhat-helm-charts/index.yaml[the Red Hat `Helm index` file]. - -As a cluster administrator, you can add multiple Helm chart repositories, apart from the default one, and display the Helm charts from these repositories in the *Developer Catalog*. - - -include::modules/helm-adding-helm-chart-repositories.adoc[leveloffset=+1] - -include::modules/helm-creating-credentials-and-certificates-to-add-helm-repositories.adoc[leveloffset=+1] diff --git a/cli_reference/helm_cli/disabling-helm-chart-repositories.adoc b/cli_reference/helm_cli/disabling-helm-chart-repositories.adoc deleted file mode 100644 index f4c9a4bb6f2b..000000000000 --- a/cli_reference/helm_cli/disabling-helm-chart-repositories.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="disabling-helm-chart-repositories"] - -= Disabling Helm hart repositories -include::modules/common-attributes.adoc[] -:context: disabling-helm-chart-repositories - -toc::[] - -As a cluster administrator, you can remove Helm chart repositories in your cluster so they are no longer visible in the *Developer Catalog*. - -include::modules/helm-disabling-helm-chart-repository-in-the-cluster.adoc[leveloffset=+1] diff --git a/cli_reference/helm_cli/getting-started-with-helm-on-openshift-container-platform.adoc b/cli_reference/helm_cli/getting-started-with-helm-on-openshift-container-platform.adoc deleted file mode 100644 index e1bfaf12af37..000000000000 --- a/cli_reference/helm_cli/getting-started-with-helm-on-openshift-container-platform.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="getting-started-with-helm-on-openshift"] - -= Getting started with Helm 3 on {product-title} -include::modules/common-attributes.adoc[] -:context: getting-started-with-helm-on-openshift - -toc::[] - -include::modules/helm-understanding-helm.adoc[leveloffset=+1] - -include::modules/helm-installing-helm.adoc[leveloffset=+1] - -include::modules/helm-installing-a-helm-chart-on-an-openshift-cluster.adoc[leveloffset=+1] - -include::modules/helm-creating-a-custom-helm-chart-on-openshift.adoc[leveloffset=+1] - diff --git a/cli_reference/helm_cli/images b/cli_reference/helm_cli/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/cli_reference/helm_cli/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/cli_reference/images b/cli_reference/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/cli_reference/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/cli_reference/kn-cli-tools.adoc b/cli_reference/kn-cli-tools.adoc deleted file mode 100644 index 5ef09c9ee3d5..000000000000 --- a/cli_reference/kn-cli-tools.adoc +++ /dev/null @@ -1,35 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="kn-cli-tools"] -= Knative CLI (`kn`) for use with OpenShift Serverless -:context: kn-cli-tools -include::modules/common-attributes.adoc[] - -toc::[] - -The Knative `kn` CLI enables simple interaction with Knative components on {product-title}. - -You can enable Knative on {product-title} by installing {ServerlessProductName}. For more information, see xref:../serverless/serverless-getting-started.adoc#serverless-getting-started[Getting started with {ServerlessProductName}]. - -[NOTE] -==== -{ServerlessProductName} cannot be installed using the `kn` CLI. A cluster administrator must install the {ServerlessOperatorName} and set up the Knative components, as described in the xref:../serverless/admin_guide/installing-openshift-serverless.adoc#installing-openshift-serverless[Serverless applications] documentation for {product-title}. -==== - -[id="kn-cli-tools-key-features"] -== Key features - -The `kn` CLI is designed to make serverless computing tasks simple and concise. -Key features of the `kn` CLI include: - -* Deploy serverless applications from the command line. -* Manage features of Knative Serving, such as services, revisions, and traffic-splitting. -* Create and manage Knative Eventing components, such as event sources and triggers. -* Create sink bindings to connect existing Kubernetes applications and Knative services. -* Extend the `kn` CLI with flexible plug-in architecture, similar to the `kubectl` CLI. -* Configure autoscaling parameters for Knative services. -* Scripted usage, such as waiting for the results of an operation, or deploying custom rollout and rollback strategies. - -[id="kn-cli-tools-installing-kn"] -== Installing the Knative CLI - -See xref:../serverless/installing-kn.adoc#installing-kn[Installing the Knative CLI]. diff --git a/cli_reference/modules b/cli_reference/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/cli_reference/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/cli_reference/openshift_cli/administrator-cli-commands.adoc b/cli_reference/openshift_cli/administrator-cli-commands.adoc deleted file mode 100644 index af359c59f805..000000000000 --- a/cli_reference/openshift_cli/administrator-cli-commands.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="cli-administrator-commands"] -= OpenShift CLI administrator commands -include::modules/common-attributes.adoc[] -:context: cli-administrator-commands - -toc::[] - -// Cluster management CLI commands -include::modules/cli-administrator-cluster-management.adoc[leveloffset=+1] - -// Node management CLI commands -include::modules/cli-administrator-node-management.adoc[leveloffset=+1] - -// Security and policy CLI commands -include::modules/cli-administrator-security-policy.adoc[leveloffset=+1] - -// Maintenance CLI commands -include::modules/cli-administrator-maintenance.adoc[leveloffset=+1] - -// Configuration CLI commands -include::modules/cli-administrator-configuration.adoc[leveloffset=+1] - -// Other administrator CLI commands -include::modules/cli-administrator-other.adoc[leveloffset=+1] diff --git a/cli_reference/openshift_cli/configuring-cli.adoc b/cli_reference/openshift_cli/configuring-cli.adoc deleted file mode 100644 index e58efba752c3..000000000000 --- a/cli_reference/openshift_cli/configuring-cli.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="cli-configuring-cli"] -= Configuring the OpenShift CLI -include::modules/common-attributes.adoc[] -:context: cli-configuring-cli - -toc::[] - -// Enabling tab completion -include::modules/cli-configuring-completion.adoc[leveloffset=+1] diff --git a/cli_reference/openshift_cli/developer-cli-commands.adoc b/cli_reference/openshift_cli/developer-cli-commands.adoc deleted file mode 100644 index 0984f1304d56..000000000000 --- a/cli_reference/openshift_cli/developer-cli-commands.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="cli-developer-commands"] -= OpenShift CLI developer commands -include::modules/common-attributes.adoc[] -:context: cli-developer-commands - -toc::[] - -// Basic CLI commands -include::modules/cli-developer-basic.adoc[leveloffset=+1] - -// Build and deploy CLI commands -include::modules/cli-developer-build-deploy.adoc[leveloffset=+1] - -// Application management CLI commands -include::modules/cli-developer-application-management.adoc[leveloffset=+1] - -// Troubleshooting and debugging CLI commands -include::modules/cli-developer-troubleshooting.adoc[leveloffset=+1] - -// Advanced developer CLI commands -include::modules/cli-developer-advanced.adoc[leveloffset=+1] - -// Settings CLI commands -include::modules/cli-developer-settings.adoc[leveloffset=+1] - -// Other developer CLI commands -include::modules/cli-developer-other.adoc[leveloffset=+1] diff --git a/cli_reference/openshift_cli/extending-cli-plugins.adoc b/cli_reference/openshift_cli/extending-cli-plugins.adoc deleted file mode 100644 index 44f5a3a7f195..000000000000 --- a/cli_reference/openshift_cli/extending-cli-plugins.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="cli-extend-plugins"] -= Extending the OpenShift CLI with plug-ins -include::modules/common-attributes.adoc[] -:context: cli-extend-plugins - -toc::[] - -You can write and install plug-ins to build on the default `oc` commands, -allowing you to perform new and more complex tasks with the {product-title} CLI. - -// Writing CLI plug-ins -include::modules/cli-extending-plugins-writing.adoc[leveloffset=+1] - -// Installing and using CLI plug-ins -include::modules/cli-extending-plugins-installing.adoc[leveloffset=+1] diff --git a/cli_reference/openshift_cli/getting-started-cli.adoc b/cli_reference/openshift_cli/getting-started-cli.adoc deleted file mode 100644 index db886c76d393..000000000000 --- a/cli_reference/openshift_cli/getting-started-cli.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="cli-getting-started"] -= Getting started with the OpenShift CLI -include::modules/common-attributes.adoc[] -:context: cli-developer-commands - -toc::[] - -// About the CLI -include::modules/cli-about-cli.adoc[leveloffset=+1] - -[id="installing-openshift-cli"] -== Installing the OpenShift CLI - -You can install the OpenShift CLI (`oc`) either by downloading the binary or by using an RPM. - -// Installing the CLI by downloading the binary -include::modules/cli-installing-cli.adoc[leveloffset=+2] - -ifndef::openshift-origin[] -// Installing the CLI by using an RPM -include::modules/cli-installing-cli-rpm.adoc[leveloffset=+2] -endif::[] - -// Logging in to the CLI -include::modules/cli-logging-in.adoc[leveloffset=+1] - -// Using the CLI -include::modules/cli-using-cli.adoc[leveloffset=+1] - -// Getting help -include::modules/cli-getting-help.adoc[leveloffset=+1] - -// Logging out of the CLI -include::modules/cli-logging-out.adoc[leveloffset=+1] diff --git a/cli_reference/openshift_cli/usage-oc-kubectl.adoc b/cli_reference/openshift_cli/usage-oc-kubectl.adoc deleted file mode 100644 index c0c0bc751f31..000000000000 --- a/cli_reference/openshift_cli/usage-oc-kubectl.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="usage-oc-kubectl"] -= Usage of oc and kubectl commands -include::modules/common-attributes.adoc[] -:context: usage-oc-kubectl - -The Kubernetes command-line interface (CLI), `kubectl`, can be used to run commands against a Kubernetes cluster. Because {product-title} is a certified Kubernetes distribution, you can use the supported `kubectl` binaries that ship with {product-title}, or you can gain extended functionality by using the `oc` binary. - -== The oc binary - -The `oc` binary offers the same capabilities as the `kubectl` binary, but it extends to natively support additional {product-title} features, including: - -* **Full support for {product-title} resources** -+ -Resources such as `DeploymentConfig`, `BuildConfig`, `Route`, `ImageStream`, and `ImageStreamTag` objects are specific to {product-title} distributions, and build upon standard Kubernetes primitives. -+ -* **Authentication** -+ -The `oc` binary offers a built-in `login` command that allows authentication and enables you to work with {product-title} projects, which map Kubernetes namespaces to authenticated users. See xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] for more information. -+ -* **Additional commands** -+ -The additional command `oc new-app`, for example, makes it easier to get new applications started using existing source code or pre-built images. Similarly, the additional command `oc new-project` makes it easier to start a project that you can switch to as your default. - -== The kubectl binary - -The `kubectl` binary is provided as a means to support existing workflows and scripts for new {product-title} users coming from a standard Kubernetes environment, or for those who prefer to use the `kubectl` CLI. Existing users of `kubectl` can continue to use the binary to interact with Kubernetes primitives, with no changes required to the {product-title} cluster. - -You can install the supported `kubectl` binary by following the steps to xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-installing-cli_cli-developer-commands[Install the OpenShift CLI]. The `kubectl` binary is included in the archive if you download the binary, or is installed when you install the CLI by using an RPM. - -For more information, see the link:https://kubernetes.io/docs/reference/kubectl/overview/[kubectl documentation]. diff --git a/cli_reference/opm-cli.adoc b/cli_reference/opm-cli.adoc deleted file mode 100644 index 34b8a5ecba25..000000000000 --- a/cli_reference/opm-cli.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="opm-cli"] -= opm CLI -include::modules/common-attributes.adoc[] -:context: opm-cli - -toc::[] - -include::modules/olm-about-opm.adoc[leveloffset=+1] -.Additional resources - -* See xref:../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging formats] for more information about the Bundle Format. -* To create a bundle image using the Operator SDK, see -xref:../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-working-bundle-images[Working with bundle images]. - -include::modules/olm-installing-opm.adoc[leveloffset=+1] - -[id="opm-addtl-resources"] -== Additional resources - -* See xref:../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs-bundle-format[Managing custom catalogs] for `opm` procedures including creating, updating, and pruning index images. diff --git a/cli_reference/osdk/cli-osdk-install.adoc b/cli_reference/osdk/cli-osdk-install.adoc deleted file mode 100644 index b37860eb57b3..000000000000 --- a/cli_reference/osdk/cli-osdk-install.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="cli-osdk-install"] -= Installing the Operator SDK CLI -include::modules/common-attributes.adoc[] -:context: cli-osdk-install - -toc::[] - -The Operator SDK provides a command-line interface (CLI) tool that Operator developers can use to build, test, and deploy an Operator. You can install the Operator SDK CLI on your workstation so that you are prepared to start authoring your own Operators. - -See xref:../../operators/operator_sdk/osdk-about.adoc#osdk-about[Developing Operators] for full documentation on the Operator SDK. - -[NOTE] -==== -{product-title} 4.7 supports Operator SDK v1.3.0. -==== - -include::modules/osdk-installing-cli-linux-macos.adoc[leveloffset=+1] diff --git a/cli_reference/osdk/cli-osdk-ref.adoc b/cli_reference/osdk/cli-osdk-ref.adoc deleted file mode 100644 index bda8652fd799..000000000000 --- a/cli_reference/osdk/cli-osdk-ref.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id="cli-osdk-ref"] -= Operator SDK CLI reference -include::modules/common-attributes.adoc[] -:context: cli-osdk-ref - -toc::[] - -The Operator SDK command-line interface (CLI) is a development kit designed to make writing Operators easier. - -.Operator SDK CLI syntax -[source,terminal] ----- -$ operator-sdk [] [] [] ----- - -Operator authors with cluster administrator access to a Kubernetes-based cluster (such as {product-title}) can use the Operator SDK CLI to develop their own Operators based on Go, Ansible, or Helm. link:https://kubebuilder.io/[Kubebuilder] is embedded into the Operator SDK as the scaffolding solution for Go-based Operators, which means existing Kubebuilder projects can be used as is with the Operator SDK and continue to work. - -See xref:../../operators/operator_sdk/osdk-about.adoc#osdk-about[Developing Operators] for full documentation on the Operator SDK. - -include::modules/osdk-cli-ref-bundle.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-cleanup.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-completion.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-create.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-generate.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-generate-bundle.adoc[leveloffset=+2] -.Additional resources - -* See xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-bundle-deploy-olm_osdk-working-bundle-images[Bundling an Operator and deploying with Operator Lifecycle Manager] for a full procedure that includes using the `make bundle` command to call the `generate bundle` subcommand. - -include::modules/osdk-cli-ref-generate-kustomize.adoc[leveloffset=+2] - -include::modules/osdk-cli-ref-init.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-run.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-run-bundle.adoc[leveloffset=+2] -.Additional resources - -* See xref:../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-operatorgroups-membership_olm-understanding-operatorgroups[Operator group membership] for details on possible install modes. - -include::modules/osdk-cli-ref-run-bundle-upgrade.adoc[leveloffset=+2] -include::modules/osdk-cli-ref-scorecard.adoc[leveloffset=+1] -.Additional resources - -* See xref:../../operators/operator_sdk/osdk-scorecard.adoc#osdk-scorecard[Validating Operators using the scorecard tool] for details about running the scorecard tool. diff --git a/cli_reference/tkn_cli/images b/cli_reference/tkn_cli/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/cli_reference/tkn_cli/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/cli_reference/tkn_cli/installing-tkn.adoc b/cli_reference/tkn_cli/installing-tkn.adoc deleted file mode 100644 index aad4ace6305e..000000000000 --- a/cli_reference/tkn_cli/installing-tkn.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id='installing-tkn'] -= Installing tkn -include::modules/common-attributes.adoc[] -include::modules/pipelines-document-attributes.adoc[] -:context: installing-tkn - -toc::[] - -Use the `tkn` CLI to manage {pipelines-title} from a terminal. The following section describes how to install `tkn` on different platforms. - -You can also find the URL to the latest binaries from the {product-title} web console by clicking the *?* icon in the upper-right corner and selecting *Command Line Tools*. - -// Install tkn on Linux -include::modules/op-installing-tkn-on-linux.adoc[leveloffset=+1] - -// Install tkn on Linux using RPM -include::modules/op-installing-tkn-on-linux-using-rpm.adoc[leveloffset=+1] - -//Install tkn on Windows -include::modules/op-installing-tkn-on-windows.adoc[leveloffset=+1] - -//Install tkn on macOS -include::modules/op-installing-tkn-on-macos.adoc[leveloffset=+1] diff --git a/cli_reference/tkn_cli/modules b/cli_reference/tkn_cli/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/cli_reference/tkn_cli/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/cli_reference/tkn_cli/op-configuring-tkn.adoc b/cli_reference/tkn_cli/op-configuring-tkn.adoc deleted file mode 100644 index 7074701c3cd2..000000000000 --- a/cli_reference/tkn_cli/op-configuring-tkn.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="op-configuring-tkn"] -= Configuring the OpenShift Pipelines `tkn` CLI -include::modules/common-attributes.adoc[] -include::modules/pipelines-document-attributes.adoc[] -:context: configuring-tkn - -toc::[] - -Configure the {pipelines-title} `tkn` CLI to enable tab completion. - -// Enabling tab completion -include::modules/op-tkn-enabling-tab-completion.adoc[leveloffset=+1] diff --git a/cli_reference/tkn_cli/op-tkn-reference.adoc b/cli_reference/tkn_cli/op-tkn-reference.adoc deleted file mode 100644 index ca6b68df39cd..000000000000 --- a/cli_reference/tkn_cli/op-tkn-reference.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id='op-tkn-reference'] -= OpenShift Pipelines `tkn` reference -include::modules/common-attributes.adoc[] -include::modules/pipelines-document-attributes.adoc[] -:context: op-tkn-reference - -toc::[] - - -This section lists the basic `tkn` CLI commands. - -== Basic syntax -`tkn [command or options] [arguments...]` - -== Global options -`--help, -h` - -// Utility commands -include::modules/op-tkn-utility-commands.adoc[leveloffset=+1] - -// Pipeline management commands -include::modules/op-tkn-pipeline-management.adoc[leveloffset=+1] - -// Pipeline run commands -include::modules/op-tkn-pipeline-run.adoc[leveloffset=+1] - -// Task management commands -include::modules/op-tkn-task-management.adoc[leveloffset=+1] - -// Task run commands -include::modules/op-tkn-task-run.adoc[leveloffset=+1] - -// Condition management commands -include::modules/op-tkn-condition-management.adoc[leveloffset=+1] - -// Pipeline resources commands -include::modules/op-tkn-pipeline-resource-management.adoc[leveloffset=+1] - -// ClusterTask management commands -include::modules/op-tkn-clustertask-management.adoc[leveloffset=+1] - -// Trigger management commands -include::modules/op-tkn-trigger-management.adoc[leveloffset=+1] diff --git a/cloud_infrastructure_access/dedicated-aws-access.adoc b/cloud_infrastructure_access/dedicated-aws-access.adoc deleted file mode 100644 index cd73316ff573..000000000000 --- a/cloud_infrastructure_access/dedicated-aws-access.adoc +++ /dev/null @@ -1,75 +0,0 @@ -[id="dedicated-aws-access"] -= Accessing AWS infrastructure -include::modules/common-attributes.adoc[] -:context: dedicated-aws-access - -toc::[] - -Amazon Web Services (AWS) infrastructure access allows -link:https://access.redhat.com/node/3610411[Customer Portal Organization Administrators] -and cluster owners to enable AWS Identity and Access Management (IAM) users to -have federated access to the AWS Management Console for their {product-title} -cluster. Administrators can select between Network Management or Read-only -access options. - -[id="dedicated-configuring-aws-access"] -== Configuring AWS infrastructure access - -== Prerequisites -* An AWS account with IAM permissions. - -[id="dedicated-aws-account-creation"] -=== Creating an AWS account with IAM permissions - -Before you can configure access to AWS infrastructure, you will need to set up IAM permissions in your AWS account. - -.Procedure - -. Log in to your AWS account. If necessary, you can create a new AWS account by following link:https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/[AWS documentation]. -. Create an IAM user with `STS:AllowAssumeRole` permissions within the AWS account. -.. Open the IAM dashboard of the AWS Management Console. -.. In the *Policies* section, click *Create Policy*. -.. Select the `JSON` tab and replace the existing text with the following: -+ -[source,json] ----- - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": "*" - } - ] - } ----- -.. Click *Review Policy*. -.. Provide an appropriate name and description, then click *Create Policy*. -.. In the *Users* section, click *Add user*. -.. Provide an appropriate user name. -.. Select *AWS Management Console access* and other roles as needed. -.. Adjust the password requirements as necessary for your organization, then click *Next: Policy*. -.. Click the *Attach existing policies directly* option. -.. Search for and check the policy created in previous steps. -+ -[NOTE] -==== -It is not recommended to set a permissions boundary. -==== -.. Click *Next: Tags*, then click *Next: Review*. Confirm the configuration is correct. -.. Click *Create user*, then click *Close* on the success page. -. Gather the IAM user's Amazon Resource Name (ARN). The ARN will have the following format: `arn:aws:iam::000111222333:user/username`. - -[id=dedicated-aws-ocm-iam-role] -=== Granting the IAM role from the OpenShift Cluster Manager - -.Procedure - -. Open the {product-title} Cluster Manager in your browser and select the cluster you want to allow AWS infrastructure access. -. Select the *Access control* tab, and scroll to the *AWS Infrastructure Access* section. -. Paste the AWS IAM ARN and select `Network Management` or `Read-only` permissions, then click *Grant role*. -. Copy the AWS OSD Console URL to your clipboard. -. Sign in to your AWS account with your Account ID or alias, IAM user name, and password. -. In a new browser tab, paste the AWS OSD Console URL that will be used to route to the AWS Switch Role page. -. Your account number and role will be filled in already. Choose a display name if necessary, then click *Switch Role*. You will now see *VPC* under *Recently visited services*. diff --git a/cloud_infrastructure_access/dedicated-aws-dc.adoc b/cloud_infrastructure_access/dedicated-aws-dc.adoc deleted file mode 100644 index c2d832df0d7a..000000000000 --- a/cloud_infrastructure_access/dedicated-aws-dc.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="dedicated-aws-dc"] -= Configuring AWS Direct Connect -include::modules/common-attributes.adoc[] -:context: dedicated-aws-direct-connect - -toc::[] - -This process describes accepting an AWS Direct Connect virtual interface with -{product-title}. For more information about AWS Direct Connect types and -configuration, see the -link:https://docs.aws.amazon.com/directconnect/latest/UserGuide/Welcome.html#overview-components[AWS Direct Connect components] -documentation. - -include::modules/dedicated-aws-dc-methods.adoc[leveloffset=+1] -include::modules/dedicated-aws-dc-hvif.adoc[leveloffset=+1] -include::modules/dedicated-aws-dc-existing.adoc[leveloffset=+1] - -[id="dedicated-aws-dc-tshooting"] -== Troubleshooting Direct Connect - -Further troubleshooting can be found in the -link:https://docs.aws.amazon.com/directconnect/latest/UserGuide/Troubleshooting.html[Troubleshooting AWS Direct Connect] -documentation. diff --git a/cloud_infrastructure_access/dedicated-aws-peering.adoc b/cloud_infrastructure_access/dedicated-aws-peering.adoc deleted file mode 100644 index 4210a1654e9e..000000000000 --- a/cloud_infrastructure_access/dedicated-aws-peering.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="dedicated-aws-peering"] -= Configuring AWS VPC peering -include::modules/common-attributes.adoc[] -:context: dedicated-aws-peering - -toc::[] - -This sample process configures an Amazon Web Services (AWS) VPC containing an -{product-title} cluster to peer with another AWS VPC network. For more -information about creating an AWS VPC Peering connection or for other possible -configurations, see the -link:http://docs.aws.amazon.com/AmazonVPC/latest/PeeringGuide/Welcome.html[AWS VPC Peering] -guide. - -include::modules/dedicated-aws-vpc-peering-terms.adoc[leveloffset=+1] -include::modules/dedicated-aws-vpc-initiating-peering.adoc[leveloffset=+1] -.Additional resources - -* xref:../cloud_infrastructure_access/dedicated-aws-access.adoc#dedicated-aws-ocm-iam-role[Logging into the Web Console for the OSD AWS Account] - -include::modules/dedicated-aws-vpc-accepting-peering.adoc[leveloffset=+1] -include::modules/dedicated-aws-vpc-configuring-routing-tables.adoc[leveloffset=+1] -include::modules/dedicated-aws-vpc-verifying-troubleshooting.adoc[leveloffset=+1] diff --git a/cloud_infrastructure_access/dedicated-aws-private-cluster.adoc b/cloud_infrastructure_access/dedicated-aws-private-cluster.adoc deleted file mode 100644 index b32b5dca66a7..000000000000 --- a/cloud_infrastructure_access/dedicated-aws-private-cluster.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="dedicated-aws-private-cluster"] -= Configuring a private cluster -include::modules/common-attributes.adoc[] -:context: dedicated-private-cluster - -toc::[] - -An {product-title} cluster can be made private so that internal applications can be hosted inside a corporate network. In addition, private clusters can be configured to have only internal API endpoints for increased security. - -{product-title} administrators can choose between public and private cluster configuration from within the *OpenShift Cluster Manager* (OCM). Privacy settings can be configured during cluster creation or after a cluster is established. - -include::modules/dedicated-enable-private-cluster-new.adoc[leveloffset=+1] - -include::modules/dedicated-enable-private-cluster-existing.adoc[leveloffset=+1] - -include::modules/dedicated-enable-public-cluster.adoc[leveloffset=+1] - -[NOTE] -==== -Red Hat Service Reliability Engineers (SREs) can access a public or private cluster through the `cloud-ingress-operator` and existing ElasticSearch Load Balancer or Amazon S3 framework. SREs can access clusters through a secure endpoint to perform maintenance and service tasks. -==== diff --git a/cloud_infrastructure_access/dedicated-aws-vpn.adoc b/cloud_infrastructure_access/dedicated-aws-vpn.adoc deleted file mode 100644 index 061d2d6371b0..000000000000 --- a/cloud_infrastructure_access/dedicated-aws-vpn.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="dedicated-aws-vpn"] -= Configuring AWS VPN -include::modules/common-attributes.adoc[] -:context: dedicated-aws-vpn - -toc::[] - -This sample process configures an Amazon Web Services (AWS) {product-title} -cluster to use a customer's on-site hardware VPN device. - -[NOTE] -==== -AWS VPN does not currently provide a managed option to apply NAT to VPN traffic. -See the -link:https://aws.amazon.com/premiumsupport/knowledge-center/configure-nat-for-vpn-traffic/[AWS Knowledge Center] -for more details. -==== - -[NOTE] -==== -Routing all traffic, for example `0.0.0.0/0`, through a private connection is not supported. This requires deleting the internet gateway, which disables SRE management traffic. -==== - -For more information about connecting an AWS VPC to remote networks using a -hardware VPN device, see the Amazon VPC -link:https://docs.aws.amazon.com/vpc/latest/userguide/vpn-connections.html[VPN Connections] -documentation. - -include::modules/dedicated-aws-vpn-creating.adoc[leveloffset=+1] -include::modules/dedicated-aws-vpn-verifying.adoc[leveloffset=+1] -include::modules/dedicated-aws-vpn-troubleshooting.adoc[leveloffset=+1] diff --git a/cloud_infrastructure_access/dedicated-understanding-aws.adoc b/cloud_infrastructure_access/dedicated-understanding-aws.adoc deleted file mode 100644 index b9e06363d049..000000000000 --- a/cloud_infrastructure_access/dedicated-understanding-aws.adoc +++ /dev/null @@ -1,26 +0,0 @@ -:context: dedicated-understanding-aws -[id="welcome-index"] -= Understanding cloud infrastructure access -include::modules/common-attributes.adoc[] - -Amazon Web Services (AWS) infrastructure access permits -link:https://access.redhat.com/node/3610411[Customer Portal Organization Administrators] -and cluster owners to enable AWS Identity and Access Management (IAM) users to -have federated access to the AWS Management Console for their {product-title} -cluster. - -[id="enabling-aws-access"] -== Enabling AWS access -AWS access can be granted for customer AWS users, and private cluster access can be implemented to suit the needs of your {product-title} environment. - -Get started with xref:../cloud_infrastructure_access/dedicated-aws-access.adoc#dedicated-aws-access[Accessing AWS infrastructure] for your {product-title} cluster. By creating an AWS user and account and providing that user with access to the {product-title} AWS account. - -After you have access to the {product-title} AWS account, use one or more of the following methods to establish a private connection to your cluster: - -- xref:../cloud_infrastructure_access/dedicated-aws-peering.adoc#dedicated-aws-peering[Configuring AWS VPC peering]: Enable VPC peering to route network traffic between two private IP addresses. - -- xref:../cloud_infrastructure_access/dedicated-aws-vpn.adoc#dedicated-aws-vpn[Configuring AWS VPN]: Establish a Virtual Private Network to securely connect your private network to your Amazon Virtual Private Cloud. - -- xref:../cloud_infrastructure_access/dedicated-aws-dc.adoc#dedicated-aws-dc[Configuring AWS Direct Connect]: Configure AWS Direct Connect to establish a dedicated network connection between your private network and an AWS Direct Connect location. - -After configuring your cloud infrastructure access, learn more about xref:../cloud_infrastructure_access/dedicated-aws-private-cluster.adoc#dedicated-aws-private-cluster[Configuring a private cluster]. diff --git a/cloud_providers/PLACEHOLDER b/cloud_providers/PLACEHOLDER deleted file mode 100644 index 4020393e57eb..000000000000 --- a/cloud_providers/PLACEHOLDER +++ /dev/null @@ -1,2 +0,0 @@ -Please delete this file once you have assemblies here. - diff --git a/cloud_providers/images b/cloud_providers/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/cloud_providers/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/cloud_service/acs-cloud-responsibility-matrix.adoc b/cloud_service/acs-cloud-responsibility-matrix.adoc new file mode 100644 index 000000000000..29c60ed4b395 --- /dev/null +++ b/cloud_service/acs-cloud-responsibility-matrix.adoc @@ -0,0 +1,11 @@ +[id="acs-cloud-policy-responsibility-matrix"] +:_mod-docs-content-type: ASSEMBLY +include::modules/common-attributes.adoc[] +:context: acs-cloud-responsibility-matrix += Overview of responsibilities for Red Hat Advanced Cluster Security Cloud Service + +toc::[] + +This documentation outlines Red Hat and customer responsibilities for the {product-title-managed-short} managed service. + +include::modules/acs-cloud-responsibilities.adoc[leveloffset=+1] diff --git a/cloud_service/acscs-architecture.adoc b/cloud_service/acscs-architecture.adoc new file mode 100644 index 000000000000..8a02601d8911 --- /dev/null +++ b/cloud_service/acscs-architecture.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: ASSEMBLY +[id="acscs-architecture"] +include::modules/common-attributes.adoc[] += {product-title-managed} architecture +:context: acscs-architecture + +toc::[] + +Discover {rh-rhacscs-first} architecture and concepts. + +include::modules/acscs-architecture-overview.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../operating/examine-images-for-vulnerabilities.adoc#enabling_scanner_v4_examine-images-for-vulnerabilities[Enabling Scanner V4] + +include::modules/acscs-central-overview.adoc[leveloffset=+1] + +include::modules/con-vuln-sources.adoc[leveloffset=+2] + +include::modules/acs-secured-cluster-services-overview.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../architecture/acs-architecture.adoc#external-components_acs-architecture[External components] + +include::modules/acscs-data-access-permissions.adoc[leveloffset=+1] diff --git a/cloud_service/acscs-default-requirements.adoc b/cloud_service/acscs-default-requirements.adoc new file mode 100644 index 000000000000..a38d6685c695 --- /dev/null +++ b/cloud_service/acscs-default-requirements.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: ASSEMBLY +[id="acscs-default-requirements"] += Default resource requirements for Red Hat Advanced Cluster Security Cloud Service +include::modules/common-attributes.adoc[] +:context: acscs-default-requirements + +toc::[] + +include::modules/acs-cloud-requirements.adoc[leveloffset=+1] + +include::modules/default-requirements-secured-cluster-services.adoc[leveloffset=+1] diff --git a/cloud_service/acscs-recommended-requirements.adoc b/cloud_service/acscs-recommended-requirements.adoc new file mode 100644 index 000000000000..8abab76a5822 --- /dev/null +++ b/cloud_service/acscs-recommended-requirements.adoc @@ -0,0 +1,23 @@ +:_mod-docs-content-type: ASSEMBLY +[id="acscs-recommended-requirements"] += Recommended resource requirements for Red Hat Advanced Cluster Security Cloud Service +include::modules/common-attributes.adoc[] +:context: acscs-recommended-requirements + +toc::[] + +The recommended resource guidelines were developed by performing a focused test that created the following objects across a given number of namespaces: + +* 10 deployments, with 3 pod replicas in a sleep state, mounting 4 secrets, 4 config maps +* 10 services, each one pointing to the TCP/8080 and TCP/8443 ports of one of the previous deployments +* 1 route pointing to the first of the previous services +* 10 secrets containing 2048 random string characters +* 10 config maps containing 2048 random string characters + +During the analysis of results, the number of deployments was identified as a primary factor for increasing of used resources. The number of deployments was used for the estimation of required resources. + +[role="_additional-resources"] +.Additional resources +* xref:../cloud_service/acscs-default-requirements.adoc#acs-cloud-requirements_acscs-default-requirements[Default resource requirements] + +include::modules/recommended-requirements-secured-cluster-services.adoc[leveloffset=+1] diff --git a/cloud_service/attributes b/cloud_service/attributes new file mode 120000 index 000000000000..184791562679 --- /dev/null +++ b/cloud_service/attributes @@ -0,0 +1 @@ +../attributes/ \ No newline at end of file diff --git a/cloud_service/getting-started-rhacs-cloud-ocp.adoc b/cloud_service/getting-started-rhacs-cloud-ocp.adoc new file mode 100644 index 000000000000..39b6db75f175 --- /dev/null +++ b/cloud_service/getting-started-rhacs-cloud-ocp.adoc @@ -0,0 +1,142 @@ +:_mod-docs-content-type: ASSEMBLY +[id="getting-started-rhacs-cloud-ocp"] += Getting started with RHACS Cloud Service +include::modules/common-attributes.adoc[] +:context: getting-started-rhacs-cloud-ocp + +toc::[] + +[role="_abstract"] + +{rh-rhacscs-first} provides security services for your {osp} and Kubernetes clusters. See the link:https://access.redhat.com/articles/7045053[Red{nbsp}Hat Advanced Cluster Security for Kubernetes Support Matrix] for information about supported platforms for secured clusters. + +.Prerequisites + +* Ensure that you can access the *Advanced Cluster Security* menu option from the {cloud-console}. ++ +[NOTE] +==== +To access the {product-title-managed-short} console, you need your Red{nbsp}Hat Single Sign-On (SSO) credentials, or credentials for another identity provider if that has been configured. See xref:../cloud_service/getting-started-rhacs-cloud-ocp.adoc#default-access-acs-console[Default access to the ACS console]. +==== + +[id="installation-overview-acs-cloud"] +== High-level overview of installation steps + +The following sections provide an overview of installation steps and links to the relevant documentation. + +[id="securing-rh-cloud-clusters"] +=== Securing {osp} clusters + +You can secure {osp} clusters by using the {product-title-short} Operator, Helm charts, or the `roxctl` CLI. + +[id="overview-installing-cloud-secured-clusters-osp-operator"] +==== Securing {osp} clusters by using the Operator + +.Procedure + +. Verify that the clusters you want to secure meet the xref:../cloud_service/acscs-default-requirements.adoc#acscs-default-requirements[default requirements]. +. In the {cloud-console}, xref:../cloud_service/installing_cloud_ocp/cloud-create-instance-ocp.adoc#cloud-create-instance-ocp[create an *ACS Instance*]. +. On each {osp} cluster you want to secure, xref:../cloud_service/installing_cloud_ocp/cloud-ocp-create-project.adoc#cloud-ocp-create-project[create a project named `stackrox`]. This project will contain the resources for {product-title-managed-short} secured clusters. +. Create the mechanism that the Central instance, also called Central, uses to set up communication with the secured clusters. You can either create an init bundle or a cluster registration secret (CRS). Perform one of these actions: +* In the ACS Console, xref:../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#init-bundle-cloud-ocp-generate[generate an init bundle]. The init bundle contains secrets that allow communication between {product-title-managed-short} secured clusters and Central. +* Log in to Central and use the `roxctl` CLI to xref:../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#roxctl-generate-init-bundle_init-bundle-cloud-ocp-generate[generate an init bundle]. +* Log in to Central and use the `roxctl` CLI to xref:../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#crs-generate-roxctl_init-bundle-cloud-ocp-generate[generate a CRS]. +. On each {osp} cluster, xref:../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply#init-bundle-cloud-ocp-apply[apply the init bundle or CRS]. +. On each {osp} cluster, xref:../cloud_service/installing_cloud_ocp/cloud-install-operator#cloud-install-operator[install the {product-title-short} Operator]. +. On each {osp} cluster, xref:../cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#installing-sc-operator-cloud-ocp[install secured cluster resources in the `stackrox` project] by using the Operator. +. xref:../cloud_service/installing_cloud_ocp/verify-installation-cloud-ocp.adoc#verify-installation-cloud-ocp[Verify installation] by ensuring that your secured clusters can communicate with the ACS instance. + +[id="overview-installing-cloud-secured-clusters-osp-helm"] +==== Securing {osp} clusters by using Helm charts + +.Procedure + +. Verify that the clusters you want to secure meet the xref:../cloud_service/acscs-default-requirements.adoc#acscs-default-requirements[default requirements]. +. In the {cloud-console}, xref:../cloud_service/installing_cloud_ocp/cloud-create-instance-ocp.adoc#cloud-create-instance-ocp[create an *ACS Instance*]. +. On each {osp} cluster you want to secure, xref:../cloud_service/installing_cloud_ocp/cloud-ocp-create-project.adoc#cloud-ocp-create-project[create a project named `stackrox`]. This project will contain the resources for {product-title-managed-short} secured clusters. +. Create the mechanism that the Central instance, also called Central, uses to set up communication with the secured clusters. You can either generate an init bundle or a cluster registration secret (CRS). Perform only one of these actions: +* In the ACS Console, xref:../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#init-bundle-cloud-ocp-generate[generate an init bundle]. The init bundle contains secrets that allow communication between {product-title-managed-short} secured clusters and Central. +* Log in to Central and use the `roxctl` CLI to xref:../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#roxctl-generate-init-bundle_init-bundle-cloud-ocp-generate[generate an init bundle]. +* Log in to Central and use the `roxctl` CLI to xref:../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#crs-generate-roxctl_init-bundle-cloud-ocp-generate[generate a CRS]. +. On each {osp} cluster, run the `helm install` command to xref:../cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#installing-sc-helm-cloud-ocp[install {product-title-short} by using Helm charts], specifying the path of the init bundle or CRS. +. xref:../cloud_service/installing_cloud_ocp/verify-installation-cloud-ocp.adoc#verify-installation-cloud-ocp[Verify installation] by ensuring that your secured clusters can communicate with the ACS instance. + +[id="overview-installing-cloud-secured-clusters-osp-roxctl"] +==== Securing {osp} clusters by using the roxctl CLI, also called the manifest method + +.Procedure + +. Verify that the clusters you want to secure meet the xref:../cloud_service/acscs-default-requirements.adoc#acscs-default-requirements[default requirements]. +. In the {cloud-console}, xref:../cloud_service/installing_cloud_ocp/cloud-create-instance-ocp.adoc#cloud-create-instance-ocp[create an *ACS Instance*]. +. On each {osp} cluster you want to secure, xref:../cloud_service/installing_cloud_ocp/cloud-ocp-create-project.adoc#cloud-ocp-create-project[create a project named `stackrox`]. This project will contain the resources for {product-title-managed-short} secured clusters. +. Perform one of the following actions: +* In the ACS console, use the xref:../cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#installing-manifest-web-portal_install-secured-cluster-cloud-ocp[legacy installation method] to create a cluster bundle. +* From a system that has access to the monitored cluster, xref:../cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#manifest-roxctl_install-secured-cluster-cloud-ocp[generate the configuration and extract and run the sensor script from the cluster bundle]. +. xref:../cloud_service/installing_cloud_ocp/verify-installation-cloud-ocp.adoc#verify-installation-cloud-ocp[Verify installation] by ensuring that your secured clusters can communicate with the ACS instance. + +[id="securing-kubernetes-clusters"] +=== Securing Kubernetes clusters + +You can secure Kubernetes clusters by using Helm charts or the `roxctl` CLI. + +[id="overview-installing-cloud-secured-clusters-kube-helm"] +==== Securing Kubernetes clusters by using Helm charts + +. Verify that the clusters you want to secure meet the xref:../cloud_service/acscs-default-requirements.adoc#acscs-default-requirements[default requirements]. +. In the {cloud-console}, xref:../cloud_service/installing_cloud_other/cloud-create-instance-other.adoc#cloud-create-instance-other[create an *ACS Instance*]. +. Create the mechanism that the Central instance, also called Central, uses to set up communication with the secured clusters. You can either create an init bundle or a cluster registration secret (CRS). Perform only one of these actions: +* In the ACS Console, xref:../cloud_service/installing_cloud_other/init-bundle-cloud-other-generate.adoc#portal-generate-init-bundle_init-bundle-cloud-other-generate[generate an init bundle]. The init bundle contains secrets that allow communication between {product-title-managed-short} secured clusters and Central. +* Log in to Central and xref:../cloud_service/installing_cloud_other/init-bundle-cloud-other-generate#roxctl-generate-init-bundle_init-bundle-cloud-other-generate[use the `roxctl` CLI to generate an init bundle]. +* Log in to Central and use the `roxctl` CLI to xref:../cloud_service/installing_cloud_other/init-bundle-cloud-other-generate#crs-generate-roxctl_init-bundle-cloud-other-generate[generate a CRS]. +. On each Kubernetes cluster, run the `helm install` command to xref:../cloud_service/installing_cloud_other/install-secured-cluster-cloud-other.adoc#install-secured-cluster-cloud-other[install by using Helm charts], specifying the path of the init bundle or CRS. +. xref:../cloud_service/installing_cloud_other/verify-installation-cloud-other.adoc#verify-installation-cloud-other[Verify installation] by ensuring that your secured clusters can communicate with the ACS instance. + +[id="overview-installing-cloud-secured-clusters-kube-roxctl"] +==== Securing Kubernetes clusters by using the roxctl CLI, also called the manifest method + +. Verify that the clusters you want to secure meet the xref:../cloud_service/acscs-default-requirements.adoc#acscs-default-requirements[default requirements]. +. In the {cloud-console}, xref:../cloud_service/installing_cloud_other/cloud-create-instance-other.adoc#cloud-create-instance-other[create an *ACS Instance*]. +. On each cluster you want to secure, create a namespace named `stackrox`. This namespace will contain the resources for {product-title-managed-short} secured clusters. +. Perform one of the following steps: +* In the ACS console, use the xref:../cloud_service/installing_cloud_other/install-secured-cluster-cloud-other.adoc#installing-manifest-web-portal_install-secured-cluster-cloud-other[legacy installation method] to create a cluster bundle. +* From a system that has access to the monitored cluster, xref:../cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#manifest-roxctl_install-secured-cluster-cloud-ocp[generate the configuration and extract and run the sensor script from the cluster bundle]. +. xref:../cloud_service/installing_cloud_ocp/verify-installation-cloud-ocp.adoc#verify-installation-cloud-ocp[Verify installation] by ensuring that your secured clusters can communicate with the ACS instance. + + +[id="default-access-acs-console"] +== Default access to the ACS Console + +By default, the authentication mechanism available to users is authentication by using Red{nbsp}Hat Single Sign-On (SSO). +You cannot delete or change the Red{nbsp}Hat SSO authentication provider. +However, you can change the minimum access role and add additional rules, or add another identity provider. + +[NOTE] +==== +To learn how authentication providers work in ACS, see xref:../operating/manage-user-access/understanding-authentication-providers.adoc#understanding-authentication-providers[Understanding authentication providers]. +==== + +A dedicated OIDC client of `sso.redhat.com` is created for each ACS Console. All OIDC clients share the same `sso.redhat.com` realm. +Claims from the token issued by `sso.redhat.com` are mapped to an ACS-issued token as follows: + +* `realm_access.roles` to `groups` +* `org_id` to `rh_org_id` +* `is_org_admin` to `rh_is_org_admin` +* `sub` to `userid` + +The built-in Red{nbsp}Hat SSO authentication provider has the required attribute `rh_org_id` set to the organization ID assigned to account of the user who created the {product-title-managed-short} instance. +This is the ID of the organizational account the user is a part of. This can be thought of as the "tenant" the user is under and owned by. +Only users with the same organizational account can access the ACS console by using the Red{nbsp}Hat SSO authentication provider. + +[NOTE] +==== +To gain more control over access to your ACS Console, configure another identity provider instead of relying on the Red{nbsp}Hat SSO authentication provider. For more information, see xref:../operating/manage-user-access/understanding-authentication-providers.adoc#authentication-provider-structure[Understanding authentication providers]. To configure the other authentication provider to be the first authentication option on the login page, its name should be lexicographically smaller than `Red{nbsp}Hat SSO`. +==== + +The minimum access role is set to `None`. Assigning a different value to this field gives access to the {product-title-managed-short} instance to all users with the same organizational account. + +Other rules that are set up in the built-in Red{nbsp}Hat SSO authentication provider include the following: + +* Rule mapping your `userid` to `Admin` +* Rules mapping administrators of the organization to `Admin` + +You can add more rules to grant access to the ACS Console to someone else with the same organizational account. For example, you can use `email` as a key. diff --git a/jaeger/jaeger_config/images b/cloud_service/images similarity index 100% rename from jaeger/jaeger_config/images rename to cloud_service/images diff --git a/cloud_service/installing_cloud_ocp/cloud-create-instance-ocp.adoc b/cloud_service/installing_cloud_ocp/cloud-create-instance-ocp.adoc new file mode 100644 index 000000000000..d4cd65b9945c --- /dev/null +++ b/cloud_service/installing_cloud_ocp/cloud-create-instance-ocp.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cloud-create-instance-ocp"] += Creating a RHACS Cloud instance on {cloud-family} +include::modules/common-attributes.adoc[] +:context: cloud-create-instance-ocp + +toc::[] + +[role="_abstract"] +Access {rh-rhacscs-first} by selecting an instance in the {cloud-console}. An *ACS instance* contains the {product-title-managed-short} management interface and services that Red{nbsp}Hat configures and manages for you. The management interface connects to your secured clusters, which contain the services that scan and collect information about vulnerabilities. One instance can connect to and monitor many clusters. + +include::modules/cloud-create-instance-steps.adoc[leveloffset=+1] + +[id="next-steps_cloud-create-instance-ocp"] +== Next steps + +* On each {osp} cluster you want to secure, xref:../installing_cloud_ocp/cloud-ocp-create-project.adoc#cloud-ocp-create-project[create a project named `stackrox`]. This project will contain the resources for {product-title-managed-short} secured clusters. \ No newline at end of file diff --git a/cloud_service/installing_cloud_ocp/cloud-install-operator.adoc b/cloud_service/installing_cloud_ocp/cloud-install-operator.adoc new file mode 100644 index 000000000000..a3512443c680 --- /dev/null +++ b/cloud_service/installing_cloud_ocp/cloud-install-operator.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cloud-install-operator"] += Installing the Operator +include::modules/common-attributes.adoc[] +:context: cloud-install-operator + +toc::[] + +[role="_abstract"] +Install the {product-title-short} Operator on your secured clusters. + +include::modules/install-acs-operator-cloud.adoc[leveloffset=+1] + +include::modules/configuring-the-rhacs-operator-for-infrastructure-nodes.adoc[leveloffset=+2] + +[id="next-steps_cloud-install-operator"] +== Next steps + +* On each {osp} cluster, xref:../installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#install-secured-cluster-cloud-ocp[install secured cluster resources in the `stackrox` project]. \ No newline at end of file diff --git a/cloud_service/installing_cloud_ocp/cloud-ocp-create-project.adoc b/cloud_service/installing_cloud_ocp/cloud-ocp-create-project.adoc new file mode 100644 index 000000000000..c12c1c7d20fb --- /dev/null +++ b/cloud_service/installing_cloud_ocp/cloud-ocp-create-project.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cloud-ocp-create-project"] += Creating a project on your Red Hat OpenShift secured cluster +include::modules/common-attributes.adoc[] +:context: cloud-ocp-create-project + +toc::[] + +[role="_abstract"] +Create a project on each {osp} cluster that you want to secure. You then use this project to install {product-title-managed-short} resources by using the Operator or Helm charts. + +include::modules/cloud-ocp-create-stackrox-project.adoc[leveloffset=+1] + +[id="next-steps_cloud-ocp-create-project"] +== Next steps + +* In the ACS Console, xref:../installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#init-bundle-cloud-ocp-generate[create an init bundle] or cluster registration secret (CRS). The init bundle contains secrets that allow communication between {product-title-managed-short} secured clusters and Central. The CRS can also be used to set up this initial communication and is more flexible and secure. \ No newline at end of file diff --git a/cloud_service/installing_cloud_ocp/configuring-the-proxy-for-secured-cluster-services-in-rhacs-cloud-service.adoc b/cloud_service/installing_cloud_ocp/configuring-the-proxy-for-secured-cluster-services-in-rhacs-cloud-service.adoc new file mode 100644 index 000000000000..a49b01d6cec4 --- /dev/null +++ b/cloud_service/installing_cloud_ocp/configuring-the-proxy-for-secured-cluster-services-in-rhacs-cloud-service.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: ASSEMBLY +[id="configuring-the-proxy-for-secured-cluster-services-in-rhacs-cloud-service"] += Configuring the proxy for secured cluster services in {product-title-managed-short} +include::modules/common-attributes.adoc[] +:context: configure-secured-cluster-proxy + +toc::[] + +[role="_abstract"] +You must configure the proxy settings for secured cluster services within the {rh-rhacscs-first} environment to establish a connection between the Secured Cluster and the specified proxy server. This ensures reliable data collection and transmission. + +//Specifying the environment variables +include::modules/specifying-the-environment-variables-in-the-securedcluster-cr.adoc[leveloffset=+1] diff --git a/cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply.adoc b/cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply.adoc new file mode 100644 index 000000000000..ce45117c4678 --- /dev/null +++ b/cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply.adoc @@ -0,0 +1,31 @@ +:_mod-docs-content-type: ASSEMBLY +[id="init-bundle-cloud-ocp-apply"] += Applying an init bundle or cluster registration secret for secured clusters +include::modules/common-attributes.adoc[] +:context: init-bundle-cloud-ocp-apply + +toc::[] + +[role="_abstract"] +Apply the init bundle or cluster registration secret (CRS) by using it to create resources. + +[NOTE] +==== +You must have the `Admin` user role to apply an init bundle or CRS. +==== + +include::modules/create-resource-init-bundle.adoc[leveloffset=+1] +include::modules/crs-apply-secured-cluster.adoc[leveloffset=+1] + +[id="next-steps_init-bundle-cloud-ocp-apply"] +== Next steps + +* On each {osp} cluster, xref:../installing_cloud_ocp/cloud-install-operator#cloud-install-operator[install the {product-title-short} Operator]. + +* Install {product-title-short} secured cluster services in all clusters that you want to monitor. + +[role="_additional-resources"] +[id="additional-resources_init-bundle-cloud-ocp-apply"] +== Additional resources + +* xref:../../configuration/add-custom-certificates.adoc#restart-sensor_add-custom-cert[Restarting the Sensor container] \ No newline at end of file diff --git a/cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc b/cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc new file mode 100644 index 000000000000..190b84752f2c --- /dev/null +++ b/cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc @@ -0,0 +1,45 @@ +:_mod-docs-content-type: ASSEMBLY +[id="init-bundle-cloud-ocp-generate"] += Generating an init bundle or cluster registration secret for secured clusters +include::modules/common-attributes.adoc[] +:context: init-bundle-cloud-ocp-generate + +toc::[] + +[role="_abstract"] + +Before you set up a secured cluster, you must create an init bundle or cluster registration secret (CRS). The secured cluster then uses this bundle or CRS to authenticate with the Central instance, also called Central. You can create an init bundle or CRS by using either the {product-title-short} portal or the `roxctl` CLI. You then apply the init bundle or CRS by using it to create resources. + +[NOTE] +==== +You must have the `Admin` user role to create an init bundle. +==== + +{product-title-short} uses a special artifact during installation that allows the {product-title-short} Central component to communicate securely with secured clusters that you are adding. Before the 4.7 release, {product-title-short} used _init bundles_ exclusively for initiating the secure communication channel. Beginning with 4.7, {product-title-short} provides an alternative to init bundles called _cluster registration secrets_ (CRSes). + +:FeatureName: Cluster registration secrets +include::snippets/technology-preview.adoc[] + +include::snippets/cluster-registration-secrets.adoc[] + +You can use either an init bundle or a cluster registration secret (CRS) during installation of a secured cluster. However, {product-title-short} does not yet provide a way to create a CRS by using the portal. Therefore, you must create the CRS by using the `roxctl` CLI. + +Before you set up a secured cluster, you must create an init bundle or CRS. The secured cluster then uses this bundle or CRS to authenticate with Central. You can create an init bundle by using either the {product-title-short} portal or the `roxctl` CLI. If you are using a CRS, you must use the `roxctl` CLI to create it. + +You can then apply the init bundle or the CRS by using the {ocp} web console or by using the `oc` or `kubectl` CLI. If you install {product-title-short} by using Helm, you provide the init bundle or CRS when you run the `helm install` command. + +[id="generate-init-bundle-cloud-ocp"] +== Generating an init bundle + +include::modules/portal-generate-init-bundle.adoc[leveloffset=+2] +include::modules/roxctl-generate-init-bundle.adoc[leveloffset=+2] + +[id="generate-crs-cloud-ocp"] +== Generating a CRS + +include::modules/crs-generate-roxctl.adoc[leveloffset=+2] + +[id="next-steps_init-bundle-cloud-ocp-generate"] +== Next steps + +* xref:../../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply.adoc#create-resource-init-bundle_init-bundle-cloud-ocp-apply[Applying an init bundle or cluster registration secret for secured clusters] diff --git a/cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc b/cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc new file mode 100644 index 000000000000..dd77bcd2a51d --- /dev/null +++ b/cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc @@ -0,0 +1,96 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-secured-cluster-cloud-ocp"] += Installing secured cluster resources from RHACS Cloud Service +include::modules/common-attributes.adoc[] +:context: install-secured-cluster-cloud-ocp + +toc::[] + +[role="_abstract"] +You can install {product-title-managed-short} on your secured clusters by using the Operator or Helm charts. You can also use the `roxctl` CLI to install it, but do not use this method unless you have a specific installation need that requires using it. + +.Prerequisites + +* During {product-title-short} installation, you noted the *Central instance* address. You can view this information by choosing *Advanced Cluster Security* -> *ACS Instances* from the cloud console navigation menu, and then clicking the ACS instance you created. +* If you are installing by using the Operator, you created your {osp} cluster that you want to secure and installed the Operator on it. +* You created and downloaded the init bundle or cluster registration secret (CRS) by using the ACS Console or by using the `roxctl` CLI. +* You applied the init bundle or CRS on the cluster that you want to secure, unless you are installing by using a Helm chart. + + +[id="installing-sc-operator-cloud-ocp"] +== Installing {product-title-short} on secured clusters by using the Operator + +To install {product-title-short} by using the Operator, you first install the Operator and then use it to install {product-title-short} on the secured cluster. + +include::modules/install-acs-operator-annotations.adoc[leveloffset=+2] + +include::modules/install-secured-cluster-operator.adoc[leveloffset=+2] + +[id="installing-sc-helm-cloud-ocp"] +== Installing {product-title-managed-short} on secured clusters by using Helm charts + +You can install {product-title-short} on secured clusters by using Helm charts with no customization, using the default values, or with customizations of configuration parameters. + +First, ensure that you add the Helm chart repository. + +include::modules/adding-helm-repository.adoc[leveloffset=+2] + +[id="installing-sc-helm-default-cloud-ocp"] +=== Installing {product-title-managed-short} on secured clusters by using Helm charts without customizations + +include::modules/acs-quick-install-secured-cluster-using-helm.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources +* xref:../../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#init-bundle-cloud-ocp-generate[Generating an init bundle for secured clusters] +* xref:../../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply.adoc#init-bundle-cloud-ocp-apply[Applying an init bundle for secured clusters] + +[id="configure-secured-cluster-services-helm-chart-customizations-cloud-ocp"] +=== Configuring the secured-cluster-services Helm chart with customizations + +You can use Helm chart configuration parameters with the `helm install` and `helm upgrade` commands. +Specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Ensure that you store this file securely. + +[IMPORTANT] +==== +When using the `secured-cluster-services` Helm chart, do not change the `values.yaml` file that is part of the chart. +==== + +include::modules/secured-cluster-services-config.adoc[leveloffset=+3] +include::modules/install-secured-cluster-services-helm-chart.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources +* xref:../../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-generate.adoc#init-bundle-cloud-ocp-generate[Generating an init bundle for secured clusters] +* xref:../../cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply.adoc#init-bundle-cloud-ocp-apply[Applying an init bundle for secured clusters] + +include::modules/change-config-options-after-deployment.adoc[leveloffset=+2] + +[id="installing-sc-roxctl-cloud-ocp"] +== Installing {product-title-short} on secured clusters by using the roxctl CLI + +To install {product-title-short} on secured clusters by using the CLI, perform the following steps: + +. Install the `roxctl` CLI. +. Install Sensor. + +[id="installing-roxctl-cli-sc-cloud-ocp"] +=== Installing the roxctl CLI + +You must first download the binary. You can install `roxctl` on Linux, Windows, or macOS. + +// Installing the CLI by downloading the binary +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+3] +include::modules/install-sensor-roxctl.adoc[leveloffset=+2] + +[id="next-steps_install-secured-cluster-cloud-ocp"] +== Next steps + +* xref:../installing_cloud_ocp/verify-installation-cloud-ocp.adoc#verify-installation-cloud-ocp[Verify installation] by ensuring that your secured clusters can communicate with the ACS instance. \ No newline at end of file diff --git a/cicd/builds/modules b/cloud_service/installing_cloud_ocp/modules similarity index 100% rename from cicd/builds/modules rename to cloud_service/installing_cloud_ocp/modules diff --git a/cloud_service/installing_cloud_ocp/snippets b/cloud_service/installing_cloud_ocp/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/cloud_service/installing_cloud_ocp/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/cloud_service/installing_cloud_ocp/verify-installation-cloud-ocp.adoc b/cloud_service/installing_cloud_ocp/verify-installation-cloud-ocp.adoc new file mode 100644 index 000000000000..2cccdfb5d0c1 --- /dev/null +++ b/cloud_service/installing_cloud_ocp/verify-installation-cloud-ocp.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: ASSEMBLY +[id="verify-installation-cloud-ocp"] += Verifying installation of secured clusters +include::modules/common-attributes.adoc[] +:context: verify-installation-cloud-ocp + +toc::[] + +[role="_abstract"] +After installing {product-title-managed-short}, you can perform some steps to verify that the installation was successful. + +To verify installation, access your ACS Console from the {cloud-console}. The Dashboard displays the number of clusters that {product-title-managed-short} is monitoring, along with information about nodes, deployments, images, and violations. + +If no data appears in the ACS Console: + +* Ensure that at least one secured cluster is connected to your {product-title-managed-short} instance. For more information, see xref:../installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#installing-sc-operator-cloud-ocp[Installing secured cluster resources from {product-title-managed-short}]. +* Examine your Sensor pod logs to ensure that the connection to your {product-title-managed-short} instance is successful. +* In the {osp} cluster, go to *Platform Configuration* -> *Clusters* to verify that the components are healthy and view additional operational information. +* Examine the values in the `SecuredCluster` API in the Operator on your local cluster to ensure that the *Central API Endpoint* has been entered correctly. This value should be the same value as shown in the *ACS instance* details in the {cloud-console}. diff --git a/cloud_service/installing_cloud_other/cloud-create-instance-other.adoc b/cloud_service/installing_cloud_other/cloud-create-instance-other.adoc new file mode 100644 index 000000000000..197387b69025 --- /dev/null +++ b/cloud_service/installing_cloud_other/cloud-create-instance-other.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cloud-create-instance-other"] += Creating an RHACS Cloud Service instance for Kubernetes clusters +include::modules/common-attributes.adoc[] +:context: cloud-create-instance-other + +toc::[] + +[role="_abstract"] +Access {rh-rhacscs-first} by selecting an instance in the {cloud-console}. An *ACS instance* contains the {product-title-managed-short} management interface and services that Red{nbsp}Hat configures and manages for you. The management interface connects to your secured clusters, which contain the services that scan and collect information about vulnerabilities. One instance can connect to and monitor many clusters. + +include::modules/cloud-create-instance-steps.adoc[leveloffset=+1] + +[id="next-steps_cloud-create-instance-other"] +== Next steps + +* On each Kubernetes cluster you want to secure, xref:../installing_cloud_other/install-secured-cluster-cloud-other.adoc#install-secured-cluster-cloud-other[install secured cluster resources] by using Helm charts or the `roxctl` CLI. \ No newline at end of file diff --git a/cloud_service/installing_cloud_other/init-bundle-cloud-other-apply.adoc b/cloud_service/installing_cloud_other/init-bundle-cloud-other-apply.adoc new file mode 100644 index 000000000000..1818fc6cc19a --- /dev/null +++ b/cloud_service/installing_cloud_other/init-bundle-cloud-other-apply.adoc @@ -0,0 +1,23 @@ +:_mod-docs-content-type: ASSEMBLY +[id="init-bundle-cloud-other-apply"] += Applying an init bundle for Kubernetes secured clusters +include::modules/common-attributes.adoc[] +:context: init-bundle-cloud-other-apply + +toc::[] + +[role="_abstract"] +Apply the init bundle by using it to create resources. + +include::modules/create-resource-init-bundle.adoc[leveloffset=+1] + +[id="next-steps_init-bundle-cloud-other-apply"] +== Next steps + +* Install {product-title-short} secured cluster services in all clusters that you want to monitor. + +[role="_additional-resources"] +[id="additional-resources_init-bundle-cloud-other-apply"] +== Additional resources + +* xref:../../configuration/add-custom-certificates.adoc#restart-sensor_add-custom-cert[Restarting the Sensor container] \ No newline at end of file diff --git a/cloud_service/installing_cloud_other/init-bundle-cloud-other-generate.adoc b/cloud_service/installing_cloud_other/init-bundle-cloud-other-generate.adoc new file mode 100644 index 000000000000..d194790d593a --- /dev/null +++ b/cloud_service/installing_cloud_other/init-bundle-cloud-other-generate.adoc @@ -0,0 +1,37 @@ +:_mod-docs-content-type: ASSEMBLY +[id="init-bundle-cloud-other-generate"] += Generating an init bundle or cluster registration secret for Kubernetes secured clusters +include::modules/common-attributes.adoc[] +:context: init-bundle-cloud-other-generate + +toc::[] + +[role="_abstract"] + +Before you set up a secured cluster, you must create an init bundle or cluster registration secret (CRS). The secured cluster then uses this bundle or CRS to authenticate with the Central instance, also called Central. You can create an init bundle by using either the {product-title-short} portal or the `roxctl` CLI. You then apply the init bundle by using it to create resources. + + +:FeatureName: Cluster registration secrets +include::snippets/technology-preview.adoc[] + +You can use either an init bundle or a cluster registration secret (CRS) during installation of a secured cluster. However, {product-title-short} does not yet provide a way to create a CRS by using the portal. Therefore, you must create the CRS by using the `roxctl` CLI. + +Before you set up a secured cluster, you must create an init bundle or CRS. The secured cluster then uses this bundle or CRS to authenticate with Central. You can create an init bundle by using either the {product-title-short} portal or the `roxctl` CLI. If you are using a CRS, you must use the `roxctl` CLI to create it. + +You can then apply the init bundle or the CRS by using the {ocp} `kubectl` CLI. If you install {product-title-short} by using Helm, you provide the init bundle or CRS when you run the `helm install` command. + +[id="generate-init-bundle-cloud-kube"] +== Generating an init bundle + +include::modules/portal-generate-init-bundle.adoc[leveloffset=+2] +include::modules/roxctl-generate-init-bundle.adoc[leveloffset=+2] + +[id="generate-crs-cloud-kube"] +== Generating a CRS + +include::modules/crs-generate-roxctl.adoc[leveloffset=+2] + +[id="next-steps_init-bundle-cloud-other-generate"] +== Next steps + +* xref:../../cloud_service/installing_cloud_other/init-bundle-cloud-other-apply.adoc#create-resource-init-bundle_init-bundle-cloud-other-apply[Creating resources by using the init bundle] \ No newline at end of file diff --git a/cloud_service/installing_cloud_other/install-secured-cluster-cloud-other.adoc b/cloud_service/installing_cloud_other/install-secured-cluster-cloud-other.adoc new file mode 100644 index 000000000000..bbd99dc17893 --- /dev/null +++ b/cloud_service/installing_cloud_other/install-secured-cluster-cloud-other.adoc @@ -0,0 +1,85 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-secured-cluster-cloud-other"] += Installing secured cluster services from RHACS Cloud Service on Kubernetes clusters +include::modules/common-attributes.adoc[] +:context: install-secured-cluster-cloud-other +:topic-helm: + +toc::[] + +[role="_abstract"] +You can install {product-title-managed-short} on your secured clusters by using one of the following methods: + +* By using Helm charts +* By using the `roxctl` CLI (do not use this method unless you have a specific installation need that requires using it) + +[id="installing-sc-helm-cloud-other"] +== Installing {product-title-managed-short} on secured clusters by using Helm charts + +You can install {product-title-short} on secured clusters by using Helm charts with no customization, by using Helm charts with the default values, or by using Helm charts with customizations of configuration parameters. + +First, ensure that you add the Helm chart repository. + +include::modules/adding-helm-repository.adoc[leveloffset=+2] + +[id="installing-sc-helm-default-cloud-other"] +=== Installing {product-title-managed-short} on secured clusters by using Helm charts without customizations + +include::modules/acs-quick-install-secured-cluster-using-helm.adoc[leveloffset=+3] + +[id="configure-secured-cluster-services-helm-chart-customizations-cloud-other"] +=== Configuring the secured-cluster-services Helm chart with customizations + +This section describes Helm chart configuration parameters that you can use with the `helm install` and `helm upgrade` commands. +You can specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Ensure that you store this file securely. + +[IMPORTANT] +==== +While using the `secured-cluster-services` Helm chart, do not modify the `values.yaml` file that is part of the chart. +==== + +include::modules/secured-cluster-services-config.adoc[leveloffset=+3] + +include::modules/install-secured-cluster-services-helm-chart.adoc[leveloffset=+3] + +include::modules/change-config-options-after-deployment.adoc[leveloffset=+2] + +[id="installing-sc-roxctl-cloud-other"] +== Installing {product-title-short} on secured clusters by using the roxctl CLI + +To install {product-title-short} on secured clusters by using the CLI, perform the following steps: + +. Install the `roxctl` CLI. +. Install Sensor. + +[id="installing-roxctl-cli-sc-cloud-other"] +=== Installing the roxctl CLI + +You must first download the binary. You can install `roxctl` on Linux, Windows, or macOS. + +// Installing the CLI by downloading the binary +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+3] +include::modules/install-sensor-roxctl.adoc[leveloffset=+2] + + + + + + + + + + + + + + + + diff --git a/cicd/gitops/modules b/cloud_service/installing_cloud_other/modules similarity index 100% rename from cicd/gitops/modules rename to cloud_service/installing_cloud_other/modules diff --git a/cloud_service/installing_cloud_other/snippets b/cloud_service/installing_cloud_other/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/cloud_service/installing_cloud_other/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/cloud_service/installing_cloud_other/verify-installation-cloud-other.adoc b/cloud_service/installing_cloud_other/verify-installation-cloud-other.adoc new file mode 100644 index 000000000000..351b6624dfc0 --- /dev/null +++ b/cloud_service/installing_cloud_other/verify-installation-cloud-other.adoc @@ -0,0 +1,18 @@ +:_mod-docs-content-type: ASSEMBLY +[id="verify-installation-cloud-other"] += Verifying installation of secured clusters +include::modules/common-attributes.adoc[] +:context: verify-installation-cloud-other + +toc::[] + +[role="_abstract"] +After installing {product-title-managed-short}, you can perform some steps to verify that the installation was successful. + +To verify installation, access your ACS Console from the {cloud-console}. The Dashboard displays the number of clusters that {product-title-managed-short} is monitoring, along with information about nodes, deployments, images, and violations. + +If no data appears in the ACS Console: + +* Ensure that at least one secured cluster is connected to your {product-title-managed-short} instance. For more information, see instructions for installing by using xref:../installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#installing-sc-helm-cloud-ocp[Helm charts] or by using the xref:../installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#installing-sc-roxctl-cloud-ocp[`roxctl` CLI]. +* Examine your Sensor pod logs to ensure that the connection to your {product-title-managed-short} instance is successful. +* Examine the values in the `SecuredCluster` API in the Operator on your local cluster to ensure that the *Central API Endpoint* has been entered correctly. This value should be the same value as shown in the *ACS instance* details in the {cloud-console}. diff --git a/jaeger/jaeger_arch/modules b/cloud_service/modules similarity index 100% rename from jaeger/jaeger_arch/modules rename to cloud_service/modules diff --git a/cloud_service/rhacs-cloud-service-service-description.adoc b/cloud_service/rhacs-cloud-service-service-description.adoc new file mode 100644 index 000000000000..91be31f8f465 --- /dev/null +++ b/cloud_service/rhacs-cloud-service-service-description.adoc @@ -0,0 +1,112 @@ +:_mod-docs-content-type: ASSEMBLY +include::modules/common-attributes.adoc[] +[id="rhacs-cloud-service-service-description"] += {product-title-managed-short} service description +:context: access-policy-service-description + +toc::[] + +include::modules/introduction-to-rhacs.adoc[leveloffset=+1] + +[id="architecture_{context}"] +== Architecture + +{product-title-managed-short} is hosted on Amazon Web Services (AWS) over two regions, eu-west-1 and us-east-1, and uses the network access points provided by the cloud provider. +Each tenant from {product-title-managed-short} uses highly-available egress proxies and is spread over 3 availability zones. For more information about {product-title-managed-short} system architecture and components, see xref:../cloud_service/acscs-architecture.adoc#acscs-architecture-overview_acscs-architecture[{rh-rhacscs-first} architecture]. + +include::modules/billing.adoc[leveloffset=+1] + +[id="security-and-compliance_{context}"] +== Security and compliance + +All {product-title-managed-short} data in the Central instance is encrypted in transit and at rest. +The data is stored in secure storage with full replication and high availability together with regularly-scheduled backups. +{product-title-managed-short} is available through cloud data centers that ensure optimal performance and the ability to meet data residency requirements. + +include::modules/cloud-info-security.adoc[leveloffset=+2] + +[id="sdlc-security_{context}"] +=== Systems development lifecycle security + +Red{nbsp}Hat follows secure development lifecycle practices. Red{nbsp}Hat Product Security practices are aligned with the Open Web Application Security Project (OWASP) and ISO12207:2017 wherever it is feasible. Red{nbsp}Hat covers OWASP project recommendations along with other secure software development practices to increase the general security posture of our products. OWASP project analysis is included in Red{nbsp}Hat's automated scanning, security testing, and threat models, as the OWASP project is built based on selected CWE weaknesses. Red{nbsp}Hat monitors weaknesses in our products to address issues before they are exploited and become vulnerabilities. + +For more information, see the following resources: + +* link:https://access.redhat.com/security_testing_sdl_practice[Red{nbsp}Hat Software Development Life Cycle practices] +* link:https://www.redhat.com/en/blog/security-design-security-principles-and-threat-modeling[Security by design: Security principles and threat modeling] + +Applications are scanned regularly and the container scan results of the product are available publicly. For example, on the Red{nbsp}Hat Ecosystem Catalog site, you can select a component image such as `rhacs-main` and click the *Security* tab to see the health index and the status of security updates. + +As part of Red{nbsp}Hat's policy, a support policy and maintenance plan is issued for any third-party components we depend on that go to end-of-life. + +[id="access-control_{context}"] +== Access control + +User accounts are managed with role-based access control (RBAC). See xref:../operating/manage-user-access/manage-role-based-access-control-3630.adoc#manage-role-based-access-control[Managing RBAC in Red{nbsp}Hat Advanced Cluster Security for Kubernetes] for more information. Red{nbsp}Hat site reliability engineers (SREs) have access to Central instances. Access is controlled with OpenShift RBAC. Credentials are instantly revoked upon termination. + +[id="authentication-provider_{context}"] +=== Authentication provider + +When you create a Central instance using link:https://console.redhat.com/[Red{nbsp}Hat Hybrid Cloud Console], authentication for the cluster administrator is configured as part of the process. +Customers must manage all access to the Central instance as part of their integrated solution. +For more information about the available authentication methods, see xref:../operating/manage-user-access/understanding-authentication-providers.adoc#understanding-authentication-providers[Understanding authentication providers]. + +The default identity provider in {product-title-managed-short} is Red{nbsp}Hat Single Sign-On (SSO). Authorization rules are set up to provide administrator access to the user who created the {product-title-managed-short} and to users who are marked as organization administrators in Red{nbsp}Hat SSO. The `admin` login is disabled for {product-title-managed-short} by default and can only be enabled temporarily by SREs. For more information about authentication using Red{nbsp}Hat SSO, see xref:../cloud_service/getting-started-rhacs-cloud-ocp.adoc#default-access-acs-console[Default access to the ACS Console]. + +[id="passwords_{context}"] +=== Password management + +Red{nbsp}Hat's password policy requires the use of a complex password. +Passwords must contain at least 14 characters and at least three of the following character classes: + +* Base 10 digits (0 to 9) +* Upper case characters (A to Z) +* Lower case characters (a to z) +* Punctuation, spaces, and other characters + +Most systems require two-factor authentication. + +Red{nbsp}Hat follows best password practices according to link:https://pages.nist.gov/800-63-3/sp800-63b.html[NIST guidelines]. + +[id="remote-access_{context}"] +=== Remote access + +Access for remote support and troubleshooting is strictly controlled through implementation of the following guidelines: + +* Strong two-factor authentication for VPN access +* A segregated network with management and administrative networks requiring additional authentication through a bastion host +* All access and management is performed over encrypted sessions + +Our customer support team offers Bomgar as a remote access solution for troubleshooting. Bomgar sessions are optional, must be initiated by the customer, and can be monitored and controlled. + +To prevent information leakage, logs are shipped to SRE through our security information and event management (SIEM) application, Splunk. + +[id="access-restriction_{context}"] +=== Central access restriction by IP addresses and CIDR ranges + +Restricting access to Central ensures that only traffic from trusted IP addresses can reach the security policy enforcement point, thereby strengthening the overall security posture. + +To request restricted access to Central, go to the link:https://access.redhat.com/support[Red Hat Customer Portal] page. +From the Customer Portal, submit a support case requesting the restriction of access to Central. +Be sure to provide the list of trusted IP addresses and CIDR ranges. +The maximum number of IP addresses and CIDR ranges is 55. + +include::modules/cloud-svc-compliance.adoc[leveloffset=+1] + +include::modules/data-protection.adoc[leveloffset=+1] + +include::modules/metrics-and-logging.adoc[leveloffset=+1] + +include::modules/updates-and-upgrades.adoc[leveloffset=+1] + +include::modules/availability.adoc[leveloffset=+1] + +include::modules/backup-and-disaster-recovery.adoc[leveloffset=+2] + +include::modules/cloud-getting-support.adoc[leveloffset=+1] + +include::modules/cloud-service-removal.adoc[leveloffset=+1] + +include::modules/pricing.adoc[leveloffset=+1] + +include::modules/service-level-agreement.adoc[leveloffset=+1] diff --git a/cloud_service/snippets b/cloud_service/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/cloud_service/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/cloud_service/upgrading-cloud/_attributes b/cloud_service/upgrading-cloud/_attributes new file mode 120000 index 000000000000..20cc1dcb77bf --- /dev/null +++ b/cloud_service/upgrading-cloud/_attributes @@ -0,0 +1 @@ +../../_attributes/ \ No newline at end of file diff --git a/installing/installing_aws/images b/cloud_service/upgrading-cloud/images similarity index 100% rename from installing/installing_aws/images rename to cloud_service/upgrading-cloud/images diff --git a/installing/installing_bare_metal/modules b/cloud_service/upgrading-cloud/modules similarity index 100% rename from installing/installing_bare_metal/modules rename to cloud_service/upgrading-cloud/modules diff --git a/cloud_service/upgrading-cloud/snippets b/cloud_service/upgrading-cloud/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/cloud_service/upgrading-cloud/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/cloud_service/upgrading-cloud/upgrade-cloudsvc-helm.adoc b/cloud_service/upgrading-cloud/upgrade-cloudsvc-helm.adoc new file mode 100644 index 000000000000..4ec74e910109 --- /dev/null +++ b/cloud_service/upgrading-cloud/upgrade-cloudsvc-helm.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: ASSEMBLY +[id="upgrade-cloudsvc-helm"] += Upgrading secured clusters in RHACS Cloud Service by using Helm charts +include::modules/common-attributes.adoc[] +:context: upgrade-cloudsvc-helm + +toc::[] + +[role="_abstract"] +You can upgrade your secured clusters in {product-title-managed-short} by using Helm charts. + +If you installed {product-title-short} secured clusters by using Helm charts, you can upgrade to the latest version of {product-title-short} by updating the Helm chart and running the `helm upgrade` command. + +include::modules/updating-helm-repository.adoc[leveloffset=+1] + +include::modules/upgrade-helm-chart.adoc[leveloffset=+1] + +[role="_additional-resources"] +== Additional resources +* xref:../../cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc#installing-sc-helm-cloud-ocp[Installing {product-title-managed-short} on secured clusters by using Helm charts] diff --git a/cloud_service/upgrading-cloud/upgrade-cloudsvc-operator.adoc b/cloud_service/upgrading-cloud/upgrade-cloudsvc-operator.adoc new file mode 100644 index 000000000000..c62196a68215 --- /dev/null +++ b/cloud_service/upgrading-cloud/upgrade-cloudsvc-operator.adoc @@ -0,0 +1,46 @@ +:_mod-docs-content-type: ASSEMBLY +[id="upgrade-cloudsvc-operator"] += Upgrading secured clusters in RHACS Cloud Service by using the Operator +include::modules/common-attributes.adoc[] +:context: upgrade-cloudsvc-operator + +toc::[] + +[role="_abstract"] + +Red{nbsp}Hat provides regular service updates for the components that it manages, including Central services. These service updates include upgrades to new versions of {product-title-managed}. + +You must regularly upgrade the version of {product-title-short} on your secured clusters to ensure compatibility with {product-title-managed-short}. + +include::modules/prepare-operator-upgrades.adoc[leveloffset=+1] +include::modules/change-collection-method.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* link:https://docs.openshift.com/container-platform/latest/operators/admin/olm-upgrading-operators.html[Updating installed Operators] + +[id="rollback-operator-upgrade-cloud"] +== Rolling back an Operator upgrade for secured clusters + +To roll back an Operator upgrade, you can use either the CLI or the {ocp} web console. + +[NOTE] +==== +On secured clusters, rolling back Operator upgrades is needed only in rare cases, for example, if an issue exists with the secured cluster. +==== + +include::modules/rollback-operator-upgrades-cli.adoc[leveloffset=+2] +include::modules/rollback-operator-upgrades-console.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.16/html/operators/understanding-operators#olm-workflow[Operator Lifecycle Manager workflow] +* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.16/html/operators/administrator-tasks#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator update] + +[id="operator-upgrade-troubleshooting_{context}"] +== Troubleshooting Operator upgrade issues + +[role="_abstract"] +Follow these instructions to investigate and resolve upgrade-related issues for the {product-title-short} Operator. + +include::modules/operator-upgrade-fail-to-deploy.adoc[leveloffset=+2] diff --git a/cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc b/cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc new file mode 100644 index 000000000000..cbd11c975be1 --- /dev/null +++ b/cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc @@ -0,0 +1,54 @@ +:_mod-docs-content-type: ASSEMBLY +[id="upgrade-cloudsvc-roxctl"] += Manually upgrading secured clusters in RHACS Cloud Service by using the roxctl CLI +include::modules/common-attributes.adoc[] +:context: upgrade-cloudsvc-roxctl + +toc::[] + +[role="_abstract"] +You can upgrade your secured clusters in {product-title-managed-short} by using the `roxctl` CLI. + +[IMPORTANT] +==== +You need to manually upgrade secured clusters only if you used the `roxctl` CLI to install the secured clusters. +==== + +[id="upgrade-roxctl-cli"] +== Upgrading the `roxctl` CLI + +To upgrade the `roxctl` CLI to the latest version, you must uninstall your current version of the `roxctl` CLI and then install the latest version of the `roxctl` CLI. + +include::modules/uninstall-roxctl-cli.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+2] + +[id="upgrade-secured-clusters-cloud"] +== Upgrading all secured clusters manually + +[IMPORTANT] +==== +To ensure optimal functionality, use the same {product-title-short} version for your secured clusters that {product-title-managed-short} is running. If you are using automatic upgrades, update all your secured clusters by using automatic upgrades. If you are not using automatic upgrades, complete the instructions in this section on all secured clusters. +==== + +To complete manual upgrades of each secured cluster running Sensor, Collector, and Admission controller, follow these instructions. + +include::modules/update-other-images.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../../cli/using-the-roxctl-cli.adoc#authenticating-by-using-the-roxctl-cli_using-roxctl-cli[Authenticating by using the roxctl CLI] + +include::modules/migrating-sccs-during-the-manual-upgrade.adoc[leveloffset=+2] + +include::modules/verify-secured-cluster-upgrade.adoc[leveloffset=+3] + +include::modules/rhcos-enable-node-scan.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../../operating/manage-vulnerabilities/scan-rhcos-node-host.adoc#scan-rhcos-node-host[Scanning {op-system} node hosts] + +* xref:../../operating/examine-images-for-vulnerabilities.adoc#enabling_scanner_v4_examine-images-for-vulnerabilities[Enabling Scanner V4] diff --git a/configuration/add-custom-certificates.adoc b/configuration/add-custom-certificates.adoc new file mode 100644 index 000000000000..68d407adb9e8 --- /dev/null +++ b/configuration/add-custom-certificates.adoc @@ -0,0 +1,54 @@ +[id="add-custom-cert"] += Adding custom certificates +include::modules/common-attributes.adoc[] +:context: add-custom-cert + +toc::[] + +[role="_abstract"] +Learn how to use a custom TLS certificate with {product-title}. After you set up a certificate, users and API clients do not have to bypass the certificate security warnings when connecting to Central. + + +[id="add-custom-security-cert"] +== Adding a custom security certificate +You can apply a security certificate during the installation or on an existing {product-title} deployment. + +//Prerequisites +include::modules/custom-cert-prerequisites.adoc[leveloffset=+2] + +//During a new installation +include::modules/custom-cert-new-install.adoc[leveloffset=+2] + +//On an existing installation +include::modules/custom-cert-existing.adoc[leveloffset=+2] + +//Updating certificates on an existing installation +include::modules/update-custom-certificate-central.adoc[leveloffset=+2] + +//Restart Central +include::modules/restart-central-container.adoc[leveloffset=+3] + +[id="configure-sensor-to-trust-cert"] +== Configuring Sensor to trust custom certificates +If you are using a custom certificate that is not trusted globally, you must configure the Sensor to trust your custom certificate. +Otherwise, you might get errors. +The specific type of error may vary based on your setup and the certificate you use. +Usually, it is an `x509 validation` related error. + +[NOTE] +==== +You do not need to configure the Sensor to trust your custom certificate if you are using a globally trusted certificate. +==== +//Downloading the Sensor bundle +include::modules/download-sensor-bundle.adoc[leveloffset=+2] + +//When deploying a new Sensor +include::modules/trust-cert-new-sensor.adoc[leveloffset=+2] + +//On an existing Sensor +include::modules/trust-cert-existing-sensor.adoc[leveloffset=+2] + +If you added the certificates to an existing sensor, you must restart the Sensor container. + +//Restart Sensor +include::modules/restart-sensor-container.adoc[leveloffset=+3] diff --git a/configuration/add-security-notices.adoc b/configuration/add-security-notices.adoc new file mode 100644 index 000000000000..9ecaadfd583d --- /dev/null +++ b/configuration/add-security-notices.adoc @@ -0,0 +1,19 @@ +[id="add-security-notices"] += Adding security notices +include::modules/common-attributes.adoc[] +:context: add-security-notices + +toc::[] + +[role="_abstract"] +With {product-title}, you can add security notices that users see when they log in. +You can also set up an organization-wide message or disclaimers on the top or bottom of the {product-title-short} portal. + +This message can serve as a reminder of corporate policies and notify employees of the appropriate policies. +Alternatively, you might want to display these messages for legal reasons, for example, to warn users that their actions are audited. + +//Add a custom login message +include::modules/add-a-custom-login-message.adoc[leveloffset=+1] + +//Add a custom header and footer +include::modules/add-a-custom-header-and-footer.adoc[leveloffset=+1] diff --git a/configuration/add-trusted-ca.adoc b/configuration/add-trusted-ca.adoc new file mode 100644 index 000000000000..5f548bca771c --- /dev/null +++ b/configuration/add-trusted-ca.adoc @@ -0,0 +1,55 @@ +[id="add-trusted-ca"] += Adding trusted certificate authorities +include::modules/common-attributes.adoc[] +:context: add-trusted-ca + +toc::[] + +[role="_abstract"] +Learn how to add custom trusted certificate authorities to {product-title}. + +If you are using an enterprise certificate authority (CA) on your network, or self-signed certificates, you must add the CA's root certificate to {product-title} as a trusted root CA. + +Adding trusted root CAs allows: + +* Central and Scanner to trust remote servers when you integrate with other tools. +//TODO: Add link to integration topic +* Sensor to trust custom certificates you use for Central. + +You can add additional CAs during the installation or on an existing deployment. + +[NOTE] +==== +You must first configure your trusted CAs in the cluster where you have deployed Central and then propagate the changes to Scanner and Sensor. +==== + +include::modules/configure-additional-cas.adoc[leveloffset=+1] + +== Propagating changes + +After you configure trusted CAs, you must make {product-title} services trust them. + +* If you have configured trusted CAs after the installation, you must restart Central. +* Additionally, if you are also adding certificates for integrating with image registries, you must restart both Central and Scanner. +//TODO: Add link to integrating with image registries + +//Restart Central +include::modules/restart-central-container.adoc[leveloffset=+2] + +//Restart Scanner +include::modules/restart-scanner-container.adoc[leveloffset=+2] + +[IMPORTANT] +==== +After you have added trusted CAs and configured Central, the CAs are included in any new Sensor deployment bundles that you create. + +* If an existing Sensor reports problems while connecting to Central, you must generate a Sensor deployment YAML file and update existing clusters. +* If you are deploying a new Sensor using the `sensor.sh` script, run the following command before you run the `sensor.sh` script: ++ +[source,terminal] +---- +$ ./ca-setup-sensor.sh -d ./additional-cas/ +---- +* If you are deploying a new Sensor using Helm, you do not have to run any additional scripts. +==== +//TODO: Add link to generate a Sensor deployment YAML file diff --git a/configuration/configure-api-token.adoc b/configuration/configure-api-token.adoc new file mode 100644 index 000000000000..2068a4b97ece --- /dev/null +++ b/configuration/configure-api-token.adoc @@ -0,0 +1,23 @@ +:_mod-docs-content-type: ASSEMBLY +[id="configure-api-token"] += Configuring API tokens +include::modules/common-attributes.adoc[] +:context: configure-api-token + +toc::[] + +[role="_abstract"] +{rh-rhacs-first} requires API tokens for some system integrations, authentication processes, and system functions. You can configure tokens using the {product-title-short} web interface. + +include::snippets/note-about-creating-tokens.adoc[] + +include::modules/create-api-token.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../cli/using-the-roxctl-cli.adoc#using-an-authentication-provider-to-authenticate-with-roxctl_using-roxctl-cli[Using an authentication provider to authenticate with roxctl] +* xref:../operating/manage-user-access/configure-short-lived-access.adoc#configure-short-lived-access[Configuring short-lived access] +* link:https://github.com/stackrox/contributions/blob/main/guides/cloud-provider-integrations/azure-service-principal-m2m-auth.md[Using Azure Entra ID service principals for machine to machine auth with RHACS] + +include::modules/about-api-token-expiration.adoc[leveloffset=+1] + diff --git a/configuration/configure-audit-logging.adoc b/configuration/configure-audit-logging.adoc new file mode 100644 index 000000000000..1bfd93096025 --- /dev/null +++ b/configuration/configure-audit-logging.adoc @@ -0,0 +1,27 @@ +[id="configure-audit-logging"] += Configuring audit logging +include::modules/common-attributes.adoc[] +:context: configure-audit-logging + +toc::[] + +[role="_abstract"] +{product-title} provides audit logging features that you can use to check all the changes made in {product-title}. +The audit log captures all the `PUT` and `POST` events, which are modifications to {product-title}. +Use this information to troubleshoot a problem or to keep a record of important events, such as changes to roles and permissions. +With audit logging you get a complete picture of all normal and abnormal events that happened on {product-title}. + +[NOTE] +==== +Audit logging is not enabled by default. +You must enable audit logging manually. +==== + +[WARNING] +==== +Currently there is no message delivery guarantee for audit log messages. +==== + +include::modules/enable-audit-log.adoc[leveloffset=+1] + +include::modules/sample-audit-log-message.adoc[leveloffset=+1] diff --git a/configuration/configure-automatic-upgrades.adoc b/configuration/configure-automatic-upgrades.adoc new file mode 100644 index 000000000000..c25becc30c33 --- /dev/null +++ b/configuration/configure-automatic-upgrades.adoc @@ -0,0 +1,46 @@ +[id="configure-automatic-upgrades"] += Configuring automatic upgrades for manifest-installed secured clusters +include::modules/common-attributes.adoc[] +:context: configure-automatic-upgrades + +toc::[] + +[role="_abstract"] +If you installed {product-title} by using the manifest installation method, also known as the _`roxctl` CLI method_ or the _legacy installation method_, you can automate the upgrade process for each secured cluster. You can also view the upgrade status from the {product-title-short} portal. + +[NOTE] +==== +Automatic upgrades are only available for {product-title-short} systems that were installed by using the manifest installation method. If you installed {product-title-short} by using the Operator, upgrades are controlled by using {olm-first}. If you installed {product-title-short} by using Helm charts, you must use Helm to upgrade. +==== + +Automatic upgrades make it easier to stay up-to-date by automating the manual task of upgrading each secured cluster. If you have automatic upgrades enabled, and the secured cluster is configured for receiving automated upgrades, the upgrader upgrades the entire secured cluster to the same version as Central. + +The new *Clusters* view displays information about all your secured clusters, the Sensor version for every cluster, and upgrade status messages. +You can also use this view to selectively upgrade your secured clusters or change their configuration. + +[NOTE] +==== +* The automatic upgrade feature is enabled by default. +* If you are using a private image registry, you must first push the Sensor and Collector images to your private registry. +* The Sensor must run with the default RBAC permissions. +* Automatic upgrades do not preserve any patches that you have made to any {product-title-short} services running in your cluster. +However, it preserves all labels and annotations that you have added to any {product-title-short} object. +* By default, {product-title} creates a service account called `sensor-upgrader` in each secured cluster. +This account is highly privileged but is only used during upgrades. +If you remove this account, Sensor does not have enough permissions, and you must complete future upgrades manually. +==== + +include::modules/enable-automatic-upgrades.adoc[leveloffset=+1] + +include::modules/disable-automatic-upgrades.adoc[leveloffset=+1] + +include::modules/automatic-upgrade-status.adoc[leveloffset=+1] + +include::modules/automatic-upgrade-failure.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../upgrading/upgrade-roxctl.adoc#troubleshooting-upgrader_upgrade-roxctl[Troubleshooting the cluster upgrader] + +include::modules/manual-upgrade-secured-clusters.adoc[leveloffset=+1] diff --git a/configuration/configure-endpoints.adoc b/configuration/configure-endpoints.adoc new file mode 100644 index 000000000000..2f532038f3ad --- /dev/null +++ b/configuration/configure-endpoints.adoc @@ -0,0 +1,23 @@ +[id="configure-endpoints"] += Configuring endpoints +include::modules/common-attributes.adoc[] +:context: configure-endpoints + +toc::[] + +[role="_abstract"] +Learn how to configure endpoints for {product-title} ({product-title-short}) by using a YAML configuration file. + +You can use a YAML configuration file to configure exposed endpoints. +You can use this configuration file to define one or more endpoints for {product-title} and customize the TLS settings for each endpoint, or disable the TLS for specific endpoints. +You can also define if client authentication is required, and which client certificates to accept. + +include::modules/custom-yaml-configuration.adoc[leveloffset=+1] + +include::modules/configure-endpoints-new-install.adoc[leveloffset=+1] + +include::modules/configure-endpoints-existing.adoc[leveloffset=+1] + +include::modules/restart-central-container.adoc[leveloffset=+2] + +include::modules/enable-traffic-flow-through-custom-ports.adoc[leveloffset=+1] diff --git a/configuration/configure-inactive-cluster-deletion.adoc b/configuration/configure-inactive-cluster-deletion.adoc new file mode 100644 index 000000000000..a1cd9c95d277 --- /dev/null +++ b/configuration/configure-inactive-cluster-deletion.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: ASSEMBLY +[id="configure-nonactive-cluster-removal"] += Configuring automatic removal of nonactive clusters from RHACS +include::modules/common-attributes.adoc[] +:context: configure-nonactive-cluster-removal + +toc::[] + +[role="_abstract"] +{product-title} ({product-title-short}) provides the option to configure your system to automatically remove nonactive clusters from {product-title-short} so that you can monitor active clusters only. Note that only clusters that were installed and performed a handshake with Central at least one time are monitored initially. If this feature is enabled, when Central has been unable to reach Sensor in a cluster for the period of time configured in the *Decomissioned cluster age* field, the cluster is considered nonactive in {product-title-short}. Central will then no longer monitor nonactive clusters. You can configure the *Decommissioned cluster age* field in the *Platform Configuration* -> *System Configuration* page. When configuring this feature, you can add a label for the cluster so that {product-title-short} continues to monitor the cluster even if it becomes nonactive. + +Removal of nonactive clusters from {product-title-short} is disabled by default. To enable this setting, enter a nonzero number in the *Decommissioned cluster age* field, as described in the following procedure. The *Decommissioned cluster age* field indicates the number of days that a cluster can remain unreachable before it is considered nonactive. When a cluster is nonactive, the *Clusters* page displays the status of the cluster. Nonactive clusters are indicated with the `unhealthy` label and the window shows the number of days after which the cluster will be removed from {product-title-short} if it continues to remain nonactive. After a cluster is removed from {product-title-short}, that action is documented with an `info` log in the Central logs. + +[NOTE] +==== +There is a 24-hour grace period after enabling this setting before clusters are removed. The cluster that hosts Central is never removed. +==== + + +include::modules/configure-cluster-decommissioning.adoc[leveloffset=+1] +include::modules/view-nonactive-clusters.adoc[leveloffset=+1] diff --git a/configuration/configure-proxy.adoc b/configuration/configure-proxy.adoc new file mode 100644 index 000000000000..b46ce1c413b7 --- /dev/null +++ b/configuration/configure-proxy.adoc @@ -0,0 +1,23 @@ +[id="configure-proxy"] += Configuring a proxy for external network access +include::modules/common-attributes.adoc[] +:context: configure-proxy + +toc::[] + +[role="_abstract"] +If your network configuration restricts outbound traffic through proxies, you can configure proxy settings in {product-title} to route traffic through a proxy. + +When you use a proxy with {product-title}: + +* All outgoing HTTP, HTTPS, and other TCP traffic from Central and Scanner goes through the proxy. +* Traffic between Central and Scanner does not go through the proxy. +* The proxy configuration does not affect the other {product-title} components. +* When you are not using the offline mode, and a Collector running in a secured cluster needs to download an additional eBPF probe at runtime: +** The collector attempts to download them by contacting Sensor. +** The Sensor then forwards this request to Central. +** Central uses the proxy to locate the module or probe at `\https://collector-modules.stackrox.io`. + +include::modules/configure-proxy-on-an-existing-deployment.adoc[leveloffset=+1] + +include::modules/configure-proxy-during-installation.adoc[leveloffset=+1] diff --git a/configuration/configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub.adoc b/configuration/configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub.adoc new file mode 100644 index 000000000000..5922505451d5 --- /dev/null +++ b/configuration/configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: ASSEMBLY +[id="configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub"] += Configuring and integrating the RHACS plugin with Red Hat Developer Hub +include::modules/common-attributes.adoc[] +:context: configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub + +toc::[] + +By configuring and integrating the {rh-rhacs-first} plugin with {rh-rhdh-first}, you can view the security information for your deployments in {rh-rhdh}. + +:FeatureName: Integration of vulnerability findings into the {rh-rhdh} +include::snippets/technology-preview.adoc[] + +//Viewing security information in {rh-rhdh} +include::modules/viewing-security-information-in-red-hat-developer-hub.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../configuration/configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub.adoc#rebuilding-the-oci-artifact_configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub[Rebuilding the OCI artifact] + +//Rebuilding the OCI artifact +include::modules/rebuilding-the-oci-artifact.adoc[leveloffset=+1] \ No newline at end of file diff --git a/configuration/customizing-platform-components.adoc b/configuration/customizing-platform-components.adoc new file mode 100644 index 000000000000..ed7cfebfc14a --- /dev/null +++ b/configuration/customizing-platform-components.adoc @@ -0,0 +1,18 @@ +:_mod-docs-content-type: ASSEMBLY +[id="customizing-platform-components_{context}"] += Customizing platform components +include::modules/common-attributes.adoc[] +:context: customizing-platform-components + +toc::[] + +[role="_abstract"] +{rh-rhacs-first} includes enhanced capabilities to classify violations and vulnerabilities into User Workload or Platform categories. Thus helping you focus on actionable data by segmenting issues based on who is responsible for addressing them. + +User workloads refer to the applications and images you deploy and manage directly. Platform components include the underlying infrastructure, Operators, and third-party services. By categorizing security findings, {product-title-short} helps you maintain oversight while prioritizing fixes for issues they directly control. + +{product-title-short} automatically identifies platform components based on predefined namespaces. Additionally, you can also customize which namespaces {product-title-short} identify as platform components. You can address platform issues by upgrading the offending component, such as {ocp} or third-party software, rather than requiring direct user remediation. Thus, by customizing platform components, you can focus on actionable security findings within your user workloads + +include::modules/understanding-platform-components.adoc[leveloffset=+1] + +include::modules/modifying-platform-component-definitions.adoc[leveloffset=+1] diff --git a/configuration/declarative-configuration-using.adoc b/configuration/declarative-configuration-using.adoc new file mode 100644 index 000000000000..2fe1bcbe8af3 --- /dev/null +++ b/configuration/declarative-configuration-using.adoc @@ -0,0 +1,41 @@ +:_mod-docs-content-type: ASSEMBLY +[id="declarative-configuration-using"] += Using declarative configuration +:context: declarative-configuration-using +include::modules/common-attributes.adoc[] + +toc::[] + +[role="_abstract"] + +With declarative configuration, you can update configurations by storing them in files in repositories and apply them to the system. Declarative configuration is useful, for example, if you are using a GitOps workflow. You can currently use declarative configuration in {rh-rhacs-first} for authentication and authorization resources such as authentication providers, roles, permission sets, and access scopes. + +To use declarative configuration, you create YAML files that contain configuration information about authentication and authorization resources. These files, or configurations, are added to {product-title-short} by using a mount point during Central installation. See the installation documentation in the "Additional resources" section for more information on configuring mount points when installing {product-title-short}. + +The configuration files used with declarative configuration are stored in config maps or secrets, depending on the type of resource. Store configurations for authentication providers in a secret for greater security. You can store other configurations in config maps. + +A single config map or secret can contain more than one configuration of multiple resource types. This allows you to limit the number of volume mounts for the Central instance. + +[id="restrictions-declarative-config-resources"] +== Restrictions for resources created from declarative configuration + +Because resources can reference other resources (for example, a role can reference both a permission set and access scope), the following restrictions for references apply: + +* A declarative configuration can only reference a resource that is either also created declaratively or a system {product-title-short} resource; for example, a resource such as the `Admin` or `Analyst` system role or permission set. +* All references between resources use names to identify the resource; therefore, all names within the same resource type must be unique. +* Resources created from declarative configuration can only be modified or deleted by altering the declarative configuration files. You cannot change these resources by using the {product-title-short} portal or the API. + +include::modules/declarative-configuration-resource-create.adoc[leveloffset=+1] + +include::modules/declarative-configuration-examples.adoc[leveloffset=+1] + +include::modules/declarative-configuration-troubleshooting.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_declarative-configuration-using"] +== Additional resources + +* xref:../installing/installing_ocp/install-central-ocp.adoc#install-using-helm-customizations-ocp[Install Central using Helm charts with customizations (Red{nbsp}Hat OpenShift)] +* xref:../installing/installing_other/install-central-other.adoc#install-using-helm-customizations-other[Install Central using Helm charts with customizations (other Kubernetes platforms)] +* xref:../operating/manage-user-access/configure-short-lived-access.adoc#configure-short-lived-access_configure-short-lived-access[Configuring short-lived access] +* xref:../integration/integrate-using-short-lived-tokens.adoc#integrate-using-short-lived-tokens[Integrating {product-title-short} using short-lived tokens] diff --git a/configuration/enable-alert-data-retention.adoc b/configuration/enable-alert-data-retention.adoc new file mode 100644 index 000000000000..fc6b5b1ac780 --- /dev/null +++ b/configuration/enable-alert-data-retention.adoc @@ -0,0 +1,30 @@ +[id="enable-alert-data-retention"] += Enabling alert data retention +include::modules/common-attributes.adoc[] +:context: enable-alert-data-retention + +toc::[] + +[role="_abstract"] +Learn how to configure a retention period for {product-title} alerts. + +With {product-title}, you can configure the time to keep historical alerts stored. +{product-title} then deletes the older alerts after the specified time. + +By automatically deleting alerts that are no longer needed, you can save storage costs. + +The alerts for which you can configure the retention period include: + +* Runtime alerts, both unresolved (active) and resolved. +* Stale deploy-time alerts that do not apply to the current deployment. + +[NOTE] +==== +* Data retention settings are enabled by default. You can change these settings after the installation. +* When you upgrade {product-title}, data retention settings are not applied unless you have enabled them before. +* You can configure alert retention settings by using the {product-title-short} portal or the API. +* The deletion process runs every hour. +Currently, you cannot change this. +==== + +include::modules/configure-alert-data-retention.adoc[leveloffset=+1] diff --git a/configuration/enable-offline-mode.adoc b/configuration/enable-offline-mode.adoc new file mode 100644 index 000000000000..3662a3fce8d1 --- /dev/null +++ b/configuration/enable-offline-mode.adoc @@ -0,0 +1,89 @@ +:_mod-docs-content-type: ASSEMBLY +[id="enable-offline-mode"] += Enabling offline mode +include::modules/common-attributes.adoc[] +:context: enable-offline-mode + +toc::[] + +[role="_abstract"] +You can use {product-title} for clusters that are not connected to the internet by enabling the offline mode. In offline mode, {product-title} components do not connect to addresses or hosts on the internet. + +[NOTE] +==== +{product-title} does not determine if the user-supplied hostnames, IP addresses, or other resources are on the internet. For example, if you try to integrate with a Docker registry hosted on the internet, {product-title} will not block this request. +==== + +To deploy and operate {product-title} in offline mode: + +. Download {product-title-short} images and install them in your clusters. If you are using {ocp}, you can use link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.12/html/operators/understanding-operators#operator-lifecycle-manager-olm[{olm-first}] and OperatorHub to download images to a workstation that is connected to the internet. The workstation then pushes images to a mirror registry that is also connected to your secured cluster. For other platforms, you can use a program such as Skopeo or Docker to pull the images from the remote registry and push them to your own private registry, as described in xref:../configuration/enable-offline-mode.adoc#download-images-for-offline-use[Downloading images for offline use]. +. Enable offline mode during installation. +. Update Scanner’s vulnerability list by uploading a new definitions file at least once per day. + +[IMPORTANT] +==== +You can only enable offline mode during the installation, and not during an upgrade. +==== + +[id="download-images-for-offline-use"] +== Downloading images for offline use + +include::modules/image-versions.adoc[leveloffset=+2] + +include::modules/retag-images.adoc[leveloffset=+3] + +[id="enable-offline-mode-during-installation"] +== Enabling offline mode during installation + +You can enable offline mode during the installation of {product-title}. + +include::modules/enable-offline-mode-helm.adoc[leveloffset=+2] + +include::modules/enable-offline-mode-roxctl.adoc[leveloffset=+2] + + +[id="update-scanner-definitions-in-offline-mode"] +== Updating Scanner definitions in offline mode + +Scanner maintains a database of vulnerabilities. When {rh-rhacs-first} runs in normal mode, Central retrieves the latest vulnerability data from the internet, and Scanner retrieves vulnerability data from Central. +//TODO: Add link to Vulnerability definitions + +However, if you are using {product-title-short} in offline mode, you must manually update the vulnerability data. To manually update the vulnerability data, you must upload a definitions file to Central, and Scanner then retrieves the vulnerability data from Central. + +In both online and offline mode, Scanner checks for new data from Central every 5 minutes by default. In online mode, Central also checks for new data from the internet approximately every 5-20 minutes. + +The offline data source is updated approximately every 3 hours. After the data has been uploaded to Central, Scanner downloads the data and updates its local vulnerability database. + +To update the definitions in offline mode, perform the following steps: + +. Download the definitions. +. Upload the definitions to Central. + +//Download the definitions +include::modules/download-scanner-definitions.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-scanner.adoc#roxctl-scanner-download-db_roxctl-scanner[roxctl scanner download-db] + +[id="upload-definitions-to-central"] +=== Uploading definitions to Central + +To upload Scanner definitions to Central, you can either use an API token or your administrator password. Red{nbsp}Hat recommends using an authentication token in a production environment because each token is assigned specific access control permissions. + +//Upload the definitions to Central (API Token) +include::modules/upload-definitions-to-central-api-token.adoc[leveloffset=+3] + +[role="_additional-resources"] +===== Additional resources +* xref:../cli/using-the-roxctl-cli.adoc#authenticating-by-using-the-roxctl-cli_using-roxctl-cli[Authenticating by using the roxctl CLI] + +//Upload the definitions to Central (admin password) +include::modules/upload-definitions-to-central-admin-pass.adoc[leveloffset=+3] + +include::modules/update-kernel-support-packages.adoc[leveloffset=+1] + +include::modules/download-kernel-support-package.adoc[leveloffset=+2] + +include::modules/upload-kernel-support-package-to-central.adoc[leveloffset=+2] \ No newline at end of file diff --git a/configuration/expose-portal-over-http.adoc b/configuration/expose-portal-over-http.adoc new file mode 100644 index 000000000000..22164cd2aec0 --- /dev/null +++ b/configuration/expose-portal-over-http.adoc @@ -0,0 +1,51 @@ +[id="expose-portal-over-http"] += Exposing the RHACS portal over HTTP +include::modules/common-attributes.adoc[] +:context: expose-portal-over-http + +toc::[] + +[role="_abstract"] +Enable an unencrypted HTTP server to expose the {product-title-short} portal through ingress controllers, Layer 7 load balancers, Istio, or other solutions. + +If you use an ingress controller, Istio, or a Layer 7 load balancer that prefers unencrypted HTTP back ends, you can configure {product-title} to expose the {product-title-short} portal over HTTP. +Doing this makes the {product-title-short} portal available over a plaintext back end. + +[IMPORTANT] +==== +To expose the {product-title-short} portal over HTTP, you must be using an ingress controller, a Layer 7 load balancer, or Istio to encrypt external traffic with HTTPS. +It is insecure to expose the {product-title-short} portal directly to external clients by using plain HTTP. +==== +//TODO Add a link to the endpoint configuration topic as the recommended way to expose portal. + +You can expose the {product-title-short} portal over HTTP during installation or on an existing deployment. + +== Prerequisites + +* To specify an HTTP endpoint you must use an ``. +It is a comma-separated list of single endpoint specifications in the form of `@:`, where: + +** `type` is `grpc` or `http`. Using `http` as type works in most use cases. +For advanced use cases, you can either use `grpc` or omit its value. +If you omit the value for `type`, you can configure two endpoints in your proxy, one for gRPC and the other for HTTP. +Both these endpoints point to the same exposed HTTP port on Central. +However, most proxies do not support carrying both gRPC and HTTP traffic on the same external port. +** `addr` is the IP address to expose Central on. +You can omit this, or use `localhost` or `127.0.0.1` if you need an HTTP endpoint which is only accessible by using port-forwarding. +** `port` is the port to expose Central on. +** The following are several valid `` values: + +*** `8080` +*** `http@8080` +*** `:8081` +*** `grpc@:8081` +*** `localhost:8080` +*** `http@localhost:8080` +*** `http@8080,grpc@8081` +*** `8080, grpc@:8081, http@0.0.0.0:8082` + +include::modules/expose-portal-http-during-installation.adoc[leveloffset=+1] + +include::modules/expose-portal-http-existing-deployment.adoc[leveloffset=+1] + +// TODO: Add link to Configure endpoints topic \ No newline at end of file diff --git a/configuration/generate-diagnostic-bundle.adoc b/configuration/generate-diagnostic-bundle.adoc new file mode 100644 index 000000000000..15d4ebf31501 --- /dev/null +++ b/configuration/generate-diagnostic-bundle.adoc @@ -0,0 +1,24 @@ +[id="generate-diagnostic-bundle"] += Generating a diagnostic bundle +include::modules/common-attributes.adoc[] +:context: generate-diagnostic-bundle + +toc::[] + +[role="_abstract"] +You can generate a diagnostic bundle and send that data to enable the support team to provide insights into the status and health of {product-title} components. + +Red{nbsp}Hat might request you to send the diagnostic bundle during investigation of your issues with {product-title}. +You can generate a diagnostic bundle and inspect its data before sending. + +[NOTE] +==== +The diagnostic bundle is unencrypted, and depending upon the number of clusters in your environment, the bundle size is between 100 KB and 1 MB. +Always use an encrypted channel to transfer this data back to Red{nbsp}Hat. +==== + +include::modules/diagnostic-bundle-data.adoc[leveloffset=+1] + +include::modules/generate-diagnostic-bundle-using-acs-portal.adoc[leveloffset=+1] + +include::modules/generate-diagnostic-bundle-using-roxctl-cli.adoc[leveloffset=+1] diff --git a/jaeger/jaeger_install/images b/configuration/images similarity index 100% rename from jaeger/jaeger_install/images rename to configuration/images diff --git a/configuration/internal-certificate-authority-rotation-for-rhacs.adoc b/configuration/internal-certificate-authority-rotation-for-rhacs.adoc new file mode 100644 index 000000000000..e51a9569b4ed --- /dev/null +++ b/configuration/internal-certificate-authority-rotation-for-rhacs.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: ASSEMBLY +[id="internal-certificate-authority-rotation-for-rhacs"] += Internal certificate authority rotation for RHACS +include::modules/common-attributes.adoc[] +:context: internal-certificate-authority-rotation-for-rhacs + +toc::[] + +[role="_abstract"] + +Certificate authority (CA) rotation is important in {rh-rhacs-first} to ensure that Central and secured clusters can communicate. +{product-title-short} includes an internal CA that is valid for 5 years. Central and secured cluster service certificates depend on this CA. If the CA expires, {product-title-short} stops working. + +Previously, if the internal CA expired, you had to delete the `central-tls` secret and manually re-register all the secured clusters. Starting with {product-title-short} 4.9, the Operator manages CA rotation. Central simultaneously trusts two CAs, enabling overlap and providing a smoother migration. + +//CA rotation support for different installation methods +include::modules/ca-rotation-support-for-different-installation-methods.adoc[leveloffset=+1] + +//Preparing for deployments and upgrades +include::modules/preparing-for-deployments-and-upgrades.adoc[leveloffset=+1] \ No newline at end of file diff --git a/configuration/inviting-users-to-your-rhacs-instance.adoc b/configuration/inviting-users-to-your-rhacs-instance.adoc new file mode 100644 index 000000000000..4ebf95e0ec4e --- /dev/null +++ b/configuration/inviting-users-to-your-rhacs-instance.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: ASSEMBLY +[id="inviting-users-to-your-rhacs-instance"] += Inviting users to your {product-title-short} instance +include::modules/common-attributes.adoc[] +:context: inviting-users-to-your-rhacs-instance + +toc::[] + +[role="_abstract"] +By inviting users to {rh-rhacs-first}, you can ensure that the right users have the appropriate access rights within your cluster. You can invite one or more users by assigning roles and defining the authentication provider. + +//Configuring access control and sending invitations +include::modules/configuring-access-control-and-sending-invitations.adoc[leveloffset=+1] \ No newline at end of file diff --git a/configuration/managing-preview-features.adoc b/configuration/managing-preview-features.adoc new file mode 100644 index 000000000000..a80fec000284 --- /dev/null +++ b/configuration/managing-preview-features.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: ASSEMBLY +[id="managing-preview-features"] += Managing technology preview features +include::modules/common-attributes.adoc[] +:context: managing-preview-features + +toc::[] + +[role="_abstract"] + +You can enable or disable features that are Technology Preview by using feature flags. + +[IMPORTANT] +==== +[subs="attributes+"] +Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. +==== + +//Managing feature flags +include::modules/managing-feature-flags.adoc[leveloffset=+1] diff --git a/jaeger/jaeger_config/modules b/configuration/modules similarity index 100% rename from jaeger/jaeger_config/modules rename to configuration/modules diff --git a/configuration/monitor-acs.adoc b/configuration/monitor-acs.adoc new file mode 100644 index 000000000000..9e024adc950b --- /dev/null +++ b/configuration/monitor-acs.adoc @@ -0,0 +1,27 @@ +[id="monitor-acs"] += Monitoring RHACS +include::modules/common-attributes.adoc[] +:context: monitor-acs + +toc::[] + +[role="_abstract"] +You can monitor {rh-rhacs-first} by using the built-in monitoring for {osp} or by using custom Prometheus monitoring. + +If you use {product-title-short} with {osp}, link:https://docs.openshift.com/container-platform/4.13/monitoring/monitoring-overview.html[{ocp}] includes a preconfigured, preinstalled, and self-updating monitoring stack that provides monitoring for core platform components. {product-title-short} exposes metrics to {osp} monitoring via an encrypted and authenticated endpoint. + +include::modules/monitoring-osp.adoc[leveloffset=+1] +include::modules/monitoring-custom-prometheus.adoc[leveloffset=+1] +include::modules/monitor-osp-disable-operator.adoc[leveloffset=+2] +include::modules/monitor-osp-disable-helm.adoc[leveloffset=+2] +include::modules/enable-monitoring-central-operator.adoc[leveloffset=+2] +include::modules/enable-monitoring-central-helm.adoc[leveloffset=2] +include::modules/prometheus-service-monitor.adoc[leveloffset=+2] + +[role="_additional-resources"] +[id="additional-resources_monitoring-acs"] +== Additional resources + +* xref:../installing/installing_ocp/install-central-config-options-ocp.adoc#install-central-config-options-ocp[Central configuration options using the Operator] +* xref:../installing/installing_other/install-central-other.adoc#change-config-options-after-deployment-central-services_install-central-other[Changing configuration options after deploying the central-services Helm chart] +* link:https://helm.sh/docs/helm/helm_install/#synopsis[Helm documentation] \ No newline at end of file diff --git a/configuration/reissue-internal-certificates.adoc b/configuration/reissue-internal-certificates.adoc new file mode 100644 index 000000000000..3d84e99148fa --- /dev/null +++ b/configuration/reissue-internal-certificates.adoc @@ -0,0 +1,61 @@ +:_mod-docs-content-type: ASSEMBLY +[id="reissue-internal-certificates"] += Reissuing internal certificates +include::modules/common-attributes.adoc[] +:context: reissue-internal-certificates + +toc::[] + +[role="_abstract"] +Each component of {product-title} uses an X.509 certificate to authenticate itself to other components. +These certificates have expiration dates, and you must reissue, or rotate, certificates before they expire. +You can view the certificate expiration dates by selecting *Platform Configuration* -> *Clusters* in the {product-title-short} portal and viewing the *Credential Expiration* column. + +//Add link to role based permissions and resources + +//reissue internal certificates for Central +include::modules/reissue-internal-certificates-central.adoc[leveloffset=+1] + +//Restart Central +include::modules/restart-central-container.adoc[leveloffset=+2] + +//reissue internal certificates for Scanner +include::modules/reissue-internal-certificates-scanner.adoc[leveloffset=+1] + +//Restart Scanner & Scanner DB +include::modules/restart-scanner-and-scannerdb-containers.adoc[leveloffset=+2] + +[id="reissue-internal-certificates-secured-clusters_{context}"] +== Reissuing internal certificates for secured clusters +Secured clusters contain the Collector, Sensor, Admission Control, and local Scanner components. +These components communicate with each other, and with Central by using certificates. + +Choose the appropriate method to reissue the internal certificates: + +* Use the automatic certificate renewal feature. This is the recommended method for Operator and Helm deployments. +* Create, download, and install an init bundle on the secured cluster. You must have the `Admin` user role to create an init bundle. This method is only recommended for Operator and Helm deployments if the certificates have already expired and the secured cluster can no longer connect to Central. +* Use the automatic upgrades feature, which is only available for static manifest deployments by using the `roxctl` CLI. This method is only recommended if you have a specific installation requirement that necessitates the use of this method. + +//automatic certificate renewal +include::modules/reissuing-internal-certificates-for-secured-clusters-by-using-automatic-certificate-renewal.adoc[leveloffset=+2] + +//Verifying the status of automatic certificate renewal +include::modules/verifying-the-status-of-automatic-certificate-renewal.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources + +* xref:../configuration/reissue-internal-certificates.adoc#applying-the-latest-internal-certificates_reissue-internal-certificates[Applying the latest internal certificates] + +//Applying the latest internal certificates +include::modules/applying-the-latest-internal-certificates.adoc[leveloffset=+3] + +//create and install an init bundle +include::modules/reissue-internal-certificates-secured-clusters.adoc[leveloffset=+2] + +//reissue internal certificates for secured clusters by using automatic upgrades +include::modules/reissue-internal-certificates-secured-clusters-automatic-upgrades.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../installing/installing_ocp/install-central-ocp.adoc#install-using-roxctl-ocp[Install Central using the roxctl CLI] \ No newline at end of file diff --git a/configuration/snippets b/configuration/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/configuration/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/configuration/using-rhacs-with-gitops.adoc b/configuration/using-rhacs-with-gitops.adoc new file mode 100644 index 000000000000..be63d36a3c92 --- /dev/null +++ b/configuration/using-rhacs-with-gitops.adoc @@ -0,0 +1,25 @@ +:_mod-docs-content-type: ASSEMBLY +[id="using-rhacs-with-gitops"] += Using RHACS with GitOps +include::modules/common-attributes.adoc[] +:context: using-rhacs-with-gitops + +toc::[] + +You can configure key {product-title-short} attributes by using GitOps workflows by storing the values as code and applying them to {product-title-short} declaratively. + +{product-title-short} provides the following two different mechanisms to control two different sets of attributes: + +* _Declarative configuration_ is a lightweight mechanism that uses config maps and secrets to configure mostly authentication and authorization resources. +* _Policy as code_ leverages an {product-title-short}-provided custom resource (CR), along with its controller, to manage {product-title-short} policies. + +include::modules/config-using-declarative-config.adoc[leveloffset=+1] + +include::modules/config-using-policy-as-code.adoc[leveloffset=+1] + + +[role="_additional-resources"] +.Additional resources + +* xref:../configuration/declarative-configuration-using.adoc#declarative-configuration-using[Using declarative configuration] +* xref:../operating/manage_security_policies/custom-security-policies.adoc#policy-as-code-about_custom-security-policies[Managing policies as code] \ No newline at end of file diff --git a/contributing_to_docs/contributing.adoc b/contributing_to_docs/contributing.adoc deleted file mode 100644 index 877edddc6522..000000000000 --- a/contributing_to_docs/contributing.adoc +++ /dev/null @@ -1,218 +0,0 @@ -[id="contributing-to-docs-contributing"] -= Contribute to OpenShift documentation -:icons: -:toc: macro -:toc-title: -:toclevels: 1 -:description: Basic information about the OpenShift GitHub repository - -toc::[] - -== Different ways to contribute -There are a few different ways you can contribute to OpenShift documentation: - -// * Submit comments at the bottom of each topic (still awaiting implementation) -* Email the OpenShift documentation team openshift-docs@redhat.com -* https://github.com/openshift/openshift-docs/issues/new[Create an issue in GitHub] -* Submit a PR. You can clone the repository, make your changes, and submit a PR. -This option is best if you have substantial changes. If you open a PR, be sure -that all of its contents are related and apply to the same versions. - -*What happens when you submit a PR?* - -The -https://github.com/orgs/openshift/teams/team-documentation[documentation team] -reviews the PR and arranges further review by the development and quality -assurance teams, as required. -If the PR requires changes, updates, or corrections, we will let you know -in the PR. We might request that you make the changes, or let you know that we -incorporated your content in a different PR. When the PR has been reviewed, all -updates are complete, and all commits are squashed, we'll merge your PR and -apply it to the valid versions. - -== Repository organization -Each top directory in the OpenShift documentation repository can include a -collection of top level assemblies and subdirectories that contain more -assemblies. The exceptions to this rule are directories whose names -start with an underscore (like `_builder_lib` and `_javascripts`), which contain -the assets used to generate the finished documentation. - -Each top level `` directory contains AsciiDoc assembly files, any `` -subdirectories, and symlinks to the `images` and `modules` directories that -contain all the images and modules for the collection. - ----- -/ -/topic_dir1 -/subtopic_dir1 -/subtopic_dirN -/topic_dir/assembly1.adoc -/topic_dir/assemblyN.adoc -/topic_dir/subtopic_dir1/assembly1.adoc -/topic_dir/subtopic_dirN/assemblyN.adoc -/topic_dir/~images -/topic_dir/~modules -... -/topic_dir2 ----- - -== Version management -Most of the content applies to all five OpenShift products: OKD, OpenShift -Online, OpenShift Dedicated, Azure Red Hat OpenShift and OpenShift Container Platform. While a large -amount of content is reused for all product collections, some information -applies to only specific collections. Content inclusion and exclusion is managed -on the assembly level by specifying distributions in the -`_topic_map.yml` file or by using `ifdef/endif` statements in individual -files. - -//// -While it is _possible_ -to accomplish this solely with Git branches to maintain slightly different -versions of a given topic, doing so would make the task of maintaining internal -consistency extremely difficult for content contributors. - -Git branching is still extremely valuable, and serves the important role of -tracking the release versions of documentation for the various OpenShift -products. -//// - -=== Conditional text between products -OpenShift documentation uses AsciiDoc's `ifdef/endif` macro to conditionalize -and reuse content across the different OpenShift products, down to the -single-line level. - -The supported distribution attributes used with the OpenShift build mechanism -are: - -* _openshift-origin_ -* _openshift-online_ -* _openshift-enterprise_ -* _openshift-dedicated_ -* _openshift-aro_ -* _openshift-webscale_ - -These attributes can be used by themselves or in conjunction to conditionalize -text within a topic document. - -Here is an example of this concept in use: - ----- -This first line is unconditionalized, and will appear for all versions. - -\ifdef::openshift-online[] -This line will only appear for OpenShift Online. -\endif::[] - -ifdef::openshift-enterprise -This line will only appear for OpenShift Container Platform. -\endif::[] - -ifdef::openshift-origin,openshift-enterprise -This line will appear for OKD and OpenShift Container Platform, but not for OpenShift Online or OpenShift Dedicated. -\endif::[] ----- - -Note that the following limitation exists when conditionalizing text: - -* While the `ifdef/endif` blocks have no size limit, do not use them to -to conditionalize an entire file. If an entire file is specific to a -only some OpenShift distributions, specify them in the `_topic_map.yml` -file. - -== Release branches -With the combination of conditionalizing content within files with -`ifdef/endif` and conditionalizing whole files in the `_topic_map.yml` -file, the `master` branch of -this repository always contains a complete set of documentation for all -OpenShift products. However, when and as new versions of an OpenShift product -are released, the `master` branch is merged down to new or existing release -branches. Here is the general naming scheme used in the branches: - -* `master` - This is our *working* branch. -* `enterprise-N.N` - OpenShift Container Platform support releases. The docs -for OpenShift Online and OpenShift Dedicated are based on the appropriate -`enterprise-N.N` branch. - -On a 12-hourly basis, the documentation web sites are rebuilt for each of these -branches. This way the published content for each released version of an -OpenShift product will remain the same while development continues on the -`master` branch. Additionally, any corrections or additions that are -"cherry-picked" into the release branches will show up in the published -documentation after 12 hours. - -[NOTE] -==== -All OpenShift content development for the 4.x stream occurs on the `master`, or - *working* branch. -Therefore, when submitting your work the PR must be created against the `master` -branch. After it is reviewed, a writer will apply the content to the relevant -release branches. If you know which branches a change applies to, be sure to -specify it in your PR. - -When adding or updating content for version 3.11, you should create a feature -branch against enterprise-3.11 to submit your changes. -==== - -== Adding files to the collection -After you create files, you must add them to the `_topic_map.yml` so -that the build system can render them. The documentation build system reads -the `_distro_map.yml` from the master branch to determine -which branches to build and then the `_topic_map.yml` file -for each of the branches -to construct the content from the source files and publish to the relevant -product site at https://docs.openshift.com. The build system _only_ reads this -file to determine which topic files to include. Therefore, all new topics that -are created must be included in the `_topic_map.yml` file in -order to be processed by the build system. - -=== Topic map file format -The `_topic_map.yml` file uses the following format: - ----- ---- //<1> -Name: Origin of the Species <2> -Dir: origin_of_the_species <3> -Distros: all <4> -Topics: - - Name: The Majestic Marmoset <5> - File: the_majestic_marmoset <6> - Distros: all - - Name: The Curious Crocodile - File: the_curious_crocodile - Distros: openshift-online,openshift-enterprise <4> - - Name: The Numerous Nematodes - Dir: the_numerous_nematodes <7> - Topics: - - Name: The Wily Worm <8> - File: the_wily_worm - - Name: The Acrobatic Ascarid <= Sub-topic 2 name - File: the_acrobatic_ascarid <= Sub-topic 2 file under / ----- -<1> Record separator at the top of each topic group. -<2> Display name of topic group. -<3> Directory name of topic group. -<4> Which OpenShift versions this topic group is part of. -* The *Distros* setting is optional for topic groups and topic items. By -default, if the *Distros* setting is not used, it is processed as if it was set -to *Distros: all* for that particular topic or topic group. This means that -topic or topic group will appear in all product documentation versions. -* The *all* value for *Distros* is a synonym for -_openshift-origin,openshift-enterprise,openshift-online,openshift-dedicated,openshift-aro,openshift-webscale_. -* The *all* value overrides other values, so _openshift-online,all_ is processed -as *all*. -<5> Topic name. -<6> Topic file under the topic group dir without `.adoc`. -<7> This topic is actually a subtopic group. Instead of a `File` path it has a -`Dir` path and `Topics`, just like a top-level topic group. -<8> Topics belonging to a subtopic group are listed just like regular topics -with a `Name` and `File`. - -== Next steps -* First, you should link:tools_and_setup.adoc[install and set up the tools and software] -on your workstation so that you can contribute. -* Next, link:doc_guidelines.adoc[review the documentation guidelines] to -understand some basic guidelines to keep things consistent -across our content. -* If you are ready to create content, or want to edit existing content, the -link:create_or_edit_content.adoc[create or edit content] topic describes how -you can do this by creating a working branch. diff --git a/contributing_to_docs/contributing_user_stories.adoc b/contributing_to_docs/contributing_user_stories.adoc deleted file mode 100644 index ad790021f648..000000000000 --- a/contributing_to_docs/contributing_user_stories.adoc +++ /dev/null @@ -1,97 +0,0 @@ -[[contributing-user-stories]] -= Contribute user stories to OpenShift documentation -:icons: -:toc: macro -:toc-title: -:toclevels: 1 -:description: Basic information about how to create user stories for OpenShift GitHub repository - -toc::[] - -== Modularization backstory -OpenShift docs are getting modularized, starting from OpenShift 4.1. -All existing content will be completely replaced with content that is based on user stories and -complies with the modularization guidelines. All future content must both -support a user story and be modular. - -== How do I contribute modularized content? -To contribute modularized content, you need to write a user story, create -documentation modules to support the user story, and create an assembly for the -story. - -== What if I don't want to write in modules? -If you don't want to write the modules yourself but have a content change, -write a user story, provide details to support the story, and reach out to the -OpenShift docs team. - -== How do I write a user story? Is there a template? -Instead of a template, we have a series of questions for you to answer to -create the user story. Follow the same steps if you are writing the modules -yourself or if you plan to work with the docs team. - -The basic format of a user story is: - ----- -As a , I want to because . ----- - -For example, "As a cluster administrator, I want to enable an Auto Scaling group to manage my OpenShift Enterprise -cluster deployed on AWS because I want my node count to scale based on application demand." - -Use the following questions to guide you in providing the context for your user story and the necessary technical details to start a draft. -You don't have to answer all of these questions, only the ones that make sense to your particular user story. - -=== Feature info -* What is the feature being developed? What does it do? -* How does it work? -* Are there any configuration files/settings/parameters being added or modified? Are any new commands being added or modified? -* What tools or software does the docs team need to test how this feature works? Does the docs team need to update any installed software? -* Are there any existing blogs, Wiki posts, Kbase articles, or Bzs involving this feature? Or any other existing information that may help to understand this feature? - -=== Customer impact -* Who is the intended audience for this feature? If it's for Enterprise, does it apply to developers, admins, or both? -* Why is it important for our users? Why would they want to use this feature? How does it benefit them? -* How will the customer use it? Is there a use case? -* How will the customer interact with this feature? Client tools? Web console? REST API? - -=== Product info -* Is this feature being developed for Online? Enterprise? Dedicated? OKD? All? -* Will this feature be rolled back to previous versions? -* If it's for Online, what type of plan do users need to use this feature? -* Is it user-facing, or more behind-the-scenes admin stuff? -* What tools or software does the docs team need to test how this feature works? - -== How do I write in modules? -The full guidelines for writing modules are in the Customer Content Services (CCS) -link:https://redhat-documentation.github.io/modular-docs/[modularization guide]. - -The main concepts of writing in modules are: - -* Each assembly contains the information required for a user to achieve a single -goal. -* Assemblies contain primarily `include` statements, which are references to -smaller, targeted module files. -* Modules can contain conceptual information, reference information, or steps, -but not a combination of the types. - -For example, a simple assembly might contain the following three modules: - -* A concept module that contains background information about the feature -that the user will configure -* A reference module that contains an annotated sample yaml file that the user -needs to modify -* A procedure module that contains the prerequisites that the user needs to -complete before they start configuring and steps that the user takes to -complete the configuration. - -The `enterprise-4.1` branch contains sample assemblies that explain how to -get started with modular documentation for OpenShift and that serve as -references for including modules in assemblies. The -link:https://raw.githubusercontent.com/openshift/openshift-docs/enterprise-4.1/mod_docs_guide/mod-docs-conventions-ocp.adoc[Modular Docs OpenShift conventions] -assembly contains the -link:https://raw.githubusercontent.com/openshift/openshift-docs/enterprise-4.1/modules/mod-docs-ocp-conventions.adoc[Modular docs OpenShift conventions] -reference module, and the -link:https://github.com/openshift/openshift-docs/blob/enterprise-4.1/mod_docs_guide/getting-started-modular-docs-ocp.adoc[Getting started with modular docs on OpenShift] -assembly contains the -link:https://raw.githubusercontent.com/openshift/openshift-docs/enterprise-4.1/modules/creating-your-first-content.adoc[Creating your first content] -procedure module. diff --git a/contributing_to_docs/create_or_edit_content.adoc b/contributing_to_docs/create_or_edit_content.adoc deleted file mode 100644 index d795473e1b51..000000000000 --- a/contributing_to_docs/create_or_edit_content.adoc +++ /dev/null @@ -1,230 +0,0 @@ -[id="contributing-to-docs-create-or-edit-content"] -= Create content or edit existing content -:icons: -:toc: macro -:toc-title: -:toclevels: 1 -:description: Create working branch to contribute new content or updates - -toc::[] - -== Before you begin -Before you create or edit content: - -* Read and review the link:contributing.adoc[Contribute to OpenShift documentation] -topic to understand some basics -* link:tools_and_setup.adoc[Install and set up the tools and software] -required to contribute -* Read and review the link:doc_guidelines.adoc[Documentation guidelines] topic -to understand the basic guidelines for consistency - -== Ensure your local repository is in sync with the remote -Before you create a local working branch, it is good practice to ensure that -your local source branch is in sync with the remote and that you have all the -latest changes. You must also ensure that your forked repository is also in sync -with the remote repository. - -[NOTE] -==== -Because most changes in this repository must be committed to the `master` -branch (which is the master for the 4.x stream), the following process always -uses `master` as the name of the source -branch. If you must use another branch as the source for your change, make -sure that you consistently use that branch name instead of `master`. - -When adding or updating content for version 3.11, you should create a feature -branch against enterprise-3.11 to submit your changes. -==== - -1. From your local repository, make sure you have the `master` branch checked -out: -+ ----- -$ git checkout master ----- - -2. Fetch the current state of the OpenShift documentation repository: -+ ----- -$ git fetch upstream ----- - -3. Incorporate the commits from the remote repository, in this case -`openshift/openshift-docs`, into your local repository: -+ ----- -$ git rebase upstream/master ----- - -4. Push the latest updates to your forked repository so that it is also in sync -with the remote: -+ ----- -$ git push origin master ----- - -== Add content or update existing content on local branch -With your local and forked repositories in sync with the remote, you can now -create a local working branch where you will make all your updates, or create -any new content. - -*Step 1:* Create local branch - -The following command creates a new local branch from the branch that you are currently on, and checks it out -automatically. Be sure to replace `` with a suitable name. -Also, be sure that the changes made on this branch are closely related. -You must create separate PRs for bugfix changes (for an old or current release) -and enhancement changes (for an upcoming new release). - ----- -$ git checkout -b ----- - -[NOTE] -==== -This command creates a new specified branch and also checks it out, so you will -automatically switch to the new branch. -==== - -*Step 2:* Create content or update existing content as required - -With the local branch created and checked out, you can now edit any content or -start adding new content. - -Ensure that any new file contains the required metadata as described -in the link:doc_guidelines.adoc[documentation guidelines] topic, including -naming and title conventions. - -*Step 3:* Add all of your changes to a pending commit - -When you are finished making all of your changes, used asciibinder to build -the updated or new content, and reviewed the rendered changes, run the following -command to add those changes to a pending commit: - ----- -$ git add . ----- - -*Step 4:* Commit your changes - -After adding your changes to a pending commit, run the following command to -commit those changes locally: - ----- -$ git commit -am "Detailed comments about what changes were made; for example, fixed typo" ----- - -*Step 5:* Rebase updates from `master` into your working branch - -Remember that you must rebase against the branch that you created this working -branch from. In most cases, it will be the master branch for the 4.x stream. - ----- -$ git rebase upstream/master ----- - -[NOTE] -==== -If you find any conflicts you must fix those, and repeat steps 3 and 4. -==== - -*Step 6:* Push all changes to your GitHub account - -After you have rebased, fixed any conflicts, and committed your changes, you can -push them to your GitHub account. This command adds your local working branch to -your GitHub repository: - ----- -$ git push origin ----- - -== Submit PR to merge your work -When you have pushed your changes to your GitHub account, you can submit a PR to -have your work from your GitHub fork to the `master` branch of the OpenShift -documentation repository. The documentation team will review the work, advise of -any further changes that are required, and finally merge your work. - -1. Go to your forked GitHub repository on the GitHub website, and you should see -your local branch that includes all of your work. -2. Click on *Pull Request* to submit the PR against the `master` branch of the -`openshift-docs` repository. -3. If you know which product versions your change applies to, include a comment -that specifies the minimum version that the change applies to. The docs team -maintains these branches for all active and future distros and your PR will be -applied to one or more of these branches. -4. Tag the documentation team with @openshift/team-documentation (if you are a part of the OpenShift organization. If not, tag @vikram-redhat). - -== Confirm your changes have been merged -When your PR has been merged into the `master` branch, you should confirm and -then sync your local and GitHub repositories with the `master` branch. - -1. On your workstation, switch to the `master` branch: -+ ----- -$ git checkout master ----- - -2. Pull the latest changes from `master`: -+ ----- -$ git fetch upstream ----- - -3. Incorporate the commits from the remote repository, in this case -`openshift/openshift-docs`, into your local repository: -+ ----- -$ git rebase upstream/master ----- - -4. After confirming in your rebased local repository that your changes have been -merged, push the latest changes, including your work, to your GitHub account: -+ ----- -$ git push origin master ----- - -== Add changes to an existing PR, if required -In some cases you might have to make changes to a PR that you have already -submitted. The following instructions describe how to make changes to an -existing PR you have already submitted. - -1. Commit whatever updates you have made to the working branch by creating a new -commit: -+ ----- -$ git commit -am "Detailed message as noted earlier" ----- - -2. Rebase your PR and squash multiple commits into one commit. Before you push -your changes in the next step, follow the instructions here to rebase and squash: -https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request - -3. After you have rebased and squashed, push the latest updates to the local -working branch to your GitHub account. -+ ----- -$ git push origin --force ----- - -The `--force` flag ignores whatever is on the remote server and replaces -everything with the local copy. You should now see the new commits in the -existing PR. Sometimes a refresh of your browser may be required. - -== Delete the local working branch -When you have confirmed that all of your changes have been accepted and merged, -and you have pulled the latest changes on `master` and pushed them to your -GitHub account, you can delete the local working branch. Ensure you are in your -local repository before proceeding. - -1. Delete the local working branch from your workstation. -+ ----- -$ git branch -D ----- - -2. Delete the working branch from your GitHub account: -+ ----- -$ git push origin : ----- diff --git a/contributing_to_docs/doc_guidelines.adoc b/contributing_to_docs/doc_guidelines.adoc deleted file mode 100644 index 5de46119d380..000000000000 --- a/contributing_to_docs/doc_guidelines.adoc +++ /dev/null @@ -1,1365 +0,0 @@ -[id="contributing-to-docs-doc-guidelines"] -= Documentation guidelines -include::modules/common-attributes.adoc -:toc: macro - -The documentation guidelines for OpenShift 4 build on top of the -link:https://redhat-documentation.github.io/modular-docs/[Red Hat modular docs reference guide]. - -toc::[] - -== General file guidelines - -* Set your editor to strip trailing whitespace. -* Do *not* hard wrap lines at 80 characters (or at any other length). -+ -It is not necessary to update existing content to unwrap lines, but you can remove existing hard wrapping from any lines that you are currently working in. -+ -[TIP] -==== -In the Atom editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragraph. -==== - -== Assembly file metadata -Every assembly file should contain the following metadata at the top, with no line -spacing in between, except where noted: - ----- -[id=""] <1> -= Assembly title <2> -include::modules/common-attributes.adoc[] <3> -:context: <4> - <5> -toc::[] <6> ----- - -<1> A unique (within OpenShift docs) anchor id for this assembly. Example: cli-developer-commands -<2> Human readable title (notice the '=' top-level header) -<3> Includes attributes common to OpenShift docs. -+ -[NOTE] -==== -The `{product-name}` and `{product-version}` common attributes are not defined in the `modules/common-attributes.adoc` file. Those attributes are pulled by AsciiBinder from the distro mapping definitions in the https://github.com/openshift/openshift-docs/blob/master/_distro_map.yml[_distro_map.yml] file. See xref:product-name-and-version[Product name and version] for more information on this topic. -==== -+ -<4> Context used for identifying headers in modules that is the same as the anchor id. Example: cli-developer-commands. -<5> A blank line. You *must* have a blank line here before the toc. -<6> The table of contents for the current assembly. - -After the heading block and a single whitespace line, you can include any content for this assembly. - -[NOTE] -==== -The assembly title, which is the first line of the document, is the only level 1 ( = ) title. -Section headers within the assembly must be level 2 ( == ) or lower. When you include modules, you must add -leveloffsets in the include statements. You can manually add more level 2 or lower section headers in the assembly. -==== - -== Module file metadata -Every module should be placed in the modules folder and should contain the following metadata at the top: - ----- -// Module included in the following assemblies: -// -// * list of assemblies where this module is included <1> - -[id="_{context}"] <2> -= Module title <3> ----- - -<1> List of assemblies in which this module is included. -<2> A module anchor with {context} that must match the module's file name. -<3> Human readable title. To ensure consistency in the results of the -leveloffset values in include statements, you must use a level one heading -( = ) for the module title. - -Example: - ----- -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/developer-cli-commands.adoc - -[id="cli-basic-commands_{context}"] -= Basic CLI commands ----- - -== Assembly/module file names - -Try to shorten the file name as much as possible _without_ abbreviating important terms that may cause confusion. For example, the `managing-authorization-policies.adoc` file name would be appropriate for an assembly titled "Managing Authorization Policies". - -== Directory names - -If you create a directory with a multiple-word name, separate each word with an underscore, for example `backup_and_restore`. Do not create a top-level directory in the repository without checking with the docs team. In the main OpenShift docs, you can create one level of subdirectories. In the docs for features that are designed to be used with OpenShift, such as Service Mesh and OpenShift virtualization, you can create two levels of subdirectories. - -== Assembly/Module titles and section headings - -Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool. - -Try to be as descriptive as possible with the title or section headings -without making them unnecessarily long. For assemblies and task modules, -use a gerund form in headings, such as: - -* Creating -* Managing -* Using - -Do not use "Overview" as a heading. - -Do not use backticks or other markup in headings. - -=== Discrete headings - -If you have a section heading that you do not want to appear in the TOC (like if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading: - -http://asciidoctor.org/docs/user-manual/#discrete-or-floating-section-titles - -A discrete heading also will not get a section number in the Customer Portal build of the doc. Previously, we would use plain bold mark-up around a heading like this, but discrete headings also allow you to ignore section nesting rules (like jumping from a `==` section level to a `====` level if you wanted for some style reason). - -To use a discrete heading, just add `[discrete]` to the line before your unique ID. For example: - ----- -[discrete] -[id="managing-authorization-policies_{context}"] -== Managing authorization policies ----- - -== Anchoring titles and section headings - -All titles and section headings must have an anchor ID. The anchor ID must be similar to the title or section heading. - -=== Anchoring in assembly files - -The following is an example anchor ID in an assembly file: - ----- -[id="understanding-the-monitoring-stack"] -= Understanding the monitoring stack ----- - -[NOTE] -==== -Do not include line spaces between the anchor ID and the section title. -==== - -=== Anchoring in module files - -You must add the `{context}` variable to the end of anchor IDs in module files. When called, the `{context}` variable is resolved into the value declared in the `:context:` attribute in the corresponding assembly file. This enables cross-referencing to module IDs in context to a specific assembly and is useful when a module is included in multiple assemblies. - -The following is an example of an anchor ID in a module file: - ----- -[id="default-monitoring-components_{context}"] -= Default monitoring components ----- - -[NOTE] -==== -The `{context}` variable must be preceded by an underscore (`_`) when declared in an anchor ID. -==== - -=== Anchoring "Prerequisites", "Additional resources", and "Next steps" titles in assemblies - -Use unique IDs for "Prerequisites", "Additional resources", and "Next steps" titles in assemblies. You can add the prefixes `prerequisites_`, `additional-resources_`, or `next-steps_` to a unique string that describes the assembly topic. The unique string can match the value assigned to the `:context:` attribute in the assembly. - -[NOTE] -==== -The `prerequisites_`, `additional-resources_`, and `next-steps_` prefixes must end with an underscore (`_`) when declared in an anchor ID in an assembly. -==== - -The following examples include IDs that are unique to the "Understanding the monitoring stack" assembly. - -*Example unique ID for a "Prerequisites" title* - ----- -[id="prerequisites_understanding-the-monitoring-stack"] -== Prerequisites ----- - -*Example unique ID for an "Additional resources" title* - ----- -[id="additional-resources_understanding-the-monitoring-stack"] -== Additional resources ----- - -*Example unique ID for a "Next steps" title* - ----- -[id="next-steps_understanding-the-monitoring-stack"] -== Next steps ----- - -== Writing assemblies -An _assembly_ is a collection of modules that describes how to accomplish a user story. - -For more information about forming assemblies, see the -link:https://redhat-documentation.github.io/modular-docs/#forming-assemblies[Red Hat modular docs reference guide] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc[assembly template]. - -[NOTE] -==== -When using "Prerequisites", "Next steps", and "Additional resources" headings in an assembly, use `==` formatting, such as `== Prerequisites` and `== Additional resources`. Use of this heading syntax at the assembly level indicates that the sections relate to the whole assembly. Only use `.` syntax (`.Additional resources`) to follow the module as a trailing include at the assembly level, which indicates that the resources apply specifically to the module. -==== - -== Writing concepts -A _concept_ contains information to support the tasks that users want to do and -must not include task information like commands or numbered steps. In most -cases, create your concepts as individual modules and include them in -appropriate assemblies. - -Avoid using gerunds in concept titles. "About " -is a common concept module title. - -For more information about creating concept modules, see the -link:https://redhat-documentation.github.io/modular-docs/#creating-concept-modules[Red Hat modular docs reference guide] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_CONCEPT_concept-explanation.adoc[concept template]. - -== Writing procedures -A _procedure_ contains the steps that users follow to complete a process or task. Procedures contain ordered steps and explicit commands. In most cases, create your procedures as individual modules and include them in appropriate assemblies. - -Use a gerund in the procedure title, such as "Creating". - -For more information about writing procedures, see the -link:https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules[Red Hat modular docs reference guide] and the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc[procedure template]. - -[NOTE] -==== -When needed, use `.Prerequisites`, `.Next steps`, or `.Additional resources` syntax to suppress TOC formatting within a module. Do not use `==` headings or xrefs in modules. -==== - -[id="product-name-and-version"] -== Product name and version - -When possible, generalize references to the product name and/or version by using -the `{product-title}` and/or `{product-version}` attributes. These attributes -are pulled by AsciiBinder from the distro mapping definitions in the -https://github.com/openshift/openshift-docs/blob/master/_distro_map.yml[_distro_map.yml] -file. - -The `{product-title}` comes from the first `name:` field in a distro mapping, -while the associated `{product-version}` comes from the `name:` fields on any -`branches:` defined. - -How these attributes render is dependent on which distro and branch build you -are viewing. The following table shows the current distros and the -possible values for `{product-title}` and `{product-version}`. - -[options="header"] -|=== -|Distro |`{product-title}` |`{product-version}` - -|`openshift-origin` -|OKD -|1.2, 1.3, 1.4, 1.5, 3.6, 3.7, 3.9, 3.10, 3.11, Latest - -|`openshift-enterprise` -|OpenShift Container Platform -|3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.9, 3.10, 3.11, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7 - -|`openshift-dedicated` -|OpenShift Dedicated -|Latest - -|`openshift-online` -|OpenShift Online -|Latest -|=== - -For example: - ----- -You can deploy applications on {product-title}. ----- - -This is a safe statement that could appear in probably any of the builds, so an -https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/contributing.adoc#conditional-text-between-products[ifdef/endif -statement] is not necessary. For example, if you were viewing a build for the -`openshift-enterprise` distro (for any of the distro-defined branches), this -would render as: - -> You can deploy applications on OpenShift Container Platform. - -And for the `openshift-origin` distro: - -> You can deploy applications on OKD. - -Considering that we use distinct branches to keep content for product versions separated, global use of `{product-version}` across all branches is probably less useful, but it is available if you come across a requirement for it. Just consider how it will render across any branches that the content appears in. - -If it makes more sense in context to refer to the major version of the product instead of a specific minor version (for example, if comparing how something in OpenShift Container Platform 4 differs from OpenShift Container Platform 3), just use the major version number. Do not prepend with a `v`, as in `v3` or `v4`. - -[NOTE] -==== -Other common attribute values are defined in the `modules/common-attributes.adoc` file. Where possible, generalize references to those values by using the common attributes. For example, use `{cloud-redhat-com}` to refer to Red Hat OpenShift Cluster Manager. -==== - -== Node names - -Do not use internal company server names in commands or example output. Provide generic OpenShift Container Platform node name examples that are not provider-specific, unless required. Where possible, use the example.com domain name when providing fully qualified domain names (FQDNs). - -The following table includes example OpenShift Container Platform 4 node names and their corresponding role types: - -[options="header"] -|=== - -|Node name |Role type - -|*node-1.example.com* -.3+.^|You can use this format for nodes that do not need role-specific node names. - -|*node-2.example.com* - -|*node-3.example.com* - -|*control-plane-1.example.com* -.3+.^|You can use this format if you need to describe the control plane role type within a node name. - -|*control-plane-2.example.com* - -|*control-plane-3.example.com* - -|*compute-1.example.com* -.2+.^|You can use this format if you need to describe the compute node role type within a node name. - -|*compute-2.example.com* - -|*bootstrap.example.com* -|You can use this format if you need to describe the bootstrap node role type within a node name. -|=== - -This example lists the status of cluster nodes that use the node name formatting guidelines: - -.... -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -compute-1.example.com Ready worker 33m v1.19.0+9f84db3 -control-plane-1.example.com Ready master 41m v1.19.0+9f84db3 -control-plane-2.example.com Ready master 45m v1.19.0+9f84db3 -compute-2.example.com Ready worker 38m v1.19.0+9f84db3 -compute-3.example.com Ready worker 33m v1.19.0+9f84db3 -control-plane-3.example.com Ready master 41m v1.19.0+9f84db3 ----- -.... - -[NOTE] -==== -Some provider-formatted host names include IPv4 addresses. An OpenShift Container Platform node name typically reflects the host name of a node. If node names in your output need to be provider-specific and require this format, use private IPv4 addresses. For example, you could use `ip-10-0-48-9.example.com` as a node name that includes a private IPv4 address. -==== - -== IP addresses - -You may include IPv4 addresses from test clusters in examples in the documentation, as long as they are private. Private IPv4 addresses fall into one of the following ranges: - -* 10.0.0.0 to 10.255.255.255 (class A address block 10.0.0.0/8) -* 172.16.0.0 to 172.31.255.255 (class B address block 172.16.0.0/12) -* 192.168.0.0 to 192.168.255.255 (class C address block 192.168.0.0/16) - -Replace all public IP addresses with an address from the following blocks. These address blocks are reserved for documentation: - -* 192.0.2.0 to 192.0.2.255 (TEST-NET-1 address block 192.0.2.0/24) -* 198.51.100.0 to 198.51.100.255 (TEST-NET-2 address block 198.51.100.0/24) -* 203.0.113.0 to 203.0.113.255 (TEST-NET-3 address block 203.0.113.0/24) - -[NOTE] -==== -There might be advanced networking examples that require specific IP addresses, or cloud provider-specific examples that require a public IP address. Contact a subject matter expert if you need assistance with replacing IP addresses. -==== - -== Links, hyperlinks, and cross references -Links can be used to cross-reference internal assemblies or send readers to external information resources for further reading. - -In OpenShift docs: - -* All links to internal content is created using `xref` and **must have an anchor ID**. -* Only use `xref` in assemblies, not modules. -* All links to external websites are created using `link`. - -[IMPORTANT] -==== -Do not split link paths across lines when wrapping text. This will cause issues with the doc builds. -==== - -=== Example URLs -To provide an example URL path that you do not want to render as a hyperlink, use this format: - -.... -`\https://www.example.com` -.... - -=== Internal cross-references -Whenever possible the link to another assembly should be part of the actual sentence. -Avoid creating links as a separate sentence that begins with "See [this assembly] for more information on x". - -[NOTE] -==== -Use the relative file path (from the file you are editing, to the file you are linking to), -even if you are linking to the same directory that you are writing in. This makes search and replace -operations to fix broken links much easier. - -For example, if you are writing in *_architecture/core_concepts/deployments.adoc_* and you want to -link to *_architecture/core_concepts/routes.adoc_* then you must include the path back to the first -level of the assembly directory: - ----- -xref:../../architecture/networking/routes.adoc#architecture-core-concepts-routes ----- -==== - -.Markup example of cross-referencing ----- -Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or -the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI]. - -Before you can create a domain, you must first xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[create an application]. ----- - -.Rendered output of cross-referencing -> Rollbacks revert part of an application back to a previous deployment. Rollbacks can be performed using the REST API or the xref:../cli_reference/openshift_cli/get_started_cli.adoc#installing-openshift-cli[OpenShift CLI]. -> -> Before you can create a domain, you must first xref:../dev_guide/application_lifecycle/new_app.adoc#dev-guide-new-app[create an application]. - -=== Links to external websites - -If you want to link to a different website, use: - ----- -link:http://othersite.com/otherpath[friendly reference text] ----- - -IMPORTANT: You must use `link:` before the start of the URL. - -IMPORTANT: You cannot link to a repository that is hosted on www.github.com. - -TIP: If you want to build a link from a URL _without_ changing the text from the actual URL, just print the URL without adding a `[friendly text]` block at the end; it will automatically be rendered as a link. - -=== Links to internal content -There are two scenarios for linking to other assemblies: - -1. Link to another file that exists in the same directory. -2. Link to another file that exists in a separate directory. - -The following examples use the example directory structure shown here: -.... -/ -/foo -/foo/bar.adoc -/baz -/baz/zig.adoc -/baz/zag.adoc -.... - -*Link to assembly in same directory* - ----- -xref:#anchor-id[friendly title] ----- - -You must use the `.adoc` file extension. The document processor will correctly link this to the resulting HTML file. - -For example, using the above syntax, if you are working on `zig.adoc` and want to link to `zag.adoc`, do it this way: - ----- -xref:../zag.adoc#baz-zag[comment] ----- - -where `baz-zag` is the anchor ID at the top of the file `zag.adoc`. - -*Link to assembly in different directory* - ----- -xref:../dir/.adoc#anchor-id[friendly title] ----- - -For example, if you are working on `bar.adoc` and you want to link to `zig.adoc`, do it this way: - ----- -xref:../baz/zig.adoc#baz-zig[see the ZIG manual for more] ----- - -[NOTE] -==== -You must use the .adoc extension in order for the link to work correctly and you must specify an anchor ID. -==== - -== Embedding an external file - -You can embed content hosted outside the link:https://github.com/openshift/openshift-docs[openshift-docs] -GitHub repository by using the `include` directive to target the URI of a raw -file. This is helpful for cases where content frequently changes; you embed the raw -file and the content auto-updates based on the changes made to the content on its -host site. - -[IMPORTANT] -==== -You are restricted to only embed files from GitHub repositories managed by the -`openshift` GitHub user. You must also prefix your external file URI with `https`. -URIs beginning with `http` are forbidden for security reasons and will fail the -documentation build. -==== - -For example, if you want to embed the link:https://github.com/openshift/installer/blob/release-4.7/upi/azure/01_vnet.json[01_vnet.json] template, include the URI of its raw file version like this: - -``` -.`01_vnet.json` ARM template -[source,json] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.7/upi/azure/01_vnet.json[] ----- -``` - -[NOTE] -==== -Embedding external files is restricted for files that change frequently, like templates. You must ensure that embedded files are QE verified before they are updated on their host site. -==== - -[NOTE] -==== -You must get approval from the Engineering, QE, and Docs teams before embedding an external file. -==== - -== Indicating Technology Preview features - -To indicate that a feature is in Technology Preview, include the -`modules/technology-preview.adoc` file in the feature's assembly to keep the -supportability wording consistent across Technology Preview features and provide a value for the :FeatureName: variable before you include this module. - -See -link:https://github.com/openshift/openshift-docs/pull/13878/files#diff-615ba1bf3b09d11a9c2604b775aa32f2[an -example] of how this is applied. - - -== Images - -=== Block images - -To include a block image (an image on its own line): - -1. Put the image file in the symlinked `images` folder. -2. In the `.adoc` content, use this format to link to the image: -+ ----- -image::[] ----- -+ -Note the double `::` instead of a single `:`, as seen in inline image usage. -You only have to specify `` itself and not the full file path; -the build mechanism automatically expands this appropriately. - -=== Inline images (icons) - -Inline images can be used to indicate graphic items in the web console, such as -buttons or menu icons. - -==== Inserting reusable images inline - -To simplify reuse, the following common SVGs (the OpenShift web console uses the -Font Awesome icon set) have already been added to the `images` folder with a -user-defined entity added to the `common-attributes.adoc` module: - -|=== -|Icon |Entity |Alt text |File name - -|Kebab -|`:kebab:` -|Options menu -|`ellipsis-v.svg` - -|=== - -When using inline, include the image after the UI element name. For example: - ----- -Click the *Options* menu {kebab}. ----- - -==== Inserting images inline without reuse - -If you are inserting an image that is not part of the `common-attributes.adoc` -module, then include the image using this formatting: - ----- -image:[title=""] ----- - -Note the single `:` instead of a double `::`, as seen in block image usage. - -For example: - ----- -image:manage-columns.png[title="Manage Columns icon"] ----- - -== Formatting - -For all of the system blocks including table delimiters, use four characters. For example: - -.... -|=== for tables ----- for code blocks -.... - -=== Code blocks, command syntax, and example output - -Code blocks are generally used to show examples of command syntax, example -screen output, and configuration files. - -The main distinction between showing command syntax and a command example is -that a command syntax shows readers how to use the command without real values. -An example command, however, shows the command with actual values with an -example output of that command, where applicable. - -For example: - -.... -In the following example, the `oc get` operation returns a complete list of services that are currently defined: - -[source,terminal] ----- -$ oc get se ----- - -.Example output -[source,terminal] ----- -NAME LABELS SELECTOR IP PORT -kubernetes component=apiserver,provider=kubernetes 172.30.17.96 443 -kubernetes-ro component=apiserver,provider=kubernetes 172.30.17.77 80 -docker-registry name=registrypod 172.30.17.158 5001 ----- -.... - -This renders as: - -> In the following example, the `oc get` operation returns a complete list of services that are currently defined: -> -> ---- -> $ oc get se -> ---- -> -> .Example output -> ---- -> NAME LABELS SELECTOR IP PORT -> kubernetes component=apiserver,provider=kubernetes 172.30.17.96 443 -> kubernetes-ro component=apiserver,provider=kubernetes 172.30.17.77 80 -> docker-registry name=registrypod 172.30.17.158 5001 -> ---- - -The following guidelines go into more detail about specific requirements and -recommendations when using code blocks: - -* Do NOT use any markup in code blocks; code blocks generally do not accept any markup. - -* For all code blocks, you must include an empty line above a code block (unless -that line is introducing block metadata, such as `[source,terminal]` for syntax -highlighting). -+ -Acceptable: -+ -.... -Lorem ipsum - ----- -$ lorem.sh ----- -.... -+ -Not acceptable: -+ -.... -Lorem ipsum ----- -$ lorem.sh ----- -.... -+ -Without the line spaces, the content is likely to be not parsed correctly. - -* Use `[source,terminal]` for `oc` commands or any terminal commands to enable -syntax highlighting. Any `[source]` metadata must go on the line directly before -the code block. For example: -+ -.... -[source,terminal] ----- -$ oc get nodes ----- -.... -+ -If you are also showing a code block for the output of the command, use -`[source,terminal]` for that code block as well. - -* Use source tags for the programming language used in the code block to enable -syntax highlighting. For example: - -** `[source,yaml]` -** `[source,go]` -** `[source,javascript]` - -* Do not use more than one command per code block. For example, the following must -be split up into three separate code blocks: -+ -.... -Run the following commands to create templates you can modify: - -[source,terminal] ----- -$ oc adm create-login-template > login.html ----- - -[source,terminal] ----- -$ oc adm create-provider-selection-template > providers.html ----- - -[source,terminal] ----- -$ oc adm create-error-template > errors.html ----- -.... - -* Separate a command and its related example output into individual code blocks. -This allows the command to be easily copied using the button on -+++docs.openshift.com+++. -+ -In addition, prepend the code block for the output with the title `.Example output` -to make it consistently clear across the docs when this is being represented. A -lead-in sentence explaining the example output is optional. For example: -+ -.... -Use the `oc new-project` command to create a new project: - -[source,terminal] ----- -$ oc new-project my-project ----- - -The output verifies that a new project was created: - -.Example output -[source,terminal] ----- -Now using project "my-project" on server "https://openshift.example.com:6443/". ----- -.... - -* To mark up command syntax, use the code block and wrap any replaceable values in -angle brackets (`<>`) with the required command parameter, using underscores -(`_`) between words as necessary for legibility. For example: -+ -.... -The following command returns a list of objects for the specified object type: - -[source,terminal] ----- -$ oc get ----- -.... -+ -This renders as: -+ --- -> The following command returns a list of objects for the specified object type: -> -> ---- -> $ oc get -> ---- --- -+ -NOTE: Avoid using full command syntax inline with sentences. - -* If you must provide additional information on what a line of a code block -represents, use callouts (`<1>`, `<2>`, etc.) to provide that information. -+ -Use this format when embedding callouts into the code block: -+ -[subs=-callouts] -.... ----- -code example 1 <1> -code example 2 <2> ----- -<1> A note about the first example value. -<2> A note about the second example value. -.... - -* If you must provide additional information on what a line of a code block -represents and the use of callouts is impractical, you can use a description list -to provide information about the variables in the code block. Using callouts -might be impractical if a code block contains too many conditional statements to -easily use numbered callouts or if the same note applies to multiple lines of the codeblock. -+ -.... ----- -code -code ----- -+ -where: - -:: Specifies the explanation of the first variable. -:: Specifies the explanation of the first variable. -.... -+ -Be sure to introduce the description list with "where:" and start each variable -description with "Specifies." - -* For long lines of code that you want to break up among multiple lines, use a -backslash to show the line break. For example: -+ ----- -$ oc get endpoints --all-namespaces --template \ - '{{ range .items }}{{ .metadata.namespace }}:{{ .metadata.name }} \ - {{ range .subsets }}{{ range .addresses }}{{ .ip }} \ - {{ end }}{{ end }}{{ "\n" }}{{ end }}' | awk '/ 172\.30\./ { print $1 }' ----- - -* If the user must run a command as root, use a number sign (`#`) at the start of the command instead of a dollar sign (`$`). For example: -+ ----- -# subscription-manager list ----- - -* For snippets or sections of a larger file, use an ellipsis (`...`) to show that -the file continues before and/or after the quoted block: -+ ----- -apiVersion: v1 -kind: Pod -metadata: - labels: - test: liveness -... ----- -+ -or -+ ----- -... -spec: - containers: - - args: - image: k8s.gcr.io/liveness -... ----- -+ -Do not use `[...]`, ``, or any other variant. - -=== Inline code or commands -Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax. - -Only use case for inline commands would be general commands and operations, without replaceables and command options. In this case an inline command is marked up using the back ticks: - -.... -Use the `GET` operation to do x. -.... - -This renders as: - -> Use the `GET` operation to do x. - -=== System messages - -System messages include error, warning, confirmation, and information messages that are presented to the user in places such as the GUI, CLI, or system logs. - -If a message is short enough to include inline, enclose it in back ticks: - -.... -Previously, image builds and pushes would fail with the `error reading blob from source` error message because the builder logic would compute the contents of new layers twice. -.... - -This renders as: - -> Previously, image builds and pushes would fail with the `error reading blob from source` error message because the builder logic would compute the contents of new layers twice. - -If a message is too long to include inline, put it inside a code block with `[source,text]` metadata: - -.... -Previously, the AWS Terraform provider that the installation program used occasionally caused a race condition with the S3 bucket, and the cluster installation failed with the following error message: -+ -[source,text] ----- -When applying changes to module.bootstrap.aws_s3_bucket.ignition, provider level=error msg="\"aws\" produced an unexpected new value for was present, but now absent. ----- -+ -Now, the installation program uses different AWS Terraform provider code, which now robustly handles S3 eventual consistency, and the installer-provisioned AWS cluster installation does not fail with that error message. -.... - -This renders as: - -> Previously, the AWS Terraform provider that the installation program used occasionally caused a race condition with the S3 bucket, and the cluster installation failed with the following error message: -> -> ---- -> When applying changes to module.bootstrap.aws_s3_bucket.ignition, provider level=error msg="\"aws\" produced an unexpected new value for was present, but now absent. -> ---- -> -> Now, the installation program uses different AWS Terraform provider code, which now robustly handles S3 eventual consistency, and the installer-provisioned AWS cluster installation does not fail with that error message. - -NOTE: Always refer to a message with the type of message it is, followed by the word "message". For example, refer to an error message as an "error message", and not simply as an "error". - -=== Lists -Lists are created as shown in this example: - -.... -. Item 1 (2 spaces between the period and the first character) - -. Item 2 - -. Item 3 -.... - -This renders as: - -> . Item 1 -> . Item 2 -> . Item 3 - -If you must add any text, admonitions, or code blocks you have to add the continuous +, as shown in the example: - -.... -. Item 1 -+ ----- -some code block ----- - -. Item 2 - -. Item 3 -.... - -This renders as: - -> . Item 1 -> + -> ---- -> some code block -> ---- -> . Item 2 -> . Item 3 - -=== Footnotes - -Avoid footnotes when possible. - -If you reference a footnote from only a single location, use the following syntax: - -.Footnote -.... -footnote:[This is the footnote text.] -.... - -If you reference a footnote from multiple locations, set an attribute with the footnote text. As a consequence, this will duplicate the footnote text at bottom of the page. - -.Footnote with text set by an attribute -.... -:note-text: This is a footnote. - -This text has a footnote qualifier attached footnote:[{note-text}]. - -But this other text uses the same qualifier elsewhere footnote:[{note-text}]. -.... - -Avoid using `footnoteref`. - -[IMPORTANT] -==== -The `footnoteref` directive is deprecated in asciidoctor and causes a build warning when `ascii_binder` is run. -==== - -.Footnote with reference -.... -footnoteref:[ref-string, This is the footnote text.] -.... - -==== Alternative footnote styling in tables - -For footnotes in tables, use the following syntax to mimic Asciidoctor's -styling: - -.... -[cols="3",options="header"] -|=== -|Header 1 -|Header 2 -|Header 3 - -|Item A ^[1]^ -|Item B -|Item C ^[2]^ - -|Item D -|Item E ^[3]^ -|Item F ^[3]^ -|=== -[.small] --- -1. A description. -2. Another description. -3. Two items relate to this description. --- -.... - -The notes are kept immediately after the table, instead of moved to the bottom -of the rendered assembly. This manual method also allows you to reuse the same -footnote number for multiple references as needed. - -Note the following: - -* Add a space before the superscripted numbers with square brackets. -* To match the table cell's font size, start the ordered list with a `[.small]` -style and wrap it in a `--` block. - -=== Collapsible content -You can collapse sections of content by using the `collapsible` option, which converts the Asciidoctor markup to HTML `details` and `summary` sections. The `collapsible` option is used at the writer's discretion and is appropriate for considerably long code blocks, lists, or other such content that significantly increases the length of a module or assembly. - -[NOTE] -==== -You must set a title for the `summary` section. If a title is not set, the default title is "Details." -==== - -Collapsible content is formatted as shown: - -.... -.Title of the `summary` dropdown -[%collapsible] -==== -This is content within the `details` section. -==== -.... - -This renders as a dropdown with collapsed content: - -.Title of the `summary` dropdown -[%collapsible] -==== -This is content within the `details` section. -==== - -If your collapsible content includes an admonition such as a note or warning, the admonition must be nested: - -.... -.Collapsible content that includes an admonition -[%collapsible] -==== -This content includes an admonition. - -[source,terminal] ----- -$ oc whoami ----- - -[NOTE] -===== -Nest admonitions when using the `collapsible` option. -===== -==== -.... - -This renders as: - -.Collapsible content that includes an admonition -[%collapsible] -==== -This content includes an admonition. - -[source,terminal] ----- -$ oc whoami ----- - -[NOTE] -===== -Nest admonitions when using the `collapsible` option. -===== -==== - -=== Quick reference - -.User accounts and info -[option="header"] -|=== -|Markup in command syntax |Description |Substitute value in Example block - -|`` -|Name of user account -|user@example.com - -|`` -|User password -|password -|=== - -.Projects and applications -[option="header"] -|=== -|Markup in command syntax |Description |Substitute value in Example block - -|`` -|Name of project -|myproject - -|`` -|Name of an application -|myapp -|=== - -== Admonitions -Admonitions such as notes and warnings are formatted as shown: - -.... -[ADMONITION] -==== -Text for admonition -==== -.... - -[id="api-object-formatting"] -== API object formatting - -For terms that are API objects, the way they are written depends on whether the term is a general reference or an actual reference to the object. - -[id="api-object-general-references"] -=== General references - -A general reference is any time you are speaking conceptually, or generally, about these components in a cluster. - -When referring to API object terms in general usage, use lowercase and separate multi-word API objects. *Default to following this guidance unless you are specifically interacting with/referring to the API object (see xref:api-object-object-references[Object references]).* - -For example: - -* pod -* node -* daemon set -* config map -* deployment -* image stream -* persistent volume claim - -.Examples of general references -.... -Kubernetes runs your workload by placing containers into pods to run on nodes. - -You must have at least one secret, config map, or service account. - -The total number of persistent volume claims in a project. -.... - -Note that if an object uses an acronym or other special capitalization, then its general reference should honor that. For example, general references to `APIService` should be written as "API service", not "api service". Any other exceptions or special guidance are noted in the xref:../contributing_to_docs/term_glossary.adoc[glossary]. - -[id="api-object-object-references"] -=== Object references - -An object reference is when you are referring to the actual instance of an API object, where the object name is important. - -When referring to actual instances of API objects, use link:https://en.wikipedia.org/wiki/Camel_case#Variations_and_synonyms[PascalCase] and mark it up as monospace in backticks (````). - -[NOTE] -==== -Do not use backticks or other markup in headings. -==== - -Be sure to match the proper object type (or `kind` in Kubernetes terms); for example, do not add an "s" to make it plural. *Only follow this guidance if you are explicitly referring to the API object (for example, when editing an object in the CLI or viewing an object in the web console).* - -For example: - -* `Pod` -* `Node` -* `DaemonSet` -* `ConfigMap` -* `Deployment` -* `ImageStream` -* `PersistentVolumeClaim` - -.Examples of API object references -.... -After you create a `Node` object, or the kubelet on a node self-registers, the control plane checks whether the new `Node` object is valid. - -The default amount of CPU that a container can use if not specified in the `Pod` spec. - -Create a file, `pvc.yaml`, with the `PersistentVolumeClaim` object definition. -.... - -[NOTE] -==== -Use "object", "resource", "custom resource", "spec", etc. as appropriate after the object reference. This helps with clarity and readability. - -Another situation where this is necessary is when referring to the plural version of objects. Do not add an "s" to the end of an object name reference to make it plural. Use only the official `kind` of object (for example, seen when you run `oc api-resources`). - -For example, the object `kind` for a node is `Node`, not `Nodes`. So do not write "You can create `Nodes` using `kubectl`." Instead, rewrite to something like "You can create `Node` objects using `kubectl`." -==== - -[id="operator-name-capitalization"] -=== Operator capitalization - -The term "Operator" is always capitalized. For example: - ----- -= Support policy for unmanaged Operators - -Individual Operators have a `managementState` parameter in their configuration. ----- - -An Operator's full name must be a proper noun, with each word initially -capitalized. If it includes a product name, defer the product's capitalization -style guidelines. For example: - -- Cluster Logging Operator -- Prometheus Operator -- etcd Operator -- Node Tuning Operator -- Cluster Version Operator - -== Quick markup reference - -|=== -|Convention |Markup |Example rendered output - -|Code blocks - -a| -.... -Use the following syntax for the `oc` command: - ----- -$ oc ----- -.... - -a| -> Use the following syntax for the `oc` command: -> -> ---- -> $ oc -> ---- - -a|Use backticks for all non-GUI "system items", including: - -* Inline commands, operations, literal values, variables, parameters, settings, -flags, environment variables, user input -* System term/item, user names, unique or example names for individual API -objects/resources (e.g., a pod named `mypod`), daemon, service, or software -package -* RPM packages -* File names or directory paths - -a| -.... -`oc get` - -Set the `upgrade` variable to `true`. - -Use the `--amend` flag. - -Answer by typing `Yes` or `No` when prompted. - -`user_name` - -`service_name` - -`package_name` - -`filename` -.... - -a| -> Use the `oc get services` command to get a list of services that are currently defined. -> ->   -> -> Use the `--amend` flag. -> ->   -> -> Set the `upgrade` variable to `true`. -> ->   -> -> Answer by typing `Yes` or `No` when prompted. -> ->   -> -> `cluster-admin` user -> ->   -> -> `firewalld` service -> ->   -> -> `rubygems` RPM package -> ->   -> -> The `express.conf` configuration file is located in the `/usr/share` directory. - -|System or software variable to be replaced by the user -a| -.... -`` - -`` -.... - -a| -> Use the following command to roll back a Deployment, specifying the Deployment name: -> -> `oc rollback ` - -|Use single asterisks for web console / GUI items (menus, buttons, page titles, etc.). -Use two characters to form the arrow in a series of menu items (`$$->$$`). - -a| -.... -Choose *Cluster Console* from the list. - -Navigate to the *Operators* -> *Catalog Sources* page. - -Click *Create Subscription*. -.... - -a| -> Choose *Cluster Console* from the list. -> ->   -> -> Navigate to the *Operators* -> *Catalog Sources* page. -> ->   -> -> Click *Create Subscription*. - -|Use underscores to emphasize the first appearance of a new term. - -a| -.... -An _Operator_ is a method of packaging, deploying, -and managing a Kubernetes application. -.... - -a| -> An _Operator_ is a method of packaging, deploying, and managing a Kubernetes application. - -|Use of underscores for general emphasis is allowed but should only be used -very sparingly. Let the writing, instead of font usage, create the emphasis -wherever possible. - -a| -.... -Do _not_ delete the file. -.... - -a| -> Do _not_ delete the file. - -|Footnotes - -|A footnote is created with the footnote macro. If you plan to reference a footnote more than once, use the ID footnoteref macro. The Customer Portal does not support spaces in the footnoteref. For example, "dynamic PV" should be "dynamicPV". - -|See link:http://asciidoctor.org/docs/user-manual/#user-footnotes[Footnotes] for the footnote and footnoteref syntax. - -|=== diff --git a/contributing_to_docs/images b/contributing_to_docs/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/contributing_to_docs/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/contributing_to_docs/modules b/contributing_to_docs/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/contributing_to_docs/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/contributing_to_docs/term_glossary.adoc b/contributing_to_docs/term_glossary.adoc deleted file mode 100644 index 50075f26b266..000000000000 --- a/contributing_to_docs/term_glossary.adoc +++ /dev/null @@ -1,675 +0,0 @@ -[id="contributing-to-docs-term-glossary"] -= OpenShift glossary of terms -{product-author} -{product-version} -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title: - -toc::[] - -== Usage of OpenShift terms - -This topic provides guidelines for referring to the various components of -OpenShift 4 and objects of a running OpenShift system in our documentation. The -goal is to standardize terminology across OpenShift content and be consistent in -the usage of our terminology when referring to OpenShift components or -architecture. - -For terms that are also API objects, there is different guidance for general usage of the term versus referencing the actual API object. This glossary mainly defines the general usage guideline (lowercase, separating words), but be sure to use the object formatting (PascalCase, in monospace) when referring to the actual object. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more information. - -[NOTE] -==== -If you want to add terms or other content to this document, or if anything must -be fixed, send an email to openshift-docs@redhat.com or submit a PR -on GitHub. -==== - -== A - -'''' -=== action - -Usage: action - -An action consists of _project_, _verb_, and _resource_: - -* *Project* is the project containing the resource that is to be acted upon. -* *Verb* is a get, list, create, or update operation. -* *Resource* is the API endpoint being accessed. This is distinct from the -referenced resource itself, which can be a pod, deployment, build, etc. - -'''' -=== API server - -Usage: API server(s) - -A REST API endpoint for interacting with the system. New deployments and -configurations can be created with this endpoint, and the state of the system -can be interrogated through this endpoint as well. - -'''' -=== API service - -Usage: API service(s) - -When referencing the actual object, write as `APIService`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -'''' -=== app - -Usage: app(s) - -Acceptable when referring to a mobile or web xref:application[application]. - -'''' -[id="application"] -=== application - -Usage: application(s) - -Although the term application is no longer an official noun in OpenShift, -customers still create and host applications on OpenShift, and using the term -within certain contexts is acceptable. For example, the term application might -refer to some combination of an image, a Git repository, or a replication -controller, and this application might be running PHP, MySQL, Ruby, JBoss, or -something else. - -.Examples of correct usage -==== -OpenShift runs your applications. - -The `new-app` command creates a new application from the components you specify. - -My application has two Ruby web services connected to a database back end and a RabbitMQ message queue, as well as a python worker framework. - -You can check the health of your application by adding probes to the various parts. - -You can host a WordPress application on OpenShift. -==== - -'''' -=== authorization - -Usage: authorization - -An authorization determines whether an _identity_ is allowed to perform any -action. It consists of _identity_ and _action_. - -== B - -'''' -=== build - -Usage: build(s), or when speaking generally about `Build` objects. - -* A build is the process of transforming input parameters into a resulting object. -* A `Build` object encapsulates the inputs needed to produce a new deployable image, as well as the status of the execution and a reference to the pod that executed the build. - -When referencing the actual object, write as "``Build`` object" as appropriate. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -'''' -=== build configuration - -Usage: build configuration(s) when speaking generally about `BuildConfig` objects. - -A `BuildConfig` object is the definition of the entire build process. A build configuration describes a single build definition and a set of triggers for when a new build is created. - -When referencing the actual object, write as "``BuildConfig`` object" as appropriate. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -== C - -'''' -=== cluster - -Usage: cluster - -The collection of controllers, pods, and services and related DNS and networking -routing configuration that are defined on the system. - -'''' -=== cluster service version - -Usage: cluster service version - -Operator Lifecycle Manager (OLM), part of the Operator Framework, uses a cluster service version (CSV) to define the metadata that accompanies an Operator container image and assist in running the Operator in a cluster. This metadata is defined in a `ClusterServiceVersion` API object used to populate user interfaces with information such as its logo, description, and version. It is also a source of technical information that is required to run the Operator, like the RBAC rules it requires and which custom resources (CRs) it manages or depends on. - -This is commonly abbreviated as a CSV. - -'''' -=== config map - -Usage: config map(s) - -Config maps hold configuration data for pods to consume. - -When referencing the actual object, write as `ConfigMap`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -Do not use: configuration map(s) - -'''' -=== container - -Usage: container(s) - -'''' -=== containerize - -Usage: containerize(d) - -Use "containerized" as an adjective when referring to applications made up of -multiple services that are distributed in containers. "Containerized" can be -used interchangeably with "container-based." - -'''' -=== container group - -Usage: container group - -'''' -=== custom resource - -Usage: custom resource (CR) - -A resource implemented through the Kubernetes `CustomResourceDefinition` API. A custom resource is distinct from the built-in Kubernetes resources, such as the pod and service resources. Every CR is part of an API group. - -Do not capitalize. - -'''' -=== custom resource definition (CRD) - -Usage: custom resource definition (CRD) for the first time reference; CRD thereafter. - -Create a custom resource definition to define a new custom resource. - -This is commonly abbreviated as a CRD. - -== D - -'''' -=== deployment - -Usage: deployment(s) when speaking generally about `Deployment` or `DeploymentConfig` objects - -* A `Deployment` is a Kubernetes-native object that provides declarative updates for pods and -replica sets. -* A `DeploymentConfig` is an OpenShift-specific object that defines the template for a pod and manages -deploying new images or configuration changes. Uses replication controllers. Predates Kubernetes `Deployment` objects. - -When referencing the actual object, write as `Deployment` or `DeploymentConfig` as appropriate. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -To avoid further confusion, do not refer to an overall OpenShift installation / -instance / cluster as an "OpenShift deployment". - -Do not use: deployment configuration(s), deployment config(s) - -'''' -=== Dockerfile - -Usage: Dockerfile; wrapped with [filename] markup. See -link:doc_guidelines.adoc[Documentation Guidelines] for markup information. - -Docker can build images automatically by reading the instructions from a -Dockerfile. A Dockerfile is a text document that contains all the commands you -would normally execute manually to build a docker image. - -Source: https://docs.docker.com/reference/builder/ - -.Examples of correct usage -==== -Open the [filename]#Dockerfile# and make the following changes. - -Create a [filename]#Dockerfile# at the root of your repository. -==== - -== E - -'''' -=== event - -Usage: event(s) - -An event is a data record expressing an occurrence and its context, based on the CNCF CloudEvents specification. -Events contain two types of information: the event data representing the occurrence, and the context metadata providing contextual information about the occurrence. -Events are routed from an event producer, or source, to connected event consumers. - -Routing can be performed based on information contained in the event, but an event will not identify a specific routing destination. -Events can be delivered through various industry standard protocols such as HTTP, AMQP, MQTT, or SMTP, or through messaging and broker systems, such as Kafka, NATS, AWS Kinesis, or Azure Event Grid. - -When referencing the actual object, write as `Event`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -// NOTE: This is inconsistently used, e.g. https://docs.openshift.com/container-platform/4.5/rest_api/metadata_apis/event-core-v1.html -See: link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#event-v1-core[Event v1 core API], link:https://github.com/cloudevents/spec/blob/master/primer.md#cloudevents-concepts[CloudEvents concepts], and link:https://github.com/cloudevents/spec/blob/master/spec.md#event[CloudEvents specification]. - -== F - -== G - -'''' -=== group/version/kind (GVK) - -Usage: group/version/kind (GVK) for the first time reference; GVK thereafter. - -A unique identifier for a Kubernetes API, specifying its _group_ (a collection of related APIs), _version_ (defines the release and level of stability), and _kind_ (an individual API type or name). - -While "GroupVersionKind" does appear in the API guide, typically there should not be a reason to mark up in reference to a specific object. Favor simply "GVK", or "GVKs" for pluralization, after the first time reference as much as possible. Avoid pluralizing the long form (e.g., group/version/kinds or groups/versions/kinds). - -== H - -== I - -'''' -=== identity - -Usage: identity or identities - -Both the user name and list of groups the user belongs to. - -'''' -=== image - -Usage: image(s) - -'''' -=== image stream - -Usage: image stream(s) - -Image streams provide a means of creating and updating container images in an ongoing way. - -'''' -=== Ignition config - -Usage: Ignition config file or Ignition config files - -The file that Ignition uses to configure Red Hat Enterprise Linux CoreOS (RHCOS) during -operating system initialization. The installation program generates different -Ignition config files to initialize bootstrap, master, and worker nodes. - -'''' - -=== Ingress - -Usage: Ingress - -API object that allows developers to expose services through an HTTP(S) aware -load balancing and proxy layer via a public DNS entry. The Ingress resource may -further specify TLS options and a certificate, or specify a public CNAME that -the OpenShift Ingress Controller should also accept for HTTP and HTTPS traffic. -An administrator typically configures their Ingress Controller to be visible -outside the cluster firewall, and may also add additional security, caching, or -traffic controls on the service content. - -'''' - -=== Ingress Controller - -Usage: Ingress Controller(s) - -A resource that forwards traffic to endpoints of services. The Ingress Controller -replaces router from {product-title} 3 and earlier. - -'''' -=== installer-provisioned infrastructure - -Usage: installer-provisioned infrastructure - -If the installation program deploys and configures the infrastructure that the -cluster runs on, it is an installer-provisioned infrastructure installation. - -Do not use: IPI - -== J - -== K - -'''' -=== kubelet - -Usage: kubelet(s) - -The agent that controls a Kubernetes node. Each node runs a kubelet, which -handles starting and stopping containers on a node, based on the desired state -defined by the master. - -'''' -=== Kubernetes master - -Usage: Kubernetes master(s) - -The Kubernetes-native equivalent to the link:#project[OpenShift master]. -An OpenShift system runs OpenShift masters, not Kubernetes masters, and -an OpenShift master provides a superset of the functionality of a Kubernetes -master, so it is generally preferred to use the term OpenShift master. - -'''' -=== Kubernetes API server - -Usage: Kubernetes API server - -== L - -== M - -'''' -=== minion - -Usage: Deprecated. Use link:#node[node] instead. - -== N - -'''' -=== node - -Usage: node(s) - -A -http://docs.openshift.org/latest/architecture/infrastructure_components/kubernetes_infrastructure.html#node[node] -provides the runtime environments for containers. - -'''' -=== namespace - -Usage: namespace - -Typically synonymous with link:#project[project] in OpenShift parlance, which is -preferred. - -== O - -'''' -=== OpenShift - -Usage: OpenShift Container Platform, OpenShift Online, OpenShift Dedicated, -OpenShift Container Engine - -The OpenShift product name should be paired with its product distribution / -variant name whenever possible. Previously, the upstream distribution was called -OpenShift Origin, however it is now called OKD; use of the OpenShift Origin name -is deprecated. - -Avoid using the name "OpenShift" on its own when referring to something that -applies to all distributions, as OKD does not have OpenShift in its name. -However, the following components currently use "OpenShift" in the name and are -allowed for use across all distribution documentation: - -- OpenShift Pipeline -- OpenShift SDN -- OpenShift Ansible Broker (deprecated in 4.2 / removed in 4.4) - -'''' -=== OpenShift API server - -Usage: OpenShift API server - -'''' -=== OpenShift CLI - -Usage: OpenShift CLI (`oc`) - -The `oc` tool is the command-line interface of OpenShift 3 and 4. - -When referencing as a prerequisite for a procedure module, use the following -construction: Install the OpenShift CLI (`oc`). - -'''' -=== OpenShift master - -Usage: OpenShift master(s) - -Provides a REST endpoint for interacting with the system and manages the state -of the system, ensuring that all containers expected to be running are actually -running and that other requests such as builds and deployments are serviced. -New deployments and configurations are created with the REST API, and the state -of the system can be interrogated through this endpoint as well. An OpenShift -master comprises the API server, scheduler, and SkyDNS. - -'''' -=== Operator - -Usage: Operator(s) - -An Operator is a method of packaging, deploying and managing a Kubernetes -application. A Kubernetes application is an application that is both deployed on -a Kubernetes cluster (including OpenShift clusters) and managed using the -Kubernetes APIs and `kubectl` or `oc` tooling. - -The term "Operator" is always captalized. - -While "containerized" is allowed, do not use "Operatorize" to refer to building an -Operator that packages an application. - -.Examples of correct usage -==== -Install the etcd Operator. - -Build an Operator using the Operator SDK. -==== - -See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for -more on Operator naming. - -'''' -=== OperatorHub - -Usage: OperatorHub - -'''' -=== Options menu - -Usage: Options menu; use sparingly; not to be confused with Actions menu, which -signifies a specific menu seen in the web console. - -This describes a menu type commonly called a "kebab", "hamburger", or "overflow" -menu that does not have hover text or a given name or label in the web console. - -'''' - -== P - -'''' -=== persistent volume (PV) - -Usage: persistent volume - -Developers can use a persistent volume claim (PVC) to request a persistent volume (PV) resource without having specific knowledge of the underlying storage infrastructure. - -'''' -=== persistent volume claim (PVC) - -Usage: persistent volume claim - -Developers can use a persistent volume claim (PVC) to request a persistent volume (PV) resource without having specific knowledge of the underlying storage infrastructure. - -'''' -=== pod - -Usage: pod(s) - -Kubernetes object that groups related Docker containers that have to share -network, file system, or memory together for placement on a node. Multiple -instances of a pod can run to provide scaling and redundancy. - -When referencing the actual object, write as `Pod`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -'''' -=== project - -Usage: project(s) - -A project allows a community of users to organize and manage their content in -isolation from other communities. It is an extension of the `Namespace` object -from Kubernetes. - -When referencing the actual object, write as `Project`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -== Q - -== R - -'''' -=== replica set - -Usage: replica set(s) - -Similar to a replication controller, a replica set is a native Kubernetes API -object that ensures a specified number of pod replicas are running at any given -time. Used by `Deployment` objects. - -When referencing the actual object, write as `ReplicaSet`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -See link:https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/[ReplicaSet - Kubernetes]. - -'''' -=== replication controller - -Usage: replication controller(s) - -Kubernetes object that ensures N (as specified by the user) instances of a given -pod are running at all times. Used by deployment configs. - -'''' -=== route - -Usage: route(s) - -OpenShift-specific API object that allows developers to expose services through -an HTTP(S) aware load balancing and proxy layer via a public DNS entry. The -route may further specify TLS options and a certificate, or specify a public -CNAME that the OpenShift Ingress Controller should also accept for HTTP and -HTTPS traffic. An administrator typically configures their Ingress Controller to -be visible outside the cluster firewall, and may also add additional security, -caching, or traffic controls on the service content. - -== S - -'''' -=== scheduler - -Usage: scheduler(s) - -Component of the Kubernetes master or OpenShift master that manages the state of -the system, places pods on nodes, and ensures that all containers that are -expected to be running are actually running. - -'''' -=== secret - -Usage: secret(s) - -Kubernetes API object that holds secret data of a certain type. - -See link:https://kubernetes.io/docs/concepts/configuration/secret/[Secrets - Kubernetes]. - -'''' -=== security context constraints (SCC) - -Usage: security context constraints - -Security context constraints govern the ability to make requests that affect the security context that will be applied to a container. - -When referencing the actual object, write as `SecurityContextConstraints`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -This is commonly abbreviated as SCC. - -'''' -=== service - -Usage: service(s) - -Kubernetes native API object that serves as an internal load balancer. It -identifies a set of replicated pods to proxy the connections it -receives to them. Backing pods can be added to or removed from a service -arbitrarily while the service remains consistently available, enabling anything -that depends on the service to refer to it at a consistent address. - -A service is a named abstraction of software service (for example, `mysql`) -consisting of local port (for example `3306`) that the proxy listens on, and the -selector that determines which pods will answer requests sent through the proxy. - -Do not confuse with link:https://www.openservicebrokerapi.org/[Open Service Broker API related objects]. -See -link:https://docs.openshift.com/container-platform/3.11/architecture/service_catalog/index.html#service-catalog-concepts-terminology[Service Catalog Concepts and Terminology]. - -'''' -=== service account - -Usage: service account(s) - -A service account binds together: - -* a name, understood by users, and perhaps by peripheral systems, for an identity -* a principal that can be authenticated and authorized -* a set of secrets - -'''' -=== SkyDNS - -Usage: SkyDNS - -Component of the Kubernetes master or OpenShift master that provides -cluster-wide DNS resolution of internal host names for services and pods. - -'''' -=== Source-to-Image (S2I) - -Usage: Source-to-Image for the first time reference; S2I thereafter. - -Deprecated abbreviation (do not use): STI - -'''' -=== spec - -Usage: spec(s) - -In addition to "spec file" being allowed related to RPM spec files, general -usage of "spec" is allowed when describing Kubernetes or OpenShift object specs -/ manifests / definitions. - -.Examples of correct usage -==== -Update the `Pod` spec to reflect the changes. -==== - -'''' -=== storage class - -Usage: storage class(es) - -Kubernetes API object that describes the parameters for a class of storage for -which persistent volumes can be dynamically provisioned. storage classes are -non-namespaced; the name of the storage class according to etcd is in -`ObjectMeta.Name`. - -When referencing the actual object, write as `StorageClass`. See link:doc_guidelines.adoc#api-object-formatting[API object formatting] for more details. - -See link:https://kubernetes.io/docs/concepts/storage/storage-classes/[Storage Classes - Kubernetes]. - -== T - -== U - -'''' -=== user-provisioned infrastructure - -Usage: user-provisioned infrastructure - -If the user must deploy and configure separate virtual or physical hosts as part of -the cluster deployment process, it is a user-provisioned infrastructure -installation. - -Do not use: UPI - -'''' - -== V - -== W - -== X - -== Y - -== Z diff --git a/contributing_to_docs/tools_and_setup.adoc b/contributing_to_docs/tools_and_setup.adoc deleted file mode 100644 index 47441b313ba1..000000000000 --- a/contributing_to_docs/tools_and_setup.adoc +++ /dev/null @@ -1,188 +0,0 @@ -[id="contributing-to-docs-tools-and-setup"] -= Install and set up the tools and software -:icons: -:toc: macro -:toc-title: -:toclevels: 1 -:linkattrs: -:description: How to set up and install the tools to contribute - -toc::[] - -== Create a GitHub account -Before you can contribute to OpenShift documentation, you must -https://www.github.com/join[sign up for a GitHub account]. - -== Set up authentication -When you have your account set up, follow the instructions to -https://help.github.com/articles/generating-ssh-keys/[generate and set up SSH -keys on GitHub] for proper authentication between your workstation and GitHub. - -Confirm authentication is working correctly with the following command: - ----- -$ ssh -T git@github.com ----- - -== Fork and clone the OpenShift documentation repository -You must fork and set up the OpenShift documentation repository on your -workstation so that you can create PRs and contribute. These steps must only -be performed during initial setup. - -. Fork the https://github.com/openshift/openshift-docs repository into your -GitHub account from the GitHub UI. You can do this by clicking on *Fork* in the -upper right-hand corner. - -. In the terminal on your workstation, change into the directory where you want -to clone the forked repository. - -. Clone the forked repository onto your workstation with the following -command, replacing __ with your actual GitHub username. -+ ----- -$ git clone git@github.com:/openshift-docs.git ----- - -. Change into the directory for the local repository you just cloned. -+ ----- -$ cd openshift-docs ----- - -. Add an upstream pointer back to the OpenShift's remote repository, in this -case _openshift-docs_. -+ ----- -$ git remote add upstream git@github.com:openshift/openshift-docs.git ----- - -This ensures that you are tracking the remote repository to keep your local -repository in sync with it. - -== Install AsciiBinder and dependencies -When you have the documentation repository cloned and set up, you are ready to -install the software and tools you will use to create the content. All OpenShift -documentation is created in AsciiDoc, and is processed with https://github.com/redhataccess/ascii_binder[AsciiBinder], -which is an http://asciidoctor.org/[AsciiDoctor]-based docs management system. - - -=== What you require -The following are minimum requirements: - -* A bash shell environment (Linux and OS X include a bash shell environment out -of the box, but if you are on Windows you can use http://cygwin.com/[Cygwin]) -* https://www.ruby-lang.org/en/[Ruby] -* http://www.git-scm.com/[Git] -* A web browser (Firefox, Chrome, or Safari) -* An editor that can strip trailing whitespace, such as -link:https://atom.io/[Atom]. - -=== Install the required software dependencies on a Linux system -The following instructions describe how to install all the required tools to do -live content editing on a Fedora Linux system. - -1. Install the _RubyGems_ package with `yum install rubygems` - -[NOTE] -==== -On certain systems, `yum` installs an older version of RubyGems that can cause issues. As an alternative, you can install RubyGems by using RVM. The following example is referenced from the link:https://rvm.io/rvm/install[RVM site]: - -[source,terminal] ----- -$ curl -sSL https://get.rvm.io | bash -s stable --ruby ----- -==== - -2. Install _Ruby_ development packages with `yum install ruby-devel` -3. Install _gcc_ with `yum install gcc-c++` -4. Install _redhat-rpm-config_ with `yum install redhat-rpm-config` -5. Install _make_ with `yum install make` -6. Install _asciidoctor-diagram_ with `gem install asciidoctor-diagram` -7. Install the _ascii_binder_ gem with `gem install ascii_binder` - -NOTE: If you already have AsciiBinder installed, you might be due for an update. -These directions assume that you are using AsciiBinder 0.2.0 or newer. To check -and update if necessary, simply run `gem update ascii_binder`. Note that you might require root permissions. - -=== Building the collection -With the initial setup complete, you are ready to build the collection. - -1. From the `openshift-docs` directory, run an initial build: -+ ----- -$ cd openshift-docs -$ asciibinder build ----- -2. Open the generated HTML file in your web browser. This will be located in the -`openshift-docs/_preview//` directory, with the same path and -filename as the original `.adoc` file you edited, only it will be with the -`.html` extension. - -== Clean up -The `.gitignore` file is set up to prevent anything under the `_preview` and -`_package` directories from being committed. However, you can reset the -environment manually by running: - ----- -$ asciibinder clean ----- - -== Next steps -With the repository and tools set up on your workstation, you can now either -edit existing content or create assemblies and modules. - -* link:doc_guidelines.adoc[Review the documentation guidelines] to understand -some basic guidelines to keep things consistent across our content. -* link:create_or_edit_content.adoc[Create a local working branch] on your -workstation to edit existing content or create content. - -=== How to deploy to your own OpenShift cluster for testing -You can deploy to your own OpenShift cluster for development. This process will use your github repo to launch the website, -and therefore your github repo must have all of the upstream branches. `master` is used for site changes, -so assuming all your work is in `master`, you can remove all remote branches and then push the upstream branches. - - -Removing remote branches and updating with upstream branches (this assumes remote repos called `origin` and `upstream`) -[WARNING] -==== -This is a destructive process, make sure that this is purely a development repo, as all local and remote branches will be deleted -by performing the below commands. -==== ----- -$ git fetch --all -$ for branch in $(git branch -r | grep -v "master" | grep "^ origin"); do git push origin --delete $(echo $branch | cut -d '/' -f 2); done -$ git branch -D $(git branch | grep -v 'master' | xargs) -$ for branch in $(git branch -r | grep -v "master" | grep "^ upstream"); do git branch --track $(echo $branch | cut -d '/' -f 2) $(echo $branch | tr -d '[:space:]'); done -$ for branch in $(git branch | grep -v "master"); do git push origin $(echo $branch | tr -d '[:space:]'); done ----- - -Deploying the docs site to an OpenShift cluster ----- -$ oc process -f asciibinder-template.yml -p NAME=community-docs \ - -p SOURCE_REPOSITORY_URL=$(git remote get-url origin) \ - -p SOURCE_REPOSITORY_REF=$(git rev-parse --abbrev-ref HEAD) \ - -p DOC_TYPE=community \ - | oc create -f - -$ oc process -f asciibinder-template.yml -p NAME=commercial-docs \ - -p SOURCE_REPOSITORY_URL=$(git remote get-url origin) \ - -p SOURCE_REPOSITORY_REF=$(git rev-parse --abbrev-ref HEAD) \ - -p DOC_TYPE=commercial \ - | oc create -f - ----- - -[NOTE] -==== -If the build fails with "Fetch source failed" status, you can -delete all the created objects and re-run above with an HTTP uri -as the `SOURCE_REPOSITORY_URL`, or you can -link:https://docs.okd.io/latest/dev_guide/builds/build_inputs.html#source-secrets-combinations[create a source secret] -and add it to the stg1 build, `oc set build-secret --source bc/stg1-docs `. -==== - - -You can delete all created objects by running - ----- -$ oc delete all -l app=community-docs -$ oc delete all -l app=commercial-docs ----- diff --git a/files/ca-setup.sh b/files/ca-setup.sh new file mode 100644 index 000000000000..c70e2f8b5651 --- /dev/null +++ b/files/ca-setup.sh @@ -0,0 +1,104 @@ +#!/usr/bin/env bash + +# Use this script to set up additional trusted certificate authorities (CAs) +# for StackRox Central and StackRox Scanner. +# For details, see https://help.stackrox.com/docs/configure-stackrox/add-trusted-ca/ +# or search the documentation in the StackRox portal. + +KUBE_COMMAND=${KUBE_COMMAND:-oc} + +update=0 + +function create_or_replace() { + cmd=create + (( ! update )) || cmd=replace + ${KUBE_COMMAND} create "$@" --dry-run -o yaml | ${KUBE_COMMAND} "$cmd" -f - +} + +function label() { + extra_args=() + (( ! update )) || extra_args+=(--overwrite) + ${KUBE_COMMAND} label "${extra_args[@]}" "$@" +} + +function usage { + echo "usage:" + echo " $(basename "$0") [-u] -f file" + echo " $(basename "$0") [-u] -d dir" + echo + echo "The argument may be:" + echo " - a single file" + echo " - a directory (all files ending in .crt and .pem will be added)" + echo "Each file must contain exactly one PEM-encoded certificate." + echo + echo "If the -u (update) argument is passed, the existing additional CAs will be" + echo "replaced." + exit 1 +} + +function create_ns { + ${KUBE_COMMAND} get ns "stackrox" > /dev/null 2>&1 || ${KUBE_COMMAND} create ns "stackrox" +} + +function create_file { + local file="$1" + create_or_replace secret -n "stackrox" generic "additional-ca" --from-file="ca.crt=$file" + label -n "stackrox" "secret/additional-ca" app.kubernetes.io/name=stackrox +} + +function create_directory { + local dir="$1" + echo "The following certificates will be used as additional CAs:" + from_file_args=() + for f in $dir/*.crt $dir/*.pem; do + if [ -f "$f" ] ; then + from_file_args+=("--from-file=$(basename "$f")=$f") + echo " - $f" + fi + done + if [ "${#from_file_args[@]}" -eq 0 ]; then + echo "Error: No filenames ending in \".crt\" or \".pem\" in $dir. Please add some." + exit 2 + fi + create_or_replace secret -n "stackrox" generic "additional-ca" "${from_file_args[@]}" + label -n "stackrox" "secret/additional-ca" app.kubernetes.io/name=stackrox +} + +[[ "$#" -ge 2 ]] || usage + +file_name= +dir_name= + +while [[ "$#" -gt 0 ]]; do + arg="$1" + shift + + case "$arg" in + -f) + [[ -z "$file_name" ]] || usage + file_name="$1" + shift + ;; + -d) + [[ -z "$dir_name" ]] || usage + dir_name="$1" + shift + ;; + -u) + (( ! update )) || usage + update=1 + ;; + *) + usage + esac +done + +create_ns + +if [[ -n "$file_name" && -z "$dir_name" ]]; then + create_file "$file_name" +elif [[ -n "$dir_name" && -z "$file_name" ]]; then + create_directory "$dir_name" +else + usage +fi diff --git a/files/create_certificate_values_file.sh b/files/create_certificate_values_file.sh new file mode 100755 index 000000000000..0cf4c08c4f92 --- /dev/null +++ b/files/create_certificate_values_file.sh @@ -0,0 +1,22 @@ +#!/bin/bash + +# Red Hat Advanced Cluster Security for Kubernetes +# Retrieve root certificates and create a private value yaml file. + +create_certificate_values_file() { + if [[ "$#" -ne 1 ]]; then + echo "wrong args. usage: create_certificate_values_file " + exit 1 + fi + + local cert_path="$1" + echo "Create root certificates values file" + # get root ca + caKey=$(kubectl -n stackrox get secret central-tls -o go-template='{{ index .data "ca-key.pem" }}' | base64 --decode) + caPem=$(kubectl -n stackrox get secret central-tls -o go-template='{{ index .data "ca.pem" }}' | base64 --decode) + + # create root certificates value file + yq e -n ".ca.cert = \"${caPem}\" | .ca.key = \"${caKey}\"" > "$cert_path" +} + +create_certificate_values_file "$@" diff --git a/getting_started/accessing-your-services.adoc b/getting_started/accessing-your-services.adoc deleted file mode 100644 index cffc2de5a029..000000000000 --- a/getting_started/accessing-your-services.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="accessing-your-services"] -= Accessing your services -include::modules/common-attributes.adoc[] -:context: access - -toc::[] - -Once you have an {product-title} subscription, you can access your services. - -include::modules/dedicated-creating-your-cluster.adoc[leveloffset=+1] - -//// - -== Receiving status updates - -Access the status portal at link:https://status-dedicated.openshift.com[]. You -can also subscribe to notifications via email, SMS, or RSS by changing your -preferences in the status portal. - -//// - -== Requesting support - -If you have questions about your environment or must open a support ticket, -you can open or view a support case in the -link:https://access.redhat.com/support/cases/#/case/list[Red Hat Customer -Portal]. diff --git a/getting_started/dedicated-networking.adoc b/getting_started/dedicated-networking.adoc deleted file mode 100644 index 177410834af6..000000000000 --- a/getting_started/dedicated-networking.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="dedicated-networking"] -= Neworking -include::modules/common-attributes.adoc[] -:context: access - -toc::[] - -include::modules/dedicated-configuring-your-application-routes.adoc[leveloffset=+1] -include::modules/dedicated-exposing-TCP-services.adoc[leveloffset=+1] diff --git a/getting_started/deleting-your-cluster.adoc b/getting_started/deleting-your-cluster.adoc deleted file mode 100644 index 78bee7785c3e..000000000000 --- a/getting_started/deleting-your-cluster.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="deleting-your-cluster"] -= Deleting your cluster -include::modules/common-attributes.adoc[] -:context: access - -To delete your {product-title} cluster: - -. From link:https://cloud.redhat.com/openshift[cloud.redhat.com/openshift], click - on the cluster you want to delete. - -. Click the *Actions* button, then *Delete Cluster*. - -. Type the name of the cluster highlighted in bold, then click *Delete*. - -Cluster deletion occurs automatically. diff --git a/getting_started/scaling-your-cluster.adoc b/getting_started/scaling-your-cluster.adoc deleted file mode 100644 index 1a63dd5c1d3d..000000000000 --- a/getting_started/scaling-your-cluster.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="scaling-your-cluster"] -= Scaling your cluster -include::modules/common-attributes.adoc[] -:context: access - -toc::[] - -include::modules/dedicated-scaling-your-cluster.adoc[leveloffset=+1] diff --git a/gitleaks.toml b/gitleaks.toml new file mode 100644 index 000000000000..849f8678e2b4 --- /dev/null +++ b/gitleaks.toml @@ -0,0 +1,23 @@ +# Only [allowlist] is picked up by the LeakTK scanning service +[allowlist] + description = "Repo Allowlist" + paths = [ + 'modules/custom-cert-new-install.adoc', + 'modules/custom-cert-existing.adoc', + + # Some test ignores for working with the scanner's unit tests + '''ignore\.d''', + '''\.ignore\.txt$''', + + # Ignore the .gitleaks.toml + '''\.gitleaks\.toml$''', + ] + regexes = [ + # '''custom-regexes-to-ignore-here''', + ] + +# [[rules]] are not picked up by the LeakTK scanning service +[[rules]] + description = "fake-leaks-custom-rule" + regex = '''asdfasdfasdfasdf''' + tags = ["fake-leaks-custom-rule"] \ No newline at end of file diff --git a/images/135_OpenShift_Distributed_Unit_0121.svg b/images/135_OpenShift_Distributed_Unit_0121.svg deleted file mode 100644 index bac62a3ed04f..000000000000 --- a/images/135_OpenShift_Distributed_Unit_0121.svg +++ /dev/null @@ -1 +0,0 @@ -RAN boundaryCentral unit (CU),control planeCentral unit (CU),user plane135_OpenShift_0121Distributed unit (DU)Radio unit (RU) \ No newline at end of file diff --git a/images/142_OpenShift_credentials_STS_0221.svg b/images/142_OpenShift_credentials_STS_0221.svg deleted file mode 100644 index 0b90d3f8a49c..000000000000 --- a/images/142_OpenShift_credentials_STS_0221.svg +++ /dev/null @@ -1 +0,0 @@ -142_OpenShift_0221PodOpenShiftAWSAWS servicesS3 bucketwith OIDC configurationIAM Role for podIAM Identity ProviderProjectedServiceAccount tokenAWS config fileToken signingTrusttokenssignedPublic keyPrivate keyServiceAccountsigning keys \ No newline at end of file diff --git a/images/150_OpenShift_VMware_on_AWS_0321_arch.svg b/images/150_OpenShift_VMware_on_AWS_0321_arch.svg deleted file mode 100644 index 963242149269..000000000000 --- a/images/150_OpenShift_VMware_on_AWS_0321_arch.svg +++ /dev/null @@ -1 +0,0 @@ -RWO PVCsVMware Cloud on AWSOpenShiftvSphere 7OpenShift SDNOpenShift integrated load balancer and ingressNSX-TVSANvCenterContainersAppAppAppControl plane VMInfra VMWorker VM150_OpenShift_0321 \ No newline at end of file diff --git a/images/92_OpenShift_Cluster_Install_RHV_0520.png b/images/92_OpenShift_Cluster_Install_RHV_0520.png deleted file mode 100644 index 885d338abe38..000000000000 Binary files a/images/92_OpenShift_Cluster_Install_RHV_0520.png and /dev/null differ diff --git a/images/OCP_3_to_4_App_migration.png b/images/OCP_3_to_4_App_migration.png deleted file mode 100644 index a1f14cd4dd89..000000000000 Binary files a/images/OCP_3_to_4_App_migration.png and /dev/null differ diff --git a/images/Operator_Icon-OpenShift_Virtualization-5.png b/images/Operator_Icon-OpenShift_Virtualization-5.png deleted file mode 100644 index 7fd768c9155b..000000000000 Binary files a/images/Operator_Icon-OpenShift_Virtualization-5.png and /dev/null differ diff --git a/images/acs-architecture-external-components.png b/images/acs-architecture-external-components.png new file mode 100644 index 000000000000..00c7a7f0972a Binary files /dev/null and b/images/acs-architecture-external-components.png differ diff --git a/images/acs-architecture-kubernetes.png b/images/acs-architecture-kubernetes.png new file mode 100644 index 000000000000..3b22a7f20e36 Binary files /dev/null and b/images/acs-architecture-kubernetes.png differ diff --git a/images/acs-architecture-ocp.png b/images/acs-architecture-ocp.png new file mode 100644 index 000000000000..0d3c156b4c76 Binary files /dev/null and b/images/acs-architecture-ocp.png differ diff --git a/images/acs-architecture-scannerv4.png b/images/acs-architecture-scannerv4.png new file mode 100644 index 000000000000..77ab263008da Binary files /dev/null and b/images/acs-architecture-scannerv4.png differ diff --git a/images/acs-architecture.png b/images/acs-architecture.png new file mode 100644 index 000000000000..bb9b9a0d9fe7 Binary files /dev/null and b/images/acs-architecture.png differ diff --git a/images/acs-collector-startup-process.png b/images/acs-collector-startup-process.png new file mode 100644 index 000000000000..fcc862605505 Binary files /dev/null and b/images/acs-collector-startup-process.png differ diff --git a/images/acscs-architecture-scannerv4.png b/images/acscs-architecture-scannerv4.png new file mode 100644 index 000000000000..888496d5091b Binary files /dev/null and b/images/acscs-architecture-scannerv4.png differ diff --git a/images/acscs-architecture.png b/images/acscs-architecture.png new file mode 100644 index 000000000000..6515a62e84a0 Binary files /dev/null and b/images/acscs-architecture.png differ diff --git a/images/add-serverless-app-dev.png b/images/add-serverless-app-dev.png deleted file mode 100644 index 1e69d3206d9c..000000000000 Binary files a/images/add-serverless-app-dev.png and /dev/null differ diff --git a/images/add-trigger-odc.png b/images/add-trigger-odc.png deleted file mode 100644 index b5c98cc4bd9b..000000000000 Binary files a/images/add-trigger-odc.png and /dev/null differ diff --git a/images/admin-console-create-binding-event-source-1.png b/images/admin-console-create-binding-event-source-1.png deleted file mode 100644 index 0f30f0cb4399..000000000000 Binary files a/images/admin-console-create-binding-event-source-1.png and /dev/null differ diff --git a/images/admin-console-create-binding-event-source-2.png b/images/admin-console-create-binding-event-source-2.png deleted file mode 100644 index 5b9b512c7baf..000000000000 Binary files a/images/admin-console-create-binding-event-source-2.png and /dev/null differ diff --git a/images/admin-console-create-role-event-source.png b/images/admin-console-create-role-event-source.png deleted file mode 100644 index 621b1b555223..000000000000 Binary files a/images/admin-console-create-role-event-source.png and /dev/null differ diff --git a/images/admin-console-create-sa-event-source.png b/images/admin-console-create-sa-event-source.png deleted file mode 100644 index a1501d594768..000000000000 Binary files a/images/admin-console-create-sa-event-source.png and /dev/null differ diff --git a/images/api-admission-chain.png b/images/api-admission-chain.png deleted file mode 100644 index 8c483eab6d3c..000000000000 Binary files a/images/api-admission-chain.png and /dev/null differ diff --git a/images/app-launcher.png b/images/app-launcher.png deleted file mode 100644 index 6a5ac43a54c8..000000000000 Binary files a/images/app-launcher.png and /dev/null differ diff --git a/images/architecture_overview.png b/images/architecture_overview.png deleted file mode 100644 index 55f1e2cee849..000000000000 Binary files a/images/architecture_overview.png and /dev/null differ diff --git a/images/bringing_it_all_together.png b/images/bringing_it_all_together.png deleted file mode 100644 index 557d6196f208..000000000000 Binary files a/images/bringing_it_all_together.png and /dev/null differ diff --git a/images/build_process1.png b/images/build_process1.png deleted file mode 100644 index c721722629e3..000000000000 Binary files a/images/build_process1.png and /dev/null differ diff --git a/images/build_process2.png b/images/build_process2.png deleted file mode 100644 index 8edbaf557cc9..000000000000 Binary files a/images/build_process2.png and /dev/null differ diff --git a/images/collection-rules.png b/images/collection-rules.png new file mode 100644 index 000000000000..496c27979952 Binary files /dev/null and b/images/collection-rules.png differ diff --git a/images/collection-side-panel.png b/images/collection-side-panel.png new file mode 100644 index 000000000000..8ee5fd3633ee Binary files /dev/null and b/images/collection-side-panel.png differ diff --git a/images/create-eventing-namespace.png b/images/create-eventing-namespace.png deleted file mode 100644 index cd316ed23011..000000000000 Binary files a/images/create-eventing-namespace.png and /dev/null differ diff --git a/images/create-nodes.png b/images/create-nodes.png deleted file mode 100644 index 69480a95d048..000000000000 Binary files a/images/create-nodes.png and /dev/null differ diff --git a/images/create-push-app.png b/images/create-push-app.png deleted file mode 100644 index a81d88d2fa1c..000000000000 Binary files a/images/create-push-app.png and /dev/null differ diff --git a/images/create-serving-namespace.png b/images/create-serving-namespace.png deleted file mode 100644 index 9d8ef2abb9ce..000000000000 Binary files a/images/create-serving-namespace.png and /dev/null differ diff --git a/images/create-silence.png b/images/create-silence.png deleted file mode 100644 index 4085666a23df..000000000000 Binary files a/images/create-silence.png and /dev/null differ diff --git a/images/create-sub-ODC.png b/images/create-sub-ODC.png deleted file mode 100644 index 54a81308a898..000000000000 Binary files a/images/create-sub-ODC.png and /dev/null differ diff --git a/images/csi-arch.png b/images/csi-arch.png deleted file mode 100644 index ffaa509ae5ab..000000000000 Binary files a/images/csi-arch.png and /dev/null differ diff --git a/images/cso-namespace-vulnerable.png b/images/cso-namespace-vulnerable.png deleted file mode 100644 index 948a6dc81276..000000000000 Binary files a/images/cso-namespace-vulnerable.png and /dev/null differ diff --git a/images/cso-registry-vulnerable.png b/images/cso-registry-vulnerable.png deleted file mode 100644 index c9b147d11cf3..000000000000 Binary files a/images/cso-registry-vulnerable.png and /dev/null differ diff --git a/images/custom_4.5.png b/images/custom_4.5.png deleted file mode 100644 index 7a8d1607d2cd..000000000000 Binary files a/images/custom_4.5.png and /dev/null differ diff --git a/images/custom_4.5.svg b/images/custom_4.5.svg deleted file mode 100644 index 8116cb5e88eb..000000000000 --- a/images/custom_4.5.svg +++ /dev/null @@ -1 +0,0 @@ -namespace/openshift-authenticationsecrets/v4-0-config-system-router-certs11namespace/openshift-consoleconfigmaps/default-ingress-cert11configmaps/serviceacount-ca11namespace/openshift-kube-controller-managerconfigmaps/serviceacount-ca11namespace/openshift-kube-schedulerconfigmaps/proxy-ca10configmaps/my-certificatenamespace/openshift-ingressnamespace/openshift-ingress-operatornamespace/openshift-config-manageddeployments/router-default3secrets/my-certificate2ingresscontrollers/defaultReferenceContents are copied0namespace/openshift-config8proxies/cluster9User7cluster-scopedsecrets/router-certs4configmaps/default-ingress-cert5configmaps/trusted-ca-bundle6Requesting namespaces75_OpenShift_0520 \ No newline at end of file diff --git a/images/darkcircle-0.png b/images/darkcircle-0.png deleted file mode 100644 index 5ab465076d8f..000000000000 Binary files a/images/darkcircle-0.png and /dev/null differ diff --git a/images/darkcircle-1.png b/images/darkcircle-1.png deleted file mode 100644 index 7b16d8ed9932..000000000000 Binary files a/images/darkcircle-1.png and /dev/null differ diff --git a/images/darkcircle-10.png b/images/darkcircle-10.png deleted file mode 100644 index dfdc4f8d4ea4..000000000000 Binary files a/images/darkcircle-10.png and /dev/null differ diff --git a/images/darkcircle-11.png b/images/darkcircle-11.png deleted file mode 100644 index 9bdcfea71d14..000000000000 Binary files a/images/darkcircle-11.png and /dev/null differ diff --git a/images/darkcircle-12.png b/images/darkcircle-12.png deleted file mode 100644 index 303bcd41f52d..000000000000 Binary files a/images/darkcircle-12.png and /dev/null differ diff --git a/images/darkcircle-2.png b/images/darkcircle-2.png deleted file mode 100644 index a537be6f42c8..000000000000 Binary files a/images/darkcircle-2.png and /dev/null differ diff --git a/images/darkcircle-3.png b/images/darkcircle-3.png deleted file mode 100644 index a22625c683a8..000000000000 Binary files a/images/darkcircle-3.png and /dev/null differ diff --git a/images/darkcircle-4.png b/images/darkcircle-4.png deleted file mode 100644 index 27d03e8c1f30..000000000000 Binary files a/images/darkcircle-4.png and /dev/null differ diff --git a/images/darkcircle-5.png b/images/darkcircle-5.png deleted file mode 100644 index 8a59e47b1498..000000000000 Binary files a/images/darkcircle-5.png and /dev/null differ diff --git a/images/darkcircle-6.png b/images/darkcircle-6.png deleted file mode 100644 index c8b686908d54..000000000000 Binary files a/images/darkcircle-6.png and /dev/null differ diff --git a/images/darkcircle-7.png b/images/darkcircle-7.png deleted file mode 100644 index 2503523947d4..000000000000 Binary files a/images/darkcircle-7.png and /dev/null differ diff --git a/images/darkcircle-8.png b/images/darkcircle-8.png deleted file mode 100644 index b14edd088c2c..000000000000 Binary files a/images/darkcircle-8.png and /dev/null differ diff --git a/images/darkcircle-9.png b/images/darkcircle-9.png deleted file mode 100644 index 5cc237f70578..000000000000 Binary files a/images/darkcircle-9.png and /dev/null differ diff --git a/images/default_4.5.png b/images/default_4.5.png deleted file mode 100644 index 9aa577d33900..000000000000 Binary files a/images/default_4.5.png and /dev/null differ diff --git a/images/default_4.5.svg b/images/default_4.5.svg deleted file mode 100644 index 42ea9d8ad941..000000000000 --- a/images/default_4.5.svg +++ /dev/null @@ -1 +0,0 @@ -namespace/openshift-authenticationsecrets/v4-0-config-system-router-certs11configmaps/detault-ingress-cert11configmaps/serviceacount-ca11namespace/openshift-kube-controller-managerconfigmaps/serviceacount-ca11namespace/openshift-kube-schedulernamespace/openshift-ingressnamespace/openshift-ingress-operatornamespace/openshift-config-manageddeployments/router-default3secrets/router-certs-default2ingresscontrollers/defaultReferenceContents are copied0secrets/router-certs4configmaps/default-ingress-cert5secrets/router-ca1namespace/openshift-console75_OpenShift_0520 \ No newline at end of file diff --git a/images/delete-apiserversource-odc.png b/images/delete-apiserversource-odc.png deleted file mode 100644 index eec08d930913..000000000000 Binary files a/images/delete-apiserversource-odc.png and /dev/null differ diff --git a/images/delete-trigger-odc.png b/images/delete-trigger-odc.png deleted file mode 100644 index abe9bc1d8a49..000000000000 Binary files a/images/delete-trigger-odc.png and /dev/null differ diff --git a/images/delete.png b/images/delete.png deleted file mode 100644 index cec427f39142..000000000000 Binary files a/images/delete.png and /dev/null differ diff --git a/images/developer-catalog.png b/images/developer-catalog.png deleted file mode 100644 index e72996af91aa..000000000000 Binary files a/images/developer-catalog.png and /dev/null differ diff --git a/images/ellipsis-v.svg b/images/ellipsis-v.svg deleted file mode 100644 index c3074e62602a..000000000000 --- a/images/ellipsis-v.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/images/etcd-monitoring-working.png b/images/etcd-monitoring-working.png deleted file mode 100644 index 0c8d1ded9b5e..000000000000 Binary files a/images/etcd-monitoring-working.png and /dev/null differ diff --git a/images/etcd-no-certificate.png b/images/etcd-no-certificate.png deleted file mode 100644 index 7af701b81cf7..000000000000 Binary files a/images/etcd-no-certificate.png and /dev/null differ diff --git a/images/etcd-operator-overview.png b/images/etcd-operator-overview.png deleted file mode 100644 index 72ae3f7901b5..000000000000 Binary files a/images/etcd-operator-overview.png and /dev/null differ diff --git a/images/etcd-operator-resources.png b/images/etcd-operator-resources.png deleted file mode 100644 index dce86b5e8eec..000000000000 Binary files a/images/etcd-operator-resources.png and /dev/null differ diff --git a/images/event-sources-odc.png b/images/event-sources-odc.png deleted file mode 100644 index d3a13fea55a3..000000000000 Binary files a/images/event-sources-odc.png and /dev/null differ diff --git a/images/eventing-conditions-true.png b/images/eventing-conditions-true.png deleted file mode 100644 index ba904f8fcf61..000000000000 Binary files a/images/eventing-conditions-true.png and /dev/null differ diff --git a/images/eventing-form-view.png b/images/eventing-form-view.png deleted file mode 100644 index 935f9b2c2ce6..000000000000 Binary files a/images/eventing-form-view.png and /dev/null differ diff --git a/images/eventing-installed-operator.png b/images/eventing-installed-operator.png deleted file mode 100644 index 469204bad5e8..000000000000 Binary files a/images/eventing-installed-operator.png and /dev/null differ diff --git a/images/eventing-overview.png b/images/eventing-overview.png deleted file mode 100644 index 4264c5bc4d61..000000000000 Binary files a/images/eventing-overview.png and /dev/null differ diff --git a/images/eventing-tab-created.png b/images/eventing-tab-created.png deleted file mode 100644 index 0ffd0754bddb..000000000000 Binary files a/images/eventing-tab-created.png and /dev/null differ diff --git a/images/image_security.png b/images/image_security.png deleted file mode 100644 index a1254d2a273a..000000000000 Binary files a/images/image_security.png and /dev/null differ diff --git a/images/ingress-certificates-workflow.png b/images/ingress-certificates-workflow.png deleted file mode 100644 index 77edf2652acf..000000000000 Binary files a/images/ingress-certificates-workflow.png and /dev/null differ diff --git a/images/installconfig.png b/images/installconfig.png deleted file mode 100644 index cf813b8d0e9c..000000000000 Binary files a/images/installconfig.png and /dev/null differ diff --git a/images/knative-health-status-dash.png b/images/knative-health-status-dash.png deleted file mode 100644 index 08777f160c37..000000000000 Binary files a/images/knative-health-status-dash.png and /dev/null differ diff --git a/images/knative-kafka-overview.png b/images/knative-kafka-overview.png deleted file mode 100644 index 2be315547a64..000000000000 Binary files a/images/knative-kafka-overview.png and /dev/null differ diff --git a/images/knative-serving-cpu-memory-dash.png b/images/knative-serving-cpu-memory-dash.png deleted file mode 100644 index 988d9d7dc9ed..000000000000 Binary files a/images/knative-serving-cpu-memory-dash.png and /dev/null differ diff --git a/images/knative-serving-created.png b/images/knative-serving-created.png deleted file mode 100644 index d6e4f6a47720..000000000000 Binary files a/images/knative-serving-created.png and /dev/null differ diff --git a/images/knative-serving-overview.png b/images/knative-serving-overview.png deleted file mode 100644 index 7980664456f3..000000000000 Binary files a/images/knative-serving-overview.png and /dev/null differ diff --git a/images/migration-PV-copy.png b/images/migration-PV-copy.png deleted file mode 100644 index a5b5baa39d98..000000000000 Binary files a/images/migration-PV-copy.png and /dev/null differ diff --git a/images/migration-PV-move.png b/images/migration-PV-move.png deleted file mode 100644 index 291fce220cf7..000000000000 Binary files a/images/migration-PV-move.png and /dev/null differ diff --git a/images/migration-architecture.png b/images/migration-architecture.png deleted file mode 100644 index 3ba8f035d15c..000000000000 Binary files a/images/migration-architecture.png and /dev/null differ diff --git a/images/mixed-windows-linux-workloads.png b/images/mixed-windows-linux-workloads.png deleted file mode 100644 index 27d4dbe21533..000000000000 Binary files a/images/mixed-windows-linux-workloads.png and /dev/null differ diff --git a/images/monitoring-alert-overview.png b/images/monitoring-alert-overview.png deleted file mode 100644 index c12d2f088e41..000000000000 Binary files a/images/monitoring-alert-overview.png and /dev/null differ diff --git a/images/monitoring-alerting-rule-overview.png b/images/monitoring-alerting-rule-overview.png deleted file mode 100644 index 812668b53be5..000000000000 Binary files a/images/monitoring-alerting-rule-overview.png and /dev/null differ diff --git a/images/monitoring-alerting-rules-screen.png b/images/monitoring-alerting-rules-screen.png deleted file mode 100644 index 401365332e17..000000000000 Binary files a/images/monitoring-alerting-rules-screen.png and /dev/null differ diff --git a/images/monitoring-alerts-screen.png b/images/monitoring-alerts-screen.png deleted file mode 100644 index 0ed404546a33..000000000000 Binary files a/images/monitoring-alerts-screen.png and /dev/null differ diff --git a/images/monitoring-architecture.svg b/images/monitoring-architecture.svg deleted file mode 100644 index 9a648fdc3788..000000000000 --- a/images/monitoring-architecture.svg +++ /dev/null @@ -1 +0,0 @@ -DeployDeployQueriesInstalled by defaultPrometheusOperatorNEPAGrafanaKSMOSMTelemeterClientDeployDeployAlertsDeployUserAlertmanagerOpenShiftProjectsUser-DefinedProjectsAlertsThanos RulerPrometheusThanosQuerierQueriesPrometheusPrometheusOperatorPlatform118_OpenShift_0920DeployDeployClusterMonitoringOperatorClusterVersionOperator \ No newline at end of file diff --git a/images/monitoring-dashboard-administrator.png b/images/monitoring-dashboard-administrator.png deleted file mode 100644 index 2a97d21d48fd..000000000000 Binary files a/images/monitoring-dashboard-administrator.png and /dev/null differ diff --git a/images/monitoring-dashboard-compute-resources.png b/images/monitoring-dashboard-compute-resources.png deleted file mode 100644 index 746e4a177aec..000000000000 Binary files a/images/monitoring-dashboard-compute-resources.png and /dev/null differ diff --git a/images/monitoring-dashboard-developer.png b/images/monitoring-dashboard-developer.png deleted file mode 100644 index 280515bd1748..000000000000 Binary files a/images/monitoring-dashboard-developer.png and /dev/null differ diff --git a/images/monitoring-diagram.png b/images/monitoring-diagram.png deleted file mode 100644 index 3e76816e5ecf..000000000000 Binary files a/images/monitoring-diagram.png and /dev/null differ diff --git a/images/monitoring-metrics-developer.png b/images/monitoring-metrics-developer.png deleted file mode 100644 index cbd0abaa88c0..000000000000 Binary files a/images/monitoring-metrics-developer.png and /dev/null differ diff --git a/images/monitoring-metrics-screen.png b/images/monitoring-metrics-screen.png deleted file mode 100644 index 4058f7f196dd..000000000000 Binary files a/images/monitoring-metrics-screen.png and /dev/null differ diff --git a/images/monitoring-silences-screen.png b/images/monitoring-silences-screen.png deleted file mode 100644 index e46f5925cbad..000000000000 Binary files a/images/monitoring-silences-screen.png and /dev/null differ diff --git a/images/monitoring-yaml-screen.png b/images/monitoring-yaml-screen.png deleted file mode 100644 index f18af6b0cc02..000000000000 Binary files a/images/monitoring-yaml-screen.png and /dev/null differ diff --git a/images/network-graph-20-deployment-mode-updated.png b/images/network-graph-20-deployment-mode-updated.png new file mode 100644 index 000000000000..a3fc13319120 Binary files /dev/null and b/images/network-graph-20-deployment-mode-updated.png differ diff --git a/images/network-graph-20-deployment-mode.png b/images/network-graph-20-deployment-mode.png new file mode 100644 index 000000000000..54fd10bd8d22 Binary files /dev/null and b/images/network-graph-20-deployment-mode.png differ diff --git a/images/network-graph-20-display-options.png b/images/network-graph-20-display-options.png new file mode 100644 index 000000000000..16e122131e01 Binary files /dev/null and b/images/network-graph-20-display-options.png differ diff --git a/images/network-graph-20-namespace-mode.png b/images/network-graph-20-namespace-mode.png new file mode 100644 index 000000000000..da0d4beb9d44 Binary files /dev/null and b/images/network-graph-20-namespace-mode.png differ diff --git a/images/network-graph-20-overview-updated.png b/images/network-graph-20-overview-updated.png new file mode 100644 index 000000000000..b219500d7754 Binary files /dev/null and b/images/network-graph-20-overview-updated.png differ diff --git a/images/network-graph-20-overview.png b/images/network-graph-20-overview.png new file mode 100644 index 000000000000..c45a784f751f Binary files /dev/null and b/images/network-graph-20-overview.png differ diff --git a/images/network-graph-internal-entities.png b/images/network-graph-internal-entities.png new file mode 100644 index 000000000000..722c1f46cc6b Binary files /dev/null and b/images/network-graph-internal-entities.png differ diff --git a/images/node-tuning-operator-workflow-revised.png b/images/node-tuning-operator-workflow-revised.png deleted file mode 100644 index a272e5854265..000000000000 Binary files a/images/node-tuning-operator-workflow-revised.png and /dev/null differ diff --git a/images/nw-egress-ips-diagram.svg b/images/nw-egress-ips-diagram.svg deleted file mode 100644 index 3c996e5648dc..000000000000 --- a/images/nw-egress-ips-diagram.svg +++ /dev/null @@ -1 +0,0 @@ -192.168.126.102Node 3meta:name: node3labels:k8s.ovn.org/egress-assignable: ""Pod network10.128.0.0/14Infrastructure network192.168.126.0/18Externalservice192.168.126.10pod4pod2pod1Node 1meta:name: node1labels:k8s.ovn.org/egress-assignable: ""namespace1namespace2121_OpenShift_1020Node 2meta:name: node2pod3 \ No newline at end of file diff --git a/images/nw-ipsec-encryption.png b/images/nw-ipsec-encryption.png deleted file mode 100644 index 0d1fc46201b1..000000000000 Binary files a/images/nw-ipsec-encryption.png and /dev/null differ diff --git a/images/odc-binding-connector.png b/images/odc-binding-connector.png deleted file mode 100644 index 54facf015b59..000000000000 Binary files a/images/odc-binding-connector.png and /dev/null differ diff --git a/images/odc-recreate-update.png b/images/odc-recreate-update.png deleted file mode 100644 index a0fda1238410..000000000000 Binary files a/images/odc-recreate-update.png and /dev/null differ diff --git a/images/odc-rolling-update.png b/images/odc-rolling-update.png deleted file mode 100644 index 1fa736639419..000000000000 Binary files a/images/odc-rolling-update.png and /dev/null differ diff --git a/images/odc-serverless-app.png b/images/odc-serverless-app.png deleted file mode 100644 index 8378acde156f..000000000000 Binary files a/images/odc-serverless-app.png and /dev/null differ diff --git a/images/odc-serverless-revisions.png b/images/odc-serverless-revisions.png deleted file mode 100644 index b373b4753bdc..000000000000 Binary files a/images/odc-serverless-revisions.png and /dev/null differ diff --git a/images/odc-view-broker.png b/images/odc-view-broker.png deleted file mode 100644 index d8ed44717f51..000000000000 Binary files a/images/odc-view-broker.png and /dev/null differ diff --git a/images/odc-wto-icon.png b/images/odc-wto-icon.png deleted file mode 100644 index 2c323700f609..000000000000 Binary files a/images/odc-wto-icon.png and /dev/null differ diff --git a/images/odc_add_view.png b/images/odc_add_view.png deleted file mode 100644 index d343a614fc41..000000000000 Binary files a/images/odc_add_view.png and /dev/null differ diff --git a/images/odc_app_grouping_label.png b/images/odc_app_grouping_label.png deleted file mode 100644 index 5287234bcbac..000000000000 Binary files a/images/odc_app_grouping_label.png and /dev/null differ diff --git a/images/odc_app_metrics.png b/images/odc_app_metrics.png deleted file mode 100644 index d81ae7902451..000000000000 Binary files a/images/odc_app_metrics.png and /dev/null differ diff --git a/images/odc_application_topology.png b/images/odc_application_topology.png deleted file mode 100644 index f418a45cfe97..000000000000 Binary files a/images/odc_application_topology.png and /dev/null differ diff --git a/images/odc_build_canceled.png b/images/odc_build_canceled.png deleted file mode 100644 index 0e4da383baf5..000000000000 Binary files a/images/odc_build_canceled.png and /dev/null differ diff --git a/images/odc_build_completed.png b/images/odc_build_completed.png deleted file mode 100644 index fa55d761cf79..000000000000 Binary files a/images/odc_build_completed.png and /dev/null differ diff --git a/images/odc_build_failed.png b/images/odc_build_failed.png deleted file mode 100644 index eb5a62cd455f..000000000000 Binary files a/images/odc_build_failed.png and /dev/null differ diff --git a/images/odc_build_new.png b/images/odc_build_new.png deleted file mode 100644 index 52cb97fd6b2c..000000000000 Binary files a/images/odc_build_new.png and /dev/null differ diff --git a/images/odc_build_pending.png b/images/odc_build_pending.png deleted file mode 100644 index a9d4615733d3..000000000000 Binary files a/images/odc_build_pending.png and /dev/null differ diff --git a/images/odc_build_running.png b/images/odc_build_running.png deleted file mode 100644 index a0aaa83590f0..000000000000 Binary files a/images/odc_build_running.png and /dev/null differ diff --git a/images/odc_che_workspace.png b/images/odc_che_workspace.png deleted file mode 100644 index fd17944d96c3..000000000000 Binary files a/images/odc_che_workspace.png and /dev/null differ diff --git a/images/odc_connecting_multiple_applications.png b/images/odc_connecting_multiple_applications.png deleted file mode 100644 index 510ffbd3fc31..000000000000 Binary files a/images/odc_connecting_multiple_applications.png and /dev/null differ diff --git a/images/odc_connector.png b/images/odc_connector.png deleted file mode 100644 index ec6be7fc5873..000000000000 Binary files a/images/odc_connector.png and /dev/null differ diff --git a/images/odc_create_project.png b/images/odc_create_project.png deleted file mode 100644 index 23a8dda1916f..000000000000 Binary files a/images/odc_create_project.png and /dev/null differ diff --git a/images/odc_devcatalog_mariadb.png b/images/odc_devcatalog_mariadb.png deleted file mode 100644 index 6ea516d4969a..000000000000 Binary files a/images/odc_devcatalog_mariadb.png and /dev/null differ diff --git a/images/odc_devcatalog_toplogy.png b/images/odc_devcatalog_toplogy.png deleted file mode 100644 index 951ede330b87..000000000000 Binary files a/images/odc_devcatalog_toplogy.png and /dev/null differ diff --git a/images/odc_developer_perspective.png b/images/odc_developer_perspective.png deleted file mode 100644 index ad24511c19c0..000000000000 Binary files a/images/odc_developer_perspective.png and /dev/null differ diff --git a/images/odc_edit_app.png b/images/odc_edit_app.png deleted file mode 100644 index bdf41a27b477..000000000000 Binary files a/images/odc_edit_app.png and /dev/null differ diff --git a/images/odc_edit_redeploy.png b/images/odc_edit_redeploy.png deleted file mode 100644 index 3708f2868262..000000000000 Binary files a/images/odc_edit_redeploy.png and /dev/null differ diff --git a/images/odc_git_repository.png b/images/odc_git_repository.png deleted file mode 100644 index 4b22c5d567c1..000000000000 Binary files a/images/odc_git_repository.png and /dev/null differ diff --git a/images/odc_helm_chart_devcatalog.png b/images/odc_helm_chart_devcatalog.png deleted file mode 100644 index 53dbf118cfcb..000000000000 Binary files a/images/odc_helm_chart_devcatalog.png and /dev/null differ diff --git a/images/odc_helm_chart_repo_filter.png b/images/odc_helm_chart_repo_filter.png deleted file mode 100644 index bfc44325b1a2..000000000000 Binary files a/images/odc_helm_chart_repo_filter.png and /dev/null differ diff --git a/images/odc_helm_chart_select_chart_ver.png b/images/odc_helm_chart_select_chart_ver.png deleted file mode 100644 index 6d7b52aa2d92..000000000000 Binary files a/images/odc_helm_chart_select_chart_ver.png and /dev/null differ diff --git a/images/odc_helm_revision_history.png b/images/odc_helm_revision_history.png deleted file mode 100644 index 1cee05afb284..000000000000 Binary files a/images/odc_helm_revision_history.png and /dev/null differ diff --git a/images/odc_info.png b/images/odc_info.png deleted file mode 100644 index c59cfc70e233..000000000000 Binary files a/images/odc_info.png and /dev/null differ diff --git a/images/odc_list_view_icon.png b/images/odc_list_view_icon.png deleted file mode 100644 index 4a6013aba005..000000000000 Binary files a/images/odc_list_view_icon.png and /dev/null differ diff --git a/images/odc_open_url.png b/images/odc_open_url.png deleted file mode 100644 index ad5498ec94a2..000000000000 Binary files a/images/odc_open_url.png and /dev/null differ diff --git a/images/odc_pod_failed.png b/images/odc_pod_failed.png deleted file mode 100644 index 94bb0a686b09..000000000000 Binary files a/images/odc_pod_failed.png and /dev/null differ diff --git a/images/odc_pod_not_ready.png b/images/odc_pod_not_ready.png deleted file mode 100644 index 5b0f76daa2f8..000000000000 Binary files a/images/odc_pod_not_ready.png and /dev/null differ diff --git a/images/odc_pod_pending.png b/images/odc_pod_pending.png deleted file mode 100644 index c0181dfdba37..000000000000 Binary files a/images/odc_pod_pending.png and /dev/null differ diff --git a/images/odc_pod_running.png b/images/odc_pod_running.png deleted file mode 100644 index 75c015fab634..000000000000 Binary files a/images/odc_pod_running.png and /dev/null differ diff --git a/images/odc_pod_succeeded.png b/images/odc_pod_succeeded.png deleted file mode 100644 index 257b956f58dc..000000000000 Binary files a/images/odc_pod_succeeded.png and /dev/null differ diff --git a/images/odc_pod_terminating.png b/images/odc_pod_terminating.png deleted file mode 100644 index f4f3fcdd3772..000000000000 Binary files a/images/odc_pod_terminating.png and /dev/null differ diff --git a/images/odc_pod_unknown.png b/images/odc_pod_unknown.png deleted file mode 100644 index d4d0b65664ff..000000000000 Binary files a/images/odc_pod_unknown.png and /dev/null differ diff --git a/images/odc_pod_warning.png b/images/odc_pod_warning.png deleted file mode 100644 index 8a6d5afb5bfa..000000000000 Binary files a/images/odc_pod_warning.png and /dev/null differ diff --git a/images/odc_project_alerts.png b/images/odc_project_alerts.png deleted file mode 100644 index 7266b3776829..000000000000 Binary files a/images/odc_project_alerts.png and /dev/null differ diff --git a/images/odc_project_dashboard.png b/images/odc_project_dashboard.png deleted file mode 100644 index 03da036fa655..000000000000 Binary files a/images/odc_project_dashboard.png and /dev/null differ diff --git a/images/odc_project_events.png b/images/odc_project_events.png deleted file mode 100644 index a24cc1e0903a..000000000000 Binary files a/images/odc_project_events.png and /dev/null differ diff --git a/images/odc_project_metrics.png b/images/odc_project_metrics.png deleted file mode 100644 index bd6ded4a54b4..000000000000 Binary files a/images/odc_project_metrics.png and /dev/null differ diff --git a/images/odc_project_permissions.png b/images/odc_project_permissions.png deleted file mode 100644 index b2f34484fd72..000000000000 Binary files a/images/odc_project_permissions.png and /dev/null differ diff --git a/images/odc_serverless_app.png b/images/odc_serverless_app.png deleted file mode 100644 index 2b748c403b17..000000000000 Binary files a/images/odc_serverless_app.png and /dev/null differ diff --git a/images/odc_topology_view_icon.png b/images/odc_topology_view_icon.png deleted file mode 100644 index 76b517a24145..000000000000 Binary files a/images/odc_topology_view_icon.png and /dev/null differ diff --git a/images/oke-about.png b/images/oke-about.png deleted file mode 100644 index bd07fe730c03..000000000000 Binary files a/images/oke-about.png and /dev/null differ diff --git a/images/olm-catalog-sources.png b/images/olm-catalog-sources.png deleted file mode 100644 index 2a8e7dbbc0da..000000000000 Binary files a/images/olm-catalog-sources.png and /dev/null differ diff --git a/images/olm-catalogsource.png b/images/olm-catalogsource.png deleted file mode 100644 index 7d7401cf7836..000000000000 Binary files a/images/olm-catalogsource.png and /dev/null differ diff --git a/images/olm-channels.png b/images/olm-channels.png deleted file mode 100644 index 845d72a77560..000000000000 Binary files a/images/olm-channels.png and /dev/null differ diff --git a/images/olm-manualapproval.png b/images/olm-manualapproval.png deleted file mode 100644 index 01f91f101de9..000000000000 Binary files a/images/olm-manualapproval.png and /dev/null differ diff --git a/images/olm-operator-delete.png b/images/olm-operator-delete.png deleted file mode 100644 index 1bde1467f2c2..000000000000 Binary files a/images/olm-operator-delete.png and /dev/null differ diff --git a/images/olm-operatorhub.png b/images/olm-operatorhub.png deleted file mode 100644 index 713179f2461e..000000000000 Binary files a/images/olm-operatorhub.png and /dev/null differ diff --git a/images/olm-replaces.png b/images/olm-replaces.png deleted file mode 100644 index 5394fee620c0..000000000000 Binary files a/images/olm-replaces.png and /dev/null differ diff --git a/images/olm-skipping-updates.png b/images/olm-skipping-updates.png deleted file mode 100644 index dae054588cff..000000000000 Binary files a/images/olm-skipping-updates.png and /dev/null differ diff --git a/images/olm-uptodate.png b/images/olm-uptodate.png deleted file mode 100644 index 2176cd097594..000000000000 Binary files a/images/olm-uptodate.png and /dev/null differ diff --git a/images/olm-workflow.png b/images/olm-workflow.png deleted file mode 100644 index aeb48f3ecb0e..000000000000 Binary files a/images/olm-workflow.png and /dev/null differ diff --git a/images/olm-z-stream.png b/images/olm-z-stream.png deleted file mode 100644 index b55a5ffa0c83..000000000000 Binary files a/images/olm-z-stream.png and /dev/null differ diff --git a/images/op-install-subscription.png b/images/op-install-subscription.png deleted file mode 100644 index 5f41c09482f3..000000000000 Binary files a/images/op-install-subscription.png and /dev/null differ diff --git a/images/op-installed-tile.png b/images/op-installed-tile.png deleted file mode 100644 index dfd4af39fca7..000000000000 Binary files a/images/op-installed-tile.png and /dev/null differ diff --git a/images/op-pipeline-builder-task-details.png b/images/op-pipeline-builder-task-details.png deleted file mode 100644 index 34b2f08e3fa0..000000000000 Binary files a/images/op-pipeline-builder-task-details.png and /dev/null differ diff --git a/images/op-pipeline-builder.png b/images/op-pipeline-builder.png deleted file mode 100644 index 8632169940e3..000000000000 Binary files a/images/op-pipeline-builder.png and /dev/null differ diff --git a/images/op-pipeline-details.png b/images/op-pipeline-details.png deleted file mode 100644 index 38027180a237..000000000000 Binary files a/images/op-pipeline-details.png and /dev/null differ diff --git a/images/op-pipeline-yaml.png b/images/op-pipeline-yaml.png deleted file mode 100644 index 2db38a6d1bf8..000000000000 Binary files a/images/op-pipeline-yaml.png and /dev/null differ diff --git a/images/op_pipeline_run.png b/images/op_pipeline_run.png deleted file mode 100644 index 145915eff5e6..000000000000 Binary files a/images/op_pipeline_run.png and /dev/null differ diff --git a/images/op_pipeline_topology.png b/images/op_pipeline_topology.png deleted file mode 100644 index 94d65ea12616..000000000000 Binary files a/images/op_pipeline_topology.png and /dev/null differ diff --git a/images/operator-maturity-model.png b/images/operator-maturity-model.png deleted file mode 100644 index c4f745c299f8..000000000000 Binary files a/images/operator-maturity-model.png and /dev/null differ diff --git a/images/orchestration.png b/images/orchestration.png deleted file mode 100644 index 4e77da1c5d8f..000000000000 Binary files a/images/orchestration.png and /dev/null differ diff --git a/images/osdk-workflow.png b/images/osdk-workflow.png deleted file mode 100644 index 2fb5236bcef3..000000000000 Binary files a/images/osdk-workflow.png and /dev/null differ diff --git a/images/ossm-grafana-dashboard-no-traffic.png b/images/ossm-grafana-dashboard-no-traffic.png deleted file mode 100644 index 7c2182c016b3..000000000000 Binary files a/images/ossm-grafana-dashboard-no-traffic.png and /dev/null differ diff --git a/images/ossm-grafana-home-screen.png b/images/ossm-grafana-home-screen.png deleted file mode 100644 index 0690720c6a47..000000000000 Binary files a/images/ossm-grafana-home-screen.png and /dev/null differ diff --git a/images/ossm-grafana-mesh-no-traffic.png b/images/ossm-grafana-mesh-no-traffic.png deleted file mode 100644 index c5f717e266a0..000000000000 Binary files a/images/ossm-grafana-mesh-no-traffic.png and /dev/null differ diff --git a/images/ossm-grafana-mesh-with-traffic.png b/images/ossm-grafana-mesh-with-traffic.png deleted file mode 100644 index 37e53db9e305..000000000000 Binary files a/images/ossm-grafana-mesh-with-traffic.png and /dev/null differ diff --git a/images/ossm-grafana-services.png b/images/ossm-grafana-services.png deleted file mode 100644 index dec1e32dcd1c..000000000000 Binary files a/images/ossm-grafana-services.png and /dev/null differ diff --git a/images/ossm-grafana-workloads.png b/images/ossm-grafana-workloads.png deleted file mode 100644 index a32e69e3e64f..000000000000 Binary files a/images/ossm-grafana-workloads.png and /dev/null differ diff --git a/images/ossm-jaeger-main-screen.png b/images/ossm-jaeger-main-screen.png deleted file mode 100644 index 9a1aabc199fb..000000000000 Binary files a/images/ossm-jaeger-main-screen.png and /dev/null differ diff --git a/images/ossm-jaeger-spans.png b/images/ossm-jaeger-spans.png deleted file mode 100644 index 24a347728dff..000000000000 Binary files a/images/ossm-jaeger-spans.png and /dev/null differ diff --git a/images/ossm-kiali-services-list.png b/images/ossm-kiali-services-list.png deleted file mode 100644 index 169e6ad6d9f4..000000000000 Binary files a/images/ossm-kiali-services-list.png and /dev/null differ diff --git a/images/ossm-prometheus-home-screen.png b/images/ossm-prometheus-home-screen.png deleted file mode 100644 index c570ae4b41cc..000000000000 Binary files a/images/ossm-prometheus-home-screen.png and /dev/null differ diff --git a/images/ossm-prometheus-metrics.png b/images/ossm-prometheus-metrics.png deleted file mode 100644 index c115e31d2441..000000000000 Binary files a/images/ossm-prometheus-metrics.png and /dev/null differ diff --git a/images/product-workflow-overview.png b/images/product-workflow-overview.png deleted file mode 100644 index b6a7872c0f20..000000000000 Binary files a/images/product-workflow-overview.png and /dev/null differ diff --git a/images/question-circle.png b/images/question-circle.png deleted file mode 100644 index a505ba1fcadd..000000000000 Binary files a/images/question-circle.png and /dev/null differ diff --git a/images/quick-start-conclusion.png b/images/quick-start-conclusion.png deleted file mode 100644 index f93257032c6d..000000000000 Binary files a/images/quick-start-conclusion.png and /dev/null differ diff --git a/images/quick-start-description.png b/images/quick-start-description.png deleted file mode 100644 index 87ab4886338a..000000000000 Binary files a/images/quick-start-description.png and /dev/null differ diff --git a/images/quick-start-display-name.png b/images/quick-start-display-name.png deleted file mode 100644 index 669443100878..000000000000 Binary files a/images/quick-start-display-name.png and /dev/null differ diff --git a/images/quick-start-duration.png b/images/quick-start-duration.png deleted file mode 100644 index b1001d3dc4f0..000000000000 Binary files a/images/quick-start-duration.png and /dev/null differ diff --git a/images/quick-start-icon.png b/images/quick-start-icon.png deleted file mode 100644 index 3341a923b9e7..000000000000 Binary files a/images/quick-start-icon.png and /dev/null differ diff --git a/images/quick-start-introduction.png b/images/quick-start-introduction.png deleted file mode 100644 index 3c6e7e4ea9d7..000000000000 Binary files a/images/quick-start-introduction.png and /dev/null differ diff --git a/images/rbac.png b/images/rbac.png deleted file mode 100644 index 63312ea53f2f..000000000000 Binary files a/images/rbac.png and /dev/null differ diff --git a/images/redcircle-1.png b/images/redcircle-1.png deleted file mode 100644 index 4cbb364a2d76..000000000000 Binary files a/images/redcircle-1.png and /dev/null differ diff --git a/images/redcircle-2.png b/images/redcircle-2.png deleted file mode 100644 index 23f4a0d23f93..000000000000 Binary files a/images/redcircle-2.png and /dev/null differ diff --git a/images/redcircle-3.png b/images/redcircle-3.png deleted file mode 100644 index 06ac69f6a99c..000000000000 Binary files a/images/redcircle-3.png and /dev/null differ diff --git a/images/s2i-flow.png b/images/s2i-flow.png deleted file mode 100644 index b7ec58fb6353..000000000000 Binary files a/images/s2i-flow.png and /dev/null differ diff --git a/images/secure_deployments.png b/images/secure_deployments.png deleted file mode 100644 index 57add95959b2..000000000000 Binary files a/images/secure_deployments.png and /dev/null differ diff --git a/images/serverless-create-eventing-yaml.png b/images/serverless-create-eventing-yaml.png deleted file mode 100644 index 45f2af92315a..000000000000 Binary files a/images/serverless-create-eventing-yaml.png and /dev/null differ diff --git a/images/serverless-create-eventing.png b/images/serverless-create-eventing.png deleted file mode 100644 index 05644c6e580d..000000000000 Binary files a/images/serverless-create-eventing.png and /dev/null differ diff --git a/images/serverless-create-namespaces.png b/images/serverless-create-namespaces.png deleted file mode 100644 index 292db72db060..000000000000 Binary files a/images/serverless-create-namespaces.png and /dev/null differ diff --git a/images/serverless-create-service-admin.png b/images/serverless-create-service-admin.png deleted file mode 100644 index b3c99c8ef11f..000000000000 Binary files a/images/serverless-create-service-admin.png and /dev/null differ diff --git a/images/serverless-create-serving-yaml.png b/images/serverless-create-serving-yaml.png deleted file mode 100644 index ba2ca43b38b5..000000000000 Binary files a/images/serverless-create-serving-yaml.png and /dev/null differ diff --git a/images/serverless-create-serving.png b/images/serverless-create-serving.png deleted file mode 100644 index f387294b15d7..000000000000 Binary files a/images/serverless-create-serving.png and /dev/null differ diff --git a/images/serverless-event-broker-workflow.png b/images/serverless-event-broker-workflow.png deleted file mode 100644 index aea669722c38..000000000000 Binary files a/images/serverless-event-broker-workflow.png and /dev/null differ diff --git a/images/serverless-event-channel-workflow.png b/images/serverless-event-channel-workflow.png deleted file mode 100644 index 99957bc3aed7..000000000000 Binary files a/images/serverless-event-channel-workflow.png and /dev/null differ diff --git a/images/serverless-search.png b/images/serverless-search.png deleted file mode 100644 index 4d2af649a02c..000000000000 Binary files a/images/serverless-search.png and /dev/null differ diff --git a/images/serverless-verify-source-channel.png b/images/serverless-verify-source-channel.png deleted file mode 100644 index 0fea95ba5f29..000000000000 Binary files a/images/serverless-verify-source-channel.png and /dev/null differ diff --git a/images/service-yaml-admin.png b/images/service-yaml-admin.png deleted file mode 100644 index 28823e44a019..000000000000 Binary files a/images/service-yaml-admin.png and /dev/null differ diff --git a/images/serving-YAML-HA.png b/images/serving-YAML-HA.png deleted file mode 100644 index 4328ba051027..000000000000 Binary files a/images/serving-YAML-HA.png and /dev/null differ diff --git a/images/serving-conditions-true.png b/images/serving-conditions-true.png deleted file mode 100644 index 22f38a447bab..000000000000 Binary files a/images/serving-conditions-true.png and /dev/null differ diff --git a/images/serving-form-view.png b/images/serving-form-view.png deleted file mode 100644 index 1f9e539fede7..000000000000 Binary files a/images/serving-form-view.png and /dev/null differ diff --git a/images/serving-installed-operator.png b/images/serving-installed-operator.png deleted file mode 100644 index 985c7b7ae836..000000000000 Binary files a/images/serving-installed-operator.png and /dev/null differ diff --git a/images/serving-overview.png b/images/serving-overview.png deleted file mode 100644 index c0e6478a9530..000000000000 Binary files a/images/serving-overview.png and /dev/null differ diff --git a/images/serving-tab-created.png b/images/serving-tab-created.png deleted file mode 100644 index 3f567c56f266..000000000000 Binary files a/images/serving-tab-created.png and /dev/null differ diff --git a/images/silence-overview.png b/images/silence-overview.png deleted file mode 100644 index 5b2093a3a89f..000000000000 Binary files a/images/silence-overview.png and /dev/null differ diff --git a/images/sink-pingsource-channel.png b/images/sink-pingsource-channel.png deleted file mode 100644 index 13cb3365e4ca..000000000000 Binary files a/images/sink-pingsource-channel.png and /dev/null differ diff --git a/images/targets-and-dependencies.png b/images/targets-and-dependencies.png deleted file mode 100644 index cf813b8d0e9c..000000000000 Binary files a/images/targets-and-dependencies.png and /dev/null differ diff --git a/images/telmetry-and-insights-operator-data-flow.svg b/images/telmetry-and-insights-operator-data-flow.svg deleted file mode 100644 index 4d0820cdd731..000000000000 --- a/images/telmetry-and-insights-operator-data-flow.svg +++ /dev/null @@ -1 +0,0 @@ -132_OpenShift_1220KubernetesAPIPrometheusAPIHTTPS (443)HTTPS (443)TelemeterClientOpenShiftContainer PlatformRed HatSupportSubscriptionmanagementOpenShiftCluster ManagerInsightsanalysis enginecloud.redhat.comapi.openshift.comRed HatWebconsoleInsightsOperator \ No newline at end of file diff --git a/images/toplogy-odc-apiserver.png b/images/toplogy-odc-apiserver.png deleted file mode 100644 index 22e6532e2091..000000000000 Binary files a/images/toplogy-odc-apiserver.png and /dev/null differ diff --git a/images/trustedsupplychain.png b/images/trustedsupplychain.png deleted file mode 100644 index e62e0f70824d..000000000000 Binary files a/images/trustedsupplychain.png and /dev/null differ diff --git a/images/verify-channel-odc.png b/images/verify-channel-odc.png deleted file mode 100644 index 43a36617d790..000000000000 Binary files a/images/verify-channel-odc.png and /dev/null differ diff --git a/images/verify-kafka-ODC.png b/images/verify-kafka-ODC.png deleted file mode 100644 index 1f94c0e028c5..000000000000 Binary files a/images/verify-kafka-ODC.png and /dev/null differ diff --git a/images/verify-pingsource-ODC.png b/images/verify-pingsource-ODC.png deleted file mode 100644 index dac0464b36cf..000000000000 Binary files a/images/verify-pingsource-ODC.png and /dev/null differ diff --git a/images/verify-subscription-odc.png b/images/verify-subscription-odc.png deleted file mode 100644 index c621e6d34f18..000000000000 Binary files a/images/verify-subscription-odc.png and /dev/null differ diff --git a/images/verify-trigger-odc.png b/images/verify-trigger-odc.png deleted file mode 100644 index be56d1a87b42..000000000000 Binary files a/images/verify-trigger-odc.png and /dev/null differ diff --git a/images/whatarecontainers.png b/images/whatarecontainers.png deleted file mode 100644 index 8c3bd20379d5..000000000000 Binary files a/images/whatarecontainers.png and /dev/null differ diff --git a/images/wmco-design.png b/images/wmco-design.png deleted file mode 100644 index d2ad6fdca5da..000000000000 Binary files a/images/wmco-design.png and /dev/null differ diff --git a/images/workload-cve-search.png b/images/workload-cve-search.png new file mode 100644 index 000000000000..1a7b7b1b4aa8 Binary files /dev/null and b/images/workload-cve-search.png differ diff --git a/images/workload-cve.png b/images/workload-cve.png new file mode 100644 index 000000000000..b86584657593 Binary files /dev/null and b/images/workload-cve.png differ diff --git a/installing/acs-default-requirements.adoc b/installing/acs-default-requirements.adoc new file mode 100644 index 000000000000..01c8a84ef0a0 --- /dev/null +++ b/installing/acs-default-requirements.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: ASSEMBLY +[id="acs-default-requirements"] += Default resource requirements for {product-title} +include::modules/common-attributes.adoc[] +:context: acs-default-requirements + +toc::[] + +include::modules/acs-requirements.adoc[leveloffset=+1] + +include::modules/default-requirements-central-services.adoc[leveloffset=+1] + +include::modules/default-requirements-secured-cluster-services.adoc[leveloffset=+1] + +include::modules/default-requirements-external-db.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../installing/installing-rhacs-on-red-hat-openshift#provision-postgresql-database_install-central-ocp[Provisioning a database in your PostgreSQL instance] diff --git a/installing/acs-high-level-overview.adoc b/installing/acs-high-level-overview.adoc new file mode 100644 index 000000000000..ce001350fc70 --- /dev/null +++ b/installing/acs-high-level-overview.adoc @@ -0,0 +1,81 @@ +:_mod-docs-content-type: ASSEMBLY +[id="acs-high-level-overview"] +include::modules/common-attributes.adoc[] += High-level {product-title-short} installation overview +:context: acs-high-level-overview + +toc::[] + +[role="_abstract"] +{product-title} ({product-title-short}) provides security services for your self-managed {osp} Kubernetes systems or platforms such as {ocp}, Amazon Elastic Kubernetes Service (Amazon EKS), Google Kubernetes Engine (Google GKE), and Microsoft Azure Kubernetes Service (Microsoft AKS). + +For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. For life cycle support information for {product-title-short}, see the link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. + +[id="general-guidelines_{context}"] +== General installation guidelines + +To ensure the best installation experience, follow these guidelines: + +. Understand the installation platforms and methods described in this module. +. Understand xref:../architecture/acs-architecture.adoc#acs-architecture_acs-architecture[{product-title} architecture]. +. Check the xref:../installing/acs-default-requirements.adoc#acs-default-requirements[default resource requirements]. + + +[id="install-platforms-methods_{context}"] +== Installation methods for different platforms + +[role="_abstract"] +You can perform different types of installations on different platforms. + +[NOTE] +==== +Not all installation methods are supported for all platforms. See the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix] for more information. +==== + +.Platforms and recommended installation methods +[%autowidth] +|=== +|*Platform type*|*Platform*|*Recommended installation methods*|*Installation steps* + +.7+|Managed service platform +|{osp} Dedicated (OSD) +.4+d|Operator (recommended), Helm charts, or `roxctl` CLI ^[1]^ +.4+a| * xref:../installing/installing_ocp/install-central-ocp.adoc#install-central-ocp[Installing Central services for {product-title-short} on {osp}] +* xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#install-secured-cluster-ocp[Installing Secured Cluster services for {product-title-short} on {osp}] + +|Azure {osp} (ARO) + +|{osp} Service on AWS (ROSA) + +|{osp} on {ibm-cloud} + +|Amazon Elastic Kubernetes Service (Amazon EKS) +.3+d|Helm charts (recommended), or `roxctl` CLI ^[1]^ + +.3+a| * xref:../installing/installing_other/install-central-other.adoc#install-central-other[Installing Central services for {product-title-short} on other platforms] +* xref:../installing/installing_other/install-secured-cluster-other.adoc#install-secured-cluster-other[Installing Secured Cluster services for {product-title-short} on other platforms] + +|Google Kubernetes Engine (Google GKE) + +|Microsoft Azure Kubernetes Service (Microsoft AKS) + +.2+|Self-managed platform +|Red{nbsp}Hat {ocp} ({ocp-short}) +.2+d|Operator (recommended), Helm charts, or `roxctl` CLI ^[1]^ +.2+a| * xref:../installing/installing_ocp/install-central-ocp.adoc#install-central-ocp[Installing Central services for {product-title-short} on {osp}] +* xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#install-secured-cluster-ocp[Installing Secured Cluster services for {product-title-short} on {osp}] + +|{osp} Kubernetes Engine (OKE) +|=== + +[.small] +-- +1. Do not use the `roxctl` installation method unless you have specific requirements for following this installation method. +-- + +include::modules/installation-methods-for-different-architectures.adoc[leveloffset=+1] + +//browser support info removed - this info is in the support matrix + +include::modules/installing-rhacs-ocp-steps.adoc[leveloffset=+1] +include::modules/installing-rhacs-kubernetes-steps.adoc[leveloffset=+1] \ No newline at end of file diff --git a/installing/acs-recommended-requirements.adoc b/installing/acs-recommended-requirements.adoc new file mode 100644 index 000000000000..ae10260e467a --- /dev/null +++ b/installing/acs-recommended-requirements.adoc @@ -0,0 +1,29 @@ +:_mod-docs-content-type: ASSEMBLY +[id="acs-recommended-requirements"] += Recommended resource requirements for {product-title} +include::modules/common-attributes.adoc[] +:context: acs-recommended-requirements + +toc::[] + +The recommended resource guidelines were developed by performing a focused test that created the following objects across a given number of namespaces: + +* 10 deployments, with 3 pod replicas in a sleep state, mounting 4 secrets, 4 config maps +* 10 services, each one pointing to the TCP/8080 and TCP/8443 ports of one of the previous deployments +* 1 route pointing to the first of the previous services +* 10 secrets containing 2048 random string characters +* 10 config maps containing 2048 random string characters + +During the analysis of results, the number of deployments is identified as a primary factor for increasing of used resources. And we are using the number of deployments for the estimation of required resources. + +[role="_additional-resources"] +.Additional resources +* xref:../installing/acs-default-requirements.adoc#acs-general-requirements_acs-default-requirements[Default resource requirements] + +include::modules/recommended-requirements-central-services.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../installing/acs-default-requirements.adoc#acs-general-requirements_acs-default-requirements[Default resource requirements] + +include::modules/recommended-requirements-secured-cluster-services.adoc[leveloffset=+1] diff --git a/installing/index.adoc b/installing/index.adoc deleted file mode 100644 index 042b30e2c94b..000000000000 --- a/installing/index.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="ocp-installation-overview"] -= {product-title} installation overview -include::modules/common-attributes.adoc[] -:context: ocp-installation-overview - -toc::[] - -include::modules/installation-overview.adoc[leveloffset=+1] - -include::modules/installation-process.adoc[leveloffset=+2] - -[discrete] -=== Installation scope - -The scope of the {product-title} installation program is intentionally narrow. It is designed for simplicity and ensured success. You can complete many more configuration tasks after installation completes. - -.Additional resources - -* See xref:../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Available cluster customizations] for details about {product-title} configuration resources. - -include::modules/supported-platforms-for-openshift-clusters.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../installing/installing-preparing.adoc#supported-installation-methods-for-different-platforms[Supported installation methods for different platforms] for more information about the types of installations that are available for each supported platform. - -* See xref:../installing/installing-preparing.adoc#installing-preparing[Selecting a cluster installation method and preparing it for users] for information about choosing an installation method and preparing the required resources. diff --git a/installing/install_config/configuring-custom-ca.adoc b/installing/install_config/configuring-custom-ca.adoc deleted file mode 100644 index bb2303b65fc0..000000000000 --- a/installing/install_config/configuring-custom-ca.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="configuring-custom-ca"] -= Configuring a custom certificate authority -include::modules/common-attributes.adoc[] -:context: configuring-custom-ca - -toc::[] - -If you install {product-title} with a proxy or in a restricted network, -you might need to configure a custom certificate authority (CA). - -//include::modules/configuring-firewall.adoc[leveloffset=+1] diff --git a/installing/install_config/configuring-firewall.adoc b/installing/install_config/configuring-firewall.adoc deleted file mode 100644 index ef650000203c..000000000000 --- a/installing/install_config/configuring-firewall.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="configuring-firewall"] -= Configuring your firewall -include::modules/common-attributes.adoc[] -:context: configuring-firewall - -toc::[] - -If you use a firewall, you must configure it so that {product-title} can access the sites that it requires to function. You must always grant access to some sites, and you grant access to more if you use -Red Hat Insights, the Telemetry service, a cloud to host your cluster, and certain build strategies. - -include::modules/configuring-firewall.adoc[leveloffset=+1] diff --git a/installing/install_config/installing-customizing.adoc b/installing/install_config/installing-customizing.adoc deleted file mode 100644 index 66119b17e60f..000000000000 --- a/installing/install_config/installing-customizing.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="installing-customizing"] -= Customizing nodes -include::modules/common-attributes.adoc[] -:context: installing-customizing - -toc::[] - -Although directly making changes to {product-title} nodes is discouraged, -there are times when it is necessary to implement a -required low-level security, redundancy, networking, or performance feature. -Direct changes to {product-title} nodes can be done by: - -* Creating machine configs that are included in manifest files -to start up a cluster during `openshift-install`. - -* Creating machine configs that are passed to running -{product-title} nodes via the Machine Config Operator. - -* Creating an Ignition config that is passed to `coreos-installer` -when installing bare-metal nodes. - -The following sections describe features that you might want to -configure on your nodes in this way. - - -include::modules/installation-special-config-kargs.adoc[leveloffset=+1] -ifdef::openshift-webscale[] -include::modules/installation-special-config-rtkernel.adoc[leveloffset=+1] -endif::openshift-webscale[] -include::modules/installation-special-config-kmod.adoc[leveloffset=+1] -include::modules/installation-special-config-encrypt-disk.adoc[leveloffset=+1] -include::modules/installation-special-config-encrypt-disk-tpm2.adoc[leveloffset=+2] -include::modules/installation-special-config-encrypt-disk-tang.adoc[leveloffset=+2] -include::modules/installation-special-config-mirrored-disk.adoc[leveloffset=+1] -include::modules/installation-special-config-crony.adoc[leveloffset=+1] - -ifndef::openshift-origin[] -== Additional resources - -See xref:../../installing/installing-fips.adoc#installing-fips[Support for FIPS cryptography] -for information on FIPS support. -endif::[] diff --git a/installing/install_config/installing-restricted-networks-preparations.adoc b/installing/install_config/installing-restricted-networks-preparations.adoc deleted file mode 100644 index 13544714894b..000000000000 --- a/installing/install_config/installing-restricted-networks-preparations.adoc +++ /dev/null @@ -1,70 +0,0 @@ -[id="installing-restricted-networks-preparations"] -= Creating a mirror registry for installation in a restricted network -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-preparations - -toc::[] - -Before you install a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. Installations on a restricted network are supported on only infrastructure that you provision, not infrastructure that the installer provisions. You can also use this procedure in unrestricted networks to ensure your clusters only use container images that have satisfied your organizational controls on external content. - -[IMPORTANT] -==== -You must have access to the internet to obtain the necessary container images. -In this procedure, you place the mirror registry on a mirror host -that has access to both your network and the Internet. If you do not have access -to a mirror host, use the disconnected procedure to copy images to a device you -can move across network boundaries with. -==== - -include::modules/installation-about-mirror-registry.adoc[leveloffset=+1] - -[id="installing-preparing-mirror"] -== Preparing your mirror host - -Before you perform the mirror procedure, you must prepare the host to retrieve content -and push it to the remote location. - -include::modules/cli-installing-cli.adoc[leveloffset=+2] - -include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1] - -//This command seems out of place. Where should it really go? -//// -[id="installing-performing-connected-mirror"] -== Performing a mirror while connected to the internet - -$ oc adm release mirror OPENSHIFT_VERSION --to MIRROR_REPOSITORY -//// - -//// -[id="installing-restricted-networks-preparations-mirroring"] -== Mirroring the content - -In production environments, add the required images to a registry in your restricted network. For non-production environments, you can use the images without a separate registry. - - modules/installation-performing-disconnected-mirror.adoc[leveloffset=+2] - - modules/installation-performing-disconnected-mirror-without-registry.adoc[leveloffset=+2] -//// - -include::modules/installation-mirror-repository.adoc[leveloffset=+1] - -include::modules/installation-preparing-restricted-cluster-to-gather-support-data.adoc[leveloffset=+1] - -include::modules/installation-restricted-network-samples.adoc[leveloffset=+1] - -include::modules/installation-images-samples-disconnected-mirroring-assist.adoc[leveloffset=+2] - - -== Next steps - -//* TODO need to add the registry secret to the machines, which is different - -* Install a cluster on infrastructure that you provision in your restricted nework, such as on -xref:../../installing/installing_vsphere/installing-restricted-networks-vsphere.adoc#installing-restricted-networks-vsphere[VMware vSphere], -xref:../../installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc#installing-restricted-networks-bare-metal[bare metal], or xref:../../installing/installing_aws/installing-restricted-networks-aws.adoc#installing-restricted-networks-aws[Amazon Web Services]. - -[id="restricted-networks-additional-resources"] -== Additional resources - -* See xref:../../support/gathering-cluster-data.adoc#gathering-data-specific-features_gathering-cluster-data[Gathering data about specific features] for more information about using must-gather. diff --git a/installing/installing-fips.adoc b/installing/installing-fips.adoc deleted file mode 100644 index 76b9b14f0e0f..000000000000 --- a/installing/installing-fips.adoc +++ /dev/null @@ -1,83 +0,0 @@ -[id="installing-fips"] -= Support for FIPS cryptography -include::modules/common-attributes.adoc[] -:context: installing-fips - -toc::[] - -Starting with version 4.3, you can install an {product-title} cluster that uses FIPS Validated / Modules in Process cryptographic libraries. - -For the {op-system-first} machines in your cluster, this change is applied when the machines are deployed based on the status of an option in the `install-config.yaml` file, which governs the cluster options that a user can change during cluster deployment. With {op-system-base-full} machines, you must enable FIPS mode when you install the operating system on the machines that you plan to use as worker machines. These configuration methods ensure that your cluster meet the requirements of a FIPS compliance audit: only FIPS Validated / Modules in Process cryptography packages are enabled before the initial system boot. - -Because FIPS must be enabled before the operating system that your cluster uses boots for the first time, you cannot enable FIPS after you deploy a cluster. - -[id="installation-about-fips-validation_{context}"] -== FIPS validation in {product-title} - -{product-title} uses certain FIPS Validated / Modules in Process modules within {op-system-base} and {op-system} for the operating system components that it uses. See link:https://access.redhat.com/articles/3359851[RHEL7 core crypto components]. For example, when users SSH into {product-title} clusters and containers, those connections are properly encrypted. - -{product-title} components are written in Go and built with Red Hat's golang compiler. When you enable FIPS mode for your cluster, all {product-title} components that require cryptographic signing call {op-system-base} and {op-system} cryptographic libraries. - -.FIPS mode attributes and limitations in {product-title} {product-version} -[cols="8a,8a",options="header"] -|=== - -|Attributes -|Limitations - -|FIPS support in {op-system-base} 7 operating systems. -.3+|The FIPS implementation does not offer a single function that both computes hash functions and validates the keys that are based on that hash. This limitation will continue to be evaluated and improved in future {product-title} releases. - -|FIPS support in CRI-O runtimes. -|FIPS support in {product-title} services. - -|FIPS Validated / Modules in Process cryptographic module and algorithms that are obtained from {op-system-base} 7 and {op-system} binaries and images. -| - -|Use of FIPS compatible golang compiler. -|TLS FIPS support is not complete but is planned for future {product-title} releases. - -|=== - -[id="installation-about-fips-components_{context}"] -== FIPS support in components that the cluster uses - -Although the {product-title} cluster itself uses FIPS Validated / Modules in Process modules, ensure that the systems that support your {product-title} cluster use FIPS Validated / Modules in Process modules for cryptography. - -[id="installation-about-fips-components-etcd_{context}"] -=== etcd - -To ensure that the secrets that are stored in etcd use FIPS Validated / Modules in Process encryption, boot the node in FIPS mode. After you install the cluster in FIPS mode, you can xref:../security/encrypting-etcd.adoc#encrypting-etcd[encrypt the etcd data] by using the FIPS-approved `aes cbc` cryptographic algorithm. - -[id="installation-about-fips-components-storage_{context}"] -=== Storage - -For local storage, use {op-system-base}-provided disk encryption or Container Native Storage that uses {op-system-base}-provided disk encryption. By storing all data in volumes that use {op-system-base}-provided disk encryption and enabling FIPS mode for your cluster, both data at rest and data in motion, or network data, are protected by FIPS Validated / Modules in Process encryption. -You can configure your cluster to encrypt the root filesystem of each node, as described -in xref:../installing/install_config/installing-customizing.adoc#installing-customizing[Customizing nodes]. - -[id="installation-about-fips-components-runtimes_{context}"] -=== Runtimes - -To ensure that containers know that they are running on a host that is using FIPS Validated / Modules in Process cryptography modules, use CRI-O to manage your runtimes. CRI-O supports FIPS mode, in that it configures the containers to know that they are running in FIPS mode. - -[id="installing-fips-mode_{context}"] -== Installing a cluster in FIPS mode - -To install a cluster in FIPS mode, follow the instructions to install a customized cluster on your preferred infrastructure. Ensure that you set `fips: true` in the `install-config.yaml` file before you deploy your cluster. - -* xref:../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-customizations[Amazon Web Services] -* xref:../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[Microsoft Azure] -* xref:../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Bare metal] -* xref:../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-customizations[Google Cloud Platform] -* xref:../installing/installing_openstack/installing-openstack-installer-custom.adoc#installing-openstack-installer-custom[{rh-openstack-first}] -* xref:../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[VMware vSphere] - -[NOTE] -==== -If you are using Azure File storage, you cannot enable FIPS mode. -==== - -To apply `AES CBC` encryption to your etcd data store, follow the xref:../security/encrypting-etcd.adoc#encrypting-etcd[Encrypting etcd data] process after you install your cluster. - -If you add {op-system-base} nodes to your cluster, ensure that you enable FIPS mode on the machines before their initial boot. See xref:../machine_management/user_infra/adding-rhel-compute.adoc#adding-rhel-compute[Adding RHEL compute machines to an {product-title} cluster] and link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/chap-federal_standards_and_regulations#sec-Enabling-FIPS-Mode[Enabling FIPS Mode] in the {op-system-base} 7 documentation. diff --git a/installing/installing-preparing.adoc b/installing/installing-preparing.adoc deleted file mode 100644 index 7a1eb8607b46..000000000000 --- a/installing/installing-preparing.adoc +++ /dev/null @@ -1,253 +0,0 @@ -[id="installing-preparing"] -= Selecting a cluster installation method and preparing it for users -include::modules/common-attributes.adoc[] -:context: installing-preparing - -toc::[] - -Before you install {product-title}, decide what kind of installation process to follow and make sure you that you have all of the required resources to prepare the cluster for users. - -[id="installing-preparing-selecting-cluster-type"] -== Selecting a cluster installation type -Before you install an {product-title} cluster, you need to select the best installation instructions to follow. Think about your answers to the following questions to select the best option. - -[id="installing-preparing-install-manage"] -=== Do you want to install and manage an {product-title} cluster yourself? - -If you want to install and manage {product-title} yourself, you can install it on the following platforms: - -* Amazon Web Services (AWS) -* Microsoft Azure -* Google Cloud Platform (GCP) -* {rh-openstack} -* {rh-virtualization} -* IBM Z and LinuxONE -* IBM Power -* VMware vSphere -* VMware Cloud (VMC) on AWS -* Bare metal or other platform agnostic infrastructure - -You can deploy an {product-title} 4 cluster to both on-premise hardware and to cloud hosting services, but all of the machines in a cluster must be in the same datacenter or cloud hosting service. - -If you want to use {product-title} but do not want to manage the cluster yourself, you have several managed service options. If you want a cluster that is fully managed by Red Hat, you can use link:https://www.openshift.com/products/dedicated/[OpenShift Dedicated] or link:https://www.openshift.com/products/online/[OpenShift Online]. You can also use OpenShift as a managed service on Azure, AWS, IBM Cloud, or Google Cloud. For more information about managed services, see the link:https://www.openshift.com/products[OpenShift Products] page. - -[id="installing-preparing-migrate"] -=== Have you used {product-title} 3 and want to use {product-title} 4? - -If you used {product-title} 3 and want to try {product-title} 4, you need to understand how different {product-title} 4 is. {product-title} 4 weaves the Operators that package, deploy, and manage Kubernetes applications and the operating system that the platform runs on, {op-system-first}, together seamlessly. Instead of deploying machines and configuring their operating systems so that you can install {product-title} on them, the {op-system} operating system is an integral part of the {product-title} cluster. Deploying the operating system for the cluster machines as part of the installation process for {product-title}. See xref:../migration/migrating_3_4/planning-migration-3-to-4.adoc#migration-comparing-ocp-3-4[Comparing OpenShift Container Platform 3 and OpenShift Container Platform 4]. - -Because you need to provision machines as part of the {product-title} cluster installation process, you cannot upgrade an {product-title} 3 cluster to {product-title} 4. Instead, you must create a new {product-title} 4 cluster and migrate your {product-title} 3 workloads to them. For more information about migrating, see link:https://redhat-cop.github.io/openshift-migration-best-practices/01-planning.html[OpenShift Migration Best Practices]. Because you must migrate to {product-title} 4, you can use any type of production cluster installation process to create your new cluster. - -[id="installing-preparing-existing-components"] -=== Do you want to use existing components in your cluster? - -Because the operating system is integral to {product-title}, it is easier to let the installation program for {product-title} stand up all of the infrastructure. These are called _installer provisioned infrastructure_ installations. In this type of installation, you can provide some existing infrastructure to the cluster, but the installation program deploys all of the machines that your cluster initially needs. - -You can deploy an installer-provisioned infrastructure cluster without specifying any customizations to the cluster or its underlying machines to xref:../installing/installing_aws/installing-aws-default.adoc#installing-aws-default[AWS], xref:../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[Azure], or xref:../installing/installing_gcp/installing-gcp-default.adoc#installing-gcp-default[GCP]. These installation methods are the fastest way to deploy a production-capable {product-title} cluster. - -If you need to perform basic configuration for your installer-provisioned infrastructure cluster, such as the instance type for the cluster machines, you can customize an installation for xref:../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-customizations[AWS], xref:../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[Azure], or xref:../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-customizations[GCP]. - -For installer-provisioned infrastructure installations, you can use an existing xref:../installing/installing_aws/installing-aws-vpc.adoc#installing-aws-vpc[VPC in AWS], xref:../installing/installing_azure/installing-azure-vnet.adoc#installing-azure-vnet[vNet in Azure], or xref:../installing/installing_gcp/installing-gcp-vpc.adoc#installing-gcp-vpc[VPC in GCP]. You can also reuse part of your networking infrastructure so that your cluster in xref:../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[AWS], xref:../installing/installing_azure/installing-azure-network-customizations.adoc#installing-azure-network-customizations[Azure], or xref:../installing/installing_gcp/installing-gcp-network-customizations.adoc#installing-gcp-network-customizations[GCP] can coexist with existing IP address allocations in your environment and integrate with existing MTU and VXLAN configurations. If you have existing accounts and credentials on these clouds, you can re-use them, but you might need to modify the accounts to have the required permissions to install {product-title} clusters on them. - -You can use the installer-provisioned infrastructure method to create appropriate machine instances on your hardware for xref:../installing/installing_rhv/installing-rhv-default.adoc#installing-rhv-default[{rh-virtualization}], xref:../installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc#installing-vsphere-installer-provisioned[vSphere], and xref:../installing/installing_bare_metal_ipi/ipi-install-overview#ipi-install-overview[bare metal]. - -If you want to reuse extensive cloud infrastructure, you can complete a _user-provisioned infrastructure_ installation. With these installations, you manually deploy the machines that your cluster requires during the installation process. If you perform a user-provisioned infrastructure installation on xref:../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[AWS], xref:../installing/installing_azure/installing-azure-user-infra.adoc#installing-azure-user-infra[Azure], or xref:../installing/installing_gcp/installing-gcp-user-infra.adoc#installing-gcp-user-infra[GCP], you can use the provided templates to help you stand up all of the required components. Otherwise, you can use the provider-agnostic installation method to deploy a cluster into other clouds. - -You can also complete a user-provisioned infrastructure installation on your existing hardware. If you use xref:../installing/installing_openstack/installing-openstack-installer-custom.adoc#installing-openstack-installer-custom[{rh-openstack}], xref:../installing/installing_rhv/installing-rhv-user-infra.adoc#installing-rhv-user-infra[{rh-virtualization}], xref:../installing/installing_ibm_z/installing-ibm-z.adoc#installing-ibm-z[IBM Z or LinuxONE], xref:../installing/installing_ibm_power/installing-ibm-power.adoc#installing-ibm-power[IBM Power], or xref:../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[vSphere], use the specific installation instructions to deploy your cluster. If you use other supported hardware, follow the xref:../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[bare metal installation] procedure. - -[id="installing-preparing-security"] -=== Do you need extra security for your cluster? - -If you use a user-provisioned installation method, you can configure a proxy for your cluster. The instructions are included in each installation procedure. - -If you want to prevent your cluster on a public cloud from exposing endpoints externally, you can deploy a private cluster with installer-provisioned infrastructure on xref:../installing/installing_aws/installing-aws-private.adoc#installing-aws-private[AWS], xref:../installing/installing_azure/installing-azure-private.adoc#installing-azure-private[Azure], or xref:../installing/installing_gcp/installing-gcp-private.adoc#installing-gcp-private[GCP]. - -If you need to install your cluster that has limited access to the Internet, such as a disconnected or restricted network cluster, you can xref:../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[mirror the installation packages] and install the cluster from them. Follow detailed instructions for user provisioned infrastructure installations into restricted networks for xref:../installing/installing_aws/installing-restricted-networks-aws.adoc#installing-restricted-networks-aws[AWS], xref:../installing/installing_gcp/installing-restricted-networks-gcp.adoc#installing-restricted-networks-gcp[GCP], xref:../installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc#installing-restricted-networks-ibm-z[IBM Z or LinuxONE], xref:../installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc#installing-restricted-networks-ibm-power[IBM Power], xref:../installing/installing_vsphere/installing-restricted-networks-vsphere.adoc#installing-restricted-networks-vsphere[vSphere], or xref:../installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc#installing-restricted-networks-bare-metal[bare metal]. - -If you need to deploy your cluster to an xref:../installing/installing_aws/installing-aws-government-region.adoc#installing-aws-government-region[AWS GovCloud region] or xref:../installing/installing_azure/installing-azure-government-region.adoc#installing-azure-government-region[Azure government region], you can configure those custom regions during an installer-provisioned infrastructure installation. - -ifndef::openshift-origin[] -You can also configure the cluster machines to use xref:../installing/installing-fips.adoc#installing-fips[FIPS Validated / Modules in Process cryptographic libraries] during installation. -endif::[] - -[id="installing-preparing-cluster-for-users"] -== Preparing your cluster for users after installation - -Some configuration is not required to install the cluster but recommended before your users access the cluster. You can customize the cluster itself by xref:../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[customizing] the Operators that make up your cluster and integrate you cluster with other required systems, such as an identity provider. -//This link will change when we consolidate the customizations page with the post-installation activities. - -For a production cluster, you must configure the following integrations: - -* xref:../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Persistent storage] -* xref:../authentication/understanding-identity-provider.adoc#understanding-identity-provider[An identity provider] -* xref:../monitoring/configuring-the-monitoring-stack.adoc#configuring-the-monitoring-stack[Monitoring core OpenShift Container Platform components] - -[id="installing-preparing-cluster-for-workloads"] -== Preparing your cluster for workloads - -Depending on your workload needs, you might need to take extra steps before you begin deploying applications. For example, after you prepare infrastructure to support your application xref:../cicd/builds/build-strategies.adoc#build-strategies[build strategy], you might need to make provisions for xref:../scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc#cnf-performance-addon-operator-for-low-latency-nodes[low-latency] workloads or to xref:../nodes/pods/nodes-pods-secrets.adoc#nodes-pods-secrets[protect sensitive workloads]. You can also configure xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[monitoring] for application workloads. - -[id="supported-installation-methods-for-different-platforms"] -== Supported installation methods for different platforms - -You can perform different types of installations on different platforms. - -[NOTE] -==== -Not all installation options are supported for all platforms, as shown in the following tables. -==== - -.Installer-provisioned infrastructure options -|=== -ifndef::openshift-origin[] -||AWS |Azure |GCP |OpenStack |RHV |Bare metal |vSphere |VMC |IBM Z |IBM Power -endif::openshift-origin[] -ifdef::openshift-origin[] -||AWS |Azure |GCP |OpenStack |oVirt |Bare metal |vSphere |VMC |IBM Z |IBM Power -endif::openshift-origin[] - -|Default -|xref:../installing/installing_aws/installing-aws-default.adoc#installing-aws-default[X] -|xref:../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[X] -|xref:../installing/installing_gcp/installing-gcp-default.adoc#installing-gcp-default[X] -| -|xref:../installing/installing_rhv/installing-rhv-default.adoc#installing-rhv-default[X] -|xref:../installing/installing_bare_metal_ipi/ipi-install-overview.adoc#ipi-install-overview[X] -|xref:../installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc#installing-vsphere-installer-provisioned[X] -|xref:../installing/installing_vmc/installing-vmc.adoc#installing-vmc[X] -| -| - -|Custom -|xref:../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-customizations[X] -|xref:../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[X] -|xref:../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-customizations[X] -|xref:../installing/installing_openstack/installing-openstack-installer-custom.adoc#installing-openstack-installer-custom[X] -|xref:../installing/installing_rhv/installing-rhv-customizations.adoc#installing-rhv-customizations[X] -| -|xref:../installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc#installing-vsphere-installer-provisioned-customizations[X] -|xref:../installing/installing_vmc/installing-vmc-customizations.adoc#installing-vmc-customizations[X] -| -| - -|Network customization -|xref:../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[X] -|xref:../installing/installing_azure/installing-azure-network-customizations.adoc#installing-azure-network-customizations[X] -|xref:../installing/installing_gcp/installing-gcp-network-customizations.adoc#installing-gcp-network-customizations[X] -| -| -| -|xref:../installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc#installing-vsphere-installer-provisioned-network-customizations[X] -|xref:../installing/installing_vmc/installing-vmc-network-customizations.adoc#installing-vmc-network-customizations[X] -| -| - -|Restricted network -| -| -| -|xref:../installing/installing_openstack/installing-openstack-installer-restricted.adoc#installing-openstack-installer-restricted[X] -|xref:../installing/installing_rhv/installing-rhv-restricted-network.adoc#installing-rhv-restricted-network[X] -| -|xref:../installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc#installing-restricted-networks-installer-provisioned-vsphere[X] -| -| -| - -|Private clusters -|xref:../installing/installing_aws/installing-aws-private.adoc#installing-aws-private[X] -|xref:../installing/installing_azure/installing-azure-private.adoc#installing-azure-private[X] -|xref:../installing/installing_gcp/installing-gcp-private.adoc#installing-gcp-private[X] -| -| -| -| -| -| -| - -|Existing virtual private networks -|xref:../installing/installing_aws/installing-aws-vpc.adoc#installing-aws-vpc[X] -|xref:../installing/installing_azure/installing-azure-vnet.adoc#installing-azure-vnet[X] -|xref:../installing/installing_gcp/installing-gcp-vpc.adoc#installing-gcp-vpc[X] -| -| -| -| -| -| -| - -|Government regions -|xref:../installing/installing_aws/installing-aws-government-region.adoc#installing-aws-government-region[X] -|xref:../installing/installing_azure/installing-azure-government-region.adoc#installing-azure-government-region[X] -| -| -| -| -| -| -| -| - -|=== - -.User-provisioned infrastructure options -|=== -ifndef::openshift-origin[] -||AWS |Azure |GCP |OpenStack |RHV |Bare metal |vSphere |VMC |IBM Z |IBM Power -endif::openshift-origin[] -ifdef::openshift-origin[] -||AWS |Azure |GCP |OpenStack |oVirt |Bare metal |vSphere |VMC |IBM Z |IBM Power -endif::openshift-origin[] - -|Custom -|xref:../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[X] -|xref:../installing/installing_azure/installing-azure-user-infra.adoc#installing-azure-user-infra[X] -|xref:../installing/installing_gcp/installing-gcp-user-infra.adoc#installing-gcp-user-infra[X] -|xref:../installing/installing_openstack/installing-openstack-user.adoc#installing-openstack-user[X] -|xref:../installing/installing_rhv/installing-rhv-user-infra.adoc#installing-rhv-user-infra[X] -|xref:../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[X] -|xref:../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[X] -|xref:../installing/installing_vmc/installing-vmc-user-infra.adoc#installing-vmc-user-infra[X] -|xref:../installing/installing_ibm_z/installing-ibm-z.adoc#installing-ibm-z[X] -|xref:../installing/installing_ibm_power/installing-ibm-power.adoc#installing-ibm-power[X] - -// Add RHV UPI link when docs are available: https://github.com/openshift/openshift-docs/pull/26484 - -|Network customization -| -| -| -| -| -|xref:../installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc#installing-bare-metal-network-customizations[X] -|xref:../installing/installing_vsphere/installing-vsphere-network-customizations.adoc#installing-vsphere-network-customizations[X] -|xref:../installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc#installing-vmc-network-customizations-user-infra[X] -| -| - -|Restricted network -|xref:../installing/installing_aws/installing-restricted-networks-aws.adoc#installing-restricted-networks-aws[X] -| -|xref:../installing/installing_gcp/installing-restricted-networks-gcp.adoc#installing-restricted-networks-gcp[X] -| -| -|xref:../installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc#installing-restricted-networks-bare-metal[X] -|xref:../installing/installing_vsphere/installing-restricted-networks-vsphere.adoc#installing-restricted-networks-vsphere[X] -|xref:../installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc#installing-restricted-networks-vmc-user-infra[X] -|xref:../installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc#installing-restricted-networks-ibm-z[X] -|xref:../installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc#installing-restricted-networks-ibm-power[X] - -|Shared VPC hosted outside of cluster project -| -| -|xref:../installing/installing_gcp/installing-gcp-user-infra-vpc.adoc#installing-gcp-user-infra-vpc[X] -| -| -| -| -| -| - -|=== diff --git a/installing/installing-troubleshooting.adoc b/installing/installing-troubleshooting.adoc deleted file mode 100644 index 73bf777d7ed0..000000000000 --- a/installing/installing-troubleshooting.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="installing-troubleshooting"] -= Troubleshooting installation issues -include::modules/common-attributes.adoc[] -:context: installing-troubleshooting - -toc::[] - -To assist in troubleshooting a failed {product-title} installation, you can -gather logs from the bootstrap and control plane, or master, machines. You can also get debug information from the installation program. - -== Prerequisites - -* You attempted to install an {product-title} cluster, and installation failed. - -include::modules/installation-bootstrap-gather.adoc[leveloffset=+1] - -include::modules/manually-gathering-logs-with-ssh.adoc[leveloffset=+1] - -include::modules/manually-gathering-logs-without-ssh.adoc[leveloffset=+1] - -include::modules/installation-getting-debug-information.adoc[leveloffset=+1] diff --git a/installing/installing_aws/installing-aws-account.adoc b/installing/installing_aws/installing-aws-account.adoc deleted file mode 100644 index 96700a23894f..000000000000 --- a/installing/installing_aws/installing-aws-account.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[id="installing-aws-account"] -= Configuring an AWS account -include::modules/common-attributes.adoc[] -:context: installing-aws-account - -toc::[] - -Before you can install {product-title}, you must configure an -Amazon Web Services (AWS) account. - -include::modules/installation-aws-route53.adoc[leveloffset=+1] - -include::modules/nw-endpoint-route53.adoc[leveloffset=+2] - -include::modules/installation-aws-limits.adoc[leveloffset=+1] - -include::modules/installation-aws-permissions.adoc[leveloffset=+1] - -include::modules/installation-aws-iam-user.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[Manually creating IAM for AWS] for steps to set the Cloud Credential Operator (CCO) to manual mode prior to installation. Use this mode in environments where the cloud identity and access management (IAM) APIs are not reachable, or if you prefer not to store an administrator-level credential secret in the cluster `kube-system` project. - -include::modules/installation-aws-regions.adoc[leveloffset=+1] - -== Next steps - -* Install an {product-title} cluster: -** xref:../../installing/installing_aws/installing-aws-default.adoc#installing-aws-default[Quickly install a cluster] with default options on installer-provisioned infrastructure -** xref:../../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-customizations[Install a cluster with cloud customizations on installer-provisioned infrastructure] -** xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[Install a cluster with network customizations on installer-provisioned infrastructure] -** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Installing a cluster on user-provisioned infrastructure in AWS by using CloudFormation templates] diff --git a/installing/installing_aws/installing-aws-customizations.adoc b/installing/installing_aws/installing-aws-customizations.adoc deleted file mode 100644 index 04814dc88e76..000000000000 --- a/installing/installing_aws/installing-aws-customizations.adoc +++ /dev/null @@ -1,80 +0,0 @@ -[id="installing-aws-customizations"] -= Installing a cluster on AWS with customizations -include::modules/common-attributes.adoc[] -:context: installing-aws-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a customized -cluster on infrastructure that the installation program provisions on -Amazon Web Services (AWS). To customize the installation, you modify -parameters in the `install-config.yaml` file before you install the cluster. - -[NOTE] -==== -The scope of the {product-title} installation configurations is intentionally narrow. It is designed for simplicity and ensured success. You can complete many more {product-title} configuration tasks after an installation completes. -==== - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Configure an AWS account] -to host the cluster. -+ -[IMPORTANT] -==== -If you have an AWS profile stored on your computer, it must not use a temporary -session token that you generated while using a multi-factor authentication -device. The cluster continues to use your current AWS credentials to create -AWS resources for the entire life of the cluster, so you must use long-lived -credentials. To generate appropriate keys, see -link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] -in the AWS documentation. You can supply the keys when you run the installation -program. -==== -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service. - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-aws-config-yaml.adoc[leveloffset=+2] - -// Removing; Proxy not supported for AWS IPI for 4.2 -// include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console. - -== Next steps - -* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation]. -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_aws/installing-aws-default.adoc b/installing/installing_aws/installing-aws-default.adoc deleted file mode 100644 index 6cb5c6371294..000000000000 --- a/installing/installing_aws/installing-aws-default.adoc +++ /dev/null @@ -1,68 +0,0 @@ -[id="installing-aws-default"] -= Installing a cluster quickly on AWS -include::modules/common-attributes.adoc[] -:context: installing-aws-default - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -Amazon Web Services (AWS) that uses the default configuration options. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Configure an AWS account] -to host the cluster. -+ -[IMPORTANT] -==== -If you have an AWS profile stored on your computer, it must not use a temporary -session token that you generated while using a multi-factor authentication -device. The cluster continues to use your current AWS credentials to -create AWS resources for the entire life of the cluster, so you must -use key-based, long-lived credentials. To generate appropriate keys, see -link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] -in the AWS documentation. You can supply the keys when you run the installation -program. -==== -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -.Additional resources - -* See link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html[Configuration and credential file settings] in the AWS documentation for more information about AWS profile and credential configuration. - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console. - -== Next steps - -* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation]. -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_aws/installing-aws-government-region.adoc b/installing/installing_aws/installing-aws-government-region.adoc deleted file mode 100644 index 6596b7009ff6..000000000000 --- a/installing/installing_aws/installing-aws-government-region.adoc +++ /dev/null @@ -1,80 +0,0 @@ -[id="installing-aws-government-region"] -= Installing a cluster on AWS into a government or secret region -include::modules/common-attributes.adoc[] -:context: installing-aws-government-region - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -Amazon Web Services (AWS) into a government or secret region. To configure the -region, modify parameters in the `install-config.yaml` file before you -install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Configure an AWS account] -to host the cluster. -+ -[IMPORTANT] -==== -If you have an AWS profile stored on your computer, it must not use a temporary -session token that you generated while using a multi-factor authentication -device. The cluster continues to use your current AWS credentials to create -AWS resources for the entire life of the cluster, so you must use long-lived -credentials. To generate appropriate keys, see -link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] -in the AWS documentation. You can supply the keys when you run the installation -program. -==== -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/installation-aws-about-government-region.adoc[leveloffset=+1] - -include::modules/private-clusters-default.adoc[leveloffset=+1] -include::modules/private-clusters-about-aws.adoc[leveloffset=+2] - -include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service. - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] -include::modules/installation-aws-config-yaml.adoc[leveloffset=+2] -include::modules/installation-aws-regions-with-no-ami.adoc[leveloffset=+2] -include::modules/installation-aws-upload-custom-rhcos-ami.adoc[leveloffset=+2] -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console. - -== Next steps - -* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation]. -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_aws/installing-aws-network-customizations.adoc b/installing/installing_aws/installing-aws-network-customizations.adoc deleted file mode 100644 index 54a3c64ec065..000000000000 --- a/installing/installing_aws/installing-aws-network-customizations.adoc +++ /dev/null @@ -1,101 +0,0 @@ -[id="installing-aws-network-customizations"] -= Installing a cluster on AWS with network customizations -include::modules/common-attributes.adoc[] -:context: installing-aws-network-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -Amazon Web Services (AWS) with customized network configuration options. By -customizing your network configuration, your cluster can coexist with existing -IP address allocations in your environment and integrate with existing MTU and -VXLAN configurations. - -You must set most of the network configuration parameters during installation, -and you can modify only `kubeProxy` configuration parameters in a running -cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Configure an AWS account] -to host the cluster. -+ -[IMPORTANT] -==== -If you have an AWS profile stored on your computer, it must not use a temporary -session token that you generated while using a multi-factor authentication -device. The cluster continues to use your current AWS credentials to -create AWS resources for the entire life of the cluster, so you must -use key-based, long-lived credentials. To generate appropriate keys, see -link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] -in the AWS documentation. You can supply the keys when you run the installation -program. -==== -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. -// TODO -// Concept that describes networking - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service. - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-aws-config-yaml.adoc[leveloffset=+2] - -// Removing; Proxy not supported for AWS IPI for 4.2 -// include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -// Network Operator specific configuration -include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1] - -[NOTE] -==== -For more information on using a Network Load Balancer (NLB) on AWS, see xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws-network-load-balancer.adoc#configuring-ingress-cluster-traffic-aws-network-load-balancer[Configuring Ingress cluster traffic on AWS using a Network Load Balancer]. -==== - -include::modules/nw-aws-nlb-new-cluster.adoc[leveloffset=+1] - -include::modules/nw-operator-cr.adoc[leveloffset=+1] - -include::modules/configuring-hybrid-ovnkubernetes.adoc[leveloffset=+1] - -[NOTE] -==== -For more information on using Linux and Windows nodes in the same cluster, see xref:../../windows_containers/understanding-windows-container-workloads.adoc#understanding-windows-container-workloads[Understanding Windows container workloads]. -==== - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console. - -== Next steps - -* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation]. -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_aws/installing-aws-private.adoc b/installing/installing_aws/installing-aws-private.adoc deleted file mode 100644 index 9fd6a24c1140..000000000000 --- a/installing/installing_aws/installing-aws-private.adoc +++ /dev/null @@ -1,78 +0,0 @@ -[id="installing-aws-private"] -= Installing a private cluster on AWS -include::modules/common-attributes.adoc[] -:context: installing-aws-private - -toc::[] - -In {product-title} version {product-version}, you can install a private cluster into an existing VPC on Amazon Web Services (AWS). The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify -parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Configure an AWS account] -to host the cluster. -+ -[IMPORTANT] -==== -If you have an AWS profile stored on your computer, it must not use a temporary -session token that you generated while using a multi-factor authentication -device. The cluster continues to use your current AWS credentials to create -AWS resources for the entire life of the cluster, so you must use long-lived -credentials. To generate appropriate keys, see -link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] -in the AWS documentation. You can supply the keys when you run the installation -program. -==== -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/private-clusters-default.adoc[leveloffset=+1] - -include::modules/private-clusters-about-aws.adoc[leveloffset=+2] - -include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service. - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-aws-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console. - -== Next steps - -* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation]. -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_aws/installing-aws-user-infra.adoc b/installing/installing_aws/installing-aws-user-infra.adoc deleted file mode 100644 index 8921dbf0bb8a..000000000000 --- a/installing/installing_aws/installing-aws-user-infra.adoc +++ /dev/null @@ -1,188 +0,0 @@ -[id="installing-aws-user-infra"] -= Installing a cluster on user-provisioned infrastructure in AWS by using CloudFormation templates -include::modules/common-attributes.adoc[] -:context: installing-aws-user-infra - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on Amazon Web Services (AWS) that uses infrastructure that you provide. - -One way to create this infrastructure is to use the provided CloudFormation templates. You can modify the templates to customize your infrastructure or use the information that they contain to create AWS objects according to your company's policies. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the cloud provider and the installation process of {product-title}. Several CloudFormation templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example. -==== - -== Prerequisites - -* You reviewed details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* You xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[configured an AWS account] -to host the cluster. -+ -[IMPORTANT] -==== -If you have an AWS profile stored on your computer, it must not use a temporary session token that you generated while using a multi-factor authentication device. The cluster continues to use your current AWS credentials to create AWS resources for the entire life of the cluster, so you must use key-based, long-lived credentials. To generate appropriate keys, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] in the AWS documentation. You can supply the keys when you run the installation program. -==== -* You downloaded the AWS CLI and installed it on your computer. See -link:https://docs.aws.amazon.com/cli/latest/userguide/install-bundle.html[Install the AWS CLI Using the Bundled Installer (Linux, macOS, or Unix)] -in the AWS documentation. -* If you use a firewall, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== -* If you do not allow the system to manage identity and access management (IAM), then a cluster administrator can xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually create and maintain IAM credentials]. Manual mode can also be used in environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service. - -include::modules/installation-aws-user-infra-requirements.adoc[leveloffset=+1] - -include::modules/installation-aws-permissions.adoc[leveloffset=+2] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-user-infra-generate.adoc[leveloffset=+1] - -include::modules/installation-disk-partitioning-upi-templates.adoc[leveloffset=+2] - -include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2] - -.Additional resources - -* See link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html[Configuration and credential file settings] in the AWS documentation for more information about AWS profile and credential configuration. - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+2] - -include::modules/installation-extracting-infraid.adoc[leveloffset=+1] - -include::modules/installation-creating-aws-vpc.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-vpc.adoc[leveloffset=+2] - -.Additional resources - -* You can view details about the CloudFormation stacks that you create by navigating to the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console]. - -include::modules/installation-creating-aws-dns.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-dns.adoc[leveloffset=+2] - -.Additional resources - -* You can view details about the CloudFormation stacks that you create by navigating to the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console]. - -* You can view details about your hosted zones by navigating to the link:https://console.aws.amazon.com/route53/[AWS Route 53 console]. - -* See link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ListInfoOnHostedZone.html[Listing public hosted zones] in the AWS documentation for more information about listing public hosted zones. - -include::modules/installation-creating-aws-security.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-security.adoc[leveloffset=+2] - -.Additional resources - -* You can view details about the CloudFormation stacks that you create by navigating to the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console]. - -include::modules/installation-aws-user-infra-rhcos-ami.adoc[leveloffset=+1] - -include::modules/installation-aws-regions-with-no-ami.adoc[leveloffset=+2] - -include::modules/installation-aws-upload-custom-rhcos-ami.adoc[leveloffset=+2] - -include::modules/installation-creating-aws-bootstrap.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-bootstrap.adoc[leveloffset=+2] - -.Additional resources - -* You can view details about the CloudFormation stacks that you create by navigating to the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console]. - -* See xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installation-aws-user-infra-rhcos-ami_installing-aws-user-infra[{op-system} AMIs for the AWS infrastructure] for details about the {op-system-first} AMIs for the AWS zones. - -include::modules/installation-creating-aws-control-plane.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-control-plane.adoc[leveloffset=+2] - -.Additional resources - -* You can view details about the CloudFormation stacks that you create by navigating to the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console]. - -include::modules/installation-creating-aws-worker.adoc[leveloffset=+1] - -//// -[id="installing-workers-aws-user-infra"] -== Creating worker nodes - -You can either manually create worker nodes or use a MachineSet to create worker -nodes after the cluster deploys. If you use a MachineSet to create and maintain -the workers, you can allow the cluster to manage them. This allows you to easily -scale, manage, and upgrade your workers. -//// - -include::modules/installation-cloudformation-worker.adoc[leveloffset=+2] - -.Additional resources - -* You can view details about the CloudFormation stacks that you create by navigating to the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console]. - -include::modules/installation-aws-user-infra-bootstrap.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/troubleshooting/troubleshooting-installations.html#monitoring-installation-progress_troubleshooting-installations[Monitoring installation progress] for details about monitoring the installation, bootstrap, and control plane logs as an {product-title} installation progresses. - -* See xref:../../support/troubleshooting/troubleshooting-installations.adoc#gathering-bootstrap-diagnostic-data_troubleshooting-installations[Gathering bootstrap node diagnostic data] for information about troubleshooting issues related to the bootstrap process. - -* You can view details about the running instances that are created by using the link:https://console.aws.amazon.com/ec2[AWS EC2 console]. - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -You can configure registry storage for user-provisioned infrastructure in AWS to deploy {product-title} to hidden regions. See xref:../../registry/configuring_registry_storage/configuring-registry-storage-aws-user-infrastructure.adoc#configuring-registry-storage-aws-user-infrastructure[Configuring the registry for AWS user-provisioned infrastructure] for more information. - -include::modules/registry-configuring-storage-aws-user-infra.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-aws-user-infra-delete-bootstrap.adoc[leveloffset=+1] - -include::modules/installation-create-ingress-dns-records.adoc[leveloffset=+1] - -include::modules/installation-aws-user-infra-installation.adoc[leveloffset=+1] - -include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1] - -[id="installing-aws-user-infra-additional-resources"] -== Additional resources - -* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console. - -* See link:https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacks.html[Working with stacks] in the AWS documentation for more information about AWS CloudFormation stacks. - -[id="installing-aws-user-infra-next-steps"] -== Next steps - -* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation]. -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_aws/installing-aws-vpc.adoc b/installing/installing_aws/installing-aws-vpc.adoc deleted file mode 100644 index 524e106f8135..000000000000 --- a/installing/installing_aws/installing-aws-vpc.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[id="installing-aws-vpc"] -= Installing a cluster on AWS into an existing VPC -include::modules/common-attributes.adoc[] -:context: installing-aws-vpc - -toc::[] - -In {product-title} version {product-version}, you can install a cluster into an existing Amazon Virtual Private Cloud (VPC) on Amazon Web Services (AWS). The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify -parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Configure an AWS account] -to host the cluster. -+ -[IMPORTANT] -==== -If you have an AWS profile stored on your computer, it must not use a temporary -session token that you generated while using a multi-factor authentication -device. The cluster continues to use your current AWS credentials to create -AWS resources for the entire life of the cluster, so you must use long-lived -credentials. To generate appropriate keys, see -link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] -in the AWS documentation. You can supply the keys when you run the installation -program. -==== -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/installation-custom-aws-vpc.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service. - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-aws-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console. - -== Next steps - -* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validating an installation]. -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_aws/installing-restricted-networks-aws.adoc b/installing/installing_aws/installing-restricted-networks-aws.adoc deleted file mode 100644 index 4d46a7aea0c9..000000000000 --- a/installing/installing_aws/installing-restricted-networks-aws.adoc +++ /dev/null @@ -1,177 +0,0 @@ -[id="installing-restricted-networks-aws"] -= Installing a cluster on AWS in a restricted network with user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-aws - -toc::[] - -In {product-title} version {product-version}, you can install a -cluster on Amazon Web Services (AWS) using infrastructure that you provide and -an internal mirror of the installation release content. - -[IMPORTANT] -==== -While you can install an {product-title} cluster by using mirrored installation -release content, your cluster still requires Internet access to use the AWS APIs. -==== - -One way to create this infrastructure is to use the provided -CloudFormation templates. You can modify the templates to customize your -infrastructure or use the information that they contain to create AWS objects -according to your company's policies. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the cloud provider and the installation process of {product-title}. Several CloudFormation templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example. -==== - -== Prerequisites - -* You xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[created a mirror registry on your mirror host] - and obtained the `imageContentSources` data for your version of {product-title}. -+ -[IMPORTANT] -==== -Because the installation media is on the mirror host, you can use that computer -to complete all installation steps. -==== -* You reviewed details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* You xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[configured an AWS account] -to host the cluster. -+ -[IMPORTANT] -==== -If you have an AWS profile stored on your computer, it must not use a temporary session token that you generated while using a multi-factor authentication device. The cluster continues to use your current AWS credentials to create AWS resources for the entire life of the cluster, so you must use key-based, long-lived credentials. To generate appropriate keys, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html[Managing Access Keys for IAM Users] in the AWS documentation. You can supply the keys when you run the installation program. -==== -* You downloaded the AWS CLI and installed it on your computer. See -link:https://docs.aws.amazon.com/cli/latest/userguide/install-bundle.html[Install the AWS CLI Using the Bundled Installer (Linux, macOS, or Unix)] -in the AWS documentation. -* If you use a firewall and plan to use the Telemetry service, you xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configured the firewall to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== -* If you do not allow the system to manage identity and access management (IAM), then a cluster administrator can xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[manually create and maintain IAM credentials]. Manual mode can also be used in environments where the cloud IAM APIs are not reachable. - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] for more information about the Telemetry service - -include::modules/installation-aws-user-infra-requirements.adoc[leveloffset=+1] - -include::modules/installation-aws-permissions.adoc[leveloffset=+2] - -//You extract the installation program from the mirrored content. - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-user-infra-generate.adoc[leveloffset=+1] - -include::modules/installation-disk-partitioning-upi-templates.adoc[leveloffset=+2] - -include::modules/installation-generate-aws-user-infra-install-config.adoc[leveloffset=+2] - -.Additional resources - -* See link:https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html[Configuration and credential file settings] in the AWS documentation for more information about AWS profile and credential configuration. - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+2] - -include::modules/installation-extracting-infraid.adoc[leveloffset=+1] - -include::modules/installation-creating-aws-vpc.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-vpc.adoc[leveloffset=+2] - -include::modules/installation-creating-aws-dns.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-dns.adoc[leveloffset=+2] - -.Additional resources - -* See link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ListInfoOnHostedZone.html[Listing public hosted zones] in the AWS documentation for more information about listing public hosted zones. - -include::modules/installation-creating-aws-security.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-security.adoc[leveloffset=+2] - -include::modules/installation-aws-user-infra-rhcos-ami.adoc[leveloffset=+1] - -include::modules/installation-creating-aws-bootstrap.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-bootstrap.adoc[leveloffset=+2] - -.Additional resources - -* See xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installation-aws-user-infra-rhcos-ami_installing-aws-user-infra[{op-system} AMIs for the AWS infrastructure] for details about the {op-system-first} AMIs for the AWS zones. - -include::modules/installation-creating-aws-control-plane.adoc[leveloffset=+1] - -include::modules/installation-cloudformation-control-plane.adoc[leveloffset=+2] - -include::modules/installation-creating-aws-worker.adoc[leveloffset=+1] - -//// -[id="installing-workers-aws-user-infra"] -== Creating worker nodes - -You can either manually create worker nodes or use a MachineSet to create worker nodes after the cluster deploys. If you use a MachineSet to create and maintain the workers, you can allow the cluster to manage them. This allows you to easily scale, manage, and upgrade your workers. -//// - -include::modules/installation-cloudformation-worker.adoc[leveloffset=+2] - -include::modules/installation-aws-user-infra-bootstrap.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../support/troubleshooting/troubleshooting-installations.html#monitoring-installation-progress_troubleshooting-installations[Monitoring installation progress] for details about monitoring the installation, bootstrap, and control plane logs as an {product-title} installation progresses. - -* See xref:../../support/troubleshooting/troubleshooting-installations.adoc#gathering-bootstrap-diagnostic-data_troubleshooting-installations[Gathering bootstrap node diagnostic data] for information about troubleshooting issues related to the bootstrap process. - -//You can install the CLI on the mirror host. - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-aws-user-infra.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-aws-user-infra-delete-bootstrap.adoc[leveloffset=+1] - -include::modules/installation-create-ingress-dns-records.adoc[leveloffset=+1] - -include::modules/installation-aws-user-infra-installation.adoc[leveloffset=+1] - -include::modules/logging-in-by-using-the-web-console.adoc[leveloffset=+1] - -[id="installing-restricted-networks-aws-additional-resources"] -== Additional resources - -* See xref:../../web_console/web-console.adoc#web-console[Accessing the web console] for more details about accessing and understanding the {product-title} web console. - -* See link:https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacks.html[Working with stacks] in the AWS documentation for more information about AWS CloudFormation stacks. - -[id="installing-restricted-networks-aws-next-steps"] -== Next steps - -* xref:../../installing/validating-an-installation.adoc#validating-an-installation[Validate an installation]. -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If the mirror registry that you used to install your cluster has a trusted CA, add it to the cluster by xref:../../openshift_images/image-configuration.adoc#images-configuration-cas_image-configuration[configuring additional trust stores]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_aws/manually-creating-iam.adoc b/installing/installing_aws/manually-creating-iam.adoc deleted file mode 100644 index b6fea7c7cc6a..000000000000 --- a/installing/installing_aws/manually-creating-iam.adoc +++ /dev/null @@ -1,38 +0,0 @@ -[id="manually-creating-iam-aws"] -= Manually creating IAM for AWS -include::modules/common-attributes.adoc[] -:context: manually-creating-iam-aws - -//TO-DO: this should be one file for AWS, Azure, and GCP with conditions for specifics. - -toc::[] - -In environments where the cloud identity and access management (IAM) APIs are not reachable, or the administrator prefers not to store an administrator-level credential secret in the cluster `kube-system` namespace, you can put the Cloud Credential Operator (CCO) into manual mode before you install the cluster. - -include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[leveloffset=+1] - -.Additional resources - -// Not supported in Azure. Condition out if combining topic for AWS/Azure/GCP. -To learn how to rotate or remove the administrator-level credential secret after installing {product-title}, see xref:../../post_installation_configuration/cluster-tasks.adoc#post-install-rotate-remove-cloud-creds[Rotating or removing cloud provider credentials]. - -For a detailed description of all available CCO credential modes and their supported platforms, see xref:../../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc[About the Cloud Credential Operator]. - -include::modules/manually-create-identity-access-management.adoc[leveloffset=+1] - -include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1] - -include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1] - -include::modules/mint-mode.adoc[leveloffset=+1] - -include::modules/mint-mode-with-removal-of-admin-credential.adoc[leveloffset=+1] - -[id="manually-creating-iam-aws-next-steps"] -== Next steps - -* Install an {product-title} cluster: -** xref:../../installing/installing_aws/installing-aws-default.adoc#installing-aws-default[Installing a cluster quickly on AWS] with default options on installer-provisioned infrastructure -** xref:../../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-customizations[Install a cluster with cloud customizations on installer-provisioned infrastructure] -** xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[Install a cluster with network customizations on installer-provisioned infrastructure] -** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Installing a cluster on user-provisioned infrastructure in AWS by using CloudFormation templates] diff --git a/installing/installing_aws/modules b/installing/installing_aws/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/installing/installing_aws/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/installing/installing_aws/preparing-to-install-on-aws.adoc b/installing/installing_aws/preparing-to-install-on-aws.adoc deleted file mode 100644 index cf8d1ab0ab76..000000000000 --- a/installing/installing_aws/preparing-to-install-on-aws.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[id="preparing-to-install-on-aws"] -= Preparing to install on AWS -include::modules/common-attributes.adoc[] -:context: preparing-to-install-on-aws - -toc::[] - -[id="preparing-to-install-on-aws-prerequisites"] -== Prerequisites - -* You reviewed details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. - -* You read the documentation on xref:../../installing/installing-preparing.adoc#installing-preparing[selecting a cluster installation method and preparing it for users]. - -[id="requirements-for-installing-ocp-on-aws"] -== Requirements for installing {product-title} on AWS - -Before installing {product-title} on Amazon Web Services (AWS), you must create an AWS account. See xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Configuring an AWS account] for details about configuring an account, account limits, account permissions, IAM user setup, and supported AWS regions. - -If the cloud identity and access management (IAM) APIs are not accessible in your environment, or if you do not want to store an administrator-level credential secret in the `kube-system` namespace, see xref:../../installing/installing_aws/manually-creating-iam.adoc#manually-creating-iam-aws[Manually creating IAM for AWS] for other options. - -[id="choosing-an-method-to-install-ocp-on-aws"] -== Choosing a method to install {product-title} on AWS - -You can install {product-title} on AWS by using one of the following deployment methods. - -* **xref:../../installing/installing_aws/installing-aws-default.adoc#installing-aws-default[Installing a cluster quickly on AWS]**: You can install {product-title} on AWS by using the default configuration options. - -* **xref:../../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-customizations[Installing a customized cluster on AWS]**: You can install a customized cluster on AWS infrastructure that the installation program provisions. The installation program allows for some customization to be applied at the installation stage. Many other customization options are available xref:../../post_installation_configuration/cluster-tasks.adoc#post-install-cluster-tasks[post-installation]. - -* **xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[Installing a cluster on AWS with network customizations]**: You can customize your {product-title} network configuration during installation, so that your cluster can coexist with your existing IP address allocations and adhere to your network requirements. - -* **xref:../../installing/installing_aws/installing-aws-vpc.adoc#installing-aws-vpc[Installing a cluster on an existing Virtual Private Cloud]**: You can install {product-title} on an existing AWS Virtual Private Cloud (VPC). You can use this installation method if you have constraints set by the guidelines of your company, such as limits when creating new accounts or infrastructure. - -* **xref:../../installing/installing_aws/installing-aws-private.adoc#installing-aws-private[Installing a private cluster on an existing VPC]**: You can install a private cluster on an existing AWS VPC. You can use this method to deploy {product-title} on an internal network that is not visible to the Internet. - -* **xref:../../installing/installing_aws/installing-aws-government-region.adoc#installing-aws-government-region[Installing a cluster on AWS into a government or secret region]**: {product-title} can be deployed into AWS regions that are specifically designed for US government agencies at the federal, state, and local level, as well as contractors, educational institutions, and other US customers that must run sensitive workloads in the cloud. - -* **xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Installing a cluster on AWS infrastructure that you provide]**: You can install {product-title} on AWS infrastructure that you provide. You can use the provided CloudFormation templates to create stacks of AWS resources that represent each of the components required for an {product-title} installation. - -* **xref:../../installing/installing_aws/installing-restricted-networks-aws.adoc#installing-restricted-networks-aws[Installing a cluster on AWS by using an internal mirror]**: You can install {product-title} on AWS infrastructure that you provide by using an internal mirror of the installation release content. You can use this method to install a cluster that does not require an active Internet connection to obtain the software components. While you can install {product-title} by using the mirrored content, your cluster still requires Internet access to use the AWS APIs. - -[id="preparing-to-install-on-aws-next-steps"] -== Next steps - -* xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Configuring an AWS account] diff --git a/installing/installing_aws/uninstalling-cluster-aws.adoc b/installing/installing_aws/uninstalling-cluster-aws.adoc deleted file mode 100644 index 5e777bc8fbdc..000000000000 --- a/installing/installing_aws/uninstalling-cluster-aws.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="uninstalling-cluster-aws"] -= Uninstalling a cluster on AWS -include::modules/common-attributes.adoc[] -:context: uninstall-cluster-aws - -toc::[] - -You can remove a cluster that you deployed to Amazon Web Services (AWS). - -include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] diff --git a/installing/installing_azure/installing-azure-account.adoc b/installing/installing_azure/installing-azure-account.adoc deleted file mode 100644 index 29f20f5cff57..000000000000 --- a/installing/installing_azure/installing-azure-account.adoc +++ /dev/null @@ -1,38 +0,0 @@ -[id="installing-azure-account"] -= Configuring an Azure account -include::modules/common-attributes.adoc[] -:context: installing-azure-account - -toc::[] - -Before you can install {product-title}, you must configure a Microsoft Azure -account. - -[IMPORTANT] -==== -All Azure resources that are available through public endpoints are subject to -resource name restrictions, and you cannot create resources that use certain -terms. For a list of terms that Azure restricts, see -link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-reserved-resource-name[Resolve reserved resource name errors] -in the Azure documentation. -==== - -include::modules/installation-azure-limits.adoc[leveloffset=+1] - -include::modules/installation-azure-network-config.adoc[leveloffset=+1] - -include::modules/installation-azure-increasing-limits.adoc[leveloffset=+1] - -include::modules/installation-azure-permissions.adoc[leveloffset=+1] - -include::modules/installation-azure-service-principal.adoc[leveloffset=+1] - -include::modules/installation-azure-regions.adoc[leveloffset=+1] - -== Next steps - -* Install an {product-title} cluster on Azure. You can -xref:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[install a customized cluster] -or -xref:../../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[quickly install a cluster] -with default options. diff --git a/installing/installing_azure/installing-azure-customizations.adoc b/installing/installing_azure/installing-azure-customizations.adoc deleted file mode 100644 index cb3caad61928..000000000000 --- a/installing/installing_azure/installing-azure-customizations.adoc +++ /dev/null @@ -1,52 +0,0 @@ -[id="installing-azure-customizations"] -= Installing a cluster on Azure with customizations -include::modules/common-attributes.adoc[] -:context: installing-azure-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a customized -cluster on infrastructure that the installation program provisions on -Microsoft Azure. To customize the installation, you modify -parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-azure-config-yaml.adoc[leveloffset=+2] - -// Removing; Proxy not supported for Azure IPI for 4.2 -// include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_azure/installing-azure-default.adoc b/installing/installing_azure/installing-azure-default.adoc deleted file mode 100644 index 12a189eb88f9..000000000000 --- a/installing/installing_azure/installing-azure-default.adoc +++ /dev/null @@ -1,41 +0,0 @@ -[id="installing-azure-default"] -= Installing a cluster quickly on Azure -include::modules/common-attributes.adoc[] -:context: installing-azure-default - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -Microsoft Azure that uses the default configuration options. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_azure/installing-azure-government-region.adoc b/installing/installing_azure/installing-azure-government-region.adoc deleted file mode 100644 index 2677dca20ab6..000000000000 --- a/installing/installing_azure/installing-azure-government-region.adoc +++ /dev/null @@ -1,61 +0,0 @@ -[id="installing-azure-government-region"] -= Installing a cluster on Azure into a government region -include::modules/common-attributes.adoc[] -:context: installing-azure-government-region - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -Microsoft Azure into a government region. To configure the government region, -you modify parameters in the `install-config.yaml` file before you install the -cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated government region to deploy the cluster to. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/installation-azure-about-government-region.adoc[leveloffset=+1] - -include::modules/private-clusters-default.adoc[leveloffset=+1] - -include::modules/private-clusters-about-azure.adoc[leveloffset=+2] - -include::modules/installation-azure-user-defined-routing.adoc[leveloffset=+2] - -include::modules/installation-about-custom-azure-vnet.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-azure-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_azure/installing-azure-network-customizations.adoc b/installing/installing_azure/installing-azure-network-customizations.adoc deleted file mode 100644 index b4f5f4420868..000000000000 --- a/installing/installing_azure/installing-azure-network-customizations.adoc +++ /dev/null @@ -1,67 +0,0 @@ -[id="installing-azure-network-customizations"] -= Installing a cluster on Azure with network customizations -include::modules/common-attributes.adoc[] -:context: installing-azure-network-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster with a -customized network configuration on infrastructure that the installation program -provisions on Microsoft Azure. By customizing your network configuration, your -cluster can coexist with existing IP address allocations in your environment and -integrate with existing MTU and VXLAN configurations. - -You must set most of the network configuration parameters during installation, -and you can modify only `kubeProxy` configuration parameters in a running -cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-azure-config-yaml.adoc[leveloffset=+2] - -// Removing; Proxy not supported for Azure IPI for 4.2 -// include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -// Network Operator specific configuration -include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1] -include::modules/nw-operator-cr.adoc[leveloffset=+1] -include::modules/configuring-hybrid-ovnkubernetes.adoc[leveloffset=+1] - -[NOTE] -==== -For more information on using Linux and Windows nodes in the same cluster, see xref:../../windows_containers/understanding-windows-container-workloads.adoc#understanding-windows-container-workloads[Understanding Windows container workloads]. -==== - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_azure/installing-azure-private.adoc b/installing/installing_azure/installing-azure-private.adoc deleted file mode 100644 index 9744b397c018..000000000000 --- a/installing/installing_azure/installing-azure-private.adoc +++ /dev/null @@ -1,56 +0,0 @@ -[id="installing-azure-private"] -= Installing a private cluster on Azure -include::modules/common-attributes.adoc[] -:context: installing-azure-private - -toc::[] - -In {product-title} version {product-version}, you can install a private cluster into an existing Azure Virtual Network (VNet) on Microsoft Azure. The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/private-clusters-default.adoc[leveloffset=+1] - -include::modules/private-clusters-about-azure.adoc[leveloffset=+2] - -include::modules/installation-azure-user-defined-routing.adoc[leveloffset=+2] - -include::modules/installation-about-custom-azure-vnet.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-azure-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_azure/installing-azure-user-infra.adoc b/installing/installing_azure/installing-azure-user-infra.adoc deleted file mode 100644 index 9a7012e46c9f..000000000000 --- a/installing/installing_azure/installing-azure-user-infra.adoc +++ /dev/null @@ -1,106 +0,0 @@ -[id="installing-azure-user-infra"] -= Installing a cluster on Azure using ARM templates -include::modules/common-attributes.adoc[] -:context: installing-azure-user-infra - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on Microsoft Azure by using infrastructure that you provide. - -Several link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/overview[Azure Resource Manager] (ARM) templates are provided to assist in completing these steps or to help model your own. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the cloud provider and the installation process of {product-title}. Several ARM templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example. -==== - -== Prerequisites - -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster. -* Download the Azure CLI and install it on your computer. See link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest[Install the Azure CLI] in the Azure documentation. The documentation below was last tested using version `2.2.0` of the Azure CLI. Azure CLI commands might perform differently based on the version you use. -* If you use a firewall and plan to use telemetry, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), then a cluster administrator can xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually create and maintain IAM credentials]. Manual mode can also be used in environments where the cloud IAM APIs are not reachable. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -[id="installation-azure-user-infra-config-project"] -== Configuring your Azure project - -Before you can install {product-title}, you must configure an Azure project to host it. - -[IMPORTANT] -==== -All Azure resources that are available through public endpoints are subject to resource name restrictions, and you cannot create resources that use certain terms. For a list of terms that Azure restricts, see link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-reserved-resource-name[Resolve reserved resource name errors] in the Azure documentation. -==== - -include::modules/installation-azure-limits.adoc[leveloffset=+2] -include::modules/installation-azure-network-config.adoc[leveloffset=+2] - -You can view Azure's DNS solution by visiting this xref:installation-azure-create-dns-zones_{context}[example for creating DNS zones]. - -include::modules/installation-azure-increasing-limits.adoc[leveloffset=+2] - -[id="csr-management-azure_{context}"] -=== Certificate signing requests management - -Because your cluster has limited access to automatic machine management when you use infrastructure that you provision, you must provide a mechanism for approving cluster certificate signing requests (CSRs) after installation. The `kube-controller-manager` only approves the kubelet client CSRs. The `machine-approver` cannot guarantee the validity of a serving certificate that is requested by using kubelet credentials because it cannot confirm that the correct machine issued the request. You must determine and implement a method of verifying the validity of the kubelet serving certificate requests and approving them. - -include::modules/installation-azure-permissions.adoc[leveloffset=+2] -include::modules/installation-azure-service-principal.adoc[leveloffset=+2] -include::modules/installation-azure-regions.adoc[leveloffset=+2] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-user-infra-generate.adoc[leveloffset=+1] -include::modules/installation-disk-partitioning-upi-templates.adoc[leveloffset=+2] -include::modules/installation-initializing.adoc[leveloffset=+2] -include::modules/installation-configure-proxy.adoc[leveloffset=+2] -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] -include::modules/installation-user-infra-exporting-common-variables-arm-templates.adoc[leveloffset=+2] -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+2] - -include::modules/installation-azure-create-resource-group-and-identity.adoc[leveloffset=+1] - -include::modules/installation-azure-user-infra-uploading-rhcos.adoc[leveloffset=+1] - -include::modules/installation-azure-create-dns-zones.adoc[leveloffset=+1] - -You can learn more about xref:installation-azure-network-config_{context}[configuring a public DNS zone in Azure] by visiting that section. - -include::modules/installation-creating-azure-vnet.adoc[leveloffset=+1] -include::modules/installation-arm-vnet.adoc[leveloffset=+2] - -include::modules/installation-azure-user-infra-deploying-rhcos.adoc[leveloffset=+1] -include::modules/installation-arm-image-storage.adoc[leveloffset=+2] - -include::modules/installation-creating-azure-dns.adoc[leveloffset=+1] -include::modules/installation-arm-dns.adoc[leveloffset=+2] - -include::modules/installation-creating-azure-bootstrap.adoc[leveloffset=+1] -include::modules/installation-arm-bootstrap.adoc[leveloffset=+2] - -include::modules/installation-creating-azure-control-plane.adoc[leveloffset=+1] -include::modules/installation-arm-control-plane.adoc[leveloffset=+2] - -include::modules/installation-azure-user-infra-wait-for-bootstrap.adoc[leveloffset=+1] - -include::modules/installation-creating-azure-worker.adoc[leveloffset=+1] -include::modules/installation-arm-worker.adoc[leveloffset=+2] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-azure-create-ingress-dns-records.adoc[leveloffset=+1] - -include::modules/installation-azure-user-infra-completing.adoc[leveloffset=+1] diff --git a/installing/installing_azure/installing-azure-vnet.adoc b/installing/installing_azure/installing-azure-vnet.adoc deleted file mode 100644 index 11c13f87896b..000000000000 --- a/installing/installing_azure/installing-azure-vnet.adoc +++ /dev/null @@ -1,50 +0,0 @@ -[id="installing-azure-vnet"] -= Installing a cluster on Azure into an existing VNet -include::modules/common-attributes.adoc[] -:context: installing-azure-vnet - -toc::[] - -In {product-title} version {product-version}, you can install a cluster into an existing Azure Virtual Network (VNet) on Microsoft Azure. The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_azure/installing-azure-account.adoc#installing-azure-account[Configure an Azure account] to host the cluster and determine the tested and validated region to deploy the cluster to. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_azure/manually-creating-iam-azure.adoc#manually-creating-iam-azure[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/installation-about-custom-azure-vnet.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-azure-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_azure/manually-creating-iam-azure.adoc b/installing/installing_azure/manually-creating-iam-azure.adoc deleted file mode 100644 index 1bc933f20d42..000000000000 --- a/installing/installing_azure/manually-creating-iam-azure.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="manually-creating-iam-azure"] -= Manually creating IAM for Azure -include::modules/common-attributes.adoc[] -:context: manually-creating-iam-azure - -toc::[] - -In environments where the cloud identity and access management (IAM) APIs are not reachable, or the administrator prefers not to store an administrator-level credential secret in the cluster `kube-system` namespace, you can put the Cloud Credential Operator (CCO) into manual mode before you install the cluster. - -include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[leveloffset=+1] - -.Additional resources - -For a detailed description of all available CCO credential modes and their supported platforms, see xref:../../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc[About the Cloud Credential Operator]. - -include::modules/manually-create-identity-access-management.adoc[leveloffset=+1] - -include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1] - -include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1] - -include::modules/mint-mode.adoc[leveloffset=+1] - -[id="manually-creating-iam-azure-next-steps"] -== Next steps - -* Install an {product-title} cluster: -** xref:../../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[Installing a cluster quickly on Azure] with default options on installer-provisioned infrastructure -** xref:../../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[Install a cluster with cloud customizations on installer-provisioned infrastructure] -** xref:../../installing/installing_azure/installing-azure-network-customizations.adoc#installing-azure-network-customizations[Install a cluster with network customizations on installer-provisioned infrastructure] diff --git a/installing/installing_azure/uninstalling-cluster-azure.adoc b/installing/installing_azure/uninstalling-cluster-azure.adoc deleted file mode 100644 index 8c3b3358365f..000000000000 --- a/installing/installing_azure/uninstalling-cluster-azure.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="uninstalling-cluster-azure"] -= Uninstalling a cluster on Azure -include::modules/common-attributes.adoc[] -:context: uninstall-cluster-azure - -toc::[] - -You can remove a cluster that you deployed to Microsoft Azure. - -include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] diff --git a/installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc b/installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc deleted file mode 100644 index 6e90998d15f1..000000000000 --- a/installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc +++ /dev/null @@ -1,126 +0,0 @@ -[id="installing-bare-metal-network-customizations"] -= Installing a cluster on bare metal with network customizations -include::modules/common-attributes.adoc[] -:context: installing-bare-metal-network-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on bare -metal infrastructure that you provision with customized network configuration -options. By customizing your network configuration, your cluster can coexist -with existing IP address allocations in your environment and integrate with -existing MTU and VXLAN configurations. - -You must set most of the network configuration parameters during installation, -and you can modify only `kubeProxy` configuration parameters in a running -cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to access Red Hat Insights]. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -// Network Operator specific configuration - -include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1] -include::modules/nw-operator-cr.adoc[leveloffset=+1] - -include::modules/installation-generate-ignition-configs.adoc[leveloffset=+1] - -[id="creating-machines-bare-metal-network-customization"] -== Creating {op-system-first} machines - -Before you install a cluster on bare metal infrastructure that you provision, -you must create {op-system} machines for it to use. To create the machines, follow either the steps -to use an ISO image or network PXE booting. - -There are several methods of configuring {op-system} during ISO and -PXE installations. These include: - -* Kernel arguments: For a PXE install, you can `APPEND` arguments to the -kernel of the live installer. For an ISO install, you can interrupt the -live installation boot process to add kernel arguments. In both cases, you can use -special `coreos.inst.*` arguments to direct the installer, as well as -standard boot arguments for turning standard kernel services -on or off. - -* Ignition configs: You must generate an {product-title} Ignition config file -(`*.ign`) for the type of node you are installing (worker, control plane, -or bootstrap). You pass the location of the Ignition config to the installed -system so that it takes effect on first boot. In special cases, you can create a -separate, limited Ignition config to pass to the live system. That Ignition config could do a certain set of tasks, such as reporting success to a provisioning system -after completing installation. This special Ignition config is consumed by the installer and should not -be used to include the standard `worker` and `master` Ignition configs. - -* `coreos-installer`: You can boot the live ISO installer to a shell prompt, -which allows you to prepare the permanent system in a variety of ways -before first boot. In particular, you can run the `coreos-installer` -command to identify various artifacts to include, work with disk partitions, -and set up networking. In some cases, you can configure features on -the live system and copy them to the installed system. - -Whether to use an ISO or PXE install depends on your situation. -A PXE install requires an available DHCP service and more preparation, -but can make the installation process more automated. An ISO install -is a more manual process and can be inconvenient if you are setting -up more than a few machines. - -include::modules/installation-user-infra-machines-iso.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+2] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-block-recreate-rollout-bare-metal.adoc[leveloffset=+2] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc#configuring-registry-storage-baremetal[Set up your registry and configure registry storage]. diff --git a/installing/installing_bare_metal/installing-bare-metal.adoc b/installing/installing_bare_metal/installing-bare-metal.adoc deleted file mode 100644 index 194ce1cb011f..000000000000 --- a/installing/installing_bare_metal/installing-bare-metal.adoc +++ /dev/null @@ -1,143 +0,0 @@ -[id="installing-bare-metal"] -= Installing a cluster on bare metal -include::modules/common-attributes.adoc[] -:context: installing-bare-metal - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -bare metal infrastructure that you provision. - -[IMPORTANT] -==== -While you might be able to follow this procedure to deploy a cluster on -virtualized or cloud environments, you must be aware of additional -considerations for non-bare metal platforms. Review the information in the -link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] -before you attempt to install an {product-title} cluster in such an environment. -==== - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-three-node-cluster.adoc[leveloffset=+1] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -[id="creating-machines-bare-metal"] -== Creating {op-system-first} machines - -Before you install a cluster on bare metal infrastructure that you provision, -you must create {op-system} machines for it to use. To create the machines, follow either the steps -to use an ISO image or network PXE booting. - -There are several methods of configuring {op-system} during ISO and -PXE installations. These include: - -* Kernel arguments: For a PXE install, you can `APPEND` arguments to the -kernel of the live installer. For an ISO install, you can interrupt the -live installation boot process to add kernel arguments. In both cases, you can use -special `coreos.inst.*` arguments to direct the live installer, as well as -standard installation boot arguments for turning standard kernel services -on or off. - -* Ignition configs: You must generate an {product-title} Ignition config file -(`*.ign`) for the type of node you are installing (worker, control plane, -or bootstrap). You pass the location of the Ignition config to the installed -system so that it takes effect on first boot. In special cases, you can create a -separate, limited Ignition config to pass to the live system. That Ignition config could do a certain set of tasks, such as reporting success to a provisioning system -after completing installation. This special Ignition config is consumed by the installer and should not -be used to include the standard `worker` and `master` Ignition configs. - -* `coreos-installer`: You can boot the live ISO installer to a shell prompt, -which allows you to prepare the permanent system in a variety of ways -before first boot. In particular, you can run the `coreos-installer` -command to identify various artifacts to include, work with disk partitions, -and set up networking. In some cases, you can configure features on -the live system and copy them to the installed system. - -Whether to use an ISO or PXE install depends on your situation. -A PXE install requires an available DHCP service and more preparation, -but can make the installation process more automated. An ISO install -is a more manual process and can be inconvenient if you are setting -up more than a few machines. - -[NOTE] -==== -As of {product-title} 4.6, the {op-system} ISO and other installation artifacts -provide support for installation on disks with 4K sectors. -==== - - -include::modules/installation-user-infra-machines-iso.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+2] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout-bare-metal.adoc[leveloffset=+3] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc#configuring-registry-storage-baremetal[Set up your registry and configure registry storage]. diff --git a/installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc b/installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc deleted file mode 100644 index bf5754cb3cdb..000000000000 --- a/installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc +++ /dev/null @@ -1,149 +0,0 @@ -[id="installing-restricted-networks-bare-metal"] -= Installing a cluster on bare metal in a restricted network -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-bare-metal - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -bare metal infrastructure that you provision in a restricted network. - -[IMPORTANT] -==== -While you might be able to follow this procedure to deploy a cluster on -virtualized or cloud environments, you must be aware of additional -considerations for non-bare metal platforms. Review the information in the -link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] -before you attempt to install an {product-title} cluster in such an environment. -==== - -== Prerequisites - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a registry on your mirror host] and obtain the `imageContentSources` data for your version of {product-title}. -+ -[IMPORTANT] -==== -Because the installation media is on the mirror host, you can use that computer -to complete all installation steps. -==== -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] -for your cluster. To deploy a private image registry, your storage must provide -ReadWriteMany access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall and plan to use telemetry, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -//You extract the installation program from the mirrored content. - -//You can install the CLI on the mirror host. - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-three-node-cluster.adoc[leveloffset=+1] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -[id="creating-machines-bare-metal-restricted-network"] -== Creating {op-system-first} machines - -Before you install a cluster on bare metal infrastructure that you provision, -you must create {op-system} machines for it to use. To create the machines, follow either the steps -to use an ISO image or network PXE booting. - -There are several methods of configuring {op-system} during ISO and -PXE installations. These include: - -* Kernel arguments: For a PXE install, you can `APPEND` arguments to the -kernel of the live installer. For an ISO install, you can interrupt the -live installation boot process to add kernel arguments. In both cases, you can use -special `coreos.inst.*` arguments to direct the live installer, as well as -standard installation boot arguments for turning standard kernel services -on or off. - -* Ignition configs: You must generate an {product-title} Ignition config file -(`*.ign`) for the type of node you are installing (worker, control plane, -or bootstrap). You pass the location of the Ignition config to the installed -system so that it takes effect on first boot. In special cases, you can create a -separate, limited Ignition config to pass to the live system. That Ignition config could do a certain set of tasks, such as reporting success to a provisioning system -after completing installation. This special Ignition config is consumed by the installer and should not -be used to include the standard `worker` and `master` Ignition configs. - -* `coreos-installer`: You can boot the live ISO installer to a shell prompt, -which allows you to prepare the permanent system in a variety of ways -before first boot. In particular, you can run the `coreos-installer` -command to identify various artifacts to include, work with disk partitions, -and set up networking. In some cases, you can configure features on -the live system and copy them to the installed system. - -Whether to use an ISO or PXE install depends on your situation. -A PXE install requires an available DHCP service and more preparation, -but can make the installation process more automated. An ISO install -is a more manual process and can be inconvenient if you are setting -up more than a few machines. - -include::modules/installation-user-infra-machines-iso.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+2] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-change-management-state.adoc[leveloffset=+3] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout-bare-metal.adoc[leveloffset=+3] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If the mirror registry that you used to install your cluster has a trusted CA, add it to the cluster by xref:../../openshift_images/image-configuration.adoc#images-configuration-cas_image-configuration[configuring additional trust stores]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_bare_metal_ipi/images/71_OpenShift_4.6_Baremetal_IPI_Deployment_1020_1.svg b/installing/installing_bare_metal_ipi/images/71_OpenShift_4.6_Baremetal_IPI_Deployment_1020_1.svg deleted file mode 100644 index 04effb30efd1..000000000000 --- a/installing/installing_bare_metal_ipi/images/71_OpenShift_4.6_Baremetal_IPI_Deployment_1020_1.svg +++ /dev/null @@ -1 +0,0 @@ -Baremetal networkProvisioning network (optional)71_OpenShift_1020Internet accessBootstrap VMProvisioning nodeIngress VIPAPI VIPOut-of-Band Managementnetwork (optional)RouterControl plane nodes x3Worker nodes xNRouterDHCP serverDNS serverProvisioning bridgeeno1Baremetal bridgeeno2 \ No newline at end of file diff --git a/installing/installing_bare_metal_ipi/images/71_OpenShift_4.6_Baremetal_IPI_Deployment_1020_2.svg b/installing/installing_bare_metal_ipi/images/71_OpenShift_4.6_Baremetal_IPI_Deployment_1020_2.svg deleted file mode 100644 index 3f07dcb5af48..000000000000 --- a/installing/installing_bare_metal_ipi/images/71_OpenShift_4.6_Baremetal_IPI_Deployment_1020_2.svg +++ /dev/null @@ -1 +0,0 @@ -Out-of-Band Managementnetwork (optional)RouterControl plane nodes x3Baremetal networkProvisioning network (optional)RouterDHCP serverDNS server71_OpenShift_1020Internet accessProvisioning nodeBootstrap VMWorker nodes xNProvisioning bridgeeno1Baremetal bridgeeno2Ingress VIPAPI VIP \ No newline at end of file diff --git a/installing/installing_bare_metal_ipi/images/flow1.png b/installing/installing_bare_metal_ipi/images/flow1.png deleted file mode 100644 index 0c1201620c33..000000000000 Binary files a/installing/installing_bare_metal_ipi/images/flow1.png and /dev/null differ diff --git a/installing/installing_bare_metal_ipi/images/flow2.png b/installing/installing_bare_metal_ipi/images/flow2.png deleted file mode 100644 index 105d2dbea3c2..000000000000 Binary files a/installing/installing_bare_metal_ipi/images/flow2.png and /dev/null differ diff --git a/installing/installing_bare_metal_ipi/images/flow3.png b/installing/installing_bare_metal_ipi/images/flow3.png deleted file mode 100644 index af0b1c94c442..000000000000 Binary files a/installing/installing_bare_metal_ipi/images/flow3.png and /dev/null differ diff --git a/installing/installing_bare_metal_ipi/images/flow4.png b/installing/installing_bare_metal_ipi/images/flow4.png deleted file mode 100644 index dcf737241600..000000000000 Binary files a/installing/installing_bare_metal_ipi/images/flow4.png and /dev/null differ diff --git a/installing/installing_bare_metal_ipi/ipi-install-configuration-files.adoc b/installing/installing_bare_metal_ipi/ipi-install-configuration-files.adoc deleted file mode 100644 index b09714eab58c..000000000000 --- a/installing/installing_bare_metal_ipi/ipi-install-configuration-files.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="ipi-install-configuration-files"] -= Configuration files -:context: ipi-install-configuration-files -:release: 4.7 - -include::modules/ipi-install-configuring-the-install-config-file.adoc[leveloffset=+1] - -ifeval::[{release} <= 4.3] -include::modules/ipi-install-configuring-the-metal3-config-file.adoc[leveloffset=+1] -endif::[] - -ifeval::[{release} >= 4.4] -include::modules/ipi-install-setting-proxy-settings-within-install-config.adoc[leveloffset=+1] -endif::[] - -ifeval::[{release} >= 4.6] -include::modules/ipi-install-modifying-install-config-for-no-provisioning-network.adoc[leveloffset=+1] -endif::[] - -include::modules/ipi-install-additional-install-config-parameters.adoc[leveloffset=+1] -include::modules/ipi-install-bmc-addressing.adoc[leveloffset=+1] -include::modules/ipi-install-root-device-hints.adoc[leveloffset=+1] -include::modules/ipi-install-creating-the-openshift-manifests.adoc[leveloffset=+1] diff --git a/installing/installing_bare_metal_ipi/ipi-install-expanding-the-cluster.adoc b/installing/installing_bare_metal_ipi/ipi-install-expanding-the-cluster.adoc deleted file mode 100644 index 7a1da80700e2..000000000000 --- a/installing/installing_bare_metal_ipi/ipi-install-expanding-the-cluster.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="ipi-install-expanding-the-cluster"] -= Expanding the cluster -include::modules/common-attributes.adoc[] -:context: ipi-install-expanding -:release: 4.7 - - -After deploying an installer-provisioned {product-title} cluster, you can use the following procedures to expand the number of worker nodes. Ensure that each prospective worker node meets the prerequisites. - -[NOTE] -==== -Expanding the cluster using RedFish Virtual Media involves meeting minimum firmware requirements. See *Firmware requirements for installing with virtual media* in the *Prerequisites* section for additional details when expanding the cluster using RedFish Virtual Media. -==== - -include::modules/ipi-install-preparing-the-bare-metal-node.adoc[leveloffset=+1] - -include::modules/ipi-install-provisioning-the-bare-metal-node.adoc[leveloffset=+1] diff --git a/installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc b/installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc deleted file mode 100644 index 11432223dd39..000000000000 --- a/installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="ipi-install-installation-workflow"] -= Setting up the environment for an OpenShift installation -include::modules/common-attributes.adoc[] -:context: ipi-install-installation-workflow - -toc::[] - -include::modules/ipi-install-installing-rhel-on-the-provisioner-node.adoc[leveloffset=+1] - -include::modules/ipi-install-preparing-the-provisioner-node-for-openshift-install.adoc[leveloffset=+1] - -include::modules/ipi-install-retrieving-the-openshift-installer.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../updating/updating-cluster-between-minor.adoc#understanding-upgrade-channels_updating-cluster-between-minor[{product-title} upgrade channels and releases] for an explanation of the different release channels. - -include::modules/ipi-install-extracting-the-openshift-installer.adoc[leveloffset=+1] - -include::modules/ipi-install-creating-an-rhcos-images-cache.adoc[leveloffset=+1] - -include::installing/installing_bare_metal_ipi/ipi-install-configuration-files.adoc[leveloffset=+1] - -include::modules/ipi-install-creating-a-disconnected-registry.adoc[leveloffset=+1] - -include::modules/ipi-install-deploying-routers-on-worker-nodes.adoc[leveloffset=+1] - -include::modules/ipi-install-validation-checklist-for-installation.adoc[leveloffset=+1] - -include::modules/ipi-install-deploying-the-cluster-via-the-openshift-installer.adoc[leveloffset=+1] - -include::modules/ipi-install-following-the-installation.adoc[leveloffset=+1] diff --git a/installing/installing_bare_metal_ipi/ipi-install-overview.adoc b/installing/installing_bare_metal_ipi/ipi-install-overview.adoc deleted file mode 100644 index a2a0100cd15a..000000000000 --- a/installing/installing_bare_metal_ipi/ipi-install-overview.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="ipi-install-overview"] -= Overview -include::modules/common-attributes.adoc[] -:context: ipi-install - -Installer-provisioned installation provides support for installing {product-title} on bare metal nodes. This guide provides a methodology to achieving a successful installation. - -During installer-provisioned installation on bare metal, the installer on the bare metal node labeled as `provisioner` creates a bootstrap VM. The role of the bootstrap VM is to assist in the process of deploying an {product-title} cluster. The bootstrap VM connects to the `baremetal` network and to the `provisioning` network, if present, via the network bridges. - -image::71_OpenShift_4.6_Baremetal_IPI_Deployment_1020_1.svg[Deployment phase one] - -When the installation of {product-title} control plane nodes is complete and fully operational, the installer destroys the bootstrap VM automatically and moves the virtual IP addresses (VIPs) to the appropriate nodes accordingly. The API VIP moves to the control plane nodes and the Ingress VIP moves to the worker nodes. - -image::71_OpenShift_4.6_Baremetal_IPI_Deployment_1020_2.svg[Deployment phase two] diff --git a/installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc b/installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc deleted file mode 100644 index abc7ce9d59de..000000000000 --- a/installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id="ipi-install-prerequisites"] -= Prerequisites -include::modules/common-attributes.adoc[] -:context: ipi-install-prerequisites -:release: 4.7 - -toc::[] - -Installer-provisioned installation of {product-title} requires: - -. One provisioner node with {op-system-base-full} 8.x installed. -. Three control plane nodes. -. Baseboard Management Controller (BMC) access to each node. -ifeval::[{release} > 4.5] -. At least one network: -.. One *required* routable network -.. One *optional* network for provisioning nodes; and, -.. One *optional* management network. -endif::[] -ifeval::[{release} < 4.6] -. At least two networks: -.. One *required* routable network -.. One *required* network for provisioning nodes; and, -.. One *optional* management network. -endif::[] - -Before starting an installer-provisioned installation of {product-title}, ensure the hardware environment meets the following requirements. - -include::modules/ipi-install-node-requirements.adoc[leveloffset=+1] -ifeval::[{release} >= 4.6] -include::modules/ipi-install-firmware-requirements-for-installing-with-virtual-media.adoc[leveloffset=+1] -endif::[] -include::modules/ipi-install-network-requirements.adoc[leveloffset=+1] -ifdef::upstream[] -ifeval::[{release} >= 4.5] -// Include IPv6 information only in DRAFT documentation -include::modules/ipi-install-ipv6-network-requirements.adoc[leveloffset=+1] -endif::[] -endif::[] -include::modules/ipi-install-configuring-nodes.adoc[leveloffset=+1] -include::modules/ipi-install-out-of-band-management.adoc[leveloffset=+1] -include::modules/ipi-install-required-data-for-installation.adoc[leveloffset=+1] -include::modules/ipi-install-validation-checklist-for-nodes.adoc[leveloffset=+1] diff --git a/installing/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc b/installing/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc deleted file mode 100644 index c2141aa5c48a..000000000000 --- a/installing/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="ipi-install-troubleshooting"] -= Troubleshooting -include::modules/common-attributes.adoc[] -:context: ipi-install-troubleshooting - -toc::[] - - -== Troubleshooting the installer workflow - -Prior to troubleshooting the installation environment, it is critical to understand the overall flow of the installer-provisioned installation on bare metal. The diagrams below provide a troubleshooting flow with a step-by-step breakdown for the environment. - -image:flow1.png[Flow-Diagram-1] - -_Workflow 1 of 4_ illustrates a troubleshooting workflow when the `install-config.yaml` file has errors or the {op-system-first} images are inaccessible. Troubleshooting suggestions can be found at xref:ipi-install-troubleshooting-install-config_{context}[Troubleshooting `install-config.yaml`]. - -image:flow2.png[Flow-Diagram-2] - -_Workflow 2 of 4_ illustrates a troubleshooting workflow for xref:ipi-install-troubleshooting-bootstrap-vm_{context}[ bootstrap VM issues], xref:ipi-install-troubleshooting-bootstrap-vm-cannot-boot_{context}[ bootstrap VMs that cannot boot up the cluster nodes], and xref:ipi-install-troubleshooting-bootstrap-vm-inspecting-logs_{context}[ inspecting logs]. When installing a {product-title} cluster without the `provisioning` network, this workflow does not apply. - -image:flow3.png[Flow-Diagram-3] - -_Workflow 3 of 4_ illustrates a troubleshooting workflow for xref:ipi-install-troubleshooting-cluster-nodes-will-not-pxe_{context}[ cluster nodes that will not PXE boot]. If installing using RedFish Virtual Media, each node must meet minimum firmware requirements for the installer to deploy the node. See *Firmware requirements for installing with virtual media* in the *Prerequisites* section for additional details. - -image:flow4.png[Flow-Diagram-4] - -_Workflow 4 of 4_ illustrates a troubleshooting workflow from -xref:ipi-install-troubleshooting-api-not-accessible_{context}[ a non-accessible API] to a xref:ipi-install-troubleshooting-reviewing-the-installation_{context}[validated installation]. - - -include::modules/ipi-install-troubleshooting-install-config.adoc[leveloffset=+1] -include::modules/ipi-install-troubleshooting-bootstrap-vm.adoc[leveloffset=+1] -include::modules/ipi-install-troubleshooting-bootstrap-vm-cannot-boot.adoc[leveloffset=+2] -include::modules/ipi-install-troubleshooting-bootstrap-vm-inspecting-logs.adoc[leveloffset=+2] -include::modules/ipi-install-troubleshooting-cluster-nodes-will-not-pxe.adoc[leveloffset=+1] -include::modules/ipi-install-troubleshooting-api-not-accessible.adoc[leveloffset=+1] -include::modules/ipi-install-troubleshooting-cleaning-up-previous-installations.adoc[leveloffset=+1] -include::modules/ipi-install-troubleshooting-registry-issues.adoc[leveloffset=+1] -include::modules/ipi-install-troubleshooting-misc-issues.adoc[leveloffset=+1] -include::modules/ipi-install-troubleshooting-failed-ignition-during-firstboot.adoc[leveloffset=+2] -include::modules/ipi-install-troubleshooting-ntp-out-of-sync.adoc[leveloffset=+2] -include::modules/ipi-install-troubleshooting-reviewing-the-installation.adoc[leveloffset=+1] diff --git a/installing/installing_gcp/installing-gcp-account.adoc b/installing/installing_gcp/installing-gcp-account.adoc deleted file mode 100644 index 49cd98734eb7..000000000000 --- a/installing/installing_gcp/installing-gcp-account.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="installing-gcp-account"] -= Configuring a GCP project -include::modules/common-attributes.adoc[] -:context: installing-gcp-account - -toc::[] - -Before you can install {product-title}, you must configure a -Google Cloud Platform (GCP) project to host it. - -include::modules/installation-gcp-project.adoc[leveloffset=+1] - -include::modules/installation-gcp-enabling-api-services.adoc[leveloffset=+1] - -include::modules/installation-gcp-dns.adoc[leveloffset=+1] - -include::modules/installation-gcp-limits.adoc[leveloffset=+1] - -include::modules/installation-gcp-service-account.adoc[leveloffset=+1] - -include::modules/installation-gcp-permissions.adoc[leveloffset=+2] - -include::modules/installation-gcp-regions.adoc[leveloffset=+1] - -== Next steps - -* Install an {product-title} cluster on GCP. You can -xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-customizations[install a customized cluster] -or xref:../../installing/installing_gcp/installing-gcp-default.adoc#installing-gcp-default[quickly install a cluster] -with default options. diff --git a/installing/installing_gcp/installing-gcp-customizations.adoc b/installing/installing_gcp/installing-gcp-customizations.adoc deleted file mode 100644 index 6f3fecd6cc1e..000000000000 --- a/installing/installing_gcp/installing-gcp-customizations.adoc +++ /dev/null @@ -1,57 +0,0 @@ -[id="installing-gcp-customizations"] -= Installing a cluster on GCP with customizations -include::modules/common-attributes.adoc[] -:context: installing-gcp-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a customized -cluster on infrastructure that the installation program provisions on -Google Cloud Platform (GCP). To customize the installation, you modify -parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_gcp/installing-gcp-account.adoc#installing-gcp-account[Configure a GCP account] -to host the cluster. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-gcp-config-yaml.adoc[leveloffset=+2] - -== Additional resources - -* xref:../../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-enabling-customer-managed-encryption_creating-machineset-gcp[Enabling customer-managed encryption keys for a machine set] - -// Removing; Proxy not supported for GCP IPI for 4.2 -// include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_gcp/installing-gcp-default.adoc b/installing/installing_gcp/installing-gcp-default.adoc deleted file mode 100644 index 91a9560f4a7c..000000000000 --- a/installing/installing_gcp/installing-gcp-default.adoc +++ /dev/null @@ -1,43 +0,0 @@ - -[id="installing-gcp-default"] -= Installing a cluster quickly on GCP -include::modules/common-attributes.adoc[] -:context: installing-gcp-default - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -Google Cloud Platform (GCP) that uses the default configuration options. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_gcp/installing-gcp-account.adoc#installing-gcp-account[Configure a GCP account] -to host the cluster. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_gcp/installing-gcp-network-customizations.adoc b/installing/installing_gcp/installing-gcp-network-customizations.adoc deleted file mode 100644 index 9e6aafcc681a..000000000000 --- a/installing/installing_gcp/installing-gcp-network-customizations.adoc +++ /dev/null @@ -1,68 +0,0 @@ -[id="installing-gcp-network-customizations"] -= Installing a cluster on GCP with network customizations -include::modules/common-attributes.adoc[] -:context: installing-gcp-network-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster with a -customized network configuration on infrastructure that the installation program -provisions on Google Cloud Platform (GCP). By customizing your network -configuration, your cluster can coexist with existing IP address allocations in -your environment and integrate with existing MTU and VXLAN configurations. To -customize the installation, you modify parameters in the `install-config.yaml` -file before you install the cluster. - -You must set most of the network configuration parameters during installation, -and you can modify only `kubeProxy` configuration parameters in a running -cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_gcp/installing-gcp-account.adoc#installing-gcp-account[Configure a GCP account] -to host the cluster. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-gcp-config-yaml.adoc[leveloffset=+2] - -== Additional resources - -* xref:../../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-enabling-customer-managed-encryption_creating-machineset-gcp[Enabling customer-managed encryption keys for a machine set] - -// Removing; Proxy not supported for GCP IPI for 4.2 -// include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -// Network Operator specific configuration -include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1] -include::modules/nw-operator-cr.adoc[leveloffset=+1] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_gcp/installing-gcp-private.adoc b/installing/installing_gcp/installing-gcp-private.adoc deleted file mode 100644 index ab7215449c6f..000000000000 --- a/installing/installing_gcp/installing-gcp-private.adoc +++ /dev/null @@ -1,60 +0,0 @@ -[id="installing-gcp-private"] -= Installing a private cluster on GCP -include::modules/common-attributes.adoc[] -:context: installing-gcp-private - -toc::[] - -In {product-title} version {product-version}, you can install a private cluster into an existing VPC on Google Cloud Platform (GCP). The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify -parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_gcp/installing-gcp-account.adoc#installing-gcp-account[Configure a GCP account] -to host the cluster. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/private-clusters-default.adoc[leveloffset=+1] - -include::modules/private-clusters-about-gcp.adoc[leveloffset=+2] - -include::modules/installation-about-custom-gcp-vpc.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-gcp-config-yaml.adoc[leveloffset=+2] - -== Additional resources - -* xref:../../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-enabling-customer-managed-encryption_creating-machineset-gcp[Enabling customer-managed encryption keys for a machine set] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_gcp/installing-gcp-user-infra-vpc.adoc b/installing/installing_gcp/installing-gcp-user-infra-vpc.adoc deleted file mode 100644 index 11b423ca904a..000000000000 --- a/installing/installing_gcp/installing-gcp-user-infra-vpc.adoc +++ /dev/null @@ -1,147 +0,0 @@ -[id="installing-gcp-user-infra-vpc"] -= Installing a cluster with shared VPC on user-provisioned infrastructure in GCP by using Deployment Manager templates -include::modules/common-attributes.adoc[] -:context: installing-gcp-user-infra-vpc - -toc::[] - -In {product-title} version {product-version}, you can install a cluster into a shared Virtual Private Cloud (VPC) on Google Cloud Platform (GCP) that uses infrastructure that you provide. In this context, a cluster installed into a shared VPC is a cluster that is configured to use a VPC from a project different from where the cluster is being deployed. For more information, see Google's documentation on link:https://cloud.google.com/vpc/docs/shared-vpc#shared_vpc_networks[shared VPC networks]. - -The steps for performing a user-provided infrastructure installation into a shared VPC are outlined here. Several -link:https://cloud.google.com/deployment-manager/docs[Deployment Manager] templates are provided to assist in -completing these steps or to help model your own. You are also free to create -the required resources through other methods. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the cloud provider and the installation process of {product-title}. Several Deployment Manager templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example. -==== - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall and plan to use telemetry, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -[id="csr-management-gcp-vpc"] -== Certificate signing requests management - -Because your cluster has limited access to automatic machine management when you -use infrastructure that you provision, you must provide a mechanism for approving -cluster certificate signing requests (CSRs) after installation. The -`kube-controller-manager` only approves the kubelet client CSRs. The -`machine-approver` cannot guarantee the validity of a serving certificate -that is requested by using kubelet credentials because it cannot confirm that -the correct machine issued the request. You must determine and implement a -method of verifying the validity of the kubelet serving certificate requests -and approving them. - -[id="installation-gcp-user-infra-config-project-vpc"] -== Configuring the GCP project that hosts your cluster - -Before you can install {product-title}, you must configure a Google Cloud -Platform (GCP) project to host it. - -include::modules/installation-gcp-project.adoc[leveloffset=+2] -include::modules/installation-gcp-enabling-api-services.adoc[leveloffset=+2] -include::modules/installation-gcp-limits.adoc[leveloffset=+2] -include::modules/installation-gcp-service-account.adoc[leveloffset=+2] -include::modules/installation-gcp-permissions.adoc[leveloffset=+3] -include::modules/installation-gcp-regions.adoc[leveloffset=+2] -include::modules/installation-gcp-install-cli.adoc[leveloffset=+2] - -include::modules/installation-gcp-user-infra-config-host-project-vpc.adoc[leveloffset=+1] -include::modules/installation-gcp-dns.adoc[leveloffset=+2] -include::modules/installation-creating-gcp-vpc.adoc[leveloffset=+2] -include::modules/installation-deployment-manager-vpc.adoc[leveloffset=+3] - -include::modules/installation-user-infra-generate.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+2] - -include::modules/installation-gcp-user-infra-shared-vpc-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+2] -.Additional resources - -[id="installation-gcp-user-infra-exporting-common-variables-vpc"] -== Exporting common variables - -include::modules/installation-extracting-infraid.adoc[leveloffset=+2] -include::modules/installation-user-infra-exporting-common-variables.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-lb.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-ext-lb.adoc[leveloffset=+2] -include::modules/installation-deployment-manager-int-lb.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-private-dns.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-private-dns.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-firewall-rules-vpc.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-firewall-rules.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-iam-shared-vpc.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-iam-shared-vpc.adoc[leveloffset=+2] - -include::modules/installation-gcp-user-infra-rhcos.adoc[leveloffset=+1] - -include::modules/installation-creating-gcp-bootstrap.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-bootstrap.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-control-plane.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-control-plane.adoc[leveloffset=+2] - -include::modules/installation-gcp-user-infra-wait-for-bootstrap.adoc[leveloffset=+1] - -include::modules/installation-creating-gcp-worker.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-worker.adoc[leveloffset=+2] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-gcp-user-infra-adding-ingress.adoc[leveloffset=+1] - -[id="installation-gcp-user-infra-vpc-adding-firewall-rules"] -== Adding ingress firewall rules -The cluster requires several firewall rules. If you do not use a shared VPC, these rules are created by the ingress controller via the GCP cloud provider. When you use a shared VPC, you can either create cluster-wide firewall rules for all services now or create each rule based on events, when the cluster requests access. By creating each rule when the cluster requests access, you know exactly which firewall rules are required. By creating cluster-wide firewall rules, you can apply the same rule set across multiple clusters. - -If you choose to create each rule based on events, you must create firewall rules after you provision the cluster and during the life of the cluster when the console notifies you that rules are missing. Events that are similar to the following event are displayed, and you must add the firewall rules that are required: - -.Example output -[source,terminal] ----- -Firewall change required by security admin: `gcloud compute firewall-rules create k8s-fw-a26e631036a3f46cba28f8df67266d55 --network example-network --description "{\"kubernetes.io/service-name\":\"openshift-ingress/router-default\", \"kubernetes.io/service-ip\":\"35.237.236.234\"}\" --allow tcp:443,tcp:80 --source-ranges 0.0.0.0/0 --target-tags exampl-fqzq7-master,exampl-fqzq7-worker --project example-project` ----- - -If you encounter issues when creating these rule-based events, you can configure the cluster-wide firewall rules while your cluster is running. - -include::modules/installation-creating-gcp-shared-vpc-cluster-wide-firewall-rules.adoc[leveloffset=+2] - -//include::modules/installation-creating-gcp-shared-vpc-ingress-firewall-rules.adoc[leveloffset=+1] - -include::modules/installation-gcp-user-infra-completing.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_gcp/installing-gcp-user-infra.adoc b/installing/installing_gcp/installing-gcp-user-infra.adoc deleted file mode 100644 index 47c8933cce25..000000000000 --- a/installing/installing_gcp/installing-gcp-user-infra.adoc +++ /dev/null @@ -1,106 +0,0 @@ -[id="installing-gcp-user-infra"] -= Installing a cluster on user-provisioned infrastructure in GCP by using Deployment Manager templates -include::modules/common-attributes.adoc[] -:context: installing-gcp-user-infra - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on Google Cloud Platform (GCP) that uses infrastructure that you provide. - -The steps for performing a user-provided infrastructure install are outlined here. Several link:https://cloud.google.com/deployment-manager/docs[Deployment Manager] templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the cloud provider and the installation process of {product-title}. Several Deployment Manager templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example. -==== - -== Prerequisites - -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall and plan to use telemetry, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), then a cluster administrator can xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually create and maintain IAM credentials]. Manual mode can also be used in environments where the cloud IAM APIs are not reachable. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -[id="csr-management-gcp_{context}"] -== Certificate signing requests management - -Because your cluster has limited access to automatic machine management when you use infrastructure that you provision, you must provide a mechanism for approving cluster certificate signing requests (CSRs) after installation. The `kube-controller-manager` only approves the kubelet client CSRs. The `machine-approver` cannot guarantee the validity of a serving certificate that is requested by using kubelet credentials because it cannot confirm that the correct machine issued the request. You must determine and implement a method of verifying the validity of the kubelet serving certificate requests and approving them. - -[id="installation-gcp-user-infra-config-project"] -== Configuring your GCP project - -Before you can install {product-title}, you must configure a Google Cloud Platform (GCP) project to host it. - -include::modules/installation-gcp-project.adoc[leveloffset=+2] -include::modules/installation-gcp-enabling-api-services.adoc[leveloffset=+2] -include::modules/installation-gcp-dns.adoc[leveloffset=+2] -include::modules/installation-gcp-limits.adoc[leveloffset=+2] -include::modules/installation-gcp-service-account.adoc[leveloffset=+2] -include::modules/installation-gcp-permissions.adoc[leveloffset=+3] -include::modules/installation-gcp-regions.adoc[leveloffset=+2] -include::modules/installation-gcp-install-cli.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate.adoc[leveloffset=+1] -include::modules/installation-disk-partitioning-upi-templates.adoc[leveloffset=+2] -include::modules/installation-initializing.adoc[leveloffset=+2] -include::modules/installation-configure-proxy.adoc[leveloffset=+2] -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+2] - -.Additional resources - -* xref:../../installing/installing_gcp/installing-gcp-user-infra.adoc#installation-gcp-user-infra-adding-ingress_installing-gcp-user-infra[Optional: Adding the ingress DNS records] - -[id="installation-gcp-user-infra-exporting-common-variables"] -== Exporting common variables - -include::modules/installation-extracting-infraid.adoc[leveloffset=+2] -include::modules/installation-user-infra-exporting-common-variables.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-vpc.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-vpc.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-lb.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-ext-lb.adoc[leveloffset=+2] -include::modules/installation-deployment-manager-int-lb.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-private-dns.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-private-dns.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-firewall-rules-vpc.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-firewall-rules.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-iam-shared-vpc.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-iam-shared-vpc.adoc[leveloffset=+2] - -include::modules/installation-gcp-user-infra-rhcos.adoc[leveloffset=+1] - -include::modules/installation-creating-gcp-bootstrap.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-bootstrap.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-control-plane.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-control-plane.adoc[leveloffset=+2] - -include::modules/installation-gcp-user-infra-wait-for-bootstrap.adoc[leveloffset=+1] - -include::modules/installation-creating-gcp-worker.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-worker.adoc[leveloffset=+2] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-gcp-user-infra-adding-ingress.adoc[leveloffset=+1] - -include::modules/installation-gcp-user-infra-completing.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_gcp/installing-gcp-vpc.adoc b/installing/installing_gcp/installing-gcp-vpc.adoc deleted file mode 100644 index aa8a587a1d98..000000000000 --- a/installing/installing_gcp/installing-gcp-vpc.adoc +++ /dev/null @@ -1,54 +0,0 @@ -[id="installing-gcp-vpc"] -= Installing a cluster on GCP into an existing VPC -include::modules/common-attributes.adoc[] -:context: installing-gcp-vpc - -toc::[] - -In {product-title} version {product-version}, you can install a cluster into an existing Virtual Private Cloud (VPC) on Google Cloud Platform (GCP). The installation program provisions the rest of the required infrastructure, which you can further customize. To customize the installation, you modify -parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* xref:../../installing/installing_gcp/installing-gcp-account.adoc#installing-gcp-account[Configure a GCP account] -to host the cluster. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* If you do not allow the system to manage identity and access management (IAM), -then a cluster administrator can -xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually -create and maintain IAM credentials]. Manual mode can also be used in -environments where the cloud IAM APIs are not reachable. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-gcp-config-yaml.adoc[leveloffset=+2] - -== Additional resources - -* xref:../../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-enabling-customer-managed-encryption_creating-machineset-gcp[Enabling customer-managed encryption keys for a machine set] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_gcp/installing-restricted-networks-gcp.adoc b/installing/installing_gcp/installing-restricted-networks-gcp.adoc deleted file mode 100644 index 74f7fdfa27f7..000000000000 --- a/installing/installing_gcp/installing-restricted-networks-gcp.adoc +++ /dev/null @@ -1,106 +0,0 @@ -[id="installing-restricted-networks-gcp"] -= Installing a cluster on GCP in a restricted network with user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-gcp - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on Google Cloud Platform (GCP) that uses infrastructure that you provide and an internal mirror of the installation release content. - -[IMPORTANT] -==== -While you can install an {product-title} cluster by using mirrored installation release content, your cluster still requires internet access to use the GCP APIs. -==== - -The steps for performing a user-provided infrastructure install are outlined here. Several link:https://cloud.google.com/deployment-manager/docs[Deployment Manager] templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the cloud provider and the installation process of {product-title}. Several Deployment Manager templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example. -==== - -== Prerequisites - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a mirror registry on your bastion host] and obtain the `imageContentSources` data for your version of {product-title}. -+ -[IMPORTANT] -==== -Because the installation media is on the bastion host, use that computer to complete all installation steps. -==== -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. While you might need to grant access to more sites, you must grant access to `*.googleapis.com` and `accounts.google.com`. -* If you do not allow the system to manage identity and access management (IAM), then a cluster administrator can xref:../../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-creating-iam-gcp[manually create and maintain IAM credentials]. Manual mode can also be used in environments where the cloud IAM APIs are not reachable. - -[id="installation-restricted-networks-gcp-user-infra-config-project"] -== Configuring your GCP project - -Before you can install {product-title}, you must configure a Google Cloud Platform (GCP) project to host it. - -include::modules/installation-gcp-project.adoc[leveloffset=+2] -include::modules/installation-gcp-enabling-api-services.adoc[leveloffset=+2] -include::modules/installation-gcp-dns.adoc[leveloffset=+2] -include::modules/installation-gcp-limits.adoc[leveloffset=+2] -include::modules/installation-gcp-service-account.adoc[leveloffset=+2] -include::modules/installation-gcp-permissions.adoc[leveloffset=+3] -include::modules/installation-gcp-regions.adoc[leveloffset=+2] -include::modules/installation-gcp-install-cli.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate.adoc[leveloffset=+1] -include::modules/installation-disk-partitioning-upi-templates.adoc[leveloffset=+2] -include::modules/installation-initializing.adoc[leveloffset=+2] -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+2] - -.Additional resources - -* xref:../../installing/installing_gcp/installing-gcp-user-infra.adoc#installation-gcp-user-infra-adding-ingress_installing-gcp-user-infra[Optional: Adding the ingress DNS records] - -[id="installation-restricted-networks-gcp-user-infra-exporting-common-variables"] -== Exporting common variables - -include::modules/installation-extracting-infraid.adoc[leveloffset=+2] -include::modules/installation-user-infra-exporting-common-variables.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-vpc.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-vpc.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-lb.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-ext-lb.adoc[leveloffset=+2] -include::modules/installation-deployment-manager-int-lb.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-private-dns.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-private-dns.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-firewall-rules-vpc.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-firewall-rules.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-iam-shared-vpc.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-iam-shared-vpc.adoc[leveloffset=+2] - -include::modules/installation-gcp-user-infra-rhcos.adoc[leveloffset=+1] - -include::modules/installation-creating-gcp-bootstrap.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-bootstrap.adoc[leveloffset=+2] - -include::modules/installation-creating-gcp-control-plane.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-control-plane.adoc[leveloffset=+2] - -include::modules/installation-gcp-user-infra-wait-for-bootstrap.adoc[leveloffset=+1] - -include::modules/installation-creating-gcp-worker.adoc[leveloffset=+1] -include::modules/installation-deployment-manager-worker.adoc[leveloffset=+2] - -//You install the CLI on the bastion host. - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-gcp-user-infra-adding-ingress.adoc[leveloffset=+1] - -include::modules/installation-gcp-user-infra-completing.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If the mirror registry that you used to install your cluster has a trusted CA, add it to the cluster by xref:../../openshift_images/image-configuration.adoc#images-configuration-cas_image-configuration[configuring additional trust stores]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_gcp/manually-creating-iam-gcp.adoc b/installing/installing_gcp/manually-creating-iam-gcp.adoc deleted file mode 100644 index f5f1802573ed..000000000000 --- a/installing/installing_gcp/manually-creating-iam-gcp.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="manually-creating-iam-gcp"] -= Manually creating IAM for GCP -include::modules/common-attributes.adoc[] -:context: manually-creating-iam-gcp - -toc::[] - -In environments where the cloud identity and access management (IAM) APIs are not reachable, or the administrator prefers not to store an administrator-level credential secret in the cluster `kube-system` namespace, you can put the Cloud Credential Operator (CCO) into manual mode before you install the cluster. - -include::modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc[leveloffset=+1] - -.Additional resources - -To learn how to rotate or remove the administrator-level credential secret after installing {product-title}, see xref:../../post_installation_configuration/cluster-tasks.adoc#post-install-rotate-remove-cloud-creds[Rotating or removing cloud provider credentials]. - -For a detailed description of all available CCO credential modes and their supported platforms, see xref:../../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc[About the Cloud Credential Operator]. - -include::modules/manually-create-identity-access-management.adoc[leveloffset=+1] - -include::modules/admin-credentials-root-secret-formats.adoc[leveloffset=+1] - -include::modules/manually-maintained-credentials-upgrade.adoc[leveloffset=+1] - -include::modules/mint-mode.adoc[leveloffset=+1] - -include::modules/mint-mode-with-removal-of-admin-credential.adoc[leveloffset=+1] - -[id="manually-creating-iam-gcp-next-steps"] -== Next steps - -* Install an {product-title} cluster: -** xref:../../installing/installing_gcp/installing-gcp-default.adoc#installing-gcp-default[Installing a cluster quickly on GCP] with default options on installer-provisioned infrastructure -** xref:../../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-customizations[Install a cluster with cloud customizations on installer-provisioned infrastructure] -** xref:../../installing/installing_gcp/installing-gcp-network-customizations.adoc#installing-gcp-network-customizations[Install a cluster with network customizations on installer-provisioned infrastructure] diff --git a/installing/installing_gcp/uninstalling-cluster-gcp.adoc b/installing/installing_gcp/uninstalling-cluster-gcp.adoc deleted file mode 100644 index a678bc58b647..000000000000 --- a/installing/installing_gcp/uninstalling-cluster-gcp.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="uninstalling-cluster-gcp"] -= Uninstalling a cluster on GCP -include::modules/common-attributes.adoc[] -:context: uninstalling-cluster-gcp - -toc::[] - -You can remove a cluster that you deployed to Google Cloud Platform (GCP). - -include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] diff --git a/cicd/builds/images b/installing/installing_helm/images similarity index 100% rename from cicd/builds/images rename to installing/installing_helm/images diff --git a/installing/installing_helm/install-helm-customization.adoc b/installing/installing_helm/install-helm-customization.adoc new file mode 100644 index 000000000000..a10d4c0009d2 --- /dev/null +++ b/installing/installing_helm/install-helm-customization.adoc @@ -0,0 +1,93 @@ +:_mod-docs-content-type: ASSEMBLY +[id="acs-install-helm-customization"] += Installing with customizations using Helm charts +include::modules/common-attributes.adoc[] +:context: acs-install-helm-customization +:topic-helm: + +toc::[] + +High-level installation flow: + +. Add {product-title} Helm chart repository. +. Configure the `central-services` Helm chart. +. Install the `central-services` Helm chart to install the xref:../../architecture/acs-architecture.adoc#centralized-components_acs-architecture[centralized components] (Central and Scanner). +. Generate an init bundle or CRS. +. Configure the `secured-cluster-services` Helm chart. +. Install the `secured-cluster-services` Helm chart to install the xref:../../architecture/acs-architecture.adoc#per-cluster-components_acs-architecture[per-cluster] and xref:../../architecture/acs-architecture.adoc#per-node-components_acs-architecture[per-node] components (Sensor, Admission controller, Collector, and Scanner-slim). + +Before you install: + +* Understand xref:../../architecture/acs-architecture.adoc[{product-title} architecture]. +* Check the xref:../../installing/acs-default-requirements.adoc#acs-default-requirements[default resource requirements page]. + +include::modules/adding-helm-repository.adoc[leveloffset=+1] + +[id="configure-central-services-helm-chart"] +== Configuring the central-services Helm chart + +This section describes Helm chart configuration parameters that you can use with the `helm install` and `helm upgrade` commands. +You can specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Ensure that you store this file securely. +//TODO: Add links to sample configuration files. + +include::modules/central-services-private-config.adoc[leveloffset=+2] + +include::modules/central-services-public-config.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* link:https://www.postgresql.org/docs/15/libpq-connect.html#LIBPQ-CONNSTRING[Connection Strings - PostgreSQL Docs] +* link:https://www.postgresql.org/docs/15/config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE[Parameter Interaction via the Configuration File - PostgreSQL Docs] +* link:https://www.postgresql.org/docs/15/auth-pg-hba-conf.html[The pg_hba.conf File - PostgreSQL Docs] + +include::modules/install-central-services-helm-chart.adoc[leveloffset=+1] + +include::modules/change-config-options-after-deployment-central-service.adoc[leveloffset=+2] + +[id="generate-init-bundle-helm"] +== Generating an init bundle or CRS + +Before you set up a secured cluster, you must create an init bundle or CRS. The secured cluster then uses this bundle or CRS to authenticate with Central. + +You can create an init bundle by using the `roxctl` CLI or from the {product-title-short} portal. You can use the `roxctl` CLI to create a CRS. + +// Generating init bundle +include::modules/roxctl-generate-init-bundle.adoc[leveloffset=+2] +include::modules/crs-generate-roxctl.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../../cli/installing-the-roxctl-cli.adoc#installing-the-roxctl-cli[Installing the `roxctl` CLI] + +// Generating init bundle +include::modules/portal-generate-init-bundle.adoc[leveloffset=+2] + +[id="configure-secured-cluster-services-helm-chart"] +== Configuring the secured-cluster-services Helm chart + +This section describes Helm chart configuration parameters that you can use with the `helm install` and `helm upgrade` commands. +You can specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Ensure that you store this file securely. +//TODO: Add links to sample configuration files. + +[IMPORTANT] +==== +While using the `secured-cluster-services` Helm chart, do not modify the `values.yaml` file that is part of the chart. +==== + +include::modules/secured-cluster-services-config.adoc[leveloffset=+2] + +include::modules/install-secured-cluster-services-helm-chart.adoc[leveloffset=+1] + +include::modules/change-config-options-after-deployment.adoc[leveloffset=+2] + +include::modules/verify-acs-installation.adoc[leveloffset=+1] diff --git a/installing/installing_helm/install-helm-quick.adoc b/installing/installing_helm/install-helm-quick.adoc new file mode 100644 index 000000000000..f73ff2051281 --- /dev/null +++ b/installing/installing_helm/install-helm-quick.adoc @@ -0,0 +1,49 @@ +:_mod-docs-content-type: ASSEMBLY +[id="acs-install-helm-quick"] += Installing quickly using Helm charts +include::modules/common-attributes.adoc[] +:context: acs-install-helm-quick +:topic-helm: + +toc::[] + +[role="_abstract"] +{product-title} installs a set of services on your {ocp} cluster. This topic describes the installation procedure for installing {product-title} on your {ocp} cluster without any customizations. + +The following steps represent the high-level installation flow for quickly installing {product-title}: + +. Add the {product-title} Helm chart repository. +. Install the `central-services` Helm chart to install the xref:../../architecture/acs-architecture.adoc#centralized-components_acs-architecture[centralized components] (Central and Scanner). +. Generate an init bundle or CRS. +. Install the `secured-cluster-services` Helm chart to install the xref:../../architecture/acs-architecture.adoc#per-cluster-components_acs-architecture[per-cluster] and xref:../../architecture/acs-architecture.adoc#per-node-components_acs-architecture[per-node] components (Sensor, Admission controller, Collector, and Scanner-slim). + +Before you install: + +* Understand xref:../../architecture/acs-architecture.adoc#acs-architecture_acs-architecture[{product-title} architecture]. +* Check the xref:../../installing/acs-default-requirements.adoc#acs-default-requirements[default resource requirements page]. + +include::modules/adding-helm-repository.adoc[leveloffset=+1] + +include::modules/acs-quick-install-using-helm.adoc[leveloffset=+1] + +[id="generate-init-bundle-helm-quick"] +== Generating an init bundle or CRS + +Before you set up a secured cluster, you must create an init bundle or CRS. The secured cluster then uses this bundle or CRS to authenticate with Central. + +// Generating init bundle +include::modules/roxctl-generate-init-bundle.adoc[leveloffset=+2] +include::modules/crs-generate-roxctl.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../../cli/installing-the-roxctl-cli.adoc#installing-the-roxctl-cli[Installing the `roxctl` CLI] +* xref:../../installing/installing_helm/install-helm-customization.adoc#portal-generate-init-bundle_acs-install-helm-customization[Generating an init bundle by using the {product-title-short} portal] + +include::modules/acs-quick-install-secured-cluster-using-helm.adoc[leveloffset=+1] + +include::modules/verify-acs-installation-ocp.adoc[leveloffset=+1] + +[role="_additional-resources"] +== Additional resources +* xref:../../installing/installing_helm/install-helm-customization.adoc#acs-install-helm-customization[Installing with customizations using Helm charts] diff --git a/cicd/pipelines/modules b/installing/installing_helm/modules similarity index 100% rename from cicd/pipelines/modules rename to installing/installing_helm/modules diff --git a/installing/installing_helm/snippets b/installing/installing_helm/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/installing/installing_helm/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/installing/installing_ibm_power/installing-ibm-power.adoc b/installing/installing_ibm_power/installing-ibm-power.adoc deleted file mode 100644 index 68d26e17c01a..000000000000 --- a/installing/installing_ibm_power/installing-ibm-power.adoc +++ /dev/null @@ -1,96 +0,0 @@ -[id="installing-ibm-power"] -= Installing a cluster on IBM Power Systems -include::modules/common-attributes.adoc[] -:context: installing-ibm-power - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -IBM Power Systems infrastructure that you provision. - -[IMPORTANT] -==== -Additional considerations exist for non-bare metal platforms. Review the information in the -link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] before you install an {product-title} cluster. -==== - -.Prerequisites - -* Before you begin the installation process, you must clean the installation directory. This ensures that the required installation files are created and updated during the installation process. -* Provision -xref:../../storage/persistent_storage/persistent-storage-nfs.adoc#persistent-storage-nfs[persistent storage using NFS] -for your cluster. To deploy a private image registry, your storage must provide -`ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -[id="creating-machines-bare-metal-power"] -== Creating {op-system-first} machines - -Before you install a cluster on IBM Power Systems infrastructure that you provision, -you must create {op-system} machines for it to use. Follow either the steps -to use an ISO image or network PXE booting to create the machines. - -include::modules/installation-user-infra-machines-iso.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3] - -include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -.Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc b/installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc deleted file mode 100644 index 2629bc8025e6..000000000000 --- a/installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc +++ /dev/null @@ -1,105 +0,0 @@ -[id="installing-restricted-networks-ibm-power"] -= Installing a cluster on IBM Power Systems in a restricted network -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-ibm-power - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -IBM Power Systems infrastructure that you provision in a restricted network. - -[IMPORTANT] -==== -Additional considerations exist for non-bare metal platforms. Review the information in the -link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] before you install an {product-title} cluster. -==== - -.Prerequisites - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a mirror registry for installation in a restricted network] and obtain the `imageContentSources` data for your version of {product-title}. -* Before you begin the installation process, you must move or remove any existing installation files. This ensures that the required installation files are created and updated during the installation process. -+ -[IMPORTANT] -==== -Ensure that installation steps are performed on a machine with access to the installation media. -==== -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] -for your cluster. To deploy a private image registry, your storage must provide -`ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall and plan to use telemetry, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -//You extract the installation program from the mirrored content. - -//You install the CLI on the bastion host. - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -[id="creating-machines-ibm-power-restricted-network"] -== Creating {op-system-first} machines - -Before you install a cluster on IBM Power Systems infrastructure that you provision, -you must create {op-system} machines for it to use. Follow either the steps -to use an ISO image or network PXE booting to create the machines. - -include::modules/installation-user-infra-machines-iso.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3] - -include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-change-management-state.adoc[leveloffset=+3] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -.Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If the mirror registry that you used to install your cluster has a trusted CA, add it to the cluster by xref:../../openshift_images/image-configuration.adoc#images-configuration-cas_image-configuration[configuring additional trust stores]. diff --git a/installing/installing_ibm_z/installing-ibm-z-kvm.adoc b/installing/installing_ibm_z/installing-ibm-z-kvm.adoc deleted file mode 100644 index 695014d437e0..000000000000 --- a/installing/installing_ibm_z/installing-ibm-z-kvm.adoc +++ /dev/null @@ -1,99 +0,0 @@ -[id="installing-ibm-z-kvm"] -= Installing a cluster with {op-system-base} KVM on IBM Z and LinuxONE -include::modules/common-attributes.adoc[] -:context: installing-ibm-z-kvm - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -IBM Z or LinuxONE infrastructure that you provision. - -[NOTE] -==== -While this document refers only to IBM Z, all information in it also applies to LinuxONE. -==== - -[IMPORTANT] -==== -Additional considerations exist for non-bare metal platforms. Review the information in the -link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] before you install an {product-title} cluster. -==== - -== Prerequisites - -* Before you begin the installation process, you must clean the installation directory. This ensures that the required installation files are created and updated during the installation process. - -* Provision -xref:../../storage/persistent_storage/persistent-storage-nfs.adoc#persistent-storage-nfs[persistent storage using NFS] -for your cluster. To deploy a private image registry, your storage must provide -ReadWriteMany access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -* {op-system-base} Kernel Virtual Machine (KVM) system that is hosted on the logical partition (LPAR) and based on {op-system-base} 8.3 or higher -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra-ibm-z-kvm.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+1] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -include::modules/installation-ibm-z-kvm-user-infra-machines-iso.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -include::modules/installation-ibm-z-troubleshooting-and-debugging.adoc[leveloffset=+1] - -.Additional resources - -* See also link:https://access.redhat.com/solutions/4387261[How to generate SOSREPORT within OpenShift4 nodes without SSH]. - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. - -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_ibm_z/installing-ibm-z.adoc b/installing/installing_ibm_z/installing-ibm-z.adoc deleted file mode 100644 index 24329ae24a5a..000000000000 --- a/installing/installing_ibm_z/installing-ibm-z.adoc +++ /dev/null @@ -1,104 +0,0 @@ -[id="installing-ibm-z"] -= Installing a cluster with z/VM on IBM Z and LinuxONE -include::modules/common-attributes.adoc[] -:context: installing-ibm-z - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -IBM Z or LinuxONE infrastructure that you provision. - -[NOTE] -==== -While this document refers only to IBM Z, all information in it also applies to LinuxONE. -==== - -[IMPORTANT] -==== -Additional considerations exist for non-bare metal platforms. Review the information in the -link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] before you install an {product-title} cluster. -==== - -== Prerequisites - -* Before you begin the installation process, you must clean the installation directory. This ensures that the required installation files are created and updated during the installation process. - -* Provision -xref:../../storage/persistent_storage/persistent-storage-nfs.adoc#persistent-storage-nfs[persistent storage using NFS] -for your cluster. To deploy a private image registry, your storage must provide -`ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. - -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -.Additional resources - -* See link:https://www.ibm.com/support/knowledgecenter/en/SSB27U_7.1.0/com.ibm.zvm.v710.hcpa6/bhslzvs.htm[Bridging a HiperSockets LAN with a z/VM Virtual Switch] in the IBM Knowledge Center. - -* See link:http://public.dhe.ibm.com/software/dw/linux390/perf/zvm_hpav00.pdf[Scaling HyperPAV alias devices on Linux guests on z/VM] for performance optimization. - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+1] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -include::modules/installation-ibm-z-user-infra-machines-iso.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -include::modules/installation-ibm-z-troubleshooting-and-debugging.adoc[leveloffset=+1] - -.Additional resources - -* See also link:https://access.redhat.com/solutions/4387261[How to generate SOSREPORT within OpenShift4 nodes without SSH]. - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. - -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc b/installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc deleted file mode 100644 index d82c1b547c37..000000000000 --- a/installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc +++ /dev/null @@ -1,106 +0,0 @@ -[id="installing-restricted-networks-ibm-z"] -= Installing a cluster with z/VM on IBM Z and LinuxONE in a restricted network -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-ibm-z - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -IBM Z and LinuxONE infrastructure that you provision in a restricted network. - -[NOTE] -==== -While this document refers to only IBM Z, all information in it also applies to LinuxONE. -==== - -[IMPORTANT] -==== -Additional considerations exist for non-bare metal platforms. Review the information in the -link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] before you install an {product-title} cluster. -==== - -.Prerequisites - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a mirror registry for installation in a restricted network] and obtain the `imageContentSources` data for your version of {product-title}. -* Before you begin the installation process, you must move or remove any existing installation files. This ensures that the required installation files are created and updated during the installation process. -+ -[IMPORTANT] -==== -Ensure that installation steps are done from a machine with access to the installation media. -==== -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] -using NFS for your cluster. To deploy a private image registry, your storage -must provide `ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall and plan to use telemetry, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -.Additional resources - -* See link:https://www.ibm.com/support/knowledgecenter/en/SSB27U_7.1.0/com.ibm.zvm.v710.hcpa6/bhslzvs.htm[Bridging a HiperSockets LAN with a z/VM Virtual Switch] in the IBM Knowledge Center. -* See link:http://public.dhe.ibm.com/software/dw/linux390/perf/zvm_hpav00.pdf[Scaling HyperPAV alias devices on Linux guests on z/VM] for performance optimization. - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -//You extract the installation program from the mirrored content. - -//You install the CLI on the bastion host. - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -include::modules/installation-ibm-z-user-infra-machines-iso.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -include::modules/installation-ibm-z-troubleshooting-and-debugging.adoc[leveloffset=+1] - -.Additional resources - -* See also link:https://access.redhat.com/solutions/4387261[How to generate SOSREPORT within {product-title} version 4 nodes without SSH]. - -.Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If the mirror registry that you used to install your cluster has a trusted CA, add it to the cluster by xref:../../openshift_images/image-configuration.adoc#images-configuration-cas_image-configuration[configuring additional trust stores]. diff --git a/installing/installing_bare_metal/images b/installing/installing_ocp/images similarity index 100% rename from installing/installing_bare_metal/images rename to installing/installing_ocp/images diff --git a/installing/installing_ocp/init-bundle-ocp.adoc b/installing/installing_ocp/init-bundle-ocp.adoc new file mode 100644 index 000000000000..94b6c32f97d1 --- /dev/null +++ b/installing/installing_ocp/init-bundle-ocp.adoc @@ -0,0 +1,54 @@ +:_mod-docs-content-type: ASSEMBLY +[id="init-bundle-ocp"] += Generating and applying an init bundle or cluster registration secret for RHACS on {osp} +include::modules/common-attributes.adoc[] +:context: init-bundle-ocp +:topic-helm: +:topic-operator: + +toc::[] + +[role="_abstract"] + +{product-title-short} uses a special artifact during installation that allows Central to communicate securely with secured clusters that you are adding. Before the 4.7 release, {product-title-short} used _init bundles_ exclusively for initiating the secure communication channel. Beginning with 4.7, {product-title-short} provides an alternative to init bundles called _cluster registration secrets_ (CRSes). + +:FeatureName: Cluster registration secrets +include::snippets/technology-preview.adoc[] + +include::snippets/cluster-registration-secrets.adoc[] + +You can use either an init bundle or a cluster registration secret (CRS) during installation of a secured cluster. However, {product-title-short} does not yet provide a way to create a CRS by using the portal. Therefore, you must create the CRS by using the `roxctl` CLI. + +Before you set up a secured cluster, you must create an init bundle or CRS. The secured cluster then uses this bundle or CRS to authenticate with Central. You can create an init bundle by using either the {product-title-short} portal or the `roxctl` CLI. If you are using a CRS, you must use the `roxctl` CLI to create it. + +You can then apply the init bundle or the CRS by using the {ocp} web console or by using the `oc` or `kubectl` CLI. If you install {product-title-short} by using Helm, you provide the init bundle or CRS when you run the `helm install` command. + +[NOTE] +==== +You must have the `Admin` user role to create an init bundle or CRS. +==== + +[id="generate-init-bundle"] +== Generating an init bundle + +include::modules/portal-generate-init-bundle.adoc[leveloffset=+2] +include::modules/roxctl-generate-init-bundle.adoc[leveloffset=+2] +include::modules/create-resource-init-bundle.adoc[leveloffset=+1] + +[id="generate-crs"] +== Generating a cluster registration secret (CRS) + +include::modules/crs-generate-roxctl.adoc[leveloffset=+2] +include::modules/crs-apply-secured-cluster.adoc[leveloffset=+1] + +[id="next-steps_init-bundle-ocp"] +== Next steps + +* Install {product-title-short} secured cluster services in all clusters that you want to monitor. + +[role="_additional-resources"] +[id="additional-resources_init-bundle-ocp"] +== Additional resources + +* xref:../../installing/installing_ocp/install-secured-cluster-ocp.adoc#installing-sc-helm[Installing {product-title-short} on secured clusters by using Helm charts] + diff --git a/installing/installing_ocp/install-central-config-options-ocp.adoc b/installing/installing_ocp/install-central-config-options-ocp.adoc new file mode 100644 index 000000000000..ac968af7dfb5 --- /dev/null +++ b/installing/installing_ocp/install-central-config-options-ocp.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-central-config-options-ocp"] += Configuring Central configuration options for RHACS using the Operator +:context: install-central-config-options-ocp +include::modules/common-attributes.adoc[] + +toc::[] + +[role="_abstract"] +When installing the Central instance by using the Operator, you can configure optional settings. + +include::modules/central-configuration-options-operator.adoc[leveloffset=+1] +include::modules/customize-installation-operator-overlays.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* link:https://www.postgresql.org/docs/15/libpq-connect.html#LIBPQ-CONNSTRING[Connection Strings - PostgreSQL Docs] +* link:https://www.postgresql.org/docs/15/config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE[Parameter Interaction via the Configuration File - PostgreSQL Docs] +* link:https://www.postgresql.org/docs/15/auth-pg-hba-conf.html[The pg_hba.conf File - PostgreSQL Docs] diff --git a/installing/installing_ocp/install-central-ocp.adoc b/installing/installing_ocp/install-central-ocp.adoc new file mode 100644 index 000000000000..4afffe069cc8 --- /dev/null +++ b/installing/installing_ocp/install-central-ocp.adoc @@ -0,0 +1,117 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-central-ocp"] += Installing Central services for RHACS on {osp} +include::modules/common-attributes.adoc[] +:context: install-central-ocp + +toc::[] + +[role="_abstract"] + +Central is the resource that contains the {product-title-short} application management interface and services. It handles data persistence, API interactions, and {product-title-short} portal access. You can use the same Central instance to secure multiple {ocp} or Kubernetes clusters. + +You can install Central on your {ocp} or Kubernetes cluster by using one of the following methods: + +* Install using the Operator +* Install using Helm charts +* Install using the `roxctl` CLI (do not use this method unless you have a specific installation need that requires using it) + +// Install using Operator + +[id="install-central-using-operator"] +== Install Central using the Operator + +To install Central by using the Operator, you first install the Operator and then use it to install {product-title-short} on the cluster where you want Central to be installed. + +include::modules/install-acs-operator-annotations.adoc[leveloffset=+2] + +include::modules/install-acs-operator.adoc[leveloffset=+2] + +include::modules/configuring-the-rhacs-operator-for-infrastructure-nodes.adoc[leveloffset=+3] + +include::modules/install-central-operator.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../../installing/acs-default-requirements.adoc#acs-default-requirements[Default resource requirements for {product-title}] +* xref:../../installing/acs-recommended-requirements.adoc#acs-recommended-requirements[Recommended resource requirements for {product-title}] +* xref:../../installing/installing_ocp/install-central-ocp.adoc#central-services-public-configuration-file_install-central-ocp[Public configuration file] + +include::modules/provision-postgresql-database.adoc[leveloffset=+2] +include::modules/install-central-operator-external-db.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../../installing/acs-default-requirements.adoc#default-requirements-central-services_acs-default-requirements[Requirements for using an external database] +* xref:../installing_ocp/install-central-config-options-ocp.adoc#install-central-config-options-ocp[Central configuration options] +* xref:https://www.postgresql.org/docs/15/libpq-connect.html#LIBPQ-CONNSTRING[PostgreSQL Connection String Docs] + +include::modules/verify-central-install-operator.adoc[leveloffset=+2] + + +// Install using Helm + +[id="install-using-helm"] + +[id="install-using-helm-no-customizations-ocp"] +== Install Central using Helm charts + +You can install Central using Helm charts without any customization, using the default values, or by using Helm charts with additional customizations of configuration parameters. + +=== Install Central using Helm charts without customization + +You can install {product-title-short} on your cluster without any customizations. You must add the Helm chart repository and install the `central-services` Helm chart to install the centralized components of Central and Scanner. + +include::modules/adding-helm-repository.adoc[leveloffset=+3] +include::modules/acs-quick-install-using-helm.adoc[leveloffset=+3] +include::modules/automatically-generated-ca.adoc[leveloffset=+3] + +[id="install-using-helm-customizations-ocp"] +=== Install Central using Helm charts with customizations + +You can install {product-title-short} on your {osp} cluster with customizations by using Helm chart configuration parameters with the `helm install` and `helm upgrade` commands. You can specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Ensure that you store this file securely. +* Configuration file `declarative-config-values.yaml`: Create this file if you are using declarative configuration to add the declarative configuration mounts to Central. + +include::modules/central-services-private-config.adoc[leveloffset=+3] + +include::modules/central-services-public-config.adoc[leveloffset=+3] + +include::modules/declarative-configuration-values.adoc[leveloffset=+3] + +include::modules/install-central-services-helm-chart.adoc[leveloffset=+3] + +include::modules/change-config-options-after-deployment-central-service.adoc[leveloffset=+2] + + +// Install using roxctl + +[id="install-using-roxctl-ocp"] +== Install Central using the roxctl CLI + +[WARNING] +==== +For production environments, Red{nbsp}Hat recommends using the Operator or Helm charts to install {product-title-short}. Do not use the `roxctl` install method unless you have a specific installation need that requires using this method. +==== + +[id="installing-roxctl-cli-ocp"] +=== Installing the roxctl CLI + +To install {product-title} you must install the `roxctl` CLI by downloading the binary. +You can install `roxctl` on Linux, Windows, or macOS. + +// Installing the CLI by downloading the binary +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+3] + +include::modules/using-the-interactive-installer.adoc[leveloffset=+2] + +include::modules/install-central-roxctl.adoc[leveloffset=+2] + diff --git a/installing/installing_ocp/install-secured-cluster-config-options-ocp.adoc b/installing/installing_ocp/install-secured-cluster-config-options-ocp.adoc new file mode 100644 index 000000000000..972804331cf6 --- /dev/null +++ b/installing/installing_ocp/install-secured-cluster-config-options-ocp.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-secured-cluster-config-options-ocp"] += Configuring Secured Cluster services options for RHACS using the Operator +:context: install-secured-cluster-config-options-ocp +include::modules/common-attributes.adoc[] + +toc::[] + +[role="_abstract"] +When installing Secured Cluster services by using the Operator, you can configure optional settings. + +include::modules/secured-cluster-configuration-options-operator.adoc[leveloffset=+1] +include::modules/customize-installation-operator-overlays.adoc[leveloffset=+1] \ No newline at end of file diff --git a/installing/installing_ocp/install-secured-cluster-ocp.adoc b/installing/installing_ocp/install-secured-cluster-ocp.adoc new file mode 100644 index 000000000000..1b1cfb8f1c7c --- /dev/null +++ b/installing/installing_ocp/install-secured-cluster-ocp.adoc @@ -0,0 +1,93 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-secured-cluster-ocp"] += Installing Secured Cluster services for RHACS on Red Hat OpenShift +include::modules/common-attributes.adoc[] +:context: install-secured-cluster-ocp + +toc::[] + +[role="_abstract"] + +You can install {product-title-short} on your secured clusters by using one of the following methods: + +* Install by using the Operator +* Install by using Helm charts +* Install by using the `roxctl` CLI (do not use this method unless you have a specific installation need that requires using it) + +[id="installing-sc-operator"] +== Installing {product-title-short} on secured clusters by using the Operator + +To install {product-title-short} by using the Operator, you first install the Operator and then use it to install {product-title-short} on the secured cluster. + +include::modules/install-acs-operator-annotations.adoc[leveloffset=+2] + +include::modules/install-secured-cluster-operator.adoc[leveloffset=+2] + +[id="installing-sc-helm"] +== Installing {product-title-short} on secured clusters by using Helm charts + +You can install {product-title-short} on secured clusters by using Helm charts with no customization, using the default values, or with customizations of configuration parameters. + +[id="installing-sc-helm-default"] +=== Installing {product-title-short} on secured clusters by using Helm charts without customizations + +include::modules/adding-helm-repository.adoc[leveloffset=+3] + +include::modules/acs-quick-install-secured-cluster-using-helm.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources +* xref:../../installing/installing_ocp/init-bundle-ocp.adoc#generate-init-bundle[Generating and applying an init bundle for {product-title-short} on Red{nbsp}Hat OpenShift] + +[id="configure-secured-cluster-services-helm-chart-customizations"] +=== Configuring the secured-cluster-services Helm chart with customizations + +This section describes Helm chart configuration parameters that you can use with the `helm install` and `helm upgrade` commands. +You can specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Ensure that you store this file securely. + +[IMPORTANT] +==== +While using the `secured-cluster-services` Helm chart, do not modify the `values.yaml` file that is part of the chart. +==== + +include::modules/secured-cluster-services-config.adoc[leveloffset=+3] + +include::modules/install-secured-cluster-services-helm-chart.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources +* xref:../../installing/installing_ocp/init-bundle-ocp.adoc#generate-init-bundle[Generating and applying an init bundle for {product-title-short} on Red{nbsp}Hat OpenShift] + +include::modules/change-config-options-after-deployment.adoc[leveloffset=+2] + + +[id="installing-sc-roxctl"] +== Installing {product-title-short} on secured clusters by using the roxctl CLI + +This method is also referred to as the manifest installation method. + +.Prerequisites + +* If you plan to use the `roxctl` CLI command to generate the files used by the sensor installation script, you have installed the `roxctl` CLI. +* You have generated the files that will be used by the sensor installation script. + +.Procedure + +* On the {ocp} secured cluster, deploy the Sensor component by running the sensor installation script. + +[id="installing-roxctl-cli-sc"] +=== Installing the roxctl CLI + +You must first download the binary. You can install `roxctl` on Linux, Windows, or macOS. + +// Installing the CLI by downloading the binary +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+3] + +include::modules/install-sensor-roxctl.adoc[leveloffset=+2] \ No newline at end of file diff --git a/installing/installing_bare_metal_ipi/modules b/installing/installing_ocp/modules similarity index 100% rename from installing/installing_bare_metal_ipi/modules rename to installing/installing_ocp/modules diff --git a/installing/installing_ocp/snippets b/installing/installing_ocp/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/installing/installing_ocp/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/installing/installing_ocp/verify-installation-rhacs-ocp.adoc b/installing/installing_ocp/verify-installation-rhacs-ocp.adoc new file mode 100644 index 000000000000..8a706e24e393 --- /dev/null +++ b/installing/installing_ocp/verify-installation-rhacs-ocp.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: ASSEMBLY +[id="verify-installation-rhacs-ocp"] += Verifying installation of RHACS on Red Hat OpenShift +include::modules/common-attributes.adoc[] +:context: verify-installation-rhacs-ocp + +toc::[] + +[role="_abstract"] +Provides steps to verify that {product-title-short} is properly installed. + +include::modules/verify-acs-installation-ocp.adoc[leveloffset=+1] diff --git a/installing/installing_openstack/installing-openstack-installer-custom.adoc b/installing/installing_openstack/installing-openstack-installer-custom.adoc deleted file mode 100644 index 059c552e04c6..000000000000 --- a/installing/installing_openstack/installing-openstack-installer-custom.adoc +++ /dev/null @@ -1,52 +0,0 @@ -[id="installing-openstack-installer-custom"] -= Installing a cluster on OpenStack with customizations -include::modules/common-attributes.adoc[] -:context: installing-openstack-installer-custom - -toc::[] - -In {product-title} version {product-version}, you can install a customized cluster on -{rh-openstack-first}. To customize the installation, modify parameters in the `install-config.yaml` before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -** Verify that {product-title} {product-version} is compatible with your {rh-openstack} version in the _Available platforms_ section. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix]. - -* Verify that your network configuration does not rely on a provider network. Provider networks are not supported. - -* Have a storage service installed in {rh-openstack}, like block storage (Cinder) or object storage (Swift). Object storage is the recommended storage technology for {product-title} registry cluster deployment. For more information, see xref:../../scalability_and_performance/optimizing-storage.adoc#optimizing-storage[Optimizing storage]. - -* Have metadata service enabled in {rh-openstack} - -include::modules/installation-osp-default-deployment.adoc[leveloffset=+1] -include::modules/installation-osp-control-compute-machines.adoc[leveloffset=+2] -include::modules/installation-osp-bootstrap-machine.adoc[leveloffset=+2] -include::modules/cluster-entitlements.adoc[leveloffset=+1] -include::modules/installation-osp-enabling-swift.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-external-network.adoc[leveloffset=+1] -include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1] -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] -include::modules/installation-initializing.adoc[leveloffset=+1] -include::modules/installation-configure-proxy.adoc[leveloffset=+2] -include::modules/installation-configuration-parameters.adoc[leveloffset=+1] -include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2] -include::modules/installation-osp-deploying-bare-metal-machines.adoc[leveloffset=+2] -include::modules/installation-osp-config-yaml.adoc[leveloffset=+2] -include::modules/ssh-agent-using.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api-floating.adoc[leveloffset=+2] -include::modules/installation-osp-accessing-api-no-floating.adoc[leveloffset=+2] -include::modules/installation-launching-installer.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-cluster-status.adoc[leveloffset=+1] -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* If you need to enable external access to node ports, xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc#nw-using-nodeport_configuring-ingress-cluster-traffic-nodeport[configure ingress cluster traffic by using a node port]. -* If you did not configure {rh-openstack} to accept application traffic over floating IP addresses, xref:../../post_installation_configuration/network-configuration.adoc#installation-osp-configuring-api-floating-ip_post-install-network-configuration[configure {rh-openstack} access with floating IP addresses]. diff --git a/installing/installing_openstack/installing-openstack-installer-kuryr.adoc b/installing/installing_openstack/installing-openstack-installer-kuryr.adoc deleted file mode 100644 index b39626c8ca62..000000000000 --- a/installing/installing_openstack/installing-openstack-installer-kuryr.adoc +++ /dev/null @@ -1,57 +0,0 @@ -[id="installing-openstack-installer-kuryr"] -= Installing a cluster on OpenStack with Kuryr -include::modules/common-attributes.adoc[] -:context: installing-openstack-installer-kuryr - -toc::[] - -In {product-title} version {product-version}, you can install a customized cluster on -{rh-openstack-first} that uses Kuryr SDN. To customize the installation, modify parameters in the `install-config.yaml` before you install the cluster. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -** Verify that {product-title} {product-version} is compatible with your {rh-openstack} version in the _Available platforms_ section. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix]. - -* Verify that your network configuration does not rely on a provider network. Provider networks are not supported. - -* Have a storage service installed in {rh-openstack}, like block storage (Cinder) or object storage (Swift). Object storage is the recommended storage technology for {product-title} registry cluster deployment. For more information, see xref:../../scalability_and_performance/optimizing-storage.adoc#optimizing-storage[Optimizing storage]. - -include::modules/installation-osp-about-kuryr.adoc[leveloffset=+1] -include::modules/installation-osp-default-kuryr-deployment.adoc[leveloffset=+1] -include::modules/installation-osp-kuryr-increase-quota.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-neutron-configuration.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-octavia-configuration.adoc[leveloffset=+2] - -You can xref:../../networking/load-balancing-openstack.adoc#installation-osp-kuryr-octavia-configure[configure your cluster to use the Octavia OVN driver] after your {rh-openstack} cloud is upgraded from version 13 to version 16. - -include::modules/installation-osp-kuryr-known-limitations.adoc[leveloffset=+2] -include::modules/installation-osp-control-compute-machines.adoc[leveloffset=+2] -include::modules/installation-osp-bootstrap-machine.adoc[leveloffset=+2] -include::modules/cluster-entitlements.adoc[leveloffset=+1] -include::modules/installation-osp-enabling-swift.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-external-network.adoc[leveloffset=+1] -include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1] -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] -include::modules/installation-initializing.adoc[leveloffset=+1] -include::modules/installation-configure-proxy.adoc[leveloffset=+2] -include::modules/installation-configuration-parameters.adoc[leveloffset=+1] -include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-config-yaml.adoc[leveloffset=+2] -include::modules/ssh-agent-using.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api-floating.adoc[leveloffset=+2] -include::modules/installation-osp-accessing-api-no-floating.adoc[leveloffset=+2] -include::modules/installation-launching-installer.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-cluster-status.adoc[leveloffset=+1] -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* If you need to enable external access to node ports, xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc#nw-using-nodeport_configuring-ingress-cluster-traffic-nodeport[configure ingress cluster traffic by using a node port]. -* If you did not configure {rh-openstack} to accept application traffic over floating IP addresses, xref:../../post_installation_configuration/network-configuration.adoc#installation-osp-configuring-api-floating-ip_post-install-network-configuration[configure {rh-openstack} access with floating IP addresses]. diff --git a/installing/installing_openstack/installing-openstack-installer-restricted.adoc b/installing/installing_openstack/installing-openstack-installer-restricted.adoc deleted file mode 100644 index 6eb718dd058a..000000000000 --- a/installing/installing_openstack/installing-openstack-installer-restricted.adoc +++ /dev/null @@ -1,56 +0,0 @@ -[id="installing-openstack-installer-restricted"] -= Installing a cluster on OpenStack in a restricted network -include::modules/common-attributes.adoc[] -:context: installing-openstack-installer-restricted - -toc::[] - -In {product-title} {product-version}, you can install a cluster on -{rh-openstack-first} in a restricted network by creating an internal mirror of the installation release content. - -.Prerequisites - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a mirror registry on your bastion host] - and obtain the `imageContentSources` data for your version of {product-title}. -+ -[IMPORTANT] -==== -Because the installation media is on the bastion host, use that computer -to complete all installation steps. -==== - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update processes]. -** Verify that {product-title} {product-version} is compatible with your {rh-openstack} version by consulting the architecture documentation's xref:../../architecture/architecture-installation.adoc#supported-platforms-for-openshift-clusters_architecture-installation[list of available platforms]. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix]. - -* Verify that your network configuration does not rely on a provider network. Provider networks are not supported. - -* Have the metadata service enabled in {rh-openstack}. - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] -include::modules/installation-osp-default-deployment.adoc[leveloffset=+1] -include::modules/installation-osp-control-compute-machines.adoc[leveloffset=+2] -include::modules/installation-osp-bootstrap-machine.adoc[leveloffset=+2] -include::modules/cluster-entitlements.adoc[leveloffset=+1] -include::modules/installation-osp-enabling-swift.adoc[leveloffset=+1] -include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1] -include::modules/installation-creating-image-restricted.adoc[leveloffset=+1] -include::modules/installation-initializing.adoc[leveloffset=+1] -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] -include::modules/installation-osp-restricted-config-yaml.adoc[leveloffset=+2] -include::modules/ssh-agent-using.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api-floating.adoc[leveloffset=+2] -include::modules/installation-osp-accessing-api-no-floating.adoc[leveloffset=+2] -include::modules/installation-launching-installer.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-cluster-status.adoc[leveloffset=+1] -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -.Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If the mirror registry that you used to install your cluster has a trusted CA, add it to the cluster by xref:../../openshift_images/image-configuration.adoc#images-configuration-cas_image-configuration[configuring additional trust stores]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* Learn how to xref:../../operators/admin/olm-restricted-networks.adoc#olm-understanding-operator-catalog-images_olm-restricted-networks[use Operator Lifecycle Manager (OLM) on restricted networks]. -* If you did not configure {rh-openstack} to accept application traffic over floating IP addresses, xref:../../post_installation_configuration/network-configuration.adoc#installation-osp-configuring-api-floating-ip_post-install-network-configuration[configure {rh-openstack} access with floating IP addresses]. diff --git a/installing/installing_openstack/installing-openstack-installer.adoc b/installing/installing_openstack/installing-openstack-installer.adoc deleted file mode 100644 index 83727707d553..000000000000 --- a/installing/installing_openstack/installing-openstack-installer.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id="installing-openstack-installer"] -= Installing a cluster on OpenStack -include::modules/common-attributes.adoc[] -:context: installing-openstack-installer - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -{rh-openstack-first}. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. - -* Verify that your network configuration does not rely on a provider network. Provider networks are not supported. - -* On {rh-openstack}, have access to an external network that does not overlap these CIDR ranges: -** `10.0.0.0/16` -** `172.30.0.0/16` -** `10.128.0.0/14` -+ -If the external network overlaps these ranges, go to xref:./installing-openstack-installer-custom.adoc#installing-openstack-installer-custom[Installing a cluster on OpenStack with customizations] - -include::modules/installation-osp-default-deployment.adoc[leveloffset=+1] -include::modules/cluster-entitlements.adoc[leveloffset=+1] -include::modules/installation-osp-enabling-swift.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-external-network.adoc[leveloffset=+1] -include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1] -include::modules/ssh-agent-using.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api-floating.adoc[leveloffset=+2] -include::modules/installation-osp-accessing-api-no-floating.adoc[leveloffset=+2] -include::modules/installation-launching-installer.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-cluster-status.adoc[leveloffset=+1] -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_openstack/installing-openstack-load-balancing.adoc b/installing/installing_openstack/installing-openstack-load-balancing.adoc deleted file mode 100644 index ecae49e5b993..000000000000 --- a/installing/installing_openstack/installing-openstack-load-balancing.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="installing-openstack-load-balancing"] -= Load balancing deployments on OpenStack -include::modules/common-attributes.adoc[] -:context: installing-openstack-load-balancing - -toc::[] - -include::modules/installation-osp-balancing-external-loads.adoc[leveloffset=+1] diff --git a/installing/installing_openstack/installing-openstack-troubleshooting.adoc b/installing/installing_openstack/installing-openstack-troubleshooting.adoc deleted file mode 100644 index 277d5e695f61..000000000000 --- a/installing/installing_openstack/installing-openstack-troubleshooting.adoc +++ /dev/null @@ -1,52 +0,0 @@ -[id="installing-openstack-troubleshooting"] -= Troubleshooting -include::modules/common-attributes.adoc[] -:context: installing-openstack-troubleshooting - -toc::[] - -//Very much a WIP. Chop up sections into mod docs as they're finalized. - -In the event of a failure in {product-title} on OpenStack installation, you can recover by understanding the likely failure modes and then starting to troubleshoot the problem. - -== View OpenStack instance logs - -== Prerequisites - -* OpenStack CLI tools are installed - -.Procedure - -. In a terminal window, run `openstack console log show ` - -The console logs appear. - -== SSH access to an instance - -== Prerequisites - -* OpenStack CLI tools are installed - -.Procedure - -. Get the IP address of the node on the private network: -+ -[source,terminal] ----- -$ openstack server list | grep master ----- -+ -.Example output -[source,terminal] ----- -| 0dcd756b-ad80-42f1-987a-1451b1ae95ba | cluster-wbzrr-master-1 | ACTIVE | cluster-wbzrr-openshift=172.24.0.21 | rhcos | m1.s2.xlarge | -| 3b455e43-729b-4e64-b3bd-1d4da9996f27 | cluster-wbzrr-master-2 | ACTIVE | cluster-wbzrr-openshift=172.24.0.18 | rhcos | m1.s2.xlarge | -| 775898c3-ecc2-41a4-b98b-a4cd5ae56fd0 | cluster-wbzrr-master-0 | ACTIVE | cluster-wbzrr-openshift=172.24.0.12 | rhcos | m1.s2.xlarge | ----- - -. Connect to the instance from the master that holds the API VIP (and API FIP) as a jumpbox: -+ -[source,terminal] ----- -$ ssh -J core@${FIP} core@ ----- diff --git a/installing/installing_openstack/installing-openstack-user-kuryr.adoc b/installing/installing_openstack/installing-openstack-user-kuryr.adoc deleted file mode 100644 index d9cfb1c413ce..000000000000 --- a/installing/installing_openstack/installing-openstack-user-kuryr.adoc +++ /dev/null @@ -1,72 +0,0 @@ -[id="installing-openstack-user-kuryr"] -= Installing a cluster on OpenStack with Kuryr on your own infrastructure -include::modules/common-attributes.adoc[] -:context: installing-openstack-user-kuryr - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -{rh-openstack-first} that runs on user-provisioned infrastructure. - -Using your own infrastructure allows you to integrate your cluster with existing infrastructure and modifications. The process requires more labor on your part than installer-provisioned installations, because you must create all {rh-openstack} resources, like Nova servers, Neutron ports, and security groups. However, Red Hat provides Ansible playbooks to help you in the deployment process. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -** Verify that {product-title} {product-version} is compatible with your {rh-openstack} version in the _Available platforms_ section. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix]. - -* Verify that your network configuration does not rely on a provider network. Provider networks are not supported. - -* Have an {rh-openstack} account where you want to install {product-title}. - -* On the machine from which you run the installation program, have: -** A single directory in which you can keep the files you create during the installation process -** Python 3 - -include::modules/installation-osp-about-kuryr.adoc[leveloffset=+1] -include::modules/installation-osp-default-kuryr-deployment.adoc[leveloffset=+1] -include::modules/installation-osp-kuryr-increase-quota.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-neutron-configuration.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-octavia-configuration.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-known-limitations.adoc[leveloffset=+2] -include::modules/installation-osp-control-compute-machines.adoc[leveloffset=+2] -include::modules/installation-osp-bootstrap-machine.adoc[leveloffset=+2] -include::modules/cluster-entitlements.adoc[leveloffset=+1] -include::modules/installation-osp-downloading-modules.adoc[leveloffset=+1] -include::modules/installation-osp-downloading-playbooks.adoc[leveloffset=+1] -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] -include::modules/ssh-agent-using.adoc[leveloffset=+1] -// include::modules/installation-osp-enabling-swift.adoc[leveloffset=+1] -include::modules/installation-osp-creating-image.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-external-network.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api-floating.adoc[leveloffset=+2] -include::modules/installation-osp-accessing-api-no-floating.adoc[leveloffset=+2] -include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1] -include::modules/installation-initializing.adoc[leveloffset=+1] -include::modules/installation-configuration-parameters.adoc[leveloffset=+1] -include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-config-yaml.adoc[leveloffset=+2] -include::modules/installation-osp-fixing-subnet.adoc[leveloffset=+2] -include::modules/installation-osp-emptying-worker-pools.adoc[leveloffset=+2] -include::modules/installation-osp-modifying-networktype.adoc[leveloffset=+2] -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] -include::modules/installation-osp-converting-ignition-resources.adoc[leveloffset=+1] -include::modules/installation-osp-creating-control-plane-ignition.adoc[leveloffset=+1] -include::modules/installation-osp-creating-network-resources.adoc[leveloffset=+1] -include::modules/installation-osp-creating-bootstrap-machine.adoc[leveloffset=+1] -include::modules/installation-osp-creating-control-plane.adoc[leveloffset=+1] -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] -include::modules/installation-osp-deleting-bootstrap-resources.adoc[leveloffset=+1] -include::modules/installation-osp-creating-compute-machines.adoc[leveloffset=+1] -include::modules/installation-approve-csrs.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-installation.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* If you need to enable external access to node ports, xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc#nw-using-nodeport_configuring-ingress-cluster-traffic-nodeport[configure ingress cluster traffic by using a node port]. -* If you did not configure {rh-openstack} to accept application traffic over floating IP addresses, xref:../../post_installation_configuration/network-configuration.adoc#installation-osp-configuring-api-floating-ip_post-install-network-configuration[configure {rh-openstack} access with floating IP addresses]. diff --git a/installing/installing_openstack/installing-openstack-user.adoc b/installing/installing_openstack/installing-openstack-user.adoc deleted file mode 100644 index bb1b0dcacfff..000000000000 --- a/installing/installing_openstack/installing-openstack-user.adoc +++ /dev/null @@ -1,70 +0,0 @@ -[id="installing-openstack-user"] -= Installing a cluster on OpenStack on your own infrastructure -include::modules/common-attributes.adoc[] -:context: installing-openstack-user - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -{rh-openstack-first} that runs on user-provisioned infrastructure. - -Using your own infrastructure allows you to integrate your cluster with existing infrastructure and modifications. The process requires more labor on your part than installer-provisioned installations, because you must create all {rh-openstack} resources, like Nova servers, Neutron ports, and security groups. However, Red Hat provides Ansible playbooks to help you in the deployment process. - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -** Verify that {product-title} {product-version} is compatible with your {rh-openstack} version in the _Available platforms_ section. You can also compare platform support across different versions by viewing the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix]. - -* Verify that your network configuration does not rely on a provider network. Provider networks are not supported. - -* Have an {rh-openstack} account where you want to install {product-title}. - -* On the machine from which you run the installation program, have: -** A single directory in which you can keep the files you create during the installation process -** Python 3 - -include::modules/cluster-entitlements.adoc[leveloffset=+1] -include::modules/installation-osp-default-deployment.adoc[leveloffset=+1] -include::modules/installation-osp-control-compute-machines.adoc[leveloffset=+2] -include::modules/installation-osp-bootstrap-machine.adoc[leveloffset=+2] -include::modules/installation-osp-downloading-modules.adoc[leveloffset=+1] -include::modules/installation-osp-downloading-playbooks.adoc[leveloffset=+1] -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] -include::modules/ssh-agent-using.adoc[leveloffset=+1] -// include::modules/installation-osp-enabling-swift.adoc[leveloffset=+1] -include::modules/installation-osp-creating-image.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-external-network.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api.adoc[leveloffset=+1] -include::modules/installation-osp-accessing-api-floating.adoc[leveloffset=+2] -include::modules/installation-osp-accessing-api-no-floating.adoc[leveloffset=+2] -include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1] -include::modules/installation-initializing.adoc[leveloffset=+1] -include::modules/installation-configuration-parameters.adoc[leveloffset=+1] -include::modules/installation-osp-config-yaml.adoc[leveloffset=+2] -include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2] -include::modules/installation-osp-fixing-subnet.adoc[leveloffset=+2] -include::modules/installation-osp-emptying-worker-pools.adoc[leveloffset=+2] -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] -include::modules/installation-osp-converting-ignition-resources.adoc[leveloffset=+1] -include::modules/installation-osp-creating-control-plane-ignition.adoc[leveloffset=+1] -include::modules/installation-osp-creating-network-resources.adoc[leveloffset=+1] - -Optionally, you can use the `inventory.yaml` file that you created to customize your installation. For example, you can deploy a cluster that uses bare metal machines. - -include::modules/installation-osp-deploying-bare-metal-machines.adoc[leveloffset=+2] -include::modules/installation-osp-creating-bootstrap-machine.adoc[leveloffset=+1] -include::modules/installation-osp-creating-control-plane.adoc[leveloffset=+1] -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] -include::modules/installation-osp-deleting-bootstrap-resources.adoc[leveloffset=+1] -include::modules/installation-osp-creating-compute-machines.adoc[leveloffset=+1] -include::modules/installation-approve-csrs.adoc[leveloffset=+1] -include::modules/installation-osp-verifying-installation.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* If you need to enable external access to node ports, xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc#nw-using-nodeport_configuring-ingress-cluster-traffic-nodeport[configure ingress cluster traffic by using a node port]. -* If you did not configure {rh-openstack} to accept application traffic over floating IP addresses, xref:../../post_installation_configuration/network-configuration.adoc#installation-osp-configuring-api-floating-ip_post-install-network-configuration[configure {rh-openstack} access with floating IP addresses]. diff --git a/installing/installing_openstack/uninstalling-cluster-openstack.adoc b/installing/installing_openstack/uninstalling-cluster-openstack.adoc deleted file mode 100644 index 545681a97a23..000000000000 --- a/installing/installing_openstack/uninstalling-cluster-openstack.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="uninstalling-cluster-openstack"] -= Uninstalling a cluster on OpenStack -include::modules/common-attributes.adoc[] -:context: uninstalling-cluster-openstack - -toc::[] - -You can remove a cluster that you deployed to {rh-openstack-first}. - -include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] diff --git a/installing/installing_openstack/uninstalling-openstack-user.adoc b/installing/installing_openstack/uninstalling-openstack-user.adoc deleted file mode 100644 index 27d3deae0062..000000000000 --- a/installing/installing_openstack/uninstalling-openstack-user.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="uninstalling-openstack-user"] -= Uninstalling a cluster on {rh-openstack} from your own infrastructure -include::modules/common-attributes.adoc[] -:context: uninstalling-openstack-user - -toc::[] - -You can remove a cluster that you deployed to {rh-openstack-first} on user-provisioned infrastructure. - -// include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] -include::modules/installation-osp-downloading-modules.adoc[leveloffset=+1] -include::modules/installation-uninstall-infra.adoc[leveloffset=+1] diff --git a/installing/installing_ibm_power/images b/installing/installing_other/images similarity index 100% rename from installing/installing_ibm_power/images rename to installing/installing_other/images diff --git a/installing/installing_other/init-bundle-other.adoc b/installing/installing_other/init-bundle-other.adoc new file mode 100644 index 000000000000..1baee2b7743f --- /dev/null +++ b/installing/installing_other/init-bundle-other.adoc @@ -0,0 +1,54 @@ +:_mod-docs-content-type: ASSEMBLY +[id="init-bundle-other"] += Generating and applying an init bundle or cluster registration secret for RHACS on other platforms +include::modules/common-attributes.adoc[] +:context: init-bundle-other +:topic-helm: + +toc::[] + +[role="_abstract"] + +{product-title-short} uses a special artifact during installation that allows Central to communicate securely with the secured clusters that you are adding. Before the 4.7 release, {product-title-short} used _init bundles_ exclusively for initiating the secure communication channel. Beginning with 4.7, {product-title-short} provides an alternative to init bundles called _cluster registration secrets_ (CRSes). + +:FeatureName: Cluster registration secrets +include::snippets/technology-preview.adoc[] + +include::snippets/cluster-registration-secrets.adoc[] + +Currently, using an init bundle or a cluster registration secret (CRS) during installation is supported. However, {product-title-short} does not yet provide a way to create a CRS by using the portal. Therefore, you must create the CRS by using the `roxctl` CLI. + +You can use CRSes when you are installing {product-title-short} by using the Operator or Helm installation methods. + +Before you set up a secured cluster, you must create an init bundle or CRS. The secured cluster then uses this bundle or CRS to authenticate with Central. You can create an init bundle by using either the {product-title-short} portal or the `roxctl` CLI. If you are using a CRS, you must use the `roxctl` CLI to create it. + +You can then apply the init bundle or the CRS by using the {ocp} web console or by using the `oc` or `kubectl` CLI. If you install {product-title-short} by using Helm, you provide the init bundle or CRS when you run the `helm install` command. + +[NOTE] +==== +You must have the `Admin` user role to create an init bundle. +==== + +[id="generate-init-bundle-other"] +== Generating an init bundle + +include::modules/portal-generate-init-bundle.adoc[leveloffset=+2] +include::modules/roxctl-generate-init-bundle.adoc[leveloffset=+2] +include::modules/create-resource-init-bundle.adoc[leveloffset=+2] + +[id="generate-crs-other"] +== Generating a CRS + +include::modules/crs-generate-roxctl.adoc[leveloffset=+2] +include::modules/crs-apply-secured-cluster.adoc[leveloffset=+2] + +[id="next-steps_init-bundle-other"] +== Next steps + +* Install {product-title-short} secured cluster services in all clusters that you want to monitor. + +[role="_additional-resources"] +== Additional resources + +* xref:../../installing/installing_ocp/install-secured-cluster-ocp.adoc#installing-sc-helm[Installing {product-title-short} on secured clusters by using Helm charts] (ocp) +* xref:../../installing/installing_other/install-secured-cluster-other.adoc#installing-sc-helm-other[Installing {product-title-short} on secured clusters by using Helm charts] (Kubernetes) diff --git a/installing/installing_other/install-central-other.adoc b/installing/installing_other/install-central-other.adoc new file mode 100644 index 000000000000..358569ed7096 --- /dev/null +++ b/installing/installing_other/install-central-other.adoc @@ -0,0 +1,84 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-central-other"] += Installing Central services for RHACS on other platforms +include::modules/common-attributes.adoc[] +:context: install-central-other + +toc::[] + +[role="_abstract"] + +Central is the resource that contains the {product-title-short} application management interface and services. It handles data persistence, API interactions, and {product-title-short} portal access. You can use the same Central instance to secure multiple {ocp} or Kubernetes clusters. + +You can install Central by using one of the following methods: + +* Install using Helm charts +* Install using the `roxctl` CLI (do not use this method unless you have a specific installation need that requires using it) + +// Install using Helm + +[id="install-using-helm-no-customizations-other"] +== Install Central using Helm charts + +You can install Central using Helm charts without any customization, using the default values, or by using Helm charts with additional customizations of configuration parameters. + +=== Install Central using Helm charts without customization + +You can install {product-title-short} on your {osp} cluster without any customizations. You must add the Helm chart repository and install the `central-services` Helm chart to install the centralized components of Central and Scanner. + +include::modules/adding-helm-repository.adoc[leveloffset=+3] +include::modules/acs-quick-install-using-helm.adoc[leveloffset=+3] +include::modules/automatically-generated-ca.adoc[leveloffset=+3] + +[id="install-using-helm-customizations-other"] +=== Install Central using Helm charts with customizations + +You can install {product-title-short} on your {osp} cluster with customizations by using Helm chart configuration parameters with the `helm install` and `helm upgrade` commands. You can specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Ensure that you store this file securely. +* Configuration file `declarative-config-values.yaml`: Create this file if you are using declarative configuration to add the declarative configuration mounts to Central. + +include::modules/central-services-private-config.adoc[leveloffset=+3] + +include::modules/central-services-public-config.adoc[leveloffset=+3] + +include::modules/declarative-configuration-values.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources +* link:https://www.postgresql.org/docs/15/libpq-connect.html#LIBPQ-CONNSTRING[Connection Strings - PostgreSQL Docs] +* link:https://www.postgresql.org/docs/15/config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE[Parameter Interaction via the Configuration File - PostgreSQL Docs] +* link:https://www.postgresql.org/docs/15/auth-pg-hba-conf.html[The pg_hba.conf File - PostgreSQL Docs] + +include::modules/install-central-services-helm-chart.adoc[leveloffset=+3] + +include::modules/change-config-options-after-deployment-central-service.adoc[leveloffset=+2] + +// Install using roxctl + +[id="install-using-roxctl-other"] +== Install Central using the roxctl CLI + +[WARNING] +==== +For production environments, Red{nbsp}Hat recommends using the Operator or Helm charts to install {product-title-short}. Do not use the `roxctl` install method unless you have a specific installation need that requires using this method. +==== + +[id="installing-roxctl-cli-other"] +=== Installing the roxctl CLI + +To install {product-title} you must install the `roxctl` CLI by downloading the binary. +You can install `roxctl` on Linux, Windows, or macOS. + +// Installing the CLI by downloading the binary +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+3] + +include::modules/using-the-interactive-installer.adoc[leveloffset=+2] + +include::modules/install-central-roxctl.adoc[leveloffset=+2] + diff --git a/installing/installing_other/install-rhacs-other.adoc b/installing/installing_other/install-rhacs-other.adoc new file mode 100644 index 000000000000..5367f06cddc1 --- /dev/null +++ b/installing/installing_other/install-rhacs-other.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-rhacs-other"] += High-level overview of installing RHACS on other platforms +include::modules/common-attributes.adoc[] +:context: install-rhacs-other + +toc::[] + +[role="_abstract"] +{product-title} ({product-title-short}) provides security services for self-managed {product-title-short} on platforms such as Amazon Elastic Kubernetes Service (Amazon EKS), Google Kubernetes Engine (Google GKE), and Microsoft Azure Kubernetes Service (Microsoft AKS). + +Before you install: + +* Understand the xref:../../installing/acs-high-level-overview.adoc#install-platforms-methods_acs-high-level-overview[installation methods for different platforms]. +* Understand xref:../../architecture/acs-architecture.adoc#acs-architecture_acs-architecture[{product-title} architecture]. +* Check the xref:../../installing/acs-default-requirements.adoc#acs-default-requirements[default resource requirements page]. + +The following list provides a high-level overview of installation steps: + +. Install xref:../installing_other/install-central-other.adoc#install-central-other[Central services] on a cluster using Helm charts or the `roxctl` CLI. +. Generate and apply an xref:../installing_other/init-bundle-other.adoc#init-bundle-other[init bundle]. +. Install xref:../installing_other/install-secured-cluster-other.adoc#install-secured-cluster-other[secured cluster resources] on each of your secured clusters. diff --git a/installing/installing_other/install-secured-cluster-other.adoc b/installing/installing_other/install-secured-cluster-other.adoc new file mode 100644 index 000000000000..17ffb2612942 --- /dev/null +++ b/installing/installing_other/install-secured-cluster-other.adoc @@ -0,0 +1,78 @@ +:_mod-docs-content-type: ASSEMBLY +[id="install-secured-cluster-other"] += Installing Secured Cluster services for RHACS on other platforms +include::modules/common-attributes.adoc[] +:context: install-secured-cluster-other + +toc::[] + +[role="_abstract"] + +You can install {rh-rhacs-first} on your secured clusters for the following platforms: + +* Amazon Elastic Kubernetes Service (Amazon EKS) +* Google Kubernetes Engine (GKE) +* Microsoft Azure Kubernetes Service (Microsoft AKS) + +[id="installing-sc-helm-other"] +== Installing {product-title-short} on secured clusters by using Helm charts + +You can install {product-title-short} on secured clusters by using Helm charts with no customization, using the default values, or with customizations of configuration parameters. + +[id="installing-sc-helm-default-other"] +=== Installing {product-title-short} on secured clusters by using Helm charts without customizations + +include::modules/adding-helm-repository.adoc[leveloffset=+3] + +include::modules/acs-quick-install-secured-cluster-using-helm.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources +* xref:../../installing/installing_other/init-bundle-other.adoc#generate-init-bundle[Generating and applying an init bundle for {product-title-short} on other platforms] + +[id="configure-secured-cluster-services-helm-chart-customizations-other"] +=== Configuring the secured-cluster-services Helm chart with customizations + +This section describes Helm chart configuration parameters that you can use with the `helm install` and `helm upgrade` commands. +You can specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Ensure that you store this file securely. + +[IMPORTANT] +==== +While using the `secured-cluster-services` Helm chart, do not modify the `values.yaml` file that is part of the chart. +==== + +include::modules/secured-cluster-services-config.adoc[leveloffset=+3] + +include::modules/install-secured-cluster-services-helm-chart.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources +* xref:../../installing/installing_other/init-bundle-other.adoc#generate-init-bundle[Generating and applying an init bundle for {product-title-short} on other platforms] + +include::modules/change-config-options-after-deployment.adoc[leveloffset=+2] + + +[id="installing-sc-roxctl-sc-other"] +== Installing {product-title-short} on secured clusters by using the roxctl CLI + +To install {product-title-short} on secured clusters by using the CLI, perform the following steps: + +. Install the `roxctl` CLI +. Install Sensor. + +[id="installing-roxctl-cli-sc-other"] +=== Installing the roxctl CLI + +You must first download the binary. You can install `roxctl` on Linux, Windows, or macOS. + +// Installing the CLI by downloading the binary +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+3] + +include::modules/install-sensor-roxctl.adoc[leveloffset=+2] \ No newline at end of file diff --git a/cli_reference/developer_cli_odo/modules b/installing/installing_other/modules similarity index 100% rename from cli_reference/developer_cli_odo/modules rename to installing/installing_other/modules diff --git a/installing/installing_other/snippets b/installing/installing_other/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/installing/installing_other/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/installing/installing_other/verify-installation-rhacs-other.adoc b/installing/installing_other/verify-installation-rhacs-other.adoc new file mode 100644 index 000000000000..22a69af1d992 --- /dev/null +++ b/installing/installing_other/verify-installation-rhacs-other.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: ASSEMBLY +[id="verify-installation-rhacs"] += Verifying installation of RHACS on other platforms +include::modules/common-attributes.adoc[] +:context: verify-installation-rhacs + +toc::[] + +[role="_abstract"] +Provides steps to verify that {product-title-short} is properly installed. + +include::modules/verify-acs-installation-kube.adoc[leveloffset=+1] diff --git a/installing/installing_platform_agnostic/installing-platform-agnostic.adoc b/installing/installing_platform_agnostic/installing-platform-agnostic.adoc deleted file mode 100644 index 6b022c3e75f1..000000000000 --- a/installing/installing_platform_agnostic/installing-platform-agnostic.adoc +++ /dev/null @@ -1,137 +0,0 @@ -[id="installing-platform-agnostic"] -= Installing a cluster on any platform -include::modules/common-attributes.adoc[] -:context: installing-platform-agnostic - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -any infrastructure that you provision, including virtualization and cloud environments. - -[IMPORTANT] -==== -Review the information in the link:https://access.redhat.com/articles/4207611[guidelines for deploying {product-title} on non-tested platforms] before you attempt to install an {product-title} cluster in virtualized or cloud environments. -==== - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-three-node-cluster.adoc[leveloffset=+1] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -[id="creating-machines-platform-agnostic"] -== Creating {op-system-first} machines - -Before you install a cluster on infrastructure that you provision, you must create {op-system} machines for it to use. If your infrastructure supports it, create the machines by following either the steps to use an ISO image or network PXE booting. In some cases, you might be able to upload an appropriate {op-system} image from the link:https://access.redhat.com/downloads/content/290[Product Downloads] page on the Red Hat Customer Portal or the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/4.7/[{op-system} image mirror] to your cloud provider and use that image to create the machines. - -There are several methods of configuring {op-system} during ISO and -PXE installations. These include: - -* Kernel arguments: For a PXE install, you can `APPEND` arguments to the -kernel of the live installer. For an ISO install, you can interrupt the -live installation boot process to add kernel arguments. In both cases, you can use -special `coreos.inst.*` arguments to direct the live installer, as well as -standard installation boot arguments for turning standard kernel services -on or off. - -* Ignition configs: You must generate an {product-title} Ignition config file -(`*.ign`) for the type of node you are installing (worker, control plane, -or bootstrap). You pass the location of the Ignition config to the installed -system so that it takes effect on first boot. In special cases, you can create a -separate, limited Ignition config to pass to the live system. That Ignition config could do a certain set of tasks, such as reporting success to a provisioning system -after completing installation. This special Ignition config is consumed by the installer and should not -be used to include the standard `worker` and `master` Ignition configs. - -* `coreos-installer`: You can boot the live ISO installer to a shell prompt, -which allows you to prepare the permanent system in a variety of ways -before first boot. In particular, you can run the `coreos-installer` -command to identify various artifacts to include, work with disk partitions, -and set up networking. In some cases, you can configure features on -the live system and copy them to the installed system. - -Whether to use an ISO or PXE install depends on your situation. -A PXE install requires an available DHCP service and more preparation, -but can make the installation process more automated. An ISO install -is a more manual process and can be inconvenient if you are setting -up more than a few machines. - -[NOTE] -==== -As of {product-title} 4.6, the {op-system} ISO and other installation artifacts -provide support for installation on disks with 4K sectors. -==== - - -include::modules/installation-user-infra-machines-iso.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-pxe.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-advanced.adoc[leveloffset=+2] - -include::modules/installation-user-infra-machines-static-network.adoc[leveloffset=+3] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+2] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout-bare-metal.adoc[leveloffset=+3] - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc#configuring-registry-storage-baremetal[Set up your registry and configure registry storage]. diff --git a/installing/installing_rhv/installing-rhv-customizations.adoc b/installing/installing_rhv/installing-rhv-customizations.adoc deleted file mode 100644 index 012ba21c98e9..000000000000 --- a/installing/installing_rhv/installing-rhv-customizations.adoc +++ /dev/null @@ -1,94 +0,0 @@ -[id="installing-rhv-customizations"] -= Installing a cluster on {rh-virtualization} with customizations -include::modules/common-attributes.adoc[] -:context: installing-rhv-customizations - -toc::[] - -You can customize and install an {product-title} cluster on {rh-virtualization-first}, similar to the one shown in the following diagram. - -image::92_OpenShift_Cluster_Install_RHV_0520.png[Diagram of an {product-title} cluster on a {rh-virtualization} cluster] - -The installation program uses installer-provisioned infrastructure to automate creating and deploying the cluster. - -To install a customized cluster, you prepare the environment and perform the following steps: - -. Create an installation configuration file, the `install-config.yaml` file, by running the installation program and answering its prompts. -. Inspect and modify parameters in the `install-config.yaml` file. -. Make a working copy of the `install-config.yaml` file. -. Run the installation program with a copy of the `install-config.yaml` file. - -Then, the installation program creates the {product-title} cluster. - -For an alternative to installing a customized cluster, see xref:../../installing/installing_rhv/installing-rhv-default.adoc#installing-rhv-default[Installing a default cluster]. - -[NOTE] -==== -This installation program is available for Linux and macOS only. -==== - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installing-rhv-requirements.adoc[leveloffset=+1] - -include::modules/installing-rhv-verifying-rhv-environment.adoc[leveloffset=+1] - -include::modules/installing-rhv-preparing-network-environment.adoc[leveloffset=+1] - -include::modules/installing-rhv-insecure-mode.adoc[leveloffset=+1] - -// include::modules/installing-rhv-setting-up-ca-certificate.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installing-rhv-example-install-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -[IMPORTANT] -==== -You have completed the steps required to install the cluster. The remaining steps show you how to verify the cluster and troubleshoot the installation. -==== - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -To learn more, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#getting-started-cli[Getting started with the OpenShift CLI]. - -include::modules/installation-osp-verifying-cluster-status.adoc[leveloffset=+1] - -.Troubleshooting -If the installation fails, the installation program times out and displays an error message. To learn more, see -xref:../../installing/installing-troubleshooting.adoc#installing-troubleshooting[Troubleshooting installation issues]. - -include::modules/installing-rhv-accessing-ocp-web-console.adoc[leveloffset=+1] - -include::modules/installation-common-issues.adoc[leveloffset=+1] - -== Post-installation tasks - -After the {product-title} cluster initializes, you can perform the following tasks. - -* Optional: After deployment, add or replace SSH keys using the Machine Config Operator (MCO) in {product-title}. -* Optional: Remove the `kubeadmin` user. Instead, use the authentication provider to create a user with cluster-admin privileges. - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. diff --git a/installing/installing_rhv/installing-rhv-default.adoc b/installing/installing_rhv/installing-rhv-default.adoc deleted file mode 100644 index dae88bbe3439..000000000000 --- a/installing/installing_rhv/installing-rhv-default.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[id="installing-rhv-default"] -= Installing a cluster quickly on {rh-virtualization} -include::modules/common-attributes.adoc[] -:context: installing-rhv-default - -toc::[] - -You can quickly install a default, non-customized, {product-title} cluster on a {rh-virtualization-first} cluster, similar to the one shown in the following diagram. - -image::92_OpenShift_Cluster_Install_RHV_0520.png[Diagram of an {product-title} cluster on a {rh-virtualization} cluster] - -The installation program uses installer-provisioned infrastructure to automate creating and deploying the cluster. - -To install a default cluster, you prepare the environment, run the installation program and answer its prompts. Then, the installation program creates the {product-title} cluster. - -For an alternative to installing a default cluster, see xref:../../installing/installing_rhv/installing-rhv-customizations.adoc#installing-rhv-customizations[Installing a cluster with customizations]. - -[NOTE] -==== -This installation program is available for Linux and macOS only. -==== - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installing-rhv-requirements.adoc[leveloffset=+1] - -include::modules/installing-rhv-verifying-rhv-environment.adoc[leveloffset=+1] - -include::modules/installing-rhv-preparing-network-environment.adoc[leveloffset=+1] - -include::modules/installing-rhv-insecure-mode.adoc[leveloffset=+1] - -// include::modules/installing-rhv-setting-up-ca-certificate.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -[IMPORTANT] -==== -You have completed the steps required to install the cluster. The remaining steps show you how to verify the cluster and troubleshoot the installation. -==== - -include::modules/cli-installing-cli.adoc[leveloffset=1] - -To learn more, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#getting-started-cli[Getting started with the OpenShift CLI]. - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=1] - -include::modules/installation-osp-verifying-cluster-status.adoc[leveloffset=+1] - -.Troubleshooting -If the installation fails, the installation program times out and displays an error message. To learn more, see -xref:../../installing/installing-troubleshooting.adoc#installing-troubleshooting[Troubleshooting installation issues]. - -include::modules/installing-rhv-accessing-ocp-web-console.adoc[leveloffset=+1] - -include::modules/installation-common-issues.adoc[leveloffset=+1] - -== Post-installation tasks -After the {product-title} cluster initializes, you can perform the following tasks. - -* Optional: After deployment, add or replace SSH keys using the Machine Config Operator (MCO) in {product-title}. -* Optional: Remove the `kubeadmin` user. Instead, use the authentication provider to create a user with cluster-admin privileges. diff --git a/installing/installing_rhv/installing-rhv-restricted-network.adoc b/installing/installing_rhv/installing-rhv-restricted-network.adoc deleted file mode 100644 index a6df57c78a06..000000000000 --- a/installing/installing_rhv/installing-rhv-restricted-network.adoc +++ /dev/null @@ -1,82 +0,0 @@ -[id="installing-rhv-restricted-network"] -= Installing a cluster on {rh-virtualization} in a restricted network -include::modules/common-attributes.adoc[] -:context: installing-rhv-restricted-network - -toc::[] - -In {product-title} version {product-version}, you can install a -customized {product-title} cluster on {rh-virtualization-first} in a restricted network by creating an internal mirror of the installation release content. - -== Prerequisites - -The following items are required to install an {product-title} cluster on a {rh-virtualization} environment. - -* You have a supported combination of versions in the link:https://access.redhat.com/articles/5485861[Support Matrix for {product-title} on {rh-virtualization}]. -* You are familiar with the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a registry on your mirror host] and obtain the `imageContentSources` data for your version of {product-title}. -+ -[IMPORTANT] -==== -Because the installation media is on the mirror host, you can use that computer -to complete all installation steps. -==== -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] for your cluster. To deploy a private image registry, your storage must provide ReadWriteMany access modes. -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall and plan to use telemetry, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installing-rhv-requirements.adoc[leveloffset=+1] - -include::modules/installing-rhv-verifying-rhv-environment.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+1] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+1] - -include::modules/installing-rhv-setting-up-installation-machine.adoc[leveloffset=+1] - -include::modules/installing-rhv-setting-up-ca-certificate.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-rhv-downloading-ansible-playbooks.adoc[leveloffset=+1] - -include::modules/installation-rhv-about-inventory-yml.adoc[leveloffset=+1] - -include::modules/installation-rhv-specifying-rhcos-image-settings.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-install-config-file.adoc[leveloffset=+1] - -include::modules/installation-bare-metal-config-yaml.adoc[leveloffset=+1] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -include::modules/installation-rhv-customizing-install-config-yaml.adoc[leveloffset=+1] - -include::modules/installation-rhv-editing-manifests.adoc[leveloffset=+1] - -include::modules/installation-rhv-making-control-plane-nodes-non-schedulable.adoc[leveloffset=+1] - -include::modules/installation-rhv-building-ignition-files.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-templates-virtual-machines.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-bootstrap-machine.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-control-plane-nodes.adoc[leveloffset=+1] - -include::modules/installation-osp-verifying-cluster-status.adoc[leveloffset=+1] - -include::modules/installation-rhv-removing-bootstrap-machine.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-worker-nodes-completing-installation.adoc[leveloffset=+1] diff --git a/installing/installing_rhv/installing-rhv-user-infra.adoc b/installing/installing_rhv/installing-rhv-user-infra.adoc deleted file mode 100644 index 87ac9bff9114..000000000000 --- a/installing/installing_rhv/installing-rhv-user-infra.adoc +++ /dev/null @@ -1,67 +0,0 @@ -[id="installing-rhv-user-infra"] -= Installing a cluster on {rh-virtualization} with user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: installing-rhv-user-infra - -toc::[] - -In {product-title} version {product-version}, you can install a -customized {product-title} cluster on {rh-virtualization-first} and other infrastructure that you provide. The {product-title} documentation uses the term _user-provisioned infrastructure_ to refer to this infrastructure type. - -The following diagram shows an example of a potential {product-title} cluster running on a {rh-virtualization} cluster. - -image::92_OpenShift_Cluster_Install_RHV_0520.png[Diagram of an {product-title} cluster on a {rh-virtualization} cluster. The {rh-virtualization} hosts run virtual machines that contain both control plane and compute pods. One of the hosts also runs a {rh-virtualization} Manager/Engine virtual machine and a bootstrap virtual machine that contains a temporary control plane pod.] - -== Prerequisites - -The following items are required to install an {product-title} cluster on a {rh-virtualization} environment. - -* You have a supported combination of versions in the link:https://access.redhat.com/articles/5485861[Support Matrix for {product-title} on {rh-virtualization}]. -* You are familiar with the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. - - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installing-rhv-requirements.adoc[leveloffset=+1] - -include::modules/installing-rhv-verifying-rhv-environment.adoc[leveloffset=+1] - -include::modules/installing-rhv-network-infrastructure-configuration-upi.adoc[leveloffset=+1] - -include::modules/installing-rhv-setting-up-installation-machine.adoc[leveloffset=+1] - -include::modules/installing-rhv-insecure-mode.adoc[leveloffset=+1] - -// include::modules/installing-rhv-setting-up-ca-certificate.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-rhv-downloading-ansible-playbooks.adoc[leveloffset=+1] - -include::modules/installation-rhv-about-inventory-yml.adoc[leveloffset=+1] - -include::modules/installation-rhv-specifying-rhcos-image-settings.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-install-config-file.adoc[leveloffset=+1] - -include::modules/installation-rhv-customizing-install-config-yaml.adoc[leveloffset=+1] - -include::modules/installation-rhv-editing-manifests.adoc[leveloffset=+1] - -include::modules/installation-rhv-making-control-plane-nodes-non-schedulable.adoc[leveloffset=+1] - -include::modules/installation-rhv-building-ignition-files.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-templates-virtual-machines.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-bootstrap-machine.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-control-plane-nodes.adoc[leveloffset=+1] - -include::modules/installation-osp-verifying-cluster-status.adoc[leveloffset=+1] - -include::modules/installation-rhv-removing-bootstrap-machine.adoc[leveloffset=+1] - -include::modules/installation-rhv-creating-worker-nodes-completing-installation.adoc[leveloffset=+1] diff --git a/installing/installing_rhv/uninstalling-cluster-rhv.adoc b/installing/installing_rhv/uninstalling-cluster-rhv.adoc deleted file mode 100644 index 3a8efb907653..000000000000 --- a/installing/installing_rhv/uninstalling-cluster-rhv.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="uninstalling-cluster-rhv"] -= Uninstalling a cluster on {rh-virtualization} -include::modules/common-attributes.adoc[] -:context: uninstalling-cluster-rhv - -toc::[] - -You can remove an {product-title} cluster from {rh-virtualization-first}. - -include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] - -include::modules/installation-rhv-removing-cluster-upi.adoc[leveloffset=+1] diff --git a/installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc b/installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc deleted file mode 100644 index 6d797757aada..000000000000 --- a/installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc +++ /dev/null @@ -1,103 +0,0 @@ -[id="installing-restricted-networks-vmc-user-infra"] -= Installing a cluster on VMC in a restricted network with user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-vmc-user-infra - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on VMware vSphere infrastructure that you provision in a restricted network by deploying it to link:https://cloud.vmware.com/vmc-aws[VMware Cloud (VMC) on AWS]. - -Once you configure your VMC environment for {product-title} deployment, you use the {product-title} installation program from the bastion management host, co-located in the VMC environment. The installation program and control plane automates the process of deploying and managing the resources needed for the {product-title} cluster. - -include::modules/setting-up-vmc-for-vsphere.adoc[leveloffset=+1] -include::modules/vmc-sizer-tool.adoc[leveloffset=+2] - -== vSphere prerequisites - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a registry on your mirror host] and obtain the `imageContentSources` data for your version of {product-title}. -+ -[IMPORTANT] -==== -Because the installation media is on the mirror host, you can use that computer -to complete all installation steps. -==== -* Provision xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#installation-registry-storage-block-recreate-rollout_configuring-registry-storage-vsphere[block registry storage]. For more information on persistent storage, see xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage]. -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall and plan to use telemetry, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -//You extract the installation program from the mirrored content. - -//You can install the CLI on the mirror host. - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -include::modules/installation-extracting-infraid.adoc[leveloffset=+1] - -include::modules/installation-vsphere-machines.adoc[leveloffset=+1] - -include::modules/machine-vsphere-machines.adoc[leveloffset=+1] - -include::modules/installation-disk-partitioning.adoc[leveloffset=+1] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring registry storage for VMware vSphere]. - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -You can add extra compute machines after the cluster installation is completed by following xref:../../machine_management/user_infra/adding-vsphere-compute-user-infra.adoc#adding-vsphere-compute-user-infra[Adding compute machines to vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If the mirror registry that you used to install your cluster has a trusted CA, add it to the cluster by xref:../../openshift_images/image-configuration.adoc#images-configuration-cas_image-configuration[configuring additional trust stores]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vmc/installing-vmc-customizations.adoc b/installing/installing_vmc/installing-vmc-customizations.adoc deleted file mode 100644 index dc26887fa11d..000000000000 --- a/installing/installing_vmc/installing-vmc-customizations.adoc +++ /dev/null @@ -1,75 +0,0 @@ -[id="installing-vmc-customizations"] -= Installing a cluster on VMC with customizations -include::modules/common-attributes.adoc[] -:context: installing-vmc-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on your VMware vSphere instance using installer-provisioned infrastructure by deploying it to link:https://cloud.vmware.com/vmc-aws[VMware Cloud (VMC) on AWS]. - -Once you configure your VMC environment for {product-title} deployment, you use the {product-title} installation program from the bastion management host, co-located in the VMC environment. The installation program and control plane automates the process of deploying and managing the resources needed for the {product-title} cluster. - -To customize the {product-title} installation, you modify parameters in the `install-config.yaml` file before you install the cluster. - -include::modules/setting-up-vmc-for-vsphere.adoc[leveloffset=+1] -include::modules/vmc-sizer-tool.adoc[leveloffset=+2] - -== vSphere prerequisites - -* Provision xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#installation-registry-storage-block-recreate-rollout_configuring-registry-storage-vsphere[block registry storage]. For more information on persistent storage, see xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage]. -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-installer-provisioned-vsphere-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -[id="installing-vmc-customizations-registry"] -== Creating registry storage - -After you install the cluster, you must create storage for the Registry Operator. - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc b/installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc deleted file mode 100644 index b292b4b07016..000000000000 --- a/installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc +++ /dev/null @@ -1,88 +0,0 @@ -[id="installing-vmc-network-customizations-user-infra"] -= Installing a cluster on VMC with user-provisioned infrastructure and network customizations -include::modules/common-attributes.adoc[] -:context: installing-vmc-network-customizations-user-infra - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on your VMware vSphere instance using infrastructure you provision with customized network configuration options by deploying it to link:https://cloud.vmware.com/vmc-aws[VMware Cloud (VMC) on AWS]. - -Once you configure your VMC environment for {product-title} deployment, you use the {product-title} installation program from the bastion management host, co-located in the VMC environment. The installation program and control plane automates the process of deploying and managing the resources needed for the {product-title} cluster. - -By customizing your network configuration, your cluster can coexist with existing IP address allocations in your environment and integrate with existing VXLAN configurations. You must set most of the network configuration parameters during installation, and you can modify only `kubeProxy` configuration parameters in a running cluster. - -include::modules/setting-up-vmc-for-vsphere.adoc[leveloffset=+1] -include::modules/vmc-sizer-tool.adoc[leveloffset=+2] - -== vSphere prerequisites - -* Provision xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#installation-registry-storage-block-recreate-rollout_configuring-registry-storage-vsphere[block registry storage]. For more information on persistent storage, see xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage]. -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to access Red Hat Insights]. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2] - -// Network Operator specific configuration - -include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1] -include::modules/nw-operator-cr.adoc[leveloffset=+1] - -include::modules/installation-generate-ignition-configs.adoc[leveloffset=+1] - -include::modules/installation-extracting-infraid.adoc[leveloffset=+1] - -include::modules/installation-vsphere-machines.adoc[leveloffset=+1] - -include::modules/machine-vsphere-machines.adoc[leveloffset=+1] - -include::modules/installation-disk-partitioning.adoc[leveloffset=+1] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -You can add extra compute machines after the cluster installation is completed by following xref:../../machine_management/user_infra/adding-vsphere-compute-user-infra.adoc#adding-vsphere-compute-user-infra[Adding compute machines to vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vmc/installing-vmc-network-customizations.adoc b/installing/installing_vmc/installing-vmc-network-customizations.adoc deleted file mode 100644 index b94b829fe72b..000000000000 --- a/installing/installing_vmc/installing-vmc-network-customizations.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id="installing-vmc-network-customizations"] -= Installing a cluster on VMC with network customizations -include::modules/common-attributes.adoc[] -:context: installing-vmc-network-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on your VMware vSphere instance using installer-provisioned infrastructure with customized network configuration options by deploying it to link:https://cloud.vmware.com/vmc-aws[VMware Cloud (VMC) on AWS]. - -Once you configure your VMC environment for {product-title} deployment, you use the {product-title} installation program from the bastion management host, co-located in the VMC environment. The installation program and control plane automates the process of deploying and managing the resources needed for the {product-title} cluster. - -By customizing your {product-title} network configuration, your cluster can coexist with existing IP address allocations in your environment and integrate with existing VXLAN configurations. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster. You must set most of the network configuration parameters during installation, and you can modify only `kubeProxy` configuration parameters in a running cluster. - -include::modules/setting-up-vmc-for-vsphere.adoc[leveloffset=+1] -include::modules/vmc-sizer-tool.adoc[leveloffset=+2] - -== vSphere prerequisites - -* Provision xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#installation-registry-storage-block-recreate-rollout_configuring-registry-storage-vsphere[block registry storage]. For more information on persistent storage, see xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage]. -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-installer-provisioned-vsphere-config-yaml.adoc[leveloffset=+2] - -// begin network customization -include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1] -include::modules/nw-operator-cr.adoc[leveloffset=+1] -// end network customization - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -[id="installing-vmc-network-customizations-registry"] -== Creating registry storage -After you install the cluster, you must create storage for the registry Operator. - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vmc/installing-vmc-user-infra.adoc b/installing/installing_vmc/installing-vmc-user-infra.adoc deleted file mode 100644 index 1792e7722e0c..000000000000 --- a/installing/installing_vmc/installing-vmc-user-infra.adoc +++ /dev/null @@ -1,96 +0,0 @@ -[id="installing-vmc-user-infra"] -= Installing a cluster on VMC with user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: installing-vmc-user-infra - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on VMware vSphere infrastructure that you provision by deploying it to link:https://cloud.vmware.com/vmc-aws[VMware Cloud (VMC) on AWS]. - -Once you configure your VMC environment for {product-title} deployment, you use the {product-title} installation program from the bastion management host, co-located in the VMC environment. The installation program and control plane automates the process of deploying and managing the resources needed for the {product-title} cluster. - -include::modules/setting-up-vmc-for-vsphere.adoc[leveloffset=+1] -include::modules/vmc-sizer-tool.adoc[leveloffset=+2] - -== vSphere prerequisites - -* Provision xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#installation-registry-storage-block-recreate-rollout_configuring-registry-storage-vsphere[block registry storage]. For more information on persistent storage, see xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage]. -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -include::modules/installation-extracting-infraid.adoc[leveloffset=+1] - -include::modules/installation-vsphere-machines.adoc[leveloffset=+1] - -include::modules/machine-vsphere-machines.adoc[leveloffset=+1] - -include::modules/installation-disk-partitioning.adoc[leveloffset=+1] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -You can add extra compute machines after the cluster installation is completed by following xref:../../machine_management/user_infra/adding-vsphere-compute-user-infra.adoc#adding-vsphere-compute-user-infra[Adding compute machines to vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vmc/installing-vmc.adoc b/installing/installing_vmc/installing-vmc.adoc deleted file mode 100644 index bf3add6569b2..000000000000 --- a/installing/installing_vmc/installing-vmc.adoc +++ /dev/null @@ -1,66 +0,0 @@ -[id="installing-vmc"] -= Installing a cluster on VMC -include::modules/common-attributes.adoc[] -:context: installing-vmc - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on VMware vSphere by deploying it to link:https://cloud.vmware.com/vmc-aws[VMware Cloud (VMC) on AWS]. - -Once you have configured your VMC environment for {product-title} deployment, you use the {product-title} installation program from the bastion management host, co-located in the VMC environment. The installation program and control plane automates the process of deploying and managing the resources needed for the {product-title} cluster. - -include::modules/setting-up-vmc-for-vsphere.adoc[leveloffset=+1] -include::modules/vmc-sizer-tool.adoc[leveloffset=+2] - -== vSphere prerequisites - -* Provision xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#installation-registry-storage-block-recreate-rollout_configuring-registry-storage-vsphere[block registry storage]. For more information on persistent storage, see xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage]. -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -[id="installing-vmc-registry"] -== Creating registry storage -After you install the cluster, you must create storage for the registry Operator. - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vmc/modules b/installing/installing_vmc/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/installing/installing_vmc/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/installing/installing_vmc/uninstalling-cluster-vmc.adoc b/installing/installing_vmc/uninstalling-cluster-vmc.adoc deleted file mode 100644 index 0b97a8bda4fd..000000000000 --- a/installing/installing_vmc/uninstalling-cluster-vmc.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="uninstalling-cluster-vmc"] -= Uninstalling a cluster on VMC -include::modules/common-attributes.adoc[] -:context: uninstalling-cluster-vmc - -toc::[] - -You can remove a cluster installed on VMware vSphere infrastructure that you deployed to link:https://cloud.vmware.com/vmc-aws[VMware Cloud (VMC) on AWS] by using installer-provisioned infrastructure. - -include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] diff --git a/installing/installing_vsphere/images b/installing/installing_vsphere/images deleted file mode 120000 index 847b03ed0541..000000000000 --- a/installing/installing_vsphere/images +++ /dev/null @@ -1 +0,0 @@ -../../images/ \ No newline at end of file diff --git a/installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc b/installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc deleted file mode 100644 index 9cec8348e536..000000000000 --- a/installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc +++ /dev/null @@ -1,70 +0,0 @@ -[id="installing-restricted-networks-installer-provisioned-vsphere"] -= Installing a cluster on vSphere in a restricted network -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-installer-provisioned-vsphere - -toc::[] - -In {product-title} {product-version}, you can install a cluster on VMware vSphere infrastructure in a restricted network by creating an internal mirror of the installation release content. - -[id="prerequisites_installing-restricted-networks-installer-provisioned-vsphere"] -== Prerequisites - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a registry on your mirror host] and obtain the `imageContentSources` data for your version of {product-title}. -+ -[IMPORTANT] -==== -Because the installation media is on the mirror host, you can use that computer to complete all installation steps. -==== -* Provision xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] for your cluster. To deploy a private image registry, your storage must provide the ReadWriteMany access mode. -* Review details about the xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] processes. -* If you use a firewall and plan to use telemetry, you must xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -If you are configuring a proxy, be sure to also review this site list. -==== - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] - -include::modules/installation-creating-image-restricted.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-installer-provisioned-vsphere-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -[id="installing-vsphere-restricted-networks-installer-provisioned-customizations-registry"] -== Creating registry storage - -After you install the cluster, you must create storage for the Registry Operator. - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -[id="next-steps_installing-restricted-networks-installer-provisioned-vsphere"] -== Next steps - -* xref:../../installing/install_config/installing-customizing.adoc#installing-customizing[Customize your cluster]. -* If necessary, you can xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. diff --git a/installing/installing_vsphere/installing-restricted-networks-vsphere.adoc b/installing/installing_vsphere/installing-restricted-networks-vsphere.adoc deleted file mode 100644 index 237cbad738ee..000000000000 --- a/installing/installing_vsphere/installing-restricted-networks-vsphere.adoc +++ /dev/null @@ -1,114 +0,0 @@ -[id="installing-restricted-networks-vsphere"] -= Installing a cluster on vSphere in a restricted network with user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: installing-restricted-networks-vsphere - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -VMware vSphere infrastructure that you provision in a restricted network. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the vSphere platform and the installation process of {product-title}. Use the user-provisioned infrastructure installation instructions as a guide; you are free to create the required resources through other methods. -==== - -== Prerequisites - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Create a registry on your mirror host] and obtain the `imageContentSources` data for your version of {product-title}. -+ -[IMPORTANT] -==== -Because the installation media is on the mirror host, you can use that computer -to complete all installation steps. -==== -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] -for your cluster. To deploy a private image registry, your storage must provide -`ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall and plan to use telemetry, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure the firewall to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/installation-about-restricted-network.adoc[leveloffset=+1] - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -//You extract the installation program from the mirrored content. - -//You can install the CLI on the mirror host. - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -include::modules/installation-extracting-infraid.adoc[leveloffset=+1] - -include::modules/installation-vsphere-machines.adoc[leveloffset=+1] - -include::modules/machine-vsphere-machines.adoc[leveloffset=+1] - -include::modules/installation-disk-partitioning.adoc[leveloffset=+1] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -You can add extra compute machines after the cluster installation is completed by following xref:../../machine_management/user_infra/adding-vsphere-compute-user-infra.adoc#adding-vsphere-compute-user-infra[Adding compute machines to vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If the mirror registry that you used to install your cluster has a trusted CA, add it to the cluster by xref:../../openshift_images/image-configuration.adoc#images-configuration-cas_image-configuration[configuring additional trust stores]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc b/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc deleted file mode 100644 index 77b3f2db49b7..000000000000 --- a/installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[id="installing-vsphere-installer-provisioned-customizations"] -= Installing a cluster on vSphere with customizations -include::modules/common-attributes.adoc[] -:context: installing-vsphere-installer-provisioned-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on your -VMware vSphere instance by using installer-provisioned infrastructure. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster. - -== Prerequisites - -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] -for your cluster. To deploy a private image registry, your storage must provide -`ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-installer-provisioned-vsphere-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -[id="installing-vsphere-installer-provisioned-customizations-registry"] -== Creating registry storage -After you install the cluster, you must create storage for the registry Operator. - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc b/installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc deleted file mode 100644 index 7deb3f73294e..000000000000 --- a/installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc +++ /dev/null @@ -1,81 +0,0 @@ -[id="installing-vsphere-installer-provisioned-network-customizations"] -= Installing a cluster on vSphere with network customizations -include::modules/common-attributes.adoc[] -:context: installing-vsphere-installer-provisioned-network-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on your -VMware vSphere instance by using installer-provisioned infrastructure with customized network configuration options. By customizing your network configuration, your cluster can coexist with existing IP address allocations in your environment and integrate with existing MTU and VXLAN configurations. To customize the installation, you modify parameters in the `install-config.yaml` file before you install the cluster. - -You must set most of the network configuration parameters during installation, and you can modify only `kubeProxy` configuration parameters in a running cluster. - -== Prerequisites - -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] -for your cluster. To deploy a private image registry, your storage must provide -`ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] - -include::modules/installation-initializing.adoc[leveloffset=+1] - -include::modules/installation-configuration-parameters.adoc[leveloffset=+2] - -include::modules/installation-installer-provisioned-vsphere-config-yaml.adoc[leveloffset=+2] - -// begin network customization -include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1] -include::modules/nw-operator-cr.adoc[leveloffset=+1] -// end network customization - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -[id="installing-vsphere-installer-provisioned-network-customizations-registry"] -== Creating registry storage -After you install the cluster, you must create storage for the registry Operator. - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc b/installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc deleted file mode 100644 index e0577dfd3271..000000000000 --- a/installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc +++ /dev/null @@ -1,68 +0,0 @@ -[id="installing-vsphere-installer-provisioned"] -= Installing a cluster on vSphere -include::modules/common-attributes.adoc[] -:context: installing-vsphere-installer-provisioned - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on your -VMware vSphere instance by using installer-provisioned infrastructure. - -== Prerequisites - -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] -for your cluster. To deploy a private image registry, your storage must provide -`ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-vsphere-installer-infra-requirements.adoc[leveloffset=+1] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-adding-vcenter-root-certificates.adoc[leveloffset=+1] - -include::modules/installation-launching-installer.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -[id="installing-vsphere-installer-provisioned-registry"] -== Creating registry storage -After you install the cluster, you must create storage for the registry Operator. - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vsphere/installing-vsphere-network-customizations.adoc b/installing/installing_vsphere/installing-vsphere-network-customizations.adoc deleted file mode 100644 index 45c97ece4d15..000000000000 --- a/installing/installing_vsphere/installing-vsphere-network-customizations.adoc +++ /dev/null @@ -1,100 +0,0 @@ -[id="installing-vsphere-network-customizations"] -= Installing a cluster on vSphere with network customizations -include::modules/common-attributes.adoc[] -:context: installing-vsphere-network-customizations - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -VMware vSphere infrastructure that you provision with customized network -configuration options. By customizing your network configuration, your cluster -can coexist with existing IP address allocations in your environment and -integrate with existing MTU and VXLAN configurations. - -You must set most of the network configuration parameters during installation, -and you can modify only `kubeProxy` configuration parameters in a running -cluster. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the vSphere platform and the installation process of {product-title}. Use the user-provisioned infrastructure installation instructions as a guide; you are free to create the required resources through other methods. -==== - -== Prerequisites - -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to access Red Hat Insights]. - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2] - -// Network Operator specific configuration - -include::modules/nw-modifying-operator-install-config.adoc[leveloffset=+1] -include::modules/nw-operator-cr.adoc[leveloffset=+1] - -include::modules/installation-generate-ignition-configs.adoc[leveloffset=+1] - -include::modules/installation-extracting-infraid.adoc[leveloffset=+1] - -include::modules/installation-vsphere-machines.adoc[leveloffset=+1] - -include::modules/machine-vsphere-machines.adoc[leveloffset=+1] - -include::modules/installation-disk-partitioning.adoc[leveloffset=+1] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -You can add extra compute machines after the cluster installation is completed by following xref:../../machine_management/user_infra/adding-vsphere-compute-user-infra.adoc#adding-vsphere-compute-user-infra[Adding compute machines to vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vsphere/installing-vsphere.adoc b/installing/installing_vsphere/installing-vsphere.adoc deleted file mode 100644 index 11be3d52f375..000000000000 --- a/installing/installing_vsphere/installing-vsphere.adoc +++ /dev/null @@ -1,107 +0,0 @@ -[id="installing-vsphere"] -= Installing a cluster on vSphere with user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: installing-vsphere - -toc::[] - -In {product-title} version {product-version}, you can install a cluster on -VMware vSphere infrastructure that you provision. - -[IMPORTANT] -==== -The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the vSphere platform and the installation process of {product-title}. Use the user-provisioned infrastructure installation instructions as a guide; you are free to create the required resources through other methods. -==== - -== Prerequisites - -* Provision -xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] -for your cluster. To deploy a private image registry, your storage must provide -`ReadWriteMany` access modes. -* Review details about the -xref:../../architecture/architecture-installation.adoc#architecture-installation[{product-title} installation and update] -processes. -* If you use a firewall, you must -xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[configure it to allow the sites] that your cluster requires access to. -+ -[NOTE] -==== -Be sure to also review this site list if you are configuring a proxy. -==== - -include::modules/cluster-entitlements.adoc[leveloffset=+1] - -include::modules/installation-vsphere-infrastructure.adoc[leveloffset=+1] - -include::modules/installation-requirements-user-infra.adoc[leveloffset=+1] - -include::modules/installation-infrastructure-user-infra.adoc[leveloffset=+1] - -include::modules/installation-network-user-infra.adoc[leveloffset=+2] - -.Additional resources - -* xref:../install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Configuring chrony time service] - -include::modules/installation-dns-user-infra.adoc[leveloffset=+2] - -include::modules/ssh-agent-using.adoc[leveloffset=+1] - -include::modules/installation-obtaining-installer.adoc[leveloffset=+1] - -include::modules/installation-initializing-manual.adoc[leveloffset=+1] - -include::modules/installation-vsphere-config-yaml.adoc[leveloffset=+2] - -include::modules/installation-configure-proxy.adoc[leveloffset=+2] - -//include::modules/installation-three-node-cluster.adoc[leveloffset=+2] - -include::modules/installation-user-infra-generate-k8s-manifest-ignition.adoc[leveloffset=+1] - -include::modules/installation-extracting-infraid.adoc[leveloffset=+1] - -include::modules/installation-vsphere-machines.adoc[leveloffset=+1] - -include::modules/machine-vsphere-machines.adoc[leveloffset=+1] - -include::modules/installation-disk-partitioning.adoc[leveloffset=+1] - -include::modules/architecture-rhcos-updating-bootloader.adoc[leveloffset=+1] - -include::modules/cli-installing-cli.adoc[leveloffset=+1] - -include::modules/installation-installing-bare-metal.adoc[leveloffset=+1] - -include::modules/cli-logging-in-kubeadmin.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/installation-operators-config.adoc[leveloffset=+1] - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+3] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+3] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -include::modules/installation-complete-user-infra.adoc[leveloffset=+1] - -You can add extra compute machines after the cluster installation is completed by following xref:../../machine_management/user_infra/adding-vsphere-compute-user-infra.adoc#adding-vsphere-compute-user-infra[Adding compute machines to vSphere]. - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] - -== Next steps - -* xref:../../post_installation_configuration/cluster-tasks.adoc#available_cluster_customizations[Customize your cluster]. -* If necessary, you can -xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[opt out of remote health reporting]. -* xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Set up your registry and configure registry storage]. -* Optional: xref:../../installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc#vsphere-problem-detector-viewing-events_vsphere-problem-detector[View the events from the vSphere Problem Detector Operator] to determine if the cluster has permission or storage configuration issues. diff --git a/installing/installing_vsphere/modules b/installing/installing_vsphere/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/installing/installing_vsphere/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/installing/installing_vsphere/uninstalling-cluster-vsphere-installer-provisioned.adoc b/installing/installing_vsphere/uninstalling-cluster-vsphere-installer-provisioned.adoc deleted file mode 100644 index c91d87acdc00..000000000000 --- a/installing/installing_vsphere/uninstalling-cluster-vsphere-installer-provisioned.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="uninstalling-cluster-vsphere-installer-provisioned"] -= Uninstalling a cluster on vSphere that uses installer-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: uninstalling-cluster-vsphere-installer-provisioned - -toc::[] - -You can remove a cluster that you deployed in your VMware vSphere instance by using installer-provisioned infrastructure. - -include::modules/installation-uninstall-clouds.adoc[leveloffset=+1] diff --git a/installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc b/installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc deleted file mode 100644 index 75b19c10f67b..000000000000 --- a/installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="using-vsphere-problem-detector-operator"] -= Using the vSphere Problem Detector Operator -include::modules/common-attributes.adoc[] -:context: vsphere-problem-detector - -toc::[] - -// About the operator -include::modules/vsphere-problem-detector-about.adoc[leveloffset=+1] - -// Run the checks -include::modules/vsphere-problem-detector-running.adoc[leveloffset=+1] - -// View the events -include::modules/vsphere-problem-detector-viewing-events.adoc[leveloffset=+1] - -// View the logs -include::modules/vsphere-problem-detector-viewing-logs.adoc[leveloffset=+1] - -// Reference: Problem detector checks -include::modules/vsphere-problem-detector-config-checks.adoc[leveloffset=+1] - -// Concept: Storage class config check -include::modules/vsphere-problem-detector-storage-class-config-check.adoc[leveloffset=+1] - -// Metrics -include::modules/vsphere-problem-detector-metrics.adoc[leveloffset=+1] - -== Additional resources - -* xref:../../monitoring/understanding-the-monitoring-stack.adoc[Understanding the monitoring stack] diff --git a/jaeger/jaeger_install/modules b/installing/modules similarity index 100% rename from jaeger/jaeger_install/modules rename to installing/modules diff --git a/installing/snippets b/installing/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/installing/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/installing/uninstall-acs.adoc b/installing/uninstall-acs.adoc new file mode 100644 index 000000000000..7286963c9570 --- /dev/null +++ b/installing/uninstall-acs.adoc @@ -0,0 +1,25 @@ +:_mod-docs-content-type: ASSEMBLY +[id="uninstall-acs"] += Uninstalling Red Hat Advanced Cluster Security for Kubernetes +include::modules/common-attributes.adoc[] +:context: uninstall-acs + +toc::[] + +[role="_abstract"] +When you install {product-title}, it creates: + +* A namespace called `rhacs-operator` where the Operator is installed, if you chose the Operator method of installation +* A namespace called `stackrox`, or another namespace where you created the Central and SecuredCluster custom resources +* `PodSecurityPolicy` and Kubernetes role-based access control (RBAC) objects for all components +* Additional labels on namespaces, for use in generated network policies +//TODO: Add link to generate network policies +* An application custom resource definition (CRD), if it does not exist + +Uninstalling {product-title} involves deleting all of these items. + +include::modules/delete-acs-namespace.adoc[leveloffset=+1] + +include::modules/delete-acs-global-resources.adoc[leveloffset=+1] + +include::modules/delete-acs-label-annotation.adoc[leveloffset=+1] diff --git a/installing/validating-an-installation.adoc b/installing/validating-an-installation.adoc deleted file mode 100644 index 1f67fcca5484..000000000000 --- a/installing/validating-an-installation.adoc +++ /dev/null @@ -1,62 +0,0 @@ -[id="validating-an-installation"] -= Validating an installation -include::modules/common-attributes.adoc[] -:context: validating-an-installation - -toc::[] - -You can check the status of an {product-title} cluster after an installation by following the procedures in this document. - -//Reviewing the installation log -include::modules/reviewing-the-installation-log.adoc[leveloffset=+1] - -//Getting cluster version, status, and update details -include::modules/getting-cluster-version-status-and-update-details.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../support/troubleshooting/troubleshooting-installations.adoc#querying-operator-status-after-installation_troubleshooting-installations[Querying Operator status after installation] for more information about querying Operator status if your installation is still progressing. - -* See xref:../support/troubleshooting/troubleshooting-operator-issues.adoc#troubleshooting-operator-issues[Troubleshooting Operator issues] for information about investigating issues with Operators. - -* See xref:../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[Updating a cluster between minor versions] for more information on updating your cluster. - -* See xref:../updating/updating-cluster-between-minor.adoc#understanding-upgrade-channels_updating-cluster-between-minor[OpenShift Container Platform upgrade channels and releases] for an overview about upgrade release channels. - -//Querying the status of the cluster nodes by using the CLI -include::modules/querying-the-status-of-cluster-nodes-using-the-cli.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../support/troubleshooting/verifying-node-health.adoc#verifying-node-health[Verifying node health] for more details about reviewing node health and investigating node issues. - -//Reviewing the cluster status from the OpenShift Container Platform web console -include::modules/reviewing-cluster-status-from-the-openshift-web-console.adoc[leveloffset=+1] - -//Reviewing the cluster status from the OpenShift Cluster Manager -include::modules/reviewing-cluster-status-from-the-openshift-cluster-manager.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc#using-insights-to-identify-issues-with-your-cluster[Using Insights to identify issues with your cluster] for more information about reviewing potential issues with your cluster. - -//Checking cluster resource availability and utilization -include::modules/checking-cluster-resource-availability-and-utilization.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Understanding the monitoring stack] for more information about the {product-title} monitoring stack. - -//Listing alerts that are firing -include::modules/listing-alerts-that-are-firing.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../monitoring/managing-alerts.adoc#managing-alerts[Managing alerts] for further details about alerting in {product-title}. - -[id="validating-an-installation-next-steps"] -== Next steps - -* See xref:../support/troubleshooting/troubleshooting-installations.adoc#troubleshooting-installations[Troubleshooting installations] if you experience issues when installing your cluster. - -* After installing {product-title}, you can xref:../post_installation_configuration/cluster-tasks.adoc#post-install-cluster-tasks[further expand and customize your cluster]. diff --git a/applications/application_life_cycle_management/images b/integration/images similarity index 100% rename from applications/application_life_cycle_management/images rename to integration/images diff --git a/integration/integrate-using-generic-webhooks.adoc b/integration/integrate-using-generic-webhooks.adoc new file mode 100644 index 000000000000..5f2d8b3510a6 --- /dev/null +++ b/integration/integrate-using-generic-webhooks.adoc @@ -0,0 +1,40 @@ +[id="integrate-using-generic-webhooks"] += Integrating by using generic webhooks +include::modules/common-attributes.adoc[] +:context: integrate-using-generic-webhooks + +toc::[] + +[role="_abstract"] +With {product-title}, you can send alert notifications as JSON messages to any webhook receiver. When a violation occurs, {product-title} makes an HTTP POST request on the configured URL. The POST request body includes JSON-formatted information about the alert. + +The webhook POST request's JSON data includes a `v1.Alert` object and any custom fields that you configure, as shown in the following example: + +[source,json] +---- +{ + "alert": { + "id": "", + "time": "", + "policy": { + "name": "", + ... + }, + ... + }, + "": "" +} +---- + +You can create multiple webhooks. For example, you can create one webhook for receiving all audit logs and another webhook for alert notifications. + +To forward alerts from {product-title} to any webhook receiver: + +. Set up a webhook URL to receive alerts. +. Use the webhook URL to set up notifications in {product-title}. +. Identify the policies you want to send notifications for, and update the notification settings for those policies. + +include::modules/webhook-configuring-acs.adoc[leveloffset=+1] + +:toolname: webhook +include::modules/configure-policy-notifications.adoc[leveloffset=+1] diff --git a/integration/integrate-using-short-lived-tokens.adoc b/integration/integrate-using-short-lived-tokens.adoc new file mode 100644 index 000000000000..3fd545419637 --- /dev/null +++ b/integration/integrate-using-short-lived-tokens.adoc @@ -0,0 +1,72 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-using-short-lived-tokens"] += Integrating RHACS using short-lived tokens +include::modules/common-attributes.adoc[] +:context: integrate-using-short-lived-tokens + +toc::[] + +[role="_abstract"] +With {rh-rhacs-first} you can authenticate against selected cloud provider APIs using short-lived tokens. {product-title-short} supports the following cloud provider integrations: + +* Amazon Web Services (AWS) using the Secure Token Service (STS) +* Google Cloud Platform (GCP) using workload identity federation +* Microsoft Azure using Microsoft Entra ID with managed identities + +{product-title-short} supports short-lived token integrations only when you install {product-title-short} on the following platforms: + +* Elastic Kubernetes Service (EKS) on AWS +* Google Kubernetes Engine (GKE) on GCP +* Microsoft Azure Kubernetes Service (AKS) +* {ocp} + +To activate short-lived authentication, you must establish trust between your Kubernetes or {ocp} cluster and your cloud provider. For EKS, GKE and AKS clusters, use the cloud provider metadata service. For {ocp} clusters, you need a publicly available OpenID Connect (OIDC) provider bucket containing the {ocp} service account signer key. + +[NOTE] +==== +You must establish trust with your cloud provider for every Central cluster that uses the short-lived token integration. However, if you use delegated scanning in combination with short-lived token image integrations, you must also establish trust for the Sensor cluster. +==== + +== Configuring AWS Secure Token Service + +{product-title-short} integrations can authenticate against Amazon Web Services using +the link:https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html[Secure Token Service]. You must configure `AssumeRole` with {product-title-short} before enabling the *Use container IAM role* option in integrations. + +[IMPORTANT] +==== +Verify that the AWS role associated with the {product-title-short} pod must have the IAM permissions required by the integration. For example, to set up a container role for integrating with the Elastic Container Registry, enable full read access to the registry. For more information about AWS IAM roles, see link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html[IAM roles]. +==== + +include::modules/aws-secure-token-service-eks.adoc[leveloffset=+2] +include::modules/aws-secure-token-service-openshift.adoc[leveloffset=+2] + +== Configuring Google workload identity federation + +{product-title-short} integrations can authenticate against the Google Cloud Platform by using link:https://cloud.google.com/iam/docs/workload-identity-federation[workload identities]. Select the *Use workload identity* option upon creation to enable workload identity authentication in a Google Cloud integration. + +[IMPORTANT] +==== +The Google service account associated with the {product-title-short} pod through the workload identity must have the IAM permissions required by the integration. For example, to set up a workload identity for integrating with Google Artifact Registry, connect a service account with the *roles/artifactregistry.reader* role. For more information about Google IAM roles see link:https://cloud.google.com/artifact-registry/docs/access-control[Configure roles and permissions]. +==== + +include::modules/google-workload-identity-federation-gke.adoc[leveloffset=+2] +include::modules/google-workload-identity-federation-openshift.adoc[leveloffset=+2] + +== Configuring Microsoft Entra ID federation + +{product-title-short} integrations can authenticate to Microsoft Azure by using managed or workload identities. +Select the *Use workload identity* checkbox during the creation of a new Microsoft Azure Container Registry (ACR) integration, if you want to enable authentication by using managed or workload identities in a Microsoft Azure integration. + +For more information about Azure managed identities, see link:https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview[What are managed identities for Azure resources?] (Microsoft Azure documentation). + +For more information about Azure workload identities, see link:https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation[Workload identity federation] (Microsoft Azure documentation). + +[IMPORTANT] +==== +The identity associated with the {product-title-short} pod through the workload identity must have the IAM permissions for the integration. For example, to set up a workload identity for integrating with Microsoft ACR, assign the *Reader* role over a scope that includes the registry. + +For more information about Microsoft Azure IAM roles, see link:https://learn.microsoft.com/en-us/azure/role-based-access-control/[Azure RBAC documentation] (Microsoft Azure documentation). +==== + +include::modules/azure-workload-identity-federation-aks.adoc[leveloffset=+2] +include::modules/azure-workload-identity-federation-openshift.adoc[leveloffset=+2] diff --git a/integration/integrate-using-syslog-protocol.adoc b/integration/integrate-using-syslog-protocol.adoc new file mode 100644 index 000000000000..544835dfdddd --- /dev/null +++ b/integration/integrate-using-syslog-protocol.adoc @@ -0,0 +1,26 @@ +[id="integrate-using-syslog-protocol"] += Integrating by using the syslog protocol +include::modules/common-attributes.adoc[] +:context: integrate-using-syslog-protocol + +toc::[] + +[role="_abstract"] +https://tools.ietf.org/html/rfc5424[Syslog] is an event logging protocol that applications use to send messages to a central location, such as a SIEM or a syslog collector, for data retention and security investigations. +With {product-title}, you can send alerts and audit events using the syslog protocol. + +[NOTE] +==== +* Forwarding events by using the syslog protocol requires the {product-title} version 3.0.52 or newer. +* When you use the syslog integration, {product-title} forwards both violation alerts that you configure and all audit events. +* Currently, {product-title} only supports *CEF* (Common Event Format). +==== + +The following steps represent a high-level workflow for integrating {product-title} with a syslog events receiver: + +. Set up a syslog events receiver to receive alerts. +. Use the receiver's address and port number to set up notifications in the {product-title}. + +After the configuration, {product-title} automatically sends all violations and audit events to the configured syslog receiver. + +include::modules/syslog-configuring-acs.adoc[leveloffset=+1] diff --git a/integration/integrate-with-amazon-s3.adoc b/integration/integrate-with-amazon-s3.adoc new file mode 100644 index 000000000000..102bb2206889 --- /dev/null +++ b/integration/integrate-with-amazon-s3.adoc @@ -0,0 +1,30 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-amazon-s3"] += Integrating with Amazon S3 +include::modules/common-attributes.adoc[] +:context: integrate-with-amazon-s3 + +toc::[] + +[role="_abstract"] +You can integrate {product-title} with link:https://aws.amazon.com/s3/[Amazon S3] to enable data backups. +You can use these backups for data restoration in the case of an infrastructure disaster or corrupt data. +After you integrate with Amazon S3, you can schedule daily or weekly backups and do manual on-demand backups. + +The backup includes the entire {product-title} database, which includes all configurations, resources, events, and certificates. +Make sure that backups are stored securely. + +[IMPORTANT] +==== +* If you are using {product-title} version 3.0.53 or older, the backup does not include certificates. +* If your Amazon S3 is part of an air-gapped environment, you must add your AWS root CA as a xref:../configuration/add-trusted-ca.adoc[trusted certificate authority] in {product-title}. +==== + +include::modules/amazon-s3-configuring-acs.adoc[leveloffset=+1] + +include::modules/perform-on-demand-backups-amazon-s3.adoc[leveloffset=+1] + +[role="_additional-resources"] +== Additional resources +* xref:../backup_and_restore/backing-up-acs.adoc#backing-up-red-hat-advanced-cluster-security-for-kubernetes[Backing up {product-title}] +* xref:../backup_and_restore/restore-acs.adoc#restoring-from-a-backup[Restoring from a backup] diff --git a/integration/integrate-with-ci-systems.adoc b/integration/integrate-with-ci-systems.adoc new file mode 100644 index 000000000000..0ad8e9380dfe --- /dev/null +++ b/integration/integrate-with-ci-systems.adoc @@ -0,0 +1,102 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-ci-systems"] += Integrating with CI systems +include::modules/common-attributes.adoc[] +:context: integrate-with-ci-systems + +toc::[] + +[role="_abstract"] + +{product-title} ({product-title-short}) integrates with a variety of continuous integration (CI) products. Before you deploy images, you can use {product-title-short} to apply build-time and deploy-time security rules to your images. + +After images are built and pushed to a registry, {product-title-short} integrates into CI pipelines. Pushing the image first allows developers to continue testing their artifacts while dealing with any policy violations alongside any other CI test failures, linter violations, or other problems. + +If possible, configure the version control system to block pull or merge requests from being merged if the build stage, which includes {product-title-short} checks, fails. + +The integration with your CI product functions by contacting your {product-title-short} installation to check whether the image complies with build-time policies you have configured. If there are policy violations, a detailed message is displayed on the console log, including the policy description, rationale, and remediation instructions. + +Each policy includes an optional enforcement setting. If you mark a policy for build-time enforcement, failure of that policy causes the client to exit with a nonzero error code. + +To integrate {product-title} with your CI system, follow these steps: + +. xref:../integration/integrate-with-ci-systems.adoc#configure-build-policies[Configure build policies]. +. xref:../integration/integrate-with-ci-systems.adoc#configure-registry-integration[Configure a registry integration]. +. xref:../integration/integrate-with-ci-systems.adoc#configure-access[Configure access] to your {product-title-short} instance. +. xref:../integration/integrate-with-ci-systems.adoc#integrate-with-your-ci-pipeline[Integrate with your CI pipeline]. + +[id="configure-build-policies"] +== Configuring build policies + +You can check {product-title-short} policies during builds. + +.Procedure + +. Configure policies that apply to the build time of the container lifecycle. +. Integrate with the registry that images are pushed to during the build. + +[role="_additional-resources"] +.Additional resources + +xref:../integration/integrate-with-image-registries.adoc#integrate-with-image-registries[Integrating with image registries] + +include::modules/integrate-ci-check-existing-build-phase-policies.adoc[leveloffset=+2] + +include::modules/create-new-system-policy.adoc[leveloffset=+2] + +include::modules/policy-enforcement-deploy.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources + +* xref:../operating/manage_security_policies/use-admission-controller-enforcement.adoc#use-admission-controller-enforcement[Using admission controller enforcement] + +[id="configure-registry-integration"] +== Configuring registry integration + +To scan images, you must provide {product-title} with access to the image registry you are using in your build pipeline. + +include::modules/check-for-existing-registry-integration.adoc[leveloffset=+2] + +[role="_additional-resources"] +==== Additional resources +* xref:../integration/integrate-with-image-registries.adoc#integrate-with-image-registries[Integrating with image registries] + +[id="configure-access"] +== Configuring access + +{product-title-short} provides the `roxctl` command-line interface (CLI) to make it easy to integrate {product-title-short} policies into your build pipeline. +The `roxctl` CLI prints detailed information about problems and how to fix them so that developers can maintain high standards in the early phases of the container lifecycle. + +To securely authenticate to the {product-title} API server, you must create an API token. + +include::modules/cli-authentication.adoc[leveloffset=+2] + +[id="install-roxctl-cli-binary"] +=== Installing the roxctl CLI by downloading the binary + +You can install the `roxctl` CLI to interact with {product-title} from a +command-line interface. You can install `roxctl` on Linux, Windows, or macOS. + +// Installing the CLI by downloading the binary +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+3] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+3] + +// Running the CLI by using a container image +include::modules/run-roxctl-from-container.adoc[leveloffset=+2] + +[id="integrate-with-your-ci-pipeline"] +== Integrating with your CI pipeline + +After you have finished these procedures, the next step is to integrate with your CI pipeline. + +Each CI system might require a slightly different configuration. + +[id="using-jenkins"] +=== Using Jenkins + +Use the link:https://plugins.jenkins.io/stackrox-container-image-scanner[StackRox Container Image Scanner] Jenkins plugin for integrating with Jenkins. +You can use this plugin in both Jenkins freestyle projects and pipelines. + +include::modules/integrate-circle-ci.adoc[leveloffset=+2] diff --git a/integration/integrate-with-cloud-management-platforms.adoc b/integration/integrate-with-cloud-management-platforms.adoc new file mode 100644 index 000000000000..4748fadf0151 --- /dev/null +++ b/integration/integrate-with-cloud-management-platforms.adoc @@ -0,0 +1,31 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-cloud-management-platforms"] += Integrating with cloud management platforms +include::modules/common-attributes.adoc[] +:context: integrate-with-cloud-management-platforms + +toc::[] + +[role="_abstract"] +You can integrate {rh-rhacs-first} with different cloud management platforms to discover potential clusters to secure. The cluster discovery aims to gain a detailed overview of the cluster assets already or not yet secured by {product-title-short}. + +The clusters discovered from a cloud management platform are accessible from the *Platform Configuration* -> *Clusters* -> *Discovered clusters* page. + +{product-title-short} matches the discovered clusters against already secured clusters. Based on the result of the matching, a discovered cluster has one of the following statuses: + +* *Secured*: The cluster is secured by {product-title-short}. +* *Unsecured*: The cluster is not secured by {product-title-short}. +* *Undetermined*: The metadata collected from secured clusters is not enough for a unique match. The cluster is either secured or unsecured. + +For successful cluster matching, ensure that the following conditions are met: + +* Sensors running on secured clusters have been updated to the latest version. +* link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS[Access to instance tags via the metadata service] has been granted for secured clusters running on AWS. Sensors require access to the AWS EC2 instance tags to determine the cluster status. + +You can integrate {product-title-short} with the following cloud management platforms: + +* link:https://paladincloud.io/[Paladin Cloud] +* link:https://console.redhat.com/openshift/[OpenShift Cluster Manager] + +include::modules/cloud-management-platforms-paladin-cloud.adoc[leveloffset=+1] +include::modules/cloud-management-platforms-ocm.adoc[leveloffset=+1] diff --git a/integration/integrate-with-email.adoc b/integration/integrate-with-email.adoc new file mode 100644 index 000000000000..486bd1513e3e --- /dev/null +++ b/integration/integrate-with-email.adoc @@ -0,0 +1,45 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-using-email"] += Integrating with email +include::modules/common-attributes.adoc[] +:context: integrate-with-email + +toc::[] + +[role="_abstract"] +With {rh-rhacs-first}, you can configure your existing email provider to send notifications about policy violations. +If you are using {rh-rhacscs-first}, you can use your existing email provider or the built-in email notifier to send email notifications. + +You can use the `Default recipient` field to forward alerts from {product-title-short} and the {product-title-managed-short} to an email address. +Otherwise, you can use annotations to define an audience and notify them about policy violations associated with a specific deployment or namespace. + +== Integrating with email on {product-title-short} + +You can use email as a notification method by forwarding alerts from {product-title-short}. + +include::modules/configure-acs-email.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage-vulnerabilities/vulnerability-management.adoc#vulnerability-management20-configure-report-delivery-destinations-schedule_acs-operating-manage-vulnerabilities[Configuring delivery destinations and scheduling] + +:toolname: Email +:context: rhacs +include::modules/configure-policy-notifications.adoc[leveloffset=+2] + +== Integrating with email on {product-title-managed-short} + +You can use your existing email provider or the built-in email notifier in {product-title-managed-short} to send email alerts about policy violations. + +* To use your own email provider, you must configure the email provider as described in the section xref:../integration/integrate-with-email.adoc#configure-acs-email_integrate-with-email[Configuring the email plugin]. +* To use the built-in email notifier, you must configure the {product-title-managed-short} email plugin. + +include::modules/configure-acscs-email.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage-vulnerabilities/vulnerability-management.adoc#vulnerability-management20-configure-report-delivery-destinations-schedule_acs-operating-manage-vulnerabilities[Configuring delivery destinations and scheduling] + +:toolname: {product-title-managed-short} Email +:context: rhacs-cloud-service +include::modules/configure-policy-notifications.adoc[leveloffset=+2] diff --git a/integration/integrate-with-google-cloud-scc.adoc b/integration/integrate-with-google-cloud-scc.adoc new file mode 100644 index 000000000000..da1616258459 --- /dev/null +++ b/integration/integrate-with-google-cloud-scc.adoc @@ -0,0 +1,23 @@ +[id="integrate-with-google-cloud-scc"] += Integrating with Google Cloud Security Command Center +include::modules/common-attributes.adoc[] +:context: integrate-with-google-cloud-scc + +toc::[] + +[role="_abstract"] +If you are using link:https://cloud.google.com/security-command-center/[Google Cloud Security Command Center] (Cloud SCC), you can forward alerts from {product-title} to Cloud SCC. +This guide explains how to integrate {product-title} with Cloud SCC. + +The following steps represent a high-level workflow for integrating {product-title} with Cloud SCC. + +. Register a new security source with Google Cloud. +. Provide the source ID and service account key to {product-title}. +. Identify the policies you want to send notifications for, and update the notification settings for those policies. + +include::modules/configure-google-cloud-scc.adoc[leveloffset=+1] + +include::modules/google-cloud-scc-configuring-acs.adoc[leveloffset=+1] + +:toolname: Google Cloud SCC +include::modules/configure-policy-notifications.adoc[leveloffset=+1] diff --git a/integration/integrate-with-google-cloud-storage.adoc b/integration/integrate-with-google-cloud-storage.adoc new file mode 100644 index 000000000000..1e3710b63110 --- /dev/null +++ b/integration/integrate-with-google-cloud-storage.adoc @@ -0,0 +1,29 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-google-cloud-storage"] += Integrating with Google Cloud Storage +include::modules/common-attributes.adoc[] +:context: integrate-with-google-cloud-storage + +toc::[] + +[role="_abstract"] +You can integrate with link:https://cloud.google.com/storage/[Google Cloud Storage (GCS)] to enable data backups. +You can use these backups for data restoration in the case of an infrastructure disaster, or corrupt data. +After you integrate with GCS, you can schedule daily or weekly backups and do manual on-demand backups. + +The backup includes the {product-title} entire database, which includes all configurations, resources, events, and certificates. +Make sure that backups are stored securely. + +[NOTE] +==== +If you are using {product-title} version 3.0.53 or older, the backup does not include certificates. +==== + +include::modules/google-cloud-storage-configuring-acs.adoc[leveloffset=+1] + +include::modules/perform-on-demand-backups-google-cloud-storage.adoc[leveloffset=+2] + +[role="_additional-resources"] +==== Additional resources +* xref:../backup_and_restore/backing-up-acs.adoc[Backing up {product-title}] +* xref:../backup_and_restore/restore-acs.adoc[Restoring from a backup] diff --git a/integration/integrate-with-image-registries.adoc b/integration/integrate-with-image-registries.adoc new file mode 100644 index 000000000000..1b77560b16f0 --- /dev/null +++ b/integration/integrate-with-image-registries.adoc @@ -0,0 +1,89 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-image-registries"] += Integrating with image registries +include::modules/common-attributes.adoc[] +:context: integrate-with-image-registries + +toc::[] + +[role="_abstract"] +{product-title} ({product-title-short}) integrates with a variety of image registries so that you can understand your images and apply security policies for image usage. + +When you integrate with image registries, you can view important image details, such as image creation date and Dockerfile details (including image layers). + +After you integrate {product-title-short} with your registry, you can scan images, view image components, and apply security policies to images before or after deployment. + +[NOTE] +==== +When you integrate with an image registry, {product-title-short} does not scan all images in your registry. {product-title-short} only scans the images when you: + +* Use the images in deployments +* Use the `roxctl` CLI to check images +* Use a continuous integration (CI) system to enforce security policies +==== + +You can integrate {product-title-short} with major image registries, including: + +* link:https://aws.amazon.com/ecr/[Amazon Elastic Container Registry (ECR)] +* link:https://hub.docker.com[Docker Hub] +* link:https://cloud.google.com/container-registry/[Google Container Registry (GCR)] +* link:https://cloud.google.com/artifact-registry/[Google Artifact Registry] +* link:https://www.ibm.com/cloud/container-registry[IBM Cloud Container Registry (ICR)] +* link:https://jfrog.com/artifactory/[JFrog Artifactory] +* link:https://azure.microsoft.com/en-au/services/container-registry/[Microsoft Azure Container Registry (ACR)] +* link:https://quay.io[Red{nbsp}Hat Quay] +* link:https://access.redhat.com/RegistryAuthentication#red-hat-registries-1[Red{nbsp}Hat container registries] +* link:https://www.sonatype.com/nexus-repository-sonatype[Sonatype Nexus] +* link:https://docs.github.com/en/packages[GitHub container registry (GHCR)] +* Any other registry that uses the link:https://docs.docker.com/registry/spec/api/[Docker Registry HTTP API] + +include::modules/automatic-configuration-image-registry.adoc[leveloffset=+1] + +[id="manual-configuration-image-registry"] +== Manually configuring image registries + +If you are using GCR, you must manually create image registry integrations. + +include::modules/manual-configuration-image-registry-ocp.adoc[leveloffset=+2] + +include::modules/manual-configuration-image-registry-ecr.adoc[leveloffset=+2] + +[id="use-assumerole-with-ecr"] +==== Using assumerole with Amazon ECR + +You can use link:https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole] to grant access to AWS resources without manually configuring each user's permissions. +Instead, you can define a role with the desired permissions so that the user is granted access to assume that role. `AssumeRole` enables you to grant, revoke, or otherwise generally manage more fine-grained permissions. + +include::modules/configuring-assumerole-with-iam.adoc[leveloffset=+4] + +include::modules/configuring-assumerole-without-iam.adoc[leveloffset=+4] + +include::modules/configuring-assumerole-acs.adoc[leveloffset=+4] + +include::modules/manual-configuration-image-registry-gcr.adoc[leveloffset=+2] + +include::modules/manual-configuration-image-registry-gar.adoc[leveloffset=+2] + +include::modules/manual-configuration-image-registry-acr.adoc[leveloffset=+2] + +include::modules/manual-configuration-image-registry-jfrog.adoc[leveloffset=+2] + +include::modules/manual-configuration-image-registry-qcr.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../integration/integrate-with-image-vulnerability-scanners.adoc#integrate-with-qcr-scanner_integrate-with-image-vulnerability-scanners[Integrating with Quay Container Registry to scan images] +* link:https://external-secrets.io/latest/api/generator/quay/[External Secrets Operator - Quay] + +include::modules/quay-keyless-eso.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../operating/examine-images-for-vulnerabilities.adoc#accessing-delegated-image-scanning_examine-images-for-vulnerabilities[Accessing delegated image scanning]. + +include::modules/manual-configuration-image-registry-ghcr.adoc[leveloffset=+2] + +include::modules/manual-configuration-image-registry-ibm.adoc[leveloffset=+2] + +include::modules/manual-configuration-image-registry-redhat.adoc[leveloffset=+2] diff --git a/integration/integrate-with-image-vulnerability-scanners.adoc b/integration/integrate-with-image-vulnerability-scanners.adoc new file mode 100644 index 000000000000..759c6c3768c9 --- /dev/null +++ b/integration/integrate-with-image-vulnerability-scanners.adoc @@ -0,0 +1,55 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-image-vulnerability-scanners"] += Integrating with image vulnerability scanners +include::modules/common-attributes.adoc[] +:context: integrate-with-image-vulnerability-scanners + +toc::[] + +[role="_abstract"] +{rh-rhacs-first} integrates with vulnerability scanners to enable you to import your container images and watch them for vulnerabilities. + +== Supported container image registries + +Red{nbsp}Hat supports the following container image registries: + +* Amazon Elastic Container Registry (ECR) +* Generic Docker registries (any generic Docker or Open Container Initiative-compliant image registries, for example, DockerHub, `gcr.io`, `mcr.microsoft.com`) +* Google Container Registry +* Google Artifact Registry +* IBM Cloud Container Registry +* JFrog Artifactory +* Microsoft Azure Container Registry (ACR) +* Red{nbsp}Hat Quay +* Red{nbsp}Hat registry (`registry.redhat.io`, `registry.access.redhat.com`) +* Sonatype Nexus + +This enhanced support gives you greater flexibility and choice in managing your container images in your preferred registry. + +[id="rhacs-scanners_{context}"] +== Scanners included in {product-title-short} + +* Scanner V4: Beginning with {product-title-short} version 4.4, a new scanner is introduced that is built on link:https://github.com/quay/claircore[Claircore], which also powers the link:https://github.com/quay/clair[Clair] scanner. Scanner V4 supports scanning of language and OS-specific image components. Scanner V4 is enabled by default during installation beginning in release 4.8. For more information about Scanner V4, including links to the installation documentation, see xref:../operating/examine-images-for-vulnerabilities.adoc#about-scanner-v4_examine-images-for-vulnerabilities[About {product-title-short} Scanner V4]. +* StackRox Scanner: This scanner was the default scanner in {product-title-short} before being replaced by Scanner V4. It originates from a fork of the Clair v2 open source scanner. If delegated scanning is configured and only the StackRox Scanner is installed on secured clusters, StackRox Scanner must also be enabled on the cluster where Central is installed or delegated scanning will not work. + +[id="alternative-scanners_{context}"] +== Alternative scanners + +* link:https://github.com/quay/clair[Clair]: Scanner V4 in {product-title-short} offers functionality provided by Claircore, which also powers the Clair V4 scanner. You can configure {product-title-short} to use Clair V4 instead of Scanner V4 by configuring an integration. +* link:https://cloud.google.com/artifact-analysis/docs/artifact-analysis[Google Artifact Analysis] +* link:https://quay.io[Red{nbsp}Hat Quay] + +[IMPORTANT] +==== +Scanner V4 is the preferred image vulnerability scanner to use with {product-title-short}, because only Scanner V4 provides full functionality and features. +==== + +If you use one of these alternative scanners in your DevOps workflow, you can use the {product-title-short} portal to configure an integration with your vulnerability scanner. After the integration, the {product-title-short} portal shows the image vulnerabilities and you can triage them easily. However, Scanner V4 provides functionality and features that alternative scanners might not offer. + +If multiple scanners are configured, {product-title-short} tries to use the non-StackRox/{product-title-short} and non-Clair scanners. If those scanners fail, {product-title-short} tries to use a configured Clair scanner. If that fails, {product-title-short} tries to use Scanner V4. If Scanner V4 is not enabled, {product-title-short} tries to use the StackRox Scanner. + +include::modules/integrate-with-clair.adoc[leveloffset=+1] + +include::modules/integrate-with-gcr-container-analysis.adoc[leveloffset=+1] + +include::modules/integrate-with-qcr-scanner.adoc[leveloffset=+1] diff --git a/integration/integrate-with-jira.adoc b/integration/integrate-with-jira.adoc new file mode 100644 index 000000000000..a00946a36ffa --- /dev/null +++ b/integration/integrate-with-jira.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-jira"] += Integrating with Jira +include::modules/common-attributes.adoc[] +:context: integrate-with-jira + +toc::[] + +[role="_abstract"] +If you are using Jira, you can forward alerts from {product-title} to Jira. + +The following steps represent a high-level workflow for integrating {product-title} with Jira: + +. Setup a user in Jira. +. Use the Jira URL, username, and password to integrate Jira with {product-title}. +. Identify policies for which you want to send notifications, and update the notification settings for those policies. + +include::modules/configure-jira.adoc[leveloffset=+1] + +include::modules/jira-configuring-acs.adoc[leveloffset=+1] + +include::modules/create-issues-in-different-jira-projects.adoc[leveloffset=+2] + +include::modules/configure-custom-priorities-in-jira.adoc[leveloffset=+2] + +[NOTE] +==== +If you get an error, follow the instructions in the xref:../integration/integrate-with-jira.adoc#troubleshoot-jira-integration_integrate-with-jira[Troubleshooting Jira integration] section. +==== + +:toolname: Jira +include::modules/configure-policy-notifications.adoc[leveloffset=+1] + +include::modules/troubleshoot-jira-integration.adoc[leveloffset=+1] diff --git a/integration/integrate-with-pagerduty.adoc b/integration/integrate-with-pagerduty.adoc new file mode 100644 index 000000000000..2645647af70d --- /dev/null +++ b/integration/integrate-with-pagerduty.adoc @@ -0,0 +1,22 @@ +[id="integrate-with-pagerduty"] += Integrating with PagerDuty +include::modules/common-attributes.adoc[] +:context: integrate-with-pagerduty + +toc::[] + +[role="_abstract"] +If you are using link:https://www.pagerduty.com/[PagerDuty], you can forward alerts from {product-title} to PagerDuty. + +The following steps represent a high-level workflow for integrating {product-title} with PagerDuty: + +. Add a new API service in PagerDuty and get the integration key. +. Use the integration key to set up notifications in {product-title}. +. Identify the policies you want to send notifications for, and update the notification settings for those policies. + +include::modules/configure-pagerduty.adoc[leveloffset=+1] + +include::modules/pagerduty-configuring-acs.adoc[leveloffset=+1] + +:toolname: PagerDuty +include::modules/configure-policy-notifications.adoc[leveloffset=+1] diff --git a/integration/integrate-with-qradar.adoc b/integration/integrate-with-qradar.adoc new file mode 100644 index 000000000000..82c15fb04110 --- /dev/null +++ b/integration/integrate-with-qradar.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-qradar"] += Integrating with QRadar +include::modules/common-attributes.adoc[] +:context: integrate-with-qradar + +toc::[] + +[role="_abstract"] +You can configure {product-title} to send events to QRadar by configuring a generic webhook integration in {product-title-short}. + +The following steps represent a high-level workflow for integrating {product-title-short} with QRadar: + +. In {product-title-short}: +.. Configure the generic webhook. ++ +[NOTE] +==== +When configuring the integration in {product-title-short}, in the *Endpoint* field, use the following example as a guide: `:`. +==== +.. Identify policies for which you want to send notifications, and update the notification settings for those policies. +. If QRadar does not automatically detect the log source, add an {product-title-short} log source on the QRadar Console. For more information on configuring QRadar and {product-title-short}, see the link:https://www.ibm.com/docs/en/dsm?topic=configuration-red-hat-advanced-cluster-security-kubernetes[Red{nbsp}Hat Advanced Cluster Security for Kubernetes] IBM resource. + +include::modules/webhook-configuring-acs.adoc[leveloffset=+1] + +:toolname: webhook +include::modules/configure-policy-notifications.adoc[leveloffset=+1] \ No newline at end of file diff --git a/integration/integrate-with-s3-api-compatible-services.adoc b/integration/integrate-with-s3-api-compatible-services.adoc new file mode 100644 index 000000000000..d0616afff85f --- /dev/null +++ b/integration/integrate-with-s3-api-compatible-services.adoc @@ -0,0 +1,30 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-s3-api-compatible-services"] += Integrating with S3 API compatible services +include::modules/common-attributes.adoc[] +:context: integrate-with-s3-api-compatible-services + +toc::[] + +[role="_abstract"] +{product-title} can be integrated with S3 API compatible services to enable data backups. +These backups can be used for data restoration in the case of an infrastructure disaster or corrupt data. +After integrating with the S3 API compatible provider, you can schedule daily or weekly backups and do manual on-demand backups. + +The backup includes the entire {product-title-short} database, which includes all configurations, resources, events, and certificates. +Make sure that backups are stored securely. + +[IMPORTANT] +==== +* To back up to Amazon S3, use the dedicated xref:integrate-with-amazon-s3.adoc#integrate-with-amazon-s3[Amazon S3] integration to ensure the best compatibility. +* Red Hat does not test this integration with every S3 API compatible provider, so the integration is not guaranteed to work with all providers. +==== + +include::modules/s3-api-compatible-services-configuring-acs.adoc[leveloffset=+1] + +include::modules/perform-on-demand-backups-s3-api-compatible-services.adoc[leveloffset=+1] + +[role="_additional-resources"] +== Additional resources +* xref:../backup_and_restore/backing-up-acs.adoc#backing-up-red-hat-advanced-cluster-security-for-kubernetes[Backing up {product-title}] +* xref:../backup_and_restore/restore-acs.adoc#restoring-from-a-backup[Restoring from a backup] diff --git a/integration/integrate-with-servicenow.adoc b/integration/integrate-with-servicenow.adoc new file mode 100644 index 000000000000..8f4b74f06df1 --- /dev/null +++ b/integration/integrate-with-servicenow.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-servicenow"] += Integrating with ServiceNow +include::modules/common-attributes.adoc[] +:context: integrate-with-servicenow + +toc::[] + +[role="_abstract"] +You can configure {product-title} to send events to ServiceNow by configuring a generic webhook integration in {product-title-short}. + +The following steps represent a high-level workflow for integrating {product-title-short} with ServiceNow: + +. In ServiceNow, configure a REST API endpoint to use in {product-title-short}. For more information that includes steps for ServiceNow configuration, see link:https://www.redhat.com/en/blog/how-integrate-red-hat-advanced-cluster-security-kubernetes-servicenow[How to integrate {product-title} with ServiceNow]. +. In {product-title-short}: +.. Configure the generic webhook. +.. Identify policies for which you want to send notifications, and update the notification settings for those policies. + +include::modules/webhook-configuring-acs.adoc[leveloffset=+1] + +:toolname: webhook +include::modules/configure-policy-notifications.adoc[leveloffset=+1] \ No newline at end of file diff --git a/integration/integrate-with-slack.adoc b/integration/integrate-with-slack.adoc new file mode 100644 index 000000000000..a31b18319e85 --- /dev/null +++ b/integration/integrate-with-slack.adoc @@ -0,0 +1,24 @@ +[id="integrate-with-slack"] += Integrating with Slack +include::modules/common-attributes.adoc[] +:context: integrate-with-slack + +toc::[] + +[role="_abstract"] +If you are using Slack, you can forward alerts from {product-title} to Slack. + +The following steps represent a high-level workflow for integrating {product-title} with Slack: + +. Create a new Slack app, enable incoming webhooks, and get a webhook URL. +. Use the webhook URL to integrate Slack with {product-title}. +. Identify policies for which you want to send notifications, and update the notification settings for those policies. + +include::modules/configure-slack.adoc[leveloffset=+1] + +include::modules/send-alerts-to-different-slack-channels.adoc[leveloffset=+2] + +include::modules/slack-configuring-acs.adoc[leveloffset=+1] + +:toolname: Slack +include::modules/configure-policy-notifications.adoc[leveloffset=+1] diff --git a/integration/integrate-with-splunk.adoc b/integration/integrate-with-splunk.adoc new file mode 100644 index 000000000000..83ea64c81536 --- /dev/null +++ b/integration/integrate-with-splunk.adoc @@ -0,0 +1,57 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrate-with-splunk"] += Integrating with Splunk +include::modules/common-attributes.adoc[] +:context: integrate-with-splunk + +toc::[] + +[role="_abstract"] +If you are using link:https://www.splunk.com/[Splunk], you can forward alerts from {product-title} to Splunk and view the violations, vulnerability detection, and compliance related data from within Splunk. + +[IMPORTANT] +==== +Currently, Splunk integration is not supported on {ibm-power}(`ppc64le`) and {ibm-z}(`s390x`). +==== + +Depending on your use case, you can integrate {product-title} with Splunk by using the following ways: + +* By xref:../integration/integrate-with-splunk.adoc#integrate-splunk-http-event-collector[using an HTTP event collector] in Splunk: +** Use the event collector option to forward alerts and audit log data. +* By xref:../integration/integrate-with-splunk.adoc#integrate-splunk-add-on[using the {product-title} add-on]: +** Use the add-on to pull the violations, vulnerability detection, and compliance data into Splunk. + +You can use one or both of these integration options to integrate the {product-title} with Splunk. + +[id="integrate-splunk-http-event-collector"] +== Using the HTTP event collector + +You can forward alerts from {product-title} to Splunk by using an HTTP event collector. + +To integrate {product-title} with Splunk by using the HTTP event collector, follow these steps: + +. Add a new HTTP event collector in Splunk and get the token value. +. Use the token value to set up notifications in {product-title}. +. Identify policies for which you want to send notifications, and update the notification settings for those policies. + +include::modules/add-http-event-collector-splunk.adoc[leveloffset=+2] + +include::modules/integrate-splunk-enable-http-event-collector.adoc[leveloffset=+3] + +include::modules/splunk-configuring-acs.adoc[leveloffset=+2] + +:toolname: Splunk +include::modules/configure-policy-notifications.adoc[leveloffset=+2] + +[id="integrate-splunk-add-on"] +== Using the {product-title} add-on + +You can use the {product-title} add-on to forward the vulnerability detection and compliance related data from the {product-title} to Splunk. + +Generate an API token with `read` permission for all resources in {product-title} and then use that token to install and configure the add-on. + +include::modules/install-and-configure-the-splunk-add-on.adoc[leveloffset=+2] + +include::modules/update-the-splunk-add-on.adoc[leveloffset=+2] + +include::modules/troubleshoot-the-splunk-add-on.adoc[leveloffset=+2] diff --git a/integration/integrate-with-sumologic.adoc b/integration/integrate-with-sumologic.adoc new file mode 100644 index 000000000000..5e4167f7548e --- /dev/null +++ b/integration/integrate-with-sumologic.adoc @@ -0,0 +1,24 @@ +[id="integrate-with-sumologic"] += Integrating with Sumo Logic +include::modules/common-attributes.adoc[] +:context: integrate-with-sumologic + +toc::[] + +[role="_abstract"] +If you are using link:https://www.sumologic.com/[Sumo Logic], you can forward alerts from {product-title} to Sumo Logic. + +The following steps represent a high-level workflow for integrating {product-title} with Sumo Logic: + +. Add a new Custom App in Sumo Logic, set the HTTP source, and get the HTTP URL. +. Use the HTTP URL to integrate Sumo Logic with {product-title}. +. Identify the policies you want to send notifications for, and update the notification settings for those policies. + +include::modules/configure-sumologic.adoc[leveloffset=+1] + +include::modules/sumologic-configuring-acs.adoc[leveloffset=+1] + +:toolname: Sumo Logic +include::modules/configure-policy-notifications.adoc[leveloffset=+1] + +include::modules/view-alerts-in-sumo-logic.adoc[leveloffset=+1] diff --git a/integration/integrating-with-microsoft-sentinel-notifier.adoc b/integration/integrating-with-microsoft-sentinel-notifier.adoc new file mode 100644 index 000000000000..fdff662c1771 --- /dev/null +++ b/integration/integrating-with-microsoft-sentinel-notifier.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: ASSEMBLY +[id="integrating-with-microsoft-sentinel-notifier"] += Integrating with Microsoft Sentinel notifier +include::modules/common-attributes.adoc[] +:context: integrate-with-sentinel + +toc::[] + +Microsoft Sentinel is a security information and event management (SIEM) solution which acts on {rh-rhacs-first} alerts and audit logs. + +//Viewing the log analytics to detect threats +include::modules/viewing-the-log-analytics-to-detect-threats.adoc[leveloffset=+1] \ No newline at end of file diff --git a/applications/application_life_cycle_management/modules b/integration/modules similarity index 100% rename from applications/application_life_cycle_management/modules rename to integration/modules diff --git a/integration/snippets b/integration/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/integration/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/jaeger/images b/jaeger/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/jaeger/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/jaeger/jaeger_arch/rhbjaeger-architecture.adoc b/jaeger/jaeger_arch/rhbjaeger-architecture.adoc deleted file mode 100644 index ccd4920c65f2..000000000000 --- a/jaeger/jaeger_arch/rhbjaeger-architecture.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id="jaeger-architecture"] -= Jaeger architecture -include::modules/jaeger-document-attributes.adoc[] -:context: jaeger-architecture - -toc::[] - -Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate to produce a response. -Jaeger lets you perform distributed tracing, which records the path of a request through various microservices that make up an application. - -_Distributed tracing_ is a technique that is used to tie the information about different units of work together — usually executed in different processes or hosts — to understand a whole chain of events in a distributed transaction. -Developers can visualize call flows in large microservice architectures with distributed tracing. -It's valuable for understanding serialization, parallelism, and sources of latency. - -Jaeger records the execution of individual requests across the whole stack of microservices, and presents them as traces. A _trace_ is a data/execution path through the system. An end-to-end trace is comprised of one or more spans. - -A _span_ represents a logical unit of work in Jaeger that has an operation name, the start time of the operation, and the duration, as well as potentially tags and logs. Spans may be nested and ordered to model causal relationships. - -// The following include statements pull in the module files that comprise the assembly. - -include::modules/jaeger-product-overview.adoc[leveloffset=+1] - -include::modules/jaeger-features.adoc[leveloffset=+1] - -include::modules/jaeger-architecture.adoc[leveloffset=+1] - -//// -TODO -WRITE more detailed component docs - -include::modules/jaeger-client-java.adoc[leveloffset=+1] - -include::modules/jaeger-agent.adoc[leveloffset=+1] - -include::modules/jaeger-collector.adoc[leveloffset=+1] - -include::modules/jaeger-data-store.adoc[leveloffset=+1] - -include::modules/jaeger-query.adoc[leveloffset=+1] - -include::modules/jaeger-ingester.adoc[leveloffset=+1] - -include::modules/jaeger-console.adoc[leveloffset=+1] -//// diff --git a/jaeger/jaeger_config/serverless-jaeger-integration.adoc b/jaeger/jaeger_config/serverless-jaeger-integration.adoc deleted file mode 100644 index c8ab3ef6a382..000000000000 --- a/jaeger/jaeger_config/serverless-jaeger-integration.adoc +++ /dev/null @@ -1,11 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-jaeger-integration"] -= Integrating Jaeger with serverless applications using OpenShift Serverless -:context: serverless-jaeger-integration -include::modules/common-attributes.adoc[] - -toc::[] - -Using Jaeger with xref:../../serverless/serverless-getting-started.adoc#serverless-getting-started[{ServerlessProductName}] allows you to enable distributed tracing for your serverless applications on {product-title}. - -include::modules/serverless-jaeger-config.adoc[leveloffset=+1] diff --git a/jaeger/jaeger_install/rhbjaeger-deploying.adoc b/jaeger/jaeger_install/rhbjaeger-deploying.adoc deleted file mode 100644 index 195f3772d449..000000000000 --- a/jaeger/jaeger_install/rhbjaeger-deploying.adoc +++ /dev/null @@ -1,77 +0,0 @@ -[id="deploying-jaeger"] -= Configuring and Deploying Jaeger -include::modules/jaeger-document-attributes.adoc[] -:context: jaeger-deploying - -toc::[] - -The Jaeger Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to be used when creating and deploying the Jaeger resources. You can either install the default configuration or modify the file to better suit your business requirements. - -Jaeger has predefined deployment strategies. You specify a deployment strategy in the custom resource file. When you create a Jaeger instance the Operator uses this configuration file to create the objects necessary for the deployment. - -.Jaeger custom resource file showing deployment strategy -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: simple-prod -spec: - strategy: production <1> ----- - -<1> The Jaeger Operator currently supports the following deployment strategies: - -* *allInOne* (Default) - This strategy is intended for development, testing, and demo purposes; it is not intended for production use. The main backend components, Agent, Collector and Query service, are all packaged into a single executable which is configured (by default) to use in-memory storage. -+ -[NOTE] -==== -In-memory storage is not persistent, which means that if the Jaeger instance shuts down, restarts, or is replaced, that your trace data will be lost. And in-memory storage cannot be scaled, since each pod has its own memory. For persistent storage, you must use the `production` or `streaming` strategies, which use Elasticsearch as the default storage. -==== - -* *production* - The production strategy is intended for production environments, where long term storage of trace data is important, as well as a more scalable and highly available architecture is required. Each of the backend components is therefore deployed separately. The Agent can be injected as a sidecar on the instrumented application. The Query and Collector services are configured with a supported storage type - currently Elasticsearch. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes. - -* *streaming* - The streaming strategy is designed to augment the production strategy by providing a streaming capability that effectively sits between the Collector and the backend storage (Elasticsearch). This provides the benefit of reducing the pressure on the backend storage, under high load situations, and enables other trace post-processing capabilities to tap into the real time span data directly from the streaming platform (https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/using_amq_streams_on_openshift/index[AMQ Streams]/ https://kafka.apache.org/documentation/[Kafka]). -+ -[NOTE] -==== -The streaming strategy requires an additional Red Hat subscription for AMQ Streams. -==== - -[NOTE] -==== -There are two ways to install and use Jaeger, as part of a service mesh or as a stand alone component. If you have installed Jaeger as part of Red Hat OpenShift Service Mesh, you can configure and deploy Jaeger as part of the xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-custom-resources-v2x[ServiceMeshControlPlane] or configure Jaeger and then xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-deploying-jaeger-streaming[reference your Jaeger configuration in the SMCP]. - -==== - -// The following include statements pull in the module files that comprise the assembly. - -include::modules/jaeger-deploy-default.adoc[leveloffset=+1] - -include::modules/jaeger-deploy-production-es.adoc[leveloffset=1] - -include::modules/jaeger-deploy-streaming.adoc[leveloffset=1] - -[id="customizing-jaeger-deployment"] -== Customizing Jaeger deployment - -include::modules/jaeger-config-default.adoc[leveloffset=+2] - -include::modules/jaeger-config-collector.adoc[leveloffset=+2] - -include::modules/jaeger-config-sampling.adoc[leveloffset=+2] - -include::modules/jaeger-config-storage.adoc[leveloffset=+2] - -include::modules/jaeger-config-query.adoc[leveloffset=+2] - -include::modules/jaeger-config-ingester.adoc[leveloffset=+2] - -[id="injecting-sidecars"] -== Injecting sidecars - -{ProductName} relies on a proxy sidecar within the application’s pod to provide the agent. The Jaeger Operator can inject Jaeger Agent sidecars into Deployment workloads. You can enable automatic sidecar injection or manage it manually. - -include::modules/jaeger-sidecar-automatic.adoc[leveloffset=2] - -include::modules/jaeger-sidecar-manual.adoc[leveloffset=2] diff --git a/jaeger/jaeger_install/rhbjaeger-installation.adoc b/jaeger/jaeger_install/rhbjaeger-installation.adoc deleted file mode 100644 index 749e204ea5a1..000000000000 --- a/jaeger/jaeger_install/rhbjaeger-installation.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id="installing-jaeger"] -= Installing Jaeger -include::modules/jaeger-document-attributes.adoc[] -:context: jaeger-install - -toc::[] - -You can install Jaeger on {product-title} in either of two ways: - -* You can install Jaeger as part of Red Hat OpenShift Service Mesh. Jaeger is included by default in the Service Mesh installation. To install Jaeger as part of a service mesh, follow the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Red Hat Service Mesh Installation] instructions. - -* If you do not want to install a service mesh, you can use the Jaeger Operator to install the Red Hat build of Jaeger by itself. To install Jaeger without a service mesh, use the following instructions. - - -== Prerequisites - -Before you can install {ProductName}, review the installation activities, and ensure that you meet the prerequisites: - -* Possess an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information. - -* Review the xref:../../architecture/architecture-installation.adoc#installation-overview_architecture-installation[{product-title} {product-version} overview]. -* Install {product-title} {product-version}. - -** xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Install {product-title} {product-version} on AWS] -** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Install {product-title} {product-version} on user-provisioned AWS] -** xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install {product-title} {product-version} on bare metal] -** xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Install {product-title} {product-version} on vSphere] -* Install the version of the {product-title} command line utility (the `oc` client tool) that matches your {product-title} version and add it to your path. - -* An account with the `cluster-admin` role. - -// The following include statements pull in the module files that comprise the assembly. - -include::modules/jaeger-install-overview.adoc[leveloffset=+1] - -include::modules/jaeger-install-elasticsearch.adoc[leveloffset=+1] - -include::modules/jaeger-install.adoc[leveloffset=+1] - -//// -== Next steps -* xref:../../jaeger/jaeger_install/rhbj-deploying.adoc#jaeger-deploying[Deploy {ProductName}]. -//// diff --git a/jaeger/jaeger_install/rhbjaeger-removing.adoc b/jaeger/jaeger_install/rhbjaeger-removing.adoc deleted file mode 100644 index eaa8aeebc80d..000000000000 --- a/jaeger/jaeger_install/rhbjaeger-removing.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="removing-jaeger"] -= Removing Jaeger -include::modules/jaeger-document-attributes.adoc[] -:context: removing-jaeger - -toc::[] - -The steps for removing Jaeger from an {product-title} cluster are as follows: - -. Shut down any Jaeger pods. -. Remove any Jaeger instances. -. Remove the Jaeger Operator. - -include::modules/jaeger-removing-instance.adoc[leveloffset=+1] - -include::modules/jaeger-removing-instance-cli.adoc[leveloffset=+1] - - -== Removing the Jaeger Operator - -.Procedure - -. Follow the instructions for xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster]. - -* Remove the Jaeger Operator. - -* After the Jaeger Operator has been removed, if appropriate, remove the OpenShift Elasticsearch Operator. diff --git a/jaeger/jaeger_install/rhbjaeger-updating.adoc b/jaeger/jaeger_install/rhbjaeger-updating.adoc deleted file mode 100644 index 421eca48c71d..000000000000 --- a/jaeger/jaeger_install/rhbjaeger-updating.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="upgrading-jaeger"] -= Upgrading Jaeger -include::modules/jaeger-document-attributes.adoc[] -:context: upgrading-jaeger - -toc::[] - -The Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. The OLM runs by default in {product-title}. -The OLM queries for available Operators as well as upgrades for installed Operators. -For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager] documentation. - -The update approach used by the Jaeger Operator upgrades the managed Jaeger instances to the version associated with the Operator. Whenever a new version of the Jaeger Operator is installed, all the Jaeger application instances managed by the Operator will be upgraded to the Operator’s version. For example, if version 1.10 is installed (both Operator and backend components) and the Operator is upgraded to version 1.11, then as soon as the Operator upgrade has completed, the Operator will scan for running Jaeger instances and upgrade them to 1.11 as well. diff --git a/jaeger/rhbjaeger-release-notes.adoc b/jaeger/rhbjaeger-release-notes.adoc deleted file mode 100644 index 986077af4f6d..000000000000 --- a/jaeger/rhbjaeger-release-notes.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="jaeger-release-notes"] -= Jaeger Release Notes -include::modules/jaeger-document-attributes.adoc[] -:context: jaeger-release-notes - -toc::[] - -// The following include statements pull in the module files that comprise the assembly. - -include::modules/jaeger-product-overview.adoc[leveloffset=+1] - -== Making open source more inclusive - -Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see link:https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language[our CTO Chris Wright's message]. - -include::modules/support.adoc[leveloffset=+1] - -include::modules/jaeger-rn-new-features.adoc[leveloffset=+1] - -include::modules/jaeger-rn-technology-preview.adoc[leveloffset=+1] - -include::modules/jaeger-rn-known-issues.adoc[leveloffset=+1] - -include::modules/jaeger-rn-fixed-issues.adoc[leveloffset=+1] diff --git a/logging/cluster-logging-dashboards.adoc b/logging/cluster-logging-dashboards.adoc deleted file mode 100644 index efbedabc581b..000000000000 --- a/logging/cluster-logging-dashboards.adoc +++ /dev/null @@ -1,30 +0,0 @@ -:context: cluster-logging-dashboards -[id="cluster-logging-dashboards"] -= Viewing cluster dashboards -include::modules/common-attributes.adoc[] - -toc::[] - -The *Logging/Elasticsearch Nodes* and *Openshift Logging* dashboards in the {product-title} web console show in-depth details about your Elasticsearch instance and the individual Elasticsearch nodes that you can use to prevent and diagnose problems. - -The *OpenShift Logging* dashboard contains charts that show details about your Elasticsearch instance at a cluster level, including cluster resources, garbage collection, shards in the cluster, and Fluentd statistics. - -The *Logging/Elasticsearch Nodes* dashboard contains charts that show details about your Elasticsearch instance, many at node level, including details on indexing, shards, resources, and so forth. - -[NOTE] -==== -For more detailed data, click the *Grafana UI* link in a dashboard to launch the Grafana dashboard. Grafana is shipped with xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[OpenShift cluster monitoring]. -==== - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-dashboards-access.adoc[leveloffset=+1] - -For information on the dashboard charts, see xref:../logging/cluster-logging-dashboards.html#cluster-logging-dashboards-logging_cluster-logging-dashboards[About the OpenShift Logging dashboard] and xref:../logging/cluster-logging-dashboards.html#cluster-logging-dashboards-es_cluster-logging-dashboards[About the Logging/Elastisearch Nodes dashboard]. - -include::modules/cluster-logging-dashboards-logging.adoc[leveloffset=+1] -include::modules/cluster-logging-dashboards-es.adoc[leveloffset=+1] - diff --git a/logging/cluster-logging-deploying.adoc b/logging/cluster-logging-deploying.adoc deleted file mode 100644 index 681d12f825c3..000000000000 --- a/logging/cluster-logging-deploying.adoc +++ /dev/null @@ -1,49 +0,0 @@ -:context: cluster-logging-deploying -[id="cluster-logging-deploying"] -= Installing OpenShift Logging -include::modules/common-attributes.adoc[] - -toc::[] - - -You can install OpenShift Logging by deploying -the OpenShift Elasticsearch and Cluster Logging Operators. The OpenShift Elasticsearch Operator -creates and manages the Elasticsearch cluster used by OpenShift Logging. -The Cluster Logging Operator creates and manages the components of the logging stack. - -The process for deploying OpenShift Logging to {product-title} involves: - -* Reviewing the xref:../logging/config/cluster-logging-storage-considerations#cluster-logging-storage[OpenShift Logging storage considerations]. - -* Installing the OpenShift Elasticsearch Operator and Cluster Logging Operator using the {product-title} xref:../logging/cluster-logging-deploying.adoc#cluster-logging-deploy-console_cluster-logging-deploying[web console] or xref:../logging/cluster-logging-deploying.adoc#cluster-logging-deploy-cli_cluster-logging-deploying[CLI]. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-deploy-console.adoc[leveloffset=+1] - -== Post-installation tasks - -If you plan to use Kibana, you must xref:#cluster-logging-visualizer-indices_cluster-logging-deploying[manually create your Kibana index patterns and visualizations] to explore and visualize data in Kibana. - -include::modules/cluster-logging-deploy-cli.adoc[leveloffset=+1] - -== Post-installation tasks - -If you plan to use Kibana, you must xref:#cluster-logging-visualizer-indices_cluster-logging-deploying[manually create your Kibana index patterns and visualizations] to explore and visualize data in Kibana. - -include::modules/cluster-logging-visualizer-indices.adoc[leveloffset=+2] - -include::modules/cluster-logging-deploy-multitenant.adoc[leveloffset=+2] - -// include::modules/cluster-logging-deploy-memory.adoc[leveloffset=+1] - -// include::modules/cluster-logging-deploy-certificates.adoc[leveloffset=+1] - -// include::modules/cluster-logging-deploy-label.adoc[leveloffset=+1] - -== Additional resources - -* For more information on installing Operators, see xref:../operators/admin/olm-adding-operators-to-cluster.adoc#olm-installing-operators-from-operatorhub_olm-adding-operators-to-a-cluster[Installing Operators from the OperatorHub]. diff --git a/logging/cluster-logging-eventrouter.adoc b/logging/cluster-logging-eventrouter.adoc deleted file mode 100644 index 5e116049668d..000000000000 --- a/logging/cluster-logging-eventrouter.adoc +++ /dev/null @@ -1,22 +0,0 @@ -:context: cluster-logging-curator -[id="cluster-logging-eventrouter"] -= Collecting and storing Kubernetes events -include::modules/common-attributes.adoc[] - -toc::[] - -The {product-title} Event Router is a pod that watches Kubernetes events and logs them for collection by OpenShift Logging. You must manually deploy the Event Router. - -The Event Router collects events from all projects and writes them to `STDOUT`. Fluentd collects those events and forwards them into the {product-title} Elasticsearch instance. Elasticsearch indexes the events to the `infra` index. - -[IMPORTANT] -==== -The Event Router adds additional load to Fluentd and can impact the number of other log messages that can be processed. -==== - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-eventrouter-deploy.adoc[leveloffset=+1] diff --git a/logging/cluster-logging-exported-fields.adoc b/logging/cluster-logging-exported-fields.adoc deleted file mode 100644 index 497464d11e24..000000000000 --- a/logging/cluster-logging-exported-fields.adoc +++ /dev/null @@ -1,49 +0,0 @@ -:context: cluster-logging-exported-fields -[id="cluster-logging-exported-fields"] -= Exported fields -include::modules/common-attributes.adoc[] - -toc::[] - - - -These are the fields exported by the logging system and available for searching -from Elasticsearch and Kibana. Use the full, dotted field name when searching. -For example, for an Elasticsearch */_search URL*, to look for a Kubernetes pod name, -use `/_search/q=kubernetes.pod_name:name-of-my-pod`. - -The following sections describe fields that may not be present in your logging store. -Not all of these fields are present in every record. -The fields are grouped in the following categories: - -* `exported-fields-Default` -* `exported-fields-systemd` -* `exported-fields-kubernetes` -* `exported-fields-pipeline_metadata` -* `exported-fields-ovirt` -* `exported-fields-aushape` -* `exported-fields-tlog` - -// * `exported-fields-rsyslog` - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-exported-fields-default.adoc[leveloffset=+1] - -//modules/cluster-logging-exported-fields-rsyslog.adoc[leveloffset=+1] - -include::modules/cluster-logging-exported-fields-systemd.adoc[leveloffset=+1] - -include::modules/cluster-logging-exported-fields-kubernetes.adoc[leveloffset=+1] - -include::modules/cluster-logging-exported-fields-container.adoc[leveloffset=+1] - -include::modules/cluster-logging-exported-fields-ovirt.adoc[leveloffset=+1] - -include::modules/cluster-logging-exported-fields-aushape.adoc[leveloffset=+1] - -include::modules/cluster-logging-exported-fields-tlog.adoc[leveloffset=+1] diff --git a/logging/cluster-logging-external.adoc b/logging/cluster-logging-external.adoc deleted file mode 100644 index a1c7298e47e3..000000000000 --- a/logging/cluster-logging-external.adoc +++ /dev/null @@ -1,39 +0,0 @@ -:context: cluster-logging-external -[id="cluster-logging-external"] -= Forwarding logs to third party systems -include::modules/common-attributes.adoc[] - -toc::[] - -By default, OpenShift Logging sends container and infrastructure logs to the default internal Elasticsearch log store defined in the `ClusterLogging` custom resource. However, it does not send audit logs to the internal store because it does not provide secure storage. If this default configuration meets your needs, you do not need to configure the Log Forwarding API. - -To send logs to other log aggregators, you use the {product-title} Log Forwarding API. This API enables you to send container, infrastructure, and audit logs to specific endpoints within or outside your cluster. You can send different types of logs to various systems, so different individuals can access each type. You can also enable TLS support to send logs securely, as required by your organization. - -[NOTE] -==== -To send audit logs to the internal log store, use the Log Forwarding API as described in xref:../logging/config/cluster-logging-log-store.adoc#cluster-logging-elasticsearch-audit_cluster-logging-store[Forward audit logs to the log store]. -==== - -When you forward logs externally, the Cluster Logging Operator creates or modifies a Fluentd config map to send logs using your desired protocols. You are responsible for configuring the protocol on the external log aggregator. - -Alternatively, you can create a config map to use the xref:../logging/cluster-logging-external.html#cluster-logging-collector-legacy-fluentd_cluster-logging-external[Fluentd *forward* protocol] or the xref:../logging/cluster-logging-external.html#cluster-logging-collector-legacy-syslog_cluster-logging-external[syslog protocol] to send logs to external systems. However, these methods for forwarding logs are deprecated in {product-title} and will be removed in a future release. - -[IMPORTANT] -==== -You cannot use the config map methods and the Log Forwarding API in the same cluster. -==== - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-collector-log-forwarding-about.adoc[leveloffset=+1] -include::modules/cluster-logging-collector-log-forwarding-supported-plugins.adoc[leveloffset=+1] -include::modules/cluster-logging-collector-log-forward-es.adoc[leveloffset=+1] -include::modules/cluster-logging-collector-log-forward-fluentd.adoc[leveloffset=+1] -include::modules/cluster-logging-collector-log-forward-syslog.adoc[leveloffset=+1] -include::modules/cluster-logging-collector-log-forward-kafka.adoc[leveloffset=+1] -include::modules/cluster-logging-collector-log-forward-project.adoc[leveloffset=+1] -include::modules/cluster-logging-collector-legacy-fluentd.adoc[leveloffset=+1] -include::modules/cluster-logging-collector-legacy-syslog.adoc[leveloffset=+1] diff --git a/logging/cluster-logging-release-notes.adoc b/logging/cluster-logging-release-notes.adoc deleted file mode 100644 index b096ab97da89..000000000000 --- a/logging/cluster-logging-release-notes.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="cluster-logging-release-notes"] -= Release notes for Red Hat OpenShift Logging 5.0 -include::modules/cluster-logging-document-attributes.adoc[] -:context: cluster-logging-release-notes-v5x - -toc::[] - -[id="openshift-logging-5-0-about-this-release"] -== About this release - -The following advisories are available for {ProductName} 5.0: - -* link:https://access.redhat.com/errata/RHBA-2021:0652[RHBA-2021:0652 Errata Advisory for Openshift Logging 5.0.0] -* link:https://access.redhat.com/errata/RHBA-2021:0963[RHBA-2021:0963 for OpenShift Logging Bug Fix Release (5.0.1)] - -[id="openshift-logging-5-0-inclusive-language"] -== Making open source more inclusive - -Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see link:https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language[Red Hat CTO Chris Wright’s message]. - -include::modules/cluster-logging-release-notes-5.0.0.adoc[leveloffset=+1] -include::modules/cluster-logging-release-notes-5.0.1.adoc[leveloffset=+1] -// include::modules/cluster-logging-release-notes-5.0.2.adoc[leveloffset=+1] diff --git a/logging/cluster-logging-uninstall.adoc b/logging/cluster-logging-uninstall.adoc deleted file mode 100644 index c6dab4e72992..000000000000 --- a/logging/cluster-logging-uninstall.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:context: cluster-logging-uninstall -[id="cluster-logging-uninstall"] -= Uninstalling OpenShift Logging -include::modules/common-attributes.adoc[] - -toc::[] - -You can remove OpenShift Logging from your {product-title} cluster. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-uninstall.adoc[leveloffset=+1] - -.Additional resources - -* xref:../storage/understanding-persistent-storage.adoc#reclaim-manual_understanding-persistent-storage[Reclaiming a persistent volume manually] diff --git a/logging/cluster-logging-upgrading.adoc b/logging/cluster-logging-upgrading.adoc deleted file mode 100644 index 29c64c5c15a6..000000000000 --- a/logging/cluster-logging-upgrading.adoc +++ /dev/null @@ -1,17 +0,0 @@ -:context: cluster-logging-upgrading -[id="cluster-logging-upgrading"] -= Updating OpenShift Logging -include::modules/common-attributes.adoc[] - -toc::[] - - - -After updating the {product-title} cluster from 4.6 to 4.7, you can update the OpenShift Elasticsearch Operator and Cluster Logging Operator from 4.6 to 5.0. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-updating-logging.adoc[leveloffset=+1] diff --git a/logging/cluster-logging-visualizer.adoc b/logging/cluster-logging-visualizer.adoc deleted file mode 100644 index aece33068d8e..000000000000 --- a/logging/cluster-logging-visualizer.adoc +++ /dev/null @@ -1,32 +0,0 @@ -:context: cluster-logging-visualizer -[id="cluster-logging-visualizer-using"] -= Viewing cluster logs by using Kibana -include::modules/common-attributes.adoc[] - -toc::[] - -OpenShift Logging includes a web console for visualizing collected log data. Currently, {product-title} deploys the Kibana console for visualization. - -Using the log visualizer, you can do the following with your data: - -* search and browse the data using the *Discover* tab. -* chart and map the data using the *Visualize* tab. -* create and view custom dashboards using the *Dashboard* tab. - -Use and configuration of the Kibana interface is beyond the scope of this documentation. For more information, -on using the interface, see the link:https://www.elastic.co/guide/en/kibana/6.8/connect-to-elasticsearch.html[Kibana documentation]. - -[NOTE] -==== -The audit logs are not stored in the internal {product-title} Elasticsearch instance by default. To view the audit logs in Kibana, you must use the xref:../logging/config/cluster-logging-log-store.adoc#cluster-logging-elasticsearch-audit_cluster-logging-store[Log Forwarding API] to configure a pipeline that uses the `default` output for audit logs. -==== - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-visualizer-indices.adoc[leveloffset=+1] -include::modules/cluster-logging-visualizer-kibana.adoc[leveloffset=+1] - - diff --git a/logging/cluster-logging.adoc b/logging/cluster-logging.adoc deleted file mode 100644 index 413c07123082..000000000000 --- a/logging/cluster-logging.adoc +++ /dev/null @@ -1,71 +0,0 @@ -:context: cluster-logging -[id="cluster-logging"] -= Understanding Red Hat OpenShift Logging -include::modules/common-attributes.adoc[] - -toc::[] - - - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -As a cluster administrator, you can deploy OpenShift Logging to -aggregate all the logs from your {product-title} cluster, such as node system audit logs, application container logs, and infrastructure logs. -OpenShift Logging aggregates these logs from throughout your cluster and stores them in a default log store. You can xref:../logging/cluster-logging-visualizer.adoc#cluster-logging-visualizer[use the Kibana web console to visualize log data]. - -OpenShift Logging aggregates the following types of logs: - -* `application` - Container logs generated by user applications running in the cluster, except infrastructure container applications. -* `infrastructure` - Logs generated by infrastructure components running in the cluster and {product-title} nodes, such as journal logs. Infrastructure components are pods that run in the `openshift*`, `kube*`, or `default` projects. -* `audit` - Logs generated by auditd, the node audit system, which are stored in the */var/log/audit/audit.log* file, and the audit logs from the Kubernetes apiserver and the OpenShift apiserver. - -[NOTE] -==== -Because the internal {product-title} Elasticsearch log store does not provide secure storage for audit logs, audit logs are not stored in the internal Elasticsearch instance by default. If you want to send the audit logs to the internal log store, for example to view the audit logs in Kibana, you must use the Log Forwarding API as described in xref:../logging/config/cluster-logging-log-store.adoc#cluster-logging-elasticsearch-audit_cluster-logging-store[Forward audit logs to the log store]. -==== -endif::[] - -ifdef::openshift-dedicated[] -As an administrator, you can deploy OpenShift Logging to -aggregate logs for a range of {product-title} services. - -OpenShift Logging runs on worker nodes. As an - administrator, you can monitor resource consumption in the -console and via Prometheus and Grafana. Due to the high work load required for -logging, more worker nodes may be required for your environment. - -Logs in {product-title} are retained for seven days before rotation. Logging -storage is capped at 600GiB. This is independent of a cluster's allocated base -storage. -endif::[] - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-about.adoc[leveloffset=+1] - -For information, see xref:../logging/cluster-logging-deploying.adoc#cluster-logging-deploying[Configuring the log collector]. - -include::modules/cluster-logging-about-components.adoc[leveloffset=+2] - -include::modules/cluster-logging-about-collector.adoc[leveloffset=+2] - -For information, see xref:../logging/config/cluster-logging-collector.adoc#cluster-logging-collector[Configuring the log collector]. - -include::modules/cluster-logging-about-logstore.adoc[leveloffset=+2] - -For information, see xref:../logging/config/cluster-logging-log-store.adoc#cluster-logging-store[Configuring the log store]. - -include::modules/cluster-logging-about-visualizer.adoc[leveloffset=+2] - -For information, see xref:../logging/config/cluster-logging-visualizer.adoc#cluster-logging-visualizer[Configuring the log visualizer]. - -include::modules/cluster-logging-eventrouter-about.adoc[leveloffset=+2] - -For information, see xref:../logging/cluster-logging-eventrouter.adoc#cluster-logging-eventrouter[Collecting and storing Kubernetes events]. - -include::modules/cluster-logging-forwarding-about.adoc[leveloffset=+2] - -For information, see xref:../logging/cluster-logging-external.adoc#cluster-logging-external[Forwarding logs to third party systems]. diff --git a/logging/config/cluster-logging-collector.adoc b/logging/config/cluster-logging-collector.adoc deleted file mode 100644 index 2e82ae1a9f18..000000000000 --- a/logging/config/cluster-logging-collector.adoc +++ /dev/null @@ -1,29 +0,0 @@ -:context: cluster-logging-collector -[id="cluster-logging-collector"] -= Configuring the logging collector -include::modules/common-attributes.adoc[] - -toc::[] - -{product-title} uses Fluentd to collect operations and application logs from your cluster and enriches the data with Kubernetes pod and project metadata. - -You can configure the CPU and memory limits for the log collector and xref:../../logging/config/cluster-logging-moving-nodes.adoc#cluster-logging-moving[move the log collector pods to specific nodes]. All supported modifications to the log collector can be performed though the `spec.collection.log.fluentd` stanza in the `ClusterLogging` custom resource (CR). - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-maintenance-support-about.adoc[leveloffset=+1] - -include::modules/cluster-logging-collector-pod-location.adoc[leveloffset=+1] - -include::modules/cluster-logging-collector-limits.adoc[leveloffset=+1] - -include::modules/cluster-logging-collector-tuning.adoc[leveloffset=+1] - -include::modules/cluster-logging-removing-unused-components-if-no-elasticsearch.adoc[leveloffset=+1] - -.Additional resources - -* xref:../../logging/cluster-logging-external.adoc#cluster-logging-external[Forwarding logs to third party systems] diff --git a/logging/config/cluster-logging-configuring-cr.adoc b/logging/config/cluster-logging-configuring-cr.adoc deleted file mode 100644 index d9cee6332e5e..000000000000 --- a/logging/config/cluster-logging-configuring-cr.adoc +++ /dev/null @@ -1,20 +0,0 @@ -:context: cluster-logging-configuring-cr -[id="cluster-logging-configuring-cr"] -= About the Cluster Logging custom resource -include::modules/common-attributes.adoc[] - -toc::[] - -To configure OpenShift Logging, you customize the `ClusterLogging` custom resource (CR). - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-about-crd.adoc[leveloffset=+1] - - - - - diff --git a/logging/config/cluster-logging-configuring.adoc b/logging/config/cluster-logging-configuring.adoc deleted file mode 100644 index 4f8bad4961ad..000000000000 --- a/logging/config/cluster-logging-configuring.adoc +++ /dev/null @@ -1,81 +0,0 @@ -:context: cluster-logging-configuring -[id="cluster-logging-configuring"] -= Configuring OpenShift Logging -include::modules/common-attributes.adoc[] - -toc::[] - -OpenShift Logging is configurable using a `ClusterLogging` custom resource (CR) deployed -in the `openshift-logging` project. - -The Cluster Logging Operator watches for changes to `ClusterLogging` CR, -creates any missing logging components, and adjusts the logging environment accordingly. - -The `ClusterLogging` CR is based on the `ClusterLogging` custom resource definition (CRD), which defines a complete OpenShift Logging environment -and includes all the components of the logging stack to collect, store and visualize logs. - -.Sample `ClusterLogging` custom resource (CR) -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogging -metadata: - creationTimestamp: '2019-03-20T18:07:02Z' - generation: 1 - name: instance - namespace: openshift-logging -spec: - collection: - logs: - fluentd: - resources: null - type: fluentd - logStore: - elasticsearch: - nodeCount: 3 - redundancyPolicy: SingleRedundancy - resources: - limits: - cpu: - memory: - requests: - cpu: - memory: - storage: {} - type: elasticsearch - managementState: Managed - visualization: - kibana: - proxy: - resources: null - replicas: 1 - resources: null - type: kibana ----- -You can configure the following for OpenShift Logging: - -* You can overwrite the image for each OpenShift Logging component by modifying the appropriate -environment variable in the `cluster-logging-operator` Deployment. - -* You can specify specific nodes for the logging components using node selectors. - -//// -* You can specify the Log collectors to deploy to each node in a cluster, either Fluentd or Rsyslog. - -[IMPORTANT] -==== -The Rsyslog log collector is currently a Technology Preview feature. -==== -//// - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -// modules/cluster-logging-configuring-image-about.adoc[leveloffset=+1] - -[IMPORTANT] -==== -The logging routes are managed by the Cluster Logging Operator and cannot be modified by the user. -==== diff --git a/logging/config/cluster-logging-curator.adoc b/logging/config/cluster-logging-curator.adoc deleted file mode 100644 index 6444b16ba5c5..000000000000 --- a/logging/config/cluster-logging-curator.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:context: cluster-logging-curator -[id="cluster-logging-curator"] -= Configuring the log curator -include::modules/common-attributes.adoc[] - -toc::[] - -In {product-title} {product-version}, log curation is performed by Elasticsearch Curator, based on a xref:../../logging/config/cluster-logging-log-store.html#cluster-logging-elasticsearch-retention_cluster-logging-store[retention policy] that you define. - -The Elasticsearch Curator tool removes Elasticsearch indices that use the data model prior to {product-title} 4.5. You can modify the Curator index retention policy for your old data. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-curator-schedule.adoc[leveloffset=+1] - -include::modules/cluster-logging-curator-delete-index.adoc[leveloffset=+1] diff --git a/logging/config/cluster-logging-log-store.adoc b/logging/config/cluster-logging-log-store.adoc deleted file mode 100644 index 861768acc21e..000000000000 --- a/logging/config/cluster-logging-log-store.adoc +++ /dev/null @@ -1,49 +0,0 @@ -:context: cluster-logging-store -[id="cluster-logging-store"] -= Configuring the log store -include::modules/common-attributes.adoc[] - -toc::[] - -{product-title} uses Elasticsearch 6 (ES) to store and organize the log data. - -You can make modifications to your log store, including: - -* storage for your Elasticsearch cluster -* shard replication across data nodes in the cluster, from full replication to no replication -* external access to Elasticsearch data - -//Following paragraph also in modules/cluster-logging-deploy-storage-considerations.adoc - -Elasticsearch is a memory-intensive application. Each Elasticsearch node needs at least 16G of memory for both memory requests and limits, unless you specify otherwise in the `ClusterLogging` custom resource. The initial set of {product-title} nodes might not be large enough to support the Elasticsearch cluster. You must add additional nodes to the {product-title} cluster to run with the recommended -or higher memory, up to a maximum of 64G for each Elasticsearch node. - -Each Elasticsearch node can operate with a lower memory setting, though this is not recommended for production environments. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-elasticsearch-audit.adoc[leveloffset=+1] - -.Additional resources - -For more information on the Log Forwarding API, see xref:../../logging/cluster-logging-external.adoc#cluster-logging-external[Forwarding logs using the Log Forwarding API]. - -include::modules/cluster-logging-elasticsearch-retention.adoc[leveloffset=+1] - -include::modules/cluster-logging-logstore-limits.adoc[leveloffset=+1] - -include::modules/cluster-logging-elasticsearch-ha.adoc[leveloffset=+1] - -include::modules/cluster-logging-elasticsearch-scaledown.adoc[leveloffset=+1] - -include::modules/cluster-logging-elasticsearch-storage.adoc[leveloffset=+1] - -include::modules/cluster-logging-elasticsearch-persistent-storage-empty.adoc[leveloffset=+1] - -include::modules/cluster-logging-manual-rollout-rolling.adoc[leveloffset=+1] - -include::modules/cluster-logging-elasticsearch-exposing.adoc[leveloffset=+1] diff --git a/logging/config/cluster-logging-maintenance-support.adoc b/logging/config/cluster-logging-maintenance-support.adoc deleted file mode 100644 index 6055720aca26..000000000000 --- a/logging/config/cluster-logging-maintenance-support.adoc +++ /dev/null @@ -1,15 +0,0 @@ -:context: cluster-logging-unsupported -[id="cluster-logging-maintenance-and-support"] -= Maintenance and support -include::modules/common-attributes.adoc[] - -toc::[] - -include::modules/cluster-logging-maintenance-support-about.adoc[leveloffset=+1] - -include::modules/cluster-logging-maintenance-support-list.adoc[leveloffset=+1] - -include::modules/unmanaged-operators.adoc[leveloffset=+1] - - - diff --git a/logging/config/cluster-logging-memory.adoc b/logging/config/cluster-logging-memory.adoc deleted file mode 100644 index 1728701244b2..000000000000 --- a/logging/config/cluster-logging-memory.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:context: cluster-logging-memory -[id="cluster-logging-memory"] -= Configuring CPU and memory limits for OpenShift Logging components -include::modules/common-attributes.adoc[] - -toc::[] - - -You can configure both the CPU and memory limits for each of the OpenShift Logging components as needed. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/cluster-logging-cpu-memory.adoc[leveloffset=+1] - diff --git a/logging/config/cluster-logging-moving-nodes.adoc b/logging/config/cluster-logging-moving-nodes.adoc deleted file mode 100644 index c50bdd20a892..000000000000 --- a/logging/config/cluster-logging-moving-nodes.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:context: cluster-logging-moving -[id="cluster-logging-moving"] -= Moving OpenShift Logging resources with node selectors -include::modules/common-attributes.adoc[] - -toc::[] - - - - - -You can use node selectors to deploy the Elasticsearch, Kibana, and Curator pods to different nodes. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/infrastructure-moving-logging.adoc[leveloffset=+1] diff --git a/logging/config/cluster-logging-storage-considerations.adoc b/logging/config/cluster-logging-storage-considerations.adoc deleted file mode 100644 index e05d236159f7..000000000000 --- a/logging/config/cluster-logging-storage-considerations.adoc +++ /dev/null @@ -1,25 +0,0 @@ -:context: cluster-logging-storage -[id="cluster-logging-storage"] -= Configuring OpenShift Logging storage -include::modules/common-attributes.adoc[] - -toc::[] - - -Elasticsearch is a memory-intensive application. The default OpenShift Logging installation deploys 16G of memory for both memory requests and memory limits. -The initial set of {product-title} nodes might not be large enough to support the Elasticsearch cluster. You must add additional nodes to the -{product-title} cluster to run with the recommended or higher memory. Each Elasticsearch node can operate with a lower -memory setting, though this is not recommended for production environments. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/cluster-logging-deploy-storage-considerations.adoc[leveloffset=+1] - -[id="cluster-logging-storage-considerations-addtl-resources"] -== Additional resources - -* xref:../../logging/config/cluster-logging-log-store.adoc#cluster-logging-elasticsearch-storage_cluster-logging-store[Configuring persistent storage for the log store] diff --git a/logging/config/cluster-logging-systemd.adoc b/logging/config/cluster-logging-systemd.adoc deleted file mode 100644 index 839db7f7a4e6..000000000000 --- a/logging/config/cluster-logging-systemd.adoc +++ /dev/null @@ -1,18 +0,0 @@ -:context: cluster-logging-systemd -[id="cluster-logging-systemd"] -= Configuring systemd-journald and Fluentd -include::modules/common-attributes.adoc[] - -toc::[] - -Because Fluentd reads from the journal, and the journal default settings are very low, journal entries can be lost because the journal cannot keep up with the logging rate from system services. - -We recommend setting `RateLimitIntervalSec=30s` and `RateLimitBurst=10000` (or even higher if necessary) to prevent the journal from losing entries. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/cluster-logging-systemd-scaling.adoc[leveloffset=+1] diff --git a/logging/config/cluster-logging-tolerations.adoc b/logging/config/cluster-logging-tolerations.adoc deleted file mode 100644 index ef13cb3b3e9f..000000000000 --- a/logging/config/cluster-logging-tolerations.adoc +++ /dev/null @@ -1,98 +0,0 @@ -:context: cluster-logging-tolerations -[id="cluster-logging-tolerations"] -= Using tolerations to control OpenShift Logging pod placement -include::modules/common-attributes.adoc[] - -toc::[] - -You can use taints and tolerations to ensure that OpenShift Logging pods run -on specific nodes and that no other workload can run on those nodes. - -Taints and tolerations are simple `key:value` pair. A taint on a node -instructs the node to repel all pods that do not tolerate the taint. - -The `key` is any string, up to 253 characters and the `value` is any string up to 63 characters. -The string must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores. - -.Sample OpenShift Logging CR with tolerations -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: openshift-logging - -... - -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 3 - tolerations: <1> - - key: "logging" - operator: "Exists" - effect: "NoExecute" - tolerationSeconds: 6000 - resources: - limits: - memory: 16Gi - requests: - cpu: 200m - memory: 16Gi - storage: {} - redundancyPolicy: "ZeroRedundancy" - visualization: - type: "kibana" - kibana: - tolerations: <2> - - key: "logging" - operator: "Exists" - effect: "NoExecute" - tolerationSeconds: 6000 - resources: - limits: - memory: 2Gi - requests: - cpu: 100m - memory: 1Gi - replicas: 1 - collection: - logs: - type: "fluentd" - fluentd: - tolerations: <3> - - key: "logging" - operator: "Exists" - effect: "NoExecute" - tolerationSeconds: 6000 - resources: - limits: - memory: 2Gi - requests: - cpu: 100m - memory: 1Gi ----- - -<1> This toleration is added to the Elasticsearch pods. -<2> This toleration is added to the Kibana pod. -<3> This toleration is added to the logging collector pods. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-elasticsearch-tolerations.adoc[leveloffset=+1] - -include::modules/cluster-logging-kibana-tolerations.adoc[leveloffset=+1] - -include::modules/cluster-logging-collector-tolerations.adoc[leveloffset=+1] - -[id="cluster-logging-tolerations-addtl-resources"] -== Additional resources - -For more information about taints and tolerations, see -xref:../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations[Controlling pod placement using node taints]. diff --git a/logging/config/cluster-logging-visualizer.adoc b/logging/config/cluster-logging-visualizer.adoc deleted file mode 100644 index 62435b5ed05b..000000000000 --- a/logging/config/cluster-logging-visualizer.adoc +++ /dev/null @@ -1,20 +0,0 @@ -:context: cluster-logging-visualizer -[id="cluster-logging-visualizer"] -= Configuring the log visualizer -include::modules/common-attributes.adoc[] - -toc::[] - -{product-title} uses Kibana to display the log data collected by OpenShift Logging. - -You can scale Kibana for redundancy and configure the CPU and memory for your Kibana nodes. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-cpu-memory.adoc[leveloffset=+1] - -include::modules/cluster-logging-kibana-scaling.adoc[leveloffset=+1] - diff --git a/logging/config/modules b/logging/config/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/logging/config/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/logging/dedicated-cluster-deploying.adoc b/logging/dedicated-cluster-deploying.adoc deleted file mode 100644 index 2a29410ac1dd..000000000000 --- a/logging/dedicated-cluster-deploying.adoc +++ /dev/null @@ -1,8 +0,0 @@ -:context: dedicated-cluster-deploying -[id="dedicated-cluster-deploying"] -= Installing the Cluster Logging Operator and OpenShift Elasticsearch Operator -include::modules/common-attributes.adoc[] - -toc::[] - -include::modules/dedicated-cluster-install-deploy.adoc[leveloffset=+1] diff --git a/logging/dedicated-cluster-logging.adoc b/logging/dedicated-cluster-logging.adoc deleted file mode 100644 index 0fe2ecc986c8..000000000000 --- a/logging/dedicated-cluster-logging.adoc +++ /dev/null @@ -1,63 +0,0 @@ -:context: dedicated-cluster-logging -[id="dedicated-cluster-logging"] -= Configuring OpenShift Logging in {product-title} -include::modules/common-attributes.adoc[] - -toc::[] - -As a cluster administrator, you can deploy OpenShift Logging -to aggregate logs for a range of services. - -{product-title} clusters can perform logging tasks using the OpenShift Elasticsearch -Operator. OpenShift Logging is configured through the Curator tool to retain logs -for two days. - -OpenShift Logging is configurable using a `ClusterLogging` custom resource (CR) -deployed in the `openshift-logging` project namespace. - -The Cluster Logging Operator watches for changes to `ClusterLogging` CR, creates -any missing logging components, and adjusts the logging environment accordingly. - -The `ClusterLogging` CR is based on the `ClusterLogging` custom resource -definition (CRD), which defines a complete OpenShift Logging environment and -includes all the components of the logging stack to collect, store and visualize -logs. - -.Sample `ClusterLogging` custom resource (CR) -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: "openshift-logging" -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 3 - storage: - storageClassName: "gp2" - size: "200Gi" - redundancyPolicy: "SingleRedundancy" - nodeSelector: - node-role.kubernetes.io/worker: "" - resources: - limits: - memory: 16G - request: - memory: 16G - visualization: - type: "kibana" - kibana: - replicas: 1 - nodeSelector: - node-role.kubernetes.io/worker: "" - collection: - logs: - type: "fluentd" - fluentd: {} - nodeSelector: - node-role.kubernetes.io/worker: "" ----- diff --git a/logging/images b/logging/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/logging/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/logging/modules b/logging/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/logging/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/logging/troubleshooting/cluster-logging-alerts.adoc b/logging/troubleshooting/cluster-logging-alerts.adoc deleted file mode 100644 index e89adadedc82..000000000000 --- a/logging/troubleshooting/cluster-logging-alerts.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:context: cluster-logging-alerts -[id="cluster-logging-alerts"] -= Understanding OpenShift Logging alerts -include::modules/common-attributes.adoc[] - -toc::[] - - -All of the logging collector alerts are listed on the Alerting UI of the {product-title} web console. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/cluster-logging-collector-alerts-viewing.adoc[leveloffset=+1] - -.Additional resources -* For more information on the Alerting UI, see xref:../../monitoring/managing-alerts.html#managing-alerts[Managing alerts]. - -include::modules/cluster-logging-collector-alerts.adoc[leveloffset=+1] -include::modules/cluster-logging-elasticsearch-rules.adoc[leveloffset=+1] diff --git a/logging/troubleshooting/cluster-logging-cluster-status.adoc b/logging/troubleshooting/cluster-logging-cluster-status.adoc deleted file mode 100644 index 54bbf58e1e50..000000000000 --- a/logging/troubleshooting/cluster-logging-cluster-status.adoc +++ /dev/null @@ -1,20 +0,0 @@ -:context: cluster-logging-cluster-status -[id="cluster-logging-cluster-status"] -= Viewing OpenShift Logging status -include::modules/common-attributes.adoc[] - -toc::[] - -You can view the status of the Cluster Logging Operator and for a number of OpenShift Logging components. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/cluster-logging-clo-status.adoc[leveloffset=+1] - -include::modules/cluster-logging-clo-status-comp.adoc[leveloffset=+1] - - diff --git a/logging/troubleshooting/cluster-logging-log-store-status.adoc b/logging/troubleshooting/cluster-logging-log-store-status.adoc deleted file mode 100644 index e1e7aa7c43db..000000000000 --- a/logging/troubleshooting/cluster-logging-log-store-status.adoc +++ /dev/null @@ -1,18 +0,0 @@ -:context: cluster-logging-elasticsearch -[id="cluster-logging-log-store-status"] -= Viewing the status of the log store -include::modules/common-attributes.adoc[] - -toc::[] - -You can view the status of the OpenShift Elasticsearch Operator and for a number of Elasticsearch components. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/cluster-logging-log-store-status-viewing.adoc[leveloffset=+1] - -include::modules/cluster-logging-log-store-status-comp.adoc[leveloffset=+1] diff --git a/logging/troubleshooting/cluster-logging-must-gather.adoc b/logging/troubleshooting/cluster-logging-must-gather.adoc deleted file mode 100644 index e830ed2ccd66..000000000000 --- a/logging/troubleshooting/cluster-logging-must-gather.adoc +++ /dev/null @@ -1,27 +0,0 @@ -:context: cluster-logging-must-gather -[id="cluster-logging-must-gather"] -= Collecting logging data for Red Hat Support -include::modules/ossm-document-attributes.adoc[] -include::modules/common-attributes.adoc[] - -toc::[] - -When opening a support case, it is helpful to provide debugging information about your cluster to Red Hat Support. - -The xref:../../support/gathering-cluster-data.adoc#gathering-cluster-data[`must-gather` tool] enables you to collect diagnostic information for project-level resources, cluster-level resources, and each of the OpenShift Logging components. - -For prompt support, supply diagnostic information for both {product-title} and OpenShift Logging. - -[NOTE] -==== -Do not use the `hack/logging-dump.sh` script. The script is no longer supported and does not collect data. -==== - -include::modules/cluster-logging-must-gather-about.adoc[leveloffset=+1] - -[id="cluster-logging-must-gather-prereqs"] -== Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -include::modules/cluster-logging-must-gather-collecting.adoc[leveloffset=+1] diff --git a/logging/troubleshooting/cluster-logging-troubleshooting-curator.adoc b/logging/troubleshooting/cluster-logging-troubleshooting-curator.adoc deleted file mode 100644 index 055fe9deae22..000000000000 --- a/logging/troubleshooting/cluster-logging-troubleshooting-curator.adoc +++ /dev/null @@ -1,20 +0,0 @@ -:context: cluster-logging-troubleshooting-curator -[id="cluster-logging-troubleshooting-curator"] -= Troubleshooting the log curator -include::modules/common-attributes.adoc[] - -toc::[] - - -You can use information in this section for debugging log curation. Curator is used to remove data that is in the Elasticsearch index format prior to {product-title} {product-version}, and will be removed in a later release. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/cluster-logging-curator-troubleshoot.adoc[leveloffset=+1] - - - - diff --git a/logging/viewing-resource-logs.adoc b/logging/viewing-resource-logs.adoc deleted file mode 100644 index c56556291655..000000000000 --- a/logging/viewing-resource-logs.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="vewing-resource-logs"] -= Viewing logs for a resource -include::modules/common-attributes.adoc[] -:context: viewing-resource-logs - -toc::[] - -You can view the logs for various resources, such as builds, deployments, and pods by using the OpenShift CLI (oc) and the web console. - -[NOTE] -==== -Resource logs are a default feature that provides limited log viewing capability. To enhance your log retrieving and viewing experience, it is recommended that you install xref:../logging/cluster-logging.adoc#cluster-logging[OpenShift Logging]. OpenShift Logging aggregates all the logs from your {product-title} cluster, such as node system audit logs, application container logs, and infrastructure logs, into a dedicated log store. You can then query, discover, and visualize your log data through the xref:../logging/cluster-logging-visualizer.adoc#cluster-logging-visualizer-using[Kibana interface]. Resource logs do not access the OpenShift Logging log store. -==== - -include::modules/viewing-resource-logs-cli-console.adoc[leveloffset=+1] - diff --git a/machine_management/applying-autoscaling.adoc b/machine_management/applying-autoscaling.adoc deleted file mode 100644 index e550c0e73959..000000000000 --- a/machine_management/applying-autoscaling.adoc +++ /dev/null @@ -1,62 +0,0 @@ -[id="applying-autoscaling"] -= Applying autoscaling to an {product-title} cluster -include::modules/common-attributes.adoc[] -:context: applying-autoscaling - -toc::[] - -Applying autoscaling to an {product-title} cluster involves deploying a cluster autoscaler and then deploying machine autoscalers for each machine type in your cluster. - -[IMPORTANT] -==== -You can configure the cluster autoscaler only in clusters where the machine API is operational. -==== - -include::modules/cluster-autoscaler-about.adoc[leveloffset=+1] - -include::modules/machine-autoscaler-about.adoc[leveloffset=+1] - -[id="configuring-clusterautoscaler"] -== Configuring the cluster autoscaler - -First, deploy the cluster autoscaler to manage automatic resource scaling in your {product-title} cluster. - -[NOTE] -==== -Because the cluster autoscaler is scoped to the entire cluster, you can make only one cluster autoscaler for the cluster. -==== - -include::modules/cluster-autoscaler-cr.adoc[leveloffset=+2] - -:FeatureName: cluster autoscaler -:FeatureResourceName: ClusterAutoscaler -include::modules/deploying-resource.adoc[leveloffset=+2] - -== Next steps - -* After you configure the cluster autoscaler, you must configure at least one machine autoscaler. - -[id="configuring-machineautoscaler"] -== Configuring the machine autoscalers - -After you deploy the cluster autoscaler, deploy `MachineAutoscaler` resources that reference the machine sets that are used to scale the cluster. - -[IMPORTANT] -==== -You must deploy at least one `MachineAutoscaler` resource after you deploy the `ClusterAutoscaler` resource. -==== - -[NOTE] -==== -You must configure separate resources for each machine set. Remember that machine sets are different in each region, so consider whether you want to enable machine scaling in multiple regions. The machine set that you scale must have at least one machine in it. -==== - -include::modules/machine-autoscaler-cr.adoc[leveloffset=+2] - -:FeatureName: machine autoscaler -:FeatureResourceName: MachineAutoscaler -include::modules/deploying-resource.adoc[leveloffset=+2] - -== Additional resources - -* For more information about pod priority, see xref:../nodes/pods/nodes-pods-priority.adoc#nodes-pods-priority[Including pod priority in pod scheduling decisions in {product-title}]. diff --git a/machine_management/creating-infrastructure-machinesets.adoc b/machine_management/creating-infrastructure-machinesets.adoc deleted file mode 100644 index b01fe3bed965..000000000000 --- a/machine_management/creating-infrastructure-machinesets.adoc +++ /dev/null @@ -1,76 +0,0 @@ -[id="creating-infrastructure-machinesets"] -= Creating infrastructure machine sets -include::modules/common-attributes.adoc[] -:context: creating-infrastructure-machinesets - -toc::[] - -You can create a machine set to host only infrastructure components. You apply specific Kubernetes labels to these machines and then update the infrastructure components to run on only those machines. These infrastructure nodes are not counted toward the total number of subscriptions that are required to run the environment. - -[IMPORTANT] -==== -Unlike earlier versions of {product-title}, you cannot move the infrastructure components to the master machines. To move the components, you must create a new machine set. -==== - -include::modules/infrastructure-components.adoc[leveloffset=+1] - -[id="creating-infrastructure-machinesets-production"] -== Creating infrastructure machine sets for production environments - -In a production deployment, deploy at least three machine sets to hold infrastructure components. Both the logging aggregation solution and the service mesh deploy Elasticsearch, and Elasticsearch requires three instances that are installed on different nodes. For high availability, deploy these nodes to different availability zones. Since you need different machine sets for each availability zone, create at least three machine sets. - -[id="creating-infrastructure-machinesets-clouds"] -=== Creating machine sets for different clouds - -Use the sample machine set for your cloud. - -include::modules/machineset-yaml-aws.adoc[leveloffset=+3] - -Machine sets running on AWS support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#machineset-non-guaranteed-instance_creating-machineset-aws[Spot Instances]. You can save on costs by using Spot Instances at a lower price compared to -On-Demand Instances on AWS. xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#machineset-creating-non-guaranteed-instance_creating-machineset-aws[Configure Spot Instances] by adding `spotMarketOptions` to the `MachineSet` YAML file. - -include::modules/machineset-yaml-azure.adoc[leveloffset=+3] - -Machine sets running on Azure support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#machineset-non-guaranteed-instance_creating-machineset-azure[Spot VMs]. You can save on costs by using Spot VMs at a lower price compared to standard VMs on Azure. You can xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#machineset-creating-non-guaranteed-instance_creating-machineset-azure[configure Spot VMs] by adding `spotVMOptions` to the `MachineSet` YAML file. - -include::modules/machineset-yaml-gcp.adoc[leveloffset=+3] - -Machine sets running on GCP support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-non-guaranteed-instance_creating-machineset-gcp[preemptible VM instances]. You can save on costs by using preemptible VM instances at a lower price -compared to normal instances on GCP. You can xref:../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-creating-non-guaranteed-instance_creating-machineset-gcp[configure preemptible VM instances] by adding `preemptible` to the `MachineSet` YAML file. - -include::modules/machineset-yaml-osp.adoc[leveloffset=+3] - -include::modules/machineset-yaml-vsphere.adoc[leveloffset=+3] - -include::modules/machineset-creating.adoc[leveloffset=+2] - -[id="assigning-machineset-resources-to-infra-nodes"] -== Assigning machine set resources to infrastructure nodes - -After creating an infrastructure machine set, the `worker` and `infra` roles are applied to new infra nodes. Nodes with the `infra` role applied are not counted toward the total number of subscriptions that are required to run the environment, even when the `worker` role is also applied. - -However, with an infra node being assigned as a worker, there is a chance user workloads could get inadvertently assigned to an infra node. To avoid this, you can apply a taint to the infra node and tolerations for the pods you want to control. - -include::modules/binding-infra-node-workloads-using-taints-tolerations.adoc[leveloffset=+2] - -.Additional resources - -* See xref:../nodes/scheduling/nodes-scheduler-about.adoc#nodes-scheduler-about[Controlling pod placement using the scheduler] for general information on scheduling a pod to a node. -* See xref:moving-resources-to-infrastructure-machinesets[Moving resources to infrastructure machine sets] for instructions on scheduling pods to infra nodes. - -[id="moving-resources-to-infrastructure-machinesets"] -== Moving resources to infrastructure machine sets - -Some of the infrastructure resources are deployed in your cluster by default. You can move them to the infrastructure machine sets that you created. - -include::modules/infrastructure-moving-router.adoc[leveloffset=+2] - -include::modules/infrastructure-moving-registry.adoc[leveloffset=+2] - -include::modules/infrastructure-moving-monitoring.adoc[leveloffset=+2] - -.Additional resources - -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#moving-monitoring-components-to-different-nodes_configuring-the-monitoring-stack[the monitoring documentation] for the general instructions on moving {product-title} components. - -include::modules/infrastructure-moving-logging.adoc[leveloffset=+2] diff --git a/machine_management/creating_machinesets/creating-machineset-aws.adoc b/machine_management/creating_machinesets/creating-machineset-aws.adoc deleted file mode 100644 index 18b588d6d0b1..000000000000 --- a/machine_management/creating_machinesets/creating-machineset-aws.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="creating-machineset-aws"] -= Creating a machine set on AWS -include::modules/common-attributes.adoc[] -:context: creating-machineset-aws - -You can create a different machine set to serve a specific purpose in your {product-title} cluster on Amazon Web Services (AWS). For example, you might create infrastructure machine sets and related machines so that you can move supporting workloads to the new machines. - -toc::[] - -include::modules/machine-api-overview.adoc[leveloffset=+1] - -include::modules/machineset-yaml-aws.adoc[leveloffset=+1] - -include::modules/machineset-creating.adoc[leveloffset=+1] - -include::modules/machineset-non-guaranteed-instance.adoc[leveloffset=+1] - -include::modules/machineset-creating-non-guaranteed-instances.adoc[leveloffset=+1] - -include::modules/machineset-dedicated-instances.adoc[leveloffset=+1] - -include::modules/machineset-creating-dedicated-instances.adoc[leveloffset=+1] diff --git a/machine_management/creating_machinesets/creating-machineset-azure.adoc b/machine_management/creating_machinesets/creating-machineset-azure.adoc deleted file mode 100644 index 4a86a8f32133..000000000000 --- a/machine_management/creating_machinesets/creating-machineset-azure.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="creating-machineset-azure"] -= Creating a machine set on Azure -include::modules/common-attributes.adoc[] -:context: creating-machineset-azure - -You can create a different machine set to serve a specific purpose in your {product-title} cluster on Microsoft Azure. For example, you might create infrastructure machine sets and related machines so that you can move supporting workloads to the new machines. - -toc::[] - -include::modules/machine-api-overview.adoc[leveloffset=+1] - -include::modules/machineset-yaml-azure.adoc[leveloffset=+1] - -include::modules/machineset-creating.adoc[leveloffset=+1] - -include::modules/machineset-non-guaranteed-instance.adoc[leveloffset=+1] - -include::modules/machineset-creating-non-guaranteed-instances.adoc[leveloffset=+1] diff --git a/machine_management/creating_machinesets/creating-machineset-gcp.adoc b/machine_management/creating_machinesets/creating-machineset-gcp.adoc deleted file mode 100644 index d3537dab93fd..000000000000 --- a/machine_management/creating_machinesets/creating-machineset-gcp.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="creating-machineset-gcp"] -= Creating a machine set on GCP -include::modules/common-attributes.adoc[] -:context: creating-machineset-gcp - -You can create a different machine set to serve a specific purpose in your {product-title} cluster on Google Cloud Platform (GCP). For example, you might create infrastructure machine sets and related machines so that you can move supporting workloads to the new machines. - -toc::[] - -include::modules/machine-api-overview.adoc[leveloffset=+1] - -include::modules/machineset-yaml-gcp.adoc[leveloffset=+1] - -include::modules/machineset-creating.adoc[leveloffset=+1] - -include::modules/machineset-non-guaranteed-instance.adoc[leveloffset=+1] - -include::modules/machineset-creating-non-guaranteed-instances.adoc[leveloffset=+1] - -include::modules/machineset-enabling-customer-managed-encryption.adoc[leveloffset=+1] diff --git a/machine_management/creating_machinesets/creating-machineset-osp.adoc b/machine_management/creating_machinesets/creating-machineset-osp.adoc deleted file mode 100644 index 8aa45952df58..000000000000 --- a/machine_management/creating_machinesets/creating-machineset-osp.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="creating-machineset-osp"] -= Creating a machine set on OpenStack -include::modules/common-attributes.adoc[] -:context: creating-machineset-osp - -You can create a different machine set to serve a specific purpose in your {product-title} cluster on {rh-openstack-first}. For example, you might create infrastructure machine sets and related machines so that you can move supporting workloads to the new machines. - -toc::[] - -include::modules/machine-api-overview.adoc[leveloffset=+1] - -include::modules/machineset-yaml-osp.adoc[leveloffset=+1] - -include::modules/machineset-creating.adoc[leveloffset=+1] - -// Mothballed - re-add when available -// include::modules/machineset-osp-adding-bare-metal.adoc[leveloffset=+1] diff --git a/machine_management/creating_machinesets/creating-machineset-rhv.adoc b/machine_management/creating_machinesets/creating-machineset-rhv.adoc deleted file mode 100644 index 53cd02593055..000000000000 --- a/machine_management/creating_machinesets/creating-machineset-rhv.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="creating-machineset-rhv"] -= Creating a machine set on {rh-virtualization} -include::modules/common-attributes.adoc[] -:context: creating-machineset-rhv - -You can create a different machine set to serve a specific purpose in your {product-title} cluster on {rh-virtualization-first}. For example, you might create infrastructure machine sets and related machines so that you can move supporting workloads to the new machines. - -toc::[] - -include::modules/machine-api-overview.adoc[leveloffset=+1] - -include::modules/machineset-yaml-rhv.adoc[leveloffset=+1] - -include::modules/machineset-creating.adoc[leveloffset=+1] diff --git a/machine_management/creating_machinesets/creating-machineset-vsphere.adoc b/machine_management/creating_machinesets/creating-machineset-vsphere.adoc deleted file mode 100644 index 6eeffb4e29ad..000000000000 --- a/machine_management/creating_machinesets/creating-machineset-vsphere.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="creating-machineset-vsphere"] -= Creating a machine set on vSphere -include::modules/common-attributes.adoc[] -:context: creating-machineset-vsphere - -toc::[] - -You can create a different machine set to serve a specific purpose in your {product-title} cluster on VMware vSphere. For example, you might create infrastructure machine sets and related machines so that you can move supporting workloads to the new machines. - -include::modules/machine-api-overview.adoc[leveloffset=+1] - -include::modules/machineset-yaml-vsphere.adoc[leveloffset=+1] - -include::modules/machineset-creating.adoc[leveloffset=+1] diff --git a/machine_management/deleting-machine.adoc b/machine_management/deleting-machine.adoc deleted file mode 100644 index 31766e3a8812..000000000000 --- a/machine_management/deleting-machine.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="deleting-machine"] -= Deleting a machine -include::modules/common-attributes.adoc[] -:context: deleting-machine - -toc::[] - -You can delete a specific machine. - -include::modules/machine-delete.adoc[leveloffset=+1] diff --git a/machine_management/deploying-machine-health-checks.adoc b/machine_management/deploying-machine-health-checks.adoc deleted file mode 100644 index 876e73d26937..000000000000 --- a/machine_management/deploying-machine-health-checks.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="deploying-machine-health-checks"] -= Deploying machine health checks -include::modules/common-attributes.adoc[] -:context: deploying-machine-health-checks - -toc::[] - -You can configure and deploy a machine health check to automatically repair damaged machines in a machine pool. - -include::modules/machine-user-provisioned-limitations.adoc[leveloffset=+1] - -include::modules/machine-health-checks-about.adoc[leveloffset=+1] - -.Additional resources - -* For more information about the node conditions you can define in a `MachineHealthCheck` CR, see xref:../nodes/nodes/nodes-nodes-viewing.html#nodes-nodes-viewing-listing_nodes-nodes-viewing[About listing all the nodes in a cluster]. - -* For more information about short-circuiting, see xref:../machine_management/deploying-machine-health-checks.adoc#machine-health-checks-short-circuiting_deploying-machine-health-checks[Short-circuiting machine health check remediation]. - -include::modules/machine-health-checks-resource.adoc[leveloffset=+1] - -.Additional resources - -include::modules/machine-health-checks-creating.adoc[leveloffset=+1] diff --git a/machine_management/images b/machine_management/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/machine_management/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/machine_management/manually-scaling-machineset.adoc b/machine_management/manually-scaling-machineset.adoc deleted file mode 100644 index eb7f8851612b..000000000000 --- a/machine_management/manually-scaling-machineset.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="manually-scaling-machineset"] -= Manually scaling a machine set -include::modules/common-attributes.adoc[] -:context: manually-scaling-machineset - -toc::[] - -You can add or remove an instance of a machine in a machine set. - -[NOTE] -==== -If you need to modify aspects of a machine set outside of scaling, see xref:../machine_management/modifying-machineset.adoc#modifying-machineset[Modifying a machine set]. -==== - -== Prerequisites - -* If you enabled the cluster-wide proxy and scale up workers not included in `networking.machineNetwork[].cidr` from the installation configuration, you must xref:../networking/enable-cluster-wide-proxy.adoc#nw-proxy-configure-object_config-cluster-wide-proxy[add the workers to the Proxy object's `noProxy` field] to prevent connection issues. - -include::modules/machine-user-provisioned-limitations.adoc[leveloffset=+1] - -include::modules/machineset-manually-scaling.adoc[leveloffset=+1] - -include::modules/machineset-delete-policy.adoc[leveloffset=+1] diff --git a/machine_management/modifying-machineset.adoc b/machine_management/modifying-machineset.adoc deleted file mode 100644 index cd8a21518695..000000000000 --- a/machine_management/modifying-machineset.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="modifying-machineset"] -= Modifying a machine set -include::modules/common-attributes.adoc[] -:context: modifying-machineset - -toc::[] - - -You can make changes to a machine set, such as adding labels, changing the instance type, or changing block storage. - -[NOTE] -==== -If you need to scale a machine set without making other changes, see xref:../machine_management/manually-scaling-machineset.adoc#manually-scaling-machineset[Manually scaling a machine set]. -==== - - -include::modules/machineset-modifying.adoc[leveloffset=+1] diff --git a/machine_management/modules b/machine_management/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/machine_management/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/machine_management/user_infra/adding-bare-metal-compute-user-infra.adoc b/machine_management/user_infra/adding-bare-metal-compute-user-infra.adoc deleted file mode 100644 index 154d7feb2d7e..000000000000 --- a/machine_management/user_infra/adding-bare-metal-compute-user-infra.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="adding-bare-metal-compute-user-infra"] -= Adding compute machines to bare metal -include::modules/common-attributes.adoc[] -:context: adding-bare-metal-compute-user-infra - -toc::[] - -You can add more compute machines to your {product-title} cluster on bare metal. - -== Prerequisites - -* You xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[installed a cluster on bare metal]. -* You have installation media and {op-system-first} images that you used to create your cluster. If you do not have these files, you must obtain them by following the instructions in the xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[installation procedure]. - -[IMPORTANT] -==== -If you do not have access to the {op-system-first} images that were used to create your cluster, you can add more compute machines to your {product-title} cluster with newer versions of {op-system-first} images. For instructions, see link:https://access.redhat.com/solutions/5514051[Adding new nodes to UPI cluster fails after upgrading to OpenShift 4.6+]. -==== - -[id="creating-machines-bare-metal"] -== Creating {op-system-first} machines - -Before you add more compute machines to a cluster that you installed on bare metal infrastructure, you must create {op-system} machines for it to use. You can either use an ISO image or network PXE booting to create the machines. - -include::modules/machine-user-infra-machines-iso.adoc[leveloffset=+2] - -include::modules/machine-user-infra-machines-pxe.adoc[leveloffset=+2] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] diff --git a/machine_management/user_infra/adding-rhel-compute.adoc b/machine_management/user_infra/adding-rhel-compute.adoc deleted file mode 100644 index 639c3672a9ab..000000000000 --- a/machine_management/user_infra/adding-rhel-compute.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="adding-rhel-compute"] -= Adding RHEL compute machines to an {product-title} cluster -include::modules/common-attributes.adoc[] -:context: adding-rhel-compute - -toc::[] - -In {product-title}, you can add Red Hat Enterprise Linux (RHEL) compute, or worker, machines to a user-provisioned infrastructure cluster. You can use RHEL as the operating system on only compute machines. - -include::modules/rhel-compute-overview.adoc[leveloffset=+1] - -include::modules/rhel-compute-requirements.adoc[leveloffset=+1] - -include::modules/rhel-preparing-playbook-machine.adoc[leveloffset=+1] - -include::modules/rhel-preparing-node.adoc[leveloffset=+1] - -include::modules/rhel-adding-node.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/rhel-ansible-parameters.adoc[leveloffset=+1] - -include::modules/rhel-removing-rhcos.adoc[leveloffset=+2] diff --git a/machine_management/user_infra/adding-vsphere-compute-user-infra.adoc b/machine_management/user_infra/adding-vsphere-compute-user-infra.adoc deleted file mode 100644 index d3e84d592053..000000000000 --- a/machine_management/user_infra/adding-vsphere-compute-user-infra.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="adding-vsphere-compute-user-infra"] -= Adding compute machines to vSphere -include::modules/common-attributes.adoc[] -:context: adding-vsphere-compute-user-infra - -toc::[] - -You can add more compute machines to your {product-title} cluster on VMware vSphere. - -== Prerequisites - -* You xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[installed a cluster on vSphere]. - -include::modules/machine-vsphere-machines.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] diff --git a/machine_management/user_infra/more-rhel-compute.adoc b/machine_management/user_infra/more-rhel-compute.adoc deleted file mode 100644 index fd533c43c4b8..000000000000 --- a/machine_management/user_infra/more-rhel-compute.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="more-rhel-compute"] -= Adding more RHEL compute machines to an {product-title} cluster -include::modules/common-attributes.adoc[] -:context: more-rhel-compute - -toc::[] - -If your {product-title} cluster already includes Red Hat Enterprise Linux (RHEL) compute machines, which are also known as worker machines, you can add more RHEL compute machines to it. - -include::modules/rhel-compute-overview.adoc[leveloffset=+1] - -include::modules/rhel-compute-requirements.adoc[leveloffset=+1] - -include::modules/rhel-preparing-node.adoc[leveloffset=+1] - -include::modules/rhel-adding-more-nodes.adoc[leveloffset=+1] - -include::modules/installation-approve-csrs.adoc[leveloffset=+1] - -include::modules/rhel-ansible-parameters.adoc[leveloffset=+1] diff --git a/makeBuild.py b/makeBuild.py index b11d6c13232c..60a5b7b25df4 100755 --- a/makeBuild.py +++ b/makeBuild.py @@ -3,6 +3,7 @@ # uses a refactored Aura script which is an opensource port of ccutil +import argparse import sys import os import logging @@ -19,6 +20,15 @@ #print(branch) +def setup_parser(): + parser = argparse.ArgumentParser( + formatter_class=argparse.ArgumentDefaultsHelpFormatter + ) + parser.add_argument( + "--include-api-book", help="Include the rest_api book in the build", action="https://github.com/store_true", default=False, + ) + return parser + # function to convert XML ids to HTML 4 compatible ids from ccutil def _fix_ids_for_html4(tree): """ @@ -75,6 +85,46 @@ def _fix_ids_for_html4(tree): if old_endterm.get("endterm") == id_val: old_endterm.set('endterm', new_id) +def build_book(book): + validated = True + starting_dir=os.getcwd() + os.chdir(os.path.join("drupal-build", distro, book)) + #print(os.getcwd() + "\n") + + # Create the transformer instance + transformer = AsciiDocPublicanTransformer() + + try: + # Transform the AsciiDoc to DocBook XML + print((">>> Working on " + book + " book in " + distro + " <<<")) + if not transformer._build_docbook_src("master.adoc", "build"): + logging.error(">>> Validation of book " + book + " in " + distro + " failed: master.adoc not found <<<") + return False + + # Parse the transformed XML + transformer._before_xml_parse("build/master.xml") + + # Parse the XML content + tree = utils.parse_xml("build/master.xml") + + # Apply XML updates from aura/ccutil + transformer._fix_uncoverted_xrefs_with_file_paths(tree) + _fix_ids_for_html4(tree) + + # Validate the transformed XML + if not transformer._validate_docbook_idrefs(tree): + logging.error(">>> Validation of book " + book + " in " + distro + " failed <<<") + validated = False + except (XMLSyntaxError, XIncludeError, InvalidInputException) as e: + logging.error(e) + validated = False + finally: + print((">>> Finished with " + book + " book in " + distro + " <<<")) + print("---------------------------------------") + os.chdir(starting_dir) + return validated + + # all validated? all_validated = True @@ -82,6 +132,10 @@ def _fix_ids_for_html4(tree): # Initialize logging cli.init_logging(False, False) + +parser = setup_parser() +args = parser.parse_args() + for distro in os.listdir("drupal-build"): print("---------------------------------------") @@ -91,53 +145,21 @@ def _fix_ids_for_html4(tree): for book in os.listdir(os.path.join("drupal-build", distro)): #print(os.getcwd() + "\n") - #if not os.path.isdir("drupal-build/" + distro + "/" + book): - #print("---------------------------------------") - #print(">>> No Book " + book + " in this repo. Skipping <<<") - #print("---------------------------------------") - - #continue - + # skip any non-directory entries + if not os.path.isdir("drupal-build/" + distro + "/" + book): + continue # rest api book is a pain and doesn't convert well if book == "rest_api": - continue - - os.chdir("drupal-build/" + distro + "/" + book) - #print(os.getcwd() + "\n") - - # Create the transformer instance - transformer = AsciiDocPublicanTransformer() - - try: - # Transform the AsciiDoc to DocBook XML - print((">>> Working on " + book + " book in " + distro + " <<<")) - if not transformer._build_docbook_src("master.adoc", "build"): - print(("Could not transform book " + book)) - all_validated = False + # Exclude the REST API book unless we explicitly require it + if not args.include_api_book: continue - # Parse the transformed XML - transformer._before_xml_parse("build/master.xml") - - # Parse the XML content - tree = utils.parse_xml("build/master.xml") - - # Apply XML updates from aura/ccutil - transformer._fix_uncoverted_xrefs_with_file_paths(tree) - _fix_ids_for_html4(tree) - - # Validate the transformed XML - if not transformer._validate_docbook_idrefs(tree): - logging.error(">>> Validation of book " + book + " in " + distro + " failed <<<") - all_validated = False - except (XMLSyntaxError, XIncludeError, InvalidInputException) as e: - logging.error(e) - all_validated = False - finally: - print((">>> Finished with " + book + " book in " + distro + " <<<")) - print("---------------------------------------") - os.chdir("../../../") - + if os.path.exists(os.path.join("drupal-build", distro, book,"hugeBook.flag")): + for secondary_book in os.listdir(os.path.join("drupal-build", distro, book)): + if os.path.isdir("drupal-build/" + distro + "/" + book + "/" + secondary_book): + all_validated = all_validated and build_book(book+"/"+secondary_book) + else: + all_validated = all_validated and build_book(book) if not all_validated: sys.exit(-1) else: diff --git a/metering/configuring_metering/metering-about-configuring.adoc b/metering/configuring_metering/metering-about-configuring.adoc deleted file mode 100644 index 4785d0b4433b..000000000000 --- a/metering/configuring_metering/metering-about-configuring.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="metering-about-configuring"] -= About configuring metering -include::modules/common-attributes.adoc[] -:context: metering-about-configuring - -toc::[] - -A `CustomResource` called your `MeteringConfig` specifies all the configuration details for your metering installation. When you first install the metering stack, a default `MeteringConfig` is generated. Use the examples in the documentation to modify this default file. Keep in mind the following key points: - -* At a minimum, you need to xref:../../metering/configuring_metering/metering-configure-persistent-storage.adoc#metering-configure-persistent-storage[configure persistent storage] and xref:../../metering/configuring_metering/metering-configure-hive-metastore.adoc#metering-configure-hive-metastore[configure the Hive metastore]. - -* Most default configuration settings work, but larger deployments or highly customized deployments should review all configuration options carefully. - -* Some configuration options can not be modified after installation. - -For configuration options that can be modified after installation, make the changes in your `MeteringConfig` and reapply the file. diff --git a/metering/configuring_metering/metering-common-config-options.adoc b/metering/configuring_metering/metering-common-config-options.adoc deleted file mode 100644 index 71f6e13f934b..000000000000 --- a/metering/configuring_metering/metering-common-config-options.adoc +++ /dev/null @@ -1,174 +0,0 @@ -[id="metering-common-config-options"] -= Common configuration options -include::modules/common-attributes.adoc[] -:context: metering-common-config-options - -toc::[] - -== Resource requests and limits -You can adjust the CPU, memory, or storage resource requests and/or limits for pods and volumes. The `default-resource-limits.yaml` below provides an example of setting resource request and limits for each component. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - reporting-operator: - spec: - resources: - limits: - cpu: 1 - memory: 500Mi - requests: - cpu: 500m - memory: 100Mi - presto: - spec: - coordinator: - resources: - limits: - cpu: 4 - memory: 4Gi - requests: - cpu: 2 - memory: 2Gi - - worker: - replicas: 0 - resources: - limits: - cpu: 8 - memory: 8Gi - requests: - cpu: 4 - memory: 2Gi - - hive: - spec: - metastore: - resources: - limits: - cpu: 4 - memory: 2Gi - requests: - cpu: 500m - memory: 650Mi - storage: - class: null - create: true - size: 5Gi - server: - resources: - limits: - cpu: 1 - memory: 1Gi - requests: - cpu: 500m - memory: 500Mi ----- - -== Node selectors -You can run the metering components on specific sets of nodes. Set the `nodeSelector` on a metering component to control where the component is scheduled. The `node-selectors.yaml` file below provides an example of setting node selectors for each component. - -[NOTE] -==== -Add the `openshift.io/node-selector: ""` namespace annotation to the metering namespace YAML file before configuring specific node selectors for the operand Pods. Specify `""` as the annotation value. -==== - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - reporting-operator: - spec: - nodeSelector: - "node-role.kubernetes.io/infra": "" <1> - - presto: - spec: - coordinator: - nodeSelector: - "node-role.kubernetes.io/infra": "" <1> - worker: - nodeSelector: - "node-role.kubernetes.io/infra": "" <1> - hive: - spec: - metastore: - nodeSelector: - "node-role.kubernetes.io/infra": "" <1> - server: - nodeSelector: - "node-role.kubernetes.io/infra": "" <1> ----- -<1> Add a `nodeSelector` parameter with the appropriate value to the component you want to move. You can use a `nodeSelector` in the format shown or use key-value pairs, based on the value specified for the node. - -[NOTE] -==== -Add the `openshift.io/node-selector: ""` namespace annotation to the metering namespace YAML file before configuring specific node selectors for the operand Pods. When the `openshift.io/node-selector` annotation is set on the project, the value is used in preference to the value of the `spec.defaultNodeSelector` field in the cluster-wide Scheduler object. -==== - -.Verification -You can verify the metering node selectors by performing any of the following checks: - -* Verify that all Pods for metering are correctly scheduled on the IP of the node that is configured in the MeteringConfig custom resource: -+ --- -.Procedure -. Check all pods in the `openshift-metering` namespace: -+ -[source,terminal] ----- -$ oc --namespace openshift-metering get pods -o wide ----- -+ -The output shows the `NODE` and corresponding `IP` for each Pod running in the `openshift-metering` namespace. -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -hive-metastore-0 1/2 Running 0 4m33s 10.129.2.26 ip-10-0-210-167.us-east-2.compute.internal -hive-server-0 2/3 Running 0 4m21s 10.128.2.26 ip-10-0-150-175.us-east-2.compute.internal -metering-operator-964b4fb55-4p699 2/2 Running 0 7h30m 10.131.0.33 ip-10-0-189-6.us-east-2.compute.internal -nfs-server 1/1 Running 0 7h30m 10.129.2.24 ip-10-0-210-167.us-east-2.compute.internal -presto-coordinator-0 2/2 Running 0 4m8s 10.131.0.35 ip-10-0-189-6.us-east-2.compute.internal -reporting-operator-869b854c78-8g2x5 1/2 Running 0 7h27m 10.128.2.25 ip-10-0-150-175.us-east-2.compute.internal ----- -+ -. Compare the nodes in the `openshift-metering` namespace to each node `NAME` in your cluster: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-147-106.us-east-2.compute.internal Ready master 14h v1.20.0+6025c28 -ip-10-0-150-175.us-east-2.compute.internal Ready worker 14h v1.20.0+6025c28 -ip-10-0-175-23.us-east-2.compute.internal Ready master 14h v1.20.0+6025c28 -ip-10-0-189-6.us-east-2.compute.internal Ready worker 14h v1.20.0+6025c28 -ip-10-0-205-158.us-east-2.compute.internal Ready master 14h v1.20.0+6025c28 -ip-10-0-210-167.us-east-2.compute.internal Ready worker 14h v1.20.0+6025c28 ----- --- - -* Verify that the node selector configuration in the MeteringConfig custom resource does not interfere with the cluster-wide node selector configuration such that no metering operand Pods are scheduled. -+ --- -.Procedure -* Check the cluster-wide Scheduler object for the `spec.defaultNodeSelector` field, which shows where Pods are scheduled by default: -+ -[source,terminal] ----- -$ oc get schedulers.config.openshift.io cluster -o yaml ----- --- diff --git a/metering/configuring_metering/metering-configure-aws-billing-correlation.adoc b/metering/configuring_metering/metering-configure-aws-billing-correlation.adoc deleted file mode 100644 index 32931b957e1e..000000000000 --- a/metering/configuring_metering/metering-configure-aws-billing-correlation.adoc +++ /dev/null @@ -1,112 +0,0 @@ -[id="metering-configure-aws-billing-correlation"] -= Configure AWS billing correlation -include::modules/common-attributes.adoc[] -:context: metering-configure-aws-billing-correlation - -toc::[] - -Metering can correlate cluster usage information with https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-reports-costusage.html[AWS detailed billing information], attaching a dollar amount to resource usage. For clusters running in EC2, you can enable this by modifying the example `aws-billing.yaml` file below. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - openshift-reporting: - spec: - awsBillingReportDataSource: - enabled: true - # Replace these with where your AWS billing reports are - # stored in S3. - bucket: "" <1> - prefix: "" - region: "" - - reporting-operator: - spec: - config: - aws: - secretName: "" <2> - - presto: - spec: - config: - aws: - secretName: "" <2> - - hive: - spec: - config: - aws: - secretName: "" <2> ----- -To enable AWS billing correlation, first ensure the AWS Cost and Usage Reports are enabled. For more information, see https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-reports-gettingstarted-turnonreports.html[Turning on the AWS Cost and Usage Report] in the AWS documentation. - -<1> Update the bucket, prefix, and region to the location of your AWS Detailed billing report. -<2> All `secretName` fields should be set to the name of a secret in the metering namespace containing AWS credentials in the `data.aws-access-key-id` and `data.aws-secret-access-key` fields. See the example secret file below for more details. - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: -data: - aws-access-key-id: "dGVzdAo=" - aws-secret-access-key: "c2VjcmV0Cg==" ----- - -To store data in S3, the `aws-access-key-id` and `aws-secret-access-key` credentials must have read and write access to the bucket. For an example of an IAM policy granting the required permissions, see the `aws/read-write.json` file below. - -[source,json] ----- -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "1", - "Effect": "Allow", - "Action": [ - "s3:AbortMultipartUpload", - "s3:DeleteObject", - "s3:GetObject", - "s3:HeadBucket", - "s3:ListBucket", - "s3:ListMultipartUploadParts", - "s3:PutObject" - ], - "Resource": [ - "arn:aws:s3:::operator-metering-data/*", <1> - "arn:aws:s3:::operator-metering-data" <1> - ] - } - ] -} -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "1", - "Effect": "Allow", - "Action": [ - "s3:AbortMultipartUpload", - "s3:DeleteObject", - "s3:GetObject", - "s3:HeadBucket", - "s3:ListBucket", - "s3:ListMultipartUploadParts", - "s3:PutObject" - ], - "Resource": [ - "arn:aws:s3:::operator-metering-data/*", <1> - "arn:aws:s3:::operator-metering-data" <1> - ] - } - ] -} ----- -<1> Replace `operator-metering-data` with the name of your bucket. - -This can be done either pre-installation or post-installation. Disabling it post-installation can cause errors in the `reporting-operator`. diff --git a/metering/configuring_metering/metering-configure-hive-metastore.adoc b/metering/configuring_metering/metering-configure-hive-metastore.adoc deleted file mode 100644 index 8ab5c8bffc12..000000000000 --- a/metering/configuring_metering/metering-configure-hive-metastore.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="metering-configure-hive-metastore"] -= Configuring the Hive metastore -include::modules/common-attributes.adoc[] -:context: metering-configure-hive-metastore - -toc::[] - -Hive metastore is responsible for storing all the metadata about the database tables created in Presto and Hive. By default, the metastore stores this information in a local embedded Derby database in a `PersistentVolume` attached to the pod. - -Generally, the default configuration of the Hive metastore works for small clusters, but users may wish to improve performance or move storage requirements out of cluster by using a dedicated SQL database for storing the Hive metastore data. - -include::modules/metering-configure-persistentvolumes.adoc[leveloffset=+1] - -include::modules/metering-use-mysql-or-postgresql-for-hive.adoc[leveloffset=+1] diff --git a/metering/configuring_metering/metering-configure-persistent-storage.adoc b/metering/configuring_metering/metering-configure-persistent-storage.adoc deleted file mode 100644 index 557d7b9a5da0..000000000000 --- a/metering/configuring_metering/metering-configure-persistent-storage.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="metering-configure-persistent-storage"] -= Configuring persistent storage -include::modules/common-attributes.adoc[] -:context: metering-configure-persistent-storage - -toc::[] - -Metering requires persistent storage to persist data collected by the `metering-operator` and to store the results of reports. A number of different storage providers and storage formats are supported. Select your storage provider and modify the example configuration files to configure persistent storage for your metering installation. - -include::modules/metering-store-data-in-s3.adoc[leveloffset=+1] - -include::modules/metering-store-data-in-s3-compatible.adoc[leveloffset=+1] - -include::modules/metering-store-data-in-azure.adoc[leveloffset=+1] - -include::modules/metering-store-data-in-gcp.adoc[leveloffset=+1] - -include::modules/metering-store-data-in-shared-volumes.adoc[leveloffset=+1] diff --git a/metering/configuring_metering/metering-configure-reporting-operator.adoc b/metering/configuring_metering/metering-configure-reporting-operator.adoc deleted file mode 100644 index e2fb9f5a5f33..000000000000 --- a/metering/configuring_metering/metering-configure-reporting-operator.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="metering-configure-reporting-operator"] -= Configuring the reporting-operator -include::modules/common-attributes.adoc[] -:context: metering-configure-reporting-operator - -toc::[] - -The `reporting-operator` is responsible for collecting data from Prometheus, storing the metrics in Presto, running report queries against Presto, and exposing their results via an HTTP API. Configuring the Operator is primarily done through your `MeteringConfig` file. - -include::modules/metering-prometheus-connection.adoc[leveloffset=+1] - -include::modules/metering-exposing-the-reporting-api.adoc[leveloffset=+1] diff --git a/metering/configuring_metering/modules b/metering/configuring_metering/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/metering/configuring_metering/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/metering/metering-about-metering.adoc b/metering/metering-about-metering.adoc deleted file mode 100644 index 8dbbc05b7dfd..000000000000 --- a/metering/metering-about-metering.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="about-metering"] -= About Metering -include::modules/common-attributes.adoc[] -:context: about-metering - -toc::[] - -include::modules/metering-overview.adoc[leveloffset=+1] diff --git a/metering/metering-installing-metering.adoc b/metering/metering-installing-metering.adoc deleted file mode 100644 index a27f8b559e51..000000000000 --- a/metering/metering-installing-metering.adoc +++ /dev/null @@ -1,57 +0,0 @@ -[id="installing-metering"] -= Installing metering -include::modules/common-attributes.adoc[] -:context: installing-metering - -toc::[] - -Review the following sections before installing metering into your cluster. - -To get started installing metering, first install the Metering Operator from OperatorHub. Next, configure your instance of metering by creating a `CustomResource`, referred to here as your MeteringConfig. Installing the Metering Operator creates a default MeteringConfig that you can modify using the examples in the documentation. After creating your MeteringConfig, install the metering stack. Last, verify your installation. - -include::modules/metering-install-prerequisites.adoc[leveloffset=+1] - -include::modules/metering-install-operator.adoc[leveloffset=+1] - -// Including this content directly in the assembly because the workflow requires linking off to the config docs, and we don't current link -// inside of modules - klamenzo 2019-09-23 -[id="metering-install-metering-stack_{context}"] -== Installing the metering stack - -After adding the Metering Operator to your cluster you can install the components of metering by installing the metering stack. - -== Prerequisites - -* Review the xref:../metering/configuring_metering/metering-about-configuring.adoc#metering-about-configuring[configuration options] -* Create a MeteringConfig resource. You can begin the following process to generate a default MeteringConfig, then use the examples in the documentation to modify this default file for your specific installation. Review the following topics to create your MeteringConfig resource: -** For configuration options, review xref:../metering/configuring_metering/metering-about-configuring.adoc#metering-about-configuring[About configuring metering]. -** At a minimum, you need to xref:../metering/configuring_metering/metering-configure-persistent-storage.adoc#metering-configure-persistent-storage[configure persistent storage] and xref:../metering/configuring_metering/metering-configure-hive-metastore.adoc#metering-configure-hive-metastore[configure the Hive metastore]. - -[IMPORTANT] -==== -There can only be one MeteringConfig resource in the `openshift-metering` namespace. Any other configuration is not supported. -==== - -.Procedure - -. From the web console, ensure you are on the *Operator Details* page for the Metering Operator in the `openshift-metering` project. You can navigate to this page by clicking *Operators* -> *Installed Operators*, then selecting the Metering Operator. - -. Under *Provided APIs*, click *Create Instance* on the Metering Configuration card. This opens a YAML editor with the default MeteringConfig file where you can define your configuration. -+ -[NOTE] -==== -For example configuration files and all supported configuration options, review the xref:../metering/configuring_metering/metering-about-configuring.adoc#metering-about-configuring[configuring metering documentation]. -==== - -. Enter your MeteringConfig into the YAML editor and click *Create*. - -The MeteringConfig resource begins to create the necessary resources for your metering stack. You can now move on to verifying your installation. - -include::modules/metering-install-verify.adoc[leveloffset=+1] - -[id="metering-install-additional-resources_{context}"] -== Additional resources - -* For more information on configuration steps and available storage platforms, see xref:../metering/configuring_metering/metering-configure-persistent-storage.adoc#metering-configure-persistent-storage[Configuring persistent storage]. - -* For the steps to configure Hive, see xref:../metering/configuring_metering/metering-configure-hive-metastore.adoc#metering-configure-hive-metastore[Configuring the Hive metastore]. diff --git a/metering/metering-troubleshooting-debugging.adoc b/metering/metering-troubleshooting-debugging.adoc deleted file mode 100644 index 364909ad42c1..000000000000 --- a/metering/metering-troubleshooting-debugging.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="metering-troubleshooting-debugging"] -= Troubleshooting and debugging metering -include::modules/common-attributes.adoc[] -:context: metering-troubleshooting-debugging - -toc::[] - -Use the following sections to help troubleshoot and debug specific issues with metering. - -In addition to the information in this section, be sure to review the following topics: - -* xref:../metering/metering-installing-metering.adoc#metering-install-prerequisites_installing-metering[Prerequisites for installing metering]. -* xref:../metering/configuring_metering/metering-about-configuring.adoc#metering-about-configuring[About configuring metering] - -include::modules/metering-troubleshooting.adoc[leveloffset=+1] - -include::modules/metering-debugging.adoc[leveloffset=+1] diff --git a/metering/metering-uninstall.adoc b/metering/metering-uninstall.adoc deleted file mode 100644 index 5adf6c1e640d..000000000000 --- a/metering/metering-uninstall.adoc +++ /dev/null @@ -1,31 +0,0 @@ -:context: metering-uninstall -[id="metering-uninstall"] -= Uninstalling metering -include::modules/common-attributes.adoc[] - -toc::[] - -You can remove metering from your {product-title} cluster. - -[NOTE] -==== -Metering does not manage or delete Amazon S3 bucket data. After uninstalling metering, -you must manually clean up S3 buckets that were used to store metering data. -==== - -[id="metering-remove"] -== Removing the Metering Operator from your cluster - -Remove the Metering Operator from your cluster by following the documentation on -xref:../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[deleting Operators from a cluster]. - -[NOTE] -==== -Removing the Metering Operator from your cluster does not remove its CustomResourceDefinitions or managed resources. See the following sections on xref:../metering/metering-uninstall.adoc#metering-uninstall_metering-uninstall[Uninstalling a metering namespace] -and xref:../metering/metering-uninstall.adoc#metering-uninstall-crds_metering-uninstall[Uninstalling metering CustomResourceDefinitions] -for steps to remove any remaining metering components. -==== - -include::modules/metering-uninstall.adoc[leveloffset=+1] - -include::modules/metering-uninstall-crds.adoc[leveloffset=+1] diff --git a/metering/metering-upgrading-metering.adoc b/metering/metering-upgrading-metering.adoc deleted file mode 100644 index 306b4ec4ed54..000000000000 --- a/metering/metering-upgrading-metering.adoc +++ /dev/null @@ -1,144 +0,0 @@ -[id="upgrading-metering"] -= Upgrading metering -include::modules/common-attributes.adoc[] -:context: upgrading-metering - -toc::[] - -You can upgrade metering to {product-version} by updating the Metering Operator subscription. - -== Prerequisites - -* The cluster is updated to 4.7. -* The xref:../metering/metering-installing-metering.adoc#metering-install-operator_installing-metering[Metering Operator] is installed from OperatorHub. -+ -[NOTE] -==== -You must upgrade the Metering Operator to {product-version} manually. Metering does not upgrade automatically if you selected the "Automatic" *Approval Strategy* in a previous installation. -==== -* The xref:../metering/configuring_metering/metering-about-configuring.adoc#metering-about-configuring[MeteringConfig] is configured. -* The xref:../metering/metering-installing-metering.adoc#metering-install-metering-stack_installing-metering[metering stack] is installed. -* Ensure that metering status is healthy by checking that all Pods are ready. - -[IMPORTANT] -==== -Potential data loss can occur if you modify your metering storage configuration after installing or upgrading metering. -==== - -.Procedure - -. Click *Operators* -> *Installed Operators* from the web console. - -. Select the `openshift-metering` Project. - -. Click *Metering Operator*. - -. Click *Subscription* -> *Channel*. - -. In the *Change Subscription Update Channel* window, select *{product-version}* and click *Save*. -+ -[NOTE] -==== -Wait several seconds to allow the subscription to update before proceeding to the next step. -==== -. Click *Operators* -> *Installed Operators*. -+ -The Metering Operator is shown as 4.7. For example: -+ ----- -Metering -4.7.0-202007012112.p0 provided by Red Hat, Inc ----- - -.Verification -You can verify the metering upgrade by performing any of the following checks: - -* Check the Metering Operator ClusterServiceVersion (CSV) for the new metering version. This can be done through either the web console or CLI. -+ --- -.Procedure (UI) - . Navigate to *Operators* -> *Installed Operators* in the metering namespace. - . Click *Metering Operator*. - . Click *Subscription* for *Subscription Details*. - . Check the *Installed Version* for the upgraded metering version. The *Starting Version* shows the metering version prior to upgrading. - -.Procedure (CLI) -* Check the Metering Operator CSV: -+ -[source,terminal] ----- -$ oc get csv | grep metering ----- -+ -.Example output for metering upgrade from 4.6 to 4.7 -[source,terminal] ----- -NAME DISPLAY VERSION REPLACES PHASE -metering-operator.4.7.0-202007012112.p0 Metering 4.7.0-202007012112.p0 metering-operator.4.6.0-202007012112.p0 Succeeded ----- --- - -* Check that all required Pods in the `openshift-metering` namespace are created. This can be done through either the web console or CLI. -+ --- -[NOTE] -==== -Many Pods rely on other components to function before they themselves can be considered ready. Some Pods may restart if other Pods take too long to start. This is to be expected during the Metering Operator upgrade. -==== - -.Procedure (UI) -* Navigate to *Workloads* -> *Pods* in the metering namespace and verify that Pods are being created. This can take several minutes after upgrading the metering stack. - -.Procedure (CLI) -* Check that all required Pods in the `openshift-metering` namespace are created: -+ -[source,terminal] ----- -$ oc -n openshift-metering get pods ----- -.Example output -[source,terminal] -+ ----- -NAME READY STATUS RESTARTS AGE -hive-metastore-0 2/2 Running 0 3m28s -hive-server-0 3/3 Running 0 3m28s -metering-operator-68dd64cfb6-2k7d9 2/2 Running 0 5m17s -presto-coordinator-0 2/2 Running 0 3m9s -reporting-operator-5588964bf8-x2tkn 2/2 Running 0 2m40s ----- --- - -* Verify that the `ReportDataSources` are importing new data, indicated by a valid timestamp in the `NEWEST METRIC` column. This might take several minutes. Filter out the "-raw" `ReportDataSources`, which do not import data: -+ -[source,terminal] ----- -$ oc get reportdatasources -n openshift-metering | grep -v raw ----- -+ -Timestamps in the `NEWEST METRIC` column indicate that `ReportDataSources` are beginning to import new data. -+ -.Example output -[source,terminal] ----- -NAME EARLIEST METRIC NEWEST METRIC IMPORT START IMPORT END LAST IMPORT TIME AGE -node-allocatable-cpu-cores 2020-05-18T21:10:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:56:44Z 23h -node-allocatable-memory-bytes 2020-05-18T21:10:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:52:07Z 23h -node-capacity-cpu-cores 2020-05-18T21:10:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:56:52Z 23h -node-capacity-memory-bytes 2020-05-18T21:10:00Z 2020-05-19T19:57:00Z 2020-05-18T19:10:00Z 2020-05-19T19:57:00Z 2020-05-19T19:57:03Z 23h -persistentvolumeclaim-capacity-bytes 2020-05-18T21:09:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:56:46Z 23h -persistentvolumeclaim-phase 2020-05-18T21:10:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:52:36Z 23h -persistentvolumeclaim-request-bytes 2020-05-18T21:10:00Z 2020-05-19T19:57:00Z 2020-05-18T19:10:00Z 2020-05-19T19:57:00Z 2020-05-19T19:57:03Z 23h -persistentvolumeclaim-usage-bytes 2020-05-18T21:09:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:52:02Z 23h -pod-limit-cpu-cores 2020-05-18T21:10:00Z 2020-05-19T19:57:00Z 2020-05-18T19:10:00Z 2020-05-19T19:57:00Z 2020-05-19T19:57:02Z 23h -pod-limit-memory-bytes 2020-05-18T21:10:00Z 2020-05-19T19:58:00Z 2020-05-18T19:11:00Z 2020-05-19T19:58:00Z 2020-05-19T19:59:06Z 23h -pod-persistentvolumeclaim-request-info 2020-05-18T21:10:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:52:07Z 23h -pod-request-cpu-cores 2020-05-18T21:10:00Z 2020-05-19T19:58:00Z 2020-05-18T19:11:00Z 2020-05-19T19:58:00Z 2020-05-19T19:58:57Z 23h -pod-request-memory-bytes 2020-05-18T21:10:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:55:32Z 23h -pod-usage-cpu-cores 2020-05-18T21:09:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:54:55Z 23h -pod-usage-memory-bytes 2020-05-18T21:08:00Z 2020-05-19T19:52:00Z 2020-05-18T19:11:00Z 2020-05-19T19:52:00Z 2020-05-19T19:55:00Z 23h -report-ns-pvc-usage 5h36m -report-ns-pvc-usage-hourly ----- - -After all Pods are ready and you have verified that new data is being imported, metering continues to collect data and report on your cluster. Review a previously xref:../metering/reports/metering-about-reports.adoc#metering-example-report-with-schedule_metering-about-reports[scheduled Report] or create a xref:../metering/reports/metering-about-reports.adoc#metering-example-report-without-schedule_metering-about-reports[Run-Once metering Report] to confirm the metering upgrade. diff --git a/metering/metering-usage-examples.adoc b/metering/metering-usage-examples.adoc deleted file mode 100644 index 8ac4cdd8f7e8..000000000000 --- a/metering/metering-usage-examples.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="metering-usage-examples"] -= Examples of using metering -include::modules/common-attributes.adoc[] -:context: metering-usage-examples - -toc::[] - -Use the following example Reports to get started measuring capacity, usage, and utilization in your cluster. These examples showcase the various types of reports metering offers, along with a selection of the predefined queries. - -== Prerequisites -* xref:../metering/metering-installing-metering.adoc#metering-install-operator_installing-metering[Install Metering] -* Review the details about xref:../metering/metering-using-metering#using-metering[writing and viewing reports]. - -include::modules/metering-cluster-capacity-examples.adoc[leveloffset=+1] - -include::modules/metering-cluster-usage-examples.adoc[leveloffset=+1] - -include::modules/metering-cluster-utilization-examples.adoc[leveloffset=+1] diff --git a/metering/metering-using-metering.adoc b/metering/metering-using-metering.adoc deleted file mode 100644 index f1f04c0b7fe2..000000000000 --- a/metering/metering-using-metering.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="using-metering"] -= Using Metering -include::modules/common-attributes.adoc[] -:context: using-metering - -toc::[] - -== Prerequisites - -* xref:../metering/metering-installing-metering.adoc#metering-install-operator_installing-metering[Install Metering] -* Review the details about the available options that can be configured for a xref:../metering/reports/metering-about-reports.adoc#metering-about-reports[Report] and how they function. - -include::modules/metering-writing-reports.adoc[leveloffset=+1] - -include::modules/metering-viewing-report-results.adoc[leveloffset=+1] diff --git a/metering/reports/metering-about-reports.adoc b/metering/reports/metering-about-reports.adoc deleted file mode 100644 index b103c9b8ad1c..000000000000 --- a/metering/reports/metering-about-reports.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="metering-about-reports"] -= About Reports -include::modules/common-attributes.adoc[] -:context: metering-about-reports - -toc::[] - -A Report is an API object that provides a method to manage periodic ETL (Extract Transform and Load) jobs using SQL queries. -They are composed using other Metering resources such as `ReportQueries`, which provide the actual SQL query to run, and `ReportDataSources`, which are what define the data available to the ReportQueries and Reports. - -Many use cases are addressed out-of-the-box with the predefined `ReportQueries` and `ReportDataSources` that come installed with metering, so you do not need to define your own unless you have a use-case not covered by what is predefined. - -include::modules/metering-reports.adoc[leveloffset=+1] diff --git a/metering/reports/metering-storage-locations.adoc b/metering/reports/metering-storage-locations.adoc deleted file mode 100644 index 90d31ff07434..000000000000 --- a/metering/reports/metering-storage-locations.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id="metering-storage-locations"] -= Storage Locations -include::modules/common-attributes.adoc[] -:context: metering-storage-locations - -toc::[] - -A StorageLocation is a custom resource that configures where data will be stored by the reporting-operator. This includes the data collected from Prometheus, and the results produced by generating a Report custom resource. - -You only need to configure a StorageLocation if you want to store data in multiple locations, like multiple S3 buckets or both S3 and HDFS, or if you wish to access a database in Hive/Presto that was not created by metering. For most users this is not a requirement, and the xref:../../metering/configuring_metering/metering-about-configuring.adoc#metering-about-configuring[documentation on configuring metering] is sufficent to configure all necessary storage components. - -== StorageLocation examples - -This first example is what the built-in local storage option looks like. It is configured to use Hive, and by default data is stored wherever Hive is configured to use storage (HDFS, S3, or a ReadWriteMany PVC). - -.Local storage example -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: StorageLocation -metadata: - name: hive - labels: - operator-metering: "true" -spec: - hive: <1> - databaseName: metering <2> - unmanagedDatabase: false <3> ----- - -<1> If the `hive` section is present, then the StorageLocation will be configured to store data in Presto by creating the table using Hive server. Only databaseName and unmanagedDatabase are required fields. -<2> The name of the database within hive. -<3> If `true`, then this StorageLocation will not be actively managed, and the databaseName is expected to already exist in Hive. If `false`, this will cause the reporting-operator to create the database in Hive. - -The next example uses an AWS S3 bucket for storage. The prefix is appended to the bucket name when constructing the path to use. - -.Remote storage example -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: StorageLocation -metadata: - name: example-s3-storage - labels: - operator-metering: "true" -spec: - hive: - databaseName: example_s3_storage - unmanagedDatabase: false - location: "s3a://bucket-name/path/within/bucket" <1> ----- -<1> (optional) The filesystem URL for Presto and Hive to use for the database. This can be an `hdfs://` or `s3a://` filesystem URL. - -There are some additional optional fields that can be specified in the `hive` section: - -* (optional) defaultTableProperties: Contains configuration options for creating tables using Hive. -* (optional) fileFormat: The file format used for storing files in the filesystem. See the link:https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL#LanguageManualDDL-StorageFormatsStorageFormatsRowFormat,StorageFormat,andSerDe[Hive Documentation on File Storage Format] for a list of options and more details. -* (optional) rowFormat: Controls the link:https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL#LanguageManualDDL-RowFormats&SerDe[ Hive row format]. This controls how Hive serializes and deserializes rows. See the link:https://cwiki.apache.org/confluence/display/Hive/LanguageManual+DDL#LanguageManualDDL-RowFormats&SerDe[Hive Documentation on Row Formats and SerDe] for more details. - -== Default StorageLocation -If an annotation `storagelocation.metering.openshift.io/is-default` exists and is set to `true` on a StorageLocation resource, then that resource becomes the default storage resource. Any components with a storage configuration option where StorageLocation is not specified will use the default storage resource. There can be only one default storage resource. If more than one resource with the annotation exists, an error is logged because the Operator cannot determine the default. - -.Default storage example -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: StorageLocation -metadata: - name: example-s3-storage - labels: - operator-metering: "true" - annotations: - storagelocation.metering.openshift.io/is-default: "true" -spec: - hive: - databaseName: example_s3_storage - unmanagedDatabase: false - location: "s3a://bucket-name/path/within/bucket" ----- diff --git a/metering/reports/modules b/metering/reports/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/metering/reports/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/metrics/PLACEHOLDER b/metrics/PLACEHOLDER deleted file mode 100644 index 4020393e57eb..000000000000 --- a/metrics/PLACEHOLDER +++ /dev/null @@ -1,2 +0,0 @@ -Please delete this file once you have assemblies here. - diff --git a/metrics/images b/metrics/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/metrics/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/metrics/modules b/metrics/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/metrics/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/migration/migrating_3_4/about-migration.adoc b/migration/migrating_3_4/about-migration.adoc deleted file mode 100644 index a7220596d806..000000000000 --- a/migration/migrating_3_4/about-migration.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="about-migration"] -= About migrating {product-title} 3 to 4 -include::modules/common-attributes.adoc[] -:context: about-migration - -toc::[] - -{product-title} 4 includes new technologies and functionality that results in a cluster that is self-managing, flexible, and automated. The way that {product-title} 4 clusters are deployed and managed drastically differs from {product-title} 3. - -To successfully transition from {product-title} 3 to {product-title} 4, it is important that you review the following information: - -xref:../../migration/migrating_3_4/planning-migration-3-to-4.adoc#planning-migration-3-to-4[Planning your transition]:: -Learn about the differences between {product-title} versions 3 and 4. Prior to transitioning, be sure that you have reviewed and prepared for storage, networking, logging, security, and monitoring considerations. - -xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migrating-application-workloads-3-4[Performing your migration]:: -Learn about and use the tools to perform your migration: - -* {mtc-full} ({mtc-short}) to migrate your application workloads -* Control Plane Migration Assistant (CPMA) to migrate your control plane diff --git a/migration/migrating_3_4/configuring-replication-repository-3-4.adoc b/migration/migrating_3_4/configuring-replication-repository-3-4.adoc deleted file mode 100644 index 592fc33148cf..000000000000 --- a/migration/migrating_3_4/configuring-replication-repository-3-4.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id='configuring-replication-repository'] -= Configuring a replication repository -include::modules/common-attributes.adoc[] -:context: migrating-3-4 -:migrating-3-4: - -toc::[] - -You must configure an object storage to use as a replication repository. The {mtc-full} ({mtc-short}) copies data from the source cluster to the replication repository, and then from the replication repository to the target cluster. - -{mtc-short} supports the xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migration-understanding-data-copy-methods_migrating-3-4[file system and snapshot data copy methods] for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider. - -The following storage providers are supported: - -* xref:../../migration/migrating_3_4/configuring-replication-repository-3-4.adoc#migration-configuring-mcg_migrating-3-4[Multi-Cloud Object Gateway (MCG)] -* xref:../../migration/migrating_3_4/configuring-replication-repository-3-4.adoc#migration-configuring-aws-s3_migrating-3-4[Amazon Web Services (AWS) S3] -* xref:../../migration/migrating_3_4/configuring-replication-repository-3-4.adoc#migration-configuring-gcp_migrating-3-4[Google Cloud Provider (GCP)] -* xref:../../migration/migrating_3_4/configuring-replication-repository-3-4.adoc#migration-configuring-azure_migrating-3-4[Microsoft Azure] -* Generic S3 object storage, for example, Minio or Ceph S3 - -The source and target clusters must have network access to the replication repository during migration. - -In a restricted environment, you can create an internally hosted replication repository. If you use a proxy server, you must ensure that your replication repository is allowed. - -ifeval::["{product-version}" == "4.2"] -:FeatureName: Configuring Multi-Cloud Object Gateway as a replication repository for migration -include::modules/technology-preview.adoc[leveloffset=+1] -endif::[] - -include::modules/migration-configuring-mcg.adoc[leveloffset=+1] -include::modules/migration-configuring-aws-s3.adoc[leveloffset=+1] -include::modules/migration-configuring-gcp.adoc[leveloffset=+1] -include::modules/migration-configuring-azure.adoc[leveloffset=+1] - -:!migrating-3-4: diff --git a/migration/migrating_3_4/deploying-cam-3-4.adoc b/migration/migrating_3_4/deploying-cam-3-4.adoc deleted file mode 100644 index 5ac0269ba741..000000000000 --- a/migration/migrating_3_4/deploying-cam-3-4.adoc +++ /dev/null @@ -1,68 +0,0 @@ -[id='deploying-cam-3-4'] -= Deploying the Migration Toolkit for Containers -include::modules/common-attributes.adoc[] -:context: migrating-3-4 -:migrating-3-4: - -toc::[] - -You can deploy the {mtc-full} ({mtc-short}) on an {product-title} {product-version} target cluster and an {product-title} 3 source cluster by installing the {mtc-full} Operator. - -[NOTE] -==== -{mtc-short} is installed on the target cluster by default. - -You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on an {product-title} 3 cluster or on a remote cluster]. -==== - -In a restricted environment, you can install the {mtc-full} Operator from a local mirror registry. - -After you have installed the {mtc-full} Operator on your clusters, you can launch the {mtc-short} console. - -[id='installing-cam-operator_{context}'] -== Installing the {mtc-full} Operator - -You can install the {mtc-full} Operator with the Operator Lifecycle Manager (OLM) on an {product-title} {product-version} target cluster and manually on an {product-title} 3 source cluster. - -[IMPORTANT] -==== -You must ensure that the same Operator version is installed on the source and target clusters. -==== - -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -include::modules/migration-installing-cam-operator-ocp-3.adoc[leveloffset=+2] -:!migrating-3-4: - -:context: disconnected-3-4 -:disconnected-3-4: -[id='installing-cam-operator_{context}'] -== Installing the {mtc-full} Operator in a restricted environment - -You can install the {mtc-full} Operator with the Operator Lifecycle Manager (OLM) on an {product-title} {product-version} target cluster and manually on an {product-title} 3 source cluster. - -For {product-title} {product-version}, you can build a custom Operator catalog image, push it to a local mirror image registry, and configure OLM to install the {mtc-full} Operator from the local registry. A `mapping.txt` file is created when you run the `oc adm catalog mirror` command. - -On the {product-title} 3 cluster, you can create a manifest file based on the Operator image and edit the file to point to your local image registry. The `image` value in the manifest file uses the `sha256` value from the `mapping.txt` file. Then, you can use the local image to create the {mtc-full} Operator. - -.Additional resources - -* xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] - -[id='installing-cam-operator-prereq_{context}'] -=== Prerequisites - -* If you want to prune the default catalog and selectively mirror only a subset of Operators, install the xref:../../cli_reference/opm-cli.adoc#opm-cli[`opm` CLI]. - -include::modules/olm-restricted-networks-configuring-operatorhub.adoc[leveloffset=+2] -include::modules/olm-pruning-index-image.adoc[leveloffset=+2] -include::modules/olm-mirroring-catalog.adoc[leveloffset=+2] -include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+2] - -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -include::modules/migration-installing-cam-operator-ocp-3.adoc[leveloffset=+2] -:!disconnected-3-4: - -:context: migrating-3-4 -:migrating-3-4: -include::modules/migration-launching-cam.adoc[leveloffset=+1] -:!migrating-3-4: diff --git a/migration/migrating_3_4/images b/migration/migrating_3_4/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/migration/migrating_3_4/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/migration/migrating_3_4/migrating-application-workloads-3-4.adoc b/migration/migrating_3_4/migrating-application-workloads-3-4.adoc deleted file mode 100644 index 4fd62ea6314e..000000000000 --- a/migration/migrating_3_4/migrating-application-workloads-3-4.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id="migrating-application-workloads-3-4"] -= About the {mtc-full} -include::modules/common-attributes.adoc[] -:context: migrating-3-4 -:migrating-3-4: - -toc::[] - -You can migrate application workloads from {product-title} 3.7, 3.9, 3.10, and 3.11 to {product-title} {product-version} with the {mtc-full} ({mtc-short}). {mtc-short} enables you to control the migration and to minimize application downtime. - -[NOTE] -==== -{mtc-short} is installed on the target cluster by default. - -You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on an {product-title} 3 cluster or on a remote cluster]. -==== - -The {mtc-short} web console and API, based on Kubernetes custom resources, enable you to migrate stateful application workloads at the granularity of a namespace. - -{mtc-short} supports the file system and snapshot data copy methods for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider. - -You can use migration hooks to run Ansible playbooks at certain points during the migration. The hooks are added when you create a migration plan. - -[NOTE] -==== -The service catalog is deprecated in {product-title} 4. You can migrate workload resources provisioned with the service catalog from {product-title} 3 to 4 but you cannot perform service catalog actions such as `provision`, `deprovision`, or `update` on these workloads after migration. - -The {mtc-short} web console displays a message if the service catalog resources cannot be migrated. -==== - -The Control Plane Migration Assistant (CPMA) is a CLI-based tool that assists you in migrating the control plane. The CPMA processes the {product-title} 3 configuration files and generates custom resource manifest files, which are consumed by {product-title} {product-version} Operators. - -[IMPORTANT] -==== -Before you begin your migration, be sure to review the information on xref:../../migration/migrating_3_4/planning-migration-3-to-4.adoc#planning-migration-3-to-4[planning your migration]. -==== - -include::modules/migration-mtc-workflow.adoc[leveloffset=+1] -include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1] -include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1] -include::modules/migration-about-migration-hooks.adoc[leveloffset=+1] -include::modules/migration-understanding-cpma.adoc[leveloffset=+1] -:!migrating-3-4: diff --git a/migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc b/migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc deleted file mode 100644 index b7e146382dc3..000000000000 --- a/migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id='migrating-applications-with-cam_{context}'] -= Migrating your applications -include::modules/common-attributes.adoc[] -:context: migrating-3-4 -:migrating-3-4: - -toc::[] - -You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or on the command line. - -include::modules/migration-prerequisites.adoc[leveloffset=+1] -include::modules/migration-creating-ca-bundle.adoc[leveloffset=+2] -include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] - -[id="migrating-applications-additional-resources_{context}"] -=== Additional resources - -* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migration-about-migration-hooks_migrating-3-4[About migration hooks] -* xref:../../migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc#mighook_migrating-3-4[MigHook custom resource] -* xref:../../migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc#migplan_migrating-3-4[MigPlan custom resource] - -[id="migrating-applications-mtc-web-console_{context}"] -== Migrating your applications by using the {mtc-short} web console - -You can configure clusters and a replication repository by using the {mtc-short} web console. Then, you can create and run a migration plan. - -include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+2] -include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+2] -include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+2] -include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+2] - -[id="migrating-applications-mtc-cli_{context}"] -== Migrating your applications on the command line - -You can migrate your applications on the command line by using the {mtc-short} custom resources (CRs). - -You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters. - -[discrete] -=== {mtc-short} terminology - -The following terms are relevant for configuring clusters: - -* `host` cluster: -** The `migration-controller` pod runs on the `host` cluster. -** A `host` cluster does not require an exposed secure registry route for direct image migration. -* Local cluster: The local cluster is often the same as the `host` cluster but this is not a requirement. -* Remote cluster: -** A remote cluster must have an exposed secure registry route for direct image migration. -** A remote cluster must have a `Secret` CR containing the `migration-controller` service account token. - -The following terms are relevant for performing a migration: - -* Source cluster: Cluster from which the applications are migrated. -* Destination cluster: Cluster to which the applications are migrated. - -include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] -include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2] - -[id="migrating-applications-mtc-cli-additional-resources_{context}"] -== Additional resources - -* xref:../../registry/securing-exposing-registry.adoc#registry-exposing-secure-registry-manually_securing-exposing-registry[Exposing a secure registry manually on an {product-title} 4 cluster] -* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#file-system-copy-method_migrating-3-4[{mtc-short} file system copy method] -* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#snapshot-copy-method_migrating-3-4[{mtc-short} snapshot copy method] -* xref:../../migration/migrating_3_4/troubleshooting-3-4.adoc#migration-viewing-migration-crs_migrating-3-4[Viewing migration custom resources] - -[id='configuring-migration-plan_{context}'] -== Configuring a migration plan - -You can increase the number of objects to be migrated or exclude resources from the migration. - -If you are migrating internal images that are deprecated in {product-title} 4, you can update the images and push them to the target cluster registry. - -include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2] -include::modules/migration-excluding-resources.adoc[leveloffset=+2] -include::modules/migration-updating-internal-images.adoc[leveloffset=+2] - -:!migrating-3-4: diff --git a/migration/migrating_3_4/migrating-with-cpma.adoc b/migration/migrating_3_4/migrating-with-cpma.adoc deleted file mode 100644 index 3812e9f90324..000000000000 --- a/migration/migrating_3_4/migrating-with-cpma.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id='migrating-with-cpma'] -= Migrating your control plane settings -include::modules/common-attributes.adoc[] -:context: migrating-3-4 -:migrating-3-4: - -toc::[] - -The Control Plane Migration Assistant (CPMA) is a CLI-based tool that assists you in migrating the control plane from {product-title} 3.7 (or later) to {product-version}. The CPMA processes the {product-title} 3 configuration files and generates custom resource manifest files, which are consumed by {product-title} {product-version} Operators. - -include::modules/migration-installing-cpma.adoc[leveloffset=+1] -include::modules/migration-using-cpma.adoc[leveloffset=+1] -:!migrating-3-4: diff --git a/migration/migrating_3_4/modules b/migration/migrating_3_4/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/migration/migrating_3_4/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/migration/migrating_3_4/planning-migration-3-to-4.adoc b/migration/migrating_3_4/planning-migration-3-to-4.adoc deleted file mode 100644 index 4afc22ee7903..000000000000 --- a/migration/migrating_3_4/planning-migration-3-to-4.adoc +++ /dev/null @@ -1,217 +0,0 @@ -[id="planning-migration-3-to-4"] -= Planning your migration -include::modules/common-attributes.adoc[] -:context: planning-migration-3-to-4 - -toc::[] - -Before performing your migration to {product-title} {product-version}, it is important to take the time to properly plan for the transition. {product-title} 4 introduces architectural changes and enhancements, so the procedures that you used to manage your {product-title} 3 cluster might not apply for {product-title} 4. - -[NOTE] -==== -This planning document assumes that you are transitioning from {product-title} 3.11 to {product-title} {product-version}. -==== - -ifndef::openshift-origin[] -This document provides high-level information on the most important xref:../../migration/migrating_3_4/planning-migration-3-to-4.adoc#migration-comparing-ocp-3-4[differences between {product-title} 3 and {product-title} 4] and the most noteworthy xref:../../migration/migrating_3_4/planning-migration-3-to-4.adoc#migration-considerations[migration considerations]. For detailed information on configuring your {product-title} 4 cluster, review the appropriate sections of the {product-title} documentation. For detailed information on new features and other notable technical changes, review the xref:../../release_notes/ocp-4-8-release-notes.adoc#ocp-4-8-release-notes[OpenShift Container Platform 4.8 release notes]. -endif::[] - -It is not possible to upgrade your existing {product-title} 3 cluster to {product-title} 4. You must start with a new {product-title} 4 installation. Tools are available to assist in migrating your control plane settings and application workloads. - -[id="migration-comparing-ocp-3-4"] -== Comparing {product-title} 3 and {product-title} 4 -With {product-title} 3, administrators individually deployed {op-system-base-full} hosts, and then installed {product-title} on top of these hosts to form a cluster. Administrators were responsible for properly configuring these hosts and performing updates. - -{product-title} 4 represents a significant change in the way that {product-title} clusters are deployed and managed. {product-title} 4 includes new technologies and functionality, such as Operators, machine sets, and {op-system-first}, which are core to the operation of the cluster. This technology shift enables clusters to self-manage some functions previously performed by administrators. This also ensures platform stability and consistency, and simplifies installation and scaling. - -For more information, see xref:../../architecture/architecture.adoc#architecture[OpenShift Container Platform architecture]. - -[id="migration-differences-architecture"] -=== Architecture differences - -[discrete] -==== Immutable infrastructure - -{product-title} 4 uses {op-system-first}, which is designed to run containerized applications, and provides efficient installation, Operator-based management, and simplified upgrades. {op-system} is an immutable container host, rather than a customizable operating system like {op-system-base}. {op-system} enables {product-title} 4 to manage and automate the deployment of the underlying container host. {op-system} is a part of {product-title}, which means that everything runs inside a container and is deployed using {product-title}. - -In {product-title} 4, control plane nodes must run {op-system}, ensuring that full-stack automation is maintained for the control plane. This makes rolling out updates and upgrades a much easier process than in {product-title} 3. - -For more information, see xref:../../architecture/architecture-rhcos.adoc#architecture-rhcos[{op-system-first}]. - -[discrete] -==== Operators - -Operators are a method of packaging, deploying, and managing a Kubernetes application. Operators ease the operational complexity of running another piece of software. They watch over your environment and use the current state to make decisions in real time. Advanced Operators are designed to upgrade and react to failures automatically. - -For more information, see xref:../../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Understanding Operators]. - -[id="migration-differences-install"] -=== Installation and update differences - -[discrete] -==== Installation process - -To install {product-title} 3.11, you prepared your {op-system-base-full} hosts, set all of the configuration values your cluster needed, and then ran an Ansible playbook to install and set up your cluster. - -In {product-title} {product-version}, you use the OpenShift installation program to create a minimum set of resources required for a cluster. Once the cluster is running, you use Operators to further configure your cluster and to install new services. After first boot, {op-system-first} systems are managed by the Machine Config Operator (MCO) that runs in the {product-title} cluster. - -For more information, see xref:../../architecture/architecture-installation.adoc#installation-process_architecture-installation[Installation process]. - -ifndef::openshift-origin[] -If you want to add {op-system-base-full} ({op-system-base}) worker machines to your {product-title} {product-version} cluster, you use an Ansible playbook to join the {op-system-base} worker machines after the cluster is running. For more information, see xref:../../machine_management/user_infra/adding-rhel-compute.adoc#adding-rhel-compute[Adding {op-system-base} compute machines to an {product-title} cluster]. -endif::[] - -[discrete] -==== Infrastructure options - -In {product-title} 3.11, you installed your cluster on infrastructure that you prepared and maintained. In addition to providing your own infrastructure, {product-title} 4 offers an option to deploy a cluster on infrastructure that the {product-title} installation program provisions and the cluster maintains. - -For more information, see xref:../../architecture/architecture-installation.adoc#installation-overview_architecture-installation[OpenShift Container Platform installation overview]. - -[discrete] -==== Upgrading your cluster - -In {product-title} 3.11, you upgraded your cluster by running Ansible playbooks. In {product-title} {product-version}, the cluster manages its own updates, including updates to {op-system-first} on cluster nodes. You can easily upgrade your cluster by using the web console or by using the `oc adm upgrade` command from the OpenShift CLI and the Operators will automatically upgrade themselves. If your {product-title} {product-version} cluster has {op-system-base} worker machines, then you will still need to run an Ansible playbook to upgrade those worker machines. - -For more information, see xref:../../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[Updating clusters]. - -[id="migration-considerations"] -== Migration considerations - -Review the changes and other considerations that might affect your transition from {product-title} 3.11 to {product-title} 4. - -[id="migration-preparing-storage"] -=== Storage considerations - -Review the following storage changes to consider when transitioning from {product-title} 3.11 to {product-title} {product-version}. - -[discrete] -==== Local volume persistent storage - -Local storage is only supported by using the Local Storage Operator in {product-title} {product-version}. It is not supported to use the local provisioner method from {product-title} 3.11. - -For more information, see xref:../../storage/persistent_storage/persistent-storage-local.adoc#persistent-storage-using-local-volume[Persistent storage using local volumes]. - -[discrete] -==== FlexVolume persistent storage - -The FlexVolume plug-in location changed from {product-title} 3.11. The new location in {product-title} {product-version} is `/etc/kubernetes/kubelet-plugins/volume/exec`. Attachable FlexVolume plug-ins are no longer supported. - -For more information, see xref:../../storage/persistent_storage/persistent-storage-flexvolume.adoc#persistent-storage-using-flexvolume[Persistent storage using FlexVolume]. - -[discrete] -==== Container Storage Interface (CSI) persistent storage - -Persistent storage using the Container Storage Interface (CSI) was link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] in {product-title} 3.11. CSI version 1.1.0 is fully supported in {product-title} {product-version}, but does not ship with any CSI drivers. You must install your own driver. - -For more information, see xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-using-csi[Persistent storage using the Container Storage Interface (CSI)]. - -[discrete] -==== Red Hat OpenShift Container Storage - -Red Hat OpenShift Container Storage 3, which is available for use with {product-title} 3.11, uses Red Hat Gluster Storage as the backing storage. - -Red Hat OpenShift Container Storage 4, which is available for use with {product-title} 4, uses Red Hat Ceph Storage as the backing storage. - -For more information, see xref:../../storage/persistent_storage/persistent-storage-ocs.adoc#red-hat-openshift-container-storage[Persistent storage using Red Hat OpenShift Container Storage] and the link:https://access.redhat.com/articles/4731161[interoperability matrix] article. - -[discrete] -==== Unsupported persistent storage options - -Support for the following persistent storage options from {product-title} 3.11 has changed in {product-title} {product-version}: - -* GlusterFS is no longer supported. -* CephFS as a standalone product is no longer supported. -* Ceph RBD as a standalone product is no longer supported. - -If you used one of these in {product-title} 3.11, you must choose a different persistent storage option for full support in {product-title} {product-version}. - -For more information, see xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage]. - -[id="migration-preparing-networking"] -=== Networking considerations - -Review the following networking changes to consider when transitioning from {product-title} 3.11 to {product-title} {product-version}. - -[discrete] -==== Network isolation mode - -The default network isolation mode for {product-title} 3.11 was `ovs-subnet`, though users frequently switched to use `ovn-multitenant`. The default network isolation mode for {product-title} {product-version} is controlled by a network policy. - -If your {product-title} 3.11 cluster used the `ovs-subnet` or `ovs-multitenant` mode, it is recommended to switch to a network policy for your {product-title} {product-version} cluster. Network policies are supported upstream, are more flexible, and they provide the functionality that `ovs-multitenant` does. If you want to maintain the `ovs-multitenant` behavior while using a network policy in {product-title} {product-version}, follow the steps to xref:../../networking/network_policy/multitenant-network-policy.adoc#multitenant-network-policy[configure multitenant isolation using network policy]. - -For more information, see xref:../../networking/network_policy/about-network-policy.adoc#about-network-policy[About network policy]. - -[discrete] -==== Encrypting traffic between hosts - -In {product-title} 3.11, you could use IPsec to encrypt traffic between hosts. {product-title} {product-version} does not support IPsec. It is recommended to use Red Hat OpenShift Service Mesh to enable mutual TLS between services. - -ifndef::openshift-origin[] -For more information, see xref:../../service_mesh/v1x/ossm-architecture.adoc#ossm-architecture-v1x[Understanding Red Hat OpenShift Service Mesh]. -endif::[] - -[id="migration-preparing-logging"] -=== Logging considerations - -Review the following logging changes to consider when transitioning from {product-title} 3.11 to {product-title} {product-version}. - -[discrete] -==== Deploying OpenShift Logging - -{product-title} 4 provides a simple deployment mechanism for OpenShift Logging, by using a Cluster Logging custom resource. - -For more information, see xref:../../logging/cluster-logging-deploying.adoc#cluster-logging-deploying_cluster-logging-deploying[Installing OpenShift Logging]. - -[discrete] -==== Aggregated logging data - -You cannot transition your aggregate logging data from {product-title} 3.11 into your new {product-title} 4 cluster. - -For more information, see xref:../../logging/cluster-logging.adoc#cluster-logging-about_cluster-logging[About OpenShift Logging]. - -[discrete] -==== Unsupported logging configurations - -Some logging configurations that were available in {product-title} 3.11 are no longer supported in {product-title} {product-version}. - -For more information on the explicitly unsupported logging cases, see xref:../../logging/config/cluster-logging-maintenance-support.adoc#cluster-logging-maintenance-and-support[Maintenance and support]. - -[id="migration-preparing-security"] -=== Security considerations - -Review the following security changes to consider when transitioning from {product-title} 3.11 to {product-title} {product-version}. - -[discrete] -==== Unauthenticated access to discovery endpoints - -In {product-title} 3.11, an unauthenticated user could access the discovery endpoints (for example, [x-]`/api/*` and [x-]`/apis/*`). For security reasons, unauthenticated access to the discovery endpoints is no longer allowed in {product-title} {product-version}. If you do need to allow unauthenticated access, you can configure the RBAC settings as necessary; however, be sure to consider the security implications as this can expose internal cluster components to the external network. - -// TODO: Anything to xref to, or additional details? - -[discrete] -==== Identity providers - -Configuration for identity providers has changed for {product-title} 4, including the following notable changes: - -* The request header identity provider in {product-title} {product-version} requires mutual TLS, where in {product-title} 3.11 it did not. -* The configuration of the OpenID Connect identity provider was simplified in {product-title} {product-version}. It now obtains data, which previously had to specified in {product-title} 3.11, from the provider's `/.well-known/openid-configuration` endpoint. - -For more information, see xref:../../authentication/understanding-identity-provider.adoc#understanding-identity-provider[Understanding identity provider configuration]. - -[discrete] -==== OAuth token storage format - -Newly created OAuth HTTP bearer tokens no longer match the names of their OAuth access token objects. The object names are now a hash of the bearer token and are no longer sensitive. This reduces the risk of leaking sensitive information. - -[id="migration-preparing-monitoring"] -=== Monitoring considerations - -Review the following monitoring changes to consider when transitioning from {product-title} 3.11 to {product-title} {product-version}. - -[discrete] -==== Alert for monitoring infrastructure availability - -The default alert that triggers to ensure the availability of the monitoring structure was called `DeadMansSwitch` in {product-title} 3.11. This was renamed to `Watchdog` in {product-title} 4. If you had PagerDuty integration set up with this alert in {product-title} 3.11, you must set up the PagerDuty integration for the `Watchdog` alert in {product-title} 4. - -For more information, see xref:../../monitoring/managing-alerts.adoc#applying-custom-alertmanager-configuration_managing-alerts[Applying custom Alertmanager configuration]. diff --git a/migration/migrating_3_4/troubleshooting-3-4.adoc b/migration/migrating_3_4/troubleshooting-3-4.adoc deleted file mode 100644 index c65d46d7f6aa..000000000000 --- a/migration/migrating_3_4/troubleshooting-3-4.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id='troubleshooting-3-4'] -= Troubleshooting -include::modules/common-attributes.adoc[] -:context: migrating-3-4 -:migrating-3-4: - -toc::[] - -You can view the {mtc-full} ({mtc-short}) custom resources and download logs to troubleshoot a failed migration. - -If the application was stopped during the failed migration, you must roll it back manually to prevent data corruption. - -[NOTE] -==== -Manual rollback is not required if the application was not stopped during migration because the original application is still running on the source cluster. -==== - -include::modules/migration-viewing-migration-crs.adoc[leveloffset=+1] -include::modules/migration-using-mig-log-reader.adoc[leveloffset=+1] -include::modules/migration-downloading-logs.adoc[leveloffset=+1] -include::modules/migration-updating-deprecated-gvks.adoc[leveloffset=+1] -include::modules/migration-error-messages.adoc[leveloffset=+1] -include::modules/migration-dvm-error-node-selectors.adoc[leveloffset=+1] -include::modules/migration-debugging-velero-resources.adoc[leveloffset=+1] -include::modules/migration-partial-failure-velero.adoc[leveloffset=+2] -include::modules/migration-using-must-gather.adoc[leveloffset=+1] - -[id="rolling-back-migration_{context}"] -== Rolling back a migration - -You can roll back a migration by using the {mtc-short} web console or the CLI. - -include::modules/migration-rolling-back-migration-web-console.adoc[leveloffset=+2] -include::modules/migration-rolling-back-migration-cli.adoc[leveloffset=+2] - -include::modules/migration-known-issues.adoc[leveloffset=+1] - -[id="troubleshooting-additional-resources_{context}"] -== Additional resources - -* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migration-mtc-workflow_migrating-3-4[{mtc-short} workflow] -* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migration-mtc-custom-resources_migrating-3-4[{mtc-short} custom resources] - -:!migrating-3-4: diff --git a/migration/migrating_3_4/upgrading-migration-tool-3-4.adoc b/migration/migrating_3_4/upgrading-migration-tool-3-4.adoc deleted file mode 100644 index c132335e083d..000000000000 --- a/migration/migrating_3_4/upgrading-migration-tool-3-4.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id='upgrading-migration-tool-3-4'] -= Upgrading the Migration Toolkit for Containers -include::modules/common-attributes.adoc[] -:context: migrating-3-4 -:migrating-3-4: - -toc::[] - -You can upgrade the {mtc-full} ({mtc-short}) by installing the latest {mtc-full} Operator. - -[IMPORTANT] -==== -You must ensure that the same Operator version is installed on the source and target clusters. - -Do not enable automatic updates on the {product-title} {product-version} cluster. -==== - -If you are upgrading {mtc-short} 1.3, you must perform an additional procedure to update the `MigPlan` custom resource (CR). - -include::modules/migration-upgrading-migration-tool-4.adoc[leveloffset=+1] -include::modules/migration-upgrading-migration-tool-3.adoc[leveloffset=+1] -include::modules/migration-upgrading-from-mtc-1-3.adoc[leveloffset=+1] -:migrating-3-4!: diff --git a/migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc b/migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc deleted file mode 100644 index 53db0e6b7fdd..000000000000 --- a/migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id='configuring-replication-repository-4-1-4'] -= Configuring a replication repository -include::modules/common-attributes.adoc[] -:context: migrating-4-1-4 -:migrating-4-1-4: - -toc::[] - -You must configure an object storage to use as a replication repository. The {mtc-full} ({mtc-short}) copies data from the source cluster to the replication repository, and then from the replication repository to the target cluster. - -{mtc-short} supports the xref:../../migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc#migration-understanding-data-copy-methods_migrating-4-1-4[file system and snapshot data copy methods] for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider. - -The following storage providers are supported: - -* xref:../../migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc#migration-configuring-mcg_migrating-4-1-4[Multi-Cloud Object Gateway (MCG)] -* xref:../../migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc#migration-configuring-aws-s3_migrating-4-1-4[Amazon Web Services (AWS) S3] -* xref:../../migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc#migration-configuring-gcp_migrating-4-1-4[Google Cloud Provider (GCP)] -* xref:../../migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc#migration-configuring-azure_migrating-4-1-4[Microsoft Azure] -* Generic S3 object storage, for example, Minio or Ceph S3 - -The source and target clusters must have network access to the replication repository during migration. - -In a restricted environment, you can create an internally hosted replication repository. If you use a proxy server, you must ensure that your replication repository is allowed. - -ifeval::["{product-version}" == "4.2"] -:FeatureName: Configuring Multi-Cloud Object Gateway as a replication repository for migration -include::modules/technology-preview.adoc[leveloffset=+1] -endif::[] - -include::modules/migration-configuring-mcg.adoc[leveloffset=+1] -include::modules/migration-configuring-aws-s3.adoc[leveloffset=+1] -include::modules/migration-configuring-gcp.adoc[leveloffset=+1] -include::modules/migration-configuring-azure.adoc[leveloffset=+1] - -:!migrating-4-1-4: diff --git a/migration/migrating_4_1_4/deploying-cam-4-1-4.adoc b/migration/migrating_4_1_4/deploying-cam-4-1-4.adoc deleted file mode 100644 index c797d341519f..000000000000 --- a/migration/migrating_4_1_4/deploying-cam-4-1-4.adoc +++ /dev/null @@ -1,72 +0,0 @@ -[id='deploying-cam-4-1-4'] -= Deploying the Migration Toolkit for Containers -include::modules/common-attributes.adoc[] -:context: migrating-4-1-4 -:migrating-4-1-4: - -toc::[] - -You can install the {mtc-full} Operator on your {product-title} {product-version} target cluster and 4.1 source cluster. The {mtc-full} Operator installs the {mtc-full} ({mtc-short}) on the target cluster by default. - -[NOTE] -==== -Optional: You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on an {product-title} 3 cluster or on a remote cluster]. -==== - -In a restricted environment, you can install the {mtc-full} Operator from a local mirror registry. - -After you have installed the {mtc-full} Operator on your clusters, you can launch the {mtc-short} web console. - -== Installing the {mtc-full} Operator - -You can install the {mtc-full} Operator with the Operator Lifecycle Manager on an {product-title} {product-version} target cluster and on an {product-title} 4.1 source cluster. - -:!migrating-4-1-4: - -:context: target-4-1-4 -:target-4-1-4: -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -:target-4-1-4!: - -:context: source-4-1-4 -:source-4-1-4: -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -:source-4-1-4!: - -:context: disconnected-4-1-4 -:disconnected-4-1-4: - -== Installing the {mtc-full} Operator in a restricted environment - -You can build a custom Operator catalog image for {product-title} 4, push it to a local mirror image registry, and configure the Operator Lifecycle Manager to install the {mtc-full} Operator from the local registry. - -.Additional resources - -* xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] - -[id='installing-cam-operator-prereq_{context}'] -=== Prerequisites - -* If you want to prune the default catalog and selectively mirror only a subset of Operators, install the xref:../../cli_reference/opm-cli.adoc#opm-cli[`opm` CLI]. - -include::modules/olm-restricted-networks-configuring-operatorhub.adoc[leveloffset=+2] -include::modules/olm-pruning-index-image.adoc[leveloffset=+2] -include::modules/olm-mirroring-catalog.adoc[leveloffset=+2] -include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+2] - -:!disconnected-4-1-4: - -:context: disconnected-target-4-1-4 -:disconnected-target-4-1-4: -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -:disconnected-target-4-1-4!: - -:context: disconnected-source-4-1-4 -:disconnected-source-4-1-4: -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -:disconnected-source-4-1-4!: - -:context: migrating-4-1-4 -:migrating-4-1-4: -include::modules/migration-launching-cam.adoc[leveloffset=+1] -:!migrating-4-1-4: diff --git a/migration/migrating_4_1_4/images b/migration/migrating_4_1_4/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/migration/migrating_4_1_4/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc b/migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc deleted file mode 100644 index d6ccf52c0ea6..000000000000 --- a/migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="migrating-application-workloads-4-1-4"] -= About the {mtc-full} -include::modules/common-attributes.adoc[] -:context: migrating-4-1-4 -:migrating-4-1-4: - -toc::[] - -You can migrate application workloads from {product-title} 4.1 to {product-version} with the {mtc-full} ({mtc-short}). {mtc-short} enables you to control the migration and to minimize application downtime. - -[NOTE] -==== -You can migrate between {product-title} clusters of the same version, for example, from 4.1 to 4.1, as long as the source and target clusters are configured correctly. - -{mtc-short} is installed on the target cluster by default. You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on a remote cluster]. -==== - -The {mtc-short} web console and API, based on Kubernetes custom resources, enable you to migrate stateful and stateless application workloads at the granularity of a namespace. - -{mtc-short} supports the file system and snapshot data copy methods for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider. - -You can use migration hooks to run Ansible playbooks at certain points during the migration. The hooks are added when you create a migration plan. - -include::modules/migration-mtc-workflow.adoc[leveloffset=+1] -include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1] -include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1] -include::modules/migration-about-migration-hooks.adoc[leveloffset=+1] -:!migrating-4-1-4: diff --git a/migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc b/migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc deleted file mode 100644 index 17fb53bc9bbb..000000000000 --- a/migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc +++ /dev/null @@ -1,76 +0,0 @@ -[id='migrating-applications-with-cam-4-1-4'] -= Migrating your applications -include::modules/common-attributes.adoc[] -:context: migrating-4-1-4 -:migrating-4-1-4: - -toc::[] - -You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or on the command line. - -include::modules/migration-prerequisites.adoc[leveloffset=+1] -include::modules/migration-creating-ca-bundle.adoc[leveloffset=+2] -include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] - -[id="migrating-applications-additional-resources_{context}"] -=== Additional resources - -* xref:../../migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc#migration-about-migration-hooks_migrating-4-1-4[About migration hooks] -* xref:../../migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc#mighook_migrating-4-1-4[MigHook custom resource] -* xref:../../migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc#migplan_migrating-4-1-4[MigPlan custom resource] - -[id="migrating-applications-mtc-web-console_{context}"] -== Migrating your applications using the {mtc-short} web console - -You can configure clusters and a replication repository by using the {mtc-short} web console. Then, you can create and run a migration plan. - -include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+2] -include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+2] -include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+2] -include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+2] - -[id="migrating-applications-mtc-cli_{context}"] -== Migrating your applications on the command line - -You can migrate your applications on the command line by using the {mtc-short} custom resources (CRs). - -You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters. - -[discrete] -=== {mtc-short} terminology - -The following terms are relevant for configuring clusters: - -* `host` cluster: -** The `migration-controller` pod runs on the `host` cluster. -** A `host` cluster does not require an exposed secure registry route for direct image migration. -* Local cluster: The local cluster is often the same as the `host` cluster but this is not a requirement. -* Remote cluster: -** A remote cluster must have an exposed secure registry route for direct image migration. -** A remote cluster must have a `Secret` CR containing the `migration-controller` service account token. - -The following terms are relevant for performing a migration: - -* Source cluster: Cluster from which the applications are migrated. -* Destination cluster: Cluster to which the applications are migrated. - -include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] -include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2] - -[id="migrating-applications-mtc-cli-additional-resources_{context}"] -== Additional resources - -* xref:../../registry/securing-exposing-registry.adoc#registry-exposing-secure-registry-manually_securing-exposing-registry[Exposing a secure registry manually on an {product-title} 4 cluster] -* xref:../../migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc#file-system-copy-method_migrating-4-1-4[{mtc-short} file system copy method] -* xref:../../migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc#snapshot-copy-method_migrating-4-1-4[{mtc-short} snapshot copy method] -* xref:../../migration/migrating_4_1_4/troubleshooting-4-1-4.adoc#migration-viewing-migration-crs_migrating-4-1-4[Viewing migration custom resources] - -[id='configuring-migration-plan_{context}'] -== Configuring a migration plan - -You can increase the number of objects to be migrated or exclude resources from the migration. - -include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2] -include::modules/migration-excluding-resources.adoc[leveloffset=+2] - -:!migrating-4-1-4: diff --git a/migration/migrating_4_1_4/modules b/migration/migrating_4_1_4/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/migration/migrating_4_1_4/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/migration/migrating_4_1_4/troubleshooting-4-1-4.adoc b/migration/migrating_4_1_4/troubleshooting-4-1-4.adoc deleted file mode 100644 index f955aa668057..000000000000 --- a/migration/migrating_4_1_4/troubleshooting-4-1-4.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id='troubleshooting-4-1-4'] -= Troubleshooting -include::modules/common-attributes.adoc[] -:context: migrating-4-1-4 -:migrating-4-1-4: - -toc::[] - -You can view the {mtc-full} ({mtc-short}) custom resources and download logs to troubleshoot a failed migration. - -If the application was stopped during the failed migration, you must roll back the migration to prevent data corruption. - -[NOTE] -==== -Manual rollback is not required if the application was not stopped during migration because the original application is still running on the source cluster. -==== - -include::modules/migration-viewing-migration-crs.adoc[leveloffset=+1] -include::modules/migration-using-mig-log-reader.adoc[leveloffset=+1] -include::modules/migration-downloading-logs.adoc[leveloffset=+1] -include::modules/migration-error-messages.adoc[leveloffset=+1] -include::modules/migration-dvm-error-node-selectors.adoc[leveloffset=+1] -include::modules/migration-debugging-velero-resources.adoc[leveloffset=+1] -include::modules/migration-partial-failure-velero.adoc[leveloffset=+2] -include::modules/migration-using-must-gather.adoc[leveloffset=+1] - -[id="rolling-back-migration_{context}"] -== Rolling back a migration - -You can roll back a migration by using the {mtc-short} web console or the CLI. - -include::modules/migration-rolling-back-migration-web-console.adoc[leveloffset=+2] -include::modules/migration-rolling-back-migration-cli.adoc[leveloffset=+2] - -include::modules/migration-known-issues.adoc[leveloffset=+1] - -[id="troubleshooting-additional-resources_{context}"] -== Additional resources - -* xref:../../migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc#migration-mtc-workflow_migrating-4-1-4[{mtc-short} workflow] -* xref:../../migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc#migration-mtc-custom-resources_migrating-4-1-4[{mtc-short} custom resources] - -:!migrating-4-1-4: diff --git a/migration/migrating_4_1_4/upgrading-migration-tool-4-1-4.adoc b/migration/migrating_4_1_4/upgrading-migration-tool-4-1-4.adoc deleted file mode 100644 index 65dc89f4774f..000000000000 --- a/migration/migrating_4_1_4/upgrading-migration-tool-4-1-4.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id='upgrading-migration-tool-4-1-4'] -= Upgrading the Migration Toolkit for Containers -include::modules/common-attributes.adoc[] -:context: migrating-4-1-4 -:migrating-4-1-4: - -toc::[] - -You can upgrade the {mtc-full} ({mtc-short}) by upgrading the {mtc-full} Operator. - -If you are upgrading {mtc-short} 1.3, you must perform an additional procedure to update the `MigPlan` custom resource (CR). - -include::modules/migration-upgrading-migration-tool-4.adoc[leveloffset=+1] -include::modules/migration-upgrading-from-mtc-1-3.adoc[leveloffset=+1] -:migrating-4-1-4!: diff --git a/migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc b/migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc deleted file mode 100644 index a00f54972fbe..000000000000 --- a/migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id='configuring-replication-repository-4-2-4'] -= Configuring a replication repository -include::modules/common-attributes.adoc[] -:context: migrating-4-2-4 -:migrating-4-2-4: - -toc::[] - -You must configure an object storage to use as a replication repository. The {mtc-full} ({mtc-short}) copies data from the source cluster to the replication repository, and then from the replication repository to the target cluster. - -{mtc-short} supports the xref:../../migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc#migration-understanding-data-copy-methods_migrating-4-2-4[file system and snapshot data copy methods] for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider. - -The following storage providers are supported: - -* xref:../../migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc#migration-configuring-mcg_migrating-4-2-4[Multi-Cloud Object Gateway (MCG)] -* xref:../../migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc#migration-configuring-aws-s3_migrating-4-2-4[Amazon Web Services (AWS) S3] -* xref:../../migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc#migration-configuring-gcp_migrating-4-2-4[Google Cloud Provider (GCP)] -* xref:../../migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc#migration-configuring-azure_migrating-4-2-4[Microsoft Azure] -* Generic S3 object storage, for example, Minio or Ceph S3 - -The source and target clusters must have network access to the replication repository during migration. - -In a restricted environment, you can create an internally hosted replication repository. If you use a proxy server, you must ensure that your replication repository is allowed. - -ifeval::["{product-version}" == "4.2"] -:FeatureName: Configuring Multi-Cloud Object Gateway as a replication repository for migration -include::modules/technology-preview.adoc[leveloffset=+1] -endif::[] - -include::modules/migration-configuring-mcg.adoc[leveloffset=+1] -include::modules/migration-configuring-aws-s3.adoc[leveloffset=+1] -include::modules/migration-configuring-gcp.adoc[leveloffset=+1] -include::modules/migration-configuring-azure.adoc[leveloffset=+1] - -:!migrating-4-2-4: diff --git a/migration/migrating_4_2_4/deploying-cam-4-2-4.adoc b/migration/migrating_4_2_4/deploying-cam-4-2-4.adoc deleted file mode 100644 index 95a69cead5b0..000000000000 --- a/migration/migrating_4_2_4/deploying-cam-4-2-4.adoc +++ /dev/null @@ -1,72 +0,0 @@ -[id='deploying-cam-4-2-4'] -= Deploying the Migration Toolkit for Containers -include::modules/common-attributes.adoc[] -:context: migrating-4-2-4 -:migrating-4-2-4: - -toc::[] - -You can install the {mtc-full} Operator on your {product-title} {product-version} target cluster and 4.2 source cluster. The {mtc-full} Operator installs the {mtc-full} ({mtc-short}) on the target cluster by default. - -[NOTE] -==== -Optional: You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on an {product-title} 3 cluster or on a remote cluster]. -==== - -In a restricted environment, you can install the {mtc-full} Operator from a local mirror registry. - -After you have installed the {mtc-full} Operator on your clusters, you can launch the {mtc-short} web console. - -== Installing the {mtc-full} Operator - -You can install the {mtc-full} Operator with the Operator Lifecycle Manager on an {product-title} {product-version} target cluster and on an {product-title} 4.1 source cluster. - -:!migrating-4-2-4: - -:context: target-4-2-4 -:target-4-2-4: -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -:target-4-2-4!: - -:context: source-4-2-4 -:source-4-2-4: -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -:source-4-2-4!: - -:context: disconnected-4-2-4 -:disconnected-4-2-4: - -== Installing the {mtc-full} Operator in a restricted environment - -You can build a custom Operator catalog image for {product-title} 4, push it to a local mirror image registry, and configure the Operator Lifecycle Manager to install the Operator from the local registry. - -.Additional resources - -* xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] - -[id='installing-cam-operator-prereq_{context}'] -=== Prerequisites - -* If you want to prune the default catalog and selectively mirror only a subset of Operators, install the xref:../../cli_reference/opm-cli.adoc#opm-cli[`opm` CLI]. - -include::modules/olm-restricted-networks-configuring-operatorhub.adoc[leveloffset=+2] -include::modules/olm-pruning-index-image.adoc[leveloffset=+2] -include::modules/olm-mirroring-catalog.adoc[leveloffset=+2] -include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+2] - -:!disconnected-4-2-4: - -:context: disconnected-target-4-2-4 -:disconnected-target-4-2-4: -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -:disconnected-target-4-2-4!: - -:context: disconnected-source-4-2-4 -:disconnected-source-4-2-4: -include::modules/migration-installing-cam-operator-ocp-4.adoc[leveloffset=+2] -:disconnected-source-4-2-4!: - -:context: migrating-4-2-4 -:migrating-4-2-4: -include::modules/migration-launching-cam.adoc[leveloffset=+1] -:!migrating-4-2-4: diff --git a/migration/migrating_4_2_4/images b/migration/migrating_4_2_4/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/migration/migrating_4_2_4/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc b/migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc deleted file mode 100644 index 1b2775cf3418..000000000000 --- a/migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="migrating-application-workloads-4-2-4"] -= About the {mtc-full} -include::modules/common-attributes.adoc[] -:context: migrating-4-2-4 -:migrating-4-2-4: - -toc::[] - -You can migrate application workloads from {product-title} 4.2 to {product-version} with the {mtc-full} ({mtc-short}). {mtc-short} enables you to control the migration and to minimize application downtime. - -[NOTE] -==== -You can migrate between {product-title} clusters of the same version, for example, from 4.2 to 4.2 or from 4.3 to 4.3, as long as the source and target clusters are configured correctly. - -{mtc-short} is installed on the target cluster by default. You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on a remote cluster]. -==== - -The {mtc-short} web console and API, based on Kubernetes custom resources, enable you to migrate stateful and stateless application workloads at the granularity of a namespace. - -{mtc-short} supports the file system and snapshot data copy methods for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider. - -You can use migration hooks to run Ansible playbooks at certain points during the migration. The hooks are added when you create a migration plan. - -include::modules/migration-mtc-workflow.adoc[leveloffset=+1] -include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1] -include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1] -include::modules/migration-about-migration-hooks.adoc[leveloffset=+1] -:!migrating-4-2-4: diff --git a/migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc b/migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc deleted file mode 100644 index 54215382b78e..000000000000 --- a/migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc +++ /dev/null @@ -1,75 +0,0 @@ -[id='migrating-applications-with-cam-4-2-4'] -= Migrating your applications -include::modules/common-attributes.adoc[] -:context: migrating-4-2-4 -:migrating-4-2-4: - -toc::[] - -You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or on the command line. - -include::modules/migration-prerequisites.adoc[leveloffset=+1] -include::modules/migration-creating-ca-bundle.adoc[leveloffset=+2] -include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] - -[id="migrating-applications-additional-resources_{context}"] -=== Additional resources - -* xref:../../migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc#migration-about-migration-hooks_migrating-4-2-4[About migration hooks] -* xref:../../migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc#mighook_migrating-4-2-4[MigHook custom resource] -* xref:../../migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc#migplan_migrating-4-2-4[MigPlan custom resource] - -[id="migrating-applications-mtc-web-console_{context}"] -== Migrating your applications by using the {mtc-short} web console - -You can configure clusters and a replication repository by using the {mtc-short} web console. Then, you can create and run a migration plan. - -include::modules/migration-adding-cluster-to-cam.adoc[leveloffset=+2] -include::modules/migration-adding-replication-repository-to-cam.adoc[leveloffset=+2] -include::modules/migration-creating-migration-plan-cam.adoc[leveloffset=+2] -include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+2] - -[id="migrating-applications-mtc-cli_{context}"] -== Migrating your applications on the command line - -You can migrate your applications on the command line by using the {mtc-short} custom resources (CRs). - -You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters. - -[discrete] -=== {mtc-short} terminology - -The following terms are relevant for configuring clusters: - -* `host` cluster: -** The `migration-controller` pod runs on the `host` cluster. -** A `host` cluster does not require an exposed secure registry route for direct image migration. -* Local cluster: The local cluster is often the same as the `host` cluster but this is not a requirement. -* Remote cluster: -** A remote cluster must have an exposed secure registry route for direct image migration. -** A remote cluster must have a `Secret` CR containing the `migration-controller` service account token. - -The following terms are relevant for performing a migration: - -* Source cluster: Cluster from which the applications are migrated. -* Destination cluster: Cluster to which the applications are migrated. - -include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] -include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2] - -[id="migrating-applications-mtc-cli-additional-resources_{context}"] -=== Additional resources - -* xref:../../migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc#migration-about-migration-hooks_migrating-4-2-4[About migration hooks] -* xref:../../migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc#mighook_migrating-4-2-4[MigHook custom resource] -* xref:../../migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc#migplan_migrating-4-2-4[MigPlan custom resource] - -[id='configuring-migration-plan_{context}'] -== Configuring a migration plan - -You can increase the number of objects to be migrated or exclude resources from the migration. - -include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2] -include::modules/migration-excluding-resources.adoc[leveloffset=+2] - -:!migrating-4-2-4: diff --git a/migration/migrating_4_2_4/modules b/migration/migrating_4_2_4/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/migration/migrating_4_2_4/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/migration/migrating_4_2_4/troubleshooting-4-2-4.adoc b/migration/migrating_4_2_4/troubleshooting-4-2-4.adoc deleted file mode 100644 index a636049ec5cd..000000000000 --- a/migration/migrating_4_2_4/troubleshooting-4-2-4.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id='troubleshooting-4-2-4'] -= Troubleshooting -include::modules/common-attributes.adoc[] -:context: migrating-4-2-4 -:migrating-4-2-4: - -toc::[] - -You can view the {mtc-full} ({mtc-short}) custom resources and download logs to troubleshoot a failed migration. - -If the application was stopped during the failed migration, you must roll it back manually to prevent data corruption. - -[NOTE] -==== -Manual rollback is not required if the application was not stopped during migration because the original application is still running on the source cluster. -==== - -include::modules/migration-viewing-migration-crs.adoc[leveloffset=+1] -include::modules/migration-using-mig-log-reader.adoc[leveloffset=+1] -include::modules/migration-downloading-logs.adoc[leveloffset=+1] -include::modules/migration-error-messages.adoc[leveloffset=+1] -include::modules/migration-dvm-error-node-selectors.adoc[leveloffset=+1] -include::modules/migration-debugging-velero-resources.adoc[leveloffset=+1] -include::modules/migration-partial-failure-velero.adoc[leveloffset=+2] -include::modules/migration-using-must-gather.adoc[leveloffset=+1] - -[id="rolling-back-migration_{context}"] -== Rolling back a migration - -You can roll back a migration by using the {mtc-short} web console or the CLI. - -include::modules/migration-rolling-back-migration-web-console.adoc[leveloffset=+2] -include::modules/migration-rolling-back-migration-cli.adoc[leveloffset=+2] - -include::modules/migration-known-issues.adoc[leveloffset=+1] - -[id="troubleshooting-additional-resources_{context}"] -== Additional resources - -* xref:../../migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc#migration-mtc-workflow_migrating-4-2-4[{mtc-short} workflow] -* xref:../../migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc#migration-mtc-custom-resources_migrating-4-2-4[{mtc-short} custom resources] - -:!migrating-4-2-4: diff --git a/migration/migrating_4_2_4/upgrading-migration-tool-4-2-4.adoc b/migration/migrating_4_2_4/upgrading-migration-tool-4-2-4.adoc deleted file mode 100644 index 340804ba1ac4..000000000000 --- a/migration/migrating_4_2_4/upgrading-migration-tool-4-2-4.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id='upgrading-migration-tool-4-2-4'] -= Upgrading the Migration Toolkit for Containers -include::modules/common-attributes.adoc[] -:context: migrating-4-2-4 -:migrating-4-2-4: - -toc::[] - -You can upgrade the {mtc-full} ({mtc-short}) by upgrading the {mtc-full} Operator. - -If you are upgrading {mtc-short} 1.3, you must perform an additional procedure to update the `MigPlan` custom resource (CR). - -include::modules/migration-upgrading-migration-tool-4.adoc[leveloffset=+1] -include::modules/migration-upgrading-from-mtc-1-3.adoc[leveloffset=+1] -:migrating-4-2-4!: diff --git a/mod_docs_guide/getting-started-modular-docs-ocp.adoc b/mod_docs_guide/getting-started-modular-docs-ocp.adoc deleted file mode 100644 index 3f738cd291ba..000000000000 --- a/mod_docs_guide/getting-started-modular-docs-ocp.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Base the file name and the ID on the assembly title. For example: -// * file name: my-assembly-a.adoc -// * ID: [id="my-assembly-a"] -// * Title: = My assembly A - -// Choose a context that is not too long and encapsulates what this assembly or -// module is about. Context MUST be unique. - -// Not sure if this guide is correct with the current guidelines anymore. Need to validate. - -[id="getting-started-modular-docs-ocp"] -= Getting started with modular docs on OpenShift -include::modules/common-attributes.adoc[] -:context: assembly-gsg - -toc::[] - -This is the modular docs getting started guide for the OpenShift documentation -team and anyone who might be contributing content to it. - -This guide has been written using the format of the modular docs -initiative. - -== Prerequisites - -* You have read through and familiarized yourself with the -link:https://redhat-documentation.github.io/modular-docs[Red Hat CCS modular docs guide]. -* You have reviewed -xref:../mod_docs_guide/mod-docs-conventions-ocp.adoc#mod-docs-ocp-references[the Modular Docs OpenShift Conventions]. -* [Optional] You have received the modular docs training. -* You know how to use Git. - -include::modules/creating-your-first-content.adoc[leveloffset=+1] - -// include::modules/mod-docs-ocp-conventions.adoc[leveloffset+=1] diff --git a/mod_docs_guide/images b/mod_docs_guide/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/mod_docs_guide/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/mod_docs_guide/mod-docs-conventions-ocp.adoc b/mod_docs_guide/mod-docs-conventions-ocp.adoc deleted file mode 100644 index c397d327c716..000000000000 --- a/mod_docs_guide/mod-docs-conventions-ocp.adoc +++ /dev/null @@ -1,19 +0,0 @@ - -// Base the file name and the ID on the assembly title. For example: -// * file name: my-assembly-a.adoc -// * ID: [id="my-assembly-a"] -// * Title: = My assembly A - -// Choose a context that is not too long and encapsulates what this assembly or -// module is about. Context MUST be unique across the docs set. - -[id="mod-docs-ocp-references"] -= Modular docs OpenShift conventions -include::modules/common-attributes.adoc[] -:context: assembly-ocp-conventions - -toc::[] - -Before you contribute to the OpenShift docs repo, review the following modular docs conventions. - -include::modules/mod-docs-ocp-conventions.adoc[leveloffset=+1] diff --git a/mod_docs_guide/modules b/mod_docs_guide/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/mod_docs_guide/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/modules/.vale.ini b/modules/.vale.ini new file mode 100644 index 000000000000..219a4063cb3e --- /dev/null +++ b/modules/.vale.ini @@ -0,0 +1,16 @@ +StylesPath = ../.vale/styles + +MinAlertLevel = suggestion + +[[!.]*.adoc] +BasedOnStyles = OpenShiftAsciiDoc, AsciiDoc, RedHat + +# Use local OpenShiftDocs Vocab terms +Vale.Terms = YES +Vale.Avoid = YES + +# Temp values are used for Prow CI comment linting only +[asciidoctor] +temp-ifdef = YES +temp-ifndef = NO +temp-ifeval = temp diff --git a/modules/about-api-token-expiration.adoc b/modules/about-api-token-expiration.adoc new file mode 100644 index 000000000000..14c9a779db31 --- /dev/null +++ b/modules/about-api-token-expiration.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * configure/configure-api-token.adoc +:_mod-docs-content-type: CONCEPT +[id="about-api-token-expiration_{context}"] += About API token expiration + +API tokens expire one year from the creation date. {product-title-short} alerts you in the web interface and by sending log messages to Central when a token will expire in less than one week. The log message process runs once an hour. Once a day, the process lists the tokens that are expiring and creates a log message for each one. Log messages are issued once a day and appear in Central logs. + +Logs have the format as shown in the following example: + +[source,text] +---- +Warn: API Token [token name] (ID [token ID]) will expire in less than X days. +---- + +You can change the default settings for the log message process by configuring the environment variables shown in the following table: + +[cols="1,1,1"] +|=== + +|Environment variable |Default value |Description + +| ROX_TOKEN_EXPIRATION_NOTIFIER_INTERVAL +| 1h (1 hour) +| The frequency at which the log message background loop that lists tokens and creates the logs will run. + +| ROX_TOKEN_EXPIRATION_NOTIFIER_BACKOFF_INTERVAL +| 24h (1 day) +| The frequency at which the loop lists tokens and issues notifications. + +| ROX_TOKEN_EXPIRATION_DETECTION_WINDOW +| 168h (1 week) +| The time period before expiration of the token that will cause the notification to be generated. + +|=== diff --git a/modules/about-crio.adoc b/modules/about-crio.adoc deleted file mode 100644 index 3f7bd1bafd81..000000000000 --- a/modules/about-crio.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-crio-issues.adoc - -[id="about-crio_{context}"] -= About CRI-O container runtime engine - -CRI-O is a Kubernetes-native container runtime implementation that integrates closely with the operating system to deliver an efficient and optimized Kubernetes experience. CRI-O provides facilities for running, stopping, and restarting containers. - -The CRI-O container runtime engine is managed using a systemd service on each {product-title} cluster node. When container runtime issues occur, verify the status of the `crio` systemd service on each node. Gather CRI-O journald unit logs from nodes that manifest container runtime issues. diff --git a/modules/about-etcd-encryption.adoc b/modules/about-etcd-encryption.adoc deleted file mode 100644 index 5ddb988b7844..000000000000 --- a/modules/about-etcd-encryption.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * security/encrypting-etcd.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="about-etcd_{context}"] -= About etcd encryption - -By default, etcd data is not encrypted in {product-title}. You can enable etcd encryption for your cluster to provide an additional layer of data security. For example, it can help protect the loss of sensitive data if an etcd backup is exposed to the incorrect parties. - -When you enable etcd encryption, the following OpenShift API server and Kubernetes API server resources are encrypted: - -* Secrets -* Config maps -* Routes -* OAuth access tokens -* OAuth authorize tokens - -When you enable etcd encryption, encryption keys are created. These keys are rotated on a weekly basis. You must have these keys to restore from an etcd backup. diff --git a/modules/about-gitops.adoc b/modules/about-gitops.adoc deleted file mode 100644 index 9a676003a7a6..000000000000 --- a/modules/about-gitops.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module is included in the following assemblies: -// -// * openshift-docs/cicd/gitops/understanding-openshift-gitops.adoc - -[id="about-gitops_{context}"] -= About GitOps - -GitOps is a declarative way to implement continuous deployment for cloud native applications. You can use GitOps to create repeatable processes for managing OpenShift Container Platform clusters and applications across multi-cluster Kubernetes environments. GitOps handles and automates complex deployments at a fast pace, saving time during deployment and release cycles. - -The GitOps workflow pushes an application through development, testing, staging, and production. GitOps either deploys a new application or updates an existing one, so you only need to update the repository; GitOps automates everything else. - -GitOps is a set of practices that use Git pull requests to manage infrastructure and application configurations. In GitOps, the Git repository is the only source of truth for system and application configuration. This Git repository contains a declarative description of the infrastructure you need in your specified environment and contains an automated process to make your environment match the described state. Also, it contains the entire state of the system so that the trail of changes to the system state are visible and auditable. By using GitOps, you resolve the issues of infrastructure and application configuration sprawl. - -GitOps defines infrastructure and application definitions as code. Then, it uses this code to manage multiple workspaces and clusters to simplify the creation of infrastructure and application configurations. By following the principles of the code, you can store the configuration of clusters and applications in Git repositories, and then follow the Git workflow to apply these repositories to your chosen clusters. You can apply the core principles of developing and maintaining software in a Git repository to the creation and management of your cluster and application configuration files. diff --git a/modules/about-must-gather.adoc b/modules/about-must-gather.adoc deleted file mode 100644 index 647baafc7935..000000000000 --- a/modules/about-must-gather.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-collecting-virt-data.adoc -// * support/gathering-cluster-data.adoc -// * serverless/serverless-support.adoc -// * service_mesh/v1x/servicemesh-release-notes.adoc -// * service_mesh/v2x/servicemesh-release-notes.adoc - -[id="about-must-gather_{context}"] -= About the must-gather tool - -The `oc adm must-gather` CLI command collects the information from your cluster that is most likely needed for debugging issues, such as: - -* Resource definitions -* Audit logs -* Service logs - -You can specify one or more images when you run the command by including the `--image` argument. When you specify an image, the tool collects data related to that feature or product. - -When you run `oc adm must-gather`, a new pod is created on the cluster. The data is collected on that pod and saved in a new directory that starts with `must-gather.local`. This directory is created in the current working directory. - -// todo: table or ref module listing available images? diff --git a/modules/about-project-creation.adoc b/modules/about-project-creation.adoc deleted file mode 100644 index ff2675ef29f6..000000000000 --- a/modules/about-project-creation.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/projects/configuring-project-creation.adoc - -[id="about-project-creation_{context}"] -= About project creation - -The {product-title} API server automatically provisions new projects based on -the project template that is identified by the `projectRequestTemplate` -parameter in the cluster's project configuration resource. If the parameter is -not defined, the API server creates a default template that creates a project -with the requested name, and assigns the requesting user to the `admin` role for -that project. - -When a project request is submitted, the API substitutes the following -parameters into the template: - -.Default project template parameters -[cols="4,8",options="header"] -|=== -|Parameter |Description - -|`PROJECT_NAME` -|The name of the project. Required. - -|`PROJECT_DISPLAYNAME` -|The display name of the project. May be empty. - -|`PROJECT_DESCRIPTION` -|The description of the project. May be empty. - -|`PROJECT_ADMIN_USER` -|The user name of the administrating user. - -|`PROJECT_REQUESTING_USER` -|The user name of the requesting user. -|=== - -Access to the API is granted to developers with the `self-provisioner` role and -the `self-provisioners` cluster role binding. This role is available to all -authenticated developers by default. diff --git a/modules/about-redhat-openshift-gitops.adoc b/modules/about-redhat-openshift-gitops.adoc deleted file mode 100644 index d4316f8ad85d..000000000000 --- a/modules/about-redhat-openshift-gitops.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module is included in the following assemblies: -// -// * openshift-docs/cicd/gitops/understanding-openshift-gitops.adoc - -[id="about-redhat-openshift-gitops_{context}"] -= About {gitops-title} - -{gitops-title} ensures consistency in applications when you deploy them to different clusters in different environments, such as: development, staging, and production. {gitops-title} organizes the deployment process around the configuration repositories and makes them the central element. It always has at least two repositories: - - . Application repository with the source code - . Environment configuration repository that defines the desired state of the application - -These repositories contain a declarative description of the infrastructure you need in your specified environment. They also contain an automated process to make your environment match the described state. - -{gitops-title} uses Argo CD to maintain cluster resources. Argo CD is an open-source declarative tool for the continuous integration and continuous deployment (CI/CD) of applications. {gitops-title} implements Argo CD as a controller so that it continuously monitors application definitions and configurations defined in a Git repository. Then, Argo CD compares the specified state of these configurations with their live state on the cluster. - -Argo CD reports any configurations that deviate from their specified state. These reports allow administrators to automatically or manually resync configurations to the defined state. Therefore, Argo CD enables you to deliver global custom resources, like the resources that are used to configure OpenShift Container Platform clusters. - -[id="key-features_{context}"] -== Key features - -{gitops-title} helps you automate the following tasks: - -* Ensure that the clusters have similar states for configuration, monitoring, and storage -* Recover or recreate clusters from a known state -* Apply or revert configuration changes to multiple OpenShift Container Platform clusters -* Associate templated configuration with different environments -* Promote applications across clusters, from staging to production diff --git a/modules/about-sosreport.adoc b/modules/about-sosreport.adoc deleted file mode 100644 index d2bce3788aab..000000000000 --- a/modules/about-sosreport.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="about-sosreport_{context}"] -= About `sosreport` - -`sosreport` is a tool that collects configuration details, system information, and diagnostic data from {op-system-base-full} and {op-system-first} systems. `sosreport` provides a standardized way to collect diagnostic information relating to a node, which can then be provided to Red Hat Support for issue diagnosis. - -In some support interactions, Red Hat Support may ask you to collect a `sosreport` archive for a specific {product-title} node. For example, it might sometimes be necessary to review system logs or other node-specific data that is not included within the output of `oc adm must-gather`. diff --git a/modules/about-toolbox.adoc b/modules/about-toolbox.adoc deleted file mode 100644 index 41149be18618..000000000000 --- a/modules/about-toolbox.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="about-toolbox_{context}"] -= About `toolbox` - -`toolbox` is a tool that starts a container on a {op-system-first} system. The tool is primarily used to start a container that includes the required binaries and plug-ins that are needed to run commands such as `sosreport` and `redhat-support-tool`. - -The primary purpose for a `toolbox` container is to gather diagnostic information and to provide it to Red Hat Support. However, if additional diagnostic tools are required, you can add RPM packages or run an image that is an alternative to the standard support tools image. diff --git a/modules/access-object-collections.adoc b/modules/access-object-collections.adoc new file mode 100644 index 000000000000..72a5055d23a2 --- /dev/null +++ b/modules/access-object-collections.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/create-use-collections.adoc +:_mod-docs-content-type: PROCEDURE +[id="access-object-collections_{context}"] += Accessing deployment collections + +To use collections, click *Platform Configuration* -> *Collections*. The page displays a list of currently-configured collections. You can perform the following actions: + +* Search for collections by entering text in the *Search by name* field, and then press *->*. +* Click on a collection in the collection list to view the collection in read-only mode. +* Click on {kebab} for an existing collection to edit, clone, or delete it. ++ +[NOTE] +==== +You cannot delete a collection that is actively used in {product-title-short}. +==== +* Click *Create collection* to create a new deployment collection. diff --git a/modules/accessing-an-example-cluster-node-tuning-operator-specification.adoc b/modules/accessing-an-example-cluster-node-tuning-operator-specification.adoc deleted file mode 100644 index 2ddb768ff40a..000000000000 --- a/modules/accessing-an-example-cluster-node-tuning-operator-specification.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/using-node-tuning-operator.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="accessing-an-example-node-tuning-operator-specification_{context}"] -= Accessing an example Node Tuning Operator specification - -Use this process to access an example Node Tuning Operator specification. - -.Procedure - - . Run: -+ -[source,terminal] ----- -$ oc get Tuned/default -o yaml -n openshift-cluster-node-tuning-operator ----- - -The default CR is meant for delivering standard node-level tuning for the {product-title} platform and it can only be modified to set the Operator Management state. Any other custom changes to the default CR will be overwritten by the Operator. For custom tuning, create your own Tuned CRs. Newly created CRs will be combined with the default CR and custom tuning applied to {product-title} nodes based on node or pod labels and profile priorities. - -[WARNING] -==== -While in certain situations the support for pod labels can be a convenient way of automatically delivering required tuning, this practice is discouraged and strongly advised against, especially in large-scale clusters. The default Tuned CR ships without pod label matching. If a custom profile is created with pod label matching, then the functionality will be enabled at that time. The pod label functionality might be deprecated in future versions of the Node Tuning Operator. -==== diff --git a/modules/accessing-delegated-image-scanning.adoc b/modules/accessing-delegated-image-scanning.adoc new file mode 100644 index 000000000000..8ce8ae10f7a4 --- /dev/null +++ b/modules/accessing-delegated-image-scanning.adoc @@ -0,0 +1,8 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: CONCEPT +[id="accessing-delegated-image-scanning_{context}"] += Accessing delegated image scanning + +You can have isolated container image registries that are only accessible from your secured clusters. The delegated image scanning feature enables you to scan images from any registry in your secured clusters. diff --git a/modules/accessing-hosts-on-aws.adoc b/modules/accessing-hosts-on-aws.adoc deleted file mode 100644 index ac973e0f916e..000000000000 --- a/modules/accessing-hosts-on-aws.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/accessing-hosts.adoc - -[id="accessing-hosts-on-aws_{context}"] -= Accessing hosts on Amazon Web Services in an installer-provisioned infrastructure cluster - -The {product-title} installer does not create any public IP addresses for any of -the Amazon Elastic Compute Cloud (Amazon EC2) instances that it provisions for -your {product-title} cluster. To be able to SSH to your {product-title} -hosts, you must follow this procedure. - -.Procedure - -. Create a security group that allows SSH access into the virtual private cloud -(VPC) created by the `openshift-install` command. - -. Create an Amazon EC2 instance on one of the public subnets the installer -created. - -. Associate a public IP address with the Amazon EC2 instance that you created. -+ -Unlike with the {product-title} installation, you should associate the Amazon -EC2 instance you created with an SSH keypair. It does not matter what operating -system you choose for this instance, as it will simply serve as an SSH bastion -to bridge the internet into your {product-title} cluster's VPC. The Amazon -Machine Image (AMI) you use does matter. With {op-system-first}, -for example, you can provide keys via Ignition, like the installer does. - -. Once you provisioned your Amazon EC2 instance and can SSH into it, you must add -the SSH key that you associated with your {product-title} installation. This key -can be different from the key for the bastion instance, but does not have to be. -+ -[NOTE] -==== -Direct SSH access is only recommended for disaster recovery. When the Kubernetes -API is responsive, run privileged pods instead. -==== - -. Run `oc get nodes`, inspect the output, and choose one of the nodes that is a -master. The host name looks similar to `ip-10-0-1-163.ec2.internal`. - -. From the bastion SSH host you manually deployed into Amazon EC2, SSH into that -master host. Ensure that you use the same SSH key you specified during the -installation: -+ -[source,terminal] ----- -$ ssh -i core@ ----- diff --git a/modules/accessing-running-pods.adoc b/modules/accessing-running-pods.adoc deleted file mode 100644 index 78d4ca6085d7..000000000000 --- a/modules/accessing-running-pods.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/investigating-pod-issues.adoc - -[id="accessing-running-pods_{context}"] -= Accessing running pods - -You can review running pods dynamically by opening a shell inside a pod or by gaining network access through port forwarding. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Switch into the project that contains the pod you would like to access. This is necessary because the `oc rsh` command does not accept the `-n` namespace option: -+ -[source,terminal] ----- -$ oc project ----- - -. Start a remote shell into a pod: -+ -[source,terminal] ----- -$ oc rsh <1> ----- -<1> If a pod has multiple containers, `oc rsh` defaults to the first container unless `-c ` is specified. - -. Start a remote shell into a specific container within a pod: -+ -[source,terminal] ----- -$ oc rsh -c pod/ ----- - -. Create a port forwarding session to a port on a pod: -+ -[source,terminal] ----- -$ oc port-forward : <1> ----- -<1> Enter `Ctrl+C` to cancel the port forwarding session. diff --git a/modules/accessing-the-event-logs-in-different-domains.adoc b/modules/accessing-the-event-logs-in-different-domains.adoc new file mode 100644 index 000000000000..801151eaf129 --- /dev/null +++ b/modules/accessing-the-event-logs-in-different-domains.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// *operating/using-the-administration-events-page.adoc + +:_mod-docs-content-type: PROCEDURE +[id="accessing-the-event-logs-in-different-domains_{context}"] += Accessing the event logs in different domains + +By viewing the administration events page, you can access various event logs in different domains. + +.Procedure + +* In the {product-title-short} platform, go to *Platform Configuration -> Administration Events*. \ No newline at end of file diff --git a/modules/accessing-windows-node-using-rdp.adoc b/modules/accessing-windows-node-using-rdp.adoc deleted file mode 100644 index 63b2fda63822..000000000000 --- a/modules/accessing-windows-node-using-rdp.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc - -[id="accessing-windows-node-using-rdp_{context}"] -= Accessing a Windows node using RDP - -You can access a Windows node by using a Remote Desktop Protocol (RDP). - -.Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You have created a Windows machine set. -* You have added the key used in the `cloud-private-key` secret and the key used when creating the cluster to the ssh-agent. For security reasons, remember to remove the keys from the ssh-agent after use. -* You have connected to the Windows node link:https://access.redhat.com/solutions/4073041[using an `ssh-bastion` pod]. - -.Procedure - -. Run the following command to set up an SSH tunnel: -+ -[source,terminal] ----- -$ ssh -L 2020::3389 \ <1> - core@$(oc get service --all-namespaces -l run=ssh-bastion -o go-template="{{ with (index (index .items 0).status.loadBalancer.ingress 0) }}{{ or .hostname .ip }}{{end}}") ----- -<1> Specify the internal IP address of the node, which can be discovered by running the following command: -+ -[source,terminal] ----- -$ oc get nodes -o jsonpath={.status.addresses[?\(@.type==\"InternalIP\"\)].address} ----- - -. From within the resulting shell, SSH into the Windows node and run the following command to create a password for the user: -+ -[source,terminal] ----- -C:\> net user * <1> ----- -<1> Specify the cloud provider user name, such as `Administrator` for AWS or `capi` for Azure. - -You can now remotely access the Windows node at `localhost:2020` using an RDP client. diff --git a/modules/accessing-windows-node-using-ssh.adoc b/modules/accessing-windows-node-using-ssh.adoc deleted file mode 100644 index dc3acde52efb..000000000000 --- a/modules/accessing-windows-node-using-ssh.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc - -[id="accessing-windows-node-using-ssh_{context}"] -= Accessing a Windows node using SSH - -You can access a Windows node by using a secure shell (SSH). - -.Prerequisites - -* You have installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You have created a Windows machine set. -* You have added the key used in the `cloud-private-key` secret and the key used when creating the cluster to the ssh-agent. For security reasons, remember to remove the keys from the ssh-agent after use. -* You have connected to the Windows node link:https://access.redhat.com/solutions/4073041[using an `ssh-bastion` pod]. - -.Procedure - -* Access the Windows node by running the following command: -+ -[source,terminal] ----- -$ ssh -t -o StrictHostKeyChecking=no -o ProxyCommand='ssh -A -o StrictHostKeyChecking=no \ - -o ServerAliveInterval=30 -W %h:%p core@$(oc get service --all-namespaces -l run=ssh-bastion \ - -o go-template="{{ with (index (index .items 0).status.loadBalancer.ingress 0) }}{{ or .hostname .ip }}{{end}}")' @ <1> <2> ----- -<1> Specify the cloud provider username, such as `Administrator` for Amazon Web Services (AWS) or `capi` for Microsoft Azure. -<2> Specify the internal IP address of the node, which can be discovered by running the following command: -+ -[source,terminal] ----- -$ oc get nodes -o jsonpath={.status.addresses[?\(@.type==\"InternalIP\"\)].address} ----- diff --git a/modules/acs-architecture-connections.adoc b/modules/acs-architecture-connections.adoc new file mode 100644 index 000000000000..550662a8865d --- /dev/null +++ b/modules/acs-architecture-connections.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// * architecture/acs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-architecture-connections_{context}"] += {product-title-short} connection protocols and default ports + +Components of {product-title-short} use various default ports and connection protocols. Depending on your system and firewall configuration, you might need to configure your firewall to allow traffic on certain ports. + +The following table provides default ports and protocols for some connections within {product-title-short} and between {product-title-short} and external components. This is helpful for configuring your firewall to allow inbound and outbound cluster traffic. + +However, you might need more detailed information in some scenarios. For example, if your firewall is integrated in the cluster router, you might need to specify ports for connections that happen within one cluster but might be on different IP networks. In this scenario, you can use the {product-title-short} network policy YAML files in your {ocp} and Kubernetes clusters to determine connections and ports that you might need to configure. + +.{product-title-short} connections between components + +[cols="4",options="header"] +|=== +| Component or external entity | Connection type | Port | Additional information + +| Central and Scanner V4 Indexer +| gRPC +| 8443 +| + +| Central and Sensor on secured cluster +a| * TCP/HTTPS +* gRPC +| 443 +| Sensor and Central primarily communicate over a bidirectional gRPC stream, initiated by Sensor to Central's port 443. + +| Central and user (CLI) +a| * gRPC +* HTTPS (with `--force-http1` option) +| 443 +| For more information about the `--force-http1` option, see the `roxctl` command options. + +| Central and vulnerability feeds +| HTTPS +| 443 +| Connects to `definitions.stackrox.io` by default. + +| Collector to Sensor +| gRPC +| 443 +| This is a bidirectional gRPC connection initiated by Collector to Sensor's port 443. + +| Collector (Compliance) to Sensor +| gRPC +| 8444 +| If node scanning is enabled on {ocp} release 4, this connection is initiated by Sensor to compliance running in the Collector pod. + +| Scanner to Scanner-DB +| TCP +| 5432 +| +| Scanner V4 Indexer to Central +| HTTPS +| 443 +| + +| Scanner V4 Indexer and Matcher to Scanner V4 DB +| TCP +| 5432 +| + +| Sensor and Admission Controller +| gRPC +| 443 +| This is a bidirectional gRPC stream, initiated by Admission Controller to Sensor's port 443. This occurs in delegated scanning scenarios or in {ocp} secured clusters. + +|=== + +//old graphic version: https://docs.openshift.com/acs/3.70/architecture/acs-architecture.html#external-components_acs-architecture \ No newline at end of file diff --git a/modules/acs-architecture-differences-ocp-kube.adoc b/modules/acs-architecture-differences-ocp-kube.adoc new file mode 100644 index 000000000000..119de57b8653 --- /dev/null +++ b/modules/acs-architecture-differences-ocp-kube.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * architecture/acs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-architecture-differences-ocp-kube_{context}"] += Architectural differences between installation on {ocp} and Kubernetes + +When you install {product-title-short} on the {ocp}, there are only two architectural differences: + +. {product-title-short} installs a lightweight version of Scanner on every secured cluster when you install {product-title-short} on {ocp} by using the Operator. The lightweight Scanner enables the scanning of images in the integrated OpenShift image registry. When you install {product-title-short} by using the Helm install method with the _default_ values, the lightweight version of Scanner is not installed. To install the lightweight Scanner on the secured cluster by using Helm, you must set the `scanner.disable=false` parameter. + +. Sensor can communicate with the lightweight Scanner installed in the secured cluster. This connection allows Sensor to access registries directly from the secured cluster in scenarios where Central might be unable to access them. Scanner requests updated data from Sensor, Sensor forwards these requests to Central, and Central downloads the requested data from `definitions.stackrox.io`. diff --git a/modules/acs-architecture-external-components.adoc b/modules/acs-architecture-external-components.adoc new file mode 100644 index 000000000000..41b8ee1984a5 --- /dev/null +++ b/modules/acs-architecture-external-components.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * architecture/acs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="external-components_{context}"] += External components + +{product-title} ({product-title-short}) interacts with the following external components: + +* *Third-party systems*: You can integrate {product-title-short} with other systems such as CI/CD pipelines, event management (SIEM) systems, logging, email, and more. +* `*roxctl*`: `roxctl` is a command-line interface (CLI) for running commands on {product-title-short}. +* *Image registries*: You can integrate {product-title-short} with various image registries and use {product-title-short} to scan and view images. +{product-title-short} automatically configures registry integrations for active images by using the image pull secrets discovered in secured clusters. +However, for scanning inactive images, you must manually configure registry integrations. +* `*definitions.stackrox.io*`: {product-title-short} aggregates the data from various vulnerability feeds at the `definitions.stackrox.io` endpoint and passes this information to Central. +The feeds include general, National Vulnerability Database (NVD) data, and distribution-specific data, such as Alpine, Debian, and Ubuntu. +* `*collector-modules.stackrox.io*`: Central reaches out to `collector-modules.stackrox.io` to obtain supported kernel modules and passes on these modules to Collector. diff --git a/modules/acs-architecture-interaction-between-services.adoc b/modules/acs-architecture-interaction-between-services.adoc new file mode 100644 index 000000000000..470fb66e35b5 --- /dev/null +++ b/modules/acs-architecture-interaction-between-services.adoc @@ -0,0 +1,147 @@ +// Module included in the following assemblies: +// +// * architecture/acs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-architecture-interaction-between-services_{context}"] += Interaction between the services + +This section explains how {product-title-short} services interact with each other. + + +.{product-title-short} with Scanner V4 +[%header,cols="^.^2,^.^1,^.^2,4"] +|=== + +|Component |Direction |Component |Description + +|Central +|⮂ +|Scanner V4 Indexer +| Central requests the Indexer to download and index (analyze) given images. This process results in an index report. Scanner V4 Indexer requests mapping files from Central that assist the indexing process. + +|Central +|⮂ +|Scanner V4 Matcher +| Central requests that the Scanner V4 Matcher match given images to known vulnerabilities. This process results in the final scan result: a vulnerability report. Scanner V4 Matcher requests the latest vulnerabilities from Central. + +|Sensor +|⮂ +|Scanner V4 Indexer +| `SecuredCluster` scanning is enabled by default in {osp} environments deployed by using the Operator or when delegated scanning is used. When `SecuredCluster` scanning is enabled, Sensor requests Scanner V4 to index images. Scanner V4 Indexer requests mapping files from Sensor that assist the indexing process unless Central exists in the same namespace. In that case, Central is contacted instead. +| Scanner V4 Indexer +|→ +|Image Registries +|The Indexer pulls image metadata from registries to determine the layers of the image, and downloads each previously unindexed layer. + +|Scanner V4 Matcher +|→ +|Scanner V4 Indexer +|Scanner V4 Matcher requests the results of the image indexing, the index report, from the Indexer. It then uses the report to determine relevant vulnerabilities. This interaction occurs only when the image is indexed in the Central cluster. This interaction does not occur when Scanner V4 is matching vulnerabilities for images indexed in secured clusters. + +|Scanner V4 Indexer +|→ +|Scanner V4 DB +|The Indexer stores data related to the indexing results to ensure that image layers are only downloaded and indexed once. This prevents unnecessary network traffic and other resource utilization. + +|Scanner V4 Matcher +|→ +|Scanner V4 DB +|Scanner V4 Matcher stores all of its vulnerability data in the database and periodically updates this data. Scanner V4 indexer also queries this data as part of the vulnerability matching process. + +|Sensor +|⮂ +|Central +|There is bidirectional communication between Central and Sensor. +Sensor polls Central periodically to download updates for the sensor bundle configuration. +It also sends events for the observed activity for the secured cluster and observed policy violations. +Central communicates with Sensor to force reprocessing of all deployments against enabled policies. + +|Collector +|⮂ +|Sensor +|Collector communicates with Sensor and sends all of the events to the respective Sensor for the cluster. +On supported {ocp} clusters, Collector analyzes the software packages installed on the nodes and sends them to Sensor so that Scanner can later scan them for vulnerabilities. +Collector also requests missing drivers from Sensor. +Sensor requests compliance scan results from Collector. Additionally, Sensor receives external Classless Inter-Domain Routing information from Central and pushes it to Collector. + +|Admission controller +|⮂ +|Sensor +|Sensors send the list of security policies to enforce to Admission controller. +Admission controller sends security policy violation alerts to Sensor. +Admission controller can also request image scans from Sensor when required. + +|Admission controller +|➞ +|Central +|It is not common; however, Admission controller can communicate with Central directly if the Central endpoint is known and Sensor is unavailable. + +|=== + +.{product-title-short} with the StackRox Scanner +[%header,cols="^.^2,^.^1,^.^2,4"] +|=== + +|Component |Direction |Interacts with |Description + +|Central +|⮂ +|Scanner +|There is bidirectional communication between Central and Scanner. +Central requests image scans from Scanner, and Scanner requests updates to its CVE database from Central. + +|Central +|➞ +|`definitions.stackrox.io` +|Central connects to the `definitions.stackrox.io` endpoint to receive the aggregated vulnerability information. + +|Central +|➞ +|`collector-modules.stackrox.io` +|Central downloads supported kernel modules from `collector-modules.stackrox.io`. + +|Central +|➞ +|Image registries +|Central queries the image registries to get image metadata. +For example, to show Dockerfile instructions in the {product-title-short} portal. + +|Scanner +|➞ +|Image registries +|Scanner pulls images from the image registry to identify vulnerabilities. + +|Sensor +|⮂ +|Central +|There is bidirectional communication between Central and Sensor. +Sensor polls Central periodically for downloading updates for the sensor bundle configuration. +It also sends events for the observed activity for the secured cluster and observed policy violations. +Central communicates with Sensor to force reprocessing of all deployments against enabled policies. + +|Sensor +|⮂ +|Scanner +|Sensor can communicate with the lightweight Scanner installed in the secured cluster. This connection allows Sensor to access registries directly from the secured cluster in scenarios where Central might be unable to access them. Scanner requests updated data from Sensor, Sensor forwards these requests to Central, and Central downloads the requested data from `definitions.stackrox.io`. + +|Collector +|⮂ +|Sensor +|Collector communicates with Sensor and sends all of the events to the respective Sensor for the cluster. +On supported {ocp} clusters, Collector analyzes the software packages installed on the nodes and sends them to Sensor so that Scanner can later scan them for vulnerabilities. +Collector also requests missing drivers from Sensor. +Sensor requests compliance scan results from Collector. Additionally, Sensor receives external Classless Inter-Domain Routing information from Central and pushes it to Collector. + +|Admission controller +|⮂ +|Sensor +|Sensors send the list of security policies to enforce to Admission controller. +Admission controller sends security policy violation alerts to Sensor. +Admission controller can also request image scans from Sensor when required. + +|Admission controller +|➞ +|Central +|It is not common; however, Admission controller can communicate with Central directly if the Central endpoint is known and Sensor is unavailable. + +|=== diff --git a/modules/acs-architecture-overview.adoc b/modules/acs-architecture-overview.adoc new file mode 100644 index 000000000000..3a6442956161 --- /dev/null +++ b/modules/acs-architecture-overview.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * architecture/acs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-architecture_{context}"] += {product-title} architecture overview + +{product-title} ({product-title-short}) uses a distributed architecture that supports high-scale deployments and is optimized to minimize the impact on the underlying {ocp} or Kubernetes nodes. + +.{product-title-short} architecture + +The following graphic shows the product architecture, including the scanner components. + +image::acs-architecture-scannerv4.png[{product-title} architecture for Kubernetes] + +//Needs changes: +// Change lines around Scanner V4 parts from dotted to solid in Cluster 1 +// ^^^ Cluster N + +You install {product-title-short} as a set of containers in your {ocp} or Kubernetes cluster. {product-title-short} includes the following services: + +* Central services you install on one cluster +* Secured cluster services you install on each cluster you want to secure by {product-title-short} + +In addition to these primary services, {product-title-short} also interacts with other external components to enhance your clusters' security. + +include::snippets/scannerv4-default-secured-clusters.adoc[] \ No newline at end of file diff --git a/modules/acs-central-services-overview.adoc b/modules/acs-central-services-overview.adoc new file mode 100644 index 000000000000..aca7b7ab9305 --- /dev/null +++ b/modules/acs-central-services-overview.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * architecture/acs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-central-services_{context}"] += Central services + +//an abbreviated version of this is used in acscs-central-overview.adoc until we go back and do some restructuring to be able to single source. If updating this section, check to make sure updates aren't needed to acscs-central-overview.adoc. +You install Central services on a single cluster. +These services include the following components: + +include::snippets/central-components.adoc[] diff --git a/modules/acs-cloud-requirements.adoc b/modules/acs-cloud-requirements.adoc new file mode 100644 index 000000000000..26cbe0d85d5a --- /dev/null +++ b/modules/acs-cloud-requirements.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// * cloud_service/acscs-default-requirements.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-cloud-requirements_{context}"] += General requirements for RHACS Cloud Service + +[role="_abstract"] +Before you can install {product-title-managed}, your system must meet several requirements. + +[WARNING] +==== +You must not install {product-title-managed-short} on: + +* Amazon Elastic File System (Amazon EFS). Use the Amazon Elastic Block Store (Amazon EBS) with the default *gp2* volume type instead. +* Older CPUs that do not have the Streaming SIMD Extensions (SSE) 4.2 instruction set. +For example, Intel processors older than _Sandy Bridge_ and AMD processors older than _Bulldozer_. +These processors were released in 2011. +==== + +To install {product-title-managed-short}, you must have one of the following systems: + +* {ocp} version {ocp-supported-version} or later, and cluster nodes with a supported operating system of {op-system-first} or {op-system-base-full} +* A supported managed Kubernetes platform, and cluster nodes with a supported operating system of Amazon Linux, CentOS, Container-Optimized OS from Google, {op-system-first}, Debian, {op-system-base-full}, or Ubuntu ++ +For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. + +The following minimum requirements and suggestions apply to cluster nodes. + +Architecture:: Supported architectures are `amd64`, `ppc64le`, or `s390x`. ++ +[NOTE] +==== +Secured cluster services are supported on {ibm-power} (`ppc64le`), {ibm-z} (`s390x`), and {ibm-linuxone} (`s390x`) clusters. +==== + +Processor:: 3 CPU cores are required. + +Memory:: 6 GiB of RAM is required. ++ +[NOTE] +==== +See the default memory and CPU requirements for each component and ensure that the node size can support them. +==== + +Storage:: For {product-title-managed-short}, a persistent volume claim (PVC) is not required. However, a PVC is strongly recommended if you have secured clusters with Scanner V4 enabled. Use Solid-State Drives (SSDs) for best performance. However, you can use another storage type if you do not have SSDs available. ++ +[IMPORTANT] +==== +You must not use Ceph FS storage with {product-title-managed-short}. Red{nbsp}Hat recommends using RBD block mode PVCs for {product-title-managed-short}. +==== + +If you plan to install {product-title-managed-short} by using Helm charts, you must meet the following requirements: + +* You must have Helm command-line interface (CLI) v3.2 or newer, if you are installing or configuring {product-title-managed-short} using Helm charts. +Use the `helm version` command to verify the version of Helm you have installed. +ifdef::op[] +* You must have the required permissions to configure deployments in the Central cluster. +endif::op[] +* You must have access to the Red{nbsp}Hat Container Registry. For information about downloading images from `registry.redhat.io`, see link:https://access.redhat.com/RegistryAuthentication[Red{nbsp}Hat Container Registry Authentication]. diff --git a/modules/acs-cloud-responsibilities.adoc b/modules/acs-cloud-responsibilities.adoc new file mode 100644 index 000000000000..ec43edb6c63a --- /dev/null +++ b/modules/acs-cloud-responsibilities.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * cloud_service/acs-cloud-responsibility-matrix.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-cloud-responsibilities_{context}"] += Shared responsibilities for {product-title-managed-short} + +While Red Hat manages the {product-title-managed-short} services, also referred to as _Central services_, the customer has certain responsibilities. + +[cols="2,1,1",options="header"] +|=== + +|Resource or action +|Red Hat responsibility +|Customer responsibility + + +|Hosted components, also called Central components +a|* Platform monitoring +* Software updates +* High availability +* Backup and restore +* Security +* Infrastructure configuration +* Scaling +* Maintenance +* Vulnerability management +a| * Access and identity authorization + +|Secured clusters (on-premise or cloud) +| +a| * Software updates +* Backup and restore +* Security +* Infrastructure configuration +* Scaling +* Maintenance +* Access and identity authorization +* Vulnerability management + +|=== diff --git a/modules/acs-quick-install-secured-cluster-using-helm.adoc b/modules/acs-quick-install-secured-cluster-using-helm.adoc new file mode 100644 index 000000000000..cec0b9ee9381 --- /dev/null +++ b/modules/acs-quick-install-secured-cluster-using-helm.adoc @@ -0,0 +1,186 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-secured-cluster-ocp.adoc +// * installing/installing_other/install-secured-cluster-other.adoc +// * installing/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc +// * installing/installing_cloud_other/install-secured-cluster-cloud-other.adoc +:_mod-docs-content-type: PROCEDURE +[id="installing-secured-cluster-services-quickly_{context}"] += Installing the secured-cluster-services Helm chart without customization + +ifeval::["{context}" == "install-secured-cluster-cloud-other"] +:cloud-svc: +endif::[] + +ifeval::["{context}" == "install-secured-cluster-cloud-ocp"] +:cloud-svc: +endif::[] + +ifeval::["{context}" == "install-secured-cluster-other"] +:k8: +endif::[] + +ifeval::["{context}" == "install-secured-cluster-ocp"] +:openshift: +endif::[] + +[role="_abstract"] +Use the following instructions to install the `secured-cluster-services` Helm chart to deploy the per-cluster and per-node components (Sensor, Admission controller, Collector, and Scanner-slim). + +.Prerequisites +* You must have generated an {product-title-short} init bundle or CRS for your cluster. +* You must have access to the Red{nbsp}Hat Container Registry and a pull secret for authentication. For information about downloading images from `registry.redhat.io`, see link:https://access.redhat.com/RegistryAuthentication[Red{nbsp}Hat Container Registry Authentication]. +ifndef::cloud-svc[] +* You must have the address that you are exposing the Central service on. +endif::cloud-svc[] +ifdef::cloud-svc[] +* You must have the *Central API Endpoint* address. You can view this information by choosing *Advanced Cluster Security* -> *ACS Instances* from the Red{nbsp}Hat Hybrid Cloud Console navigation menu, then clicking the ACS instance you created. +endif::[] + +//Procedure for kubernetes - non-cloud +//do not show for openshift, cloud +ifndef::openshift,cloud-svc[] +.Procedure +* Run one of the following commands on your Kubernetes-based clusters: +** If you are using an init bundle, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + -f \// <1> + -f \// <2> + --set clusterName= \ + --set centralEndpoint= \// <3> + --set imagePullSecrets.username= \//<4> + --set imagePullSecrets.password=//<5> +---- +<1> Use the `-f` option to specify the path for the init bundle. +<2> Use the `-f` option to specify the path for the pull secret for Red{nbsp}Hat Container Registry authentication. +<3> Specify the address and port number for Central. For example, `acs.domain.com:443`. +<4> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<5> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. +** If you are using a CRS, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + --set-file crs.file= \// <1> + -f \// <2> + --set clusterName= \ + --set centralEndpoint= \// <3> + --set imagePullSecrets.username= \// <4> + --set imagePullSecrets.password=// <5> +---- +<1> Use the name of the file in which the generated CRS has been stored. +<2> Use the `-f` option to specify the path for the pull secret for Red{nbsp}Hat Container Registry authentication. +<3> Specify the address and port number for Central. For example, `acs.domain.com:443`. +<4> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<5> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. +endif::openshift,cloud-svc[] + +//Procedure for kubernetes - cloud +ifdef::cloud-svc[] +.Procedure +* Run one of the following commands on your Kubernetes-based clusters: +** If you are using an init bundle, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + -f \// <1> + -f \// <2> + --set clusterName= \ + --set centralEndpoint= \// <3> + --set imagePullSecrets.username= \//<4> + --set imagePullSecrets.password=//<5> +---- +<1> Use the `-f` option to specify the path for the init bundle. +<2> Use the `-f` option to specify the path for the pull secret for Red{nbsp}Hat Container Registry authentication. +<3> Enter the *Central API Endpoint* address. You can view this information by choosing *Advanced Cluster Security* -> *ACS Instances* from the Red{nbsp}Hat Hybrid Cloud Console navigation menu, then clicking the {product-title-short} instance you created. +<4> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<5> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. +endif::cloud-svc[] + +//Procedure for OpenShift - non-cloud +//do not show for cloud +ifndef::cloud-svc[] + +.Procedure + +* Run one of the following commands on an {ocp} cluster: +** If you are using an init bundle, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + -f \// <1> + -f \// <2> + --set clusterName= \ + --set centralEndpoint= \// <3> + --set scanner.disable=false <4> +---- +<1> Use the `-f` option to specify the path for the init bundle. +<2> Use the `-f` option to specify the path for the pull secret for Red{nbsp}Hat Container Registry authentication. +<3> Specify the address and port number for Central. For example, `acs.domain.com:443`. +<4> Set the value of the `scanner.disable` parameter to `false`, which means that Scanner-slim will be enabled during the installation. In Kubernetes, the secured cluster services now include Scanner-slim. +** If you are using a CRS, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + --set-file crs.file= \// <1> + -f \// <2> + --set clusterName= \ + --set centralEndpoint= \// <3> + --set scanner.disable=false <4> +---- +<1> Use the name of the file in which the generated CRS has been stored. +<2> Use the `-f` option to specify the path for the pull secret for Red{nbsp}Hat Container Registry authentication. +<3> Specify the address and port number for Central. For example, `acs.domain.com:443`. +<4> Set the value of the `scanner.disable` parameter to `false`, which means that Scanner-slim will be enabled during the installation. In Kubernetes, the secured cluster services now include Scanner-slim. +endif::cloud-svc[] + +//Procedure for OpenShift cloud +ifdef::cloud-svc[] + +.Procedure + +* Run one of the following commands on an {ocp} cluster: +** If you are using an init bundle, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + -f \// <1> + -f \// <2> + --set clusterName= \ + --set centralEndpoint= \// <3> + --set scanner.disable=false <4> +---- +<1> Use the `-f` option to specify the path for the init bundle. +<2> Use the `-f` option to specify the path for the pull secret for Red{nbsp}Hat Container Registry authentication. +<3> Enter the *Central API Endpoint* address. You can view this information by choosing *Advanced Cluster Security* -> *ACS Instances* from the Red{nbsp}Hat Hybrid Cloud Console navigation menu, then clicking the {product-title-short} instance you created. +<4> Set the value of the `scanner.disable` parameter to `false`, which means that Scanner-slim will be enabled during the installation. In Kubernetes, the secured cluster services now include Scanner-slim. +** If you are using a CRS, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + --set-file crs.file= \// <1> + -f \// <2> + --set clusterName= \ + --set centralEndpoint= \// <3> + --set scanner.disable=false <4> +---- +<1> Use the name of the file in which the generated CRS has been stored. +<2> Use the `-f` option to specify the path for the pull secret for Red{nbsp}Hat Container Registry authentication. +<3> Enter the *Central API Endpoint* address. You can view this information by choosing *Advanced Cluster Security* -> *ACS Instances* from the Red{nbsp}Hat Hybrid Cloud Console navigation menu, then clicking the {product-title-short} instance you created. +<4> Set the value of the `scanner.disable` parameter to `false`, which means that Scanner-slim will be enabled during the installation. In Kubernetes, the secured cluster services now include Scanner-slim. +endif::cloud-svc[] \ No newline at end of file diff --git a/modules/acs-quick-install-using-helm.adoc b/modules/acs-quick-install-using-helm.adoc new file mode 100644 index 000000000000..0121112ca9b0 --- /dev/null +++ b/modules/acs-quick-install-using-helm.adoc @@ -0,0 +1,79 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-ocp.adoc +// * installing/installing_other/install-central-other.adoc +:_mod-docs-content-type: PROCEDURE +[id="installing-quickly_{context}"] += Installing the central-services Helm chart without customizations + +Use the following instructions to install the `central-services` Helm chart to deploy the centralized components (Central and Scanner). + +.Prerequisites +* You must have access to the Red{nbsp}Hat Container Registry. For information about downloading images from `registry.redhat.io`, see link:https://access.redhat.com/RegistryAuthentication[Red{nbsp}Hat Container Registry Authentication]. + +.Procedure + +* Run the following command to install Central services and expose Central using a route: ++ +[source,terminal] +---- +$ helm install -n stackrox \ + --create-namespace stackrox-central-services rhacs/central-services \ + --set imagePullSecrets.username= \// <1> + --set imagePullSecrets.password= \// <2> + --set central.exposure.route.enabled=true +---- +<1> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<2> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. + +* Or, run the following command to install Central services and expose Central using a load balancer: ++ +[source,terminal] +---- +$ helm install -n stackrox \ + --create-namespace stackrox-central-services rhacs/central-services \ + --set imagePullSecrets.username= \// <1> + --set imagePullSecrets.password= \// <2> + --set central.exposure.loadBalancer.enabled=true +---- +<1> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<2> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. + +* Or, run the following command to install Central services and expose Central using port forward: ++ +[source,terminal] +---- +$ helm install -n stackrox \ + --create-namespace stackrox-central-services rhacs/central-services \ + --set imagePullSecrets.username= \// <1> + --set imagePullSecrets.password= <2> +---- +<1> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<2> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. + +[IMPORTANT] +==== +* If you are installing {product-title} in a cluster that requires a proxy to connect to external services, you must specify your proxy configuration by using the `proxyConfig` parameter. For example: ++ +[source,yaml] +---- +env: + proxyConfig: | + url: http://proxy.name:port + username: username + password: password + excludes: + - some.domain +---- +* If you already created one or more image pull secrets in the namespace in which you are installing, instead of using a username and password, you can use `--set imagePullSecrets.useExisting=""`. +* Do not use image pull secrets: + +** If you are pulling your images from `quay.io/stackrox-io` or a registry in a private network that does not require authentication. Use use `--set imagePullSecrets.allowNone=true` instead of specifying a username and password. +** If you already configured image pull secrets in the default service account in the namespace you are installing. Use `--set imagePullSecrets.useFromDefaultServiceAccount=true` instead of specifying a username and password. +==== + +The output of the installation command includes: + +* An automatically generated administrator password. +* Instructions on storing all the configuration values. +* Any warnings that Helm generates. diff --git a/modules/acs-requirements.adoc b/modules/acs-requirements.adoc new file mode 100644 index 000000000000..90d6bc95dfe0 --- /dev/null +++ b/modules/acs-requirements.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// * installing/acs-default-requirements.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-general-requirements_{context}"] += General RHACS requirements + +[role="_abstract"] +Before you can install {product-title-short}, your system must meet several requirements. + +[WARNING] +==== +You must not install {product-title-short} on: + +* Amazon Elastic File System (Amazon EFS). Use the Amazon Elastic Block Store (Amazon EBS) with the default *gp2* volume type instead. +* Older CPUs that do not have the Streaming SIMD Extensions (SSE) 4.2 instruction set. +For example, Intel processors older than _Sandy Bridge_ and AMD processors older than _Bulldozer_. +These processors were released in 2011. +==== + +To install {product-title-short}, you must have one of the following systems: + +* {ocp} version {ocp-supported-version} or later, and cluster nodes with a supported operating system of {op-system-first} or {op-system-base-full} +* A supported managed Kubernetes platform, and cluster nodes with a supported operating system of Amazon Linux, CentOS, Container-Optimized OS from Google, {op-system-first}, Debian, {op-system-base-full}, or Ubuntu ++ +For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. For life cycle support information for {product-title-short}, see the link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. + +The following minimum requirements and suggestions apply to cluster nodes. + +Architecture:: `amd64`, `ppc64le`, or `s390x` ++ +[NOTE] +==== +Starting with {product-title-short} 4.3, both Central and secured cluster services are supported on {ibm-power}(`ppc64le`), {ibm-z}(`s390x`), and {ibm-linuxone}(`s390x`) clusters. +==== + +Processor:: 3 CPU cores are required. + +Memory:: 6 GiB of RAM is required. ++ +[NOTE] +==== +See the default memory and CPU requirements for each component and ensure that the node size can support them. +==== + +Storage:: A persistent volume claim (PVC) is required on the cluster where Central is installed. It is strongly recommended on the secured clusters where Scanner V4 is enabled. Use Solid-State Drives (SSDs) for best performance. However, you can use another storage type if you do not have SSDs available. ++ +[IMPORTANT] +==== +You must not use Ceph FS storage with {product-title}. Red{nbsp}Hat recommends using RBD block mode PVCs for {product-title}. +==== + +If you plan to install {product-title-short} by using Helm charts, you must meet the following requirements: + +* You must have Helm command-line interface (CLI) v3.2 or newer, if you are installing or configuring {product-title-short} using Helm charts. +Use the `helm version` command to verify the version of Helm you have installed. +ifdef::op[] +* You must have the required permissions to configure deployments in the Central cluster. +endif::op[] +* You must have access to the Red{nbsp}Hat Container Registry. For information about downloading images from `registry.redhat.io`, see link:https://access.redhat.com/RegistryAuthentication[Red{nbsp}Hat Container Registry Authentication]. diff --git a/modules/acs-secured-cluster-services-overview.adoc b/modules/acs-secured-cluster-services-overview.adoc new file mode 100644 index 000000000000..e0a1ee1d840d --- /dev/null +++ b/modules/acs-secured-cluster-services-overview.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * architecture/acs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acs-secured-cluster-services_{context}"] += Secured cluster services + +:title: Red Hat Advanced Cluster Security +:short-title: RHACS + +ifeval::["{context}" == "acscs-architecture"] +:title: Red Hat Advanced Cluster Security Cloud Service +:short-title: RHACS Cloud Service +endif::[] + + +You install the secured cluster services on each cluster that you want to secure by using the {title}. +Secured cluster services include the following components: + +* *Sensor*: Sensor is the service responsible for analyzing and monitoring the cluster. +Sensor listens to the {ocp} or Kubernetes API and Collector events to report the current state of the cluster. +Sensor also triggers deploy-time and runtime violations based on {short-title} policies. +In addition, Sensor is responsible for all cluster interactions, such as applying network policies, initiating reprocessing of {short-title} policies, and interacting with the Admission controller. +* *Admission controller*: The Admission controller prevents users from creating workloads that violate security policies in {short-title}. +* *Collector*: Collector analyzes and monitors container activity on cluster nodes. +It collects container runtime and network activity information and sends the collected data to Sensor. +* *Scanner V4*: Scanner V4 retrieves and scans images and indexes them. It is the default scanner for {product-title-short} and contains the following components: +** *Scanner V4 Indexer*: The Scanner V4 Indexer performs image indexing, previously known as image analysis. Given an image and registry credentials, the Indexer pulls the image from the registry. The Indexer finds the base operating system, if one exists, and looks for packages. It stores and outputs an index report, which contains the findings for the given image. +** *Scanner V4 DB*: This database stores information for Scanner V4, including index reports. For best performance, configure a persistent volume claim (PVC) for Scanner V4 DB. +* *StackRox Scanner*: In Kubernetes, the secured cluster services include Scanner-slim as an optional component. However, on {ocp}, {short-title} installs a Scanner-slim version on each secured cluster to scan images in the {ocp} integrated registry and optionally other registries. +* *Scanner-DB*: This database contains data for the StackRox Scanner. ++ +[NOTE] +==== +When secured cluster services are installed on the same cluster as Central services and installed in the same namespace, secured cluster services do not deploy Scanner V4 components. Instead, it is assumed that Central services already include a deployment of Scanner V4. +==== + +:!title: +:!short-title: \ No newline at end of file diff --git a/modules/acscs-architecture-overview.adoc b/modules/acscs-architecture-overview.adoc new file mode 100644 index 000000000000..31c864c957eb --- /dev/null +++ b/modules/acscs-architecture-overview.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * cloud_service/acscs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acscs-architecture-overview_{context}"] += {product-title-managed} architecture overview + +{rh-rhacscs-first} is a Red{nbsp}Hat managed Software-as-a-Service (SaaS) platform that lets you protect your Kubernetes and {ocp} clusters and applications throughout the build, deploy, and runtime lifecycles. + +{product-title-managed-short} includes many built-in DevOps enforcement controls and security-focused best practices based on industry standards such as the Center for Internet Security (CIS) benchmarks and the National Institute of Standards Technology (NIST) guidelines. +You can also integrate it with your existing DevOps tools and workflows to improve security and compliance. + + +.{product-title-managed-short} architecture + +The following graphic shows the architecture with the StackRox Scanner and Scanner V4. +//Does this graphic need updates to change Scanner V4 components to non-dotted lines since they are now not optional? + +image::acscs-architecture-scannerv4.png[{product-title-managed-short}] + +Central services include the user interface (UI), data storage, {product-title-short} application programming interface (API), and image scanning capabilities. +You deploy your Central service through the link:https://console.redhat.com/[Red{nbsp}Hat Hybrid Cloud Console.] When you create a new ACS instance, Red{nbsp}Hat creates your individual control plane for {product-title-short}. + +{product-title-managed-short} allows you to secure self-managed clusters that communicate with a Central instance. +The clusters you secure, called Secured Clusters, are managed by you, and not by Red{nbsp}Hat. +Secured Cluster services include optional vulnerability scanning services, admission control services, and data collection services used for runtime monitoring and compliance. +You install Secured Cluster services on any OpenShift or Kubernetes cluster you want to secure. + +include::snippets/scannerv4-default-secured-clusters.adoc[] \ No newline at end of file diff --git a/modules/acscs-central-overview.adoc b/modules/acscs-central-overview.adoc new file mode 100644 index 000000000000..1e0b159cea91 --- /dev/null +++ b/modules/acscs-central-overview.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * cloud_service/acscs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acscs-central_{context}"] += Central + +Red{nbsp}Hat manages Central, the control plane for {product-title-managed-short}. +These services include the following components: + +include::snippets/central-components.adoc[] diff --git a/modules/acscs-data-access-permissions.adoc b/modules/acscs-data-access-permissions.adoc new file mode 100644 index 000000000000..6daa4822b566 --- /dev/null +++ b/modules/acscs-data-access-permissions.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * cloud_service/acscs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="acscs-data-access-permissions_{context}"] += Data access and permissions + + +[role="_abstract"] +Red{nbsp}Hat does not have access to the clusters on which you install the secured cluster services. +Also, {product-title-managed-short} does not need permission to access the secured clusters. +For example, you do not need to create new IAM policies, access roles, or API tokens. + +However, {product-title-managed-short} stores the data that secured cluster services send. +All data is encrypted within {product-title-managed-short}. +Encrypting the data within the {product-title-managed-short} platform helps to ensure the confidentiality and integrity of the data. + +When you install secured cluster services on a cluster, it generates data and transmits it to the {product-title-managed-short}. +This data is kept secure within the {product-title-managed-short} platform, and only authorized SRE team members and systems can access this data. +{product-title-managed-short} uses this data to monitor the security and compliance of your cluster and applications, and to provide valuable insights and analytics that can help you optimize your deployments. diff --git a/modules/add-a-custom-header-and-footer.adoc b/modules/add-a-custom-header-and-footer.adoc new file mode 100644 index 000000000000..4dca30606719 --- /dev/null +++ b/modules/add-a-custom-header-and-footer.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * configuration/add-security-notices.adoc +:_mod-docs-content-type: PROCEDURE +[id="add-a-custom-header-and-footer_{context}"] += Adding a custom header and footer + +You can place custom text in a header and footer and configure the text and its background color. + +.Prerequisites + +* You must have the `Administration` role with `read` permission to view the custom header and footer configuration options. +* You must have the `Administration` role with `write` permission to modify, enable or disable the custom header and footer. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *System Configuration*. +. On the *System Configuration* view header, click *Edit*. +. Under the *Header Configuration* and *Footer Configuration* sections, enter the header and footer text. +. Customize the header and footer *Text Color*, *Size*, and *Background Color*. +. To enable the header, turn on the toggle in the *Header Configuration* section. +. To enable the footer, turn on the toggle in the *Footer Configuration* section. +. Click *Save*. diff --git a/modules/add-a-custom-login-message.adoc b/modules/add-a-custom-login-message.adoc new file mode 100644 index 000000000000..3534bbe2e726 --- /dev/null +++ b/modules/add-a-custom-login-message.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * configuration/add-security-notices.adoc +:_mod-docs-content-type: PROCEDURE +[id="add-a-custom-login-message_{context}"] += Adding a custom login message + +The display of a warning message before login warns malicious or uninformed users about the consequences of their actions. + +.Prerequisites + +* You must have the `Administration` role with `read` permission to view the login message configuration options. +* You must have the `Administration` role with `write` permission to modify, enable or disable the login message. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *System Configuration*. +. On the *System Configuration* view header, click *Edit*. +. Enter your login message in the *Login Configuration* section. +. To enable the login message, turn on the toggle in the *Login Configuration* section. +. Click *Save*. diff --git a/modules/add-http-event-collector-splunk.adoc b/modules/add-http-event-collector-splunk.adoc new file mode 100644 index 000000000000..845b4c0c5e6d --- /dev/null +++ b/modules/add-http-event-collector-splunk.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-splunk.adoc +:_mod-docs-content-type: PROCEDURE +[id="add-http-event-collector-splunk_{context}"] += Adding an HTTP event collector in Splunk + +Add a new HTTP event collector for your Splunk instance, and get the token. + +.Procedure +. In your Splunk dashboard, go to *Settings* -> *Add Data*. +. Click *Monitor*. +. On the *Add Data* page, click *HTTP Event Collector*. +. Enter a *Name* for the event collector and then click *Next >*. +. Accept the default *Input Settings* and click *Review >*. +. Review the event collector properties and click *Submit >*. +. Copy the *Token Value* for the event collector. You need this token value to configure integration with Splunk in {product-title}. diff --git a/modules/add-logical-conditions-policy-criteria.adoc b/modules/add-logical-conditions-policy-criteria.adoc new file mode 100644 index 000000000000..07aaf9790380 --- /dev/null +++ b/modules/add-logical-conditions-policy-criteria.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="add-logical-conditions-policy-criteria_{context}"] += Adding logical conditions for the policy criteria + +[role="_abstract"] +You can use the drag-and-drop policy fields panel to specify logical conditions for the policy criteria. + +.Procedure +. In the *Policy Criteria* section, select *Add a new condition* to add a new policy section. +** You can click on the *Edit* icon to rename the policy section. +** The *Drag out a policy field* section lists available policy criteria in multiple categories. +You can expand and collapse these categories to view the policy criteria attributes. +. Drag an attribute to the *Drop a policy field inside* area of the policy section. +. Depending on the type of the attribute you select, you get different options to configure the conditions for the selected attribute. +For example: +** If you select an attribute with Boolean values `Read-Only Root Filesystem`, you will see `READ-ONLY` and `WRITABLE` options. +** If you select an attribute with compound values `Environment variable`, you will see options to enter values for `Key`, `Value`, and `Value From` fields, and an icon to add more values for the available options. +.. To combine multiple values for an attribute, click the *Add* icon. +.. You can also click on the logical operator `AND` or `OR` listed in a policy section, to toggle between `AND` and `OR` operators. +Toggling between operators only works inside a policy section and not between two different policy sections. +. You can specify more than one `AND` and `OR` condition by repeating these steps. +After you configure the conditions for the added attributes, click *Next* to continue with the policy creation. diff --git a/modules/add-pod-namespace-to-sensor-and-admission-control.adoc b/modules/add-pod-namespace-to-sensor-and-admission-control.adoc new file mode 100644 index 000000000000..1c069568cccf --- /dev/null +++ b/modules/add-pod-namespace-to-sensor-and-admission-control.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-45.adoc +:_mod-docs-content-type: PROCEDURE +[id="add-pod-namespace-to-sensor-and-admission-control_{context}"] += Adding POD_NAMESPACE to sensor and admission-control deployments + +[role="_abstract"] +When upgrading to version 4.6 or later from a version earlier than 4.6, you must patch the sensor and admission-control deployments to set the `POD_NAMESPACE` environment variable. + +[NOTE] +==== +If you are using Kubernetes, use `kubectl` instead of `oc` for the commands listed in this procedure. +==== + +.Procedure + +. Patch sensor to ensure `POD_NAMESPACE` is set by running the following command: ++ +[source,terminal,subs=attributes+] +---- +$ [[ -z "$(oc -n stackrox get deployment sensor -o yaml | grep POD_NAMESPACE)" ]] && oc -n stackrox patch deployment sensor --type=json -p '[{"op":"add","path":"/spec/template/spec/containers/0/env/-","value":{"name":"POD_NAMESPACE","valueFrom":{"fieldRef":{"fieldPath":"metadata.namespace"}}}}]' +---- +. Patch admission-control to ensure `POD_NAMESPACE` is set by running the following command: ++ +[source,terminal,subs=attributes+] +---- +$ [[ -z "$(oc -n stackrox get deployment admission-control -o yaml | grep POD_NAMESPACE)" ]] && oc -n stackrox patch deployment admission-control --type=json -p '[{"op":"add","path":"/spec/template/spec/containers/0/env/-","value":{"name":"POD_NAMESPACE","valueFrom":{"fieldRef":{"fieldPath":"metadata.namespace"}}}}]' +---- \ No newline at end of file diff --git a/modules/add-process-to-baseline.adoc b/modules/add-process-to-baseline.adoc new file mode 100644 index 000000000000..422ddf6cc181 --- /dev/null +++ b/modules/add-process-to-baseline.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: PROCEDURE +[id="add-process-to-baseline_{context}"] += Adding a process to the baseline + +You can add a process to the baseline. + +.Procedure +. In the {product-title-short} portal, select *Risk* from the navigation menu. +. Select a deployment from the list of deployments in the default *Risk* view. +Deployment details open in a panel on the right. +. In the *Deployment* details panel, select the *Process Discovery* tab. +. Under the *Running Processes* section, click the *Add* icon for the process you want to add to the process baseline. + +[NOTE] +==== +The *Add* icon is available only for the processes that are not in the process baseline. +==== diff --git a/modules/adding-a-custom-logo.adoc b/modules/adding-a-custom-logo.adoc deleted file mode 100644 index d9a9561b8aee..000000000000 --- a/modules/adding-a-custom-logo.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/customizing-the-web-console.adoc - -[id="adding-a-custom-logo_{context}"] -= Adding a custom logo and product name - -You can create custom branding by adding a custom logo or custom product name. You can set both or one without the other, as these settings are independent of each other. - -.Prerequisites - -* You must have administrator privileges. -* Create a file of the logo that you want to use. The logo can be a file in any common image format, including GIF, JPG, PNG, or SVG, and is constrained to a `max-height` of `60px`. - -.Procedure - -. Import your logo file into a config map in the `openshift-config` namespace: -+ -[source,terminal] ----- -$ oc create configmap console-custom-logo --from-file /path/to/console-custom-logo.png -n openshift-config ----- - -. Edit the web console's Operator configuration to include `customLogoFile` and `customProductName`: -+ -[source,terminal] ----- -$ oc edit consoles.operator.openshift.io cluster ----- -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Console -metadata: - name: cluster -spec: - customization: - customLogoFile: - key: console-custom-logo.png - name: console-custom-logo - customProductName: My Console ----- -+ -Once the Operator configuration is updated, it will sync the custom logo config map into the console namespace, mount it to the console pod, and redeploy. - -. Check for success. If there are any issues, the console cluster Operator will report a `Degraded` status, and the console Operator configuration will also report a `CustomLogoDegraded` status, but with reasons like `KeyOrFilenameInvalid` or `NoImageProvided`. -+ -To check the `clusteroperator`, run: -+ -[source,terminal] ----- -$ oc get clusteroperator console -o yaml ----- -+ -To check the console Operator configuration, run: -+ -[source,terminal] ----- -$ oc get consoles.operator.openshift.io -o yaml ----- diff --git a/modules/adding-attached-collections.adoc b/modules/adding-attached-collections.adoc new file mode 100644 index 000000000000..4673549f5b6f --- /dev/null +++ b/modules/adding-attached-collections.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/create-use-collections.adoc +:_mod-docs-content-type: PROCEDURE +[id="adding-attached-collections_{context}"] += Adding attached collections + +Grouping collections and adding them to other collections can be useful if you want to create small collections based on deployments. You can reuse and combine those smaller collections into larger, hierarchical collections. To add additional collections to a collection that you are creating: + +. Perform one of the following actions: +* Enter text in the *Filter by name* field and press *->* to view matching results. +* Click the name of a collection from the *Available collections* list to view information about the collection, such as the name and rules for the collection and the deployments that match that collection. +. After viewing collection information, close the window to return to the *Attached collections* page. +. Click *+Attach*. The *Attached collections* section lists the collections that you attached. ++ +[NOTE] +==== +When you add an attached collection, the attached collection contains results based on the configured selection rules. For example, if an attached collection includes resources that would be filtered out by the rules used in the parent collection, then those items are still added to the parent collection because of the rules in the attached collection. Attached collections extend the original collection using an `OR` operator. +==== +. Click *Save*. \ No newline at end of file diff --git a/modules/adding-custom-notification-banners.adoc b/modules/adding-custom-notification-banners.adoc deleted file mode 100644 index bd2fa8bed598..000000000000 --- a/modules/adding-custom-notification-banners.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/customizing-the-web-console.adoc - -[id="creating-custom-notification-banners_{context}"] -= Creating custom notification banners - -.Prerequisites - -* You must have administrator privileges. - -.Procedure - -. From *Administration* -> *Custom Resource Definitions*, click on -*ConsoleNotification*. -. Select *Instances* tab -. Click *Create Console Notification* and edit the file: -+ -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleNotification -metadata: - name: example -spec: - text: This is an example notification message with an optional link. - location: BannerTop <1> - link: - href: 'https://www.example.com/' - text: Optional link text - color: '#fff' - backgroundColor: '#0088ce' - ----- -<1> Valid location settings are `BannerTop`, `BannerBottom`, and `BannerTopBottom`. - -. Click the *Create* button to apply your changes. diff --git a/modules/adding-helm-repository.adoc b/modules/adding-helm-repository.adoc new file mode 100644 index 000000000000..0d4b283271f6 --- /dev/null +++ b/modules/adding-helm-repository.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-ocp.adoc +// * installing/installing_other/install-central-other.adoc +:_mod-docs-content-type: PROCEDURE +[id="adding-helm-repository_{context}"] += Adding the Helm chart repository + +ifeval::["{context}" == "install-secured-cluster-cloud-other"] +:cloud-svc: +endif::[] + + +.Procedure + +* Add the {product-title-short} charts repository. ++ +[source,terminal] +---- +$ helm repo add rhacs https://mirror.openshift.com/pub/rhacs/charts/ +---- + +The Helm repository for {product-title} includes Helm charts for installing different components, including: + +ifndef::cloud-svc[] +* Central services Helm chart (`central-services`) for installing the centralized components (Central and Scanner). ++ +[NOTE] +==== +You deploy centralized components only once and you can monitor multiple separate clusters by using the same installation. +==== +endif::[] +* Secured Cluster Services Helm chart (`secured-cluster-services`) for installing the per-cluster and per-node components (Sensor, Admission Controller, Collector, and Scanner-slim). ++ +[NOTE] +==== +Deploy the per-cluster components into each cluster that you want to monitor and deploy the per-node components in all nodes that you want to monitor. +==== + +.Verification + +* Run the following command to verify the added chart repository: ++ +[source,terminal] +---- +$ helm search repo -l rhacs/ +---- diff --git a/modules/adding-to-a-project.adoc b/modules/adding-to-a-project.adoc deleted file mode 100644 index c36de07126c2..000000000000 --- a/modules/adding-to-a-project.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="adding-to-a-project_{context}"] -= Adding to a project - -.Procedure - -. Select *Developer* from the context selector at the top of the web console -navigation menu. - -. Click *+Add* - -. At the top of the page, select the name of the project that you want to add to. - -. Click on a method for adding to your project, and then follow the workflow. diff --git a/modules/adding-yaml-examples-to-kube-resources.adoc b/modules/adding-yaml-examples-to-kube-resources.adoc deleted file mode 100644 index 313d97302c8f..000000000000 --- a/modules/adding-yaml-examples-to-kube-resources.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/customizing-the-web-console.adoc - -[id="adding-yaml-examples-to-kube-resources_{context}"] -= Adding YAML examples to Kubernetes resources - -You can dynamically add YAML examples to any Kubernetes resources at any time. - -.Prerequisites - -* You must have cluster administrator privileges. - -.Procedure - -. From *Administration* -> *Custom Resource Definitions*, click on *ConsoleYAMLSample*. - -. Click *YAML* and edit the file: -+ -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleYAMLSample -metadata: - name: example -spec: - targetResource: - apiVersion: batch/v1 - kind: Job - title: Example Job - description: An example Job YAML sample - yaml: | - apiVersion: batch/v1 - kind: Job - metadata: - name: countdown - spec: - template: - metadata: - name: countdown - spec: - containers: - - name: counter - image: centos:7 - command: - - "bin/bash" - - "-c" - - "for i in 9 8 7 6 5 4 3 2 1 ; do echo $i ; done" - restartPolicy: Never ----- -Use `spec.snippet` to indicate that the YAML sample is not the full YAML resource -definition, but a fragment that can be inserted into the existing YAML document -at the user's cursor. - -. Click *Save*. diff --git a/modules/admin-credentials-root-secret-formats.adoc b/modules/admin-credentials-root-secret-formats.adoc deleted file mode 100644 index e8196e35b3b7..000000000000 --- a/modules/admin-credentials-root-secret-formats.adoc +++ /dev/null @@ -1,104 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/manually-creating-iam.adoc - -ifeval::["{context}" == "manually-creating-iam-aws"] -:aws: -endif::[] -ifeval::["{context}" == "manually-creating-iam-azure"] -:azure: -endif::[] -ifeval::["{context}" == "manually-creating-iam-gcp"] -:google-cloud-platform: -endif::[] - -[id="admin-credentials-root-secret-formats_{context}"] -= Admin credentials root secret format - -Each cloud provider uses a credentials root secret in the `kube-system` -namespace by convention, which is then used to satisfy all credentials requests -and create their respective secrets. This is done either by minting new -credentials, with _mint mode_, or by copying the credentials root secret, with -_passthrough mode_. - -The format for the secret varies by cloud, and is also used for each -`CredentialsRequest` secret. - -ifdef::aws[] - -.Amazon Web Services (AWS) secret format - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - namespace: kube-system - name: aws-creds -stringData: - aws_access_key_id: - aws_secret_access_key: ----- - -endif::aws[] - -ifdef::azure[] - -.Microsoft Azure secret format - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - namespace: kube-system - name: azure-credentials -stringData: - azure_subscription_id: - azure_client_id: - azure_client_secret: - azure_tenant_id: - azure_resource_prefix: - azure_resourcegroup: - azure_region: ----- - -On Microsoft Azure, the credentials secret format includes two properties that must -contain the cluster's infrastructure ID, generated randomly for each cluster -installation. This value can be found after running create manifests: - -[source,terminal] ----- -$ cat .openshift_install_state.json | jq '."*installconfig.ClusterID".InfraID' -r ----- - -.Example output -[source,terminal] ----- -mycluster-2mpcn ----- - -This value would be used in the secret data as follows: - -[source,yaml] ----- -azure_resource_prefix: mycluster-2mpcn -azure_resourcegroup: mycluster-2mpcn-rg ----- -endif::azure[] - -ifdef::google-cloud-platform[] - -.Google Cloud Platform (GCP) secret format - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - namespace: kube-system - name: gcp-credentials -stringData: - service_account.json: ----- -endif::google-cloud-platform[] diff --git a/modules/administration-event-details-overview.adoc b/modules/administration-event-details-overview.adoc new file mode 100644 index 000000000000..eb6c8af7cce1 --- /dev/null +++ b/modules/administration-event-details-overview.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// *operating/using-the-administration-events-page.adoc + +:_mod-docs-content-type: CONCEPT +[id="administration-event-details-overview_{context}"] += Administration event details overview + +The administration event provides log information that describes the error or event. + +The logs provide the following information: + +* Context of the event +* Steps to take to fix the error + +The administration event page organizes information in the following groups: + +* *Resource type*: Classifies events based on the resource or component type involved. ++ +The following resource types are included: + +** `API Token` +** `Cluster` +** `Image` +** `Node` +** `Notifier` + +* *Resource name*: Specifies the name of the resource or component to which the event refers. It identifies the specific instance within the domain where the event occurred. + +* *Event type*: Specifies the source of the event. Central generates log events that correspond to administration events created from log statements. + +* *Event ID*: A unique identifier composed of alphanumeric characters that is assigned to each event. Event IDs can be useful in identifying, tracking, and managing events over time. + +* *Created at*: Indicates the timestamp and date when the event was originally created or recorded. + +* *Last occurred at*: Specifies the timestamp and date when the event last occurred. This tracks the timing of the event, which can be critical for diagnosing and fixing recurring issues. + +* *Count*: Indicates the number of times a particular event occurred. This number is useful in assessing the frequency of an issue. An event that has occurred multiple times indicates a persistent issue that you need to fix. \ No newline at end of file diff --git a/modules/administration-events-page-overview.adoc b/modules/administration-events-page-overview.adoc new file mode 100644 index 000000000000..36a6c9045747 --- /dev/null +++ b/modules/administration-events-page-overview.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// *operating/using-the-administration-events-page.adoc + +:_mod-docs-content-type: CONCEPT +[id="administration-events-page-overview_{context}"] += Administration events page overview + +The administration events page organizes information in the following groups: + +* *Domain*: Categorizes events by the specific area or domain within {product-title-short} in which the event occurred. This classification helps organize and understand the context of events. ++ +The following domains are included: + +** `Authentication` +** `General` +** `Image Scanning` +** `Integrations` + +* *Resource type*: Classifies events based on the resource or component type involved. ++ +The following resource types are included: + +** `API Token` +** `Cluster` +** `Image` +** `Node` +** `Notifier` + +* *Level*: Indicates the severity or importance of an event. ++ +The following levels are included: + +** `Error` +** `Warning` +** `Success` +** `Info` +** `Unknown` + +* *Event last occurred at*: Provides information about the timestamp and date when an event occurred. It helps track the timing of events, which is essential for diagnosing issues and understanding the sequence of actions or incidents. + +* *Count*: Indicates the number of times a particular event occurred. This number is useful in assessing the frequency of an issue. An event that has occurred multiple times indicates a persistent issue that you need to fix. + +Each event also gives you an indication of what you need to do to fix the error. \ No newline at end of file diff --git a/modules/administration-usage-page-overview.adoc b/modules/administration-usage-page-overview.adoc new file mode 100644 index 000000000000..478750a5871c --- /dev/null +++ b/modules/administration-usage-page-overview.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/use-system-health-dashboard.adoc + +:_mod-docs-content-type: REFERENCE +[id="administration-usage-page-overview_{context}"] += Administration usage page overview + +When you click *Show administration usage* in the *System Health* page, you can view the product usage data for the number of secured Kubernetes nodes and CPU units for secured clusters based on metrics collected from Sensors. You can use this information to estimate {rh-rhacs-first} consumption data for reporting. + +For more information on how CPU units are defined in Kubernetes, see link:https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu[CPU resource units] (Kubernetes documentation). + +[NOTE] +==== +{ocp} provides its own usage reports. You can use this information with self-managed Kubernetes systems. +==== + +{product-title-short} provides the following usage data in the web portal and API: + +Currently secured:: +CPU units::: Indicates the number of Kubernetes CPU units that your {product-title-short} secured clusters uses, as of the latest metrics collection. +Node count::: Indicates the number of Kubernetes nodes that {product-title-short} secures, as of the latest metrics collection. +Maximum secured:: +CPU units::: Indicates the maximum number of CPU units that your {product-title-short} secured clusters use, measured hourly and aggregated for the time period that you specified. +Node count::: Indicates the maximum number of Kubernetes nodes that {product-title-short} secures, measured hourly and aggregated for the time period that you specified. +CPU units observation date::: Indicates the date on which the maximum secured CPU units data was collected. +Node count observation date::: Indicates the date on which the maximum secured node count data was collected. \ No newline at end of file diff --git a/modules/admission-plug-ins-about.adoc b/modules/admission-plug-ins-about.adoc deleted file mode 100644 index b16463756141..000000000000 --- a/modules/admission-plug-ins-about.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/admission-plug-ins.adoc - -[id="admission-plug-ins-about_{context}"] -= About admission plug-ins - -Admission plug-ins are used to help regulate how {product-title} {product-version} functions. Admission plug-ins intercept requests to the master API to validate resource requests and ensure policies are adhered to, after the request is authenticated and authorized. For example, they are commonly used to enforce security policy, resource limitations or configuration requirements. - -Admission plug-ins run in sequence as an admission chain. If any admission plug-in in the sequence rejects a request, the whole chain is aborted and an error is returned. - -{product-title} has a default set of admission plug-ins enabled for each resource type. These are required for proper functioning of the cluster. Admission plug-ins ignore resources that they are not responsible for. - -In addition to the defaults, the admission chain can be extended dynamically through webhook admission plug-ins that call out to custom webhook servers. There are two types of webhook admission plug-ins: a mutating admission plug-in and a validating admission plug-in. The mutating admission plug-in runs first and can both modify resources and validate requests. The validating admission plug-in validates requests and runs after the mutating admission plug-in so that modifications triggered by the mutating admission plug-in can also be validated. - -Calling webhook servers through a mutating admission plug-in can produce side effects on resources related to the target object. In such situations, you must take steps to validate that the end result is as expected. - -[WARNING] -==== -Dynamic admission should be used cautiously because it impacts cluster control plane operations. When calling webhook servers through webhook admission plug-ins in {product-title} {product-version}, ensure that you have read the documentation fully and tested for side effects of mutations. Include steps to restore resources back to their original state prior to mutation, in the event that a request does not pass through the entire admission chain. -==== diff --git a/modules/admission-plug-ins-default.adoc b/modules/admission-plug-ins-default.adoc deleted file mode 100644 index 3f7f8368060e..000000000000 --- a/modules/admission-plug-ins-default.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/admission-plug-ins.adoc - -[id="admission-plug-ins-default_{context}"] -= Default admission plug-ins - -//Future xref - A set of default admission plug-ins is enabled in {product-title} {product-version}. These default plug-ins contribute to fundamental control plane functionality, such as ingress policy, xref:../nodes/clusters/nodes-cluster-overcommit.adoc#nodes-cluster-resource-override_nodes-cluster-overcommit[cluster resource limit override] and quota policy. -A set of default admission plug-ins is enabled in {product-title} {product-version}. These default plug-ins contribute to fundamental control plane functionality, such as ingress policy, cluster resource limit override and quota policy. diff --git a/modules/admission-webhook-types.adoc b/modules/admission-webhook-types.adoc deleted file mode 100644 index 3d73e4c64120..000000000000 --- a/modules/admission-webhook-types.adoc +++ /dev/null @@ -1,110 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/admission-plug-ins.adoc - -[id="admission-webhook-types_{context}"] -= Types of webhook admission plug-ins - -Cluster administrators can call out to webhook servers through the mutating admission plug-in or the validating admission plug-in in the API server admission chain. - -[id="mutating-admission-plug-in_{context}"] -== Mutating admission plug-in - -The mutating admission plug-in is invoked during the mutation phase of the admission process, which allows modification of resource content before it is persisted. One example webhook that can be called through the mutating admission plug-in is the Pod Node Selector feature, which uses an annotation on a namespace to find a label selector and add it to the pod specification. - -[id="mutating-admission-plug-in-config_{context}"] -.Sample mutating admission plug-in configuration - -[source,yaml] ----- -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: MutatingWebhookConfiguration <1> -metadata: - name: <2> -webhooks: -- name: <3> - clientConfig: <4> - service: - namespace: default <5> - name: kubernetes <6> - path: <7> - caBundle: <8> - rules: <9> - - operations: <10> - - - apiGroups: - - "" - apiVersions: - - "*" - resources: - - - failurePolicy: <11> - sideEffects: None ----- - -<1> Specifies a mutating admission plug-in configuration. -<2> The name for the `MutatingWebhookConfiguration` object. Replace `` with the appropriate value. -<3> The name of the webhook to call. Replace `` with the appropriate value. -<4> Information about how to connect to, trust, and send data to the webhook server. -<5> The namespace where the front-end service is created. -<6> The name of the front-end service. -<7> The webhook URL used for admission requests. Replace `` with the appropriate value. -<8> A PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace `` with the appropriate certificate in base64 format. -<9> Rules that define when the API server should use this webhook admission plug-in. -<10> One or more operations that trigger the API server to call this webhook admission plug-in. Possible values are `create`, `update`, `delete` or `connect`. Replace `` and `` with the appropriate values. -<11> Specifies how the policy should proceed if the webhook server is unavailable. -Replace `` with either `Ignore` (to unconditionally accept the request in the event of a failure) or `Fail` (to deny the failed request). Using `Ignore` can result in unpredictable behavior for all clients. - -[IMPORTANT] -==== -In {product-title} {product-version}, objects created by users or control loops through a mutating admission plug-in might return unexpected results, especially if values set in an initial request are overwritten, which is not recommended. -==== - -[id="validating-admission-plug-in_{context}"] -== Validating admission plug-in - -A validating admission plug-in is invoked during the validation phase of the admission process. This phase allows the enforcement of invariants on particular API resources to ensure that the resource does not change again. The Pod Node Selector is also an example of a webhook which is called by the validating admission plug-in, to ensure that all `nodeSelector` fields are constrained by the node selector restrictions on the namespace. - -[id="validating-admission-plug-in-config_{context}"] -//http://blog.kubernetes.io/2018/01/extensible-admission-is-beta.html -.Sample validating admission plug-in configuration - -[source,yaml] ----- -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration <1> -metadata: - name: <2> -webhooks: -- name: <3> - clientConfig: <4> - service: - namespace: default <5> - name: kubernetes <6> - path: <7> - caBundle: <8> - rules: <9> - - operations: <10> - - - apiGroups: - - "" - apiVersions: - - "*" - resources: - - - failurePolicy: <11> - sideEffects: Unknown ----- - -<1> Specifies a validating admission plug-in configuration. -<2> The name for the `ValidatingWebhookConfiguration` object. Replace `` with the appropriate value. -<3> The name of the webhook to call. Replace `` with the appropriate value. -<4> Information about how to connect to, trust, and send data to the webhook server. -<5> The namespace where the front-end service is created. -<6> The name of the front-end service. -<7> The webhook URL used for admission requests. Replace `` with the appropriate value. -<8> A PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace `` with the appropriate certificate in base64 format. -<9> Rules that define when the API server should use this webhook admission plug-in. -<10> One or more operations that trigger the API server to call this webhook admission plug-in. Possible values are `create`, `update`, `delete` or `connect`. Replace `` and `` with the appropriate values. -<11> Specifies how the policy should proceed if the webhook server is unavailable. -Replace `` with either `Ignore` (to unconditionally accept the request in the event of a failure) or `Fail` (to deny the failed request). Using `Ignore` can result in unpredictable behavior for all clients. diff --git a/modules/admission-webhooks-about.adoc b/modules/admission-webhooks-about.adoc deleted file mode 100644 index 24ad3650bbd8..000000000000 --- a/modules/admission-webhooks-about.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/admission-plug-ins.adoc - -[id="admission-webhooks-about_{context}"] -= Webhook admission plug-ins - -In addition to {product-title} default admission plug-ins, dynamic admission can be implemented through webhook admission plug-ins that call webhook servers, to extend the functionality of the admission chain. Webhook servers are called over HTTP at defined endpoints. - -There are two types of webhook admission plug-ins in {product-title}: - -//Future xref - * During the admission process, xref:../architecture/admission-plug-ins.adoc#mutating-admission-plug-in[the mutating admission plug-in] can perform tasks, such as injecting affinity labels. -* During the admission process, the _mutating admission plug-in_ can perform tasks, such as injecting affinity labels. - -//Future xref - * At the end of the admission process, xref:../architecture/admission-plug-ins.adoc#validating-admission-plug-in[the validating admission plug-in] makes sure an object is configured properly, for example ensuring affinity labels are as expected. If the validation passes, {product-title} schedules the object as configured. -* At the end of the admission process, the _validating admission plug-in_ can be used to make sure an object is configured properly, for example ensuring affinity labels are as expected. If the validation passes, {product-title} schedules the object as configured. - -When an API request comes in, mutating or validating admission plug-ins use the list of external webhooks in the configuration and call them in parallel: - -* If all of the webhooks approve the request, the admission chain continues. - -* If any of the webhooks deny the request, the admission request is denied and the reason for doing so is based on the first denial. - -* If more than one webhook denies the admission request, only the first denial reason is returned to the user. - -* If an error is encountered when calling a webhook, the request is either denied or the webhook is ignored depending on the error policy set. If the error policy is set to `Ignore`, the request is unconditionally accepted in the event of a failure. If the policy is set to `Fail`, failed requests are denied. Using `Ignore` can result in unpredictable behavior for all clients. - -//Future xrefs - Communication between the webhook admission plug-in and the webhook server must use TLS. Generate a certificate authority (CA) certificate and use the certificate to sign the server certificate that is used by your webhook server. The PEM-encoded CA certificate is supplied to the webhook admission plug-in using a mechanism, such as xref:../security/certificates/service-serving-certificate.adoc#service-serving-certificate[service serving certificate secrets]. -Communication between the webhook admission plug-in and the webhook server must use TLS. Generate a CA certificate and use the certificate to sign the server certificate that is used by your webhook admission server. The PEM-encoded CA certificate is supplied to the webhook admission plug-in using a mechanism, such as service serving certificate secrets. - -The following diagram illustrates the sequential admission chain process within which multiple webhook servers are called. - -.API admission chain with mutating and validating admission plug-ins -image::api-admission-chain.png["API admission stage", align="center"] - -An example webhook admission plug-in use case is where all pods must have a common set of labels. In this example, the mutating admission plug-in can inject labels and the validating admission plug-in can check that labels are as expected. {product-title} would subsequently schedule pods that include required labels and reject those that do not. - -Some common webhook admission plug-in use cases include: - -//Future xref - * Namespace reservation. -* Namespace reservation. -//Future xrefs - * :../networking/hardware_networks/configuring-sriov-operator.adoc#configuring-sriov-operator[Limiting custom network resources managed by the SR-IOV network device plug-in]. -* Limiting custom network resources managed by the SR-IOV network device plug-in. -//Future xref - * xref:../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations_dedicating_nodes-scheduler-taints-tolerations[Defining tolerations that enable taints to qualify which pods should be scheduled on a node]. -* Defining tolerations that enable taints to qualify which pods should be scheduled on a node. -//Future xref - * xref:../nodes/pods/nodes-pods-priority.adoc#admin-guide-priority-preemption-names_nodes-pods-priority[Pod priority class validation]. -* Pod priority class validation. diff --git a/modules/all-report-jobs-tab.adoc b/modules/all-report-jobs-tab.adoc new file mode 100644 index 000000000000..d8c390afc16a --- /dev/null +++ b/modules/all-report-jobs-tab.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: CONCEPT +[id="all-report-jobs-tab_{context}"] += All report jobs tab + +The *All report jobs* tab shows the current status and requester for each report job, with completed jobs indicated in the row expansion section. + +The report jobs are organized into the following groups: + +Completed:: Indicates which report jobs have been finished. +Status:: Displays the current state of each report job. ++ +The following values are associated with the report job status: ++ +`Waiting`::: The report job is in the queue. +`Preparing`::: The report job is being processed. +`Report ready for download`::: The report is ready and available for download. +`Partial report ready for download`::: A report is partially complete and ready for download. +`Report successfully sent`::: The report was successfully emailed. +`Partial report successfully sent`::: A report is partially complete and was successfully emailed. +`Report failed to generate`::: There was an issue with the report job. Hover to view the error message. +`None`::: There are no recent jobs available. + +Requester:: Identifies the user or system account that initiated the report job. \ No newline at end of file diff --git a/modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc b/modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc deleted file mode 100644 index 0fad9f8d59ae..000000000000 --- a/modules/alternatives-to-storing-admin-secrets-in-kube-system.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/manually-creating-iam.adoc -// * installing/installing_azure/manually-creating-iam-azure.adoc -// * installing/installing_gcp/manually-creating-iam-gcp.adoc - -ifeval::["{context}" == "manually-creating-iam-aws"] -:aws: -endif::[] -ifeval::["{context}" == "manually-creating-iam-azure"] -:azure: -endif::[] -ifeval::["{context}" == "manually-creating-iam-gcp"] -:google-cloud-platform: -endif::[] - -[id="alternatives-to-storing-admin-secrets-in-kube-system_{context}"] -= Alternatives to storing administrator-level secrets in the kube-system project - -The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubernetes custom resource definitions (CRDs). You can configure the CCO to suit the security requirements of your organization by setting different values for the `credentialsMode` parameter in the `install-config.yaml` file. - -ifdef::aws,google-cloud-platform[] -If you prefer not to store an administrator-level credential secret in the cluster `kube-system` project, you can choose one of the following options when installing {product-title}: - -* *Manage cloud credentials manually*: -+ -You can set the `credentialsMode` parameter for the CCO to `Manual` to manage cloud credentials manually. Using manual mode allows each cluster component to have only the permissions it requires, without storing an administrator-level credential in the cluster. You can also use this mode if your environment does not have connectivity to the cloud provider public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade. You must also manually supply credentials for every component that requests them. - -* *Remove the administrator-level credential secret after installing {product-title} with mint mode*: -+ -If you are using the CCO with the `credentialsMode` parameter set to `Mint`, you can remove or rotate the administrator-level credential after installing {product-title}. Mint mode is the default configuration for the CCO. This option requires the presence of the administrator-level credential during an installation. The administrator-level credential is used during the installation to mint other credentials with some permissions granted. The original credential secret is not stored in the cluster permanently. - -[NOTE] -==== -Prior to a non z-stream upgrade, you must reinstate the credential secret with the administrator-level credential. If the credential is not present, the upgrade might be blocked. -==== - -endif::aws,google-cloud-platform[] - -ifdef::azure[] -If you prefer not to store an administrator-level credential secret in the cluster `kube-system` project, you can set the `credentialsMode` parameter for the CCO to `Manual` when installing {product-title} and manage your cloud credentials manually. - -Using manual mode allows each cluster component to have only the permissions it requires, without storing an administrator-level credential in the cluster. You can also use this mode if your environment does not have connectivity to the cloud provider public IAM endpoint. However, you must manually reconcile permissions with new release images for every upgrade. You must also manually supply credentials for every component that requests them. -endif::azure[] diff --git a/modules/amazon-s3-configuring-acs.adoc b/modules/amazon-s3-configuring-acs.adoc new file mode 100644 index 000000000000..1654ce8c3375 --- /dev/null +++ b/modules/amazon-s3-configuring-acs.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-amazon-s3.adoc +:_mod-docs-content-type: PROCEDURE +[id="amazon-s3-configuring-acs_{context}"] += Configuring Amazon S3 integration in {product-title} + +To configure Amazon S3 backups, create a new integration in {product-title}. + +.Prerequisites +* An existing S3 Bucket. +To create a new bucket with required permissions, see the Amazon documentation topic link:https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html[Creating a bucket]. +* `Read`, `write`, and `delete` permissions for the S3 bucket, the *Access key ID*, and the *Secret access key*. +* If you are using *KIAM*, *kube2iam* or another proxy, then an *IAM role* that has the `read`, `write`, and `delete` permissions. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *External backups* section and select *Amazon S3*. +. Click *New Integration* (*`add`* icon). +. Enter a name for *Integration Name*. +. Enter the number of backups to retain in the *Backups To Retain* box. +. For *Schedule*, select the backup frequency as daily or weekly and the time to run the backup process. +. Enter the *Bucket* name where you want to store the backup. +. Optionally, enter an *Object Prefix* if you want to save the backups in a specific folder structure. +For more information, see the Amazon documentation topic link:https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html#object-keys[Working with object metadata]. +. Enter the *Endpoint* for the bucket if you are using a non-public S3 instance, otherwise leave it blank. +. Enter the *Region* for the bucket. +. Turn on the *Use Container IAM Role* toggle or enter the *Access Key ID*, and the *Secret Access Key*. +. Select *Test* to confirm that the integration with Amazon S3 is working. +. Select *Create* to generate the configuration. + +Once configured, {product-title} automatically backs up all data according to the specified schedule. diff --git a/modules/analyze-images-and-deployments-without-observed-cves.adoc b/modules/analyze-images-and-deployments-without-observed-cves.adoc new file mode 100644 index 000000000000..69c56ed6a0e0 --- /dev/null +++ b/modules/analyze-images-and-deployments-without-observed-cves.adoc @@ -0,0 +1,95 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="analyze-images-and-deployments-without-observed-cves_{context}"] += Analyze images and deployments without observed CVEs + +When you view the list of images without vulnerabilities, {product-title-short} shows the images that meet at least one of the following conditions: + +** Images that do not have CVEs +** Images that report a scanner error that may result in a false negative of no CVEs + +[NOTE] +==== +An image that actually contains vulnerabilities can appear in this list inadvertently. For example, if Scanner was able to scan the image and it is known to {rh-rhacs-first}, but the scan was not successfully completed, {product-title-short} cannot detect vulnerabilities. + +This scenario occurs if an image has an operating system that {product-title-short} Scanner does not support. {product-title-short} displays scan errors when you hover over an image in the image list or click the image name for more information. +==== + +.Procedure + +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Results*. +. Click *More Views* and select *Images without CVEs*. +. To filter the list of results by entity, for example, to search for a specific image, select the appropriate filters and attributes. ++ +To select multiple entities and attributes, click the right arrow icon to add another criteria. Depending on your choices, enter the appropriate information such as text, or select a date or object. ++ +The filter entities and attributes are listed in the following table. ++ +[NOTE] +==== +The *Filtered view* icon indicates that the displayed results were filtered based on the criteria that you selected. You can click *Clear filters* to remove all filters, or remove individual filters by clicking on them. +==== ++ +.Filter options +[cols="2",options="header"] +|=== +|Entity|Attributes + +|Image +a| +* *Name*: The name of the image. +* *Operating system*: The operating system of the image. +* *Tag*: The tag for the image. +* *Label*: The label for the image. +* *Registry*: The registry where the image is located. + +|Image Component +a| + +* *Name*: The name of the image component, for example, `activerecord-sql-server-adapter` +* *Source*: +** OS +** Python +** Java +** Ruby +** Node.js +** Go +** Dotnet Core Runtime +** Infrastructure + +* *Version*: Version of the image component; for example, `3.4.21`. You can use this to search for a specific version of a component, for example, in conjunction with a component name. +|Deployment +a| +* *Name*: Name of the deployment. +* *Label*: Label for the deployment. +* *Annotation*: The annotation for the deployment. +* *Status*: Whether the deployment is inactive or active. +|Namespace +a| +* *ID*: The `metadata.uid` of the namespace that is created by Kubernetes. +* *Name*: The name of the namespace. +* *Label*: The label for the namespace. +* *Annotation*: The annotation for the namespace. +|Cluster +a| +* *ID*: The alphanumeric ID for the cluster. This is an internal identifier that {product-title-short} assigns for tracking purposes. +* *Name*: The name of the cluster. +* *Label*: The label for the cluster. +* *Type*: The cluster type, for example, OCP. +* *Platform type*: The platform type, for example, OpenShift 4 cluster. +|=== +. Click one of the following tabs to view the data that you want: +* * Images*: Displays images that contain discovered vulnerabilities. +* * Deployments*: Displays deployments that contain discovered vulnerabilities. +. Optional: Choose the appropriate method to re-organize the information in the page: +* To select the categories that you want to display in the table, perform the following steps: +.. Click *Columns*. +.. Choose the appropriate method to manage the columns: +*** To view all the categories, click *Select all*. +*** To reset to the default categories, click *Reset to default*. +*** To view only the selected categories, select the one or more categories that you want to view, and then click *Save*. +*** To sort the table in ascending or descending order, select a column heading. +. In the list of results, click an image name or deployment name to view more information about the item. \ No newline at end of file diff --git a/modules/analyzing-all-violations.adoc b/modules/analyzing-all-violations.adoc new file mode 100644 index 000000000000..d4d258505e8b --- /dev/null +++ b/modules/analyzing-all-violations.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: PROCEDURE +[id="analyzing-all-violations_{context}"] += Analyzing all violations + +By viewing the *Violations* page, you can analyze all violations and take corrective action. + +.Procedure + +. In the {product-title-short} portal, click *Violations*. +. Click one of the following tabs to view violations by category: +** *User Workloads*: Displays violations for user-managed workloads. +** *Platform*: Displays violations for workloads used by {ocp} and layered services. +** *All violations*: Displays violations for user workloads and platform components. It also displays audit log violations for cluster resources. +. Click one of the following tabs to view violations by type: +** *Active*: Displays violations in the build and deploy stages or unresolved runtime violations. +** *Resolved*: Displays the following violations: +*** Violations in the build and deploy stages for workloads that were removed or modified to be compliant +*** Manually resolved runtime violations +*** Violations that were generated before a policy exclusion was added +** *Attempted*: Displays violations for deployment actions that were attempted but blocked by the evaluation of enforced policies. For example, if the admission controller detected that the attempted deployment action, such as a deployment create, update, or scale, would cause a policy violation, it prevented the operation from running in the cluster. +. Optional: Choose a method to reorganize or filter information on the *Violations* page: +** To sort the violations in ascending or descending order, select a column heading. +** To filter violations, use the filter bar. +** To see more details about the violation, select a violation in the *Violations* page. +. Optional: Choose the appropriate method to exclude a deployment from the policy: +** If you selected a single deployment, click the overflow menu {kebab} and then select *Exclude deployment from policy*. +** If you selected multiple deployments, from the *Row actions* drop-down list, select *Exclude deployments from policy*. +//Do we need to add an explanation for "Mark as resolved"? \ No newline at end of file diff --git a/modules/analyzing-and-managing-the-system-health-information.adoc b/modules/analyzing-and-managing-the-system-health-information.adoc new file mode 100644 index 000000000000..4bb3089e56a0 --- /dev/null +++ b/modules/analyzing-and-managing-the-system-health-information.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * operating/use-system-health-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="analyzing-and-managing-the-system-health-information_{context}"] += Analyzing and managing the system health information + +You can view all the health-related information associated with the {rh-rhacs-first} components on the *System Health* page. + +.Procedure +. In the {product-title-short} portal, click *Platform Configuration* -> *System Health*. +. Optional: To download the administration usage data as a CSV file, perform the following steps: +.. Click *Show administration usage*. ++ +[NOTE] +==== +The *Administration usage* page displays the administration usage data you have collected, including the number of secured Kubernetes nodes and CPU units. The current usage reflects the last metrics received from Sensors, with a delay of about 5 minutes. + +Maximum usage is aggregated hourly and only includes clusters that are still connected. The date range is inclusive and matches your time zone. This data is not sent to Red Hat or displayed as Prometheus metrics. +==== +.. Enter the start and end date in `YYYY-MM-DD` format. If you do not specify the start and end date, the first and last day of the month is selected automatically. +.. To download the administration usage data, click *Download CSV*. + +. Optional: To download the platform data, perform the following steps: +.. Click *Generate diagnostic bundle*. +.. Optional: Choose the appropriate method to filter the platform data that you want to include in the compressed file: +*** To filter the platform data based on specific clusters, select one or more clusters from the *Filter by clusters* drop-down list. If you do not select a cluster, all clusters are selected automatically. +*** To filter the platform data according to the start time, enter a time in coordinated universal time (UTC) format, `yyyy-mm-ddThh:mmZ`. If you do not specify a start time, the diagnostic bundle includes the platform data for the last 20 minutes. +.. To download the platform data, click *Download diagnostic bundle*. + +. Optional: To view the *Cluster status*, *Sensor upgrade*, or *Credential expiration* information associated with one or more clusters, perform the following steps: +.. Click *View clusters*. +.. To display further details on a cluster, click on the cluster name. +.. You can find all the status information associated with the selected cluster in the *Cluster summary* section. +.. Click *Next*. +.. Optional: To download the required YAML file to update your Helm values, click *Download Helm values*. +.. Click *Finish*. + +. Optional: To update the certificate associated with the {product-title-short} components such as Central, StackRox Scanner, or Scanner V4, perform the following steps: +.. Scroll down to locate the component for which you want to update the certificate. +.. Click *Download YAML*. +.. Optional: To reissue the internal certificates, perform the following steps: +... Click *Reissuing internal certificates*. +... Follow the instructions in the Red{nbsp}Hat documentation to apply the YAML and complete the reissue. \ No newline at end of file diff --git a/modules/analyzing-compliance-scan-schedules.adoc b/modules/analyzing-compliance-scan-schedules.adoc new file mode 100644 index 000000000000..64c97f14a832 --- /dev/null +++ b/modules/analyzing-compliance-scan-schedules.adoc @@ -0,0 +1,58 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="analyzing-compliance-scan-schedules_{context}"] += Analyzing compliance scan schedules + +By viewing the *Schedules* page, you can analyze the various attributes of the compliance scan schedule that you created. + +.Prerequisites + +* You have created a compliance scan schedule. ++ +For more information about how to create a compliance scan schedule, see "Customizing and automating your compliance scans". + +.Procedure + +. In the {product-title-short} portal, click *Compliance -> OpenShift Schedules*. +. Optional: To sort the compliance scan schedules in ascending or descending order, select the *Name* column heading. +. Select the compliance scan that you have created. +. Optional: To sort the cluster health information in ascending or descending order, select a column heading in the *Clusters* section. +. Optional: To view the status of the one or more requested jobs from different users: +.. Click the *All report jobs* tab. +.. You can find the status of the one or more report jobs in the *Status* column. +.. Optional: Choose the appropriate method to re-organize the information in the *All report jobs* section: +*** To sort the jobs in ascending or descending order, select the *Completed* column heading. +*** To filter the jobs based on the report run states, select one or more states from the *Filter by report run states* drop-down list. ++ +The following values are associated with the report run states: ++ +**** `Waiting` +**** `Preparing` +**** `Report ready for download` +**** `Partial report ready for download` +**** `Report successfully sent` +**** `Partial report successfully sent` +**** `Report failed to generate` +*** To view only the jobs that you created, set *View only my jobs* to on. +.. Optional: To view the job details associated with a report job, perform the following steps: +... Locate the report job for which you want to view the job details. +... To view the job details, expand the report job. + +//This is not implemented in 4.6 +//// +. Optional: To set the retention period for the scan schedule report, perform the following steps: +.. In the {product-title-short} portal, click *Platform Configuration* -> *System Configuration*. ++ +You can configure the following setting for scan schedule reports: ++ +*** *Vulnerability report job history retention*: The number of days to retain your scan schedule report. +.. To edit this value, click *Edit*, make your changes, and then click *Save*. ++ +[NOTE] +==== +All report jobs are kept in your system until they exceed the limit you set. +==== +//// \ No newline at end of file diff --git a/modules/analyzing-the-collector-pod-status.adoc b/modules/analyzing-the-collector-pod-status.adoc new file mode 100644 index 000000000000..838ef314cb43 --- /dev/null +++ b/modules/analyzing-the-collector-pod-status.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * troubleshooting/retrieving-and-analyzing-the-collector-logs-and-pod-status.adoc +:_mod-docs-content-type: PROCEDURE +[id="analyzing-the-collector-pod-status_{context}"] += Analyzing the Collector pod status + +Examining the pod's most recent status is another easy way to determine the cause of a Collector crash. Failure messages are recorded to the most recent status and are accessible using the `kubectl describe pod` or `oc describe pod` command. + +.Procedure + +* Describe the Collector pod: ++ +[source,terminal,subs="+quotes"] +---- +$ oc describe pod -n stackrox __ <1> +---- ++ +-- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. For `__`, specify the name of your Collector pod, for example, `collector-vclg5`. +-- ++ +.Example output ++ +[source,text] +---- +# ... + Last State: Terminated + Reason: Error + Message: No suitable kernel object downloaded <1> + Exit Code: 1 + Started: Fri, 21 Oct 2022 11:50:56 +0100 + Finished: Fri, 21 Oct 2022 11:51:25 +0100 +# ... +---- ++ +-- +<1> In this example, you can see that Collector has failed to download a kernel driver. +-- \ No newline at end of file diff --git a/modules/annotating-a-route-with-a-cookie-name.adoc b/modules/annotating-a-route-with-a-cookie-name.adoc deleted file mode 100644 index f2bef5522ad0..000000000000 --- a/modules/annotating-a-route-with-a-cookie-name.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// *using-cookies-to-keep-route-statefulness - -[id="annotating-a-route-with-a-cookie_{context}"] -= Annotating a route with a cookie - -You can set a cookie name to overwrite the default, auto-generated one for the -route. This allows the application receiving route traffic to know the cookie -name. By deleting the cookie it can force the next request to re-choose an -endpoint. So, if a server was overloaded it tries to remove the requests from the -client and redistribute them. - -.Procedure - -. Annotate the route with the desired cookie name: -+ -[source,terminal] ----- -$ oc annotate route router.openshift.io/="-" ----- -+ -For example, to annotate the cookie name of `my_cookie` to the `my_route` with -the annotation of `my_cookie_anno`: -+ -[source,terminal] ----- -$ oc annotate route my_route router.openshift.io/my_cookie="-my_cookie_anno" ----- - -. Save the cookie, and access the route: -+ -[source,terminal] ----- -$ curl $my_route -k -c /tmp/my_cookie ----- diff --git a/modules/apiserversource-kn-delete.adoc b/modules/apiserversource-kn-delete.adoc deleted file mode 100644 index 4eef4f0d4285..000000000000 --- a/modules/apiserversource-kn-delete.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-apiserversource.adoc - -[id="delete-apiserversource-kn_{context}"] -= Deleting the API server source using the Knative CLI - -This section describes the steps used to delete the API server source, trigger, service account, cluster role, and cluster role binding using `kn` and `oc` commands. - -.Prerequisites - -* You must have the `kn` CLI installed. - -.Procedure - -. Delete the trigger: -+ -[source,terminal] ----- -$ kn trigger delete ----- - -. Delete the event source: -+ -[source,terminal] ----- -$ kn source apiserver delete ----- - -. Delete the service account, cluster role, and cluster binding: -+ -[source,terminal] ----- -$ oc delete -f authentication.yaml ----- diff --git a/modules/apiserversource-kn.adoc b/modules/apiserversource-kn.adoc deleted file mode 100644 index 177f3fb40c9f..000000000000 --- a/modules/apiserversource-kn.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-apiserversource.adoc - -[id="apiserversource-kn_context"] -= Using the API server source with the Knative CLI - -This section describes the steps required to create an API server source using `kn` commands. - -.Prerequisites - -* You must have {ServerlessProductName}, the Knative Serving and Eventing components, and the `kn` CLI installed. - -.Procedure - -. Create an API server source that uses a broker as an event sink: -+ -[source,terminal] ----- -$ kn source apiserver create --sink broker: --resource "event:v1" --service-account --mode Resource ----- - -. To check that the API server source is set up correctly, create a Knative service that dumps incoming messages to its log: -+ -[source,terminal] ----- -$ kn service create --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- - -. Create a trigger to filter events from the `default` broker to the service: -+ -[source,terminal] ----- -$ kn trigger create --sink ksvc: ----- - -. Create events by launching a Pod in the default namespace: -+ -[source,terminal] ----- -$ oc create deployment hello-node --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- - -. Check that the controller is mapped correctly by inspecting the output generated by the following command: -+ -[source,terminal] ----- -$ kn source apiserver describe ----- -+ -.Example output -[source,terminal] ----- -Name: mysource -Namespace: default -Annotations: sources.knative.dev/creator=developer, sources.knative.dev/lastModifier=developer -Age: 3m -ServiceAccountName: events-sa -Mode: Resource -Sink: - Name: default - Namespace: default - Kind: Broker (eventing.knative.dev/v1) -Resources: - Kind: event (v1) - Controller: false -Conditions: - OK TYPE AGE REASON - ++ Ready 3m - ++ Deployed 3m - ++ SinkProvided 3m - ++ SufficientPermissions 3m - ++ EventTypesProvided 3m ----- - -.Verification - -You can verify that the Kubernetes events were sent to Knative by looking at the message dumper function logs. - -. Get the pods: -+ -[source,terminal] ----- -$ oc get pods ----- - -. View the message dumper function logs for the pods: -+ -[source,terminal] ----- -$ oc logs $(oc get pod -o name | grep event-display) -c user-container ----- -+ -.Example output -[source,terminal] ----- -☁️ cloudevents.Event -Validation: valid -Context Attributes, - specversion: 1.0 - type: dev.knative.apiserver.resource.update - datacontenttype: application/json - ... -Data, - { - "apiVersion": "v1", - "involvedObject": { - "apiVersion": "v1", - "fieldPath": "spec.containers{hello-node}", - "kind": "Pod", - "name": "hello-node", - "namespace": "default", - ..... - }, - "kind": "Event", - "message": "Started container", - "metadata": { - "name": "hello-node.159d7608e3a3572c", - "namespace": "default", - .... - }, - "reason": "Started", - ... - } ----- diff --git a/modules/apiserversource-yaml-delete.adoc b/modules/apiserversource-yaml-delete.adoc deleted file mode 100644 index 49ed835107bf..000000000000 --- a/modules/apiserversource-yaml-delete.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-apiserversource.adoc - -[id="delete-apiserversource-yaml_{context}"] -= Deleting the API server source - -This section describes how to delete the API server source, trigger, service account, cluster role, and cluster role binding by deleting their YAML files. - -.Procedure - -. Delete the trigger: -+ -[source,terminal] ----- -$ oc delete -f trigger.yaml ----- - -. Delete the event source: -+ -[source,terminal] ----- -$ oc delete -f k8s-events.yaml ----- - -. Delete the service account, cluster role, and cluster binding: -+ -[source,terminal] ----- -$ oc delete -f authentication.yaml ----- diff --git a/modules/apiserversource-yaml.adoc b/modules/apiserversource-yaml.adoc deleted file mode 100644 index 745ebda54455..000000000000 --- a/modules/apiserversource-yaml.adoc +++ /dev/null @@ -1,248 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/event_workflows/serverless-listing-event-sources.adoc - -[id="apiserversource-yaml_context"] -= Using the API server source with the YAML method - -This guide describes the steps required to create an API server source using YAML files. - -.Prerequisites - -* You will need to have a Knative Serving and Eventing installation. -* You will need to have created the `default` broker in the same namespace as the one defined in the API server source YAML file. - -.Procedure - -. To create a service account, role, and role binding for the API server source, create a file named `authentication.yaml` and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: events-sa - namespace: default <1> - ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: event-watcher - namespace: default <1> -rules: - - apiGroups: - - "" - resources: - - events - verbs: - - get - - list - - watch - ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: k8s-ra-event-watcher - namespace: default <1> -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: event-watcher -subjects: - - kind: ServiceAccount - name: events-sa - namespace: default <1> ----- -<1> Change this namespace to the namespace that you have selected for installing API server source. -+ -[NOTE] -==== -If you want to re-use an existing service account with the appropriate permissions, you must modify the `authentication.yaml` for that service account. -==== -+ -After you have created the `authentication.yaml` file, apply it: -+ -[source,terminal] ----- -$ oc apply -f authentication.yaml ----- - -. To create an API server source, create a file named `k8s-events.yaml` and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: sources.knative.dev/v1alpha1 -kind: ApiServerSource -metadata: - name: testevents -spec: - serviceAccountName: events-sa - mode: Resource - resources: - - apiVersion: v1 - kind: Event - sink: - ref: - apiVersion: eventing.knative.dev/v1 - kind: Broker - name: default ----- - -+ -After you have created the `k8s-events.yaml` file, apply it: -+ -[source,terminal] ----- -$ oc apply -f k8s-events.yaml ----- - -. To check that the API server source is set up correctly, create a Knative service that dumps incoming messages to its log. -+ -Copy the following sample YAML into a file named `service.yaml`: -+ -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: event-display - namespace: default -spec: - template: - spec: - containers: - - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- -+ -After you have created the `service.yaml` file, apply it: -+ -[source,terminal] ----- -$ oc apply -f service.yaml ----- - -. To create a trigger from the `default` broker that filters events to the service created in the previous step, create a file named `trigger.yaml` and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: eventing.knative.dev/v1 -kind: Trigger -metadata: - name: event-display-trigger - namespace: default -spec: - broker: default - subscriber: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display ----- -+ -After you have created the `trigger.yaml` file, apply it: -+ -[source,terminal] ----- -$ oc apply -f trigger.yaml ----- - -. To create events, launch a Pod in the default namespace: -+ -[source,terminal] ----- -$ oc create deployment hello-node --image=quay.io/openshift-knative/knative-eventing-sources-event-display ----- - -. To check that the controller is mapped correctly, enter the following command and inspect the output: -+ -[source,terminal] ----- -$ oc get apiserversource.sources.knative.dev testevents -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: sources.knative.dev/v1alpha1 -kind: ApiServerSource -metadata: - annotations: - creationTimestamp: "2020-04-07T17:24:54Z" - generation: 1 - name: testevents - namespace: default - resourceVersion: "62868" - selfLink: /apis/sources.knative.dev/v1alpha1/namespaces/default/apiserversources/testevents2 - uid: 1603d863-bb06-4d1c-b371-f580b4db99fa -spec: - mode: Resource - resources: - - apiVersion: v1 - controller: false - controllerSelector: - apiVersion: "" - kind: "" - name: "" - uid: "" - kind: Event - labelSelector: {} - serviceAccountName: events-sa - sink: - ref: - apiVersion: eventing.knative.dev/v1 - kind: Broker - name: default ----- - -.Verification - -To verify that the Kubernetes events were sent to Knative, you can look at the message dumper function logs. - -. Get the pods: -+ -[source,terminal] ----- -$ oc get pods ----- - -. View the message dumper function logs for the pods: -+ -[source,terminal] ----- -$ oc logs $(oc get pod -o name | grep event-display) -c user-container ----- -+ -.Example output -[source,terminal] ----- -☁️ cloudevents.Event -Validation: valid -Context Attributes, - specversion: 1.0 - type: dev.knative.apiserver.resource.update - datacontenttype: application/json - ... -Data, - { - "apiVersion": "v1", - "involvedObject": { - "apiVersion": "v1", - "fieldPath": "spec.containers{hello-node}", - "kind": "Pod", - "name": "hello-node", - "namespace": "default", - ..... - }, - "kind": "Event", - "message": "Started container", - "metadata": { - "name": "hello-node.159d7608e3a3572c", - "namespace": "default", - .... - }, - "reason": "Started", - ... - } ----- diff --git a/modules/application-health-about.adoc b/modules/application-health-about.adoc deleted file mode 100644 index 79cd5b16d7dd..000000000000 --- a/modules/application-health-about.adoc +++ /dev/null @@ -1,217 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/application-health.adoc - -[id="application-health-about_{context}"] -= Understanding health checks - -A health check periodically performs diagnostics on a -running container using any combination of the readiness, liveness, and startup health checks. - -You can include one or more probes in the specification for the pod that contains the container which you want to perform the health checks. - -[NOTE] -==== -If you want to add or edit health checks in an existing pod, you must edit the pod `DeploymentConfig` object or use the *Developer* perspective in the web console. You cannot use the CLI to add or edit health checks for an existing pod. -==== - -Readiness probe:: -A _readiness probe_ determines if a container is ready to accept service requests. If -the readiness probe fails for a container, the kubelet removes the pod from the list of available service endpoints. -+ -After a failure, the probe continues to examine the pod. If the pod becomes available, the kubelet adds the pod to the list of available service endpoints. - -Liveness health check:: -A _liveness probe_ determines if a container is still -running. If the liveness probe fails due to a condition such as a deadlock, the kubelet kills the container. The pod then -responds based on its restart policy. -+ -For example, a liveness probe on a pod with a `restartPolicy` of `Always` or `OnFailure` -kills and restarts the container. - -Startup probe:: -A _startup probe_ indicates whether the application within a container is started. All other probes are disabled until the startup succeeds. If the startup probe does not succeed within a specified time period, the kubelet kills the container, and the container is subject to the pod `restartPolicy`. -+ -Some applications can require additional start-up time on their first initialization. You can use a startup probe with a liveness or readiness probe to delay that probe long enough to handle lengthy start-up time using the `failureThreshold` and `periodSeconds` parameters. -+ -For example, you can add a startup probe, with a `failureThreshold` of 30 failures and a `periodSeconds` of 10 seconds (30 * 10s = 300s) for a maximum of 5 minutes, to a liveness probe. After the startup probe succeeds the first time, the liveness probe takes over. - -You can configure liveness, readiness, and startup probes with any of the following types of tests: - -* HTTP `GET`: When using an HTTP `GET` test, the test determines the healthiness of the container by using a web hook. The test is successful if the HTTP response code is between `200` and `399`. -+ -You can use an HTTP `GET` test with applications that return HTTP status codes when completely initialized. - -* Container Command: When using a container command test, the probe executes a command inside the container. The probe is successful if the test exits with a `0` status. - -* TCP socket: When using a TCP socket test, the probe attempts to open a socket to the container. The container is only -considered healthy if the probe can establish a connection. You can use a TCP socket test with applications that do not start listening until -initialization is complete. - -You can configure several fields to control the behavior of a probe: - -* `initialDelaySeconds`: The time, in seconds, after the container starts before the probe can be scheduled. The default is 0. -* `periodSeconds`: The delay, in seconds, between performing probes. The default is `10`. -* `timeoutSeconds`: The number of seconds of inactivity after which the probe times out and the container is assumed to have failed. The default is `1`. -* `successThreshold`: The number of times that the probe must report success after a failure to reset the container status to successful. The value must be `1` for a liveness probe. The default is `1`. -* `failureThreshold`: The number of times that the probe is allowed to fail. The default is 3. After the specified attempts: -** for a liveness probe, the container is restarted -** for a readiness probe, the pod is marked `Unready` -** for a startup probe, the container is killed and is subject to the pod's `restartPolicy` -+ -[NOTE] -==== -The `timeoutSeconds` parameter has no effect on the readiness and liveness -probes for container command probes, as {product-title} cannot time out on an exec call into -the container. One way to implement a timeout in a container command probe is by using the `exec-timeout` command to run your -liveness or readiness probes, as shown in the examples. -==== - -[discrete] -[id="application-health-examples"] -== Example probes - -The following are samples of different probes as they would appear in an object specification. - -.Sample readiness probe with a container command readiness probe in a pod spec -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - labels: - test: health-check - name: my-application -... -spec: - containers: - - name: goproxy-app <1> - args: - image: k8s.gcr.io/goproxy:0.1 <2> - readinessProbe: <3> - exec: <4> - command: <5> - - cat - - /tmp/healthy -... ----- - -<1> The container name. -<2> The container image to deploy. -<3> A readiness probe. -<4> A container command test. -<5> The commands to execute on the container. - -.Sample container command startup probe and liveness probe with container command tests in a pod spec -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - labels: - test: health-check - name: my-application -... -spec: - containers: - - name: goproxy-app <1> - args: - image: k8s.gcr.io/goproxy:0.1 <2> - livenessProbe: <3> - httpGet: <4> - scheme: HTTPS <5> - path: /healthz - port: 8080 <6> - httpHeaders: - - name: X-Custom-Header - value: Awesome - startupProbe: <7> - httpGet: <8> - path: /healthz - port: 8080 <9> - failureThreshold: 30 <10> - periodSeconds: 10 <11> -... ----- - -<1> The container name. -<2> Specify the container image to deploy. -<3> A liveness probe. -<4> An HTTP `GET` test. -<5> The internet scheme: `HTTP` or `HTTPS`. The default value is `HTTP`. -<6> The port on which the container is listening. -<7> A startup probe. -<8> An HTTP `GET` test. -<9> The port on which the container is listening. -<10> The number of times to try the probe after a failure. -<11> The number of seconds to perform the probe. - -.Sample liveness probe with a container command test that uses a timeout in a pod spec -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - labels: - test: health-check - name: my-application -... -spec: - containers: - - name: goproxy-app <1> - args: - image: k8s.gcr.io/goproxy:0.1 <2> - livenessProbe: <3> - exec: <4> - command: <5> - - /bin/bash - - '-c' - - timeout 60 /opt/eap/bin/livenessProbe.sh - periodSeconds: 10 <6> - successThreshold: 1 <7> - failureThreshold: 3 <8> -... ----- - -<1> The container name. -<2> Specify the container image to deploy. -<3> The liveness probe. -<4> The type of probe, here a container command probe. -<5> The command line to execute inside the container. -<6> How often in seconds to perform the probe. -<7> The number of number of consecutive successes needed to show success after a failure. -<8> The number of times to try the probe after a failure. - -.Sample readiness probe and liveness probe with a TCP socket test in a deployment -[source,yaml] ----- -kind: Deployment -apiVersion: apps/v1 -... -spec: -... - template: - spec: - containers: - - resources: {} - readinessProbe: <1> - tcpSocket: - port: 8080 - timeoutSeconds: 1 - periodSeconds: 10 - successThreshold: 1 - failureThreshold: 3 - terminationMessagePath: /dev/termination-log - name: ruby-ex - livenessProbe: <2> - tcpSocket: - port: 8080 - initialDelaySeconds: 15 - timeoutSeconds: 1 - periodSeconds: 10 - successThreshold: 1 - failureThreshold: 3 -... ----- -<1> The readiness probe. -<2> The liveness probe. diff --git a/modules/application-health-configuring.adoc b/modules/application-health-configuring.adoc deleted file mode 100644 index 10a9d6475601..000000000000 --- a/modules/application-health-configuring.adoc +++ /dev/null @@ -1,129 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/application-health.adoc - -[id="application-health-configuring_{context}"] -= Configuring health checks using the CLI - -To configure readiness, liveness, and startup probes, add one or more probes to the specification for the pod that contains the container which you want to perform the health checks - -[NOTE] -==== -If you want to add or edit health checks in an existing pod, you must edit the pod `DeploymentConfig` object or use the *Developer* perspective in the web console. You cannot use the CLI to add or edit health checks for an existing pod. -==== - -.Procedure - -To add probes for a container: - -. Create a `Pod` object to add one or more probes: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - labels: - test: health-check - name: my-application -spec: - containers: - - name: my-container <1> - args: - image: k8s.gcr.io/goproxy:0.1 <2> - livenessProbe: <3> - tcpSocket: <4> - port: 8080 <5> - initialDelaySeconds: 15 <6> - timeoutSeconds: 1 <7> - readinessProbe: <8> - httpGet: <9> - host: my-host <10> - scheme: HTTPS <11> - path: /healthz - port: 8080 <12> - startupProbe: <13> - exec: <14> - command: <15> - - cat - - /tmp/healthy - failureThreshold: 30 <16> - periodSeconds: 10 <17> ----- -<1> Specify the container name. -<2> Specify the container image to deploy. -<3> Optional: Create a Liveness probe. -<4> Specify a test to perform, here a TCP Socket test. -<5> Specify the port on which the container is listening. -<6> Specify the time, in seconds, after the container starts before the probe can be scheduled. -<7> Specify the number of seconds between probes. -<8> Optional: Create a Readiness probe. -<9> Specify the type of test to perform, here an HTTP test. -<10> Specify a host IP address. When `host` is not defined, the `PodIP` is used. -<11> Specify `HTTP` or `HTTPS`. When `scheme` is not defined, the `HTTP` scheme is used. -<12> Specify the port on which the container is listening. -<13> Optional: Create a Startup probe. -<14> Specify the type of test to perform, here an Container Execution probe. -<15> Specify the commands to execute on the container. -<16> Specify the number of times to try the probe after a failure. -<17> Specify the number of seconds to perform the probe. -+ -[NOTE] -==== -If the `initialDelaySeconds` value is lower than the `periodSeconds` value, the first Readiness probe occurs at some point between the two periods due to an issue with timers. -==== - -. Create the `Pod` object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- - -. Verify the state of the health check pod: -+ -[source,terminal] ----- -$ oc describe pod health-check ----- -+ -.Example output -[source,terminal] ----- -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Scheduled 9s default-scheduler Successfully assigned openshift-logging/liveness-exec to ip-10-0-143-40.ec2.internal - Normal Pulling 2s kubelet, ip-10-0-143-40.ec2.internal pulling image "k8s.gcr.io/liveness" - Normal Pulled 1s kubelet, ip-10-0-143-40.ec2.internal Successfully pulled image "k8s.gcr.io/liveness" - Normal Created 1s kubelet, ip-10-0-143-40.ec2.internal Created container - Normal Started 1s kubelet, ip-10-0-143-40.ec2.internal Started container ----- -+ -The following is the output of a failed probe that restarted a container: -+ -.Sample Liveness check output with unhealthy container -[source,terminal] ----- -$ oc describe pod pod1 ----- -+ -.Example output -[source,terminal] ----- -.... - -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Scheduled Successfully assigned aaa/liveness-http to ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj - Normal AddedInterface 47s multus Add eth0 [10.129.2.11/23] - Normal Pulled 46s kubelet, ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj Successfully pulled image "k8s.gcr.io/liveness" in 773.406244ms - Normal Pulled 28s kubelet, ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj Successfully pulled image "k8s.gcr.io/liveness" in 233.328564ms - Normal Created 10s (x3 over 46s) kubelet, ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj Created container liveness - Normal Started 10s (x3 over 46s) kubelet, ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj Started container liveness - Warning Unhealthy 10s (x6 over 34s) kubelet, ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj Liveness probe failed: HTTP probe failed with statuscode: 500 - Normal Killing 10s (x2 over 28s) kubelet, ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj Container liveness failed liveness probe, will be restarted - Normal Pulling 10s (x3 over 47s) kubelet, ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj Pulling image "k8s.gcr.io/liveness" - Normal Pulled 10s kubelet, ci-ln-37hz77b-f76d1-wdpjv-worker-b-snzrj Successfully pulled image "k8s.gcr.io/liveness" in 244.116568ms ----- diff --git a/modules/applications-create-using-cli-image.adoc b/modules/applications-create-using-cli-image.adoc deleted file mode 100644 index b35597546b2c..000000000000 --- a/modules/applications-create-using-cli-image.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/application_life_cycle_management/creating-applications-using-the-cli.adoc - -[id="applications-create-using-cli-image_{context}"] -= Creating an application from an image - -You can deploy an application from an existing image. Images can come from image streams in the {product-title} server, images in a specific registry, or images in the local Docker server. - -The `new-app` command attempts to determine the type of image specified in the arguments passed to it. However, you can explicitly tell `new-app` whether the image is a container image using the `--docker-image` argument or an image stream using the `-i|--image-stream` argument. - -[NOTE] -==== -If you specify an image from your local Docker repository, you must ensure that the same image is available to the {product-title} cluster nodes. -==== - -== Docker Hub MySQL image - -Create an application from the Docker Hub MySQL image, for example: - -[source,terminal] ----- -$ oc new-app mysql ----- - -== Image in a private registry - -Create an application using an image in a private registry, specify the full container image specification: - -[source,terminal] ----- -$ oc new-app myregistry:5000/example/myimage ----- - -== Existing image stream and optional image stream tag - -Create an application from an existing image stream and optional image stream tag: - -[source,terminal] ----- -$ oc new-app my-stream:v1 ----- diff --git a/modules/applications-create-using-cli-modify.adoc b/modules/applications-create-using-cli-modify.adoc deleted file mode 100644 index 014a5ac832a0..000000000000 --- a/modules/applications-create-using-cli-modify.adoc +++ /dev/null @@ -1,205 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/application_life_cycle_management/creating-applications-using-the-cli.adoc - -[id="applications-create-using-cli-modify_{context}"] -= Modifying application creation - -The `new-app` command generates {product-title} objects that build, deploy, and run the application that is created. Normally, these objects are created in the current project and assigned names that are derived from the input source repositories or the input images. However, with `new-app` you can modify this behavior. - -.`new-app` output objects -[cols="2,8",options="header"] -|=== - -|Object |Description - -|`BuildConfig` -|A `BuildConfig` object is created for each source repository that is specified in the command line. The `BuildConfig` object specifies the strategy to use, the source location, and the build output location. - -|`ImageStreams` -|For the `BuildConfig` object, two image streams are usually created. One represents the input image. With source builds, this is the builder image. -ifndef::openshift-online[] -With `Docker` builds, this is the *FROM* image. -endif::[] -The second one represents the output image. If a container image was specified as input to `new-app`, then an image stream is created for that image as well. - -|`DeploymentConfig` -|A `DeploymentConfig` object is created either to deploy the output of a build, or a specified image. The `new-app` command creates `emptyDir` volumes for all Docker volumes that are specified in containers included in the resulting `DeploymentConfig` object . - -|`Service` -|The `new-app` command attempts to detect exposed ports in input images. It uses the lowest numeric exposed port to generate a service that exposes that port. To expose a different port, after `new-app` has completed, simply use the `oc expose` command to generate additional services. - -|Other -|Other objects can be generated when instantiating templates, according to the template. - -|=== - -== Specifying environment variables - -When generating applications from a template, source, or an image, you can use the `-e|--env` argument to pass environment variables to the application container at run time: - -[source,terminal] ----- -$ oc new-app openshift/postgresql-92-centos7 \ - -e POSTGRESQL_USER=user \ - -e POSTGRESQL_DATABASE=db \ - -e POSTGRESQL_PASSWORD=password ----- - -The variables can also be read from file using the `--env-file` argument. The following is an example file called `postgresql.env`: - -[source,terminal] ----- -POSTGRESQL_USER=user -POSTGRESQL_DATABASE=db -POSTGRESQL_PASSWORD=password ----- - -Read the variables from the file: - -[source,terminal] ----- -$ oc new-app openshift/postgresql-92-centos7 --env-file=postgresql.env ----- - -Additionally, environment variables can be given on standard input by using `--env-file=-`: - -[source,terminal] ----- -$ cat postgresql.env | oc new-app openshift/postgresql-92-centos7 --env-file=- ----- - -[NOTE] -==== -Any `BuildConfig` objects created as part of `new-app` processing are not updated with environment variables passed with the `-e|--env` or `--env-file` argument. -==== - -== Specifying build environment variables - -When generating applications from a template, source, or an image, you can use the `--build-env` argument to pass environment variables to the build container at run time: - -[source,terminal] ----- -$ oc new-app openshift/ruby-23-centos7 \ - --build-env HTTP_PROXY=http://myproxy.net:1337/ \ - --build-env GEM_HOME=~/.gem ----- - -The variables can also be read from a file using the `--build-env-file` argument. The following is an example file called `ruby.env`: - -[source,terminal] ----- -HTTP_PROXY=http://myproxy.net:1337/ -GEM_HOME=~/.gem ----- - -Read the variables from the file: - -[source,terminal] ----- -$ oc new-app openshift/ruby-23-centos7 --build-env-file=ruby.env ----- - -Additionally, environment variables can be given on standard input by using `--build-env-file=-`: - -[source,terminal] ----- -$ cat ruby.env | oc new-app openshift/ruby-23-centos7 --build-env-file=- ----- - -== Specifying labels - -When generating applications from source, images, or templates, you can use the `-l|--label` argument to add labels to the created objects. Labels make it easy to collectively select, configure, and delete objects associated with the application. - -[source,terminal] ----- -$ oc new-app https://github.com/openshift/ruby-hello-world -l name=hello-world ----- - -== Viewing the output without creation - -To see a dry-run of running the `new-app` command, you can use the `-o|--output` argument with a `yaml` or `json` value. You can then use the output to preview the objects that are created or redirect it to a file that you can edit. After you are satisfied, you can use `oc create` to create the {product-title} objects. - -To output `new-app` artifacts to a file, run the following: - -[source,terminal] ----- -$ oc new-app https://github.com/openshift/ruby-hello-world \ - -o yaml > myapp.yaml ----- - -Edit the file: - -[source,terminal] ----- -$ vi myapp.yaml ----- - -Create a new application by referencing the file: - -[source,terminal] ----- -$ oc create -f myapp.yaml ----- - -== Creating objects with different names - -Objects created by `new-app` are normally named after the source repository, or the image used to generate them. You can set the name of the objects produced by adding a `--name` flag to the command: - -[source,terminal] ----- -$ oc new-app https://github.com/openshift/ruby-hello-world --name=myapp ----- - -== Creating objects in a different project - -Normally, `new-app` creates objects in the current project. However, you can create objects in a different project by using the `-n|--namespace` argument: - -[source,terminal] ----- -$ oc new-app https://github.com/openshift/ruby-hello-world -n myproject ----- - -== Creating multiple objects - -The `new-app` command allows creating multiple applications specifying multiple parameters to `new-app`. Labels specified in the command line apply to all objects created by the single command. Environment variables apply to all components created from source or images. - -To create an application from a source repository and a Docker Hub image: - -[source,terminal] ----- -$ oc new-app https://github.com/openshift/ruby-hello-world mysql ----- - -[NOTE] -==== -If a source code repository and a builder image are specified as separate arguments, `new-app` uses the builder image as the builder for the source code repository. If this is not the intent, specify the required builder image for the source using the `~` separator. -==== - -== Grouping images and source in a single pod - -The `new-app` command allows deploying multiple images together in a single pod. To specify which images to group together, use the `+` separator. The `--group` command line argument can also be used to specify the images that should be grouped together. To group the image built from a source repository with other images, specify its builder image in the group: - -[source,terminal] ----- -$ oc new-app ruby+mysql ----- - -To deploy an image built from source and an external image together: - -[source,terminal] ----- -$ oc new-app \ - ruby~https://github.com/openshift/ruby-hello-world \ - mysql \ - --group=ruby+mysql ----- - -== Searching for images, templates, and other inputs - -To search for images, templates, and other inputs for the `oc new-app` command, add the `--search` and `--list` flags. For example, to find all of the images or templates that include PHP: - -[source,terminal] ----- -$ oc new-app --search php ----- diff --git a/modules/applications-create-using-cli-source-code.adoc b/modules/applications-create-using-cli-source-code.adoc deleted file mode 100644 index 9fa5cd6c9b5b..000000000000 --- a/modules/applications-create-using-cli-source-code.adoc +++ /dev/null @@ -1,144 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/application_life_cycle_management/creating-applications-using-the-cli.adoc - -[id="applications-create-using-cli-source-code_{context}"] -= Creating an application from source code - -With the `new-app` command you can create applications from source code in a local or remote Git repository. - -The `new-app` command creates a build configuration, which itself creates a new application image from your source code. The `new-app` command typically also creates a `DeploymentConfig` object to deploy the new image, and a service to provide load-balanced access to the deployment running your image. - -{product-title} automatically detects whether the pipeline or source build strategy should be used, and in the case of source builds, detects an appropriate language builder image. - -== Local - -To create an application from a Git repository in a local directory: - -[source,terminal] ----- -$ oc new-app / ----- - -[NOTE] -==== -If you use a local Git repository, the repository must have a remote named `origin` that points to a URL that is accessible by the {product-title} cluster. If there is no recognized remote, running the `new-app` command will create a binary build. -==== - -== Remote - -To create an application from a remote Git repository: - -[source,terminal] ----- -$ oc new-app https://github.com/sclorg/cakephp-ex ----- - -To create an application from a private remote Git repository: - -[source,terminal] ----- -$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret ----- - -[NOTE] -==== -If you use a private remote Git repository, you can use the `--source-secret` flag to specify an existing source clone secret that will get injected into your build config to access the repository. -==== - -You can use a subdirectory of your source code repository by specifying a `--context-dir` flag. To create an application from a remote Git repository and a context subdirectory: - -[source,terminal] ----- -$ oc new-app https://github.com/sclorg/s2i-ruby-container.git \ - --context-dir=2.0/test/puma-test-app ----- - -Also, when specifying a remote URL, you can specify a Git branch to use by appending `#` to the end of the URL: - -[source,terminal] ----- -$ oc new-app https://github.com/openshift/ruby-hello-world.git#beta4 ----- - -== Build strategy detection - -If a Jenkins file exists in the root or specified context directory of the source repository when creating a new application, {product-title} generates a pipeline build strategy. Otherwise, it generates a source build strategy. - -Override the build strategy by setting the `--strategy` flag to either `pipeline` or `source`. - -[source,terminal] ----- -$ oc new-app /home/user/code/myapp --strategy=docker ----- - -[NOTE] -==== -The `oc` command requires that files containing build sources are available in a remote Git repository. For all source builds, you must use `git remote -v`. -==== - -== Language detection - -If you use the source build strategy, `new-app` attempts to determine the language builder to use by the presence of certain files in the root or specified context directory of the repository: - -.Languages detected by `new-app` -[cols="4,8",options="header"] -|=== - -|Language |Files -ifdef::openshift-enterprise,openshift-webscale,openshift-dedicated,openshift-aro,openshift-online[] -|`dotnet` -|`project.json`, `pass:[*.csproj]` -endif::[] -|`jee` -|`pom.xml` - -|`nodejs` -|`app.json`, `package.json` - -|`perl` -|`cpanfile`, `index.pl` - -|`php` -|`composer.json`, `index.php` - -|`python` -|`requirements.txt`, `setup.py` - -|`ruby` -|`Gemfile`, `Rakefile`, `config.ru` - -|`scala` -|`build.sbt` - -|`golang` -|`Godeps`, `main.go` -|=== - -After a language is detected, `new-app` searches the {product-title} server for image stream tags that have a `supports` annotation matching the detected language, or an image stream that matches the name of the detected language. If a match is not found, `new-app` searches the link:https://registry.hub.docker.com[Docker Hub registry] for an image that matches the detected language based on name. - -You can override the image the builder uses for a particular source repository by specifying the image, either an image stream or container -specification, and the repository with a `~` as a separator. Note that if this is done, build strategy detection and language detection are not carried out. - -For example, to use the `myproject/my-ruby` imagestream with the source in a remote repository: - -[source,terminal] ----- -$ oc new-app myproject/my-ruby~https://github.com/openshift/ruby-hello-world.git ----- - -To use the `openshift/ruby-20-centos7:latest` container image stream with the source in a local repository: - -[source,terminal] ----- -$ oc new-app openshift/ruby-20-centos7:latest~/home/user/code/my-ruby-app ----- - -[NOTE] -==== -Language detection requires the Git client to be locally installed so that your repository can be cloned and inspected. If Git is not available, you can avoid the language detection step by specifying the builder image to use with your repository with the `~` syntax. - -The `-i ` invocation requires that `new-app` attempt to clone `repository` to determine what type of artifact it is, so this will fail if Git is not available. - -The `-i --code ` invocation requires `new-app` clone `repository` to determine whether `image` should be used as a builder for the source code, or deployed separately, as in the case of a database image. -==== diff --git a/modules/applications-create-using-cli-template.adoc b/modules/applications-create-using-cli-template.adoc deleted file mode 100644 index 1ec4ed185362..000000000000 --- a/modules/applications-create-using-cli-template.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/application_life_cycle_management/creating-applications-using-the-cli.adoc - -[id="applications-create-using-cli-template_{context}"] -= Creating an application from a template - -You can create an application from a previously stored template or from a -template file, by specifying the name of the template as an argument. For -example, you can store a sample application template and use it to create an -application. - -Upload an application template to your current project's template library. The following example uploads an application template from a file called `examples/sample-app/application-template-stibuild.json`: - -[source,terminal] ----- -$ oc create -f examples/sample-app/application-template-stibuild.json ----- - -Then create a new application by referencing the application template. In this example, the template name is `ruby-helloworld-sample`: - -[source,terminal] ----- -$ oc new-app ruby-helloworld-sample ----- - -To create a new application by referencing a template file in your local file system, without first storing it in {product-title}, use the `-f|--file` argument. For example: - -[source,terminal] ----- -$ oc new-app -f examples/sample-app/application-template-stibuild.json ----- - -== Template parameters - -When creating an application based on a template, use the `-p|--param` argument to set parameter values that are defined by the template: - -[source,terminal] ----- -$ oc new-app ruby-helloworld-sample \ - -p ADMIN_USERNAME=admin -p ADMIN_PASSWORD=mypassword ----- - -You can store your parameters in a file, then use that file with `--param-file` when instantiating a template. If you want to read the parameters from standard input, use `--param-file=-`. The following is an example file called `helloworld.params`: - -[source,terminal] ----- -ADMIN_USERNAME=admin -ADMIN_PASSWORD=mypassword ----- - -Reference the parameters in the file when instantiating a template: - -[source,terminal] ----- -$ oc new-app ruby-helloworld-sample --param-file=helloworld.params ----- diff --git a/modules/applying-the-latest-internal-certificates.adoc b/modules/applying-the-latest-internal-certificates.adoc new file mode 100644 index 000000000000..ce57d4d8aa0f --- /dev/null +++ b/modules/applying-the-latest-internal-certificates.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="applying-the-latest-internal-certificates_{context}"] += Applying the latest internal certificates + +By manually restarting the pods of the affected cluster, you can apply the latest certificates and prevent downtime. + +.Prerequisites + +* You have `write` permission for the `Administration` resource. + +.Procedure + +* To manually restart the pods of the affected cluster, run the following command: ++ +[source,terminal] +---- +$ oc -n delete pods --all <1> +---- ++ +-- +<1> The namespace where you installed the secured cluster. For example, `stackrox`. ++ +If you use Kubernetes, use `kubectl` instead of `oc`. +-- \ No newline at end of file diff --git a/modules/architecture-container-application-benefits.adoc b/modules/architecture-container-application-benefits.adoc deleted file mode 100644 index 5328cb429c8a..000000000000 --- a/modules/architecture-container-application-benefits.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture.adoc - -[id="architecture-container-application-benefits_{context}"] -= The benefits of containerized applications - -Using containerized applications offers many advantages over using traditional deployment methods. Where applications were once expected to be installed on operating systems that included all their dependencies, containers let an application carry their dependencies with them. Creating containerized applications offers many benefits. - -[id="operating-system-benefits_{context}"] -== Operating system benefits - -Containers use small, dedicated Linux operating systems without a kernel. Their file system, networking, cgroups, process tables, and namespaces are separate from the host Linux system, but the containers can integrate with the hosts seamlessly when necessary. Being based on Linux allows containers to use all the advantages that come with the open source development model of rapid innovation. - -Because each container uses a dedicated operating system, you can deploy applications that require conflicting software dependencies on the same host. Each container carries its own dependent software and manages its own interfaces, such as networking and file systems, so applications never need to compete for those assets. - -[id="deployment-scaling-benefits_{context}"] -== Deployment and scaling benefits - -If you employ rolling upgrades between major releases of your application, you can continuously improve your applications without downtime and still maintain compatibility with the current release. - -You can also deploy and test a new version of an application alongside the existing version. If the container passes your tests, simply deploy more new containers and remove the old ones.  - -Since all the software dependencies for an application are resolved within the container itself, you can use a standardized operating system on each host in your data center. You do not need to configure a specific operating system for each application host. When your data center needs more capacity, you can deploy another generic host system. - -Similarly, scaling containerized applications is simple. {product-title} offers a simple, standard way of scaling any containerized service. For example, if you build applications as a set of microservices rather than large, monolithic applications, you can scale the individual microservices individually to meet demand. This capability allows you to scale only the required services instead of the entire application, which can allow you to meet application demands while using minimal resources. diff --git a/modules/architecture-kubernetes-introduction.adoc b/modules/architecture-kubernetes-introduction.adoc deleted file mode 100644 index 06756c169c39..000000000000 --- a/modules/architecture-kubernetes-introduction.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture.adoc - -[id="architecture-kubernetes-introduction_{context}"] -= About Kubernetes - -Although container images and the containers that run from them are the -primary building blocks for modern application development, to run them at scale -requires a reliable and flexible distribution system. Kubernetes is the -defacto standard for orchestrating containers. - -Kubernetes is an open source container orchestration engine for automating -deployment, scaling, and management of containerized applications. The general -concept of Kubernetes is fairly simple: - -* Start with one or more worker nodes to run the container workloads. -* Manage the deployment of those workloads from one or more master nodes. -* Wrap containers in a deployment unit called a pod. Using pods provides extra -metadata with the container and offers the ability to group several containers -in a single deployment entity. -* Create special kinds of assets. For example, services are represented by a -set of pods and a policy that defines how they are accessed. This policy -allows containers to connect to the services that they need even if they do not -have the specific IP addresses for the services. Replication controllers are -another special asset that indicates how many pod replicas are required to run -at a time. You can use this capability to automatically scale your application -to adapt to its current demand. - -In only a few years, Kubernetes has seen massive cloud and on-premise adoption. -The open source development model allows many people to extend Kubernetes -by implementing different technologies for components such as networking, -storage, and authentication. diff --git a/modules/architecture-machine-roles.adoc b/modules/architecture-machine-roles.adoc deleted file mode 100644 index 64930e4e8d0b..000000000000 --- a/modules/architecture-machine-roles.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture.adoc -[id="architecture-machine-roles_{context}"] -= Machine roles in {product-title} - -{product-title} assigns hosts different roles. These roles define the function of the machine within the cluster. The cluster contains definitions for the standard master and worker role types. - -[NOTE] -==== -The cluster also contains the definition for the bootstrap role. Because the bootstrap machine is used only during cluster installation, its function is explained in the cluster installation documentation. -==== - -[id="defining-workers_{context}"] -== Cluster workers - -In a Kubernetes cluster, the worker nodes are where the actual workloads requested by Kubernetes users run and are managed. The worker nodes advertise their capacity and the scheduler, which is part of the master services, determines on which nodes to start containers and pods. Important services run on each worker node, including CRI-O, which is the container engine, Kubelet, which is the service that accepts and fulfills requests for running and stopping container workloads, and a service proxy, which manages communication for pods across workers. - -In {product-title}, machine sets control the worker machines. Machines with the worker role drive compute workloads that are governed by a specific machine pool that autoscales them. Because {product-title} has the capacity to support multiple machine types, the worker machines are classed as _compute_ machines. In this release, the terms _worker machine_ and _compute machine_ are used interchangeably because the only default type of compute machine is the worker machine. In future versions of {product-title}, different types of compute machines, such as infrastructure machines, might be used by default. - -[id="defining-masters_{context}"] -== Cluster masters - -In a Kubernetes cluster, the master nodes run services that are required to control the Kubernetes cluster. In {product-title}, the master machines are the control plane. They contain more than just the Kubernetes services for managing the {product-title} cluster. Because all of the machines with the control plane role are master machines, the terms _master_ and _control plane_ are used interchangeably to describe them. Instead of being grouped into a machine set, master machines are defined by a series of standalone machine API resources. Extra controls apply to master machines to prevent you from deleting all master machines and breaking your cluster. - -[NOTE] -==== -Exactly three master nodes must be used for all production deployments. -==== - -Services that fall under the Kubernetes category on the master include the Kubernetes API server, etcd, Kubernetes controller manager, and HAProxy services. - -.Kubernetes services that run on the control plane -[cols="1,2",options="header"] -|=== -|Component |Description -|Kubernetes API server -|The Kubernetes API server validates and configures the data for pods, services, -and replication controllers. It also provides a focal point for the shared state of the cluster. -|etcd -|etcd stores the persistent master state while other components watch etcd for -changes to bring themselves into the specified state. -//etcd can be optionally configured for high availability, typically deployed with 2n+1 peer services. -|Kubernetes controller manager -|The Kubernetes controller manager watches etcd for changes to objects such as -replication, namespace, and service account controller objects, and then uses the -API to enforce the specified state. Several such processes create a cluster with -one active leader at a time. -|=== - -There are also OpenShift services that run on the control plane, which include the OpenShift API server, OpenShift controller manager, and OAuth API server. - -.OpenShift services that run on the control plane -[cols="1,2",options="header"] -|=== -|Component |Description -|OpenShift API server -|The OpenShift API server validates and configures the data for OpenShift resources, such as projects, routes, and templates. - -The OpenShift API server is managed by the OpenShift API Server Operator. -|OpenShift controller manager -|The OpenShift controller manager watches etcd for changes to OpenShift objects, such as project, route, and template controller objects, and then uses the API to enforce the specified state. - -The OpenShift controller manager is managed by the OpenShift Controller Manager Operator. -|OpenShift OAuth API server -|The OpenShift OAuth API server validates and configures the data to authenticate to OpenShift Container Platform, such as users, groups, and OAuth tokens. - -The OpenShift OAuth API server is managed by the Cluster Authentication Operator. -|OpenShift OAuth server -|Users request tokens from the OpenShift OAuth server to authenticate themselves to the API. - -The OpenShift OAuth server is managed by the Cluster Authentication Operator. -|=== - -Some of these services on the master machines run as systemd services, while others run as static pods. - -Systemd services are appropriate for services that you need to always come up on that particular system shortly after it starts. For master machines, those include sshd, which allows remote login. It also includes services such as: - -* The CRI-O container engine (crio), which runs and manages the containers. {product-title} {product-version} uses CRI-O instead of the Docker Container Engine. -* Kubelet (kubelet), which accepts requests for managing containers on the machine from master services. - -CRI-O and Kubelet must run directly on the host as systemd services because they need to be running before you can run other containers. - -The [x-]`installer-*` and [x-]`revision-pruner-*` control plane pods must run with root permissions because they write to the `/etc/kubernetes` directory, which is owned by the root user. These pods are in the following namespaces: - -* `openshift-etcd` -* `openshift-kube-apiserver` -* `openshift-kube-controller-manager` -* `openshift-kube-scheduler` diff --git a/modules/architecture-platform-benefits.adoc b/modules/architecture-platform-benefits.adoc deleted file mode 100644 index ca26489c85a0..000000000000 --- a/modules/architecture-platform-benefits.adoc +++ /dev/null @@ -1,130 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture.adoc - -[id="architecture-platform-benefits_{context}"] -= {product-title} overview - -//// -Red Hat was one of the early contributors of Kubernetes and quickly integrated -it as the centerpiece of its {product-title} product line. Today, Red Hat -continues as one of the largest contributors to Kubernetes across a wide range -of technology areas. -//// - -{product-title} provides enterprise-ready enhancements to Kubernetes, including the following enhancements: - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -* Hybrid cloud deployments. You can deploy {product-title} clusters to variety of public cloud platforms or in your data center. -endif::[] -ifdef::openshift-dedicated[] -* {product-title} clusters are deployed on AWS environments and can be used as part of a hybrid approach for application management. -endif::[] -* Integrated Red Hat technology. Major components in {product-title} come from {op-system-base-full} and related Red Hat technologies. {product-title} benefits from the intense testing and certification initiatives for Red Hat’s enterprise quality software. -* Open source development model. Development is completed in the open, and the source code is available from public software repositories. This open collaboration fosters rapid innovation and development. - -Although Kubernetes excels at managing your applications, it does not specify -or manage platform-level requirements or deployment processes. Powerful and -flexible platform management tools and processes are important benefits that -{product-title} {product-version} offers. The following sections describe some -unique features and benefits of {product-title}. - -[id="architecture-custom-os_{context}"] -== Custom operating system - -{product-title} uses {op-system-first}, a container-oriented operating -system that combines some of the best features and functions of the CoreOS and -Red Hat Atomic Host operating systems. {op-system} is specifically designed for -running containerized applications from {product-title} and works with new tools -to provide fast installation, Operator-based management, and simplified upgrades. - -{op-system} includes: - -* Ignition, which {product-title} uses as a firstboot system configuration for initially bringing up and configuring machines. -* CRI-O, a Kubernetes native container runtime implementation that integrates closely with the operating system to deliver an efficient and optimized Kubernetes experience. CRI-O provides facilities for running, stopping, and restarting containers. It fully replaces the Docker Container Engine, which was used in {product-title} 3. -* Kubelet, the primary node agent for Kubernetes that is responsible for -launching and monitoring containers. - -In {product-title} {product-version}, you must use {op-system} for all control -plane machines, but you can use Red Hat Enterprise Linux (RHEL) as the operating -system for compute machines, which are also known as worker machines. If you choose to use RHEL workers, you -must perform more system maintenance than if you use {op-system} for all of the -cluster machines. - -[id="architecture-platform-management_{context}"] -== Simplified installation and update process - -With {product-title} {product-version}, if you have an account with the right -permissions, you can deploy a production cluster in supported clouds by running -a single command and providing a few values. You can also customize your cloud -installation or install your cluster in your data center if you use a supported -platform. - -For clusters that use {op-system} for all machines, updating, or -upgrading, {product-title} is a simple, highly-automated process. Because -{product-title} completely controls the systems and services that run on each -machine, including the operating system itself, from a central control plane, -upgrades are designed to become automatic events. If your cluster contains -RHEL worker machines, the control plane benefits from the streamlined update -process, but you must perform more tasks to upgrade the RHEL machines. - -[id="architecture-key-features_{context}"] -== Other key features - -Operators are both the fundamental unit of the {product-title} {product-version} -code base and a convenient way to deploy applications and software components -for your applications to use. In {product-title}, Operators serve as the platform foundation and remove the need for manual upgrades of operating systems and control plane applications. {product-title} Operators such as the -Cluster Version Operator and Machine Config Operator allow simplified, -cluster-wide management of those critical components. - -Operator Lifecycle Manager (OLM) and the OperatorHub provide facilities for -storing and distributing Operators to people developing and deploying applications. - -The Red Hat Quay Container Registry is a Quay.io container registry that serves -most of the container images and Operators to {product-title} clusters. -Quay.io is a public registry version of Red Hat Quay that stores millions of images -and tags. - -Other enhancements to Kubernetes in {product-title} include improvements in -software defined networking (SDN), authentication, log aggregation, monitoring, -and routing. {product-title} also offers a comprehensive web console and the -custom OpenShift CLI (`oc`) interface. - - -//// -{product-title} includes the following infrastructure components: - -* OpenShift API server -* Kubernetes API server -* Kubernetes controller manager -* Kubernetes nodes/kubelet -* CRI-O -* {op-system} -* Infrastructure Operators -* Networking (SDN/Router/DNS) -* Storage -* Monitoring -* Telemetry -* Security -* Authorization/Authentication/Oauth -* Logging - -It also offers the following user interfaces: -* Web Console -* OpenShift CLI (`oc`) -* Rest API -//// - - -[id="architecture-overview-image_{context}"] -== {product-title} lifecycle - -The following figure illustrates the basic {product-title} lifecycle: - -* Creating an {product-title} cluster -* Managing the cluster -* Developing and deploying applications -* Scaling up applications - -.High level {product-title} overview -image::product-workflow-overview.png[High-level {product-title} flow] diff --git a/modules/architecture-platform-introduction.adoc b/modules/architecture-platform-introduction.adoc deleted file mode 100644 index 9f71ccf9cbfb..000000000000 --- a/modules/architecture-platform-introduction.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// * architecture/architecture.adoc - -[id="architecture-platform-introduction_{context}"] -= Introduction to {product-title} - -{product-title} is a platform for developing and running containerized -applications. It is designed to allow applications and the data centers -that support them to expand from just a few machines and applications to -thousands of machines that serve millions of clients. - -With its foundation in Kubernetes, {product-title} incorporates the same -technology that serves as the engine for massive telecommunications, streaming -video, gaming, banking, and other applications. Its implementation in open -Red Hat technologies lets you extend your containerized applications beyond a -single cloud to on-premise and multi-cloud environments. - -// The architecture presented here is meant to give you insights into how {product-title} works. It does this by stepping you through the process of installing an {product-title} cluster, managing the cluster, and developing and deploying applications on it. Along the way, this architecture describes: - -// * Major components of {product-title} -// * Ways of exploring different aspects of {product-title} yourself -// * Available frontdoors (and backdoors) to modify the installation and management of your {product-title} cluster -// * Different types of container application types diff --git a/modules/architecture-rhcos-updating-bootloader.adoc b/modules/architecture-rhcos-updating-bootloader.adoc deleted file mode 100644 index 514525f5e4ca..000000000000 --- a/modules/architecture-rhcos-updating-bootloader.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc - -[id="architecture-rhcos-updating-bootloader.adoc_{context}"] -= Updating the bootloader using bootupd - -To update the bootloader by using `bootupd`, you must either install `bootupd` on {op-system} machines manually or provide a machine config with the enabled `systemd` unit. Unlike `grubby` or other bootloader tools, `bootupd` does not manage kernel space configuration such as passing kernel arguments. - -After you have installed `bootupd`, you can manage it remotely from the {product-title} cluster. - -[NOTE] -==== -It is recommended that you use `bootupd` only on bare metal or virtualized hypervisor installations, such as for protection against the BootHole vulnerability. -==== - -.Manual install method -You can manually install `bootupd` by using the `bootctl` command-line tool. - -. Inspect the system status: -+ -[source,terminal] ----- -# bootupctl status ----- -+ -.Example output -[source,terminal] ----- -Component EFI - Installed: grub2-efi-x64-1:2.04-31.fc33.x86_64,shim-x64-15-8.x86_64 - Update: At latest version ----- - -[start=2] -. {op-system} images created without `bootupd` installed on them require an explicit adoption phase. -+ -If the system status is `Adoptable`, perform the adoption: -+ -[source,terminal] ----- -# bootupctl adopt-and-update ----- -+ -.Example output -[source,terminal] ----- -Updated: grub2-efi-x64-1:2.04-31.fc33.x86_64,shim-x64-15-8.x86_64 ----- - -. If an update is available, apply the update so that the changes take effect on the next reboot: -+ -[source,terminal] ----- -# bootupctl update ----- -+ -.Example output -[source,terminal] ----- -Updated: grub2-efi-x64-1:2.04-31.fc33.x86_64,shim-x64-15-8.x86_64 ----- - -.Machine config method -Another way to enable `bootupd` is by providing a machine config. - -* Provide a machine config file with the enabled `systemd` unit, as shown in the following example: -+ -.Example output -[source,yaml] ----- - variant: rhcos - version: 1.1.0 - systemd: - units: - - name: custom-bootupd-auto.service - enabled: true - contents: | - [Unit] - Description=Bootupd automatic update - - [Service] - ExecStart=/usr/bin/bootupctl update - RemainAfterExit=yes - - [Install] - WantedBy=multi-user.target ----- diff --git a/modules/assessing-the-profile-compliance-across-clusters.adoc b/modules/assessing-the-profile-compliance-across-clusters.adoc new file mode 100644 index 000000000000..f454832314d6 --- /dev/null +++ b/modules/assessing-the-profile-compliance-across-clusters.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="assessing-the-profile-compliance-across-clusters_{context}"] += Assessing the profile compliance across clusters + +By viewing the *Coverage* page, you can assess the profile compliance for nodes and platform resources across clusters. + +.Prerequisites + +* You have installed the Compliance Operator version 1.6.0 or later. ++ +For more information about how to install the Compliance Operator, see "Using the Compliance Operator with {product-title}". ++ +[NOTE] +==== +** Currently, the compliance feature and the Compliance Operator evaluate only infrastructure and platform compliance. + +** The compliance feature requires the Compliance Operator to be running and does _not_ support Amazon Elastic Kubernetes Service (EKS). +==== + +* You have created a compliance scan schedule. ++ +For more information about how to create a compliance scan schedule, see "Customizing and automating your compliance scans". + +.Procedure + +* In the {product-title-short} portal, click *Compliance -> OpenShift Coverage*. \ No newline at end of file diff --git a/modules/assign-role-to-user-or-group.adoc b/modules/assign-role-to-user-or-group.adoc new file mode 100644 index 000000000000..b42e1b88cf77 --- /dev/null +++ b/modules/assign-role-to-user-or-group.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="assign-role-to-user-or-group_{context}"] += Assigning a role to a user or a group + +You can use the {product-title-short} portal to assign roles to a user or a group. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. From the list of authentication providers, select the authentication provider. +. Click *Edit minimum role and rules*. +. Under the *Rules* section, click *Add new rule*. +. For *Key*, select one of the values from `userid`, `name`, `email`, or `groups`. The available choices depend on the authentication provider. +. For *Value*, enter the value of the user ID, name, email address, or group based on the key you selected. For example, to assign the `Analyst` role to a user by email, after selecting `email` for the *Key* field, enter the email address of the user. +. Click the *Role* drop-down menu and select the role you want to assign. For example, to assign the `Analyst` role to a user whose email you have entered, select `Analyst`. +. Click *Save*. + +You can repeat these instructions for each user or group and assign different roles. For role aggregation, you can use the same key/value pair with multiple roles. For example, you can create a rule that assigns the `Analyst` role to the user `jsmith@example.com`, and then add another rule to assign the `Vulnerability Report Creator` role to the same user. For more information about roles, see "System roles". diff --git a/modules/auth-allowing-javascript-access-api-server.adoc b/modules/auth-allowing-javascript-access-api-server.adoc deleted file mode 100644 index 73f44eefb715..000000000000 --- a/modules/auth-allowing-javascript-access-api-server.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * security/allowing-javascript-access-api-server.adoc - -[id="auth-allowing-javascript-access-api-server_{context}"] -= Allowing JavaScript-based access to the API server from additional hosts - -The default {product-title} configuration only allows the OpenShift web console to send requests to the API server. - -If you need to access the API server or OAuth server from a JavaScript -application using a different host name, you can configure additional host names -to allow. - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Edit the `APIServer` resource: -+ -[source,terminal] ----- -$ oc edit apiserver.config.openshift.io cluster ----- -+ -. Add the `additionalCORSAllowedOrigins` field under the `spec` section and -specify one or more additional host names: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: APIServer -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: "2019-07-11T17:35:37Z" - generation: 1 - name: cluster - resourceVersion: "907" - selfLink: /apis/config.openshift.io/v1/apiservers/cluster - uid: 4b45a8dd-a402-11e9-91ec-0219944e0696 -spec: - additionalCORSAllowedOrigins: - - (?i)//my\.subdomain\.domain\.com(:|\z) <1> ----- -<1> The host name is specified as a link:https://github.com/google/re2/wiki/Syntax[Golang regular expression] that matches -against CORS headers from HTTP requests against the API server and OAuth server. -+ -[NOTE] -==== -This example uses the following syntax: - -* The `(?i)` makes it case-insensitive. -* The `//` pins to the beginning of the domain and matches the double slash -following `http:` or `https:`. -* The `\.` escapes dots in the domain name. -* The `(:|\z)` matches the end of the domain name `(\z)` or a port separator -`(:)`. -==== - -. Save the file to apply the changes. diff --git a/modules/authentication-api-impersonation.adoc b/modules/authentication-api-impersonation.adoc deleted file mode 100644 index 63e6de2d9f40..000000000000 --- a/modules/authentication-api-impersonation.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-authentication.adoc -// * applications/projects/creating-project-other-user.adoc -// * users_and_roles/impersonating-system-admin.adoc - -[id="authentication-api-impersonation_{context}"] -= API impersonation - -You can configure a request to the {product-title} API to act as though it originated from another user. For more information, see link:https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation[User impersonation] in the Kubernetes documentation. diff --git a/modules/authentication-configmap-create-from-console.adoc b/modules/authentication-configmap-create-from-console.adoc deleted file mode 100644 index 3dc1d46649aa..000000000000 --- a/modules/authentication-configmap-create-from-console.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -//* authentication/configmaps.adoc - -[id="authentication-configmap-create-from-console_{context}"] -= Creating a config map in the {product-title} web console - -You can create a config map in the {product-title} web console. - -.Procedure - -* To create a config map as a cluster administrator: -+ -. In the Administrator perspective, select `Workloads` -> `Config Maps`. -+ -. At the top right side of the page, select *Create Config Map*. -+ -. Enter the contents of your config map. -+ -. Select *Create*. - -* To create a config map as a developer: -+ -. In the Developer perspective, select `Config Maps`. -+ -. At the top right side of the page, select *Create Config Map*. -+ -. Enter the contents of your config map. -+ -. Select *Create*. diff --git a/modules/authentication-configmap-create.adoc b/modules/authentication-configmap-create.adoc deleted file mode 100644 index 69a8adbef090..000000000000 --- a/modules/authentication-configmap-create.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -//* authentication/configmaps.adoc - -[id="authentication-configmap-create_{context}"] -= Creating a config map - -You can use the following command to create a config map from directories, specific files, or literal values. - -.Procedure - -* Create a config map: -+ -[source,terminal] ----- -$ oc create configmap [options] ----- diff --git a/modules/authentication-configmap-creating-from-directories.adoc b/modules/authentication-configmap-creating-from-directories.adoc deleted file mode 100644 index f2dc41de3b95..000000000000 --- a/modules/authentication-configmap-creating-from-directories.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -//* authentication/configmaps.adoc - -[id="authentication-configmap-creating-from-directories_{context}"] -= Creating a config map from a directory - -You can create a config map from a directory. This method allows you to use multiple files within a directory to create a config map. - -.Procedure - -The following example procedure outlines how to create a config map from a directory. - -. Start with a directory with some files that already contain the data with which you want to populate a config map: -+ -[source,terminal] ----- -$ ls example-files ----- -+ -.Example output -[source,terminal] ----- -game.properties -ui.properties ----- -+ -[source,terminal] ----- -$ cat example-files/game.properties ----- -+ -.Example output -[source,terminal] ----- -enemies=aliens -lives=3 -enemies.cheat=true -enemies.cheat.level=noGoodRotten -secret.code.passphrase=UUDDLRLRBABAS -secret.code.allowed=true -secret.code.lives=30 ----- -+ -[source,terminal] ----- -$ cat example-files/ui.properties ----- -+ -.Example output -[source,terminal] ----- -color.good=purple -color.bad=yellow -allow.textmode=true -how.nice.to.look=fairlyNice ----- - -. Create a `ConfigMap` holding the content of each file in this directory by entering the following command: -+ -[source,terminal] ----- -$ oc create configmap game-config \ - --from-file=example-files/ ----- -+ -When the `--from-file` option points to a directory, each file directly in that directory is used to populate a key in the `ConfigMap`, where the name of the key is the file name, and the value of the key is the content of the file. -+ -For example, the previous command creates the following `ConfigMap`: -+ -[source,terminal] ----- -$ oc describe configmaps game-config ----- -+ -.Example output -[source,terminal] ----- -Name: game-config -Namespace: default -Labels: -Annotations: - -Data - -game.properties: 158 bytes -ui.properties: 83 bytes ----- -+ -You can see that the two keys in the map are created from the file names in the directory specified in the command. Because the content of those keys might be large, the output of `oc describe` only shows the names of the keys and their sizes. -+ -. Enter the `oc get` command for the object with the `-o` option to see the values of the keys: -+ -[source,terminal] ----- -$ oc get configmaps game-config -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -data: - game.properties: |- - enemies=aliens - lives=3 - enemies.cheat=true - enemies.cheat.level=noGoodRotten - secret.code.passphrase=UUDDLRLRBABAS - secret.code.allowed=true - secret.code.lives=30 - ui.properties: | - color.good=purple - color.bad=yellow - allow.textmode=true - how.nice.to.look=fairlyNice -kind: ConfigMap -metadata: - creationTimestamp: 2016-02-18T18:34:05Z - name: game-config - namespace: default - resourceVersion: "407"- - selflink: /api/v1/namespaces/default/configmaps/game-config - uid: 30944725-d66e-11e5-8cd0-68f728db1985 ----- diff --git a/modules/authentication-configmap-creating-from-files.adoc b/modules/authentication-configmap-creating-from-files.adoc deleted file mode 100644 index 9271f3f85526..000000000000 --- a/modules/authentication-configmap-creating-from-files.adoc +++ /dev/null @@ -1,104 +0,0 @@ -// Module included in the following assemblies: -// -//* authentication/configmaps.adoc - -[id="authentication-configmap-creating-from-files_{context}"] -= Creating a ConfigMap from a file - -You can create a config map from a file. - -.Procedure - -The following example procedure outlines how to create a config map from a file. - -[NOTE] -==== -If you create a config map from a file, you can include files containing non-UTF8 data that are placed in this field without corrupting the non-UTF8 data. {product-title} detects binary files and transparently encodes the file as `MIME`. On the server, the `MIME` payload is decoded and stored without corrupting the data. -==== - -You can pass the `--from-file` option multiple times to the CLI. The following example yields equivalent results to the creating from directories example. - -. Create a `ConfigMap` specifying a specific file: -+ -[source,terminal] ----- -$ oc create configmap game-config-2 \ - --from-file=example-files/game.properties \ - --from-file=example-files/ui.properties ----- -+ -. Verify the results: -+ -[source,terminal] ----- -$ oc get configmaps game-config-2 -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -data: - game.properties: |- - enemies=aliens - lives=3 - enemies.cheat=true - enemies.cheat.level=noGoodRotten - secret.code.passphrase=UUDDLRLRBABAS - secret.code.allowed=true - secret.code.lives=30 - ui.properties: | - color.good=purple - color.bad=yellow - allow.textmode=true - how.nice.to.look=fairlyNice -kind: ConfigMap -metadata: - creationTimestamp: 2016-02-18T18:52:05Z - name: game-config-2 - namespace: default - resourceVersion: "516" - selflink: /api/v1/namespaces/default/configmaps/game-config-2 - uid: b4952dc3-d670-11e5-8cd0-68f728db1985 ----- - -You can specify the key to set in a `ConfigMap` for content imported from a file. This can be set by passing a `key=value` expression to the `--from-file` option. For example: - -. Create a `ConfigMap` specifying a key-value pair: -+ -[source,terminal] ----- -$ oc create configmap game-config-3 \ - --from-file=game-special-key=example-files/game.properties ----- - -. Verify the results: -+ -[source,terminal] ----- -$ oc get configmaps game-config-3 -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -data: - game-special-key: |- <1> - enemies=aliens - lives=3 - enemies.cheat=true - enemies.cheat.level=noGoodRotten - secret.code.passphrase=UUDDLRLRBABAS - secret.code.allowed=true - secret.code.lives=30 -kind: ConfigMap -metadata: - creationTimestamp: 2016-02-18T18:54:22Z - name: game-config-3 - namespace: default - resourceVersion: "530" - selflink: /api/v1/namespaces/default/configmaps/game-config-3 - uid: 05f8da22-d671-11e5-8cd0-68f728db1985 ----- -<1> This is the key that you set in the preceding step. diff --git a/modules/authentication-configmap-creating-from-literal-values.adoc b/modules/authentication-configmap-creating-from-literal-values.adoc deleted file mode 100644 index bd5b65eed499..000000000000 --- a/modules/authentication-configmap-creating-from-literal-values.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -//* authentication/configmaps.adoc - -[id="authentication-configmap-creating-from-literal-values_{context}"] -= Creating a config map from literal values - -You can supply literal values for a config map. - -.Procedure - -The `--from-literal` option takes a `key=value` syntax that allows literal values to be supplied directly on the command line. - -. Create a `ConfigMap` specifying a literal value: -+ -[source,terminal] ----- -$ oc create configmap special-config \ - --from-literal=special.how=very \ - --from-literal=special.type=charm ----- - -. Verify the results: -+ -[source,terminal] ----- -$ oc get configmaps special-config -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -data: - special.how: very - special.type: charm -kind: ConfigMap -metadata: - creationTimestamp: 2016-02-18T19:14:38Z - name: special-config - namespace: default - resourceVersion: "651" - selflink: /api/v1/namespaces/default/configmaps/special-config - uid: dadce046-d673-11e5-8cd0-68f728db1985 ----- diff --git a/modules/authentication-configmap-overview.adoc b/modules/authentication-configmap-overview.adoc deleted file mode 100644 index 76fc7ba6aa5a..000000000000 --- a/modules/authentication-configmap-overview.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configmaps.adoc - -[id="authentication-configmap-overview_{context}"] -= Understanding ConfigMaps - -Many applications require configuration using some combination of configuration files, command line arguments, and environment variables. In {product-title}, these configuration artifacts are decoupled from image content to keep containerized applications portable. - -The `ConfigMap` object provides mechanisms to inject containers with configuration data while keeping containers agnostic of {product-title}. A config map can be used to store fine-grained information like individual properties or coarse-grained information like entire configuration files or JSON blobs. - -The `ConfigMap` API object holds key-value pairs of configuration data that can be consumed in pods or used to store configuration data for system components such as controllers. For example: - -.`ConfigMap` Object Definition -[source,yaml] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - creationTimestamp: 2016-02-18T19:14:38Z - name: example-config - namespace: default -data: <1> - example.property.1: hello - example.property.2: world - example.property.file: |- - property.1=value-1 - property.2=value-2 - property.3=value-3 -binaryData: - bar: L3Jvb3QvMTAw <2> ----- -<1> Contains the configuration data. -<2> Points to a file that contains non-UTF8 data, for example, a binary Java keystore file. Enter the file data in Base 64. - -[NOTE] -==== -You can use the `binaryData` field when you create a config map from a binary file, such as an image. -==== - -Configuration data can be consumed in pods in a variety of ways. A config map can be used to: - -* Populate environment variable values in containers -* Set command-line arguments in a container -* Populate configuration files in a volume - -Users and system components can store configuration data in a config map. - -A config map is similar to a secret, but designed to more conveniently support working with strings that do not contain sensitive information. - -[discrete] -== Config map restrictions - -*A config map must be created before its contents can be consumed in pods.* - -Controllers can be written to tolerate missing configuration data. Consult individual components configured by using config maps on a case-by-case basis. - -*`ConfigMap` objects reside in a project.* - -They can only be referenced by pods in the same project. - -*The Kubelet only supports the use of a config map for pods it gets from the API server.* - -This includes any pods created by using the CLI, or indirectly from a replication controller. It does not include pods created by using the {product-title} node's `--manifest-url` flag, its `--config` flag, or its REST API because these are not common ways to create pods. diff --git a/modules/authentication-configmaps-use-case-consuming-in-env-vars.adoc b/modules/authentication-configmaps-use-case-consuming-in-env-vars.adoc deleted file mode 100644 index cf80cfe1caa1..000000000000 --- a/modules/authentication-configmaps-use-case-consuming-in-env-vars.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// Module included in the following assemblies: -// -//* authentication/configmaps.adoc - -[id="authentication-configmaps-use-case-consuming-in-env-vars_{context}"] -= Populating environment variables in containers by using config maps - -Config maps can be used to populate individual environment variables in containers or to populate environment variables in containers from all keys that form valid environment variable names. - -As an example, consider the following config map: - -.`ConfigMap` with two environment variables -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: special-config <1> - namespace: default <2> -data: - special.how: very <3> - special.type: charm <3> ----- -<1> Name of the `ConfigMap`. -<2> The project in which the `ConfigMap` resides. Config maps can only be referenced by pods in the same project. -<3> Environment variables to inject. - -.`ConfigMap` with one environment variable -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: env-config <1> - namespace: default -data: - log_level: INFO <2> ----- -<1> Name of the `ConfigMap`. -<2> Environment variable to inject. - -.Procedure - -* You can consume the keys of this `ConfigMap` in a pod using `configMapKeyRef` sections. -+ -.Sample `Pod` specification configured to inject specific environment variables -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-test-pod -spec: - containers: - - name: test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "-c", "env" ] - env: <1> - - name: SPECIAL_LEVEL_KEY <2> - valueFrom: - configMapKeyRef: - name: special-config <3> - key: special.how <4> - - name: SPECIAL_TYPE_KEY - valueFrom: - configMapKeyRef: - name: special-config <3> - key: special.type <4> - optional: true <5> - envFrom: <6> - - configMapRef: - name: env-config <7> - restartPolicy: Never ----- -<1> Stanza to pull the specified environment variables from a `ConfigMap`. -<2> Name of a Pod environment variable that you are injecting a key's value into. -<3> Name of the `ConfigMap` to pull specific environment variables from. -<4> Environment variable to pull from the `ConfigMap`. -<5> Makes the environment variable optional. As optional, the Pod will be started even if the specified `ConfigMap` and keys do not exist. -<6> Stanza to pull all environment variables from a `ConfigMap`. -<7> Name of the `ConfigMap` to pull all environment variables from. -+ -When this Pod is run, the Pod logs will include the following output: -+ ----- -SPECIAL_LEVEL_KEY=very -log_level=INFO ----- - -[NOTE] -==== -`SPECIAL_TYPE_KEY=charm` is not listed in the example output because `optional: true` is set. -==== diff --git a/modules/authentication-configmaps-use-case-consuming-in-volumes.adoc b/modules/authentication-configmaps-use-case-consuming-in-volumes.adoc deleted file mode 100644 index a8e2b4e663bc..000000000000 --- a/modules/authentication-configmaps-use-case-consuming-in-volumes.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -//* authentication/configmaps.adoc - -[id="authentication-configmaps-use-case-consuming-in-volumes_{context}"] -= Injecting content into a volume by using config maps - -You can inject content into a volume by using config maps. - -.Example `ConfigMap` -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: special-config - namespace: default -data: - special.how: very - special.type: charm ----- - -.Procedure - -You have a couple different options for injecting content into a volume by using config maps. - -* The most basic way to inject content into a volume by using a config map is to populate the volume with files where the key is the file name and the content of the file is the value of the key: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-test-pod -spec: - containers: - - name: test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "cat", "/etc/config/special.how" ] - volumeMounts: - - name: config-volume - mountPath: /etc/config - volumes: - - name: config-volume - configMap: - name: special-config <1> - restartPolicy: Never ----- -<1> File containing key. -+ -When this pod is run, the output of the cat command will be: -+ ----- -very ----- - -* You can also control the paths within the volume where `ConfigMap` keys are projected: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-test-pod -spec: - containers: - - name: test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "cat", "/etc/config/path/to/special-key" ] - volumeMounts: - - name: config-volume - mountPath: /etc/config - volumes: - - name: config-volume - configMap: - name: special-config - items: - - key: special.how - path: path/to/special-key <1> - restartPolicy: Never ----- -<1> Path to `ConfigMap` key. -+ -When this pod is run, the output of the cat command will be: -+ ----- -very ----- diff --git a/modules/authentication-configmaps-use-case-setting-command-line-arguments.adoc b/modules/authentication-configmaps-use-case-setting-command-line-arguments.adoc deleted file mode 100644 index 88de8bfd9ca9..000000000000 --- a/modules/authentication-configmaps-use-case-setting-command-line-arguments.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/builds-configmaps.adoc - -[id="builds-configmaps-use-case-setting-command-line-arguments_{context}"] -= Setting command-line arguments for container commands with ConfigMaps - -A ConfigMap can also be used to set the value of the commands or arguments in a container. This is accomplished by using the Kubernetes substitution syntax `$(VAR_NAME)`. Consider the following ConfigMaps: - -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: special-config - namespace: default -data: - special.how: very - special.type: charm ----- - -.Procedure - -* To inject values into a command in a container, you must consume the keys you want to use as environment variables, as in the consuming ConfigMaps in environment variables use case. Then you can refer to them in a container's command using the `$(VAR_NAME)` syntax. -+ -.Sample `Pod` specification configured to inject specific environment variables -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-test-pod -spec: - containers: - - name: test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "-c", "echo $(SPECIAL_LEVEL_KEY) $(SPECIAL_TYPE_KEY)" ] <1> - env: - - name: SPECIAL_LEVEL_KEY - valueFrom: - configMapKeyRef: - name: special-config - key: special.how - - name: SPECIAL_TYPE_KEY - valueFrom: - configMapKeyRef: - name: special-config - key: special.type - restartPolicy: Never ----- -<1> Inject the values into a command in a container using the keys you want to use as environment variables. -+ -When this Pod is run, the output from the echo command run in the test-container container is as follows: -+ ----- -very charm ----- diff --git a/modules/authentication-kubeadmin.adoc b/modules/authentication-kubeadmin.adoc deleted file mode 100644 index eea747aeabeb..000000000000 --- a/modules/authentication-kubeadmin.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assmeblies: -// -// * authentication/removing-kubeadmin.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="understanding-kubeadmin_{context}"] -= The kubeadmin user - -{product-title} creates a cluster administrator, `kubeadmin`, after the -installation process completes. - -This user has the `cluster-admin` role automatically applied and is treated -as the root user for the cluster. The password is dynamically generated -and unique to your {product-title} environment. After installation -completes the password is provided in the installation program's output. -For example: - -[source,terminal] ----- -INFO Install complete! -INFO Run 'export KUBECONFIG=/auth/kubeconfig' to manage the cluster with 'oc', the OpenShift CLI. -INFO The cluster is ready when 'oc login -u kubeadmin -p ' succeeds (wait a few minutes). -INFO Access the OpenShift web-console here: https://console-openshift-console.apps.demo1.openshift4-beta-abcorp.com -INFO Login to the console with user: kubeadmin, password: ----- diff --git a/modules/authentication-prometheus-system-metrics.adoc b/modules/authentication-prometheus-system-metrics.adoc deleted file mode 100644 index e8a10be6a179..000000000000 --- a/modules/authentication-prometheus-system-metrics.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-authentication.adoc - -[id="authentication-prometheus-system-metrics_{context}"] -= Authentication metrics for Prometheus - -{product-title} captures the following Prometheus system metrics during authentication attempts: - -* `openshift_auth_basic_password_count` counts the number of `oc login` user name and password attempts. -* `openshift_auth_basic_password_count_result` counts the number of `oc login` user name and password attempts by result, `success` or `error`. -* `openshift_auth_form_password_count` counts the number of web console login attempts. -* `openshift_auth_form_password_count_result` counts the number of web console login attempts by result, `success` or `error`. -* `openshift_auth_password_total` counts the total number of `oc login` and web console login attempts. diff --git a/modules/authentication-remove-kubeadmin.adoc b/modules/authentication-remove-kubeadmin.adoc deleted file mode 100644 index 3b675719b2f8..000000000000 --- a/modules/authentication-remove-kubeadmin.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-authentication.adoc -// * authentication/understanding-identity-provider.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="removing-kubeadmin_{context}"] -= Removing the kubeadmin user - -After you define an identity provider and create a new `cluster-admin` -user, you can remove the `kubeadmin` to improve cluster security. - -[WARNING] -==== -If you follow this procedure before another user is a `cluster-admin`, -then {product-title} must be reinstalled. It is not possible to undo -this command. -==== - -.Prerequisites - -* You must have configured at least one identity provider. -* You must have added the `cluster-admin` role to a user. -* You must be logged in as an administrator. - -.Procedure - -* Remove the `kubeadmin` secrets: -+ -[source,terminal] ----- -$ oc delete secrets kubeadmin -n kube-system ----- diff --git a/modules/auto-lock-process-baselines-known-limitations.adoc b/modules/auto-lock-process-baselines-known-limitations.adoc new file mode 100644 index 000000000000..9ce34def553b --- /dev/null +++ b/modules/auto-lock-process-baselines-known-limitations.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="auto-lock-process-baselines-known-limitations_{context}"] += Auto-lock process baselines known limitations + +[role="_abstract"] +Central, Central DB, and Sensor consume more CPU and memory resources when process baseline auto-lock is enabled. This can lead to CPU throttling and pods crashing due to running out of memory. + +The following results were obtained from tests with 1,000 deployments in which 5,000 process were spawned every 30 seconds (166.67 processes per second). The test was run with the feature enabled and disabled. Resource usage was compared between the two tests. For the tests the process baseline generation duration was set to three minutes and the rate of process creation did not change after the baseline generation period ended. + +* Sensor used 24 Mb more memory. +* The difference in Sensor memory usage did not appear to increase with time. +* Sensor CPU usage increased by 0.14 CPUs. +* Central used 175 Mb more memory. +* The rate of increase of Central memory usage was 65 Kb per second greater with auto-lock enabled. +* Central CPU usage increased by 0.12 CPUs. +* Central DB used 296 Mb more memory with auto-lock enabled. +* The difference in Central DB memory usage did not appear to increase over time. +* Central DB CPU usage was low and increased by 0.03 CPUs. diff --git a/modules/auto-lock-process-baselines.adoc b/modules/auto-lock-process-baselines.adoc new file mode 100644 index 000000000000..2943721db31a --- /dev/null +++ b/modules/auto-lock-process-baselines.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: PROCEDURE +[id="auto-lock-process-baselines_{context}"] += Configuring auto-lock for process baselines + +[role="_abstract"] +You can configure {product-title-short} to automatically lock process baselines when they leave the observation period. The auto-lock feature must be enabled in both Central and in the secured cluster. + +Note the following guidelines when using this feature: + +* The feature is enabled in Central by default and disabled in the secured clusters by default. Therefore, enabling the feature does not require restarting Central. However, changing the state of the feature in Central does require a restart of Central. +* The feature is only enabled for process baselines for secured clusters where the feature is enabled. +* Disabling the feature after it has been enabled does not unlock process baselines that have been locked by the feature. +* Enabling the feature does not lock process baselines that left the observation period before the feature was enabled. + +.Procedure + +. In the {ocp} web console, go to the {product-title-short} Operator page. +. In the top navigation menu, select *Secured Cluster*. +. Click the instance name, for example, *stackrox-secured-cluster-services*. +. Use one of the following methods to change the setting: +* In the *Form view*, under *Process baselines settings* -> *Auto Lock*, select *Enabled* or *Disabled*. +* Click *YAML* to open the YAML editor and locate the `spec.processBaselines.autoLock` attribute. Change to `Enabled` or `Disabled`. +. Click *Save.* +. To enable or disable the feature in Central, set the `ROX_AUTO_LOCK_PROCESS_BASELINES` environment variable. The default value is `true`. diff --git a/modules/automatic-configuration-image-registry.adoc b/modules/automatic-configuration-image-registry.adoc new file mode 100644 index 000000000000..69ce2f086468 --- /dev/null +++ b/modules/automatic-configuration-image-registry.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: CONCEPT +[id="automatic-configuration-image-registry_{context}"] += Automatic configuration + +[role="_abstract"] +{product-title} includes default integrations with standard registries, such as Docker Hub and others. It can also automatically configure integrations based on artifacts found in the monitored clusters, such as image pull secrets. Usually, you do not need to configure registry integrations manually. + +[IMPORTANT] +==== +* If you use a Google Container Registry (GCR), {product-title} does not create a registry integration automatically. +* If you use {product-title-managed}, automatic configuration is unavailable, and you must manually create registry integrations. +==== + +[id="amazon_ecr_{context}"] += Amazon ECR integrations + +For Amazon ECR integrations, {product-title} automatically generates ECR registry integrations if the following conditions are met: + +* The cloud provider for the cluster is AWS. +* The nodes in your cluster have an Instance Identity and Access Management (IAM) Role association and the Instance Metadata Service is available in the nodes. For example, when using Amazon Elastic Kubernetes Service (EKS) to manage your cluster, this role is known as the EKS Node IAM role. +* The Instance IAM role has IAM policies granting access to the ECR registries from which you are deploying. + +If the listed conditions are met, {product-title} monitors deployments that pull from ECR registries and automatically generates ECR integrations for them. You can edit these integrations after they are automatically generated. diff --git a/modules/automatic-upgrade-failure.adoc b/modules/automatic-upgrade-failure.adoc new file mode 100644 index 000000000000..4c923e899ba2 --- /dev/null +++ b/modules/automatic-upgrade-failure.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * configuration/configure-automatic-upgrades.adoc +:_mod-docs-content-type: CONCEPT +[id="automatic-upgrade-failure_{context}"] += Automatic upgrade failure for manifest-installed secured clusters + +Sometimes, {product-title-short} automatic upgrades might fail to install. +When an upgrade fails, the status message for the secured cluster changes to `Upgrade failed. Retry upgrade`. +To view more information about the failure and understand why the upgrade failed, you can check the secured cluster row in the *Clusters* view. For more information, see "Troubleshooting the cluster upgrader". + +Some common reasons for the failure are: + +* The sensor-upgrader deployment might not have run because of a missing or a non-schedulable image. +* The pre-flight checks may have failed, either because of insufficient RBAC permissions or because the cluster state is not recognizable. +This can happen if you have edited {product-title} service configurations or the `auto-upgrade.stackrox.io/component` label is missing. +* There might be errors in executing the upgrade. If this happens, the upgrade installer automatically attempts to roll back the upgrade. + +[NOTE] +==== +Sometimes, the rollback can also fail. For these cases, view the cluster logs to identify the issue or contact support. For more information, see "Troubleshooting the cluster upgrader". +==== + +After you identify and fix the root cause for the upgrade failure, you can use the *Retry Upgrade* option to upgrade your secured cluster. diff --git a/modules/automatic-upgrade-status.adoc b/modules/automatic-upgrade-status.adoc new file mode 100644 index 000000000000..481cb3f66c4d --- /dev/null +++ b/modules/automatic-upgrade-status.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * configuration/configure-automatic-upgrades.adoc +:_mod-docs-content-type: CONCEPT +[id="automatic-upgrade-status_{context}"] += Automatic upgrade status + +The *Clusters* view lists all clusters and their upgrade statuses. + +[cols="1,3"] +|=== +|Upgrade status |Description + +|Up to date with Central +|The secured cluster is running the same version as Central. + +|Upgrade available +|A new version is available for the Sensor and Collector. + +|Upgrade failed. Retry upgrade. +|The previous automatic upgrade failed. +//TODO: Add link to automatic upgrade failure module + +|Secured cluster version is not managed by {product-title-short}. +|External tools such as Helm or the Operator control the secured cluster version. You can upgrade the secured cluster using external tools. + +|Pre-flight checks complete +|The upgrade is in progress. Before performing automatic upgrade, the upgrade installer runs a pre-flight check. During the pre-flight check, the installer verifies if certain conditions are satisfied and then only starts the upgrade process. + +|Not applicable +|{product-title-short} cannot communicate with the cluster. + +|=== diff --git a/modules/automatically-generated-ca.adoc b/modules/automatically-generated-ca.adoc new file mode 100644 index 000000000000..e02cfdecc41e --- /dev/null +++ b/modules/automatically-generated-ca.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-ocp.adoc +// * installing/installing_other/install-central-other.adoc +:_mod-docs-content-type: CONCEPT +[id="automatically-generated-ca_{context}"] += Retrieving the automatically generated certificate authority + +When installing {product-title-short}, a certificate authority (CA) is automatically generated and stored in a Kubernetes secret on the cluster. If you later change your installation by using Helm, you might need to supply this CA. For example, enabling an {product-title-short} component that was initially disabled at installation time requires that you provide this CA. + +The automatically generated CA is stored in a secret that is usually named similar to `stackrox-generated-_suffix_`, where _suffix_ is a randomly generated string. + +To retrieve the CA and export it to a `generated-values.yaml` file when needed for the `helm upgrade` command, for example, run the following command: + +[source,terminal] +---- +$ kubectl -n get secret stackrox-generated- \ + -o go-template='{{ index .data "generated-values.yaml" }}' | \ + base64 --decode >generated-values.yaml +---- + +[IMPORTANT] +==== +This file might contain sensitive data, so store it in a safe place. +==== + +If you are using the `helm upgrade` command after changing a configuration, you might need to supply this CA. For example, to update your system and enable Scanner V4, you run the following command: + +[source,terminal] +---- +$ helm upgrade -n stackrox stackrox-central-services rhacs/central-services --reuse-values \ + -f \ + --set scannerV4.disable=false +---- \ No newline at end of file diff --git a/modules/availability.adoc b/modules/availability.adoc new file mode 100644 index 000000000000..9dd9a777458a --- /dev/null +++ b/modules/availability.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_mod-docs-content-type: CONCEPT +[id="availability_{context}"] += Availability + +Availability and disaster avoidance are extremely important aspects of any security platform. {rh-rhacscs-first} provides numerous protections against failures at multiple levels. +To account for possible cloud provider failures, Red{nbsp}Hat established multiple availability zones. diff --git a/modules/available-persistent-storage-options.adoc b/modules/available-persistent-storage-options.adoc deleted file mode 100644 index f7a06872fd3b..000000000000 --- a/modules/available-persistent-storage-options.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/optimizing-storage.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="available-persistent-storage-options_{context}"] -= Available persistent storage options - -Understand your persistent storage options so that you can optimize your -{product-title} environment. - -.Available storage options -[cols="1,4,3",options="header"] -|=== -| Storage type | Description | Examples - -|Block -a|* Presented to the operating system (OS) as a block device -* Suitable for applications that need full control of storage and operate at a low level on files -bypassing the file system -* Also referred to as a Storage Area Network (SAN) -* Non-shareable, which means that only one client at a time can mount an endpoint of this type -| AWS EBS and VMware vSphere support dynamic persistent volume (PV) provisioning natively in {product-title}. -// Ceph RBD, OpenStack Cinder, Azure Disk, GCE persistent disk - -|File -a| * Presented to the OS as a file system export to be mounted -* Also referred to as Network Attached Storage (NAS) -* Concurrency, latency, file locking mechanisms, and other capabilities vary widely between protocols, implementations, vendors, and scales. -|RHEL NFS, NetApp NFS ^[1]^, and Vendor NFS -// Azure File, AWS EFS - -| Object -a| * Accessible through a REST API endpoint -* Configurable for use in the {product-title} Registry -* Applications must build their drivers into the application and/or container. -| AWS S3 -// Aliyun OSS, Ceph Object Storage (RADOS Gateway) -// Google Cloud Storage, Azure Blob Storage, OpenStack Swift -|=== -[.small] --- -1. NetApp NFS supports dynamic PV provisioning when using the Trident plug-in. --- - -[IMPORTANT] -==== -Currently, CNS is not supported in {product-title} {product-version}. -==== diff --git a/modules/aws-secure-token-service-eks.adoc b/modules/aws-secure-token-service-eks.adoc new file mode 100644 index 000000000000..cf3db9df29e7 --- /dev/null +++ b/modules/aws-secure-token-service-eks.adoc @@ -0,0 +1,77 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-short-lived-tokens.adoc +:_mod-docs-content-type: PROCEDURE +[id="amazon-secure-token-service-eks_{context}"] += Configuring Elastic Kubernetes Service (EKS) + +[role="_abstract"] +When running {rh-rhacs-first} on EKS, you can configure short-lived tokens through the Amazon Secure Token Service. + +.Procedure +. Run the following command to enable the IAM OpenID Connect (OIDC) provider for your EKS cluster: ++ +[source,terminal] +---- +$ eksctl utils associate-iam-oidc-provider --cluster --approve +---- +. link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html[Create an IAM role] for your EKS cluster. +. Edit the permission policy of the role and grant the permissions required by the integration. For example: ++ +[source,json] +---- +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ecr:BatchCheckLayerAvailability", + "ecr:BatchGetImage", + "ecr:DescribeImages", + "ecr:DescribeRepositories", + "ecr:GetAuthorizationToken", + "ecr:GetDownloadUrlForLayer", + "ecr:ListImages" + ], + "Resource": "arn:aws:iam:::role/" + } + ] +} +---- +. Update the trust relationship for the role that you want to assume: ++ +[source,json] +---- +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": [ + "arn:aws:iam:::role/" <1> + ] + }, + "Action": "sts:AssumeRole" + } + ] +} +---- +<1> The `` should match with the new role that you have created in earlier steps. +. Enter the following command to associate the newly created role with a service account: ++ +[source,terminal] +---- +$ oc -n stackrox annotate sa central eks.amazonaws.com/role-arn=arn:aws:iam::67890:role/ <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +. Enter the following command to restart the Central pod and apply the changes: ++ +[source,terminal] +---- +$ oc -n stackrox delete pod -l "app in (central,sensor)" <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. diff --git a/modules/aws-secure-token-service-openshift.adoc b/modules/aws-secure-token-service-openshift.adoc new file mode 100644 index 000000000000..55b62e5361bb --- /dev/null +++ b/modules/aws-secure-token-service-openshift.adoc @@ -0,0 +1,70 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-short-lived-tokens.adoc +:_mod-docs-content-type: PROCEDURE +[id="amazon-secure-token-service-openshift_{context}"] += Configuring {ocp} + +[role="_abstract"] +When running {rh-rhacs-first} on {ocp}, you can configure short-lived tokens through the Amazon Secure Token Service. + +.Prerequisites +* You must have a public OpenID Connect (OIDC) configuration bucket with the {ocp} service account signer key. To get the OIDC configuration for the {ocp} cluster, Red{nbsp}Hat recommends using the instructions at link:https://docs.openshift.com/container-platform/4.14/authentication/managing_cloud_provider_credentials/cco-short-term-creds.html[Cloud Credential Operator in manual mode for short-term credentials]. +* You must have access to AWS IAM and the permissions to create and change roles. + +.Procedure +. Follow the instructions at link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html[Creating OpenID Connect (OIDC) identity providers] to create web identity of the {ocp} cluster. Use `openshift` as the value for *Audience*. +. link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html[Create an IAM role] for the web identity of the {ocp} cluster. +. Edit the permission policy of the role and grant the permissions required by the integration. For example: ++ +[source,json] +---- +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ecr:BatchCheckLayerAvailability", + "ecr:BatchGetImage", + "ecr:DescribeImages", + "ecr:DescribeRepositories", + "ecr:GetAuthorizationToken", + "ecr:GetDownloadUrlForLayer", + "ecr:ListImages" + ], + "Resource": "arn:aws:iam:::role/" + } + ] +} +---- +. Update the trust relationship for the role that you want to assume: ++ +[source,json] +---- +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + ":aud": "openshift" + } + } + } + ] +} +---- +. Set the following {product-title-short} environment variables on the Central or Sensor deployment: ++ +[source] +---- +AWS_ROLE_ARN= +AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/openshift/serviceaccount/token +---- diff --git a/modules/azure-workload-identity-federation-aks.adoc b/modules/azure-workload-identity-federation-aks.adoc new file mode 100644 index 000000000000..7408ab5abf94 --- /dev/null +++ b/modules/azure-workload-identity-federation-aks.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-short-lived-tokens.adoc +:_mod-docs-content-type: PROCEDURE +[id="azure-workload-identity-federation-gke_{context}"] += Configuring Microsoft Azure Kubernetes Service + +[role="_abstract"] +By running {rh-rhacs-first} on Microsoft Azure Kubernetes Service (AKS), you can configure short-lived tokens by using Microsoft Entra ID managed identities. + +.Prerequisites +* You have access to the cluster and integration resources within Microsoft Azure. + +.Procedure +. Create a trust relationship between the external IdP and a user-assigned managed identity or application in Microsoft Entra ID. ++ +For more information, see link:https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation#how-it-works[Workload identity federation] (Microsoft Azure documentation). +. Annotate the {product-title-short} service account by running the following command: ++ +[source,terminal] +---- +$ oc annotate serviceaccount \//<1> + central \// <2> + --namespace stackrox \ + azure.workload.identity/client-id= <3> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +<2> When setting up the delegated scanning, use *sensor* instead of *central*. +<3> Enter the client ID of the associated identity. ++ +.Example output +[source,terminal] +---- +serviceaccount/central annotated +---- diff --git a/modules/azure-workload-identity-federation-openshift.adoc b/modules/azure-workload-identity-federation-openshift.adoc new file mode 100644 index 000000000000..6500900d5825 --- /dev/null +++ b/modules/azure-workload-identity-federation-openshift.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-short-lived-tokens.adoc +:_mod-docs-content-type: PROCEDURE +[id="azure-workload-identity-federation-openshift_{context}"] += Configuring {ocp} + +[role="_abstract"] +By running {rh-rhacs-first} on {ocp}, you can configure short-lived tokens by using Microsoft Entra ID managed identities. + +.Prerequisites +* You have a public OpenID Connect (OIDC) configuration bucket with the {ocp} service account signer key. ++ +For more information, see link:https://docs.openshift.com/container-platform/{ocp-latest-version}/authentication/managing_cloud_provider_credentials/cco-short-term-creds.html["Manual mode with short-term credentials for components"] in _OpenShift Container Platform_ documentation. +* You have a Microsoft Entra ID user-assigned managed identity. +* You have access to a Microsoft Azure subscription with the permission to assign role assignments. + +.Procedure +* To add the federated identity credentials to a user-assigned managed identity, run the following command, for example: ++ +[source,terminal] +---- +$ az identity federated-credential create \ + --name "${FEDERATED_CREDENTIAL_NAME}" \ + --identity-name "${MANAGED_IDENTITY_NAME}" \// <1> + --resource-group "${RESOURCE_GROUP}" \ + --issuer "${OIDC_ISSUER_URL}" \// <2> + --subject system:serviceaccount:stackrox:central \ <3> + --audience openshift +---- +<1> The managed identity must have all the permissions for federation. +<2> The issuer must match the service account token issuer of the {ocp} cluster. +<3> For delegated scanning, set the subject to *system:serviceaccount:stackrox:sensor*. ++ +For more information about how to configure short-lived tokens by using Microsoft Entra ID managed identities, see link:https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust-user-assigned-managed-identity?pivots=identity-wif-mi-methods-azp[Configure a user-assigned managed identity to trust an external identity provider] (Microsoft Azure documentation). diff --git a/modules/back-up-central-database.adoc b/modules/back-up-central-database.adoc new file mode 100644 index 000000000000..d8328bf1bfc1 --- /dev/null +++ b/modules/back-up-central-database.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="back-up-central-database_{context}"] += Backing up the Central database + +You can back up the Central database and use that backup for rolling back from a failed upgrade or data restoration in the case of an infrastructure disaster. + +.Prerequisites + +* You must have an API token with `read` permission for all resources of {product-title}. The *Analyst* system role has `read` permissions for all resources. +* You have installed the `roxctl` CLI. +* You have configured the `ROX_API_TOKEN` and the `ROX_CENTRAL_ADDRESS` environment variables. + +.Procedure + +* Run the backup command: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central backup +---- diff --git a/modules/backing-up-your-postgresql-database-and-certificates.adoc b/modules/backing-up-your-postgresql-database-and-certificates.adoc new file mode 100644 index 000000000000..c4e8b7cb030b --- /dev/null +++ b/modules/backing-up-your-postgresql-database-and-certificates.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/backing-up-acs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="backing-up-your-postgresql-database-and-certificates_{context}"] += Backing up your PostgreSQL database and certificates + +By backing up your {rh-rhacs-first} instance with an external PostgreSQL database, you can ensure the security and integrity of your data by following a vendor-recommended procedure. In this process, you back up the PostgreSQL database first, and then back up the {product-title-short} certificates. + +.Procedure + +. To back up the PostgreSQL database, run the following command: ++ +[source,terminal] +---- +$ pg_dump -U -d -f +---- ++ +where: + +``:: Specifies the name of the user who has the necessary permissions to perform the dump. +``:: Specifies the actual name of the database. +``:: Specifies the desired location and name for your backup file. + +. To back up the {product-title-short} certificates, run the following command: ++ +[source,terminal] +---- +$ roxctl central backup --certs-only=true +---- diff --git a/modules/backup-and-disaster-recovery.adoc b/modules/backup-and-disaster-recovery.adoc new file mode 100644 index 000000000000..710ad7c84a8e --- /dev/null +++ b/modules/backup-and-disaster-recovery.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_content-type: CONCEPT +[id="backup-disaster-recovery_{context}"] += Backup and disaster recovery + +The {product-title-managed-short} Disaster Recovery strategy includes backups of database and any customization. This also applies to customer data stored in the Central database. Recovery time varies based on the number of appliances and database sizes; however, because the appliances can be clustered and distributed, the RTO can be reduced upfront with proper architecture planning. + +All snapshots are created using the appropriate cloud provider snapshot APIs, encrypted and then uploaded to secure object storage, which for Amazon Web Services (AWS) is an S3 bucket. + +* Red Hat does not commit to a Recovery Point Objective (RPO) or Recovery Time Objective (RTO). For more information, see link:https://www.redhat.com/licenses/Appendix_4_Red_Hat_Online_Services_20221213.pdf[PRODUCT APPENDIX 4 RED HAT ONLINE SERVICES]. + +* Site Reliability Engineering performs backups only as a precautionary measure. They are stored in the same region as the cluster. + +* Customers should deploy multiple availability zone Secured Clusters with workloads that follow Kubernetes best practices to ensure high availability within a region. + +Disaster recovery plans are exercised annually at a minimum. A Business Continuity Management standard and guideline is in place so that the BC lifecycle is consistently followed throughout the organization. This policy includes a requirement for testing at least annually, or with major change of functional plans. Review sessions are required to be conducted after any plan exercise or activation, and plan updates are made as needed. + +Red Hat has generator backup systems. Our IT production systems are hosted in a Tier 3 data center facility that has recurring testing to ensure redundancy is operational. They are audited yearly to validate compliance. \ No newline at end of file diff --git a/modules/backup-considerations-for-external-databases-and-cloud-users.adoc b/modules/backup-considerations-for-external-databases-and-cloud-users.adoc new file mode 100644 index 000000000000..cd26f60ebf62 --- /dev/null +++ b/modules/backup-considerations-for-external-databases-and-cloud-users.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/backing-up-acs.adoc + +:_mod-docs-content-type: CONCEPT +[id="backup-considerations-for-external-databases-and-cloud-users_{context}"] += Backup considerations for external databases and cloud users + +You must manage your backups differently if you use an external database or if you are a cloud user. + +.Back up with an external database + +If you use an external database, you cannot use the automatic backup option or start a backup process from within {rh-rhacs-first}. + +[IMPORTANT] +==== +* When you upgrade your external database, you must scale down Central before you start the backup. Central attempts to connect to the database until it is successful, which can cause issues during the upgrade process. + +* For a database that you manage, you must use the backup procedures that your database vendor recommends. +==== + +.Back up for cloud users + +If you are a cloud user, you cannot use the automatic backup option or start the backup process from an integration. Red{nbsp}Hat is responsible for backing up your data. \ No newline at end of file diff --git a/modules/backup-deployment-config-helm.adoc b/modules/backup-deployment-config-helm.adoc new file mode 100644 index 000000000000..fda0af563753 --- /dev/null +++ b/modules/backup-deployment-config-helm.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/backing-up-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="backup-deployment-config-helm_{context}"] += Backing up deployment using Helm + +[role="_abstract"] +When you use the Helm chart to install {product-title-short}, you store all the custom configuration for your Central deployment within the custom values that you apply to the Helm chart. + +You can back up the custom values and save it in a YAML file. + +.Procedure +* Run the following command to back up custom Helm chart values in a YAML file: ++ +[source,terminal] +---- +$ helm get values --all -n __ __ -o yaml > central-values-backup.yaml +---- diff --git a/modules/backup-deployment-config-operator.adoc b/modules/backup-deployment-config-operator.adoc new file mode 100644 index 000000000000..9b995d80763c --- /dev/null +++ b/modules/backup-deployment-config-operator.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/backing-up-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="backup-deployment-config-operator_{context}"] += Backing up deployment using the {product-title-short} Operator + +[role="_abstract"] +When you use the {product-title-short} Operator to instal {product-title-short}, {ocp} stores all the custom configuration for your Central deployment within the Central custom resource. +You can backup the Central custom resource, the `central-tls` secret, and the administrator password. The `central-tls` secret includes the certificates for authenticating with Secured clusters and signing API tokens. + +.Procedure +. Run the following command to save the Central custom resource in a YAML file: ++ +[source,terminal] +---- +$ oc get central -n __ __ -o yaml > central-cr.yaml +---- +. Run the following command to save `central-tls` in a JSON file: ++ +[source,terminal] +---- +$ oc get secret -n __ central-tls -o json | jq 'del(.metadata.ownerReferences)' > central-tls.json +---- +. Run the following command to the administrator password in a JSON file: ++ +[source,terminal] +---- +$ oc get secret -n __ central-htpasswd -o json | jq 'del(.metadata.ownerReferences)' > central-htpasswd.json +---- diff --git a/modules/backup-etcd.adoc b/modules/backup-etcd.adoc deleted file mode 100644 index d9d099f3e00b..000000000000 --- a/modules/backup-etcd.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * disaster_recovery/backing-up-etcd.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="backing-up-etcd-data_{context}"] -= Backing up etcd data - -Follow these steps to back up etcd data by creating an etcd snapshot and backing up the resources for the static pods. This backup can be saved and used at a later time if you need to restore etcd. - -[IMPORTANT] -==== -Only save a backup from a single master host. Do not take a backup from each master host in the cluster. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have checked whether the cluster-wide proxy is enabled. -+ -[TIP] -==== -You can check whether the proxy is enabled by reviewing the output of `oc get proxy cluster -o yaml`. The proxy is enabled if the `httpProxy`, `httpsProxy`, and `noProxy` fields have values set. -==== - -.Procedure - -. Start a debug session for a master node: -+ -[source,terminal] ----- -$ oc debug node/ ----- - -. Change your root directory to the host: -+ -[source,terminal] ----- -sh-4.2# chroot /host ----- - -. If the cluster-wide proxy is enabled, be sure that you have exported the `NO_PROXY`, `HTTP_PROXY`, and `HTTPS_PROXY` environment variables. - -. Run the `cluster-backup.sh` script and pass in the location to save the backup to. -+ -[source,terminal] ----- -sh-4.4# /usr/local/bin/cluster-backup.sh /home/core/assets/backup ----- -+ -.Example script output -[source,terminal] ----- -1bf371f1b5a483927cd01bb593b0e12cff406eb8d7d0acf4ab079c36a0abd3f7 -etcdctl version: 3.3.18 -API version: 3.3 -found latest kube-apiserver-pod: /etc/kubernetes/static-pod-resources/kube-apiserver-pod-7 -found latest kube-controller-manager-pod: /etc/kubernetes/static-pod-resources/kube-controller-manager-pod-8 -found latest kube-scheduler-pod: /etc/kubernetes/static-pod-resources/kube-scheduler-pod-6 -found latest etcd-pod: /etc/kubernetes/static-pod-resources/etcd-pod-2 -Snapshot saved at /home/core/assets/backup/snapshot_2020-03-18_220218.db -snapshot db and kube resources are successfully saved to /home/core/assets/backup ----- -+ -In this example, two files are created in the `/home/core/assets/backup/` directory on the master host: - -* `snapshot_.db`: This file is the etcd snapshot. -* `static_kuberesources_.tar.gz`: This file contains the resources for the static pods. If etcd encryption is enabled, it also contains the encryption keys for the etcd snapshot. -+ -[NOTE] -==== -If etcd encryption is enabled, it is recommended to store this second file separately from the etcd snapshot for security reasons. However, this file is required to restore from the etcd snapshot. - -Keep in mind that etcd encryption only encrypts values, not keys. This means that resource types, namespaces, and object names are unencrypted. -==== diff --git a/modules/baseline-router-performance.adoc b/modules/baseline-router-performance.adoc deleted file mode 100644 index 966de06a907a..000000000000 --- a/modules/baseline-router-performance.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// * scalability_and_performance/routing-optimization.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="baseline-router-performance_{context}"] -= Baseline Ingress Controller (router) performance - -The {product-title} Ingress Controller, or router, is the Ingress point for all external traffic destined for {product-title} services. - -When evaluating a single HAProxy router performance in terms of HTTP requests handled per second, the performance varies depending on many factors. In particular: - -* HTTP keep-alive/close mode - -* Route type - -* TLS session resumption client support - -* Number of concurrent connections per target route - -* Number of target routes - -* Back end server page size - -* Underlying infrastructure (network/SDN solution, CPU, and so on) - -While performance in your specific environment will vary, Red Hat lab tests on a public cloud instance of size 4 vCPU/16GB RAM. A single HAProxy router handling 100 routes terminated by backends serving 1kB static pages is able to handle the following number of transactions per second. - -In HTTP keep-alive mode scenarios: - -[cols="3",options="header"] -|=== -|*Encryption* |*LoadBalancerService*|*HostNetwork* -|none |21515|29622 -|edge |16743|22913 -|passthrough |36786|53295 -|re-encrypt |21583|25198 -|=== - -In HTTP close (no keep-alive) scenarios: - -[cols="3",options="header"] -|=== -|*Encryption* |*LoadBalancerService*|*HostNetwork* -|none |5719|8273 -|edge |2729|4069 -|passthrough |4121|5344 -|re-encrypt |2320|2941 -|=== - -Default Ingress Controller configuration with `ROUTER_THREADS=4` was used and two different endpoint publishing strategies (LoadBalancerService/HostNetwork) were tested. -TLS session resumption was used for encrypted routes. With HTTP keep-alive, a single HAProxy router is capable of saturating 1 Gbit NIC at page sizes as small as 8 kB. - -When running on bare metal with modern processors, you can expect roughly twice the performance of the public cloud instance above. This overhead is introduced by the virtualization layer in place on public clouds and holds mostly true for private cloud-based virtualization as well. The following table is a guide to how many applications to use behind the router: - -[cols="2,4",options="header"] -|=== -|*Number of applications* |*Application type* -|5-10 |static file/web server or caching proxy -|100-1000 |applications generating dynamic content - -|=== - -In general, HAProxy can support routes for 5 to 1000 applications, depending on -the technology in use. Ingress Controller performance might be limited by the -capabilities and performance of the applications behind it, such as language or -static versus dynamic content. - -Ingress, or router, sharding should be used to serve more routes towards applications and help horizontally scale the routing tier. diff --git a/modules/billing.adoc b/modules/billing.adoc new file mode 100644 index 000000000000..024f35e17b4c --- /dev/null +++ b/modules/billing.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_mod-docs-content-type: CONCEPT +[id="billing_{context}"] += Billing + +Customers can purchase a {product-title-managed-short} subscription on the Amazon Web Services (AWS) marketplace. +The service cost is charged hourly per secured core, or vCPU of a node belonging to a secured cluster. + +.Subscription cost example +==== +If you have established a connection to two secured clusters, each with 5 identical nodes with 8 vCPUs (such as Amazon EC2 m7g.2xlarge), the total number of secured cores is 80 (2 x 5 x 8 = 80). +==== \ No newline at end of file diff --git a/modules/binding-infra-node-workloads-using-taints-tolerations.adoc b/modules/binding-infra-node-workloads-using-taints-tolerations.adoc deleted file mode 100644 index 4570844aa147..000000000000 --- a/modules/binding-infra-node-workloads-using-taints-tolerations.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc - -[id="binding-infra-node-workloads-using-taints-tolerations_{context}"] -= Binding infrastructure node workloads using taints and tolerations - -If you have an infra node that has the `infra` and `worker` roles assigned, you must configure the node so that user workloads are not assigned to it. - -.Prerequisites - -* Configure additional `MachineSet` objects in your {product-title} cluster. - -.Procedure - -. Use the following command to add a taint to the infra node to prevent scheduling user workloads on it: -+ -[source,terminal] ----- -$ oc adm taint nodes : ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm taint nodes node1 node-role.kubernetes.io/infra:NoSchedule ----- -+ -This example places a taint on `node1` that has key `node-role.kubernetes.io/infra` and taint effect `NoSchedule`. Nodes with the `NoSchedule` effect schedule only pods that tolerate the taint, but allow existing pods to remain scheduled on the node. -+ -[NOTE] -==== -If a descheduler is used, pods violating node taints could be evicted from the cluster. -==== - -. Add tolerations for the pod configurations you want to schedule on the infra node, like router, registry, and monitoring workloads. Add the following code to the `Pod` object specification: -+ -[source, yaml] ----- -tolerations: - - effect: NoSchedule <1> - key: node-role.kubernetes.io/infra <2> - operator: Exists <3> ----- -<1> Specify the effect that you added to the node. -<2> Specify the key that you added to the node. -<3> Specify the `Exists` Operator to require a taint with the key `node-role.kubernetes.io/infra` to be present on the node. -+ -This toleration matches the taint created by the `oc adm taint` command. A pod with this toleration can be scheduled onto the infra node. -+ -[NOTE] -==== -Moving pods for an Operator installed via OLM to an infra node is not always possible. The capability to move Operator pods depends on the configuration of each Operator. -==== - -. Schedule the pod to the infra node using a scheduler. See the documentation for _Controlling pod placement onto nodes_ for details. diff --git a/modules/bound-sa-tokens-about.adoc b/modules/bound-sa-tokens-about.adoc deleted file mode 100644 index 33925c73117c..000000000000 --- a/modules/bound-sa-tokens-about.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/bound-service-account-tokens.adoc - -[id="bound-sa-tokens-about_{context}"] -= About bound service account tokens - -You can use bound service account tokens to limit the scope of permissions for a given service account token. These tokens are audience and time-bound. This facilitates the authentication of a service account to an IAM role and the generation of temporary credentials mounted to a pod. You can request bound service account tokens by using volume projection and the TokenRequest API. diff --git a/modules/bound-sa-tokens-configuring.adoc b/modules/bound-sa-tokens-configuring.adoc deleted file mode 100644 index 39b7ecba95f4..000000000000 --- a/modules/bound-sa-tokens-configuring.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/bound-service-account-tokens.adoc - -[id="bound-sa-tokens-configuring_{context}"] -= Configuring bound service account tokens using volume projection - -You can configure pods to request bound service account tokens by using volume projection. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have created a service account. This procedure assumes that the service account is named `build-robot`. - -.Procedure - -. Optionally, set the service account issuer. -+ -This step is typically not required if the bound tokens are used only within the cluster. - -.. Edit the `cluster` `Authentication` object: -+ -[source,terminal] ----- -$ oc edit authentications cluster ----- - -.. Set the `spec.serviceAccountIssuer` field to the desired service account issuer value: -+ -[source,yaml] ----- -spec: - serviceAccountIssuer: https://test.default.svc <1> ----- -<1> This value should be a URL from which the recipient of a bound token can source the public keys necessary to verify the signature of the token. The default is [x-]`https://kubernetes.default.svc`. - -. Configure a pod to use a bound service account token by using volume projection. - -.. Create a file called `pod-projected-svc-token.yaml` with the following contents: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: nginx -spec: - containers: - - image: nginx - name: nginx - volumeMounts: - - mountPath: /var/run/secrets/tokens - name: vault-token - serviceAccountName: build-robot <1> - volumes: - - name: vault-token - projected: - sources: - - serviceAccountToken: - path: vault-token <2> - expirationSeconds: 7200 <3> - audience: vault <4> ----- -<1> A reference to an existing service account. -<2> The path relative to the mount point of the file to project the token into. -<3> Optionally set the expiration of the service account token, in seconds. The default is 3600 seconds (1 hour) and must be at least 600 seconds (10 minutes). The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours. -<4> Optionally set the intended audience of the token. The recipient of a token should verify that the recipient identity matches the audience claim of the token, and should otherwise reject the token. The audience defaults to the identifier of the API server. - -.. Create the pod: -+ -[source,terminal] ----- -$ oc create -f pod-projected-svc-token.yaml ----- -+ -The kubelet requests and stores the token on behalf of the pod, makes the token available to the pod at a configurable file path, and refreshes the token as it approaches expiration. - -. The application that uses the bound token must handle reloading the token when it rotates. -+ -The kubelet rotates the token if it is older than 80 percent of its time to live, or if the token is older than 24 hours. diff --git a/modules/building-memcached-operator-using-osdk.adoc b/modules/building-memcached-operator-using-osdk.adoc deleted file mode 100644 index 64191c506742..000000000000 --- a/modules/building-memcached-operator-using-osdk.adoc +++ /dev/null @@ -1,442 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-getting-started.adoc - -[id="building-memcached-operator-using-osdk_{context}"] -= Building a Go-based Operator using the Operator SDK - -This procedure walks through an example of building a simple Memcached Operator using tools and libraries provided by the SDK. - -.Prerequisites - -- Operator SDK CLI installed on the development workstation -- Operator Lifecycle Manager (OLM) installed on a Kubernetes-based cluster (v1.8 -or above to support the `apps/v1beta2` API group), for example {product-title} {product-version} -- Access to the cluster using an account with `cluster-admin` permissions -- OpenShift CLI (`oc`) v{product-version}+ installed - -.Procedure - -. *Create a new project.* -+ -Use the CLI to create a new `memcached-operator` project: -+ -[source,terminal] ----- -$ mkdir -p $GOPATH/src/github.com/example-inc/ ----- -+ -[source,terminal] ----- -$ cd $GOPATH/src/github.com/example-inc/ ----- -+ -[source,terminal] ----- -$ operator-sdk new memcached-operator ----- -+ -[source,terminal] ----- -$ cd memcached-operator ----- - -. *Add a new custom resource definition (CRD).* - -.. Use the CLI to add a new CRD API called `Memcached`, with `APIVersion` set to `cache.example.com/v1apha1` and `Kind` set to `Memcached`: -+ -[source,terminal] ----- -$ operator-sdk add api \ - --api-version=cache.example.com/v1alpha1 \ - --kind=Memcached ----- -+ -This scaffolds the Memcached resource API under `pkg/apis/cache/v1alpha1/`. - -.. Modify the spec and status of the `Memcached` custom resource (CR) at the `pkg/apis/cache/v1alpha1/memcached_types.go` file: -+ -[source,go] ----- -type MemcachedSpec struct { - // Size is the size of the memcached deployment - Size int32 `json:"size"` -} -type MemcachedStatus struct { - // Nodes are the names of the memcached pods - Nodes []string `json:"nodes"` -} ----- - -.. After modifying the `*_types.go` file, always run the following command to update the generated code for that resource type: -+ -[source,terminal] ----- -$ operator-sdk generate k8s ----- - -. *Optional: Add custom validation to your CRD.* -+ -OpenAPI v3.0 schemas are added to CRD manifests in the `spec.validation` block when the manifests are generated. This validation block allows Kubernetes to validate the properties in a Memcached CR when it is created or updated. -+ -Additionally, a `pkg/apis///zz_generated.openapi.go` file is generated. This file contains the Go representation of this validation block if the `+k8s:openapi-gen=true annotation` is present above the `Kind` type declaration, which is present by default. This auto-generated code is the OpenAPI model of your Go `Kind` type, from which you can create a full OpenAPI Specification and generate a client. -+ -As an Operator author, you can use Kubebuilder markers (annotations) to configure custom validations for your API. These markers must always have a `+kubebuilder:validation` prefix. For example, adding an enum-type specification can be done by adding the following marker: -+ -[source,go] ----- -// +kubebuilder:validation:Enum=Lion;Wolf;Dragon -type Alias string ----- -+ -Usage of markers in API code is discussed in the Kubebuilder link:https://book.kubebuilder.io/reference/generating-crd.html[Generating CRDs] and link:https://book.kubebuilder.io/reference/markers.html[Markers for Config/Code Generation] documentation. A full list of OpenAPIv3 validation markers is also available in the Kubebuilder link:https://book.kubebuilder.io/reference/markers/crd-validation.html[CRD Validation] documentation. -+ -If you add any custom validations, run the following command to update the OpenAPI validation section in the `deploy/crds/cache.example.com_memcacheds_crd.yaml` file for the CRD: -+ -[source,terminal] ----- -$ operator-sdk generate crds ----- -+ -.Example generated YAML -[source,yaml] ----- -spec: - validation: - openAPIV3Schema: - properties: - spec: - properties: - size: - format: int32 - type: integer ----- - -. *Add a new controller.* - -.. Add a new controller to the project to watch and reconcile the `Memcached` resource: -+ -[source,terminal] ----- -$ operator-sdk add controller \ - --api-version=cache.example.com/v1alpha1 \ - --kind=Memcached ----- -+ -This scaffolds a new controller implementation under `pkg/controller/memcached/`. - -.. For this example, replace the generated controller file `pkg/controller/memcached/memcached_controller.go` with the link:https://github.com/operator-framework/operator-sdk/blob/master/example/memcached-operator/memcached_controller.go.tmpl[example implementation]. -+ -The example controller executes the following reconciliation logic for each `Memcached` resource: -+ --- -* Create a Memcached deployment if it does not exist. -* Ensure that the Deployment size is the same as specified by the `Memcached` CR spec. -* Update the `Memcached` resource status with the names of the Memcached pods. --- -+ -The next two sub-steps inspect how the controller watches resources and how the reconcile loop is triggered. You can skip these steps to go directly to building and running the Operator. - -.. Inspect the controller implementation at the `pkg/controller/memcached/memcached_controller.go` file to see how the controller watches resources. -+ -The first watch is for the `Memcached` type as the primary resource. For each add, update, or delete event, the reconcile loop is sent a reconcile `Request` (a `:` key) for that `Memcached` object: -+ -[source,go] ----- -err := c.Watch( - &source.Kind{Type: &cachev1alpha1.Memcached{}}, &handler.EnqueueRequestForObject{}) ----- -+ -The next watch is for `Deployment` objects, but the event handler maps each event to a reconcile `Request` for the owner of the deployment. In this case, this is the `Memcached` object for which the deployment was created. This allows the controller to watch deployments as a secondary resource: -+ -[source,go] ----- -err := c.Watch(&source.Kind{Type: &appsv1.Deployment{}}, &handler.EnqueueRequestForOwner{ - IsController: true, - OwnerType: &cachev1alpha1.Memcached{}, - }) ----- - -.. Every controller has a `Reconciler` object with a `Reconcile()` method that implements the reconcile loop. The reconcile loop is passed the `Request` argument which is a `:` key used to lookup the primary resource object, `Memcached`, from the cache: -+ -[source,go] ----- -func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Result, error) { - // Lookup the Memcached instance for this reconcile request - memcached := &cachev1alpha1.Memcached{} - err := r.client.Get(context.TODO(), request.NamespacedName, memcached) - ... -} ----- -+ -Based on the return value of the `Reconcile()` function, the reconcile `Request` might be requeued, and the loop might be triggered again: -+ -[source,go] ----- -// Reconcile successful - don't requeue -return reconcile.Result{}, nil -// Reconcile failed due to error - requeue -return reconcile.Result{}, err -// Requeue for any reason other than error -return reconcile.Result{Requeue: true}, nil ----- -[id="building-memcached-operator-using-osdk-build-and-run_{context}"] - -. *Build and run the Operator.* - -.. Before running the Operator, the CRD must be registered with the Kubernetes API server: -+ -[source,terminal] ----- -$ oc create \ - -f deploy/crds/cache_v1alpha1_memcached_crd.yaml ----- - -.. After registering the CRD, there are two options for running the Operator: -+ --- -* As a Deployment inside a Kubernetes cluster -* As Go program outside a cluster --- -+ -Choose one of the following methods. - -... _Option A:_ Running as a deployment inside the cluster. - -.... Build the `memcached-operator` image and push it to a registry: -+ -[source,terminal] ----- -$ operator-sdk build quay.io/example/memcached-operator:v0.0.1 ----- - -.... The deployment manifest is generated at `deploy/operator.yaml`. Update the deployment image as follows since the default is just a placeholder: -+ -[source,terminal] ----- -$ sed -i 's|REPLACE_IMAGE|quay.io/example/memcached-operator:v0.0.1|g' deploy/operator.yaml ----- - -.... Ensure you have an account on link:https://quay.io[Quay.io] for the next step, or substitute your preferred container registry. On the registry, link:https://quay.io/new/[create a new public image] repository named `memcached-operator`. - -.... Push the image to the registry: -+ -[source,terminal] ----- -$ podman push quay.io/example/memcached-operator:v0.0.1 ----- - -.... Set up RBAC and create the `memcached-operator` manifests: -+ -[source,terminal] ----- -$ oc create -f deploy/role.yaml ----- -+ -[source,terminal] ----- -$ oc create -f deploy/role_binding.yaml ----- -+ -[source,terminal] ----- -$ oc create -f deploy/service_account.yaml ----- -+ -[source,terminal] ----- -$ oc create -f deploy/operator.yaml ----- - -.... Verify that the `memcached-operator` deploy is up and running: -+ -[source,terminal] ----- -$ oc get deployment ----- -+ -.Example output -[source,terminal] ----- -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -memcached-operator 1 1 1 1 1m ----- - -... _Option B:_ Running locally outside the cluster. -+ -This method is preferred during development cycle to deploy and test faster. -+ -Run the Operator locally with the default Kubernetes configuration file present at `$HOME/.kube/config`: -+ -[source,terminal] ----- -$ operator-sdk run --local --namespace=default ----- -+ -You can use a specific `kubeconfig` using the flag `--kubeconfig=`. - -. *Verify that the Operator can deploy a Memcached application* by creating a `Memcached` CR. - -.. Create the example `Memcached` CR that was generated at `deploy/crds/cache_v1alpha1_memcached_cr.yaml`. - -.. View the file: -+ -[source,terminal] ----- -$ cat deploy/crds/cache_v1alpha1_memcached_cr.yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: "cache.example.com/v1alpha1" -kind: "Memcached" -metadata: - name: "example-memcached" -spec: - size: 3 ----- - -.. Create the object: -+ -[source,terminal] ----- -$ oc apply -f deploy/crds/cache_v1alpha1_memcached_cr.yaml ----- - -.. Ensure that `memcached-operator` creates the deployment for the CR: -+ -[source,terminal] ----- -$ oc get deployment ----- -+ -.Example output -[source,terminal] ----- -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -memcached-operator 1 1 1 1 2m -example-memcached 3 3 3 3 1m ----- - -.. Check the pods and CR to confirm the CR status is updated with the pod names: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -example-memcached-6fd7c98d8-7dqdr 1/1 Running 0 1m -example-memcached-6fd7c98d8-g5k7v 1/1 Running 0 1m -example-memcached-6fd7c98d8-m7vn7 1/1 Running 0 1m -memcached-operator-7cc7cfdf86-vvjqk 1/1 Running 0 2m ----- -+ -[source,terminal] ----- -$ oc get memcached/example-memcached -o yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: cache.example.com/v1alpha1 -kind: Memcached -metadata: - clusterName: "" - creationTimestamp: 2018-03-31T22:51:08Z - generation: 0 - name: example-memcached - namespace: default - resourceVersion: "245453" - selfLink: /apis/cache.example.com/v1alpha1/namespaces/default/memcacheds/example-memcached - uid: 0026cc97-3536-11e8-bd83-0800274106a1 -spec: - size: 3 -status: - nodes: - - example-memcached-6fd7c98d8-7dqdr - - example-memcached-6fd7c98d8-g5k7v - - example-memcached-6fd7c98d8-m7vn7 ----- - -. *Verify that the Operator can manage a deployed Memcached application* by updating the size of the deployment. - -.. Change the `spec.size` field in the `memcached` CR from `3` to `4`: -+ -[source,terminal] ----- -$ cat deploy/crds/cache_v1alpha1_memcached_cr.yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: "cache.example.com/v1alpha1" -kind: "Memcached" -metadata: - name: "example-memcached" -spec: - size: 4 ----- - -.. Apply the change: -+ -[source,terminal] ----- -$ oc apply -f deploy/crds/cache_v1alpha1_memcached_cr.yaml ----- - -.. Confirm that the Operator changes the deployment size: -+ -[source,terminal] ----- -$ oc get deployment ----- -+ -.Example output -[source,terminal] ----- -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -example-memcached 4 4 4 4 5m ----- - -. *Clean up the resources:* -+ -[source,terminal] ----- -$ oc delete -f deploy/crds/cache_v1alpha1_memcached_cr.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/crds/cache_v1alpha1_memcached_crd.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/operator.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/role.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/role_binding.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/service_account.yaml ----- - -.Additional resources - -* For more information about OpenAPI v3.0 validation schemas in CRDs, refer to the link:https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#specifying-a-structural-schema[Kubernetes documentation]. diff --git a/modules/builds-about.adoc b/modules/builds-about.adoc deleted file mode 100644 index 9e4579b666fc..000000000000 --- a/modules/builds-about.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -//*builds/understanding-image-builds - - -[id="builds-about_{context}"] -= Builds - -A build is the process of transforming input parameters into a resulting object. Most often, the process is used to transform input parameters or source code into a runnable image. A `BuildConfig` object is the definition of the entire build process. - -{product-title} uses Kubernetes by creating containers from build images and pushing them to a container image registry. - -Build objects share common characteristics including inputs for a build, the requirement to complete a build process, logging the build process, publishing resources from successful builds, and publishing the final status of the build. Builds take advantage of resource restrictions, specifying limitations on resources such as CPU usage, memory usage, and build or pod execution time. - -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -The {product-title} build system provides extensible support for build strategies that are based on selectable types specified in the build API. There are three primary build strategies available: - -* Docker build -* Source-to-image (S2I) build -* Custom build - -By default, docker builds and S2I builds are supported. -endif::[] - -The resulting object of a build depends on the builder used to create it. For docker and S2I builds, the resulting objects are runnable images. For custom builds, the resulting objects are whatever the builder image author has specified. - -Additionally, the pipeline build strategy can be used to implement sophisticated -workflows: - -* Continuous integration -* Continuous deployment diff --git a/modules/builds-adding-input-secrets-configmaps.adoc b/modules/builds-adding-input-secrets-configmaps.adoc deleted file mode 100644 index b7b5cb23648f..000000000000 --- a/modules/builds-adding-input-secrets-configmaps.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-adding-input-secrets-configmaps_{context}"] -= Adding input secrets and config maps - -In some scenarios, build operations require credentials or other configuration data to access dependent resources, but it is undesirable for that information to be placed in source control. You can define input secrets and input config maps for this purpose. - -.Procedure - -To add an input secret, config maps, or both to an existing `BuildConfig` object: - -. Create the `ConfigMap` object, if it does not exist: -+ -[source,terminal] ----- -$ oc create configmap settings-mvn \ - --from-file=settings.xml= ----- -+ -This creates a new config map named `settings-mvn`, which contains the plain text content of the `settings.xml` file. - -. Create the `Secret` object, if it does not exist: -+ -[source,terminal] ----- -$ oc create secret generic secret-mvn \ - --from-file=id_rsa= ----- -+ -This creates a new secret named `secret-mvn`, which contains the base64 encoded content of the `id_rsa` private key. - -. Add the config map and secret to the `source` section in the existing -`BuildConfig` object: -+ -[source,yaml] ----- -source: - git: - uri: https://github.com/wildfly/quickstart.git - contextDir: helloworld - configMaps: - - configMap: - name: settings-mvn - secrets: - - secret: - name: secret-mvn ----- - -To include the secret and config map in a new `BuildConfig` object, run the following command: - -[source,terminal] ----- -$ oc new-build \ - openshift/wildfly-101-centos7~https://github.com/wildfly/quickstart.git \ - --context-dir helloworld --build-secret “secret-mvn” \ - --build-config-map "settings-mvn" ----- - -During the build, the `settings.xml` and `id_rsa` files are copied into the directory where the source code is located. In {product-title} S2I builder images, this is the image working directory, which is set using the `WORKDIR` instruction in the `Dockerfile`. If you want to specify another directory, add a `destinationDir` to the definition: - -[source,yaml] ----- -source: - git: - uri: https://github.com/wildfly/quickstart.git - contextDir: helloworld - configMaps: - - configMap: - name: settings-mvn - destinationDir: ".m2" - secrets: - - secret: - name: secret-mvn - destinationDir: ".ssh" ----- - -You can also specify the destination directory when creating a new `BuildConfig` object: - -[source,terminal] ----- -$ oc new-build \ - openshift/wildfly-101-centos7~https://github.com/wildfly/quickstart.git \ - --context-dir helloworld --build-secret “secret-mvn:.ssh” \ - --build-config-map "settings-mvn:.m2" ----- - -In both cases, the `settings.xml` file is added to the `./.m2` directory of the build environment, and the `id_rsa` key is added to the `./.ssh` directory. diff --git a/modules/builds-adding-source-clone-secrets.adoc b/modules/builds-adding-source-clone-secrets.adoc deleted file mode 100644 index 8102276ddf00..000000000000 --- a/modules/builds-adding-source-clone-secrets.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/creating-build-inputs.adoc - -[id="builds-adding-source-clone-secrets_{context}"] -= Source Clone Secrets - -Builder pods require access to any Git repositories defined as source for a build. Source clone secrets are used to provide the builder pod with access it would not normally have access to, such as private repositories or repositories with self-signed or untrusted SSL certificates. - -The following source clone secret configurations are supported: - -* .gitconfig File -* Basic Authentication -* SSH Key Authentication -* Trusted Certificate Authorities - -[NOTE] -==== -You can also use combinations of these configurations to meet your specific needs. -==== diff --git a/modules/builds-assigning-builds-to-nodes.adoc b/modules/builds-assigning-builds-to-nodes.adoc deleted file mode 100644 index f56c8de29b5f..000000000000 --- a/modules/builds-assigning-builds-to-nodes.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/advanced-build-operations.adoc - -[id="builds-assigning-builds-to-nodes_{context}"] -= Assigning builds to specific nodes - -Builds can be targeted to run on specific nodes by specifying labels in the `nodeSelector` field of a build configuration. The `nodeSelector` value is a set of key-value pairs that are matched to `Node` labels when scheduling the build pod. - -The `nodeSelector` value can also be controlled by cluster-wide default and override values. Defaults will only be applied if the build configuration does not define any key-value pairs for the `nodeSelector` and also does not define an explicitly empty map value of `nodeSelector:{}`. Override values will replace values in the build configuration on a key by key basis. - -//See Configuring Global Build Defaults and Overrides for more information. - -[NOTE] -==== -If the specified `NodeSelector` cannot be matched to a node with those labels, the build still stay in the `Pending` state indefinitely. -==== - -.Procedure - -* Assign builds to run on specific nodes by assigning labels in the `nodeSelector` field of the `BuildConfig`, for example: -+ -[source,yaml] ----- -apiVersion: "v1" -kind: "BuildConfig" -metadata: - name: "sample-build" -spec: - nodeSelector:<1> - key1: value1 - key2: value2 ----- -<1> Builds associated with this build configuration will run only on nodes with the `key1=value2` and `key2=value2` labels. diff --git a/modules/builds-automatically-add-source-clone-secrets.adoc b/modules/builds-automatically-add-source-clone-secrets.adoc deleted file mode 100644 index 2e09a5feffe3..000000000000 --- a/modules/builds-automatically-add-source-clone-secrets.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-automatically-add-source-clone-secrets_{context}"] -= Automatically adding a source clone secret to a build configuration - -When a `BuildConfig` is created, {product-title} can automatically populate its source clone secret reference. This behavior allows the resulting builds to automatically use the credentials stored in the referenced secret to authenticate to a remote Git repository, without requiring further configuration. - -To use this functionality, a secret containing the Git repository credentials must exist in the namespace in which the `BuildConfig` is later created. This secrets must include one or more annotations prefixed with `build.openshift.io/source-secret-match-uri-`. The value of each of these annotations is a Uniform Resource Identifier (URI) pattern, which is defined as follows. When a `BuildConfig` is created without a source clone secret reference and its Git source URI matches a URI pattern in a secret annotation, {product-title} automatically inserts a reference to that secret in the `BuildConfig`. - -.Prerequisites - -A URI pattern must consist of: - -* A valid scheme: `*://`, `git://`, `http://`, `https://` or `ssh://` -* A host: \*` or a valid hostname or IP address optionally preceded by `*.` -* A path: `/\*` or `/` followed by any characters optionally including `*` characters - -In all of the above, a `*` character is interpreted as a wildcard. - -[IMPORTANT] -==== -URI patterns must match Git source URIs which are conformant to link:https://www.ietf.org/rfc/rfc3986.txt[RFC3986]. Do not include a username (or password) component in a URI pattern. - -For example, if you use `ssh://git@bitbucket.atlassian.com:7999/ATLASSIAN jira.git` for a git repository URL, the source secret must be specified as `pass:c[ssh://bitbucket.atlassian.com:7999/*]` (and not `pass:c[ssh://git@bitbucket.atlassian.com:7999/*]`). - -[source,terminal] ----- -$ oc annotate secret mysecret \ - 'build.openshift.io/source-secret-match-uri-1=ssh://bitbucket.atlassian.com:7999/*' ----- - -==== - -.Procedure - -If multiple secrets match the Git URI of a particular `BuildConfig`, {product-title} selects the secret with the longest match. This allows for basic overriding, as in the following example. - -The following fragment shows two partial source clone secrets, the first matching any server in the domain `mycorp.com` accessed by HTTPS, and the second overriding access to servers `mydev1.mycorp.com` and `mydev2.mycorp.com`: - -[source,yaml] ----- -kind: Secret -apiVersion: v1 -metadata: - name: matches-all-corporate-servers-https-only - annotations: - build.openshift.io/source-secret-match-uri-1: https://*.mycorp.com/* -data: - ... - -kind: Secret -apiVersion: v1 -metadata: - name: override-for-my-dev-servers-https-only - annotations: - build.openshift.io/source-secret-match-uri-1: https://mydev1.mycorp.com/* - build.openshift.io/source-secret-match-uri-2: https://mydev2.mycorp.com/* -data: - ... ----- - -* Add a `build.openshift.io/source-secret-match-uri-` annotation to a pre-existing secret using: -+ -[source,terminal] ----- -$ oc annotate secret mysecret \ - 'build.openshift.io/source-secret-match-uri-1=https://*.mycorp.com/*' ----- diff --git a/modules/builds-basic-access-build-logs.adoc b/modules/builds-basic-access-build-logs.adoc deleted file mode 100644 index 7110b4e08b6e..000000000000 --- a/modules/builds-basic-access-build-logs.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-access-build-logs_{context}"] -= Accessing build logs - -You can access build logs using the web console or the CLI. - -.Procedure - -* To stream the logs using the build directly, enter the following command: -+ -[source,terminal] ----- -$ oc describe build ----- diff --git a/modules/builds-basic-access-build-verbosity.adoc b/modules/builds-basic-access-build-verbosity.adoc deleted file mode 100644 index 14505782dca6..000000000000 --- a/modules/builds-basic-access-build-verbosity.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/basic-build-operations.adoc - -[id="builds-basic-access-build-verbosity_{context}"] -= Enabling log verbosity - -You can enable a more verbose output by passing the `BUILD_LOGLEVEL` environment variable as part of the `sourceStrategy` -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -or `dockerStrategy` -endif::[] -in a `BuildConfig`. - -[NOTE] -==== -An administrator can set the default build verbosity for the entire {product-title} instance by configuring `env/BUILD_LOGLEVEL`. This default can be overridden by specifying `BUILD_LOGLEVEL` in a given `BuildConfig`. You can specify a higher priority override on the command line for non-binary builds by passing `--build-loglevel` to `oc start-build`. -==== - -Available log levels for source builds are as follows: - -[horizontal] -Level 0:: Produces output from containers running the `assemble` script and all encountered errors. This is the default. -Level 1:: Produces basic information about the executed process. -Level 2:: Produces very detailed information about the executed process. -Level 3:: Produces very detailed information about the executed process, and a listing of the archive contents. -Level 4:: Currently produces the same information as level 3. -Level 5:: Produces everything mentioned on previous levels and additionally provides docker push messages. - -.Procedure - -* To enable more verbose output, pass the `BUILD_LOGLEVEL` environment variable as part of the `sourceStrategy` -ifndef::openshift-online[] -or `dockerStrategy` -endif::[] -in a `BuildConfig`: -+ -[source,yaml] ----- -sourceStrategy: -... - env: - - name: "BUILD_LOGLEVEL" - value: "2" <1> ----- -<1> Adjust this value to the desired log level. diff --git a/modules/builds-basic-access-buildconfig-logs.adoc b/modules/builds-basic-access-buildconfig-logs.adoc deleted file mode 100644 index 5f48e5099c7a..000000000000 --- a/modules/builds-basic-access-buildconfig-logs.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-access-buildconfig-logs_{context}"] -= Accessing BuildConfig logs - -You can access `BuildConfig` logs using the web console or the CLI. - -.Procedure - -* To stream the logs of the latest build for a `BuildConfig`, enter the following command: -+ -[source,terminal] ----- -$ oc logs -f bc/ ----- diff --git a/modules/builds-basic-access-buildconfig-version-logs.adoc b/modules/builds-basic-access-buildconfig-version-logs.adoc deleted file mode 100644 index 41e6bba030fc..000000000000 --- a/modules/builds-basic-access-buildconfig-version-logs.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-access-buildconfig-version-logs_{context}"] -= Accessing BuildConfig logs for a given version build - -You can access logs for a given version build for a `BuildConfig` using the web console or the CLI. - -.Procedure - -* To stream the logs for a given version build for a `BuildConfig`, enter the following command: -+ -[source,terminal] ----- -$ oc logs --version= bc/ ----- diff --git a/modules/builds-basic-cancel-all-state.adoc b/modules/builds-basic-cancel-all-state.adoc deleted file mode 100644 index 90d63b8dc473..000000000000 --- a/modules/builds-basic-cancel-all-state.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-cancel-all-state_{context}"] -= Canceling all builds in a given state - -You can cancel all builds in a given state, such as `new` or `pending`, while ignoring the builds in other states. - -.Procedure - -* To cancel all in a given state, enter the following command: -+ -[source,terminal] ----- -$ oc cancel-build bc/ ----- diff --git a/modules/builds-basic-cancel-all.adoc b/modules/builds-basic-cancel-all.adoc deleted file mode 100644 index 36c8a6c5ad39..000000000000 --- a/modules/builds-basic-cancel-all.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-cancel-all_{context}"] -= Canceling all builds - -You can cancel all builds from the build configuration with the following CLI command. - -.Procedure - -* To cancel all builds, enter the following command: -+ -[source,terminal] ----- -$ oc cancel-build bc/ ----- diff --git a/modules/builds-basic-cancel-build.adoc b/modules/builds-basic-cancel-build.adoc deleted file mode 100644 index e7b78282029c..000000000000 --- a/modules/builds-basic-cancel-build.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-cancel-build_{context}"] -= Canceling a build - -You can cancel a build using the web console, or with the following CLI command. - -.Procedure - -* To manually cancel a build, enter the following command: -+ -[source,terminal] ----- -$ oc cancel-build ----- diff --git a/modules/builds-basic-cancel-multiple.adoc b/modules/builds-basic-cancel-multiple.adoc deleted file mode 100644 index d69d331b050d..000000000000 --- a/modules/builds-basic-cancel-multiple.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-cancel-multiple_{context}"] -= Canceling multiple builds - -You can cancel multiple builds with the following CLI command. - -.Procedure - -* To manually cancel multiple builds, enter the following command: -+ -[source,terminal] ----- -$ oc cancel-build ----- diff --git a/modules/builds-basic-delete-buildconfig.adoc b/modules/builds-basic-delete-buildconfig.adoc deleted file mode 100644 index 3e9db28f56c7..000000000000 --- a/modules/builds-basic-delete-buildconfig.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-delete-buildconfig_{context}"] -= Deleting a BuildConfig - -You can delete a `BuildConfig` using the following command. - -.Procedure - -* To delete a `BuildConfig`, enter the following command: -+ -[source,terminal] ----- -$ oc delete bc ----- -+ -This also deletes all builds that were instantiated from this `BuildConfig`. - -* To delete a `BuildConfig` and keep the builds instatiated from the `BuildConfig`, specify the `--cascade=false` flag when you enter the following command: -+ -[source,terminal] ----- -$ oc delete --cascade=false bc ----- diff --git a/modules/builds-basic-start-build.adoc b/modules/builds-basic-start-build.adoc deleted file mode 100644 index 5742ce21636b..000000000000 --- a/modules/builds-basic-start-build.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-start-build_{context}"] -= Starting a build - -You can manually start a new build from an existing build configuration in your current project. - -.Procedure - -To manually start a build, enter the following command: - -[source,terminal] ----- -$ oc start-build ----- diff --git a/modules/builds-basic-start-environment-variable.adoc b/modules/builds-basic-start-environment-variable.adoc deleted file mode 100644 index f134b61e6fd6..000000000000 --- a/modules/builds-basic-start-environment-variable.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-start-environment-variable_{context}"] -= Setting environment variables when starting a build - -You can specify the `--env` flag to set any desired environment variable for the build. - -.Procedure - -* To specify a desired environment variable, enter the following command: -+ -[source,terminal] ----- -$ oc start-build --env== ----- diff --git a/modules/builds-basic-start-logs.adoc b/modules/builds-basic-start-logs.adoc deleted file mode 100644 index 1d1b8f878f4d..000000000000 --- a/modules/builds-basic-start-logs.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-start-logs_{context}"] -= Streaming build logs - -You can specify the `--follow` flag to stream the build's logs in `stdout`. - -.Procedure - -* To manually stream a build's logs in `stdout`, enter the following command: -+ -[source,terminal] ----- -$ oc start-build --follow ----- diff --git a/modules/builds-basic-start-re-run.adoc b/modules/builds-basic-start-re-run.adoc deleted file mode 100644 index b9fb0543e226..000000000000 --- a/modules/builds-basic-start-re-run.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-start-re-run_{context}"] -= Re-running a build - -You can manually re-run a build using the `--from-build` flag. - -.Procedure - -* To manually re-run a build, enter the following command: -+ -[source,terminal] ----- -$ oc start-build --from-build= ----- diff --git a/modules/builds-basic-start-source.adoc b/modules/builds-basic-start-source.adoc deleted file mode 100644 index cfcc03df2a2a..000000000000 --- a/modules/builds-basic-start-source.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-start-source_{context}"] -= Starting a build with source - -Rather than relying on a Git source pull -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -or a Dockerfile -endif::[] -for a build, you can also start a build by directly pushing your source, which could be the contents of a Git or SVN working directory, a set of pre-built binary artifacts you want to deploy, or a single file. This can be done by specifying one of the following options for the `start-build` command: - -[cols="1,2",options="header"] -|=== -|Option |Description - -|`--from-dir=` -|Specifies a directory that will be archived and used as a binary input for the build. - -|`--from-file=` -|Specifies a single file that will be the only file in the build source. The file is placed in the root of an empty directory with the same file name as the original file provided. - -|`--from-repo=` -|Specifies a path to a local repository to use as the binary input for a build. Add the `--commit` option to control which branch, tag, or commit is used for the build. -|=== - -When passing any of these options directly to the build, the contents are streamed to the build and override the current build source settings. - -[NOTE] -==== -Builds triggered from binary input will not preserve the source on the server, so rebuilds triggered by base image changes will use the source specified in the build configuration. -==== - -.Procedure - -* Start a build from a source using the following command to send the contents of a local Git repository as an archive from the tag `v2`: -+ -[source,terminal] ----- -$ oc start-build hello-world --from-repo=../hello-world --commit=v2 ----- diff --git a/modules/builds-basic-view-build-details.adoc b/modules/builds-basic-view-build-details.adoc deleted file mode 100644 index 8fcecaeaa46f..000000000000 --- a/modules/builds-basic-view-build-details.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// * builds/basic-build-operations.adoc - -[id="builds-basic-view-build-details_{context}"] -= Viewing build details - -You can view build details with the web console or by using the `oc describe` CLI command. - -This displays information including: - -* The build source. -* The build strategy. -* The output destination. -* Digest of the image in the destination registry. -* How the build was created. - -If the build uses the -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -`Docker` or -endif::[] -`Source` strategy, the `oc describe` output also includes information about the source revision used for the build, including the commit ID, author, committer, and message. - -.Procedure - -* To view build details, enter the following command: -+ -[source,terminal] ----- -$ oc describe build ----- diff --git a/modules/builds-binary-source.adoc b/modules/builds-binary-source.adoc deleted file mode 100644 index 25af1615c63b..000000000000 --- a/modules/builds-binary-source.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-binary-source_{context}"] -= Binary (local) source - -Streaming content from a local file system to the builder is called a `Binary` type build. The corresponding value of `BuildConfig.spec.source.type` is `Binary` for these builds. - -This source type is unique in that it is leveraged solely based on your use of the `oc start-build`. - -[NOTE] -==== -Binary type builds require content to be streamed from the local file system, so automatically triggering a binary type build, like an image change trigger, is not possible. This is because the binary files cannot be provided. Similarly, you cannot launch binary type builds from the web console. -==== - -To utilize binary builds, invoke `oc start-build` with one of these options: - -* `--from-file`: The contents of the file you specify are sent as a binary stream to the builder. You can also specify a URL to a file. Then, the builder stores the data in a file with the same name at the top of the build context. - -* `--from-dir` and `--from-repo`: The contents are archived and sent as a binary stream to the builder. Then, the builder extracts the contents of the archive within the build context directory. With `--from-dir`, you can also specify a URL to an archive, which is extracted. - -* `--from-archive`: The archive you specify is sent to the builder, where it is extracted within the build context directory. This option behaves the same as `--from-dir`; an archive is created on your host first, whenever the argument to these options is a directory. - -In each of the previously listed cases: - -* If your `BuildConfig` already has a `Binary` source type defined, it is effectively ignored and replaced by what the client sends. - -* If your `BuildConfig` has a `Git` source type defined, it is dynamically disabled, since `Binary` and `Git` are mutually exclusive, and the data in the binary stream provided to the builder takes precedence. - -Instead of a file name, you can pass a URL with HTTP or HTTPS schema to `--from-file` and `--from-archive`. When using `--from-file` with a URL, the name of the file in the builder image is determined by the `Content-Disposition` header sent by the web server, or the last component of the URL path if the header is not present. No form of authentication is supported and it is not possible to use custom TLS certificate or disable certificate validation. - -When using `oc new-build --binary=true`, the command ensures that the restrictions associated with binary builds are enforced. The resulting `BuildConfig` has a source type of `Binary`, meaning that the only valid way to run a build for this `BuildConfig` is to use `oc start-build` with one of the `--from` options to provide the requisite binary data. - -ifndef::openshift-online[] -The Dockerfile and `contextDir` source options have special meaning with binary builds. - -Dockerfile can be used with any binary build source. If Dockerfile is used and the binary stream is an archive, its contents serve as a replacement Dockerfile to any Dockerfile in the archive. If Dockerfile is used with the `--from-file` argument, and the file argument is named Dockerfile, the value from Dockerfile replaces the value from the binary stream. -endif::[] - -In the case of the binary stream encapsulating extracted archive content, the value of the `contextDir` field is interpreted as a subdirectory within the archive, and, if valid, the builder changes into that subdirectory before executing the build. diff --git a/modules/builds-build-custom-builder-image.adoc b/modules/builds-build-custom-builder-image.adoc deleted file mode 100644 index 1c08cf3aea19..000000000000 --- a/modules/builds-build-custom-builder-image.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/custom-builds-buildah.adoc - - -[id="builds-build-custom-builder-image_{context}"] -= Build custom builder image - -You can use {product-title} to build and push custom builder images to use in a custom strategy. - -.Prerequisites - -* Define all the inputs that will go into creating your new custom builder image. - -.Procedure - -. Define a `BuildConfig` object that will build your custom builder image: -+ -[source,terminal] ----- -$ oc new-build --binary --strategy=docker --name custom-builder-image ----- - -. From the directory in which you created your custom build image, run the build: -+ -[source,terminal] ----- -$ oc start-build custom-builder-image --from-dir . -F ----- -+ -After the build completes, your new custom builder image is available in your project in an image stream tag that is named `custom-builder-image:latest`. diff --git a/modules/builds-build-environment.adoc b/modules/builds-build-environment.adoc deleted file mode 100644 index 9477f016a7c4..000000000000 --- a/modules/builds-build-environment.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-build-environment_{context}"] -= Build environments - -As with pod environment variables, build environment variables can be defined in terms of references to other resources or variables using the Downward API. There are some exceptions, which are noted. - -You can also manage environment variables defined in the `BuildConfig` with the `oc set env` command. - -[NOTE] -==== -Referencing container resources using `valueFrom` in build environment variables is not supported as the references are resolved before the container is created. -==== diff --git a/modules/builds-build-hooks.adoc b/modules/builds-build-hooks.adoc deleted file mode 100644 index f2aa289b7be6..000000000000 --- a/modules/builds-build-hooks.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-build-hooks_{context}"] -= Build hooks - -Build hooks allow behavior to be injected into the build process. - -The `postCommit` field of a `BuildConfig` object runs commands inside a temporary container that is running the build output image. The hook is run immediately after the last layer of the image has been committed and before the image is pushed to a registry. - -The current working directory is set to the image's `WORKDIR`, which is the default working directory of the container image. For most images, this is where the source code is located. - -The hook fails if the script or command returns a non-zero exit code or if starting the temporary container fails. When the hook fails it marks the build as failed and the image is not pushed to a registry. The reason for failing can be inspected by looking at the build logs. - -Build hooks can be used to run unit tests to verify the image before the build is marked complete and the image is made available in a registry. If all tests pass and the test runner returns with exit code `0`, the build is marked successful. In case of any test failure, the build is marked as failed. In all cases, the build log contains the output of the test runner, which can be used to identify failed tests. - -The `postCommit` hook is not only limited to running tests, but can be used for other commands as well. Since it runs in a temporary container, changes made by the hook do not persist, meaning that running the hook cannot affect the final image. This behavior allows for, among other uses, the installation and usage of test dependencies that are automatically discarded and are not present in the final image. diff --git a/modules/builds-build-pruning.adoc b/modules/builds-build-pruning.adoc deleted file mode 100644 index d77adffb6dfa..000000000000 --- a/modules/builds-build-pruning.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/advanced-build-operations.adoc - -[id="builds-build-pruning_{context}"] -= Pruning builds - -By default, builds that have completed their lifecycle are persisted indefinitely. You can limit the number of previous builds that are retained. - -.Procedure - -. Limit the number of previous builds that are retained by supplying a positive integer value for `successfulBuildsHistoryLimit` or `failedBuildsHistoryLimit` in your `BuildConfig`, for example: -+ -[source,yaml] ----- -apiVersion: "v1" -kind: "BuildConfig" -metadata: - name: "sample-build" -spec: - successfulBuildsHistoryLimit: 2 <1> - failedBuildsHistoryLimit: 2 <2> ----- -<1> `successfulBuildsHistoryLimit` will retain up to two builds with a status of `completed`. -<2> `failedBuildsHistoryLimit` will retain up to two builds with a status of `failed`, `canceled`, or `error`. - -. Trigger build pruning by one of the following actions: -+ -* Updating a build configuration. -* Waiting for a build to complete its lifecycle. - -Builds are sorted by their creation timestamp with the oldest builds being pruned first. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[NOTE] -==== -Administrators can manually prune builds using the 'oc adm' object pruning command. -==== -endif::[] diff --git a/modules/builds-build-run-policy.adoc b/modules/builds-build-run-policy.adoc deleted file mode 100644 index 216ce745586b..000000000000 --- a/modules/builds-build-run-policy.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/advanced-build-operations.adoc - -[id="builds-build-run-policy_{context}"] -= Build run policy - -The build run policy describes the order in which the builds created from the build configuration should run. This can be done by changing the value of the `runPolicy` field in the `spec` section of the `Build` specification. - -It is also possible to change the `runPolicy` value for existing build configurations, by: - -* Changing `Parallel` to `Serial` or `SerialLatestOnly` and triggering a new build from this configuration causes the new build to wait until all parallel builds complete as the serial build can only run alone. -* Changing `Serial` to `SerialLatestOnly` and triggering a new build causes cancellation of all existing builds in queue, except the currently running build and the most recently created build. The newest build runs next. diff --git a/modules/builds-buildconfig.adoc b/modules/builds-buildconfig.adoc deleted file mode 100644 index 53647a2db39f..000000000000 --- a/modules/builds-buildconfig.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// * builds/understanding-builds.adoc - -[id="builds-buildconfig_{context}"] -= BuildConfigs - -A build configuration describes a single build definition and a set of triggers for when a new build is created. Build configurations are defined by a `BuildConfig`, which is a REST object that can be used in a POST to the API server to create a new instance. - -A build configuration, or `BuildConfig`, is characterized by a build strategy -and one or more sources. The strategy determines the process, while the sources provide its input. - -Depending on how you choose to create your application using {product-title}, a `BuildConfig` is typically generated automatically for you if you use the web console or CLI, and it can be edited at any time. Understanding the parts that make up a `BuildConfig` and their available options can help if you choose to manually change your configuration later. - -The following example `BuildConfig` results in a new build every time a container image tag or the source code changes: - -.`BuildConfig` object definition -[source,yaml] ----- -kind: BuildConfig -apiVersion: build.openshift.io/v1 -metadata: - name: "ruby-sample-build" <1> -spec: - runPolicy: "Serial" <2> - triggers: <3> - - - type: "GitHub" - github: - secret: "secret101" - - type: "Generic" - generic: - secret: "secret101" - - - type: "ImageChange" - source: <4> - git: - uri: "https://github.com/openshift/ruby-hello-world" - strategy: <5> - sourceStrategy: - from: - kind: "ImageStreamTag" - name: "ruby-20-centos7:latest" - output: <6> - to: - kind: "ImageStreamTag" - name: "origin-ruby-sample:latest" - postCommit: <7> - script: "bundle exec rake test" ----- -<1> This specification creates a new `BuildConfig` named `ruby-sample-build`. -<2> The `runPolicy` field controls whether builds created from this build configuration can be run simultaneously. The default value is `Serial`, which means new builds run sequentially, not simultaneously. -<3> You can specify a list of triggers, which cause a new build to be created. -<4> The `source` section defines the source of the build. The source type determines the primary source of input, and can be either `Git`, to point to a code repository location, -ifndef::openshift-online[] -`Dockerfile`, to build from an inline Dockerfile, -endif::[] -or `Binary`, to accept binary payloads. It is possible to have multiple sources at once. Refer to the documentation for each source type for details. -<5> The `strategy` section describes the build strategy used to execute the build. You can specify a `Source` -ifndef::openshift-online[] -, `Docker`, or `Custom` -endif::[] -strategy here. This example uses the `ruby-20-centos7` container image that Source-to-image (S2I) uses for the application build. -<6> After the container image is successfully built, it is pushed into the repository described in the `output` section. -<7> The `postCommit` section defines an optional build hook. diff --git a/modules/builds-chaining-builds.adoc b/modules/builds-chaining-builds.adoc deleted file mode 100644 index 0248633ad02d..000000000000 --- a/modules/builds-chaining-builds.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/advanced-build-operations.adoc - -[id="builds-chaining-builds_{context}"] -= Chained builds - -For compiled languages such as Go, C, C++, and Java, including the dependencies necessary for compilation in the application image might increase the size of the image or introduce vulnerabilities that can be exploited. - -To avoid these problems, two builds can be chained together. One build that produces the compiled artifact, and a second build that places that artifact in a separate image that runs the artifact. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -In the following example, a source-to-image (S2I) build is combined with a docker build to compile an artifact that is then placed in a separate runtime image. - -[NOTE] -==== -Although this example chains a S2I build and a docker build, the first build can use any strategy that produces an image containing the desired artifacts, and the second build can use any strategy that can consume input content from an image. -==== - -//image::chained-build.png[Chained Build] *Needs update* - -The first build takes the application source and produces an image containing a `WAR` file. The image is pushed to the `artifact-image` image stream. The path of the output artifact depends on the `assemble` script of the S2I builder used. In this case, it is output to `/wildfly/standalone/deployments/ROOT.war`. - -[source,yaml] ----- -apiVersion: v1 -kind: BuildConfig -metadata: - name: artifact-build -spec: - output: - to: - kind: ImageStreamTag - name: artifact-image:latest - source: - git: - uri: https://github.com/openshift/openshift-jee-sample.git - strategy: - sourceStrategy: - from: - kind: ImageStreamTag - name: wildfly:10.1 - namespace: openshift ----- - -The second build uses image source with a path to the WAR file inside the output image from the first build. An inline `dockerfile` copies that `WAR` file into a runtime image. - -[source,yaml] ----- -apiVersion: v1 -kind: BuildConfig -metadata: - name: image-build -spec: - output: - to: - kind: ImageStreamTag - name: image-build:latest - source: - dockerfile: |- - FROM jee-runtime:latest - COPY ROOT.war /deployments/ROOT.war - images: - - from: <1> - kind: ImageStreamTag - name: artifact-image:latest - paths: <2> - - sourcePath: /wildfly/standalone/deployments/ROOT.war - destinationDir: "." - strategy: - dockerStrategy: - from: <3> - kind: ImageStreamTag - name: jee-runtime:latest - triggers: - - imageChange: {} - type: ImageChange ----- -<1> `from` specifies that the docker build should include the output of the image from the `artifact-image` image stream, which was the target of the previous build. -<2> `paths` specifies which paths from the target image to include in the current docker build. -<3> The runtime image is used as the source image for the docker build. - -The result of this setup is that the output image of the second build does not have to contain any of the build tools that are needed to create the `WAR` file. Also, because the second build contains an image change trigger, whenever the first build is run and produces a new image with the binary artifact, the second build is automatically triggered to produce a runtime image that contains that artifact. Therefore, both builds behave as a single build with two stages. -endif::[] diff --git a/modules/builds-configuration-change-triggers.adoc b/modules/builds-configuration-change-triggers.adoc deleted file mode 100644 index d9c548c19d66..000000000000 --- a/modules/builds-configuration-change-triggers.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-configuration-change-triggers_{context}"] -= Configuration change triggers - -A configuration change trigger allows a build to be automatically invoked as soon as a new `BuildConfig` is created. - -The following is an example trigger definition YAML within the `BuildConfig`: - -[source,yaml] ----- - type: "ConfigChange" ----- - -[NOTE] -==== -Configuration change triggers currently only work when creating a new `BuildConfig`. In a future release, configuration change triggers will also be able to launch a build whenever a `BuildConfig` is updated. -==== diff --git a/modules/builds-configuration-file.adoc b/modules/builds-configuration-file.adoc deleted file mode 100644 index d0e19d8a0da3..000000000000 --- a/modules/builds-configuration-file.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/build-configuration.adoc - -[id="builds-configuration-file_{context}"] -= Configuring build settings - -You can configure build settings by editing the `build.config.openshift.io/cluster` resource. - -.Procedure - -* Edit the `build.config.openshift.io/cluster` resource: -+ -[source,terminal] ----- -$ oc edit build.config.openshift.io/cluster ----- -+ -The following is an example `build.config.openshift.io/cluster` resource: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Build<1> -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: "2019-05-17T13:44:26Z" - generation: 2 - name: cluster - resourceVersion: "107233" - selfLink: /apis/config.openshift.io/v1/builds/cluster - uid: e2e9cc14-78a9-11e9-b92b-06d6c7da38dc -spec: - buildDefaults:<2> - defaultProxy:<3> - httpProxy: http://proxy.com - httpsProxy: https://proxy.com - noProxy: internal.com - env:<4> - - name: envkey - value: envvalue - gitProxy:<5> - httpProxy: http://gitproxy.com - httpsProxy: https://gitproxy.com - noProxy: internalgit.com - imageLabels:<6> - - name: labelkey - value: labelvalue - resources:<7> - limits: - cpu: 100m - memory: 50Mi - requests: - cpu: 10m - memory: 10Mi - buildOverrides:<8> - imageLabels:<9> - - name: labelkey - value: labelvalue - nodeSelector:<10> - selectorkey: selectorvalue - tolerations:<11> - - effect: NoSchedule - key: node-role.kubernetes.io/builds -operator: Exists ----- -<1> `Build`: Holds cluster-wide information on how to handle builds. The canonical, and only valid name is `cluster`. -<2> `buildDefaults`: Controls the default information for builds. -<3> `defaultProxy`: Contains the default proxy settings for all build operations, including image pull or push and source download. -<4> `env`: A set of default environment variables that are applied to the build if the specified variables do not exist on the build. -<5> `gitProxy`: Contains the proxy settings for Git operations only. If set, this overrides any Proxy settings for all Git commands, such as `git clone`. -<6> `imageLabels`: A list of labels that are applied to the resulting image. -You can override a default label by providing a label with the same name in the `BuildConfig`. -<7> `resources`: Defines resource requirements to execute the build. -<8> `buildOverrides`: Controls override settings for builds. -<9> `imageLabels`: A list of labels that are applied to the resulting image. -If you provided a label in the `BuildConfig` with the same name as one in this table, your label will be overwritten. -<10> `nodeSelector`: A selector which must be true for the build pod to fit on a node. -<11> `tolerations`: A list of tolerations that overrides any existing tolerations set on a build pod. diff --git a/modules/builds-configuration-parameters.adoc b/modules/builds-configuration-parameters.adoc deleted file mode 100644 index 30581f31fff1..000000000000 --- a/modules/builds-configuration-parameters.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/build-configuration.adoc - -[id="builds-configuration-parameters_{context}"] -= Build controller configuration parameters - -The `build.config.openshift.io/cluster` resource offers the following configuration parameters. - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`Build` -|Holds cluster-wide information on how to handle builds. The canonical, and only valid name is `cluster`. - -`spec`: Holds user-settable values for the build controller configuration. - -|`buildDefaults` -|Controls the default information for builds. - -`defaultProxy`: Contains the default proxy settings for all build operations, including image pull or push and source download. - -You can override values by setting the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables in the `BuildConfig` strategy. - -`gitProxy`: Contains the proxy settings for Git operations only. If set, this overrides any proxy settings for all Git commands, such as `git clone`. - -Values that are not set here are inherited from DefaultProxy. - -`env`: A set of default environment variables that are applied to the build if the specified variables do not exist on the build. - -`imageLabels`: A list of labels that are applied to the resulting image. You can override a default label by providing a label with the same name in the `BuildConfig`. - -`resources`: Defines resource requirements to execute the build. - -|`ImageLabel` -|`name`: Defines the name of the label. It must have non-zero length. - -|`buildOverrides` -|Controls override settings for builds. - -`imageLabels`: A list of labels that are applied to the resulting image. If you provided a label in the `BuildConfig` with the same name as one in this table, your label will be overwritten. - -`nodeSelector`: A selector which must be true for the build pod to fit on a node. - -`tolerations`: A list of tolerations that overrides any existing tolerations set on a build pod. - -|`BuildList` -|`items`: Standard object's metadata. - -|=== diff --git a/modules/builds-configuring-post-commit-build-hooks.adoc b/modules/builds-configuring-post-commit-build-hooks.adoc deleted file mode 100644 index 0d21bbb2e3bb..000000000000 --- a/modules/builds-configuring-post-commit-build-hooks.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-configuring-post-commit-build-hooks_{context}"] -= Configuring post commit build hooks - -There are different ways to configure the post build hook. All forms in the following examples are equivalent and run `bundle exec rake test --verbose`. - -.Procedure - -* Shell script: -+ -[source,yaml] ----- -postCommit: - script: "bundle exec rake test --verbose" ----- -+ -The `script` value is a shell script to be run with `/bin/sh -ic`. Use this when a shell script is appropriate to execute the build hook. For example, for running unit tests as above. To control the image entry point, or if the image does not have `/bin/sh`, use `command` and/or `args`. -+ -[NOTE] -==== -The additional `-i` flag was introduced to improve the experience working with CentOS and RHEL images, and may be removed in a future release. -==== - -* Command as the image entry point: -+ -[source,yaml] ----- -postCommit: - command: ["/bin/bash", "-c", "bundle exec rake test --verbose"] ----- -+ -In this form, `command` is the command to run, which overrides the image -entry point in the exec form, as documented in the link:https://docs.docker.com/engine/reference/builder/#entrypoint[Dockerfile reference]. This is needed if the image does not have `/bin/sh`, or if you do not want to use a shell. In all other cases, using `script` might be more convenient. - -* Command with arguments: -+ -[source,yaml] ----- -postCommit: - command: ["bundle", "exec", "rake", "test"] - args: ["--verbose"] ----- -+ -This form is equivalent to appending the arguments to `command`. - -[NOTE] -==== -Providing both `script` and `command` simultaneously creates an invalid build hook. -==== diff --git a/modules/builds-create-custom-build-artifacts.adoc b/modules/builds-create-custom-build-artifacts.adoc deleted file mode 100644 index 5c256aa11692..000000000000 --- a/modules/builds-create-custom-build-artifacts.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/custom-builds-buildah.adoc - - -[id="builds-create-custom-build-artifacts_{context}"] -= Creating custom build artifacts - -You must create the image you want to use as your custom build image. - -.Procedure - -. Starting with an empty directory, create a file named `Dockerfile` with the following content: -+ -[source,terminal] ----- -FROM registry.centos.org/centos:7 -RUN yum install -y buildah -# In this example, `/tmp/build` contains the inputs that build when this -# custom builder image is run. Normally the custom builder image fetches -# this content from some location at build time, by using git clone as an example. -ADD dockerfile.sample /tmp/input/Dockerfile -ADD build.sh /usr/bin -RUN chmod a+x /usr/bin/build.sh -# /usr/bin/build.sh contains the actual custom build logic that will be run when -# this custom builder image is run. -ENTRYPOINT ["/usr/bin/build.sh"] ----- - -. In the same directory, create a file named `dockerfile.sample`. This file is included in the custom build image and defines the image that is produced by the custom build: -+ -[source,terminal] ----- -FROM registry.centos.org/centos:7 -RUN touch /tmp/built ----- - -. In the same directory, create a file named `build.sh`. This file contains the logic that is run when the custom build runs: -+ -[source,terminal] ----- -#!/bin/sh -# Note that in this case the build inputs are part of the custom builder image, but normally this -# is retrieved from an external source. -cd /tmp/input -# OUTPUT_REGISTRY and OUTPUT_IMAGE are env variables provided by the custom -# build framework -TAG="${OUTPUT_REGISTRY}/${OUTPUT_IMAGE}" - - -# performs the build of the new image defined by dockerfile.sample -buildah --storage-driver vfs bud --isolation chroot -t ${TAG} . - - -# buildah requires a slight modification to the push secret provided by the service -# account to use it for pushing the image -cp /var/run/secrets/openshift.io/push/.dockercfg /tmp -(echo "{ \"auths\": " ; cat /var/run/secrets/openshift.io/push/.dockercfg ; echo "}") > /tmp/.dockercfg - - -# push the new image to the target for the build -buildah --storage-driver vfs push --tls-verify=false --authfile /tmp/.dockercfg ${TAG} ----- diff --git a/modules/builds-create-imagestreamtag.adoc b/modules/builds-create-imagestreamtag.adoc deleted file mode 100644 index c94292935a2b..000000000000 --- a/modules/builds-create-imagestreamtag.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/running-entitled-builds.adoc - -[id="builds-create-imagestreamtag_{context}"] -= Creating an image stream tag for the Red Hat Universal Base Image - -To use Red Hat subscriptions within a build, you create an image stream tag to reference the Universal Base Image (UBI). - -To make the UBI available *in every project* in the cluster, you add the image stream tag to the `openshift` namespace. Otherwise, to make it available *in a specific project*, you add the image stream tag to that project. - -The benefit of using image stream tags this way is that doing so grants access to the UBI based on the `registry.redhat.io` credentials in the install pull secret without exposing the pull secret to other users. This is more convenient than requiring each developer to install pull secrets with `registry.redhat.io` credentials in each project. - -.Procedure - -* To create an `ImageStreamTag` in the `openshift` namespace, so it is available to developers in all projects, enter: -+ -[source,terminal] ----- -$ oc tag --source=docker registry.redhat.io/ubi7/ubi:latest ubi:latest -n openshift ----- - -* To create an `ImageStreamTag` in a single project, enter: -+ -[source,terminal] ----- -$ oc tag --source=docker registry.redhat.io/ubi7/ubi:latest ubi:latest ----- diff --git a/modules/builds-creating-secrets.adoc b/modules/builds-creating-secrets.adoc deleted file mode 100644 index feac9983fd1c..000000000000 --- a/modules/builds-creating-secrets.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// * builds/creating-build-inputs.adoc - -[id="builds-creating-secrets_{context}"] -= Creating secrets - -You must create a secret before creating the pods that depend on that secret. - -When creating secrets: - -* Create a secret object with secret data. -* Update the pod service account to allow the reference to the secret. -* Create a pod, which consumes the secret as an environment variable or as a file using a `secret` volume. - -.Procedure - -* Use the create command to create a secret object from a JSON or YAML file: -+ -[source,terminal] ----- -$ oc create -f ----- -+ -For example, you can create a secret from your local `.docker/config.json` file: -+ -[source,terminal] ----- -$ oc create secret generic dockerhub \ - --from-file=.dockerconfigjson= \ - --type=kubernetes.io/dockerconfigjson ----- -+ -This command generates a JSON specification of the secret named `dockerhub` and creates the object. -+ -.YAML Opaque Secret Object Definition -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: mysecret -type: Opaque <1> -data: - username: dXNlci1uYW1l - password: cGFzc3dvcmQ= ----- -+ -<1> Specifies an _opaque_ secret. -+ -.Docker Configuration JSON File Secret Object Definition -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: aregistrykey - namespace: myapps -type: kubernetes.io/dockerconfigjson <1> -data: - .dockerconfigjson:bm5ubm5ubm5ubm5ubm5ubm5ubm5ubmdnZ2dnZ2dnZ2dnZ2dnZ2dnZ2cgYXV0aCBrZXlzCg== <2> ----- -+ -<1> Specifies that the secret is using a docker configuration JSON file. -<2> The output of a base64-encoded the docker configuration JSON file diff --git a/modules/builds-custom-strategy.adoc b/modules/builds-custom-strategy.adoc deleted file mode 100644 index 76d6c22656d9..000000000000 --- a/modules/builds-custom-strategy.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-custom-strategy_{context}"] -= Custom strategy - -When using a Custom strategy, all the defined input secrets and config maps are available in the builder container in the `/var/run/secrets/openshift.io/build` directory. The custom build image must use these secrets and config maps appropriately. With the Custom strategy, you can define secrets as described in Custom strategy options. - -There is no technical difference between existing strategy secrets and the input secrets. However, your builder image can distinguish between them and use them differently, based on your build use case. - -The input secrets are always mounted into the `/var/run/secrets/openshift.io/build` directory, or your builder can parse the `$BUILD` environment variable, which includes the full build object. - -[IMPORTANT] -==== -If a pull secret for the registry exists in both the namespace and the node, builds default to using the pull secret in the namespace. -==== diff --git a/modules/builds-define-build-inputs.adoc b/modules/builds-define-build-inputs.adoc deleted file mode 100644 index 9e59018203c3..000000000000 --- a/modules/builds-define-build-inputs.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/creating-build-inputs.adoc - -[id="builds-define-build-inputs_{context}"] -= Build inputs - -A build input provides source content for builds to operate on. You can use the following build inputs to provide sources in {product-title}, listed in order of precedence: - -ifndef::openshift-online[] -* Inline Dockerfile definitions -endif::[] -* Content extracted from existing images -* Git repositories -* Binary (Local) inputs -* Input secrets -* External artifacts - -ifdef::openshift-online[] -[IMPORTANT] -==== -The docker build strategy is not supported in {product-title}. Therefore, inline Dockerfile definitions are not accepted. -==== -endif::[] - -You can combine multiple inputs in a single build. -ifndef::openshift-online[] -However, as the inline Dockerfile takes precedence, it can overwrite any other file named Dockerfile provided by another input. -endif::[] -Binary (local) input and Git repositories are mutually exclusive inputs. - -You can use input secrets when you do not want certain resources or credentials used during a build to be available in the final application image produced by the build, or want to consume a value that is defined in a secret resource. External artifacts can be used to pull in additional files that are not available as one of the other build input types. - -When you run a build: - -. A working directory is constructed and all input content is placed in the working directory. For example, the input Git repository is cloned into the working directory, and files specified from input images are copied into the working directory using the target path. - -. The build process changes directories into the `contextDir`, if one is defined. - -ifndef::openshift-online[] -. The inline Dockerfile, if any, is written to the current directory. -endif::[] - -. The content from the current directory is provided to the build process -for reference by the -ifndef::openshift-online[] -Dockerfile, custom builder logic, or -endif::[] -`assemble` script. This means any input content that resides outside the `contextDir` is ignored by the build. - -The following example of a source definition includes multiple input types and an explanation of how they are combined. For more details on how each input type is defined, see the specific sections for each input type. - -[source,yaml] ----- -source: - git: - uri: https://github.com/openshift/ruby-hello-world.git <1> - images: - - from: - kind: ImageStreamTag - name: myinputimage:latest - namespace: mynamespace - paths: - - destinationDir: app/dir/injected/dir <2> - sourcePath: /usr/lib/somefile.jar - contextDir: "app/dir" <3> -ifndef::openshift-online[] - dockerfile: "FROM centos:7\nRUN yum install -y httpd" <4> -endif::[] ----- -<1> The repository to be cloned into the working directory for the build. -<2> `/usr/lib/somefile.jar` from `myinputimage` is stored in `/app/dir/injected/dir`. -<3> The working directory for the build becomes `/app/dir`. -ifndef::openshift-online[] -<4> A Dockerfile with this content is created in `/app/dir`, overwriting any existing file with that name. -endif::[] diff --git a/modules/builds-disabling-build-strategy-globally.adoc b/modules/builds-disabling-build-strategy-globally.adoc deleted file mode 100644 index 337e35f54c0b..000000000000 --- a/modules/builds-disabling-build-strategy-globally.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/securing-builds-by-strategy.adoc - - -[id="builds-disabling-build-strategy-globally_{context}"] -= Disabling access to a build strategy globally - -To prevent access to a particular build strategy globally, log in as a user with cluster administrator privileges, remove the corresponding role from the `system:authenticated` group, and apply the annotation `rbac.authorization.kubernetes.io/autoupdate: "false"` to protect them from changes between the API restarts. The following example shows disabling the docker build strategy. - -.Procedure - -. Apply the `rbac.authorization.kubernetes.io/autoupdate` annotation: -+ -[source,terminal] ----- -$ oc edit clusterrolebinding system:build-strategy-docker-binding ----- -+ -.Example output -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - annotations: - rbac.authorization.kubernetes.io/autoupdate: "false" <1> - creationTimestamp: 2018-08-10T01:24:14Z - name: system:build-strategy-docker-binding - resourceVersion: "225" - selfLink: /apis/rbac.authorization.k8s.io/v1/clusterrolebindings/system%3Abuild-strategy-docker-binding - uid: 17b1f3d4-9c3c-11e8-be62-0800277d20bf -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: system:build-strategy-docker -subjects: -- apiGroup: rbac.authorization.k8s.io - kind: Group - name: system:authenticated ----- -<1> Change the `rbac.authorization.kubernetes.io/autoupdate` annotation's value to `"false"`. - -. Remove the role: -+ -[source,terminal] ----- -$ oc adm policy remove-cluster-role-from-group system:build-strategy-docker system:authenticated ----- - -. Ensure the build strategy subresources are also removed from these roles: -+ -[source,terminal] ----- -$ oc edit clusterrole admin ----- -+ -[source,terminal] ----- -$ oc edit clusterrole edit ----- - -. For each role, remove the line that corresponds to the resource of the strategy to disable. - -.. Disable the docker Build Strategy for *admin*: -+ -[source,yaml] ----- -kind: ClusterRole -metadata: - name: admin -... -rules: -- resources: - - builds/custom - - builds/docker <1> - - builds/source - ... -... ----- -<1> Delete this line to disable docker builds globally for users with the *admin* role. diff --git a/modules/builds-displaying-webhook-urls.adoc b/modules/builds-displaying-webhook-urls.adoc deleted file mode 100644 index f42afb1f5ce1..000000000000 --- a/modules/builds-displaying-webhook-urls.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-displaying-webhook-urls_{context}"] -= Displaying webhook URLs - -You can use the following command to display webhook URLs associated with a build configuration. If the command does not display any webhook URLs, then no webhook trigger is defined for that build configuration. - -.Procedure - -* To display any webhook URLs associated with a `BuildConfig`, run: - -[source,terminal] ----- -$ oc describe bc ----- diff --git a/modules/builds-docker-credentials-private-registries.adoc b/modules/builds-docker-credentials-private-registries.adoc deleted file mode 100644 index cd376dfeb2f2..000000000000 --- a/modules/builds-docker-credentials-private-registries.adoc +++ /dev/null @@ -1,114 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/creating-build-inputs.adoc - -[id="builds-docker-credentials-private-registries_{context}"] -= Using docker credentials for private registries - -You can supply builds with a .`docker/config.json` file with valid credentials for private container registries. This allows you to push the output image into a private container image registry or pull a builder image from the private container image registry that requires authentication. - -[NOTE] -==== -For the {product-title} container image registry, this is not required because secrets are generated automatically for you by {product-title}. -==== - -The `.docker/config.json` file is found in your home directory by default and -has the following format: - -[source,yaml] ----- -auths: - https://index.docker.io/v1/: <1> - auth: "YWRfbGzhcGU6R2labnRib21ifTE=" <2> - email: "user@example.com" <3> ----- -<1> URL of the registry. -<2> Encrypted password. -<3> Email address for the login. - -You can define multiple container image registry entries in this file. Alternatively, you can also add authentication entries to this file by running the `docker login` command. The file will be created if it does not exist. - -Kubernetes provides `Secret` objects, which can be used to store configuration and passwords. - -.Prerequisites - -* You must have a `.docker/config.json` file. - -.Procedure - -. Create the secret from your local `.docker/config.json` file: -+ -[source,terminal] ----- -$ oc create secret generic dockerhub \ - --from-file=.dockerconfigjson= \ - --type=kubernetes.io/dockerconfigjson ----- -+ -This generates a JSON specification of the secret named `dockerhub` and creates the object. -+ -. Add a `pushSecret` field into the `output` section of the `BuildConfig` and set it to the name of the `secret` that you created, which in the previous example is `dockerhub`: -+ -[source,yaml] ----- -spec: - output: - to: - kind: "DockerImage" - name: "private.registry.com/org/private-image:latest" - pushSecret: - name: "dockerhub" ----- -+ -You can use the `oc set build-secret` command to set the push secret on the build configuration: -+ -[source,terminal] ----- -$ oc set build-secret --push bc/sample-build dockerhub ----- -+ -You can also link the push secret to the service account used by the build instead of specifying the `pushSecret` field. By default, builds use the `builder` service account. The push secret is automatically added to the build if the secret contains a credential that matches the repository hosting the build's output image. -+ -[source,terminal] ----- -$ oc secrets link builder dockerhub ----- -+ -. Pull the builder container image from a private container image registry by specifying the `pullSecret` field, which is part of the build strategy definition: -+ -[source,yaml] ----- -strategy: - sourceStrategy: - from: - kind: "DockerImage" - name: "docker.io/user/private_repository" - pullSecret: - name: "dockerhub" ----- -+ -You can use the `oc set build-secret` command to set the pull secret on the build configuration: -+ -[source,terminal] ----- -$ oc set build-secret --pull bc/sample-build dockerhub ----- -+ -ifndef::openshift-online[] -[NOTE] -==== -This example uses `pullSecret` in a Source build, but it is also applicable in Docker and Custom builds. -==== -endif::[] -+ -You can also link the pull secret to the service account used by the build instead of specifying the `pullSecret` field. By default, builds use the `builder` service account. The pull secret is automatically added to the build if the secret contains a credential that matches the repository hosting the build's input image. To link the pull secret to the service account used by the build instead of specifying the `pullSecret` field, run: -+ -[source,terminal] ----- -$ oc secrets link builder dockerhub ----- -+ -[NOTE] -==== -You must specify a `from` image in the `BuildConfig` spec to take advantage of this feature. Docker strategy builds generated by `oc new-build` or `oc new-app` may not do this in some situations. -==== diff --git a/modules/builds-docker-source-build-output.adoc b/modules/builds-docker-source-build-output.adoc deleted file mode 100644 index 46046e95b740..000000000000 --- a/modules/builds-docker-source-build-output.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/managing-build-output.adoc - -[id="builds-docker-source-build-output_{context}"] -= Build output - -Builds that use the -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -docker or -endif::[] -source-to-image (S2I) strategy result in the creation of a new container image. The image is then pushed to the container image registry specified in the `output` section of the `Build` specification. - -If the output kind is `ImageStreamTag`, then the image will be pushed to the integrated {product-title} registry and tagged in the specified imagestream. If the output is of type `DockerImage`, then the name of the output reference will be used as a docker push specification. The specification may contain a registry or will default to DockerHub if no registry is specified. If the output section of the build specification is empty, then the image will not be pushed at the end of the build. - -.Output to an ImageStreamTag -[source,yaml] ----- -spec: - output: - to: - kind: "ImageStreamTag" - name: "sample-image:latest" ----- - -.Output to a docker Push Specification -[source,yaml] ----- -spec: - output: - to: - kind: "DockerImage" - name: "my-registry.mycompany.com:5000/myimages/myimage:tag" ----- diff --git a/modules/builds-docker-strategy.adoc b/modules/builds-docker-strategy.adoc deleted file mode 100644 index c5b0b110849f..000000000000 --- a/modules/builds-docker-strategy.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-docker-strategy_{context}"] -= Docker strategy - -When using a docker strategy, you can add all defined input secrets into your container image using the link:https://docs.docker.com/engine/reference/builder/#add[`ADD`] and link:https://docs.docker.com/engine/reference/builder/#copy[`COPY` instructions] in your Dockerfile. - -If you do not specify the `destinationDir` for a secret, then the files are copied into the same directory in which the Dockerfile is located. If you specify a relative path as `destinationDir`, then the secrets are copied into that directory, relative to your Dockerfile location. This makes the secret files available to the Docker build operation as part of the context directory used during the build. - -.Example of a Dockerfile referencing secret and config map data ----- -FROM centos/ruby-22-centos7 - -USER root -COPY ./secret-dir /secrets -COPY ./config / - -# Create a shell script that will output secrets and ConfigMaps when the image is run -RUN echo '#!/bin/sh' > /input_report.sh -RUN echo '(test -f /secrets/secret1 && echo -n "secret1=" && cat /secrets/secret1)' >> /input_report.sh -RUN echo '(test -f /config && echo -n "relative-configMap=" && cat /config)' >> /input_report.sh -RUN chmod 755 /input_report.sh - -CMD ["/bin/sh", "-c", "/input_report.sh"] ----- - -[NOTE] -==== -Users normally remove their input secrets from the final application image so that the secrets are not present in the container running from that image. However, the secrets still exist in the image itself in the layer where they were added. This removal is part of the Dockerfile itself. -==== diff --git a/modules/builds-dockerfile-source.adoc b/modules/builds-dockerfile-source.adoc deleted file mode 100644 index d6b5842d1be2..000000000000 --- a/modules/builds-dockerfile-source.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-dockerfile-source_{context}"] -= Dockerfile source - -When you supply a `dockerfile` value, the content of this field is written to disk as a file named `dockerfile`. This is done after other input sources are processed, so if the input source repository contains a Dockerfile in the root directory, it is overwritten with this content. - -The source definition is part of the `spec` section in the `BuildConfig`: - -[source,yaml] ----- -source: - dockerfile: "FROM centos:7\nRUN yum install -y httpd" <1> ----- -<1> The `dockerfile` field contains an inline Dockerfile that is built. - -.Additional resources - -* The typical use for this field is to provide a Dockerfile to a docker strategy build. diff --git a/modules/builds-gitconfig-file-secured-git.adoc b/modules/builds-gitconfig-file-secured-git.adoc deleted file mode 100644 index b26f55ede667..000000000000 --- a/modules/builds-gitconfig-file-secured-git.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-gitconfig-file-secured-git_{context}"] -= Creating a secret from a .gitconfig file for secured Git - -If your Git server is secured with two-way SSL and user name with password, you must add the certificate files to your source build and add references to the certificate files in the `.gitconfig` file. - -.Prerequisites - -* You must have Git credentials. - -.Procedure - -Add the certificate files to your source build and add references to the certificate files in the `.gitconfig` file. - -. Add the `client.crt`, `cacert.crt`, and `client.key` files to the `/var/run/secrets/openshift.io/source/` folder in the application source code. - -. In the `.gitconfig` file for the server, add the `[http]` section shown in the following example: -+ -[source,terminal] ----- -# cat .gitconfig ----- -+ -.Example output -[source,terminal] ----- -[user] - name = - email = -[http] - sslVerify = false - sslCert = /var/run/secrets/openshift.io/source/client.crt - sslKey = /var/run/secrets/openshift.io/source/client.key - sslCaInfo = /var/run/secrets/openshift.io/source/cacert.crt ----- - -. Create the secret: -+ -[source,terminal] ----- -$ oc create secret generic \ ---from-literal=username= \ <1> ---from-literal=password= \ <2> ---from-file=.gitconfig=.gitconfig \ ---from-file=client.crt=/var/run/secrets/openshift.io/source/client.crt \ ---from-file=cacert.crt=/var/run/secrets/openshift.io/source/cacert.crt \ ---from-file=client.key=/var/run/secrets/openshift.io/source/client.key ----- -<1> The user's Git user name. -<2> The password for this user. - -[IMPORTANT] -==== -To avoid having to enter your password again, be sure to specify the source-to-image (S2I) image in your builds. However, if you cannot clone the repository, you must still specify your user name and password to promote the build. -==== - -.Additional resources - -* `/var/run/secrets/openshift.io/source/` folder in the application source code. diff --git a/modules/builds-gitconfig-file.adoc b/modules/builds-gitconfig-file.adoc deleted file mode 100644 index 5f445ac65be6..000000000000 --- a/modules/builds-gitconfig-file.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-gitconfig-file_{context}"] -= Creating a secret from a .gitconfig file - -If the cloning of your application is dependent on a `.gitconfig` file, then you can create a secret that contains it. Add it to the builder service account and then your `BuildConfig`. - -.Procedure - -* To create a secret from a `.gitconfig` file: - -[source,terminal] ----- -$ oc create secret generic --from-file= ----- - -[NOTE] -==== -SSL verification can be turned off if `sslVerify=false` is set for the `http` -section in your `.gitconfig` file: - -[source,yaml] ----- -[http] - sslVerify=false ----- -==== diff --git a/modules/builds-image-source.adoc b/modules/builds-image-source.adoc deleted file mode 100644 index d2cb76933b9c..000000000000 --- a/modules/builds-image-source.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-image-source_{context}"] -= Image source - -You can add additional files to the build process with images. Input images are referenced in the same way the `From` and `To` image targets are defined. This means both container images and image stream tags can be referenced. In conjunction with the image, you must provide one or more path pairs to indicate the path of the files or directories to copy the image and the destination to place them in the build context. - -The source path can be any absolute path within the image specified. The destination must be a relative directory path. At build time, the image is loaded and the indicated files and directories are copied into the context directory of the build process. This is the same directory into which the source repository content is cloned. If the source path ends in `/.` then the content of the directory is copied, but the directory itself is not created at the destination. - -Image inputs are specified in the `source` definition of the `BuildConfig`: - -[source,yaml] ----- -source: - git: - uri: https://github.com/openshift/ruby-hello-world.git - images: <1> - - from: <2> - kind: ImageStreamTag - name: myinputimage:latest - namespace: mynamespace - paths: <3> - - destinationDir: injected/dir <4> - sourcePath: /usr/lib/somefile.jar <5> - - from: - kind: ImageStreamTag - name: myotherinputimage:latest - namespace: myothernamespace - pullSecret: mysecret <6> - paths: - - destinationDir: injected/dir - sourcePath: /usr/lib/somefile.jar ----- -<1> An array of one or more input images and files. -<2> A reference to the image containing the files to be copied. -<3> An array of source/destination paths. -<4> The directory relative to the build root where the build process can access the file. -<5> The location of the file to be copied out of the referenced image. -<6> An optional secret provided if credentials are needed to access the input image. - -Optionally, if an input image requires a pull secret, you can link the pull secret to the service account used by the build. By default, builds use the `builder` service account. The pull secret is automatically added to the build if the secret contains a credential that matches the repository hosting the input image. To link a pull secret to the service account used by the build, run: - -[source,terminal] ----- -$ oc secrets link builder dockerhub ----- - -ifndef::openshift-online[] -[NOTE] -==== -This feature is not supported for builds using the custom strategy. -==== -endif::[] - -///// -.Additional resources - -* Custom Strategy -ifndef::openshift-online[] -* ImageStreamTags -endif::[] -///// diff --git a/modules/builds-input-secrets-configmaps.adoc b/modules/builds-input-secrets-configmaps.adoc deleted file mode 100644 index 3a5acaef2cbc..000000000000 --- a/modules/builds-input-secrets-configmaps.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-input-secrets-configmaps_{context}"] -= Input secrets and config maps - -In some scenarios, build operations require credentials or other configuration data to access dependent resources, but it is undesirable for that information to be placed in source control. You can define input secrets and input config maps for this purpose. - -For example, when building a Java application with Maven, you can set up a private mirror of Maven Central or JCenter that is accessed by private keys. To download libraries from that private mirror, you have to supply the -following: - -. A `settings.xml` file configured with the mirror's URL and connection settings. -. A private key referenced in the settings file, such as `~/.ssh/id_rsa`. - -For security reasons, you do not want to expose your credentials in the application image. - -This example describes a Java application, but you can use the same approach for adding SSL certificates into the `/etc/ssl/certs` directory, API keys or tokens, license files, and more. diff --git a/modules/builds-manually-add-source-clone-secrets.adoc b/modules/builds-manually-add-source-clone-secrets.adoc deleted file mode 100644 index 7942bb00fabd..000000000000 --- a/modules/builds-manually-add-source-clone-secrets.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-manually-add-source-clone-secrets_{context}"] -= Manually adding a source clone secret - -Source clone secrets can be added manually to a build configuration by adding a `sourceSecret` field to the `source` section inside the `BuildConfig` and setting it to the name of the secret that you created. In this example, it is the `basicsecret`. - -[source,yaml] ----- -apiVersion: "v1" -kind: "BuildConfig" -metadata: - name: "sample-build" -spec: - output: - to: - kind: "ImageStreamTag" - name: "sample-image:latest" - source: - git: - uri: "https://github.com/user/app.git" - sourceSecret: - name: "basicsecret" - strategy: - sourceStrategy: - from: - kind: "ImageStreamTag" - name: "python-33-centos7:latest" ----- - -.Procedure - -You can also use the `oc set build-secret` command to set the source clone secret on an existing build configuration. - -* To set the source clone secret on an existing build configuration, enter the following command: -+ -[source,terminal] ----- -$ oc set build-secret --source bc/sample-build basicsecret ----- diff --git a/modules/builds-output-image-environment-variables.adoc b/modules/builds-output-image-environment-variables.adoc deleted file mode 100644 index 94f3a096599b..000000000000 --- a/modules/builds-output-image-environment-variables.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/managing-build-output.adoc - -[id="builds-output-image-environment-variables_{context}"] -= Output image environment variables - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -docker and -endif::[] -source-to-image (S2I) strategy builds set the following environment variables on output images: - -[options="header"] -|=== - -|Variable |Description - -|`OPENSHIFT_BUILD_NAME` -|Name of the build - -|`OPENSHIFT_BUILD_NAMESPACE` -|Namespace of the build - -|`OPENSHIFT_BUILD_SOURCE` -|The source URL of the build - -|`OPENSHIFT_BUILD_REFERENCE` -|The Git reference used in the build - -|`OPENSHIFT_BUILD_COMMIT` -|Source commit used in the build -|=== - -Additionally, any user-defined environment variable, for example those configured with -S2I] -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -or docker -endif::[] -strategy options, will also be part of the output image environment variable list. diff --git a/modules/builds-output-image-labels.adoc b/modules/builds-output-image-labels.adoc deleted file mode 100644 index 8630446b3a1c..000000000000 --- a/modules/builds-output-image-labels.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/managing-build-output.adoc - -[id="builds-output-image-labels_{context}"] -= Output image labels - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -docker and -endif::[] -source-to-image (S2I)` builds set the following labels on output images: - -[options="header"] -|=== - -|Label |Description - -|`io.openshift.build.commit.author` -|Author of the source commit used in the build - -|`io.openshift.build.commit.date` -|Date of the source commit used in the build - -|`io.openshift.build.commit.id` -|Hash of the source commit used in the build - -|`io.openshift.build.commit.message` -|Message of the source commit used in the build - -|`io.openshift.build.commit.ref` -|Branch or reference specified in the source - -|`io.openshift.build.source-location` -|Source URL for the build -|=== - -You can also use the `BuildConfig.spec.output.imageLabels` field to specify a list of custom labels that will be applied to each image built from the build configuration. - -.Custom Labels to be Applied to Built Images -[source,yaml] ----- -spec: - output: - to: - kind: "ImageStreamTag" - name: "my-image:latest" - imageLabels: - - name: "vendor" - value: "MyCompany" - - name: "authoritative-source-url" - value: "registry.mycompany.com" ----- diff --git a/modules/builds-restricting-build-strategy-globally.adoc b/modules/builds-restricting-build-strategy-globally.adoc deleted file mode 100644 index 11fe3c62d02a..000000000000 --- a/modules/builds-restricting-build-strategy-globally.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/securing-builds-by-strategy.adoc - - -[id="builds-restricting-build-strategy-globally_{context}"] -= Restricting build strategies to users globally - -You can allow a set of specific users to create builds with a particular strategy. - -.Prerequisites - -* Disable global access to the build strategy. - -.Procedure - -* Assign the role that corresponds to the build strategy to a specific user. For -example, to add the `system:build-strategy-docker` cluster role to the user -`devuser`: -+ -[source,terminal] ----- -$ oc adm policy add-cluster-role-to-user system:build-strategy-docker devuser ----- -+ -[WARNING] -==== -Granting a user access at the cluster level to the `builds/docker` subresource means that the user can create builds with the docker strategy in any project in which they can create builds. -==== diff --git a/modules/builds-restricting-build-strategy-to-user.adoc b/modules/builds-restricting-build-strategy-to-user.adoc deleted file mode 100644 index ffce3d5e6735..000000000000 --- a/modules/builds-restricting-build-strategy-to-user.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/securing-builds-by-strategy.adoc - - -[id="builds-restricting-build-strategy-to-user_{context}"] -= Restricting build strategies to a user within a project - -Similar to granting the build strategy role to a user globally, you can allow a set of specific users within a project to create builds with a particular strategy. - -.Prerequisites - -* Disable global access to the build strategy. - -.Procedure - -* Assign the role that corresponds to the build strategy to a specific user within a project. For example, to add the `system:build-strategy-docker` role within the project `devproject` to the user `devuser`: -+ -[source,terminal] ----- -$ oc adm policy add-role-to-user system:build-strategy-docker devuser -n devproject ----- diff --git a/modules/builds-secrets-overview.adoc b/modules/builds-secrets-overview.adoc deleted file mode 100644 index cfc1f4bef1ab..000000000000 --- a/modules/builds-secrets-overview.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// * builds/creating-build-inputs.adoc - -[id="builds-secrets-overview_{context}"] -= What is a secret? - -The `Secret` object type provides a mechanism to hold sensitive information such as passwords, {product-title} client configuration files, `dockercfg` files, private source repository credentials, and so on. Secrets decouple sensitive content from the pods. You can mount secrets into containers using a volume plug-in or the system can use secrets to perform actions on behalf of a pod. - -.YAML Secret Object Definition - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: test-secret - namespace: my-namespace -type: Opaque <1> -data: <2> - username: dmFsdWUtMQ0K <3> - password: dmFsdWUtMg0KDQo= -stringData: <4> - hostname: myapp.mydomain.com <5> ----- -<1> Indicates the structure of the secret’s key names and values. -<2> The allowable format for the keys in the `data` field must meet the guidelines in the `DNS_SUBDOMAIN` value in the Kubernetes identifiers glossary. -<3> The value associated with keys in the `data` map must be base64 encoded. -<4> Entries in the `stringData` map are converted to base64 and the entry are then moved to the `data` map automatically. This field is write-only. The value is only be returned by the `data` field. -<5> The value associated with keys in the `stringData` map is made up of plain text strings. - -[id="builds-secrets-overview-properties_{context}"] -== Properties of secrets - -Key properties include: - -* Secret data can be referenced independently from its definition. -* Secret data volumes are backed by temporary file-storage facilities (tmpfs) and never come to rest on a node. -* Secret data can be shared within a namespace. - -[id="builds-secrets-overview-types_{context}"] -== Types of Secrets - -The value in the `type` field indicates the structure of the secret's key names and values. The type can be used to enforce the presence of user names and keys in the secret object. If you do not want validation, use the `opaque` type, which is the default. - -Specify one of the following types to trigger minimal server-side validation to ensure the presence of specific key names in the secret data: - -* `kubernetes.io/service-account-token`. Uses a service account token. -* `kubernetes.io/dockercfg`. Uses the `.dockercfg` file for required Docker credentials. -* `kubernetes.io/dockerconfigjson`. Uses the `.docker/config.json` file for required Docker credentials. -* `kubernetes.io/basic-auth`. Use with basic authentication. -* `kubernetes.io/ssh-auth`. Use with SSH key authentication. -* `kubernetes.io/tls`. Use with TLS certificate authorities. - -Specify `type= Opaque` if you do not want validation, which means the secret does not claim to conform to any convention for key names or values. An `opaque` secret, allows for unstructured `key:value` pairs that can contain arbitrary values. - -[NOTE] -==== -You can specify other arbitrary types, such as `example.com/my-secret-type`. These types are not enforced server-side, but indicate that the creator of the -secret intended to conform to the key/value requirements of that type. -==== - -[id="builds-secrets-overview-updates_{context}"] -== Updates to secrets - -When you modify the value of a secret, the value used by an already running pod does not dynamically change. To change a secret, you must delete the original pod and create a new pod, in some cases with an identical `PodSpec`. - -Updating a secret follows the same workflow as deploying a new container image. You can use the `kubectl rolling-update` command. - -The `resourceVersion` value in a secret is not specified when it is referenced. Therefore, if a secret is updated at the same time as pods are starting, the version of the secret that is used for the pod is not defined. - -[NOTE] -==== -Currently, it is not possible to check the resource version of a secret object that was used when a pod was created. It is planned that pods report this information, so that a controller could restart ones using a old `resourceVersion`. In the interim, do not update the data of existing secrets, but create new ones with distinct names. -==== diff --git a/modules/builds-secrets-restrictions.adoc b/modules/builds-secrets-restrictions.adoc deleted file mode 100644 index c26236140854..000000000000 --- a/modules/builds-secrets-restrictions.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// * builds/creating-build-inputs.adoc - -[id="builds-secrets-restrictions_{context}"] -= Secrets restrictions - -To use a secret, a pod needs to reference the secret. A secret can be used with a pod in three ways: - -* To populate environment variables for containers. -* As files in a volume mounted on one or more of its containers. -* By kubelet when pulling images for the pod. - -Volume type secrets write data into the container as a file using the volume mechanism. `imagePullSecrets` use service accounts for the automatic injection of the secret into all pods in a namespaces. - -When a template contains a secret definition, the only way for the template to use the provided secret is to ensure that the secret volume sources are validated and that the specified object reference actually points to an object of type `Secret`. Therefore, a secret needs to be created before any pods that depend on it. The most effective way to ensure this is to have it get injected automatically through the use of a service account. - -Secret API objects reside in a namespace. They can only be referenced by pods in that same namespace. - -Individual secrets are limited to 1MB in size. This is to discourage the creation of large secrets that would exhaust apiserver and kubelet memory. However, creation of a number of smaller secrets could also exhaust memory. diff --git a/modules/builds-service-serving-certificate-secrets.adoc b/modules/builds-service-serving-certificate-secrets.adoc deleted file mode 100644 index 613baa458efd..000000000000 --- a/modules/builds-service-serving-certificate-secrets.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// * builds/creating-build-inputs.adoc - -[id="builds-service-serving-certificate-secrets_{context}"] -= Service serving certificate secrets - -Service serving certificate secrets are intended to support complex middleware applications that need out-of-the-box certificates. It has the same settings as the server certificates generated by the administrator tooling for nodes and masters. - -.Procedure - -To secure communication to your service, have the cluster generate a signed serving certificate/key pair into a secret in your namespace. - -* Set the `service.alpha.openshift.io/serving-cert-secret-name` annotation on your service with the value set to the name you want to use for your secret. -+ -Then, your `PodSpec` can mount that secret. When it is available, your pod runs. The certificate is good for the internal service DNS name, `..svc`. -+ -The certificate and key are in PEM format, stored in `tls.crt` and `tls.key` respectively. The certificate/key pair is automatically replaced when it gets close to expiration. View the expiration date in the `service.alpha.openshift.io/expiry` annotation on the secret, which is in RFC3339 format. - -[NOTE] -==== -In most cases, the service DNS name `..svc` is not externally routable. The primary use of `..svc` is for intracluster or intraservice communication, and with re-encrypt routes. -==== - -Other pods can trust cluster-created certificates, which are only signed for -internal DNS names, by using the certificate authority (CA) bundle in the `/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt` file that is automatically mounted in their pod. - -The signature algorithm for this feature is `x509.SHA256WithRSA`. To manually rotate, delete the generated secret. A new certificate is created. diff --git a/modules/builds-setting-build-resources.adoc b/modules/builds-setting-build-resources.adoc deleted file mode 100644 index 09435368469e..000000000000 --- a/modules/builds-setting-build-resources.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/advanced-build-operations.adoc - -[id="builds-setting-build-resources_{context}"] -= Setting build resources - -By default, builds are completed by pods using unbound resources, such as memory and CPU. These resources can be limited. - -.Procedure - -You can limit resource use in two ways: - -* Limit resource use by specifying resource limits in the default container limits of a project. -* Limit resource use by specifying resource limits as part of the build configuration. ** In the following example, each of the `resources`, `cpu`, and `memory` parameters are optional: -+ -[source,yaml] ----- -apiVersion: "v1" -kind: "BuildConfig" -metadata: - name: "sample-build" -spec: - resources: - limits: - cpu: "100m" <1> - memory: "256Mi" <2> ----- -<1> `cpu` is in CPU units: `100m` represents 0.1 CPU units (100 * 1e-3). -<2> `memory` is in bytes: `256Mi` represents 268435456 bytes (256 * 2 ^ 20). -+ -However, if a quota has been defined for your project, one of the following two items is required: -+ -*** A `resources` section set with an explicit `requests`: -+ -[source,yaml] ----- -resources: - requests: <1> - cpu: "100m" - memory: "256Mi" ----- -<1> The `requests` object contains the list of resources that correspond to the list of resources in the quota. -+ -*** A limit range defined in your project, where the defaults from the `LimitRange` object apply to pods created during the build process. -+ -Otherwise, build pod creation will fail, citing a failure to satisfy quota. diff --git a/modules/builds-setting-maximum-duration.adoc b/modules/builds-setting-maximum-duration.adoc deleted file mode 100644 index 38c9c25cee88..000000000000 --- a/modules/builds-setting-maximum-duration.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/advanced-build-operations.adoc - -[id="builds-setting-maximum-duration_{context}"] -= Setting maximum duration - -When defining a `BuildConfig` object, you can define its maximum duration by setting the `completionDeadlineSeconds` field. It is specified in seconds and is not set by default. When not set, there is no maximum duration enforced. - -The maximum duration is counted from the time when a build pod gets scheduled in the system, and defines how long it can be active, including the time needed to pull the builder image. After reaching the specified timeout, the build is terminated by {product-title}. - -.Procedure - -* To set maximum duration, specify `completionDeadlineSeconds` in your `BuildConfig`. The following example shows the part of a `BuildConfig` specifying `completionDeadlineSeconds` field for 30 minutes: -+ -[source,yaml] ----- -spec: - completionDeadlineSeconds: 1800 ----- - -[NOTE] -==== -This setting is not supported with the Pipeline Strategy option. -==== diff --git a/modules/builds-setting-triggers-manually.adoc b/modules/builds-setting-triggers-manually.adoc deleted file mode 100644 index 586c22ba06dc..000000000000 --- a/modules/builds-setting-triggers-manually.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-setting-triggers-manually_{context}"] -= Setting triggers manually - -Triggers can be added to and removed from build configurations with `oc set triggers`. - -.Procedure - -* To set a GitHub webhook trigger on a build configuration, use: -+ -[source,terminal] ----- -$ oc set triggers bc --from-github ----- - -* To set an imagechange trigger, use: -+ -[source,terminal] ----- -$ oc set triggers bc --from-image='' ----- - -* To remove a trigger, add `--remove`: -+ -[source,terminal] ----- -$ oc set triggers bc --from-bitbucket --remove ----- - -[NOTE] -==== -When a webhook trigger already exists, adding it again regenerates the webhook secret. -==== - -For more information, consult the help documentation with by running: - -[source,terminal] ----- -$ oc set triggers --help ----- diff --git a/modules/builds-source-code.adoc b/modules/builds-source-code.adoc deleted file mode 100644 index 41ec0a214aae..000000000000 --- a/modules/builds-source-code.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -//* builds/creating-build-inputs.adoc - -[id="builds-source-code_{context}"] -= Git source - -When specified, source code is fetched from the supplied location. - -ifndef::openshift-online[] -If you supply an inline Dockerfile, it overwrites the Dockerfile in the `contextDir` of the Git repository. -endif::[] - -The source definition is part of the `spec` section in the `BuildConfig`: - -[source,yaml] ----- -source: - git: <1> - uri: "https://github.com/openshift/ruby-hello-world" - ref: "master" - contextDir: "app/dir" <2> -ifndef::openshift-online[] - dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" <3> -endif::[] ----- -<1> The `git` field contains the URI to the remote Git repository of the source code. Optionally, specify the `ref` field to check out a specific Git reference. A valid `ref` can be a SHA1 tag or a branch name. -<2> The `contextDir` field allows you to override the default location inside the source code repository where the build looks for the application source code. If your application exists inside a sub-directory, you can override the default location (the root folder) using this field. -ifndef::openshift-online[] -<3> If the optional `dockerfile` field is provided, it should be a string containing a Dockerfile that overwrites any Dockerfile that may exist in the source repository. -endif::[] - -If the `ref` field denotes a pull request, the system uses a `git fetch` operation and then checkout `FETCH_HEAD`. - -When no `ref` value is provided, {product-title} performs a shallow clone (`--depth=1`). In this case, only the files associated with the most recent commit on the default branch (typically `master`) are downloaded. This results in repositories downloading faster, but without the full commit history. To perform a full `git clone` of the default branch of a specified repository, set `ref` to the name of the default branch (for example `master`). - - -[WARNING] -==== -Git clone operations that go through a proxy that is performing man in the middle (MITM) TLS hijacking or reencrypting of the proxied connection do not work. -==== diff --git a/modules/builds-source-input-satellite-config.adoc b/modules/builds-source-input-satellite-config.adoc deleted file mode 100644 index 080345fc1406..000000000000 --- a/modules/builds-source-input-satellite-config.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/running-entitled-builds.adoc - -[id="builds-source-input-satellite-config_{context}"] -= Adding Red Hat Satellite configurations to builds - -Builds that use Red Hat Satellite to install content must provide appropriate configurations to obtain content from Satellite repositories. - -.Prerequisites - -* You must provide or create a `yum`-compatible repository configuration file that downloads content from your Satellite instance. -+ -.Sample repository configuration -+ -[source,terminal] ----- -[test-] - name=test- - baseurl = https://satellite.../content/dist/rhel/server/7/7Server/x86_64/os - enabled=1 - gpgcheck=0 - sslverify=0 - sslclientkey = /etc/pki/entitlement/...-key.pem - sslclientcert = /etc/pki/entitlement/....pem ----- - -.Procedure - -. Create a `ConfigMap` containing the Satellite repository configuration file: -+ -[source,terminal] ----- -$ oc create configmap yum-repos-d --from-file /path/to/satellite.repo ----- -+ - -. Add the Satellite repository configuration to the `BuildConfig`: -+ -[source,yaml] ----- -source: - configMaps: - - configMap: - name: yum-repos-d - destinationDir: yum.repos.d ----- diff --git a/modules/builds-source-input-subman-config.adoc b/modules/builds-source-input-subman-config.adoc deleted file mode 100644 index 5f04670bd739..000000000000 --- a/modules/builds-source-input-subman-config.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/running-entitled-builds.adoc - -[id="builds-source-input-subman-config_{context}"] -= Adding Subscription Manager configurations to builds - -Builds that use the Subscription Manager to install content must provide appropriate configuration files and certificate authorities for subscribed repositories. - -.Prerequisites - -You must have access to the Subscription Manager's configuration and certificate authority files. - -.Procedure - -. Create a `ConfigMap` for the Subscription Manager configuration: -+ -[source,terminal] ----- -$ oc create configmap rhsm-conf --from-file /path/to/rhsm/rhsm.conf ----- - -. Create a `ConfigMap` for the certificate authority: -+ -[source,terminal] ----- -$ oc create configmap rhsm-ca --from-file /path/to/rhsm/ca/redhat-uep.pem ----- - -. Add the Subscription Manager configuration and certificate authority to the -`BuildConfig`: -+ -[source,yaml] ----- -source: - configMaps: - - configMap: - name: rhsm-conf - destinationDir: rhsm-conf - - configMap: - name: rhsm-ca - destinationDir: rhsm-ca ----- diff --git a/modules/builds-source-secret-basic-auth.adoc b/modules/builds-source-secret-basic-auth.adoc deleted file mode 100644 index 32f61b636b7d..000000000000 --- a/modules/builds-source-secret-basic-auth.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-source-secret-basic-auth_{context}"] -= Creating a secret from source code basic authentication - -Basic authentication requires either a combination of `--username` and `--password`, or a token to authenticate against the software configuration management (SCM) server. - -.Prerequisites - -* User name and password to access the private repository. - -.Procedure - -. Create the secret first before using the `--username` and `--password` to access the private repository: -+ -[source,terminal] ----- -$ oc create secret generic \ - --from-literal=username= \ - --from-literal=password= \ - --type=kubernetes.io/basic-auth ----- -+ -. Create a basic authentication secret with a token: -+ -[source,terminal] ----- -$ oc create secret generic \ - --from-literal=password= \ - --type=kubernetes.io/basic-auth ----- diff --git a/modules/builds-source-secret-combinations-basic-auth-ca.adoc b/modules/builds-source-secret-combinations-basic-auth-ca.adoc deleted file mode 100644 index c307135948e2..000000000000 --- a/modules/builds-source-secret-combinations-basic-auth-ca.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/creating-build-inputs.adoc - -[id="builds-source-secret-combinations-basic-auth-ca_{context}"] -= Creating a basic authentication secret with a CA certificate - -You can combine the different methods for creating source clone secrets for your specific needs, such as a secret that combines a basic authentication and certificate authority (CA) certificate. - -.Prerequisites - -* Basic authentication credentials -* CA certificate - -.Procedure - -* Create a basic authentication secret with a CA certificate, run: -+ -[source,terminal] ----- -$ oc create secret generic \ - --from-literal=username= \ - --from-literal=password= \ - --from-file=ca-cert= \ - --type=kubernetes.io/basic-auth ----- diff --git a/modules/builds-source-secret-combinations-basic-auth-gitconfig-ca.adoc b/modules/builds-source-secret-combinations-basic-auth-gitconfig-ca.adoc deleted file mode 100644 index 956d7b3fcc4b..000000000000 --- a/modules/builds-source-secret-combinations-basic-auth-gitconfig-ca.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/creating-build-inputs.adoc - -[id="builds-source-secret-combinations-basic-auth-gitconfig-ca_{context}"] -= Creating a basic authentication secret with a .gitconfig file and CA certificate - -You can combine the different methods for creating source clone secrets for your specific needs, such as a secret that combines a basic authentication, `.gitconfig` file, and certificate authority (CA) certificate. - -.Prerequisites - -* Basic authentication credentials -* `.gitconfig` file -* CA certificate - -.Procedure - -* To create a basic authentication secret with a `.gitconfig` file and CA certificate, run: -+ -[source,terminal] ----- -$ oc create secret generic \ - --from-literal=username= \ - --from-literal=password= \ - --from-file= \ - --from-file=ca-cert= \ - --type=kubernetes.io/basic-auth ----- diff --git a/modules/builds-source-secret-combinations-basic-auth-gitconfig.adoc b/modules/builds-source-secret-combinations-basic-auth-gitconfig.adoc deleted file mode 100644 index 73b2518ee0d1..000000000000 --- a/modules/builds-source-secret-combinations-basic-auth-gitconfig.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/creating-build-inputs.adoc - -[id="builds-source-secret-combinations-basic-auth-gitconfig_{context}"] -= Creating a basic authentication secret with a .gitconfig file - -You can combine the different methods for creating source clone secrets for your specific needs, such as a secret that combines a basic authentication and `.gitconfig` file. - -.Prerequisites - -* Basic authentication credentials -* `.gitconfig` file - -.Procedure - -* To create a basic authentication secret with a `.gitconfig` file, run: -+ -[source,terminal] ----- -$ oc create secret generic \ - --from-literal=username= \ - --from-literal=password= \ - --from-file= \ - --type=kubernetes.io/basic-auth ----- diff --git a/modules/builds-source-secret-combinations-gitconfig-ca.adoc b/modules/builds-source-secret-combinations-gitconfig-ca.adoc deleted file mode 100644 index 65cdc9238b3a..000000000000 --- a/modules/builds-source-secret-combinations-gitconfig-ca.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-source-secret-combinations-gitconfig-ca_{context}"] -= Creating a secret that combines a .gitconfig file and CA certificate - -You can combine the different methods for creating source clone secrets for your specific needs, such as a secret that combines a `.gitconfig` file and certificate authority (CA) certificate. - -.Prerequisites - -* .gitconfig file -* CA certificate - -.Procedure - -* To create a secret that combines a `.gitconfig` file and CA certificate, run: -+ -[source,terminal] ----- -$ oc create secret generic \ - --from-file=ca.crt= \ - --from-file= ----- diff --git a/modules/builds-source-secret-combinations-ssh-gitconfig.adoc b/modules/builds-source-secret-combinations-ssh-gitconfig.adoc deleted file mode 100644 index afa7cee6dda5..000000000000 --- a/modules/builds-source-secret-combinations-ssh-gitconfig.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-source-secret-combinations-ssh-gitconfig_{context}"] -= Creating a SSH-based authentication secret with a `.gitconfig` file - -You can combine the different methods for creating source clone secrets for your specific needs, such as a SSH-based authentication secret with a `.gitconfig` file. - -.Prerequisites - -* SSH authentication -* .gitconfig file - -.Procedure - -* To create a SSH-based authentication secret with a `.gitconfig` file, run: -+ -[source,terminal] ----- -$ oc create secret generic \ - --from-file=ssh-privatekey= \ - --from-file= \ - --type=kubernetes.io/ssh-auth ----- diff --git a/modules/builds-source-secret-combinations.adoc b/modules/builds-source-secret-combinations.adoc deleted file mode 100644 index 128dc9356a8a..000000000000 --- a/modules/builds-source-secret-combinations.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-source-secret-combinations_{context}"] -= Source secret combinations - -You can combine the different methods for creating source clone secrets for your specific needs. diff --git a/modules/builds-source-secret-ssh-key-auth.adoc b/modules/builds-source-secret-ssh-key-auth.adoc deleted file mode 100644 index e6b0e74e5f18..000000000000 --- a/modules/builds-source-secret-ssh-key-auth.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-source-secret-ssh-key-auth_{context}"] -= Creating a secret from source code SSH key authentication - -SSH key based authentication requires a private SSH key. - -The repository keys are usually located in the `$HOME/.ssh/` directory, and are named `id_dsa.pub`, `id_ecdsa.pub`, `id_ed25519.pub`, or `id_rsa.pub` by default. - -.Procedure - -. Generate SSH key credentials: -+ -[source,terminal] ----- -$ ssh-keygen -t ed25519 -C "your_email@example.com" ----- -+ -[NOTE] -==== -Creating a passphrase for the SSH key prevents {product-title} from building. When prompted for a passphrase, leave it blank. -==== -+ -Two files are created: the public key and a corresponding private key (one of `id_dsa`, `id_ecdsa`, `id_ed25519`, or `id_rsa`). With both of these in place, consult your source control management (SCM) system's manual on how to upload -the public key. The private key is used to access your private repository. -+ -. Before using the SSH key to access the private repository, create the secret: -+ -[source,terminal] ----- -$ oc create secret generic \ - --from-file=ssh-privatekey= \ - --type=kubernetes.io/ssh-auth ----- diff --git a/modules/builds-source-secret-trusted-ca.adoc b/modules/builds-source-secret-trusted-ca.adoc deleted file mode 100644 index 7590af236601..000000000000 --- a/modules/builds-source-secret-trusted-ca.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-source-secret-trusted-ca_{context}"] -= Creating a secret from source code trusted certificate authorities - -The set of Transport Layer Security (TLS) certificate authorities (CA) that are trusted during a Git clone operation are built into the {product-title} infrastructure images. If your Git server uses a self-signed certificate or one signed by an authority not trusted by the image, you can create a secret that contains the certificate or disable TLS verification. - -If you create a secret for the CA certificate, {product-title} uses it to access your Git server during the Git clone operation. Using this method is significantly more secure than disabling Git SSL verification, which accepts any TLS certificate that is presented. - -.Procedure - -Create a secret with a CA certificate file. - -. If your CA uses Intermediate Certificate Authorities, combine the certificates for all CAs in a `ca.crt` file. Enter the following command: -+ -[source,terminal] ----- -$ cat intermediateCA.crt intermediateCA.crt rootCA.crt > ca.crt ----- - -.. Create the secret: -+ -[source,terminal] ----- -$ oc create secret generic mycert --from-file=ca.crt= <1> ----- -<1> You must use the key name `ca.crt`. diff --git a/modules/builds-source-secrets-entitlements.adoc b/modules/builds-source-secrets-entitlements.adoc deleted file mode 100644 index a059450d15b0..000000000000 --- a/modules/builds-source-secrets-entitlements.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/running-entitled-builds.adoc - -[id="builds-source-secrets-entitlements_{context}"] -= Adding subscription entitlements as a build secret - -Builds that use Red Hat subscriptions to install content must include the entitlement keys as a build secret. - -.Prerequisites - -You must have access to Red Hat entitlements through your subscription, and the entitlements must have separate public and private key files. - -.Procedure - -. Create a secret containing your entitlements, ensuring that there are separate files containing the public and private keys: -+ -[source,terminal] ----- -$ oc create secret generic etc-pki-entitlement --from-file /path/to/entitlement/{ID}.pem \ -> --from-file /path/to/entitlement/{ID}-key.pem ... ----- - -. Add the secret as a build input in the build configuration: -+ -[source,yaml] ----- -source: - secrets: - - secret: - name: etc-pki-entitlement - destinationDir: etc-pki-entitlement ----- diff --git a/modules/builds-source-to-image.adoc b/modules/builds-source-to-image.adoc deleted file mode 100644 index fa824fd6a69b..000000000000 --- a/modules/builds-source-to-image.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-source-to-image_{context}"] -= Source-to-image strategy - -When using a `Source` strategy, all defined input secrets are copied to their respective `destinationDir`. If you left `destinationDir` empty, then the secrets are placed in the working directory of the builder image. - -The same rule is used when a `destinationDir` is a relative path. The secrets are placed in the paths that are relative to the working directory of the image. The final directory in the `destinationDir` path is created if it does not exist in the builder image. All preceding directories in the `destinationDir` must exist, or an error will occur. - -[NOTE] -==== -Input secrets are added as world-writable, have `0666` permissions, and are truncated to size zero after executing the `assemble` script. This means that the secret files exist in the resulting image, but they are empty for security reasons. - -Input config maps are not truncated after the `assemble` script completes. -==== diff --git a/modules/builds-strategy-custom-build.adoc b/modules/builds-strategy-custom-build.adoc deleted file mode 100644 index e21f003af6d3..000000000000 --- a/modules/builds-strategy-custom-build.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/build-strategies.adoc - -[id="builds-strategy-custom-build_{context}"] -= Custom build - -The custom build strategy allows developers to define a specific builder image responsible for the entire build process. Using your own builder image allows you to customize your build process. - -A custom builder image is a plain container image embedded with build process logic, for example for building RPMs or base images. - -Custom builds run with a high level of privilege and are not available to users by default. Only users who can be trusted with cluster administration permissions should be granted access to run custom builds. diff --git a/modules/builds-strategy-custom-environment-variables.adoc b/modules/builds-strategy-custom-environment-variables.adoc deleted file mode 100644 index 01f2e4cba861..000000000000 --- a/modules/builds-strategy-custom-environment-variables.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/build-strategies.adoc - -[id="builds-strategy-custom-environment-variables_{context}"] -= Using environment variables for custom builds - -To make environment variables available to the custom build process, you can add environment variables to the `customStrategy` definition of the build configuration. - -The environment variables defined there are passed to the pod that runs the -custom build. - -.Procedure - -. Define a custom HTTP proxy to be used during build: -+ -[source,yaml] ----- -customStrategy: -... - env: - - name: "HTTP_PROXY" - value: "http://myproxy.net:5187/" - ----- -+ -. To manage environment variables defined in the build configuration, enter the following command: -+ -[source,terminal] ----- -$ oc set env ----- diff --git a/modules/builds-strategy-custom-from-image.adoc b/modules/builds-strategy-custom-from-image.adoc deleted file mode 100644 index 6354755bcc1f..000000000000 --- a/modules/builds-strategy-custom-from-image.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/build-strategies.adoc - -[id="builds-strategy-custom-from-image_{context}"] -= Using FROM image for custom builds - -You can use the `customStrategy.from` section to indicate the image to use for the custom build - -.Procedure - -* Set the `customStrategy.from` section: -+ -[source,yaml] ----- -strategy: - customStrategy: - from: - kind: "DockerImage" - name: "openshift/sti-image-builder" ----- diff --git a/modules/builds-strategy-custom-secrets.adoc b/modules/builds-strategy-custom-secrets.adoc deleted file mode 100644 index d24314622919..000000000000 --- a/modules/builds-strategy-custom-secrets.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/build-strategies.adoc - -[id="builds-strategy-custom-secrets_{context}"] -= Using secrets in custom builds - -In addition to secrets for source and images that can be added to all build types, custom strategies allow adding an arbitrary list of secrets to the builder pod. - -.Procedure - -* To mount each secret at a specific location, edit the `secretSource` and `mountPath` fields of the `strategy` YAML file: -+ -[source,yaml] ----- -strategy: - customStrategy: - secrets: - - secretSource: <1> - name: "secret1" - mountPath: "/tmp/secret1" <2> - - secretSource: - name: "secret2" - mountPath: "/tmp/secret2" ----- -<1> `secretSource` is a reference to a secret in the same namespace as the build. -<2> `mountPath` is the path inside the custom builder where the secret should be mounted. diff --git a/modules/builds-strategy-docker-build-arguments.adoc b/modules/builds-strategy-docker-build-arguments.adoc deleted file mode 100644 index a1370bb03b55..000000000000 --- a/modules/builds-strategy-docker-build-arguments.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-docker-build-arguments_{context}"] -= Adding docker build arguments - -You can set link:http://docs.docker.com/v1.7/reference/api/hub_registry_spec/#docker-registry-1-0[docker build arguments] using the `BuildArgs` array. The build arguments are passed to docker when a build is started. - -.Procedure - -To set docker build arguments, add entries to the `BuildArgs` array, which is located in the `dockerStrategy` definition of the `BuildConfig` object. For example: - -[source,yaml] ----- -dockerStrategy: -... - buildArgs: - - name: "foo" - value: "bar" ----- diff --git a/modules/builds-strategy-docker-build.adoc b/modules/builds-strategy-docker-build.adoc deleted file mode 100644 index cb58f6b7d01b..000000000000 --- a/modules/builds-strategy-docker-build.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -//*builds/build-strategies.adoc -//*builds/understanding-image-builds - -[id="builds-strategy-docker-build_{context}"] -= Docker build - -The docker build strategy invokes the docker build command, and it expects a repository with a Dockerfile and all required artifacts in it to produce a runnable image. diff --git a/modules/builds-strategy-docker-entitled-satellite.adoc b/modules/builds-strategy-docker-entitled-satellite.adoc deleted file mode 100644 index 688c10e1f283..000000000000 --- a/modules/builds-strategy-docker-entitled-satellite.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -//* builds/running-entitled-builds.adoc - -[id="builds-strategy-docker-entitled-satellite_{context}"] -= Docker builds using Red Hat Satellite subscriptions - -Docker strategy builds can use Red Hat Satellite repositories to install subscription content. - -.Prerequisites - -* The entitlement keys and Satellite repository configurations must be added as build inputs. - -.Procedure - -Use the following as an example Dockerfile to install content with Satellite: - -[source,terminal] ----- -FROM registry.redhat.io/rhel7:latest -USER root -# Copy entitlements -COPY ./etc-pki-entitlement /etc/pki/entitlement -# Copy repository configuration -COPY ./yum.repos.d /etc/yum.repos.d -# Delete /etc/rhsm-host to use entitlements from the build container -RUN sed -i".org" -e "s#^enabled=1#enabled=0#g" /etc/yum/pluginconf.d/subscription-manager.conf <1> -#RUN cat /etc/yum/pluginconf.d/subscription-manager.conf -RUN yum clean all -#RUN yum-config-manager -RUN rm /etc/rhsm-host && \ - # yum repository info provided by Satellite - yum -y update && \ - yum -y install && \ - # Remove entitlements - rm -rf /etc/pki/entitlement -# OpenShift requires images to run as non-root by default -USER 1001 -ENTRYPOINT ["/bin/bash"] ----- -<1> If adding Satellite configurations to builds using `enabled=1` fails, add `RUN sed -i".org" -e "s#^enabled=1#enabled=0#g" /etc/yum/pluginconf.d/subscription-manager.conf` to the Dockerfile. diff --git a/modules/builds-strategy-docker-entitled-subman.adoc b/modules/builds-strategy-docker-entitled-subman.adoc deleted file mode 100644 index c315fb07b957..000000000000 --- a/modules/builds-strategy-docker-entitled-subman.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/running-entitled-builds.adoc - -[id="builds-strategy-docker-entitled-subman_{context}"] -= Docker builds using Subscription Manager - -Docker strategy builds can use the Subscription Manager to install subscription content. - -.Prerequisites - -The entitlement keys, subscription manager configuration, and subscription manager certificate authority must be added as build inputs. - -.Procedure - -Use the following as an example Dockerfile to install content with the Subscription Manager: - -[source,terminal] ----- -FROM registry.redhat.io/rhel7:latest -USER root -# Copy entitlements -COPY ./etc-pki-entitlement /etc/pki/entitlement -# Copy subscription manager configurations -COPY ./rhsm-conf /etc/rhsm -COPY ./rhsm-ca /etc/rhsm/ca -# Delete /etc/rhsm-host to use entitlements from the build container -RUN rm /etc/rhsm-host && \ - # Initialize /etc/yum.repos.d/redhat.repo - # See https://access.redhat.com/solutions/1443553 - yum repolist --disablerepo=* && \ - subscription-manager repos --enable && \ - yum -y update && \ - yum -y install && \ - # Remove entitlements and Subscription Manager configs - rm -rf /etc/pki/entitlement && \ - rm -rf /etc/rhsm -# OpenShift requires images to run as non-root by default -USER 1001 -ENTRYPOINT ["/bin/bash"] ----- diff --git a/modules/builds-strategy-docker-environment-variables.adoc b/modules/builds-strategy-docker-environment-variables.adoc deleted file mode 100644 index 3e983acb3f90..000000000000 --- a/modules/builds-strategy-docker-environment-variables.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-docker-environment-variables_{context}"] -= Using docker environment variables - -To make environment variables available to the docker build process and resulting image, you can add environment variables to the `dockerStrategy` definition of the build configuration. - -The environment variables defined there are inserted as a single `ENV` Dockerfile instruction right after the `FROM` instruction, so that it can be referenced later on within the Dockerfile. - -.Procedure - -The variables are defined during build and stay in the output image, therefore they will be present in any container that runs that image as well. - -For example, defining a custom HTTP proxy to be used during build and runtime: - -[source,yaml] ----- -dockerStrategy: -... - env: - - name: "HTTP_PROXY" - value: "http://myproxy.net:5187/" ----- - -You can also manage environment variables defined in the build configuration with the `oc set env` command. diff --git a/modules/builds-strategy-docker-force-pull-example.adoc b/modules/builds-strategy-docker-force-pull-example.adoc deleted file mode 100644 index a6d63f81a576..000000000000 --- a/modules/builds-strategy-docker-force-pull-example.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-docker-force-pull-example_{context}"] -= Docker force pull flag example - -Set the following to use the `forcePull` flag with Docker: - -[source,yaml] ----- -strategy: - dockerStrategy: - forcePull: true <1> ----- -<1> This flag causes the local builder image to be ignored, and a fresh version to be pulled from the registry to which the imagestream points. Setting `forcePull` to `false` results in the default behavior of honoring the image stored locally. diff --git a/modules/builds-strategy-docker-from-image.adoc b/modules/builds-strategy-docker-from-image.adoc deleted file mode 100644 index 50ca0ec0fd4c..000000000000 --- a/modules/builds-strategy-docker-from-image.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-docker-from-image_{context}"] -= Replacing Dockerfile FROM image - -You can replace the `FROM` instruction of the Dockerfile with the `from` of the `BuildConfig` object. If the Dockerfile uses multi-stage builds, the image in the last `FROM` instruction will be replaced. - -.Procedure - -To replace the `FROM` instruction of the Dockerfile with the `from` of the `BuildConfig`. - -[source,yaml] ----- -strategy: - dockerStrategy: - from: - kind: "ImageStreamTag" - name: "debian:latest" ----- diff --git a/modules/builds-strategy-docker-squash-layers.adoc b/modules/builds-strategy-docker-squash-layers.adoc deleted file mode 100644 index 3ee30f8247ce..000000000000 --- a/modules/builds-strategy-docker-squash-layers.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -//* builds/running-entitled-builds.adoc - -[id="builds-strategy-docker-squash-layers_{context}"] -= Squash layers with docker builds - -Docker builds normally create a layer representing each instruction in a Dockerfile. Setting the `imageOptimizationPolicy` to `SkipLayers` merges all instructions into a single layer on top of the base image. - -.Procedure - -* Set the `imageOptimizationPolicy` to `SkipLayers`: -+ -[source,yaml] ----- -strategy: - dockerStrategy: - imageOptimizationPolicy: SkipLayers ----- diff --git a/modules/builds-strategy-dockerfile-path.adoc b/modules/builds-strategy-dockerfile-path.adoc deleted file mode 100644 index 09a6442439e1..000000000000 --- a/modules/builds-strategy-dockerfile-path.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-dockerfile-path_{context}"] -= Using Dockerfile path - -By default, docker builds use a Dockerfile located at the root of the context specified in the `BuildConfig.spec.source.contextDir` field. - -The `dockerfilePath` field allows the build to use a different path to locate your Dockerfile, relative to the `BuildConfig.spec.source.contextDir` field. It can be a different file name than the default Dockerfile, such as `MyDockerfile`, or a path to a Dockerfile in a subdirectory, such as `dockerfiles/app1/Dockerfile`. - -.Procedure - -To use the `dockerfilePath` field for the build to use a different path to locate your Dockerfile, set: - -[source,yaml] ----- -strategy: - dockerStrategy: - dockerfilePath: dockerfiles/app1/Dockerfile ----- diff --git a/modules/builds-strategy-enable-pulling-pushing.adoc b/modules/builds-strategy-enable-pulling-pushing.adoc deleted file mode 100644 index a6ab99a9c349..000000000000 --- a/modules/builds-strategy-enable-pulling-pushing.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/running-entitled-builds.adoc - -[id="builds-strategy-enable-pulling-pushing_{context}"] -= Enabling pulling and pushing - -You can enable pulling to a private registry by setting the pull secret and pushing by setting the push secret in the build configuration. - -.Procedure - -To enable pulling to a private registry: - -* Set the pull secret in the build configuration. - -To enable pushing: - - * Set the push secret in the build configuration. - -//// -[NOTE] -==== -This module needs specific instructions and examples. And needs to be used for Docker and S2I. -==== -//// diff --git a/modules/builds-strategy-force-pull-procedure.adoc b/modules/builds-strategy-force-pull-procedure.adoc deleted file mode 100644 index bfc8efea84a1..000000000000 --- a/modules/builds-strategy-force-pull-procedure.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -//* builds/build-strategies.adoc - -[id="builds-strategy-force-pull-procedure_{context}"] -= Using the force pull flag - -By default, if the builder image specified in the build configuration is available locally on the node, that image will be used. However, you can use the `forcepull` flag to override the local image and refresh it from the registry. - -.Procedure - -To override the local image and refresh it from the registry to which the image stream points, create a `BuildConfig` with the `forcePull` flag set to `true`. diff --git a/modules/builds-strategy-pipeline-build.adoc b/modules/builds-strategy-pipeline-build.adoc deleted file mode 100644 index 3d0a604c9310..000000000000 --- a/modules/builds-strategy-pipeline-build.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -//*builds/build-strategies.adoc -//*builds/understanding-image-builds - -[id="builds-strategy-pipeline-build_{context}"] -= Pipeline build - -[IMPORTANT] -==== -The Pipeline build strategy is deprecated in {product-title} 4. Equivalent and improved functionality is present in the {product-title} Pipelines based on Tekton. - -Jenkins images on {product-title} are fully supported and users should follow Jenkins user documentation for defining their `jenkinsfile` in a job or store it in a Source Control Management system. -==== - -The Pipeline build strategy allows developers to define a Jenkins pipeline for use by the Jenkins pipeline plug-in. The build can be started, monitored, and managed by {product-title} in the same way as any other build type. - -Pipeline workflows are defined in a `jenkinsfile`, either embedded directly in the build configuration, or supplied in a Git repository and referenced by the build configuration. - -//The first time a project defines a build configuration using a Pipeline -//strategy, {product-title} instantiates a Jenkins server to execute the -//pipeline. Subsequent Pipeline build configurations in the project share this -//Jenkins server. - -//.Additional resources - -//* Pipeline build configurations require a Jenkins server to manage the -//pipeline execution. diff --git a/modules/builds-strategy-pipeline-environment-variables.adoc b/modules/builds-strategy-pipeline-environment-variables.adoc deleted file mode 100644 index 8bdac5458db6..000000000000 --- a/modules/builds-strategy-pipeline-environment-variables.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-pipeline-environment-variables_{context}"] -= Using environment variables for pipeline builds - -[IMPORTANT] -==== -The Pipeline build strategy is deprecated in {product-title} 4. Equivalent and improved functionality is present in the {product-title} Pipelines based on Tekton. - -Jenkins images on {product-title} are fully supported and users should follow Jenkins user documentation for defining their `jenkinsfile` in a job or store it in a Source Control Management system. -==== - -To make environment variables available to the Pipeline build process, you can add environment variables to the `jenkinsPipelineStrategy` definition of the build configuration. - -Once defined, the environment variables will be set as parameters for any Jenkins job associated with the build configuration. - -.Procedure - -* To define environment variables to be used during build, edit the YAML file: -+ -[source,yaml] ----- -jenkinsPipelineStrategy: -... - env: - - name: "FOO" - value: "BAR" - ----- - -You can also manage environment variables defined in the build configuration with the `oc set env` command. - - - -//[NOTE] -//==== -// This module needs specific instructions and examples. -// This is similar between Docker, S2I, and Custom. -//==== diff --git a/modules/builds-strategy-pipeline-mapping-buildconfig-jenkins.adoc b/modules/builds-strategy-pipeline-mapping-buildconfig-jenkins.adoc deleted file mode 100644 index 93912c1694d9..000000000000 --- a/modules/builds-strategy-pipeline-mapping-buildconfig-jenkins.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-pipeline-mapping-buildconfig-jenkins_{context}"] -= Mapping between BuildConfig environment variables and Jenkins job parameters - -When a Jenkins job is created or updated based on changes to a Pipeline strategy build configuration, any environment variables in the build configuration are mapped to Jenkins job parameters definitions, where the default values for the Jenkins job parameters definitions are the current values of the associated environment variables. - -After the Jenkins job's initial creation, you can still add additional parameters to the job from the Jenkins console. The parameter names differ from the names of the environment variables in the build configuration. The parameters are honored when builds are started for those Jenkins jobs. - -How you start builds for the Jenkins job dictates how the parameters are set. - -* If you start with `oc start-build`, the values of the environment variables in the build configuration are the parameters set for the corresponding job instance. Any changes you make to the parameters' default values from the Jenkins console are ignored. The build configuration values take precedence. - -* If you start with `oc start-build -e`, the values for the environment variables specified in the `-e` option take precedence. -** If you specify an environment variable not listed in the build configuration, they will be added as a Jenkins job parameter definitions. -** Any changes you make from the Jenkins console to the parameters corresponding to the environment variables are ignored. The build configuration and what you specify with `oc start-build -e` takes precedence. - -* If you start the Jenkins job with the Jenkins console, then you can control the setting of the parameters with the Jenkins console as part of starting a build for the job. - -[NOTE] -==== -It is recommended that you specify in the build configuration all possible environment variables to be associated with job parameters. Doing so reduces disk I/O and improves performance during Jenkins processing. -==== diff --git a/modules/builds-strategy-pipeline-providing-jenkinsfile.adoc b/modules/builds-strategy-pipeline-providing-jenkinsfile.adoc deleted file mode 100644 index dc429d4026ac..000000000000 --- a/modules/builds-strategy-pipeline-providing-jenkinsfile.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-pipeline-providing-jenkinsfile_{context}"] -= Providing the Jenkins file for pipeline builds - -[IMPORTANT] -==== -The Pipeline build strategy is deprecated in {product-title} 4. Equivalent and improved functionality is present in the {product-title} Pipelines based on Tekton. - -Jenkins images on {product-title} are fully supported and users should follow Jenkins user documentation for defining their `jenkinsfile` in a job or store it in a Source Control Management system. -==== - -The `jenkinsfile` uses the standard groovy language syntax to allow fine grained control over the configuration, build, and deployment of your application. - -You can supply the `jenkinsfile` in one of the following ways: - -* A file located within your source code repository. -* Embedded as part of your build configuration using the `jenkinsfile` field. - -When using the first option, the `jenkinsfile` must be included in your applications source code repository at one of the following locations: - -* A file named `jenkinsfile` at the root of your repository. -* A file named `jenkinsfile` at the root of the source `contextDir` of your repository. -* A file name specified via the `jenkinsfilePath` field of the `JenkinsPipelineStrategy` section of your BuildConfig, which is relative to the source `contextDir` if supplied, otherwise it defaults to the root of the repository. - -The `jenkinsfile` is run on the Jenkins agent pod, which must have the -{product-title} client binaries available if you intend to use the {product-title} DSL. - -.Procedure - -To provide the Jenkins file, you can either: - -* Embed the Jenkins file in the build configuration. -* Include in the build configuration a reference to the Git repository that contains the Jenkins file. - -.Embedded Definition -[source,yaml] ----- -kind: "BuildConfig" -apiVersion: "v1" -metadata: - name: "sample-pipeline" -spec: - strategy: - jenkinsPipelineStrategy: - jenkinsfile: |- - node('agent') { - stage 'build' - openshiftBuild(buildConfig: 'ruby-sample-build', showBuildLogs: 'true') - stage 'deploy' - openshiftDeploy(deploymentConfig: 'frontend') - } ----- - -.Reference to Git Repository -[source,yaml] ----- -kind: "BuildConfig" -apiVersion: "v1" -metadata: - name: "sample-pipeline" -spec: - source: - git: - uri: "https://github.com/openshift/ruby-hello-world" - strategy: - jenkinsPipelineStrategy: - jenkinsfilePath: some/repo/dir/filename <1> ----- -<1> The optional `jenkinsfilePath` field specifies the name of the file to use, relative to the source `contextDir`. If `contextDir` is omitted, it defaults to the root of the repository. If `jenkinsfilePath` is omitted, it defaults to `jenkinsfile`. diff --git a/modules/builds-strategy-s2i-build.adoc b/modules/builds-strategy-s2i-build.adoc deleted file mode 100644 index e8d51fde8f34..000000000000 --- a/modules/builds-strategy-s2i-build.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/build-strategies.adoc -//* builds/understanding-image-builds.adoc - -[id="builds-strategy-s2i-build_{context}"] -= Source-to-image build - -Source-to-image (S2I) is a tool for building reproducible container images. It produces ready-to-run images by injecting application source into a container image and assembling a new image. The new image incorporates the base image, the builder, and built source and is ready to use with the `buildah run` command. S2I supports incremental builds, which re-use previously downloaded dependencies, previously built artifacts, and so on. - - -//// -The advantages of S2I include the following: - -[horizontal] -Image flexibility:: S2I scripts can be written to inject application code into almost any existing Docker-formatted container image, taking advantage of the existing ecosystem. Note that, currently, S2I relies on `tar` to inject application source, so the image needs to be able to process tarred content. - -Speed:: With S2I, the assemble process can perform a large number of complex operations without creating a new layer at each step, resulting in a fast process. In addition, S2I scripts can be written to re-use artifacts stored in a previous version of the application image, rather than having to download or build them each time the build is run. - -Patchability:: S2I allows you to rebuild the application consistently if an underlying image needs a patch due to a security issue. - -Operational efficiency:: By restricting build operations instead of allowing arbitrary actions, as a Dockerfile would allow, the PaaS operator can avoid accidental or intentional abuses of the build system. - -Operational security:: Building an arbitrary Dockerfile exposes the host system to root privilege escalation. This can be exploited by a malicious user because the entire Docker build process is run as a user with Docker privileges. S2I restricts the operations performed as a root user and can run the scripts as a non-root user. - -User efficiency:: S2I prevents developers from performing arbitrary `yum install` type operations, which could slow down development iteration, during their application build. - -Ecosystem:: S2I encourages a shared ecosystem of images where you can leverage best practices for your applications. - -Reproducibility:: Produced images can include all inputs including specific versions of build tools and dependencies. This ensures that the image can be reproduced precisely. -//// diff --git a/modules/builds-strategy-s2i-buildconfig-environment.adoc b/modules/builds-strategy-s2i-buildconfig-environment.adoc deleted file mode 100644 index 18dce72bbf5c..000000000000 --- a/modules/builds-strategy-s2i-buildconfig-environment.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -//* * builds/build-strategies.adoc - -[id="builds-strategy-s2i-buildconfig-environment_{context}"] -= Using source-to-image build configuration environment - -You can add environment variables to the `sourceStrategy` definition of the build configuration. The environment variables defined there are visible during the `assemble` script execution and will be defined in the output image, making them also available to the `run` script and application code. - -.Procedure - -* For example, to disable assets compilation for your Rails application: -+ -[source,yaml] ----- -sourceStrategy: -... - env: - - name: "DISABLE_ASSET_COMPILATION" - value: "true" ----- - -.Additional resources - -* The build environment section provides more advanced instructions. -* You can also manage environment variables defined in the build configuration with the `oc set env` command. diff --git a/modules/builds-strategy-s2i-environment-files.adoc b/modules/builds-strategy-s2i-environment-files.adoc deleted file mode 100644 index 5d1eec53f808..000000000000 --- a/modules/builds-strategy-s2i-environment-files.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-s2i-environment-files_{context}"] -= Using source-to-image environment files - -Source build enables you to set environment values, one per line, inside your application, by specifying them in a `.s2i/environment` file in the source repository. The environment variables specified in this file are present during the build process and in the output image. - -If you provide a `.s2i/environment` file in your source repository, source-to-image (S2I) reads this file during the build. This allows customization of the build behavior as the `assemble` script may use these variables. - -.Procedure - -For example, to disable assets compilation for your Rails application during the build: - -* Add `DISABLE_ASSET_COMPILATION=true` in the `.s2i/environment` file. - -In addition to builds, the specified environment variables are also available in the running application itself. For example, to cause the Rails application to start in `development` mode instead of `production`: - -* Add `RAILS_ENV=development` to the `.s2i/environment` file. - - -The complete list of supported environment variables is available in the using images section for each image. diff --git a/modules/builds-strategy-s2i-environment-variables.adoc b/modules/builds-strategy-s2i-environment-variables.adoc deleted file mode 100644 index 027e0fd17889..000000000000 --- a/modules/builds-strategy-s2i-environment-variables.adoc +++ /dev/null @@ -1,7 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-s2i-environment-variables_{context}"] -= Source-to-image environment variables - -There are two ways to make environment variables available to the source build process and resulting image. Environment files and BuildConfig environment values. Variables provided will be present during the build process and in the output image. diff --git a/modules/builds-strategy-s2i-force-pull-example.adoc b/modules/builds-strategy-s2i-force-pull-example.adoc deleted file mode 100644 index 85f659bdd1a2..000000000000 --- a/modules/builds-strategy-s2i-force-pull-example.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-s2i-force-pull-example_{context}"] -= Source-to-Image (S2I) force pull flag example - -Set the following to use the `forcePull` flag with S2I: - -[source,yaml] ----- -strategy: - sourceStrategy: - from: - kind: "ImageStreamTag" - name: "builder-image:latest" <1> - forcePull: true <2> ----- -<1> The builder image being used, where the local version on the node may not be up to date with the version in the registry to which the imagestream points. -<2> This flag causes the local builder image to be ignored and a fresh version to be pulled from the registry to which the imagestream points. Setting `forcePull` to `false` results in the default behavior of honoring the image stored locally. diff --git a/modules/builds-strategy-s2i-ignore-source-files.adoc b/modules/builds-strategy-s2i-ignore-source-files.adoc deleted file mode 100644 index c7d3d76d7d48..000000000000 --- a/modules/builds-strategy-s2i-ignore-source-files.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-s2i-ignore-source-files_{context}"] -= Ignoring source-to-image source files - -Source-to-image (S2I) supports a `.s2iignore` file, which contains a list of file patterns that should be ignored. Files in the build working directory, as provided by the various input sources, that match a pattern found in the `.s2iignore` file will not be made available to the `assemble` script. - -//For more details on the format of the `.s2iignore` file, see the S2I documentation. diff --git a/modules/builds-strategy-s2i-incremental-builds.adoc b/modules/builds-strategy-s2i-incremental-builds.adoc deleted file mode 100644 index 96a217fa2400..000000000000 --- a/modules/builds-strategy-s2i-incremental-builds.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -//* builds/build-strategies.adoc - -[id="builds-strategy-s2i-incremental-builds_{context}"] -= Performing source-to-image incremental builds - -Source-to-image (S2I) can perform incremental builds, which means it reuses artifacts from previously-built images. - -.Procedure - -* To create an incremental build, create a with the following modification to the strategy definition: -+ -[source,yaml] ----- -strategy: - sourceStrategy: - from: - kind: "ImageStreamTag" - name: "incremental-image:latest" <1> - incremental: true <2> ----- -<1> Specify an image that supports incremental builds. Consult the documentation of the builder image to determine if it supports this behavior. -<2> This flag controls whether an incremental build is attempted. If the builder image does not support incremental builds, the build will still succeed, but you will get a log message stating the incremental build was not successful because of a missing `save-artifacts` script. - -.Additional resources - -* See S2I Requirements for information on how to create a builder image supporting incremental builds. diff --git a/modules/builds-strategy-s2i-override-builder-image-scripts.adoc b/modules/builds-strategy-s2i-override-builder-image-scripts.adoc deleted file mode 100644 index 0173d3938119..000000000000 --- a/modules/builds-strategy-s2i-override-builder-image-scripts.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-s2i-override-builder-image-scripts_{context}"] -= Overriding source-to-image builder image scripts - -You can override the `assemble`, `run`, and `save-artifacts` source-to-image (S2I) scripts provided by the builder image. - -.Procedure - -To override the `assemble`, `run`, and `save-artifacts` S2I scripts provided by the builder image, either: - -* Provide an `assemble`, `run`, or `save-artifacts` script in the `.s2i/bin` directory of your application source repository. -* Provide a URL of a directory containing the scripts as part of the strategy definition. For example: -+ -[source,yaml] ----- -strategy: - sourceStrategy: - from: - kind: "ImageStreamTag" - name: "builder-image:latest" - scripts: "http://somehost.com/scripts_directory" <1> ----- -<1> This path will have `run`, `assemble`, and `save-artifacts` appended to it. If any or all scripts are found they will be used in place of the same named scripts provided in the image. - -[NOTE] -==== -Files located at the `scripts` URL take precedence over files located in `.s2i/bin` of the source repository. -==== diff --git a/modules/builds-strategy-secrets-web-console.adoc b/modules/builds-strategy-secrets-web-console.adoc deleted file mode 100644 index 64173603a7a3..000000000000 --- a/modules/builds-strategy-secrets-web-console.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-strategy-secrets-web-console_{context}"] -= Adding secrets with web console - -You can add a secret to your build configuration so that it can access a private repository. - -.Procedure - -To add a secret to your build configuration so that it can access a private -repository from the {product-title} web console: - -. Create a new {product-title} project. - -. Create a secret that contains credentials for accessing a private source code -repository. - -. Create a build configuration. - -. On the build configuration editor page or in the `create app from builder image` page of the web console, set the *Source Secret*. - -. Click the *Save* button. - - -//[NOTE] -//==== -// This module needs specific instructions and examples. -// This is applicable for Docker, S2I, and Custom. -//==== diff --git a/modules/builds-triggers.adoc b/modules/builds-triggers.adoc deleted file mode 100644 index a2ec77d47ca7..000000000000 --- a/modules/builds-triggers.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-triggers_{context}"] -= Build triggers - -When defining a `BuildConfig`, you can define triggers to control the circumstances in which the `BuildConfig` should be run. The following build triggers are available: - -* Webhook -* Image change -* Configuration change diff --git a/modules/builds-troubleshooting-access-resources.adoc b/modules/builds-troubleshooting-access-resources.adoc deleted file mode 100644 index 678a0656c2ad..000000000000 --- a/modules/builds-troubleshooting-access-resources.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/troubleshooting-builds.adoc - -[id="builds-troubleshooting-access-resources_{context}"] -= Resolving denial for access to resources - -If your request for access to resources is denied: - -Issue:: -A build fails with: - -[source,terminal] ----- -requested access to the resource is denied ----- - -Resolution:: -You have exceeded one of the image quotas set on your project. Check your current quota and verify the limits applied and storage in use: - -[source,terminal] ----- -$ oc describe quota ----- diff --git a/modules/builds-troubleshooting-service-certificate-generation.adoc b/modules/builds-troubleshooting-service-certificate-generation.adoc deleted file mode 100644 index 2b111d5adaf5..000000000000 --- a/modules/builds-troubleshooting-service-certificate-generation.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// *builds/troubleshooting-builds.adoc - -[id="builds-troubleshooting-service-certificate-generation_{context}"] -= Service certificate generation failure - -If your request for access to resources is denied: - -Issue:: -If a service certificate generation fails with (service's `service.alpha.openshift.io/serving-cert-generation-error` annotation contains): - -.Example output -[source,terminal] ----- -secret/ssl-key references serviceUID 62ad25ca-d703-11e6-9d6f-0e9c0057b608, which does not match 77b6dd80-d716-11e6-9d6f-0e9c0057b60 ----- - -Resolution:: -The service that generated the certificate no longer exists, or has a different `serviceUID`. You must force certificates regeneration by removing the old secret, and clearing the following annotations on the service: `service.alpha.openshift.io/serving-cert-generation-error` and `service.alpha.openshift.io/serving-cert-generation-error-num`: - -[source,terminal] ----- -$ oc delete secret ----- - -[source,terminal] ----- -$ oc annotate service service.alpha.openshift.io/serving-cert-generation-error- ----- - -[source,terminal] ----- -$ oc annotate service service.alpha.openshift.io/serving-cert-generation-error-num- ----- - -[NOTE] -==== -The command removing annotation has a `-` after the annotation name to be -removed. -==== diff --git a/modules/builds-tutorial-pipeline.adoc b/modules/builds-tutorial-pipeline.adoc deleted file mode 100644 index ea4425907a97..000000000000 --- a/modules/builds-tutorial-pipeline.adoc +++ /dev/null @@ -1,223 +0,0 @@ -// Module included in the following assemblies: -// * builds/build-strategies.adoc - -[id="builds-tutorial-pipeline_{context}"] -= Pipeline build tutorial - -[IMPORTANT] -==== -The Pipeline build strategy is deprecated in {product-title} 4. Equivalent and improved functionality is present in the {product-title} Pipelines based on Tekton. - -Jenkins images on {product-title} are fully supported and users should follow Jenkins user documentation for defining their `jenkinsfile` in a job or store it in a Source Control Management system. -==== - -This example demonstrates how to create an {product-title} Pipeline that will build, deploy, and verify a `Node.js/MongoDB` application using the `nodejs-mongodb.json` template. - -.Procedure - -. Create the Jenkins master: -+ -[source,terminal] ----- - $ oc project ----- -+ -Select the project that you want to use or create a new project with `oc new-project `. -+ -[source,terminal] ----- - $ oc new-app jenkins-ephemeral <2> ----- -+ -If you want to use persistent storage, use `jenkins-persistent` instead. -+ -. Create a file named `nodejs-sample-pipeline.yaml` with the following content: -+ -[NOTE] -==== -This creates a `BuildConfig` object that employs the Jenkins pipeline strategy to build, deploy, and scale the `Node.js/MongoDB` example application. -==== -+ -[source,yaml] -+ ----- -kind: "BuildConfig" -apiVersion: "v1" -metadata: - name: "nodejs-sample-pipeline" -spec: - strategy: - jenkinsPipelineStrategy: - jenkinsfile: - type: JenkinsPipeline ----- -+ -. Once you create a `BuildConfig` object with a `jenkinsPipelineStrategy`, tell the -pipeline what to do by using an inline `jenkinsfile`: -+ -[NOTE] -==== -This example does not set up a Git repository for the application. - -The following `jenkinsfile` content is written in Groovy using the {product-title} DSL. For this example, include inline content in the `BuildConfig` object using the YAML Literal Style, though including a `jenkinsfile` in your source repository is the preferred method. -==== -+ -[source,groovy] ----- -def templatePath = 'https://raw.githubusercontent.com/openshift/nodejs-ex/master/openshift/templates/nodejs-mongodb.json' <1> -def templateName = 'nodejs-mongodb-example' <2> -pipeline { - agent { - node { - label 'nodejs' <3> - } - } - options { - timeout(time: 20, unit: 'MINUTES') <4> - } - stages { - stage('preamble') { - steps { - script { - openshift.withCluster() { - openshift.withProject() { - echo "Using project: ${openshift.project()}" - } - } - } - } - } - stage('cleanup') { - steps { - script { - openshift.withCluster() { - openshift.withProject() { - openshift.selector("all", [ template : templateName ]).delete() <5> - if (openshift.selector("secrets", templateName).exists()) { <6> - openshift.selector("secrets", templateName).delete() - } - } - } - } - } - } - stage('create') { - steps { - script { - openshift.withCluster() { - openshift.withProject() { - openshift.newApp(templatePath) <7> - } - } - } - } - } - stage('build') { - steps { - script { - openshift.withCluster() { - openshift.withProject() { - def builds = openshift.selector("bc", templateName).related('builds') - timeout(5) { <8> - builds.untilEach(1) { - return (it.object().status.phase == "Complete") - } - } - } - } - } - } - } - stage('deploy') { - steps { - script { - openshift.withCluster() { - openshift.withProject() { - def rm = openshift.selector("dc", templateName).rollout() - timeout(5) { <9> - openshift.selector("dc", templateName).related('pods').untilEach(1) { - return (it.object().status.phase == "Running") - } - } - } - } - } - } - } - stage('tag') { - steps { - script { - openshift.withCluster() { - openshift.withProject() { - openshift.tag("${templateName}:latest", "${templateName}-staging:latest") <10> - } - } - } - } - } - } -} ----- -<1> Path of the template to use. -<2> Name of the template that will be created. -<3> Spin up a `node.js` agent pod on which to run this build. -<4> Set a timeout of 20 minutes for this pipeline. -<5> Delete everything with this template label. -<6> Delete any secrets with this template label. -<7> Create a new application from the `templatePath`. -<8> Wait up to five minutes for the build to complete. -<9> Wait up to five minutes for the deployment to complete. -<10> If everything else succeeded, tag the `$ {templateName}:latest` image as -`$ {templateName}-staging:latest`. A pipeline build configuration for the staging -environment can watch for the `$ {templateName}-staging:latest` image to change -and then deploy it to the staging environment. -+ -[NOTE] -==== -The previous example was written using the declarative pipeline style, but the older scripted pipeline style is also supported. -==== -+ -. Create the Pipeline `BuildConfig` in your {product-title} cluster: -+ -[source,terminal] ----- -$ oc create -f nodejs-sample-pipeline.yaml ----- -+ -.. If you do not want to create your own file, you can use the sample from the Origin repository by running: -+ -[source,terminal] ----- -$ oc create -f https://raw.githubusercontent.com/openshift/origin/master/examples/jenkins/pipeline/nodejs-sample-pipeline.yaml ----- -+ -. Start the Pipeline: -+ -[source,terminal] ----- -$ oc start-build nodejs-sample-pipeline ----- -+ -[NOTE] -==== -Alternatively, you can start your pipeline with the {product-title} web console by navigating to the Builds -> Pipeline section and clicking *Start Pipeline*, or by visiting the Jenkins Console, navigating to the Pipeline that you created, and clicking *Build Now*. -==== -+ -Once the pipeline is started, you should see the following actions performed within your project: -+ -* A job instance is created on the Jenkins server. -* An agent pod is launched, if your pipeline requires one. -* The pipeline runs on the agent pod, or the master if no agent is required. -** Any previously created resources with the `template=nodejs-mongodb-example` label will be deleted. -** A new application, and all of its associated resources, will be created from the `nodejs-mongodb-example` template. -** A build will be started using the `nodejs-mongodb-example` `BuildConfig`. -*** The pipeline will wait until the build has completed to trigger the next stage. -** A deployment will be started using the `nodejs-mongodb-example` deployment configuration. -*** The pipeline will wait until the deployment has completed to trigger the next stage. -** If the build and deploy are successful, the `nodejs-mongodb-example:latest` image will be tagged as `nodejs-mongodb-example:stage`. -* The agent pod is deleted, if one was required for the pipeline. -+ -[NOTE] -==== -The best way to visualize the pipeline execution is by viewing it in the {product-title} web console. You can view your pipelines by logging in to the web console and navigating to Builds -> Pipelines. -==== diff --git a/modules/builds-understanding-openshift-pipeline.adoc b/modules/builds-understanding-openshift-pipeline.adoc deleted file mode 100644 index 7de6eb38c3d8..000000000000 --- a/modules/builds-understanding-openshift-pipeline.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -//* builds/build-strategies.adoc - -[id="builds-understanding-openshift-pipeline_{context}"] -= Understanding {product-title} pipelines - -[IMPORTANT] -==== -The Pipeline build strategy is deprecated in {product-title} 4. Equivalent and improved functionality is present in the {product-title} Pipelines based on Tekton. - -Jenkins images on {product-title} are fully supported and users should follow Jenkins user documentation for defining their `jenkinsfile` in a job or store it in a Source Control Management system. -==== - -Pipelines give you control over building, deploying, and promoting your applications on {product-title}. Using a combination of the Jenkins Pipeline build strategy, `jenkinsfiles`, and the {product-title} Domain Specific Language (DSL) provided by the Jenkins Client Plug-in, you can create advanced build, test, deploy, and promote pipelines for any scenario. - -*{product-title} Jenkins Sync Plugin* - -The {product-title} Jenkins Sync Plugin keeps the build configuration and build objects in sync with Jenkins jobs and builds, and provides the following: - - * Dynamic job and run creation in Jenkins. - * Dynamic creation of agent pod templates from image streams, image stream tags, or config maps. - * Injecting of environment variables. - * Pipeline visualization in the {product-title} web console. - * Integration with the Jenkins git plugin, which passes commit information from - * Synchronizing secrets into Jenkins credential entries {product-title} builds to the Jenkins git plugin. - -*{product-title} Jenkins Client Plugin* - -The {product-title} Jenkins Client Plugin is a Jenkins plugin which aims to provide a readable, concise, comprehensive, and fluent Jenkins Pipeline syntax for rich interactions with an {product-title} API Server. The plugin uses the {product-title} command line tool, `oc`, which must be available on the nodes executing the script. - -The Jenkins Client Plug-in must be installed on your Jenkins master so the {product-title} DSL will be available to use within the `jenkinsfile` for your application. This plug-in is installed and enabled by default when using the {product-title} Jenkins image. - -For {product-title} Pipelines within your project, you will must use the Jenkins Pipeline Build Strategy. This strategy defaults to using a `jenkinsfile` at the root of your source repository, but also provides the following configuration options: - -* An inline `jenkinsfile` field within your build configuration. -* A `jenkinsfilePath` field within your build configuration that references the location of the `jenkinsfile` to use relative to the source `contextDir`. - -[NOTE] -==== -The optional `jenkinsfilePath` field specifies the name of the file to use, relative to the source `contextDir`. If `contextDir` is omitted, it defaults to the root of the repository. If `jenkinsfilePath` is omitted, it defaults to `jenkinsfile`. -==== diff --git a/modules/builds-use-custom-builder-image.adoc b/modules/builds-use-custom-builder-image.adoc deleted file mode 100644 index 5a1c2bb2e136..000000000000 --- a/modules/builds-use-custom-builder-image.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/custom-builds-buildah.adoc - - -[id="builds-use-custom-builder-image_{context}"] -= Use custom builder image - -You can define a `BuildConfig` object that uses the custom strategy in conjunction with your custom builder image to execute your custom build logic. - -.Prerequisites - -* Define all the required inputs for new custom builder image. -* Build your custom builder image. - -.Procedure - -. Create a file named `buildconfig.yaml`. This file defines the `BuildConfig` object that is created in your project and executed: -+ -[source,yaml] ----- -kind: BuildConfig -apiVersion: v1 -metadata: - name: sample-custom-build - labels: - name: sample-custom-build - annotations: - template.alpha.openshift.io/wait-for-ready: 'true' -spec: - strategy: - type: Custom - customStrategy: - forcePull: true - from: - kind: ImageStreamTag - name: custom-builder-image:latest - namespace: <1> - output: - to: - kind: ImageStreamTag - name: sample-custom:latest ----- -<1> Specify your project name. - -. Create the `BuildConfig`: -+ -[source,terminal] ----- -$ oc create -f buildconfig.yaml ----- - -. Create a file named `imagestream.yaml`. This file defines the image stream to which the build will push the image: -+ -[source,yaml] ----- -kind: ImageStream -apiVersion: v1 -metadata: - name: sample-custom -spec: {} ----- - -. Create the imagestream: -+ -[source,terminal] ----- -$ oc create -f imagestream.yaml ----- - -. Run your custom build: -+ -[source,terminal] ----- -$ oc start-build sample-custom-build -F ----- -+ -When the build runs, it launches a pod running the custom builder image that was built earlier. The pod runs the `build.sh` logic that is defined as the entrypoint for the custom builder image. The `build.sh` logic invokes Buildah to build the `dockerfile.sample` that was embedded in the custom builder image, and then uses Buildah to push the new image to the `sample-custom image stream`. diff --git a/modules/builds-using-bitbucket-webhooks.adoc b/modules/builds-using-bitbucket-webhooks.adoc deleted file mode 100644 index 6daf4640c7f7..000000000000 --- a/modules/builds-using-bitbucket-webhooks.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-using-bitbucket-webhooks_{context}"] -= Using Bitbucket webhooks - -link:https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html[Bitbucket webhooks] handle the call made by Bitbucket when a repository is updated. Similar to the previous triggers, you must specify a secret. The following example is a trigger definition YAML within the `BuildConfig`: - -[source,yaml] ----- -type: "Bitbucket" -bitbucket: - secretReference: - name: "mysecret" ----- - -The payload URL is returned as the Bitbucket Webhook URL by the `oc describe` command, and is structured as follows: - -.Example output -[source,terminal] ----- -https:///oapi/v1/namespaces//buildconfigs//webhooks//bitbucket ----- - -.Procedure - -. To configure a Bitbucket Webhook: - -.. Describe the 'BuildConfig' to get the webhook URL: -+ -[source,terminal] ----- -$ oc describe bc ----- - -.. Copy the webhook URL, replacing `` with your secret value. - -.. Follow the link:https://confluence.atlassian.com/bitbucket/manage-webhooks-735643732.html[Bitbucket setup instructions] to paste the webhook URL into your Bitbucket repository settings. - -. Given a file containing a valid JSON payload, such as `payload.json`, you can -manually trigger the webhook with `curl`: -+ -[source,terminal] ----- -$ curl -H "X-Event-Key: repo:push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https:///oapi/v1/namespaces//buildconfigs//webhooks//bitbucket ----- -+ -The `-k` argument is only necessary if your API server does not have a properly signed certificate. diff --git a/modules/builds-using-build-fields-as-environment-variables.adoc b/modules/builds-using-build-fields-as-environment-variables.adoc deleted file mode 100644 index eb452ddbd7e2..000000000000 --- a/modules/builds-using-build-fields-as-environment-variables.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-using-build-fields-as-environment-variables_{context}"] -= Using build fields as environment variables - -You can inject information about the build object by setting the `fieldPath` environment variable source to the `JsonPath` of the field from which you are interested in obtaining the value. - -[NOTE] -==== -Jenkins Pipeline strategy does not support `valueFrom` syntax for environment variables. -==== - -.Procedure - -* Set the `fieldPath` environment variable source to the `JsonPath` of the field from which you are interested in obtaining the value: -+ -[source,yaml] ----- -env: - - name: FIELDREF_ENV - valueFrom: - fieldRef: - fieldPath: metadata.name ----- diff --git a/modules/builds-using-cli-post-commit-build-hooks.adoc b/modules/builds-using-cli-post-commit-build-hooks.adoc deleted file mode 100644 index dbfe7e04c114..000000000000 --- a/modules/builds-using-cli-post-commit-build-hooks.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-using-cli-post-commit-build-hooks_{context}"] -= Using the CLI to set post commit build hooks - -The `oc set build-hook` command can be used to set the build hook for a build configuration. - -.Procedure - -. To set a command as the post-commit build hook: -+ -[source,terminal] ----- -$ oc set build-hook bc/mybc \ - --post-commit \ - --command \ - -- bundle exec rake test --verbose ----- -+ -. To set a script as the post-commit build hook: -+ -[source,terminal] ----- -$ oc set build-hook bc/mybc --post-commit --script="bundle exec rake test --verbose" ----- diff --git a/modules/builds-using-external-artifacts.adoc b/modules/builds-using-external-artifacts.adoc deleted file mode 100644 index 8f79b07f4c0f..000000000000 --- a/modules/builds-using-external-artifacts.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/creating-build-inputs.adoc - -[id="builds-using-external-artifacts_{context}"] -= External artifacts - -It is not recommended to store binary files in a source repository. Therefore, you must define a build which pulls additional files, such as Java `.jar` dependencies, during the build process. How this is done depends on the build strategy you are using. - -For a Source build strategy, you must put appropriate shell commands into the `assemble` script: - -.`.s2i/bin/assemble` File -[source,terminal] ----- -#!/bin/sh -APP_VERSION=1.0 -wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar ----- - -.`.s2i/bin/run` File -[source,terminal] ----- -#!/bin/sh -exec java -jar app.jar ----- - -ifndef::openshift-online[] -For a Docker build strategy, you must modify the Dockerfile and invoke -shell commands with the link:https://docs.docker.com/engine/reference/builder/#run[`RUN` instruction]: - -.Excerpt of Dockerfile -[source,terminal] ----- -FROM jboss/base-jdk:8 - -ENV APP_VERSION 1.0 -RUN wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar - -EXPOSE 8080 -CMD [ "java", "-jar", "app.jar" ] ----- -endif::[] - -In practice, you may want to use an environment variable for the file location so that the specific file to be downloaded can be customized using an environment variable defined on the `BuildConfig`, rather than updating the -ifndef::openshift-online[] -Dockerfile or -endif::[] -`assemble` script. - -You can choose between different methods of defining environment variables: - -* Using the `.s2i/environment` file] (only for a Source build strategy) -* Setting in `BuildConfig` -* Providing explicitly using `oc start-build --env` (only for builds that are triggered manually) - -//.Additional resources -//* For more information on how to control which *_assemble_* and *_run_* script is -//used by a Source build, see Overriding builder image scripts. diff --git a/modules/builds-using-generic-webhooks.adoc b/modules/builds-using-generic-webhooks.adoc deleted file mode 100644 index 15c0161baff9..000000000000 --- a/modules/builds-using-generic-webhooks.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-using-generic-webhooks_{context}"] -= Using generic webhooks - -Generic webhooks are invoked from any system capable of making a web request. As with the other webhooks, you must specify a secret, which is part of the URL that the caller must use to trigger the build. The secret ensures the uniqueness of the URL, preventing others from triggering the build. The following is an example trigger definition YAML within the `BuildConfig`: - -[source,yaml] ----- -type: "Generic" -generic: - secretReference: - name: "mysecret" - allowEnv: true <1> ----- -<1> Set to `true` to allow a generic webhook to pass in environment variables. - -.Procedure - -. To set up the caller, supply the calling system with the URL of the generic -webhook endpoint for your build: -+ -.Example output -[source,terminal] ----- -https:///oapi/v1/namespaces//buildconfigs//webhooks//generic ----- -+ -The caller must invoke the webhook as a `POST` operation. - -. To invoke the webhook manually you can use `curl`: -+ -[source,terminal] ----- -$ curl -X POST -k https:///oapi/v1/namespaces//buildconfigs//webhooks//generic ----- -+ -The HTTP verb must be set to `POST`. The insecure `-k` flag is specified to ignore certificate validation. This second flag is not necessary if your cluster has properly signed certificates. -+ -The endpoint can accept an optional payload with the following format: -+ -[source,yaml] ----- -git: - uri: "" - ref: "" - commit: "" - author: - name: "" - email: "" - committer: - name: "" - email: "" - message: "" -env: <1> - - name: "" - value: "" ----- -<1> Similar to the `BuildConfig` environment variables, the environment variables defined here are made available to your build. If these variables collide with the `BuildConfig` environment variables, these variables take precedence. By default, environment variables passed by webhook are ignored. Set the `allowEnv` field to `true` on the webhook definition to enable this behavior. - -. To pass this payload using `curl`, define it in a file named `payload_file.yaml` and run: -+ -[source,terminal] ----- -$ curl -H "Content-Type: application/yaml" --data-binary @payload_file.yaml -X POST -k https:///oapi/v1/namespaces//buildconfigs//webhooks//generic ----- -+ -The arguments are the same as the previous example with the addition of a header and a payload. The `-H` argument sets the `Content-Type` header to `application/yaml` or `application/json` depending on your payload format. The `--data-binary` argument is used to send a binary payload with newlines intact with the `POST` request. - -[NOTE] -==== -{product-title} permits builds to be triggered by the generic webhook even if an invalid request payload is presented, for example, invalid content type, unparsable or invalid content, and so on. This behavior is maintained for backwards compatibility. If an invalid request payload is presented, {product-title} returns a warning in JSON format as part of its `HTTP 200 OK` response. -==== diff --git a/modules/builds-using-github-webhooks.adoc b/modules/builds-using-github-webhooks.adoc deleted file mode 100644 index 94de607a20a5..000000000000 --- a/modules/builds-using-github-webhooks.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-using-github-webhooks_{context}"] -= Using GitHub webhooks - -GitHub webhooks handle the call made by GitHub when a repository is updated. When defining the trigger, you must specify a secret, which is part of the URL you supply to GitHub when configuring the webhook. - -Example GitHub webhook definition: - -[source,yaml] ----- -type: "GitHub" -github: - secretReference: - name: "mysecret" ----- - -[NOTE] -==== -The secret used in the webhook trigger configuration is not the same as `secret` field you encounter when configuring webhook in GitHub UI. The former is to make the webhook URL unique and hard to predict, the latter is an optional string field used to create HMAC hex digest of the body, which is sent as an `X-Hub-Signature` header. -==== - -The payload URL is returned as the GitHub Webhook URL by the `oc describe` -command (see Displaying Webhook URLs), and is structured as follows: - -.Example output -[source,terminal] ----- -https:///oapi/v1/namespaces//buildconfigs//webhooks//github ----- - -.Prerequisites - -* Create a `BuildConfig` from a GitHub repository. - -.Procedure - -. To configure a GitHub Webhook: - -.. After creating a `BuildConfig` from a GitHub repository, run: -+ -[source,terminal] ----- -$ oc describe bc/ ----- -+ -This generates a webhook GitHub URL that looks like: -+ -.Example output -[source,terminal] ----- -/github>. ----- - -.. Cut and paste this URL into GitHub, from the GitHub web console. - -.. In your GitHub repository, select *Add Webhook* from *Settings -> Webhooks*. - -.. Paste the URL output into the *Payload URL* field. - -.. Change the *Content Type* from GitHub's default `application/x-www-form-urlencoded` to `application/json`. - -.. Click *Add webhook*. -+ -You should see a message from GitHub stating that your webhook was successfully configured. -+ -Now, when you push a change to your GitHub repository, a new build automatically starts, and upon a successful build a new deployment starts. -+ -[NOTE] -==== -link:https://gogs.io[Gogs] supports the same webhook payload format as GitHub. Therefore, if you are using a Gogs server, you can define a GitHub webhook trigger on your `BuildConfig` and trigger it by your Gogs server as well. -==== - -. Given a file containing a valid JSON payload, such as `payload.json`, you can manually trigger the webhook with `curl`: -+ -[source,terminal] ----- -$ curl -H "X-GitHub-Event: push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https:///oapi/v1/namespaces//buildconfigs//webhooks//github ----- -+ -The `-k` argument is only necessary if your API server does not have a properly -signed certificate. - -.Additional resources - -//* link:https://developer.github.com/webhooks/[GitHub] -* link:https://gogs.io[Gogs] diff --git a/modules/builds-using-gitlab-webhooks.adoc b/modules/builds-using-gitlab-webhooks.adoc deleted file mode 100644 index e47fb8095fb8..000000000000 --- a/modules/builds-using-gitlab-webhooks.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-using-gitlab-webhooks_{context}"] -= Using GitLab webhooks - -GitLab webhooks handle the call made by GitLab when a repository is updated. As with the GitHub triggers, you must specify a secret. The following example is a trigger definition YAML within the `BuildConfig`: - -[source,yaml] ----- -type: "GitLab" -gitlab: - secretReference: - name: "mysecret" ----- - -The payload URL is returned as the GitLab Webhook URL by the `oc describe` command, and is structured as follows: - -.Example output -[source,terminal] ----- -https:///oapi/v1/namespaces//buildconfigs//webhooks//gitlab ----- - -.Procedure - -. To configure a GitLab Webhook: - -.. Describe the `BuildConfig` to get the webhook URL: -+ -[source,terminal] ----- -$ oc describe bc ----- - -.. Copy the webhook URL, replacing `` with your secret value. - -.. Follow the link:https://docs.gitlab.com/ce/user/project/integrations/webhooks.html#webhooks[GitLab setup instructions] -to paste the webhook URL into your GitLab repository settings. - -. Given a file containing a valid JSON payload, such as `payload.json`, you can -manually trigger the webhook with `curl`: -+ -[source,terminal] ----- -$ curl -H "X-GitLab-Event: Push Hook" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https:///oapi/v1/namespaces//buildconfigs//webhooks//gitlab ----- -+ -The `-k` argument is only necessary if your API server does not have a properly -signed certificate. - -.Additional resources - -//* link:https://docs.gitlab.com/ce/user/project/integrations/webhooks.html[GitLab] diff --git a/modules/builds-using-image-change-triggers.adoc b/modules/builds-using-image-change-triggers.adoc deleted file mode 100644 index 253edae3b292..000000000000 --- a/modules/builds-using-image-change-triggers.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-using-image-change-triggers_{context}"] -= Using image change triggers - -Image change triggers allow your build to be automatically invoked when a new version of an upstream image is available. For example, if a build is based on top of a RHEL image, then you can trigger that build to run any time the RHEL image changes. As a result, the application image is always running on the latest RHEL base image. - -[NOTE] -==== -Image streams that point to container images in link:http://docs.docker.com/v1.7/reference/api/hub_registry_spec/#docker-registry-1-0[v1 container registries] only trigger a build once when the image stream tag becomes available and not on subsequent image updates. This is due to the lack of uniquely identifiable images in v1 container registries. -==== - -.Procedure - -Configuring an image change trigger requires the following actions: - -. Define an `ImageStream` that points to the upstream image you want to trigger on: -+ -[source,yaml] ----- -kind: "ImageStream" -apiVersion: "v1" -metadata: - name: "ruby-20-centos7" ----- -+ -This defines the image stream that is tied to a container image repository located at `_/__/ruby-20-centos7`. The `` is defined as a service with the name `docker-registry` running in {product-title}. - -. If an image stream is the base image for the build, set the from field in the build strategy to point to the `ImageStream`: -+ -[source,yaml] ----- -strategy: - sourceStrategy: - from: - kind: "ImageStreamTag" - name: "ruby-20-centos7:latest" ----- -+ -In this case, the `sourceStrategy` definition is consuming the `latest` tag of the image stream named `ruby-20-centos7` located within this namespace. - -. Define a build with one or more triggers that point to `ImageStreams`: -+ -[source,yaml] ----- -type: "imageChange" <1> -imageChange: {} -type: "imageChange" <2> -imageChange: - from: - kind: "ImageStreamTag" - name: "custom-image:latest" ----- -<1> An image change trigger that monitors the `ImageStream` and `Tag` as defined by the build strategy's `from` field. The `imageChange` object here must be empty. -<2> An image change trigger that monitors an arbitrary imagestream. The `imageChange` part in this case must include a `from` field that references the `ImageStreamTag` to monitor. - -When using an image change trigger for the strategy image stream, the generated build is supplied with an immutable docker tag that points to the latest image corresponding to that tag. This new image reference is used by the strategy when it executes for the build. - -For other image change triggers that do not reference the strategy image stream, a new build is started, but the build strategy is not updated with a unique image reference. - -Since this example has an image change trigger for the strategy, the resulting build is: - -[source,yaml] ----- -strategy: - sourceStrategy: - from: - kind: "DockerImage" - name: "172.30.17.3:5001/mynamespace/ruby-20-centos7:" ----- - -This ensures that the triggered build uses the new image that was just pushed to the repository, and the build can be re-run any time with the same inputs. - -You can pause an image change trigger to allow multiple changes on the referenced image stream before a build is started. You can also set the `paused` attribute to true when initially adding an `ImageChangeTrigger` to a `BuildConfig` to prevent a build from being immediately triggered. - -[source,yaml] ----- -type: "ImageChange" -imageChange: - from: - kind: "ImageStreamTag" - name: "custom-image:latest" - paused: true ----- - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -In addition to setting the image field for all `Strategy` types, for custom builds, the `OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE` environment variable is checked. -If it does not exist, then it is created with the immutable image reference. If it does exist then it is updated with the immutable image reference. -endif::[] - -If a build is triggered due to a webhook trigger or manual request, the build that is created uses the `` resolved from the `ImageStream` referenced by the `Strategy`. This ensures that builds are performed using consistent image tags for ease of reproduction. - -.Additional resources - -* link:http://docs.docker.com/v1.7/reference/api/hub_registry_spec/#docker-registry-1-0[v1 container registries] diff --git a/modules/builds-using-proxy-git-cloning.adoc b/modules/builds-using-proxy-git-cloning.adoc deleted file mode 100644 index ac1c73338379..000000000000 --- a/modules/builds-using-proxy-git-cloning.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-using-proxy-git-cloning_{context}"] -= Using a proxy - -If your Git repository can only be accessed using a proxy, you can define the proxy to use in the `source` section of the build configuration. You can configure both an HTTP and HTTPS proxy to use. Both fields are optional. Domains for which no proxying should be performed can also be specified in the `NoProxy` field. - -[NOTE] -==== -Your source URI must use the HTTP or HTTPS protocol for this to work. -==== - -[source,yaml] ----- -source: - git: - uri: "https://github.com/openshift/ruby-hello-world" - httpProxy: http://proxy.example.com - httpsProxy: https://proxy.example.com - noProxy: somedomain.com, otherdomain.com ----- - -[NOTE] -==== -For Pipeline strategy builds, given the current restrictions with the Git plug-in for Jenkins, any Git operations through the Git plug-in do not leverage the HTTP or HTTPS proxy defined in the `BuildConfig`. The Git plug-in only uses the proxy configured in the Jenkins UI at the Plugin Manager panel. This proxy is then used for all git interactions within Jenkins, across all jobs. -==== - -.Additional resources - -* You can find instructions on how to configure proxies through the Jenkins UI at link:https://wiki.jenkins-ci.org/display/JENKINS/JenkinsBehindProxy[JenkinsBehindProxy]. diff --git a/modules/builds-using-secrets-as-environment-variables.adoc b/modules/builds-using-secrets-as-environment-variables.adoc deleted file mode 100644 index 42c82ec59e91..000000000000 --- a/modules/builds-using-secrets-as-environment-variables.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/creating-build-inputs.adoc - -[id="builds-using-secrets-as-environment-variables_{context}"] -= Using secrets as environment variables - -You can make key values from secrets available as environment variables using the `valueFrom` syntax. - -.Procedure - -* To use a secret as an environment variable, set the `valueFrom` syntax: -+ -[source,yaml] ----- -apiVersion: v1 -kind: BuildConfig -metadata: - name: secret-example-bc -spec: - strategy: - sourceStrategy: - env: - - name: MYVAL - valueFrom: - secretKeyRef: - key: myval - name: mysecret ----- diff --git a/modules/builds-using-secrets.adoc b/modules/builds-using-secrets.adoc deleted file mode 100644 index 79ae1b225642..000000000000 --- a/modules/builds-using-secrets.adoc +++ /dev/null @@ -1,119 +0,0 @@ -// Module included in the following assemblies: -// * builds/creating-build-inputs.adoc - - -[id="builds-using-secrets_{context}"] -= Using secrets - -After creating secrets, you can create a pod to reference your secret, get logs, and delete the pod. - -.Procedure - -. Create the pod to reference your secret: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- - -. Get the logs: -+ -[source,terminal] ----- -$ oc logs secret-example-pod ----- - -. Delete the pod: -+ -[source,terminal] ----- -$ oc delete pod secret-example-pod ----- - -.Additional resources - -* Example YAML files with secret data: -+ -.YAML Secret That Will Create Four Files -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: test-secret -data: - username: dmFsdWUtMQ0K <1> - password: dmFsdWUtMQ0KDQo= <2> -stringData: - hostname: myapp.mydomain.com <3> - secret.properties: |- <4> - property1=valueA - property2=valueB ----- -<1> File contains decoded values. -<2> File contains decoded values. -<3> File contains the provided string. -<4> File contains the provided data. -+ -.YAML of a Pod Populating Files in a Volume with Secret Data -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: secret-example-pod -spec: - containers: - - name: secret-test-container - image: busybox - command: [ "/bin/sh", "-c", "cat /etc/secret-volume/*" ] - volumeMounts: - # name must match the volume name below - - name: secret-volume - mountPath: /etc/secret-volume - readOnly: true - volumes: - - name: secret-volume - secret: - secretName: test-secret - restartPolicy: Never ----- -+ -.YAML of a Pod Populating Environment Variables with Secret Data -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: secret-example-pod -spec: - containers: - - name: secret-test-container - image: busybox - command: [ "/bin/sh", "-c", "export" ] - env: - - name: TEST_SECRET_USERNAME_ENV_VAR - valueFrom: - secretKeyRef: - name: test-secret - key: username - restartPolicy: Never ----- -+ -.YAML of a Build Config Populating Environment Variables with Secret Data -[source,yaml] ----- -apiVersion: v1 -kind: BuildConfig -metadata: - name: secret-example-bc -spec: - strategy: - sourceStrategy: - env: - - name: TEST_SECRET_USERNAME_ENV_VAR - valueFrom: - secretKeyRef: - name: test-secret - key: username ----- diff --git a/modules/builds-webhook-triggers.adoc b/modules/builds-webhook-triggers.adoc deleted file mode 100644 index fbea051a1045..000000000000 --- a/modules/builds-webhook-triggers.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/triggering-builds-build-hooks.adoc - -[id="builds-webhook-triggers_{context}"] -= Webhook triggers - -Webhook triggers allow you to trigger a new build by sending a request to the {product-title} API endpoint. You can define these triggers using GitHub, GitLab, Bitbucket, or Generic webhooks. - -Currently, {product-title} webhooks only support the analogous versions of the push event for each of the Git-based Source Code Management (SCM) systems. All other event types are ignored. - -When the push events are processed, the {product-title} master host confirms if the branch reference inside the event matches the branch reference in the corresponding `BuildConfig`. If so, it then checks out the exact commit reference noted in the webhook event on the {product-title} build. If they do not match, no build is triggered. - -[NOTE] -==== -`oc new-app` and `oc new-build` create GitHub and Generic webhook triggers automatically, but any other needed webhook triggers must be added manually. You can manually add triggers by setting triggers. -==== - -For all webhooks, you must define a secret with a key named `WebHookSecretKey` and the value being the value to be supplied when invoking the webhook. The webhook definition must then reference the secret. The secret ensures the uniqueness of the URL, preventing others from triggering the build. The value of the key is compared to the secret provided during the webhook invocation. - -For example here is a GitHub webhook with a reference to a secret named `mysecret`: - -[source,yaml] ----- -type: "GitHub" -github: - secretReference: - name: "mysecret" ----- - -The secret is then defined as follows. Note that the value of the secret is base64 encoded as is required for any `data` field of a `Secret` object. - -[source,yaml] ----- -- kind: Secret - apiVersion: v1 - metadata: - name: mysecret - creationTimestamp: - data: - WebHookSecretKey: c2VjcmV0dmFsdWUx ----- diff --git a/modules/bulk-locking-and-unlocking-process-baselines.adoc b/modules/bulk-locking-and-unlocking-process-baselines.adoc new file mode 100644 index 000000000000..0394e3a24779 --- /dev/null +++ b/modules/bulk-locking-and-unlocking-process-baselines.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: REFERENCE +[id="bulk-locking-and-unlocking-process-baselines_{context}"] += Bulk locking and unlocking process baselines + +[role="_abstract"] +You can lock or unlock all process baselines in a cluster by using API endpoints. You can specify an optional set of namespaces to limit the action to just those namespaces. The API endpoints are as follows: + +* `/v1/processbaselines/bulk/lock` +* `/v1/processbaselines/bulk/unlock` + +The following example shows the input for the endpoints: + +[source,json] +---- +{ + "cluster_id": "aeaaaaaa-0000-0000-0000-000000000000", + "namespaces": [ + "stackrox", + "gmp-system" + ] +} +---- + +These endpoints return success or an error. diff --git a/modules/bypass-admission-controller-enforcement.adoc b/modules/bypass-admission-controller-enforcement.adoc new file mode 100644 index 000000000000..9e295a7a69d1 --- /dev/null +++ b/modules/bypass-admission-controller-enforcement.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="bypass-admission-controller-enforcement_{context}"] += Bypassing admission controller enforcement + +[role="_abstract"] +To bypass the admission controller, add the `admission.stackrox.io/break-glass` annotation to your configuration YAML. +Bypassing the admission controller triggers a policy violation which includes deployment details. +Red{nbsp}Hat recommends providing an issue-tracker link or some other reference as the value of this annotation so that others can understand why you bypassed the admission controller. diff --git a/modules/ca-rotation-support-for-different-installation-methods.adoc b/modules/ca-rotation-support-for-different-installation-methods.adoc new file mode 100644 index 000000000000..15ae21459e34 --- /dev/null +++ b/modules/ca-rotation-support-for-different-installation-methods.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * configuration/internal-certificate-authority-rotation-for-rhacs.adoc + +:_mod-docs-content-type: REFERENCE +[id="ca-rotation-support-for-different-installation-methods_{context}"] += CA rotation support for different installation methods + +The following table shows the level of certificate authority (CA) rotation support based on the installation method you use for Central and secured clusters: + +.Installation methods and CA rotation support +[cols="2,2,2,2",options="header"] +|=== +|Component |Installation method |CA rotation support |Notes + +|Central +|Operator-installed +|Full support +|Migration is fully automated. + +|Central +|Helm or manifest +|Not supported +|Use the Operator for automatic CA rotation. + +|Secured cluster +|Operator-installed +|Full support +|Migration is fully automated if the connected Central instance is also Operator-installed. + +|Secured cluster +|Helm or manifest +|Partial support +|Connect to Central that has rotated its CA, but cannot rotate its own service certificates to the new CA. Manual re-registration is required before the old CA expires. + +|=== \ No newline at end of file diff --git a/modules/central-configuration-options-operator.adoc b/modules/central-configuration-options-operator.adoc new file mode 100644 index 000000000000..cc9e0d651ba5 --- /dev/null +++ b/modules/central-configuration-options-operator.adoc @@ -0,0 +1,338 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-config-options-ocp.adoc +:_mod-docs-content-type: CONCEPT +[id="central-configuration-options-operator_{context}"] += Central configuration options using the Operator + +[role="_abstract"] +When you create a Central instance, the Operator lists the following configuration options for the `Central` custom resource. + +The following table includes settings for an external PostgreSQL database. + +[id="central-settings_{context}"] +== Central settings + +[cols="1,3"] +|=== +| Parameter | Description + +| `central.adminPasswordSecret` +| Specify a secret that contains the administrator password in the `password` data item. If omitted, the operator autogenerates a password and stores it in the `password` item in the `central-htpasswd` secret. + +|`central.defaultTLSSecret` +| By default, Central only serves an internal TLS certificate, which means that you need to handle TLS termination at the ingress or load balancer level. If you want to terminate TLS in Central and serve a custom server certificate, you can specify a secret containing the certificate and private key. + +|`central.adminPasswordGenerationDisabled` +|Set this parameter to `true` to disable the automatic administrator password generation. Use this only after you perform the first-time setup of alternative authentication methods. +Do not use this for initial installation. +Otherwise, you must reinstall the custom resource to log back in. + +| `central.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Central. This parameter is mainly used for infrastructure nodes. + +| `central.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +|`central.exposure.loadBalancer.enabled` +|Set this to `true` to expose Central through a load balancer. + +|`central.exposure.loadBalancer.port` +|Use this parameter to specify a custom port for your load balancer. + +|`central.exposure.loadBalancer.ip` +|Use this parameter to specify a static IP address reserved for your load balancer. + +|`central.exposure.route.enabled` +|Set this to `true` to expose Central through a {osp} passthrough route. Disables all route settings if set to `false`. The default value is `false`. + +|`central.exposure.route.host` +|Use this parameter to specify a custom hostname to use for Central's passthrough route. Leave this unset to accept the default value that {ocp} provides. + +|`central.exposure.route.reencrypt.enabled` +|Set this to `true` to expose Central through a {osp} reencrypt route. The default value is `false`. + +|`central.exposure.route.reencrypt.host` +|Use this parameter to specify a custom hostname to use for Central's reencrypt route. Leave this unset to accept the default value that {ocp} provides. + +|`central.exposure.route.reencrypt.tls.caCertificate` +|Use this parameter to specify a PEM-encoded certificate chain that might be used to establish a complete chain of trust. By default, {ocp} provides the certificate authority. + +|`central.exposure.route.reencrypt.tls.certificate` +|Use this parameter to specify the PEM-encoded certificate that is served on the route. The {ocp} certificate authority signs the default certificate. + +|`central.exposure.route.reencrypt.tls.destinationCACertificate` +|Use this parameter to specify the CA certificate of the final destination, that is of Central. The {ocp} router uses this certificate to perform health checks on the secure connection. By default, Central provides the certificate authority. + +|`central.exposure.route.reencrypt.tls.key` +|Use this parameter to specify the PEM-encoded private key of the certificate that is served on the route. The {ocp} certificate authority signs the default certificate. + +|`central.exposure.nodeport.enabled` +|Set this to `true` to expose Central through a node port. The default value is `false`. + +|`central.exposure.nodeport.port` +|Use this to specify an explicit node port. + +|`central.monitoring.exposeEndpoint` +|Use `Enabled` to enable monitoring for Central. When you enable monitoring, {product-title-short} creates a new monitoring service on port number `9090`. The default value is `Disabled`. + +|`central.nodeSelector` +|If you want this component to only run on specific nodes, you can use this parameter to configure a node selector. + +|`central.resources.limits` +| Use this parameter to override the default resource limits for the Central. + +|`central.resources.requests` +| Use this parameter to override the default resource requests for the Central. + +|`central.imagePullSecrets` +|Use this parameter to specify the image pull secrets for the Central image. + +| `central.db.passwordSecret.name` +| Specify a secret that has the database password in the `password` data item. Only use this parameter if you want to specify a connection string manually. If omitted, the operator auto-generates a password and stores it in the `password` item in the `central-db-password` secret. + +|`central.db.connectionString` +a| Setting this parameter will not deploy Central DB, and Central will connect using the specified connection string. If you specify a value for this parameter, you must also specify a value for `central.db.passwordSecret.name`. +This parameter has the following constraints: + +* Connection string must be in keyword/value format as described in the PostgreSQL documentation. For more information, see the links in the *Additional resources* section. +* Postgres 15 is the recommended and supported version. Red{nbsp}Hat has deprecated the support for Postgres 13 and will remove it in the newer versions of {product-title-short}. +* Connections through PGBouncer are not supported. +* You must have the following permissions on the database: + ** Connection rights to the database. + ** Usage and create privileges on the schema. + ** Select, insert, update, and delete privileges on all tables. + ** Usage privileges on all sequences in the schema. + +| `central.db.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Central DB. This parameter is mainly used for infrastructure nodes. + +| `central.db.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +|`central.db.persistence.hostPath.path` +|Specify a host path to store persistent data in a directory on the host. Red{nbsp}Hat does not recommend using this. If you need to use host path, you must use it with a node selector. + +|`central.db.persistence.persistentVolumeClaim.claimName` +|The name of the PVC to manage persistent data. +If no PVC with the given name exists, it is created. The default value is `central-db` if not set. To prevent data loss, the PVC is not removed automatically when Central is deleted. + +|`central.db.persistence.persistentVolumeClaim.size` +| The size of the persistent volume when created through the claim. This is automatically generated by default. + +|`central.db.persistence.persistentVolumeClaim.storageClassName` +| The name of the storage class to use for the PVC. If your cluster is not configured with a default storage class, you must provide a value for this parameter. + +|`central.db.connectionPoolSize.minConnections` +| Use this parameter to override the default minimum connection pool size between Central and Central DB. The default value is 10. + +|`central.db.connectionPoolSize.maxConnections` +a| Use this parameter to override the default maximum connection pool size between Central and Central DB. The default value is 90. +Ensure that this value does not exceed the maximum number of connections supported by the Central DB: + +* An Operator-managed Central DB supports a maximum of 100 connections by default. +* For external PostgreSQL databases, check the database settings or consult your cloud provider for managed databases. + +|`central.db.resources.limits` +| Use this parameter to override the default resource limits for the Central DB. + +|`central.db.resources.requests` +| Use this parameter to override the default resource requests for the Central DB. + +|`central.db.nodeSelector` +|If you want this component to only run on specific nodes, you can use this parameter to configure a node selector. + +|=== + +[id="scanner-settings_{context}"] +== StackRox Scanner settings for the Operator + +[cols="1,3"] +|=== +| Parameter | Description + +| `scanner.analyzer.nodeSelector` +| If you want this scanner to only run on specific nodes, you can use this parameter to configure a node selector. + +| `scanner.analyzer.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the StackRox Scanner. This parameter is mainly used for infrastructure nodes. + +| `scanner.analyzer.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `scanner.analyzer.resources.limits` +| Use this parameter to override the default resource limits for the StackRox Scanner. + +| `scanner.analyzer.resources.requests` +| Use this parameter to override the default resource requests for the StackRox Scanner. + +| `scanner.analyzer.scaling.autoScaling` +| When enabled, the number of analyzer replicas is managed dynamically based on the load, within the limits specified. + +| `scanner.analyzer.scaling.maxReplicas` +| Specifies the maximum replicas to be used in the analyzer autoscaling configuration + +| `scanner.analyzer.scaling.minReplicas` +| Specifies the minimum replicas to be used in the analyzer autoscaling configuration + +| `scanner.analyzer.scaling.replicas` +| When autoscaling is disabled, the number of replicas is always configured to match this value. + +| `scanner.db.nodeSelector` +| If you want this component to only run on specific nodes, you can use this parameter to configure a node selector. + +| `scanner.db.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the StackRox Scanner DB. This parameter is mainly used for infrastructure nodes. + +| `scanner.db.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `scanner.db.resources.limits` +| Use this parameter to override the default resource limits for the StackRox Scanner DB. + +| `scanner.db.resources.requests` +| Use this parameter to override the default resource requests for the StackRox Scanner DB. + +|`scanner.monitoring.exposeEndpoint` +|Use `Enabled` to enable monitoring for the StackRox Scanner. When you enable monitoring, {product-title-short} creates a new monitoring service on port number `9090`. The default value is `Disabled`. + +| `scanner.scannerComponent` +| If you do not want to deploy the StackRox Scanner, you can disable it by using this parameter. If you disable the StackRox Scanner, all other settings in this section have no effect. + +|=== + +[id="scannerv4-settings_{context}"] +== Scanner V4 settings for the Operator + +[cols="1,3"] +|=== +| Parameter | Description + +| `scannerV4.db.nodeSelector` +| If you want this component to only run on specific nodes, you can use this parameter to configure a node selector. + +| `scannerV4.db.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner V4 DB. This parameter is mainly used for infrastructure nodes. + +| `scannerV4.db.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `scannerV4.db.resources.limits` +| Use this parameter to override the default resource limits for Scanner V4 DB. + +| `scannerV4.db.resources.requests` +| Use this parameter to override the default resource requests for Scanner V4 DB. + +| `scannerV4.db.persistence.persistentVolumeClaim.claimName` +| The name of the PVC to manage persistent data for Scanner V4. +The default value is `scanner-v4-db`. + +| `scannerV4.db.persistence.persistentVolumeClaim.size` +| The size of the PVC to manage persistent data for Scanner V4. + +| `scannerV4.db.persistence.persistentVolumeClaim.storageClassName` +| The name of the storage class to use for the PVC. If your cluster is not configured with a default storage class, you must provide a value for this parameter. + +| `scannerV4.indexer.nodeSelector` +| If you want this component to only run on specific nodes, you can use this parameter to configure a node selector. + +| `scannerV4.indexer.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the Scanner V4 Indexer. This parameter is mainly used for infrastructure nodes. + +| `scannerV4.indexer.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `scannerV4.indexer.resources.limits` +| Use this parameter to override the default resource limits for the Scanner V4 Indexer. + +| `scannerV4.indexer.resources.requests` +| Use this parameter to override the default resource requests for the Scanner V4 Indexer. + +| `scannerV4.indexer.scaling.autoScaling` +| When enabled, the number of Scanner V4 Indexer replicas is managed dynamically based on the load, within the limits specified. + +| `scannerV4.indexer.scaling.maxReplicas` +| Specifies the maximum replicas to be used in the Scanner V4 Indexer autoscaling configuration. + +| `scannerV4.indexer.scaling.minReplicas` +| Specifies the minimum replicas to be used in the Scanner V4 Indexer autoscaling configuration. + +| `scannerV4.indexer.scaling.replicas` +| When autoscaling is disabled for the Scanner V4 Indexer, the number of replicas is always configured to match this value. + +| `scannerV4.matcher.nodeSelector` +| If you want this component to only run on specific nodes, you can use this parameter to configure a node selector. + +| `scannerV4.matcher.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the Scanner V4 Matcher. This parameter is mainly used for infrastructure nodes. + +| `scannerV4.matcher.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `scannerV4.matcher.resources.limits` +| Use this parameter to override the default resource limits for the Scanner V4 Matcher. + +| `scannerV4.matcher.resources.requests` +| Use this parameter to override the default resource requests for the Scanner V4 Matcher. + +| `scannerV4.matcher.scaling.autoScaling` +| When enabled, the number of Scanner V4 Matcher replicas is managed dynamically based on the load, within the limits specified. + +| `scannerV4.matcher.scaling.maxReplicas` +| Specifies the maximum replicas to be used in the Scanner V4 Matcher autoscaling configuration. + +| `scannerV4.matcher.scaling.minReplicas` +| Specifies the minimum replicas to be used in the Scanner V4 Matcher autoscaling configuration. + +| `scannerV4.matcher.scaling.replicas` +| When autoscaling is disabled for the Scanner V4 Matcher, the number of replicas is always configured to match this value. + +| `scannerV4.monitoring.exposeEndpoint` +| Configures a monitoring endpoint for Scanner V4. The monitoring endpoint allows other services to collect metrics from Scanner V4, provided in a Prometheus-compatible format. Use `Enabled` to expose the monitoring endpoint. When you enable monitoring, {product-title-short} creates a new service, `monitoring`, with port 9090, and a network policy allowing inbound connections to the port. By default, this is not enabled. + +| `scannerV4.scannerComponent` +| If this setting is not specified, Scanner V4 is enabled for new installations, by default. For updates from an earlier release, Scanner V4 will not be enabled in the upgrade by default, if it was not previously enabled. To disable Scanner V4, set to `Disabled`. Disabling Scanner V4 negatively impacts the ability of {product-title-short} to provide thorough and accurate scanning results. + +|=== + + +[id="general-and-miscellaneous-settings_{context}"] +== General and miscellaneous settings + +[cols="1,3"] +|=== +| Parameter | Description + +| `customize.annotations` +| Allows specifying custom annotations for the Central deployment. + +| `customize.envVars` +| Advanced settings to configure environment variables. + +| `egress.connectivityPolicy` + +| Configures whether {product-title-short} should run in online or offline mode. In offline mode, automatic updates of vulnerability definitions and kernel modules are disabled. + +| `misc.createSCCs` +| Specify `true` to create `SecurityContextConstraints` (SCCs) for Central. +Setting to `true` might cause issues in some environments. + +| `monitoring.openshift.enabled` +| If you set this option to `false`, {product-title} will not set up {osp} monitoring. Defaults to `true` on {osp} 4. + +|`network.policies` +a| To provide security at the network level, {product-title-short} creates default `NetworkPolicy` resources in the namespace where Central is installed. These network policies allow ingress to specific components on specific ports. If you do not want {product-title-short} to create these policies, set this parameter to `Disabled`. The default value is `Enabled`. + +[WARNING] +==== +Disabling creation of default network policies can break communication between {product-title-short} components. If you disable creation of default policies, you must create your own network policies to allow this communication. +==== + +| `overlays` +| See "Customizing the installation using the Operator with overlays". + +| `tls.additionalCAs` +| Additional Trusted CA certificates for the secured cluster to trust. +These certificates are typically used when integrating with services using a private certificate authority. + +|=== diff --git a/modules/central-services-private-config.adoc b/modules/central-services-private-config.adoc new file mode 100644 index 000000000000..1044f2f4aabc --- /dev/null +++ b/modules/central-services-private-config.adoc @@ -0,0 +1,213 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +:_mod-docs-content-type: CONCEPT +[id="central-services-private-configuration-file_{context}"] += Private configuration file + +This section lists the configurable parameters of the `values-private.yaml` file. +There are no default values for these parameters. + +[id="central-services-private-configuration-file-image-pull-secrets_{context}"] +== Image pull secrets +The credentials that are required for pulling images from the registry depend on the following factors: + +* If you are using a custom registry, you must specify these parameters: +** `imagePullSecrets.username` +** `imagePullSecrets.password` +** `image.registry` + +* If you do not use a username and password to log in to the custom registry, you must specify one of the following parameters: +** `imagePullSecrets.allowNone` +** `imagePullSecrets.useExisting` +** `imagePullSecrets.useFromDefaultServiceAccount` + +[cols="1,3",options="header"] +|=== +| Parameter | Description + +| `imagePullSecrets.username` +| The username of the account that is used to log in to the registry. + +| `imagePullSecrets.password` +| The password of the account that is used to log in to the registry. + +| `imagePullSecrets.allowNone` +| Use `true` if you are using a custom registry and it allows pulling images without credentials. + +| `imagePullSecrets.useExisting` +| A comma-separated list of secrets as values. +For example, `secret1, secret2, secretN`. Use this option if you have already created pre-existing image pull secrets with the given name in the target namespace. + +| `imagePullSecrets.useFromDefaultServiceAccount` +| Use `true` if you have already configured the default service account in the target namespace with sufficiently scoped image pull secrets. +|=== + +[id="central-services-private-configuration-file-proxy-config_{context}"] +== Proxy configuration + +If you are installing {product-title} in a cluster that requires a proxy to connect to external services, you must specify your proxy configuration by using the `proxyConfig` parameter. +For example: + +[source,yaml] +---- +env: + proxyConfig: | + url: http://proxy.name:port + username: username + password: password + excludes: + - some.domain +---- + +|=== +| Parameter | Description + +| `env.proxyConfig` +| Your proxy configuration. +|=== + +[id="central-services-private-configuration-file-central_{context}"] +== Central +Configurable parameters for Central. + +For a new installation, you can skip the following parameters: + +* `central.jwtSigner.key` +* `central.serviceTLS.cert` +* `central.serviceTLS.key` +* `central.adminPassword.value` +* `central.adminPassword.htpasswd` +* `central.db.serviceTLS.cert` +* `central.db.serviceTLS.key` +* `central.db.password.value` + +* When you do not specify values for these parameters the Helm chart autogenerates values for them. +* If you want to modify these values you can use the `helm upgrade` command and specify the values using the `--set` option. + +[IMPORTANT] +==== +For setting the administrator password, you can only use either `central.adminPassword.value` or `central.adminPassword.htpasswd`, but not both. +==== + +[cols="1,3",options="header"] +|=== +| Parameter | Description + +| `central.jwtSigner.key` +| A private key which {product-title-short} should use for signing JSON web tokens (JWTs) for authentication. + +| `central.serviceTLS.cert` +| An internal certificate that the Central service should use for deploying Central. + +| `central.serviceTLS.key` +| The private key of the internal certificate that the Central service should use. + +| `central.defaultTLS.cert` +a| The user-facing certificate that Central should use. {product-title-short} uses this certificate for {product-title-short} portal. + +* For a new installation, you must provide a certificate, otherwise, {product-title-short} installs Central by using a self-signed certificate. +* If you are upgrading, {product-title-short} uses the existing certificate and its key. + +| `central.defaultTLS.key` +a| The private key of the user-facing certificate that Central should use. + +* For a new installation, you must provide the private key, otherwise, {product-title-short} installs Central by using a self-signed certificate. +* If you are upgrading, {product-title-short} uses the existing certificate and its key. + +| `central.db.password.value` +| Connection password for Central database. + +| `central.adminPassword.value` +| Administrator password for logging into {product-title-short}. + +| `central.adminPassword.htpasswd` +| Administrator password for logging into {product-title-short}. +This password is stored in hashed format using bcrypt. + +| `central.db.serviceTLS.cert` +| An internal certificate that the Central DB service should use for deploying Central DB. + +| `central.db.serviceTLS.key` +| The private key of the internal certificate that the Central DB service should use. + +| `central.db.password.value` +| The password used to connect to the Central DB. + +|=== + +[NOTE] +==== +If you are using `central.adminPassword.htpasswd` parameter, you must use a bcrypt encoded password hash. +You can run the command `htpasswd -nB admin` to generate a password hash. +For example, + +[source,yaml] +---- +htpasswd: | + admin: +---- +==== + +[id="central-services-private-configuration-file-scanner_{context}"] +== Scanner +Configurable parameters for the StackRox Scanner and Scanner V4. + +For a new installation, you can skip the following parameters and the Helm chart autogenerates values for them. +Otherwise, if you are upgrading to a new version, specify the values for the following parameters: + +* `scanner.dbPassword.value` +* `scanner.serviceTLS.cert` +* `scanner.serviceTLS.key` +* `scanner.dbServiceTLS.cert` +* `scanner.dbServiceTLS.key` +* `scannerV4.db.password.value` +* `scannerV4.indexer.serviceTLS.cert` +* `scannerV4.indexer.serviceTLS.key` +* `scannerV4.matcher.serviceTLS.cert` +* `scannerV4.matcher.serviceTLS.key` +* `scannerV4.db.serviceTLS.cert` +* `scannerV4.db.serviceTLS.key` + +[cols="1,3",options="header"] +|=== +| Parameter | Description + +| `scanner.dbPassword.value` +| The password to use for authentication with Scanner database. +Do not modify this parameter because {product-title-short} automatically creates and uses its value internally. + +| `scanner.serviceTLS.cert` +| An internal certificate that the StackRox Scanner service should use for deploying the StackRox Scanner. + +| `scanner.serviceTLS.key` +| The private key of the internal certificate that the Scanner service should use. + +| `scanner.dbServiceTLS.cert` +| An internal certificate that the Scanner-db service should use for deploying Scanner database. + +| `scanner.dbServiceTLS.key` +| The private key of the internal certificate that the Scanner-db service should use. + +| `scannerV4.db.password.value` +| The password to use for authentication with the Scanner V4 database. Do not modify this parameter because {product-title-short} automatically creates and uses its value internally. + +| `scannerV4.db.serviceTLS.cert` +| An internal certificate that the Scanner V4 DB service should use for deploying the Scanner V4 database. + +| `scannerV4.db.serviceTLS.key` +| The private key of the internal certificate that the Scanner V4 DB service should use. + +| `scannerV4.indexer.serviceTLS.cert` +| An internal certificate that the Scanner V4 service should use for deploying the Scanner V4 Indexer. + +| `scannerV4.indexer.serviceTLS.key` +| The private key of the internal certificate that the Scanner V4 Indexer should use. + +| `scannerV4.matcher.serviceTLS.cert` +| An internal certificate that the Scanner V4 service should use for deploying the the Scanner V4 Matcher. + +| `scannerV4.matcher.serviceTLS.key` +| The private key of the internal certificate that the Scanner V4 Matcher should use. + +|=== diff --git a/modules/central-services-public-config.adoc b/modules/central-services-public-config.adoc new file mode 100644 index 000000000000..33aa1f2eaab0 --- /dev/null +++ b/modules/central-services-public-config.adoc @@ -0,0 +1,640 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +// * installing/installing_ocp/install-central-ocp.adoc +// * installing/installing_other/install-central-other.adoc + +:_mod-docs-content-type: CONCEPT +[id="central-services-public-configuration-file_{context}"] += Public configuration file +This section lists the configurable parameters of the `values-public.yaml` file. + +[id="central-services-public-configuration-file-image-pull-secrets_{context}"] +== Image pull secrets +Image pull secrets are the credentials required for pulling images from your registry. + +|=== +| Parameter | Description + +| `imagePullSecrets.allowNone` +| Use `true` if you are using a custom registry and it allows pulling images without credentials. + +| `imagePullSecrets.useExisting` +| A comma-separated list of secrets as values. +For example, `secret1, secret2`. +Use this option if you have already created pre-existing image pull secrets with the given name in the target namespace. + +| `imagePullSecrets.useFromDefaultServiceAccount` +| Use `true` if you have already configured the default service account in the target namespace with sufficiently scoped image pull secrets. +|=== + +[id="central-services-public-configuration-file-image_{context}"] +== Image +Image declares the configuration to set up the main registry, which the Helm chart uses to resolve images for the `central.image`, `scanner.image`, `scanner.dbImage`, `scannerV4.image`, and `scannerV4.db.image` parameters. + +|=== +| Parameter | Description + +| `image.registry` +| Address of your image registry. +Either use a hostname, such as `registry.redhat.io`, or a remote registry hostname, such as `us.gcr.io/stackrox-mirror`. +|=== + +[id="central-services-public-configuration-file-config-as-code_{context}"] +== Policy as code + +Policy as code provides a way to configure {product-title-short} to work with a continuous delivery tool such as Argo CD to track, manage, and apply policies that you have authored locally or exported from the {product-title-short} portal and modified. You configure Argo CD or your other tool to apply policy as code resources to the same namespace in which {product-title-short} is installed. + +|=== +| Parameter | Description + +| `configAsCode.enabled` +| By default, the value is `true` so that policy as code is enabled. Set to `false` to disable the policy as code feature. + +|=== + +[id="central-services-public-configuration-file-environment-variables_{context}"] +== Environment variables +{product-title} automatically detects your cluster environment and sets values for `env.openshift`, `env.istio`, and `env.platform`. +Only set these values to override the automatic cluster environment detection. + +|=== +| Parameter | Description + +| `env.openshift` +| Use `true` for installing on an {ocp} cluster and overriding automatic cluster environment detection. + +| `env.istio` +| Use `true` for installing on an Istio enabled cluster and overriding automatic cluster environment detection. + +| `env.platform` +| The platform on which you are installing {product-title-short}. +Set its value to `default` or `gke` to specify cluster platform and override automatic cluster environment detection. + +| `env.offlineMode` +| Use `true` to use {product-title-short} in offline mode. +//TODO: Add link to offline mode. + +| `env.grpcEnforceALPN` +| Use `true` to force application-level protocol negotiation (ALPN) during the TLS handshake. +|=== + +[id="additional-trusted-certificate-authorities_{context}"] +== Additional trusted certificate authorities +The {product-title-short} automatically references the system root certificates to trust. +When Central, the StackRox Scanner, or Scanner V4 must reach out to services that use certificates issued by an authority in your organization or a globally trusted partner organization, you can add trust for these services by specifying the root certificate authority to trust by using the following parameter: + +|=== +| Parameter | Description + +| `additionalCAs.` +| Specify the PEM encoded certificate of the root certificate authority to trust. + +|=== + +[id="default-network-policy-creation_{context}"] +== Default network policies + +To provide security at the network level, {product-title-short} creates default `NetworkPolicy` resources in the namespace where Central is installed. These network policies allow ingress to specific components on specific ports. If you do not want {product-title-short} to create these policies, set this parameter to `Disabled`. The default value is `Enabled`. + +[WARNING] +==== +Disabling creation of default network policies can break communication between {product-title-short} components. If you disable creation of default policies, you must create your own network policies to allow this communication. +==== + +|=== +| Parameter | Description + +|`network.enableNetworkPolicies` +| Specify if {product-title-short} creates default network policies to allow communication between components. To create your own network policies, set this parameter to `False`. The default value is `True`. + +|=== + +[id="central-services-public-configuration-file-central_{context}"] +== Central +Configurable parameters for Central. + +* For exposing Central deployment for external access. +You must specify one parameter, either `central.exposure.loadBalancer`, `central.exposure.nodePort`, or `central.exposure.route`. +When you do not specify any value for these parameters, you must manually expose Central or access it by using port-forwarding. + +The following table includes settings for an external PostgreSQL database. + +|=== +| Parameter | Description + +|`central.declarativeConfiguration.mounts.configMaps` +| Mounts config maps used for declarative configurations. + +|`Central.declarativeConfiguration.mounts.secrets` +| Mounts secrets used for declarative configurations. + +| `central.endpointsConfig` +| The endpoint configuration options for Central. + +| `central.nodeSelector` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Central. This parameter is mainly used for infrastructure nodes. + +| `central.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Central. This parameter is mainly used for infrastructure nodes. + +| `central.exposeMonitoring` +| Specify `true` to expose Prometheus metrics endpoint for Central on port number `9090`. + +| `central.image.registry` +| A custom registry that overrides the global `image.registry` parameter for the Central image. + +| `central.image.name` +| The custom image name that overrides the default Central image name (`main`). + +| `central.image.tag` +| The custom image tag that overrides the default tag for Central image. +If you specify your own image tag during a new installation, you must manually increment this tag when you to upgrade to a new version by running the `helm upgrade` command. +If you mirror Central images in your own registry, do not modify the original image tags. + +| `central.image.fullRef` +| Full reference including registry address, image name, and image tag for the Central image. +Setting a value for this parameter overrides the `central.image.registry`, `central.image.name`, and `central.image.tag` parameters. + +| `central.resources.requests.memory` +| The memory request for Central. + +| `central.resources.requests.cpu` +| The CPU request for Central. + +| `central.resources.limits.memory` +| The memory limit for Central. + +| `central.resources.limits.cpu` +| The CPU limit for Central. + +| `central.exposure.loadBalancer.enabled` +| Use `true` to expose Central by using a load balancer. + +| `central.exposure.loadBalancer.port` +| The port number on which to expose Central. +The default port number is 443. + +| `central.exposure.nodePort.enabled` +| Use `true` to expose Central by using the node port service. + +| `central.exposure.nodePort.port` +| The port number on which to expose Central. +When you skip this parameter, {ocp} automatically assigns a port number. +Red{nbsp}Hat recommends that you do not specify a port number if you are exposing {product-title-short} by using a node port. + +| `central.exposure.route.enabled` +| Use `true` to expose Central by using a route. +Disables all route settings if set to `false`. +This parameter is only available for {ocp} clusters. + +| `central.exposure.route.host` +| Use this parameter to specify a custom hostname to use for Central's passthrough route. +Leave this unset to accept the default value that {ocp} provides. +This parameter is only available for {ocp} clusters. + +| `central.exposure.route.reencrypt.enabled` +| Set this to `true` to expose Central through a {osp} reencrypt route. +The default value is `false`. +This parameter is only available for {ocp} clusters. + +| `central.exposure.route.reencrypt.host` +| Use this parameter to specify a custom hostname to use for Central's reencrypt route. +Leave this unset to accept the default value that {ocp} provides. +This parameter is only available for {ocp} clusters. + +| `central.exposure.route.reencrypt.tls.caCertificate` +| Use this parameter to specify a PEM-encoded certificate chain that might be used to establish a complete chain of trust. +By default, {ocp} provides the certificate authority. +This parameter is only available for {ocp} clusters. + +| `central.exposure.route.reencrypt.tls.certificate` +| Use this parameter to specify the PEM-encoded certificate that is served on the route. The {ocp} certificate authority signs the default certificate. +This parameter is only available for {ocp} clusters. + +| `central.exposure.route.reencrypt.tls.destinationCACertificate` +| Use this parameter to specify the CA certificate of the final destination, that is of Central. +The {ocp} router uses this certificate to perform health checks on the secure connection. By default, Central provides the certificate authority. + +| `central.exposure.route.reencrypt.tls.key` +| Use this parameter to specify the PEM-encoded private key of the certificate that is served on the route. +The {ocp} certificate authority signs the default certificate. +This parameter is only available for {ocp} clusters. + +| `central.db.external` +| Use `true` to specify that Central DB should not be deployed and that an external database will be used. + +| `central.db.source.connectionString` +a| The connection string for Central to use to connect to the database. This is only used when `central.db.external` is set to true. The connection string must be in keyword/value format as described in the PostgreSQL documentation in "Additional resources". + +* Postgres 15 is the recommended and supported version. Red{nbsp}Hat has deprecated the support for Postgres 13 and will remove it in the newer versions of {product-title-short}. +* Connections through PgBouncer are not supported. +* User must be superuser with ability to create and delete databases. + +| `central.db.source.minConns` +| The minimum number of connections to the database to be established. + +| `central.db.source.maxConns` +| The maximum number of connections to the database to be established. + +| `central.db.source.statementTimeoutMs` +| The number of milliseconds a single query or transaction can be active against the database. + +| `central.db.postgresConfig` +| The postgresql.conf to be used for Central DB as described in the PostgreSQL documentation in "Additional resources". + +| `central.db.hbaConfig` +| The pg_hba.conf to be used for Central DB as described in the PostgreSQL documentation in "Additional resources". + +| `central.db.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force Central DB to only schedule on nodes with the specified label. + +| `central.db.image.registry` +| A custom registry that overrides the global `image.registry` parameter for the Central DB image. + +| `central.db.image.name` +| The custom image name that overrides the default Central DB image name (`central-db`). + +| `central.db.image.tag` +| The custom image tag that overrides the default tag for Central DB image. +If you specify your own image tag during a new installation, you must manually increment this tag when you to upgrade to a new version by running the `helm upgrade` command. +If you mirror Central DB images in your own registry, do not modify the original image tags. + +| `central.db.image.fullRef` +| Full reference including registry address, image name, and image tag for the Central DB image. +Setting a value for this parameter overrides the `central.db.image.registry`, `central.db.image.name`, and `central.db.image.tag` parameters. + +| `central.db.resources.requests.memory` +| The memory request for Central DB. + +| `central.db.resources.requests.cpu` +| The CPU request for Central DB. + +| `central.db.resources.limits.memory` +| The memory limit for Central DB. + +| `central.db.resources.limits.cpu` +| The CPU limit for Central DB. + +| `central.db.persistence.hostPath` +| The path on the node where {product-title-short} should create a database volume. Red{nbsp}Hat does not recommend using this option. + +| `central.db.persistence.persistentVolumeClaim.claimName` +| The name of the persistent volume claim (PVC) you are using. + +| `central.db.persistence.persistentVolumeClaim.createClaim` +| Use `true` to create a new persistent volume claim, or `false` to use an existing claim. + +| `central.db.persistence.persistentVolumeClaim.size` +| The size (in GiB) of the persistent volume managed by the specified claim. + +|=== + +[id="central-services-public-configuration-file-scanner_{context}"] +== StackRox Scanner +The following table lists the configurable parameters for the StackRox Scanner. The StackRox Scanner is deprecated. + +|=== +| Parameter | Description + +| `scanner.disable` +| Use `true` to install {product-title-short} without the StackRox Scanner. +When you use it with the `helm upgrade` command, Helm removes the existing StackRox Scanner deployment. + +| `scanner.exposeMonitoring` +| Specify `true` to expose Prometheus metrics endpoint for the StackRox Scanner on port number `9090`. + +| `scanner.replicas` +| The number of replicas to create for the StackRox Scanner deployment. +When you use it with the `scanner.autoscaling` parameter, this value sets the initial number of replicas. + +| `scanner.logLevel` +| Configure the log level for the StackRox Scanner. +Red{nbsp}Hat recommends that you not change the default log level value (`INFO`). + +| `scanner.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force the StackRox Scanner to only schedule on nodes with the specified label. + +| `scanner.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the StackRox Scanner. This parameter is mainly used for infrastructure nodes. + +| `scanner.autoscaling.disable` +| Use `true` to disable autoscaling for the StackRox Scanner deployment. +When you disable autoscaling, the `minReplicas` and `maxReplicas` parameters do not have any effect. + +| `scanner.autoscaling.minReplicas` +| The minimum number of replicas for autoscaling. + +| `scanner.autoscaling.maxReplicas` +| The maximum number of replicas for autoscaling. + +| `scanner.resources.requests.memory` +| The memory request for the StackRox Scanner. + +| `scanner.resources.requests.cpu` +| The CPU request for the StackRox Scanner. + +| `scanner.resources.limits.memory` +| The memory limit for the StackRox Scanner. + +| `scanner.resources.limits.cpu` +| The CPU limit for the StackRox Scanner. + +| `scanner.dbResources.requests.memory` +| The memory request for the StackRox Scanner database deployment. + +| `scanner.dbResources.requests.cpu` +| The CPU request for the StackRox Scanner database deployment. + +| `scanner.dbResources.limits.memory` +| The memory limit for the StackRox Scanner database deployment. + +| `scanner.dbResources.limits.cpu` +| The CPU limit for the StackRox Scanner database deployment. + +| `scanner.image.registry` +| A custom registry for the StackRox Scanner image. + +| `scanner.image.name` +| The custom image name that overrides the default StackRox Scanner image name (`scanner`). + +| `scanner.dbImage.registry` +| A custom registry for the StackRox Scanner DB image. + +| `scanner.dbImage.name` +| The custom image name that overrides the default StackRox Scanner DB image name (`scanner-db`). + +| `scanner.dbNodeSelector` +| Specify a node selector label as `label-key: label-value` to force the StackRox Scanner DB to only schedule on nodes with the specified label. + +| `scanner.dbTolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the StackRox Scanner DB. This parameter is mainly used for infrastructure nodes. + +|=== + +[id="central-services-public-configuration-file-scannerv4_{context}"] +== Scanner V4 +The following table lists the configurable parameters for Scanner V4. + +|=== +| Parameter | Description + +| `scannerV4.db.persistence.persistentVolumeClaim.claimName` +| The name of the PVC to manage persistent data for Scanner V4. By default, for Central, the system creates a PVC and uses the default value of `scanner-v4-db` for the name. +| `scannerV4.db.persistence.persistentVolumeClaim.size` +| The size of the PVC to manage persistent data for Scanner V4. + +| `scannerV4.db.persistence.persistentVolumeClaim.storageClassName` +| The name of the storage class to use for the PVC. If your cluster is not configured with a default storage class, you must provide a value for this parameter. + +| `scannerV4.disable` +a| The following values are valid: + +* `true`: Scanner V4 is not deployed. + +* `false`: Scanner V4 is deployed. + +If no value is specified, the following behavior occurs by default: + +* New installations: Scanner V4 is deployed. + +* Upgrades from a release earlier than 4.8: Scanner V4 is not deployed. + +| `scannerV4.exposeMonitoring` +| Specify `true` to expose Prometheus metrics endpoint for Scanner V4 on port number `9090`. + +| `scannerV4.indexer.replicas` +| The number of replicas to create for the Scanner V4 Indexer deployment. +When you use it with the `scannerV4.indexer.autoscaling` parameter, this value sets the initial number of replicas. + +| `scannerV4.indexer.logLevel` +| Configure the log level for the Scanner V4 Indexer. +Red{nbsp}Hat recommends that you not change the default log level value (`INFO`). + +| `scannerV4.indexer.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force the Scanner V4 Indexer to only schedule on nodes with the specified label. + +| `scannerV4.indexer.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the Scanner V4 Indexer. This parameter is mainly used for infrastructure nodes. + +| `scannerV4.indexer.autoscaling.disable` +| Use `true` to disable autoscaling for the Scanner V4 Indexer deployment. +When you disable autoscaling, the `minReplicas` and `maxReplicas` parameters do not have any effect. + +| `scannerV4.indexer.autoscaling.minReplicas` +| The minimum number of replicas for autoscaling. + +| `scannerV4.indexer.autoscaling.maxReplicas` +| The maximum number of replicas for autoscaling. + +| `scannerV4.indexer.resources.requests.memory` +| The memory request for the Scanner V4 Indexer. + +| `scannerV4.indexer.resources.requests.cpu` +| The CPU request for the Scanner V4 Indexer. + +| `scannerV4.indexer.resources.limits.memory` +| The memory limit for the Scanner V4 Indexer. + +| `scannerV4.indexer.resources.limits.cpu` +| The CPU limit for the Scanner V4 Indexer. + +| `scannerV4.matcher.replicas` +| The number of replicas to create for the Scanner V4 Matcher deployment. +When you use it with the `scannerV4.matcher.autoscaling` parameter, this value sets the initial number of replicas. + +| `scannerV4.matcher.logLevel` +|Red{nbsp}Hat recommends that you not change the default log level value (`INFO`). + +| `scannerV4.matcher.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force the Scanner V4 Matcher to only schedule on nodes with the specified label. + +| `scannerV4.matcher.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the Scanner V4 Matcher. This parameter is mainly used for infrastructure nodes. + +| `scannerV4.matcher.autoscaling.disable` +| Use `true` to disable autoscaling for the Scanner V4 Matcher deployment. +When you disable autoscaling, the `minReplicas` and `maxReplicas` parameters do not have any effect. + +| `scannerV4.matcher.autoscaling.minReplicas` +| The minimum number of replicas for autoscaling. + +| `scannerV4.matcher.autoscaling.maxReplicas` +| The maximum number of replicas for autoscaling. + +| `scannerV4.matcher.resources.requests.memory` +| The memory request for the Scanner V4 Matcher. + +| `scannerV4.matcher.resources.requests.cpu` +| The CPU request for the Scanner V4 Matcher. + +| `scannerV4.db.resources.requests.memory` +| The memory request for the Scanner V4 database deployment. + +| `scannerV4.db.resources.requests.cpu` +| The CPU request for the Scanner V4 database deployment. + +| `scannerV4.db.resources.limits.memory` +| The memory limit for the Scanner V4 database deployment. + +| `scannerV4.db.resources.limits.cpu` +| The CPU limit for the Scanner V4 database deployment. + +| `scannerV4.db.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force the Scanner V4 DB to only schedule on nodes with the specified label. + +| `scannerV4.db.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the Scanner V4 DB. This parameter is mainly used for infrastructure nodes. + +| `scannerV4.db.image.registry` +| A custom registry for the Scanner V4 DB image. + +| `scannerV4.db.image.name` +| The custom image name that overrides the default Scanner V4 DB image name (`scanner-v4-db`). + +| `scannerV4.image.registry` +| A custom registry for the Scanner V4 image. + +| `scannerV4.image.name` +| The custom image name that overrides the default Scanner V4 image name (`scanner-v4`). + +|=== + +[id="central-services-public-configuration-file-customizations_{context}"] +== Customization +Use these parameters to specify additional attributes for all objects that {product-title-short} creates. + +|=== +| Parameter | Description + +| `customize.labels` +| A custom label to attach to all objects. + +| `customize.annotations` +| A custom annotation to attach to all objects. + +| `customize.podLabels` +| A custom label to attach to all deployments. + +| `customize.podAnnotations` +| A custom annotation to attach to all deployments. + +| `customize.envVars` +| A custom environment variable for all containers in all objects. + +| `customize.central.labels` +| A custom label to attach to all objects that Central creates. + +| `customize.central.annotations` +| A custom annotation to attach to all objects that Central creates. + +| `customize.central.podLabels` +| A custom label to attach to all Central deployments. + +| `customize.central.podAnnotations` +| A custom annotation to attach to all Central deployments. + +| `customize.central.envVars` +| A custom environment variable for all Central containers. + +| `customize.scanner.labels` +| A custom label to attach to all objects that Scanner creates. + +| `customize.scanner.annotations` +| A custom annotation to attach to all objects that Scanner creates. + +| `customize.scanner.podLabels` +| A custom label to attach to all Scanner deployments. + +| `customize.scanner.podAnnotations` +| A custom annotation to attach to all Scanner deployments. + +| `customize.scanner.envVars` +| A custom environment variable for all Scanner containers. + +| `customize.scanner-db.labels` +| A custom label to attach to all objects that Scanner DB creates. + +| `customize.scanner-db.annotations` +| A custom annotation to attach to all objects that Scanner DB creates. + +| `customize.scanner-db.podLabels` +| A custom label to attach to all Scanner DB deployments. + +| `customize.scanner-db.podAnnotations` +| A custom annotation to attach to all Scanner DB deployments. + +| `customize.scanner-db.envVars` +| A custom environment variable for all Scanner DB containers. + +| `customize.scanner-v4-indexer.labels` +| A custom label to attach to all objects that Scanner V4 Indexer creates and into the pods belonging to them. + +| `customize.scanner-v4-indexer.annotations` +| A custom annotation to attach to all objects that Scanner V4 Indexer creates and into the pods belonging to them. + +| `customize.scanner-v4-indexer.podLabels` +| A custom label to attach to all objects that Scanner V4 Indexer creates and into the pods belonging to them. + +| `customize.scanner-v4-indexer.podAnnotations` +| A custom annotation to attach to all objects that Scanner V4 Indexer creates and into the pods belonging to them. + +| `customize.scanner-4v-indexer.envVars` +| A custom environment variable for all Scanner V4 Indexer containers and the pods belonging to them. + +| `customize.scanner-v4-matcher.labels` +| A custom label to attach to all objects that Scanner V4 Matcher creates and into the pods belonging to them. + +| `customize.scanner-v4-matcher.annotations` +| A custom annotation to attach to all objects that Scanner V4 Matcher creates and into the pods belonging to them. + +| `customize.scanner-v4-matcher.podLabels` +| A custom label to attach to all objects that Scanner V4 Matcher creates and into the pods belonging to them. + +| `customize.scanner-v4-matcher.podAnnotations` +| A custom annotation to attach to all objects that Scanner V4 Matcher creates and into the pods belonging to them. + +| `customize.scanner-4v-matcher.envVars` +| A custom environment variable for all Scanner V4 Matcher containers and the pods belonging to them. + +| `customize.scanner-v4-db.labels` +| A custom label to attach to all objects that Scanner V4 DB creates and into the pods belonging to them. + +| `customize.scanner-v4-db.annotations` +| A custom annotation to attach to all objects that Scanner V4 DB creates and into the pods belonging to them. + +| `customize.scanner-v4-db.podLabels` +| A custom label to attach to all objects that Scanner V4 DB creates and into the pods belonging to them. + +| `customize.scanner-v4-db.podAnnotations` +| A custom annotation to attach to all objects that Scanner V4 DB creates and into the pods belonging to them. + +| `customize.scanner-4v-db.envVars` +| A custom environment variable for all Scanner V4 DB containers and the pods belonging to them. + + + +|=== + +You can also use: + +* the `customize.other.service/\*.labels` and the `customize.other.service/*.annotations` parameters, to specify labels and annotations for all objects. +* or, provide a specific service name, for example, `customize.other.service/central-loadbalancer.labels` and `customize.other.service/central-loadbalancer.annotations` as parameters and set their value. + +[id="central-services-public-configuration-file-advance-customization_{context}"] +== Advanced customization +[IMPORTANT] +==== +The parameters specified in this section are for information only. +Red{nbsp}Hat does not support {product-title-short} instances with modified namespace and release names. +==== + +|=== +| Parameter | Description + +| `allowNonstandardNamespace` +| Use `true` to deploy {product-title-short} into a namespace other than the default namespace `stackrox`. + +| `allowNonstandardReleaseName` +| Use `true` to deploy {product-title-short} with a release name other than the default `stackrox-central-services`. +|=== diff --git a/modules/certificate-injection-using-operators.adoc b/modules/certificate-injection-using-operators.adoc deleted file mode 100644 index b2dad4bbcbfe..000000000000 --- a/modules/certificate-injection-using-operators.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring-a-custom-pki.adoc - -[id="certificate-injection-using-operators_{context}"] -= Certificate injection using Operators - -Once your custom CA certificate is added to the cluster via ConfigMap, the -Cluster Network Operator merges the user-provided and system CA certificates -into a single bundle and injects the merged bundle into the Operator requesting -the trust bundle injection. - -Operators request this injection by creating an empty ConfigMap with the -following label: - -[source,yaml] ----- -config.openshift.io/inject-trusted-cabundle="true" ----- - -The Operator mounts this ConfigMap into the container's local trust store. - -[NOTE] -==== -Adding a trusted CA certificate is only needed if the certificate is not -included in the {op-system-first} trust bundle. -==== - -Certificate injection is not limited to Operators. The Cluster Network Operator -injects certificates across any namespace when an empty ConfigMap is created with the -`config.openshift.io/inject-trusted-cabundle=true` label. - -The ConfigMap can reside in any namespace, but the ConfigMap must be mounted as -a volume to each container within a Pod that requires a custom CA. For example: - -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: my-example-custom-ca-deployment - namespace: my-example-custom-ca-ns -spec: - ... - spec: - ... - containers: - - name: my-container-that-needs-custom-ca - volumeMounts: - - name: trusted-ca - mountPath: /etc/pki/ca-trust/extracted/pem - readOnly: true - volumes: - - name: trusted-ca - configMap: - name: trusted-ca - items: - - key: ca-bundle.crt <1> - path: tls-ca-bundle.pem <2> ----- -<1> `ca-bundle.crt` is required as the ConfigMap key. -<2> `tls-ca-bundle.pem` is required as the ConfigMap path. diff --git a/modules/change-collection-method.adoc b/modules/change-collection-method.adoc new file mode 100644 index 000000000000..c1128a0ce2ff --- /dev/null +++ b/modules/change-collection-method.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-operator.adoc +// * cloud_service/upgrade-cloudsvc-operator.adoc +:_mod-docs-content-type: PROCEDURE +[id="change-collection-method_{context}"] += Changing the collection method + +[role="_abstract"] +If the cluster that you are upgrading contains the `SecuredCluster` CR, you must ensure that the per node collection setting is set to `CORE_BPF` before you upgrade. + +.Procedure + +. In the {ocp} web console, go to the {product-title-short} Operator page. +. In the top navigation menu, select *Secured Cluster*. +. Click the instance name, for example, *stackrox-secured-cluster-services*. +. Use one of the following methods to change the setting: +* In the *Form view*, under *Per Node Settings* -> *Collector Settings* -> *Collection*, select *CORE_BPF*. +* Click *YAML* to open the YAML editor and locate the `spec.perNode.collector.collection` attribute. If the value is `KernelModule` or `EBPF`, then change it to `CORE_BPF`. +. Click *Save.* diff --git a/modules/change-config-options-after-deployment-central-service.adoc b/modules/change-config-options-after-deployment-central-service.adoc new file mode 100644 index 000000000000..c87ef3d5c829 --- /dev/null +++ b/modules/change-config-options-after-deployment-central-service.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +:_mod-docs-content-type: PROCEDURE +[id="change-config-options-after-deployment-central-services_{context}"] += Changing configuration options after deploying the central-services Helm chart + +You can make changes to any configuration options after you have deployed the `central-services` Helm chart. + +When using the `helm upgrade` command to make changes, the following guidelines and requirements apply: + +* You can also specify configuration values using the `--set` or `--set-file` parameters. +However, these options are not saved, and you must manually specify all the options again whenever you make changes. +* Some changes, such as enabling a new component, require new certificates to be issued for the component. Therefore, you must provide a CA when making these changes. +** If the CA was generated by the Helm chart during the initial installation, you must retrieve these automatically generated values from the cluster and provide them to the `helm upgrade` command. The post-installation notes of the `central-services` Helm chart include a command for retrieving the automatically generated values. +** If the CA was generated outside of the Helm chart and provided during the installation of the `central-services` chart, then you must perform that action again when using the `helm upgrade` command, for example, by using the `--reuse-values` flag with the `helm upgrade` command. + + +.Procedure + +. Update the `values-public.yaml` and `values-private.yaml` configuration files with new values. +. Run the `helm upgrade` command and specify the configuration files using the `-f` option: ++ +[source,terminal] +---- +$ helm upgrade -n stackrox \ + stackrox-central-services rhacs/central-services \ + --reuse-values \// <1> + -f \ + -f +---- +<1> If you have modified values that are not included in the `values_public.yaml` and `values_private.yaml` files, include the `--reuse-values` parameter. diff --git a/modules/change-config-options-after-deployment.adoc b/modules/change-config-options-after-deployment.adoc new file mode 100644 index 000000000000..7b3d47ff4093 --- /dev/null +++ b/modules/change-config-options-after-deployment.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +:_mod-docs-content-type: PROCEDURE +[id="change-config-options-after-deployment_{context}"] += Changing configuration options after deploying the secured-cluster-services Helm chart + +You can make changes to any configuration options after you have deployed the `secured-cluster-services` Helm chart. + +When using the `helm upgrade` command to make changes, the following guidelines and requirements apply: + +* You can also specify configuration values using the `--set` or `--set-file` parameters. +However, these options are not saved, and you must manually specify all the options again whenever you make changes. +* Some changes, such as enabling a new component, require new certificates to be issued for the component. Therefore, you must provide a CA when making these changes. +** If the CA was generated by the Helm chart during the initial installation, you must retrieve these automatically generated values from the cluster and provide them to the `helm upgrade` command. The post-installation notes of the `central-services` Helm chart include a command for retrieving the automatically generated values. +** If the CA was generated outside of the Helm chart and provided during the installation of the `central-services` chart, then you must perform that action again when using the `helm upgrade` command, for example, by using the `--reuse-values` flag with the `helm upgrade` command. + +.Procedure + +. Update the `values-public.yaml` and `values-private.yaml` configuration files with new values. +. Run the `helm upgrade` command and specify the configuration files using the `-f` option: ++ +[source,terminal] +---- +$ helm upgrade -n stackrox \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + --reuse-values \// <1> + -f \ + -f +---- +<1> If you have modified values that are not included in the `values_public.yaml` and `values_private.yaml` files, include the `--reuse-values` parameter. diff --git a/modules/changing-the-log-level.adoc b/modules/changing-the-log-level.adoc new file mode 100644 index 000000000000..fd0e8ff09ff6 --- /dev/null +++ b/modules/changing-the-log-level.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * cli/debugging-issues.adoc +:_mod-docs-content-type: PROCEDURE +[id="changing-the-log-level_{context}"] += Changing the log level + +.Procedure + +* Run the following command to change the log level: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl central debug log --level=__ <1> +---- +<1> The acceptable values for `` are `Panic`, `Fatal`, `Error`, `Warn`, `Info`, and `Debug`. \ No newline at end of file diff --git a/modules/check-for-existing-registry-integration.adoc b/modules/check-for-existing-registry-integration.adoc new file mode 100644 index 000000000000..7dc1c67f37c4 --- /dev/null +++ b/modules/check-for-existing-registry-integration.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +:_mod-docs-content-type: PROCEDURE +[id="check-for-existing-registry-integration_{context}"] += Checking for existing registry integration + +You can use the {product-title-short} portal to check if you have already integrated with a registry. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integration* section, look for highlighted *Registry* tiles. +The tiles also list the number of items already configured for that tile. + +If none of the Registry tiles are highlighted, you must first integrate with an image registry. diff --git a/modules/checking-cluster-resource-availability-and-utilization.adoc b/modules/checking-cluster-resource-availability-and-utilization.adoc deleted file mode 100644 index 53673c846c59..000000000000 --- a/modules/checking-cluster-resource-availability-and-utilization.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc - -[id="checking-cluster-resource-availability-and-utilization_{context}"] -= Checking cluster resource availability and utilization - -{product-title} provides a comprehensive set of monitoring dashboards that help you understand the state of cluster components. - -In the *Administrator* perspective, you can access dashboards for core {product-title} components, including: - -* etcd - -* Kubernetes compute resources - -* Kubernetes network resources - -* Prometheus - -* Dashboards relating to cluster and node performance - -.Example compute resources dashboard -image::monitoring-dashboard-compute-resources.png[] - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. In the *Administrator* perspective in the {product-title} web console, navigate to *Monitoring* -> *Dashboards*. - -. Choose a dashboard in the *Dashboard* list. Some dashboards, such as the *etcd* dashboard, produce additional sub-menus when selected. - -. Optional: Select a time range for the graphs in the *Time Range* list. - -. Optional: Select a *Refresh Interval*. - -. Hover over each of the graphs within a dashboard to display detailed information about specific items. - - diff --git a/modules/checking-deployment-yaml-files.adoc b/modules/checking-deployment-yaml-files.adoc new file mode 100644 index 000000000000..900a05009560 --- /dev/null +++ b/modules/checking-deployment-yaml-files.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// +// * cli/checking-policy-compliance.adoc +:_mod-docs-content-type: PROCEDURE +[id="checking-deployment-yaml-files_{context}"] += Checking deployment YAML files + +.Procedure + +* Run the following command to check the build-time and deploy-time violations of your security policies in YAML deployment files: ++ +[source,terminal] +---- +$ roxctl deployment check --file= \// <1> +--namespace= \// <2> +--cluster= \// <3> +--verbose <4> +---- ++ +-- +<1> For the ``, specify the YAML file with one or more deployments to send to Central for policy evaluation. +You can also specify multiple YAML files to send to Central for policy evaluation by using the `--file` flag, for example `--file=`, `--file=`, and so on. +<2> For the ``, specify a namespace to enhance deployments with context information such as network policies, role-based access controls (RBACs) and services for deployments that do not have a namespace in their specification. The namespace defined in the specification is not changed. The default value is `default`. +<3> For the ``, specify the cluster name or ID that you want to use as the context for the evaluation to enable extended deployments with cluster-specific information. +<4> By enabling the `--verbose` flag, you receive additional information for each deployment during the policy check. The extended information includes the RBAC permission level and a comprehensive list of network policies that is applied. ++ +[NOTE] +==== +You can see the additional information for each deployment in your JSON output, regardless of whether you enable the `--verbose` flag or not. +==== +-- ++ +The format is defined in the API reference. +To cause {rh-rhacs-first} to re-pull image metadata and image scan results from the associated registry and scanner, add the `--force` option. ++ +[NOTE] +==== +To check specific image scan results, you must have a token with both `read` and `write` permissions for the `Image` resource. +The default *Continuous Integration* system role already has the required permissions. +//TODO: Add link to the system role topic. +==== ++ +This command validates the following items: + +** Configuration options in a YAML file, such as resource limits or privilege options +** Aspects of the images used in a YAML file, such as components or vulnerabilities \ No newline at end of file diff --git a/modules/checking-file-intergrity-cr-status.adoc b/modules/checking-file-intergrity-cr-status.adoc deleted file mode 100644 index 9ebc311e883a..000000000000 --- a/modules/checking-file-intergrity-cr-status.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-understanding.adoc - -[id="checking-the-file-integrity-CR-status_{context}"] -= Checking the `FileIntegrity` custom resource status - -The `FileIntegrity` custom resource (CR) reports its status through the -.`status.phase` subresource. - -.Procedure - -. To query the `FileIntegrity` CR status, run: -+ -[source,terminal] ----- -$ oc get fileintegrities/worker-fileintegrity -o jsonpath="{ .status.phase }" ----- -+ -.Example output -[source,terminal] ----- -Active ----- diff --git a/modules/checking-image-scan-results.adoc b/modules/checking-image-scan-results.adoc new file mode 100644 index 000000000000..419478c6c4db --- /dev/null +++ b/modules/checking-image-scan-results.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * cli/checking-policy-compliance.adoc +:_mod-docs-content-type: PROCEDURE +[id="checking-image-scan-results_{context}"] += Checking image scan results + +You can also check the scan results for specific images. + +.Procedure + +* Run the following command to return the components and vulnerabilities found in the image in JSON format: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl image scan --image __ +---- ++ +The format is defined in the API reference. +To cause {rh-rhacs-first} to re-pull image metadata and image scan results from the associated registry and scanner, add the `--force` option. ++ +[NOTE] +==== +To check specific image scan results, you must have a token with both `read` and `write` permissions for the `Image` resource. +The default *Continuous Integration* system role already has the required permissions. +//TODO: Add link to the system role topic. +==== \ No newline at end of file diff --git a/modules/checking-images.adoc b/modules/checking-images.adoc new file mode 100644 index 000000000000..99e222b1d953 --- /dev/null +++ b/modules/checking-images.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * cli/checking-policy-compliance.adoc +:_mod-docs-content-type: PROCEDURE +[id="checking-images_{context}"] += Checking images + +.Procedure + +* Run the following command to check the build-time violations of your security policies in images: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl image check --image=__ +---- ++ +The format is defined in the API reference. +To cause {rh-rhacs-first} to re-pull image metadata and image scan results from the associated registry and scanner, add the `--force` option. ++ +[NOTE] +==== +To check specific image scan results, you must have a token with both `read` and `write` permissions for the `Image` resource. +The default *Continuous Integration* system role already has the required permissions. +//TODO: Add link to the system role topic. +==== \ No newline at end of file diff --git a/modules/checking-load-balancer-configuration.adoc b/modules/checking-load-balancer-configuration.adoc deleted file mode 100644 index b917d6cd0a33..000000000000 --- a/modules/checking-load-balancer-configuration.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="checking-load-balancer-configuration_{context}"] -= Checking a load balancer configuration before {product-title} installation - -Check your load balancer configuration prior to starting an {product-title} installation. - -.Prerequisites - -* You have configured an external load balancer of your choosing, in preparation for an {product-title} installation. The following example is based on a {op-system-base-full} host using HAProxy to provide load balancing services to a cluster. -* You have configured DNS in preparation for an {product-title} installation. -* You have SSH access to your load balancer. - -.Procedure - -. Check that the `haproxy` systemd service is active: -+ -[source,terminal] ----- -$ ssh @ systemctl status haproxy ----- - -. Verify that the load balancer is listening on the required ports. The following example references ports `80`, `443`, `6443`, and `22623`. -+ -* For HAProxy instances running on {op-system-base-full} 6, verify port status by using the `netstat` command: -+ -[source,terminal] ----- -$ ssh @ netstat -nltupe | grep -E ':80|:443|:6443|:22623' ----- -+ -* For HAProxy instances running on {op-system-base-full} 7 or 8, verify port status by using the `ss` command: -+ -[source,terminal] ----- -$ ssh @ ss -nltupe | grep -E ':80|:443|:6443|:22623' ----- -+ -[NOTE] -==== -Red Hat recommends the `ss` command instead of `netstat` in {op-system-base-full} 7 or later. `ss` is provided by the iproute package. For more information on the `ss` command, see the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-tool_reference-ss[{op-system-base-full} 7 Performance Tuning Guide]. -==== -+ -. Check that the wildcard DNS record resolves to the load balancer: -+ -[source,terminal] ----- -$ dig @ ----- diff --git a/modules/checking-mco-status.adoc b/modules/checking-mco-status.adoc deleted file mode 100644 index f119113f6905..000000000000 --- a/modules/checking-mco-status.adoc +++ /dev/null @@ -1,100 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="checking-mco-status_{context}"] -= Checking machine config pool status - -To see the status of the Machine Config Operator, its sub-components, and the resources it manages, use the following `oc` commands: - -.Procedure -. To see the number of MCO-managed nodes available on your cluster for each pool, type: -+ -[source,terminal] ----- -$ oc get machineconfigpool -NAME CONFIG UPDATED UPDATING DEGRADED MACHINECOUNT READYMACHINECOUNT UPDATEDMACHINECOUNT DEGRADEDMACHINECOUNT AGE -master rendered-master-dd… True False False 3 3 3 0 4h42m -worker rendered-worker-fde… True False False 3 3 3 0 4h42m ----- -+ -In the previous output, there are three master and three worker nodes. All machines are updated and none are currently updating. Because all nodes are `Updated` and `Ready` and none are `Degraded`, you can tell that there are no issues. - -. To see each existing `machineconfig`, type: -+ -[source,terminal] ----- -$ oc get machineconfigs -NAME GENERATEDBYCONTROLLER IGNITIONVERSION AGE -00-master 2c9371fbb673b97a6fe8b1c52... 3.1.0 5h18m -00-worker 2c9371fbb673b97a6fe8b1c52... 3.1.0 5h18m -01-master-container-runtime 2c9371fbb673b97a6fe8b1c52... 3.1.0 5h18m -01-master-kubelet 2c9371fbb673b97a6fe8b1c52… 3.1.0 5h18m -... -rendered-master-dde... 2c9371fbb673b97a6fe8b1c52... 3.1.0 5h18m -rendered-worker-fde... 2c9371fbb673b97a6fe8b1c52... 3.1.0 5h18m ----- -+ -Note that the `machineconfigs` listed as `rendered` are not meant to be changed or deleted. Expect them to be hidden at some point in the future. - -. Check the status of worker (or change to master) to see the status of that pool of nodes: -+ -[source,terminal] ----- -$ oc describe mcp worker -... - Degraded Machine Count: 0 - Machine Count: 3 - Observed Generation: 2 - Ready Machine Count: 3 - Unavailable Machine Count: 0 - Updated Machine Count: 3 -Events: ----- - -. You can view the contents of a particular machine config (in this case, `01-master-kubelet`). The trimmed output from the following `oc describe` command shows that this `machineconfig` contains both configuration files (`cloud.conf` and `kubelet.conf`) and a systemd service -(Kubernetes Kubelet): -+ -[source,terminal] ----- -$ oc describe machineconfigs 01-master-kubelet -Name: 01-master-kubelet -... -Spec: - Config: - Ignition: - Version: 3.1.0 - Storage: - Files: - Contents: - Source: data:, - Mode: 420 - Overwrite: true - Path: /etc/kubernetes/cloud.conf - Contents: - Source: data:,kind%3A%20KubeletConfiguration%0AapiVersion%3A%20kubelet.config.k8s.io%2Fv1beta1%0Aauthentication%3A%0A%20%20x509%3A%0A%20%20%20%20clientCAFile%3A%20%2Fetc%2Fkubernetes%2Fkubelet-ca.crt%0A%20%20anonymous... - Mode: 420 - Overwrite: true - Path: /etc/kubernetes/kubelet.conf - Systemd: - Units: - Contents: [Unit] -Description=Kubernetes Kubelet -Wants=rpc-statd.service network-online.target crio.service -After=network-online.target crio.service - -ExecStart=/usr/bin/hyperkube \ - kubelet \ - --config=/etc/kubernetes/kubelet.conf \ ... ----- - -If something goes wrong with a machine config that you apply, you can always back out that change. For example, if you had run `oc create -f ./myconfig.yaml` to apply a machine config, you could remove that machine config by typing: - -[source,terminal] ----- -$ oc delete -f ./myconfig.yaml ----- - -If that was the only problem, the nodes in the affected pool should return to a non-degraded state. This actually causes the rendered configuration to roll back to its previously rendered state. - -If you add your own machine configs to your cluster, you can use the commands shown in the previous example to check their status and the related status of the pool to which they are applied. diff --git a/modules/checking-project-status-using-the-CLI.adoc b/modules/checking-project-status-using-the-CLI.adoc deleted file mode 100644 index 36e3f7777692..000000000000 --- a/modules/checking-project-status-using-the-CLI.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="checking-project-status-using-the-CLI_{context}"] -= Checking project status using the CLI - -.Procedure - -. Run: -+ -[source,terminal] ----- -$ oc status ----- -+ -This command provides a high-level overview of the current project, with its -components and their relationships. diff --git a/modules/checking-project-status-using-the-web-console.adoc b/modules/checking-project-status-using-the-web-console.adoc deleted file mode 100644 index 2552af0e7040..000000000000 --- a/modules/checking-project-status-using-the-web-console.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="checking-project-status-using-the-web-console_{context}"] -= Checking project status using the web console - -.Procedure - -. Navigate to *Home* -> *Projects*. - -. Select a project to see its status. diff --git a/modules/checking-the-compliance-status-of-your-infrastructure.adoc b/modules/checking-the-compliance-status-of-your-infrastructure.adoc new file mode 100644 index 000000000000..728efe9ec2a1 --- /dev/null +++ b/modules/checking-the-compliance-status-of-your-infrastructure.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="checking-the-compliance-status-of-your-infrastructure_{context}"] += Checking the compliance status of your infrastructure + +By performing a compliance scan, you can check the compliance status of your entire infrastructure for all compliance standards. When you run a compliance scan, {rh-rhacs-first} creates a data snapshot of your environment. The data snapshot includes alerts, images, network policies, deployments, and related host-based data. + +Central collects the host-based data from Sensors running in your clusters. Central then collects further data from the compliance container running in each Collector pod. + +The compliance container collects the following data about your environment: + +* Configurations for the container daemon, container runtime and container image. +* Information about container networks. +* Command-line arguments and processes for the container runtime, Kubernetes, and {ocp}. +* Permissions for specific file paths. +* Configuration files for Kubernetes and {ocp} core services. +* After data collection is complete, Central checks the data to determine the results. You can view the results in the compliance dashboard and create compliance reports based on the results. + + +[NOTE] +==== +* The following terms are associated with a compliance scan: +Control:: Describes a single line item in an industry or regulatory standard that an auditor uses to evaluate an information system for compliance with that standard. {product-title-short} verifies evidence of compliance with a single control by performing one or more checks. +Check:: Is the single test performed during a single control assessment. +* Some controls have multiple checks associated with them. If one of the associated checks for a control fails, the entire control state is marked as Fail. +==== + +.Procedure + +. In the {product-title-short} portal, click *Compliance -> Dashboard*. +. Optional: By default, information on all standards is displayed in the compliance results. ++ +To display information about specific standards only, perform the following steps: + +.. Click *Manage standards*. +.. By default, all standards are selected. Clear the checkbox for any specific standard that you do not want to display. +.. Click *Save*. ++ +Standards that are not selected do not appear in the dashboard display, including the widgets, in the compliance results tables accessible from the dashboard, and in the PDF files created by using the *Export* button. However, when exporting the results as a CSV file, all default standards are included. + +. Click *Scan environment*. ++ +[NOTE] +==== +Scanning the entire environment takes about 2 minutes to complete. This time might vary depending on the number of clusters and nodes in your environment. +==== + +.Verification + +. In the {product-title-short} portal, click *Configuration Management*. +. In the *CIS Kubernetes v1.5* widget, click *Scan*. +. {product-title-short} displays a message which indicates that a compliance scan is in progress. diff --git a/modules/cli-about-cli.adoc b/modules/cli-about-cli.adoc deleted file mode 100644 index 7afbb8b1cb4b..000000000000 --- a/modules/cli-about-cli.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/getting-started.adoc - -[id="cli-about-cli_{context}"] -= About the OpenShift CLI - -With the OpenShift command-line interface (CLI), the `oc` command, you can create applications and manage {product-title} projects from a terminal. The OpenShift CLI is ideal in the following situations: - -* Working directly with project source code -* Scripting {product-title} operations -* Managing projects while restricted by bandwidth resources and the web console is unavailable diff --git a/modules/cli-administrator-cluster-management.adoc b/modules/cli-administrator-cluster-management.adoc deleted file mode 100644 index 5ced456748cb..000000000000 --- a/modules/cli-administrator-cluster-management.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/administrator-cli-commands.adoc - -[id="cli-cluster-management-commands_{context}"] -= Cluster management CLI commands - -== inspect - -Gather debugging information for a particular resource. - -[NOTE] -==== -This command is experimental and might change without notice. -==== - -.Example: Collect debugging data for the OpenShift API server cluster Operator -[source,terminal] ----- -$ oc adm inspect clusteroperator/openshift-apiserver ----- - -== must-gather - -Bulk collect data about the current state of your cluster to debug issues. - -[NOTE] -==== -This command is experimental and might change without notice. -==== - -.Example: Gather debugging information -[source,terminal] ----- -$ oc adm must-gather ----- - -== top - -Show usage statistics of resources on the server. - -.Example: Show CPU and memory usage for pods -[source,terminal] ----- -$ oc adm top pods ----- - -.Example: Show usage statistics for images -[source,terminal] ----- -$ oc adm top images ----- - -//// -== upgrade - -Upgrade the cluster to a newer version. - -.Example: Upgrade the cluster to version 4.1.1 -[source,terminal] ----- -$ oc adm upgrade --to=4.1.1 ----- -//// diff --git a/modules/cli-administrator-configuration.adoc b/modules/cli-administrator-configuration.adoc deleted file mode 100644 index 3b25d7f960d6..000000000000 --- a/modules/cli-administrator-configuration.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/administrator-cli-commands.adoc - -[id="cli-configuration-commands_{context}"] -= Configuration CLI commands - -== create-bootstrap-project-template - -Create a bootstrap project template. - -.Example: Output a bootstrap project template in YAML format to stdout -[source,terminal] ----- -$ oc adm create-bootstrap-project-template -o yaml ----- - -== create-error-template - -Create a template for customizing the error page. - -.Example: Output a template for the error page to stdout -[source,terminal] ----- -$ oc adm create-error-template ----- - -== create-kubeconfig - -Creates a basic `.kubeconfig` file from client certificates. - -.Example: Create a `.kubeconfig` file with the provided client certificates -[source,terminal] ----- -$ oc adm create-kubeconfig \ - --client-certificate=/path/to/client.crt \ - --client-key=/path/to/client.key \ - --certificate-authority=/path/to/ca.crt ----- - -== create-login-template - -Create a template for customizing the login page. - -.Example: Output a template for the login page to stdout -[source,terminal] ----- -$ oc adm create-login-template ----- - -== create-provider-selection-template - -Create a template for customizing the provider selection page. - -.Example: Output a template for the provider selection page to stdout -[source,terminal] ----- -$ oc adm create-provider-selection-template ----- diff --git a/modules/cli-administrator-maintenance.adoc b/modules/cli-administrator-maintenance.adoc deleted file mode 100644 index 14e2a7f25cf3..000000000000 --- a/modules/cli-administrator-maintenance.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/administrator-cli-commands.adoc - -[id="cli-maintenance-commands_{context}"] -= Maintenance CLI commands - -== migrate - -Migrate resources on the cluster to a new version or format depending on the -subcommand used. - -.Example: Perform an update of all stored objects -[source,terminal] ----- -$ oc adm migrate storage ----- - -.Example: Perform an update of only pods -[source,terminal] ----- -$ oc adm migrate storage --include=pods ----- - -== prune - -Remove older versions of resources from the server. - -.Example: Prune older builds including those whose build configs no longer exist -[source,terminal] ----- -$ oc adm prune builds --orphans ----- diff --git a/modules/cli-administrator-node-management.adoc b/modules/cli-administrator-node-management.adoc deleted file mode 100644 index bb3b7ab02ad0..000000000000 --- a/modules/cli-administrator-node-management.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/administrator-cli-commands.adoc - -[id="cli-node-management-commands_{context}"] -= Node management CLI commands - -== cordon - -Mark a node as unschedulable. Manually marking a node as unschedulable blocks -any new pods from being scheduled on the node, but does not affect existing pods -on the node. - -.Example: Mark `node1` as unschedulable -[source,terminal] ----- -$ oc adm cordon node1 ----- - -== drain - -Drain a node in preparation for maintenance. - -.Example: Drain `node1` -[source,terminal] ----- -$ oc adm drain node1 ----- - -== node-logs - -Display and filter node logs. - -.Example: Get logs for `NetworkManager` -[source,terminal] ----- -$ oc adm node-logs --role master -u NetworkManager.service ----- - -== taint - -Update the taints on one or more nodes. - -.Example: Add a taint to dedicate a node for a set of users -[source,terminal] ----- -$ oc adm taint nodes node1 dedicated=groupName:NoSchedule ----- - -.Example: Remove the taints with key `dedicated` from node `node1` -[source,terminal] ----- -$ oc adm taint nodes node1 dedicated- ----- - -== uncordon - -Mark a node as schedulable. - -.Example: Mark `node1` as schedulable -[source,terminal] ----- -$ oc adm uncordon node1 ----- diff --git a/modules/cli-administrator-other.adoc b/modules/cli-administrator-other.adoc deleted file mode 100644 index bde63eb5f25c..000000000000 --- a/modules/cli-administrator-other.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/administrator-cli-commands.adoc - -[id="cli-other-administrator-commands_{context}"] -= Other Administrator CLI commands - -== build-chain - -Output the inputs and dependencies of any builds. - -.Example: Output dependencies for the `perl` imagestream -[source,terminal] ----- -$ oc adm build-chain perl ----- - -== completion - -Output shell completion code for the `oc adm` commands for the specified shell. - -.Example: Display `oc adm` completion code for Bash -[source,terminal] ----- -$ oc adm completion bash ----- - -== config - -Manage the client configuration files. This command has the same behavior as the -`oc config` command. - -.Example: Display the current configuration -[source,terminal] ----- -$ oc adm config view ----- - -.Example: Switch to a different context -[source,terminal] ----- -$ oc adm config use-context test-context ----- - -== release - -Manage various aspects of the {product-title} release process, such as viewing information about a release or inspecting the contents of a release. - -.Example: Generate a changelog between two releases and save to `changelog.md` -[source,terminal] ----- -$ oc adm release info --changelog=/tmp/git \ - quay.io/openshift-release-dev/ocp-release:4.7.0-x86_64 \ - quay.io/openshift-release-dev/ocp-release:4.7.1-x86_64 \ - > changelog.md ----- - -== verify-image-signature - -Verify the image signature of an image imported to the internal registry using -the local public GPG key. - -.Example: Verify the `nodejs` image signature -[source,terminal] ----- -$ oc adm verify-image-signature \ - sha256:2bba968aedb7dd2aafe5fa8c7453f5ac36a0b9639f1bf5b03f95de325238b288 \ - --expected-identity 172.30.1.1:5000/openshift/nodejs:latest \ - --public-key /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release \ - --save ----- diff --git a/modules/cli-administrator-security-policy.adoc b/modules/cli-administrator-security-policy.adoc deleted file mode 100644 index 567f3f8fdbf7..000000000000 --- a/modules/cli-administrator-security-policy.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/administrator-cli-commands.adoc - -[id="cli-security-policy-commands_{context}"] -= Security and policy CLI commands - -== certificate - -Approve or reject certificate signing requests (CSRs). - -.Example: Approve a CSR -[source,terminal] ----- -$ oc adm certificate approve csr-sqgzp ----- - -== groups - -Manage groups in your cluster. - -.Example: Create a new group -[source,terminal] ----- -$ oc adm groups new my-group ----- - -== new-project - -Create a new project and specify administrative options. - -.Example: Create a new project using a node selector -[source,terminal] ----- -$ oc adm new-project myproject --node-selector='type=user-node,region=east' ----- - -== pod-network - -Manage pod networks in the cluster. - -.Example: Isolate `project1` and `project2` from other non-global projects -[source,terminal] ----- -$ oc adm pod-network isolate-projects project1 project2 ----- - -== policy - -Manage roles and policies on the cluster. - -.Example: Add the `edit` role to `user1` for all projects -[source,terminal] ----- -$ oc adm policy add-cluster-role-to-user edit user1 ----- - -.Example: Add the `privileged` security context constraint to a service account -[source,terminal] ----- -$ oc adm policy add-scc-to-user privileged -z myserviceaccount ----- diff --git a/modules/cli-authentication.adoc b/modules/cli-authentication.adoc new file mode 100644 index 000000000000..e5346642891a --- /dev/null +++ b/modules/cli-authentication.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * cli/getting-started-cli.adoc +:_mod-docs-content-type: PROCEDURE +[id="cli-authentication_{context}"] += Exporting and saving the API token + +//TODO: Add links to role based access control + +.Procedure + +. After you have generated the authentication token, export it as the `ROX_API_TOKEN` variable by entering the following command: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN= +---- +. (Optional): You can also save the token in a file and use it with the `--token-file` option by entering the following command: ++ +[source,terminal] +---- +$ roxctl central debug dump --token-file +---- + +Note the following guidelines: + +* You cannot use both the `-password` (`-p`) and the `--token-file` options simultaneously. +* If you have already set the `ROX_API_TOKEN` variable, and specify the `--token-file` option, the `roxctl` CLI uses the specified token file for authentication. +* If you have already set the `ROX_API_TOKEN` variable, and specify the `--password` option, the `roxctl` CLI uses the specified password for authentication. \ No newline at end of file diff --git a/modules/cli-configuring-completion.adoc b/modules/cli-configuring-completion.adoc deleted file mode 100644 index 95224d479148..000000000000 --- a/modules/cli-configuring-completion.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/configuring-cli.adoc - -[id="cli-enabling-tab-completion_{context}"] -= Enabling tab completion - -After you install the `oc` CLI tool, you can enable tab completion to -automatically complete `oc` commands or suggest options when you press Tab. - -.Prerequisites - -* You must have the `oc` CLI tool installed. - -.Procedure - -The following procedure enables tab completion for Bash. - -. Save the Bash completion code to a file. -+ -[source,terminal] ----- -$ oc completion bash > oc_bash_completion ----- - -. Copy the file to `/etc/bash_completion.d/`. -+ -[source,terminal] ----- -$ sudo cp oc_bash_completion /etc/bash_completion.d/ ----- -+ -You can also save the file to a local directory and source it from your -`.bashrc` file instead. - -Tab completion is enabled when you open a new terminal. diff --git a/modules/cli-developer-advanced.adoc b/modules/cli-developer-advanced.adoc deleted file mode 100644 index 0e7039bffbd2..000000000000 --- a/modules/cli-developer-advanced.adoc +++ /dev/null @@ -1,169 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/developer-cli-commands.adoc - -[id="cli-advanced-developer-commands_{context}"] -= Advanced developer CLI commands - -== api-resources - -Display the full list of API resources that the server supports. - -.Example: List the supported API resources -[source,terminal] ----- -$ oc api-resources ----- - -== api-versions - -Display the full list of API versions that the server supports. - -.Example: List the supported API versions -[source,terminal] ----- -$ oc api-versions ----- - -== auth - -Inspect permissions and reconcile RBAC roles. - -.Example: Check whether the current user can read pod logs -[source,terminal] ----- -$ oc auth can-i get pods --subresource=log ----- - -.Example: Reconcile RBAC roles and permissions from a file -[source,terminal] ----- -$ oc auth reconcile -f policy.json ----- - -== cluster-info - -Display the address of the master and cluster services. - -.Example: Display cluster information -[source,terminal] ----- -$ oc cluster-info ----- - -== convert - -Convert a YAML or JSON configuration file to a different API version and print -to standard output (stdout). - -.Example: Convert `pod.yaml` to the latest version -[source,terminal] ----- -$ oc convert -f pod.yaml ----- - -== extract - -Extract the contents of a config map or secret. Each key in the config map or -secret is created as a separate file with the name of the key. - -.Example: Download the contents of the `ruby-1-ca` config map to the current directory -[source,terminal] ----- -$ oc extract configmap/ruby-1-ca ----- - -.Example: Print the contents of the `ruby-1-ca` config map to stdout -[source,terminal] ----- -$ oc extract configmap/ruby-1-ca --to=- ----- - -== idle - -Idle scalable resources. An idled service will automatically become unidled when -it receives traffic or it can be manually unidled using the `oc scale` command. - -.Example: Idle the `ruby-app` service -[source,terminal] ----- -$ oc idle ruby-app ----- - -== image - -Manage images in your {product-title} cluster. - -.Example: Copy an image to another tag -[source,terminal] ----- -$ oc image mirror myregistry.com/myimage:latest myregistry.com/myimage:stable ----- - -== observe - -Observe changes to resources and take action on them. - -.Example: Observe changes to services -[source,terminal] ----- -$ oc observe services ----- - -== patch - -Updates one or more fields of an object using strategic merge patch in JSON or -YAML format. - -.Example: Update the `spec.unschedulable` field for node `node1` to `true` -[source,terminal] ----- -$ oc patch node/node1 -p '{"spec":{"unschedulable":true}}' ----- - -[NOTE] -==== -If you must patch a custom resource definition, you must include the -`--type merge` option in the command. -==== - -== policy - -Manage authorization policies. - -.Example: Add the `edit` role to `user1` for the current project -[source,terminal] ----- -$ oc policy add-role-to-user edit user1 ----- - -== process - -Process a template into a list of resources. - -.Example: Convert `template.json` to a resource list and pass to `oc create` -[source,terminal] ----- -$ oc process -f template.json | oc create -f - ----- - -== registry - -Manage the integrated registry on {product-title}. - -.Example: Display information about the integrated registry -[source,terminal] ----- -$ oc registry info ----- - -== replace - -Modify an existing object based on the contents of the specified configuration -file. - -.Example: Update a pod using the content in `pod.json` -[source,terminal] ----- -$ oc replace -f pod.json ----- diff --git a/modules/cli-developer-application-management.adoc b/modules/cli-developer-application-management.adoc deleted file mode 100644 index d4661069abe1..000000000000 --- a/modules/cli-developer-application-management.adoc +++ /dev/null @@ -1,191 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/developer-cli-commands.adoc - -[id="cli-application-management-commands_{context}"] -= Application management CLI commands - -== annotate - -Update the annotations on one or more resources. - -.Example: Add an annotation to a route -[source,terminal] ----- -$ oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist="192.168.1.10" ----- - -.Example: Remove the annotation from the route -[source,terminal] ----- -$ oc annotate route/test-route haproxy.router.openshift.io/ip_whitelist- ----- - -== apply - -Apply a configuration to a resource by file name or standard in (stdin) in JSON -or YAML format. - -.Example: Apply the configuration in `pod.json` to a pod -[source,terminal] ----- -$ oc apply -f pod.json ----- - -== autoscale - -Autoscale a deployment or replication controller. - -.Example: Autoscale to a minimum of two and maximum of five pods -[source,terminal] ----- -$ oc autoscale deploymentconfig/parksmap-katacoda --min=2 --max=5 ----- - -== create - -Create a resource by file name or standard in (stdin) in JSON or YAML format. - -.Example: Create a pod using the content in `pod.json` -[source,terminal] ----- -$ oc create -f pod.json ----- - -== delete - -Delete a resource. - -.Example: Delete a pod named `parksmap-katacoda-1-qfqz4` -[source,terminal] ----- -$ oc delete pod/parksmap-katacoda-1-qfqz4 ----- - -.Example: Delete all pods with the `app=parksmap-katacoda` label -[source,terminal] ----- -$ oc delete pods -l app=parksmap-katacoda ----- - -== describe - -Return detailed information about a specific object. - -.Example: Describe a deployment named `example` -[source,terminal] ----- -$ oc describe deployment/example ----- - -.Example: Describe all pods -[source,terminal] ----- -$ oc describe pods ----- - -== edit - -Edit a resource. - -.Example: Edit a deployment using the default editor -[source,terminal] ----- -$ oc edit deploymentconfig/parksmap-katacoda ----- - -.Example: Edit a deployment using a different editor -[source,terminal] ----- -$ OC_EDITOR="nano" oc edit deploymentconfig/parksmap-katacoda ----- - -.Example: Edit a deployment in JSON format -[source,terminal] ----- -$ oc edit deploymentconfig/parksmap-katacoda -o json ----- - -== expose - -Expose a service externally as a route. - -.Example: Expose a service -[source,terminal] ----- -$ oc expose service/parksmap-katacoda ----- - -.Example: Expose a service and specify the host name -[source,terminal] ----- -$ oc expose service/parksmap-katacoda --hostname=www.my-host.com ----- - -== get - -Display one or more resources. - -.Example: List pods in the `default` namespace -[source,terminal] ----- -$ oc get pods -n default ----- - -.Example: Get details about the `python` deployment in JSON format -[source,terminal] ----- -$ oc get deploymentconfig/python -o json ----- - -== label - -Update the labels on one or more resources. - -.Example: Update the `python-1-mz2rf` pod with the label `status` set to `unhealthy` -[source,terminal] ----- -$ oc label pod/python-1-mz2rf status=unhealthy ----- - -== scale - -Set the desired number of replicas for a replication controller or a -deployment. - -.Example: Scale the `ruby-app` deployment to three pods -[source,terminal] ----- -$ oc scale deploymentconfig/ruby-app --replicas=3 ----- - -== secrets - -Manage secrets in your project. - -.Example: Allow `my-pull-secret` to be used as an image pull secret by the `default` service account -[source,terminal] ----- -$ oc secrets link default my-pull-secret --for=pull ----- - -== serviceaccounts - -Get a token assigned to a service account or create a new token or `kubeconfig` -file for a service account. - -.Example: Get the token assigned to the `default` service account -[source,terminal] ----- -$ oc serviceaccounts get-token default ----- - -== set - -Configure existing application resources. - -.Example: Set the name of a secret on a build config -[source,terminal] ----- -$ oc set build-secret --source buildconfig/mybc mysecret ----- diff --git a/modules/cli-developer-basic.adoc b/modules/cli-developer-basic.adoc deleted file mode 100644 index 03fa81352c38..000000000000 --- a/modules/cli-developer-basic.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/developer-cli-commands.adoc - -[id="cli-basic-commands_{context}"] -= Basic CLI commands - -== explain - -Display documentation for a certain resource. - -.Example: Display documentation for pods -[source,terminal] ----- -$ oc explain pods ----- - -== login - -Log in to the {product-title} server and save login information for subsequent -use. - -.Example: Interactive login -[source,terminal] ----- -$ oc login ----- - -.Example: Log in specifying a user name -[source,terminal] ----- -$ oc login -u user1 ----- - -== new-app - -Create a new application by specifying source code, a template, or an image. - -.Example: Create a new application from a local Git repository -[source,terminal] ----- -$ oc new-app . ----- - -.Example: Create a new application from a remote Git repository -[source,terminal] ----- -$ oc new-app https://github.com/sclorg/cakephp-ex ----- - -.Example: Create a new application from a private remote repository -[source,terminal] ----- -$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret ----- - -== new-project - -Create a new project and switch to it as the default project in your -configuration. - -.Example: Create a new project -[source,terminal] ----- -$ oc new-project myproject ----- - -== project - -Switch to another project and make it the default in your configuration. - -.Example: Switch to a different project -[source,terminal] ----- -$ oc project test-project ----- - -== projects - -Display information about the current active project and existing projects on -the server. - -.Example: List all projects -[source,terminal] ----- -$ oc projects ----- - -== status - -Show a high-level overview of the current project. - -.Example: Show the status of the current project -[source,terminal] ----- -$ oc status ----- diff --git a/modules/cli-developer-build-deploy.adoc b/modules/cli-developer-build-deploy.adoc deleted file mode 100644 index 3b6b385b839c..000000000000 --- a/modules/cli-developer-build-deploy.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/developer-cli-commands.adoc - -[id="cli-build-deploy-commands_{context}"] -= Build and Deploy CLI commands - -== cancel-build - -Cancel a running, pending, or new build. - -.Example: Cancel a build -[source,terminal] ----- -$ oc cancel-build python-1 ----- - -.Example: Cancel all pending builds from the `python` build config -[source,terminal] ----- -$ oc cancel-build buildconfig/python --state=pending ----- - -== import-image - -Import the latest tag and image information from an image repository. - -.Example: Import the latest image information -[source,terminal] ----- -$ oc import-image my-ruby ----- - -== new-build - -Create a new build config from source code. - -.Example: Create a build config from a local Git repository -[source,terminal] ----- -$ oc new-build . ----- - -.Example: Create a build config from a remote Git repository -[source,terminal] ----- -$ oc new-build https://github.com/sclorg/cakephp-ex ----- - -== rollback - -Revert an application back to a previous deployment. - -.Example: Roll back to the last successful deployment -[source,terminal] ----- -$ oc rollback php ----- - -.Example: Roll back to a specific version -[source,terminal] ----- -$ oc rollback php --to-version=3 ----- - -== rollout - -Start a new rollout, view its status or history, or roll back to a previous -revision of your application. - -.Example: Roll back to the last successful deployment -[source,terminal] ----- -$ oc rollout undo deploymentconfig/php ----- - -.Example: Start a new rollout for a deployment with its latest state -[source,terminal] ----- -$ oc rollout latest deploymentconfig/php ----- - -== start-build - -Start a build from a build config or copy an existing build. - -.Example: Start a build from the specified build config -[source,terminal] ----- -$ oc start-build python ----- - -.Example: Start a build from a previous build -[source,terminal] ----- -$ oc start-build --from-build=python-1 ----- - -.Example: Set an environment variable to use for the current build -[source,terminal] ----- -$ oc start-build python --env=mykey=myvalue ----- - -== tag - -Tag existing images into image streams. - -.Example: Configure the `ruby` image's `latest` tag to refer to the image for the `2.0` tag -[source,terminal] ----- -$ oc tag ruby:latest ruby:2.0 ----- diff --git a/modules/cli-developer-other.adoc b/modules/cli-developer-other.adoc deleted file mode 100644 index f1690c0f4bf4..000000000000 --- a/modules/cli-developer-other.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/developer-cli-commands.adoc - -[id="cli-other-developer-commands_{context}"] -= Other developer CLI commands - -== help - -Display general help information for the CLI and a list of available commands. - -.Example: Display available commands -[source,terminal] ----- -$ oc help ----- - -.Example: Display the help for the `new-project` command -[source,terminal] ----- -$ oc help new-project ----- - -== plugin - -List the available plug-ins on the user's `PATH`. - -.Example: List available plug-ins -[source,terminal] ----- -$ oc plugin list ----- - -== version - -Display the `oc` client and server versions. - -.Example: Display version information -[source,terminal] ----- -$ oc version ----- - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] - -For cluster administrators, the {product-title} server version is also displayed. - -endif::openshift-enterprise,openshift-webscale,openshift-origin[] diff --git a/modules/cli-developer-settings.adoc b/modules/cli-developer-settings.adoc deleted file mode 100644 index 0b501874d160..000000000000 --- a/modules/cli-developer-settings.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/developer-cli-commands.adoc - -[id="cli-settings-commands_{context}"] -= Settings CLI commands - -== completion - -Output shell completion code for the specified shell. - -.Example: Display completion code for Bash -[source,terminal] ----- -$ oc completion bash ----- - -== config - -Manage the client configuration files. - -.Example: Display the current configuration -[source,terminal] ----- -$ oc config view ----- - -.Example: Switch to a different context -[source,terminal] ----- -$ oc config use-context test-context ----- - -== logout - -Log out of the current session. - -.Example: End the current session -[source,terminal] ----- -$ oc logout ----- - -== whoami - -Display information about the current session. - -.Example: Display the currently authenticated user -[source,terminal] ----- -$ oc whoami ----- diff --git a/modules/cli-developer-troubleshooting.adoc b/modules/cli-developer-troubleshooting.adoc deleted file mode 100644 index eb5e5e5f501a..000000000000 --- a/modules/cli-developer-troubleshooting.adoc +++ /dev/null @@ -1,123 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/developer-cli-commands.adoc - -[id="cli-troubleshooting-commands_{context}"] -= Troubleshooting and debugging CLI commands - -== attach - -Attach the shell to a running container. - -.Example: Get output from the `python` container from pod `python-1-mz2rf` -[source,terminal] ----- -$ oc attach python-1-mz2rf -c python ----- - -== cp - -Copy files and directories to and from containers. - -.Example: Copy a file from the `python-1-mz2rf` pod to the local file system -[source,terminal] ----- -$ oc cp default/python-1-mz2rf:/opt/app-root/src/README.md ~/mydirectory/. ----- - -== debug - -Launch a command shell to debug a running application. - -.Example: Debug the `python` deployment -[source,terminal] ----- -$ oc debug deploymentconfig/python ----- - -== exec - -Execute a command in a container. - -.Example: Execute the `ls` command in the `python` container from pod `python-1-mz2rf` -[source,terminal] ----- -$ oc exec python-1-mz2rf -c python ls ----- - -== logs - -Retrieve the log output for a specific build, build config, deployment, or -pod. - -.Example: Stream the latest logs from the `python` deployment -[source,terminal] ----- -$ oc logs -f deploymentconfig/python ----- - -== port-forward - -Forward one or more local ports to a pod. - -.Example: Listen on port `8888` locally and forward to port `5000` in the pod -[source,terminal] ----- -$ oc port-forward python-1-mz2rf 8888:5000 ----- - -== proxy - -Run a proxy to the Kubernetes API server. - -.Example: Run a proxy to the API server on port `8011` serving static content from `./local/www/` -[source,terminal] ----- -$ oc proxy --port=8011 --www=./local/www/ ----- - -== rsh - -Open a remote shell session to a container. - -.Example: Open a shell session on the first container in the `python-1-mz2rf` pod -[source,terminal] ----- -$ oc rsh python-1-mz2rf ----- - -== rsync - -Copy contents of a directory to or from a running pod container. Only changed -files are copied using the `rsync` command from your operating system. - -.Example: Synchronize files from a local directory with a pod directory -[source,terminal] ----- -$ oc rsync ~/mydirectory/ python-1-mz2rf:/opt/app-root/src/ ----- - -== run - -Create a pod running a particular image. - -.Example: Start a pod running the `perl` image -[source,terminal] ----- -$ oc run my-test --image=perl ----- - -== wait - -Wait for a specific condition on one or more resources. - -[NOTE] -==== -This command is experimental and might change without notice. -==== - -.Example: Wait for the `python-1-mz2rf` pod to be deleted -[source,terminal] ----- -$ oc wait --for=delete pod/python-1-mz2rf ----- diff --git a/modules/cli-extending-plugins-installing.adoc b/modules/cli-extending-plugins-installing.adoc deleted file mode 100644 index bb3f5fb1e4b5..000000000000 --- a/modules/cli-extending-plugins-installing.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/extending-cli-plugins.adoc - -[id="cli-installing-plugins_{context}"] -= Installing and using CLI plug-ins - -After you write a custom plug-in for the {product-title} CLI, you must install -it to use the functionality that it provides. - -[IMPORTANT] -==== -OpenShift CLI plug-ins are currently a Technology Preview feature. -ifdef::openshift-enterprise,openshift-webscale[] -Technology Preview features are not supported with Red Hat production service -level agreements (SLAs), might not be functionally complete, and Red Hat does -not recommend to use them for production. These features provide early access to -upcoming product features, enabling customers to test functionality and provide -feedback during the development process. - -See the link:https://access.redhat.com/support/offerings/techpreview/[Red Hat -Technology Preview features support scope] for more information. -endif::[] -==== - -.Prerequisites - -* You must have the `oc` CLI tool installed. -* You must have a CLI plug-in file that begins with `oc-` or `kubectl-`. - -.Procedure - -. If necessary, update the plug-in file to be executable. -+ -[source,terminal] ----- -$ chmod +x ----- -. Place the file anywhere in your `PATH`, such as `/usr/local/bin/`. -+ -[source,terminal] ----- -$ sudo mv /usr/local/bin/. ----- -. Run `oc plugin list` to make sure that the plug-in is listed. -+ -[source,terminal] ----- -$ oc plugin list ----- -+ -.Example output -[source,terminal] ----- -The following compatible plugins are available: - -/usr/local/bin/ ----- -+ -If your plug-in is not listed here, verify that the file begins with `oc-` -or `kubectl-`, is executable, and is on your `PATH`. -. Invoke the new command or option introduced by the plug-in. -+ -For example, if you built and installed the `kubectl-ns` plug-in from the - link:https://github.com/kubernetes/sample-cli-plugin[Sample plug-in repository], - you can use the following command to view the current namespace. -+ -[source,terminal] ----- -$ oc ns ----- -+ -Note that the command to invoke the plug-in depends on the plug-in file name. -For example, a plug-in with the file name of `oc-foo-bar` is invoked by the `oc foo bar` -command. diff --git a/modules/cli-extending-plugins-writing.adoc b/modules/cli-extending-plugins-writing.adoc deleted file mode 100644 index ec6b20e1f512..000000000000 --- a/modules/cli-extending-plugins-writing.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/extending-cli-plugins.adoc - -[id="cli-writing-plugins_{context}"] -= Writing CLI plug-ins - -You can write a plug-in for the {product-title} CLI in any programming language -or script that allows you to write command-line commands. Note that you can not -use a plug-in to overwrite an existing `oc` command. - -[IMPORTANT] -==== -OpenShift CLI plug-ins are currently a Technology Preview feature. -ifdef::openshift-enterprise,openshift-webscale[] -Technology Preview features are not supported with Red Hat production service -level agreements (SLAs), might not be functionally complete, and Red Hat does -not recommend to use them for production. These features provide early access to -upcoming product features, enabling customers to test functionality and provide -feedback during the development process. - -See the link:https://access.redhat.com/support/offerings/techpreview/[Red Hat -Technology Preview features support scope] for more information. -endif::[] -==== - -.Procedure - -This procedure creates a simple Bash plug-in that prints a message to the -terminal when the `oc foo` command is issued. - -. Create a file called `oc-foo`. -+ -When naming your plug-in file, keep the following in mind: - -* The file must begin with `oc-` or `kubectl-` to be recognized as a -plug-in. -* The file name determines the command that invokes the plug-in. For example, a -plug-in with the file name `oc-foo-bar` can be invoked by a command of -`oc foo bar`. You can also use underscores if you want the command to contain -dashes. For example, a plug-in with the file name `oc-foo_bar` can be invoked -by a command of `oc foo-bar`. - -. Add the following contents to the file. -+ -[source,bash] ----- -#!/bin/bash - -# optional argument handling -if [[ "$1" == "version" ]] -then - echo "1.0.0" - exit 0 -fi - -# optional argument handling -if [[ "$1" == "config" ]] -then - echo $KUBECONFIG - exit 0 -fi - -echo "I am a plugin named kubectl-foo" ----- - -After you install this plug-in for the {product-title} CLI, it can be invoked -using the `oc foo` command. - -.Additional resources - -* Review the link:https://github.com/kubernetes/sample-cli-plugin[Sample plug-in repository] -for an example of a plug-in written in Go. -* Review the link:https://github.com/kubernetes/cli-runtime/[CLI runtime repository] for a set of utilities to assist in writing plug-ins in Go. diff --git a/modules/cli-getting-help.adoc b/modules/cli-getting-help.adoc deleted file mode 100644 index 0bbcbf6ce47d..000000000000 --- a/modules/cli-getting-help.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/getting-started.adoc - -[id="cli-getting-help_{context}"] -= Getting help - -You can get help with CLI commands and {product-title} resources in the -following ways. - -* Use `oc help` to get a list and description of all available CLI commands: -+ -.Example: Get general help for the CLI -[source,terminal] ----- -$ oc help ----- -+ -.Example output -[source,terminal] ----- -OpenShift Client - -This client helps you develop, build, deploy, and run your applications on any OpenShift or Kubernetes compatible -platform. It also includes the administrative commands for managing a cluster under the 'adm' subcommand. - -Usage: - oc [flags] - -Basic Commands: - login Log in to a server - new-project Request a new project - new-app Create a new application - -... ----- - -* Use the `--help` flag to get help about a specific CLI command: -+ -.Example: Get help for the `oc create` command -[source,terminal] ----- -$ oc create --help ----- -+ -.Example output -[source,terminal] ----- -Create a resource by filename or stdin - -JSON and YAML formats are accepted. - -Usage: - oc create -f FILENAME [flags] - -... ----- - -* Use the `oc explain` command to view the description and fields for a -particular resource: -+ -.Example: View documentation for the `Pod` resource -[source,terminal] ----- -$ oc explain pods ----- -+ -.Example output -[source,terminal] ----- -KIND: Pod -VERSION: v1 - -DESCRIPTION: - Pod is a collection of containers that can run on a host. This resource is - created by clients and scheduled onto hosts. - -FIELDS: - apiVersion - APIVersion defines the versioned schema of this representation of an - object. Servers should convert recognized schemas to the latest internal - value, and may reject unrecognized values. More info: - https://git.k8s.io/community/contributors/devel/api-conventions.md#resources - -... ----- diff --git a/modules/cli-installing-cli-rpm.adoc b/modules/cli-installing-cli-rpm.adoc deleted file mode 100644 index 3e4efcd03071..000000000000 --- a/modules/cli-installing-cli-rpm.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/getting-started.adoc - -[id="cli-installing-cli-rpm_{context}"] -= Installing the OpenShift CLI by using an RPM - -For {op-system-base-full}, you can install the OpenShift CLI (`oc`) as an RPM if you have an active {product-title} subscription on your Red Hat account. - -.Prerequisites - -* Must have root or sudo privileges. - -.Procedure - -. Register with Red Hat Subscription Manager: -+ -[source,terminal] ----- -# subscription-manager register ----- - -. Pull the latest subscription data: -+ -[source,terminal] ----- -# subscription-manager refresh ----- - -. List the available subscriptions: -+ -[source,terminal] ----- -# subscription-manager list --available --matches '*OpenShift*' ----- - -. In the output for the previous command, find the pool ID for an {product-title} subscription and attach the subscription to the registered system: -+ -[source,terminal] ----- -# subscription-manager attach --pool= ----- - -. Enable the repositories required by {product-title} {product-version}. - -** For Red Hat Enterprise Linux 8: -+ -[source,terminal] ----- -# subscription-manager repos --enable="rhocp-4.7-for-rhel-8-x86_64-rpms" ----- - -** For Red Hat Enterprise Linux 7: -+ -[source,terminal] ----- -# subscription-manager repos --enable="rhel-7-server-ose-4.7-rpms" ----- - -. Install the `openshift-clients` package: -+ -[source,terminal] ----- -# yum install openshift-clients ----- - -After you install the CLI, it is available using the `oc` command: - -[source,terminal] ----- -$ oc ----- diff --git a/modules/cli-installing-cli.adoc b/modules/cli-installing-cli.adoc deleted file mode 100644 index 3df9f76cdd28..000000000000 --- a/modules/cli-installing-cli.adoc +++ /dev/null @@ -1,168 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/getting-started.adoc -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-default.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-default.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_gcp/installing-gcp-default.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/install_config/installing-restricted-networks-preparations.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * openshift_images/samples-operator-alt-registry.adoc -// * installing/installing_rhv/installing-rhv-customizations.adoc -// * installing/installing_rhv/installing-rhv-default.adoc -// * updating/updating-restricted-network-cluster.adoc -// -// AMQ docs link to this; do not change anchor - -ifeval::["{context}" == "updating-restricted-network-cluster"] -:restricted: -endif::[] - -[id="cli-installing-cli_{context}"] -= Installing the OpenShift CLI by downloading the binary - -You can install the OpenShift CLI (`oc`) to interact with {product-title} from a -command-line interface. You can install `oc` on Linux, Windows, or macOS. - -[IMPORTANT] -==== -If you installed an earlier version of `oc`, you cannot use it to complete all -of the commands in {product-title} {product-version}. Download and -install the new version of `oc`. -ifdef::restricted[] -If you are upgrading a cluster in a restricted network, install the `oc` version that you plan to upgrade to. -endif::restricted[] -==== - -[id="cli-installing-cli-on-linux_{context}"] -== Installing the OpenShift CLI on Linux - -You can install the OpenShift CLI (`oc`) binary on Linux by using the following procedure. - -.Procedure - -ifdef::openshift-origin[] -. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture. -. Download `oc.tar.gz`. -endif::[] -ifndef::openshift-origin[] -. Navigate to the link:https://cloud.redhat.com/openshift/install[Infrastructure Provider] page on the {cloud-redhat-com} site. -. Select your infrastructure provider, and, if applicable, your installation type. -. In the *Command-line interface* section, select *Linux* from the drop-down menu and click *Download command-line tools*. -endif::[] -. Unpack the archive: -+ -[source,terminal] ----- -$ tar xvzf ----- -. Place the `oc` binary in a directory that is on your `PATH`. -+ -To check your `PATH`, execute the following command: -+ -[source,terminal] ----- -$ echo $PATH ----- - -After you install the CLI, it is available using the `oc` command: - -[source,terminal] ----- -$ oc ----- - -[id="cli-installing-cli-on-windows_{context}"] -== Installing the OpenShift CLI on Windows - -You can install the OpenShift CLI (`oc`) binary on Windows by using the following procedure. - -.Procedure - -ifdef::openshift-origin[] -. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture. -. Download `oc.zip`. -endif::[] -ifndef::openshift-origin[] -. Navigate to the link:https://cloud.redhat.com/openshift/install[Infrastructure Provider] page on the {cloud-redhat-com} site. -. Select your infrastructure provider, and, if applicable, your installation type. -. In the *Command-line interface* section, select *Windows* from the drop-down menu and click *Download command-line tools*. -endif::[] -. Unzip the archive with a ZIP program. -. Move the `oc` binary to a directory that is on your `PATH`. -+ -To check your `PATH`, open the command prompt and execute the following command: -+ -[source,terminal] ----- -C:\> path ----- - -After you install the CLI, it is available using the `oc` command: - -[source,terminal] ----- -C:\> oc ----- - -[id="cli-installing-cli-on-macos_{context}"] -== Installing the OpenShift CLI on macOS - -You can install the OpenShift CLI (`oc`) binary on macOS by using the following procedure. - -.Procedure - -ifdef::openshift-origin[] -. Navigate to https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture. -. Download `oc.tar.gz`. -endif::[] -ifndef::openshift-origin[] -. Navigate to the link:https://cloud.redhat.com/openshift/install[Infrastructure Provider] page on the {cloud-redhat-com} site. -. Select your infrastructure provider, and, if applicable, your installation type. -. In the *Command-line interface* section, select *MacOS* from the drop-down menu and click *Download command-line tools*. -endif::[] -. Unpack and unzip the archive. -. Move the `oc` binary to a directory on your PATH. -+ -To check your `PATH`, open a terminal and execute the following command: -+ -[source,terminal] ----- -$ echo $PATH ----- - -After you install the CLI, it is available using the `oc` command: - -[source,terminal] ----- -$ oc ----- - - -ifeval::["{context}" == "updating-restricted-network-cluster"] -:!restricted: -endif::[] diff --git a/modules/cli-logging-in-kubeadmin.adoc b/modules/cli-logging-in-kubeadmin.adoc deleted file mode 100644 index 3040753aad55..000000000000 --- a/modules/cli-logging-in-kubeadmin.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-default.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-default.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_gcp/installing-gcp-default.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp_user_infra/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vsphere-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing_rhv/installing-rhv-customizations.adoc -// * installing/installing_rhv/installing-rhv-default.adoc - - -[id="cli-logging-in-kubeadmin_{context}"] -= Logging in to the cluster by using the CLI - -You can log in to your cluster as a default system user by exporting the cluster `kubeconfig` file. -The `kubeconfig` file contains information about the cluster that is used by the CLI to connect a client to the correct cluster and API server. -The file is specific to a cluster and is created during {product-title} installation. - -.Prerequisites - -* You deployed an {product-title} cluster. -* You installed the `oc` CLI. - -.Procedure - -. Export the `kubeadmin` credentials: -+ -[source,terminal] ----- -$ export KUBECONFIG=/auth/kubeconfig <1> ----- -<1> For ``, specify the path to the directory that you stored -the installation files in. - -. Verify you can run `oc` commands successfully using the exported configuration: -+ -[source,terminal] ----- -$ oc whoami ----- -+ -.Example output -[source,terminal] ----- -system:admin ----- diff --git a/modules/cli-logging-in.adoc b/modules/cli-logging-in.adoc deleted file mode 100644 index c76e333466be..000000000000 --- a/modules/cli-logging-in.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/getting-started.adoc - -[id="cli-logging-in_{context}"] -= Logging in to the OpenShift CLI - -You can log in to the `oc` CLI to access and manage your cluster. - -.Prerequisites - -* You must have access to an {product-title} cluster. -* You must have installed the CLI. - -[NOTE] -==== -To access a cluster that is accessible only over an HTTP proxy server, you can set the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` variables. -These environment variables are respected by the `oc` CLI so that all communication with the cluster goes through the HTTP proxy. -==== - -.Procedure - -* Log in to the CLI using the `oc login` command and enter the required -information when prompted. -+ -[source,terminal] ----- -$ oc login ----- -+ -.Example output -[source,terminal] ----- -Server [https://localhost:8443]: https://openshift.example.com:6443 <1> -The server uses a certificate signed by an unknown authority. -You can bypass the certificate check, but any data you send to the server could be intercepted by others. -Use insecure connections? (y/n): y <2> - -Authentication required for https://openshift.example.com:6443 (openshift) -Username: user1 <3> -Password: <4> -Login successful. - -You don't have any projects. You can try to create a new project, by running - - oc new-project - -Welcome! See 'oc help' to get started. ----- -<1> Enter the {product-title} server URL. -<2> Enter whether to use insecure connections. -<3> Enter the user name to log in as. -<4> Enter the user's password. - -You can now create a project or issue other commands for managing your cluster. diff --git a/modules/cli-logging-out.adoc b/modules/cli-logging-out.adoc deleted file mode 100644 index 57be58cea225..000000000000 --- a/modules/cli-logging-out.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/getting-started.adoc - -[id="cli-logging-out_{context}"] -= Logging out of the OpenShift CLI - -You can log out the OpenShift CLI to end your current session. - -* Use the `oc logout` command. -+ -[source,terminal] ----- -$ oc logout ----- -+ -.Example output -[source,terminal] ----- -Logged "user1" out on "https://openshift.example.com/" ----- - -This deletes the saved authentication token from the server and removes it from -your configuration file. diff --git a/modules/cli-using-cli.adoc b/modules/cli-using-cli.adoc deleted file mode 100644 index 9414f7e6a50c..000000000000 --- a/modules/cli-using-cli.adoc +++ /dev/null @@ -1,134 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/openshift_cli/getting-started.adoc - -[id="cli-using-cli_{context}"] -= Using the OpenShift CLI - -Review the following sections to learn how to complete common tasks using the CLI. - -== Creating a project - -Use the `oc new-project` command to create a new project. - -[source,terminal] ----- -$ oc new-project my-project ----- - -.Example output -[source,terminal] ----- -Now using project "my-project" on server "https://openshift.example.com:6443/". ----- - -== Creating a new app - -Use the `oc new-app` command to create a new application. - -[source,terminal] ----- -$ oc new-app https://github.com/sclorg/cakephp-ex ----- - -.Example output -[source,terminal] ----- ---> Found image 40de956 (9 days old) in imagestream "openshift/php" under tag "7.2" for "php" - -... - - Run 'oc status' to view your app. ----- - -== Viewing pods - -Use the `oc get pods` command to view the pods for the current project. - -[source,terminal] ----- -$ oc get pods -o wide ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE -cakephp-ex-1-build 0/1 Completed 0 5m45s 10.131.0.10 ip-10-0-141-74.ec2.internal -cakephp-ex-1-deploy 0/1 Completed 0 3m44s 10.129.2.9 ip-10-0-147-65.ec2.internal -cakephp-ex-1-ktz97 1/1 Running 0 3m33s 10.128.2.11 ip-10-0-168-105.ec2.internal ----- - -== Viewing pod logs - -Use the `oc logs` command to view logs for a particular pod. - -[source,terminal] ----- -$ oc logs cakephp-ex-1-deploy ----- - -.Example output -[source,terminal] ----- ---> Scaling cakephp-ex-1 to 1 ---> Success ----- - -== Viewing the current project - -Use the `oc project` command to view the current project. - -[source,terminal] ----- -$ oc project ----- - -.Example output -[source,terminal] ----- -Using project "my-project" on server "https://openshift.example.com:6443/". ----- - -== Viewing the status for the current project - -Use the `oc status` command to view information about the current project, such -as services, deployments, and build configs. - -[source,terminal] ----- -$ oc status ----- - -.Example output -[source,terminal] ----- -In project my-project on server https://openshift.example.com:6443 - -svc/cakephp-ex - 172.30.236.80 ports 8080, 8443 - dc/cakephp-ex deploys istag/cakephp-ex:latest <- - bc/cakephp-ex source builds https://github.com/sclorg/cakephp-ex on openshift/php:7.2 - deployment #1 deployed 2 minutes ago - 1 pod - -3 infos identified, use 'oc status --suggest' to see details. ----- - -== Listing supported API resources - -Use the `oc api-resources` command to view the list of supported API resources -on the server. - -[source,terminal] ----- -$ oc api-resources ----- - -.Example output -[source,terminal] ----- -NAME SHORTNAMES APIGROUP NAMESPACED KIND -bindings true Binding -componentstatuses cs false ComponentStatus -configmaps cm true ConfigMap -... ----- diff --git a/modules/cloud-create-instance-steps.adoc b/modules/cloud-create-instance-steps.adoc new file mode 100644 index 000000000000..8e7d61094682 --- /dev/null +++ b/modules/cloud-create-instance-steps.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * installing/cloud-create-instance-other.adoc +// * installing/cloud-create-instance-ocp.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cloud-create-instance-steps_{context}"] += Creating an instance in the console + +[role="_abstract"] +In the {cloud-console}, create an *ACS instance* to connect to your secured clusters. + +.Procedure + +To create an *ACS instance*: + +. Log in to the {cloud-console}. +. From the navigation menu, select *Advanced Cluster Security* -> *ACS Instances*. +. Select *Create ACS instance* and enter information into the displayed fields or select the appropriate option from the drop-down list: +* *Name*: Enter the name of your *ACS instance*. An *ACS instance* contains the {product-title-short} Central component, also referred to as "Central", which includes the {product-title-managed-short} management interface and services that are configured and managed by Red{nbsp}Hat. You manage your secured clusters that communicate with Central. You can connect many secured clusters to one instance. +* *Cloud provider*: The cloud provider where Central is located. Select *AWS*. +* *Cloud region*: The region for your cloud provider where Central is located. Select one of the following regions: +** US-East, N. Virginia +** Europe, Ireland +* *Availability zones*: Use the default value (*Multi*). +. Click *Create instance*. diff --git a/modules/cloud-credential-operator.adoc b/modules/cloud-credential-operator.adoc deleted file mode 100644 index d3daf7ae2224..000000000000 --- a/modules/cloud-credential-operator.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cloud-credential-operator_{context}"] -= Cloud Credential Operator - -[discrete] -== Purpose - -The Cloud Credential Operator (CCO) manages cloud provider credentials as Kubernetes custom resource definitions (CRDs). The CCO syncs on `CredentialsRequest` custom resources (CRs) to allow {product-title} components to request cloud provider credentials with the specific permissions that are required for the cluster to run. - -By setting different values for the `credentialsMode` parameter in the `install-config.yaml` file, the CCO can be configured to operate in several different modes. If no mode is specified, or the `credentialsMode` parameter is set to an empty string (`""`), the CCO operates in its default mode. - -[discrete] -== Project - -link:https://github.com/openshift/cloud-credential-operator[openshift-cloud-credential-operator] - -[discrete] -== CRDs - -* `credentialsrequests.cloudcredential.openshift.io` -** Scope: Namespaced -** CR: `CredentialsRequest` -** Validation: Yes - -[discrete] -== Configuration objects - -No configuration required. diff --git a/modules/cloud-getting-support.adoc b/modules/cloud-getting-support.adoc new file mode 100644 index 000000000000..92cc9e0423d5 --- /dev/null +++ b/modules/cloud-getting-support.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_content-type: CONCEPT +[id="cloud-getting-support_{context}"] += Getting support for RHACS Cloud Service + + +If you experience difficulty with a procedure described in this documentation, or with {product-title-managed-short} in general, visit the link:https://access.redhat.com/support[Red Hat Customer Portal]. + +From the Customer Portal, you can perform the following actions: + +* Search or browse through the Red Hat Knowledgebase of articles and solutions relating to Red Hat products. + +* Submit a support case to Red Hat Support. + +* Access other product documentation. + +To identify issues with your cluster, you can use Insights in {product-title-managed-short}. Insights provides details about issues and, if available, information on how to solve a problem. + diff --git a/modules/cloud-info-security.adoc b/modules/cloud-info-security.adoc new file mode 100644 index 000000000000..bbd5db58b8dd --- /dev/null +++ b/modules/cloud-info-security.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_content-type: CONCEPT +[id="cloud-info-security_{context}"] += Information security guidelines, roles, and responsibilities + +Red{nbsp}Hat's information security guidelines, aligned with the link:https://www.nist.gov/cyberframework[NIST Cybersecurity Framework], are approved by executive management. Red{nbsp}Hat maintains a dedicated team of globally-distributed certified information security professionals. See the following resources: + +* link:https://www.first.org/members/teams/rh-isirt[FIRST: RH-ISIRT team] +* link:https://www.trusted-introducer.org/directory/teams/rh-isirt.html[TF-CSIRT: RH-ISIRT team] + +Red{nbsp}Hat has strict internal policies and practices to protect our customers and their businesses. These policies and practices are confidential. In addition, we comply with all applicable laws and regulations, including those related to data privacy. +//There was no URL given for the link below. +//For more information, see [Red{nbsp}Hat, Inc. Information Security Operating Guidelines]. + +Red{nbsp}Hat's information security roles and responsibilities are not managed by third parties. + +Red{nbsp}Hat maintains an ISO 27001 certification for our corporate information security management system (ISMS), which governs how all of our people work, corporate endpoint devices, and authentication and authorization practices. We have taken a standardized approach to this through the implementation of the Red{nbsp}Hat Enterprise Security Standard (ESS) to all infrastructure, products, services and technology that Red{nbsp}Hat employs. A copy of the ESS is available upon request. + +{product-title-managed-short} runs on an instance of OpenShift Dedicated hosted on Amazon Web Services (AWS). OpenShift Dedicated is compliant with ISO 27001, ISO 27017, ISO 27018, PCI DSS, SOC 2 Type 2, and HIPAA. Strong processes and security controls are aligned with industry standards to manage information security. + +{product-title-managed-short} follows the same security principles, guidelines, processes and controls defined for OpenShift Dedicated. These certifications demonstrate how our services platform, associated operations, and management practices align with core security requirements. We meet many of these requirements by following solid Secure Software Development Framework (SSDF) practices as defined by NIST, including build pipeline security. Implementation of SSDF controls are implemented via our Secure Software Management Lifecycle (SSML) for all products and services. + +Red{nbsp}Hat's proven and experienced global site reliability engineering (SRE) team is available 24x7 and proactively manages the cluster life cycle, infrastructure configuration, scaling, maintenance, security patching, and incident response as it relates to the hosted components of {product-title-managed-short}. The Red{nbsp}Hat SRE team is responsible for managing HA, uptime, backups, restore, and security for the {product-title-managed-short} control plane. {product-title-managed-short} comes with a 99.95% availability SLA and 24x7 RH SRE support by phone or chat. + +You are responsible for use of the product, including implementation of policies, vulnerability management, and deployment of secured cluster components within your {ocp} environments. The Red{nbsp}Hat SRE team manages the control plane that contains tenant data in line with the compliance frameworks noted previously, including: + +* All Red{nbsp}Hat SRE access the data plane clusters through the backplane which enables audited access to the cluster +* Red{nbsp}Hat SRE only deploys images from the Red{nbsp}Hat registry. All content posted to the Red{nbsp}Hat registry goes through rigorous checks. These images are the same images available to self-managed customers. +* Each tenant has their own individual mTLS CA, which encrypts data in-transit, enabling multi-tenant isolation. Additional isolation is provided via SELinux controls namespaces and network policies. +* Each tenant has their own instance of the RDS database. + +All Red{nbsp}Hat SREs and developers go through rigorous Secure Development Lifecycle training. + +For more information, see the following resources: + +* link:https://www.redhat.com/en/resources/site-reliability-engineering-services-datasheet[Red Hat Site Reliability Engineering (SRE) services] +* link:https://www.redhat.com/en/resources/openshift-dedicated-datasheet[Red{nbsp}Hat OpenShift Dedicated] +* link:https://access.redhat.com/articles/red_hat_sdl[An Overview of Red{nbsp}Hat's Secure Development Lifecycle (SDL) practices] + + diff --git a/modules/cloud-management-platforms-ocm.adoc b/modules/cloud-management-platforms-ocm.adoc new file mode 100644 index 000000000000..49e3d2cb022f --- /dev/null +++ b/modules/cloud-management-platforms-ocm.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-cloud-management-platforms.adoc +:_mod-docs-content-type: PROCEDURE +[id="cloud-management-platforms-ocm.adoc_{context}"] += Configuring Red Hat OpenShift Cluster Manager integration + +To discover cluster assets from Red{nbsp}Hat OpenShift Cluster Manager, create a new integration in {product-title}. + +.Prerequisites +* A Red{nbsp}Hat account. +* A link:https://console.redhat.com/iam/service-accounts[Red{nbsp}Hat service account]. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Cloud source integrations* section and select *Red{nbsp}Hat OpenShift Cluster Manager*. +. Click *New integration*. +. Enter a name for *Integration name*. +. Enter the Red{nbsp}Hat OpenShift Cluster Manager API endpoint for *Endpoint*. The default is `\https://api.openshift.com`. +. Enter the Red{nbsp}Hat service account credentials for *Client ID* and *Client secret*. +. Select *Test* to confirm that authentication is working. +. Select *Create* to generate the configuration. + +Once configured, {product-title} discovers cluster assets from your connected Red{nbsp}Hat account. diff --git a/modules/cloud-management-platforms-paladin-cloud.adoc b/modules/cloud-management-platforms-paladin-cloud.adoc new file mode 100644 index 000000000000..0bc71ce2953d --- /dev/null +++ b/modules/cloud-management-platforms-paladin-cloud.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-cloud-management-platforms.adoc +:_mod-docs-content-type: PROCEDURE +[id="cloud-management-platforms-paladin-cloud_{context}"] += Configuring Paladin Cloud integration + +To discover cluster assets from Paladin Cloud, create a new integration in {product-title}. + +.Prerequisites +* A Paladin Cloud account. +* A Paladin Cloud API token. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Cloud source integrations* section and select *Paladin Cloud*. +. Click *New integration*. +. Enter a name for *Integration name*. +. Enter the Paladin Cloud API endpoint for *Paladin Cloud endpoint*. The default is `\https://api.paladincloud.io`. +. Enter the Paladin Cloud API token for *Paladin Cloud token*. +. Select *Test* to confirm that authentication is working. +. Select *Create* to generate the configuration. + +Once configured, {product-title} discovers cluster assets from your connected Paladin Cloud account. diff --git a/modules/cloud-ocp-create-stackrox-project.adoc b/modules/cloud-ocp-create-stackrox-project.adoc new file mode 100644 index 000000000000..e253b85ffc38 --- /dev/null +++ b/modules/cloud-ocp-create-stackrox-project.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * installing/install_cloud_ocp/cloud-ocp-create-project.adoc +:_mod-docs-content-type: PROCEDURE +[id="cloud-ocp-create-stackrox-project_{context}"] += Creating a project on your cluster + +.Procedure +* In your {ocp} cluster, go to *Home* -> *Projects* and create a project for {product-title-managed-short}. Use `stackrox` as the project *Name*. diff --git a/modules/cloud-service-removal.adoc b/modules/cloud-service-removal.adoc new file mode 100644 index 000000000000..5def63d8a828 --- /dev/null +++ b/modules/cloud-service-removal.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_content-type: CONCEPT +[id="cloud-service-removal_{context}"] += Service removal + +You can delete {product-title-managed-short} using the default delete operations from the link:https://console.redhat.com/[Red Hat Hybrid Cloud Console]. +Deleting the {product-title-managed-short} Central instance automatically removes all {product-title-short} components. Deleting is not reversible. diff --git a/modules/cloud-svc-compliance.adoc b/modules/cloud-svc-compliance.adoc new file mode 100644 index 000000000000..324dcf2ae602 --- /dev/null +++ b/modules/cloud-svc-compliance.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_content-type: CONCEPT +[id="cloud-svc-compliance_{context}"] += Compliance + +[role="_abstract"] +{product-title-managed-short} is certified across key global standards, ensuring top-tier security, compliance, and data protection for your business. + +The following table outlines certifications for {product-title-managed-short}. + +.Security and control certifications for {product-title-managed-short} + +[cols="1,1",options="header"] +|=== +|Compliance +| {product-title-managed-short} on Kubernetes + +| ISO/IEC 27001:2022 +| Yes + +| ISO/IEC 27017:2015 +| Yes + +| ISO/IEC 27018:2019 +| Yes + +| PCI DSS 4.0 +| Yes + +| SOC 2 Type 2 +| Yes + +| SOC 2 Type 3 +| Yes + +|=== \ No newline at end of file diff --git a/modules/cluster-authentication-operator.adoc b/modules/cluster-authentication-operator.adoc deleted file mode 100644 index 0056de181e25..000000000000 --- a/modules/cluster-authentication-operator.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-authentication-operator_{context}"] -= Cluster Authentication Operator - -[discrete] -== Purpose - -The Cluster Authentication Operator installs and maintains the `Authentication` custom resource in a cluster and can be viewed with: - -[source,terminal] ----- -$ oc get clusteroperator authentication -o yaml ----- - -[discrete] -== Project - -link:https://github.com/openshift/cluster-authentication-operator[cluster-authentication-operator] diff --git a/modules/cluster-autoscaler-about.adoc b/modules/cluster-autoscaler-about.adoc deleted file mode 100644 index a71f1cee5de7..000000000000 --- a/modules/cluster-autoscaler-about.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/applying-autoscaling.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="cluster-autoscaler-about_{context}"] -= About the cluster autoscaler - -The cluster autoscaler adjusts the size of an {product-title} cluster to meet its current deployment needs. It uses declarative, Kubernetes-style arguments to provide infrastructure management that does not rely on objects of a specific cloud provider. The cluster autoscaler has a cluster scope, and is not associated with a particular namespace. - -The cluster autoscaler increases the size of the cluster when there are pods that failed to schedule on any of the current nodes due to insufficient resources or when another node is necessary to meet deployment needs. The cluster autoscaler does not increase the cluster resources beyond the limits that you specify. - -[IMPORTANT] -==== -Ensure that the `maxNodesTotal` value in the `ClusterAutoscaler` resource definition that you create is large enough to account for the total possible number of machines in your cluster. This value must encompass the number of control plane machines and the possible number of compute machines that you might scale to. -==== - -The cluster autoscaler decreases the size of the cluster when some nodes are consistently not needed for a significant period, such as when it has low resource use and all of its important pods can fit on other nodes. - -If the following types of pods are present on a node, the cluster autoscaler will not remove the node: - -* Pods with restrictive pod disruption budgets (PDBs). -* Kube-system pods that do not run on the node by default. -* Kube-system pods that do not have a PDB or have a PDB that is too restrictive. -* Pods that are not backed by a controller object such as a deployment, replica set, or stateful set. -* Pods with local storage. -* Pods that cannot be moved elsewhere because of a lack of resources, incompatible node selectors or affinity, matching anti-affinity, and so on. -* Unless they also have a `"cluster-autoscaler.kubernetes.io/safe-to-evict": "true"` annotation, pods that have a `"cluster-autoscaler.kubernetes.io/safe-to-evict": "false"` annotation. - -If you configure the cluster autoscaler, additional usage restrictions apply: - -* Do not modify the nodes that are in autoscaled node groups directly. All nodes within the same node group have the same capacity and labels and run the same system pods. -* Specify requests for your pods. -* If you have to prevent pods from being deleted too quickly, configure appropriate PDBs. -* Confirm that your cloud provider quota is large enough to support the maximum node pools that you configure. -* Do not run additional node group autoscalers, especially the ones offered by your cloud provider. - - -The horizontal pod autoscaler (HPA) and the cluster autoscaler modify cluster resources in different ways. The HPA changes the deployment's or replica set's number of replicas based on the current CPU load. If the load increases, the HPA creates new replicas, regardless of the amount of resources available to the cluster. If there are not enough resources, the cluster autoscaler adds resources so that the HPA-created pods can run. If the load decreases, the HPA stops some replicas. If this action causes some nodes to be underutilized or completely empty, the cluster autoscaler deletes the unnecessary nodes. - - -The cluster autoscaler takes pod priorities into account. The Pod Priority and Preemption feature enables scheduling pods based on priorities if the cluster does not have enough resources, but the cluster autoscaler ensures that the cluster has resources to run all pods. To honor the intention of both features, the cluster autoscaler includes a priority cutoff function. You can use this cutoff to schedule "best-effort" pods, which do not cause the cluster autoscaler to increase resources but instead run only when spare resources are available. - -Pods with priority lower than the cutoff value do not cause the cluster to scale up or prevent the cluster from scaling down. No new nodes are added to run the pods, and nodes running these pods might be deleted to free resources. - -//// -Default priority cutoff is 0. It can be changed using `--expendable-pods-priority-cutoff` flag, but we discourage it. cluster autoscaler also doesn't trigger scale-up if an unschedulable Pod is already waiting for a lower priority Pod preemption. -//// diff --git a/modules/cluster-autoscaler-cr.adoc b/modules/cluster-autoscaler-cr.adoc deleted file mode 100644 index c7bf97642586..000000000000 --- a/modules/cluster-autoscaler-cr.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/applying-autoscaling.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="cluster-autoscaler-cr_{context}"] -= `ClusterAutoscaler` resource definition - -This `ClusterAutoscaler` resource definition shows the parameters and sample values for the cluster autoscaler. - - -[source,yaml] ----- -apiVersion: "autoscaling.openshift.io/v1" -kind: "ClusterAutoscaler" -metadata: - name: "default" -spec: - podPriorityThreshold: -10 <1> - resourceLimits: - maxNodesTotal: 24 <2> - cores: - min: 8 <3> - max: 128 <4> - memory: - min: 4 <5> - max: 256 <6> - gpus: - - type: nvidia.com/gpu <7> - min: 0 <8> - max: 16 <9> - - type: amd.com/gpu <7> - min: 0 <8> - max: 4 <9> - scaleDown: <10> - enabled: true <11> - delayAfterAdd: 10m <12> - delayAfterDelete: 5m <13> - delayAfterFailure: 30s <14> - unneededTime: 60s <15> ----- -<1> Specify the priority that a pod must exceed to cause the cluster autoscaler to deploy additional nodes. Enter a 32-bit integer value. The `podPriorityThreshold` value is compared to the value of the `PriorityClass` that you assign to each pod. -<2> Specify the maximum number of nodes to deploy. This value is the total number of machines that are deployed in your cluster, not just the ones that the autoscaler controls. Ensure that this value is large enough to account for all of your control plane and compute machines and the total number of replicas that you specify in your `MachineAutoscaler` resources. -<3> Specify the minimum number of cores to deploy. -<4> Specify the maximum number of cores to deploy. -<5> Specify the minimum amount of memory, in GiB, per node. -<6> Specify the maximum amount of memory, in GiB, per node. -<7> Optionally, specify the type of GPU node to deploy. Only `nvidia.com/gpu` and `amd.com/gpu` are valid types. -<8> Specify the minimum number of GPUs to deploy. -<9> Specify the maximum number of GPUs to deploy. -<10> In this section, you can specify the period to wait for each action by using any valid link:https://golang.org/pkg/time/#ParseDuration[ParseDuration] interval, including `ns`, `us`, `ms`, `s`, `m`, and `h`. -<11> Specify whether the cluster autoscaler can remove unnecessary nodes. -<12> Optionally, specify the period to wait before deleting a node after a node has recently been _added_. If you do not specify a value, the default value of `10m` is used. -<13> Specify the period to wait before deleting a node after a node has recently been _deleted_. If you do not specify a value, the default value of `10s` is used. -<14> Specify the period to wait before deleting a node after a scale down failure occurred. If you do not specify a value, the default value of `3m` is used. -<15> Specify the period before an unnecessary node is eligible for deletion. If you do not specify a value, the default value of `10m` is used. diff --git a/modules/cluster-autoscaler-operator.adoc b/modules/cluster-autoscaler-operator.adoc deleted file mode 100644 index c37e338537ff..000000000000 --- a/modules/cluster-autoscaler-operator.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-autoscaler-operator_{context}"] -= Cluster Autoscaler Operator - -[discrete] -== Purpose - -The Cluster Autoscaler Operator manages deployments of the OpenShift Cluster Autoscaler using the `cluster-api` provider. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-autoscaler-operator[cluster-autoscaler-operator] - -[discrete] -== CRDs - -* `ClusterAutoscaler`: This is a singleton resource, which controls the configuration autoscaler instance for the cluster. The Operator only responds to the `ClusterAutoscaler` resource named `default` in the managed namespace, the value of the `WATCH_NAMESPACE` environment variable. -* `MachineAutoscaler`: This resource targets a node group and manages the annotations to enable and configure autoscaling for that group, the `min` and `max` size. Currently only `MachineSet` objects can be targeted. diff --git a/modules/cluster-dns-operator.adoc b/modules/cluster-dns-operator.adoc deleted file mode 100644 index 85f6a758beaf..000000000000 --- a/modules/cluster-dns-operator.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="dns-operator_{context}"] -= DNS Operator - -[discrete] -== Purpose - -The DNS Operator deploys and manages CoreDNS to provide a name resolution service to pods that enables DNS-based Kubernetes Service discovery in {product-title}. - -The Operator creates a working default deployment based on the cluster's configuration. - -* The default cluster domain is `cluster.local`. -* Configuration of the CoreDNS Corefile or Kubernetes plug-in is not yet supported. - -The DNS Operator manages CoreDNS as a Kubernetes daemon set exposed as a service with a static IP. CoreDNS runs on all nodes in the cluster. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-dns-operator[cluster-dns-operator] diff --git a/modules/cluster-entitlements.adoc b/modules/cluster-entitlements.adoc deleted file mode 100644 index ba40d7d9982d..000000000000 --- a/modules/cluster-entitlements.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture.adoc -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-default.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-default.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_gcp/installing-gcp-default.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_rhv/installing-rhv-restricted-network.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc - -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:restricted: -endif::[] - -[id="cluster-entitlements_{context}"] -ifndef::openshift-origin[] -= Internet and Telemetry access for {product-title} - -In {product-title} {product-version}, you require access to the Internet to -ifndef::restricted[] -install -endif::restricted[] -ifdef::restricted[] -obtain the images that are necessary to install -endif::restricted[] -your cluster. -The Telemetry service, which runs by default to provide metrics about cluster health and the success of updates, also requires Internet access. If your cluster is connected to the Internet, Telemetry runs automatically, and your cluster is registered to the link:https://cloud.redhat.com/openshift[{cloud-redhat-com} (OCM)]. - -Once you confirm that your {cloud-redhat-com} inventory is correct, either maintained automatically by Telemetry or manually using OCM, link:https://access.redhat.com/documentation/en-us/subscription_central/2020-04/html/getting_started_with_subscription_watch/con-how-to-select-datacollection-tool_assembly-requirements-and-your-responsibilities-ctxt#red_hat_openshift[use subscription watch] to track your {product-title} subscriptions at the account or multi-cluster level. - -You must have Internet access to: - -* Access the link:https://cloud.redhat.com/openshift[{cloud-redhat-com}] page to download the installation program and perform subscription management. If the cluster has Internet access and you do not disable Telemetry, that service automatically entitles your cluster. -* Access link:http://quay.io[Quay.io] to obtain the packages that are required to install your cluster. -* Obtain the packages that are required to perform cluster updates. -ifdef::openshift-enterprise,openshift-webscale[] - -[IMPORTANT] -==== -If your cluster cannot have direct Internet access, you can perform a restricted network installation on some types of infrastructure that you provision. During that process, you download the content that is required and use it to populate a mirror registry with the packages that you need to install a cluster and generate the installation program. With some installation types, the environment that you install your cluster in will not require Internet access. Before you update the cluster, you update the content of the mirror registry. -==== - -endif::openshift-enterprise,openshift-webscale[] -endif::openshift-origin[] - -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:!restricted: -endif::[] diff --git a/modules/cluster-image-registry-operator.adoc b/modules/cluster-image-registry-operator.adoc deleted file mode 100644 index db1d60acdb39..000000000000 --- a/modules/cluster-image-registry-operator.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-image-registry-operator_{context}"] -= Cluster Image Registry Operator - -[discrete] -== Purpose - -The Cluster Image Registry Operator manages a singleton instance of the {product-title} registry. It manages all configuration of the registry, including creating storage. - -On initial start up, the Operator creates a default `image-registry` resource instance based on the configuration detected in the cluster. This indicates what cloud storage type to use based on the cloud provider. - -If insufficient information is available to define a complete `image-registry` resource, then an incomplete resource is defined and the Operator updates the resource status with information about what is missing. - -The Cluster Image Registry Operator runs in the `openshift-image-registry` namespace and it also manages the registry instance in that location. All configuration and workload resources for the registry reside in that namespace. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-image-registry-operator[cluster-image-registry-operator] diff --git a/modules/cluster-kube-scheduler-operator.adoc b/modules/cluster-kube-scheduler-operator.adoc deleted file mode 100644 index b5e8d14bfd93..000000000000 --- a/modules/cluster-kube-scheduler-operator.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-kube-scheduler-operator_{context}"] -= Kubernetes Scheduler Operator - -[discrete] -== Purpose - -The Kubernetes Scheduler Operator manages and updates the Kubernetes Scheduler deployed on top of {product-title}. The Operator is based on the {product-title} `library-go` framework and it is installed with the Cluster Version Operator (CVO). - -The Kubernetes Scheduler Operator contains the following components: - -* Operator -* Bootstrap manifest renderer -* Installer based on static pods -* Configuration observer - -By default, the Operator exposes Prometheus metrics through the metrics service. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-kube-scheduler-operator[cluster-kube-scheduler-operator] - -[discrete] -== Configuration - -The configuration for the Kubernetes Scheduler is the result of merging: - -* a default configuration. -* an observed configuration from the spec `schedulers.config.openshift.io`. - -All of these are sparse configurations, invalidated JSON snippets which are merged to form a valid configuration at the end. diff --git a/modules/cluster-logging-about-collector.adoc b/modules/cluster-logging-about-collector.adoc deleted file mode 100644 index 714b389fa143..000000000000 --- a/modules/cluster-logging-about-collector.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging.adoc - -[id="cluster-logging-about-collector_{context}"] -= About the logging collector - -{product-title} uses Fluentd to collect container and node logs. - -By default, the log collector uses the following sources: - -* journald for all system logs -* `/var/log/containers/*.log` for all container logs - -If you configure the log collector to collect audit logs, it gets them from `/var/log/audit/audit.log`. - -The logging collector is a daemon set that deploys pods to each {product-title} node. System and infrastructure logs are generated by journald log messages from the operating system, the container runtime, and {product-title}. Application logs are generated by the CRI-O container engine. Fluentd collects the logs from these sources and forwards them internally or externally as you configure in {product-title}. - -The container runtimes provide minimal information to identify the source of log messages: project, pod name, and container ID. This information is not sufficient to uniquely identify the source of the logs. If a pod with a given name and project is deleted before the log collector begins processing its logs, information from the API server, such as labels and annotations, might not be available. There might not be a way to distinguish the log messages from a similarly named pod and project or trace the logs to their source. This limitation means that log collection and normalization are considered *best effort*. - -[IMPORTANT] -==== -The available container runtimes provide minimal information to identify the -source of log messages and do not guarantee unique individual log -messages or that these messages can be traced to their source. -==== diff --git a/modules/cluster-logging-about-components.adoc b/modules/cluster-logging-about-components.adoc deleted file mode 100644 index 4a6e5ba34515..000000000000 --- a/modules/cluster-logging-about-components.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging.adoc -// * virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc - - -ifeval::["{context}" == "virt-openshift-cluster-monitoring"] -:virt-logging: -endif::[] - -[id="cluster-logging-about-components_{context}"] -= About OpenShift Logging components - -The OpenShift Logging components include a collector deployed to each node in the {product-title} cluster -that collects all node and container logs and writes them to a log store. You can use a centralized web UI -to create rich visualizations and dashboards with the aggregated data. - -The major components of OpenShift Logging are: - -* collection - This is the component that collects logs from the cluster, formats them, and forwards them to the log store. The current implementation is Fluentd. -* log store - This is where the logs are stored. The default implementation is Elasticsearch. You can use the default Elasticsearch log store or forward logs to external log stores. The default log store is optimized and tested for short-term storage. -* visualization - This is the UI component you can use to view logs, graphs, charts, and so forth. The current implementation is Kibana. - -ifndef::virt-logging[] -This document might refer to log store or Elasticsearch, visualization or Kibana, collection or Fluentd, interchangeably, except where noted. -endif::virt-logging[] - -ifeval::["{context}" == "virt-openshift-cluster-monitoring"] -:!virt-logging: -endif::[] diff --git a/modules/cluster-logging-about-crd.adoc b/modules/cluster-logging-about-crd.adoc deleted file mode 100644 index 8e79669a27f6..000000000000 --- a/modules/cluster-logging-about-crd.adoc +++ /dev/null @@ -1,136 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging.adoc - -[id="cluster-logging-configuring-crd_{context}"] -= About the `ClusterLogging` custom resource - -To make changes to your OpenShift Logging environment, create and modify the `ClusterLogging` custom resource (CR). - -Instructions for creating or modifying a CR are provided in this documentation as appropriate. - -The following example shows a typical custom resource for OpenShift Logging. - -[id="efk-logging-configuring-about-sample_{context}"] -.Sample `ClusterLogging` custom resource (CR) -ifdef::openshift-dedicated[] -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: "openshift-logging" -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - retentionPolicy: - application: - maxAge: 1d - infra: - maxAge: 7d - audit: - maxAge: 7d - elasticsearch: - nodeCount: 3 - storage: - storageClassName: "gp2" - size: "200Gi" - redundancyPolicy: "SingleRedundancy" - nodeSelector: - node-role.kubernetes.io/worker: "" - resources: - request: - memory: 8G - proxy: - resources: - limits: - memory: 256Mi - requests: - memory: 256Mi - visualization: - type: "kibana" - kibana: - replicas: 1 - nodeSelector: - node-role.kubernetes.io/worker: "" - collection: - logs: - type: "fluentd" - fluentd: {} - nodeSelector: - node-role.kubernetes.io/worker: "" ----- -endif::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" <1> - namespace: "openshift-logging" <2> -spec: - managementState: "Managed" <3> - logStore: - type: "elasticsearch" <4> - retentionPolicy: - application: - maxAge: 1d - infra: - maxAge: 7d - audit: - maxAge: 7d - elasticsearch: - nodeCount: 3 - resources: - limits: - memory: 16Gi - requests: - cpu: "1" - memory: 16Gi - storage: - storageClassName: "gp2" - size: "200G" - redundancyPolicy: "SingleRedundancy" - visualization: <5> - type: "kibana" - kibana: - resources: - limits: - memory: 736Mi - requests: - cpu: 100m - memory: 736Mi - replicas: 1 - curation: <6> - type: "curator" - curator: - resources: - limits: - memory: 256Mi - requests: - cpu: 100m - memory: 256Mi - schedule: "30 3 * * *" - collection: <7> - logs: - type: "fluentd" - fluentd: - resources: - limits: - memory: 736Mi - requests: - cpu: 100m - memory: 736Mi ----- -<1> The CR name must be `instance`. -<2> The CR must be installed to the `openshift-logging` namespace. -<3> The Cluster Logging Operator management state. When set to `unmanaged` the operator is in an unsupported state and will not get updates. -<4> Settings for the log store, including retention policy, the number of nodes, the resource requests and limits, and the storage class. -<5> Settings for the visualizer, including the resource requests and limits, and the number of pod replicas. -<6> Settings for curation, including the resource requests and limits, and curation schedule. -<7> Settings for the log collector, including the resource requests and limits. -endif::[] diff --git a/modules/cluster-logging-about-curator.adoc b/modules/cluster-logging-about-curator.adoc deleted file mode 100644 index b491c0b931fb..000000000000 --- a/modules/cluster-logging-about-curator.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging.adoc - -[id="cluster-logging-about-curator_{context}"] -= About logging curation - -In {product-title} {product-version}, log curation is performed by Elasticsearch based on a xref:../logging/config/cluster-logging-log-store.html#cluster-logging-elasticsearch-retention_cluster-logging-store[retention policy] that you define. The Elasticsearch Curator tool removes Elasticsearch indices that use the data model prior to {product-title} 4.5. diff --git a/modules/cluster-logging-about-logstore.adoc b/modules/cluster-logging-about-logstore.adoc deleted file mode 100644 index 653190b41979..000000000000 --- a/modules/cluster-logging-about-logstore.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging.adoc - -[id="cluster-logging-about-logstore_{context}"] -= About the log store - -By default, {product-title} uses link:https://www.elastic.co/products/elasticsearch[Elasticsearch (ES)] to store log data. Optionally, you can use the log forwarding features to forward logs to external log stores using Fluentd protocols, syslog protocols, or the {product-title} Log Forwarding API. - -The OpenShift Logging Elasticsearch instance is optimized and tested for short term storage, approximately seven days. If you want to retain your logs over a longer term, it is recommended you move the data to a third-party storage system. - -Elasticsearch organizes the log data from Fluentd into datastores, or _indices_, then subdivides each index into multiple pieces called _shards_, which it spreads across a set of Elasticsearch nodes in an Elasticsearch cluster. You can configure Elasticsearch to make copies of the shards, called _replicas_, which Elasticsearch also spreads across the Elasticsearch nodes. The `ClusterLogging` custom resource (CR) allows you to specify how the shards are replicated to provide data redundancy and resilience to failure. You can also specify how long the different types of logs are retained using a retention policy in the `ClusterLogging` CR. - -[NOTE] -==== -The number of primary shards for the index templates is equal to the number of Elasticsearch data nodes. -==== - -The Cluster Logging Operator and companion OpenShift Elasticsearch Operator ensure that each Elasticsearch node is deployed using a unique deployment that includes its own storage volume. -You can use a `ClusterLogging` custom resource (CR) to increase the number of Elasticsearch nodes, as needed. -Refer to the link:https://www.elastic.co/guide/en/elasticsearch/guide/current/hardware.html[Elasticsearch documentation] for considerations involved in configuring storage. - -[NOTE] -==== -A highly-available Elasticsearch environment requires at least three Elasticsearch nodes, -each on a different host. -==== - -Role-based access control (RBAC) applied on the Elasticsearch indices enables the controlled access of the logs to the developers. Administrators can access all logs and developers can access only the logs in their projects. diff --git a/modules/cluster-logging-about-visualizer.adoc b/modules/cluster-logging-about-visualizer.adoc deleted file mode 100644 index 5e2853aed398..000000000000 --- a/modules/cluster-logging-about-visualizer.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging.adoc - -[id="cluster-logging-about-visualizer_{context}"] -= About logging visualization - -{product-title} uses Kibana to display the log data collected by Fluentd and indexed by Elasticsearch. - -Kibana is a browser-based console interface to query, discover, and visualize your Elasticsearch data through -histograms, line graphs, pie charts, and other visualizations. - diff --git a/modules/cluster-logging-about.adoc b/modules/cluster-logging-about.adoc deleted file mode 100644 index 2d2d469e450a..000000000000 --- a/modules/cluster-logging-about.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc -// * logging/cluster-logging.adoc -// * serverless/knative_serving/cluster-logging-serverless.adoc - -// This module uses conditionalized paragraphs so that the module -// can be re-used in associated products. - - -[id="cluster-logging-about_{context}"] -= About deploying OpenShift Logging - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -{product-title} cluster administrators can deploy OpenShift Logging using -the {product-title} web console or CLI to install the OpenShift Elasticsearch -Operator and Cluster Logging Operator. When the operators are installed, you create -a `ClusterLogging` custom resource (CR) to schedule OpenShift Logging pods and -other resources necessary to support OpenShift Logging. The operators are -responsible for deploying, upgrading, and maintaining OpenShift Logging. -endif::openshift-enterprise,openshift-webscale,openshift-origin[] - -ifdef::openshift-dedicated[] -{product-title} administrators can deploy the Cluster Logging Operator and the -OpenShift Elasticsearch Operator by using the {product-title} web console and can configure logging in the -`openshift-logging` namespace. Configuring logging will deploy Elasticsearch, -Fluentd, and Kibana in the `openshift-logging` namespace. The operators are -responsible for deploying, upgrading, and maintaining OpenShift Logging. -endif::openshift-dedicated[] - -The `ClusterLogging` CR defines a complete OpenShift Logging environment that includes all the components -of the logging stack to collect, store and visualize logs. The Cluster Logging Operator watches the OpenShift Logging -CR and adjusts the logging deployment accordingly. - -Administrators and application developers can view the logs of the projects for which they have view access. diff --git a/modules/cluster-logging-clo-status-comp.adoc b/modules/cluster-logging-clo-status-comp.adoc deleted file mode 100644 index 9729a90292be..000000000000 --- a/modules/cluster-logging-clo-status-comp.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-cluster-status.adoc - -[id="cluster-logging-clo-status-example_{context}"] -= Viewing the status of OpenShift Logging components - -You can view the status for a number of OpenShift Logging components. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Change to the `openshift-logging` project. -+ -[source,terminal] ----- -$ oc project openshift-logging ----- - -. View the status of the OpenShift Logging environment: -+ -[source,terminal] ----- -$ oc describe deployment cluster-logging-operator ----- -+ -.Example output -[source,terminal] ----- -Name: cluster-logging-operator - -.... - -Conditions: - Type Status Reason - ---- ------ ------ - Available True MinimumReplicasAvailable - Progressing True NewReplicaSetAvailable - -.... - -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal ScalingReplicaSet 62m deployment-controller Scaled up replica set cluster-logging-operator-574b8987df to 1---- ----- - -. View the status of the OpenShift Logging replica set: - -.. Get the name of a replica set: -+ -.Example output -[source,terminal] ----- -$ oc get replicaset ----- -+ -.Example output -[source,terminal] ----- -NAME DESIRED CURRENT READY AGE -cluster-logging-operator-574b8987df 1 1 1 159m -elasticsearch-cdm-uhr537yu-1-6869694fb 1 1 1 157m -elasticsearch-cdm-uhr537yu-2-857b6d676f 1 1 1 156m -elasticsearch-cdm-uhr537yu-3-5b6fdd8cfd 1 1 1 155m -kibana-5bd5544f87 1 1 1 157m ----- - -.. Get the status of the replica set: -+ -[source,terminal] ----- -$ oc describe replicaset cluster-logging-operator-574b8987df ----- -+ -.Example output -[source,terminal] ----- -Name: cluster-logging-operator-574b8987df - -.... - -Replicas: 1 current / 1 desired -Pods Status: 1 Running / 0 Waiting / 0 Succeeded / 0 Failed - -.... - -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal SuccessfulCreate 66m replicaset-controller Created pod: cluster-logging-operator-574b8987df-qjhqv---- ----- diff --git a/modules/cluster-logging-clo-status.adoc b/modules/cluster-logging-clo-status.adoc deleted file mode 100644 index 86803df1d706..000000000000 --- a/modules/cluster-logging-clo-status.adoc +++ /dev/null @@ -1,232 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-cluster-status.adoc - -[id="cluster-logging-clo-status_{context}"] -= Viewing the status of the Cluster Logging Operator - -You can view the status of your Cluster Logging Operator. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Change to the `openshift-logging` project. -+ -[source,terminal] ----- -$ oc project openshift-logging ----- - -. To view the OpenShift Logging status: - -.. Get the OpenShift Logging status: -+ -[source,terminal] ----- -$ oc get clusterlogging instance -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogging - -.... - -status: <1> - collection: - logs: - fluentdStatus: - daemonSet: fluentd <2> - nodes: - fluentd-2rhqp: ip-10-0-169-13.ec2.internal - fluentd-6fgjh: ip-10-0-165-244.ec2.internal - fluentd-6l2ff: ip-10-0-128-218.ec2.internal - fluentd-54nx5: ip-10-0-139-30.ec2.internal - fluentd-flpnn: ip-10-0-147-228.ec2.internal - fluentd-n2frh: ip-10-0-157-45.ec2.internal - pods: - failed: [] - notReady: [] - ready: - - fluentd-2rhqp - - fluentd-54nx5 - - fluentd-6fgjh - - fluentd-6l2ff - - fluentd-flpnn - - fluentd-n2frh - logstore: <3> - elasticsearchStatus: - - ShardAllocationEnabled: all - cluster: - activePrimaryShards: 5 - activeShards: 5 - initializingShards: 0 - numDataNodes: 1 - numNodes: 1 - pendingTasks: 0 - relocatingShards: 0 - status: green - unassignedShards: 0 - clusterName: elasticsearch - nodeConditions: - elasticsearch-cdm-mkkdys93-1: - nodeCount: 1 - pods: - client: - failed: - notReady: - ready: - - elasticsearch-cdm-mkkdys93-1-7f7c6-mjm7c - data: - failed: - notReady: - ready: - - elasticsearch-cdm-mkkdys93-1-7f7c6-mjm7c - master: - failed: - notReady: - ready: - - elasticsearch-cdm-mkkdys93-1-7f7c6-mjm7c -visualization: <4> - kibanaStatus: - - deployment: kibana - pods: - failed: [] - notReady: [] - ready: - - kibana-7fb4fd4cc9-f2nls - replicaSets: - - kibana-7fb4fd4cc9 - replicas: 1 ----- -<1> In the output, the cluster status fields appear in the `status` stanza. -<2> Information on the Fluentd pods. -<3> Information on the Elasticsearch pods, including Elasticsearch cluster health, `green`, `yellow`, or `red`. -<4> Information on the Kibana pods. - - -[id="cluster-logging-clo-status-message_{context}"] -== Example condition messages - -The following are examples of some condition messages from the `Status.Nodes` section of the OpenShift Logging instance. - - -// https://github.com/openshift/elasticsearch-operator/pull/92 - -A status message similar to the following indicates a node has exceeded the configured low watermark and no shard will be allocated to this node: - -.Example output -[source,yaml] ----- - nodes: - - conditions: - - lastTransitionTime: 2019-03-15T15:57:22Z - message: Disk storage usage for node is 27.5gb (36.74%). Shards will be not - be allocated on this node. - reason: Disk Watermark Low - status: "True" - type: NodeStorage - deploymentName: example-elasticsearch-clientdatamaster-0-1 - upgradeStatus: {} ----- - -A status message similar to the following indicates a node has exceeded the configured high watermark and shards will be relocated to other nodes: - -.Example output -[source,yaml] ----- - nodes: - - conditions: - - lastTransitionTime: 2019-03-15T16:04:45Z - message: Disk storage usage for node is 27.5gb (36.74%). Shards will be relocated - from this node. - reason: Disk Watermark High - status: "True" - type: NodeStorage - deploymentName: cluster-logging-operator - upgradeStatus: {} ----- - -A status message similar to the following indicates the Elasticsearch node selector in the CR does not match any nodes in the cluster: - -.Example output -[source,yaml] ----- - Elasticsearch Status: - Shard Allocation Enabled: shard allocation unknown - Cluster: - Active Primary Shards: 0 - Active Shards: 0 - Initializing Shards: 0 - Num Data Nodes: 0 - Num Nodes: 0 - Pending Tasks: 0 - Relocating Shards: 0 - Status: cluster health unknown - Unassigned Shards: 0 - Cluster Name: elasticsearch - Node Conditions: - elasticsearch-cdm-mkkdys93-1: - Last Transition Time: 2019-06-26T03:37:32Z - Message: 0/5 nodes are available: 5 node(s) didn't match node selector. - Reason: Unschedulable - Status: True - Type: Unschedulable - elasticsearch-cdm-mkkdys93-2: - Node Count: 2 - Pods: - Client: - Failed: - Not Ready: - elasticsearch-cdm-mkkdys93-1-75dd69dccd-f7f49 - elasticsearch-cdm-mkkdys93-2-67c64f5f4c-n58vl - Ready: - Data: - Failed: - Not Ready: - elasticsearch-cdm-mkkdys93-1-75dd69dccd-f7f49 - elasticsearch-cdm-mkkdys93-2-67c64f5f4c-n58vl - Ready: - Master: - Failed: - Not Ready: - elasticsearch-cdm-mkkdys93-1-75dd69dccd-f7f49 - elasticsearch-cdm-mkkdys93-2-67c64f5f4c-n58vl - Ready: ----- - -A status message similar to the following indicates that the requested PVC could not bind to PV: - -.Example output -[source,yaml] ----- - Node Conditions: - elasticsearch-cdm-mkkdys93-1: - Last Transition Time: 2019-06-26T03:37:32Z - Message: pod has unbound immediate PersistentVolumeClaims (repeated 5 times) - Reason: Unschedulable - Status: True - Type: Unschedulable ----- - -A status message similar to the following indicates that the Fluentd pods cannot be scheduled because the node selector did not match any nodes: - -.Example output -[source,yaml] ----- -Status: - Collection: - Logs: - Fluentd Status: - Daemon Set: fluentd - Nodes: - Pods: - Failed: - Not Ready: - Ready: ----- diff --git a/modules/cluster-logging-collector-alerts-viewing.adoc b/modules/cluster-logging-collector-alerts-viewing.adoc deleted file mode 100644 index a63a7401f8ad..000000000000 --- a/modules/cluster-logging-collector-alerts-viewing.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-collector-alerts-viewing_{context}"] -= Viewing logging collector alerts - -Alerts are shown in the {product-title} web console, on the *Alerts* tab of the Alerting UI. Alerts are in one of the following states: - -* *Firing*. The alert condition is true for the duration of the timeout. Click the *Options* menu at the end of the firing alert to view more information or silence the alert. -* *Pending* The alert condition is currently true, but the timeout has not been reached. -* *Not Firing*. The alert is not currently triggered. - -.Procedure - -To view OpenShift Logging and other {product-title} alerts: - -. In the {product-title} console, click *Monitoring* → *Alerting*. - -. Click the *Alerts* tab. The alerts are listed, based on the filters selected. - diff --git a/modules/cluster-logging-collector-alerts.adoc b/modules/cluster-logging-collector-alerts.adoc deleted file mode 100644 index b1790df54e2b..000000000000 --- a/modules/cluster-logging-collector-alerts.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-collector-alerts_{context}"] -= About logging collector alerts - -The following alerts are generated by the logging collector. You can view these alerts in the {product-title} web console, on the *Alerts* page of the Alerting UI. - -.Fluentd Prometheus alerts -|=== -|Alert |Message |Description |Severity - -|`FluentDHighErrorRate` -|` of records have resulted in an error by fluentd .` -|The number of FluentD output errors is high, by default more than 10 in the previous 15 minutes. -|Warning - -|`FluentdNodeDown` -|`Prometheus could not scrape fluentd for more than 10m.` -|Fluentd is reporting that Prometheus could not scrape a specific Fluentd instance. -|Critical - -|`FluentdQueueLengthBurst` -|`In the last minute, fluentd buffer queue length increased more than 32. Current value is .` -|Fluentd is reporting that it cannot keep up with the data being indexed. -|Warning - -|`FluentdQueueLengthIncreasing` -|`In the last 12h, fluentd buffer queue length constantly increased more than 1. Current value is .` -|Fluentd is reporting that the queue size is increasing. -|Critical - -|`FluentDVeryHighErrorRate` -|` of records have resulted in an error by fluentd .` -|The number of FluentD output errors is very high, by default more than 25 in the previous 15 minutes. -|Critical - -|=== - diff --git a/modules/cluster-logging-collector-legacy-fluentd.adoc b/modules/cluster-logging-collector-legacy-fluentd.adoc deleted file mode 100644 index b0453031dbb6..000000000000 --- a/modules/cluster-logging-collector-legacy-fluentd.adoc +++ /dev/null @@ -1,119 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-legacy-fluentd_{context}"] -= Forwarding logs using the legacy Fluentd method - -You can use the Fluentd *forward* protocol to send logs to destinations outside of your {product-title} cluster by creating a configuration file and config map. You are responsible for configuring the external log aggregator to receive the logs from {product-title}. - -[IMPORTANT] -==== -This method for forwarding logs is deprecated in {product-title} and will be removed in a future release. -==== - -ifdef::openshift-origin[] -The *forward* protocols are provided with the Fluentd image as of v1.4.0. -endif::openshift-origin[] - -To send logs using the Fluentd *forward* protocol, create a configuration file called `secure-forward.conf`, that points to an external log aggregator. Then, use that file to create a config map called called `secure-forward` in the `openshift-logging` project, which {product-title} uses when forwarding the logs. - -.Sample Fluentd configuration file - -[source,yaml] ----- - - @type forward - - self_hostname ${hostname} - shared_key "fluent-receiver" - - transport tls - tls_verify_hostname false - tls_cert_path '/etc/ocp-forward/ca-bundle.crt' - - @type file - path '/var/lib/fluentd/secureforwardlegacy' - queued_chunks_limit_size "1024" - chunk_limit_size "1m" - flush_interval "5s" - flush_at_shutdown "false" - flush_thread_count "2" - retry_max_interval "300" - retry_forever true - overflow_action "exception" - - - host fluent-receiver.example.com - port 24224 - - ----- - -.Procedure - -To configure {product-title} to forward logs using the legacy Fluentd method: - -. Create a configuration file named `secure-forward` and specify parameters similar to the following within the `` stanza: -+ -[source,yaml] ----- - - @type forward - - self_hostname ${hostname} - shared_key <1> - - transport tls <2> - tls_verify_hostname <3> - tls_cert_path <4> - <5> - @type file - path '/var/lib/fluentd/secureforwardlegacy' - queued_chunks_limit_size "#{ENV['BUFFER_QUEUE_LIMIT'] || '1024' }" - chunk_limit_size "#{ENV['BUFFER_SIZE_LIMIT'] || '1m' }" - flush_interval "#{ENV['FORWARD_FLUSH_INTERVAL'] || '5s'}" - flush_at_shutdown "#{ENV['FLUSH_AT_SHUTDOWN'] || 'false'}" - flush_thread_count "#{ENV['FLUSH_THREAD_COUNT'] || 2}" - retry_max_interval "#{ENV['FORWARD_RETRY_WAIT'] || '300'}" - retry_forever true - overflow_action "#{ENV['BUFFER_QUEUE_FULL_ACTION'] || 'exception'}" - - - name <6> - host <7> - hostlabel <8> - port <9> - - <10> - name - host - ----- -<1> Enter the shared key between nodes. -<2> Specify `tls` to enable TLS validation. -<3> Set to `true` to verify the server cert host name. Set to `false` to ignore server cert host name. -<4> Specify the path to the private CA certificate file as `/etc/ocp-forward/ca_cert.pem`. -<5> Specify the link:https://docs.fluentd.org/configuration/buffer-section[Fluentd buffer parameters] as needed. -<6> Optionally, enter a name for this server. -<7> Specify the host name or IP of the server. -<8> Specify the host label of the server. -<9> Specify the port of the server. -<10> Optionally, add additional servers. -If you specify two or more servers, *forward* uses these server nodes in a round-robin order. -+ -To use Mutual TLS (mTLS) authentication, see the link:https://docs.fluentd.org/output/forward#tips-and-tricks[Fluentd documentation] for information about client certificate, key parameters, and other settings. - -. Create a config map named `secure-forward` in the `openshift-logging` project from the configuration file: -+ -[source,terminal] ----- -$ oc create configmap secure-forward --from-file=secure-forward.conf -n openshift-logging ----- - -The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd pods to force them to redeploy. - -[source,terminal] ----- -$ oc delete pod --selector logging-infra=fluentd ----- diff --git a/modules/cluster-logging-collector-legacy-syslog.adoc b/modules/cluster-logging-collector-legacy-syslog.adoc deleted file mode 100644 index 6e122dea3b0a..000000000000 --- a/modules/cluster-logging-collector-legacy-syslog.adoc +++ /dev/null @@ -1,118 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-legacy-syslog_{context}"] -= Forwarding logs using the legacy syslog method - -You can use the *syslog* RFC3164 protocol to send logs to destinations outside of your {product-title} cluster by creating a configuration file and config map. You are responsible for configuring the external log aggregator to receive the logs from {product-title}. - -[IMPORTANT] -==== -This method for forwarding logs is deprecated in {product-title} and will be removed in a future release. -==== - -There are two versions of the *syslog* protocol: - -* *out_syslog*: The non-buffered implementation, which communicates through UDP, does not buffer data and writes out results immediately. -* *out_syslog_buffered*: The buffered implementation, which communicates through TCP and link:https://docs.fluentd.org/buffer[buffers data into chunks]. - -To send logs using the *syslog* protocol, create a configuration file called `syslog.conf`, with the information needed to forward the logs. Then, use that file to create a config map called `syslog` in the `openshift-logging` project, which {product-title} uses when forwarding the logs. - -.Sample syslog configuration file -[source,yaml] ----- - -@type syslog_buffered -remote_syslog rsyslogserver.example.com -port 514 -hostname ${hostname} -remove_tag_prefix tag -facility local0 -severity info -use_record true -payload_key message -rfc 3164 - ----- - -You can configure the following `syslog` parameters. For more information, see the syslog link:https://tools.ietf.org/html/rfc3164[RFC3164]. - -* facility: The link:https://tools.ietf.org/html/rfc3164#section-4.1.1[syslog facility]. The value can be a decimal integer or a case-insensitive keyword: -** `0` or `kern` for kernel messages -** `1` or `user` for user-level messages, the default. -** `2` or `mail` for the mail system -** `3` or `daemon` for the system daemons -** `4` or `auth` for the security/authentication messages -** `5` or `syslog` for messages generated internally by syslogd -** `6` or `lpr` for the line printer subsystem -** `7` or `news` for the network news subsystem -** `8` or `uucp` for the UUCP subsystem -** `9` or `cron` for the clock daemon -** `10` or `authpriv` for security authentication messages -** `11` or `ftp` for the FTP daemon -** `12` or `ntp` for the NTP subsystem -** `13` or `security` for the syslog audit logs -** `14` or `console` for the syslog alert logs -** `15` or `solaris-cron` for the scheduling daemon -** `16`–`23` or `local0` – `local7` for locally used facilities -* payloadKey: The record field to use as payload for the syslog message. -* rfc: The RFC to be used for sending log using syslog. -* severity: The link:https://tools.ietf.org/html/rfc3164#section-4.1.1[syslog severity] to set on outgoing syslog records. The value can be a decimal integer or a case-insensitive keyword: -** `0` or `Emergency` for messages indicating the system is unusable -** `1` or `Alert` for messages indicating action must be taken immediately -** `2` or `Critical` for messages indicating critical conditions -** `3` or `Error` for messages indicating error conditions -** `4` or `Warning` for messages indicating warning conditions -** `5` or `Notice` for messages indicating normal but significant conditions -** `6` or `Informational` for messages indicating informational messages -** `7` or `Debug` for messages indicating debug-level messages, the default -* tag: The record field to use as tag on the syslog message. -* trimPrefix: The prefix to remove from the tag. - -.Procedure - -To configure {product-title} to forward logs using the legacy configuration methods: - -. Create a configuration file named `syslog.conf` and specify parameters similar to the following within the `` stanza: -+ ----- - -@type <1> -remote_syslog <2> -port 514 <3> -hostname ${hostname} -remove_tag_prefix <4> -facility -severity -use_record -payload_key message -rfc 3164 <5> - ----- -<1> Specify the protocol to use, either: `syslog` or `syslog_buffered`. -<2> Specify the FQDN or IP address of the syslog server. -<3> Specify the port of the syslog server. -<4> Optional: Specify the appropriate syslog parameters, for example: -** Parameter to remove the specified `tag` field from the syslog prefix. -** Parameter to set the specified field as the syslog key. -** Parameter to specify the syslog log facility or source. -** Parameter to specify the syslog log severity. -** Parameter to use the severity and facility from the record if available. If `true`, the `container_name`, `namespace_name`, and `pod_name` are included in the output content. -** Parameter to specify the key to set the payload of the syslog message. Defaults to `message`. -<5> With the legacy syslog method, you must specify `3164` for the `rfc` value. - -. Create a config map named `syslog` in the `openshift-logging` project from the configuration file: -+ -[source,terminal] ----- -$ oc create configmap syslog --from-file=syslog.conf -n openshift-logging ----- - -The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd -pods to force them to redeploy. - -[source,terminal] ----- -$ oc delete pod --selector logging-infra=fluentd ----- diff --git a/modules/cluster-logging-collector-limits.adoc b/modules/cluster-logging-collector-limits.adoc deleted file mode 100644 index d28ddaf3599c..000000000000 --- a/modules/cluster-logging-collector-limits.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-collector-limits_{context}"] -= Configure log collector CPU and memory limits - -The log collector allows for adjustments to both the CPU and memory limits. - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc -n openshift-logging edit ClusterLogging instance ----- -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: openshift-logging - -... - -spec: - collection: - logs: - fluentd: - resources: - limits: <1> - memory: 736Mi - requests: - cpu: 100m - memory: 736Mi ----- -<1> Specify the CPU and memory limits and requests as needed. The values shown are the default values. diff --git a/modules/cluster-logging-collector-log-forward-es.adoc b/modules/cluster-logging-collector-log-forward-es.adoc deleted file mode 100644 index 825443351397..000000000000 --- a/modules/cluster-logging-collector-log-forward-es.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-log-forward-es_{context}"] -= Forwarding logs to an external Elasticsearch instance - -You can optionally forward logs to an external Elasticsearch instance in addition to, or instead of, the internal {product-title} Elasticsearch instance. You are responsible for configuring the external log aggregator to receive the logs from {product-title}. - -To configure log forwarding to an external Elasticsearch instance, create a `ClusterLogForwarder` custom resource (CR) with an output to that instance and a pipeline that uses the output. The external Elasticsearch output can use the HTTP (insecure) or HTTPS (secure HTTP) connection. - -To forward logs to both an external and the internal Elasticsearch instance, create outputs and pipelines to the external instance and a pipeline that uses the `default` output to forward logs to the internal instance. You do not need to create a `default` output. If you do configure a `default` output, you receive an error message because the `default` output is reserved for the Cluster Logging Operator. - -[NOTE] -==== -If you want to forward logs to *only* the internal {product-title} Elasticsearch instance, you do not need to create a `ClusterLogForwarder` CR. -==== - -.Procedure - -. Create a `ClusterLogForwarder` CR YAML file similar to the following: -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: ClusterLogForwarder -metadata: - name: instance <1> - namespace: openshift-logging <2> -spec: - outputs: - - name: elasticsearch-insecure <3> - type: "elasticsearch" <4> - url: http://elasticsearch.insecure.com:9200 <5> - - name: elasticsearch-secure - type: "elasticsearch" - url: https://elasticsearch.secure.com:9200 - secret: - name: es-secret <6> - pipelines: - - name: application-logs <7> - inputRefs: <8> - - application - - audit - outputRefs: - - elasticsearch-secure <9> - - default <10> - labels: - logs: application <11> - - name: infrastructure-audit-logs <12> - inputRefs: - - infrastructure - outputRefs: - - elasticsearch-insecure - labels: - logs: audit-infra ----- -<1> The name of the `ClusterLogForwarder` CR must be `instance`. -<2> The namespace for the `ClusterLogForwarder` CR must be `openshift-logging`. -<3> Specify a name for the output. -<4> Specify the `elasticsearch` type. -<5> Specify the URL and port of the external Elasticsearch instance as a valid absolute URL. You can use the `http` (insecure) or `https` (secure HTTP) protocol. If the cluster-wide proxy using the CIDR annotation is enabled, the output must be a server name or FQDN, not an IP Address. -<6> If using an `https` prefix, you must specify the name of the secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project and must have keys of: *tls.crt*, *tls.key*, and *ca-bundle.crt* that point to the respective certificates that they represent. -<7> Optional: Specify a name for the pipeline. -<8> Specify which log types should be forwarded using that pipeline: `application,` `infrastructure`, or `audit`. -<9> Specify the output to use with that pipeline for forwarding the logs. -<10> Optional: Specify the `default` output to send the logs to the internal Elasticsearch instance. -<11> Optional: One or more labels to add to the logs. -<12> Optional: Configure multiple outputs to forward logs to other external log aggregtors of any supported type: -** Optional. A name to describe the pipeline. -** The `inputRefs` is the log type to forward using that pipeline: `application,` `infrastructure`, or `audit`. -** The `outputRefs` is the name of the output to use. -** Optional: One or more labels to add to the logs. - -. Create the CR object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- - -The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd -pods to force them to redeploy. - -[source,terminal] ----- -$ oc delete pod --selector logging-infra=fluentd ----- diff --git a/modules/cluster-logging-collector-log-forward-fluentd.adoc b/modules/cluster-logging-collector-log-forward-fluentd.adoc deleted file mode 100644 index 2366eeec7fe1..000000000000 --- a/modules/cluster-logging-collector-log-forward-fluentd.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-log-forward-fluentd_{context}"] -= Forwarding logs using the Fluentd forward protocol - -You can use the Fluentd *forward* protocol to send a copy of your logs to an external log aggregator configured to accept the protocol instead of, or in addition to, the default Elasticsearch log store. You are responsible for configuring the external log aggregator to receive the logs from {product-title}. - -To configure log forwarding using the *forward* protocol, create a `ClusterLogForwarder` custom resource (CR) with one or more outputs to the Fluentd servers and pipelines that use those outputs. The Fluentd output can use a TCP (insecure) or TLS (secure TCP) connection. - -[NOTE] -==== -Alternately, you can use a config map to forward logs using the *forward* protocols. However, this method is deprecated in {product-title} and will be removed in a future release. -==== - -.Procedure - -. Create a `ClusterLogForwarder` CR YAML file similar to the following: -+ -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogForwarder -metadata: - name: instance <1> - namespace: openshift-logging <2> -spec: - outputs: - - name: fluentd-server-secure <3> - type: fluentdForward <4> - url: 'tls://fluentdserver.security.example.com:24224' <5> - secret: <6> - name: fluentd-secret - - name: fluentd-server-insecure - type: fluentdForward - url: 'tcp://fluentdserver.home.example.com:24224' - pipelines: - - name: forward-to-fluentd-secure <7> - inputRefs: <8> - - application - - audit - outputRefs: - - fluentd-server-secure <9> - - default <10> - labels: - clusterId: C1234 <11> - - name: forward-to-fluentd-insecure <12> - inputRefs: - - infrastructure - outputRefs: - - fluentd-server-insecure - labels: - clusterId: C1234 ----- -<1> The name of the `ClusterLogForwarder` CR must be `instance`. -<2> The namespace for the `ClusterLogForwarder` CR must be `openshift-logging`. -<3> Specify a name for the output. -<4> Specify the `fluentdForward` type. -<5> Specify the URL and port of the external Fluentd instance as a valid absolute URL. You can use the `tcp` (insecure) or `tls` (secure TCP) protocol. If the cluster-wide proxy using the CIDR annotation is enabled, the output must be a server name or FQDN, not an IP address. -<6> If using a `tls` prefix, you must specify the name of the secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project and must have keys of: *tls.crt*, *tls.key*, and *ca-bundle.crt* that point to the respective certificates that they represent. -<7> Optional. Specify a name for the pipeline. -<8> Specify which log types should be forwarded using that pipeline: `application,` `infrastructure`, or `audit`. -<9> Specify the output to use with that pipeline for forwarding the logs. -<10> Optional. Specify the `default` output to forward logs to the internal Elasticsearch instance. -<11> Optional. One or more labels to add to the logs. -<12> Optional: Configure multiple outputs to forward logs to other external log aggregtors of any supported type: -** Optional. A name to describe the pipeline. -** The `inputRefs` is the log type to forward using that pipeline: `application,` `infrastructure`, or `audit`. -** The `outputRefs` is the name of the output to use. -** Optional: One or more labels to add to the logs. - -. Create the CR object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- - -The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd -pods to force them to redeploy. - -[source,terminal] ----- -$ oc delete pod --selector logging-infra=fluentd ----- diff --git a/modules/cluster-logging-collector-log-forward-kafka.adoc b/modules/cluster-logging-collector-log-forward-kafka.adoc deleted file mode 100644 index 6fecdf9cc8d0..000000000000 --- a/modules/cluster-logging-collector-log-forward-kafka.adoc +++ /dev/null @@ -1,115 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-log-forward-kafka_{context}"] -= Forwarding logs to a Kafka broker - -You can forward logs to an external Kafka broker in addition to, or instead of, the default Elasticsearch log store. - -To configure log forwarding to an external Kafka instance, create a `ClusterLogForwarder` custom resource (CR) with an output to that instance and a pipeline that uses the output. You can include a specific Kafka topic in the output or use the default. The Kafka output can use a TCP (insecure) or TLS (secure TCP) connection. - -.Procedure - -. Create a `ClusterLogForwarder` CR YAML file similar to the following: -+ -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogForwarder -metadata: - name: instance <1> - namespace: openshift-logging <2> -spec: - outputs: - - name: app-logs <3> - type: kafka <4> - url: tls://kafka.example.devlab.com:9093/app-topic <5> - secret: - name: kafka-secret <6> - - name: infra-logs - type: kafka - url: tcp://kafka.devlab2.example.com:9093/infra-topic <7> - - name: audit-logs - type: kafka - url: tls://kafka.qelab.example.com:9093/audit-topic - secret: - name: kafka-secret-qe - pipelines: - - name: app-topic <8> - inputRefs: <9> - - application - outputRefs: <10> - - app-logs - labels: - logType: application <11> - - name: infra-topic <12> - inputRefs: - - infrastructure - outputRefs: - - infra-logs - labels: - logType: infra - - name: audit-topic - inputRefs: - - audit - outputRefs: - - audit-logs - - default <13> - labels: - logType: audit ----- -<1> The name of the `ClusterLogForwarder` CR must be `instance`. -<2> The namespace for the `ClusterLogForwarder` CR must be `openshift-logging`. -<3> Specify a name for the output. -<4> Specify the `kafka` type. -<5> Specify the URL and port of the Kafka broker as a valid absolute URL, optionally with a specific topic. You can use the `tcp` (insecure) or `tls` (secure TCP) protocol. If the cluster-wide proxy using the CIDR annotation is enabled, the output must be a server name or FQDN, not an IP address. -<6> If using a `tls` prefix, you must specify the name of the secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project and must have keys of: *tls.crt*, *tls.key*, and *ca-bundle.crt* that point to the respective certificates that they represent. -<7> Optional: To send an insecure output, use a `tcp` prefix in front of the URL. Also omit the `secret` key and its `name` from this output. -<8> Optional: Specify a name for the pipeline. -<9> Specify which log types should be forwarded using that pipeline: `application,` `infrastructure`, or `audit`. -<10> Specify the output to use with that pipeline for forwarding the logs. -<11> Optional: One or more labels to add to the logs. -<12> Optional: Configure multiple outputs to forward logs to other external log aggregtors of any supported type: -** Optional. A name to describe the pipeline. -** The `inputRefs` is the log type to forward using that pipeline: `application,` `infrastructure`, or `audit`. -** The `outputRefs` is the name of the output to use. -** Optional: One or more labels to add to the logs. -<13> Optional: Specify `default` to forward logs to the internal Elasticsearch instance. - -. Optional: To forward a single output to multiple kafka brokers, specify an array of kafka brokers as shown in this example: -+ -[source,yaml] ----- -... -spec: - outputs: - - name: app-logs - type: kafka - secret: - name: kafka-secret-dev - kafka: <1> - brokers: <2> - - tls://kafka-broker1.example.com:9093/ - - tls://kafka-broker2.example.com:9093/ - topic: app-topic <3> -... ----- -<1> Specify a `kafka` key that has a `brokers` and `topic` key. -<2> Use the `brokers` key to specify an array of one or more brokers. -<3> Use the `topic` key to specify the target topic that will receive the logs. - -. Create the CR object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- - -The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd -pods to force them to redeploy. - -[source,terminal] ----- -$ oc delete pod --selector logging-infra=fluentd ----- diff --git a/modules/cluster-logging-collector-log-forward-project.adoc b/modules/cluster-logging-collector-log-forward-project.adoc deleted file mode 100644 index ca26a489a66c..000000000000 --- a/modules/cluster-logging-collector-log-forward-project.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-log-forward-project_{context}"] -= Forwarding application logs from specific projects - -You can use the Log forwarding API to send a copy of the application logs from specific projects to an external log aggregator instead of, or in addition to, the default Elasticsearch log store. You are responsible for configuring the external log aggregator to receive the logs from {product-title}. - -To configure forwarding application logs from a project, create a `ClusterLogForwarder` custom resource (CR) with at least one input from a project, optional outputs for other log aggregators, and pipelines that use those inputs and outputs. - -.Procedure - -. Create a `ClusterLogForwarder` CR YAML file similar to the following: -+ -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogForwarder -metadata: - name: instance <1> - namespace: openshift-logging <2> -spec: - outputs: - - name: fluentd-server-secure <3> - type: fluentdForward <4> - url: 'tls://fluentdserver.security.example.com:24224' <5> - secret: <6> - name: fluentd-secret - - name: fluentd-server-insecure - type: fluentdForward - url: 'tcp://fluentdserver.home.example.com:24224' - inputs: <7> - - name: my-app-logs - application: - namespaces: - - my-project - pipelines: - - name: forward-to-fluentd-insecure <8> - inputRefs: <9> - - my-app-logs - outputRefs: <10> - - fluentd-server-insecure - labels: <11> - project: my-project - - name: forward-to-fluentd-secure <12> - inputRefs: - - application - - audit - - infrastructure - outputRefs: - - fluentd-server-secure - - default - labels: - clusterId: C1234 ----- -<1> The name of the `ClusterLogForwarder` CR must be `instance`. -<2> The namespace for the `ClusterLogForwarder` CR must be `openshift-logging`. -<3> Specify a name for the output. -<4> Specify the output type: `elasticsearch`, `fluentdForward`, `syslog`, or `kafka`. -<5> Specify the URL and port of the external log aggregator as a valid absolute URL. If the cluster-wide proxy using the CIDR annotation is enabled, the output must be a server name or FQDN, not an IP address. -<6> If using a `tls` prefix, you must specify the name of the secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project and must have keys of: *tls.crt*, *tls.key*, and *ca-bundle.crt* that point to the respective certificates that they represent. -<7> Configuration for an input to filter application logs from the specified projects. -<8> Configuration for a pipeline to use the input to send project application logs to an external Fluentd instance. -<9> The `my-app-logs` input. -<10> The name of the output to use. -<11> Optional: A label to add to the logs. -<12> Configuration for a pipeline to send logs to other log aggregators. -** Optional: Specify a name for the pipeline. -** Specify which log types should be forwarded using that pipeline: `application,` `infrastructure`, or `audit`. -** Specify the output to use with that pipeline for forwarding the logs. -** Optional: Specify the `default` output to forward logs to the internal Elasticsearch instance. -** Optional: One or more labels to add to the logs. - -. Create the CR object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- diff --git a/modules/cluster-logging-collector-log-forward-syslog.adoc b/modules/cluster-logging-collector-log-forward-syslog.adoc deleted file mode 100644 index 48558a5e34f9..000000000000 --- a/modules/cluster-logging-collector-log-forward-syslog.adoc +++ /dev/null @@ -1,153 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-log-forward-syslog_{context}"] -= Forwarding logs using the syslog protocol - -You can use the *syslog* link:https://tools.ietf.org/html/rfc3164[RFC3164] or link:https://tools.ietf.org/html/rfc5424[RFC5424] protocol to send a copy of your logs to an external log aggregator configured to accept the protocol instead of, or in addition to, the default Elasticsearch log store. You are responsible for configuring the external log aggregator to receive the logs from {product-title}. - -To configure log forwarding using the *syslog* protocol, create a `ClusterLogForwarder` custom resource (CR) with one or more outputs to the syslog servers and pipelines that use those outputs. The syslog output can use a UDP, TCP, or TLS connection. - -[NOTE] -==== -Alternately, you can use a config map to forward logs using the *syslog* RFC3164 protocols. However, this method is deprecated in {product-title} and will be removed in a future release. -==== - -.Procedure - -. Create a `ClusterLogForwarder` CR YAML file similar to the following: -+ -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogForwarder -metadata: - name: instance <1> - namespace: openshift-logging <2> -spec: - outputs: - - name: rsyslog-east <3> - type: syslog <4> - syslog: <5> - facility: local0 - rfc: RFC3164 - payloadKey: message - severity: informational - url: 'tls://rsyslogserver.east.example.com:514' <6> - secret: <7> - name: syslog-secret - - name: rsyslog-west - type: syslog - syslog: - appName: myapp - facility: user - msgID: mymsg - procID: myproc - rfc: RFC5424 - severity: debug - url: 'udp://rsyslogserver.west.example.com:514' - pipelines: - - name: syslog-east <8> - inputRefs: <9> - - audit - - application - outputRefs: <10> - - rsyslog-east - - default <11> - labels: - syslog: east <12> - secure: true - - name: syslog-west <13> - inputRefs: - - infrastructure - outputRefs: - - rsyslog-west - - default - labels: - syslog: west ----- -<1> The name of the `ClusterLogForwarder` CR must be `instance`. -<2> The namespace for the `ClusterLogForwarder` CR must be `openshift-logging`. -<3> Specify a name for the output. -<4> Specify the `syslog` type. -<5> Optional. Specify the syslog parameters, listed below. -<6> Specify the URL and port of the external syslog instance. You can use the `udp` (insecure), `tcp` (insecure) or `tls` (secure TCP) protocol. If the cluster-wide proxy using the CIDR annotation is enabled, the output must be a server name or FQDN, not an IP address. -<7> If using a `tls` prefix, you must specify the name of the secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project and must have keys of: *tls.crt*, *tls.key*, and *ca-bundle.crt* that point to the respective certificates that they represent. -<8> Optional: Specify a name for the pipeline. -<9> Specify which log types should be forwarded using that pipeline: `application,` `infrastructure`, or `audit`. -<10> Specify the output to use with that pipeline for forwarding the logs. -<11> Optional: Specify the `default` output to forward logs to the internal Elasticsearch instance. -<12> Optional: One or more labels to add to the logs. -<13> Optional: Configure multiple outputs to forward logs to other external log aggregtors of any supported type: -** Optional. A name to describe the pipeline. -** The `inputRefs` is the log type to forward using that pipeline: `application,` `infrastructure`, or `audit`. -** The `outputRefs` is the name of the output to use. -** Optional: One or more labels to add to the logs. - -. Create the CR object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- - -The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd -pods to force them to redeploy. - -[source,terminal] ----- -$ oc delete pod --selector logging-infra=fluentd ----- - -[id=cluster-logging-collector-log-forward-examples-syslog-parms] -== Syslog parameters - -You can configure the following for the `syslog` outputs. For more information, see the syslog link:https://tools.ietf.org/html/rfc3164[RFC3164] or link:https://tools.ietf.org/html/rfc5424[RFC5424] RFC. - -* facility: The link:https://tools.ietf.org/html/rfc5424#section-6.2.1[syslog facility]. The value can be a decimal integer or a case-insensitive keyword: -** `0` or `kern` for kernel messages -** `1` or `user` for user-level messages, the default. -** `2` or `mail` for the mail system -** `3` or `daemon` for system daemons -** `4` or `auth` for security/authentication messages -** `5` or `syslog` for messages generated internally by syslogd -** `6` or `lpr` for line printer subsystem -** `7` or `news` for the network news subsystem -** `8` or `uucp` for the UUCP subsystem -** `9` or `cron` for the clock daemon -** `10` or `authpriv` for security authentication messages -** `11` or `ftp` for the FTP daemon -** `12` or `ntp` for the NTP subsystem -** `13` or `security` for the syslog audit log -** `14` or `console` for the syslog alert log -** `15` or `solaris-cron` for the scheduling daemon -** `16`–`23` or `local0` – `local7` for locally used facilities -* Optional. `payloadKey`: The record field to use as payload for the syslog message. -+ -[NOTE] -==== -Configuring the `payloadKey` parameter prevents other parameters from being forwarded to the syslog. -==== -+ -* rfc: The RFC to be used for sending log using syslog. The default is RFC5424. -* severity: The link:https://tools.ietf.org/html/rfc5424#section-6.2.1[syslog severity] to set on outgoing syslog records. The value can be a decimal integer or a case-insensitive keyword: -** `0` or `Emergency` for messages indicating the system is unusable -** `1` or `Alert` for messages indicating action must be taken immediately -** `2` or `Critical` for messages indicating critical conditions -** `3` or `Error` for messages indicating error conditions -** `4` or `Warning` for messages indicating warning conditions -** `5` or `Notice` for messages indicating normal but significant conditions -** `6` or `Informational` for messages indicating informational messages -** `7` or `Debug` for messages indicating debug-level messages, the default -* tag: Tag specifies a record field to use as tag on the syslog message. -* trimPrefix: Remove the specified prefix from the tag. - -[id=cluster-logging-collector-log-forward-examples-syslog-5424] -== Additional RFC5424 syslog parameters - -The following parameters apply to RFC5424: - -* appName: The APP-NAME is a free-text string that identifies the application that sent the log. Must be specified for `RFC5424`. -* msgID: The MSGID is a free-text string that identifies the type of message. Must be specified for `RFC5424`. -* procID: The PROCID is a free-text string. A a change in the value indicates a discontinuity in syslog reporting. Must be specified for `RFC5424`. diff --git a/modules/cluster-logging-collector-log-forwarding-about.adoc b/modules/cluster-logging-collector-log-forwarding-about.adoc deleted file mode 100644 index b839b8cd755d..000000000000 --- a/modules/cluster-logging-collector-log-forwarding-about.adoc +++ /dev/null @@ -1,149 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-log-forwarding-about_{context}"] -= About forwarding logs to third-party systems - -Forwarding cluster logs to external third-party systems requires a combination of _outputs_ and _pipelines_ specified in a `ClusterLogForwarder` custom resource (CR) to send logs to specific endpoints inside and outside of your {product-title} cluster. You can also use _inputs_ to forward the application logs associated with a specific project to an endpoint. - -* An _output_ is the destination for log data that you define, or where you want the logs sent. An output can be one of the following types: -+ --- -* `elasticsearch`. An external Elasticsearch instance. The `elasticsearch` output can use a TLS connection. - -* `fluentdForward`. An external log aggregation solution that supports Fluentd. This option uses the Fluentd *forward* protocols. The `fluentForward` output can use a TCP or TLS connection and supports shared-key authentication by providing a *shared_key* field in a secret. Shared-key authentication can be used with or without TLS. - -* `syslog`. An external log aggregation solution that supports the syslog link:https://tools.ietf.org/html/rfc3164[RFC3164] or link:https://tools.ietf.org/html/rfc5424[RFC5424] protocols. The `syslog` output can use a UDP, TCP, or TLS connection. - -* `kafka`. A Kafka broker. The `kafka` output can use a TCP or TLS connection. - -* `default`. The internal {product-title} Elasticsearch instance. You are not required to configure the default output. If you do configure a `default` output, you receive an error message because the `default` output is reserved for the Cluster Logging Operator. --- -+ -If the output URL scheme requires TLS (HTTPS, TLS, or UDPS), then TLS server-side authentication is enabled. To also enable client authentication, the output must name a secret in the `openshift-logging` project. The secret must have keys of: *tls.crt*, *tls.key*, and *ca-bundle.crt* that point to the respective certificates that they represent. - -* A _pipeline_ defines simple routing from one log type to one or more outputs, or which logs you want to send. The log types are one of the following: -+ --- -* `application`. Container logs generated by user applications running in the cluster, except infrastructure container applications. - -* `infrastructure`. Container logs from pods that run in the `openshift*`, `kube*`, or `default` projects and journal logs sourced from node file system. - -* `audit`. Logs generated by auditd, the node audit system, and the audit logs from the Kubernetes API server and the OpenShift API server. --- -+ -You can add labels to outbound log messages by using `key:value` pairs in the pipeline. For example, you might add a label to messages that are forwarded to others data centers or label the logs by type. Labels that are added to objects are also forwarded with the log message. - -* An _input_ forwards the application logs associated with a specific project to a pipeline. - -In the pipeline, you define which log types to forward using an `inputRef` parameter and where to forward the logs to using an `outputRef` parameter. - -Note the following: - -* If a `ClusterLogForwarder` object exists, logs are not forwarded to the default Elasticsearch instance, unless there is a pipeline with the `default` output. - -* By default, OpenShift Logging sends container and infrastructure logs to the default internal Elasticsearch log store defined in the `ClusterLogging` custom resource. However, it does not send audit logs to the internal store because it does not provide secure storage. If this default configuration meets your needs, do not configure the Log Forwarding API. - -* If you do not define a pipeline for a log type, the logs of the undefined types are dropped. For example, if you specify a pipeline for the `application` and `audit` types, but do not specify a pipeline for the `infrastructure` type, `infrastructure` logs are dropped. - -* You can use multiple types of outputs in the `ClusterLogForwarder` custom resource (CR) to send logs to servers that support different protocols. - -* The internal {product-title} Elasticsearch instance does not provide secure storage for audit logs. We recommend you ensure that the system to which you forward audit logs is compliant with your organizational and governmental regulations and is properly secured. OpenShift Logging does not comply with those regulations. - -* You are responsible for creating and maintaining any additional configurations that external destinations might require, such as keys and secrets, service accounts, port openings, or global proxy configuration. - -The following example forwards the audit logs to a secure external Elasticsearch instance, the infrastructure logs to an insecure external Elasticsearch instance, the application logs to a Kafka broker, and the application logs from the `my-apps-logs` project to the internal Elasticsearch instance. - -.Sample log forwarding outputs and pipelines -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: ClusterLogForwarder -metadata: - name: instance <1> - namespace: openshift-logging <2> -spec: - outputs: - - name: elasticsearch-secure <3> - type: "elasticsearch" - url: https://elasticsearch.secure.com:9200 - secret: - name: elasticsearch - - name: elasticsearch-insecure <4> - type: "elasticsearch" - url: http://elasticsearch.insecure.com:9200 - - name: kafka-app <5> - type: "kafka" - url: tls://kafka.secure.com:9093/app-topic - inputs: <6> - - name: my-app-logs - application: - namespaces: - - my-project - pipelines: - - name: audit-logs <7> - inputRefs: - - audit - outputRefs: - - elasticsearch-secure - - default - labels: - datacenter: east - secure: true - - name: infrastructure-logs <8> - inputRefs: - - infrastructure - outputRefs: - - elasticsearch-insecure - labels: - datacenter: west - - name: my-app <9> - inputRefs: - - my-app-logs - outputRefs: - - default - - inputRefs: <10> - - application - outputRefs: - - kafka-app - labels: - datacenter: south ----- -<1> The name of the `ClusterLogForwarder` CR must be `instance`. -<2> The namespace for the `ClusterLogForwarder` CR must be `openshift-logging`. -<3> Configuration for an secure Elasticsearch output using a secret with a secure URL. -** A name to describe the output. -** The type of output: `elasticsearch`. -** The secure URL and port of the Elasticsearch instance as a valid absolute URL, including the prefix. -** The secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project. -<4> Configuration for an insecure Elasticsearch output: -** A name to describe the output. -** The type of output: `elasticsearch`. -** The insecure URL and port of the Elasticsearch instance as a valid absolute URL, including the prefix. -<5> Configuration for a Kafka output using a client-authenticated TLS communication over a secure URL -** A name to describe the output. -** The type of output: `kafka`. -** Specify the URL and port of the Kafka broker as a valid absolute URL, including the prefix. -<6> Configuration for an input to filter application logs from the `my-namespace` project. -<7> Configuration for a pipeline to send audit logs to the secure external Elasticsearch instance: -** Optional. A name to describe the pipeline. -** The `inputRefs` is the log type, in this example `audit`. -** The `outputRefs` is the name of the output to use, in this example `elasticsearch-secure` to forward to the secure Elasticsearch instance and `default` to forward to the internal Elasticsearch instance. -** Optional: Labels to add to the logs. -<8> Configuration for a pipeline to send infrastructure logs to the insecure external Elasticsearch instance: -<9> Configuration for a pipeline to send logs from the `my-project` project to the internal Elasticsearch instance. -** Optional. A name to describe the pipeline. -** The `inputRefs` is a specific input: `my-app-logs`. -** The `outputRefs` is `default`. -** Optional: A label to add to the logs. -<10> Configuration for a pipeline to send logs to the Kafka broker, with no pipeline name: -** The `inputRefs` is the log type, in this example `application`. -** The `outputRefs` is the name of the output to use. -** Optional: A label to add to the logs. - -[discrete] -[id="cluster-logging-external-fluentd"] -== Fluentd log handling when the external log aggregator is unavailable - -If your external logging aggregator becomes unavailable and cannot receive logs, Fluentd continues to collect logs and stores them in a buffer. When the log aggregator becomes available, log forwarding resumes, including the buffered logs. If the buffer fills completely, Fluentd stops collecting logs. {product-title} rotates the logs and deletes them. You cannot adjust the buffer size or add a persistent volume claim (PVC) to the Fluentd daemon set or pods. diff --git a/modules/cluster-logging-collector-log-forwarding-supported-plugins.adoc b/modules/cluster-logging-collector-log-forwarding-supported-plugins.adoc deleted file mode 100644 index 41fa996c79bd..000000000000 --- a/modules/cluster-logging-collector-log-forwarding-supported-plugins.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// logging/cluster-logging-external.adoc - -[id="cluster-logging-collector-log-forwarding-supported-plugins_{context}"] - -= Supported log data output types - -Red Hat OpenShift Logging version 5.0 provides the following output types and protocols for sending log data to target log collectors. - -Red Hat tests each of the combinations shown in the following table. However, you should be able to send log data to a wider range target log collectors that ingest these protocols. - -[options="header"] -|==== -| Output types | Protocols | Tested with - -| fluentdForward -| fluentd forward v1 -a| fluentd 1.7.4 - -logstash 7.10.1 - -| elasticsearch -| elasticsearch -a| Elasticsearch 6.8.1 - -Elasticsearch 7.10.1 - -| syslog -| RFC-3164, RFC-5424 -| rsyslog 8.37.0-9.el7 - -| kafka -| kafka 0.11 -| kafka 2.4.1 - -|==== - -// Note to tech writer, validate these items against the corresponding line of the test configuration file that Red Hat OpenShift Logging version 5.0 uses: https://github.com/openshift/origin-aggregated-logging/blob/release-5.0/fluentd/Gemfile.lock -// This file is the authoritative source of information about which items and versions Red Hat tests and supports. -// According to this link:https://github.com/zendesk/ruby-kafka#compatibility[Zendesk compatibility list for ruby-kafka], the fluent-plugin-kafka plug-in supports Kafka version 0.11. - -[NOTE] -==== -Previously, the syslog output supported only RFC-3164. The current syslog output adds support for RFC-5424. -==== diff --git a/modules/cluster-logging-collector-pod-location.adoc b/modules/cluster-logging-collector-pod-location.adoc deleted file mode 100644 index 4a92b84b4af9..000000000000 --- a/modules/cluster-logging-collector-pod-location.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-collector-pod-location_{context}"] -= Viewing logging collector pods - -You can view the Fluentd logging collector pods and the corresponding nodes that they are running on. The Fluentd logging collector pods run only in the `openshift-logging` project. - -.Procedure - -* Run the following command in the `openshift-logging` project to view the Fluentd logging collector pods and their details: - -[source,terminal] ----- -$ oc get pods --selector component=fluentd -o wide -n openshift-logging ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -fluentd-8d69v 1/1 Running 0 134m 10.130.2.30 master1.example.com -fluentd-bd225 1/1 Running 0 134m 10.131.1.11 master2.example.com -fluentd-cvrzs 1/1 Running 0 134m 10.130.0.21 master3.example.com -fluentd-gpqg2 1/1 Running 0 134m 10.128.2.27 worker1.example.com -fluentd-l9j7j 1/1 Running 0 134m 10.129.2.31 worker2.example.com ----- - -//// -[source,terminal] ----- -$ oc get pods -o wide | grep rsyslog ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -rsyslog-5gtfs 1/1 Running 0 3m6s 10.130.0.40 ip-10-0-148-139.ec2.internal -rsyslog-67rv6 1/1 Running 0 3m6s 10.128.2.13 ip-10-0-158-206.ec2.internal -rsyslog-bqgjn 1/1 Running 0 3m6s 10.131.0.11 ip-10-0-132-167.ec2.internal -rsyslog-cjmdp 1/1 Running 0 3m6s 10.129.2.16 ip-10-0-139-191.ec2.internal -rsyslog-kqlzh 1/1 Running 0 3m6s 10.129.0.37 ip-10-0-141-243.ec2.internal -rsyslog-nhshr 1/1 Running 0 3m6s 10.128.0.41 ip-10-0-143-38.ec2.internal ----- -//// diff --git a/modules/cluster-logging-collector-tolerations.adoc b/modules/cluster-logging-collector-tolerations.adoc deleted file mode 100644 index 143edbf79515..000000000000 --- a/modules/cluster-logging-collector-tolerations.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-collector-tolerations_{context}"] -= Using tolerations to control the log collector pod placement - -You can ensure which nodes the logging collector pods run on and prevent -other workloads from using those nodes by using tolerations on the pods. - -You apply tolerations to logging collector pods through the `ClusterLogging` custom resource (CR) -and apply taints to a node through the node specification. You can use taints and tolerations -to ensure the pod does not get evicted for things like memory and CPU issues. - -By default, the logging collector pods have the following toleration: - -[source,yaml] ----- -tolerations: -- key: "node-role.kubernetes.io/master" - operator: "Exists" - effect: "NoExecute" ----- - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Use the following command to add a taint to a node where you want logging collector pods to schedule logging collector pods: -+ -[source,terminal] ----- -$ oc adm taint nodes =: ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm taint nodes node1 collector=node:NoExecute ----- -+ -This example places a taint on `node1` that has key `collector`, value `node`, and taint effect `NoExecute`. -You must use the `NoExecute` taint effect. `NoExecute` schedules only pods that match the taint and removes existing pods -that do not match. - -. Edit the `collection` stanza of the `ClusterLogging` custom resource (CR) to configure a toleration for the logging collector pods: -+ -[source,yaml] ----- - collection: - logs: - type: "fluentd" - fluentd: - tolerations: - - key: "collector" <1> - operator: "Exists" <2> - effect: "NoExecute" <3> - tolerationSeconds: 6000 <4> ----- -<1> Specify the key that you added to the node. -<2> Specify the `Exists` operator to require the `key`/`value`/`effect` parameters to match. -<3> Specify the `NoExecute` effect. -<4> Optionally, specify the `tolerationSeconds` parameter to set how long a pod can remain bound to a node before being evicted. - -This toleration matches the taint created by the `oc adm taint` command. A pod with this toleration would be able to schedule onto `node1`. diff --git a/modules/cluster-logging-collector-tuning.adoc b/modules/cluster-logging-collector-tuning.adoc deleted file mode 100644 index 7985f96cc150..000000000000 --- a/modules/cluster-logging-collector-tuning.adoc +++ /dev/null @@ -1,169 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-collector-tuning_{context}"] -= Advanced configuration for the log forwarder - -OpenShift Logging includes multiple Fluentd parameters that you can use for tuning the performance of the Fluentd log forwarder. With these parameters, you can change the following Fluentd behaviors: - -* the size of Fluentd chunks and chunk buffer -* the Fluentd chunk flushing behavior -* the Fluentd chunk forwarding retry behavior - -Fluentd collects log data in a single blob called a _chunk_. When Fluentd creates a chunk, the chunk is considered to be in the _stage_, where the chunk gets filled with data. When the chunk is full, Fluentd moves the chunk to the _queue_, where chunks are held before being flushed, or written out to their destination. Fluentd can fail to flush a chunk for a number of reasons, such as network issues or capacity issues at the destination. If a chunk cannot be flushed, Fluentd retries flushing as configured. - -By default in {product-title}, Fluentd uses the _exponential backoff_ method to retry flushing, where Fluentd doubles the time it waits between attempts to retry flushing again, which helps reduce connection requests to the destination. You can disable exponential backoff and use the _periodic_ retry method instead, which retries flushing the chunks at a specified interval. By default, Fluentd retries chunk flushing indefinitely. In {product-title}, you cannot change the indefinite retry behavior. - -These parameters can help you determine the trade-offs between latency and throughput. - -* To optimize Fluentd for throughput, you could use these parameters to reduce network packet count by configuring larger buffers and queues, delaying flushes, and setting longer times between retries. Be aware that larger buffers require more space on the node file system. - -* To optimize for low latency, you could use the parameters to send data as soon as possible, avoid the build-up of batches, have shorter queues and buffers, and use more frequent flush and retries. - -You can configure the chunking and flushing behavior using the following parameters in the `ClusterLogging` custom resource (CR). The parameters are then automatically added to the Fluentd config map for use by Fluentd. - -[NOTE] -==== -These parameters are: - -* Not relevant to most users. The default settings should give good general performance. -* Only for advanced users with detailed knowledge of Fluentd configuration and performance. -* Only for performance tuning. They have no effect on functional aspects of logging. -==== - -.Advanced Fluentd Configuration Parameters -[options="header"] -|=== - -|Parmeter |Description |Default - -|`chunkLimitSize` -|The maximum size of each chunk. Fluentd stops writing data to a chunk when it reaches this size. Then, Fluentd sends the chunk to the queue and opens a new chunk. -|`8m` - -|`totalLimitSize` -|The maximum size of the buffer, which is the total size of the stage and the queue. If the buffer size exceeds this value, Fluentd stops adding data to chunks and fails with an error. All data not in chunks is lost. -|`8G` - -|`flushInterval` -|The interval between chunk flushes. You can use `s` (seconds), `m` (minutes), `h` (hours), or `d` (days). -|`1s` - -|`flushMode` -a| The method to perform flushes: - -* `lazy`: Flush chunks based on the `timekey` parameter. You cannot modify the `timekey` parameter. -* `interval`: Flush chunks based on the `flushInterval` parameter. -* `immediate`: Flush chunks immediately after data is added to a chunk. -|`interval` - -|`flushThreadCount` -|The number of threads that perform chunk flushing. Increasing the number of threads improves the flush throughput, which hides network latency. -|`2` - -|`overflowAction` -a|The chunking behavior when the queue is full: - -* `throw_exception`: Raise an exception to show in the log. -* `block`: Stop data chunking until the full buffer issue is resolved. -* `drop_oldest_chunk`: Drop the oldest chunk to accept new incoming chunks. Older chunks have less value than newer chunks. -|`block` - -|`retryMaxInterval` -|The maximum time in seconds for the `exponential_backoff` retry method. -|`300s` - -|`retryType` -a|The retry method when flushing fails: - -* `exponential_backoff`: Increase the time between flush retries. Fluentd doubles the time it waits until the next retry until the `retry_max_interval` parameter is reached. -* `periodic`: Retries flushes periodically, based on the `retryWait` parameter. -|`exponential_backoff` - -|`retryWait` -|The time in seconds before the next chunk flush. -|`1s` - -|=== - -For more information on the Fluentd chunk lifecycle, see link:https://docs.fluentd.org/buffer[Buffer Plugins] in the Fluentd documentation. - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] -+ ----- -$ oc edit ClusterLogging instance ----- - -. Add or modify any of the following parameters: -+ -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogging -metadata: - name: instance - namespace: openshift-logging -spec: - forwarder: - fluentd: - buffer: - chunkLimitSize: 8m <1> - flushInterval: 5s <2> - flushMode: interval <3> - flushThreadCount: 3 <4> - overflowAction: throw_exception <5> - retryMaxInterval: "300s" <6> - retryType: periodic <7> - retryWait: 1s <8> - totalLimitSize: 32m <9> -... ----- -<1> Specify the maximum size of each chunk before it is queued for flushing. -<2> Specify the interval between chunk flushes. -<3> Specify the method to perform chunk flushes: `lazy`, `interval`, or `immediate`. -<4> Specify the number of threads to use for chunk flushes. -<5> Specify the chunking behavior when the queue is full: `throw_exception`, `block`, or `drop_oldest_chunk`. -<6> Specify the maximum interval in seconds for the `exponential_backoff` chunk flushing method. -<7> Specify the retry type when chunk flushing fails: `exponential_backoff` or `periodic`. -<8> Specify the time in seconds before the next chunk flush. -<9> Specify the maximum size of the chunk buffer. - -. Verify that the Fluentd pods are redeployed: -+ -[source,terminal] ----- -$ oc get pods -n openshift-logging ----- - -. Check that the new values are in the `fluentd` config map: -+ -[source,terminal] ----- -$ oc extract configmap/fluentd --confirm ----- -+ -.Example fluentd.conf -[source,terminal] ----- - - @type file - path '/var/lib/fluentd/default' - flush_mode interval - flush_interval 5s - flush_thread_count 3 - flush_at_shutdown true - retry_type periodic - retry_wait 1s - retry_max_interval 300s - retry_forever true - queued_chunks_limit_size "#{ENV['BUFFER_QUEUE_LIMIT'] || '32' }" - total_limit_size "#{ENV['TOTAL_LIMIT_SIZE'] || 8589934592 }" #32M - chunk_limit_size "#{ENV['BUFFER_SIZE_LIMIT'] || '8m'}" - overflow_action throw_exception - ----- diff --git a/modules/cluster-logging-configuring-image-about.adoc b/modules/cluster-logging-configuring-image-about.adoc deleted file mode 100644 index 619f2fd25ef5..000000000000 --- a/modules/cluster-logging-configuring-image-about.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-configuring.adoc - -[id="cluster-logging-configuring-image-about_{context}"] -= Understanding OpenShift Logging component images - -There are several components in OpenShift Logging, each one implemented with one -or more images. Each image is specified by an environment variable -defined in the *cluster-logging-operator* deployment in the *openshift-logging* project and should not be changed. - -You can view the images by running the following command: - -[source,terminal] ----- -$ oc -n openshift-logging set env deployment/cluster-logging-operator --list | grep _IMAGE ----- - -[source,terminal] ----- -FLUENTD_IMAGE=registry.redhat.io/openshift-logging/fluentd-rhel8:latest@sha256:ffdf79da7386871d2bc24cd937e02284b30f85a9979dc8c635fb73021cbca2f3 <1> -CURATOR_IMAGE=registry.redhat.io/openshift-logging/logging-curator5-rhel8:latest@sha256:b57c5135d72a01170e1cef26af1ea79d80ce52934456cfe363280ecbe795f21a <2> ----- -<1> *FLUENTD_IMAGE* deploys Fluentd. -<2> *CURATOR_IMAGE* deploys Curator. - -[NOTE] -==== -Promtail is not officially supported at this time. -==== - -The values might be different depending on your environment. diff --git a/modules/cluster-logging-cpu-memory.adoc b/modules/cluster-logging-cpu-memory.adoc deleted file mode 100644 index 9c0fb51ac81b..000000000000 --- a/modules/cluster-logging-cpu-memory.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-memory-limits_{context}"] -= Configuring CPU and memory limits - -The OpenShift Logging components allow for adjustments to both the CPU and memory limits. - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc -n openshift-logging edit ClusterLogging instance ----- -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: openshift-logging - -... - -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 3 - resources: <1> - limits: - memory: 16Gi - requests: - cpu: 200m - memory: 16Gi - storage: - storageClassName: "gp2" - size: "200G" - redundancyPolicy: "SingleRedundancy" - visualization: - type: "kibana" - kibana: - resources: <2> - limits: - memory: 1Gi - requests: - cpu: 500m - memory: 1Gi - proxy: - resources: <2> - limits: - memory: 100Mi - requests: - cpu: 100m - memory: 100Mi - replicas: 2 - curation: - type: "curator" - curator: - resources: <3> - limits: - memory: 200Mi - requests: - cpu: 200m - memory: 200Mi - schedule: "*/10 * * * *" - collection: - logs: - type: "fluentd" - fluentd: - resources: <4> - limits: - memory: 736Mi - requests: - cpu: 200m - memory: 736Mi ----- -<1> Specify the CPU and memory limits and requests for the log store as needed. For Elasticsearch, you must adjust both the request value and the limit value. -<2> Specify the CPU and memory limits and requests for the log visualizer as needed. -<3> Specify the CPU and memory limits and requests for the log curator as needed. -<4> Specify the CPU and memory limits and requests for the log collector as needed. diff --git a/modules/cluster-logging-curator-delete-index.adoc b/modules/cluster-logging-curator-delete-index.adoc deleted file mode 100644 index 34b6ebc4bbc1..000000000000 --- a/modules/cluster-logging-curator-delete-index.adoc +++ /dev/null @@ -1,129 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-curator.adoc - -[id="cluster-logging-curator-yaml_{context}"] -= Configuring Curator index deletion - -//// -This file can be expanded when more functions are supported. Only delete_indices currently. When more functions are added, we can use include::modules/cluster-logging-curator-actions.adoc[leveloffset=+1] for a strict delete index files topic, if needed -//// - -You can configure Curator to delete Elasticsearch data that uses the data model prior to {product-title} 4.5. You can configure per-project and global settings. Global settings apply to any project not specified. Per-project settings override global settings. -// Preserve the hard-coded "4.5" in the preceding paragraph. Do not replace it with a product version attribute. - -.Prerequisites - -* OpenShift Logging must be installed. - -.Procedure - -To delete indices: - -. Edit the {product-title} custom Curator configuration file: -+ -[source,terminal] ----- -$ oc edit configmap/curator ----- - -. Set the following parameters as needed: -+ -[source,yaml] ----- -config.yaml: | - project_name: - action - unit:value ----- -+ -The available parameters are: -+ -.Project options -[cols="3,7",options="header"] -|=== -|Variable Name -|Description - -|`project_name` -|The actual name of a project, such as *myapp-devel*. For {product-title} *operations* logs, use the name `.operations` as the project name. - -|`action` -|The action to take, currently only `delete` is allowed. - -|`unit` -|The period to use for deletion, `days`, `weeks`, or `months`. - -|`value` -|The number of units. -|=== -+ -.Filter options -[cols="3,7",options="header"] -|=== -|Variable Name -|Description - -|`.defaults` -|Use `.defaults` as the `project_name` to set the defaults for projects that are -not specified. - -|`.regex` -|The list of regular expressions that match project names. - -|`pattern` -|The valid and properly escaped regular expression pattern enclosed by single -quotation marks. - -|=== - -For example, to configure Curator to: - -- Delete indices in the *myapp-dev* project older than `1 day` -- Delete indices in the *myapp-qe* project older than `1 week` -- Delete *operations* logs older than `8 weeks` -- Delete all other projects indices after they are `31 days` old -- Delete indices older than 1 day that are matched by the `^project\..+\-dev.*$` regex -- Delete indices older than 2 days that are matched by the `^project\..+\-test.*$` regex - -Use: - -[source,yaml] ----- - config.yaml: | - .defaults: - delete: - days: 31 - - .operations: - delete: - weeks: 8 - - myapp-dev: - delete: - days: 1 - - myapp-qe: - delete: - weeks: 1 - - .regex: - - pattern: '^project\..+\-dev\..*$' - delete: - days: 1 - - pattern: '^project\..+\-test\..*$' - delete: - days: 2 ----- - -[IMPORTANT] -==== -When you use `months` as the `$UNIT` for an operation, Curator starts counting at -the first day of the current month, not the current day of the current month. -For example, if today is April 15, and you want to delete indices that are 2 months -older than today (delete: months: 2), Curator does not delete indices that are dated -older than February 15; it deletes indices older than February 1. That is, it -goes back to the first day of the current month, then goes back two whole months -from that date. If you want to be exact with Curator, it is best to use days -(for example, `delete: days: 30`). -==== diff --git a/modules/cluster-logging-curator-schedule.adoc b/modules/cluster-logging-curator-schedule.adoc deleted file mode 100644 index 38248079ae72..000000000000 --- a/modules/cluster-logging-curator-schedule.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-curator.adoc - -[id="cluster-logging-curator-schedule_{context}"] -= Configuring the Curator schedule - -You can specify the schedule for Curator using the `Cluster Logging` custom resource -created by the OpenShift Logging installation. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -To configure the Curator schedule: - -. Edit the `ClusterLogging` custom resource in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc edit clusterlogging instance ----- -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - -... - - curation: - curator: - schedule: 30 3 * * * <1> - type: curator ----- -<1> Specify the schedule for Curator in link:https://en.wikipedia.org/wiki/Cron[cron format]. -+ -[NOTE] -==== -The time zone is set based on the host node where the Curator pod runs. -==== diff --git a/modules/cluster-logging-curator-troubleshoot.adoc b/modules/cluster-logging-curator-troubleshoot.adoc deleted file mode 100644 index 1375aebf4cbd..000000000000 --- a/modules/cluster-logging-curator-troubleshoot.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-curator.adoc - -[id="cluster-logging-curator-troubleshoot_{context}"] -= Troubleshooting log curation - -You can use information in this section for debugging log curation. For example, if curator is in a failed state, but the log messages do not -provide a reason, you could increase the log level and trigger a new job, instead of waiting for another scheduled run of the cron job. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -To enable the Curator debug log and trigger next Curator iteration manually: - -. Enable debug log of Curator: -+ -[source,terminal] ----- -$ oc set env cronjob/curator CURATOR_LOG_LEVEL=DEBUG CURATOR_SCRIPT_LOG_LEVEL=DEBUG ----- -+ -Specify the log level: -+ -* *CRITICAL*. Curator displays only critical messages. -* *ERROR*. Curator displays only error and critical messages. -* *WARNING*. Curator displays only error, warning, and critical messages. -* *INFO*. Curator displays only informational, error, warning, and critical messages. -* *DEBUG*. Curator displays only debug messages, in addition to all of the above. -+ -The default value is INFO. -+ -[NOTE] -==== -OpenShift Logging uses the {product-title} custom environment variable `CURATOR_SCRIPT_LOG_LEVEL` in {product-title} wrapper scripts (`run.sh` and `convert.py`). -The environment variable takes the same values as `CURATOR_LOG_LEVEL` for script debugging, as needed. -==== - -. Trigger next curator iteration: -+ -[source,terminal] ----- -$ oc create job --from=cronjob/curator ----- - -. Use the following commands to control the cron job: - -** Suspend a cron job: -+ -[source,terminal] ----- -$ oc patch cronjob curator -p '{"spec":{"suspend":true}}' ----- - -** Resume a cron job: -+ -[source,terminal] ----- -$ oc patch cronjob curator -p '{"spec":{"suspend":false}}' ----- - -** Change a cron job schedule: -+ -[source,terminal] ----- -$ oc patch cronjob curator -p '{"spec":{"schedule":"0 0 * * *"}}' <1> ----- -<1> The `schedule` option accepts schedules in link:https://en.wikipedia.org/wiki/Cron[cron format]. diff --git a/modules/cluster-logging-dashboards-access.adoc b/modules/cluster-logging-dashboards-access.adoc deleted file mode 100644 index ed5e307b9e12..000000000000 --- a/modules/cluster-logging-dashboards-access.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// -// * logging/cluster-logging-dashboards.adoc - -[id="cluster-logging-dashboards-access_{context}"] -= Accessing the Elastisearch and Openshift Logging dashboards - - -You can view the *Logging/Elasticsearch Nodes* and *Openshift Logging* dashboards in the {product-title} web console. - -.Procedure - -To launch the dashboards: - -. In the {product-title} web console, click *Monitoring* -> *Dashboards*. - -. On the *Dashboards* page, select *Logging/Elasticsearch Nodes* or *Openshift Logging* from the *Dashboard* menu. -+ -For the *Logging/Elasticsearch Nodes* dashboard, you can select the Elasticsearch node you want to view and set the data resolution. -+ -The appropriate dashboard is displayed, showing multiple charts of data. - -. Optionally, select a different time range to display or refresh rate for the data from the *Time Range* and *Refresh Interval* menus. - -[NOTE] -==== -For more detailed data, click the *Grafana UI* link to launch the Grafana dashboard. -==== diff --git a/modules/cluster-logging-dashboards-es.adoc b/modules/cluster-logging-dashboards-es.adoc deleted file mode 100644 index 7db01c18985b..000000000000 --- a/modules/cluster-logging-dashboards-es.adoc +++ /dev/null @@ -1,196 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-dashboards.adoc - -[id="cluster-logging-dashboards-es_{context}"] -= Charts on the Logging/Elasticsearch nodes dashboard - -The *Logging/Elasticsearch Nodes* dashboard contains charts that show details about your Elasticsearch instance, many at node-level, for further diagnostics. - -Elasticsearch status:: - -The *Logging/Elasticsearch Nodes* dashboard contains the following charts about the status of your Elasticsearch instance. - -.Elasticsearch status fields -[options="header"] -|=== -|Metric|Description - -|Cluster status -a|The cluster health status during the selected time period, using the Elasticsearch green, yellow, and red statuses: - -* 0 - Indicates that the Elasticsearch instance is in green status, which means that all shards are allocated. -* 1 - Indicates that the Elasticsearch instance is in yellow status, which means that replica shards for at least one shard are not allocated. -* 2 - Indicates that the Elasticsearch instance is in red status, which means that at least one primary shard and its replicas are not allocated. - -|Cluster nodes -|The total number of Elasticsearch nodes in the cluster. - -|Cluster data nodes -|The number of Elasticsearch data nodes in the cluster. - -|Cluster pending tasks -|The number of cluster state changes that are not finished and are waiting in a cluster queue, for example, index creation, index deletion, or shard allocation. A growing trend indicates that the cluster is not able to keep up with changes. - -|=== - -Elasticsearch cluster index shard status:: - -Each Elasticsearch index is a logical group of one or more shards, which are basic units of persisted data. There are two types of index shards: primary shards, and replica shards. When a document is indexed into an index, it is stored in one of its primary shards and copied into every replica of that shard. The number of primary shards is specified when the index is created, and the number cannot change during index lifetime. You can change the number of replica shards at any time. - -The index shard can be in several states depending on its lifecycle phase or events occurring in the cluster. When the shard is able to perform search and indexing requests, the shard is active. If the shard cannot perform these requests, the shard is non–active. A shard might be non-active if the shard is initializing, reallocating, unassigned, and so forth. - -Index shards consist of a number of smaller internal blocks, called index segments, which are physical representations of the data. An index segment is a relatively small, immutable Lucene index that is created when Lucene commits newly-indexed data. Lucene, a search library used by Elasticsearch, merges index segments into larger segments in the background to keep the total number of segments low. If the process of merging segments is slower than the speed at which new segments are created, it could indicate a problem. - -When Lucene performs data operations, such as a search operation, Lucene performs the operation against the index segments in the relevant index. For that purpose, each segment contains specific data structures that are loaded in the memory and mapped. Index mapping can have a significant impact on the memory used by segment data structures. - -The *Logging/Elasticsearch Nodes* dashboard contains the following charts about the Elasticsearch index shards. - -.Elasticsearch cluster shard status charts -[options="header"] - -|=== -|Metric|Description - -|Cluster active shards -|The number of active primary shards and the total number of shards, including replicas, in the cluster. If the number of shards grows higher, the cluster performance can start degrading. - -|Cluster initializing shards -|The number of non-active shards in the cluster. A non-active shard is one that is initializing, being reallocated to a different node, or is unassigned. A cluster typically has non–active shards for short periods. A growing number of non–active shards over longer periods could indicate a problem. - -|Cluster relocating shards -|The number of shards that Elasticsearch is relocating to a new node. Elasticsearch relocates nodes for multiple reasons, such as high memory use on a node or after a new node is added to the cluster. - -|Cluster unassigned shards -|The number of unassigned shards. Elasticsearch shards might be unassigned for reasons such as a new index being added or the failure of a node. - -|=== - -Elasticsearch node metrics:: - -Each Elasticsearch node has a finite amount of resources that can be used to process tasks. When all the resources are being used and Elasticsearch attempts to perform a new task, Elasticsearch put the tasks into a queue until some resources become available. - -The *Logging/Elasticsearch Nodes* dashboard contains the following charts about resource usage for a selected node and the number of tasks waiting in the Elasticsearch queue. - -.Elasticsearch node metric charts -[options="header"] -|=== -|Metric|Description - -|ThreadPool tasks -|The number of waiting tasks in individual queues, shown by task type. A long–term accumulation of tasks in any queue could indicate node resource shortages or some other problem. - -|CPU usage -|The amount of CPU being used by the selected Elasticsearch node as a percentage of the total CPU allocated to the host container. - -|Memory usage -|The amount of memory being used by the selected Elasticsearch node. - -|Disk usage -|The total disk space being used for index data and metadata on the selected Elasticsearch node. - -|Documents indexing rate -|The rate that documents are indexed on the selected Elasticsearch node. - -|Indexing latency -|The time taken to index the documents on the selected Elasticsearch node. Indexing latency can be affected by many factors, such as JVM Heap memory and overall load. A growing latency indicates a resource capacity shortage in the instance. - -|Search rate -|The number of search requests run on the selected Elasticsearch node. - -|Search latency -|The time taken to complete search requests on the selected Elasticsearch node. Search latency can be affected by many factors. A growing latency indicates a resource capacity shortage in the instance. - -|Documents count (with replicas) -|The number of Elasticsearch documents stored on the selected Elasticsearch node, including documents stored in both the primary shards and replica shards that are allocated on the node. - -|Documents deleting rate -|The number of Elasticsearch documents being deleted from any of the index shards that are allocated to the selected Elasticsearch node. - -|Documents merging rate -|The number of Elasticsearch documents being merged in any of index shards that are allocated to the selected Elasticsearch node. - -|=== - -Elasticsearch node fielddata:: - -link:https://www.elastic.co/guide/en/elasticsearch/reference/6.8/fielddata.html[_Fielddata_] is an Elasticsearch data structure that holds lists of terms in an index and is kept in the JVM Heap. Because fielddata building is an expensive operation, Elasticsearch caches the fielddata structures. Elasticsearch can evict a fielddata cache when the underlying index segment is deleted or merged, or if there is not enough JVM HEAP memory for all the fielddata caches. - -The *Logging/Elasticsearch Nodes* dashboard contains the following charts about Elasticsearch fielddata. - -.Elasticsearch node fielddata charts -[options="header"] -|=== -|Metric|Description - -|Fielddata memory size -|The amount of JVM Heap used for the fielddata cache on the selected Elasticsearch node. - -|Fielddata evictions -|The number of fielddata structures that were deleted from the selected Elasticsearch node. - -|=== - -Elasticsearch node query cache:: - -If the data stored in the index does not change, search query results are cached in a node-level query cache for reuse by Elasticsearch. - -The *Logging/Elasticsearch Nodes* dashboard contains the following charts about the Elasticsearch node query cache. - -.Elasticsearch node query charts -[options="header"] -|=== -|Metric|Description - -|Query cache size -|The total amount of memory used for the query cache for all the shards allocated to the selected Elasticsearch node. - -|Query cache evictions -|The number of query cache evictions on the selected Elasticsearch node. - -|Query cache hits -|The number of query cache hits on the selected Elasticsearch node. - -|Query cache misses -|The number of query cache misses on the selected Elasticsearch node. - -|=== - -Elasticsearch index throttling:: - -When indexing documents, Elasticsearch stores the documents in index segments, which are physical representations of the data. At the same time, Elasticsearch periodically merges smaller segments into a larger segment as a way to optimize resource use. If the indexing is faster then the ability to merge segments, the merge process does not complete quickly enough, which can lead to issues with searches and performance. To prevent this situation, Elasticsearch throttles indexing, typically by reducing the number of threads allocated to indexing down to a single thread. - -The *Logging/Elasticsearch Nodes* dashboard contains the following charts about Elasticsearch index throttling. - -.Index throttling charts -[options="header"] -|=== -|Metric|Description - -|Indexing throttling -|The amount of time that Elasticsearch has been throttling the indexing operations on the selected Elasticsearch node. - -|Merging throttling -|The amount of time that Elasticsearch has been throttling the segment merge operations on the selected Elasticsearch node. - -|=== - -Node JVM Heap statistics:: - -The *Logging/Elasticsearch Nodes* dashboard contains the following charts about JVM Heap operations. - -.JVM Heap statistic charts -[options="header"] -|=== -|Metric|Description - -|Heap used -|The amount of the total allocated JVM Heap space that is used on the selected Elasticsearch node. - -|GC count -|The number of garbage collection operations that have been run on the selected Elasticsearch node, by old and young garbage collection. - -|GC time -|The amount of time that the JVM spent running garbage collection operations on the selected Elasticsearch node, by old and young garbage collection. - -|=== diff --git a/modules/cluster-logging-dashboards-logging.adoc b/modules/cluster-logging-dashboards-logging.adoc deleted file mode 100644 index 4f8c64458118..000000000000 --- a/modules/cluster-logging-dashboards-logging.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-dashboards.adoc - -[id="cluster-logging-dashboards-logging_{context}"] -= About the OpenShift Logging dashboard - -The *OpenShift Logging* dashboard contains charts that show details about your Elasticsearch instance at a cluster-level that you can use to diagnose and anticipate problems. - -.OpenShift Logging charts -[options="header"] -|=== -|Metric|Description - -|Elastic Cluster Status -a|The current Elasticsearch status: - -* ONLINE - Indicates that the Elasticsearch instance is online. -* OFFLINE - Indicates that the Elasticsearch instance is offline. - -|Elastic Nodes -|The total number of Elasticsearch nodes in the Elasticsearch instance. - -|Elastic Shards -|The total number of Elasticsearch shards in the Elasticsearch instance. - -|Elastic Documents -|The total number of Elasticsearch documents in the Elasticsearch instance. - -|Total Index Size on Disk -|The total disk space that is being used for the Elasticsearch indices. - -|Elastic Pending Tasks -|The total number of Elasticsearch changes that have not been completed, such as index creation, index mapping, shard allocation, or shard failure. - -|Elastic JVM GC time -|The amount of time that the JVM spent executing Elasticsearch garbage collection operations in the cluster. - -|Elastic JVM GC Rate -|The total number of times that JVM executed garbage activities per second. - -|Elastic Query/Fetch Latency Sum -a|* Query latency: The average time each Elasticsearch search query takes to execute. -* Fetch latency: The average time each Elasticsearch search query spends fetching data. - -Fetch latency typically takes less time than query latency. If fetch latency is consistently increasing, it might indicate slow disks, data enrichment, or large requests with too many results. - -|Elastic Query Rate -|The total queries executed against the Elasticsearch instance per second for each Elasticsearch node. - -|CPU -|The amount of CPU used by Elasticsearch, Fluentd, and Kibana, shown for each component. - -|Elastic JVM Heap Used -|The amount of JVM memory used. In a healthy cluster, the graph shows regular drops as memory is freed by JVM garbage collection. - -|Elasticsearch Disk Usage -|The total disk space used by the Elasticsearch instance for each Elasticsearch node. - -|File Descriptors In Use -|The total number of file descriptors used by Elasticsearch, Fluentd, and Kibana. - -|FluentD emit count -|The total number of Fluentd messages per second for the Fluentd default output, and the retry count for the default output. - -|FluentD Buffer Availability -|The percent of the Fluentd buffer that is available for chunks. A full buffer might indicate that Fluentd is not able to process the number of logs received. - -|Elastic rx bytes -|The total number of bytes that Elasticsearch has received from FluentD, the Elasticsearch nodes, and other sources. - -|Elastic Index Failure Rate -|The total number of times per second that an Elasticsearch index fails. A high rate might indicate an issue with indexing. - -|FluentD Output Error Rate -|The total number of times per second that FluentD is not able to output logs. - -|=== diff --git a/modules/cluster-logging-deploy-certificates.adoc b/modules/cluster-logging-deploy-certificates.adoc deleted file mode 100644 index c6c25b166b50..000000000000 --- a/modules/cluster-logging-deploy-certificates.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-deploy.adoc - -[id="cluster-logging-deploy-certificates_{context}"] -= Deploying custom certificates - -You can specify custom certificates using the following variables -instead of relying on those generated during the deployment process. These -certificates are used to encrypt and secure communication between a user's -browser and Kibana. The security-related files will be generated if they are not -supplied. - -[cols="3,7",options="header"] -|=== -|File Name -|Description - -|`openshift_logging_kibana_cert` -|A browser-facing certificate for the Kibana server. - -|`openshift_logging_kibana_key` -|A key to be used with the browser-facing Kibana certificate. - -|`openshift_logging_kibana_ca` -|The absolute path on the control node to the CA file to use -for the browser facing Kibana certs. - -|=== diff --git a/modules/cluster-logging-deploy-cli.adoc b/modules/cluster-logging-deploy-cli.adoc deleted file mode 100644 index af19dc1fdf42..000000000000 --- a/modules/cluster-logging-deploy-cli.adoc +++ /dev/null @@ -1,462 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-deploying.adoc - -[id="cluster-logging-deploy-cli_{context}"] -= Installing OpenShift Logging using the CLI - -You can use the {product-title} CLI to install the OpenShift Elasticsearch and Cluster Logging Operators. - -.Prerequisites - -* Ensure that you have the necessary persistent storage for Elasticsearch. Note that each Elasticsearch node -requires its own storage volume. -+ -[NOTE] -==== -If you use a local volume for persistent storage, do not use a raw block volume, which is described with `volumeMode: block` in the `LocalVolume` object. Elasticsearch cannot use raw block volumes. -==== -+ -Elasticsearch is a memory-intensive application. By default, {product-title} installs three Elasticsearch nodes with memory requests and limits of 16 GB. This initial set of three {product-title} nodes might not have enough memory to run Elasticsearch within your cluster. If you experience memory issues that are related to Elasticsearch, add more Elasticsearch nodes to your cluster rather than increasing the memory on existing nodes. - -ifdef::openshift-origin[] -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in _Obtaining the installation program_ in the installation documentation for your platform. -+ -If you have the pull secret, add the `redhat-operators` catalog to the OperatorHub custom resource (CR) as shown in *Configuring {product-title} to use Red Hat Operators*. -endif::[] - -.Procedure - -To install the OpenShift Elasticsearch Operator and Cluster Logging Operator using the CLI: - -. Create a Namespace for the OpenShift Elasticsearch Operator. - -.. Create a Namespace object YAML file (for example, `eo-namespace.yaml`) for the OpenShift Elasticsearch Operator: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-operators-redhat <1> - annotations: - openshift.io/node-selector: "" - labels: - openshift.io/cluster-monitoring: "true" <2> ----- -<1> You must specify the `openshift-operators-redhat` Namespace. To prevent -possible conflicts with metrics, you should configure the Prometheus Cluster -Monitoring stack to scrape metrics from the `openshift-operators-redhat` -Namespace and not the `openshift-operators` Namespace. The `openshift-operators` -Namespace might contain Community Operators, which are untrusted and could publish -a metric with the same name as an {product-title} metric, which would cause -conflicts. -<2> You must specify this label as shown to ensure that cluster monitoring -scrapes the `openshift-operators-redhat` Namespace. - -.. Create the Namespace: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f eo-namespace.yaml ----- - -. Create a Namespace for the Cluster Logging Operator: - -.. Create a Namespace object YAML file (for example, `clo-namespace.yaml`) for the Cluster Logging Operator: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-logging - annotations: - openshift.io/node-selector: "" - labels: - openshift.io/cluster-monitoring: "true" ----- - -.. Create the Namespace: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f clo-namespace.yaml ----- - -. Install the OpenShift Elasticsearch Operator by creating the following objects: - -.. Create an Operator Group object YAML file (for example, `eo-og.yaml`) for the OpenShift Elasticsearch Operator: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: openshift-operators-redhat - namespace: openshift-operators-redhat <1> -spec: {} ----- -<1> You must specify the `openshift-operators-redhat` Namespace. - -.. Create an Operator Group object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f eo-og.yaml ----- - -.. Create a Subscription object YAML file (for example, `eo-sub.yaml`) to -subscribe a Namespace to the OpenShift Elasticsearch Operator. -+ -.Example Subscription -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: "elasticsearch-operator" - namespace: "openshift-operators-redhat" <1> -spec: - channel: "5.0" <2> - installPlanApproval: "Automatic" - source: "redhat-operators" <3> - sourceNamespace: "openshift-marketplace" - name: "elasticsearch-operator" ----- -<1> You must specify the `openshift-operators-redhat` Namespace. -<2> Specify `5.0` or `stable` as the channel. `stable` is the latest 5.x released code. -<3> Specify `redhat-operators`. If your {product-title} cluster is installed on a restricted network, also known as a disconnected cluster, -specify the name of the CatalogSource object created when you configured the Operator Lifecycle Manager (OLM). - -.. Create the Subscription object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f eo-sub.yaml ----- -+ -The OpenShift Elasticsearch Operator is installed to the `openshift-operators-redhat` Namespace and copied to each project in the cluster. - -.. Verify the Operator installation: -+ -[source,terminal] ----- -$ oc get csv --all-namespaces ----- -+ -.Example output -[source,terminal] ----- -NAMESPACE NAME DISPLAY VERSION REPLACES PHASE -default elasticsearch-operator.5.0.0-202007012112.p0 OpenShift Elasticsearch Operator 5.0.0-202007012112.p0 Succeeded -kube-node-lease elasticsearch-operator.5.0.0-202007012112.p0 OpenShift Elasticsearch Operator 5.0.0-202007012112.p0 Succeeded -kube-public elasticsearch-operator.5.0.0-202007012112.p0 OpenShift Elasticsearch Operator 5.0.0-202007012112.p0 Succeeded -kube-system elasticsearch-operator.5.0.0-202007012112.p0 OpenShift Elasticsearch Operator 5.0.0-202007012112.p0 Succeeded -openshift-apiserver-operator elasticsearch-operator.5.0.0-202007012112.p0 OpenShift Elasticsearch Operator 5.0.0-202007012112.p0 Succeeded -openshift-apiserver elasticsearch-operator.5.0.0-202007012112.p0 OpenShift Elasticsearch Operator 5.0.0-202007012112.p0 Succeeded -openshift-authentication-operator elasticsearch-operator.5.0.0-202007012112.p0 OpenShift Elasticsearch Operator 5.0.0-202007012112.p0 Succeeded -openshift-authentication elasticsearch-operator.5.0.0-202007012112.p0 OpenShift Elasticsearch Operator 5.0.0-202007012112.p0 Succeeded -... ----- -+ -There should be an OpenShift Elasticsearch Operator in each Namespace. The version number might be different than shown. - -. Install the Cluster Logging Operator by creating the following objects: - -.. Create an Operator Group object YAML file (for example, `clo-og.yaml`) for the Cluster Logging Operator: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: cluster-logging - namespace: openshift-logging <1> -spec: - targetNamespaces: - - openshift-logging <1> ----- -<1> You must specify the `openshift-logging` Namespace. - -.. Create an Operator Group object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f clo-og.yaml ----- - -.. Create a Subscription object YAML file (for example, `clo-sub.yaml`) to -subscribe a Namespace to the Cluster Logging Operator. -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: cluster-logging - namespace: openshift-logging <1> -spec: - channel: "5.0" <2> - name: cluster-logging - source: redhat-operators <3> - sourceNamespace: openshift-marketplace ----- -<1> You must specify the `openshift-logging` Namespace. -<2> Specify `5.0` or `stable` as the channel. `stable` is the latest 5.x released code. -<3> Specify `redhat-operators`. If your {product-title} cluster is installed on a restricted network, also known as a disconnected cluster, specify the name of the CatalogSource object you created when you configured the Operator Lifecycle Manager (OLM). -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f clo-sub.yaml ----- -+ -The Cluster Logging Operator is installed to the `openshift-logging` Namespace. - -.. Verify the Operator installation. -+ -There should be a Cluster Logging Operator in the `openshift-logging` Namespace. The Version number might be different than shown. -+ -[source,terminal] ----- -$ oc get csv -n openshift-logging ----- -+ -.Example output -[source,terminal] ----- -NAMESPACE NAME DISPLAY VERSION REPLACES PHASE -... -openshift-logging clusterlogging.5.0.0-202007012112.p0 OpenShift Logging 5.0.0-202007012112.p0 Succeeded -... ----- - -. Create a OpenShift Logging instance: - -.. Create an instance object YAML file (for example, `clo-instance.yaml`) for the Cluster Logging Operator: -+ -[NOTE] -==== -This default OpenShift Logging configuration should support a wide array of environments. Review the topics on tuning and -configuring OpenShift Logging components for information on modifications you can make to your OpenShift Logging cluster. -==== -+ -ifdef::openshift-dedicated[] -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: "openshift-logging" -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - retentionPolicy: - application: - maxAge: 1d - infra: - maxAge: 7d - audit: - maxAge: 7d - elasticsearch: - nodeCount: 3 - storage: - storageClassName: gp2 - size: "200Gi" - redundancyPolicy: "SingleRedundancy" - nodeSelector: - node-role.kubernetes.io/worker: "" - resources: - request: - memory: 8G - visualization: - type: "kibana" - kibana: - replicas: 1 - nodeSelector: - node-role.kubernetes.io/worker: "" - curation: - type: "curator" - curator: - schedule: "30 3 * * *" - nodeSelector: - node-role.kubernetes.io/worker: "" - collection: - logs: - type: "fluentd" - fluentd: {} - nodeSelector: - node-role.kubernetes.io/worker: "" ----- -endif::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" <1> - namespace: "openshift-logging" -spec: - managementState: "Managed" <2> - logStore: - type: "elasticsearch" <3> - retentionPolicy: <4> - application: - maxAge: 1d - infra: - maxAge: 7d - audit: - maxAge: 7d - elasticsearch: - nodeCount: 3 <5> - storage: - storageClassName: "" <6> - size: 200G - resources: <7> - requests: - memory: "8Gi" - proxy: <8> - resources: - limits: - memory: 256Mi - requests: - memory: 256Mi - redundancyPolicy: "SingleRedundancy" - visualization: - type: "kibana" <9> - kibana: - replicas: 1 - curation: - type: "curator" - curator: - schedule: "30 3 * * *" <10> - collection: - logs: - type: "fluentd" <11> - fluentd: {} ----- -<1> The name must be `instance`. -<2> The OpenShift Logging management state. In some cases, if you change the OpenShift Logging defaults, you must set this to `Unmanaged`. -However, an unmanaged deployment does not receive updates until OpenShift Logging is placed back into a managed state. Placing a deployment back into a managed state might revert any modifications you made. -<3> Settings for configuring Elasticsearch. Using the custom resource (CR), you can configure shard replication policy and persistent storage. -<4> Specify the length of time that Elasticsearch should retain each log source. Enter an integer and a time designation: weeks(w), hours(h/H), minutes(m) and seconds(s). For example, `7d` for seven days. Logs older than the `maxAge` are deleted. You must specify a retention policy for each log source or the Elasticsearch indices will not be created for that source. -<5> Specify the number of Elasticsearch nodes. See the note that follows this list. -<6> Enter the name of an existing storage class for Elasticsearch storage. For best performance, specify a storage class that allocates block storage. If you do not specify a storage class, {product-title} deploys OpenShift Logging with ephemeral storage only. -<7> Specify the CPU and memory requests for Elasticsearch as needed. If you leave these values blank, the OpenShift Elasticsearch Operator sets default values that should be sufficient for most deployments. The default values are `16G` for the memory request and `1` for the CPU request. -<8> Specify the CPU and memory requests for the Elasticsearch proxy as needed. If you leave these values blank, the OpenShift Elasticsearch Operator sets default values that should be sufficient for most deployments. The default values are `256Mi` for the memory request and `100m` for the CPU request. -<9> Settings for configuring Kibana. Using the CR, you can scale Kibana for redundancy and configure the CPU and memory for your Kibana pods. For more information, see *Configuring the log visualizer*. -<10> Settings for configuring the Curator schedule. Curator is used to remove data that is in the Elasticsearch index format prior to {product-title} 4.5 and will be removed in a later release. -<11> Settings for configuring Fluentd. Using the CR, you can configure Fluentd CPU and memory limits. For more information, see *Configuring Fluentd*. -+ -[NOTE] -+ -==== -The maximum number of Elasticsearch master nodes is three. If you specify a `nodeCount` greater than `3`, {product-title} creates three Elasticsearch nodes that are Master-eligible nodes, with the master, client, and data roles. The additional Elasticsearch nodes are created as Data-only nodes, using client and data roles. Master nodes perform cluster-wide actions such as creating or deleting an index, shard allocation, and tracking nodes. Data nodes hold the shards and perform data-related operations such as CRUD, search, and aggregations. Data-related operations are I/O-, memory-, and CPU-intensive. It is important to monitor these resources and to add more Data nodes if the current nodes are overloaded. - -For example, if `nodeCount=4`, the following nodes are created: - -[source,terminal] ----- -$ oc get deployment ----- - -.Example output -[source,terminal] ----- -cluster-logging-operator 1/1 1 1 18h -elasticsearch-cd-x6kdekli-1 1/1 1 0 6m54s -elasticsearch-cdm-x6kdekli-1 1/1 1 1 18h -elasticsearch-cdm-x6kdekli-2 1/1 1 0 6m49s -elasticsearch-cdm-x6kdekli-3 1/1 1 0 6m44s ----- - -The number of primary shards for the index templates is equal to the number of Elasticsearch data nodes. -==== - -.. Create the instance: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f clo-instance.yaml ----- -+ -This creates the OpenShift Logging components, the `Elasticsearch` custom resource and components, and the Kibana interface. - -. Verify the install by listing the pods in the *openshift-logging* project. -+ -You should see several pods for OpenShift Logging, Elasticsearch, Fluentd, and Kibana similar to the following list: -+ -[source,terminal] ----- -$ oc get pods -n openshift-logging ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -cluster-logging-operator-66f77ffccb-ppzbg 1/1 Running 0 7m -elasticsearch-cdm-ftuhduuw-1-ffc4b9566-q6bhp 2/2 Running 0 2m40s -elasticsearch-cdm-ftuhduuw-2-7b4994dbfc-rd2gc 2/2 Running 0 2m36s -elasticsearch-cdm-ftuhduuw-3-84b5ff7ff8-gqnm2 2/2 Running 0 2m4s -fluentd-587vb 1/1 Running 0 2m26s -fluentd-7mpb9 1/1 Running 0 2m30s -fluentd-flm6j 1/1 Running 0 2m33s -fluentd-gn4rn 1/1 Running 0 2m26s -fluentd-nlgb6 1/1 Running 0 2m30s -fluentd-snpkt 1/1 Running 0 2m28s -kibana-d6d5668c5-rppqm 2/2 Running 0 2m39s ----- diff --git a/modules/cluster-logging-deploy-console.adoc b/modules/cluster-logging-deploy-console.adoc deleted file mode 100644 index 7daccdfbf478..000000000000 --- a/modules/cluster-logging-deploy-console.adoc +++ /dev/null @@ -1,280 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-deploying.adoc - -[id="cluster-logging-deploy-console_{context}"] -= Installing OpenShift Logging using the web console - -You can use the {product-title} web console to install the OpenShift Elasticsearch and Cluster Logging Operators. - -.Prerequisites - -* Ensure that you have the necessary persistent storage for Elasticsearch. Note that each Elasticsearch node -requires its own storage volume. -+ -[NOTE] -==== -If you use a local volume for persistent storage, do not use a raw block volume, which is described with `volumeMode: block` in the `LocalVolume` object. Elasticsearch cannot use raw block volumes. -==== -+ -Elasticsearch is a memory-intensive application. By default, {product-title} installs three Elasticsearch nodes with memory requests and limits of 16 GB. This initial set of three {product-title} nodes might not have enough memory to run Elasticsearch within your cluster. If you experience memory issues that are related to Elasticsearch, add more Elasticsearch nodes to your cluster rather than increasing the memory on existing nodes. - -ifdef::openshift-origin[] -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in _Obtaining the installation program_ in the installation documentation for your platform. -+ -If you have the pull secret, add the `redhat-operators` catalog to the OperatorHub custom resource (CR) as shown in _Configuring {product-title} to use Red Hat Operators_. -endif::[] - -.Procedure - -To install the OpenShift Elasticsearch Operator and Cluster Logging Operator using the {product-title} web console: - -. Install the OpenShift Elasticsearch Operator: - -.. In the {product-title} web console, click *Operators* -> *OperatorHub*. - -.. Choose *OpenShift Elasticsearch Operator* from the list of available Operators, and click *Install*. - -.. Ensure that the *All namespaces on the cluster* is selected under *Installation Mode*. - -.. Ensure that *openshift-operators-redhat* is selected under *Installed Namespace*. -+ -You must specify the `openshift-operators-redhat` namespace. The `openshift-operators` -namespace might contain Community Operators, which are untrusted and could publish -a metric with the same name as an {product-title} metric, which would cause -conflicts. - -.. Select *Enable operator recommended cluster monitoring on this namespace*. -+ -This option sets the `openshift.io/cluster-monitoring: "true"` label in the Namespace object. -You must select this option to ensure that cluster monitoring -scrapes the `openshift-operators-redhat` namespace. - -.. Select *5.0* as the *Update Channel*. - -.. Select an *Approval Strategy*. -+ -* The *Automatic* strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available. -+ -* The *Manual* strategy requires a user with appropriate credentials to approve the Operator update. - -.. Click *Install*. - -.. Verify that the OpenShift Elasticsearch Operator installed by switching to the *Operators* → *Installed Operators* page. - -.. Ensure that *OpenShift Elasticsearch Operator* is listed in all projects with a *Status* of *Succeeded*. - -. Install the Cluster Logging Operator: - -.. In the {product-title} web console, click *Operators* -> *OperatorHub*. - -.. Choose *Cluster Logging* from the list of available Operators, and click *Install*. - -.. Ensure that the *A specific namespace on the cluster* is selected under *Installation Mode*. - -.. Ensure that *Operator recommended namespace* is *openshift-logging* under *Installed Namespace*. - -.. Select *Enable operator recommended cluster monitoring on this namespace*. -+ -This option sets the `openshift.io/cluster-monitoring: "true"` label in the Namespace object. -You must select this option to ensure that cluster monitoring -scrapes the `openshift-logging` namespace. - -.. Select *5.0* as the *Update Channel*. - -.. Select an *Approval Strategy*. -+ -* The *Automatic* strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available. -+ -* The *Manual* strategy requires a user with appropriate credentials to approve the Operator update. - -.. Click *Install*. - -.. Verify that the Cluster Logging Operator installed by switching to the *Operators* → *Installed Operators* page. - -.. Ensure that *Cluster Logging* is listed in the *openshift-logging* project with a *Status* of *Succeeded*. -+ -If the Operator does not appear as installed, to troubleshoot further: -+ -* Switch to the *Operators* → *Installed Operators* page and inspect -the *Status* column for any errors or failures. -* Switch to the *Workloads* → *Pods* page and check the logs in any pods in the -`openshift-logging` project that are reporting issues. - -. Create a OpenShift Logging instance: - -.. Switch to the *Administration* -> *Custom Resource Definitions* page. - -.. On the *Custom Resource Definitions* page, click *ClusterLogging*. - -.. On the *Custom Resource Definition Overview* page, select *View Instances* from the *Actions* menu. - -.. On the *ClusterLoggings* page, click *Create ClusterLogging*. -+ -You might have to refresh the page to load the data. - -.. In the YAML field, replace the code with the following: -+ -[NOTE] -==== -This default OpenShift Logging configuration should support a wide array of environments. Review the topics on tuning and -configuring OpenShift Logging components for information on modifications you can make to your OpenShift Logging cluster. -==== -+ -ifdef::openshift-dedicated[] -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: "openshift-logging" -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - retentionPolicy: - application: - maxAge: 1d - infra: - maxAge: 7d - audit: - maxAge: 7d - elasticsearch: - nodeCount: 3 - storage: - storageClassName: gp2 - size: "200Gi" - redundancyPolicy: "SingleRedundancy" - nodeSelector: - node-role.kubernetes.io/worker: "" - resources: - request: - memory: 8G - visualization: - type: "kibana" - kibana: - replicas: 1 - nodeSelector: - node-role.kubernetes.io/worker: "" - curation: - type: "curator" - curator: - schedule: "30 3 * * *" - nodeSelector: - node-role.kubernetes.io/worker: "" - collection: - logs: - type: "fluentd" - fluentd: {} - nodeSelector: - node-role.kubernetes.io/worker: "" ----- -endif::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" <1> - namespace: "openshift-logging" -spec: - managementState: "Managed" <2> - logStore: - type: "elasticsearch" <3> - retentionPolicy: <4> - application: - maxAge: 1d - infra: - maxAge: 7d - audit: - maxAge: 7d - elasticsearch: - nodeCount: 3 <5> - storage: - storageClassName: "" <6> - size: 200G - resources: <7> - requests: - memory: "8Gi" - proxy: <8> - resources: - limits: - memory: 256Mi - requests: - memory: 256Mi - redundancyPolicy: "SingleRedundancy" - visualization: - type: "kibana" <9> - kibana: - replicas: 1 - curation: - type: "curator" - curator: - schedule: "30 3 * * *" <10> - collection: - logs: - type: "fluentd" <11> - fluentd: {} ----- -<1> The name must be `instance`. -<2> The OpenShift Logging management state. In some cases, if you change the OpenShift Logging defaults, you must set this to `Unmanaged`. -However, an unmanaged deployment does not receive updates until OpenShift Logging is placed back into a managed state. -<3> Settings for configuring Elasticsearch. Using the CR, you can configure shard replication policy and persistent storage. -<4> Specify the length of time that Elasticsearch should retain each log source. Enter an integer and a time designation: weeks(w), hours(h/H), minutes(m) and seconds(s). For example, `7d` for seven days. Logs older than the `maxAge` are deleted. You must specify a retention policy for each log source or the Elasticsearch indices will not be created for that source. -<5> Specify the number of Elasticsearch nodes. See the note that follows this list. -<6> Enter the name of an existing storage class for Elasticsearch storage. For best performance, specify a storage class that allocates block storage. If you do not specify a storage class, OpenShift Logging uses ephemeral storage. -<7> Specify the CPU and memory requests for Elasticsearch as needed. If you leave these values blank, the OpenShift Elasticsearch Operator sets default values that should be sufficient for most deployments. The default values are `16G` for the memory request and `1` for the CPU request. -<8> Specify the CPU and memory requests for the Elasticsearch proxy as needed. If you leave these values blank, the OpenShift Elasticsearch Operator sets default values that should be sufficient for most deployments. The default values are `256Mi` for the memory request and `100m` for the CPU request. -<9> Settings for configuring Kibana. Using the CR, you can scale Kibana for redundancy and configure the CPU and memory for your Kibana nodes. For more information, see *Configuring the log visualizer*. -<10> Settings for configuring the Curator schedule. Curator is used to remove data that is in the Elasticsearch index format prior to {product-title} 4.5 and will be removed in a later release. -<11> Settings for configuring Fluentd. Using the CR, you can configure Fluentd CPU and memory limits. For more information, see *Configuring Fluentd*. -+ -[NOTE] -+ -==== -The maximum number of Elasticsearch master nodes is three. If you specify a `nodeCount` greater than `3`, {product-title} creates three Elasticsearch nodes that are Master-eligible nodes, with the master, client, and data roles. The additional Elasticsearch nodes are created as Data-only nodes, using client and data roles. Master nodes perform cluster-wide actions such as creating or deleting an index, shard allocation, and tracking nodes. Data nodes hold the shards and perform data-related operations such as CRUD, search, and aggregations. Data-related operations are I/O-, memory-, and CPU-intensive. It is important to monitor these resources and to add more Data nodes if the current nodes are overloaded. - -For example, if `nodeCount=4`, the following nodes are created: - -[source,terminal] ----- -$ oc get deployment ----- - -.Example output -[source,terminal] ----- -cluster-logging-operator 1/1 1 1 18h -elasticsearch-cd-x6kdekli-1 0/1 1 0 6m54s -elasticsearch-cdm-x6kdekli-1 1/1 1 1 18h -elasticsearch-cdm-x6kdekli-2 0/1 1 0 6m49s -elasticsearch-cdm-x6kdekli-3 0/1 1 0 6m44s ----- - -The number of primary shards for the index templates is equal to the number of Elasticsearch data nodes. -==== - -.. Click *Create*. This creates the OpenShift Logging components, the `Elasticsearch` custom resource and components, and the Kibana interface. - -. Verify the install: - -.. Switch to the *Workloads* -> *Pods* page. - -.. Select the *openshift-logging* project. -+ -You should see several pods for OpenShift Logging, Elasticsearch, Fluentd, and Kibana similar to the following list: -+ -* cluster-logging-operator-cb795f8dc-xkckc -* elasticsearch-cdm-b3nqzchd-1-5c6797-67kfz -* elasticsearch-cdm-b3nqzchd-2-6657f4-wtprv -* elasticsearch-cdm-b3nqzchd-3-588c65-clg7g -* fluentd-2c7dg -* fluentd-9z7kk -* fluentd-br7r2 -* fluentd-fn2sb -* fluentd-pb2f8 -* fluentd-zqgqx -* kibana-7fb4fd4cc9-bvt4p diff --git a/modules/cluster-logging-deploy-label.adoc b/modules/cluster-logging-deploy-label.adoc deleted file mode 100644 index ea3ea67be033..000000000000 --- a/modules/cluster-logging-deploy-label.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-deploy.adoc - -[id="cluster-logging-deploy-label_{context}"] -= Labeling nodes - -At 100 nodes or more, it is recommended to first pre-pull the logging images -from the registry. -After deploying the logging pods (Elasticsearch, Kibana, and -Curator), node labeling should be done in steps of 20 nodes at a time. For -example: - -Using a simple loop: - -[source,terminal] ----- -$ while read node; do oc label nodes $node elasticsearch-fluentd=true; done < 20_fluentd.lst ----- - -The following also works: - -[source,terminal] ----- -$ oc label nodes 10.10.0.{100..119} elasticsearch-fluentd=true ----- - -Labeling nodes in groups paces the daemon sets used by OpenShift logging, helping to avoid contention on shared resources such as the image registry. - -[NOTE] -==== -Check for the occurrence of any "CrashLoopBackOff | ImagePullFailed | Error" issues. -`oc logs `, `oc describe pod ` and `oc get event` are helpful diagnostic commands. -==== diff --git a/modules/cluster-logging-deploy-memory.adoc b/modules/cluster-logging-deploy-memory.adoc deleted file mode 100644 index accf34ab0172..000000000000 --- a/modules/cluster-logging-deploy-memory.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-deploy.adoc - -[id="cluster-logging-deploy-memory_{context}"] -= Configure memory for Elasticsearch instances - -By default, the amount of RAM allocated to each ES instance is 16GB. You can change this value as needed. - -Keep in mind that *half* of this value will be passed to the individual -Elasticsearch pods java processes -link:https://www.elastic.co/guide/en/elasticsearch/guide/current/heap-sizing.html#_give_half_your_memory_to_lucene[heap -size]. - -.Procedure - diff --git a/modules/cluster-logging-deploy-multitenant.adoc b/modules/cluster-logging-deploy-multitenant.adoc deleted file mode 100644 index cf78c4d60a0d..000000000000 --- a/modules/cluster-logging-deploy-multitenant.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-deploying.adoc - -[id="cluster-logging-deploy-multitenant_{context}"] -= Installing OpenShift Logging into a multitenant network - -If you are deploying OpenShift Logging into a cluster that uses multitenant isolation mode, projects are isolated from other projects. As a result, network traffic is not allowed between pods or services in different projects. - -Because the OpenShift Elasticsearch Operator and the Cluster Logging Operator are installed in different projects, you must explicitly allow access between the `openshift-operators-redhat` and `openshift-logging` projects. How you allow this access depends on how you configured multitenant isolation mode. - -.Procedure - -To allow traffic between the OpenShift Elasticsearch Operator and the Cluster Logging Operator, perform one of the following: - -* If you configured multitenant isolation mode with the OpenShift SDN CNI plug-in set to the *Multitenant* mode, use the following command to join the two projects: -+ -For example: -+ -[source,terminal] ----- -$ oc adm pod-network join-projects --to=openshift-operators-redhat openshift-logging ----- - -* If you configured multitenant isolation mode with the OpenShift SDN CNI plug-in set to the *NetworkPolicy* mode, create a network policy object in the `openshift-logging` namespace that allows ingress from the `openshift-operators-redhat` project to the `openshift-logging` project. -+ -For example: -+ -[source,yaml] ----- -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: allow-openshift-operators-redhat -spec: - ingress: - - from: - - namespaceSelector: - matchLabels: - project: openshift-operators-redhat ----- - diff --git a/modules/cluster-logging-deploy-storage-considerations.adoc b/modules/cluster-logging-deploy-storage-considerations.adoc deleted file mode 100644 index 00d8d6c12f50..000000000000 --- a/modules/cluster-logging-deploy-storage-considerations.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-deploy.adoc - -[id="cluster-logging-deploy-storage-considerations_{context}"] -= Storage considerations for OpenShift Logging and {product-title} - -//// -An Elasticsearch index is a collection of primary shards and their corresponding replica shards. This is how Elasticsearch implements high availability internally, so there is little requirement to use hardware based mirroring RAID variants. RAID 0 can still be used to increase overall disk performance. -//// - -A persistent volume is required for each Elasticsearch deployment configuration. On {product-title} this is achieved using persistent volume claims. - -[NOTE] -==== -If you use a local volume for persistent storage, do not use a raw block volume, which is described with `volumeMode: block` in the `LocalVolume` object. Elasticsearch cannot use raw block volumes. -==== - -The OpenShift Elasticsearch Operator names the PVCs using the Elasticsearch resource name. - -//// -Below are capacity planning guidelines for {product-title} aggregate logging. - -*Example scenario* - -Assumptions: - -. Which application: Apache -. Bytes per line: 256 -. Lines per second load on application: 1 -. Raw text data -> JSON - -Baseline (256 characters per minute -> 15KB/min) - -[cols="3,4",options="header"] -|=== -|Logging pods -|Storage Throughput - -|3 es -1 kibana -1 curator -1 fluentd -| 6 pods total: 90000 x 86400 = 7,7 GB/day - -|3 es -1 kibana -1 curator -11 fluentd -| 16 pods total: 225000 x 86400 = 24,0 GB/day - -|3 es -1 kibana -1 curator -20 fluentd -|25 pods total: 225000 x 86400 = 32,4 GB/day -|=== - - -Calculating the total logging throughput and disk space required for your {product-title} cluster requires knowledge of your applications. For example, if one of your applications on average logs 10 lines-per-second, each 256 bytes-per-line, calculate per-application throughput and disk space as follows: - ----- - (bytes-per-line * (lines-per-second) = 2560 bytes per app per second - (2560) * (number-of-pods-per-node,100) = 256,000 bytes per second per node - 256k * (number-of-nodes) = total logging throughput per cluster per second ----- -//// - -Fluentd ships any logs from *systemd journal* and **/var/log/containers/*.log** to Elasticsearch. - -Elasticsearch requires sufficient memory to perform large merge operations. If it does not have enough memory, it becomes unresponsive. To avoid this problem, evaluate how much application log data you need, and allocate approximately double that amount of free storage capacity. - -By default, when storage capacity is 85% full, Elasticsearch stops allocating new data to the node. At 90%, Elasticsearch attempts to relocate existing shards from that node to other nodes if possible. But if no nodes have a free capacity below 85%, Elasticsearch effectively rejects creating new indices and becomes RED. - -[NOTE] -==== -These low and high watermark values are Elasticsearch defaults in the current release. You can modify these default values. Although the alerts use the same default values, you cannot change these values in the alerts. -==== diff --git a/modules/cluster-logging-deploying-about.adoc b/modules/cluster-logging-deploying-about.adoc deleted file mode 100644 index 770baf838060..000000000000 --- a/modules/cluster-logging-deploying-about.adoc +++ /dev/null @@ -1,213 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-deploying-about.adoc - -[id="cluster-logging-deploying-about_{context}"] -= About deploying and configuring OpenShift Logging - -OpenShift Logging is designed to be used with the default configuration, which is tuned for small to medium sized {product-title} clusters. - -The installation instructions that follow include a sample `ClusterLogging` custom resource (CR), which you can use to create a OpenShift Logging instance -and configure your OpenShift Logging environment. - -If you want to use the default OpenShift Logging install, you can use the sample CR directly. - -If you want to customize your deployment, make changes to the sample CR as needed. The following describes the configurations you can make when installing your OpenShift Logging instance or modify after installation. See the Configuring sections for more information on working with each component, including modifications you can make outside of the `ClusterLogging` custom resource. - -[id="cluster-logging-deploy-about-config_{context}"] -== Configuring and Tuning OpenShift Logging - -You can configure your OpenShift Logging environment by modifying the `ClusterLogging` custom resource deployed -in the `openshift-logging` project. - -You can modify any of the following components upon install or after install: - -Memory and CPU:: -You can adjust both the CPU and memory limits for each component by modifying the `resources` -block with valid memory and CPU values: - ----- -spec: - logStore: - elasticsearch: - resources: - limits: - cpu: - memory: - requests: - cpu: 1 - memory: 16Gi - type: "elasticsearch" - collection: - logs: - fluentd: - resources: - limits: - cpu: - memory: - requests: - cpu: - memory: - type: "fluentd" - visualization: - kibana: - resources: - limits: - cpu: - memory: - requests: - cpu: - memory: - type: kibana - curation: - curator: - resources: - limits: - memory: 200Mi - requests: - cpu: 200m - memory: 200Mi - type: "curator" ----- - -Elasticsearch storage:: -You can configure a persistent storage class and size for the Elasticsearch cluster using the `storageClass` `name` and `size` parameters. The Cluster Logging Operator creates a persistent volume claim (PVC) for each data node in the Elasticsearch cluster based on these parameters. - ----- - spec: - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 3 - storage: - storageClassName: "gp2" - size: "200G" ----- - -This example specifies each data node in the cluster will be bound to a PVC that -requests "200G" of "gp2" storage. Each primary shard will be backed by a single replica. - -[NOTE] -==== -Omitting the `storage` block results in a deployment that includes ephemeral storage only. - ----- - spec: - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 3 - storage: {} ----- -==== - -Elasticsearch replication policy:: -You can set the policy that defines how Elasticsearch shards are replicated across data nodes in the cluster: - -* `FullRedundancy`. The shards for each index are fully replicated to every data node. -* `MultipleRedundancy`. The shards for each index are spread over half of the data nodes. -* `SingleRedundancy`. A single copy of each shard. Logs are always available and recoverable as long as at least two data nodes exist. -* `ZeroRedundancy`. No copies of any shards. Logs may be unavailable (or lost) in the event a node is down or fails. - -//// -Log collectors:: -You can select which log collector is deployed as a daemon set to each node in the {product-title} cluster, either: - -* Fluentd - The default log collector based on Fluentd. -* Rsyslog - Alternate log collector supported as **Tech Preview** only. - ----- - spec: - collection: - logs: - fluentd: - resources: - limits: - cpu: - memory: - requests: - cpu: - memory: - type: "fluentd" ----- -//// - -Curator schedule:: -You specify the schedule for Curator in the link:https://en.wikipedia.org/wiki/Cron[cron format]. - ----- - spec: - curation: - type: "curator" - resources: - curator: - schedule: "30 3 * * *" ----- - -[id="cluster-logging-deploy-about-sample_{context}"] -== Sample modified `ClusterLogging` custom resource - -The following is an example of a `ClusterLogging` custom resource modified using the options previously described. - -.Sample modified `ClusterLogging` custom resource ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: "openshift-logging" -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - retentionPolicy: - application: - maxAge: 1d - infra: - maxAge: 7d - audit: - maxAge: 7d - elasticsearch: - nodeCount: 3 - resources: - limits: - memory: 16Gi - requests: - cpu: 200m - memory: 16Gi - storage: - storageClassName: "gp2" - size: "200G" - redundancyPolicy: "SingleRedundancy" - visualization: - type: "kibana" - kibana: - resources: - limits: - memory: 1Gi - requests: - cpu: 500m - memory: 1Gi - replicas: 1 - curation: - type: "curator" - curator: - resources: - limits: - memory: 200Mi - requests: - cpu: 200m - memory: 200Mi - schedule: "*/5 * * * *" - collection: - logs: - type: "fluentd" - fluentd: - resources: - limits: - memory: 1Gi - requests: - cpu: 200m - memory: 1Gi ----- - diff --git a/modules/cluster-logging-document-attributes.adoc b/modules/cluster-logging-document-attributes.adoc deleted file mode 100644 index 74edda273c32..000000000000 --- a/modules/cluster-logging-document-attributes.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Standard document attributes to be used in the Logging documentation -// -// The following are shared by all RHOSSM documents: -:toc: -:toclevels: 4 -:toc-title: -:experimental: -// -// Product content attributes, that is, substitution variables in the files. -// -:product-title: OpenShift Container Platform -:ProductName: Red Hat OpenShift Logging -:ProductShortName: Logging -:ProductRelease: -:ProductVersion: 5.0.0 -:MaistraVersion: 5.0 -:product-build: -:DownloadURL: registry.redhat.io -:cloud-redhat-com: Red Hat OpenShift Cluster Manager -:kebab: image:kebab.png[title="Options menu"] -// -// Documentation publishing attributes used in the master-docinfo.xml file -// Note that the DocInfoProductName generates the URL for the product page. -// Changing the value changes the generated URL. -// -:DocInfoProductName: OpenShift Logging -:DocInfoProductNumber: 5.0 -// -// Book Names: -// Defining the book names in document attributes instead of hard-coding them in -// the master.adoc files and in link references. This makes it easy to change the -// book name if necessary. -// Using the pattern ending in 'BookName' makes it easy to grep for occurrences -// throughout the topics -// -:Install_BookName: Installing Red Hat OpenShift Logging -:Using_BookName: Using Red Hat OpenShift Logging -:RN_BookName: Red Hat OpenShift Logging Release Notes diff --git a/modules/cluster-logging-elasticsearch-audit.adoc b/modules/cluster-logging-elasticsearch-audit.adoc deleted file mode 100644 index dbd7e1ada187..000000000000 --- a/modules/cluster-logging-elasticsearch-audit.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-elasticsearch-audit_{context}"] -= Forward audit logs to the log store - -Because the internal {product-title} Elasticsearch log store does not provide secure storage for audit logs, by default audit logs are not stored in the internal Elasticsearch instance. - -If you want to send the audit logs to the internal log store, for example to view the audit logs in Kibana, you must use the Log Forwarding API. - -[IMPORTANT] -==== -The internal {product-title} Elasticsearch log store does not provide secure storage for audit logs. We recommend you ensure that the system to which you forward audit logs is compliant with your organizational and governmental regulations and is properly secured. OpenShift Logging does not comply with those regulations. -==== - -.Procedure - -To use the Log Forwarding API to forward audit logs to the internal Elasticsearch instance: - -. Create a `ClusterLogForwarder` CR YAML file or edit your existing CR: -+ -* Create a CR to send all log types to the internal Elasticsearch instance. You can use the following example without making any changes: -+ -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogForwarder -metadata: - name: instance - namespace: openshift-logging -spec: - pipelines: <1> - - name: all-to-default - inputRefs: - - infrastructure - - application - - audit - outputRefs: - - default ----- -<1> A pipeline defines the type of logs to forward using the specified output. The default output forwards logs to the internal Elasticsearch instance. -+ -[NOTE] -==== -You must specify all three types of logs in the pipeline: application, infrastructure, and audit. If you do not specify a log type, those logs are not stored and will be lost. -==== -+ -* If you have an existing `ClusterLogForwarder` CR, add a pipeline to the default output for the audit logs. You do not need to define the default output. For example: -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: ClusterLogForwarder -metadata: - name: instance - namespace: openshift-logging -spec: - outputs: - - name: elasticsearch-insecure - type: "elasticsearch" - url: http://elasticsearch-insecure.messaging.svc.cluster.local - insecure: true - - name: elasticsearch-secure - type: "elasticsearch" - url: https://elasticsearch-secure.messaging.svc.cluster.local - secret: - name: es-audit - - name: secureforward-offcluster - type: "fluentdForward" - url: https://secureforward.offcluster.com:24224 - secret: - name: secureforward - pipelines: - - name: container-logs - inputRefs: - - application - outputRefs: - - secureforward-offcluster - - name: infra-logs - inputRefs: - - infrastructure - outputRefs: - - elasticsearch-insecure - - name: audit-logs - inputRefs: - - audit - outputRefs: - - elasticsearch-secure - - default <1> ----- -<1> This pipeline sends the audit logs to the internal Elasticsearch instance in addition to an external instance. - diff --git a/modules/cluster-logging-elasticsearch-exposing.adoc b/modules/cluster-logging-elasticsearch-exposing.adoc deleted file mode 100644 index bbf457f7dd6c..000000000000 --- a/modules/cluster-logging-elasticsearch-exposing.adoc +++ /dev/null @@ -1,180 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-elasticsearch-exposing_{context}"] -= Exposing the log store service as a route - -By default, the log store that is deployed with OpenShift Logging is not -accessible from outside the logging cluster. You can enable a route with re-encryption termination -for external access to the log store service for those tools that access its data. - -Externally, you can access the log store by creating a reencrypt route, your {product-title} token and the installed -log store CA certificate. Then, access a node that hosts the log store service with a cURL request that contains: - -* The `Authorization: Bearer ${token}` -* The Elasticsearch reencrypt route and an link:https://www.elastic.co/guide/en/elasticsearch/reference/current/api-conventions.html[Elasticsearch API request]. - -Internally, you can access the log store service using the log store cluster IP, -which you can get by using either of the following commands: - -[source,terminal] ----- -$ oc get service elasticsearch -o jsonpath={.spec.clusterIP} -n openshift-logging ----- - -.Example output -[source,terminal] ----- -172.30.183.229 ----- - -[source,terminal] ----- -$ oc get service elasticsearch -n openshift-logging ----- - -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -elasticsearch ClusterIP 172.30.183.229 9200/TCP 22h ----- - -You can check the cluster IP address with a command similar to the following: - -[source,terminal] ----- -$ oc exec elasticsearch-cdm-oplnhinv-1-5746475887-fj2f8 -n openshift-logging -- curl -tlsv1.2 --insecure -H "Authorization: Bearer ${token}" "https://172.30.183.229:9200/_cat/health" ----- - -.Example output -[source,terminal] ----- - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed -100 29 100 29 0 0 108 0 --:--:-- --:--:-- --:--:-- 108 ----- - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -* You must have access to the project to be able to access to the logs. - -.Procedure - -To expose the log store externally: - -. Change to the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc project openshift-logging ----- - -. Extract the CA certificate from the log store and write to the *_admin-ca_* file: -+ -[source,terminal] ----- -$ oc extract secret/elasticsearch --to=. --keys=admin-ca ----- -+ -.Example output -[source,terminal] ----- -admin-ca ----- - -. Create the route for the log store service as a YAML file: -+ -.. Create a YAML file with the following: -+ -[source,yaml] ----- -apiVersion: route.openshift.io/v1 -kind: Route -metadata: - name: elasticsearch - namespace: openshift-logging -spec: - host: - to: - kind: Service - name: elasticsearch - tls: - termination: reencrypt - destinationCACertificate: | <1> ----- -<1> Add the log store CA certifcate or use the command in the next step. You do not have to set the `spec.tls.key`, `spec.tls.certificate`, and `spec.tls.caCertificate` parameters required by some reencrypt routes. - -.. Run the following command to add the log store CA certificate to the route YAML you created: -+ -[source,terminal] ----- -$ cat ./admin-ca | sed -e "s/^/ /" >> .yaml ----- - -.. Create the route: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -.Example output -[source,terminal] ----- -route.route.openshift.io/elasticsearch created ----- -+ -//For an example reencrypt route object, see Re-encryption Termination. -//+ -//This line ^^ will be linked when the topic is available. - -. Check that the Elasticsearch service is exposed: - -.. Get the token of this service account to be used in the request: -+ -[source,terminal] ----- -$ token=$(oc whoami -t) ----- - -.. Set the *elasticsearch* route you created as an environment variable. -+ -[source,terminal] ----- -$ routeES=`oc get route elasticsearch -o jsonpath={.spec.host}` ----- - -.. To verify the route was successfully created, run the following command that accesses Elasticsearch through the exposed route: -+ -[source,terminal] ----- -curl -tlsv1.2 --insecure -H "Authorization: Bearer ${token}" "https://${routees}/" ----- -+ -The response appears similar to the following: -+ -.Example output -[source,json] ----- -{ - "name" : "elasticsearch-cdm-i40ktba0-1", - "cluster_name" : "elasticsearch", - "cluster_uuid" : "0eY-tJzcR3KOdpgeMJo-MQ", - "version" : { - "number" : "6.8.1", - "build_flavor" : "oss", - "build_type" : "zip", - "build_hash" : "Unknown", - "build_date" : "Unknown", - "build_snapshot" : true, - "lucene_version" : "7.7.0", - "minimum_wire_compatibility_version" : "5.6.0", - "minimum_index_compatibility_version" : "5.0.0" -}, - "" : "" -} ----- diff --git a/modules/cluster-logging-elasticsearch-ha.adoc b/modules/cluster-logging-elasticsearch-ha.adoc deleted file mode 100644 index 6310c4c7b5d3..000000000000 --- a/modules/cluster-logging-elasticsearch-ha.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-elasticsearch-ha_{context}"] -= Configuring replication policy for the log store - -You can define how Elasticsearch shards are replicated across data nodes in the cluster. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc edit clusterlogging instance ----- -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - -.... - -spec: - logStore: - type: "elasticsearch" - elasticsearch: - redundancyPolicy: "SingleRedundancy" <1> ----- -<1> Specify a redundancy policy for the shards. The change is applied upon saving the changes. -+ -* *FullRedundancy*. Elasticsearch fully replicates the primary shards for each index -to every data node. This provides the highest safety, but at the cost of the highest amount of disk required and the poorest performance. -* *MultipleRedundancy*. Elasticsearch fully replicates the primary shards for each index to half of the data nodes. -This provides a good tradeoff between safety and performance. -* *SingleRedundancy*. Elasticsearch makes one copy of the primary shards for each index. -Logs are always available and recoverable as long as at least two data nodes exist. -Better performance than MultipleRedundancy, when using 5 or more nodes. You cannot -apply this policy on deployments of single Elasticsearch node. -* *ZeroRedundancy*. Elasticsearch does not make copies of the primary shards. -Logs might be unavailable or lost in the event a node is down or fails. -Use this mode when you are more concerned with performance than safety, or have -implemented your own disk/PVC backup/restore strategy. - -[NOTE] -==== -The number of primary shards for the index templates is equal to the number of Elasticsearch data nodes. -==== - diff --git a/modules/cluster-logging-elasticsearch-persistent-storage-empty.adoc b/modules/cluster-logging-elasticsearch-persistent-storage-empty.adoc deleted file mode 100644 index 1b78a8e59497..000000000000 --- a/modules/cluster-logging-elasticsearch-persistent-storage-empty.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch-storage.adoc - -[id="cluster-logging-elasticsearch-persistent-storage-empty_{context}"] -= Configuring the log store for emptyDir storage - -You can use emptyDir with your log store, which creates an ephemeral -deployment in which all of a pod's data is lost upon restart. - -[NOTE] -==== -When using emptyDir, if log storage is restarted or redeployed, you will lose data. -==== - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Edit the `ClusterLogging` CR to specify emptyDir: -+ -[source,yaml] ----- - spec: - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 3 - storage: {} ----- - - diff --git a/modules/cluster-logging-elasticsearch-retention.adoc b/modules/cluster-logging-elasticsearch-retention.adoc deleted file mode 100644 index 7190ef3b0230..000000000000 --- a/modules/cluster-logging-elasticsearch-retention.adoc +++ /dev/null @@ -1,127 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-elasticsearch-retention_{context}"] -= Configuring log retention time - -You can specify how long the default Elasticsearch log store keeps indices using a separate _retention policy_ for each of the three log sources: infrastructure logs, application logs, and audit logs. The retention policy, which you configure using the `maxAge` parameter in the Cluster Logging custom resource (CR), is considered for the Elasticsearch roll over schedule and determines when Elasticsearch deletes the rolled-over indices. - -Elasticsearch rolls over an index, moving the current index and creating a new -index, when an index matches any of the following conditions: - -* The index is older than the `rollover.maxAge` value in the `Elasticsearch` CR. -* The index size is greater than 40 GB × the number of primary shards. -* The index doc count is greater than 40960 KB × the number of primary shards. - -Elasticsearch deletes the rolled-over indices are deleted based on the -retention policy you configure. - -If you do not create a retention policy for any of the log sources, logs -are deleted after seven days by default. - -[IMPORTANT] -==== -If you do not specify a retention policy for all three log sources, only logs -from the sources with a retention policy are stored. For example, if you -set a retention policy for the infrastructure and applicaiton logs, but do not -set a retention policy for audit logs, the audit logs will not be retained -and there will be no *audit-* index in Elasticsearch or Kibana. -==== - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -To configure the log retention time: - -. Edit the `ClusterLogging` CR to add or modify the `retentionPolicy` parameter: -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -... -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - retentionPolicy: <1> - application: - maxAge: 1d - infra: - maxAge: 7d - audit: - maxAge: 7d - elasticsearch: - nodeCount: 3 -... ----- -<1> Specify the time that Elasticsearch should retain each log source. Enter an -integer and a time designation: weeks(w), hours(h/H), minutes(m) and seconds(s). -For example, `1d` for one day. Logs older than the `maxAge` are deleted. -By default, logs are retained for seven days. - -. You can verify the settings in the `Elasticsearch` custom resource (CR). -+ -For example, the Cluster Logging Operator updated the following -`Elasticsearch` CR to configure a retention policy that includes settings -to roll over active indices for the infrastructure logs every eight hours and -the rolled-ver indices are deleted seven days after rollover. {product-title} checks -every 15 minutes to determine if the indices need to be rolled over. -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "Elasticsearch" -metadata: - name: "elasticsearch" -spec: -... - indexManagement: - policies: <1> - - name: infra-policy - phases: - delete: - minAge: 7d <2> - hot: - actions: - rollover: - maxAge: 8h <3> - pollInterval: 15m <4> -... ----- -<1> For each log source, the retention policy indicates when to delete and -rollover logs for that source. -<2> When {product-title} deletes the rolled-over indices. This setting -is the `maxAge` you set in the `ClusterLogging` CR. -<3> The index age for {product-title} to consider when rolling over the indices. -This value is determined from the `maxAge` you set in the `ClusterLogging` CR. -<4> When {product-title} checks if the indices should be rolled over. -This setting is the default and cannot be changed. -+ -[NOTE] -==== -Modifying the `Elasticsearch` CR is not supported. All changes to the retention -policies must be made in the `ClusterLogging` CR. -==== -+ -The OpenShift Elasticsearch Operator deploys a cron job to roll over indices for each -mapping using the defined policy, scheduled using the `pollInterval`. -+ -[source,terminal] ----- -$ oc get cronjob ----- -+ -.Example output -[source,terminal] ----- -NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE -curator */10 * * * * False 0 5s -elasticsearch-im-app */15 * * * * False 0 4s -elasticsearch-im-audit */15 * * * * False 0 4s -elasticsearch-im-infra */15 * * * * False 0 4s ----- diff --git a/modules/cluster-logging-elasticsearch-rules.adoc b/modules/cluster-logging-elasticsearch-rules.adoc deleted file mode 100644 index 9d134de23551..000000000000 --- a/modules/cluster-logging-elasticsearch-rules.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch - -[id="cluster-logging-elasticsearch-rules_{context}"] -= About Elasticsearch alerting rules - -You can view these alerting rules in Prometheus. - -[cols="3,6,1",options="header"] -|=== -|Alert -|Description -|Severity - - -|ElasticsearchClusterNotHealthy -|The cluster health status has been RED for at least 2 minutes. The cluster does not accept writes, shards may be missing, or the master - node hasn't been elected yet. -|critical - -|ElasticsearchClusterNotHealthy -|The cluster health status has been YELLOW for at least 20 minutes. Some shard replicas are not allocated. -|warning - -|ElasticsearchDiskSpaceRunningLow -|The cluster is expected to be out of disk space within the next 6 hours. -|Critical - -|ElasticsearchHighFileDescriptorUsage -|The cluster is predicted to be out of file descriptors within the next hour. -|warning - -|ElasticsearchJVMHeapUseHigh -|The JVM Heap usage on the specified node is high. -|Alert - -|ElasticsearchNodeDiskWatermarkReached -|The specified node has hit the low watermark due to low free disk space. Shards can not be allocated to this node anymore. You should consider adding more disk space to the node. -|info - -|ElasticsearchNodeDiskWatermarkReached -|The specified node has hit the high watermark due to low free disk space. Some shards will be re-allocated to different -nodes if possible. Make sure more disk space is added to the node or drop old indices allocated to this node. -|warning - -|ElasticsearchNodeDiskWatermarkReached -|The specified node has hit the flood watermark due to low free disk space. Every index that has a shard allocated on this node is enforced a read-only block. The index block must be manually released when the disk use falls below the high watermark. -|critical - -|ElasticsearchJVMHeapUseHigh -|The JVM Heap usage on the specified node is too high. -|alert - -|ElasticsearchWriteRequestsRejectionJumps -|Elasticsearch is experiencing an increase in write rejections on the specified node. This node might not be keeping up with the indexing speed. -|Warning - -|AggregatedLoggingSystemCPUHigh -|The CPU used by the system on the specified node is too high. -|alert - -|ElasticsearchProcessCPUHigh -|The CPU used by Elasticsearch on the specified node is too high. -|alert -|=== diff --git a/modules/cluster-logging-elasticsearch-scaledown.adoc b/modules/cluster-logging-elasticsearch-scaledown.adoc deleted file mode 100644 index dea23e5cc746..000000000000 --- a/modules/cluster-logging-elasticsearch-scaledown.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-log-store.adoc - -[id="cluster-logging-elasticsearch-scaledown_{context}"] -= Scaling down Elasticsearch pods - -Reducing the number of Elasticsearch pods in your cluster can result in data loss or Elasticsearch performance degradation. - -If you scale down, you should scale down by one pod at a time and allow the cluster to re-balance the shards and replicas. After the Elasticsearch health status returns to `green`, you can scale down by another pod. - -[NOTE] -==== -If your Elasticsearch cluster is set to `ZeroRedundancy`, you should not scale down your Elasticsearch pods. -==== diff --git a/modules/cluster-logging-elasticsearch-storage.adoc b/modules/cluster-logging-elasticsearch-storage.adoc deleted file mode 100644 index e532a1360f19..000000000000 --- a/modules/cluster-logging-elasticsearch-storage.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-elasticsearch-storage_{context}"] -= Configuring persistent storage for the log store - -Elasticsearch requires persistent storage. The faster the storage, the faster the Elasticsearch performance. - -[WARNING] -==== -Using NFS storage as a volume or a persistent volume (or via NAS such as -Gluster) is not supported for Elasticsearch storage, as Lucene relies on file -system behavior that NFS does not supply. Data corruption and other problems can -occur. -==== - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Edit the `ClusterLogging` CR to specify that each data node in the cluster is bound to a Persistent Volume Claim. -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - -.... - - spec: - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 3 - storage: - storageClassName: "gp2" - size: "200G" ----- - -This example specifies each data node in the cluster is bound to a Persistent Volume Claim that requests "200G" of AWS General Purpose SSD (gp2) storage. - -[NOTE] -==== -If you use a local volume for persistent storage, do not use a raw block volume, which is described with `volumeMode: block` in the `LocalVolume` object. Elasticsearch cannot use raw block volumes. -==== diff --git a/modules/cluster-logging-elasticsearch-tolerations.adoc b/modules/cluster-logging-elasticsearch-tolerations.adoc deleted file mode 100644 index ae4ed73dc2cc..000000000000 --- a/modules/cluster-logging-elasticsearch-tolerations.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-elasticsearch-tolerations_{context}"] -= Using tolerations to control the log store pod placement - -You can control which nodes the log store pods runs on and prevent -other workloads from using those nodes by using tolerations on the pods. - -You apply tolerations to the log store pods through the `ClusterLogging` custom resource (CR) -and apply taints to a node through the node specification. A taint on a node is a `key:value pair` that -instructs the node to repel all pods that do not tolerate the taint. Using a specific `key:value` pair -that is not on other pods ensures only the log store pods can run on that node. - -By default, the log store pods have the following toleration: - -[source,yaml] ----- -tolerations: -- effect: "NoExecute" - key: "node.kubernetes.io/disk-pressure" - operator: "Exists" ----- - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Use the following command to add a taint to a node where you want to schedule the OpenShift Logging pods: -+ -[source,terminal] ----- -$ oc adm taint nodes =: ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm taint nodes node1 elasticsearch=node:NoExecute ----- -+ -This example places a taint on `node1` that has key `elasticsearch`, value `node`, and taint effect `NoExecute`. -Nodes with the `NoExecute` effect schedule only pods that match the taint and remove existing pods -that do not match. - -. Edit the `logstore` section of the `ClusterLogging` CR to configure a toleration for the Elasticsearch pods: -+ -[source,yaml] ----- - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 1 - tolerations: - - key: "elasticsearch" <1> - operator: "Exists" <2> - effect: "NoExecute" <3> - tolerationSeconds: 6000 <4> ----- -<1> Specify the key that you added to the node. -<2> Specify the `Exists` operator to require a taint with the key `elasticsearch` to be present on the Node. -<3> Specify the `NoExecute` effect. -<4> Optionally, specify the `tolerationSeconds` parameter to set how long a pod can remain bound to a node before being evicted. - -This toleration matches the taint created by the `oc adm taint` command. A pod with this toleration could be scheduled onto `node1`. diff --git a/modules/cluster-logging-eventrouter-about.adoc b/modules/cluster-logging-eventrouter-about.adoc deleted file mode 100644 index 79719c38718e..000000000000 --- a/modules/cluster-logging-eventrouter-about.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging.adoc - -[id="cluster-logging-eventrouter-about_{context}"] -= About event routing - -The Event Router is a pod that watches {product-title} events so they can be collected by OpenShift Logging. -The Event Router collects events from all projects and writes them to `STDOUT`. Fluentd collects those events and forwards them into the {product-title} Elasticsearch instance. Elasticsearch indexes the events to the `infra` index. - -You must manually deploy the Event Router. diff --git a/modules/cluster-logging-eventrouter-deploy.adoc b/modules/cluster-logging-eventrouter-deploy.adoc deleted file mode 100644 index 6317253c23c1..000000000000 --- a/modules/cluster-logging-eventrouter-deploy.adoc +++ /dev/null @@ -1,188 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-eventrouter.adoc - -[id="cluster-logging-eventrouter-deploy_{context}"] -= Deploying and configuring the Event Router - -Use the following steps to deploy the Event Router into your cluster. You should always deploy the Event Router to the `openshift-logging` project to ensure it collects events from across the cluster. - -The following Template object creates the service account, cluster role, and cluster role binding required for the Event Router. The template also configures and deploys the Event Router pod. You can use this template without making changes, or change the deployment object CPU and memory requests. - -.Prerequisites - -* You need proper permissions to create service accounts and update cluster role bindings. For example, you can run the following template with a user that has the *cluster-admin* role. - -* OpenShift Logging must be installed. - -.Procedure - -. Create a template for the Event Router: -+ -[source,yaml] ----- -kind: Template -apiVersion: v1 -metadata: - name: eventrouter-template - annotations: - description: "A pod forwarding kubernetes events to OpenShift Logging stack." - tags: "events,EFK,logging,cluster-logging" -objects: - - kind: ServiceAccount <1> - apiVersion: v1 - metadata: - name: eventrouter - namespace: ${NAMESPACE} - - kind: ClusterRole <2> - apiVersion: v1 - metadata: - name: event-reader - rules: - - apiGroups: [""] - resources: ["events"] - verbs: ["get", "watch", "list"] - - kind: ClusterRoleBinding <3> - apiVersion: v1 - metadata: - name: event-reader-binding - subjects: - - kind: ServiceAccount - name: eventrouter - namespace: ${NAMESPACE} - roleRef: - kind: ClusterRole - name: event-reader - - kind: ConfigMap <4> - apiVersion: v1 - metadata: - name: eventrouter - namespace: ${NAMESPACE} - data: - config.json: |- - { - "sink": "stdout" - } - - kind: Deployment <5> - apiVersion: apps/v1 - metadata: - name: eventrouter - namespace: ${NAMESPACE} - labels: - component: eventrouter - logging-infra: eventrouter - provider: openshift - spec: - selector: - matchLabels: - component: eventrouter - logging-infra: eventrouter - provider: openshift - replicas: 1 - template: - metadata: - labels: - component: eventrouter - logging-infra: eventrouter - provider: openshift - name: eventrouter - spec: - serviceAccount: eventrouter - containers: - - name: kube-eventrouter - image: ${IMAGE} - imagePullPolicy: IfNotPresent - resources: - requests: - cpu: ${CPU} - memory: ${MEMORY} - volumeMounts: - - name: config-volume - mountPath: /etc/eventrouter - volumes: - - name: config-volume - configMap: - name: eventrouter -parameters: - - name: IMAGE - displayName: Image - value: "registry.redhat.io/openshift-logging/eventrouter-rhel8:latest" - - name: CPU <6> - displayName: CPU - value: "100m" - - name: MEMORY <7> - displayName: Memory - value: "128Mi" - - name: NAMESPACE - displayName: Namespace - value: "openshift-logging" <8> ----- -<1> Creates a Service Account in the `openshift-logging` project for the Event Router. -<2> Creates a ClusterRole to monitor for events in the cluster. -<3> Creates a ClusterRoleBinding to bind the ClusterRole to the service account. -<4> Creates a config map in the `openshift-logging` project to generate the required `config.json` file. -<5> Creates a deployment in the `openshift-logging` project to generate and configure the Event Router pod. -<6> Specifies the minimum amount of memory to allocate to the Event Router pod. Defaults to `128Mi`. -<7> Specifies the minimum amount of CPU to allocate to the Event Router pod. Defaults to `100m`. -<8> Specifies the `openshift-logging` project to install objects in. - -. Use the following command to process and apply the template: -+ -[source,terminal] ----- -$ oc process -f | oc apply -n openshift-logging -f - ----- -+ -For example: -+ -[source,terminal] ----- -$ oc process -f eventrouter.yaml | oc apply -n openshift-logging -f - ----- -+ -.Example output -[source,terminal] ----- -serviceaccount/logging-eventrouter created -clusterrole.authorization.openshift.io/event-reader created -clusterrolebinding.authorization.openshift.io/event-reader-binding created -configmap/logging-eventrouter created -deployment.apps/logging-eventrouter created ----- - -. Validate that the Event Router installed in the `openshift-logging` project: -+ -.. View the new Event Router pod: -+ -[source,terminal] ----- -$ oc get pods --selector component=eventrouter -o name -n openshift-logging ----- -+ -.Example output -[source,terminal] ----- -pod/cluster-logging-eventrouter-d649f97c8-qvv8r ----- - -.. View the events collected by the Event Router: -+ -[source,terminal] ----- -$ oc logs -n openshift-logging ----- -+ -For example: -+ -[source,terminal] ----- -$ oc logs cluster-logging-eventrouter-d649f97c8-qvv8r -n openshift-logging ----- -+ -.Example output -[source,terminal] ----- -{"verb":"ADDED","event":{"metadata":{"name":"openshift-service-catalog-controller-manager-remover.1632d931e88fcd8f","namespace":"openshift-service-catalog-removed","selfLink":"/api/v1/namespaces/openshift-service-catalog-removed/events/openshift-service-catalog-controller-manager-remover.1632d931e88fcd8f","uid":"787d7b26-3d2f-4017-b0b0-420db4ae62c0","resourceVersion":"21399","creationTimestamp":"2020-09-08T15:40:26Z"},"involvedObject":{"kind":"Job","namespace":"openshift-service-catalog-removed","name":"openshift-service-catalog-controller-manager-remover","uid":"fac9f479-4ad5-4a57-8adc-cb25d3d9cf8f","apiVersion":"batch/v1","resourceVersion":"21280"},"reason":"Completed","message":"Job completed","source":{"component":"job-controller"},"firstTimestamp":"2020-09-08T15:40:26Z","lastTimestamp":"2020-09-08T15:40:26Z","count":1,"type":"Normal"}} ----- -+ -You can also use Kibana to view events by creating an index pattern using the Elasticsearch `infra` index. diff --git a/modules/cluster-logging-exported-fields-aushape.adoc b/modules/cluster-logging-exported-fields-aushape.adoc deleted file mode 100644 index 3223ed28b26e..000000000000 --- a/modules/cluster-logging-exported-fields-aushape.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-aushape_{context}"] -= Aushape exported fields - -These are the Aushape fields exported by OpenShift Logging available for searching -from Elasticsearch and Kibana. - -Audit events converted with Aushape. For more information, see -link:https://github.com/Scribery/aushape[Aushape]. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `aushape.serial` -|Audit event serial number. - -| `aushape.node` -|Name of the host where the audit event occurred. - -| `aushape.error` -|The error aushape encountered while converting the event. - -| `aushape.trimmed` -|An array of JSONPath expressions relative to the event object, specifying -objects or arrays with the content removed as the result of event size limiting. -An empty string means the event removed the content, and an empty array means -the trimming occurred by unspecified objects and arrays. - -| `aushape.text` -|An array log record strings representing the original audit event. -|=== - -[discrete] -[id="exported-fields-aushape.data_{context}"] -=== `aushape.data` Fields - -Parsed audit event data related to Aushape. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `aushape.data.avc` -|type: nested - -| `aushape.data.execve` -|type: string - -| `aushape.data.netfilter_cfg` -|type: nested - -| `aushape.data.obj_pid` -|type: nested - -| `aushape.data.path` -|type: nested -|=== diff --git a/modules/cluster-logging-exported-fields-container.adoc b/modules/cluster-logging-exported-fields-container.adoc deleted file mode 100644 index d893b804f0cc..000000000000 --- a/modules/cluster-logging-exported-fields-container.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-container_{context}"] -= Container exported fields - -These are the Docker fields exported by OpenShift Logging available for searching from Elasticsearch and Kibana. -Namespace for docker container-specific metadata. The docker.container_id is the Docker container ID. - - -[discrete] -[id="exported-fields-pipeline_metadata.collector_{context}"] -=== `pipeline_metadata.collector` Fields - -This section contains metadata specific to the collector. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `pipeline_metadata.collector.hostname` -|FQDN of the collector. It might be different from the FQDN of the actual emitter -of the logs. - -| `pipeline_metadata.collector.name` -|Name of the collector. - -| `pipeline_metadata.collector.version` -|Version of the collector. - -| `pipeline_metadata.collector.ipaddr4` -|IP address v4 of the collector server, can be an array. - -| `pipeline_metadata.collector.ipaddr6` -|IP address v6 of the collector server, can be an array. - -| `pipeline_metadata.collector.inputname` -|How the log message was received by the collector whether it was TCP/UDP, or -imjournal/imfile. - -| `pipeline_metadata.collector.received_at` -|Time when the message was received by the collector. - -| `pipeline_metadata.collector.original_raw_message` -|The original non-parsed log message, collected by the collector or as close to the -source as possible. -|=== - -[discrete] -[id="exported-fields-pipeline_metadata.normalizer_{context}"] -=== `pipeline_metadata.normalizer` Fields - -This section contains metadata specific to the normalizer. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `pipeline_metadata.normalizer.hostname` -|FQDN of the normalizer. - -| `pipeline_metadata.normalizer.name` -|Name of the normalizer. - -| `pipeline_metadata.normalizer.version` -|Version of the normalizer. - -| `pipeline_metadata.normalizer.ipaddr4` -|IP address v4 of the normalizer server, can be an array. - -| `pipeline_metadata.normalizer.ipaddr6` -|IP address v6 of the normalizer server, can be an array. - -| `pipeline_metadata.normalizer.inputname` -|how the log message was received by the normalizer whether it was TCP/UDP. - -| `pipeline_metadata.normalizer.received_at` -|Time when the message was received by the normalizer. - -| `pipeline_metadata.normalizer.original_raw_message` -|The original non-parsed log message as it is received by the normalizer. - -| `pipeline_metadata.trace` -|The field records the trace of the message. Each collector and normalizer appends -information about itself and the date and time when the message was processed. -|=== diff --git a/modules/cluster-logging-exported-fields-default.adoc b/modules/cluster-logging-exported-fields-default.adoc deleted file mode 100644 index dddc43bcd774..000000000000 --- a/modules/cluster-logging-exported-fields-default.adoc +++ /dev/null @@ -1,1100 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-default_{context}"] -= Default exported fields - -These are the default fields exported by the logging system and available for searching -from Elasticsearch and Kibana. The default fields are Top Level and `collectd*` - -[discrete] -=== Top Level Fields - -The top level fields are common to every application, and may be present in -every record. For the Elasticsearch template, top level fields populate the actual -mappings of `default` in the template's mapping section. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `@timestamp` -| The UTC value marking when the log payload was created, or when the log payload -was first collected if the creation time is not known. This is the log -processing pipeline’s best effort determination of when the log payload was -generated. Add the `@` prefix convention to note a field as being reserved for a -particular use. With Elasticsearch, most tools look for `@timestamp` by default. -For example, the format would be 2015-01-24 14:06:05.071000. - -| `geoip` -|This is geo-ip of the machine. - -| `hostname` -|The `hostname` is the fully qualified domain name (FQDN) of the entity -generating the original payload. This field is an attempt to derive this -context. Sometimes the entity generating it knows the context. While other times -that entity has a restricted namespace itself, which is known by the collector -or normalizer. - -| `ipaddr4` -|The IP address V4 of the source server, which can be an array. - -| `ipaddr6` -|The IP address V6 of the source server, if available. - -| `level` -|The logging level as provided by rsyslog (severitytext property), python's -logging module. Possible values are as listed at -link:http://sourceware.org/git/?p=glibc.git;a=blob;f=misc/sys/syslog.h;h=ee01478c4b19a954426a96448577c5a76e6647c0;hb=HEAD#l74[`misc/sys/syslog.h`] -plus `trace` and `unknown`. For example, _alert crit debug emerg err info notice -trace unknown warning_. Note that `trace` is not in the `syslog.h` list but many -applications use it. - -* You should only use `unknown` when the logging system gets a value it does not -understand, and note that it is the highest level. - -* Consider `trace` as higher or more verbose, than `debug`. - -* `error` is deprecated, use `err`. - -* Convert `panic` to `emerg`. - -* Convert `warn` to `warning`. - -Numeric values from `syslog/journal PRIORITY` can usually be mapped using the -priority values as listed at -link:http://sourceware.org/git/?p=glibc.git;a=blob;f=misc/sys/syslog.h;h=ee01478c4b19a954426a96448577c5a76e6647c0;hb=HEAD#l51[misc/sys/syslog.h]. - -Log levels and priorities from other logging systems should be mapped to the -nearest match. See -link:https://docs.python.org/2.7/library/logging.html#logging-levels[python -logging] for an example. - -| `message` -|A typical log entry message, or payload. It can be stripped of metadata pulled -out of it by the collector or normalizer, that is UTF-8 encoded. - -| `pid` -|This is the process ID of the logging entity, if available. - -| `service` -|The name of the service associated with the logging entity, if available. For -example, the `syslog APP-NAME` property is mapped to -the service field. - -| `tags` -|Optionally provided operator defined list of tags placed on each log by the -collector or normalizer. The payload can be a string with whitespace-delimited -string tokens, or a JSON list of string tokens. - -| `file` -|Optional path to the file containing the log entry local to the collector `TODO` -analyzer for file paths. - -| `offset` -|The offset value can represent bytes to the start of the log line in the file -(zero or one based), or log line numbers (zero or one based), as long as the -values are strictly monotonically increasing in the context of a single log -file. The values are allowed to wrap, representing a new version of the log file -(rotation). - -| `namespace_name` -|Associate this record with the `namespace` that shares it's name. This value -will not be stored, but it is used to associate the record with the appropriate -`namespace` for access control and visualization. Normally this value will be -given in the tag, but if the protocol does not support sending a tag, this field -can be used. If this field is present, it will override the `namespace` given in -the tag or in `kubernetes.namespace_name`. - -| `namespace_uuid` -|This is the `uuid` associated with the `namespace_name`. This value will not be -stored, but is used to associate the record with the appropriate namespace for -access control and visualization. If this field is present, it will override the -`uuid` given in `kubernetes.namespace_uuid`. This will also cause the Kubernetes -metadata lookup to be skipped for this log record. -|=== - -[discrete] -=== `collectd` Fields - -The following fields represent namespace metrics metadata. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interval` -|type: float - -The `collectd` interval. - -| `collectd.plugin` -|type: string - -The `collectd` plug-in. - -| `collectd.plugin_instance` -|type: string - -The `collectd` plugin_instance. - -| `collectd.type_instance` -|type: string - -The `collectd` `type_instance`. - -| `collectd.type` -|type: string - -The `collectd` type. - -| `collectd.dstypes` -|type: string - -The `collectd` dstypes. -|=== - -[discrete] -[id="exported-fields-collectd.processes_{context}"] -=== `collectd.processes` Fields - -The following field corresponds to the `collectd` processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_state` -|type: integer -The `collectd ps_state` type of processes plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_disk_ops_{context}"] -=== `collectd.processes.ps_disk_ops` Fields - -The `collectd` `ps_disk_ops` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_disk_ops.read` -|type: float - -`TODO` - -| `collectd.processes.ps_disk_ops.write` -|type: float - -`TODO` - -| `collectd.processes.ps_vm` -|type: integer - -The `collectd` `ps_vm` type of processes plug-in. - -| `collectd.processes.ps_rss` -|type: integer - -The `collectd` `ps_rss` type of processes plug-in. - -| `collectd.processes.ps_data` -|type: integer - -The `collectd` `ps_data` type of processes plug-in. - -| `collectd.processes.ps_code` -|type: integer - -The `collectd` `ps_code` type of processes plug-in. - -| `collectd.processes.ps_stacksize` -| type: integer - -The `collectd` `ps_stacksize` type of processes plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_cputime_{context}"] -=== `collectd.processes.ps_cputime` Fields - -The `collectd` `ps_cputime` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_cputime.user` -|type: float - -`TODO` - -| `collectd.processes.ps_cputime.syst` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_count_{context}"] -=== `collectd.processes.ps_count` Fields - -The `collectd` `ps_count` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_count.processes` -|type: integer - -`TODO` - -| `collectd.processes.ps_count.threads` -|type: integer - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_pagefaults_{context}"] -=== `collectd.processes.ps_pagefaults` Fields - -The `collectd` `ps_pagefaults` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_pagefaults.majflt` -|type: float - -`TODO` - -| `collectd.processes.ps_pagefaults.minflt` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.processes.ps_disk_octets_{context}"] -=== `collectd.processes.ps_disk_octets` Fields - -The `collectd ps_disk_octets` type of processes plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.processes.ps_disk_octets.read` -|type: float - -`TODO` - -| `collectd.processes.ps_disk_octets.write` -|type: float - -`TODO` - -| `collectd.processes.fork_rate` -|type: float - -The `collectd` `fork_rate` type of processes plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.disk_{context}"] -=== `collectd.disk` Fields - -Corresponds to `collectd` disk plug-in. - -[discrete] -[id="exported-fields-collectd.disk.disk_merged_{context}"] -=== `collectd.disk.disk_merged` Fields - -The `collectd` `disk_merged` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_merged.read` -|type: float - -`TODO` - -| `collectd.disk.disk_merged.write` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.disk.disk_octets_{context}"] -=== `collectd.disk.disk_octets` Fields - -The `collectd` `disk_octets` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_octets.read` -|type: float - -`TODO` - -| `collectd.disk.disk_octets.write` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.disk.disk_time_{context}"] -=== `collectd.disk.disk_time` Fields - -The `collectd` `disk_time` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_time.read` -|type: float - -`TODO` - -| `collectd.disk.disk_time.write` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.disk.disk_ops_{context}"] -=== `collectd.disk.disk_ops` Fields - -The `collectd` `disk_ops` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_ops.read` -|type: float - -`TODO` - -| `collectd.disk.disk_ops.write` -|type: float - -`TODO` - -| `collectd.disk.pending_operations` -|type: integer - -The `collectd` `pending_operations` type of disk plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.disk.disk_io_time_{context}"] -=== `collectd.disk.disk_io_time` Fields - -The `collectd disk_io_time` type of disk plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.disk.disk_io_time.io_time` -|type: float - -`TODO` - -| `collectd.disk.disk_io_time.weighted_io_time` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.interface_{context}"] -=== `collectd.interface` Fields - -Corresponds to the `collectd` interface plug-in. - -[discrete] -[id="exported-fields-collectd.interface.if_octets_{context}"] -=== `collectd.interface.if_octets` Fields - -The `collectd` `if_octets` type of interface plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interface.if_octets.rx` -|type: float - -`TODO` - -| `collectd.interface.if_octets.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.interface.if_packets_{context}"] -=== `collectd.interface.if_packets` Fields - -The `collectd` `if_packets` type of interface plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interface.if_packets.rx` -|type: float - -`TODO` - -| `collectd.interface.if_packets.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.interface.if_errors_{context}"] -=== `collectd.interface.if_errors` Fields - -The `collectd` `if_errors` type of interface plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interface.if_errors.rx` -|type: float - -`TODO` - -| `collectd.interface.if_errors.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.interface.if_dropped_{context}"] -=== collectd.interface.if_dropped Fields - -The `collectd` `if_dropped` type of interface plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.interface.if_dropped.rx` -|type: float - -`TODO` - -| `collectd.interface.if_dropped.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt_{context}"] -=== `collectd.virt` Fields - -Corresponds to `collectd` virt plug-in. - -[discrete] -[id="exported-fields-collectd.virt.if_octets_{context}"] -=== `collectd.virt.if_octets` Fields - -The `collectd if_octets` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.if_octets.rx` -|type: float - -`TODO` - -| `collectd.virt.if_octets.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.if_packets_{context}"] -=== `collectd.virt.if_packets` Fields - -The `collectd` `if_packets` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.if_packets.rx` -|type: float - -`TODO` - -| `collectd.virt.if_packets.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.if_errors_{context}"] -=== `collectd.virt.if_errors` Fields - -The `collectd` `if_errors` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.if_errors.rx` -|type: float - -`TODO` - -| `collectd.virt.if_errors.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.if_dropped_{context}"] -=== `collectd.virt.if_dropped` Fields - -The `collectd` `if_dropped` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.if_dropped.rx` -|type: float - -`TODO` - -| `collectd.virt.if_dropped.tx` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.disk_ops_{context}"] -=== `collectd.virt.disk_ops` Fields - -The `collectd` `disk_ops` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.disk_ops.read` -|type: float - -`TODO` - -| `collectd.virt.disk_ops.write` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.virt.disk_octets_{context}"] -=== `collectd.virt.disk_octets` Fields - -The `collectd` `disk_octets` type of virt plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.virt.disk_octets.read` -|type: float - -`TODO` - -| `collectd.virt.disk_octets.write` -|type: float - -`TODO` - -| `collectd.virt.memory` -|type: float - -The `collectd` memory type of virt plug-in. - -| `collectd.virt.virt_vcpu` -|type: float - -The `collectd` `virt_vcpu` type of virt plug-in. - -| `collectd.virt.virt_cpu_total` -|type: float - -The `collectd` `virt_cpu_total` type of virt plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.CPU_{context}"] -=== `collectd.CPU` Fields - -Corresponds to the `collectd` CPU plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.CPU.percent` -|type: float - -The `collectd` type percent of plug-in CPU. -|=== - -[discrete] -[id="exported-fields-collectd.df_{context}"] -=== collectd.df Fields - -Corresponds to the `collectd` `df` plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.df.df_complex` -|type: float - -The `collectd` type `df_complex` of plug-in `df`. - -| `collectd.df.percent_bytes` -|type: float - -The `collectd` type `percent_bytes` of plug-in `df`. -|=== - -[discrete] -[id="exported-fields-collectd.entropy_{context}"] -=== `collectd.entropy` Fields - -Corresponds to the `collectd` entropy plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.entropy.entropy` -|type: integer - -The `collectd` entropy type of entropy plug-in. -|=== - -//// -[discrete] -[id="exported-fields-collectd.nfs_{context}"] -=== `collectd.nfs` Fields - -Corresponds to the `collectd` NFS plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.nfs.nfs_procedure` -|type: integer - -The `collectd` `nfs_procedure` type of nfs plug-in. -|=== -//// - -[discrete] -[id="exported-fields-collectd.memory_{context}"] -=== `collectd.memory` Fields - -Corresponds to the `collectd` memory plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.memory.memory` -|type: float - -The `collectd` memory type of memory plug-in. - -| `collectd.memory.percent` -|type: float - -The `collectd` percent type of memory plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.swap_{context}"] -=== `collectd.swap` Fields - -Corresponds to the `collectd` swap plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.swap.swap` -|type: integer - -The `collectd` swap type of swap plug-in. - -| `collectd.swap.swap_io` -|type: integer - -The `collectd swap_io` type of swap plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.load_{context}"] -=== `collectd.load` Fields - -Corresponds to the `collectd` load plug-in. - -[discrete] -[id="exported-fields-collectd.load.load_{context}"] -=== `collectd.load.load` Fields - -The `collectd` load type of load plug-in - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.load.load.shortterm` -|type: float - -`TODO` - -| `collectd.load.load.midterm` -|type: float - -`TODO` - -| `collectd.load.load.longterm` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.aggregation_{context}"] -=== `collectd.aggregation` Fields - -Corresponds to `collectd` aggregation plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.aggregation.percent` -|type: float - -`TODO` -|=== - -[discrete] -[id="exported-fields-collectd.statsd_{context}"] -=== `collectd.statsd` Fields - -Corresponds to `collectd` `statsd` plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.statsd.host_cpu` -|type: integer - -The `collectd` CPU type of `statsd` plug-in. - -| `collectd.statsd.host_elapsed_time` -|type: integer - -The `collectd` `elapsed_time` type of `statsd` plug-in. - -| `collectd.statsd.host_memory` -|type: integer - -The `collectd` memory type of `statsd` plug-in. - -| `collectd.statsd.host_nic_speed` -|type: integer - -The `collectd` `nic_speed` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_rx` -|type: integer - -The `collectd` `nic_rx` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_tx` -|type: integer - -The `collectd` `nic_tx` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_rx_dropped` -|type: integer - -The `collectd` `nic_rx_dropped` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_tx_dropped` -|type: integer - -The `collectd` `nic_tx_dropped` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_rx_errors` -|type: integer - -The `collectd` `nic_rx_errors` type of `statsd` plug-in. - -| `collectd.statsd.host_nic_tx_errors` -|type: integer - -The `collectd` `nic_tx_errors` type of `statsd` plug-in. - -| `collectd.statsd.host_storage` -|type: integer - -The `collectd` storage type of `statsd` plug-in. - -| `collectd.statsd.host_swap` -|type: integer - -The `collectd` swap type of `statsd` plug-in. - -| `collectd.statsd.host_vdsm` -|type: integer - -The `collectd` VDSM type of `statsd` plug-in. - -| `collectd.statsd.host_vms` -|type: integer - -The `collectd` VMS type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_tx_dropped` -|type: integer - -The `collectd` `nic_tx_dropped` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_rx_bytes` -|type: integer - -The `collectd` `nic_rx_bytes` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_tx_bytes` -|type: integer - -The `collectd` `nic_tx_bytes` type of `statsd` plug-in. - -| `collectd.statsd.vm_balloon_min` -|type: integer - -The `collectd` `balloon_min` type of `statsd` plug-in. - -| `collectd.statsd.vm_balloon_max` -|type: integer - -The `collectd` `balloon_max` type of `statsd` plug-in. - -| `collectd.statsd.vm_balloon_target` -|type: integer - -The `collectd` `balloon_target` type of `statsd` plug-in. - -| `collectd.statsd.vm_balloon_cur` -| type: integer - -The `collectd` `balloon_cur` type of `statsd` plug-in. - -| `collectd.statsd.vm_cpu_sys` -|type: integer - -The `collectd` `cpu_sys` type of `statsd` plug-in. - -| `collectd.statsd.vm_cpu_usage` -|type: integer - -The `collectd` `cpu_usage` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_read_ops` -|type: integer - -The `collectd` `disk_read_ops` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_write_ops` -|type: integer - -The `collectd` `disk_write_ops` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_flush_latency` -|type: integer - -The `collectd` `disk_flush_latency` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_apparent_size` -|type: integer - -The `collectd` `disk_apparent_size` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_write_bytes` -|type: integer - -The `collectd` `disk_write_bytes` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_write_rate` -|type: integer - -The `collectd` `disk_write_rate` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_true_size` -|type: integer - -The `collectd` `disk_true_size` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_read_rate` -|type: integer - -The `collectd` `disk_read_rate` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_write_latency` -|type: integer - -The `collectd` `disk_write_latency` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_read_latency` -|type: integer - -The `collectd` `disk_read_latency` type of `statsd` plug-in. - -| `collectd.statsd.vm_disk_read_bytes` -|type: integer - -The `collectd` `disk_read_bytes` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_rx_dropped` -|type: integer - -The `collectd` `nic_rx_dropped` type of `statsd` plug-in. - -| `collectd.statsd.vm_cpu_user` -|type: integer - -The `collectd` `cpu_user` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_rx_errors` -|type: integer - -The `collectd` `nic_rx_errors` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_tx_errors` -|type: integer - -The `collectd` `nic_tx_errors` type of `statsd` plug-in. - -| `collectd.statsd.vm_nic_speed` -|type: integer - -The `collectd` `nic_speed` type of `statsd` plug-in. -|=== - -[discrete] -[id="exported-fields-collectd.postgresql_{context}"] -=== `collectd.postgresql Fields` - -Corresponds to `collectd` `postgresql` plug-in. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `collectd.postgresql.pg_n_tup_g` -|type: integer - -The `collectd` type `pg_n_tup_g` of plug-in postgresql. - -| `collectd.postgresql.pg_n_tup_c` -|type: integer - -The `collectd` type `pg_n_tup_c` of plug-in postgresql. - -| `collectd.postgresql.pg_numbackends` -|type: integer - -The `collectd` type `pg_numbackends` of plug-in postgresql. - -| `collectd.postgresql.pg_xact` -|type: integer - -The `collectd` type `pg_xact` of plug-in postgresql. - -| `collectd.postgresql.pg_db_size` -|type: integer - -The `collectd` type `pg_db_size` of plug-in postgresql. - -| `collectd.postgresql.pg_blks` -|type: integer - -The `collectd` type `pg_blks` of plug-in postgresql. -|=== diff --git a/modules/cluster-logging-exported-fields-kubernetes.adoc b/modules/cluster-logging-exported-fields-kubernetes.adoc deleted file mode 100644 index fcb5db82fd47..000000000000 --- a/modules/cluster-logging-exported-fields-kubernetes.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-kubernetes_{context}"] -= Kubernetes exported fields - -These are the Kubernetes fields exported by OpenShift Logging available for searching -from Elasticsearch and Kibana. - -The namespace for Kubernetes-specific metadata. The `kubernetes.pod_name` is the -name of the pod. - -[discrete] -[id="exported-fields-kubernetes.labels_{context}"] -=== `kubernetes.labels` Fields - -Labels attached to the OpenShift object are `kubernetes.labels`. Each label name -is a subfield of labels field. Each label name is de-dotted, meaning dots in the -name are replaced with underscores. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `kubernetes.pod_id` -|Kubernetes ID of the pod. - -| `kubernetes.namespace_name` -|The name of the namespace in Kubernetes. - -| `kubernetes.namespace_id` -|ID of the namespace in Kubernetes. - -| `kubernetes.host` -|Kubernetes node name. - -| `kubernetes.container_name` -|The name of the container in Kubernetes. - -| `kubernetes.labels.deployment` -|The deployment associated with the Kubernetes object. - -| `kubernetes.labels.deploymentconfig` -|The deploymentconfig associated with the Kubernetes object. - -| `kubernetes.labels.component` -|The component associated with the Kubernetes object. - -| `kubernetes.labels.provider` -|The provider associated with the Kubernetes object. -|=== - -[discrete] -[id="exported-fields-kubernetes.annotations_{context}"] -=== `kubernetes.annotations` Fields - -Annotations associated with the OpenShift object are `kubernetes.annotations` -fields. diff --git a/modules/cluster-logging-exported-fields-ovirt.adoc b/modules/cluster-logging-exported-fields-ovirt.adoc deleted file mode 100644 index d05611540b7a..000000000000 --- a/modules/cluster-logging-exported-fields-ovirt.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-ovirt_{context}"] -= oVirt exported fields - -These are the oVirt fields exported by OpenShift Logging available for searching -from Elasticsearch and Kibana. - -Namespace for oVirt metadata. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `ovirt.entity` -|The type of the data source, hosts, VMS, and engine. - -| `ovirt.host_id` -|The oVirt host UUID. -|=== - -[discrete] -[id="exported-fields-ovirt.engine_{context}"] -=== `ovirt.engine` Fields - -Namespace for oVirt engine related metadata. The FQDN of the oVirt engine is -`ovirt.engine.fqdn` diff --git a/modules/cluster-logging-exported-fields-rsyslog.adoc b/modules/cluster-logging-exported-fields-rsyslog.adoc deleted file mode 100644 index fec43d97ad1a..000000000000 --- a/modules/cluster-logging-exported-fields-rsyslog.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-rsyslog_{context}"] -= `rsyslog` exported fields - -These are the `rsyslog` fields exported by the logging system and available for searching -from Elasticsearch and Kibana. - -The following fields are RFC5424 based metadata. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `rsyslog.facility` -|See `syslog` specification for more information on `rsyslog`. - -| `rsyslog.protocol-version` -|This is the `rsyslog` protocol version. - -| `rsyslog.structured-data` -|See `syslog` specification for more information on `syslog` structured-data. - -| `rsyslog.msgid` -|This is the `syslog` msgid field. - -| `rsyslog.appname` -|If `app-name` is the same as `programname`, then only fill top-level field `service`. -If `app-name` is not equal to `programname`, this field will hold `app-name`. -See syslog specifications for more information. -|=== diff --git a/modules/cluster-logging-exported-fields-systemd.adoc b/modules/cluster-logging-exported-fields-systemd.adoc deleted file mode 100644 index 4e74873b5f1d..000000000000 --- a/modules/cluster-logging-exported-fields-systemd.adoc +++ /dev/null @@ -1,195 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-systemd_{context}"] -= `systemd` exported fields - -These are the `systemd` fields exported by OpenShift Logging available for searching -from Elasticsearch and Kibana. - -Contains common fields specific to `systemd` journal. -link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html[Applications] -may write their own fields to the journal. These will be available under the -`systemd.u` namespace. `RESULT` and `UNIT` are two such fields. - -[discrete] -[id="exported-fields-systemd.k_{context}"] -=== `systemd.k` Fields - -The following table contains `systemd` kernel-specific metadata. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `systemd.k.KERNEL_DEVICE` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_KERNEL_DEVICE=[`systemd.k.KERNEL_DEVICE`] -is the kernel device name. - -| `systemd.k.KERNEL_SUBSYSTEM` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_KERNEL_SUBSYSTEM=[`systemd.k.KERNEL_SUBSYSTEM`] -is the kernel subsystem name. - -| `systemd.k.UDEV_DEVLINK` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_UDEV_DEVLINK=[`systemd.k.UDEV_DEVLINK`] -includes additional symlink names that point to the node. - -| `systemd.k.UDEV_DEVNODE` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_UDEV_DEVNODE=[`systemd.k.UDEV_DEVNODE`] -is the node path of the device. - -| `systemd.k.UDEV_SYSNAME` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_UDEV_SYSNAME=[ `systemd.k.UDEV_SYSNAME`] -is the kernel device name. - -|=== - -[discrete] -[id="exported-fields-systemd.t_{context}"] -=== `systemd.t` Fields - -`systemd.t Fields` are trusted journal fields, fields that are implicitly added -by the journal, and cannot be altered by client code. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `systemd.t.AUDIT_LOGINUID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_AUDIT_SESSION=[`systemd.t.AUDIT_LOGINUID`] -is the user ID for the journal entry process. - -| `systemd.t.BOOT_ID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_BOOT_ID=[`systemd.t.BOOT_ID`] -is the kernel boot ID. - -| `systemd.t.AUDIT_SESSION` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_AUDIT_SESSION=[`systemd.t.AUDIT_SESSION`] -is the session for the journal entry process. - -| `systemd.t.CAP_EFFECTIVE` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_CAP_EFFECTIVE=[`systemd.t.CAP_EFFECTIVE`] -represents the capabilities of the journal entry process. - -| `systemd.t.CMDLINE` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_COMM=[`systemd.t.CMDLINE`] -is the command line of the journal entry process. - -| `systemd.t.COMM` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_COMM=[`systemd.t.COMM`] -is the name of the journal entry process. - -| `systemd.t.EXE` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_COMM=[`systemd.t.EXE`] -is the executable path of the journal entry process. - -| `systemd.t.GID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_PID=[`systemd.t.GID`] -is the group ID for the journal entry process. - -| `systemd.t.HOSTNAME` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_HOSTNAME=[`systemd.t.HOSTNAME`] -is the name of the host. - -| `systemd.t.MACHINE_ID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_MACHINE_ID=[`systemd.t.MACHINE_ID`] -is the machine ID of the host. - -| `systemd.t.PID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_PID=[`systemd.t.PID`] -is the process ID for the journal entry process. - -| `systemd.t.SELINUX_CONTEXT` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SELINUX_CONTEXT=[`systemd.t.SELINUX_CONTEXT`] -is the security context, or label, for the journal entry process. - -| `systemd.t.SOURCE_REALTIME_TIMESTAMP` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SOURCE_REALTIME_TIMESTAMP=[`systemd.t.SOURCE_REALTIME_TIMESTAMP`] -is the earliest and most reliable timestamp of the message. This is converted to RFC 3339 NS format. - -| `systemd.t.SYSTEMD_CGROUP` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=[`systemd.t.SYSTEMD_CGROUP`] -is the `systemd` control group path. - -| `systemd.t.SYSTEMD_OWNER_UID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=[`systemd.t.SYSTEMD_OWNER_UID`] -is the owner ID of the session. - -| `systemd.t.SYSTEMD_SESSION` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=[`systemd.t.SYSTEMD_SESSION`], -if applicable, is the `systemd` session ID. - -| `systemd.t.SYSTEMD_SLICE` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=[`systemd.t.SYSTEMD_SLICE`] -is the slice unit of the journal entry process. - -| `systemd.t.SYSTEMD_UNIT` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=[`systemd.t.SYSTEMD_UNIT`] -is the unit name for a session. - -| `systemd.t.SYSTEMD_USER_UNIT` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_SYSTEMD_CGROUP=[`systemd.t.SYSTEMD_USER_UNIT`], -if applicable, is the user unit name for a session. - -| `systemd.t.TRANSPORT` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_TRANSPORT=[`systemd.t.TRANSPORT`] -is the method of entry by the journal service. This includes, `audit`, `driver`, -`syslog`, `journal`, `stdout`, and `kernel`. - -| `systemd.t.UID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#_PID=[`systemd.t.UID`] -is the user ID for the journal entry process. - -| `systemd.t.SYSLOG_FACILITY` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#SYSLOG_FACILITY=[`systemd.t.SYSLOG_FACILITY`] -is the field containing the facility, formatted as a decimal string, for `syslog`. - -| `systemd.t.SYSLOG_IDENTIFIER` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#SYSLOG_FACILITY=[`systemd.t.systemd.t.SYSLOG_IDENTIFIER`] -is the identifier for `syslog`. - -| `systemd.t.SYSLOG_PID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#SYSLOG_FACILITY=[`SYSLOG_PID`] -is the client process ID for `syslog`. -|=== - -[discrete] -[id="exported-fields-systemd.u_{context}"] -=== `systemd.u` Fields - -`systemd.u Fields` are directly passed from clients and stored in the journal. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `systemd.u.CODE_FILE` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=[`systemd.u.CODE_FILE`] -is the code location containing the filename of the source. - -| `systemd.u.CODE_FUNCTION` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=[`systemd.u.CODE_FUNCTION`] -is the code location containing the function of the source. - -| `systemd.u.CODE_LINE` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=[`systemd.u.CODE_LINE`] -is the code location containing the line number of the source. - -| `systemd.u.ERRNO` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=[`systemd.u.ERRNO`], -if present, is the low-level error number formatted in numeric value, as a decimal string. - -| `systemd.u.MESSAGE_ID` -|link:https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=[`systemd.u.MESSAGE_ID`] -is the message identifier ID for recognizing message types. - -| `systemd.u.RESULT` -|For private use only. - -| `systemd.u.UNIT` -|For private use only. -|=== diff --git a/modules/cluster-logging-exported-fields-tlog.adoc b/modules/cluster-logging-exported-fields-tlog.adoc deleted file mode 100644 index 82724afc1591..000000000000 --- a/modules/cluster-logging-exported-fields-tlog.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-exported-fields.adoc - -[id="cluster-logging-exported-fields-tlog_{context}"] -= Tlog exported fields - -These are the Tlog fields exported by the OpenShift Logging system and available for searching -from Elasticsearch and Kibana. - -Tlog terminal I/O recording messages. For more information see -link:https://github.com/Scribery/tlog[Tlog]. - -[cols="3,7",options="header"] -|=== -|Parameter -|Description - -| `tlog.ver` -|Message format version number. - -| `tlog.user` -|Recorded user name. - -| `tlog.term` -|Terminal type name. - -| `tlog.session` -|Audit session ID of the recorded session. - -| `tlog.id` -|ID of the message within the session. - -| `tlog.pos` -|Message position in the session, milliseconds. - -| `tlog.timing` -|Distribution of this message's events in time. - -| `tlog.in_txt` -|Input text with invalid characters scrubbed. - -| `tlog.in_bin` -|Scrubbed invalid input characters as bytes. - -| `tlog.out_txt` -|Output text with invalid characters scrubbed. - -| `tlog.out_bin` -|Scrubbed invalid output characters as bytes. -|=== diff --git a/modules/cluster-logging-forwarding-about.adoc b/modules/cluster-logging-forwarding-about.adoc deleted file mode 100644 index 628257362fc5..000000000000 --- a/modules/cluster-logging-forwarding-about.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging.adoc - -[id="cluster-logging-forwarding-about_{context}"] -= About log forwarding - -By default, OpenShift Logging sends logs to the default internal Elasticsearch log store, defined in the `ClusterLogging` custom resource (CR). If you want to forward logs to other log aggregators, you can use the log forwarding features to send logs to specific endpoints within or outside your cluster. - diff --git a/modules/cluster-logging-kibana-limits.adoc b/modules/cluster-logging-kibana-limits.adoc deleted file mode 100644 index 281a97b926f3..000000000000 --- a/modules/cluster-logging-kibana-limits.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-visualizer.adoc - -[id="cluster-logging-kibana-limits_{context}"] -= Configure the CPU and memory limits for the log visualizer - -You can adjust both the CPU and memory limits for the pod that hosts the log visualizer. - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc edit ClusterLogging instance ----- -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - -.... - -spec: - visualization: - type: "kibana" - kibana: - replicas: - resources: <1> - limits: - memory: 1Gi - requests: - cpu: 500m - memory: 1Gi - proxy: <2> - resources: - limits: - memory: 100Mi - requests: - cpu: 100m - memory: 100Mi - ----- -<1> Specify the CPU and memory limits to allocate for each node. -<2> Specify the CPU and memory limits to allocate to the Kibana proxy. diff --git a/modules/cluster-logging-kibana-scaling.adoc b/modules/cluster-logging-kibana-scaling.adoc deleted file mode 100644 index 042819a93b2c..000000000000 --- a/modules/cluster-logging-kibana-scaling.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-visualizer.adoc - -[id="cluster-logging-kibana-scaling_{context}"] -= Scaling redundancy for the log visualizer nodes - -You can scale the pod that hosts the log visualizer for redundancy. - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc edit ClusterLogging instance ----- -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - -.... - -spec: - visualization: - type: "kibana" - kibana: - replicas: 1 <1> ----- -<1> Specify the number of Kibana nodes. diff --git a/modules/cluster-logging-kibana-tolerations.adoc b/modules/cluster-logging-kibana-tolerations.adoc deleted file mode 100644 index b9cbb7c94010..000000000000 --- a/modules/cluster-logging-kibana-tolerations.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-visualizer.adoc - -[id="cluster-logging-kibana-tolerations_{context}"] -= Using tolerations to control the log visualizer pod placement - -You can control the node where the log visualizer pod runs and prevent -other workloads from using those nodes by using tolerations on the pods. - -You apply tolerations to the log visualizer pod through the `ClusterLogging` custom resource (CR) -and apply taints to a node through the node specification. A taint on a node is a `key:value pair` that -instructs the node to repel all pods that do not tolerate the taint. Using a specific `key:value` pair -that is not on other pods ensures only the Kibana pod can run on that node. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Use the following command to add a taint to a node where you want to schedule the log visualizer pod: -+ -[source,terminal] ----- -$ oc adm taint nodes =: ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm taint nodes node1 kibana=node:NoExecute ----- -+ -This example places a taint on `node1` that has key `kibana`, value `node`, and taint effect `NoExecute`. -You must use the `NoExecute` taint effect. `NoExecute` schedules only pods that match the taint and remove existing pods -that do not match. - -. Edit the `visualization` section of the `ClusterLogging` CR to configure a toleration for the Kibana pod: -+ -[source,yaml] ----- - visualization: - type: "kibana" - kibana: - tolerations: - - key: "kibana" <1> - operator: "Exists" <2> - effect: "NoExecute" <3> - tolerationSeconds: 6000 <4> ----- -<1> Specify the key that you added to the node. -<2> Specify the `Exists` operator to require the `key`/`value`/`effect` parameters to match. -<3> Specify the `NoExecute` effect. -<4> Optionally, specify the `tolerationSeconds` parameter to set how long a pod can remain bound to a node before being evicted. - - -This toleration matches the taint created by the `oc adm taint` command. A pod with this toleration would be able to schedule onto `node1`. diff --git a/modules/cluster-logging-log-store-status-comp.adoc b/modules/cluster-logging-log-store-status-comp.adoc deleted file mode 100644 index f9f96f74f824..000000000000 --- a/modules/cluster-logging-log-store-status-comp.adoc +++ /dev/null @@ -1,203 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-elasticsearch-status-comp_{context}"] -= Viewing the status of the log store components - -You can view the status for a number of the log store components. - -Elasticsearch indices:: -You can view the status of the Elasticsearch indices. - -. Get the name of an Elasticsearch pod: -+ -[source,terminal] ----- -$ oc get pods --selector component=elasticsearch -o name ----- -+ -.Example output -[source,terminal] ----- -pod/elasticsearch-cdm-1godmszn-1-6f8495-vp4lw -pod/elasticsearch-cdm-1godmszn-2-5769cf-9ms2n -pod/elasticsearch-cdm-1godmszn-3-f66f7d-zqkz7 ----- - -. Get the status of the indices: -+ -[source,terminal] ----- -$ oc exec elasticsearch-cdm-4vjor49p-2-6d4d7db474-q2w7z -- indices ----- -+ -.Example output -[source,terminal] ----- -Defaulting container name to elasticsearch. -Use 'oc describe pod/elasticsearch-cdm-4vjor49p-2-6d4d7db474-q2w7z -n openshift-logging' to see all of the containers in this pod. - -green open infra-000002 S4QANnf1QP6NgCegfnrnbQ 3 1 119926 0 157 78 -green open audit-000001 8_EQx77iQCSTzFOXtxRqFw 3 1 0 0 0 0 -green open .security iDjscH7aSUGhIdq0LheLBQ 1 1 5 0 0 0 -green open .kibana_-377444158_kubeadmin yBywZ9GfSrKebz5gWBZbjw 3 1 1 0 0 0 -green open infra-000001 z6Dpe__ORgiopEpW6Yl44A 3 1 871000 0 874 436 -green open app-000001 hIrazQCeSISewG3c2VIvsQ 3 1 2453 0 3 1 -green open .kibana_1 JCitcBMSQxKOvIq6iQW6wg 1 1 0 0 0 0 -green open .kibana_-1595131456_user1 gIYFIEGRRe-ka0W3okS-mQ 3 1 1 0 0 0 ----- - - -Log store pods:: -You can view the status of the pods that host the log store. - -. Get the name of a pod: -+ -[source,terminal] ----- -$ oc get pods --selector component=elasticsearch -o name ----- -+ -.Example output -[source,terminal] ----- -pod/elasticsearch-cdm-1godmszn-1-6f8495-vp4lw -pod/elasticsearch-cdm-1godmszn-2-5769cf-9ms2n -pod/elasticsearch-cdm-1godmszn-3-f66f7d-zqkz7 ----- - -. Get the status of a pod: -+ -[source,terminal] ----- -$ oc describe pod elasticsearch-cdm-1godmszn-1-6f8495-vp4lw ----- -+ -The output includes the following status information: -+ -.Example output -[source,terminal] ----- -.... -Status: Running - -.... - -Containers: - elasticsearch: - Container ID: cri-o://b7d44e0a9ea486e27f47763f5bb4c39dfd2 - State: Running - Started: Mon, 08 Jun 2020 10:17:56 -0400 - Ready: True - Restart Count: 0 - Readiness: exec [/usr/share/elasticsearch/probe/readiness.sh] delay=10s timeout=30s period=5s #success=1 #failure=3 - -.... - - proxy: - Container ID: cri-o://3f77032abaddbb1652c116278652908dc01860320b8a4e741d06894b2f8f9aa1 - State: Running - Started: Mon, 08 Jun 2020 10:18:38 -0400 - Ready: True - Restart Count: 0 - -.... - -Conditions: - Type Status - Initialized True - Ready True - ContainersReady True - PodScheduled True - -.... - -Events: ----- - -Log storage pod deployment configuration:: -You can view the status of the log store deployment configuration. - -. Get the name of a deployment configuration: -+ -[source,terminal] ----- -$ oc get deployment --selector component=elasticsearch -o name ----- -+ -.Example output -[source,terminal] ----- -deployment.extensions/elasticsearch-cdm-1gon-1 -deployment.extensions/elasticsearch-cdm-1gon-2 -deployment.extensions/elasticsearch-cdm-1gon-3 ----- - -. Get the deployment configuration status: -+ -[source,terminal] ----- -$ oc describe deployment elasticsearch-cdm-1gon-1 ----- -+ -The output includes the following status information: -+ -.Example output -[source,terminal] ----- -.... - Containers: - elasticsearch: - Image: registry.redhat.io/openshift-logging/elasticsearch6-rhel8 - Readiness: exec [/usr/share/elasticsearch/probe/readiness.sh] delay=10s timeout=30s period=5s #success=1 #failure=3 - -.... - -Conditions: - Type Status Reason - ---- ------ ------ - Progressing Unknown DeploymentPaused - Available True MinimumReplicasAvailable - -.... - -Events: ----- - -Log store replica set:: -You can view the status of the log store replica set. - -. Get the name of a replica set: -+ -[source,terminal] ----- -$ oc get replicaSet --selector component=elasticsearch -o name - -replicaset.extensions/elasticsearch-cdm-1gon-1-6f8495 -replicaset.extensions/elasticsearch-cdm-1gon-2-5769cf -replicaset.extensions/elasticsearch-cdm-1gon-3-f66f7d ----- - -. Get the status of the replica set: -+ -[source,terminal] ----- -$ oc describe replicaSet elasticsearch-cdm-1gon-1-6f8495 ----- -+ -The output includes the following status information: -+ -.Example output -[source,terminal] ----- -.... - Containers: - elasticsearch: - Image: registry.redhat.io/openshift-logging/elasticsearch6-rhel8@sha256:4265742c7cdd85359140e2d7d703e4311b6497eec7676957f455d6908e7b1c25 - Readiness: exec [/usr/share/elasticsearch/probe/readiness.sh] delay=10s timeout=30s period=5s #success=1 #failure=3 - -.... - -Events: ----- diff --git a/modules/cluster-logging-log-store-status-viewing.adoc b/modules/cluster-logging-log-store-status-viewing.adoc deleted file mode 100644 index 618f5d387c0d..000000000000 --- a/modules/cluster-logging-log-store-status-viewing.adoc +++ /dev/null @@ -1,219 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-log-store.adoc - -[id="cluster-logging-log-store-comp-viewing_{context}"] -= Viewing the status of the log store - -You can view the status of your log store. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Change to the `openshift-logging` project. -+ -[source,terminal] ----- -$ oc project openshift-logging ----- - -. To view the status: - -.. Get the name of the log store instance: -+ -[source,terminal] ----- -$ oc get Elasticsearch ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -elasticsearch 5h9m ----- - -.. Get the log store status: -+ -[source,terminal] ----- -$ oc get Elasticsearch -o yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get Elasticsearch elasticsearch -n openshift-logging -o yaml ----- -+ -The output includes information similar to the following: -+ -.Example output -[source,terminal] ----- -status: <1> - cluster: <2> - activePrimaryShards: 30 - activeShards: 60 - initializingShards: 0 - numDataNodes: 3 - numNodes: 3 - pendingTasks: 0 - relocatingShards: 0 - status: green - unassignedShards: 0 - clusterHealth: "" - conditions: [] <3> - nodes: <4> - - deploymentName: elasticsearch-cdm-zjf34ved-1 - upgradeStatus: {} - - deploymentName: elasticsearch-cdm-zjf34ved-2 - upgradeStatus: {} - - deploymentName: elasticsearch-cdm-zjf34ved-3 - upgradeStatus: {} - pods: <5> - client: - failed: [] - notReady: [] - ready: - - elasticsearch-cdm-zjf34ved-1-6d7fbf844f-sn422 - - elasticsearch-cdm-zjf34ved-2-dfbd988bc-qkzjz - - elasticsearch-cdm-zjf34ved-3-c8f566f7c-t7zkt - data: - failed: [] - notReady: [] - ready: - - elasticsearch-cdm-zjf34ved-1-6d7fbf844f-sn422 - - elasticsearch-cdm-zjf34ved-2-dfbd988bc-qkzjz - - elasticsearch-cdm-zjf34ved-3-c8f566f7c-t7zkt - master: - failed: [] - notReady: [] - ready: - - elasticsearch-cdm-zjf34ved-1-6d7fbf844f-sn422 - - elasticsearch-cdm-zjf34ved-2-dfbd988bc-qkzjz - - elasticsearch-cdm-zjf34ved-3-c8f566f7c-t7zkt - shardAllocationEnabled: all ----- -<1> In the output, the cluster status fields appear in the `status` stanza. -<2> The status of the log store: -+ -* The number of active primary shards. -* The number of active shards. -* The number of shards that are initializing. -* The number of log store data nodes. -* The total number of log store nodes. -* The number of pending tasks. -* The log store status: `green`, `red`, `yellow`. -* The number of unassigned shards. -<3> Any status conditions, if present. The log store status indicates the reasons from the scheduler if a pod could not be placed. Any events related to the following conditions are shown: -* Container Waiting for both the log store and proxy containers. -* Container Terminated for both the log store and proxy containers. -* Pod unschedulable. -Also, a condition is shown for a number of issues, see *Example condition messages*. -<4> The log store nodes in the cluster, with `upgradeStatus`. -<5> The log store client, data, and master pods in the cluster, listed under 'failed`, `notReady` or `ready` state. - -[id="cluster-logging-elasticsearch-status-message_{context}"] -== Example condition messages - -The following are examples of some condition messages from the `Status` section of the Elasticsearch instance. - -// https://github.com/openshift/elasticsearch-operator/pull/92 - -This status message indicates a node has exceeded the configured low watermark and no shard will be allocated to this node. - -[source,yaml] ----- -status: - nodes: - - conditions: - - lastTransitionTime: 2019-03-15T15:57:22Z - message: Disk storage usage for node is 27.5gb (36.74%). Shards will be not - be allocated on this node. - reason: Disk Watermark Low - status: "True" - type: NodeStorage - deploymentName: example-elasticsearch-cdm-0-1 - upgradeStatus: {} ----- - -This status message indicates a node has exceeded the configured high watermark and shards will be relocated to other nodes. - -[source,yaml] ----- -status: - nodes: - - conditions: - - lastTransitionTime: 2019-03-15T16:04:45Z - message: Disk storage usage for node is 27.5gb (36.74%). Shards will be relocated - from this node. - reason: Disk Watermark High - status: "True" - type: NodeStorage - deploymentName: example-elasticsearch-cdm-0-1 - upgradeStatus: {} ----- - -This status message indicates the log store node selector in the CR does not match any nodes in the cluster: - -[source,yaml] ----- -status: - nodes: - - conditions: - - lastTransitionTime: 2019-04-10T02:26:24Z - message: '0/8 nodes are available: 8 node(s) didn''t match node selector.' - reason: Unschedulable - status: "True" - type: Unschedulable ----- - -This status message indicates that the log store CR uses a non-existent PVC. - -[source,yaml] ----- -status: - nodes: - - conditions: - - last Transition Time: 2019-04-10T05:55:51Z - message: pod has unbound immediate PersistentVolumeClaims (repeated 5 times) - reason: Unschedulable - status: True - type: Unschedulable ----- - -This status message indicates that your log store cluster does not have enough nodes to support your log store redundancy policy. - -[source,yaml] ----- -status: - clusterHealth: "" - conditions: - - lastTransitionTime: 2019-04-17T20:01:31Z - message: Wrong RedundancyPolicy selected. Choose different RedundancyPolicy or - add more nodes with data roles - reason: Invalid Settings - status: "True" - type: InvalidRedundancy ----- - -This status message indicates your cluster has too many master nodes: - -[source,yaml] ----- -status: - clusterHealth: green - conditions: - - lastTransitionTime: '2019-04-17T20:12:34Z' - message: >- - Invalid master nodes count. Please ensure there are no more than 3 total - nodes with master roles - reason: Invalid Settings - status: 'True' - type: InvalidMasters ----- diff --git a/modules/cluster-logging-logstore-limits.adoc b/modules/cluster-logging-logstore-limits.adoc deleted file mode 100644 index e99ad6c29100..000000000000 --- a/modules/cluster-logging-logstore-limits.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-elasticsearch.adoc - -[id="cluster-logging-logstore-limits_{context}"] -= Configuring CPU and memory requests for the log store - -Each component specification allows for adjustments to both the CPU and memory requests. -You should not have to manually adjust these values as the OpenShift Elasticsearch -Operator sets values sufficient for your environment. - -[NOTE] -==== -In large-scale clusters, the default memory limit for the Elasticsearch proxy container might not be sufficient, causing the proxy container to be OOMKilled. If you experience this issue, increase the memory requests and limits for the Elasticsearch proxy. -==== - -Each Elasticsearch node can operate with a lower memory setting though this is *not* recommended for production deployments. -For production use, you should have no less than the default 16Gi allocated to each pod. Preferably you should allocate as much as possible, up to 64Gi per pod. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc edit ClusterLogging instance ----- -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" -.... -spec: - logStore: - type: "elasticsearch" - elasticsearch: - resources: <1> - requests: - cpu: "1" - memory: "64Gi" - proxy: <2> - resources: - limits: - memory: 100Mi - requests: - memory: 100Mi ----- -<1> Specify the CPU and memory requests for Elasticsearch as needed. If you leave these values blank, -the OpenShift Elasticsearch Operator sets default values that should be sufficient for most deployments. The default values are `16Gi` for the memory request and `1` for the CPU request. -<2> Specify the CPU and memory requests for the Elasticsearch proxy as needed. If you leave these values blank, the OpenShift Elasticsearch Operator sets default values that should be sufficient for most deployments. The default values are `256Mi` for the memory request and `100m` for the CPU request. - -If you adjust the amount of Elasticsearch memory, you must change both the request value and the limit value. - -For example: - -[source,yaml] ----- - resources: - limits: - memory: "32Gi" - requests: - cpu: "8" - memory: "32Gi" ----- - -Kubernetes generally adheres the node configuration and does not allow Elasticsearch to use the specified limits. -Setting the same value for the `requests` and `limits` ensures that Elasticsearch can use the memory you want, assuming the node has the memory available. diff --git a/modules/cluster-logging-maintenance-support-about.adoc b/modules/cluster-logging-maintenance-support-about.adoc deleted file mode 100644 index 6d8b600cc70a..000000000000 --- a/modules/cluster-logging-maintenance-support-about.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/config/cluster-logging-maintenance-support.adoc - -[id="cluster-logging-maintenance-support-about_{context}"] -= About unsupported configurations - -The supported way of configuring OpenShift Logging is by configuring it using the options described in this documentation. Do not use other configurations, as they are unsupported. Configuration paradigms might change across {product-title} releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use configurations other than those described in this documentation, your changes will disappear because the OpenShift Elasticsearch Operator and Cluster Logging Operator reconcile any differences. The Operators reverse everything to the defined state by default and by design. - -[NOTE] -==== -If you _must_ perform configurations not described in the {product-title} documentation, you _must_ set your Cluster Logging Operator or OpenShift Elasticsearch Operator to *Unmanaged*. An unmanaged OpenShift Logging environment is _not supported_ and does not receive updates until you return OpenShift Logging to *Managed*. -==== diff --git a/modules/cluster-logging-maintenance-support-list.adoc b/modules/cluster-logging-maintenance-support-list.adoc deleted file mode 100644 index 4b8b852d012c..000000000000 --- a/modules/cluster-logging-maintenance-support-list.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/config/cluster-logging-maintenance-support.adoc - -[id="cluster-logging-maintenance-support-list_{context}"] -= Unsupported configurations - -You must set the Cluster Logging Operator to the unmanaged state to modify the following components: - -* the Curator cron job - -* the `Elasticsearch` CR - -* the Kibana deployment - -* the `fluent.conf` file - -* the Fluentd daemon set - -You must set the OpenShift Elasticsearch Operator to the unmanaged state to modify the following component: - -* the Elasticsearch deployment files. - -Explicitly unsupported cases include: - -* *Configuring default log rotation*. You cannot modify the default log rotation configuration. - -* *Configuring the collected log location*. You cannot change the location of the log collector output file, which by default is `/var/log/fluentd/fluentd.log`. - -* *Throttling log collection*. You cannot throttle down the rate at which the logs are read in by the log collector. - -* *Configuring log collection JSON parsing*. You cannot format log messages in JSON. - -* *Configuring the logging collector using environment variables*. You cannot use environment variables to modify the log collector. - -* *Configuring how the log collector normalizes logs*. You cannot modify default log normalization. - -* *Configuring Curator in scripted deployments*. You cannot configure log curation in scripted deployments. - -* *Using the Curator Action file*. You cannot use the Curator config map to modify the Curator action file. - diff --git a/modules/cluster-logging-manual-rollout-rolling.adoc b/modules/cluster-logging-manual-rollout-rolling.adoc deleted file mode 100644 index 82ba217a2a07..000000000000 --- a/modules/cluster-logging-manual-rollout-rolling.adoc +++ /dev/null @@ -1,210 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/config/cluster-logging-log-store.adoc - -[id="cluster-logging-manual-rollout-rolling_{context}"] -= Performing an Elasticsearch rolling cluster restart - -Perform a rolling restart when you change the `elasticsearch` config map -or any of the `elasticsearch-*` deployment configurations. - -Also, a rolling restart is recommended if the nodes on which an Elasticsearch pod -runs requires a reboot. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -* Install the {product-title} link:https://github.com/openshift/origin-aggregated-logging/tree/master/elasticsearch#es_util[*es_util*] tool - -.Procedure - -To perform a rolling cluster restart: - -. Change to the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc project openshift-logging ----- - -. Get the names of the Elasticsearch pods: -+ ----- -$ oc get pods | grep elasticsearch- ----- - -. Perform a shard synced flush using the {product-title} link:https://github.com/openshift/origin-aggregated-logging/tree/master/elasticsearch#es_util[*es_util*] tool to ensure there are no pending operations waiting to be written to disk prior to shutting down: -+ -[source,terminal] ----- -$ oc exec -c elasticsearch -- es_util --query="_flush/synced" -XPOST ----- -+ -For example: -+ -[source,terminal] ----- -$ oc exec -c elasticsearch-cdm-5ceex6ts-1-dcd6c4c7c-jpw6 -c elasticsearch -- es_util --query="_flush/synced" -XPOST ----- -+ -.Example output -[source,terminal] ----- -{"_shards":{"total":4,"successful":4,"failed":0},".security":{"total":2,"successful":2,"failed":0},".kibana_1":{"total":2,"successful":2,"failed":0}} ----- - -. Prevent shard balancing when purposely bringing down nodes using the {product-title} -link:https://github.com/openshift/origin-aggregated-logging/tree/master/elasticsearch#es_util[*es_util*] tool: -+ -[source,terminal] ----- -$ oc exec -c elasticsearch -- es_util --query="_cluster/settings" -XPUT -d '{ "persistent": { "cluster.routing.allocation.enable" : "primaries" } }' ----- -+ -For example: -+ -[source,terminal] ----- -$ oc exec elasticsearch-cdm-5ceex6ts-1-dcd6c4c7c-jpw6 -c elasticsearch -- es_util --query="_cluster/settings" -XPUT -d '{ "persistent": { "cluster.routing.allocation.enable" : "primaries" } }' ----- -+ -.Example output -[source,terminal] ----- -{"acknowledged":true,"persistent":{"cluster":{"routing":{"allocation":{"enable":"primaries"}}}},"transient": ----- - -. After the command is complete, for each deployment you have for an ES cluster: - -.. By default, the {product-title} Elasticsearch cluster blocks rollouts to their nodes. Use the following command to allow rollouts -and allow the pod to pick up the changes: -+ -[source,terminal] ----- -$ oc rollout resume deployment/ ----- -+ -For example: -+ -[source,terminal] ----- -$ oc rollout resume deployment/elasticsearch-cdm-0-1 ----- -+ -[source,terminal] ----- -deployment.extensions/elasticsearch-cdm-0-1 resumed ----- -+ -A new pod is deployed. After the pod has a ready container, you can -move on to the next deployment. -+ -[source,terminal] ----- -$ oc get pods | grep elasticsearch- ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -elasticsearch-cdm-5ceex6ts-1-dcd6c4c7c-jpw6k 2/2 Running 0 22h -elasticsearch-cdm-5ceex6ts-2-f799564cb-l9mj7 2/2 Running 0 22h -elasticsearch-cdm-5ceex6ts-3-585968dc68-k7kjr 2/2 Running 0 22h ----- - -.. After the deployments are complete, reset the pod to disallow rollouts: -+ -[source,terminal] ----- -$ oc rollout pause deployment/ ----- -+ -For example: -+ -[source,terminal] ----- -$ oc rollout pause deployment/elasticsearch-cdm-0-1 ----- -+ -[source,terminal] ----- -deployment.extensions/elasticsearch-cdm-0-1 paused ----- -+ -.. Check that the Elasticsearch cluster is in a `green` or `yellow` state: -+ -[source,terminal] ----- -$ oc exec -c elasticsearch -- es_util --query=_cluster/health?pretty=true ----- -+ -[NOTE] -==== -If you performed a rollout on the Elasticsearch pod you used in the previous commands, the pod no longer exists and you need a new pod name here. -==== -+ -For example: -+ -[source,terminal] ----- -$ oc exec elasticsearch-cdm-5ceex6ts-1-dcd6c4c7c-jpw6 -c elasticsearch -- es_util --query=_cluster/health?pretty=true ----- -+ -.Example output -[source,json] ----- -{ - "cluster_name" : "elasticsearch", - "status" : "yellow", <1> - "timed_out" : false, - "number_of_nodes" : 3, - "number_of_data_nodes" : 3, - "active_primary_shards" : 8, - "active_shards" : 16, - "relocating_shards" : 0, - "initializing_shards" : 0, - "unassigned_shards" : 1, - "delayed_unassigned_shards" : 0, - "number_of_pending_tasks" : 0, - "number_of_in_flight_fetch" : 0, - "task_max_waiting_in_queue_millis" : 0, - "active_shards_percent_as_number" : 100.0 -} ----- -<1> Make sure this parameter value is `green` or `yellow` before proceeding. - -. If you changed the Elasticsearch configuration map, repeat these steps for each Elasticsearch pod. - -. After all the deployments for the cluster have been rolled out, re-enable shard balancing: -+ -[source,terminal] ----- -$ oc exec -c elasticsearch -- es_util --query="_cluster/settings" -XPUT -d '{ "persistent": { "cluster.routing.allocation.enable" : "all" } }' ----- -+ -For example: -+ -[source,terminal] ----- -$ oc exec elasticsearch-cdm-5ceex6ts-1-dcd6c4c7c-jpw6 -c elasticsearch -- es_util --query="_cluster/settings" -XPUT -d '{ "persistent": { "cluster.routing.allocation.enable" : "all" } }' ----- -+ -.Example output -[source,terminal] ----- -{ - "acknowledged" : true, - "persistent" : { }, - "transient" : { - "cluster" : { - "routing" : { - "allocation" : { - "enable" : "all" - } - } - } - } -} ----- diff --git a/modules/cluster-logging-must-gather-about.adoc b/modules/cluster-logging-must-gather-about.adoc deleted file mode 100644 index 4ab38170a3ca..000000000000 --- a/modules/cluster-logging-must-gather-about.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/troubleshooting/cluster-logging-must-gather.adoc - -[id="about-must-gather_{context}"] -= About the must-gather tool - -The `oc adm must-gather` CLI command collects the information from your cluster that is most likely needed for debugging issues. - -For your OpenShift Logging environment, `must-gather` collects the following information: - -* project-level resources, including pods, configuration maps, service accounts, roles, role bindings, and events at the project level -* cluster-level resources, including nodes, roles, and role bindings at the cluster level -* OpenShift Logging resources in the `openshift-logging` and `openshift-operators-redhat` namespaces, including health status for the log collector, the log store, the curator, and the log visualizer - -When you run `oc adm must-gather`, a new pod is created on the cluster. The data is collected on that pod and saved in a new directory that starts with `must-gather.local`. This directory is created in the current working directory. - - - diff --git a/modules/cluster-logging-must-gather-collecting.adoc b/modules/cluster-logging-must-gather-collecting.adoc deleted file mode 100644 index 0ba6694bd737..000000000000 --- a/modules/cluster-logging-must-gather-collecting.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/troubleshooting/cluster-logging-must-gather.adoc - -[id="cluster-logging-must-gather-collecting_{context}"] -= Collecting OpenShift Logging data - -You can use the `oc adm must-gather` CLI command to collect information about your OpenShift Logging environment. - -.Procedure - -To collect OpenShift Logging information with `must-gather`: - -. Navigate to the directory where you want to store the `must-gather` information. - -. Run the `oc adm must-gather` command against the OpenShift Logging image: -+ -ifndef::openshift-origin[] -[source,terminal] ----- -$ oc adm must-gather --image=$(oc -n openshift-logging get deployment.apps/cluster-logging-operator -o jsonpath='{.spec.template.spec.containers[?(@.name == "cluster-logging-operator")].image}') ----- -endif::openshift-origin[] -ifdef::openshift-origin[] -[source,terminal] ----- -$ oc adm must-gather --image=quay.io/openshift/origin-cluster-logging-operator ----- -endif::openshift-origin[] -+ -The `must-gather` tool creates a new directory that starts with `must-gather.local` within the current directory. For example: -`must-gather.local.4157245944708210408`. - -. Create a compressed file from the `must-gather` directory that was just created. For example, on a computer that uses a Linux operating system, run the following command: -+ -[source,terminal] ----- -$ tar -cvaf must-gather.tar.gz must-gather.local.4157245944708210408 ----- - -. Attach the compressed file to your support case on the link:https://access.redhat.com/[Red Hat Customer Portal]. diff --git a/modules/cluster-logging-release-notes-5.0.0.adoc b/modules/cluster-logging-release-notes-5.0.0.adoc deleted file mode 100644 index c29c8841a405..000000000000 --- a/modules/cluster-logging-release-notes-5.0.0.adoc +++ /dev/null @@ -1,227 +0,0 @@ -[id="cluster-logging-release-notes-5-0-0"] -= OpenShift Logging 5.0.0 - -This release includes Red Hat Bug Advisory, link:https://access.redhat.com/errata/RHBA-2021:0652[RHBA-2021:0652 Errata Advisory for Openshift Logging 5.0.0]. - -[id="openshift-logging-5-0-new-features-and-enhancements"] -== New features and enhancements - -This release adds improvements related to the following concepts. - -[discrete] -[id="ocp-4-7-cluster-logging-renamed-openshift-logging"] -=== Cluster Logging becomes Red Hat OpenShift Logging - -With this release, Cluster Logging becomes Red Hat OpenShift Logging, version 5.0. - -[discrete] -[id="openshift-logging-5-0-eo-max-five-shards"] -// https://bugzilla.redhat.com/show_bug.cgi?id=1883444 -=== Maximum five primary shards per index - -With this release, the OpenShift Elasticsearch Operator (EO) sets the number of primary shards for an index between one and five, depending on the number of data nodes defined for a cluster. - -Previously, the EO set the number of shards for an index to the number of data nodes. When an index in Elasticsearch was configured with a number of replicas, it created that many replicas for each primary shard, not per index. Therefore, as the index sharded, a greater number of replica shards existed in the cluster, which created a lot of overhead for the cluster to replicate and keep in sync. - -[discrete] -[id="openshift-logging-5-0-updated-eo-name"] -// https://bugzilla.redhat.com/show_bug.cgi?id=1898920 -=== Updated OpenShift Elasticsearch Operator name and maturity level - -This release updates the display name of the OpenShift Elasticsearch Operator and operator maturity level. The new display name and clarified specific use for the OpenShift Elasticsearch Operator are updated in Operator Hub. - -[discrete] -[id="openshift-logging-5-0-es-csv-success"] -// https://bugzilla.redhat.com/show_bug.cgi?id=1913464 -=== OpenShift Elasticsearch Operator reports on CSV success - -This release adds reporting metrics to indicate that installing or upgrading the `ClusterServiceVersion` (CSV) object for the OpenShift Elasticsearch Operator was successful. Previously, there was no way to determine, or generate an alert, if the installing or upgrading the CSV failed. Now, an alert is provided as part of the OpenShift Elasticsearch Operator. - -[discrete] -[id="openshift-logging-5-0-reduced-cert-warnings"] -// https://bugzilla.redhat.com/show_bug.cgi?id=1884812 -=== Reduce Elasticsearch pod certificate permission warnings - -Previously, when the Elasticsearch pod started, it generated certificate permission warnings, which misled some users to troubleshoot their clusters. The current release fixes these permissions issues to reduce these types of notifications. - -[discrete] -[id="openshift-logging-5-0-links-from-alerts"] -// https://bugzilla.redhat.com/show_bug.cgi?id=1913469 -=== New links from alerts to explanations and troubleshooting - -This release adds a link from the alerts that an Elasticsearch cluster generates to a page of explanations and troubleshooting steps for that alert. - -[discrete] -[id="openshift-logging-5-0-curl-connection-timeout"] -// https://bugzilla.redhat.com/show_bug.cgi?id=1881709 -=== New connection timeout for deletion jobs - -The current release adds a connection timeout for deletion jobs, which helps prevent pods from occasionally hanging when they query Elasticsearch to delete indices. Now, if the underlying 'curl' call does not connect before the timeout period elapses, the timeout terminates the call. - -[discrete] -[id="openshift-logging-5-0-minimize-updates-to-rollover-index-templates"] -// https://bugzilla.redhat.com/show_bug.cgi?id=1920215 -=== Minimize updates to rollover index templates - -With this enhancement, the OpenShift Elasticsearch Operator only updates its rollover index templates if they have different field values. Index templates have a higher priority than indices. When the template is updated, the cluster prioritizes distributing them over the index shards, impacting performance. To minimize Elasticsearch cluster operations, the operator only updates the templates when the number of primary shards or replica shards changes from what is currently configured. - -[id="openshift-logging-5-0-technology-preview"] -== Technology Preview features - -Some features in this release are currently in Technology Preview. These experimental features are not intended for production use. Note the following scope of support on the Red Hat Customer Portal for these features: - -link:https://access.redhat.com/support/offerings/techpreview[Technology Preview Features Support Scope] - -In the table below, features are marked with the following statuses: - -* *TP*: _Technology Preview_ -* *GA*: _General Availability_ -* *-*: _Not Available_ - -.Technology Preview tracker -[cols="4,1,1,1",options="header"] -|==== -|Feature |OCP 4.5 |OCP 4.6 |Logging 5.0 - -|Log forwarding -|TP -|GA -|GA - -|==== - -// UNUSED BOILERPLATE -// [id="openshift-logging-5-0-notable-technical-changes"] -// == Notable technical changes -// -// {ProductName} 5.0 introduces the following notable technical changes. -// -// [id="openshift-logging-5-0-deprecated-removed-features"] -// == Deprecated and removed features -// -// Some features available in previous releases have been deprecated or removed. -// -// Deprecated functionality is still included in {ProductName} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. For the most recent list of major functionality deprecated and removed within {ProductName} {product-version}, refer to the table below. Additional details for more fine-grained functionality that has been deprecated and removed are listed after the table. -// -// In the table, features are marked with the following statuses: -// -// * *GA*: _General Availability_ -// * *DEP*: _Deprecated_ -// * *REM*: _Removed_ -// -// .Deprecated and removed features tracker -// [cols="3,1,1,1",options="header"] -// |==== -// |Feature |OCP 4.5 |OCP 4.6 |OCP 4.7 -// -// |`OperatorSource` objects -// |DEP -// |REM -// |REM -// |==== -// -// [id="openshift-logging-5-0-deprecated-features"] -// === Deprecated features -// -// [id="openshift-logging-5-0-removed-features"] -// === Removed features - -[id="openshift-logging-5-0-bug-fixes"] -== Bug fixes - -* Previously, Elasticsearch rejected HTTP requests whose headers exceeded the default max header size, 8 KB. Now, the max header size is 128 KB, and Elasticsearch no longer rejects HTTP requests for exceeding the max header size. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1845293[*BZ#1845293*]) - -* Previously, nodes did not recover from `Pending` status because a software bug did not correctly update their statuses in the Elasticsearch custom resource (CR). The current release fixes this issue, so the nodes can recover when their status is `Pending.` (link:https://bugzilla.redhat.com/show_bug.cgi?id=1887357[*BZ#1887357*]) - -* Previously, when the Cluster Logging Operator (CLO) scaled down the number of Elasticsearch nodes in the `clusterlogging` CR to three nodes, it omitted previously-created nodes that had unique IDs. The OpenShift Elasticsearch Operator rejected the update because it has safeguards that prevent nodes with unique IDs from being removed. Now, when the CLO scales down the number of nodes and updates the Elasticsearch CR, it marks nodes with unique IDs as count 0 instead of omitting them. As a result, users can scale down their cluster to 3 nodes by using the `clusterlogging` CR. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1879150[*BZ#1879150*]) - -* Previously, the Fluentd collector pod went into a crash loop when the `ClusterLogForwarder` had an incorrectly-configured secret. The current release fixes this issue. Now, the `ClusterLogForwarder` validates the secrets and reports any errors in its status field. As a result, it does not cause the Fluentd collector pod to crash. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1888943[*1888943*]) - -* Previously, if you updated the Kibana resource configuration in the `clusterlogging` instance to `resource{}`, the resulting nil map caused a panic and changed the status of the OpenShift Elasticsearch Operator to `CrashLoopBackOff`. The current release fixes this issue by initializing the map. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1889573[*BZ#1889573*]) - -* Previously, the fluentd collector pod went into a crash loop when the ClusterLogForwarder had multiple outputs using the same secret. The current release fixes this issue. Now, multiple outputs can share a secret. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1890072[*1890072*]) - -* Previously, if you deleted a Kibana route, the Cluster Logging Operator (CLO) could not recover or recreate it. Now, the CLO watches the route, and if you delete the route, the OpenShift Elasticsearch Operator can reconcile or recreate it. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1890825[*BZ#1890825*]) - -* Previously, the Cluster Logging Operator (CLO) would attempt to reconcile the Elasticsearch resource, which depended upon the Red Hat-provided Elastic Custom Resource Definition (CRD). Attempts to list an unknown kind caused the CLO to exit its reconciliation loop. This happened because the CLO tried to reconcile all of its managed resources whether they were defined or not. The current release fixes this issue. The CLO only reconciles types provided by the OpenShift Elasticsearch Operator if a user defines managed storage. As a result, users can create collector-only deployments of cluster logging by deploying the CLO. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1891738[*BZ#1891738*]) - -* Previously, because of an LF GA syslog implementation for RFC 3164, logs sent to remote syslog were not compatible with the legacy behavior. The current release fixes this issue. AddLogSource adds details about log's source details to the "message" field. Now, logs sent to remote syslog are compatible with the legacy behavior. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1891886[*BZ#1891886*]) - -* Previously, the Elasticsearch rollover pods failed with a `resource_already_exists_exception` error. Within the Elasticsearch rollover API, when the next index was created, the `*-write` alias was not updated to point to it. As a result, the next time the rollover API endpoint was triggered for that particular index, it received an error that the resource already existed. -+ -The current release fixes this issue. Now, when a rollover occurs in the `indexmanagement` cronjobs, if a new index was created, it verifies that the alias points to the new index. This behavior prevents the error. If the cluster is already receiving this error, a cronjob fixes the issue so that subsequent runs work as expected. Now, performing rollovers no longer produces the exception. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1893992[*BZ#1893992*]) - -* Previously, Fluent stopped sending logs even though the logging stack seemed functional. Logs were not shipped to an endpoint for an extended period even when an endpoint came back up. This happened if the max backoff time was too long and the endpoint was down. The current release fixes this issue by lowering the max backoff time, so the logs are shipped sooner. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1894634[*BZ#1894634*]) - -* Previously, omitting the Storage size of the Elasticsearch node caused panic in the OpenShift Elasticsearch Operator code. This panic appeared in the logs as: `Observed a panic: "invalid memory address or nil pointer dereference"` The panic happened because although Storage size is a required field, the software didn't check for it. The current release fixes this issue, so there is no panic if the storage size is omitted. Instead, the storage defaults to ephemeral storage and generates a log message for the user. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1899589[*BZ#1899589*]) - -* Previously, `elasticsearch-rollover` and `elasticsearch-delete` pods remained in the `Invalid JSON:` or `ValueError: No JSON object could be decoded` error states. This exception was raised because there was no exception handler for invalid JSON input. The current release fixes this issue by providing a handler for invalid JSON input. As a result, the handler outputs an error message instead of an exception traceback, and the `elasticsearch-rollover` and `elasticsearch-delete` jobs do not remain those error states. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1899905[*BZ#1899905*]) - -* Previously, when deploying Fluentd as a stand-alone, a Kibana pod was created even if the value of `replicas` was `0`. This happened because Kibana defaulted to `1` pod even when there were no Elasticsearch nodes. The current release fixes this. Now, a Kibana only defaults to `1` when there are one or more Elasticsearch nodes. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1901424[*BZ#1901424*]) - -* Previously, if you deleted the secret, it was not recreated. Even though the certificates were on a disk local to the operator, they weren't rewritten because they hadn't changed. That is, certificates were only written if they changed. The current release fixes this issue. It rewrites the secret if the certificate changes or is not found. Now, if you delete the master-certs, they are replaced. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1901869[*BZ#1901869*]) - -* Previously, if a cluster had multiple custom resources with the same name, the resource would get selected alphabetically when not fully qualified with the API group. As a result, if you installed both Red Hat’s OpenShift Elasticsearch Operator alongside the OpenShift Elasticsearch Operator, you would see failures when collected data via a must-gather report. The current release fixes this issue by ensuring must-gathers now use the full API group when gathering information about the cluster's custom resources. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1897731[*BZ#1897731*]) - -* An earlier bug fix to address issues related to certificate generation introduced an error. Trying to read the certificates caused them to be regenerated because they were recognized as missing. This, in turn, triggered the OpenShift Elasticsearch Operator to perform a rolling upgrade on the Elasticsearch cluster and, potentially, to have mismatched certificates. This bug was caused by the operator incorrectly writing certificates to the working directory. The current release fixes this issue. Now the operator consistently reads and writes certificates to the same working directory, and the certificates are only regenerated if needed. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1905910[*BZ#1905910*]) - -* Previously, queries to the root endpoint to retrieve the Elasticsearch version received a 403 response. The 403 response broke any services that used this endpoint in prior releases. This error happened because non-administrative users did not have the `monitor` permission required to query the root endpoint and retrieve the Elasticsearch version. Now, non-administrative users can query the root endpoint for the deployed version of Elasticsearch. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1906765[*BZ#1906765*]) - -* Previously, in some bulk insertion situations, the Elasticsearch proxy timed out connections between fluentd and Elasticsearch. As a result, fluentd failed to deliver messages and logged a `Server returned nothing (no headers, no data)` error. The current release fixes this issue: It increases the default HTTP read and write timeouts in the Elasticsearch proxy from five seconds to one minute. It also provides command-line options in the Elasticsearch proxy to control HTTP timeouts in the field. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1908707[*BZ#1908707*]) - -* Previously, in some cases, the {ProductName}/Elasticsearch dashboard was missing from the {product-title} monitoring dashboard because the dashboard configuration resource referred to a different namespace owner and caused the {product-title} to garbage-collect that resource. Now, the ownership reference is removed from the OpenShift Elasticsearch Operator reconciler configuration, and the logging dashboard appears in the console. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1910259[*BZ#1910259*]) - -* Previously, the code that uses environment variables to replace values in the Kibana configuration file did not consider commented lines. This prevented users from overriding the default value of server.maxPayloadBytes. The current release fixes this issue by uncommenting the default value of server.maxPayloadByteswithin. Now, users can override the value by using environment variables, as documented. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1918876[*BZ#1918876*]) - -* Previously, the Kibana log level was increased not to suppress instructions to delete indices that failed to migrate, which also caused the display of GET requests at the INFO level that contained the Kibana user's email address and OAuth token. The current release fixes this issue by masking these fields, so the Kibana logs do not display them. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1925081[*BZ#1925081*]) - - -[id="openshift-logging-5-0-known-issues"] -== Known issues - -* Fluentd pods with the `ruby-kafka-1.1.0` and `fluent-plugin-kafka-0.13.1` gems are not compatible with Apache Kafka version 0.10.1.0. -+ -As a result, log forwarding to Kafka fails with a message: `error_class=Kafka::DeliveryFailed error="Failed to send messages to flux-openshift-v4/1"` -+ -The `ruby-kafka-0.7` gem dropped support for Kafka 0.10 in favor of native support for Kafka 0.11. The `ruby-kafka-1.0.0` gem added support for Kafka 2.3 and 2.4. The current version of OpenShift Logging tests and therefore supports Kafka version 2.4.1. -+ -To work around this issue, upgrade to a supported version of Apache Kafka. -+ -(link:https://bugzilla.redhat.com/show_bug.cgi?id=1907370[*BZ#1907370*]) - -// UNUSED BOILERPLATE -// [id="openshift-logging-5-0-asynchronous-errata-updates"] -// == Asynchronous errata updates -// -// Security, bug fix, and enhancement updates for {ProductName} 5.0 are released as asynchronous errata through the Red Hat Network. All {ProductName} 5.0 errata are https://access.redhat.com/downloads/[available on the Red Hat Customer Portal]. See the https://access.redhat.com/support/policy/updates/openshift#logging[{ProductName} Life Cycle] for more information about asynchronous errata. -// // TBD Update https://access.redhat.com/downloads/ to something like https://access.redhat.com/downloads/content/201/ once the Logging product has been released. -// -// Red Hat Customer Portal users can enable errata notifications in the account settings for Red Hat Subscription Management (RHSM). When errata notifications are enabled, users are notified via email whenever new errata relevant to their registered systems are released. -// -// [NOTE] -// ==== -// Red Hat Customer Portal user accounts must have systems registered and consuming {ProductName} entitlements for {ProductName} errata notification emails to generate. -// ==== -// -// This section will continue to be updated over time to provide notes on enhancements and bug fixes for future asynchronous errata releases of {ProductName} 5.0. Versioned asynchronous releases, for example with the form {ProductName} 5.0.z, will be detailed in subsections. In addition, releases in which the errata text cannot fit in the space provided by the advisory will be detailed in subsections that follow. -// -// [IMPORTANT] -// ==== -// For any {ProductName} release, always review the instructions on xref:../updating/updating-cluster.adoc#TBD[updating your cluster] properly. -// ==== -// -// [id="openshift-logging-5-0-0-ga"] -// === RHBA-2020:66974-04 Errata Advisory for Openshift Logging 5.0.0 -// -// (link:https://errata.devel.redhat.com/docs/show/66974[RHBA-2020:66974-04 Errata Advisory for Openshift Logging 5.0.0]) is now available. New features, changes, -// -// Issued: 2021-02-24 -// -// {ProductName} release 5.0 is now available. The list of bug fixes that are included in the update is documented in the link:https://errata.devel.redhat.com/docs/show/66974[RHBA-2020:66974-04] advisory. - -// UNUSED BOILERPLATE -// The RPM packages that are included in the update are provided by the link:https://access.redhat.com/errata/RHBA-2020:5678[RHBA-2020:5678] advisory. -// -// Space precluded documenting all of the container images for this release in the advisory. See the following article for notes on the container images in this release: -// -// link:https://access.redhat.com/solutions/[{ProductName} 5.0.0 container image list] diff --git a/modules/cluster-logging-release-notes-5.0.1.adoc b/modules/cluster-logging-release-notes-5.0.1.adoc deleted file mode 100644 index d622b6904f75..000000000000 --- a/modules/cluster-logging-release-notes-5.0.1.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="cluster-logging-release-notes-5-0-1"] -= OpenShift Logging 5.0.1 - -This release includes Red Hat Bug Advisory, link:https://access.redhat.com/errata/RHBA-2021:0963[RHBA-2021:0963 for OpenShift Logging Bug Fix Release (5.0.1)]. - -[id="openshift-logging-5-0-1-bug-fixes"] -== Bug fixes - -* Previously, if you enabled legacy log forwarding, logs were not sent to managed storage. This issue occurred because the generated log forwarding configuration improperly chose between either log forwarding or legacy log forwarding. The current release fixes this issue. If the `ClusterLogging` CR defines a `logstore`, logs are sent to managed storage. Additionally, if legacy log forwarding is enabled, logs are sent to legacy log forwarding regardless of whether managed storage is enabled. -(link:https://issues.redhat.com/browse/LOG-1172[*LOG-1172*]) - -* Previously, while under load, Elasticsearch responded to some requests with an HTTP 500 error, even though there was nothing wrong with the cluster. Retrying the request was successful. This release fixes the issue by updating the cron jobs to be more resilient when encountering temporary HTTP 500 errors. Now, they will retry a request multiple times first before failing. -(link:https://issues.redhat.com/browse/LOG-1215[*LOG-1215*]) - -// Other bugs in this release that do not have release notes: -// -// * link:https://issues.redhat.com/browse/LOG-1169[*LOG-1169*] No icon for CLO and EO 5.0 on Operator hub -// * https://issues.redhat.com/browse/LOG-1182[*LOG-1182*] Fix EO upgrade tests for 5.0 diff --git a/modules/cluster-logging-release-notes-5.0.2.adoc b/modules/cluster-logging-release-notes-5.0.2.adoc deleted file mode 100644 index aa2520476d12..000000000000 --- a/modules/cluster-logging-release-notes-5.0.2.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="cluster-logging-release-notes-5-0-2"] -= OpenShift Logging 5.0.2 - -This release includes Red Hat Bug Advisory, link:https://access.redhat.com/errata/RHBA-2021:0963[RHBA-2021:0963 for OpenShift Logging Bug Fix Release (5.0.1)]. - -[id="openshift-logging-5-0-2-bug-fixes"] -== Bug fixes - -* If you did not set `.proxy` in the cluster installation configuration and then configured a global proxy on the installed cluster, a bug prevented Fluentd from forwarding logs to Elasticsearch. To work around this issue, in the proxy/cluster configuration, set `no_proxy` to `.svc.cluster.local` so it skips internal traffic. The current release fixes the proxy configuration issue. Now, if you configure the global proxy after installing an {product-title} cluster, Fluentd forwards logs to Elasticsearch. (link:https://issues.redhat.com/browse/LOG-1187[*LOG-1187*]) diff --git a/modules/cluster-logging-removing-unused-components-if-no-elasticsearch.adoc b/modules/cluster-logging-removing-unused-components-if-no-elasticsearch.adoc deleted file mode 100644 index 74af663d4223..000000000000 --- a/modules/cluster-logging-removing-unused-components-if-no-elasticsearch.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-collector.adoc - -[id="cluster-logging-removing-unused-components-if-no-elasticsearch_{context}"] -= Removing unused components if you do not use the default Elasticsearch log store - -As an administrator, in the rare case that you forward logs to a third-party log store and do not use the default Elasticsearch log store, you can remove several unused components from your logging cluster. - -In other words, if you do not use the default Elasticsearch log store, you can remove the internal Elasticsearch `logStore`, Kibana `visualization`, and log `curation` components from the `ClusterLogging` custom resource (CR). Removing these components is optional but saves resources. - -.Prerequisites - -* Verify that your log forwarder does not send log data to the default internal Elasticsearch cluster. Inspect the `ClusterLogForwarder` CR YAML file that you used to configure log forwarding. Verify that it _does not_ have an `outputRefs` element that specifies `default`. For example: -+ -[source,yaml] ----- -outputRefs: -- default ----- - -[WARNING] -==== -Suppose the `ClusterLogForwarder` CR forwards log data to the internal Elasticsearch cluster, and you remove the `logStore` component from the `ClusterLogging` CR. In that case, the internal Elasticsearch cluster will not be present to store the log data. This absence can cause data loss. -==== - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc edit ClusterLogging instance ----- - -. If they are present, remove the `logStore`, `visualization`, `curation` stanzas from the `ClusterLogging` CR. - -. Preserve the `collection` stanza of the `ClusterLogging` CR. The result should look similar to the following example: -+ -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: "openshift-logging" -spec: - managementState: "Managed" - collection: - logs: - type: "fluentd" - fluentd: {} ----- - -. Verify that the Fluentd pods are redeployed: -+ -[source,terminal] ----- -$ oc get pods -n openshift-logging ----- diff --git a/modules/cluster-logging-systemd-scaling.adoc b/modules/cluster-logging-systemd-scaling.adoc deleted file mode 100644 index 80bcbaca925c..000000000000 --- a/modules/cluster-logging-systemd-scaling.adoc +++ /dev/null @@ -1,136 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/config/cluster-logging-systemd - -[id="cluster-logging-systemd-scaling_{context}"] -= Configuring systemd-journald for OpenShift Logging - -As you scale up your project, the default logging environment might need some -adjustments. - -For example, if you are missing logs, you might have to increase the rate limits for journald. -You can adjust the number of messages to retain for a specified period of time to ensure that -OpenShift Logging does not use excessive resources without dropping logs. - -You can also determine if you want the logs compressed, how long to retain logs, how or if the logs are stored, -and other settings. - -.Procedure - -. Create a `journald.conf` file with the required settings: -+ -[source,terminal] ----- -Compress=yes <1> -ForwardToConsole=no <2> -ForwardToSyslog=no -MaxRetentionSec=1month <3> -RateLimitBurst=10000 <4> -RateLimitIntervalSec=30s -Storage=persistent <5> -SyncIntervalSec=1s <6> -SystemMaxUse=8g <7> -SystemKeepFree=20% <8> -SystemMaxFileSize=10M <9> ----- -+ -<1> Specify whether you want logs compressed before they are written to the file system. -Specify `yes` to compress the message or `no` to not compress. The default is `yes`. -<2> Configure whether to forward log messages. Defaults to `no` for each. Specify: -* `ForwardToConsole` to forward logs to the system console. -* `ForwardToKsmg` to forward logs to the kernel log buffer. -* `ForwardToSyslog` to forward to a syslog daemon. -* `ForwardToWall` to forward messages as wall messages to all logged-in users. -<3> Specify the maximum time to store journal entries. Enter a number to specify seconds. Or -include a unit: "year", "month", "week", "day", "h" or "m". Enter `0` to disable. The default is `1month`. -<4> Configure rate limiting. If, during the time interval defined by `RateLimitIntervalSec`, more logs than specified in `RateLimitBurst` -are received, all further messages within the interval are dropped until the interval is over. It is recommended to set -`RateLimitIntervalSec=30s` and `RateLimitBurst=10000`, which are the defaults. -<5> Specify how logs are stored. The default is `persistent`: -* `volatile` to store logs in memory in `/var/log/journal/`. -* `persistent` to store logs to disk in `/var/log/journal/`. systemd creates the directory if it does not exist. -* `auto` to store logs in in `/var/log/journal/` if the directory exists. If it does not exist, systemd temporarily stores logs in `/run/systemd/journal`. -* `none` to not store logs. systemd drops all logs. -<6> Specify the timeout before synchronizing journal files to disk for *ERR*, *WARNING*, *NOTICE*, *INFO*, and *DEBUG* logs. -systemd immediately syncs after receiving a *CRIT*, *ALERT*, or *EMERG* log. The default is `1s`. -<7> Specify the maximum size the journal can use. The default is `8g`. -<8> Specify how much disk space systemd must leave free. The default is `20%`. -<9> Specify the maximum size for individual journal files stored persistently in `/var/log/journal`. The default is `10M`. -+ -[NOTE] -==== -If you are removing the rate limit, you might see increased CPU utilization on the -system logging daemons as it processes any messages that would have previously -been throttled. -==== -+ -For more information on systemd settings, see link:https://www.freedesktop.org/software/systemd/man/journald.conf.html[https://www.freedesktop.org/software/systemd/man/journald.conf.html]. The default settings listed on that page might not apply to {product-title}. -+ -// Defaults from https://github.com/openshift/openshift-ansible/pull/3753/files#diff-40b7a7231e77d95ca6009dc9bcc0f470R33-R34 - -. Convert the `journal.conf` file to base64: -+ -[source,terminal] ----- -$ export jrnl_cnf=$( cat /journald.conf | base64 -w0 ) ----- - -. Create a new `MachineConfig` object for master or worker and add the `journal.conf` parameters: -+ -For example: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: 50-corp-journald -spec: - config: - ignition: - version: 3.1.0 - storage: - files: - - contents: - source: data:text/plain;charset=utf-8;base64,${jrnl_cnf} - mode: 0644 <1> - overwrite: true - path: /etc/systemd/journald.conf <2> ----- -<1> Set the permissions for the `journal.conf` file. It is recommended to set `0644` permissions. -<2> Specify the path to the base64-encoded `journal.conf` file. - -. Create the machine config: -+ -[source,terminal] ----- -$ oc apply -f .yaml ----- -+ -The controller detects the new `MachineConfig` object and generates a new `rendered-worker-` version. - -. Monitor the status of the rollout of the new rendered configuration to each node: -+ -[source,terminal] ----- -$ oc describe machineconfigpool/worker ----- -+ -.Example output -[source,terminal] ----- -Name: worker -Namespace: -Labels: machineconfiguration.openshift.io/mco-built-in= -Annotations: -API Version: machineconfiguration.openshift.io/v1 -Kind: MachineConfigPool - -... - -Conditions: - Message: - Reason: All nodes are updating to rendered-worker-913514517bcea7c93bd446f4830bc64e ----- diff --git a/modules/cluster-logging-troubleshooting-unknown.adoc b/modules/cluster-logging-troubleshooting-unknown.adoc deleted file mode 100644 index c1f3a57a4986..000000000000 --- a/modules/cluster-logging-troubleshooting-unknown.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-troublehsooting.adoc - -[id="cluster-logging-troubleshooting-unknown_{context}"] -= Troubleshooting a Kubernetes unknown error while connecting to Elasticsearch - -If you are attempting to use a F-5 load balancer in front of Kibana with -`X-Forwarded-For` enabled, this can cause an issue in which the Elasticsearch -`Searchguard` plug-in is unable to correctly accept connections from Kibana. - -.Example Kibana Error Message ----- -Kibana: Unknown error while connecting to Elasticsearch - -Error: Unknown error while connecting to Elasticsearch -Error: UnknownHostException[No trusted proxies] ----- - -.Procedure - -To configure Searchguard to ignore the extra header: - -. Scale down all Fluentd pods. - -. Scale down Elasticsearch after the Fluentd pods have terminated. - -. Add `searchguard.http.xforwardedfor.header: DUMMY` to the Elasticsearch -configuration section. -+ -[source,terminal] ----- -$ oc edit configmap/elasticsearch <1> ----- -<1> This approach requires that Elasticsearch configurations are within a config map. -+ - -. Scale Elasticsearch back up. - -. Scale up all Fluentd pods. diff --git a/modules/cluster-logging-uninstall.adoc b/modules/cluster-logging-uninstall.adoc deleted file mode 100644 index d8904ee27970..000000000000 --- a/modules/cluster-logging-uninstall.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-uninstall.adoc - -[id="cluster-logging-uninstall_{context}"] -= Uninstalling OpenShift Logging from {product-title} - -You can stop log aggregation by deleting the `ClusterLogging` custom resource (CR). After deleting the CR, there are other OpenShift Logging components that remain, which you can optionally remove. - - -Deleting the `ClusterLogging` CR does not remove the persistent volume claims (PVCs). To preserve or delete the remaining PVCs, persistent volumes (PVs), and associated data, you must take further action. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -.Procedure - -To remove OpenShift Logging: - -. Use the {product-title} web console to remove the `ClusterLogging` CR: - -.. Switch to the *Administration* -> *Custom Resource Definitions* page. - -.. On the *Custom Resource Definitions* page, click *ClusterLogging*. - -.. On the *Custom Resource Definition Details* page, click *Instances*. - -.. Click the Options menu {kebab} next to the instance and select *Delete ClusterLogging*. - -. Optional: Delete the custom resource definitions (CRD): - -.. Switch to the *Administration* -> *Custom Resource Definitions* page. - -.. Click the Options menu {kebab} next to *ClusterLogForwarder* and select *Delete Custom Resource Definition*. - -.. Click the Options menu {kebab} next to *ClusterLogging* and select *Delete Custom Resource Definition*. - -.. Click the Options menu {kebab} next to *Elasticsearch* and select *Delete Custom Resource Definition*. - -. Optional: Remove the Cluster Logging Operator and OpenShift Elasticsearch Operator: - -.. Switch to the *Operators* -> *Installed Operators* page. - -.. Click the Options menu {kebab} next to the Cluster Logging Operator and select *Uninstall Operator*. - -.. Click the Options menu {kebab} next to the OpenShift Elasticsearch Operator and select *Uninstall Operator*. - -. Optional: Remove the OpenShift Logging and Elasticsearch projects. - -.. Switch to the *Home* -> *Projects* page. - -.. Click the Options menu {kebab} next to the *openshift-logging* project and select *Delete Project*. - -.. Confirm the deletion by typing `openshift-logging` in the dialog box and click *Delete*. - -.. Click the Options menu {kebab} next to the *openshift-operators-redhat* project and select *Delete Project*. -+ -[IMPORTANT] -==== -Do not delete the `openshift-operators-redhat` project if other global operators are installed in this namespace. -==== - -.. Confirm the deletion by typing `openshift-operators-redhat` in the dialog box and click *Delete*. - -. To keep the PVCs for reuse with other pods, keep the labels or PVC names that you need to reclaim the PVCs. - -. Optional: If you do not want to keep the PVCs, you can delete them. -+ -[WARNING] -==== -Releasing or deleting PVCs can delete PVs and cause data loss. -==== - -.. Switch to the *Storage* -> *Persistent Volume Claims* page. - -.. Click the Options menu {kebab} next to each PVC and select *Delete Persistent Volume Claim*. - -.. If you want to recover storage space, you can delete the PVs. diff --git a/modules/cluster-logging-updating-logging.adoc b/modules/cluster-logging-updating-logging.adoc deleted file mode 100644 index ec2dba773f37..000000000000 --- a/modules/cluster-logging-updating-logging.adoc +++ /dev/null @@ -1,252 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-upgrading.adoc - -[id="cluster-logging-updating-logging_{context}"] -= Updating OpenShift Logging - -After updating the {product-title} cluster, you can update from cluster logging 4.6 to Red Hat OpenShift Logging 5.0 by changing the subscription for the OpenShift Elasticsearch Operator and the Cluster Logging Operator. - -When you update: - -* You must update the OpenShift Elasticsearch Operator before updating the Cluster Logging Operator. -* You must update both the OpenShift Elasticsearch Operator and the Cluster Logging Operator. -+ -Kibana is unusable when the OpenShift Elasticsearch Operator has been updated but the Cluster Logging Operator has not been updated. -+ -If you update the Cluster Logging Operator before the OpenShift Elasticsearch Operator, Kibana does not update and the Kibana custom resource (CR) is not created. To work around this problem, delete the Cluster Logging Operator pod. When the Cluster Logging Operator pod redeploys, the Kibana CR is created. - -[IMPORTANT] -==== -Upgrade your cluster logging version to 4.6 before updating to Red Hat OpenShift Logging 5.0. -==== - -.Prerequisites - -* Update the {product-title} cluster from 4.6 to 4.7. - -* Make sure the OpenShift Logging status is healthy: -+ -** All pods are `ready`. -** The Elasticsearch cluster is healthy. - -* Back up your Elasticsearch and Kibana data. - -.Procedure - -. Update the OpenShift Elasticsearch Operator: - -.. From the web console, click *Operators* -> *Installed Operators*. - -.. Select the `openshift-operators-redhat` project. - -.. Click the *OpenShift Elasticsearch Operator*. - -.. Click *Subscription* -> *Channel*. - -.. In the *Change Subscription Update Channel* window, select *5.0* and click *Save*. - -.. Wait for a few seconds, then click *Operators* -> *Installed Operators*. -+ -Verify that the OpenShift Elasticsearch Operator version is 5.0.x. -+ -Wait for the *Status* field to report *Succeeded*. - -. Update the Cluster Logging Operator: - -.. From the web console, click *Operators* -> *Installed Operators*. - -.. Select the `openshift-logging` project. - -.. Click the *Cluster Logging Operator*. - -.. Click *Subscription* -> *Channel*. - -.. In the *Change Subscription Update Channel* window, select *5.0* and click *Save*. - -.. Wait for a few seconds, then click *Operators* -> *Installed Operators*. -+ -Verify that the Cluster Logging Operator version is 5.0.x. -+ -Wait for the *Status* field to report *Succeeded*. - -. Check the logging components: - -.. Ensure that all Elasticsearch pods are in the *Ready* status: -+ -[source,terminal] ----- -$ oc get pod -n openshift-logging --selector component=elasticsearch ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -elasticsearch-cdm-1pbrl44l-1-55b7546f4c-mshhk 2/2 Running 0 31m -elasticsearch-cdm-1pbrl44l-2-5c6d87589f-gx5hk 2/2 Running 0 30m -elasticsearch-cdm-1pbrl44l-3-88df5d47-m45jc 2/2 Running 0 29m ----- -+ -.. Ensure that the Elasticsearch cluster is healthy: -+ -[source,terminal] ----- -$ oc exec -n openshift-logging -c elasticsearch elasticsearch-cdm-1pbrl44l-1-55b7546f4c-mshhk -- es_cluster_health ----- -+ -[source,json] ----- -{ - "cluster_name" : "elasticsearch", - "status" : "green", -} -.... - ----- - -.. Ensure that the Elasticsearch cron jobs are created: -+ -[source,terminal] ----- -$ oc project openshift-logging ----- -+ -[source,terminal] ----- -$ oc get cronjob ----- -+ -[source,terminal] ----- -NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE -elasticsearch-delete-app */15 * * * * False 0 27s -elasticsearch-delete-audit */15 * * * * False 0 27s -elasticsearch-delete-infra */15 * * * * False 0 27s -elasticsearch-rollover-app */15 * * * * False 0 27s -elasticsearch-rollover-audit */15 * * * * False 0 27s -elasticsearch-rollover-infra */15 * * * * False 0 27s ----- - -.. Verify that the log store is updated to 5.0 and the indices are `green`: -+ -[source,terminal] ----- -$ oc exec -c elasticsearch -- indices ----- -+ -Verify that the output includes the `app-00000x`, `infra-00000x`, `audit-00000x`, `.security` indices. -+ -.Sample output with indices in a green status -[%collapsible] -==== -[source,terminal] ----- -Tue Jun 30 14:30:54 UTC 2020 -health status index uuid pri rep docs.count docs.deleted store.size pri.store.size -green open infra-000008 bnBvUFEXTWi92z3zWAzieQ 3 1 222195 0 289 144 -green open infra-000004 rtDSzoqsSl6saisSK7Au1Q 3 1 226717 0 297 148 -green open infra-000012 RSf_kUwDSR2xEuKRZMPqZQ 3 1 227623 0 295 147 -green open .kibana_7 1SJdCqlZTPWlIAaOUd78yg 1 1 4 0 0 0 -green open infra-000010 iXwL3bnqTuGEABbUDa6OVw 3 1 248368 0 317 158 -green open infra-000009 YN9EsULWSNaxWeeNvOs0RA 3 1 258799 0 337 168 -green open infra-000014 YP0U6R7FQ_GVQVQZ6Yh9Ig 3 1 223788 0 292 146 -green open infra-000015 JRBbAbEmSMqK5X40df9HbQ 3 1 224371 0 291 145 -green open .orphaned.2020.06.30 n_xQC2dWQzConkvQqei3YA 3 1 9 0 0 0 -green open infra-000007 llkkAVSzSOmosWTSAJM_hg 3 1 228584 0 296 148 -green open infra-000005 d9BoGQdiQASsS3BBFm2iRA 3 1 227987 0 297 148 -green open infra-000003 1-goREK1QUKlQPAIVkWVaQ 3 1 226719 0 295 147 -green open .security zeT65uOuRTKZMjg_bbUc1g 1 1 5 0 0 0 -green open .kibana-377444158_kubeadmin wvMhDwJkR-mRZQO84K0gUQ 3 1 1 0 0 0 -green open infra-000006 5H-KBSXGQKiO7hdapDE23g 3 1 226676 0 295 147 -green open infra-000001 eH53BQ-bSxSWR5xYZB6lVg 3 1 341800 0 443 220 -green open .kibana-6 RVp7TemSSemGJcsSUmuf3A 1 1 4 0 0 0 -green open infra-000011 J7XWBauWSTe0jnzX02fU6A 3 1 226100 0 293 146 -green open app-000001 axSAFfONQDmKwatkjPXdtw 3 1 103186 0 126 57 -green open infra-000016 m9c1iRLtStWSF1GopaRyCg 3 1 13685 0 19 9 -green open infra-000002 Hz6WvINtTvKcQzw-ewmbYg 3 1 228994 0 296 148 -green open infra-000013 KR9mMFUpQl-jraYtanyIGw 3 1 228166 0 298 148 -green open audit-000001 eERqLdLmQOiQDFES1LBATQ 3 1 0 0 0 0 ----- -==== - -.. Verify that the log collector is updated to 5.0: -+ -[source,terminal] ----- -$ oc get ds fluentd -o json | grep fluentd-init ----- -+ -Verify that the output includes a `fluentd-init` container: -+ -[source,terminal] ----- -"containerName": "fluentd-init" ----- - -.. Verify that the log visualizer is updated to 5.0 using the Kibana CRD: -+ -[source,terminal] ----- -$ oc get kibana kibana -o json ----- -+ -Verify that the output includes a Kibana pod with the `ready` status: -+ -.Sample output with a ready Kibana pod -[%collapsible] -==== -[source,json] ----- -[ -{ -"clusterCondition": { -"kibana-5fdd766ffd-nb2jj": [ -{ -"lastTransitionTime": "2020-06-30T14:11:07Z", -"reason": "ContainerCreating", -"status": "True", -"type": "" -}, -{ -"lastTransitionTime": "2020-06-30T14:11:07Z", -"reason": "ContainerCreating", -"status": "True", -"type": "" -} -] -}, -"deployment": "kibana", -"pods": { -"failed": [], -"notReady": [] -"ready": [] -}, -"replicaSets": [ -"kibana-5fdd766ffd" -], -"replicas": 1 -} -] ----- -==== - -.. Verify the Curator is updated to 5.0: -+ -[source,terminal] ----- -$ oc get cronjob -o name ----- -+ -[source,terminal] ----- -cronjob.batch/curator -cronjob.batch/elasticsearch-delete-app -cronjob.batch/elasticsearch-delete-audit -cronjob.batch/elasticsearch-delete-infra -cronjob.batch/elasticsearch-rollover-app -cronjob.batch/elasticsearch-rollover-audit -cronjob.batch/elasticsearch-rollover-infra ----- -+ -Verify that the output includes the `elasticsearch-delete-\*` and `elasticsearch-rollover-*` indices. diff --git a/modules/cluster-logging-visualizer-indices.adoc b/modules/cluster-logging-visualizer-indices.adoc deleted file mode 100644 index 4f65fd48115d..000000000000 --- a/modules/cluster-logging-visualizer-indices.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-visualizer.adoc - -[id="cluster-logging-visualizer-indices_{context}"] -= Defining Kibana index patterns - -An index pattern defines the Elasticsearch indices that you want to visualize. To explore and visualize data in Kibana, you must create an index pattern. - -.Prerequisites - -* A user must have the `cluster-admin` role, the `cluster-reader` role, or both roles to view the *infra* and *audit* indices in Kibana. The default `kubeadmin` user has proper permissions to view these indices. -+ -If you can view the pods and logs in the `default`, `kube-` and `openshift-` projects, you should be able to access these indices. You can use the following command to check if the current user has appropriate permissions: -+ -[source,terminal] ----- -$ oc auth can-i get pods/log -n ----- -+ -.Example output -[source,terminal] ----- -yes ----- -+ -[NOTE] -==== -The audit logs are not stored in the internal {product-title} Elasticsearch instance by default. To view the audit logs in Kibana, you must use the Log Forwarding API to configure a pipeline that uses the `default` output for audit logs. -==== - -* Elasticsearch documents must be indexed before you can create index patterns. This is done automatically, but it might take a few minutes in a new or updated cluster. - -.Procedure - -To define index patterns and create visualizations in Kibana: - -. In the {product-title} console, click the Application Launcher {launch} and select *Logging*. - -. Create your Kibana index patterns by clicking *Management* -> *Index Patterns* -> *Create index pattern*: - -** Each user must manually create index patterns when logging into Kibana the first time to see logs for their projects. Users must create an index pattern named `app` and use the `@timestamp` time field to view their container logs. - -** Each admin user must create index patterns when logged into Kibana the first time for the `app`, `infra`, and `audit` indices using the `@timestamp` time field. - -. Create Kibana Visualizations from the new index patterns. diff --git a/modules/cluster-logging-visualizer-kibana.adoc b/modules/cluster-logging-visualizer-kibana.adoc deleted file mode 100644 index 32dacc8a1422..000000000000 --- a/modules/cluster-logging-visualizer-kibana.adoc +++ /dev/null @@ -1,121 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/viewing/cluster-logging-visualizer.adoc - -[id="cluster-logging-visualizer-kibana_{context}"] -= Viewing cluster logs in Kibana - -You view cluster logs in the Kibana web console. The methods for viewing and visualizing your data in Kibana that are beyond the scope of this documentation. For more information, refer to the link:https://www.elastic.co/guide/en/kibana/6.8/tutorial-sample-discover.html[Kibana documentation]. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. - -* Kibana index patterns must exist. - -* A user must have the `cluster-admin` role, the `cluster-reader` role, or both roles to view the *infra* and *audit* indices in Kibana. The default `kubeadmin` user has proper permissions to view these indices. -+ -If you can view the pods and logs in the `default`, `kube-` and `openshift-` projects, you should be able to access these indices. You can use the following command to check if the current user has appropriate permissions: -+ -[source,terminal] ----- -$ oc auth can-i get pods/log -n ----- -+ -.Example output -[source,terminal] ----- -yes ----- -+ -[NOTE] -==== -The audit logs are not stored in the internal {product-title} Elasticsearch instance by default. To view the audit logs in Kibana, you must use the Log Forwarding API to configure a pipeline that uses the `default` output for audit logs. -==== - -.Procedure - -To view logs in Kibana: - -. In the {product-title} console, click the Application Launcher {launch} and select *Logging*. - -. Log in using the same credentials you use to log in to the {product-title} console. -+ -The Kibana interface launches. - -. In Kibana, click *Discover*. - -. Select the index pattern you created from the drop-down menu in the top-left corner: *app*, *audit*, or *infra*. -+ -The log data displays as time-stamped documents. - -. Expand one of the time-stamped documents. - -. Click the *JSON* tab to display the log entry for that document. -+ -.Sample infrastructure log entry in Kibana -[%collapsible] -==== -[source,terminal] ----- -{ - "_index": "infra-000001", - "_type": "_doc", - "_id": "YmJmYTBlNDkZTRmLTliMGQtMjE3NmFiOGUyOWM3", - "_version": 1, - "_score": null, - "_source": { - "docker": { - "container_id": "f85fa55bbef7bb783f041066be1e7c267a6b88c4603dfce213e32c1" - }, - "kubernetes": { - "container_name": "registry-server", - "namespace_name": "openshift-marketplace", - "pod_name": "redhat-marketplace-n64gc", - "container_image": "registry.redhat.io/redhat/redhat-marketplace-index:v4.7", - "container_image_id": "registry.redhat.io/redhat/redhat-marketplace-index@sha256:65fc0c45aabb95809e376feb065771ecda9e5e59cc8b3024c4545c168f", - "pod_id": "8f594ea2-c866-4b5c-a1c8-a50756704b2a", - "host": "ip-10-0-182-28.us-east-2.compute.internal", - "master_url": "https://kubernetes.default.svc/", - "namespace_id": "3abab127-7669-4eb3-b9ef-44c04ad68d38", - "namespace_labels": { - "openshift_io/cluster-monitoring": "true" - }, - "flat_labels": [ - "catalogsource_operators_coreos_com/update=redhat-marketplace" - ] - }, - "message": "time=\"2020-09-23T20:47:03Z\" level=info msg=\"serving registry\" database=/database/index.db port=50051", - "level": "unknown", - "hostname": "ip-10-0-182-28.internal", - "pipeline_metadata": { - "collector": { - "ipaddr4": "10.0.182.28", - "inputname": "fluent-plugin-systemd", - "name": "fluentd", - "received_at": "2020-09-23T20:47:15.007583+00:00", - "version": "1.7.4 1.6.0" - } - }, - "@timestamp": "2020-09-23T20:47:03.422465+00:00", - "viaq_msg_id": "YmJmYTBlNDktMDMGQtMjE3NmFiOGUyOWM3", - "openshift": { - "labels": { - "logging": "infra" - } - } - }, - "fields": { - "@timestamp": [ - "2020-09-23T20:47:03.422Z" - ], - "pipeline_metadata.collector.received_at": [ - "2020-09-23T20:47:15.007Z" - ] - }, - "sort": [ - 1600894023422 - ] -} ----- -==== diff --git a/modules/cluster-logging-visualizer-launch.adoc b/modules/cluster-logging-visualizer-launch.adoc deleted file mode 100644 index 268ea7a9c092..000000000000 --- a/modules/cluster-logging-visualizer-launch.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/cluster-logging-visualizer.adoc - -[id="cluster-logging-visualizer-launch_{context}"] -= Launching the log visualizer - -{product-title} uses Kibana as the log visualizer. Kibana is a browser-based console to query, discover, and visualize your logs through histograms, line graphs, -pie charts, heat maps, built-in geospatial support, and other visualizations. - -.Prerequisites - -* To list the *infra* and *audit* indices in Kibana, a user must have the `cluster-admin` role, the `cluster-reader` role, or both roles. The default `kubeadmin` user has proper permissions to list these indices. -+ -If you can view the pods and logs in the `default`, `kube-*` and `openshift-*` projects, you should be able to access these indices. You can use the following command to check if the current user has proper permissions: -+ -[source,terminal] ----- -$ oc auth can-i get pods/log -n ----- -+ -.Example output -[source,terminal] ----- -yes ----- -+ -[NOTE] -==== -The audit logs are not stored in the internal {product-title} Elasticsearch instance by default. To view the audit logs in Kibana, you must use the Log Forwarding API to configure a pipeline that uses the `default` output for audit logs. -==== - -.Procedure - -To launch Kibana: - -. In the {product-title} console, click the Application Launcher {launch} and select *Logging*. - -. Log in using the same credentials you use to log in to the {product-title} console. -+ -The Kibana interface launches. - -[NOTE] -==== -If you get a *security_exception* error in the Kibana console and cannot access your Kibana indices, you might have an expired OAuth token. If you see this error, log out of the Kibana console, and then log back in. This refreshes your OAuth tokens and you should be able to access your indices. -==== diff --git a/modules/cluster-monitoring-operator.adoc b/modules/cluster-monitoring-operator.adoc deleted file mode 100644 index a9baf0310b3e..000000000000 --- a/modules/cluster-monitoring-operator.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-monitoring-operator_{context}"] -= Cluster Monitoring Operator - -[discrete] -== Purpose - -The Cluster Monitoring Operator manages and updates the Prometheus-based cluster monitoring stack deployed on top of {product-title}. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-monitoring-operator[openshift-monitoring] - -[discrete] -== CRDs - -* `alertmanagers.monitoring.coreos.com` -** Scope: Namespaced -** CR: `alertmanager` -** Validation: Yes -* `prometheuses.monitoring.coreos.com` -** Scope: Namespaced -** CR: `prometheus` -** Validation: Yes -* `prometheusrules.monitoring.coreos.com` -** Scope: Namespaced -** CR: `prometheusrule` -** Validation: Yes -* `servicemonitors.monitoring.coreos.com` -** Scope: Namespaced -** CR: `servicemonitor` -** Validation: Yes - -[discrete] -== Configuration objects - -[source,terminal] ----- -$ oc -n openshift-monitoring edit cm cluster-monitoring-config ----- diff --git a/modules/cluster-network-operator.adoc b/modules/cluster-network-operator.adoc deleted file mode 100644 index e5027d4ea013..000000000000 --- a/modules/cluster-network-operator.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-network-operator_{context}"] -= Cluster Network Operator - -[discrete] -== Purpose - -The Cluster Network Operator installs and upgrades the networking components on an {product-title} cluster. diff --git a/modules/cluster-node-tuning-operator-default-profiles-set.adoc b/modules/cluster-node-tuning-operator-default-profiles-set.adoc deleted file mode 100644 index 0cdc547ebad0..000000000000 --- a/modules/cluster-node-tuning-operator-default-profiles-set.adoc +++ /dev/null @@ -1,91 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/using-node-tuning-operator.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="custom-tuning-default-profiles-set_{context}"] -= Default profiles set on a cluster - -The following are the default profiles set on a cluster. - -[source,yaml] ----- -apiVersion: tuned.openshift.io/v1 -kind: Tuned -metadata: - name: default - namespace: openshift-cluster-node-tuning-operator -spec: - profile: - - name: "openshift" - data: | - [main] - summary=Optimize systems running OpenShift (parent profile) - include=${f:virt_check:virtual-guest:throughput-performance} - - [selinux] - avc_cache_threshold=8192 - - [net] - nf_conntrack_hashsize=131072 - - [sysctl] - net.ipv4.ip_forward=1 - kernel.pid_max=>4194304 - net.netfilter.nf_conntrack_max=1048576 - net.ipv4.conf.all.arp_announce=2 - net.ipv4.neigh.default.gc_thresh1=8192 - net.ipv4.neigh.default.gc_thresh2=32768 - net.ipv4.neigh.default.gc_thresh3=65536 - net.ipv6.neigh.default.gc_thresh1=8192 - net.ipv6.neigh.default.gc_thresh2=32768 - net.ipv6.neigh.default.gc_thresh3=65536 - vm.max_map_count=262144 - - [sysfs] - /sys/module/nvme_core/parameters/io_timeout=4294967295 - /sys/module/nvme_core/parameters/max_retries=10 - - - name: "openshift-control-plane" - data: | - [main] - summary=Optimize systems running OpenShift control plane - include=openshift - - [sysctl] - # ktune sysctl settings, maximizing i/o throughput - # - # Minimal preemption granularity for CPU-bound tasks: - # (default: 1 msec# (1 + ilog(ncpus)), units: nanoseconds) - kernel.sched_min_granularity_ns=10000000 - # The total time the scheduler will consider a migrated process - # "cache hot" and thus less likely to be re-migrated - # (system default is 500000, i.e. 0.5 ms) - kernel.sched_migration_cost_ns=5000000 - # SCHED_OTHER wake-up granularity. - # - # Preemption granularity when tasks wake up. Lower the value to - # improve wake-up latency and throughput for latency critical tasks. - kernel.sched_wakeup_granularity_ns=4000000 - - - name: "openshift-node" - data: | - [main] - summary=Optimize systems running OpenShift nodes - include=openshift - - [sysctl] - net.ipv4.tcp_fastopen=3 - fs.inotify.max_user_watches=65536 - fs.inotify.max_user_instances=8192 - - recommend: - - profile: "openshift-control-plane" - priority: 30 - match: - - label: "node-role.kubernetes.io/master" - - label: "node-role.kubernetes.io/infra" - - - profile: "openshift-node" - priority: 40 ----- diff --git a/modules/cluster-node-tuning-operator-verify-profiles.adoc b/modules/cluster-node-tuning-operator-verify-profiles.adoc deleted file mode 100644 index a35733483e06..000000000000 --- a/modules/cluster-node-tuning-operator-verify-profiles.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/using-node-tuning-operator.adoc - -[id="verifying-tuned-profiles-are-applied_{context}"] -= Verifying that the TuneD profiles are applied - -Starting with {product-title} 4.8, it is no longer necessary to check the TuneD pod logs -to find which TuneD profiles are applied on cluster nodes. - -[source,terminal] ----- -$ oc get profile -n openshift-cluster-node-tuning-operator ----- - -.Example output -[source,terminal] ----- -NAME TUNED APPLIED DEGRADED AGE -master-0 openshift-control-plane True False 6h33m -master-1 openshift-control-plane True False 6h33m -master-2 openshift-control-plane True False 6h33m -worker-a openshift-node True False 6h28m -worker-b openshift-node True False 6h28m ----- - -* `NAME`: Name of the Profile object. There is one Profile object per node and their names match. -* `TUNED`: Name of the desired TuneD profile to apply. -* `APPLIED`: `True` if the TuneD daemon applied the desired profile. (`True/False/Unknown`). -* `DEGRADED`: `True` if any errors were reported during application of the TuneD profile (`True/False/Unknown`). -* `AGE`: Time elapsed since the creation of Profile object. diff --git a/modules/cluster-openshift-controller-manager-operators.adoc b/modules/cluster-openshift-controller-manager-operators.adoc deleted file mode 100644 index 52d18d574c48..000000000000 --- a/modules/cluster-openshift-controller-manager-operators.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-openshift-controller-manager-operator_{context}"] -= OpenShift Controller Manager Operator - -[discrete] -== Purpose - -The OpenShift Controller Manager Operator installs and maintains the `OpenShiftControllerManager` custom resource in a cluster and can be viewed with: - -[source,terminal] ----- -$ oc get clusteroperator openshift-controller-manager -o yaml ----- - -The custom resource definitino (CRD) `openshiftcontrollermanagers.operator.openshift.io` can be viewed in a cluster with: - -[source,terminal] ----- -$ oc get crd openshiftcontrollermanagers.operator.openshift.io -o yaml ----- - -[discrete] -== Project - -link:https://github.com/openshift/cluster-openshift-controller-manager-operator[cluster-openshift-controller-manager-operator] diff --git a/modules/cluster-samples-operator.adoc b/modules/cluster-samples-operator.adoc deleted file mode 100644 index 7c5e20bf9898..000000000000 --- a/modules/cluster-samples-operator.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-samples-operator_{context}"] -= Cluster Samples Operator - -[discrete] -== Purpose - -The Cluster Samples Operator manages the sample image streams and templates stored in the `openshift` namespace. - -On initial start up, the Operator creates the default samples configuration resource to initiate the creation of the image streams and templates. The configuration object is a cluster scoped object with the key `cluster` and type `configs.samples`. - -The image streams are the {op-system-first}-based {product-title} image streams pointing to images on `registry.redhat.io`. Similarly, the templates are those categorized as {product-title} templates. - -The Cluster Samples Operator deployment is contained within the `openshift-cluster-samples-operator` namespace. On start up, the install pull secret is used by the image stream import logic in the internal registry and API server to authenticate with `registry.redhat.io`. An administrator can create any additional secrets in the `openshift` namespace if they change the registry used for the sample image streams. If created, those secrets contain the content of a `config.json` for `docker` needed to facilitate image import. - -The image for the Cluster Samples Operator contains image stream and template definitions for the associated {product-title} release. After the Cluster Samples Operator creates a sample, it adds an annotation that denotes the {product-title} version that it is compatible with. The Operator uses this annotation to ensure that each sample matches the compatible release version. Samples outside of its inventory are ignored, as are skipped samples. - -Modifications to any samples that are managed by the Operator are allowed as long as the version annotation is not modified or deleted. However, on an upgrade, as the version annotation will change, those modifications can get replaced as the sample will be updated with the newer version. The Jenkins images are part of the image payload from the installation and are tagged into the image streams directly. - -The samples resource includes a finalizer, which cleans up the following upon its deletion: - -* Operator-managed image streams -* Operator-managed templates -* Operator-generated configuration resources -* Cluster status resources - -Upon deletion of the samples resource, the Cluster Samples Operator recreates the resource using the default configuration. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-samples-operator[cluster-samples-operator] diff --git a/modules/cluster-status-section.adoc b/modules/cluster-status-section.adoc new file mode 100644 index 000000000000..55e177b983cf --- /dev/null +++ b/modules/cluster-status-section.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/use-system-health-dashboard.adoc + +:_mod-docs-content-type: REFERENCE +[id="cluster-status-section_{context}"] += Cluster status section + +The *Cluster status* section organizes the information into the following groups: + +Healthy:: Indicates that the cluster and all its components are fully operational without any detected issues. +Unhealthy:: Indicates the components or subsystems that have failed or are in a critical state and require immediate attention. +Degraded:: Indicates the components functioning below optimal performance or with limited functionality. +Unavailable:: Indicates the components or services that are unreachable or nonfunctional. +Uninitialized:: Indicates the components or services that are not yet set up or are in the process of initialization. +Total:: Indicates the total count of clusters being monitored in the system. \ No newline at end of file diff --git a/modules/cluster-storage-operator.adoc b/modules/cluster-storage-operator.adoc deleted file mode 100644 index 0890dee3c3ba..000000000000 --- a/modules/cluster-storage-operator.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-storage-operator_{context}"] -= Cluster Storage Operator - -[discrete] -== Purpose - -The Cluster Storage Operator sets {product-title} cluster-wide storage defaults. It ensures a default storage class exists for {product-title} clusters. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-storage-operator[cluster-storage-operator] - -[discrete] -== Configuration - -No configuration is required. - -[discrete] -== Notes - -* The Cluster Storage Operator supports Amazon Web Services (AWS) and {rh-openstack-first}. -* The created storage class can be made non-default by editing its annotation, but the storage class cannot be deleted as long as the Operator runs. diff --git a/modules/cluster-version-operator.adoc b/modules/cluster-version-operator.adoc deleted file mode 100644 index 89579df315db..000000000000 --- a/modules/cluster-version-operator.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="cluster-version-operator_{context}"] -= Cluster Version Operator - -[discrete] -== Purpose - -[discrete] -== Project - -link:https://github.com/openshift/cluster-version-operator[cluster-version-operator] diff --git a/modules/cnf-about-virtual-routing-and-forwarding.adoc b/modules/cnf-about-virtual-routing-and-forwarding.adoc deleted file mode 100644 index 8dd7ad87cfaa..000000000000 --- a/modules/cnf-about-virtual-routing-and-forwarding.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// networking/multiple_networks/about-virtual-routing-and-forwarding.adoc - -[id="cnf-about-virtual-routing-and-forwarding_{context}"] -= About virtual routing and forwarding - -Virtual routing and forwarding (VRF) devices combined with IP rules provide the ability to create virtual routing and forwarding domains. VRF reduces the number of permissions needed by CNF, and provides increased visibility of the network topology of secondary networks. VRF is used to provide multi-tenancy functionality, for example, where each tenant has its own unique routing tables and requires different default gateways. - -Processes can bind a socket to the VRF device. Packets through the binded socket use the routing table associated with the VRF device. An important feature of VRF is that it impacts only OSI model layer 3 traffic and above so L2 tools, such as LLDP, are not affected. This allows higher priority IP rules such as policy based routing to take precedence over the VRF device rules directing specific traffic. - -[id="cnf-benefits-secondary-networks-telecommunications-operators_{context}"] -== Benefits of secondary networks for pods for telecommunications operators - -In telecommunications use cases, each CNF can potentially be connected to multiple different networks sharing the same address space. These secondary networks can potentially conflict with the cluster's main network CIDR. Using the CNI VRF plug-in, network functions can be connected to different customers' infrastructure using the same IP address, keeping different customers isolated. IP addresses are overlapped with {product-title} IP space. The CNI VRF plug-in also reduces the number of permissions needed by CNF and increases the visibility of network topologies of secondary networks. diff --git a/modules/cnf-about_hyperthreading_for_low_latency_and_real_time_applications.adoc b/modules/cnf-about_hyperthreading_for_low_latency_and_real_time_applications.adoc deleted file mode 100644 index 1d62a6856f1b..000000000000 --- a/modules/cnf-about_hyperthreading_for_low_latency_and_real_time_applications.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="about_hyperthreading_for_low_latency_and_real_time_applications_{context}"] -= About hyperthreading for low latency and real-time applications - -Hyperthreading is an Intel processor technology that allows a physical CPU processor core to function as two logical cores, executing two independent threads simultaneously. Hyperthreading allows for better system throughput for certain workload types where parallel processing is beneficial. The default {product-title} configuration expects hyperthreading to be enabled by default. - -For telecommunications applications, it is important to design your application infrastructure to minimize latency as much as possible. Hyperthreading can slow performance times and negatively affect throughput for compute intensive workloads that require low latency. Disabling hyperthreading ensures predictable performance and can decrease processing times for these workloads. - -[NOTE] -==== -Hyperthreading implementation and configuration differs depending on the hardware you are running {product-title} on. Consult the relevant host hardware tuning information for more details of the hyperthreading implementation specific to that hardware. Disabling hyperthreading can increase the cost per core of the cluster. -==== diff --git a/modules/cnf-allocating-multiple-huge-page-sizes.adoc b/modules/cnf-allocating-multiple-huge-page-sizes.adoc deleted file mode 100644 index 71259f1d617f..000000000000 --- a/modules/cnf-allocating-multiple-huge-page-sizes.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// CNF-538 Promote Multiple Huge Pages Sizes for Pods and Containers to beta -// Module included in the following assemblies: -// -// *scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="cnf-allocating-multiple-huge-page-sizes_{context}"] -= Allocating multiple huge page sizes - -You can request huge pages with different sizes under the same container. This allows you to define more complicated pods consisting of containers with different huge page size needs. - -For example, you can define sizes `1G` and `2M` and the Performance Addon Operator will configure both sizes on the node, as shown here: - -[source,yaml] ----- -spec: - hugepages: - defaultHugepagesSize: 1G - pages: - - count: 1024 - node: 0 - size: 2M - - count: 4 - node: 1 - size: 1G ----- diff --git a/modules/cnf-assigning-a-secondary-network-to-a-vrf.adoc b/modules/cnf-assigning-a-secondary-network-to-a-vrf.adoc deleted file mode 100644 index 4ede6c460c6f..000000000000 --- a/modules/cnf-assigning-a-secondary-network-to-a-vrf.adoc +++ /dev/null @@ -1,128 +0,0 @@ -// Module included in the following assemblies: -// -// networking/multiple_networks/assigning-a-secondary-network-to-a-vrf.adoc - - -[id="cnf-assigning-a-secondary-network-to-a-vrf_{context}"] -= Assigning a secondary network to a VRF - -As a cluster administrator, you can configure an additional network for your VRF domain by using the CNI VRF plug-in. The virtual network created by this plug-in is associated with a physical interface that you specify. - -[id="cnf-creating-an-additional-network-attachment-with-the-cni-vrf-plug-in_{context}"] -== Creating an additional network attachment with the CNI VRF plug-in - -The Cluster Network Operator (CNO) manages additional network definitions. When you specify an additional network to create, the CNO creates the `NetworkAttachmentDefinition` custom resource (CR) automatically. - -[NOTE] -==== -Do not edit the `NetworkAttachmentDefinition` CRs that the Cluster Network Operator manages. Doing so might disrupt network traffic on your additional network. -==== - -.Prerequisites - -* Install the {product-title} CLI (oc). -* Log in to the OpenShift cluster as a user with cluster-admin privileges. - -.Procedure - -. Create the CNO CR by running the following command: -+ -[source,terminal] ----- -$ oc edit networks.operator.openshift.io cluster ----- -. Extend the CR that you are creating by adding the `rawCNIConfig` configuration for the additional network, as in the example CR below. The following YAML configures the CNI VRF plug-in: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster - spec: - additionalNetworks: - - name: test-network-1 - namespace: test-1 - type: Raw - rawCNIConfig: '{ - "cniVersion": "0.3.1", - "name": "macvlan-vrf", - "plugins": [ <1> - { - "type": "macvlan", <2> - "master": "eth1", - "ipam": { - "type": "static", - "addresses": [ - { - "address": "191.168.1.23/24" - } - ] - } - }, - { - "type": "vrf", - "vrfname": "example-vrf-name", <3> - "table": 1001 <4> - }] - }' ----- -<1> `plugins` must be a list. The first item in the list must be secondary network underpinning the VRF network. The second item in the list is the VRF plugin configuration. -<2> `type` must be set to `vrf`. -<3> `vrfname` is the name of the VRF that the interface is assigned to. If it does not exist in the pod, it is created. -<4> `table` is the routing table ID. Optional. By default, the `tableid` parameter is used. If it is not specified, the CNI assigns a free routing table ID to the VRF. -+ -[NOTE] -==== -VRF will function correctly only when the resource is of type `netdevice`. -==== -. Save your changes and quit the text editor to commit your changes. -. Confirm that the CNO created the `NetworkAttachmentDefinition` CR by running the following command. Replace `` with the namespace that you specified when configuring the network attachment. There might be a delay before the CNO creates the CR. -+ -[source,terminal] ----- -$ oc get network-attachment-definitions -n ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -additional-network-1 14m ----- - -.Verifying that the additional VRF network attachment is successful - -To verify that the VRF CNI is correctly configured and the additional network attachment is attached, do the following: - -. Create a network that uses the VRF CNI. -. Assign the network to a pod. -. Verify that the pod network attachment is connected to the VRF additional network. SSH into the pod and run the following command: -+ -[source,terminal] ----- -$ ip vrf show ----- -+ -.Example output -+ -[source,terminal] ----- -Name Table ------------------------ -red 10 ----- -. Confirm the VRF interface is master of the secondary interface: -+ -[source,terminal] ----- -$ ip link ----- -+ -.Example output -+ -[source,terminal] ----- -5: net1: mtu 1500 qdisc noqueue master red state UP mode ----- - diff --git a/modules/cnf-assigning-a-sriov-network-to-a-vrf.adoc b/modules/cnf-assigning-a-sriov-network-to-a-vrf.adoc deleted file mode 100644 index ffc5bb5c56ff..000000000000 --- a/modules/cnf-assigning-a-sriov-network-to-a-vrf.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// Module included in the following assemblies: -// -//networking/hardware_networks/configuring-sriov-device.adoc - -[id="cnf-assigning-a-sriov-network-to-a-vrf_{context}"] -= Assigning an SR-IOV network to a VRF - -As a cluster administrator, you can assign an SR-IOV network interface to your VRF domain by using the CNI VRF plug-in. - -To do this, add the VRF configuration to the optional `metaPlugins` parameter of the `SriovNetwork` resource. - -[id="cnf-creating-an-additional-sriov-network-with-vrf-plug-in_{context}"] -== Creating an additional SR-IOV network attachment with the CNI VRF plug-in - -The SR-IOV Network Operator manages additional network definitions. When you specify an additional SR-IOV network to create, the SR-IOV Network Operator creates the `NetworkAttachmentDefinition` custom resource (CR) automatically. - -[NOTE] -==== -Do not edit `NetworkAttachmentDefinition` custom resources that the SR-IOV Network Operator manages. Doing so might disrupt network traffic on your additional network. -==== - -.Prerequisites -* Install the {product-title} CLI (oc). -* Log in to the {product-title} cluster as a user with cluster-admin privileges. - -.Procedure -. Create the `SriovNetwork` CR by running the following command: -+ -[source,terminal] ----- -$ oc create sriovnetwork.openshift.io cluster ----- -. Extend the CR that you are creating by adding the `metaPlugins` configuration for the additional network you are creating, as in the following example CR. -. Save your changes and quit the text editor to commit your changes. The following YAML configures the `SriovNetwork` object: -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetwork -metadata: - name: example-network - namespace: additional-sriov-network-1 -spec: - ipam: | - { - "type": "host-local", - "subnet": "10.56.217.0/24", - "rangeStart": "10.56.217.171", - "rangeEnd": "10.56.217.181", - "routes": [{ - "dst": "0.0.0.0/0" - }], - "gateway": "10.56.217.1" - } - vlan: 0 - resourceName: intelnics - metaPlugins : | - { - "type": "vrf", <1> - "vrfname": "example-vrf-name" <2> - } ----- -<1> `type` must be set to `vrf`. -<2> `vrfname` is the name of the VRF that the interface is assigned to. If it does not exist in the pod, it is created. - -.Verify the `NetworkAttachmentDefinition` CR is successfully created -Confirm that the SR-IOV Network Operator created the `NetworkAttachmentDefinition` CR by running the following command. Replace `` with the namespace that you specified when configuring the network attachment. There might be a delay before the SR-IOV Network Operator creates the CR. - -[source,terminal] ----- -$ oc get network-attachment-definitions -n ----- - -.Example output -[source,terminal] ----- -NAME AGE -additional-sriov-network-1 14m ----- - -.Verifying that the additional SR-IOV network attachment is successful - -To verify that the VRF CNI is correctly configured and the additional SR-IOV network attachment is attached, do the following: - -. Create an SR-IOV network that uses the VRF CNI. -. Assign the network to a pod. -. Verify that the pod network attachment is connected to the SR-IOV additional network. SSH into the pod and run the following command: -+ -[source,terminal] ----- -$ ip vrf show ----- -+ -.Example output -[source,terminal] ----- -Name Table ------------------------ -red 10 ----- -. Confirm the VRF interface is master of the secondary interface: -+ -[source,terminal] ----- -$ ip link ----- -+ -.Example output -[source,terminal] ----- -5: net1: mtu 1500 qdisc noqueue master red state UP mode ----- - diff --git a/modules/cnf-associating-secondary-interfaces-metrics-to-network-attachments.adoc b/modules/cnf-associating-secondary-interfaces-metrics-to-network-attachments.adoc deleted file mode 100644 index e1fbbbb39bc5..000000000000 --- a/modules/cnf-associating-secondary-interfaces-metrics-to-network-attachments.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// CNF-43 Associate Secondary Interfaces Metrics to Network Attachments -// Module included in the following assemblies: -// -// *networking/associating-secondary-interfaces-metrics-to-network-attachments.adoc - -[id="cnf-associating-secondary-interfaces-metrics-to-network-attachments_{context}"] -= Associating secondary interfaces metrics to network attachments - -Secondary devices, or interfaces, are used for different purposes. It is important to have a way to classify them to be able to aggregate the metrics for secondary devices with the same classification. - -Exposed metrics contain the interface but do not specify where the interface originates. This is workable when there are no additional interfaces, but if a secondary interface is added, it is difficult to make use of the metrics since it is hard to identify the interfaces using only the interface name as an identifier. - -When adding secondary interfaces, their names depend on the order in which they are added, and different secondary interfaces might belong to different networks and can be used for different purposes. - -With `pod_network_name_info` it is possible to extend the current metrics with the additional information that identifies the interface type. In this way, it is possible to aggregate the metrics and to add specific alarms to specific interface types. - -The network type is generated using the name of the related `NetworkAttachementDefinition`, that in turn is used to differentiate different classes of secondary networks. For example, different interfaces belonging to different networks or using different CNIs use different network attachment definition names. - -[id="cnf-associating-secondary-interfaces-metrics-to-network-attachments-network-metrics-daemon_{context}"] -== Network Metrics Daemon - -The Network Metrics Daemon is a daemon component that collects and publishes network related metrics. - -The kubelet is already publishing network related metrics you can observe. These metrics are: - -* `container_network_receive_bytes_total` -* `container_network_receive_errors_total` -* `container_network_receive_packets_total` -* `container_network_receive_packets_dropped_total` -* `container_network_transmit_bytes_total` -* `container_network_transmit_errors_total` -* `container_network_transmit_packets_total` -* `container_network_transmit_packets_dropped_total` - -The labels in these metrics contain, among others: - -* Pod name -* Pod namespace -* Interface name (such as `eth0`) - -These metrics work well until new interfaces are added to the Pod, for example via https://github.com/intel/multus-cni[Multus], as it is not clear what the interface names refer to. - -The interface label refers to the interface name, but it is not clear what that interface is meant for. In case of many different interfaces, it would be impossible to understand what network the metrics you are monitoring refer to. - -This is addressed by introducing the new `pod_network_name_info` described in the following section. - -[id="cnf-associating-secondary-interfaces-metrics-with-network-name_{context}"] -== Metrics with network name - -This daemonset publishes a `pod_network_name_info` gauge metric, with a fixed value of `0`: - -[source,bash] ----- -pod_network_name_info{interface="net0",namespace="namespacename",network_name="nadnamespace/firstNAD",pod="podname"} 0 ----- - -The network name label is produced using the annotation added by Multus. It ia the concatenation of the namespace the network attachment definition belongs to, plus the name of the network attachment definition. - -The new metric alone does not provide much value, but combined with the network related `container_network_*` metrics, it offers better support for monitoring secondary networks. - -Using a `promql` query like the following ones, it is possible to get a new metric containing the value and the network name retrieved from the `k8s.v1.cni.cncf.io/networks-status` annotation: - -[source,bash] ----- -(container_network_receive_bytes_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info ) -(container_network_receive_errors_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info ) -(container_network_receive_packets_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info ) -(container_network_receive_packets_dropped_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info ) -(container_network_transmit_bytes_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info ) -(container_network_transmit_errors_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info ) -(container_network_transmit_packets_total) + on(namespace,pod,interface) group_left(network_name) ( pod_network_name_info ) -(container_network_transmit_packets_dropped_total) + on(namespace,pod,interface) group_left(network_name) ----- diff --git a/modules/cnf-collecting-low-latency-tuning-debugging-data-for-red-hat-support.adoc b/modules/cnf-collecting-low-latency-tuning-debugging-data-for-red-hat-support.adoc deleted file mode 100644 index 321e503b9ab3..000000000000 --- a/modules/cnf-collecting-low-latency-tuning-debugging-data-for-red-hat-support.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// CNF-643 Support and debugging tools for CNF -// Module included in the following assemblies: -// -// *scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="cnf-collecting-low-latency-tuning-debugging-data-for-red-hat-support_{context}"] -= Collecting low latency tuning debugging data for Red Hat Support - -When opening a support case, it is helpful to provide debugging information about your cluster to Red Hat Support. - -The `must-gather` tool enables you to collect diagnostic information about your {product-title} cluster, including node tuning, NUMA topology, and other information needed to debug issues with low latency setup. - -For prompt support, supply diagnostic information for both {product-title} and low latency tuning. - -[id="cnf-about-must-gather_{context}"] -== About the must-gather tool - -The `oc adm must-gather` CLI command collects the information from your cluster that is most likely needed for debugging issues, such as: - -* Resource definitions -* Audit logs -* Service logs - -You can specify one or more images when you run the command by including the `--image` argument. When you specify an image, the tool collects data related to that feature or product. When you run `oc adm must-gather`, a new pod is created on the cluster. The data is collected on that pod and saved in a new directory that starts with `must-gather.local`. This directory is created in your current working directory. - -[id="cnf-about-collecting-low-latency-data_{context}"] -== About collecting low latency tuning data - -Use the `oc adm must-gather` CLI command to collect information about your cluster, including features and objects associated with low latency tuning, including: - -* The Performance Addon Operator namespaces and child objects. -* `MachineConfigPool` and associated `MachineConfig` objects. -* The Node Tuning Operator and associated Tuned objects. -* Linux Kernel command line options. -* CPU and NUMA topology -* Basic PCI device information and NUMA locality. - -To collect container-native virtualization data with `must-gather`, you must specify the container-native virtualization image: - -[source,terminal] ----- ---image=registry.redhat.io/openshift4/performance-addon-operator-must-gather-rhel8. ----- - -[id="cnf-about-gathering-data_{context}"] -== Gathering data about specific features - -You can gather debugging information about specific features by using the `oc adm must-gather` CLI command with the `--image` or `--image-stream` argument. The `must-gather` tool supports multiple images, so you can gather data about more than one feature by running a single command. - -[NOTE] -==== -To collect the default `must-gather` data in addition to specific feature data, add the `--image-stream=openshift/must-gather` argument. -==== - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. -* The {product-title} CLI (oc) installed. - -.Procedure - -. Navigate to the directory where you want to store the `must-gather` data. - -. Run the `oc adm must-gather` command with one or more `--image` or `--image-stream` arguments. For example, the following command gathers both the default cluster data and information specific to container-native virtualization: -+ -[source,terminal] ----- -$ oc adm must-gather \ - --image-stream=openshift/must-gather \ <1> - - --image=registry.redhat.io/openshift4/performance-addon-operator-must-gather-rhel8 <2> ----- -+ -<1> The default {product-title} `must-gather` image. -<2> The `must-gather` image for low latency tuning diagnostics. - -. Create a compressed file from the `must-gather` directory that was created in your working directory. For example, on a computer that uses a Linux operating system, run the following command: -+ -[source,terminal] ----- - $ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ <1> ----- -+ -<1> Replace `must-gather-local.5421342344627712289/` with the actual directory name. - -. Attach the compressed file to your support case on the link:https://access.redhat.com/[Red Hat Customer Portal]. diff --git a/modules/cnf-configure_for_irq_dynamic_load_balancing.adoc b/modules/cnf-configure_for_irq_dynamic_load_balancing.adoc deleted file mode 100644 index c7bf57c9111d..000000000000 --- a/modules/cnf-configure_for_irq_dynamic_load_balancing.adoc +++ /dev/null @@ -1,174 +0,0 @@ -// Module included in the following assemblies: -// -// scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="configuring_for_irq_dynamic_load_balancing_{context}"] -= Configuring a node for IRQ dynamic load balancing - -To configure a cluster node to handle IRQ dynamic load balancing, do the following: - -. Log in to the {product-title} cluster as a user with cluster-admin privileges. -. Set the performance profile `apiVersion` to use `performance.openshift.io/v2`. -. Remove the `globallyDisableIrqLoadBalancing` field or set it to `false`. -. Set the appropriate isolated and reserved CPUs. The following snippet illustrates a profile that reserves 2 CPUs. IRQ load-balancing is enabled for pods running on the `isolated` CPU set: -+ -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: PerformanceProfile -metadata: - name: dynamic-irq-profile -spec: - cpu: - isolated: 2-5 - reserved: 0-1 -... ----- - -. Create the pod that uses exclusive CPUs, and set `irq-load-balancing.crio.io` and `cpu-quota.crio.io` annotations to `disable`. For example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dynamic-irq-pod - annotations: - irq-load-balancing.crio.io: "disable" - cpu-quota.crio.io: "disable" -spec: - containers: - - name: dynamic-irq-pod - image: "quay.io/openshift-kni/cnf-tests:4.6" - command: ["sleep", "10h"] - resources: - requests: - cpu: 2 - memory: "200M" - limits: - cpu: 2 - memory: "200M" - nodeSelector: - node-role.kubernetes.io/worker-cnf: "" - runtimeClassName: performance-dynamic-irq-profile -... ----- - -. Enter the pod `runtimeClassName` in the form performance-, where is the `name` from the `PerformanceProfile` YAML, in this example, `performance-dynamic-irq-profile`. -. Set the node selector to target a cnf-worker. -. Ensure the pod is running correctly. Status should be `running`, and the correct cnf-worker node should be set: -+ -[source,terminal] ----- -$ oc get pod -o wide ----- -+ -.Expected output -+ -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -dynamic-irq-pod 1/1 Running 0 5h33m ----- -. Get the CPUs that the pod configured for IRQ dynamic load balancing runs on: -+ -[source,terminal] ----- -$ oc exec -it dynamic-irq-pod -- /bin/bash -c "grep Cpus_allowed_list /proc/self/status | awk '{print $2}'" ----- -+ -.Expected output -+ -[source,terminal] ----- -Cpus_allowed_list: 2-3 ----- -. Ensure the node configuration is applied correctly. SSH into the node to verify the configuration. -+ -[source,terminal] ----- -$ oc debug node/ ----- -+ -.Expected output -+ -[source,terminal] ----- -Starting pod/-debug ... -To use host binaries, run `chroot /host` - -Pod IP: -If you don't see a command prompt, try pressing enter. - -sh-4.4# ----- - -. Verify that you can use the node file system: -+ -[source,terminal] ----- -sh-4.4# chroot /host ----- -+ -.Expected output -+ -[source,terminal] ----- -sh-4.4# ----- - -. Ensure the default system CPU affinity mask does not include the `dynamic-irq-pod` CPUs, for example, CPUs 2 and 3. -+ -[source,terminal] ----- -$ cat /proc/irq/default_smp_affinity ----- -+ -.Example output -+ -[source,terminal] ----- -33 ----- -. Ensure the system IRQs are not configured to run on the `dynamic-irq-pod` CPUs: -+ -[source,terminal] ----- -find /proc/irq/ -name smp_affinity_list -exec sh -c 'i="$1"; mask=$(cat $i); file=$(echo $i); echo $file: $mask' _ {} \; ----- -+ -.Example output -+ -[source,terminal] ----- -/proc/irq/0/smp_affinity_list: 0-5 -/proc/irq/1/smp_affinity_list: 5 -/proc/irq/2/smp_affinity_list: 0-5 -/proc/irq/3/smp_affinity_list: 0-5 -/proc/irq/4/smp_affinity_list: 0 -/proc/irq/5/smp_affinity_list: 0-5 -/proc/irq/6/smp_affinity_list: 0-5 -/proc/irq/7/smp_affinity_list: 0-5 -/proc/irq/8/smp_affinity_list: 4 -/proc/irq/9/smp_affinity_list: 4 -/proc/irq/10/smp_affinity_list: 0-5 -/proc/irq/11/smp_affinity_list: 0 -/proc/irq/12/smp_affinity_list: 1 -/proc/irq/13/smp_affinity_list: 0-5 -/proc/irq/14/smp_affinity_list: 1 -/proc/irq/15/smp_affinity_list: 0 -/proc/irq/24/smp_affinity_list: 1 -/proc/irq/25/smp_affinity_list: 1 -/proc/irq/26/smp_affinity_list: 1 -/proc/irq/27/smp_affinity_list: 5 -/proc/irq/28/smp_affinity_list: 1 -/proc/irq/29/smp_affinity_list: 0 -/proc/irq/30/smp_affinity_list: 0-5 ----- - -Some IRQ controllers do not support IRQ re-balancing and will always expose all online CPUs as the IRQ mask. These IRQ controllers effectively run on CPU 0. For more information on the host configuration, SSH into the host and run the following, replacing `` with the CPU number that you want to query: - -[source,terminal] ----- -$ cat /proc/irq//effective_affinity ----- diff --git a/modules/cnf-configuring-huge-pages.adoc b/modules/cnf-configuring-huge-pages.adoc deleted file mode 100644 index a53ece80a0de..000000000000 --- a/modules/cnf-configuring-huge-pages.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -//CNF-78 (4.4) -// * scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="cnf-configuring-huge-pages_{context}"] -= Configuring huge pages - -Nodes must pre-allocate huge pages used in an {product-title} cluster. Use the Performance Addon Operator to allocate huge pages on a specific node. - -{product-title} provides a method for creating and allocating huge pages. Performance Addon Operator provides an easier method for doing this using the performance profile. - -For example, in the `hugepages` `pages` section of the performance profile, you can specify multiple blocks of `size`, `count`, and, optionally, `node`: - -[source,yaml] ----- -hugepages: - defaultHugepagesSize: "1G" - pages: - - size: "1G" - count: 4 - node: 0 <1> ----- - -<1> `node` is the NUMA node in which the huge pages are allocated. If you omit `node`, the pages are evenly spread across all NUMA nodes. - -[NOTE] -==== -Wait for the relevant machine config pool status that indicates the update is finished. -==== - -These are the only configuration steps you need to do to allocate huge pages. - - -.Verification - -* To verify the configuration, see the `/proc/meminfo` file on the node: -+ -[source,terminal] ----- -$ oc debug node/ip-10-0-141-105.ec2.internal ----- -+ -[source,terminal] ----- -# grep -i huge /proc/meminfo ----- -+ -.Example output -[source,terminal] ----- -AnonHugePages: ###### ## -ShmemHugePages: 0 kB -HugePages_Total: 2 -HugePages_Free: 2 -HugePages_Rsvd: 0 -HugePages_Surp: 0 -Hugepagesize: #### ## -Hugetlb: #### ## ----- - -* Use `oc describe` to report the new size: -+ -[source,terminal] ----- -$ oc describe node worker-0.ocp4poc.example.com | grep -i huge ----- -+ -.Example output -[source,terminal] ----- - hugepages-1g=true - hugepages-###: ### - hugepages-###: ### ----- diff --git a/modules/cnf-creating-the-performance-profile-object.adoc b/modules/cnf-creating-the-performance-profile-object.adoc deleted file mode 100644 index 585032156bb9..000000000000 --- a/modules/cnf-creating-the-performance-profile-object.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// Epic CNF-78 -// * scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="cnf-creating-the-performance-profile-object_{context}"] -= Creating the PerformanceProfile object - -Create the `PerformanceProfile` object using the object that is posted to the cluster. -After you have specified your settings, the `PerformanceProfile` object is compiled into multiple objects: - -* A `Machine.Config` file that manipulates the nodes. -* A `KubeletConfig` file that configures the Topology Manager, the CPU Manager, and the {product-title} nodes. -* The Tuned profile that configures the Node Tuning Operator. - -.Procedure - -. Prepare a cluster. - -. Create a Machine ConfigPool. - -. Install the Performance Profile Operator. - -. Create a performance profile that is appropriate for your hardware and topology. -In the performance profile, you can specify whether to update the kernel to kernel-rt, the CPUs that -will be reserved for housekeeping, and CPUs that will be used for running the workloads. -+ -This is a typical performance profile: -+ ----- -apiversion: performance.openshift.io/v2 -kind: PerformanceProfile -metadata: - name: -spec: - cpu: - isolated: “1-3” - reserved: “0” - hugepages: - defaultHugepagesSize: “1Gi” - pages: -size: “1Gi” - count: 4 - node: 0 -realTimeKernel: - enabled: true - numa: - topologyPolicy: “best-effort” ----- - -. Specify two groups of CPUs in the `spec` section: -+ -`isolated` - Has the lowest latency. Because processes in this group have no interruptions, there is zero packet loss. -+ -`reserved` - The housekeeping CPUs. Threads in the reserved group tend to be very busy, so latency-sensitive -applications should be run in the isolated group. -See link:https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/#create-a-pod-that-gets-assigned-a-qos-class-of-guaranteed[Create a Pod that gets assigned a QoS class of `Guaranteed`]. - -For example, you can reserve cores (threads) from a single NUMA node and put your workloads on another NUMA node. -The reason for this is that the housekeeping CPUs may be touching caches in the CPU. -Keeping your workloads on a separate NUMA node prevents the nodes from interfering with each other. -Additionally, each NUMA node has its own memory bus that is not shared. diff --git a/modules/cnf-debugging-low-latency-cnf-tuning-status.adoc b/modules/cnf-debugging-low-latency-cnf-tuning-status.adoc deleted file mode 100644 index 4f7684cfe04c..000000000000 --- a/modules/cnf-debugging-low-latency-cnf-tuning-status.adoc +++ /dev/null @@ -1,121 +0,0 @@ -// Module included in the following assemblies: -// Epic CNF-303 (4.5) -// scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc -//CNF-303 Performance add-ons status CNF-372 -//Performance Addon Operator Detailed Status -//See: https://issues.redhat.com/browse/CNF-379 (Yanir Quinn) - -[id="cnf-debugging-low-latency-cnf-tuning-status_{context}"] -= Debugging low latency CNF tuning status - -The `PerformanceProfile` custom resource (CR) contains status fields for reporting tuning status and debugging latency degradation issues. These fields report on conditions that describe the state of the operator's reconciliation functionality. - -A typical issue can arise when the status of machine config pools that are attached to the performance profile are in a degraded state, causing the `PerformanceProfile` status to degrade. In this case, the machine config pool issues a failure message. - -The Performance Addon Operator contains the `performanceProfile.spec.status.Conditions` status field: - -[source,bash] ----- -Status: - Conditions: - Last Heartbeat Time: 2020-06-02T10:01:24Z - Last Transition Time: 2020-06-02T10:01:24Z - Status: True - Type: Available - Last Heartbeat Time: 2020-06-02T10:01:24Z - Last Transition Time: 2020-06-02T10:01:24Z - Status: True - Type: Upgradeable - Last Heartbeat Time: 2020-06-02T10:01:24Z - Last Transition Time: 2020-06-02T10:01:24Z - Status: False - Type: Progressing - Last Heartbeat Time: 2020-06-02T10:01:24Z - Last Transition Time: 2020-06-02T10:01:24Z - Status: False - Type: Degraded ----- - -The `Status` field contains `Conditions` that specify `Type` values that indicate the status of the performance profile: - -`Available`:: All machine configs and Tuned profiles have been created successfully and are available for cluster components are responsible to process them (NTO, MCO, Kubelet). - -`Upgradeable`:: Indicates whether the resources maintained by the Operator are in a state that is safe to upgrade. - -`Progressing`:: Indicates that the deployment process from the performance profile has started. - -`Degraded`:: Indicates an error if: -+ -* Validation of the performance profile has failed. -* Creation of all relevant components did not complete successfully. - -Each of these types contain the following fields: - -`Status`:: The state for the specific type (`true` or `false`). -`Timestamp`:: The transaction timestamp. -`Reason string`:: The machine readable reason. -`Message string`:: The human readable reason describing the state and error details, if any. - -[id="cnf-debugging-low-latency-cnf-tuning-status-machineconfigpools_{context}"] -== Machine config pools - -A performance profile and its created products are applied to a node according to an associated machine config pool (MCP). The MCP holds valuable information about the progress of applying the machine configurations created by performance addons that encompass kernel args, kube config, huge pages allocation, and deployment of rt-kernel. The performance addons controller monitors changes in the MCP and updates the performance profile status accordingly. - -The only conditions returned by the MCP to the performance profile status is when the MCP is `Degraded`, which leads to `performaceProfile.status.condition.Degraded = true`. - -.Example - -The following example is for a performance profile with an associated machine config pool (`worker-cnf`) that was created for it: - -. The associated machine config pool is in a degraded state: -+ -[source,terminal] ----- -# oc get mcp ----- -+ -.Example output -+ -[source,terminal] ----- -NAME CONFIG UPDATED UPDATING DEGRADED MACHINECOUNT READYMACHINECOUNT UPDATEDMACHINECOUNT DEGRADEDMACHINECOUNT AGE -master rendered-master-2ee57a93fa6c9181b546ca46e1571d2d True False False 3 3 3 0 2d21h -worker rendered-worker-d6b2bdc07d9f5a59a6b68950acf25e5f True False False 2 2 2 0 2d21h -worker-cnf rendered-worker-cnf-6c838641b8a08fff08dbd8b02fb63f7c False True True 2 1 1 1 2d20h ----- - -. The `describe` section of the MCP shows the reason: -+ -[source,terminal] ----- -# oc describe mcp worker-cnf ----- -+ -.Example output -+ -[source,terminal] ----- - Message: Node node-worker-cnf is reporting: "prepping update: - machineconfig.machineconfiguration.openshift.io \"rendered-worker-cnf-40b9996919c08e335f3ff230ce1d170\" not - found" - Reason: 1 nodes are reporting degraded status on sync ----- - -. The degraded state should also appear under the performance profile `status` field marked as `degraded = true`: -+ -[source,terminal] ----- -# oc describe performanceprofiles performance ----- -+ -.Example output -+ -[source,terminal] ----- -Message: Machine config pool worker-cnf Degraded Reason: 1 nodes are reporting degraded status on sync. -Machine config pool worker-cnf Degraded Message: Node yquinn-q8s5v-w-b-z5lqn.c.openshift-gce-devel.internal is -reporting: "prepping update: machineconfig.machineconfiguration.openshift.io -\"rendered-worker-cnf-40b9996919c08e335f3ff230ce1d170\" not found". Reason: MCPDegraded - Status: True - Type: Degraded ----- diff --git a/modules/cnf-deploying-the-du-infrastructure-profile.adoc b/modules/cnf-deploying-the-du-infrastructure-profile.adoc deleted file mode 100644 index 42da5516e719..000000000000 --- a/modules/cnf-deploying-the-du-infrastructure-profile.adoc +++ /dev/null @@ -1,255 +0,0 @@ -// CNF-950 4.7 Deploying the DU infrastructure profile -// Module included in the following assemblies: -// -// *cnf-provisioning-and-deploying-a-distributed-unit.adoc - -[id="scalability_and_performance/cnf-deploying-the-du-infrastructure-profile_{context}"] -= Deploying the DU infrastructure profile - -[id="cnf-creating-the-performance-addon-operator-and-du-performance-profile_{context}"] -== Creating the Performance Addon Operator and DU performance profile - -. Create and apply the performance profile, for example: -+ -[source,yaml] ----- -cat < - reserved: "0,2,4,6,8" <2> - hugepages: - defaultHugepagesSize: 1G - pages: - - count: 16 <3> - size: 1G - node: 0 - nodeSelector: - # Pay attention to the node label, create MCP accordingly - node-role.kubernetes.io/worker-cnf: "" - numa: - topologyPolicy: "restricted" - realTimeKernel: - # For CU should be false - enabled: true - -EOF ----- -<1> Configure this line based upon the customer CPU hardware selected to run the DU. -<2> Configure this line based upon the customer CPU hardware selected to run the DU. -<3> Configure this line based upon the customer memory configuration selected to run the DU. - -. Use the following command to verify the changes have been applied to the cluster: -+ -[source,terminal] ----- -$ oc wait mcp/worker-cnf --for condition="updated" ----- - -[id="cnf-creating-the-ptp-operator-and-slave-profile_{context}"] -== Creating the PTP Operator and slave profile - -. Apply the PTP configuration, for example: -+ -[source,yaml] ----- -cat < - ptp4lOpts: "-2 -s --summary_interval -4" <2> - phc2sysOpts: "-a -r -n 24" <3> - ptp4lConf: | - [global] - # - # Default Data Set - # - twoStepFlag 1 - slaveOnly 0 - priority1 128 - priority2 128 - domainNumber 24 <4> - #utc_offset 37 - clockClass 248 - clockAccuracy 0xFE - offsetScaledLogVariance 0xFFFF - free_running 0 - freq_est_interval 1 - dscp_event 0 - dscp_general 0 - dataset_comparison ieee1588 - G.8275.defaultDS.localPriority 128 - # - # Port Data Set - # - logAnnounceInterval -3 <5> - logSyncInterval -4 <5> - logMinDelayReqInterval -4 <5> - logMinPdelayReqInterval -4 <5> - announceReceiptTimeout 3 <5> - syncReceiptTimeout 0 - delayAsymmetry 0 - fault_reset_interval 4 - neighborPropDelayThresh 20000000 - masterOnly 0 - G.8275.portDS.localPriority 128 - # - # Run time options - # - assume_two_step 0 - logging_level 6 - path_trace_enabled 0 - follow_up_info 0 - hybrid_e2e 0 - inhibit_multicast_service 0 - net_sync_monitor 0 - tc_spanning_tree 0 - tx_timestamp_timeout 1 - unicast_listen 0 - unicast_master_table 0 - unicast_req_duration 3600 - use_syslog 1 - verbose 0 - summary_interval 0 - kernel_leap 1 - check_fup_sync 0 - # - # Servo Options - # - pi_proportional_const 0.0 - pi_integral_const 0.0 - pi_proportional_scale 0.0 - pi_proportional_exponent -0.3 - pi_proportional_norm_max 0.7 - pi_integral_scale 0.0 - pi_integral_exponent 0.4 - pi_integral_norm_max 0.3 - step_threshold 0.0 - first_step_threshold 0.00002 - max_frequency 900000000 - clock_servo pi - sanity_freq_limit 200000000 - ntpshm_segment 0 - # - # Transport options - # - transportSpecific 0x0 - ptp_dst_mac 01:1B:19:00:00:00 - p2p_dst_mac 01:80:C2:00:00:0E - udp_ttl 1 - udp6_scope 0x0E - uds_address /var/run/ptp4l - # - # Default interface options - # - clock_type OC - network_transport UDPv4 - delay_mechanism E2E - time_stamping hardware - tsproc_mode filter - delay_filter moving_median - delay_filter_length 10 - egressLatency 0 - ingressLatency 0 - boundary_clock_jbod 0 - # - # Clock description - # - productDescription ;; - revisionData ;; - manufacturerIdentity 00:00:00 - userDescription ; - timeSource 0xA0 - recommend: - - profile: "slave" - priority: 4 - match: - - nodeLabel: "ptp/slave" - -EOF ----- -<1> The interface selected needs to match the Linux interface name. -<2> `-2` configures Ethernet encapsulation of PTP. `--summary_interval -4` sets the logging interval. -This is currently set to match `logSyncInterval -4`. -<3> `-n 24` must match the `domainNumber 24`. -<4> `domainNumber 24` must match the `-n 24`. -<5> These variables are set to enable the G.8275.1 profile for PTP. - -[id="cnf-creating-the-sriov-operator-and-associated-profiles_{context}"] -== Creating the SR-IOV Operator and associated profiles - -. Apply the SR-IOV network node policy, for example: -+ -[source,yaml] ----- -cat < -# For Mellanox please change to: -# deviceType: netdevice -# isRdma: true - deviceType: vfio-pci - isRdma: false - nicSelector: -# The exact physical function name must match the hardware used - pfNames: ["ens1f1"] <2> - nodeSelector: - node-role.kubernetes.io/worker-cnf: "" - feature.node.kubernetes.io/network-sriov.capable: "true" - numVfs: 4 - priority: 10 - resourceName: mh_u_site_1_fqdn_worker1 - -EOF ----- -<1> This file works for Intel and must change for Mellanox, as described in -_SR-IOV configuration notes_. -<2> Must be updated with the specific device on the server. - -. Create the SR-IOV network, for example: -+ -[source,yaml] ----- -cat < ---- -apiVersion: v1 -kind: Namespace -metadata: - name: mh-net-ns-site-1-fqdn-worker1 - -EOF ----- -<1> Modify this line to match the DU’s networking. diff --git a/modules/cnf-installing-the-operators.adoc b/modules/cnf-installing-the-operators.adoc deleted file mode 100644 index 45020f4d524d..000000000000 --- a/modules/cnf-installing-the-operators.adoc +++ /dev/null @@ -1,242 +0,0 @@ -// CNF-950 4.7 Installing the operators -// Module included in the following assemblies: -// -// *scalability_and_performance/cnf-provisioning-and-deploying-a-distributed-unit.adoc - -[id="cnf-installing-the-operators_{context}"] -= Installing the Operators - -[id="cnf-installing-the-performnce-addon-operator_{context}"] -== Installing the Performance Addon Operator - -Install the Performance Addon Operator using the {product-title} CLI. - -.Procedure - -. Create the Performance Addon Operator namespace: -+ -[source,yaml] ----- -cat <" <1> - name: performance-addon-operator - source: redhat-operators <2> - sourceNamespace: openshift-marketplace - -EOF ----- -<1> Specify the value you obtained in the previous step for the `status.defaultChannel` parameter. -<2> You must specify the `redhat-operators` value. - -[id="cnf-installing-the-precision-time-protocol-operator_{context}"] -== Installing the Precision Time Protocol (PTP) Operator - -Install the PTP Operator using the {product-title} CLI or the web console. - -.Procedure - -. Apply the Operator namespace: -+ -[source,yaml] ----- -cat <" <1> - name: performance-addon-operator - source: redhat-operators <2> - sourceNamespace: openshift-marketplace ----- -<1> Specify the value from you obtained in the previous step for the `.status.defaultChannel` parameter. -<2> You must specify the `redhat-operators` value. - -.. Create the Subscription object by running the following command: -+ -[source,terminal] ----- -$ oc create -f pao-sub.yaml ----- - -.. Change to the `openshift-performance-addon-operator` project: -+ -[source,terminal] ----- -$ oc project openshift-performance-addon-operator ----- - -[id="install-operator-web-console_{context}"] -== Installing the Performance Addon Operator using the web console - -As a cluster administrator, you can install the Performance Addon Operator using the web console. - -[NOTE] -==== -You must create the `Namespace` CR and `OperatorGroup` CR as mentioned in the previous section. -==== - -.Procedure - -. Install the Performance Addon Operator using the {product-title} web console: - -.. In the {product-title} web console, click *Operators* -> *OperatorHub*. - -.. Choose *Performance Addon Operator* from the list of available Operators, and then click *Install*. - -.. On the *Install Operator* page, select *All namespaces on the cluster*. Then, click *Install*. - -. Optional: Verify that the performance-addon-operator installed successfully: - -.. Switch to the *Operators* -> *Installed Operators* page. - -.. Ensure that *Performance Addon Operator* is listed in the *openshift-performance-addon-operator* project with a *Status* of *InstallSucceeded*. -+ -[NOTE] -==== -During installation an Operator might display a *Failed* status. If the installation later succeeds with an *InstallSucceeded* message, you can ignore the *Failed* message. -==== -+ -If the Operator does not appear as installed, to troubleshoot further: -+ -* Go to the *Operators* -> *Installed Operators* page and inspect the *Operator Subscriptions* and *Install Plans* tabs for any failure or errors -under *Status*. -* Go to the *Workloads* -> *Pods* page and check the logs for pods in the `performance-addon-operator` project. diff --git a/modules/cnf-managing-device-interrupt-processing-for-guaranteed-pod-isolated-cpus.adoc b/modules/cnf-managing-device-interrupt-processing-for-guaranteed-pod-isolated-cpus.adoc deleted file mode 100644 index be28a28cc53e..000000000000 --- a/modules/cnf-managing-device-interrupt-processing-for-guaranteed-pod-isolated-cpus.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// CNF-802 Infrastructure-provided interrupt processing for guaranteed pod CPUs -// Module included in the following assemblies: -// -// *cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="managing-device-interrupt-processing-for-guaranteed-pod-isolated-cpus_{context}"] -= Managing device interrupt processing for guaranteed pod isolated CPUs - -The Performance Addon Operator manages host CPUs by dividing them into reserved CPUs for cluster and operating system housekeeping duties, and isolated CPUs for workloads. CPUs that are used for low latency workloads are set as isolated. - -Device interrupts are load balanced between all isolated and reserved CPUs to avoid CPUs being overloaded, with the exception of CPUs where there is a guaranteed pod running. Guaranteed pod CPUs are prevented from processing device interrupts when the relevant annotations are set for the pod. - -In the performance profile, `globallyDisableIrqLoadBalancing` is used to manage whether device interrupts are processed or not. For certain workloads the reserved CPUs are not always sufficient for dealing with device interrupts, and for this reason, device interrupts are not globally disabled on the isolated CPUs. By default, Performance Addon Operator does not disable device interrupts on isolated CPUs. - -To achieve low latency for workloads, some (but not all) pods require the CPUs they are running on to not process device interrupts. A pod annotation, `irq-load-balancing.crio.io`, is used to define whether device interrupts are processed or not. When configured, CRI-O disables device interrupts only as long as the pod is running. - -[id="configuring-global-device-interrupts-handling-for-isolated-cpus_{context}"] -== Disabling global device interrupts handling in Performance Addon Operator - -To configure Performance Addon Operator to disable global device interrupts for the isolated CPU set, set the `globallyDisableIrqLoadBalancing` field in the performance profile to `true`. When `true`, conflicting pod annotations are ignored. When `false`, IRQ loads are balanced across all CPUs. - -A performance profile snippet illustrates this setting: - -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: PerformanceProfile -metadata: - name: manual -spec: - globallyDisableIrqLoadBalancing: true -... ----- - -[id="disabling_interrupt_processing_for_individual_pods_{context}"] -== Disabling interrupt processing for individual pods - -To disable interrupt processing for individual pods, ensure that `globallyDisableIrqLoadBalancing` is set to `false` in the performance profile. Then, in the pod specification, set the `irq-load-balancing.crio.io` and `cpu-quota.crio.io` pod annotations to `disable`. An example pod specification snippet that illustrates this is below: - -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: Pod -metadata: - annotations: - irq-load-balancing.crio.io: "disable" - cpu-quota.crio.io: "disable" -spec: - runtimeClassName: performance- -... ----- - - - - diff --git a/modules/cnf-modifying-and-applying-the-default-profile.adoc b/modules/cnf-modifying-and-applying-the-default-profile.adoc deleted file mode 100644 index fcd6dd80a0e7..000000000000 --- a/modules/cnf-modifying-and-applying-the-default-profile.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// CNF-950 4.7 Modifying and applying the default profile -// Module included in the following assemblies: -// -// *scalability_and_performance/cnf-provisioning-and-deploying-a-distributed-unit.adoc - -[id="cnf-modifying-and-applying-the-default-profile_{context}"] -= Modifying and applying the default profile - -You can apply the profile manually or with the toolset of your choice, such as ArgoCD. - -[NOTE] -==== -This procedure applies the DU profile step-by-step. If the profile is pulled together into a single project and applied in one step, issues will occur between the MCO and -the SRIOV operators if an Intel NIC is used for networking traffic. To avoid a race condition between the MCO and the SRIOV Operators, it is recommended that the DU application be applied in three steps: - -. Apply the profile without SRIOV. -. Wait for the cluster to settle. -. Apply the SRIOV portion. -==== diff --git a/modules/cnf-performing-end-to-end-tests-for-platform-verification.adoc b/modules/cnf-performing-end-to-end-tests-for-platform-verification.adoc deleted file mode 100644 index af937784eb90..000000000000 --- a/modules/cnf-performing-end-to-end-tests-for-platform-verification.adoc +++ /dev/null @@ -1,632 +0,0 @@ -// Module included in the following assemblies: -// Epic CNF-290 (4.5) -// scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="cnf-performing-end-to-end-tests-for-platform-verification_{context}"] -= Performing end-to-end tests for platform verification - -The Cloud-native Network Functions link:https://quay.io/repository/openshift-kni/cnf-tests?tag=latest&tab=tags[(CNF)] tests image is a containerized test suite that validates features required to run CNF payloads. You can use this image to validate a CNF-enabled OpenShift cluster where all the components required for running CNF workloads are installed. - -The tests run by the image are split into three different phases: - -* Simple cluster validation -* Setup -* End to end tests - -The validation phase checks that all the features required to be tested are deployed correctly on the cluster. - -Validations include: - -* Targeting a machine config pool that belong to the machines to be tested -* Enabling SCTP on the nodes -* Enabling xt_u32 kernel module via machine config -* Having the Performance Addon Operator installed -* Having the SR-IOV Operator installed -* Having the PTP Operator installed -* Using OVN kubernetes as the SDN - -Latency tests, a part of the CNF-test container, also require the same validations. For more information about running a latency test, see the Running the latency tests section. - -The tests need to perform an environment configuration every time they are executed. This involves items such as creating SRI-OV node policies, performance profiles, or PTP profiles. Allowing the tests to configure an already configured cluster might affect the functionality of the cluster. Also, changes to configuration items such as SR-IOV node policy might result in the environment being temporarily unavailable until the configuration change is processed. - -[id="cnf-performing-end-to-end-tests-prerequisites_{context}"] -== Prerequisites - -* The test entrypoint is `/usr/bin/test-run.sh`. It runs both a setup test set and the real conformance test suite. The minimum requirement is to provide it with a kubeconfig file and its related `$KUBECONFIG` environment variable, mounted through a volume. - -* The tests assumes that a given feature is already available on the cluster in the form of an Operator, flags enabled on the cluster, or machine configs. - -* Some tests require a pre-existing machine config pool to append their changes to. This must be created on the cluster before running the tests. -+ -The default worker pool is `worker-cnf` and can be created with the following manifest: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool -metadata: - name: worker-cnf - labels: - machineconfiguration.openshift.io/role: worker-cnf -spec: - machineConfigSelector: - matchExpressions: - - { - key: machineconfiguration.openshift.io/role, - operator: In, - values: [worker-cnf, worker], - } - paused: false - nodeSelector: - matchLabels: - node-role.kubernetes.io/worker-cnf: "" ----- -+ -You can use the `ROLE_WORKER_CNF` variable to override the worker pool name: -+ -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig -e -ROLE_WORKER_CNF=custom-worker-pool registry.redhat.io/openshift4/cnf-tests-rhel8:v4.6 /usr/bin/test-run.sh ----- -+ -[NOTE] -==== -Currently, not all tests run selectively on the nodes belonging to the pool. -==== - -[id="cnf-performing-end-to-end-tests-running-the-tests_{context}"] -== Running the tests -Assuming the `kubeconfig` file is in the current folder, the command for running the test suite is: - ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig registry.redhat.io/openshift4/cnf-tests-rhel8:v4.6 /usr/bin/test-run.sh ----- - -This allows your `kubeconfig` file to be consumed from inside the running container. - -[id="cnf-performing-end-to-end-tests-running-the-latency_tests"] -=== Running the latency tests -In {product-title} {product-version}, you can also run latency tests from the CNF-test container. The latency test allows you to set a latency limit so that you can determine performance, throughput, and latency. - -The latency test runs the `oslat` tool, which is an open source program to detect OS level latency. For more information, see the Red Hat Knowledgebase solution link:https://access.redhat.com/solutions/5315541[How to measure OS and hardware latency on isolated CPUs?]. - -By default, the latency tests are disabled. To enable the latency test, you must add the `LATENCY_TEST_RUN` variable and set its value to `true`. For example, `LATENCY_TEST_RUN=true`. - -Additionally, you can set the following environment variables for latency tests: - -* `LATENCY_TEST_RUNTIME` - Specifies the amount of time (in seconds) that the latency test must run. -* `OSLAT_MAXIMUM_LATENCY` - Specifies the maximum latency (in microseconds) that is expected from all buckets during the `oslat` test run. - -To perform the latency tests, run the following command: - ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig -e LATENCY_TEST_RUN=true -e LATENCY_TEST_RUNTIME=600 -e OSLAT_MAXIMUM_LATENCY=20 registry.redhat.io/openshift4/cnf-tests-rhel8:v4.7 /usr/bin/test-run.sh ----- -[NOTE] -==== -You must run the latency test in discovery mode. For more information, see the Discovery mode section. -==== - -.Excerpt of a sample result of a 10-second latency test using the following command: -[source,terminal] ----- -[root@cnf12-installer ~]# podman run --rm -v $KUBECONFIG:/kubeconfig:Z -e PERF_TEST_PROFILE=worker-cnf-2 -e KUBECONFIG=/kubeconfig -e LATENCY_TEST_RUN=true -e LATENCY_TEST_RUNTIME=10 -e OSLAT_MAXIMUM_LATENCY=20 -e DISCOVERY_MODE=true registry.redhat.io/openshift4/cnf-tests-rhel8:v4.7 /usr/bin/test-run.sh --ginkgo.focus="Latency" -running /0_config.test -ginkgo.focus=Latency ----- -.Example output -[source, terminal] ----- -I1106 15:09:08.087085 7 request.go:621] Throttling request took 1.037172581s, request: GET:https://api.cnf12.kni.lab.eng.bos.redhat.com:6443/apis/autoscaling.openshift.io/v1?timeout=32s -Running Suite: Performance Addon Operator configuration - -Random Seed: 1604675347 -Will run 0 of 1 specs - -JUnit report was created: /unit_report_performance_config.xml - -Ran 0 of 1 Specs in 0.000 seconds -SUCCESS! -- 0 Passed | 0 Failed | 0 Pending | 1 Skipped -PASS -running /4_latency.test -ginkgo.focus=Latency -I1106 15:09:10.735795 23 request.go:621] Throttling request took 1.037276624s, request: GET:https://api.cnf12.kni.lab.eng.bos.redhat.com:6443/apis/certificates.k8s.io/v1?timeout=32s -Running Suite: Performance Addon Operator latency e2e tests - -Random Seed: 1604675349 -Will run 1 of 1 specs - -I1106 15:10:06.401180 23 nodes.go:86] found mcd machine-config-daemon-r78qc for node cnfdd8.clus2.t5g.lab.eng.bos.redhat.com -I1106 15:10:06.738120 23 utils.go:23] run command 'oc [exec -i -n openshift-machine-config-operator -c machine-config-daemon --request-timeout 30 machine-config-daemon-r78qc -- cat /rootfs/var/log/oslat.log]' (err=): - stdout= -Version: v0.1.7 - -Total runtime: 10 seconds -Thread priority: SCHED_FIFO:1 -CPU list: 3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50 -CPU for main thread: 2 -Workload: no -Workload mem: 0 (KiB) -Preheat cores: 48 - -Pre-heat for 1 seconds... -Test starts... -Test completed. - -Core: 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 -CPU Freq: 2096 2096 2096 2096 2096 2096 2096 2096 2096 2096 2096 2096 2096 2092 2096 2096 2096 2092 2092 2096 2096 2096 2096 2096 2096 2096 2096 2096 2096 2092 2096 2096 2092 2096 2096 2096 2096 2092 2096 2096 2096 2092 2096 2096 2096 2096 2096 2096 (Mhz) -... -Maximum: 3 4 3 3 3 3 3 3 4 3 3 3 3 4 3 3 3 3 3 4 3 3 3 3 3 3 3 3 3 4 3 3 3 3 3 3 3 4 3 3 3 3 3 4 3 3 3 4 (us) ----- - -[id="cnf-performing-end-to-end-tests-image-parameters_{context}"] -== Image parameters - -Depending on the requirements, the tests can use different images. There are two images used by the tests that can be changed using the following environment variables: - -* `CNF_TESTS_IMAGE` -* `DPDK_TESTS_IMAGE` - -For example, to change the `CNF_TESTS_IMAGE` with a custom registry run the following command: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig -e CNF_TESTS_IMAGE="custom-cnf-tests-image:latests" registry.redhat.io/openshift4/cnf-tests-rhel8:v4.7 /usr/bin/test-run.sh ----- - -[id="cnf-performing-end-to-end-tests-ginko-parameters_{context}"] -=== Ginkgo parameters - -The test suite is built upon the ginkgo BDD framework. This means that it accepts parameters for filtering or skipping tests. - -You can use the `-ginkgo.focus` parameter to filter a set of tests: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig registry.redhat.io/openshift4/cnf-tests-rhel8:v4.7 /usr/bin/test-run.sh -ginkgo.focus="performance|sctp" ----- - -You can run only the latency test using the `-ginkgo.focus` parameter. - -To run only the latency test, you must provide the `-ginkgo.focus` parameter and the `PERF_TEST_PROFILE` environment variable that contains the name of the performance profile that needs to be tested. For example: - -[source, terminal] ----- -$ docker run --rm -v $KUBECONFIG:/kubeconfig -e KUBECONFIG=/kubeconfig -e LATENCY_TEST_RUN=true -e LATENCY_TEST_RUNTIME=600 -e OSLAT_MAXIMUM_LATENCY=20 -e PERF_TEST_PROFILE= registry.redhat.io/openshift4/cnf-tests-rhel8:v4.7 /usr/bin/test-run.sh -ginkgo.focus="\[performance\]\[config\]|\[performance\]\ Latency\ Test" ----- - -[NOTE] -==== -There is a particular test that requires both SR-IOV and SCTP. Given the selective nature of the `focus` parameter, this test is triggered by only placing the `sriov` matcher. If the tests are executed against a cluster where SR-IOV is installed but SCTP is not, adding the `-ginkgo.skip=SCTP` parameter causes the tests to skip SCTP testing. -==== - -[id="cnf-performing-end-to-end-tests-available-features_{context}"] -=== Available features - -The set of available features to filter are: - -* `performance` -* `sriov` -* `ptp` -* `sctp` -* `xt_u32` -* `dpdk` - -[id="cnf-performing-end-to-end-tests-dry-run_{context}"] -== Dry run - -Use this command to run in dry-run mode. This is useful for checking what is in the test suite and provides output for all of the tests the image would run. - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig registry.redhat.io/openshift4/cnf-tests-rhel8:v4.7 /usr/bin/test-run.sh -ginkgo.dryRun -ginkgo.v ----- - -[id="cnf-performing-end-to-end-tests-disconnected-mode_{context}"] -== Disconnected mode - -The CNF tests image support running tests in a disconnected cluster, meaning a cluster that is not able to reach outer registries. This is done in two steps: - -. Performing the mirroring. - -. Instructing the tests to consume the images from a custom registry. - -[id="cnf-performing-end-to-end-tests-mirroring-images-to-custom-registry_{context}"] -=== Mirroring the images to a custom registry accessible from the cluster - -A `mirror` executable is shipped in the image to provide the input required by `oc` to mirror the images needed to run the tests to a local registry. - -Run this command from an intermediate machine that has access both to the cluster and to link:https://catalog.redhat.com/software/containers/explore[registry.redhat.io] over the Internet: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig registry.redhat.io/openshift4/cnf-tests-rhel8:v4.7 /usr/bin/mirror -registry my.local.registry:5000/ | oc image mirror -f - ----- - -Then, follow the instructions in the following section about overriding the registry used to fetch the images. - -[id="instruct-the-tests-to-consume-images-from-a-custom-registry_{context}"] -=== Instruct the tests to consume those images from a custom registry - -This is done by setting the `IMAGE_REGISTRY` environment variable: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig -e IMAGE_REGISTRY="my.local.registry:5000/" -e CNF_TESTS_IMAGE="custom-cnf-tests-image:latests" registry.redhat.io/openshift4/cnf-tests-rhel8:v4.7 /usr/bin/test-run.sh ----- - -[id="cnf-performing-end-to-end-tests-mirroring-to-cluster-internal-registry_{context}"] -=== Mirroring to the cluster internal registry - -{product-title} provides a built-in container image registry, which runs as a standard workload on the cluster. - -.Procedure - -. Gain external access to the registry by exposing it with a route: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io/cluster --patch '{"spec":{"defaultRoute":true}}' --type=merge ----- - -. Fetch the registry endpoint: -+ -[source,terminal] ----- -REGISTRY=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}') ----- - -. Create a namespace for exposing the images: -+ -[source,terminal] ----- -$ oc create ns cnftests ----- - -. Make that image stream available to all the namespaces used for tests. This is required to allow the tests namespaces to fetch the images from the `cnftests` image stream. -+ -[source,terminal] ----- -$ oc policy add-role-to-user system:image-puller system:serviceaccount:sctptest:default --namespace=cnftests ----- -+ -[source,terminal] ----- -$ oc policy add-role-to-user system:image-puller system:serviceaccount:cnf-features-testing:default --namespace=cnftests ----- -+ -[source,terminal] ----- -$ oc policy add-role-to-user system:image-puller system:serviceaccount:performance-addon-operators-testing:default --namespace=cnftests ----- -+ -[source,terminal] ----- -$ oc policy add-role-to-user system:image-puller system:serviceaccount:dpdk-testing:default --namespace=cnftests ----- -+ -[source,terminal] ----- -$ oc policy add-role-to-user system:image-puller system:serviceaccount:sriov-conformance-testing:default --namespace=cnftests ----- - -. Retrieve the docker secret name and auth token: -+ -[source,bash] ----- -SECRET=$(oc -n cnftests get secret | grep builder-docker | awk {'print $1'} -TOKEN=$(oc -n cnftests get secret $SECRET -o jsonpath="{.data['\.dockercfg']}" | base64 -d | jq '.["image-registry.openshift-image-registry.svc:5000"].auth') ----- - -. Write a `dockerauth.json` similar to this: -+ -[source,bash] ----- -echo "{\"auths\": { \"$REGISTRY\": { \"auth\": $TOKEN } }}" > dockerauth.json ----- - -. Do the mirroring: -+ -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig registry.redhat.io/openshift4/cnf-tests-rhel8:v4.6 /usr/bin/mirror -registry $REGISTRY/cnftests | oc image mirror --insecure=true -a=$(pwd)/dockerauth.json -f - ----- - -. Run the tests: -+ -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig -e IMAGE_REGISTRY=image-registry.openshift-image-registry.svc:5000/cnftests cnf-tests-local:latest /usr/bin/test-run.sh ----- - -[id="mirroring-different-set-of-images_{context}"] -=== Mirroring a different set of images - -.Procedure - -. The `mirror` command tries to mirror the u/s images by default. This can be overridden by passing a file with the following format to the image: -+ -[source,yaml] ----- -[ - { - "registry": "public.registry.io:5000", - "image": "imageforcnftests:4.7" - }, - { - "registry": "public.registry.io:5000", - "image": "imagefordpdk:4.7" - } -] ----- - -. Pass it to the `mirror` command, for example saving it locally as `images.json`. With the following command, the local path is mounted in `/kubeconfig` inside the container and that can be passed to the mirror command. -+ -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig registry.redhat.io/openshift4/cnf-tests-rhel8:v4.6 /usr/bin/mirror --registry "my.local.registry:5000/" --images "/kubeconfig/images.json" | oc image mirror -f - ----- - -[id="discovery-mode_{context}"] -== Discovery mode - -Discovery mode allows you to validate the functionality of a cluster without altering its configuration. Existing environment configurations are used for the tests. The tests attempt to find the configuration items needed and use those items to execute the tests. If resources needed to run a specific test are not found, the test is skipped, providing an appropriate message to the user. After the tests are finished, no cleanup of the pre-configured configuration items is done, and the test environment can be immediately used for another test run. - -Some configuration items are still created by the tests. These are specific items needed for a test to run; for example, a SR-IOV Network. These configuration items are created in custom namespaces and are cleaned up after the tests are executed. - -An additional bonus is a reduction in test run times. As the configuration items are already there, no time is needed for environment configuration and stabilization. - -To enable discovery mode, the tests must be instructed by setting the `DISCOVERY_MODE` environment variable as follows: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig:Z -e KUBECONFIG=/kubeconfig/kubeconfig -e -DISCOVERY_MODE=true registry.redhat.io/openshift-kni/cnf-tests /usr/bin/test-run.sh ----- - -[id="required-environment-config-prereqs_{context}"] -=== Required environment configuration prerequisites - -.SR-IOV tests - -Most SR-IOV tests require the following resources: - -* `SriovNetworkNodePolicy`. -* At least one with the resource specified by `SriovNetworkNodePolicy` being allocatable; a resource count of at least 5 is considered sufficient. - -Some tests have additional requirements: - -* An unused device on the node with available policy resource, with link state `DOWN` and not a bridge slave. -* A `SriovNetworkNodePolicy` with a MTU value of `9000`. - -.DPDK tests - -The DPDK related tests require: - -* A performance profile. -* A SR-IOV policy. -* A node with resources available for the SR-IOV policy and available with the `PerformanceProfile` node selector. - -.PTP tests - -* A slave `PtpConfig` (`ptp4lOpts="-s" ,phc2sysOpts="-a -r"`). -* A node with a label matching the slave `PtpConfig`. - -.SCTP tests - -* `SriovNetworkNodePolicy`. -* A node matching both the `SriovNetworkNodePolicy` and a `MachineConfig` that enables SCTP. - -.XT_U32 tests - -* A node with a machine config that enables XT_U32. - -.Performance Operator tests - -Various tests have different requirements. Some of them are: - -* A performance profile. -* A performance profile having `profile.Spec.CPU.Isolated = 1`. -* A performance profile having `profile.Spec.RealTimeKernel.Enabled == true`. -* A node with no huge pages usage. - -[id="limiting-nodes-used-during-tests_{context}"] -=== Limiting the nodes used during tests - -The nodes on which the tests are executed can be limited by specifying a `NODES_SELECTOR` environment variable. Any resources created by the test are then limited to the specified nodes. - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig:Z -e KUBECONFIG=/kubeconfig/kubeconfig -e -NODES_SELECTOR=node-role.kubernetes.io/worker-cnf registry.redhat.io/openshift-kni/cnf-tests /usr/bin/test-run.sh ----- - -[id="using-single-performance-profile_{context}"] -=== Using a single performance profile - -The resources needed by the DPDK tests are higher than those required by the performance test suite. To make the execution faster, the performance profile used by tests can be overridden using one that also serves the DPDK test suite. - -To do this, a profile like the following one can be mounted inside the container, and the performance tests can be instructed to deploy it. - -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: PerformanceProfile -metadata: - name: performance -spec: - cpu: - isolated: "4-15" - reserved: "0-3" - hugepages: - defaultHugepagesSize: "1G" - pages: - - size: "1G" - count: 16 - node: 0 - realTimeKernel: - enabled: true - nodeSelector: - node-role.kubernetes.io/worker-cnf: "" ----- - -To override the performance profile used, the manifest must be mounted inside the container and the tests must be instructed by setting the `PERFORMANCE_PROFILE_MANIFEST_OVERRIDE` parameter as follows: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig:Z -e KUBECONFIG=/kubeconfig/kubeconfig -e -PERFORMANCE_PROFILE_MANIFEST_OVERRIDE=/kubeconfig/manifest.yaml registry.redhat.io/openshift-kni/cnf-tests /usr/bin/test-run.sh ----- - -[id="disabling-performance-profile-cleanup_{context}"] -=== Disabling the performance profile cleanup - -When not running in discovery mode, the suite cleans up all the created artifacts and configurations. This includes the performance profile. - -When deleting the performance profile, the machine config pool is modified and nodes are rebooted. After a new iteration, a new profile is created. This causes long test cycles between runs. - -To speed up this process, set `CLEAN_PERFORMANCE_PROFILE="false"` to instruct the tests not to clean the performance profile. In this way, the next iteration will not need to create it and wait for it to be applied. - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig:Z -e KUBECONFIG=/kubeconfig/kubeconfig -e -CLEAN_PERFORMANCE_PROFILE="false" registry.redhat.io/openshift-kni/cnf-tests /usr/bin/test-run.sh ----- - -[id="cnf-performing-end-to-end-tests-troubleshooting_{context}"] -== Troubleshooting - -The cluster must be reached from within the container. You can verify this by running: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -e KUBECONFIG=/kubeconfig/kubeconfig -registry.redhat.io/openshift-kni/cnf-tests oc get nodes ----- - -If this does not work, it could be caused by spanning across DNS, MTU size, or firewall issues. - -[id="cnf-performing-end-to-end-tests-test-reports_{context}"] -== Test reports - -CNF end-to-end tests produce two outputs: a JUnit test output and a test failure report. - -[id="cnf-performing-end-to-end-tests-junit-test-output_{context}"] -=== JUnit test output - -A JUnit-compliant XML is produced by passing the `--junit` parameter together with the path where the report is dumped: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -v $(pwd)/junitdest:/path/to/junit -e KUBECONFIG=/kubeconfig/kubeconfig registry.redhat.io/openshift4/cnf-tests-rhel8:v4.6 /usr/bin/test-run.sh --junit /path/to/junit ----- - -[id="cnf-performing-end-to-end-tests-test-failure-report_{context}"] -=== Test failure report - -A report with information about the cluster state and resources for troubleshooting can be produced by passing the `--report` parameter with the path where the report is dumped: - -[source,terminal] ----- -$ docker run -v $(pwd)/:/kubeconfig -v $(pwd)/reportdest:/path/to/report -e KUBECONFIG=/kubeconfig/kubeconfig registry.redhat.io/openshift4/cnf-tests-rhel8:v4.6 /usr/bin/test-run.sh --report /path/to/report ----- - -[id="cnf-performing-end-to-end-tests-podman_{context}"] -=== A note on podman - -When executing podman as non root and non privileged, mounting paths can fail with "permission denied" errors. To make it work, append `:Z` to the volumes creation; for example, `-v $(pwd)/:/kubeconfig:Z` to allow podman to do the proper SELinux relabeling. - -[id="cnf-performing-end-to-end-tests-running-on-4-4_{context}"] -=== Running on {product-title} 4.4 - -With the exception of the following, the CNF end-to-end tests are compatible with {product-title} 4.4: - -[source,bash] ----- -[test_id:28466][crit:high][vendor:cnf-qe@redhat.com][level:acceptance] Should contain configuration injected through openshift-node-performance profile -[test_id:28467][crit:high][vendor:cnf-qe@redhat.com][level:acceptance] Should contain configuration injected through the openshift-node-performance profile ----- - -You can skip these tests by adding the `-ginkgo.skip “28466|28467"` parameter. - -[id="cnf-performing-end-to-end-tests-using-single-performance-profile_{context}"] -=== Using a single performance profile - -The DPDK tests require more resources than what is required by the performance test suite. To make the execution faster, you can override the performance profile used by the tests using a profile that also serves the DPDK test suite. - -To do this, use a profile like the following one that can be mounted inside the container, and the performance tests can be instructed to deploy it. - -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: PerformanceProfile -metadata: - name: performance -spec: - cpu: - isolated: "5-15" - reserved: "0-4" - hugepages: - defaultHugepagesSize: "1G" - pages: - -size: "1G" - count: 16 - node: 0 - realTimeKernel: - enabled: true - numa: - topologyPolicy: "best-effort" - nodeSelector: - node-role.kubernetes.io/worker-cnf: "" ----- - -To override the performance profile, the manifest must be mounted inside the container and the tests must be instructed by setting the `PERFORMANCE_PROFILE_MANIFEST_OVERRIDE`: - -[source,termal] ----- -$ docker run -v $(pwd)/:/kubeconfig:Z -e KUBECONFIG=/kubeconfig/kubeconfig -e PERFORMANCE_PROFILE_MANIFEST_OVERRIDE=/kubeconfig/manifest.yaml registry.redhat.io/openshift4/cnf-tests-rhel8:v4.6 /usr/bin/test-run.sh ----- - -[id="cnf-performing-end-to-end-tests-cluster-impacts_{context}"] -== Impacts on the cluster - -Depending on the feature, running the test suite could cause different impacts on the cluster. In general, only the SCTP tests do not change the cluster configuration. All of the other features have various impacts on the configuration. - -[id="cnf-performing-end-to-end-tests-sctp_{context}"] -=== SCTP - -SCTP tests just run different pods on different nodes to check connectivity. The impacts on the cluster are related to running simple pods on two nodes. - -[id="cnf-performing-end-to-end-tests-xtu32_{context}"] -=== XT_U32 - -XT_U32 tests run pods on different nodes to check iptables rule that utilize xt_u32. The impacts on the cluster are related to running simple pods on two nodes. - -[id="cnf-performing-end-to-end-tests-sr-iov_{context}"] -=== SR-IOV - -SR-IOV tests require changes in the SR-IOV network configuration, where the tests create and destroy different types of configuration. - -This might have an impact if existing SR-IOV network configurations are already installed on the cluster, because there may be conflicts depending on the priority of such configurations. - -At the same time, the result of the tests might be affected by existing configurations. - -[id="cnf-performing-end-to-end-tests-ptp_{context}"] -=== PTP - -PTP tests apply a PTP configuration to a set of nodes of the cluster. As with SR-IOV, this might conflict with any existing PTP configuration already in place, with unpredictable results. - -[id="cnf-performing-end-to-end-tests-performance_{context}"] -=== Performance - -Performance tests apply a performance profile to the cluster. The effect of this is changes in the node configuration, reserving CPUs, allocating memory huge pages, and setting the kernel packages to be realtime. If an existing profile named `performance` is already available on the cluster, the tests do not deploy it. - -[id="cnf-performing-end-to-end-tests-dpdk_{context}"] -=== DPDK - -DPDK relies on both performance and SR-IOV features, so the test suite configures both a performance profile and SR-IOV networks, so the impacts are the same as those described in SR-IOV testing and performance testing. - -[id="cnf-performing-end-to-end-tests-cleaning-up_{context}"] -=== Cleaning up - -After running the test suite, all the dangling resources are cleaned up. diff --git a/modules/cnf-provisioning-deploying-a-distributed-unit-(du)-manually.adoc b/modules/cnf-provisioning-deploying-a-distributed-unit-(du)-manually.adoc deleted file mode 100644 index 2657ade7e63a..000000000000 --- a/modules/cnf-provisioning-deploying-a-distributed-unit-(du)-manually.adoc +++ /dev/null @@ -1,112 +0,0 @@ -// CNF-950 4.7 Provisioning and deploying a Distributed Unit (DU) manually -// Module included in the following assemblies: -// -// *scalability_and_performance/cnf-provisioning-and-deploying-a-distributed-unit.adoc - -[id="cnf-provisioning-deploying-a-distributed-unit-(du)-manually_{context}"] -= Provisioning and deploying a distributed unit (DU) manually - -Radio access network (RAN) is composed of central units (CU), distributed units (DU), and radio units (RU). -RAN from the telecommunications standard perspective is shown below: - -image::135_OpenShift_Distributed_Unit_0121.svg[High level RAN overview] - -From the three components composing RAN, the CU and DU can be virtualized and implemented as cloud-native functions. - -The CU and DU split architecture is driven by real-time computing and networking requirements. A DU can be seen as a real-time part of a -telecommunication baseband unit. -One distributed unit may aggregate several cells. A CU can be seen as a non-realtime part of a baseband unit, aggregating -traffic from one or more distributed units. - -A cell in the context of a DU can be seen as a real-time application performing intensive digital signal processing, data transfer, -and algorithmic tasks. -Cells often use hardware acceleration (FPGA, GPU, eASIC) for DSP processing offload, but there are also software-only implementations -(FlexRAN), based on AVX-512 instructions. - -Running cell application on COTS hardware requires the following features to be enabled: - -* Real-time kernel -* CPU isolation -* NUMA awareness -* Huge pages memory management -* Precision timing synchronization using PTP -* AVX-512 instruction set (for Flexran and / or FPGA implementation) -* Additional features depending on the RAN Operator requirements - -Accessing hardware acceleration devices and high throughput network interface cards by virtualized software applications -requires use of SR-IOV and Passthrough PCI device virtualization. - -In addition to the compute and acceleration requirements, DUs operate on multiple internal and external networks. - -[id="cnf-manifest-structure_{context}"] -== The manifest structure - -The profile is built from one cluster specific folder and one or more site-specific folders. -This is done to address a deployment that includes remote worker nodes, with several sites belonging to the same cluster. - -The [`cluster-config`](ran-profile/cluster-config) directory contains performance and PTP customizations based upon -Operator deployments in [`deploy`](../feature-configs/deploy) folder. - -The [`site.1.fqdn`](site.1.fqdn) folder contains site-specific network customizations. - -[id="cnf-du-prerequisites_{context}"] -== Prerequisites - -Before installing the Operators and deploying the DU, perform the following steps. - -. Create a machine config pool for the RAN worker nodes. For example: -+ -[source,yaml] ----- -cat < node-role.kubernetes.io/worker-cnf="" ----- - -. Label the node as PTP slave (DU only): -+ -[source,terminal] ----- -$ oc label --overwrite node/ ptp/slave="" ----- - -[id="cnf-du-configuration-notes_{context}"] -== SR-IOV configuration notes - -The `SriovNetworkNodePolicy` object must be configured differently for different NIC models and placements. - -|==================== -|*Manufacturer* |*deviceType* |*isRdma* -|Intel |vfio-pci or netdevice |false -|Mellanox |netdevice |structure -|==================== - -In addition, when configuring the `nicSelector`, the `pfNames` value must match the intended interface name on the specific host. - -If there is a mixed cluster where some of the nodes are deployed with Intel NICs and some with Mellanox, several SR-IOV configurations can be -created with the same `resourceName`. The device plug-in will discover only the available ones and will put the capacity on the node accordingly. diff --git a/modules/cnf-provisioning-deploying-a-distributed-unit-manually.adoc b/modules/cnf-provisioning-deploying-a-distributed-unit-manually.adoc deleted file mode 100644 index 4a7b5bfa5499..000000000000 --- a/modules/cnf-provisioning-deploying-a-distributed-unit-manually.adoc +++ /dev/null @@ -1,112 +0,0 @@ -// CNF-950 4.7 Provisioning and deploying a Distributed Unit (DU) manually -// Module included in the following assemblies: -// -// *scalability_and_performance/cnf-provisioning-and-deploying-a-distributed-unit.adoc - -[id="cnf-provisioning-deploying-a-distributed-unit-manually_{context}"] -= Provisioning and deploying a distributed unit (DU) manually - -Radio access network (RAN) is composed of central units (CU), distributed units (DU), and radio units (RU). -RAN from the telecommunications standard perspective is shown below: - -image::135_OpenShift_Distributed_Unit_0121.svg[High level RAN overview] - -From the three components composing RAN, the CU and DU can be virtualized and implemented as cloud-native functions. - -The CU and DU split architecture is driven by real-time computing and networking requirements. A DU can be seen as a real-time part of a -telecommunication baseband unit. -One distributed unit may aggregate several cells. A CU can be seen as a non-realtime part of a baseband unit, aggregating -traffic from one or more distributed units. - -A cell in the context of a DU can be seen as a real-time application performing intensive digital signal processing, data transfer, -and algorithmic tasks. -Cells often use hardware acceleration (FPGA, GPU, eASIC) for DSP processing offload, but there are also software-only implementations -(FlexRAN), based on AVX-512 instructions. - -Running cell application on COTS hardware requires the following features to be enabled: - -* Real-time kernel -* CPU isolation -* NUMA awareness -* Huge pages memory management -* Precision timing synchronization using PTP -* AVX-512 instruction set (for Flexran and / or FPGA implementation) -* Additional features depending on the RAN Operator requirements - -Accessing hardware acceleration devices and high throughput network interface cards by virtualized software applications -requires use of SR-IOV and Passthrough PCI device virtualization. - -In addition to the compute and acceleration requirements, DUs operate on multiple internal and external networks. - -[id="cnf-manifest-structure_{context}"] -== The manifest structure - -The profile is built from one cluster specific folder and one or more site-specific folders. -This is done to address a deployment that includes remote worker nodes, with several sites belonging to the same cluster. - -The [`cluster-config`](ran-profile/cluster-config) directory contains performance and PTP customizations based upon -Operator deployments in [`deploy`](../feature-configs/deploy) folder. - -The [`site.1.fqdn`](site.1.fqdn) folder contains site-specific network customizations. - -[id="cnf-du-prerequisites_{context}"] -== Prerequisites - -Before installing the Operators and deploying the DU, perform the following steps. - -. Create a machine config pool for the RAN worker nodes. For example: -+ -[source,yaml] ----- -cat < node-role.kubernetes.io/worker-cnf="" ----- - -. Label the node as PTP slave (DU only): -+ -[source,terminal] ----- -$ oc label --overwrite node/ ptp/slave="" ----- - -[id="cnf-du-configuration-notes_{context}"] -== SR-IOV configuration notes - -The `SriovNetworkNodePolicy` object must be configured differently for different NIC models and placements. - -|==================== -|*Manufacturer* |*deviceType* |*isRdma* -|Intel |vfio-pci or netdevice |false -|Mellanox |netdevice |structure -|==================== - -In addition, when configuring the `nicSelector`, the `pfNames` value must match the intended interface name on the specific host. - -If there is a mixed cluster where some of the nodes are deployed with Intel NICs and some with Mellanox, several SR-IOV configurations can be -created with the same `resourceName`. The device plug-in will discover only the available ones and will put the capacity on the node accordingly. diff --git a/modules/cnf-provisioning-real-time-and-low-latency-workloads.adoc b/modules/cnf-provisioning-real-time-and-low-latency-workloads.adoc deleted file mode 100644 index 1fa005cae203..000000000000 --- a/modules/cnf-provisioning-real-time-and-low-latency-workloads.adoc +++ /dev/null @@ -1,236 +0,0 @@ -// CNF-489 Real time and low latency workload provisioning -// Module included in the following assemblies: -// -// *cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="cnf-provisioning-real-time-and-low-latency-workloads_{context}"] -= Provisioning real-time and low latency workloads - -Many industries and organizations need extremely high performance computing and might require low and predictable latency, especially in the financial and telecommunications industries. For these industries, with their unique requirements, {product-title} provides a Performance Addon Operator to implement automatic tuning to achieve low latency performance and consistent response time for {product-title} applications. - -The cluster administrator uses this performance profile configuration that makes it easier to make these changes in a more reliable way. The administrator can specify whether to update the kernel to kernel-rt (real-time), the CPUs that will be reserved for housekeeping, and the CPUs that are used for running the workloads. - -[id="performance-addon-operator-known-limitations-for-real-time_{context}"] -== Known limitations for real-time - -[NOTE] -==== -The RT kernel is only supported on worker nodes. -==== - -To fully utilize the real-time mode, the containers must run with elevated privileges. -See link:https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-capabilities-for-a-container[Set capabilities for a Container] for information on granting privileges. - -{product-title} restricts the allowed capabilities, so you might need to create a `SecurityContext` as well. - -[NOTE] -==== -This procedure is fully supported with bare metal installations using {op-system-first} systems. -==== - -Establishing the right performance expectations refers to the fact that the real-time kernel is not a panacea. Its objective is consistent, low-latency determinism offering predictable response times. There is some additional kernel overhead associated with the real-time kernel. This is due primarily to handling hardware interruptions in separately scheduled threads. The increased overhead in some workloads results in some degradation in overall throughput. The exact amount of degradation is very workload dependent, ranging from 0% to 30%. However, it is the cost of determinism. - -[id="performance-addon-operator-provisioning-worker-with-real-time-capabilities_{context}"] -== Provisioning a worker with real-time capabilities - -. Install Performance Addon Operator to the cluster. -. Optional: Add a node to the {product-title} cluster. -See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_for_real_time/8/html-single/tuning_guide/index#Setting_BIOS_parameters[Setting BIOS parameters]. -. Optional: Create a new machine config pool for real-time nodes. -. Add the node to the proper machine config pool, using node role labels. -+ -You must decide which nodes will be configured with real-time workloads. It could be all of the nodes in the cluster or a subset of the nodes. The Performance Addon Operator expects all of the nodes are part of a dedicated machine config pool. If you use all of the nodes, you just point the Performance Addon Operator to the worker node role label. If you use a subset, you must group the nodes into a new machine config pool. - -. Create the `PerformanceProfile` with the proper set of housekeeping cores and `realTimeKernel: enabled: true`. - -. Specify a node selector in the `PerformanceProfile`, as shown here: -+ -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: PerformanceProfile -metadata: - name: example-performanceprofile -spec: -... - realTimeKernel: - enabled: true - nodeSelector: - node-role.kubernetes.io/worker-rt: "" ----- - -. Verify that a matching machine config pool exists with a label: -+ -[source,bash] ----- -machineconfiguration.openshift.io/role=worker-rt ----- - -. {product-title} will start configuring the nodes, which might involve multiple reboots. Wait for the nodes to settle. This can take a long time depending on the specific hardware you use, but 20 minutes per node is expected. - -. Verify everything is working as expected. - -[id="performance-addon-operator-verifying-real-time-kernel-installation_{context}"] -== Verifying the real-time kernel installation - -Use this command to verify that the real-time kernel is installed: - -[source,terminal] ----- -$ oc get node -o wide ----- - -Note the worker with the role `worker-rt` that contains the string `4.18.0-211.rt5.23.el8.x86_64`: - -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION INTERNAL-IP -EXTERNAL-IP OS-IMAGE KERNEL-VERSION -CONTAINER-RUNTIME -cnf-worker-0.example.com Ready worker,worker-rt 5d17h v1.20.0 -128.66.135.107 Red Hat Enterprise Linux CoreOS 46.82.202008252340-0 (Ootpa) -4.18.0-211.rt5.23.el8.x86_64 cri-o://1.20.0-90.rhaos4.6.git4a0ac05.el8-rc.1 -[...] ----- - -[id="performance-addon-operator-creating-workload-that-works-in-real-time_{context}"] -== Creating a workload that works in real-time - -Use the following procedures for preparing a workload that will use real-time capabilities. - -.Procedure - -. Create a pod with a QoS class of `Guaranteed`. -. Optional: Disable CPU load balancing for DPDK. -. Assign a proper node selector. - -When writing your applications, follow the general recommendations described in -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_for_real_time/8/html-single/tuning_guide/index#chap-Application_Tuning_and_Deployment[Application tuning and deployment]. - -[id="performance-addon-operator-creating-pod-with-guaranteed-qos-class_{context}"] -== Creating a pod with a QoS class of `Guaranteed` - -Keep the following in mind when you create a pod that is given a QoS class of `Guaranteed`: - -* Every container in the pod must have a memory limit and a memory request, and they must be the same. -* Every container in the pod must have a CPU limit and a CPU request, and they must be the same. - -The following example shows the configuration file for a pod that has one container. The container has a memory limit and a memory request, both equal to 200 MiB. The container has a CPU limit and a CPU request, both equal to 1 CPU. - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: qos-demo - namespace: qos-example -spec: - containers: - - name: qos-demo-ctr - image: - resources: - limits: - memory: "200Mi" - cpu: "1" - requests: - memory: "200Mi" - cpu: "1" ----- - -. Create the pod: -+ -[source,terminal] ----- -$ oc apply -f qos-pod.yaml --namespace=qos-example ----- - -. View detailed information about the pod: -+ -[source,terminal] ----- -$ oc get pod qos-demo --namespace=qos-example --output=yaml ----- -+ -.Example output -[source,yaml] ----- -spec: - containers: - ... -status: - qosClass: Guaranteed ----- -+ -[NOTE] -==== -If a container specifies its own memory limit, but does not specify a memory request, {product-title} automatically assigns a memory request that matches the limit. Similarly, if a container specifies its own CPU limit, but does not specify a CPU request, {product-title} automatically assigns a CPU request that matches the limit. -==== - -[id="performance-addon-operator-disabling-cpu-load-balancing-for-dpdk_{context}"] -== Optional: Disabling CPU load balancing for DPDK - -Functionality to disable or enable CPU load balancing is implemented on the CRI-O level. The code under the CRI-O disables or enables CPU load balancing only when the following requirements are met. - -* The pod must use the `performance-` runtime class. You can get the proper name by looking at the status of the performance profile, as shown here: -+ -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: PerformanceProfile -... -status: - ... - runtimeClass: performance-manual ----- - -* The pod must have the `cpu-load-balancing.crio.io: true` annotation. - -The Performance Addon Operator is responsible for the creation of the high-performance runtime handler config snippet under relevant nodes and for creation of the high-performance runtime class under the cluster. It will have the same content as default runtime handler except it enables the CPU load balancing configuration functionality. - -To disable the CPU load balancing for the pod, the `Pod` specification must include the following fields: - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - ... - annotations: - ... - cpu-load-balancing.crio.io: "disable" - ... - ... -spec: - ... - runtimeClassName: performance- - ... ----- - -[NOTE] -==== -Only disable CPU load balancing when the CPU manager static policy is enabled and for pods with guaranteed QoS that use whole CPUs. Otherwise, disabling CPU load balancing can affect the performance of other containers in the cluster. -==== - -[id="performance-addon-operator-assigning-proper-node-selector_{context}"] -== Assigning a proper node selector - -The preferred way to assign a pod to nodes is to use the same node selector the performance profile used, as shown here: - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: example -spec: - [...] - nodeSelector: - node-role.kubernetes.io/worker-rt: "" ----- - -For more information, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.5/html-single/nodes/index#nodes-scheduler-node-selectors[Placing pods on specific nodes using node selectors]. - -[id="performance-addon-operator-scheduling-workload-onto-worker-with-real-time-capabilities_{context}"] -== Scheduling a workload onto a worker with real-time capabilities - -Use label selectors that match the nodes attached to the machine config pool that was configured for low latency by the Performance Addon Operator. For more information, see link:https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/[Assigning pods to nodes]. diff --git a/modules/cnf-tuning-nodes-for-low-latency-via-performanceprofile.adoc b/modules/cnf-tuning-nodes-for-low-latency-via-performanceprofile.adoc deleted file mode 100644 index 4bf3a1075b10..000000000000 --- a/modules/cnf-tuning-nodes-for-low-latency-via-performanceprofile.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// Epic CNF-78 (4.4) -// Epic CNF-422 (4.5) -// scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="cnf-tuning-nodes-for-low-latency-via-performanceprofile_{context}"] -= Tuning nodes for low latency with the performance profile - -The performance profile lets you control latency tuning aspects of nodes that belong to a certain machine config pool. After you specify your settings, the `PerformanceProfile` object is compiled into multiple objects that perform the actual node level tuning: - -* A `MachineConfig` file that manipulates the nodes. -* A `KubeletConfig` file that configures the Topology Manager, the CPU Manager, and the {product-title} nodes. -* The Tuned profile that configures the Node Tuning Operator. - -.Procedure - -. Prepare a cluster. - -. Create a machine config pool. - -. Install the Performance Addon Operator. - -. Create a performance profile that is appropriate for your hardware and topology. In the performance profile, you can specify whether to update the kernel to kernel-rt, allocation of huge pages, the CPUs that will be reserved for operating system housekeeping processes and CPUs that will be used for running the workloads. -+ -This is a typical performance profile: -+ -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: PerformanceProfile -metadata: - name: performance -spec: - cpu: - isolated: "5-15" - reserved: "0-4" - hugepages: - defaultHugepagesSize: "1G" - pages: - -size: "1G" - count: 16 - node: 0 - realTimeKernel: - enabled: true <1> - numa: <2> - topologyPolicy: "best-effort" - nodeSelector: - node-role.kubernetes.io/worker-cnf: "" ----- - -<1> Valid values are `true` or `false`. Setting the `true` value installs the real-time kernel on the node. -<2> Use this field to configure the topology manager policy. Valid values are `none` (default), `best-effort`, `restricted`, and `single-numa-node`. For more information, see link:https://kubernetes.io/docs/tasks/administer-cluster/topology-manager/#topology-manager-policies[Topology Manager Policies]. - -[id="cnf-partitioning-the-cpus_{context}"] -== Partitioning the CPUs - -You can reserve cores, or threads, for operating system housekeeping tasks from a single NUMA node and put your workloads on another NUMA node. The reason for this is that the housekeeping processes might be using the CPUs in a way that would impact latency sensitive processes running on those same CPUs. Keeping your workloads on a separate NUMA node prevents the processes from interfering with each other. Additionally, each NUMA node has its own memory bus that is not shared. - -Specify two groups of CPUs in the `spec` section: - -* `isolated` - Has the lowest latency. Processes in this group have no interruptions and so can, for example, reach much higher DPDK zero packet loss bandwidth. - -* `reserved` - The housekeeping CPUs. Threads in the reserved group tend to be very busy, so latency-sensitive applications should be run in the isolated group. See link:https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/#create-a-pod-that-gets-assigned-a-qos-class-of-guaranteed[Create a pod that gets assigned a QoS class of `Guaranteed`]. diff --git a/modules/cnf-understanding-low-latency.adoc b/modules/cnf-understanding-low-latency.adoc deleted file mode 100644 index 59d1992eea43..000000000000 --- a/modules/cnf-understanding-low-latency.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// Epic CNF-78 (4.4) -// * scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="cnf-understanding-low-latency_{context}"] -= Understanding low latency - -The emergence of Edge computing in the area of Telco / 5G plays a key role in -reducing latency and congestion problems and improving application performance. - -Simply put, latency determines how fast data (packets) moves from the sender to -receiver and returns to the sender after processing by the receiver. Obviously, -maintaining a network architecture with the lowest possible delay of latency -speeds is key for meeting the network performance requirements of 5G. Compared -to 4G technology, with an average latency of 50ms, 5G is targeted to reach -latency numbers of 1ms or less. This reduction in latency boosts wireless -throughput by a factor of 10. - -Many of the deployed applications in the Telco space require low latency that -can only tolerate zero packet loss. Tuning for zero packet loss helps mitigate -the inherent issues that degrade network performance. For more information, see -link:https://www.redhat.com/en/blog/tuning-zero-packet-loss-red-hat-openstack-platform-part-1[Tuning -for Zero Packet Loss in {rh-openstack-first}]. - -The Edge computing initiative also comes in to play for reducing latency rates. -Think of it as literally being on the edge of the cloud and closer to the user. -This greatly reduces the distance between the user and distant data centers, -resulting in reduced application response times and performance latency. - -Administrators must be able to manage their many Edge sites and local services -in a centralized way so that all of the deployments can run at the lowest -possible management cost. They also need an easy way to deploy and configure -certain nodes of their cluster for real-time low latency and high-performance -purposes. Low latency nodes are useful for applications such as Cloud-native -Network Functions (CNF) and Data Plane Development Kit (DPDK). - -{product-title} currently provides mechanisms to tune software on an -{product-title} cluster for real-time running and low latency (around <20 -microseconds reaction time). This includes tuning the kernel and {product-title} -set values, installing a kernel, and reconfiguring the machine. But this method -requires setting up four different Operators and performing many configurations -that, when done manually, is complex and could be prone to mistakes. - -{product-title} provides a Performance Addon Operator to implement automatic -tuning to achieve low latency performance for OpenShift applications. -The cluster administrator uses this performance profile configuration that makes -it easier to make these changes in a more reliable way. The administrator can -specify whether to update the kernel to kernel-rt, the CPUs that will be -reserved for housekeeping, and the CPUs that will be used for running the -workloads. diff --git a/modules/cnf-upgrading-performance-addon-operator.adoc b/modules/cnf-upgrading-performance-addon-operator.adoc deleted file mode 100644 index b2b2569825fd..000000000000 --- a/modules/cnf-upgrading-performance-addon-operator.adoc +++ /dev/null @@ -1,134 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="upgrading-performance-addon-operator_{context}"] -= Upgrading Performance Addon Operator - -You can manually upgrade to the next minor version of Performance Addon Operator and monitor the status of an update by using the web console. - -[id="about-upgrading-performance-addon-operator_{context}"] -== About upgrading Performance Addon Operator - -* You can upgrade to the next minor version of Performance Addon Operator by using the {product-title} web console to change the channel of your Operator subscription. - -* You can enable automatic z-stream updates during Performance Addon Operator installation. - -* Updates are delivered via the Marketplace Operator, which is deployed during {product-title} installation.The Marketplace Operator makes external Operators available to your cluster. - -* The amount of time an update takes to complete depends on your network connection. Most automatic updates complete within fifteen minutes. - -[id="how-performance-addon-operator-upgrades-affect-your-cluster_{context}"] -=== How Performance Addon Operator upgrades affect your cluster - -* Neither the low latency tuning nor huge pages are affected. - -* Updating the Operator should not cause any unexpected reboots. - -[id="upgrading-performance-addon-operator-to-minor-version_{context}"] -=== Upgrading Performance Addon Operator to the next minor version - -You can manually upgrade Performance Addon Operator to the next minor version by using the {product-title} web console to change the channel of your Operator subscription. - -.Prerequisites - -* Access to the cluster as a user with the cluster-admin role. - -.Procedure - -. Access the OpenShift web console and navigate to *Operators → Installed Operators*. - -. Click *Performance Addon Operator* to open the *Operator Details* page. - -. Click the *Subscription* tab to open the *Subscription Overview* page. - -. In the *Channel* pane, click the pencil icon on the right side of the version number to open the *Change Subscription Update Channel* window. - -. Select the next minor version. For example, if you want to upgrade to Performance Addon Operator 4.7, select *4.7*. - -. Click *Save*. - -. Check the status of the upgrade by navigating to *Operators → Installed Operators*. You can also check the status by running the following `oc` command: -+ -[source,terminal] ----- -$ oc get csv -n openshift-performance-addon-operator ----- - -[id="upgrading-performance-addon-operator-configured-for-a-specific-namespace_{context}"] -=== Upgrading Performance Addon Operator when previously installed to a specific namespace - -If you previously installed the Performance Addon Operator to a specific namespace on the cluster, for example `openshift-performance-addon-operator`, modify the `OperatorGroup` object to remove the `targetNamespaces` entry before upgrading. - -.Prerequisites - -* Install the {product-title} CLI (oc). -* Log in to the OpenShift cluster as a user with cluster-admin privileges. - -.Procedure - -. Edit the Performance Addon Operator `OperatorGroup` CR and remove the `spec` element that contains the `targetNamespaces` entry by running the following command: -+ -[source,terminal] ----- -$ oc patch operatorgroup -n openshift-performance-addon-operator openshift-performance-addon-operator --type json -p '[{ "op": "remove", "path": "/spec" }]' ----- - -. Wait until the Operator Lifecycle Manager (OLM) processes the change. -. Verify that the OperatorGroup CR change has been successfully applied. Check that the `OperatorGroup` CR `spec` element has been removed: -+ -[source,terminal] ----- -$ oc describe -n openshift-performance-addon-operator og openshift-performance-addon-operator ----- - -. Proceed with the Performance Addon Operator upgrade. -//. Proceed with the xref:../scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes#upgrading-performance-addon-operator_{context}[Performance Addon Operator upgrade]. - -[id="performance-addon-operator-monitoring-upgrade-status_{context}"] -== Monitoring upgrade status -The best way to monitor Performance Addon Operator upgrade status is to watch the `ClusterServiceVersion` (CSV) `PHASE`. -You can also monitor the CSV conditions in the web console or by running the `oc get csv` command. - -[NOTE] -==== -The `PHASE` and conditions values are approximations that are based on available information. -==== - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -* Install the OpenShift CLI (`oc`). - -.Procedure - -. Run the following command: -+ -[source,terminal] ----- -$ oc get csv ----- - -. Review the output, checking the `PHASE` field. For example: -+ -[source,terminal] ----- -VERSION REPLACES PHASE -4.7.0 performance-addon-operator.v4.6.0 Installing -4.6.0 Replacing ----- - -. Run `get csv` again to verify the output: -+ -[source,terminal] ----- -# oc get csv ----- -+ -.Example output -[source,terminal] ----- -NAME DISPLAY VERSION REPLACES PHASE -performance-addon-operator.v4.7.0 Performance Addon Operator 4.7.0 performance-addon-operator.v4.6.0 Succeeded ----- diff --git a/modules/cnf-use-device-interrupt-processing-for-isolated-cpus.adoc b/modules/cnf-use-device-interrupt-processing-for-isolated-cpus.adoc deleted file mode 100644 index 902d5ca0288f..000000000000 --- a/modules/cnf-use-device-interrupt-processing-for-isolated-cpus.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// CNF-802 Infrastructure-provided interrupt processing for guaranteed pod CPUs -// Module included in the following assemblies: -// -// *cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="use-device-interrupt-processing-for-isolated-cpus_{context}"] -= Upgrading the performance profile to use device interrupt processing - -When you upgrade the Performance Addon Operator performance profile custom resource definition (CRD) from v1 or v1alpha1 to v2, `globallyDisableIrqLoadBalancing` is set to `true` on existing profiles. - -[NOTE] -==== -When `globallyDisableIrqLoadBalancing` is set to `true`, device interrupts are processed across all CPUs as long as they don't belong to a guaranteed pod. -==== - -[id="pao_supported_api_versions_{context}"] -== Supported API Versions - -The Performance Addon Operator supports `v2`, `v1`, and `v1alpha1` for the performance profile `apiVersion` field. The v1 and v1alpha1 APIs are identical. The v2 API includes an optional boolean field `globallyDisableIrqLoadBalancing` with a default value of `false`. - -[id="upgrading_pao_api_from_v1alpha1_to_v1_{context}"] -=== Upgrading Performance Addon Operator API from v1alpha1 to v1 - -When upgrading Performance Addon Operator API version from v1alpha1 to v1, the v1alpha1 performance profiles are converted on-the-fly using a "None" Conversion strategy and served to the Performance Addon Operator with API version v1. - -[id="upgrading_pao_api_from_v1alpha1_to_v1_or_v2_{context}"] -=== Upgrading Performance Addon Operator API from v1alpha1 or v1 to v2 - -When upgrading from an older Performance Addon Operator API version, the existing v1 and v1alpha1 performance profiles are converted using a conversion webhook that injects the `globallyDisableIrqLoadBalancing` field with a value of `true`. diff --git a/modules/collecting-docker-logs-windows.adoc b/modules/collecting-docker-logs-windows.adoc deleted file mode 100644 index b38664a0796b..000000000000 --- a/modules/collecting-docker-logs-windows.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc - -[id="collecting-docker-logs-windows_{context}"] -= Collecting Docker logs for Windows containers - -The Windows Docker service does not stream its logs to stdout, but instead, logs to the event log for Windows. You can view the Docker event logs to investigate issues you think might be caused by the Windows Docker service. - -.Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You have created a Windows machine set. - -.Procedure - -. SSH into the Windows node and enter PowerShell: -+ -[source,terminal] ----- -C:\> powershell ----- - -. View the Docker logs by running the following command: -+ -[source,terminal] ----- -C:\> Get-EventLog -LogName Application -Source Docker ----- diff --git a/modules/collecting-kube-node-logs-windows.adoc b/modules/collecting-kube-node-logs-windows.adoc deleted file mode 100644 index f2615222def2..000000000000 --- a/modules/collecting-kube-node-logs-windows.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc - -[id="collecting-kube-node-logs-windows_{context}"] -= Collecting Kubernetes node logs for Windows containers - -Windows container logging works differently from Linux container logging; the Kubernetes node logs for Windows workloads are streamed to the `C:\k\logs` directory by default. Therefore, you must gather the Windows node logs from that directory. - -.Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You have created a Windows machine set. - -.Procedure - -. To view the logs under all directories in `C:\k\logs`, run the following command: -+ -[source,terminal] ----- -$ oc adm node-logs -l kubernetes.io/os=windows --path= \ - /ip-10-0-138-252.us-east-2.compute.internal containers \ - /ip-10-0-138-252.us-east-2.compute.internal hybrid-overlay \ - /ip-10-0-138-252.us-east-2.compute.internal kube-proxy \ - /ip-10-0-138-252.us-east-2.compute.internal kubelet \ - /ip-10-0-138-252.us-east-2.compute.internal pods ----- - -. You can now list files in the directories using the same command and view the individual log files. For example, to view the kubelet logs, run the following command: -+ -[source,terminal] ----- -$ oc adm node-logs -l kubernetes.io/os=windows --path=/kubelet/kubelet.log ----- diff --git a/modules/collecting-windows-application-event-logs.adoc b/modules/collecting-windows-application-event-logs.adoc deleted file mode 100644 index f57957179575..000000000000 --- a/modules/collecting-windows-application-event-logs.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc - -[id="collecting-windows-application-event-logs_{context}"] -= Collecting Windows application event logs - -The `Get-WinEvent` shim on the kubelet `logs` endpoint can be used to collect application event logs from Windows machines. - -.Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You have created a Windows machine set. - -.Procedure - -* To view logs from all applications logging to the event logs on the Windows machine, run: -+ -[source,terminal] ----- -$ oc adm node-logs -l kubernetes.io/os=windows --path=journal ----- -+ -The same command is executed when collecting logs with `oc adm must-gather`. -+ -Other Windows application logs from the event log can also be collected by specifying the respective service with a `-u` flag. For example, you can run the following command to collect logs for the docker runtime service: -+ -[source,terminal] ----- -$ oc adm node-logs -l kubernetes.io/os=windows --path=journal -u docker ----- diff --git a/modules/common-attributes.adoc b/modules/common-attributes.adoc index 514d91c9dcf4..423635c9a557 100644 --- a/modules/common-attributes.adoc +++ b/modules/common-attributes.adoc @@ -1,4 +1,4 @@ -// The {product-title} attribute provides the context-sensitive name of the relevant OpenShift distribution, for example, "OpenShift Container Platform" or "OKD". The {product-version} attribute provides the product version relative to the distribution, for example "4.8". +// The {product-title} attribute provides the context-sensitive name of the relevant OpenShift distribution, for example, "OpenShift Container Platform" or "OKD", The {product-version} attribute provides the product version relative to the distribution, for example "4.8". // {product-title} and {product-version} are parsed when AsciiBinder queries the _distro_map.yml file in relation to the base branch of a pull request. // See https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc#product-name-version for more information on this topic. // Other common attributes are defined in the following lines: @@ -9,10 +9,10 @@ :toc-title: :imagesdir: images :prewrap!: -:op-system-first: Red Hat Enterprise Linux CoreOS (RHCOS) +:op-system-first: Red{nbsp}Hat Enterprise Linux CoreOS (RHCOS) :op-system: RHCOS :op-system-base: RHEL -:op-system-base-full: Red Hat Enterprise Linux (RHEL) +:op-system-base-full: Red{nbsp}Hat Enterprise Linux (RHEL) ifdef::openshift-origin[] :op-system-first: Fedora CoreOS (FCOS) :op-system: FCOS @@ -21,14 +21,29 @@ ifdef::openshift-origin[] endif::[] :tsb-name: Template Service Broker :kebab: image:kebab.png[title="Options menu"] -:rh-openstack-first: Red Hat OpenStack Platform (RHOSP) +:rh-openstack-first: Red{nbsp}Hat OpenStack Platform (RHOSP) :rh-openstack: RHOSP -:cloud-redhat-com: Red Hat OpenShift Cluster Manager -:rh-storage-first: Red Hat OpenShift Container Storage +:cloud-redhat-com: Red{nbsp}Hat OpenShift Cluster Manager +:cloud-console: Red{nbsp}Hat Hybrid Cloud Console +:cloud-family: Red{nbsp}Hat Cloud +:ibm-power: IBM Power +:ibm-z: IBM Z +:ibm-cloud: IBM Cloud +:ibm-linuxone: IBM(R) LinuxONE +:rh-ibm-cloud: Red{nbsp}Hat OpenShift on IBM Cloud +:rh-storage-first: Red{nbsp}Hat OpenShift Container Storage :rh-storage: OpenShift Container Storage +:rh-rhacm-first: Red{nbsp}Hat Advanced Cluster Management (RHACM) +:rh-rhtas-first: Red{nbsp}Hat Trusted Artifact Signer (RHTAS) +:rh-rhacs-first: Red{nbsp}Hat Advanced Cluster Security for Kubernetes (RHACS) +:rh-rhacscs-first: Red{nbsp}Hat Advanced Cluster Security Cloud Service (RHACS Cloud Service) +:rh-rhacm: RHACM +:rh-rhdh-first: Red{nbsp}Hat Developer Hub (RHDH) +:rh-rhdh: RHDH +:rhdh-latest-version: 1.4 :sandboxed-containers-first: OpenShift sandboxed containers :sandboxed-containers: Sandboxed Containers Operator -:rh-virtualization-first: Red Hat Virtualization (RHV) +:rh-virtualization-first: Red{nbsp}Hat Virtualization (RHV) :rh-virtualization: RHV ifdef::openshift-origin[] :rh-virtualization-first: oVirt @@ -39,3 +54,22 @@ endif::[] :mtc-full: Migration Toolkit for Containers :mtc-version: 1.4 :mtc-version-z: 1.4.2 +:ocp: OpenShift Container Platform +:ocp-short: OCP +:osp: Red{nbsp}Hat OpenShift +:olm-first: Operator Lifecycle Manager (OLM) +:olm: OLM +:rhacs-version: 4.9.0 +:ocp-supported-version: 4.12 +:ocp-latest-version: 4.17 +:pipelines-shortname: OpenShift Pipelines +:plugin-acs-latest-version: 0.0.4 +:product-rosa: Red{nbsp}Hat OpenShift Service on AWS +:product-rosa-short: ROSA +:product-title: Red{nbsp}Hat Advanced Cluster Security for Kubernetes +:product-version: 4.6 +:product-title-short: RHACS +:product-title-managed: Red{nbsp}Hat Advanced Cluster Security Cloud Service +:product-title-managed-short: RHACS Cloud Service +// Following are used in modules/configure-policy-notifications.adoc +:toolname: PagerDuty \ No newline at end of file diff --git a/modules/common-search-queries.adoc b/modules/common-search-queries.adoc new file mode 100644 index 000000000000..3d99a6e99b6c --- /dev/null +++ b/modules/common-search-queries.adoc @@ -0,0 +1,103 @@ +// Module included in the following assemblies: +// +// * operating/search-filter.adoc +:_mod-docs-content-type: CONCEPT +[id="common-search-queries_{context}"] += Common search queries + +Here are some common search queries you can run with {product-title}. + +== Finding deployments that are affected by a specific CVE + +|=== +| Query | Example + +| `CVE:` +| `CVE:CVE-2018-11776` +|=== + +== Finding privileged running deployments + +|=== +| Query | Example + +| `Privileged:` +| `Privileged:true` +|=== + +== Finding deployments that have external network exposure + +|=== +| Query | Example + +| `Exposure Level:` +| `Exposure Level:External` +|=== + +== Finding deployments that are running specific processes + +|=== +| Query | Example + +| `Process Name:` +| `Process Name:bash` +|=== + +== Finding deployments that have serious but fixable vulnerabilities + +|=== +| Query | Example + +| `CVSS:` +| `CVSS:>=6` `Fixable:.*` +|=== + +== Finding deployments that use passwords exposed through environment variables + +|=== +| Query | Example + +| `Environment Key:` +| `Environment Key:r/.\*pass.*` +|=== + +== Finding running deployments that have particular software components in them + +|=== +| Query | Example + +| `Component:` +| `Component:libgpg-error` or `Component:sudo` +|=== + +== Finding users or groups + +Use Kubernetes link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/[Labels and Selectors], and link:https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/[Annotations] to attach metadata to your deployments. +You can then query based on the applied annotations and labels to identify individuals or groups. + +=== Finding who owns a particular deployment + +|=== +| Query | Example + +| `Deployment:` `Label:` or `Deployment:` `Annotation:` +| `Deployment:app-server` `Label:team=backend` +|=== + +=== Finding who is deploying images from public registries + +|=== +| Query | Example + +| `Image Registry:` `Label:` or `Image Registry:` `Annotation:` +| `Image Registry:docker.io` `Label:team=backend` +|=== + +=== Finding who is deploying into the default namespace + +|=== +| Query | Example + +| `Namespace:default` `Label:` or `Namespace:default` `Annotation:` +| `Namespace:default` `Label:team=backend` +|=== diff --git a/modules/compliance-anatomy.adoc b/modules/compliance-anatomy.adoc deleted file mode 100644 index 9c34f6af9c1b..000000000000 --- a/modules/compliance-anatomy.adoc +++ /dev/null @@ -1,342 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-troubleshooting.adoc - -[id="compliance-anatomy_{context}"] -= Anatomy of a scan - -The following sections outline the components and stages of Compliance Operator scans. - -[id="compliance-anatomy-compliance-sources_{context}"] -== Compliance sources -The compliance content is stored in `Profile` objects that are generated from a `ProfileBundle` object. The Compliance Operator creates a `ProfileBundle` object for the cluster and another for the cluster nodes. - -[source,terminal] ----- -$ oc get profilebundle.compliance ----- - -[source,terminal] ----- -$ oc get profile.compliance ----- - -The `ProfileBundle` objects are processed by deployments labeled with the `Bundle` name. To troubleshoot an issue with the `Bundle`, you can find the deployment and view logs of the pods in a deployment: - -[source,terminal] ----- -$ oc logs -lprofile-bundle=ocp4 -c profileparser ----- - -[source,terminal] ----- -$ oc get deployments,pods -lprofile-bundle=ocp4 ----- - -[source,terminal] ----- -$ oc logs pods/ ----- - -[source,terminal] ----- -$ oc describe pod/ -c profileparser ----- - -[id="compliance-anatomy-scan-setting-scan-binding-lifecycle_{context}"] -== The ScanSetting and ScanSettingBinding objects lifecycle and debugging -With valid compliance content sources, the high-level `ScanSetting` and `ScanSettingBinding` objects can be used to generate `ComplianceSuite` and `ComplianceScan` objects: - -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ScanSetting -metadata: - name: my-companys-constraints -debug: true -# For each role, a separate scan will be created pointing -# to a node-role specified in roles -roles: - - worker ---- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ScanSettingBinding -metadata: - name: my-companys-compliance-requirements -profiles: - # Node checks - - name: rhcos4-e8 - kind: Profile - apiGroup: compliance.openshift.io/v1alpha1 - # Cluster checks - - name: ocp4-e8 - kind: Profile - apiGroup: compliance.openshift.io/v1alpha1 -settingsRef: - name: my-companys-constraints - kind: ScanSetting - apiGroup: compliance.openshift.io/v1alpha1 ----- - -Both `ScanSetting` and `ScanSettingBinding` objects are handled by the same controller tagged with `logger=scansettingbindingctrl`. These objects have no status. Any issues are communicated in form of events: - -[source,terminal] ----- -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal SuiteCreated 9m52s scansettingbindingctrl ComplianceSuite openshift-compliance/my-companys-compliance-requirements created ----- - -Now a `ComplianceSuite` object is created. The flow continues to reconcile the newly created `ComplianceSuite`. - -[id="compliance-suite-lifecycle-debugging_{context}"] -== ComplianceSuite custom resource lifecycle and debugging -The `ComplianceSuite` CR is a wrapper around `ComplianceScan` CRs. The `ComplianceSuite` CR is handled by controller tagged with `logger=suitectrl`. -This controller handles creating scans from a suite, reconciling and aggregating individual Scan statuses into a single Suite status. If a suite is set to execute periodically, the `suitectrl` also handles creating a `CronJob` CR that re-runs the scans in the suite after the initial run is done: - -[source,terminal] ----- -$ oc get cronjobs ----- - -.Example output -[source,terminal] ----- -NAME SCHEDULE SUSPEND ACTIVE LAST SCHEDULE AGE - 0 1 * * * False 0 151m ----- - -For the most important issues, events are emitted. View them with `oc describe compliancesuites/`. The `Suite` objects also have a `Status` subresource that is updated when any of `Scan` objects that belong to this suite update their `Status` subresource. After all expected scans are created, control is passed to the scan controller. - -[id="compliance-scan-lifecycle-debugging_{context}"] -== ComplianceScan custom resource lifecycle and debugging -The `ComplianceScan` CRs are handled by the `scanctrl` controller. This is also where the actual scans happen and the scan results are created. Each scan goes through several phases: - -[id="compliance-scan-pending-phase_{context}"] -=== Pending phase -The scan is validated for correctness in this phase. If some parameters like storage size are invalid, the scan transitions to DONE with ERROR result, otherwise proceeds to the Launching phase. - -[id="compliance-scan-launching-phase_{context}"] -=== Launching phase -In this phase, several config maps that contain either environment for the scanner pods or directly the script that the scanner pods will be evaluating. List the config maps: - -[source,terminal] ----- -$ oc get cm -lcompliance.openshift.io/scan-name=rhcos4-e8-worker,complianceoperator.openshift.io/scan-script= ----- - -These config maps will be used by the scanner pods. If you ever needed to modify the scanner behavior, change the scanner debug level or print the raw results, modifying the config maps is the way to go. Afterwards, a persistent volume claim is created per scan to store the raw ARF results: - -[source,terminal] ----- -$ oc get pvc -lcompliance.openshift.io/scan-name= ----- - -The PVCs are mounted by a per-scan `ResultServer` deployment. A `ResultServer` is a simple HTTP server where the individual scanner pods upload the full ARF results to. Each server can run on a different node. The full ARF results might be very large and you cannot presume that it would be possible to create a volume that could be mounted from multiple nodes at the same time. After the scan is finished, the `ResultServer` deployment is scaled down. The PVC with the raw results can be mounted from another custom pod and the results can be fetched or inspected. The traffic between the scanner pods and the `ResultServer` is protected by mutual TLS protocols. - -Finally, the scanner pods are launched in this phase; one scanner pod for a `Platform` scan instance and one scanner pod per matching node for a `node` scan instance. The per-node pods are labeled with the node name. Each pod is always labeled with the `ComplianceScan` name: - -[source,terminal] ----- -$ oc get pods -lcompliance.openshift.io/scan-name=rhcos4-e8-worker,workload=scanner --show-labels ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE LABELS -rhcos4-e8-worker-ip-10-0-169-90.eu-north-1.compute.internal-pod 0/2 Completed 0 39m compliance.openshift.io/scan-name=rhcos4-e8-worker,targetNode=ip-10-0-169-90.eu-north-1.compute.internal,workload=scanner -At this point, the scan proceeds to the Running phase. ----- - -[id="compliance-scan-running-phase_{context}"] -=== Running phase -The running phase waits until the scanner pods finish. The following terms and processes are in use in the running phase: - -* *init container*: There is one init container called `content-container`. It runs the *contentImage* container and executes a single command that copies the *contentFile* to the `/content` directory shared with the other containers in this pod. - -* *scanner*: This container runs the scan. For node scans, the container mounts the node filesystem as `/host` and mounts the content delivered by the init container. The container also mounts the `entrypoint` `ConfigMap` created in the Launching phase and executes it. The default script in the entrypoint `ConfigMap` executes OpenSCAP and stores the result files in the `/results` directory shared between the pod's containers. Logs from this pod can be viewed to determine what the OpenSCAP scanner checked. More verbose output can be viewed with the `debug` flag. - -* *logcollector*: The logcollector container waits until the scanner container finishes. Then, it uploads the full ARF results to the `ResultServer` and separately uploads the XCCDF results along with scan result and OpenSCAP result code as a `ConfigMap.` These result config maps are labeled with the scan name (`compliance.openshift.io/scan-name=`): -+ -[source,terminal] ----- -$ oc describe cm/rhcos4-e8-worker-ip-10-0-169-90.eu-north-1.compute.internal-pod ----- -+ -.Example output -[source,terminal] ----- - Name: rhcos4-e8-worker-ip-10-0-169-90.eu-north-1.compute.internal-pod - Namespace: openshift-compliance - Labels: compliance.openshift.io/scan-name-scan=rhcos4-e8-worker - complianceoperator.openshift.io/scan-result= - Annotations: compliance-remediations/processed: - compliance.openshift.io/scan-error-msg: - compliance.openshift.io/scan-result: NON-COMPLIANT - OpenSCAP-scan-result/node: ip-10-0-169-90.eu-north-1.compute.internal - - Data - ==== - exit-code: - ---- - 2 - results: - ---- - - ... - ----- - -Scanner pods for `Platform` scans are similar, except: - -* There is one extra init container called `api-resource-collector` that reads the OpenSCAP content provided by the content-container init, container, figures out which API resources the content needs to examine and stores those API resources to a shared directory where the `scanner` container would read them from. - -* The `scanner` container does not need to mount the host file system. - -When the scanner pods are done, the scans move on to the Aggregating phase. - -[id="compliance-scan-aggregating-phase_{context}"] -=== Aggregating phase -In the aggregating phase, the scan controller spawns yet another pod called the aggregator pod. Its purpose it to take the result `ConfigMap` objects, read the results and for each check result create the corresponding Kubernetes object. If the check failure can be automatically remediated, a `ComplianceRemediation` object is created. To provide human-readable metadata for the checks and remediations, the aggregator pod also mounts the OpenSCAP content using an init container. - -When a config map is processed by an aggregator pod, it is labeled the `compliance-remediations/processed` label. The result of this phase are `ComplianceCheckResult` objects: - -[source,terminal] ----- -$ oc get compliancecheckresults -lcompliance.openshift.io/scan-name=rhcos4-e8-worker ----- - -.Example output -[source,terminal] ----- -NAME STATUS SEVERITY -rhcos4-e8-worker-accounts-no-uid-except-zero PASS high -rhcos4-e8-worker-audit-rules-dac-modification-chmod FAIL medium ----- -and `ComplianceRemediation` objects: - -[source,terminal] ----- -$ oc get complianceremediations -lcompliance.openshift.io/scan-name=rhcos4-e8-worker ----- - -.Example output -[source,terminal] ----- -NAME STATE -rhcos4-e8-worker-audit-rules-dac-modification-chmod NotApplied -rhcos4-e8-worker-audit-rules-dac-modification-chown NotApplied -rhcos4-e8-worker-audit-rules-execution-chcon NotApplied -rhcos4-e8-worker-audit-rules-execution-restorecon NotApplied -rhcos4-e8-worker-audit-rules-execution-semanage NotApplied -rhcos4-e8-worker-audit-rules-execution-setfiles NotApplied ----- - -After these CRs are created, the aggregator pod exits and the scan moves on to the Done phase. - -[id="compliance-scan-done-phase_{context}"] -=== Done phase -In the final scan phase, the scan resources are cleaned up if needed and the `ResultServer` deployment is either scaled down (if the scan was one-time) or deleted if the scan is continuous; the next scan instance would then recreate the deployment again. - -It is also possible to trigger a re-run of a scan in the Done phase by annotating it: - -[source,terminal] ----- -$ oc annotate compliancescans/ compliance.openshift.io/rescan= ----- - -After the scan reaches the Done phase, nothing else happens on its own unless the remediations are set to be applied automatically with `autoApplyRemediations: true`. The {product-title} administrator would now review the remediations and apply them as needed. If the remediations are set to be applied automatically, the `ComplianceSuite` controller takes over in the Done phase, pauses the machine config pool to which the scan maps to and applies all the remediations in one go. If a remediation is applied, the `ComplianceRemediation` controller takes over. - -[id="compliance-remediation-lifecycle-debugging_{context}"] -== ComplianceRemediation controller lifecycle and debugging -The example scan has reported some findings. One of the remediations can be enabled by toggling its `apply` attribute to `true`: - -[source,terminal] ----- -$ oc patch complianceremediations/rhcos4-e8-worker-audit-rules-dac-modification-chmod --patch '{"spec":{"apply":true}}' --type=merge ----- - -The `ComplianceRemediation` controller (`logger=remediationctrl`) reconciles the modified object. The result of the reconciliation is change of status of the remediation object that is reconciled, but also a change of the rendered per-suite `MachineConfig` object that contains all the applied remediations. - -The `MachineConfig` object always begins with `75-` and is named after the scan and the suite: - -[source,terminal] ----- -$ oc get mc | grep 75- ----- - -.Example output -[source,terminal] ----- -75-rhcos4-e8-worker-my-companys-compliance-requirements 2.2.0 2m46s ----- - -The remediations the `mc` currently consists of are listed in the machine config's annotations: - -[source,terminal] ----- -$ oc describe mc/75-rhcos4-e8-worker-my-companys-compliance-requirements ----- - -.Example output -[source,terminal] ----- -Name: 75-rhcos4-e8-worker-my-companys-compliance-requirements -Labels: machineconfiguration.openshift.io/role=worker -Annotations: remediation/rhcos4-e8-worker-audit-rules-dac-modification-chmod: ----- - -The `ComplianceRemediation` controller's algorithm works like this: - -* All currently applied remediations are read into an initial remediation set. -* If the reconciled remediation is supposed to be applied, it is added to the set. -* A `MachineConfig` object is rendered from the set and annotated with names of remediations in the set. If the set is empty (the last remediation was unapplied), the rendered `MachineConfig` object is removed. -* If and only if the rendered machine config is different from the one already applied in the cluster, the applied MC is updated (or created, or deleted). -* Creating or modifying a `MachineConfig` object triggers a reboot of nodes that match the `machineconfiguration.openshift.io/role` label - see the Machine Config Operator documentation for more details. - -The remediation loop ends once the rendered machine config is updated, if needed, and the reconciled remediation object status is updated. In our case, applying the remediation would trigger a reboot. After the reboot, annotate the scan to re-run it: - -[source,terminal] ----- -$ oc annotate compliancescans/ compliance.openshift.io/rescan= ----- - -The scan will run and finish. Check for the remediation to pass: - -[source,terminal] ----- -$ oc get compliancecheckresults/rhcos4-e8-worker-audit-rules-dac-modification-chmod ----- - -.Example output -[source,terminal] ----- -NAME STATUS SEVERITY -rhcos4-e8-worker-audit-rules-dac-modification-chmod PASS medium ----- - -[id="compliance-operator-useful-labels_{context}"] -== Useful labels - -Each pod that is spawned by the Compliance Operator is labeled specifically with the scan it belongs to and the work it does. The scan identifier is labeled with the `compliance.openshift.io/scan-name` label. The workload identifier is labeled with the `workload` label. - -The Compliance Operator schedules the following workloads: - -* *scanner*: Performs the compliance scan. - -* *resultserver*: Stores the raw results for the compliance scan. - -* *aggregator*: Aggregates the results, detects inconsistencies and outputs result objects (checkresults and remediations). - -* *suitererunner*: Will tag a suite to be re-run (when a schedule is set). - -* *profileparser*: Parses a datastream and creates the appropriate profiles, rules and variables. - -When debugging and logs are required for a certain workload, run: - -[source,terminal] ----- -$ oc logs -l workload= -c ----- diff --git a/modules/compliance-apply-remediations-from-scans.adoc b/modules/compliance-apply-remediations-from-scans.adoc deleted file mode 100644 index c7d1d27f64f7..000000000000 --- a/modules/compliance-apply-remediations-from-scans.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-advanced.adoc - -[id="installing-compliance-operator-cli_{context}"] -= Applying remediations generated by suite scans - -Although you can use the `autoApplyRemediations` boolean parameter in a `ComplianceSuite` object, you can alternatively annotate the object with `compliance.openshift.io/apply-remediations`. This allows the Operator to apply all of the created remediations. - -.Procedure - -* Apply the `compliance.openshift.io/apply-remediations` annotation by running: - -[source,terminal] ----- -$ oc annotate compliancesuites/ compliance.openshift.io/apply-remediations= ----- diff --git a/modules/compliance-applying.adoc b/modules/compliance-applying.adoc deleted file mode 100644 index 966d0af2f823..000000000000 --- a/modules/compliance-applying.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-remediation.adoc - -[id="compliance-applying_{context}"] -= Applying a remediation - -The boolean attribute `spec.apply` controls whether the remediation should be applied by the Compliance Operator. You can apply the remediation by setting the attribute to `true`: - -[source,terminal] ----- -$ oc patch complianceremediations/-sysctl-net-ipv4-conf-all-accept-redirects --patch '{"spec":{"apply":true}}' --type=merge ----- - -After the Compliance Operator processes the applied remediation, the `status.ApplicationState` attribute would change to *Applied* or to *Error* if incorrect. When a machine config remediation is applied, that remediation along with all other applied remediations are rendered into a `MachineConfig` object named `75-$scan-name-$suite-name`. That `MachineConfig` object is subsequently rendered by the Machine Config Operator and finally applied to all the nodes in a machine config pool by an instance of the machine control daemon running on each node. - -Note that when the Machine Config Operator applies a new `MachineConfig` object to nodes in a pool, all the nodes belonging to the pool are rebooted. This might be inconvenient when applying multiple remediations, each of which re-renders the composite `75-$scan-name-$suite-name` `MachineConfig` object. To prevent applying the remediation immediately, you can pause the machine config pool by setting the `.spec.paused` attribute of a `MachineConfigPool` object to `true`. - -The Compliance Operator can apply remediations automatically. Set `autoApplyRemediations: true` in the `ScanSetting` top-level object. - -[WARNING] -==== -Applying remediations automatically should only be done with careful consideration. -==== diff --git a/modules/compliance-assessment-and-reporting-by-using-rhacs.adoc b/modules/compliance-assessment-and-reporting-by-using-rhacs.adoc new file mode 100644 index 000000000000..79975448dae0 --- /dev/null +++ b/modules/compliance-assessment-and-reporting-by-using-rhacs.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/compliance-feature-overview.adoc + +:_mod-docs-content-type: CONCEPT +[id="compliance-assessment-and-reporting-by-using-rhacs_{context}"] += Compliance assessment and reporting by using RHACS + +On the dashboard page, you can assess and report on the compliance of your containerized infrastructure and workloads with the applicable technical controls from a range of security and regulatory frameworks. + +You can run out-of-the-box compliance scans based on the following industry standards: + +* *Center for Internet Security (CIS) Benchmarks* for *Kubernetes* +* *Health Insurance Portability and Accountability Act* (HIPAA) +* *National Institute of Standards and Technology (NIST) Special Publication 800-190* +* *NIST Special Publication 800-53* +* *Payment Card Industry Data Security Standard* (PCI DSS) +* *OpenShift Compliance Operator Profiles* ++ +The Compliance Operator evaluates the compliance of both the {ocp} Kubernetes API resources and the nodes running the cluster. There are several profiles available as part of the Compliance Operator installation. ++ +For more information about the available profiles, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-latest-version}/html-single/security_and_compliance/index#compliance-operator-supported-profiles[Supported compliance profiles]. + +By scanning your environment based on these standards, you can: + +* Evaluate your infrastructure for regulatory compliance. +* Harden your Kubernetes orchestrator. +* Understand and manage the overall security posture of your environment. +* Get a detailed overview of the compliance status of clusters, namespaces, and nodes. \ No newline at end of file diff --git a/modules/compliance-auto-update-remediations.adoc b/modules/compliance-auto-update-remediations.adoc deleted file mode 100644 index 9ab51cc5e195..000000000000 --- a/modules/compliance-auto-update-remediations.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-advanced.adoc - -[id="automatically-update-remediations_{context}"] -= Automatically update remediations - -In some cases, a scan with newer content might mark remediations as `OUTDATED`. As an administrator, you can apply the `compliance.openshift.io/remove-outdated` annotation to apply new remediations and remove the outdated ones. - -.Procedure - -* Apply the `compliance.openshift.io/remove-outdated` annotation: - -[source,terminal] ----- -$ oc annotate compliancesuites/ compliance.openshift.io/remove-outdated= ----- - -Alternatively, set the `autoUpdateRemediations` flag in a `ScanSetting` or `ComplianceSuite` object to update the remediations automatically. diff --git a/modules/compliance-custom-storage.adoc b/modules/compliance-custom-storage.adoc deleted file mode 100644 index ccb7299dd930..000000000000 --- a/modules/compliance-custom-storage.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-advanced.adoc - -[id="compliance-custom-storage_{context}"] -= Setting custom storage size for results -While the custom resources such as `ComplianceCheckResult` represent an aggregated result of one check across all scanned nodes, it can be useful to review the raw results as produced by the scanner. The raw results are produced in the ARF format and can be large (tens of megabytes per node), it is impractical to store them in a Kubernetes resource backed by the `etcd` key-value store. Instead, every scan creates a persistent volume (PV) which defaults to 1GB size. Depending on your environment, you may want to increase the PV size accordingly. This is done using the `rawResultStorage.size` attribute that is exposed in both the `ScanSetting` and `ComplianceScan` resources. - -A related parameter is `rawResultStorage.rotation` which controls how many scans are retained in the PV before the older scans are rotated. The default value is 3, setting the rotation policy to 0 disables the rotation. Given the default rotation policy and an estimate of 100MB per a raw ARF scan report, you can calculate the right PV size for your environment. - -[id="using-custom-result-storage-values_{context}"] -== Using custom result storage values -Because {product-title} can be deployed in a variety of public clouds or bare metal, the Compliance Operator cannot determine available storage configurations. By default, the Compliance Operator will try to create the PV for storing results using the default storage class of the cluster, but a custom storage class can be configured using the `rawResultStorage.StorageClassName` attribute. - -[IMPORTANT] -==== -If your cluster does not specify a default storage class, this attribute must be set. -==== - -Configure the `ScanSetting` custom resource to use a standard storage class and create persistent volumes that are 10GB in size and keep the last 10 results: - -.Example `ScanSetting` CR - -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ScanSetting -metadata: - name: default - namespace: openshift-compliance -rawResultStorage: - storageClassName: standard - rotation: 10 - size: 10Gi -roles: -- worker -- master -scanTolerations: -- effect: NoSchedule - key: node-role.kubernetes.io/master - operator: Exists -schedule: '0 1 * * *' ----- diff --git a/modules/compliance-dashboard-overview.adoc b/modules/compliance-dashboard-overview.adoc new file mode 100644 index 000000000000..571273c4feea --- /dev/null +++ b/modules/compliance-dashboard-overview.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: CONCEPT +[id="compliance-dashboard-overview_{context}"] += Compliance dashboard overview + +After you have performed a compliance scan, the compliance dashboard displays the results as the compliance status for your environment. You can view compliance violations directly from the dashboard. To find out if your environment is compliant against specific benchmarks, filter the detailed view and drill down into the compliance standards. + +You can use shortcuts to check the compliance status of clusters, namespaces, and nodes, which are located at the upper right of your compliance dashboard. Clicking these shortcuts, you can view the compliance snapshot and generate reports on the overall compliance of your clusters, namespaces, or nodes. \ No newline at end of file diff --git a/modules/compliance-filtering-failed-results.adoc b/modules/compliance-filtering-failed-results.adoc deleted file mode 100644 index 0378bf8589c4..000000000000 --- a/modules/compliance-filtering-failed-results.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-remediation.adoc - -[id="filtering-failed-compliance-check-results_{context}"] -= Filters for failed compliance check results - -By default, the `ComplianceCheckResult` objects are labeled with several useful labels that allow you to query the checks and decide on the next steps after the results are generated. - -List checks that belong to a specific suite: - -[source,terminal] ----- -$ oc get compliancecheckresults -l compliance.openshift.io/suite=example-compliancesuite ----- - -List checks that belong to a specific scan: - -[source,terminal] ----- -$ oc get compliancecheckresults -l compliance.openshift.io/scan=example-compliancescan ----- - -Not all `ComplianceCheckResult` objects create `ComplianceRemediation` objects. Only `ComplianceCheckResult` objects that can be remediated automatically do. A `ComplianceCheckResult` object has a related remediation if it is labeled with the `compliance.openshift.io/automated-remediation` label. The name of the remediation is the same as the name of the check. - -List all failing checks that can be remediated automatically: - -[source,terminal] ----- -$ oc get compliancecheckresults -l 'compliance.openshift.io/check-status=FAIL,compliance.openshift.io/automated-remmediation ----- - -List all failing checks that must be remediated manually: - -[source,terminal] ----- -$ oc get compliancecheckresults -l 'compliance.openshift.io/check-status=FAIL,!compliance.openshift.io/automated-remediation ----- - -The manual remediation steps are typically stored in the `description` attribute in the `ComplianceCheckResult` object. diff --git a/modules/compliance-imagestreams.adoc b/modules/compliance-imagestreams.adoc deleted file mode 100644 index ec23b302e998..000000000000 --- a/modules/compliance-imagestreams.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-manage.adoc - -[id="compliance-imagestreams_{context}"] -= Using image streams - -The `contentImage` reference points to a valid `ImageStreamTag`, and the Compliance Operator ensures that the content stays up to date automatically. - -[NOTE] -==== -`ProfileBundle` objects also accept `ImageStream` references. -==== - -.Example image stream -[source,terminal] ----- -$ oc get is -n openshift-compliance ----- - -.Example output -[source,terminal] ----- -NAME IMAGE REPOSITORY TAGS UPDATED -openscap-ocp4-ds image-registry.openshift-image-registry.svc:5000/openshift-compliance/openscap-ocp4-ds latest 32 seconds ago ----- - -.Procedure -. Ensure that the lookup policy is set to local: -+ -[source,terminal] ----- -$ oc patch is openscap-ocp4-ds \ - -p '{"spec":{"lookupPolicy":{"local":true}}}' \ - --type=merge - imagestream.image.openshift.io/openscap-ocp4-ds patched - -n openshift-compliance ----- - -. Use the name of the `ImageStreamTag` for the `ProfileBundle` by retrieving the `istag` name: -+ -[source,terminal] ----- -$ oc get istag -n openshift-compliance ----- -+ -.Example output -[source,terminal] ----- -NAME IMAGE REFERENCE UPDATED -openscap-ocp4-ds:latest image-registry.openshift-image-registry.svc:5000/openshift-compliance/openscap-ocp4-ds@sha256:46d7ca9b7055fe56ade818ec3e62882cfcc2d27b9bf0d1cbae9f4b6df2710c96 3 minutes ago ----- - -. Create the `ProfileBundle`: -+ -[source,terminal] ----- -$ cat << EOF | oc create -f - -apiVersion: compliance.openshift.io/v1alpha1 -kind: ProfileBundle -metadata: - name: mybundle - spec: - contentImage: openscap-ocp4-ds:latest - contentFile: ssg-rhcos4-ds.xml -EOF ----- - -This `ProfileBundle` will track the image and any changes that are applied to it, such as updating the tag to point to a different hash, will immediately be reflected in the `ProfileBundle`. diff --git a/modules/compliance-inconsistent.adoc b/modules/compliance-inconsistent.adoc deleted file mode 100644 index 1e6d4755f96c..000000000000 --- a/modules/compliance-inconsistent.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-remediation.adoc - -[id="compliance-inconsistent_{context}"] -= Inconsistent remediations -The `ScanSetting` object lists the node roles that the compliance scans generated from the `ScanSetting` or `ScanSettingBinding` objects would scan. Each node role usually maps to a machine config pool. - -[IMPORTANT] -==== -It is expected that all machines in a machine config pool are identical and all scan results from the nodes in a pool should be identical. -==== - -If some of the results are different from others, the Compliance Operator flags a `ComplianceCheckResult` object where some of the nodes will report as `INCONSISTENT`. All `ComplianceCheckResult` objects are also labeled with `compliance.openshift.io/inconsistent-check`. - -Because the number of machines in a pool might be quite large, the Compliance Operator attempts to find the most common state and list the nodes that differ from the common state. The most common state is stored in the `compliance.openshift.io/most-common-status` annotation and the annotation `compliance.openshift.io/inconsistent-source` contains pairs of `hostname:status` of check statuses that differ from the most common status. If no common state can be found, all the `hostname:status` pairs are listed in the `compliance.openshift.io/inconsistent-source annotation`. - -If possible, a remediation is still created so that the cluster can converge to a compliant status. However, this might not always be possible and correcting the difference between nodes must be done manually. The compliance scan must be re-run to get a consistent result by annotating the scan with the `compliance.openshift.io/rescan=` option: - -[source,terminal] ----- -$ oc annotate compliancescans/ compliance.openshift.io/rescan= ----- diff --git a/modules/compliance-manual.adoc b/modules/compliance-manual.adoc deleted file mode 100644 index 45aec5d58310..000000000000 --- a/modules/compliance-manual.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-remediation.adoc - -[id="compliance-manual_{context}"] -= Remediating a platform check manually - -Checks for Platform scans typically have to be remediated manually by the administrator for two reasons: - -* It is not always possible to automatically determine the value that must be set. One of the checks requires that a list of allowed registries is provided, but the scanner has no way of knowing which registries the organization wants to allow. - -* Different checks modify different API objects, requiring automated remediation to possess `root` or superuser access to modify objects in the cluster, which is not advised. - -.Procedure -. The example below uses the `ocp4-ocp-allowed-registries-for-import` rule, which would fail on a default {product-title} installation. Inspect the rule `oc get rule.compliance/ocp4-ocp-allowed-registries-for-import -oyaml`, the rule is to limit the registries the users are allowed to import images from by setting the `allowedRegistriesForImport` attribute, The _warning_ attribute of the rule also shows the API object checked, so it can be modified and remediate the issue: -+ -[source,terminal] ----- -$ oc edit image.config.openshift.io/cluster ----- -+ -.Example output -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Image -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: "2020-09-10T10:12:54Z" - generation: 2 - name: cluster - resourceVersion: "363096" - selfLink: /apis/config.openshift.io/v1/images/cluster - uid: 2dcb614e-2f8a-4a23-ba9a-8e33cd0ff77e -spec: - allowedRegistriesForImport: - - domainName: registry.redhat.io -status: - externalRegistryHostnames: - - default-route-openshift-image-registry.apps.user-cluster-09-10-12-07.devcluster.openshift.com - internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ----- - -. Re-run the scan: -+ -[source,terminal] ----- -$ oc annotate compliancescans/ compliance.openshift.io/rescan= ----- diff --git a/modules/compliance-objects.adoc b/modules/compliance-objects.adoc deleted file mode 100644 index 0db4e4b9a693..000000000000 --- a/modules/compliance-objects.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-advanced.adoc - -[id="compliance-objects_{context}"] -= Using the ComplianceSuite and ComplianceScan objects directly - -While it is recommended that users take advantage of the `ScanSetting` and `ScanSettingBinding` objects to define the suites and scans, there are valid use cases to define the `ComplianceSuite` objects directly: - -* Specifying only a single rule to scan. This can be useful for debugging together with the `debug: true` attribute which increases the OpenSCAP scanner verbosity, as the debug mode tends to get quite verbose otherwise. Limiting the test to one rule helps to lower the amount of debug information. - -* Providing a custom nodeSelector. In order for a remediation to be applicable, the nodeSelector must match a pool. - -* Pointing the Scan to a bespoke config map with a tailoring file. - -* For testing or development when the overhead of parsing profiles from bundles is not required. - -The following example shows a `ComplianceSuite` that scans the worker machines with only a single rule: - -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ComplianceSuite -metadata: - name: workers-compliancesuite -spec: - scans: - - name: workers-scan - profile: xccdf_org.ssgproject.content_profile_moderate - content: ssg-rhcos4-ds.xml - contentImage: quay.io/complianceascode/ocp4:latest - debug: true - rule: xccdf_org.ssgproject.content_rule_no_direct_root_logins - nodeSelector: - node-role.kubernetes.io/worker: "" ----- - -The `ComplianceSuite` object and the `ComplianceScan` objects referred to above specify several attributes in a format that OpenSCAP expects. - -To find out the profile, content, or rule values, you can start by creating a similar Suite from `ScanSetting` and `ScanSettingBinding` or inspect the objects parsed from the `ProfileBundle` objects like rules or profiles. Those objects contain the `xccdf_org` identifiers you can use to refer to them from a `ComplianceSuite`. diff --git a/modules/compliance-operator-cli-installation.adoc b/modules/compliance-operator-cli-installation.adoc deleted file mode 100644 index ae289d34a350..000000000000 --- a/modules/compliance-operator-cli-installation.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-installation.adoc - -[id="installing-compliance-operator-cli_{context}"] -= Installing the Compliance Operator using the CLI - -.Prerequisites - -* You must have `admin` privileges. - -.Procedure - -. Create a `Namespace` object YAML file by running: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-compliance ----- - -. Create the `OperatorGroup` object YAML file by running: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: compliance-operator - namespace: openshift-compliance -spec: - targetNamespaces: - - openshift-compliance ----- - -. Set the {product-title} major and minor version as an environment variable, which is used as the channel value in the next step: -+ -[source,terminal] ----- -$ OC_VERSION=$(oc version -o yaml | grep openshiftVersion | grep -o '[0-9]*[.][0-9]*' | head -1) ----- - -. Create the `Subscription` object YAML file by running: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: compliance-operator-sub - namespace: openshift-compliance -spec: - channel: "${OC_VERSION}" - installPlanApproval: Automatic - name: compliance-operator - source: redhat-operators - sourceNamespace: openshift-marketplace ----- - -.Verification - -. Verify the installation succeeded by inspecting the CSV file: -+ -[source,terminal] ----- -$ oc get csv -n openshift-compliance ----- - -. Verify that the Compliance Operator is up and running: -+ -[source,terminal] ----- -$ oc get deploy -n openshift-compliance ----- diff --git a/modules/compliance-operator-configure-scanning.adoc b/modules/compliance-operator-configure-scanning.adoc new file mode 100644 index 000000000000..fbe23f7f3843 --- /dev/null +++ b/modules/compliance-operator-configure-scanning.adoc @@ -0,0 +1,84 @@ +// Module included in the following assemblies: +// +// * operating/compliance-operator-rhacs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="compliance-operator-configure-scanning_{context}"] += Configuring the ScanSettingBinding object + +[role="_abstract"] +By creating a `ScanSettingBinding` object in the `openshift-compliance` namespace, you can scan your cluster by using the `cis` and `cis-node` profiles either from the command-line interface (CLI) or user interface (UI). + +[IMPORTANT] +==== +This example uses `ocp4-cis` and `ocp4-cis-node` profiles, but {ocp} provides additional profiles. + +For more information, see "Understanding the Compliance Operator". +==== + +.Prerequisites + +* You have installed the Compliance Operator. + +.Procedure + +* To create the `ScanSettingBinding` object from the CLI, perform the following steps: + +.. Create a file named `sscan.yaml` by using the following content: ++ +[source,yaml] +---- +apiVersion: compliance.openshift.io/v1alpha1 +kind: ScanSettingBinding +metadata: + name: cis-compliance +profiles: + - name: ocp4-cis-node + kind: Profile + apiGroup: compliance.openshift.io/v1alpha1 + - name: ocp4-cis + kind: Profile + apiGroup: compliance.openshift.io/v1alpha1 +settingsRef: + name: default + kind: ScanSetting + apiGroup: compliance.openshift.io/v1alpha1 +---- + +.. Create the `ScanSettingBinding` object by running the following command: ++ +[source, terminal] +---- +$ oc create -f sscan.yaml -n openshift-compliance +---- +If successful, the following message is displayed: ++ +[source, terminal] +---- +$ scansettingbinding.compliance.openshift.io/cis-compliance created +---- + +* To create the `ScanSettingBinding` object from the UI, perform the following steps: + +.. Change the active project to `openshift-compliance`. +.. Click *+* to open the *Import YAML* page. +.. Paste the YAML from the previous example, and then click *Create*. + +.Verification + +. Run a compliance scan in {product-title-short}. ++ +For more information about how to run a compliance scan by using the compliance feature, see "Checking the compliance status of your infrastructure". + +. Ensure that `ocp4-cis` and `ocp4-cis-node` results are displayed. + +[IMPORTANT] +==== +* If you are using the CLI, you can view the compliance scan results from the dashboard page. ++ +For more information about how to view the compliance scan results from the dashboard page, see "Viewing the compliance standards across your environment". + +* If you are using the UI, you can view the compliance scan results from both the dashboard and coverage page. ++ +For more information about how to view the compliance scan results from the coverage page, see "Assessing the profile compliance across clusters". +==== \ No newline at end of file diff --git a/modules/compliance-operator-console-installation.adoc b/modules/compliance-operator-console-installation.adoc deleted file mode 100644 index 8abdd9fc75ed..000000000000 --- a/modules/compliance-operator-console-installation.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-installation.adoc - -[id="installing-compliance-operator-web-console_{context}"] -= Installing the Compliance Operator through the web console - -.Prerequisites - -* You must have `admin` privileges. - -.Procedure - -. In the {product-title} web console, navigate to *Operators* -> *OperatorHub*. -. Search for the Compliance Operator, then click *Install*. -. Keep the default selection of *Installation mode* and *namespace* to ensure that the Operator will be installed to the `openshift-compliance` namespace. -. Click *Install*. - -.Verification - -To confirm that the installation is successful: - -. Navigate to the *Operators* -> *Installed Operators* page. -. Check that the Compliance Operator is installed in the `openshift-compliance` namespace and its status is `Succeeded`. - -If the Operator is not installed successfully: - -. Navigate to the *Operators* -> *Installed Operators* page and inspect the `Status` column for any errors or failures. -. Navigate to the *Workloads* -> *Pods* page and check the logs in any pods in the `openshift-compliance` project that are reporting issues. diff --git a/modules/compliance-operator-install.adoc b/modules/compliance-operator-install.adoc new file mode 100644 index 000000000000..e1a7669c8b28 --- /dev/null +++ b/modules/compliance-operator-install.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operating/compliance-operator-rhacs.adoc +:_mod-docs-content-type: PROCEDURE +[id="compliance-operator-install_{context}"] += Installing the Compliance Operator + +[role="_abstract"] +Install the Compliance Operator by using the Operator Hub. + +.Procedure + +. In the web console, go to the *Operators* -> *OperatorHub* page. + +. Enter *compliance operator* into the *Filter by keyword* box to find the Compliance Operator. + +. Select the *Compliance Operator* to view the details page. + +. Read the information about the Operator, and then click *Install*. + +[IMPORTANT] +==== +* If you use the compliance feature, you can schedule your scan by using {product-title-short} to create a compliance scan schedule. ++ +For more information about scheduling a compliance scan by using the compliance feature, see "Customizing and automating your compliance scans". + +* If you create a scan schedule, you do _not_ need to create the `ScanSettingBinding` on the Compliance Operator. +==== \ No newline at end of file diff --git a/modules/compliance-profilebundle.adoc b/modules/compliance-profilebundle.adoc deleted file mode 100644 index a820e7d74330..000000000000 --- a/modules/compliance-profilebundle.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-manage.adoc - -[id="compliance-profilebundle_{context}"] -= ProfileBundle CR example - -The bundle object needs two pieces of information: the URL of a container image that contains the `contentImage` and the file that contains the compliance content. The `contentFile` parameter is relative to the root of the file system. The built-in `rhcos4` `ProfileBundle` object can be defined in the example below: - -[source,yaml] ----- - apiVersion: compliance.openshift.io/v1alpha1 - kind: ProfileBundle - metadata: - name: rhcos4 - spec: - contentImage: quay.io/complianceascode/ocp4:latest <1> - contentFile: ssg-rhcos4-ds.xml <2> ----- -<1> Content image location. -<2> Location of the file containing the compliance content. - -[IMPORTANT] -==== -The base image used for the content images must include `coreutils`. -==== diff --git a/modules/compliance-profiles.adoc b/modules/compliance-profiles.adoc deleted file mode 100644 index c29d6ea8ed42..000000000000 --- a/modules/compliance-profiles.adoc +++ /dev/null @@ -1,157 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-understanding.adoc - -[id="compliance_profiles_{context}"] -= Compliance Operator profiles - -There are several profiles available as part of the Compliance Operator installation. - -View the available profiles: - -[source,terminal] ----- -$ oc get -n profiles.compliance ----- - -.Example output -[source,terminal] ----- -NAME AGE -ocp4-cis 4h52m -ocp4-cis-node 4h52m -ocp4-e8 4h52m -ocp4-moderate 4h52m -rhcos4-e8 4h52m -rhcos4-moderate 4h52m ----- - -These profiles represent different compliance benchmarks. - -View the details of a profile: - -[source,terminal] ----- -$ oc get -n -oyaml profiles.compliance ----- - -.Example output -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -description: |- - This profile contains configuration checks for Red Hat - Enterprise Linux CoreOS that align to the Australian - Cyber Security Centre (ACSC) Essential Eight. - A copy of the Essential Eight in Linux Environments guide can - be found at the ACSC website: ... -id: xccdf_org.ssgproject.content_profile_e8 -kind: Profile -metadata: - annotations: - compliance.openshift.io/product: redhat_enterprise_linux_coreos_4 - compliance.openshift.io/product-type: Node - creationTimestamp: "2020-09-07T11:42:51Z" - generation: 1 - labels: - compliance.openshift.io/profile-bundle: rhcos4 - name: rhcos4-e8 - namespace: openshift-compliance -rules: -- rhcos4-accounts-no-uid-except-zero -- rhcos4-audit-rules-dac-modification-chmod -- rhcos4-audit-rules-dac-modification-chown -- rhcos4-audit-rules-execution-chcon -- rhcos4-audit-rules-execution-restorecon -- rhcos4-audit-rules-execution-semanage -- rhcos4-audit-rules-execution-setfiles -- rhcos4-audit-rules-execution-setsebool -- rhcos4-audit-rules-execution-seunshare -- rhcos4-audit-rules-kernel-module-loading -- rhcos4-audit-rules-login-events -- rhcos4-audit-rules-login-events-faillock -- rhcos4-audit-rules-login-events-lastlog -- rhcos4-audit-rules-login-events-tallylog -- rhcos4-audit-rules-networkconfig-modification -- rhcos4-audit-rules-sysadmin-actions -- rhcos4-audit-rules-time-adjtimex -- rhcos4-audit-rules-time-clock-settime -- rhcos4-audit-rules-time-settimeofday -- rhcos4-audit-rules-time-stime -- rhcos4-audit-rules-time-watch-localtime -- rhcos4-audit-rules-usergroup-modification -- rhcos4-auditd-data-retention-flush -- rhcos4-auditd-freq -- rhcos4-auditd-local-events -- rhcos4-auditd-log-format -- rhcos4-auditd-name-format -- rhcos4-auditd-write-logs -- rhcos4-configure-crypto-policy -- rhcos4-configure-ssh-crypto-policy -- rhcos4-no-empty-passwords -- rhcos4-selinux-policytype -- rhcos4-selinux-state -- rhcos4-service-auditd-enabled -- rhcos4-sshd-disable-empty-passwords -- rhcos4-sshd-disable-gssapi-auth -- rhcos4-sshd-disable-rhosts -- rhcos4-sshd-disable-root-login -- rhcos4-sshd-disable-user-known-hosts -- rhcos4-sshd-do-not-permit-user-env -- rhcos4-sshd-enable-strictmodes -- rhcos4-sshd-print-last-log -- rhcos4-sshd-set-loglevel-info -- rhcos4-sshd-use-priv-separation -- rhcos4-sysctl-kernel-dmesg-restrict -- rhcos4-sysctl-kernel-kexec-load-disabled -- rhcos4-sysctl-kernel-kptr-restrict -- rhcos4-sysctl-kernel-randomize-va-space -- rhcos4-sysctl-kernel-unprivileged-bpf-disabled -- rhcos4-sysctl-kernel-yama-ptrace-scope -- rhcos4-sysctl-net-core-bpf-jit-harden -title: Australian Cyber Security Centre (ACSC) Essential Eight ----- - -View the rules within a desired profile: - -[source,terminal] ----- -$ oc get -n -oyaml rules.compliance ----- - -.Example output -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -description: 'auditdaugenrules.rules/etc/audit/rules.d
        -w /var/log/tallylog -p wa -k logins -w /var/run/faillock -p wa -k logins -w /var/log/lastlog -p wa -k logins
        auditdauditctl/etc/audit/audit.rules
        -w /var/log/tallylog -p wa -k logins -w /var/run/faillock -p wa -k logins -w /var/log/lastlog -p wa -k logins
        file in order to watch for unattempted manual edits of files involved in storing logon events:' -id: xccdf_org.ssgproject.content_rule_audit_rules_login_events -kind: Rule -metadata: - annotations: - compliance.openshift.io/rule: audit-rules-login-events - control.compliance.openshift.io/NIST-800-53: AU-2(d);AU-12(c);AC-6(9);CM-6(a) - policies.open-cluster-management.io/controls: AU-2(d),AU-12(c),AC-6(9),CM-6(a) - policies.open-cluster-management.io/standards: NIST-800-53 - creationTimestamp: "2020-09-07T11:43:03Z" - generation: 1 - labels: - compliance.openshift.io/profile-bundle: rhcos4 - name: rhcos4-audit-rules-login-events - namespace: openshift-compliance - rationale: |- - Manual editing of these files may indicate nefarious activity, - such as an attacker attempting to remove evidence of an - intrusion. - severity: medium - title: Record Attempts to Alter Logon and Logout Events - warning: |- -
        • audit_rules_login_events_tallylog
          • -
        • audit_rules_login_events_faillock
          • -
        • audit_rules_login_events_lastlog
        - This rule checks for multiple syscalls related to login - events and was written with DISA STIG in mind. - Other policies should use separate rule for - each syscall that needs to be checked. ----- - -Each profile has the product name that it applies to added as a prefix to the profile's name. `ocp4-e8` applies the Essential 8 benchmark to the {product-title} product, while `rhcos4-e8` applies the Essential 8 benchmark to the Red Hat CoreOS product. diff --git a/modules/compliance-raw-tailored.adoc b/modules/compliance-raw-tailored.adoc deleted file mode 100644 index 595a5612b357..000000000000 --- a/modules/compliance-raw-tailored.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-advanced.adoc - -[id="compliance-raw-tailored_{context}"] -= Using raw tailored profiles -While the `TailoredProfile` CR enables the most common tailoring operations, the XCCDF standard allows even more flexibility in tailoring OpenSCAP profiles. In addition, if your organization has been using OpenScap previously, you may have an existing XCCDF tailoring file and can reuse it. - -The `ComplianceSuite` object contains an optional `TailoringConfigMap` attribute that you can point to a custom tailoring file. The value of the `TailoringConfigMap` attribute is a name of a config map which must contain a key called `tailoring.xml` and the value of this key is the tailoring contents. - -.Procedure -. Create the `ConfigMap` object from a file: -+ -[source,terminal] ----- -$ oc create configmap --from-file=tailoring.xml=/path/to/the/tailoringFile.xml ----- - -. Reference the tailoring file in a scan that belongs to a suite: -+ -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ComplianceSuite -metadata: - name: workers-compliancesuite -spec: - debug: true - scans: - - name: workers-scan - profile: xccdf_org.ssgproject.content_profile_moderate - content: ssg-rhcos4-ds.xml - contentImage: quay.io/complianceascode/ocp4:latest - debug: true - tailoringConfigMap: - name: - nodeSelector: - node-role.kubernetes.io/worker: "" ----- diff --git a/modules/compliance-rescan.adoc b/modules/compliance-rescan.adoc deleted file mode 100644 index 764bf62b21ab..000000000000 --- a/modules/compliance-rescan.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-advanced.adoc - -[id="compliance-rescan_{context}"] -= Performing a rescan -Typically you will want to re-run a scan on a defined schedule, like every Monday or daily. It can also be useful to re-run a scan once after fixing a problem on a node. To perform a single scan, annotate the scan with the `compliance.openshift.io/rescan=` option: - -[source,terminal] ----- -$ oc annotate compliancescans/ compliance.openshift.io/rescan= ----- diff --git a/modules/compliance-results.adoc b/modules/compliance-results.adoc deleted file mode 100644 index 98c77d031775..000000000000 --- a/modules/compliance-results.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-raw-results.adoc - -[id="compliance-results_{context}"] -= Obtaining Compliance Operator raw results from a persistent volume - -.Procedure - -The Compliance Operator generates and stores the raw results in a persistent volume. These results are in Asset Reporting Format (ARF). - -. Explore the `ComplianceSuite` object: -+ -[source,terminal] ----- -$ oc get compliancesuites nist-moderate-modified -o json \ - | jq '.status.scanStatuses[].resultsStorage' - { - "name": "rhcos4-moderate-worker", - "namespace": "openshift-compliance" - } - { - "name": "rhcos4-moderate-master", - "namespace": "openshift-compliance" - } ----- -+ -This shows the persistent volume claims where the raw results are accessible. - -. Verify the raw data location by using the name and namespace of one of the results: -+ -[source,terminal] ----- -$ oc get pvc -n openshift-compliance rhcos4-moderate-worker ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE -rhcos4-moderate-worker Bound pvc-548f6cfe-164b-42fe-ba13-a07cfbc77f3a 1Gi RWO gp2 92m ----- - -. Fetch the raw results by spawning a pod that mounts the volume and copying the results: -+ -.Example pod -[source,yaml] ----- -apiVersion: "v1" -kind: Pod -metadata: - name: pv-extract -spec: - containers: - - name: pv-extract-pod - image: registry.access.redhat.com/ubi8/ubi - command: ["sleep", "3000"] - volumeMounts: - - mountPath: "/workers-scan-results" - name: workers-scan-vol - volumes: - - name: workers-scan-vol - persistentVolumeClaim: - claimName: rhcos4-moderate-worker ----- - -. After the pod is running, download the results: -+ -[source,terminal] ----- -$ oc cp pv-extract:/workers-scan-results . ----- -+ -[IMPORTANT] -==== -Spawning a pod that mounts the persistent volume will keep the claim as `Bound`. If the volume’s storage class in use has permissions set to `ReadWriteOnce`, the volume is only mountable by one pod at a time. You must delete the pod upon completion, or it will be possible for the Operator to schedule a pod and continue storing results in this location. -==== - -. After the extraction is complete, the pod can be deleted: -+ -[source,terminal] ----- -$ oc delete pod pv-extract ----- diff --git a/modules/compliance-review.adoc b/modules/compliance-review.adoc deleted file mode 100644 index 31ca1810a628..000000000000 --- a/modules/compliance-review.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-remediation.adoc - -[id="compliance-review_{context}"] -= Reviewing a remediation - -Review both the `ComplianceRemediation` object and the `ComplianceCheckResult` object that owns the remediation. The `ComplianceCheckResult` object contains human-readable descriptions of what the check does and the hardening trying to prevent, as well as other `metadata` like the severity and the associated security controls. The `ComplianceRemediation` object represents a way to fix the problem described in the `ComplianceCheckResult`. - -Below is an example of a check and a remediation called `sysctl-net-ipv4-conf-all-accept-redirects`. This example is redacted to only show `spec` and `status` and omits `metadata`: - -[source,yaml] ----- -spec: - apply: false - current: - object: - apiVersion: machineconfiguration.openshift.io/v1 - kind: MachineConfig - spec: - config: - ignition: - version: 2.2.0 - storage: - files: - - contents: - source: data:,net.ipv4.conf.all.accept_redirects%3D0 - filesystem: root - mode: 420 - path: /etc/sysctl.d/75-sysctl_net_ipv4_conf_all_accept_redirects.conf - outdated: {} -status: - applicationState: NotApplied ----- - -The remediation payload is stored in the `spec.current` attribute. The payload can be any Kubernetes object, but because this remediation was produced by a node scan, the remediation payload in the above example is a `MachineConfig` object. For Platform scans, the remediation payload is often a different kind of an object (for example, a `ConfigMap` or `Secret` object), but typically applying that remediation is up to the administrator, because otherwise the Compliance Operator would have required a very broad set of permissions to manipulate any generic Kubernetes object. An example of remediating a Platform check is provided later in the text. - -To see exactly what the remediation does when applied, the `MachineConfig` object contents use the Ignition objects for the configuration. Refer to the link:https://coreos.com/ignition/docs/latest/configuration-v2_2.html[Ignition specification] for further information about the format. In our example, `the spec.config.storage.files[0].path` attribute specifies the file that is being create by this remediation (`/etc/sysctl.d/75-sysctl_net_ipv4_conf_all_accept_redirects.conf`) and the `spec.config.storage.files[0].contents.source` attribute specifies the contents of that file. - -[NOTE] -==== -The contents of the files are URL-encoded. -==== - -Use the following Python script to view the contents: - -[source,terminal] ----- -$ echo "net.ipv4.conf.all.accept_redirects%3D0" | python3 -c "import sys, urllib.parse; print(urllib.parse.unquote(''.join(sys.stdin.readlines())))" ----- - -.Example output -[source,terminal] ----- -net.ipv4.conf.all.accept_redirects=0 ----- diff --git a/modules/compliance-scan-status-overview.adoc b/modules/compliance-scan-status-overview.adoc new file mode 100644 index 000000000000..328f29df91b1 --- /dev/null +++ b/modules/compliance-scan-status-overview.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: REFERENCE +[id="compliance-scan-status-overview_{context}"] += Compliance scan status overview + +By understanding the compliance scan status, you can manage the overall security posture of your environment. + +[cols="2,2",options="header"] +|=== +|Status |Description + +|`Fail` +|The compliance check failed. + +|`Pass` +|The compliance check passed. + +|`Not Applicable` +|Skipped the compliance check because it was not applicable. + +|`Info` +|The compliance check gathered data, but {product-title-short} could not make a pass or fail determination. + +|`Error` +|The compliance check failed due to a technical issue. + +|`Manual` +|Manual intervention is required to ensure compliance. + +|`Inconsistent` +|The compliance scan data is inconsistent, and requires closer inspection and targeted resolution. +|=== \ No newline at end of file diff --git a/modules/compliance-tailored-profiles.adoc b/modules/compliance-tailored-profiles.adoc deleted file mode 100644 index ef3fe2431450..000000000000 --- a/modules/compliance-tailored-profiles.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-tailor.adoc - -[id="compliance-tailored-profiles_{context}"] -= Using tailored profiles -While the `TailoredProfile` CR enables the most common tailoring operations, the XCCDF standard allows even more flexibility in tailoring OpenSCAP profiles. In addition, if your organization has been using OpenScap previously, you may have an existing XCCDF tailoring file and can reuse it. - -The `ComplianceSuite` object contains an optional `TailoringConfigMap` attribute that you can point to a custom tailoring file. The value of the `TailoringConfigMap` attribute is a name of a config map, which must contain a key called `tailoring.xml` and the value of this key is the tailoring contents. - -.Procedure - -. Browse the available rules for the {op-system-first} `ProfileBundle`: -+ -[source,terminal] ----- -$ oc get rules.compliance -l compliance.openshift.io/profile-bundle=rhcos4 ----- - -. Browse the available variables in the same `ProfileBundle`: -+ -[source,terminal] ----- -$ oc get variables.compliance -l compliance.openshift.io/profile-bundle=rhcos4 ----- - -. Choose which rules you want to add to the `TailoredProfile`. This `TailoredProfile` example disables two rules and changes one value. Use the `rationale` value to describe why these changes were made: -+ -.Example output -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: TailoredProfile -metadata: - name: nist-moderate-modified -spec: - extends: rhcos4-moderate - title: My modified NIST moderate profile - disableRules: - - name: rhcos4-file-permissions-node-config - rationale: This breaks X application. - - name: rhcos4-account-disable-post-pw-expiration - rationale: No need to check this as it comes from the IdP - setValues: - - name: rhcos4-var-selinux-state - rationale: Organizational requirements - value: permissive ----- - -. Add the profile to the `ScanSettingsBinding` object: -+ -[source,terminal] ----- -$ cat nist-moderate-modified.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ScanSettingBinding -metadata: - name: nist-moderate-modified -profiles: - - apiGroup: compliance.openshift.io/v1alpha1 - kind: Profile - name: ocp4-moderate - - apiGroup: compliance.openshift.io/v1alpha1 - kind: TailoredProfile - name: nist-moderate-modified -settingsRef: - apiGroup: compliance.openshift.io/v1alpha1 - kind: ScanSetting - name: default ----- - -. Create the `TailoredProfile`: -+ -[source,terminal] ----- -$ oc create -n -f .yaml ----- -+ -.Example output -[source,terminal] ----- -scansettingbinding.compliance.openshift.io/nist-moderate-modified created ----- diff --git a/modules/compliance-unapplying.adoc b/modules/compliance-unapplying.adoc deleted file mode 100644 index f83f4367bc11..000000000000 --- a/modules/compliance-unapplying.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-remediation.adoc - -[id="compliance-unapplying_{context}"] -= Unapplying a remediation -It might be required to unapply a remediation that was previously applied. - -.Procedure -. Toggle the flag to `false`: -+ -[source,terminal] ----- -$ oc patch complianceremediations/-sysctl-net-ipv4-conf-all-accept-redirects ----- - -. The remediation status will change to `NotApplied` and the composite `MachineConfig` object would be re-rendered to not include the remediation. -+ -[IMPORTANT] -==== -All affected nodes with the remediation will be rebooted. -==== diff --git a/modules/compliance-update.adoc b/modules/compliance-update.adoc deleted file mode 100644 index c2231fb61f9c..000000000000 --- a/modules/compliance-update.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-manage.adoc - -[id="compliance-update_{context}"] -= Updating security content - -Security content is shipped as container images that the `ProfileBundle` objects refer to. To accurately track updates to `ProfileBundles` and the custom resources parsed from the bundles such as rules or profiles, identify the container image with the compliance content using a digest instead of a tag: - -.Example output -[source,yaml] ----- - apiVersion: compliance.openshift.io/v1alpha1 - kind: ProfileBundle - metadata: - name: rhcos4 - spec: - contentImage: quay.io/user/ocp4-openscap-content@sha256:a1749f5150b19a9560a5732fe48a89f07bffc79c0832aa8c49ee5504590ae687 <1> - contentFile: ssg-rhcos4-ds.xml ----- - -<1> Security container image. - -Each `ProfileBundle` is backed by a deployment. When the Compliance Operator detects that the container image digest has changed, the deployment is updated to reflect the change and parse the content again. Using the digest instead of a tag ensures that you use a stable and predictable set of profiles. diff --git a/modules/compliance-updating.adoc b/modules/compliance-updating.adoc deleted file mode 100644 index b317c300f26c..000000000000 --- a/modules/compliance-updating.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-operator-remediation.adoc - -[id="compliance-updating_{context}"] -= Updating remediations - -When a new version of compliance content is used, it might deliver a new and different version of a remediation than the previous version. The Compliance Operator will keep the old version of the remediation applied. The {product-title} administrator is also notified of the new version to review and apply. A ComplianceRemediation object that had been applied earlier, but was updated changes its status to *Outdated*. The outdated objects are labeled so that they can be searched for easily. - -The previously applied remediation contents would then be stored in the `spec.outdated` attribute of a `ComplianceRemediation` object and the new updated contents would be stored in the `spec.current` attribute. After updating the content to a newer version, the administrator then needs to review the remediation. As long as the `spec.outdated` attribute exists, it would be used to render the resulting `MachineConfig` object. After the `spec.outdated` attribute is removed, the Compliance Operator re-renders the resulting `MachineConfig` object, which causes the Operator to push the configuration to the nodes. - -.Procedure - -. Search for any outdated remediations: -+ -[source,terminal] ----- -$ oc get complianceremediations -lcomplianceoperator.openshift.io/outdated-remediation= ----- -+ -.Example output -[source,terminal] ----- -NAME STATE -workers-scan-no-empty-passwords Outdated ----- -+ -The currently applied remediation is stored in the `Outdated` attribute and the new, unapplied remediation is stored in the `Current` attribute. If you are satisfied with the new version, remove the `Outdated` field. If you want to keep the updated content, remove the `Current` and `Outdated` attributes. - -. Apply the newer version of the remediation: -+ -[source,terminal] ----- -$ oc patch complianceremediations workers-scan-no-empty-passwords --type json -p '[{"op":"remove", "path":/spec/outdated}]' ----- - -. The remediation state will switch from `Outdated` to `Applied`: -+ -[source,terminal] ----- -$ oc get complianceremediations workers-scan-no-empty-passwords ----- -+ -.Example output -[source,terminal] ----- -NAME STATE -workers-scan-no-empty-passwords Applied ----- - -. The nodes will apply the newer remediation version and reboot. diff --git a/modules/con-policy-categories.adoc b/modules/con-policy-categories.adoc new file mode 100644 index 000000000000..4175e8d48e18 --- /dev/null +++ b/modules/con-policy-categories.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="con-policy-categories_{context}"] += Policy categories + +{product-title-short} uses policy categories to group policies by type and function. You can use these categories to organize and search for policies. + +{product-title-short} provides the following default policy categories: + +* Anomalous Activity +* Cryptocurrency Mining +* DevOps Best Practices +* Docker Center for Internet Security (CIS) +* Kubernetes +* Kubernetes Events +* Network Tools +* Package Management +* Privileges +* Security Best Practices +* Supply Chain Security +* System Modification +* Vulnerability Management +* Zero Trust + +You can view existing categories and create your own policy categories in the {product-title-short} portal by using the *Policy Categories* tab in the *Policy Management* window. \ No newline at end of file diff --git a/modules/con-vuln-sources.adoc b/modules/con-vuln-sources.adoc new file mode 100644 index 000000000000..18bbd98ae47e --- /dev/null +++ b/modules/con-vuln-sources.adoc @@ -0,0 +1,70 @@ +// Module included in the following assemblies: +// +// * architecture/acs-architecture.adoc +// * cloud_service/acscs-architecture.adoc +:_mod-docs-content-type: CONCEPT +[id="con-vuln-sources_{context}"] += Vulnerability data sources + +Sources for vulnerabilities depend on the scanner that is used in your system. {product-title-short} contains two scanners: StackRox Scanner and Scanner V4. The StackRox Scanner is deprecated. Scanner V4 is the default image scanner. + +[id="scanner-v4-vuln-sources"] +== Scanner V4 sources + +Scanner V4 uses the following vulnerability sources: + +link:https://security.access.redhat.com/data/csaf/v2/vex/[Red{nbsp}Hat VEX]:: This source is used with release 4.6 and later. This source provides vulnerability data in link:https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.html#45-profile-5-vex[Vulnerability Exploitability eXchange(VEX)] format. {product-title-short} takes advantage of VEX benefits to significantly decrease the time needed for the initial loading of vulnerability data, and the space needed to store vulnerability data. VEX also provides improved accuracy over OVAL. ++ +{product-title-short} might list a different number of vulnerabilities when you are scanning with a {product-title-short} version that uses OVAL, such as {product-title-short} version 4.5, and a version that uses VEX, such as version 4.6. For example, {product-title-short} no longer displays vulnerabilities with a status of "under investigation," while these vulnerabilities were included with previous versions that used OVAL data. ++ +For containers from or built on top of containers from the Red{nbsp}Hat Ecosystem Catalog, {product-title-short} provides an option to show only vulnerabilities from Red{nbsp}Hat's VEX data. VEX data for Red{nbsp}Hat images is the most accurate because the Red{nbsp}Hat security team vets the vulnerabilities in those images and reports the results in VEX. Other vulnerability sources such as OSV can report vulnerabilities that Red{nbsp}Hat has determined are not applicable to the image. This can cause false positives in vulnerability results. Enabling the setting to use only VEX data for Red{nbsp}Hat images minimizes these false positives. ++ +The option to use VEX data for Red{nbsp}Hat containers is disabled by default. To enable this option, in Scanner V4 Matcher, set the environment variable `ROX_SCANNER_V4_RED_HAT_LAYERS_RED_HAT_VULNS_ONLY` to `true`. Be aware that in rare instances, using this option can cause valid vulnerabilities to not appear in scan results, or false negatives. For example, Red{nbsp}Hat does not track vulnerabilities for products that have reached end of life. Also be aware that Red{nbsp}Hat's VEX data is missing link:https://access.redhat.com/security/middleware_security_scanning_problem[accurate security data for many Middleware products]. ++ +For more information about Red{nbsp}Hat security data, including information about the use of OVAL, Common Security Advisory Framework Version 2.0 (CSAF), and VEX, see link:https://www.redhat.com/en/blog/future-red-hat-security-data[The future of Red{nbsp}Hat security data]. +link:https://osv.dev/[OSV]:: This is used for language-related vulnerabilities, such as Go, Java, JavaScript, Python, and Ruby. This source might provide +vulnerability IDs other than CVE IDs for vulnerabilities, such as a GitHub Security Advisory (GHSA) ID. ++ +[NOTE] +==== +{product-title-short} uses the OSV database available at link:https://osv.dev/[OSV.dev] under link:https://github.com/google/osv.dev/blob/master/LICENSE[Apache License 2.0]. +==== +link:https://nvd.nist.gov/[NVD]:: This is used for various purposes such as filling in information gaps when vendors do not provide information. For example, Alpine does not provide a description, CVSS score, severity, or published date. ++ +[NOTE] +==== +This product uses the NVD API but is not endorsed or certified by the NVD. +==== +Additional vulnerability sources:: +* link:https://secdb.alpinelinux.org/[Alpine Security Database] +* Data tracked in link:https://alas.aws.amazon.com/index.html[Amazon Linux Security Center] +* link:https://security-tracker.debian.org/tracker/data/json[Debian Security Tracker] +* link:https://linux.oracle.com/security/oval[Oracle OVAL] +* link:https://packages.vmware.com/photon/photon_oval_definitions/[Photon OVAL] +* link:https://support.novell.com/security/oval/[SUSE OVAL] +* link:https://security-metadata.canonical.com/oval/[Ubuntu OVAL] +* link:https://github.com/stackrox/stackrox/blob/master/scanner/updater/manual/vulns.go[StackRox]: The upstream StackRox project maintains a set of vulnerabilities that might not be discovered due to data formatting from other sources or absence of data. + +Scanner V4 Indexer sources:: Scanner V4 indexer uses the following files to index Red{nbsp}Hat containers: + +* link:https://security.access.redhat.com/data/metrics/repository-to-cpe.json[repository-to-cpe.json]: Maps RPM repositories to their related CPEs, which is required for matching vulnerabilities for RHEL-based images. +* link:https://security.access.redhat.com/data/metrics/container-name-repos-map.json[container-name-repos-map.json]: This matches container names to their respective repositories. + +[id="stackrox-scanner-vuln-sources"] +== StackRox Scanner sources + +StackRox Scanner uses the following vulnerability sources: + +* link:https://access.redhat.com/security/data/oval/v2/[Red{nbsp}Hat OVAL] v2 +* link:https://secdb.alpinelinux.org/[Alpine Security Database] +* Data tracked in link:https://alas.aws.amazon.com/index.html[Amazon Linux Security Center] +* link:https://security-tracker.debian.org/tracker/data/json[Debian Security Tracker] +* link:https://git.launchpad.net/ubuntu-cve-tracker/[Ubuntu CVE Tracker] +* link:https://nvd.nist.gov/[NVD]: This is used for various purposes such as filling in information gaps when vendors do not provide information. For example, Alpine does not provide a description, CVSS score, severity, or published date. ++ +[NOTE] +==== +This product uses the NVD API but is not endorsed or certified by the NVD. +==== +* link:https://github.com/stackrox/scanner/blob/master/ext/vulnsrc/manual/manual.go[Linux manual entries] and link:https://github.com/stackrox/scanner/blob/master/pkg/vulnloader/nvdloader/manual.go[NVD manual entries]: The upstream StackRox project maintains a set of vulnerabilities that might not be discovered due to data formatting from other sources or absence of data. +* link:https://security.access.redhat.com/data/metrics/repository-to-cpe.json[repository-to-cpe.json]: Maps RPM repositories to their related CPEs, which is required for matching vulnerabilities for RHEL-based images. diff --git a/modules/config-using-declarative-config.adoc b/modules/config-using-declarative-config.adoc new file mode 100644 index 000000000000..471266b85d61 --- /dev/null +++ b/modules/config-using-declarative-config.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * configuration/using-rhacs-with-gitops.adoc +:_mod-docs-content-type: CONCEPT +[id="config-using-declarative-config_{context}"] += Configuration by using declarative configuration + +You can configure the following resources by using the {product-title-short} declarative configuration method: + +* Authentication providers +* Roles +* Permission sets +* Notifiers +* Access scopes +* Short-lived tokens + +To configure these resources, you create YAML files that contain configuration information. These files are used to create a ConfigMap or Secret that is added to {product-title-short} by using a mount point during installation of the {product-title-short} Central resource. diff --git a/modules/config-using-policy-as-code.adoc b/modules/config-using-policy-as-code.adoc new file mode 100644 index 000000000000..001f557616c1 --- /dev/null +++ b/modules/config-using-policy-as-code.adoc @@ -0,0 +1,8 @@ +// Module included in the following assemblies: +// +// * configuration/using-rhacs-with-gitops.adoc +:_mod-docs-content-type: CONCEPT +[id="config-using-policy-as-code_{context}"] += Configuration by using policy as code + +You can create and manage policies as code by authoring policies as Kubernetes custom resources (CRs), and then applying them to the {product-title-short} Central namespace by using a GitOps tool such as OpenShift GitOps, which is built on ArgoCD. diff --git a/modules/configmap-adding-ca.adoc b/modules/configmap-adding-ca.adoc deleted file mode 100644 index 664ca14fad7f..000000000000 --- a/modules/configmap-adding-ca.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/setting-up-trusted-ca -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc - -[id="configmap-adding-ca_{context}"] -= Adding certificate authorities to the cluster - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -You can add certificate authorities (CA) to the cluster for use when pushing and pulling images with the following procedure. - -.Prerequisites - -* You must have cluster administrator privileges. -* You must have access to the public certificates of the registry, usually a `hostname/ca.crt` file located in the `/etc/docker/certs.d/` directory. - -.Procedure - -. Create a `ConfigMap` in the `openshift-config` namespace containing the trusted certificates for the registries that use self-signed certificates. For each CA file, ensure the key in the `ConfigMap` is the hostname of the registry in the `hostname[..port]` format: -+ -[source,terminal] ----- -$ oc create configmap registry-cas -n openshift-config \ ---from-file=myregistry.corp.com..5000=/etc/docker/certs.d/myregistry.corp.com:5000/ca.crt \ ---from-file=otherregistry.com=/etc/docker/certs.d/otherregistry.com/ca.crt ----- - -. Update the cluster image configuration: -+ -[source,terminal] ----- -$ oc patch image.config.openshift.io/cluster --patch '{"spec":{"additionalTrustedCA":{"name":"registry-cas"}}}' --type=merge ----- -endif::[] - -ifdef::openshift-dedicated[] -You can add certificate authorities (CA) to the cluster for use when pushing and pulling images with the following procedure. - -.Prerequisites - -* You must have Dedicated administrator privileges. -* You must have access to the public certificates of the registry, usually a -`hostname/ca.crt` file located in the `/etc/docker/certs.d/` directory. - -.Procedure - -. Create a `ConfigMap` in the `openshift-config` namespace containing the trusted certificates for the registries that use self-signed certificates. For each CA file, ensure the key in the `ConfigMap` is the hostname of the registry in the `hostname[..port]` format: -+ -[source,terminal] ----- -$ oc create configmap registry-cas -n openshift-config \ ---from-file=myregistry.corp.com..5000=/etc/docker/certs.d/myregistry.corp.com:5000/ca.crt \ ---from-file=otherregistry.com=/etc/docker/certs.d/otherregistry.com/ca.crt ----- - -. Update the cluster image configuration: -+ -[source,terminal] ----- -$ oc patch image.config.openshift.io/cluster --patch '{"spec":{"additionalTrustedCA":{"name":"registry-cas"}}}' --type=merge ----- -endif::[] diff --git a/modules/configuration-details-tab.adoc b/modules/configuration-details-tab.adoc new file mode 100644 index 000000000000..b50fdcbecbdf --- /dev/null +++ b/modules/configuration-details-tab.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: CONCEPT +[id="configuration-details-tab_{context}"] += Configuration details tab + +The *Configuration details* tab displays information about the scan schedule information such as the essential parameters, cluster status, associated profiles, and email delivery destinations. + +== Parameters section + +The *Parameters* section organizes information into the following groups: + +Name:: The unique identifier for the compliance scan. +Description:: Specifies additional information about the compliance scan. +Schedule:: Specifies when the compliance scans should run. +Last scanned:: The timestamp of the last compliance scan performed. +Last updated:: The last date and time that the compliance scan data was modified. + +== Clusters section + +The *Clusters* section organizes information into the following groups: + +Cluster:: Lists the one or more clusters associated with a compliance scan. +Operator status:: Indicates the current health or operational status of the Operator. + +== Profiles section + +The *Profiles* section lists the one or more profiles associated with a compliance scan. + +== Delivery destinations section + +The *Delivery destinations* section organizes information into the following groups: + +Email notifier:: Specifies the email notification system or tool set up to distribute reports or alerts. +Distribution list:: Lists the recipients who should receive the notifications or reports. +Email template:: Specifies the email format used for the notifications. You can use the default or customize the email subject and body as needed. diff --git a/modules/configuration-resource-overview.adoc b/modules/configuration-resource-overview.adoc deleted file mode 100644 index d1bb5b8c665b..000000000000 --- a/modules/configuration-resource-overview.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * TBD - -[id="configuration-resource-overview_{context}"] -= About Configuration Resources in {product-title} - -You perform many customization and configuration tasks after you deploy your -cluster, including configuring networking and setting your identity provider. - -In {product-title}, you modify Configuration Resources to determine the behavior -of these integrations. The Configuration Resources are controlled by Operators -that are managed by the Cluster Version Operator, which manages all of the -Operators that run your cluster's control plane. - -You can customize the following Configuration Resources: - -[cols="3a,8a",options="header"] -|=== - -|Configuration Resource |Description -|Authentication -| - -|DNS -| - -|Samples -| * *ManagementState:* -** *Managed.* The operator updates the samples as the configuration dictates. -** *Unmanaged.* The operator ignores updates to the samples resource object and -any imagestreams or templates in the `openshift` namespace. -** *Removed.* The operator removes the set of managed imagestreams -and templates in the `openshift` namespace. It ignores new samples created by -the cluster administrator or any samples in the skipped lists. After the removals are -complete, the operator works like it is in the `Unmanaged` state and ignores -any watch events on the sample resources, imagestreams, or templates. It -operates on secrets to facilitate the CENTOS to RHEL switch. There are some -caveats around concurrent create and removal. -* *Samples Registry:* Overrides the registry from which images are imported. -* *Architecture:* Place holder to choose an architecture type. Currently only x86 -is supported. -* *Skipped Imagestreams:* Imagestreams that are in the operator’s -inventory, but that the cluster administrator wants the operator to ignore or not manage. -* *Skipped Templates:* Templates that are in the operator’s inventory, but that -the cluster administrator wants the operator to ignore or not manage. - -|Infrastructure -| - -|Ingress -| - -|Network -| - -|OAuth -| - -|=== - -While you can complete many other customizations and configure other integrations -with an {product-title} cluster, configuring these resources is a common first -step after you deploy a cluster. - -Like all Operators, the Configuration Resources are governed by -Custom Resource Definitions (CRD). You customize the CRD for each -Configuration Resource that you want to modify in your cluster. diff --git a/modules/configuration-using-devops.adoc b/modules/configuration-using-devops.adoc new file mode 100644 index 000000000000..d47d1f5359b8 --- /dev/null +++ b/modules/configuration-using-devops.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +:_mod-docs-content-type: CONCEPT +[id="configuration-using-devops_{context}"] += Configuration using DevOps + +You can use {product-title-short} with your DevOps system to configure authentication and authorization resources, including the following examples: + +* Authentication providers +* Roles +* Permission sets +* Notifiers +* Access scopes + +To use DevOps to configure these parameters, you create YAML files that contain configuration information. These files are used to create a config map that is added to {product-title-short} by using a mount point during installation of the {product-title-short} Central resource. + +Additionally, you can use your DevOps system to configure and manage security policies by using the "policy as code" feature. You can author policies in YAML or JSON and save them as Kubernetes custom resources (CRs). Then, you use your DevOps system to track, manage, and apply policies to your clusters that are running {product-title-short}. A Kubernetes controller in {product-title-short} uses the API to receive information about new, updated, or deleted policies and reconciles the policy changes. diff --git a/modules/configure-acs-email.adoc b/modules/configure-acs-email.adoc new file mode 100644 index 000000000000..8cc75fca497d --- /dev/null +++ b/modules/configure-acs-email.adoc @@ -0,0 +1,72 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-email.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-acs-email_{context}"] += Configuring the email plugin + +The {product-title-short} notifier can send email to a recipient specified in the integration, or it can use annotations to determine the recipient. + +[IMPORTANT] +==== +If you are using {product-title-managed-short}, it blocks port `25` by default. Configure your mail server to use port `587` or `465` to send email notifications. +==== + +.Procedure + +. Go to *Platform Configuration* -> *Integrations*. +. Under the *Notifier Integrations* section, select *Email*. +. Select *New Integration*. +. In the *Integration name* field, enter a name for your email integration. +. In the *Email server* field, enter the address of your email server. The email server address includes fully qualified domain name (FQDN) and the port number; for example, `smtp.example.com:465`. +. Optional: If you are using an unauthenticated Simple Mail Transfer Protocol (SMTP), select *Enable unauthenticated SMTP*. This is insecure and not recommended, but might be required for some integrations. For example, you might need to enable this option if you use an internal server for notifications that does not require authentication. ++ +[NOTE] +==== +You cannot change an existing email integration that uses authentication to enable unauthenticated SMTP. You must delete the existing integration and create a new one with *Enable unauthenticated SMTP* selected. +==== +. Enter the user name and password of a service account that is used for authentication. +. Optional: Enter the name that you want to appear in the `FROM` header of email notifications in the *From* field; for example, `Security Alerts`. +. Specify the email address that you want to appear in the `SENDER` header of email notifications in the *Sender* field. +. Specify the email address that will receive the notifications in the *Default recipient* field. +. Optional: Enter an annotation key in *Annotation key for recipient*. You can use annotations to dynamically determine an email recipient. To do this: + +.. Add an annotation similar to the following example in your namespace or deployment YAML file, where `email` is the `Annotation key` that you specify in your email integration. You can create an annotation for the deployment or the namespace. ++ +[subs="+quotes"] +---- +annotations: + email: __ +---- +.. Use the annotation key `email` in the *Annotation key for recipient* field. ++ +If you configured the deployment or namespace with an annotation, the {product-title-short} sends the alert to the email specified in the annotation. Otherwise, it sends the alert to the default recipient. ++ +[NOTE] +==== +The following rules govern how {product-title-short} determines the recipient of an email notification: + +* If the deployment has an annotation key, the annotation's value overrides the default value. +* If the namespace has an annotation key, the namespace's value overrides the default value. +* If a deployment has an annotation key and a defined audience, {product-title-short} sends an email to the audience specified in the key. +* If a deployment does not have an annotation key, {product-title-short} checks the namespace for an annotation key and sends an email to the specified audience. +* If no annotation keys exist, {product-title-short} sends an email to the default recipient. +==== +. Optional: Select *Disable TLS certificate validation (insecure)* to send email without TLS. You should not disable TLS unless you are using StartTLS. ++ +[NOTE] +==== +Use TLS for email notifications. Without TLS, all email is sent unencrypted. +==== + +. Optional: To use StartTLS, select either *Login* or *Plain* from the *Use STARTTLS (requires TLS to be disabled)* drop-down menu. ++ +[IMPORTANT] +==== +With StartTLS, credentials are passed in plain text to the email server before the session encryption is established. + +* StartTLS with the *Login* parameter sends authentication credentials in a `*base64*` encoded string. +* StartTLS with the *Plain* parameter sends authentication credentials to your mail relay in plain text. +==== + +. Optional: Enter a hostname to use for the SMTP HELO/EHLO messages sent during the SMTP handshake. If you do not specify a hostname, `localhost` is used by default. \ No newline at end of file diff --git a/modules/configure-acscs-email.adoc b/modules/configure-acscs-email.adoc new file mode 100644 index 000000000000..91e96f046d1a --- /dev/null +++ b/modules/configure-acscs-email.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-email.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-acscs-email_{context}"] += Configuring the {product-title-managed-short} email plugin + +The {product-title-managed-short} notifier sends an email to a recipient. You can specify the recipient in the integration, or {product-title-managed-short} can use annotation keys to find the recipient. + +[IMPORTANT] +==== +* You can only send 250 emails per 24-hour rolling period. If you exceed this limit, {product-title-managed-short} sends emails only after the 24-hour period ends. +* Because of rate limits, Red{nbsp}Hat recommends using email notifications only for critical alerts or vulnerability reports. +==== + +.Procedure + +. Go to *Platform Configuration* -> *Integrations*. +. Under the *Notifier Integrations* section, select *{product-title-managed-short} Email*. +. Select *New Integration*. +. In the *Integration name* field, enter a name for your email integration. +. Specify the email address to which you want to send the email notifications in the *Default recipient* field. +. Optional: Enter an annotation key in *Annotation key for recipient*. You can use annotations to dynamically determine an email recipient. To do this: + +.. Add an annotation similar to the following example in your namespace or deployment YAML file, where `email` is the `Annotation key` that you specify in your email integration. You can create an annotation for the deployment or the namespace. ++ +[subs="+quotes"] +---- +annotations: + email: __ +---- +.. Use the annotation key `email` in the *Annotation key for recipient* field. + +If you configured the deployment or namespace with an annotation, the {product-title-managed-short} sends the alert to the email specified in the annotation. Otherwise, it sends the alert to the default recipient. + +[NOTE] +==== + +The following rules govern how {product-title-managed-short} determines the recipient of an email notification: + +* If the deployment has an annotation key, the annotation's value overrides the default value. +* If the namespace has an annotation key, the namespace's value overrides the default value. +* If a deployment has an annotation key and a defined audience, {product-title-managed-short} sends an email to the audience specified in the key. +* If a deployment does not have an annotation key, {product-title-managed-short} checks the namespace for an annotation key and sends an email to the specified audience. +* If no annotation keys exist, {product-title-managed-short} sends an email to the default recipient. +==== diff --git a/modules/configure-additional-cas.adoc b/modules/configure-additional-cas.adoc new file mode 100644 index 000000000000..bfc3fe515a77 --- /dev/null +++ b/modules/configure-additional-cas.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * configuration/add-trusted-ca.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-additional-cas_{context}"] += Configuring additional CAs + +To add custom CAs: + +.Procedure + +. Download the link:https://raw.githubusercontent.com/openshift/openshift-docs/rhacs-docs-main/files/ca-setup.sh[`ca-setup.sh`] script. ++ +[NOTE] +==== +* If you are doing a new installation, you can find the `ca-setup.sh` script in the `scripts` directory at `central-bundle/central/scripts/ca-setup.sh`. +* You must run the `ca-setup.sh` script in the same terminal from which you logged into your {ocp} cluster. +==== +. Make the `ca-setup.sh` script executable: ++ +[source,terminal] +---- +$ chmod +x ca-setup.sh +---- +. To add: +.. A single certificate, use the `-f` (file) option: ++ +[source,terminal] +---- +$ ./ca-setup.sh -f +---- ++ +[NOTE] +==== +* You must use a PEM-encoded certificate file (with any extension). +* You can also use the `-u` (update) option along with the `-f` option to update any previously added certificate. +==== +.. Multiple certificates at once, move all certificates in a directory, and then use the `-d` (directory) option: ++ +[source,terminal] +---- +$ ./ca-setup.sh -d +---- ++ +[NOTE] +==== +* You must use PEM-encoded certificate files with a `.crt` or `.pem` extension. +* Each file must only contain a single certificate. +* You can also use the `-u` (update) option along with the `-d` option to update any previously added certificates. +==== diff --git a/modules/configure-alert-data-retention.adoc b/modules/configure-alert-data-retention.adoc new file mode 100644 index 000000000000..596b49cea764 --- /dev/null +++ b/modules/configure-alert-data-retention.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * configuration/enable-alert-data-retention.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-alert-data-retention_{context}"] += Configuring alert data retention + +You can configure alert retention settings by using the {product-title-short} portal. + +.Prerequisites + +* You must have the `Administration` role with `read` and `write` permissions to configure data retention. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *System Configuration*. +. On the *System Configuration* view header, click *Edit*. +. Under the *Data Retention Configuration* section, update the number of days for each type of data: +* *All Runtime Violations* +* *Resolved Deploy-Phase Violations* +* *Runtime Violations For Deleted Deployments* +* *Images No Longer Deployed* ++ +[NOTE] +==== +To save a type of data forever, set the retention period to `0` days. +==== +. Click *Save*. + +[NOTE] +==== +To configure alert data retention by using {product-title} API, view the `PutConfig` API and related APIs in the `ConfigService` group in the API reference documentation. +==== diff --git a/modules/configure-cidr-blocks-ng20.adoc b/modules/configure-cidr-blocks-ng20.adoc new file mode 100644 index 000000000000..4c4d83258f18 --- /dev/null +++ b/modules/configure-cidr-blocks-ng20.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-cidr-blocks-ng20_{context}"] += Configuring CIDR blocks in the network graph + +[role="_abstract"] +You can specify custom CIDR blocks or configure the display of auto-discovered CIDR blocks in the network graph. + +.Procedure +. In the {product-title-short} portal, go to *Network Graph*, and then select *Manage CIDR Blocks*. You can perform the following actions: +* Toggle *Auto-discovered CIDR blocks* to hide auto-discovered CIDR blocks in the network graph. ++ +[NOTE] +==== +When you hide the auto-discovered CIDR blocks, the auto-discovered CIDR blocks are hidden for all clusters, and not only for the selected cluster in the network graph. +==== +* Add a custom CIDR block to the graph by performing the following steps: +.. Enter the CIDR name and CIDR address in the fields. To add additional CIDR blocks, click *Add CIDR block* and enter information for each block. +.. Click *Update Configuration* to save the changes. diff --git a/modules/configure-cluster-decommissioning.adoc b/modules/configure-cluster-decommissioning.adoc new file mode 100644 index 000000000000..458c19ff1917 --- /dev/null +++ b/modules/configure-cluster-decommissioning.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * configuration/cluster-decommissioning.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-cluster-decommissioning_{context}"] += Configuring cluster decommissioning + +[role="_abstract"] +You can configure {product-title-short} to automatically remove nonactive clusters from {product-title-short}. Nonactive clusters are those that were installed and performed a handshake with Central at least once but have been unreachable by Sensor for a specified period of time. You can also label clusters so that they are not removed when they are unreachable. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *System Configuration*. +. In the *System Configuration* header, click *Edit*. +. In the *Cluster deletion* section, you can configure the following fields: +* *Decommissioned cluster age*: The number of days that a cluster is unreachable before it is considered for removal from {product-title-short}. If Central cannot reach Sensor on the cluster for this number of days, the cluster and all of its resources are removed from {product-title-short}. To leave this feature disabled, which is the default behavior, enter `0` in this field. To enable this feature, enter a nonzero number, such as `90`, to configure the number of unreachable days. +* *Ignore clusters which have labels*: To prevent a cluster from being removed, you can configure a label by entering a key and value in this section. Clusters with this label will not be removed, even if they have been unreachable for the number of days set in the *Decommissioned cluster age* field. + +** *Key*: Enter the label to use for the cluster. +** *Value*: Enter the value associated with the key. ++ +For example, to preserve production clusters from removal, you can configure a key of `cluster-type` and a value of `production`. ++ +[NOTE] +==== +In the *Cluster deletion* section, click *Clusters which have Sensor Status: Unhealthy* to go to the *Clusters* list page. This page is filtered to show nonactive clusters that are subject to removal and a timeframe for the removal from {product-title-short}. +==== +. Click *Save*. + +[NOTE] +==== +To view and configure this option by using the API, use the `decommissionedClusterRetention` settings in the request payload for the `/v1/config` and `/v1/config/private` endpoints. For more information, see the API documentation for the `ConfigService` object by navigating to *Help* -> *API reference* in the {product-title-short} portal. +==== + + diff --git a/modules/configure-custom-priorities-in-jira.adoc b/modules/configure-custom-priorities-in-jira.adoc new file mode 100644 index 000000000000..c0fec16ecf2d --- /dev/null +++ b/modules/configure-custom-priorities-in-jira.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-jira.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-custom-priorities-in-jira_{context}"] += Configuring custom priorities in Jira + +If you are using custom priorities in your Jira project, you can configure them in {product-title}. + +.Procedure +. While configuring Jira integration in {product-title}, turn on the *Priority Mapping* toggle. {product-title} gets the JIRA project schema, and auto fills the values for the *CRITICAL_SEVERITY*, *HIGH_SEVERITY*, *MEDIUM_SEVERITY*, and *LOW_SEVERITY* fields. +. Verify or update the priority values based on your JIRA project configuration. +. Select *Test* to test that the integration with Jira is working. +. Select *Create* to generate the configuration. diff --git a/modules/configure-endpoints-existing.adoc b/modules/configure-endpoints-existing.adoc new file mode 100644 index 000000000000..a41204ec8447 --- /dev/null +++ b/modules/configure-endpoints-existing.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * configuration/configure-endpoints.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-endpoints-existing_{context}"] += Configuring endpoints for an existing instance + +You can configure endpoints for an existing instance of {product-title}. + +.Procedure +. Download the existing config map: ++ +[source,terminal] +---- +$ oc -n stackrox get cm/central-endpoints -o go-template='{{index .data "endpoints.yaml"}}' > /central_endpoints.yaml +---- +. In the downloaded `central_endpoints.yaml` file, specify your custom YAML configuration. +. Upload and apply the modified `central_endpoints.yaml` configuration file: ++ +[source,terminal] +---- +$ oc -n stackrox create cm central-endpoints --from-file=endpoints.yaml=/central-endpoints.yaml -o yaml --dry-run | \ +oc label -f - --local -o yaml app.kubernetes.io/name=stackrox | \ +oc apply -f - +---- +. Restart Central. + +[NOTE] +==== +If you expose any additional ports other than the default port `8443`, you must create network policies that allow traffic on those additional ports. +==== diff --git a/modules/configure-endpoints-new-install.adoc b/modules/configure-endpoints-new-install.adoc new file mode 100644 index 000000000000..ed6f5f309b50 --- /dev/null +++ b/modules/configure-endpoints-new-install.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * configuration/configure-endpoints.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-endpoints-new-install_{context}"] += Configuring endpoints during a new installation + +When you install {product-title} by using the `roxctl` CLI, it creates a folder named `central-bundle`, which contains the necessary YAML manifests and scripts to deploy Central. + +.Procedure +. After you generate the `central-bundle`, open the `./central-bundle/central/02-endpoints-config.yaml` file. +. In this file, add your custom YAML configuration under the `data:` section of the key `endpoints.yaml`. +Make sure that you maintain a 4 space indentation for the YAML configuration. +. Continue the installation instructions as usual. +{product-title} uses the specified configuration. + +[NOTE] +==== +If you expose any additional ports other than the default port `8443`, you must create network policies that allow traffic on those additional ports. +==== diff --git a/modules/configure-google-cloud-scc.adoc b/modules/configure-google-cloud-scc.adoc new file mode 100644 index 000000000000..7eb517579b36 --- /dev/null +++ b/modules/configure-google-cloud-scc.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-google-cloud-scc.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-google-cloud-scc_{context}"] += Configuring Google Cloud SCC + +Start by adding {product-title} as a trusted Cloud SCC source. + +.Procedure +. Follow the link:https://cloud.google.com/security-command-center/docs/how-to-security-sources[Adding vulnerability and threat sources to Cloud Security Command Center] guide and add {product-title} as a trusted Cloud SCC source. +Make a note of the *Source ID* that Google Cloud creates for your {product-title} integration. +If you do not see a source ID after registering, you can find it on the link:https://console.cloud.google.com/security/command-center/settings/source-management[Cloud SCC Security Sources page]. +. Create a key for the service account you created, or the existing account you used, in the previous step. +See Google Cloud's guide to link:https://cloud.google.com/iam/docs/creating-managing-service-account-keys[creating and managing service account keys] for details. diff --git a/modules/configure-jira.adoc b/modules/configure-jira.adoc new file mode 100644 index 000000000000..c6216d427a44 --- /dev/null +++ b/modules/configure-jira.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-jira.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-jira_{context}"] += Configuring Jira + +Start by creating a new user, and assign appropriate roles and permissions. + +.Prerequisites +* You need a Jira account with permissions to create and edit issues in the project with which you are integrating. + +.Procedure +* Create a user in Jira which have access to the projects for which you want to create issues: +** To create a new user, see the Jira documentation topic link:https://confluence.atlassian.com/adminjiraserver/create-edit-or-remove-a-user-938847025.html[Create, edit, or remove a user]. +** To give users access to project roles and applications, see the Jira documentation topic link:https://confluence.atlassian.com/adminjiraserver/assign-users-to-groups-project-roles-and-applications-938847026.html[Assign users to groups, project roles, and applications]. ++ +[NOTE] +==== +If you are using Jira Software Cloud, after you create the user, you must create a token for the user: + +. Go to https://id.atlassian.com/manage/api-tokens, to generate a new token. +. Use the token as password when you configure {product-title}. +==== diff --git a/modules/configure-minimum-access-role.adoc b/modules/configure-minimum-access-role.adoc new file mode 100644 index 000000000000..14a9096305ec --- /dev/null +++ b/modules/configure-minimum-access-role.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: CONCEPT +[id="configure-access-role_{context}"] += Configuring minimum access role + +[role="_abstract"] +You can configure a minimum access role that applies to all new users when they log in to the {product-title-short} portal. +To set a minimum access role, you must first configure an authentication provider. +//TODO: Add link to configure an authentication provider + +[NOTE] +==== +* The minimum access role is granted to all users who sign in with the authentication provider you configure. +* Set the minimum access role to *None* if you want to define permissions entirely by using specific rules. +==== + +.Prerequisites +* You must have the *Admin* role, or read and write permissions for the `Access` resource to create, modify, and delete custom roles. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Under *Auth Providers*, select the authentication provider for which you want to configure the minimum access role. +. Click *Edit Provider*. +. Under section 2 *Assign StackRox roles to your users*, select one of the roles from *Minimum access role*. +. Click *Save*. diff --git a/modules/configure-ocp-oauth-identity-provider.adoc b/modules/configure-ocp-oauth-identity-provider.adoc new file mode 100644 index 000000000000..d70ed3143794 --- /dev/null +++ b/modules/configure-ocp-oauth-identity-provider.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-ocp-oauth.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-ocp-oauth-identity-provider_{context}"] += Configuring {ocp} OAuth server as an identity provider + +[role="_abstract"] +To integrate the built-in {ocp} OAuth server as an identity provider for {product-title-short}, use the instructions in this section. + +.Prerequisites +* You must have the `Access` permission to configure identity providers in {product-title-short}. +* You must have already configured users and groups in {ocp} OAuth server through an identity provider. For information about the identity provider requirements, see link:https://docs.openshift.com/container-platform/4.9/authentication/understanding-identity-provider.html[Understanding identity provider configuration]. + +[NOTE] +==== +The following procedure configures only a single main route named `central` for the {ocp} OAuth server. +==== + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. Click *Create auth provider* and select *OpenShift Auth* from the drop-down list. +. Enter a name for the authentication provider in the *Name* field. +. Assign a *Minimum access role* for users that access {product-title-short} using the selected identity provider. A user must have the permissions granted to this role or a role with higher permissions to log in to {product-title-short}. ++ +[TIP] +==== +For security, Red{nbsp}Hat recommends first setting the *Minimum access role* to *None* while you complete setup. Later, you can return to the *Access Control* page to set up more tailored access rules based on user metadata from your identity provider. +==== + +. Optional: To add access rules for users and groups accessing {product-title-short}, click *Add new rule* in the *Rules* section, then enter the rule information and click *Save*. You will need attributes for the user or group so that you can configure access. ++ +[TIP] +==== +Group mappings are more robust because groups are usually associated with teams or permissions sets and require modification less often than users. +==== ++ + +To get user information in {ocp}, you can use one of the following methods: ++ +-- +* Click *User Management* -> *Users* -> * -> *YAML*. +* Access the `k8s/cluster/user.openshift.io\~v1~User//yaml` file and note the values for `name`, `uid` (`userid` in {product-title-short}), and `groups`. +* Use the {ocp} API as described in the _{ocp} API reference_. +-- ++ +The following configuration example describes how to configure rules for an *Admin* role with the following attributes: ++ +-- +** `name`: `administrator` +** `groups`: `["system:authenticated", "system:authenticated:oauth", "myAdministratorsGroup"]` +** `uid`: `12345-00aa-1234-123b-123fcdef1234` +-- ++ +You can add a rule for this administrator role using one of the following steps: ++ +** To configure a rule for a name, select `name` from the *Key* drop-down list, enter `administrator` in the *Value* field, then select *Administrator* under *Role*. +** To configure a rule for a group, select `groups` from the *Key* drop-down list, enter `myAdministratorsGroup` in the *Value* field, then select *Admin* under *Role*. +** To configure a rule for a user name, select `userid` from the *Key* drop-down list, enter `12345-00aa-1234-123b-123fcdef1234` in the *Value* field, then select *Admin* under *Role*. + diff --git a/modules/configure-oidc-identity-provider.adoc b/modules/configure-oidc-identity-provider.adoc new file mode 100644 index 000000000000..39f24e34facf --- /dev/null +++ b/modules/configure-oidc-identity-provider.adoc @@ -0,0 +1,70 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-google-workspace-identity.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-oidc-identity-provider_{context}"] += Configuring an OIDC identity provider + +You can configure {product-title} ({product-title-short}) to use your OpenID Connect (OIDC) identity provider. + +.Prerequisites +* You must have already configured an application in your identity provider, such as Google Workspace. +* You must have permissions to configure identity providers in {product-title-short}. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. Click *Create auth provider* and select *OpenID Connect* from the drop-down list. +. Enter information in the following fields: +** *Name*: A name to identify your authentication provider; for example, *Google Workspace*. The integration name is shown on the login page to help users select the correct sign-in option. +** *Callback mode*: Select *Auto-select (recommended)*, which is the default value, unless the identity provider requires another mode. ++ +[NOTE] +==== +`Fragment` mode is designed around the limitations of Single Page Applications (SPAs). Red{nbsp}Hat only supports the `Fragment` mode for early integrations and does not recommended using it for later integrations. +==== +** *Issuer*: The root URL of your identity provider; for example, `\https://accounts.google.com` for Google Workspace. +See your identity provider documentation for more information. ++ +[NOTE] +==== +If you are using {product-title-short} version 3.0.49 and later, for *Issuer* you can perform these actions: + +* Prefix your root URL with `https+insecure://` to skip TLS validation. +This configuration is insecure and Red{nbsp}Hat does not recommended it. +Only use it for testing purposes. +* Specify query strings; for example, `?key1=value1&key2=value2` along with the root URL. +{product-title-short} appends the value of *Issuer* as you entered it to the authorization endpoint. +You can use it to customize your provider's login screen. +For example, you can optimize the Google Workspace login screen to a specific hosted domain by using the link:https://developers.google.com/identity/protocols/oauth2/openid-connect#hd-param[`hd` parameter], or preselect an authentication method in `PingFederate` by using the link:https://docs.pingidentity.com/bundle/pingfederate-93/page/nfr1564003024683.html[`pfidpadapterid` parameter]. +==== +** *Client ID*: The OIDC Client ID for your configured project. +** *Client Secret*: Enter the client secret provided by your identity provider (IdP). If you are not using a client secret, which is not recommended, select *Do not use Client Secret*. + +. Assign a *Minimum access role* for users who access {product-title-short} using the selected identity provider. ++ +[TIP] +==== +Set the *Minimum access role* to *Admin* while you complete setup. Later, you can return to the *Access Control* page to set up more tailored access rules based on user metadata from your identity provider. +==== + +. To add access rules for users and groups accessing {product-title-short}, click *Add new rule* in the *Rules* section. For example, to give the *Admin* role to a user called `administrator`, you can use the following key-value pairs to create access rules: ++ +|=== +| *Key* | *Value* +|Name +|administrator +|Role +|Admin +|=== +. Click *Save*. + +.Verification +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. Select the *Auth providers* tab. +. Select the authentication provider for which you want to verify the configuration. +. Select *Test login* from the *Auth Provider* section header. +The *Test login* page opens in a new browser tab. +. Log in with your credentials. +** If you logged in successfully, {product-title-short} shows the `User ID` and `User Attributes` that the identity provider sent for the credentials that you used to log in to the system. +** If your login attempt failed, {product-title-short} shows a message describing why the identity provider's response could not be processed. +. Close the *Test Login* browser tab. diff --git a/modules/configure-pagerduty.adoc b/modules/configure-pagerduty.adoc new file mode 100644 index 000000000000..d7fc5984826d --- /dev/null +++ b/modules/configure-pagerduty.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-pagerduty.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-pagerduty_{context}"] += Configuring PagerDuty + +[role="_abstract"] +Start integrating with PagerDuty by creating a new service and by getting the integration key. + +.Procedure +. Go to *Configuration* -> *Services*. +. Select *Add Services*. +. Under *General Settings*, specify a *Name* and *Description*. +. Under *Integration Setting*, click *Use our API Directly* with *Events v2 API* selected for the *Integration Type* drop-down menu. +. Under *Incident Settings*, select an *Escalation Policy*, and configure notification settings and incident timeouts. +. Accept default settings for *Incident Behavior* and *Alert Grouping*, or configure them as required. +. Click *Add Service*. +. From the *Service Details* page, make note of the *Integration Key*. diff --git a/modules/configure-pki-authentication-portal.adoc b/modules/configure-pki-authentication-portal.adoc new file mode 100644 index 000000000000..0e6b5c36100d --- /dev/null +++ b/modules/configure-pki-authentication-portal.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/enable-pki-authentication.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-pki-authentication-portal_{context}"] += Configuring PKI authentication by using the RHACS portal + +You can configure Public Key Infrastructure (PKI) authentication by using the {product-title-short} portal. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. Click *Create Auth Provider* and select *User Certificates* from the drop-down list. +. In the *Name* field, specify a name for this authentication provider. +. In the *CA certificate(s) (PEM)* field, paste your root CA certificate in PEM format. +. Assign a *Minimum access role* for users who access {product-title-short} using PKI authentication. A user must have the permissions granted to this role or a role with higher permissions to log in to {product-title-short}. ++ +[TIP] +==== +For security, Red{nbsp}Hat recommends first setting the *Minimum access role* to *None* while you complete setup. Later, you can return to the *Access Control* page to set up more tailored access rules based on user metadata from your identity provider. +==== + +. To add access rules for users and groups accessing {product-title-short}, click *Add new rule* in the *Rules* section. For example, to give the *Admin* role to a user called `administrator`, you can use the following key-value pairs to create access rules: ++ +|=== +| *Key* | *Value* +|Name +|administrator +|Role +|Admin +|=== +. Click *Save*. diff --git a/modules/configure-pki-authentication-roxctl.adoc b/modules/configure-pki-authentication-roxctl.adoc new file mode 100644 index 000000000000..271b404efd8d --- /dev/null +++ b/modules/configure-pki-authentication-roxctl.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/enable-pki-authentication.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-pki-authentication-roxctl_{context}"] += Configuring PKI authentication by using the `roxctl` CLI + +You can configure PKI authentication by using the `roxctl` CLI. + +.Procedure +* Run the following command: ++ +[source,terminal] +---- +$ roxctl -e : central userpki create -c -r +---- diff --git a/modules/configure-policy-enforcement-creating-policies.adoc b/modules/configure-policy-enforcement-creating-policies.adoc new file mode 100644 index 000000000000..a68206713a59 --- /dev/null +++ b/modules/configure-policy-enforcement-creating-policies.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-policy-enforcement-creating-policies_{context}"] += Configuring policy enforcement + +[role="_abstract"] +You can configure if {product-title-short} should only inform you with a notification when this policy is violated, or inform you and enforce the policy. Policy enforcement is determined by whether the admission controller is enabled on the cluster and the lifecycle stage of the policy. + +.Procedure + +. Select an enforcement method: +* *Inform*: Include the violation in the violations list. +* *Inform and enforce*: enforce actions. If you select this option, you must select the enforcement behavior for the policy by using the toggle for each lifecycle. +The enforcement behavior you can select depends on the lifecycle stages you selected for the policy in the *Lifecycle* section of the policy definition. +The following enforcement behaviors are available depending on the lifecycle stage: +* *Build*: {product-title-short} fails your continuous integration (CI) builds when images match the criteria of the policy. +* *Deploy*: For the *Deploy* stage, {product-title-short} blocks the creation and update of deployments that match the conditions of the policy if the {product-title-short} admission controller is configured and running. +** In clusters with admission controller enforcement, the Kubernetes or {ocp} API server blocks all noncompliant deployments. In other clusters, {product-title-short} edits noncompliant deployments to prevent pods from being scheduled. +** For existing deployments, policy changes only result in enforcement at the next detection of the criteria, when a Kubernetes event occurs. For more information about enforcement, see "Security policy enforcement for the deploy stage". +* *Runtime*: {product-title-short} deletes all pods when an event in the pods matches the criteria of the policy. ++ +[WARNING] +==== +Policy enforcement can impact running applications or development processes. +Before you enable enforcement options, inform all stakeholders and plan how to respond to automated enforcement actions. +==== \ No newline at end of file diff --git a/modules/configure-policy-notifications.adoc b/modules/configure-policy-notifications.adoc new file mode 100644 index 000000000000..f1e7c751a9da --- /dev/null +++ b/modules/configure-policy-notifications.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-email.adoc +// * integration/integrate-with-pagerduty.adoc +// Set :toolname: before using this module +:_mod-docs-content-type: PROCEDURE +[id="configure-policy-notifications_{context}"] += Configuring policy notifications + +Enable alert notifications for system policies. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. Select one or more policies for which you want to send alerts. +. Under **Bulk actions**, select *Enable notification*. +. In the **Enable notification** window, select the **{toolname}** notifier. ++ +[NOTE] +==== +If you have not configured any other integrations, the system displays a message that no notifiers are configured. +==== +. Click *Enable*. + +[NOTE] +==== +* {product-title} sends notifications on an opt-in basis. +To receive notifications, you must first assign a notifier to the policy. +* Notifications are only sent once for a given alert. +If you have assigned a notifier to a policy, you will not receive a notification unless a violation generates a new alert. + +* {product-title} creates a new alert for the following scenarios: +** A policy violation occurs for the first time in a deployment. +** A runtime-phase policy violation occurs in a deployment after you resolved the previous runtime alert for a policy in that deployment. +==== diff --git a/modules/configure-policy-rules.adoc b/modules/configure-policy-rules.adoc new file mode 100644 index 000000000000..f63f0b364bfa --- /dev/null +++ b/modules/configure-policy-rules.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-policy-rules_{context}"] += Configuring policy rules + +[role="_abstract"] + +You can use policy fields, or criteria, to create rules for your policies. + +.Procedure + +To create a policy rule: + +. In the *Rules* section, configure the conditions that you want to trigger the policy. You can edit the rule titles and click *Add a new rule* to add an additional rule. +. For each rule, click and drag policy fields into the *Policy Section* to add policy fields or criteria. ++ +[NOTE] +==== +The policy fields that are available depend on the lifecycle stage you chose for the policy. For example, criteria under *Kubernetes access policies* or *Networking* are available when creating a policy for the runtime lifecycle, but not when creating a policy for the build lifecycle. See "Policy criteria" in the "Additional resources" section for more information about policy criteria, including information about criteria and the lifecycle phase in which they are available. +==== +. For each field, you can select from options that are specific to the field. These differ depending on the type of field. For example: +* The default behavior for a value that is a string is to match on a policy field, and you click *Not* to indicate when you do not want the field to match. +* Some fields contain a value that is either `true` or `false`. +* Some fields require you to select a value from a drop-down list. +* If you select an attribute with Boolean values `Read-Only Root Filesystem`, the `READ-ONLY` and `WRITABLE` options are available. +* If you select an attribute with compound values `Environment variable`, you can enter values for the `Key`, `Value`, and `Value From` fields, and click the icon to add more values for the available options. ++ +[NOTE] +==== +See "Policy criteria" in the "Additional resources" section for more information. +==== +. To combine multiple values for an attribute, click the *Add* icon. +. Click *Next*. \ No newline at end of file diff --git a/modules/configure-policy-scope.adoc b/modules/configure-policy-scope.adoc new file mode 100644 index 000000000000..c0f08bc6e291 --- /dev/null +++ b/modules/configure-policy-scope.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-policy-scope_{context}"] += Configuring the policy scope + +[role="_abstract"] +You can define the scope of a policy to restrict or allow the policy for certain entities. You can enable the policy to apply only to a specific cluster, namespace, or deployment label. For policies configured for the deploy and runtime lifecycle stages, you can also exclude a cluster, namespace, deployment, or deployment label so that the policy is not applied. For the build lifecycle stage, you can exclude specific images so that, for example, those images will not trigger a violation during the continuous integration part of a continuous integration/continuous delivery (CI/CD) pipeline. + +.Procedure + +. To restrict by scope, click *Add inclusion scope*. This enables this policy to only be applied for a specific cluster, a namespace, or a deployment label. +You can add multiple scopes and also use regular expressions in link:https://github.com/google/re2/wiki/Syntax[RE2 Syntax] for namespaces and labels. +. To exclude by scope, for example, to exclude specific deployments, clusters, namespaces, and deployment labels from the policy, click *Add exclusion scope*. The policy will not apply to the entities that you select. You can add multiple scopes and also use regular expressions in link:https://github.com/google/re2/wiki/Syntax[RE2 Syntax] for namespaces and labels. However, you cannot use regular expressions for selecting deployments. ++ +[NOTE] +==== +This function is only available for policies configured for the deploy and runtime lifecycle stages. +==== +. For policies configured for the build lifecycle stage, you can exclude images from the policy. In the *Exclude images (Build lifecycle only)* field, enter the images that you do not want to trigger a violation for. ++ +[NOTE] +==== +The *Excluded Images* setting only applies when you check images in a continuous integration system with the *Build* lifecycle stage. +It does not have any effect if you use this policy to check running deployments in the *Deploy* lifecycle stage or runtime activities in the *Runtime* lifecycle stage. +==== +. Click *Next*. \ No newline at end of file diff --git a/modules/configure-proxy-during-installation.adoc b/modules/configure-proxy-during-installation.adoc new file mode 100644 index 000000000000..f07be8483a82 --- /dev/null +++ b/modules/configure-proxy-during-installation.adoc @@ -0,0 +1,76 @@ +// Module included in the following assemblies: +// +// * configuration/configure-proxy.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-proxy-during-installation_{context}"] += Configuring a proxy during installation + +When you are installing {product-title} by using the `roxctl` command-line interface (CLI) or Helm, you can specify your proxy configuration during the installation. + +When you run the installer by using the `roxctl central generate` command, the installer generates the secrets and deployment configuration files for your environment. You can configure a proxy by editing the generated configuration secret (YAML) file. Currently, you cannot configure proxies by using the `roxctl` CLI. The configuration is stored in a Kubernetes secret and it is shared by both Central and Scanner. + +.Procedure + +. Open the configuration file `central/proxy-config-secret.yaml` from your deployment bundle directory. ++ +[NOTE] +==== +If you are using Helm the configuration file is at `central/templates/proxy-config-secret.yaml`. +==== +. Edit the fields you want to modify in the configuration file: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + namespace: stackrox + name: proxy-config +type: Opaque +stringData: + config.yaml: |- <4> + # # NOTE: Both central and scanner should be restarted if this secret is changed. + # # While it is possible that some components will pick up the new proxy configuration + # # without a restart, it cannot be guaranteed that this will apply to every possible + # # integration etc. + # url: http://proxy.name:port <2> + # username: username <1> + # password: password <1> + # # If the following value is set to true, the proxy wil NOT be excluded for the default hosts: + # # - *.stackrox, *.stackrox.svc + # # - localhost, localhost.localdomain, 127.0.0.0/8, ::1 + # # - *.local + # omitDefaultExcludes: false + # excludes: # hostnames (may include * components) for which you do not <3> + # # want to use a proxy, like in-cluster repositories. + # - some.domain + # # The following configuration sections allow specifying a different proxy to be used for HTTP(S) connections. + # # If they are omitted, the above configuration is used for HTTP(S) connections as well as TCP connections. + # # If only the `http` section is given, it will be used for HTTPS connections as well. + # # Note: in most cases, a single, global proxy configuration is sufficient. + # http: + # url: http://http-proxy.name:port <2> + # username: username <1> + # password: password <1> + # https: + # url: http://https-proxy.name:port <2> + # username: username <1> + # password: password <1> +---- +<1> Adding a `username` and a `password` is optional, both at the beginning and in the `http` and `https` sections. +<2> The `url` option supports the following URL schemes: +*** `http://` for an HTTP proxy. +*** `https://` for a TLS-enabled HTTP proxy. +*** `socks5://` for a SOCKS5 proxy. +<3> The `excludes` list can contain DNS names (with or without `*` wildcards), IP addresses, or IP blocks in CIDR notation (for example, `10.0.0.0/8`). +The values in this list are applied to all outgoing connections, regardless of protocol. +<4> The `|-` line in the `stringData` section indicates the start of the configuration data. ++ +[NOTE] +==== +* When you first open the file, all values are commented out (by using the `\#` sign at the beginning of the line). +Lines starting with double hash signs `# #` contain explanation of the configuration keys. +* Make sure that when you edit the fields, you maintain an indentation level of two spaces relative to the `config.yaml: |-` line. +==== +. After editing the configuration file, you can proceed with your usual installation. +The updated configuration instructs {product-title} to use the proxy running on the provided address and the port number. diff --git a/modules/configure-proxy-on-an-existing-deployment.adoc b/modules/configure-proxy-on-an-existing-deployment.adoc new file mode 100644 index 000000000000..3cac341ce741 --- /dev/null +++ b/modules/configure-proxy-on-an-existing-deployment.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * configuration/configure-proxy.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-proxy-on-an-existing-deployment_{context}"] += Configuring a proxy on an existing deployment + +To configure a proxy in an existing deployment, you must export the `proxy-config` secret as a YAML file, update your proxy configuration in that file, and upload it as a secret. + +[NOTE] +==== +If you have configured a global proxy on your {ocp} cluster, the Operator Lifecycle Manager (OLM) automatically configures Operators that it manages with the cluster-wide proxy. However, you can also configure installed Operators to override the global proxy or inject a custom certificate authority (CA) certificate. + +For more information, see link:https://docs.openshift.com/container-platform/4.11/operators/admin/olm-configuring-proxy-support.html[Configuring proxy support in Operator Lifecycle Manager]. +==== + +.Procedure + +. Save the existing secret as a YAML file: ++ +[source,terminal] +---- +$ oc -n stackrox get secret proxy-config \ + -o go-template='{{index .data "config.yaml" | \ + base64decode}}{{"\n"}}' > /tmp/proxy-config.yaml +---- +. Edit the fields you want to modify in the YAML configuration file, as specified in the Configure proxy during installation section. +//TODO Link to Configure proxy during installation section +. After you save the changes, run the following command to replace the secret: ++ +[source,terminal] +---- +$ oc -n stackrox create secret generic proxy-config \ + --from-file=config.yaml=/tmp/proxy-config.yaml -o yaml --dry-run | \ + oc label -f - --local -o yaml app.kubernetes.io/name=stackrox | \ + oc apply -f - +---- ++ +[IMPORTANT] +==== +* You must wait for at least 1 minute, until {ocp} propagates your changes to Central and Scanner. +* If you see any issues with outgoing connections after changing the proxy configuration, you must restart your Central and Scanner pods. +==== +//TODO add link to restarting Central and Scanner diff --git a/modules/configure-saml-identity-provider.adoc b/modules/configure-saml-identity-provider.adoc new file mode 100644 index 000000000000..6b3ac211f9a3 --- /dev/null +++ b/modules/configure-saml-identity-provider.adoc @@ -0,0 +1,58 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-okta-identity-cloud.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-saml-identity-provider_{context}"] += Configuring a SAML 2.0 identity provider + +Use the instructions in this section to integrate a Security Assertion Markup Language (SAML) 2.0 identity provider with {product-title} ({product-title-short}). + +.Prerequisites +* You must have permissions to configure identity providers in {product-title-short}. +* For Okta identity providers, you must have an Okta app configured for {product-title-short}. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. Click *Create auth provider* and select *SAML 2.0* from the drop-down list. +. In the *Name* field, enter a name to identify this authentication provider; for example, *Okta* or *Google*. The integration name is shown on the login page to help users select the correct sign-in option. +. In the *ServiceProvider issuer* field, enter the value that you are using as the `Audience URI` or `SP Entity ID` in Okta, or a similar value in other providers. +. Select the type of *Configuration*: +** *Option 1: Dynamic Configuration*: If you select this option, enter the *IdP Metadata URL*, or the URL of *Identity Provider metadata* available from your identity provider console. The configuration values are acquired from the URL. +** *Option 2: Static Configuration*: Copy the required static fields from the *View Setup Instructions* link in the Okta console, or a similar location for other providers: +*** *IdP Issuer* +*** *IdP SSO URL* +*** *Name/ID Format* +*** *IdP Certificate(s) (PEM)* + +. Assign a *Minimum access role* for users who access {product-title-short} using SAML. ++ +[TIP] +==== +Set the *Minimum access role* to *Admin* while you complete setup. Later, you can return to the *Access Control* page to set up more tailored access rules based on user metadata from your identity provider. +==== +. Click *Save*. + +[IMPORTANT] +==== +If your SAML identity provider's authentication response meets the following criteria: + +* Includes a `NotValidAfter` assertion: The user session remains valid until the time specified in the `NotValidAfter` field has elapsed. After the user session expires, users must reauthenticate. +* Does not include a `NotValidAfter` assertion: The user session remains valid for 30 days, and then users must reauthenticate. +==== + +.Verification + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. Select the *Auth Providers* tab. +. Click the authentication provider for which you want to verify the configuration. +. Select *Test login* from the *Auth Provider* section header. +The *Test login* page opens in a new browser tab. +. Sign in with your credentials. +** If you logged in successfully, {product-title-short} shows the `User ID` and `User Attributes` that the identity provider sent for the credentials that you used to log in to the system. +** If your login attempt failed, {product-title-short} shows a message describing why the identity provider's response could not be processed. +. Close the *Test login* browser tab. ++ +[NOTE] +==== +Even if the response indicates successful authentication, you might need to create additional access rules based on the user metadata from your identity provider. +==== diff --git a/modules/configure-short-lived-access.adoc b/modules/configure-short-lived-access.adoc new file mode 100644 index 000000000000..44be0c700712 --- /dev/null +++ b/modules/configure-short-lived-access.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-short-lived-access.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-short-lived-access_{context}"] += Configure short-lived access for an OIDC identity token issuer + +[role="_abstract"] +Start configuring short-lived access for an OpenID Connect (OIDC) identity token issuer. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll to the *Authentication Tokens* category, and then click *Machine access configuration*. +. Click *Create configuration*. +. Select the *configuration type*, choosing one of the following: +** *Generic* if you use an arbitrary OIDC identity token issuer. +** *GitHub Actions* if you plan to access {product-title-short} from GitHub Actions. +. Enter the OIDC identity token issuer. +. Enter the *token lifetime* for tokens issued by the configuration. ++ +[NOTE] +==== +The format for the *token lifetime* is *XhYmZs* and you cannot set it for longer than 24 hours. +==== +. Add rules to the configuration: +** The *Key* is the OIDC token's claim to use. +** The *Value* is the expected OIDC token claim value. +** The *Role* is the role to assign to the token if the OIDC token claim and value exist. ++ +[NOTE] +==== +Rules are similar to Authentication Provider rules to assign roles based on claim values. + +As a general rule, Red{nbsp}Hat recommends to use unique, immutable claims within Rules. The general recommendation is to use the *sub* claim within the OIDC identity token. +For more information about OIDC token claims, see link:https://openid.net/specs/openid-connect-core-1_0.html#Claims[the list of standard OIDC claims]. +==== +. Click *Save*. diff --git a/modules/configure-slack.adoc b/modules/configure-slack.adoc new file mode 100644 index 000000000000..44019c66368b --- /dev/null +++ b/modules/configure-slack.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-slack.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-slack_{context}"] += Configuring Slack + +Start by creating a new Slack app, and get the webhook URL. + +.Prerequisites +. You need an administrator account or a user account with permissions to create webhooks. + +.Procedure +. Create a new Slack app: ++ +[NOTE] +==== +If you want to use an existing Slack app, go to link:https://api.slack.com/apps[https://api.slack.com/apps] and select an app. +==== +.. Go to link:https://api.slack.com/apps/new[https://api.slack.com/apps/new]. +.. Enter the *App Name* and choose a *Development Slack Workspace* to install your app. +.. Click *Create App*. +. On the settings page, *Basic Information* section, select *Incoming Webhooks* (under *Add features and functionality*). +. Turn on the *Activate Incoming Webhooks* toggle. +. Select *Add New Webhook to Workspace*. +. Choose a *channel* that the app will post to, and then select *Authorize*. +The page refreshes and you are sent back to your app settings page. +. Copy the webhook URL located in the *Webhook URLs for Your Workspace* section. + +For more information, see the Slack documentation topic, link:https://api.slack.com/incoming-webhooks#getting_started_with_incoming_webhooks[Getting started with Incoming Webhooks]. diff --git a/modules/configure-sumologic.adoc b/modules/configure-sumologic.adoc new file mode 100644 index 000000000000..ecfec07122f5 --- /dev/null +++ b/modules/configure-sumologic.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-sumologic.adoc +:_mod-docs-content-type: PROCEDURE +[id="configure-sumologic_{context}"] += Configuring Sumo Logic + +Use the *Setup Wizard* to set up *Streaming Data* and get the HTTP URL. + +.Procedure +. Log in to your Sumo Logic Home page and select *Setup Wizard*. +. Move your cursor over to *Set Up Streaming Data* and select *Get Started*. +. On the Select Data Type page, select *Your Custom App*. +. On the Set Up Collection page, select *HTTP Source*. +. Enter a name for *Source Category*, for example, `rhacs` and click *Continue*. +. *Copy* the generated URL. diff --git a/modules/configuring-access-control-and-sending-invitations.adoc b/modules/configuring-access-control-and-sending-invitations.adoc new file mode 100644 index 000000000000..e2d852b9b394 --- /dev/null +++ b/modules/configuring-access-control-and-sending-invitations.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * configuration/inviting-users-to-rhacs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="configuring-access-control-and-sending-invitations_{context}"] += Configuring access control and sending invitations + +By configuring access control in the {product-title-short} portal, you can invite users to your {product-title-short} instance. + +.Procedure + +. In the {product-title-short} portal, go to the *Platform Configuration -> Access Control -> Auth providers* tab, and then click *Invite users*. + +. In the *Invite users* dialog box, provide the following information: +* *Emails to invite*: Enter one or more email addresses of the users you want to invite. Ensure that they are valid email addresses associated with the intended recipients. +* *Provider*: From the drop-down list, select a provider you want to use for each invited user. ++ +[IMPORTANT] +==== +* If you have only one authentication provider available, it is selected by default. +* If multiple authentication providers are available and at least one of them is `Red{nbsp}Hat SSO` or `Default Internal SSO`, that provider is selected by default. +* If multiple authentication providers are available, but none of them is `Red{nbsp}Hat SSO` or `Default Internal SSO`, you are prompted to select one manually. +* If you have not yet set up an authentication provider, a warning message appears and the form is disabled. Click the link, which takes you to the *Access Control* section to configure an authentication provider. +==== +* *Role*: From the drop-down list, select the role to assign to each invited user. + +. Click *Invite users*. +. On the confirmation dialog box, you receive a confirmation that the users have been created with the selected role. +. Copy the one or more email addresses and the message into an email that you create in your own email client, and send it to the users. +. Click *Done*. + +.Verification + +. In the {product-title-short} portal, go to the *Platform Configuration -> Access Control -> Auth providers* tab. +. Select the authentication provider you used to invite users. +. Scroll down to the *Rules* section. +. Verify that the user emails and authentication provider roles have been added to the list. \ No newline at end of file diff --git a/modules/configuring-and-using-the-roxctl-cli-in-rhacs-cloud-service.adoc b/modules/configuring-and-using-the-roxctl-cli-in-rhacs-cloud-service.adoc new file mode 100644 index 000000000000..a302d9391887 --- /dev/null +++ b/modules/configuring-and-using-the-roxctl-cli-in-rhacs-cloud-service.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * cli/using-the-roxctl-cli.adoc + +:_mod-docs-content-type: PROCEDURE +[id="configuring-and-using-the-roxctl-cli-in-rhacs-cloud-service_{context}"] += Configuring and using the roxctl CLI in {product-title-managed-short} + +.Procedure + +* Export the `ROX_API_TOKEN` by running the following command: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN= +---- + +* Export the `ROX_ENDPOINT` by running the following command: ++ +[source,terminal] +---- +$ export ROX_ENDPOINT=
        : +---- + +* You can use the `--help` option to get more information about the commands. + +* In {rh-rhacscs-first}, when using `roxctl` commands that require the Central address, use the *Central instance address* as displayed in the *Instance Details* section of the {cloud-console}. For example, use `acs-ABCD12345.acs.rhcloud.com` instead of `acs-data-ABCD12345.acs.rhcloud.com`. \ No newline at end of file diff --git a/modules/configuring-assumerole-acs.adoc b/modules/configuring-assumerole-acs.adoc new file mode 100644 index 000000000000..7977cd6320f0 --- /dev/null +++ b/modules/configuring-assumerole-acs.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="configuring-assumerole-acs_{context}"] += Configuring AssumeRole in {product-title-short} + +[role="_abstract"] +After configuring AssumeRole in ECR, you can integrate {product-title} with Amazon Elastic Container Registry (ECR) by using AssumeRole. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Amazon ECR*. +. Click *New Integration*. +. Enter the details for the following fields: +.. *Integration Name*: The name of the integration. +.. *Registry ID*: The ID of the registry. +.. *Region*: The region for the registry; for example, `us-west-1`. +. If you are using IAM, select *Use container IAM role*. Otherwise, clear the *Use custom IAM role* box and enter the *Access key ID* and *Secret access key*. +. If you are using AssumeRole, select *Use AssumeRole* and enter the details for the following fields: +.. *AssumeRole ID*: The ID of the role to assume. +.. *AssumeRole External ID* (optional): If you are using an link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html[external ID with AssumeRole], you can enter it here. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/configuring-assumerole-with-iam.adoc b/modules/configuring-assumerole-with-iam.adoc new file mode 100644 index 000000000000..4550b5c8b067 --- /dev/null +++ b/modules/configuring-assumerole-with-iam.adoc @@ -0,0 +1,67 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="configuring-assumerole-with-iam_{context}"] += Configuring AssumeRole with container IAM + +[role="_abstract"] +Before you can use AssumeRole with {product-title}, you must first configure it. + +.Procedure +. Enable the IAM OIDC provider for your EKS cluster: ++ +[source,terminal] +---- +$ eksctl utils associate-iam-oidc-provider --cluster --approve +---- +. link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html[Create an IAM role] for your EKS cluster. +. Associate the newly created role with a service account: ++ +[source,terminal] +---- +$ kubectl -n stackrox annotate sa central eks.amazonaws.com/role-arn=arn:aws:iam::67890:role/ +---- +. Restart Central to apply the changes. ++ +[source,terminal] +---- +$ kubectl -n stackrox delete pod -l app=central +---- +. Assign the role to a policy that allows the role to assume another role as required: ++ +[source,json] +---- +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "arn:aws:iam:::role/" <1> + } + ] +} +---- +<1> Replace `` with the role you want to assume. +. Update the trust relationship for the role you want to assume: ++ +[source,json] +---- +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": [ + "arn:aws:iam:::role/" <1> + ] + }, + "Action": "sts:AssumeRole" + } + ] +} +---- +<1> The `` should match with the new role you have created earlier. diff --git a/modules/configuring-assumerole-without-iam.adoc b/modules/configuring-assumerole-without-iam.adoc new file mode 100644 index 000000000000..8884c6ae06b8 --- /dev/null +++ b/modules/configuring-assumerole-without-iam.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="configuring-assumerole-without-iam_{context}"] += Configuring AssumeRole without container IAM + +[role="_abstract"] +To use AssumeRole without container IAM, you must use an access and a secret key to authenticate as an link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[AWS user with programmatic access]. + +.Procedure +. Depending on whether the AssumeRole user is in the same account as the ECR registry or in a different account, you must either: +* Create a new role with the desired permissions if the user for which you want to assume role is in the same account as the ECR registry. ++ +[NOTE] +==== +When creating the role, you can choose any trusted entity as required. However, you must modify it after creation. +==== +* Or, you must provide permissions to access the ECR registry and define its trust relationship if the user is in a different account than the ECR registry: ++ +[source,json] +---- +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "arn:aws:iam:::role/" <1> + } + ] +} +---- +<1> Replace `` with the role you want to assume. +. Configure the trust relationship of the role by including the user ARN under the *Principal* field: ++ +[source,json] +---- +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": [ + "arn:aws:iam:::user/" + ] + }, + "Action": "sts:AssumeRole" + } + ] +} +---- diff --git a/modules/configuring-cluster-loader.adoc b/modules/configuring-cluster-loader.adoc deleted file mode 100644 index 7823f1e7f78d..000000000000 --- a/modules/configuring-cluster-loader.adoc +++ /dev/null @@ -1,209 +0,0 @@ -// Module included in the following assemblies: -// -// scalability_and_performance/using-cluster-loader.adoc - -[id="configuring_cluster_loader_{context}"] -= Configuring Cluster Loader - -The tool creates multiple namespaces (projects), which contain multiple templates or pods. - -== Example Cluster Loader configuration file - -Cluster Loader’s configuration file is a basic YAML file: - -[source,yaml] ----- -provider: local <1> -ClusterLoader: - cleanup: true - projects: - - num: 1 - basename: clusterloader-cakephp-mysql - tuning: default - ifexists: reuse - templates: - - num: 1 - file: cakephp-mysql.json - - - num: 1 - basename: clusterloader-dancer-mysql - tuning: default - ifexists: reuse - templates: - - num: 1 - file: dancer-mysql.json - - - num: 1 - basename: clusterloader-django-postgresql - tuning: default - ifexists: reuse - templates: - - num: 1 - file: django-postgresql.json - - - num: 1 - basename: clusterloader-nodejs-mongodb - tuning: default - ifexists: reuse - templates: - - num: 1 - file: quickstarts/nodejs-mongodb.json - - - num: 1 - basename: clusterloader-rails-postgresql - tuning: default - templates: - - num: 1 - file: rails-postgresql.json - - tuningsets: <2> - - name: default - pods: - stepping: <3> - stepsize: 5 - pause: 0 s - rate_limit: <4> - delay: 0 ms ----- -<1> Optional setting for end-to-end tests. Set to `local` to avoid extra log messages. -<2> The tuning sets allow rate limiting and stepping, the ability to create several batches of pods while pausing in between sets. Cluster Loader monitors completion of the previous step before continuing. -<3> Stepping will pause for `M` seconds after each `N` objects are created. -<4> Rate limiting will wait `M` milliseconds between the creation of objects. - -This example assumes that references to any external template files or pod spec files are also mounted into the container. - -[IMPORTANT] -==== -If you are running Cluster Loader on Microsoft Azure, then you must set the `AZURE_AUTH_LOCATION` variable to a file that contains the output of -`terraform.azure.auto.tfvars.json`, which is present in the installer directory. -==== - -== Configuration fields - -.Top-level Cluster Loader Fields -|=== -|Field |Description - -|`cleanup` -|Set to `true` or `false`. One definition per configuration. If set to `true`, `cleanup` deletes all namespaces (projects) created by Cluster Loader at the end of the test. - -|`projects` -|A sub-object with one or many definition(s). Under `projects`, each namespace to create is defined and `projects` has several mandatory subheadings. - -|`tuningsets` -|A sub-object with one definition per configuration. `tuningsets` allows the user to define a tuning set to add configurable timing to project or object creation (pods, templates, and so on). - -|`sync` -|An optional sub-object with one definition per configuration. Adds synchronization possibilities during object creation. -|=== - -.Fields under `projects` -|=== -|Field |Description - -|`num` -|An integer. One definition of the count of how many projects to create. - -|`basename` -|A string. One definition of the base name for the project. The count of identical namespaces will be appended to `Basename` to prevent collisions. - -|`tuning` -|A string. One definition of what tuning set you want to apply to the objects, which you deploy inside this namespace. - -|`ifexists` -|A string containing either `reuse` or `delete`. Defines what the tool does if it finds a project or namespace that has the same name of the project or namespace it creates during execution. - -|`configmaps` -|A list of key-value pairs. The key is the config map name and the value is a path to a file from which you create the config map. - -|`secrets` -|A list of key-value pairs. The key is the secret name and the value is a path to a file from which you create the secret. - -|`pods` -|A sub-object with one or many definition(s) of pods to deploy. - -|`templates` -|A sub-object with one or many definition(s) of templates to deploy. -|=== - -.Fields under `pods` and `templates` -|=== -|Field |Description - -|`num` -|An integer. The number of pods or templates to deploy. - -|`image` -|A string. The docker image URL to a repository where it can be pulled. - -|`basename` -| A string. One definition of the base name for the template (or pod) that you want to create. - -|`file` -|A string. The path to a local file, which is either a pod spec or template to be created. - -|`parameters` -|Key-value pairs. Under `parameters`, you can specify a list of values to override in the pod or template. -|=== - -.Fields under `tuningsets` -|=== -|Field |Description - -|`name` -|A string. The name of the tuning set which will match the name specified when defining a tuning in a project. - -|`pods` -|A sub-object identifying the `tuningsets` that will apply to pods. - -|`templates` -|A sub-object identifying the `tuningsets` that will apply to templates. -|=== - -.Fields under `tuningsets` `pods` or `tuningsets` `templates` -|=== -|Field |Description - -|`stepping` -|A sub-object. A stepping configuration used if you want to create an object in a step creation pattern. - -|`rate_limit` -|A sub-object. A rate-limiting tuning set configuration to limit the object creation rate. -|=== - -.Fields under `tuningsets` `pods` or `tuningsets` `templates`, `stepping` -|=== -|Field |Description - -|`stepsize` -|An integer. How many objects to create before pausing object creation. - -|`pause` -|An integer. How many seconds to pause after creating the number of objects defined in `stepsize`. - -|`timeout` -|An integer. How many seconds to wait before failure if the object creation is not successful. - -|`delay` -|An integer. How many milliseconds (ms) to wait between creation requests. -|=== - -.Fields under `sync` -|=== -|Field |Description - -|`server` -|A sub-object with `enabled` and `port` fields. The boolean `enabled` defines whether to start an HTTP server for pod synchronization. The integer `port` defines the HTTP server port to listen on (`9090` by default). - -|`running` -|A boolean. Wait for pods with labels matching `selectors` to go into `Running` state. - -|`succeeded` -|A boolean. Wait for pods with labels matching `selectors` to go into `Completed` state. - -|`selectors` -|A list of selectors to match pods in `Running` or `Completed` states. - -|`timeout` -|A string. The synchronization timeout period to wait for pods in `Running` or `Completed` states. For values that are not `0`, use units: [ns\|us\|ms\|s\|m\|h]. -|=== diff --git a/modules/configuring-cluster-monitoring.adoc b/modules/configuring-cluster-monitoring.adoc deleted file mode 100644 index 5e57bb82b13b..000000000000 --- a/modules/configuring-cluster-monitoring.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/scaling-cluster-monitoring-operator.adoc - -[id="configuring-cluster-monitoring_{context}"] -= Configuring cluster monitoring - -.Procedure - -To increase the storage capacity for Prometheus: - -. Create a YAML configuration file, `cluster-monitoring-config.yml`. For example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -data: - config.yaml: | - prometheusOperator: - baseImage: quay.io/coreos/prometheus-operator - prometheusConfigReloaderBaseImage: quay.io/coreos/prometheus-config-reloader - configReloaderBaseImage: quay.io/coreos/configmap-reload - nodeSelector: - node-role.kubernetes.io/infra: "" - prometheusK8s: - retention: {{PROMETHEUS_RETENTION_PERIOD}} <1> - baseImage: openshift/prometheus - nodeSelector: - node-role.kubernetes.io/infra: "" - volumeClaimTemplate: - spec: - storageClassName: gp2 - resources: - requests: - storage: {{PROMETHEUS_STORAGE_SIZE}} <2> - alertmanagerMain: - baseImage: openshift/prometheus-alertmanager - nodeSelector: - node-role.kubernetes.io/infra: "" - volumeClaimTemplate: - spec: - storageClassName: gp2 - resources: - requests: - storage: {{ALERTMANAGER_STORAGE_SIZE}} <3> - nodeExporter: - baseImage: openshift/prometheus-node-exporter - kubeRbacProxy: - baseImage: quay.io/coreos/kube-rbac-proxy - kubeStateMetrics: - baseImage: quay.io/coreos/kube-state-metrics - nodeSelector: - node-role.kubernetes.io/infra: "" - grafana: - baseImage: grafana/grafana - nodeSelector: - node-role.kubernetes.io/infra: "" - auth: - baseImage: openshift/oauth-proxy - k8sPrometheusAdapter: - nodeSelector: - node-role.kubernetes.io/infra: "" -metadata: - name: cluster-monitoring-config -namespace: openshift-monitoring ----- -<1> A typical value is `PROMETHEUS_RETENTION_PERIOD=15d`. Units are measured in -time using one of these suffixes: s, m, h, d. -<2> A typical value is `PROMETHEUS_STORAGE_SIZE=2000Gi`. Storage values can be a -plain integer or as a fixed-point integer using one of these suffixes: E, P, T, -G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. -<3> A typical value is `ALERTMANAGER_STORAGE_SIZE=20Gi`. Storage values can be a -plain integer or as a fixed-point integer using one of these suffixes: E, P, T, -G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. - -. Set the values like the retention period and storage sizes. - -. Apply the changes by running: -+ -[source,terminal] ----- -$ oc create -f cluster-monitoring-config.yml ----- diff --git a/modules/configuring-dynamic-admission.adoc b/modules/configuring-dynamic-admission.adoc deleted file mode 100644 index 04005eb31157..000000000000 --- a/modules/configuring-dynamic-admission.adoc +++ /dev/null @@ -1,385 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/admission-plug-ins.adoc - -[id="configuring-dynamic-admission_{context}"] -= Configuring dynamic admission - -This procedure outlines high-level steps to configure dynamic admission. The functionality of the admission chain is extended by configuring a webhook admission plug-in to call out to a webhook server. - -The webhook server is also configured as an aggregated API server. This allows other {product-title} components to communicate with the webhook using internal credentials and facilitates testing using the `oc` command. Additionally, this enables role based access control (RBAC) into the webhook and prevents token information from other API servers from being disclosed to the webhook. - -.Prerequisites - -* An {product-title} account with cluster administrator access. -* The {product-title} CLI (`oc`) installed. -* A published webhook server container image. - -.Procedure - -. Build a webhook server container image and make it available to the cluster using an image registry. - -. Create a local CA key and certificate and use them to sign the webhook server's certificate signing request (CSR). - -. Create a new project for webhook resources: -+ -[source,terminal] ----- -$ oc new-project my-webhook-namespace <1> ----- -<1> Note that the webhook server might expect a specific name. - -. Define RBAC rules for the aggregated API service in a file called `rbac.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: List -items: - -- apiVersion: rbac.authorization.k8s.io/v1 <1> - kind: ClusterRoleBinding - metadata: - name: auth-delegator-my-webhook-namespace - roleRef: - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io - name: system:auth-delegator - subjects: - - kind: ServiceAccount - namespace: my-webhook-namespace - name: server - -- apiVersion: rbac.authorization.k8s.io/v1 <2> - kind: ClusterRole - metadata: - annotations: - name: system:openshift:online:my-webhook-server - rules: - - apiGroups: - - online.openshift.io - resources: - - namespacereservations <3> - verbs: - - get - - list - - watch - -- apiVersion: rbac.authorization.k8s.io/v1 <4> - kind: ClusterRole - metadata: - name: system:openshift:online:my-webhook-requester - rules: - - apiGroups: - - admission.online.openshift.io - resources: - - namespacereservations <5> - verbs: - - create - -- apiVersion: rbac.authorization.k8s.io/v1 <6> - kind: ClusterRoleBinding - metadata: - name: my-webhook-server-my-webhook-namespace - roleRef: - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io - name: system:openshift:online:my-webhook-server - subjects: - - kind: ServiceAccount - namespace: my-webhook-namespace - name: server - -- apiVersion: rbac.authorization.k8s.io/v1 <7> - kind: RoleBinding - metadata: - namespace: kube-system - name: extension-server-authentication-reader-my-webhook-namespace - roleRef: - kind: Role - apiGroup: rbac.authorization.k8s.io - name: extension-apiserver-authentication-reader - subjects: - - kind: ServiceAccount - namespace: my-webhook-namespace - name: server - -- apiVersion: rbac.authorization.k8s.io/v1 <8> - kind: ClusterRole - metadata: - name: my-cluster-role - rules: - - apiGroups: - - admissionregistration.k8s.io - resources: - - validatingwebhookconfigurations - - mutatingwebhookconfigurations - verbs: - - get - - list - - watch - - apiGroups: - - "" - resources: - - namespaces - verbs: - - get - - list - - watch - -- apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: my-cluster-role - roleRef: - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io - name: my-cluster-role - subjects: - - kind: ServiceAccount - namespace: my-webhook-namespace - name: server ----- -<1> Delegates authentication and authorization to the webhook server API. -<2> Allows the webhook server to access cluster resources. -<3> Points to resources. This example points to the `namespacereservations` resource. -<4> Enables the aggregated API server to create admission reviews. -<5> Points to resources. This example points to the `namespacereservations` resource. -<6> Enables the webhook server to access cluster resources. -<7> Role binding to read the configuration for terminating authentication. -<8> Default cluster role and cluster role bindings for an aggregated API server. - -. Apply those RBAC rules to the cluster: -+ -[source,terminal] ----- -$ oc auth reconcile -f rbac.yaml ----- - -. Create a YAML file called `webhook-daemonset.yaml` that is used to deploy a webhook as a daemon set server in a namespace: -+ -[source,yaml] ----- -apiVersion: apps/v1 -kind: DaemonSet -metadata: - namespace: my-webhook-namespace - name: server - labels: - server: "true" -spec: - selector: - matchLabels: - server: "true" - template: - metadata: - name: server - labels: - server: "true" - spec: - serviceAccountName: server - containers: - - name: my-webhook-container <1> - image: /: <2> - imagePullPolicy: IfNotPresent - command: - - <3> - ports: - - containerPort: 8443 <4> - volumeMounts: - - mountPath: /var/serving-cert - name: serving-cert - readinessProbe: - httpGet: - path: /healthz - port: 8443 <5> - scheme: HTTPS - volumes: - - name: serving-cert - secret: - defaultMode: 420 - secretName: server-serving-cert ----- -<1> Note that the webhook server might expect a specific container name. -<2> Points to a webhook server container image. Replace `/:` with the appropriate value. -<3> Specifies webhook container run commands. Replace `` with the appropriate value. -<4> Defines the target port within pods. This example uses port 8443. -<5> Specifies the port used by the readiness probe. This example uses port 8443. - -. Deploy the daemon set: -+ -[source,terminal] ----- -$ oc apply -f webhook-daemonset.yaml ----- - -. Define a secret for the service serving certificate signer, within a YAML file called `webhook-secret.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - namespace: my-webhook-namespace - name: server-serving-cert -type: kubernetes.io/tls -data: - tls.crt: <1> - tls.key: <2> ----- -<1> References the signed webhook server certificate. Replace `` with the appropriate certificate in base64 format. -<2> References the signed webhook server key. Replace `` with the appropriate key in base64 format. - -. Create the secret: -+ -[source,terminal] ----- -$ oc apply -f webhook-secret.yaml ----- - -. Define a service account and service, within a YAML file called `webhook-service.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: List -items: - -- apiVersion: v1 - kind: ServiceAccount - metadata: - namespace: my-webhook-namespace - name: server - -- apiVersion: v1 - kind: Service - metadata: - namespace: my-webhook-namespace - name: server - annotations: - service.alpha.openshift.io/serving-cert-secret-name: server-serving-cert - spec: - selector: - server: "true" - ports: - - port: 443 <1> - targetPort: 8443 <2> ----- -<1> Defines the port that the service listens on. This example uses port 443. -<2> Defines the target port within pods that the service forwards connections to. This example uses port 8443. - -. Expose the webhook server within the cluster: -+ -[source,terminal] ----- -$ oc apply -f webhook-service.yaml ----- - -. Define a custom resource definition for the webhook server, in a file called `webhook-crd.yaml`: -+ -[source,yaml] ----- -apiVersion: apiextensions.k8s.io/v1beta1 -kind: CustomResourceDefinition -metadata: - name: namespacereservations.online.openshift.io <1> -spec: - group: online.openshift.io <2> - version: v1alpha1 <3> - scope: Cluster <4> - names: - plural: namespacereservations <5> - singular: namespacereservation <6> - kind: NamespaceReservation <7> ----- -<1> Reflects `CustomResourceDefinition` `spec` values and is in the format `.`. This example uses the `namespacereservations` resource. -<2> REST API group name. -<3> REST API version name. -<4> Accepted values are `Namespaced` or `Cluster`. -<5> Plural name to be included in URL. -<6> Alias seen in `oc` output. -<7> The reference for resource manifests. - -. Apply the custom resource definition: -+ -[source,terminal] ----- -$ oc apply -f webhook-crd.yaml ----- - -. Configure the webhook server also as an aggregated API server, within a file called `webhook-api-service.yaml`: -+ -[source,yaml] ----- -apiVersion: apiregistration.k8s.io/v1beta1 -kind: APIService -metadata: - name: v1beta1.admission.online.openshift.io -spec: - caBundle: <1> - group: admission.online.openshift.io - groupPriorityMinimum: 1000 - versionPriority: 15 - service: - name: server - namespace: my-webhook-namespace - version: v1beta1 ----- -<1> A PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace `` with the appropriate certificate in base64 format. - -. Deploy the aggregated API service: -+ -[source,terminal] ----- -$ oc apply -f webhook-api-service.yaml ----- - -. Define the webhook admission plug-in configuration within a file called `webhook-config.yaml`. This example uses the validating admission plug-in: -+ -[source,yaml] ----- -apiVersion: admissionregistration.k8s.io/v1beta1 -kind: ValidatingWebhookConfiguration -metadata: - name: namespacereservations.admission.online.openshift.io <1> -webhooks: -- name: namespacereservations.admission.online.openshift.io <2> - clientConfig: - service: <3> - namespace: default - name: kubernetes - path: /apis/admission.online.openshift.io/v1beta1/namespacereservations <4> - caBundle: <5> - rules: - - operations: - - CREATE - apiGroups: - - project.openshift.io - apiVersions: - - "*" - resources: - - projectrequests - - operations: - - CREATE - apiGroups: - - "" - apiVersions: - - "*" - resources: - - namespaces - failurePolicy: Fail ----- -<1> Name for the `ValidatingWebhookConfiguration` object. This example uses the `namespacereservations` resource. -<2> Name of the webhook to call. This example uses the `namespacereservations` resource. -<3> Enables access to the webhook server through the aggregated API. -<4> The webhook URL used for admission requests. This example uses the `namespacereservation` resource. -<5> A PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace `` with the appropriate certificate in base64 format. - -. Deploy the webhook: -+ -[source,terminal] ----- -$ oc apply -f webhook-config.yaml ----- - -. Verify that the webhook is functioning as expected. For example, if you have configured dynamic admission to reserve specific namespaces, confirm that requests to create those namespaces are rejected and that requests to create non-reserved namespaces succeed. diff --git a/modules/configuring-firewall.adoc b/modules/configuring-firewall.adoc deleted file mode 100644 index 5f3e6477d9f3..000000000000 --- a/modules/configuring-firewall.adoc +++ /dev/null @@ -1,123 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/configuring-firewall.adoc - -[id="configuring-firewall_{context}"] -= Configuring your firewall for {product-title} - -Before you install {product-title}, you must configure your firewall to grant access to the sites that {product-title} requires. - -There are no special configuration considerations for services running on only controller nodes versus worker nodes. - -.Procedure - -. Allowlist the following registry URLs: -+ -[cols="3,4",options="header"] -|=== -|URL | Function -|`registry.redhat.io` -|Provides core container images - -|`quay.io` -|Provides core container images - -|`sso.redhat.com` -|The `https://cloud.redhat.com/openshift` site uses authentication from `sso.redhat.com` - -|`openshift.org` -|Provides {op-system-first} images -|=== -+ -When you add a site such as `quay.io` to your allowlist, do not add a wildcard entry such as `*.quay.io` to your denylist. In most cases, image registries use a content delivery network (CDN) to serve images. If a firewall blocks access, then image downloads are denied when the initial download request is redirected to a host name such as `cdn01.quay.io`. - -. Allowlist any site that provides resources for a language or framework that your builds require. - -. If you do not disable Telemetry, you must grant access to the following URLs to access Red Hat Insights: -+ -[cols="3,4",options="header"] -|=== -|URL | Function - -|`cert-api.access.redhat.com` -|Required for Telemetry - -|`api.access.redhat.com` -|Required for Telemetry - -|`infogw.api.openshift.com` -|Required for Telemetry - -|`https://cloud.redhat.com/api/ingress` -|Required for Telemetry and for `insights-operator` -|=== - -. If you use Amazon Web Services (AWS), Microsoft Azure, or Google Cloud Platform (GCP) to host your cluster, you must grant access to the URLs that provide the cloud provider API and DNS for that cloud: -+ -[cols="2a,8a,8a",options="header"] -|=== -|Cloud |URL |Function - -.2+|AWS -|`*.amazonaws.com` -|Required to access AWS services and resources. Review the link:https://docs.aws.amazon.com/general/latest/gr/rande.html[AWS Service Endpoints] in the AWS documentation to determine the exact endpoints to allow for the regions that you use. - -|`oso-rhc4tp-docker-registry.s3-us-west-2.amazonaws.com` -|Required to access AWS services and resources when using strict security requirements. Review the link:https://docs.aws.amazon.com/general/latest/gr/rande.html[AWS Service Endpoints] in the AWS documentation to determine the exact endpoints to allow for the regions that you use. - -.2+|GCP -|`*.googleapis.com` -|Required to access GCP services and resources. Review link:https://cloud.google.com/endpoints/[Cloud Endpoints] in the GCP documentation to determine the endpoints to allow for your APIs. - -|`accounts.google.com` -| Required to access your GCP account. - -|Azure -|`management.azure.com` -|Required to access Azure services and resources. Review the link:https://docs.microsoft.com/en-us/rest/api/azure/[Azure REST API Reference] in the Azure documentation to determine the endpoints to allow for your APIs. - -|=== - -. Allowlist the following URLs: -+ -[cols="3,4",options="header"] -|=== -|URL | Function - -|`mirror.openshift.com` -|Required to access mirrored installation content and images. This site is also a source of release image signatures, although the Cluster Version Operator needs only a single functioning source. - -|`storage.googleapis.com/openshift-release` -|A source of release image signatures, although the Cluster Version Operator needs only a single functioning source. - -|`*.apps..` -|Required to access the default cluster routes unless you set an ingress wildcard during installation. - -|`quay-registry.s3.amazonaws.com` -|Required to access Quay image content in AWS. - -|`api.openshift.com` -|Required to check if updates are available for the cluster. - -|`art-rhcos-ci.s3.amazonaws.com` -|Required to download {op-system-first} images. - -|`api.openshift.com` -|Required for your cluster token. - -|`cloud.redhat.com/openshift` -|Required for your cluster token. - -|`registry.access.redhat.com` -|Required for `odo` CLI. -|=== -+ -Operators require route access to perform health checks. Specifically, the -authentication and web console Operators connect to two routes to verify that -the routes work. If you are the cluster administrator and do not want to allow -`*.apps..`, then allow these routes: -+ -* `oauth-openshift.apps..` -* `console-openshift-console.apps..`, or the host name -that is specified in the `spec.route.hostname` field of the -`consoles.operator/cluster` object if the field is not empty. diff --git a/modules/configuring-hpa-based-on-application-metrics.adoc b/modules/configuring-hpa-based-on-application-metrics.adoc deleted file mode 100644 index f0595dde6ba7..000000000000 --- a/modules/configuring-hpa-based-on-application-metrics.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/configuring-hpa-for-an-application.adoc - -[id="configuring-hpa-based-on-application-metrics_{context}"] -= Configuring HPA based on application metrics - -If you configure an application to export metrics, you can set up Horizontal Pod Autoscaling (HPA) based on these metrics. - -.Procedure - -. Create a YAML file for your configuration. In this example, it is called `deploy.yaml`. - -. Add configuration for deploying the horizontal pod autoscaler for the application. This example configures and deploys HPA based on the application `http_requests_per_second` metric for the sample application configured in the "Application monitoring" section: -+ -[source,yaml] ----- -apiVersion: autoscaling/v2beta1 -kind: HorizontalPodAutoscaler -metadata: - name: example-app-scaler - namespace: default -spec: - scaleTargetRef: - apiVersion: apps/v1 - kind: Deployment - name: example-app <1> - minReplicas: 3 <2> - maxReplicas: 10 <3> - metrics: - - type: Pods - pods: - metricName: http_requests_per_second <4> - targetAverageValue: 10 <5> ----- -<1> `name` specifies the application. -<2> `minReplicas` specifies the minimum number of replicas for the HPA to maintain for the application. -<3> `maxReplicas` specifies the maximum number of replicas for the HPA to maintain for the application. -<4> `metricName` specifies the metric upon which HPA is based. Here, specify the metric you previously exposed for your application. -<5> `targetAverageValue` specifies the value of the metric for the HPA to try to maintain by increasing or decreasing the number of replicas. - -. Apply the configuration file to the cluster: -+ -[source,terminal] ----- -$ oc apply -f deploy.yaml ----- diff --git a/modules/configuring-huge-pages.adoc b/modules/configuring-huge-pages.adoc deleted file mode 100644 index 8837d8d978fd..000000000000 --- a/modules/configuring-huge-pages.adoc +++ /dev/null @@ -1,165 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="configuring-huge-pages_{context}"] -= Configuring huge pages - -Nodes must pre-allocate huge pages used in an {product-title} cluster. There are two ways of reserving huge pages: at boot time and at run time. Reserving at boot time increases the possibility of success because the memory has not yet been significantly fragmented. The Node Tuning Operator currently supports boot time allocation of huge pages on specific nodes. - -== At boot time - -.Procedure - -To minimize node reboots, the order of the steps below needs to be followed: - -. Label all nodes that need the same huge pages setting by a label. -+ -[source,terminal] ----- -$ oc label node node-role.kubernetes.io/worker-hp= ----- - -. Create a file with the following content and name it `hugepages-tuned-boottime.yaml`: -+ -[source,yaml] ----- -apiVersion: tuned.openshift.io/v1 -kind: Tuned -metadata: - name: hugepages <1> - namespace: openshift-cluster-node-tuning-operator -spec: - profile: <2> - - data: | - [main] - summary=Boot time configuration for hugepages - include=openshift-node - [bootloader] - cmdline_openshift_node_hugepages=hugepagesz=2M hugepages=50 <3> - name: openshift-node-hugepages - - recommend: - - machineConfigLabels: <4> - machineconfiguration.openshift.io/role: "worker-hp" - priority: 30 - profile: openshift-node-hugepages ----- -<1> Set the `name` of the Tuned resource to `hugepages`. -<2> Set the `profile` section to allocate huge pages. -<3> Note the order of parameters is important as some platforms support huge pages of various sizes. -<4> Enable machine config pool based matching. - -. Create the Tuned `hugepages` object -+ -[source,terminal] ----- -$ oc create -f hugepages-tuned-boottime.yaml ----- - -. Create a file with the following content and name it `hugepages-mcp.yaml`: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool -metadata: - name: worker-hp - labels: - worker-hp: "" -spec: - machineConfigSelector: - matchExpressions: - - {key: machineconfiguration.openshift.io/role, operator: In, values: [worker,worker-hp]} - nodeSelector: - matchLabels: - node-role.kubernetes.io/worker-hp: "" ----- - -. Create the machine config pool: -+ -[source,terminal] ----- -$ oc create -f hugepages-mcp.yaml ----- - -Given enough non-fragmented memory, all the nodes in the `worker-hp` machine config pool should now have 50 2Mi huge pages allocated. - -[source,terminal] ----- -$ oc get node -o jsonpath="{.status.allocatable.hugepages-2Mi}" -100Mi ----- - -[WARNING] -==== -This functionality is currently only supported on {op-system-first} 8.x worker nodes. On {op-system-base-full} 7.x worker nodes the TuneD `[bootloader]` plug-in is currently not supported. -==== - -//// -For run-time allocation, kubelet changes are needed, see BZ1819719. -== At run time - -.Procedure - -. Label the node so that the Node Tuning Operator knows on which node to apply the tuned profile, which describes how many huge pages should be allocated: -+ -[source,terminal] ----- -$ oc label node hugepages=true ----- - -. Create a file with the following content and name it `hugepages-tuned-runtime.yaml`: -+ -[source,yaml] ----- -apiVersion: tuned.openshift.io/v1 -kind: Tuned -metadata: - name: hugepages <1> - namespace: openshift-cluster-node-tuning-operator -spec: - profile: <2> - - data: | - [main] - summary=Run time configuration for hugepages - include=openshift-node - [vm] - transparent_hugepages=never - [sysfs] - /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages=50 - name: node-hugepages - - recommend: - - match: <3> - - label: hugepages - priority: 30 - profile: node-hugepages ----- -<1> Set the `name` of the Tuned resource to `hugepages`. -<2> Set the `profile` section to allocate huge pages. -<3> Set the `match` section to associate the profile to nodes with the `hugepages` label. - -. Create the custom `hugepages` tuned profile by using the `hugepages-tuned-runtime.yaml` file: -+ -[source,terminal] ----- -$ oc create -f hugepages-tuned-runtime.yaml ----- - -. After creating the profile, the Operator applies the new profile to the correct -node and allocates huge pages. Check the logs of a tuned pod on a node using -huge pages to verify: -+ -[source,terminal] ----- -$ oc logs \ - -n openshift-cluster-node-tuning-operator | grep 'applied$' | tail -n1 ----- -+ ----- -2019-08-08 07:20:41,286 INFO tuned.daemon.daemon: static tuning from profile 'node-hugepages' applied ----- - -//// diff --git a/modules/configuring-hybrid-ovnkubernetes.adoc b/modules/configuring-hybrid-ovnkubernetes.adoc deleted file mode 100644 index 7ca513e8ce09..000000000000 --- a/modules/configuring-hybrid-ovnkubernetes.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_azure/installing-azure-network-customizations.adoc -// * networking/ovn_kubernetes_network_provider/configuring-hybrid-networking.adoc - -[id="configuring-hybrid-ovnkubernetes_{context}"] -= Configuring hybrid networking with OVN-Kubernetes - -You can configure your cluster to use hybrid networking with OVN-Kubernetes. This allows a hybrid cluster that supports different node networking configurations. For example, this is necessary to run both Linux and Windows nodes in a cluster. - -[IMPORTANT] -==== -You must configure hybrid networking with OVN-Kubernetes during the installation of your cluster. You cannot switch to hybrid networking after the installation process. -==== - -.Prerequisites - -* You defined `OVNKubernetes` for the `networking.networkType` parameter in the `install-config.yaml` file. See the installation documentation for configuring {product-title} network customizations on your chosen cloud provider for more information. - -.Procedure - -. Create the manifests from the directory that contains the installation program: -+ -[source,terminal] ----- -$ ./openshift-install create manifests --dir= <1> ----- -<1> For ``, specify the name of the directory that contains the `install-config.yaml` file for your cluster. - -. Create a file that is named `cluster-network-03-config.yml` in the `/manifests/` directory: -+ -[source,terminal] ----- -$ touch /manifests/cluster-network-03-config.yml <1> ----- -<1> For ``, specify the directory name that contains the `manifests/` directory for your cluster. -+ -After creating the file, several network configuration files are in the `manifests/` directory, as shown: -+ -[source,terminal] ----- -$ ls -1 /manifests/cluster-network-* ----- -+ -.Example output -[source,terminal] ----- -cluster-network-01-crd.yml -cluster-network-02-config.yml -cluster-network-03-config.yml ----- - -. Open the `cluster-network-03-config.yml` file and configure OVN-Kubernetes with hybrid networking. For example: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - creationTimestamp: null - name: cluster -spec: <1> - clusterNetwork: <2> - - cidr: 10.128.0.0/14 - hostPrefix: 23 - externalIP: - policy: {} - serviceNetwork: - - 172.30.0.0/16 - defaultNetwork: - type: OVNKubernetes <3> - ovnKubernetesConfig: - hybridOverlayConfig: - hybridClusterNetwork: <4> - - cidr: 10.132.0.0/14 - hostPrefix: 23 - hybridOverlayVXLANPort: 9898 <5> -status: {} ----- -<1> The parameters for the `spec` parameter are only an example. Specify your configuration for the Cluster Network Operator in the custom resource. -<2> Specify the CIDR configuration used when adding nodes. -<3> Specify `OVNKubernetes` as the Container Network Interface (CNI) cluster network provider. -<4> Specify the CIDR configuration used for nodes on the additional overlay network. The `hybridClusterNetwork` CIDR cannot overlap with the `clusterNetwork` CIDR. -<5> Specify a custom VXLAN port for the additional overlay network. This is required for running Windows nodes in a cluster installed on vSphere, and must not be configured for any other cloud provider. The custom port can be any open port excluding the default `4789` port. For more information on this requirement, see the Microsoft documentation on link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/kubernetes/common-problems#pod-to-pod-connectivity-between-hosts-is-broken-on-my-kubernetes-cluster-running-on-vsphere[Pod-to-pod connectivity between hosts is broken]. - -. Optional: Back up the `/manifests/cluster-network-03-config.yml` file. The installation program deletes the `manifests/` directory when creating the cluster. diff --git a/modules/configuring-network-baselining-timeframe.adoc b/modules/configuring-network-baselining-timeframe.adoc new file mode 100644 index 000000000000..52b7b994a7c0 --- /dev/null +++ b/modules/configuring-network-baselining-timeframe.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="configuring-network-baselining-timeframe_{context}"] += Configuring network baselining time frame + +You can use the `ROX_NETWORK_BASELINE_OBSERVATION_PERIOD` and the `ROX_BASELINE_GENERATION_DURATION` environment variables to configure the observation period and the network baseline generation duration. + +.Procedure + +. Set the `ROX_NETWORK_BASELINE_OBSERVATION_PERIOD` environment variable by running the following command: ++ +[source,terminal] +---- +$ oc -n stackrox set env deploy/central \// <1> + ROX_NETWORK_BASELINE_OBSERVATION_PERIOD= <2> +---- ++ +-- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +<2> Value must be time units, for example: `300ms`, `-1.5h`, or `2h45m`. Valid time units are `ns`, `us` or `µs`, `ms`, `s`, `m`, `h`. +-- + +. Set the `ROX_BASELINE_GENERATION_DURATION` environment variable by running the following command: ++ +[source,terminal] +---- +$ oc -n stackrox set env deploy/central \// <1> + ROX_BASELINE_GENERATION_DURATION= <2> +---- ++ +-- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +<2> Value must be time units, for example: `300ms`, `-1.5h`, or `2h45m`. Valid time units are `ns`, `us` or `µs`, `ms`, `s`, `m`, `h`. +-- \ No newline at end of file diff --git a/modules/configuring-output-format.adoc b/modules/configuring-output-format.adoc new file mode 100644 index 000000000000..20f204c18ff4 --- /dev/null +++ b/modules/configuring-output-format.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// * cli/checking-policy-compliance.adoc +:_mod-docs-content-type: CONCEPT +[id="configuring-output-format_{context}"] += Configuring output format + +When you check policy compliance by using the `roxctl deployment check` or `roxctl image check` commands, you can specify the output format by using the `-o` option to the command and specifying the format as `json`, `table`, `csv`, or `junit`. This option determines how the output of a command is displayed in the terminal. + +For example, the following command checks a deployment and then displays the result in `csv` format: +[source,terminal,subs="+quotes"] +---- +$ roxctl deployment check --file =__ -o csv +---- + +[NOTE] +==== +When you do not specify the `-o` option for the output format, the following default behavior is used: + +* The format for the `deployment check` and the `image check` commands is `table`. +* The default output format for the `image scan` command is `json`. This is the old JSON format output for compatibility with older versions of the CLI. To get the output in the new JSON format, specify the option with format, as `-o json`. Use the old JSON format output when gathering data for troubleshooting purposes. +==== + +Different options are available to configure the output. The following table lists the options and the format in which they are available. + +[%header,cols="1,2,1"] +|=== +|Option +|Description +|Formats + +|`--compact-output` +|Use this option to display the JSON output in a compact format. +|`json` + +|`--headers` +|Use this option to specify custom headers. +|`table` and `csv` + +|`--no-header` +|Use this option to omit the header row from the output. +|`table` and `csv` + +|`--row-jsonpath-expressions` +a|Use this option to specify link:https://github.com/tidwall/gjson[GJSON paths] to select specific items from the output. For example, to get the *Policy name* and *Severity* for a deployment check, use the following command: +[source,terminal,subs="+quotes"] +---- +$ roxctl deployment check --file=__ \ + -o table --headers POLICY-NAME,SEVERITY \ + --row-jsonpath-expressions="{results.#.violatedPolicies.#.name,results.#.violatedPolicies.#.severity}" +---- +|`table` and `csv` + +|`--merge-output` +|Use this options to merge table cells that have the same value. +|`table` + +|`headers-as-comment` +|Use this option to include the header row as a comment in the output. +|`csv` + +|`--junit-suite-name` +|Use this option to specify the name of the JUnit test suite. +|`junit` + +|=== \ No newline at end of file diff --git a/modules/configuring-scale-bounds-knative.adoc b/modules/configuring-scale-bounds-knative.adoc deleted file mode 100644 index d6a392c91679..000000000000 --- a/modules/configuring-scale-bounds-knative.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/configuring-knative-serving-autoscaling.adoc - -[id="configuring-scale-bounds-knative_{context}"] -= Configuring scale bounds Knative Serving autoscaling - -The `minScale` and `maxScale` annotations can be used to configure the minimum and maximum number of pods that can serve applications. -These annotations can be used to prevent cold starts or to help control computing costs. - -minScale:: If the `minScale` annotation is not set, pods will scale to zero (or to 1 if enable-scale-to-zero is false per the `ConfigMap`). - -maxScale:: If the `maxScale` annotation is not set, there will be no upper limit for the number of pods created. - -`minScale` and `maxScale` can be configured as follows in the revision template: - -[source,yaml] ----- -spec: - template: - metadata: - annotations: - autoscaling.knative.dev/minScale: "2" - autoscaling.knative.dev/maxScale: "10" ----- - -Using these annotations in the revision template will propagate this confguration to `PodAutoscaler` objects. - -[NOTE] -==== -These annotations apply for the full lifetime of a revision. Even when a revision is not referenced by any route, the minimal Pod count specified by `minScale` will still be provided. Keep in mind that non-routeable revisions may be garbage collected, which enables Knative to reclaim the resources. -==== diff --git a/modules/configuring-secret-for-wmco.adoc b/modules/configuring-secret-for-wmco.adoc deleted file mode 100644 index 864e573ecd4f..000000000000 --- a/modules/configuring-secret-for-wmco.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/enabling-windows-container-workloads.adoc - -[id="configuring-secret-for-wmco_{context}"] -= Configuring a secret for the Windows Machine Config Operator - -To run the Windows Machine Config Operator (WMCO), you must create a secret in the WMCO namespace containing a private key. This is required to allow the WMCO to communicate with the Windows virtual machine (VM). - -.Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You created a PEM-encoded file containing an RSA key. - -.Procedure - -* Define the secret required to access the Windows VMs: -+ -[source,terminal] ----- -$ oc create secret generic cloud-private-key --from-file=private-key.pem=${HOME}/.ssh/ \ - -n openshift-windows-machine-config-operator <1> ----- - -<1> You must create the private key in the WMCO namespace, like `openshift-windows-machine-config-operator`. - -It is recommended to use a different private key than the one used when installing the cluster. diff --git a/modules/configuring-the-rhacs-operator-for-infrastructure-nodes.adoc b/modules/configuring-the-rhacs-operator-for-infrastructure-nodes.adoc new file mode 100644 index 000000000000..594ae6c61b37 --- /dev/null +++ b/modules/configuring-the-rhacs-operator-for-infrastructure-nodes.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-ocp.adoc +// * cloud_service/installing_cloud_ocp/cloud-install-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="configuring-the-rhacs-operator-for-infrastructure-nodes_{context}"] += Configuring the {product-title-short} Operator for infrastructure nodes + +To deploy the {rh-rhacs-first} Operator on infrastructure nodes, you can modify its subscription YAML to include `nodeSelector` and `tolerations` to ensure that its pods are scheduled correctly. + +.Procedure + +. Configure the {product-title-short} Operator with the necessary `nodeSelector` and `tolerations` for infrastructure nodes before you apply the {olm-first} subscription by using the following content, for example: ++ +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + labels: + operators.coreos.com/rhacs-operator.rhacs-operator: "" + name: rhacs-operator + namespace: rhacs-operator +spec: + channel: stable + config: + nodeSelector: + node-role.kubernetes.io/infra: "" # <1> + tolerations: + - effect: NoSchedule + key: node-role.kubernetes.io/infra # <2> + operator: Exists + installPlanApproval: Automatic + name: rhacs-operator + source: redhat-operators + sourceNamespace: openshift-marketplace +---- ++ +-- +<1> The `nodeSelector` key and value instruct the Kubernetes scheduler to place the Operator pods on nodes that have the label `node-role.kubernetes.io/infra: ""`. +<2> The `tolerations` entry allows the Operator pods to be scheduled on nodes that have a taint with the `node-role.kubernetes.io/infra` key. This is necessary as infrastructure nodes are usually provided with a taint to prevent non-infrastructure workloads from being scheduled on them. +-- + +. Save the YAML file and apply it by using the OpenShift CLI (`oc`). + +When you apply the YAML file, you update the subscription for the {product-title-short} Operator. This in turn configures where the {product-title-short} Operator pods can be scheduled. The `rhacs-operator` namespace is the designated location for the {product-title-short} Operator. \ No newline at end of file diff --git a/modules/configuring_hyperthreading_for_a_cluster.adoc b/modules/configuring_hyperthreading_for_a_cluster.adoc deleted file mode 100644 index 9ae95a4ac1b4..000000000000 --- a/modules/configuring_hyperthreading_for_a_cluster.adoc +++ /dev/null @@ -1,119 +0,0 @@ -// Module included in the following assemblies: -// -// scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc - -[id="configuring_hyperthreading_for_a_cluster_{context}"] -= Configuring hyperthreading for a cluster - -To configure hyperthreading for an {product-title} cluster, set the CPU threads in the performance profile to the same cores that are configured for the reserved or isolated CPU pools. - -[NOTE] -==== -If you configure a performance profile, and subsequently change the hyperthreading configuration for the host, ensure that you update the CPU `isolated` and `reserved` fields in the `PerformanceProfile` YAML to match the new configuration. -==== - -[WARNING] -==== -Disabling a previously enabled host hyperthreading configuration can cause the CPU core IDs listed in the `PerformanceProfile` YAML to be incorrect. This incorrect configuration can cause the node to become unavailable because the listed CPUs can no longer be found. -==== - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. -* Install the OpenShift CLI (oc). - -.Procedure - -. Ascertain which threads are running on what CPUs for the host you want to configure. -+ -You can view which threads are running on the host CPUs by logging in to the cluster and running the following command: -+ -[source,terminal] ----- -$ lscpu --all --extended ----- -+ -.Example output -+ -[source,terminal] ----- -CPU NODE SOCKET CORE L1d:L1i:L2:L3 ONLINE MAXMHZ MINMHZ -0 0 0 0 0:0:0:0 yes 4800.0000 400.0000 -1 0 0 1 1:1:1:0 yes 4800.0000 400.0000 -2 0 0 2 2:2:2:0 yes 4800.0000 400.0000 -3 0 0 3 3:3:3:0 yes 4800.0000 400.0000 -4 0 0 0 0:0:0:0 yes 4800.0000 400.0000 -5 0 0 1 1:1:1:0 yes 4800.0000 400.0000 -6 0 0 2 2:2:2:0 yes 4800.0000 400.0000 -7 0 0 3 3:3:3:0 yes 4800.0000 400.0000 ----- -+ -In this example, there are eight logical CPU cores running on four physical CPU cores. CPU0 and CPU4 are running on physical Core0, CPU1 and CPU5 are running on physical Core 1, and so on. -+ -Alternatively, to view the threads that are set for a particular physical CPU core (`cpu0` in the example below), open a command prompt and run the following: -+ -[source,terminal] ----- -$ cat /sys/devices/system/cpu/cpu0/topology/thread_siblings_list ----- -+ -.Example output -+ -[source,terminal] ----- -0-4 ----- - -. Apply the isolated and reserved CPUs in the `PerformanceProfile` YAML. For example, you could set logical cores CPU0 and CPU4 as isolated, and logical cores CPU1 and CPU5 as reserved: -+ -[source,yaml] ----- -... - cpu: - isolated: 0-4 - reserved: 1-5 -... ----- - -[IMPORTANT] -==== -Hyperthreading is enabled by default on most Intel processors. If you enable hyperthreading, all threads processed by a particular core must be isolated or processed on the same core. -==== - -[id="disabling_hyperthreading_for_low_latency_applications_{context}"] -== Disabling hyperthreading for low latency applications - -When configuring clusters for low latency processing, consider whether you want to disable hyperthreading before you deploy the cluster. To disable hyperthreading, do the following: - -. Create a performance profile that is appropriate for your hardware and topology. -. Set `nosmt` as an additional kernel argument. The following example performance profile illustrates this setting: - -[source,yaml] ----- -apiVersion: performance.openshift.io/v2 -kind: PerformanceProfile -metadata: - name: example-performanceprofile -spec: - additionalKernelArgs: - - nmi_watchdog=0 - - audit=0 - - mce=off - - processor.max_cstate=1 - - idle=poll - - intel_idle.max_cstate=0 - - nosmt - cpu: - isolated: 2-3 - reserved: 0-1 - hugepages: - defaultHugepagesSize: 1G - pages: - - count: 2 - node: 0 - size: 1G - nodeSelector: - node-role.kubernetes.io/performance: '' - realTimeKernel: - enabled: true ----- diff --git a/modules/connectivity-map-output-formats-and-visualizations.adoc b/modules/connectivity-map-output-formats-and-visualizations.adoc new file mode 100644 index 000000000000..fb16bebb1f8f --- /dev/null +++ b/modules/connectivity-map-output-formats-and-visualizations.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: CONCEPT +[id="connectivity-map-output-formats-and-visualizations_{context}"] += Connectivity map output formats and visualizations + +You can use various output formats, including `txt`, `md`, `csv`, `json`, and `dot`. The `dot` format is ideal for visualizing the output as a connectivity graph. It can be viewed using graph visualization software such as link:https://graphviz.org/[Graphviz tool], and link:https://www.google.com/search?q=vscode+Graphviz+extension[extensions to VSCode]. You can convert the `dot` output to formats such as `svg`, `jpeg`, or `png` using Graphviz, whether it is installed locally or through an online viewer. \ No newline at end of file diff --git a/modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc b/modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc new file mode 100644 index 000000000000..9a5fb13f6cdf --- /dev/null +++ b/modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: CONCEPT +[id="connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command_{context}"] += Connectivity mapping using the roxctl netpol connectivity map command + +Connectivity mapping shows you allowed connections between workloads. It uses network policies defined in Kubernetes manifests, including Admin Network Policy (ANP) and Baseline Admin Network Policy (BANP). You can visualize and understand how your Kubernetes workloads communicate based on these combined network policies. + +To retrieve connectivity mapping information, the `roxctl netpol connectivity map` command requires a directory path. This directory must contain your Kubernetes network policy, ANP, and BANP manifests. The command's output details the connectivity within the analyzed Kubernetes resources. diff --git a/modules/consequences-of-disabling-telemetry.adoc b/modules/consequences-of-disabling-telemetry.adoc new file mode 100644 index 000000000000..838929703d1a --- /dev/null +++ b/modules/consequences-of-disabling-telemetry.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// * telemetry/opting-out-of-telemetry.adoc +:_mod-docs-content-type: CONCEPT +[id="consequences-of-disabling-telemetry_{context}"] += Consequences of disabling Telemetry + +In {rh-rhacs-first} version 4.0, you can opt out of Telemetry. +However, telemetry is embedded as a core component, so opting out is strongly discouraged. +Opting out of telemetry limits the ability of Red{nbsp}Hat to understand how everyone uses the product and which areas to prioritize for improvements. \ No newline at end of file diff --git a/modules/console-operator.adoc b/modules/console-operator.adoc deleted file mode 100644 index 7708f73281df..000000000000 --- a/modules/console-operator.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="console-operator_{context}"] -= Console Operator - -[discrete] -== Purpose - -The Console Operator installs and maintains the {product-title} web console on a cluster. - -[discrete] -== Project - -link:https://github.com/openshift/console-operator[console-operator] diff --git a/modules/consolidated-scanner.adoc b/modules/consolidated-scanner.adoc new file mode 100644 index 000000000000..ef4e83a70375 --- /dev/null +++ b/modules/consolidated-scanner.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: CONCEPT +[id="about-scanner-v4_{context}"] += About Scanner V4 + +[role="_abstract"] +{product-title-short} provides its own scanner, Scanner V4, or you can configure an integration to use {product-title-short} with another vulnerability scanner. + +Built on link:https://github.com/quay/claircore[Claircore], Scanner V4 provides scanning for language and operating system-specific image components and scanning {op-system-first}. + +[NOTE] +==== +Beginning with release 4.6, due to changes in vulnerability sources used, Scanner V4 only considers vulnerabilities affecting Red{nbsp}Hat products dated back to 2014. Previously, when reading Red Hat's OVAL data, the vulnerabilities dated back to before 2000. +==== \ No newline at end of file diff --git a/modules/containers-about.adoc b/modules/containers-about.adoc deleted file mode 100644 index 6a017d5bc5d9..000000000000 --- a/modules/containers-about.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.aodc - -[id="containers-about_{context}"] -= Containers - -The basic units of {product-title} applications are called _containers_. -link:https://access.redhat.com/articles/1353593[Linux container technologies] -are lightweight mechanisms for isolating running processes so that they are -limited to interacting with only their designated resources. The word -container is defined as a specific running or paused instance of a container -image. - -Many application instances can be running in containers on a single host without -visibility into each others' processes, files, network, and so on. Typically, -each container provides a single service, often called a micro-service, such -as a web server or a database, though containers can be used for arbitrary -workloads. - -The Linux kernel has been incorporating capabilities for container technologies -for years. The Docker project developed a convenient management interface for -Linux containers on a host. More recently, the -link:https://github.com/opencontainers/[Open Container Initiative] has developed -open standards for container formats and container runtimes. {product-title} and -Kubernetes add the ability to orchestrate OCI- and Docker-formatted containers -across multi-host installations. - -Though you do not directly interact with container runtimes when using -{product-title}, understanding their capabilities and terminology is -important for understanding their role in {product-title} and how your -applications function inside of containers. - -Tools such as -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/managing_containers/#using_podman_to_work_with_containers[podman] -can be used to replace `docker` command-line tools for running and managing -containers directly. Using `podman`, you can experiment with containers -separately from {product-title}. diff --git a/modules/contributing-quick-starts.adoc b/modules/contributing-quick-starts.adoc deleted file mode 100644 index 56a823c177e8..000000000000 --- a/modules/contributing-quick-starts.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="contributing-quick-starts_{context}"] -= Contributing quick starts - -{product-title} introduces the quick start custom resource, which is defined by a `ConsoleQuickStart` object. Operators and administrators can use this resource to contribute quick starts to the cluster. - -.Prerequisites - -* You must have cluster administrator privileges. - -.Procedure - -. To create a new quick start, run: -+ -[source,yaml] ----- -$ oc get -o yaml consolequickstart spring-with-s2i > my-quick-start.yaml ----- - -. Run: -+ -[source,yaml] ----- -$ oc create -f my-quick-start.yaml ----- - -. Update the YAML file using the guidance outlined in this documentation. - -. Save your edits. - -[id="viewing-quick-start-api-documentation_{context}"] -== Viewing the quick start API documentation - -.Procedure - -* To see the quick start API documentation, run: -+ -[source,terminal] ----- -$ oc explain consolequickstarts ----- - -Run `oc explain -h` for more information about `oc explain` usage. diff --git a/modules/copying-files-pods-and-containers.adoc b/modules/copying-files-pods-and-containers.adoc deleted file mode 100644 index d65e0bd885f7..000000000000 --- a/modules/copying-files-pods-and-containers.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/investigating-pod-issues.adoc - -[id="copying-files-pods-and-containers_{context}"] -= Copying files to and from pods and containers - -You can copy files to and from a pod to test configuration changes or gather diagnostic information. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Copy a file to a pod: -+ -[source,terminal] ----- -$ oc cp :/ -c <1> ----- -<1> The first container in a pod is selected if the `-c` option is not specified. - -. Copy a file from a pod: -+ -[source,terminal] ----- -$ oc cp :/ -c <1> ----- -<1> The first container in a pod is selected if the `-c` option is not specified. -+ -[NOTE] -==== -For `oc cp` to function, the `tar` binary must be available within the container. -==== diff --git a/modules/coverage-page-overview.adoc b/modules/coverage-page-overview.adoc new file mode 100644 index 000000000000..1b63796ef9c5 --- /dev/null +++ b/modules/coverage-page-overview.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: CONCEPT +[id="coverage-page-overview_{context}"] += OpenShift Coverage page overview + +When you view the *Coverage* page and apply a filter to a schedule, all results are filtered accordingly. This filter remains active for all coverage pages until you delete it. You can always view the results based on a single profile. + +You can select profiles grouped according to their associated benchmarks by using the toggle group. You calculate the compliance percentage based on the number of passed checks in relation to the total number of checks. + +[NOTE] +==== +The *Coverage* page now only shows the results of the last scan. If the last scan fails, the {rh-rhacs-first} deletes the previous results and you cannot see any information for this scan on the *Coverage* page. +==== + +The *Checks* view lists the profile checks and enables you to easily navigate and understand your compliance status. + +The profile check information is organized into the following groups: + +Check:: The name of the profile check. +Controls:: Shows the various controls associated with each check. +Fail status:: Shows the checks that have failed and require your attention. +Pass status:: Shows the checks that have been successfully passed. +Manual status:: Shows the checks that require a manual review because additional organizational or technical knowledge is required that you cannot automate. +Other status:: Shows the checks with a status other than pass or fail, such as warnings or informational statuses. +Compliance:: Shows the overall compliance status and helps you to ensure that your environment meets the required standards. + +The *Clusters* view lists the clusters and enables you to effectively monitor and manage your clusters. + +The cluster information is organized into the following groups: + +Cluster:: The name of the cluster. +Last scanned:: Indicates when the individual clusters were last scanned. +Fail status:: Shows the clusters whose scan has failed and which require your attention. +Pass status:: Shows the clusters that have successfully passed all checks. +Manual status:: Shows the checks that require a manual review because additional organizational or technical knowledge is required that you cannot automate. +Other status:: Shows the clusters that have a status other than pass or fail, such as warnings or informational alerts. +Compliance:: Shows the overall compliance status of your clusters and helps you to ensure that they meet the required standards. \ No newline at end of file diff --git a/modules/crd-creating-aggregated-cluster-roles.adoc b/modules/crd-creating-aggregated-cluster-roles.adoc deleted file mode 100644 index ac705e105b01..000000000000 --- a/modules/crd-creating-aggregated-cluster-roles.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/crds/extending-api-with-crds.adoc - -[id="crd-creating-aggregated-cluster-role_{context}"] -= Creating cluster roles for custom resource definitions - -Cluster administrators can grant permissions to existing cluster-scoped custom resource definitions (CRDs). If you use the `admin`, `edit`, and `view` default cluster roles, you can take advantage of cluster role aggregation for their rules. - -[IMPORTANT] -==== -You must explicitly assign permissions to each of these roles. The roles with more permissions do not inherit rules from roles with fewer permissions. If you assign a rule to a role, you must also assign that verb to roles that have more permissions. For example, if you grant the `get crontabs` permission to the view role, you must also grant it to the `edit` and `admin` roles. The `admin` or `edit` role is usually assigned to the user that created a project through the project template. -==== - -.Prerequisites - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -- Create a CRD. -endif::[] -ifdef::openshift-dedicated[] -- A cluster-scoped CRD has been created in your cluster. -endif::[] - -.Procedure - -. Create a cluster role definition file for the CRD. The cluster role definition is a YAML file that contains the rules that apply to each cluster role. A {product-title} controller adds the rules that you specify to the default cluster roles. -+ -.Example YAML file for a cluster role definition -[source,yaml] ----- -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1 <1> -metadata: - name: aggregate-cron-tabs-admin-edit <2> - labels: - rbac.authorization.k8s.io/aggregate-to-admin: "true" <3> - rbac.authorization.k8s.io/aggregate-to-edit: "true" <4> -rules: -- apiGroups: ["stable.example.com"] <5> - resources: ["crontabs"] <6> - verbs: ["get", "list", "watch", "create", "update", "patch", "delete", "deletecollection"] <7> ---- -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: aggregate-cron-tabs-view <2> - labels: - # Add these permissions to the "view" default role. - rbac.authorization.k8s.io/aggregate-to-view: "true" <8> - rbac.authorization.k8s.io/aggregate-to-cluster-reader: "true" <9> -rules: -- apiGroups: ["stable.example.com"] <5> - resources: ["crontabs"] <6> - verbs: ["get", "list", "watch"] <7> ----- -<1> Use the `rbac.authorization.k8s.io/v1` API. -<2> Specify a name for the definition. -<3> Specify this label to grant permissions to the admin default role. -<4> Specify this label to grant permissions to the edit default role. -<5> Specify the group name of the CRD. -<6> Specify the plural name of the CRD that these rules apply to. -<7> Specify the verbs that represent the permissions that are granted to the role. For example, apply read and write permissions to the `admin` and `edit` roles and only read permission to the `view` role. -<8> Specify this label to grant permissions to the `view` default role. -<9> Specify this label to grant permissions to the `cluster-reader` default role. - -. Create the cluster role: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- diff --git a/modules/crd-creating-crds.adoc b/modules/crd-creating-crds.adoc deleted file mode 100644 index eb80d3539abe..000000000000 --- a/modules/crd-creating-crds.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/crds/extending-api-with-crds.adoc - -[id="crd-creating-custom-resources-definition_{context}"] -= Creating a custom resource definition - -To create custom resource (CR) objects, cluster administrators must first create a custom resource definition (CRD). - -.Prerequisites - -- Access to an {product-title} cluster with `cluster-admin` user privileges. - -.Procedure - -To create a CRD: - -. Create a YAML file that contains the following field types: -+ -.Example YAML file for a CRD -[source,yaml] ----- -apiVersion: apiextensions.k8s.io/v1 <1> -kind: CustomResourceDefinition -metadata: - name: crontabs.stable.example.com <2> -spec: - group: stable.example.com <3> - version: v1 <4> - scope: Namespaced <5> - names: - plural: crontabs <6> - singular: crontab <7> - kind: CronTab <8> - shortNames: - - ct <9> ----- -<1> Use the `apiextensions.k8s.io/v1` API. -<2> Specify a name for the definition. This must be in the `.` format using the values from the `group` and `plural` fields. -<3> Specify a group name for the API. An API group is a collection of objects that are logically related. For example, all batch objects like `Job` or `ScheduledJob` could be in the batch API group (such as `batch.api.example.com`). A good practice is to use a fully-qualified-domain name (FQDN) of your organization. -<4> Specify a version name to be used in the URL. Each API group can exist in multiple versions, for example `v1alpha`, `v1beta`, `v1`. -<5> Specify whether the custom objects are available to a project (`Namespaced`) or all projects in the cluster (`Cluster`). -<6> Specify the plural name to use in the URL. The `plural` field is the same as a resource in an API URL. -<7> Specify a singular name to use as an alias on the CLI and for display. -<8> Specify the kind of objects that can be created. The type can be in CamelCase. -<9> Specify a shorter string to match your resource on the CLI. -+ -[NOTE] -==== -By default, a CRD is cluster-scoped and available to all projects. -==== - -. Create the CRD object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -A new RESTful API endpoint is created at: -+ -[source,terminal] ----- -/apis////*//... ----- -+ -For example, using the example file, the following endpoint is created: -+ -[source,terminal] ----- -/apis/stable.example.com/v1/namespaces/*/crontabs/... ----- -+ -You can now use this endpoint URL to create and manage CRs. The object kind is based on the `spec.kind` field of the CRD object you created. diff --git a/modules/crd-creating-custom-resources-from-file.adoc b/modules/crd-creating-custom-resources-from-file.adoc deleted file mode 100644 index 4728bc1079f2..000000000000 --- a/modules/crd-creating-custom-resources-from-file.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Useful paired with modules/crd-inspecting-custom-resources.adoc -// -// Module included in the following assemblies: -// -// * operators/understanding/crds/crd-managing-resources-from-crds.adoc -// * operators/understanding/crds/extending-api-with-crds.adoc - -[id="crd-creating-custom-resources-from-file_{context}"] -= Creating custom resources from a file - -After a custom resource definitions (CRD) has been added to the cluster, custom resources (CRs) can be created with the CLI from a file using the CR specification. - -.Prerequisites - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -- CRD added to the cluster by a cluster administrator. -endif::[] -ifdef::openshift-dedicated[] -- A CRD has been created in your cluster. -endif::[] - -.Procedure - -. Create a YAML file for the CR. In the following example definition, the `cronSpec` and `image` custom fields are set in a CR of `Kind: CronTab`. The `Kind` comes from the `spec.kind` field of the CRD object: -+ -.Example YAML file for a CR -[source,yaml] ----- -apiVersion: "stable.example.com/v1" <1> -kind: CronTab <2> -metadata: - name: my-new-cron-object <3> - finalizers: <4> - - finalizer.stable.example.com -spec: <5> - cronSpec: "* * * * /5" - image: my-awesome-cron-image ----- -+ -<1> Specify the group name and API version (name/version) from the CRD. -<2> Specify the type in the CRD. -<3> Specify a name for the object. -<4> Specify the link:https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#finalizers[finalizers] for the object, if any. Finalizers allow controllers to implement conditions that must be completed before the object can be deleted. -<5> Specify conditions specific to the type of object. - -. After you create the file, create the object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- diff --git a/modules/crd-custom-resource-definitions.adoc b/modules/crd-custom-resource-definitions.adoc deleted file mode 100644 index 7845a75d65fd..000000000000 --- a/modules/crd-custom-resource-definitions.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/crds/crd-managing-resources-from-crds.adoc -// * operators/understanding/crds/extending-api-with-crds.adoc - -[id="crd-custom-resource-definitions_{context}"] -= Custom resource definitions - -In the Kubernetes API, a _resource_ is an endpoint that stores a collection of API objects of a certain kind. For example, the built-in `Pods` resource contains a collection of `Pod` objects. - -A _custom resource definition_ (CRD) object defines a new, unique object type, called a _kind_, in the cluster and lets the Kubernetes API server handle its entire lifecycle. - -_Custom resource_ (CR) objects are created from CRDs that have been added to the cluster by a cluster administrator, allowing all cluster users to add the new resource type into projects. - -ifeval::["{context}" == "crd-extending-api-with-crds"] -When a cluster administrator adds a new CRD to the cluster, the Kubernetes API server reacts by creating a new RESTful resource path that can be accessed by the entire cluster or a single project (namespace) and begins serving the specified CR. - -Cluster administrators that want to grant access to the CRD to other users can use cluster role aggregation to grant access to users with the `admin`, `edit`, or `view` default cluster roles. Cluster role aggregation allows the insertion of custom policy rules into these cluster roles. This behavior integrates the new resource into the RBAC policy of the cluster as if it was a built-in resource. -endif::[] - -Operators in particular make use of CRDs by packaging them with any required RBAC policy and other software-specific logic. -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -Cluster administrators can also add CRDs manually to the cluster outside of the lifecycle of an Operator, making them available to all users. - -[NOTE] -==== -While only cluster administrators can create CRDs, developers can create the CR from an existing CRD if they have read and write permission to it. -==== -endif::[] -ifdef::openshift-dedicated[] -{product-title} cluster administrators can manage RBAC to CRDs that have been added to customer project namespaces, making them available to authorized users. -endif::[] diff --git a/modules/crd-inspecting-custom-resources.adoc b/modules/crd-inspecting-custom-resources.adoc deleted file mode 100644 index 25a886476d42..000000000000 --- a/modules/crd-inspecting-custom-resources.adoc +++ /dev/null @@ -1,92 +0,0 @@ -// Useful paired with modules/crd-creating-custom-resources-from-file.adoc -// -// Module included in the following assemblies: -// -// * operators/understanding/crds/crd-managing-resources-from-crds.adoc -// * operators/understanding/crds/extending-api-with-crds.adoc - -[id="crd-inspecting-custom-resources_{context}"] -= Inspecting custom resources - -You can inspect custom resource (CR) objects that exist in your cluster using the CLI. - -.Prerequisites - -* A CR object exists in a namespace to which you have access. - -.Procedure - -. To get information on a specific kind of a CR, run: -+ -[source,terminal] ----- -$ oc get ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get crontab ----- -+ -.Example output -[source,terminal] ----- -NAME KIND -my-new-cron-object CronTab.v1.stable.example.com ----- -+ -Resource names are not case-sensitive, and you can use either the singular or plural forms defined in the CRD, as well as any short name. For example: -+ -[source,terminal] ----- -$ oc get crontabs ----- -+ -[source,terminal] ----- -$ oc get crontab ----- -+ -[source,terminal] ----- -$ oc get ct ----- - -. You can also view the raw YAML data for a CR: -+ -[source,terminal] ----- -$ oc get -o yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get ct -o yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: v1 -items: -- apiVersion: stable.example.com/v1 - kind: CronTab - metadata: - clusterName: "" - creationTimestamp: 2017-05-31T12:56:35Z - deletionGracePeriodSeconds: null - deletionTimestamp: null - name: my-new-cron-object - namespace: default - resourceVersion: "285" - selfLink: /apis/stable.example.com/v1/namespaces/default/crontabs/my-new-cron-object - uid: 9423255b-4600-11e7-af6a-28d2447dc82b - spec: - cronSpec: '* * * * /5' <1> - image: my-awesome-cron-image <1> ----- -<1> Custom data from the YAML that you used to create the object displays. diff --git a/modules/create-a-containerruntimeconfig-crd.adoc b/modules/create-a-containerruntimeconfig-crd.adoc deleted file mode 100644 index f5b53a8e9e2a..000000000000 --- a/modules/create-a-containerruntimeconfig-crd.adoc +++ /dev/null @@ -1,215 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="create-a-containerruntimeconfig_{context}"] -= Creating a `ContainerRuntimeConfig` CR to edit CRI-O parameters - -You can change some of the settings associated with the {product-title} CRI-O runtime for the nodes associated with a specific machine config pool (MCP). Using a `ContainerRuntimeConfig` custom resource (CR), you set the configuration values and add a label to match the MCP. The MCO then rebuilds the `crio.conf` and `storage.conf` configuration files on the associated nodes with the updated values. - -[NOTE] -==== -To revert the changes implemented by using a `ContainerRuntimeConfig` CR, you must delete the CR. Removing the label from the machine config pool does not revert the changes. -==== - -You can modify the following settings by using a `ContainerRuntimeConfig` CR: - -* **PIDs limit**: The `pidsLimit` parameter sets the CRI-O `pids_limit` parameter, which is maximum number of processes allowed in a container. The default is 1024 (`pids_limit = 1024`). -* **Log level**: The `logLevel` parameter sets the CRI-O `log_level` parameter, which is the level of verbosity for log messages. The default is `info` (`log_level = info`). Other options include `fatal`, `panic`, `error`, `warn`, `debug`, and `trace`. -* **Overlay size**: The `overlaySize` parameter sets the CRI-O Overlay storage driver `size` parameter, which is the maximum size of a container image. The default is 10 GB (size = "10G"). -* **Maximum log size**: The `logSizeMax` parameter sets the CRI-O `log_size_max` parameter, which is the maximum size allowed for the container log file. The default is unlimited (`log_size_max = -1`). If set to a positive number, it must be at least 8192 to not be smaller than the ConMon read buffer. ConMon is a program that -monitors communications between a container manager (such as Podman or CRI-O) and the OCI runtime (such as runc or crun) for a single container. - -You can create multiple `ContainerRuntimeConfig` CRs, as needed, with a limit of ten. For the first `ContainerRuntimeConfig` CR, the MCO creates a machine config appended with `containerruntime`. With each subsequent CR, the controller creates a new `containerruntime` machine config with a numeric suffix. For example, if you have a `containerruntime` machine config with a `-2` suffix, the next `containerruntime` machine config is appended with `-3`. - -You can also edit an existing `ContainerRuntimeConfig` CRs to edit existing settings or add new settings instead of creating a new CR. It is recommended to create a new CR to modify a different machine config pool, rather than add additional labels to an existing CR. - -If you want to delete the machine configs, you should delete them in reverse order to avoid exceeding the limit. For example, you should delete the `containerruntime-3` machine config before deleting the `containerruntime-2` machine config. - -[NOTE] -==== -If you have a machine config with a `containerruntime-9` suffix, the next machine config is appended with `containerruntime-10` and will fail as it exceeds the limit, even if there are fewer than 10 `containerruntime` machine configs. -==== - -.Example showing multiple `ContainerRuntimeConfig` CRs -[source,terminal] ----- -$ oc get ctrcfg ----- - -.Example output -[source, terminal] ----- -NAME AGE -ctr-pid 24m -ctr-overlay 15m -ctr-level 5m45s ----- - -.Example showing multiple `containerruntime` machine configs -[source,terminal] ----- -$ oc get mc | grep container ----- - -.Example output -[source, terminal] ----- -... -01-master-container-runtime b5c5119de007945b6fe6fb215db3b8e2ceb12511 3.2.0 57m -... -01-worker-container-runtime b5c5119de007945b6fe6fb215db3b8e2ceb12511 3.2.0 57m -... -99-worker-generated-containerruntime b5c5119de007945b6fe6fb215db3b8e2ceb12511 3.2.0 26m -99-worker-generated-containerruntime-1 b5c5119de007945b6fe6fb215db3b8e2ceb12511 3.2.0 17m -99-worker-generated-containerruntime-2 b5c5119de007945b6fe6fb215db3b8e2ceb12511 3.2.0 7m26s -... ----- - -The following example raises the `pids_limit` to 2048, sets the `log_level` to `debug`, sets the overlay size to 8 GB, and sets the `log_size_max` to unlimited: - -.Example `ContainerRuntimeConfig` CR -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: ContainerRuntimeConfig -metadata: - name: overlay-size -spec: - machineConfigPoolSelector: - matchLabels: - pools.operator.machineconfiguration.openshift.io/worker: '' <1> - containerRuntimeConfig: - pidsLimit: 2048 <2> - logLevel: debug <3> - overlaySize: 8G <4> - logSizeMax: "-1" <5> ----- -<1> Specifies the machine config pool label. -<2> Optional: Specifies the level of verbosity for log messages. -<3> Optional: Specifies the maximum size allowed for the container log file. If set to a positive number, it must be at least `8192`. -<4> Optional: Specifies the maximum size of a container image. -<5> Optional: Specifies the maximum number of processes allowed in a container. - -.Procedure - -To change CRI-O settings using the `ContainerRuntimeConfig` CR: - -. Create a YAML file for the `ContainerRuntimeConfig` CR: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: ContainerRuntimeConfig -metadata: - name: overlay-size -spec: - machineConfigPoolSelector: - matchLabels: - pools.operator.machineconfiguration.openshift.io/worker: '' <1> - containerRuntimeConfig: <2> - pidsLimit: 2048 - logLevel: debug - overlaySize: 8G - logSizeMax: "-1" ----- -<1> Specify a label for the machine config pool that you want you want to modify. -<2> Set the parameters as needed. - -. Create the `ContainerRuntimeConfig` CR: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- - -. Verify that the CR is created: -+ -[source,terminal] ----- -$ oc get ContainerRuntimeConfig ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -overlay-size 3m19s ----- - -. Check that a new `containerruntime` machine config is created: -+ -[source,terminal] ----- -$ oc get machineconfigs | grep containerrun ----- -+ -.Example output -[source,terminal] ----- -99-worker-generated-containerruntime 2c9371fbb673b97a6fe8b1c52691999ed3a1bfc2 3.1.0 31s ----- - -. Monitor the machine config pool until all are shown as ready: -+ -[source,terminal] ----- -$ oc get mcp worker ----- -+ -.Example output -+ -[source,terminal] ----- -NAME CONFIG UPDATED UPDATING DEGRADED MACHINECOUNT READYMACHINECOUNT UPDATEDMACHINECOUNT DEGRADEDMACHINECOUNT AGE -worker rendered-worker-169 False True False 3 1 1 0 9h ----- - -. Verify that the settings were applied in CRI-O: - -.. Open an `oc debug` session to a node in the machine config pool and run `chroot /host`. -+ -[source, terminal] ----- -$ oc debug node/ ----- -+ -[source, terminal] ----- -sh-4.4# chroot /host ----- - -.. Verify the changes in the `crio.conf` file: -+ -[source,terminal] ----- -sh-4.4# crio config | egrep 'log_level|pids_limit|log_size_max' ----- -+ -.Example output -+ -[source,terminal] ----- -pids_limit = 2048 -log_size_max = -1 -log_level = "debug" ----- - -.. Verify the changes in the `storage.conf`file: -+ -[source,terminal] ----- -sh-4.4# head -n 7 /etc/containers/storage.conf ----- -+ -.Example output -+ ----- -[storage] - driver = "overlay" - runroot = "/var/run/containers/storage" - graphroot = "/var/lib/containers/storage" - [storage.options] - additionalimagestores = [] - size = "8G" ----- diff --git a/modules/create-a-custom-access-scope.adoc b/modules/create-a-custom-access-scope.adoc new file mode 100644 index 000000000000..ff700e05d1b4 --- /dev/null +++ b/modules/create-a-custom-access-scope.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-a-custom-access-scope_{context}"] += Creating a custom access scope + +[role="_abstract"] +You can create new access scopes from the *Access Control* view. + +.Prerequisites +* You must have the *Admin* role, or a role with the permission set with read and write permissions for the `Access` resource to create, modify, and delete permission sets. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Select *Access scopes*. +. Click *Create access scope*. +. Enter a *Name* and *Description* for the new access scope. +. Under the *Allowed resources* section: +** Use the *Cluster filter* and *Namespace filter* fields to filter the list of clusters and namespaces visible in the list. +** Expand the *Cluster name* to see the list of namespaces in that cluster. +** To allow access to all namespaces in a cluster, toggle the switch in the *Manual selection* column. ++ +[NOTE] +==== +Access to a specific cluster provides users with access to the following resources within the scope of the cluster: + +* {ocp} or Kubernetes cluster metadata and security information +* Compliance information for authorized clusters +* Node metadata and security information +* Access to all namespaces in that cluster and their associated security information +==== +** To allow access to a namespace, toggle the switch in the *Manual selection* column for a namespace. ++ +[NOTE] +==== +Access to a specific namespace gives access to the following information within the scope of the namespace: + +* Alerts and violations for deployments +* Vulnerability data for images +* Deployment metadata and security information +* Role and user information +* Network graph, policy, and baseline information for deployments +* Process information and process baseline configuration +* Prioritized risk information for each deployment +==== +. If you want to allow access to clusters and namespaces based on labels, click *Add label selector* under the *Label selection rules* section. Then click *Add rule* to specify *Key* and *Value* pairs for the label selector. You can specify labels for clusters and namespaces. +. Click *Save*. + +[id="scale-considerations_{context}"] +== Scale considerations + +In large environments, for example, with thousands of namespaces, the application of user scopes that cover large numbers of namespaces can cause some pages to render slowly or time out. For example, you might experience timeouts when opening the main *Dashboard* page. + +Performance was tested in a single-cluster context on an environment with 20,000 deployments across 5,000 namespaces and 80,000 alerts in one test cluster. In that testing, the load time of the main *Dashboard* page for scopes including up to 2,000 namespaces on that cluster was under a few seconds. + +Performance was tested in a multi-cluster context on an environment with 200,000 deployments across 50,000 namespaces and 800,000 alerts across 10 test clusters. In that testing, the load time of the main *Dashboard* page was under a few seconds for scopes including up to 500 namespaces across the 10 clusters, as well as for scopes including up to 2,000 namespaces on a single cluster. + +The load time of {product-title-short} portal pages for user scopes with more namespaces than the numbers tested cannot be guaranteed to stay under the timeout limit. diff --git a/modules/create-a-custom-permission-set.adoc b/modules/create-a-custom-permission-set.adoc new file mode 100644 index 000000000000..f644b8bbb3cc --- /dev/null +++ b/modules/create-a-custom-permission-set.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-a-custom-permission-set_{context}"] += Creating a custom permission set + +[role="_abstract"] +You can create new permission sets from the *Access Control* view. + +.Prerequisites +* You must have the *Admin* role, or read and write permissions for the `Access` resource to create, modify, and delete permission sets. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. Select *Permission sets*. +. Click *Create permission set*. +. Enter a *Name* and *Description* for the new permission set. +. For each resource, under the *Access level* column, select one of the permissions from `No access`, `Read access`, or `Read and Write access`. ++ +[WARNING] +==== +* If you are configuring a permission set for users, you must grant read-only permissions for the following resources: +** `Alert` +** `Cluster` +** `Deployment` +** `Image` +** `NetworkPolicy` +** `NetworkGraph` +** `WorkflowAdministration` +** `Secret` +* These permissions are preselected when you create a new permission set. +* If you do not grant these permissions, users will experience issues with viewing pages in the {product-title-short} portal. +==== +. Click *Save*. diff --git a/modules/create-a-custom-role-3630.adoc b/modules/create-a-custom-role-3630.adoc new file mode 100644 index 000000000000..f30d41420336 --- /dev/null +++ b/modules/create-a-custom-role-3630.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-a-custom-role-3630_{context}"] += Creating a custom role + +[role="_abstract"] +You can create new roles from the *Access Control* view. + +.Prerequisites +* You must have the *Admin* role, or read and write permissions for the `Access` resource to create, modify, and delete custom roles. +* You must create a permissions set and an access scope for the custom role before creating the role. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access Control*. +. Select *Roles*. +. Click *Create role*. +. Enter a *Name* and *Description* for the new role. +. Select a *Permission set* for the role. +. Select an *Access scope* for the role. +. Click *Save*. diff --git a/modules/create-a-kubeletconfig-crd-to-edit-kubelet-parameters.adoc b/modules/create-a-kubeletconfig-crd-to-edit-kubelet-parameters.adoc deleted file mode 100644 index fc2fbd930c6d..000000000000 --- a/modules/create-a-kubeletconfig-crd-to-edit-kubelet-parameters.adoc +++ /dev/null @@ -1,118 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/recommended-host-practices.adoc -// * post_installation_configuration/node-tasks.adoc -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="create-a-kubeletconfig-crd-to-edit-kubelet-parameters_{context}"] -= Creating a `KubeletConfig` CRD to edit kubelet parameters - -The kubelet configuration is currently serialized as an Ignition configuration, so it can be directly edited. However, there is also a new -`kubelet-config-controller` added to the Machine Config Controller (MCC). This allows you to create a `KubeletConfig` custom resource (CR) to edit the kubelet parameters. - -.Procedure - -. Run: -+ -[source,terminal] ----- -$ oc get machineconfig ----- -+ -This provides a list of the available machine configuration objects you can select. By default, the two kubelet-related configs are `01-master-kubelet` and `01-worker-kubelet`. - -. To check the current value of max pods per node, run: -+ -[source,terminal] ----- -# oc describe node | grep Allocatable -A6 ----- -+ -Look for `value: pods: `. -+ -For example: -+ -[source,terminal] ----- -# oc describe node ip-172-31-128-158.us-east-2.compute.internal | grep Allocatable -A6 ----- -+ -.Example output -[source,terminal] ----- -Allocatable: - attachable-volumes-aws-ebs: 25 - cpu: 3500m - hugepages-1Gi: 0 - hugepages-2Mi: 0 - memory: 15341844Ki - pods: 250 ----- - -. To set the max pods per node on the worker nodes, create a custom resource file that contains the kubelet configuration. For example, `change-maxPods-cr.yaml`: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: set-max-pods -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: large-pods - kubeletConfig: - maxPods: 500 ----- -+ -The rate at which the kubelet talks to the API server depends on queries per second (QPS) and burst values. The default values, `50` for `kubeAPIQPS` and `100` for `kubeAPIBurst`, are good enough if there are limited pods running on each node. Updating the kubelet QPS and burst rates is recommended if there are enough CPU and memory resources on the node: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: set-max-pods -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: large-pods - kubeletConfig: - maxPods: - kubeAPIBurst: - kubeAPIQPS: ----- - -.. Run: -+ -[source,terminal] ----- -$ oc create -f change-maxPods-cr.yaml ----- - -.. Run: -+ -[source,terminal] ----- -$ oc get kubeletconfig ----- -+ -This should return `set-max-pods`. -+ -Depending on the number of worker nodes in the cluster, wait for the worker nodes to be rebooted one by one. For a cluster with 3 worker nodes, this could take about 10 to 15 minutes. - -. Check for `maxPods` changing for the worker nodes: -+ -[source,terminal] ----- -$ oc describe node ----- - -.. Verify the change by running: -+ -[source,terminal] ----- -$ oc get kubeletconfigs set-max-pods -o yaml ----- -+ -This should show a status of `True` and `type:Success` diff --git a/modules/create-additional-routes-ocp-oauth.adoc b/modules/create-additional-routes-ocp-oauth.adoc new file mode 100644 index 000000000000..c7f1b576f48a --- /dev/null +++ b/modules/create-additional-routes-ocp-oauth.adoc @@ -0,0 +1,87 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-ocp-oauth.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-additional-routes-ocp-oauth_{context}"] += Creating additional routes for {ocp} OAuth server + +When you configure {ocp} OAuth server as an identity provider by using {product-title} portal, {product-title-short} configures only a single route for the OAuth server. +However, you can create additional routes by specifying them as annotations in the Central custom resource. + +.Prerequisites + +* You must have configured link:https://docs.openshift.com/container-platform/4.12/authentication/using-service-accounts-as-oauth-client.html#service-accounts-as-oauth-clients_using-service-accounts-as-oauth-client[Service accounts as OAuth clients] for your {ocp} OAuth server. + +.Procedure + +* If you installed {product-title-short} using the {product-title-short} Operator: +. Create a `CENTRAL_ADDITIONAL_ROUTES` environment variable that contains a patch for the Central custom resource: ++ +[source,terminal] +---- +$ CENTRAL_ADDITIONAL_ROUTES=' +spec: + central: + exposure: + loadBalancer: + enabled: false + port: 443 + nodePort: + enabled: false + route: + enabled: true + persistence: + persistentVolumeClaim: + claimName: stackrox-db + customize: + annotations: + serviceaccounts.openshift.io/oauth-redirecturi.main: sso/providers/openshift/callback <1> + serviceaccounts.openshift.io/oauth-redirectreference.main: "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"central\"}}" <2> + serviceaccounts.openshift.io/oauth-redirecturi.second: sso/providers/openshift/callback <3> + serviceaccounts.openshift.io/oauth-redirectreference.second: "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"second-central\"}}" <4> +' +---- +<1> The redirect URI for setting the main route. +<2> The redirect URI reference for the main route. +<3> The redirect for setting the second route. +<4> The redirect reference for the second route. + +. Apply the `CENTRAL_ADDITIONAL_ROUTES` patch to the Central custom resource: ++ +[source,terminal] +---- +$ oc patch centrals.platform.stackrox.io \ + -n \ <1> + \ <2> + --patch "$CENTRAL_ADDITIONAL_ROUTES" \ + --type=merge +---- +<1> Replace `` with the name of the project that contains the Central custom resource. +<2> Replace `` with the name of the Central custom resource. + +* Or, if you installed {product-title-short} using Helm: +. Add the following annotations to your `values-public.yaml` file: ++ +[source,yaml] +---- +customize: + central: + annotations: + serviceaccounts.openshift.io/oauth-redirecturi.main: sso/providers/openshift/callback <1> + serviceaccounts.openshift.io/oauth-redirectreference.main: "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"central\"}}" <2> + serviceaccounts.openshift.io/oauth-redirecturi.second: sso/providers/openshift/callback <3> + serviceaccounts.openshift.io/oauth-redirectreference.second: "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"second-central\"}}" <4> +---- +<1> The redirect for setting the main route. +<2> The redirect reference for the main route. +<3> The redirect for setting the second route. +<4> The redirect reference for the second route. +. Apply the custom annotations to the Central custom resource by using `helm upgrade`: ++ +[source,terminal] +---- +$ helm upgrade -n stackrox \ + stackrox-central-services rhacs/central-services \ + -f <1> +---- +<1> Specify the path of the `values-public.yaml` configuration file using the `-f` option. diff --git a/modules/create-an-okta-app.adoc b/modules/create-an-okta-app.adoc new file mode 100644 index 000000000000..2627ea4109cb --- /dev/null +++ b/modules/create-an-okta-app.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-okta-identity-cloud.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-an-okta-app_{context}"] += Creating an Okta app + +Before you can use Okta as a SAML 2.0 identity provider for {product-title}, you must create an Okta app. + +[WARNING] +==== +Okta's *Developer Console* does not support the creation of custom SAML 2.0 applications. +If you are using the *Developer Console*, you must first switch to the *Admin Console* (*Classic UI*). +To switch, click *Developer Console* in the top left of the page and select *Classic UI*. +==== + +.Prerequisites +* You must have an account with administrative privileges for the Okta portal. + +.Procedure +. On the Okta portal, select *Applications* from the menu bar. +. Click *Add Application* and then select *Create New App*. +. In the *Create a New Application Integration* dialog box, leave *Web* as the platform and select *SAML 2.0* as the protocol that you want to sign in users. +. Click *Create*. +. On the *General Settings* page, enter a name for the app in the *App name* field. +. Click *Next*. +. On the *SAML Settings* page, set values for the following fields: +.. *Single sign on URL* +*** Specify it as `\https://<{product-title-short}_portal_hostname>/sso/providers/saml/acs`. +*** Leave the *Use this for Recipient URL and Destination URL* option checked. +*** If your {product-title-short} portal is accessible at different URLs, you can add them here by checking the *Allow this app to request other SSO URLs* option and add the alternative URLs using the specified format. +.. *Audience URI (SP Entity ID)* +*** Set the value to *{product-title-short}* or another value of your choice. +*** Remember the value you choose; you will need this value when you configure {product-title}. +.. *Attribute Statements* +*** You must add at least one attribute statement. +*** Red{nbsp}Hat recommends using the email attribute: +**** *Name:* email +**** *Format:* Unspecified +**** *Value:* user.email +. Verify that you have configured at least one *Attribute Statement* before continuing. +. Click *Next*. +. On the *Feedback* page, select an option that applies to you. +. Select an appropriate *App type*. +. Click *Finish*. + +After the configuration is complete, you are redirected to the *Sign On* settings page for the new app. +A yellow box contains links to the information that you need to configure {product-title}. + +After you have created the app, assign Okta users to this application. +Go to the *Assignments* tab, and assign the set of individual users or groups that can access {product-title}. +For example, assign the group *Everyone* to allow all users in the organization to access {product-title}. diff --git a/modules/create-api-token.adoc b/modules/create-api-token.adoc new file mode 100644 index 000000000000..4b94f658cb58 --- /dev/null +++ b/modules/create-api-token.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * configure/configure-api-token.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-api-token_{context}"] += Creating an API token + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll to the *Authentication Tokens* category, and then click *API Token*. +. Click *Generate Token*. +. Enter a name for the token and select a role that provides the required level of access (for example, *Continuous Integration* or *Sensor Creator*). +. Click *Generate*. ++ +[IMPORTANT] +==== +Copy the generated token and securely store it. +You will not be able to view it again. +==== \ No newline at end of file diff --git a/modules/create-collection-rules.adoc b/modules/create-collection-rules.adoc new file mode 100644 index 000000000000..e3a96f88e75c --- /dev/null +++ b/modules/create-collection-rules.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * operating/create-use-collections.adoc +:_mod-docs-content-type: PROCEDURE +[id="creating-collection-rules_{context}"] += Creating collection rules + +When creating collections, you must configure at least one rule or attach another collection to the new collection that you are creating. + +[NOTE] +==== +Currently, collections are available only for deployments. +==== + +Configure rules to select the resources to include in the collection. Use the preview panel to see the results of the collection rules as you configure them. You can configure rules in any order. + +.Procedure + +. In the *Deployments* section, select one of the following options from the drop-down list: +* *No deployments specified*: Select this option if you do not want to use the deployment criteria in your search. +* *Deployments with names matching*: Select this option to choose by name and then select one of the following options: +** *An exact value of*: Enter the exact name of the deployment. +** *A regex value of*: You can use regular expressions to search for a deployment. This option is useful if you do not know the exact name of the deployment. A regular expression is a string of letters, numbers, and symbols that defines a pattern. {product-title-short} uses this pattern to match characters or groups of characters and return results. For regular expressions, link:https://github.com/google/re2/wiki/Syntax[RE2 syntax] is supported. Perl syntax is not supported. To select _all deployments_, select this option and enter `.*`. See "Using regular expressions" for more information and examples. +* *Deployments with labels matching exactly*: Select this option to select deployments with labels that match the exact text that you enter. The label must be a valid Kubernetes label in the format of `key=value`. +. Optional: To add more deployments with names or labels that match additional criteria for inclusion, click *OR* and configure another exact or regular expression value. + diff --git a/modules/create-issues-in-different-jira-projects.adoc b/modules/create-issues-in-different-jira-projects.adoc new file mode 100644 index 000000000000..ba4db27d26fd --- /dev/null +++ b/modules/create-issues-in-different-jira-projects.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-jira.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-issues-in-different-jira-projects_{context}"] += Creating issues in different Jira projects + +[role="_abstract"] +You can configure {product-title} to create issues in different Jira projects so that they directly go to the correct team. After completing the configuration, if a deployment has an annotation in the YAML file, {product-title-short} creates issues in the project specified for that annotation. Otherwise, {product-title-short} creates issues in the default project. + +.Prerequisites +* You must have an account with access to each project that you want to send the alerts to. + +.Procedure +. Add an annotation similar to the following example in your namespace or deployment YAML file: ++ +[source,yaml,subs="+quotes"] +---- +annotations: +# ... + jira/project-key: +# ... +---- +. Use the annotation key `jira/project-key` in the *Annotation key for project* field when you configure {product-title}. diff --git a/modules/create-new-system-policy.adoc b/modules/create-new-system-policy.adoc new file mode 100644 index 000000000000..b3938a62cd53 --- /dev/null +++ b/modules/create-new-system-policy.adoc @@ -0,0 +1,70 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-new-system-policy_{context}"] += Creating a new system policy + +In addition to using the default policies, you can also create custom policies in {product-title}. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. Click *+ New Policy*. +. Enter the *Name* for the policy. +. Select a *Severity* level for the policy: Critical, High, Medium, or Low. +. Choose the *Lifecycle Stages* for which the policy is applicable, from *Build*, *Deploy*, or *Runtime*. You can select more than one stage. ++ +[NOTE] +==== +If you create a new policy for integrating with a CI system, select *Build* as the lifecycle stage. +==== +** Build-time policies apply to image fields such as CVEs and Dockerfile instructions. +** Deploy-time policies can include all build-time policy criteria. They can also have data from your cluster configurations, such as running in privileged mode or mounting the Docker daemon socket. +** Runtime policies can include all build-time and deploy-time policy criteria, and data about process executions during runtime. +. Enter information about the policy in the *Description*, *Rationale*, and *Remediation* fields. +When CI validates the build, the data from these fields is displayed. +Therefore, include all information explaining the policy. +. Select a category from the *Categories* drop-down menu. +. Select a notifier from the *Notifications* drop-down menu that receives alert notifications when a violation occurs for this policy. ++ +[NOTE] +==== +You must integrate {product-title-short} with your notification providers, such as webhooks, Jira, or PagerDuty, to receive alert notifications. Notifiers only show up if you have integrated any notification providers with {product-title-short}. +==== +. Use *Restrict to Scope* to enable this policy only for a specific cluster, namespace, or label. +You can add multiple scopes and also use regular expressions in RE2 Syntax for namespaces and labels. +. Use *Exclude by Scope* to exclude deployments, clusters, namespaces, and labels. +This field indicates that the policy will not apply to the entities that you specify. +You can add multiple scopes and also use regular expressions in RE2 Syntax for namespaces and labels. +However, you cannot use regular expressions for selecting deployments. +. For *Excluded Images (Build Lifecycle only)*, select all the images from the list for which you do not want to trigger a violation for the policy. ++ +[NOTE] +==== +The *Excluded Images (Build Lifecycle only)* setting only applies when you check images in a continuous integration system (the Build lifecycle stage). +It does not have any effect if you use this policy to check running deployments (the Deploy lifecycle stage) or runtime activities (the Runtime lifecycle stage). +==== +. In the *Policy Criteria* section, configure the attributes that will trigger the policy. +//TODO: Add link to policy criteria +. Select *Next* on the panel header. +. The new policy panel shows a preview of the violations that are triggered if you enable the policy. +. Select *Next* on the panel header. +. Choose the enforcement behavior for the policy. +Enforcement settings are only available for the stages that you selected for the *Lifecycle Stages* option. +Select *ON* to enforce policy and report a violation. Select *OFF* to only report a violation. ++ +[NOTE] +==== +The enforcement behavior is different for each lifecycle stage. + +* For the *Build* stage, {product-title-short} fails your CI builds when images match the conditions of the policy. +* For the *Deploy* stage, {product-title-short} blocks the creation and update of deployments that match the conditions of the policy if the {product-title-short} admission controller is configured and running. +** In clusters with admission controller enforcement, the Kubernetes or {ocp} API server blocks all noncompliant deployments. In other clusters, {product-title-short} edits noncompliant deployments to prevent pods from being scheduled. +** For existing deployments, policy changes only result in enforcement at the next detection of the criteria, when a Kubernetes event occurs. For more information about enforcement, see "Security policy enforcement for the deploy stage". +* For the *Runtime* stage, {product-title-short} stops all pods that match the conditions of the policy. +==== ++ +[WARNING] +==== +Policy enforcement can impact running applications or development processes. Before you enable enforcement options, inform all stakeholders and plan how to respond to the automated enforcement actions. +==== diff --git a/modules/create-object-collections.adoc b/modules/create-object-collections.adoc new file mode 100644 index 000000000000..a6659639c499 --- /dev/null +++ b/modules/create-object-collections.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/create-use-collections.adoc +:_mod-docs-content-type: PROCEDURE +[id="creating-object-collections_{context}"] += Creating deployment collections + +When creating a collection, you must name it and define the rules for the collection. + +.Procedure + +. In the Collections page, click *Create collection*. +. Enter the name and description for the collection. +. In the *Collection rules* section, you must perform at least one of the following actions: +* Define the rules for the collection: See the "Creating collection rules" section for more information. +* Attach existing collections to the collection: See the "Adding attached collections" section for more information. +. The results of your rule configuration or choosing attached collections are available in the *Collection results* live preview panel. Click *Hide results* to remove this panel from display. +. Click *Save*. diff --git a/modules/create-policies-to-block-specific-cves.adoc b/modules/create-policies-to-block-specific-cves.adoc new file mode 100644 index 000000000000..9fb02bbf70fb --- /dev/null +++ b/modules/create-policies-to-block-specific-cves.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="create-policies-to-block-specific-cves_{context}"] += Creating policies to block specific CVEs by using the dashboard + +You can create new policies or add specific CVEs to an existing policy from the *Vulnerability Management* view. + +.Procedure + +. Click *CVEs* from the *Vulnerability Management* view header. +. You can select the checkboxes for one or more CVEs, and then click *Add selected CVEs to Policy* (*`add`* icon) or move the mouse over a CVE in the list, and select the *Add* icon. + +. For *Policy Name*: +** To add the CVE to an existing policy, select an existing policy from the drop-down list box. +** To create a new policy, enter the name for the new policy, and select *Create *. +. Select a value for *Severity*, either *Critical*, *High*, *Medium*, or *Low*. +. Choose the *Lifecycle Stage* to which your policy is applicable, from *Build*, or *Deploy*. +You can also select both life-cycle stages. +. Enter details about the policy in the *Description* box. +. Turn off the *Enable Policy* toggle if you want to create the policy but enable it later. +The *Enable Policy* toggle is on by default. +. Verify the listed CVEs which are included in this policy. +. Click *Save Policy*. diff --git a/modules/create-policy-categories-using-tab.adoc b/modules/create-policy-categories-using-tab.adoc new file mode 100644 index 000000000000..8e665f0c85ff --- /dev/null +++ b/modules/create-policy-categories-using-tab.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-policy-categories-using-tab_{context}"] += Creating policy categories by using the Policy categories tab + +Beginning with version 3.74, {product-title-short} provides a new method to create and manage policy categories in {product-title-managed} or in {product-title-short} if you have the PostgreSQL database enabled. All policy workflows other than policy creation remain unchanged when using this feature. + +You can also configure policy categories by using the `PolicyCategoryService` API object. For more information, go to *Help* -> *API reference* in the {product-title-short} portal. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. Click the *Policy categories* tab. This tab provides a list of existing categories and allows you to filter the list by category name. You can also click *Show all categories* and select the checkbox to remove default or custom categories from the displayed list. +. Click *Create category*. +. Enter a category name and click *Create*. + diff --git a/modules/create-policy-from-risk-view.adoc b/modules/create-policy-from-risk-view.adoc new file mode 100644 index 000000000000..9b9593203d45 --- /dev/null +++ b/modules/create-policy-from-risk-view.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-policy-from-risk-view_{context}"] += Creating a security policy from the risk view + +[role="_abstract"] +While evaluating risks in your deployments in the *Risk* view, when you apply local page filtering, you can create new security policies based on the filtering criteria you are using. + +.Procedure +. Go to the {product-title-short} portal and select *Risk* from the navigation menu. +. Apply local page filtering criteria that you want to create a policy for. +. Select *New Policy* and complete the required fields to create a new policy. For the steps to create a policy, see "Creating a security policy from the system policies view". diff --git a/modules/create-policy-from-system-policies-view.adoc b/modules/create-policy-from-system-policies-view.adoc new file mode 100644 index 000000000000..01d36e06f91e --- /dev/null +++ b/modules/create-policy-from-system-policies-view.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="create-policy-from-system-policies-view_{context}"] += Creating a security policy from the system policies view + +You can create new security policies from the system policies view. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. Click *Create policy*. +. Configure the policy definition information in the following sections. diff --git a/modules/create-resource-init-bundle.adoc b/modules/create-resource-init-bundle.adoc new file mode 100644 index 000000000000..63e0b6d0b549 --- /dev/null +++ b/modules/create-resource-init-bundle.adoc @@ -0,0 +1,143 @@ +// Module included in the following assemblies: +// +// * cloud_service/installing_cloud_other/init-bundle-cloud-other-apply.adoc +// * cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply.adoc +// * installing/installing_ocp/init-bundle-ocp.adoc +// * installing/installing_other/init-bundle-other.adoc + +//Conditionals to show ocp commands for OpenShift, kube commands for Kubernetes, Central language for non-cloud +ifeval::["{context}" == "init-bundle-cloud-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-other"] +:kube: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:kube: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:cloud: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:cloud: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:cloud-ocp-apply: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:cloud-other-apply: +endif::[] + +:_mod-docs-content-type: PROCEDURE +[id="create-resource-init-bundle_{context}"] += Applying the init bundle on the secured cluster + +//Do not show for ACSCS +ifndef::cloud[] +Before you configure a secured cluster, you must apply the init bundle by using it to create the required resources on the cluster. Applying the init bundle allows the services on the secured cluster to communicate with Central. +endif::cloud[] + +//Show for ACSCS +ifdef::cloud[] +Before you configure a secured cluster, you must apply the init bundle by using it to create the required resources on the secured cluster. Applying the init bundle allows the services on the secured cluster to communicate with {product-title-managed-short}. +endif::cloud[] + +[NOTE] +==== +If you are installing by using Helm charts, do not perform this step. Complete the installation by using Helm; See "Installing +{product-title-short} on secured clusters by using Helm charts" in the additional resources section. +==== + +.Prerequisites +* You must have generated an init bundle containing secrets. +* You must have created the `stackrox` project, or namespace, on the cluster where secured cluster services will be installed. Using `stackrox` for the project is not required, but ensures that vulnerabilities for {product-title-short} processes are not reported when scanning your clusters. + +.Procedure +//Show for OpenShift +ifdef::openshift[] +To create resources, perform only one of the following steps: + +* Create resources using the {ocp} web console: In the {ocp} web console, make sure that you are in the `stackrox` namespace. In the top menu, click *+* to open the *Import YAML* page. You can drag the init bundle file or copy and paste its contents into the editor, and then click *Create*. When the command is complete, the display shows that the `collector-tls`, `sensor-tls`, and `admission-control-tls` resources were created. + +* Create resources using the {osp} CLI: Using the {osp} CLI, run the following command to create the resources: ++ +[source,terminal] +---- +$ oc create -f \// <1> + -n <2> +---- +<1> Specify the file name of the init bundle containing the secrets. +<2> Specify the name of the project where Central services are installed. +endif::openshift[] +//Show for Kubernetes +ifdef::kube[] +* Using the `kubectl` CLI, run the following commands to create the resources: ++ +[source,terminal] +---- +$ kubectl create namespace stackrox <1> +$ kubectl create -f \// <2> + -n <3> +---- +<1> Create the project where secured cluster resources will be installed. This example uses `stackrox`. +<2> Specify the file name of the init bundle containing the secrets. +<3> Specify the project name that you created. This example uses `stackrox`. +endif::kube[] + +ifdef::cloud-ocp-apply,cloud-other-apply[] +.Verification + +* Restart Sensor to pick up the new certificates. ++ +For more information about how to restart Sensor, see "Restarting the Sensor container" in the "Additional resources" section. +endif::cloud-ocp-apply,cloud-other-apply[] + +ifeval::["{context}" == "init-bundle-cloud-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-other"] +:!kube: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:!kube: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:!cloud: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:!cloud: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:!cloud-ocp-apply: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:!cloud-other-apply: +endif::[] \ No newline at end of file diff --git a/modules/creating-a-project-using-the-CLI.adoc b/modules/creating-a-project-using-the-CLI.adoc deleted file mode 100644 index 4a06cc70d7d6..000000000000 --- a/modules/creating-a-project-using-the-CLI.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="creating-a-project-using-the-CLI_{context}"] -= Creating a project using the CLI - -If allowed by your cluster administrator, you can create a new project. - -[NOTE] -==== -Projects starting with `openshift-` and `kube-` are considered critical by {product-title}. As such, {product-title} does not allow you to create Projects starting with `openshift-` or `kube-` using the `oc new-project` command. Cluster administrators can create these Projects using the `oc adm new-project` command. -==== - -[NOTE] -==== -You cannot assign an SCC to pods created in one of the default namespaces: `default`, `kube-system`, `kube-public`, `openshift-node`, `openshift-infra`, and `openshift`. You cannot use these namespaces for running pods or services. -==== - -.Procedure - -. Run: - -[source,terminal] ----- -$ oc new-project \ - --description="" --display-name="" ----- - -For example: - -[source,terminal] ----- -$ oc new-project hello-openshift \ - --description="This is an example project" \ - --display-name="Hello OpenShift" ----- - -[NOTE] -==== -The number of projects you are allowed to create -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -may be limited by the system administrator. -endif::[] -ifdef::openshift-online[] -is limited. -endif::[] -After your limit is reached, you might have to delete an existing project in -order to create a new one. -==== diff --git a/modules/creating-a-project-using-the-web-console.adoc b/modules/creating-a-project-using-the-web-console.adoc deleted file mode 100644 index 8131ec26f5dc..000000000000 --- a/modules/creating-a-project-using-the-web-console.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="creating-a-project-using-the-web-console_{context}"] -= Creating a project using the web console - -If allowed by your cluster administrator, you can create a new project. - -[NOTE] -==== -Projects starting with `openshift-` and `kube-` are considered critical by {product-title}. As such, {product-title} does not allow you to create Projects starting with `openshift-` using the web console. -==== - -[NOTE] -==== -You cannot assign an SCC to pods created in one of the default namespaces: `default`, `kube-system`, `kube-public`, `openshift-node`, `openshift-infra`, and `openshift`. You cannot use these namespaces for running pods or services. -==== - -.Procedure - -. Navigate to *Home* -> *Projects*. - -. Click *Create Project*. - -. Enter your project details. - -. Click *Create*. diff --git a/modules/creating-an-infra-node.adoc b/modules/creating-an-infra-node.adoc deleted file mode 100644 index d37d570d25e5..000000000000 --- a/modules/creating-an-infra-node.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/cluster-tasks.adoc - -[id="creating-an-infra-node_{context}"] -= Creating an infrastructure node - -[IMPORTANT] -==== -See Creating infrastructure machine sets for installer-provisioned infrastructure environments or for any cluster where the master nodes are managed by the machine API. -==== - -Requirements of the cluster dictate that infrastructure, also called `infra` nodes, be provisioned. The installer only provides provisions for master and worker nodes. Worker nodes can be designated as infrastructure nodes or application, also called `app`, nodes through labeling. - -.Procedure - -. Add a label to the worker node that you want to act as application node: -+ -[source,terminal] ----- -$ oc label node node-role.kubernetes.io/app="" ----- - -. Add a label to the worker nodes that you want to act as infrastructure nodes: -+ -[source,terminal] ----- -$ oc label node node-role.kubernetes.io/infra="" ----- - -. Check to see if applicable nodes now have the `infra` role and `app` roles: -+ -[source,terminal] ----- -$ oc get nodes ----- - -. Create a default node selector so that pods without a node selector are assigned a subset of nodes to be deployed on, for example by default deployment in worker nodes. As an example, the `defaultNodeSelector` to deploy pods on worker nodes by default would look like: -+ -[source,yaml] ----- -defaultNodeSelector: node-role.kubernetes.io/app= ----- - -. Move infrastructure resources to the newly labeled `infra` nodes. diff --git a/modules/creating-custom-links.adoc b/modules/creating-custom-links.adoc deleted file mode 100644 index 9efac43d386d..000000000000 --- a/modules/creating-custom-links.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/customizing-the-web-console.adoc - -[id="creating-custom-links_{context}"] -= Creating custom links in the web console - -.Prerequisites - -* You must have administrator privileges. - -.Procedure - -. From *Administration* -> *Custom Resource Definitions*, click on -*ConsoleLink*. -. Select *Instances* tab -. Click *Create Console Link* and edit the file: -+ -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleLink -metadata: - name: example -spec: - href: 'https://www.example.com/' - location: HelpMenu <1> - text: Link 1 ----- -<1> Valid location settings are `HelpMenu`, `UserMenu`, `ApplicationMenu`, and -`NamespaceDashboard`. -+ -To make the custom link appear in all namespaces, follow this example: -+ -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleLink -metadata: - name: namespaced-dashboard-link-for-all-namespaces -spec: - href: 'https://www.example.com/' - location: NamespaceDashboard - text: This appears in all namespaces ----- -+ -To make the custom link appear in only some namespaces, follow this example: -+ -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleLink -metadata: - name: namespaced-dashboard-for-some-namespaces -spec: - href: 'https://www.example.com/' - location: NamespaceDashboard - # This text will appear in a box called "Launcher" under "namespace" or "project" in the web console - text: Custom Link Text - namespaceDashboard: - namespaces: - # for these specific namespaces - - my-namespace - - your-namespace - - other-namespace ----- -+ -To make the custom link appear in the application menu, follow this example: -+ -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleLink -metadata: - name: application-menu-link-1 -spec: - href: 'https://www.example.com/' - location: ApplicationMenu - text: Link 1 - applicationMenu: - section: My New Section - # image that is 24x24 in size - imageURL: https://via.placeholder.com/24 ----- - -. Click the *Save* button to apply your changes. diff --git a/modules/creating-infra-machines.adoc b/modules/creating-infra-machines.adoc deleted file mode 100644 index 0d16f13b27ec..000000000000 --- a/modules/creating-infra-machines.adoc +++ /dev/null @@ -1,112 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/cluster-tasks.adoc - -[id="creating-infra-machines_{context}"] -= Creating infrastructure machines - -If you need infrastructure machines to have dedicated configurations, then you must create an infra pool. - -.Procedure - -. Create a machine config pool that contains both the worker role and your custom role as machine config selector: -+ -[source,terminal] ----- -$ cat infra.mcp.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool -metadata: - name: infra -spec: - machineConfigSelector: - matchExpressions: - - {key: machineconfiguration.openshift.io/role, operator: In, values: [worker,infra]} - nodeSelector: - matchLabels: - node-role.kubernetes.io/infra: "" ----- - -. After you have the YAML file, you can create the machine config pool: -+ -[source,terminal] ----- -$ oc create -f infra.mcp.yaml ----- - -. Check the machine configs to ensure that the infrastructure configuration rendered successfully: -+ -[source,terminal] ----- -$ oc get machineconfig ----- -+ -.Example output -[source,terminal] ----- -NAME GENERATEDBYCONTROLLER IGNITIONVERSION CREATED -00-master 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 31d -00-worker 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 31d -01-master-container-runtime 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 31d -01-master-kubelet 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 31d -01-worker-container-runtime 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 31d -01-worker-kubelet 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 31d -99-master-1ae2a1e0-a115-11e9-8f14-005056899d54-registries 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 31d -99-master-ssh 2.2.0 31d -99-worker-1ae64748-a115-11e9-8f14-005056899d54-registries 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 31d -99-worker-ssh 2.2.0 31d -rendered-infra-4e48906dca84ee702959c71a53ee80e7 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 23m -rendered-master-072d4b2da7f88162636902b074e9e28e 5b6fb8349a29735e48446d435962dec4547d3090 2.2.0 31d -rendered-master-3e88ec72aed3886dec061df60d16d1af 02c07496ba0417b3e12b78fb32baf6293d314f79 2.2.0 31d -rendered-master-419bee7de96134963a15fdf9dd473b25 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 17d -rendered-master-53f5c91c7661708adce18739cc0f40fb 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 13d -rendered-master-a6a357ec18e5bce7f5ac426fc7c5ffcd 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 7d3h -rendered-master-dc7f874ec77fc4b969674204332da037 5b6fb8349a29735e48446d435962dec4547d3090 2.2.0 31d -rendered-worker-1a75960c52ad18ff5dfa6674eb7e533d 5b6fb8349a29735e48446d435962dec4547d3090 2.2.0 31d -rendered-worker-2640531be11ba43c61d72e82dc634ce6 5b6fb8349a29735e48446d435962dec4547d3090 2.2.0 31d -rendered-worker-4e48906dca84ee702959c71a53ee80e7 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 7d3h -rendered-worker-4f110718fe88e5f349987854a1147755 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 17d -rendered-worker-afc758e194d6188677eb837842d3b379 02c07496ba0417b3e12b78fb32baf6293d314f79 2.2.0 31d -rendered-worker-daa08cc1e8f5fcdeba24de60cd955cc3 365c1cfd14de5b0e3b85e0fc815b0060f36ab955 2.2.0 13d ----- - -. Optional: To deploy changes to a custom pool, create a machine config that uses the custom pool name as the label, such as `infra`. Note that this is not required and only shown for instructional purposes. In this manner, you can apply any custom configurations specific to only your infra nodes. -+ -[source,terminal] ----- -$ cat infra.mc.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: infra - name: 51-infra -spec: - config: - ignition: - version: 2.2.0 - storage: - files: - - contents: - source: data:,infra - filesystem: root - mode: 0644 - path: /etc/infratest ----- - -. Apply the machine config, then verify that the infra-labeled nodes are updated with the configuration file: -+ -[source,terminal] ----- -$ oc create -f infra.mc.yaml ----- diff --git a/modules/creating-new-osdk-v0-1-0-project.adoc b/modules/creating-new-osdk-v0-1-0-project.adoc deleted file mode 100644 index a7247b601c4b..000000000000 --- a/modules/creating-new-osdk-v0-1-0-project.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc - -[id="creating-new-operator-sdk-v0-1-0-project_{context}"] -= Creating a new Operator SDK v0.1.0 project - -Rename your Operator SDK v0.0.x project and create a new v0.1.0 project in its -place. - -.Prerequisites - -- Operator SDK v0.1.0 CLI installed on the development workstation -- `memcached-operator` project previously deployed using an earlier version of -Operator SDK - -.Procedure - -. Ensure the SDK version is v0.1.0: -+ ----- -$ operator-sdk --version -operator-sdk version 0.1.0 ----- - -. Create a new project: -+ ----- -$ mkdir -p $GOPATH/src/github.com/example-inc/ -$ cd $GOPATH/src/github.com/example-inc/ -$ mv memcached-operator old-memcached-operator -$ operator-sdk new memcached-operator --skip-git-init -$ ls -memcached-operator old-memcached-operator ----- - -. Copy over `.git` from old project: -+ ----- -$ cp -rf old-memcached-operator/.git memcached-operator/.git ----- diff --git a/modules/creating-runtimeclass.adoc b/modules/creating-runtimeclass.adoc deleted file mode 100644 index 8fcea09f74c8..000000000000 --- a/modules/creating-runtimeclass.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/scheduling-windows-workloads.adoc - -[id="creating-runtimeclass_{context}"] -= Creating a `RuntimeClass` object to encapsulate scheduling mechanisms - -Using a `RuntimeClass` object simplifies the use of scheduling mechanisms like taints and tolerations; you deploy a runtime class that encapsulates your taints and tolerations and then apply it to your pods to schedule them to the appropriate node. Creating a runtime class is also necessary in clusters that support multiple operating system variants. - -.Procedure - -. Create a `RuntimeClass` object YAML file. For example, `runtime-class.yaml`: -+ -[source,yaml] ----- -apiVersion: node.k8s.io/v1beta1 -kind: RuntimeClass -metadata: - name: <1> -handler: 'docker' -scheduling: - nodeSelector: <2> - kubernetes.io/os: 'windows' - kubernetes.io/arch: 'amd64' - node.kubernetes.io/windows-build: '10.0.17763' - tolerations: <3> - - effect: NoSchedule - key: os - operator: Equal - value: "Windows" ----- -<1> Specify the `RuntimeClass` object name, which is defined in the pods you want to be managed by this runtime class. -<2> Specify labels that must be present on nodes that support this runtime class. Pods using this runtime class can only be scheduled to a node matched by this selector. The node selector of the runtime class is merged with the existing node selector of the pod. Any conflicts prevent the pod from being scheduled to the node. -<3> Specify tolerations to append to pods, excluding duplicates, running with this runtime class during admission. This combines the set of nodes tolerated by the pod and the runtime class. - -. Create the `RuntimeClass` object: -+ -[source,terminal] ----- -$ oc create -f .yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f runtime-class.yaml ----- - -. Apply the `RuntimeClass` object to your pod to ensure it is scheduled to the appropriate operating system variant: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: my-windows-pod -spec: - runtimeClassName: <1> -... ----- -<1> Specify the runtime class to manage the scheduling of your pod. diff --git a/modules/creating-serverless-apps-admin-console.adoc b/modules/creating-serverless-apps-admin-console.adoc deleted file mode 100644 index be9ca3468f89..000000000000 --- a/modules/creating-serverless-apps-admin-console.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/admin_guide/serverless-cluster-admin-serving.adoc - -[id="creating-serverless-apps-admin-console_{context}"] -= Creating serverless applications using the Administrator perspective - -.Prerequisites - -To create serverless applications using the *Administrator* perspective, ensure that you have completed the following steps. - -* The {ServerlessOperatorName} and Knative Serving are installed. -* You have logged in to the web console and are in the *Administrator* perspective. - -.Procedure - -. Navigate to the *Serverless* -> *Serving* page. -. In the *Create* list, select *Service*. -. Manually enter YAML or JSON definitions, or by dragging and dropping a file into the editor. -. Click *Create*. diff --git a/modules/creating-serverless-apps-kn.adoc b/modules/creating-serverless-apps-kn.adoc deleted file mode 100644 index a384c88af07a..000000000000 --- a/modules/creating-serverless-apps-kn.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/serving-creating-managing-apps.adoc - -[id="creating-serverless-apps-kn_{context}"] -= Creating serverless applications using the kn CLI - -The following procedure describes how you can create a basic serverless application using the `kn` CLI. - -.Prerequisites -* {ServerlessOperatorName} and Knative Serving are installed on your cluster. -* You have installed `kn` CLI. - -.Procedure - -* Create a Knative service: -+ -[source,terminal] ----- -$ kn service create --image --env ----- -+ -.Example command -[source,terminal] -[source,terminal] ----- -$ kn service create event-display \ - --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- -+ -.Example output -[source,terminal] ----- -Creating service 'event-display' in namespace 'default': - - 0.271s The Route is still working to reflect the latest desired specification. - 0.580s Configuration "event-display" is waiting for a Revision to become ready. - 3.857s ... - 3.861s Ingress has not yet been reconciled. - 4.270s Ready to serve. - -Service 'event-display' created with latest revision 'event-display-bxshg-1' and URL: -http://event-display-default.apps-crc.testing ----- diff --git a/modules/creating-serverless-apps-yaml.adoc b/modules/creating-serverless-apps-yaml.adoc deleted file mode 100644 index 1486d98cec23..000000000000 --- a/modules/creating-serverless-apps-yaml.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/serving-creating-managing-apps.adoc - -[id="creating-serverless-apps-yaml_{context}"] -= Creating serverless applications using YAML - -To create a serverless application by using YAML, you must create a YAML file that defines a `Service` object, then apply it by using `oc apply`. - -.Procedure - -. Create a YAML file containing the following sample code: -+ -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: event-delivery - namespace: default -spec: - template: - spec: - containers: - - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest - env: - - name: RESPONSE - value: "Hello Serverless!" ----- -. Navigate to the directory where the YAML file is contained, and deploy the application by applying the YAML file: -+ -[source,terminal] ----- -$ oc apply -f ----- - -After the service is created and the application is deployed, Knative creates an immutable revision for this version of the application. -Knative also performs network programming to create a route, ingress, service, and load balancer for your application and automatically scales your pods up and down based on traffic, including inactive pods. diff --git a/modules/creating-the-vsphere-windows-vm-golden-image.adoc b/modules/creating-the-vsphere-windows-vm-golden-image.adoc deleted file mode 100644 index cb5eac97b81a..000000000000 --- a/modules/creating-the-vsphere-windows-vm-golden-image.adoc +++ /dev/null @@ -1,147 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc - -[id="creating-the-vsphere-windows-vm-golden-image_{context}"] -= Creating the vSphere Windows VM golden image - -Create a vSphere Windows virtual machine (VM) golden image. - -.Prerequisites - -* You have installed a cluster on vSphere configured with hybrid networking using OVN-Kubernetes. -* You have defined a custom VXLAN port in your hybrid networking configuration to work around the link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/kubernetes/common-problems#pod-to-pod-connectivity-between-hosts-is-broken-on-my-kubernetes-cluster-running-on-vsphere[pod-to-pod connectivity issue between hosts]. - -.Procedure - -. Create the VM from an updated version of the Windows Server 1909 VM image that includes the link:https://support.microsoft.com/en-us/help/4565351/windows-10-update-kb4565351[Microsoft patch KB4565351]. This patch is required to set the VXLAN UDP port, which is required for clusters installed on vSphere. This patch is not available for the `Windows Server 2019` VM image. - -. Create the `C:\Users\Administrator.ssh\authorized_keys` file in the Windows VM containing the public key that corresponds to the private key that resides in the secret you created in the `openshift-windows-machine-config-operator` namespace. The private key of the secret was created when first installing the Windows Machine Config Operator (WMCO) to give {product-title} access to Windows VMs. The `authorized_keys` file is used to configure SSH in the Windows VM. - -. Configure SSH on the Windows VM by running the following Powershell script: -+ -[source,posh] ----- -# Powershell script to configure SSH on vSphere Windows VMs -Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 -$firewallRuleName = "ContainerLogsPort" -$containerLogsPort = "10250" -New-NetFirewallRule -DisplayName $firewallRuleName -Direction Inbound -Action Allow -Protocol TCP -LocalPort $containerLogsPort -EdgeTraversalPolicy Allow -Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force -Install-Module -Force OpenSSHUtils -Set-Service -Name ssh-agent -StartupType 'Automatic' -Set-Service -Name sshd -StartupType 'Automatic' -Start-Service ssh-agent -Start-Service sshd -$pubKeyConf = (Get-Content -path C:\ProgramData\ssh\sshd_config) -replace '#PubkeyAuthentication yes','PubkeyAuthentication yes' -$pubKeyConf | Set-Content -Path C:\ProgramData\ssh\sshd_config -$passwordConf = (Get-Content -path C:\ProgramData\ssh\sshd_config) -replace '#PasswordAuthentication yes','PasswordAuthentication yes' -$passwordConf | Set-Content -Path C:\ProgramData\ssh\sshd_config -$authFileConf = (Get-Content -path C:\ProgramData\ssh\sshd_config) -replace 'AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys','#AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys' -$authFileConf | Set-Content -Path C:\ProgramData\ssh\sshd_config -$pubKeyLocationConf = (Get-Content -path C:\ProgramData\ssh\sshd_config) -replace 'Match Group administrators','#Match Group administrators' -$pubKeyLocationConf | Set-Content -Path C:\ProgramData\ssh\sshd_config -Restart-Service sshd -New-item -Path $env:USERPROFILE -Name .ssh -ItemType Directory -force ----- - -. Install and configure VMware Tools version 11.0.6 or greater on the Windows VM. See the link:https://docs.vmware.com/en/VMware-Tools/index.html[VMware Tools documentation] for more information. - -. After installing VMware Tools on the Windows VM, verify the following: -.. The `C:\ProgramData\VMware\VMware Tools\tools.conf` file has the following entry: -+ -[source,ini] ----- -exclude-nics= ----- -+ -This entry ensures the following: -+ -* The cloned vNIC generated on the Windows VM by the hybrid-overlay is not ignored. -* The VM has an IP address in vCenter. - -.. The VMTools Windows service is running. - -. Pull all of the required Windows container base images needed for your applications. The images you pull -are dependent on the Windows kernel you are using. See Microsoft's documentation on link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/container-base-images[pulling Windows container base images] for more information. - -. Run the link:https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation[Windows Sysprep tool] on the Windows VM: -+ -[source,terminal] ----- -C:\> sysprep.exe /generalize /oobe /shutdown /unattend: ----- -+ -An example `unattend.xml` is provided, which maintains all the changes needed for the WMCO. For example, the `unattend.xml` file must ensure the Administrator's home directory stays intact with the SSH public key. You must customize the example to fit your needs. -+ -.Example `unattend.xml` -[%collapsible] -==== -[source,xml] ----- - - - - - - 0409:00000409 - en-US - en-US - en-US - en-US - - - true - - - 0 - - - windows-host - My_Product_key - - - - - - - MyPassword - true</PlainText> - </Password> - <Enabled>true</Enabled> - <Username>Administrator</Username> - </AutoLogon> - <OOBE> - <HideEULAPage>true</HideEULAPage> - <HideLocalAccountScreen>true</HideLocalAccountScreen> - <HideOEMRegistrationScreen>true</HideOEMRegistrationScreen> - <HideOnlineAccountScreens>true</HideOnlineAccountScreens> - <HideWirelessSetupInOOBE>true</HideWirelessSetupInOOBE> - <NetworkLocation>Work</NetworkLocation> - <ProtectYourPC>1</ProtectYourPC> - <SkipMachineOOBE>true</SkipMachineOOBE> - <SkipUserOOBE>true</SkipUserOOBE> - </OOBE> - <RegisteredOrganization>Organization</RegisteredOrganization> - <RegisteredOwner>Owner</RegisteredOwner> - <DisableAutoDaylightTimeSet>false</DisableAutoDaylightTimeSet> - <TimeZone>Eastern Standard Time</TimeZone> - <UserAccounts> - <AdministratorPassword> - <Value>MyPassword</Value> - <PlainText>true</PlainText> - </AdministratorPassword> - <LocalAccounts> - <LocalAccount wcm:action="https://github.com/add"> - <Description>Administrator</Description> - <DisplayName>Administrator</DisplayName> - <Group>Administrators</Group> - <Name>Administrator</Name> - </LocalAccount> - </LocalAccounts> - </UserAccounts> - </component> - </settings> -</unattend> ----- -==== diff --git a/modules/creating-your-first-content.adoc b/modules/creating-your-first-content.adoc deleted file mode 100644 index 20316e749317..000000000000 --- a/modules/creating-your-first-content.adoc +++ /dev/null @@ -1,108 +0,0 @@ -// Module included in the following assemblies: -// -// assembly_getting-started-modular-docs-ocp.adoc - -// Base the file name and the ID on the module title. For example: -// * file name: doing-procedure-a.adoc -// * ID: [id="doing-procedure-a"] -// * Title: = Doing procedure A - -[id="creating-your-first-content_{context}"] -= Creating your first content - -In this procedure, you will create your first example content using modular -docs for the OpenShift docs repository. - -.Prerequisites - -* You have forked and then cloned the OpenShift docs repository locally. -* You have downloaded and are using Atom text editor for creating content. -* You have installed AsciiBinder (the build tool for OpenShift docs). - -.Procedure - -. Navigate to your locally cloned OpenShift docs repository on a command line. - -. Create a new feature branch: - -+ ----- -git checkout master -git checkout -b my_first_mod_docs ----- -+ -. If there is no `modules` directory in the root folder, create one. - -. In this `modules` directory, create a file called `my-first-module.adoc`. - -. Open this newly created file in Atom and copy into this file the contents from -the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc[procedure template] -from Modular docs repository. - -. Replace the content in this file with some example text using the guidelines -in the comments. Give this module the title `My First Module`. Save this file. -You have just created your first module. - -. Create a new directory from the root of your OpenShift docs repository and -call it `my_guide`. - -. In this my_guide directory, create a new file called -`assembly_my-first-assembly.adoc`. - -. Open this newly created file in Atom and copy into this file the contents from -the link:https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc[assembly template] -from Modular docs repository. - -. Replace the content in this file with some example text using the guidelines -in the comments. Give this assembly the title: `My First Assembly`. - -. Before the first anchor id in this assembly file, add a `:context:` attribute: - -+ -`:context: assembly-first-content` - -. After the Prerequisites section, add the module created earlier (the following is -deliberately spelled incorrectly to pass validation. Use 'include' instead of 'ilude'): - -+ -`ilude::modules/my-first-module.adoc[leveloffset=+1]` - -+ -Remove the other includes that are present in this file. Save this file. - -. Open up `my-first-module.adoc` in the `modules` folder. At the top of -this file, in the comments section, add the following to indicate in which -assembly this module is being used: - -+ ----- -// Module included in the following assemblies: -// -// my_guide/assembly_my-first-assembly.adoc ----- - -. Open up `_topic_map.yml` from the root folder and add these lines at the end -of this file and then save. - -+ ----- ---- -Name: OpenShift CCS Mod Docs First Guide -Dir: my_guide -Distros: openshift-* -Topics: -- Name: My First Assembly - File: assembly_my-first-assembly ----- - -. On the command line, run `asciibinder` from the root folder of openshift-docs. -You don't have to add or commit your changes for asciibinder to run. - -. After the asciibinder build completes, open up your browser and navigate to -<YOUR-LOCAL-GIT-REPO-LOCATION>/openshift-docs/_preview/openshift-enterprise/my_first_mod_docs/my_guide/assembly_my-first-assembly.html - -. Confirm that your book `my_guide` has an assembly `My First Assembly` with the -contents from your module `My First Module`. - -NOTE: You can delete this branch now if you are done testing. This branch -shouldn't be submitted to the upstream openshift-docs repository. diff --git a/modules/critical-sev-security-policies.adoc b/modules/critical-sev-security-policies.adoc new file mode 100644 index 000000000000..3b64e2facd2c --- /dev/null +++ b/modules/critical-sev-security-policies.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/default-security-policies.adoc +:_mod-docs-content-type: REFERENCE +[id="critical-sev-security-policies_{context}"] += Critical severity security policies + +//// +In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly. + +Be sure to include a line break between the title and the module introduction. +//// + +[role="_abstract"] +The following table lists the default security policies in {product-title} that are of critical severity. The policies are organized by lifecycle stage. + +.Critical severity security policies +[options="header"] +|==== +|Life cycle stage |Name |Description | Status +|Build or Deploy |Apache Struts: CVE-2017-5638|Alerts when deployments have images that contain the CVE-2017-5638 Apache Struts vulnerability. |Enabled +|Build or Deploy |Log4Shell: log4j Remote Code Execution vulnerability |Alerts when deployments include images that contain the CVE-2021-44228 and CVE-2021-45046 Log4Shell vulnerabilities. Flaws exist in the Apache Log4j Java logging library in versions 2.0-beta9 - 2.15.0, excluding version 2.12.2. |Enabled +|Build or Deploy |Spring4Shell (Spring Framework Remote Code Execution) and Spring Cloud Function vulnerabilities |Alerts when deployments include images that contain either the CVE-2022-22965 vulnerability, which affects Spring MVC, and the CVE-2022-22963 vulnerability, which affects Spring Cloud. In versions 3.16, 3.2.2, and older unsupported versions, Spring Cloud contains flaws. Flaws exist in Spring Framework in versions 5.3.0 - 5.3.17, versions 5.2.0 - 5.2.19, and in older unsupported versions. |Enabled +|Runtime |Iptables Executed in Privileged Container |Alerts when privileged pods run iptables. |Enabled +|==== + +//// +[role="_additional-resources"] +.Additional resources + +* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros. +* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +//// \ No newline at end of file diff --git a/modules/crs-apply-secured-cluster.adoc b/modules/crs-apply-secured-cluster.adoc new file mode 100644 index 000000000000..020b7c343f20 --- /dev/null +++ b/modules/crs-apply-secured-cluster.adoc @@ -0,0 +1,142 @@ +// Module included in the following assemblies: +// +// * cloud_service/installing_cloud_other/init-bundle-cloud-other-apply.adoc +// * cloud_service/installing_cloud_ocp/init-bundle-cloud-ocp-apply.adoc +// * installing/installing_ocp/init-bundle-ocp.adoc +// * installing/installing_other/init-bundle-other.adoc + +//Conditionals to show ocp commands for OpenShift, kube commands for Kubernetes, Central language for non-cloud +ifeval::["{context}" == "init-bundle-cloud-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-other"] +:kube: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:kube: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:cloud: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:cloud: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:cloud-ocp-apply: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:cloud-other-apply: +endif::[] + +:_mod-docs-content-type: PROCEDURE +[id="crs-apply-secured-cluster_{context}"] += Applying the cluster registration secret (CRS) on the secured cluster + +//Do not show for ACSCS +ifndef::cloud[] +Before you configure a secured cluster, you must apply the CRS to the cluster. After you have applied the CRS, the services on the secured cluster can communicate securely with Central. +endif::cloud[] + +//Show for ACSCS +ifdef::cloud[] +Before you configure a secured cluster, you must apply the CRS to the secured cluster. After you have applied the CRS, the services on the secured cluster can communicate securely with {product-title-managed-short}. +endif::cloud[] + +[NOTE] +==== +If you are installing by using Helm charts, do not perform this step. Complete the installation by using Helm; See "Installing +{product-title-short} on secured clusters by using Helm charts" in the additional resources section. +==== + +.Prerequisites +* You must have generated a CRS. + +.Procedure +//Show for OpenShift +ifdef::openshift[] +To create resources, perform only one of the following steps: + +* Create resources using the {ocp} web console: In the {ocp} web console, go to the `stackrox` project or the project where you want to install the secured cluster services. In the top menu, click *+* to open the *Import YAML* page. You can drag the CRS file or copy and paste its contents into the editor, and then click *Create*. When the command is complete, the display shows that the secret named `cluster-registration-secret` was created. + +* Create resources using the {osp} CLI: Using the {osp} CLI, run the following command to create the resources: ++ +[source,terminal] +---- +$ oc create -f <file_name.yaml> \// <1> + -n <stackrox> <2> +---- +<1> Specify the file name of the CRS. +<2> Specify the name of the project where secured cluster services are installed. +endif::openshift[] +//Show for Kubernetes +ifdef::kube[] +* Using the `kubectl` CLI, run the following commands to create the resources: ++ +[source,terminal] +---- +$ kubectl create namespace stackrox <1> +$ kubectl create -f <file_name.yaml> \// <2> + -n <stackrox> <3> +---- +<1> Create the project where secured cluster resources will be installed. This example uses `stackrox`. +<2> Specify the file name of the CRS. +<3> Specify the project name that you created. This example uses `stackrox`. +endif::kube[] + +ifdef::cloud-ocp-apply,cloud-other-apply[] +.Verification + +* Restart Sensor to pick up the new certificates. ++ +For more information about how to restart Sensor, see "Restarting the Sensor container" in the "Additional resources" section. +endif::cloud-ocp-apply,cloud-other-apply[] + +ifeval::["{context}" == "init-bundle-cloud-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-other"] +:!kube: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:!kube: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:!cloud: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:!cloud: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-apply"] +:!cloud-ocp-apply: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-apply"] +:!cloud-other-apply: +endif::[] \ No newline at end of file diff --git a/modules/crs-generate-roxctl.adoc b/modules/crs-generate-roxctl.adoc new file mode 100644 index 000000000000..c4872327dd35 --- /dev/null +++ b/modules/crs-generate-roxctl.adoc @@ -0,0 +1,124 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +// +// You must declare the `topic-helm` or `topic-operator` attribute when using this module. +:_mod-docs-content-type: PROCEDURE +[id="crs-generate-roxctl_{context}"] += Generating a CRS by using the roxctl CLI + +ifeval::["{context}" == "init-bundle-cloud-other"] +:other: +endif::[] + +ifeval::["{context}" == init-bundle-cloud-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-generate"] +:cloud-ocp-generate: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-generate"] +:cloud-other-generate: +endif::[] + +You can create a cluster registration secret by using the `roxctl` CLI. + +[NOTE] +==== +You must have the `Admin` user role to create a CRS. +==== + +.Prerequisites + +* You have configured the `ROX_API_TOKEN` and the `ROX_CENTRAL_ADDRESS` environment variables: + +.. Set the `ROX_API_TOKEN` by running the following command: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN=<api_token> +---- + +.. Set the `ROX_CENTRAL_ADDRESS` environment variable by running the following command: ++ +[source,terminal] +---- +$ export ROX_CENTRAL_ADDRESS=<address>:<port_number> +---- + +ifdef::cloud-ocp-generate,cloud-other-generate[] +[IMPORTANT] +==== +In {product-title-managed-short}, when using `roxctl` commands that require the Central address, use the *Central instance address* as displayed in the *Instance Details* section of the {cloud-console}. For example, use `acs-ABCD12345.acs.rhcloud.com` instead of `acs-data-ABCD12345.acs.rhcloud.com`. +==== +endif::cloud-ocp-generate,cloud-other-generate[] + +.Procedure + +* To generate a CRS, run the following command: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" \ + central crs generate <crs_name> \ <1> + --output <file_name> <2> +---- +<1> Enter an identifier or name for the CRS. +<2> Enter a file name or use `-` for standard output. ++ +[IMPORTANT] +==== +Ensure that you store this file securely because it contains secrets. +You can use the same file to set up multiple secured clusters. You cannot retrieve a previously-generated CRS. +==== + +Depending on the output that you select, the command might return some INFO messages about the CRS and the YAML file. + +.Sample output + +[source,terminal] +---- +INFO: Successfully generated new CRS +INFO: +INFO: Name: test-crs +INFO: Created at: 2025-02-26T19:07:21Z +INFO: Expires at: 2026-02-26T19:07:00Z +INFO: Created By: sample-token +INFO: ID: 9214a63f-7e0e-485a-baae-0757b0860ac9 +# This is a StackRox Cluster Registration Secret (CRS). +# It is used for setting up StackRox secured clusters. +# NOTE: This file contains secret data that allows connecting new secured clusters to central, +# and needs to be handled and stored accordingly. +apiVersion: v1 +data: + crs: EXAMPLEZXlKMlpYSnphVzl1SWpveExDSkRRWE1pT2xzaUxTMHRMUzFDUlVkSlRpQkRSVkpVU1VaSlEwREXAMPLE= +kind: Secret +metadata: + annotations: + crs.platform.stackrox.io/created-at: "2025-02-26T19:07:21.800414339Z" + crs.platform.stackrox.io/expires-at: "2026-02-26T19:07:00Z" + crs.platform.stackrox.io/id: 9214a63f-7e0e-485a-baae-0757b0860ac9 + crs.platform.stackrox.io/name: test-crs + creationTimestamp: null + name: cluster-registration-secret +INFO: Then CRS needs to be stored securely, since it contains secrets. +INFO: It is not possible to retrieve previously generated CRSs. +---- + +ifeval::["{context}" == "init-bundle-cloud-other"] +:!other: +endif::[] + +ifeval::["{context}" == init-bundle-cloud-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-generate"] +:!cloud-ocp-generate: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-generate"] +:!cloud-other-generate: +endif::[] \ No newline at end of file diff --git a/modules/custom-cert-existing.adoc b/modules/custom-cert-existing.adoc new file mode 100644 index 000000000000..199d116de404 --- /dev/null +++ b/modules/custom-cert-existing.adoc @@ -0,0 +1,63 @@ +// Module included in the following assemblies: +// +// * configuration/add-custom-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="custom-cert-existing_{context}"] += Adding a custom certificate for an existing instance + +.Procedure + +* If you have installed {product-title} using the Operator: ++ +. Create a `central-default-tls-cert` secret that contains the appropriate TLS certificates in the namespace where the Central service is installed by entering the following command: ++ + +[source,terminal] +---- +oc -n <namespace> create secret tls central-default-tls-cert --cert <tls-cert.pem> --key <tls-key.pem> +---- + +* If you have installed {product-title} using Helm: ++ +. Add your custom certificate and its key in the `values-private.yaml` file: ++ +[source,yaml] +---- +central: + # Configure a default TLS certificate (public cert + private key) for central + defaultTLS: + cert: | + -----BEGIN CERTIFICATE----- + EXAMPLE!MIIMIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G + ... + -----END CERTIFICATE----- + key: | + -----BEGIN EC PRIVATE KEY----- + EXAMPLE!MHcl4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo= + ... + -----END EC PRIVATE KEY----- +---- +. Use the `helm upgrade` command and provide the updated configuration file: ++ +[source,terminal] +---- + +$ helm upgrade -n stackrox --create-namespace stackrox-central-services \ + rhacs/central-services --reuse-values \//<1> + -f values-private.yaml + +---- +<1> You must use this parameter because the `values-private.yaml` file does not contain all of the required configuration values. +* If you have installed {product-title} using the `roxctl` CLI: +** Create and apply a TLS secret from the PEM-encoded key and certificate files: ++ +[source,terminal] +---- +$ oc -n stackrox create secret tls central-default-tls-cert \ + --cert <server_cert.pem> \ + --key <server_key.pem> \ + --dry-run -o yaml | oc apply -f - +---- ++ +After you run this command, Central automatically applies the new key and certificate without requiring the pod to be restarted. It might take up to a minute to propagate the changes. diff --git a/modules/custom-cert-new-install.adoc b/modules/custom-cert-new-install.adoc new file mode 100644 index 000000000000..98b32fed1df1 --- /dev/null +++ b/modules/custom-cert-new-install.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// * configuration/add-custom-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="custom-cert-new-install_{context}"] += Adding a custom certificate during a new installation + +.Procedure + +* If you are installing {product-title} using the Operator: ++ +. Create a `central-default-tls-cert` secret that contains the appropriate TLS certificates in the namespace where the Central service will be installed by entering the following command: ++ +[source,terminal] +---- +oc -n <namespace> create secret tls central-default-tls-cert --cert <tls-cert.pem> --key <tls-key.pem> +---- +* If you are installing {product-title} using Helm: ++ +. Add your custom certificate and its key in the `values-private.yaml` file: ++ +[source,yaml] +---- +central: + # Configure a default TLS certificate (public cert + private key) for central + defaultTLS: + cert: | + -----BEGIN CERTIFICATE----- + EXAMPLE!MIIMIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G + ... + -----END CERTIFICATE----- + key: | + -----BEGIN EC PRIVATE KEY----- + EXAMPLE!MHcl4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo= + ... + -----END EC PRIVATE KEY----- +---- +. Provide the configuration file during the installation: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace stackrox-central-services rhacs/central-services -f values-private.yaml +---- +* If you are installing {product-title} using the `roxctl` CLI, provide the certificate and key files when you run the installer: +** For the non-interactive installer, use the `--default-tls-cert` and `--default-tls-key` options: ++ +[source,terminal] +---- +$ roxctl central generate --default-tls-cert "cert.pem" --default-tls-key "key.pem" +---- +** For the interactive installer, provide the certificate and key files when you enter answers for the prompts: ++ +[source,text] +---- +... +Enter PEM cert bundle file (optional): <cert.pem> +Enter PEM private key file (optional): <key.pem> +Enter administrator password (default: autogenerated): +Enter orchestrator (k8s, openshift): openshift +... +---- diff --git a/modules/custom-cert-prerequisites.adoc b/modules/custom-cert-prerequisites.adoc new file mode 100644 index 000000000000..19f5def06565 --- /dev/null +++ b/modules/custom-cert-prerequisites.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * configuration/add-custom-certificates.adoc + +:_mod-docs-content-type: CONCEPT +[id="custom-cert-prerequisites_{context}"] += Prerequisites for adding custom certificates + +.Prerequisites + +* You must already have PEM-encoded private key and certificate files. +* The certificate file should begin and end with human-readable blocks. For example: ++ +[source,text] +---- +-----BEGIN CERTIFICATE----- +MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0G +... +l4wOuDwKQa+upc8GftXE2C//4mKANBC6It01gUaTIpo= +-----END CERTIFICATE----- +---- +* The certificate file can contain either a single (leaf) certificate, or a certificate chain. ++ +[WARNING] +==== +* If the certificate is not directly signed by a trusted root, you must provide the full certificate chain, including any intermediate certificates. +* All certificates in the chain must be in order so that the leaf certificate is the first and the root certificate is the last in the chain. +==== +* If you are using a custom certificate that is not globally trusted, you must also configure the Sensor to trust your custom certificate. diff --git a/modules/custom-security-policies-about.adoc b/modules/custom-security-policies-about.adoc new file mode 100644 index 000000000000..6c01e5857c06 --- /dev/null +++ b/modules/custom-security-policies-about.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="custom-security-policies-about_{context}"] += Custom security policies + +[role="_abstract"] + +{product-title-short} allows you to create custom security policies to provide security during the build, deploy, and run phases of development. You can create custom security policies by the following methods: + +* You can clone a default policy and then modify it to configure specific information for your environment +* You can use the {product-title-short} portal to create and save a new policy. +* With the policy as code feature, you can create and save policies as Kubernetes custom resources (CRs) and use a Kubernetes-native continuous delivery (CD) tool such as Argo CD to apply them to clusters. + +For more information, see "Creating and modifying custom security policies". \ No newline at end of file diff --git a/modules/custom-tuning-example.adoc b/modules/custom-tuning-example.adoc deleted file mode 100644 index f7317bdb3a69..000000000000 --- a/modules/custom-tuning-example.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/using-node-tuning-operator.adoc - -[id="custom-tuning-example_{context}"] -= Custom tuning example - -The following CR applies custom node-level tuning for -{product-title} nodes with label -`tuned.openshift.io/ingress-node-label` set to any value. -As an administrator, use the following command to create a custom Tuned CR. - -.Custom tuning example -[source,terminal] ----- -$ oc create -f- <<_EOF_ -apiVersion: tuned.openshift.io/v1 -kind: Tuned -metadata: - name: ingress - namespace: openshift-cluster-node-tuning-operator -spec: - profile: - - data: | - [main] - summary=A custom OpenShift ingress profile - include=openshift-control-plane - [sysctl] - net.ipv4.ip_local_port_range="1024 65535" - net.ipv4.tcp_tw_reuse=1 - name: openshift-ingress - recommend: - - match: - - label: tuned.openshift.io/ingress-node-label - priority: 10 - profile: openshift-ingress -_EOF_ ----- - -[IMPORTANT] -==== -Custom profile writers are strongly encouraged to include the default TuneD -daemon profiles shipped within the default Tuned CR. The example above uses the -default `openshift-control-plane` profile to accomplish this. -==== diff --git a/modules/custom-tuning-specification.adoc b/modules/custom-tuning-specification.adoc deleted file mode 100644 index f07c9d70372f..000000000000 --- a/modules/custom-tuning-specification.adoc +++ /dev/null @@ -1,177 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/using-node-tuning-operator.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="custom-tuning-specification_{context}"] -= Custom tuning specification - -The custom resource (CR) for the Operator has two major sections. The first section, `profile:`, is a list of TuneD profiles and their names. The second, `recommend:`, defines the profile selection logic. - -Multiple custom tuning specifications can co-exist as multiple CRs in the Operator's namespace. The existence of new CRs or the deletion of old CRs is detected by the Operator. All existing custom tuning specifications are merged and appropriate objects for the containerized TuneD daemons are updated. - -*Management state* - -The Operator Management state is set by adjusting the default Tuned CR. By default, the Operator is in the Managed state and the `spec.managementState` field is not present in the default Tuned CR. Valid values for the Operator Management state are as follows: - - * Managed: the Operator will update its operands as configuration resources are updated - * Unmanaged: the Operator will ignore changes to the configuration resources - * Removed: the Operator will remove its operands and resources the Operator provisioned - -*Profile data* - -The `profile:` section lists TuneD profiles and their names. - -[source,yaml] ----- -profile: -- name: tuned_profile_1 - data: | - # TuneD profile specification - [main] - summary=Description of tuned_profile_1 profile - - [sysctl] - net.ipv4.ip_forward=1 - # ... other sysctl's or other TuneD daemon plugins supported by the containerized TuneD - -# ... - -- name: tuned_profile_n - data: | - # TuneD profile specification - [main] - summary=Description of tuned_profile_n profile - - # tuned_profile_n profile settings ----- - -*Recommended profiles* - -The `profile:` selection logic is defined by the `recommend:` section of the CR. The `recommend:` section is a list of items to recommend the profiles based on a selection criteria. - -[source,yaml] ----- -recommend: -<recommend-item-1> -# ... -<recommend-item-n> ----- - -The individual items of the list: - -[source,yaml] ----- -- machineConfigLabels: <1> - <mcLabels> <2> - match: <3> - <match> <4> - priority: <priority> <5> - profile: <tuned_profile_name> <6> ----- -<1> Optional. -<2> A dictionary of key/value `MachineConfig` labels. The keys must be unique. -<3> If omitted, profile match is assumed unless a profile with a higher priority matches first or `machineConfigLabels` is set. -<4> An optional list. -<5> Profile ordering priority. Lower numbers mean higher priority (`0` is the highest priority). -<6> A TuneD profile to apply on a match. For example `tuned_profile_1`. - -`<match>` is an optional list recursively defined as follows: - -[source,yaml] ----- -- label: <label_name> <1> - value: <label_value> <2> - type: <label_type> <3> - <match> <4> ----- -<1> Node or pod label name. -<2> Optional node or pod label value. If omitted, the presence of `<label_name>` is enough to match. -<3> Optional object type (`node` or `pod`). If omitted, `node` is assumed. -<4> An optional `<match>` list. - -If `<match>` is not omitted, all nested `<match>` sections must also evaluate to `true`. Otherwise, `false` is assumed and the profile with the respective `<match>` section will not be applied or recommended. Therefore, the nesting (child `<match>` sections) works as logical AND operator. Conversely, if any item of the `<match>` list matches, the entire `<match>` list evaluates to `true`. Therefore, the list acts as logical OR operator. - -If `machineConfigLabels` is defined, machine config pool based matching is turned on for the given `recommend:` list item. `<mcLabels>` specifies the labels for a machine config. The machine config is created automatically to apply host settings, such as kernel boot parameters, for the profile `<tuned_profile_name>`. This involves finding all machine config pools with machine config selector matching `<mcLabels>` and setting the profile `<tuned_profile_name>` on all nodes that are assigned the found machine config pools. - - -The list items `match` and `machineConfigLabels` are connected by the logical OR operator. The `match` item is evaluated first in a short-circuit manner. Therefore, if it evaluates to `true`, the `machineConfigLabels` item is not considered. - -[IMPORTANT] -==== -When using machine config pool based matching, it is advised to group nodes with the same hardware configuration into the same machine config pool. Not following this practice might result in TuneD operands calculating conflicting kernel parameters for two or more nodes sharing the same machine config pool. -==== - -.Example: node or pod label based matching -[source,yaml] ----- -- match: - - label: tuned.openshift.io/elasticsearch - match: - - label: node-role.kubernetes.io/master - - label: node-role.kubernetes.io/infra - type: pod - priority: 10 - profile: openshift-control-plane-es -- match: - - label: node-role.kubernetes.io/master - - label: node-role.kubernetes.io/infra - priority: 20 - profile: openshift-control-plane -- priority: 30 - profile: openshift-node ----- - -The CR above is translated for the containerized TuneD daemon into its `recommend.conf` file based on the profile priorities. The profile with the -highest priority (`10`) is `openshift-control-plane-es` and, therefore, it is considered first. The containerized TuneD daemon running on a given node looks to see if there is a pod running on the same node with the `tuned.openshift.io/elasticsearch` label set. If not, the entire `<match>` section evaluates as `false`. If there is such a pod with the label, in order for the `<match>` section to evaluate to `true`, the node label also needs to be `node-role.kubernetes.io/master` or `node-role.kubernetes.io/infra`. - -If the labels for the profile with priority `10` matched, `openshift-control-plane-es` profile is applied and no other profile is considered. If the node/pod label combination did not match, the second highest priority profile (`openshift-control-plane`) is considered. This profile is applied if the containerized TuneD pod runs on a node with labels `node-role.kubernetes.io/master` or `node-role.kubernetes.io/infra`. - -Finally, the profile `openshift-node` has the lowest priority of `30`. It lacks the `<match>` section and, therefore, will always match. It acts as a profile catch-all to set `openshift-node` profile, if no other profile with higher priority matches on a given node. - -image::node-tuning-operator-workflow-revised.png[Decision workflow] - -.Example: machine config pool based matching -[source,yaml] ----- -apiVersion: tuned.openshift.io/v1 -kind: Tuned -metadata: - name: openshift-node-custom - namespace: openshift-cluster-node-tuning-operator -spec: - profile: - - data: | - [main] - summary=Custom OpenShift node profile with an additional kernel parameter - include=openshift-node - [bootloader] - cmdline_openshift_node_custom=+skew_tick=1 - name: openshift-node-custom - - recommend: - - machineConfigLabels: - machineconfiguration.openshift.io/role: "worker-custom" - priority: 20 - profile: openshift-node-custom ----- - -To minimize node reboots, label the target nodes with a label the machine config pool's node selector will match, then create the Tuned CR above and finally create the custom machine config pool itself. - -// $ oc label node <node> node-role.kubernetes.io/worker-custom= -// $ oc create -f <tuned-cr-above> -// $ oc create -f- <<EOF -// apiVersion: machineconfiguration.openshift.io/v1 -// kind: MachineConfigPool -// metadata: -// name: worker-custom -// labels: -// worker-custom: "" -// spec: -// machineConfigSelector: -// matchExpressions: -// - {key: machineconfiguration.openshift.io/role, operator: In, values: [worker,worker-custom]} -// nodeSelector: -// matchLabels: -// node-role.kubernetes.io/worker-custom: "" -// EOF diff --git a/modules/custom-yaml-configuration.adoc b/modules/custom-yaml-configuration.adoc new file mode 100644 index 000000000000..2836ae982a89 --- /dev/null +++ b/modules/custom-yaml-configuration.adoc @@ -0,0 +1,95 @@ +// Module included in the following assemblies: +// +// * configuration/configure-endpoints.adoc +:_mod-docs-content-type: CONCEPT +[id="custom-yaml-configuration_{context}"] += Custom YAML configuration + +[role="_abstract"] +{product-title} uses the YAML configuration as a `ConfigMap`, making configurations easier to change and manage. + +When you use the custom YAML configuration file, you can configure the following for each endpoint: + +* The protocols to use, such as `HTTP`, `gRPC`, or both. +* Enable or disable TLS. +* Specify server certificates. +* Client Certificate Authorities (CA) to trust for client authentication. +* Specify if client certificate authentication (`mTLS`) is required. + +You can use the configuration file to specify endpoints either during the installation or on an existing instance of {product-title}. +However, if you expose any additional ports other than the default port `8443`, you must create network policies that allow traffic on those additional ports. + +The following is a sample `endpoints.yaml` configuration file for {product-title}: + +[source,yaml,subs=attributes+] +---- +# Sample endpoints.yaml configuration for Central. +# +# # CAREFUL: If the following line is uncommented, do not expose the default endpoint on port 8443 by default. +# # This will break normal operation. +# disableDefault: true # if true, do not serve on :8443 <1> +endpoints: <2> + # Serve plaintext HTTP only on port 8080 + - listen: ":8080" <3> + # Backend protocols, possible values are 'http' and 'grpc'. If unset or empty, assume both. + protocols: <4> + - http + tls: <5> + # Disable TLS. If this is not specified, assume TLS is enabled. + disable: true <6> + # Serve HTTP and gRPC for sensors only on port 8444 + - listen: ":8444" <3> + tls: <5> + # Which TLS certificates to serve, possible values are 'service' (For service certificates that {product-title} generates) + # and 'default' (user-configured default TLS certificate). If unset or empty, assume both. + serverCerts: <7> + - default + - service + # Client authentication settings. + clientAuth: <8> + # Enforce TLS client authentication. If unset, do not enforce, only request certificates + # opportunistically. + required: true <9> + # Which TLS client CAs to serve, possible values are 'service' (CA for service + # certificates that {product-title} generates) and 'user' (CAs for PKI auth providers). If unset or empty, assume both. + certAuthorities: <10> + # if not set, assume ["user", "service"] + - service +---- +<1> Use `true` to disable exposure on the default port number `8443`. +The default value is `false`; changing it to `true` might break existing functionality. +<2> A list of additional endpoints for exposing Central. +<3> The address and port number on which to listen. You must specify this value if you are using `endpoints`. +You can use the format `port`, `:port`, or `address:port` to specify values. +For example, +* `8080` or `:8080` - listen on port `8080` on all interfaces. +* `0.0.0.0:8080` - listen on port `8080` on all IPv4 (not IPv6) interfaces. +* `127.0.0.1:8080` - listen on port `8080` on the local loopback device only. +<4> Protocols to use for the specified endpoint. +Acceptable values are `http` and `grpc`. +If you do not specify a value, Central listens to both HTTP and gRPC traffic on the specified port. +If you want to expose an endpoint exclusively for the {product-title-short} portal, use `http`. +However, you will not be able to use the endpoint for service-to-service communication or for the `roxctl` CLI, because these clients require both gRPC and HTTP. +Red{nbsp}Hat recommends that you do not specify a value of this key, to enable both HTTP and gRPC protocols for the endpoint. +If you want to restrict an endpoint to {product-title} services only, use the *clientAuth* option. +<5> Use it to specify the TLS settings for the endpoint. +If you do not specify a value, {product-title} enables TLS with the default settings for all the following nested keys. +<6> Use `true` to disable TLS on the specified endpoint. +The default value is `false`. +When you set it to `true`, you cannot specify values for `serverCerts` and `clientAuth`. +<7> Specify a list of sources from which to configure server TLS certificates. +The `serverCerts` list is order-dependent, it means that the first item in the list determines the certificate that Central uses by default, when there is no matching SNI (Server Name Indication). +You can use this to specify multiple certificates and Central automatically selects the right certificate based on SNI. +Acceptable values are: +* `default`: use the already configured custom TLS certificate if it exists. +* `service`: use the internal service certificate that {product-title} generates. +<8> Use it to configure the behavior of the TLS-enabled endpoint's client certificate authentication. +<9> Use `true` to only allow clients with a valid client certificate. +The default value is `false`. +You can use `true` in conjunction with a the `certAuthorities` setting of `service` to only allow {product-title} services to connect to this endpoint. +<10> A list of CA to verify client certificates. The default value is `["service", "user"]`. +The `certAuthorities` list is order-independent, it means that the position of the items in this list does not matter. +Also, setting it as empty list `[]` disables client certificate authentication for the endpoint, which is different from leaving this value unset. +Acceptable values are: +* `service`: CA for service certificates that {product-title} generates. +* `user`: CAs configured by PKI authentication providers. diff --git a/modules/customize-certificates-add-service-serving-apiservice.adoc b/modules/customize-certificates-add-service-serving-apiservice.adoc deleted file mode 100644 index 589540160bf1..000000000000 --- a/modules/customize-certificates-add-service-serving-apiservice.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/service-serving-certificate.adoc - -[id="add-service-certificate-apiservice_{context}"] -= Add the service CA bundle to an API service - -You can annotate an `APIService` object with `service.beta.openshift.io/inject-cabundle=true` to have its `spec.caBundle` field populated with the service CA bundle. This allows the Kubernetes API server to validate the service CA certificate used to secure the targeted endpoint. - -.Procedure - -. Annotate the API service with `service.beta.openshift.io/inject-cabundle=true`: -+ -[source,terminal] ----- -$ oc annotate apiservice <api_service_name> \//<1> - service.beta.openshift.io/inject-cabundle=true ----- -<1> Replace `<api_service_name>` with the name of the API service to annotate. -+ -For example, use the following command to annotate the API service `test1`: -+ -[source,terminal] ----- -$ oc annotate apiservice test1 service.beta.openshift.io/inject-cabundle=true ----- - -. View the API service to ensure that the service CA bundle has been injected: -+ -[source,terminal] ----- -$ oc get apiservice <api_service_name> -o yaml ----- -+ -The CA bundle is displayed in the `spec.caBundle` field in the YAML output: -+ -[source,terminal] ----- -apiVersion: apiregistration.k8s.io/v1 -kind: APIService -metadata: - annotations: - service.beta.openshift.io/inject-cabundle: "true" -... -spec: - caBundle: <CA_BUNDLE> -... ----- diff --git a/modules/customize-certificates-add-service-serving-configmap.adoc b/modules/customize-certificates-add-service-serving-configmap.adoc deleted file mode 100644 index 6ea32eb352ba..000000000000 --- a/modules/customize-certificates-add-service-serving-configmap.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/service-serving-certificate.adoc - -[id="add-service-certificate-configmap_{context}"] -= Add the service CA bundle to a config map - -A Pod can access the service CA certificate by mounting a `ConfigMap` object that -is annotated with `service.beta.openshift.io/inject-cabundle=true`. -Once annotated, the cluster automatically injects the service CA -certificate into the `service-ca.crt` key on the config map. Access to -this CA certificate allows TLS clients to verify connections to -services using service serving certificates. - -[IMPORTANT] -==== -After adding this annotation to a config map all existing data in it is -deleted. It is recommended to use a separate config map to contain the -`service-ca.crt`, instead of using the same config map that stores your -pod configuration. -==== - -.Procedure - -. Annotate the config map with `service.beta.openshift.io/inject-cabundle=true`: -+ -[source,terminal] ----- -$ oc annotate configmap <config_map_name> \//<1> - service.beta.openshift.io/inject-cabundle=true ----- -<1> Replace `<config_map_name>` with the name of the config map to annotate. -+ -[NOTE] -==== -Explicitly referencing the `service-ca.crt` key in a volume mount will prevent a pod from starting until the config map has been injected with the CA bundle. This behavior can be overridden by setting the `optional` field to `true` for the volume's serving certificate configuration. -==== -+ -For example, use the following command to annotate the config map `test1`: -+ -[source,terminal] ----- -$ oc annotate configmap test1 service.beta.openshift.io/inject-cabundle=true ----- - -. View the config map to ensure that the service CA bundle has been injected: -+ -[source,terminal] ----- -$ oc get configmap <config_map_name> -o yaml ----- -+ -The CA bundle is displayed as the value of the `service-ca.crt` key in the YAML output: -+ -[source,terminal] ----- -apiVersion: v1 -data: - service-ca.crt: | - -----BEGIN CERTIFICATE----- -... ----- diff --git a/modules/customize-certificates-add-service-serving-crd.adoc b/modules/customize-certificates-add-service-serving-crd.adoc deleted file mode 100644 index 85a7eccf5f54..000000000000 --- a/modules/customize-certificates-add-service-serving-crd.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/service-serving-certificate.adoc - -[id="add-service-certificate-crd_{context}"] -= Add the service CA bundle to a custom resource definition - -You can annotate a `CustomResourceDefinition` (CRD) object with `service.beta.openshift.io/inject-cabundle=true` to have its `spec.conversion.webhook.clientConfig.caBundle` field populated with the service CA bundle. This allows the Kubernetes API server to validate the service CA certificate used to secure the targeted endpoint. - -[NOTE] -==== -The service CA bundle will only be injected into the CRD if the CRD is configured to use a webhook for conversion. It is only useful to inject the service CA bundle if a CRD's webhook is secured with a service CA certificate. -==== - -.Procedure - -. Annotate the CRD with `service.beta.openshift.io/inject-cabundle=true`: -+ -[source,terminal] ----- -$ oc annotate crd <crd_name> \//<1> - service.beta.openshift.io/inject-cabundle=true ----- -<1> Replace `<crd_name>` with the name of the CRD to annotate. -+ -For example, use the following command to annotate the CRD `test1`: -+ -[source,terminal] ----- -$ oc annotate crd test1 service.beta.openshift.io/inject-cabundle=true ----- - -. View the CRD to ensure that the service CA bundle has been injected: -+ -[source,terminal] ----- -$ oc get crd <crd_name> -o yaml ----- -+ -The CA bundle is displayed in the `spec.conversion.webhook.clientConfig.caBundle` field in the YAML output: -+ -[source,terminal] ----- -apiVersion: apiextensions.k8s.io/v1 -kind: CustomResourceDefinition -metadata: - annotations: - service.beta.openshift.io/inject-cabundle: "true" -... -spec: - conversion: - strategy: Webhook - webhook: - clientConfig: - caBundle: <CA_BUNDLE> -... ----- diff --git a/modules/customize-certificates-add-service-serving-mutating-webhook.adoc b/modules/customize-certificates-add-service-serving-mutating-webhook.adoc deleted file mode 100644 index e623a79ec4c0..000000000000 --- a/modules/customize-certificates-add-service-serving-mutating-webhook.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/service-serving-certificate.adoc - -[id="add-service-certificate-mutating-webhook_{context}"] -= Add the service CA bundle to a mutating webhook configuration - -You can annotate a `MutatingWebhookConfiguration` object with `service.beta.openshift.io/inject-cabundle=true` to have the `clientConfig.caBundle` field of each webhook populated with the service CA bundle. This allows the Kubernetes API server to validate the service CA certificate used to secure the targeted endpoint. - -[NOTE] -==== -Do not set this annotation for admission webhook configurations that need to specify different CA bundles for different webhooks. If you do, then the service CA bundle will be injected for all webhooks. -==== - -.Procedure - -. Annotate the mutating webhook configuration with `service.beta.openshift.io/inject-cabundle=true`: -+ -[source,terminal] ----- -$ oc annotate mutatingwebhookconfigurations <mutating_webhook_name> \//<1> - service.beta.openshift.io/inject-cabundle=true ----- -<1> Replace `<mutating_webhook_name>` with the name of the mutating webhook configuration to annotate. -+ -For example, use the following command to annotate the mutating webhook configuration `test1`: -+ -[source,terminal] ----- -$ oc annotate mutatingwebhookconfigurations test1 service.beta.openshift.io/inject-cabundle=true ----- - -. View the mutating webhook configuration to ensure that the service CA bundle has been injected: -+ -[source,terminal] ----- -$ oc get mutatingwebhookconfigurations <mutating_webhook_name> -o yaml ----- -+ -The CA bundle is displayed in the `clientConfig.caBundle` field of all webhooks in the YAML output: -+ -[source,terminal] ----- -apiVersion: admissionregistration.k8s.io/v1 -kind: MutatingWebhookConfiguration -metadata: - annotations: - service.beta.openshift.io/inject-cabundle: "true" -... -webhooks: -- myWebhook: - - v1beta1 - clientConfig: - caBundle: <CA_BUNDLE> -... ----- diff --git a/modules/customize-certificates-add-service-serving-validating-webhook.adoc b/modules/customize-certificates-add-service-serving-validating-webhook.adoc deleted file mode 100644 index 60c92348555c..000000000000 --- a/modules/customize-certificates-add-service-serving-validating-webhook.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/service-serving-certificate.adoc - -[id="add-service-certificate-validating-webhook_{context}"] -= Add the service CA bundle to a validating webhook configuration - -You can annotate a `ValidatingWebhookConfiguration` object with `service.beta.openshift.io/inject-cabundle=true` to have the `clientConfig.caBundle` field of each webhook populated with the service CA bundle. This allows the Kubernetes API server to validate the service CA certificate used to secure the targeted endpoint. - -[NOTE] -==== -Do not set this annotation for admission webhook configurations that need to specify different CA bundles for different webhooks. If you do, then the service CA bundle will be injected for all webhooks. -==== - -.Procedure - -. Annotate the validating webhook configuration with `service.beta.openshift.io/inject-cabundle=true`: -+ -[source,terminal] ----- -$ oc annotate validatingwebhookconfigurations <validating_webhook_name> \//<1> - service.beta.openshift.io/inject-cabundle=true ----- -<1> Replace `<validating_webhook_name>` with the name of the validating webhook configuration to annotate. -+ -For example, use the following command to annotate the validating webhook configuration `test1`: -+ -[source,terminal] ----- -$ oc annotate validatingwebhookconfigurations test1 service.beta.openshift.io/inject-cabundle=true ----- - -. View the validating webhook configuration to ensure that the service CA bundle has been injected: -+ -[source,terminal] ----- -$ oc get validatingwebhookconfigurations <validating_webhook_name> -o yaml ----- -+ -The CA bundle is displayed in the `clientConfig.caBundle` field of all webhooks in the YAML output: -+ -[source,terminal] ----- -apiVersion: admissionregistration.k8s.io/v1 -kind: ValidatingWebhookConfiguration -metadata: - annotations: - service.beta.openshift.io/inject-cabundle: "true" -... -webhooks: -- myWebhook: - - v1beta1 - clientConfig: - caBundle: <CA_BUNDLE> -... ----- diff --git a/modules/customize-certificates-add-service-serving.adoc b/modules/customize-certificates-add-service-serving.adoc deleted file mode 100644 index e9ea8b41f2bb..000000000000 --- a/modules/customize-certificates-add-service-serving.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/service-serving-certificate.adoc - -[id="add-service-certificate_{context}"] -= Add a service certificate - -To secure communication to your service, generate a -signed serving certificate and key pair into a secret in the same -namespace as the service. - -[IMPORTANT] -==== -The generated certificate is only valid for the internal service DNS name -`<service.name>.<service.namespace>.svc`, and are only valid for -internal communications. -==== - -.Prerequisites: - -* You must have a service defined. - -.Procedure - -. Annotate the service with `service.beta.openshift.io/serving-cert-secret-name`: -+ -[source,terminal] ----- -$ oc annotate service <service_name> \//<1> - service.beta.openshift.io/serving-cert-secret-name=<secret_name> //<2> ----- -<1> Replace `<service_name>` with the name of the service to secure. -<2> `<secret_name>` will be the name of the generated secret containing the -certificate and key pair. For convenience, it is recommended that this -be the same as `<service_name>`. -+ -For example, use the following command to annotate the service `test1`: -+ -[source,terminal] ----- -$ oc annotate service test1 service.beta.openshift.io/serving-cert-secret-name=test1 ----- - -. Examine the service to confirm that the annotations are present: -+ -[source,terminal] ----- -$ oc describe service <service_name> ----- -+ -.Example output -[source,terminal] ----- -... -Annotations: service.beta.openshift.io/serving-cert-secret-name: <service_name> - service.beta.openshift.io/serving-cert-signed-by: openshift-service-serving-signer@1556850837 -... ----- - -. After the cluster generates a secret for your service, your `Pod` spec can -mount it, and the pod will run after it becomes available. diff --git a/modules/customize-certificates-api-add-named.adoc b/modules/customize-certificates-api-add-named.adoc deleted file mode 100644 index eee2d8027c5b..000000000000 --- a/modules/customize-certificates-api-add-named.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/api-server.adoc - -[id="customize-certificates-api-add-named_{context}"] -= Add an API server named certificate - -The default API server certificate is issued by an internal {product-title} -cluster CA. You can add one or more alternative certificates that the API -server will return based on the fully qualified domain name (FQDN) requested by -the client, for example when a reverse proxy or load balancer is used. - -.Prerequisites - -* You must have a certificate for the FQDN and its corresponding private key. Each should be in a separate PEM format file. -* The private key must be unencrypted. If your key is encrypted, decrypt it -before importing it into {product-title}. -* The certificate must include the `subjectAltName` extension showing the FQDN. -* The certificate file can contain one or more certificates in a chain. The -certificate for the API server FQDN must be the first certificate in the file. -It can then be followed with any intermediate certificates, and the file should -end with the root CA certificate. - -[WARNING] -==== -Do not provide a named certificate for the internal load balancer (host -name `api-int.<cluster_name>.<base_domain>`). Doing so will leave your -cluster in a degraded state. -==== - -.Procedure - -. Create a secret that contains the certificate chain and private key in the -`openshift-config` namespace. -+ -[source,terminal] ----- -$ oc create secret tls <secret> \//<1> - --cert=</path/to/cert.crt> \//<2> - --key=</path/to/cert.key> \//<3> - -n openshift-config ----- -<1> `<secret>` is the name of the secret that will contain the certificate chain and private key. -<2> `</path/to/cert.crt>` is the path to the certificate chain on your local file system. -<3> `</path/to/cert.key>` is the path to the private key associated with this certificate. - -. Update the API server to reference the created secret. -+ -[source,terminal] ----- -$ oc patch apiserver cluster \ - --type=merge -p \ - '{"spec":{"servingCerts": {"namedCertificates": - [{"names": ["<FQDN>"], //<1> - "servingCertificate": {"name": "<secret>"}}]}}}' <2> ----- -<1> Replace `<FQDN>` with the FQDN that the API server should provide the certificate for. -<2> Replace `<secret>` with the name used for the secret in the previous step. - -. Examine the `apiserver/cluster` object and confirm the secret is now -referenced. -+ -[source,terminal] ----- -$ oc get apiserver cluster -o yaml ----- -+ -.Example output -[source,terminal] ----- -... -spec: - servingCerts: - namedCertificates: - - names: - - <FQDN> - servingCertificate: - name: <secret> -... ----- diff --git a/modules/customize-certificates-manually-rotate-service-ca.adoc b/modules/customize-certificates-manually-rotate-service-ca.adoc deleted file mode 100644 index d73aa2c44002..000000000000 --- a/modules/customize-certificates-manually-rotate-service-ca.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/certificates/service-signing-certificates.adoc - -[id="manually-rotate-service-ca_{context}"] -= Manually rotate the service CA certificate - -The service CA is valid for 26 months and is automatically refreshed when there is less than six months validity left. - -If necessary, you can manually refresh the service CA by using the following procedure. - -[WARNING] -==== -A manually-rotated service CA does not maintain trust with the previous service CA. You might experience a temporary service disruption until the pods in the cluster are restarted, which ensures that pods are using service serving certificates issued by the new service CA. -==== - -.Prerequisites - -* You must be logged in as a cluster admin. - -.Procedure - -. View the expiration date of the current service CA certificate by -using the following command. -+ -[source,terminal] ----- -$ oc get secrets/signing-key -n openshift-service-ca \ - -o template='{{index .data "tls.crt"}}' \ - | base64 -d \ - | openssl x509 -noout -enddate ----- - -. Manually rotate the service CA. This process generates a new service CA -which will be used to sign the new service certificates. -+ -[source,terminal] ----- -$ oc delete secret/signing-key -n openshift-service-ca ----- - -. To apply the new certificates to all services, restart all the pods -in your cluster. This command ensures that all services use the -updated certificates. -+ -[source,terminal] ----- -$ for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); \ - do oc delete pods --all -n $I; \ - sleep 1; \ - done ----- -+ -[WARNING] -==== -This command will cause a service interruption, as it goes through and -deletes every running pod in every namespace. These pods will automatically -restart after they are deleted. -==== diff --git a/modules/customize-certificates-replace-default-router.adoc b/modules/customize-certificates-replace-default-router.adoc deleted file mode 100644 index c126771d1576..000000000000 --- a/modules/customize-certificates-replace-default-router.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/replacing-default-ingress-certificate.adoc - -[id="replacing-default-ingress_{context}"] -= Replacing the default ingress certificate - -You can replace the default ingress certificate for all -applications under the `.apps` subdomain. After you replace -the certificate, all applications, including the web console -and CLI, will have encryption provided by specified certificate. - -.Prerequisites - -* You must have a wildcard certificate for the fully qualified `.apps` subdomain -and its corresponding private key. Each should be in a separate PEM format file. -* The private key must be unencrypted. If your key is encrypted, decrypt it -before importing it into {product-title}. -* The certificate must include the `subjectAltName` extension showing -`*.apps.<clustername>.<domain>`. -* The certificate file can contain one or more certificates in a chain. The -wildcard certificate must be the first certificate in the file. It can then be -followed with any intermediate certificates, and the file should end with the -root CA certificate. -* Copy the root CA certificate into an additional PEM format file. - -.Procedure - -. Create a config map that includes only the root CA certificate used to sign the wildcard certificate: -+ -[source,terminal] ----- -$ oc create configmap custom-ca \ - --from-file=ca-bundle.crt=</path/to/example-ca.crt> \//<1> - -n openshift-config ----- -<1> `</path/to/example-ca.crt>` is the path to the root CA certificate file on your local file system. - -. Update the cluster-wide proxy configuration with the newly created config map: -+ -[source,terminal] ----- -$ oc patch proxy/cluster \ - --type=merge \ - --patch='{"spec":{"trustedCA":{"name":"custom-ca"}}}' ----- - -. Create a secret that contains the wildcard certificate chain and key: -+ -[source,terminal] ----- -$ oc create secret tls <secret> \//<1> - --cert=</path/to/cert.crt> \//<2> - --key=</path/to/cert.key> \//<3> - -n openshift-ingress ----- -<1> `<secret>` is the name of the secret that will contain the certificate chain -and private key. -<2> `</path/to/cert.crt>` is the path to the certificate chain on your local -file system. -<3> `</path/to/cert.key>` is the path to the private key associated -with this certificate. - -. Update the Ingress Controller configuration with the newly created -secret: -+ -[source,terminal] ----- -$ oc patch ingresscontroller.operator default \ - --type=merge -p \ - '{"spec":{"defaultCertificate": {"name": "<secret>"}}}' \//<1> - -n openshift-ingress-operator ----- -<1> Replace `<secret>` with the name used for the secret in -the previous step. diff --git a/modules/customize-certificates-rotate-service-serving.adoc b/modules/customize-certificates-rotate-service-serving.adoc deleted file mode 100644 index a6dcee1de1db..000000000000 --- a/modules/customize-certificates-rotate-service-serving.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/service-serving-certificate.adoc - -[id="rotate-service-serving_{context}"] -= Manually rotate the generated service certificate - -You can rotate the service certificate by deleting the -associated secret. Deleting the secret results in a new one -being automatically created, resulting in a new certificate. - -.Prerequisites - -* A secret containing the certificate and key pair must -have been generated for the service. - -.Procedure - -. Examine the service to determine the secret containing the -certificate. This is found in the `serving-cert-secret-name` -annotation, as seen below. -+ -[source,terminal] ----- -$ oc describe service <service_name> ----- -+ -.Example output -[source,terminal] ----- -... -service.beta.openshift.io/serving-cert-secret-name: <secret> -... ----- - -. Delete the generated secret for the service. This process -will automatically recreate the secret. -+ -[source,terminal] ----- -$ oc delete secret <secret> //<1> ----- -<1> Replace `<secret>` with the name of the secret from the previous -step. - -. Confirm that the certificate has been recreated -by obtaining the new secret and examining the `AGE`. -+ -[source,terminal] ----- -$ oc get secret <service_name> ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE DATA AGE -<service.name> kubernetes.io/tls 2 1s ----- diff --git a/modules/customize-certificates-understanding-default-router.adoc b/modules/customize-certificates-understanding-default-router.adoc deleted file mode 100644 index 8a9ad75d2496..000000000000 --- a/modules/customize-certificates-understanding-default-router.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// security/certificates/replacing-default-ingress-certificate.adoc - -[id="understanding-default-ingress_{context}"] -= Understanding the default ingress certificate - -By default, {product-title} uses the Ingress Operator to -create an internal CA and issue a wildcard certificate that is valid for -applications under the `.apps` sub-domain. Both the web console and CLI -use this certificate as well. - -The internal infrastructure CA certificates are self-signed. -While this process might be perceived as bad practice by some security or -PKI teams, any risk here is minimal. The only clients that implicitly -trust these certificates are other components within the cluster. -Replacing the default wildcard certificate with one that is issued by a -public CA already included in the CA bundle as provided by the container userspace -allows external clients to connect securely to applications running under the `.apps` sub-domain. diff --git a/modules/customize-certificates-understanding-service-serving.adoc b/modules/customize-certificates-understanding-service-serving.adoc deleted file mode 100644 index 4b18de035d34..000000000000 --- a/modules/customize-certificates-understanding-service-serving.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificates/service-serving-certificate.adoc - -[id="understanding-service-serving_{context}"] -= Understanding service serving certificates - -Service serving certificates are intended to support complex -middleware applications that require encryption. These certificates are -issued as TLS web server certificates. - -The `service-ca` controller uses the `x509.SHA256WithRSA` signature -algorithm to generate service certificates. - -The generated certificate and key are in PEM format, stored in `tls.crt` -and `tls.key` respectively, within a created secret. The -certificate and key are automatically replaced when they get close to -expiration. - -The service CA certificate, which issues the service certificates, is valid for 26 months and is automatically rotated when there is less than six months validity left. After rotation, the previous service CA configuration is still trusted until its expiration. This allows a grace period for all affected services to refresh their key material before the expiration. If you do not upgrade your cluster during this grace period, which restarts services and refreshes their key material, you might need to manually restart services to avoid failures after the previous service CA expires. - -[NOTE] -==== -You can use the following command to manually restart all pods in the cluster. Be aware that running this command causes a service interruption, because it deletes every running pod in every namespace. These pods will automatically restart after they are deleted. - -[source,terminal] ----- -$ for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); \ - do oc delete pods --all -n $I; \ - sleep 1; \ - done ----- -==== diff --git a/modules/customize-installation-operator-overlays.adoc b/modules/customize-installation-operator-overlays.adoc new file mode 100644 index 000000000000..324a4261a1aa --- /dev/null +++ b/modules/customize-installation-operator-overlays.adoc @@ -0,0 +1,201 @@ +:_mod-docs-content-type: CONCEPT +[id="customize-installation-operator-overlays_{context}"] + += Customizing the installation using the Operator with overlays + +[role="_abstract"] +Learn how to tailor the installation of {product-title-short} using the Operator method with overlays. + +[id="overlays_{context}"] +== Overlays + +When `Central` or `SecuredCluster` custom resources don't expose certain low-level configuration options as parameters, +you can use the `.spec.overlays` field for adjustments. Use this field to amend the Kubernetes resources +generated by these custom resources. + +The `.spec.overlays` field comprises a sequence of patches, applied in their listed order. These patches are processed +by the Operator on the Kubernetes resources before deployment to the cluster. + +[WARNING] +==== +The `.spec.overlays` field in both `Central` and `SecuredCluster` allows users to modify +low-level Kubernetes resources in arbitrary ways. Use this feature only when the desired customization +is not available through the `SecuredCluster` or `Central` custom resources. + +Support for the `.spec.overlays` feature is limited primarily because it grants the ability to +make intricate and highly specific modifications to Kubernetes resources, which can vary significantly +from one implementation to another. This level of customization introduces a complexity that goes beyond +standard usage scenarios, making it challenging to provide broad support. Each modification can +be unique, potentially interacting with the Kubernetes system in unpredictable ways across +different versions and configurations of the product. This variability means that troubleshooting and +guaranteeing the stability of these customizations require a level of expertise and understanding specific +to each individual's setup. Consequently, while this feature empowers tailoring Kubernetes resources +to meet precise needs, greater responsibility must also assumed to ensure the compatibility and stability +of configurations, especially during upgrades or changes to the underlying product. + +==== + +The following example shows the structure of an overlay: +[source,yaml] +---- +overlays: +- apiVersion: v1 # <1> + kind: ExampleKind # <2> + name: my-resource # <3> + patches: + - path: .some.field # <4> + value: | # <5> + key1: data2 + key2: data2 +---- + +<1> Targeted Kubernetes resource ApiVersion, for example `apps/v1`, `v1`, `networking.k8s.io/v1` +<2> Resource type (e.g., Deployment, ConfigMap, NetworkPolicy) +<3> Name of the resource, for example `my-resource` +<4> JSONPath expression to the field, for example `spec.template.spec.containers[name:central].env[-1]` +<5> YAML string for the new field value. If you do not want to use YAML parsing, you can use the `verbatim` key as shown in the following ConfigMap example. + +[id="adding-an-overlay_{context}"] +=== Adding an overlay + +For customizations, you can add overlays to `Central` or `SecuredCluster` custom resources. Use the OpenShift CLI (`oc`) +or the OpenShift Container Platform web console for modifications. + +If overlays do not take effect as expected, check the {product-title-short} Operator logs for any syntax errors or +issues logged. + +[id="examples_{context}"] +== Overlay examples + +[id="adding-eks-role-arn-annotation_{context}"] +=== Specifying an EKS pod role ARN for the Central ServiceAccount + +Add an Amazon Elastic Kubernetes Service (EKS) pod role Amazon Resource Name (ARN) annotation to the `central` +ServiceAccount as shown in the following example: + +[source,yaml] +---- +apiVersion: platform.stackrox.io +kind: Central +metadata: + name: central +spec: + # ... + overlays: + - apiVersion: v1 + kind: ServiceAccount + name: central + patches: + - path: metadata.annotations.eks\.amazonaws\.com/role-arn + value: "\"arn:aws:iam:1234:role\"" +---- + +[id="adding-an-environment-variable-to-a-deployment_{context}"] +=== Injecting an environment variable into the Central deployment + +Inject an environment variable into the `central` deployment as shown in the following example: + +[source,yaml] +---- +apiVersion: platform.stackrox.io +kind: Central +metadata: + name: central +spec: + # ... + overlays: + - apiVersion: apps/v1 + kind: Deployment + name: central + patches: + - path: spec.template.spec.containers[name:central].env[-1] + value: | + name: MY_ENV_VAR + value: value +---- + +[id="adding-an-ingress-to-a-network-policy_{context}"] +=== Extending network policy with an ingress rule + +Add an ingress rule to the `allow-ext-to-central` network policy for port 999 traffic as shown in the following example: + +[source,yaml] +---- +apiVersion: platform.stackrox.io +kind: Central +metadata: + name: central +spec: + # ... + overlays: + - apiVersion: networking.k8s.io/v1 + kind: NetworkPolicy + name: allow-ext-to-central + patches: + - path: spec.ingress[-1] + value: | + ports: + - port: 999 + protocol: TCP +---- + +[id="changing-configmap-data_{context}"] +=== Modifying ConfigMap data + +Modify the `central-endpoints` ConfigMap data as shown in the following example: + +[source,yaml] +---- +apiVersion: platform.stackrox.io +kind: Central +metadata: + name: central +spec: + # ... + overlays: + - apiVersion: v1 + kind: ConfigMap + name: central-endpoints + patches: + - path: data.endpoints\.yaml + verbatim: | + disableDefault: false + # another line +---- + +This example shows how to override only a single item (file) under `data`. + +Follow this example by taking these steps: + +* Use the `verbatim` key, rather than `value`. +This helps pass through characters such as newlines or quotes so that they are unaffected. +* You must escape the dot in the filename in the `path` key as shown, or + you can write the path as `data["endpoints.yaml"]`. + +[id="adding-a-container-to-a-deployment_{context}"] +=== Adding a container to the `Central` deployment + +Add a new container to the `central` deployment as shown in the following example:. + +[source,yaml] +---- +apiVersion: platform.stackrox.io +kind: Central +metadata: + name: central +spec: + # ... + overlays: + - apiVersion: apps/v1 + kind: Deployment + name: central + patches: + - path: spec.template.spec.containers[-1] + value: | + name: nginx + image: nginx + ports: + - containerPort: 8000 + name: http + protocol: TCP +---- diff --git a/modules/customizing-and-automating-your-compliance-scans.adoc b/modules/customizing-and-automating-your-compliance-scans.adoc new file mode 100644 index 000000000000..127de9f7d23c --- /dev/null +++ b/modules/customizing-and-automating-your-compliance-scans.adoc @@ -0,0 +1,168 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="customizing-and-automating-your-compliance-scans_{context}"] += Customizing and automating your compliance scans + +By creating a compliance scan schedule, you can customize and automate your compliance scans to align with your operational requirements. + +[NOTE] +==== +You can only have one schedule that scans the same profile on the same cluster. This means that you cannot create multiple scan schedules for the same profile on a single cluster. +==== + +.Prerequisites + +* You have installed the Compliance Operator version 1.6.0 or later. ++ +For more information about how to install the Compliance Operator, see "Using the Compliance Operator with {product-title}". ++ +[NOTE] +==== +** Currently, the compliance feature and the Compliance Operator evaluate only infrastructure and platform compliance. + +** To use the compliance feature, you must run the Compliance Operator on a {osp} cluster. +==== + +.Procedure + +. In the {product-title-short} portal, click *Compliance -> OpenShift Schedules*. +. Click *Create scan schedule*. +. In the *Create scan schedule* page, provide the following information: + +** *Name*: Enter a name to identify different compliance scans. + +** *Description*: Specify the reason for each compliance scan. + +** *Schedule*: Adjust the scan schedule to fit your required schedule: + +*** *Frequency*: From the drop-down list, select how often you want to run the scan. If you do not select a frequency, `Daily` is selected automatically. ++ +The following values are associated with how often you want to perform the scan: + +**** `Daily` +**** `Weekly` +**** `Monthly` + +*** *On day(s)*: From the list, select one or more days of the week on which you want to perform the scan. ++ +The following values are associated with the days of the week on which you want to perform the scan: + +**** `Monday` +**** `Tuesday` +**** `Wednesday` +**** `Thursday` +**** `Friday` +**** `Saturday` +**** `Sunday` +**** `The first of the month` +**** `The middle of the month` ++ +[NOTE] +==== +These values are only applicable if you specify the frequency of scan as `Weekly` or `Monthly`. +==== + +*** *Time*: Start to type the time in `hh:mm` at which you want to run the scan. From the list that is displayed, select a time. + +. Click *Next*. +. Select one or more healthy clusters that you want to include in the scan. +. Click *Next*. +. Select one or more profiles that you want to include in the scan. +. Click *Next*. +. Optional: To configure email delivery destinations for manually triggered reports, perform the following steps: ++ +[NOTE] +==== +You can add one or more delivery destinations. +==== + +.. Expand *Add delivery destination*. +.. In the *Delivery destination* page, provide the following information: +*** *Email notifier*: Select an email notifier from the drop-down list. ++ +Optional: To configure the setting for a new email notifier integration, perform the following steps: + +... From *Select a notifier* drop-down list, click *Create email notifier*. + +... In the *Create email notifier* page, provide the following information: +**** *Integration name*: Enter a unique name for the email notifier. This name helps you identify and manage this specific email notifier configuration. +**** *Email server*: Specify the address of the SMTP server that you want to use to send the emails. +**** *Username*: Enter the username that is required for authentication with the SMTP server. This is often the email address used for sending the emails. +**** *Password*: Enter the password associated with the SMTP username. This password is used for authentication with the SMTP server. +**** *From*: This address usually represents the sender of the emails and is visible to the recipients. This is optional. +**** *Sender*: Enter the name of the sender, which is displayed together with the _From_ email address. This name helps recipients identify who sent the email. +**** *Default recipient*: Enter the default email address that should receive the notifications if no specific recipient is specified. This ensures that there is always a recipient for the emails. +**** *Annotation key for recipient*: Specify the annotation key to define a recipient that you want to notify about the policy violations related to a specific deployment or namespace. This is optional. +**** Optional: Select the *Enable unauthenticated SMTP* checkbox, if your SMTP server does not require authentication. This is not recommended due to security reasons. +**** Optional: Select the *Disable TLS certificate validation (insecure)* checkbox, if you want to disable TLS certificate validation. This is not recommended due to security reasons. +**** Optional: In the *Use STARTTLS (requires TLS to be disabled)* field, select the type of STARTTLS for securing the connection to the SMTP server from the drop-down list. ++ +[IMPORTANT] +==== +To use this option, you must disable TLS certificate validation. +==== ++ +The following values are associated with the type of STARTTLS for securing the connection to the SMTP server: + +***** `Disabled` ++ +Data is not encrypted. +***** `Plain` ++ +Encodes username and password in base64. +***** `Login` ++ +Sends username and password as separate base64-encoded strings for added security. +... Click *Save integration*. + +*** *Distribution list*: Enter one or more comma-separated email addresses of the recipients who should receive the report. + +*** *Email template*: The default template is automatically applied. ++ +Optional: To customize the email subject and body as needed, perform the following steps: + +.... Click the pencil icon. +.... In the *Edit email template* page, provide the following information: +***** *Email subject*: Enter the desired subject line for the email. This subject is displayed in the recipient's inbox and should clearly indicate the purpose of the email. +***** *Email body*: Compose the text of the email. This is the main content of the email and can include text, placeholders for dynamic content and any formatting necessary to get your message across effectively. +.... Click *Apply*. + +. Click *Next*. +. Review your scan configuration, and then click *Save*. + +.Verification + +. In the {product-title-short} portal, click *Compliance -> OpenShift Schedules*. +. Select the compliance scan that you have created. +. In the *Clusters* section, verify that the operator status is healthy. +. Optional: To edit the scan schedule, perform the following steps: +.. From the *Actions* drop-down list, which is in the upper right of the page, select *Edit scan schedule*. +.. Make your changes. +.. Click *Save*. +. Optional: To manually send a scan report: ++ +[NOTE] +==== +* You can only send a scan report manually if you have configured an email delivery destination. +* Compliance reporting is only available for clusters running Compliance Operator version 1.6.0 or later. +==== +** From the *Actions* drop-down list, which is in the upper right of the page, select *Send report*. ++ +You receive a confirmation that you have requested to send a report. +. Optional: To download a scan report, perform the following steps: ++ +[NOTE] +==== +Compliance reporting is only available for clusters running Compliance Operator version 1.6.0 or later. +==== +.. From the *Actions* drop-down list, which is in the upper right of the page, select *Generate download*. ++ +You receive a confirmation that the report generation has started. +.. Click the *All report jobs* tab. +.. Optional: Set *View only my jobs* to on. +.. Locate the report job that you created. +.. Wait until the download is complete, and then click *Ready for download*. +.. Optional: To delete the report job, click the overflow menu {kebab} and then select *Delete download*. \ No newline at end of file diff --git a/modules/customizing-cli-downloads.adoc b/modules/customizing-cli-downloads.adoc deleted file mode 100644 index c03015bb6880..000000000000 --- a/modules/customizing-cli-downloads.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/customizing-the-web-console.adoc - -[id="creating-custom-CLI-downloads_{context}"] -= Customizing CLI downloads - -You can configure links for downloading the CLI with custom link text and URLs, -which can point directly to file packages or to an external page that provides -the packages. - -.Prerequisites - -* You must have administrator privileges. - -.Procedure - -. Navigate to *Administration* -> *Custom Resource Definitions*. - -. Select *ConsoleCLIDownload* from the list of Custom Resource Definitions (CRDs). - -. Click the *YAML* tab, and then make your edits: -+ -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleCLIDownload -metadata: - name: example-cli-download-links-for-foo -spec: - description: | - This is an example of download links for foo - displayName: example-foo - links: - - href: 'https://www.example.com/public/foo.tar' - text: foo for linux - - href: 'https://www.example.com/public/foo.mac.zip' - text: foo for mac - - href: 'https://www.example.com/public/foo.win.zip' - text: foo for windows ----- - -. Click the *Save* button. diff --git a/modules/customizing-project-request-message.adoc b/modules/customizing-project-request-message.adoc deleted file mode 100644 index 681d7dbf1c64..000000000000 --- a/modules/customizing-project-request-message.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/projects/configuring-project-creation.adoc - -[id="customizing-project-request-message_{context}"] -= Customizing the project request message - -When a developer or a service account that is unable to self-provision projects -makes a project creation request using the web console or CLI, the following -error message is returned by default: - -[source,terminal] ----- -You may not request a new project via this API. ----- - -Cluster administrators can customize this message. Consider updating it to -provide further instructions on how to request a new project specific to your -organization. For example: - -* To request a project, contact your system administrator at -[x-]`projectname@example.com`. -* To request a new project, fill out the project request form located at -[x-]`https://internal.example.com/openshift-project-request`. - -To customize the project request message: - -.Procedure - -. Edit the project configuration resource using the web console or CLI. - -** Using the web console: -... Navigate to the *Administration* -> *Cluster Settings* page. -... Click *Global Configuration* to view all configuration resources. -... Find the entry for *Project* and click *Edit YAML*. - -** Using the CLI: -... Log in as a user with `cluster-admin` privileges. -... Edit the `project.config.openshift.io/cluster` resource: -+ -[source,terminal] ----- -$ oc edit project.config.openshift.io/cluster ----- - -. Update the `spec` section to include the `projectRequestMessage` parameter and -set the value to your custom message: -+ -.Project configuration resource with custom project request message -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Project -metadata: - ... -spec: - projectRequestMessage: <message_string> ----- -+ -For example: - -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Project -metadata: - ... -spec: - projectRequestMessage: To request a project, contact your system administrator at projectname@example.com. ----- - -. After you save your changes, attempt to create a new project as a developer or -service account that is unable to self-provision projects to verify that your -changes were successfully applied. diff --git a/modules/customizing-the-login-page.adoc b/modules/customizing-the-login-page.adoc deleted file mode 100644 index 4384fa5729c8..000000000000 --- a/modules/customizing-the-login-page.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/customizing-the-web-console.adoc - -[id="customizing-the-login-page_{context}"] -= Customizing the login page - -Create Terms of Service information with custom login pages. Custom login pages -can also be helpful if you use a third-party login provider, such as GitHub or -Google, to show users a branded page that they trust and expect before being -redirected to the authentication provider. You can also render custom error -pages during the authentication process. - -.Prerequisites - -* You must have administrator privileges. - -.Procedure - -. Run the following commands to create templates you can modify: -+ -[source,terminal] ----- -$ oc adm create-login-template > login.html ----- -+ -[source,terminal] ----- -$ oc adm create-provider-selection-template > providers.html ----- -+ -[source,terminal] ----- -$ oc adm create-error-template > errors.html ----- - -. Create the secrets: -+ -[source,terminal] ----- -$ oc create secret generic login-template --from-file=login.html -n openshift-config ----- -+ -[source,terminal] ----- -$ oc create secret generic providers-template --from-file=providers.html -n openshift-config ----- -+ -[source,terminal] ----- -$ oc create secret generic error-template --from-file=errors.html -n openshift-config ----- - -. Run: -+ -[source,terminal] ----- -$ oc edit oauths cluster ----- - -. Update the specification: -+ -[source,yaml] ----- -spec: - templates: - error: - name: error-template - login: - name: login-template - providerSelection: - name: providers-template ----- -+ -Run `oc explain oauths.spec.templates` to understand the options. diff --git a/modules/customizing-the-web-console-URL.adoc b/modules/customizing-the-web-console-URL.adoc deleted file mode 100644 index e1994c4d4602..000000000000 --- a/modules/customizing-the-web-console-URL.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/customizing-the-web-console.adoc - -[id="customizing-the-web-console-url_{context}"] -= Customizing the web console URL - -You can update the web console URL, `consoleURL`, to a custom value. - -.Procedure - -. Modify the cluster instance created by default during installation in the `consoles.operator.openshift.io` custom resource: -+ -[source,terminal] ----- -$ oc patch consoles.operator.openshift.io cluster --patch '{"spec":{"route":{"hostname":"console.example.com"}}}' --type=merge ----- - -. If you specify a custom certificate, you must create a secret in the `openshift-config` namespace that has the key and certificate. For example: -+ -[source,terminal] ----- -$ oc create secret tls console-tls --key=key.pem --cert=cert.pem -n openshift-config ----- -+ -Then, add the following stanza to the configuration resource: -+ -[source,yaml] ----- -spec: - route: - hostname: console.example.com - secret: - name: console-tls ----- diff --git a/modules/cves-tab.adoc b/modules/cves-tab.adoc new file mode 100644 index 000000000000..02b29731e570 --- /dev/null +++ b/modules/cves-tab.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: CONCEPT +[id="cves-tab_{context}"] += CVEs tab + +The CVEs view organizes information into the following groups: + +* *CVE*: Displays a unique identifier for Common Vulnerabilities and Exposures (CVE), each representing a specific vulnerability, to track and analyze it in detail. +* *Images by severity*: Groups images based on the severity level of the associated vulnerabilities. +* *Top CVSS*: Displays the highest CVSS score for each CVE across images to highlight the vulnerabilities with the most severe impact. +* *Top NVD CVSS*: Shows the highest severity scores from the National Vulnerability Database (NVD) to enable standardized impact assessments. This information is only visible when using Scanner V4. +* *EPSS probability*: The likelihood that the vulnerability could be exploited according to the link:https://www.first.org/epss/[Exploit Prediction Scoring System (EPSS)]. This EPSS data provides a percentage estimate of the probability that exploitation of this vulnerability will be observed in the next 30 days. The EPSS collects data of observed exploitation activity from partners, and exploitation activity does not mean that an attempted exploitation was successful. The EPSS score should be used as a single data point _along with other information_, such as the age of the CVE, to help you prioritize the vulnerabilities to address. For more information, see link:https://access.redhat.com/articles/7106599[{product-title-short} and EPSS]. This information is visible only when using Scanner V4. +* *Affected images*: Displays the number of container images affected by specific CVEs to assess the scope of vulnerabilities. +* *First discovered*: Shows the date each vulnerability was first discovered in the environment to measure the duration of its exposure. +* *Published*: Indicates when the CVE was publicly disclosed. + +To review and triage the details associated with a CVE, click on the CVE. + +A window opens with information about the vulnerabilities associated with the CVE. \ No newline at end of file diff --git a/modules/data-protection.adoc b/modules/data-protection.adoc new file mode 100644 index 000000000000..26bf00ec6d5b --- /dev/null +++ b/modules/data-protection.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_content-type: CONCEPT +[id="data-protection_{context}"] += Data protection + +[role="_abstract"] +Red{nbsp}Hat provides data protection by using various methods, such as logging, access control, and encryption. + +[id="data-storage-media-protection_{context}"] +== Data storage media protection + +To protect our data and client data from risk of theft or destruction, Red{nbsp}Hat employs the following methods: + +* access logging +* automated account termination procedures +* application of the principle of least privilege + +Data is encrypted in transit and at rest using strong data encryption following NIST guidelines and Federal Information Processing Standards (FIPS) where possible and practical. This includes backup systems. + +{product-title-managed-short} encrypts data at rest within the Amazon Relational Database Service (RDS) database by using AWS-managed Key Management Services (KMS) keys. All data between the application and the database, together with data exchange between the systems, are encrypted in transit. + +[id="data-retention-destruction_{context}"] +=== Data retention and destruction + +Records, including those containing personal data, are retained as required by law. Records not required by law or a reasonable business need are securely removed. Secure data destruction requirements are included in operating procedures, using military grade tools. In addition, staff have access to secure document destruction facilities. + +[id="encryption_{context}"] +=== Encryption + +Red{nbsp}Hat uses link:https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk[AWS managed keys] which are rotated by AWS each year. For information on the use of keys, see link:https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.Keys.html[AWS KMS key management]. For more information about RDS, see link:https://aws.amazon.com/rds/features/security[Amazon RDS Security]. + +[id="multi-tenancy_{context}"] +=== Multi-tenancy + +{product-title-managed-short} isolates tenants by namespace on {ocp}. SELinux provides additional isolation. Each customer has a unique RDS instance. + +[id="data-ownership_{context}"] +=== Data ownership + +Customer data is stored in an encrypted RDS database not available on the public internet. Only Site Reliability Engineers (SREs) have access to it, and the access is audited. + +Every {product-title-managed-short} system comes integrated with Red{nbsp}Hat external SSO. Authorization rules are set up to provide administrator access to the user created the Cloud Service and to users who are marked as organization administrators in Red{nbsp}Hat SSO. The admin login is disabled for {product-title-managed-short} by default and can only be temporarily enabled by SREs. + +Red{nbsp}Hat collects information about the number of secured clusters connected to {product-title-managed-short} and the usage of features. Metadata generated by the application and stored in the RDS database is owned by the customer. Red{nbsp}Hat only accesses data for troubleshooting purposes and with customer permission. Red{nbsp}Hat access requires audited privilege escalation. + +Upon contract termination, Red{nbsp}Hat can perform a secure disk wipe upon request. However, we are unable to physically destroy media (cloud providers such as AWS do not provide this option). + +To secure data in case of a breach, you can perform the following actions: + +* Disconnect all secured clusters from {product-title-managed-short} immediately using the cluster management page. +* Immediately disable access to the {product-title-managed-short} by using the Access Control page. +* Immediately delete your {product-title-short} instance, which also deletes the RDS instance. + +Any AWS RDS (data store) specific access modifications would be implemented by the {product-title-managed-short} SRE engineers. \ No newline at end of file diff --git a/modules/data-storage-management.adoc b/modules/data-storage-management.adoc deleted file mode 100644 index 5093c5df74ac..000000000000 --- a/modules/data-storage-management.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/optimizing-storage.adoc - -[id="data-storage-management_{context}"] -= Data storage management - -The following table summarizes the main directories that {product-title} components write data to. - -.Main directories for storing {product-title} data -[options="header,footer"] -|=== -|Directory|Notes|Sizing|Expected growth - -|*_/var/lib/etcd_* -|Used for etcd storage when storing the database. -|Less than 20 GB. - -Database can grow up to 8 GB. -|Will grow slowly with the environment. Only storing metadata. - -Additional 20-25 GB for every additional 8 GB of memory. - -|*_/var/lib/containers_* -|This is the mount point for the CRI-O runtime. Storage used for active container runtimes, including pods, and storage of local images. Not used for registry storage. -|50 GB for a node with 16 GB memory. Note that this sizing should not be used to determine minimum cluster requirements. - -Additional 20-25 GB for every additional 8 GB of memory. -|Growth is limited by capacity for running containers. - -|*_/var/lib/kubelet_* -|Ephemeral volume storage for pods. This includes anything external that is mounted into a container at runtime. Includes environment variables, kube secrets, and data volumes not backed by persistent volumes. -|Varies -|Minimal if pods requiring storage are using persistent volumes. If using ephemeral storage, this can grow quickly. - -|*_/var/log_* -|Log files for all components. -|10 to 30 GB. -|Log files can grow quickly; size can be managed by growing disks or by using log rotate. - -|=== diff --git a/modules/declarative-configuration-auth-resources.adoc b/modules/declarative-configuration-auth-resources.adoc new file mode 100644 index 000000000000..8dd2ddfc100d --- /dev/null +++ b/modules/declarative-configuration-auth-resources.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control-3630.adoc +:_mod-docs-content-type: CONCEPT +[id="declarative-configuration-auth-resources_{context}"] += Declarative configuration for authentication and authorization resources + +[role="_abstract"] +You can use declarative configuration for authentication and authorization resources such as authentication providers, roles, permission sets, and access scopes. For instructions on how to use declarative configuration, see "Using declarative configuration" in the "Additional resources" section. \ No newline at end of file diff --git a/modules/declarative-configuration-examples.adoc b/modules/declarative-configuration-examples.adoc new file mode 100644 index 000000000000..2703f98ba54f --- /dev/null +++ b/modules/declarative-configuration-examples.adoc @@ -0,0 +1,160 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control-3630.adoc + +:_mod-docs-content-type: CONCEPT +[id="declarative-configuration-examples_{context}"] += Declarative configuration examples + +[role="_abstract"] +You can create declarative configurations by using the following examples as a guide. Use the `roxctl declarative-config lint` command to verify that your configurations are valid. + +[id="declarative-config-example-auth-provider"] +== Declarative configuration authentication provider example + +.Declarative configuration authentication provider example + +[source,yaml] +---- +name: A sample auth provider +minimumRole: Analyst <1> +uiEndpoint: central.custom-domain.com:443 <2> +extraUIEndpoints: <3> + - central-alt.custom-domain.com:443 +groups: <4> + - key: email <5> + value: example@example.com + role: Admin <6> + - key: groups + value: reviewers + role: Analyst +requiredAttributes: <7> + - key: org_id + value: "12345" +claimMappings: <8> + - path: org_id + value: my_org_id +oidc: <9> + issuer: sample.issuer.com <10> + mode: auto <11> + clientID: CLIENT_ID + clientSecret: CLIENT_SECRET +clientSecret: CLIENT_SECRET +iap: <12> + audience: audience +saml: <13> + spIssuer: sample.issuer.com + metadataURL: sample.provider.com/metadata +saml: <14> + spIssuer: sample.issuer.com + cert: | <15> + ssoURL: saml.provider.com + idpIssuer: idp.issuer.com +userpki: + certificateAuthorities: | <16> + certificate <17> +openshift: <18> + enable: true +---- +<1> Identifies the minimum role that will be assigned by default to any user logging in. If left blank, the value is `None`. +<2> Use the user interface endpoint of your Central instance. +<3> If your Central instance is exposed to different endpoints, specify them here. +<4> These fields map users to specific roles, based on their attributes. +<5> The key can be any claim returned from the authentication provider. +<6> Identifies the role that the users are given. You can use a default role or a declaratively-created role. +<7> Optional: Use these fields if attributes returned from the authentication provider are required; for example, if the audience is limited to a specific organization or group. +<8> Optional: Use these fields if claims returned from the identity provider should be mapped to custom claims. +<9> This section is required only for OpenID Connect (OIDC) authentication providers. +<10> Identifies the expected issuer for the token. +<11> Identifies the OIDC callback mode. Possible values are `auto`, `post`, `query`, and `fragment`. The preferred value is `auto`. +<12> This section is required only for Google Identity-Aware Proxy (IAP) authentication providers. +<13> This section is required only for Security Assertion Markup Language (SAML) 2.0 dynamic configuration authentication providers. +<14> This section is required only for SAML 2.0 static configuration authentication providers. +<15> Include the certificate in Privacy Enhanced Mail (PEM) format. +<16> This section is required only for authentication with user certificates. +<17> Include the certificate in PEM format. +<18> This section is required only for OpenShift Auth authentication providers. + +[id="declarative-config-example-short-lived-token"] +== Declarative configuration short-lived token example + +.Declarative configuration short-lived token example +[source,yaml] +---- +issuer: https://token.actions.githubusercontent.com <1> +type: GITHUB_ACTION <2> +tokenExpirationDuration: 20m <3> +mappings: <4> + - key: sub <5> + value: repos:stackrox:stackrox + role: Analyst <6> +---- +<1> Identifies the expected issuer for the token to exchange against a short-lived one. +<2> Specify the configuration type. See "Configuring short-lived access" and "Integrating {product-title-short} using short-lived access tokens" for more information. +<3> Specify the token lifetime in the *XhYmZs* format. The lifetime cannot be longer than 24 hours. +<4> These fields map users to specific roles, based on their attributes. +<5> The key can be any claim returned from the issuer. +<6> Identifies the role that the users are given. You can use a default role or a declaratively-created one. + + +[id="declarative-config-example-permission-set"] +== Declarative configuration permission set example + +.Declarative configuration permission set example + +[source,yaml] +---- +name: A sample permission set +description: A sample permission set created declaratively +resources: +- resource: Integration <1> + access: READ_ACCESS <2> +- resource: Administration + access: READ_WRITE_ACCESS +---- +<1> For a full list of supported resources, go to *Access Control* -> *Permission Sets*. +<2> Access can be either `READ_ACCESS` or `READ_WRITE_ACCESS`. + +[id="declarative-config-example-access-scope"] +== Declarative configuration access scope example + +.Declarative configuration access scope example + +[source,yaml] +---- +name: A sample access scope +description: A sample access scope created declaratively +rules: + included: + - cluster: secured-cluster-A <1> + namespaces: + - namespaceA + - cluster: secured-cluster-B <2> + clusterLabelSelectors: + - requirements: + - requirements: + - key: kubernetes.io/metadata.name + operator: IN <3> + values: + - production + - staging + - environment +---- +<1> Identifies a cluster where only specific namespaces are included within the access scope. +<2> Identifies a cluster where all namespaces are included within the access scope. +<3> Identifies the Operator to use for the label selection. Valid values are `IN`, `NOT_IN`, `EXISTS`, and `NOT_EXISTS`. + +[id="declarative-config-example-role"] +== Declarative configuration role example + +.Declarative configuration role example + +[source,yaml] +---- +name: A sample role +description: A sample role created declaratively +permissionSet: A sample permission set <1> +accessScope: Unrestricted <2> +---- +<1> Name of the permission set; can be either one of the system permission sets or a declaratively-created permission set. +<2> Name of the access scope; can be either one of the system access scopes or a declaratively-created access scope. diff --git a/modules/declarative-configuration-resource-create.adoc b/modules/declarative-configuration-resource-create.adoc new file mode 100644 index 000000000000..57235839bc8e --- /dev/null +++ b/modules/declarative-configuration-resource-create.adoc @@ -0,0 +1,71 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control-3630.adoc +:_mod-docs-content-type: PROCEDURE +[id="declarative-configuration-resource-create_{context}"] += Creating declarative configurations + +Use `roxctl` to create the YAML files that store the configurations, create a config map from the files, and apply the config map. + +.Prerequisites +* You have added the mount for the config map or secret during the installation of Central. In this example, the config map is called "declarative-configs". See the installation documentation listed in the "Additional resources" section for more information. + +.Procedure + +. Create the permission set by entering the following command. This example creates a permission set named "restricted" and is saved as the `permission-set.yaml` file. It sets read and write access for the `Administration` resource and read access to the Access resource. ++ +[source,terminal,subs=attributes+] +---- +$ roxctl declarative-config create permission-set \ +--name="restricted" \ +--description="Restriction permission set that only allows \ +access to Administration and Access resources" \ +--resource-with-access=Administration=READ_WRITE_ACCESS \ +--resource-with-access=Access=READ_ACCESS > permission-set.yaml +---- +. Create the role that allows access to the `Administration` and `Access` resources by entering the following command. This example creates a role named "restricted" and is saved as the `role.yaml` file. ++ +[source,terminal,subs=attributes+] +---- +$ roxctl declarative-config create role \ +--name="restricted" \ +--description="Restricted role that only allows access to Administration and Access" \ +--permission-set="restricted" \ +--access-scope="Unrestricted" > role.yaml +---- +. Create a config map from the two YAML files that were created in the earlier steps by entering the following command. This example creates the `declarative-configurations` config map. ++ +[source,terminal,subs=attributes+] +---- +$ kubectl create configmap declarative-configurations \ <1> +--from-file permission-set.yaml --from-file role.yaml \ +-o yaml --namespace=stackrox > declarative-configs.yaml +---- +<1> For {ocp}, use `oc create`. +. Apply the config map by entering the following command: ++ +[source,terminal,subs=attributes+] +---- +$ kubectl apply -f declarative-configs.yaml <1> +---- +<1> For {ocp}, use `oc apply`. ++ +After you apply the config map, configuration information extracted from Central creates the resources. ++ +[NOTE] +==== +Although the watch interval is 5 seconds, as described in the following paragraph, there can be a delay in propagating changes from the config map to the Central mount. +==== +You can configure the following intervals to specify how declarative configurations interact with Central: + +* Configuration watch interval: The interval for Central to check for changes is every 5 seconds. You can configure this interval by using the `ROX_DECLARATIVE_CONFIG_WATCH_INTERVAL` environment variable. +* Reconciliation interval: By default, declarative configuration reconciliation with Central occurs every 20 seconds. You can configure this interval by using the `ROX_DECLARATIVE_CONFIG_RECONCILE_INTERVAL` environment variable. + +After creating authentication and authorization resources by using declarative configuration, you can view them in the *Access Control* page in the {product-title-short} web portal. The *Origin* field indicates `Declarative` if the resource was created by using declarative configuration. + +[NOTE] +==== +You cannot edit resources created from declarative configurations in the {product-title-short} web portal. You must edit the configuration files directly to make changes to these resources. +==== + +You can view the status of declarative configurations by navigating to *Platform Configuration* -> *System Health* and scrolling to the *Declarative configuration* section. \ No newline at end of file diff --git a/modules/declarative-configuration-troubleshooting.adoc b/modules/declarative-configuration-troubleshooting.adoc new file mode 100644 index 000000000000..48363e611279 --- /dev/null +++ b/modules/declarative-configuration-troubleshooting.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control-3630.adoc +:_mod-docs-content-type: CONCEPT +[id="declarative-configuration-troubleshooting_{context}"] += Troubleshooting declarative configuration + +[role="_abstract"] +You can use the error messages displayed in the *Declarative configuration* section of the *Platform Configuration* -> *System Health* page to help in troubleshooting. The `roxctl declarative-config` command also includes a `lint` option to validate the configuration file and help you detect errors. + +The error messages displayed in the *Declarative configuration* section of the *Platform Configuration* -> *System Health* page provide information about issues with declarative configurations. Problems with declarative configurations can be caused by the following conditions: + +* The format of the configuration file is not in valid YAML. +* The configuration file contains invalid values, such as invalid access within a permission set. +* Invalid storage constraints exist, such as resource names are not unique or the configuration contains invalid references to a resource. + +To validate configuration files, check for errors in configuration files, and make sure that there are no invalid storage constraints when creating and updating configuration files, use the `roxctl declarative-config lint` command. + +To troubleshoot a storage constraint during deletion, check if the resource has been marked as `Declarative Orphaned`. This indicates that the declarative configuration referenced by a resource was deleted (for example, if the declarative configuration for a permission set that was referenced by a role was deleted). To correct this error, edit the resource to point to a new permission set, or restore the declarative configuration that was deleted. \ No newline at end of file diff --git a/modules/declarative-configuration-values.adoc b/modules/declarative-configuration-values.adoc new file mode 100644 index 000000000000..248bd3fa7274 --- /dev/null +++ b/modules/declarative-configuration-values.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +:_mod-docs-content-type: PROCEDURE +[id="declarative-configuration-values_{context}"] += Declarative configuration values + +[role=_abstract] +To use declarative configuration, you must create a YAML file (in this example, named "declarative-config-values.yaml") that adds the declarative configuration mounts to Central. This file is used in a Helm installation. + +.Procedure +. Create the YAML file (in this example, named `declarative-config-values.yaml`) using the following example as a guideline: ++ +[source,yaml] +---- +central: + declarativeConfiguration: + mounts: + configMaps: + - declarative-configs + secrets: + - sensitive-declarative-configs +---- +. Install the Central services Helm chart as documented in the "Installing the central-services Helm chart", referencing the `declarative-config-values.yaml` file. \ No newline at end of file diff --git a/modules/dedicated-admin-granting-permissions.adoc b/modules/dedicated-admin-granting-permissions.adoc deleted file mode 100644 index 255f3306dac6..000000000000 --- a/modules/dedicated-admin-granting-permissions.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// administering_a_cluster/dedicated-admin-role.adoc - -[id="dedicated-admin-granting-permissions_{context}"] -= Granting permissions to users or groups - -To grant permissions to other users or groups, you can add, or _bind_, a role to -them using the following commands: - ----- -$ oc adm policy add-role-to-user <role> <user_name> -$ oc adm policy add-role-to-group <role> <group_name> ----- diff --git a/modules/dedicated-admin-role-overview.adoc b/modules/dedicated-admin-role-overview.adoc deleted file mode 100644 index 8459c4eb17c7..000000000000 --- a/modules/dedicated-admin-role-overview.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="dedicated-admin-role-overview_{context}"] -ifdef::openshift-dedicated[] -= About the dedicated administrator role - -The accounts for dedicated administrators of an {product-title} cluster, -have increased -permissions and access to all user-created projects. - -//// -[NOTE] -==== -Some configuration changes or procedures discussed in this guide can be -performed by only the {product-title} Operations Team. They are included in this -guide for informational purposes to help you as an {product-title} cluster -administrator better understand what configuration options are possible. If you -want to request a change to your cluster that you cannot perform using the -administrator CLI, open a support case on the -https://access.redhat.com/support/[Red Hat Customer Portal]. -==== -//// - -When your account has the `dedicated-admins-cluster` authorization role -bound to it, you -are automatically bound to the `dedicated-admins-project` role for any new projects -that users in the cluster create. - -You can perform actions that are associated with a set of verbs, such as `create`, -to operate on a set of resource names, such as `templates`. To view the details -of these roles and their sets of -verbs and resources, run the following commands: - ----- -$ oc describe clusterrole/dedicated-admins-cluster -$ oc describe clusterrole/dedicated-admins-project ----- - -The verb names do not necessarily all map directly to `oc` commands but rather -equate more generally to the types of CLI operations you can perform. For -example, having the `list` verb means that you can display a list of all objects -of a given resource name by running the `oc get` command, but the `get` verb -means that you can display the details of a specific object if you know its name -by runnign the `oc describe` command. - -{product-title} administrators can grant users a `dedicated-reader` role, which -provides view-only access at the cluster level and view access for all -user projects. - -endif::[] diff --git a/modules/dedicated-aws-dc-existing.adoc b/modules/dedicated-aws-dc-existing.adoc deleted file mode 100644 index 585cf14e6bc9..000000000000 --- a/modules/dedicated-aws-dc-existing.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-dc.adoc - -[id="dedicated-aws-dc-existing"] -= Connecting to an existing Direct Connect Gateway - -.Prerequisites - -* Confirm the CIDR range of the OSD VPC will not conflict with any other VGWs you have associated. -* Gather the following information: -** The Direct Connect Gateway ID. -** The AWS Account ID associated with the virtual interface. -** The BGP ASN assigned for the DXGateway. Optional: the Amazon default ASN may also be used. - -.Procedure - -. Log in to the OSD AWS Account Dashboard and select the correct region. -. From the OSD AWS Account region, select *VPC* from the *Services* menu. -. From *VPN Connections*, select *Virtual Private Gateways*. -. Select *Create Virtual Private Gateway*. -. Give the Virtual Private Gateway a suitable name. -. Click *Custom ASN* and enter the *Amazon side ASN* value gathered previously or use the Amazon Provided ASN. -. Create the Virtual Private Gateway. -. In the *Navigation* pane of the OSD AWS Account Dashboard, choose *Virtual private gateways* and select the virtual private gateway. Choose *View details*. -. Choose *Direct Connect gateway associations* and click *Associate Direct Connect gateway*. -. Under *Association account type*, for Account owner, choose *Another account*. -. For *Direct Connect gateway owner*, enter the ID of the AWS account that owns the Direct Connect gateway. -. Under *Association settings*, for Direct Connect gateway ID, enter the ID of the Direct Connect gateway. -. Under *Association settings*, for Virtual interface owner, enter the ID of the AWS account that owns the virtual interface for the association. -. Optional: Add prefixes to Allowed prefixes, separating them using commas. -. Choose *Associate Direct Connect gateway*. -. After the Association Proposal has been sent, it will be waiting for your -acceptance. The final steps you must perform are available in the -link:https://docs.aws.amazon.com/directconnect/latest/UserGuide/multi-account-associate-vgw.html[AWS Documentation]. diff --git a/modules/dedicated-aws-dc-hvif.adoc b/modules/dedicated-aws-dc-hvif.adoc deleted file mode 100644 index 6613dbe4deb2..000000000000 --- a/modules/dedicated-aws-dc-hvif.adoc +++ /dev/null @@ -1,91 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-dc.adoc - -[id="dedicated-aws-dc-hvif"] -= Creating the hosted Virtual Interface - -.Prerequisites - -* Gather OSD AWS Account ID. - -[id="dedicated-aws-dc-hvif-type"] -== Determining the type of Direct Connect connection - -View the Direct Connect Virtual Interface details to determine the type of -connection. - -.Procedure - -. Log in to the OSD AWS Account Dashboard and select the correct region. -. Select *Direct Connect* from the *Services* menu. -. There will be one or more Virtual Interfaces waiting to be accepted, select one of them to view the *Summary*. -. View the Virtual Interface type: private or public. -. Record the *Amazon side ASN* value. - -If the Direct Connect Virtual Interface type is Private, a Virtual Private -Gateway is created. If the Direct Connect Virtual Interface is Public, a Direct -Connect Gateway is created. - -[id="dedicated-aws-dc-hvif-private"] -== Creating a Private Direct Connect - -A Private Direct Connect is created if the Direct Connect Virtual Interface type -is Private. - -.Procedure - -. Log in to the OSD AWS Account Dashboard and select the correct region. -. From the AWS region, select *VPC* from the *Services* menu. -. Select *Virtual Private Gateways* from *VPN Connections*. -. Click *Create Virtual Private Gateway*. -. Give the Virtual Private Gateway a suitable name. -. Select *Custom ASN* and enter the *Amazon side ASN* value gathered previously. -. Create the Virtual Private Gateway. -. Click the newly created Virtual Private Gateway and choose *Attach to VPC* from the *Actions* tab. -. Select the *OSD Cluster VPC* from the list, and attach the Virtual Private Gateway to the VPC. -. From the *Services* menu, click *Direct Connect*. Choose one of the Direct Connect Virtual Interfaces from the list. -. Acknowledge the *I understand that Direct Connect port charges apply once I click Accept Connection* message, then choose *Accept Connection*. -. Choose to *Accept* the Virtual Private Gateway Connection and select the Virtual Private Gateway that was created in the previous steps. -. Select *Accept* to accept the connection. -. Repeat the previous steps if there is more than one Virtual Interface. - -[id="dedicated-aws-dc-hvif-public"] -== Creating a Public Direct Connect - -A Public Direct Connect is created if the Direct Connect Virtual Interface type -is Public. - -.Procedure - -. Log in to the OSD AWS Account Dashboard and select the correct region. -. From the OSD AWS Account region, select *Direct Connect* from the *Services* menu. -. Select *Direct Connect Gateways* and *Create Direct Connect Gateway*. -. Give the Direct Connect Gateway a suitable name. -. In the *Amazon side ASN*, enter the Amazon side ASN value gathered previously. -. Create the Direct Connect Gateway. -. Select *Direct Connect* from the *Services* menu. -. Select one of the Direct Connect Virtual Interfaces from the list. -. Acknowledge the *I understand that Direct Connect port charges apply once I click Accept Connection* message, then choose *Accept Connection*. -. Choose to *Accept* the Direct Connect Gateway Connection and select the Direct Connect Gateway that was created in the previous steps. -. Click *Accept* to accept the connection. -. Repeat the previous steps if there is more than one Virtual Interface. - -[id="dedicated-aws-dc-hvif-verifying"] -== Verifying the Virtual Interfaces - -After the Direct Connect Virtual Interfaces have been accepted, wait a short -period and view the status of the Interfaces. - -.Procedure - -. Log in to the OSD AWS Account Dashboard and select the correct region. -. From the OSD AWS Account region, select *Direct Connect* from the *Services* menu. -. Select one of the Direct Connect Virtual Interfaces from the list. -. Check the Interface State has become *Available* -. Check the Interface BGP Status has become *Up*. -. Repeat this verification for any remaining Direct Connect Interfaces. - -After the Direct Connect Virtual Interfaces are available, you can log in to the -OSD AWS Account Dashboard and download the Direct Connect configuration file for -configuration on your side. diff --git a/modules/dedicated-aws-dc-methods.adoc b/modules/dedicated-aws-dc-methods.adoc deleted file mode 100644 index 83a4814340d3..000000000000 --- a/modules/dedicated-aws-dc-methods.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-dc.adoc - -[id="dedicated-aws-dc-methods"] -= AWS Direct Connect methods - -A Direct Connect connection requires a hosted Virtual Interface (VIF) connected -to a Direct Connect Gateway (DXGateway), which is in turn associated to a -Virtual Gateway (VGW) or a Transit Gateway to access a remote VPC in -the same or another account. - -If you do not have an existing DXGateway, the typical process involves creating -the hosted VIF, with the DXGateway and VGW being created in the OSD AWS Account. - -If you have an existing DXGateway connected to one or more existing VGWs, the -process involves the OSD AWS Account sending an Association Proposal -to the DXGateway owner. The DXGateway owner must ensure that the proposed CIDR -will not conflict with any other VGWs they have associated. - -See the following AWS documentation for more details: - -* link:https://docs.aws.amazon.com/directconnect/latest/UserGuide/WorkingWithVirtualInterfaces.html[Virtual Interfaces] -* link:https://docs.aws.amazon.com/directconnect/latest/UserGuide/direct-connect-gateways-intro.html[Direct Connect Gateways] -* link:https://docs.aws.amazon.com/directconnect/latest/UserGuide/multi-account-associate-vgw.html[Associating a VGW across accounts] - -[IMPORTANT] -==== -When connecting to an existing DXGateway, you are responsible for the -link:https://aws.amazon.com/directconnect/pricing/[costs]. -==== - -There are two configuration options available: - -[horizontal] -Method 1:: Create the hosted VIF and then the DXGateway and VGW. -Method 2:: Request a connection via an existing Direct Connect Gateway that you own. diff --git a/modules/dedicated-aws-vpc-accepting-peering.adoc b/modules/dedicated-aws-vpc-accepting-peering.adoc deleted file mode 100644 index ade593e17d15..000000000000 --- a/modules/dedicated-aws-vpc-accepting-peering.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-peering.adoc - -[id="dedicated-aws-vpc-accepting-peering"] -= Accepting the VPC peer request - -After you create the VPC peering connection, you must accept the request in the -Customer AWS Account. - -.Prerequisites - -* Initiate the VPC peer request. - -.Procedure - -. Log in to the AWS Web Console. -. Navigate to *VPC Service*. -. Go to *Peering Connections*. -. Click on *Pending peering connection*. -. Confirm the AWS Account and VPC ID that the request originated from. This should -be from the OSD AWS Account and {product-title} Cluster VPC. -. Click *Accept Request*. diff --git a/modules/dedicated-aws-vpc-configuring-routing-tables.adoc b/modules/dedicated-aws-vpc-configuring-routing-tables.adoc deleted file mode 100644 index d1b1a0c9ff83..000000000000 --- a/modules/dedicated-aws-vpc-configuring-routing-tables.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-peering.adoc - -[id="dedicated-aws-vpc-configuring-routing-tables"] -= Configuring the routing tables - -After you accept the VPC peering request, both VPCs must configure their routes -to communicate across the peering connection. - -.Prerequisites - -* Initiate and accept the VPC peer request. - -.Procedure - -. Log in to the AWS Web Console for the OSD AWS Account. -. Navigate to the *VPC Service*, then *Route Tables*. -. Select the Route Table for the {product-title} Cluster VPC. -+ -[NOTE] -==== -On some clusters, there may be more than one route table for a particular VPC. -Select the private one that has a number of explicitly associated subnets. -==== - -. Select the *Routes* tab, then *Edit*. -. Enter the Customer VPC CIDR block in the *Destination* text box. -. Enter the Peering Connection ID in the *Target* text box. -. Click *Save*. - -. You must complete the same process with the other VPC's CIDR block: -.. Log into the Customer AWS Web Console → *VPC Service* → *Route Tables*. -.. Select the Route Table for your VPC. -.. Select the *Routes* tab, then *Edit*. -.. Enter the {product-title} Cluster VPC CIDR block in the *Destination* text box. -.. Enter the Peering Connection ID in the *Target* text box. -.. Click *Save*. - -The VPC peering connection is now complete. Follow the verification procedure to -ensure connectivity across the peering connection is working. diff --git a/modules/dedicated-aws-vpc-initiating-peering.adoc b/modules/dedicated-aws-vpc-initiating-peering.adoc deleted file mode 100644 index bc4464b3ac09..000000000000 --- a/modules/dedicated-aws-vpc-initiating-peering.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-peering.adoc - -[id="dedicated-aws-vpc-initiating-peering"] -= Initiating the VPC peer request - -You can send a VPC peering connection request from the OSD AWS Account to the -Customer AWS Account. - -.Prerequisites - -* Gather the following information about the Customer VPC required to initiate the -peering request: -** Customer AWS account number -** Customer VPC ID -** Customer VPC Region -** Customer VPC CIDR -* Check the CIDR block used by the {product-title} Cluster VPC. If it overlaps or -matches the CIDR block for the Customer VPC, then peering between these two VPCs -is not possible; see the Amazon VPC -link:https://docs.aws.amazon.com/vpc/latest/peering/invalid-peering-configurations.html[Unsupported VPC Peering Configurations] -documentation for details. If the CIDR blocks do not overlap, you can procedure -with the procedure. - -.Procedure - -. Log in to the Web Console for the OSD AWS Account and navigate to the -*VPC Dashboard* in the region where the cluster is being hosted. -. Go to the *Peering Connections* page and click the *Create Peering Connection* -button. -. Verify the details of the account you are logged in to and the details of the -account and VPC you are connecting to: -.. *Peering connection name tag*: Set a descriptive name for the VPC Peering Connection. -.. *VPC (Requester)*: Select the {product-title} Cluster VPC ID from the dropdown -*list. -.. *Account*: Select *Another account* and provide the Customer AWS Account number -*(without dashes). -.. *Region*: If the Customer VPC Region differs from the current region, select -*Another Region* and select the customer VPC Region from the dropdown list. -.. *VPC (Accepter)*: Set the Customer VPC ID. -. Click *Create Peering Connection*. -. Confirm that the request enters a *Pending* state. If it enters a *Failed* -state, confirm the details and repeat the process. diff --git a/modules/dedicated-aws-vpc-peering-terms.adoc b/modules/dedicated-aws-vpc-peering-terms.adoc deleted file mode 100644 index 964506b55921..000000000000 --- a/modules/dedicated-aws-vpc-peering-terms.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-peering.adoc - -[id="dedicated-aws-vpc-peering-terms"] -= VPC peering terms - -When setting up a VPC peering connection between two VPCs on two separate AWS -accounts, the following terms are used: - -[horizontal] -OSD AWS Account:: The AWS account that contains the {product-title} cluster. -OSD Cluster VPC:: The VPC that contains the {product-title} cluster. -Customer AWS Account:: Your non-OSD AWS Account that you would like to peer with. -Customer VPC:: The VPC in your AWS Account that you would like to peer with. -Customer VPC Region:: The region where the customer's VPC resides. - -[NOTE] -==== -As of July 2018, AWS supports inter-region VPC peering between all commercial regions link:https://aws.amazon.com/vpc/faqs/#Peering_Connections[excluding China]. -==== diff --git a/modules/dedicated-aws-vpc-verifying-troubleshooting.adoc b/modules/dedicated-aws-vpc-verifying-troubleshooting.adoc deleted file mode 100644 index 191813f59061..000000000000 --- a/modules/dedicated-aws-vpc-verifying-troubleshooting.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-peering.adoc - -[id="dedicated-aws-vpc-verifying-troubleshooting"] -= Verifying and troubleshooting VPC peering - -After you set up a VPC peering connection, it is best to confirm it has been -configured and is working correctly. - -.Prerequisites - -* Initiate and accept the VPC peer request. -* Configure the routing tables. - -.Procedure - -* In the AWS console, look at the route table for the cluster VPC that is peered. -Ensure that the steps for configuring the routing tables were followed and that -there is a route table entry pointing the VPC CIDR range destination to the -peering connection target. -+ -If the routes look correct on both the {product-title} Cluster VPC route table -and Customer VPC route table, then the connection should be tested using the -`netcat` method below. If the test calls are successful, then VPC peering is -working correctly. - -* To test network connectivity to an endpoint device, `nc` (or `netcat`) is a -helpful troubleshooting tool. It is included in the default image and provides -quick and clear output if a connection can be established: - -.. Create a temporary Pod using the `busybox` image, which cleans up after itself: -+ ----- -$ oc run netcat-test \ - --image=busybox -i -t \ - --restart=Never --rm \ - -- /bin/sh ----- - -.. Check the connection using `nc`. -+ --- -* Example successful connection results: -+ ----- -/ nc -zvv 192.168.1.1 8080 -10.181.3.180 (10.181.3.180:8080) open -sent 0, rcvd 0 ----- - -* Example failed connection results: -+ ----- -/ nc -zvv 192.168.1.2 8080 -nc: 10.181.3.180 (10.181.3.180:8081): Connection refused -sent 0, rcvd 0 ----- --- - -.. Exit the container, which automatically deletes the Pod: -+ ----- -/ exit ----- diff --git a/modules/dedicated-aws-vpn-creating.adoc b/modules/dedicated-aws-vpn-creating.adoc deleted file mode 100644 index 4bcc110bc3f2..000000000000 --- a/modules/dedicated-aws-vpn-creating.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-vpn.adoc - -[id="dedicated-aws-vpn-creating"] -= Creating a VPN connection - -You can configure an Amazon Web Services (AWS) {product-title} cluster to use a -customer's on-site hardware VPN device using the following procedures. - -.Prerequisites - -* Hardware VPN gateway device model and software version, for example Cisco ASA -running version 8.3. See the Amazon VPC -link:https://docs.aws.amazon.com/vpc/latest/adminguide/Introduction.html#DevicesTested[Network Administrator Guide] -to confirm whether your gateway device is supported by AWS. -* Public, static IP address for the VPN gateway device. -* BGP or static routing: if BGP, the ASN is required. If static routing, you must -configure at least one static route. -* Optional: IP and Port/Protocol of a reachable service to test the VPN connection. - -[id="dedicated-aws-vpn-creating-configuring"] -== Configuring the VPN connection - -.Procedure - -. Log in to the OSD AWS Account Dashboard, and navigate to the VPC Dashboard. -. Click on *Your VPCs* and identify the name and VPC ID for the VPC containing the {product-title} cluster. -. From the VPC Dashboard, click *Customer Gateway*. -. Click *Create Customer Gateway* and give it a meaningful name. -. Select the routing method: *Dynamic* or *Static*. -. If Dynamic, enter the BGP ASN in the field that appears. -. Paste in the VPN gateway endpoint IP address. -. Click *Create*. -. If you do not already have a Virtual Private Gateway attached to the intended VPC: -.. From the VPC Dashboard, click on *Virtual Private Gateway*. -.. Click *Create Virtual Private Gateway*, give it a meaningful name, and click *Create*. -.. Leave the default Amazon default ASN. -.. Select the newly created gateway, click *Attach to VPC*, and attach it to the cluster VPC you identified earlier. - -[id="dedicated-aws-vpn-creating-establishing"] -== Establishing the VPN Connection - -.Procedure - -. From the VPC dashboard, click on *Site-to-Site VPN Connections*. -. Click *Create VPN Connection*. -.. Give it a meaningful name tag. -.. Select the virtual private gateway created previously. -.. For Customer Gateway, select *Existing*. -.. Select the customer gateway device by name. -.. If the VPN will use BGP, select *Dynamic*, otherwise select *Static*. Enter -Static IP CIDRs. If there are multiple CIDRs, add each CIDR as *Another Rule*. -.. Click *Create*. -.. Wait for VPN status to change to *Available*, approximately 5 to 10 minutes. -. Select the VPN you just created and click *Download Configuration*. -.. From the dropdown list, select the vendor, platform, and version of the customer -gateway device, then click *Download*. -.. The *Generic* vendor configuration is also available for retrieving information -in a plain text format. - -[NOTE] -==== -After the VPN connection has been established, be sure to set up Route -Propagation or the VPN may not function as expected. -==== - -[NOTE] -==== -Note the VPC subnet information, which you must add to your configuration as the -remote network. -==== - -[id="dedicated-aws-vpn-creating-propagation"] -== Enabling VPN route propagation - -After you have set up the VPN connection, you must ensure that route propagation -is enabled so that the necessary routes are added to the VPC's route table. - -.Procedure - -. From the VPC Dashboard, click on *Route Tables*. -. Select the private Route table associated with the VPC that contains your -{product-title} cluster. -+ -[NOTE] -==== -On some clusters, there may be more than one route table for a particular VPC. -Select the private one that has a number of explicitly associated subnets. -==== -. Click on the *Route Propagation* tab. -. In the table that appears, you should see the virtual private gateway you -created previously. Check the value in the *Propagate column*. -.. If Propagate is set to *No*, click *Edit route propagation*, check the Propagate -checkbox next to the virtual private gateway's name and click *Save*. - -After you configure your VPN tunnel and AWS detects it as *Up*, your static or -BGP routes are automatically added to the route table. diff --git a/modules/dedicated-aws-vpn-troubleshooting.adoc b/modules/dedicated-aws-vpn-troubleshooting.adoc deleted file mode 100644 index ea7d31503ddb..000000000000 --- a/modules/dedicated-aws-vpn-troubleshooting.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-vpn.adoc - -[id="dedicated-aws-vpn-troubleshooting"] -= Troubleshooting the VPN connection - -[discrete] -[id="dedicated-aws-vpn-tunnel-down"] -== Tunnel does not connect - -If the tunnel connection is still *Down*, there are several things you can verify: - -* The AWS tunnel will not initiate a VPN connection. The connection attempt must be initiated from the Customer Gateway. -* Ensure that your source traffic is coming from the same IP as the configured customer gateway. AWS will silently drop all traffic to the gateway whose source IP address does not match. -* Ensure that your configuration matches values link:https://docs.aws.amazon.com/vpc/latest/adminguide/Introduction.html#CGRequirements[supported by AWS]. This includes IKE versions, DH groups, IKE lifetime, and more. -* Recheck the route table for the VPC. Ensure that propagation is enabled and that there are entries in the route table that have the virtual private gateway you created earlier as a target. -* Confirm that you do not have any firewall rules that could be causing an interruption. -* Check if you are using a policy-based VPN as this can cause complications depending on how it is configured. -* Further troubleshooting steps can be found at the link:https://aws.amazon.com/premiumsupport/knowledge-center/vpn-tunnel-troubleshooting/[AWS Knowledge Center]. - -[discrete] -[id="dedicated-aws-vpn-tunnel-stay-connected"] -== Tunnel does not stay connected - -If the tunnel connection has trouble staying *Up* consistently, know that all -AWS tunnel connections must be initiated from your gateway. AWS tunnels -link:https://docs.aws.amazon.com/vpn/latest/s2svpn/VPC_VPN.html#CustomerGateway[do -not initiate tunneling]. - -Red Hat recommends setting up an SLA Monitor (Cisco ASA) or some device on your -side of the tunnel that constantly sends "interesting" traffic, for example -`ping`, `nc`, or `telnet`, at any IP address configured within the VPC CIDR -range. It does not matter whether the connection is successful, just that the -traffic is being directed at the tunnel. - -[discrete] -[id="dedicated-aws-vpn-secondary-tunnel-down"] -== Secondary tunnel in Down state - -When a VPN tunnel is created, AWS creates an additional failover tunnel. -Depending upon the gateway device, sometimes the secondary tunnel will be seen -as in the *Down* state. - -The AWS Notification is as follows: - ----- -You have new non-redundant VPN connections - -One or more of your vpn connections are not using both tunnels. This mode of -operation is not highly available and we strongly recommend you configure your -second tunnel. View your non-redundant VPN connections. ----- diff --git a/modules/dedicated-aws-vpn-verifying.adoc b/modules/dedicated-aws-vpn-verifying.adoc deleted file mode 100644 index 0011954d9bd6..000000000000 --- a/modules/dedicated-aws-vpn-verifying.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/cloud_infrastructure_access/dedicated-aws-vpn.adoc - -[id="dedicated-aws-vpn-verifying"] -= Verifying the VPN connection - -After you have set up your side of the VPN tunnel, you can verify that the -tunnel is up in the AWS console and that connectivity across the tunnel is -working. - -.Prerequisites - -* Created a VPN connection. - -.Procedure - -. *Verify the tunnel is up in AWS.* - -.. From the VPC Dashboard, click on *VPN Connections*. -.. Select the VPN connection you created previously and click the *Tunnel Details* tab. -.. You should be able to see that at least one of the VPN tunnels is *Up*. - -. *Verify the connection.* -+ -To test network connectivity to an endpoint device, `nc` (or `netcat`) is a -helpful troubleshooting tool. It is included in the default image and provides -quick and clear output if a connection can be established: - -.. Create a temporary Pod using the `busybox` image, which cleans up after itself: -+ ----- -$ oc run netcat-test \ - --image=busybox -i -t \ - --restart=Never --rm \ - -- /bin/sh ----- - -.. Check the connection using `nc`. -+ --- -* Example successful connection results: -+ ----- -/ nc -zvv 192.168.1.1 8080 -10.181.3.180 (10.181.3.180:8080) open -sent 0, rcvd 0 ----- - -* Example failed connection results: -+ ----- -/ nc -zvv 192.168.1.2 8080 -nc: 10.181.3.180 (10.181.3.180:8081): Connection refused -sent 0, rcvd 0 ----- --- - -.. Exit the container, which automatically deletes the Pod: -+ ----- -/ exit ----- diff --git a/modules/dedicated-cluster-admin-enable.adoc b/modules/dedicated-cluster-admin-enable.adoc deleted file mode 100644 index df8defa375b2..000000000000 --- a/modules/dedicated-cluster-admin-enable.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// administering_a_cluster/cluster-admin-role.adoc - -[id="dedicated-cluster-admin-enable"] -= Enabling the cluster-admin role for your cluster - -The cluster-admin role must be enabled at the cluster level before it can be assigned to a user. - -.Prerequisites -. Open a technical support case with Red Hat to request that `cluster-admin` be enabled for your cluster. - -.Procedure -. In the OpenShift Cluster Manager, select the cluster you want to assign cluster-admin privileges. -. Under the *Actions* dropdown menu, select *Allow cluster-admin access*. diff --git a/modules/dedicated-cluster-admin-grant.adoc b/modules/dedicated-cluster-admin-grant.adoc deleted file mode 100644 index 1b7b3a6e27f3..000000000000 --- a/modules/dedicated-cluster-admin-grant.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// administering_a_cluster/cluster-admin-role.adoc - -[id="dedicated-cluster-admin-grant"] -= Granting the cluster-admin role to users - -After enabling cluster-admin rights on your cluster, you can assign the role to users. - -.Prerequisites -* Cluster access with cluster owner permissions - -.Procedure -. In the OpenShift Cluster Manager, select the cluster you want to assign cluster-admin privileges. -. Under the *Access Control* tab, locate the *Cluster Administrative Users* section. Click *Add user*. -. After determining an appropriate User ID, select *cluster-admin* from the *Group* selection, then click *Add user*. -+ -[NOTE] -==== -Cluster-admin user creation can take several minutes to complete. -==== -+ -[NOTE] -==== -Existing dedicated-admin users cannot elevate their role to cluster-admin. A new user must be created with the cluster-admin role assigned. -==== diff --git a/modules/dedicated-cluster-install-deploy.adoc b/modules/dedicated-cluster-install-deploy.adoc deleted file mode 100644 index 397ce4b9f39a..000000000000 --- a/modules/dedicated-cluster-install-deploy.adoc +++ /dev/null @@ -1,150 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/dedicated-cluster-deploying.adoc - -[id="dedicated-cluster-install-deploy"] - -= Installing OpenShift Logging and OpenShift Elasticsearch Operators - -You can use the {product-title} console to install OpenShift Logging by deploying instances of -the OpenShift Logging and OpenShift Elasticsearch Operators. The Cluster Logging Operator -creates and manages the components of the logging stack. The OpenShift Elasticsearch Operator -creates and manages the Elasticsearch cluster used by OpenShift Logging. - -[NOTE] -==== -The OpenShift Logging solution requires that you install both the -Cluster Logging Operator and OpenShift Elasticsearch Operator. When you deploy an instance -of the Cluster Logging Operator, it also deploys an instance of the OpenShift Elasticsearch -Operator. -==== - -Your OpenShift Dedicated cluster includes 600 GiB of persistent storage that is -exclusively available for deploying Elasticsearch for OpenShift Logging. - -Elasticsearch is a memory-intensive application. Each Elasticsearch node needs -8G of memory for both memory requests and limits. Each Elasticsearch node can -operate with a lower memory setting, though this is not recommended for -production deployments. - -.Procedure - -. Install the OpenShift Elasticsearch Operator from the OperatorHub: - -.. In the {product-title} web console, click *Operators* -> *OperatorHub*. - -.. Choose *Elasticsearch* from the list of available Operators, and click *Install*. - -.. On the *Install Operator* page, under *A specific namespace on the cluster* select *openshift-logging*. -Then, click *Install*. - -. Install the Cluster Logging Operator from the OperatorHub: - -.. In the {product-title} web console, click *Operators* -> *OperatorHub*. - -.. Choose *Cluster Logging* from the list of available Operators, and click *Install*. - -.. On the *Install Operator* page, under *A specific namespace on the cluster* select *openshift-logging*. -Then, click *Install*. - -. Verify the operator installations: - -.. Switch to the *Operators* → *Installed Operators* page. - -.. Ensure that *Cluster Logging* and *Elasticsearch* Operators are listed in the -*openshift-logging* project with a *Status* of *InstallSucceeded*. -+ -[NOTE] -==== -During installation an operator might display a *Failed* status. If the operator then installs with an *InstallSucceeded* message, -you can safely ignore the *Failed* message. -==== -+ -If either operator does not appear as installed, to troubleshoot further: -+ -* Switch to the *Operators* → *Installed Operators* page and inspect -the *Status* column for any errors or failures. -* Switch to the *Workloads* → *Pods* page and check the logs in each Pod in the -`openshift-logging` project that is reporting issues. - -. Create and deploy a OpenShift Logging instance: - -.. Switch to the *Operators* → *Installed Operators* page. - -.. Click the installed *Cluster Logging* Operator. - -.. Under the *Details* tab, in the *Provided APIs* section, in the -*Cluster Logging* box, click *Create Instance* . Select the *YAML View* -radio button and paste the following YAML definition into the window -that displays. -+ -.Cluster Logging custom resource (CR) -[source,yaml] ----- -apiVersion: "logging.openshift.io/v1" -kind: "ClusterLogging" -metadata: - name: "instance" - namespace: "openshift-logging" -spec: - managementState: "Managed" - logStore: - type: "elasticsearch" - elasticsearch: - nodeCount: 3 - storage: - storageClassName: gp2 - size: "200Gi" - redundancyPolicy: "SingleRedundancy" - nodeSelector: - node-role.kubernetes.io/worker: "" - resources: - limits: - memory: 16G - requests: - memory: 16G - visualization: - type: "kibana" - kibana: - replicas: 1 - nodeSelector: - node-role.kubernetes.io/worker: "" - curation: - type: "curator" - curator: - schedule: "15 * * * *" - nodeSelector: - node-role.kubernetes.io/worker: "" - collection: - logs: - type: "fluentd" - fluentd: {} - nodeSelector: - node-role.kubernetes.io/worker: "" ----- - -.. Click *Create* to deploy the logging instance, which creates the Cluster -Logging and Elasticsearch custom resources. - -. Verify that the pods for the OpenShift Logging instance deployed: - -.. Switch to the *Workloads* → *Pods* page. - -.. Select the *openshift-logging* project. -+ -You should see several pods for OpenShift Logging, Elasticsearch, Fluentd, and Kibana similar to the following list: -+ -* cluster-logging-operator-cb795f8dc-xkckc -* elasticsearch-cdm-b3nqzchd-1-5c6797-67kfz -* elasticsearch-cdm-b3nqzchd-2-6657f4-wtprv -* elasticsearch-cdm-b3nqzchd-3-588c65-clg7g -* fluentd-2c7dg -* fluentd-9z7kk -* fluentd-br7r2 -* fluentd-fn2sb -* fluentd-pb2f8 -* fluentd-zqgqx -* kibana-7fb4fd4cc9-bvt4p - -. Access the OpenShift Logging interface, *Kibana*, from the *Monitoring* → -*Logging* page of the {product-title} web console. diff --git a/modules/dedicated-configuring-your-application-routes.adoc b/modules/dedicated-configuring-your-application-routes.adoc deleted file mode 100644 index 41154213a8eb..000000000000 --- a/modules/dedicated-configuring-your-application-routes.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * welcome/accessing-your-services.adoc - -[id="dedicated-configuring-your-application-routes_{context}"] -= Configuring your application routes - -When your cluster is provisioned, an AWS elastic load balancer (ELB) is created -to route application traffic into the cluster. The domain for your ELB is -configured to route application traffic via -`http(s)://*.<cluster-id>.<shard-id>.p1.openshiftapps.com`. The `<shard-id>` is a -random four-character string assigned to your cluster at creation time. - -If you want to use custom domain names for your application routes, {product-title} supports -CNAME records in your DNS configuration that point to -`elb.apps.<cluster-id>.<shard-id>.p1.openshiftapps.com`. While `elb` is recommended as a -reminder for where this record is pointing, you can use any string for this -value. You can create these CNAME records for each custom route you have, or you -can create a wildcard CNAME record. For example: - ----- -*.openshift.example.com CNAME elb.apps.my-example.a1b2.p1.openshiftapps.com ----- - -This allows you to create routes like *_app1.openshift.example.com_* and -*_app2.openshift.example.com_* without having to update your DNS every time. - -//// - -Customers with configured VPC peering or VPN connections have the option of -requesting a second ELB, so that application routes can be configured as -internal-only or externally available. The domain for this ELB will be identical -to the first, with a different `<shard-id>` value. By default, application -routes are handled by the internal-only router. To expose an application or -service externally, you must create a new route with a specific label, -`route=external`. - -To expose a new route for an existing service, apply the label `route=external` -and define a host name that contains the secondary, public router shard ID: - ----- -$ oc expose service <service-name> -l route=external --name=<custom-route-name> --hostname=<custom-hostname>.<shard-id>.<cluster-id>.openshiftapps.com ----- - -Alternatively, you can use a custom domain: - ----- -$ oc expose service <service-name> -l route=external --name=<custom-route-name> --hostname=<custom-domain> ----- - -//// diff --git a/modules/dedicated-creating-your-cluster.adoc b/modules/dedicated-creating-your-cluster.adoc deleted file mode 100644 index 072038f955fd..000000000000 --- a/modules/dedicated-creating-your-cluster.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/accessing-your-services.adoc - -[id="dedicated-creating-your-cluster_{context}"] -= Creating your cluster - -To create your {product-title} cluster: - -. Log in to link:https://cloud.redhat.com/openshift[cloud.redhat.com/openshift]. - -. Select *Create Cluster* -> *Red Hat OpenShift Dedicated*. - -. Enter your *Cluster name*, number of *Compute nodes*, and select an *AWS Region*. - -. Select your *Node Type*. The number and types of nodes available to you depend -upon your {product-title} subscription. - -. If you want to configure your networking IP ranges under *Advanced Options*, the -following are the default ranges available to use: - -.. Node CIDR: 10.0.0.0/16 - -.. Service CIDR: 172.30.0.0/16 - -.. Pod CIDR: 10.128.0.0/14 - -. Add your Identity provider by clicking the *Add OAuth Configuration* link or using the *Access Control* tab. - -. Add a _Dedicated Admin_ user by clicking the *Access Control* tab, then *Add User*. - -. Input the user's name, then click *Add*. - -In the *Overview* tab under the *Details* heading will have a *Status* -indicator. This will indicate that your cluster is *Ready* for use. - -= Accessing your cluster - -To access your {product-title} cluster: - -. From link:https://cloud.redhat.com/openshift[cloud.redhat.com/openshift], click - on the cluster you want to access. - - . Click *Launch Console*. diff --git a/modules/dedicated-enable-private-cluster-existing.adoc b/modules/dedicated-enable-private-cluster-existing.adoc deleted file mode 100644 index 26dad14de1de..000000000000 --- a/modules/dedicated-enable-private-cluster-existing.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * cloud_infrastructure_access/dedicated-private-cluster.adoc - -[id="dedicated-enable-private-cluster-existing"] -= Enabling private cluster on an existing cluster - -You can enable private clusters after a cluster has been created: - -.Prerequisites - -* AWS VPC Peering, VPN, DirectConnect, or TransitGateway has been configured to allow private access. - -.Procedure - -. Access your cluster in the OpenShift Cluster Manager. -. Navigate to the *Networking* tab. -. Select *Make API private* under *Master API endpoint* and click *Change settings*. -+ -[NOTE] -==== -Transitioning your cluster between private and public can take several minutes to complete. -==== diff --git a/modules/dedicated-enable-private-cluster-new.adoc b/modules/dedicated-enable-private-cluster-new.adoc deleted file mode 100644 index cad07eadb040..000000000000 --- a/modules/dedicated-enable-private-cluster-new.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * cloud_infrastructure_access/dedicated-private-cluster.adoc - -[id="dedicated-enable-private-cluster-new"] -= Enabling private cluster on a new cluster - -You can enable private cluster settings when creating a new cluster: - -.Prerequisites - -* AWS VPC Peering, VPN, DirectConnect, or TransitGateway has been configured to allow private access. - -.Procedure - -. In the OpenShift Cluster Manager, click *Create cluster* and select *{product-title}*. -. Configure your cluster details, then select *Advanced* in the Networking section. -. Determine your CIDR requirements for your network and input the required fields. -+ -[IMPORTANT] -==== -CIDR configurations cannot be changed later. Confirm your selections with your network administrator before proceeding. -==== -. Under *Cluster Privacy*, select *Private*. diff --git a/modules/dedicated-enable-public-cluster.adoc b/modules/dedicated-enable-public-cluster.adoc deleted file mode 100644 index a64b9d7e163b..000000000000 --- a/modules/dedicated-enable-public-cluster.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * cloud_infrastructure_access/dedicated-private-cluster.adoc - -[id="dedicated-enable-public-cluster"] -= Enabling public cluster on a private cluster - -You can set a private cluster to public facing: - -.Procedure - -. Access your cluster in the OpenShift Cluster Manager. -. Navigate to the *Networking* tab. -. Deselect *Make API private* under *Master API endpoint* and click *Change settings*. -+ -[NOTE] -==== -Transitioning your cluster between private and public can take several minutes to complete. -==== diff --git a/modules/dedicated-exposing-TCP-services.adoc b/modules/dedicated-exposing-TCP-services.adoc deleted file mode 100644 index e64c95e86bb3..000000000000 --- a/modules/dedicated-exposing-TCP-services.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// * welcome/accessing-your-services.adoc - -[id="dedicated-exposing-TCP-services_{context}"] -= Exposing TCP services - -{product-title} routes expose applications by proxying traffic through -HTTP/HTTPS(SNI)/TLS(SNI) to pods and services. A -link:https://kubernetes.io/docs/concepts/services-networking/#loadbalancer[LoadBalancer] -service creates an AWS Elastic Load Balancer (ELB) for your {product-title} -cluster, enabling direct TCP access to applications exposed by your LoadBalancer -service. - -[NOTE] -==== -LoadBalancer services require an additional purchase. Contact your sales team if -you are interested in using LoadBalancer services for your {product-title} -cluster. -==== - -== Checking your LoadBalancer Quota - -By purchasing LoadBalancer services, you are provided with a quota of -LoadBalancers available for your {product-title} cluster. - ----- -$ oc describe clusterresourcequota loadbalancer-quota -Name: loadbalancer-quota -Labels: <none> -... -Resource Used Hard --------- ---- ---- -services.loadbalancers 0 4 ----- - -== Exposing TCP service - -You can expose your applications over an external LoadBalancer service, enabling -access over the public Internet. - ----- -$ oc expose dc httpd-example --type=LoadBalancer --name=lb-service -service/lb-service created ----- - -== Creating an internal-only TCP service - -You can alternatively expose your applications internally only, enabling access -only through AWS VPC Peering or a VPN connection. - ----- -$ oc expose dc httpd-example --type=LoadBalancer --name=internal-lb --dry-run -o yaml | awk '1;/metadata:/{ print " annotations:\n service.beta.kubernetes.io/aws-load-balancer-internal: \"true\"" }' | oc create -f - -service/internal-lb created ----- - -== Enabling LoadBalancer access logs - -You may, optionally, create an S3 bucket within your own AWS account, and configure the LoadBalancer service to send access logs to this S3 bucket at predefined intervals. - -=== Prerequisites - -You must first create the S3 bucket within your own AWS account, in the same AWS region that your {product-title} cluster is deployed. This S3 bucket can be configured with all public access blocked, including system permissions. Once your S3 bucket is created, you must attach a policy to your bucket as https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/enable-access-logs.html#attach-bucket-policy[outlined by AWS]. - -=== Configuring the LoadBalancer service - -Update and apply the following annotations to your service YAML definition, prior to creating the object in your cluster. - ----- -metadata: - name: my-service - annotations: - # Specifies whether access logs are enabled for the load balancer - service.beta.kubernetes.io/aws-load-balancer-access-log-enabled: "true" - # The interval for publishing the access logs. You can specify an interval of either 5 or 60 (minutes). - service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval: "60" - # The name of the Amazon S3 bucket where the access logs are stored - service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name: "my-bucket" - # The logical hierarchy you created for your Amazon S3 bucket, for example `my-bucket-prefix/prod` - # This must match the prefix specified in the S3 policy - service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix: "my-bucket-prefix/prod" ----- - -=== Creating the LoadBalancer service - -Once the annotations have been saved into a YAML file, you can create it from the command line: - ----- -$ oc create -f loadbalancer.yml -service/my-service created ----- - -== Using your TCP Service - -Once your LoadBalancer service is created, you can access your service by using -the URL provided to you by {product-title}. The `LoadBalancer Ingress` value is -a URL unique to your service that remains static as long as the service is not -deleted. If you prefer to use a custom domain, you can create a CNAME DNS record -for this URL. - ----- -$ oc describe svc lb-service -Name: lb-service -Namespace: default -Labels: app=httpd-example -Annotations: <none> -Selector: name=httpd-example -Type: LoadBalancer -IP: 10.120.182.252 -LoadBalancer Ingress: a5387ba36201e11e9ba901267fd7abb0-1406434805.us-east-1.elb.amazonaws.com -Port: <unset> 8080/TCP -TargetPort: 8080/TCP -NodePort: <unset> 31409/TCP -Endpoints: <none> -Session Affinity: None -External Traffic Policy: Cluster ----- diff --git a/modules/dedicated-logging-in-and-verifying-permissions.adoc b/modules/dedicated-logging-in-and-verifying-permissions.adoc deleted file mode 100644 index 0301ab410ac0..000000000000 --- a/modules/dedicated-logging-in-and-verifying-permissions.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// administering_a_cluster/dedicated-admin-role.adoc - -[id="dedicated-admin-logging-in-verifying-permissions_{context}"] -= Logging in and verifying permissions - -You can log in as an {product-title} cluster administration via the web console -or CLI, just as you would if you were an application developer. - -When you log in to the web console, all user-created projects across the cluster -are visible from the main *Projects* page. - -Use the standard `oc login` command to log in with the CLI: - ----- -$ oc login <your_instance_url> ----- - -All projects are visible using: - ----- -$ oc get projects ----- - -When your account has the `dedicated-admins-cluster` cluster role bound to it, -you are automatically bound to the `dedicated-admins-project` for any new -projects that are created by users in the cluster. - -To verify if your account has administrator privileges, run the following -command against a user-created project to view its default role bindings. If you -are a cluster administrator, you will see your account listed under subjects for -the `dedicated-admins-project-0` and `dedicated-admins-project-1` role bindings -for the project: - ----- -$ oc describe rolebinding.rbac -n <project_name> - -Name: admin -Labels: <none> -Annotations: <none> -Role: - Kind: ClusterRole - Name: admin -Subjects: - Kind Name Namespace - ---- ---- --------- - User fred@example.com <1> - - -Name: dedicated-admins-project -Labels: <none> -Annotations: <none> -Role: - Kind: ClusterRole - Name: dedicated-admins-project -Subjects: - Kind Name Namespace - ---- ---- --------- - User alice@example.com <2> - User bob@example.com <2> -... ----- -<1> The `fred@example.com` user is a normal, project-scoped administrator for -this project. -<2> The `alice@example.com` and `bob@example.com` users are cluster -administrators. - -To view details on your increased permissions, and the sets of -verbs and resources associated with the `dedicated-admins-cluster` and -`dedicated-admins-project` roles, run the following: - ----- -$ oc describe clusterrole.rbac dedicated-admins-cluster -$ oc describe clusterrole.rbac dedicated-admins-project ----- diff --git a/modules/dedicated-managing-dedicated-administrators.adoc b/modules/dedicated-managing-dedicated-administrators.adoc deleted file mode 100644 index a819558b1cfe..000000000000 --- a/modules/dedicated-managing-dedicated-administrators.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// administering_a_cluster/dedicated-admin-role.adoc - -[id="dedicated-managing-dedicated-administrators_{context}"] -= Managing {product-title} administrators - -Administrator roles are managed using a `dedicated-admins` group on the cluster. -Existing members of this group can edit membership via the -link:https://cloud.redhat.com/openshift[{cloud-redhat-com}] site. - -[id="dedicated-administrators-adding-user_{context}"] -== Adding a user -. Navigate to the *Cluster Details* page and *Access Control* tab. -. Click the *Add user* button. (first user only) -. Enter the user name and select the group (*dedicated-admins*) -. Click the *Add* button. - -[id="dedicated-administrators-removing-user_{context}"] -== Removing a user -. Navigate to the *Cluster Details* page and *Access Control* tab. -. Click the 3 vertical dots to the right of the user / group combination to show a menu, then click on *Delete*. diff --git a/modules/dedicated-managing-quotas-and-limit-ranges.adoc b/modules/dedicated-managing-quotas-and-limit-ranges.adoc deleted file mode 100644 index fec3480cb036..000000000000 --- a/modules/dedicated-managing-quotas-and-limit-ranges.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// administering_a_cluster/dedicated-admin-role.adoc - -[id="dedicated-managing-quotas-and-limit-ranges_{context}"] -= Managing quotas and limit ranges - -As an administrator, you are able to view, create, and modify quotas and limit -ranges on other projects. This allows you to better constrain how compute -resources and objects are consumed by users across the cluster. diff --git a/modules/dedicated-managing-service-accounts.adoc b/modules/dedicated-managing-service-accounts.adoc deleted file mode 100644 index 684a22055276..000000000000 --- a/modules/dedicated-managing-service-accounts.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// administering_a_cluster/dedicated-admin-role.adoc - -[id="dedicated-managing-service-accounts_{context}"] -= Managing service accounts - -Service accounts are API objects that exist within each project. To manage -service accounts, you can use the `oc` command with the `sa` or `serviceaccount` -object type or use the web console. - -The *dedicated-admin* service creates the *dedicated-admins* group. This group is -granted the roles at the cluster or individual project level. Users can be -assigned to this group and group membership defines who has OpenShift Dedicated -administrator access. However, by design, service accounts cannot be added to -regular groups. - -Instead, the dedicated-admin service creates a special project for this purpose -named *dedicated-admin*. The service account group for this project is granted -OpenShift Dedicated *admin* roles, granting OpenShift Dedicated administrator -access to all service accounts within the *dedicated-admin* project. These service -accounts can then be used to perform any actions that require OpenShift -Dedicated administrator access. - -Users that are members of the *dedicated-admins* group, and thus have been granted -the *dedicated-admin* role, have `edit` access to the *dedicated-admin* project. This -allows these users to manage the service accounts in this project and create new -ones as needed. - -To get a list of existing service accounts in the current project, run: - ----- -$ oc get sa -NAME SECRETS AGE -builder 2 2d -default 2 2d -deployer 2 2d ----- - -To create a new service account, run: - ----- -$ oc create sa <service-account-name> ----- - -As soon as a service account is created, two secrets are automatically added to -it: - -* an API token -* credentials for the OpenShift Container Registry - -These can be seen by describing the service account: - ----- -$ oc describe sa <service-account-name> ----- - -The system ensures that service accounts always have an API token and registry -credentials. - -The generated API token and registry credentials do not expire, but they can be -revoked by deleting the secret. When the secret is deleted, a new one is -automatically generated to take its place. diff --git a/modules/dedicated-scaling-your-cluster.adoc b/modules/dedicated-scaling-your-cluster.adoc deleted file mode 100644 index 76a2e512c743..000000000000 --- a/modules/dedicated-scaling-your-cluster.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * getting_started/scaling_your_cluster.adoc - -[id="dedicated-scaling-your-cluster_{context}"] -= Scaling your cluster - -To scale your {product-title} cluster: - -. From link:https://cloud.redhat.com/openshift[cloud.redhat.com/openshift], click - on the cluster you want to resize. - -. Click the *Actions* button, then *Scale Cluster*. - -. Select how many compute nodes are required, then click *Apply*. - -Scaling occurs automatically. In the *Overview* tab under the *Details* -heading,the *Status* indicator shows that your cluster is *Ready* for use. diff --git a/modules/dedicated-storage-expanding-filesystem-pvc.adoc b/modules/dedicated-storage-expanding-filesystem-pvc.adoc deleted file mode 100644 index 35b782c6eb5f..000000000000 --- a/modules/dedicated-storage-expanding-filesystem-pvc.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/expanding-persistent-volume.adoc - -[id="dedicated-storage-expanding-filesystem-pvc_{context}"] -= Expanding {product-title} Persistent Volume Claims (PVCs) - -Expanding PVCs based on volume types that need file system re-sizing, -such as AWS EBS, is a two-step process. -This process involves expanding volume objects in the cloud provider and -then expanding the file system on the actual node. These steps occur automatically -after the PVC object is edited and might require a pod restart to take effect. - -Expanding the file system on the node only happens when a new pod is started -with the volume. - -.Prerequisites - -* The controlling StorageClass must have `allowVolumeExpansion` set -to `true`. This is the default configuration in {product-title}. - -+ -[IMPORTANT] -==== -Decreasing the size of an Amazon Elastic Block Store (EBS) volume is not supported. However, you -can create a smaller volume and then migrate your data to it by using a -tool such as `oc rsync`. After modifying a volume, you must wait at least six hours before -making additional modifications to the same volume. -==== - -.Procedure - -. Edit the PVC and request a new size by editing the `spec.resources.requests.storage` -value. The following `oc patch` command will change the PVC's size: -+ ----- -$ oc patch pvc <pvc_name> -p '{"spec": {"resources": {"requests": {"storage": "8Gi"}}}}' ----- - -. Once the cloud provider object has finished re-sizing, the PVC might be set to -`FileSystemResizePending`. The following command is used to check -the condition: -+ ----- -$ oc describe pvc mysql - -Name: mysql -Namespace: my-project -StorageClass: gp2 -Status: Bound -Volume: pvc-5fa3feb4-7115-4735-8652-8ebcfec91bb9 -Labels: app=cakephp-mysql-persistent - template=cakephp-mysql-persistent - template.openshift.io/template-instance-owner=6c7f7c56-1037-4105-8c08-55a6261c39ca -Annotations: pv.kubernetes.io/bind-completed: yes - pv.kubernetes.io/bound-by-controller: yes - volume.beta.kubernetes.io/storage-provisioner: kubernetes.io/aws-ebs - volume.kubernetes.io/selected-node: ip-10-0-128-221.us-east-2.compute.internal - volume.kubernetes.io/storage-resizer: kubernetes.io/aws-ebs -Finalizers: [kubernetes.io/pvc-protection] -Capacity: 1Gi <1> -Access Modes: RWO -VolumeMode: Filesystem -Conditions: <2> - Type Status LastProbeTime LastTransitionTime Reason Message - ---- ------ ----------------- ------------------ ------ ------- - FileSystemResizePending True <Timestamp> <Timestamp> Waiting for user to (re-)start a Pod to - finish file system resize of volume on node. -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal WaitForFirstConsumer 36m persistentvolume-controller waiting for first consumer to be created before binding - Normal ProvisioningSucceeded 36m persistentvolume-controller Successfully provisioned volume - pvc-5fa3feb4-7115-4735-8652-8ebcfec91bb9 using - kubernetes.io/aws-ebs -Mounted By: mysql-1-q4nz7 <3> ----- -<1> The current capacity of the PVC. -<2> Any relevant conditions are displayed here. -<3> The pod that is currently mounting this volume - -. If the output of the previous command included a message to restart the pod, delete the mounting pod that it specified: -+ ----- -$ oc delete pod mysql-1-q4nz7 ----- - -. Once the pod is running, the newly requested size is available and the -`FileSystemResizePending` condition is removed from the PVC. diff --git a/modules/default-requirements-central-services.adoc b/modules/default-requirements-central-services.adoc new file mode 100644 index 000000000000..c32239b8c8f6 --- /dev/null +++ b/modules/default-requirements-central-services.adoc @@ -0,0 +1,167 @@ +// Module included in the following assemblies: +// +// * installing/acs-default-requirements.adoc +:_mod-docs-content-type: CONCEPT +[id="default-requirements-central-services_{context}"] += Central services (self-managed) + +[NOTE] +==== +If you are using {rh-rhacscs-first}, you do not need to review the requirements for Central services, because they are managed by Red{nbsp}Hat. You only need to look at the requirements for secured cluster services. +==== + +Central services contain the following components: + +* Central +* Scanner V4 +* StackRox Scanner (optional) + +[id="default-requirements-central-services-central_{context}"] +== Central + +A containerized service called Central handles API interactions and {product-title-short} web portal access while a containerized service called Central DB (PostgreSQL 15) handles data persistence. + +Central DB requires persistent storage in the cluster where Central is installed. + +* You can provide storage with a persistent volume claim (PVC). ++ +[NOTE] +==== +You can use a hostPath volume for storage only if all your hosts (or a group of hosts) mount a shared file system, such as an NFS share or a storage appliance. +Otherwise, your data is only saved on a single node. Red{nbsp}Hat does not recommend using a hostPath volume. +==== +* Use Solid-State Drives (SSD) for best performance. However, you can use another storage type if you do not have SSDs available. +* If you use a web proxy or firewall, you must configure bypass rules to allow traffic for the `definitions.stackrox.io` domain and enable {product-title-short} to trust your web proxy or firewall. Otherwise, updates for vulnerabilities will fail. You must also ensure that incoming connections from Sensor on secured clusters to Central on port 443 are possible. ++ +{product-title} requires access to: + +** `definitions.stackrox.io` for downloading updated vulnerability data. Vulnerability updates allow {product-title} to maintain up-to-date vulnerability data when new vulnerabilities are discovered or additional data sources are added. + +[NOTE] +==== +For security reasons, you should deploy Central in a cluster with limited administrative access. +==== + +== CPU, memory, and storage requirements + +The following table lists the minimum CPU and memory values required to install and run Central. + +|=== +| Central | CPU | Memory + +| *Request* +| 1.5 cores +| 4 GiB + +| *Limit* +| 4 cores +| 8 GiB +|=== + +Central requires Central DB to store data. The following table lists the minimum CPU, memory, and storage values required to install and run Central DB. + +|=== +| Central DB | CPU | Memory | Storage + +| *Request* +| 4 cores +| 8 GiB +| 100 GiB + +| *Limit* +| 8 cores +| 16 GiB +| 100 GiB +|=== + + +[id="default-requirements-central-services-scanner_{context}"] +== Scanner + +Scanner is responsible for scanning images, nodes, and the platform for vulnerabilities. + +{product-title-short} includes two image vulnerability scanners: StackRox Scanner and Scanner V4. The StackRox Scanner is deprecated. Scanner V4 was introduced in release 4.4 and as of release 4.8 is the default image scanner. + +== StackRox Scanner + +The following table lists the minimum CPU and memory values required to install and run StackRox Scanner. The requirements in this table are based on the default of 3 replicas. + +|=== +| StackRox Scanner | CPU | Memory + +| *Request* +| 3 cores +| 4500 MiB + +| *Limit* +| 6 cores +| 12 GiB +|=== + +The StackRox Scanner requires Scanner DB (PostgreSQL 15) to store data. This data is not persisted. The following table lists the minimum CPU and memory values required to install and run Scanner DB. + +|=== +| Scanner DB | CPU | Memory + +| *Request* +| 0.2 cores +| 512 MiB + +| *Limit* +| 2 cores +| 4 GiB +|=== + + +[id="default-requirements-central-services-scanner-v4_{context}"] +== Scanner V4 + +*Scanner V4 Indexer* + +The requirements in this table are based on the default of 3 replicas. + +|=== +| Scanner V4 Indexer | CPU | Memory + +| *Request* +| 4.5 cores +| 1536 MiB + +| *Limit* +| 12 cores +| 9 GiB +|=== + +*Scanner V4 Matcher* + +The requirements in this table are based on the default of 2 replicas. + +|=== +| Scanner V4 Matcher | CPU | Memory + +| *Request* +| 1 core +| 3 GiB + +| *Limit* +| 2 cores +| 6 GiB +|=== + +*Scanner V4 DB* + +Scanner V4 requires Scanner V4 DB (PostgreSQL 15) to store data. For Scanner V4 DB, a PVC is required to ensure optimal performance. The following table lists the minimum CPU, memory, and storage values required to install and run Scanner V4 DB. + +|=== +| Scanner V4 DB | CPU | Memory | Storage + +| *Request* +| 1 core +| 4 GiB +| 50 GiB + +| *Limit* +| 4 cores +| 8 GiB +| 50 GiB +|=== diff --git a/modules/default-requirements-external-db.adoc b/modules/default-requirements-external-db.adoc new file mode 100644 index 000000000000..0bbe2df816c6 --- /dev/null +++ b/modules/default-requirements-external-db.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * installing/acs-default-requirements.adoc +:_mod-docs-content-type: CONCEPT +[id="external-db-req_{context}"] += Requirements for using an external database + +[role="_abstract"] +You can configure {product-title} Central services to use an external PostgreSQL-compatible database for data persistence instead of deploying its own database pod. + +[IMPORTANT] +==== +When you use an external database, note the following guidance: + +* The database infrastructure manages persistent storage for Central DB. Therefore, do not configure persistence settings for the Central DB within the {product-title-short} installation configuration. +* Red Hat supports the configuration and operation of {product-title-short} Central connected to that database. However, support for database-specific operations such as backup and restore, performance diagnosis and potential tuning, software and version upgrades, and high availability/disaster recovery operation falls under third-party support. Manually upgrading or customizing your database outside of a full platform upgrade also limits supportability. +==== + +If you select an external database, your database instance and the user connecting to it must meet the requirements listed in the following sections. + +== Database type and version +The database must be a PostgreSQL-compatible database that supports PostgreSQL 13 or later. + +== User permissions +The user account that Central uses to connect to the database must be a `superuser` account with connection rights to the database and the following permissions: + +* `Usage` and `Create` permissions on the schema. +* `Select`, `Insert`, `Update`, and `Delete` permissions on all tables in the schema. +* `Usage` permissions on all sequences in the schema. +* The ability to create and delete databases as a `superuser`. + +== Connection string +Central connects to the external database by using a connection string, which must be in `keyword=value` format. The connection string should specify details such as the host, port, database name, user, and SSL/TLS mode. For example, `host=<host> port=5432 database=stackrox user=stackrox sslmode=verify-ca`. + +[NOTE] +==== +Connections through *PgBouncer* are not supported. +==== + +== CA certificates +If your external database uses a certificate issued by a private or untrusted Certificate Authority (CA), you might need to specify the CA certificate so that Central trusts the database certificate. You can add this by using a TLS block in the Central custom resource configuration. diff --git a/modules/default-requirements-secured-cluster-services.adoc b/modules/default-requirements-secured-cluster-services.adoc new file mode 100644 index 000000000000..75d3cac3a3a3 --- /dev/null +++ b/modules/default-requirements-secured-cluster-services.adoc @@ -0,0 +1,227 @@ +// Module included in the following assemblies: +// +// * installing/acs-default-requirements.adoc +// * cloud_service/acscs-default-requirements.adoc +:_mod-docs-content-type: CONCEPT +[id="default-requirements-secured-cluster-services_{context}"] += Secured cluster services + +//page will need updates - see ROX-29608 +Secured cluster services contain the following components: + +* Sensor +* Admission controller +* Collector +* Scanner (optional) +* Scanner V4 (optional) + +If you use a web proxy or firewall, you must ensure that secured clusters and Central can communicate on HTTPS port 443. + +[id="default-requirements-secured-cluster-services-sensor_{context}"] +== Sensor + +Sensor monitors your Kubernetes and {ocp} clusters. These services currently deploy in a single deployment, which handles interactions with the Kubernetes API and coordinates with the other {product-title} components. + +=== CPU and memory requirements + +The following table lists the minimum CPU and memory values required to install and run sensor on secured clusters. + +[cols="3",options="header"] +|=== +| Sensor | CPU | Memory + +| *Request* +| 2 cores +| 4 GiB + +| *Limit* +| 4 cores +| 8 GiB +|=== + +[id="default-requirements-secured-cluster-services-admission-controller_{context}"] +== Admission controller + +The Admission controller prevents users from creating workloads that violate policies you configure. + +=== CPU and memory requirements + +By default, the admission control service runs 3 replicas. The following table lists the request and limits for each replica. + +[cols="3",options="header"] +|=== +| Admission controller | CPU | Memory + +| *Request* +| 0.05 cores +| 100 MiB + +| *Limit* +| 0.5 cores +| 500 MiB +|=== + +[id="default-requirements-secured-cluster-services-collector_{context}"] +== Collector + +Collector monitors runtime activity on each node in your secured clusters as a DaemonSet. It connects to Sensor to report this information. The collector pod has three containers. The first container is collector, which monitors and reports the runtime activity on the node. The other two are compliance and node-inventory. + +=== Collection requirements + +To use the `CORE_BPF` collection method, the base kernel must support BTF, and the BTF file must be available to collector. +In general, the kernel version must be later than 5.8 (4.18 for {op-system-base} nodes) and the `CONFIG_DEBUG_INFO_BTF` configuration option must be set. + +Collector looks for the BTF file in the standard locations shown in the following list: + +.BTF file locations +[%collapsible] +==== +[source,terminal] +---- +/sys/kernel/btf/vmlinux +/boot/vmlinux-<kernel-version> +/lib/modules/<kernel-version>/vmlinux-<kernel-version> +/lib/modules/<kernel-version>/build/vmlinux +/usr/lib/modules/<kernel-version>/kernel/vmlinux +/usr/lib/debug/boot/vmlinux-<kernel-version> +/usr/lib/debug/boot/vmlinux-<kernel-version>.debug +/usr/lib/debug/lib/modules/<kernel-version>/vmlinux +---- +==== + +If any of these files exists, it is likely that the kernel has BTF support and `CORE_BPF` is configurable. + +=== CPU and memory requirements + +By default, the collector pod runs 3 containers. The following tables list the request and limits for each container and the total for each collector pod. + +==== Collector container + +[cols="3",options="header"] +|=== +| Type | CPU | Memory +| *Request* +| 0.06 cores +| 320 MiB + +| *Limit* +| 0.9 cores +| 1000 MiB +|=== + +==== Compliance container + +[cols="3",options="header"] +|=== + +| Type | CPU | Memory +| *Request* +| 0.01 cores +| 10 MiB + +| *Limit* +| 1 core +| 2000 MiB +|=== + +==== Node-inventory container + +[cols="3",options="header"] +|=== +|Type | CPU | Memory +| *Request* +| 0.01 cores +| 10 MiB + +| *Limit* +| 1 core +| 500 MiB +|=== + +==== Total collector pod requirements + +[cols="3",options="header"] +|=== +|Type | CPU | Memory +| *Request* +| 0.07 cores +| 340 MiB + +| *Limit* +| 2.75 cores +| 3500 MiB +|=== + +[id="default-requirements-secured-cluster-services-scanner_{context}"] +== Scanner + +=== CPU and memory requirements + +The requirements in this table are based on the default of 3 replicas. + +|=== +| StackRox Scanner | CPU | Memory + +| *Request* +| 3 cores +| 4500 MiB + +| *Limit* +| 6 cores +| 12 GiB +|=== + +The StackRox Scanner requires Scanner DB (PostgreSQL 15) to store data. The following table lists the minimum memory and storage values required to install and run Scanner DB. + +|=== +| Scanner DB | CPU | Memory + +| *Request* +| 0.2 cores +| 512 MiB + +| *Limit* +| 2 cores +| 4 GiB +|=== + +[id="default-requirements-secured-cluster-services-scanner-v4_{context}"] +== Scanner V4 + +Scanner V4 is optional. If Scanner V4 is installed on secured clusters, the following requirements apply. + +=== CPU, memory, and storage requirements + +=== Scanner V4 Indexer + +The requirements in this table are based on the default of 2 replicas. + +[cols="3",options="header"] +|=== +| Scanner V4 Indexer | CPU | Memory +| *Request* +| 2 cores +| 3000 MiB + +| *Limit* +| 4 cores +| 6 GiB +|=== + +=== Scanner V4 DB + +Scanner V4 requires Scanner V4 DB (PostgreSQL 15) to store data. The following table lists the minimum CPU, memory, and storage values required to install and run Scanner V4 DB. For Scanner V4 DB, a PVC is not required, but it is strongly recommended because it ensures optimal performance. + +[cols="4",options="header"] +|=== +| Scanner V4 DB | CPU | Memory | Storage +| *Request* +| 0.2 cores +| 2 GiB +| 10 GiB + +| *Limit* +| 2 cores +| 4 GiB +| 10 GiB +|=== diff --git a/modules/default-security-policies-about.adoc b/modules/default-security-policies-about.adoc new file mode 100644 index 000000000000..3f1e4b8afa59 --- /dev/null +++ b/modules/default-security-policies-about.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="default-security-policies-about_{context}"] += Default security policies + +[role="_abstract"] + +The default security policies in {product-title} provide broad coverage to identify security issues and ensure best practices for security in your environment. By configuring those policies, you can automatically prevent high-risk service deployments in your environment and respond to runtime security incidents. + +For a list of default security policies categorized by severity, see "Policy reference". diff --git a/modules/default-security-policies.adoc b/modules/default-security-policies.adoc new file mode 100644 index 000000000000..c42114313f3e --- /dev/null +++ b/modules/default-security-policies.adoc @@ -0,0 +1,20 @@ + +// Module included in the following assemblies: +// +// * operating/manage_security_policies/security-policy-reference.adoc +:_mod-docs-content-type: MODULE +[id="default-security-policies_{context}"] += Default security policies + +[role="_abstract"] + +The default security policies in {product-title} provide broad coverage to identify security issues and ensure best practices for security in your environment. By configuring those policies, you can automatically prevent high-risk service deployments in your environment and respond to runtime security incidents. + +[NOTE] +==== +The severity levels for policies in {product-title} are different from the severity levels that Red{nbsp}Hat Product Security assigns. + +The {product-title} policy severity levels are Critical, High, Medium, and Low. Red{nbsp}Hat Product Security rates vulnerability severity levels as Critical, Important, Moderate, and Low. + +While a policy's severity level and the Red{nbsp}Hat Product Security severity levels can interact, it is important to distinguish between them. For more information about the Red{nbsp}Hat Product Security severity levels, see link:https://access.redhat.com/security/updates/classification[Severity Ratings]. +==== diff --git a/modules/defining-template-for-external-log-link.adoc b/modules/defining-template-for-external-log-link.adoc deleted file mode 100644 index d8f59b3338ce..000000000000 --- a/modules/defining-template-for-external-log-link.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/customizing-the-web-console.adoc - -[id="defining-template-for-external-log-links_{context}"] -= Defining a template for an external log link - -If you are connected to a service that helps you browse your logs, but you need -to generate URLs in a particular way, then you can define a template for your -link. - -.Prerequisites - -* You must have administrator privileges. - -.Procedure - -. From *Administration* -> *Custom Resource Definitions*, click on -*ConsoleExternalLogLink*. -. Select *Instances* tab -. Click *Create Console External Log Link* and edit the file: -+ -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleExternalLogLink -metadata: - name: example -spec: - hrefTemplate: >- - https://example.com/logs?resourceName=${resourceName}&containerName=${containerName}&resourceNamespace=${resourceNamespace}&podLabels=${podLabels} - text: Example Logs ----- diff --git a/modules/delete-a-custom-role.adoc b/modules/delete-a-custom-role.adoc new file mode 100644 index 000000000000..8ce8fdfaae05 --- /dev/null +++ b/modules/delete-a-custom-role.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="delete-a-custom-role_{context}"] += Deleting a custom role + +[role="_abstract"] +From the *Access Control* view, you can delete the custom roles that you have created. + +.Prerequisites +* You must have the *Admin* role, or read and write permissions for the `Access` resource to create, modify, and delete custom roles. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Click on the *Roles and Permissions* tab. +. From the *StackRox Roles* panel, hover over the name of the role you want to delete and click the *Delete* icon. + +[NOTE] +==== +* You cannot modify `read` and `write` permissions for the default system roles. +* When you delete a custom role that has users assigned to it, all associated users transfer to the configured minimum access role. +==== diff --git a/modules/delete-acs-global-resources.adoc b/modules/delete-acs-global-resources.adoc new file mode 100644 index 000000000000..c2546706a07c --- /dev/null +++ b/modules/delete-acs-global-resources.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// * installing/uninstall-acs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="delete-acs-global-resources_{context}"] += Deleting global resources + +[role="_abstract"] +You can delete the global resources that {rh-rhacs-first} creates by using the {ocp} or Kubernetes command-line interface (CLI). + +.Procedure + +* To delete the global resources by using the {ocp} CLI, perform the following steps: + +.. Retrieve all the StackRox-related cluster roles, cluster role bindings, roles, role bindings, and PSPs, and then delete them by running the following command: ++ +[source,terminal] +---- +$ oc get clusterrole,clusterrolebinding,role,rolebinding,psp -o name | grep stackrox | xargs oc delete --wait +---- ++ +[NOTE] +==== +You might receive the `error: the server doesn't have a resource type "psp"` error message in {product-title-short} 4.4 and later versions because the pod security policies (PSPs) are deprecated. The PSPs were removed from Kubernetes in version 1.25, except for clusters with older Kubernetes versions. +==== + +.. Delete the custom security context constraints (SCCs) labeled with `app.kubernetes.io/name=stackrox` by running the following command: ++ +[source,terminal] +---- +$ oc delete scc -l "app.kubernetes.io/name=stackrox" +---- ++ +[NOTE] +==== +You might receive the `No resources found` error message in {product-title-short} 4.4 and later versions because the custom SCCs with this label are no longer used in these versions. +==== + +.. Delete the `ValidatingWebhookConfiguration` object named `stackrox` by running the following command: ++ +[source,terminal] +---- +$ oc delete ValidatingWebhookConfiguration stackrox +---- + +* To delete the global resources by using the Kubernetes CLI, perform the following steps: + +.. Retrieve all the StackRox-related cluster roles, cluster role bindings, roles, role bindings, and PSPs, and then delete them by running the following command: ++ +[source,terminal] +---- +$ kubectl get clusterrole,clusterrolebinding,role,rolebinding,psp -o name | grep stackrox | xargs kubectl delete --wait +---- ++ +[NOTE] +==== +You might receive the `error: the server doesn't have a resource type "psp"` error message in {product-title-short} 4.4 and later versions because the pod security policies (PSPs) are deprecated. The PSPs were removed from Kubernetes in version 1.25, except for clusters with older Kubernetes versions. +==== + +.. Delete the `ValidatingWebhookConfiguration` object named `stackrox` by running the following command: ++ +[source,terminal] +---- +$ kubectl delete ValidatingWebhookConfiguration stackrox +---- \ No newline at end of file diff --git a/modules/delete-acs-label-annotation.adoc b/modules/delete-acs-label-annotation.adoc new file mode 100644 index 000000000000..aa4374c766ff --- /dev/null +++ b/modules/delete-acs-label-annotation.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * installing/uninstall-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="delete-acs-label-annotation_{context}"] += Deleting labels and annotations + +[role="_abstract"] +You can delete the labels and annotations that {product-title} creates, by using the {ocp} or Kubernetes command-line interface. + +.Procedure +* Delete labels and annotations: +** On {ocp}: ++ +[source,terminal] +---- +$ for namespace in $(oc get ns | tail -n +2 | awk '{print $1}'); do oc label namespace $namespace namespace.metadata.stackrox.io/id-; oc label namespace $namespace namespace.metadata.stackrox.io/name-; oc annotate namespace $namespace modified-by.stackrox.io/namespace-label-patcher-; done +---- +** On Kubernetes: ++ +[source,terminal] +---- +$ for namespace in $(kubectl get ns | tail -n +2 | awk '{print $1}'); do kubectl label namespace $namespace namespace.metadata.stackrox.io/id-; kubectl label namespace $namespace namespace.metadata.stackrox.io/name-; kubectl annotate namespace $namespace modified-by.stackrox.io/namespace-label-patcher-; done +---- diff --git a/modules/delete-acs-namespace.adoc b/modules/delete-acs-namespace.adoc new file mode 100644 index 000000000000..330fc7b884ea --- /dev/null +++ b/modules/delete-acs-namespace.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * installing/uninstall-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="delete-acs-namespace_{context}"] += Deleting namespace + +[role="_abstract"] +You can delete the namespace that {product-title} creates by using the {ocp} or Kubernetes command-line interface. + +.Procedure +* Delete the `stackrox` namespace: +** On {ocp}: ++ +[source,terminal] +---- +$ oc delete namespace stackrox +---- +** On Kubernetes: ++ +[source,terminal] +---- +$ kubectl delete namespace stackrox +---- + +[NOTE] +==== +If you installed {product-title-short} in a different namespace, use the name of that namespace in the `delete` command. +==== diff --git a/modules/delete-all-autogenerated-policies-ng20.adoc b/modules/delete-all-autogenerated-policies-ng20.adoc new file mode 100644 index 000000000000..225f9253dab1 --- /dev/null +++ b/modules/delete-all-autogenerated-policies-ng20.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="delete-all-autogenerated-policies-ng20_{context}"] += Deleting all policies autogenerated in the network graph + +[role="_abstract"] +You can delete all automatically generated policies from your cluster that you have created by using {product-title-short}. + +.Procedure + +* Run the following command: ++ +[source,terminal] +---- +$ oc get ns -o jsonpath='{.items[*].metadata.name}' | \ +xargs -n 1 oc delete networkpolicies -l \ +'network-policy-generator.stackrox.io/generated=true' -n <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + diff --git a/modules/delete-generated-policies-ng20.adoc b/modules/delete-generated-policies-ng20.adoc new file mode 100644 index 000000000000..b009c6b79eea --- /dev/null +++ b/modules/delete-generated-policies-ng20.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="delete-generated-policies-ng20_{context}"] += Reverting to a previously applied policy in the network graph + +[role="_abstract"] +You can remove a policy and revert to a previously applied policy. + +.Procedure +. In the {product-title-short} portal, go to *Network Graph*. +. Select a cluster name from the menu on the top bar. +. Select one or more namespaces and deployments. +. Select *Simulate network policy*. +. Select *View active YAMLS*. +. From the *Actions* menu, select *Revert rules to previously applied YAML*. ++ +[WARNING] +==== +Directly applying network policies might cause problems for running applications. +Always download and test the network policies in a development environment or test clusters before applying them to production workloads. +==== diff --git a/modules/delete-kn-trigger.adoc b/modules/delete-kn-trigger.adoc deleted file mode 100644 index ace30d8990e4..000000000000 --- a/modules/delete-kn-trigger.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * /serverless/event_workflows/serverless-using-brokers.adoc - -[id="delete-kn-trigger_{context}"] -= Deleting a trigger using `kn` - -.Procedure - -* Delete a trigger: -+ -[source,terminal] ----- -$ kn trigger delete <trigger_name> ----- - -.Verification - -. List existing triggers: -+ -[source,terminal] ----- -$ kn trigger list ----- - -. Verify that the trigger no longer exists: -+ -.Example output -[source,terminal] ----- -No triggers found. ----- diff --git a/modules/deleting-a-namespace-using-the-web-console.adoc b/modules/deleting-a-namespace-using-the-web-console.adoc deleted file mode 100644 index 24d23e66a156..000000000000 --- a/modules/deleting-a-namespace-using-the-web-console.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/uninstalling-virt.adoc - -[id="deleting-a-namespace-using-the-web-console_{context}"] -= Deleting a namespace using the web console - -You can delete a namespace by using the {product-title} web console. - -[NOTE] -==== -If you do not have permissions to delete the namespace, the *Delete Namespace* -option is not available. -==== - -.Procedure - -. Navigate to *Administration* -> *Namespaces*. - -. Locate the namespace that you want to delete in the list of namespaces. - -. On the far right side of the namespace listing, select *Delete Namespace* from the -Options menu {kebab}. - -. When the *Delete Namespace* pane opens, enter the name of the namespace that -you want to delete in the field. - -. Click *Delete*. diff --git a/modules/deleting-a-project-using-the-CLI.adoc b/modules/deleting-a-project-using-the-CLI.adoc deleted file mode 100644 index 9e011dd5b6da..000000000000 --- a/modules/deleting-a-project-using-the-CLI.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="deleting-a-project-using-the-CLI_{context}"] -= Deleting a project using the CLI - -When you delete a project, the server updates the project status to -*Terminating* from *Active*. Then, the server clears all content from a project -that is in the *Terminating* state before finally removing the project. While a -project is in *Terminating* status, you cannot add new content to the project. -Projects can be deleted from the CLI or the web console. - -.Procedure - -. Run: -+ -[source,terminal] ----- -$ oc delete project <project_name> ----- diff --git a/modules/deleting-a-project-using-the-web-console.adoc b/modules/deleting-a-project-using-the-web-console.adoc deleted file mode 100644 index 0c73a4c827ea..000000000000 --- a/modules/deleting-a-project-using-the-web-console.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/projects/working-with-projects.adoc - -[id="deleting-a-project-using-the-web-console_{context}"] -= Deleting a project using the web console - -You can delete a project by using the {product-title} web console. - -[NOTE] -==== -If you do not have permissions to delete the project, the *Delete Project* -option is not available. -==== - -.Procedure - -. Navigate to *Home* -> *Projects*. - -. Locate the project that you want to delete from the list of projects. - -. On the far right side of the project listing, select *Delete Project* from the -Options menu {kebab}. - -. When the *Delete Project* pane opens, enter the name of the project that -you want to delete in the field. - -. Click *Delete*. \ No newline at end of file diff --git a/modules/deleting-cluster-integration.adoc b/modules/deleting-cluster-integration.adoc new file mode 100644 index 000000000000..723dddb809c5 --- /dev/null +++ b/modules/deleting-cluster-integration.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * cli/managing-secured-clusters.adoc +:_mod-docs-content-type: PROCEDURE +[id="deleting-cluster-integration_{context}"] += Deleting cluster integration + +.Procedure + +* Before deleting the cluster, ensure you have the correct cluster name that you want to remove from Central: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl cluster delete --name=_<cluster_name>_ +---- ++ +[IMPORTANT] +==== +Deleting the cluster integration does not remove the {product-title-short} services running in the cluster, depending on the installation method. +You can remove the services by running the `delete-sensor.sh` script from the Sensor installation bundle. +==== \ No newline at end of file diff --git a/modules/deleting-pingsource-kn.adoc b/modules/deleting-pingsource-kn.adoc deleted file mode 100644 index e06792abe6b2..000000000000 --- a/modules/deleting-pingsource-kn.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-pingsource.adoc - -[id="deleting-pingsource-kn_{context}"] -= Deleting a ping source by using the Knative CLI - -The following procedure describes how to delete a ping source using the `kn` CLI. - -* Delete the ping source: -+ -[source,terminal] ----- -$ kn delete pingsources.sources.knative.dev <ping_source_name> ----- diff --git a/modules/deleting-pingsource-yaml.adoc b/modules/deleting-pingsource-yaml.adoc deleted file mode 100644 index cb31391b3baa..000000000000 --- a/modules/deleting-pingsource-yaml.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-pingsource.adoc - -[id="deleting-pingsource-yaml_{context}"] -= Deleting a ping source that was created by using YAML - -The following procedure describes how to delete a ping source that was created by using YAML. - -.Procedure - -* Delete the ping source: -+ -[source,terminal] ----- -$ oc delete -f <ping_source_yaml_filename> ----- -+ -.Example command -[source,terminal] ----- -$ oc delete -f ping-source.yaml ----- diff --git a/modules/deleting-wmco-namespace.adoc b/modules/deleting-wmco-namespace.adoc deleted file mode 100644 index f2bf8a5de420..000000000000 --- a/modules/deleting-wmco-namespace.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/disabling-windows-container-workloads.adoc - -[id="deleting-wmco-namespace_{context}"] -= Deleting the Windows Machine Config Operator namespace - -You can delete the namespace that was generated for the Windows Machine Config Operator (WMCO) by default. - -.Prerequisites - -* The WMCO is removed from your cluster. - -.Procedure - -. Remove all Windows workloads that were created in the `openshift-windows-machine-config-operator` namespace: -+ -[source,terminal] ----- -$ oc delete --all pods --namespace=openshift-windows-machine-config-operator ----- - -. Verify that all pods in the `openshift-windows-machine-config-operator` namespace are deleted or are reporting a terminating state: -+ -[source,terminal] ----- -$ oc get pods --namespace openshift-windows-machine-config-operator ----- - -. Delete the `openshift-windows-machine-config-operator` namespace: -+ -[source,terminal] ----- -$ oc delete namespace openshift-windows-machine-config-operator ----- diff --git a/modules/deploy-red-hat-openshift-container-storage.adoc b/modules/deploy-red-hat-openshift-container-storage.adoc deleted file mode 100644 index adcedaef0e93..000000000000 --- a/modules/deploy-red-hat-openshift-container-storage.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/storage-configuration.adoc - -[options="header",cols="1,1"] -|=== - -|If you are looking for Red Hat OpenShift Container Storage information about... -|See the following Red Hat OpenShift Container Storage documentation: - -|What’s new, known issues, notable bug fixes, and Technology Previews -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/4.5_release_notes/[OpenShift Container Storage 4.5 Release Notes] - -|Supported workloads, layouts, hardware and software requirements, sizing and scaling recommendations -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/planning_your_deployment/index[Planning your OpenShift Container Storage 4.5 deployment] - -|Instructions on preparing to deploy when your environment is not directly connected to the internet -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/preparing_to_deploy_in_a_disconnected_environment/index[Preparing to deploy OpenShift Container Storage 4.5 in a disconnected environment] - -|Instructions on deploying OpenShift Container Storage to use an external Red Hat Ceph Storage cluster -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/deploying_openshift_container_storage_in_external_mode/index[Deploying OpenShift Container Storage 4.5 in external mode] - -|Instructions on deploying OpenShift Container Storage to local storage on bare metal infrastructure -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/deploying_openshift_container_storage_using_bare_metal_infrastructure/index[Deploying OpenShift Container Storage 4.5 using bare metal infrastructure] - -|Instructions on deploying OpenShift Container Storage on Red Hat OpenShift Container Platform VMWare vSphere clusters -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/deploying_openshift_container_storage_on_vmware_vsphere/index[Deploying OpenShift Container Storage 4.5 on VMWare vSphere] - -|Instructions on deploying OpenShift Container Storage using Amazon Web Services for local or cloud storage -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/deploying_openshift_container_storage_using_amazon_web_services/index[Deploying OpenShift Container Storage 4.5 using Amazon Web Services] - -|Instructions on deploying and managing OpenShift Container Storage on existing Red Hat OpenShift Container Platform Google Cloud clusters -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/deploying_and_managing_openshift_container_storage_using_google_cloud/index[Deploying and managing OpenShift Container Storage 4.5 using Google Cloud] - -|Instructions on deploying and managing OpenShift Container Storage on existing Red Hat OpenShift Container Platform Azure clusters -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/deploying_and_managing_openshift_container_storage_using_microsoft_azure/index[Deploying and managing OpenShift Container Storage 4.5 using Microsoft Azure] - -|Managing a Red Hat OpenShift Container Storage 4.5 cluster -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/managing_openshift_container_storage/index[Managing OpenShift Container Storage 4.5] - -|Monitoring a Red Hat OpenShift Container Storage 4.5 cluster -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/monitoring_openshift_container_storage/index[Monitoring Red Hat OpenShift Container Storage 4.5] - -|Resolve issues encountered during operations -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.5/html/troubleshooting_openshift_container_storage/index[Troubleshooting OpenShift Container Storage 4.5] - -|Migrating your {product-title} cluster from version 3 to version 4 -|link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.5/html/migration/index[Migration] - -|=== diff --git a/modules/deploying-resource.adoc b/modules/deploying-resource.adoc deleted file mode 100644 index 61f018c6dbe8..000000000000 --- a/modules/deploying-resource.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Be sure to set the :FeatureName: and :FeatureResourceName: values in each assembly on the lines before -// the include statement for this module. For example, add the following lines to the assembly: -// :FeatureName: cluster autoscaler -// :FeatureResourceName: ClusterAutoscaler -// -// Module included in the following assemblies: -// -// * machine_management/applying-autoscaling.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="{FeatureResourceName}-deploying_{context}"] -= Deploying the {FeatureName} - -To deploy the {FeatureName}, you create an instance of the `{FeatureResourceName}` resource. - -.Procedure - -. Create a YAML file for the `{FeatureResourceName}` resource that contains the customized resource definition. - -. Create the resource in the cluster: -+ -[source,terminal] ----- -$ oc create -f <filename>.yaml <1> ----- -<1> `<filename>` is the name of the resource file that you customized. - -// Undefine attributes, so that any mistakes are easily spotted -:!FeatureName: -:!FeatureResourceName: diff --git a/modules/deployments-ab-testing-lb.adoc b/modules/deployments-ab-testing-lb.adoc deleted file mode 100644 index b38b4bd0aeb5..000000000000 --- a/modules/deployments-ab-testing-lb.adoc +++ /dev/null @@ -1,268 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/route-based-deployment-strategies.adoc - -[id="deployments-ab-testing-lb_{context}"] -= Load balancing for A/B testing - -The user sets up a route with multiple services. Each service handles a version of the application. - -Each service is assigned a `weight` and the portion of requests to each service is the `service_weight` divided by the `sum_of_weights`. The `weight` for each service is distributed to the service's endpoints so that the sum of the endpoint `weights` is the service `weight`. - -The route can have up to four services. The `weight` for the service can be between `0` and `256`. When the `weight` is `0`, the service does not participate in load-balancing but continues to serve existing persistent connections. When the service `weight` is not `0`, each endpoint has a minimum `weight` of `1`. Because of this, a service with a lot of endpoints can end up with higher `weight` than intended. In this case, reduce the number of pods to get the expected load balance `weight`. - -//// -See the -xref:../../architecture/networking/routes.adoc#alternateBackends[Alternate -Backends and Weights] section for more information. - -The web console allows users to set the weighting and show balance between them: - -weighting.png[Visualization of Alternate Back Ends in the Web Console] -//// - -.Procedure - -To set up the A/B environment: - -. Create the two applications and give them different names. Each creates a `DeploymentConfig` object. The applications are versions of the same program; one is usually the current production version and the other the proposed new version. -.. Create the first application. The following example creates an application called `ab-example-a`: -+ -[source,terminal] ----- -$ oc new-app openshift/deployment-example --name=ab-example-a ----- -+ -.. Create the second application: -+ -[source,terminal] ----- -$ oc new-app openshift/deployment-example --name=ab-example-b ----- -+ -Both applications are deployed and services are created. - -. Make the application available externally via a route. At this point, you can expose either. It can be convenient to expose the current production version first and later modify the route to add the new version. -+ -[source,terminal] ----- -$ oc expose svc/ab-example-a ----- -+ -Browse to the application at `ab-example-a.<project>.<router_domain>` to verify that you see the expected version. - -. When you deploy the route, the router balances the traffic according to the `weights` specified for the services. At this point, there is a single service with default `weight=1` so all requests go to it. Adding the other service as an `alternateBackends` and adjusting the `weights` brings the A/B setup to life. This can be done by the `oc set route-backends` command or by editing the route. -+ -Setting the `oc set route-backend` to `0` means the service does not participate in load-balancing, but continues to serve existing persistent connections. -+ -[NOTE] -==== -Changes to the route just change the portion of traffic to the various services. You might have to scale the deployment to adjust the number of pods to handle the anticipated loads. -==== -+ -To edit the route, run: -+ -[source,terminal] ----- -$ oc edit route <route_name> ----- -+ -.Example output -[source,terminal] ----- -... -metadata: - name: route-alternate-service - annotations: - haproxy.router.openshift.io/balance: roundrobin -spec: - host: ab-example.my-project.my-domain - to: - kind: Service - name: ab-example-a - weight: 10 - alternateBackends: - - kind: Service - name: ab-example-b - weight: 15 -... ----- - -[id="deployments-ab-testing-lb-web_{context}"] -== Managing weights of an existing route using the web console - -.Procedure - -. Navigate to the *Networking* -> *Routes* page. - -. Click the Actions menu {kebab} next to the route you want to edit and select *Edit Route*. - -. Edit the YAML file. Update the `weight` to be an integer between `0` and `256` that specifies the relative weight of the target against other target reference objects. The value `0` suppresses requests to this back end. The default is `100`. Run `oc explain routes.spec.alternateBackends` for more information about the options. - -. Click *Save*. - -[id="deployments-ab-testing-lb-web-new-route_{context}"] -== Managing weights of an new route using the web console - -. Navigate to the *Networking* -> *Routes* page. - -. Click *Create Route*. - -. Enter the route *Name*. - -. Select the *Service*. - -. Click *Add Alternate Service*. - -. Enter a value for *Weight* and *Alternate Service Weight*. Enter a number between `0` and `255` that depicts relative weight compared with other targets. The default is `100`. - -. Select the *Target Port*. - -. Click *Create*. - -[id="deployments-ab-testing-lb-cli_{context}"] -== Managing weights using the CLI - -.Procedure - -. To manage the services and corresponding weights load balanced by the route, use the `oc set route-backends` command: -+ -[source,terminal] ----- -$ oc set route-backends ROUTENAME \ - [--zero|--equal] [--adjust] SERVICE=WEIGHT[%] [...] [options] ----- -+ -For example, the following sets `ab-example-a` as the primary service with `weight=198` and `ab-example-b` as the first alternate service with a `weight=2`: -+ -[source,terminal] ----- -$ oc set route-backends ab-example ab-example-a=198 ab-example-b=2 ----- -+ -This means 99% of traffic is sent to service `ab-example-a` and 1% to service `ab-example-b`. -+ -This command does not scale the deployment. You might be required to do so to have enough pods to handle the request load. - -. Run the command with no flags to verify the current configuration: -+ -[source,terminal] ----- -$ oc set route-backends ab-example ----- -+ -.Example output -[source,terminal] ----- -NAME KIND TO WEIGHT -routes/ab-example Service ab-example-a 198 (99%) -routes/ab-example Service ab-example-b 2 (1%) ----- - -. To alter the weight of an individual service relative to itself or to the primary service, use the `--adjust` flag. Specifying a percentage adjusts the service relative to either the primary or the first alternate (if you specify the primary). If there are other backends, their weights are kept proportional to the changed. -+ -The following example alters the weight of `ab-example-a` and `ab-example-b` services: -+ -[source,terminal] ----- -$ oc set route-backends ab-example --adjust ab-example-a=200 ab-example-b=10 ----- -+ -Alternatively, alter the weight of a service by specifying a percentage: -+ -[source,terminal] ----- -$ oc set route-backends ab-example --adjust ab-example-b=5% ----- -+ -By specifying `+` before the percentage declaration, you can adjust a weighting relative to the current setting. For example: -+ -[source,terminal] ----- -$ oc set route-backends ab-example --adjust ab-example-b=+15% ----- -+ -The `--equal` flag sets the `weight` of all services to `100`: -+ -[source,terminal] ----- -$ oc set route-backends ab-example --equal ----- -+ -The `--zero` flag sets the `weight` of all services to `0`. All requests then return with a 503 error. -+ -[NOTE] -==== -Not all routers may support multiple or weighted backends. -==== - -[id="deployments-ab-one-service-multi-dc_{context}"] -== One service, multiple `DeploymentConfig` objects - -.Procedure - -. Create a new application, adding a label `ab-example=true` that will be common to all shards: -+ -[source,terminal] ----- -$ oc new-app openshift/deployment-example --name=ab-example-a --as-deployment-config=true --labels=ab-example=true --env=SUBTITLE\=shardA -$ oc delete svc/ab-example-a ----- -+ -The application is deployed and a service is created. This is the first shard. - -. Make the application available via a route, or use the service IP directly: -+ -[source,terminal] ----- -$ oc expose deploymentconfig ab-example-a --name=ab-example --selector=ab-example\=true -$ oc expose service ab-example ----- - -. Browse to the application at `ab-example-<project_name>.<router_domain>` to verify you see the `v1` image. - -. Create a second shard based on the same source image and label as the first shard, but with a different tagged version and unique environment variables: -+ -[source,terminal] ----- -$ oc new-app openshift/deployment-example:v2 \ - --name=ab-example-b --labels=ab-example=true \ - SUBTITLE="shard B" COLOR="red" --as-deployment-config=true -$ oc delete svc/ab-example-b ----- - -. At this point, both sets of pods are being served under the route. However, because both browsers (by leaving a connection open) and the router (by default, through a cookie) attempt to preserve your connection to a back-end server, you might not see both shards being returned to you. -+ -To force your browser to one or the other shard: - -.. Use the `oc scale` command to reduce replicas of `ab-example-a` to `0`. -+ -[source,terminal] ----- -$ oc scale dc/ab-example-a --replicas=0 ----- -+ -Refresh your browser to show `v2` and `shard B` (in red). - -.. Scale `ab-example-a` to `1` replica and `ab-example-b` to `0`: -+ -[source,terminal] ----- -$ oc scale dc/ab-example-a --replicas=1; oc scale dc/ab-example-b --replicas=0 ----- -+ -Refresh your browser to show `v1` and `shard A` (in blue). - -. If you trigger a deployment on either shard, only the pods in that shard are affected. You can trigger a deployment by changing the `SUBTITLE` environment variable in either `DeploymentConfig` object: -+ -[source,terminal] ----- -$ oc edit dc/ab-example-a ----- -+ -or -+ -[source,terminal] ----- -$ oc edit dc/ab-example-b ----- diff --git a/modules/deployments-ab-testing.adoc b/modules/deployments-ab-testing.adoc deleted file mode 100644 index f0f4ea28202a..000000000000 --- a/modules/deployments-ab-testing.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/route-based-deployment-strategies.adoc - -[id="deployments-ab-testing_{context}"] -= A/B deployments - -The A/B deployment strategy lets you try a new version of the application in a -limited way in the production environment. You can specify that the production -version gets most of the user requests while a limited fraction of requests go -to the new version. - -Because you control the portion of requests to each version, as testing -progresses you can increase the fraction of requests to the new version and -ultimately stop using the previous version. As you adjust the request load on -each version, the number of pods in each service might have to be scaled as well -to provide the expected performance. - -In addition to upgrading software, you can use this feature to experiment with -versions of the user interface. Since some users get the old version and some -the new, you can evaluate the user's reaction to the different versions to -inform design decisions. - -For this to be effective, both the old and new versions must be similar enough -that both can run at the same time. This is common with bug fix releases and -when new features do not interfere with the old. The versions require N-1 -compatibility to properly work together. - -{product-title} supports N-1 compatibility through the web console as well as -the CLI. diff --git a/modules/deployments-accessing-private-repos.adoc b/modules/deployments-accessing-private-repos.adoc deleted file mode 100644 index a11009f93fb0..000000000000 --- a/modules/deployments-accessing-private-repos.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-accessing-private-repos_{context}"] -= Accessing private repositories from `DeploymentConfig` objects - -You can add a secret to your `DeploymentConfig` object so that it can access images from a private repository. This procedure shows the {product-title} web console method. - -.Procedure - -. Create a new project. - -. From the *Workloads* page, create a secret that contains credentials for accessing a private image repository. - -. Create a `DeploymentConfig` object. - -. On the `DeploymentConfig` object editor page, set the *Pull Secret* and save your changes. diff --git a/modules/deployments-assigning-pods-to-nodes.adoc b/modules/deployments-assigning-pods-to-nodes.adoc deleted file mode 100644 index 7d92d5e0f542..000000000000 --- a/modules/deployments-assigning-pods-to-nodes.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-assigning-pods-to-nodes_{context}"] -= Assigning pods to specific nodes - -You can use node selectors in conjunction with labeled nodes to control pod -placement. - -Cluster administrators can set the default node selector for a project in order -to restrict pod placement to specific nodes. As a developer, you can set a node -selector on a `Pod` configuration to restrict nodes even further. - -.Procedure - -. To add a node selector when creating a pod, edit the `Pod` configuration, and add -the `nodeSelector` value. This can be added to a single `Pod` configuration, or in -a `Pod` template: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -spec: - nodeSelector: - disktype: ssd -... ----- -+ -Pods created when the node selector is in place are assigned to nodes with the -specified labels. The labels specified here are used in conjunction with the -labels added by a cluster administrator. -+ -For example, if a project has the `type=user-node` and `region=east` labels -added to a project by the cluster administrator, and you add the above -`disktype: ssd` label to a pod, the pod is only ever scheduled on nodes that -have all three labels. -+ -[NOTE] -==== -Labels can only be set to one value, so setting a node selector of `region=west` -in a `Pod` configuration that has `region=east` as the administrator-set default, -results in a pod that will never be scheduled. -==== diff --git a/modules/deployments-blue-green.adoc b/modules/deployments-blue-green.adoc deleted file mode 100644 index 07f4e9c0cc00..000000000000 --- a/modules/deployments-blue-green.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/route-based-deployment-strategies.adoc - -[id="deployments-blue-green_{context}"] -= Blue-green deployments - -Blue-green deployments involve running two versions of an application at the same time and moving traffic from the in-production version (the blue version) to the newer version (the green version). You can use a rolling strategy or switch services in a route. - -Because many applications depend on persistent data, you must have an application that supports _N-1 compatibility_, which means it shares data and implements live migration between the database, store, or disk by creating two copies of the data layer. - -Consider the data used in testing the new version. If it is the production data, a bug in the new version can break the production version. - -[id="deployments-blue-green-setting-up_{context}"] -== Setting up a blue-green deployment - -Blue-green deployments use two `DeploymentConfig` objects. Both are running, and the one in production depends on the service the route specifies, with each `DeploymentConfig` object exposed to a different service. - -[NOTE] -==== -Routes are intended for web (HTTP and HTTPS) traffic, so this technique is best suited for web applications. -==== - -You can create a new route to the new version and test it. When ready, change the service in the production route to point to the new service and the new (green) version is live. - -If necessary, you can roll back to the older (blue) version by switching the service back to the previous version. - -.Procedure - -. Create two independent application components. -.. Create a copy of the example application running the `v1` image under the `example-blue` service: -+ -[source,terminal] ----- -$ oc new-app openshift/deployment-example:v1 --name=example-blue ----- -+ -.. Create a second copy that uses the `v2` image under the `example-green` service: -+ -[source,terminal] ----- -$ oc new-app openshift/deployment-example:v2 --name=example-green ----- - -. Create a route that points to the old service: -+ -[source,terminal] ----- -$ oc expose svc/example-blue --name=bluegreen-example ----- - -. Browse to the application at `example-blue.<project>.<router_domain>` to verify you see the `v1` image. - -. Edit the route and change the service name to `example-green`: -+ -[source,terminal] ----- -$ oc patch route/bluegreen-example -p '{"spec":{"to":{"name":"example-green"}}}' ----- - -. To verify that the route has changed, refresh the browser until you see the `v2` image. diff --git a/modules/deployments-canary-deployments.adoc b/modules/deployments-canary-deployments.adoc deleted file mode 100644 index 6ac3331f5571..000000000000 --- a/modules/deployments-canary-deployments.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/deployment-strategies.adoc - -[id="deployments-canary-deployments_{context}"] -= Canary deployments - -All rolling deployments in {product-title} are _canary deployments_; a new version (the canary) is tested before all of the old instances are replaced. If the readiness check never succeeds, the canary instance is removed and the `DeploymentConfig` object will be automatically rolled back. - -The readiness check is part of the application code and can be as sophisticated as necessary to ensure the new instance is ready to be used. If you must implement more complex checks of the application (such as sending real user workloads to the new instance), consider implementing a custom deployment or using a blue-green deployment strategy. diff --git a/modules/deployments-comparing-deploymentconfigs.adoc b/modules/deployments-comparing-deploymentconfigs.adoc deleted file mode 100644 index a5d7c1da8857..000000000000 --- a/modules/deployments-comparing-deploymentconfigs.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/what-deployments-are.adoc - -[id="deployments-comparing-deploymentconfigs_{context}"] -= Comparing `Deployment` and `DeploymentConfig` objects - -Both Kubernetes `Deployment` objects and {product-title}-provided `DeploymentConfig` objects are supported in {product-title}; however, it is recommended to use `Deployment` objects unless you need a specific feature or behavior provided by `DeploymentConfig` objects. - -The following sections go into more detail on the differences between the two object types to further help you decide which type to use. - -[id="deployments-design_{context}"] -== Design - -One important difference between `Deployment` and `DeploymentConfig` objects is the properties of the link:https://en.wikipedia.org/wiki/CAP_theorem[CAP theorem] that each design has chosen for the rollout process. `DeploymentConfig` objects prefer consistency, whereas `Deployments` objects take availability over consistency. - -For `DeploymentConfig` objects, if a node running a deployer pod goes down, it will not get replaced. The process waits until the node comes back online or is manually deleted. Manually deleting the node also deletes the corresponding pod. This means that you can not delete the pod to unstick the rollout, as the kubelet is responsible for deleting the associated pod. - -However, deployment rollouts are driven from a controller manager. The controller manager runs in high availability mode on masters and uses leader election algorithms to value availability over consistency. During a failure it is possible for other masters to act on the same deployment at the same time, but this issue will be reconciled shortly after the failure occurs. - -[id="delpoymentconfigs-specific-features_{context}"] -== `DeploymentConfig` object-specific features - -[discrete] -==== Automatic rollbacks - -Currently, deployments do not support automatically rolling back to the last successfully deployed replica set in case of a failure. - -[discrete] -==== Triggers - -Deployments have an implicit config change trigger in that every change in the pod template of a deployment automatically triggers a new rollout. -If you do not want new rollouts on pod template changes, pause the deployment: - -[source,terminal] ----- -$ oc rollout pause deployments/<name> ----- - -[discrete] -==== Lifecycle hooks - -Deployments do not yet support any lifecycle hooks. - -[discrete] -==== Custom strategies - -Deployments do not support user-specified custom deployment strategies yet. - -[id="delpoyments-specific-features_{context}"] -== Deployment-specific features - -[discrete] -==== Rollover - -The deployment process for `Deployment` objects is driven by a controller loop, in contrast to `DeploymentConfig` objects which use deployer pods for every new rollout. This means that the `Deployment` object can have as many active replica sets as possible, and eventually the deployment controller will scale down all old replica sets and scale up the newest one. - -`DeploymentConfig` objects can have at most one deployer pod running, otherwise multiple deployers end up conflicting while trying to scale up what they think should be the newest replication controller. Because of this, only two replication controllers can be active at any point in time. Ultimately, this translates to faster rapid rollouts for `Deployment` objects. - -[discrete] -==== Proportional scaling - -Because the deployment controller is the sole source of truth for the sizes of new and old replica sets owned by a deployment, it is able to scale ongoing rollouts. Additional replicas are distributed proportionally based on the size of each replica set. - -Deployments cannot be scaled when a rollout is ongoing because the controller will end up having issues with the deployer process about the size of the new replication controller. - -[discrete] -==== Pausing mid-rollout - -Deployments can be paused at any point in time, meaning you can also pause ongoing rollouts. On the other hand, you cannot pause deployer pods -currently, so if you try to pause a deployment in the middle of a rollout, the deployer process will not be affected and will continue until it finishes. diff --git a/modules/deployments-creating-rolling-deployment.adoc b/modules/deployments-creating-rolling-deployment.adoc deleted file mode 100644 index e6a0162f8eb1..000000000000 --- a/modules/deployments-creating-rolling-deployment.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/deployment-strategies.adoc - -[id="deployments-creating-rolling-deployment_{context}"] -= Creating a rolling deployment - -Rolling deployments are the default type in {product-title}. You can create a rolling deployment using the CLI. - -.Procedure - -. Create an application based on the example deployment images found in link:https://hub.docker.com/r/openshift/deployment-example/[Docker Hub]: -+ -[source,terminal] ----- -$ oc new-app openshift/deployment-example ----- - -. If you have the router installed, make the application available via a route or use the service IP directly. -+ -[source,terminal] ----- -$ oc expose svc/deployment-example ----- - -. Browse to the application at `deployment-example.<project>.<router_domain>` to verify you see the `v1` image. - -. Scale the `DeploymentConfig` object up to three replicas: -+ -[source,terminal] ----- -$ oc scale dc/deployment-example --replicas=3 ----- - -. Trigger a new deployment automatically by tagging a new version of the example as the `latest` tag: -+ -[source,terminal] ----- -$ oc tag deployment-example:v2 deployment-example:latest ----- - -. In your browser, refresh the page until you see the `v2` image. - -. When using the CLI, the following command shows how many pods are on version 1 and how many are on version 2. In the web console, the pods are progressively added to v2 and removed from v1: -+ -[source,terminal] ----- -$ oc describe dc deployment-example ----- - -During the deployment process, the new replication controller is incrementally scaled up. After the new pods are marked as `ready` (by passing their readiness check), the deployment process continues. - -If the pods do not become ready, the process aborts, and the deployment rolls back to its previous version. diff --git a/modules/deployments-custom-strategy.adoc b/modules/deployments-custom-strategy.adoc deleted file mode 100644 index 66dcb82cc8b6..000000000000 --- a/modules/deployments-custom-strategy.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/deployment-strategies.adoc - -[id="deployments-custom-strategy_{context}"] -= Custom strategy - -The custom strategy allows you to provide your own deployment behavior. - -.Example custom strategy definition -[source,yaml] ----- -strategy: - type: Custom - customParams: - image: organization/strategy - command: [ "command", "arg1" ] - environment: - - name: ENV_1 - value: VALUE_1 ----- - -In the above example, the `organization/strategy` container image provides the deployment behavior. The optional `command` array overrides any `CMD` directive specified in the image's `Dockerfile`. The optional environment variables provided are added to the execution environment of the strategy process. - -Additionally, {product-title} provides the following environment variables to the deployment process: - -[cols="4,8",options="header"] -|=== -|Environment variable |Description - -.^|`OPENSHIFT_DEPLOYMENT_NAME` -|The name of the new deployment, a replication controller. - -.^|`OPENSHIFT_DEPLOYMENT_NAMESPACE` -|The name space of the new deployment. -|=== - -The replica count of the new deployment will initially be zero. The responsibility of the strategy is to make the new deployment active using the -logic that best serves the needs of the user. - -Alternatively, use the `customParams` object to inject the custom deployment logic into the existing deployment strategies. Provide a custom shell script logic and call the `openshift-deploy` binary. Users do not have to supply their custom deployer container image; in this case, the default {product-title} deployer image is used instead: - -[source,yaml] ----- -strategy: - type: Rolling - customParams: - command: - - /bin/sh - - -c - - | - set -e - openshift-deploy --until=50% - echo Halfway there - openshift-deploy - echo Complete ----- - -This results in following deployment: - -[source,terminal] ----- -Started deployment #2 ---> Scaling up custom-deployment-2 from 0 to 2, scaling down custom-deployment-1 from 2 to 0 (keep 2 pods available, don't exceed 3 pods) - Scaling custom-deployment-2 up to 1 ---> Reached 50% (currently 50%) -Halfway there ---> Scaling up custom-deployment-2 from 1 to 2, scaling down custom-deployment-1 from 2 to 0 (keep 2 pods available, don't exceed 3 pods) - Scaling custom-deployment-1 down to 1 - Scaling custom-deployment-2 up to 2 - Scaling custom-deployment-1 down to 0 ---> Success -Complete ----- - -If the custom deployment strategy process requires access to the {product-title} API or the Kubernetes API the container that executes the strategy can use the service account token available inside the container for authentication. diff --git a/modules/deployments-deploymentconfigs.adoc b/modules/deployments-deploymentconfigs.adoc deleted file mode 100644 index a31e07a00ec4..000000000000 --- a/modules/deployments-deploymentconfigs.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/what-deployments-are.adoc - -[id="deployments-and-deploymentconfigs_{context}"] -= `DeploymentConfig` objects - -Building on replication controllers, {product-title} adds expanded support for the software development and deployment lifecycle with the concept of `DeploymentConfig` objects. In the simplest case, a `DeploymentConfig` object creates a new replication controller and lets it start up pods. - -However, {product-title} deployments from `DeploymentConfig` objects also provide the ability to transition from an existing deployment of an image to a new one and also define hooks to be run before or after creating the replication controller. - -The `DeploymentConfig` deployment system provides the following capabilities: - -* A `DeploymentConfig` object, which is a template for running applications. -* Triggers that drive automated deployments in response to events. -* User-customizable deployment strategies to transition from the previous version to the new version. A strategy runs inside a pod commonly referred as the deployment process. -* A set of hooks (lifecycle hooks) for executing custom behavior in different points during the lifecycle of a deployment. -* Versioning of your application to support rollbacks either manually or automatically in case of deployment failure. -* Manual replication scaling and autoscaling. - -When you create a `DeploymentConfig` object, a replication controller is created representing the `DeploymentConfig` object's pod template. If the deployment changes, a new replication controller is created with the latest pod template, and a deployment process runs to scale down the old replication controller and scale up the new one. - -Instances of your application are automatically added and removed from both service load balancers and routers as they are created. As long as your application supports graceful shutdown when it receives the `TERM` signal, you can ensure that running user connections are given a chance to complete normally. - -The {product-title} `DeploymentConfig` object defines the following details: - -. The elements of a `ReplicationController` definition. -. Triggers for creating a new deployment automatically. -. The strategy for transitioning between deployments. -. Lifecycle hooks. - -Each time a deployment is triggered, whether manually or automatically, a deployer pod manages the deployment (including scaling down the old -replication controller, scaling up the new one, and running hooks). The deployment pod remains for an indefinite amount of time after it completes the deployment to retain its logs of the deployment. When a deployment is superseded by another, the previous replication controller is retained to enable easy rollback if needed. - -.Example `DeploymentConfig` definition -[source,yaml] ----- -apiVersion: v1 -kind: DeploymentConfig -metadata: - name: frontend -spec: - replicas: 5 - selector: - name: frontend - template: { ... } - triggers: - - type: ConfigChange <1> - - imageChangeParams: - automatic: true - containerNames: - - helloworld - from: - kind: ImageStreamTag - name: hello-openshift:latest - type: ImageChange <2> - strategy: - type: Rolling <3> ----- -<1> A config change trigger causes a new deployment to be created any time the replication controller template changes. -<2> An image change trigger causes a new deployment to be created each time a new version of the backing image is available in the named image stream. -<3> The default `Rolling` strategy makes a downtime-free transition between deployments. diff --git a/modules/deployments-exec-cmd-in-container.adoc b/modules/deployments-exec-cmd-in-container.adoc deleted file mode 100644 index d792bf5c0c8c..000000000000 --- a/modules/deployments-exec-cmd-in-container.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-exe-cmd-in-container_{context}"] -= Executing commands inside a container - -You can add a command to a container, which modifies the container's start-up behavior by overruling the image's `ENTRYPOINT`. This is different from a lifecycle hook, which instead can be run once per deployment at a specified time. - -.Procedure - -. Add the `command` parameters to the `spec` field of the `DeploymentConfig` object. You can also add an `args` field, which modifies the `command` (or the `ENTRYPOINT` if `command` does not exist). -+ -[source,yaml] ----- -spec: - containers: - - - name: <container_name> - image: 'image' - command: - - '<command>' - args: - - '<argument_1>' - - '<argument_2>' - - '<argument_3>' ----- -+ -For example, to execute the `java` command with the `-jar` and `/opt/app-root/springboots2idemo.jar` arguments: -+ -[source,yaml] ----- -spec: - containers: - - - name: example-spring-boot - image: 'image' - command: - - java - args: - - '-jar' - - /opt/app-root/springboots2idemo.jar ----- diff --git a/modules/deployments-graceful-termination.adoc b/modules/deployments-graceful-termination.adoc deleted file mode 100644 index ba10afd42803..000000000000 --- a/modules/deployments-graceful-termination.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/route-based-deployment-strategies.adoc - -[id="deployments-graceful-termination_{context}"] -= Graceful termination - -{product-title} and Kubernetes give application instances time to shut down before removing them from load balancing rotations. However, applications must ensure they cleanly terminate user connections as well before they exit. - -On shutdown, {product-title} sends a `TERM` signal to the processes in the container. Application code, on receiving `SIGTERM`, stop accepting new connections. This ensures that load balancers route traffic to other active instances. The application code then waits until all open connections are closed, or gracefully terminate individual connections at the next opportunity, before exiting. - -After the graceful termination period expires, a process that has not exited is sent the `KILL` signal, which immediately ends the process. The -`terminationGracePeriodSeconds` attribute of a pod or pod template controls the graceful termination period (default 30 seconds) and can be customized per application as necessary. diff --git a/modules/deployments-kube-deployments.adoc b/modules/deployments-kube-deployments.adoc deleted file mode 100644 index 831d85a783f8..000000000000 --- a/modules/deployments-kube-deployments.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/what-deployments-are.adoc - -[id="deployments-kube-deployments_{context}"] -= Deployments - -Kubernetes provides a first-class, native API object type in {product-title} called `Deployment`. `Deployment` objects serve as a descendant of the {product-title}-specific `DeploymentConfig` object. - -Like `DeploymentConfig` objects, `Deployment` objects describe the desired state of a particular component of an application as a pod template. Deployments create replica sets, which orchestrate pod lifecycles. - -For example, the following deployment definition creates a replica set to bring up one `hello-openshift` pod: - -.Deployment definition -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: hello-openshift -spec: - replicas: 1 - selector: - matchLabels: - app: hello-openshift - template: - metadata: - labels: - app: hello-openshift - spec: - containers: - - name: hello-openshift - image: openshift/hello-openshift:latest - ports: - - containerPort: 80 ----- diff --git a/modules/deployments-lifecycle-hooks.adoc b/modules/deployments-lifecycle-hooks.adoc deleted file mode 100644 index 2067cf17453d..000000000000 --- a/modules/deployments-lifecycle-hooks.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/deployment-strategies.adoc - -[id="deployments-lifecycle-hooks_{context}"] -= Lifecycle hooks - -The rolling and recreate strategies support _lifecycle hooks_, or deployment hooks, which allow behavior to be injected into the deployment process at predefined points within the strategy: - -.Example `pre` lifecycle hook -[source,yaml] ----- -pre: - failurePolicy: Abort - execNewPod: {} <1> ----- -<1> `execNewPod` is a pod-based lifecycle hook. - -Every hook has a _failure policy_, which defines the action the strategy should take when a hook failure is encountered: - -[cols="2,8"] -|=== - -.^|`Abort` -|The deployment process will be considered a failure if the hook fails. - -.^|`Retry` -|The hook execution should be retried until it succeeds. - -.^|`Ignore` -|Any hook failure should be ignored and the deployment should proceed. -|=== - -Hooks have a type-specific field that describes how to execute the hook. Currently, pod-based hooks are the only supported hook type, specified by the `execNewPod` field. - -[discrete] -==== Pod-based lifecycle hook - -Pod-based lifecycle hooks execute hook code in a new pod derived from the template in a `DeploymentConfig` object. - -The following simplified example deployment uses the rolling strategy. Triggers and some other minor details are omitted for brevity: - -[source,yaml] ----- -kind: DeploymentConfig -apiVersion: v1 -metadata: - name: frontend -spec: - template: - metadata: - labels: - name: frontend - spec: - containers: - - name: helloworld - image: openshift/origin-ruby-sample - replicas: 5 - selector: - name: frontend - strategy: - type: Rolling - rollingParams: - pre: - failurePolicy: Abort - execNewPod: - containerName: helloworld <1> - command: [ "/usr/bin/command", "arg1", "arg2" ] <2> - env: <3> - - name: CUSTOM_VAR1 - value: custom_value1 - volumes: - - data <4> ----- -<1> The `helloworld` name refers to `spec.template.spec.containers[0].name`. -<2> This `command` overrides any `ENTRYPOINT` defined by the `openshift/origin-ruby-sample` image. -<3> `env` is an optional set of environment variables for the hook container. -<4> `volumes` is an optional set of volume references for the hook container. - -In this example, the `pre` hook will be executed in a new pod using the `openshift/origin-ruby-sample` image from the `helloworld` container. The hook pod has the following properties: - -* The hook command is `/usr/bin/command arg1 arg2`. -* The hook container has the `CUSTOM_VAR1=custom_value1` environment variable. -* The hook failure policy is `Abort`, meaning the deployment process fails if the hook fails. -* The hook pod inherits the `data` volume from the `DeploymentConfig` object pod. - -[id="deployments-setting-lifecycle-hooks_{context}"] -== Setting lifecycle hooks - -You can set lifecycle hooks, or deployment hooks, for a deployment using the CLI. - -.Procedure - -. Use the `oc set deployment-hook` command to set the type of hook you want: `--pre`, `--mid`, or `--post`. For example, to set a pre-deployment hook: -+ -[source,terminal] ----- -$ oc set deployment-hook dc/frontend \ - --pre -c helloworld -e CUSTOM_VAR1=custom_value1 \ - --volumes data --failure-policy=abort -- /usr/bin/command arg1 arg2 ----- diff --git a/modules/deployments-n1-compatibility.adoc b/modules/deployments-n1-compatibility.adoc deleted file mode 100644 index 52ad646196d2..000000000000 --- a/modules/deployments-n1-compatibility.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/route-based-deployment-strategies.adoc - -[id="deployments-n1-compatibility_{context}"] -= N-1 compatibility - -Applications that have new code and old code running at the same time must be -careful to ensure that data written by the new code can be read and handled (or -gracefully ignored) by the old version of the code. This is sometimes called -_schema evolution_ and is a complex problem. - -This can take many forms: data stored on disk, in a database, in a temporary -cache, or that is part of a user's browser session. While most web applications -can support rolling deployments, it is important to test and design your -application to handle it. - -For some applications, the period of time that old code and new code is running -side by side is short, so bugs or some failed user transactions are acceptable. -For others, the failure pattern may result in the entire application becoming -non-functional. - -One way to validate N-1 compatibility is to use an A/B deployment: run the old -code and new code at the same time in a controlled way in a test environment, -and verify that traffic that flows to the new deployment does not cause failures -in the old deployment. diff --git a/modules/deployments-proxy-shards.adoc b/modules/deployments-proxy-shards.adoc deleted file mode 100644 index 9a0cc7dc89b2..000000000000 --- a/modules/deployments-proxy-shards.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/route-based-deployment-strategies.adoc - -[id="deployments-proxy-shard_{context}"] -= Proxy shards and traffic splitting - -In production environments, you can precisely control the distribution of -traffic that lands on a particular shard. When dealing with large numbers of -instances, you can use the relative scale of individual shards to implement -percentage based traffic. That combines well with a _proxy shard_, which -forwards or splits the traffic it receives to a separate service or application -running elsewhere. - -In the simplest configuration, the proxy forwards requests unchanged. In -more complex setups, you can duplicate the incoming requests and send to -both a separate cluster as well as to a local instance of the application, and -compare the result. Other patterns include keeping the caches of a DR -installation warm, or sampling incoming traffic for analysis purposes. - -Any TCP (or UDP) proxy could be run under the desired shard. Use the `oc scale` -command to alter the relative number of instances serving requests under the -proxy shard. For more complex traffic management, consider customizing the -{product-title} router with proportional balancing capabilities. diff --git a/modules/deployments-recreate-strategy.adoc b/modules/deployments-recreate-strategy.adoc deleted file mode 100644 index dca822276508..000000000000 --- a/modules/deployments-recreate-strategy.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/deployment-strategies.adoc - -[id="deployments-recreate-strategy_{context}"] -= Recreate strategy - -The recreate strategy has basic rollout behavior and supports lifecycle hooks for injecting code into the deployment process. - -.Example recreate strategy definition -[source,yaml] ----- -strategy: - type: Recreate - recreateParams: <1> - pre: {} <2> - mid: {} - post: {} ----- - -<1> `recreateParams` are optional. -<2> `pre`, `mid`, and `post` are lifecycle hooks. - -The recreate strategy: - -. Executes any `pre` lifecycle hook. -. Scales down the previous deployment to zero. -. Executes any `mid` lifecycle hook. -. Scales up the new deployment. -. Executes any `post` lifecycle hook. - -[IMPORTANT] -==== -During scale up, if the replica count of the deployment is greater than one, the first replica of the deployment will be validated for readiness before fully scaling up the deployment. If the validation of the first replica fails, the deployment will be considered a failure. -==== - -*When to use a recreate deployment:* - -- When you must run migrations or other data transformations before your new code starts. -- When you do not support having new and old versions of your application code running at the same time. -- When you want to use a RWO volume, which is not supported being shared between multiple replicas. - -A recreate deployment incurs downtime because, for a brief period, no instances of your application are running. However, your old code and new code do not run at the same time. diff --git a/modules/deployments-replicasets.adoc b/modules/deployments-replicasets.adoc deleted file mode 100644 index fe2bbb4820c6..000000000000 --- a/modules/deployments-replicasets.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/what-deployments-are.adoc - -[id="deployments-repliasets_{context}"] -= Replica sets - -Similar to a replication controller, a `ReplicaSet` is a native Kubernetes API object that ensures a specified number of pod replicas are running at any given time. The difference between a replica set and a replication controller is that a replica set supports set-based selector requirements whereas a replication controller only supports equality-based selector requirements. - -[NOTE] -==== -Only use replica sets if you require custom update orchestration or do not require updates at all. Otherwise, use deployments. Replica sets can be used independently, but are used by deployments to orchestrate pod creation, deletion, and updates. Deployments manage their replica sets automatically, provide declarative updates to pods, and do not have to manually manage the replica sets that they create. -==== - -The following is an example `ReplicaSet` definition: - -[source,yaml] ----- -apiVersion: apps/v1 -kind: ReplicaSet -metadata: - name: frontend-1 - labels: - tier: frontend -spec: - replicas: 3 - selector: <1> - matchLabels: <2> - tier: frontend - matchExpressions: <3> - - {key: tier, operator: In, values: [frontend]} - template: - metadata: - labels: - tier: frontend - spec: - containers: - - image: openshift/hello-openshift - name: helloworld - ports: - - containerPort: 8080 - protocol: TCP - restartPolicy: Always ----- -<1> A label query over a set of resources. The result of `matchLabels` and `matchExpressions` are logically conjoined. -<2> Equality-based selector to specify resources with labels that match the selector. -<3> Set-based selector to filter keys. This selects all resources with key equal to `tier` and value equal to `frontend`. diff --git a/modules/deployments-replicationcontrollers.adoc b/modules/deployments-replicationcontrollers.adoc deleted file mode 100644 index eef11545854f..000000000000 --- a/modules/deployments-replicationcontrollers.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/what-deployments-are.adoc - -[id="deployments-replicationcontrollers_{context}"] -= Replication controllers - -A replication controller ensures that a specified number of replicas of a pod are running at all times. If pods exit or are deleted, the replication controller acts to instantiate more up to the defined number. Likewise, if there are more running than desired, it deletes as many as necessary to match the defined amount. - -A replication controller configuration consists of: - -* The number of replicas desired, which can be adjusted at run time. -* A `Pod` definition to use when creating a replicated pod. -* A selector for identifying managed pods. - -A selector is a set of labels assigned to the pods that are managed by the replication controller. These labels are included in the `Pod` definition that the replication controller instantiates. The replication controller uses the selector to determine how many instances of the pod are already running in order to adjust as needed. - -The replication controller does not perform auto-scaling based on load or traffic, as it does not track either. Rather, this requires its replica -count to be adjusted by an external auto-scaler. - -The following is an example definition of a replication controller: - -[source,yaml] ----- -apiVersion: v1 -kind: ReplicationController -metadata: - name: frontend-1 -spec: - replicas: 1 <1> - selector: <2> - name: frontend - template: <3> - metadata: - labels: <4> - name: frontend <5> - spec: - containers: - - image: openshift/hello-openshift - name: helloworld - ports: - - containerPort: 8080 - protocol: TCP - restartPolicy: Always ----- -<1> The number of copies of the pod to run. -<2> The label selector of the pod to run. -<3> A template for the pod the controller creates. -<4> Labels on the pod should include those from the label selector. -<5> The maximum name length after expanding any parameters is 63 characters. diff --git a/modules/deployments-retrying-deployment.adoc b/modules/deployments-retrying-deployment.adoc deleted file mode 100644 index acbff09d2548..000000000000 --- a/modules/deployments-retrying-deployment.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-retrying-deployment_{context}"] -= Retrying a deployment - -If the current revision of your `DeploymentConfig` object failed to deploy, you can restart the deployment process. - -.Procedure - -. To restart a failed deployment process: -+ -[source,terminal] ----- -$ oc rollout retry dc/<name> ----- -+ -If the latest revision of it was deployed successfully, the command displays a message and the deployment process is not retried. -+ -[NOTE] -==== -Retrying a deployment restarts the deployment process and does not create a new deployment revision. The restarted replication controller has the same configuration it had when it failed. -==== diff --git a/modules/deployments-rolling-back.adoc b/modules/deployments-rolling-back.adoc deleted file mode 100644 index f6f722c2ca5e..000000000000 --- a/modules/deployments-rolling-back.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-rolling-back_{context}"] -= Rolling back a deployment - -Rollbacks revert an application back to a previous revision and can be performed using the REST API, the CLI, or the web console. - -.Procedure - -. To rollback to the last successful deployed revision of your configuration: -+ -[source,terminal] ----- -$ oc rollout undo dc/<name> ----- -+ -The `DeploymentConfig` object's template is reverted to match the deployment revision specified in the undo command, and a new replication controller is started. If no revision is specified with `--to-revision`, then the last successfully deployed revision is used. - -. Image change triggers on the `DeploymentConfig` object are disabled as part of the rollback to prevent accidentally starting a new deployment process soon after the rollback is complete. -+ -To re-enable the image change triggers: -+ -[source,terminal] ----- -$ oc set triggers dc/<name> --auto ----- - -[NOTE] -==== -Deployment configs also support automatically rolling back to the last successful revision of the configuration in case the latest deployment process fails. In that case, the latest template that failed to deploy stays intact by the system and it is up to users to fix their configurations. -==== diff --git a/modules/deployments-rolling-strategy.adoc b/modules/deployments-rolling-strategy.adoc deleted file mode 100644 index fcb6e019ada2..000000000000 --- a/modules/deployments-rolling-strategy.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/deployment-strategies.adoc - -[id="deployments-rolling-strategy_{context}"] -= Rolling strategy - -A rolling deployment slowly replaces instances of the previous version of an application with instances of the new version of the application. The rolling strategy is the default deployment strategy used if no strategy is specified on a `DeploymentConfig` object. - -A rolling deployment typically waits for new pods to become `ready` via a readiness check before scaling down the old components. If a significant issue occurs, the rolling deployment can be aborted. - -*When to use a rolling deployment:* - -- When you want to take no downtime during an application update. -- When your application supports having old code and new code running at the same time. - -A rolling deployment means you to have both old and new versions of your code running at the same time. This typically requires that your application handle N-1 compatibility. - -.Example rolling strategy definition -[source,yaml] ----- -strategy: - type: Rolling - rollingParams: - updatePeriodSeconds: 1 <1> - intervalSeconds: 1 <2> - timeoutSeconds: 120 <3> - maxSurge: "20%" <4> - maxUnavailable: "10%" <5> - pre: {} <6> - post: {} ----- -<1> The time to wait between individual pod updates. If unspecified, this value defaults to `1`. -<2> The time to wait between polling the deployment status after update. If unspecified, this value defaults to `1`. -<3> The time to wait for a scaling event before giving up. Optional; the default is `600`. Here, _giving up_ means automatically rolling back to the previous complete deployment. -<4> `maxSurge` is optional and defaults to `25%` if not specified. See the information below the following procedure. -<5> `maxUnavailable` is optional and defaults to `25%` if not specified. See the information below the following procedure. -<6> `pre` and `post` are both lifecycle hooks. - -The rolling strategy: - -. Executes any `pre` lifecycle hook. -. Scales up the new replication controller based on the surge count. -. Scales down the old replication controller based on the max unavailable count. -. Repeats this scaling until the new replication controller has reached the desired replica count and the old replication controller has been scaled to zero. -. Executes any `post` lifecycle hook. - -[IMPORTANT] -==== -When scaling down, the rolling strategy waits for pods to become ready so it can decide whether further scaling would affect availability. If scaled up pods never become ready, the deployment process will eventually time out and result in a deployment failure. -==== - -The `maxUnavailable` parameter is the maximum number of pods that can be unavailable during the update. The `maxSurge` parameter is the maximum number of pods that can be scheduled above the original number of pods. Both parameters can be set to either a percentage (e.g., `10%`) or an absolute value (e.g., `2`). The default value for both is `25%`. - -These parameters allow the deployment to be tuned for availability and speed. For example: - -- `maxUnavailable*=0` and `maxSurge*=20%` ensures full capacity is maintained during the update and rapid scale up. -- `maxUnavailable*=10%` and `maxSurge*=0` performs an update using no extra capacity (an in-place update). -- `maxUnavailable*=10%` and `maxSurge*=10%` scales up and down quickly with some potential for capacity loss. - -Generally, if you want fast rollouts, use `maxSurge`. If you have to take into account resource quota and can accept partial unavailability, use -`maxUnavailable`. diff --git a/modules/deployments-running-pod-svc-acct.adoc b/modules/deployments-running-pod-svc-acct.adoc deleted file mode 100644 index f456bded632e..000000000000 --- a/modules/deployments-running-pod-svc-acct.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-running-pod-svc-acct_{context}"] -= Running a pod with a different service account - -You can run a pod with a service account other than the default. - -.Procedure - -. Edit the `DeploymentConfig` object: -+ -[source,terminal] ----- -$ oc edit dc/<deployment_config> ----- - -. Add the `serviceAccount` and `serviceAccountName` parameters to the `spec` field, and specify the service account you want to use: -+ -[source,yaml] ----- -spec: - securityContext: {} - serviceAccount: <service_account> - serviceAccountName: <service_account> ----- diff --git a/modules/deployments-scaling-manually.adoc b/modules/deployments-scaling-manually.adoc deleted file mode 100644 index 5d86ba4a472c..000000000000 --- a/modules/deployments-scaling-manually.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-scaling-manually_{context}"] -= Scaling manually - -In addition to rollbacks, you can exercise fine-grained control over the number of replicas by manually scaling them. - -[NOTE] -==== -Pods can also be auto-scaled using the `oc autoscale` command. -==== - -.Procedure - -. To manually scale a `DeploymentConfig` object, use the `oc scale` command. For example, the following command sets the replicas in the `frontend` `DeploymentConfig` object to `3`. -+ -[source,terminal] ----- -$ oc scale dc frontend --replicas=3 ----- -+ -The number of replicas eventually propagates to the desired and current state of the deployment configured by the `DeploymentConfig` object `frontend`. diff --git a/modules/deployments-setting-resources.adoc b/modules/deployments-setting-resources.adoc deleted file mode 100644 index 2fa22caf14b5..000000000000 --- a/modules/deployments-setting-resources.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-setting-resources_{context}"] -= Setting deployment resources - -A deployment is completed by a pod that consumes resources (memory, CPU, and ephemeral storage) on a node. By default, pods consume unbounded node resources. However, if a project specifies default container limits, then pods consume resources up to those limits. - -[NOTE] -==== -The minimum memory limit for a deployment is 12 MB. If a container fails to start due to a `Cannot allocate memory` pod event, the memory limit is too low. Either increase or remove the memory limit. Removing the limit allows pods to consume unbounded node resources. -==== - -You can also limit resource use by specifying resource limits as part of the deployment strategy. Deployment resources can be used with the recreate, rolling, or custom deployment strategies. - -.Procedure - -. In the following example, each of `resources`, `cpu`, `memory`, and `ephemeral-storage` is optional: -+ -[source,yaml] ----- -type: "Recreate" -resources: - limits: - cpu: "100m" <1> - memory: "256Mi" <2> - ephemeral-storage: "1Gi" <3> ----- -<1> `cpu` is in CPU units: `100m` represents 0.1 CPU units (100 * 1e-3). -<2> `memory` is in bytes: `256Mi` represents 268435456 bytes (256 * 2 ^ 20). -<3> `ephemeral-storage` is in bytes: `1Gi` represents 1073741824 bytes (2 ^ 30). -+ -However, if a quota has been defined for your project, one of the following two items is required: -+ --- -- A `resources` section set with an explicit `requests`: -+ -[source,yaml] ----- - type: "Recreate" - resources: - requests: <1> - cpu: "100m" - memory: "256Mi" - ephemeral-storage: "1Gi" ----- -<1> The `requests` object contains the list of resources that correspond to the list of resources in the quota. - -- A limit range defined in your project, where the defaults from the `LimitRange` object apply to pods created during the deployment process. --- -+ -To set deployment resources, choose one of the above options. Otherwise, deploy pod creation fails, citing a failure to satisfy quota. diff --git a/modules/deployments-setting-triggers.adoc b/modules/deployments-setting-triggers.adoc deleted file mode 100644 index b7ab501bd98f..000000000000 --- a/modules/deployments-setting-triggers.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-setting-triggers_{context}"] -= Setting deployment triggers - -.Procedure - -. You can set deployment triggers for a `DeploymentConfig` object using the `oc set triggers` command. For example, to set a image change trigger, use the following command: -+ -[source,terminal] ----- -$ oc set triggers dc/<dc_name> \ - --from-image=<project>/<image>:<tag> -c <container_name> ----- diff --git a/modules/deployments-starting-deployment.adoc b/modules/deployments-starting-deployment.adoc deleted file mode 100644 index 2bce3ca3dfc5..000000000000 --- a/modules/deployments-starting-deployment.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-starting-a-deployment_{context}"] -= Starting a deployment - -You can start a rollout to begin the deployment process of your application. - -.Procedure - -. To start a new deployment process from an existing `DeploymentConfig` object, run the following command: -+ -[source,terminal] ----- -$ oc rollout latest dc/<name> ----- -+ -[NOTE] -==== -If a deployment process is already in progress, the command displays a message and a new replication controller will not be deployed. -==== diff --git a/modules/deployments-tab.adoc b/modules/deployments-tab.adoc new file mode 100644 index 000000000000..28e63cd74180 --- /dev/null +++ b/modules/deployments-tab.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +ifeval::["{context}" == "observed-cves"] +:observedcves: +endif::[] + +:_mod-docs-content-type: CONCEPT +[id="deployments-tab_{context}"] += Deployments tab + +The deployments view organizes information into the following groups: + +* *Deployment*: Indicates the name or identifier of each deployment. +ifdef::observedcves[] +* *CVEs by severity*: Groups the vulnerabilities associated with each deployment based on their severity. +endif::observedcves[] +* *Cluster*: Displays the cluster in which each deployment is located. +* *Namespace*: Displays the namespace of each deployment. +* *Images*: Displays the container images that the deployment uses. +* *First discovered*: Shows the date on which the vulnerabilities associated with a deployment were first discovered. + +To review and triage the details associated with a deployment, click on the deployment. + +A window opens with information about the vulnerabilities associated with the deployment. + +ifeval::["{context}" == "observed-cves"] +:!observedcves: +endif::[] \ No newline at end of file diff --git a/modules/deployments-triggers.adoc b/modules/deployments-triggers.adoc deleted file mode 100644 index 5140677f9507..000000000000 --- a/modules/deployments-triggers.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-triggers_{context}"] -= Deployment triggers - -A `DeploymentConfig` object can contain triggers, which drive the creation of new deployment processes in response to events inside the cluster. - -[WARNING] -==== -If no triggers are defined on a `DeploymentConfig` object, a config change trigger is added by default. If triggers are defined as an empty field, deployments must be started manually. -==== - -[discrete] -[id="deployments-configchange-trigger_{context}"] -=== Config change deployment triggers - -The config change trigger results in a new replication controller whenever configuration changes are detected in the pod template of the `DeploymentConfig` object. - -[NOTE] -==== -If a config change trigger is defined on a `DeploymentConfig` object, the first replication controller is automatically created soon after the `DeploymentConfig` object itself is created and it is not paused. -==== - -.Config change deployment trigger -[source,yaml] ----- -triggers: - - type: "ConfigChange" ----- - -[discrete] -[id="deployments-imagechange-trigger_{context}"] -=== Image change deployment triggers - -The image change trigger results in a new replication controller whenever the content of an image stream tag changes (when a new version of the image is pushed). - -.Image change deployment trigger -[source,yaml] ----- -triggers: - - type: "ImageChange" - imageChangeParams: - automatic: true <1> - from: - kind: "ImageStreamTag" - name: "origin-ruby-sample:latest" - namespace: "myproject" - containerNames: - - "helloworld" ----- -<1> If the `imageChangeParams.automatic` field is set to `false`, the trigger is disabled. - -With the above example, when the `latest` tag value of the `origin-ruby-sample` image stream changes and the new image value differs from the current image specified in the `DeploymentConfig` object's `helloworld` container, a new replication controller is created using the new image for the `helloworld` container. - -[NOTE] -==== -If an image change trigger is defined on a `DeploymentConfig` object (with a config change trigger and `automatic=false`, or with `automatic=true`) and the image stream tag pointed by the image change trigger does not exist yet, the initial deployment process will automatically start as soon as an image is imported or pushed by a build to the image stream tag. -==== diff --git a/modules/deployments-viewing-deployment.adoc b/modules/deployments-viewing-deployment.adoc deleted file mode 100644 index 897f144050d6..000000000000 --- a/modules/deployments-viewing-deployment.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-viewing-a-deployment_{context}"] -= Viewing a deployment - -You can view a deployment to get basic information about all the available revisions of your application. - -.Procedure - -. To show details about all recently created replication controllers for the provided `DeploymentConfig` object, including any currently running deployment process, run the following command: -+ -[source,terminal] ----- -$ oc rollout history dc/<name> ----- - -. To view details specific to a revision, add the `--revision` flag: -+ -[source,terminal] ----- -$ oc rollout history dc/<name> --revision=1 ----- - -. For more detailed information about a `DeploymentConfig` object and its latest revision, use the `oc describe` command: -+ -[source,terminal] ----- -$ oc describe dc <name> ----- diff --git a/modules/deployments-viewing-logs.adoc b/modules/deployments-viewing-logs.adoc deleted file mode 100644 index 7a0393b9d9b6..000000000000 --- a/modules/deployments-viewing-logs.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/managing-deployment-processes.adoc - -[id="deployments-viewing-logs_{context}"] -= Viewing deployment logs - -.Procedure - -. To stream the logs of the latest revision for a given `DeploymentConfig` object: -+ -[source,terminal] ----- -$ oc logs -f dc/<name> ----- -+ -If the latest revision is running or failed, the command returns the logs of the process that is responsible for deploying your pods. If it is successful, it returns the logs from a pod of your application. - -. You can also view logs from older failed deployment processes, if and only if these processes (old replication controllers and their deployer pods) exist and have not been pruned or deleted manually: -+ -[source,terminal] ----- -$ oc logs --version=1 dc/<name> ----- diff --git a/modules/determining-where-installation-issues-occur.adoc b/modules/determining-where-installation-issues-occur.adoc deleted file mode 100644 index ba22dd8ae43b..000000000000 --- a/modules/determining-where-installation-issues-occur.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="determining-where-installation-issues-occur_{context}"] -= Determining where installation issues occur - -When troubleshooting {product-title} installation issues, you can monitor installation logs to determine at which stage issues occur. Then, retrieve diagnostic data relevant to that stage. - -{product-title} installation proceeds through the following stages: - -. Ignition configuration files are created. - -. The bootstrap machine boots and starts hosting the remote resources required for the master machines to boot. - -. The master machines fetch the remote resources from the bootstrap machine and finish booting. - -. The master machines use the bootstrap machine to form an etcd cluster. - -. The bootstrap machine starts a temporary Kubernetes control plane using the new etcd cluster. - -. The temporary control plane schedules the production control plane to the master machines. - -. The temporary control plane shuts down and passes control to the production control plane. - -. The bootstrap machine adds {product-title} components into the production control plane. - -. The installation program shuts down the bootstrap machine. - -. The control plane sets up the worker nodes. - -. The control plane installs additional services in the form of a set of Operators. - -. The cluster downloads and configures remaining components needed for the day-to-day operation, including the creation of worker machines in supported environments. diff --git a/modules/developer-cli-odo-about-devfiles-in-odo.adoc b/modules/developer-cli-odo-about-devfiles-in-odo.adoc deleted file mode 100644 index f95a8217e54e..000000000000 --- a/modules/developer-cli-odo-about-devfiles-in-odo.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="about-the-devfile-in-odo"] -= About the devfile in `{odo-title}` - -The devfile is a portable file that describes your development environment. -With the devfile, you can define a portable developmental environment without the need for reconfiguration. - -With the devfile, you can describe your development environment, such as the source code, IDE tools, application runtimes, and predefined commands. To learn more about the devfile, see link:https://redhat-developer.github.io/devfile/[the devfile documentation]. - -With `{odo-title}`, you can create components from the devfiles. When creating a component by using a devfile, `{odo-title}` transforms the devfile into a workspace consisting of multiple containers that run on {product-title}, Kubernetes, or Docker. -`{odo-title}` automatically uses the default devfile registry but users can add their own registries. diff --git a/modules/developer-cli-odo-adding-a-custom-builder-to-specify-a-build-image.adoc b/modules/developer-cli-odo-adding-a-custom-builder-to-specify-a-build-image.adoc deleted file mode 100644 index 0ac215ef0ca0..000000000000 --- a/modules/developer-cli-odo-adding-a-custom-builder-to-specify-a-build-image.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-single-component-application-with-odo.adoc - -[id="adding-a-custom-builder-to-specify-a-build-image_{context}"] -= Adding a custom builder to specify a build image - -With {product-title}, you can add a custom image to bridge the gap between the creation of custom images. - -The following example demonstrates the successful import and use of the `redhat-openjdk-18` image: - -.Prerequisites -* The OpenShift CLI (oc) is installed. - -.Procedure - -. Import the image into {product-title}: -+ -[source,terminal] ----- -$ oc import-image openjdk18 \ ---from=registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift \ ---confirm ----- -. Tag the image to make it accessible to {odo-title}: -+ -[source,terminal] ----- -$ oc annotate istag/openjdk18:latest tags=builder ----- -. Deploy the image with {odo-title}: -+ -[source,terminal] ----- -$ odo create openjdk18 --git \ -https://github.com/openshift-evangelists/Wild-West-Backend ----- diff --git a/modules/developer-cli-odo-adding-storage-to-the-application-components.adoc b/modules/developer-cli-odo-adding-storage-to-the-application-components.adoc deleted file mode 100644 index 2eaf140a08d4..000000000000 --- a/modules/developer-cli-odo-adding-storage-to-the-application-components.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// *cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-single-component-application-with-odo.adoc -// *cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-storage.adoc - -[id="adding-storage-to-the-application-components_{context}"] -= Adding storage to the application components - -Use the `odo storage` command to add persistent data to your application. Examples of data that must persist include database files, dependencies, and build artifacts, such as a `.m2` Maven directory. - -.Procedure - -. Add the storage to your component: -+ -[source,terminal] ----- -$ odo storage create <storage_name> --path=<path_to_the_directory> --size=<size> ----- - -. Push the storage to the cluster: -+ -[source,terminal] ----- -$ odo push ----- - -. Verify that the storage is now attached to your component by listing all storage in the component: -+ -[source,terminal] ----- -$ odo storage list ----- -+ -.Example output -+ -[source,terminal] ----- -The component 'nodejs' has the following storage attached: -NAME SIZE PATH STATE -mystorage 1Gi /data Pushed ----- - -. Delete the storage from your component: -+ -[source,terminal] ----- -$ odo storage delete <storage_name> ----- - -. List all storage to verify that the storage state is `Locally Deleted`: -+ -[source,terminal] ----- -$ odo storage list ----- -+ -.Example output -+ -[source,terminal] ----- -The component 'nodejs' has the following storage attached: -NAME SIZE PATH STATE -mystorage 1Gi /data Locally Deleted ----- - -. Push the changes to the cluster: -+ -[source,terminal] ----- -$ odo push ----- diff --git a/modules/developer-cli-odo-attributes.adoc b/modules/developer-cli-odo-attributes.adoc deleted file mode 100644 index fe676f118db9..000000000000 --- a/modules/developer-cli-odo-attributes.adoc +++ /dev/null @@ -1 +0,0 @@ -:odo-title: odo diff --git a/modules/developer-cli-odo-basic-odo-cli-commands.adoc b/modules/developer-cli-odo-basic-odo-cli-commands.adoc deleted file mode 100644 index ce0e1826aae8..000000000000 --- a/modules/developer-cli-odo-basic-odo-cli-commands.adoc +++ /dev/null @@ -1,620 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/odo-cli-reference.adoc - -[id="basic-odo-cli-commands_{context}"] -= Basic {odo-title} CLI commands - -== app - -Perform application operations related to your {product-title} project. - -.Example using app - -[source,terminal] ----- - # Delete the application - odo app delete myapp - - # Describe 'webapp' application, - odo app describe webapp - - # List all applications in the current project - odo app list - - # List all applications in the specified project - odo app list --project myproject ----- - - -== catalog - -Perform catalog-related operations. - -.Example using catalog - -[source,terminal] ----- - # Get the supported components - odo catalog list components - - # Get the supported services from service catalog - odo catalog list services - - # Search for a component - odo catalog search component python - - # Search for a service - odo catalog search service mysql - - # Describe a service - odo catalog describe service mysql-persistent ----- - -== component - -Manage components of an application. - -.Example using component - -[source,terminal] ----- -# Create a new component -odo component create - -# Create a local configuration and create all objects on the cluster -odo component create --now ----- - -== config - -Modify `odo` specific settings within the `config` file. - -.Example using config - -[source,terminal] ----- - - # For viewing the current local configuration - odo config view - - # Set a configuration value in the local configuration - odo config set Type java - odo config set Name test - odo config set MinMemory 50M - odo config set MaxMemory 500M - odo config set Memory 250M - odo config set Ignore false - odo config set MinCPU 0.5 - odo config set MaxCPU 2 - odo config set CPU 1 - - # Set an environment variable in the local configuration - odo config set --env KAFKA_HOST=kafka --env KAFKA_PORT=6639 - - # Create a local configuration and apply the changes to the cluster immediately - odo config set --now - - # Unset a configuration value in the local config - odo config unset Type - odo config unset Name - odo config unset MinMemory - odo config unset MaxMemory - odo config unset Memory - odo config unset Ignore - odo config unset MinCPU - odo config unset MaxCPU - odo config unset CPU - - # Unset an env variable in the local config - odo config unset --env KAFKA_HOST --env KAFKA_PORT ----- - -|======= -|Application |Application is the name of application the component needs to be part of -|CPU |The minimum and maximum CPU a component can consume -|Ignore |Consider the .odoignore file for push and watch -|======= - -.Available Local Parameters: -|======= -|Application |The name of application that the component needs to be part of -|CPU |The minimum and maximum CPU a component can consume -|Ignore |Whether to consider the `.odoignore` file for push and watch -|MaxCPU |The maximum CPU a component can consume -|MaxMemory |The maximum memory a component can consume -|Memory |The minimum and maximum memory a component can consume -|MinCPU |The minimum CPU a component can consume -|MinMemory |The minimum memory a component is provided -|Name |The name of the component -|Ports |Ports to be opened in the component -|Project |The name of the project that the component is part of -|Ref |Git ref to use for creating component from git source -|SourceLocation |The path indicates the location of binary file or git source -|SourceType |Type of component source - git/binary/local -|Storage |Storage of the component -|Type |The type of component -|Url |The URL to access the component -|======= - -== create - -Create a configuration describing a component to be deployed on {product-title}. If a component name is not provided, it is autogenerated. - -By default, builder images are used from the current namespace. To explicitly supply a namespace, use: `odo create namespace/name:version`. If a version is not specified, the version defaults to `latest`. - -Use `odo catalog list` to see a full list of component types that can be deployed. - -.Example using create - -[source,terminal] ----- - # Create new Node.js component with the source in current directory. - odo create nodejs - - # Create new Node.js component and push it to the cluster immediately. - odo create nodejs --now - - # A specific image version may also be specified - odo create nodejs:latest - - # Create new Node.js component named 'frontend' with the source in './frontend' directory - odo create nodejs frontend --context ./frontend - - # Create a new Node.js component of version 6 from the 'openshift' namespace - odo create openshift/nodejs:6 --context /nodejs-ex - - # Create new Wildfly component with binary named sample.war in './downloads' directory - odo create wildfly wildfly --binary ./downloads/sample.war - - # Create new Node.js component with source from remote git repository - odo create nodejs --git https://github.com/openshift/nodejs-ex.git - - # Create new Node.js git component while specifying a branch, tag or commit ref - odo create nodejs --git https://github.com/openshift/nodejs-ex.git --ref master - - # Create new Node.js git component while specifying a tag - odo create nodejs --git https://github.com/openshift/nodejs-ex.git --ref v1.0.1 - - # Create new Node.js component with the source in current directory and ports 8080-tcp,8100-tcp and 9100-udp exposed - odo create nodejs --port 8080,8100/tcp,9100/udp - - # Create new Node.js component with the source in current directory and env variables key=value and key1=value1 exposed - odo create nodejs --env key=value,key1=value1 - - # Create a new Python component with the source in a Git repository - odo create python --git https://github.com/openshift/django-ex.git - - # Passing memory limits - odo create nodejs --memory 150Mi - odo create nodejs --min-memory 150Mi --max-memory 300 Mi - - # Passing cpu limits - odo create nodejs --cpu 2 - odo create nodejs --min-cpu 200m --max-cpu 2 ----- - -== debug - -Debug a component. - -.Example using debug - -[source,terminal] ----- -# Displaying information about the state of debugging -odo debug info - -# Starting the port forwarding for a component to debug the application -odo debug port-forward - -# Setting a local port to port forward -odo debug port-forward --local-port 9292 ----- - -== delete - -Delete an existing component. - -.Example using delete - -[source,terminal] ----- - # Delete component named 'frontend'. - odo delete frontend - odo delete frontend --all-apps ----- - - -== describe - -Describe the given component. - -.Example using describe - -[source,terminal] ----- - # Describe nodejs component - odo describe nodejs ----- - -== link - - -Link a component to a service or component. - -.Example using link - -[source,terminal] ----- - # Link the current component to the 'my-postgresql' service - odo link my-postgresql - - # Link component 'nodejs' to the 'my-postgresql' service - odo link my-postgresql --component nodejs - - # Link current component to the 'backend' component (backend must have a single exposed port) - odo link backend - - # Link component 'nodejs' to the 'backend' component - odo link backend --component nodejs - - # Link current component to port 8080 of the 'backend' component (backend must have port 8080 exposed) - odo link backend --port 8080 ----- - -Link adds the appropriate secret to the environment of the source component. The source component can then consume the entries of the secret as environment variables. If the source component is not provided, the current active component is assumed. - -== list - -List all the components in the current application and the states of the components. - -.The states of the components -Pushed:: A component is pushed to the cluster. -Not Pushed:: A component is not pushed to the cluster. -Unknown:: `{odo-title}` is disconnected from the cluster. - -.Example using list - -[source,terminal] ----- - # List all components in the application - odo list - - # List all the components in a given path - odo list --path <path_to_your_component> ----- - -== log - -Retrieve the log for the given component. - -.Example using log - -[source,terminal] ----- - # Get the logs for the nodejs component - odo log nodejs ----- - - - -== login - -Log in to the cluster. - -.Example using login - -[source,terminal] ----- - # Log in interactively - odo login - - # Log in to the given server with the given certificate authority file - odo login localhost:8443 --certificate-authority=/path/to/cert.crt - - # Log in to the given server with the given credentials (basic auth) - odo login localhost:8443 --username=myuser --password=mypass - - # Log in to the given server with the given credentials (token) - odo login localhost:8443 --token=xxxxxxxxxxxxxxxxxxxxxxx ----- - - -== logout - -Log out of the current {product-title} session. - -.Example using logout - -[source,terminal] ----- - # Log out - odo logout ----- - - -== preference - -Modify `odo` specific configuration settings within the global preference file. - -.Example using preference -[source,terminal] ----- - - # For viewing the current preferences - odo preference view - - # Set a preference value in the global preference - odo preference set UpdateNotification false - odo preference set NamePrefix "app" - odo preference set Timeout 20 - - # Enable experimental mode - odo preference set experimental true - - # Unset a preference value in the global preference - odo preference unset UpdateNotification - odo preference unset NamePrefix - odo preference unset Timeout - - # Disable experimental mode - odo preference set experimental false - - # Use persistent volumes in the cluster - odo preference set ephemeral false ----- - -[NOTE] -==== -By default, the path to the global preference file is `~/.odo/preferece.yaml` and it is stored in the environment variable `GLOBALODOCONFIG`. You can set up a custom path by setting the value of the environment variable to a new preference path, for example `GLOBALODOCONFIG="new_path/preference.yaml"` -==== - -.Available Parameters: -|======= -|NamePrefix |The default prefix is the current directory name. Use this value to set a default name prefix. -|Timeout |The timeout (in seconds) for {product-title} server connection checks. -|UpdateNotification |Controls whether an update notification is shown. -|======= - -== project - -Perform project operations. - -.Example using project - -[source,terminal] ----- - # Set the active project - odo project set - - # Create a new project - odo project create myproject - - # List all the projects - odo project list - - # Delete a project - odo project delete myproject - - # Get the active project - odo project get ----- - -== push - -Push source code to a component. - -.Example using push - -[source,terminal] ----- - # Push source code to the current component - odo push - - # Push data to the current component from the original source. - odo push - - # Push source code in ~/mycode to component called my-component - odo push my-component --context ~/mycode - - # Push source code and display event notifications in JSON format. - odo push -o json ----- - -== registry - -Create and modify custom registries. - -.Example using registry -[source,terminal] ----- -# Add a registry to the registry list -odo registry add <registry name> <registry URL> - -# List a registry in the registry list -odo registry list - -# Delete a registry from the registry list -odo registry delete <registry name> - -# Update a registry in the registry list -odo registry update <registry name> <registry URL> - -# List a component with a corresponding registry -odo catalog list components - -# Create a component that is hosted by a specific registry -odo create <component type> --registry <registry name> ----- - -== service - -Perform service catalog operations. - -.Example using service - -[source,terminal] ----- - # Create new postgresql service from service catalog using dev plan and name my-postgresql-db. - odo service create dh-postgresql-apb my-postgresql-db --plan dev -p postgresql_user=luke -p postgresql_password=secret - - # Delete the service named 'mysql-persistent' - odo service delete mysql-persistent - - # List all services in the application - odo service list ----- - - -== storage - -Perform storage operations. - -.Example using storage - -[source,terminal] ----- - # Create storage of size 1Gb to a component - odo storage create mystorage --path=/opt/app-root/src/storage/ --size=1Gi - - # Delete storage mystorage from the currently active component - odo storage delete mystorage - - # List all storage attached or mounted to the current component and - # all unattached or unmounted storage in the current application - odo storage list - - # Set the `-o json` flag to get a JSON formatted output - odo storage list -o json ----- - -== unlink - -Unlink component or a service. - -For this command to be successful, the service or component must have been linked prior to the invocation using `odo link`. - -.Example using unlink - -[source,terminal] ----- - # Unlink the 'my-postgresql' service from the current component - odo unlink my-postgresql - - # Unlink the 'my-postgresql' service from the 'nodejs' component - odo unlink my-postgresql --component nodejs - - # Unlink the 'backend' component from the current component (backend must have a single exposed port) - odo unlink backend - - # Unlink the 'backend' service from the 'nodejs' component - odo unlink backend --component nodejs - - # Unlink the backend's 8080 port from the current component - odo unlink backend --port 8080 ----- - -== update - -Update the source code path of a component - -.Example using update - -[source,terminal] ----- - # Change the source code path of a currently active component to local (use the current directory as a source) - odo update --local - - # Change the source code path of the frontend component to local with source in ./frontend directory - odo update frontend --local ./frontend - - # Change the source code path of a currently active component to git - odo update --git https://github.com/openshift/nodejs-ex.git - - # Change the source code path of the component named node-ex to git - odo update node-ex --git https://github.com/openshift/nodejs-ex.git - - # Change the source code path of the component named wildfly to a binary named sample.war in ./downloads directory - odo update wildfly --binary ./downloads/sample.war ----- - -== url - -Expose a component to the outside world. - -.Example using url - -[source,terminal] ----- - # Create a URL for the current component with a specific port - odo url create --port 8080 - - # Create a URL with a specific name and port - odo url create example --port 8080 - - # Create a URL with a specific name by automatic detection of port (only for components which expose only one service port) - odo url create example - - # Create a URL with a specific name and port for component frontend - odo url create example --port 8080 --component frontend - - # Delete a URL to a component - odo url delete myurl - - # List the available URLs - odo url list - - # Create a URL in the configuration and apply the changes to the cluster - odo url create --now - - # Create an HTTPS URL - odo url create --secure ----- - -The URLs that are generated using this command can be used to access the deployed components from outside the cluster. - -== utils - -Utilities for terminal commands and modifying odo configurations. - -.Example using utils - -[source,terminal] ----- - # Bash terminal PS1 support - source <(odo utils terminal bash) - - # Zsh terminal PS1 support - source <(odo utils terminal zsh) - ----- - - -== version - - -Print the client version information. - -.Example using version - -[source,terminal] ----- - # Print the client version of odo - odo version ----- - -== watch - -{odo-title} starts watching for changes and updates the component upon a change automatically. - -.Example using watch - -[source,terminal] ----- - # Watch for changes in directory for current component - odo watch - - # Watch for changes in directory for component called frontend - odo watch frontend ----- diff --git a/modules/developer-cli-odo-configuring-debugging-parameters.adoc b/modules/developer-cli-odo-configuring-debugging-parameters.adoc deleted file mode 100644 index ab6900f76451..000000000000 --- a/modules/developer-cli-odo-configuring-debugging-parameters.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/creating_and_deploying_applications_with_odo/debugging-applications-in-odo.adoc - -[id="configuring-debugging-parameters_{context}"] - -= Configuring debugging parameters - -You can specify a remote port with `odo config` command and a local port with the `odo debug` command. - -.Procedure - -* To set a remote port on which the debugging agent should run, run: -+ -[source,terminal] ----- -$ odo config set DebugPort 9292 ----- -+ -[NOTE] -==== -You must redeploy your component for this value to be reflected on the component. -==== - -* To set a local port to port forward, run: -+ -[source,terminal] ----- -$ odo debug port-forward --local-port 9292 ----- -+ -[NOTE] -==== -The local port value does not persist. You must provide it every time you need to change the port. -==== diff --git a/modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc b/modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc deleted file mode 100644 index c1ad5b092b07..000000000000 --- a/modules/developer-cli-odo-connecting-a-java-application-to-mysql-database.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-java-application-with-a-database - -[id="connecting-a-java-application-to-a-database_{context}"] -= Connecting a Java application to a database - -To connect your Java application to the database, use the `odo link` command. - -.Procedure - -. Display the list of services: -+ -[source,terminal] ----- -$ odo service list ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -Database/sampledatabase 6m31s ----- - -. Connect the database to your application: -+ -[source,terminal] ----- -$ odo link Database/sampledatabase ----- - -. Push the changes to your cluster: -+ -[source,terminal] ----- -$ odo push ----- -+ -After the link has been created and pushed, a secret that contains the database connection data is created. - -. Check the component for values injected from the database service: -+ -[source,sh] ----- -$ odo exec -- bash -c 'export | grep DATABASE' -declare -x DATABASE_CLUSTERIP="10.106.182.173" -declare -x DATABASE_DB_NAME="sampledb" -declare -x DATABASE_DB_PASSWORD="samplepwd" -declare -x DATABASE_DB_USER="sampleuser" ----- - -. Open the URL of your Java application and navigate to the `CreatePerson.xhtml` data entry page. Enter a username and age by using the the form. Click *Save*. -+ -Note that now you can see the data in the database by clicking the *View Persons Record List* link. -+ -You can also use a CLI tool such as `psql` to manipulate the database. diff --git a/modules/developer-cli-odo-connecting-the-database.adoc b/modules/developer-cli-odo-connecting-the-database.adoc deleted file mode 100644 index b60d9afcef5e..000000000000 --- a/modules/developer-cli-odo-connecting-the-database.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-multicomponent-application-with-odo.adoc -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc - -[id="Connecting-the-database-to-the-front-end-application_{context}"] -= Connecting the database to the front-end application - -. Link the database to the front-end service: -+ -[source,terminal] ----- -$ odo link mongodb-persistent ----- -+ -.Example output -[source,terminal] ----- - ✓ Service mongodb-persistent has been successfully linked from the component nodejs-nodejs-ex-mhbb - -Following environment variables were added to nodejs-nodejs-ex-mhbb component: -- database_name -- password -- uri -- username -- admin_password ----- - -. See the environment variables of the application and the database in the pod: - -.. Get the pod name: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -mongodb-1-gsznc 1/1 Running 0 28m -nodejs-nodejs-ex-mhbb-app-4-vkn9l 1/1 Running 0 1m ----- - -.. Connect to the pod: -+ -[source,terminal] ----- -$ oc rsh nodejs-nodejs-ex-mhbb-app-4-vkn9l ----- - -.. Check the environment variables: -+ -[source,terminal] ----- -sh-4.2$ env ----- -+ -.Example output -[source,terminal] ----- -uri=mongodb://172.30.126.3:27017 -password=dHIOpYneSkX3rTLn -database_name=sampledb -username=user43U -admin_password=NCn41tqmx7RIqmfv ----- - -. Open the URL in the browser and notice the database configuration in the bottom right: -+ -[source,terminal] ----- -$ odo url list ----- -+ -.Example output -[source,terminal] ----- -Request information -Page view count: 24 - -DB Connection Info: -Type: MongoDB -URL: mongodb://172.30.126.3:27017/sampledb ----- diff --git a/modules/developer-cli-odo-connecting-your-application-to-multiple-services-using-openshift-service-catalog.adoc b/modules/developer-cli-odo-connecting-your-application-to-multiple-services-using-openshift-service-catalog.adoc deleted file mode 100644 index 298b3184ced7..000000000000 --- a/modules/developer-cli-odo-connecting-your-application-to-multiple-services-using-openshift-service-catalog.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-single-component-application-with-odo.adoc - -[id="connecting-your-application-to-multiple-services-using-openshift-service-catalog_{context}"] - -= Connecting your application to multiple services using OpenShift Service Catalog - -The OpenShift service catalog is an implementation of the Open Service Broker API (OSB API) for Kubernetes. You can use it to connect applications deployed in {product-title} to a variety of services. - -.Prerequisites - -* You have a running {product-title} cluster. -* The service catalog is installed and enabled on your cluster. - -.Procedure - -* To list the services: -+ -[source,terminal] ----- -$ odo catalog list services ----- - -* To use service catalog-related operations: -+ -[source,terminal] ----- -$ odo service <verb> <service_name> ----- diff --git a/modules/developer-cli-odo-converting-an-s2i-component-into-a-devfile-component.adoc b/modules/developer-cli-odo-converting-an-s2i-component-into-a-devfile-component.adoc deleted file mode 100644 index 52e9ba912423..000000000000 --- a/modules/developer-cli-odo-converting-an-s2i-component-into-a-devfile-component.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module is included in the following assemblies: -// -// cli_reference/developer_cli_odo/using-devfiles-in-odo.adoc - -[id="converting-an-s2i-component-into-a-devfile-component_{context}"] -= Converting an S2I component into a devfile component - -With `{odo-title}`, you can create both Source-to-Image (S2I) and devfile components. If you have an existing S2I component, you can convert it into a devfile component using the `odo utils` command. - -.Procedure - -Run all the commands from the S2I component directory. - -. Run the `odo utils convert-to-devfile` command, which creates `devfile.yaml` and `env.yaml` based on your component: -+ -[source,terminal] ----- -$ odo utils convert-to-devfile ----- - -. Push the component to your cluster: -+ -[source,terminal] ----- -$ odo push ----- -+ -[NOTE] -==== -If the devfile component deployment failed, delete it by running: `odo delete -a` -==== -+ - -. Verify that the devfile component deployed successfully: -+ -[source,terminal] ----- -$ odo list ----- - -. Delete the S2I component: -+ -[source,terminal] ----- -$ odo delete --s2i ----- diff --git a/modules/developer-cli-odo-creating-a-database-with-odo.adoc b/modules/developer-cli-odo-creating-a-database-with-odo.adoc deleted file mode 100644 index dd1246580c98..000000000000 --- a/modules/developer-cli-odo-creating-a-database-with-odo.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: - -[id="creating-a-database-with-odo_{context}"] - -= Creating a database with `odo` - -To create a database, you must have an access to the database Operator. For this example, Dev4Devs PostgreSQL Operator is used. - -.Procedure - - -. View the list of the services in your project: -+ -[source,terminal] ----- -$ odo catalog list services ----- -+ -.Example output ----- -Operators available in the cluster -NAME CRDs -postgresql-operator.v0.1.1 Backup, Database ----- - -. Store the YAML of the service in a file: -+ -[source,terminal] ----- -$ odo service create postgresql-operator.v0.1.1/Database --dry-run > db.yaml ----- - -. Add the following values under the `metadata:` section in the `db.yaml` file: -+ -[source,yaml] ----- - name: sampledatabase - annotations: - service.binding/db.name: 'path={.spec.databaseName}' - service.binding/db.password: 'path={.spec.databasePassword}' - service.binding/db.user: 'path={.spec.databaseUser}' ----- -+ -This configuration ensures that when a database service is started, appropriate annotations are added to it. Annotations help the Service Binding Operator in injecting the values for `databaseName`, `databasePassword`, and `databaseUser` into the application. - -. Change the following values under the `spec:` section of the YAML file: -+ -[source,yaml] ----- - databaseName: "sampledb" - databasePassword: "samplepwd" - databaseUser: "sampleuser" ----- - -. Create a database from the YAML file: -+ -[source,terminal] ----- -$ odo service create --from-file db.yaml ----- -+ -A database instance is now present in your project. diff --git a/modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc b/modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc deleted file mode 100644 index 5cad1b7e1b4d..000000000000 --- a/modules/developer-cli-odo-creating-a-java-microservice-jpa-application.adoc +++ /dev/null @@ -1,110 +0,0 @@ -= Creating a Java MicroServices JPA application - -With `odo`, you can create and manage a sample Java MicroServices JPA application. - -.Procedure - -. Clone the sample application: -+ -[source,terminal] ----- -$ git clone https://github.com/redhat-developer/application-stack-samples ----- - -. Navigate to the application directory: -+ -[source,terminal] ----- -$ cd ./application-stack-samples/jpa ----- - -. Initialize the project: -+ -[source,terminal] ----- -$ odo create java-openliberty java-application ----- - -. Push the application to the cluster: -+ -[source,terminal] ----- -$ odo push ----- -+ -The application is now deployed to the cluster. - -. View the status of the cluster by streaming the OpenShift logs to the terminal: -+ -[source,terminal] ----- -$ odo log ----- -+ -Notice the test failures and `UnknownDatabaseHostException` error. This is because your application does not have a database yet: -+ -[source,terminal] ----- -[INFO] [err] java.net.UnknownHostException: ${DATABASE_CLUSTERIP} -[INFO] [err] at java.base/java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:220) -[INFO] [err] at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:403) -[INFO] [err] at java.base/java.net.Socket.connect(Socket.java:609) -[INFO] [err] at org.postgresql.core.PGStream.<init>(PGStream.java:68) -[INFO] [err] at org.postgresql.core.v3.ConnectionFactoryImpl.openConnectionImpl(ConnectionFactoryImpl.java:144) -[INFO] [err] ... 86 more -[ERROR] Tests run: 2, Failures: 1, Errors: 1, Skipped: 0, Time elapsed: 0.706 s <<< FAILURE! - in org.example.app.it.DatabaseIT -[ERROR] testGetAllPeople Time elapsed: 0.33 s <<< FAILURE! -org.opentest4j.AssertionFailedError: Expected at least 2 people to be registered, but there were only: [] ==> expected: <true> but was: <false> - at org.example.app.it.DatabaseIT.testGetAllPeople(DatabaseIT.java:57) - -[ERROR] testGetPerson Time elapsed: 0.047 s <<< ERROR! -java.lang.NullPointerException - at org.example.app.it.DatabaseIT.testGetPerson(DatabaseIT.java:41) - -[INFO] -[INFO] Results: -[INFO] -[ERROR] Failures: -[ERROR] DatabaseIT.testGetAllPeople:57 Expected at least 2 people to be registered, but there were only: [] ==> expected: <true> but was: <false> -[ERROR] Errors: -[ERROR] DatabaseIT.testGetPerson:41 NullPointer -[INFO] -[ERROR] Tests run: 2, Failures: 1, Errors: 1, Skipped: 0 -[INFO] -[ERROR] Integration tests failed: There are test failures. ----- - -. Create an ingress URL to access the application: -+ -[source,terminal] ----- -$ odo url create --port 8080 ----- - -. Push the changes to your cluster: -+ -[source,terminal] ----- -$ odo push ----- - -. Display the created URL: -+ -[source,terminal] ----- -$ odo url list ----- -+ -.Example output -[source,terminal] ----- -Found the following URLs for component mysboproj -NAME STATE URL PORT SECURE KIND -java-application-8080 Pushed http://java-application-8080.apps-crc.testing 8080 false ingress ----- -+ -The application is now deployed to the cluster and you can access it by using the URL that is created. - -. Use the URL to navigate to the `CreatePerson.xhtml` data entry page and enter a username and age by using the the form. Click *Save*. -+ -Note that you cannot see the data by clicking the *View Persons Record List* link since your application does not have a database connected yet. diff --git a/modules/developer-cli-odo-creating-a-project.adoc b/modules/developer-cli-odo-creating-a-project.adoc deleted file mode 100644 index 734ba0a9b545..000000000000 --- a/modules/developer-cli-odo-creating-a-project.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-single-component-application-with-odo.adoc -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-multicomponent-application-with-odo.adoc -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-projects - -[id="creating-a-project_{context}"] -= Creating a project - -Create a project to keep your source code, tests, and libraries organized in a separate single unit. - -.Procedure - -. Log in to an {product-title} cluster: -+ -[source,terminal] ----- -$ odo login -u developer -p developer ----- - -. Create a project: -+ -[source,terminal] ----- -$ odo project create myproject ----- -+ -.Example output -[source,terminal] ----- - ✓ Project 'myproject' is ready for use - ✓ New project created and now using project : myproject ----- diff --git a/modules/developer-cli-odo-creating-a-service-from-an-operator.adoc b/modules/developer-cli-odo-creating-a-service-from-an-operator.adoc deleted file mode 100644 index debfd096a114..000000000000 --- a/modules/developer-cli-odo-creating-a-service-from-an-operator.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-instances-of-services-managed-by-the-operators.adoc - -[id="creating-a-service-from-an-operator_{context}"] - -= Creating a service from an Operator - -If an Operator has valid values defined in its `metadata` to start the requested service, you can use the service with `odo service create`. - -. Print the YAML of the service as a file on your local drive: -+ -[source,terminal] ----- -$ oc get csv/etcdoperator.v0.9.4 -o yaml ----- - -. Verify that the values of the service are valid: -+ -[source,terminal] ----- -apiVersion: etcd.database.coreos.com/v1beta2 -kind: EtcdCluster -metadata: - name: example -spec: - size: 3 - version: 3.2.13 ----- - -. Start an `EtcdCluster` service from the `etcdoperator.v0.9.4` Operator: -+ -[source,terminal] ----- -$ odo service create etcdoperator.v0.9.4 EtcdCluster ----- - -. Verify that a service has started: -+ -[source,terminal] ----- -$ oc get EtcdCluster ----- diff --git a/modules/developer-cli-odo-creating-and-deploying-a-nodejs-application-with-odo.adoc b/modules/developer-cli-odo-creating-and-deploying-a-nodejs-application-with-odo.adoc deleted file mode 100644 index 93e41f540e37..000000000000 --- a/modules/developer-cli-odo-creating-and-deploying-a-nodejs-application-with-odo.adoc +++ /dev/null @@ -1,106 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-single-component-application-with-odo -// * cli_reference/developer_cli_odo/using-odo-in-a-restricted-environment/creating-and-deploying-a-component-to-the-restricted-cluster -ifeval::["{context}" == "creating-a-single-component-application-with-odo"] -:single: -endif::[] -ifeval::["{context}" == "creating-a-multicomponent-application-with-odo"] -:multi: -endif::[] - -[id="creating-a-nodejs-application-with-odo_{context}"] -= Creating a Node.js application with {odo-title} - -To create a Node.js component, download the Node.js application and push the source code to your cluster with `{odo-title}`. - -.Procedure - -ifdef::single[] - -. Create a directory for your components: -+ -[source,terminal] ----- -$ mkdir my_components && cd my_components ----- - -. Download the example Node.js application: -+ -[source,terminal] ----- -$ git clone https://github.com/openshift/nodejs-ex ----- -endif::single[] - -ifdef::multi[] - -. Download the example front-end application: -+ -[source,terminal] ----- -$ git clone https://github.com/openshift-evangelists/Wild-West-Frontend frontend ----- - -endif::multi[] - - -. Change the current directory to the directory with your application: -+ -[source,terminal] ----- -$ cd <directory_name> ----- - -. Add a component of the type Node.js to your application: -+ -[source,terminal] ----- -$ odo create nodejs ----- -+ -NOTE: By default, the latest image is used. You can also explicitly specify an image version by using `odo create openshift/nodejs:8`. - -. Push the initial source code to the component: -+ -[source,terminal] ----- -$ odo push ----- -+ -Your component is now deployed to {product-title}. - -. Create a URL and add an entry in the local configuration file as follows: -+ -[source,terminal] ----- -$ odo url create --port 8080 ----- -+ -. Push the changes. This creates a URL on the cluster. -+ -[source,terminal] ----- -$ odo push ----- -+ -. List the URLs to check the desired URL for the component. -+ -[source,terminal] ----- -$ odo url list ----- -+ -. View your deployed application using the generated URL. -+ -[source,terminal] ----- -$ curl <url> ----- - -ifeval::["{context}" == "creating-a-single-component-application-with-odo"] -:!single: -endif::[] -ifeval::["{context}" == "creating-a-multicomponent-application-with-odo"] -:!multi: -endif::[] diff --git a/modules/developer-cli-odo-creating-services-from-yaml-files.adoc b/modules/developer-cli-odo-creating-services-from-yaml-files.adoc deleted file mode 100644 index f33b7a9e91e0..000000000000 --- a/modules/developer-cli-odo-creating-services-from-yaml-files.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-instances-of-services-managed-by-the-operators.adoc - -[id="creating-services-from-yaml-files_{context}"] - -= Creating services from YAML files - -If the YAML definition of the service or custom resource (CR) has invalid or placeholder data, you can use the `--dry-run` flag to get the YAML definition, specify the correct values, and start the service using the corrected YAML definition. -Printing and modifying the YAML used to start a service -`{odo-title}` provides the feature to print the YAML definition of the service or CR provided by the Operator before starting a service. - -. To display the YAML of the service, run: -+ -[source,terminal] ----- -$ odo service create <operator-name> --dry-run ----- -+ -For example, to print YAML definition of `EtcdCluster` provided by the `etcdoperator.v0.9.4` Operator, run: -+ -[source,terminal] ----- -$ odo service create etcdoperator.v0.9.4 --dry-run ----- -+ -The YAML is saved as the `etcd.yaml` file. - -. Modify the `etcd.yaml` file: -+ -[source,yaml] ----- -apiVersion: etcd.database.coreos.com/v1beta2 -kind: EtcdCluster -metadata: - name: my-etcd-cluster // <1> -spec: - size: 1 // <2> - version: 3.2.13 ----- -+ -<1> Change the name from `example` to `my-etcd-cluster` -<2> Reduce the size from `3` to `1` - -. Start a service from the YAML file: -+ -[source,terminal] ----- -$ odo service create --from-file etcd.yaml ----- - -. Verify that the `EtcdCluster` service has started with one pod instead of the pre-configured three pods: -+ -[source,terminal] ----- -$ oc get pods | grep my-etcd-cluster ----- diff --git a/modules/developer-cli-odo-debugging-an-application.adoc b/modules/developer-cli-odo-debugging-an-application.adoc deleted file mode 100644 index 7ddd9b03a1d1..000000000000 --- a/modules/developer-cli-odo-debugging-an-application.adoc +++ /dev/null @@ -1,102 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/creating_and_deploying_applications_with_odo/debugging-applications-in-odo.adoc - -[id="debugging-an-application_{context}"] - -= Debugging an application - -You can debug your application in `odo` with the `odo debug` command. - -.Procedure - -. Download the sample application that contains the necessary `debugrun` step within its devfile: -+ -[source,terminal] ----- -$ odo create nodejs --starter ----- -+ -.Example output -[source,terminal] ----- -Validation - ✓ Checking devfile existence [11498ns] - ✓ Checking devfile compatibility [15714ns] - ✓ Creating a devfile component from registry: DefaultDevfileRegistry [17565ns] - ✓ Validating devfile component [113876ns] - -Starter Project - ✓ Downloading starter project nodejs-starter from https://github.com/odo-devfiles/nodejs-ex.git [428ms] - -Please use `odo push` command to create the component with source deployed ----- - -. Push the application with the `--debug` flag, which is required for all debugging deployments: -+ -[source,terminal] ----- -$ odo push --debug ----- -+ -.Example output -[source,terminal] ----- -Validation - ✓ Validating the devfile [29916ns] - -Creating Kubernetes resources for component nodejs - ✓ Waiting for component to start [38ms] - -Applying URL changes - ✓ URLs are synced with the cluster, no changes are required. - -Syncing to component nodejs - ✓ Checking file changes for pushing [1ms] - ✓ Syncing files to the component [778ms] - -Executing devfile commands for component nodejs - ✓ Executing install command "npm install" [2s] - ✓ Executing debug command "npm run debug" [1s] - -Pushing devfile component nodejs - ✓ Changes successfully pushed to component ----- -+ -[NOTE] -==== -You can specify a custom debug command by using the `--debug-command="custom-step"` flag. -==== - -. Port forward to the local port to access the debugging interface: -+ -[source,terminal] ----- -$ odo debug port-forward ----- -+ -.Example output -[source,terminal] ----- -Started port forwarding at ports - 5858:5858 ----- -+ -[NOTE] -==== -You can specify a port by using the `--local-port` flag. -==== - -. Check that the debug session is running in a separate terminal window: -+ -[source,terminal] ----- -$ odo debug info ----- -+ -.Example output -[source,terminal] ----- -Debug is running for the component on the local port : 5858 ----- - -. Attach the debugger that is bundled in your IDE of choice. Instructions vary depending on your IDE, for example: link:https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_remote-debugging[VSCode debugging interface]. diff --git a/modules/developer-cli-odo-deleting-an-application.adoc b/modules/developer-cli-odo-deleting-an-application.adoc deleted file mode 100644 index ee0ebe8fe1b5..000000000000 --- a/modules/developer-cli-odo-deleting-an-application.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-single-component-application-with-odo.adoc -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-multicomponent-application-with-odo.adoc - -[id="deleting-an-application_{context}"] -= Deleting an application - -Use the `odo app delete` command to delete your application. - -.Procedure - -. List the applications in the current project: -+ -[source,terminal] ----- -$ odo app list ----- -+ -.Example output -[source,terminal] ----- - The project '<project_name>' has the following applications: - NAME - app ----- - -. List the components associated with the applications. These components will be deleted with the application: -+ -[source,terminal] ----- -$ odo component list ----- -+ -.Example output -[source,terminal] ----- - APP NAME TYPE SOURCE STATE - app nodejs-nodejs-ex-elyf nodejs file://./ Pushed ----- - -. Delete the application: -+ -[source,terminal] ----- -$ odo app delete <application_name> ----- -+ -.Example output -[source,terminal] ----- - ? Are you sure you want to delete the application: <application_name> from project: <project_name> ----- -. Confirm the deletion with `Y`. You can suppress the confirmation prompt using the `-f` flag. diff --git a/modules/developer-cli-odo-deploying-a-database-in-interactive-mode.adoc b/modules/developer-cli-odo-deploying-a-database-in-interactive-mode.adoc deleted file mode 100644 index 7f3ef1e80e92..000000000000 --- a/modules/developer-cli-odo-deploying-a-database-in-interactive-mode.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc - -[id="deploying-a-database-in-interactive-mode_{context}"] -= Deploying a database in interactive mode - -{odo-title} provides a command-line interactive mode which simplifies deployment. - -.Procedure - -* Run the interactive mode and answer the prompts: -+ -[source,terminal] ----- -$ odo service create ----- -+ -.Example output -[source,terminal] ----- -? Which kind of service do you wish to create database -? Which database service class should we use mongodb-persistent -? Enter a value for string property DATABASE_SERVICE_NAME (Database Service Name): mongodb -? Enter a value for string property MEMORY_LIMIT (Memory Limit): 512Mi -? Enter a value for string property MONGODB_DATABASE (MongoDB Database Name): sampledb -? Enter a value for string property MONGODB_VERSION (Version of MongoDB Image): 3.2 -? Enter a value for string property VOLUME_CAPACITY (Volume Capacity): 1Gi -? Provide values for non-required properties No -? How should we name your service mongodb-persistent -? Output the non-interactive version of the selected options No -? Wait for the service to be ready No - ✓ Creating service [32ms] - ✓ Service 'mongodb-persistent' was created -Progress of the provisioning will not be reported and might take a long time. -You can see the current status by executing 'odo service list' ----- - -[NOTE] -==== -Your password or username will be passed to the front-end application as environment variables. -==== diff --git a/modules/developer-cli-odo-deploying-a-database-manually.adoc b/modules/developer-cli-odo-deploying-a-database-manually.adoc deleted file mode 100644 index 8a2f83462279..000000000000 --- a/modules/developer-cli-odo-deploying-a-database-manually.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc - -[id="deploying-a-database-manually_{context}"] -= Deploying a database manually - -. List the available services: -+ -[source,terminal] ----- -$ odo catalog list services ----- -+ -.Example output -[source,terminal] ----- -NAME PLANS -django-psql-persistent default -jenkins-ephemeral default -jenkins-pipeline-example default -mariadb-persistent default -mongodb-persistent default -mysql-persistent default -nodejs-mongo-persistent default -postgresql-persistent default -rails-pgsql-persistent default ----- - -. Choose the `mongodb-persistent` type of service and see the required parameters: -+ -[source,terminal] ----- -$ odo catalog describe service mongodb-persistent ----- -+ -.Example output -[source,terminal] ----- - *********************** | ***************************************************** - Name | default - ----------------- | ----------------- - Display Name | - ----------------- | ----------------- - Short Description | Default plan - ----------------- | ----------------- - Required Params without a | - default value | - ----------------- | ----------------- - Required Params with a default | DATABASE_SERVICE_NAME - value | (default: 'mongodb'), - | MEMORY_LIMIT (default: - | '512Mi'), MONGODB_VERSION - | (default: '3.2'), - | MONGODB_DATABASE (default: - | 'sampledb'), VOLUME_CAPACITY - | (default: '1Gi') - ----------------- | ----------------- - Optional Params | MONGODB_ADMIN_PASSWORD, - | NAMESPACE, MONGODB_PASSWORD, - | MONGODB_USER ----- - -. Pass the required parameters as flags and wait for the deployment of the database: -+ -[source,terminal] ----- -$ odo service create mongodb-persistent --plan default --wait -p DATABASE_SERVICE_NAME=mongodb -p MEMORY_LIMIT=512Mi -p MONGODB_DATABASE=sampledb -p VOLUME_CAPACITY=1Gi ----- diff --git a/modules/developer-cli-odo-deploying-a-java-application-using-a-devfile.adoc b/modules/developer-cli-odo-deploying-a-java-application-using-a-devfile.adoc deleted file mode 100644 index ed05cef9edf4..000000000000 --- a/modules/developer-cli-odo-deploying-a-java-application-using-a-devfile.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -// cli_reference/developer_cli_odo/creating-a-java-application-using-devfile - -[id="deploying-a-java-application-using-a-devfile_{context}"] -= Deploying a Java application using a devfile - -In this section, you will learn how to deploy a sample Java project that uses Maven and Java 8 JDK using a devfile. - -.Procedure - -. Create a directory to store the source code of your component: -+ -[source,terminal] ----- -$ mkdir <directory-name> ----- - -. Create a component configuration of Spring Boot component type named `myspring` and download its sample project: -+ -[source,terminal] ----- -$ odo create java-spring-boot myspring --starter ----- -+ -The previous command produces the following output: -+ -[source,terminal] ----- -Validation -✓ Checking devfile compatibility [195728ns] -✓ Creating a devfile component from registry: DefaultDevfileRegistry [170275ns] -✓ Validating devfile component [281940ns] - -Please use `odo push` command to create the component with source deployed ----- -+ -The `odo create` command downloads the associated `devfile.yaml` file from the recorded devfile registries. - -. List the contents of the directory to confirm that the devfile and the sample Java application were downloaded: -+ -[source,terminal] ----- -$ ls ----- -+ -The previous command produces the following output: -+ -[source,terminal] ----- -README.md devfile.yaml pom.xml src ----- - -. Create a URL to access the deployed component: -+ -[source,terminal] ----- -$ odo url create --host apps-crc.testing ----- -+ -The previous command produces the following output: -+ -[source,terminal] ----- -✓ URL myspring-8080.apps-crc.testing created for component: myspring - -To apply the URL configuration changes, please use odo push ----- -+ -NOTE: You must use your cluster host domain name when creating the URL. - -. Push the component to the cluster: -+ -[source,terminal] ----- -$ odo push ----- -+ -The previous command produces the following output: -+ -[source,terminal] ----- -Validation - ✓ Validating the devfile [81808ns] - -Creating Kubernetes resources for component myspring - ✓ Waiting for component to start [5s] - -Applying URL changes - ✓ URL myspring-8080: http://myspring-8080.apps-crc.testing created - -Syncing to component myspring - ✓ Checking files for pushing [2ms] - ✓ Syncing files to the component [1s] - -Executing devfile commands for component myspring - ✓ Executing devbuild command "/artifacts/bin/build-container-full.sh" [1m] - ✓ Executing devrun command "/artifacts/bin/start-server.sh" [2s] - -Pushing devfile component myspring - ✓ Changes successfully pushed to component ----- - -. List the URLs of the component to verify that the component was pushed successfully: -+ -[source,terminal] ----- -$ odo url list ----- -+ -The previous command produces the following output: -+ -[source,terminal] ----- -Found the following URLs for component myspring -NAME URL PORT SECURE -myspring-8080 http://myspring-8080.apps-crc.testing 8080 false ----- - -. View your deployed application by using the generated URL: -+ -[source,terminal] ----- -$ curl http://myspring-8080.apps-crc.testing ----- diff --git a/modules/developer-cli-odo-deploying-the-back-end-component.adoc b/modules/developer-cli-odo-deploying-the-back-end-component.adoc deleted file mode 100644 index 6fdc30c05d34..000000000000 --- a/modules/developer-cli-odo-deploying-the-back-end-component.adoc +++ /dev/null @@ -1,213 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-multicomponent-application-with-odo.adoc - -[id="deploying-the-back-end-component_{context}"] - -= Deploying the back-end component - -To create a Java component, import the Java builder image, download the Java application and push the source code to your cluster with `{odo-title}`. - -.Procedure - -. Import `openjdk18` into the cluster: -+ -[source,terminal] ----- -$ oc import-image openjdk18 \ ---from=registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift --confirm ----- - -. Tag the image as `builder` to make it accessible for {odo-title}: -+ -[source,terminal] ----- -$ oc annotate istag/openjdk18:latest tags=builder ----- - -. Run `odo catalog list components` to see the created image: -+ -[source,terminal] ----- -$ odo catalog list components ----- -+ -.Example output -[source,terminal] ----- -Odo Devfile Components: -NAME DESCRIPTION REGISTRY -java-maven Upstream Maven and OpenJDK 11 DefaultDevfileRegistry -java-openliberty Open Liberty microservice in Java DefaultDevfileRegistry -java-quarkus Upstream Quarkus with Java+GraalVM DefaultDevfileRegistry -java-springboot Spring Boot® using Java DefaultDevfileRegistry -nodejs Stack with NodeJS 12 DefaultDevfileRegistry - -Odo OpenShift Components: -NAME PROJECT TAGS SUPPORTED -java openshift 11,8,latest YES -dotnet openshift 2.1,3.1,latest NO -golang openshift 1.13.4-ubi7,1.13.4-ubi8,latest NO -httpd openshift 2.4-el7,2.4-el8,latest NO -nginx openshift 1.14-el7,1.14-el8,1.16-el7,1.16-el8,latest NO -nodejs openshift 10-ubi7,10-ubi8,12-ubi7,12-ubi8,latest NO -perl openshift 5.26-el7,5.26-ubi8,5.30-el7,latest NO -php openshift 7.2-ubi7,7.2-ubi8,7.3-ubi7,7.3-ubi8,latest NO -python openshift 2.7-ubi7,2.7-ubi8,3.6-ubi7,3.6-ubi8,3.8-ubi7,3.8-ubi8,latest NO -ruby openshift 2.5-ubi7,2.5-ubi8,2.6-ubi7,2.6-ubi8,2.7-ubi7,latest NO -wildfly openshift 10.0,10.1,11.0,12.0,13.0,14.0,15.0,16.0,17.0,18.0,19.0,20.0,8.1,9.0,latest NO ----- - -. Create a directory for your components: -+ -[source,terminal] ----- -$ mkdir my_components && cd my_components ----- - -. Download the example back-end application: -+ -[source,terminal] ----- -$ git clone https://github.com/openshift-evangelists/Wild-West-Backend backend ----- - -. Change to the back-end source directory: -+ -[source,terminal] ----- -$ cd backend ----- - -. Check that you have the correct files in the directory: -+ -[source,terminal] ----- -$ ls ----- -+ -.Example output -[source,terminal] ----- -debug.sh pom.xml src ----- - -. Build the back-end source files with Maven to create a JAR file: -+ -[source,terminal] ----- -$ mvn package ----- -+ -.Example output -[source,terminal] ----- -... -[INFO] -------------------------------------- -[INFO] BUILD SUCCESS -[INFO] -------------------------------------- -[INFO] Total time: 2.635 s -[INFO] Finished at: 2019-09-30T16:11:11-04:00 -[INFO] Final Memory: 30M/91M -[INFO] -------------------------------------- ----- - -. Create a component configuration of Java component-type named `backend`: -+ -[source,terminal] ----- -$ odo create --s2i openjdk18 backend --binary target/wildwest-1.0.jar ----- -+ -.Example output -[source,terminal] ----- - ✓ Validating component [1ms] - Please use `odo push` command to create the component with source deployed ----- -+ -Now the configuration file `config.yaml` is in the local directory of the back-end component that contains information about the component for deployment. - -. Check the configuration settings of the back-end component in the `config.yaml` file using: -+ -[source,terminal] ----- -$ odo config view ----- -+ -.Example output -[source,terminal] ----- -COMPONENT SETTINGS ------------------------------------------------- -PARAMETER CURRENT_VALUE -Type openjdk18 -Application app -Project myproject -SourceType binary -Ref -SourceLocation target/wildwest-1.0.jar -Ports 8080/TCP,8443/TCP,8778/TCP -Name backend -MinMemory -MaxMemory -DebugPort -Ignore -MinCPU -MaxCPU ----- - -. Push the component to the {product-title} cluster. -+ -[source,terminal] ----- -$ odo push ----- -+ -.Example output -[source,terminal] ----- -Validation - ✓ Checking component [6ms] - -Configuration changes - ✓ Initializing component - ✓ Creating component [124ms] - -Pushing to component backend of type binary - ✓ Checking files for pushing [1ms] - ✓ Waiting for component to start [48s] - ✓ Syncing files to the component [811ms] - ✓ Building component [3s] ----- -+ -Using `odo push`, {product-title} creates a container to host the back-end component, deploys the container into a pod running on the {product-title} cluster, and starts the `backend` component. - -. Validate: - -* The status of the action in {odo-title}: -+ -[source,terminal] ----- -$ odo log -f ----- -+ -.Example output -[source,terminal] ----- -2019-09-30 20:14:19.738 INFO 444 --- [ main] c.o.wildwest.WildWestApplication : Starting WildWestApplication v1.0 onbackend-app-1-9tnhc with PID 444 (/deployments/wildwest-1.0.jar started by jboss in /deployments) ----- - -* The status of the back-end component: -+ -[source,terminal] ----- -$ odo list ----- -+ -.Example output -[source,terminal] ----- -APP NAME TYPE SOURCE STATE -app backend openjdk18 file://target/wildwest-1.0.jar Pushed ----- diff --git a/modules/developer-cli-odo-deploying-the-front-end-component.adoc b/modules/developer-cli-odo-deploying-the-front-end-component.adoc deleted file mode 100644 index 8ac13b4dfdfa..000000000000 --- a/modules/developer-cli-odo-deploying-the-front-end-component.adoc +++ /dev/null @@ -1,143 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-multicomponent-application-with-odo.adoc -// * cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-an-application-with-a-database.adoc - -ifeval::["{context}" == "creating-a-multicomponent-application-with-odo"] -:multi: -endif::[] -ifeval::["{context}" == "creating-an-application-with-a-database"] -:database: -endif::[] - -[id="deploying-the-front-end-component_{context}"] - -= Deploying the front-end component - -To create and deploy a front-end component, download the Node.js application and push the source code to your cluster with `{odo-title}`. - -.Procedure - -. Download the example front-end application: -+ -[source,terminal] ----- -$ git clone https://github.com/openshift/nodejs-ex frontend ----- - -. Change the current directory to the front-end directory: -+ -[source,terminal] ----- -$ cd frontend ----- - -. List the contents of the directory to see that the front end is a Node.js application. -+ -[source,terminal] ----- -$ ls ----- -+ -.Example output -[source,terminal] ----- -README.md openshift server.js views -helm package.json tests ----- -+ -[NOTE] -==== -The front-end component is written in an interpreted language (Node.js); it does not need to be built. -==== - -. Create a component configuration of Node.js component-type named `frontend`: -+ -[source,terminal] ----- -$ odo create --s2i nodejs frontend ----- -+ -.Example output -[source,terminal] ----- - ✓ Validating component [5ms] -Please use `odo push` command to create the component with source deployed ----- - -ifdef::database[] -. Create a URL to access the frontend interface. -+ -[source,terminal] ----- -$ odo url create myurl ----- -+ -.Example output -[source,terminal] ----- - ✓ URL myurl created for component: nodejs-nodejs-ex-pmdp ----- - -. Push the component to the {product-title} cluster. -+ -[source,terminal] ----- -$ odo push ----- -+ -.Example output -[source,terminal] ----- -Validation - ✓ Checking component [7ms] - - Configuration changes - ✓ Initializing component - ✓ Creating component [134ms] - - Applying URL changes - ✓ URL myurl: http://myurl-app-myproject.192.168.42.79.nip.io created - - Pushing to component nodejs-nodejs-ex-mhbb of type local - ✓ Checking files for pushing [657850ns] - ✓ Waiting for component to start [6s] - ✓ Syncing files to the component [408ms] - ✓ Building component [7s] - ✓ Changes successfully pushed to component ----- -endif::database[] - -ifdef::multi[] -. Push the component to a running container. -+ -[source,terminal] ----- -$ odo push ----- -+ -.Example output -[source,terminal] ----- -Validation - ✓ Checking component [8ms] - -Configuration changes - ✓ Initializing component - ✓ Creating component [83ms] - -Pushing to component frontend of type local - ✓ Checking files for pushing [2ms] - ✓ Waiting for component to start [45s] - ✓ Syncing files to the component [3s] - ✓ Building component [18s] - ✓ Changes successfully pushed to component ----- -endif::multi[] - -ifeval::["{context}" == "creating-a-multicomponent-application-with-odo"] -:!multi: -endif::[] -ifeval::["{context}" == "creating-an-application-with-a-database"] -:!database: -endif::[] diff --git a/modules/developer-cli-odo-developer-setup.adoc b/modules/developer-cli-odo-developer-setup.adoc deleted file mode 100644 index a4625f8f8ca2..000000000000 --- a/modules/developer-cli-odo-developer-setup.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/odo-architecture.adoc - -[id="developer-setup_{context}"] - -= Developer setup - -With {odo-title} you can create and deploy application on {product-title} clusters from a terminal. Code editor plug-ins use {odo-title} which allows users to interact with {product-title} clusters from their IDE terminals. Examples of plug-ins that use {odo-title}: VS Code OpenShift Connector, OpenShift Connector for Intellij, Codewind for Eclipse Che. - -{odo-title} works on Windows, macOS, and Linux operating systems and from any terminal. {odo-title} provides autocompletion for bash and zsh command line shells. - -{odo-title} supports Node.js and Java components. diff --git a/modules/developer-cli-odo-exposing-the-components-to-the-public.adoc b/modules/developer-cli-odo-exposing-the-components-to-the-public.adoc deleted file mode 100644 index 183df785d746..000000000000 --- a/modules/developer-cli-odo-exposing-the-components-to-the-public.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-multicomponent-application-with-odo.adoc - -[id="exposing-the-components-to-the-public_{context}"] - -= Exposing components to the public - -.Procedure - -. Navigate to the `frontend` directory: -+ -[source,terminal] ----- -$ cd frontend ----- - -. Create an external URL for the application: -+ -[source,terminal] ----- -$ odo url create frontend --port 8080 ----- -+ -.Example output -[source,terminal] ----- - ✓ URL frontend created for component: frontend - -To create URL on the OpenShift cluster, use `odo push` ----- - -. Apply the changes: -+ -[source,terminal] ----- -$ odo push ----- -+ -.Example output -[source,terminal] ----- -Validation - ✓ Checking component [21ms] - -Configuration changes - ✓ Retrieving component data [35ms] - ✓ Applying configuration [29ms] - -Applying URL changes - ✓ URL frontend: http://frontend-app-myproject.192.168.42.79.nip.io created - -Pushing to component frontend of type local - ✓ Checking file changes for pushing [1ms] - ✓ No file changes detected, skipping build. Use the '-f' flag to force the build. ----- - -. Open the URL in a browser to view the application. - -[NOTE] -==== -If an application requires permissions to the active service account to access the {product-title} namespace and delete active pods, the following error may occur when looking at `odo log` from the back-end component: - -`Message: Forbidden!Configured service account doesn't have access. Service account may have been revoked` - -To resolve this error, add permissions for the service account role: - -[source,terminal] ----- -$ oc policy add-role-to-group view system:serviceaccounts -n <project> ----- - -[source,terminal] ----- -$ oc policy add-role-to-group edit system:serviceaccounts -n <project> ----- - -Do not do this on a production cluster. -==== diff --git a/modules/developer-cli-odo-ignoring-files-or-patterns.adoc b/modules/developer-cli-odo-ignoring-files-or-patterns.adoc deleted file mode 100644 index 66b6f6808461..000000000000 --- a/modules/developer-cli-odo-ignoring-files-or-patterns.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/configuring-the-odo-cli.adoc - -[id="ignoring-files-or-patterns_{context}"] -= Ignoring files or patterns - -You can configure a list of files or patterns to ignore by modifying the `.odoignore` file in the root directory of your application. This applies to both `odo push` and `odo watch`. - -If the `.odoignore` file does _not_ exist, the `.gitignore` file is used instead for ignoring specific files and folders. - -To ignore `.git` files, any files with the `.js` extension, and the folder `tests`, add the following to either the `.odoignore` or the `.gitignore` file: - ----- -.git -*.js -tests/ ----- - -The `.odoignore` file allows any glob expressions. \ No newline at end of file diff --git a/modules/developer-cli-odo-installing-odo-on-linux-on-ibm-power.adoc b/modules/developer-cli-odo-installing-odo-on-linux-on-ibm-power.adoc deleted file mode 100644 index 34fd462aec70..000000000000 --- a/modules/developer-cli-odo-installing-odo-on-linux-on-ibm-power.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/installing-odo.adoc - -[id="installing-odo-on-linux-on-ibm-power_{context}"] -= Installing {odo-title} on Linux on IBM Power - -[id="installing-odo-on-linux-on-ibm-power-binary_{context}"] -== Binary installation - -.Procedure - -. Obtain the binary: -+ -[source,terminal] ----- -# curl -L https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-linux-ppc64le -o /usr/local/bin/odo ----- - -. Change the permissions on the file: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/odo ----- - -[id="installing-odo-on-linux-on-ibm-power-tarball_{context}"] -== Tarball installation - -.Procedure - -. Obtain the tarball: -+ -[source,terminal] ----- -# sh -c 'curl -L https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-linux-ppc64le.tar.gz | gzip -d > /usr/local/bin/odo' ----- - -. Change the permissions on the file: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/odo ----- diff --git a/modules/developer-cli-odo-installing-odo-on-linux-on-ibm-z.adoc b/modules/developer-cli-odo-installing-odo-on-linux-on-ibm-z.adoc deleted file mode 100644 index 55fadc9572e9..000000000000 --- a/modules/developer-cli-odo-installing-odo-on-linux-on-ibm-z.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/installing-odo.adoc - -[id="installing-odo-on-linux-on-ibm-z"] - -= Installing {odo-title} on Linux on IBM Z and LinuxONE - -== Binary installation - -.Procedure - -. Obtain the binary: -+ -[source,terminal] ----- -# curl -L https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-linux-s390x -o /usr/local/bin/odo ----- - -. Change the permissions on the file: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/odo ----- - -== Tarball installation - -.Procedure - -. Obtain the tarball: -+ -[source,terminal] ----- -# sh -c 'curl -L https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-linux-s390x.tar.gz | gzip -d > /usr/local/bin/odo' ----- - -. Change the permissions on the file: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/odo ----- diff --git a/modules/developer-cli-odo-installing-odo-on-linux.adoc b/modules/developer-cli-odo-installing-odo-on-linux.adoc deleted file mode 100644 index e774c6e3edf3..000000000000 --- a/modules/developer-cli-odo-installing-odo-on-linux.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/installing-odo.adoc - -[id="installing-odo-on-linux_{context}"] - -= Installing {odo-title} on Linux - -== Binary installation - -.Procedure - -. Obtain the binary: -+ -[source,terminal] ----- -# curl -L https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-linux-amd64 -o /usr/local/bin/odo ----- - -. Change the permissions on the file: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/odo ----- - -== Tarball installation - -.Procedure - -. Obtain the tarball: -+ -[source,terminal] ----- -# sh -c 'curl -L https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-linux-amd64.tar.gz | gzip -d > /usr/local/bin/odo' ----- - -. Change the permissions on the file: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/odo ----- diff --git a/modules/developer-cli-odo-installing-odo-on-macos.adoc b/modules/developer-cli-odo-installing-odo-on-macos.adoc deleted file mode 100644 index 6fa0e1721231..000000000000 --- a/modules/developer-cli-odo-installing-odo-on-macos.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/installing-odo.adoc - -[id="installing-odo-on-macos_{context}"] - -= Installing {odo-title} on macOS - -== Binary installation - -.Procedure - -. Obtain the binary: -+ -[source,terminal] ----- -# curl -L https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-darwin-amd64 -o /usr/local/bin/odo ----- - -. Change the permissions on the file: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/odo ----- - -== Tarball installation - -.Procedure - -. Obtain the tarball: -+ -[source,terminal] ----- -# sh -c 'curl -L https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-darwin-amd64.tar.gz | gzip -d > /usr/local/bin/odo' ----- - -. Change the permissions on the file: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/odo ----- diff --git a/modules/developer-cli-odo-installing-odo-on-vs-code.adoc b/modules/developer-cli-odo-installing-odo-on-vs-code.adoc deleted file mode 100644 index 0e1d34fc483f..000000000000 --- a/modules/developer-cli-odo-installing-odo-on-vs-code.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/installing-odo.adoc - -[id="installing-odo-on-vs-code_{context}"] - -= Installing odo on VS Code - -The https://marketplace.visualstudio.com/items?itemName=redhat.vscode-openshift-connector[OpenShift VS Code extension] uses both `odo` and the `oc` binary to interact with your {product-title} cluster. To work with these features, install the OpenShift VS Code extension on VS Code. - -.Prerequisites - -* You have installed VS Code. - -.Procedure - -. Open VS Code. - -. Launch VS Code Quick Open with `Ctrl`+`P`. - -. Enter the following command: -+ ----- -$ ext install redhat.vscode-openshift-connector ----- diff --git a/modules/developer-cli-odo-installing-odo-on-windows.adoc b/modules/developer-cli-odo-installing-odo-on-windows.adoc deleted file mode 100644 index 7030c7fc5e90..000000000000 --- a/modules/developer-cli-odo-installing-odo-on-windows.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/installing-odo.adoc - -[id="installing-odo-on-windows_{context}"] - -= Installing {odo-title} on Windows - -== Binary installation - -. Download the latest link:https://mirror.openshift.com/pub/openshift-v4/clients/odo/latest/odo-windows-amd64.exe[`odo.exe`] file. -. Add the location of your `odo.exe` to your `GOPATH/bin` directory. - -[discrete] -== Setting the `PATH` variable for Windows 7/8 - -The following example demonstrates how to set up a path variable. Your binaries can be located in any location, but this example uses `C:\go-bin` as the location. - -. Create a folder at `C:\go-bin`. -. Right click *Start* and click *Control Panel*. -. Select *System and Security* and then click *System*. -. From the menu on the left, select the *Advanced systems settings* and click the *Environment Variables* button at the bottom. -. Select *Path* from the *Variable* section and click *Edit*. -. Click *New* and type `C:\go-bin` into the field or click *Browse* and select the directory, and click *OK*. - -[discrete] -== Setting the `PATH` variable for Windows 10 - -Edit `Environment Variables` using search: - -. Click *Search* and type `env` or `environment`. -. Select *Edit environment variables for your account*. -. Select *Path* from the *Variable* section and click *Edit*. -. Click *New* and type `C:\go-bin` into the field or click *Browse* and select the directory, and click *OK*. diff --git a/modules/developer-cli-odo-linking-both-components.adoc b/modules/developer-cli-odo-linking-both-components.adoc deleted file mode 100644 index 0d1753879c42..000000000000 --- a/modules/developer-cli-odo-linking-both-components.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-multicomponent-application-with-odo.adoc -[id="linking-both-components_{context}"] - -= Linking both components - -Components running on the cluster need to be connected to interact. {product-title} provides linking mechanisms to publish communication bindings from a program to its clients. - -.Procedure - -. List all the components that are running on the cluster: -+ -[source,terminal] ----- -$ odo list ----- -+ -.Example output -[source,terminal] ----- -OpenShift Components: -APP NAME PROJECT TYPE SOURCETYPE STATE -app backend testpro openjdk18 binary Pushed -app frontend testpro nodejs local Pushed ----- - - -. Link the current front-end component to the back end: -+ -[source,terminal] ----- -$ odo link backend --port 8080 ----- -+ -.Example output -[source,terminal] ----- - ✓ Component backend has been successfully linked from the component frontend - -Following environment variables were added to frontend component: -- COMPONENT_BACKEND_HOST -- COMPONENT_BACKEND_PORT ----- -+ -The configuration information of the back-end component is added to the front-end component and the front-end component restarts. diff --git a/modules/developer-cli-odo-listing-available-devfile-components.adoc b/modules/developer-cli-odo-listing-available-devfile-components.adoc deleted file mode 100644 index 7776cda4083f..000000000000 --- a/modules/developer-cli-odo-listing-available-devfile-components.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// cli_reference/developer_cli_odo/creating-a-java-application-using-devfile - -[id="listing-available-devfile-components_{context}"] -= Listing available devfile components - -With `{odo-title}`, you can display all the components that are available for you on the cluster. Components that are available depend on the configuration of your cluster. - -.Procedure - -. To list available devfile components on your cluster, run: -+ -[source,terminal] ----- -$ odo catalog list components ----- -+ -The output lists the available `{odo-title}` components: -+ -[source,terminal] ----- -Odo Devfile Components: -NAME DESCRIPTION REGISTRY -java-maven Upstream Maven and OpenJDK 11 DefaultDevfileRegistry -java-openliberty Open Liberty microservice in Java DefaultDevfileRegistry -java-quarkus Upstream Quarkus with Java+GraalVM DefaultDevfileRegistry -java-springboot Spring Boot® using Java DefaultDevfileRegistry -nodejs Stack with NodeJS 12 DefaultDevfileRegistry - -Odo OpenShift Components: -NAME PROJECT TAGS SUPPORTED -java openshift 11,8,latest YES -dotnet openshift 2.1,3.1,latest NO -golang openshift 1.13.4-ubi7,1.13.4-ubi8,latest NO -httpd openshift 2.4-el7,2.4-el8,latest NO -nginx openshift 1.14-el7,1.14-el8,1.16-el7,1.16-el8,latest NO -nodejs openshift 10-ubi7,10-ubi8,12-ubi7,12-ubi8,latest NO -perl openshift 5.26-el7,5.26-ubi8,5.30-el7,latest NO -php openshift 7.2-ubi7,7.2-ubi8,7.3-ubi7,7.3-ubi8,latest NO -python openshift 2.7-ubi7,2.7-ubi8,3.6-ubi7,3.6-ubi8,3.8-ubi7,3.8-ubi8,latest NO -ruby openshift 2.5-ubi7,2.5-ubi8,2.6-ubi7,2.6-ubi8,2.7-ubi7,latest NO -wildfly openshift 10.0,10.1,11.0,12.0,13.0,14.0,15.0,16.0,17.0,18.0,19.0,20.0,8.1,9.0,latest NO ----- diff --git a/modules/developer-cli-odo-listing-available-services-from-the-operators-installed-on-the-cluster.adoc b/modules/developer-cli-odo-listing-available-services-from-the-operators-installed-on-the-cluster.adoc deleted file mode 100644 index 07b5c2f44682..000000000000 --- a/modules/developer-cli-odo-listing-available-services-from-the-operators-installed-on-the-cluster.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-instances-of-services-managed-by-the-operators.adoc - -[id="listing-available-services-from-the-operators-installed-on-the-cluster_{context}"] - -= Listing available services from the Operators installed on the cluster - -With `{odo-title}`, you can display the list of the Operators installed on your cluster, and the services they provide. - -* To list the Operators installed in current project, run: -+ -[source,terminal] ----- -$ odo catalog list services ----- -+ -The command lists Operators and the CRDs. -The output of the command shows the Operators installed on your cluster. For example: -+ -[source,terminal] ----- -Operators available in the cluster -NAME CRDs -etcdoperator.v0.9.4 EtcdCluster, EtcdBackup, EtcdRestore -mongodb-enterprise.v1.4.5 MongoDB, MongoDBUser, MongoDBOpsManager ----- -+ -`etcdoperator.v0.9.4` is the Operator, `EtcdCluster`, `EtcdBackup` and `EtcdRestore` are the CRDs provided by the Operator. diff --git a/modules/developer-cli-odo-mirroring-a-supported-builder-image.adoc b/modules/developer-cli-odo-mirroring-a-supported-builder-image.adoc deleted file mode 100644 index 66aaa6f76e76..000000000000 --- a/modules/developer-cli-odo-mirroring-a-supported-builder-image.adoc +++ /dev/null @@ -1,92 +0,0 @@ -// Module included in the following assemblies: -// -// cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster - -[id="mirroring-a-supported-builder-image_{context}"] -= Mirroring a supported builder image - -To use npm packages for Node.js dependencies and Maven packages for Java dependencies and configure a runtime environment for your application, you must mirror a respective builder image from the mirror registry. - - -.Procedure - -. Verify that the required images tag is not imported: -+ -[source,terminal] ----- -$ oc describe is nodejs -n openshift ----- -+ -.Example output -[source,terminal] ----- -Name: nodejs -Namespace: openshift -[...] - -10 - tagged from <mirror-registry>:<port>/rhoar-nodejs/nodejs-10 - prefer registry pullthrough when referencing this tag - - Build and run Node.js 10 applications on RHEL 7. For more information about using this builder image, including OpenShift considerations, see https://github.com/nodeshift/centos7-s2i-nodejs. - Tags: builder, nodejs, hidden - Example Repo: https://github.com/sclorg/nodejs-ex.git - - ! error: Import failed (NotFound): dockerimage.image.openshift.io "<mirror-registry>:<port>/rhoar-nodejs/nodejs-10:latest" not found - About an hour ago - -10-SCL (latest) - tagged from <mirror-registry>:<port>/rhscl/nodejs-10-rhel7 - prefer registry pullthrough when referencing this tag - - Build and run Node.js 10 applications on RHEL 7. For more information about using this builder image, including OpenShift considerations, see https://github.com/nodeshift/centos7-s2i-nodejs. - Tags: builder, nodejs - Example Repo: https://github.com/sclorg/nodejs-ex.git - - ! error: Import failed (NotFound): dockerimage.image.openshift.io "<mirror-registry>:<port>/rhscl/nodejs-10-rhel7:latest" not found - About an hour ago - -[...] ----- - -. Mirror the supported image tag to the private registry: -+ -[source,terminal] ----- -$ oc image mirror registry.access.redhat.com/rhscl/nodejs-10-rhel7:<tag> <private_registry>/rhscl/nodejs-10-rhel7:<tag> ----- - -. Import the image: -+ -[source,terminal] ----- -$ oc tag <mirror-registry>:<port>/rhscl/nodejs-10-rhel7:<tag> nodejs-10-rhel7:latest --scheduled ----- -+ -You must periodically re-import the image. The `--scheduled` flag enables automatic re-import of the image. - -. Verify that the images with the given tag have been imported: -+ -[source,terminal] ----- -$ oc describe is nodejs -n openshift ----- -+ -.Example output -[source,terminal] ----- -Name: nodejs -[...] -10-SCL (latest) - tagged from <mirror-registry>:<port>/rhscl/nodejs-10-rhel7 - prefer registry pullthrough when referencing this tag - - Build and run Node.js 10 applications on RHEL 7. For more information about using this builder image, including OpenShift considerations, see https://github.com/nodeshift/centos7-s2i-nodejs. - Tags: builder, nodejs - Example Repo: https://github.com/sclorg/nodejs-ex.git - - * <mirror-registry>:<port>/rhscl/nodejs-10-rhel7@sha256:d669ecbc11ac88293de50219dae8619832c6a0f5b04883b480e073590fab7c54 - 3 minutes ago - -[...] ----- diff --git a/modules/developer-cli-odo-modifying-the-running-application.adoc b/modules/developer-cli-odo-modifying-the-running-application.adoc deleted file mode 100644 index 695494633f3f..000000000000 --- a/modules/developer-cli-odo-modifying-the-running-application.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-multicomponent--application-with-odo.adoc - -[id="modifying-the-running-application_{context}"] - -= Modifying the running application - -.Procedure - -. Change the local directory to the front-end directory: -+ -[source,terminal] ----- -$ cd frontend ----- - -. Monitor the changes on the file system using: -+ -[source,terminal] ----- -$ odo watch ----- - -. Edit the `index.html` file to change the displayed name for the game. -+ -[NOTE] -==== -A slight delay is possible before {odo-title} recognizes the change. -==== -+ -{odo-title} pushes the changes to the front-end component and prints its status to the terminal: -+ -[source,terminal] ----- -File /root/frontend/index.html changed -File changed -Pushing files... - ✓ Waiting for component to start - ✓ Copying files to component - ✓ Building component ----- - -. Refresh the application page in the web browser. The new name is now displayed. diff --git a/modules/developer-cli-odo-modifying-your-application-code.adoc b/modules/developer-cli-odo-modifying-your-application-code.adoc deleted file mode 100644 index ddef73601a08..000000000000 --- a/modules/developer-cli-odo-modifying-your-application-code.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/creating-a-single-component-application-with-odo.adoc - -[id="modifying-your-application-code_{context}"] -= Modifying your application code - -You can modify your application code and have the changes applied to your application on {product-title}. - -. Edit one of the layout files within the Node.js directory with your preferred text editor. - -. Update your component: -+ -[source,terminal] ----- -$ odo push ----- -. Refresh your application in the browser to see the changes. diff --git a/modules/developer-cli-odo-openshift-cluster-objects.adoc b/modules/developer-cli-odo-openshift-cluster-objects.adoc deleted file mode 100644 index a2ba21652c8d..000000000000 --- a/modules/developer-cli-odo-openshift-cluster-objects.adoc +++ /dev/null @@ -1,91 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/odo-architecture.adoc - -[id="openshift-cluster-objects_{context}"] -= OpenShift cluster objects - -== Init Containers -Init containers are specialized containers that run before the application container starts and configure the necessary environment for the application containers to run. Init containers can have files that application images do not have, for example setup scripts. Init containers always run to completion and the application container does not start if any of the init containers fails. - -The pod created by {odo-title} executes two Init Containers: - -* The `copy-supervisord` Init container. -* The `copy-files-to-volume` Init container. - -=== `copy-supervisord` - -The `copy-supervisord` Init container copies necessary files onto an `emptyDir` volume. The main application container utilizes these files from the `emptyDir` volume. - -.Files that are copied onto the `emptyDir` volume: -* Binaries: -** `go-init` is a minimal init system. It runs as the first process (PID 1) inside the application container. go-init starts the `SupervisorD` daemon which runs the developer code. go-init is required to handle orphaned processes. -** `SupervisorD` is a process control system. It watches over configured processes and ensures that they are running. It also restarts services when necessary. For {odo-title}, `SupervisorD` executes and monitors the developer code. - -* Configuration files: -** `supervisor.conf` is the configuration file necessary for the SupervisorD daemon to start. -* Scripts: -** `assemble-and-restart` is an OpenShift S2I concept to build and deploy user-source code. The assemble-and-restart script first assembles the user source code inside the application container and then restarts SupervisorD for user changes to take effect. -** `Run` is an OpenShift S2I concept of executing the assembled source code. The `run` script executes the assembled code created by the `assemble-and-restart` script. -** `s2i-setup` is a script that creates files and directories which are necessary for the `assemble-and-restart` and run scripts to execute successfully. The script is executed whenever the application container starts. - -* Directories: -** `language-scripts`: OpenShift S2I allows custom `assemble` and `run` scripts. A few language specific custom scripts are present in the `language-scripts` directory. The custom scripts provide additional configuration to make {odo-title} debug work. - -The `emptyDir` volume is mounted at the `/opt/odo` mount point for both the Init container and the application container. - -=== `copy-files-to-volume` -The `copy-files-to-volume` Init container copies files that are in `/opt/app-root` in the S2I builder image onto the persistent volume. The volume is then mounted at the same location (`/opt/app-root`) in an application container. - -Without the persistent volume on `/opt/app-root` the data in this directory is lost when the persistent volume claim is mounted at the same location. - -The PVC is mounted at the `/mnt` mount point inside the Init container. - -== Application container -Application container is the main container inside of which the user-source code executes. - -Application container is mounted with two volumes: - -* `emptyDir` volume mounted at `/opt/odo` -* The persistent volume mounted at `/opt/app-root` - -`go-init` is executed as the first process inside the application container. The `go-init` process then starts the `SupervisorD` daemon. - -`SupervisorD` executes and monitors the user assembled source code. If the user process crashes, `SupervisorD` restarts it. - -== Persistent volumes and persistent volume claims -A persistent volume claim (PVC) is a volume type in Kubernetes which provisions a persistent volume. The life of a persistent volume is independent of a pod lifecycle. The data on the persistent volume persists across pod restarts. - -The `copy-files-to-volume` Init container copies necessary files onto the persistent volume. The main application container utilizes these files at runtime for execution. - -The naming convention of the persistent volume is <component_name>-s2idata. - -[options="header"] -|=== -| Container | PVC mounted at -| `copy-files-to-volume` -| `/mnt` - -| Application container -| `/opt/app-root` -|=== - -== `emptyDir` volume -An `emptyDir` volume is created when a pod is assigned to a node, and exists as long as that pod is running on the node. If the container is restarted or moved, the content of the `emptyDir` is removed, Init container restores the data back to the `emptyDir`. `emptyDir` is initially empty. - -The `copy-supervisord` Init container copies necessary files onto the `emptyDir` volume. These files are then utilized by the main application container at runtime for execution. - -[options="header"] -|=== -| Container | `emptyDir volume` mounted at -| `copy-supervisord` -| `/opt/odo` - -| Application container -| `/opt/odo` -|=== - -== Service -A service is a Kubernetes concept of abstracting the way of communicating with a set of pods. - -{odo-title} creates a service for every application pod to make it accessible for communication. diff --git a/modules/developer-cli-odo-openshift-source-to-image.adoc b/modules/developer-cli-odo-openshift-source-to-image.adoc deleted file mode 100644 index 7341c89caf1d..000000000000 --- a/modules/developer-cli-odo-openshift-source-to-image.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/odo-architecture.adoc - -[id="openshift-source-to-image_{context}"] - -= OpenShift source-to-image - -OpenShift Source-to-Image (S2I) is an open-source project which helps in building artifacts from source code and injecting these into container images. S2I produces ready-to-run images by building source code without the need of a Dockerfile. -{odo-title} uses S2I builder image for executing developer source code inside a container. diff --git a/modules/developer-cli-odo-overwriting-a-mirror-registry.adoc b/modules/developer-cli-odo-overwriting-a-mirror-registry.adoc deleted file mode 100644 index dab40aa2d553..000000000000 --- a/modules/developer-cli-odo-overwriting-a-mirror-registry.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/creating-and-deploying-a-component-to-the-disconnected-cluster - -[id="overwriting-the-mirror-registry_{context}"] -= Overwriting the mirror registry - -To download npm packages for Node.js dependencies and Maven packages for Java dependencies from a private mirror registry, you must create and configure a mirror npm or Maven registry on the cluster. You can then overwrite the mirror registry on an existing component or when you create a new component. - -.Procedure - -* To overwrite the mirror registry on an existing component: -+ -[source,terminal] ----- -$ odo config set --env NPM_MIRROR=<npm_mirror_registry> ----- - -* To overwrite the mirror registry when creating a component: -+ -[source,terminal] ----- -$ odo component create nodejs --env NPM_MIRROR=<npm_mirror_registry> ----- diff --git a/modules/developer-cli-odo-push-workflow.adoc b/modules/developer-cli-odo-push-workflow.adoc deleted file mode 100644 index 488558f0da6d..000000000000 --- a/modules/developer-cli-odo-push-workflow.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/odo-architecture.adoc - -[id="odo-push-workflow_{context}"] - -= `{odo-title} push` workflow -This section describes `{odo-title} push` workflow. {odo-title} push deploys user code on an {product-title} cluster with all the necessary {product-title} resources. - -. Creating resources -+ -If not already created, `{odo-title} push` creates the following {product-title} resources: -+ -* `DeploymentConfig` object: -** Two init containers are executed: `copy-supervisord` and `copy-files-to-volume`. The init containers copy files onto the `emptyDir` and the `PersistentVolume` type of volumes respectively. -** The application container starts. The first process in the application container is the `go-init` process with PID=1. -** `go-init` process starts the SupervisorD daemon. -+ -[NOTE] -==== -The user application code has not been copied into the application container yet, so the `SupervisorD` daemon does not execute the `run` script. -==== -+ -* `Service` object -* `Secret` objects -* `PersistentVolumeClaim` object - - -. Indexing files -+ -* A file indexer indexes the files in the source code directory. The indexer traverses through the source code directories recursively and finds files which have been created, deleted, or renamed. -* A file indexer maintains the indexed information in an {odo-title} index file inside the `.odo` directory. -* If the {odo-title} index file is not present, it means that the file indexer is being executed for the first time, and creates a new {odo-title} index JSON file. -The {odo-title} index JSON file contains a file map - the relative file paths of the traversed files and the absolute paths of the changed and deleted files. - -. Pushing code -+ -Local code is copied into the application container, usually under `/tmp/src`. - -. Executing `assemble-and-restart` -+ -On a successful copy of the source code, the `assemble-and-restart` script is executed inside the running application container. diff --git a/modules/developer-cli-odo-pushing-the-odo-init-image-to-a-mirror-registry.adoc b/modules/developer-cli-odo-pushing-the-odo-init-image-to-a-mirror-registry.adoc deleted file mode 100644 index 8b7ea360b3f4..000000000000 --- a/modules/developer-cli-odo-pushing-the-odo-init-image-to-a-mirror-registry.adoc +++ /dev/null @@ -1,133 +0,0 @@ -// Module included in the following assemblies: -// -// cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/pushing-the-odo-init-image-to-the-restricted-cluster-registry.adoc - -[id="pushing-the-odo-init-image-to-a-mirror-registry_{context}"] -= Pushing the `odo` init image to a mirror registry - -Depending on your operating system, you can push the `odo` init image to a cluster with a mirror registry as follows: - -[id="pushing-the-init-image-to-a-mirror-registry-on-linux_{context}"] - -== Pushing the `init` image to a mirror registry on Linux - -.Procedure - -. Use `base64` to encode the root certification authority (CA) content of your mirror registry: -+ -[source,terminal] ----- -$ echo <content_of_additional_ca> | base64 -d > disconnect-ca.crt ----- - -. Copy the encoded root CA certificate to the appropriate location: -+ -[source,terminal] ----- -$ sudo cp ./disconnect-ca.crt /etc/pki/ca-trust/source/anchors/<mirror-registry>.crt ----- - -. Trust a CA in your client platform and log into the {product-title} mirror registry: -+ -[source,terminal] ----- -$ sudo update-ca-trust enable && sudo systemctl daemon-reload && sudo systemctl restart / docker && docker login <mirror-registry>:5000 -u <username> -p <password> ----- - -. Mirror the `odo` init image: -+ -[source,terminal] ----- -$ oc image mirror registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> <mirror-registry>:5000/openshiftdo/odo-init-image-rhel7:<tag> ----- - -. Override the default `odo` init image path by setting the `ODO_BOOTSTRAPPER_IMAGE` environment variable: -+ -[source,terminal] ----- -$ export ODO_BOOTSTRAPPER_IMAGE=<mirror-registry>:5000/openshiftdo/odo-init-image-rhel7:<tag> ----- - - -[id="pushing-the-init-image-to-a-mirror-registry-on-macos_{context}"] - -== Pushing the `init` image to a mirror registry on MacOS - -.Procedure - -. Use `base64` to encode the root certification authority (CA) content of your mirror registry: -+ -[source,terminal] ----- -$ echo <content_of_additional_ca> | base64 -d > disconnect-ca.crt ----- - -. Copy the encoded root CA certificate to the appropriate location: -+ -.. Restart Docker using the Docker UI. -+ -.. Run the following command: -+ -[source,terminal] ----- -$ docker login <mirror-registry>:5000 -u <username> -p <password> ----- - -. Mirror the `odo` init image: -+ -[source,terminal] ----- -$ oc image mirror registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> <mirror-registry>:5000/openshiftdo/odo-init-image-rhel7:<tag> ----- - -. Override the default `odo` init image path by setting the `ODO_BOOTSTRAPPER_IMAGE` environment variable: -+ -[source,terminal] ----- -$ export ODO_BOOTSTRAPPER_IMAGE=<mirror-registry>:5000/openshiftdo/odo-init-image-rhel7:<tag> ----- - -[id="pushing-the-init-image-to-a-mirror-registry-on-windows_{context}"] - -== Pushing the `init` image to a mirror registry on Windows - -.Procedure - -. Use `base64` to encode the root certification authority (CA) content of your mirror registry: -+ -[source,terminal] ----- -PS C:\> echo <content_of_additional_ca> | base64 -d > disconnect-ca.crt ----- - -. As an administrator, copy the encoded root CA certificate to the appropriate location by executing the following command: -+ -[source,terminal] ----- -PS C:\WINDOWS\system32> certutil -addstore -f "ROOT" disconnect-ca.crt ----- - -. Trust a CA in your client platform and log into the {product-title} mirror registry: -+ -.. Restart Docker using the Docker UI. -+ -.. Run the following command: -+ -[source,terminal] ----- -PS C:\WINDOWS\system32> docker login <mirror-registry>:5000 -u <username> -p <password> ----- - -. Mirror the `odo` init image: -+ -[source,terminal] ----- -PS C:\> oc image mirror registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> <mirror-registry>:5000/openshiftdo/odo-init-image-rhel7:<tag> ----- - -. Override the default `odo` init image path by setting the `ODO_BOOTSTRAPPER_IMAGE` environment variable: -+ -[source,terminal] ----- -PS C:\> $env:ODO_BOOTSTRAPPER_IMAGE="<mirror-registry>:5000/openshiftdo/odo-init-image-rhel7:<tag>" ----- diff --git a/modules/developer-cli-odo-pushing-the-odo-init-image-to-an-internal-registry-directly.adoc b/modules/developer-cli-odo-pushing-the-odo-init-image-to-an-internal-registry-directly.adoc deleted file mode 100644 index 7f3dd04ead40..000000000000 --- a/modules/developer-cli-odo-pushing-the-odo-init-image-to-an-internal-registry-directly.adoc +++ /dev/null @@ -1,238 +0,0 @@ -// Module included in the following assemblies: -// -// cli_reference/developer_cli_odo/using_odo_in_a_restricted_environment/pushing-the-odo-init-image-to-the-restricted-cluster-registry.adoc - -[id="pushing-the-odo-init-image-to-an-internal-registry-directly_{context}"] -= Pushing the `odo` init image to an internal registry directly - -If your cluster allows images to be pushed to the internal registry directly, push the `odo` init image to the registry as follows: - -[id="pushing-the-init-image-directly-on-linux_{context}"] - -== Pushing the `init` image directly on Linux - -.Procedure - -. Enable the default route: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io cluster -p '{"spec":{"defaultRoute":true}}' --type='merge' -n openshift-image-registry ----- - -. Get a wildcard route CA: -+ -[source,terminal] ----- -$ oc get secret router-certs-default -n openshift-ingress -o yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: v1 -data: - tls.crt: ************************** - tls.key: ################## -kind: Secret -metadata: - [...] -type: kubernetes.io/tls ----- - -. Use `base64` to encode the root certification authority (CA) content of your mirror registry: -+ -[source,terminal] ----- -$ echo <tls.crt> | base64 -d > ca.crt ----- - -. Trust a CA in your client platform: -+ -[source,terminal] ----- -$ sudo cp ca.crt /etc/pki/ca-trust/source/anchors/externalroute.crt && sudo update-ca-trust enable && sudo systemctl daemon-reload && sudo systemctl restart docker ----- - -. Log into the internal registry: -+ -[source,terminal] ----- -$ oc get route -n openshift-image-registry -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -default-route <registry_path> image-registry <all> reencrypt None - -$ docker login <registry_path> -u kubeadmin -p $(oc whoami -t) ----- - -. Push the `odo` init image: -+ -[source,terminal] ----- -$ docker pull registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> - -$ docker tag registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> <registry_path>/openshiftdo/odo-init-image-rhel7:<tag> - -$ docker push <registry_path>/openshiftdo/odo-init-image-rhel7:<tag> ----- - -. Override the default `odo` init image path by setting the `ODO_BOOTSTRAPPER_IMAGE` environment variable: -+ -[source,terminal] ----- -$ export ODO_BOOTSTRAPPER_IMAGE=<registry_path>/openshiftdo/odo-init-image-rhel7:1.0.1 ----- - - -[id="pushing-the-init-image-directly-on-macos_{context}"] - -== Pushing the `init` image directly on MacOS - -.Procedure - -. Enable the default route: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io cluster -p '{"spec":{"defaultRoute":true}}' --type='merge' -n openshift-image-registry ----- - -. Get a wildcard route CA: -+ -[source,terminal] ----- -$ oc get secret router-certs-default -n openshift-ingress -o yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: v1 -data: - tls.crt: ************************** - tls.key: ################## -kind: Secret -metadata: - [...] -type: kubernetes.io/tls ----- - -. Use `base64` to encode the root certification authority (CA) content of your mirror registry: -+ -[source,terminal] ----- -$ echo <tls.crt> | base64 -d > ca.crt ----- - -. Trust a CA in your client platform: -+ -[source,terminal] ----- -$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt ----- - -. Log into the internal registry: -+ -[source,terminal] ----- -$ oc get route -n openshift-image-registry -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -default-route <registry_path> image-registry <all> reencrypt None - -$ docker login <registry_path> -u kubeadmin -p $(oc whoami -t) ----- - -. Push the `odo` init image: -+ -[source,terminal] ----- -$ docker pull registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> - -$ docker tag registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> <registry_path>/openshiftdo/odo-init-image-rhel7:<tag> - -$ docker push <registry_path>/openshiftdo/odo-init-image-rhel7:<tag> ----- - -. Override the default `odo` init image path by setting the `ODO_BOOTSTRAPPER_IMAGE` environment variable: -+ -[source,terminal] ----- -$ export ODO_BOOTSTRAPPER_IMAGE=<registry_path>/openshiftdo/odo-init-image-rhel7:1.0.1 ----- - - -[id="pushing-the-init-image-directly-on-windows_{context}"] - -== Pushing the `init` image directly on Windows - -.Procedure - -. Enable the default route: -+ -[source,terminal] ----- -PS C:\> oc patch configs.imageregistry.operator.openshift.io cluster -p '{"spec":{"defaultRoute":true}}' --type='merge' -n openshift-image-registry ----- - -. Get a wildcard route CA: -+ -[source,terminal] ----- -PS C:\> oc get secret router-certs-default -n openshift-ingress -o yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: v1 -data: - tls.crt: ************************** - tls.key: ################## -kind: Secret -metadata: - [...] -type: kubernetes.io/tls ----- - -. Use `base64` to encode the root certification authority (CA) content of your mirror registry: -+ -[source,terminal] ----- -PS C:\> echo <tls.crt> | base64 -d > ca.crt ----- - -. As an administrator, trust a CA in your client platform by executing the following command: -+ -[source,terminal] ----- -PS C:\WINDOWS\system32> certutil -addstore -f "ROOT" ca.crt ----- - -. Log into the internal registry: -+ -[source,terminal] ----- -PS C:\> oc get route -n openshift-image-registry -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -default-route <registry_path> image-registry <all> reencrypt None - -PS C:\> docker login <registry_path> -u kubeadmin -p $(oc whoami -t) ----- - -. Push the `odo` init image: -+ -[source,terminal] ----- -PS C:\> docker pull registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> - -PS C:\> docker tag registry.access.redhat.com/openshiftdo/odo-init-image-rhel7:<tag> <registry_path>/openshiftdo/odo-init-image-rhel7:<tag> - -PS C:\> docker push <registry_path>/openshiftdo/odo-init-image-rhel7:<tag> ----- - -. Override the default `odo` init image path by setting the `ODO_BOOTSTRAPPER_IMAGE` environment variable: -+ -[source,terminal] ----- -PS C:\> $env:ODO_BOOTSTRAPPER_IMAGE="<registry_path>/openshiftdo/odo-init-image-rhel7:<tag>" ----- diff --git a/modules/developer-cli-odo-sample-applications.adoc b/modules/developer-cli-odo-sample-applications.adoc deleted file mode 100644 index d3febf54af4c..000000000000 --- a/modules/developer-cli-odo-sample-applications.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/using-sample-applications.adoc - -[id="odo-sample-applications_{context}"] - -= Examples from Git repositories - -== httpd - -This example helps build and serve static content using httpd on CentOS 7. For more information about using this builder image, including {product-title} considerations, see the link:https://github.com/sclorg/httpd-container/blob/master/2.4/root/usr/share/container-scripts/httpd/README.md[Apache HTTP Server container image repository]. - -[source,terminal] ----- -$ odo create httpd --git https://github.com/openshift/httpd-ex.git ----- - -== java - -This example helps build and run fat JAR Java applications on CentOS 7. For more information about using this builder image, including {product-title} considerations, see the link:https://github.com/fabric8io-images/s2i/blob/master/README.md[Java S2I Builder image]. - -[source,terminal] ----- -$ odo create java --git https://github.com/spring-projects/spring-petclinic.git ----- - -== nodejs - -Build and run Node.js applications on CentOS 7. For more information about using this builder image, including {product-title} considerations, see the link:https://github.com/sclorg/s2i-nodejs-container/blob/master/8/README.md[Node.js 8 container image]. - -[source,terminal] ----- -$ odo create nodejs --git https://github.com/openshift/nodejs-ex.git ----- - -== perl - -This example helps build and run Perl applications on CentOS 7. For more information about using this builder image, including {product-title} considerations, see the link:https://github.com/sclorg/s2i-perl-container/blob/master/5.26/README.md[Perl 5.26 container image]. - -[source,terminal] ----- -$ odo create perl --git https://github.com/openshift/dancer-ex.git ----- - -== php - -This example helps build and run PHP applications on CentOS 7. For more information about using this builder image, including {product-title} considerations, see the link:https://github.com/sclorg/s2i-php-container/blob/master/7.1/README.md[PHP 7.1 Docker image]. - -[source,terminal] ----- -$ odo create php --git https://github.com/openshift/cakephp-ex.git ----- - -== python - -This example helps build and run Python applications on CentOS 7. For more information about using this builder image, including {product-title} considerations, see the link:https://github.com/sclorg/s2i-python-container/blob/master/3.6/README.md[Python 3.6 container image]. - -[source,terminal] ----- -$ odo create python --git https://github.com/openshift/django-ex.git ----- - -== ruby - -This example helps build and run Ruby applications on CentOS 7. For more information about using this builder image, including {product-title} considerations, see link:https://github.com/sclorg/s2i-ruby-container/blob/master/2.5/README.md[Ruby 2.5 container image]. - -[source,terminal] ----- -$ odo create ruby --git https://github.com/openshift/ruby-ex.git ----- - -== wildfly - -This example helps build and run WildFly applications on CentOS 7. For more information about using this builder image, including {product-title} considerations, see the link:https://github.com/wildfly/wildfly-s2i/blob/master/README.md[Wildfly - CentOS Docker images for OpenShift]. - -[source,terminal] ----- -$ odo create wildfly --git https://github.com/openshift/openshift-jee-sample.git ----- - -= Binary examples - -== java - -Java can be used to deploy a binary artifact as follows: - -[source,terminal] ----- -$ git clone https://github.com/spring-projects/spring-petclinic.git -$ cd spring-petclinic -$ mvn package -$ odo create java test3 --binary target/*.jar -$ odo push ----- - -== wildfly - -WildFly can be used to deploy a binary application as follows: - -[source,terminal] ----- -$ git clone https://github.com/openshiftdemos/os-sample-java-web.git -$ cd os-sample-java-web -$ mvn package -$ cd .. -$ mkdir example && cd example -$ mv ../os-sample-java-web/target/ROOT.war example.war -$ odo create wildfly --binary example.war ----- diff --git a/modules/developer-cli-odo-setting-and-unsetting-environment-variables.adoc b/modules/developer-cli-odo-setting-and-unsetting-environment-variables.adoc deleted file mode 100644 index 99c867d59347..000000000000 --- a/modules/developer-cli-odo-setting-and-unsetting-environment-variables.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/managing-environment-variables-in-odo.adoc - -[id="setting-and-unsetting-environment-variables._{context}"] - -= Setting and unsetting environment variables - -.Procedure - -* To set an environment variable in a component: -+ -[source,terminal] ----- -$ odo config set --env <variable>=<value> ----- - -* To unset an environment variable in a component: -+ -[source,terminal] ----- -$ odo config unset --env <variable> ----- - -* To list all environment variables in a component: -+ -[source,terminal] ----- -$ odo config view ----- diff --git a/modules/developer-cli-odo-switching-between-ephemeral-and-persistent-storage.adoc b/modules/developer-cli-odo-switching-between-ephemeral-and-persistent-storage.adoc deleted file mode 100644 index ae1067993355..000000000000 --- a/modules/developer-cli-odo-switching-between-ephemeral-and-persistent-storage.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// *cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/working-with-storage.adoc - -[id="switching-between-ephemeral-and-persistent-storage_{context}"] -= Switching between ephemeral and persistent storage - -You can switch between ephemeral and persistent storage in your project by using the `odo preference` command. `odo preference` modifies the global preference in your cluster. - -When persistent storage is enabled, the cluster stores the information between the restarts. - -When ephemeral storage is enabled, the cluster does not store the information between the restarts. - -Ephemeral storage is enabled by default. - -.Procedure - -. See the preference currently set in your project: -+ -[source,terminal] ----- -$ odo preference view ----- -+ -.Example output -+ -[source,terminal] ----- -PARAMETER CURRENT_VALUE -UpdateNotification -NamePrefix -Timeout -BuildTimeout -PushTimeout -Experimental -PushTarget -Ephemeral true ----- - -. To unset the ephemeral storage and set the persistent storage: -+ -[source,terminal] ----- -$ odo preference set Ephemeral false ----- - -. To set the ephemeral storage again: -+ -[source,terminal] ----- -$ odo preference set Ephemeral true ----- -+ -The `odo preference` command changes the global settings of all your currently deployed components as well as ones you will deploy in future. - -. Run `odo push` to make `odo` create a specified storage for your component: -+ -[source,terminal] ----- -$ odo push ----- diff --git a/modules/developer-cli-odo-using-command-completion.adoc b/modules/developer-cli-odo-using-command-completion.adoc deleted file mode 100644 index 0c9a1c9b545c..000000000000 --- a/modules/developer-cli-odo-using-command-completion.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/developer_cli_odo/configuring-the-odo-cli.adoc - -[id="using-command-completion_{context}"] -= Using command completion - -[NOTE] -==== -Currently command completion is only supported for bash, zsh, and fish shells. -==== - -{odo-title} provides a smart completion of command parameters based on user input. For this to work, {odo-title} needs to integrate with the executing shell. - -.Procedure - -* To install command completion automatically: -. Run: -+ -[source,terminal] ----- -$ odo --complete ----- -+ -. Press `y` when prompted to install the completion hook. - -* To install the completion hook manually, add `complete -o nospace -C <full_path_to_your_odo_binary> odo` to your shell configuration file. After any modification to your shell configuration file, restart your shell. - -* To disable completion: -. Run: -+ -[source,terminal] ----- -$ odo --uncomplete ----- -+ -. Press `y` when prompted to uninstall the completion hook. - -[NOTE] -==== -Re-enable command completion if you either rename the {odo-title} executable or move it to a different directory. -==== diff --git a/modules/diagnostic-bundle-data.adoc b/modules/diagnostic-bundle-data.adoc new file mode 100644 index 000000000000..9951115a524e --- /dev/null +++ b/modules/diagnostic-bundle-data.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * configuration/generate-diagnostic-bundle.adoc +:_mod-docs-content-type: CONCEPT +[id="diagnostic-bundle-data_{context}"] += Diagnostic bundle data + +When you generate a diagnostic bundle, it includes the following data: + +* Central heap profile. +* System logs: Logs of all {product-title} components (for the last 20 minutes) and logs of recently crashed components (from up to 20 minutes before the crash). +System logs depend on the size of your environment. +For large deployments, data includes log files for components with critical errors only, such as a high restart count. +* YAML definitions for {product-title} components: This data does not include Kubernetes secrets. +* {ocp} or Kubernetes events: Details about the events that relate to the objects in the `stackrox` namespace. +* Online Telemetry data, which includes: +** Storage information: Details about the database size and the amount of free space available in attached volumes. +** {product-title} components health information: Details about {product-title} components versions, their memory usage, and any reported errors. +** Coarse-grained usage statistics: Details about API endpoint invocation counts and reported error statuses. +It does not include the actual data sent in API requests. +** Nodes information: Details about the nodes in each secured cluster. +It includes kernel and operating system versions, resource pressure, and taints. +** Environment information: Details about each secured cluster, including Kubernetes or {ocp} version, Istio version (if applicable), cloud provider type and other similar information. diff --git a/modules/differences-between-machinesets-and-machineconfigpool.adoc b/modules/differences-between-machinesets-and-machineconfigpool.adoc deleted file mode 100644 index def5913d9301..000000000000 --- a/modules/differences-between-machinesets-and-machineconfigpool.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/node-tasks.adoc -// * post_installation_configuration/cluster-tasks.adoc - - -[id="differences-between-machinesets-and-machineconfigpool_{context}"] -= Understanding the difference between machine sets and the machine config pool - -`MachineSet` objects describe {product-title} nodes with respect to the cloud or machine provider. - -The `MachineConfigPool` object allows `MachineConfigController` components to define and provide the status of machines in the context of upgrades. - -The `MachineConfigPool` object allows users to configure how upgrades are rolled out to the {product-title} nodes in the machine config pool. - -The `NodeSelector` object can be replaced with a reference to the `MachineSet` object. diff --git a/modules/digging-into-machine-config.adoc b/modules/digging-into-machine-config.adoc deleted file mode 100644 index dd5b97ad2e3c..000000000000 --- a/modules/digging-into-machine-config.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture_rhcos.adoc - -[id="digging-into-machine-config_{context}"] -= Changing Ignition configs after installation - -Machine config pools manage a cluster of nodes and their corresponding machine -configs. Machine configs contain configuration information for a cluster. -To list all machine config pools that are known: - -[source,terminal] ----- -$ oc get machineconfigpools ----- - -.Example output -[source,terminal] ----- -NAME   CONFIG                                  UPDATED UPDATING DEGRADED -master master-1638c1aea398413bb918e76632f20799 False   False    False -worker worker-2feef4f8288936489a5a832ca8efe953 False   False    False ----- - -To list all machine configs: - -[source,terminal] ----- -$ oc get machineconfig ----- - -.Example output -[source,terminal] ----- -NAME                                      GENERATEDBYCONTROLLER   IGNITIONVERSION   CREATED   OSIMAGEURL - -00-master                                 4.0.0-0.150.0.0-dirty   3.1.0             16m -00-master-ssh                             4.0.0-0.150.0.0-dirty                     16m -00-worker                                 4.0.0-0.150.0.0-dirty   3.1.0             16m -00-worker-ssh                             4.0.0-0.150.0.0-dirty                     16m -01-master-kubelet                         4.0.0-0.150.0.0-dirty   3.1.0             16m -01-worker-kubelet                         4.0.0-0.150.0.0-dirty   3.1.0             16m -master-1638c1aea398413bb918e76632f20799   4.0.0-0.150.0.0-dirty   3.1.0             16m -worker-2feef4f8288936489a5a832ca8efe953   4.0.0-0.150.0.0-dirty   3.1.0             16m ----- - -The Machine Config Operator acts somewhat differently than Ignition when it -comes to applying these machine configs. The machine configs are read in order -(from 00* to 99*). Labels inside the machine configs identify the type of node -each is for (master or worker). If the same file appears in multiple -machine config files, the last one wins. So, for example, any file that appears -in a 99* file would replace the same file that appeared in a 00* file. -The input `MachineConfig` objects are unioned into a "rendered" `MachineConfig` -object, which will be used as a target by the operator and is the value you -can see in the machine config pool. - -To see what files are being managed from a machine config, look for "Path:" -inside a particular `MachineConfig` object. For example: - -[source,terminal] ----- -$ oc describe machineconfigs 01-worker-container-runtime | grep Path: ----- - -.Example output -[source,terminal] ----- -            Path:            /etc/containers/registries.conf -            Path:            /etc/containers/storage.conf -            Path:            /etc/crio/crio.conf ----- - -Be sure to give the machine config file a later name -(such as 10-worker-container-runtime). Keep in mind that the content of each -file is in URL-style data. Then apply the new machine config to the cluster. diff --git a/modules/disable-admission-controller-enforcement.adoc b/modules/disable-admission-controller-enforcement.adoc new file mode 100644 index 000000000000..84e96ad2bb35 --- /dev/null +++ b/modules/disable-admission-controller-enforcement.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="disable-admission-controller-enforcement_{context}"] += Disabling admission controller enforcement + +[role="_abstract"] +You can disable admission controller enforcement from the *Clusters* view on the {product-title} ({product-title-short}) portal. + +.Procedure +. In the {product-title-short} portal, select *Platform Configuration* -> *Clusters*. +. Select an existing cluster from the list. +. Turn off the *Enforce on Object Creates* and *Enforce on Object Updates* toggles in the *Dynamic Configuration* section. +. Select *Next*. +. Select *Finish*. diff --git a/modules/disable-associated-policies.adoc b/modules/disable-associated-policies.adoc new file mode 100644 index 000000000000..8469ff9eea7e --- /dev/null +++ b/modules/disable-associated-policies.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="disable-associated-policies_{context}"] += Disabling the admission controller for policies + +[role="_abstract"] +You can turn off the enforcement on relevant policies, which in turn instructs the admission controller to skip enforcements. +//is this correct? It doesn't seem right. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. Disable enforcement on the default policies that you do not want to enforce. For example: +** In the policies view, click the *Kubernetes Actions: Exec into Pod* policy. Selection *Actions* -> *Disable policy*. diff --git a/modules/disable-automatic-upgrades.adoc b/modules/disable-automatic-upgrades.adoc new file mode 100644 index 000000000000..9e1914e4c4bb --- /dev/null +++ b/modules/disable-automatic-upgrades.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * configuration/configure-automatic-upgrades.adoc +:_mod-docs-content-type: PROCEDURE +[id="disable-automatic-upgrades_{context}"] += Disabling automatic upgrades of manifest-installed secured clusters + +If you want to manage your secured cluster upgrades manually, you can disable automatic upgrades. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. +. Turn off the *Automatically upgrade secured clusters* toggle. ++ +[NOTE] +==== +For new installations, the *Automatically upgrade secured clusters* toggle is enabled by default. +==== diff --git a/modules/disable-identify-vulnerabilities-in-nodes.adoc b/modules/disable-identify-vulnerabilities-in-nodes.adoc new file mode 100644 index 000000000000..a0be70ababfe --- /dev/null +++ b/modules/disable-identify-vulnerabilities-in-nodes.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="disable-identify-vulnerabilities-in-nodes_{context}"] += Disabling identifying vulnerabilities in nodes + +Identifying vulnerabilities in nodes is enabled by default. You can disable it from the {product-title-short} portal. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under *Image Integrations*, select *StackRox Scanner*. +. From the list of scanners, select *StackRox Scanner* to view its details. +. Click *Edit*. +. To use only the image scanner and not the node scanner, click *Image Scanner*. +. Click *Save*. diff --git a/modules/disable-language-specific-vulnerability-scanning.adoc b/modules/disable-language-specific-vulnerability-scanning.adoc new file mode 100644 index 000000000000..1e89adda0d29 --- /dev/null +++ b/modules/disable-language-specific-vulnerability-scanning.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="disable-language-specific-vulnerability-scanning_{context}"] += Disabling language-specific vulnerability scanning + +Scanner identifies the vulnerabilities in the programming language-specific dependencies by default. You can disable the language-specific dependency scanning. + +.Procedure +* To disable language-specific vulnerability scanning, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox set env deploy/scanner \ <1> + ROX_LANGUAGE_VULNS=false <2> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +<2> If you are using {product-title} version 3.0.47 or older, replace the environment variable name `ROX_LANGUAGE_VULNS` with `LANGUAGE_VULNS`. diff --git a/modules/disable-online-telemetry-new-install.adoc b/modules/disable-online-telemetry-new-install.adoc new file mode 100644 index 000000000000..861241a0c389 --- /dev/null +++ b/modules/disable-online-telemetry-new-install.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * configuration/online-telemetry.adoc +:_mod-docs-content-type: PROCEDURE +[id="disable-online-telemetry-new-install_{context}"] += Disabling online telemetry during a new installation + +You can disable online telemetry during the installation. + +.Procedure + +* If you are installing {product-title} using Helm: +** Set the `central.disableTelemetry` parameter to `true` when you configure the public configuration file for the `central-services` Helm chart. +* If you are installing {product-title} using the `roxctl` CLI: +** Specify the `--enable-telemetry=false` option when you run the interactive installer: ++ +[source,terminal] +---- +$ roxctl central generate interactive --enable-telemetry=false +---- diff --git a/modules/disable-the-webhook.adoc b/modules/disable-the-webhook.adoc new file mode 100644 index 000000000000..4ccdc3e244f7 --- /dev/null +++ b/modules/disable-the-webhook.adoc @@ -0,0 +1,76 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="disable-the-webhook_{context}"] += Disabling the webhook + +[role="_abstract"] + +You can disable admission controller enforcement from the *Clusters* view in the {product-title-short} portal. + +[IMPORTANT] +==== +If you disable the admission controller by turning off the webhook, you must redeploy the Sensor bundle. +==== + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. +. Select an existing cluster from the list. +. Turn off the *Enable Admission Controller Webhook to listen on exec and port-forward events* toggle in the *Static Configuration* section. +. Select *Next* to continue with Sensor setup. +. Click *Download YAML file and keys*. +. From a system that has access to the monitored cluster, extract and run the `sensor` script: ++ +[source,terminal] +---- +$ unzip -d sensor sensor-<cluster_name>.zip +---- ++ +[source,terminal] +---- +$ ./sensor/sensor.sh +---- ++ +[NOTE] +==== +If you get a warning that you do not have the required permissions to deploy the sensor, follow the on-screen instructions, or contact your cluster administrator for help. +==== +After the sensor is deployed, it contacts Central and provides cluster information. +. Return to the {product-title-short} portal and check if the deployment is successful. +If it is successful, a green checkmark appears under section #2. +If you do not see a green checkmark, use the following command to check for problems: +* On {ocp}: ++ +[source,terminal] +---- +$ oc get pod -n stackrox -w +---- +* On Kubernetes: ++ +[source,terminal] +---- +$ kubectl get pod -n stackrox -w +---- +. Select *Finish*. + +[NOTE] +==== +When you disable the admission controller, {product-title-short} does not delete the `ValidatingWebhookConfiguration` parameter. +However, instead of checking requests for violations, it accepts all `AdmissionReview` requests. + +To remove the `ValidatingWebhookConfiguration` object, run the following command in the secured cluster: + +* On {ocp}: ++ +[source,terminal] +---- +$ oc delete ValidatingWebhookConfiguration/stackrox +---- +* On Kubernetes: ++ +[source,terminal] +---- +$ kubectl delete ValidatingWebhookConfiguration/stackrox +---- +==== diff --git a/modules/disabling-etcd-encryption.adoc b/modules/disabling-etcd-encryption.adoc deleted file mode 100644 index e7f386f3e77f..000000000000 --- a/modules/disabling-etcd-encryption.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * security/encrypting-etcd.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="disabling-etcd-encryption_{context}"] -= Disabling etcd encryption - -You can disable encryption of etcd data in your cluster. - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Modify the `APIServer` object: -+ -[source,terminal] ----- -$ oc edit apiserver ----- - -. Set the `encryption` field type to `identity`: -+ -[source,yaml] ----- -spec: - encryption: - type: identity <1> ----- -<1> The `identity` type is the default value and means that no encryption is performed. - -. Save the file to apply the changes. -+ -The decryption process starts. It can take 20 minutes or longer for this process to complete, depending on the size of your cluster. - -. Verify that etcd decryption was successful. - -.. Review the `Encrypted` status condition for the OpenShift API server to verify that its resources were successfully decrypted: -+ -[source,terminal] ----- -$ oc get openshiftapiserver -o=jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -The output shows `DecryptionCompleted` upon successful decryption: -+ -[source,terminal] ----- -DecryptionCompleted -Encryption mode set to identity and everything is decrypted ----- -+ -If the output shows `DecryptionInProgress`, decryption is still in progress. Wait a few minutes and try again. - -.. Review the `Encrypted` status condition for the Kubernetes API server to verify that its resources were successfully decrypted: -+ -[source,terminal] ----- -$ oc get kubeapiserver -o=jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -The output shows `DecryptionCompleted` upon successful decryption: -+ -[source,terminal] ----- -DecryptionCompleted -Encryption mode set to identity and everything is decrypted ----- -+ -If the output shows `DecryptionInProgress`, decryption is still in progress. Wait a few minutes and try again. - -.. Review the `Encrypted` status condition for the OpenShift OAuth API server to verify that its resources were successfully decrypted: -+ -[source,terminal] ----- -$ oc get authentication.operator.openshift.io -o=jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -The output shows `DecryptionCompleted` upon successful decryption: -+ -[source,terminal] ----- -DecryptionCompleted -Encryption mode set to identity and everything is decrypted ----- -+ -If the output shows `DecryptionInProgress`, decryption is still in progress. Wait a few minutes and try again. diff --git a/modules/disabling-project-self-provisioning.adoc b/modules/disabling-project-self-provisioning.adoc deleted file mode 100644 index c17965b91d34..000000000000 --- a/modules/disabling-project-self-provisioning.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/projects/configuring-project-creation.adoc - -[id="disabling-project-self-provisioning_{context}"] -= Disabling project self-provisioning - -You can prevent an authenticated user group from self-provisioning new projects. - -.Procedure - -. Log in as a user with `cluster-admin` privileges. - -. View the `self-provisioners` cluster role binding usage by running the following command: -+ -[source,terminal] ----- -$ oc describe clusterrolebinding.rbac self-provisioners ----- -+ -.Example output -[source,terminal] ----- -Name: self-provisioners -Labels: <none> -Annotations: rbac.authorization.kubernetes.io/autoupdate=true -Role: - Kind: ClusterRole - Name: self-provisioner -Subjects: - Kind Name Namespace - ---- ---- --------- - Group system:authenticated:oauth ----- -+ -Review the subjects in the `self-provisioners` section. - -. Remove the `self-provisioner` cluster role from the group `system:authenticated:oauth`. - -** If the `self-provisioners` cluster role binding binds only the `self-provisioner` role to the `system:authenticated:oauth` group, run the following command: -+ -[source,terminal] ----- -$ oc patch clusterrolebinding.rbac self-provisioners -p '{"subjects": null}' ----- - -** If the `self-provisioners` cluster role binding binds the `self-provisioner` role to more users, groups, or service accounts than the `system:authenticated:oauth` group, run the following command: -+ -[source,terminal] ----- -$ oc adm policy \ - remove-cluster-role-from-group self-provisioner \ - system:authenticated:oauth ----- - -. Edit the `self-provisioners` cluster role binding to prevent automatic updates to the role. Automatic updates reset the cluster roles to the default state. - -** To update the role binding using the CLI: - -... Run the following command: -+ -[source,terminal] ----- -$ oc edit clusterrolebinding.rbac self-provisioners ----- - -... In the displayed role binding, set the `rbac.authorization.kubernetes.io/autoupdate` parameter value to `false`, as shown in the following example: -+ -[source,yaml] ----- -apiVersion: authorization.openshift.io/v1 -kind: ClusterRoleBinding -metadata: - annotations: - rbac.authorization.kubernetes.io/autoupdate: "false" - ... ----- - -** To update the role binding by using a single command: -+ -[source,terminal] ----- -$ oc patch clusterrolebinding.rbac self-provisioners -p '{ "metadata": { "annotations": { "rbac.authorization.kubernetes.io/autoupdate": "false" } } }' ----- - -. Log in as an authenticated user and verify that it can no longer self-provision a project: -+ -[source,terminal] ----- -$ oc new-project test ----- -+ -.Example output -[source,terminal] ----- -Error from server (Forbidden): You may not request a new project via this API. ----- -+ -Consider customizing this project request message to provide more helpful instructions specific to your organization. diff --git a/modules/disabling-telemetry.adoc b/modules/disabling-telemetry.adoc new file mode 100644 index 000000000000..3eeb927b5014 --- /dev/null +++ b/modules/disabling-telemetry.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * telemetry/opting-out-of-telemetry.adoc +:_mod-docs-content-type: PROCEDURE +[id="disabling-telemetry_{context}"] + += Disabling Telemetry + +If you have configured Telemetry by setting the key in your environment, you can disable Telemetry data collection from the {rh-rhacs-first} user interface (UI). + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration > System Configuration*. +. In the *System Configuration* header, click *Edit*. +. Scroll down and ensure that *Online Telemetry Data Collection* is set to *Disabled.* diff --git a/modules/displaying-potential-issues-with-your-cluster.adoc b/modules/displaying-potential-issues-with-your-cluster.adoc deleted file mode 100644 index 7d9846788745..000000000000 --- a/modules/displaying-potential-issues-with-your-cluster.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc - -[id="displaying-potential-issues-with-your-cluster_{context}"] -= Displaying potential issues with your cluster - -This section describes how to display the Insights report in the {cloud-redhat-com}. - -Note that Insights repeatedly analyzes your cluster and shows the latest results. These results can change, for example, if you fix an issue or a new issue has been detected. - -.Prerequisites - -* Your cluster is registered in the {cloud-redhat-com}. -* Remote health reporting is enabled, which is the default. -* You are logged in to the link:https://cloud.redhat.com/openshift[{cloud-redhat-com}]. - -.Procedure - -. Click the *Clusters* menu in the left pane. - -. Click the cluster's name to display the details of the cluster. - -. Open the *Insights* tab of the cluster. -+ -Depending on the result, the tab displays one of the following: -+ -* *Your cluster passed all health checks*, if Insights did not identify any issues. - -* A list of issues Insights has detected, prioritized by risk (low, moderate, important, and critical). - -* *No health checks to display*, if Insights has not yet analyzed the cluster. The analysis starts shortly after the cluster has been installed and connected to the internet. - -. If any issues are displayed on the tab, click the *>* icon in front of the entry for further details. -+ -Depending on the issue, the details can also contain a link to an Red Hat Knowledge Base article. For details and information on how to solve the problem, click *How to remediate this issue*. diff --git a/modules/displaying-the-insights-status-in-the-web-console.adoc b/modules/displaying-the-insights-status-in-the-web-console.adoc deleted file mode 100644 index 1a6b38598660..000000000000 --- a/modules/displaying-the-insights-status-in-the-web-console.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc - -[id="displaying-the-insights-status-in-the-web-console_{context}"] -= Displaying the Insights status in the web console - -Insights repeatedly analyzes your cluster and you can display the status of identified potential issues of your cluster in the {product-title} web console. This status shows the number of issues in the different categories and, for further details, links to the reports in the {cloud-redhat-com}. - -.Prerequisites - -* Your cluster is registered in the {cloud-redhat-com}. -* Remote health reporting is enabled, which is the default. -* You are logged in to the {product-title} web console. - -.Procedure - -. Navigate to *Home* -> *Overview* in the {product-title} web console. - -. Click *Insights* on the *Status* card. -+ -The pop-up window lists potential issues grouped by priority. Click the individual categories or *View all in {product-title}* to display further details. - diff --git a/modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc b/modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc new file mode 100644 index 000000000000..43b2c68faab8 --- /dev/null +++ b/modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: CONCEPT +[id="distinguishing-between-syntactic-and-semantic-difference-outputs_{context}"] += Distinguishing between syntactic and semantic difference outputs + +In the following example, `dir1` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[`netpol-analysis-example-minimal/`], and `dir2` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-diff-example-minimal[`netpol-diff-example-minimal/`]. The difference between the directories is a small change in the network policy `backend-netpol`. + +.Example policy from `dir1`: + +[source,yaml] +---- +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + creationTimestamp: null + name: backend-netpol +spec: + ingress: + - from: + - podSelector: + matchLabels: + app: frontend + ports: + - port: 9090 + protocol: TCP + podSelector: + matchLabels: + app: backendservice + policyTypes: + - Ingress + - Egress +status: {} +---- + +The change in `dir2` is an added `-` before the ports attribute, which produces a difference output. \ No newline at end of file diff --git a/modules/download-kernel-support-package.adoc b/modules/download-kernel-support-package.adoc new file mode 100644 index 000000000000..2f099873437a --- /dev/null +++ b/modules/download-kernel-support-package.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: PROCEDURE +[id="download-kernel-support-package_{context}"] += Downloading kernel support packages + +[NOTE] +==== +Support packages are deprecated and have no effect on secured clusters running version +4.5 or later. Support package uploads only affect secured clusters on version 4.4 and +earlier. +==== + +If you are running {product-title} in offline mode, you can download packages containing probes for all recent and supported Linux kernel versions and then upload them to Central. + +.Procedure + +* View and download available support packages from link:https://install.stackrox.io/collector/support-packages/index.html[https://install.stackrox.io/collector/support-packages/index.html]. +The kernel support packages list categorizes support packages based on {product-title} version. diff --git a/modules/download-network-baselines.adoc b/modules/download-network-baselines.adoc new file mode 100644 index 000000000000..49e01ae33a7a --- /dev/null +++ b/modules/download-network-baselines.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="download-network-baselines_{context}"] += Downloading network baselines from the network graph + +You can download network baselines as YAML files from the network graph view. + +.Procedure +. In the {product-title-short} portal, go to *Network Graph*. +. Click the *Namespaces* list and use the search field to locate a namespace, or select individual namespaces. +. Click the *Deployments* list and use the search field to locate a deployment, or select individual deployments to display in the network graph. +. In the network graph, click on a deployment to view the information panel. +. The *Baseline* tab lists the baseline flows. Use the *filter by entity name* field to further restrict the list of flows. +. Optional: Check the box to exclude ports and protocols. +. Click *Download baseline as network policy*. \ No newline at end of file diff --git a/modules/download-scanner-definitions.adoc b/modules/download-scanner-definitions.adoc new file mode 100644 index 000000000000..cf9e36e4b543 --- /dev/null +++ b/modules/download-scanner-definitions.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: PROCEDURE +[id="download-scanner-definitions_{context}"] += Downloading Scanner definitions + +If you are running {product-title} in offline mode, you can download the vulnerability definitions database that Scanner uses and then upload it to Central. + +.Prerequisites + +* To download Scanner definitions, you need a system with internet access. + +.Procedure + +* To download the definitions, perform one of the following actions: +** Recommended: Beginning with {product-title-short} version 4.4, use the `roxctl scanner download-db --scanner-db-file scanner-vuln-updates.zip` command to download the definitions. +** Go to link:https://install.stackrox.io/scanner/scanner-vuln-updates.zip[https://install.stackrox.io/scanner/scanner-vuln-updates.zip] to download the definitions. diff --git a/modules/download-sensor-bundle.adoc b/modules/download-sensor-bundle.adoc new file mode 100644 index 000000000000..e35b7e4da750 --- /dev/null +++ b/modules/download-sensor-bundle.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * configuration/add-custom-certificates.adoc +:_mod-docs-content-type: PROCEDURE + +[id="proc_downloading-sensor-bundle_{context}"] += Downloading a Sensor bundle + +[role="_abstract"] +The Sensor bundle includes the necessary configuration files and scripts to install Sensor. You can download the Sensor bundle from the {product-title-short} portal. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. +. Click *New Cluster* and specify a name for the cluster. +. If you are deploying the Sensor in the same cluster, accept the default values for all the fields. +Otherwise, if you are deploying into a different cluster, replace the address `central.stackrox.svc:443` with a load balancer, node port, or other address (including the port number) that is accessible from the other cluster in which you are planning to install. ++ +[NOTE] +==== +If you are using a non-gRPC capable load balancer, such as HAProxy, AWS Application Load Balancer (ALB), or AWS Elastic Load Balancing (ELB) use the WebSocket Secure (`wss`) protocol. +To use `wss`: + +. Prefix the address with `wss://`, and +. Add the port number after the address, for example, `wss://stackrox-central.example.com:443`. +==== +. Click *Next* to continue. +. Click *Download YAML File and Keys*. diff --git a/modules/downloading-sensor-bundle-for-existing-clusters.adoc b/modules/downloading-sensor-bundle-for-existing-clusters.adoc new file mode 100644 index 000000000000..02a2ec657230 --- /dev/null +++ b/modules/downloading-sensor-bundle-for-existing-clusters.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * cli/managing-secured-clusters.adoc +:_mod-docs-content-type: PROCEDURE +[id="downloading-sensor-bundles-for-existing-clusters_{context}"] += Downloading Sensor bundles for existing clusters + +.Procedure + +* Run the following command to download Sensor bundles for existing clusters by specifying a `cluster name` or `ID`: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl sensor get-bundle _<cluster_name_or_id>_ +---- \ No newline at end of file diff --git a/modules/dr-recover-expired-control-plane-certs.adoc b/modules/dr-recover-expired-control-plane-certs.adoc deleted file mode 100644 index 12a7bc5d1f01..000000000000 --- a/modules/dr-recover-expired-control-plane-certs.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * disaster_recovery/scenario-3-expired-certs.adoc - -[id="dr-scenario-3-recovering-expired-certs_{context}"] -= Recovering from expired control plane certificates - -As of {product-title} 4.4.8, the cluster can automatically recover from expired control plane certificates. You no longer need to perform the manual steps that were required in previous versions. - -The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. - -Use the following steps to approve the pending `node-bootstrapper` CSRs. - -.Procedure - -. Get the list of current CSRs: -+ -[source,terminal] ----- -$ oc get csr ----- - -. Review the details of a CSR to verify that it is valid: -+ -[source,terminal] ----- -$ oc describe csr <csr_name> <1> ----- -<1> `<csr_name>` is the name of a CSR from the list of current CSRs. - -. Approve each valid `node-bootstrapper` CSR: -+ -[source,terminal] ----- -$ oc adm certificate approve <csr_name> ----- diff --git a/modules/dr-restoring-cluster-state.adoc b/modules/dr-restoring-cluster-state.adoc deleted file mode 100644 index 620b45bfefd6..000000000000 --- a/modules/dr-restoring-cluster-state.adoc +++ /dev/null @@ -1,316 +0,0 @@ -// Module included in the following assemblies: -// -// * disaster_recovery/scenario-2-restoring-cluster-state.adoc -// * post_installation_configuration/cluster-tasks.adoc - - -[id="dr-scenario-2-restoring-cluster-state_{context}"] -= Restoring to a previous cluster state - -You can use a saved etcd backup to restore back to a previous cluster state. You use the etcd backup to restore a single control plane host. Then the etcd cluster Operator handles scaling to the remaining master hosts. - -[IMPORTANT] -==== -When you restore your cluster, you must use an etcd backup that was taken from the same z-stream release. For example, an {product-title} 4.7.2 cluster must use an etcd backup that was taken from 4.7.2. -==== - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. -* SSH access to master hosts. -* A backup directory containing both the etcd snapshot and the resources for the static pods, which were from the same backup. The file names in the directory must be in the following formats: `snapshot_<datetimestamp>.db` and `static_kuberesources_<datetimestamp>.tar.gz`. - -.Procedure - -. Select a control plane host to use as the recovery host. This is the host that you will run the restore operation on. - -. Establish SSH connectivity to each of the control plane nodes, including the recovery host. -+ -The Kubernetes API server becomes inaccessible after the restore process starts, so you cannot access the control plane nodes. For this reason, it is recommended to establish SSH connectivity to each control plane host in a separate terminal. -+ -[IMPORTANT] -==== -If you do not complete this step, you will not be able to access the master hosts to complete the restore procedure, and you will be unable to recover your cluster from this state. -==== - -. Copy the etcd backup directory to the recovery control plane host. -+ -This procedure assumes that you copied the `backup` directory containing the etcd snapshot and the resources for the static pods to the `/home/core/` directory of your recovery control plane host. - -. Stop the static pods on all other control plane nodes. -+ -[NOTE] -==== -It is not required to manually stop the pods on the recovery host. The recovery script will stop the pods on the recovery host. -==== - -.. Access a control plane host that is not the recovery host. - -.. Move the existing etcd pod file out of the kubelet manifest directory: -+ -[source,terminal] ----- -[core@ip-10-0-154-194 ~]$ sudo mv /etc/kubernetes/manifests/etcd-pod.yaml /tmp ----- - -.. Verify that the etcd pods are stopped. -+ -[source,terminal] ----- -[core@ip-10-0-154-194 ~]$ sudo crictl ps | grep etcd | grep -v operator ----- -+ -The output of this command should be empty. If it is not empty, wait a few minutes and check again. - -.. Move the existing Kubernetes API server pod file out of the kubelet manifest directory: -+ -[source,terminal] ----- -[core@ip-10-0-154-194 ~]$ sudo mv /etc/kubernetes/manifests/kube-apiserver-pod.yaml /tmp ----- - -.. Verify that the Kubernetes API server pods are stopped. -+ -[source,terminal] ----- -[core@ip-10-0-154-194 ~]$ sudo crictl ps | grep kube-apiserver | grep -v operator ----- -+ -The output of this command should be empty. If it is not empty, wait a few minutes and check again. - -.. Move the etcd data directory to a different location: -+ -[source,terminal] ----- -[core@ip-10-0-154-194 ~]$ sudo mv /var/lib/etcd/ /tmp ----- - -.. Repeat this step on each of the other master hosts that is not the recovery host. - -. Access the recovery control plane host. - - -. If the cluster-wide proxy is enabled, be sure that you have exported the `NO_PROXY`, `HTTP_PROXY`, and `HTTPS_PROXY` environment variables. -+ -[TIP] -==== -You can check whether the proxy is enabled by reviewing the output of `oc get proxy cluster -o yaml`. The proxy is enabled if the `httpProxy`, `httpsProxy`, and `noProxy` fields have values set. -==== - -. Run the restore script on the recovery control plane host and pass in the path to the etcd backup directory: -+ -[source,terminal] ----- -[core@ip-10-0-143-125 ~]$ sudo -E /usr/local/bin/cluster-restore.sh /home/core/backup ----- -+ -.Example script output -[source,terminal] ----- -...stopping kube-scheduler-pod.yaml -...stopping kube-controller-manager-pod.yaml -...stopping etcd-pod.yaml -...stopping kube-apiserver-pod.yaml -Waiting for container etcd to stop -.complete -Waiting for container etcdctl to stop -.............................complete -Waiting for container etcd-metrics to stop -complete -Waiting for container kube-controller-manager to stop -complete -Waiting for container kube-apiserver to stop -..........................................................................................complete -Waiting for container kube-scheduler to stop -complete -Moving etcd data-dir /var/lib/etcd/member to /var/lib/etcd-backup -starting restore-etcd static pod -starting kube-apiserver-pod.yaml -static-pod-resources/kube-apiserver-pod-7/kube-apiserver-pod.yaml -starting kube-controller-manager-pod.yaml -static-pod-resources/kube-controller-manager-pod-7/kube-controller-manager-pod.yaml -starting kube-scheduler-pod.yaml -static-pod-resources/kube-scheduler-pod-8/kube-scheduler-pod.yaml ----- - -. Restart the kubelet service on all master hosts. - -.. From the recovery host, run the following command: -+ -[source,terminal] ----- -[core@ip-10-0-143-125 ~]$ sudo systemctl restart kubelet.service ----- - -.. Repeat this step on all other master hosts. - -. Verify that the single member control plane has started successfully. - -.. From the recovery host, verify that the etcd container is running. -+ -[source,terminal] ----- -[core@ip-10-0-143-125 ~]$ sudo crictl ps | grep etcd | grep -v operator ----- -+ -.Example output -[source,terminal] ----- -3ad41b7908e32 36f86e2eeaaffe662df0d21041eb22b8198e0e58abeeae8c743c3e6e977e8009 About a minute ago Running etcd 0 7c05f8af362f0 ----- - -.. From the recovery host, verify that the etcd pod is running. -+ -[source,terminal] ----- -[core@ip-10-0-143-125 ~]$ oc get pods -n openshift-etcd | grep -v etcd-quorum-guard | grep etcd ----- -+ -[NOTE] -==== -If you attempt to run `oc login` prior to running this command and receive the following error, wait a few moments for the authentication controllers to start and try again. - -[source,terminal] ----- -Unable to connect to the server: EOF ----- -==== -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -etcd-ip-10-0-143-125.ec2.internal 1/1 Running 1 2m47s ----- -+ -If the status is `Pending`, or the output lists more than one running etcd pod, wait a few minutes and check again. - -. Force etcd redeployment. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc patch etcd cluster -p='{"spec": {"forceRedeploymentReason": "recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge <1> ----- -<1> The `forceRedeploymentReason` value must be unique, which is why a timestamp is appended. -+ -When the etcd cluster Operator performs a redeployment, the existing nodes are started with new pods similar to the initial bootstrap scale up. - -. Verify all nodes are updated to the latest revision. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc get etcd -o=jsonpath='{range .items[0].status.conditions[?(@.type=="NodeInstallerProgressing")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -Review the `NodeInstallerProgressing` status condition for etcd to verify that all nodes are at the latest revision. The output shows `AllNodesAtLatestRevision` upon successful update: -+ -[source,terminal] ----- -AllNodesAtLatestRevision -3 nodes are at revision 7 <1> ----- -<1> In this example, the latest revision number is `7`. -+ -If the output includes multiple revision numbers, such as `2 nodes are at revision 6; 1 nodes are at revision 7`, this means that the update is still in progress. Wait a few minutes and try again. - -. After etcd is redeployed, force new rollouts for the control plane. The Kubernetes API server will reinstall itself on the other nodes because the kubelet is connected to API servers using an internal load balancer. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following commands. - -.. Update the `kubeapiserver`: -+ -[source,terminal] ----- -$ oc patch kubeapiserver cluster -p='{"spec": {"forceRedeploymentReason": "recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge ----- -+ -Verify all nodes are updated to the latest revision. -+ -[source,terminal] ----- -$ oc get kubeapiserver -o=jsonpath='{range .items[0].status.conditions[?(@.type=="NodeInstallerProgressing")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -Review the `NodeInstallerProgressing` status condition to verify that all nodes are at the latest revision. The output shows `AllNodesAtLatestRevision` upon successful update: -+ -[source,terminal] ----- -AllNodesAtLatestRevision -3 nodes are at revision 7 <1> ----- -<1> In this example, the latest revision number is `7`. -+ -If the output includes multiple revision numbers, such as `2 nodes are at revision 6; 1 nodes are at revision 7`, this means that the update is still in progress. Wait a few minutes and try again. - -.. Update the `kubecontrollermanager`: -+ -[source,terminal] ----- -$ oc patch kubecontrollermanager cluster -p='{"spec": {"forceRedeploymentReason": "recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge ----- -+ -Verify all nodes are updated to the latest revision. -+ -[source,terminal] ----- -$ oc get kubecontrollermanager -o=jsonpath='{range .items[0].status.conditions[?(@.type=="NodeInstallerProgressing")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -Review the `NodeInstallerProgressing` status condition to verify that all nodes are at the latest revision. The output shows `AllNodesAtLatestRevision` upon successful update: -+ -[source,terminal] ----- -AllNodesAtLatestRevision -3 nodes are at revision 7 <1> ----- -<1> In this example, the latest revision number is `7`. -+ -If the output includes multiple revision numbers, such as `2 nodes are at revision 6; 1 nodes are at revision 7`, this means that the update is still in progress. Wait a few minutes and try again. - -.. Update the `kubescheduler`: -+ -[source,terminal] ----- -$ oc patch kubescheduler cluster -p='{"spec": {"forceRedeploymentReason": "recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge ----- -+ -Verify all nodes are updated to the latest revision. -+ -[source,terminal] ----- -$ oc get kubescheduler -o=jsonpath='{range .items[0].status.conditions[?(@.type=="NodeInstallerProgressing")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -Review the `NodeInstallerProgressing` status condition to verify that all nodes are at the latest revision. The output shows `AllNodesAtLatestRevision` upon successful update: -+ -[source,terminal] ----- -AllNodesAtLatestRevision -3 nodes are at revision 7 <1> ----- -<1> In this example, the latest revision number is `7`. -+ -If the output includes multiple revision numbers, such as `2 nodes are at revision 6; 1 nodes are at revision 7`, this means that the update is still in progress. Wait a few minutes and try again. - -. Verify that all master hosts have started and joined the cluster. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc get pods -n openshift-etcd | grep -v etcd-quorum-guard | grep etcd ----- -+ -.Example output -[source,terminal] ----- -etcd-ip-10-0-143-125.ec2.internal 2/2 Running 0 9h -etcd-ip-10-0-154-194.ec2.internal 2/2 Running 0 9h -etcd-ip-10-0-173-171.ec2.internal 2/2 Running 0 9h ----- - -Note that it might take several minutes after completing this procedure for all services to be restored. For example, authentication by using `oc login` might not immediately work until the OAuth server pods are restarted. diff --git a/modules/dynamic-provisioning-about.adoc b/modules/dynamic-provisioning-about.adoc deleted file mode 100644 index fad366e3c254..000000000000 --- a/modules/dynamic-provisioning-about.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="about_{context}"] -= About dynamic provisioning - -The `StorageClass` resource object describes and classifies storage that can -be requested, as well as provides a means for passing parameters for -dynamically provisioned storage on demand. `StorageClass` objects can also -serve as a management mechanism for controlling different levels of -storage and access to the storage. Cluster Administrators (`cluster-admin`) - or Storage Administrators (`storage-admin`) define and create the -`StorageClass` objects that users can request without needing any detailed -knowledge about the underlying storage volume sources. - -The {product-title} persistent volume framework enables this functionality -and allows administrators to provision a cluster with persistent storage. -The framework also gives users a way to request those resources without -having any knowledge of the underlying infrastructure. - -Many storage types are available for use as persistent volumes in -{product-title}. While all of them can be statically provisioned by an -administrator, some types of storage are created dynamically using the -built-in provider and plug-in APIs. diff --git a/modules/dynamic-provisioning-annotations.adoc b/modules/dynamic-provisioning-annotations.adoc deleted file mode 100644 index 7875a7a6efd3..000000000000 --- a/modules/dynamic-provisioning-annotations.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="storage-class-annotations_{context}"] -= Storage class annotations - -To set a storage class as the cluster-wide default, add -the following annotation to your storage class metadata: - -[source,yaml] ----- -storageclass.kubernetes.io/is-default-class: "true" ----- - -For example: - -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - annotations: - storageclass.kubernetes.io/is-default-class: "true" -... ----- - -This enables any persistent volume claim (PVC) that does not specify a -specific storage class to automatically be provisioned through the -default storage class. - -[NOTE] -==== -The beta annotation `storageclass.beta.kubernetes.io/is-default-class` is -still working; however, it will be removed in a future release. -==== - -To set a storage class description, add the following annotation -to your storage class metadata: - -[source,yaml] ----- -kubernetes.io/description: My Storage Class Description ----- - -For example: - -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - annotations: - kubernetes.io/description: My Storage Class Description -... ----- diff --git a/modules/dynamic-provisioning-available-plugins.adoc b/modules/dynamic-provisioning-available-plugins.adoc deleted file mode 100644 index df167f160237..000000000000 --- a/modules/dynamic-provisioning-available-plugins.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module included in the following assemblies -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="available-plug-ins_{context}"] -= Available dynamic provisioning plug-ins - -{product-title} provides the following provisioner plug-ins, which have -generic implementations for dynamic provisioning that use the cluster's -configured provider's API to create new storage resources: - - -[options="header",cols="1,1,1"] -|=== - -|Storage type -|Provisioner plug-in name -|Notes - -|{rh-openstack-first} Cinder -|`kubernetes.io/cinder` -| - -|{rh-openstack} Manila Container Storage Interface (CSI) -|`manila.csi.openstack.org` -|Once installed, the OpenStack Manila CSI Driver Operator and ManilaDriver automatically create the required storage classes for all available Manila share types needed for dynamic provisioning. - -|AWS Elastic Block Store (EBS) -|`kubernetes.io/aws-ebs` -|For dynamic provisioning when using multiple clusters in different zones, -tag each node with `Key=kubernetes.io/cluster/<cluster_name>,Value=<cluster_id>` -where `<cluster_name>` and `<cluster_id>` are unique per cluster. - -|AWS Elastic File System (EFS) -| -|Dynamic provisioning is accomplished through the EFS provisioner Pod and -not through a provisioner plug-in. - -|Azure Disk -|`kubernetes.io/azure-disk` -| - -|Azure File -|`kubernetes.io/azure-file` -|The `persistent-volume-binder` service account requires permissions to create -and get secrets to store the Azure storage account and keys. - -|GCE Persistent Disk (gcePD) -|`kubernetes.io/gce-pd` -|In multi-zone configurations, it is advisable to run one {product-title} -cluster per GCE project to avoid PVs from being created in zones where -no node in the current cluster exists. - -//|GlusterFS -//|`kubernetes.io/glusterfs` -//| - -//|Ceph RBD -//|`kubernetes.io/rbd` -//| - -//|Trident from NetApp -//|`netapp.io/trident` -//|Storage orchestrator for NetApp ONTAP, SolidFire, and E-Series storage. - -|link:https://www.vmware.com/support/vsphere.html[VMware vSphere] -|`kubernetes.io/vsphere-volume` -| - -//|HPE Nimble Storage -//|`hpe.com/nimble` -//|Dynamic provisioning of HPE Nimble Storage resources using the -//HPE Nimble Kube Storage Controller. - -|=== - -[IMPORTANT] -==== -Any chosen provisioner plug-in also requires configuration for the relevant -cloud, host, or third-party provider as per the relevant documentation. -==== diff --git a/modules/dynamic-provisioning-aws-definition.adoc b/modules/dynamic-provisioning-aws-definition.adoc deleted file mode 100644 index 557a2bbf15a3..000000000000 --- a/modules/dynamic-provisioning-aws-definition.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="aws-definition_{context}"] -= AWS Elastic Block Store (EBS) object definition - -.aws-ebs-storageclass.yaml -[source,yaml] ----- -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: slow -provisioner: kubernetes.io/aws-ebs -parameters: - type: io1 <1> - iopsPerGB: "10" <2> - encrypted: "true" <3> - kmsKeyId: keyvalue <4> - fsType: ext4 <5> ----- -<1> (required) Select from `io1`, `gp2`, `sc1`, `st1`. The default is `gp2`. -See the -link:http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[AWS documentation] -for valid Amazon Resource Name (ARN) values. -<2> (optional) Only for *io1* volumes. I/O operations per second per GiB. -The AWS volume plug-in multiplies this with the size of the requested -volume to compute IOPS of the volume. The value cap is 20,000 IOPS, which -is the maximum supported by AWS. See the -link:http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[AWS documentation] -for further details. -<3> (optional) Denotes whether to encrypt the EBS volume. Valid values -are `true` or `false`. -<4> (optional) The full ARN of the key to use when encrypting the volume. -If none is supplied, but `encypted` is set to `true`, then AWS generates a -key. See the -link:http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[AWS documentation] -for a valid ARN value. -<5> (optional) File system that is created on dynamically provisioned -volumes. This value is copied to the `fsType` field of dynamically -provisioned persistent volumes and the file system is created when the -volume is mounted for the first time. The default value is `ext4`. diff --git a/modules/dynamic-provisioning-azure-disk-definition.adoc b/modules/dynamic-provisioning-azure-disk-definition.adoc deleted file mode 100644 index 4fa7176193ba..000000000000 --- a/modules/dynamic-provisioning-azure-disk-definition.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="azure-disk-definition_{context}"] -= Azure Disk object definition - -.azure-advanced-disk-storageclass.yaml -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: managed-premium - annotations: - storageclass.kubernetes.io/is-default-class: "true" -provisioner: kubernetes.io/azure-disk -volumeBindingMode: WaitForFirstConsumer <1> -allowVolumeExpansion: true -parameters: - kind: Managed <2> - storageaccounttype: Premium_LRS <3> -reclaimPolicy: Delete ----- -<1> Using `WaitForFirstConsumer` is strongly recommended. This provisions the volume while allowing enough storage to schedule the pod on a free worker node from an available zone. -<2> Possible values are `Shared` (default), `Managed`, and `Dedicated`. -+ -[IMPORTANT] -==== -Red Hat only supports the use of `kind: Managed` in the storage class. - -With `Shared` and `Dedicated`, Azure creates unmanaged disks, while {product-title} creates a managed disk for machine OS (root) disks. But because Azure Disk does not allow the use of both managed and unmanaged disks on a node, unmanaged disks created with `Shared` or `Dedicated` cannot be attached to {product-title} nodes. -==== - -<3> Azure storage account SKU tier. Default is empty. Note that Premium VMs can attach both `Standard_LRS` and `Premium_LRS` disks, Standard VMs can only attach `Standard_LRS` disks, Managed VMs can only attach managed disks, and unmanaged VMs can only attach unmanaged disks. -+ -.. If `kind` is set to `Shared`, Azure creates all unmanaged disks in a few shared storage accounts in the same resource group as the cluster. -.. If `kind` is set to `Managed`, Azure creates new managed disks. -.. If `kind` is set to `Dedicated` and a `storageAccount` is specified, Azure uses the specified storage account for the new unmanaged disk in the same resource group as the cluster. For this to work: - * The specified storage account must be in the same region. - * Azure Cloud Provider must have write access to the storage account. -.. If `kind` is set to `Dedicated` and a `storageAccount` is not specified, Azure creates a new dedicated storage account for the new unmanaged disk in the same resource group as the cluster. diff --git a/modules/dynamic-provisioning-azure-file-considerations.adoc b/modules/dynamic-provisioning-azure-file-considerations.adoc deleted file mode 100644 index 5a89d1d66e99..000000000000 --- a/modules/dynamic-provisioning-azure-file-considerations.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-azure-file.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="azure-file-considerations_{context}"] -= Considerations when using Azure File - -The following file system features are not supported by the default Azure File storage class: - -* Symlinks -* Hard links -* Extended attributes -* Sparse files -* Named pipes - -Additionally, the owner user identifier (UID) of the Azure File mounted directory is different from the process UID of the container. The `uid` mount option can be specified in the `StorageClass` object to define -a specific user identifier to use for the mounted directory. - -The following `StorageClass` object demonstrates modifying the user and group identifier, along with enabling symlinks for the mounted directory. - -[source,yaml] ----- -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: azure-file -mountOptions: - - uid=1500 <1> - - gid=1500 <2> - - mfsymlinks <3> -provisioner: kubernetes.io/azure-file -parameters: - location: eastus - skuName: Standard_LRS -reclaimPolicy: Delete -volumeBindingMode: Immediate ----- -<1> Specifies the user identifier to use for the mounted directory. -<2> Specifies the group identifier to use for the mounted directory. -<3> Enables symlinks. diff --git a/modules/dynamic-provisioning-azure-file-definition.adoc b/modules/dynamic-provisioning-azure-file-definition.adoc deleted file mode 100644 index 306e2f11794b..000000000000 --- a/modules/dynamic-provisioning-azure-file-definition.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - - -[id="azure-file-definition_{context}"] -= Azure File object definition - -The Azure File storage class uses secrets to store the Azure storage account name -and the storage account key that are required to create an Azure Files share. These -permissions are created as part of the following procedure. - -.Procedure - -. Define a `ClusterRole` object that allows access to create and view secrets: -+ -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: -# name: system:azure-cloud-provider - name: <persistent-volume-binder-role> <1> -rules: -- apiGroups: [''] - resources: ['secrets'] - verbs: ['get','create'] ----- -<1> The name of the cluster role to view and create secrets. - -. Add the cluster role to the service account: -+ -[source,terminal] ----- -$ oc adm policy add-cluster-role-to-user <persistent-volume-binder-role> ----- -+ -.Example output -[source,terminal] ----- - system:serviceaccount:kube-system:persistent-volume-binder ----- - -. Create the Azure File `StorageClass` object: -+ -[source,yaml] ----- -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: <azure-file> <1> -provisioner: kubernetes.io/azure-file -parameters: - location: eastus <2> - skuName: Standard_LRS <3> - storageAccount: <storage-account> <4> -reclaimPolicy: Delete -volumeBindingMode: Immediate ----- -<1> Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes. -<2> Location of the Azure storage account, such as `eastus`. Default is empty, meaning that a new Azure storage account will be created in the {product-title} cluster's location. -<3> SKU tier of the Azure storage account, such as `Standard_LRS`. Default is empty, meaning that a new Azure storage account will be created with the `Standard_LRS` SKU. -<4> Name of the Azure storage account. If a storage account is provided, then -`skuName` and `location` are ignored. If no storage account is provided, then -the storage class searches for any storage account that is associated with the -resource group for any accounts that match the defined `skuName` and `location`. diff --git a/modules/dynamic-provisioning-ceph-rbd-definition.adoc b/modules/dynamic-provisioning-ceph-rbd-definition.adoc deleted file mode 100644 index 58c77075fbcd..000000000000 --- a/modules/dynamic-provisioning-ceph-rbd-definition.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc - -[id="ceph-rbd-definition_{context}"] -= Ceph RBD object definition - -.ceph-storageclass.yaml -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: cephfs -provisioner: kubernetes.io/rbd -parameters: - monitors: 10.16.153.105:6789 <1> - adminId: admin <2> - adminSecretName: ceph-secret <3> - adminSecretNamespace: kube-system <4> - pool: kube <5> - userId: kube <6> - userSecretName: ceph-secret-user <7> - fsType: ext4 <8> - imageFormat: "2" <9> ----- -<1> (required) A comma-delimited list of Ceph monitors. -<2> (optional) Ceph client ID that is capable of creating images in the -pool. Default is `admin`. -<3> (required) Secret Name for `adminId`. The provided secret must have -type `kubernetes.io/rbd`. -<4> (optional) The namespace for `adminSecret`. Default is `default`. -<5> (optional) Ceph RBD pool. Default is `rbd`. -<6> (optional) Ceph client ID that is used to map the Ceph RBD image. -Default is the same as `adminId`. -<7> (required) The name of Ceph Secret for `userId` to map Ceph RBD image. -It must exist in the same namespace as PVCs. -<8> (optional) File system that is created on dynamically provisioned -volumes. This value is copied to the `fsType` field of dynamically -provisioned persistent volumes and the file system is created when the -volume is mounted for the first time. The default value is `ext4`. -<9> (optional) Ceph RBD image format. The default value is `2`. diff --git a/modules/dynamic-provisioning-change-default-class.adoc b/modules/dynamic-provisioning-change-default-class.adoc deleted file mode 100644 index 691721fd4f0d..000000000000 --- a/modules/dynamic-provisioning-change-default-class.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc -// * post_installation_configuration/storage-configuration.adoc - - -[id="change-default-storage-class_{context}"] -= Changing the default storage class - -If you are using AWS, use the following process to change the default -storage class. This process assumes you have two storage classes -defined, `gp2` and `standard`, and you want to change the default -storage class from `gp2` to `standard`. - -. List the storage class: -+ -[source,terminal] ----- -$ oc get storageclass ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE -gp2 (default) kubernetes.io/aws-ebs <1> -standard kubernetes.io/aws-ebs ----- -<1> `(default)` denotes the default storage class. - -. Change the value of the annotation -`storageclass.kubernetes.io/is-default-class` to `false` for the default -storage class: -+ -[source,terminal] ----- -$ oc patch storageclass gp2 -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "false"}}}' ----- - -. Make another storage class the default by adding or modifying the -annotation as `storageclass.kubernetes.io/is-default-class=true`. -+ -[source,terminal] ----- -$ oc patch storageclass standard -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}' ----- - -. Verify the changes: -+ -[source,terminal] ----- -$ oc get storageclass ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE -gp2 kubernetes.io/aws-ebs -standard (default) kubernetes.io/aws-ebs ----- diff --git a/modules/dynamic-provisioning-cinder-definition.adoc b/modules/dynamic-provisioning-cinder-definition.adoc deleted file mode 100644 index eec8fc4917d8..000000000000 --- a/modules/dynamic-provisioning-cinder-definition.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="openstack-cinder-storage-class_{context}"] -= {rh-openstack} Cinder object definition - -.cinder-storageclass.yaml -[source,yaml] ----- -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: gold -provisioner: kubernetes.io/cinder -parameters: - type: fast <1> - availability: nova <2> - fsType: ext4 <3> ----- -<1> Volume type created in Cinder. Default is empty. -<2> Availability Zone. If not specified, volumes are generally -round-robined across all active zones where the {product-title} cluster -has a node. -<3> File system that is created on dynamically provisioned volumes. This -value is copied to the `fsType` field of dynamically provisioned -persistent volumes and the file system is created when the volume is -mounted for the first time. The default value is `ext4`. diff --git a/modules/dynamic-provisioning-defining-storage-class.adoc b/modules/dynamic-provisioning-defining-storage-class.adoc deleted file mode 100644 index 6369d5b6dc60..000000000000 --- a/modules/dynamic-provisioning-defining-storage-class.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="defining-storage-classes_{context}"] -= Defining a storage class - -`StorageClass` objects are currently a globally scoped object and must be -created by `cluster-admin` or `storage-admin` users. - -[IMPORTANT] -==== -The Cluster Storage Operator might install a default storage class depending -on the platform in use. This storage class is owned and controlled by the -operator. It cannot be deleted or modified beyond defining annotations -and labels. If different behavior is desired, you must define a custom -storage class. -==== - -The following sections describe the basic definition for a -`StorageClass` object and specific examples for each of the supported plug-in types. diff --git a/modules/dynamic-provisioning-gce-definition.adoc b/modules/dynamic-provisioning-gce-definition.adoc deleted file mode 100644 index bb95a1239326..000000000000 --- a/modules/dynamic-provisioning-gce-definition.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="gce-persistentdisk-storage-class_{context}"] -= GCE PersistentDisk (gcePD) object definition - -.gce-pd-storageclass.yaml -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: standard - annotations: - storageclass.kubernetes.io/is-default-class: "true" -provisioner: kubernetes.io/gce-pd -parameters: - type: pd-standard <1> - replication-type: none -volumeBindingMode: WaitForFirstConsumer -allowVolumeExpansion: true -reclaimPolicy: Delete ----- -<1> Select either `pd-standard` or `pd-ssd`. The default is `pd-standard`. diff --git a/modules/dynamic-provisioning-gluster-definition.adoc b/modules/dynamic-provisioning-gluster-definition.adoc deleted file mode 100644 index 0089db152287..000000000000 --- a/modules/dynamic-provisioning-gluster-definition.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc - -[id="gluster-definition_{context}"] -= GlusterFS object definition - -.glusterfs-storageclass.yaml -[source,yaml] ----- -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: slow -provisioner: kubernetes.io/glusterfs -parameters: <1> - resturl: http://127.0.0.1:8081 <2> - restuser: admin <3> - secretName: heketi-secret <4> - secretNamespace: default <5> - gidMin: "40000" <6> - gidMax: "50000" <7> - volumeoptions: group metadata-cache, nl-cache on <8> - volumetype: replicate:3 <9> ----- -<1> Listed are mandatory and a few optional parameters. Refer to -link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/3.10/html-single/operations_guide/#sect_file_reg_storageclass[Registering a Storage Class] for additional parameters. -<2> link:https://github.com/heketi/heketi[heketi] (volume management REST -service for Gluster) URL that provisions GlusterFS volumes on demand. The -general format should be `{http/https}://{IPaddress}:{Port}`. This is a -mandatory parameter for the GlusterFS dynamic provisioner. If the heketi -service is exposed as a routable service in the {product-title}, it will -have a resolvable fully qualified domain name (FQDN) and heketi service URL. -<3> heketi user who has access to create volumes. This is typically `admin`. -<4> Identification of a Secret that contains a user password to use when -talking to heketi. An empty password will be used -when both `secretNamespace` and `secretName` are omitted. -The provided secret must be of type `"kubernetes.io/glusterfs"`. -<5> The namespace of mentioned `secretName`. An empty password will be used -when both `secretNamespace` and `secretName` are omitted. The provided -Secret must be of type `"kubernetes.io/glusterfs"`. -<6> Optional. The minimum value of the GID range for volumes of this -StorageClass. -<7> Optional. The maximum value of the GID range for volumes of this -StorageClass. -<8> Optional. Options for newly created volumes. It allows for -performance tuning. See -link:https://docs.gluster.org/en/v3/Administrator%20Guide/Managing%20Volumes/#tuning-volume-options[Tuning Volume Options] -for more GlusterFS volume options. -<9> Optional. The -link:https://docs.gluster.org/en/v3/Quick-Start-Guide/Architecture/[type of volume] -to use. - -[NOTE] -==== -When the `gidMin` and `gidMax` values are not specified, their defaults are -2000 and 2147483647 respectively. Each dynamically provisioned volume -will be given a GID in this range (`gidMin-gidMax`). This GID is released -from the pool when the respective volume is deleted. The GID pool is -per StorageClass. -If two or more storage classes have GID ranges that overlap there may be -duplicate GIDs dispatched by the provisioner. -==== - -When heketi authentication is used, a Secret containing the admin key must -also exist. - -[source,terminal] ----- -$ oc create secret generic heketi-secret --from-literal=key=<password> -n <namespace> --type=kubernetes.io/glusterfs ----- - -This results in the following configuration: - -.heketi-secret.yaml -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: heketi-secret - namespace: namespace - ... -data: - key: cGFzc3dvcmQ= <1> -type: kubernetes.io/glusterfs ----- -<1> base64 encoded password - -[NOTE] -==== -When the PVs are dynamically provisioned, the GlusterFS plug-in -automatically creates an Endpoints and a headless Service named -`gluster-dynamic-<claimname>`. When the PVC is deleted, these dynamic -resources are deleted automatically. -==== diff --git a/modules/dynamic-provisioning-manila-csi-definition.adoc b/modules/dynamic-provisioning-manila-csi-definition.adoc deleted file mode 100644 index 844bcda0f8de..000000000000 --- a/modules/dynamic-provisioning-manila-csi-definition.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc - -[id="openstack-manila-csi-definition_{context}"] -= {rh-openstack} Manila Container Storage Interface (CSI) object definition - -Once installed, the OpenStack Manila CSI Driver Operator and ManilaDriver automatically create the required storage classes for all available Manila share types needed for dynamic provisioning. diff --git a/modules/dynamic-provisioning-storage-class-definition.adoc b/modules/dynamic-provisioning-storage-class-definition.adoc deleted file mode 100644 index f484a8e96e9d..000000000000 --- a/modules/dynamic-provisioning-storage-class-definition.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="basic-storage-class-definition_{context}"] -= Basic `StorageClass` object definition - -The following resource shows the parameters and default values that you -use to configure a storage class. This example uses the AWS -ElasticBlockStore (EBS) object definition. - - -.Sample `StorageClass` definition -[source,yaml] ----- -kind: StorageClass <1> -apiVersion: storage.k8s.io/v1 <2> -metadata: - name: gp2 <3> - annotations: <4> - storageclass.kubernetes.io/is-default-class: 'true' - ... -provisioner: kubernetes.io/aws-ebs <5> -parameters: <6> - type: gp2 -... ----- -<1> (required) The API object type. -<2> (required) The current apiVersion. -<3> (required) The name of the storage class. -<4> (optional) Annotations for the storage class. -<5> (required) The type of provisioner associated with this storage class. -<6> (optional) The parameters required for the specific provisioner, this -will change from plug-in to plug-in. diff --git a/modules/dynamic-provisioning-vsphere-definition.adoc b/modules/dynamic-provisioning-vsphere-definition.adoc deleted file mode 100644 index e02e11d3f82d..000000000000 --- a/modules/dynamic-provisioning-vsphere-definition.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following definitions: -// -// * storage/dynamic-provisioning.adoc -// * post_installation_configuration/storage-configuration.adoc - - -[id="vsphere-definition_{context}"] -= VMware vSphere object definition - -.vsphere-storageclass.yaml -[source,yaml] ----- -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: slow -provisioner: kubernetes.io/vsphere-volume <1> -parameters: - diskformat: thin <2> ----- -<1> For more information about using VMware vSphere with {product-title}, -see the -link:https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/index.html[VMware vSphere documentation]. -<2> `diskformat`: `thin`, `zeroedthick` and `eagerzeroedthick` are all -valid disk formats. See vSphere docs for additional details regarding the -disk format types. The default value is `thin`. diff --git a/modules/enable-admission-controller-enforcement.adoc b/modules/enable-admission-controller-enforcement.adoc new file mode 100644 index 000000000000..b36cd4bba585 --- /dev/null +++ b/modules/enable-admission-controller-enforcement.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/use-admission-controller-enforcement.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-admission-controller-enforcement_{context}"] += Enabling admission controller enforcement + +[role="_abstract"] +You can enable admission controller enforcement from the *Clusters* view when you install Sensor or edit an existing cluster configuration. + +//Add something here about how enforcement can be enabled in individual policies + +//Also add something about how it needs to be configured when installing the Operator, if you have chosen an Operator install method + +//This section will be heavily changed for 4.9 in a separate PR + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. +. Select an existing cluster from the list or secure a new cluster by selecting *Secure a cluster* -> *Legacy installation method*. +. If you are securing a new cluster, in the *Static Configuration* section of the cluster configuration panel, enter the details for your cluster. +. Red{nbsp}Hat recommends that you only turn on the *Configure Admission Controller Webhook to listen on Object Creates* toggle if you are planning to use the admission controller to enforce on object create events. +. Red{nbsp}Hat recommends that you only turn on the *Configure Admission Controller Webhook to listen on Object Updates* toggle if you are planning to use the admission controller to enforce on update events. +. Red{nbsp}Hat recommends that you only turn on the *Enable Admission Controller Webhook to listen on exec and port-forward events* toggle if you are planning to use the admission controller to enforce on pod execution and pod port forwards events. +. Configure the following options in the *Dynamic Configuration* section: +** *Enforce on Object Creates*: This toggle controls the behavior of the admission control service. +You must have the *Configure Admission Controller Webhook to listen on Object Creates* toggle turned on for this to work. +** *Enforce on Object Updates*: This toggle controls the behavior of the admission control service. +You must have the *Configure Admission Controller Webhook to listen on Object Updates* toggle turned on for this to work. +. Select *Next*. +. In the *Download files* section, select *Download YAML files and keys*. ++ +[NOTE] +==== +When enabling admission controller for an existing cluster, follow this guidance: + +* If you make any changes in the *Static Configuration* section, you must download the YAML files and redeploy the Sensor. +* If you make any changes in the *Dynamic Configuration* section, you can skip downloading the files and deployment, as {product-title-short} automatically synchronizes the Sensor and applies the changes. +==== +. Select *Finish*. + +.Verification +* After you provision a new cluster with the generated YAML, run the following command to verify if admission controller enforcement is configured correctly: ++ +[source,terminal] +---- +$ oc get ValidatingWebhookConfiguration <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +.Example output +[source,terminal] +---- +NAME CREATED AT +stackrox 2019-09-24T06:07:34Z +---- diff --git a/modules/enable-alert-on-baseline-violations-ng20.adoc b/modules/enable-alert-on-baseline-violations-ng20.adoc new file mode 100644 index 000000000000..3afba1eaa891 --- /dev/null +++ b/modules/enable-alert-on-baseline-violations-ng20.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-alert-on-baseline-violations-ng20_{context}"] += Enabling alerts on baseline violations in the network graph + +You can configure {product-title-short} to detect anomalous network flows and trigger violations for traffic that is not in the baseline. This can help you determine if the network contains unwanted traffic before you block traffic with a network policy. + +.Procedure + +. Click the *Namespaces* list and use the search field to locate a namespace, or select individual namespaces. +. Click the *Deployments* list and use the search field to locate a deployment, or select individual deployments to display in the network graph. +. In the network graph, click on a deployment to view the information panel. +. In the *Baseline* tab, you can view baseline flows. Use the *filter by entity name* field to further restrict the flows that are displayed. +. Toggle the *Alert on baseline violations* option. +* After you toggle the *Alert on baseline violations* option, anomalous network flows trigger violations. +* You can toggle the *Alert on baseline violations* option again to stop receiving violations for anomalous network flows. diff --git a/modules/enable-audit-log.adoc b/modules/enable-audit-log.adoc new file mode 100644 index 000000000000..6bd29afd2025 --- /dev/null +++ b/modules/enable-audit-log.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * configuration/configure-audit-logging.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-audit-log_{context}"] += Enabling audit logging + +[role="_abstract"] +When you enable audit logging, every time there is a modification, {product-title} sends an HTTP POST message (in JSON format) to the configured system. + +.Prerequisites +* Configure Splunk or another webhook receiver to handle {product-title} log messages. +* You must have `write` permission enabled on the *Notifiers* resource for your role. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *Generic Webhook* or *Splunk*. +. Fill in the required information and turn on the *Enable Audit Logging* toggle. diff --git a/modules/enable-automatic-upgrades.adoc b/modules/enable-automatic-upgrades.adoc new file mode 100644 index 000000000000..f7245cd56f1d --- /dev/null +++ b/modules/enable-automatic-upgrades.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * configuration/configure-automatic-upgrades.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-automatic-upgrades_{context}"] += Enabling automatic upgrades for manifest-installed secured clusters + +You can enable automatic upgrades for all secured clusters that were installed by using the manifest installation method, also known as the `roxctl` CLI method. This feature automatically upgrades Sensor, Admission Controller, Collector, and Compliance in all secured clusters to the same version as Central. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. +. Turn on the *Automatically upgrade secured clusters* toggle. ++ +[NOTE] +==== +For new installations, the *Automatically upgrade secured clusters* toggle is enabled by default. +==== diff --git a/modules/enable-disable-online-telemetry-existing.adoc b/modules/enable-disable-online-telemetry-existing.adoc new file mode 100644 index 000000000000..47d6354d5a60 --- /dev/null +++ b/modules/enable-disable-online-telemetry-existing.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * configuration/online-telemetry.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-disable-online-telemetry-existing_{context}"] += Enabling or disabling online telemetry for an existing instance + +You can enable or disable online telemetry for an existing instance of {product-title} by using the {product-title-short} portal. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *System Configuration*. +. In the *System Configuration* view: +* Turn on the *Online Telemetry Data Collection* toggle to enable online telemetry. +* Turn off the *Online Telemetry Data Collection* toggle to disable online telemetry. diff --git a/modules/enable-monitoring-central-helm.adoc b/modules/enable-monitoring-central-helm.adoc new file mode 100644 index 000000000000..e1b6ad916ead --- /dev/null +++ b/modules/enable-monitoring-central-helm.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * configuration/monitor-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-monitoring-central-helm_{context}"] += Monitoring Central services by using Helm + +You can monitor Central services, Central and Scanner, by changing the configuration options in the `central-services` Helm chart. For more information, see "Changing configuration options after deploying the central-services Helm chart" in the "Additional resources" section. + +.Procedure +. Update the `values-public.yaml` configuration file with the following values: ++ +[source,yaml] +---- +central.exposeMonitoring: true +scanner.exposeMonitoring: true +---- +. Run the `helm upgrade` command and specify the configuration files. \ No newline at end of file diff --git a/modules/enable-monitoring-central-operator.adoc b/modules/enable-monitoring-central-operator.adoc new file mode 100644 index 000000000000..d13ec4e39fc9 --- /dev/null +++ b/modules/enable-monitoring-central-operator.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * configuration/monitor-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-monitoring-central-operator_{context}"] += Monitoring Central services by using the {product-title-short} Operator + +[role="_abstract"] +You can monitor Central services, Central and Scanner, by changing the configuration of the `Central` custom resource. For more information on configuration options, see "Central configuration options using the Operator" in the "Additional resources" section. + +.Procedure +. On the {ocp} web console, go to the *Operators* -> *Installed Operators* page. +. Select the {product-title} Operator from the list of installed Operators. +. Click on the *Central* tab. +. From the list of Central instances, click on a Central instance for which you want to enable monitoring for. +. Click on the *YAML* tab and update the YAML configuration: +* For monitoring Central, enable the `central.monitoring.exposeEndpoint` configuration option for the `Central` custom resource. +* For monitoring Scanner, enable the `scanner.monitoring.exposeEndpoint` configuration option for the `Central` custom resource. +. Click *Save*. \ No newline at end of file diff --git a/modules/enable-offline-mode-helm.adoc b/modules/enable-offline-mode-helm.adoc new file mode 100644 index 000000000000..572a12b718d8 --- /dev/null +++ b/modules/enable-offline-mode-helm.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-offline-mode-helm_{context}"] += Enabling offline mode by using Helm configuration + +You can enable offline mode during the installation when you are installing {product-title} by using a Helm chart. +//TODO: link to helm installation + +.Procedure + +. When installing the central-services Helm chart, set the value of the `env.offlineMode` environmental variable to `true` in the `values-public.yaml` configuration file. +. When installing the secured-cluster-services Helm chart, set the value of the `config.offlineMode` parameter to `true` in the `values-public.yaml` configuration file. + diff --git a/modules/enable-offline-mode-roxctl.adoc b/modules/enable-offline-mode-roxctl.adoc new file mode 100644 index 000000000000..19338fa1c227 --- /dev/null +++ b/modules/enable-offline-mode-roxctl.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-offline-mode-roxctl_{context}"] += Enabling offline mode by using the roxctl CLI + +You can enable offline mode when you are installing {product-title} by using the `roxctl` CLI. +//TODO: link to roxctl CLI installation + +.Procedure + +. If you are using a registry other than the default internet-connected registry (`registry.redhat.io`), provide the locations where you have pushed the {product-title} images when answering the `image to use` prompts: ++ +[source,terminal,subs=attributes+] +---- +Enter main image to use (if unset, the default will be used): <your_registry>/rhacs-main-rhel8:{rhacs-version} +---- ++ +[NOTE] +==== +The default image depends on your answer for the prompt `Enter default container images settings:`. If you entered `rhacs`, the default option, the default image will be `registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version}`. +==== + ++ +[source,terminal,subs=attributes+] +---- +Enter Scanner DB image to use (if unset, the default will be used): <your_registry>/rhacs-scanner-db-rhel8:{rhacs-version} +---- ++ +[source,terminal,subs=attributes+] +---- +Enter Scanner image to use (if unset, the default will be used): <your_registry>/rhacs-scanner-rhel8:{rhacs-version} +---- +. To enable the offline mode, enter `true` when answering the `Enter whether to run StackRox in offline mode` prompt: ++ +[source,terminal,subs=attributes+] +---- +Enter whether to run StackRox in offline mode, which avoids reaching out to the internet (default: "false"): true +---- +. Later, when you add Sensor to a remote cluster in the *Platform Configuration* -> *Clusters* view in the {product-title-short} portal, you must specify your the Collector image name in the *Collector Image Repository* field. diff --git a/modules/enable-traffic-flow-through-custom-ports.adoc b/modules/enable-traffic-flow-through-custom-ports.adoc new file mode 100644 index 000000000000..ab7d770bde0f --- /dev/null +++ b/modules/enable-traffic-flow-through-custom-ports.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * configuration/configure-endpoints.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-traffic-flow-through-custom-ports_{context}"] += Enabling traffic flow through custom ports + +If you are exposing a port to another service running in the same cluster or to an ingress controller, you must only allow traffic from the services in your cluster or from the proxy of the ingress controller. +Otherwise, if you are exposing a port by using a load balancer service, you might want to allow traffic from all sources, including external sources. Use the procedure listed in this section to allow traffic from all sources. + +.Procedure +. Clone the `allow-ext-to-central` Kubernetes network policy: ++ +[source,terminal] +---- +$ oc -n stackrox get networkpolicy.networking.k8s.io/allow-ext-to-central -o yaml > <directory_path>/allow-ext-to-central-custom-port.yaml +---- +. Use it as a reference to create your network policy, and in that policy, specify the port number you want to expose. +Make sure to change the name of your network policy in the `metadata` section of the YAML file, so that it does not interfere with the built-in `allow-ext-to-central` policy. diff --git a/modules/enabling-etcd-encryption.adoc b/modules/enabling-etcd-encryption.adoc deleted file mode 100644 index 702b185e3b59..000000000000 --- a/modules/enabling-etcd-encryption.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * security/encrypting-etcd.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="enabling-etcd-encryption_{context}"] -= Enabling etcd encryption - -You can enable etcd encryption to encrypt sensitive resources in your cluster. - -[WARNING] -==== -It is not recommended to take a backup of etcd until the initial encryption process is complete. If the encryption process has not completed, the backup might be only partially encrypted. -==== - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Modify the `APIServer` object: -+ -[source,terminal] ----- -$ oc edit apiserver ----- - -. Set the `encryption` field type to `aescbc`: -+ -[source,yaml] ----- -spec: - encryption: - type: aescbc <1> ----- -<1> The `aescbc` type means that AES-CBC with PKCS#7 padding and a 32 byte key is used to perform the encryption. - -. Save the file to apply the changes. -+ -The encryption process starts. It can take 20 minutes or longer for this process to complete, depending on the size of your cluster. - -. Verify that etcd encryption was successful. - -.. Review the `Encrypted` status condition for the OpenShift API server to verify that its resources were successfully encrypted: -+ -[source,terminal] ----- -$ oc get openshiftapiserver -o=jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -The output shows `EncryptionCompleted` upon successful encryption: -+ -[source,terminal] ----- -EncryptionCompleted -All resources encrypted: routes.route.openshift.io ----- -+ -If the output shows `EncryptionInProgress`, encryption is still in progress. Wait a few minutes and try again. - -.. Review the `Encrypted` status condition for the Kubernetes API server to verify that its resources were successfully encrypted: -+ -[source,terminal] ----- -$ oc get kubeapiserver -o=jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -The output shows `EncryptionCompleted` upon successful encryption: -+ -[source,terminal] ----- -EncryptionCompleted -All resources encrypted: secrets, configmaps ----- -+ -If the output shows `EncryptionInProgress`, encryption is still in progress. Wait a few minutes and try again. - -.. Review the `Encrypted` status condition for the OpenShift OAuth API server to verify that its resources were successfully encrypted: -+ -[source,terminal] ----- -$ oc get authentication.operator.openshift.io -o=jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -The output shows `EncryptionCompleted` upon successful encryption: -+ -[source,terminal] ----- -EncryptionCompleted -All resources encrypted: oauthaccesstokens.oauth.openshift.io, oauthauthorizetokens.oauth.openshift.io ----- -+ -If the output shows `EncryptionInProgress`, encryption is still in progress. Wait a few minutes and try again. diff --git a/modules/enabling-external-ip-collection-secured-clusters.adoc b/modules/enabling-external-ip-collection-secured-clusters.adoc new file mode 100644 index 000000000000..6475f8aa2417 --- /dev/null +++ b/modules/enabling-external-ip-collection-secured-clusters.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * operating/visualizing-external-entities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-external-ip-collection-secured-clusters_{context}"] += Enabling external IP collection in secured clusters + +[role="_abstract"] +To enable external IP collection in secured clusters, you must individually configure each secured cluster's runtime configuration. + +You can have some clusters with the functionality enabled while others remain disabled. In this case, external IP information is only available for the clusters where you have enabled the feature. + +You can use a `ConfigMap` object to enable the external IP collection in secured clusters. + +.Procedure + +* Create a `ConfigMap` object called `collector-config` with the following content: ++ +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: collector-config + namespace: stackrox +data: + runtime_config.yaml: | <1> + networking: + externalIps: + enabled: ENABLED <2> +---- +<1> {product-title-short} mounts this file at `/etc/stackrox/runtime_config.yaml`. +<2> `networking.externalIps.enable` was changed to `networking.externalIps.enabled` in {product-title-short} 4.7. It is an enum and can be set to `ENABLED` or `DISABLED`. + +When you create or update the `ConfigMap` object, the collector refreshes the runtime configuration. When you delete the `ConfigMap` object, the settings revert to the default runtime configuration values. For more information, see xref:../operating/using-collector-runtime-configuration.adoc#using-collector-runtime-configuration[Using Collector runtime configuration]. diff --git a/modules/enabling-internal-api-server-vsphere.adoc b/modules/enabling-internal-api-server-vsphere.adoc deleted file mode 100644 index b426519b840e..000000000000 --- a/modules/enabling-internal-api-server-vsphere.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc - -[id="enabling-internal-api-server-vsphere_{context}"] -= Enabling communication with the internal API server for the WMCO on vSphere - -The Windows Machine Config Operator (WMCO) downloads the Ignition config files from the internal API server endpoint. You must enable communication with the internal API server so that your Windows virtual machine (VM) can download the Ignition config files, and the kubelet on the configured VM can communicate with the internal API server. - -.Prerequisites - -* You have installed a cluster on vSphere. - -.Procedure - -* Add a new DNS entry for `api-int.<cluster_name>.<base_domain>` that points to the external API server URL `api.<cluster_name>.<base_domain>`. This can be a CNAME or an additional A record. - -[NOTE] -==== -The external API endpoint was already created as part of the initial cluster installation on vSphere. -==== diff --git a/modules/enabling-scanner-v4-after-helm-installation-central.adoc b/modules/enabling-scanner-v4-after-helm-installation-central.adoc new file mode 100644 index 000000000000..910920fbfce7 --- /dev/null +++ b/modules/enabling-scanner-v4-after-helm-installation-central.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-scanner-v4-after-helm-installation-central_{context}"] += Enabling RHACS Scanner V4 for Central when upgrading by using Helm + +[role="_abstract"] +You can enable Scanner V4 when upgrading by using Helm by enabling setting the `scannerV4.disable` parameter to `false`. + +.Procedure + +. On the cluster where Central is installed, run the following command, using the instructions in "Changing configuration options after deploying the central-services Helm chart" if you need more information: ++ +[source,terminal] +---- +$ helm upgrade -n stackrox \ + stackrox-central-services rhacs/central-services \ + --reuse-values \ + -f <path_to_values_public.yaml> \ + -f <path_to_generated-values.yaml> \// <1> + --set scannerV4.disable=false +---- +<1> When updating the system and installing a new component, you must provide the internal CA. See "Retrieving the automatically generated certificate authority". + diff --git a/modules/enabling-scanner-v4-after-helm-installation-secured-cluster.adoc b/modules/enabling-scanner-v4-after-helm-installation-secured-cluster.adoc new file mode 100644 index 000000000000..d2f9371d1cc6 --- /dev/null +++ b/modules/enabling-scanner-v4-after-helm-installation-secured-cluster.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-scanner-v4-after-helm-installation-secured-cluster_{context}"] += Enabling RHACS Scanner V4 on the secured cluster when upgrading by using Helm + +[role="_abstract"] +You can enable Scanner V4 when upgrading by using Helm. + +.Prerequisites + +* You set up Central and the secured cluster by using an init bundle or CRS so that they can communicate with each other. + +.Procedure + +. On the secured cluster, run the following command, using the instructions in "Configuring the secured-cluster-services Helm chart with customizations" if you need more information: ++ +[source,terminal] +---- +$ helm upgrade -n stackrox \ + stackrox-central-services rhacs/secured-cluster-services \ + --reuse-values \ + -f <path_to_values_public.yaml> \ + -f <path_to_generated-values.yaml> \// <1> + --set scannerV4.disable=false +---- +<1> When updating the system and installing a new component, you must provide the internal CA. See "Retrieving the automatically generated certificate authority". diff --git a/modules/enabling-scanner-v4-after-operator-installation-central.adoc b/modules/enabling-scanner-v4-after-operator-installation-central.adoc new file mode 100644 index 000000000000..c606892b1e11 --- /dev/null +++ b/modules/enabling-scanner-v4-after-operator-installation-central.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-scanner-v4-after-operator-installation-central_{context}"] += Enabling RHACS Scanner V4 for Central after Operator installation + +[role="_abstract"] +If Scanner V4 was not enabled during installation, you can enable it after installation. + +.Procedure + +. In the cluster where Central is installed, in the console, click *Operators* -> *Installed Operators* and select the {product-title-short} Operator. +. Click *Central* in the menu bar. +. Click the name of the cluster where Central was installed. The default value is *stackrox-central-services*. +. Click the *YAML* tab. +. Edit the YAML file as shown in the following example: ++ +[source,yaml] +---- + scannerV4: + scannerComponent: Enabled +---- diff --git a/modules/enabling-scanner-v4-after-operator-installation-secured-cluster.adoc b/modules/enabling-scanner-v4-after-operator-installation-secured-cluster.adoc new file mode 100644 index 000000000000..188a92a1e4f1 --- /dev/null +++ b/modules/enabling-scanner-v4-after-operator-installation-secured-cluster.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-scanner-v4-after-operator-installation-secured-cluster_{context}"] += Enabling RHACS Scanner V4 on the secured cluster after Operator installation + +[role="_abstract"] +You can enable Scanner V4 after installation. + +.Prerequisite + +* You set up Central and the secured cluster by using an init bundle or CRS so that they can communicate with each other. + +.Procedure + +. In the secured cluster, click *Operators* -> *Installed Operators* and select the {product-title-short} Operator. +. Click *Secured Cluster* in the menu bar. +. Click the default cluster name, *stackrox-secured-cluster-services*, or the name that you entered during installation. +. Click the *YAML* tab. +. Edit the YAML file as shown in the following example: ++ +[source,yaml] +---- + scannerV4: + scannerComponent: AutoSense +---- \ No newline at end of file diff --git a/modules/enabling-scanner-v4-helm-central.adoc b/modules/enabling-scanner-v4-helm-central.adoc new file mode 100644 index 000000000000..db308bbdb90c --- /dev/null +++ b/modules/enabling-scanner-v4-helm-central.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-scanner-v4-helm-central_{context}"] += Enabling RHACS Scanner V4 for Central when installing with Helm + +[role="_abstract"] +Scanner V4 is not enabled by default, but you can enable it during installation. Use this procedure to understand the steps you must follow when enabling Scanner V4. However, you might need to refer to the detailed installation documentation in "Additional resources", depending on the configuration of your other components. + +.Procedure + +. On the cluster where Central is installed, run the following command, using the instructions in "Install Central using Helm charts with customizations" if you need more information: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-central-services rhacs/central-services \ + --set scannerV4.disable=false \ + -f <path_to_values_public.yaml> -f <path_to_values_private.yaml> +---- ++ +.Example output +[source,terminal] +---- +Central Services Configuration Summary: + + Stackrox Version: 4.7.1 + Kubernetes Version: v1.31.6 + Kubernetes Namespace: stackrox + Helm Release Name: stackrox-central-services + OpenShift Cluster: 4 + Scanner V4: enabled + Scanner V4 DB Volume: PVC (scanner-v4-db) +---- ++ +. Configure your init bundle or cluster registration secret (CRS) so that Central and the secured cluster can communicate. For more information, see "Generating and applying an init bundle or cluster registration secret for RHACS on Red Hat OpenShift" or "Generating and applying an init bundle or cluster registration secret for RHACS on other platforms". \ No newline at end of file diff --git a/modules/enabling-scanner-v4-helm-secured-cluster.adoc b/modules/enabling-scanner-v4-helm-secured-cluster.adoc new file mode 100644 index 000000000000..28a2d8ed7949 --- /dev/null +++ b/modules/enabling-scanner-v4-helm-secured-cluster.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-scanner-v4-helm-secured-cluster_{context}"] += Enabling RHACS Scanner V4 on the secured cluster when installing with Helm + +[role="_abstract"] +Scanner V4 is not enabled by default, but you can enable it during installation. Use this procedure to understand the steps you must follow when enabling Scanner V4. However, you might need to refer to the detailed installation documentation in "Additional resources", depending on the configuration of your other components. + +.Prerequisite + +* You set up Central and the secured cluster by using an init bundle or CRS so that they can communicate with each other. + +.Procedure + +. On the secured cluster, run the following command, using the instructions in "Configuring the secured-cluster-services Helm chart with customizations" if you need more information: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-secured-cluster-services rhacs/secured-cluster-services \ + --set-file crs.file=<crs_file_name.yaml> \ + -f <path_to_pull_secret.yaml> \ + -f <path_to_values_public.yaml> -f <path_to_values_private.yaml> \ + --set clusterName=<name_of_the_secured_cluster> \ + --set centralEndpoint=<endpoint_of_central_service> \ + --set scanner.disable=false \ + --set scannerV4.disable=false +---- \ No newline at end of file diff --git a/modules/enabling-scanner-v4-operator-central.adoc b/modules/enabling-scanner-v4-operator-central.adoc new file mode 100644 index 000000000000..7007601b45f4 --- /dev/null +++ b/modules/enabling-scanner-v4-operator-central.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-scanner-v4-operator-central_{context}"] += Enabling RHACS Scanner V4 for Central when installing with the Operator + +[role="_abstract"] +Scanner V4 is not enabled by default, but you can enable it during installation. Use this procedure to understand the steps you must follow when enabling Scanner V4. However, you might need to refer to the detailed installation documentation in "Additional resources", depending on the configuration of your other components. + +.Procedure + +. On the cluster where Central is installed, follow the installation procedures as described in "Installing Central using the Operator method". Choose one of these methods to enable Scanner V4: +* As described in that procedure, when configuring the available options for Central, go to the *Scanner V4 Component Settings* section and in the *Scanner V4 Component* menu, select *Enabled*. +* In the Central custom resource (CR) YAML, configure the following parameter: ++ +[source,yaml] +---- + scannerV4: + scannerComponent: Enabled +---- +. Configure your init bundle or cluster registration secret (CRS) to allow communication between Central and the secured cluster. For more information, see "Generating and applying an init bundle or cluster registration secret for RHACS on Red Hat OpenShift". \ No newline at end of file diff --git a/modules/enabling-scanner-v4-operator-secured-cluster.adoc b/modules/enabling-scanner-v4-operator-secured-cluster.adoc new file mode 100644 index 000000000000..98bb80de3982 --- /dev/null +++ b/modules/enabling-scanner-v4-operator-secured-cluster.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: PROCEDURE +[id="enabling-scanner-v4-operator-secured-cluster_{context}"] += Enabling RHACS Scanner V4 on the secured cluster when installing with the Operator + +[role="_abstract"] +Scanner V4 is not enabled by default, but you can enable it during installation. Use this procedure to understand the steps you must follow when enabling Scanner V4. However, you might need to refer to the detailed installation documentation in "Additional resources", depending on the configuration of your other components. + +.Prerequisite + +* You set up Central and the secured cluster by using an init bundle or CRS so that they can communicate with each other. + +.Procedure + +. On the secured cluster, follow the installation procedures as described in "Installing {product-title-short} on secured clusters by using the Operator". Choose one of these methods to enable Scanner V4: +* In the *Scanner V4 Component Settings* section, in the *Scanner V4 Component* menu, select *AutoSense*. +* In the SecuredCluster CR YAML, configure the following parameter: ++ +[source,yaml] +---- + scannerV4: + scannerComponent: AutoSense +---- \ No newline at end of file diff --git a/modules/enforcement-existing-deployments.adoc b/modules/enforcement-existing-deployments.adoc new file mode 100644 index 000000000000..ef166ba7b4f0 --- /dev/null +++ b/modules/enforcement-existing-deployments.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +// * operating/manage_security_policies/about-security-policies.adoc +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: CONCEPT +[id="enforcement-existing-deployments_{context}"] += Enforcement on existing deployments + +For existing deployments, policy changes only result in enforcement at the next detection of the criteria, when a Kubernetes event occurs. If you make changes to a policy, you must reassess policies by selecting *Policy Management* and clicking *Reassess All*. This action applies deploy policies on all existing deployments regardless of whether there are any new incoming Kubernetes events. If a policy is violated, then {product-title-short} performs enforcement. \ No newline at end of file diff --git a/modules/enhancing-image-scanning-by-accessing-delegated-image-scanning.adoc b/modules/enhancing-image-scanning-by-accessing-delegated-image-scanning.adoc new file mode 100644 index 000000000000..4d62b2fa7570 --- /dev/null +++ b/modules/enhancing-image-scanning-by-accessing-delegated-image-scanning.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: CONCEPT +[id="enhancing-image-scanning-by-accessing-delegated-image-scanning_{context}"] += Enhancing image scanning by accessing delegated image scanning + +Currently, by default, Central Services Scanner performs both indexing (identification of components) and vulnerability matching (enrichment of components with vulnerability data) for images observed in your secured clusters, with the exception of images from the {ocp} integrated registry. + +For images from the {ocp} integrated registry, Scanner-slim installed in your secured cluster performs the indexing, and the Central Services Scanner performs the vulnerability matching. + +The delegated image scanning feature extends scanning functionality by allowing Scanner-slim to index images from any registry and then send them to Central for vulnerability matching. To use this feature, ensure that Scanner-slim is installed in your secured clusters. If Scanner-slim is not present, scan requests are sent directly to Central. \ No newline at end of file diff --git a/modules/enter-policy-details.adoc b/modules/enter-policy-details.adoc new file mode 100644 index 000000000000..d512b95a3235 --- /dev/null +++ b/modules/enter-policy-details.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="enter-policy-details_{context}"] += Entering policy details + +[role="_abstract"] +Enter details about your policy, such as the name, severity, description, and guidance to resolve violations of the policy. + +.Procedure + +. Enter a *Name* for the policy. +. Select a *Severity* level for this policy. +. Select a policy category for the policy. This is a required field. +. Enter details about the policy in the *Description* field. +. Enter an explanation about why the policy exists in the *Rationale* field. +. Enter steps to resolve violations of this policy in the *Guidance* field. +. Under the *MITRE ATT&CK* section, select the link:https://attack.mitre.org/matrices/enterprise/containers/[tactics and the techniques] you want to specify for the policy. +.. Click *Add tactic*, and then select a tactic from the drop-down list. +.. Click the *Add technique* to add techniques for the selected tactic. You can specify multiple techniques for a tactic. +. Click *Next*. \ No newline at end of file diff --git a/modules/ephemeral-storage-csi-inline-overview.adoc b/modules/ephemeral-storage-csi-inline-overview.adoc deleted file mode 100644 index 2e5b6f4b2b09..000000000000 --- a/modules/ephemeral-storage-csi-inline-overview.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/ephemeral-storage-csi-inline.adoc - -[id="ephemeral-storage-csi-inline-overview_{context}"] -= Overview of CSI inline ephemeral volumes - -Traditionally, volumes that are backed by Container Storage Interface (CSI) drivers can only be used with a `PersistentVolume` and `PersistentVolumeClaim` object combination. - -This feature allows you to specify CSI volumes directly in the `Pod` specification, rather than in a `PersistentVolume` object. Inline volumes are ephemeral and do not persist across pod restarts. - -== Support limitations - -By default, {product-title} supports CSI inline ephemeral volumes with these limitations: - -* Support is only available for CSI drivers. In-tree and FlexVolumes are not supported. -* {product-title} does not include any CSI drivers. Use the CSI drivers provided by -link:https://kubernetes-csi.github.io/docs/drivers.html[community or storage vendors]. Follow the installation instructions provided by the CSI driver. -* CSI drivers might not have implemented the inline volume functionality, including `Ephemeral` capacity. For details, see the CSI driver documentation. diff --git a/modules/ephemeral-storage-csi-inline-pod.adoc b/modules/ephemeral-storage-csi-inline-pod.adoc deleted file mode 100644 index 790f3a70abfd..000000000000 --- a/modules/ephemeral-storage-csi-inline-pod.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/ephemeral-storage-csi-inline-pod-scheduling.adoc - -[id="ephemeral-storage-csi-inline-pod_{context}"] -= Embedding a CSI inline ephemeral volume in the `Pod` specification - -You can embed a CSI inline ephemeral volume in the `Pod` specification in {product-title}. At runtime, nested inline volumes follow the ephemeral lifecycle of their associated pods so that the CSI driver handles all phases of volume operations as pods are created and destroyed. - -.Procedure - -. Create the `Pod` object definition and save it to a file. - -. Embed the CSI inline ephemeral volume in the file. -+ -.my-csi-app.yaml -[source,yaml] ----- -kind: Pod -apiVersion: v1 -metadata: - name: my-csi-app -spec: - containers: - - name: my-frontend - image: busybox - volumeMounts: - - mountPath: "/data" - name: my-csi-inline-vol - command: [ "sleep", "1000000" ] - volumes: <1> - - name: my-csi-inline-vol - csi: - driver: inline.storage.kubernetes.io - volumeAttributes: - foo: bar ----- -<1> The name of the volume that is used by pods. - -. Create the object definition file that you saved in the previous step. -+ -[source,terminal] ----- -$ oc create -f my-csi-app.yaml ----- diff --git a/modules/etcd-defrag.adoc b/modules/etcd-defrag.adoc deleted file mode 100644 index e41334def945..000000000000 --- a/modules/etcd-defrag.adoc +++ /dev/null @@ -1,143 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/cluster-tasks.adoc -// * scalability_and_performance/recommended-host-practices.adoc - -[id="etcd-defrag_{context}"] -= Defragmenting etcd data - -Manual defragmentation must be performed periodically to reclaim disk space after etcd history compaction and other events cause disk fragmentation. - -History compaction is performed automatically every five minutes and leaves gaps in the back-end database. This fragmented space is available for use by etcd, but is not available to the host file system. You must defragment etcd to make this space available to the host file system. - -Because etcd writes data to disk, its performance strongly depends on disk performance. Consider defragmenting etcd every month, twice a month, or as needed for your cluster. You can also monitor the `etcd_db_total_size_in_bytes` metric to determine whether defragmentation is necessary. - -[WARNING] -==== -Defragmenting etcd is a blocking action. The etcd member will not response until defragmentation is complete. For this reason, wait at least one minute between defragmentation actions on each of the pods to allow the cluster to recover. -==== - -Follow this procedure to defragment etcd data on each etcd member. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Determine which etcd member is the leader, because the leader should be defragmented last. - -.. Get the list of etcd pods: -+ -[source,terminal] ----- -$ oc get pods -n openshift-etcd -o wide | grep -v quorum-guard | grep etcd ----- -+ -.Example output -[source,terminal] ----- -etcd-ip-10-0-159-225.example.redhat.com 3/3 Running 0 175m 10.0.159.225 ip-10-0-159-225.example.redhat.com <none> <none> -etcd-ip-10-0-191-37.example.redhat.com 3/3 Running 0 173m 10.0.191.37 ip-10-0-191-37.example.redhat.com <none> <none> -etcd-ip-10-0-199-170.example.redhat.com 3/3 Running 0 176m 10.0.199.170 ip-10-0-199-170.example.redhat.com <none> <none> ----- - -.. Choose a pod and run the following command to determine which etcd member is the leader: -+ -[source,terminal] ----- -$ oc rsh -n openshift-etcd etcd-ip-10-0-159-225.us-west-1.compute.internal etcdctl endpoint status --cluster -w table ----- -+ -.Example output -[source,terminal] ----- -Defaulting container name to etcdctl. -Use 'oc describe pod/etcd-ip-10-0-159-225.example.redhat.com -n openshift-etcd' to see all of the containers in this pod. -+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+ -| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS | -+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+ -| https://10.0.191.37:2379 | 251cd44483d811c3 | 3.4.9 | 104 MB | false | false | 7 | 91624 | 91624 | | -| https://10.0.159.225:2379 | 264c7c58ecbdabee | 3.4.9 | 104 MB | false | false | 7 | 91624 | 91624 | | -| https://10.0.199.170:2379 | 9ac311f93915cc79 | 3.4.9 | 104 MB | true | false | 7 | 91624 | 91624 | | -+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+ ----- -+ -Based on the `IS LEADER` column of this output, the [x-]`https://10.0.199.170:2379` endpoint is the leader. Matching this endpoint with the output of the previous step, the pod name of the leader is `etcd-ip-10-0-199-170.example.redhat.com`. - -. Defragment an etcd member. - -.. Connect to the running etcd container, passing in the name of a pod that is _not_ the leader: -+ -[source,terminal] ----- -$ oc rsh -n openshift-etcd etcd-ip-10-0-159-225.example.redhat.com ----- - -.. Unset the `ETCDCTL_ENDPOINTS` environment variable: -+ -[source,terminal] ----- -sh-4.4# unset ETCDCTL_ENDPOINTS ----- - -.. Defragment the etcd member: -+ -[source,terminal] ----- -sh-4.4# etcdctl --command-timeout=30s --endpoints=https://localhost:2379 defrag ----- -+ -.Example output -[source,terminal] ----- -Finished defragmenting etcd member[https://localhost:2379] ----- -+ -If a timeout error occurs, increase the value for `--command-timeout` until the command succeeds. - -.. Verify that the database size was reduced: -+ -[source,terminal] ----- -sh-4.4# etcdctl endpoint status -w table --cluster ----- -+ -.Example output -[source,terminal] ----- -+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+ -| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | IS LEARNER | RAFT TERM | RAFT INDEX | RAFT APPLIED INDEX | ERRORS | -+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+ -| https://10.0.191.37:2379 | 251cd44483d811c3 | 3.4.9 | 104 MB | false | false | 7 | 91624 | 91624 | | -| https://10.0.159.225:2379 | 264c7c58ecbdabee | 3.4.9 | 41 MB | false | false | 7 | 91624 | 91624 | | <1> -| https://10.0.199.170:2379 | 9ac311f93915cc79 | 3.4.9 | 104 MB | true | false | 7 | 91624 | 91624 | | -+---------------------------+------------------+---------+---------+-----------+------------+-----------+------------+--------------------+--------+ ----- -This example shows that the database size for this etcd member is now 41 MB as opposed to the starting size of 104 MB. - -.. Repeat these steps to connect to each of the other etcd members and defragment them. Always defragment the leader last. -+ -Wait at least one minute between defragmentation actions to allow the etcd pod to recover. Until the etcd pod recovers, the etcd member will not respond. - -. If any `NOSPACE` alarms were triggered due to the space quota being exceeded, clear them. - -.. Check if there are any `NOSPACE` alarms: -+ -[source,terminal] ----- -sh-4.4# etcdctl alarm list ----- -+ -.Example output -[source,terminal] ----- -memberID:12345678912345678912 alarm:NOSPACE ----- - -.. Clear the alarms: -+ -[source,terminal] ----- -sh-4.4# etcdctl alarm disarm ----- diff --git a/modules/etcd-operator.adoc b/modules/etcd-operator.adoc deleted file mode 100644 index 7c8600c604ee..000000000000 --- a/modules/etcd-operator.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="etcd-cluster-operator_{context}"] -= etcd cluster Operator - -[discrete] -== Purpose - -The etcd cluster Operator automates etcd cluster scaling, enables etcd monitoring and metrics, and simplifies disaster recovery procedures. -[discrete] -== Project - -link:https://github.com/openshift/cluster-etcd-operator/[cluster-etcd-operator] - -[discrete] -== CRDs - -* `etcds.operator.openshift.io` -** Scope: Cluster -** CR: `etcd` -** Validation: Yes - -[discrete] -== Configuration objects - -[source,terminal] ----- -$ oc edit etcd cluster ----- diff --git a/modules/evidence-reports.adoc b/modules/evidence-reports.adoc new file mode 100644 index 000000000000..a3730d1dcdd3 --- /dev/null +++ b/modules/evidence-reports.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: REFERENCE +[id="evidence-reports_{context}"] += Evidence reports + +You can export comprehensive compliance-related data from {rh-rhacs-first} in CSV format as an evidence report. This evidence report contains detailed information about the compliance assessment, and is tailored for technical roles, such as compliance auditors, DevOps engineers, or security practitioners. + +An evidence report contains the following information: + +[cols="2,2",options="header"] +|=== +|CSV field |Description + +|Standard +|The compliance standard, for example, CIS Kubernetes. + +|Cluster +|The name of the assessed cluster. + +|Namespace +|The name of the namespace or project where the deployment exists. + +|Object Type +|The Kubernetes entity type of the object. +For example, `node`, `cluster`, `DaemonSet`, `Deployment`, or `StaticPod`. + +|Object Name +|The name of the object, which is a Kubernetes systems-generated string that uniquely identify objects. +For example, `gke-setup-dev21380-default-pool-8e086a77-1jfq`. + +|Control +|The control number as it appears in the compliance standard. + +|Control Description +|Description about the compliance check that the control carries out. + +|State +|Whether the compliance check passed or failed. + +|Evidence +|The explanation about why a specific compliance check failed or passed. + +|Assessment Time +|The time and date when you ran the compliance scan. +|=== \ No newline at end of file diff --git a/modules/example-apache-httpd-configuration.adoc b/modules/example-apache-httpd-configuration.adoc deleted file mode 100644 index 1eef9c54072c..000000000000 --- a/modules/example-apache-httpd-configuration.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-ldap-identity-provider.adoc - -[id="example-apache-httpd-configuration_{context}"] -= Example Apache HTTPD configuration for basic identity providers - -The basic identify provider (IDP) configuration in {product-title} 4 requires -that the IDP server respond with JSON for success and failures. You can use CGI -scripting in Apache HTTPD to accomplish this. This section provides examples. - -.Example `/etc/httpd/conf.d/login.conf` ----- -<VirtualHost *:443> - # CGI Scripts in here - DocumentRoot /var/www/cgi-bin - - # SSL Directives - SSLEngine on - SSLCipherSuite PROFILE=SYSTEM - SSLProxyCipherSuite PROFILE=SYSTEM - SSLCertificateFile /etc/pki/tls/certs/localhost.crt - SSLCertificateKeyFile /etc/pki/tls/private/localhost.key - - # Configure HTTPD to execute scripts - ScriptAlias /basic /var/www/cgi-bin - - # Handles a failed login attempt - ErrorDocument 401 /basic/fail.cgi - - # Handles authentication - <Location /basic/login.cgi> - AuthType Basic - AuthName "Please Log In" - AuthBasicProvider file - AuthUserFile /etc/httpd/conf/passwords - Require valid-user - </Location> -</VirtualHost> ----- - -.Example `/var/www/cgi-bin/login.cgi` ----- -#!/bin/bash -echo "Content-Type: application/json" -echo "" -echo '{"sub":"userid", "name":"'$REMOTE_USER'"}' -exit 0 ----- - -.Example `/var/www/cgi-bin/fail.cgi` ----- -#!/bin/bash -echo "Content-Type: application/json" -echo "" -echo '{"error": "Login failure"}' -exit 0 ----- - -== File requirements - -These are the requirements for the files you create on an Apache HTTPD web -server: - -* `login.cgi` and `fail.cgi` must be executable (`chmod +x`). -* `login.cgi` and `fail.cgi` must have proper SELinux contexts if SELinux is -enabled: `restorecon -RFv /var/www/cgi-bin`, or ensure that the context is -`httpd_sys_script_exec_t` using `ls -laZ`. -* `login.cgi` is only executed if your user successfully logs in per `Require -and Auth` directives. -* `fail.cgi` is executed if the user fails to log in, resulting in an `HTTP 401` -response. diff --git a/modules/exchanging-identity-token.adoc b/modules/exchanging-identity-token.adoc new file mode 100644 index 000000000000..dcb7beb4e41e --- /dev/null +++ b/modules/exchanging-identity-token.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-short-lived-access.adoc +:_mod-docs-content-type: PROCEDURE +[id="exchanging-identity-token_{context}"] += Exchanging an identity token + +[role="_abstract"] + +.Prerequisites +* You have a valid OpenID Connect (OIDC) token. +* You added a *Machine access configuration* for the {product-title-short} instance you want to access. + +.Procedure +. Prepare the POST request's JSON data: ++ +[source,json] +---- +{ + "idToken": "<id_token>" +} +---- + +. Send a POST request to the API */v1/auth/m2m/exchange*. +. Wait for the API response: ++ +[source,json] +---- +{ + "accessToken": "<access_token>" +} +---- +. Use the returned access token to access the {product-title-short} instance. + +[NOTE] +==== +If you are using *GitHub Actions*, you can use the link:https://github.com/marketplace/actions/central-login[stackrox/central-login GitHub Action]. +==== \ No newline at end of file diff --git a/modules/export-security-policy.adoc b/modules/export-security-policy.adoc new file mode 100644 index 000000000000..03d30fa4f58c --- /dev/null +++ b/modules/export-security-policy.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="export-security-policy_{context}"] += Exporting a security policy + +[role="_abstract"] +When you export a policy, it includes all the policy contents and also includes cluster scopes, cluster exclusions, and all configured notifications. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. From the *Policies* page, select the policy you want to edit. +. Select *Actions* -> *Export policy to JSON*. diff --git a/modules/expose-portal-http-during-installation.adoc b/modules/expose-portal-http-during-installation.adoc new file mode 100644 index 000000000000..07070f0c0308 --- /dev/null +++ b/modules/expose-portal-http-during-installation.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * dir/filename.adoc +:_mod-docs-content-type: PROCEDURE +[id="expose-portal-http-during-installation_{context}"] += Exposing the RHACS portal over HTTP during the installation + +[role="_abstract"] +If you are installing {product-title} using the `roxctl` CLI, use the `--plaintext-endpoints` option with the `roxctl central generate interactive` command to enable the HTTP server during the installation. + +.Procedure + +* Run the following command to specify an HTTP endpoint during the interactive installation process: ++ +[source,terminal] +---- +$ roxctl central generate interactive \ + --plaintext-endpoints=<endpoints_spec> <1> +---- +<1> Endpoint specifications in the form of `<type>@<addr>:<port>`. See the Prerequisites section for details. +//TODO: Add link to Prerequisites section diff --git a/modules/expose-portal-http-existing-deployment.adoc b/modules/expose-portal-http-existing-deployment.adoc new file mode 100644 index 000000000000..645ac965e745 --- /dev/null +++ b/modules/expose-portal-http-existing-deployment.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * dir/filename.adoc +:_mod-docs-content-type: PROCEDURE +[id="expose-portal-http-existing-deployment_{context}"] += Exposing the RHACS portal over HTTP for an existing deployment + +[role="_abstract"] +You can enable the HTTP server on an existing {product-title} deployment. + +.Procedure + +. Create a patch and define a `ROX_PLAINTEXT_ENDPOINTS` environment variable: ++ +[source,terminal] +---- +$ CENTRAL_PLAINTEXT_PATCH=' +spec: + template: + spec: + containers: + - name: central + env: + - name: ROX_PLAINTEXT_ENDPOINTS + value: <endpoints_spec> <1> +' +---- +<1> Endpoint specifications in the form of `<type>@<addr>:<port>`. See the Prerequisites section for details. +//TODO: Add link to Prerequisites section +. Add the `ROX_PLAINTEXT_ENDPOINTS` environment variable to the Central deployment: ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy/central -p "$CENTRAL_PLAINTEXT_PATCH" +---- diff --git a/modules/failing-to-load-the-ebpf-probe.adoc b/modules/failing-to-load-the-ebpf-probe.adoc new file mode 100644 index 000000000000..0c7e08a8b3fb --- /dev/null +++ b/modules/failing-to-load-the-ebpf-probe.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * troubleshooting/commonly-occurring-error-conditions.adoc + +:_mod-docs-content-type: CONCEPT +[id="failing-to-load-the-ebpf-probe_{context}"] += Failing to load the eBPF probe + +Before Collector starts, it loads the eBPF probe; however, in rare cases, you might encounter issues where Collector cannot load the eBPF probe, which results in various error messages or exceptions. In such cases, you must check the logs to identify the problems with failure in loading the eBPF probe. + +Consider the following Collector log: + +[source,terminal] +---- +[...] +[INFO 2025/07/24 10:26:37] Trying to open the right engine! +[INFO 2025/07/24 10:26:41] libbpf: prog 'execve_x': -- BEGIN PROG LOAD LOG -- +[...] +-- END PROG LOAD LOG -- +[INFO 2025/07/24 10:26:41] libbpf: prog 'execve_x': failed to load: -7 +[INFO 2025/07/24 10:26:41] libbpf: failed to load object 'bpf_probe' +[INFO 2025/07/24 10:26:41] libbpf: failed to load BPF skeleton 'bpf_probe': -7 +[INFO 2025/07/24 10:26:41] libpman: failed to load BPF object (errno: 7 | message: Argument list too long) +---- + +If you encounter this kind of error, you must report it to {product-title} ({product-title-short}) support team or create an issue in the `stackrox/collector` GitHub repository. diff --git a/modules/feature-gate-features.adoc b/modules/feature-gate-features.adoc deleted file mode 100644 index 55a72730f25f..000000000000 --- a/modules/feature-gate-features.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-enabling-features.adoc - -[id="feature-gate-features_{context}"] -= Features that are affected by FeatureGates - -The following Technology Preview features included in {product-title}: - -[options="header"] -|=== -| FeatureGate| Description| Default - -|`RotateKubeletServerCertificate` -|Enables the rotation of the server TLS certificate on the cluster. -|True - -|`SupportPodPidsLimit` -|Enables support for limiting the number of processes (PIDs) running in a pod. -|True - -|`MachineHealthCheck` -|Enables automatically repairing unhealthy machines in a machine pool. -|True - -|`LocalStorageCapacityIsolation` -|Enable the consumption of local ephemeral storage and also the `sizeLimit` property of an `emptyDir` volume. -|False - -|=== - -You can enable these features by editing the Feature Gate Custom Resource. -Turning on these features cannot be undone and prevents the ability to upgrade your cluster. diff --git a/modules/fetching-vulnerability-definitions.adoc b/modules/fetching-vulnerability-definitions.adoc new file mode 100644 index 000000000000..5c056bdedc84 --- /dev/null +++ b/modules/fetching-vulnerability-definitions.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: CONCEPT +[id="fetching-vulnerability-definitions_{context}"] += Fetching vulnerability definitions + +In online mode, Central fetches the vulnerability definitions every 5 minutes from a single feed. +This feed combines vulnerability definitions from upstream sources, and it refreshes every 3 hours. The address of the feed is `\https://definitions.stackrox.io`. + +You can change the frequency of the default query from Central to the `definitions.stackrox.io` feed by setting the `ROX_SCANNER_VULN_UPDATE_INTERVAL` environment variable. Run the following command: + +[source,terminal] +---- +$ oc -n stackrox set env deploy/central ROX_SCANNER_VULN_UPDATE_INTERVAL=<value> <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +This variable applies to the connection between Central and the `definitions.stackrox.io` feed. Both the StackRox Scanner and Scanner V4 use vulnerability data from Central that is obtained from this feed. The StackRox Scanner's config map still has an `updater.interval` parameter for configuring the scanner's updating frequency, but it no longer includes the `fetchFromCentral` parameter. + +For more information about the vulnerability sources that {product-title-short} uses, see "Vulnerability sources" in "{product-title} architecture". + +//Future work when time permits: +// Take instructions for changing the frequency of fetching definitions and put them into a procedure module. Call that module from the operating/examine-images-for-vulnerabilities.adoc module. \ No newline at end of file diff --git a/modules/file-integrity-CR-phases.adoc b/modules/file-integrity-CR-phases.adoc deleted file mode 100644 index 57602d4272f5..000000000000 --- a/modules/file-integrity-CR-phases.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-understanding.adoc - -[id="file-integrity-CR-phases_{context}"] -= `FileIntegrity` custom resource phases - -* `Pending` - The phase after the custom resource (CR) is created. -* `Active` - The phase when the backing daemon set is up and running. -* `Initializing` - The phase when the AIDE database is being reinitialized. diff --git a/modules/file-integrity-examine-default-config.adoc b/modules/file-integrity-examine-default-config.adoc deleted file mode 100644 index feb1510b6c1c..000000000000 --- a/modules/file-integrity-examine-default-config.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-configuring.adoc - -[id="file-integrity-examine-default-config_{context}"] -= Examine the default configuration - -The default File Integrity Operator configuration is stored in a config map with -the same name as the `FileIntegrity` CR. - -.Procedure - -* To examine the default config, run: -+ -[source,terminal] ----- -$ oc describe cm/worker-fileintegrity ----- diff --git a/modules/file-integrity-important-attributes.adoc b/modules/file-integrity-important-attributes.adoc deleted file mode 100644 index da0428c6b243..000000000000 --- a/modules/file-integrity-important-attributes.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-configuring.adoc - -[id="important-file-integrity-object-attributes_{context}"] -= Important attributes - -.Important `spec` and `spec.config` attributes - -[%header,cols=2*] -|=== -|Attribute -|Description - -|`spec.nodeSelector` -|A map of key-values pairs that must match with node’s labels in order for the -AIDE pods to be schedulable on that node. The typical use is to set only a -single key-value pair where `node-role.kubernetes.io/worker: ""` schedules AIDE on -all worker nodes, `node.openshift.io/os_id: "rhcos"` schedules on all -{op-system-first} nodes. - -|`spec.debug` -|A boolean attribute. If set to `true`, the daemon running in the AIDE deamon set’s -pods would output extra information. - -|`spec.tolerations` -|Specify tolerations to schedule on nodes with custom taints. When not specified, -a default toleration is applied, which allows tolerations to run on master nodes. - -|`spec.config.gracePeriod` -|The number of seconds to pause in between AIDE integrity checks. Frequent AIDE -checks on a node can be resource intensive, so it can be useful to specify a -longer interval. Defaults to `900`, or 15 minutes. - -|`spec.config.name`, `spec.config.namespace`, `spec.config.key` -|These three attributes allow you to set a custom AIDE configuration. When the name -or namespace are unset, the File Integrity Operator generates a configuration -suitable for {op-system} systems. The name and namespace attributes point to the -config map; the key points to a key inside that config map. Use the key -attribute to specify a custom key that contains the actual config and defaults -to `aide.conf`. -|=== diff --git a/modules/file-integrity-node-status-failure.adoc b/modules/file-integrity-node-status-failure.adoc deleted file mode 100644 index a5ece7ae5a19..000000000000 --- a/modules/file-integrity-node-status-failure.adoc +++ /dev/null @@ -1,114 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-understanding.adoc - -[id="file-integrity-node-status-failure_{context}"] -= `FileIntegrityNodeStatus` failure status example - -To simulate a failure condition, modify one of the files AIDE tracks. For -example, modify `/etc/resolv.conf` on one of the worker nodes: - -[source,terminal] ----- -$ oc debug node/ip-10-0-130-192.ec2.internal ----- - -.Example output -[source,terminal] ----- -Creating debug namespace/openshift-debug-node-ldfbj ... -Starting pod/ip-10-0-130-192ec2internal-debug ... -To use host binaries, run `chroot /host` -Pod IP: 10.0.130.192 -If you don't see a command prompt, try pressing enter. -sh-4.2# echo "# integrity test" >> /host/etc/resolv.conf -sh-4.2# exit - -Removing debug pod ... -Removing debug namespace/openshift-debug-node-ldfbj ... ----- - -After some time, the `Failed` condition was reported in the results array of the -corresponding `FileIntegrityNodeStatus`. The previous `Succeeded` condition is -retained, which allows you to pinpoint the time the check failed. - -[source,terminal] ----- -$ oc get fileintegritynodestatuses.fileintegrity.openshift.io/worker-fileintegrity-ip-10-0-130-192.ec2.internal -ojsonpath='{.results}' | jq -r ----- - -Alternatively, if you are not mentioning the object name, run: - -[source,terminal] ----- -$ oc get fileintegritynodestatuses.fileintegrity.openshift.io -ojsonpath='{.items[*].results}' | jq ----- - -.Example output -[source,terminal] ----- -[ - { - "condition": "Succeeded", - "lastProbeTime": "2020-09-15T12:54:14Z" - }, - { - "condition": "Failed", - "filesChanged": 1, - "lastProbeTime": "2020-09-15T12:57:20Z", - "resultConfigMapName": "aide-ds-worker-fileintegrity-ip-10-0-130-192.ec2.internal-failed", - "resultConfigMapNamespace": "openshift-file-integrity" - } -] ----- - -The `Failed` condition points to a config map that gives more details about what -exactly failed and why: - -[source,terminal] ----- -$ oc describe cm aide-ds-worker-fileintegrity-ip-10-0-130-192.ec2.internal-failed ----- - -.Example output -[source,terminal] ----- -Name: aide-ds-worker-fileintegrity-ip-10-0-130-192.ec2.internal-failed -Namespace: openshift-file-integrity -Labels: file-integrity.openshift.io/node=ip-10-0-130-192.ec2.internal - file-integrity.openshift.io/owner=worker-fileintegrity - file-integrity.openshift.io/result-log= -Annotations: file-integrity.openshift.io/files-added: 0 - file-integrity.openshift.io/files-changed: 1 - file-integrity.openshift.io/files-removed: 0 - -Data - -integritylog: ------- -AIDE 0.15.1 found differences between database and filesystem!! -Start timestamp: 2020-09-15 12:58:15 - -Summary: - Total number of files: 31553 - Added files: 0 - Removed files: 0 - Changed files: 1 - - ---------------------------------------------------- -Changed files: ---------------------------------------------------- - -changed: /hostroot/etc/resolv.conf - ---------------------------------------------------- -Detailed information about changes: ---------------------------------------------------- - - -File: /hostroot/etc/resolv.conf - SHA512 : sTQYpB/AL7FeoGtu/1g7opv6C+KT1CBJ , qAeM+a8yTgHPnIHMaRlS+so61EN8VOpg - -Events: <none> ----- diff --git a/modules/file-integrity-node-status-success.adoc b/modules/file-integrity-node-status-success.adoc deleted file mode 100644 index 1f807ba75296..000000000000 --- a/modules/file-integrity-node-status-success.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-understanding.adoc - -[id="file-integrity-node-status-success_{context}"] -= `FileIntegrityNodeStatus` success status example - -.Example output of a condition with a success status - -[source,terminal] ----- -[ - { - "condition": "Succeeded", - "lastProbeTime": "2020-09-15T12:45:57Z" - } -] -[ - { - "condition": "Succeeded", - "lastProbeTime": "2020-09-15T12:46:03Z" - } -] -[ - { - "condition": "Succeeded", - "lastProbeTime": "2020-09-15T12:45:48Z" - } -] ----- - -In this case, all three scans succeeded and so far there are no other -conditions. diff --git a/modules/file-integrity-node-status.adoc b/modules/file-integrity-node-status.adoc deleted file mode 100644 index fe72cf08a598..000000000000 --- a/modules/file-integrity-node-status.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-understanding.adoc - -[id="file-integrity-node-status-types_{context}"] -= `FileIntegrityNodeStatus` status types - -These conditions are reported in the results array of the -corresponding `FileIntegrityNodeStatus`: - -* `Succeeded` - The integrity check passed; the files and directories -covered by the AIDE check have not been modified since the database was last -initialized. - -* `Failed` - The integrity check failed; some files or directories -covered by the AIDE check have been modified since the database was last -initialized. - -* `Error` - The AIDE scanner encountered an internal error. diff --git a/modules/file-integrity-operator-changing-custom-config.adoc b/modules/file-integrity-operator-changing-custom-config.adoc deleted file mode 100644 index 0d6f6997026c..000000000000 --- a/modules/file-integrity-operator-changing-custom-config.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-configuring.adoc - -[id="file-integrity-operator-changing-custom-config_{context}"] -= Changing the custom File Integrity configuration - -To change the File Integrity configuration, never change the generated -config map. Instead, change the config map that is linked to the `FileIntegrity` -object through the `spec.name`, `namespace`, and `key` attributes. - -Currently, you must also annotate the `FileIntegrity` object to force -reconciliation of the object and its config map. For example: - -[source,terminal] ----- -$ oc annotate fileintegrities/worker-fileintegrity file-integrity.openshift.io/config-version=2 ----- - -The value of the annotation or whether it is an annotation does not really -matter; the purpose is of this operation is to force reconciliation of the -`FileIntegrity` object and re-render the processed config map with the generated -configuration. diff --git a/modules/file-integrity-operator-defining-custom-config.adoc b/modules/file-integrity-operator-defining-custom-config.adoc deleted file mode 100644 index 52d4c6a8f463..000000000000 --- a/modules/file-integrity-operator-defining-custom-config.adoc +++ /dev/null @@ -1,102 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-configuring.adoc - -[id="file-integrity-operator-defining-custom-config_{context}"] -= Defining a custom File Integrity Operator configuration - -This example focuses on defining a custom configuration for a scanner that runs -on the master nodes based on the default configuration provided for the -`worker-fileintegrity` CR. This workflow might be useful if you are planning -to deploy a custom software running as a daemon set and storing its data under -`/opt/mydaemon` on the master nodes. - -.Procedure - -. Make a copy of the default configuration. - -. Edit the default configuration with the files that must be watched or excluded. - -. Store the edited contents in a new config map. - -. Point the `FileIntegrity` object to the new config map through the attributes in -`spec.config`. - -. Extract the default configuration: -+ -[source,terminal] ----- -$ oc extract cm/worker-fileintegrity --keys=aide.conf ----- -+ -This creates a file named `aide.conf` that you can edit. To illustrate how the -Operator post-processes the paths, this example adds an exclude directory -without the prefix: -+ -[source,terminal] ----- -$ vim aide.conf ----- -+ -.Example output -[source,terminal] ----- -/hostroot/etc/kubernetes/static-pod-resources -!/hostroot/etc/kubernetes/aide.* -!/hostroot/etc/kubernetes/manifests -!/hostroot/etc/docker/certs.d -!/hostroot/etc/selinux/targeted -!/hostroot/etc/openvswitch/conf.db ----- -+ -Exclude a path specific to master nodes: -+ -[source,terminal] ----- -!/opt/mydaemon/ ----- -+ -Store the other content in `/etc`: -+ -[source,terminal] ----- -/hostroot/etc/ CONTENT_EX ----- - -. Create a config map based on this file: -+ -[source,terminal] ----- -$ oc create cm master-aide-conf --from-file=aide.conf ----- - -. Define a `FileIntegrity` CR manifest that references the config map: -+ -[source,yaml] ----- -apiVersion: fileintegrity.openshift.io/v1alpha1 -kind: FileIntegrity -metadata: - name: master-fileintegrity - namespace: openshift-file-integrity -spec: - nodeSelector: - node-role.kubernetes.io/master: "" - config: - name: master-aide-conf - namespace: openshift-file-integrity ----- -+ -The Operator processes the provided config map file and stores the result in a -config map with the same name as the `FileIntegrity` object: -+ -[source,terminal] ----- -$ oc describe cm/master-fileintegrity | grep /opt/mydaemon ----- -+ -.Example output -[source,terminal] ----- -!/hostroot/opt/mydaemon ----- diff --git a/modules/file-integrity-operator-exploring-daemon-sets.adoc b/modules/file-integrity-operator-exploring-daemon-sets.adoc deleted file mode 100644 index bb9033f98ea5..000000000000 --- a/modules/file-integrity-operator-exploring-daemon-sets.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-advanced-usage.adoc - -[id="file-integrity-operator-exploring-daemon-sets_{context}"] -= Exploring the daemon sets - -Each `FileIntegrity` object represents a scan on a number of nodes. The scan -itself is performed by pods managed by a daemon set. - -To find the daemon set that represents a `FileIntegrity` object, run: - -[source,terminal] ----- -$ oc get ds/aide-ds-$file-integrity-object-name ----- - -To list the pods in that daemon set, run: - -[source,terminal] ----- -$ oc get pods -lapp=$ds-name ----- - -To view logs of a single AIDE pod, call `oc logs` on one of the pods. - -.Example output -[source,terminal] ----- -debug: aide files locked by aideLoop -running aide check -aide check returned status 0 -debug: aide files unlocked by aideLoop -debug: Getting FileIntegrity openshift-file-integrity/worker-fileintegrity -Created OK configMap 'aide-ds-worker-fileintegrity-ip-10-0-128-73.eu-north-1.compute.internal' ----- - -The config maps created by the AIDE daemon are not retained and are deleted -after the File Integrity Operator processes them. However, on failure and error, -the contents of these config maps are copied to the config map that the -`FileIntegrityNodeStatus` object points to. diff --git a/modules/file-integrity-operator-machine-config-integration.adoc b/modules/file-integrity-operator-machine-config-integration.adoc deleted file mode 100644 index 8e29ade7ce97..000000000000 --- a/modules/file-integrity-operator-machine-config-integration.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-advanced-usage.adoc - -[id="file-integrity-operator-machine-config-integration_{context}"] -= Machine config integration - -In {product-title} 4, the cluster node configuration is delivered through -`MachineConfig` objects. You can assume that the changes to files that are -caused by a `MachineConfig` object are expected and should not cause the file -integrity scan to fail. To suppress changes to files caused by `MachineConfig` -object updates, the File Integrity Operator watches the node objects; when a -node is being updated, the AIDE scans are suspended for the duration of the -update. When the update finishes, the database is reinitialized and the scans -resume. - -This pause and resume logic only applies to updates through the `MachineConfig` -API, as they are reflected in the node object annotations. diff --git a/modules/file-integrity-operator-reinitializing-database.adoc b/modules/file-integrity-operator-reinitializing-database.adoc deleted file mode 100644 index fe21841f77c1..000000000000 --- a/modules/file-integrity-operator-reinitializing-database.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-advanced-usage.adoc - -[id="file-integrity-operator-reinitializing-database_{context}"] -= Reinitializing the database - -If the File Integrity Operator detects a change that was planned, it might be -required to reinitialize the database. To do that, annotate the `FileIntegrity` -custom resource (CR) with `file-integrity.openshift.io/re-init`: - -[source,terminal] ----- -$ oc annotate fileintegrities/worker-fileintegrity file-integrity.openshift.io/re-init= ----- - -The old database and log files are backed up and a new database is initialized. -The old database and logs are retained on the nodes under `/etc/kubernetes`, as -seen in the following output from a pod spawned using `oc debug`: - -.Example output -[source,terminal] ----- - ls -lR /host/etc/kubernetes/aide.* --rw-------. 1 root root 1839782 Sep 17 15:08 /host/etc/kubernetes/aide.db.gz --rw-------. 1 root root 1839783 Sep 17 14:30 /host/etc/kubernetes/aide.db.gz.backup-20200917T15_07_38 --rw-------. 1 root root 73728 Sep 17 15:07 /host/etc/kubernetes/aide.db.gz.backup-20200917T15_07_55 --rw-r--r--. 1 root root 0 Sep 17 15:08 /host/etc/kubernetes/aide.log --rw-------. 1 root root 613 Sep 17 15:07 /host/etc/kubernetes/aide.log.backup-20200917T15_07_38 --rw-r--r--. 1 root root 0 Sep 17 15:07 /host/etc/kubernetes/aide.log.backup-20200917T15_07_55 ----- - -To provide some permanence of record, the resulting config maps are not -owned by the `FileIntegrity` object, so manual cleanup is necessary. As a -result, any previous integrity failures would still be visible in the -`FileIntegrityNodeStatus` object. diff --git a/modules/file-integrity-operator-viewing-attributes.adoc b/modules/file-integrity-operator-viewing-attributes.adoc deleted file mode 100644 index 39ddd1c58f23..000000000000 --- a/modules/file-integrity-operator-viewing-attributes.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-configuring.adoc - -[id="viewing-file-integrity-object-attributes_{context}"] -= Viewing `FileIntegrity` object attributes - -As with any Kubernetes custom resources (CRs), you can run `oc explain -fileintegrity`, and then look at the individual attributes using: - -[source,terminal] ----- -$ oc explain fileintegrity.spec ----- - -[source,terminal] ----- -$ oc explain fileintegrity.spec.config ----- diff --git a/modules/file-integrity-supplying-custom-aide-config.adoc b/modules/file-integrity-supplying-custom-aide-config.adoc deleted file mode 100644 index 90ee73890ed3..000000000000 --- a/modules/file-integrity-supplying-custom-aide-config.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-configuring.adoc - -[id="file-integrity-operator-supplying-custom-aide-config_{context}"] -= Supplying a custom AIDE configuration - -Any entries that configure AIDE internal behavior such as `DBDIR`, `LOGDIR`, -`database`, and `database_out` are overwritten by the Operator. The Operator -would add a prefix to `/hostroot/` before all paths to be watched for integrity -changes. This makes reusing existing AIDE configs that might often not be -tailored for a containerized environment and start from the root directory -easier. - -[NOTE] -==== -`/hostroot` is the directory where the pods running AIDE mount the host’s -file system. Changing the configuration triggers a reinitializing of the database. -==== diff --git a/modules/file-integrity-understanding-default-config.adoc b/modules/file-integrity-understanding-default-config.adoc deleted file mode 100644 index 3225b591fabf..000000000000 --- a/modules/file-integrity-understanding-default-config.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-configuring.adoc - -[id="file-integrity-understanding-default-config_{context}"] -= Understanding the default File Integrity Operator configuration - -Below is an excerpt from the `aide.conf` key of the config map: - -[source,bash] ----- -@@define DBDIR /hostroot/etc/kubernetes -@@define LOGDIR /hostroot/etc/kubernetes -database=file:@@{DBDIR}/aide.db.gz -database_out=file:@@{DBDIR}/aide.db.gz -gzip_dbout=yes -verbose=5 -report_url=file:@@{LOGDIR}/aide.log -report_url=stdout -PERMS = p+u+g+acl+selinux+xattrs -CONTENT_EX = sha512+ftype+p+u+g+n+acl+selinux+xattrs - -/hostroot/boot/ CONTENT_EX -/hostroot/root/\..* PERMS -/hostroot/root/ CONTENT_EX ----- - -The default configuration for a `FileIntegrity` instance provides coverage for -files under the following directories: - -* `/root` -* `/boot` -* `/usr` -* `/etc` - -The following directories are not covered: - -* `/var` -* `/opt` -* Some OpenShift-specific excludes under `/etc/` diff --git a/modules/file-integrity-understanding-file-integrity-cr.adoc b/modules/file-integrity-understanding-file-integrity-cr.adoc deleted file mode 100644 index 90c13d714f97..000000000000 --- a/modules/file-integrity-understanding-file-integrity-cr.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-understanding.adoc - -[id="understanding-file-integrity-custom-resource_{context}"] -= Understanding the `FileIntegrity` custom resource - -An instance of a `FileIntegrity` custom resource (CR) represents a set of -continuous file integrity scans for one or more nodes. - -Each `FileIntegrity` CR is backed by a daemon set running AIDE on the nodes -matching the `FileIntegrity` CR specification. - -The following example `FileIntegrity` CR enables scans on only the worker nodes, -but otherwise uses the defaults. - -.Example `FileIntegrity` CR - -[source,yaml] ----- -apiVersion: fileintegrity.openshift.io/v1alpha1 -kind: FileIntegrity -metadata: - name: worker-fileintegrity - namespace: openshift-file-integrity -spec: - nodeSelector: - node-role.kubernetes.io/worker: "" - config: {} ----- diff --git a/modules/file-integrity-understanding-file-integrity-node-statuses-object.adoc b/modules/file-integrity-understanding-file-integrity-node-statuses-object.adoc deleted file mode 100644 index cbc15e02af17..000000000000 --- a/modules/file-integrity-understanding-file-integrity-node-statuses-object.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * security/file_integrity_operator/file-integrity-operator-understanding.adoc - -[id="understanding-file-integrity-node-statuses-object_{context}"] -= Understanding the `FileIntegrityNodeStatuses` object - -The scan results of the `FileIntegrity` CR are reported in another object called -`FileIntegrityNodeStatuses`. - -[source,terminal] ----- -$ oc get fileintegritynodestatuses ----- - -.Example output -[source,terminal] ----- -NAME AGE -worker-fileintegrity-ip-10-0-130-192.ec2.internal 101s -worker-fileintegrity-ip-10-0-147-133.ec2.internal 109s -worker-fileintegrity-ip-10-0-165-160.ec2.internal 102s ----- - -[NOTE] -==== -`FileIntegrityNodeStatus` might not be created until the second run of the -scanner is finished. The period is configurable. -==== - -There is one result object per node. The `nodeName` attribute of -each `FileIntegrityNodeStatus` object corresponds to the node being scanned. The -status of the file integrity scan is represented in the `results` array, which -holds scan conditions. - -[source,terminal] ----- -$ oc get fileintegritynodestatuses.fileintegrity.openshift.io -ojsonpath='{.items[*].results}' | jq ----- diff --git a/modules/find-clusters-with-most-kubernetes-and-istio-vulnerabilities.adoc b/modules/find-clusters-with-most-kubernetes-and-istio-vulnerabilities.adoc new file mode 100644 index 000000000000..ccdfd8aa0e1e --- /dev/null +++ b/modules/find-clusters-with-most-kubernetes-and-istio-vulnerabilities.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="find-clusters-with-most-kubernetes-and-istio-vulnerabilities_{context}"] += Finding clusters with most Kubernetes and Istio vulnerabilities by using the dashboard + +[role="_abstract"] +You can identify the clusters with most Kubernetes, {osp}, and Istio vulnerabilities (deprecated) in your environment by using the vulnerability management dashboard. + +.Procedure + +. In the {product-title-short} portal, click *Vulnerability Management*-> *Dashboard*. The *Clusters with most orchestrator and Istio vulnerabilities* widget shows a list of clusters, ranked by the number of Kubernetes, {osp}, and Istio vulnerabilities (deprecated) in each cluster. +The cluster on top of the list is the cluster with the highest number of vulnerabilities. +. Click on one of the clusters from the list to view details about the cluster. +The *Cluster* view includes: +** *Cluster Summary* section, which shows cluster details and metadata, top risky objects (deployments, namespaces, and images), recently detected vulnerabilities, riskiest images, and deployments with the most severe policy violations. +** *Cluster Findings* section, which includes a list of failing policies and list of fixable CVEs. +** *Related Entities* section, which shows the number of namespaces, deployments, policies, images, components, and CVEs the cluster contains. +You can select these entities to view more details. +. Click *View All* on the widget header to view the list of all clusters. \ No newline at end of file diff --git a/modules/find-failing-cis-controls.adoc b/modules/find-failing-cis-controls.adoc new file mode 100644 index 000000000000..02439c7cba08 --- /dev/null +++ b/modules/find-failing-cis-controls.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * operating/review-cluster-configuration.adoc +:_mod-docs-content-type: PROCEDURE +[id="find-failing-cis-controls_{context}"] += Finding failing CIS controls + +[role="_abstract"] +Similar to the *Policy Violations* sunburst chart in the *Configuration Management* view, the *CIS Kubernetes v1.5* widget provides information about failing Center for Information Security (CIS) controls. + +Each level of the chart is represented by one ring or circle. + +* The innermost circle represents the percentage of failing controls. +* The next ring represents the control categories. +* The outermost ring represents individual controls in a particular category. + +.Procedure + +. To view details about failing controls, hover over the sunburst chart. +. To view detailed information about failing controls, select *_n_ Controls Failing*, where _n_ is a number. +The *Controls* view displays a list of failing controls filtered based on the compliance state. +. Select a row to view more details, including control descriptions and nodes where the controls are failing. +. The *Control Findings* section in the information panel lists nodes where the controls are failing. +Select a row to view more details, including Kubernetes labels, annotations, and other metadata. + +You can use the detailed information to focus on a subset of nodes, industry standards, or failing controls. You can also assess, check, and report on the compliance status of your containerized infrastructure. \ No newline at end of file diff --git a/modules/find-policy-violations.adoc b/modules/find-policy-violations.adoc new file mode 100644 index 000000000000..75397083b4e5 --- /dev/null +++ b/modules/find-policy-violations.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/review-cluster-configuration.adoc +:_mod-docs-content-type: PROCEDURE +[id="find-policy-violations_{context}"] += Finding policy violations + +[role="_abstract"] +The *Policy Violations by Severity* widget in the *Configuration Management* view displays policy violations in a sunburst chart. +Each level of the chart is represented by one ring or circle. + +* The innermost circle represents the total number of violations. +* The next ring represents the *Low*, *Medium*, *High*, and *Critical* policy categories. +* The outermost ring represents individual policies in a particular category. + +The *Configuration Management* view only shows the information about policies that have the *Lifecycle Stage* set to *Deploy*. +It does not include policies that address runtime behavior or those configured for assessment in the *Build* stage. + +.Procedure +. In the {product-title-short} portal, go to *Configuration Management*. +. On the *Policy Violations by Severity* widget, move your mouse over the sunburst chart to view details about policy violations. +. Select *_n_ rated as high*, where _n_ is a number, to view detailed information about high-priority policy violations. +The *Policies* view displays a list of policy violations filtered on the selected category. +. Select a row to view more details, including policy description, remediation, deployments with violations, and more. +The details are visible in a panel. +. The *Policy Findings* section in the information panel lists deployments where these violations occurred. +. Select a deployment under the *Policy Findings* section to view related details including Kubernetes labels, annotations, and service account. + +You can use the detailed information to plan a remediation for violations. diff --git a/modules/find-the-most-vulnerable-image-components.adoc b/modules/find-the-most-vulnerable-image-components.adoc new file mode 100644 index 000000000000..3f0e60db11fb --- /dev/null +++ b/modules/find-the-most-vulnerable-image-components.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc +:_mod-docs-content-type: PROCEDURE + +[id="find-the-most-vulnerable-image-components_{context}"] += Finding the most vulnerable image components by using the dashboard + +[role="_abstract"] +Use the *Vulnerability Management* view for identifying highly vulnerable image components. + +.Procedure + +. Go to the {product-title-short} portal and click *Vulnerability Management* -> *Dashboard* from the navigation menu. +. From the *Vulnerability Management* view header, select *Application & Infrastructure* -> *Image Components*. +. In the *Image Components* view, select the *Image CVEs* column header to arrange the components in descending order (highest first) based on the CVEs count. diff --git a/modules/gathering-application-diagnostic-data.adoc b/modules/gathering-application-diagnostic-data.adoc deleted file mode 100644 index e7ee464fef81..000000000000 --- a/modules/gathering-application-diagnostic-data.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-s2i.adoc - -[id="gathering-application-diagnostic-data_{context}"] -= Gathering application diagnostic data to investigate application failures - -Application failures can occur within running application pods. In these situations, you can retrieve diagnostic information with these strategies: - -* Review events relating to the application pods. -* Review the logs from the application pods, including application-specific log files that are not collected by the OpenShift Logging framework. -* Test application functionality interactively and run diagnostic tools in an application container. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. List events relating to a specific application pod. The following example retrieves events for an application pod named `my-app-1-akdlg`: -+ -[source,terminal] ----- -$ oc describe pod/my-app-1-akdlg ----- - -. Review logs from an application pod: -+ -[source,terminal] ----- -$ oc logs -f pod/my-app-1-akdlg ----- - -. Query specific logs within a running application pod. Logs that are sent to stdout are collected by the OpenShift Logging framework and are included in the output of the preceding command. The following query is only required for logs that are not sent to stdout. -+ -.. If an application log can be accessed without root privileges within a pod, concatenate the log file as follows: -+ -[source,terminal] ----- -$ oc exec my-app-1-akdlg -- cat /var/log/my-application.log ----- -+ -.. If root access is required to view an application log, you can start a debug container with root privileges and then view the log file from within the container. Start the debug container from the project's `DeploymentConfig` object. Pod users typically run with non-root privileges, but running troubleshooting pods with temporary root privileges can be useful during issue investigation: -+ -[source,terminal] ----- -$ oc debug dc/my-deployment-configuration --as-root -- cat /var/log/my-application.log ----- -+ -[NOTE] -==== -You can access an interactive shell with root access within the debug pod if you run `oc debug dc/<deployment_configuration> --as-root` without appending `-- <command>`. -==== - -. Test application functionality interactively and run diagnostic tools, in an application container with an interactive shell. -.. Start an interactive shell on the application container: -+ -[source,terminal] ----- -$ oc exec -it my-app-1-akdlg /bin/bash ----- -+ -.. Test application functionality interactively from within the shell. For example, you can run the container's entry point command and observe the results. Then, test changes from the command line directly, before updating the source code and rebuilding the application container through the S2I process. -+ -.. Run diagnostic binaries available within the container. -+ -[NOTE] -==== -Root privileges are required to run some diagnostic binaries. In these situations you can start a debug pod with root access, based on a problematic pod's `DeploymentConfig` object, by running `oc debug dc/<deployment_configuration> --as-root`. Then, you can run diagnostic binaries as root from within the debug pod. -==== - -. If diagnostic binaries are not available within a container, you can run a host's diagnostic binaries within a container's namespace by using `nsenter`. The following example runs `ip ad` within a container's namespace, using the host`s `ip` binary. -.. Enter into a debug session on the target node. This step instantiates a debug pod called `<node_name>-debug`: -+ -[source,terminal] ----- -$ oc debug node/my-cluster-node ----- -+ -.. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead. -==== -+ -.. Determine the target container ID: -+ -[source,terminal] ----- -# crictl ps ----- -+ -.. Determine the container's process ID. In this example, the target container ID is `a7fe32346b120`: -+ -[source,terminal] ----- -# crictl inspect a7fe32346b120 --output yaml | grep 'pid:' | awk '{print $2}' ----- -+ -.. Run `ip ad` within the container's namespace, using the host's `ip` binary. This example uses `31150` as the container's process ID. The `nsenter` command enters the namespace of a target process and runs a command in its namespace. Because the target process in this example is a container's process ID, the `ip ad` command is run in the container's namespace from the host: -+ -[source,terminal] ----- -# nsenter -n -t 31150 -- ip ad ----- -+ -[NOTE] -==== -Running a host's diagnostic binaries within a container's namespace is only possible if you are using a privileged container such as a debug node. -==== diff --git a/modules/gathering-bootstrap-diagnostic-data.adoc b/modules/gathering-bootstrap-diagnostic-data.adoc deleted file mode 100644 index e5f7ef789c56..000000000000 --- a/modules/gathering-bootstrap-diagnostic-data.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="gathering-bootstrap-diagnostic-data_{context}"] -= Gathering bootstrap node diagnostic data - -When experiencing bootstrap-related issues, you can gather `bootkube.service` `journald` unit logs and container logs from the bootstrap node. - -.Prerequisites - -* You have SSH access to your bootstrap node. -* You have the fully qualified domain name of the bootstrap node. -* If you are hosting Ignition configuration files by using an HTTP server, you must have the HTTP server's fully qualified domain name and the port number. You must also have SSH access to the HTTP host. - -.Procedure - -. If you have access to the bootstrap node's console, monitor the console until the node reaches the login prompt. - -. Verify the Ignition file configuration. -+ -* If you are hosting Ignition configuration files by using an HTTP server. -+ -.. Verify the bootstrap node Ignition file URL. Replace `<http_server_fqdn>` with HTTP server's fully qualified domain name: -+ -[source,terminal] ----- -$ curl -I http://<http_server_fqdn>:<port>/bootstrap.ign <1> ----- -<1> The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. -+ -.. To verify that the Ignition file was received by the bootstrap node, query the HTTP server logs on the serving host. For example, if you are using an Apache web server to serve Ignition files, enter the following command: -+ -[source,terminal] ----- -$ grep -is 'bootstrap.ign' /var/log/httpd/access_log ----- -+ -If the bootstrap Ignition file is received, the associated `HTTP GET` log message will include a `200 OK` success status, indicating that the request succeeded. -+ -.. If the Ignition file was not received, check that the Ignition files exist and that they have the appropriate file and web server permissions on the serving host directly. -+ -* If you are using a cloud provider mechanism to inject Ignition configuration files into hosts as part of their initial deployment. -+ -.. Review the bootstrap node's console to determine if the mechanism is injecting the bootstrap node Ignition file correctly. - -. Verify the availability of the bootstrap node's assigned storage device. - -. Verify that the bootstrap node has been assigned an IP address from the DHCP server. - -. Collect `bootkube.service` journald unit logs from the bootstrap node. Replace `<bootstrap_fqdn>` with the bootstrap node's fully qualified domain name: -+ -[source,terminal] ----- -$ ssh core@<bootstrap_fqdn> journalctl -b -f -u bootkube.service ----- -+ -[NOTE] -==== -The `bootkube.service` log on the bootstrap node outputs etcd `connection refused` errors, indicating that the bootstrap server is unable to connect to etcd on master nodes. After etcd has started on each master node and the nodes have joined the cluster, the errors should stop. -==== -+ -. Collect logs from the bootstrap node containers. -.. Collect the logs using `podman` on the bootstrap node. Replace `<bootstrap_fqdn>` with the bootstrap node's fully qualified domain name: -+ -[source,terminal] ----- -$ ssh core@<bootstrap_fqdn> 'for pod in $(sudo podman ps -a -q); do sudo podman logs $pod; done' ----- - -. If the bootstrap process fails, verify the following. -+ -* You can resolve `api.<cluster_name>.<base_domain>` from the installation host. -* The load balancer proxies port 6443 connections to bootstrap and master nodes. Ensure that the proxy configuration meets {product-title} installation requirements. diff --git a/modules/gathering-crio-logs.adoc b/modules/gathering-crio-logs.adoc deleted file mode 100644 index 5fed36502c6c..000000000000 --- a/modules/gathering-crio-logs.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-crio-issues.adoc - -[id="gathering-crio-logs_{context}"] -= Gathering CRI-O journald unit logs - -If you experience CRI-O issues, you can obtain CRI-O journald unit logs from a node. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). -* You have the fully qualified domain names of the control plane, or master machines. - -.Procedure - -. Gather CRI-O journald unit logs. The following example collects logs from all master nodes within the cluster: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u crio ----- - -. Gather CRI-O journald unit logs from a specific node: -+ -[source,terminal] ----- -$ oc adm node-logs <node_name> -u crio ----- - -. If the API is not functional, review the logs using SSH instead. Replace `<node>.<cluster_name>.<base_domain>` with appropriate values: -+ -[source,terminal] ----- -$ ssh core@<node>.<cluster_name>.<base_domain> journalctl -b -f -u crio.service ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. Before attempting to collect diagnostic data over SSH, review whether the data collected by running `oc adm must gather` and other `oc` commands is sufficient instead. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>`. -==== diff --git a/modules/gathering-data-specific-features.adoc b/modules/gathering-data-specific-features.adoc deleted file mode 100644 index 97148c34462c..000000000000 --- a/modules/gathering-data-specific-features.adoc +++ /dev/null @@ -1,296 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-collecting-virt-data.adoc -// * support/gathering-cluster-data.adoc - -//This file contains UI elements and/or package names that need to be updated. - -// Dependency: modules/virt-document-attributes.adoc - -ifeval::["{context}" == "gathering-cluster-data"] -:from-main-support-section: -:VirtProductName: OpenShift Virtualization -endif::[] - -[id="gathering-data-specific-features_{context}"] -= Gathering data about specific features - -You can gather debugging information about specific features by using the `oc adm must-gather` CLI command with the `--image` or `--image-stream` argument. The `must-gather` tool supports multiple images, so you can gather data about more than one feature by running a single command. - -ifdef::from-main-support-section[] - -ifndef::openshift-origin[] - -.Supported must-gather images -[cols="2,2",options="header",subs="attributes+"] -|=== -|Image |Purpose - -|`registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion}` -|Data collection for {VirtProductName}. - -|`registry.redhat.io/openshift-serverless-1/svls-must-gather-rhel8` -|Data collection for OpenShift Serverless. - -|`registry.redhat.io/openshift-service-mesh/istio-must-gather-rhel7` -|Data collection for Red Hat OpenShift Service Mesh. - -|`registry.redhat.io/rhcam-1-2/openshift-migration-must-gather-rhel8` -|Data collection for migration-related information. - -|`registry.redhat.io/ocs4/ocs-must-gather-rhel8:v4.7` -|Data collection for Red Hat OpenShift Container Storage. - -|`registry.redhat.io/openshift4/ose-cluster-logging-operator` -|Data collection for OpenShift Logging. - -|=== - -endif::openshift-origin[] - -ifdef::openshift-origin[] - -.Available must-gather images -[cols="2,2",options="header"] -|=== -|Image |Purpose - -|`quay.io/kubevirt/must-gather` -|Data collection for KubeVirt. - -|`quay.io/openshift-knative/must-gather` -|Data collection for Knative. - -|`docker.io/maistra/istio-must-gather` -|Data collection for service mesh. - -|`quay.io/konveyor/must-gather` -|Data collection for migration-related information. - -|`quay.io/ocs-dev/ocs-must-gather` -|Data collection for OpenShift Container Storage. - -|`quay.io/openshift/origin-cluster-logging-operator` -|Data collection for OpenShift Logging. - -|=== - -endif::openshift-origin[] - - -endif::from-main-support-section[] - -[NOTE] -==== -To collect the default `must-gather` data in addition to specific feature data, add the `--image-stream=openshift/must-gather` argument. -==== - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. -* The {product-title} CLI (`oc`) installed. - -.Procedure - -. Navigate to the directory where you want to store the `must-gather` data. - -ifndef::openshift-origin[] - -. Run the `oc adm must-gather` command with one or more `--image` or `--image-stream` arguments. For example, the following command gathers both the default cluster data and information specific to {VirtProductName}: -+ -[source,terminal,subs="attributes+"] ----- -$ oc adm must-gather \ - --image-stream=openshift/must-gather \ <1> - --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion} <2> ----- -<1> The default {product-title} `must-gather` image -<2> The must-gather image for {VirtProductName} -+ -You can use the `must-gather` tool with additional arguments to gather data that is specifically related to OpenShift Logging and the Cluster Logging Operator in your cluster. For OpenShift Logging, run the following command: -+ -[source,terminal] ----- -$ oc adm must-gather --image=$(oc -n openshift-logging get deployment.apps/cluster-logging-operator \ - -o jsonpath='{.spec.template.spec.containers[?(@.name == "cluster-logging-operator")].image}') ----- -+ -.Example `must-gather` output for OpenShift Logging -[%collapsible] -==== -[source,terminal] ----- -├── cluster-logging -│ ├── clo -│ │ ├── cluster-logging-operator-74dd5994f-6ttgt -│ │ ├── clusterlogforwarder_cr -│ │ ├── cr -│ │ ├── csv -│ │ ├── deployment -│ │ └── logforwarding_cr -│ ├── collector -│ │ ├── fluentd-2tr64 -│ ├── curator -│ │ └── curator-1596028500-zkz4s -│ ├── eo -│ │ ├── csv -│ │ ├── deployment -│ │ └── elasticsearch-operator-7dc7d97b9d-jb4r4 -│ ├── es -│ │ ├── cluster-elasticsearch -│ │ │ ├── aliases -│ │ │ ├── health -│ │ │ ├── indices -│ │ │ ├── latest_documents.json -│ │ │ ├── nodes -│ │ │ ├── nodes_stats.json -│ │ │ └── thread_pool -│ │ ├── cr -│ │ ├── elasticsearch-cdm-lp8l38m0-1-794d6dd989-4jxms -│ │ └── logs -│ │ ├── elasticsearch-cdm-lp8l38m0-1-794d6dd989-4jxms -│ ├── install -│ │ ├── co_logs -│ │ ├── install_plan -│ │ ├── olmo_logs -│ │ └── subscription -│ └── kibana -│ ├── cr -│ ├── kibana-9d69668d4-2rkvz -├── cluster-scoped-resources -│ └── core -│ ├── nodes -│ │ ├── ip-10-0-146-180.eu-west-1.compute.internal.yaml -│ └── persistentvolumes -│ ├── pvc-0a8d65d9-54aa-4c44-9ecc-33d9381e41c1.yaml -├── event-filter.html -├── gather-debug.log -└── namespaces - ├── openshift-logging - │ ├── apps - │ │ ├── daemonsets.yaml - │ │ ├── deployments.yaml - │ │ ├── replicasets.yaml - │ │ └── statefulsets.yaml - │ ├── batch - │ │ ├── cronjobs.yaml - │ │ └── jobs.yaml - │ ├── core - │ │ ├── configmaps.yaml - │ │ ├── endpoints.yaml - │ │ ├── events - │ │ │ ├── curator-1596021300-wn2ks.162634ebf0055a94.yaml - │ │ │ ├── curator.162638330681bee2.yaml - │ │ │ ├── elasticsearch-delete-app-1596020400-gm6nl.1626341a296c16a1.yaml - │ │ │ ├── elasticsearch-delete-audit-1596020400-9l9n4.1626341a2af81bbd.yaml - │ │ │ ├── elasticsearch-delete-infra-1596020400-v98tk.1626341a2d821069.yaml - │ │ │ ├── elasticsearch-rollover-app-1596020400-cc5vc.1626341a3019b238.yaml - │ │ │ ├── elasticsearch-rollover-audit-1596020400-s8d5s.1626341a31f7b315.yaml - │ │ │ ├── elasticsearch-rollover-infra-1596020400-7mgv8.1626341a35ea59ed.yaml - │ │ ├── events.yaml - │ │ ├── persistentvolumeclaims.yaml - │ │ ├── pods.yaml - │ │ ├── replicationcontrollers.yaml - │ │ ├── secrets.yaml - │ │ └── services.yaml - │ ├── openshift-logging.yaml - │ ├── pods - │ │ ├── cluster-logging-operator-74dd5994f-6ttgt - │ │ │ ├── cluster-logging-operator - │ │ │ │ └── cluster-logging-operator - │ │ │ │ └── logs - │ │ │ │ ├── current.log - │ │ │ │ ├── previous.insecure.log - │ │ │ │ └── previous.log - │ │ │ └── cluster-logging-operator-74dd5994f-6ttgt.yaml - │ │ ├── cluster-logging-operator-registry-6df49d7d4-mxxff - │ │ │ ├── cluster-logging-operator-registry - │ │ │ │ └── cluster-logging-operator-registry - │ │ │ │ └── logs - │ │ │ │ ├── current.log - │ │ │ │ ├── previous.insecure.log - │ │ │ │ └── previous.log - │ │ │ ├── cluster-logging-operator-registry-6df49d7d4-mxxff.yaml - │ │ │ └── mutate-csv-and-generate-sqlite-db - │ │ │ └── mutate-csv-and-generate-sqlite-db - │ │ │ └── logs - │ │ │ ├── current.log - │ │ │ ├── previous.insecure.log - │ │ │ └── previous.log - │ │ ├── curator-1596028500-zkz4s - │ │ ├── elasticsearch-cdm-lp8l38m0-1-794d6dd989-4jxms - │ │ ├── elasticsearch-delete-app-1596030300-bpgcx - │ │ │ ├── elasticsearch-delete-app-1596030300-bpgcx.yaml - │ │ │ └── indexmanagement - │ │ │ └── indexmanagement - │ │ │ └── logs - │ │ │ ├── current.log - │ │ │ ├── previous.insecure.log - │ │ │ └── previous.log - │ │ ├── fluentd-2tr64 - │ │ │ ├── fluentd - │ │ │ │ └── fluentd - │ │ │ │ └── logs - │ │ │ │ ├── current.log - │ │ │ │ ├── previous.insecure.log - │ │ │ │ └── previous.log - │ │ │ ├── fluentd-2tr64.yaml - │ │ │ └── fluentd-init - │ │ │ └── fluentd-init - │ │ │ └── logs - │ │ │ ├── current.log - │ │ │ ├── previous.insecure.log - │ │ │ └── previous.log - │ │ ├── kibana-9d69668d4-2rkvz - │ │ │ ├── kibana - │ │ │ │ └── kibana - │ │ │ │ └── logs - │ │ │ │ ├── current.log - │ │ │ │ ├── previous.insecure.log - │ │ │ │ └── previous.log - │ │ │ ├── kibana-9d69668d4-2rkvz.yaml - │ │ │ └── kibana-proxy - │ │ │ └── kibana-proxy - │ │ │ └── logs - │ │ │ ├── current.log - │ │ │ ├── previous.insecure.log - │ │ │ └── previous.log - │ └── route.openshift.io - │ └── routes.yaml - └── openshift-operators-redhat - ├── ... ----- -==== -endif::openshift-origin[] - -ifdef::openshift-origin[] - -. Run the `oc adm must-gather` command with one or more `--image` or `--image-stream` arguments. For example, the following command gathers both the default cluster data and information specific to KubeVirt: -+ -[source,terminal] ----- -$ oc adm must-gather \ - --image-stream=openshift/must-gather \ <1> - --image=quay.io/kubevirt/must-gather <2> ----- -<1> The default {product-title} `must-gather` image -<2> The must-gather image for KubeVirt - -endif::openshift-origin[] - -. Create a compressed file from the `must-gather` directory that was just created in your working directory. For example, on a computer that uses a Linux -operating system, run the following command: -+ -[source,terminal] ----- -$ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ <1> ----- -<1> Make sure to replace `must-gather-local.5421342344627712289/` with the -actual directory name. - -. Attach the compressed file to your support case on the link:https://access.redhat.com[Red Hat Customer Portal]. - -ifeval::["{context}" == "gathering-cluster-data"] -:!from-main-support-section: -:!VirtProductName: -endif::[] diff --git a/modules/gathering-operator-logs.adoc b/modules/gathering-operator-logs.adoc deleted file mode 100644 index db29db0f3413..000000000000 --- a/modules/gathering-operator-logs.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-operator-issues.adoc - -[id="gathering-operator-logs_{context}"] -= Gathering Operator logs - -If you experience Operator issues, you can gather detailed diagnostic information from Operator pod logs. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). -* You have the fully qualified domain names of the control plane, or master machines. - -.Procedure - -. List the Operator pods that are running in the Operator's namespace, plus the pod status, restarts, and age: -+ -[source,terminal] ----- -$ oc get pods -n <operator_namespace> ----- - -. Review logs for an Operator pod: -+ -[source,terminal] ----- -$ oc logs pod/<pod_name> -n <operator_namespace> ----- -+ -If an Operator pod has multiple containers, the preceding command will produce an error that includes the name of each container. Query logs from an individual container: -+ -[source,terminal] ----- -$ oc logs pod/<operator_pod_name> -c <container_name> -n <operator_namespace> ----- - -. If the API is not functional, review Operator pod and container logs on each master node by using SSH instead. Replace `<master-node>.<cluster_name>.<base_domain>` with appropriate values. -.. List pods on each master node: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl pods ----- -+ -.. For any Operator pods not showing a `Ready` status, inspect the pod's status in detail. Replace `<operator_pod_id>` with the Operator pod's ID listed in the output of the preceding command: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl inspectp <operator_pod_id> ----- -+ -.. List containers related to an Operator pod: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl ps --pod=<operator_pod_id> ----- -+ -.. For any Operator container not showing a `Ready` status, inspect the container's status in detail. Replace `<container_id>` with a container ID listed in the output of the preceding command: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl inspect <container_id> ----- -+ -.. Review the logs for any Operator containers not showing a `Ready` status. Replace `<container_id>` with a container ID listed in the output of the preceding command: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl logs -f <container_id> ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. Before attempting to collect diagnostic data over SSH, review whether the data collected by running `oc adm must gather` and other `oc` commands is sufficient instead. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>`. -==== diff --git a/modules/gathering-s2i-diagnostic-data.adoc b/modules/gathering-s2i-diagnostic-data.adoc deleted file mode 100644 index d65c9f6a85e8..000000000000 --- a/modules/gathering-s2i-diagnostic-data.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-s2i.adoc - -[id="gathering-s2i-diagnostic-data_{context}"] -= Gathering Source-to-Image diagnostic data - -The S2I tool runs a build pod and a deployment pod in sequence. The deployment pod is responsible for deploying the application pods based on the application container image created in the build stage. Watch build, deployment and application pod status to determine where in the S2I process a failure occurs. Then, focus diagnostic data collection accordingly. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Watch the pod status throughout the S2I process to determine at which stage a failure occurs: -+ -[source,terminal] ----- -$ oc get pods -w <1> ----- -<1> Use `-w` to monitor pods for changes until you quit the command using `Ctrl+C`. - -. Review a failed pod's logs for errors. -+ -* *If the build pod fails*, review the build pod's logs: -+ -[source,terminal] ----- -$ oc logs -f pod/<application_name>-<build_number>-build ----- -+ -[NOTE] -==== -Alternatively, you can review the build configuration's logs using `oc logs -f bc/<application_name>`. The build configuration's logs include the logs from the build pod. -==== -+ -* *If the deployment pod fails*, review the deployment pod's logs: -+ -[source,terminal] ----- -$ oc logs -f pod/<application_name>-<build_number>-deploy ----- -+ -[NOTE] -==== -Alternatively, you can review the deployment configuration's logs using `oc logs -f dc/<application_name>`. This outputs logs from the deployment pod until the deployment pod completes successfully. The command outputs logs from the application pods if you run it after the deployment pod has completed. After a deployment pod completes, its logs can still be accessed by running `oc logs -f pod/<application_name>-<build_number>-deploy`. -==== -+ -* *If an application pod fails, or if an application is not behaving as expected within a running application pod*, review the application pod's logs: -+ -[source,terminal] ----- -$ oc logs -f pod/<application_name>-<build_number>-<random_string> ----- diff --git a/modules/generate-diagnostic-bundle-using-acs-portal.adoc b/modules/generate-diagnostic-bundle-using-acs-portal.adoc new file mode 100644 index 000000000000..90486218efc6 --- /dev/null +++ b/modules/generate-diagnostic-bundle-using-acs-portal.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * configuration/generate-diagnostic-bundle.adoc +// * operating/use-system-health-dashboard.adoc +:_mod-docs-content-type: PROCEDURE +[id="generate-diagnostic-bundle-using-acs-portal_{context}"] += Generating a diagnostic bundle by using the RHACS portal + +You can generate a diagnostic bundle by using the system health dashboard in the {product-title-short} portal. + +.Prerequisites +* To generate a diagnostic bundle, you need `read` permission for the `Administration` resource. + +.Procedure +. In the {product-title-short} portal, select *Platform Configuration* -> *System Health*. +. On the *System Health* view header, click *Generate Diagnostic Bundle*. +. For the *Filter by clusters* drop-down menu, select the clusters for which you want to generate the diagnostic data. +. For *Filter by starting time*, specify the date and time (in UTC format) from which you want to include the diagnostic data. +. Click *Download Diagnostic Bundle*. diff --git a/modules/generate-diagnostic-bundle-using-roxctl-cli.adoc b/modules/generate-diagnostic-bundle-using-roxctl-cli.adoc new file mode 100644 index 000000000000..3c1a24c73fb8 --- /dev/null +++ b/modules/generate-diagnostic-bundle-using-roxctl-cli.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * configuration/generate-diagnostic-bundle.adoc +:_mod-docs-content-type: PROCEDURE +[id="generate-diagnostic-bundle-using-roxctl-cli_{context}"] += Generating a diagnostic bundle by using the roxctl CLI + +You can generate a diagnostic bundle with the {rh-rhacs-first} administrator password or API token and central address by using the `roxctl` CLI. + +.Prerequisites +* To generate a diagnostic bundle, you need `read` permission for the `Administration` resource. + +* You must have configured the {product-title-short} administrator password or API token and central address. + +.Procedure + +* To generate a diagnostic bundle by using the {product-title-short} administrator password, perform the following steps: + +. Run the following command to configure the `ROX_PASSWORD` and `ROX_CENTRAL_ADDRESS` environment variables: ++ +[source,terminal,subs="+quotes"] +---- +$ export ROX_PASSWORD=_<rox_password>_ && export ROX_CENTRAL_ADDRESS=_<address>:<port_number>_ <1> +---- ++ +<1> For `<rox_password>`, specify the {product-title-short} administrator password. + +. Run the following command to generate a diagnostic bundle by using the {product-title-short} administrator password: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" -p "$ROX_PASSWORD" central debug download-diagnostics +---- + +* To generate a diagnostic bundle by using the API token, perform the following steps: + +. Run the following command to configure the `ROX_API_TOKEN` environment variable: ++ +[source,terminal,subs="+quotes"] +---- +$ export ROX_API_TOKEN=_<api_token>_ +---- + +. Run the following command to generate a diagnostic bundle by using the API token: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug download-diagnostics +---- diff --git a/modules/generate-network-policies-ng20.adoc b/modules/generate-network-policies-ng20.adoc new file mode 100644 index 000000000000..b2dc687eb68f --- /dev/null +++ b/modules/generate-network-policies-ng20.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="generate-network-policies-ng20_{context}"] += Generating network policies in the network graph + +[role="_abstract"] +{product-title-short} lets you automatically generate network policies based on the actual observed network communication flows in your environment. + +You can generate policies based on the cluster, namespaces, and deployments that you have selected in the network graph. Policies are generated for any deployments that are included in the current Network Graph scope. For example, the current scope could include the entire cluster, a cluster and namespaces, or individually selected deployments in the selected namespaces. You can also further reduce the scope by applying one of the filters from the *Filter deployments* field with any combination of the cluster, namespace, and deployment selections. For example, you could narrow the scope to deployments in a specific cluster and namespace that are affected by a specific CVE. Policies are generated from the traffic observed during the baseline discovery period. + +. In the {product-title-short} portal, go to *Network Graph*. +. Select a cluster, and then select one or more namespaces. +. Optional: Select individual deployments to restrict the policy generated to only those deployments. You can also use the *Filter deployments* feature to further narrow the scope. +. In the network graph header, select *Network policy generator*. +. Optional: In the information panel that opens, select *Exclude ports & protocols* to remove the port/protocol restrictions when generating network policies from a baseline. ++ +As an example, the `nginx3` deployment makes a port 80 connection to `nginx4`, and this is included as part of the baseline for `nginx4`. If policies are generated and this checkbox is not selected (the default behavior), the generated policy will restrict the allowed connections from `nginx3` to `nginx4` to only port 80. If policies are generated with this option selected, the generated policy will allow any port in the connection from `nginx3` to `nginx4`. +. Click *Generate and simulate network policies*. {product-title-short} generates policies for the scope that you have chosen. This scope is displayed at the top of the *Generate network policies* panel. ++ +[NOTE] +==== +Clicking on the deployment information in the scope displays a list of the deployments that are included. +==== +. Optional: Copy the generated network policy configuration YAML file to the clipboard or download it by clicking the download icon in the panel. +. Optional: To compare the generated network policies to the existing network policies, click *Compare*. The YAML files for existing and generated network policies are shown in a side-by-side view. ++ +[NOTE] +==== +Some items do not have generated policies, such as namespaces with existing ingress policies or deployments in certain protected namespaces such as as `stackrox` or `acs`. +==== +. Optional: Click the *Actions* menu to perform the following activities: +* Share the YAML file with notifiers: Sends the YAML file to one of the system notifiers you have configured, for example, Slack, ServiceNow, or an application that uses generic webhooks. These notifiers are configured by navigating to *Platform Configuration* -> *Integrations*. See the documentation in the "Additional resources" section for more information. +* Rebuild rules from active traffic: Refreshes the generated policies that are displayed. +* Revert rules to previously applied YAML: Removes the simulated policy and reverts to the last network policy. \ No newline at end of file diff --git a/modules/generating-connectivity-difference-reports.adoc b/modules/generating-connectivity-difference-reports.adoc new file mode 100644 index 000000000000..04bdb4566325 --- /dev/null +++ b/modules/generating-connectivity-difference-reports.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: PROCEDURE +[id="generating-connectivity-difference-reports_{context}"] += Generating connectivity difference reports by using the roxctl netpol connectivity diff command + +[role="_abstract"] +Generate a report on connectivity differences between two sets of Kubernetes manifests, including network policies by using the `roxctl netpol connectivity diff` command . + +.Prerequisites + +* You have two folders, `dir1` and `dir2`, each containing Kubernetes manifests, including network policies. + +.Procedure + +* To find the connectivity differences between the Kubernetes manifests in the specified directories, run the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl netpol connectivity diff --dir1=<folder_path_1> --dir2=<folder_path_2> [flags] <1> +---- ++ +<1> Specify the path to the folders, which can include sub-folders that contain YAML resources and network policies for analysis. The command scans the entire sub-folder trees for both the directories. ++ +For example, `<folder_path_1>` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[`netpol-analysis-example-minimal/`] and `<folder_path_2>` is link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-diff-example-minimal[`netpol-diff-example-minimal/`]. Optionally, you can also specify parameters to change the behavior of the command. + +[NOTE] +==== +The command considers all YAML files that you can accept by using `kubectl apply -f`, and the YAML files then become valid inputs for your `roxctl netpol connectivity diff` command. +==== + +.Example output + +[cols="1,2,2,1,1,1",options="header"] +|=== + +|diff-type |source |destination |dir 1 |dir 2 |workloads-diff-info + +|changed +|default/frontend[Deployment] +|default/backend[Deployment] +|TCP 9090 +|TCP 9090,UDP 53 +| + +|added +|0.0.0.0-255.255.255.255 +|default/backend[Deployment] +|No Connections +|TCP 9090 +| + +|=== + +The semantic difference report gives you an overview of the connections that were changed, added, or removed in `dir2` compared to the connections allowed in `dir1`. When you review the output, each line represents one allowed connection that was added, removed, or changed in `dir2` compared to `dir1`. + +If applicable, the `workloads-diff-info` provides additional details about added or removed workloads related to the added or removed connection. + +For example, if a connection from workload `A` to workload `B` is removed because workload `B` was deleted, the `workloads-diff-info` indicates that workload `B` was removed. However, if such a connection was removed only because of network policy changes and neither workload `A` nor `B` was deleted, the `workloads-diff-info` is empty. diff --git a/modules/generating-sboms-by-using-the-api.adoc b/modules/generating-sboms-by-using-the-api.adoc new file mode 100644 index 000000000000..b97a5f9fcc09 --- /dev/null +++ b/modules/generating-sboms-by-using-the-api.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scanner-generate-sbom.adoc + +:_mod-docs-content-type: REFERENCE +[id="generating-sboms-by-using-the-api_{context}"] += Generating SBOMs by using the API + +You can use the {rh-rhacs-first} API to create a Software Bill of Materials (SBOM). You must use the `ROX_API_TOKEN` for authorization to connect to the endpoint and generate the SBOM. The request payload is generated in JSON format. + +For more information, see "GenerateSBOM". \ No newline at end of file diff --git a/modules/generating-sboms-by-using-the-rhacs-portal.adoc b/modules/generating-sboms-by-using-the-rhacs-portal.adoc new file mode 100644 index 000000000000..867fb8b8af1d --- /dev/null +++ b/modules/generating-sboms-by-using-the-rhacs-portal.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scanner-generate-sbom.adoc + +:_mod-docs-content-type: PROCEDURE +[id="generating-sboms-by-using-the-rhacs-portal_{context}"] += Generating SBOMs by using the RHACS portal + +[role="_abstract"] +You can generate a Software Bill of Materials (SBOM) by using the {rh-rhacs-first} portal. + +.Procedure + +. In the {product-title-short} portal, click the *Vulnerability Management* -> *Results* -> *<number> Images* tab. +. Locate the image that you want to use, and do any of the following tasks: +** Click the overflow menu {kebab}, and then select *Generate SBOM*. +** Select the image to view the image details, and then click *Generate SBOM*. + +A window opens that provides information about the image and the SBOM format that is generated. {product-title-short} creates the file in JSON format. Depending on your browser configuration, your browser can automatically download the file to your computer. \ No newline at end of file diff --git a/modules/generating-sboms-by-using-the-roxctl-cli.adoc b/modules/generating-sboms-by-using-the-roxctl-cli.adoc new file mode 100644 index 000000000000..120a4b707e59 --- /dev/null +++ b/modules/generating-sboms-by-using-the-roxctl-cli.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scanner-generate-sbom.adoc + +:_mod-docs-content-type: PROCEDURE +[id="generating-sboms-by-using-the-roxctl-cli_{context}"] += Generating SBOMs by using the roxctl CLI + +[role="_abstract"] +You can generate a Software Bill of Materials (SBOM) by using the `roxctl` CLI. + +.Procedure + +* To generate SBOMs, run the following command: ++ +[source,terminal] +---- +$ roxctl image sbom --image=<image_name> <1> +---- ++ +<1> Specify the name and reference of the image that you want to generate an SBOM for, in string format. For example, `nginx:latest` or `nginx@sha256:...`. ++ +For more information, see "roxctl image sbom". \ No newline at end of file diff --git a/modules/generating-sensor-deployment-files.adoc b/modules/generating-sensor-deployment-files.adoc new file mode 100644 index 000000000000..bc09a432125f --- /dev/null +++ b/modules/generating-sensor-deployment-files.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * cli/managing-secured-clusters.adoc +:_mod-docs-content-type: PROCEDURE +[id="generating-sensor-deployment-files_{context}"] += Generating Sensor deployment files + +== Generating files for Kubernetes systems + +.Procedure + +* Generate the required sensor configuration for your Kubernetes cluster and associate it with your Central instance by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl sensor generate k8s --name _<cluster_name>_ --central "$ROX_ENDPOINT" +---- + +== Generating files for {ocp} systems + +.Procedure + +* Generate the required sensor configuration for your {ocp} cluster and associate it with your Central instance by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl sensor generate openshift --openshift-version _<ocp_version>_ --name _<cluster_name>_ --central "$ROX_ENDPOINT" <1> +---- ++ +<1> For the `--openshift-version` option, specify the major {ocp} version number for your cluster. For example, specify `3` for {ocp} version `3.x` and specify `4` for {ocp} version `4.x`. ++ +Read the `--help` output to see other options that you might need to use depending on your system architecture. ++ +Verify that the endpoint you provide for `--central` can be reached from the cluster where you are deploying {product-title} services. ++ +[IMPORTANT] +==== +If you are using a non-gRPC capable load balancer, such as HAProxy, AWS Application Load Balancer (ALB), or AWS Elastic Load Balancing (ELB), follow these guidelines: + +* Use the WebSocket Secure (`wss`) protocol. +To use `wss`, prefix the address with *`wss://`*, and +* Add the port number after the address, for example: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl sensor generate k8s --central wss://stackrox-central.example.com:443 +---- +==== diff --git a/modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc b/modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc new file mode 100644 index 000000000000..c1c95def4533 --- /dev/null +++ b/modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: PROCEDURE +[id="generating-svg-graphs-from-the-dot-output-using-graphviz_{context}"] += Generating svg graphs from the dot output using Graphviz + +Follow these steps to create a graph in `svg` format from the `dot` output. + +.Prerequisites + +* link:https://graphviz.org/[Graphviz] is installed on your local system. + +.Procedure + +* Run the following command to create the graph in `svg` format: ++ +[source,terminal] +---- +$ dot -Tsvg connlist_output.dot > connlist_output_graph.svg +---- ++ +The following are examples of the dot output and the resulting graph generated by Graphviz: + +** link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/connlist/netpol-analysis-example-minimal_connlist_output.dot[Example 1: dot output] + +** link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/connlist/netpol-analysis-example-minimal_connlist_output.dot.svg[Example 2: Graph generated by Graphviz] diff --git a/modules/getting-cluster-version-status-and-update-details.adoc b/modules/getting-cluster-version-status-and-update-details.adoc deleted file mode 100644 index 61bee9035016..000000000000 --- a/modules/getting-cluster-version-status-and-update-details.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc - -[id="getting-cluster-version-and-update-details_{context}"] -= Getting cluster version, status, and update details - -You can view the cluster version and status by running the `oc get clusterversion` command. If the status shows that the installation is still progressing, you can review the status of the Operators for more information. - -You can also list the current update channel and review the available cluster updates. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Obtain the cluster version and overall status: -+ -[source,terminal] ----- -$ oc get clusterversion ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING SINCE STATUS -version 4.6.4 True False 6m25s Cluster version is 4.6.4 ----- -+ -The example output indicates that the cluster has been installed successfully. - -. If the cluster status indicates that the installation is still progressing, you can obtain more detailed progress information by checking the status of the Operators: -+ -[source,terminal] ----- -$ oc get clusteroperators.config.openshift.io ----- - -. View a detailed summary of cluster specifications, update availability, and update history: -+ -[source,terminal] ----- -$ oc describe clusterversion ----- - -. List the current update channel: -+ -[source,terminal] ----- -$ oc get clusterversion -o jsonpath='{.items[0].spec}{"\n"}' ----- -+ -.Example output -[source,terminal] ----- -{"channel":"stable-4.6","clusterID":"245539c1-72a3-41aa-9cec-72ed8cf25c5c","upstream":"https://api.openshift.com/api/upgrades_info/v1/graph"} ----- - -. Review the available cluster updates: -+ -[source,terminal] ----- -$ oc adm upgrade ----- -+ -.Example output -[source,terminal] ----- -Cluster version is 4.6.4 - -Updates: - -VERSION IMAGE -4.6.6 quay.io/openshift-release-dev/ocp-release@sha256:c7e8f18e8116356701bd23ae3a23fb9892dd5ea66c8300662ef30563d7104f39 ----- diff --git a/modules/getting-information-about-the-events-in-a-particular-domain.adoc b/modules/getting-information-about-the-events-in-a-particular-domain.adoc new file mode 100644 index 000000000000..9f239523d573 --- /dev/null +++ b/modules/getting-information-about-the-events-in-a-particular-domain.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// *operating/using-the-administration-events-page.adoc + +:_mod-docs-content-type: PROCEDURE +[id="getting-information-about-the-events-in-a-particular-domain_{context}"] += Getting information about the events in a particular domain + +By viewing the details of an administration event, you get more information about the events in that particular domain. This enables you to better understand the context and details of the events. + +.Procedure + +* In the *Administration Events* page, click the domain to view its details. \ No newline at end of file diff --git a/modules/gitops-document-attributes.adoc b/modules/gitops-document-attributes.adoc deleted file mode 100644 index 21dc24bd1cf8..000000000000 --- a/modules/gitops-document-attributes.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Standard document attributes to be used in the documentation -// -// The following are shared by all documents: -:toc: -:toclevels: 4 -:experimental: -// -// Product content attributes, that is, substitution variables in the files. -// -:gitops-title: Red Hat OpenShift GitOps -:gitops-shortname: GitOps -:gitops-ver: release-tech-preview-1.0 diff --git a/modules/google-cloud-scc-configuring-acs.adoc b/modules/google-cloud-scc-configuring-acs.adoc new file mode 100644 index 000000000000..b5cc160f38eb --- /dev/null +++ b/modules/google-cloud-scc-configuring-acs.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-google-cloud-scc.adoc +:_mod-docs-content-type: PROCEDURE +[id="google-cloud-scc-configuring-acs_{context}"] += Configuring {product-title} for integrating with Google Cloud SCC + +You can create a new Google Cloud SCC integration in {product-title} by using the source ID and a Google service account. + +.Prerequisites +* A *service account* with the `Security Center Findings Editor` IAM role on the organization level. +See link:https://cloud.google.com/security-command-center/docs/access-control[Access control with IAM] for more information. +* Either a link:https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity[workload identity] +or a *Service account key (JSON)* for the service account. See link:https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating[Creating a service account] +and link:https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys[Creating service account keys] for more information. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *Google Cloud SCC*. +. Click *New Integration* (*`add`* icon). +. Enter a name for *Integration Name*. +. Enter the *Cloud SCC Source ID*. +. When using a workload identity, check *Use workload identity*. Otherwise, enter the contents of + your service account key file into the *Service account key (JSON)* field. +. Select *Create* to generate the configuration. diff --git a/modules/google-cloud-storage-configuring-acs.adoc b/modules/google-cloud-storage-configuring-acs.adoc new file mode 100644 index 000000000000..85ee003a1d92 --- /dev/null +++ b/modules/google-cloud-storage-configuring-acs.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-google-cloud-storage.adoc +:_mod-docs-content-type: PROCEDURE +[id="google-cloud-storage-configuring-acs_{context}"] += Configuring {product-title} + +[role="_abstract"] +To configure data backups on Google Cloud Storage (GCS), create an integration in {product-title}. + +.Prerequisites +* An existing *bucket*. +To create a new bucket, see the official Google Cloud Storage documentation topic link:https://cloud.google.com/storage/docs/creating-buckets[Creating storage buckets]. +* A *service account* with the `Storage Object Admin` IAM role in the storage bucket you want to use. +See link:https://cloud.google.com/storage/docs/access-control/using-iam-permissions[Using Cloud IAM permissions] for more information. +* Either a link:https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity[workload identity] +or a *Service account key (JSON)* for the service account. See link:https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating[Creating a service account] +and link:https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys[Creating service account keys] for more information. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *External backups* section and select *Google Cloud Storage*. +. Click *New Integration* (*`add`* icon). +. Enter a name for *Integration Name*. +. Enter the number of backups to retain in the *Backups To Retain* box. +. For *Schedule*, select the backup frequency (daily or weekly) and the time to run the backup process. +. Enter the *Bucket* name in which you want to store the backup. +. When using a workload identity, check *Use workload identity*. Otherwise, enter the contents of + your service account key file into the *Service account key (JSON)* field. +. Select *Test* to confirm that the integration with GCS is working. +. Select *Create* to generate the configuration. + +Once configured, {product-title} automatically backs up all data according to the specified schedule. diff --git a/modules/google-workload-identity-federation-gke.adoc b/modules/google-workload-identity-federation-gke.adoc new file mode 100644 index 000000000000..b09c4bcbc721 --- /dev/null +++ b/modules/google-workload-identity-federation-gke.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-short-lived-tokens.adoc +:_mod-docs-content-type: PROCEDURE +[id="google-workload-identity-federation-gke_{context}"] += Configuring Google Kubernetes Engine (GKE) + +[role="_abstract"] +When running {rh-rhacs-first} on GKE, you can configure short-lived tokens through Google workload identities. + +.Prerequisites +* You must have access to the Google Cloud project containing the cluster and integration resources. + +.Procedure +. Follow the instructions in the Google Cloud Platform documentation to link:https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity[Use workload identity federation for GKE]. +. Annotate the {product-title-short} service account by running the following command: ++ +[source,terminal] +---- +$ oc annotate serviceaccount \ <1> + central \ <2> + --namespace stackrox \ + iam.gke.io/gcp-service-account=<GSA_NAME>@<GSA_PROJECT>.iam.gserviceaccount.com +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +<2> When setting up delegated scanning, use *sensor* instead of *central*. diff --git a/modules/google-workload-identity-federation-openshift.adoc b/modules/google-workload-identity-federation-openshift.adoc new file mode 100644 index 000000000000..b2fbd5420b94 --- /dev/null +++ b/modules/google-workload-identity-federation-openshift.adoc @@ -0,0 +1,78 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-short-lived-tokens.adoc +:_mod-docs-content-type: PROCEDURE +[id="google-workload-identity-federation-openshift_{context}"] += Configuring {ocp} + +[role="_abstract"] +You can configure short-lived tokens through Google workload identities when running {rh-rhacs-first} on {ocp}. + +.Prerequisites +* You must have a public OIDC configuration bucket with the {ocp} service account signer key. The recommended way to obtain the OIDC configuration for the {ocp} cluster is to use the link:https://docs.openshift.com/container-platform/4.14/authentication/managing_cloud_provider_credentials/cco-short-term-creds.html[Cloud Credential Operator in manual mode for short-term credentials] instructions. +* Access to a Google Cloud project with the *roles/iam.workloadIdentityPoolAdmin* role. + +.Procedure +. Follow the instructions at link:https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#iam-workload-pools-list-gcloud[Manage workload identity pools] to create a workload identity pool. For example: ++ +[source,terminal] +---- +$ gcloud iam workload-identity-pools create rhacs-pool \ + --location="global" \ + --display-name="RHACS workload pool" +---- + +. Follow the instructions at link:https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#manage-providers[Manage workload identity pool providers] to create a workload identity pool provider. For example: ++ +[source,terminal] +---- +$ gcloud iam workload-identity-pools providers create-oidc rhacs-provider \ + --location="global" \ + --workload-identity-pool="rhacs-pool" \ + --display-name="RHACS provider" \ + --attribute-mapping="google.subject=assertion.sub" \ + --issuer-uri="https://<oidc_configuration_url>" \ + --allowed-audiences=openshift +---- + +. Connect a Google service account to the workload identity pool. For example: ++ +[source,terminal] +---- +$ gcloud iam service-accounts add-iam-policy-binding <GSA_NAME>@<GSA_PROJECT>.iam.gserviceaccount.com \ + --role roles/iam.workloadIdentityUser \ + --member="principal://iam.googleapis.com/projects/<GSA_PROJECT_NUMBER>/locations/global/workloadIdentityPools/rhacs-provider/subject/system:serviceaccount:stackrox:central" <1> +---- +<1> For delegated scanning, set the subject to *system:serviceaccount:stackrox:sensor*. + +. Create a service account JSON containing the Security token service (STS) configuration. For example: ++ +[source,json] +---- +{ + "type": "external_account", + "audience": "//iam.googleapis.com/projects/<GSA_PROJECT_ID>/locations/global/workloadIdentityPools/rhacs-pool/providers/rhacs-provider", + "subject_token_type": "urn:ietf:params:oauth:token-type:jwt", + "token_url": "https://sts.googleapis.com/v1/token", + "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/%3CGSA_NAME%3E@%3CGSA_PROJECT%3E.iam.gserviceaccount.com:generateAccessToken", + "credential_source": { + "file": "/var/run/secrets/openshift/serviceaccount/token", + "format": { + "type": "text" + } + } +} +---- + +. Use the service account JSON as a secret to the {product-title-short} namespace: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: gcp-cloud-credentials + namespace: stackrox +data: + credentials: <base64_encoded_json> +---- diff --git a/modules/graceful-restart.adoc b/modules/graceful-restart.adoc deleted file mode 100644 index c9b31564282e..000000000000 --- a/modules/graceful-restart.adoc +++ /dev/null @@ -1,152 +0,0 @@ -// Module included in the following assemblies: -// -// * backup_and_restore/graceful-cluster-restart.adoc - -[id="graceful-restart_{context}"] -= Restarting the cluster - -You can restart your cluster after it has been shut down gracefully. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* This procedure assumes that you gracefully shut down the cluster. - -.Procedure - -. Power on any cluster dependencies, such as external storage or an LDAP server. - -. Start all cluster machines. -+ -Use the appropriate method for your cloud environment to start the machines, for example, from your cloud provider's web console. -+ -Wait approximately 10 minutes before continuing to check the status of master nodes. - -. Verify that all master nodes are ready. -+ -[source,terminal] ----- -$ oc get nodes -l node-role.kubernetes.io/master ----- -+ -The master nodes are ready if the status is `Ready`, as shown in the following output: -+ -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-168-251.ec2.internal Ready master 75m v1.20.0 -ip-10-0-170-223.ec2.internal Ready master 75m v1.20.0 -ip-10-0-211-16.ec2.internal Ready master 75m v1.20.0 ----- - -. If the master nodes are _not_ ready, then check whether there are any pending certificate signing requests (CSRs) that must be approved. - -.. Get the list of current CSRs: -+ -[source,terminal] ----- -$ oc get csr ----- - -.. Review the details of a CSR to verify that it is valid: -+ -[source,terminal] ----- -$ oc describe csr <csr_name> <1> ----- -<1> `<csr_name>` is the name of a CSR from the list of current CSRs. - -.. Approve each valid CSR: -+ -[source,terminal] ----- -$ oc adm certificate approve <csr_name> ----- - -. After the master nodes are ready, verify that all worker nodes are ready. -+ -[source,terminal] ----- -$ oc get nodes -l node-role.kubernetes.io/worker ----- -+ -The worker nodes are ready if the status is `Ready`, as shown in the following output: -+ -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-179-95.ec2.internal Ready worker 64m v1.20.0 -ip-10-0-182-134.ec2.internal Ready worker 64m v1.20.0 -ip-10-0-250-100.ec2.internal Ready worker 64m v1.20.0 ----- - -. If the worker nodes are _not_ ready, then check whether there are any pending certificate signing requests (CSRs) that must be approved. - -.. Get the list of current CSRs: -+ -[source,terminal] ----- -$ oc get csr ----- - -.. Review the details of a CSR to verify that it is valid: -+ -[source,terminal] ----- -$ oc describe csr <csr_name> <1> ----- -<1> `<csr_name>` is the name of a CSR from the list of current CSRs. - -.. Approve each valid CSR: -+ -[source,terminal] ----- -$ oc adm certificate approve <csr_name> ----- - -. Verify that the cluster started properly. - -.. Check that there are no degraded cluster Operators. -+ -[source,terminal] ----- -$ oc get clusteroperators ----- -+ -Check that there are no cluster Operators with the `DEGRADED` condition set to `True`. -+ -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -authentication 4.7.0 True False False 59m -cloud-credential 4.7.0 True False False 85m -cluster-autoscaler 4.7.0 True False False 73m -config-operator 4.7.0 True False False 73m -console 4.7.0 True False False 62m -csi-snapshot-controller 4.7.0 True False False 66m -dns 4.7.0 True False False 76m -etcd 4.7.0 True False False 76m -... ----- - -.. Check that all nodes are in the `Ready` state: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -Check that the status for all nodes is `Ready`. -+ -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-168-251.ec2.internal Ready master 82m v1.20.0 -ip-10-0-170-223.ec2.internal Ready master 82m v1.20.0 -ip-10-0-179-95.ec2.internal Ready worker 70m v1.20.0 -ip-10-0-182-134.ec2.internal Ready worker 70m v1.20.0 -ip-10-0-211-16.ec2.internal Ready master 82m v1.20.0 -ip-10-0-250-100.ec2.internal Ready worker 69m v1.20.0 ----- - -If the cluster did not start properly, you might need to restore your cluster using an etcd backup. diff --git a/modules/graceful-shutdown.adoc b/modules/graceful-shutdown.adoc deleted file mode 100644 index aae8997719c2..000000000000 --- a/modules/graceful-shutdown.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * backup_and_restore/graceful-cluster-shutdown.adoc - -[id="graceful-shutdown_{context}"] -= Shutting down the cluster - -You can shut down your cluster in a graceful manner so that it can be restarted at a later date. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have taken an etcd backup. -+ -[IMPORTANT] -==== -It is important to take an etcd backup before performing this procedure so that your cluster can be restored if you encounter any issues when restarting the cluster. -==== - -.Procedure - -. Shut down all of the nodes in the cluster. You can do this from your cloud provider's web console, or you can use the below commands: - -.. Obtain the list of nodes: -+ -[source,terminal] ----- -$ nodes=$(oc get nodes -o jsonpath='{.items[*].metadata.name}') ----- - -.. Shut down all of the nodes: -+ -[source,terminal] ----- -$ for node in ${nodes[@]} -do - echo "==== Shut down $node ====" - ssh core@$node sudo shutdown -h 1 -done ----- -+ -Shutting down the nodes using one of these methods allows pods to terminate gracefully, which reduces the chance for data corruption. -+ -[NOTE] -==== -It is not necessary to drain master nodes of the standard pods that ship with {product-title} prior to shutdown. - -Cluster administrators are responsible for ensuring a clean restart of their own workloads after the cluster is restarted. If you drained master nodes prior to shutdown because of custom workloads, you must mark the master nodes as schedulable before the cluster will be functional again after restart. -==== - -. Shut off any cluster dependencies that are no longer needed, such as external storage or an LDAP server. Be sure to consult your vendor's documentation before doing so. diff --git a/modules/helm-adding-helm-chart-repositories.adoc b/modules/helm-adding-helm-chart-repositories.adoc deleted file mode 100644 index e035bd660659..000000000000 --- a/modules/helm-adding-helm-chart-repositories.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/helm/configuring-custom-helm-chart-repositories.adoc - -[id="adding-helm-chart-repositories_{context}"] -= Adding custom Helm chart repositories - -As a cluster administrator, you can add custom Helm chart repositories to your cluster and enable access to the Helm charts from these repositories in the *Developer Catalog*. - -.Procedure - -. To add a new Helm Chart Repository, you must add the Helm Chart Repository custom resource (CR) to your cluster. -+ -.Sample Helm Chart Repository CR - -[source,yaml] ----- -apiVersion: helm.openshift.io/v1beta1 -kind: HelmChartRepository -metadata: - name: <name> -spec: - # optional name that might be used by console - # name: <chart-display-name> - connectionConfig: - url: <helm-chart-repository-url> ----- -+ -For example, to add an Azure sample chart repository, run: -+ -[source,terminal] ----- -$ cat <<EOF | oc apply -f - -apiVersion: helm.openshift.io/v1beta1 -kind: HelmChartRepository -metadata: - name: azure-sample-repo -spec: - name: azure-sample-repo - connectionConfig: - url: https://raw.githubusercontent.com/Azure-Samples/helm-charts/master/docs -EOF ----- -+ -. Navigate to the *Developer Catalog* in the web console to verify that the Helm charts from the chart repository are displayed. -+ -For example, use the *Chart repositories* filter to search for a Helm chart from the repository. -+ -.Chart repositories filter -image::odc_helm_chart_repo_filter.png[] -+ -[NOTE] -==== -If a cluster administrator removes all of the chart repositories, then you cannot view the Helm option in the *+Add* view, *Developer Catalog*, and left navigation panel. -==== diff --git a/modules/helm-creating-a-custom-helm-chart-on-openshift.adoc b/modules/helm-creating-a-custom-helm-chart-on-openshift.adoc deleted file mode 100644 index 044ba67aa2ed..000000000000 --- a/modules/helm-creating-a-custom-helm-chart-on-openshift.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/helm/getting-started-with-helm-on-openshift.adoc - -[id="creating-a-custom-helm-chart-on-openshift_{context}"] -= Creating a custom Helm chart on {product-title} - -.Procedure -. Create a new project: -+ -[source,terminal] ----- -$ oc new-project nodejs-ex-k ----- - -. Download an example Node.js chart that contains {product-title} objects: -+ -[source,terminal] ----- -$ git clone https://github.com/redhat-developer/redhat-helm-charts ----- - -. Go to the directory with the sample chart: -+ -[source,terminal] ----- -$ cd redhat-helm-charts/alpha/nodejs-ex-k/ ----- - -. Edit the `Chart.yaml` file and add a description of your chart: -+ -[source,yaml] ----- -apiVersion: v2 <1> -name: nodejs-ex-k <2> -description: A Helm chart for OpenShift <3> -icon: https://static.redhat.com/libs/redhat/brand-assets/latest/corp/logo.svg <4> ----- -+ -<1> The chart API version. It should be `v2` for Helm charts that require at least Helm 3. -<2> The name of your chart. -<3> The description of your chart. -<4> The URL to an image to be used as an icon. - -. Verify that the chart is formatted properly: -+ -[source,terminal] ----- -$ helm lint ----- -+ -.Example output -[source,terminal] ----- -[INFO] Chart.yaml: icon is recommended - -1 chart(s) linted, 0 chart(s) failed ----- - -. Navigate to the previous directory level: -+ -[source,terminal] ----- -$ cd .. ----- - -. Install the chart: -+ -[source,terminal] ----- -$ helm install nodejs-chart nodejs-ex-k ----- - -. Verify that the chart has installed successfully: -+ -[source,terminal] ----- -$ helm list ----- -+ -.Example output -[source,terminal] ----- -NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION -nodejs-chart nodejs-ex-k 1 2019-12-05 15:06:51.379134163 -0500 EST deployed nodejs-0.1.0 1.16.0 ----- diff --git a/modules/helm-creating-credentials-and-certificates-to-add-helm-repositories.adoc b/modules/helm-creating-credentials-and-certificates-to-add-helm-repositories.adoc deleted file mode 100644 index e13f964c73ba..000000000000 --- a/modules/helm-creating-credentials-and-certificates-to-add-helm-repositories.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/helm/configuring-custom-helm-chart-repositories.adoc - -[id="creating-credentials-and-certificates-to-add-helm-repositories_{context}"] -= Creating credentials and CA certificates to add Helm chart repositories - -Some Helm chart repositories need credentials and custom certificate authority (CA) certificates to connect to it. You can use the web console as well as the CLI to add credentials and certificates. - -.Procedure -To configure the credentials and certificates, and then add a Helm chart repository using the CLI: - -. In the `openshift-config` namespace, create a `ConfigMap` object with a custom CA certificate in PEM encoded format, and store it under the `ca-bundle.crt` key within the config map: -+ -[source,terminal] ----- -$ oc create configmap helm-ca-cert \ ---from-file=ca-bundle.crt=/path/to/certs/ca.crt \ --n openshift-config ----- -+ -. In the `openshift-config` namespace, create a `Secret` object to add the client TLS configurations: -+ -[source,terminal] ----- -$ oc create secret generic helm-tls-configs \ ---from-file=tls.crt=/path/to/certs/client.crt \ ---from-file=tls.key=/path/to/certs//client.key \ --n openshift-config ----- -+ -Note that the client certificate and key must be in PEM encoded format and stored under the keys `tls.crt` and `tls.key`, respectively. - -. Add the Helm repository as follows: -+ -[source,terminal] ----- -$ cat <<EOF | oc apply -f - -apiVersion: helm.openshift.io/v1beta1 -kind: HelmChartRepository -metadata: - name: <helm-repository> -spec: - name: <helm-repository> - connectionConfig: - url: <URL for the Helm repository> - tlsConfig: - name: helm-tls-configs - ca: - name: helm-ca-cert -EOF ----- -+ -The `ConfigMap` and `Secret` are consumed in the HelmChartRepository CR using the `tlsConfig` and `ca` fields. These certificates are used to connect to the Helm repository URL. -. By default, all authenticated users have access to all configured charts. However, for chart repositories where certificates are needed, you must provide users with read access to the `helm-ca-cert` config map and `helm-tls-configs` secret in the `openshift-config` namespace, as follows: -+ -[source,terminal] ----- -$ cat <<EOF | kubectl apply -f - -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - namespace: openshift-config - name: helm-chartrepos-tls-conf-viewer -rules: -- apiGroups: [""] - resources: ["configmaps"] - resourceNames: ["helm-ca-cert"] - verbs: ["get"] -- apiGroups: [""] - resources: ["secrets"] - resourceNames: ["helm-tls-configs"] - verbs: ["get"] ---- -kind: RoleBinding -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - namespace: openshift-config - name: helm-chartrepos-tls-conf-viewer -subjects: - - kind: Group - apiGroup: rbac.authorization.k8s.io - name: 'system:authenticated' -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: helm-chartrepos-tls-conf-viewer -EOF ----- diff --git a/modules/helm-disabling-helm-chart-repository-in-the-cluster.adoc b/modules/helm-disabling-helm-chart-repository-in-the-cluster.adoc deleted file mode 100644 index c66391f4d26a..000000000000 --- a/modules/helm-disabling-helm-chart-repository-in-the-cluster.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/helm/disabling-helm-chart-repositories.adoc - -[id="helm-disabling-helm-chart-repository-in-the-cluster_{context}"] -= Disabling Helm Chart repository in the cluster - -You can disable Helm Charts in the catalog by adding the `disabled` property in the `HelmChartRepository` custom resource. - -.Procedure - -* To disable a Helm Chart repository by using CLI, add the `disabled: true` flag to the custom resource. For example, to remove an Azure sample chart repository, run: -+ ----- -$ cat <<EOF | oc apply -f - -apiVersion: helm.openshift.io/v1beta1 -kind: HelmChartRepository -metadata: - name: azure-sample-repo -spec: - connectionConfig: - url:https://raw.githubusercontent.com/Azure-Samples/helm-charts/master/docs - disabled: true -EOF ----- - -* To disable a recently added Helm Chart repository by using Web Console: -+ -. Go to *Custom Resource Definitions* and search for the `HelmChartRepository` custom resource. - -. Go to *Instances*, find the repository you want to disable, and click its name. - -. Go to the *YAML* tab, add the `disabled: true` flag in the `spec` section, and click `Save`. -+ -.Example ----- -spec: - connectionConfig: - url: <url-of-the-repositoru-to-be-disabled> - disabled: true ----- -+ -The repository is now disabled and will not appear in the catalog. diff --git a/modules/helm-generate-root-certificates.adoc b/modules/helm-generate-root-certificates.adoc new file mode 100644 index 000000000000..3bfe5230e4b3 --- /dev/null +++ b/modules/helm-generate-root-certificates.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-helm.adoc +:_mod-docs-content-type: PROCEDURE +[id="helm-generate-root-certificates_{context}"] += Generating root certificates file + +[role="_abstract"] +If you do not have access to your `values-private.yaml` configuration file that you have used to install {rh-rhacs-first}, use the following instruction to generate the `values-private.yaml` configuration file containing root certificates. + +Skip the instruction here, if you have access to your `values-private.yaml` configuration file. + +[IMPORTANT] +==== +The generated `values-private.yaml` file has sensitive configuration options. Ensure that you store this file securely. +==== + +.Procedure + +. Download the link:https://raw.githubusercontent.com/openshift/openshift-docs/rhacs-docs-main/files/create_certificate_values_file.sh[`create_certificate_values_file.sh`] script. +. Make the `create_certificate_values_file.sh` script executable: ++ +[source,terminal] +---- +$ chmod +x create_certificate_values_file.sh +---- +. Run the `create_certificate_values_file.sh` script file: ++ +[source,terminal] +---- +$ create_certificate_values_file.sh values-private.yaml +---- diff --git a/modules/helm-installing-a-helm-chart-on-an-openshift-cluster.adoc b/modules/helm-installing-a-helm-chart-on-an-openshift-cluster.adoc deleted file mode 100644 index 62c3aefc3a5d..000000000000 --- a/modules/helm-installing-a-helm-chart-on-an-openshift-cluster.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/helm/getting-started-with-helm-on-openshift.adoc - -[id="installing-a-helm-chart-on-an-openshift-cluster_{context}"] - -= Installing a Helm chart on an {product-title} cluster - -.Prerequisites -* You have a running {product-title} cluster and you have logged into it. -* You have installed Helm. - -.Procedure - -. Create a new project: -+ -[source,terminal] ----- -$ oc new-project mysql ----- - -. Add a repository of Helm charts to your local Helm client: -+ -[source,terminal] ----- -$ helm repo add stable https://kubernetes-charts.storage.googleapis.com/ ----- -+ -.Example output -[source,terminal] ----- -"stable" has been added to your repositories ----- - -. Update the repository: -+ -[source,terminal] ----- -$ helm repo update ----- - -. Install an example MySQL chart: -+ -[source,terminal] ----- -$ helm install example-mysql stable/mysql ----- - -. Verify that the chart has installed successfully: -+ -[source,terminal] ----- -$ helm list ----- -+ -.Example output -[source,terminal] ----- -NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION -example-mysql mysql 1 2019-12-05 15:06:51.379134163 -0500 EST deployed mysql-1.5.0 5.7.27 ----- diff --git a/modules/helm-installing-helm.adoc b/modules/helm-installing-helm.adoc deleted file mode 100644 index be10878485c9..000000000000 --- a/modules/helm-installing-helm.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/helm/getting-started-with-helm-on-openshift.adoc - -[id="installing-helm_{context}"] -= Installing Helm - -The following section describes how to install Helm on different platforms using the CLI. - -You can also find the URL to the latest binaries from the {product-title} web console by clicking the *?* icon in the upper-right corner and selecting *Command Line Tools*. - -.Prerequisites -* You have installed Go, version 1.13 or higher. - -== On Linux - -. Download the Helm binary and add it to your path: -+ -[source,terminal] ----- -# curl -L https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest/helm-linux-amd64 -o /usr/local/bin/helm ----- - -. Make the binary file executable: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/helm ----- - -. Check the installed version: -+ -[source,terminal] ----- -$ helm version ----- -+ -.Example output -[source,terminal] ----- -version.BuildInfo{Version:"v3.0", GitCommit:"b31719aab7963acf4887a1c1e6d5e53378e34d93", GitTreeState:"clean", GoVersion:"go1.13.4"} ----- - -== On Windows 7/8 - -. Download the latest link:https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest/helm-windows-amd64.exe[`.exe` file] and put in a directory of your preference. -. Right click *Start* and click *Control Panel*. -. Select *System and Security* and then click *System*. -. From the menu on the left, select *Advanced systems settings* and click *Environment Variables* at the bottom. -. Select *Path* from the *Variable* section and click *Edit*. -. Click *New* and type the path to the folder with the `.exe` file into the field or click *Browse* and select the directory, and click *OK*. - -== On Windows 10 - -. Download the latest link:https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest/helm-windows-amd64.exe[`.exe` file] and put in a directory of your preference. -. Click *Search* and type `env` or `environment`. -. Select *Edit environment variables for your account*. -. Select *Path* from the *Variable* section and click *Edit*. -. Click *New* and type the path to the directory with the exe file into the field or click *Browse* and select the directory, and click *OK*. - - -== On MacOS -. Download the Helm binary and add it to your path: -+ -[source,terminal] ----- -# curl -L https://mirror.openshift.com/pub/openshift-v4/clients/helm/latest/helm-darwin-amd64 -o /usr/local/bin/helm ----- - - -. Make the binary file executable: -+ -[source,terminal] ----- -# chmod +x /usr/local/bin/helm ----- - -. Check the installed version: -+ -[source,terminal] ----- -$ helm version ----- -+ -.Example output -[source,terminal] ----- -version.BuildInfo{Version:"v3.0", GitCommit:"b31719aab7963acf4887a1c1e6d5e53378e34d93", GitTreeState:"clean", GoVersion:"go1.13.4"} ----- diff --git a/modules/helm-optimize-central-db-and-pvc.adoc b/modules/helm-optimize-central-db-and-pvc.adoc new file mode 100644 index 000000000000..2ed9aa7da8dc --- /dev/null +++ b/modules/helm-optimize-central-db-and-pvc.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-helm.adoc +:_mod-docs-content-type: REFERENCE +[id="helm-optimize-central-db-and-pvc_{context}"] += Optimizing Central database and PVC + +[role="_abstract"] +When you upgrade to {rh-rhacs-first} 4.0, {product-title-short} creates a PostgreSQL instance called `central-db` with a default Persistent Volume Claims (PVC). Optionally, you can customize `central-db` or PVC configuration. + +Red{nbsp}Hat recommends the following minimum memory and CPU requests: + +[source,yaml] +---- +central: + db: + resources: + requests: + memory: 16Gi + cpu: 8 + limits: + memory: 16Gi + cpu: 8 +---- diff --git a/modules/helm-understanding-helm.adoc b/modules/helm-understanding-helm.adoc deleted file mode 100644 index a324f344d4c9..000000000000 --- a/modules/helm-understanding-helm.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// cli_reference/helm_cli/getting-started-with-helm-on-openshift.adoc -// applications/application_life_cycle_manager/odc-working-with-helm-charts-using-developer-perspective.adoc - -[id="helm-understanding-helm_{context}"] -= Understanding Helm - -Helm is a software package manager that simplifies deployment of applications and services to {product-title} clusters. - -Helm uses a packaging format called _charts_. -A Helm chart is a collection of files that describes the {product-title} resources. - -A running instance of the chart in a cluster is called a _release_. A new release is created every time a chart is installed on the cluster. - -Each time a chart is installed, or a release is upgraded or rolled back, an incremental revision is created. - - -== Key features - -Helm provides the ability to: - -* Search through a large collection of charts stored in the chart repository. -* Modify existing charts. -* Create your own charts with {product-title} or Kubernetes resources. -* Package and share your applications as charts. diff --git a/modules/high-sev-security-policies.adoc b/modules/high-sev-security-policies.adoc new file mode 100644 index 000000000000..3ed8bca25a27 --- /dev/null +++ b/modules/high-sev-security-policies.adoc @@ -0,0 +1,72 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/default-security-policies.adoc +:_mod-docs-content-type: REFERENCE +[id="high-sev-security-policies_{context}"] += High severity security policies + +//// +In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly. + +Be sure to include a line break between the title and the module introduction. +//// + +[role="_abstract"] +The following table lists the default security policies in {product-title} that are of high severity. The policies are organized by lifecycle stage. + +.High severity security policies +[options="header"] +|==== +|Life cycle stage |Name |Description | Status +|Build or Deploy |Fixable Common Vulnerability Scoring System (CVSS) >= 7 |Alerts when deployments with fixable vulnerabilities have a CVSS of at least 7. However, Red{nbsp}Hat recommends that you create policies using Common Vulnerabilities and Exposures (CVE) severity instead of CVSS score. |Disabled +|Build or Deploy |Fixable Severity at least Important |Alerts when deployments with fixable vulnerabilities have a severity rating of at least Important. |Enabled +|Build or Deploy |Rapid Reset: Denial of Service Vulnerability in HTTP/2 Protocol |Alerts on deployments with images containing components that are susceptible to a Denial of Service (DoS) vulnerability for HTTP/2 servers. This addresses a flaw in the handling of multiplexed streams in HTTP/2. A client can rapidly create a request and immediately reset them, which creates extra work for the server while avoiding hitting any server-side limits, resulting in a denial of service attack. To use this policy, consider cloning the policy and adding the `Fixable` policy criteria before enabling it. |Disabled +|Build or Deploy |Secure Shell (ssh) Port Exposed in Image |Alerts when deployments expose port 22, which is commonly reserved for SSH access. |Enabled +|Build or Deploy +|Red{nbsp}Hat Images must be signed by the Red{nbsp}Hat Release Key +a|Alerts when a Red{nbsp}Hat image is not signed by the official link:https://access.redhat.com/security/team/key[Red{nbsp}Hat product signing key, "Release Key 3"]. These alerts apply to images from the following registries and remotes: + +* `registry.redhat.io` +* `registry.access.redhat.com` +* `quay.io/openshift-release-dev/ocp-release` +* `quay.io/openshift-release-dev/ocp-v4.0-art-dev` + +|Disabled +|Deploy |Emergency Deployment Annotation |Alerts when deployments use the emergency annotation, such as "admission.stackrox.io/break-glass":"ticket-1234" to circumvent StackRox Admission controller checks. |Enabled +|Deploy |Environment Variable Contains Secret |Alerts when deployments have environment variables that contain 'SECRET'. |Enabled +|Deploy |Fixable CVSS >= 6 and Privileged |Alerts when deployments run in privileged mode with fixable vulnerabilities that have a CVSS of at least 6. However, Red{nbsp}Hat recommends that you create policies using CVE severity instead of CVSS score. |Disabled by default in version 3.72.0 and later +|Deploy | Privileged Containers with Important and Critical Fixable CVEs |Alerts when containers that run in privileged mode have important or critical fixable vulnerabilities. |Enabled +|Deploy |Secret Mounted as Environment Variable |Alerts when a deployment has a Kubernetes secret that is mounted as an environment variable. |Disabled +|Deploy |Secure Shell (ssh) Port Exposed |Alerts when deployments expose port 22, which is commonly reserved for SSH access. |Enabled +|Runtime |Cryptocurrency Mining Process Execution |Spawns the crypto-currency mining process. |Enabled +|Runtime |iptables Execution |Detects when someone runs iptables, which is a deprecated way of managing network states in containers. |Enabled +|Runtime |Kubernetes Actions: Exec into Pod |Alerts when the Kubernetes API receives a request to run a command in a container. |Enabled +|Runtime |Linux Group Add Execution |Detects when someone runs the addgroup or groupadd binary to add a Linux group. |Enabled +|Runtime |Linux User Add Execution |Detects when someone runs the useradd or adduser binary to add a Linux user. |Enabled +|Runtime |Login Binaries |Indicates when someone tries to log in. |Disabled +|Runtime |Network Management Execution |Detects when someone runs binary files that can manipulate network configuration and management. |Enabled +|Runtime |nmap Execution |Alerts when someone starts the nmap process in a container during run time. |Enabled +|Runtime |OpenShift: Kubeadmin Secret Accessed |Alerts when someone accesses the kubeadmin secret. |Enabled +|Runtime |Password Binaries |Indicates when someone attempts to change a password. |Disabled +|Runtime |Process Targeting Cluster Kubelet Endpoint |Detects the misuse of the healthz, kubelet API, or heapster endpoint. |Enabled +|Runtime |Process Targeting Cluster Kubernetes Docker Stats Endpoint |Detects the misuse of the Kubernetes docker stats endpoint. |Enabled +|Runtime |Process Targeting Kubernetes Service Endpoint |Detects the misuse of the Kubernetes Service API endpoint. |Enabled +|Runtime |Process with UID 0 |Alerts when deployments contain processes that run with UID 0. |Disabled +|Runtime |Secure Shell Server (sshd) Execution |Detects containers that run the SSH daemon. |Enabled +|Runtime |SetUID Processes |Use setuid binary files, which permit people to run certain programs with escalated privileges. |Disabled +|Runtime |Shadow File Modification |Indicates when someone tries to modify shadow files. |Disabled +|Runtime |Shell Spawned by Java Application |Detects when a shell, such as bash, csh, sh, or zsh, is run as a subprocess of a Java application. |Enabled +|Runtime |Unauthorized Network Flow |Generates a violation for any network flows that fall outside of the baselines of the "alert on anomalous violations" setting. |Enabled +|Runtime |Unauthorized Processed Execution |Generates a violation for any process execution that is not explicitly allowed by a locked process baseline for a container specification in a Kubernetes deployment. |Enabled +|==== + + + +//// +[role="_additional-resources"] +.Additional resources + +* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros. +* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +//// diff --git a/modules/how-huge-pages-are-consumed-by-apps.adoc b/modules/how-huge-pages-are-consumed-by-apps.adoc deleted file mode 100644 index 375f0d616d3b..000000000000 --- a/modules/how-huge-pages-are-consumed-by-apps.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="how-huge-pages-are-consumed-by-apps_{context}"] -= How huge pages are consumed by apps - -Nodes must pre-allocate huge pages in order for the node to report its huge page -capacity. A node can only pre-allocate huge pages for a single size. - -Huge pages can be consumed through container-level resource requirements using the -resource name `hugepages-<size>`, where size is the most compact binary -notation using integer values supported on a particular node. For example, if a -node supports 2048KiB page sizes, it exposes a schedulable resource -`hugepages-2Mi`. Unlike CPU or memory, huge pages do not support over-commitment. - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - generateName: hugepages-volume- -spec: - containers: - - securityContext: - privileged: true - image: rhel7:latest - command: - - sleep - - inf - name: example - volumeMounts: - - mountPath: /dev/hugepages - name: hugepage - resources: - limits: - hugepages-2Mi: 100Mi <1> - memory: "1Gi" - cpu: "1" - volumes: - - name: hugepage - emptyDir: - medium: HugePages ----- -<1> Specify the amount of memory for `hugepages` as the exact amount to be -allocated. Do not specify this value as the amount of memory for `hugepages` -multiplied by the size of the page. For example, given a huge page size of 2MB, -if you want to use 100MB of huge-page-backed RAM for your application, then you -would allocate 50 huge pages. {product-title} handles the math for you. As in -the above example, you can specify `100MB` directly. - -*Allocating huge pages of a specific size* - -Some platforms support multiple huge page sizes. To allocate huge pages of a -specific size, precede the huge pages boot command parameters with a huge page -size selection parameter `hugepagesz=<size>`. The `<size>` value must be -specified in bytes with an optional scale suffix [`kKmMgG`]. The default huge -page size can be defined with the `default_hugepagesz=<size>` boot parameter. - -*Huge page requirements* - -* Huge page requests must equal the limits. This is the default if limits are -specified, but requests are not. - -* Huge pages are isolated at a pod scope. Container isolation is planned in a -future iteration. - -* `EmptyDir` volumes backed by huge pages must not consume more huge page memory -than the pod request. - -* Applications that consume huge pages via `shmget()` with `SHM_HUGETLB` must run -with a supplemental group that matches *_proc/sys/vm/hugetlb_shm_group_*. - -.Additional resources - -* https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/performance_tuning_guide/sect-red_hat_enterprise_linux-performance_tuning_guide-configuring_transparent_huge_pages[Configuring Transparent Huge Pages] diff --git a/modules/how-to-plan-your-environment-according-to-application-requirements.adoc b/modules/how-to-plan-your-environment-according-to-application-requirements.adoc deleted file mode 100644 index 9007a38f8290..000000000000 --- a/modules/how-to-plan-your-environment-according-to-application-requirements.adoc +++ /dev/null @@ -1,186 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc - -[id="how-to-plan-according-to-application-requirements_{context}"] -= How to plan your environment according to application requirements - -Consider an example application environment: - -[options="header",cols="5"] -|=== -|Pod type |Pod quantity |Max memory |CPU cores |Persistent storage - -|apache -|100 -|500 MB -|0.5 -|1 GB - -|node.js -|200 -|1 GB -|1 -|1 GB - -|postgresql -|100 -|1 GB -|2 -|10 GB - -|JBoss EAP -|100 -|1 GB -|1 -|1 GB -|=== - -Extrapolated requirements: 550 CPU cores, 450GB RAM, and 1.4TB storage. - -Instance size for nodes can be modulated up or down, depending on your -preference. Nodes are often resource overcommitted. In this deployment -scenario, you can choose to run additional smaller nodes or fewer larger nodes -to provide the same amount of resources. Factors such as operational agility and -cost-per-instance should be considered. - -[options="header",cols="4"] -|=== -|Node type |Quantity |CPUs |RAM (GB) - -|Nodes (option 1) -|100 -|4 -|16 - -|Nodes (option 2) -|50 -|8 -|32 - -|Nodes (option 3) -|25 -|16 -|64 -|=== - -Some applications lend themselves well to overcommitted environments, and some -do not. Most Java applications and applications that use huge pages are examples -of applications that would not allow for overcommitment. That memory can not be -used for other applications. In the example above, the environment would be -roughly 30 percent overcommitted, a common ratio. - -The application pods can access a service either by using environment variables or DNS. -If using environment variables, for each active service the variables are injected by the -kubelet when a pod is run on a node. A cluster-aware DNS server watches the Kubernetes API -for new services and creates a set of DNS records for each one. If DNS is enabled throughout -your cluster, then all pods should automatically be able to resolve services by their DNS name. -Service discovery using DNS can be used in case you must go beyond 5000 services. When using -environment variables for service discovery, the argument list exceeds the allowed length after -5000 services in a namespace, then the pods and deployments will start failing. Disable the service -links in the deployment's service specification file to overcome this: - -[source,yaml] ----- - --- - Kind: Template - apiVersion: v1 - metadata: - name: deploymentConfigTemplate - creationTimestamp: - annotations: - description: This template will create a deploymentConfig with 1 replica, 4 env vars and a service. - tags: '' - objects: - - kind: DeploymentConfig - apiVersion: v1 - metadata: - name: deploymentconfig${IDENTIFIER} - spec: - template: - metadata: - labels: - name: replicationcontroller${IDENTIFIER} - spec: - enableServiceLinks: false - containers: - - name: pause${IDENTIFIER} - image: "${IMAGE}" - ports: - - containerPort: 8080 - protocol: TCP - env: - - name: ENVVAR1_${IDENTIFIER} - value: "${ENV_VALUE}" - - name: ENVVAR2_${IDENTIFIER} - value: "${ENV_VALUE}" - - name: ENVVAR3_${IDENTIFIER} - value: "${ENV_VALUE}" - - name: ENVVAR4_${IDENTIFIER} - value: "${ENV_VALUE}" - resources: {} - imagePullPolicy: IfNotPresent - capabilities: {} - securityContext: - capabilities: {} - privileged: false - restartPolicy: Always - serviceAccount: '' - replicas: 1 - selector: - name: replicationcontroller${IDENTIFIER} - triggers: - - type: ConfigChange - strategy: - type: Rolling - - kind: Service - apiVersion: v1 - metadata: - name: service${IDENTIFIER} - spec: - selector: - name: replicationcontroller${IDENTIFIER} - ports: - - name: serviceport${IDENTIFIER} - protocol: TCP - port: 80 - targetPort: 8080 - portalIP: '' - type: ClusterIP - sessionAffinity: None - status: - loadBalancer: {} - parameters: - - name: IDENTIFIER - description: Number to append to the name of resources - value: '1' - required: true - - name: IMAGE - description: Image to use for deploymentConfig - value: gcr.io/google-containers/pause-amd64:3.0 - required: false - - name: ENV_VALUE - description: Value to use for environment variables - generate: expression - from: "[A-Za-z0-9]{255}" - required: false - labels: - template: deploymentConfigTemplate ----- - -The number of application pods that can run in a namespace is dependent on the number of services and the -length of the service name when the environment variables are used for service discovery. `ARG_MAX` on the system -defines the maximum argument length for a new process and it is set to `2097152 KiB` by default. The Kubelet injects -environment variables in to each pod scheduled to run in the namespace including: - -* `<SERVICE_NAME>_SERVICE_HOST=<IP>` -* `<SERVICE_NAME>_SERVICE_PORT=<PORT>` -* `<SERVICE_NAME>_PORT=tcp://<IP>:<PORT>` -* `<SERVICE_NAME>_PORT_<PORT>_TCP=tcp://<IP>:<PORT>` -* `<SERVICE_NAME>_PORT_<PORT>_TCP_PROTO=tcp` -* `<SERVICE_NAME>_PORT_<PORT>_TCP_PORT=<PORT>` -* `<SERVICE_NAME>_PORT_<PORT>_TCP_ADDR=<ADDR>` - -The pods in the namespace will start to fail if the argument length exceeds the allowed value and the number of -characters in a service name impacts it. For example, in a namespace with 5000 services, the limit on the service name -is 33 characters, which enables you to run 5000 pods in the namespace. diff --git a/modules/how-to-plan-your-environment-according-to-cluster-maximums.adoc b/modules/how-to-plan-your-environment-according-to-cluster-maximums.adoc deleted file mode 100644 index 60eeea66a1f1..000000000000 --- a/modules/how-to-plan-your-environment-according-to-cluster-maximums.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc - -[id="how-to-plan-according-to-cluster-maximums_{context}"] -= How to plan your environment according to tested cluster maximums - -[IMPORTANT] -==== -Oversubscribing the physical resources on a node affects resource guarantees the Kubernetes scheduler makes during pod placement. Learn what measures you can take to avoid memory swapping. - -Some of the tested maximums are stretched only in a single dimension. They will vary when many objects are running on the cluster. - -The numbers noted in this documentation are based on Red Hat's test methodology, setup, configuration, and tunings. These numbers can vary based on your own individual setup and environments. -==== - -While planning your environment, determine how many pods are expected to fit per node: - ----- -required pods per cluster / pods per node = total number of nodes needed ----- - -The current maximum number of pods per node is 250. However, the number of pods that fit on a node is dependent on the application itself. Consider the application's memory, CPU, and storage requirements, as described in _How to plan your environment according to application requirements_. - -.Example scenario - -If you want to scope your cluster for 2200 pods per cluster, you would need at least five nodes, assuming that there are 500 maximum pods per node: - ----- -2200 / 500 = 4.4 ----- - -If you increase the number of nodes to 20, then the pod distribution changes to 110 pods per node: - ----- -2200 / 20 = 110 ----- - -Where: - ----- -required pods per cluster / total number of nodes = expected pods per node ----- diff --git a/modules/identify-container-image-layer-that-introduces-vulnerabilities.adoc b/modules/identify-container-image-layer-that-introduces-vulnerabilities.adoc new file mode 100644 index 000000000000..884d0139001a --- /dev/null +++ b/modules/identify-container-image-layer-that-introduces-vulnerabilities.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="identify-container-image-layer-that-introduces-vulnerabilities_{context}"] += Identifying the container image layer that introduces vulnerabilities by using the dashboard + +[role="_abstract"] +You can use the *Vulnerability Management* dashboard to identify vulnerable components and the image layer they appear in. + +.Procedure + +. Go to the {product-title-short} portal and click *Vulnerability Management* -> *Dashboard* from the navigation menu. +. Select an image from either the *Top Riskiest Images* widget or click the *Images* button at the top of the dashboard and select an image. +. In the *Image* details view, next to *Dockerfile*, select the expand icon to see a summary of image components. +. Select the expand icon for specific components to get more details about the CVEs affecting the selected component. diff --git a/modules/identify-dockerfile-line-component-cve.adoc b/modules/identify-dockerfile-line-component-cve.adoc new file mode 100644 index 000000000000..2a805fe1e552 --- /dev/null +++ b/modules/identify-dockerfile-line-component-cve.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="identify-dockerfile-line-component-cve_{context}"] += Identifying Dockerfile lines in images that introduced components with CVEs + +[role="_abstract"] +You can identify specific Dockerfile lines in an image that introduced components with CVEs. + +.Procedure + +To view a problematic line: + +. In the {product-title-short} portal, click *Vulnerability Management* -> *Results*. +. Click *User Workloads*. +. Click the tab to view the type of CVEs. The following tabs are available: +* *Observed* +* *Deferred* +* *False positives* +. In the list of CVEs, click the CVE name to open the page containing the CVE details. The *Affected components* column lists the components that include the CVE. +. Expand the CVE to display additional information, including the Dockerfile line that introduced the component. + + diff --git a/modules/identify-operating-system-of-the-base-image.adoc b/modules/identify-operating-system-of-the-base-image.adoc new file mode 100644 index 000000000000..2845b027f6b6 --- /dev/null +++ b/modules/identify-operating-system-of-the-base-image.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="identify-operating-system-of-the-base-image_{context}"] += Identifying the operating system of the base image by using the dashboard + +[role="_abstract"] +Use the *Vulnerability Management* view to identify the operating system of the base image. + +.Procedure + +. Go to the {product-title-short} portal and click *Vulnerability Management* -> *Dashboard* from the navigation menu. +. From the *Vulnerability Management* view header, select *Images*. +. View the base operating system (OS) and OS version for all images under the *Image OS* column. +//TODO: Add link to local page filtering +. Select an image to view its details. +The base operating system is also available under the *Image Summary* -> *Details and Metadata* section. + +[NOTE] +==== +{product-title} lists the *Image OS* as *unknown* when either: + +* The operating system information is not available, or +* If the image scanner in use does not provide this information. + +Docker Trusted Registry, Google Container Registry, and Anchore do not provide this information. +==== diff --git a/modules/identify-top-risky-objects.adoc b/modules/identify-top-risky-objects.adoc new file mode 100644 index 000000000000..82385a09b547 --- /dev/null +++ b/modules/identify-top-risky-objects.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="top-risky-objects_{context}"] += Identifying top risky objects by using the dashboard + +Use the *Vulnerability Management* view for identifying the top risky objects in your environment. +The *Top Risky* widget displays information about the top risky images, deployments, clusters, and namespaces in your environment. +The risk is determined based on the number of vulnerabilities and their CVSS scores. + +.Procedure + +. Go to the {product-title-short} portal and click *Vulnerability Management* -> *Dashboard* from the navigation menu. +. Select the *Top Risky* widget header to choose between riskiest images, deployments, clusters, and namespaces. ++ +The small circles on the chart represent the chosen object (image, deployment, cluster, namespace). +Hover over the circles to see an overview of the object they represent. +And select a circle to view detailed information about the selected object, its related entities, and the connections between them. ++ +For example, if you are viewing *Top Risky Deployments by CVE Count and CVSS score*, each circle on the chart represents a deployment. + +** When you hover over a deployment, you see an overview of the deployment, which includes deployment name, name of the cluster and namespace, severity, risk priority, CVSS, and CVE count (including fixable). +** When you select a deployment, the *Deployment* view opens for the selected deployment. +The *Deployment* view shows in-depth details of the deployment and includes information about policy violations, common vulnerabilities, CVEs, and riskiest images for that deployment. + +. Select *View All* on the widget header to view all objects of the chosen type. +For example, if you chose *Top Risky Deployments by CVE Count and CVSS score*, you can select *View All* to view detailed information about all deployments in your infrastructure. diff --git a/modules/identify-vulnerabilities-in-nodes.adoc b/modules/identify-vulnerabilities-in-nodes.adoc new file mode 100644 index 000000000000..e8a580fc8885 --- /dev/null +++ b/modules/identify-vulnerabilities-in-nodes.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="identify-vulnerabilities-in-nodes_{context}"] += Identifying vulnerabilities in nodes by using the dashboard + +You can use the *Vulnerability Management* view to identify vulnerabilities in your nodes. +The identified vulnerabilities include vulnerabilities in core Kubernetes components and container runtimes such as Docker, CRI-O, runC, and containerd. For more information on operating systems that {product-title-short} can scan, see "Supported operating systems". + +.Procedure +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Dashboard*. +. Select *Nodes* on the header to view a list of all the CVEs affecting your nodes. +. Select a node from the list to view details of all CVEs affecting that node. +.. When you select a node, the *Node* details panel opens for the selected node. +The *Node* view shows in-depth details of the node and includes information about CVEs by CVSS score and fixable CVEs for that node. +.. Select *View All* on the *CVEs by CVSS score* widget header to view a list of all the CVEs in the selected node. +You can also filter the list of CVEs. +//TODO: link to Local page filtering +.. To export the fixable CVEs as a CSV file, select *Export as CSV* under the *Node Findings* section. diff --git a/modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc b/modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc new file mode 100644 index 000000000000..12bbf8e3e0e6 --- /dev/null +++ b/modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc @@ -0,0 +1,12 @@ + +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: CONCEPT +[id="identifying-the-differences-in-allowed-connections-between-project-versions_{context}"] += Identifying the differences in allowed connections between project versions + +The `roxctl netpol connectivity diff` command identifies differences in allowed connections between two project versions. It analyzes network policy, Admin Network Policy (ANP), and Baseline Admin Network Policy (BANP) manifests in each version's directory. This analysis provides a text-based report of the differences. It also includes the impact of ANP and BANP resources, giving you a complete view of policy changes across cluster scopes. + +You can view connectivity difference reports in a variety of output formats, including `text`, `md`, `dot`, and `csv`. diff --git a/modules/identity-provider-about-basic-authentication.adoc b/modules/identity-provider-about-basic-authentication.adoc deleted file mode 100644 index 74ecdeeef078..000000000000 --- a/modules/identity-provider-about-basic-authentication.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc - -[id="identity-provider-about-basic-authentication_{context}"] -= About basic authentication - -Basic authentication is a generic back-end integration mechanism that allows -users to log in to {product-title} with credentials validated against a remote -identity provider. - -Because basic authentication is generic, you can use this identity -provider for advanced authentication configurations. - -[IMPORTANT] -==== -Basic authentication must use an HTTPS connection to the remote server to -prevent potential snooping of the user ID and password and man-in-the-middle -attacks. -==== - -With basic authentication configured, users send their user name -and password to {product-title}, which then validates those credentials against -a remote server by making a server-to-server request, passing the credentials as -a basic authentication header. This requires users to send their credentials to -{product-title} during login. - -[NOTE] -==== -This only works for user name/password login mechanisms, and {product-title} must -be able to make network requests to the remote authentication server. -==== - -User names and passwords are validated against a remote URL that is protected -by basic authentication and returns JSON. - -A `401` response indicates failed authentication. - -A non-`200` status, or the presence of a non-empty "error" key, indicates an -error: - -[source,terminal] ----- -{"error":"Error message"} ----- - -A `200` status with a `sub` (subject) key indicates success: - -[source,terminal] ----- -{"sub":"userid"} <1> ----- -<1> The subject must be unique to the authenticated user and must not be able to -be modified. - -A successful response can optionally provide additional data, such as: - -* A display name using the `name` key. For example: -+ -[source,terminal] ----- -{"sub":"userid", "name": "User Name", ...} ----- -+ -* An email address using the `email` key. For example: -+ -[source,terminal] ----- -{"sub":"userid", "email":"user@example.com", ...} ----- -+ -* A preferred user name using the `preferred_username` key. This is useful when -the unique, unchangeable subject is a database key or UID, and a more -human-readable name exists. This is used as a hint when provisioning the -{product-title} user for the authenticated identity. For example: -+ -[source,terminal] ----- -{"sub":"014fbff9a07c", "preferred_username":"bob", ...} ----- diff --git a/modules/identity-provider-about-ldap.adoc b/modules/identity-provider-about-ldap.adoc deleted file mode 100644 index 7390ab36e4f1..000000000000 --- a/modules/identity-provider-about-ldap.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-ldap-identity-provider.adoc - -[id="identity-provider-about-ldap_{context}"] -= About LDAP authentication - -During authentication, the LDAP directory is searched for an entry that matches -the provided user name. If a single unique match is found, a simple bind is -attempted using the distinguished name (DN) of the entry plus the provided -password. - -These are the steps taken: - -. Generate a search filter by combining the attribute and filter in the -configured `url` with the user-provided user name. -. Search the directory using the generated filter. If the search does not return -exactly one entry, deny access. -. Attempt to bind to the LDAP server using the DN of the entry retrieved from -the search, and the user-provided password. -. If the bind is unsuccessful, deny access. -. If the bind is successful, build an identity using the configured attributes -as the identity, email address, display name, and preferred user name. - -The configured `url` is an RFC 2255 URL, which specifies the LDAP host and -search parameters to use. The syntax of the URL is: - ----- -ldap://host:port/basedn?attribute?scope?filter ----- - -For this URL: - -[cols="2a,8a",options="header"] -|=== -|URL component | Description -.^|`ldap` | For regular LDAP, use the string `ldap`. For secure LDAP -(LDAPS), use `ldaps` instead. -.^|`host:port` | The name and port of the LDAP server. Defaults to -`localhost:389` for ldap and `localhost:636` for LDAPS. -.^|`basedn` | The DN of the branch of the directory where all searches should -start from. At the very least, this must be the top of your directory tree, but -it could also specify a subtree in the directory. -.^|`attribute` | The attribute to search for. Although RFC 2255 allows a -comma-separated list of attributes, only the first attribute will be used, no -matter how many are provided. If no attributes are provided, the default is to -use `uid`. It is recommended to choose an attribute that will be unique across -all entries in the subtree you will be using. -.^|`scope` | The scope of the search. Can be either `one` or `sub`. -If the scope is not provided, the default is to use a scope of `sub`. -.^|`filter` | A valid LDAP search filter. If not provided, defaults to -`(objectClass=*)` -|=== - -When doing searches, the attribute, filter, and provided user name are combined -to create a search filter that looks like: - ----- -(&(<filter>)(<attribute>=<username>)) ----- - -For example, consider a URL of: - ----- -ldap://ldap.example.com/o=Acme?cn?sub?(enabled=true) ----- - -When a client attempts to connect using a user name of `bob`, the resulting -search filter will be `(&(enabled=true)(cn=bob))`. - -If the LDAP directory requires authentication to search, specify a `bindDN` and -`bindPassword` to use to perform the entry search. diff --git a/modules/identity-provider-about-request-header.adoc b/modules/identity-provider-about-request-header.adoc deleted file mode 100644 index af57a2406e00..000000000000 --- a/modules/identity-provider-about-request-header.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc - -[id="identity-provider-about-request-header_{context}"] -= About request header authentication - -A request header identity provider identifies users from request -header values, such as `X-Remote-User`. It is typically used in combination with -an authenticating proxy, which sets the request header value. - -[NOTE] -==== -You can also use the request header identity provider for advanced configurations -such as the community-supported link:https://github.com/openshift/request-header-saml-service-provider[SAML authentication]. -Note that this solution is not supported by Red Hat. -==== - -For users to authenticate using this identity provider, they must access -`https://_<namespace_route>_/oauth/authorize` (and subpaths) via an authenticating proxy. -To accomplish this, configure the OAuth server to redirect unauthenticated -requests for OAuth tokens to the proxy endpoint that proxies to -`https://_<namespace_route>_/oauth/authorize`. - -To redirect unauthenticated requests from clients expecting browser-based login flows: - -* Set the `provider.loginURL` parameter to the authenticating proxy URL that -will authenticate interactive clients and then proxy the request to -`https://_<namespace_route>_/oauth/authorize`. - -To redirect unauthenticated requests from clients expecting `WWW-Authenticate` challenges: - -* Set the `provider.challengeURL` parameter to the authenticating proxy URL that -will authenticate clients expecting `WWW-Authenticate` challenges and then proxy -the request to `https://_<namespace_route>_/oauth/authorize`. - -The `provider.challengeURL` and `provider.loginURL` parameters can include -the following tokens in the query portion of the URL: - -* `${url}` is replaced with the current URL, escaped to be safe in a query parameter. -+ -For example: [x-]`https://www.example.com/sso-login?then=${url}` - -* `${query}` is replaced with the current query string, unescaped. -+ -For example: [x-]`https://www.example.com/auth-proxy/oauth/authorize?${query}` - -[IMPORTANT] -==== -As of {product-title} 4.1, your proxy must support mutual TLS. -==== - -[id="sspi-windows_{context}"] -== SSPI connection support on Microsoft Windows - -ifdef::openshift-enterprise,openshift-webscale[] - -[IMPORTANT] -==== -Using SSPI connection support on Microsoft Windows is a Technology Preview feature. -Technology Preview features are not supported with Red Hat production service -level agreements (SLAs), might not be functionally complete, and Red Hat does -not recommend to use them for production. These features provide early access to -upcoming product features, enabling customers to test functionality and provide -feedback during the development process. - -For more information on Red Hat Technology Preview features support scope, see -https://access.redhat.com/support/offerings/techpreview/. -==== - -endif::[] - -The OpenShift CLI (`oc`) supports the Security Support Provider Interface (SSPI) to allow for SSO -flows on Microsft Windows. If you use the request header identity provider with a -GSSAPI-enabled proxy to connect an Active Directory server to {product-title}, -users can automatically authenticate to {product-title} by using the `oc` command -line interface from a domain-joined Microsoft Windows computer. diff --git a/modules/identity-provider-add.adoc b/modules/identity-provider-add.adoc deleted file mode 100644 index de0f338da849..000000000000 --- a/modules/identity-provider-add.adoc +++ /dev/null @@ -1,108 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-allow-all-identity-provider.adoc -// * authentication/identity_providers/configuring-deny-all-identity-provider.adoc -// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc -// * authentication/identity_providers/configuring-keystone-identity-provider.adoc -// * authentication/identity_providers/configuring-ldap-identity-provider.adoc -// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc -// * authentication/identity_providers/configuring-github-identity-provider.adoc -// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc -// * authentication/identity_providers/configuring-google-identity-provider.adoc -// * authentication/identity_providers/configuring-oidc-identity-provider.adoc - -// GitHub and Google IDPs do not support username/password login commands -ifeval::["{context}" == "configuring-github-identity-provider"] -:no-username-password-login: -endif::[] -ifeval::["{context}" == "configuring-google-identity-provider"] -:no-username-password-login: -endif::[] -// Only some OIDC IDPs support username/password login commands -ifeval::["{context}" == "configuring-oidc-identity-provider"] -:no-username-password-login: -:oidc: -endif::[] - -[id="add-identity-provider_{context}"] -= Adding an identity provider to your clusters - -After you install your cluster, add an identity provider to it so your -users can authenticate. - -.Prerequisites - -* Create an {product-title} cluster. -* Create the custom resource (CR) for your identity providers. -* You must be logged in as an administrator. - -.Procedure - -. Apply the defined CR: -+ -[source,terminal] ----- -$ oc apply -f </path/to/CR> ----- -+ -[NOTE] -==== -If a CR does not exist, `oc apply` creates a new CR and might trigger the following warning: `Warning: oc apply should be used on resources created by either oc create --save-config or oc apply`. In this case you can safely ignore this warning. -==== - -ifndef::no-username-password-login[] -. Log in to the cluster as a user from your identity provider, entering the -password when prompted. -+ -[source,terminal] ----- -$ oc login -u <username> ----- -endif::no-username-password-login[] - -ifdef::no-username-password-login[] - -. Obtain a token from the OAuth server. -+ -As long as the `kubeadmin` user has been removed, the `oc login` command provides instructions on how to access a web page where you can retrieve the token. -+ -You can also access this page from the web console by navigating to *(?) Help* -> *Command Line Tools* -> *Copy Login Command*. - -. Log in to the cluster, passing in the token to authenticate. -+ -[source,terminal] ----- -$ oc login --token=<token> ----- -+ -[NOTE] -==== -ifdef::oidc[] -Some OpenID Connect identity providers support logging in with a user name and password. -endif::oidc[] - -ifndef::oidc[] -This identity provider does not support logging in with a user name and password. -endif::oidc[] -==== -endif::no-username-password-login[] - -. Confirm that the user logged in successfully, and display the user name. -+ -[source,terminal] ----- -$ oc whoami ----- - -// Undefining attributes -ifeval::["{context}" == "configuring-google-identity-provider"] -:!no-username-password-login: -endif::[] -ifeval::["{context}" == "configuring-oidc-identity-provider"] -:!no-username-password-login: -:!oidc: -endif::[] -ifeval::["{context}" == "configuring-github-identity-provider"] -:!no-username-password-login: -endif::[] diff --git a/modules/identity-provider-apache-custom-proxy-configuration.adoc b/modules/identity-provider-apache-custom-proxy-configuration.adoc deleted file mode 100644 index 843f50171681..000000000000 --- a/modules/identity-provider-apache-custom-proxy-configuration.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc - -[id="identity-provider-apache-custom-proxy-configuration_{context}"] -= Custom proxy configuration - -Using the `mod_auth_gssapi` module is a popular way to configure the Apache -authentication proxy using the request header identity provider; however, it is -not required. Other proxies can easily be used if the following requirements are -met: - -* Block the `X-Remote-User` header from client requests to prevent spoofing. -* Enforce client certificate authentication in the `RequestHeaderIdentityProvider` -configuration. -* Require the `X-Csrf-Token` header be set for all authentication requests using -the challenge flow. -* Make sure only the `/oauth/authorize` endpoint and its subpaths are proxied; -redirects must be rewritten to allow the backend server to send the client to -the correct location. -* The URL that proxies to `\https://<namespace_route>/oauth/authorize` must end -with `/authorize` with no trailing slash. For example, `\https://proxy.example.com/login-proxy/authorize?...` -must proxy to `\https://<namespace_route>/oauth/authorize?...`. -+ -* Subpaths of the URL that proxies to `\https://<namespace_route>/oauth/authorize` -must proxy to subpaths of `\https://<namespace_route>/oauth/authorize`. For -example, `\https://proxy.example.com/login-proxy/authorize/approve?...` must -proxy to `\https://<namespace_route>/oauth/authorize/approve?...`. - -[NOTE] -==== -The `\https://<namespace_route>` address is the route to the OAuth server and -can be obtained by running `oc get route -n openshift-authentication`. -==== diff --git a/modules/identity-provider-basic-authentication-CR.adoc b/modules/identity-provider-basic-authentication-CR.adoc deleted file mode 100644 index dd184c921558..000000000000 --- a/modules/identity-provider-basic-authentication-CR.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc - -[id="identity-provider-basic-authentication-CR_{context}"] -= Sample basic authentication CR - -The following custom resource (CR) shows the parameters and acceptable values for a -basic authentication identity provider. - -.Basic authentication CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: basicidp <1> - mappingMethod: claim <2> - type: BasicAuth - basicAuth: - url: https://www.example.com/remote-idp <3> - ca: <4> - name: ca-config-map - tlsClientCert: <5> - name: client-cert-secret - tlsClientKey: <6> - name: client-key-secret ----- -<1> This provider name is prefixed to the returned user ID to form an identity -name. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> URL accepting credentials in Basic authentication headers. -<4> Optional: Reference to an {product-title} `ConfigMap` object containing the -PEM-encoded certificate authority bundle to use in validating server -certificates for the configured URL. -<5> Optional: Reference to an {product-title} `Secret` object containing the client -certificate to present when making requests to the configured URL. -<6> Reference to an {product-title} `Secret` object containing the key for the -client certificate. Required if `tlsClientCert` is specified. diff --git a/modules/identity-provider-basic-authentication-troubleshooting.adoc b/modules/identity-provider-basic-authentication-troubleshooting.adoc deleted file mode 100644 index b8b3856043d0..000000000000 --- a/modules/identity-provider-basic-authentication-troubleshooting.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc - -[id="identity-provider-basic-authentication-troubleshooting_{context}"] -= Basic authentication troubleshooting - -The most common issue relates to network connectivity to the backend server. For -simple debugging, run `curl` commands on the master. To test for a successful -login, replace the `<user>` and `<password>` in the following example command -with valid credentials. To test an invalid login, replace them with false -credentials. - -[source,terminal] ----- -$ curl --cacert /path/to/ca.crt --cert /path/to/client.crt --key /path/to/client.key -u <user>:<password> -v https://www.example.com/remote-idp ----- - -*Successful responses* - -A `200` status with a `sub` (subject) key indicates success: - -[source,terminal] ----- -{"sub":"userid"} ----- -The subject must be unique to the authenticated user, and must not be able to -be modified. - -A successful response can optionally provide additional data, such as: - -* A display name using the `name` key: -+ -[source,terminal] ----- -{"sub":"userid", "name": "User Name", ...} ----- -* An email address using the `email` key: -+ -[source,terminal] ----- -{"sub":"userid", "email":"user@example.com", ...} ----- -* A preferred user name using the `preferred_username` key: -+ -[source,terminal] ----- -{"sub":"014fbff9a07c", "preferred_username":"bob", ...} ----- -+ -The `preferred_username` key is useful when -the unique, unchangeable subject is a database key or UID, and a more -human-readable name exists. This is used as a hint when provisioning the -{product-title} user for the authenticated identity. - -*Failed responses* - -- A `401` response indicates failed authentication. -- A non-`200` status or the presence of a non-empty "error" key indicates an -error: `{"error":"Error message"}` diff --git a/modules/identity-provider-config-map.adoc b/modules/identity-provider-config-map.adoc deleted file mode 100644 index 1fd39625a44e..000000000000 --- a/modules/identity-provider-config-map.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc -// * authentication/identity_providers/configuring-github-identity-provider.adoc -// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc -// * authentication/identity_providers/configuring-ldap-identity-provider.adoc -// * authentication/identity_providers/configuring-oidc-identity-provider.adoc -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc - -ifeval::["{context}" == "configuring-github-identity-provider"] -:github: -endif::[] - -[id="identity-provider-creating-configmap_{context}"] -= Creating a config map - -Identity providers use {product-title} `ConfigMap` objects in the `openshift-config` -namespace to contain the certificate authority bundle. These are primarily -used to contain certificate bundles needed by the identity provider. - -ifdef::github[] -[NOTE] -==== -This procedure is only required for GitHub Enterprise. -==== -endif::github[] - -.Procedure - -* Define an {product-title} `ConfigMap` object containing the -certificate authority by using the following command. The certificate -authority must be stored in the `ca.crt` key of the `ConfigMap` object. -+ -[source,terminal] ----- -$ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config ----- - -// Undefining attributes -ifeval::["{context}" == "configuring-google-identity-provider"] -:!github: -endif::[] diff --git a/modules/identity-provider-configuring-apache-request-header.adoc b/modules/identity-provider-configuring-apache-request-header.adoc deleted file mode 100644 index 5fe251286eda..000000000000 --- a/modules/identity-provider-configuring-apache-request-header.adoc +++ /dev/null @@ -1,244 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc - -[id="identity-provider-configuring-apache-request-header_{context}"] -= Configuring Apache authentication using request header - -This example uses the `mod_auth_gssapi` module to configure an Apache -authentication proxy using the request header identity provider. - -.Prerequisites - -* Obtain the `mod_auth_gssapi` module from the -link:https://access.redhat.com/solutions/392003[Optional channel]. -You must have the following packages installed on your local machine: -+ -** `httpd` -** `mod_ssl` -** `mod_session` -** `apr-util-openssl` -** `mod_auth_gssapi` - -* Generate a CA for validating requests that submit the trusted header. Define -an {product-title} `ConfigMap` object containing the CA. This is done by running: -+ -[source,terminal] ----- -$ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config ----- -+ -The CA must be stored in the `ca.crt` key of the `ConfigMap` object. - -* Generate a client certificate for the proxy. You can generate this certificate -by using any x509 certificate tooling. The client certificate must be signed by -the CA you generated for validating requests that submit the trusted header. - -* Create the custom resource (CR) for your identity providers. - -.Procedure - -This proxy uses a client certificate to connect to the OAuth server, which -is configured to trust the `X-Remote-User` header. - -. Create the certificate for the Apache configuration. The certificate that you -specify as the `SSLProxyMachineCertificateFile` parameter value is the proxy's -client certificate that is used to authenticate the proxy to the server. It must -use `TLS Web Client Authentication` as the extended key type. - -. Create the Apache configuration. Use the following template to provide your -required settings and values: -+ -[IMPORTANT] -==== -Carefully review the template and customize its contents to fit your -environment. -==== -+ ----- -LoadModule request_module modules/mod_request.so -LoadModule auth_gssapi_module modules/mod_auth_gssapi.so -# Some Apache configurations might require these modules. -# LoadModule auth_form_module modules/mod_auth_form.so -# LoadModule session_module modules/mod_session.so - -# Nothing needs to be served over HTTP. This virtual host simply redirects to -# HTTPS. -<VirtualHost *:80> - DocumentRoot /var/www/html - RewriteEngine On - RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R,L] -</VirtualHost> - -<VirtualHost *:443> - # This needs to match the certificates you generated. See the CN and X509v3 - # Subject Alternative Name in the output of: - # openssl x509 -text -in /etc/pki/tls/certs/localhost.crt - ServerName www.example.com - - DocumentRoot /var/www/html - SSLEngine on - SSLCertificateFile /etc/pki/tls/certs/localhost.crt - SSLCertificateKeyFile /etc/pki/tls/private/localhost.key - SSLCACertificateFile /etc/pki/CA/certs/ca.crt - - SSLProxyEngine on - SSLProxyCACertificateFile /etc/pki/CA/certs/ca.crt - # It is critical to enforce client certificates. Otherwise, requests can - # spoof the X-Remote-User header by accessing the /oauth/authorize endpoint - # directly. - SSLProxyMachineCertificateFile /etc/pki/tls/certs/authproxy.pem - - # To use the challenging-proxy, an X-Csrf-Token must be present. - RewriteCond %{REQUEST_URI} ^/challenging-proxy - RewriteCond %{HTTP:X-Csrf-Token} ^$ [NC] - RewriteRule ^.* - [F,L] - - <Location /challenging-proxy/oauth/authorize> - # Insert your backend server name/ip here. - ProxyPass https://<namespace_route>/oauth/authorize - AuthName "SSO Login" - # For Kerberos - AuthType GSSAPI - Require valid-user - RequestHeader set X-Remote-User %{REMOTE_USER}s - - GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab - # Enable the following if you want to allow users to fallback - # to password based authentication when they do not have a client - # configured to perform kerberos authentication. - GssapiBasicAuth On - - # For ldap: - # AuthBasicProvider ldap - # AuthLDAPURL "ldap://ldap.example.com:389/ou=People,dc=my-domain,dc=com?uid?sub?(objectClass=*)" - </Location> - - <Location /login-proxy/oauth/authorize> - # Insert your backend server name/ip here. - ProxyPass https://<namespace_route>/oauth/authorize - - AuthName "SSO Login" - AuthType GSSAPI - Require valid-user - RequestHeader set X-Remote-User %{REMOTE_USER}s env=REMOTE_USER - - GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab - # Enable the following if you want to allow users to fallback - # to password based authentication when they do not have a client - # configured to perform kerberos authentication. - GssapiBasicAuth On - - ErrorDocument 401 /login.html - </Location> - -</VirtualHost> - -RequestHeader unset X-Remote-User ----- -+ -[NOTE] -==== -The `\https://<namespace_route>` address is the route to the OAuth server and -can be obtained by running `oc get route -n openshift-authentication`. -==== - -. Update the `identityProviders` stanza in the custom resource (CR): -+ -[source,yaml] ----- -identityProviders: - - name: requestheaderidp - type: RequestHeader - requestHeader: - challengeURL: "https://<namespace_route>/challenging-proxy/oauth/authorize?${query}" - loginURL: "https://<namespace_route>/login-proxy/oauth/authorize?${query}" - ca: - name: ca-config-map - clientCommonNames: - - my-auth-proxy - headers: - - X-Remote-User ----- - -. Verify the configuration. - -.. Confirm that you can bypass the proxy by requesting a token by supplying the -correct client certificate and header: -+ -[source,terminal] ----- -# curl -L -k -H "X-Remote-User: joe" \ - --cert /etc/pki/tls/certs/authproxy.pem \ - https://<namespace_route>/oauth/token/request ----- - -.. Confirm that requests that do not supply the client certificate fail by -requesting a token without the certificate: -+ -[source,terminal] ----- -# curl -L -k -H "X-Remote-User: joe" \ - https://<namespace_route>/oauth/token/request ----- - -.. Confirm that the `challengeURL` redirect is active: -+ -[source,terminal] ----- -# curl -k -v -H 'X-Csrf-Token: 1' \ - https://<namespace_route>/oauth/authorize?client_id=openshift-challenging-client&response_type=token ----- -+ -Copy the `challengeURL` redirect to use in the next step. - -.. Run this command to show a `401` response with a `WWW-Authenticate` basic -challenge, a negotiate challenge, or both challenges: -+ -[source,terminal] ----- -# curl -k -v -H 'X-Csrf-Token: 1' \ - <challengeURL_redirect + query> ----- - -.. Test logging in to the OpenShift CLI (`oc`) with and without using a Kerberos -ticket: -... If you generated a Kerberos ticket by using `kinit`, destroy it: -+ -[source,terminal] ----- -# kdestroy -c cache_name <1> ----- -+ -<1> Make sure to provide the name of your Kerberos cache. -... Log in to the `oc` tool by using your Kerberos credentials: -+ -[source,terminal] ----- -# oc login ----- -+ -Enter your Kerberos user name and password at the prompt. -... Log out of the `oc` tool: -+ -[source,terminal] ----- -# oc logout ----- -... Use your Kerberos credentials to get a ticket: -+ -[source,terminal] ----- -# kinit ----- -+ -Enter your Kerberos user name and password at the prompt. -... Confirm that you can log in to the `oc` tool: -+ -[source,terminal] ----- -# oc login ----- -+ -If your configuration is correct, you are logged in without entering separate -credentials. diff --git a/modules/identity-provider-configuring-using-web-console.adoc b/modules/identity-provider-configuring-using-web-console.adoc deleted file mode 100644 index 66104670d5d4..000000000000 --- a/modules/identity-provider-configuring-using-web-console.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -//* authentication/identity_providers/configuring-htpasswd-identity-provider.adoc -//* authentication/identity_providers/configuring-oidc-identity-provider.adoc - -[id="identity-provider-configuring-using-the-web-console_{context}"] -= Configuring identity providers using the web console - -Configure your identity provider (IDP) through the web console instead of the CLI. - -.Prerequisites - -* You must be logged in to the web console as a cluster administrator. - -.Procedure - -. Navigate to *Administration* -> *Cluster Settings*. -. Under the *Global Configuration* tab, click *OAuth*. -. Under the *Identity Providers* section, select your identity provider from the -*Add* drop-down menu. - -[NOTE] -==== -You can specify multiple IDPs through the web console without overwriting -existing IDPs. -==== diff --git a/modules/identity-provider-creating-htpasswd-file-linux.adoc b/modules/identity-provider-creating-htpasswd-file-linux.adoc deleted file mode 100644 index 43d312c755b8..000000000000 --- a/modules/identity-provider-creating-htpasswd-file-linux.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc - -[id="identity-provider-creating-htpasswd-file-linux_{context}"] -= Creating an HTPasswd file using Linux - -To use the HTPasswd identity provider, you must generate a flat file that -contains the user names and passwords for your cluster by using -link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. - -.Prerequisites - -* Have access to the `htpasswd` utility. On Red Hat Enterprise Linux -this is available by installing the `httpd-tools` package. - -.Procedure - -. Create or update your flat file with a user name and hashed password: -+ -[source,terminal] ----- -$ htpasswd -c -B -b </path/to/users.htpasswd> <user_name> <password> ----- -+ -The command generates a hashed version of the password. -+ -For example: -+ -[source,terminal] ----- -$ htpasswd -c -B -b users.htpasswd user1 MyPassword! ----- -+ -.Example output -[source,terminal] ----- -Adding password for user user1 ----- - -. Continue to add or update credentials to the file: -+ -[source,terminal] ----- -$ htpasswd -B -b </path/to/users.htpasswd> <user_name> <password> ----- diff --git a/modules/identity-provider-creating-htpasswd-file-windows.adoc b/modules/identity-provider-creating-htpasswd-file-windows.adoc deleted file mode 100644 index 5a3e62b91c8f..000000000000 --- a/modules/identity-provider-creating-htpasswd-file-windows.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc - -[id="identity-provider-creating-htpasswd-file-windows_{context}"] -= Creating an HTPasswd file using Windows - -To use the HTPasswd identity provider, you must generate a flat file that -contains the user names and passwords for your cluster by using -link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. - -.Prerequisites - -* Have access to `htpasswd.exe`. This file is included in the `\bin` -directory of many Apache httpd distributions. - -.Procedure - -. Create or update your flat file with a user name and hashed password: -+ -[source,terminal] ----- -> htpasswd.exe -c -B -b <\path\to\users.htpasswd> <user_name> <password> ----- -+ -The command generates a hashed version of the password. -+ -For example: -+ -[source,terminal] ----- -> htpasswd.exe -c -B -b users.htpasswd user1 MyPassword! ----- -+ -.Example output -[source,terminal] ----- -Adding password for user user1 ----- - -. Continue to add or update credentials to the file: -+ -[source,terminal] ----- -> htpasswd.exe -b <\path\to\users.htpasswd> <user_name> <password> ----- diff --git a/modules/identity-provider-default-CR.adoc b/modules/identity-provider-default-CR.adoc deleted file mode 100644 index 528c986f6b96..000000000000 --- a/modules/identity-provider-default-CR.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-identity-provider.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="identity-provider-default-CR_{context}"] -= Sample identity provider CR - -The following custom resource (CR) shows the parameters and default -values that you use to configure an identity provider. This example -uses the HTPasswd identity provider. - -.Sample identity provider CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: my_identity_provider <1> - mappingMethod: claim <2> - type: HTPasswd - htpasswd: - fileData: - name: htpass-secret <3> ----- -<1> This provider name is prefixed to provider user names to form an -identity name. -<2> Controls how mappings are established between this provider's -identities and `User` objects. -<3> An existing secret containing a file generated using -link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. diff --git a/modules/identity-provider-github-CR.adoc b/modules/identity-provider-github-CR.adoc deleted file mode 100644 index 73709cfb25f5..000000000000 --- a/modules/identity-provider-github-CR.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-github-identity-provider.adoc - -[id="identity-provider-github-CR_{context}"] -= Sample GitHub CR - -The following custom resource (CR) shows the parameters and acceptable values for a -GitHub identity provider. - -.GitHub CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: githubidp <1> - mappingMethod: claim <2> - type: GitHub - github: - ca: <3> - name: ca-config-map - clientID: {...} <4> - clientSecret: <5> - name: github-secret - hostname: ... <6> - organizations: <7> - - myorganization1 - - myorganization2 - teams: <8> - - myorganization1/team-a - - myorganization2/team-b ----- -<1> This provider name is prefixed to the GitHub numeric user ID to form an -identity name. It is also used to build the callback URL. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> Optional: Reference to an {product-title} `ConfigMap` object containing the -PEM-encoded certificate authority bundle to use in validating server -certificates for the configured URL. Only for use in GitHub Enterprise -with a non-publicly trusted root certificate. -<4> The client ID of a -link:https://github.com/settings/applications/new[registered GitHub OAuth -application]. The application must be configured with a callback URL of -`\https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name>`. -<5> Reference to an {product-title} `Secret` object containing the client secret -issued by GitHub. -<6> For GitHub Enterprise, you must provide the host name of your instance, such as -`example.com`. This value must match the GitHub Enterprise `hostname` value in -in the `/setup/settings` file and cannot include a port number. If this -value is not set, then either `teams` or `organizations` must be defined. -For GitHub, omit this parameter. -<7> The list of organizations. Either the `organizations` or `teams` field must be set unless the `hostname` field is set, or if `mappingMethod` is set to `lookup`. Cannot be used in combination with the `teams` field. -<8> The list of teams. Either the `teams` or `organizations` field must be set unless the `hostname` field is set, or if `mappingMethod` is set to `lookup`. Cannot be used in combination with the `organizations` field. - -[NOTE] -==== -If `organizations` or `teams` is specified, only GitHub users that are members of -at least one of the listed organizations will be allowed to log in. If the GitHub OAuth -application configured in `clientID` is not owned by the organization, an organization -owner must grant third-party access to use this option. This can be done during -the first GitHub login by the organization's administrator, or from the GitHub organization settings. -==== diff --git a/modules/identity-provider-gitlab-CR.adoc b/modules/identity-provider-gitlab-CR.adoc deleted file mode 100644 index 7c4b59b5b2f5..000000000000 --- a/modules/identity-provider-gitlab-CR.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc - -[id="identity-provider-gitlab-CR_{context}"] -= Sample GitLab CR - -The following custom resource (CR) shows the parameters and acceptable values for a -GitLab identity provider. - -.GitLab CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: gitlabidp <1> - mappingMethod: claim <2> - type: GitLab - gitlab: - clientID: {...} <3> - clientSecret: <4> - name: gitlab-secret - url: https://gitlab.com <5> - ca: <6> - name: ca-config-map ----- -<1> This provider name is prefixed to the GitLab numeric user ID to form an -identity name. It is also used to build the callback URL. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> The client ID of a -link:https://docs.gitlab.com/ce/api/oauth2.html[registered GitLab OAuth application]. -The application must be configured with a callback URL of -`\https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name>`. -<4> Reference to an {product-title} `Secret` object containing the client secret -issued by GitLab. -<5> The host URL of a GitLab provider. This could either be `\https://gitlab.com/` -or any other self hosted instance of GitLab. -<6> Optional: Reference to an {product-title} `ConfigMap` object containing the -PEM-encoded certificate authority bundle to use in validating server -certificates for the configured URL. diff --git a/modules/identity-provider-google-CR.adoc b/modules/identity-provider-google-CR.adoc deleted file mode 100644 index 273c4e332c74..000000000000 --- a/modules/identity-provider-google-CR.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-google-identity-provider.adoc - -[id="identity-provider-google-CR_{context}"] -= Sample Google CR - -The following custom resource (CR) shows the parameters and acceptable -values for a Google identity provider. - -.Google CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: googleidp <1> - mappingMethod: claim <2> - type: Google - google: - clientID: {...} <3> - clientSecret: <4> - name: google-secret - hostedDomain: "example.com" <5> ----- -<1> This provider name is prefixed to the Google numeric user ID to form an -identity name. It is also used to build the redirect URL. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> The client ID of a link:https://console.developers.google.com/[registered -Google project]. The project must be configured with a redirect URI of -`\https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name>`. -<4> Reference to an {product-title} `Secret` object containing the client secret -issued by Google. -<5> A -link:https://developers.google.com/identity/protocols/OpenIDConnect#hd-param[hosted domain] -used to restrict sign-in accounts. Optional if the `lookup` `mappingMethod` -is used. If empty, any Google account is allowed to authenticate. diff --git a/modules/identity-provider-htpasswd-CR.adoc b/modules/identity-provider-htpasswd-CR.adoc deleted file mode 100644 index a80fa3f7f3b3..000000000000 --- a/modules/identity-provider-htpasswd-CR.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc - -[id="identity-provider-htpasswd-CR_{context}"] -= Sample HTPasswd CR - -The following custom resource (CR) shows the parameters and acceptable values for an -HTPasswd identity provider. - -.HTPasswd CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: my_htpasswd_provider <1> - mappingMethod: claim <2> - type: HTPasswd - htpasswd: - fileData: - name: htpass-secret <3> ----- -<1> This provider name is prefixed to provider user names to form an identity -name. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> An existing secret containing a file generated using -link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. diff --git a/modules/identity-provider-htpasswd-secret.adoc b/modules/identity-provider-htpasswd-secret.adoc deleted file mode 100644 index b6cc06d5fd1b..000000000000 --- a/modules/identity-provider-htpasswd-secret.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc - -[id="identity-provider-creating-htpasswd-secret_{context}"] -= Creating the HTPasswd Secret - -To use the HTPasswd identity provider, you must define a secret that -contains the HTPasswd user file. - -.Prerequisites - -* Create an HTPasswd file. - -.Procedure - -* Create an {product-title} `Secret` object that contains the HTPasswd users file. -+ -[source,terminal] ----- -$ oc create secret generic htpass-secret --from-file=htpasswd=</path/to/users.htpasswd> -n openshift-config ----- -+ -[NOTE] -==== -The secret key containing the users file for the `--from-file` argument must be named `htpasswd`, as shown in the above command. -==== diff --git a/modules/identity-provider-htpasswd-update-users.adoc b/modules/identity-provider-htpasswd-update-users.adoc deleted file mode 100644 index e2ef1f1422ee..000000000000 --- a/modules/identity-provider-htpasswd-update-users.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc - -[id="identity-provider-htpasswd-update-users_{context}"] -= Updating users for an HTPasswd identity provider - -You can add or remove users from an existing HTPasswd identity provider. - -.Prerequisites - -* You have created a `Secret` object that contains the HTPasswd user file. This procedure assumes that it is named `htpass-secret`. -* You have configured an HTPasswd identity provider. This procedure assumes that it is named `my_htpasswd_provider`. -* You have access to the `htpasswd` utility. On Red Hat Enterprise Linux this is available by installing the `httpd-tools` package. -* You have cluster administrator privileges. - -.Procedure - -. Retrieve the HTPasswd file from the `htpass-secret` `Secret` object and save the file to your file system: -+ -[source,terminal] ----- -$ oc get secret htpass-secret -ojsonpath={.data.htpasswd} -n openshift-config | base64 -d > users.htpasswd ----- - -. Add or remove users from the `users.htpasswd` file. - -** To add a new user: -+ -[source,terminal] ----- -$ htpasswd -bB users.htpasswd <username> <password> ----- -+ -.Example output -[source,terminal] ----- -Adding password for user <username> ----- - -** To remove an existing user: -+ -[source,terminal] ----- -$ htpasswd -D users.htpasswd <username> ----- -+ -.Example output -[source,terminal] ----- -Deleting password for user <username> ----- - -. Replace the `htpass-secret` `Secret` object with the updated users in the `users.htpasswd` file: -+ -[source,terminal] ----- -$ oc create secret generic htpass-secret --from-file=htpasswd=users.htpasswd --dry-run=client -o yaml -n openshift-config | oc replace -f - ----- - -. If you removed one or more users, you must additionally remove existing resources for each user. - -.. Delete the `User` object: -+ -[source,terminal] ----- -$ oc delete user <username> ----- -+ -.Example output -[source,terminal] ----- -user.user.openshift.io "<username>" deleted ----- -+ -Be sure to remove the user, otherwise the user can continue using their token as long as it has not expired. - -.. Delete the `Identity` object for the user: -+ -[source,terminal] ----- -$ oc delete identity my_htpasswd_provider:<username> ----- -+ -.Example output -[source,terminal] ----- -identity.user.openshift.io "my_htpasswd_provider:<username>" deleted ----- diff --git a/modules/identity-provider-keystone-CR.adoc b/modules/identity-provider-keystone-CR.adoc deleted file mode 100644 index 09cb3c7c63de..000000000000 --- a/modules/identity-provider-keystone-CR.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-keystone-identity-provider.adoc - -[id="identity-provider-keystone-CR_{context}"] -= Sample Keystone CR - -The following custom resource (CR) shows the parameters and acceptable values for a -Keystone identity provider. - -.Keystone CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: keystoneidp <1> - mappingMethod: claim <2> - type: Keystone - keystone: - domainName: default <3> - url: https://keystone.example.com:5000 <4> - ca: <5> - name: ca-config-map - tlsClientCert: <6> - name: client-cert-secret - tlsClientKey: <7> - name: client-key-secret ----- -<1> This provider name is prefixed to provider user names to form an identity name. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> Keystone domain name. In Keystone, usernames are domain-specific. Only a single domain is supported. -<4> The URL to use to connect to the Keystone server (required). This must -use https. -<5> Optional: Reference to an {product-title} `ConfigMap` object containing the -PEM-encoded certificate authority bundle to use in validating server -certificates for the configured URL. -<6> Optional: Reference to an {product-title} `Secret` object containing the client -certificate to present when making requests to the configured URL. -<7> Reference to an {product-title} `Secret` object containing the key for the -client certificate. Required if `tlsClientCert` is specified. diff --git a/modules/identity-provider-ldap-CR.adoc b/modules/identity-provider-ldap-CR.adoc deleted file mode 100644 index 2c62acdf8c65..000000000000 --- a/modules/identity-provider-ldap-CR.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-ldap-identity-provider.adoc - -[id="identity-provider-ldap-CR_{context}"] -= Sample LDAP CR - -The following custom resource (CR) shows the parameters and acceptable values for an -LDAP identity provider. - -.LDAP CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: ldapidp <1> - mappingMethod: claim <2> - type: LDAP - ldap: - attributes: - id: <3> - - dn - email: <4> - - mail - name: <5> - - cn - preferredUsername: <6> - - uid - bindDN: "" <7> - bindPassword: <8> - name: ldap-secret - ca: <9> - name: ca-config-map - insecure: false <10> - url: "ldap://ldap.example.com/ou=users,dc=acme,dc=com?uid" <11> ----- -<1> This provider name is prefixed to the returned user ID to form an identity -name. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> List of attributes to use as the identity. First non-empty attribute is -used. At least one attribute is required. If none of the listed attribute -have a value, authentication fails. Defined attributes are retrieved as raw, -allowing for binary values to be used. -<4> List of attributes to use as the email address. First non-empty -attribute is used. -<5> List of attributes to use as the display name. First non-empty -attribute is used. -<6> List of attributes to use as the preferred user name when provisioning a -user for this identity. First non-empty attribute is used. -<7> Optional DN to use to bind during the search phase. Must be set if -`bindPassword` is defined. -<8> Optional reference to an {product-title} `Secret` object containing the bind -password. Must be set if `bindDN` is defined. -<9> Optional: Reference to an {product-title} `ConfigMap` object containing the -PEM-encoded certificate authority bundle to use in validating server -certificates for the configured URL. Only used when `insecure` is `false`. -<10> When `true`, no TLS connection is made to the server. When `false`, -`ldaps://` URLs connect using TLS, and `ldap://` URLs are upgraded to TLS. -This must be set to `false` when `ldaps://` URLs are in use, as these -URLs always attempt to connect using TLS. -<11> An RFC 2255 URL which specifies the LDAP host and search parameters to use. - -[NOTE] -==== -To whitelist users for an LDAP integration, use the `lookup` mapping method. -Before a login from LDAP would be allowed, a cluster administrator must create -an `Identity` object and a `User` object for each LDAP user. -==== diff --git a/modules/identity-provider-ldap-secret.adoc b/modules/identity-provider-ldap-secret.adoc deleted file mode 100644 index e74afdd662b8..000000000000 --- a/modules/identity-provider-ldap-secret.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-ldap-identity-provider.adoc - -[id="identity-provider-creating-ldap-secret_{context}"] -= Creating the LDAP secret - -To use the identity provider, you must define an {product-title} `Secret` object -that contains the `bindPassword` field. - -* Define an {product-title} `Secret` object that contains the `bindPassword` field. -+ -[source,terminal] ----- -$ oc create secret generic ldap-secret --from-literal=bindPassword=<secret> -n openshift-config ----- -+ -[NOTE] -==== -The secret key containing the bindPassword for the `--from-literal` argument must be called `bindPassword`, as shown in the above command. -==== diff --git a/modules/identity-provider-oidc-CR.adoc b/modules/identity-provider-oidc-CR.adoc deleted file mode 100644 index fc6ccea8d60b..000000000000 --- a/modules/identity-provider-oidc-CR.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-oidc-identity-provider.adoc - -[id="identity-provider-oidc-CR_{context}"] -= Sample OpenID Connect CRs - -The following custom resources (CRs) show the parameters and acceptable values for an -OpenID Connect identity provider. - -If you must specify a custom certificate bundle, extra scopes, extra authorization request -parameters, or a `userInfo` URL, use the full OpenID Connect CR. - -.Standard OpenID Connect CR -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: oidcidp <1> - mappingMethod: claim <2> - type: OpenID - openID: - clientID: ... <3> - clientSecret: <4> - name: idp-secret - claims: <5> - preferredUsername: - - preferred_username - name: - - name - email: - - email - issuer: https://www.idp-issuer.com <6> ----- -<1> This provider name is prefixed to the value of the identity claim to form an -identity name. It is also used to build the redirect URL. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> The client ID of a client registered with the OpenID provider. The -client must be allowed to redirect to -`\https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>`. -<4> Reference to an {product-title} `Secret` object containing the client secret. -<5> List of claims to use as the identity. First non-empty claim is used. At -least one claim is required. If none of the listed claims have a value, -authentication fails. For example, this uses the value of the `sub` claim in the returned `id_token` as the user's identity. -<6> link:https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier[Issuer Identifier] -described in the OpenID spec. Must use `https` without query or fragment -component. - -.Full OpenID Connect CR -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: oidcidp - mappingMethod: claim - type: OpenID - openID: - clientID: ... - clientSecret: - name: idp-secret - ca: <1> - name: ca-config-map - extraScopes: <2> - - email - - profile - extraAuthorizeParameters: <3> - include_granted_scopes: "true" - claims: - preferredUsername: <4> - - preferred_username - - email - name: <5> - - nickname - - given_name - - name - email: <6> - - custom_email_claim - - email - issuer: https://www.idp-issuer.com - ----- -<1> Optional: Reference to an {product-title} config map containing the -PEM-encoded certificate authority bundle to use in validating server -certificates for the configured URL. -<2> Optional list of scopes to request, in addition to the `openid` scope, -during the authorization token request. -<3> Optional map of extra parameters to add to the authorization token request. -<4> List of claims to use as the preferred user name when provisioning a user -for this identity. First non-empty claim is used. -<5> List of claims to use as the display name. First non-empty claim is used. -<6> List of claims to use as the email address. First non-empty claim is used. diff --git a/modules/identity-provider-overview.adoc b/modules/identity-provider-overview.adoc deleted file mode 100644 index e0ee2addba45..000000000000 --- a/modules/identity-provider-overview.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-identity-provider.adoc -// * authentication/identity_providers/configuring-allow-all-identity-provider.adoc -// * authentication/identity_providers/configuring-deny-all-identity-provider.adoc -// * authentication/identity_providers/configuring-htpasswd-identity-provider.adoc -// * authentication/identity_providers/configuring-keystone-identity-provider.adoc -// * authentication/identity_providers/configuring-ldap-identity-provider.adoc -// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc -// * authentication/identity_providers/configuring-github-identity-provider.adoc -// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc -// * authentication/identity_providers/configuring-google-identity-provider.adoc -// * authentication/identity_providers/configuring-oidc-identity-provider.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="identity-provider-overview_{context}"] -= About identity providers in {product-title} - -By default, only a `kubeadmin` user exists on your cluster. To specify an -identity provider, you must create a custom resource (CR) that describes -that identity provider and add it to the cluster. - -[NOTE] -==== -{product-title} user names containing `/`, `:`, and `%` are not supported. -==== diff --git a/modules/identity-provider-parameters.adoc b/modules/identity-provider-parameters.adoc deleted file mode 100644 index 98365bf21d21..000000000000 --- a/modules/identity-provider-parameters.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-identity-provider.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="identity-provider-parameters_{context}"] -= Identity provider parameters - -The following parameters are common to all identity providers: - -[cols="2a,8a",options="header"] -|=== -|Parameter | Description -|`name` | The provider name is prefixed to provider user names to form an -identity name. - -|`mappingMethod` | Defines how new identities are mapped to users when they log in. -Enter one of the following values: - -claim:: The default value. Provisions a user with the identity's preferred -user name. Fails if a user with that user name is already mapped to another -identity. -lookup:: Looks up an existing identity, user identity mapping, and user, -but does not automatically provision users or identities. This allows cluster -administrators to set up identities and users manually, or using an external -process. Using this method requires you to manually provision users. -generate:: Provisions a user with the identity's preferred user name. If a -user with the preferred user name is already mapped to an existing identity, a -unique user name is generated. For example, `myuser2`. This method should not be -used in combination with external processes that require exact matches between -{product-title} user names and identity provider user names, such as LDAP group -sync. -add:: Provisions a user with the identity's preferred user name. If a user -with that user name already exists, the identity is mapped to the existing user, -adding to any existing identity mappings for the user. Required when multiple -identity providers are configured that identify the same set of users and map to -the same user names. -|=== - -[NOTE] -When adding or changing identity providers, you can map identities from the new -provider to existing users by setting the `mappingMethod` parameter to -`add`. diff --git a/modules/identity-provider-registering-github.adoc b/modules/identity-provider-registering-github.adoc deleted file mode 100644 index 61879573d176..000000000000 --- a/modules/identity-provider-registering-github.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-github-identity-provider.adoc - -[id="identity-provider-registering-github_{context}"] -= Registering a GitHub application - -To use GitHub or GitHub Enterprise as an identity provider, you must register -an application to use. - -.Procedure - -. Register an application on GitHub: -** For GitHub, click https://github.com/settings/profile[*Settings*] -> -https://github.com/settings/apps[*Developer settings*] -> -https://github.com/settings/developers[*OAuth Apps*] -> -https://github.com/settings/applications/new[*Register a new OAuth application*]. -** For GitHub Enterprise, go to your GitHub Enterprise home page and then click -*Settings -> Developer settings -> Register a new application*. -. Enter an application name, for example `My OpenShift Install`. -. Enter a homepage URL, such as -`\https://oauth-openshift.apps.<cluster-name>.<cluster-domain>`. -. Optional: Enter an application description. -. Enter the authorization callback URL, where the end of the URL contains the -identity provider `name`: -+ ----- -https://oauth-openshift.apps.<cluster-name>.<cluster-domain>/oauth2callback/<idp-provider-name> ----- -+ -For example: -+ ----- -https://oauth-openshift.apps.example-openshift-cluster.com/oauth2callback/github/ ----- -. Click *Register application*. GitHub provides a client ID and a client secret. -You need these values to complete the identity provider configuration. diff --git a/modules/identity-provider-request-header-CR.adoc b/modules/identity-provider-request-header-CR.adoc deleted file mode 100644 index 447b3285e143..000000000000 --- a/modules/identity-provider-request-header-CR.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc - -[id="identity-provider-request-header-CR_{context}"] -= Sample request header CR - -The following custom resource (CR) shows the parameters and -acceptable values for a request header identity provider. - -.Request header CR - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - identityProviders: - - name: requestheaderidp <1> - mappingMethod: claim <2> - type: RequestHeader - requestHeader: - challengeURL: "https://www.example.com/challenging-proxy/oauth/authorize?${query}" <3> - loginURL: "https://www.example.com/login-proxy/oauth/authorize?${query}" <4> - ca: <5> - name: ca-config-map - clientCommonNames: <6> - - my-auth-proxy - headers: <7> - - X-Remote-User - - SSO-User - emailHeaders: <8> - - X-Remote-User-Email - nameHeaders: <9> - - X-Remote-User-Display-Name - preferredUsernameHeaders: <10> - - X-Remote-User-Login ----- -<1> This provider name is prefixed to the user name in the request header to -form an identity name. -<2> Controls how mappings are established between this provider's identities and `User` objects. -<3> Optional: URL to redirect unauthenticated `/oauth/authorize` requests to, -that will authenticate browser-based clients and then proxy their request to -`https://_<namespace_route>_/oauth/authorize`. -The URL that proxies to `https://_<namespace_route>_/oauth/authorize` must end with `/authorize` (with no trailing slash), -and also proxy subpaths, in order for OAuth approval flows to work properly. -`${url}` is replaced with the current URL, escaped to be safe in a query parameter. -`${query}` is replaced with the current query string. -If this attribute is not defined, then `loginURL` must be used. -<4> Optional: URL to redirect unauthenticated `/oauth/authorize` requests to, -that will authenticate clients which expect `WWW-Authenticate` challenges, and -then proxy them to `https://_<namespace_route>_/oauth/authorize`. -`${url}` is replaced with the current URL, escaped to be safe in a query parameter. -`${query}` is replaced with the current query string. -If this attribute is not defined, then `challengeURL` must be used. -<5> Reference to an {product-title} `ConfigMap` object containing a PEM-encoded -certificate bundle. Used as a trust anchor to validate the TLS -certificates presented by the remote server. -+ -[IMPORTANT] -==== -As of {product-title} 4.1, the `ca` field is required for this identity -provider. This means that your proxy must support mutual TLS. -==== -<6> Optional: list of common names (`cn`). If set, a valid client certificate with -a Common Name (`cn`) in the specified list must be presented before the request headers -are checked for user names. If empty, any Common Name is allowed. Can only be used in combination -with `ca`. -<7> Header names to check, in order, for the user identity. The first header containing -a value is used as the identity. Required, case-insensitive. -<8> Header names to check, in order, for an email address. The first header containing -a value is used as the email address. Optional, case-insensitive. -<9> Header names to check, in order, for a display name. The first header containing -a value is used as the display name. Optional, case-insensitive. -<10> Header names to check, in order, for a preferred user name, if different than the immutable -identity determined from the headers specified in `headers`. The first header containing -a value is used as the preferred user name when provisioning. Optional, case-insensitive. diff --git a/modules/identity-provider-secret.adoc b/modules/identity-provider-secret.adoc deleted file mode 100644 index 02d4a3d8827c..000000000000 --- a/modules/identity-provider-secret.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc -// * authentication/identity_providers/configuring-github-identity-provider.adoc -// * authentication/identity_providers/configuring-gitlab-identity-provider.adoc -// * authentication/identity_providers/configuring-google-identity-provider.adoc -// * authentication/identity_providers/configuring-keystone-identity-provider.adoc -// * authentication/identity_providers/configuring-oidc-identity-provider.adoc -// * authentication/identity_providers/configuring-request-header-identity-provider.adoc - -[id="identity-provider-creating-secret_{context}"] -= Creating the secret - -Identity providers use {product-title} `Secret` objects in the `openshift-config` -namespace to contain the client secret, client certificates, and keys. - -* You can define an {product-title} `Secret` object containing a string -by using the following command. -+ -[source,terminal] ----- -$ oc create secret generic <secret_name> --from-literal=clientSecret=<secret> -n openshift-config ----- - -* You can define an {product-title} `Secret` object containing the contents of a -file, such as a certificate file, by using the following command. -+ -[source,terminal] ----- -$ oc create secret generic <secret_name> --from-file=/path/to/file -n openshift-config ----- diff --git a/modules/idle-idling-applications.adoc b/modules/idle-idling-applications.adoc deleted file mode 100644 index 8ecbdee23ec4..000000000000 --- a/modules/idle-idling-applications.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/idling-applications.adoc - -[id="idle-idling-applications_{context}"] -= Idling applications - -Idling an application involves finding the scalable resources (deployment -configurations, replication controllers, and others) associated with a service. -Idling an application finds the service and marks it as idled, scaling down the -resources to zero replicas. - -You can use the `oc idle` command to idle a single service, or use the -`--resource-names-file` option to idle multiple services. - -[id="idle-idling-applications-single_{context}"] -== Idling a single service - -.Procedure - -. To idle a single service, run: -+ -[source,terminal] ----- -$ oc idle <service> ----- - -[id="idle-idling-applications-multiple_{context}"] -== Idling multiple services - -Idling multiple services is helpful if an application spans across a set of -services within a project, or when idling multiple services in conjunction with -a script to idle multiple applications in bulk within the same project. - -.Procedure - -. Create a file containing a list of the services, each on their own line. - -. Idle the services using the `--resource-names-file` option: -+ -[source,terminal] ----- -$ oc idle --resource-names-file <filename> ----- - -[NOTE] -==== -The `idle` command is limited to a single project. For idling applications across -a cluster, run the `idle` command for each project individually. -==== diff --git a/modules/idle-unidling-applications.adoc b/modules/idle-unidling-applications.adoc deleted file mode 100644 index 56d5318b4d95..000000000000 --- a/modules/idle-unidling-applications.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/idling-applications.adoc - -[id="idle-unidling-applications_{context}"] -= Unidling applications - -Application services become active again when they receive network traffic and -are scaled back up their previous state. This includes both traffic to the -services and traffic passing through routes. - -Applications can also be manually unidled by scaling up the resources. - -.Procedure - -. To scale up a DeploymentConfig, run: -+ -[source,terminal] ----- -$ oc scale --replicas=1 dc <dc_name> ----- - -[NOTE] -==== -Automatic unidling by a router is currently only supported by the default -HAProxy router. -==== diff --git a/modules/ignition-config-viewing.adoc b/modules/ignition-config-viewing.adoc deleted file mode 100644 index 9c739728364b..000000000000 --- a/modules/ignition-config-viewing.adoc +++ /dev/null @@ -1,100 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture_rhcos.adoc - -[id="ignition-config-viewing_{context}"] -= Viewing Ignition configuration files - -To see the Ignition config file used to deploy the bootstrap machine, run the -following command: - -[source,terminal] ----- -$ openshift-install create ignition-configs --dir $HOME/testconfig ----- - -After you answer a few questions, the `bootstrap.ign`, `master.ign`, and -`worker.ign` files appear in the directory you entered. - -To see the contents of the `bootstrap.ign` file, pipe it through the `jq` filter. -Here’s a snippet from that file: - -[source,terminal] ----- -$ cat $HOME/testconfig/bootstrap.ign | jq -\\{ -  "ignition": \\{ -        "config": \\{}, -  "storage": \\{ -        "files": [ -          \\{ -            "filesystem": "root", -            "path": "/etc/motd", -            "user": \\{ -              "name": "root" -            }, -            "append": true, -            "contents": \\{ -              "source": "data:text/plain;charset=utf-8;base64,VGhpcyBpcyB0aGUgYm9vdHN0cmFwIG5vZGU7IGl0IHdpbGwgYmUgZGVzdHJveWVkIHdoZW4gdGhlIG1hc3RlciBpcyBmdWxseSB1cC4KClRoZSBwcmltYXJ5IHNlcnZpY2UgaXMgImJvb3RrdWJlLnNlcnZpY2UiLiBUbyB3YXRjaCBpdHMgc3RhdHVzLCBydW4gZS5nLgoKICBqb3VybmFsY3RsIC1iIC1mIC11IGJvb3RrdWJlLnNlcnZpY2UK", ----- - -To decode the contents of a file listed in the `bootstrap.ign` file, pipe the -base64-encoded data string representing the contents of that file to the `base64 --d` command. Here’s an example using the contents of the `/etc/motd` file added to -the bootstrap machine from the output shown above: - -[source,terminal] ----- -$ echo VGhpcyBpcyB0aGUgYm9vdHN0cmFwIG5vZGU7IGl0IHdpbGwgYmUgZGVzdHJveWVkIHdoZW4gdGhlIG1hc3RlciBpcyBmdWxseSB1cC4KClRoZSBwcmltYXJ5IHNlcnZpY2UgaXMgImJvb3RrdWJlLnNlcnZpY2UiLiBUbyB3YXRjaCBpdHMgc3RhdHVzLCBydW4gZS5nLgoKICBqb3VybmFsY3RsIC1iIC1mIC11IGJvb3RrdWJlLnNlcnZpY2UK | base64 -d ----- - -.Example output -[source,terminal] ----- -This is the bootstrap machine; it will be destroyed when the master is fully up. - -The primary service is "bootkube.service". To watch its status, run, e.g.: - -journalctl -b -f -u bootkube.service ----- - -Repeat those commands on the `master.ign` and `worker.ign` files to see the source -of Ignition config files for each of those machine types.  You should see a line -like the following for the `worker.ign`, identifying how it gets its Ignition -config from the bootstrap machine: - -[source,terminal] ----- -"source": "https://api.myign.develcluster.example.com:22623/config/worker", ----- - -Here are a few things you can learn from the `bootstrap.ign` file: + - -* Format: The format of the file is defined in the -https://coreos.github.io/ignition/configuration-v3_2/[Ignition config spec]. -Files of the same format are used later by the MCO to merge changes into a -machine’s configuration. -* Contents: Because the bootstrap machine serves the Ignition configs for other -machines, both master and worker machine Ignition config information is stored in the -`bootstrap.ign`, along with the bootstrap machine’s configuration. -* Size: The file is more than 1300 lines long, with path to various types of resources. -* The content of each file that will be copied to the machine is actually encoded -into data URLs, which tends to make the content a bit clumsy to read. (Use the - jq and base64 commands shown previously to make the content more readable.) -* Configuration: The different sections of the Ignition config file are generally - meant to contain files that are just dropped into a machine’s file system, rather - than commands to modify existing files. For example, instead of having a section - on NFS that configures that service, you would just add an NFS configuration - file, which would then be started by the init process when the system comes up. -* users: A user named core is created, with your ssh key assigned to that user. -This allows you to log in to the cluster with that user name and your -credentials. -* storage: The storage section identifies files that are added to each machine. A -few notable files include `/root/.docker/config.json` (which provides credentials - your cluster needs to pull from container image registries) and a bunch of - manifest files in `/opt/openshift/manifests` that are used to configure your cluster. -* systemd: The systemd section holds content used to create systemd unit files. -Those files are used to start up services at boot time, as well as manage those -services on running systems. -* Primitives: Ignition also exposes low-level primitives that other tools can -build on. diff --git a/modules/image-integrations-section.adoc b/modules/image-integrations-section.adoc new file mode 100644 index 000000000000..bed88b6bae9b --- /dev/null +++ b/modules/image-integrations-section.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * operating/use-system-health-dashboard.adoc + +:_mod-docs-content-type: REFERENCE +[id="image-integrations-section_{context}"] += Image Integrations section + +The *Image Integrations* section organizes the information into the following groups: + +Name:: Indicates the name of the integrated image. +Label:: Indicates a descriptive label associated with the integration for additional context. +Error message:: Indicates any issues or errors that the integration encounters. +Date:: Indicates the timestamp of the last health check or status update for the integration. \ No newline at end of file diff --git a/modules/image-versions.adoc b/modules/image-versions.adoc new file mode 100644 index 000000000000..e34fbf233114 --- /dev/null +++ b/modules/image-versions.adoc @@ -0,0 +1,46 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +// * release-notes/<version>-release-notes.adoc +// +:_mod-docs-content-type: REFERENCE +[id="image-versions_{context}"] += Image versions + +You can manually pull, retag, and push {rh-rhacs-first} images to your registry. The current version includes the following images: + +.{product-title} images +[%header,cols="1,1,2"] +|=== +|Image |Description |Current version + +|Main +|Includes Central, Sensor, Admission controller, and Compliance components. Also includes `roxctl` for use in continuous integration (CI) systems. +a|`registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version}` + +|Central DB +|PostgreSQL instance that provides the database storage for Central. +a|`registry.redhat.io/advanced-cluster-security/rhacs-central-db-rhel8:{rhacs-version}` + +|Scanner +|Scans images and nodes. +a|. `registry.redhat.io/advanced-cluster-security/rhacs-scanner-rhel8:{rhacs-version}` +. `registry.redhat.io/advanced-cluster-security/rhacs-scanner-slim-rhel8:{rhacs-version}` + +|Scanner DB +|Stores image scan results and vulnerability definitions. +a|`registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version}` + +|Scanner V4 +|Scans images. +a|`registry.redhat.io/advanced-cluster-security/rhacs-scanner-v4-rhel8:{rhacs-version}` + +|Scanner V4 DB +|Stores image scan results and vulnerability definitions for Scanner V4. +a|`registry.redhat.io/advanced-cluster-security/rhacs-scanner-v4-db-rhel8:{rhacs-version}` + +|Collector +|Collects runtime activity in Kubernetes or {ocp} clusters. +a|. `registry.redhat.io/advanced-cluster-security/rhacs-collector-rhel8:{rhacs-version}` + +|=== \ No newline at end of file diff --git a/masters/images b/modules/images similarity index 100% rename from masters/images rename to modules/images diff --git a/modules/images-about.adoc b/modules/images-about.adoc deleted file mode 100644 index 38434a3a1a11..000000000000 --- a/modules/images-about.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.aodc - -[id="images-about_{context}"] -= Images - -Containers in {product-title} are based on OCI- or -Docker-formatted container _images_. An image is a -binary that includes all of the requirements for running a single -container, as well as metadata describing its needs and capabilities. - -You can think of it as a packaging technology. Containers only have access to -resources defined in the image unless you give the container additional access -when creating it. By deploying the same image in multiple containers across -multiple hosts and load balancing between them, {product-title} can provide -redundancy and horizontal scaling for a service packaged into an image. - -You can use the -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/managing_containers/#using_podman_to_work_with_containers[podman] -or `docker` CLI directly to build images, but {product-title} also supplies -builder images that assist with creating new images by adding your code or -configuration to existing images. - -Because applications develop over time, a single image name can actually -refer to many different versions of the same image. Each different -image is referred to uniquely by its hash (a long hexadecimal number -e.g., `fd44297e2ddb050ec4f...`) which is usually shortened to 12 -characters (e.g., `fd44297e2ddb`). diff --git a/modules/images-add-tags-to-imagestreams.adoc b/modules/images-add-tags-to-imagestreams.adoc deleted file mode 100644 index e50fd5bc899d..000000000000 --- a/modules/images-add-tags-to-imagestreams.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/tagging-images - -[id="images-add-tags-to-imagestreams_{context}"] -= Adding tags to imagestreams - -An imagestream in {product-title} comprises zero or more container images -identified by tags. - -There are different types of tags available. The default behavior uses a -_permanent_ tag, which points to a specific image in time. If the _permanent_tag -is in use and the source changes, the tag does not change for the destination. - -A _tracking_ tag means the destination tag's metadata is updated during the import -of the source tag. - -.Procedure - -* You can add tags to an imagestream using the `oc tag` command: -+ -[source,terminal] ----- -$ oc tag <source> <destination> ----- -+ -For example, to configure the `ruby` imagestreams `static-2.0` tag to always -refer to the current image for the `ruby` imagestreams `2.0` tag: -+ -[source,terminal] ----- -$ oc tag ruby:2.0 ruby:static-2.0 ----- -+ -This creates a new imagestreamtag named `static-2.0` in the `ruby` imagestream. -The new tag directly references the image id that the `ruby:2.0` -imagestreamtag pointed to at the time `oc tag` was run, and the image it points -to never changes. - -* To ensure the destination tag is updated whenever the source tag changes, use -the `--alias=true` flag: -+ -[source,terminal] ----- -$ oc tag --alias=true <source> <destination> ----- - -[NOTE] -==== -Use a _tracking_ tag for creating permanent aliases, for example, `latest` or -`stable`. The tag only works correctly within a single imagestream. Trying -to create a cross-imagestream alias produces an error. -==== - -* You can also add the `--scheduled=true` flag to have the destination tag be -refreshed, or re-imported, periodically. The period is configured globally at -the system level. - -* The `--reference` flag creates an imagestreamtag that is not imported. The -tag points to the source location, permanently. -+ -If you want to instruct OpenShift to always fetch the tagged image from the -integrated registry, use `--reference-policy=local`. The registry uses the -pull-through feature to serve the image to the client. By default, the image -blobs are mirrored locally by the registry. As a result, they can be pulled more -quickly the next time they are needed. The flag also allows for pulling from -insecure registries without a need to supply `--insecure-registry` to the container -runtime as long as the imagestream has an insecure annotation or the tag has an -insecure import policy. diff --git a/modules/images-allow-pods-to-reference-images-across-projects.adoc b/modules/images-allow-pods-to-reference-images-across-projects.adoc deleted file mode 100644 index a2847c8d92d8..000000000000 --- a/modules/images-allow-pods-to-reference-images-across-projects.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/using-image-pull-secrets - -[id="images-allow-pods-to-reference-images-across-projects_{context}"] -= Allowing pods to reference images across projects - -When using the internal registry, to allow pods in `project-a` to reference -images in `project-b`, a service account in `project-a` must be bound to the -`system:image-puller` role in `project-b`. - -.Procedure - -. To allow pods in `project-a` to reference images in `project-b`, bind a service -account in `project-a` to the `system:image-puller` role in `project-b`: -+ -[source,terminal] ----- -$ oc policy add-role-to-user \ - system:image-puller system:serviceaccount:project-a:default \ - --namespace=project-b ----- -+ -After adding that role, the pods in `project-a` that reference the default -service account are able to pull images from `project-b`. - -. To allow access for any service account in `project-a`, use the group: -+ -[source,terminal] ----- -$ oc policy add-role-to-group \ - system:image-puller system:serviceaccounts:project-a \ - --namespace=project-b ----- diff --git a/modules/images-allow-pods-to-reference-images-from-secure-registries.adoc b/modules/images-allow-pods-to-reference-images-from-secure-registries.adoc deleted file mode 100644 index 4f3e0f10a3c0..000000000000 --- a/modules/images-allow-pods-to-reference-images-from-secure-registries.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/using-image-pull-secrets -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc -// * openshift_images/managing-image-streams.adoc - -[id="images-allow-pods-to-reference-images-from-secure-registries_{context}"] -= Allowing pods to reference images from other secured registries - -The `.dockercfg` `$HOME/.docker/config.json` file for Docker clients is a -Docker credentials file that stores your authentication information if you have -previously logged into a secured or insecure registry. - -To pull a secured container image that is not from {product-title}'s internal -registry, you must create a pull secret from your Docker credentials and add -it to your service account. - -.Procedure - -* If you already have a `.dockercfg` file for the secured registry, you can create -a secret from that file by running: -+ -[source,terminal] ----- -$ oc create secret generic <pull_secret_name> \ - --from-file=.dockercfg=<path/to/.dockercfg> \ - --type=kubernetes.io/dockercfg ----- - -* Or if you have a `$HOME/.docker/config.json` file: -+ -[source,terminal] ----- -$ oc create secret generic <pull_secret_name> \ - --from-file=.dockerconfigjson=<path/to/.docker/config.json> \ - --type=kubernetes.io/dockerconfigjson ----- - -* If you do not already have a Docker credentials file for the secured registry, -you can create a secret by running: -+ -[source,terminal] ----- -$ oc create secret docker-registry <pull_secret_name> \ - --docker-server=<registry_server> \ - --docker-username=<user_name> \ - --docker-password=<password> \ - --docker-email=<email> ----- - -* To use a secret for pulling images for pods, you must add the secret to your -service account. The name of the service account in this example should match -the name of the service account the pod uses. `default` is the default -service account: -+ -[source,terminal] ----- -$ oc secrets link default <pull_secret_name> --for=pull ----- diff --git a/modules/images-configuration-allowed.adoc b/modules/images-configuration-allowed.adoc deleted file mode 100644 index 1beb229521cf..000000000000 --- a/modules/images-configuration-allowed.adoc +++ /dev/null @@ -1,130 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="images-configuration-allowed_{context}"] -= Adding specific registries - -You can add a list of registries that are permitted for image pull and push actions by editing the `image.config.openshift.io/cluster` custom resource (CR). {product-title} applies the changes to this CR to all nodes in the cluster. - -When pulling or pushing images, the container runtime searches the registries listed under the `registrySources` parameter in the `image.config.openshift.io/cluster` CR. If you created a list of registries under the `allowedRegistries` parameter, the container runtime searches only those registries. Registries not in the list are blocked. - -[WARNING] -==== -When the `allowedRegistries` parameter is defined, all registries including the `registry.redhat.io` and `quay.io` registries are blocked unless explicitly listed. If you use the parameter, to prevent pod failure, add `registry.redhat.io` and `quay.io` to the `allowedRegistries` list, as they are required by payload images within your environment. For disconnected clusters, mirror registries should also be added. -==== - -.Procedure - -. Edit the `image.config.openshift.io/cluster` CR: -+ -[source,terminal] ----- -$ oc edit image.config.openshift.io/cluster ----- -+ -The following is an example `image.config.openshift.io/cluster` CR with an allowed list: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Image -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: "2019-05-17T13:44:26Z" - generation: 1 - name: cluster - resourceVersion: "8302" - selfLink: /apis/config.openshift.io/v1/images/cluster - uid: e34555da-78a9-11e9-b92b-06d6c7da38dc -spec: - registrySources: <1> - allowedRegistries: <2> - - example.com - - quay.io - - registry.redhat.io -status: - internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ----- -<1> `registrySources`: Contains configurations that determine how the container runtime should treat individual registries when accessing images for builds and pods. It does not contain configuration for the internal cluster registry. -<2> `allowedRegistries`: Registries to use for image pull and push actions. All other registries are blocked. -+ -[NOTE] -==== -Either the `allowedRegistries` parameter or the `blockedRegistries` parameter can be set, but not both. -==== -+ -The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` resource for any changes to the registries. When the MCO detects a change, it drains the nodes, applies the change, and uncordons the nodes. After the nodes return to the `Ready` state, the allowed registries list is used to update the image signature policy in the `/host/etc/containers/policy.json` file on each node. - -. To check that the registries have been added to the policy file, use the following command on a node: -+ -[source,terminal] ----- -$ cat /host/etc/containers/policy.json ----- -+ -The following policy indicates that only images from the example.com, quay.io, and registry.redhat.io registries are permitted for image pulls and pushes: -+ -.Example image signature policy file -[%collapsible] -==== -[source,terminal] ----- -{ - "default": [{ - "type": "reject" - }], - "transports": { - "atomic": { - "example.com": [{ - "type": "insecureAcceptAnything" - }], - "quay.io": [{ - "type": "insecureAcceptAnything" - }], - "registry.redhat.io": [{ - "type": "insecureAcceptAnything" - }] - }, - "docker": { - "example.com": [{ - "type": "insecureAcceptAnything" - }], - "quay.io": [{ - "type": "insecureAcceptAnything" - }], - "registry.redhat.io": [{ - "type": "insecureAcceptAnything" - }] - }, - "docker-daemon": { - "": [{ - "type": "insecureAcceptAnything" - }] - } - } -} ----- -==== - -[NOTE] -==== -If your cluster uses the `registrySources.insecureRegistries` parameter, ensure that any insecure registries are included in the allowed list. - -For example: - -[source,yml] ----- -spec: - registrySources: - insecureRegistries: - - insecure.com - allowedRegistries: - - example.com - - quay.io - - registry.redhat.io - - insecure.com ----- -==== diff --git a/modules/images-configuration-blocked.adoc b/modules/images-configuration-blocked.adoc deleted file mode 100644 index 81f290b89559..000000000000 --- a/modules/images-configuration-blocked.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="images-configuration-blocked_{context}"] -= Blocking specific registries - -You can block any registry by editing the `image.config.openshift.io/cluster` custom resource (CR). {product-title} applies the changes to this CR to all nodes in the cluster. - -When pulling or pushing images, the container runtime searches the registries listed under the `registrySources` parameter in the `image.config.openshift.io/cluster` CR. If you created a list of registries under the `blockedRegistries` parameter, the container runtime does not search those registries. All other registries are allowed. - -.Procedure - -. Edit the `image.config.openshift.io/cluster` CR: -+ -[source,terminal] ----- -$ oc edit image.config.openshift.io/cluster ----- -+ -The following is an example `image.config.openshift.io/cluster` CR with a blocked list: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Image -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: "2019-05-17T13:44:26Z" - generation: 1 - name: cluster - resourceVersion: "8302" - selfLink: /apis/config.openshift.io/v1/images/cluster - uid: e34555da-78a9-11e9-b92b-06d6c7da38dc -spec: - registrySources: <1> - blockedRegistries: <2> - - untrusted.com -status: - internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ----- -<1> `registrySources`: Contains configurations that determine how the container runtime should treat individual registries when accessing images for builds and pods. It does not contain configuration for the internal cluster registry. -<2> Specify registries that should not be used for image pull and push actions. All other registries are allowed. -+ -[NOTE] -==== -Either the `blockedRegistries` registry or the `allowedRegistries` registry can be set, but not both. -==== -+ -The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` resource for any changes to the registries. When the MCO detects a change, it drains the nodes, applies the change, and uncordons the nodes. After the nodes return to the `Ready` state, changes to the blocked registries appear in the `/etc/containers/registries.conf` file on each node. - -. To check that the registries have been added to the policy file, use the following command on a node: -+ -[source,terminal] ----- -$ cat /host/etc/containers/registries.conf ----- -+ -The following example indicates that images from the `untrusted.com` registry are prevented for image pulls and pushes: -+ -.Example output -[source,terminal] ----- -unqualified-search-registries = ["registry.access.redhat.com", "docker.io"] - -[[registry]] - prefix = "" - location = "untrusted.com" - blocked = true ----- diff --git a/modules/images-configuration-cas.adoc b/modules/images-configuration-cas.adoc deleted file mode 100644 index 9bd5783c81a3..000000000000 --- a/modules/images-configuration-cas.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring-registry-operator.adoc -// * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="images-configuration-cas_{context}"] -= Configuring additional trust stores for image registry access - -The `image.config.openshift.io/cluster` custom resource can contain a reference to a config map that contains additional certificate authorities to be trusted during image registry access. - -.Prerequisites -* The CAs must be PEM-encoded. - -.Procedure - -You can create a config map in the `openshift-config` namespace and use its name in `AdditionalTrustedCA` in the `image.config.openshift.io` custom resource to provide additional CAs that should be trusted when contacting external registries. - -The ConfigMap key is the host name of a registry with the port for which this CA is to be trusted, and the base64-encoded certificate is the value, for each additional registry CA to trust. - -.Image registry CA config map example -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: my-registry-ca -data: - registry.example.com: | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - registry-with-port.example.com..5000: | <1> - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- ----- -<1> If the registry has the port, such as `registry-with-port.example.com:5000`, `:` should be replaced with `..`. - -You can configure additional CAs with the following procedure. - -. To configure an additional CA: -+ -[source,terminal] ----- -$ oc create configmap registry-config --from-file=<external_registry_address>=ca.crt -n openshift-config ----- -+ -[source,terminal] ----- -$ oc edit image.config.openshift.io cluster ----- -+ -[source,yaml] ----- -spec: - additionalTrustedCA: - name: registry-config ----- diff --git a/modules/images-configuration-file.adoc b/modules/images-configuration-file.adoc deleted file mode 100644 index 3c99f28823e4..000000000000 --- a/modules/images-configuration-file.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="images-configuration-file_{context}"] -= Configuring image settings - -You can configure image registry settings by editing the -`image.config.openshift.io/cluster` custom resource (CR). The -Machine Config Operator (MCO) watches the -`image.config.openshift.io/cluster` CR for any changes -to the registries and reboots the nodes when it detects changes. - -.Procedure - -. Edit the `image.config.openshift.io/cluster` custom resource: -+ -[source,terminal] ----- -$ oc edit image.config.openshift.io/cluster ----- -+ -The following is an example `image.config.openshift.io/cluster` CR: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Image <1> -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: "2019-05-17T13:44:26Z" - generation: 1 - name: cluster - resourceVersion: "8302" - selfLink: /apis/config.openshift.io/v1/images/cluster - uid: e34555da-78a9-11e9-b92b-06d6c7da38dc -spec: - allowedRegistriesForImport: <2> - - domainName: quay.io - insecure: false - additionalTrustedCA: <3> - name: myconfigmap - registrySources: <4> - allowedRegistries: - - example.com - - quay.io - - registry.redhat.io - insecureRegistries: - - insecure.com -status: - internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ----- -<1> `Image`: Holds cluster-wide information about how to handle images. The -canonical, and only valid name is `cluster`. -<2> `allowedRegistriesForImport`: Limits the container image registries from which -normal users may import images. Set this list to the registries that you trust -to contain valid images, and that you want applications to be able to -import from. Users with permission to create images or `ImageStreamMappings` -from the API are not affected by this policy. Typically only cluster -administrators will have the appropriate permissions. -<3> `additionalTrustedCA`: A reference to a ConfigMap containing additional CAs that -should be trusted during `ImageStream import`, `pod image pull`, -`openshift-image-registry pullthrough`, and builds. The namespace for this ConfigMap is -`openshift-config`. The format of the ConfigMap is to use the registry hostname -as the key, and the PEM certificate as the value, for each additional registry CA to -trust. -<4> `registrySources`: Contains configuration that determines how the container -runtime should treat individual registries when accessing images for builds and -pods. For instance, whether or not to allow insecure access. It does not contain -configuration for the internal cluster registry. This example lists `allowedRegistries`, -which defines the registries that are allowed to be used. One of the registries listed -is insecure. - -. To check that the changes are applied, list your nodes: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ci-ln-j5cd0qt-f76d1-vfj5x-master-0 Ready master 98m v1.19.0+7070803 -ci-ln-j5cd0qt-f76d1-vfj5x-master-1 Ready,SchedulingDisabled master 99m v1.19.0+7070803 -ci-ln-j5cd0qt-f76d1-vfj5x-master-2 Ready master 98m v1.19.0+7070803 -ci-ln-j5cd0qt-f76d1-vfj5x-worker-b-nsnd4 Ready worker 90m v1.19.0+7070803 -ci-ln-j5cd0qt-f76d1-vfj5x-worker-c-5z2gz NotReady,SchedulingDisabled worker 90m v1.19.0+7070803 -ci-ln-j5cd0qt-f76d1-vfj5x-worker-d-stsjv Ready worker 90m v1.19.0+7070803 ----- diff --git a/modules/images-configuration-insecure.adoc b/modules/images-configuration-insecure.adoc deleted file mode 100644 index 672aa33ddc0e..000000000000 --- a/modules/images-configuration-insecure.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="images-configuration-insecure_{context}"] -= Allowing insecure registries - -You can add insecure registries by editing the `image.config.openshift.io/cluster` custom resource (CR). -{product-title} applies the changes to this CR to all nodes in the cluster. - -Registries that do not use valid SSL certificates or do not require HTTPS connections are considered insecure. - -[WARNING] -==== -Insecure external registries should be avoided to reduce possible security risks. -==== -.Procedure - -. Edit the `image.config.openshift.io/cluster` CR: -+ -[source,terminal] ----- -$ oc edit image.config.openshift.io/cluster ----- -+ -The following is an example `image.config.openshift.io/cluster` CR with an insecure registries list: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Image -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: "2019-05-17T13:44:26Z" - generation: 1 - name: cluster - resourceVersion: "8302" - selfLink: /apis/config.openshift.io/v1/images/cluster - uid: e34555da-78a9-11e9-b92b-06d6c7da38dc -spec: - registrySources: <1> - insecureRegistries: <2> - - insecure.com - allowedRegistries: - - example.com - - quay.io - - registry.redhat.io - - insecure.com <3> -status: - internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ----- -<1> `registrySources`: Contains configurations that determine how the container runtime should treat individual registries when accessing images for builds and pods. It does not contain configuration for the internal cluster registry. -<2> Specify an insecure registry. -<3> Ensure that any insecure registries are included in the `allowedRegistries` list. -+ -[NOTE] -==== -When the `allowedRegistries` parameter is defined, all registries including the registry.redhat.io and quay.io registries are blocked unless explicitly listed. If you use the parameter, to prevent pod failure, add `registry.redhat.io` and `quay.io` to the `allowedRegistries` list, as they are required by payload images within your environment. -==== -+ -The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` CR for any changes to the registries, then drains and uncordons the nodes when it detects changes. After the nodes return to the `Ready` state, changes to the insecure and blocked registries appear in the `/etc/containers/registries.conf` file on each node. - -. To check that the registries have been added to the policy file, use the following command on a node: -+ -[source,terminal] ----- -$ cat /host/etc/containers/registries.conf ----- -+ -The following example indicates that images from the `insecure.com` registry is insecure and is allowed for image pulls and pushes. -+ -.Example output -[source,terminal] ----- -unqualified-search-registries = ["registry.access.redhat.com", "docker.io"] - -[[registry]] - prefix = "" - location = "insecure.com" - insecure = true ----- diff --git a/modules/images-configuration-parameters.adoc b/modules/images-configuration-parameters.adoc deleted file mode 100644 index fd8c0c24db84..000000000000 --- a/modules/images-configuration-parameters.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="images-configuration-parameters_{context}"] -= Image controller configuration parameters - -The `image.config.openshift.io/cluster` resource holds cluster-wide information -about how to handle images. The canonical, and only valid name is `cluster`. -Its `spec` offers the following configuration parameters. - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`allowedRegistriesForImport` -|`allowedRegistriesForImport`: Limits the container image registries from which -normal users may import images. Set this list to the registries that you trust -to contain valid images, and that you want applications to be able to -import from. Users with permission to create images or `ImageStreamMappings` -from the API are not affected by this policy. Typically only cluster -administrators will have the appropriate permissions. - -Every element of this list contains a location of the registry specified by the -registry domain name. - -`domainName`: Specifies a domain name for the registry. In case the registry uses a -non-standard (80 or 443) port, the port should be included in the domain name -as well. - -`insecure`: Insecure indicates whether the registry is secure or insecure. -By default, if not otherwise specified, the registry is assumed to be secure. - -|`additionalTrustedCA` -|`additionalTrustedCA`: A reference to a ConfigMap containing additional CAs that -should be trusted during `ImageStream import`, `pod image pull`, -`openshift-image-registry pullthrough`, and builds. - -The namespace for this ConfigMap is `openshift-config`. The format of the -ConfigMap is to use the registry hostname as the key, and the PEM-encoded -certificate as the value, for each additional registry CA to trust. - -|`externalRegistryHostnames` -|`externalRegistryHostnames`: Provides the hostnames for the default external -image registry. The external hostname should be set only when the image registry -is exposed externally. The first value is used in `publicDockerImageRepository` -field in ImageStreams. The value must be in `hostname[:port]` format. - -|`registrySources` -|`registrySources`: Contains configuration that determines how the container -runtime should treat individual registries when accessing images for builds and -pods. For instance, whether or not to allow insecure access. It does not contain -configuration for the internal cluster registry. - -`insecureRegistries`: Registries which do not have a valid TLS certificate or -only support HTTP connections. - -`blockedRegistries`: Registries for which image pull and push actions are denied. All other -registries are allowed. - -`allowedRegistries`: Registries for which image pull and push actions are allowed. All other -registries are blocked. - -`containerRuntimeSearchRegistries`: Registries for which image pull and push actions are allowed -using image short names. All other registries are blocked. - -Either `blockedRegistries` or `allowedRegistries` can be set, but not both. - -|=== - -[WARNING] -==== -When the `allowedRegistries` parameter is defined, all registries including `registry.redhat.io` and `quay.io` are blocked unless explicitly listed. When using the parameter, to prevent pod failure, declare the `registry.redhat.io` and `quay.io` registries, as they are required by payload images within your environment. For disconnected clusters, mirror registries should also be added. -==== - -The `status` field of the `image.config.openshift.io/cluster` resource holds -observed values from the cluster. - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`internalRegistryHostname` -|`internalRegistryHostname`: Set by the Image Registry Operator, which controls -the `internalRegistryHostname`. It sets the hostname for the default internal -image registry. The value must be in `hostname[:port]` format. For backward -compatibility, you can still use the `OPENSHIFT_DEFAULT_REGISTRY` environment -variable, but this setting overrides the environment variable. - -|`externalRegistryHostnames` -|`externalRegistryHostnames`: Set by the Image Registry Operator, provides the -external hostnames for the image registry when it is exposed externally. The -first value is used in `publicDockerImageRepository` field in ImageStreams. The -values must be in `hostname[:port]` format. - -|=== diff --git a/modules/images-configuration-registry-mirror.adoc b/modules/images-configuration-registry-mirror.adoc deleted file mode 100644 index 568993d3ee63..000000000000 --- a/modules/images-configuration-registry-mirror.adoc +++ /dev/null @@ -1,213 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="images-configuration-registry-mirror_{context}"] -= Configuring image registry repository mirroring -Setting up container registry repository mirroring enables you to: - -* configure your {product-title} cluster to redirect requests -to pull images from a repository on a source image registry and have -it resolved by a repository on a mirrored image registry -* identify multiple mirrored repositories for each target -repository, to make sure that if one mirror is down, another -can be used - -The attributes of repository mirroring in {product-title} include: - -* Image pulls are resilient to registry downtimes. -* Clusters in restricted networks can pull -images from critical locations (such as quay.io) -and have registries behind a company firewall -provide the requested images. -* A particular order of registries is tried when -an image pull request is made, with the permanent -registry typically being the last one tried. -* The mirror information you enter is added to the `/etc/containers/registries.conf` -file on every node in the {product-title} cluster. -* When a node makes a request for an image from the source repository, it -tries each mirrored repository in turn until it finds the requested content. -If all mirrors fail, the cluster tries the source repository. Upon success, the -image is pulled to the node. - -Setting up repository mirroring can be done in the following ways: - -* At {product-title} installation: By pulling container images needed -by {product-title} and then bringing those images behind your company's -firewall, you can install {product-title} into a -datacenter that is in a restricted network. See -Mirroring the {product-title} image repository for details. - -* After {product-title} installation: Even if you don't configure mirroring during {product-title} -installation, you can do so later using the `ImageContentSourcePolicy` object. - -The following procedure provides a post-installation mirror configuration, where you create an `ImageContentSourcePolicy` object that identifies: - -* the source of the container image repository you want to mirror -* a separate entry for each mirror repository you want to offer the content -requested from the source repository. - -.Prerequisites -* Access to the cluster as a user with the `cluster-admin` role. - - -.Procedure - -. Configure mirrored repositories, by either: -+ -* Setting up a mirrored repository with Red Hat Quay, as -described in link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/manage_red_hat_quay/repo-mirroring-in-red-hat-quay[Red Hat Quay Repository Mirroring]. -Using Red Hat Quay allows you to copy images from one repository to another -and also automatically sync those repositories repeatedly over time. -* Using a tool such as `skopeo` to copy images manually -from the source directory to the mirrored repository. -+ -For example, after installing the skopeo RPM package -on a Red Hat Enterprise Linux -(RHEL 7 or RHEL 8) system, use the `skopeo` command as shown in this example: -+ -[source,terminal] ----- -$ skopeo copy \ -docker://registry.access.redhat.com/ubi8/ubi-minimal@sha256:5cfbaf45ca96806917830c183e9f37df2e913b187adb32e89fd83fa455ebaa6 \ -docker://example.io/example/ubi-minimal ----- -+ -In this example, you have a container image registry that is named -`example.io` with an image repository named `example` to which -you want to copy the `ubi8/ubi-minimal` image from -`registry.access.redhat.com`. -After you create the registry, you can configure your {product-title} -cluster to redirect requests made of the source repository to the -mirrored repository. - -. Log in to your {product-title} cluster. - -. Create an `ImageContentSourcePolicy` file (for example, -`registryrepomirror.yaml`), replacing the source and -mirrors with your own registry and repository pairs and images: - -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1alpha1 -kind: ImageContentSourcePolicy -metadata: - name: ubi8repo -spec: - repositoryDigestMirrors: - - mirrors: - - example.io/example/ubi-minimal <1> - source: registry.access.redhat.com/ubi8/ubi-minimal <2> - - mirrors: - - example.com/example/ubi-minimal - source: registry.access.redhat.com/ubi8/ubi-minimal ----- -<1> Indicates the name of the image registry and repository -<2> Indicates the registry and repository containing the content that is mirrored - -. Create the new `ImageContentSourcePolicy` object: -+ -[source,terminal] ----- -$ oc create -f registryrepomirror.yaml ----- -+ -After the `ImageContentSourcePolicy` object is created, -the new settings are deployed to each node and -the cluster starts using the mirrored repository -for requests to the source repository. - -. To check that the mirrored configuration settings, -are applied, do the following on one of the nodes. - -.. List your nodes: -+ -[source,terminal] ----- -$ oc get node ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-137-44.ec2.internal Ready worker 7m v1.20.0 -ip-10-0-138-148.ec2.internal Ready master 11m v1.20.0 -ip-10-0-139-122.ec2.internal Ready master 11m v1.20.0 -ip-10-0-147-35.ec2.internal Ready,SchedulingDisabled worker 7m v1.20.0 -ip-10-0-153-12.ec2.internal Ready worker 7m v1.20.0 -ip-10-0-154-10.ec2.internal Ready master 11m v1.20.0 ----- -+ -You can see that scheduling on each worker node is disabled as the change is being applied. - -.. Start the debugging process to access the node: -+ -[source,terminal] ----- -$ oc debug node/ip-10-0-147-35.ec2.internal ----- -+ -.Example output -[source,terminal] ----- -Starting pod/ip-10-0-147-35ec2internal-debug ... -To use host binaries, run `chroot /host` ----- - -.. Access the node's files: -+ -[source,terminal] ----- -sh-4.2# chroot /host ----- - -.. Check the `/etc/containers/registries.conf` file to make sure -the changes were made: -+ -[source,terminal] ----- -sh-4.2# cat /etc/containers/registries.conf ----- -+ -.Example output -[source,terminal] ----- -unqualified-search-registries = ["registry.access.redhat.com", "docker.io"] -[[registry]] - location = "registry.access.redhat.com/ubi8/" - insecure = false - blocked = false - mirror-by-digest-only = true - prefix = "" - - [[registry.mirror]] - location = "example.io/example/ubi8-minimal" - insecure = false - - [[registry.mirror]] - location = "example.com/example/ubi8-minimal" - insecure = false ----- - -.. Pull an image digest to the node from the source and check if it is -resolved by the mirror. `ImageContentSourcePolicy` objects support image digests only, not image tags. -+ -[source,terminal] ----- -sh-4.2# podman pull --log-level=debug registry.access.redhat.com/ubi8/ubi-minimal@sha256:5cfbaf45ca96806917830c183e9f37df2e913b187adb32e89fd83fa455ebaa6 ----- - -.Troubleshooting repository mirroring - -If the repository mirroring procedure does not work as described, use -the following information about how repository mirroring works to help -troubleshoot the problem. - -* The first working mirror is used to supply the pulled image. -* The main registry will only be used if no other mirror works. -* From the system context, the `Insecure` flags are used as fallback. -* The format of the `/etc/containers/registries` file has -changed recently. It is now version 2 and in TOML format. diff --git a/modules/images-configuration-shortname.adoc b/modules/images-configuration-shortname.adoc deleted file mode 100644 index 35ccdd5288b9..000000000000 --- a/modules/images-configuration-shortname.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/image-configuration.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="images-configuration-shortname_{context}"] -= Adding registries that allow image short names - -You can add registries to search for an image short name by editing the `image.config.openshift.io/cluster` custom resource (CR). {product-title} applies the changes to this CR to all nodes in the cluster. - -An image short name enables you to search for images without including the fully qualified domain name in the pull spec. For example, you could use `rhel7/etcd` instead of `registry.access.redhat.com/rhe7/etcd`. - -You might use short names in situations where using the full path is not practical. For example, if your cluster references multiple internal registries whose DNS changes frequently, you would need to update the fully qualified domain names in your pull specs with each change. In this case, using an image short name might be beneficial. - -When pulling or pushing images, the container runtime searches the registries listed under the `registrySources` parameter in the `image.config.openshift.io/cluster` CR. If you created a list of registries under the `containerRuntimeSearchRegistries` parameter, when pulling an image with a short name, the container runtime searches those registries. - -[WARNING] -==== -Using image short names with public registries is strongly discouraged. You should use image short names with only internal or private registries. - -If you list public registries under the `containerRuntimeSearchRegistries` parameter, you expose your credentials to all the registries on the list and you risk network and registry attacks. You should always use fully-qualified image names with public registries. -==== - -The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` resource for any changes to the registries. When the MCO detects a change, it drains the nodes, applies the change, and uncordons the nodes. After the nodes return to the `Ready` state, if the `containerRuntimeSearchRegistries` parameter is added, the MCO creates a file in the `/etc/containers/registries.conf.d` directory on each node with the listed registries. The file overrides the default list of unqualified search registries in the `/host/etc/containers/registries.conf` file. There is no way to fall back to the default list of unqualified search registries. - -The `containerRuntimeSearchRegistries` parameter works only with the Podman and CRI-O container engines. The registries in the list can be used only in pod specs, not in builds and image streams. - -.Procedure - -. Edit the `image.config.openshift.io/cluster` custom resource: -+ -[source,terminal] ----- -$ oc edit image.config.openshift.io/cluster ----- -+ -The following is an example `image.config.openshift.io/cluster` CR: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Image -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: "2019-05-17T13:44:26Z" - generation: 1 - name: cluster - resourceVersion: "8302" - selfLink: /apis/config.openshift.io/v1/images/cluster - uid: e34555da-78a9-11e9-b92b-06d6c7da38dc -spec: - allowedRegistriesForImport: - - domainName: quay.io - insecure: false - additionalTrustedCA: - name: myconfigmap - registrySources: - containerRuntimeSearchRegistries: <1> - - "reg1.io" - - "reg2.io" - - "reg3.io" - allowedRegistries: <2> - - example.com - - quay.io - - registry.redhat.io - - "reg1.io" - - "reg2.io" - - "reg3.io" -... -status: - internalRegistryHostname: image-registry.openshift-image-registry.svc:5000 ----- -<1> Specify registries to use with image short names. You should use image short names with only internal or private registries to reduce possible security risks. -<2> Ensure that any registries listed under `containerRuntimeSearchRegistries` are included in the `allowedRegistries` list. -+ -[NOTE] -==== -When the `allowedRegistries` parameter is defined, all registries including the `registry.redhat.io` and `quay.io` registries are blocked unless explicitly listed. If you use this parameter, to prevent pod failure, add `registry.redhat.io` and `quay.io` to the `allowedRegistries` list, as they are required by payload images within your environment. -==== - -. To check that the registries have been added, use the following command on a node: -+ -[source,terminal] ----- -$ cat /host/etc/containers/registries.conf.d/01-image-searchRegistries.conf ----- -+ -.Example output -[source,terminal] ----- -unqualified-search-registries = ['reg1.io', 'reg2.io', 'reg3.io'] ----- - diff --git a/modules/images-container-repository-about.adoc b/modules/images-container-repository-about.adoc deleted file mode 100644 index e672effc4155..000000000000 --- a/modules/images-container-repository-about.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.aodc - -[id="images-container-repository-about_{context}"] -= Image repository - -An *image repository* is a collection of related container images and tags identifying them. For example, the OpenShift Jenkins images are in the repository: - ----- -docker.io/openshift/jenkins-2-centos7 ----- diff --git a/modules/images-create-guide-general.adoc b/modules/images-create-guide-general.adoc deleted file mode 100644 index b8385a918103..000000000000 --- a/modules/images-create-guide-general.adoc +++ /dev/null @@ -1,226 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/create-images.adoc - -[id="images-create-guide-general_{context}"] -= General container image guidelines - -The following guidelines apply when creating a container image in general, and are -independent of whether the images are used on {product-title}. - -[discrete] -== Reuse images - -Wherever possible, we recommend that you base your image on an appropriate -upstream image using the `FROM` statement. This ensures your image can easily -pick up security fixes from an upstream image when it is updated, rather than -you having to update your dependencies directly. - -In addition, use tags in the `FROM` instruction (for example, `rhel:rhel7`) to -make it clear to users exactly which version of an image your image is based on. -Using a tag other than `latest` ensures your image is not subjected to breaking -changes that might go into the `latest` version of an upstream image. - -[discrete] -== Maintain compatibility within tags - -When tagging your own images, we recommend that you try to maintain backwards -compatibility within a tag. For example, if you provide an image named -`foo` and it currently includes version 1.0, you might provide a tag of -`foo:v1`. When you update the image, as long as it continues to be compatible -with the original image, you can continue to tag the new image `foo:v1`, and -downstream consumers of this tag will be able to get updates without being -broken. - -If you later release an incompatible update, then you should switch to a new -tag, for example `foo:v2`. This allows downstream consumers to move up to the -new version at will, but not be inadvertently broken by the new incompatible -image. Any downstream consumer using `foo:latest` takes on the risk of any -incompatible changes being introduced. - -[discrete] -== Avoid multiple processes - -We recommend that you do not start multiple services, such as a database and -`SSHD`, inside one container. This is not necessary because containers -are lightweight and can be easily linked together for orchestrating multiple -processes. {product-title} allows you to easily colocate and co-manage related images -by grouping them into a single pod. - -This colocation ensures the containers share a network namespace and storage -for communication. Updates are also less disruptive as each image can be updated -less frequently and independently. Signal handling flows are also clearer with a -single process as you do not have to manage routing signals to spawned -processes. - -[discrete] -== Use `exec` in wrapper scripts - -Many images use wrapper scripts to do some setup before starting a process for the software being run. If your image uses such a script, that script should use `exec` so that the script’s process is replaced by your software. If you do not use `exec`, then signals sent by your container runtime will go to your wrapper script instead of your software’s process. This is not what you want, as illustrated here: - -Say you have a wrapper script that starts a process for some server. You start your container (for example, using `podman run -i`), which runs the wrapper script, which in turn starts your process. Now say that you want to kill your container with `CTRL+C`. If your wrapper script used exec to start the server process, `podman` will send SIGINT to the server process, and everything will work as you expect. If you didn’t use exec in your wrapper script, `podman` will send SIGINT to the process for the wrapper script and your process will keep running like nothing happened. - -Also note that your process runs as PID 1 when running in a container. -This means that if your main process terminates, the entire container is -stopped, killing any child processes you may have launched from your PID 1 -process. - -See the -http://blog.phusion.nl/2015/01/20/docker-and-the-pid-1-zombie-reaping-problem/["Docker -and the PID 1 zombie reaping problem"] blog article for additional implications. -Also see the https://felipec.wordpress.com/2013/11/04/init/["Demystifying the -init system (PID 1)"] blog article for a deep dive on PID 1 and `init` -systems. - - -[discrete] -== Clean temporary files - -All temporary files you create during the build process should be removed. This -also includes any files added with the `ADD` command. For example, we strongly -recommended that you run the `yum clean` command after performing `yum install` -operations. - -You can prevent the `yum` cache from ending up in an image layer by creating -your `RUN` statement as follows: - ----- -RUN yum -y install mypackage && yum -y install myotherpackage && yum clean all -y ----- - -Note that if you instead write: - ----- -RUN yum -y install mypackage -RUN yum -y install myotherpackage && yum clean all -y ----- - -Then the first `yum` invocation leaves extra files in that layer, and these -files cannot be removed when the `yum clean` operation is run later. The extra -files are not visible in the final image, but they are present in the underlying -layers. - -The current container build process does not allow a command run in a later layer -to shrink the space used by the image when something was removed in an earlier -layer. However, this may change in the future. This means that if you perform an -`rm` command in a later layer, although the files are hidden it does not reduce -the overall size of the image to be downloaded. Therefore, as with the `yum -clean` example, it is best to remove files in the same command that created -them, where possible, so they do not end up written to a layer. - -In addition, performing multiple commands in a single `RUN` statement reduces -the number of layers in your image, which improves download and extraction time. - -[discrete] -== Place instructions in the proper order - -The container builder reads the `Dockerfile` and runs the instructions from top to -bottom. Every instruction that is successfully executed creates a layer which -can be reused the next time this or another image is built. It is very important -to place instructions that will rarely change at the top of your -`Dockerfile`. Doing so ensures the next builds of the same image are -very fast because the cache is not invalidated by upper layer changes. - -For example, if you are working on a `Dockerfile` that contains an `ADD` -command to install a file you are iterating on, and a `RUN` command to `yum -install` a package, it is best to put the `ADD` command last: - ----- -FROM foo -RUN yum -y install mypackage && yum clean all -y -ADD myfile /test/myfile ----- - -This way each time you edit `myfile` and rerun `podman build` or `docker build`, the system reuses the cached layer for the `yum` command and only generates the new layer for the `ADD` operation. - -If instead you wrote the `Dockerfile` as: - ----- -FROM foo -ADD myfile /test/myfile -RUN yum -y install mypackage && yum clean all -y ----- - -Then each time you changed *_myfile_* and reran `podman build` or `docker build`, the `ADD` operation would invalidate the `RUN` layer cache, so the `yum` operation must be -rerun as well. - -[discrete] -== Mark important ports - -The EXPOSE instruction makes a port in the container available to the host system and other containers. While it is possible to specify that a port should be exposed with a `podman run` invocation, using the EXPOSE instruction in a `Dockerfile` makes it easier for both humans and software to use your image by explicitly declaring the ports your software needs to run: - -* Exposed ports will show up under `podman ps` associated with containers created from your image -* Exposed ports will also be present in the metadata for your image returned by `podman inspect` -* Exposed ports will be linked when you link one container to another - -[discrete] -== Set environment variables - -It is good practice to set environment variables with the `ENV` instruction. -One example is to set the version of your project. This makes it easy for people -to find the version without looking at the `Dockerfile`. Another example is -advertising a path on the system that could be used by another process, such as -`JAVA_HOME`. - -[discrete] -== Avoid default passwords - -It is best to avoid setting default passwords. Many people will extend the image -and forget to remove or change the default password. This can lead to security -issues if a user in production is assigned a well-known password. Passwords -should be configurable using an environment variable instead. - -If you do choose to set a default password, ensure that an appropriate warning -message is displayed when the container is started. The message should inform -the user of the value of the default password and explain how to change it, such -as what environment variable to set. - -[discrete] -== Avoid sshd - -It is best to avoid running *sshd* in your image. You can use the `podman exec` or `docker exec` -command to access containers that are running on the local host. Alternatively, -you can use the `oc exec` command or the `oc rsh` -command to access containers that are running on the {product-title} cluster. -Installing and running *sshd* in your image opens up additional vectors for -attack and requirements for security patching. - -[discrete] -== Use volumes for persistent data - -Images should use a https://docs.docker.com/reference/builder/#volume[volume] for persistent data. This way {product-title} mounts the network storage -to the node running the container, and if the container moves to a new node the -storage is reattached to that node. By using the volume for all persistent -storage needs, the content is preserved even if the container is restarted or -moved. If your image writes data to arbitrary locations within the container, -that content might not be preserved. - -All data that needs to be preserved even after the container is destroyed must -be written to a volume. Container engines support a `readonly` flag for -containers which can be used to strictly enforce good practices about not -writing data to ephemeral storage in a container. Designing your image around -that capability now will make it easier to take advantage of it later. - -Furthermore, explicitly defining volumes in your `Dockerfile` makes it easy -for consumers of the image to understand what volumes they must define when -running your image. - -See the -https://kubernetes.io/docs/concepts/storage/volumes/[Kubernetes -documentation] for more information on how volumes are used in {product-title}. - -//// -For more information on how Volumes are used in {product-title}, see https://kubernetes.io/docs/concepts/storage/volumes[this documentation]. (NOTE to docs team: this link should really go to something in the openshift docs, once we have it) -//// - -[NOTE] -==== -Even with persistent volumes, each instance of your image has its own -volume, and the filesystem is not shared between instances. This means the -volume cannot be used to share state in a cluster. -==== - -.Additional resources - -* Docker documentation - https://docs.docker.com/articles/dockerfile_best-practices/[Best practices for writing Dockerfiles] - -* Project Atomic documentation - http://www.projectatomic.io/docs/docker-image-author-guidance/[Guidance for Container Image Authors] diff --git a/modules/images-create-guide-openshift.adoc b/modules/images-create-guide-openshift.adoc deleted file mode 100644 index 4c375b5b3d83..000000000000 --- a/modules/images-create-guide-openshift.adoc +++ /dev/null @@ -1,219 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/create-images.adoc - -[id="images-create-guide-openshift_{context}"] -= {product-title}-specific guidelines - -The following are guidelines that apply when creating container images specifically -for use on {product-title}. -ifdef::openshift-online[] -[discrete] -== Privileges and volume builds - -container images cannot be built using the `VOLUME` directive in the `DOCKERFILE`. -Images using a read/write file system must use persistent volumes or -`emptyDir` volumes instead of local storage. Instead of specifying a volume in -the Dockerfile, specify a directory for local storage and mount either a -persistent volume or `emptyDir` volume to that directory when deploying the pod. -endif::[] - -[discrete] -== Enable images for source-to-image (S2I) - -For images that are intended to run application code provided by a third party, -such as a Ruby image designed to run Ruby code provided by a developer, you can -enable your image to work with the -https://github.com/openshift/source-to-image[Source-to-Image (S2I)] build tool. -S2I is a framework which makes it easy to write images that take application -source code as an input and produce a new image that runs the assembled -application as output. - -For example, this https://github.com/sclorg/s2i-python-container[Python image] -defines S2I scripts for building various versions of Python applications. - -[discrete] -[id="use-uid_{context}"] -== Support arbitrary user ids - -By default, {product-title} runs containers using an arbitrarily assigned user -ID. This provides additional security against processes escaping the container -due to a container engine vulnerability and thereby achieving escalated -permissions on the host node. - -For an image to support running as an arbitrary user, directories and files that -may be written to by processes in the image should be owned by the root group -and be read/writable by that group. Files to be executed should also have group -execute permissions. - -Adding the following to your Dockerfile sets the directory and file permissions -to allow users in the root group to access them in the built image: - ----- -RUN chgrp -R 0 /some/directory && \ - chmod -R g=u /some/directory ----- - -Because the container user is always a member of the root group, the container -user can read and write these files. - -[WARNING] -==== -Care must be taken when altering the directories and file permissions of -sensitive areas of a container (no different than to a normal system). - -If applied to sensitive areas, such as `/etc/passwd`, this can allow the -modification of such files by unintended users potentially exposing the -container or host. CRI-O supports the insertion of random user IDs into the -container's `/etc/passwd`, so changing it's permissions should never be required. -==== - -In addition, the processes running in the container must not listen on -privileged ports (ports below 1024), since they are not running as a -privileged user. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[IMPORTANT] -==== -If your S2I image does not include a *USER* declaration with a numeric user, -your builds will fail by default. To allow images that use either named -users or the root (*0*) user to build in {product-title}, you can add the -project's builder service account -(*system:serviceaccount:<your-project>:builder*) to the *privileged* security -context constraint (SCC). Alternatively, you can allow all images to -run as any user. -==== -endif::[] - -[discrete] -[id="use-services_{context}"] -== Use services for inter-image communication - -For cases where your image needs to communicate with a service provided by -another image, such as a web front end image that needs to access a database -image to store and retrieve data, your image should consume an {product-title} -service. -Services provide a static endpoint for access which does not change as -containers are stopped, started, or moved. In addition, services provide load -balancing for requests. - -//// -For more information see https://kubernetes.io/docs/concepts/services-networking/service/[this documentation]. (NOTE to docs team: this link should really go to something in the openshift docs once we have it) -//// - -[discrete] -== Provide common libraries - -For images that are intended to run application code provided by a third party, -ensure that your image contains commonly used libraries for your platform. In -particular, provide database drivers for common databases used with your -platform. For example, provide JDBC drivers for MySQL and PostgreSQL if you are -creating a Java framework image. Doing so prevents the need for common -dependencies to be downloaded during application assembly time, speeding up -application image builds. It also simplifies the work required by application -developers to ensure all of their dependencies are met. - -[discrete] -[id="use-env-vars_{context}"] -== Use environment variables for configuration - -Users of your image should be able to configure it without having to create a -downstream image based on your image. This means that the runtime configuration -should be handled using environment variables. For a simple configuration, the -running process can consume the environment variables directly. For a more -complicated configuration or for runtimes which do not support this, configure -the runtime by defining a template configuration file that is processed during -startup. During this processing, values supplied using environment variables can -be substituted into the configuration file or used to make decisions about what -options to set in the configuration file. - -It is also possible and recommended to pass secrets such as certificates and -keys into the container using environment variables. This ensures that the -secret values do not end up committed in an image and leaked into a container image -registry. - -Providing environment variables allows consumers of your image to customize -behavior, such as database settings, passwords, and performance tuning, without -having to introduce a new layer on top of your image. Instead, they can simply -define environment variable values when defining a pod and change those settings -without rebuilding the image. - -For extremely complex scenarios, configuration can also be supplied using -volumes that would be mounted into the container at runtime. However, if you -elect to do it this way you must ensure that your image provides clear error -messages on startup when the necessary volume or configuration is not present. - -This topic is related to the Using Services for Inter-image -Communication topic in that configuration like datasources should be defined in -terms of environment variables that provide the service endpoint information. -This allows an application to dynamically consume a datasource service that is -defined in the {product-title} environment without modifying the application -image. - -In addition, tuning should be done by inspecting the *cgroups* settings -for the container. This allows the image to tune itself to the available memory, -CPU, and other resources. For example, Java-based images should tune their heap -based on the *cgroup* maximum memory parameter to ensure they do not -exceed the limits and get an out-of-memory error. - -See the following references for more on how to manage *cgroup* quotas -in containers: - -- Blog article - https://goldmann.pl/blog/2014/09/11/resource-management-in-docker[Resource management in Docker] -- Docker documentation - https://docs.docker.com/engine/admin/runmetrics/[Runtime Metrics] -- Blog article - http://fabiokung.com/2014/03/13/memory-inside-linux-containers[Memory inside Linux containers] - -[discrete] -== Set image metadata - -Defining image metadata helps {product-title} better consume your container images, -allowing {product-title} to create a better experience for developers using your -image. For example, you can add metadata to provide helpful descriptions of your -image, or offer suggestions on other images that may also be needed. - -[discrete] -== Clustering - -You must fully understand what it means to run multiple instances of your image. -In the simplest case, the load balancing function of a service handles routing -traffic to all instances of your image. However, many frameworks must share -information to perform leader election or failover state; for example, -in session replication. - -Consider how your instances accomplish this communication when running in -{product-title}. Although pods can communicate directly with each other, their -IP addresses change anytime the pod starts, stops, or is moved. Therefore, it is -important for your clustering scheme to be dynamic. - -[discrete] -== Logging - -It is best to send all logging to standard out. {product-title} collects -standard out from containers and sends it to the centralized logging service -where it can be viewed. If you must separate log content, prefix the output -with an appropriate keyword, which makes it possible to filter the messages. - -If your image logs to a file, users must use manual operations to enter the -running container and retrieve or view the log file. - -[discrete] -== Liveness and readiness probes - -Document example liveness and readiness probes that can be used with your image. These probes will allow -users to deploy your image with confidence that traffic will not be routed to -the container until it is prepared to handle it, and that the container will be -restarted if the process gets into an unhealthy state. - -[discrete] -== Templates - -Consider providing an example template with -your image. A template will give users an easy way to quickly get your image -deployed with a working configuration. Your template should include the -liveness and readiness probes you documented with the image, for completeness. - - -.Additional resources - -* link:https://docs.docker.com/engine/docker-overview/[Docker basics] -* link:https://docs.docker.com/engine/reference/builder/[Dockerfile reference] -* link:http://www.projectatomic.io/docs/docker-image-author-guidance[Project Atomic Guidance for Container Image Authors] diff --git a/modules/images-create-guidelines.adoc b/modules/images-create-guidelines.adoc deleted file mode 100644 index 333a0e41827d..000000000000 --- a/modules/images-create-guidelines.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/create-images.adoc - -[id="images-create-guidelines_{context}"] -= Learning container best practices - -When creating container images to run on {product-title} -there are a number of best -practices to consider as an image author to ensure a good experience for -consumers of those images. Because images are intended to be immutable and used -as-is, the following guidelines help ensure that your images are highly -consumable and easy to use on {product-title}. diff --git a/modules/images-create-metadata-define.adoc b/modules/images-create-metadata-define.adoc deleted file mode 100644 index 3387102a5708..000000000000 --- a/modules/images-create-metadata-define.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/create-images.adoc - -[id="images-create-metadata-define_{context}"] -= Defining image metadata - -You can use the `LABEL` instruction in a `Dockerfile` to define image -metadata. Labels are similar to environment variables in that they are key value -pairs attached to an image or a container. Labels are different from environment -variable in that they are not visible to the running application and they can -also be used for fast look-up of images and containers. - -link:https://docs.docker.com/engine/reference/builder/#label[Docker -documentation] for more information on the `LABEL` instruction. - -The label names should typically be namespaced. The namespace should be set -accordingly to reflect the project that is going to pick up the labels and use -them. For {product-title} the namespace should be set to `io.openshift` and -for Kubernetes the namespace is `io.k8s`. - -See the https://docs.docker.com/engine/userguide/labels-custom-metadata[Docker custom -metadata] documentation for details about the format. - -.Supported Metadata -[cols="3a,8a",options="header"] -|=== - -|Variable |Description - -|`io.openshift.tags` -|This label contains a list of tags represented as list of comma-separated -string values. The tags are the way to categorize the container images into broad -areas of functionality. Tags help UI and generation tools to suggest relevant -container images during the application creation process. - ----- -LABEL io.openshift.tags mongodb,mongodb24,nosql ----- - -|`io.openshift.wants` -|Specifies a list of tags that the generation tools and the UI might use to -provide relevant suggestions if you do not have the container images with given tags -already. For example, if the container image wants `mysql` and `redis` and you -do not have the container image with `redis` tag, then UI might suggest you to add -this image into your deployment. - ----- -LABEL io.openshift.wants mongodb,redis ----- - -|`io.k8s.description` -|This label can be used to give the container image consumers more detailed -information about the service or functionality this image provides. The UI can -then use this description together with the container image name to provide more -human friendly information to end users. - ----- -LABEL io.k8s.description The MySQL 5.5 Server with master-slave replication support ----- - -|`io.openshift.non-scalable` -|An image might use this variable to suggest that it does not support scaling. -The UI will then communicate this to consumers of that image. Being not-scalable -basically means that the value of `replicas` should initially not be set higher -than 1. - ----- -LABEL io.openshift.non-scalable true ----- - -|`io.openshift.min-memory` and `io.openshift.min-cpu` -|This label suggests how much resources the container image might need to -work properly. The UI might warn the user that deploying this container image may -exceed their user quota. The values must be compatible with -Kubernetes quantity. - ----- -LABEL io.openshift.min-memory 8Gi -LABEL io.openshift.min-cpu 4 ----- - -|=== diff --git a/modules/images-create-metadata.adoc b/modules/images-create-metadata.adoc deleted file mode 100644 index 4b957d9997a4..000000000000 --- a/modules/images-create-metadata.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/create-images.adoc - -[id="images-create-metadata_{context}"] -= Including metadata in images - -Defining image metadata helps {product-title} better consume your container images, allowing {product-title} to create a better experience for developers using your image. For example, you can add metadata to provide helpful descriptions of your image, or offer suggestions on other images that may also be needed. - -This topic only defines the metadata needed by the current set of use cases. Additional metadata or use cases may be added in the future. - -== Defining image metadata -You can use the `LABEL` instruction in a `Dockerfile` to define image -metadata. Labels are similar to environment variables in that they are key value -pairs attached to an image or a container. Labels are different from environment -variable in that they are not visible to the running application and they can -also be used for fast look-up of images and containers. - -link:https://docs.docker.com/engine/reference/builder/#label[Docker -documentation] for more information on the `LABEL` instruction. - -The label names should typically be namespaced. The namespace should be set -accordingly to reflect the project that is going to pick up the labels and use -them. For {product-title} the namespace should be set to `io.openshift` and -for Kubernetes the namespace is `io.k8s`. - -See the https://docs.docker.com/engine/userguide/labels-custom-metadata[Docker custom -metadata] documentation for details about the format. - -.Supported Metadata -[cols="3a,8a",options="header"] -|=== - -|Variable |Description - -|`io.openshift.tags` -|This label contains a list of tags represented as a list of comma-separated string values. The tags are the way to categorize the container images into broad areas of functionality. Tags help UI and generation tools to suggest relevant container images during the application creation process. - ----- -LABEL io.openshift.tags mongodb,mongodb24,nosql ----- - -|`io.openshift.wants` -|Specifies a list of tags that the generation tools and the UI might use to provide relevant suggestions if you do not have the container images with specified tags already. For example, if the container image wants `mysql` and `redis` and you do not have the container image with `redis` tag, then UI might suggest you to add this image into your deployment. - ----- -LABEL io.openshift.wants mongodb,redis ----- - -|`io.k8s.description` -|This label can be used to give the container image consumers more detailed -information about the service or functionality this image provides. The UI can -then use this description together with the container image name to provide more -human friendly information to end users. - ----- -LABEL io.k8s.description The MySQL 5.5 Server with master-slave replication support ----- - -|`io.openshift.non-scalable` -|An image might use this variable to suggest that it does not support scaling. -The UI will then communicate this to consumers of that image. Being not-scalable -basically means that the value of `replicas` should initially not be set higher -than 1. - ----- -LABEL io.openshift.non-scalable true ----- - -|`io.openshift.min-memory` and `io.openshift.min-cpu` -|This label suggests how much resources the container image might need to -work properly. The UI might warn the user that deploying this container image may -exceed their user quota. The values must be compatible with -Kubernetes quantity. - ----- -LABEL io.openshift.min-memory 8Gi -LABEL io.openshift.min-cpu 4 ----- - -|=== diff --git a/modules/images-create-s2i-build.adoc b/modules/images-create-s2i-build.adoc deleted file mode 100644 index c17dc3165035..000000000000 --- a/modules/images-create-s2i-build.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/build-strategies.adoc - -[id="images-create-s2i-build_{context}"] -= Understanding the source-to-image build process - -The build process consists of the following three fundamental elements, which are combined into a final container image: - -* Sources -* Source-to-image (S2I) scripts -* Builder image - -During the build process, S2I must place sources and scripts inside the builder image. To do so, S2I creates a `tar` file that contains the sources and scripts, then streams that file into the builder image. Before executing the `assemble` script, S2I un-tars that file and places its contents into the location specified by the `io.openshift.s2i.destination` label from the builder image, with the default location being the `/tmp` directory. - -For this process to happen, your image must supply the `tar` archiving utility, the `tar` command available in `$PATH`, and the command line interpreter, the -`/bin/sh` command. This allows your image to use the fastest possible build path. If the `tar` or `/bin/sh` command is not available, the `s2i build` process is forced to automatically perform an additional container build to put both the sources and the scripts inside the image, and only then run the usual build. - -//// -See the following diagram for the basic S2I build workflow: - -.Build Workflow -image::s2i-flow.png[S2I workflow] - -Run build's responsibility is to un-tar the sources, scripts and artifacts -(if such exist) and invoke the `assemble` script. If this is the second run -(after catching `tar` or `/bin/sh` not found error) it is responsible only -for invoking `assemble` script, since both scripts and sources are already there. -//// diff --git a/modules/images-create-s2i-scripts.adoc b/modules/images-create-s2i-scripts.adoc deleted file mode 100644 index fdef7e0b3d1e..000000000000 --- a/modules/images-create-s2i-scripts.adoc +++ /dev/null @@ -1,150 +0,0 @@ -// Module included in the following assemblies: -// -//* builds/build-strategies.adoc - -[id="images-create-s2i-scripts_{context}"] -= How to write source-to-image scripts - -You can write source-to-image (S2I) scripts in any programming language, as long as the scripts are executable inside the builder image. S2I supports multiple options providing `assemble`/`run`/`save-artifacts` scripts. All of these locations are checked on each build in the following order: - -. A script specified in the build configuration. -. A script found in the application source `.s2i/bin` directory. -. A script found at the default image URL with the `io.openshift.s2i.scripts-url` label. - -Both the `io.openshift.s2i.scripts-url` label specified in the image and the script specified in a build configuration can take one of the following forms: - -* `image:///path_to_scripts_dir`: absolute path inside the image to a directory where the S2I scripts are located. -* `$$file:///path_to_scripts_dir$$`: relative or absolute path to a directory on the host where the S2I scripts are located. -* `http(s)://path_to_scripts_dir`: URL to a directory where the S2I scripts are located. - -.S2I Scripts -[cols="3a,8a",options="header"] -|=== - -|Script |Description - -|`assemble` -|The `assemble` script builds the application artifacts from a source and places them into appropriate directories inside the image. This script is required. The workflow for this script is: - -. Restore build artifacts. If you want to support incremental builds, make sure to define `save-artifacts` as well. This is optional. -. Place the application source in the desired location. -. Build the application artifacts. -. Install the artifacts into locations appropriate for them to run. - -|`run` -|The `run` script executes your application. This script is required. - -|`save-artifacts` -|The `save-artifacts` script gathers all dependencies that can speed up the build processes that follow. This script is optional. For example: - -* For Ruby, `gems` installed by Bundler. -* For Java, `.m2` contents. - -These dependencies are gathered into a `tar` file and streamed to the standard output. - -|`usage` -|The `usage` script allows you to inform the user how to properly use your image. This script is optional. - -|`test/run` -|The `test/run` script allows you to create a process to check if the image is working correctly. This script is optional. The proposed flow of that process is: - -. Build the image. -. Run the image to verify the `usage` script. -. Run `s2i build` to verify the `assemble` script. -. Optional: Run `s2i build` again to verify the `save-artifacts` and `assemble` scripts save and restore artifacts functionality. -. Run the image to verify the test application is working. - -The suggested location to put the test application built by your `test/run` script is the `test/test-app` directory in your image repository. -|=== - -== Example S2I Scripts - -The following example S2I scripts are written in Bash. Each example assumes its `tar` contents are unpacked into the `/tmp/s2i` directory. - -.`assemble` script: -[source,terminal] ----- -#!/bin/bash - -# restore build artifacts -if [ "$(ls /tmp/s2i/artifacts/ 2>/dev/null)" ]; then - mv /tmp/s2i/artifacts/* $HOME/. -fi - -# move the application source -mv /tmp/s2i/src $HOME/src - -# build application artifacts -pushd ${HOME} -make all - -# install the artifacts -make install -popd ----- - - -.`run` script: -[source,terminal] ----- -#!/bin/bash - -# run the application -/opt/application/run.sh ----- - -.`save-artifacts` script: -[source,terminal] ----- -#!/bin/bash - -pushd ${HOME} -if [ -d deps ]; then - # all deps contents to tar stream - tar cf - deps -fi -popd - ----- - -.`usage` script: -[source,terminal] ----- -#!/bin/bash - -# inform the user how to use the image -cat <<EOF -This is a S2I sample builder image, to use it, install -https://github.com/openshift/source-to-image -EOF ----- - - -//// -== Using Images with ONBUILD Instructions -The `ONBUILD` instructions can be found in many official container images. For -example: - -* Ruby -* Node.js -* Python - -See the link:https://docs.docker.com/engine/reference/builder/#onbuild[Docker -documentation] for more information on `ONBUILD`. - -Upon startup, S2I detects whether the builder image contains `sh` and `tar` binaries -which are necessary for the S2I process to inject build inputs. If the builder image -does not contain these prerequisites, it will attempt to instead perform a container build -to layer the inputs. If the builder image includes `ONBUILD` instructions, S2I -will instead fail the build because the `ONBUILD` instructions would be executed -during the layering process, and that equates to performing a generic container -build which is less secure than an S2I build and requires explicit permissions. - -Therefore you should ensure that your S2I builder image either does not contain -`ONBUILD` instructions, or ensure that it has the necessary `sh` and `tar` binary -prerequisites. - -.Additional resources - -* link:https://blog.openshift.com/create-s2i-builder-image/[S2I Image Creation Tutorial] -//// diff --git a/modules/images-create-s2i.adoc b/modules/images-create-s2i.adoc deleted file mode 100644 index 771b73472b81..000000000000 --- a/modules/images-create-s2i.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/build-strategies.adoc - -[id="images-create-s2i_{context}"] -= Creating images from source code with source-to-image - -Source-to-image (S2I) is a framework that makes it easy to write images that take application source code as an input and produce a new image that runs the assembled application as output. - -The main advantage of using S2I for building reproducible container images is the ease of use for developers. As a builder image author, you must understand two basic concepts in order for your images to provide the best possible S2I performance, the build process and S2I scripts. diff --git a/modules/images-custom.adoc b/modules/images-custom.adoc deleted file mode 100644 index c0f0d833fa96..000000000000 --- a/modules/images-custom.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * builds/build-strategies.adoc - -[id="images-custom_{context}"] -= Using custom builder images - -{product-title}'s custom build strategy enables you to define a specific builder image responsible for the entire build process. When you need a build to produce individual artifacts such as packages, JARs, WARs, installable ZIPs, or base images, use a custom builder image using the custom build strategy. - -A custom builder image is a plain container image embedded with build process logic, which is used for building artifacts such as RPMs or base container images. - -Additionally, the custom builder allows implementing any extended build process, such as a CI/CD flow that runs unit or integration tests. - -[id="images-custom-builder-image-ref_{context}"] -== Custom builder image - -Upon invocation, a custom builder image receives the following environment variables with the information needed to proceed with the build: - -.Custom Builder Environment Variables -[cols="1,3",options="header"] -|=== - -|Variable Name |Description - -|`BUILD` -|The entire serialized JSON of the `Build` object definition. If you must use a specific API version for serialization, you can set the `buildAPIVersion` parameter in the custom strategy specification of the build configuration. - -|`SOURCE_REPOSITORY` -|The URL of a Git repository with source to be built. - -|`SOURCE_URI` -|Uses the same value as `SOURCE_REPOSITORY`. Either can be used. - -|`SOURCE_CONTEXT_DIR` -|Specifies the subdirectory of the Git repository to be used when building. Only present if defined. - -|`SOURCE_REF` -|The Git reference to be built. - -|`ORIGIN_VERSION` -|The version of the {product-title} master that created this build object. - -|`OUTPUT_REGISTRY` -|The container image registry to push the image to. - -|`OUTPUT_IMAGE` -|The container image tag name for the image being built. - -|`PUSH_DOCKERCFG_PATH` -|The path to the container registry credentials for running a `podman push` operation. - -|=== - -[id="images-custom-builder-flow_{context}"] -== Custom builder workflow - -Although custom builder image authors have flexibility in defining the build process, your builder image must adhere to the following required steps necessary for running a build inside of {product-title}: - -. The `Build` object definition contains all the necessary information about input parameters for the build. -. Run the build process. -. If your build produces an image, push it to the output location of the build if it is defined. Other output locations can be passed with environment variables. diff --git a/modules/images-getting-info-about-imagestreams.adoc b/modules/images-getting-info-about-imagestreams.adoc deleted file mode 100644 index ab7cda49ba41..000000000000 --- a/modules/images-getting-info-about-imagestreams.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-getting-info-about-imagestreams_{context}"] -= Getting information about imagestreams - -You can get general information about the imagestream and detailed information -about all the tags it is pointing to. - -.Procedure - -* Get general information about the imagestream -and detailed information about all the tags it is pointing to: -+ -[source,terminal] ----- -$ oc describe is/<image-name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe is/python ----- -+ -.Example output -[source,terminal] ----- -Name: python -Namespace: default -Created: About a minute ago -Labels: <none> -Annotations: openshift.io/image.dockerRepositoryCheck=2017-10-02T17:05:11Z -Docker Pull Spec: docker-registry.default.svc:5000/default/python -Image Lookup: local=false -Unique Images: 1 -Tags: 1 - -3.5 - tagged from centos/python-35-centos7 - - * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 - About a minute ago ----- - -* Get all the information available about particular imagestreamtag: -+ -[source,terminal] ----- -$ oc describe istag/<image-stream>:<tag-name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe istag/python:latest ----- -+ -.Example output -[source,terminal] ----- -Image Name: sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 -Docker Image: centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 -Name: sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 -Created: 2 minutes ago -Image Size: 251.2 MB (first layer 2.898 MB, last binary layer 72.26 MB) -Image Created: 2 weeks ago -Author: <none> -Arch: amd64 -Entrypoint: container-entrypoint -Command: /bin/sh -c $STI_SCRIPTS_PATH/usage -Working Dir: /opt/app-root/src -User: 1001 -Exposes Ports: 8080/tcp -Docker Labels: build-date=20170801 ----- - -[NOTE] -==== -More information is output than shown. -==== diff --git a/modules/images-id.adoc b/modules/images-id.adoc deleted file mode 100644 index 7dc92bf1a679..000000000000 --- a/modules/images-id.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.aodc - -[id="images-id_{context}"] -= Image IDs - -An image ID is a SHA (Secure Hash Algorithm) code that can be used to -pull an image. A SHA image ID cannot change. A specific SHA identifier always -references the exact same container image content. For example: - ----- -docker.io/openshift/jenkins-2-centos7@sha256:ab312bda324 ----- diff --git a/modules/images-image-pull-policy-overview.adoc b/modules/images-image-pull-policy-overview.adoc deleted file mode 100644 index 6d6cded4fcf8..000000000000 --- a/modules/images-image-pull-policy-overview.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-pull-policy - -[id="images-image-pull-policy_{context}"] -= Image pull policy overview - -When {product-title} creates containers, it uses the container's -`imagePullPolicy` to determine if the image should be pulled prior to starting -the container. There are three possible values for `imagePullPolicy`: - -.`imagePullPolicy` values -[width="50%",options="header"] -|=== -|Value |Description - -|`Always` -|Always pull the image. - -|`IfNotPresent` -|Only pull the image if it does not already exist on the node. - -|`Never` -|Never pull the image. -|=== - - -If a container's `imagePullPolicy` parameter is not specified, {product-title} -sets it based on the image's tag: - -. If the tag is `latest`, {product-title} defaults `imagePullPolicy` to `Always`. -. Otherwise, {product-title} defaults `imagePullPolicy` to `IfNotPresent`. diff --git a/modules/images-image-registry-about.adoc b/modules/images-image-registry-about.adoc deleted file mode 100644 index 015a06d4bbca..000000000000 --- a/modules/images-image-registry-about.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.adoc - -[id="images-image-registry-about_{context}"] -= Image registry - -An *image registry* is a content server that can store and serve -container images. For example: - ----- -registry.redhat.io ----- - -A registry contains a collection of one or more image repositories, which -contain one or more tagged images. Red Hat provides a registry at -`registry.redhat.io` for subscribers. {product-title} can also supply its own -internal registry for managing custom container images. diff --git a/modules/images-imagestream-adding-tags.adoc b/modules/images-imagestream-adding-tags.adoc deleted file mode 100644 index 0a4d7e088a4a..000000000000 --- a/modules/images-imagestream-adding-tags.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-imagestream-adding-tags_{context}"] -= Adding tags to an imagestream - -You can add additional tags to imagestreams. - -.Procedure - -* Add a tag that points to one of the existing tags by using the `oc tag` -command: -+ -[source,terminal] ----- -$ oc tag <image-name:tag1> <image-name:tag2> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc tag python:3.5 python:latest ----- -+ -.Example output -[source,terminal] ----- -Tag python:latest set to python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25. ----- - -* Confirm the imagestream has two tags, one (`3.5`) pointing at the external -container image and another tag (`latest`) pointing to the same image because it -was created based on the first tag. -+ -[source,terminal] ----- -$ oc describe is/python ----- -+ -.Example output -[source,terminal] ----- -Name: python -Namespace: default -Created: 5 minutes ago -Labels: <none> -Annotations: openshift.io/image.dockerRepositoryCheck=2017-10-02T17:05:11Z -Docker Pull Spec: docker-registry.default.svc:5000/default/python -Image Lookup: local=false -Unique Images: 1 -Tags: 2 - -latest - tagged from python@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 - - * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 - About a minute ago - -3.5 - tagged from centos/python-35-centos7 - - * centos/python-35-centos7@sha256:49c18358df82f4577386404991c51a9559f243e0b1bdc366df25 - 5 minutes ago ----- diff --git a/modules/images-imagestream-configure.adoc b/modules/images-imagestream-configure.adoc deleted file mode 100644 index 024ec3dcb07b..000000000000 --- a/modules/images-imagestream-configure.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-imagestream-configure_{context}"] -= Configuring imagestreams - -ifdef::openshift-origin,openshift-online,openshift-enterprise,openshift-dedicated[] -An `ImageStream` object file contains the following elements. -endif::openshift-origin,openshift-online,openshift-enterprise,openshift-dedicated[] - -[id="image-stream-object-definition_{context}"] -.Imagestream object definition - -[source,yaml] ----- -apiVersion: v1 -kind: ImageStream -metadata: - annotations: - openshift.io/generated-by: OpenShiftNewApp - creationTimestamp: 2017-09-29T13:33:49Z - generation: 1 - labels: - app: ruby-sample-build - template: application-template-stibuild - name: origin-ruby-sample <1> - namespace: test - resourceVersion: "633" - selflink: /oapi/v1/namespaces/test/imagestreams/origin-ruby-sample - uid: ee2b9405-c68c-11e5-8a99-525400f25e34 -spec: {} -status: - dockerImageRepository: 172.30.56.218:5000/test/origin-ruby-sample <2> - tags: - - items: - - created: 2017-09-02T10:15:09Z - dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d <3> - generation: 2 - image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 <4> - - created: 2017-09-29T13:40:11Z - dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 - generation: 1 - image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d - tag: latest <5> ----- - -<1> The name of the imagestream. -<2> Docker repository path where new images can be pushed to add/update them in this imagestream. -<3> The SHA identifier that this imagestreamtag currently references. Resources that reference this imagestreamtag use this identifier. -<4> The SHA identifier that this imagestreamtag previously referenced. Can be used to rollback to an older image. -<5> The imagestreamtag name. diff --git a/modules/images-imagestream-external-image-tags.adoc b/modules/images-imagestream-external-image-tags.adoc deleted file mode 100644 index 692a3673b01c..000000000000 --- a/modules/images-imagestream-external-image-tags.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-imagestreams-external-image-tags_{context}"] -= Adding tags for an external image - -You can add tags for external images. - -.Procedure - -* Add tags pointing to internal or external images, by using the `oc tag` command - for all tag-related operations: -+ -[source,terminal] ----- -$ oc tag <repository/image> <image-name:tag> ----- -+ -For example, this command maps the `docker.io/python:3.6.0` image to the `3.6` -tag in the `python` imagestream. -+ -[source,terminal] ----- -$ oc tag docker.io/python:3.6.0 python:3.6 ----- -+ -.Example output -[source,terminal] ----- -Tag python:3.6 set to docker.io/python:3.6.0. ----- -+ -If the external image is secured, you must create a secret with -credentials for accessing that registry. diff --git a/modules/images-imagestream-image.adoc b/modules/images-imagestream-image.adoc deleted file mode 100644 index 11df8abf7cd3..000000000000 --- a/modules/images-imagestream-image.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.aodc - -[id="images-imagestream-image_{context}"] -= Imagestream images - -An imagestream image allows you to retrieve a specific -container image from a particular imagestream where it is tagged. An image -stream image is an API resource object that pulls together some metadata about a -particular image SHA identifier. diff --git a/modules/images-imagestream-import-images-private-registry.adoc b/modules/images-imagestream-import-images-private-registry.adoc deleted file mode 100644 index 5ce986912335..000000000000 --- a/modules/images-imagestream-import-images-private-registry.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// * assembly/openshift_images/managing-image-streams.adoc - -[id="images-imagestream-import-images-private-registry_{context}"] -= Importing images and image streams from private registries - -An image stream can be configured to import tag and image metadata from private image registries requiring authentication. This procedures applies if you change the registry that the Cluster Samples Operator uses to pull content from to something other than link:registry.redhat.io[registry.redhat.io]. - -[NOTE] -==== -When importing from insecure or secure registries, the registry URL defined in the secret must include the `:80` port suffix or the secret is not used when attempting to import from the registry. -==== - -.Procedure - -. You must create a `secret` object that is used to store your credentials by entering the following command: -+ -[source,terminal] ----- -$ oc create secret generic <secret_name> --from-file=.dockerconfigjson=<file_absolute_path> --type=kubernetes.io/dockerconfigjson ----- -+ -. After the secret is configured, create the new image stream or enter the `oc import-image` command: -+ -[source,terminal] ----- -$ oc import-image <imagestreamtag> --from=<image> --confirm ----- -+ -During the import process, {product-title} picks up the secrets and provides them to the remote party. diff --git a/modules/images-imagestream-import.adoc b/modules/images-imagestream-import.adoc deleted file mode 100644 index 80940927279e..000000000000 --- a/modules/images-imagestream-import.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-imagestreams-import_{context}"] -= Configuring periodic importing of imagestreamtags - -When working with an external container image registry, to periodically -re-import an image, for example to get latest security updates, you can use the -`--scheduled` flag. - -.Procedure - -. Schedule importing images: -+ -[source,terminal] ----- -$ oc tag <repository/image> <image-name:tag> --scheduled ----- -+ -For example: -+ -[source,terminal] ----- -$ oc tag docker.io/python:3.6.0 python:3.6 --scheduled ----- -+ -.Example output -[source,terminal] ----- -Tag python:3.6 set to import docker.io/python:3.6.0 periodically. ----- -+ -This command causes {product-title} to periodically update this particular image -stream tag. This period is a cluster-wide setting set to 15 minutes by default. - -. Remove the periodic check, re-run above command but omit the `--scheduled` flag. -This will reset its behavior to default. -+ -[source,terminal] ----- -$ oc tag <repositiory/image> <image-name:tag> ----- diff --git a/modules/images-imagestream-mapping.adoc b/modules/images-imagestream-mapping.adoc deleted file mode 100644 index 6b439ed10d11..000000000000 --- a/modules/images-imagestream-mapping.adoc +++ /dev/null @@ -1,136 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-imagestream-mapping_{context}"] -= Imagestream mapping - -When the integrated registry receives a new image, it creates and sends an image -stream mapping to {product-title}, providing the image's project, name, tag, and -image metadata. - -[NOTE] -==== -Configuring imagestream mappings is an advanced feature. -==== - -This information is used to create a new image (if it does not already exist) -and to tag the image into the imagestream. {product-title} stores complete -metadata about each image, such as commands, entry point, and environment -variables. Images in {product-title} are immutable and the maximum name length -is 63 characters. - -The following imagestream mapping example results in an image being tagged as -*test/origin-ruby-sample:latest*: - -.Imagestream mapping object definition - -[source,yaml] ----- -apiVersion: v1 -kind: ImageStreamMapping -metadata: - creationTimestamp: null - name: origin-ruby-sample - namespace: test -tag: latest -image: - dockerImageLayers: - - name: sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef - size: 0 - - name: sha256:ee1dd2cb6df21971f4af6de0f1d7782b81fb63156801cfde2bb47b4247c23c29 - size: 196634330 - - name: sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef - size: 0 - - name: sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef - size: 0 - - name: sha256:ca062656bff07f18bff46be00f40cfbb069687ec124ac0aa038fd676cfaea092 - size: 177723024 - - name: sha256:63d529c59c92843c395befd065de516ee9ed4995549f8218eac6ff088bfa6b6e - size: 55679776 - - name: sha256:92114219a04977b5563d7dff71ec4caa3a37a15b266ce42ee8f43dba9798c966 - size: 11939149 - dockerImageMetadata: - Architecture: amd64 - Config: - Cmd: - - /usr/libexec/s2i/run - Entrypoint: - - container-entrypoint - Env: - - RACK_ENV=production - - OPENSHIFT_BUILD_NAMESPACE=test - - OPENSHIFT_BUILD_SOURCE=https://github.com/openshift/ruby-hello-world.git - - EXAMPLE=sample-app - - OPENSHIFT_BUILD_NAME=ruby-sample-build-1 - - PATH=/opt/app-root/src/bin:/opt/app-root/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin - - STI_SCRIPTS_URL=image:///usr/libexec/s2i - - STI_SCRIPTS_PATH=/usr/libexec/s2i - - HOME=/opt/app-root/src - - BASH_ENV=/opt/app-root/etc/scl_enable - - ENV=/opt/app-root/etc/scl_enable - - PROMPT_COMMAND=. /opt/app-root/etc/scl_enable - - RUBY_VERSION=2.2 - ExposedPorts: - 8080/tcp: {} - Labels: - build-date: 2015-12-23 - io.k8s.description: Platform for building and running Ruby 2.2 applications - io.k8s.display-name: 172.30.56.218:5000/test/origin-ruby-sample:latest - io.openshift.build.commit.author: Ben Parees <bparees@users.noreply.github.com> - io.openshift.build.commit.date: Wed Jan 20 10:14:27 2016 -0500 - io.openshift.build.commit.id: 00cadc392d39d5ef9117cbc8a31db0889eedd442 - io.openshift.build.commit.message: 'Merge pull request #51 from php-coder/fix_url_and_sti' - io.openshift.build.commit.ref: master - io.openshift.build.image: centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e - io.openshift.build.source-location: https://github.com/openshift/ruby-hello-world.git - io.openshift.builder-base-version: 8d95148 - io.openshift.builder-version: 8847438ba06307f86ac877465eadc835201241df - io.openshift.s2i.scripts-url: image:///usr/libexec/s2i - io.openshift.tags: builder,ruby,ruby22 - io.s2i.scripts-url: image:///usr/libexec/s2i - license: GPLv2 - name: CentOS Base Image - vendor: CentOS - User: "1001" - WorkingDir: /opt/app-root/src - Container: 86e9a4a3c760271671ab913616c51c9f3cea846ca524bf07c04a6f6c9e103a76 - ContainerConfig: - AttachStdout: true - Cmd: - - /bin/sh - - -c - - tar -C /tmp -xf - && /usr/libexec/s2i/assemble - Entrypoint: - - container-entrypoint - Env: - - RACK_ENV=production - - OPENSHIFT_BUILD_NAME=ruby-sample-build-1 - - OPENSHIFT_BUILD_NAMESPACE=test - - OPENSHIFT_BUILD_SOURCE=https://github.com/openshift/ruby-hello-world.git - - EXAMPLE=sample-app - - PATH=/opt/app-root/src/bin:/opt/app-root/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin - - STI_SCRIPTS_URL=image:///usr/libexec/s2i - - STI_SCRIPTS_PATH=/usr/libexec/s2i - - HOME=/opt/app-root/src - - BASH_ENV=/opt/app-root/etc/scl_enable - - ENV=/opt/app-root/etc/scl_enable - - PROMPT_COMMAND=. /opt/app-root/etc/scl_enable - - RUBY_VERSION=2.2 - ExposedPorts: - 8080/tcp: {} - Hostname: ruby-sample-build-1-build - Image: centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e - OpenStdin: true - StdinOnce: true - User: "1001" - WorkingDir: /opt/app-root/src - Created: 2016-01-29T13:40:00Z - DockerVersion: 1.8.2.fc21 - Id: 9d7fd5e2d15495802028c569d544329f4286dcd1c9c085ff5699218dbaa69b43 - Parent: 57b08d979c86f4500dc8cad639c9518744c8dd39447c055a3517dc9c18d6fccd - Size: 441976279 - apiVersion: "1.0" - kind: DockerImage - dockerImageMetadataVersion: "1.0" - dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d ----- diff --git a/modules/images-imagestream-remove-tag.adoc b/modules/images-imagestream-remove-tag.adoc deleted file mode 100644 index b408ce1be3dc..000000000000 --- a/modules/images-imagestream-remove-tag.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-imagestreams-remove-tag_{context}"] -= Removing imagestreamtags - -You can remove old tags from an imagestream. - -.Procedure - -* Remove old tags from an imagestream: -+ -[source,terminal] ----- -$ oc tag -d <image-name:tag> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc tag -d python:3.5 ----- -+ -.Example output -[source,terminal] ----- -Deleted tag default/python:3.5. ----- diff --git a/modules/images-imagestream-tag.adoc b/modules/images-imagestream-tag.adoc deleted file mode 100644 index 0f3d15a54f91..000000000000 --- a/modules/images-imagestream-tag.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.aodc - -[id="images-imagestream-tag_{context}"] -= Imagestreamtags - -An imagestreamtag is a named pointer to an image in an imagestream. An image -stream tag is similar to a container image tag. diff --git a/modules/images-imagestream-trigger.adoc b/modules/images-imagestream-trigger.adoc deleted file mode 100644 index 7bb12efde3c8..000000000000 --- a/modules/images-imagestream-trigger.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.aodc - -[id="images-imagestream-trigger_{context}"] -= Imagestream triggers - -An imagestream trigger causes a specific action when an imagestreamtag -changes. For example, importing can cause the value of the tag to change, which -causes a trigger to fire when there are Deployments, Builds, or other resources -listening for those. diff --git a/modules/images-imagestream-update-tag.adoc b/modules/images-imagestream-update-tag.adoc deleted file mode 100644 index 5f3fb412853a..000000000000 --- a/modules/images-imagestream-update-tag.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-imagestreams-update-tag_{context}"] -= Updating imagestreamtags - -You can update a tag to reflect another tag in an imagestream. - -.Procedure - -* Update a tag: -+ -[source,terminal] ----- -$ oc tag <image-name:tag> <image-name:latest> ----- -+ -For example, the following updates the `latest` tag to reflect the `3.6` tag in -an imagestream: -+ -[source,terminal] ----- -$ oc tag python:3.6 python:latest ----- -+ -.Example output -[source,terminal] ----- -Tag python:latest set to python@sha256:438208801c4806548460b27bd1fbcb7bb188273d13871ab43f. ----- diff --git a/modules/images-imagestream-use.adoc b/modules/images-imagestream-use.adoc deleted file mode 100644 index 7909e8e28e59..000000000000 --- a/modules/images-imagestream-use.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.aodc -// * openshift_images/image-streams-managing.adoc - -[id="images-imagestream-use_{context}"] -= Using imagestreams - -An imagestream and its associated tags provide an abstraction for referencing -container images from within {product-title}. The imagestream and its tags -allow you to see what images are available and ensure that you are using the -specific image you need even if the image in the repository changes. - -Imagestreams do not contain actual image data, but present a single virtual -view of related images, similar to an image repository. - -You can configure Builds and Deployments to watch an imagestream for -notifications when new images are added and react by performing a Build or -Deployment, respectively. - -For example, if a Deployment is using a certain image and a new version of that -image is created, a Deployment could be automatically performed to pick up the -new version of the image. - -However, if the imagestreamtag used by the Deployment or Build is not updated, -then even if the container image in the container image registry is updated, the -Build or Deployment will continue using the previous, presumably known good -image. - -The source images can be stored in any of the following: - -* {product-title}'s integrated registry. -* An external registry, for example `registry.redhat.io` or `hub.docker.com`. -* Other imagestreams in the {product-title} cluster. - -When you define an object that references an imagestreamtag (such as a Build -or Deployment configuration), you point to an imagestreamtag, not the Docker -repository. When you Build or Deploy your application, {product-title} queries -the Docker repository using the imagestreamtag to locate the associated ID of -the image and uses that exact image. - -The imagestream metadata is stored in the etcd instance along with other -cluster information. - -Using imagestreams has several significant benefits: - -* You can tag, rollback a tag, and quickly deal with images, without having to -re-push using the command line. - -* You can trigger Builds and Deployments when a new image is pushed to the -registry. Also, {product-title} has generic triggers for other resources, such -as Kubernetes objects. - -* You can mark a tag for periodic re-import. If the source image has changed, that -change is picked up and reflected in the imagestream, which triggers the Build -and/or Deployment flow, depending upon the Build or Deployment configuration. - -* You can share images using fine-grained access control and quickly distribute -images across your teams. - -* If the source image changes, the imagestreamtag will still point to a -known-good version of the image, ensuring that your application will not break -unexpectedly. - -* You can configure security around who can view and use the images through -permissions on the `ImageStream` objects. - -* Users that lack permission to read or list images on the cluster level can still -retrieve the images tagged in a project using imagestreams. diff --git a/modules/images-managing-images-enabling-imagestreams-kube.adoc b/modules/images-managing-images-enabling-imagestreams-kube.adoc deleted file mode 100644 index b7edf1f5716a..000000000000 --- a/modules/images-managing-images-enabling-imagestreams-kube.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/managing-images/using-imagestreams-with-kube-resources.adoc - - -[id="images-managing-images-enabling-imagestreams-kube_{context}"] -= Enabling imagestreams with Kubernetes resources - -When using imagestreams with Kubernetes resources, you can only reference imagestreams that reside in the same project as the resource. The imagestream reference must consist of a single segment value, for example `ruby:2.5`, where `ruby` is the name of an imagestream that has a tag named `2.5` and resides in the same project as the resource making the reference. - -[NOTE] -==== -This feature can not be used in the `default` namespace, nor in any `openshift-` or `kube-` namespace. -==== - -There are two ways to enable imagestreams with Kubernetes resources: - -* Enabling imagestream resolution on a specific resource. This allows only this resource to use the imagestream name in the image field. -* Enabling imagestream resolution on an imagestream. This allows all resources pointing to this imagestream to use it in the image field. - -.Procedure - -You can use `oc set image-lookup` to enable imagestream resolution on a specific resource or imagestream resolution on an imagestream. - -. To allow all resources to reference the imagestream named `mysql`, enter the following command: -+ -[source,terminal] ----- -$ oc set image-lookup mysql ----- -+ -This sets the `Imagestream.spec.lookupPolicy.local` field to true. -+ -.Imagestream with image lookup enabled -[source,yaml] ----- -apiVersion: v1 -kind: ImageStream -metadata: - annotations: - openshift.io/display-name: mysql - name: mysql - namespace: myproject -spec: - lookupPolicy: - local: true ----- -+ -When enabled, the behavior is enabled for all tags within the imagestream. -+ -. Then you can query the imagestreams and see if the option is set: -+ -[source,terminal] ----- -$ oc set image-lookup imagestream --list ----- - -You can enable image lookup on a specific resource. - -* To allow the Kubernetes deployment named `mysql` to use imagestreams, run the following command: -+ -[source,terminal] ----- -$ oc set image-lookup deploy/mysql ----- -+ -This sets the `alpha.image.policy.openshift.io/resolve-names` annotation -on the deployment. -+ -.Deployment with image lookup enabled -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: mysql - namespace: myproject -spec: - replicas: 1 - template: - metadata: - annotations: - alpha.image.policy.openshift.io/resolve-names: '*' - spec: - containers: - - image: mysql:latest - imagePullPolicy: Always - name: mysql ----- - -You can disable image lookup. - -* To disable image lookup, pass `--enabled=false`: -+ -[source,terminal] ----- -$ oc set image-lookup deploy/mysql --enabled=false ----- diff --git a/modules/images-managing-overview.adoc b/modules/images-managing-overview.adoc deleted file mode 100644 index 74febc4637c1..000000000000 --- a/modules/images-managing-overview.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift-images/managing-images.adoc - -[id="images-managing-overview_{context}"] -= Images overview - -An imagestream comprises any number of container images identified by tags. It -presents a single virtual view of related images, similar to a container image -repository. - -By watching an imagestream, builds and deployments can receive notifications -when new images are added or modified and react by performing a build or -deployment, respectively. diff --git a/modules/images-other-jenkins-agent-env-var.adoc b/modules/images-other-jenkins-agent-env-var.adoc deleted file mode 100644 index 67035521870b..000000000000 --- a/modules/images-other-jenkins-agent-env-var.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins-agent.adoc - -[id="images-other-jenkins-agent-env-var_{context}"] -= Jenkins agent environment variables - -Each Jenkins agent container can be configured with the following environment -variables. - -[options="header"] -|=== -| Variable | Definition | Example values and settings - -|`JAVA_MAX_HEAP_PARAM`, -`CONTAINER_HEAP_PERCENT`, -`JENKINS_MAX_HEAP_UPPER_BOUND_MB` -|These values control the maximum heap size of the Jenkins JVM. If -`JAVA_MAX_HEAP_PARAM` is set, its value takes -precedence. Otherwise, the maximum heap size is dynamically calculated as -`CONTAINER_HEAP_PERCENT` of the container -memory limit, optionally capped at `JENKINS_MAX_HEAP_UPPER_BOUND_MB` MiB. - -By default, the maximum heap size of the Jenkins JVM is set to 50% of the -container memory limit with no cap. -|`JAVA_MAX_HEAP_PARAM` example setting: `-Xmx512m` - -`CONTAINER_HEAP_PERCENT` default: `0.5`, or 50% - -`JENKINS_MAX_HEAP_UPPER_BOUND_MB` example setting: `512 MiB` - -|`JAVA_INITIAL_HEAP_PARAM`, -`CONTAINER_INITIAL_PERCENT` -|These values control the initial heap size of the Jenkins JVM. If -`JAVA_INITIAL_HEAP_PARAM` is set, its value takes -precedence. Otherwise, the initial heap size is dynamically calculated as -`CONTAINER_INITIAL_PERCENT` of the -dynamically calculated maximum heap size. - -By default, the JVM sets the initial heap size. -|`JAVA_INITIAL_HEAP_PARAM` example setting: `-Xms32m` - -`CONTAINER_INITIAL_PERCENT` example setting: `0.1`, or 10% - -|`CONTAINER_CORE_LIMIT` -|If set, specifies an integer number of cores used for sizing numbers of internal -JVM threads. -|Example setting: `2` - -|`JAVA_TOOL_OPTIONS` -|Specifies options to apply to all JVMs running in this container. It is not -recommended to override this value. -|Default: `-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true` - -|`JAVA_GC_OPTS` -|Specifies Jenkins JVM garbage collection parameters. It is not recommended to -override this value. -|Default: `-XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90` - -|`JENKINS_JAVA_OVERRIDES` -|Specifies additional options for the Jenkins JVM. These options are appended to -all other options, including the Java options above, and can be used to override -any of them, if necessary. Separate each additional option with a space; if any -option contains space characters, escape them with a backslash. -|Example settings: `-Dfoo -Dbar`; `-Dfoo=first\ value -Dbar=second\ value` - -|=== diff --git a/modules/images-other-jenkins-agent-gradle.adoc b/modules/images-other-jenkins-agent-gradle.adoc deleted file mode 100644 index f71c27bb9c3a..000000000000 --- a/modules/images-other-jenkins-agent-gradle.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins-agent.adoc - -[id="images-other-jenkins-agent-gradle_{context}"] -= Jenkins agent Gradle builds - -Hosting Gradle builds in the Jenkins agent on {product-title} presents -additional complications because in addition to the Jenkins JNLP agent and -Gradle JVMs, Gradle spawns a third JVM to run tests if they are specified. - - -The following settings are suggested as a starting point for running Gradle -builds in a memory constrained Jenkins agent on {product-title}. You can modify -these settings as required. - -* Ensure the long-lived Gradle daemon is disabled by adding -`org.gradle.daemon=false` to the `gradle.properties` file. -* Disable parallel build execution by ensuring `org.gradle.parallel=true` is not -set in the `gradle.properties` file and that `--parallel` is not set as a command -line argument. -* To prevent Java compilations running out-of-process, set `java { options.fork = -false }` in the `build.gradle` file . -* Disable multiple additional test processes by ensuring -`test { maxParallelForks = 1 }` is set in the `build.gradle` file. -* Override the Gradle JVM memory parameters by the `GRADLE_OPTS`, `JAVA_OPTS` or -`JAVA_TOOL_OPTIONS` environment. -variables. -* Set the maximum heap size and JVM arguments for any Gradle test JVM by defining -the `maxHeapSize` and `jvmArgs` settings in `build.gradle`, or though the -`-Dorg.gradle.jvmargs` command line argument. diff --git a/modules/images-other-jenkins-agent-images.adoc b/modules/images-other-jenkins-agent-images.adoc deleted file mode 100644 index a5ae35856a72..000000000000 --- a/modules/images-other-jenkins-agent-images.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins-agent.adoc - -[id="images-other-jenkins-agent-images_{context}"] -= Jenkins agent images - -The {product-title} Jenkins agent images are available on `quay.io` or -`registry.redhat.io`. - -Jenkins images are available through the Red Hat Registry: - -[source,terminal] ----- -$ docker pull registry.redhat.io/openshift4/ose-jenkins:<v4.5.0> ----- - -[source,terminal] ----- -$ docker pull registry.redhat.io/openshift4/jenkins-agent-nodejs-10-rhel7:<v4.5.0> ----- - -[source,terminal] ----- -$ docker pull registry.redhat.io/openshift4/jenkins-agent-nodejs-12-rhel7:<v4.5.0> ----- - -[source,terminal] ----- -$ docker pull registry.redhat.io/openshift4/ose-jenkins-agent-maven:<v4.5.0> ----- - -[source,terminal] ----- -$ docker pull registry.redhat.io/openshift4/ose-jenkins-agent-base:<v4.5.0> ----- - -To use these images, you can either access them directly from `quay.io` or -`registry.redhat.io` or push them into your {product-title} container image -registry. diff --git a/modules/images-other-jenkins-agent-memory.adoc b/modules/images-other-jenkins-agent-memory.adoc deleted file mode 100644 index 97b1f7253f38..000000000000 --- a/modules/images-other-jenkins-agent-memory.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins-agent.adoc - -[id="images-other-jenkins-agent-memory_{context}"] -= Jenkins agent memory requirements - -A JVM is used in all Jenkins agents to host the Jenkins JNLP agent as well as -to run any Java applications such as `javac`, Maven, or Gradle. - -By default, the Jenkins JNLP agent JVM uses 50% of the container memory limit for -its heap. This value can be modified by the `CONTAINER_HEAP_PERCENT` -environment variable. It can also be capped at an upper limit or overridden -entirely. - -By default, any other processes run in the Jenkins agent container, such as -shell scripts or `oc` commands run from pipelines, cannot use more -than the remaining 50% memory limit without provoking an OOM kill. - -By default, each further JVM process that runs in a Jenkins agent container uses -up to 25% of the container memory limit for it's heap. It might be necessary to -tune this limit for many build workloads. diff --git a/modules/images-other-jenkins-agent-pod-retention.adoc b/modules/images-other-jenkins-agent-pod-retention.adoc deleted file mode 100644 index 012a61c1da00..000000000000 --- a/modules/images-other-jenkins-agent-pod-retention.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins-agent.adoc - -[id="images-other-jenkins-agent-pod-retention_{context}"] -= Jenkins agent pod retention - -Jenkins agent pods, also known as slave pods, are deleted by default after the -build completes or is stopped. This behavior can be changed by the Kubernetes -plug-in _Pod Retention_ setting. Pod retention can be set for all Jenkins -builds, with overrides for each pod template. The following behaviors are -supported: - -* `Always` keeps the build pod regardless of build result. -* `Default` uses the plug-in value (pod template only). -* `Never` always deletes the pod. -* `On Failure` keeps the pod if it fails during the build. - -You can override pod retention in the pipeline Jenkinsfile: - -[source,groovy] ----- -podTemplate(label: "mypod", - cloud: "openshift", - inheritFrom: "maven", - podRetention: onFailure(), <1> - containers: [ - ... - ]) { - node("mypod") { - ... - } -} ----- -<1> Allowed values for `podRetention` are `never()`, `onFailure()`, `always()`, -and `default()`. - -[WARNING] -==== -Pods that are kept might continue to run and count against resource quotas. -==== diff --git a/modules/images-other-jenkins-auth.adoc b/modules/images-other-jenkins-auth.adoc deleted file mode 100644 index 933d58fe5d46..000000000000 --- a/modules/images-other-jenkins-auth.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-auth_{context}"] -= Jenkins authentication - -Jenkins authentication is used by default if the image is run directly, without -using a template. - -The first time Jenkins starts, the configuration is created along with the -administrator user and password. The default user credentials are `admin` and -`password`. Configure the default password by setting the `JENKINS_PASSWORD` -environment variable when using, and only when using, standard Jenkins -authentication. - -.Procedure - -* Create a Jenkins application that uses standard Jenkins authentication: -+ -[source,terminal] ----- -$ oc new-app -e \ - JENKINS_PASSWORD=<password> \ - openshift4/ose-jenkins ----- diff --git a/modules/images-other-jenkins-config-kubernetes.adoc b/modules/images-other-jenkins-config-kubernetes.adoc deleted file mode 100644 index 08f4e2276197..000000000000 --- a/modules/images-other-jenkins-config-kubernetes.adoc +++ /dev/null @@ -1,150 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-config-kubernetes_{context}"] -= Configuring the Jenkins Kubernetes plug-in - -The {product-title} Jenkins image includes the pre-installed -https://wiki.jenkins-ci.org/display/JENKINS/Kubernetes+Plugin[Kubernetes -plug-in] that allows Jenkins agents to be dynamically provisioned on multiple -container hosts using Kubernetes and {product-title}. - -To use the Kubernetes plug-in, {product-title} provides images that are suitable -for use as Jenkins agents: the `Base`, `Maven`, and `Node.js` images. - -Both the Maven and Node.js agent images are automatically configured as -Kubernetes Pod Template images within the {product-title} Jenkins image's -configuration for the Kubernetes plug-in. That configuration includes labels for -each of the images that can be applied to any of your Jenkins jobs under their -`Restrict where this project can be run` setting. If the label is applied, -jobs run under an {product-title} Pod running the -respective agent image. - -The Jenkins image also provides auto-discovery and auto-configuration of -additional agent images for the Kubernetes plug-in. - -With the {product-title} Sync plug-in, the Jenkins image on Jenkins start-up -searches for the following within the project that it is running or the -projects specifically listed in the plug-in's configuration: - -* Imagestreams that have the label `role` set to `jenkins-slave`. -* Imagestreamtags that have the annotation `role` set to `jenkins-slave`. -* ConfigMaps that have the label `role` set to `jenkins-slave`. - -When it finds an imagestream with the appropriate label, or imagestreamtag -with the appropriate annotation, it generates the corresponding Kubernetes -plug-in configuration so you can assign your Jenkins jobs to run in a Pod -that runs the container image that is provided by the imagestream. - -The name and image references of the imagestream or imagestreamtag are mapped -to the name and image fields in the Kubernetes plug-in Pod template. You can -control the label field of the Kubernetes plug-in Pod template by setting an -annotation on the imagestream or imagestreamtag object with the key -`slave-label`. Otherwise, the name is used as the label. - -[NOTE] -==== -Do not log in to the Jenkins console and modify the Pod Template configuration. -If you do so after the Pod Template is created, and the OpenShift Sync plug-in -detects that the image associated with the ImageStream or ImageStreamTag has -changed, it replaces the Pod Template and overwrites those configuration -changes. You cannot merge a new configuration with the existing configuration. - -Consider the ConfigMap approach if you have more complex configuration needs. -==== - -When it finds a ConfigMap with the appropriate label, it assumes that any values -in the key-value data payload of the ConfigMap contains XML that is consistent -with the configuration format for Jenkins and the Kubernetes plug-in Pod -templates. A key differentiator to note when using ConfigMaps, instead of -imagestreams or imagestreamtags, is that you can control all the parameters -of the Kubernetes plug-in Pod template. - -Example ConfigMap for `jenkins-agent`: - -[source,yaml] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: jenkins-agent - labels: - role: jenkins-slave -data: - template1: |- - <org.csanchez.jenkins.plugins.kubernetes.PodTemplate> - <inheritFrom></inheritFrom> - <name>template1</name> - <instanceCap>2147483647</instanceCap> - <idleMinutes>0</idleMinutes> - <label>template1</label> - <serviceAccount>jenkins</serviceAccount> - <nodeSelector></nodeSelector> - <volumes/> - <containers> - <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate> - <name>jnlp</name> - <image>openshift/jenkins-agent-maven-35-centos7:v3.10</image> - <privileged>false</privileged> - <alwaysPullImage>true</alwaysPullImage> - <workingDir>/tmp</workingDir> - <command></command> - <args>${computer.jnlpmac} ${computer.name}</args> - <ttyEnabled>false</ttyEnabled> - <resourceRequestCpu></resourceRequestCpu> - <resourceRequestMemory></resourceRequestMemory> - <resourceLimitCpu></resourceLimitCpu> - <resourceLimitMemory></resourceLimitMemory> - <envVars/> - </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate> - </containers> - <envVars/> - <annotations/> - <imagePullSecrets/> - <nodeProperties/> - </org.csanchez.jenkins.plugins.kubernetes.PodTemplate> ----- - -[NOTE] -==== -If you log in to the Jenkins console and make further changes to the Pod Template -configuration after the Pod Template is created, and the OpenShift Sync plug-in -detects that the ConfigMap has changed, it will replace the Pod Template and -overwrite those configuration changes. You cannot merge a new configuration with -the existing configuration. - -Do not log in to the Jenkins console and modify the Pod Template configuration. -If you do so after the Pod Template is created, and the OpenShift Sync plug-in -detects that the image associated with the ImageStream or ImageStreamTag has -changed, it replaces the Pod Template and overwrites those configuration -changes. You cannot merge a new configuration with the existing configuration. - -Consider the ConfigMap approach if you have more complex configuration needs. - -==== - -After it is installed, the OpenShift Sync plug-in monitors the API server of -{product-title} for updates to `ImageStreams`, `ImageStreamTags`, and -`ConfigMaps` and adjusts the configuration of the Kubernetes plug-in. - -The following rules apply: - -* Removing the label or annotation from the `ConfigMap`, `ImageStream`, or -`ImageStreamTag` results in the deletion of any existing `PodTemplate` from -the configuration of the Kubernetes plug-in. -* If those objects are removed, the corresponding configuration -is removed from the Kubernetes plug-in. -* Either creating appropriately labeled or annotated `ConfigMap`, -`ImageStream`, or `ImageStreamTag` objects, or the adding of labels after their -initial creation, leads to creating of a `PodTemplate` in the Kubernetes-plugin -configuration. -* In the case of the `PodTemplate` by `ConfigMap` form, changes to the `ConfigMap` -data for the `PodTemplate` are applied to the `PodTemplate` settings in the -Kubernetes plug-in configuration and overrides any changes that were made to the -`PodTemplate` through the Jenkins UI between changes to the `ConfigMap`. - -To use a container image as a Jenkins agent, the image must run the slave agent as -an entrypoint. For more details about this, refer to the official -https://wiki.jenkins-ci.org/display/JENKINS/Distributed+builds#Distributedbuilds-Launchslaveagentheadlessly[Jenkins -documentation]. diff --git a/modules/images-other-jenkins-create-service.adoc b/modules/images-other-jenkins-create-service.adoc deleted file mode 100644 index 81b992c746b0..000000000000 --- a/modules/images-other-jenkins-create-service.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-create-service_{context}"] -= Creating a Jenkins service from a template - -Templates provide parameter fields to define all the environment variables -with predefined default values. {product-title} provides templates to make -creating a new Jenkins service easy. The Jenkins templates should be -registered in the default `openshift` project by your cluster administrator -during the initial cluster setup. - -The two available templates both define deployment configuration and a service. -The templates differ in their storage strategy, which affects whether or not the -Jenkins content persists across a Pod restart. - -[NOTE] -==== -A Pod might be restarted when it is moved to another node or when an update of -the deployment configuration triggers a redeployment. -==== - -* `jenkins-ephemeral` uses ephemeral storage. On Pod restart, all data is lost. -This template is only useful for development or testing. - -* `jenkins-persistent` uses a Persistent Volume store. Data survives a Pod -restart. - -To use a Persistent Volume store, the cluster administrator must define a -Persistent Volume pool in the {product-title} deployment. - -After you select which template you want, you must instantiate the -template to be able to use Jenkins. - -.Procedure - -. Create a new Jenkins application using one of the following methods: -** A Persistent Volume: -+ -[source,terminal] ----- -$ oc new-app jenkins-persistent ----- - -** Or an `emptyDir` type volume where configuration does not persist across Pod restarts: -+ -[source,terminal] ----- -$ oc new-app jenkins-ephemeral ----- diff --git a/modules/images-other-jenkins-cross-project.adoc b/modules/images-other-jenkins-cross-project.adoc deleted file mode 100644 index d08757b856cd..000000000000 --- a/modules/images-other-jenkins-cross-project.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-cross-project_{context}"] -= Providing Jenkins cross project access - -If you are going to run Jenkins somewhere other than your -same project, you must provide an access token to Jenkins to access your -project. - -.Procedure - -. Identify the secret for the service account that has appropriate permissions -to access the project Jenkins must access: -+ -[source,terminal] ----- -$ oc describe serviceaccount jenkins ----- -+ -.Example output -[source,terminal] ----- -Name: default -Labels: <none> -Secrets: { jenkins-token-uyswp } - { jenkins-dockercfg-xcr3d } -Tokens: jenkins-token-izv1u - jenkins-token-uyswp ----- -+ -In this case the secret is named `jenkins-token-uyswp`. - -. Retrieve the token from the secret: -+ -[source,terminal] ----- -$ oc describe secret <secret name from above> ----- -+ -.Example output -[source,terminal] ----- -Name: jenkins-token-uyswp -Labels: <none> -Annotations: kubernetes.io/service-account.name=jenkins,kubernetes.io/service-account.uid=32f5b661-2a8f-11e5-9528-3c970e3bf0b7 -Type: kubernetes.io/service-account-token -Data -==== -ca.crt: 1066 bytes -token: eyJhbGc..<content cut>....wRA ----- -+ -The token parameter contains the token value Jenkins requires to access the project. diff --git a/modules/images-other-jenkins-customize-s2i.adoc b/modules/images-other-jenkins-customize-s2i.adoc deleted file mode 100644 index fd2929b38129..000000000000 --- a/modules/images-other-jenkins-customize-s2i.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-customize-s2i_{context}"] -= Customizing the Jenkins image through Source-To-Image - -To customize the official {product-title} Jenkins image, you can use the image -as a Source-To-Image (S2I) builder. - -You can use S2I to copy your custom Jenkins Jobs definitions, add additional -plug-ins, or replace the provided `config.xml` file with your own, custom, -configuration. - -To include your modifications in the Jenkins image, you must have a -Git repository with the following directory structure: - -`plugins`:: -This directory contains those binary Jenkins plug-ins you want to copy into -Jenkins. - -`plugins.txt`:: -This file lists the plug-ins you want to install using the following syntax: - ----- -pluginId:pluginVersion ----- - -`configuration/jobs`:: -This directory contains the Jenkins job definitions. - -`configuration/config.xml`:: -This file contains your custom Jenkins configuration. - -The contents of the `configuration/` directory is copied -to the `/var/lib/jenkins/` directory, so you can also include -additional files, such as `credentials.xml`, there. - -The following example build configuration customizes the Jenkins -image in {product-title}: - -[source,yaml] ----- -apiVersion: v1 -kind: BuildConfig -metadata: - name: custom-jenkins-build -spec: - source: <1> - git: - uri: https://github.com/custom/repository - type: Git - strategy: <2> - sourceStrategy: - from: - kind: ImageStreamTag - name: jenkins:2 - namespace: openshift - type: Source - output: <3> - to: - kind: ImageStreamTag - name: custom-jenkins:latest ----- - -<1> The `source` parameter defines the source Git repository -with the layout described above. -<2> The `strategy` parameter defines the original Jenkins image to use -as a source image for the build. -<3> The `output` parameter defines the resulting, customized Jenkins image that -you can use in deployment configurations instead of the official Jenkins image. diff --git a/modules/images-other-jenkins-env-var.adoc b/modules/images-other-jenkins-env-var.adoc deleted file mode 100644 index 8217f8e00a7f..000000000000 --- a/modules/images-other-jenkins-env-var.adoc +++ /dev/null @@ -1,134 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-env-var_{context}"] -= Jenkins environment variables - -The Jenkins server can be configured with the following environment variables: - -[options="header"] -|=== -| Variable | Definition | Example values and settings - -|`OPENSHIFT_ENABLE_OAUTH` -|Determines whether the OpenShift Login plug-in manages authentication when -logging in to Jenkins. To enable, set to `true`. -|Default: `false` - -|`JENKINS_PASSWORD` -|The password for the `admin` user when using standard Jenkins authentication. -Not applicable when `OPENSHIFT_ENABLE_OAUTH` is set to `true`. -|Default: `password` - -|`JAVA_MAX_HEAP_PARAM`, -`CONTAINER_HEAP_PERCENT`, -`JENKINS_MAX_HEAP_UPPER_BOUND_MB` -|These values control the maximum heap size of the Jenkins JVM. If -`JAVA_MAX_HEAP_PARAM` is set, its value takes -precedence. Otherwise, the maximum heap size is dynamically calculated as -`CONTAINER_HEAP_PERCENT` of the container -memory limit, optionally capped at `JENKINS_MAX_HEAP_UPPER_BOUND_MB` MiB. - -By default, the maximum heap size of the Jenkins JVM is set to 50% of the -container memory limit with no cap. -|`JAVA_MAX_HEAP_PARAM` example setting: `-Xmx512m` - -`CONTAINER_HEAP_PERCENT` default: `0.5`, or 50% - -`JENKINS_MAX_HEAP_UPPER_BOUND_MB` example setting: `512 MiB` - -|`JAVA_INITIAL_HEAP_PARAM`, -`CONTAINER_INITIAL_PERCENT` -|These values control the initial heap size of the Jenkins JVM. If -`JAVA_INITIAL_HEAP_PARAM` is set, its value takes -precedence. Otherwise, the initial heap size is dynamically calculated as -`CONTAINER_INITIAL_PERCENT` of the -dynamically calculated maximum heap size. - -By default, the JVM sets the initial heap size. -|`JAVA_INITIAL_HEAP_PARAM` example setting: `-Xms32m` - -`CONTAINER_INITIAL_PERCENT` example setting: `0.1`, or 10% - -|`CONTAINER_CORE_LIMIT` -|If set, specifies an integer number of cores used for sizing numbers of internal -JVM threads. -|Example setting: `2` - -|`JAVA_TOOL_OPTIONS` -|Specifies options to apply to all JVMs running in this container. It is not -recommended to override this value. -|Default: `-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true` - -|`JAVA_GC_OPTS` -|Specifies Jenkins JVM garbage collection parameters. It is not recommended to -override this value. -|Default: `-XX:+UseParallelGC -XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90` - -|`JENKINS_JAVA_OVERRIDES` -|Specifies additional options for the Jenkins JVM. These options are appended to -all other options, including the Java options above, and may be used to override -any of them if necessary. Separate each additional option with a space; if any -option contains space characters, escape them with a backslash. -|Example settings: `-Dfoo -Dbar`; `-Dfoo=first\ value -Dbar=second\ value`. - -|`JENKINS_OPTS` -|Specifies arguments to Jenkins. -| - -|`INSTALL_PLUGINS` -|Specifies additional Jenkins plug-ins to install when the container is first run -or when `OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS` is set to `true`. -Plug-ins are specified as a comma-delimited list of name:version pairs. -|Example setting: `git:3.7.0,subversion:2.10.2`. - -|`OPENSHIFT_PERMISSIONS_POLL_INTERVAL` -|Specifies the interval in milliseconds that the OpenShift Login plug-in polls -{product-title} for the permissions that are associated with each user that is -defined in Jenkins. -|Default: `300000` - 5 minutes - -|`OVERRIDE_PV_CONFIG_WITH_IMAGE_CONFIG` -|When running this image with an {product-title} persistent volume for the Jenkins -configuration directory, the transfer of configuration from the image to the Persistent -Volume is performed only the first time the image starts because the Persistent -Volume is assigned when the Persistent Volume Claim is created. If you create a -custom image that extends this image and updates configuration in the custom image -after the initial startup, the configuration is not copied over unless you set this -environment variable to `true`. -|Default: `false` - -|`OVERRIDE_PV_PLUGINS_WITH_IMAGE_PLUGINS` -|When running this image with an {product-title} persistent volume for the Jenkins -configuration directory, the transfer of plugins from the image to the Persistent -Volume is performed only the first time the image starts because the Persistent -Volume is assigned when the Persistent Volume Claim is created. If you create a -custom image that extends this image and updates plug-ins in the custom image after -the initial startup, the plug-ins are not copied over unless you set this -environment variable to `true`. -|Default: `false` - -|`ENABLE_FATAL_ERROR_LOG_FILE` -|When running this image with an {product-title} Persistent Volume Claim for the -Jenkins configuration directory, this environment variable allows the fatal error -log file to persist when a fatal error occurs. The fatal error file is saved at -`/var/lib/jenkins/logs`. -|Default: `false` - -|`NODEJS_SLAVE_IMAGE` -|Setting this value overrides the image that is used for the default NodeJS agent -Pod configuration. A related imagestreamtag named `jenkins-agent-nodejs` is in -in the project. This variable must be set before Jenkins starts the first time -for it to have an effect. -|Default NodeJS agent image in Jenkins server: -`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-nodejs:latest` - -|`MAVEN_SLAVE_IMAGE` -|Setting this value overrides the image used for the default maven agent Pod -configuration. A related imagestreamtag named `jenkins-agent-maven` is in the -project. This variable must be set before Jenkins starts the first time for it -to have an effect. -|Default Maven agent image in Jenkins server: -`image-registry.openshift-image-registry.svc:5000/openshift/jenkins-agent-maven:latest` -|=== diff --git a/modules/images-other-jenkins-kubernetes-plugin.adoc b/modules/images-other-jenkins-kubernetes-plugin.adoc deleted file mode 100644 index fc8f7715666b..000000000000 --- a/modules/images-other-jenkins-kubernetes-plugin.adoc +++ /dev/null @@ -1,118 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-kubernetes-plugin_{context}"] -= Using the Jenkins Kubernetes plug-in - -In the following example, the `openshift-jee-sample` BuildConfig causes a -Jenkins Maven agent Pod to be dynamically provisioned. The Pod clones some Java -source code, builds a WAR file, and causes a second BuildConfig, -`openshift-jee-sample-docker` to run. The second BuildConfig layers the new WAR -file into a container image. - -The following example is a BuildConfig that uses the Jenkins Kubernetes plug-in. - -[source,yaml] ----- -kind: List -apiVersion: v1 -items: -- kind: ImageStream - apiVersion: v1 - metadata: - name: openshift-jee-sample -- kind: BuildConfig - apiVersion: v1 - metadata: - name: openshift-jee-sample-docker - spec: - strategy: - type: Docker - source: - type: Docker - dockerfile: |- - FROM openshift/wildfly-101-centos7:latest - COPY ROOT.war /wildfly/standalone/deployments/ROOT.war - CMD $STI_SCRIPTS_PATH/run - binary: - asFile: ROOT.war - output: - to: - kind: ImageStreamTag - name: openshift-jee-sample:latest -- kind: BuildConfig - apiVersion: v1 - metadata: - name: openshift-jee-sample - spec: - strategy: - type: JenkinsPipeline - jenkinsPipelineStrategy: - jenkinsfile: |- - node("maven") { - sh "git clone https://github.com/openshift/openshift-jee-sample.git ." - sh "mvn -B -Popenshift package" - sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war" - } - triggers: - - type: ConfigChange ----- - -It is also possible to override the specification of the dynamically created -Jenkins agent pod. The following is a modification to the previous example, which -overrides the container memory and specifies an environment variable: - -The following example is a BuildConfig that the Jenkins Kubernetes Plug-in, -specifying memory limit and environment variable. - -[source,yaml] ----- -kind: BuildConfig -apiVersion: v1 -metadata: - name: openshift-jee-sample -spec: - strategy: - type: JenkinsPipeline - jenkinsPipelineStrategy: - jenkinsfile: |- - podTemplate(label: "mypod", <1> - cloud: "openshift", <2> - inheritFrom: "maven", <3> - containers: [ - containerTemplate(name: "jnlp", <4> - image: "openshift/jenkins-agent-maven-35-centos7:v3.10", <5> - resourceRequestMemory: "512Mi", <6> - resourceLimitMemory: "512Mi", <7> - envVars: [ - envVar(key: "CONTAINER_HEAP_PERCENT", value: "0.25") <8> - ]) - ]) { - node("mypod") { <9> - sh "git clone https://github.com/openshift/openshift-jee-sample.git ." - sh "mvn -B -Popenshift package" - sh "oc start-build -F openshift-jee-sample-docker --from-file=target/ROOT.war" - } - } - triggers: - - type: ConfigChange ----- -<1> A new Pod template called `mypod` is defined dynamically. The new Pod -template name is referenced in the node stanza. -<2> The `cloud` value must be set to `openshift`. -<3> The new Pod template can inherit its configuration from an existing Pod -template. In this case, inherited from the Maven Pod template that is -pre-defined by {product-title}. -<4> This example overrides values in the pre-existing Container, and must be -specified by name. All Jenkins agent images shipped with {product-title} use -the Container name `jnlp`. -<5> Specify the Container image name again. This is a known issue. -<6> A memory request of `512 Mi` is specified. -<7> A memory limit of `512 Mi` is specified. -<8> An environment variable `CONTAINER_HEAP_PERCENT`, with value `0.25`, is -specified. -<9> The node stanza references the name of the defined Pod template. - -By default, the pod is deleted when the build completes. This behavior can be -modified with the plug-in or within a pipeline Jenkinsfile. diff --git a/modules/images-other-jenkins-memory.adoc b/modules/images-other-jenkins-memory.adoc deleted file mode 100644 index feab975a7ed5..000000000000 --- a/modules/images-other-jenkins-memory.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-memory_{context}"] -= Jenkins memory requirements - -When deployed by the provided Jenkins Ephemeral or Jenkins Persistent -templates, the default memory limit is `1 Gi`. - -By default, all other process that run in the Jenkins container cannot use more -than a total of `512 MiB` of memory. If they require more memory, the container -halts. It is therefore highly recommended that pipelines run external commands -in an agent container wherever possible. - -And if `Project` quotas allow for it, see recommendations from the Jenkins -documentation on what a Jenkins master should have from a memory perspective. -Those recommendations proscribe to allocate even more memory for the Jenkins master. - -It is recommended to specify memory request and limit values on agent containers -created by the Jenkins Kubernetes Plug-in. Admin users can set default values on -a per-agent image basis through the Jenkins configuration. The memory request -and limit parameters can also be overridden on a per-container basis. - -You can increase the amount of memory available to Jenkins by overriding -the `MEMORY_LIMIT` parameter when instantiating the Jenkins Ephemeral or -Jenkins Persistent template. diff --git a/modules/images-other-jenkins-oauth-auth.adoc b/modules/images-other-jenkins-oauth-auth.adoc deleted file mode 100644 index 0b2c1eef5438..000000000000 --- a/modules/images-other-jenkins-oauth-auth.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-oauth-auth_{context}"] -= {product-title} OAuth authentication - -OAuth authentication is activated by configuring options on the *Configure -Global Security* panel in the Jenkins UI, or by setting the -`OPENSHIFT_ENABLE_OAUTH` environment variable on the Jenkins *Deployment -configuration* to anything other than `false`. This activates the {product-title} -Login plug-in, which retrieves the configuration information from Pod data or by -interacting with the {product-title} API server. - -Valid credentials are controlled by the {product-title} identity provider. - -Jenkins supports both browser and non-browser access. - -Valid users are automatically added to the Jenkins authorization matrix at log -in, where {product-title} `Roles` dictate the specific Jenkins permissions the -users have. The `Roles` used by default are the predefined `admin`, `edit`, and `view`. -The login plug-in executes self-SAR requests against those `Roles` in the `Project` -or namespace that Jenkins is running in. - -Users with the `admin` role have the traditional Jenkins administrative -user permissions. Users with the `edit` or `view` role have progressively -fewer permissions. - -The default {product-title} `admin`, `edit`, and `view` `Roles` and the Jenkins permissions -those `Roles` are assigned in the Jenkins instance are configurable. - -When running Jenkins in an {product-title} `Pod`, the login plug-in looks for a `ConfigMap` named `openshift-jenkins-login-plugin-config` in the namespace that Jenkins is running in. - -If this plugin finds and can read in that `ConfigMap`, you can define the `Role` to Jenkins Permission mappings. Specifically: - - * The login plug-in treats the key and value pairs in the `ConfigMap` as Jenkins permission to OpenShift Role mappings. - * The key is the Jenkins permission group short ID and the Jenkins permission short ID, with those two separated by a hyphen character. - * If you want to add the `Overall Jenkins Administer` permission to an {product-title} `Role`, the key should be `Overall-Administer`. - * To get a sense of which permission groups and permissions IDs are available, go to the matrix authorization page in the Jenkins console and IDs for the groups and individual permissions in the table they provide. - * The value of the key and value pair is the list of {product-title} `Roles` the permission should apply to, with each role separated by a comma. - * If you want to add the `Overall Jenkins Administer` permission to both the default `admin` and `edit` `Roles`, as well as a new jenkins role you have created, the value for the key `Overall-Administer` would be `admin,edit,jenkins`. - - -[NOTE] -==== -The `admin` user that is pre-populated in the {product-title} Jenkins image with -administrative privileges is not given those privileges when -{product-title} OAuth is used. To grant these permissions the {product-title} -cluster administrator must explicitly define that user in the {product-title} -identity provider and assigs the `admin` role to the user. -==== - -Jenkins users' permissions that are stored can be changed after the users are -initially established. The OpenShift Login plug-in polls the {product-title} API -server for permissions and updates the permissions stored in Jenkins for each -user with the permissions retrieved from {product-title}. If the Jenkins UI is -used to update permissions for a Jenkins user, the permission changes are -overwritten the next time the plug-in polls {product-title}. - -You can control how often the polling occurs with the -`OPENSHIFT_PERMISSIONS_POLL_INTERVAL` environment variable. The default polling -interval is five minutes. - -The easiest way to create a new Jenkins service using OAuth authentication is to -use a template. diff --git a/modules/images-other-jenkins-permissions.adoc b/modules/images-other-jenkins-permissions.adoc deleted file mode 100644 index 9e4f8bff2c5d..000000000000 --- a/modules/images-other-jenkins-permissions.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * images/using_images/images-other-jenkins.adoc - -[id="images-other-jenkins-permissions_{context}"] -= Jenkins permissions - -If in the ConfigMap the `<serviceAccount>` element of the Pod Template XML is -the {product-title} Service Account used for the resulting pod, the service -account credentials are mounted into the pod. The permissions are associated -with the service account and control which operations against the -{product-title} master are allowed from the pod. - -Consider the following scenario with service accounts used for the pod, which -is launched by the Kubernetes Plug-in that runs in the {product-title} Jenkins -image: - -If you use the example template for Jenkins that is provided by {product-title}, -the `jenkins` service account is defined with the `edit` role for the project -Jenkins runs in, and the master Jenkins Pod has that service account -mounted. - -The two default Maven and NodeJS Pod Templates that are injected into the Jenkins -configuration are also set to use the same service account as the Jenkins master. - -* Any Pod templates that are automatically discovered by the OpenShift Sync -plug-in because their imagestreams or imagestreamtags have the required label or -annotations are configured to use the Jenkins master's service account as their -service account. -* For the other ways you can provide a Pod Template definition into Jenkins and -the Kubernetes plug-in, you have to explicitly specify the service account to -use. Those other ways include the Jenkins console, the `podTemplate` pipeline DSL -that is provided by the Kubernetes plug-in, or labeling a ConfigMap whose data -is the XML configuration for a Pod Template. -* If you do not specify a value for the service account, the `default` service -account is used. -* Ensure that whatever service account is used has the necessary -permissions, roles, and so on defined within {product-title} to manipulate -whatever projects you choose to manipulate from the within the pod. diff --git a/modules/images-pulling-from-private-registries.adoc b/modules/images-pulling-from-private-registries.adoc deleted file mode 100644 index e0dd0f2b5254..000000000000 --- a/modules/images-pulling-from-private-registries.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/using-image-pull-secrets - -[id="images-pulling-from-private-registries_{context}"] -= Pulling from private registries with delegated authentication - -A private registry can delegate authentication to a separate service. In these -cases, image pull secrets must be defined for both the authentication and -registry endpoints. - -.Procedure - -. Create a secret for the delegated authentication server: -+ -[source,terminal] ----- -$ oc create secret docker-registry \ - --docker-server=sso.redhat.com \ - --docker-username=developer@example.com \ - --docker-password=******** \ - --docker-email=unused \ - redhat-connect-sso - -secret/redhat-connect-sso ----- -+ -. Create a secret for the private registry: -+ -[source,terminal] ----- -$ oc create secret docker-registry \ - --docker-server=privateregistry.example.com \ - --docker-username=developer@example.com \ - --docker-password=******** \ - --docker-email=unused \ - private-registry - -secret/private-registry ----- diff --git a/modules/images-referencing-images-imagestreams.adoc b/modules/images-referencing-images-imagestreams.adoc deleted file mode 100644 index a963cb0e09ac..000000000000 --- a/modules/images-referencing-images-imagestreams.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/tagging-images - -[id="images-referencing-images-imagestreams_{context}"] -= Referencing images in imagestreams - -You can use tags to reference images in imagestreams using the following -reference types. - -.Imagestream reference types -[width="50%",options="header"] -|=== -|Reference type |Description - -|`ImageStreamTag` -|An `ImageStreamTag` is used to reference or retrieve an image for a given -imagestream and tag. - -|`ImageStreamImage` -|An `ImageStreamImage` is used to reference or retrieve an image for a given -imagestream and image `sha` ID. - -|`DockerImage` -|A `DockerImage` is used to reference or retrieve an image for a given external -registry. It uses standard Docker _pull specification_ for its name. -|=== - -When viewing example imagestream definitions you may notice they contain -definitions of `ImageStreamTag` and references to `DockerImage`, but nothing -related to `ImageStreamImage`. - -This is because the `ImageStreamImage` objects are automatically created in -{product-title} when you import or tag an image into the imagestream. You -should never have to explicitly define an `ImageStreamImage` object in any -imagestream definition that you use to create imagestreams. - -.Procedure - -* To reference an image for a given imagestream and tag, use `ImageStreamTag`: -+ ----- -<image_stream_name>:<tag> ----- - -* To reference an image for a given imagestream and image `sha` ID, use -`ImageStreamImage`: -+ ----- -<image_stream_name>@<id> ----- -+ -The `<id>` is an immutable identifier for a specific image, also called a -digest. - -* To reference or retrieve an image for a given external -registry, use `DockerImage`: -+ ----- -openshift/ruby-20-centos7:2.0 ----- -+ -[NOTE] -==== -When no tag is specified, it is assumed the *latest* tag is used. -==== -+ -You can also reference a third-party registry: -+ ----- -registry.redhat.io/rhel7:latest ----- -+ -Or an image with a digest: -+ ----- -centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e ----- diff --git a/modules/images-remove-tag-imagestream.adoc b/modules/images-remove-tag-imagestream.adoc deleted file mode 100644 index 8b9562adf9d8..000000000000 --- a/modules/images-remove-tag-imagestream.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/tagging-images - -[id="images-remove-tag-imagestream_{context}"] -= Removing tags from imagestreams - -You can remove tags from an imagestream. - -.Procedure - -* To remove a tag completely from an imagestream run: -+ -[source,terminal] ----- -$ oc delete istag/ruby:latest ----- -+ -or: -+ -[source,terminal] ----- -$ oc tag -d ruby:latest ----- diff --git a/modules/images-samples-operator-deprecated-image-stream.adoc b/modules/images-samples-operator-deprecated-image-stream.adoc deleted file mode 100644 index f0973afc14ab..000000000000 --- a/modules/images-samples-operator-deprecated-image-stream.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/configuring-samples-operator.adoc - - -[id="images-samples-operator-deprecated-image-stream_{context}"] -= Removing deprecated image stream tags from the Cluster Samples Operator - -The Cluster Samples Operator leaves deprecated image stream tags in an image stream because users can have deployments that use the deprecated image stream tags. - -You can remove deprecated image stream tags by editing the image stream with the `oc tag` command. - -[NOTE] -==== -Deprecated image stream tags that the samples providers have removed from their image streams are not included on initial installations. -==== - -.Prerequisites - -* You installed the `oc` CLI. - -.Procedure - -* Remove deprecated image stream tags by editing the image stream with the `oc tag` command. -+ -[source,terminal] ----- -$ oc tag -d <image_stream_name:tag> ----- -+ -.Example output -[source,terminal] ----- -Deleted tag default/<image_stream_name:tag>. ----- - -//Similar procedure in images-imagestreams-remove-tag.adoc diff --git a/modules/images-tab.adoc b/modules/images-tab.adoc new file mode 100644 index 000000000000..3dc20bb3c457 --- /dev/null +++ b/modules/images-tab.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +ifeval::["{context}" == "observed-cves"] +:observedcves: +endif::[] + +:_mod-docs-content-type: CONCEPT +[id="images-tab_{context}"] += Images tab + +The images view organizes the information into the following groups: + +* *Image*: Displays the name or identifier of each container image. +ifdef::observedcves[] +* *CVEs by severity*: Groups the vulnerabilities associated with each image based on their severity. +endif::observedcves[] +* *Operating system*: Highlights the operating system that the image uses and helps identify potential vulnerabilities specific to that operating system. +* *Deployments*: Shows all deployments where the image is actively running so you can assess the impact and prioritize remediation based on usage. +* *Age*: Shows how long the image has been in use and provides information about potential risks associated with outdated images. +* *Scan time*: Shows the timestamp of the last scan. + +To review and triage the details associated with an image, click on the image. + +A window opens with information about the vulnerabilities associated with the image. + +ifeval::["{context}" == "observed-cves"] +:!observedcves: +endif::[] \ No newline at end of file diff --git a/modules/images-tag.adoc b/modules/images-tag.adoc deleted file mode 100644 index 9fd9132ece39..000000000000 --- a/modules/images-tag.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/images-understand.adoc -// * openshift_images/tagging-images.adoc - -[id="images-tag_{context}"] -= Image tags - -An image tag is a label applied to a container image in a repository that -distinguishes a specific image from other images in an imagestream. Typically, -the tag represents a version number of some sort. For example, here v3.11.59-2 -is the tag: - ----- -registry.access.redhat.com/openshift3/jenkins-2-rhel7:v3.11.59-2 ----- - -You can add additional tags to an image. For example, an image might be assigned -the tags :v3.11.59-2 and :latest. - -{product-title} provides the `oc tag` command, which is similar to the `docker -tag` command, but operates on imagestreams instead of directly on images. diff --git a/modules/images-tagging-conventions.adoc b/modules/images-tagging-conventions.adoc deleted file mode 100644 index e9dde0c9bf56..000000000000 --- a/modules/images-tagging-conventions.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/tagging-images - -[id="images-tagging-conventions_{context}"] -= Image tag conventions - -Images evolve over time and their tags reflect this. Generally, an image tag -always points to the latest image built. - -If there is too much information embedded in a tag name, like -`v2.0.1-may-2019`, the tag points to just one revision of an image and is -never updated. Using default image pruning options, such an image is never -removed. -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -In very large clusters, the schema of creating new tags for every revised image -could eventually fill up the etcd datastore with excess tag metadata for images -that are long outdated. -endif::[] - -If the tag is named `v2.0`, image revisions are more likely. This -results in longer tag history and, therefore, the image pruner is more likely to -remove old and unused images. - -Although tag naming convention is up to you, here are a few examples in the -format `<image_name>:<image_tag>`: - -.Image tag naming conventions -[width="50%",options="header"] -|=== -|Description |Example - -|Revision -|`myimage:v2.0.1` - -|Architecture -|`myimage:v2.0-x86_64` - -|Base image -|`myimage:v1.2-centos7` - -|Latest (potentially unstable) -|`myimage:latest` - -|Latest stable -|`myimage:stable` -|=== - -If you require dates in tag names, periodically inspect old and unsupported -images and `istags` and remove them. Otherwise, you can experience increasing -resource usage caused by retaining old images. diff --git a/modules/images-test-s2i.adoc b/modules/images-test-s2i.adoc deleted file mode 100644 index a04f0d21a681..000000000000 --- a/modules/images-test-s2i.adoc +++ /dev/null @@ -1,165 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/create-images.adoc - -[id="images-test-s2i_{context}"] -= Testing S2I images - -As an Source-to-Image (S2I) builder image author, you can test your S2I image -locally and use the {product-title} build system for automated testing and -continuous integration. - -S2I requires the -`assemble` and `run` scripts to be present to successfully run -the S2I build. Providing the `save-artifacts` script reuses the build -artifacts, and providing the `usage` script ensures that usage information is -printed to console when someone runs the container image outside of the S2I. - -The goal of testing an S2I image is to make sure that all of these described -commands work properly, even if the base container image has changed or the tooling -used by the commands was updated. - -[id="testing-requirements_{context}"] -== Understanding testing requirements -The standard location for the `test` script is `test/run`. This script is -invoked by the {product-title} S2I image builder and it could be a simple Bash -script or a static Go binary. - -The `test/run` script performs the S2I build, so you must have the S2I binary -available in your `$PATH`. If required, follow the installation instructions -in the -https://github.com/openshift/source-to-image/blob/master/README.md#installation[S2I -README]. - -S2I combines the application source code and builder image, so to test -it you need a sample application source to verify that the source successfully -transforms into a runnable container image. The sample application should be simple, -but it should exercise the crucial steps of `assemble` and `run` scripts. - -[id="generating-scripts-and-tools_{context}"] -== Generating scripts and tools -The S2I tooling comes with powerful generation tools to speed up the process of -creating a new S2I image. The `s2i create` command produces all the necessary S2I -scripts and testing tools along with the `Makefile`: - -[source,termnal] ----- -$ s2i create _<image name>_ _<destination directory>_ ----- - -The generated `test/run` script must be adjusted to be -useful, but it provides a good starting point to begin developing. - -[NOTE] -==== -The `test/run` script produced by the `s2i create` command requires that the sample application sources are inside the `test/test-app` directory. -==== -ifndef::openshift-online[] -[id="testing-locally_{context}"] - -== Testing locally -The easiest way to run the S2I image tests locally is to use the generated -`Makefile`. - -If you did not use the `s2i create` command, you can copy the -following `Makefile` template and replace the `IMAGE_NAME` parameter with -your image name. - -.Sample `Makefile` ----- -IMAGE_NAME = openshift/ruby-20-centos7 -CONTAINER_ENGINE := $(shell command -v podman 2> /dev/null | echo docker) - -build: - ${CONTAINER_ENGINE} build -t $(IMAGE_NAME) . - -.PHONY: test -test: - ${CONTAINER_ENGINE} build -t $(IMAGE_NAME)-candidate . - IMAGE_NAME=$(IMAGE_NAME)-candidate test/run ----- - -[id="basic-testing-workflow_{context}"] - -== Basic testing workflow -The `test` script assumes you have already built the image you want to -test. If required, first build the S2I image. Run one of the following commands: - -* If you use Podman, run the following command: -+ -[source,terminal] ----- -$ podman build -t <builder_image_name> ----- - -* If you use Docker, run the following command: -+ -[source,terminal] ----- -$ docker build -t <builder_image_name> ----- - -The following steps describe the default workflow to test S2I image builders: - -. Verify the `usage` script is working: -+ -* If you use Podman, run the following command: -+ -[source,terminal] ----- -$ podman run <builder_image_name> . ----- - -* If you use Docker, run the following command: -+ -[source,terminal] ----- -$ docker run <builder_image_name> . ----- - -. Build the image: -+ -[source,terminal] -[options="nowrap"] ----- -$ s2i build file:///path-to-sample-app _<BUILDER_IMAGE_NAME>_ _<OUTPUT_APPLICATION_IMAGE_NAME>_ ----- - -. Optional: if you support `save-artifacts`, run step 2 once again to -verify that saving and restoring artifacts works properly. - -. Run the container: -+ -* If you use Podman, run the following command: -+ -[source,terminal] ----- -$ podman run <output_application_image_name> ----- - -* If you use Docker, run the following command: -+ -[source,terminal] ----- -$ docker run <output_application_image_name> ----- - -. Verify the container is running and the application is responding. - -Running these steps is generally enough to tell if the builder image is -working as expected. - - -[id="using-openshift-for-building-the-image_{context}"] - -== Using {product-title} for building the image -Once you have a `Dockerfile` and the other artifacts that make up your new -S2I builder image, you can put them in a git repository and use {product-title} -to build and push the image. Simply define a Docker build that points -to your repository. - -If your {product-title} instance is hosted on a public IP address, the build can -be triggered each time you push into your S2I builder image GitHub repository. - -You can also use the `ImageChangeTrigger` to trigger a rebuild of your applications that are -based on the S2I builder image you updated. -endif::openshift-online[] diff --git a/modules/images-triggering-updates-imagestream-changes-kubernetes-about.adoc b/modules/images-triggering-updates-imagestream-changes-kubernetes-about.adoc deleted file mode 100644 index 85965d314cf6..000000000000 --- a/modules/images-triggering-updates-imagestream-changes-kubernetes-about.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/triggering-updates-on-imagestream-changes.adoc - - -[id="images-triggering-updates-imagestream-changes-kubernetes-about_{context}"] -= Triggering Kubernetes resources - -Kubernetes resources do not have fields for triggering, unlike deployment and build configurations, which include as part of their API definition a set of fields for controlling triggers. Instead, you can use annotations in {product-title} to request triggering. - -The annotation is defined as follows: - -[source,yaml] ----- -Key: image.openshift.io/triggers -Value: -[ - { - "from": { - "kind": "ImageStreamTag", <1> - "name": "example:latest", <2> - "namespace": "myapp", <3> - }, - "fieldPath": "spec.template.spec.containers[?(@.name='web')].image", <4> - "paused": "false" <5> - }, - ... -] ----- -<1> Required: `kind` is the resource to trigger from must be `ImageStreamTag`. -<2> Required: `name` must be the name of an image stream tag. -<3> Optional: `namespace` defaults to the namespace of the object. -<4> Required: `fieldPath` is the JSON path to change. This field is limited and accepts only a JSON path expression that precisely matches a container by ID or index. For pods, the JSON path is "spec.containers[?(@.name='web')].image". -<5> Optional: `paused` is whether or not the trigger is paused, and the default value is `false`. Set `paused` to `true` to temporarily disable this trigger. - -When one of the core Kubernetes resources contains both a pod template and this annotation, {product-title} attempts to update the object by using the image currently associated with the image stream tag that is referenced by trigger. The update is performed against the `fieldPath` specified. - -Examples of core Kubernetes resources that can contain both a pod template and annotation include: - -* `CronJobs` -* `Deployments` -* `StatefulSets` -* `DaemonSets` -* `Jobs` -* `ReplicationControllers` -* `Pods` diff --git a/modules/images-triggering-updates-imagestream-changes-kubernetes-cli.adoc b/modules/images-triggering-updates-imagestream-changes-kubernetes-cli.adoc deleted file mode 100644 index 803a4e197206..000000000000 --- a/modules/images-triggering-updates-imagestream-changes-kubernetes-cli.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/triggering-updates-on-imagestream-changes.adoc - - -[id="images-triggering-updates-imagestream-changes-kubernetes-cli_{context}"] -= Triggering Kubernetes resources manually - -You can manually trigger Kubernetes resources by entering the `oc set triggers` command. - -When adding an image trigger to deployments, you can use the `oc set triggers` command. For example, the example command in this procedure adds an image change trigger to the deployment named `example` so that when the `example:latest` image stream tag is updated, the `web` container inside the deployment updates with the new image value. - -.Procedure - -* Trigger Kubernetes resources by entering the `oc set triggers` command: -+ -[source,terminal] ----- -$ oc set triggers deploy/example --from-image=example:latest -c web ----- - -Unless the deployment is paused, this pod template update automatically causes a deployment to occur with the new image value. diff --git a/modules/images-triggering-updates-imagestream-changes-kubernetes.adoc b/modules/images-triggering-updates-imagestream-changes-kubernetes.adoc deleted file mode 100644 index 9befa9f97864..000000000000 --- a/modules/images-triggering-updates-imagestream-changes-kubernetes.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/triggering-updates-on-imagestream-changes.adoc - - -[id="images-triggering-updates-imagestream-changes-kubernetes_{context}"] -= Triggering Kubernetes resources automatically - -You can automatically trigger Kubernetes resources by updating the image stream tag. - -In the following example, the trigger fires when the `example:latest` image stream tag is updated. Upon firing, the pod template image reference for the `web` container is updated with a new image value for the object. If the pod template is part of a deployment definition, the change to the pod template automatically triggers a deployment, which rolls out the new image. - -.Procedure - -* Trigger Kubernetes resources by updating the image stream tag similar to the one in this example: -+ -[source,yaml] ----- -image.openshift.io/triggers=[{"from":{"kind":"ImageStreamTag","name":"example:latest"},"fieldPath":"spec.template.spec.containers[?(@.name='web')].image"}] ----- - -Unless the deployment is paused, this pod template update automatically causes a deployment to occur with the new image value. diff --git a/modules/images-update-global-pull-secret.adoc b/modules/images-update-global-pull-secret.adoc deleted file mode 100644 index fb32b3934e1f..000000000000 --- a/modules/images-update-global-pull-secret.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/managing_images/using-image-pull-secrets.adoc -// * post_installation_configuration/cluster-tasks.adoc -// * support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc -// -// Not included, but linked to from: -// * operators/admin/olm-managing-custom-catalogs.adoc - -[id="images-update-global-pull-secret_{context}"] -= Updating the global cluster pull secret - -You can update the global pull secret for your cluster. - -[WARNING] -==== -Cluster resources must adjust to the new pull secret, which can temporarily limit the usability of the cluster. -==== - -Updating the global pull secret causes the Machine Config Operator to drain the nodes, apply the change, and uncordon the nodes. - -[NOTE] -==== -As of {product-title} 4.7, changes to the global pull secret no longer trigger a reboot. -==== - -.Prerequisites - -* You have a new or modified pull secret file to upload. -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -* Enter the following command to update the global pull secret for your cluster: -+ -[source,terminal] ----- -$ oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjson=<pull-secret-location> <1> ----- -<1> Provide the path to the new pull secret file. - -This update is rolled out to all nodes, which can take some time depending on the size of your cluster. During this time, nodes are drained and pods are rescheduled on the remaining nodes. - -//Also referred to as the cluster-wide pull secret. diff --git a/modules/images-using-imagestream-change-triggers.adoc b/modules/images-using-imagestream-change-triggers.adoc deleted file mode 100644 index 6a71a9f487da..000000000000 --- a/modules/images-using-imagestream-change-triggers.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-using-imagestream-change-triggers_{context}"] -= Imagestream change triggers - -Imagestream triggers allow your Builds and Deployments to be automatically -invoked when a new version of an upstream image is available. - -//from FAQ - -For example, Builds and Deployments can be automatically started when an image -stream tag is modified. This is achieved by monitoring that particular image -stream tag and notifying the Build or Deployment when a change is detected. diff --git a/modules/images-using-imagestream-images.adoc b/modules/images-using-imagestream-images.adoc deleted file mode 100644 index 015ea08b0af9..000000000000 --- a/modules/images-using-imagestream-images.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-using-imagestream-images_{context}"] -= Imagestream images - -An imagestream image points from within an imagestream -to a particular image ID. - -Imagestream images allow you to retrieve metadata about an image from a -particular imagestream where it is tagged. - -Imagestream image objects are automatically created in {product-title} whenever -you import or tag an image into the imagestream. You should never have to -explicitly define an imagestream image object in any imagestream definition -that you use to create imagestreams. - -The imagestream image consists of the imagestream name and image ID from the -repository, delimited by an `@` sign: - ----- -<image-stream-name>@<image-id> ----- - -To refer to the image in the `ImageStream` object example, the imagestream image -looks like: - ----- -origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d ----- diff --git a/modules/images-using-imagestream-tags.adoc b/modules/images-using-imagestream-tags.adoc deleted file mode 100644 index 9790ebc1984d..000000000000 --- a/modules/images-using-imagestream-tags.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/image-streams-managing.adoc - -[id="images-using-imagestream-tags_{context}"] -= Imagestreamtags - -An imagestreamtag is a named pointer to an image in an _imagestream_. It is -often abbreviated as _istag_. An imagestreamtag is used to reference or -retrieve an image for a given imagestream and tag. - -Imagestreamtags can reference any local or externally managed image. It -contains a history of images represented as a stack of all images the tag ever -pointed to. Whenever a new or existing image is tagged under particular image -stream tag, it is placed at the first position in the history stack. The image -previously occupying the top position will be available at the second position, -and so forth. This allows for easy rollbacks to make tags point to historical -images again. - -The following imagestreamtag is from an `ImageStream` object: - -.Imagestreamtag with two images in its history - -[source,yaml] ----- - tags: - - items: - - created: 2017-09-02T10:15:09Z - dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d - generation: 2 - image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 - - created: 2017-09-29T13:40:11Z - dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 - generation: 1 - image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d - tag: latest ----- - -Imagestreamtags can be _permanent_ tags or _tracking_ tags. - -* _Permanent tags_ are version-specific tags that point to a particular version of -an image, such as Python 3.5. - -* _Tracking tags_ are reference tags that follow another imagestreamtag and - could be updated in the future to change which image they follow, much like a - symlink. Note that these new levels are not guaranteed to be - backwards-compatible. -+ -For example, the `latest` imagestreamtags that ship with {product-title} are -tracking tags. This means consumers of the `latest` imagestreamtag will be -updated to the newest level of the framework provided by the image when a new -level becomes available. A `latest` imagestreamtag to `v3.10` could be changed -to `v3.11` at any time. It is important to be aware that these `latest` image -stream tags behave differently than the Docker `latest` tag. The `latest` image -stream tag, in this case, does not point to the latest image in the Docker -repository. It points to another imagestreamtag, which might not be the latest -version of an image. For example, if the `latest` imagestreamtag points to -`v3.10` of an image, when the `3.11` version is released, the `latest` tag is -not automatically updated to `v3.11`, and remains at `v3.10` until it is -manually updated to point to a `v3.11` imagestreamtag. -+ -[NOTE] -==== -Tracking tags are limited to a single imagestream and cannot reference other -imagestreams. -==== - -You can create your own imagestreamtags for your own needs. - -The imagestreamtag is composed of the name of the imagestream and a tag, -separated by a colon: - ----- -<imagestream name>:<tag> ----- - -For example, to refer to the -`sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d` image -in the `ImageStream` object example earlier, the imagestreamtag -would be: - ----- -origin-ruby-sample:latest ----- diff --git a/modules/impersonation-project-creation.adoc b/modules/impersonation-project-creation.adoc deleted file mode 100644 index f1280a2e0048..000000000000 --- a/modules/impersonation-project-creation.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/projects/creating-project-other-user.adoc - -[id="impersonation-project-creation_{context}"] -= Impersonating a user when you create a project - -You can impersonate a different user when you create a project request. Because -`system:authenticated:oauth` is the only bootstrap group that can -create project requests, you must impersonate that group. - -.Procedure - -* To create a project request on behalf of a different user: -+ -[source,terminal] ----- -$ oc new-project <project> --as=<user> \ - --as-group=system:authenticated --as-group=system:authenticated:oauth ----- diff --git a/modules/impersonation-system-admin-group.adoc b/modules/impersonation-system-admin-group.adoc deleted file mode 100644 index cb612405996b..000000000000 --- a/modules/impersonation-system-admin-group.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * users_and_roles/impersonating-system-admin.adoc - -[id="impersonation-system-admin-group_{context}"] -= Impersonating the `system:admin` group - - -When a `system:admin` user is granted cluster administration permissions through a group, you must include the -`--as=<user> --as-group=<group1> --as-group=<group2>` parameters in the command to impersonate the associated groups. - -.Procedure - -* To grant a user permission to impersonate a `system:admin` by impersonating the associated cluster administration groups, -run the following command: -+ -[source,terminal] ----- -$ oc create clusterrolebinding <any_valid_name> --clusterrole=sudoer --as=<user> \ ---as-group=<group1> --as-group=<group2> ----- diff --git a/modules/impersonation-system-admin-user.adoc b/modules/impersonation-system-admin-user.adoc deleted file mode 100644 index a6eda0a24721..000000000000 --- a/modules/impersonation-system-admin-user.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * users_and_roles/impersonating-system-admin.adoc - -[id="impersonation-system-admin-user_{context}"] -= Impersonating the `system:admin` user - -You can grant a user permission to impersonate `system:admin`, which grants them -cluster administrator permissions. - -.Procedure - -* To grant a user permission to impersonate `system:admin`, run the following command: -+ -[source,terminal] ----- -$ oc create clusterrolebinding <any_valid_name> --clusterrole=sudoer --user=<username> ----- diff --git a/modules/import-security-policy.adoc b/modules/import-security-policy.adoc new file mode 100644 index 000000000000..79febf4a3030 --- /dev/null +++ b/modules/import-security-policy.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="import-security-policy_{context}"] += Importing a security policy + +[role="_abstract"] +You can import a security policy from the *System Policies* view on the {product-title-short} portal. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. Click *Import policy*. +. In the *Import policy JSON* dialog, click *Upload* and select the JSON file you want to upload. +. Click *Begin import*. ++ +Each security policy in {product-title-short} has a unique ID (UID) and a unique name. +When you import a policy, {product-title-short} handles the uploaded policy as follows: ++ +* If the imported policy UID and name do not match any existing policy, {product-title-short} creates a new policy. +* If the imported policy has the same UID as an existing policy, but a different name, you can either: +** Keep both policies. +{product-title-short} saves the imported policy with a new UID. +** Replace the existing policy with the imported policy. +* If the imported policy has the same name as an existing policy, but a different UID, you can either: +** Keep both policies by providing a new name for the imported policy. +** Replace the existing policy with the imported policy. +* If the imported policy has the same name and UID as an existing policy, the {product-title} checks if the policy criteria match to the existing policy. +If the policy criteria match, {product-title-short} keeps the existing policy and shows a success message. +If the policy criteria do not match, you can either: +** Keep both policies by providing a new name for the imported policy. +** Replace the existing policy with the imported policy. ++ +[IMPORTANT] +==== +* If you import into the same Central instance, {product-title-short} uses all the exported fields. +* If you import into a different Central instance, {product-title-short} omits certain fields, such as cluster scopes, cluster exclusions, and notifications. +{product-title-short} shows these omitted fields in a message. +These fields vary for every installation, and you cannot migrate them from one Central instance to another. +==== diff --git a/modules/information-collected-by-telemetry.adoc b/modules/information-collected-by-telemetry.adoc new file mode 100644 index 000000000000..d4542db6ecc0 --- /dev/null +++ b/modules/information-collected-by-telemetry.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * telemetry/about-telemetry.adoc +:_mod-docs-content-type: CONCEPT +[id="information-collected-by-telemetry_{context}"] += Information collected by Telemetry + +Telemetry does not collect identifying information such as user names, passwords, or the names or addresses of user resources. + +[NOTE] +==== +Telemetry data collection is enabled by default, except for the installations with the offline mode enabled. +==== + +Telemetry collects the following information: + +* API, `roxctl` CLI, and user interface (UI) features and settings to know how you use {rh-rhacs-first}, which helps prioritize efforts. +* The time you spend on UI screens to help us improve user experience. +* The integrations are used to know if there are integrations that you have never used. +* The number of connected secured clusters and their configurations. +* Errors you encounter to identify the most common problems. \ No newline at end of file diff --git a/modules/infrastructure-components.adoc b/modules/infrastructure-components.adoc deleted file mode 100644 index 7b2b19587bd6..000000000000 --- a/modules/infrastructure-components.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="infrastructure-components_{context}"] -= {product-title} infrastructure components - -The following infrastructure workloads do not incur {product-title} worker subscriptions: - -* Kubernetes and {product-title} control plane services that run on masters -* The default router -* The integrated container image registry -* The cluster metrics collection, or monitoring service, including components for monitoring user-defined projects -* Cluster aggregated logging -* Service brokers -* Red Hat Quay -* Red Hat OpenShift Container Storage -* Red Hat Advanced Cluster Manager - -Any node that runs any other container, pod, or component is a worker node that your subscription must cover. diff --git a/modules/infrastructure-moving-logging.adoc b/modules/infrastructure-moving-logging.adoc deleted file mode 100644 index a384cd165665..000000000000 --- a/modules/infrastructure-moving-logging.adoc +++ /dev/null @@ -1,226 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * logging/cluster-logging-moving.adoc - -[id="infrastructure-moving-logging_{context}"] -= Moving OpenShift Logging resources - -You can configure the Cluster Logging Operator to deploy the pods for any or all of the OpenShift Logging components, Elasticsearch, Kibana, and Curator to different nodes. You cannot move the Cluster Logging Operator pod from its installed location. - -For example, you can move the Elasticsearch pods to a separate node because of high CPU, memory, and disk requirements. - -.Prerequisites - -* OpenShift Logging and Elasticsearch must be installed. These features are not installed by default. - -.Procedure - -. Edit the `ClusterLogging` custom resource (CR) in the `openshift-logging` project: -+ -[source,terminal] ----- -$ oc edit ClusterLogging instance ----- -+ -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogging - -.... - -spec: - collection: - logs: - fluentd: - resources: null - type: fluentd - curation: - curator: - nodeSelector: <1> - node-role.kubernetes.io/infra: '' - resources: null - schedule: 30 3 * * * - type: curator - logStore: - elasticsearch: - nodeCount: 3 - nodeSelector: <1> - node-role.kubernetes.io/infra: '' - redundancyPolicy: SingleRedundancy - resources: - limits: - cpu: 500m - memory: 16Gi - requests: - cpu: 500m - memory: 16Gi - storage: {} - type: elasticsearch - managementState: Managed - visualization: - kibana: - nodeSelector: <1> - node-role.kubernetes.io/infra: '' <1> - proxy: - resources: null - replicas: 1 - resources: null - type: kibana - -.... - ----- -<1> Add a `nodeSelector` parameter with the appropriate value to the component you want to move. You can use a `nodeSelector` in the format shown or use `<key>: <value>` pairs, based on the value specified for the node. - -.Verification - -To verify that a component has moved, you can use the `oc get pod -o wide` command. - -For example: - -* You want to move the Kibana pod from the `ip-10-0-147-79.us-east-2.compute.internal` node: -+ -[source,terminal] ----- -$ oc get pod kibana-5b8bdf44f9-ccpq9 -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -kibana-5b8bdf44f9-ccpq9 2/2 Running 0 27s 10.129.2.18 ip-10-0-147-79.us-east-2.compute.internal <none> <none> ----- - -* You want to move the Kibana Pod to the `ip-10-0-139-48.us-east-2.compute.internal` node, a dedicated infrastructure node: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-133-216.us-east-2.compute.internal Ready master 60m v1.20.0 -ip-10-0-139-146.us-east-2.compute.internal Ready master 60m v1.20.0 -ip-10-0-139-192.us-east-2.compute.internal Ready worker 51m v1.20.0 -ip-10-0-139-241.us-east-2.compute.internal Ready worker 51m v1.20.0 -ip-10-0-147-79.us-east-2.compute.internal Ready worker 51m v1.20.0 -ip-10-0-152-241.us-east-2.compute.internal Ready master 60m v1.20.0 -ip-10-0-139-48.us-east-2.compute.internal Ready infra 51m v1.20.0 ----- -+ -Note that the node has a `node-role.kubernetes.io/infra: ''` label: -+ -[source,terminal] ----- -$ oc get node ip-10-0-139-48.us-east-2.compute.internal -o yaml ----- -+ -.Example output -[source,yaml] ----- -kind: Node -apiVersion: v1 -metadata: - name: ip-10-0-139-48.us-east-2.compute.internal - selfLink: /api/v1/nodes/ip-10-0-139-48.us-east-2.compute.internal - uid: 62038aa9-661f-41d7-ba93-b5f1b6ef8751 - resourceVersion: '39083' - creationTimestamp: '2020-04-13T19:07:55Z' - labels: - node-role.kubernetes.io/infra: '' -.... ----- - -* To move the Kibana pod, edit the `ClusterLogging` CR to add a node selector: -+ -[source,yaml] ----- -apiVersion: logging.openshift.io/v1 -kind: ClusterLogging - -.... - -spec: - -.... - - visualization: - kibana: - nodeSelector: <1> - node-role.kubernetes.io/infra: '' <1> - proxy: - resources: null - replicas: 1 - resources: null - type: kibana ----- -<1> Add a node selector to match the label in the node specification. - -* After you save the CR, the current Kibana pod is terminated and new pod is deployed: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -cluster-logging-operator-84d98649c4-zb9g7 1/1 Running 0 29m -elasticsearch-cdm-hwv01pf7-1-56588f554f-kpmlg 2/2 Running 0 28m -elasticsearch-cdm-hwv01pf7-2-84c877d75d-75wqj 2/2 Running 0 28m -elasticsearch-cdm-hwv01pf7-3-f5d95b87b-4nx78 2/2 Running 0 28m -fluentd-42dzz 1/1 Running 0 28m -fluentd-d74rq 1/1 Running 0 28m -fluentd-m5vr9 1/1 Running 0 28m -fluentd-nkxl7 1/1 Running 0 28m -fluentd-pdvqb 1/1 Running 0 28m -fluentd-tflh6 1/1 Running 0 28m -kibana-5b8bdf44f9-ccpq9 2/2 Terminating 0 4m11s -kibana-7d85dcffc8-bfpfp 2/2 Running 0 33s ----- - -* The new pod is on the `ip-10-0-139-48.us-east-2.compute.internal` node: -+ -[source,terminal] ----- -$ oc get pod kibana-7d85dcffc8-bfpfp -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -kibana-7d85dcffc8-bfpfp 2/2 Running 0 43s 10.131.0.22 ip-10-0-139-48.us-east-2.compute.internal <none> <none> ----- - -* After a few moments, the original Kibana pod is removed. -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -cluster-logging-operator-84d98649c4-zb9g7 1/1 Running 0 30m -elasticsearch-cdm-hwv01pf7-1-56588f554f-kpmlg 2/2 Running 0 29m -elasticsearch-cdm-hwv01pf7-2-84c877d75d-75wqj 2/2 Running 0 29m -elasticsearch-cdm-hwv01pf7-3-f5d95b87b-4nx78 2/2 Running 0 29m -fluentd-42dzz 1/1 Running 0 29m -fluentd-d74rq 1/1 Running 0 29m -fluentd-m5vr9 1/1 Running 0 29m -fluentd-nkxl7 1/1 Running 0 29m -fluentd-pdvqb 1/1 Running 0 29m -fluentd-tflh6 1/1 Running 0 29m -kibana-7d85dcffc8-bfpfp 2/2 Running 0 62s ----- diff --git a/modules/infrastructure-moving-monitoring.adoc b/modules/infrastructure-moving-monitoring.adoc deleted file mode 100644 index 63d9ad1298c6..000000000000 --- a/modules/infrastructure-moving-monitoring.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc - -[id="infrastructure-moving-monitoring_{context}"] -= Moving the monitoring solution - - -By default, the Prometheus Cluster Monitoring stack, which contains Prometheus, Grafana, and AlertManager, is deployed to provide cluster monitoring. It is managed by the Cluster Monitoring Operator. To move its components to different machines, you create and apply a custom config map. - -.Procedure - -. Save the following `ConfigMap` definition as the `cluster-monitoring-configmap.yaml` file: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: |+ - alertmanagerMain: - nodeSelector: - node-role.kubernetes.io/infra: "" - prometheusK8s: - nodeSelector: - node-role.kubernetes.io/infra: "" - prometheusOperator: - nodeSelector: - node-role.kubernetes.io/infra: "" - grafana: - nodeSelector: - node-role.kubernetes.io/infra: "" - k8sPrometheusAdapter: - nodeSelector: - node-role.kubernetes.io/infra: "" - kubeStateMetrics: - nodeSelector: - node-role.kubernetes.io/infra: "" - telemeterClient: - nodeSelector: - node-role.kubernetes.io/infra: "" - openshiftStateMetrics: - nodeSelector: - node-role.kubernetes.io/infra: "" - thanosQuerier: - nodeSelector: - node-role.kubernetes.io/infra: "" ----- -+ -Running this config map forces the components of the monitoring stack to redeploy to infrastructure nodes. - -. Apply the new config map: -+ -[source,terminal] ----- -$ oc create -f cluster-monitoring-configmap.yaml ----- - -. Watch the monitoring pods move to the new machines: -+ -[source,terminal] ----- -$ watch 'oc get pod -n openshift-monitoring -o wide' ----- - -. If a component has not moved to the `infra` node, delete the pod with this component: -+ -[source,terminal] ----- -$ oc delete pod -n openshift-monitoring <pod> ----- -+ -The component from the deleted pod is re-created on the `infra` node. diff --git a/modules/infrastructure-moving-registry.adoc b/modules/infrastructure-moving-registry.adoc deleted file mode 100644 index 11959f9a3e08..000000000000 --- a/modules/infrastructure-moving-registry.adoc +++ /dev/null @@ -1,85 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc - -[id="infrastructure-moving-registry_{context}"] -= Moving the default registry - -You configure the registry Operator to deploy its pods to different nodes. - -.Prerequisites - -* Configure additional machine sets in your {product-title} cluster. - -.Procedure - -. View the `config/instance` object: -+ -[source,terminal] ----- -$ oc get configs.imageregistry.operator.openshift.io cluster -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: imageregistry.operator.openshift.io/v1 -kind: Config -metadata: - creationTimestamp: 2019-02-05T13:52:05Z - finalizers: - - imageregistry.operator.openshift.io/finalizer - generation: 1 - name: cluster - resourceVersion: "56174" - selfLink: /apis/imageregistry.operator.openshift.io/v1/configs/cluster - uid: 36fd3724-294d-11e9-a524-12ffeee2931b -spec: - httpSecret: d9a012ccd117b1e6616ceccb2c3bb66a5fed1b5e481623 - logging: 2 - managementState: Managed - proxy: {} - replicas: 1 - requests: - read: {} - write: {} - storage: - s3: - bucket: image-registry-us-east-1-c92e88cad85b48ec8b312344dff03c82-392c - region: us-east-1 -status: -... ----- - -. Edit the `config/instance` object: -+ -[source,terminal] ----- -$ oc edit configs.imageregistry.operator.openshift.io cluster ----- - -. Add the following lines of text the `spec` section of the object: -+ -[source,yaml] ----- - nodeSelector: - node-role.kubernetes.io/infra: "" ----- - -. Verify the registry pod has been moved to the infrastructure node. -+ -.. Run the following command to identify the node where the registry pod is located: -+ -[source,terminal] ----- -$ oc get pods -o wide -n openshift-image-registry ----- -+ -.. Confirm the node has the label you specified: -+ -[source,terminal] ----- -$ oc describe node <node_name> ----- -+ -Review the command output and confirm that `node-role.kubernetes.io/infra` is in the `LABELS` list. diff --git a/modules/infrastructure-moving-router.adoc b/modules/infrastructure-moving-router.adoc deleted file mode 100644 index f5441918525f..000000000000 --- a/modules/infrastructure-moving-router.adoc +++ /dev/null @@ -1,103 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc - -[id="infrastructure-moving-router_{context}"] -= Moving the router - -You can deploy the router pod to a different machine set. By default, the pod is deployed to a worker node. - -.Prerequisites - -* Configure additional machine sets in your {product-title} cluster. - -.Procedure - -. View the `IngressController` custom resource for the router Operator: -+ -[source,terminal] ----- -$ oc get ingresscontroller default -n openshift-ingress-operator -o yaml ----- -+ -The command output resembles the following text: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - creationTimestamp: 2019-04-18T12:35:39Z - finalizers: - - ingresscontroller.operator.openshift.io/finalizer-ingresscontroller - generation: 1 - name: default - namespace: openshift-ingress-operator - resourceVersion: "11341" - selfLink: /apis/operator.openshift.io/v1/namespaces/openshift-ingress-operator/ingresscontrollers/default - uid: 79509e05-61d6-11e9-bc55-02ce4781844a -spec: {} -status: - availableReplicas: 2 - conditions: - - lastTransitionTime: 2019-04-18T12:36:15Z - status: "True" - type: Available - domain: apps.<cluster>.example.com - endpointPublishingStrategy: - type: LoadBalancerService - selector: ingresscontroller.operator.openshift.io/deployment-ingresscontroller=default ----- - -. Edit the `ingresscontroller` resource and change the `nodeSelector` to use the `infra` label: -+ -[source,terminal] ----- -$ oc edit ingresscontroller default -n openshift-ingress-operator ----- -+ -Add the `nodeSelector` stanza that references the `infra` label to the `spec` section, as shown: -+ -[source,yaml] ----- - spec: - nodePlacement: - nodeSelector: - matchLabels: - node-role.kubernetes.io/infra: "" ----- - -. Confirm that the router pod is running on the `infra` node. -.. View the list of router pods and note the node name of the running pod: -+ -[source,terminal] ----- -$ oc get pod -n openshift-ingress -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -router-default-86798b4b5d-bdlvd 1/1 Running 0 28s 10.130.2.4 ip-10-0-217-226.ec2.internal <none> <none> -router-default-955d875f4-255g8 0/1 Terminating 0 19h 10.129.2.4 ip-10-0-148-172.ec2.internal <none> <none> ----- -+ -In this example, the running pod is on the `ip-10-0-217-226.ec2.internal` node. - -.. View the node status of the running pod: -+ -[source,terminal] ----- -$ oc get node <node_name> <1> ----- -<1> Specify the `<node_name>` that you obtained from the pod list. -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-217-226.ec2.internal Ready infra,worker 17h v1.20.0 ----- -+ -Because the role list includes `infra`, the pod is running on the correct node. diff --git a/modules/infrastructure-node-sizing.adoc b/modules/infrastructure-node-sizing.adoc deleted file mode 100644 index 917525cb1dbd..000000000000 --- a/modules/infrastructure-node-sizing.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/recommended-host-practices.adoc - -[id="infrastructure-node-sizing_{context}"] -= Infrastructure node sizing - -The infrastructure node resource requirements depend on the cluster age, nodes, and objects in the cluster, as these factors can lead to an increase in the number of metrics or time series in Prometheus. The following infrastructure node size recommendations are based on the results of cluster maximums and control plane density focused testing. - -[options="header",cols="3*"] -|=== -| Number of worker nodes |CPU cores |Memory (GB) - -| 25 -| 4 -| 16 - -| 100 -| 8 -| 32 - -| 250 -| 16 -| 128 - -| 500 -| 32 -| 128 - -|=== - -[IMPORTANT] -==== -These sizing recommendations are based on scale tests, which create a large number of objects across the cluster. These tests include reaching some of the cluster maximums. In the case of 250 and 500 node counts on a {product-title} {product-version} cluster, these maximums are 10000 namespaces with 61000 pods, 10000 deployments, 181000 secrets, 400 config maps, and so on. Prometheus is a highly memory intensive application; the resource usage depends on various factors including the number of nodes, objects, the Prometheus metrics scraping interval, metrics or time series, and the age of the cluster. The disk size also depends on the retention period. You must take these factors into consideration and size them accordingly. - -These sizing recommendations are only applicable for the Prometheus, Router, and Registry infrastructure components, which are installed during cluster installation. Logging is a day-two operation and is not included in these recommendations. -==== - -[NOTE] -==== -In {product-title} {product-version}, half of a CPU core (500 millicore) is now reserved by the system by default compared to {product-title} 3.11 and previous versions. This influences the stated sizing recommendations. -==== diff --git a/modules/ingress-operator.adoc b/modules/ingress-operator.adoc deleted file mode 100644 index 750dca298571..000000000000 --- a/modules/ingress-operator.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="ingress-operator_{context}"] -= Ingress Operator - -[discrete] -== Purpose - -The Ingress Operator configures and manages the {product-title} router. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-ingress-operator[openshift-ingress-operator] - -[discrete] -== CRDs - -* `clusteringresses.ingress.openshift.io` -** Scope: Namespaced -** CR: `clusteringresses` -** Validation: No - -[discrete] -== Configuration objects - -* Cluster config -** Type Name: `clusteringresses.ingress.openshift.io` -** Instance Name: `default` -** View Command: -+ -[source,terminal] ----- -$ oc get clusteringresses.ingress.openshift.io -n openshift-ingress-operator default -o yaml ----- - -[discrete] -== Notes - -The Ingress Operator sets up the router in the `openshift-ingress` project and creates the deployment for the router: - -[source,terminal] ----- -$ oc get deployment -n openshift-ingress ----- - -The Ingress Operator uses the `clusterNetwork[].cidr` from the `network/cluster` status to determine what mode (IPv4, IPv6, or dual stack) the managed ingress controller (router) should operate in. For example, if `clusterNetwork` contains only a v6 `cidr`, then the ingress controller operate in IPv6-only mode. - -In the following example, ingress controllers managed by the Ingress Operator will run in IPv4-only mode because only one cluster network exists and the network is an IPv4 `cidr`: - -[source,terminal] ----- -$ oc get network/cluster -o jsonpath='{.status.clusterNetwork[*]}' ----- - -.Example output -[source,terminal] ----- -map[cidr:10.128.0.0/14 hostPrefix:23] ----- diff --git a/modules/insights-operator-about.adoc b/modules/insights-operator-about.adoc deleted file mode 100644 index fec7920e546c..000000000000 --- a/modules/insights-operator-about.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * support/remote_health_monitoring/about-remote-health-monitoring.adoc - -[id="insights-operator-about_{context}"] -= About the Insights Operator - -The Insights Operator periodically gathers configuration and component failure status and, by default, reports that data every two hours to Red Hat. This information enables Red Hat to assess configuration and deeper failure data than is reported through Telemetry. - -Users of {product-title} can display the report of each cluster in {cloud-redhat-com}. If any issues have been identified, Insights provides further details and, if available, steps on how to solve a problem. - -The Insights Operator does not collect identifying information, such as user names, passwords, or certificates. See link:https://cloud.redhat.com/security/insights[Red Hat Insights Data & Application Security] for information about Red Hat Insights data collection and controls. - -Red Hat uses all connected cluster information to: - -* Proactively identify potential cluster issues and provide a solution and preventive actions in {cloud-redhat-com} -* Improve {product-title} by providing aggregated and critical information to product and support teams -* Make {product-title} more intuitive diff --git a/modules/insights-operator-new-pull-secret-disabled.adoc b/modules/insights-operator-new-pull-secret-disabled.adoc deleted file mode 100644 index c44df0d6c574..000000000000 --- a/modules/insights-operator-new-pull-secret-disabled.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * support/insights-operator/disabling-insights-operator.adoc - -[id="insights-operator-new-pull-secret_{context}"] -= Modifying the global cluster pull secret to disable remote health reporting - -You can modify your existing global cluster pull secret to disable remote health reporting. This disables both Telemetry and the Insights Operator. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Download the global cluster pull secret to your local file system. -+ -[source,terminal] ----- -$ oc extract secret/pull-secret -n openshift-config --to=. ----- - -. In a text editor, edit the `.dockerconfigjson` file that was downloaded. - -. Remove the `cloud.openshift.com` JSON entry, for example: -+ -[source,json] ----- -"cloud.openshift.com":{"auth":"<hash>","email":"<email_address>"} ----- - -. Save the file. - -You can now update your cluster to use this modified pull secret. diff --git a/modules/insights-operator-showing-data-collected-from-the-cluster.adoc b/modules/insights-operator-showing-data-collected-from-the-cluster.adoc deleted file mode 100644 index 2566acbc3862..000000000000 --- a/modules/insights-operator-showing-data-collected-from-the-cluster.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * support/remote_health_monitoring/showing-data-collected-by-remote-health-reporting.adoc - -[id="insights-operator-showing-data-collected-from-the-cluster_{context}"] -= Showing data collected by the Insights Operator - -You can review the data that is collected by the Insights Operator. - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Find the name of the currently running pod for the Insights Operator: -+ -[source,terminal] ----- -$ INSIGHTS_OPERATOR_POD=$(oc get pods --namespace=openshift-insights -o custom-columns=:metadata.name --no-headers --field-selector=status.phase=Running) ----- - -. Copy the recent data archives collected by the Insights Operator: -+ -[source,terminal] ----- -$ oc cp openshift-insights/$INSIGHTS_OPERATOR_POD:/var/lib/insights-operator ./insights-data ----- - -The recent Insights Operator archives are now available in the `insights-data` directory. diff --git a/modules/insights-operator-what-information-is-collected.adoc b/modules/insights-operator-what-information-is-collected.adoc deleted file mode 100644 index f9c29b8a7dea..000000000000 --- a/modules/insights-operator-what-information-is-collected.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * support/remote_health_monitoring/about-remote-health-monitoring.adoc - -[id="insights-operator-what-information-is-collected_{context}"] -= Information collected by the Insights Operator - -The following information is collected by the Insights Operator: - -* General information about your cluster and its components to identify issues that are specific to your {product-title} version and environment -* Configuration files, such as the image registry configuration, of your cluster to determine incorrect settings and issues that are specific to parameters you set -* Errors that occur in the cluster components -* Progress information of running updates, and the status of any component upgrades -* Details of the platform that {product-title} is deployed on, such as Amazon Web Services, and the region that the cluster is located in -* If an Operator reports an issue, information is collected about core {product-title} pods in the `openshift-&#42;` and `kube-&#42;` projects. This includes state, resource, security context, volume information, and more. - diff --git a/modules/inspect-online-telemetry-data.adoc b/modules/inspect-online-telemetry-data.adoc new file mode 100644 index 000000000000..14e5e94ac7dc --- /dev/null +++ b/modules/inspect-online-telemetry-data.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * configuration/online-telemetry.adoc +:_mod-docs-content-type: PROCEDURE +[id="inspect-online-telemetry-data_{context}"] += Inspecting online telemetry data + +You can inspect the data that {product-title} collects for online telemetry. + +.Procedure +. Generate a diagnostic bundle. +//TODO: Add link +. The diagnostic bundle (compressed zip file) includes a `telemetry.json` file. +. Inspect the contents of the `telemetry.json` file. + +[NOTE] +==== +The online telemetry data only includes data that is in the `telemetry.json` file and not the contents of the whole diagnostic bundle. +==== + diff --git a/modules/inspecting-pod-and-container-logs.adoc b/modules/inspecting-pod-and-container-logs.adoc deleted file mode 100644 index bbea9e61d6b7..000000000000 --- a/modules/inspecting-pod-and-container-logs.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/investigating-pod-issues.adoc - -[id="inspecting-pod-and-container-logs_{context}"] -= Inspecting pod and container logs - -You can inspect pod and container logs for warnings and error messages related to explicit pod failures. Depending on policy and exit code, pod and container logs remain available after pods have been terminated. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Query logs for a specific pod: -+ -[source,terminal] ----- -$ oc logs <pod_name> ----- - -. Query logs for a specific container within a pod: -+ -[source,terminal] ----- -$ oc logs <pod_name> -c <container_name> ----- -+ -Logs retrieved using the preceding `oc logs` commands are composed of messages sent to stdout within pods or containers. - -. Inspect logs contained in `/var/log/` within a pod. -.. List log files and subdirectories contained in `/var/log` within a pod: -+ -[source,terminal] ----- -$ oc exec <pod_name> ls -alh /var/log ----- -+ -.. Query a specific log file contained in `/var/log` within a pod: -+ -[source,terminal] ----- -$ oc exec <pod_name> cat /var/log/<path_to_log> ----- -.. List log files and subdirectories contained in `/var/log` within a specific container: -+ -[source,terminal] ----- -$ oc exec <pod_name> -c <container_name> ls /var/log ----- -+ -.. Query a specific log file contained in `/var/log` within a specific container: -+ -[source,terminal] ----- -$ oc exec <pod_name> -c <container_name> cat /var/log/<path_to_log> ----- diff --git a/modules/install-acs-operator-annotations.adoc b/modules/install-acs-operator-annotations.adoc new file mode 100644 index 000000000000..0cd7a68d5cea --- /dev/null +++ b/modules/install-acs-operator-annotations.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * installing/install-ocp-operator.adoc +:_mod-docs-content-type: CONCEPT +[id="install-acs-operator-annotations_{context}"] += Operator annotations used during installation + +[role="_abstract"] +{product-title-short} uses annotations attached to the custom resource (CR) so that for installations performed by using the Operator, the default values for certain configuration items are decided at runtime by the Operator based on the current environment, allowing the previously configured value of an item to persist. + +For some configuration items, using a static default value for the installation is not ideal. Beginning with {product-title-short} version 4.8, the Operator can add annotations that are attached to the CR that you apply to clusters. These annotations allow a default decision that the Operator previously made to persist and be reapplied in the future, even if the default behavior for a fresh installation has changed. In summary, {product-title-short} uses annotations to persist runtime defaults. This means that the default value for a certain configuration setting is decided by the Operator at runtime. + +For example, in release 4.8 and later, if a value is not specified for enabling Scanner V4, the default behavior is to enable Scanner V4. However, if a value is configured in the CR, such as `disable`, then {product-title-short} uses that value. In the Scanner V4 example, Scanner V4 was disabled by default in version 4.7; when updating to version 4.8 by using the Operator, that disabled setting persists and Scanner V4 is disabled. + +Annotations are in the form `feature-defaults.platform.stackrox.io/<identifier>`. For example, `feature-defaults.platform.stackrox.io/scannerV4` is the annotation that allows the Operator to keep the default Scanner V4 enablement toggle stable during updating to {product-title-short} version 4.8. + +[IMPORTANT] +==== +Do not change or delete these annotations. +==== diff --git a/modules/install-acs-operator-cloud.adoc b/modules/install-acs-operator-cloud.adoc new file mode 100644 index 000000000000..489c2dd184f3 --- /dev/null +++ b/modules/install-acs-operator-cloud.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * cloud_service/installing_cloud_ocp/cloud-install-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="install-acs-operator-cloud_{context}"] += Installing the {product-title-short} Operator for {product-title-managed-short} + +[role="_abstract"] +Using the OperatorHub provided with {ocp} is the easiest way to install the {product-title-short} Operator. + +.Prerequisites +* You have access to an {ocp} cluster using an account with Operator installation permissions. +* You must be using {ocp} {ocp-supported-version} or later. For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. + +.Procedure +. In the web console, go to the *Operators* -> *OperatorHub* page. + +. If {product-title} is not displayed, enter *Advanced Cluster Security* into the *Filter by keyword* box to find the {product-title} Operator. + +. Select the *{product-title} Operator* to view the details page. + +. Read the information about the Operator, and then click *Install*. + +. On the *Install Operator* page: + +** Keep the default value for *Installation mode* as *All namespaces on the cluster*. +** Select a specific namespace in which to install the Operator for the *Installed namespace* field. Install the {product-title} Operator in the *rhacs-operator* namespace. +** Select automatic or manual updates for *Update approval*. ++ +If you select automatic updates, when a new version of the Operator is available, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator. ++ +If you select manual updates, when a newer version of the Operator is available, OLM creates an update request. As a cluster administrator, you must manually approve the update request to update the Operator to the latest version. ++ +Red{nbsp}Hat recommends enabling automatic upgrades for Operator in {product-title-managed-short}. See the link:https://access.redhat.com/articles/7045053[Red Hat Advanced Cluster Security for Kubernetes Support Matrix] for more information. +. Click *Install*. + +.Verification +* After the installation completes, go to *Operators* -> *Installed Operators* to verify that the {product-title} Operator is listed with the status of *Succeeded*. diff --git a/modules/install-acs-operator.adoc b/modules/install-acs-operator.adoc new file mode 100644 index 000000000000..49363f243df8 --- /dev/null +++ b/modules/install-acs-operator.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-ocp.adoc + +:_mod-docs-content-type: PROCEDURE +[id="install-acs-operator_{context}"] += Installing the {product-title} Operator + +[role="_abstract"] +Using the OperatorHub provided with {ocp} is the easiest way to install {product-title}. + +.Prerequisites +* You have access to an {ocp} cluster using an account with Operator installation permissions. +* You must be using {ocp} {ocp-supported-version} or later. For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. For life cycle support information for {product-title-short}, see the link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. + +.Procedure +. In the web console, go to the *Operators* -> *OperatorHub* page. + +. If {product-title} is not displayed, enter *Advanced Cluster Security* into the *Filter by keyword* box to find the {product-title} Operator. + +. Select the *{product-title} Operator* to view the details page. + +. Read the information about the Operator, and then click *Install*. + +. On the *Install Operator* page: + +** Keep the default value for *Installation mode* as *All namespaces on the cluster*. +** Choose a specific namespace in which to install the Operator for the *Installed namespace* field. Install the {product-title} Operator in the *rhacs-operator* namespace. +** Select automatic or manual updates for *Update approval*. ++ +If you choose automatic updates, when a new version of the Operator is available, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator. ++ +If you choose manual updates, when a newer version of the Operator is available, OLM creates an update request. As a cluster administrator, you must manually approve the update request to update the Operator to the latest version. ++ +[IMPORTANT] +==== +If you choose manual updates, you must update the {product-title-short} Operator in all secured clusters when you update the {product-title-short} Operator in the cluster where Central is installed. The secured clusters and the cluster where Central is installed must have the same version to ensure optimal functionality. +==== + +. Click *Install*. + +.Verification +* After the installation completes, go to *Operators* -> *Installed Operators* to verify that the {product-title} Operator is listed with the status of *Succeeded*. + +After you install the Operator into the *rhacs-operator* project, you can install, configure, and deploy the `Central` custom resource (CR) into the `stackrox` project by using the installed Operator. \ No newline at end of file diff --git a/modules/install-and-configure-the-splunk-add-on.adoc b/modules/install-and-configure-the-splunk-add-on.adoc new file mode 100644 index 000000000000..c002a5d18a18 --- /dev/null +++ b/modules/install-and-configure-the-splunk-add-on.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-splunk.adoc +:_mod-docs-content-type: PROCEDURE +[id="install-and-configure-the-splunk-add-on_{context}"] += Installing and configuring the Splunk add-on + +You can install the {product-title} add-on from your Splunk instance. + +[NOTE] +==== +To maintain backward compatibility with the StackRox Kubernetes Security Platform add-on, the `source_type` and `input_type` parameters for configured inputs are still called `stackrox_compliance`, `stackrox_violations`, and `stackrox_vulnerability_management`. +==== + +.Prerequisites +* You must have an API token with `read` permission for all resources of {product-title}. You can assign the *Analyst* system role to grant this level of access. The *Analyst* role has read permissions for all resources. + +.Procedure +. Download the {product-title} add-on from link:https://splunkbase.splunk.com/app/5315/[Splunkbase]. +. Go to the Splunk home page on your Splunk instance. +. Go to *Apps* -> *Manage Apps*. +. Select *Install app from file*. +. In the *Upload app* pop-up box, select *Choose File* and select the {product-title} add-on file. +. Click *Upload*. +. Click *Restart Splunk*, and confirm to restart. +. After Splunk restarts, select *{product-title}* from the *Apps* menu. +. Go to *Configuration* and then click *Add-on Settings*. +.. For *Central Endpoint*, enter the IP address or the name of your Central instance. For example, `central.custom:443`. +.. Enter the *API token* you have generated for the add-on. +.. Click *Save*. +. Go to *Inputs*. +. Click *Create New Input*, and select one of the following: +** *ACS Compliance* to pull the compliance data. +** *ACS Violations* to pull the violations data. +** *ACS Vulnerability Management* to pull the vulnerabilities data. +. Enter a *Name* for the input. +. Select an *Interval* to pull data from {product-title}. +For example, every 14400 seconds. +. Select the Splunk *Index* to which you want to send the data. +. For *Central Endpoint*, enter the IP address or the name of your Central instance. +. Enter the *API token* you have generated for the add-on. +. Click *Add*. + + +.Verification +* To verify the the {product-title} add-on installation, query the received data. +.. In your Splunk instance, go to *Search* and type `index=* sourcetype="stackrox-*"` as the query. +.. Press *Enter*. + +Verify that your configured sources are displayed in the search results. diff --git a/modules/install-central-operator-external-db.adoc b/modules/install-central-operator-external-db.adoc new file mode 100644 index 000000000000..da65880f9c66 --- /dev/null +++ b/modules/install-central-operator-external-db.adoc @@ -0,0 +1,96 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-ocp.adoc +:_mod-docs-content-type: PROCEDURE +[id="install-central-operator-external-db_{context}"] + += Installing Central with an external database using the Operator method + +[role="_abstract"] +The main component of {product-title} is called Central. You can install Central on {ocp} by using the `Central` custom resource. You deploy Central only once, and you can monitor multiple separate clusters by using the same Central installation. + +[IMPORTANT] +==== +When you install {product-title} for the first time, you must first install the `Central` custom resource because the `SecuredCluster` custom resource installation is dependent on certificates that Central generates. +==== + +For more information about {product-title-short} databases, see the link:https://access.redhat.com/articles/7045053#database-scope-of-coverage-7[Database Scope of Coverage]. + +.Prerequisites +* You must be using {ocp} {ocp-supported-version} or later. For more information about supported {ocp} versions, see the link:https://access.redhat.com/articles/7045053[Red Hat Advanced Cluster Security for Kubernetes Support Matrix]. ++ +[NOTE] +==== +Postgres 15 is the recommended and supported version. Red{nbsp}Hat has deprecated the support for Postgres 13 and will remove it in the newer versions of {product-title-short}. +==== +* For detailed requirements, see "Requirements for using an external database" in the additional resources section. + +.Procedure +. On the {ocp} web console, go to the *Operators* -> *Installed Operators* page. +. Select the {product-title} Operator from the list of installed Operators. +. If you have installed the Operator in the recommended namespace, {ocp} lists the project as `rhacs-operator`. Select *Project: rhacs-operator* -> *Create project*. ++ +[WARNING] +==== +* If you have installed the Operator in a different namespace, {ocp} shows the name of that namespace rather than `rhacs-operator`. +* Red{nbsp}Hat recommends installing the {product-title} `Central` custom resource in a dedicated project. Do not install it in the project where you have installed the {product-title} Operator. Additionally, do not install it in any projects with names that begin with `kube`, `openshift`, or `redhat`, and in the `istio-system` project. +==== +. Enter the new project name (for example, `stackrox`), and click *Create*. Red{nbsp}Hat recommends that you use `stackrox` as the project name. +. Create a password secret in the deployed namespace by using the {ocp} web console or the terminal. +** On the {ocp} web console, go to the *Workloads* → *Secrets* page. Create a *Key/Value secret* with the key `password` and the value as the path of a plain text file containing the password for the superuser of the provisioned database. +** Or, run the following command in your terminal: ++ +[source,terminal] +---- +$ oc create secret generic external-db-password \// <1> + --from-file=password=<password.txt> <2> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +<2> Replace `password.txt` with the path of the file which has the plain text password. +. Return to the {product-title} operator page in the {ocp} web console. Under the *Provided APIs* section, select *Central*. Click *Create Central*. +. Optional: If you are using declarative configuration, next to *Configure via:*, click *YAML view*. +. Add the information for the declarative configuration, such as shown in the following example: ++ +[source,yaml] +---- +... +spec: + central: + declarativeConfiguration: + configMaps: + - name: <declarative-configs> <1> + secrets: + - name: <sensitive-declarative-configs> <2> +... +---- +<1> Replace <declarative-configs> with the name of the config maps that you are using. +<2> Replace <sensitive-declarative-configs> with the name of the secrets that you are using. +. Enter a name for your `Central` custom resource and add any labels you want to apply. +. Go to *Central Component Settings* -> *Central DB Settings*. +. For *Administrator Password* specify the referenced secret as `external-db-password` (or the secret name of the password created previously). +. For *Connection String* specify the connection string in `keyword=value` format, for example, `host=<host> port=5432 database=stackrox user=stackrox sslmode=verify-ca` +. For *Persistence* -> *PersistentVolumeClaim* -> *Claim Name*, remove `central-db`. +. If necessary, you can specify a Certificate Authority so that there is trust between the database certificate and Central. To add this, go to the YAML view and add a TLS block under the top-level spec, as shown in the following example: ++ +[source,yaml] +---- +spec: + tls: + additionalCAs: + - name: db-ca + content: | + <certificate> +---- +//Add a link for customization options +. Click *Create*. + +[NOTE] +==== +If you are using the cluster-wide proxy, {product-title} uses that proxy configuration to connect to the external services. +==== + +.Next Steps +. Verify Central installation. +. Optional: Configure Central options. +. Generate an init bundle containing the cluster secrets that allows communication between the `Central` and `SecuredCluster` resources. You need to download this bundle, use it to generate resources on the clusters you want to secure, and securely store it. +. Install secured cluster services on each cluster you want to monitor. diff --git a/modules/install-central-operator.adoc b/modules/install-central-operator.adoc new file mode 100644 index 000000000000..e695b0650f52 --- /dev/null +++ b/modules/install-central-operator.adoc @@ -0,0 +1,123 @@ +// Module included in the following assemblies: +// +// * installing/install-ocp-operator.adoc +:_mod-docs-content-type: PROCEDURE +[id="install-central-operator_{context}"] += Installing Central using the Operator method + +[role="_abstract"] +The main component of {product-title} is called Central. You can install Central on {ocp} by using the `Central` custom resource. You deploy Central only once, and you can monitor multiple separate clusters by using the same Central installation. + +[IMPORTANT] +==== +* When you install {product-title} for the first time, you must first install the `Central` custom resource because the `SecuredCluster` custom resource installation is dependent on certificates that Central generates. +* Red{nbsp}Hat recommends installing the {product-title} `Central` custom resource in a dedicated project. Do not install it in the project where you have installed the {product-title} Operator. Additionally, do not install it in any projects with names that begin with `kube`, `openshift`, or `redhat`, and in the `istio-system` project. +==== + +.Prerequisites +* You must be using {ocp} {ocp-supported-version} or later. For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. For life cycle support information for {product-title-short}, see the link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. + +.Procedure +. On the {ocp} web console, go to the *Operators* -> *Installed Operators* page. +. Select the {product-title} Operator from the list of installed Operators. +. If you have installed the Operator in the recommended namespace, {ocp} lists the project as `rhacs-operator`. Select *Project: rhacs-operator* -> *Create project*. ++ +[NOTE] +==== +* If you installed the Operator in a different namespace, {ocp} lists the name of that namespace instead of `rhacs-operator`. +==== +. Enter the new project name (for example, `stackrox`), and click *Create*. Red{nbsp}Hat recommends that you use `stackrox` as the project name. +. Under the *Provided APIs* section, select *Central*. Click *Create Central*. +. Optional: If you are using declarative configuration, next to *Configure via:*, click *YAML view* and add the information for the declarative configuration, such as shown in the following example: ++ +[source,yaml] +---- +... +spec: + central: + declarativeConfiguration: + configMaps: + - name: "<declarative-configs>" <1> + secrets: + - name: "<sensitive-declarative-configs>" <2> +... +---- +<1> Replace <declarative-configs> with the name of the config maps that you are using. +<2> Replace <sensitive-declarative-configs> with the name of the secrets that you are using. +. Enter a name for your `Central` custom resource and add any labels you want to apply. Otherwise, accept the default values for the available options. +. You can configure available options for Central: +* Central component settings: ++ +[cols="1,3",options="header"] +|=== +|Setting +|Description + +|*Administrator password* +|Secret that contains the administrator password. Use this field if you do not want {product-title-short} to generate a password for you. + +|*Exposure* +|Settings for exposing Central by using a route, load balancer, or node port. See the `central.exposure.<parameter>` information in the "Public configuration file" section in "Installing Central services for {product-title-short} on {osp}". + +|*User-facing TLS certificate secret* +|Use this field if you want to terminate TLS in Central and serve a custom server certificate. + +|*Monitoring* +|Configures the monitoring endpoint for Central. See the `central.exposeMonitoring` parameter in the "Public configuration file" section in "Installing Central services for {product-title-short} on {osp}". + +|*Central DB Settings* +|Settings for Central DB, including data persistence. See the `central.db.<parameter>` information in the "Public configuration file" section in "Installing Central services for {product-title-short} on {osp}". + +|*Resources* +|Use these fields after consulting the documentation if you need to override the default settings for memory and CPU resources. For more information, see the "Default resource requirements for {product-title-short}" and "Recommended resource requirements for {product-title-short}" sections in the "Installation" chapter. + +|*Tolerations* +|Use this parameter to configure Central to run only on specific nodes. See the `central.tolerations` parameter in the "Public configuration file" section in "Installing Central services for {product-title-short} on {osp}". + +|*Host Aliases* +|Use this parameter to configure additional hostnames to resolve in the pod's hosts file. + +|=== +* *Scanner Component Settings*: Settings for the StackRox Scanner. See the "Scanner" table in the "Public configuration file" section in "Installing Central services for {product-title-short} on {osp}". +* *Scanner V4 Component Settings*: Settings for Scanner V4 scanner, the default scanner. See the "Scanner V4" table in the "Public configuration file" section in "Installing Central services for {product-title-short} on {osp}". ++ +You can configure the following options for Scanner V4: ++ +[cols="1,3",options="header"] +|=== +|Setting +|Description + +|*Indexer* +| The process that indexes images and creates a report of findings. You can configure replicas and autoscaling, resources, and tolerations. Before changing the default resource values, see the "Scanner V4" sections in the "Default resource requirements for {product-title-short}" and "Recommended resource requirements for {product-title-short}" sections in the "Installation" chapter. + +| *Matcher* +| The process that performs vulnerability matching of the report from the indexer against vulnerability data stored in Scanner V4 DB. You can configure replicas and autoscaling, resources, and tolerations. Before changing the default resource values, see the "Scanner V4" sections in the "Default resource requirements for {product-title-short}" and "Recommended resource requirements for {product-title-short}" sections in the "Installation" chapter. + +| *DB* +| The database that stores information for Scanner V4, including vulnerability data and index reports. You can configure persistence, resources, and tolerations. If you are using Scanner V4, a persistent volume claim (PVC) is required on Central clusters. +A PVC is strongly recommended on secured clusters for best results. Before changing the default resource values, see the "Scanner V4" sections in the "Default resource requirements for {product-title-short}" and "Recommended resource requirements for {product-title-short}" sections in the "Installation" chapter. +|=== +* *Egress*: Settings for outgoing network traffic, including whether {product-title-short} should run in online (connected) or offline (disconnected) mode. +* *TLS*: Use this field to add additional trusted root certificate authorities (CAs). +* *network*: To provide security at the network level, {product-title-short} creates default `NetworkPolicy` resources in the namespace where Central is installed. To create and manage your own network policies, in the *policies* section, select *Disabled*. By default, this option is *Enabled*. ++ +[WARNING] +==== +Disabling creation of default network policies can break communication between {product-title-short} components. If you disable creation of default policies, you must create your own network policies to allow this communication. +==== +* *Advanced configuration*: You can use these fields to perform the following actions: +** Specify additional image pull secrets +** Add custom environment variables to set for managed pods' containers +** Enable {osp} monitoring +. Click *Create*. + +[NOTE] +==== +If you are using the cluster-wide proxy, {product-title} uses that proxy configuration to connect to the external services. +==== +.Next Steps +. Verify Central installation. +. Optional: Configure Central options. +. Generate an init bundle containing the cluster secrets that allows communication between the `Central` and `SecuredCluster` resources. You need to download this bundle, use it to generate resources on the clusters you want to secure, and securely store it. +. Install secured cluster services on each cluster you want to monitor. diff --git a/modules/install-central-roxctl.adoc b/modules/install-central-roxctl.adoc new file mode 100644 index 000000000000..cc97fc191cbb --- /dev/null +++ b/modules/install-central-roxctl.adoc @@ -0,0 +1,101 @@ +// Module included in the following assemblies: +// +// * installing/install_ocp/install-central-ocp.adoc +// * installing/install_other/install-central-other.adoc +// * backup_and_restore/restore-acs.htm +:_mod-docs-content-type: PROCEDURE +[id="install-central-roxctl_{context}"] += Running the Central installation scripts + +ifeval::["{context}" == "install-central-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "install-central-other"] +:kube: +endif::[] + +ifeval::["{context}" == "restore-acs"] +:openshift: +endif::[] + +After you run the interactive installer, you can run the `setup.sh` script to install Central. + +.Procedure +. Run the `setup.sh` script to configure image registry access: ++ +[source,terminal] +---- +$ ./central-bundle/central/scripts/setup.sh +---- +. Create the necessary resources: ++ +ifdef::openshift[] +[source,terminal] +---- +$ oc create -R -f central-bundle/central +---- +endif::openshift[] +ifdef::kube[] +[source,terminal] +---- +$ kubectl create -R -f central-bundle/central +---- +endif::kube[] +. Check the deployment progress: ++ +ifdef::openshift[] +[source,terminal] +---- +$ oc get pod -n stackrox -w +---- +endif::openshift[] +ifdef::kube[] +[source,terminal] +---- +$ kubectl get pod -n stackrox -w +---- +endif::kube[] +. After Central is running, find the {product-title-short} portal IP address and open it in your browser. +Depending on the exposure method you selected when answering the prompts, use one of the following methods to get the IP address. ++ +|=== +|Exposure method |Command |Address |Example + +| *Route* +| `oc -n stackrox get route central` +| The address under the `HOST/PORT` column in the output +| `+https://central-stackrox.example.route+` + +| *Node Port* +| `oc get node -owide && oc -n stackrox get svc central-loadbalancer` +| IP or hostname of any node, on the port shown for the service +| `+https://198.51.100.0:31489+` + +| *Load Balancer* +| `oc -n stackrox get svc central-loadbalancer` +| EXTERNAL-IP or hostname shown for the service, on port 443 +| `+https://192.0.2.0+` + +| *None* +| `central-bundle/central/scripts/port-forward.sh 8443` +| `+https://localhost:8443+` +| `+https://localhost:8443+` +|=== + +[NOTE] +==== +If you have selected autogenerated password during the interactive install, you can run the following command to see it for logging into Central: +[source,terminal] +---- +$ cat central-bundle/password +---- +==== + +ifeval::["{context}" == "install-central-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "install-central-other"] +:!kube: +endif::[] \ No newline at end of file diff --git a/modules/install-central-services-helm-chart.adoc b/modules/install-central-services-helm-chart.adoc new file mode 100644 index 000000000000..3b27f8a21601 --- /dev/null +++ b/modules/install-central-services-helm-chart.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +:_mod-docs-content-type: PROCEDURE +[id="install-central-services-helm-chart_{context}"] += Installing the central-services Helm chart + +After you configure the `values-public.yaml` and `values-private.yaml` files, install the `central-services` Helm chart to deploy the centralized components (Central and Scanner). + +.Procedure + +* Run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace \ + stackrox-central-services rhacs/central-services \ + -f <path_to_values_public.yaml> -f <path_to_values_private.yaml> <1> +---- +<1> Use the `-f` option to specify the paths for your YAML configuration files. + +[NOTE] +==== +Optional: If using declarative configuration, add `-f <path_to_declarative-config-values.yaml` to this command to mount the declarative configurations file in Central. +==== diff --git a/modules/install-helm-customization-overview.adoc b/modules/install-helm-customization-overview.adoc new file mode 100644 index 000000000000..ce9273459433 --- /dev/null +++ b/modules/install-helm-customization-overview.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * installing/install-central-ocp.adoc +:_mod-docs-content-type: REFERENCE + +[id="install-helm-customization-overview"] += Installing with customizations using Helm charts +include::common-attributes.adoc[] +:context: install-helm-customization-overview + + +toc::[] + +This section describes Helm chart configuration parameters that you can use with the `helm install` and `helm upgrade` commands when installing {product-title-short} using Helm charts on the cluster where Central is installed or on secure clusters. +You can specify these parameters by using the `--set` option or by creating YAML configuration files. + +Create the following files for configuring the Helm chart for installing {product-title}: + +* Public configuration file `values-public.yaml`: Use this file to save all non-sensitive configuration options. +* Private configuration file `values-private.yaml`: Use this file to save all sensitive configuration options. Make sure that you store this file securely. + +[IMPORTANT] +==== +While using the `secured-cluster-services` Helm chart, do not modify the `values.yaml` file that is part of the chart. +==== + diff --git a/modules/install-rhacs-cloud-ocp-create-stackrox-project.adoc b/modules/install-rhacs-cloud-ocp-create-stackrox-project.adoc new file mode 100644 index 000000000000..f3fac50ad898 --- /dev/null +++ b/modules/install-rhacs-cloud-ocp-create-stackrox-project.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// +:_mod-docs-content-type: PROCEDURE +[id="cloud-ocp-create-stackrox-project_{context}"] += Creating a {product-title-managed} project on your cluster + +[role="_abstract"] +Create a project on each {ocp} cluster that you want to secure. + +.Procedure + +* In your {ocp} cluster, go to *Home* -> *Projects* and create a project for {product-title-managed-short}. Use `stackrox` as the project *Name*. \ No newline at end of file diff --git a/modules/install-roxctl-cli-linux.adoc b/modules/install-roxctl-cli-linux.adoc new file mode 100644 index 000000000000..e54e5d5f5470 --- /dev/null +++ b/modules/install-roxctl-cli-linux.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * cli/using-roxctl-cli.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="installing-cli-on-linux_{context}"] += Installing the roxctl CLI on Linux + +You can install the `roxctl` CLI binary on Linux by using the following procedure. + +[NOTE] +==== +`roxctl` CLI for Linux is available for `amd64`, `arm64`, `ppc64le`, and `s390x` architectures. +==== + +.Procedure + +. Determine the `roxctl` architecture for the target operating system: ++ +[source,terminal,subs=attributes+] +---- +$ arch="$(uname -m | sed "s/x86_64//")"; arch="${arch:+-$arch}" +---- + +. Download the `roxctl` CLI: ++ +[source,terminal,subs=attributes+] +---- +$ curl -L -f -o roxctl "https://mirror.openshift.com/pub/rhacs/assets/%7Brhacs-version%7D/bin/Linux/roxctl$%7Barch%7D" +---- + +. Make the `roxctl` binary executable: ++ +[source,terminal] +---- +$ chmod +x roxctl +---- +. Place the `roxctl` binary in a directory that is on your `PATH`: ++ +To check your `PATH`, execute the following command: ++ +[source,terminal] +---- +$ echo $PATH +---- + +.Verification + +* Verify the `roxctl` version you have installed: ++ +[source,terminal] +---- +$ roxctl version +---- diff --git a/modules/install-roxctl-cli-macos.adoc b/modules/install-roxctl-cli-macos.adoc new file mode 100644 index 000000000000..f7d3b0f0a1a9 --- /dev/null +++ b/modules/install-roxctl-cli-macos.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// * cli/using-roxctl-cli.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="installing-cli-on-macos_{context}"] += Installing the roxctl CLI on macOS + +You can install the `roxctl` CLI binary on macOS by using the following procedure. + +[NOTE] +==== +`roxctl` CLI for macOS is available for `amd64` and `arm64` architectures. +==== + +.Procedure + +. Determine the `roxctl` architecture for the target operating system: ++ +[source,terminal,subs=attributes+] +---- +$ arch="$(uname -m | sed "s/x86_64//")"; arch="${arch:+-$arch}" +---- + +. Download the `roxctl` CLI: ++ +[source,terminal,subs=attributes+] +---- +$ curl -L -f -o roxctl "https://mirror.openshift.com/pub/rhacs/assets/%7Brhacs-version%7D/bin/Darwin/roxctl$%7Barch%7D" +---- + +. Remove all extended attributes from the binary: ++ +[source,terminal] +---- +$ xattr -c roxctl +---- +. Make the `roxctl` binary executable: ++ +[source,terminal] +---- +$ chmod +x roxctl +---- +. Place the `roxctl` binary in a directory that is on your `PATH`: ++ +To check your `PATH`, execute the following command: ++ +[source,terminal] +---- +$ echo $PATH +---- + +.Verification + +* Verify the `roxctl` version you have installed: ++ +[source,terminal] +---- +$ roxctl version +---- diff --git a/modules/install-roxctl-cli-windows.adoc b/modules/install-roxctl-cli-windows.adoc new file mode 100644 index 000000000000..76a3146ae300 --- /dev/null +++ b/modules/install-roxctl-cli-windows.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * cli/using-roxctl-cli.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="installing-cli-on-windows_{context}"] += Installing the roxctl CLI on Windows + +You can install the `roxctl` CLI binary on Windows by using the following procedure. + +[NOTE] +==== +`roxctl` CLI for Windows is available for the `amd64` architecture. +==== + +.Procedure + +* Download the `roxctl` CLI: ++ +[source,terminal,subs=attributes+] +---- +$ curl -f -O https://mirror.openshift.com/pub/rhacs/assets/{rhacs-version}/bin/Windows/roxctl.exe +---- + +.Verification + +* Verify the `roxctl` version you have installed: ++ +[source,terminal] +---- +$ roxctl version +---- \ No newline at end of file diff --git a/modules/install-scanner-roxctl.adoc b/modules/install-scanner-roxctl.adoc new file mode 100644 index 000000000000..fac9309e775a --- /dev/null +++ b/modules/install-scanner-roxctl.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * installing/install-quick-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="install-scanner-roxctl_{context}"] += Installing Scanner + +ifeval::["{context}" == "install-secured-cluster-cloud-other"] +:cloud-svc: +endif::[] + + +[role="_abstract"] +You can configure {product-title} to obtain image data from a variety of open-source and commercial image scanners. +//Link to image scanners topic + +However, {product-title} also provides an image vulnerability scanner component, called Scanner. It enriches deployments with image vulnerability information. + +Red{nbsp}Hat recommends deploying Scanner so that it can scan all images, including the images from public registries, for vulnerabilities. +You can deploy the Scanner in the same cluster with Central. + +.Prerequisites +* You must configure your image registry to allow Scanner to download and scan images. Usually, image registry integrations are created automatically by {product-title}. +//See Image Registry integration for the details. + +.Procedure +. Run the following command to configure image registry access: ++ +[source,terminal] +---- +$ ./central-bundle/scanner/scripts/setup.sh +---- +. After the script finishes, run the following command to create the scanner service: +ifndef::cloud-svc[] ++ +[source,terminal] +---- +$ oc create -R -f central-bundle/scanner +---- +endif::[] +ifdef::cloud-svc[] ++ +[source,terminal] +---- +$ kubectl create -R -f central-bundle/scanner +---- +endif::[] + + diff --git a/modules/install-secured-cluster-operator.adoc b/modules/install-secured-cluster-operator.adoc new file mode 100644 index 000000000000..af88497ea9d3 --- /dev/null +++ b/modules/install-secured-cluster-operator.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// * installing/install_cloud_ocp/install-secured-cluster-cloud-ocp.adoc +// * installing/installing_ocp/install-secured-cluster-ocp.adoc + +:_mod-docs-content-type: PROCEDURE +[id="install-secured-cluster-operator_{context}"] += Installing secured cluster services + +ifeval::["{context}" == "install-secured-cluster-cloud-ocp"] +:cloud-svc: +endif::[] + +[role="_abstract"] +You can install Secured Cluster services on your clusters by using the Operator, which creates the `SecuredCluster` custom resource. You must install the Secured Cluster services on every cluster in your environment that you want to monitor. + +[IMPORTANT] +==== +When you install {product-title}: + +* If you are installing {product-title-short} for the first time, you must first install the `Central` custom resource because the `SecuredCluster` custom resource installation is dependent on certificates that Central generates. +* Do not install `SecuredCluster` in projects whose names start with `kube`, `openshift`, or `redhat`, or in the `istio-system` project. +* If you are installing {product-title-short} `SecuredCluster` custom resource on a cluster that also hosts Central, ensure that you install it in the same namespace as Central. +* If you are installing {product-title} `SecuredCluster` custom resource on a cluster that does not host Central, Red{nbsp}Hat recommends that you install the {product-title} `SecuredCluster` custom resource in its own project and not in the project in which you have installed the {product-title} Operator. +==== + +.Prerequisites +* If you are using {ocp}, you must install version {ocp-supported-version} or later. +* You have installed the {product-title-short} Operator on the cluster that you want to secure, called the secured cluster. +* You have generated an init bundle or cluster registration secret (CRS) and applied it to the cluster in the recommended `stackrox` namespace. + +.Procedure +. On the {ocp} web console for the secured cluster, go to the *Operators* -> *Installed Operators* page. +. Click the {product-title-short} Operator. +. If you have installed the Operator in the recommended namespace, {ocp} lists the project as `rhacs-operator`. ++ +[NOTE] +==== +* If you installed the Operator in a different namespace, {ocp} lists the name of that namespace instead of `rhacs-operator`. +==== +. Click *Installed Operators*. +. You should have created the `stackrox` namespace when you applied the init bundle or the CRS. Make sure that you are in this namespace by verifying that *Project:stackrox* is selected in the menu. +. In *Provided APIs*, click *Secured Cluster*. +. Click *Create SecuredCluster*. +. Select one of the following options in the *Configure via* field: +* *Form view*: Use this option if you want to use the on-screen fields to configure the secured cluster and do not need to change any other fields. +* *YAML view*: Use this view to set up the secured cluster by using the YAML file. The YAML file is displayed in the window and you can edit fields in it. If you select this option, when you are finished editing the file, click *Create*. +. If you are using *Form view*, enter the new project name by accepting or editing the default name. The default value is *stackrox-secured-cluster-services*. +. Optional: Add any labels for the cluster. +. Enter a unique name for your `SecuredCluster` custom resource. +. For *Central Endpoint*, enter the address of your Central instance. For example, if Central is available at `\https://central.example.com`, then specify the central endpoint as `central.example.com`. +ifdef::cloud-svc[] +* For {product-title-managed-short} use the *Central API Endpoint* address. You can view this information by choosing *Advanced Cluster Security* -> *ACS Instances* from the Red{nbsp}Hat Hybrid Cloud Console navigation menu, then clicking the {product-title-short} instance you created. +endif::cloud-svc[] +* Use the default value of `central.stackrox.svc:443` _only_ if you are installing secured cluster services in the same cluster where Central is installed. +* Do not use the default value when you are configuring multiple clusters. Instead, use the hostname when configuring the *Central Endpoint* value for each cluster. +. For the remaining fields, accept the default values or configure custom values if needed. For example, you might need to configure TLS if you are using custom certificates or untrusted CAs. See "Configuring Secured Cluster services options for {product-title-short} using the Operator" for more information. +. Click *Create*. +. After a brief pause, the *SecuredClusters* page displays the status of `stackrox-secured-cluster-services`. You might see the following conditions: +* *Conditions: Deployed, Initialized*: The secured cluster services have been installed and the secured cluster is communicating with Central. +* *Conditions: Initialized, Irreconcilable*: The secured cluster is not communicating with Central. Make sure that you applied the init bundle you created in the {product-title-short} web portal to the secured cluster. + +.Next steps +. Configure additional secured cluster settings (optional). +. Verify installation. + +ifeval::["{context}" == "install-secured-cluster-cloud-ocp"] +:!cloud-svc: +endif::[] diff --git a/modules/install-secured-cluster-services-helm-chart.adoc b/modules/install-secured-cluster-services-helm-chart.adoc new file mode 100644 index 000000000000..7b02da45edea --- /dev/null +++ b/modules/install-secured-cluster-services-helm-chart.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +:_mod-docs-content-type: PROCEDURE +[id="install-secured-cluster-services-helm-chart_{context}"] += Installing the secured-cluster-services Helm chart with customizations + +After you configure the `values-public.yaml` and `values-private.yaml` files, install the `secured-cluster-services` Helm chart to deploy the following per-cluster and per-node components: + +* Sensor +* Admission controller +* Collector +* Scanner: optional for secured clusters when the StackRox Scanner is installed +* Scanner DB: optional for secured clusters when the StackRox Scanner is installed +* Scanner V4 Indexer and Scanner V4 DB: optional for secured clusters when Scanner V4 is installed + +.Prerequisites +* You must have generated an {product-title-short} init bundle for your cluster. +* You must have access to the Red{nbsp}Hat Container Registry and a pull secret for authentication. For information about downloading images from `registry.redhat.io`, see link:https://access.redhat.com/RegistryAuthentication[Red{nbsp}Hat Container Registry Authentication]. +ifndef::cloud-svc[] +* You must have the address and the port number that you are exposing the Central service on. +endif::cloud-svc[] +ifdef::cloud-svc[] +* You must have the *Central API Endpoint* address. You can view this information by choosing *Advanced Cluster Security* -> *ACS Instances* from the Red{nbsp}Hat Hybrid Cloud Console navigation menu, then clicking the {product-title-short} instance you created. +endif::[] + +.Procedure + +* Run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox \ + --create-namespace stackrox-secured-cluster-services rhacs/secured-cluster-services \ + -f <name_of_cluster_init_bundle.yaml> \ + -f <path_to_values_public.yaml> \// <1> + -f <path_to_values_private.yaml> \// <2> + --set imagePullSecrets.username=<username> \// <3> + --set imagePullSecrets.password=<password> <4> +---- +<1> Use the `-f` option to specify the paths for your public YAML configuration file. +<2> Use the `-f` option to specify the paths for your private YAML configuration file. +<3> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<4> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. + +[NOTE] +==== +To deploy `secured-cluster-services` Helm chart by using a continuous integration (CI) system, pass the init bundle YAML file as an environment variable to the `helm install` command: + +[source,terminal] +---- +$ helm install ... -f <(echo "$INIT_BUNDLE_YAML_SECRET") <1> +---- +<1> If you are using base64 encoded variables, use the `helm install ... -f <(echo "$INIT_BUNDLE_YAML_SECRET" | base64 --decode)` command instead. +==== diff --git a/modules/install-sensor-roxctl.adoc b/modules/install-sensor-roxctl.adoc new file mode 100644 index 000000000000..930f1b9fc677 --- /dev/null +++ b/modules/install-sensor-roxctl.adoc @@ -0,0 +1,129 @@ +// Module included in the following assemblies: +// +// * installing/install-quick-roxctl.adoc +// * installing/installing_ocp/install-secured-cluster-ocp.adoc +// * installing/installing_other/install-secured-cluster-other.adoc +// * cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc +// * cloud_service/installing_cloud_other/install-secured-cluster-cloud-other.adoc + +:_mod-docs-content-type: PROCEDURE +[id="install-sensor-roxctl_{context}"] += Installing Sensor + +ifeval::["{context}" == "install-secured-cluster-cloud-other"] +:cloud-svc: +endif::[] + +ifeval::["{context}" == "install-secured-cluster-cloud-other"] +:kube: +endif::[] + +To monitor a cluster, you must deploy Sensor. You must deploy Sensor into each cluster that you want to monitor. This installation method is also called the manifest installation method. + +To perform an installation by using the manifest installation method, follow _only one_ of the following procedures: + +* Use the {product-title-short} web portal to download the cluster bundle, and then extract and run the sensor script. +* Use the `roxctl` CLI to generate the required sensor configuration for your {ocp} cluster and associate it with your Central instance. + +.Prerequisites +* You must have already installed Central services, or you can access Central services by selecting your *ACS instance* on {rh-rhacscs-first}. + +[id="installing-manifest-web-portal_{context}"] +== Manifest installation method by using the web portal + +.Procedure + +. On your secured cluster, in the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. +. Select *Secure a cluster* -> *Legacy installation method*. +. Specify a name for the cluster. +. Provide appropriate values for the fields based on where you are deploying the Sensor. +ifndef::cloud-svc[] +** If you are deploying Sensor in the same cluster, accept the default values for all the fields. +** If you are deploying into a different cluster, replace `central.stackrox.svc:443` with a load balancer, node port, or other address, including the port number, that is accessible from the other cluster. +** If you are using a non-gRPC capable load balancer, such as HAProxy, AWS Application Load Balancer (ALB), or AWS Elastic Load Balancing (ELB), use the WebSocket Secure (`wss`) protocol. To use `wss`: +*** Prefix the address with *`wss://`*. +*** Add the port number after the address, for example, `wss://stackrox-central.example.com:443`. +endif::cloud-svc[] +ifdef::cloud-svc[] +** Enter the *Central API Endpoint* address. You can view this information by choosing *Advanced Cluster Security* -> *ACS Instances* from the Red{nbsp}Hat Hybrid Cloud Console navigation menu, then clicking the {product-title-short} instance you created. +endif::cloud-svc[] +. Click *Next* to continue with the Sensor setup. +. Click *Download YAML File and Keys* to download the cluster bundle (zip archive). ++ +[IMPORTANT] +==== +The cluster bundle zip archive includes unique configurations and keys for each cluster. +Do not reuse the same files in another cluster. +==== +. From a system that has access to the monitored cluster, extract and run the `sensor` script from the cluster bundle: ++ +[source,terminal] +---- +$ unzip -d sensor sensor-<cluster_name>.zip +---- ++ +[source,terminal] +---- +$ ./sensor/sensor.sh +---- +If you get a warning that you do not have the required permissions to deploy Sensor, follow the on-screen instructions, or contact your cluster administrator for help. + +After Sensor is deployed, it contacts Central and provides cluster information. + +[id="manifest-roxctl_{context}"] +== Manifest installation by using the roxctl CLI + +.Procedure + +. Generate the required sensor configuration for your {ocp} cluster and associate it with your Central instance by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl sensor generate openshift --openshift-version _<ocp_version>_ --name _<cluster_name>_ --central "$ROX_ENDPOINT" <1> +---- ++ +<1> For the `--openshift-version` option, specify the major {ocp} version number for your cluster. For example, specify `3` for {ocp} version `3.x` and specify `4` for {ocp} version `4.x`. +. From a system that has access to the monitored cluster, extract and run the `sensor` script from the cluster bundle: ++ +[source,terminal] +---- +$ unzip -d sensor sensor-<cluster_name>.zip +---- ++ +[source,terminal] +---- +$ ./sensor/sensor.sh +---- +If you get a warning that you do not have the required permissions to deploy Sensor, follow the on-screen instructions, or contact your cluster administrator for help. + +After Sensor is deployed, it contacts Central and provides cluster information. + +.Verification +. Return to the {product-title-short} portal and check if the deployment is successful. +If successful, when viewing your list of clusters in *Platform Configuration* -> *Clusters*, the cluster status displays a green checkmark and a *Healthy* status. +If you do not see a green checkmark, use the following command to check for problems: +ifndef::kube[] +* On {ocp}, enter the following command: ++ +[source,terminal] +---- +$ oc get pod -n stackrox -w +---- +endif::[] +* On Kubernetes, enter the following command: ++ +[source,terminal] +---- +$ kubectl get pod -n stackrox -w +---- +. Click *Finish* to close the window. + +After installation, Sensor starts reporting security information to {product-title-short} and the {product-title-short} portal dashboard begins showing deployments, images, and policy violations from the cluster on which you have installed the Sensor. + +ifeval::["{context}" == "install-secured-cluster-cloud-other"] +:!cloud-svc: +endif::[] + +ifeval::["{context}" == "install-secured-cluster-cloud-other"] +:!kube: +endif::[] \ No newline at end of file diff --git a/modules/installation-about-custom-azure-vnet.adoc b/modules/installation-about-custom-azure-vnet.adoc deleted file mode 100644 index c0567afe2766..000000000000 --- a/modules/installation-about-custom-azure-vnet.adoc +++ /dev/null @@ -1,110 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc - -[id="installation-about-custom-azure-vnet_{context}"] -= About reusing a VNet for your {product-title} cluster - -In {product-title} {product-version}, you can deploy a cluster into an existing Azure Virtual Network (VNet) in Microsoft Azure. If you do, you must also use existing subnets within the VNet and routing rules. - -By deploying {product-title} into an existing Azure VNet, you might be able to avoid service limit constraints in new accounts or more easily abide by the operational constraints that your company's guidelines set. This is a good option to use if you cannot obtain the infrastructure creation permissions that are required to create the VNet. - -[IMPORTANT] -==== -The use of an existing VNet requires the use of the updated Azure Private DNS (preview) feature. See link:https://azure.microsoft.com/en-us/updates/announcing-preview-refresh-for-azure-dns-private-zones-2/[Announcing Preview Refresh for Azure DNS Private Zones] for more information about the limitations of this feature. -==== - -[id="installation-about-custom-azure-vnet-requirements_{context}"] -== Requirements for using your VNet - -When you deploy a cluster by using an existing VNet, you must perform additional network configuration before you install the cluster. In installer-provisioned infrastructure clusters, the installer usually creates the following components, but it does not create them when you install into an existing VNet: - -* Subnets -* Route tables -* VNets -* Network Security Groups - -If you use a custom VNet, you must correctly configure it and its subnets for the installation program and the cluster to use. The installation program cannot subdivide network ranges for the cluster to use, set route tables for the subnets, or set VNet options like DHCP, so you must do so before you install the cluster. - -The cluster must be able to access the resource group that contains the existing VNet and subnets. While all of the resources that the cluster creates are placed in a separate resource group that it creates, some network resources are used from a separate group. Some cluster Operators must be able to access resources in both resource groups. For example, the Machine API controller attaches NICS for the virtual machines that it creates to subnets from the networking resource group. - -Your VNet must meet the following characteristics: - -* The VNet’s CIDR block must contain the `Networking.MachineCIDR` range, which is the IP address pool for cluster machines. -* The VNet and its subnets must belong to the same resource group, and the subnets must be configured to use Azure-assigned DHCP IP addresses instead of static IP addresses. - -You must provide two subnets within your VNet, one for the control plane machines and one for the compute machines. Because Azure distributes machines in different availability zones within the region that you specify, your cluster will have high availability by default. - -To ensure that the subnets that you provide are suitable, the installation program confirms the following data: - -* All the subnets that you specify exist. -* You provide two private subnets for each availability zone. -* The subnet CIDRs belong to the machine CIDR that you specified. Machines are not provisioned in availability zones that you do not provide private subnets for. If required, the installation program creates public load balancers that manage the control plane and worker nodes, and Azure allocates a public IP address to them. - -If you destroy a cluster that uses an existing VNet, the VNet is not deleted. - -[id="installation-about-custom-azure-vnet-nsg-requirements_{context}"] -=== Network security group requirements - -The network security groups for the subnets that host the compute and control plane machines require specific access to ensure that the cluster communication is correct. You must create rules to allow access to the required cluster communication ports. - -[IMPORTANT] -==== -The network security group rules must be in place before you install the cluster. If you attempt to install a cluster without the required access, the installation program cannot reach the Azure APIs, and installation fails. -==== - -.Required ports -[options="header",cols="1,3,1,1"] -|=== - -|Port -|Description -|Control plane -|Compute - -|`80` -|Allows HTTP traffic -|x -| - -|`443` -|Allows HTTPS traffic -|x -| - -|`6443` -|Allows communication to the control plane machines -|x -|x - -|`22623` -|Allows communication to the machine config server -|x -|x - -|=== - - -[id="installation-about-custom-azure-permissions_{context}"] -== Division of permissions - -Starting with {product-title} 4.3, you do not need all of the permissions that are required for an installation program-provisioned infrastructure cluster to deploy a cluster. This change mimics the division of permissions that you might have at your company: some individuals can create different resources in your clouds than others. For example, you might be able to create application-specific items, like instances, storage, and load balancers, but not networking-related components such as VNets, subnet, or ingress rules. - -The Azure credentials that you use when you create your cluster do not need the networking permissions that are required to make VNets and core networking components within the VNet, such as subnets, routing tables, internet gateways, NAT, and VPN. You still need permission to make the application resources that the machines within the cluster require, such as load balancers, security groups, storage accounts, and nodes. - -[id="installation-about-custom-azure-vnet-isolation_{context}"] -== Isolation between clusters - -Because the cluster is unable to modify network security groups in an existing subnet, there is no way to isolate clusters from each other on the VNet. -//// -These are some of the details from the AWS version, and if any of them are relevant to Azure, they can be included. -If you deploy {product-title} to an existing network, the isolation of cluster services is reduced in the following ways: - -* You can install multiple {product-title} clusters in the same VNet. -* ICMP ingress is allowed to entire network. -* TCP 22 ingress (SSH) is allowed to the entire network. -* Control plane TCP 6443 ingress (Kubernetes API) is allowed to the entire network. -* Control plane TCP 22623 ingress (MCS) is allowed to the entire network. -//// diff --git a/modules/installation-about-custom-gcp-vpc.adoc b/modules/installation-about-custom-gcp-vpc.adoc deleted file mode 100644 index a668a1e2ba65..000000000000 --- a/modules/installation-about-custom-gcp-vpc.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/ - -[id="installation-about-custom-gcp-vpc_{context}"] -= About using a custom VPC - -In {product-title} {product-version}, you can deploy a cluster into an existing VPC in Google Cloud Platform (GCP). If you do, you must also use existing subnets within the VPC and routing rules. - -By deploying {product-title} into an existing GCP VPC, you might be able to avoid limit constraints in new accounts or more easily abide by the operational constraints that your company's guidelines set. This is a good option to use if you cannot obtain the infrastructure creation permissions that are required to create the VPC yourself. - -[id="installation-about-custom-gcp-vpcs-requirements_{context}"] -== Requirements for using your VPC - -The installation program will no longer create the following components: - -* VPC -* Subnets -* Cloud router -* Cloud NAT -* NAT IP addresses - -If you use a custom VPC, you must correctly configure it and its subnets for the installation program and the cluster to use. The installation program cannot subdivide network ranges for the cluster to use, set route tables for the subnets, or set VPC options like DHCP, so you must do so before you install the cluster. - -Your VPC and subnets must meet the following characteristics: - -* The VPC must be in the same GCP project that you deploy the {product-title} cluster to. -* To allow access to the Internet from the control plane and compute machines, you must configure cloud NAT on the subnets to allow egress to it. These machines do not have a public address. Even if you do not require access to the Internet, you must allow egress to the VPC network to obtain the installation program and images. Because multiple cloud NATs cannot be configured on the shared subnets, the installation program cannot configure it. - -To ensure that the subnets that you provide are suitable, the installation program confirms the following data: - -* All the subnets that you specify exist and belong to the VPC that you specified. -* The subnet CIDRs belong to the machine CIDR. -* You must provide a subnet to deploy the cluster control plane and compute machines to. You can use the same subnet for both machine types. - -If you destroy a cluster that uses an existing VPC, the VPC is not deleted. - -[id="installation-about-custom-gcp-permissions_{context}"] -== Division of permissions - -Starting with {product-title} 4.3, you do not need all of the permissions that are required for an installation program-provisioned infrastructure cluster to deploy a cluster. This change mimics the division of permissions that you might have at your company: some individuals can create different resources in your clouds than others. For example, you might be able to create application-specific items, like instances, buckets, and load balancers, but not networking-related components such as VPCs, subnets, or Ingress rules. - -The GCP credentials that you use when you create your cluster do not need the networking permissions that are required to make VPCs and core networking components within the VPC, such as subnets, routing tables, internet gateways, NAT, and VPN. You still need permission to make the application resources that the machines within the cluster require, such as load balancers, security groups, storage, and nodes. - -[id="installation-about-custom-gcp-vpcs-isolation_{context}"] -== Isolation between clusters - -If you deploy {product-title} to an existing network, the isolation of cluster services is preserved by firewall rules that reference the machines in your cluster by the cluster's infrastructure ID. Only traffic within the cluster is allowed. - -If you deploy multiple clusters to the same VPC, the following components might share access between clusters: - -* The API, which is globally available with an external publishing strategy or available throughout the network in an internal publishing strategy -* Debugging tools, such as ports on VM instances that are open to the machine CIDR for SSH and ICMP access diff --git a/modules/installation-about-mirror-registry.adoc b/modules/installation-about-mirror-registry.adoc deleted file mode 100644 index 0ad4fc482440..000000000000 --- a/modules/installation-about-mirror-registry.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-restricted-networks-preparations.adoc - -[id="installation-about-mirror-registry_{context}"] -= About the mirror registry - -You can mirror the images that are required for {product-title} installation and subsequent product updates to a mirror registry. These actions use the same process. The release image, which contains the description of the content, and the images it references are all mirrored. In addition, the Operator catalog source image and the images that it references must be mirrored for each Operator that you use. After you mirror the content, you configure each cluster to retrieve this content from your mirror registry. - -The mirror registry can be any container registry that supports the most recent container image API, which is referred to as `schema2`. All major cloud provider registries, as well as Red Hat Quay, Artifactory, and the open source link:https://github.com/docker/distribution[Docker distribution registry] have the necessary support. Using one of these registries ensures that {product-title} can verify the integrity of each image in disconnected environments. - -The mirror registry must be reachable by every machine in the clusters that you provision. If the registry is unreachable installation, updating, or normal operations such as workload relocation might fail. For that reason, you must run mirror registries in a highly available way, and the mirror registries must at least match the production availability of your {product-title} clusters. - -When you populate a mirror registry with {product-title} images, you can follow two scenarios. If you have a host that can access both the internet and your mirror registry, but not your cluster nodes, you can directly mirror the content from that machine. This process is referred to as _connected mirroring_. If you have no such host, you must mirror the images to a file system and then bring that host or removable media into your restricted environment. This process is referred to as _disconnected mirroring_. diff --git a/modules/installation-about-restricted-network.adoc b/modules/installation-about-restricted-network.adoc deleted file mode 100644 index e7cfa6dc681b..000000000000 --- a/modules/installation-about-restricted-network.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_openstack/installing-openstack-installer-restricted.adoc -// * installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc -// * installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc -// * installing/installing-rhv-restricted-network.adoc - -ifeval::["{context}" == "installing-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:ipi: -endif::[] -ifeval::["{context}" == "installing-rhv-restricted-network"] -:ipi: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:ipi: -endif::[] - -[id="installation-about-restricted-networks_{context}"] -= About installations in restricted networks - -In {product-title} {product-version}, you can perform an installation that does not -require an active connection to the Internet to obtain software components. Restricted network installations can be completed using installer-provisioned infrastructure or user-provisioned infrastructure, depending on the cloud platform to which you are installing the cluster. - -ifndef::ibm-power[] -If you choose to perform a restricted network installation on a cloud platform, you -still require access to its cloud APIs. Some cloud functions, like -Amazon Web Service's IAM service, require Internet access, so you might still -require Internet access. -//behind a proxy -Depending on your network, you might require less Internet -access for an installation on bare metal hardware or on VMware vSphere. -endif::ibm-power[] - -To complete a restricted network installation, you must create a registry that -mirrors the contents of the {product-title} registry and contains the -installation media. You can create this registry on a mirror host, which can -access both the Internet and your closed network, or by using other methods -that meet your restrictions. - -ifndef::ipi[] -[IMPORTANT] -==== -Because of the complexity of the configuration for user-provisioned installations, consider completing a standard user-provisioned infrastructure installation before you attempt a restricted network installation using user-provisioned infrastructure. Completing this test installation might make it easier to isolate and troubleshoot any issues that might arise during your installation in a restricted network. -==== -endif::ipi[] - -[id="installation-restricted-network-limits_{context}"] -== Additional limits - -Clusters in restricted networks have the following additional limitations and restrictions: - -* The `ClusterVersion` status includes an `Unable to retrieve available updates` -error. -//* The authentication Operator might randomly fail. -* By default, you cannot use the contents of the Developer Catalog because - you cannot access the required image stream tags. -//* The `TelemeterClientDown` and `Watchdog` alerts from the monitoring Operator always display. - -ifeval::["{context}" == "installing-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:!ipi: -endif::[] -ifeval::["{context}" == "installing-rhv-restricted-network"] -:!ipi: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:!ipi: -endif::[] diff --git a/modules/installation-adding-registry-pull-secret.adoc b/modules/installation-adding-registry-pull-secret.adoc deleted file mode 100644 index 4ce9a5df6299..000000000000 --- a/modules/installation-adding-registry-pull-secret.adoc +++ /dev/null @@ -1,185 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc -// * openshift_images/samples-operator-alt-registry.adoc -// * updating/updating-restricted-network-cluster.adoc - -ifeval::["{context}" == "updating-restricted-network-cluster"] -:restricted: -endif::[] - -ifeval::["{context}" == "installing-restricted-networks-preparations"] -:restricted: -endif::[] - -[id="installation-adding-registry-pull-secret_{context}"] -= Configuring credentials that allow images to be mirrored - -Create a container image registry credentials file that allows mirroring -images from Red Hat to your mirror. - -ifdef::restricted[] -[WARNING] -==== -Do not use this image registry credentials file as the pull secret when you install a cluster. If you provide this file when you install cluster, all of the machines in the cluster will have write access to your mirror registry. -==== -endif::restricted[] - -ifdef::restricted[] -[WARNING] -==== -This process requires that you have write access to a container image registry on the mirror registry and adds the credentials to a registry pull secret. -==== - -endif::restricted[] - -.Prerequisites - -* You configured a mirror registry to use in your restricted network. -ifdef::restricted[] -* You identified an image repository location on your mirror registry to mirror images into. -* You provisioned a mirror registry account that allows images to be uploaded to that image repository. -endif::restricted[] - -.Procedure - -Complete the following steps on the installation host: - -ifndef::openshift-origin[] -. Download your `registry.redhat.io` pull secret from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site and save it to a `.json` file. -endif::[] - -. Generate the base64-encoded user name and password or token for your mirror -registry: -+ -[source,terminal] ----- -$ echo -n '<user_name>:<password>' | base64 -w0 <1> -BGVtbYk3ZHAtqXs= ----- -<1> For `<user_name>` and `<password>`, specify the user name and password that -you configured for your registry. - -ifndef::openshift-origin[] -. Make a copy of your pull secret in JSON format: -+ -[source,terminal] ----- -$ cat ./pull-secret.text | jq . > <path>/<pull-secret-file><1> ----- -<1> Specify the path to the folder to store the pull secret in and a name for -the JSON file that you create. -+ -The contents of the file resemble the following example: -+ -[source,json] ----- -{ - "auths": { - "cloud.openshift.com": { - "auth": "b3BlbnNo...", - "email": "you@example.com" - }, - "quay.io": { - "auth": "b3BlbnNo...", - "email": "you@example.com" - }, - "registry.connect.redhat.com": { - "auth": "NTE3Njg5Nj...", - "email": "you@example.com" - }, - "registry.redhat.io": { - "auth": "NTE3Njg5Nj...", - "email": "you@example.com" - } - } -} ----- -endif::[] - -ifndef::openshift-origin[] -. Edit the new -endif::[] -ifdef::openshift-origin[] -. Create a `.json` -endif::[] -file and add a section that describes your registry to it: -+ -[source,json] ----- -ifndef::openshift-origin[] - "auths": { - "<mirror_registry>": { <1> - "auth": "<credentials>", <2> - "email": "you@example.com" - }, -endif::[] -ifdef::openshift-origin[] -{ - "auths": { - "<mirror_registry>": { <1> - "auth": "<credentials>", <2> - "email": "you@example.com" - } - } -} -endif::[] ----- -<1> For `<mirror_registry>`, specify the registry domain name, and optionally the -port, that your mirror registry uses to serve content. For example, -`registry.example.com` or `registry.example.com:5000` -<2> For `<credentials>`, specify the base64-encoded user name and password for -the mirror registry. -+ -ifndef::openshift-origin[] -The file resembles the following example: -+ -[source,json] ----- -{ - "auths": { - "<mirror_registry>": { - "auth": "<credentials>", - "email": "you@example.com" - }, - "cloud.openshift.com": { - "auth": "b3BlbnNo...", - "email": "you@example.com" - }, - "quay.io": { - "auth": "b3BlbnNo...", - "email": "you@example.com" - }, - "registry.connect.redhat.com": { - "auth": "NTE3Njg5Nj...", - "email": "you@example.com" - }, - "registry.redhat.io": { - "auth": "NTE3Njg5Nj...", - "email": "you@example.com" - } - } -} ----- -endif::[] - -//// -This is not currently working as intended. -. Log in to your registry by using the following command: -+ -[source,terminal] ----- -$ oc registry login --to ./pull-secret.json --registry "<registry_host_and_port>" --auth-basic=<username>:<password> ----- -+ -Provide both the registry details and a valid user name and password for the registry. -//// - -ifeval::["{context}" == "installing-restricted-networks-preparations"] -:!restricted: -endif::[] - -ifeval::["{context}" == "updating-restricted-network-cluster"] -:!restricted: -endif::[] diff --git a/modules/installation-adding-vcenter-root-certificates.adoc b/modules/installation-adding-vcenter-root-certificates.adoc deleted file mode 100644 index 70bd8a25da91..000000000000 --- a/modules/installation-adding-vcenter-root-certificates.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc - -[id="installation-adding-vcenter-root-certificates_{context}"] -= Adding vCenter root CA certificates to your system trust - -Because the installation program requires access to your vCenter's API, you must add your vCenter's trusted root CA certificates to your system trust before you install an {product-title} cluster. - -.Procedure - -. From the vCenter home page, download the vCenter's root CA certificates. Click *Download trusted root CA certificates* in the vSphere Web Services SDK section. The `<vCenter>/certs/download.zip` file downloads. - -. Extract the compressed file that contains the vCenter root CA certificates. The contents of the compressed file resemble the following file structure: -+ ----- -certs -├── lin -│ ├── 108f4d17.0 -│ ├── 108f4d17.r1 -│ ├── 7e757f6a.0 -│ ├── 8e4f8471.0 -│ └── 8e4f8471.r0 -├── mac -│ ├── 108f4d17.0 -│ ├── 108f4d17.r1 -│ ├── 7e757f6a.0 -│ ├── 8e4f8471.0 -│ └── 8e4f8471.r0 -└── win - ├── 108f4d17.0.crt - ├── 108f4d17.r1.crl - ├── 7e757f6a.0.crt - ├── 8e4f8471.0.crt - └── 8e4f8471.r0.crl - -3 directories, 15 files ----- - -. Add the files for your operating system to the system trust. For example, on a Fedora operating system, run the following command: -+ -[source,terminal] ----- -# cp certs/lin/* /etc/pki/ca-trust/source/anchors ----- - -. Update your system trust. For example, on a Fedora operating system, run the following command: -+ -[source,terminal] ----- -# update-ca-trust extract ----- diff --git a/modules/installation-approve-csrs.adoc b/modules/installation-approve-csrs.adoc deleted file mode 100644 index 595fad47bdca..000000000000 --- a/modules/installation-approve-csrs.adoc +++ /dev/null @@ -1,201 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-gcp-restricted-networks.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * machine_management/user_provisioned/adding-rhel-compute.adoc -// * machine_management/user_provisioned/more-rhel-compute.adoc -// * machine_management/user_provisioned/adding-bare-metal-compute-user-infra.adoc -// * machine_management/user_provisioned/adding-vsphere-compute-user-infra.adoc -// * post_installation_configuration/node-tasks.adoc -// * installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc -// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc -// * installing/installing_ibm_z/installing-ibm-power.adoc -// * installing/installing_ibm_z/installing-restricted-networks-ibm-power.adoc - - -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:ibm-z-kvm: -endif::[] - -[id="installation-approve-csrs_{context}"] -= Approving the certificate signing requests for your machines - -When you add machines to a cluster, two pending certificate signing requests (CSRs) are generated for each machine that you added. You must confirm that these CSRs are approved or, if necessary, approve them yourself. The client requests must be approved first, followed by the server requests. - -.Prerequisites - -* You added machines to your cluster. - -.Procedure - -. Confirm that the cluster recognizes the machines: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -master-0 Ready master 63m v1.20.0 -master-1 Ready master 63m v1.20.0 -master-2 Ready master 64m v1.20.0 -worker-0 NotReady worker 76s v1.20.0 -worker-1 NotReady worker 70s v1.20.0 ----- -+ -The output lists all of the machines that you created. -+ -[NOTE] -==== -The preceding output might not include the compute nodes, also known as worker nodes, until some CSRs are approved. -==== - -. Review the pending CSRs and ensure that you see the client requests with the `Pending` or `Approved` status for each machine that you added to the cluster: -+ -ifndef::ibm-z,ibm-z-kvm[] -[source,terminal] ----- -$ oc get csr ----- -+ -.Example output -[source,terminal] ----- -NAME AGE REQUESTOR CONDITION -csr-8b2br 15m system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending -csr-8vnps 15m system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending -... ----- -+ -In this example, two machines are joining the cluster. You might see more approved CSRs in the list. -endif::ibm-z,ibm-z-kvm[] -ifdef::ibm-z,ibm-z-kvm[] -[source,terminal] ----- -$ oc get csr ----- -+ -[source,terminal] -.Example output ----- -NAME AGE REQUESTOR CONDITION -csr-mddf5 20m system:node:master-01.example.com Approved,Issued -csr-z5rln 16m system:node:worker-21.example.com Approved,Issued ----- -endif::ibm-z,ibm-z-kvm[] - -. If the CSRs were not approved, after all of the pending CSRs for the machines you added are in `Pending` status, approve the CSRs for your cluster machines: -+ -[NOTE] -==== -Because the CSRs rotate automatically, approve your CSRs within an hour of adding the machines to the cluster. If you do not approve them within an hour, the certificates will rotate, and more than two certificates will be present for each node. You must approve all of these certificates. After you approve the initial CSRs, the subsequent node client CSRs are automatically approved by the cluster `kube-controller-manager`. -==== -+ -[NOTE] -==== -For clusters running on platforms that are not machine API enabled, such as bare metal and other user-provisioned infrastructure, you must implement a method of automatically approving the kubelet serving certificate requests (CSRs). If a request is not approved, then the `oc exec`, `oc rsh`, and `oc logs` commands cannot succeed, because a serving certificate is required when the API server connects to the kubelet. Any operation that contacts the Kubelet endpoint requires this certificate approval to be in place. The method must watch for new CSRs, confirm that the CSR was submitted by the `node-bootstrapper` service account in the `system:node` or `system:admin` groups, and confirm the identity of the node. -==== - -** To approve them individually, run the following command for each valid CSR: -+ -[source,terminal] ----- -$ oc adm certificate approve <csr_name> <1> ----- -<1> `<csr_name>` is the name of a CSR from the list of current CSRs. - -** To approve all pending CSRs, run the following command: -+ -[source,terminal] ----- -$ oc get csr -o go-template='{{range .items}}{{if not .status}}{{.metadata.name}}{{"\n"}}{{end}}{{end}}' | xargs --no-run-if-empty oc adm certificate approve ----- -+ -[NOTE] -==== -Some Operators might not become available until some CSRs are approved. -==== - -. Now that your client requests are approved, you must review the server requests for each machine that you added to the cluster: -+ -[source,terminal] ----- -$ oc get csr ----- -+ -.Example output -[source,terminal] ----- -NAME AGE REQUESTOR CONDITION -csr-bfd72 5m26s system:node:ip-10-0-50-126.us-east-2.compute.internal Pending -csr-c57lv 5m26s system:node:ip-10-0-95-157.us-east-2.compute.internal Pending -... ----- - -. If the remaining CSRs are not approved, and are in the `Pending` status, approve the CSRs for your cluster machines: - -** To approve them individually, run the following command for each valid CSR: -+ -[source,terminal] ----- -$ oc adm certificate approve <csr_name> <1> ----- -<1> `<csr_name>` is the name of a CSR from the list of current CSRs. - -** To approve all pending CSRs, run the following command: -+ -[source,terminal] ----- -$ oc get csr -o go-template='{{range .items}}{{if not .status}}{{.metadata.name}}{{"\n"}}{{end}}{{end}}' | xargs oc adm certificate approve ----- - -. After all client and server CSRs have been approved, the machines have the `Ready` status. Verify this by running the following command: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -master-0 Ready master 73m v1.20.0 -master-1 Ready master 73m v1.20.0 -master-2 Ready master 74m v1.20.0 -worker-0 Ready worker 11m v1.20.0 -worker-1 Ready worker 11m v1.20.0 ----- -+ -[NOTE] -==== -It can take a few minutes after approval of the server CSRs for the machines to transition to the `Ready` status. -==== - -.Additional information -* For more information on CSRs, see link:https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/[Certificate Signing Requests]. - -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:!ibm-z-kvm: -endif::[] diff --git a/modules/installation-arm-bootstrap.adoc b/modules/installation-arm-bootstrap.adoc deleted file mode 100644 index 4c60b60b5ddb..000000000000 --- a/modules/installation-arm-bootstrap.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-arm-bootstrap_{context}"] -= ARM template for the bootstrap machine - -You can use the following Azure Resource Manager (ARM) template to deploy the -bootstrap machine that you need for your {product-title} cluster: - -.`04_bootstrap.json` ARM template -[%collapsible] -==== -[source,json] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/azure/04_bootstrap.json[] ----- -==== diff --git a/modules/installation-arm-control-plane.adoc b/modules/installation-arm-control-plane.adoc deleted file mode 100644 index 09346241a8f7..000000000000 --- a/modules/installation-arm-control-plane.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-arm-control-plane_{context}"] -= ARM template for control plane machines - -You can use the following Azure Resource Manager (ARM) template to deploy the -control plane machines that you need for your {product-title} cluster: - -.`05_masters.json` ARM template -[%collapsible] -==== -[source,json] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/azure/05_masters.json[] ----- -==== diff --git a/modules/installation-arm-dns.adoc b/modules/installation-arm-dns.adoc deleted file mode 100644 index 7f6b10cf6a0b..000000000000 --- a/modules/installation-arm-dns.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-arm-dns_{context}"] -= ARM template for the network and load balancers - -You can use the following Azure Resource Manager (ARM) template to deploy the -networking objects and load balancers that you need for your {product-title} -cluster: - -.`03_infra.json` ARM template -[%collapsible] -==== -[source,json] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/azure/03_infra.json[] ----- -==== diff --git a/modules/installation-arm-image-storage.adoc b/modules/installation-arm-image-storage.adoc deleted file mode 100644 index b4e2d829cf56..000000000000 --- a/modules/installation-arm-image-storage.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-arm-image-storage_{context}"] -= ARM template for image storage - -You can use the following Azure Resource Manager (ARM) template to deploy the -stored {op-system-first} image that you need for your {product-title} cluster: - -.`02_storage.json` ARM template -[%collapsible] -==== -[source,json] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/azure/02_storage.json[] ----- -==== diff --git a/modules/installation-arm-vnet.adoc b/modules/installation-arm-vnet.adoc deleted file mode 100644 index 1b6dc5343da9..000000000000 --- a/modules/installation-arm-vnet.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-arm-vnet_{context}"] -= ARM template for the VNet - -You can use the following Azure Resource Manager (ARM) template to deploy the -VNet that you need for your {product-title} cluster: - -.`01_vnet.json` ARM template -[%collapsible] -==== -[source,json] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/azure/01_vnet.json[] ----- -==== diff --git a/modules/installation-arm-worker.adoc b/modules/installation-arm-worker.adoc deleted file mode 100644 index 8a47882bc0ab..000000000000 --- a/modules/installation-arm-worker.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-arm-worker_{context}"] -= ARM template for worker machines - -You can use the following Azure Resource Manager (ARM) template to deploy the -worker machines that you need for your {product-title} cluster: - -.`06_workers.json` ARM template -[%collapsible] -==== -[source,json] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/azure/06_workers.json[] ----- -==== diff --git a/modules/installation-aws-about-government-region.adoc b/modules/installation-aws-about-government-region.adoc deleted file mode 100644 index fd1808202f66..000000000000 --- a/modules/installation-aws-about-government-region.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-government-region.adoc - -[id="installation-aws-about-government-region_{context}"] -= AWS government and secret regions - -{product-title} supports deploying a cluster to -link:https://aws.amazon.com/govcloud-us[AWS GovCloud (US)] regions and the link:https://aws.amazon.com/federal/us-intelligence-community/[AWS Commercial Cloud Services (C2S) Secret Region]. These regions are specifically designed for US government agencies at the federal, state, and -local level, as well as contractors, educational institutions, and other US -customers that must run sensitive workloads in the cloud. - -These regions do not have published {op-system-first} Amazon Machine Images (AMI) to select, so you -must upload a custom AMI that belongs to that region. - -The following AWS GovCloud partitions are supported: - -* `us-gov-west-1` -* `us-gov-east-1` - -The following AWS Secret Region partition is supported: - -* `us-iso-east-1` - -The AWS government or secret region, and accompanying custom AMI, must be manually configured in the -`install-config.yaml` file since {op-system} AMIs are not provided by Red Hat -for those regions. - -[IMPORTANT] -==== -If you are deploying to the C2S Secret Region, you must also define a custom CA certificate in the `additionalTrustBundle` field of the `install-config.yaml` file because the AWS API requires a custom CA trust bundle. To allow the installation program to access the AWS API, the CA certificates must also be defined on the machine that runs the installation program. You must add the CA bundle to the trust store on the machine, use the `AWS_CA_BUNDLE` environment variable, or define the CA bundle in the link:https://docs.aws.amazon.com/credref/latest/refdocs/setting-global-ca_bundle.html[`ca_bundle`] field of the AWS config file. -==== diff --git a/modules/installation-aws-config-yaml.adoc b/modules/installation-aws-config-yaml.adoc deleted file mode 100644 index a009c4e5eadc..000000000000 --- a/modules/installation-aws-config-yaml.adoc +++ /dev/null @@ -1,273 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc - -ifeval::["{context}" == "installing-aws-network-customizations"] -:with-networking: -endif::[] -ifeval::["{context}" != "installing-aws-network-customizations"] -:without-networking: -endif::[] -ifeval::["{context}" == "installing-aws-vpc"] -:vpc: -endif::[] -ifeval::["{context}" == "installing-aws-private"] -:vpc: -:private: -endif::[] -ifeval::["{context}" == "installing-aws-government-region"] -:vpc: -:private: -:gov: -endif::[] - - -[id="installation-aws-config-yaml_{context}"] -= Sample customized `install-config.yaml` file for AWS - -You can customize the `install-config.yaml` file to specify more details about -your {product-title} cluster's platform or modify the values of the required -parameters. - -[IMPORTANT] -==== -This sample YAML file is provided for reference only. You must obtain your -`install-config.yaml` file by using the installation program and modify it. -==== - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com <1> -credentialsMode: Mint <2> -controlPlane: <3> <4> - hyperthreading: Enabled <5> - name: master - platform: - aws: - zones: -ifdef::gov[] - - us-gov-west-1a - - us-gov-west-1b -endif::gov[] -ifndef::gov[] - - us-west-2a - - us-west-2b -endif::gov[] - rootVolume: - iops: 4000 - size: 500 - type: io1 <6> - type: m5.xlarge - replicas: 3 -compute: <3> -- hyperthreading: Enabled <5> - name: worker - platform: - aws: - rootVolume: - iops: 2000 - size: 500 - type: io1 <6> - type: c5.4xlarge - zones: -ifdef::gov[] - - us-gov-west-1c -endif::gov[] -ifndef::gov[] - - us-west-2c -endif::gov[] - replicas: 3 -metadata: - name: test-cluster <1> -ifdef::without-networking[] -networking: -endif::[] -ifdef::with-networking[] -networking: <3> -endif::[] - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineNetwork: - - cidr: 10.0.0.0/16 -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] - serviceNetwork: - - 172.30.0.0/16 -platform: - aws: -ifndef::gov[] - region: us-west-2 <1> -endif::gov[] -ifdef::gov[] - region: us-gov-west-1 -endif::gov[] - userTags: - adminContact: jdoe - costCenter: 7536 -ifdef::vpc[] - subnets: <7> - - subnet-1 - - subnet-2 - - subnet-3 - amiID: ami-96c6f8f7 <8> - serviceEndpoints: <9> - - name: ec2 - url: https://vpce-id.ec2.us-west-2.vpce.amazonaws.com -endif::vpc[] -ifndef::vpc[] - amiID: ami-96c6f8f7 <7> - serviceEndpoints: <8> - - name: ec2 - url: https://vpce-id.ec2.us-west-2.vpce.amazonaws.com -endif::vpc[] -pullSecret: '{"auths": ...}' <1> -ifdef::vpc[] -ifndef::openshift-origin[] -fips: false <10> -sshKey: ssh-ed25519 AAAA... <11> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <10> -endif::openshift-origin[] -endif::vpc[] -ifndef::vpc[] -ifndef::openshift-origin[] -fips: false <9> -sshKey: ssh-ed25519 AAAA... <10> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <9> -endif::openshift-origin[] -endif::vpc[] -ifdef::private[] -ifndef::openshift-origin[] -publish: Internal <12> -endif::openshift-origin[] -endif::private[] -ifdef::gov[] -ifndef::openshift-origin[] -additionalTrustBundle: | <13> - -----BEGIN CERTIFICATE----- - <MY_TRUSTED_CA_CERT> - -----END CERTIFICATE----- -endif::openshift-origin[] -endif::gov[] -ifdef::private[] -ifdef::openshift-origin[] -publish: Internal <11> -endif::openshift-origin[] -endif::private[] -ifdef::gov[] -ifdef::openshift-origin[] -additionalTrustBundle: | <12> - -----BEGIN CERTIFICATE----- - <MY_TRUSTED_CA_CERT> - -----END CERTIFICATE----- -endif::openshift-origin[] -endif::gov[] ----- -ifndef::gov[] -<1> Required. The installation program prompts you for this value. -endif::gov[] -ifdef::gov[] -<1> Required. -endif::gov[] -<2> Optional: Add this parameter to force the Cloud Credential Operator (CCO) to use the specified mode, instead of having the CCO dynamically try to determine the capabilities of the credentials. For details about CCO modes, see the _Cloud Credential Operator_ entry in the _Red Hat Operators reference_ content. -<3> If you do not provide these parameters and values, the installation program -provides the default value. -<4> The `controlPlane` section is a single mapping, but the compute section is a -sequence of mappings. To meet the requirements of the different data structures, -the first line of the `compute` section must begin with a hyphen, `-`, and the -first line of the `controlPlane` section must not. Although both sections -currently define a single machine pool, it is possible that future versions -of {product-title} will support defining multiple compute pools during -installation. Only one control plane pool is used. -<5> Whether to enable or disable simultaneous multithreading, or -`hyperthreading`. By default, simultaneous multithreading is enabled -to increase the performance of your machines' cores. You can disable it by -setting the parameter value to `Disabled`. If you disable simultaneous -multithreading in some cluster machines, you must disable it in all cluster -machines. -+ -[IMPORTANT] -==== -If you disable simultaneous multithreading, ensure that your capacity planning -accounts for the dramatically decreased machine performance. Use larger -instance types, such as `m4.2xlarge` or `m5.2xlarge`, for your machines if you -disable simultaneous multithreading. -==== -<6> To configure faster storage for etcd, especially for larger clusters, set the -storage type as `io1` and set `iops` to `2000`. -ifdef::vpc[] -<7> If you provide your own VPC, specify subnets for each availability zone that your cluster uses. -<8> The ID of the AMI used to boot machines for the cluster. If set, the AMI -must belong to the same region as the cluster. -<9> The AWS service endpoints. Custom endpoints are required when installing to -an unknown AWS region. The endpoint URL must use the `https` protocol and the -host must trust the certificate. -ifndef::openshift-origin[] -<10> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<11> You can optionally provide the `sshKey` value that you use to access the -machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<10> You can optionally provide the `sshKey` value that you use to access the -machines in your cluster. -endif::openshift-origin[] -endif::vpc[] -ifndef::vpc[] -<7> The ID of the AMI used to boot machines for the cluster. If set, the AMI -must belong to the same region as the cluster. -<8> The AWS service endpoints. Custom endpoints are required when installing to -an unknown AWS region. The endpoint URL must use the `https` protocol and the -host must trust the certificate. -ifndef::openshift-origin[] -<9> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<10> You can optionally provide the `sshKey` value that you use to access the -machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<9> You can optionally provide the `sshKey` value that you use to access the -machines in your cluster. -endif::openshift-origin[] -endif::vpc[] -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -ifdef::private[] -<12> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster, which cannot be accessed from the Internet. The default value is `External`. -endif::private[] -ifdef::gov[] -<13> The custom CA certificate. This is required when deploying to the AWS C2S Secret Region because the AWS API requires a custom CA trust bundle. -endif::gov[] - -ifeval::["{context}" == "installing-aws-network-customizations"] -:!with-networking: -endif::[] -ifeval::["{context}" != "installing-aws-network-customizations"] -:!without-networking: -endif::[] -ifeval::["{context}" == "installing-aws-vpc"] -:!vpc: -endif::[] -ifeval::["{context}" == "installing-aws-private"] -:!vpc: -:!private: -endif::[] -ifeval::["{context}" == "installing-aws-government-region"] -:!vpc: -:!private: -:!gov: -endif::[] diff --git a/modules/installation-aws-iam-user.adoc b/modules/installation-aws-iam-user.adoc deleted file mode 100644 index 4b076b558a88..000000000000 --- a/modules/installation-aws-iam-user.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-account.adoc - -[id="installation-aws-iam-user_{context}"] -= Creating an IAM user - -Each Amazon Web Services (AWS) account contains a root user account that is -based on the email address you used to create the account. This is a -highly-privileged account, and it is recommended to use it for only initial -account and billing configuration, creating an initial set of users, and -securing the account. - -Before you install {product-title}, create a secondary IAM -administrative user. As you complete the -link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[Creating an IAM User in Your AWS Account] -procedure in the AWS documentation, set the following options: - -.Procedure - -. Specify the IAM user name and select `Programmatic access`. - -. Attach the `AdministratorAccess` policy to ensure that the account has -sufficient permission to create the cluster. This policy provides the cluster -with the ability to grant credentials to each {product-title} component. The -cluster grants the components only the credentials that they require. -+ -[NOTE] -==== -While it is possible to create a policy that grants the all of the required -AWS permissions and attach it to the user, this is not the preferred option. -The cluster will not have the ability to grant additional credentials to -individual components, so the same credentials are used by all components. -==== - -. Optional: Add metadata to the user by attaching tags. - -. Confirm that the user name that you specified is granted the -`AdministratorAccess` policy. - -. Record the access key ID and secret access key values. You must use these -values when you configure your local machine to run the installation program. -+ -[IMPORTANT] -==== -You cannot use a temporary session token that you generated while using a -multi-factor authentication device to authenticate to AWS when you deploy a -cluster. The cluster continues to use your current AWS credentials to -create AWS resources for the entire life of the cluster, so you must -use key-based, long-lived credentials. -==== diff --git a/modules/installation-aws-limits.adoc b/modules/installation-aws-limits.adoc deleted file mode 100644 index 0a687a144ce9..000000000000 --- a/modules/installation-aws-limits.adoc +++ /dev/null @@ -1,112 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-account.adoc - -[id="installation-aws-limits_{context}"] -= AWS account limits - -The {product-title} cluster uses a number of Amazon Web Services (AWS) -components, and the default -link:https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html[Service Limits] -affect your ability to install {product-title} clusters. If you use certain -cluster configurations, deploy your cluster in certain AWS regions, or -run multiple clusters from your account, you might need -to request additional resources for your AWS account. - -The following table summarizes the AWS components whose limits can impact your -ability to install and run {product-title} clusters. - -[cols="2a,3a,3a,8a",options="header"] -|=== -|Component |Number of clusters available by default| Default AWS limit |Description - -|Instance Limits -|Varies -|Varies -|By default, each cluster creates the following instances: - -* One bootstrap machine, which is removed after installation -* Three master nodes -* Three worker nodes - -These instance type counts are within a new account's default limit. To deploy -more worker nodes, enable autoscaling, deploy large workloads, or use a -different instance type, review your account limits to ensure that your cluster -can deploy the machines that you need. - -In most regions, the bootstrap and worker machines uses an `m4.large` machines -and the master machines use `m4.xlarge` instances. In some regions, including -all regions that do not support these instance types, `m5.large` and `m5.xlarge` -instances are used instead. - -|Elastic IPs (EIPs) -|0 to 1 -|5 EIPs per account -|To provision the cluster in a highly available configuration, the installation program -creates a public and private subnet for each -link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html[availability zone within a region]. -Each private subnet requires a -link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html[NAT Gateway], -and each NAT gateway requires a separate -link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html[elastic IP]. -Review the -link:https://aws.amazon.com/about-aws/global-infrastructure/[AWS region map] to -determine how many availability zones are in each region. To take advantage of -the default high availability, install the cluster in a region with at least -three availability zones. To install a cluster in a region with more than five -availability zones, you must increase the EIP limit. -[IMPORTANT] -==== -To use the `us-east-1` region, you must increase the EIP limit for your account. -==== - -|Virtual Private Clouds (VPCs) -|5 -|5 VPCs per region -|Each cluster creates its own VPC. - -|Elastic Load Balancing (ELB/NLB) -|3 -|20 per region -|By default, each cluster creates internal and external network load balancers for the master -API server and a single classic elastic load balancer for the router. Deploying -more Kubernetes `Service` objects with type `LoadBalancer` will create additional -link:https://aws.amazon.com/elasticloadbalancing/[load balancers]. - - -|NAT Gateways -|5 -|5 per availability zone -|The cluster deploys one NAT gateway in each availability zone. - -|Elastic Network Interfaces (ENIs) -|At least 12 -|350 per region -|The default installation creates 21 ENIs and an ENI for each availability zone -in your region. For example, the `us-east-1` region contains six availability -zones, so a cluster that is deployed in that zone uses 27 ENIs. Review the -link:https://aws.amazon.com/about-aws/global-infrastructure/[AWS region map] to -determine how many availability zones are in each region. - -Additional ENIs are created for additional machines and elastic load balancers -that are created by cluster usage and deployed workloads. - -|VPC Gateway -|20 -|20 per account -|Each cluster creates a single VPC Gateway for S3 access. - - -|S3 buckets -|99 -|100 buckets per account -|Because the installation process creates a temporary bucket and the registry -component in each cluster creates a bucket, you can create only 99 -{product-title} clusters per AWS account. - -|Security Groups -|250 -|2,500 per account -|Each cluster creates 10 distinct security groups. - | Fail, optionally surfacing response body to the user -|=== diff --git a/modules/installation-aws-permissions.adoc b/modules/installation-aws-permissions.adoc deleted file mode 100644 index e96c6a7a2c64..000000000000 --- a/modules/installation-aws-permissions.adoc +++ /dev/null @@ -1,262 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-aws-account.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-aws-permissions_{context}"] -= Required AWS permissions - -When you attach the `AdministratorAccess` policy to the IAM user that you create in Amazon Web Services (AWS), -you grant that user all of the required permissions. To deploy all components of an {product-title} -cluster, the IAM user requires the following permissions: - -.Required EC2 permissions for installation -[%collapsible] -==== -* `ec2:AllocateAddress` -* `ec2:AssociateAddress` -* `ec2:AuthorizeSecurityGroupEgress` -* `ec2:AuthorizeSecurityGroupIngress` -* `ec2:CopyImage` -* `ec2:CreateNetworkInterface` -* `ec2:AttachNetworkInterface` -* `ec2:CreateSecurityGroup` -* `ec2:CreateTags` -* `ec2:CreateVolume` -* `ec2:DeleteSecurityGroup` -* `ec2:DeleteSnapshot` -* `ec2:DeleteTags` -* `ec2:DeregisterImage` -* `ec2:DescribeAccountAttributes` -* `ec2:DescribeAddresses` -* `ec2:DescribeAvailabilityZones` -* `ec2:DescribeDhcpOptions` -* `ec2:DescribeImages` -* `ec2:DescribeInstanceAttribute` -* `ec2:DescribeInstanceCreditSpecifications` -* `ec2:DescribeInstances` -* `ec2:DescribeInternetGateways` -* `ec2:DescribeKeyPairs` -* `ec2:DescribeNatGateways` -* `ec2:DescribeNetworkAcls` -* `ec2:DescribeNetworkInterfaces` -* `ec2:DescribePrefixLists` -* `ec2:DescribeRegions` -* `ec2:DescribeRouteTables` -* `ec2:DescribeSecurityGroups` -* `ec2:DescribeSubnets` -* `ec2:DescribeTags` -* `ec2:DescribeVolumes` -* `ec2:DescribeVpcAttribute` -* `ec2:DescribeVpcClassicLink` -* `ec2:DescribeVpcClassicLinkDnsSupport` -* `ec2:DescribeVpcEndpoints` -* `ec2:DescribeVpcs` -* `ec2:GetEbsDefaultKmsKeyId` -* `ec2:ModifyInstanceAttribute` -* `ec2:ModifyNetworkInterfaceAttribute` -* `ec2:ReleaseAddress` -* `ec2:RevokeSecurityGroupEgress` -* `ec2:RevokeSecurityGroupIngress` -* `ec2:RunInstances` -* `ec2:TerminateInstances` -==== - -.Required permissions for creating network resources during installation -[%collapsible] -==== -* `ec2:AssociateDhcpOptions` -* `ec2:AssociateRouteTable` -* `ec2:AttachInternetGateway` -* `ec2:CreateDhcpOptions` -* `ec2:CreateInternetGateway` -* `ec2:CreateNatGateway` -* `ec2:CreateRoute` -* `ec2:CreateRouteTable` -* `ec2:CreateSubnet` -* `ec2:CreateVpc` -* `ec2:CreateVpcEndpoint` -* `ec2:ModifySubnetAttribute` -* `ec2:ModifyVpcAttribute` - -[NOTE] -===== -If you use an existing VPC, your account does not require these permissions for creating network resources. -===== -==== - -.Required Elastic Load Balancing permissions for installation -[%collapsible] -==== -* `elasticloadbalancing:AddTags` -* `elasticloadbalancing:ApplySecurityGroupsToLoadBalancer` -* `elasticloadbalancing:AttachLoadBalancerToSubnets` -* `elasticloadbalancing:ConfigureHealthCheck` -* `elasticloadbalancing:CreateListener` -* `elasticloadbalancing:CreateLoadBalancer` -* `elasticloadbalancing:CreateLoadBalancerListeners` -* `elasticloadbalancing:CreateTargetGroup` -* `elasticloadbalancing:DeleteLoadBalancer` -* `elasticloadbalancing:DeregisterInstancesFromLoadBalancer` -* `elasticloadbalancing:DeregisterTargets` -* `elasticloadbalancing:DescribeInstanceHealth` -* `elasticloadbalancing:DescribeListeners` -* `elasticloadbalancing:DescribeLoadBalancerAttributes` -* `elasticloadbalancing:DescribeLoadBalancers` -* `elasticloadbalancing:DescribeTags` -* `elasticloadbalancing:DescribeTargetGroupAttributes` -* `elasticloadbalancing:DescribeTargetHealth` -* `elasticloadbalancing:ModifyLoadBalancerAttributes` -* `elasticloadbalancing:ModifyTargetGroup` -* `elasticloadbalancing:ModifyTargetGroupAttributes` -* `elasticloadbalancing:RegisterInstancesWithLoadBalancer` -* `elasticloadbalancing:RegisterTargets` -* `elasticloadbalancing:SetLoadBalancerPoliciesOfListener` -==== - -.Required IAM permissions for installation -[%collapsible] -==== -* `iam:AddRoleToInstanceProfile` -* `iam:CreateInstanceProfile` -* `iam:CreateRole` -* `iam:DeleteInstanceProfile` -* `iam:DeleteRole` -* `iam:DeleteRolePolicy` -* `iam:GetInstanceProfile` -* `iam:GetRole` -* `iam:GetRolePolicy` -* `iam:GetUser` -* `iam:ListInstanceProfilesForRole` -* `iam:ListRoles` -* `iam:ListUsers` -* `iam:PassRole` -* `iam:PutRolePolicy` -* `iam:RemoveRoleFromInstanceProfile` -* `iam:SimulatePrincipalPolicy` -* `iam:TagRole` -==== - -.Required Route 53 permissions for installation -[%collapsible] -==== -* `route53:ChangeResourceRecordSets` -* `route53:ChangeTagsForResource` -* `route53:CreateHostedZone` -* `route53:DeleteHostedZone` -* `route53:GetChange` -* `route53:GetHostedZone` -* `route53:ListHostedZones` -* `route53:ListHostedZonesByName` -* `route53:ListResourceRecordSets` -* `route53:ListTagsForResource` -* `route53:UpdateHostedZoneComment` -==== - -.Required S3 permissions for installation -[%collapsible] -==== -* `s3:CreateBucket` -* `s3:DeleteBucket` -* `s3:GetAccelerateConfiguration` -* `s3:GetBucketAcl` -* `s3:GetBucketCors` -* `s3:GetBucketLocation` -* `s3:GetBucketLogging` -* `s3:GetBucketObjectLockConfiguration` -* `s3:GetBucketReplication` -* `s3:GetBucketRequestPayment` -* `s3:GetBucketTagging` -* `s3:GetBucketVersioning` -* `s3:GetBucketWebsite` -* `s3:GetEncryptionConfiguration` -* `s3:GetLifecycleConfiguration` -* `s3:GetReplicationConfiguration` -* `s3:ListBucket` -* `s3:PutBucketAcl` -* `s3:PutBucketTagging` -* `s3:PutEncryptionConfiguration` -==== - -.S3 permissions that cluster Operators require -[%collapsible] -==== -* `s3:DeleteObject` -* `s3:GetObject` -* `s3:GetObjectAcl` -* `s3:GetObjectTagging` -* `s3:GetObjectVersion` -* `s3:PutObject` -* `s3:PutObjectAcl` -* `s3:PutObjectTagging` -==== - -.Required permissions to delete base cluster resources -[%collapsible] -==== -* `autoscaling:DescribeAutoScalingGroups` -* `ec2:DeleteNetworkInterface` -* `ec2:DeleteVolume` -* `elasticloadbalancing:DeleteTargetGroup` -* `elasticloadbalancing:DescribeTargetGroups` -* `iam:DeleteAccessKey` -* `iam:DeleteUser` -* `iam:ListAttachedRolePolicies` -* `iam:ListInstanceProfiles` -* `iam:ListRolePolicies` -* `iam:ListUserPolicies` -* `s3:DeleteObject` -* `s3:ListBucketVersions` -* `tag:GetResources` -==== - -.Required permissions to delete network resources -[%collapsible] -==== -* `ec2:DeleteDhcpOptions` -* `ec2:DeleteInternetGateway` -* `ec2:DeleteNatGateway` -* `ec2:DeleteRoute` -* `ec2:DeleteRouteTable` -* `ec2:DeleteSubnet` -* `ec2:DeleteVpc` -* `ec2:DeleteVpcEndpoints` -* `ec2:DetachInternetGateway` -* `ec2:DisassociateRouteTable` -* `ec2:ReplaceRouteTableAssociation` - -[NOTE] -===== -If you use an existing VPC, your account does not require these permissions to delete network resources. Instead, your account only requires the `tag:UntagResources` permission to delete network resources. -===== -==== - -.Additional IAM and S3 permissions that are required to create manifests -[%collapsible] -==== -* `iam:CreateAccessKey` -* `iam:CreateUser` -* `iam:DeleteAccessKey` -* `iam:DeleteUser` -* `iam:DeleteUserPolicy` -* `iam:GetUserPolicy` -* `iam:ListAccessKeys` -* `iam:PutUserPolicy` -* `iam:TagUser` -* `iam:GetUserPolicy` -* `iam:ListAccessKeys` -* `s3:PutBucketPublicAccessBlock` -* `s3:GetBucketPublicAccessBlock` -* `s3:PutLifecycleConfiguration` -* `s3:HeadBucket` -* `s3:ListBucketMultipartUploads` -* `s3:AbortMultipartUpload` -==== - -.Optional permissions for instance and quota checks for installation -[%collapsible] -==== -* `ec2:DescribeInstanceTypeOfferings` -* `servicequotas:ListAWSDefaultServiceQuotas` -==== diff --git a/modules/installation-aws-regions-with-no-ami.adoc b/modules/installation-aws-regions-with-no-ami.adoc deleted file mode 100644 index 84a2e6829fd0..000000000000 --- a/modules/installation-aws-regions-with-no-ami.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-user-infra.adoc - -[id="installation-aws-regions-with-no-ami_{context}"] -= AWS regions without a published {op-system} AMI - -You can deploy an {product-title} cluster to Amazon Web Services (AWS) regions -without native support for a {op-system-first} Amazon Machine Image (AMI) or the -AWS software development kit (SDK). If a -published AMI is not available for an AWS region, you can upload a custom AMI -prior to installing the cluster. This is required if you are deploying your -cluster to an AWS government or secret region. AWS government and secret regions are supported by the AWS SDK. - -If you are deploying to a region not supported by the AWS SDK -and you do not specify a custom AMI, the installation program -copies the `us-east-1` AMI to the user account automatically. Then the -installation program creates the control plane machines with encrypted EBS -volumes using the default or user-specified Key Management Service (KMS) key. -This allows the AMI to follow the same process workflow as published {op-system} -AMIs. - -A region without native support for an {op-system} AMI is not available to -select from the terminal during cluster creation because it is not published. -However, you can install to this region by configuring the custom AMI in the -`install-config.yaml` file. diff --git a/modules/installation-aws-regions.adoc b/modules/installation-aws-regions.adoc deleted file mode 100644 index 56037b11fecd..000000000000 --- a/modules/installation-aws-regions.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-account.adoc - -[id="installation-aws-regions_{context}"] -= Supported AWS regions - -You can deploy an {product-title} cluster to the following public regions: - -* `af-south-1` (Cape Town) -* `ap-east-1` (Hong Kong) -* `ap-northeast-1` (Tokyo) -* `ap-northeast-2` (Seoul) -* `ap-south-1` (Mumbai) -* `ap-southeast-1` (Singapore) -* `ap-southeast-2` (Sydney) -* `ca-central-1` (Central) -* `eu-central-1` (Frankfurt) -* `eu-north-1` (Stockholm) -* `eu-south-1` (Milan) -* `eu-west-1` (Ireland) -* `eu-west-2` (London) -* `eu-west-3` (Paris) -* `me-south-1` (Bahrain) -* `sa-east-1` (São Paulo) -* `us-east-1` (N. Virginia) -* `us-east-2` (Ohio) -* `us-west-1` (N. California) -* `us-west-2` (Oregon) - -The following AWS GovCloud regions are supported: - -* `us-gov-west-1` -* `us-gov-east-1` - -The AWS C2S Secret Region is supported: - -* `us-iso-east-1` diff --git a/modules/installation-aws-route53.adoc b/modules/installation-aws-route53.adoc deleted file mode 100644 index 5d0710ff180a..000000000000 --- a/modules/installation-aws-route53.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-account.adoc - -[id="installation-aws-route53_{context}"] -= Configuring Route 53 - -To install {product-title}, the Amazon Web Services (AWS) account you use must -have a dedicated public hosted zone in your Route 53 service. This zone must be -authoritative for the domain. The Route 53 service provides -cluster DNS resolution and name lookup for external connections to the cluster. - -.Procedure - -. Identify your domain, or subdomain, and registrar. You can transfer an existing domain and -registrar or obtain a new one through AWS or another source. -+ -[NOTE] -==== -If you purchase a new domain through AWS, it takes time for the relevant DNS -changes to propagate. For more information about purchasing domains -through AWS, see -link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html[Registering Domain Names Using Amazon Route 53] -in the AWS documentation. -==== - -. If you are using an existing domain and registrar, migrate its DNS to AWS. See -link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/MigratingDNS.html[Making Amazon Route 53 the DNS Service for an Existing Domain] -in the AWS documentation. - -. Create a public hosted zone for your domain or subdomain. See -link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html[Creating a Public Hosted Zone] -in the AWS documentation. -+ -Use an appropriate root domain, such as `openshiftcorp.com`, or subdomain, -such as `clusters.openshiftcorp.com`. - -. Extract the new authoritative name servers from the hosted zone records. See -link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/GetInfoAboutHostedZone.html[Getting the Name Servers for a Public Hosted Zone] -in the AWS documentation. - -. Update the registrar records for the AWS Route 53 name servers that your domain -uses. For example, if you registered your domain to a Route 53 service in a -different accounts, see the following topic in the AWS documentation: -link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-name-servers-glue-records.html#domain-name-servers-glue-records-procedure[Adding or Changing Name Servers or Glue Records]. - -. If you are using a subdomain, add its delegation records to the parent domain. This gives Amazon Route 53 responsibility for the subdomain. Follow the delegation procedure outlined by the DNS provider of the parent domain. See link:https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingNewSubdomain.html[Creating a subdomain that uses Amazon Route 53 as the DNS service without migrating the parent domain] in the AWS documentation for an example high level procedure. diff --git a/modules/installation-aws-upload-custom-rhcos-ami.adoc b/modules/installation-aws-upload-custom-rhcos-ami.adoc deleted file mode 100644 index 725a64737f16..000000000000 --- a/modules/installation-aws-upload-custom-rhcos-ami.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-government-region.adoc - -[id="installation-aws-upload-custom-rhcos-ami_{context}"] -= Uploading a custom {op-system} AMI in AWS - -If you are deploying to a custom Amazon Web Services (AWS) region, you must -upload a custom {op-system-first} Amazon Machine Image (AMI) that belongs to -that region. - -.Prerequisites - -* You configured an AWS account. -* You created an Amazon S3 bucket with the required IAM -link:https://docs.aws.amazon.com/vm-import/latest/userguide/vmie_prereqs.html#vmimport-role[service role]. -* You uploaded your {op-system} VMDK file to Amazon S3. -ifdef::openshift-enterprise,openshift-webscale[] -The {op-system} VMDK file must be the highest version that is less than or equal to the {product-title} version you are installing. -endif::[] -* You downloaded the AWS CLI and installed it on your computer. See -link:https://docs.aws.amazon.com/cli/latest/userguide/install-bundle.html[Install the AWS CLI Using the Bundled Installer]. - -.Procedure - -. Export your AWS profile as an environment variable: -+ -[source,terminal] ----- -$ export AWS_PROFILE=<aws_profile> <1> ----- -<1> The AWS profile name that holds your AWS credentials, like `govcloud`. - -. Export the region to associate with your custom AMI as an environment -variable: -+ -[source,terminal] ----- -$ export AWS_DEFAULT_REGION=<aws_region> <1> ----- -<1> The AWS region, like `us-gov-east-1`. - -. Export the version of {op-system} you uploaded to Amazon S3 as an environment -variable: -+ -[source,terminal] ----- -$ export RHCOS_VERSION=<version> <1> ----- -<1> The {op-system} VMDK version, like `4.7.0`. - -. Export the Amazon S3 bucket name as an environment variable: -+ -[source,terminal] ----- -$ export VMIMPORT_BUCKET_NAME=<s3_bucket_name> ----- - -. Create the `containers.json` file and define your {op-system} VMDK file: -+ -[source,terminal] ----- -$ cat <<EOF > containers.json -{ - "Description": "rhcos-${RHCOS_VERSION}-x86_64-aws.x86_64", - "Format": "vmdk", - "UserBucket": { - "S3Bucket": "${VMIMPORT_BUCKET_NAME}", - "S3Key": "rhcos-${RHCOS_VERSION}-x86_64-aws.x86_64.vmdk" - } -} -EOF ----- - -. Import the {op-system} disk as an Amazon EBS snapshot: -+ -[source,terminal] ----- -$ aws ec2 import-snapshot --region ${AWS_DEFAULT_REGION} \ - --description "<description>" \ <1> - --disk-container <file_path>/containers.json <2> ----- -<1> The description of your {op-system} disk being imported, like -`rhcos-${RHCOS_VERSION}-x86_64-aws.x86_64`. -<2> The file path to the JSON file describing your {op-system} disk. The JSON -file should contain your Amazon S3 bucket name and key. - -. Check the status of the image import: -+ -[source,terminal] ----- -$ watch -n 5 aws ec2 describe-import-snapshot-tasks --region ${AWS_DEFAULT_REGION} ----- -+ -.Example output -[source,terminal] ----- -{ - "ImportSnapshotTasks": [ - { - "Description": "rhcos-4.7.0-x86_64-aws.x86_64", - "ImportTaskId": "import-snap-fh6i8uil", - "SnapshotTaskDetail": { - "Description": "rhcos-4.7.0-x86_64-aws.x86_64", - "DiskImageSize": 819056640.0, - "Format": "VMDK", - "SnapshotId": "snap-06331325870076318", - "Status": "completed", - "UserBucket": { - "S3Bucket": "external-images", - "S3Key": "rhcos-4.7.0-x86_64-aws.x86_64.vmdk" - } - } - } - ] -} ----- -+ -Copy the `SnapshotId` to register the image. - -. Create a custom {op-system} AMI from the {op-system} snapshot: -+ -[source,terminal] ----- -$ aws ec2 register-image \ - --region ${AWS_DEFAULT_REGION} \ - --architecture x86_64 \ <1> - --description "rhcos-${RHCOS_VERSION}-x86_64-aws.x86_64" \ <2> - --ena-support \ - --name "rhcos-${RHCOS_VERSION}-x86_64-aws.x86_64" \ <3> - --virtualization-type hvm \ - --root-device-name '/dev/xvda' \ - --block-device-mappings 'DeviceName=/dev/xvda,Ebs={DeleteOnTermination=true,SnapshotId=<snapshot_ID>}' <4> ----- -<1> The {op-system} VMDK architecture type, like `x86_64`, `s390x`, or `ppc64le`. -<2> The `Description` from the imported snapshot. -<3> The name of the {op-system} AMI. -<4> The `SnapshotID` from the imported snapshot. - -To learn more about these APIs, see the AWS documentation for -link:https://docs.aws.amazon.com/vm-import/latest/userguide/vmimport-import-snapshot.html[importing snapshots] -and link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-an-ami-ebs.html#creating-launching-ami-from-snapshot[creating EBS-backed AMIs]. diff --git a/modules/installation-aws-user-infra-bootstrap.adoc b/modules/installation-aws-user-infra-bootstrap.adoc deleted file mode 100644 index e451c8c78286..000000000000 --- a/modules/installation-aws-user-infra-bootstrap.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-aws-user-infra-bootstrap_{context}"] -= Initializing the bootstrap sequence on AWS with user-provisioned infrastructure - -After you create all of the required infrastructure in Amazon Web Services (AWS), -you can start the bootstrap sequence that initializes the {product-title} control plane. - -.Prerequisites - -* You configured an AWS account. -* You added your AWS keys and region to your local AWS profile by running `aws configure`. -* You generated the Ignition config files for your cluster. -* You created and configured a VPC and associated subnets in AWS. -* You created and configured DNS, load balancers, and listeners in AWS. -* You created the security groups and roles required for your cluster in AWS. -* You created the bootstrap machine. -* You created the control plane machines. -* You created the worker nodes. - -.Procedure - -. Change to the directory that contains the installation program and start the bootstrap process that initializes the {product-title} control plane: -+ -[source,terminal] ----- -$ ./openshift-install wait-for bootstrap-complete --dir=<installation_directory> \ <1> - --log-level=info <2> ----- -<1> For `<installation_directory>`, specify the path to the directory that you -stored the installation files in. -<2> To view different installation details, specify `warn`, `debug`, or -`error` instead of `info`. -+ -.Example output -[source,terminal] ----- -INFO Waiting up to 20m0s for the Kubernetes API at https://api.mycluster.example.com:6443... -INFO API v1.19.0+9f84db3 up -INFO Waiting up to 30m0s for bootstrapping to complete... -INFO It is now safe to remove the bootstrap resources -INFO Time elapsed: 1s ----- -+ -If the command exits without a `FATAL` warning, your {product-title} control plane -has initialized. -+ -[NOTE] -==== -After the control plane initializes, it sets up the compute nodes and installs additional services in the form of Operators. -==== diff --git a/modules/installation-aws-user-infra-delete-bootstrap.adoc b/modules/installation-aws-user-infra-delete-bootstrap.adoc deleted file mode 100644 index 28c9b1f8a876..000000000000 --- a/modules/installation-aws-user-infra-delete-bootstrap.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-aws-user-infra-delete-bootstrap_{context}"] -= Deleting the bootstrap resources - -After you complete the initial Operator configuration for the cluster, remove the bootstrap resources from Amazon Web Services (AWS). - -.Prerequisites - -* You completed the initial Operator configuration for your cluster. - -.Procedure - -. Delete the bootstrap resources. If you used the CloudFormation template, -link:https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html[delete its stack]: -** Delete the stack by using the AWS CLI: -+ -[source,terminal] ----- -$ aws cloudformation delete-stack --stack-name <name> <1> ----- -<1> `<name>` is the name of your bootstrap stack. -** Delete the stack by using the link:https://console.aws.amazon.com/cloudformation/[AWS CloudFormation console]. diff --git a/modules/installation-aws-user-infra-installation.adoc b/modules/installation-aws-user-infra-installation.adoc deleted file mode 100644 index e39f9ad7132c..000000000000 --- a/modules/installation-aws-user-infra-installation.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -ifeval::["{context}" == "installing-restricted-networks-aws"] -:restricted: -endif::[] - -[id="installation-aws-user-infra-installation_{context}"] -= Completing an AWS installation on user-provisioned infrastructure - -After you start the {product-title} installation on Amazon Web Service (AWS) -user-provisioned infrastructure, monitor the deployment to completion. - -.Prerequisites - -* You removed the bootstrap node for an {product-title} cluster on user-provisioned AWS infrastructure. -* You installed the `oc` CLI. - -.Procedure - -ifdef::restricted[] -. From the directory that contains the installation program, complete -endif::restricted[] -ifndef::restricted[] -* From the directory that contains the installation program, complete -endif::restricted[] -the cluster installation: -+ -[source,terminal] ----- -$ ./openshift-install --dir=<installation_directory> wait-for install-complete <1> ----- -<1> For `<installation_directory>`, specify the path to the directory that you -stored the installation files in. -+ -.Example output -[source,terminal] ----- -INFO Waiting up to 40m0s for the cluster at https://api.mycluster.example.com:6443 to initialize... -INFO Waiting up to 10m0s for the openshift-console route to be created... -INFO Install complete! -INFO To access the cluster as the system:admin user when using 'oc', run 'export KUBECONFIG=/home/myuser/install_dir/auth/kubeconfig' -INFO Access the OpenShift web-console here: https://console-openshift-console.apps.mycluster.example.com -INFO Login to the console with user: "kubeadmin", and password: "4vYBz-Fe5en-ymBEc-Wt6NL" -INFO Time elapsed: 1s ----- -+ -[IMPORTANT] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== - -ifdef::restricted[] -. Register your cluster on the link:https://cloud.redhat.com/openshift/register[Cluster registration] page. -endif::restricted[] - - -ifeval::["{context}" == "installing-restricted-networks-aws"] -:!restricted: -endif::[] -ifdef::openshift-origin[] -:!restricted: -endif::[] diff --git a/modules/installation-aws-user-infra-requirements.adoc b/modules/installation-aws-user-infra-requirements.adoc deleted file mode 100644 index a0706b846327..000000000000 --- a/modules/installation-aws-user-infra-requirements.adoc +++ /dev/null @@ -1,591 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-aws-user-infra-requirements_{context}"] -= Required AWS infrastructure components - -To install {product-title} on user-provisioned infrastructure in Amazon Web Services (AWS), you must manually create both the machines and their supporting infrastructure. - -For more information about the integration testing for different platforms, see the link:https://access.redhat.com/articles/4128421[OpenShift Container Platform 4.x Tested Integrations] page. - -By using the provided CloudFormation templates, you can create stacks of AWS resources that represent the following components: - -* An AWS Virtual Private Cloud (VPC) -* Networking and load balancing components -* Security groups and roles -* An {product-title} bootstrap node -* {product-title} control plane nodes -* An {product-title} compute node - -Alternatively, you can manually create the components or you can reuse existing infrastructure that meets the cluster requirements. Review the CloudFormation templates for more details about how the components interrelate. - -[id="installation-aws-user-infra-cluster-machines_{context}"] -== Cluster machines - -You need `AWS::EC2::Instance` objects for the following machines: - -* A bootstrap machine. This machine is required during installation, but you can remove it after your cluster deploys. -* Three control plane machines. The control plane machines are not governed by a machine set. -* Compute machines. You must create at least two compute machines, which are also known as worker machines, during installation. These machines are not governed by a machine set. - -//// -You can also create and control them by using a MachineSet after your -control plane initializes and you can access the cluster API by using the `oc` -command line interface. -//// - -You can use the following instance types for the cluster machines with the provided CloudFormation templates. - - -[IMPORTANT] -==== -If `m4` instance types are not available in your region, such as with `eu-west-3`, use `m5` types instead. -==== - -.Instance types for machines -[cols="2a,2a,2a,2a",options="header"] -|=== - -|Instance type -|Bootstrap -|Control plane -|Compute - -|`i3.large` -|x -| -| - -| `m4.large` -| -| -|x - -| `m4.xlarge` -| -|x -|x - -| `m4.2xlarge` -| -|x -|x - -| `m4.4xlarge` -| -|x -|x - -| `m4.8xlarge` -| -|x -|x - -| `m4.10xlarge` -| -|x -|x - -| `m4.16xlarge` -| -|x -|x - -| `m5.large` -| -| -|x - -| `m5.xlarge` -| -|x -|x - -| `m5.2xlarge` -| -|x -|x - -| `m5.4xlarge` -| -|x -|x - -| `m5.8xlarge` -| -|x -|x - -| `m5.10xlarge` -| -|x -|x - -| `m5.16xlarge` -| -|x -|x - -| `c4.large` -| -| -|x - -| `c4.xlarge` -| -| -|x - -| `c4.2xlarge` -| -|x -|x - -| `c4.4xlarge` -| -|x -|x - -| `c4.8xlarge` -| -|x -|x - -| `r4.large` -| -| -|x - -| `r4.xlarge` -| -|x -|x - -| `r4.2xlarge` -| -|x -|x - -| `r4.4xlarge` -| -|x -|x - -| `r4.8xlarge` -| -|x -|x - -| `r4.16xlarge` -| -|x -|x - -|=== - -You might be able to use other instance types that meet the specifications of these instance types. - -[id="csr-management-aws_{context}"] -== Certificate signing requests management - -Because your cluster has limited access to automatic machine management when you -use infrastructure that you provision, you must provide a mechanism for approving -cluster certificate signing requests (CSRs) after installation. The -`kube-controller-manager` only approves the kubelet client CSRs. The -`machine-approver` cannot guarantee the validity of a serving certificate -that is requested by using kubelet credentials because it cannot confirm that -the correct machine issued the request. You must determine and implement a -method of verifying the validity of the kubelet serving certificate requests -and approving them. - -[id="installation-aws-user-infra-other-infrastructure_{context}"] -== Other infrastructure components - -* A VPC -* DNS entries -* Load balancers (classic or network) and listeners -* A public and a private Route 53 zone -* Security groups -* IAM roles -* S3 buckets - -If you are working in a disconnected environment, you are unable to reach the -public IP addresses for EC2 and ELB endpoints. To resolve this, you must create -a VPC endpoint and attach it to the subnet that the clusters are using. The -endpoints should be named as follows: - -* `ec2.<region>.amazonaws.com` -* `elasticloadbalancing.<region>.amazonaws.com` -* `s3.<region>.amazonaws.com` - -.Required VPC components - -You must provide a suitable VPC and subnets that allow communication to your -machines. - -[cols="2a,7a,3a,3a",options="header"] -|=== - -|Component -|AWS type -2+|Description - -|VPC -|* `AWS::EC2::VPC` -* `AWS::EC2::VPCEndpoint` -2+|You must provide a public VPC for the cluster to use. The VPC uses an -endpoint that references the route tables for each subnet to improve communication with the registry that is hosted in S3. - -|Public subnets -|* `AWS::EC2::Subnet` -* `AWS::EC2::SubnetNetworkAclAssociation` -2+|Your VPC must have public subnets for between 1 and 3 availability zones -and associate them with appropriate Ingress rules. - -|Internet gateway -| -* `AWS::EC2::InternetGateway` -* `AWS::EC2::VPCGatewayAttachment` -* `AWS::EC2::RouteTable` -* `AWS::EC2::Route` -* `AWS::EC2::SubnetRouteTableAssociation` -* `AWS::EC2::NatGateway` -* `AWS::EC2::EIP` -2+|You must have a public Internet gateway, with public routes, attached to the -VPC. In the provided templates, each public subnet has a NAT gateway with an EIP address. These NAT gateways allow cluster resources, like private subnet instances, to reach the Internet and are not required for some restricted network or proxy scenarios. - -.7+|Network access control -.7+| * `AWS::EC2::NetworkAcl` -* `AWS::EC2::NetworkAclEntry` -2+|You must allow the VPC to access the following ports: -h|Port -h|Reason - -|`80` -|Inbound HTTP traffic - -|`443` -|Inbound HTTPS traffic - -|`22` -|Inbound SSH traffic - -|`1024` - `65535` -|Inbound ephemeral traffic - -|`0` - `65535` -|Outbound ephemeral traffic - - -|Private subnets -|* `AWS::EC2::Subnet` -* `AWS::EC2::RouteTable` -* `AWS::EC2::SubnetRouteTableAssociation` -2+|Your VPC can have private subnets. The provided CloudFormation templates -can create private subnets for between 1 and 3 availability zones. -If you use private subnets, you must provide appropriate routes and tables -for them. - -|=== - - -.Required DNS and load balancing components - -Your DNS and load balancer configuration needs to use a public hosted zone and -can use a private hosted zone similar to the one that the installation program -uses if it provisions the cluster's infrastructure. You must -create a DNS entry that resolves to your load balancer. An entry for -`api.<cluster_name>.<domain>` must point to the external load balancer, and an -entry for `api-int.<cluster_name>.<domain>` must point to the internal load -balancer. - -The cluster also requires load balancers and listeners for port 6443, which are -required for the Kubernetes API and its extensions, and port 22623, which are -required for the Ignition config files for new machines. The targets will be the -master nodes. Port 6443 must be accessible to both clients external to the -cluster and nodes within the cluster. Port 22623 must be accessible to nodes -within the cluster. - - -[cols="2a,2a,8a",options="header"] -|=== - -|Component -|AWS type -|Description - -|DNS -|`AWS::Route53::HostedZone` -|The hosted zone for your internal DNS. - -|etcd record sets -|`AWS::Route53::RecordSet` -|The registration records for etcd for your control plane machines. - -|Public load balancer -|`AWS::ElasticLoadBalancingV2::LoadBalancer` -|The load balancer for your public subnets. - -|External API server record -|`AWS::Route53::RecordSetGroup` -|Alias records for the external API server. - -|External listener -|`AWS::ElasticLoadBalancingV2::Listener` -|A listener on port 6443 for the external load balancer. - -|External target group -|`AWS::ElasticLoadBalancingV2::TargetGroup` -|The target group for the external load balancer. - -|Private load balancer -|`AWS::ElasticLoadBalancingV2::LoadBalancer` -|The load balancer for your private subnets. - -|Internal API server record -|`AWS::Route53::RecordSetGroup` -|Alias records for the internal API server. - -|Internal listener -|`AWS::ElasticLoadBalancingV2::Listener` -|A listener on port 22623 for the internal load balancer. - -|Internal target group -|`AWS::ElasticLoadBalancingV2::TargetGroup` -|The target group for the internal load balancer. - -|Internal listener -|`AWS::ElasticLoadBalancingV2::Listener` -|A listener on port 6443 for the internal load balancer. - -|Internal target group -|`AWS::ElasticLoadBalancingV2::TargetGroup` -|The target group for the internal load balancer. - -|=== - -.Security groups - -The control plane and worker machines require access to the following ports: - -[cols="2a,2a,2a,2a",options="header"] -|=== - -|Group -|Type -|IP Protocol -|Port range - - -.4+|`MasterSecurityGroup` -.4+|`AWS::EC2::SecurityGroup` -|`icmp` -|`0` - -|`tcp` -|`22` - -|`tcp` -|`6443` - -|`tcp` -|`22623` - -.2+|`WorkerSecurityGroup` -.2+|`AWS::EC2::SecurityGroup` -|`icmp` -|`0` - -|`tcp` -|`22` - - -.2+|`BootstrapSecurityGroup` -.2+|`AWS::EC2::SecurityGroup` - -|`tcp` -|`22` - -|`tcp` -|`19531` - -|=== - -.Control plane Ingress - -The control plane machines require the following Ingress groups. Each Ingress group is -a `AWS::EC2::SecurityGroupIngress` resource. - -[cols="2a,5a,2a,2a",options="header"] -|=== - -|Ingress group -|Description -|IP protocol -|Port range - - -|`MasterIngressEtcd` -|etcd -|`tcp` -|`2379`- `2380` - -|`MasterIngressVxlan` -|Vxlan packets -|`udp` -|`4789` - -|`MasterIngressWorkerVxlan` -|Vxlan packets -|`udp` -|`4789` - -|`MasterIngressInternal` -|Internal cluster communication and Kubernetes proxy metrics -|`tcp` -|`9000` - `9999` - -|`MasterIngressWorkerInternal` -|Internal cluster communication -|`tcp` -|`9000` - `9999` - -|`MasterIngressKube` -|Kubernetes kubelet, scheduler and controller manager -|`tcp` -|`10250` - `10259` - -|`MasterIngressWorkerKube` -|Kubernetes kubelet, scheduler and controller manager -|`tcp` -|`10250` - `10259` - -|`MasterIngressIngressServices` -|Kubernetes Ingress services -|`tcp` -|`30000` - `32767` - -|`MasterIngressWorkerIngressServices` -|Kubernetes Ingress services -|`tcp` -|`30000` - `32767` - -|=== - - -.Worker Ingress - -The worker machines require the following Ingress groups. Each Ingress group is -a `AWS::EC2::SecurityGroupIngress` resource. - -[cols="2a,5a,2a,2a",options="header"] -|=== - -|Ingress group -|Description -|IP protocol -|Port range - - -|`WorkerIngressVxlan` -|Vxlan packets -|`udp` -|`4789` - -|`WorkerIngressWorkerVxlan` -|Vxlan packets -|`udp` -|`4789` - -|`WorkerIngressInternal` -|Internal cluster communication -|`tcp` -|`9000` - `9999` - -|`WorkerIngressWorkerInternal` -|Internal cluster communication -|`tcp` -|`9000` - `9999` - -|`WorkerIngressKube` -|Kubernetes kubelet, scheduler, and controller manager -|`tcp` -|`10250` - -|`WorkerIngressWorkerKube` -|Kubernetes kubelet, scheduler, and controller manager -|`tcp` -|`10250` - -|`WorkerIngressIngressServices` -|Kubernetes Ingress services -|`tcp` -|`30000` - `32767` - -|`WorkerIngressWorkerIngressServices` -|Kubernetes Ingress services -|`tcp` -|`30000` - `32767` - -|=== - - -.Roles and instance profiles - -You must grant the machines permissions in AWS. The provided CloudFormation -templates grant the machines `Allow` permissions for the following `AWS::IAM::Role` objects -and provide a `AWS::IAM::InstanceProfile` for each set of roles. If you do -not use the templates, you can grant the machines the following broad permissions -or the following individual permissions. - -[cols="2a,2a,2a,2a",options="header"] -|=== - -|Role -|Effect -|Action -|Resource - -.4+|Master -|`Allow` -|`ec2:*` -|`*` - -|`Allow` -|`elasticloadbalancing:*` -|`*` - -|`Allow` -|`iam:PassRole` -|`*` - -|`Allow` -|`s3:GetObject` -|`*` - -|Worker -|`Allow` -|`ec2:Describe*` -|`*` - - -.3+|Bootstrap -|`Allow` -|`ec2:Describe*` -|`*` - -|`Allow` -|`ec2:AttachVolume` -|`*` - -|`Allow` -|`ec2:DetachVolume` -|`*` - -|`Allow` -|`s3:GetObject` -|`*` - -|=== diff --git a/modules/installation-aws-user-infra-rhcos-ami.adoc b/modules/installation-aws-user-infra-rhcos-ami.adoc deleted file mode 100644 index 20d2a7a47d16..000000000000 --- a/modules/installation-aws-user-infra-rhcos-ami.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-aws-user-infra-rhcos-ami_{context}"] -= {op-system} AMIs for the AWS infrastructure - -Red Hat provides {op-system-first} AMIs valid for the various Amazon Web -Services (AWS) zones you can specify for your {product-title} nodes. - -[NOTE] -==== -You can also install to regions that do not have a {op-system} AMI published by -importing your own AMI. -==== - -.{op-system} AMIs - -[cols="2a,2a",options="header"] -|=== - -|AWS zone -|AWS AMI - -|`af-south-1` -|`ami-057e5df70c52dc128` - -|`ap-east-1` -|`ami-006ab68917f52bb13` - -|`ap-northeast-1` -|`ami-0d236f6289c700771` - -|`ap-northeast-2` -|`ami-040394572427a293a` - -|`ap-south-1` -|`ami-0838c978c0390dd75` - -|`ap-southeast-1` -|`ami-07af688c8b65de56f` - -|`ap-southeast-2` -|`ami-0a36faab6aa0a0dea` - -|`ca-central-1` -|`ami-01284e5815ce66a95` - -|`eu-central-1` -|`ami-0361c06cf3e935cfe` - -|`eu-north-1` -|`ami-0080eb90a48d9655e` - -|`eu-south-1` -|`ami-0a3bc89f7aadf0343` - -|`eu-west-1` -|`ami-0b4024fa5cb2588bd` - -|`eu-west-2` -|`ami-07376355104ab4106` - -|`eu-west-3` -|`ami-038f4ce9ea7ac7191` - -|`me-south-1` -|`ami-025899013a24bb708` - -|`sa-east-1` -|`ami-089e1a3dcc5a5fe08` - -|`us-east-1` -|`ami-0d5f9982f029fbc14` - -|`us-east-2` -|`ami-0c84b5c5255ec4777` - -|`us-west-1` -|`ami-0b421328859954025` - -|`us-west-2` -|`ami-010de485a2ee23e5e` - -|=== diff --git a/modules/installation-azure-about-government-region.adoc b/modules/installation-azure-about-government-region.adoc deleted file mode 100644 index 0ef5078be7f0..000000000000 --- a/modules/installation-azure-about-government-region.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-government-region.adoc - -[id="installation-azure-about-government-region_{context}"] -= Azure government regions - -{product-title} supports deploying a cluster to -link:https://docs.microsoft.com/en-us/azure/azure-government/documentation-government-welcome[Microsoft Azure Government (MAG)] -regions. MAG is specifically designed for US government agencies at the federal, -state, and local level, as well as contractors, educational institutions, and -other US customers that must run sensitive workloads on Azure. MAG is composed -of government-only data center regions, all granted an -link:https://docs.microsoft.com/en-us/microsoft-365/compliance/offering-dod-disa-l2-l4-l5?view=o365-worldwide#dod-impact-level-5-provisional-authorization[Impact Level 5 Provisional Authorization]. - -Installing to a MAG region requires manually configuring the Azure Government -dedicated cloud instance and region in the `install-config.yaml` file. You must -also update your service principal to reference the appropriate government -environment. - -[NOTE] -==== -The Azure government region cannot be selected using the guided terminal prompts -from the installation program. You must define the region manually in the -`install-config.yaml` file. Remember to also set the dedicated cloud instance, -like `AzureUSGovernmentCloud`, based on the region specified. -==== diff --git a/modules/installation-azure-config-yaml.adoc b/modules/installation-azure-config-yaml.adoc deleted file mode 100644 index 376f5706df15..000000000000 --- a/modules/installation-azure-config-yaml.adoc +++ /dev/null @@ -1,254 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-network-customizations.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc - -ifeval::["{context}" == "installing-azure-network-customizations"] -:with-networking: -endif::[] -ifeval::["{context}" != "installing-azure-network-customizations"] -:without-networking: -endif::[] -ifeval::["{context}" == "installing-azure-vnet"] -:vnet: -endif::[] -ifeval::["{context}" == "installing-azure-private"] -:private: -endif::[] -ifeval::["{context}" == "installing-azure-government-region"] -:gov: -endif::[] - -[id="installation-azure-config-yaml_{context}"] -= Sample customized `install-config.yaml` file for Azure - -You can customize the `install-config.yaml` file to specify more details about your {product-title} cluster's platform or modify the values of the required parameters. - -[IMPORTANT] -==== -This sample YAML file is provided for reference only. You must obtain your `install-config.yaml` file by using the installation program and modify it. -==== - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com <1> -controlPlane: <2> - hyperthreading: Enabled <3> <4> - name: master - platform: - azure: - osDisk: - diskSizeGB: 1024 <5> - type: Standard_D8s_v3 - replicas: 3 -compute: <2> -- hyperthreading: Enabled <3> - name: worker - platform: - azure: - type: Standard_D2s_v3 - osDisk: - diskSizeGB: 512 <5> - zones: <6> - - "1" - - "2" - - "3" - replicas: 5 -metadata: - name: test-cluster <1> -ifdef::without-networking[] -networking: -endif::[] -ifdef::with-networking[] -networking: <2> -endif::[] - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineNetwork: - - cidr: 10.0.0.0/16 -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] - serviceNetwork: - - 172.30.0.0/16 -platform: - azure: -ifndef::gov[] - region: centralus <1> -endif::gov[] -ifdef::gov[] - region: usgovvirginia -endif::gov[] - baseDomainResourceGroupName: resource_group <7> -ifdef::vnet,private,gov[] - networkResourceGroupName: vnet_resource_group <8> - virtualNetwork: vnet <9> - controlPlaneSubnet: control_plane_subnet <10> - computeSubnet: compute_subnet <11> -endif::vnet,private,gov[] -ifdef::private,gov[] - outboundType: UserDefinedRouting <12> -endif::private,gov[] -ifdef::gov[] - cloudName: AzureUSGovernmentCloud <13> -endif::gov[] -pullSecret: '{"auths": ...}' <1> -ifdef::vnet[] -ifndef::openshift-origin[] -fips: false <12> -endif::openshift-origin[] -ifndef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <13> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <12> -endif::openshift-origin[] -endif::vnet[] -ifdef::private[] -ifndef::openshift-origin[] -fips: false <13> -sshKey: ssh-ed25519 AAAA... <14> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <13> -endif::openshift-origin[] -endif::private[] -ifdef::gov[] -ifndef::openshift-origin[] -fips: false <14> -endif::openshift-origin[] -ifndef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <15> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <14> -endif::openshift-origin[] -endif::gov[] -ifndef::vnet,private,gov[] -ifndef::openshift-origin[] -fips: false <8> -sshKey: ssh-ed25519 AAAA... <9> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <8> -endif::openshift-origin[] -endif::vnet,private,gov[] -ifdef::private[] -ifndef::openshift-origin[] -publish: Internal <15> -endif::openshift-origin[] -ifdef::openshift-origin[] -publish: Internal <14> -endif::openshift-origin[] -endif::private[] -ifdef::gov[] -ifndef::openshift-origin[] -publish: Internal <16> -endif::openshift-origin[] -ifdef::openshift-origin[] -publish: Internal <15> -endif::openshift-origin[] -endif::gov[] ----- -ifndef::gov[] -<1> Required. The installation program prompts you for this value. -endif::gov[] -ifdef::gov[] -<1> Required. -endif::gov[] -<2> If you do not provide these parameters and values, the installation program provides the default value. -<3> The `controlPlane` section is a single mapping, but the compute section is a sequence of mappings. To meet the requirements of the different data structures, the first line of the `compute` section must begin with a hyphen, `-`, and the first line of the `controlPlane` section must not. Although both sections currently define a single machine pool, it is possible that future versions of {product-title} will support defining multiple compute pools during installation. Only one control plane pool is used. -<4> Whether to enable or disable simultaneous multithreading, or `hyperthreading`. By default, simultaneous multithreading is enabled to increase the performance of your machines' cores. You can disable it by setting the parameter value to `Disabled`. If you disable simultaneous multithreading in some cluster machines, you must disable it in all cluster machines. -+ -[IMPORTANT] -==== -If you disable simultaneous multithreading, ensure that your capacity planning accounts for the dramatically decreased machine performance. Use larger virtual machine types, such as `Standard_D8s_v3`, for your machines if you disable simultaneous multithreading. -==== -<5> You can specify the size of the disk to use in GB. Minimum recommendation for master nodes is 1024 GB. -//To configure faster storage for etcd, especially for larger clusters, set the -//storage type as `io1` and set `iops` to `2000`. -<6> Specify a list of zones to deploy your machines to. For high availability, specify at least two zones. -<7> Specify the name of the resource group that contains the DNS zone for your base domain. -ifdef::vnet,private,gov[] -<8> If you use an existing VNet, specify the name of the resource group that contains it. -<9> If you use an existing VNet, specify its name. -<10> If you use an existing VNet, specify the name of the subnet to host the control plane machines. -<11> If you use an existing VNet, specify the name of the subnet to host the compute machines. -endif::vnet,private,gov[] -ifdef::private,gov[] -<12> You can customize your own outbound routing. Configuring user-defined routing prevents exposing external endpoints in your cluster. User-defined routing for egress requires deploying your cluster to an existing VNet. -endif::private,gov[] -ifdef::gov[] -<13> Specify the name of the Azure cloud environment to deploy your cluster to. Set `AzureUSGovernmentCloud` to deploy to a Microsoft Azure Government (MAG) region. The default value is `AzurePublicCloud`. -endif::gov[] -ifdef::vnet[] -ifndef::openshift-origin[] -<12> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<13> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<12> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -endif::vnet[] -ifdef::private[] -ifndef::openshift-origin[] -<13> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<14> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<13> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -endif::private[] -ifdef::gov[] -ifndef::openshift-origin[] -<14> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<15> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<14> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -endif::gov[] -ifndef::vnet,private,gov[] -ifndef::openshift-origin[] -<8> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<9> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<8> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -endif::vnet,private,gov[] -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -ifdef::private[] -<15> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster, which cannot be accessed from the Internet. The default value is `External`. -endif::private[] -ifdef::gov[] -<16> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster, which cannot be accessed from the Internet. The default value is `External`. -endif::gov[] - -ifeval::["{context}" == "installing-azure-network-customizations"] -:!with-networking: -endif::[] -ifeval::["{context}" != "installing-azure-network-customizations"] -:!without-networking: -endif::[] -ifeval::["{context}" == "installing-azure-vnet"] -:!vnet: -endif::[] -ifeval::["{context}" == "installing-azure-private"] -:!private: -endif::[] -ifeval::["{context}" == "installing-azure-government-region"] -:!gov: -endif::[] diff --git a/modules/installation-azure-create-dns-zones.adoc b/modules/installation-azure-create-dns-zones.adoc deleted file mode 100644 index 680598d86ac3..000000000000 --- a/modules/installation-azure-create-dns-zones.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-create-dns-zones_{context}"] -= Example for creating DNS zones - -DNS records are required for clusters that use user-provisioned infrastructure. -You should choose the DNS strategy that fits your scenario. - -For this example, link:https://docs.microsoft.com/en-us/azure/dns/dns-overview[Azure's DNS solution] -is used, so you will create a new public DNS zone for external (internet) -visibility and a private DNS zone for internal cluster resolution. - -[NOTE] -==== -The public DNS zone is not required to exist in the same resource group as the -cluster deployment and might already exist in your organization for the desired -base domain. If that is the case, you can skip creating the public DNS zone; be -sure the installation config you generated earlier reflects that scenario. -==== - -.Prerequisites - -* Configure an Azure account. - -* Generate the Ignition config files for your cluster. - -.Procedure - -. Create the new public DNS zone in the resource group exported in the -`BASE_DOMAIN_RESOURCE_GROUP` environment variable: -+ -[source,terminal] ----- -$ az network dns zone create -g ${BASE_DOMAIN_RESOURCE_GROUP} -n ${CLUSTER_NAME}.${BASE_DOMAIN} ----- -+ -You can skip this step if you are using a public DNS zone that already exists. - -. Create the private DNS zone in the same resource group as the rest of this -deployment: -+ -[source,terminal] ----- -$ az network private-dns zone create -g ${RESOURCE_GROUP} -n ${CLUSTER_NAME}.${BASE_DOMAIN} ----- diff --git a/modules/installation-azure-create-ingress-dns-records.adoc b/modules/installation-azure-create-ingress-dns-records.adoc deleted file mode 100644 index 0669f098d3b2..000000000000 --- a/modules/installation-azure-create-ingress-dns-records.adoc +++ /dev/null @@ -1,92 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-create-ingress-dns-records_{context}"] -= Adding the Ingress DNS records - -If you removed the DNS Zone configuration when creating Kubernetes manifests and -generating Ignition configs, you must manually create DNS records that point at -the Ingress load balancer. You can create either a wildcard -`*.apps.{baseDomain}.` or specific records. You can use A, CNAME, and other -records per your requirements. - -.Prerequisites - -* You deployed an {product-title} cluster on Microsoft Azure by using infrastructure that you provisioned. -* Install the OpenShift CLI (`oc`). -* Install the `jq` package. -* Install or update the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[Azure CLI]. - -.Procedure - -. Confirm the Ingress router has created a load balancer and populated the -`EXTERNAL-IP` field: -+ -[source,terminal] ----- -$ oc -n openshift-ingress get service router-default ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -router-default LoadBalancer 172.30.20.10 35.130.120.110 80:32288/TCP,443:31215/TCP 20 ----- - -. Export the Ingress router IP as a variable: -+ -[source,terminal] ----- -$ export PUBLIC_IP_ROUTER=`oc -n openshift-ingress get service router-default --no-headers | awk '{print $4}'` ----- - -. Add a `*.apps` record to the public DNS zone. - -.. If you are adding this cluster to a new public zone, run: -+ -[source,terminal] ----- -$ az network dns record-set a add-record -g ${BASE_DOMAIN_RESOURCE_GROUP} -z ${CLUSTER_NAME}.${BASE_DOMAIN} -n *.apps -a ${PUBLIC_IP_ROUTER} --ttl 300 ----- - -.. If you are adding this cluster to an already existing public zone, run: -+ -[source,terminal] ----- -$ az network dns record-set a add-record -g ${BASE_DOMAIN_RESOURCE_GROUP} -z ${BASE_DOMAIN} -n *.apps.${CLUSTER_NAME} -a ${PUBLIC_IP_ROUTER} --ttl 300 ----- - -. Add a `*.apps` record to the private DNS zone: -.. Create a `*.apps` record by using the following command: -+ -[source,terminal] ----- -$ az network private-dns record-set a create -g ${RESOURCE_GROUP} -z ${CLUSTER_NAME}.${BASE_DOMAIN} -n *.apps --ttl 300 ----- -.. Add the `*.apps` record to the private DNS zone by using the following command: -+ -[source,terminal] ----- -$ az network private-dns record-set a add-record -g ${RESOURCE_GROUP} -z ${CLUSTER_NAME}.${BASE_DOMAIN} -n *.apps -a ${PUBLIC_IP_ROUTER} ----- - -If you prefer to add explicit domains instead of using a wildcard, you can -create entries for each of the cluster's current routes: - -[source,terminal] ----- -$ oc get --all-namespaces -o jsonpath='{range .items[*]}{range .status.ingress[*]}{.host}{"\n"}{end}{end}' routes ----- - -.Example output -[source,terminal] ----- -oauth-openshift.apps.cluster.basedomain.com -console-openshift-console.apps.cluster.basedomain.com -downloads-openshift-console.apps.cluster.basedomain.com -alertmanager-main-openshift-monitoring.apps.cluster.basedomain.com -grafana-openshift-monitoring.apps.cluster.basedomain.com -prometheus-k8s-openshift-monitoring.apps.cluster.basedomain.com ----- diff --git a/modules/installation-azure-create-resource-group-and-identity.adoc b/modules/installation-azure-create-resource-group-and-identity.adoc deleted file mode 100644 index 34cc32fb1389..000000000000 --- a/modules/installation-azure-create-resource-group-and-identity.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-create-resource-group-and-identity_{context}"] -= Creating the Azure resource group and identity - -You must create a Microsoft Azure link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups[resource group] and an identity for that resource group. -These are both used during the installation of your {product-title} cluster on -Azure. - -.Prerequisites - -* Configure an Azure account. - -* Generate the Ignition config files for your cluster. - -.Procedure - -. Create the resource group in a supported Azure region: -+ -[source,terminal] ----- -$ az group create --name ${RESOURCE_GROUP} --location ${AZURE_REGION} ----- - -. Create an Azure identity for the resource group: -+ -[source,terminal] ----- -$ az identity create -g ${RESOURCE_GROUP} -n ${INFRA_ID}-identity ----- -+ -This is used to grant the required access to Operators in your cluster. For -example, this allows the Ingress Operator to create a public IP and its load -balancer. You must assign the Azure identity to a role. - -. Grant the Contributor role to the Azure identity: - -.. Export the following variables required by the Azure role assignment: -+ -[source,terminal] ----- -$ export PRINCIPAL_ID=`az identity show -g ${RESOURCE_GROUP} -n ${INFRA_ID}-identity --query principalId --out tsv` ----- -+ -[source,terminal] ----- -$ export RESOURCE_GROUP_ID=`az group show -g ${RESOURCE_GROUP} --query id --out tsv` ----- - -.. Assign the Contributor role to the identity: -+ -[source,terminal] ----- -$ az role assignment create --assignee "${PRINCIPAL_ID}" --role 'Contributor' --scope "${RESOURCE_GROUP_ID}" ----- diff --git a/modules/installation-azure-increasing-limits.adoc b/modules/installation-azure-increasing-limits.adoc deleted file mode 100644 index 731ccc90a52e..000000000000 --- a/modules/installation-azure-increasing-limits.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-account.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-increasing-limits_{context}"] -= Increasing Azure account limits - -To increase an account limit, file a support request on the Azure portal. -[NOTE] -==== -You can increase only one type of quota per support request. -==== - -.Procedure - -. From the Azure portal, click *Help + support* in the lower left corner. - -. Click *New support request* and then select the required values: -.. From the *Issue type* list, select *Service and subscription limits (quotas)*. -.. From the *Subscription* list, select the subscription to modify. -.. From the *Quota type* list, select the quota to increase. For example, select -*Compute-VM (cores-vCPUs) subscription limit increases* to increase the number -of vCPUs, which is required to install a cluster. -.. Click *Next: Solutions*. - -. On the *Problem Details* page, provide the required information for your quota -increase: -.. Click *Provide details* and provide the required details in the *Quota details* window. -.. In the SUPPORT METHOD and CONTACT INFO sections, provide the issue severity -and your contact details. - -. Click *Next: Review + create* and then click *Create*. diff --git a/modules/installation-azure-limits.adoc b/modules/installation-azure-limits.adoc deleted file mode 100644 index 8b445050853b..000000000000 --- a/modules/installation-azure-limits.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-account.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-limits_{context}"] -= Azure account limits - -The {product-title} cluster uses a number of Microsoft Azure -components, and the default -link:https://docs.microsoft.com/en-us/azure/azure-subscription-service-limits[Azure subscription and service limits, quotas, and constraints] -affect your ability to install {product-title} clusters. - -[IMPORTANT] -==== -Default limits vary by offer category types, such as Free Trial and Pay-As-You-Go, and by series, such as Dv2, F, and G. For example, the default for Enterprise Agreement subscriptions is 350 cores. - -Check the limits for your subscription type and if necessary, increase quota limits for your account before you install a default -cluster on Azure. -==== - -The following table summarizes the Azure components whose limits can impact your -ability to install and run {product-title} clusters. - - -[cols="2a,3a,3a,8a",options="header"] -|=== -|Component |Number of components required by default| Default Azure limit |Description - -|vCPU -|40 -|20 per region -|A default cluster requires 40 vCPUs, so you must increase the account limit. - -By default, each cluster creates the following instances: - -* One bootstrap machine, which is removed after installation -* Three control plane machines -* Three compute machines - -Because the bootstrap machine uses `Standard_D4s_v3` machines, which use 4 vCPUs, -the control plane machines use `Standard_D8s_v3` virtual -machines, which use 8 vCPUs, and the worker machines use `Standard_D4s_v3` -virtual machines, which use 4 vCPUs, a default cluster requires 40 vCPUs. -The bootstrap node VM, which uses 4 vCPUs, is used only during installation. - -To deploy more worker nodes, enable autoscaling, deploy large workloads, or use -a different instance type, you must further increase the vCPU limit for your -account to ensure that your cluster can deploy the machines that you require. - -By default, the installation program distributes control plane and compute machines across -link:https://azure.microsoft.com/en-us/global-infrastructure/availability-zones/[all availability zones] -within -link:https://azure.microsoft.com/en-us/global-infrastructure/regions[a region]. -To ensure high availability for your cluster, select a region with at least -three availability zones. If your region contains fewer than three availability -zones, the installation program places more than one control plane machine in the -available zones. -//// -You can [provide an install-config](../overview.md#multiple-invocations) to -[configure](customization.md) the installation program to use specific zones to override the defaults. -//// - -|VNet -| 1 -| 1000 per region -| Each default cluster requires one Virtual Network (VNet), which contains two -subnets. - -|Network interfaces -|6 -|65,536 per region -|Each default cluster requires six network interfaces. If you create more -machines or your deployed workloads create load balancers, your cluster uses -more network interfaces. - -|Network security groups -|2 -|5000 -| Each default cluster -Each cluster creates network security groups for each subnet in the VNet. -The default cluster creates network -security groups for the control plane and for the compute node subnets: - -[horizontal] - `controlplane`:: Allows the control plane machines to be reached on port 6443 - from anywhere -`node`:: Allows worker nodes to be reached from the Internet on ports 80 and 443 - -|Network load balancers -| 3 -| 1000 per region -|Each cluster creates the following -link:https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview[load balancers]: - -[horizontal] -`default`:: Public IP address that load balances requests to ports 80 and 443 across worker machines -`internal`:: Private IP address that load balances requests to ports 6443 and 22623 across control plane machines -`external`:: Public IP address that load balances requests to port 6443 across control plane machines - -If your applications create more Kubernetes `LoadBalancer` service objects, -your cluster uses more load balancers. - -|Public IP addresses -|3 -| -|Each of the two public load balancers uses a public IP address. The bootstrap -machine also uses a public IP address so that you can SSH into the -machine to troubleshoot issues during installation. The IP address for the -bootstrap node is used only during installation. - -|Private IP addresses -|7 -| -|The internal load balancer, each of the three control plane machines, and each -of the three worker machines each use a private IP address. -|=== diff --git a/modules/installation-azure-network-config.adoc b/modules/installation-azure-network-config.adoc deleted file mode 100644 index 8f7963aade91..000000000000 --- a/modules/installation-azure-network-config.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-account.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-network-config_{context}"] -= Configuring a public DNS zone in Azure - -To install {product-title}, the Microsoft Azure account you use must -have a dedicated public hosted DNS zone in your account. This zone must be -authoritative for the domain. This service provides -cluster DNS resolution and name lookup for external connections to the cluster. - -.Procedure - -. Identify your domain, or subdomain, and registrar. You can transfer an -existing domain and registrar or obtain a new one through Azure or another source. -+ -[NOTE] -==== -For more information about purchasing domains through Azure, see -link:https://docs.microsoft.com/en-us/azure/app-service/manage-custom-dns-buy-domain[Buy a custom domain name for Azure App Service] -in the Azure documentation. -==== - -. If you are using an existing domain and registrar, migrate its DNS to Azure. See -link:https://docs.microsoft.com/en-us/azure/app-service/manage-custom-dns-migrate-domain[Migrate an active DNS name to Azure App Service] -in the Azure documentation. - -. Configure DNS for your domain. Follow the steps in the -link:https://docs.microsoft.com/en-us/azure/dns/dns-delegate-domain-azure-dns[Tutorial: Host your domain in Azure DNS] -in the Azure documentation to create a public hosted zone for your domain or -subdomain, extract the new authoritative name servers, and update the registrar -records for the name servers that your domain uses. -+ -Use an appropriate root domain, such as `openshiftcorp.com`, or subdomain, -such as `clusters.openshiftcorp.com`. - -. If you use a subdomain, follow your company's procedures to add its delegation -records to the parent domain. diff --git a/modules/installation-azure-permissions.adoc b/modules/installation-azure-permissions.adoc deleted file mode 100644 index d7bd3ea38a8c..000000000000 --- a/modules/installation-azure-permissions.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-account.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-permissions_{context}"] -= Required Azure roles - -Your Microsoft Azure account must have the following roles for the subscription -that you use: - -* `User Access Administrator` - -To set roles on the Azure portal, see the -link:https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal[Manage access to Azure resources using RBAC and the Azure portal] -in the Azure documentation. diff --git a/modules/installation-azure-regions.adoc b/modules/installation-azure-regions.adoc deleted file mode 100644 index eb08362293a5..000000000000 --- a/modules/installation-azure-regions.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-account.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-regions_{context}"] -= Supported Azure regions - -The installation program dynamically generates the list of available Microsoft Azure regions based on your subscription. The following Azure regions were tested and validated in {product-title} version 4.6.1: - -[discrete] -== Supported Azure public regions - -* `australiacentral` (Australia Central) -* `australiaeast` (Australia East) -* `australiasoutheast` (Australia South East) -* `brazilsouth` (Brazil South) -* `canadacentral` (Canada Central) -* `canadaeast` (Canada East) -* `centralindia` (Central India) -* `centralus` (Central US) -* `eastasia` (East Asia) -* `eastus` (East US) -* `eastus2` (East US 2) -* `francecentral` (France Central) -//* francesouth (France South) -* `germanywestcentral` (Germany West Central) -* `japaneast` (Japan East) -* `japanwest` (Japan West) -* `koreacentral` (Korea Central) -* `koreasouth` (Korea South) -* `northcentralus` (North Central US) -* `northeurope` (North Europe) -* `norwayeast` (Norway East) -* `southafricanorth` (South Africa North) -//* southafricawest (South Africa West) -* `southcentralus` (South Central US) -* `southeastasia` (Southeast Asia) -* `southindia` (South India) -* `switzerlandnorth` (Switzerland North) -//* uaecentral (UAE Central) -* `uaenorth` (UAE North) -* `uksouth` (UK South) -* `ukwest` (UK West) -* `westcentralus` (West Central US) -* `westeurope` (West Europe) -* `westindia` (West India) -* `westus` (West US) -* `westus2` (West US 2) - -[discrete] -== Supported Azure Government regions - -Support for the following Microsoft Azure Government (MAG) regions was added in {product-title} version 4.6: - -* `usgovtexas` (US Gov Texas) -* `usgovvirginia` (US Gov Virginia) -//* usdodcentral (US DoD Central) -//* usdodeast (US DoD East) -//* usgovarizona (US Gov Arizona) -//* usgoviowa (US Gov Iowa) - -You can reference all available MAG regions in the link:https://azure.microsoft.com/en-us/global-infrastructure/geographies/#geographies[Azure documentation]. Other provided MAG regions are expected to work with {product-title}, but have not been tested. diff --git a/modules/installation-azure-service-principal.adoc b/modules/installation-azure-service-principal.adoc deleted file mode 100644 index 243f0fab6ede..000000000000 --- a/modules/installation-azure-service-principal.adoc +++ /dev/null @@ -1,200 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-account.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-service-principal_{context}"] -= Creating a service principal - -Because {product-title} and its installation program must create Microsoft Azure -resources through Azure Resource Manager, you must create a service principal -to represent it. - -.Prerequisites - -* Install or update the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[Azure CLI]. -* Install the `jq` package. -* Your Azure account has the required roles for the subscription that you use. - -.Procedure - -. Log in to the Azure CLI: -+ -[source,terminal] ----- -$ az login ----- -+ -Log in to Azure in the web console by using your credentials. - -. If your Azure account uses subscriptions, ensure that you are using the right -subscription. -.. View the list of available accounts and record the `tenantId` value for the -subscription you want to use for your cluster: -+ -[source,terminal] ----- -$ az account list --refresh ----- -+ -.Example output -[source,terminal] ----- -[ - { - "cloudName": "AzureCloud", - "id": "9bab1460-96d5-40b3-a78e-17b15e978a80", - "isDefault": true, - "name": "Subscription Name", - "state": "Enabled", - "tenantId": "6057c7e9-b3ae-489d-a54e-de3f6bf6a8ee", - "user": { - "name": "you@example.com", - "type": "user" - } - } -] ----- - -.. View your active account details and confirm that the `tenantId` value matches -the subscription you want to use: -+ -[source,terminal] ----- -$ az account show ----- -+ -.Example output -[source,terminal] ----- -{ - "environmentName": "AzureCloud", - "id": "9bab1460-96d5-40b3-a78e-17b15e978a80", - "isDefault": true, - "name": "Subscription Name", - "state": "Enabled", - "tenantId": "6057c7e9-b3ae-489d-a54e-de3f6bf6a8ee", <1> - "user": { - "name": "you@example.com", - "type": "user" - } -} ----- -<1> Ensure that the value of the `tenantId` parameter is the UUID of the -correct subscription. - -.. If you are not using the right subscription, change the active subscription: -+ -[source,terminal] ----- -$ az account set -s <id> <1> ----- -<1> Substitute the value of the `id` for the subscription that you want to -use for `<id>`. - -.. If you changed the active subscription, display your account information again: -+ -[source,terminal] ----- -$ az account show ----- -+ -.Example output -[source,terminal] ----- -{ - "environmentName": "AzureCloud", - "id": "33212d16-bdf6-45cb-b038-f6565b61edda", - "isDefault": true, - "name": "Subscription Name", - "state": "Enabled", - "tenantId": "8049c7e9-c3de-762d-a54e-dc3f6be6a7ee", - "user": { - "name": "you@example.com", - "type": "user" - } -} ----- - -. Record the values of the `tenantId` and `id` parameters from the previous -output. You need these values during {product-title} installation. - -. Create the service principal for your account: -+ -[source,terminal] ----- -$ az ad sp create-for-rbac --role Contributor --name <service_principal> <1> ----- -<1> Replace `<service_principal>` with the name to assign to the service principal. -+ -.Example output -[source,terminal] ----- -Changing "<service_principal>" to a valid URI of "http://<service_principal>", which is the required format used for service principal names -Retrying role assignment creation: 1/36 -Retrying role assignment creation: 2/36 -Retrying role assignment creation: 3/36 -Retrying role assignment creation: 4/36 -{ - "appId": "8bd0d04d-0ac2-43a8-928d-705c598c6956", - "displayName": "<service_principal>", - "name": "http://<service_principal>", - "password": "ac461d78-bf4b-4387-ad16-7e32e328aec6", - "tenant": "6048c7e9-b2ad-488d-a54e-dc3f6be6a7ee" -} ----- - -. Record the values of the `appId` and `password` parameters from the previous -output. You need these values during {product-title} installation. - -. Grant additional permissions to the service principal. -+ --- -** You must always add the `Contributor` and `User Access Administrator` roles to the app registration service principal so the cluster can assign credentials for its components. -** To operate the Cloud Credential Operator (CCO) in _mint mode_, the app registration service principal also requires the `Azure Active Directory Graph/Application.ReadWrite.OwnedBy` API permission. -** To operate the CCO in _passthrough mode_, the app registration service principal does not require additional API permissions. --- -+ -For more information about CCO modes, see the *Cloud Credential Operator* entry in the *Red Hat Operators reference* content. - -.. To assign the `User Access Administrator` role, run the following command: -+ -[source,terminal] ----- -$ az role assignment create --role "User Access Administrator" \ - --assignee-object-id $(az ad sp list --filter "appId eq '<appId>'" \ <1> - | jq '.[0].objectId' -r) ----- -<1> Replace `<appId>` with the `appId` parameter value for your service principal. - -.. To assign the `Azure Active Directory Graph` permission, run the following -command: -+ -[source,terminal] ----- -$ az ad app permission add --id <appId> \ <1> - --api 00000002-0000-0000-c000-000000000000 \ - --api-permissions 824c81eb-e3f8-4ee6-8f6d-de7f50d565b7=Role ----- -<1> Replace `<appId>` with the `appId` parameter value for your service principal. -+ -.Example output -[source,terminal] ----- -Invoking "az ad app permission grant --id 46d33abc-b8a3-46d8-8c84-f0fd58177435 --api 00000002-0000-0000-c000-000000000000" is needed to make the change effective ----- -+ -For more information about the specific permissions that you grant with this -command, see the -link:https://blogs.msdn.microsoft.com/aaddevsup/2018/06/06/guid-table-for-windows-azure-active-directory-permissions/[GUID Table for Windows Azure Active Directory Permissions]. -.. Approve the permissions request. If your account does not have the -Azure Active Directory tenant administrator role, follow the guidelines for -your organization to request that the tenant administrator approve your -permissions request. -+ -[source, terminal] ----- -$ az ad app permission grant --id <appId> \ <1> - --api 00000002-0000-0000-c000-000000000000 ----- -<1> Replace `<appId>` with the `appId` parameter value for your service principal. diff --git a/modules/installation-azure-user-defined-routing.adoc b/modules/installation-azure-user-defined-routing.adoc deleted file mode 100644 index ce7fd7a8dda2..000000000000 --- a/modules/installation-azure-user-defined-routing.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-private.adoc - -[id="installation-azure-user-defined-routing_{context}"] -= User-defined outbound routing - -In {product-title}, you can choose your own outbound routing for a cluster to -connect to the Internet. This allows you to skip the creation of public IP -addresses and the public load balancer. - -You can configure user-defined routing by modifying parameters in the -`install-config.yaml` file before installing your cluster. A pre-existing VNet -is required to use outbound routing when installing a cluster; the installation -program is not responsible for configuring this. - -When configuring a cluster to use user-defined routing, the installation program -does not create the following resources: - -* Outbound rules for access to the Internet. -* Public IPs for the public load balancer. -* Kubernetes Service object to add the cluster machines to the public load -balancer for outbound requests. - -You must ensure the following items are available before setting user-defined -routing: - -* Egress to the Internet is possible to pull container images, unless using an -internal registry mirror. -* The cluster can access Azure APIs. -* Various allowlist endpoints are configured. You can reference these endpoints -in the _Configuring your firewall_ section. - -There are several pre-existing networking setups that are supported for Internet -access using user-defined routing. - -[discrete] -== Private cluster with network address translation - -You can use link:https://docs.microsoft.com/en-us/azure/virtual-network/nat-overview[Azure VNET network address translation (NAT)] -to provide outbound Internet access for the subnets in your cluster. You can -reference -link:https://docs.microsoft.com/en-us/azure/virtual-network/quickstart-create-nat-gateway-cli[Create a NAT gateway using Azure CLI] -in the Azure documentation for configuration instructions. - -When using a VNet setup with Azure NAT and user-defined routing configured, you -can create a private cluster with no public endpoints. - -[discrete] -== Private cluster with Azure Firewall - -You can use Azure Firewall to provide outbound routing for the VNet used to -install the cluster. You can learn more about -link:https://docs.microsoft.com/en-us/azure/aks/egress-outboundtype#deploy-a-cluster-with-outbound-type-of-udr-and-azure-firewall[providing user-defined routing with Azure Firewall] -in the Azure documentation. - -When using a VNet setup with Azure Firewall and user-defined routing configured, -you can create a private cluster with no public endpoints. - -[discrete] -== Private cluster with a proxy configuration - -You can use a proxy with user-defined routing to allow egress to the Internet. -You must ensure that cluster Operators do not access Azure APIs using a -proxy; Operators must have access to Azure APIs outside of the proxy. - -When using the default route table for subnets, with `0.0.0.0/0` populated -automatically by Azure, all Azure API requests are routed over Azure's internal -network even though the IP addresses are public. As long as the Network Security -Group rules allow egress to Azure API endpoints, proxies with user-defined -routing configured allow you to create private clusters with no public -endpoints. - -[discrete] -== Private cluster with no Internet access - -You can have VNets with no access to the Internet if your cluster has access to -the following: - -* An internal registry mirror that allows for pulling container images -* Access to Azure APIs - -With these requirements available, you can use user-defined routing to create -private clusters with no public endpoints. diff --git a/modules/installation-azure-user-infra-completing.adoc b/modules/installation-azure-user-infra-completing.adoc deleted file mode 100644 index d0f0c1658b64..000000000000 --- a/modules/installation-azure-user-infra-completing.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-user-infra-completing_{context}"] -= Completing an Azure installation on user-provisioned infrastructure - -After you start the {product-title} installation on Microsoft Azure -user-provisioned infrastructure, you can monitor the cluster events until the -cluster is ready. - -.Prerequisites - -* Deploy the bootstrap machine for an {product-title} cluster on user-provisioned Azure infrastructure. -* Install the `oc` CLI and log in. - -.Procedure - -* Complete the cluster installation: -+ -[source,terminal] ----- -$ ./openshift-install --dir=<installation_directory> wait-for install-complete <1> ----- -+ -.Example output -[source,terminal] ----- -INFO Waiting up to 30m0s for the cluster to initialize... ----- -<1> For `<installation_directory>`, specify the path to the directory that you -stored the installation files in. -+ -[IMPORTANT] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== diff --git a/modules/installation-azure-user-infra-deploying-rhcos.adoc b/modules/installation-azure-user-infra-deploying-rhcos.adoc deleted file mode 100644 index a62a5aee432d..000000000000 --- a/modules/installation-azure-user-infra-deploying-rhcos.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-user-infra-deploying-rhcos_{context}"] -= Deploying the {op-system} cluster image for the Azure infrastructure - -You must use a valid {op-system-first} image for Microsoft Azure for your -{product-title} nodes. - -.Prerequisites - -* Configure an Azure account. - -* Generate the Ignition config files for your cluster. - -* Store the {op-system} virtual hard disk (VHD) cluster image in an Azure storage container. - -* Store the bootstrap Ignition config file in an Azure storage container. - -.Procedure - -. Copy the template from the *ARM template for image storage* section of -this topic and save it as `02_storage.json` in your cluster's installation directory. This template -describes the image storage that your cluster requires. - -. Export the {op-system} VHD blob URL as a variable: -+ -[source,terminal] ----- -$ export VHD_BLOB_URL=`az storage blob url --account-name ${CLUSTER_NAME}sa --account-key ${ACCOUNT_KEY} -c vhd -n "rhcos.vhd" -o tsv` ----- - -. Deploy the cluster image: -+ -[source,terminal] ----- -$ az deployment group create -g ${RESOURCE_GROUP} \ - --template-file "<installation_directory>/02_storage.json" \ - --parameters vhdBlobURL="${VHD_BLOB_URL}" \ <1> - --parameters baseName="${INFRA_ID}"<2> ----- -<1> The blob URL of the {op-system} VHD to be used to create master and worker machines. -<2> The base name to be used in resource names; this is usually the cluster's infrastructure ID. diff --git a/modules/installation-azure-user-infra-uploading-rhcos.adoc b/modules/installation-azure-user-infra-uploading-rhcos.adoc deleted file mode 100644 index fe56db6dd86a..000000000000 --- a/modules/installation-azure-user-infra-uploading-rhcos.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-azure-user-infra.adoc - -[id="installation-azure-user-infra-uploading-rhcos_{context}"] -= Uploading the {op-system} cluster image and bootstrap Ignition config file - -The Azure client does not support deployments based on files existing locally; -therefore, you must copy and store the {op-system} virtual hard disk (VHD) -cluster image and bootstrap Ignition config file in a storage container so they -are accessible during deployment. - -.Prerequisites - -* Configure an Azure account. - -* Generate the Ignition config files for your cluster. - -.Procedure - -. Create an Azure storage account to store the VHD cluster image: -+ -[source,terminal] ----- -$ az storage account create -g ${RESOURCE_GROUP} --location ${AZURE_REGION} --name ${CLUSTER_NAME}sa --kind Storage --sku Standard_LRS ----- -+ -[WARNING] -==== -The Azure storage account name must be between 3 and 24 characters in length and -use numbers and lower-case letters only. If your `CLUSTER_NAME` variable does -not follow these restrictions, you must manually define the Azure storage -account name. For more information on Azure storage account name restrictions, -see link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/error-storage-account-name[Resolve errors for storage account names] -in the Azure documentation. -==== - -. Export the storage account key as an environment variable: -+ -[source,terminal] ----- -$ export ACCOUNT_KEY=`az storage account keys list -g ${RESOURCE_GROUP} --account-name ${CLUSTER_NAME}sa --query "[0].value" -o tsv` ----- - -. Choose the {op-system} version to use and export the URL of its VHD to an -environment variable: -+ -[source,terminal] ----- -$ export VHD_URL=`curl -s https://raw.githubusercontent.com/openshift/installer/release-4.8/data/data/rhcos.json | jq -r .azure.url` ----- -+ -[IMPORTANT] -==== -The {op-system} images might not change with every release of {product-title}. -You must specify an image with the highest version that is -less than or equal to the {product-title} version that you install. Use the image version -that matches your {product-title} version if it is available. -==== - -. Copy the chosen VHD to a blob: -+ -[source,terminal] ----- -$ az storage container create --name vhd --account-name ${CLUSTER_NAME}sa --account-key ${ACCOUNT_KEY} ----- -+ -[source,terminal] ----- -$ az storage blob copy start --account-name ${CLUSTER_NAME}sa --account-key ${ACCOUNT_KEY} --destination-blob "rhcos.vhd" --destination-container vhd --source-uri "${VHD_URL}" ----- -+ -To track the progress of the VHD copy task, run this script: -+ ----- -status="unknown" -while [ "$status" != "success" ] -do - status=`az storage blob show --container-name vhd --name "rhcos.vhd" --account-name ${CLUSTER_NAME}sa --account-key ${ACCOUNT_KEY} -o tsv --query properties.copy.status` - echo $status -done ----- - -. Create a blob storage container and upload the generated `bootstrap.ign` file: -+ -[source,terminal] ----- -$ az storage container create --name files --account-name ${CLUSTER_NAME}sa --account-key ${ACCOUNT_KEY} --public-access blob ----- -+ -[source,terminal] ----- -$ az storage blob upload --account-name ${CLUSTER_NAME}sa --account-key ${ACCOUNT_KEY} -c "files" -f "<installation_directory>/bootstrap.ign" -n "bootstrap.ign" ----- diff --git a/modules/installation-azure-user-infra-wait-for-bootstrap.adoc b/modules/installation-azure-user-infra-wait-for-bootstrap.adoc deleted file mode 100644 index a64a29ca9a61..000000000000 --- a/modules/installation-azure-user-infra-wait-for-bootstrap.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-azure-user-infra-wait-for-bootstrap_{context}"] -= Wait for bootstrap completion and remove bootstrap resources in Azure - -After you create all of the required infrastructure in Microsoft Azure, wait for -the bootstrap process to complete on the machines that you provisioned by using -the Ignition config files that you generated with the installation program. - -.Prerequisites - -* Configure an Azure account. -* Generate the Ignition config files for your cluster. -* Create and configure a VNet and associated subnets in Azure. -* Create and configure networking and load balancers in Azure. -* Create control plane and compute roles. -* Create the bootstrap machine. -* Create the control plane machines. - -.Procedure - -. Change to the directory that contains the installation program and run the -following command: -+ -[source,terminal] ----- -$ ./openshift-install wait-for bootstrap-complete --dir=<installation_directory> \ <1> - --log-level info <2> ----- -<1> For `<installation_directory>`, specify the path to the directory that you -stored the installation files in. -<2> To view different installation details, specify `warn`, `debug`, or -`error` instead of `info`. -+ -If the command exits without a `FATAL` warning, your production control plane -has initialized. - -. Delete the bootstrap resources: -+ -[source,terminal] ----- -$ az network nsg rule delete -g ${RESOURCE_GROUP} --nsg-name ${INFRA_ID}-nsg --name bootstrap_ssh_in -$ az vm stop -g ${RESOURCE_GROUP} --name ${INFRA_ID}-bootstrap -$ az vm deallocate -g ${RESOURCE_GROUP} --name ${INFRA_ID}-bootstrap -$ az vm delete -g ${RESOURCE_GROUP} --name ${INFRA_ID}-bootstrap --yes -$ az disk delete -g ${RESOURCE_GROUP} --name ${INFRA_ID}-bootstrap_OSDisk --no-wait --yes -$ az network nic delete -g ${RESOURCE_GROUP} --name ${INFRA_ID}-bootstrap-nic --no-wait -$ az storage blob delete --account-key ${ACCOUNT_KEY} --account-name ${CLUSTER_NAME}sa --container-name files --name bootstrap.ign -$ az network public-ip delete -g ${RESOURCE_GROUP} --name ${INFRA_ID}-bootstrap-ssh-pip ----- diff --git a/modules/installation-bare-metal-config-yaml.adoc b/modules/installation-bare-metal-config-yaml.adoc deleted file mode 100644 index 13ef60f8eba9..000000000000 --- a/modules/installation-bare-metal-config-yaml.adoc +++ /dev/null @@ -1,314 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc -// * installing/installing_ibm_power/installing-ibm-power.adoc -// * installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc -// * installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing-rhv-restricted-network.adoc - -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:ibm-z-kvm: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:ibm-z: -:restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-platform-agnostic"] -:agnostic: -endif::[] -ifeval::["{context}" == "installing-rhv-restricted-network"] -:rhv: -endif::[] - - -[id="installation-bare-metal-config-yaml_{context}"] -ifndef::ibm-z,ibm-z-kvm,ibm-power,agnostic,rhv[] -= Sample `install-config.yaml` file for bare metal -endif::ibm-z,ibm-z-kvm,ibm-power,agnostic,rhv[] -ifdef::ibm-z,ibm-z-kvm[] -= Sample `install-config.yaml` file for IBM Z -endif::ibm-z,ibm-z-kvm[] -ifdef::ibm-power[] -= Sample `install-config.yaml` file for IBM Power Systems -endif::ibm-power[] -ifdef::agnostic[] -= Sample `install-config.yaml` file for other platforms -endif::agnostic[] -ifdef::rhv[] -= Sample `install-config.yaml` file for RHV -endif::rhv[] - -You can customize the `install-config.yaml` file to specify more details about -your {product-title} cluster's platform or modify the values of the required -parameters. - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com <1> -compute: -- hyperthreading: Enabled <2> <3> - name: worker - replicas: 0 <4> -ifeval::["{context}" == "installing-ibm-z"] - architecture : s390x -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] - architecture : s390x -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] - architecture : s390x -endif::[] -ifeval::["{context}" == "installing-ibm-power"] - architecture : ppc64le -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] - architecture : ppc64le -endif::[] -controlPlane: - hyperthreading: Enabled <2> <3> - name: master <3> - replicas: 3 <5> -ifeval::["{context}" == "installing-ibm-z"] - architecture : s390x -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] - architecture : s390x -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] - architecture : s390x -endif::[] -ifeval::["{context}" == "installing-ibm-power"] - architecture : ppc64le -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] - architecture : ppc64le -endif::[] -metadata: - name: test <6> -networking: - clusterNetwork: - - cidr: 10.128.0.0/14 <7> - hostPrefix: 23 <8> -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] - serviceNetwork: <9> - - 172.30.0.0/16 -platform: - none: {} <10> -ifndef::openshift-origin[] -fips: false <11> -endif::openshift-origin[] -ifndef::restricted[] -ifndef::openshift-origin[] -pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "you@example.com"}}}' <12> -endif::openshift-origin[] -ifdef::openshift-origin[] -pullSecret: '{"auths": ...}' <11> -endif::openshift-origin[] -ifndef::openshift-origin[] -sshKey: 'ssh-ed25519 AAAA...' <13> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: 'ssh-ed25519 AAAA...' <12> -endif::openshift-origin[] -endif::restricted[] -ifdef::restricted[] -ifndef::openshift-origin[] -pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "you@example.com"}}}' <12> -endif::openshift-origin[] -ifdef::openshift-origin[] -pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "you@example.com"}}}' <11> -endif::openshift-origin[] -ifndef::openshift-origin[] -sshKey: 'ssh-ed25519 AAAA...' <13> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: 'ssh-ed25519 AAAA...' <12> -endif::openshift-origin[] -endif::restricted[] -ifdef::restricted[] -ifndef::openshift-origin[] -additionalTrustBundle: | <14> - -----BEGIN CERTIFICATE----- - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - -----END CERTIFICATE----- -imageContentSources: <15> -- mirrors: - - <local_registry>/<local_repository_name>/release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <local_registry>/<local_repository_name>/release - source: registry.svc.ci.openshift.org/ocp/release -endif::openshift-origin[] -ifdef::openshift-origin[] -additionalTrustBundle: | <13> - -----BEGIN CERTIFICATE----- - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - -----END CERTIFICATE----- -imageContentSources: <14> -- mirrors: - - <local_registry>/<local_repository_name>/release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <local_registry>/<local_repository_name>/release - source: registry.svc.ci.openshift.org/ocp/release -endif::openshift-origin[] -ifdef::ibm-z[] - - <local_repository>/ocp4/openshift4 - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <local_repository>/ocp4/openshift4 - source: quay.io/openshift-release-dev/ocp-v4.0-art-dev -endif::ibm-z[] -ifndef::ibm-z[] -ifndef::openshift-origin[] - - <local_registry>/<local_repository_name>/release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <local_registry>/<local_repository_name>/release - source: registry.svc.ci.openshift.org/ocp/release -endif::openshift-origin[] -endif::ibm-z[] -endif::restricted[] ----- -<1> The base domain of the cluster. All DNS records must be sub-domains of this -base and include the cluster name. -<2> The `controlPlane` section is a single mapping, but the compute section is a -sequence of mappings. To meet the requirements of the different data structures, -the first line of the `compute` section must begin with a hyphen, `-`, and the -first line of the `controlPlane` section must not. Although both sections -currently define a single machine pool, it is possible that future versions -of {product-title} will support defining multiple compute pools during -installation. Only one control plane pool is used. -<3> Whether to enable or disable simultaneous multithreading (SMT), or `hyperthreading`. By default, SMT is enabled to increase the performance of your machines' cores. You can disable it by setting the parameter value to `Disabled`. If you disable SMT, you must disable it in all cluster machines; this includes both control plane and compute machines. -+ -[IMPORTANT] -==== -If you disable simultaneous multithreading (SMT) using the `install-config.yaml` file or in your BIOS settings, ensure that your capacity planning accounts for the dramatically decreased machine performance. If you disable SMT in the BIOS, the `hyperthreading` parameter in the `install-config.yaml` file will have no effect. -==== -<4> You must set the value of the `replicas` parameter to `0`. This parameter -controls the number of workers that the cluster creates and manages for you, -which are functions that the cluster does not perform when you -use user-provisioned infrastructure. You must manually deploy worker -machines for the cluster to use before you finish installing {product-title}. -<5> The number of control plane machines that you add to the cluster. Because -the cluster uses this values as the number of etcd endpoints in the cluster, the -value must match the number of control plane machines that you deploy. -<6> The cluster name that you specified in your DNS records. -<7> A block of IP addresses from which pod IP addresses are allocated. This block must -not overlap with existing physical networks. These IP addresses are used for the pod network. If you need to access the pods from an external network, you must configure load balancers and routers to manage the traffic. -<8> The subnet prefix length to assign to each individual node. For example, if -`hostPrefix` is set to `23`, then each node is assigned a `/23` subnet out of -the given `cidr`, which allows for 510 (2^(32 - 23) - 2) pod IPs addresses. If -you are required to provide access to nodes from an external network, configure -load balancers and routers to manage the traffic. -<9> The IP address pool to use for service IP addresses. You can enter only -one IP address pool. If you need to access the services from an external network, -configure load balancers and routers to manage the traffic. -<10> You must set the platform to `none`. You cannot provide additional platform -configuration variables for -ifndef::ibm-z,ibm-z-kvm,ibm-power,rhv[your platform.] -ifdef::ibm-z,ibm-z-kvm[IBM Z infrastructure.] -ifdef::ibm-power[IBM Power Systems infrastructure.] -ifdef::rhv[RHV infrastructure.] -ifndef::openshift-origin[] -<11> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -endif::openshift-origin[] -ifndef::restricted[] -ifdef::ibm-z,ibm-z-kvm[] -<12> The pullSecret value contains the authentication information for your registry. For `<bastion_host_name>`, specify the registry domain name that you specified in the certificate for your mirror registry, and for `<credentials>`, specify the base64-encoded user name and password for your mirror registry. -endif::ibm-z,ibm-z-kvm[] -ifndef::ibm-z,ibm-z-kvm[] -<12> The pull secret that you obtained from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. -endif::ibm-z,ibm-z-kvm[] -This pull secret allows you to authenticate with the services that are -provided by the included authorities, including Quay.io, which serves the -container images for {product-title} components. -endif::restricted[] -ifdef::restricted[] -<12> For `<local_registry>`, specify the registry domain name, and optionally the -port, that your mirror registry uses to serve content. For example -`registry.example.com` or `registry.example.com:5000`. For `<credentials>`, -specify the base64-encoded user name and password for your mirror registry. -<13> The pull secret that you obtained from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. This pull secret allows you to authenticate with the services that are -provided by the included authorities, including Quay.io, which serves the -container images for {product-title} components. -endif::restricted[] -ifndef::openshift-origin[] -<13> The public portion of the default SSH key for the `core` user in -{op-system-first}. -endif::openshift-origin[] -ifdef::openshift-origin[] -<12> The public portion of the default SSH key for the `core` user in -{op-system-first}. -endif::openshift-origin[] -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -ifdef::restricted[] -ifndef::ibm-z,ibm-z-kvm[] -<14> Provide the contents of the certificate file that you used for your mirror -registry. -endif::ibm-z,ibm-z-kvm[] -ifdef::ibm-z,ibm-z-kvm[] -<14> Add the `additionalTrustBundle` parameter and value. The value must be the contents of the certificate file that you used for your mirror registry, which can be an exiting, trusted certificate authority or the self-signed certificate that you generated for the mirror registry. -endif::ibm-z,ibm-z-kvm[] -<15> Provide the `imageContentSources` section from the output of the command to -mirror the repository. -endif::restricted[] - - -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!restricted: -endif::[] -ifdef::openshift-origin[] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:!ibm-z-kvm: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:!ibm-z: -:!restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-platform-agnostic"] -:!agnostic: -endif::[] -ifeval::["{context}" == "installing-rhv-restricted-network"] -:!rhv: -endif::[] diff --git a/modules/installation-bootstrap-gather.adoc b/modules/installation-bootstrap-gather.adoc deleted file mode 100644 index 049fd8f1a507..000000000000 --- a/modules/installation-bootstrap-gather.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing-troubleshooting.adoc -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="installation-bootstrap-gather_{context}"] -= Gathering logs from a failed installation - -If you gave an SSH key to your installation program, you can gather data about -your failed installation. - -[NOTE] -==== -You use a different command to gather logs about an unsuccessful installation -than to gather logs from a running cluster. If you must gather logs from a -running cluster, use the `oc adm must-gather` command. -==== - -.Prerequisites - -* Your {product-title} installation failed before the bootstrap process finished. The bootstrap node is running and accessible through SSH. -* The `ssh-agent` process is active on your computer, and you provided the same SSH key to both the `ssh-agent` process and the installation program. -* If you tried to install a cluster on infrastructure that you provisioned, you must have the fully qualified domain names of the bootstrap and master nodes. - -.Procedure - -. Generate the commands that are required to obtain the installation logs from -the bootstrap and control plane machines: -+ --- -** If you used installer-provisioned infrastructure, change to the directory that contains the installation program and run the following command: -+ -[source,terminal] ----- -$ ./openshift-install gather bootstrap --dir=<installation_directory> <1> ----- -<1> `installation_directory` is the directory you specified when you ran `./openshift-install create cluster`. This directory contains the {product-title} -definition files that the installation program creates. -+ -For installer-provisioned infrastructure, the installation program stores -information about the cluster, so you do not specify the host names or IP -addresses. - -** If you used infrastructure that you provisioned yourself, change to the directory that contains the installation program and run the following -command: -+ -[source,terminal] ----- -$ ./openshift-install gather bootstrap --dir=<installation_directory> \ <1> - --bootstrap <bootstrap_address> \ <2> - --master <master_1_address> \ <3> - --master <master_2_address> \ <3> - --master <master_3_address>" <3> ----- -<1> For `installation_directory`, specify the same directory you specified when you ran `./openshift-install create cluster`. This directory contains the {product-title} -definition files that the installation program creates. -<2> `<bootstrap_address>` is the fully qualified domain name or IP address of -the cluster's bootstrap machine. -<3> For each control plane, or master, machine in your cluster, replace `<master_*_address>` with its fully qualified domain name or IP address. -+ -[NOTE] -==== -A default cluster contains three control plane machines. List all of your control plane machines as shown, no matter how many your cluster uses. -==== --- -+ -.Example output -[source,terminal] ----- -INFO Pulling debug logs from the bootstrap machine -INFO Bootstrap gather logs captured here "<installation_directory>/log-bundle-<timestamp>.tar.gz" ----- -+ -If you open a Red Hat support case about your installation failure, include -the compressed logs in the case. diff --git a/modules/installation-cloudformation-bootstrap.adoc b/modules/installation-cloudformation-bootstrap.adoc deleted file mode 100644 index e55922deebd0..000000000000 --- a/modules/installation-cloudformation-bootstrap.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-cloudformation-bootstrap_{context}"] -= CloudFormation template for the bootstrap machine - -You can use the following CloudFormation template to deploy the bootstrap -machine that you need for your {product-title} cluster. - -.CloudFormation template for the bootstrap machine -[%collapsible] -==== -[source,yaml] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/aws/cloudformation/04_cluster_bootstrap.yaml[] ----- -==== diff --git a/modules/installation-cloudformation-control-plane.adoc b/modules/installation-cloudformation-control-plane.adoc deleted file mode 100644 index d78c02afb905..000000000000 --- a/modules/installation-cloudformation-control-plane.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-cloudformation-control-plane_{context}"] -= CloudFormation template for control plane machines - -You can use the following CloudFormation template to deploy the control plane -machines that you need for your {product-title} cluster. - -.CloudFormation template for control plane machines -[%collapsible] -==== -[source,yaml] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/aws/cloudformation/05_cluster_master_nodes.yaml[] ----- -==== diff --git a/modules/installation-cloudformation-dns.adoc b/modules/installation-cloudformation-dns.adoc deleted file mode 100644 index 7a1e3a937c3c..000000000000 --- a/modules/installation-cloudformation-dns.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-cloudformation-dns_{context}"] -= CloudFormation template for the network and load balancers - -You can use the following CloudFormation template to deploy the networking -objects and load balancers that you need for your {product-title} cluster. - -.CloudFormation template for the network and load balancers -[%collapsible] -==== -[source,yaml] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/aws/cloudformation/02_cluster_infra.yaml[] ----- -==== - -[IMPORTANT] -==== -If you are deploying your cluster to an AWS government or secret region, you must update the `InternalApiServerRecord` to use `CNAME` records. Records of type `ALIAS` are not supported for AWS government regions. For example: - -[source,yaml] ----- -Type: CNAME -TTL: 10 -ResourceRecords: -- !GetAtt IntApiElb.DNSName ----- -==== diff --git a/modules/installation-cloudformation-security.adoc b/modules/installation-cloudformation-security.adoc deleted file mode 100644 index 4d6b99f3667c..000000000000 --- a/modules/installation-cloudformation-security.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-cloudformation-security_{context}"] -= CloudFormation template for security objects - -You can use the following CloudFormation template to deploy the security objects -that you need for your {product-title} cluster. - -.CloudFormation template for security objects -[%collapsible] -==== -[source,yaml] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/aws/cloudformation/03_cluster_security.yaml[] ----- -==== diff --git a/modules/installation-cloudformation-vpc.adoc b/modules/installation-cloudformation-vpc.adoc deleted file mode 100644 index 47f3a4bb398b..000000000000 --- a/modules/installation-cloudformation-vpc.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-cloudformation-vpc_{context}"] -= CloudFormation template for the VPC - -You can use the following CloudFormation template to deploy the VPC that -you need for your {product-title} cluster. - -.CloudFormation template for the VPC -[%collapsible] -==== -[source,yaml] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/aws/cloudformation/01_vpc.yaml[] ----- -==== diff --git a/modules/installation-cloudformation-worker.adoc b/modules/installation-cloudformation-worker.adoc deleted file mode 100644 index 0d6ffc022c07..000000000000 --- a/modules/installation-cloudformation-worker.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-cloudformation-worker_{context}"] -= CloudFormation template for worker machines - -You can use the following CloudFormation template to deploy the worker machines -that you need for your {product-title} cluster. - -.CloudFormation template for worker machines -[%collapsible] -==== -[source,yaml] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/aws/cloudformation/06_cluster_worker_node.yaml[] ----- -==== diff --git a/modules/installation-common-issues.adoc b/modules/installation-common-issues.adoc deleted file mode 100644 index 453f7d296e44..000000000000 --- a/modules/installation-common-issues.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing/installing-troubleshooting.adoc - -[id="installation-common-issues_{context}"] -= Troubleshooting common issues with installing on {rh-virtualization-first} - -Here are some common issues you might encounter, along with proposed causes and solutions. - -[id="cpu-load-increases-and-nodes-go-into-a-not-ready-state_{context}"] -== CPU load increases and nodes go into a `Not Ready` state - -* *Symptom*: CPU load increases significantly and nodes start going into a `Not Ready` state. -* *Cause*: The storage domain latency might be too high, especially for master nodes. -* *Solution*: -+ -Make the nodes ready again by restarting the kubelet service: -+ -[source,terminal] ----- -$ systemctl restart kubelet ----- -+ -Inspect the {product-title} metrics service, which automatically gathers and reports on some valuable data such as the etcd disk sync duration. If the cluster is operational, use this data to help determine whether storage latency or throughput is the root issue. If so, consider using a storage resource that has lower latency and higher throughput. -+ -To get raw metrics, enter the following command as kubeadmin or user with cluster-admin privileges: -+ -[source,terminal] ----- -$ oc get --insecure-skip-tls-verify --server=https://localhost:<port> --raw=/metrics ----- -+ -To learn more, see https://access.redhat.com/articles/3793621[Exploring Application Endpoints for the purposes of Debugging with OpenShift 4.x] - -[id="trouble-connecting-the-rhv-cluster-api_{context}"] -== Trouble connecting the {product-title} cluster API - -* *Symptom*: The installation program completes but the {product-title} cluster API is not available. The bootstrap virtual machine remains up after the bootstrap process is complete. When you enter the following command, the response will time out. -+ -[source,terminal] ----- -$ oc login -u kubeadmin -p *** <apiurl> ----- - -* *Cause*: The bootstrap VM was not deleted by the installation program and has not released the cluster's API IP address. -* *Solution*: Use the `wait-for` subcommand to be notified when the bootstrap process is complete: -+ -[source,terminal] ----- -$ ./openshift-install wait-for bootstrap-complete ----- -+ -When the bootstrap process is complete, delete the bootstrap virtual machine: -+ -[source,terminal] ----- -$ ./openshift-install destroy bootstrap ----- diff --git a/modules/installation-complete-user-infra.adoc b/modules/installation-complete-user-infra.adoc deleted file mode 100644 index 8f96bd08f6fa..000000000000 --- a/modules/installation-complete-user-infra.adoc +++ /dev/null @@ -1,247 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:ibm-z: -:restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:ibm-power: -:restricted: -endif::[] -[id="installation-complete-user-infra_{context}"] -= Completing installation on user-provisioned infrastructure - -After you complete the Operator configuration, you can finish installing the -cluster on infrastructure that you provide. - -.Prerequisites - -* Your control plane has initialized. -* You have completed the initial Operator configuration. - -.Procedure - -. Confirm that all the cluster components are online: -+ -[source,terminal] ----- -$ watch -n5 oc get clusteroperators ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -authentication 4.7.0 True False False 3h56m -baremetal 4.7.0 True False False 29h -cloud-credential 4.7.0 True False False 29h -cluster-autoscaler 4.7.0 True False False 29h -config-operator 4.7.0 True False False 6h39m -console 4.7.0 True False False 3h59m -csi-snapshot-controller 4.7.0 True False False 4h12m -dns 4.7.0 True False False 4h15m -etcd 4.7.0 True False False 29h -image-registry 4.7.0 True False False 3h59m -ingress 4.7.0 True False False 4h30m -insights 4.7.0 True False False 29h -kube-apiserver 4.7.0 True False False 29h -kube-controller-manager 4.7.0 True False False 29h -kube-scheduler 4.7.0 True False False 29h -kube-storage-version-migrator 4.7.0 True False False 4h2m -machine-api 4.7.0 True False False 29h -machine-approver 4.7.0 True False False 6h34m -machine-config 4.7.0 True False False 3h56m -marketplace 4.7.0 True False False 4h2m -monitoring 4.7.0 True False False 6h31m -network 4.7.0 True False False 29h -node-tuning 4.7.0 True False False 4h30m -openshift-apiserver 4.7.0 True False False 3h56m -openshift-controller-manager 4.7.0 True False False 4h36m -openshift-samples 4.7.0 True False False 4h30m -operator-lifecycle-manager 4.7.0 True False False 29h -operator-lifecycle-manager-catalog 4.7.0 True False False 29h -operator-lifecycle-manager-packageserver 4.7.0 True False False 3h59m -service-ca 4.7.0 True False False 29h -storage 4.7.0 True False False 4h30m ----- -+ -When all of the cluster Operators are `AVAILABLE`, you can complete the installation. - -. Monitor for cluster completion: -+ -[source,terminal] ----- -$ ./openshift-install --dir=<installation_directory> wait-for install-complete <1> ----- -<1> For `<installation_directory>`, specify the path to the directory that you -stored the installation files in. -+ -.Example output -[source,terminal] ----- -INFO Waiting up to 30m0s for the cluster to initialize... ----- -+ -The command succeeds when the Cluster Version Operator finishes deploying the -{product-title} cluster from Kubernetes API server. -+ -[IMPORTANT] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== - -. Confirm that the Kubernetes API server is communicating with the pods. -.. To view a list of all pods, use the following command: -+ -[source,terminal] ----- -$ oc get pods --all-namespaces ----- -+ -.Example output -[source,terminal] ----- -NAMESPACE NAME READY STATUS RESTARTS AGE -openshift-apiserver-operator openshift-apiserver-operator-85cb746d55-zqhs8 1/1 Running 1 9m -openshift-apiserver apiserver-67b9g 1/1 Running 0 3m -openshift-apiserver apiserver-ljcmx 1/1 Running 0 1m -openshift-apiserver apiserver-z25h4 1/1 Running 0 2m -openshift-authentication-operator authentication-operator-69d5d8bf84-vh2n8 1/1 Running 0 5m -... ----- - -.. View the logs for a pod that is listed in the output of the previous command -by using the following command: -+ -[source,terminal] ----- -$ oc logs <pod_name> -n <namespace> <1> ----- -<1> Specify the pod name and namespace, as shown in the output of the previous -command. -+ -If the pod logs display, the Kubernetes API server can communicate with the -cluster machines. -ifdef::ibm-z,ibm-power[] -. For an installation with FCP, additional steps are required to enable multipathing. -.. To enable multipathing on master nodes, apply the following machine config file: -+ -[source,yaml] --- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: "master" - name: 99-master-kargs-mpath -spec: - kernelArguments: - - 'rd.multipath=default' - - 'root=/dev/disk/by-label/dm-mpath-root' --- - -.. To enable multipathing on worker nodes, apply the following machine config file: -+ -[source,yaml] --- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: "worker" - name: 99-worker-kargs-mpath -spec: - kernelArguments: - - 'rd.multipath=default' - - 'root=/dev/disk/by-label/dm-mpath-root' --- -endif::ibm-z,ibm-power[] -ifdef::ibm-power[] -.. To display a boot list and specify the possible boot devices if the system is booted in normal mode, enter the following command: -+ -[source,terminal] ----- -$ bootlist -m normal -o -sda ----- -.. To update the boot list for normal mode and add alternate device names, enter the following command: -+ -[source,terminal] ----- -$ bootlist -m normal -o /dev/sdc /dev/sdd /dev/sde -sdc -sdd -sde ----- -+ -If the original boot disk path is down, the node reboots from the alternate device registered in the normal boot device list. -endif::ibm-power[] -ifdef::ibm-z,ibm-power[] -.. All the worker nodes are restarted. To monitor the process, enter the following command: -+ -[source,terminal] ----- -$ oc get nodes -w ----- -+ -[NOTE] -==== -If you have additional machine types such as infrastructure nodes, repeat the process for these types. -==== -endif::ibm-z,ibm-power[] - -ifdef::restricted[] -. Register your cluster on the link:https://cloud.redhat.com/openshift/register[Cluster registration] page. -endif::restricted[] - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!restricted: -endif::[] -ifdef::openshift-origin[] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:!ibm-z: -:!restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:!ibm-power: -:restricted: -endif::[] \ No newline at end of file diff --git a/modules/installation-configuration-parameters.adoc b/modules/installation-configuration-parameters.adoc deleted file mode 100644 index 83d25737530c..000000000000 --- a/modules/installation-configuration-parameters.adoc +++ /dev/null @@ -1,933 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-network-customizations.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_gcp/installing-gcp-network-customizations.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc -// * installing/installing_rhv/installing-rhv-custom.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc - -ifeval::["{context}" == "installing-aws-customizations"] -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-government-region"] -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-network-customizations"] -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-private"] -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-vpc"] -:aws: -endif::[] -ifeval::["{context}" == "installing-azure-customizations"] -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-government-region"] -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-network-customizations"] -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-private"] -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-vnet"] -:azure: -endif::[] -ifeval::["{context}" == "installing-gcp-customizations"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-private"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-network-customizations"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-vpc"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-aws-customizations"] -:aws: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-custom"] -:osp: -:osp-custom: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:osp: -:osp-kuryr: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:osp: -:osp-custom: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:osp: -:osp-kuryr: -endif::[] -ifeval::["{context}" == "installing-rhv-customizations"] -:rhv: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-customizations"] -:vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:vmc: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:osp: -:osp-custom: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:vsphere: -endif::[] - -[id="installation-configuration-parameters_{context}"] -= Installation configuration parameters - -Before you deploy an {product-title} cluster, you provide parameter values to describe your account on the cloud platform that hosts your cluster and optionally customize your cluster's platform. When you create the `install-config.yaml` installation configuration file, you provide values for the required parameters through the command line. If you customize your cluster, you can modify the `install-config.yaml` file to provide more details about the platform. - -[NOTE] -==== -After installation, you cannot modify these parameters in the `install-config.yaml` file. -==== - -[IMPORTANT] -==== -The `openshift-install` command does not validate field names for parameters. If an incorrect name is specified, the related file or object is not created, and no error is reported. Ensure that the field names for any parameters that are specified are correct. -==== - -.Required parameters -[cols=".^2,.^3,.^5a",options="header"] -|==== -|Parameter|Description|Values - -|`apiVersion` -|The API version for the `install-config.yaml` content. The current version is `v1`. The installer may also support older API versions. -|String - -|`baseDomain` -|The base domain of your cloud provider. The base domain is used to create routes to your {product-title} cluster components. The full DNS name for your cluster is a combination of the `baseDomain` and `metadata.name` parameter values that uses the `<metadata.name>.<baseDomain>` format. -|A fully-qualified domain or subdomain name, such as `example.com`. - -|`metadata` -|Kubernetes resource `ObjectMeta`, from which only the `name` parameter is consumed. -|Object - -|`metadata.name` -|The name of the cluster. DNS records for the cluster are all subdomains of `{{.metadata.name}}.{{.baseDomain}}`. -|String of lowercase letters, hyphens (`-`), and periods (`.`), such as `dev`. -ifdef::osp[] -The string must be 14 characters or fewer long. -endif::osp[] - -|`platform` -|The configuration for the specific platform upon which to perform the installation: `aws`, `baremetal`, `azure`, `openstack`, `ovirt`, `vsphere`. For additional information about `platform.<platform>` parameters, consult the following table for your specific platform. -|Object - -ifndef::openshift-origin[] -|`pullSecret` -|Get this pull secret from link:https://cloud.redhat.com/openshift/install/pull-secret[] to authenticate downloading container images for {product-title} components from services such as Quay.io. -| -[source,json] ----- -{ - "auths":{ - "cloud.openshift.com":{ - "auth":"b3Blb=", - "email":"you@example.com" - }, - "quay.io":{ - "auth":"b3Blb=", - "email":"you@example.com" - } - } -} ----- -endif::[] - -|==== - -.Optional parameters -[cols=".^2,.^3a,.^3a",options="header"] -|==== -|Parameter|Description|Values - -|`additionalTrustBundle` -|A PEM-encoded X.509 certificate bundle that is added to the nodes' trusted certificate store. This trust bundle may also be used when a proxy has been configured. -|String - -|`compute` -|The configuration for the machines that comprise the compute nodes. -|Array of machine-pool objects. For details, see the following "Machine-pool" table. - -|`compute.architecture` -|Determines the instruction set architecture of the machines in the pool. Currently, heteregeneous clusters are not supported, so all pools must specify the same architecture. Valid values are `amd64` (the default). -|String - -|`compute.hyperthreading` -|Whether to enable or disable simultaneous multithreading, or `hyperthreading`, on compute machines. By default, simultaneous multithreading is enabled to increase the performance of your machines' cores. -[IMPORTANT] -==== -If you disable simultaneous multithreading, ensure that your capacity planning -accounts for the dramatically decreased machine performance. -==== -|`Enabled` or `Disabled` - -|`compute.name` -|Required if you use `compute`. The name of the machine pool. -|`worker` - -|`compute.platform` -|Required if you use `compute`. Use this parameter to specify the cloud provider to host the worker machines. This parameter value must match the `controlPlane.platform` parameter value. -|`aws`, `azure`, `gcp`, `openstack`, `ovirt`, `vsphere`, or `{}` - -|`compute.replicas` -|The number of compute machines, which are also known as worker machines, to provision. -|A positive integer greater than or equal to `2`. The default value is `3`. - -|`controlPlane` -|The configuration for the machines that comprise the control plane. -|Array of `MachinePool` objects. For details, see the following "Machine-pool" table. - -|`controlPlane.architecture` -|Determines the instruction set architecture of the machines in the pool. Currently, heterogeneous clusters are not supported, so all pools must specify the same architecture. Valid values are `amd64` (the default). -|String - -|`controlPlane.hyperthreading` -|Whether to enable or disable simultaneous multithreading, or `hyperthreading`, on control plane machines. By default, simultaneous multithreading is enabled to increase the performance of your machines' cores. -[IMPORTANT] -==== -If you disable simultaneous multithreading, ensure that your capacity planning -accounts for the dramatically decreased machine performance. -==== -|`Enabled` or `Disabled` - -|`controlPlane.name` -|Required if you use `controlPlane`. The name of the machine pool. -|`master` - -|`controlPlane.platform` -|Required if you use `controlPlane`. Use this parameter to specify the cloud provider that hosts the control plane machines. This parameter value must match the `compute.platform` parameter value. -|`aws`, `azure`, `gcp`, `openstack`, `ovirt`, `vsphere`, or `{}` - -|`controlPlane.replicas` -|The number of control plane machines to provision. -|The only supported value is `3`, which is the default value. - -|`credentialsMode` -|The Cloud Credential Operator (CCO) mode. If no mode is specified, the CCO dynamically tries to determine the capabilities of the provided credentials, with a preference for mint mode on the platforms where multiple modes are supported. -[NOTE] -==== -Not all CCO modes are supported for all cloud providers. For more information on CCO modes, see the _Cloud Credential Operator_ entry in the _Red Hat Operators reference_ content. -==== -|`Mint`, `Passthrough`, `Manual`, or an empty string (`""`). -ifndef::openshift-origin[] -|`fips` -|Enable or disable FIPS mode. The default is `false` (disabled). If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -[NOTE] -==== -If you are using Azure File storage, you cannot enable FIPS mode. -==== -|`false` or `true` -endif::openshift-origin[] -|`imageContentSources` -|Sources and repositories for the release-image content. -|Array of objects. Includes a `source` and, optionally, `mirrors`, as described in the following rows of this table. - -|`imageContentSources.source` -|Required if you use `imageContentSources`. Specify the repository that users refer to, for example, in image pull specifications. -|String - -|`imageContentSources.mirrors` -|Specify one or more repositories that may also contain the same images. -|Array of strings - -|`networking` -|The configuration for the network for the cluster. -|Object - -[NOTE] -==== -You cannot modify parameters specified by the `networking` object after installation. -==== - -|`networking.networkType` -|The default Container Network Interface (CNI) network provider plug-in to install. -ifdef::openshift-origin[] -Either `OpenShiftSDN` or `OVNKubernetes`. The default value is `OVNKubernetes`. -endif::openshift-origin[] -ifndef::openshift-origin[] -Either `OpenShiftSDN` or `OVNKubernetes`. The default value is `OpenShiftSDN`. -endif::openshift-origin[] -|String - -|`networking.clusterNetwork` -|The IP address pools for pods. The default is `10.128.0.0/14` with a host prefix of `/23`. -|Array of objects. For example: - -[source,yaml] ----- -networking: - clusterNetworking: - - cidr: 10.128.0.0/14 - hostPrefix: 23 ----- - -|`networking.clusterNetwork.cidr` -|Required if you use `networking.clusterNetwork`. The IP block address pool. -|IP network. IP networks are represented as strings using Classless Inter-Domain Routing (CIDR) notation with a traditional IP address or network number, followed by the forward slash (`/`) character, followed by a decimal value between `0` and `32` that describes the number of significant bits. For example, `10.0.0.0/16` represents IP addresses `10.0.0.0` through `10.0.255.255`. - -|`networking.clusterNetwork.hostPrefix` -|Required if you use `networking.clusterNetwork`. The prefix size to allocate to each node from the CIDR. For example, `24` would allocate `2^8=256` addresses to each node. -|Integer - -|`networking.serviceNetwork` -|The IP address pools for services. The default is `172.30.0.0/16`. -|Array of IP networks. IP networks are represented as strings using Classless Inter-Domain Routing (CIDR) notation with a traditional IP address or network number, followed by the forward slash (`/`) character, followed by a decimal value between `0` and `32` that describes the number of significant bits. For example, `10.0.0.0/16` represents IP addresses `10.0.0.0` through `10.0.255.255`. - -|`networking.machineNetwork` -|The IP address pools for machines. -|Array of objects - -|`networking.machineNetwork.cidr` -|Required if you use `networking.machineNetwork`. The IP block address pool. The default is `10.0.0.0/16` for all platforms other than libvirt. For libvirt, the default is `192.168.126.0/24`. -|IP network. IP networks are represented as strings using Classless Inter-Domain Routing (CIDR) notation with a traditional IP address or network number, followed by the forward slash (`/`) character, followed by a decimal value between `0` and `32` that describes the number of significant bits. For example, `10.0.0.0/16` represents IP addresses `10.0.0.0` through `10.0.255.255`. - -|`publish` -|How to publish or expose the user-facing endpoints of your cluster, such as the Kubernetes API, OpenShift routes. -|`Internal` or `External`. To deploy a private cluster, which cannot be accessed from the internet, set `publish` to `Internal`. The default value is `External`. - -|`sshKey` -| The SSH key or keys to authenticate access your cluster machines. -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -a|One or more keys. For example: -``` -sshKey: - key1... - key2... - key3... -``` -|==== - - -ifdef::aws[] -.Optional AWS parameters -[cols=".^2,.^3,.^5a",options="header"] -|==== -|Parameter|Description|Values - -|`compute.platform.aws.amiID` -|The AWS AMI used to boot compute machines for the cluster. This is required for regions that require a custom {op-system} AMI. -|Any published or custom {op-system} AMI that belongs to the set AWS region. - -|`compute.platform.aws.rootVolume.iops` -|The Input/Output Operations Per Second (IOPS) that is reserved for the root volume. -|Integer, for example `4000`. - -|`compute.platform.aws.rootVolume.size` -|The size in GiB of the root volume. -|Integer, for example `500`. - -|`compute.platform.aws.rootVolume.type` -|The instance type of the root volume. -|Valid link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html[AWS EBS instance type], -such as `io1`. - -|`compute.platform.aws.type` -|The EC2 instance type for the compute machines. -|Valid link:https://aws.amazon.com/ec2/instance-types/[AWS instance type], such as `c5.9xlarge`. - -|`compute.platform.aws.zones` -|The availability zones where the installation program creates machines for the compute machine pool. If you provide your own VPC, you must provide a subnet in that availability zone. -|A list of valid AWS availability zones, such as `us-east-1c`, in a -link:https://yaml.org/spec/1.2/spec.html#sequence//[YAML sequence]. - -|`compute.aws.region` -|The AWS region that the installation program creates compute resources in. -|Any valid link:https://docs.aws.amazon.com/general/latest/gr/rande.html[AWS region], such as `us-east-1`. - -|`controlPlane.platform.aws.amiID` -|The AWS AMI used to boot control plane machines for the cluster. This is required for regions that require a custom {op-system} AMI. -|Any published or custom {op-system} AMI that belongs to the set AWS region. - -|`controlPlane.platform.aws.type` -|The EC2 instance type for the control plane machines. -|Valid link:https://aws.amazon.com/ec2/instance-types/[AWS instance type], such as `c5.9xlarge`. - -|`controlPlane.platform.aws.zones` -|The availability zones where the installation program creates machines for the -control plane machine pool. -|A list of valid AWS availability zones, such as `us-east-1c`, in a link:https://yaml.org/spec/1.2/spec.html#sequence//[YAML sequence]. - -|`controlPlane.aws.region` -|The AWS region that the installation program creates control plane resources in. -|Valid link:https://docs.aws.amazon.com/general/latest/gr/rande.html[AWS region], such as `us-east-1`. - -|`platform.aws.amiID` -|The AWS AMI used to boot all machines for the cluster. If set, the AMI must -belong to the same region as the cluster. This is required for regions that require a custom {op-system} AMI. -|Any published or custom {op-system} AMI that belongs to the set AWS region. - -|`platform.aws.serviceEndpoints.name` -|The AWS service endpoint name. Custom endpoints are only required for cases -where alternative AWS endpoints, like FIPS, must be used. Custom API endpoints -can be specified for EC2, S3, IAM, Elastic Load Balancing, Tagging, Route 53, -and STS AWS services. -|Valid link:https://docs.aws.amazon.com/general/latest/gr/rande.html[AWS service endpoint] name. - -|`platform.aws.serviceEndpoints.url` -|The AWS service endpoint URL. The URL must use the `https` protocol and the -host must trust the certificate. -|Valid link:https://docs.aws.amazon.com/general/latest/gr/rande.html[AWS service endpoint] URL. - -|`platform.aws.userTags` -|A map of keys and values that the installation program adds as tags to all resources that it creates. -|Any valid YAML map, such as key value pairs in the `<key>: <value>` format. For more information about AWS tags, see link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html[Tagging Your Amazon EC2 Resources] in the AWS documentation. - -|`platform.aws.subnets` -|If you provide the VPC instead of allowing the installation program to create the VPC for you, specify the subnet for the cluster to use. The subnet must be part of the same `machineNetwork[].cidr` ranges that you specify. For a standard cluster, specify a public and a private subnet for each availability zone. For a private cluster, specify a private subnet for each availability zone. -|Valid subnet IDs. - -|==== -endif::aws[] - -ifdef::osp[] -.Additional {rh-openstack-first} parameters -[cols=".^2m,.^3a,^5a",options="header"] -|==== -|Parameter|Description|Values - -|`compute.platform.openstack.rootVolume.size` -|For compute machines, the size in gigabytes of the root volume. If you do not set this value, machines use ephemeral storage. -|Integer, for example `30`. - -|`compute.platform.openstack.rootVolume.type` -|For compute machines, the root volume's type. -|String, for example `performance`. - -|`controlPlane.platform.openstack.rootVolume.size` -|For control plane machines, the size in gigabytes of the root volume. If you do not set this value, machines use ephemeral storage. -|Integer, for example `30`. - -|`controlPlane.platform.openstack.rootVolume.type` -|For control plane machines, the root volume's type. -|String, for example `performance`. - -|`platform.openstack.cloud` -|The name of the {rh-openstack} cloud to use from the list of clouds in the -`clouds.yaml` file. -|String, for example `MyCloud`. - -|`platform.openstack.externalNetwork` -|The {rh-openstack} external network name to be used for installation. -|String, for example `external`. - -|`platform.openstack.computeFlavor` -|The {rh-openstack} flavor to use for control plane and compute machines. - -This property is deprecated. To use a flavor as the default for all machine pools, add it as the value of the `type` key in the `platform.openstack.defaultMachinePlatform` property. You can also set a flavor value for each machine pool individually. - -|String, for example `m1.xlarge`. -|==== - -.Optional {rh-openstack} parameters -[%header, cols=".^2,.^3,.^5a"] -|==== -|Parameter|Description|Values - -|`compute.platform.openstack.additionalNetworkIDs` -|Additional networks that are associated with compute machines. Allowed address pairs are not created for additional networks. -|A list of one or more UUIDs as strings. For example, `fa806b2f-ac49-4bce-b9db-124bc64209bf`. - -|`compute.platform.openstack.additionalSecurityGroupIDs` -|Additional security groups that are associated with compute machines. -|A list of one or more UUIDs as strings. For example, `7ee219f3-d2e9-48a1-96c2-e7429f1b0da7`. - -|`compute.platform.openstack.zones` -|{rh-openstack} Compute (Nova) availability zones (AZs) to install machines on. If this parameter is not set, the installer relies on the default settings for Nova that the {rh-openstack} administrator configured. - -On clusters that use Kuryr, {rh-openstack} Octavia does not support availability zones. Load balancers and, if you are using the Amphora provider driver, {product-title} services that rely on Amphora VMs, are not created according to the value of this property. -|A list of strings. For example, `["zone-1", "zone-2"]`. - -|`controlPlane.platform.openstack.additionalNetworkIDs` -|Additional networks that are associated with control plane machines. Allowed address pairs are not created for additional networks. -|A list of one or more UUIDs as strings. For example, `fa806b2f-ac49-4bce-b9db-124bc64209bf`. - -|`controlPlane.platform.openstack.additionalSecurityGroupIDs` -|Additional security groups that are associated with control plane machines. -|A list of one or more UUIDs as strings. For example, `7ee219f3-d2e9-48a1-96c2-e7429f1b0da7`. - -|`controlPlane.platform.openstack.zones` -|{rh-openstack} Compute (Nova) availability zones (AZs) to install machines on. If this parameter is not set, the installer relies on the default settings for Nova that the {rh-openstack} administrator configured. - -On clusters that use Kuryr, {rh-openstack} Octavia does not support availability zones. Load balancers and, if you are using the Amphora provider driver, {product-title} services that rely on Amphora VMs, are not created according to the value of this property. -|A list of strings. For example, `["zone-1", "zone-2"]`. - -|`platform.openstack.clusterOSImage` -|The location from which the installer downloads the {op-system} image. - -You must set this parameter to perform an installation in a restricted network. -|An HTTP or HTTPS URL, optionally with an SHA-256 checksum. - -For example, `\http://mirror.example.com/images/rhcos-43.81.201912131630.0-openstack.x86_64.qcow2.gz?sha256=ffebbd68e8a1f2a245ca19522c16c86f67f9ac8e4e0c1f0a812b068b16f7265d`. -The value can also be the name of an existing Glance image, for example `my-rhcos`. - -|`platform.openstack.clusterOSImageProperties` -|Properties to add to the installer-uploaded ClusterOSImage in Glance. This property is ignored if `platform.openstack.clusterOSImage` is set to an existing Glance image. - -You can use this property to exceed the default persistent volume (PV) limit for {rh-openstack} of 26 PVs per node. To exceed the limit, set the `hw_scsi_model` property value to `virtio-scsi` and the `hw_disk_bus` value to `scsi`. - -You can also use this property to enable the QEMU guest agent by including the `hw_qemu_guest_agent` property with a value of `yes`. -|A list of key-value string pairs. For example, `["hw_scsi_model": "virtio-scsi", "hw_disk_bus": "scsi"]`. - -|`platform.openstack.defaultMachinePlatform` -|The default machine pool platform configuration. -| -[source,json] ----- -{ - "type": "ml.large", - "rootVolume": { - "size": 30, - "type": "performance" - } -} ----- - -|`platform.openstack.ingressFloatingIP` -|An existing floating IP address to associate with the Ingress port. To use this property, you must also define the `platform.openstack.externalNetwork` property. -|An IP address, for example `128.0.0.1`. - -|`platform.openstack.lbFloatingIP` -|An existing floating IP address to associate with the API load balancer. To use this property, you must also define the `platform.openstack.externalNetwork` property. -|An IP address, for example `128.0.0.1`. - -|`platform.openstack.externalDNS` -|IP addresses for external DNS servers that cluster instances use for DNS resolution. -|A list of IP addresses as strings. For example, `["8.8.8.8", "192.168.1.12"]`. - -|`platform.openstack.machinesSubnet` -|The UUID of a {rh-openstack} subnet that the cluster's nodes use. Nodes and virtual IP (VIP) ports are created on this subnet. - -The first item in `networking.machineNetwork` must match the value of `machinesSubnet`. - -If you deploy to a custom subnet, you cannot specify an external DNS server to the {product-title} installer. Instead, link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.0/html/command_line_interface_reference/subnet[add DNS to the subnet in {rh-openstack}]. - -|A UUID as a string. For example, `fa806b2f-ac49-4bce-b9db-124bc64209bf`. -|==== -endif::osp[] - -ifdef::azure[] -.Additional Azure parameters -[cols=".^2,.^3a,.^3a",options="header"] -|==== -|Parameter|Description|Values - -|`controlPlane.platform.azure.osDisk.diskSizeGB` -|The Azure disk size for the VM. -|Integer that represents the size of the disk in GB. The minimum supported disk size is `1024`. - -|`platform.azure.baseDomainResourceGroupName` -|The name of the resource group that contains the DNS zone for your base domain. -|String, for example `production_cluster`. - -|`platform.azure.outboundType` -|The outbound routing strategy used to connect your cluster to the internet. If -you are using user-defined routing, you must have pre-existing networking -available where the outbound routing has already been configured prior to -installing a cluster. The installation program is not responsible for -configuring user-defined routing. -|`LoadBalancer` or `UserDefinedRouting`. The default is `LoadBalancer`. - -|`platform.azure.region` -|The name of the Azure region that hosts your cluster. -|Any valid region name, such as `centralus`. - -|`platform.azure.zone` -|List of availability zones to place machines in. For high availability, specify -at least two zones. -|List of zones, for example `["1", "2", "3"]`. - -|`platform.azure.networkResourceGroupName` -|The name of the resource group that contains the existing VNet that you want to deploy your cluster to. This name cannot be the same as the `platform.azure.baseDomainResourceGroupName`. -|String. - -|`platform.azure.virtualNetwork` -|The name of the existing VNet that you want to deploy your cluster to. -|String. - -|`platform.azure.controlPlaneSubnet` -|The name of the existing subnet in your VNet that you want to deploy your control plane machines to. -|Valid CIDR, for example `10.0.0.0/16`. - -|`platform.azure.computeSubnet` -|The name of the existing subnet in your VNet that you want to deploy your compute machines to. -|Valid CIDR, for example `10.0.0.0/16`. - -|`platform.azure.cloudName` -|The name of the Azure cloud environment that is used to configure the Azure SDK with the appropriate Azure API endpoints. If empty, the default value `AzurePublicCloud` is used. -|Any valid cloud environment, such as `AzurePublicCloud` or `AzureUSGovernmentCloud`. - -|==== - -[NOTE] -==== -You cannot customize -link:https://azure.microsoft.com/en-us/global-infrastructure/availability-zones/[Azure Availability Zones] -or -link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-using-tags[Use tags to organize your Azure resources] -with an Azure cluster. -==== -endif::azure[] - - -ifdef::gcp[] -.Additional Google Cloud Platform (GCP) parameters -[cols=".^2,.^3a,.^3a",options="header"] -|==== -|Parameter|Description|Values - -|`platform.gcp.network` -|The name of the existing VPC that you want to deploy your cluster to. -|String. - -|`platform.gcp.type` -|The link:https://cloud.google.com/compute/docs/machine-types[GCP machine type]. -|The GCP machine type. - -|`platform.gcp.zones` -|The availability zones where the installation program creates machines for the specified MachinePool. -|A list of valid link:https://cloud.google.com/compute/docs/regions-zones#available[GCP availability zones], such as `us-central1-a`, in a -link:https://yaml.org/spec/1.2/spec.html#sequence//[YAML sequence]. - -|`platform.gcp.controlPlaneSubnet` -|The name of the existing subnet in your VPC that you want to deploy your control plane machines to. -|The subnet name. - -|`platform.gcp.computeSubnet` -|The name of the existing subnet in your VPC that you want to deploy your compute machines to. -|The subnet name. - -|`controlPlane.platform.gcp.osDisk.encryptionKey.kmsKey.name` -|The name of the customer managed encryption key to be used for control plane machine disk encryption. -|The encryption key name. - -|`controlPlane.platform.gcp.osDisk.encryptionKey.kmsKey.keyRing` -|For control plane machines, the name of the KMS key ring to which the KMS key belongs. -|The KMS key ring name. - -|`controlPlane.platform.gcp.osDisk.encryptionKey.kmsKey.location` -|For control plane machines, the GCP location in which the key ring exists. For more information on KMS locations, see Google's documentation on link:https://cloud.google.com/kms/docs/locations[Cloud KMS locations]. -|The GCP location for the key ring. - -|`controlPlane.platform.gcp.osDisk.encryptionKey.kmsKey.projectID` -|For control plane machines, the ID of the project in which the KMS key ring exists. This value defaults to the VM project ID if not set. -|The GCP project ID. - -//// -`controlPlane.platform.gcp.osDisk.encryptionKey.kmsKeyServiceAccount` - -The GCP Compute Engine System service account used for the encryption request for the given KMS key. The Compute Engine default service account is always used for control plane machines during installation, which follows this pattern: `service-<project_number>@compute-system.iam.gserviceaccount.com`. The default service account must have access to the KMS key specified for the control plane machines. The custom service account defined is available for use during post-installation operations. For more information on GCP service accounts, see Google's documentation on link:https://cloud.google.com/iam/docs/service-accounts#types[Types of service accounts]. - -The GCP Compute Engine System service account email, like `<service_account_name>@<project_id>.iam.gserviceaccount.com`. -//// -// kmsKeyServiceAccount not yet fully supported in 4.7. Re-add when more stable. - -|`compute.platform.gcp.osDisk.encryptionKey.kmsKey.name` -|The name of the customer managed encryption key to be used for compute machine disk encryption. -|The encryption key name. - -|`compute.platform.gcp.osDisk.encryptionKey.kmsKey.keyRing` -|For compute machines, the name of the KMS key ring to which the KMS key belongs. -|The KMS key ring name. - -|`compute.platform.gcp.osDisk.encryptionKey.kmsKey.location` -|For compute machines, the GCP location in which the key ring exists. For more information on KMS locations, see Google's documentation on link:https://cloud.google.com/kms/docs/locations[Cloud KMS locations]. -|The GCP location for the key ring. - -|`compute.platform.gcp.osDisk.encryptionKey.kmsKey.projectID` -|For compute machines, the ID of the project in which the KMS key ring exists. This value defaults to the VM project ID if not set. -|The GCP project ID. - -//// -`compute.platform.gcp.osDisk.encryptionKey.kmsKeyServiceAccount` - -For compute machines, the GCP Compute Engine System service account used for the encryption request for the given KMS key. If left undefined, the Compute Engine default service account is used, which follows this pattern: `service-<project_number>@compute-system.iam.gserviceaccount.com`. For more information on GCP service accounts, see Google's documentation on link:https://cloud.google.com/iam/docs/service-accounts#types[Types of service accounts]. - -The GCP Compute Engine System service account email, like `<service_account_name>@<project_id>.iam.gserviceaccount.com`. -//// -// kmsKeyServiceAccount not yet fully supported in 4.7. Re-add when more stable. -|==== - -endif::gcp[] - -ifdef::rhv[] - -.Additional {rh-virtualization-first} parameters for clusters -[cols=".^2,.^3a,.^3a",options="header"] -|==== -|Parameter|Description|Values - -|`platform.ovirt.ovirt_cluster_id` -|Required. The Cluster where the VMs will be created. -|String. For example: `68833f9f-e89c-4891-b768-e2ba0815b76b` - -|`platform.ovirt.ovirt_storage_domain_id` -|Required. The Storage Domain ID where the VM disks will be created. -|String. For example: `ed7b0f4e-0e96-492a-8fff-279213ee1468` - -|`platform.ovirt.ovirt_network_name` -|Required. The network name where the VM nics will be created. -|String. For example: `ocpcluster` - -|`platform.ovirt.vnicProfileID` -|Required. The vNIC profile ID of the VM network interfaces. This can be inferred if the cluster network has a single profile. -|String. For example: `3fa86930-0be5-4052-b667-b79f0a729692` - -|`platform.ovirt.api_vip` -|Required. An IP address on the machine network that will be assigned to the API virtual IP (VIP). You can access the OpenShift API at this endpoint. -|String. Example: `10.46.8.230` - -|`platform.ovirt.ingress_vip` -|Required. An IP address on the machine network that will be assigned to the Ingress virtual IP (VIP). -|String. Example: `10.46.8.232` -|==== - - -.Additional {rh-virtualization} parameters for machine pools -[cols=".^2,.^3a,.^3a",options="header"] -|==== -|Parameter|Description|Values - -|`<machine-pool>.platform.ovirt.cpu` -|Optional. Defines the CPU of the VM. -|Object - -|`<machine-pool>.platform.ovirt.cpu.cores` -|Required if you use `<machine-pool>.platform.ovirt.cpu`. The number of cores. Total virtual CPUs (vCPUs) is cores * sockets. -|Integer - -|`<machine-pool>.platform.ovirt.cpu.sockets` -|Required if you use `<machine-pool>.platform.ovirt.cpu`. The number of sockets per core. Total virtual CPUs (vCPUs) is cores * sockets. -|Integer - -|`<machine-pool>.platform.ovirt.memoryMB` -|Optional. Memory of the VM in MiB. -|Integer - -|`<machine-pool>.platform.ovirt.instanceTypeID` -|Optional. An instance type UUID, such as `00000009-0009-0009-0009-0000000000f1`, which you can get from the `https://<engine-fqdn>/ovirt-engine/api/instancetypes` endpoint. -|String of UUID - -|`<machine-pool>.platform.ovirt.osDisk` -|Optional. Defines the first and bootable disk of the VM. -|String - -|`<machine-pool>.platform.ovirt.osDisk.sizeGB` -|Required if you use `<machine-pool>.platform.ovirt.osDisk`. Size of the disk in GiB. -|Number - -|`<machine-pool>.platform.ovirt.vmType` -|Optional. The VM workload type, such as `high-performance`, `server`, or `desktop`. -|String -|==== - -[NOTE] -==== -You can replace `<machine-pool>` with `controlPlane` or `compute`. -==== - -endif::rhv[] - -ifdef::vsphere,vmc[] -.Additional VMware vSphere cluster parameters -[cols=".^2,.^3a,.^3a",options="header"] -|==== -|Parameter|Description|Values - -|`platform.vsphere.vCenter` -|The fully-qualified host name or IP address of the vCenter server. -|String - -|`platform.vsphere.username` -|The user name to use to connect to the vCenter instance with. This user must have at least -the roles and privileges that are required for -link:https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/vcp-roles.html[static or dynamic persistent volume provisioning] -in vSphere. -|String - -|`platform.vsphere.password` -|The password for the vCenter user name. -|String - -|`platform.vsphere.datacenter` -|The name of the datacenter to use in the vCenter instance. -|String - -|`platform.vsphere.defaultDatastore` -|The name of the default datastore to use for provisioning volumes. -|String - -|`platform.vsphere.folder` -|_Optional_. The absolute path of an existing folder where the installation program creates the virtual machines. If you do not provide this value, the installation program creates a folder that is named with the infrastructure ID in the datacenter virtual machine folder. -|String, for example, `/<datacenter_name>/vm/<folder_name>/<subfolder_name>`. - -|`platform.vsphere.network` -|The network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured. -|String - -|`platform.vsphere.cluster` -|The vCenter cluster to install the {product-title} cluster in. -|String - -|`platform.vsphere.apiVIP` -|The virtual IP (VIP) address that you configured for control plane API access. -|An IP address, for example `128.0.0.1`. - -|`platform.vsphere.ingressVIP` -|The virtual IP (VIP) address that you configured for cluster ingress. -|An IP address, for example `128.0.0.1`. -|==== - -.Optional VMware vSphere machine pool parameters -[cols=".^2,.^3a,.^3a",options="header"] -|==== -|Parameter|Description|Values - -|`platform.vsphere.clusterOSImage` -|The location from which the installer downloads the {op-system} image. You must set this parameter to perform an installation in a restricted network. -|An HTTP or HTTPS URL, optionally with a SHA-256 checksum. For example, `\https://mirror.openshift.com/images/rhcos-<version>-vmware.<architecture>.ova`. - -|`platform.vsphere.osDisk.diskSizeGB` -|The size of the disk in gigabytes. -|Integer - -|`platform.vsphere.cpus` -|The total number of virtual processor cores to assign a virtual machine. -|Integer - -|`platform.vsphere.coresPerSocket` -|The number of cores per socket in a virtual machine. The number of virtual CPUs (vCPUs) on the virtual machine is `platform.vsphere.cpus`/`platform.vsphere.coresPerSocket`. The default value is `1` -|Integer - -|`platform.vsphere.memoryMB` -|The size of a virtual machine's memory in megabytes. -|Integer -|==== - -endif::vsphere,vmc[] - -ifeval::["{context}" == "installing-aws-customizations"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-government-region"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-network-customizations"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-private"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-vpc"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-azure-customizations"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-government-region"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-network-customizations"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-private"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-vnet"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-gcp-customizations"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-private"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-network-customizations"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-vpc"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-aws-customizations"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-custom"] -:!osp: -:!osp-custom: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:!osp: -:!osp-kuryr: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:!osp: -:!osp-custom: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:!osp: -:!osp-kuryr: -endif::[] -ifeval::["{context}" == "installing-rhv-customizations"] -:!rhv: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"] -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-customizations"] -:!vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:!vmc: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:!osp: -:!osp-custom: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:!vsphere: -endif::[] diff --git a/modules/installation-configure-proxy.adoc b/modules/installation-configure-proxy.adoc deleted file mode 100644 index 467451ff8bca..000000000000 --- a/modules/installation-configure-proxy.adoc +++ /dev/null @@ -1,146 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * networking/configuring-a-custom-pki.adoc -// * installing/installing-rhv-restricted-network.adoc - -ifeval::["{context}" == "installing-bare-metal"] -:bare-metal: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:bare-metal: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-user-infra"] -:vmc: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:vmc: -endif::[] - -[id="installation-configure-proxy_{context}"] -= Configuring the cluster-wide proxy during installation - -Production environments can deny direct access to the Internet and instead have -an HTTP or HTTPS proxy available. You can configure a new {product-title} -cluster to use a proxy by configuring the proxy settings in the -`install-config.yaml` file. - -ifdef::bare-metal[] -[NOTE] -==== -For bare metal installations, if you do not assign node IP addresses from the -range that is specified in the `networking.machineNetwork[].cidr` field in the -`install-config.yaml` file, you must include them in the `proxy.noProxy` field. -==== -endif::bare-metal[] - -.Prerequisites - -* You have an existing `install-config.yaml` file. -// TODO: xref (../../installing/install_config/configuring-firewall.adoc#configuring-firewall) -* You reviewed the sites that your cluster requires access to and determined whether any of them need to bypass the proxy. By default, all cluster egress traffic is proxied, including calls to hosting cloud provider APIs. You added sites to the `Proxy` object's `spec.noProxy` field to bypass the proxy if necessary. -+ -[NOTE] -==== -The `Proxy` object `status.noProxy` field is populated with the values of the `networking.machineNetwork[].cidr`, `networking.clusterNetwork[].cidr`, and `networking.serviceNetwork[]` fields from your installation configuration. - -For installations on Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure, and {rh-openstack-first}, the `Proxy` object `status.noProxy` field is also populated with the instance metadata endpoint (`169.254.169.254`). -==== - -.Procedure - -. Edit your `install-config.yaml` file and add the proxy settings. For example: -+ -[source,yaml] ----- -apiVersion: v1 -baseDomain: my.domain.com -proxy: - httpProxy: http://<username>:<pswd>@<ip>:<port> <1> - httpsProxy: http://<username>:<pswd>@<ip>:<port> <2> - noProxy: example.com <3> -additionalTrustBundle: | <4> - -----BEGIN CERTIFICATE----- - <MY_TRUSTED_CA_CERT> - -----END CERTIFICATE----- -... ----- -<1> A proxy URL to use for creating HTTP connections outside the cluster. The -URL scheme must be `http`. If you use an MITM transparent proxy network that does not require additional proxy configuration but requires additional CAs, you must not specify an `httpProxy` value. -<2> A proxy URL to use for creating HTTPS connections outside the cluster. If -this field is not specified, then `httpProxy` is used for both HTTP and HTTPS -connections. -If you use an MITM transparent proxy network that does not require additional proxy configuration but requires additional CAs, you must not specify an `httpsProxy` value. -<3> A comma-separated list of destination domain names, domains, IP addresses, or -other network CIDRs to exclude proxying. Preface a domain with `.` to match subdomains only. For example, `.y.com` matches `x.y.com`, but not `y.com`. Use `*` to bypass proxy for all destinations. -ifdef::vsphere,vmc[] -You must include vCenter's IP address and the IP range that you use for its machines. -endif::vsphere,vmc[] -<4> If provided, the installation program generates a config map that is named `user-ca-bundle` in -the `openshift-config` namespace that contains one or more additional CA -certificates that are required for proxying HTTPS connections. The Cluster Network -Operator then creates a `trusted-ca-bundle` config map that merges these contents -with the {op-system-first} trust bundle, and this config map is referenced in the `Proxy` -object's `trustedCA` field. The `additionalTrustBundle` field is required unless -the proxy's identity certificate is signed by an authority from the {op-system} trust -bundle. -If you use an MITM transparent proxy network that does not require additional proxy configuration but requires additional CAs, you must provide the MITM CA certificate. -+ -[NOTE] -==== -The installation program does not support the proxy `readinessEndpoints` field. -==== - -. Save the file and reference it when installing {product-title}. - -The installation program creates a cluster-wide proxy that is named `cluster` that uses the proxy -settings in the provided `install-config.yaml` file. If no proxy settings are -provided, a `cluster` `Proxy` object is still created, but it will have a nil -`spec`. - -[NOTE] -==== -Only the `Proxy` object named `cluster` is supported, and no additional -proxies can be created. -==== - -ifeval::["{context}" == "installing-bare-metal"] -:!bare-metal: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!bare-metal: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-user-infra"] -:!vmc: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!vmc: -endif::[] diff --git a/modules/installation-create-ingress-dns-records.adoc b/modules/installation-create-ingress-dns-records.adoc deleted file mode 100644 index e8388f2ba22e..000000000000 --- a/modules/installation-create-ingress-dns-records.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-create-ingress-dns-records_{context}"] -= Creating the Ingress DNS Records - -If you removed the DNS Zone configuration, manually create DNS records that point to the Ingress load balancer. -You can create either a wildcard record or specific records. While the following procedure uses A records, you can use other record types that you require, such as CNAME or alias. - -.Prerequisites - -* You deployed an {product-title} cluster on Amazon Web Services (AWS) that uses infrastructure that you provisioned. -* You installed the OpenShift CLI (`oc`). -* You installed the `jq` package. -* You downloaded the AWS CLI and installed it on your computer. See -link:https://docs.aws.amazon.com/cli/latest/userguide/install-bundle.html[Install the AWS CLI Using the Bundled Installer (Linux, macOS, or Unix)]. - -.Procedure - -. Determine the routes to create. -** To create a wildcard record, use `*.apps.<cluster_name>.<domain_name>`, where `<cluster_name>` is your cluster name, and `<domain_name>` is the Route 53 base domain for your {product-title} cluster. -** To create specific records, you must create a record for each route that your cluster uses, as shown in the output of the following command: -+ -[source,terminal] ----- -$ oc get --all-namespaces -o jsonpath='{range .items[*]}{range .status.ingress[*]}{.host}{"\n"}{end}{end}' routes ----- -+ -.Example output -[source,terminal] ----- -oauth-openshift.apps.<cluster_name>.<domain_name> -console-openshift-console.apps.<cluster_name>.<domain_name> -downloads-openshift-console.apps.<cluster_name>.<domain_name> -alertmanager-main-openshift-monitoring.apps.<cluster_name>.<domain_name> -grafana-openshift-monitoring.apps.<cluster_name>.<domain_name> -prometheus-k8s-openshift-monitoring.apps.<cluster_name>.<domain_name> ----- - -. Retrieve the Ingress Operator load balancer status and note the value of the external IP address that it uses, which is shown in the `EXTERNAL-IP` column: -+ -[source,terminal] ----- -$ oc -n openshift-ingress get service router-default ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -router-default LoadBalancer 172.30.62.215 ab3...28.us-east-2.elb.amazonaws.com 80:31499/TCP,443:30693/TCP 5m ----- - -. Locate the hosted zone ID for the load balancer: -+ -[source,terminal] ----- -$ aws elb describe-load-balancers | jq -r '.LoadBalancerDescriptions[] | select(.DNSName == "<external_ip>").CanonicalHostedZoneNameID' <1> ----- -<1> For `<external_ip>`, specify the value of the external IP address of the Ingress Operator load balancer that you obtained. -+ -.Example output -[source,terminal] ----- -Z3AADJGX6KTTL2 ----- - -+ -The output of this command is the load balancer hosted zone ID. - -. Obtain the public hosted zone ID for your cluster's domain: -+ -[source,terminal] ----- -$ aws route53 list-hosted-zones-by-name \ - --dns-name "<domain_name>" \ <1> - --query 'HostedZones[? Config.PrivateZone != `true` && Name == `<domain_name>.`].Id' <1> - --output text ----- -<1> For `<domain_name>`, specify the Route 53 base domain for your {product-title} cluster. -+ -.Example output -[source,terminal] ----- -/hostedzone/Z3URY6TWQ91KVV ----- -+ -The public hosted zone ID for your domain is shown in the command output. In this example, it is `Z3URY6TWQ91KVV`. - -. Add the alias records to your private zone: -+ -[source,terminal] ----- -$ aws route53 change-resource-record-sets --hosted-zone-id "<private_hosted_zone_id>" --change-batch '{ <1> -> "Changes": [ -> { -> "Action": "CREATE", -> "ResourceRecordSet": { -> "Name": "\\052.apps.<cluster_domain>", <2> -> "Type": "A", -> "AliasTarget":{ -> "HostedZoneId": "<hosted_zone_id>", <3> -> "DNSName": "<external_ip>.", <4> -> "EvaluateTargetHealth": false -> } -> } -> } -> ] -> }' ----- -<1> For `<private_hosted_zone_id>`, specify the value from the output of the CloudFormation template for DNS and load balancing. -<2> For `<cluster_domain>`, specify the domain or subdomain that you use with your {product-title} cluster. -<3> For `<hosted_zone_id>`, specify the public hosted zone ID for the load balancer that you obtained. -<4> For `<external_ip>`, specify the value of the external IP address of the Ingress Operator load balancer. Ensure that you include the trailing period (`.`) in this parameter value. - -. Add the records to your public zone: -+ -[source,terminal] ----- -$ aws route53 change-resource-record-sets --hosted-zone-id "<public_hosted_zone_id>"" --change-batch '{ <1> -> "Changes": [ -> { -> "Action": "CREATE", -> "ResourceRecordSet": { -> "Name": "\\052.apps.<cluster_domain>", <2> -> "Type": "A", -> "AliasTarget":{ -> "HostedZoneId": "<hosted_zone_id>", <3> -> "DNSName": "<external_ip>.", <4> -> "EvaluateTargetHealth": false -> } -> } -> } -> ] -> }' ----- -<1> For `<public_hosted_zone_id>`, specify the public hosted zone for your domain. -<2> For `<cluster_domain>`, specify the domain or subdomain that you use with your {product-title} cluster. -<3> For `<hosted_zone_id>`, specify the public hosted zone ID for the load balancer that you obtained. -<4> For `<external_ip>`, specify the value of the external IP address of the Ingress Operator load balancer. Ensure that you include the trailing period (`.`) in this parameter value. diff --git a/modules/installation-creating-aws-bootstrap.adoc b/modules/installation-creating-aws-bootstrap.adoc deleted file mode 100644 index f6fcf8527888..000000000000 --- a/modules/installation-creating-aws-bootstrap.adoc +++ /dev/null @@ -1,231 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-creating-aws-bootstrap_{context}"] -= Creating the bootstrap node in AWS - -You must create the bootstrap node in Amazon Web Services (AWS) to use during {product-title} cluster initialization. - -You can use the provided CloudFormation template and a custom parameter file to create a stack of AWS resources. The stack represents the bootstrap node that your {product-title} installation requires. - -[NOTE] -==== -If you do not use the provided CloudFormation template to create your bootstrap -node, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* You configured an AWS account. -* You added your AWS keys and region to your local AWS profile by running `aws configure`. -* You generated the Ignition config files for your cluster. -* You created and configured a VPC and associated subnets in AWS. -* You created and configured DNS, load balancers, and listeners in AWS. -* You created the security groups and roles required for your cluster in AWS. - -.Procedure - -. Provide a location to serve the `bootstrap.ign` Ignition config file to your -cluster. This file is located in your installation directory. One way to do this -is to create an S3 bucket in your cluster's region and upload the Ignition -config file to it. -+ -[IMPORTANT] -==== -The provided CloudFormation Template assumes that the -Ignition config files for your cluster are served from an S3 bucket. If you -choose to serve the files from another location, you must modify the templates. -==== -+ -[IMPORTANT] -==== -If you are deploying to a region that has endpoints that differ from the AWS SDK, or you are providing your own custom endpoints, you must use a presigned URL for your S3 bucket instead of the `s3://` schema. -==== -+ -[NOTE] -==== -The bootstrap Ignition config file does contain secrets, like X.509 keys. The -following steps provide basic security for the S3 bucket. To provide additional -security, you can enable an S3 bucket policy to allow only certain users, such -as the OpenShift IAM user, to access objects that the bucket contains. You -can avoid S3 entirely and serve your bootstrap Ignition config file from any -address that the bootstrap machine can reach. -==== - -.. Create the bucket: -+ -[source,terminal] ----- -$ aws s3 mb s3://<cluster-name>-infra <1> ----- -<1> `<cluster-name>-infra` is the bucket name. When creating the `install-config.yaml` file, replace `<cluster-name>` with the name specified for the cluster. - -.. Upload the `bootstrap.ign` Ignition config file to the bucket: -+ -[source,terminal] ----- -$ aws s3 cp <installation_directory>/bootstrap.ign s3://<cluster-name>-infra/bootstrap.ign <1> ----- -<1> For `<installation_directory>`, specify the path to the directory that you stored the installation files in. - -.. Verify that the file uploaded: -+ -[source,terminal] ----- -$ aws s3 ls s3://<cluster-name>-infra/ ----- -+ -.Example output -[source,terminal] ----- -2019-04-03 16:15:16 314878 bootstrap.ign ----- - -. Create a JSON file that contains the parameter values that the template -requires: -+ -[source,json] ----- -[ - { - "ParameterKey": "InfrastructureName", <1> - "ParameterValue": "mycluster-<random_string>" <2> - }, - { - "ParameterKey": "RhcosAmi", <3> - "ParameterValue": "ami-<random_string>" <4> - }, - { - "ParameterKey": "AllowedBootstrapSshCidr", <5> - "ParameterValue": "0.0.0.0/0" <6> - }, - { - "ParameterKey": "PublicSubnet", <7> - "ParameterValue": "subnet-<random_string>" <8> - }, - { - "ParameterKey": "MasterSecurityGroupId", <9> - "ParameterValue": "sg-<random_string>" <10> - }, - { - "ParameterKey": "VpcId", <11> - "ParameterValue": "vpc-<random_string>" <12> - }, - { - "ParameterKey": "BootstrapIgnitionLocation", <13> - "ParameterValue": "s3://<bucket_name>/bootstrap.ign" <14> - }, - { - "ParameterKey": "AutoRegisterELB", <15> - "ParameterValue": "yes" <16> - }, - { - "ParameterKey": "RegisterNlbIpTargetsLambdaArn", <17> - "ParameterValue": "arn:aws:lambda:<region>:<account_number>:function:<dns_stack_name>-RegisterNlbIpTargets-<random_string>" <18> - }, - { - "ParameterKey": "ExternalApiTargetGroupArn", <19> - "ParameterValue": "arn:aws:elasticloadbalancing:<region>:<account_number>:targetgroup/<dns_stack_name>-Exter-<random_string>" <20> - }, - { - "ParameterKey": "InternalApiTargetGroupArn", <21> - "ParameterValue": "arn:aws:elasticloadbalancing:<region>:<account_number>:targetgroup/<dns_stack_name>-Inter-<random_string>" <22> - }, - { - "ParameterKey": "InternalServiceTargetGroupArn", <23> - "ParameterValue": "arn:aws:elasticloadbalancing:<region>:<account_number>:targetgroup/<dns_stack_name>-Inter-<random_string>" <24> - } -] - ----- -<1> The name for your cluster infrastructure that is encoded in your Ignition -config files for the cluster. -<2> Specify the infrastructure name that you extracted from the Ignition config -file metadata, which has the format `<cluster-name>-<random-string>`. -<3> Current {op-system-first} AMI to use for the bootstrap node. -<4> Specify a valid `AWS::EC2::Image::Id` value. -<5> CIDR block to allow SSH access to the bootstrap node. -<6> Specify a CIDR block in the format `x.x.x.x/16-24`. -<7> The public subnet that is associated with your VPC to launch the bootstrap -node into. -<8> Specify the `PublicSubnetIds` value from the output of the CloudFormation -template for the VPC. -<9> The master security group ID (for registering temporary rules) -<10> Specify the `MasterSecurityGroupId` value from the output of the -CloudFormation template for the security group and roles. -<11> The VPC created resources will belong to. -<12> Specify the `VpcId` value from the output of the CloudFormation template -for the VPC. -<13> Location to fetch bootstrap Ignition config file from. -<14> Specify the S3 bucket and file name in the form -`s3://<bucket_name>/bootstrap.ign`. -<15> Whether or not to register a network load balancer (NLB). -<16> Specify `yes` or `no`. If you specify `yes`, you must provide a Lambda -Amazon Resource Name (ARN) value. -<17> The ARN for NLB IP target registration lambda group. -<18> Specify the `RegisterNlbIpTargetsLambda` value from the output of the -CloudFormation template for DNS and load balancing. Use `arn:aws-us-gov` if -deploying the cluster to an AWS GovCloud region. -<19> The ARN for external API load balancer target group. -<20> Specify the `ExternalApiTargetGroupArn` value from the output of the -CloudFormation template for DNS and load balancing. Use `arn:aws-us-gov` if -deploying the cluster to an AWS GovCloud region. -<21> The ARN for internal API load balancer target group. -<22> Specify the `InternalApiTargetGroupArn` value from the output of the -CloudFormation template for DNS and load balancing. Use `arn:aws-us-gov` if -deploying the cluster to an AWS GovCloud region. -<23> The ARN for internal service load balancer target group. -<24> Specify the `InternalServiceTargetGroupArn` value from the output of the -CloudFormation template for DNS and load balancing. Use `arn:aws-us-gov` if -deploying the cluster to an AWS GovCloud region. - -. Copy the template from the *CloudFormation template for the bootstrap machine* -section of this topic and save it as a YAML file on your computer. This template -describes the bootstrap machine that your cluster requires. - -. Launch the CloudFormation template to create a stack of AWS resources that represent the bootstrap node: -+ -[IMPORTANT] -==== -You must enter the command on a single line. -==== -+ -[source,terminal] ----- -$ aws cloudformation create-stack --stack-name <name> <1> - --template-body file://<template>.yaml <2> - --parameters file://<parameters>.json <3> - --capabilities CAPABILITY_NAMED_IAM <4> ----- -<1> `<name>` is the name for the CloudFormation stack, such as `cluster-bootstrap`. -You need the name of this stack if you remove the cluster. -<2> `<template>` is the relative path to and name of the CloudFormation template -YAML file that you saved. -<3> `<parameters>` is the relative path to and name of the CloudFormation -parameters JSON file. -<4> You must explicitly declare the `CAPABILITY_NAMED_IAM` capability because the provided template creates some `AWS::IAM::Role` and `AWS::IAM::InstanceProfile` resources. -+ -.Example output -[source,terminal] ----- -arn:aws:cloudformation:us-east-1:269333783861:stack/cluster-bootstrap/12944486-2add-11eb-9dee-12dace8e3a83 ----- - -. Confirm that the template components exist: -+ -[source,terminal] ----- -$ aws cloudformation describe-stacks --stack-name <name> ----- -+ -After the `StackStatus` displays `CREATE_COMPLETE`, the output displays values -for the following parameters. You must provide these parameter values to -the other CloudFormation templates that you run to create your cluster: -[horizontal] -`BootstrapInstanceId`:: The bootstrap Instance ID. -`BootstrapPublicIp`:: The bootstrap node public IP address. -`BootstrapPrivateIp`:: The bootstrap node private IP address. diff --git a/modules/installation-creating-aws-control-plane.adoc b/modules/installation-creating-aws-control-plane.adoc deleted file mode 100644 index f647f79c9a8c..000000000000 --- a/modules/installation-creating-aws-control-plane.adoc +++ /dev/null @@ -1,243 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-creating-aws-control-plane_{context}"] -= Creating the control plane machines in AWS - -You must create the control plane machines in Amazon Web Services (AWS) that your cluster will use. - -You can use the provided CloudFormation template and a custom parameter file to create a stack of AWS resources that represent the control plane nodes. - -[IMPORTANT] -==== -The CloudFormation template creates a stack that represents three control plane nodes. -==== - -[NOTE] -==== -If you do not use the provided CloudFormation template to create your control plane -nodes, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* You configured an AWS account. -* You added your AWS keys and region to your local AWS profile by running `aws configure`. -* You generated the Ignition config files for your cluster. -* You created and configured a VPC and associated subnets in AWS. -* You created and configured DNS, load balancers, and listeners in AWS. -* You created the security groups and roles required for your cluster in AWS. -* You created the bootstrap machine. - -.Procedure - -. Create a JSON file that contains the parameter values that the template -requires: -+ -[source,json] ----- -[ - { - "ParameterKey": "InfrastructureName", <1> - "ParameterValue": "mycluster-<random_string>" <2> - }, - { - "ParameterKey": "RhcosAmi", <3> - "ParameterValue": "ami-<random_string>" <4> - }, - { - "ParameterKey": "AutoRegisterDNS", <5> - "ParameterValue": "yes" <6> - }, - { - "ParameterKey": "PrivateHostedZoneId", <7> - "ParameterValue": "<random_string>" <8> - }, - { - "ParameterKey": "PrivateHostedZoneName", <9> - "ParameterValue": "mycluster.example.com" <10> - }, - { - "ParameterKey": "Master0Subnet", <11> - "ParameterValue": "subnet-<random_string>" <12> - }, - { - "ParameterKey": "Master1Subnet", <11> - "ParameterValue": "subnet-<random_string>" <12> - }, - { - "ParameterKey": "Master2Subnet", <11> - "ParameterValue": "subnet-<random_string>" <12> - }, - { - "ParameterKey": "MasterSecurityGroupId", <13> - "ParameterValue": "sg-<random_string>" <14> - }, - { - "ParameterKey": "IgnitionLocation", <15> - "ParameterValue": "https://api-int.<cluster_name>.<domain_name>:22623/config/master" <16> - }, - { - "ParameterKey": "CertificateAuthorities", <17> - "ParameterValue": "data:text/plain;charset=utf-8;base64,ABC...xYz==" <18> - }, - { - "ParameterKey": "MasterInstanceProfileName", <19> - "ParameterValue": "<roles_stack>-MasterInstanceProfile-<random_string>" <20> - }, - { - "ParameterKey": "MasterInstanceType", <21> - "ParameterValue": "m4.xlarge" <22> - }, - { - "ParameterKey": "AutoRegisterELB", <23> - "ParameterValue": "yes" <24> - }, - { - "ParameterKey": "RegisterNlbIpTargetsLambdaArn", <25> - "ParameterValue": "arn:aws:lambda:<region>:<account_number>:function:<dns_stack_name>-RegisterNlbIpTargets-<random_string>" <26> - }, - { - "ParameterKey": "ExternalApiTargetGroupArn", <27> - "ParameterValue": "arn:aws:elasticloadbalancing:<region>:<account_number>:targetgroup/<dns_stack_name>-Exter-<random_string>" <28> - }, - { - "ParameterKey": "InternalApiTargetGroupArn", <29> - "ParameterValue": "arn:aws:elasticloadbalancing:<region>:<account_number>:targetgroup/<dns_stack_name>-Inter-<random_string>" <30> - }, - { - "ParameterKey": "InternalServiceTargetGroupArn", <31> - "ParameterValue": "arn:aws:elasticloadbalancing:<region>:<account_number>:targetgroup/<dns_stack_name>-Inter-<random_string>" <32> - } -] ----- -<1> The name for your cluster infrastructure that is encoded in your Ignition -config files for the cluster. -<2> Specify the infrastructure name that you extracted from the Ignition config -file metadata, which has the format `<cluster-name>-<random-string>`. -<3> Current{op-system-first} AMI to use for the control plane machines. -<4> Specify an `AWS::EC2::Image::Id` value. -<5> Whether or not to perform DNS etcd registration. -<6> Specify `yes` or `no`. If you specify `yes`, you must provide hosted zone -information. -<7> The Route 53 private zone ID to register the etcd targets with. -<8> Specify the `PrivateHostedZoneId` value from the output of the -CloudFormation template for DNS and load balancing. -<9> The Route 53 zone to register the targets with. -<10> Specify `<cluster_name>.<domain_name>` where `<domain_name>` is the Route 53 -base domain that you used when you generated `install-config.yaml` file for the -cluster. Do not include the trailing period (.) that is -displayed in the AWS console. -<11> A subnet, preferably private, to launch the control plane machines on. -<12> Specify a subnet from the `PrivateSubnets` value from the output of the -CloudFormation template for DNS and load balancing. -<13> The master security group ID to associate with master nodes. -<14> Specify the `MasterSecurityGroupId` value from the output of the -CloudFormation template for the security group and roles. -<15> The location to fetch control plane Ignition config file from. -<16> Specify the generated Ignition config file location, -`https://api-int.<cluster_name>.<domain_name>:22623/config/master`. -<17> The base64 encoded certificate authority string to use. -<18> Specify the value from the `master.ign` file that is in the installation -directory. This value is the long string with the format -`data:text/plain;charset=utf-8;base64,ABC...xYz==`. -<19> The IAM profile to associate with master nodes. -<20> Specify the `MasterInstanceProfile` parameter value from the output of -the CloudFormation template for the security group and roles. -<21> The type of AWS instance to use for the control plane machines. -<22> Allowed values: -* `m4.xlarge` -* `m4.2xlarge` -* `m4.4xlarge` -* `m4.8xlarge` -* `m4.10xlarge` -* `m4.16xlarge` -* `m5.xlarge` -* `m5.2xlarge` -* `m5.4xlarge` -* `m5.8xlarge` -* `m5.10xlarge` -* `m5.16xlarge` -* `c4.2xlarge` -* `c4.4xlarge` -* `c4.8xlarge` -* `r4.xlarge` -* `r4.2xlarge` -* `r4.4xlarge` -* `r4.8xlarge` -* `r4.16xlarge` -+ -[IMPORTANT] -==== -If `m4` instance types are not available in your region, such as with -`eu-west-3`, specify an `m5` type, such as `m5.xlarge`, instead. -==== -<23> Whether or not to register a network load balancer (NLB). -<24> Specify `yes` or `no`. If you specify `yes`, you must provide a Lambda -Amazon Resource Name (ARN) value. -<25> The ARN for NLB IP target registration lambda group. -<26> Specify the `RegisterNlbIpTargetsLambda` value from the output of the CloudFormation template for DNS -and load balancing. Use `arn:aws-us-gov` if deploying the cluster to an AWS -GovCloud region. -<27> The ARN for external API load balancer target group. -<28> Specify the `ExternalApiTargetGroupArn` value from the output of the CloudFormation template for DNS -and load balancing. Use `arn:aws-us-gov` if deploying the cluster to an AWS -GovCloud region. -<29> The ARN for internal API load balancer target group. -<30> Specify the `InternalApiTargetGroupArn` value from the output of the CloudFormation template for DNS -and load balancing. Use `arn:aws-us-gov` if deploying the cluster to an AWS -GovCloud region. -<31> The ARN for internal service load balancer target group. -<32> Specify the `InternalServiceTargetGroupArn` value from the output of the CloudFormation template for DNS -and load balancing. Use `arn:aws-us-gov` if deploying the cluster to an AWS -GovCloud region. - -. Copy the template from the *CloudFormation template for control plane machines* -section of this topic and save it as a YAML file on your computer. This template -describes the control plane machines that your cluster requires. - -. If you specified an `m5` instance type as the value for `MasterInstanceType`, -add that instance type to the `MasterInstanceType.AllowedValues` parameter -in the CloudFormation template. - -. Launch the CloudFormation template to create a stack of AWS resources that represent the control plane nodes: -+ -[IMPORTANT] -==== -You must enter the command on a single line. -==== -+ -[source,terminal] ----- -$ aws cloudformation create-stack --stack-name <name> <1> - --template-body file://<template>.yaml <2> - --parameters file://<parameters>.json <3> ----- -<1> `<name>` is the name for the CloudFormation stack, such as `cluster-control-plane`. -You need the name of this stack if you remove the cluster. -<2> `<template>` is the relative path to and name of the CloudFormation template -YAML file that you saved. -<3> `<parameters>` is the relative path to and name of the CloudFormation -parameters JSON file. -+ -.Example output -[source,terminal] ----- -arn:aws:cloudformation:us-east-1:269333783861:stack/cluster-control-plane/21c7e2b0-2ee2-11eb-c6f6-0aa34627df4b ----- -+ -[NOTE] -==== -The CloudFormation template creates a stack that represents three control plane nodes. -==== - -. Confirm that the template components exist: -+ -[source,terminal] ----- -$ aws cloudformation describe-stacks --stack-name <name> ----- diff --git a/modules/installation-creating-aws-dns.adoc b/modules/installation-creating-aws-dns.adoc deleted file mode 100644 index 7d91033df5fe..000000000000 --- a/modules/installation-creating-aws-dns.adoc +++ /dev/null @@ -1,167 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-creating-aws-dns_{context}"] -= Creating networking and load balancing components in AWS - -You must configure networking and classic or network load balancing in Amazon Web Services (AWS) that your {product-title} cluster can use. - -You can use the provided CloudFormation template and a custom parameter file to create a stack of AWS resources. The stack represents the networking and load balancing components that your {product-title} cluster requires. The template also creates a hosted zone and subnet tags. - -You can run the template multiple times within a single Virtual Private Cloud (VPC). - -[NOTE] -==== -If you do not use the provided CloudFormation template to create your AWS -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* You configured an AWS account. -* You added your AWS keys and region to your local AWS profile by running `aws configure`. -* You generated the Ignition config files for your cluster. -* You created and configured a VPC and associated subnets in AWS. - -.Procedure - -. Obtain the hosted zone ID for the Route 53 base domain that you specified in the -`install-config.yaml` file for your cluster. You can obtain details about your hosted zone by running the following command: -+ -[source,terminal] ----- -$ aws route53 list-hosted-zones-by-name --dns-name <route53_domain> <1> ----- -<1> For the `<route53_domain>`, specify the Route 53 base domain that you used -when you generated the `install-config.yaml` file for the cluster. -+ -.Example output -[source,terminal] ----- -mycluster.example.com. False 100 -HOSTEDZONES 65F8F38E-2268-B835-E15C-AB55336FCBFA /hostedzone/Z21IXYZABCZ2A4 mycluster.example.com. 10 ----- -+ -In the example output, the hosted zone ID is `Z21IXYZABCZ2A4`. - -. Create a JSON file that contains the parameter values that the template -requires: -+ -[source,json] ----- -[ - { - "ParameterKey": "ClusterName", <1> - "ParameterValue": "mycluster" <2> - }, - { - "ParameterKey": "InfrastructureName", <3> - "ParameterValue": "mycluster-<random_string>" <4> - }, - { - "ParameterKey": "HostedZoneId", <5> - "ParameterValue": "<random_string>" <6> - }, - { - "ParameterKey": "HostedZoneName", <7> - "ParameterValue": "example.com" <8> - }, - { - "ParameterKey": "PublicSubnets", <9> - "ParameterValue": "subnet-<random_string>" <10> - }, - { - "ParameterKey": "PrivateSubnets", <11> - "ParameterValue": "subnet-<random_string>" <12> - }, - { - "ParameterKey": "VpcId", <13> - "ParameterValue": "vpc-<random_string>" <14> - } -] ----- -<1> A short, representative cluster name to use for host names, etc. -<2> Specify the cluster name that you used when you generated the -`install-config.yaml` file for the cluster. -<3> The name for your cluster infrastructure that is encoded in your Ignition -config files for the cluster. -<4> Specify the infrastructure name that you extracted from the Ignition config -file metadata, which has the format `<cluster-name>-<random-string>`. -<5> The Route 53 public zone ID to register the targets with. -<6> Specify the Route 53 public zone ID, which as a format similar to -`Z21IXYZABCZ2A4`. You can obtain this value from the AWS console. -<7> The Route 53 zone to register the targets with. -<8> Specify the Route 53 base domain that you used when you generated the -`install-config.yaml` file for the cluster. Do not include the trailing period -(.) that is displayed in the AWS console. -<9> The public subnets that you created for your VPC. -<10> Specify the `PublicSubnetIds` value from the output of the CloudFormation -template for the VPC. -<11> The private subnets that you created for your VPC. -<12> Specify the `PrivateSubnetIds` value from the output of the CloudFormation -template for the VPC. -<13> The VPC that you created for the cluster. -<14> Specify the `VpcId` value from the output of the CloudFormation template -for the VPC. - -. Copy the template from the *CloudFormation template for the network and load balancers* -section of this topic and save it as a YAML file on your computer. This template -describes the networking and load balancing objects that your cluster requires. -+ -[IMPORTANT] -==== -If you are deploying your cluster to an AWS government or secret region, you must update the `InternalApiServerRecord` in the CloudFormation template to use `CNAME` records. Records of type `ALIAS` are not supported for AWS government regions. -==== - -. Launch the CloudFormation template to create a stack of AWS resources that provide the networking and load balancing components: -+ -[IMPORTANT] -==== -You must enter the command on a single line. -==== -+ -[source,terminal] ----- -$ aws cloudformation create-stack --stack-name <name> <1> - --template-body file://<template>.yaml <2> - --parameters file://<parameters>.json <3> - --capabilities CAPABILITY_NAMED_IAM <4> ----- -<1> `<name>` is the name for the CloudFormation stack, such as `cluster-dns`. -You need the name of this stack if you remove the cluster. -<2> `<template>` is the relative path to and name of the CloudFormation template -YAML file that you saved. -<3> `<parameters>` is the relative path to and name of the CloudFormation -parameters JSON file. -<4> You must explicitly declare the `CAPABILITY_NAMED_IAM` capability because the provided template creates some `AWS::IAM::Role` resources. -+ -.Example output -[source,terminal] ----- -arn:aws:cloudformation:us-east-1:269333783861:stack/cluster-dns/cd3e5de0-2fd4-11eb-5cf0-12be5c33a183 ----- - -. Confirm that the template components exist: -+ -[source,terminal] ----- -$ aws cloudformation describe-stacks --stack-name <name> ----- -+ -After the `StackStatus` displays `CREATE_COMPLETE`, the output displays values -for the following parameters. You must provide these parameter values to -the other CloudFormation templates that you run to create your cluster: -[horizontal] -`PrivateHostedZoneId`:: Hosted zone ID for the private DNS. -`ExternalApiLoadBalancerName`:: Full name of the external API load balancer. -`InternalApiLoadBalancerName`:: Full name of the internal API load balancer. -`ApiServerDnsName`:: Full host name of the API server. -`RegisterNlbIpTargetsLambda`:: Lambda ARN useful to help register/deregister IP -targets for these load balancers. -`ExternalApiTargetGroupArn`:: ARN of external API target group. -`InternalApiTargetGroupArn`:: ARN of internal API target group. -`InternalServiceTargetGroupArn`:: ARN of internal service target group. diff --git a/modules/installation-creating-aws-security.adoc b/modules/installation-creating-aws-security.adoc deleted file mode 100644 index b9f992ec9fba..000000000000 --- a/modules/installation-creating-aws-security.adoc +++ /dev/null @@ -1,114 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-creating-aws-security_{context}"] -= Creating security group and roles in AWS - -You must create security groups and roles in Amazon Web Services (AWS) for your {product-title} cluster to use. - -You can use the provided CloudFormation template and a custom parameter file to create a stack of AWS resources. The stack represents the security groups and roles that your {product-title} cluster requires. - -[NOTE] -==== -If you do not use the provided CloudFormation template to create your AWS -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* You configured an AWS account. -* You added your AWS keys and region to your local AWS profile by running `aws configure`. -* You generated the Ignition config files for your cluster. -* You created and configured a VPC and associated subnets in AWS. - -.Procedure - -. Create a JSON file that contains the parameter values that the template -requires: -+ -[source,json] ----- -[ - { - "ParameterKey": "InfrastructureName", <1> - "ParameterValue": "mycluster-<random_string>" <2> - }, - { - "ParameterKey": "VpcCidr", <3> - "ParameterValue": "10.0.0.0/16" <4> - }, - { - "ParameterKey": "PrivateSubnets", <5> - "ParameterValue": "subnet-<random_string>" <6> - }, - { - "ParameterKey": "VpcId", <7> - "ParameterValue": "vpc-<random_string>" <8> - } -] ----- -<1> The name for your cluster infrastructure that is encoded in your Ignition -config files for the cluster. -<2> Specify the infrastructure name that you extracted from the Ignition config -file metadata, which has the format `<cluster-name>-<random-string>`. -<3> The CIDR block for the VPC. -<4> Specify the CIDR block parameter that you used for the VPC that you defined -in the form `x.x.x.x/16-24`. -<5> The private subnets that you created for your VPC. -<6> Specify the `PrivateSubnetIds` value from the output of the CloudFormation -template for the VPC. -<7> The VPC that you created for the cluster. -<8> Specify the `VpcId` value from the output of the CloudFormation template for -the VPC. - -. Copy the template from the *CloudFormation template for security objects* -section of this topic and save it as a YAML file on your computer. This template -describes the security groups and roles that your cluster requires. - -. Launch the CloudFormation template to create a stack of AWS resources that represent the security groups and roles: -+ -[IMPORTANT] -==== -You must enter the command on a single line. -==== -+ -[source,terminal] ----- -$ aws cloudformation create-stack --stack-name <name> <1> - --template-body file://<template>.yaml <2> - --parameters file://<parameters>.json <3> - --capabilities CAPABILITY_NAMED_IAM <4> ----- -<1> `<name>` is the name for the CloudFormation stack, such as `cluster-sec`. -You need the name of this stack if you remove the cluster. -<2> `<template>` is the relative path to and name of the CloudFormation template -YAML file that you saved. -<3> `<parameters>` is the relative path to and name of the CloudFormation -parameters JSON file. -<4> You must explicitly declare the `CAPABILITY_NAMED_IAM` capability because the provided template creates some `AWS::IAM::Role` and `AWS::IAM::InstanceProfile` resources. -+ -.Example output -[source,terminal] ----- -arn:aws:cloudformation:us-east-1:269333783861:stack/cluster-sec/03bd4210-2ed7-11eb-6d7a-13fc0b61e9db ----- - -. Confirm that the template components exist: -+ -[source,terminal] ----- -$ aws cloudformation describe-stacks --stack-name <name> ----- -+ -After the `StackStatus` displays `CREATE_COMPLETE`, the output displays values -for the following parameters. You must provide these parameter values to -the other CloudFormation templates that you run to create your cluster: -[horizontal] -`MasterSecurityGroupId`:: Master Security Group ID -`WorkerSecurityGroupId`:: Worker Security Group ID -`MasterInstanceProfile`:: Master IAM Instance Profile -`WorkerInstanceProfile`:: Worker IAM Instance Profile diff --git a/modules/installation-creating-aws-vpc.adoc b/modules/installation-creating-aws-vpc.adoc deleted file mode 100644 index 5adf165f14c1..000000000000 --- a/modules/installation-creating-aws-vpc.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-creating-aws-vpc_{context}"] -= Creating a VPC in AWS - -You must create a Virtual Private Cloud (VPC) in Amazon Web Services (AWS) for your {product-title} -cluster to use. You can customize the VPC to meet your requirements, including -VPN and route tables. - -You can use the provided CloudFormation template and a custom parameter file to create a stack of AWS resources that represent the VPC. - -[NOTE] -==== -If you do not use the provided CloudFormation template to create your AWS -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* You configured an AWS account. -* You added your AWS keys and region to your local AWS profile by running `aws configure`. -* You generated the Ignition config files for your cluster. - -.Procedure - -. Create a JSON file that contains the parameter values that the template -requires: -+ -[source,json] ----- -[ - { - "ParameterKey": "VpcCidr", <1> - "ParameterValue": "10.0.0.0/16" <2> - }, - { - "ParameterKey": "AvailabilityZoneCount", <3> - "ParameterValue": "1" <4> - }, - { - "ParameterKey": "SubnetBits", <5> - "ParameterValue": "12" <6> - } -] ----- -<1> The CIDR block for the VPC. -<2> Specify a CIDR block in the format `x.x.x.x/16-24`. -<3> The number of availability zones to deploy the VPC in. -<4> Specify an integer between `1` and `3`. -<5> The size of each subnet in each availability zone. -<6> Specify an integer between `5` and `13`, where `5` is `/27` and `13` is `/19`. - -. Copy the template from the *CloudFormation template for the VPC* -section of this topic and save it as a YAML file on your computer. This template -describes the VPC that your cluster requires. - -. Launch the CloudFormation template to create a stack of AWS resources that represent the VPC: -+ -[IMPORTANT] -==== -You must enter the command on a single line. -==== -+ -[source,terminal] ----- -$ aws cloudformation create-stack --stack-name <name> <1> - --template-body file://<template>.yaml <2> - --parameters file://<parameters>.json <3> ----- -<1> `<name>` is the name for the CloudFormation stack, such as `cluster-vpc`. -You need the name of this stack if you remove the cluster. -<2> `<template>` is the relative path to and name of the CloudFormation template -YAML file that you saved. -<3> `<parameters>` is the relative path to and name of the CloudFormation -parameters JSON file. -+ -.Example output -[source,terminal] ----- -arn:aws:cloudformation:us-east-1:269333783861:stack/cluster-vpc/dbedae40-2fd3-11eb-820e-12a48460849f ----- - -. Confirm that the template components exist: -+ -[source,terminal] ----- -$ aws cloudformation describe-stacks --stack-name <name> ----- -+ -After the `StackStatus` displays `CREATE_COMPLETE`, the output displays values -for the following parameters. You must provide these parameter values to -the other CloudFormation templates that you run to create your cluster: -[horizontal] -`VpcId`:: The ID of your VPC. -`PublicSubnetIds`:: The IDs of the new public subnets. -`PrivateSubnetIds`:: The IDs of the new private subnets. diff --git a/modules/installation-creating-aws-worker.adoc b/modules/installation-creating-aws-worker.adoc deleted file mode 100644 index 5a97709b29fa..000000000000 --- a/modules/installation-creating-aws-worker.adoc +++ /dev/null @@ -1,192 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="installation-creating-aws-worker_{context}"] -= Creating the worker nodes in AWS - -//// -If you do not plan to automatically create worker nodes by using a MachineSet, -//// - -You can create worker nodes in Amazon Web Services (AWS) for your cluster to use. - -You can use the provided CloudFormation template and a custom parameter file to create a stack of AWS resources that represent a worker node. - -[IMPORTANT] -==== -The CloudFormation template creates a stack that represents one worker node. -You must create a stack for each worker node. -==== - -[NOTE] -==== -If you do not use the provided CloudFormation template to create your worker -nodes, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* You configured an AWS account. -* You added your AWS keys and region to your local AWS profile by running `aws configure`. -* You generated the Ignition config files for your cluster. -* You created and configured a VPC and associated subnets in AWS. -* You created and configured DNS, load balancers, and listeners in AWS. -* You created the security groups and roles required for your cluster in AWS. -* You created the bootstrap machine. -* You created the control plane machines. - -.Procedure - -. Create a JSON file that contains the parameter values that the CloudFormation -template requires: -+ -[source,json] ----- -[ - { - "ParameterKey": "InfrastructureName", <1> - "ParameterValue": "mycluster-<random_string>" <2> - }, - { - "ParameterKey": "RhcosAmi", <3> - "ParameterValue": "ami-<random_string>" <4> - }, - { - "ParameterKey": "Subnet", <5> - "ParameterValue": "subnet-<random_string>" <6> - }, - { - "ParameterKey": "WorkerSecurityGroupId", <7> - "ParameterValue": "sg-<random_string>" <8> - }, - { - "ParameterKey": "IgnitionLocation", <9> - "ParameterValue": "https://api-int.<cluster_name>.<domain_name>:22623/config/worker" <10> - }, - { - "ParameterKey": "CertificateAuthorities", <11> - "ParameterValue": "" <12> - }, - { - "ParameterKey": "WorkerInstanceProfileName", <13> - "ParameterValue": "" <14> - }, - { - "ParameterKey": "WorkerInstanceType", <15> - "ParameterValue": "m4.large" <16> - } -] ----- -<1> The name for your cluster infrastructure that is encoded in your Ignition -config files for the cluster. -<2> Specify the infrastructure name that you extracted from the Ignition config -file metadata, which has the format `<cluster-name>-<random-string>`. -<3> Current {op-system-first} AMI to use for the worker nodes. -<4> Specify an `AWS::EC2::Image::Id` value. -<5> A subnet, preferably private, to launch the worker nodes on. -<6> Specify a subnet from the `PrivateSubnets` value from the output of the -CloudFormation template for DNS and load balancing. -<7> The worker security group ID to associate with worker nodes. -<8> Specify the `WorkerSecurityGroupId` value from the output of the -CloudFormation template for the security group and roles. -<9> The location to fetch bootstrap Ignition config file from. -<10> Specify the generated Ignition config location, -`https://api-int.<cluster_name>.<domain_name>:22623/config/worker`. -<11> Base64 encoded certificate authority string to use. -<12> Specify the value from the `worker.ign` file that is in the installation -directory. This value is the long string with the format -`data:text/plain;charset=utf-8;base64,ABC...xYz==`. -<13> The IAM profile to associate with worker nodes. -<14> Specify the `WorkerInstanceProfile` parameter value from the output of -the CloudFormation template for the security group and roles. -<15> The type of AWS instance to use for the control plane machines. -<16> Allowed values: -* `m4.large` -* `m4.xlarge` -* `m4.2xlarge` -* `m4.4xlarge` -* `m4.8xlarge` -* `m4.10xlarge` -* `m4.16xlarge` -* `m5.large` -* `m5.xlarge` -* `m5.2xlarge` -* `m5.4xlarge` -* `m5.8xlarge` -* `m5.10xlarge` -* `m5.16xlarge` -* `c4.large` -* `c4.xlarge` -* `c4.2xlarge` -* `c4.4xlarge` -* `c4.8xlarge` -* `r4.large` -* `r4.xlarge` -* `r4.2xlarge` -* `r4.4xlarge` -* `r4.8xlarge` -* `r4.16xlarge` -+ -[IMPORTANT] -==== -If `m4` instance types are not available in your region, such as with -`eu-west-3`, use `m5` types instead. -==== - -. Copy the template from the *CloudFormation template for worker machines* -section of this topic and save it as a YAML file on your computer. This template -describes the networking objects and load balancers that your cluster requires. - -. If you specified an `m5` instance type as the value for `WorkerInstanceType`, -add that instance type to the `WorkerInstanceType.AllowedValues` parameter -in the CloudFormation template. - -. Launch the CloudFormation template to create a stack of AWS resources that represent a worker node: -+ -[IMPORTANT] -==== -You must enter the command on a single line. -==== -+ -[source,terminal] ----- -$ aws cloudformation create-stack --stack-name <name> <1> - --template-body file://<template>.yaml \ <2> - --parameters file://<parameters>.json <3> ----- -<1> `<name>` is the name for the CloudFormation stack, such as `cluster-worker-1`. -You need the name of this stack if you remove the cluster. -<2> `<template>` is the relative path to and name of the CloudFormation template -YAML file that you saved. -<3> `<parameters>` is the relative path to and name of the CloudFormation -parameters JSON file. -+ -.Example output -[source,terminal] ----- -arn:aws:cloudformation:us-east-1:269333783861:stack/cluster-worker-1/729ee301-1c2a-11eb-348f-sd9888c65b59 ----- -+ -[NOTE] -==== -The CloudFormation template creates a stack that represents one worker node. -==== - -. Confirm that the template components exist: -+ -[source,terminal] ----- -$ aws cloudformation describe-stacks --stack-name <name> ----- - -. Continue to create worker stacks until you have created enough worker machines for your cluster. You can create additional worker stacks by referencing the same template and parameter files and specifying a different stack name. -+ -[IMPORTANT] -==== -You must create at least two worker machines, so you must create at least -two stacks that use this CloudFormation template. -==== diff --git a/modules/installation-creating-azure-bootstrap.adoc b/modules/installation-creating-azure-bootstrap.adoc deleted file mode 100644 index eda5487f4c5a..000000000000 --- a/modules/installation-creating-azure-bootstrap.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-creating-azure-bootstrap_{context}"] -= Creating the bootstrap machine in Azure - -You must create the bootstrap machine in Microsoft Azure to use during -{product-title} cluster initialization. One way to create this machine is to -modify the provided Azure Resource Manager (ARM) template. - -[NOTE] -==== -If you do not use the provided ARM template to create your bootstrap machine, -you must review the provided information and manually create the infrastructure. -If your cluster does not initialize correctly, you might have to contact Red Hat -support with your installation logs. -==== - -.Prerequisites - -* Configure an Azure account. -* Generate the Ignition config files for your cluster. -* Create and configure a VNet and associated subnets in Azure. -* Create and configure networking and load balancers in Azure. -* Create control plane and compute roles. - -.Procedure - -. Copy the template from the *ARM template for the bootstrap machine* section of -this topic and save it as `04_bootstrap.json` in your cluster's installation directory. This template -describes the bootstrap machine that your cluster requires. - -. Export the following variables required by the bootstrap machine deployment: -+ -[source,terminal] ----- -$ export BOOTSTRAP_URL=`az storage blob url --account-name ${CLUSTER_NAME}sa --account-key ${ACCOUNT_KEY} -c "files" -n "bootstrap.ign" -o tsv` -$ export BOOTSTRAP_IGNITION=`jq -rcnM --arg v "3.1.0" --arg url ${BOOTSTRAP_URL} '{ignition:{version:$v,config:{replace:{source:$url}}}}' | base64 | tr -d '\n'` ----- - -. Create the deployment by using the `az` CLI: -+ -[source,terminal] ----- -$ az deployment group create -g ${RESOURCE_GROUP} \ - --template-file "<installation_directory>/04_bootstrap.json" \ - --parameters bootstrapIgnition="${BOOTSTRAP_IGNITION}" \ <1> - --parameters sshKeyData="${SSH_KEY}" \ <2> - --parameters baseName="${INFRA_ID}" <3> ----- -<1> The bootstrap Ignition content for the bootstrap cluster. -<2> The SSH RSA public key file as a string. -<3> The base name to be used in resource names; this is usually the cluster's infrastructure ID. diff --git a/modules/installation-creating-azure-control-plane.adoc b/modules/installation-creating-azure-control-plane.adoc deleted file mode 100644 index f019e1a5951c..000000000000 --- a/modules/installation-creating-azure-control-plane.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-creating-azure-control-plane_{context}"] -= Creating the control plane machines in Azure - -You must create the control plane machines in Microsoft Azure for your cluster -to use. One way to create these machines is to modify the provided Azure -Resource Manager (ARM) template. - -[NOTE] -==== -If you do not use the provided ARM template to create your control plane -machines, you must review the provided information and manually create the -infrastructure. If your cluster does not initialize correctly, you might have to -contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure an Azure account. -* Generate the Ignition config files for your cluster. -* Create and configure a VNet and associated subnets in Azure. -* Create and configure networking and load balancers in Azure. -* Create control plane and compute roles. -* Create the bootstrap machine. - -.Procedure - -. Copy the template from the *ARM template for control plane machines* -section of this topic and save it as `05_masters.json` in your cluster's installation directory. -This template describes the control plane machines that your cluster requires. - -. Export the following variable needed by the control plane machine deployment: -+ -[source,terminal] ----- -$ export MASTER_IGNITION=`cat <installation_directory>/master.ign | base64 | tr -d '\n'` ----- - -. Create the deployment by using the `az` CLI: -+ -[source,terminal] ----- -$ az deployment group create -g ${RESOURCE_GROUP} \ - --template-file "<installation_directory>/05_masters.json" \ - --parameters masterIgnition="${MASTER_IGNITION}" \ <1> - --parameters sshKeyData="${SSH_KEY}" \ <2> - --parameters privateDNSZoneName="${CLUSTER_NAME}.${BASE_DOMAIN}" \ <3> - --parameters baseName="${INFRA_ID}"<4> ----- -<1> The Ignition content for the master nodes. -<2> The SSH RSA public key file as a string. -<3> The name of the private DNS zone to which the master nodes are attached. -<4> The base name to be used in resource names; this is usually the cluster's infrastructure ID. diff --git a/modules/installation-creating-azure-dns.adoc b/modules/installation-creating-azure-dns.adoc deleted file mode 100644 index 8260c3738d99..000000000000 --- a/modules/installation-creating-azure-dns.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-creating-azure-dns_{context}"] -= Creating networking and load balancing components in Azure - -You must configure networking and load balancing in Microsoft Azure for your -{product-title} cluster to use. One way to create these components is -to modify the provided Azure Resource Manager (ARM) template. - -[NOTE] -==== -If you do not use the provided ARM template to create your Azure infrastructure, -you must review the provided information and manually create the infrastructure. -If your cluster does not initialize correctly, you might have to contact Red Hat -support with your installation logs. -==== - -.Prerequisites - -* Configure an Azure account. -* Generate the Ignition config files for your cluster. -* Create and configure a VNet and associated subnets in Azure. - -.Procedure - -. Copy the template from the *ARM template for the network and load balancers* -section of this topic and save it as `03_infra.json` in your cluster's installation directory. This -template describes the networking and load balancing objects that your cluster -requires. - -. Create the deployment by using the `az` CLI: -+ -[source,terminal] ----- -$ az deployment group create -g ${RESOURCE_GROUP} \ - --template-file "<installation_directory>/03_infra.json" \ - --parameters privateDNSZoneName="${CLUSTER_NAME}.${BASE_DOMAIN}" \ <1> - --parameters baseName="${INFRA_ID}"<2> ----- -<1> The name of the private DNS zone. -<2> The base name to be used in resource names; this is usually the cluster's infrastructure ID. - -. Create an `api` DNS record in the public zone for the API public load -balancer. The `${BASE_DOMAIN_RESOURCE_GROUP}` variable must point to the -resource group where the public DNS zone exists. - -.. Export the following variable: -+ -[source,terminal] ----- -$ export PUBLIC_IP=`az network public-ip list -g ${RESOURCE_GROUP} --query "[?name=='${INFRA_ID}-master-pip'] | [0].ipAddress" -o tsv` ----- - -.. Create the DNS record in a new public zone: -+ -[source,terminal] ----- -$ az network dns record-set a add-record -g ${BASE_DOMAIN_RESOURCE_GROUP} -z ${CLUSTER_NAME}.${BASE_DOMAIN} -n api -a ${PUBLIC_IP} --ttl 60 ----- - -.. If you are adding the cluster to an existing public zone, you can create the DNS -record in it instead: -+ -[source,terminal] ----- -$ az network dns record-set a add-record -g ${BASE_DOMAIN_RESOURCE_GROUP} -z ${BASE_DOMAIN} -n api.${CLUSTER_NAME} -a ${PUBLIC_IP} --ttl 60 ----- diff --git a/modules/installation-creating-azure-vnet.adoc b/modules/installation-creating-azure-vnet.adoc deleted file mode 100644 index 5dd734af32d8..000000000000 --- a/modules/installation-creating-azure-vnet.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-creating-azure-vnet_{context}"] -= Creating a VNet in Azure - -You must create a virtual network (VNet) in Microsoft Azure for your -{product-title} cluster to use. You can customize the VNet to meet your -requirements. One way to create the VNet is to modify the provided Azure -Resource Manager (ARM) template. - -[NOTE] -==== -If you do not use the provided ARM template to create your Azure infrastructure, -you must review the provided information and manually create the infrastructure. -If your cluster does not initialize correctly, you might have to contact Red Hat -support with your installation logs. -==== - -.Prerequisites - -* Configure an Azure account. -* Generate the Ignition config files for your cluster. - -.Procedure - -. Copy the template from the *ARM template for the VNet* section of this topic -and save it as `01_vnet.json` in your cluster's installation directory. This template describes the -VNet that your cluster requires. - -. Create the deployment by using the `az` CLI: -+ -[source,terminal] ----- -$ az deployment group create -g ${RESOURCE_GROUP} \ - --template-file "<installation_directory>/01_vnet.json" \ - --parameters baseName="${INFRA_ID}"<1> ----- -<1> The base name to be used in resource names; this is usually the cluster's infrastructure ID. - -. Link the VNet template to the private DNS zone: -+ -[source,terminal] ----- -$ az network private-dns link vnet create -g ${RESOURCE_GROUP} -z ${CLUSTER_NAME}.${BASE_DOMAIN} -n ${INFRA_ID}-network-link -v "${INFRA_ID}-vnet" -e false ----- diff --git a/modules/installation-creating-azure-worker.adoc b/modules/installation-creating-azure-worker.adoc deleted file mode 100644 index 885c9e9254a5..000000000000 --- a/modules/installation-creating-azure-worker.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-creating-azure-worker_{context}"] -= Creating additional worker machines in Azure - -You can create worker machines in Microsoft Azure for your cluster -to use by launching individual instances discretely or by automated processes -outside the cluster, such as auto scaling groups. You can also take advantage of -the built-in cluster scaling mechanisms and the machine API in {product-title}. - -In this example, you manually launch one instance by using the Azure Resource -Manager (ARM) template. Additional instances can be launched by including -additional resources of type `06_workers.json` in the file. - -[NOTE] -==== -If you do not use the provided ARM template to create your worker machines, you -must review the provided information and manually create the infrastructure. If -your cluster does not initialize correctly, you might have to contact Red Hat -support with your installation logs. -==== - -.Prerequisites - -* Configure an Azure account. -* Generate the Ignition config files for your cluster. -* Create and configure a VNet and associated subnets in Azure. -* Create and configure networking and load balancers in Azure. -* Create control plane and compute roles. -* Create the bootstrap machine. -* Create the control plane machines. - -.Procedure - -. Copy the template from the *ARM template for worker machines* -section of this topic and save it as `06_workers.json` in your cluster's installation directory. This -template describes the worker machines that your cluster requires. - -. Export the following variable needed by the worker machine deployment: -+ -[source,terminal] ----- -$ export WORKER_IGNITION=`cat <installation_directory>/worker.ign | base64 | tr -d '\n'` ----- - -. Create the deployment by using the `az` CLI: -+ -[source,terminal] ----- -$ az deployment group create -g ${RESOURCE_GROUP} \ - --template-file "<installation_directory>/06_workers.json" \ - --parameters workerIgnition="${WORKER_IGNITION}" \ <1> - --parameters sshKeyData="${SSH_KEY}" \ <2> - --parameters baseName="${INFRA_ID}" <3> ----- -<1> The Ignition content for the worker nodes. -<2> The SSH RSA public key file as a string. -<3> The base name to be used in resource names; this is usually the cluster's infrastructure ID. diff --git a/modules/installation-creating-gcp-bootstrap.adoc b/modules/installation-creating-gcp-bootstrap.adoc deleted file mode 100644 index ee2997e32491..000000000000 --- a/modules/installation-creating-gcp-bootstrap.adoc +++ /dev/null @@ -1,143 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-bootstrap_{context}"] -= Creating the bootstrap machine in GCP - -You must create the bootstrap machine in Google Cloud Platform (GCP) to use during -{product-title} cluster initialization. One way to create this machine is -to modify the provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your bootstrap -machine, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. -* Create and configure networking and load balancers in GCP. -* Create control plane and compute roles. - -.Procedure - -. Copy the template from the *Deployment Manager template for the bootstrap machine* -section of this topic and save it as `04_bootstrap.py` on your computer. This -template describes the bootstrap machine that your cluster requires. - -. Export the location of the {op-system-first} image that the installation program requires: -+ -[source,terminal] ----- -$ export CLUSTER_IMAGE=(`gcloud compute images describe ${INFRA_ID}-rhcos-image --format json | jq -r .selfLink`) ----- - -. Create a bucket and upload the `bootstrap.ign` file: -+ -[source,terminal] ----- -$ gsutil mb gs://${INFRA_ID}-bootstrap-ignition -$ gsutil cp <installation_directory>/bootstrap.ign gs://${INFRA_ID}-bootstrap-ignition/ ----- - -. Create a signed URL for the bootstrap instance to use to access the Ignition -config. Export the URL from the output as a variable: -+ -[source,terminal] ----- -$ export BOOTSTRAP_IGN=`gsutil signurl -d 1h service-account-key.json gs://${INFRA_ID}-bootstrap-ignition/bootstrap.ign | grep "^gs:" | awk '{print $5}'` ----- - -. Create a `04_bootstrap.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >04_bootstrap.yaml -imports: -- path: 04_bootstrap.py - -resources: -- name: cluster-bootstrap - type: 04_bootstrap.py - properties: - infra_id: '${INFRA_ID}' <1> - region: '${REGION}' <2> - zone: '${ZONE_0}' <3> - - cluster_network: '${CLUSTER_NETWORK}' <4> - control_subnet: '${CONTROL_SUBNET}' <5> - image: '${CLUSTER_IMAGE}' <6> - machine_type: 'n1-standard-4' <7> - root_volume_size: '128' <8> - - bootstrap_ign: '${BOOTSTRAP_IGN}' <9> -EOF ----- -<1> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -<2> `region` is the region to deploy the cluster into, for example `us-central1`. -<3> `zone` is the zone to deploy the bootstrap instance into, for example `us-central1-b`. -<4> `cluster_network` is the `selfLink` URL to the cluster network. -<5> `control_subnet` is the `selfLink` URL to the control subnet. -<6> `image` is the `selfLink` URL to the {op-system} image. -<7> `machine_type` is the machine type of the instance, for example `n1-standard-4`. -<8> `bootstrap_ign` is the URL output when creating a signed URL above. - -. Create the deployment by using the `gcloud` CLI: -+ -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-bootstrap --config 04_bootstrap.yaml ----- - -ifndef::shared-vpc[] -. The templates do not manage load balancer membership due to limitations of Deployment -Manager, so you must add the bootstrap machine manually. - -.. Add the bootstrap instance to the internal load balancer instance group: -+ -[source,terminal] ----- -$ gcloud compute instance-groups unmanaged add-instances \ - ${INFRA_ID}-bootstrap-instance-group --zone=${ZONE_0} --instances=${INFRA_ID}-bootstrap ----- - -.. Add the bootstrap instance group to the internal load balancer backend service: -+ -[source,terminal] ----- -$ gcloud compute backend-services add-backend \ - ${INFRA_ID}-api-internal-backend-service --region=${REGION} --instance-group=${INFRA_ID}-bootstrap-instance-group --instance-group-zone=${ZONE_0} ----- -endif::shared-vpc[] - -ifdef::shared-vpc[] -. Add the bootstrap instance to the internal load balancer instance group: -+ -[source,terminal] ----- -$ gcloud compute instance-groups unmanaged add-instances ${INFRA_ID}-bootstrap-instance-group --zone=${ZONE_0} --instances=${INFRA_ID}-bootstrap ----- - -. Add the bootstrap instance group to the internal load balancer backend service: -+ -[source,terminal] ----- -$ gcloud compute backend-services add-backend ${INFRA_ID}-api-internal-backend-service --region=${REGION} --instance-group=${INFRA_ID}-bootstrap-instance-group --instance-group-zone=${ZONE_0} ----- -endif::shared-vpc[] - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-gcp-control-plane.adoc b/modules/installation-creating-gcp-control-plane.adoc deleted file mode 100644 index 0e3f4c3dbbe9..000000000000 --- a/modules/installation-creating-gcp-control-plane.adoc +++ /dev/null @@ -1,158 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-control-plane_{context}"] -= Creating the control plane machines in GCP - -You must create the control plane machines in Google Cloud Platform (GCP) for -your cluster to use. One way to create these machines is to modify the -provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your -control plane machines, you must review the provided information and manually -create the infrastructure. If your cluster does not initialize correctly, you -might have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. -* Create and configure networking and load balancers in GCP. -* Create control plane and compute roles. -* Create the bootstrap machine. - -.Procedure - -. Copy the template from the *Deployment Manager template for control plane machines* -section of this topic and save it as `05_control_plane.py` on your computer. -This template describes the control plane machines that your cluster requires. - -. Export the following variable required by the resource definition: -+ -[source,terminal] ----- -$ export MASTER_IGNITION=`cat <installation_directory>/master.ign` ----- - -. Create a `05_control_plane.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >05_control_plane.yaml -imports: -- path: 05_control_plane.py - -resources: -- name: cluster-control-plane - type: 05_control_plane.py - properties: - infra_id: '${INFRA_ID}' <1> - zones: <2> - - '${ZONE_0}' - - '${ZONE_1}' - - '${ZONE_2}' - - control_subnet: '${CONTROL_SUBNET}' <3> - image: '${CLUSTER_IMAGE}' <4> - machine_type: 'n1-standard-4' <5> - root_volume_size: '128' - service_account_email: '${MASTER_SERVICE_ACCOUNT}' <6> - - ignition: '${MASTER_IGNITION}' <7> -EOF ----- -<1> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -<2> `zones` are the zones to deploy the control plane instances into, for example `us-central1-a`, `us-central1-b`, and `us-central1-c`. -<3> `control_subnet` is the `selfLink` URL to the control subnet. -<4> `image` is the `selfLink` URL to the {op-system} image. -<5> `machine_type` is the machine type of the instance, for example `n1-standard-4`. -<6> `service_account_email` is the email address for the master service account that you created. -<7> `ignition` is the contents of the `master.ign` file. - -. Create the deployment by using the `gcloud` CLI: -+ -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-control-plane --config 05_control_plane.yaml ----- - -. The templates do not manage DNS entries due to limitations of Deployment -Manager, so you must add the etcd entries manually. - -.. Export the following control plane variables: -+ -[source,terminal] ----- -$ export MASTER0_IP=(`gcloud compute instances describe ${INFRA_ID}-master-0 --zone ${ZONE_0} --format json | jq -r .networkInterfaces[0].networkIP`) -$ export MASTER1_IP=(`gcloud compute instances describe ${INFRA_ID}-master-1 --zone ${ZONE_1} --format json | jq -r .networkInterfaces[0].networkIP`) -$ export MASTER2_IP=(`gcloud compute instances describe ${INFRA_ID}-master-2 --zone ${ZONE_2} --format json | jq -r .networkInterfaces[0].networkIP`) ----- -.. Add the DNS entries for the control plane etcd entries: -+ -ifndef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add ${MASTER0_IP} --name etcd-0.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add ${MASTER1_IP} --name etcd-1.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add ${MASTER2_IP} --name etcd-2.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add \ - "0 10 2380 etcd-0.${CLUSTER_NAME}.${BASE_DOMAIN}." \ - "0 10 2380 etcd-1.${CLUSTER_NAME}.${BASE_DOMAIN}." \ - "0 10 2380 etcd-2.${CLUSTER_NAME}.${BASE_DOMAIN}." \ - --name _etcd-server-ssl._tcp.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type SRV --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction execute --zone ${INFRA_ID}-private-zone ----- -endif::shared-vpc[] -ifdef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction add ${MASTER0_IP} --name etcd-0.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction add ${MASTER1_IP} --name etcd-1.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction add ${MASTER2_IP} --name etcd-2.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction add \ - "0 10 2380 etcd-0.${CLUSTER_NAME}.${BASE_DOMAIN}." \ - "0 10 2380 etcd-1.${CLUSTER_NAME}.${BASE_DOMAIN}." \ - "0 10 2380 etcd-2.${CLUSTER_NAME}.${BASE_DOMAIN}." \ - --name _etcd-server-ssl._tcp.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type SRV --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction execute --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} ----- -endif::shared-vpc[] - -. The templates do not manage load balancer membership due to limitations of Deployment -Manager, so you must add the control plane machines manually. -** Run the following commands to add the control plane machines to the appropriate instance groups: -+ -[source,terminal] ----- -$ gcloud compute instance-groups unmanaged add-instances ${INFRA_ID}-master-${ZONE_0}-instance-group --zone=${ZONE_0} --instances=${INFRA_ID}-master-0 -$ gcloud compute instance-groups unmanaged add-instances ${INFRA_ID}-master-${ZONE_1}-instance-group --zone=${ZONE_1} --instances=${INFRA_ID}-master-1 -$ gcloud compute instance-groups unmanaged add-instances ${INFRA_ID}-master-${ZONE_2}-instance-group --zone=${ZONE_2} --instances=${INFRA_ID}-master-2 ----- - -** For an external cluster, you must also run the following commands to add the control plane machines to the target pools: -+ -[source,terminal] ----- -$ gcloud compute target-pools add-instances ${INFRA_ID}-api-target-pool --instances-zone="${ZONE_0}" --instances=${INFRA_ID}-master-0 -$ gcloud compute target-pools add-instances ${INFRA_ID}-api-target-pool --instances-zone="${ZONE_1}" --instances=${INFRA_ID}-master-1 -$ gcloud compute target-pools add-instances ${INFRA_ID}-api-target-pool --instances-zone="${ZONE_2}" --instances=${INFRA_ID}-master-2 ----- - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-gcp-dns.adoc b/modules/installation-creating-gcp-dns.adoc deleted file mode 100644 index 394a446b79e8..000000000000 --- a/modules/installation-creating-gcp-dns.adoc +++ /dev/null @@ -1,119 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-dns_{context}"] -= Creating networking and load balancing components in GCP - -You must configure networking and load balancing in Google Cloud Platform (GCP) for your -{product-title} cluster to use. One way to create these components is -to modify the provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your GCP -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. - -.Procedure - -. Copy the template from the *Deployment Manager template for the network and load balancers* -section of this topic and save it as `02_infra.py` on your computer. This -template describes the networking and load balancing objects that your cluster -requires. - -. Export the following variable required by the resource definition: -+ -ifndef::shared-vpc[] -[source,terminal] ----- -$ export CLUSTER_NETWORK=`gcloud compute networks describe ${INFRA_ID}-network --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} --format json | jq -r .selfLink` ----- -endif::shared-vpc[] -ifdef::shared-vpc[] -[source,terminal] ----- -$ export CLUSTER_NETWORK=`gcloud compute networks describe ${HOST_PROJECT_NETWORK} --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} --format json | jq -r .selfLink` ----- -+ -Where `<network_name>` is the name of the network that hosts the shared VPC. -endif::shared-vpc[] - -. Create a `02_infra.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >02_infra.yaml -imports: -- path: 02_infra.py - -resources: -- name: cluster-infra - type: 02_infra.py - properties: - infra_id: '${INFRA_ID}' <1> - region: '${REGION}' <2> - - cluster_domain: '${CLUSTER_NAME}.${BASE_DOMAIN}' <3> - cluster_network: '${CLUSTER_NETWORK}' <4> -EOF ----- -<1> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -<2> `region` is the region to deploy the cluster into, for example `us-central1`. -<3> `cluster_domain` is the domain for the cluster, for example `openshift.example.com`. -<4> `cluster_network` is the `selfLink` URL to the cluster network. - -. Create the deployment by using the `gcloud` CLI: -+ -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-infra --config 02_infra.yaml ----- - -. The templates do not create DNS entries due to limitations of Deployment -Manager, so you must create them manually: - -.. Export the following variable: -+ -[source,terminal] ----- -$ export CLUSTER_IP=`gcloud compute addresses describe ${INFRA_ID}-cluster-public-ip --region=${REGION} --format json | jq -r .address` ----- - -.. Add external DNS entries: -+ -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${BASE_DOMAIN_ZONE_NAME} -$ gcloud dns record-sets transaction add ${CLUSTER_IP} --name api.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${BASE_DOMAIN_ZONE_NAME} -$ gcloud dns record-sets transaction execute --zone ${BASE_DOMAIN_ZONE_NAME} ----- - -.. Add internal DNS entries: -+ -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add ${CLUSTER_IP} --name api.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add ${CLUSTER_IP} --name api-int.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction execute --zone ${INFRA_ID}-private-zone ----- - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-gcp-firewall-rules-vpc.adoc b/modules/installation-creating-gcp-firewall-rules-vpc.adoc deleted file mode 100644 index 8fb97ce1b397..000000000000 --- a/modules/installation-creating-gcp-firewall-rules-vpc.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-firewall-rules-vpc_{context}"] -= Creating firewall rules in GCP - -You must create firewall rules in Google Cloud Platform (GCP) for your -{product-title} cluster to use. One way to create these components is -to modify the provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your GCP -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. - -.Procedure - -. Copy the template from the -*Deployment Manager template for firewall rules* -section of this topic and save it as `03_firewall.py` on your computer. This -template describes the security groups that your cluster requires. - -. Create a `03_firewall.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >03_firewall.yaml -imports: -- path: 03_firewall.py - -resources: -- name: cluster-firewall - type: 03_firewall.py - properties: - allowed_external_cidr: '0.0.0.0/0' <1> - infra_id: '${INFRA_ID}' <2> - cluster_network: '${CLUSTER_NETWORK}' <3> - network_cidr: '${NETWORK_CIDR}' <4> -EOF ----- -<1> `allowed_external_cidr` is the CIDR range that can access the cluster API and SSH to the bootstrap host. For an internal cluster, set this value to `${NETWORK_CIDR}`. -<2> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -<3> `cluster_network` is the `selfLink` URL to the cluster network. -<4> `network_cidr` is the CIDR of the VPC network, for example `10.0.0.0/16`. - -. Create the deployment by using the `gcloud` CLI: -+ -ifdef::shared-vpc[] -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-firewall --config 03_firewall.yaml --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} ----- -endif::shared-vpc[] -ifndef::shared-vpc[] -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-firewall --config 03_firewall.yaml ----- -endif::shared-vpc[] - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-gcp-iam-shared-vpc.adoc b/modules/installation-creating-gcp-iam-shared-vpc.adoc deleted file mode 100644 index 6834066a2792..000000000000 --- a/modules/installation-creating-gcp-iam-shared-vpc.adoc +++ /dev/null @@ -1,147 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-iam-shared-vpc_{context}"] -= Creating IAM roles in GCP - -You must create IAM roles in Google Cloud Platform (GCP) for your -{product-title} cluster to use. One way to create these components is -to modify the provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your GCP -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. - -.Procedure - -. Copy the template from the -*Deployment Manager template for IAM roles* -section of this topic and save it as `03_iam.py` on your computer. This -template describes the IAM roles that your cluster requires. - -. Create a `03_iam.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >03_iam.yaml -imports: -- path: 03_iam.py -resources: -- name: cluster-iam - type: 03_iam.py - properties: - infra_id: '${INFRA_ID}' <1> -EOF ----- -<1> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. - -. Create the deployment by using the `gcloud` CLI: -+ -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-iam --config 03_iam.yaml ----- - -. Export the variable for the master service account: -+ -[source,terminal] ----- -$ export MASTER_SERVICE_ACCOUNT=(`gcloud iam service-accounts list --filter "email~^${INFRA_ID}-m@${PROJECT_NAME}." --format json | jq -r '.[0].email'`) ----- - -. Export the variable for the worker service account: -+ -[source,terminal] ----- -$ export WORKER_SERVICE_ACCOUNT=(`gcloud iam service-accounts list --filter "email~^${INFRA_ID}-w@${PROJECT_NAME}." --format json | jq -r '.[0].email'`) ----- - -ifndef::shared-vpc[] -. Export the variable for the subnet that hosts the compute machines: -+ -[source,terminal] ----- -$ export COMPUTE_SUBNET=(`gcloud compute networks subnets describe ${INFRA_ID}-worker-subnet --region=${REGION} --format json | jq -r .selfLink`) ----- -endif::shared-vpc[] - -ifdef::shared-vpc[] -. Assign the permissions that the installation program requires to the service accounts for the subnets that host the control plane and compute subnets: - -.. Grant the `networkViewer` role of the project that hosts your shared VPC to the master service account: -+ -[source,terminal] ----- -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} projects add-iam-policy-binding ${HOST_PROJECT} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.networkViewer" ----- - -.. Grant the `networkUser` role to the master service account for the control plane subnet: -+ -[source,terminal] ----- -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} compute networks subnets add-iam-policy-binding "${HOST_PROJECT_CONTROL_SUBNET}" --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.networkUser" --region ${REGION} ----- - -.. Grant the `networkUser` role to the worker service account for the control plane subnet: -+ -[source,terminal] ----- -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} compute networks subnets add-iam-policy-binding "${HOST_PROJECT_CONTROL_SUBNET}" --member "serviceAccount:${WORKER_SERVICE_ACCOUNT}" --role "roles/compute.networkUser" --region ${REGION} ----- - -.. Grant the `networkUser` role to the master service account for the compute subnet: -+ -[source,terminal] ----- -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} compute networks subnets add-iam-policy-binding "${HOST_PROJECT_COMPUTE_SUBNET}" --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.networkUser" --region ${REGION} ----- - -.. Grant the `networkUser` role to the worker service account for the compute subnet: -+ -[source,terminal] ----- -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} compute networks subnets add-iam-policy-binding "${HOST_PROJECT_COMPUTE_SUBNET}" --member "serviceAccount:${WORKER_SERVICE_ACCOUNT}" --role "roles/compute.networkUser" --region ${REGION} ----- -endif::shared-vpc[] - -. The templates do not create the policy bindings due to limitations of Deployment -Manager, so you must create them manually: -+ -[source,terminal] ----- -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.instanceAdmin" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.networkAdmin" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.securityAdmin" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/iam.serviceAccountUser" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/storage.admin" - -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${WORKER_SERVICE_ACCOUNT}" --role "roles/compute.viewer" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${WORKER_SERVICE_ACCOUNT}" --role "roles/storage.admin" ----- - -. Create a service account key and store it locally for later use: -+ -[source,terminal] ----- -$ gcloud iam service-accounts keys create service-account-key.json --iam-account=${MASTER_SERVICE_ACCOUNT} ----- - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-gcp-lb.adoc b/modules/installation-creating-gcp-lb.adoc deleted file mode 100644 index a60617595b0d..000000000000 --- a/modules/installation-creating-gcp-lb.adoc +++ /dev/null @@ -1,148 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-lb_{context}"] -= Creating load balancers in GCP - -You must configure load balancers in Google Cloud Platform (GCP) for your -{product-title} cluster to use. One way to create these components is -to modify the provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your GCP -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. - -.Procedure - -. Copy the template from the *Deployment Manager template for the internal load balancer* -section of this topic and save it as `02_lb_int.py` on your computer. This -template describes the internal load balancing objects that your cluster -requires. - -. For an external cluster, also copy the template from the *Deployment Manager template for the external load balancer* -section of this topic and save it as `02_lb_ext.py` on your computer. This -template describes the external load balancing objects that your cluster -requires. - -. Export the variables that the deployment template uses: - -.. Export the cluster network location: -+ -ifdef::shared-vpc[] -[source,terminal] ----- -$ export CLUSTER_NETWORK=(`gcloud compute networks describe ${HOST_PROJECT_NETWORK} --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} --format json | jq -r .selfLink`) ----- -endif::shared-vpc[] -ifndef::shared-vpc[] -[source,terminal] ----- -$ export CLUSTER_NETWORK=(`gcloud compute networks describe ${INFRA_ID}-network --format json | jq -r .selfLink`) ----- -endif::shared-vpc[] - -.. Export the control plane subnet location: -+ -ifdef::shared-vpc[] -[source,terminal] ----- -$ export CONTROL_SUBNET=(`gcloud compute networks subnets describe ${HOST_PROJECT_CONTROL_SUBNET} --region=${REGION} --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} --format json | jq -r .selfLink`) ----- -endif::shared-vpc[] -ifndef::shared-vpc[] -[source,terminal] ----- -$ export CONTROL_SUBNET=(`gcloud compute networks subnets describe ${INFRA_ID}-master-subnet --region=${REGION} --format json | jq -r .selfLink`) ----- -endif::shared-vpc[] - -.. Export the three zones that the cluster uses: -+ -[source,terminal] ----- -$ export ZONE_0=(`gcloud compute regions describe ${REGION} --format=json | jq -r .zones[0] | cut -d "/" -f9`) ----- -+ -[source,terminal] ----- -$ export ZONE_1=(`gcloud compute regions describe ${REGION} --format=json | jq -r .zones[1] | cut -d "/" -f9`) ----- -+ -[source,terminal] ----- -$ export ZONE_2=(`gcloud compute regions describe ${REGION} --format=json | jq -r .zones[2] | cut -d "/" -f9`) ----- - -. Create a `02_infra.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >02_infra.yaml -imports: -- path: 02_lb_ext.py -- path: 02_lb_int.py <1> -resources: -- name: cluster-lb-ext <1> - type: 02_lb_ext.py - properties: - infra_id: '${INFRA_ID}' <2> - region: '${REGION}' <3> -- name: cluster-lb-int - type: 02_lb_int.py - properties: - cluster_network: '${CLUSTER_NETWORK}' - control_subnet: '${CONTROL_SUBNET}' <4> - infra_id: '${INFRA_ID}' - region: '${REGION}' - zones: <5> - - '${ZONE_0}' - - '${ZONE_1}' - - '${ZONE_2}' -EOF ----- -<1> Required only when deploying an external cluster. -<2> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -<3> `region` is the region to deploy the cluster into, for example `us-central1`. -<4> `control_subnet` is the URI to the control subnet. -<5> `zones` are the zones to deploy the control plane instances into, like `us-east1-b`, `us-east1-c`, and `us-east1-d`. - -. Create the deployment by using the `gcloud` CLI: -+ -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-infra --config 02_infra.yaml ----- - -. Export the cluster IP address: -+ -[source,terminal] ----- -$ export CLUSTER_IP=(`gcloud compute addresses describe ${INFRA_ID}-cluster-ip --region=${REGION} --format json | jq -r .address`) ----- - -. For an external cluster, also export the cluster public IP address: -+ -[source,terminal] ----- -$ export CLUSTER_PUBLIC_IP=(`gcloud compute addresses describe ${INFRA_ID}-cluster-public-ip --region=${REGION} --format json | jq -r .address`) ----- - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-gcp-private-dns.adoc b/modules/installation-creating-gcp-private-dns.adoc deleted file mode 100644 index b32518f4a971..000000000000 --- a/modules/installation-creating-gcp-private-dns.adoc +++ /dev/null @@ -1,123 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-private-dns_{context}"] -= Creating a private DNS zone in GCP - -You must configure a private DNS zone in Google Cloud Platform (GCP) for your -{product-title} cluster to use. One way to create this component is -to modify the provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your GCP -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. - -.Procedure - -. Copy the template from the *Deployment Manager template for the private DNS* -section of this topic and save it as `02_dns.py` on your computer. This -template describes the private DNS objects that your cluster -requires. - -. Create a `02_dns.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >02_dns.yaml -imports: -- path: 02_dns.py - -resources: -- name: cluster-dns - type: 02_dns.py - properties: - infra_id: '${INFRA_ID}' <1> - cluster_domain: '${CLUSTER_NAME}.${BASE_DOMAIN}' <2> - cluster_network: '${CLUSTER_NETWORK}' <3> -EOF ----- -<1> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -<2> `cluster_domain` is the domain for the cluster, for example `openshift.example.com`. -<3> `cluster_network` is the `selfLink` URL to the cluster network. - -. Create the deployment by using the `gcloud` CLI: -+ -ifdef::shared-vpc[] -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-dns --config 02_dns.yaml --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} ----- -endif::shared-vpc[] -ifndef::shared-vpc[] -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-dns --config 02_dns.yaml ----- -endif::shared-vpc[] - -. The templates do not create DNS entries due to limitations of Deployment -Manager, so you must create them manually: - -.. Add the internal DNS entries: -+ -ifdef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction add ${CLUSTER_IP} --name api.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction add ${CLUSTER_IP} --name api-int.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction execute --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} ----- -endif::shared-vpc[] -ifndef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add ${CLUSTER_IP} --name api.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add ${CLUSTER_IP} --name api-int.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction execute --zone ${INFRA_ID}-private-zone ----- -endif::shared-vpc[] - -.. For an external cluster, also add the external DNS entries: -+ -ifdef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} dns record-sets transaction start --zone ${BASE_DOMAIN_ZONE_NAME} -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} dns record-sets transaction add ${CLUSTER_PUBLIC_IP} --name api.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${BASE_DOMAIN_ZONE_NAME} -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} dns record-sets transaction execute --zone ${BASE_DOMAIN_ZONE_NAME} ----- -endif::shared-vpc[] -ifndef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${BASE_DOMAIN_ZONE_NAME} -$ gcloud dns record-sets transaction add ${CLUSTER_PUBLIC_IP} --name api.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 60 --type A --zone ${BASE_DOMAIN_ZONE_NAME} -$ gcloud dns record-sets transaction execute --zone ${BASE_DOMAIN_ZONE_NAME} ----- -endif::shared-vpc[] - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-gcp-security.adoc b/modules/installation-creating-gcp-security.adoc deleted file mode 100644 index 06e94492c178..000000000000 --- a/modules/installation-creating-gcp-security.adoc +++ /dev/null @@ -1,111 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-creating-gcp-security_{context}"] -= Creating firewall rules and IAM roles in GCP - -You must create security groups and roles in Google Cloud Platform (GCP) for your -{product-title} cluster to use. One way to create these components is -to modify the provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your GCP -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. - -.Procedure - -. Copy the template from the *Deployment Manager template for firewall rules and IAM roles* -section of this topic and save it as `03_security.py` on your computer. This -template describes the security groups and roles that your cluster requires. - -. Export the following variables required by the resource definition: -+ -[source,terminal] ----- -$ export MASTER_NAT_IP=`gcloud compute addresses describe ${INFRA_ID}-master-nat-ip --region ${REGION} --format json | jq -r .address` -$ export WORKER_NAT_IP=`gcloud compute addresses describe ${INFRA_ID}-worker-nat-ip --region ${REGION} --format json | jq -r .address` ----- - -. Create a `03_security.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >03_security.yaml -imports: -- path: 03_security.py - -resources: -- name: cluster-security - type: 03_security.py - properties: - allowed_external_cidr: '0.0.0.0/0' <1> - infra_id: '${INFRA_ID}' <2> - region: '${REGION}' <3> - cluster_network: '${CLUSTER_NETWORK}' <4> - network_cidr: '${NETWORK_CIDR}' <5> - master_nat_ip: '${MASTER_NAT_IP}' <6> - worker_nat_ip: '${WORKER_NAT_IP}' <7> -EOF ----- -<1> `allowed_external_cidr` is the CIDR range that can access the cluster API and SSH to the bootstrap host. For an internal cluster, set this value to `${NETWORK_CIDR}`. -<2> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -<3> `region` is the region to deploy the cluster into, for example `us-central1`. -<4> `cluster_network` is the `selfLink` URL to the cluster network. -<5> `network_cidr` is the CIDR of the VPC network, for example `10.0.0.0/16`. -<6> `master_nat_ip` is the IP address of the master NAT, for example `34.94.100.1`. -<7> `worker_nat_ip` is the IP address of the worker NAT, for example `34.94.200.1`. - -. Create the deployment by using the `gcloud` CLI: -+ -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-security --config 03_security.yaml ----- - -. Export the variable for the master service account: -+ -[source,terminal] ----- -$ export MASTER_SERVICE_ACCOUNT=`gcloud iam service-accounts list --filter "email~^${INFRA_ID}-m@${PROJECT_NAME}." --format json | jq -r '.[0].email'` ----- - -. Export the variable for the worker service account: -+ -[source,terminal] ----- -$ export WORKER_SERVICE_ACCOUNT=`gcloud iam service-accounts list --filter "email~^${INFRA_ID}-w@${PROJECT_NAME}." --format json | jq -r '.[0].email'` ----- - -. The templates do not create the policy bindings due to limitations of Deployment -Manager, so you must create them manually: -+ -[source,terminal] ----- -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.instanceAdmin" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.networkAdmin" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/compute.securityAdmin" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/iam.serviceAccountUser" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${MASTER_SERVICE_ACCOUNT}" --role "roles/storage.admin" - -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${WORKER_SERVICE_ACCOUNT}" --role "roles/compute.viewer" -$ gcloud projects add-iam-policy-binding ${PROJECT_NAME} --member "serviceAccount:${WORKER_SERVICE_ACCOUNT}" --role "roles/storage.admin" ----- - -. Create a service account key and store it locally for later use: -+ -[source,terminal] ----- -$ gcloud iam service-accounts keys create service-account-key.json --iam-account=${MASTER_SERVICE_ACCOUNT} ----- diff --git a/modules/installation-creating-gcp-shared-vpc-cluster-wide-firewall-rules.adoc b/modules/installation-creating-gcp-shared-vpc-cluster-wide-firewall-rules.adoc deleted file mode 100644 index 774e23b20877..000000000000 --- a/modules/installation-creating-gcp-shared-vpc-cluster-wide-firewall-rules.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -[id="installation-creating-gcp-shared-vpc-cluster-wide-firewall-rules_{context}"] -= Creating cluster-wide firewall rules for a shared VPC in GCP - -You can create cluster-wide firewall rules to allow the access that the {product-title} cluster requires. - -[WARNING] -==== -If you do not choose to create firewall rules based on cluster events, you must create cluster-wide firewall rules. -==== - -.Prerequisites - -* You exported the variables that the Deployment Manager templates require to deploy your cluster. -* You created the networking and load balancing components in GCP that your cluster requires. - -.Procedure - -. Add a single firewall rule to allow the Google Cloud Engine health checks to access all of the services. This rule enables the ingress load balancers to determine the health status of their instances. -+ -[source,terminal] ----- -$ gcloud compute firewall-rules create --allow='tcp:30000-32767,udp:30000-32767' --network="${CLUSTER_NETWORK}" --source-ranges='130.211.0.0/22,35.191.0.0/16,209.85.152.0/22,209.85.204.0/22' --target-tags="${INFRA_ID}-master,${INFRA_ID}-worker" ${INFRA_ID}-ingress-hc --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} ----- - -. Add a single firewall rule to allow access to all cluster services: -+ --- -** For an external cluster: -+ -[source,terminal] ----- -$ gcloud compute firewall-rules create --allow='tcp:80,tcp:443' --network="${CLUSTER_NETWORK}" --source-ranges="0.0.0.0/0" --target-tags="${INFRA_ID}-master,${INFRA_ID}-worker" ${INFRA_ID}-ingress --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} ----- -** For a private cluster: -+ -[source,terminal] ----- -$ gcloud compute firewall-rules create --allow='tcp:80,tcp:443' --network="${CLUSTER_NETWORK}" --source-ranges=${NETWORK_CIDR} --target-tags="${INFRA_ID}-master,${INFRA_ID}-worker" ${INFRA_ID}-ingress --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} ----- --- -+ -Because this rule only allows traffic on TCP ports `80` and `443`, ensure that you add all the ports that your services use. diff --git a/modules/installation-creating-gcp-shared-vpc-ingress-firewall-rules.adoc b/modules/installation-creating-gcp-shared-vpc-ingress-firewall-rules.adoc deleted file mode 100644 index 3861e982e9bb..000000000000 --- a/modules/installation-creating-gcp-shared-vpc-ingress-firewall-rules.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -[id="installation-creating-gcp-shared-vpc-ingress-firewall-rules_{context}"] -= Creating ingress firewall rules for a shared VPC in GCP - -You must create ingress firewall rules to allow the access that the {product-title} cluster requires. - -.Prerequisites - -* You exported the variables that the Deployment Manager templates require to deploy your cluster. -* You created the networking and load balancing components in GCP that your cluster requires. - -.Procedure - -* Add ingress firewall rules: -** For an external cluster: -+ ----- -$ gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} compute firewall-rules create --allow='tc p:30000-32767,udp:30000-32767' --network="${CLUSTER_NETWORK}" --source-ranges='130.211.0.0/22,35.191.0.0/16, 209.85.152.0/22,209.85.204.0/22' --target-tags="${INFRA_ID}-master,${INFRA_ID}-worker" ${INFRA_ID}-ingress-h c -417 -418 gcloud --account=${HOST_PROJECT_ACCOUNT} --project=${HOST_PROJECT} compute firewall-rules create --allow='tc p:80,tcp:443' --network="${CLUSTER_NETWORK}" --source-ranges="0.0.0.0/0" --target-tags="${INFRA_ID}-master,$ {INFRA_ID}-worker" ${INFRA_ID}-ingress ----- - -** For an internal cluster: -+ ----- -$ gcloud compute firewall-rules create --allow='tcp:30000-32767,udp:30000-32767' --network="${CLUSTER_NETWORK }" --source-ranges='130.211.0.0/22,35.191.0.0/16,209.85.152.0/22,209.85.204.0/22' --target-tags="${INFRA_ID} -master,${INFRA_ID}-worker" ${INFRA_ID}-ingress-hc -383 -gcloud compute firewall-rules create --allow='tcp:80,tcp:443' --network="${CLUSTER_NETWORK}" --source-ranges="${NETWORK_CIDR}" --target-tags="${INFRA_ID}-master,${INFRA_ID}-worker" ${INFRA_ID}-ingress ----- diff --git a/modules/installation-creating-gcp-vpc.adoc b/modules/installation-creating-gcp-vpc.adoc deleted file mode 100644 index fc8467cbba15..000000000000 --- a/modules/installation-creating-gcp-vpc.adoc +++ /dev/null @@ -1,151 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-vpc_{context}"] -= Creating a VPC in GCP - -You must create a VPC in Google Cloud Platform (GCP) for your {product-title} -cluster to use. You can customize the VPC to meet your requirements. One way to -create the VPC is to modify the provided Deployment Manager template. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your GCP -infrastructure, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -ifndef::shared-vpc[] -* Generate the Ignition config files for your cluster. -endif::shared-vpc[] - -.Procedure - -. Copy the template from the *Deployment Manager template for the VPC* -section of this topic and save it as `01_vpc.py` on your computer. This template -describes the VPC that your cluster requires. - -ifdef::shared-vpc[] -. Export the following variables required by the resource definition: - -.. Export the control plane CIDR: -+ -[source,terminal] ----- -$ export MASTER_SUBNET_CIDR='10.0.0.0/19' ----- - -.. Export the compute CIDR: -+ -[source,terminal] ----- -$ export WORKER_SUBNET_CIDR='10.0.32.0/19' ----- - -.. Export the region to deploy the VPC network and cluster to: -+ -[source,terminal] ----- -$ export REGION='<region>' ----- - -. Export the variable for the ID of the project that hosts the shared VPC: -+ -[source,terminal] ----- -$ export HOST_PROJECT=<host_project> ----- - -. Export the variable for the email of the service account that belongs to host project: -+ -[source,terminal] ----- -$ export HOST_PROJECT_ACCOUNT=<host_service_account_email> ----- -endif::shared-vpc[] - -. Create a `01_vpc.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >01_vpc.yaml -imports: -- path: 01_vpc.py - -resources: -- name: cluster-vpc - type: 01_vpc.py - properties: -ifndef::shared-vpc[] - infra_id: '${INFRA_ID}' <1> -endif::shared-vpc[] -ifdef::shared-vpc[] - infra_id: '<prefix>' <1> -endif::shared-vpc[] - region: '${REGION}' <2> - master_subnet_cidr: '${MASTER_SUBNET_CIDR}' <3> - worker_subnet_cidr: '${WORKER_SUBNET_CIDR}' <4> -EOF ----- -ifndef::shared-vpc[] -<1> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -endif::shared-vpc[] -ifdef::shared-vpc[] -<1> `infra_id` is the prefix of the network name. -endif::shared-vpc[] -<2> `region` is the region to deploy the cluster into, for example `us-central1`. -<3> `master_subnet_cidr` is the CIDR for the master subnet, for example `10.0.0.0/19`. -<4> `worker_subnet_cidr` is the CIDR for the worker subnet, for example `10.0.32.0/19`. - -. Create the deployment by using the `gcloud` CLI: -+ -ifndef::shared-vpc[] -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-vpc --config 01_vpc.yaml ----- -endif::shared-vpc[] -ifdef::shared-vpc[] -[source,terminal] ----- -$ gcloud deployment-manager deployments create <vpc_deployment_name> --config 01_vpc.yaml --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} <1> ----- -<1> For `<vpc_deployment_name>`, specify the name of the VPC to deploy. - -. Export the VPC variable that other components require: -.. Export the name of the host project network: -+ -[source,terminal] ----- -$ export HOST_PROJECT_NETWORK=<vpc_network> ----- -.. Export the name of the host project control plane subnet: -+ -[source,terminal] ----- -$ export HOST_PROJECT_CONTROL_SUBNET=<control_plane_subnet> ----- -.. Export the name of the host project compute subnet: -+ -[source,terminal] ----- -$ export HOST_PROJECT_COMPUTE_SUBNET=<compute_subnet> ----- - -. Set up the shared VPC. See link:https://cloud.google.com/vpc/docs/provisioning-shared-vpc#setting_up[Setting up Shared VPC] in the GCP documentation. -endif::shared-vpc[] - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-gcp-worker.adoc b/modules/installation-creating-gcp-worker.adoc deleted file mode 100644 index 68d1ad81aa4b..000000000000 --- a/modules/installation-creating-gcp-worker.adoc +++ /dev/null @@ -1,131 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-creating-gcp-worker_{context}"] -= Creating additional worker machines in GCP - -You can create worker machines in Google Cloud Platform (GCP) for your cluster -to use by launching individual instances discretely or by automated processes -outside the cluster, such as auto scaling groups. You can also take advantage of -the built-in cluster scaling mechanisms and the machine API in {product-title}. - -In this example, you manually launch one instance by using the Deployment -Manager template. Additional instances can be launched by including additional -resources of type `06_worker.py` in the file. - -[NOTE] -==== -If you do not use the provided Deployment Manager template to create your worker -machines, you must review the provided information and manually create -the infrastructure. If your cluster does not initialize correctly, you might -have to contact Red Hat support with your installation logs. -==== - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. -* Create and configure networking and load balancers in GCP. -* Create control plane and compute roles. -* Create the bootstrap machine. -* Create the control plane machines. - -.Procedure - -. Copy the template from the *Deployment Manager template for worker machines* -section of this topic and save it as `06_worker.py` on your computer. This -template describes the worker machines that your cluster requires. - -. Export the variables that the resource definition uses. -.. Export the subnet that hosts the compute machines: -+ -ifndef::shared-vpc[] -[source,terminal] ----- -$ export COMPUTE_SUBNET=(`gcloud compute networks subnets describe ${INFRA_ID}-worker-subnet --region=${REGION} --format json | jq -r .selfLink`) ----- -endif::shared-vpc[] -ifdef::shared-vpc[] -[source,terminal] ----- -$ export COMPUTE_SUBNET=(`gcloud compute networks subnets describe ${HOST_PROJECT_COMPUTE_SUBNET} --region=${REGION} --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} --format json | jq -r .selfLink`) ----- -endif::shared-vpc[] - -.. Export the email address for your service account: -+ -[source,terminal] ----- -$ export WORKER_SERVICE_ACCOUNT=(`gcloud iam service-accounts list --filter "email~^${INFRA_ID}-w@${PROJECT_NAME}." --format json | jq -r '.[0].email'`) ----- - -.. Export the location of the compute machine Ignition config file: -+ -[source,terminal] ----- -$ export WORKER_IGNITION=`cat <installation_directory>/worker.ign` ----- - -. Create a `06_worker.yaml` resource definition file: -+ -[source,terminal] ----- -$ cat <<EOF >06_worker.yaml -imports: -- path: 06_worker.py - -resources: -- name: 'worker-0' <1> - type: 06_worker.py - properties: - infra_id: '${INFRA_ID}' <2> - zone: '${ZONE_0}' <3> - compute_subnet: '${COMPUTE_SUBNET}' <4> - image: '${CLUSTER_IMAGE}' <5> - machine_type: 'n1-standard-4' <6> - root_volume_size: '128' - service_account_email: '${WORKER_SERVICE_ACCOUNT}' <7> - ignition: '${WORKER_IGNITION}' <8> -- name: 'worker-1' - type: 06_worker.py - properties: - infra_id: '${INFRA_ID}' <2> - zone: '${ZONE_1}' <3> - compute_subnet: '${COMPUTE_SUBNET}' <4> - image: '${CLUSTER_IMAGE}' <5> - machine_type: 'n1-standard-4' <6> - root_volume_size: '128' - service_account_email: '${WORKER_SERVICE_ACCOUNT}' <7> - ignition: '${WORKER_IGNITION}' <8> -EOF ----- -<1> `name` is the name of the worker machine, for example `worker-0`. -<2> `infra_id` is the `INFRA_ID` infrastructure name from the extraction step. -<3> `zone` is the zone to deploy the worker machine into, for example `us-central1-a`. -<4> `compute_subnet` is the `selfLink` URL to the compute subnet. -<5> `image` is the `selfLink` URL to the {op-system} image. -<6> `machine_type` is the machine type of the instance, for example `n1-standard-4`. -<7> `service_account_email` is the email address for the worker service account that you created. -<8> `ignition` is the contents of the `worker.ign` file. - -. Optional: If you want to launch additional instances, include additional -resources of type `06_worker.py` in your `06_worker.yaml` resource definition -file. - -. Create the deployment by using the `gcloud` CLI: -+ -[source,terminal] ----- -$ gcloud deployment-manager deployments create ${INFRA_ID}-worker --config 06_worker.yaml ----- - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-creating-image-restricted.adoc b/modules/installation-creating-image-restricted.adoc deleted file mode 100644 index b23c1a56a122..000000000000 --- a/modules/installation-creating-image-restricted.adoc +++ /dev/null @@ -1,86 +0,0 @@ -//Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-restricted.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc - -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:osp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:vsphere: -endif::[] - -[id="installation-creating-image-restricted_{context}"] -= Creating the {op-system} image for restricted network installations - -Download the {op-system-first} image to install {product-title} on a restricted network -ifdef::osp[{rh-openstack-first}] -ifdef::vsphere[VMware vSphere] -environment. - -.Prerequisites - -* Obtain the {product-title} installation program. For a restricted network installation, the program is on your bastion host. - -.Procedure - -. Log in to the Red Hat Customer Portal's https://access.redhat.com/downloads/content/290[Product Downloads page]. - -. Under *Version*, select the most recent release of {product-title} {product-version} for RHEL 8. -+ -[IMPORTANT] -==== -The {op-system} images might not change with every release of {product-title}. -You must download images with the highest version that is less than or equal to -the {product-title} version that you install. Use the image versions that match -your {product-title} version if they are available. -==== - -ifdef::osp[] -. Download the *{op-system-first} - OpenStack Image (QCOW)* image. -endif::osp[] -ifdef::vsphere[] -. Download the *{op-system-first} - vSphere* image. -endif::vsphere[] - -ifdef::osp[] -. Decompress the image. -+ -[NOTE] -==== -You must decompress the image before the cluster can use it. The name of the downloaded file might not contain a compression extension, like `.gz` or `.tgz`. To find out if or how the file is compressed, in a command line, enter: - ----- -$ file <name_of_downloaded_file> ----- - -==== - -. Upload the image that you decompressed to a location that is accessible from the bastion server, like Glance. For example: -+ ----- -$ openstack image create --file rhcos-44.81.202003110027-0-openstack.x86_64.qcow2 --disk-format qcow2 rhcos-${RHCOS_VERSION} ----- -+ -[IMPORTANT] -==== -Depending on your {rh-openstack} environment, you might be able to upload the image in either link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/15/html/instances_and_images_guide/index[`.raw` or `.qcow2` formats]. If you use Ceph, you must use the `.raw` format. -==== -+ -[WARNING] -==== -If the installation program finds multiple images with the same name, it chooses one of them at random. To avoid this behavior, create unique names for resources in {rh-openstack}. -==== -endif::osp[] -ifdef::vsphere[] -. Upload the image you downloaded to a location that is accessible from the bastion server. -endif::vsphere[] - -The image is now available for a restricted installation. Note the image name or location for use in {product-title} deployment. - -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:!vsphere: -endif::[] diff --git a/modules/installation-creating-mirror-registry.adoc b/modules/installation-creating-mirror-registry.adoc deleted file mode 100644 index 7103839c4ffe..000000000000 --- a/modules/installation-creating-mirror-registry.adoc +++ /dev/null @@ -1,170 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-restricted-networks-preparations.adoc -// * openshift_images/samples-operator-alt-registry.adoc - -ifeval::["{context}" == "installing-restricted-networks-preparations"] -:restricted: -endif::[] - -[id="installation-creating-mirror-registry_{context}"] -= Creating a mirror registry - -Create a registry to host the mirrored content that you require for installing -{product-title}. - -ifdef::restricted[] -For installation in a restricted network, you can place the mirror -registry on a host that can be accessed from both the your network and -the internet. If you do not have access to such a host, use the -method that best fits your restrictions to bring the contents of the -mirror registry into your restricted network. -endif::restricted[] - -[NOTE] -==== -The following procedure creates a simple registry that stores data in the -`/opt/registry` folder and runs in a `podman` container. You can use a different -registry solution, such as -link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#repo-mirroring-in-red-hat-quay[Red Hat Quay]. -Review the following procedure to ensure that your registry functions -correctly. -==== - -.Prerequisites - -* You have a Red Hat Enterprise Linux (RHEL) server on your network to use -as the registry host. -* The registry host can access the internet. - -.Procedure - -ifdef::restricted[] -On the mirror host, take the following actions: -endif::restricted[] - -. Install the required packages: -+ -[source,terminal] ----- -# yum -y install podman httpd-tools ----- -+ -The `podman` package provides the container package that you run the registry -in. The `httpd-tools` package provides the `htpasswd` utility, which -you use to create users. - -. Create folders for the registry: -+ -[source,terminal] ----- -# mkdir -p /opt/registry/{auth,certs,data} ----- -+ -These folders are mounted inside the registry container. - -. Provide a certificate for the registry. If you do not have an existing, trusted -certificate authority, you can generate a self-signed certificate: -+ -[source,terminal] ----- -$ cd /opt/registry/certs ----- -+ -[source,terminal] ----- -# openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key -x509 -days 365 -out domain.crt ----- -+ -At the prompts, provide the required values for the certificate: -[horizontal] -Country Name (2 letter code):: Specify the two-letter ISO country code for your location. -See the link:https://www.iso.org/iso-3166-country-codes.html[ISO 3166 country codes] -standard. -State or Province Name (full name):: Enter the full name of your state or province. -Locality Name (eg, city):: Enter the name of your city. -Organization Name (eg, company):: Enter your company name. -Organizational Unit Name (eg, section):: Enter your department name. -Common Name (eg, your name or your server's hostname):: Enter the host name for -the registry host. Ensure that your hostname is in DNS and that it resolves to -the expected IP address. -Email Address:: Enter your email address. -For more information, see the -link:https://www.openssl.org/docs/man1.1.1/man1/req.html[req] description in the -OpenSSL documentation. - -. Generate a user name and a password for your registry that uses the `bcrpt` format: -+ -[source,terminal] ----- -# htpasswd -bBc /opt/registry/auth/htpasswd <user_name> <password> <1> ----- -<1> Replace `<user_name>` and `<password>` with a user name and a password. - -. Create the `mirror-registry` container to host your registry: -+ -[source,terminal] ----- -# podman run --name mirror-registry -p <local_registry_host_port>:5000 \ <1> - -v /opt/registry/data:/var/lib/registry:z \ - -v /opt/registry/auth:/auth:z \ - -e "REGISTRY_AUTH=htpasswd" \ - -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \ - -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \ - -v /opt/registry/certs:/certs:z \ - -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ - -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ - -e REGISTRY_COMPATIBILITY_SCHEMA1_ENABLED=true \ - -d docker.io/library/registry:2 ----- -<1> For `<local_registry_host_port>`, specify the port that your mirror registry -uses to serve content. - -. Open the required ports for your registry: -+ -[source,terminal] ----- -# firewall-cmd --add-port=<local_registry_host_port>/tcp --zone=internal --permanent <1> -# firewall-cmd --add-port=<local_registry_host_port>/tcp --zone=public --permanent <1> -# firewall-cmd --reload ----- -<1> For `<local_registry_host_port>`, specify the port that your mirror registry -uses to serve content. - -. Add the self-signed certificate to your list of trusted certificates: -+ -[source,terminal] ----- -# cp /opt/registry/certs/domain.crt /etc/pki/ca-trust/source/anchors/ -# update-ca-trust ----- -+ -You must trust your certificate to log in to your registry during the mirror process. - -. Confirm that the registry is available: -+ -[source,terminal] ----- -$ curl -u <user_name>:<password> -k https://<local_registry_host_name>:<local_registry_host_port>/v2/_catalog <1> - -{"repositories":[]} ----- -<1> For `<user_name>` and `<password>`, specify the user name and password -for your registry. For `<local_registry_host_name>`, specify the registry domain name -that you specified in your certificate, such as `registry.example.com`. For -`<local_registry_host_port>`, specify the port that your mirror registry uses to -serve content. -+ -If the command output displays an empty repository, your registry is available. - -//// -. To stop the registry:: -+ ----- -# podman stop mirror-registry ----- -//// - -ifeval::["{context}" == "installing-restricted-networks-preparations"] -:!restricted: -endif::[] diff --git a/modules/installation-custom-aws-vpc.adoc b/modules/installation-custom-aws-vpc.adoc deleted file mode 100644 index 41dbdeff857c..000000000000 --- a/modules/installation-custom-aws-vpc.adoc +++ /dev/null @@ -1,147 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc - -[id="installation-custom-aws-vpc_{context}"] -= About using a custom VPC - -In {product-title} {product-version}, you can deploy a cluster into existing subnets in an existing Amazon Virtual Private Cloud (VPC) in Amazon Web Services (AWS). By deploying {product-title} into an existing AWS VPC, you might be able to avoid limit constraints in new accounts or more easily abide by the operational constraints that your company's guidelines set. If you cannot obtain the infrastructure creation permissions that are required to create the VPC yourself, use this installation option. - -Because the installation program cannot know what other components are also in your existing subnets, it cannot choose subnet CIDRs and so forth on your behalf. You must configure networking for the subnets that you install your cluster to yourself. - -[id="installation-custom-aws-vpc-requirements_{context}"] -== Requirements for using your VPC - -The installation program no longer creates the following components: - -* Internet gateways -* NAT gateways -* Subnets -* Route tables -* VPCs -* VPC DHCP options -* VPC endpoints - -If you use a custom VPC, you must correctly configure it and its subnets for the installation program and the cluster to use. The installation program cannot subdivide network ranges for the cluster to use, set route tables for the subnets, or set VPC options like DHCP, so you must do so before you install the cluster. - -Your VPC must meet the following characteristics: - -* The VPC's CIDR block must contain the `Networking.MachineCIDR` range, which is the IP address pool for cluster machines. -* The VPC must not use the `kubernetes.io/cluster/.*: owned` tag. -* You must enable the `enableDnsSupport` and `enableDnsHostnames` attributes in your VPC so that the cluster can use the Route 53 zones that are attached to the VPC to resolve cluster’s internal DNS records. See link:https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-support[DNS Support in Your VPC] in the AWS documentation. - -If you use a cluster with public access, you must create a public and a private subnet for each availability zone that your cluster uses. The installation program modifies your subnets to add the `kubernetes.io/cluster/.*: shared` tag, so your subnets must have at least one free tag slot available for it. Review the current link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#tag-restrictions[Tag Restrictions] in the AWS documentation to ensure that the installation program can add a tag to each subnet that you specify. - -If you are working in a disconnected environment, you are unable to reach the -public IP addresses for EC2 and ELB endpoints. To resolve this, you must create -a VPC endpoint and attach it to the subnet that the clusters are using. The -endpoints should be named as follows: - -* `ec2.<region>.amazonaws.com` -* `elasticloadbalancing.<region>.amazonaws.com` -* `s3.<region>.amazonaws.com` - -.Required VPC components - -You must provide a suitable VPC and subnets that allow communication to your -machines. - -[cols="2a,7a,3a,3a",options="header"] -|=== - -|Component -|AWS type -2+|Description - -|VPC -|* `AWS::EC2::VPC` -* `AWS::EC2::VPCEndpoint` -2+|You must provide a public VPC for the cluster to use. The VPC uses an -endpoint that references the route tables for each subnet to improve communication with the registry that is hosted in S3. - -|Public subnets -|* `AWS::EC2::Subnet` -* `AWS::EC2::SubnetNetworkAclAssociation` -2+|Your VPC must have public subnets for between 1 and 3 availability zones -and associate them with appropriate Ingress rules. - -|Internet gateway -| -* `AWS::EC2::InternetGateway` -* `AWS::EC2::VPCGatewayAttachment` -* `AWS::EC2::RouteTable` -* `AWS::EC2::Route` -* `AWS::EC2::SubnetRouteTableAssociation` -* `AWS::EC2::NatGateway` -* `AWS::EC2::EIP` -2+|You must have a public Internet gateway, with public routes, attached to the -VPC. In the provided templates, each public subnet has a NAT gateway with an EIP address. These NAT gateways allow cluster resources, like private subnet instances, to reach the Internet and are not required for some restricted network or proxy scenarios. - -.7+|Network access control -.7+| * `AWS::EC2::NetworkAcl` -* `AWS::EC2::NetworkAclEntry` -2+|You must allow the VPC to access the following ports: -h|Port -h|Reason - -|`80` -|Inbound HTTP traffic - -|`443` -|Inbound HTTPS traffic - -|`22` -|Inbound SSH traffic - -|`1024` - `65535` -|Inbound ephemeral traffic - -|`0` - `65535` -|Outbound ephemeral traffic - - -|Private subnets -|* `AWS::EC2::Subnet` -* `AWS::EC2::RouteTable` -* `AWS::EC2::SubnetRouteTableAssociation` -2+|Your VPC can have private subnets. The provided CloudFormation templates -can create private subnets for between 1 and 3 availability zones. -If you use private subnets, you must provide appropriate routes and tables -for them. - -|=== - -[id="installation-custom-aws-vpc-validation_{context}"] -== VPC validation - -To ensure that the subnets that you provide are suitable, the installation program confirms the following data: - -* All the subnets that you specify exist. -* You provide private subnets. -* The subnet CIDRs belong to the machine CIDR that you specified. -* You provide subnets for each availability zone. Each availability zone contains no more than one public and one private subnet. If you use a private cluster, provide only a private subnet for each availability zone. Otherwise, provide exactly one public and private subnet for each availability zone. -* You provide a public subnet for each private subnet availability zone. Machines are not provisioned in availability zones that you do not provide private subnets for. - -If you destroy a cluster that uses an existing VPC, the VPC is not deleted. When you remove the {product-title} cluster from a VPC, the `kubernetes.io/cluster/.*: shared` tag is removed from the subnets that it used. - -[id="installation-about-custom-aws-permissions_{context}"] -== Division of permissions - -Starting with {product-title} 4.3, you do not need all of the permissions that are required for an installation program-provisioned infrastructure cluster to deploy a cluster. This change mimics the division of permissions that you might have at your company: some individuals can create different resource in your clouds than others. For example, you might be able to create application-specific items, like instances, buckets, and load balancers, but not networking-related components such as VPCs, subnets, or ingress rules. - -The AWS credentials that you use when you create your cluster do not need the networking permissions that are required to make VPCs and core networking components within the VPC, such as subnets, routing tables, Internet gateways, NAT, and VPN. You still need permission to make the application resources that the machines within the cluster require, such as ELBs, security groups, S3 buckets, and nodes. - -[id="installation-custom-aws-vpc-isolation_{context}"] -== Isolation between clusters - -If you deploy {product-title} to an existing network, the isolation of cluster services is reduced in the following ways: - -* You can install multiple {product-title} clusters in the same VPC. -* ICMP ingress is allowed from the entire network. -* TCP 22 ingress (SSH) is allowed to the entire network. -//You can restrict ingress to the control plane and compute security groups by either adding the security groups to an SSH bastion instance or altering rules to allow the bastion. -* Control plane TCP 6443 ingress (Kubernetes API) is allowed to the entire network. -* Control plane TCP 22623 ingress (MCS) is allowed to the entire network. -//This should be restricted to the control plane and compute security groups, instead of the current by-VPC-CIDR logic to avoid leaking sensitive Ignition configs to non-cluster entities sharing the VPC. diff --git a/modules/installation-deployment-manager-bootstrap.adoc b/modules/installation-deployment-manager-bootstrap.adoc deleted file mode 100644 index 7180279ef943..000000000000 --- a/modules/installation-deployment-manager-bootstrap.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-deployment-manager-bootstrap_{context}"] -= Deployment Manager template for the bootstrap machine - -You can use the following Deployment Manager template to deploy the bootstrap -machine that you need for your {product-title} cluster: - -.`04_bootstrap.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/04_bootstrap.py[] ----- -==== diff --git a/modules/installation-deployment-manager-control-plane.adoc b/modules/installation-deployment-manager-control-plane.adoc deleted file mode 100644 index f51c4630a404..000000000000 --- a/modules/installation-deployment-manager-control-plane.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-deployment-manager-control-plane_{context}"] -= Deployment Manager template for control plane machines - -You can use the following Deployment Manager template to deploy the control -plane machines that you need for your {product-title} cluster: - -.`05_control_plane.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/05_control_plane.py[] ----- -==== diff --git a/modules/installation-deployment-manager-dns.adoc b/modules/installation-deployment-manager-dns.adoc deleted file mode 100644 index 78e333aa7ab4..000000000000 --- a/modules/installation-deployment-manager-dns.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-deployment-manager-dns_{context}"] -= Deployment Manager template for the network and load balancers - -You can use the following Deployment Manager template to deploy the networking -objects and load balancers that you need for your {product-title} cluster: - -.`02_infra.py` Deployment Manager template -[source,python] ----- -def GenerateConfig(context): - - resources = [{ - 'name': context.properties['infra_id'] + '-cluster-public-ip', - 'type': 'compute.v1.address', - 'properties': { - 'region': context.properties['region'] - } - }, { - 'name': context.properties['infra_id'] + '-api-http-health-check', - 'type': 'compute.v1.httpHealthCheck', - 'properties': { - 'port': 6080, - 'requestPath': '/readyz' - } - }, { - 'name': context.properties['infra_id'] + '-api-target-pool', - 'type': 'compute.v1.targetPool', - 'properties': { - 'region': context.properties['region'], - 'healthChecks': ['$(ref.' + context.properties['infra_id'] + '-api-http-health-check.selfLink)'], - 'instances': [] - } - }, { - 'name': context.properties['infra_id'] + '-api-forwarding-rule', - 'type': 'compute.v1.forwardingRule', - 'properties': { - 'region': context.properties['region'], - 'IPAddress': '$(ref.' + context.properties['infra_id'] + '-cluster-public-ip.selfLink)', - 'target': '$(ref.' + context.properties['infra_id'] + '-api-target-pool.selfLink)', - 'portRange': '6443' - } - }, { - 'name': context.properties['infra_id'] + '-ign-http-health-check', - 'type': 'compute.v1.httpHealthCheck', - 'properties': { - 'port': 22624, - 'requestPath': '/healthz' - } - }, { - 'name': context.properties['infra_id'] + '-ign-target-pool', - 'type': 'compute.v1.targetPool', - 'properties': { - 'region': context.properties['region'], - 'healthChecks': ['$(ref.' + context.properties['infra_id'] + '-ign-http-health-check.selfLink)'], - 'instances': [] - } - }, { - 'name': context.properties['infra_id'] + '-ign-forwarding-rule', - 'type': 'compute.v1.forwardingRule', - 'properties': { - 'region': context.properties['region'], - 'IPAddress': '$(ref.' + context.properties['infra_id'] + '-cluster-public-ip.selfLink)', - 'target': '$(ref.' + context.properties['infra_id'] + '-ign-target-pool.selfLink)', - 'portRange': '22623' - } - }, { - 'name': context.properties['infra_id'] + '-private-zone', - 'type': 'dns.v1.managedZone', - 'properties': { - 'description': '', - 'dnsName': context.properties['cluster_domain'] + '.', - 'visibility': 'private', - 'privateVisibilityConfig': { - 'networks': [{ - 'networkUrl': context.properties['cluster_network'] - }] - } - } - }] - return {'resources': resources} ----- diff --git a/modules/installation-deployment-manager-ext-lb.adoc b/modules/installation-deployment-manager-ext-lb.adoc deleted file mode 100644 index 7be8a1adcfa6..000000000000 --- a/modules/installation-deployment-manager-ext-lb.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -[id="installation-deployment-manager-ext-lb_{context}"] -= Deployment Manager template for the external load balancer - -You can use the following Deployment Manager template to deploy the external load balancer that you need for your {product-title} cluster: - -.`02_lb_ext.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/02_lb_ext.py[] ----- -==== diff --git a/modules/installation-deployment-manager-firewall-rules.adoc b/modules/installation-deployment-manager-firewall-rules.adoc deleted file mode 100644 index 0170e7c7797f..000000000000 --- a/modules/installation-deployment-manager-firewall-rules.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-shared-vpc.adoc - -[id="installation-deployment-manager-firewall-rules_{context}"] -= Deployment Manager template for firewall rules - -You can use the following Deployment Manager template to deploy the firewall rues that you need for your {product-title} cluster: - -.`03_firewall.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/03_firewall.py[] ----- -==== diff --git a/modules/installation-deployment-manager-iam-shared-vpc.adoc b/modules/installation-deployment-manager-iam-shared-vpc.adoc deleted file mode 100644 index cbf94943611b..000000000000 --- a/modules/installation-deployment-manager-iam-shared-vpc.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-shared-vpc.adoc - -[id="installation-deployment-manager-iam-shared-vpc_{context}"] -= Deployment Manager template for IAM roles - -You can use the following Deployment Manager template to deploy the IAM roles that you need for your {product-title} cluster: - -.`03_iam.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/03_iam.py[] ----- -==== diff --git a/modules/installation-deployment-manager-int-lb.adoc b/modules/installation-deployment-manager-int-lb.adoc deleted file mode 100644 index 8799cb853db1..000000000000 --- a/modules/installation-deployment-manager-int-lb.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -[id="installation-deployment-manager-int-lb_{context}"] -= Deployment Manager template for the internal load balancer - -You can use the following Deployment Manager template to deploy the internal load balancer that you need for your {product-title} cluster: - -.`02_lb_int.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/02_lb_int.py[] ----- -==== diff --git a/modules/installation-deployment-manager-private-dns.adoc b/modules/installation-deployment-manager-private-dns.adoc deleted file mode 100644 index ca42f612d96e..000000000000 --- a/modules/installation-deployment-manager-private-dns.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -[id="installation-deployment-manager-private-dns_{context}"] -= Deployment Manager template for the private DNS - -You can use the following Deployment Manager template to deploy the private DNS that you need for your {product-title} cluster: - -.`02_dns.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/02_dns.py[] ----- -==== diff --git a/modules/installation-deployment-manager-security.adoc b/modules/installation-deployment-manager-security.adoc deleted file mode 100644 index a518b06e468c..000000000000 --- a/modules/installation-deployment-manager-security.adoc +++ /dev/null @@ -1,154 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-deployment-manager-security_{context}"] -= Deployment Manager template for firewall rules and IAM roles - -You can use the following Deployment Manager template to deploy the security -objects that you need for your {product-title} cluster: - -.`03_security.py` Deployment Manager template -[source,python] ----- -def GenerateConfig(context): - - resources = [{ - 'name': context.properties['infra_id'] + '-api', - 'type': 'compute.v1.firewall', - 'properties': { - 'network': context.properties['cluster_network'], - 'allowed': [{ - 'IPProtocol': 'tcp', - 'ports': ['6443'] - }], - 'sourceRanges': ['0.0.0.0/0'], - 'targetTags': [context.properties['infra_id'] + '-master'] - } - }, { - 'name': context.properties['infra_id'] + '-mcs', - 'type': 'compute.v1.firewall', - 'properties': { - 'network': context.properties['cluster_network'], - 'allowed': [{ - 'IPProtocol': 'tcp', - 'ports': ['22623'] - }], - 'sourceRanges': [ - context.properties['network_cidr'], - context.properties['master_nat_ip'], - context.properties['worker_nat_ip'] - ], - 'targetTags': [context.properties['infra_id'] + '-master'] - } - }, { - 'name': context.properties['infra_id'] + '-health-checks', - 'type': 'compute.v1.firewall', - 'properties': { - 'network': context.properties['cluster_network'], - 'allowed': [{ - 'IPProtocol': 'tcp', - 'ports': ['6080', '22624'] - }], - 'sourceRanges': ['35.191.0.0/16', '209.85.152.0/22', '209.85.204.0/22'], - 'targetTags': [context.properties['infra_id'] + '-master'] - } - }, { - 'name': context.properties['infra_id'] + '-etcd', - 'type': 'compute.v1.firewall', - 'properties': { - 'network': context.properties['cluster_network'], - 'allowed': [{ - 'IPProtocol': 'tcp', - 'ports': ['2379-2380'] - }], - 'sourceTags': [context.properties['infra_id'] + '-master'], - 'targetTags': [context.properties['infra_id'] + '-master'] - } - }, { - 'name': context.properties['infra_id'] + '-control-plane', - 'type': 'compute.v1.firewall', - 'properties': { - 'network': context.properties['cluster_network'], - 'allowed': [{ - 'IPProtocol': 'tcp', - 'ports': ['10257'] - },{ - 'IPProtocol': 'tcp', - 'ports': ['10259'] - }], - 'sourceTags': [ - context.properties['infra_id'] + '-master', - context.properties['infra_id'] + '-worker' - ], - 'targetTags': [context.properties['infra_id'] + '-master'] - } - }, { - 'name': context.properties['infra_id'] + '-internal-network', - 'type': 'compute.v1.firewall', - 'properties': { - 'network': context.properties['cluster_network'], - 'allowed': [{ - 'IPProtocol': 'icmp' - },{ - 'IPProtocol': 'tcp', - 'ports': ['22'] - }], - 'sourceRanges': [context.properties['network_cidr']], - 'targetTags': [ - context.properties['infra_id'] + '-master', - context.properties['infra_id'] + '-worker' - ] - } - }, { - 'name': context.properties['infra_id'] + '-internal-cluster', - 'type': 'compute.v1.firewall', - 'properties': { - 'network': context.properties['cluster_network'], - 'allowed': [{ - 'IPProtocol': 'udp', - 'ports': ['4789', '6081'] - },{ - 'IPProtocol': 'tcp', - 'ports': ['9000-9999'] - },{ - 'IPProtocol': 'udp', - 'ports': ['9000-9999'] - },{ - 'IPProtocol': 'tcp', - 'ports': ['10250'] - },{ - 'IPProtocol': 'tcp', - 'ports': ['30000-32767'] - },{ - 'IPProtocol': 'udp', - 'ports': ['30000-32767'] - }], - 'sourceTags': [ - context.properties['infra_id'] + '-master', - context.properties['infra_id'] + '-worker' - ], - 'targetTags': [ - context.properties['infra_id'] + '-master', - context.properties['infra_id'] + '-worker' - ] - } - }, { - 'name': context.properties['infra_id'] + '-master-node-sa', - 'type': 'iam.v1.serviceAccount', - 'properties': { - 'accountId': context.properties['infra_id'] + '-m', - 'displayName': context.properties['infra_id'] + '-master-node' - } - }, { - 'name': context.properties['infra_id'] + '-worker-node-sa', - 'type': 'iam.v1.serviceAccount', - 'properties': { - 'accountId': context.properties['infra_id'] + '-w', - 'displayName': context.properties['infra_id'] + '-worker-node' - } - }] - - return {'resources': resources} ----- diff --git a/modules/installation-deployment-manager-vpc.adoc b/modules/installation-deployment-manager-vpc.adoc deleted file mode 100644 index c0e0430533e6..000000000000 --- a/modules/installation-deployment-manager-vpc.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-deployment-manager-vpc_{context}"] -= Deployment Manager template for the VPC - -You can use the following Deployment Manager template to deploy the VPC that -you need for your {product-title} cluster: - -.`01_vpc.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/01_vpc.py[] ----- -==== diff --git a/modules/installation-deployment-manager-worker.adoc b/modules/installation-deployment-manager-worker.adoc deleted file mode 100644 index 45b12de9b7e7..000000000000 --- a/modules/installation-deployment-manager-worker.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-deployment-manager-worker_{context}"] -= Deployment Manager template for worker machines - -You can use the following Deployment Manager template to deploy the worker machines -that you need for your {product-title} cluster: - -.`06_worker.py` Deployment Manager template -[%collapsible] -==== -[source,python] ----- -include::https://raw.githubusercontent.com/openshift/installer/release-4.8/upi/gcp/06_worker.py[] ----- -==== diff --git a/modules/installation-disk-partitioning-upi-templates.adoc b/modules/installation-disk-partitioning-upi-templates.adoc deleted file mode 100644 index b826498c246a..000000000000 --- a/modules/installation-disk-partitioning-upi-templates.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -// Similar content to what is in this module is also present in modules/installation-disk-partitioning.adoc. <-- This module is in use with the following vSphere assemblies: -// * installing-vsphere.adoc -// * installing-vsphere-network-customizations.adoc -// * installing-restricted-networks-vsphere.adoc - -// Similar content to what is in this module is also present in modules/installation-user-infra-machines-advanced.adoc. <-- This module is in use with the following bare metal assemblies: -// * installing-bare-metal-network-customizations.adoc -// * installing-bare-metal.adoc -// * installing-restricted-networks-bare-metal.adoc - -[id="installation-disk-partitioning-upi-templates_{context}"] -= Optional: Creating a separate `/var` partition -It is recommended that disk partitioning for {product-title} be left to the installer. However, there are cases where you might want to create separate partitions in a part of the filesystem that you expect to grow. - -{product-title} supports the addition of a single partition to attach storage to either the `/var` partition or a subdirectory of `/var`. For example: - -* `/var/lib/containers`: Holds container-related content that can grow as more images and containers are added to a system. -* `/var/lib/etcd`: Holds data that you might want to keep separate for purposes such as performance optimization of etcd storage. -* `/var`: Holds data that you might want to keep separate for purposes such as auditing. - -Storing the contents of a `/var` directory separately makes it easier to grow storage for those areas as needed and reinstall {product-title} at a later date and keep that data intact. With this method, you will not have to pull all your containers again, nor will you have to copy massive log files when you update systems. - -Because `/var` must be in place before a fresh installation of {op-system-first}, the following procedure sets up the separate `/var` partition by creating a machine config that is inserted during the `openshift-install` preparation phases of an {product-title} installation. - -[IMPORTANT] -==== -If you follow the steps to create a separate `/var` partition in this procedure, it is not necessary to create the Kubernetes manifest and Ignition config files again as described later in this section. -==== - -.Procedure - -. Create a directory to hold the {product-title} installation files: -+ -[source,terminal] ----- -$ mkdir $HOME/clusterconfig ----- - -. Run `openshift-install` to create a set of files in the `manifest` and `openshift` subdirectories. Answer the system questions as you are prompted: -+ -[source,terminal] ----- -$ openshift-install create manifests --dir $HOME/clusterconfig -? SSH Public Key ... -$ ls $HOME/clusterconfig/openshift/ -99_kubeadmin-password-secret.yaml -99_openshift-cluster-api_master-machines-0.yaml -99_openshift-cluster-api_master-machines-1.yaml -99_openshift-cluster-api_master-machines-2.yaml -... ----- - -. Create a `MachineConfig` object and add it to a file in the `openshift` directory. For example, name the file `98-var-partition.yaml`, change the disk device name to the name of the storage device on the `worker` systems, and set the storage size as appropriate. This attaches storage to a separate `/var` directory. - -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: 98-var-partition -spec: - config: - ignition: - version: 3.1.0 - storage: - disks: - - device: /dev/<device_name> <1> - partitions: - - sizeMiB: <partition_size> - startMiB: <partition_start_offset> <2> - label: var - filesystems: - - path: /var - device: /dev/disk/by-partlabel/var - format: xfs - systemd: - units: - - name: var.mount - enabled: true - contents: | - [Unit] - Before=local-fs.target - [Mount] - Where=/var - What=/dev/disk/by-partlabel/var - [Install] - WantedBy=local-fs.target ----- -+ -<1> The storage device name of the disk that you want to partition. -<2> When adding a data partition to the boot disk, a minimum value of 25000 MiB (Mebibytes) is recommended. The root file system is automatically resized to fill all available space up to the specified offset. If no value is specified, or if the specified value is smaller than the recommended minimum, the resulting root file system will be too small, and future reinstalls of {op-system} might overwrite the beginning of the data partition. - -. Run `openshift-install` again to create Ignition configs from a set of files in the `manifest` and `openshift` subdirectories: -+ -[source,terminal] ----- -$ openshift-install create ignition-configs --dir $HOME/clusterconfig -$ ls $HOME/clusterconfig/ -auth bootstrap.ign master.ign metadata.json worker.ign ----- - -Now you can use the Ignition config files as input to the installation procedures to install {op-system-first} systems. diff --git a/modules/installation-disk-partitioning.adoc b/modules/installation-disk-partitioning.adoc deleted file mode 100644 index ad7fe8ec7793..000000000000 --- a/modules/installation-disk-partitioning.adoc +++ /dev/null @@ -1,129 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc - -// This content was sourced from the bare metal RHCOS assembly file `modules/installation-user-infra-machines-advanced.adoc` under the `== Disk partitioning` subheader. "Disk partioning" content in the bare metal assembly is not modularized, so anything in this vsphere module should be checked against that file for consistency until such time that the large bare metal assembly can be modularized. - -[id="installation-disk-partitioning_{context}"] -= Disk partitioning - -In most cases, data partitions are originally created by installing {op-system}, rather than by installing another operating system. In such cases, the {product-title} installer should be allowed to configure your disk partitions. - -However, there are two cases where you might want to intervene to override the default partitioning when installing an -{product-title} node: - -* Create separate partitions: For greenfield installations on an empty -disk, you might want to add separate storage to a partition. This is -officially supported for making `/var` or a subdirectory of `/var`, such as `/var/lib/etcd`, a separate partition, but not both. -+ -[IMPORTANT] -==== -Kubernetes supports only two filesystem partitions. If you add more than one partition to the original configuration, Kubernetes cannot monitor all of them. -==== -* Retain existing partitions: For a brownfield installation where you are reinstalling {product-title} on an existing node and want to retain data partitions installed from your previous operating system, there are both boot arguments and options to `coreos-installer` that allow you to retain existing data partitions. - -[discrete] -= Creating a separate `/var` partition -In general, disk partitioning for {product-title} should be left to the -installer. However, there are cases where you might want to create separate partitions in a part of the filesystem that you expect to grow. - -{product-title} supports the addition of a single partition to attach -storage to either the `/var` partition or a subdirectory of `/var`. -For example: - -* `/var/lib/containers`: Holds container-related content that can grow -as more images and containers are added to a system. -* `/var/lib/etcd`: Holds data that you might want to keep separate for purposes such as performance optimization of etcd storage. -* `/var`: Holds data that you might want to keep separate for purposes such as auditing. - -Storing the contents of a `/var` directory separately makes it easier to grow storage for those areas as needed and reinstall {product-title} at a later date and keep that data intact. With this method, you will not have to pull all your containers again, nor will you have to copy massive log files when you update systems. - -Because `/var` must be in place before a fresh installation of -{op-system-first}, the following procedure sets up the separate `/var` partition -by creating a machine config that is inserted during the `openshift-install` -preparation phases of an {product-title} installation. - -.Procedure - -. Create a directory to hold the {product-title} installation files: -+ -[source,terminal] ----- -$ mkdir $HOME/clusterconfig ----- - -. Run `openshift-install` to create a set of files in the `manifest` and -`openshift` subdirectories. Answer the system questions as you are prompted: -+ -[source,terminal] ----- -$ openshift-install create manifests --dir $HOME/clusterconfig -? SSH Public Key ... -$ ls $HOME/clusterconfig/openshift/ -99_kubeadmin-password-secret.yaml -99_openshift-cluster-api_master-machines-0.yaml -99_openshift-cluster-api_master-machines-1.yaml -99_openshift-cluster-api_master-machines-2.yaml -... ----- - -. Create a `MachineConfig` object and add it to a file in the `openshift` directory. -For example, name the file `98-var-partition.yaml`, change the disk device name to the name of the storage device on the `worker` systems, and set the storage size as appropriate. This attaches storage to a separate `/var` -directory. - -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: 98-var-partition -spec: - config: - ignition: - version: 3.1.0 - storage: - disks: - - device: /dev/<device_name> <1> - partitions: - - sizeMiB: <partition_size> - startMiB: <partition_start_offset> <2> - label: var - filesystems: - - path: /var - device: /dev/disk/by-partlabel/var - format: xfs - systemd: - units: - - name: var.mount - enabled: true - contents: | - [Unit] - Before=local-fs.target - [Mount] - Where=/var - What=/dev/disk/by-partlabel/var - [Install] - WantedBy=local-fs.target ----- -+ -<1> The storage device name of the disk that you want to partition. -<2> When adding a data partition to the boot disk, a minimum value of 25000 mebibytes is recommended. The root file system is automatically resized to fill all available space up to the specified offset. If no value is specified, or if the specified value is smaller than the recommended minimum, the resulting root file system will be too small, and future reinstalls of {op-system} might overwrite the beginning of the data partition. - -. Run `openshift-install` again to create Ignition configs from a set of files in the `manifest` and `openshift` subdirectories: -+ -[source,terminal] ----- -$ openshift-install create ignition-configs --dir $HOME/clusterconfig -$ ls $HOME/clusterconfig/ -auth bootstrap.ign master.ign metadata.json worker.ign ----- - -Now you can use the Ignition config files as input to the vSphere installation procedures to install {op-system-first} systems. diff --git a/modules/installation-dns-user-infra.adoc b/modules/installation-dns-user-infra.adoc deleted file mode 100644 index 0240f7a84299..000000000000 --- a/modules/installation-dns-user-infra.adoc +++ /dev/null @@ -1,171 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing-rhv-restricted-network.adoc - - - -:prewrap!: - -[id="installation-dns-user-infra_{context}"] -= User-provisioned DNS requirements - -DNS is used for name resolution and reverse name resolution. DNS A/AAAA or CNAME records -are used for name resolution and PTR records are used for reverse name resolution. -The reverse records are important because {op-system-first} uses the reverse records to set the host name for -all the nodes. Additionally, the reverse records are used to generate the certificate signing requests -(CSR) that {product-title} needs to operate. - -The following DNS records are required for an {product-title} cluster that uses -user-provisioned infrastructure. In each record, `<cluster_name>` is the cluster -name and `<base_domain>` is the cluster base domain that you specify in the -`install-config.yaml` file. A complete DNS record takes the form: `<component>.<cluster_name>.<base_domain>.`. - -.Required DNS records -[cols="1a,3a,5a",options="header"] -|=== - -|Component -|Record -|Description - -.2+a|Kubernetes API -|`api.<cluster_name>.<base_domain>.` -|Add a DNS A/AAAA or CNAME record, and a DNS PTR record, to identify the load balancer -for the control plane machines. These records must be resolvable by both clients -external to the cluster and from all the nodes within the cluster. - -|`api-int.<cluster_name>.<base_domain>.` -|Add a DNS A/AAAA or CNAME record, and a DNS PTR record, to identify the load balancer -for the control plane machines. These records must be resolvable from all the -nodes within the cluster. -[IMPORTANT] -==== -The API server must be able to resolve the worker nodes by the host names -that are recorded in Kubernetes. If the API server cannot resolve the node -names, then proxied API calls can fail, and you cannot retrieve logs from pods. -==== - -|Routes -|`*.apps.<cluster_name>.<base_domain>.` -|Add a wildcard DNS A/AAAA or CNAME record that refers to the load balancer that targets the -machines that run the Ingress router pods, which are the worker nodes by -default. These records must be resolvable by both clients external to the cluster -and from all the nodes within the cluster. - -|Bootstrap -|`bootstrap.<cluster_name>.<base_domain>.` -|Add a DNS A/AAAA or CNAME record, and a DNS PTR record, to identify the bootstrap -machine. These records must be resolvable by the nodes within the cluster. - -|Master hosts -|`<master><n>.<cluster_name>.<base_domain>.` -|Add DNS A/AAAA or CNAME records and DNS PTR records to identify each machine -for the master nodes. These records must be resolvable by the nodes within the cluster. - -|Worker hosts -|`<worker><n>.<cluster_name>.<base_domain>.` -|Add DNS A/AAAA or CNAME records and DNS PTR records to identify each machine -for the worker nodes. These records must be resolvable by the nodes within the cluster. - -|=== - -[TIP] -==== -You can use the `nslookup <hostname>` command to verify name resolution. You can use the -`dig -x <ip_address>` command to verify reverse name resolution for the PTR records. -==== - -The following example of a BIND zone file shows sample A records for name resolution. The -purpose of the example is to show the records that are needed. The example is not meant -to provide advice for choosing one name resolution service over another. - -.Sample DNS zone database -[%collapsible] -==== -[source,text] -$TTL 1W -@ IN SOA ns1.example.com. root ( - 2019070700 ; serial - 3H ; refresh (3 hours) - 30M ; retry (30 minutes) - 2W ; expiry (2 weeks) - 1W ) ; minimum (1 week) - IN NS ns1.example.com. - IN MX 10 smtp.example.com. -; -; -ns1 IN A 192.168.1.5 -smtp IN A 192.168.1.5 -; -helper IN A 192.168.1.5 -helper.ocp4 IN A 192.168.1.5 -; -; The api identifies the IP of your load balancer. -api.ocp4 IN A 192.168.1.5 -api-int.ocp4 IN A 192.168.1.5 -; -; The wildcard also identifies the load balancer. -*.apps.ocp4 IN A 192.168.1.5 -; -; Create an entry for the bootstrap host. -bootstrap.ocp4 IN A 192.168.1.96 -; -; Create entries for the master hosts. -master0.ocp4 IN A 192.168.1.97 -master1.ocp4 IN A 192.168.1.98 -master2.ocp4 IN A 192.168.1.99 -; -; Create entries for the worker hosts. -worker0.ocp4 IN A 192.168.1.11 -worker1.ocp4 IN A 192.168.1.7 -; -;EOF -==== - -The following example BIND zone file shows sample PTR records for reverse name -resolution. - -.Sample DNS zone database for reverse records -[%collapsible] -==== -[source,text] -$TTL 1W -@ IN SOA ns1.example.com. root ( - 2019070700 ; serial - 3H ; refresh (3 hours) - 30M ; retry (30 minutes) - 2W ; expiry (2 weeks) - 1W ) ; minimum (1 week) - IN NS ns1.example.com. -; -; The syntax is "last octet" and the host must have an FQDN -; with a trailing dot. -97 IN PTR master0.ocp4.example.com. -98 IN PTR master1.ocp4.example.com. -99 IN PTR master2.ocp4.example.com. -; -96 IN PTR bootstrap.ocp4.example.com. -; -5 IN PTR api.ocp4.example.com. -5 IN PTR api-int.ocp4.example.com. -; -11 IN PTR worker0.ocp4.example.com. -7 IN PTR worker1.ocp4.example.com. -; -;EOF -==== - -[NOTE] -==== -For clusters using installer-provisioned infrastructure, only the DNS records must be added. -==== diff --git a/modules/installation-extracting-infraid.adoc b/modules/installation-extracting-infraid.adoc deleted file mode 100644 index 33e9d88aa0e5..000000000000 --- a/modules/installation-extracting-infraid.adoc +++ /dev/null @@ -1,196 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc - -ifeval::["{context}" == "installing-aws-user-infra"] -:cp-first: Amazon Web Services -:cp: AWS -:cp-template: CloudFormation -:aws: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-aws"] -:cp-first: Amazon Web Services -:cp: AWS -:cp-template: CloudFormation -:aws: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:cp-first: Microsoft Azure -:cp: Azure -:cp-template-first: Azure Resource Manager -:cp-template: ARM -:azure: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra"] -:cp-first: Google Cloud Platform -:cp: GCP -:cp-template: Deployment Manager -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:cp-first: Google Cloud Platform -:cp: GCP -:cp-template: Deployment Manager -:gcp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:cp-first: Google Cloud Platform -:cp: GCP -:cp-template: Deployment Manager -:gcp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:cp-first: VMware vSphere -:cp: vSphere -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:cp-first: VMware vSphere -:cp: vSphere -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-network-customizations"] -:cp-first: VMware vSphere -:cp: vSphere -:vsphere: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:cp-first: VMware Cloud on AWS -:cp: VMC -:vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-user-infra"] -:cp-first: VMware Cloud on AWS -:cp: VMC -:vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations-user-infra"] -:cp-first: VMware Cloud on AWS -:cp: VMC -:vmc: -endif::[] - -[id="installation-extracting-infraid_{context}"] -= Extracting the infrastructure name - -ifdef::aws,gcp[] -The Ignition config files contain a unique cluster identifier that you can use to -uniquely identify your cluster in {cp-first} ({cp}). The infrastructure name is also used to locate the appropriate {cp} resources during an {product-title} installation. The provided {cp-template} -templates contain references to this infrastructure name, so you must extract -it. -endif::aws,gcp[] - -ifdef::azure[] -The Ignition config files contain a unique cluster identifier that you can use to -uniquely identify your cluster in {cp-first}. The provided {cp-template-first} ({cp-template}) -templates contain references to this infrastructure name, so you must extract -it. -endif::azure[] - -ifdef::vsphere,vmc[] -The Ignition config files contain a unique cluster identifier that you can use to -uniquely identify your cluster in {cp-first}. If you plan to use the cluster identifier as the name of your virtual machine folder, you must extract it. -endif::vsphere,vmc[] - -.Prerequisites - -* You obtained the {product-title} installation program and the pull secret for your cluster. -* You generated the Ignition config files for your cluster. -* You installed the `jq` package. - -.Procedure - -* To extract and view the infrastructure name from the Ignition config file -metadata, run the following command: -+ -[source,terminal] ----- -$ jq -r .infraID <installation_directory>/metadata.json <1> ----- -<1> For `<installation_directory>`, specify the path to the directory that you stored the -installation files in. -+ -.Example output -[source,terminal] ----- -openshift-vw9j6 <1> ----- -<1> The output of this command is your cluster name and a random string. - -ifeval::["{context}" == "installing-aws-user-infra"] -:!cp-first: -:!cp: -:!cp-template: -:!aws: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-aws"] -:!cp-first: -:!cp: -:!cp-template: -:!aws: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:!cp-first: -:!cp: -:!cp-template-first: -:!cp-template: -:!azure: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra"] -:!cp-first: -:!cp: -:!cp-template: -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!cp-first: Google Cloud Platform -:!cp: GCP -:!cp-template: Deployment Manager -:!gcp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:!cp-first: -:!cp: -:!cp-template: -:!gcp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!cp-first: VMware vSphere -:!cp: vSphere -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:!cp-first: VMware vSphere -:!cp: vSphere -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-network-customizations"] -:!cp-first: VMware vSphere -:!cp: vSphere -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!cp-first: VMware Cloud on AWS -:!cp: VMC -:!vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-user-infra"] -:!cp-first: VMware Cloud on AWS -:!cp: VMC -:!vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations-user-infra"] -:!cp-first: VMware Cloud on AWS -:!cp: VMC -:!vmc: -endif::[] diff --git a/modules/installation-gcp-config-yaml.adoc b/modules/installation-gcp-config-yaml.adoc deleted file mode 100644 index 84bf09ec96c0..000000000000 --- a/modules/installation-gcp-config-yaml.adoc +++ /dev/null @@ -1,184 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-network-customizations.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_gcp/installing-gcp-private.adoc - -ifeval::["{context}" == "installing-gcp-network-customizations"] -:with-networking: -endif::[] -ifeval::["{context}" != "installing-gcp-network-customizations"] -:without-networking: -endif::[] -ifeval::["{context}" == "installing-gcp-vpc"] -:vpc: -endif::[] -ifeval::["{context}" == "installing-gcp-private"] -:private: -:vpc: -endif::[] - -[id="installation-gcp-config-yaml_{context}"] -= Sample customized `install-config.yaml` file for GCP - -You can customize the `install-config.yaml` file to specify more details about your {product-title} cluster's platform or modify the values of the required parameters. - -[IMPORTANT] -==== -This sample YAML file is provided for reference only. You must obtain your `install-config.yaml` file by using the installation program and modify it. -==== - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com <1> -controlPlane: <2> - hyperthreading: Enabled <3> <4> - name: master - platform: - gcp: - type: n2-standard-4 - zones: - - us-central1-a - - us-central1-c - osDisk: - diskType: pd-ssd - diskSizeGB: 256 - encryptionKey: <5> - kmsKey: - name: worker-key - keyRing: test-machine-keys - location: global - projectID: project-id - replicas: 3 -compute: <2> -- hyperthreading: Enabled <3> - name: worker - platform: - gcp: - type: n2-standard-4 - zones: - - us-central1-a - - us-central1-c - osDisk: - diskType: pd-standard - diskSizeGB: 128 - encryptionKey: <5> - kmsKey: - name: worker-key - keyRing: test-machine-keys - location: global - projectID: project-id - replicas: 3 -metadata: - name: test-cluster <1> -ifdef::without-networking[] -networking: -endif::[] -ifdef::with-networking[] -networking: <2> -endif::[] - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineNetwork: - - cidr: 10.0.0.0/16 -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] - serviceNetwork: - - 172.30.0.0/16 -platform: - gcp: - projectID: openshift-production <1> - region: us-central1 <1> -ifdef::vpc[] - network: existing_vpc <6> - controlPlaneSubnet: control_plane_subnet <7> - computeSubnet: compute_subnet <8> -endif::vpc[] -pullSecret: '{"auths": ...}' <1> -ifndef::vpc[] -ifndef::openshift-origin[] -fips: false <6> -sshKey: ssh-ed25519 AAAA... <7> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <6> -endif::openshift-origin[] -endif::vpc[] -ifdef::vpc[] -ifndef::openshift-origin[] -fips: false <9> -sshKey: ssh-ed25519 AAAA... <10> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <9> -endif::openshift-origin[] -endif::vpc[] -ifdef::private[] -ifndef::openshift-origin[] -publish: Internal <11> -endif::openshift-origin[] -ifdef::openshift-origin[] -publish: Internal <10> -endif::openshift-origin[] -endif::private[] ----- -<1> Required. The installation program prompts you for this value. -<2> If you do not provide these parameters and values, the installation program provides the default value. -<3> The `controlPlane` section is a single mapping, but the compute section is a sequence of mappings. To meet the requirements of the different data structures, the first line of the `compute` section must begin with a hyphen, `-`, and the first line of the `controlPlane` section must not. Although both sections currently define a single machine pool, it is possible that future versions of {product-title} will support defining multiple compute pools during installation. Only one control plane pool is used. -<4> Whether to enable or disable simultaneous multithreading, or `hyperthreading`. By default, simultaneous multithreading is enabled to increase the performance of your machines' cores. You can disable it by setting the parameter value to `Disabled`. If you disable simultaneous multithreading in some cluster machines, you must disable it in all cluster machines. -+ -[IMPORTANT] -==== -If you disable simultaneous multithreading, ensure that your capacity planning accounts for the dramatically decreased machine performance. Use larger machine types, such as `n1-standard-8`, for your machines if you disable simultaneous multithreading. -==== -<5> Optional: The custom encryption key section to encrypt both virtual machines and persistent volumes. Your default compute service account must have the permissions granted to use your KMS key and have the correct IAM role assigned. The default service account name follows the `service-<project_number>@compute-system.iam.gserviceaccount.com` pattern. For more information on granting the correct permissions for your service account, see "Machine management" -> "Creating machine sets" -> "Creating a machine set on GCP". -ifdef::vpc[] -<6> If you use an existing VPC, specify its name. -<7> If you use an existing VPC, specify the name of the existing subnet to deploy the control plane machines to. The subnet must belong to the VPC that you specified. -<8> If you use an existing VPC, specify the name of the existing subnet to deploy the compute machines to. The subnet must belong to the VPC that you specified. -ifndef::openshift-origin[] -<9> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<10> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<9> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -endif::vpc[] -ifndef::vpc[] -ifndef::openshift-origin[] -<6> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<7> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<6> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -endif::vpc[] -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -ifdef::private[] -<11> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster, which cannot be accessed from the Internet. The default value is `External`. -endif::private[] - -ifeval::["{context}" == "installing-gcp-network-customizations"] -:!with-networking: -endif::[] -ifeval::["{context}" != "installing-gcp-network-customizations"] -:!without-networking: -endif::[] -ifeval::["{context}" == "installing-gcp-vpc"] -:!vpc: -endif::[] -ifeval::["{context}" == "installing-gcp-private"] -:!private: -:!vpc: -endif::[] diff --git a/modules/installation-gcp-dns.adoc b/modules/installation-gcp-dns.adoc deleted file mode 100644 index acbd310df420..000000000000 --- a/modules/installation-gcp-dns.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-account.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:user-infra-vpc: -endif::[] - -[id="installation-gcp-dns_{context}"] -= Configuring DNS for GCP - -To install {product-title}, the Google Cloud Platform (GCP) account you use must -have a dedicated public hosted zone -ifndef::user-infra-vpc[] -in the same project that you host the {product-title} cluster. -endif::user-infra-vpc[] -ifdef::user-infra-vpc[] -in the project that hosts the shared VPC that you install the cluster into. -endif::user-infra-vpc[] -This zone must be authoritative for the domain. The -DNS service provides cluster DNS resolution and name lookup for external -connections to the cluster. - -.Procedure - -. Identify your domain, or subdomain, and registrar. You can transfer an existing domain and -registrar or obtain a new one through GCP or another source. -+ -[NOTE] -==== -If you purchase a new domain, it can take time for the relevant DNS -changes to propagate. For more information about purchasing domains -through Google, see link:https://domains.google/[Google Domains]. -==== - -. Create a public hosted zone for your domain or subdomain in your GCP project. See -link:https://cloud.google.com/dns/zones/#creating_public_zones[Creating public zones] -in the GCP documentation. -+ -Use an appropriate root domain, such as `openshiftcorp.com`, or subdomain, -such as `clusters.openshiftcorp.com`. - -. Extract the new authoritative name servers from the hosted zone records. See -link:https://cloud.google.com/dns/docs/update-name-servers#look_up_your_name_servers[Look up your Cloud DNS name servers] -in the GCP documentation. -+ -You typically have four name servers. - -. Update the registrar records for the name servers that your domain -uses. For example, if you registered your domain to Google Domains, see the -following topic in the Google Domains Help: -link:https://support.google.com/domains/answer/3290309?hl=en[How to switch to custom name servers]. - -. If you migrated your root domain to Google Cloud DNS, migrate your DNS records. See link:https://cloud.google.com/dns/docs/migrating[Migrating to Cloud DNS] in the GCP documentation. - -. If you use a subdomain, follow your company's procedures to add its delegation records to the parent domain. This process might include a request to your company's IT department or the division that controls the root domain and DNS services for your company. - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!user-infra-vpc: -endif::[] diff --git a/modules/installation-gcp-enabling-api-services.adoc b/modules/installation-gcp-enabling-api-services.adoc deleted file mode 100644 index 4152d07faeb1..000000000000 --- a/modules/installation-gcp-enabling-api-services.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-account.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-gcp-user-infra"] -:template: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:template: -endif::[] -ifeval::["{context}" == "installing-gcp-restricted-networks"] -:template: -endif::[] - -[id="installation-gcp-enabling-api-services_{context}"] -= Enabling API services in GCP - -Your Google Cloud Platform (GCP) project requires access to several API services -to complete {product-title} installation. - -.Prerequisites - -* You created a project to host your cluster. - -.Procedure - -* Enable the following required API services in the project that hosts your -cluster. See -link:https://cloud.google.com/service-usage/docs/enable-disable#enabling[Enabling services] -in the GCP documentation. -+ -.Required API services -[cols="2a,3a",options="header"] -|=== -|API service |Console service name - -ifdef::template[] -|Cloud Deployment Manager V2 API -|`deploymentmanager.googleapis.com` -endif::template[] - -|Compute Engine API -|`compute.googleapis.com` - -|Google Cloud APIs -|`cloudapis.googleapis.com` - -|Cloud Resource Manager API -|`cloudresourcemanager.googleapis.com` - -|Google DNS API -|`dns.googleapis.com` - -|IAM Service Account Credentials API -|`iamcredentials.googleapis.com` - -|Identity and Access Management (IAM) API -|`iam.googleapis.com` - -|Service Management API -|`servicemanagement.googleapis.com` - -|Service Usage API -|`serviceusage.googleapis.com` - -|Google Cloud Storage JSON API -|`storage-api.googleapis.com` - -|Cloud Storage -|`storage-component.googleapis.com` - -|=== - -ifeval::["{context}" == "installing-gcp-user-infra"] -:!template: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!template: -endif::[] -ifeval::["{context}" == "installing-gcp-restricted-networks"] -:!template: -endif::[] diff --git a/modules/installation-gcp-install-cli.adoc b/modules/installation-gcp-install-cli.adoc deleted file mode 100644 index 978306ba006b..000000000000 --- a/modules/installation-gcp-install-cli.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-gcp-install-cli_{context}"] -= Installing and configuring CLI tools for GCP - -To install {product-title} on Google Cloud Platform (GCP) using user-provisioned -infrastructure, you must install and configure the CLI tools for GCP. - -.Prerequisites - -* You created a project to host your cluster. -* You created a service account and granted it the required permissions. - -.Procedure - -. Install the following binaries in `$PATH`: -+ --- -* `gcloud` -* `gsutil` --- -+ -See link:https://cloud.google.com/sdk/docs/#install_the_latest_cloud_tools_version_cloudsdk_current_version[Install the latest Cloud SDK version] -in the GCP documentation. - -. Authenticate using the `gcloud` tool with your configured service account. -+ -See link:https://cloud.google.com/sdk/docs/authorizing#authorizing_with_a_service_account[Authorizing with a service account] in the GCP documentation. diff --git a/modules/installation-gcp-limits.adoc b/modules/installation-gcp-limits.adoc deleted file mode 100644 index d0ea6720d949..000000000000 --- a/modules/installation-gcp-limits.adoc +++ /dev/null @@ -1,105 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-account.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-gcp-user-infra"] -:template: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:template: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:template: -endif::[] - -[id="installation-gcp-limits_{context}"] -= GCP account limits - -The {product-title} cluster uses a number of Google Cloud Platform (GCP) -components, but the default -link:https://cloud.google.com/docs/quota[Quotas] -do not affect your ability to install a default {product-title} cluster. - -A default cluster, which contains three compute and three control plane machines, -uses the following resources. Note that some resources are required only during -the bootstrap process and are removed after the cluster deploys. - -.GCP resources used in a default cluster - -[cols="2a,2a,2a,2a,2a",options="header"] -|=== -|Service -|Component -|Location -|Total resources required -|Resources removed after bootstrap - -ifeval::["{context}" == "installing-gcp-account"] -|Service account |IAM |Global |5 |0 -|Firewall rules |Compute |Global |11 |1 -|Forwarding rules |Compute |Global |2 |0 -|In-use global IP addresses |Compute |Global |4 |1 -|Health checks |Compute |Global |3 |0 -|Images |Compute |Global |1 |0 -|Networks |Compute |Global |2 |0 -|Static IP addresses |Compute |Region |4 |1 -|Routers |Compute |Global |1 |0 -|Routes |Compute |Global |2 |0 -|Subnetworks |Compute |Global |2 |0 -|Target pools |Compute |Global |3 |0 -|CPUs |Compute |Region |28 |4 -|Persistent disk SSD (GB) |Compute |Region |896 |128 -endif::[] - -ifdef::template[] -|Service account |IAM |Global |5 |0 -|Firewall rules |Networking |Global |11 |1 -|Forwarding rules |Compute |Global |2 |0 -// |In-use IP addresses global |Networking |Global |4 |1 -|Health checks |Compute |Global |2 |0 -|Images |Compute |Global |1 |0 -|Networks |Networking |Global |1 |0 -// |Static IP addresses |Compute |Region |4 |1 -|Routers |Networking |Global |1 |0 -|Routes |Networking |Global |2 |0 -|Subnetworks |Compute |Global |2 |0 -|Target pools |Networking |Global |2 |0 -// |CPUs |Compute |Region |28 |4 -// |Persistent Disk SSD (GB) |Compute |Region |896 |128 -endif::template[] -|=== - -[NOTE] -==== -If any of the quotas are insufficient during installation, the installation program displays an error that states both which quota was exceeded and the region. -==== - -Be sure to consider your actual cluster size, planned cluster growth, and any usage from other clusters that are associated with your account. The CPU, static IP addresses, and persistent disk SSD (storage) quotas are the ones that are most likely to be insufficient. - -If you plan to deploy your cluster in one of the following regions, you will exceed the maximum storage quota and are likely to exceed the CPU quota limit: - -* `asia-east2` -* `asia-northeast2` -* `asia-south1` -* `australia-southeast1` -* `europe-north1` -* `europe-west2` -* `europe-west3` -* `europe-west6` -* `northamerica-northeast1` -* `southamerica-east1` -* `us-west2` - -You can increase resource quotas from the link:https://console.cloud.google.com/iam-admin/quotas[GCP console], but you might need to file a support ticket. Be sure to plan your cluster size early so that you can allow time to resolve the support ticket before you install your {product-title} cluster. - -ifeval::["{context}" == "installing-gcp-user-infra"] -:!template: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!template: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:!template: -endif::[] diff --git a/modules/installation-gcp-permissions.adoc b/modules/installation-gcp-permissions.adoc deleted file mode 100644 index 3c1060791ff8..000000000000 --- a/modules/installation-gcp-permissions.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-account.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-gcp-user-infra"] -:template: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:template: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:template: -endif::[] - -[id="installation-gcp-permissions_{context}"] -= Required GCP permissions - -When you attach the `Owner` role to the service account that you create, you -grant that service account all permissions, including those that are required to -install {product-title}. To deploy an {product-title} cluster, the service -account requires the following permissions. If you deploy your cluster into an existing VPC, the service account does not require certain networking permissions, which are noted in the following lists: - -.Required roles for the installation program -* Compute Admin -* Security Admin -* Service Account Admin -* Service Account User -* Storage Admin - -.Required roles for creating network resources during installation -* DNS Administrator - -ifdef::template[] -.Required roles for user-provisioned GCP infrastructure -* Deployment Manager Editor -* Service Account Key Admin -endif::template[] - -.Optional roles -For the cluster to create new limited credentials for its Operators, add -the following role: - -* Service Account Key Admin - -The roles are applied to the service accounts that the control plane and compute -machines use: - -.GCP service account permissions -[cols="2a,2a",options="header"] -|=== - -|Account -|Roles - -.5+|Control Plane -|`roles/compute.instanceAdmin` -|`roles/compute.networkAdmin` -|`roles/compute.securityAdmin` -|`roles/storage.admin` -|`roles/iam.serviceAccountUser` - -.2+|Compute -|`roles/compute.viewer` -|`roles/storage.admin` -|=== - -ifeval::["{context}" == "installing-gcp-user-infra"] -:!template: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:!template: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!template: -endif::[] diff --git a/modules/installation-gcp-project.adoc b/modules/installation-gcp-project.adoc deleted file mode 100644 index 795d03a02117..000000000000 --- a/modules/installation-gcp-project.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-account.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-gcp-project_{context}"] -= Creating a GCP project - -To install {product-title}, you must create a project in your Google Cloud Platform (GCP) account to host the cluster. - -.Procedure - -* Create a project to host your {product-title} cluster. See -link:https://cloud.google.com/resource-manager/docs/creating-managing-projects[Creating and Managing Projects] in the GCP documentation. -+ -[IMPORTANT] -==== -Your GCP project must use the Premium Network Service Tier if you are using installer-provisioned infrastructure. The Standard Network Service Tier is not supported for clusters installed using the installation program. The installation program configures internal load balancing for the `api-int.<cluster_name>.<base_domain>` URL; the Premium Tier is required for internal load balancing. -==== diff --git a/modules/installation-gcp-regions.adoc b/modules/installation-gcp-regions.adoc deleted file mode 100644 index 928ea957a4a4..000000000000 --- a/modules/installation-gcp-regions.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-account.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-gcp-regions_{context}"] -= Supported GCP regions - -You can deploy an {product-title} cluster to the following Google Cloud Platform (GCP) -regions: - -* `asia-east1` (Changhua County, Taiwan) -* `asia-east2` (Hong Kong) -* `asia-northeast1` (Tokyo, Japan) -* `asia-northeast2` (Osaka, Japan) -* `asia-south1` (Mumbai, India) -* `asia-southeast1` (Jurong West, Singapore) -* `australia-southeast1` (Sydney, Australia) -* `europe-north1` (Hamina, Finland) -* `europe-west1` (St. Ghislain, Belgium) -* `europe-west2` (London, England, UK) -* `europe-west3` (Frankfurt, Germany) -* `europe-west4` (Eemshaven, Netherlands) -* `europe-west6` (Zürich, Switzerland) -* `northamerica-northeast1` (Montréal, Québec, Canada) -* `southamerica-east1` (São Paulo, Brazil) -* `us-central1` (Council Bluffs, Iowa, USA) -* `us-east1` (Moncks Corner, South Carolina, USA) -* `us-east4` (Ashburn, Northern Virginia, USA) -* `us-west1` (The Dalles, Oregon, USA) -* `us-west2` (Los Angeles, California, USA) diff --git a/modules/installation-gcp-service-account.adoc b/modules/installation-gcp-service-account.adoc deleted file mode 100644 index 43a595699afa..000000000000 --- a/modules/installation-gcp-service-account.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-account.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-gcp-service-account_{context}"] -= Creating a service account in GCP - -{product-title} requires a Google Cloud Platform (GCP) service account that provides authentication and authorization to access data in the Google APIs. If you do not have an existing IAM service account that contains the required roles in your project, you must create one. - -.Prerequisites - -* You created a project to host your cluster. - -.Procedure - -. Create a service account in the project that you use to host your -{product-title} cluster. See -link:https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating_a_service_account[Creating a service account] -in the GCP documentation. - -. Grant the service account the appropriate permissions. You can either -grant the individual permissions that follow or assign the `Owner` role to it. -See link:https://cloud.google.com/iam/docs/granting-roles-to-service-accounts#granting_access_to_a_service_account_for_a_resource[Granting roles to a service account for specific resources]. -+ -[NOTE] -==== -While making the service account an owner of the project is the easiest way to gain the required permissions, it means that service account has complete control over the project. You must determine if the risk that comes from offering that power is acceptable. -==== - -. Create the service account key in JSON format. -See link:https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys[Creating service account keys] -in the GCP documentation. -+ -The service account key is required to create a cluster. diff --git a/modules/installation-gcp-user-infra-adding-ingress.adoc b/modules/installation-gcp-user-infra-adding-ingress.adoc deleted file mode 100644 index fd082c9e0751..000000000000 --- a/modules/installation-gcp-user-infra-adding-ingress.adoc +++ /dev/null @@ -1,123 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:shared-vpc: -endif::[] - -[id="installation-gcp-user-infra-adding-ingress_{context}"] -ifndef::shared-vpc[] -= Optional: Adding the ingress DNS records -endif::shared-vpc[] -ifdef::shared-vpc[] -= Adding the ingress DNS records -endif::shared-vpc[] - -If you removed the DNS Zone configuration when creating Kubernetes manifests and -generating Ignition configs, you must manually create DNS records that point at -the ingress load balancer. You can create either a wildcard -`*.apps.{baseDomain}.` or specific records. You can use A, CNAME, and other -records per your requirements. - -.Prerequisites - -* Configure a GCP account. -* Remove the DNS Zone configuration when creating Kubernetes manifests and -generating Ignition configs. -* Create and configure a VPC and associated subnets in GCP. -* Create and configure networking and load balancers in GCP. -* Create control plane and compute roles. -* Create the bootstrap machine. -* Create the control plane machines. -* Create the worker machines. - -.Procedure - -. Wait for the Ingress router to create a load balancer and populate the `EXTERNAL-IP` field: -+ -[source,terminal] ----- -$ oc -n openshift-ingress get service router-default ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -router-default LoadBalancer 172.30.18.154 35.233.157.184 80:32288/TCP,443:31215/TCP 98 ----- - -. Add the A record to your zones: -** To use A records: -... Export the variable for the router IP address: -+ -[source,terminal] ----- -$ export ROUTER_IP=`oc -n openshift-ingress get service router-default --no-headers | awk '{print $4}'` ----- -... Add the A record to the private zones: -+ -ifndef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction add ${ROUTER_IP} --name \*.apps.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 300 --type A --zone ${INFRA_ID}-private-zone -$ gcloud dns record-sets transaction execute --zone ${INFRA_ID}-private-zone ----- -endif::shared-vpc[] -ifdef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction add ${ROUTER_IP} --name \*.apps.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 300 --type A --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction execute --zone ${INFRA_ID}-private-zone --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} ----- -endif::shared-vpc[] -... For an external cluster, also add the A record to the public zones: -+ -ifndef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${BASE_DOMAIN_ZONE_NAME} -$ gcloud dns record-sets transaction add ${ROUTER_IP} --name \*.apps.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 300 --type A --zone ${BASE_DOMAIN_ZONE_NAME} -$ gcloud dns record-sets transaction execute --zone ${BASE_DOMAIN_ZONE_NAME} ----- -endif::shared-vpc[] -ifdef::shared-vpc[] -[source,terminal] ----- -$ if [ -f transaction.yaml ]; then rm transaction.yaml; fi -$ gcloud dns record-sets transaction start --zone ${BASE_DOMAIN_ZONE_NAME} --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction add ${ROUTER_IP} --name \*.apps.${CLUSTER_NAME}.${BASE_DOMAIN}. --ttl 300 --type A --zone ${BASE_DOMAIN_ZONE_NAME} --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} -$ gcloud dns record-sets transaction execute --zone ${BASE_DOMAIN_ZONE_NAME} --project ${HOST_PROJECT} --account ${HOST_PROJECT_ACCOUNT} ----- -endif::shared-vpc[] - -** To add explicit domains instead of using a wildcard, -create entries for each of the cluster's current routes: -+ -[source,terminal] ----- -$ oc get --all-namespaces -o jsonpath='{range .items[*]}{range .status.ingress[*]}{.host}{"\n"}{end}{end}' routes ----- -+ -.Example output -[source,terminal] ----- -oauth-openshift.apps.your.cluster.domain.example.com -console-openshift-console.apps.your.cluster.domain.example.com -downloads-openshift-console.apps.your.cluster.domain.example.com -alertmanager-main-openshift-monitoring.apps.your.cluster.domain.example.com -grafana-openshift-monitoring.apps.your.cluster.domain.example.com -prometheus-k8s-openshift-monitoring.apps.your.cluster.domain.example.com ----- - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!shared-vpc: -endif::[] diff --git a/modules/installation-gcp-user-infra-completing.adoc b/modules/installation-gcp-user-infra-completing.adoc deleted file mode 100644 index fb3314264694..000000000000 --- a/modules/installation-gcp-user-infra-completing.adoc +++ /dev/null @@ -1,129 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -[id="installation-gcp-user-infra-installation_{context}"] -= Completing a GCP installation on user-provisioned infrastructure - -After you start the {product-title} installation on Google Cloud Platform (GCP) -user-provisioned infrastructure, you can monitor the cluster events until the -cluster is ready. - -.Prerequisites - -* Deploy the bootstrap machine for an {product-title} cluster on user-provisioned GCP infrastructure. -* Install the `oc` CLI and log in. - -.Procedure - -. Complete the cluster installation: -+ -[source,terminal] ----- -$ ./openshift-install --dir=<installation_directory> wait-for install-complete <1> ----- -+ -.Example output -[source,terminal] ----- -INFO Waiting up to 30m0s for the cluster to initialize... ----- -<1> For `<installation_directory>`, specify the path to the directory that you -stored the installation files in. -+ -[IMPORTANT] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== - -. Observe the running state of your cluster. -+ --- -.. Run the following command to view the current cluster version and status: -+ -[source,terminal] ----- -$ oc get clusterversion ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING SINCE STATUS -version False True 24m Working towards 4.5.4: 99% complete ----- - -.. Run the following command to view the Operators managed on the control plane by -the Cluster Version Operator (CVO): -+ -[source,terminal] ----- -$ oc get clusteroperators ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -authentication 4.5.4 True False False 7m56s -cloud-credential 4.5.4 True False False 31m -cluster-autoscaler 4.5.4 True False False 16m -console 4.5.4 True False False 10m -csi-snapshot-controller 4.5.4 True False False 16m -dns 4.5.4 True False False 22m -etcd 4.5.4 False False False 25s -image-registry 4.5.4 True False False 16m -ingress 4.5.4 True False False 16m -insights 4.5.4 True False False 17m -kube-apiserver 4.5.4 True False False 19m -kube-controller-manager 4.5.4 True False False 20m -kube-scheduler 4.5.4 True False False 20m -kube-storage-version-migrator 4.5.4 True False False 16m -machine-api 4.5.4 True False False 22m -machine-config 4.5.4 True False False 22m -marketplace 4.5.4 True False False 16m -monitoring 4.5.4 True False False 10m -network 4.5.4 True False False 23m -node-tuning 4.5.4 True False False 23m -openshift-apiserver 4.5.4 True False False 17m -openshift-controller-manager 4.5.4 True False False 15m -openshift-samples 4.5.4 True False False 16m -operator-lifecycle-manager 4.5.4 True False False 22m -operator-lifecycle-manager-catalog 4.5.4 True False False 22m -operator-lifecycle-manager-packageserver 4.5.4 True False False 18m -service-ca 4.5.4 True False False 23m -service-catalog-apiserver 4.5.4 True False False 23m -service-catalog-controller-manager 4.5.4 True False False 23m -storage 4.5.4 True False False 17m ----- - -.. Run the following command to view your cluster pods: -+ -[source,terminal] ----- -$ oc get pods --all-namespaces ----- -+ -.Example output -[source,terminal] ----- -NAMESPACE NAME READY STATUS RESTARTS AGE -kube-system etcd-member-ip-10-0-3-111.us-east-2.compute.internal 1/1 Running 0 35m -kube-system etcd-member-ip-10-0-3-239.us-east-2.compute.internal 1/1 Running 0 37m -kube-system etcd-member-ip-10-0-3-24.us-east-2.compute.internal 1/1 Running 0 35m -openshift-apiserver-operator openshift-apiserver-operator-6d6674f4f4-h7t2t 1/1 Running 1 37m -openshift-apiserver apiserver-fm48r 1/1 Running 0 30m -openshift-apiserver apiserver-fxkvv 1/1 Running 0 29m -openshift-apiserver apiserver-q85nm 1/1 Running 0 29m -... -openshift-service-ca-operator openshift-service-ca-operator-66ff6dc6cd-9r257 1/1 Running 0 37m -openshift-service-ca apiservice-cabundle-injector-695b6bcbc-cl5hm 1/1 Running 0 35m -openshift-service-ca configmap-cabundle-injector-8498544d7-25qn6 1/1 Running 0 35m -openshift-service-ca service-serving-cert-signer-6445fc9c6-wqdqn 1/1 Running 0 35m -openshift-service-catalog-apiserver-operator openshift-service-catalog-apiserver-operator-549f44668b-b5q2w 1/1 Running 0 32m -openshift-service-catalog-controller-manager-operator openshift-service-catalog-controller-manager-operator-b78cr2lnm 1/1 Running 0 31m ----- --- -+ -When the current cluster version is `AVAILABLE`, the installation is complete. diff --git a/modules/installation-gcp-user-infra-config-host-project-vpc.adoc b/modules/installation-gcp-user-infra-config-host-project-vpc.adoc deleted file mode 100644 index 26537f3badf3..000000000000 --- a/modules/installation-gcp-user-infra-config-host-project-vpc.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -[id="installation-gcp-user-infra-config-host-project-vpc_{context}"] -= Configuring the GCP project that hosts your shared VPC network - -If you use a shared Virtual Private Cloud (VPC) to host your {product-title} cluster in Google Cloud Platform (GCP), you must configure the project that hosts it. - -[NOTE] -==== -If you already have a project that hosts the shared VPC network, review this section to ensure that the project meets all of the requirements to install an {product-title} cluster. -==== - -.Procedure - -. Create a project to host the shared VPC for your {product-title} cluster. See -link:https://cloud.google.com/resource-manager/docs/creating-managing-projects[Creating and Managing Projects] in the GCP documentation. - -. Create a service account in the project that hosts your shared VPC. See -link:https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating_a_service_account[Creating a service account] -in the GCP documentation. - -. Grant the service account the appropriate permissions. You can either -grant the individual permissions that follow or assign the `Owner` role to it. -See link:https://cloud.google.com/iam/docs/granting-roles-to-service-accounts#granting_access_to_a_service_account_for_a_resource[Granting roles to a service account for specific resources]. -+ -[NOTE] -==== -While making the service account an owner of the project is the easiest way to gain the required permissions, it means that service account has complete control over the project. You must determine if the risk that comes from offering that power is acceptable. - -The service account for the project that hosts the shared VPC network requires the following roles: - -* Compute Network User -* Compute Security Admin -* Deployment Manager Editor -* DNS Administrator -* Security Admin -* Network Management Admin -==== diff --git a/modules/installation-gcp-user-infra-rhcos.adoc b/modules/installation-gcp-user-infra-rhcos.adoc deleted file mode 100644 index c7adebdfcf87..000000000000 --- a/modules/installation-gcp-user-infra-rhcos.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc - -[id="installation-gcp-user-infra-rhcos_{context}"] -= Creating the {op-system} cluster image for the GCP infrastructure - -You must use a valid {op-system-first} image for Google Cloud Platform (GCP) for -your {product-title} nodes. - -.Procedure - -ifndef::openshift-origin[] -. Obtain the {op-system} image from the -link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] -page. -+ -[IMPORTANT] -==== -The {op-system} images might not change with every release of {product-title}. -You must download an image with the highest version that is -less than or equal to the {product-title} version that you install. Use the image version -that matches your {product-title} version if it is available. -==== -+ -The file name contains the {product-title} version number in the format -`rhcos-<version>-<arch>-gcp.<arch>.tar.gz`. -endif::openshift-origin[] -ifdef::openshift-origin[] -. Obtain the {op-system} image from the -link:https://getfedora.org/en/coreos/download?tab=cloud_operators&stream=stable[{op-system} Downloads] page -endif::openshift-origin[] - -. Create the Google storage bucket: -+ -[source,terminal] ----- -$ gsutil mb gs://<bucket_name> ----- - -. Upload the {op-system} image to the Google storage bucket: -+ -[source,terminal] ----- -$ gsutil cp <downloaded_image_file_path>/rhcos-<version>-x86_64-gcp.x86_64.tar.gz gs://<bucket_name> ----- - -. Export the uploaded {op-system} image location as a variable: -+ -[source,terminal] ----- -$ export IMAGE_SOURCE=`gs://<bucket_name>/rhcos-<version>-x86_64-gcp.x86_64.tar.gz` ----- - -. Create the cluster image: -+ -[source,terminal] ----- -$ gcloud compute images create "${INFRA_ID}-rhcos-image" \ - --source-uri="${IMAGE_SOURCE}" ----- diff --git a/modules/installation-gcp-user-infra-shared-vpc-config-yaml.adoc b/modules/installation-gcp-user-infra-shared-vpc-config-yaml.adoc deleted file mode 100644 index f276c9973c3c..000000000000 --- a/modules/installation-gcp-user-infra-shared-vpc-config-yaml.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -[id="installation-gcp-user-infra-shared-vpc-config-yaml_{context}"] -= Sample customized `install-config.yaml` file for GCP - -You can customize the `install-config.yaml` file to specify more details about your {product-title} cluster's platform or modify the values of the required parameters. - -[IMPORTANT] -==== -This sample YAML file is provided for reference only. You must obtain your `install-config.yaml` file by using the installation program and modify it. -==== - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com <1> -controlPlane: <2> - hyperthreading: Enabled <3> <4> - name: master - platform: - gcp: - type: n2-standard-4 - zones: - - us-central1-a - - us-central1-c - replicas: 3 -compute: <2> -- hyperthreading: Enabled <3> - name: worker - platform: - gcp: - type: n2-standard-4 - zones: - - us-central1-a - - us-central1-c - replicas: 0 -metadata: - name: test-cluster -networking: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineNetwork: - - cidr: 10.0.0.0/16 -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] - serviceNetwork: - - 172.30.0.0/16 -platform: - gcp: - projectID: openshift-production - region: us-central1 <5> -pullSecret: '{"auths": ...}' -ifndef::openshift-origin[] -fips: false <6> -sshKey: ssh-ed25519 AAAA... <7> -publish: Internal <8> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: ssh-ed25519 AAAA... <6> -publish: Internal <7> -endif::openshift-origin[] ----- -<1> Specify the public DNS on the host project. -<2> If you do not provide these parameters and values, the installation program provides the default value. -<3> The `controlPlane` section is a single mapping, but the compute section is a sequence of mappings. To meet the requirements of the different data structures, the first line of the `compute` section must begin with a hyphen, `-`, and the first line of the `controlPlane` section must not. Although both sections currently define a single machine pool, it is possible that future versions of {product-title} will support defining multiple compute pools during installation. Only one control plane pool is used. -<4> Whether to enable or disable simultaneous multithreading, or `hyperthreading`. By default, simultaneous multithreading is enabled to increase the performance of your machines' cores. You can disable it by setting the parameter value to `Disabled`. If you disable simultaneous multithreading in some cluster machines, you must disable it in all cluster machines. -+ -[IMPORTANT] -==== -If you disable simultaneous multithreading, ensure that your capacity planning accounts for the dramatically decreased machine performance. Use larger machine types, such as `n1-standard-8`, for your machines if you disable simultaneous multithreading. -==== -<5> Specify the region that your VPC network is in. -ifndef::openshift-origin[] -<6> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -<7> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -ifdef::openshift-origin[] -<6> You can optionally provide the `sshKey` value that you use to access the machines in your cluster. -endif::openshift-origin[] -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -ifndef::openshift-origin[] -<8> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster, which cannot be accessed from the Internet. The default value is `External`. -To use a shared VPC in a cluster that uses infrastructure that you provision, you must set `publish` to `Internal`. The installation program will no longer be able to access the public DNS zone for the base domain in the host project. -endif::openshift-origin[] -ifdef::openshift-origin[] -<7> How to publish the user-facing endpoints of your cluster. Set `publish` to `Internal` to deploy a private cluster, which cannot be accessed from the Internet. The default value is `External`. -To use a shared VPC in a cluster that uses infrastructure that you provision, you must set `publish` to `Internal`. The installation program will no longer be able to access the public DNS zone for the base domain in the host project. -endif::openshift-origin[] \ No newline at end of file diff --git a/modules/installation-gcp-user-infra-wait-for-bootstrap.adoc b/modules/installation-gcp-user-infra-wait-for-bootstrap.adoc deleted file mode 100644 index af56a3543bae..000000000000 --- a/modules/installation-gcp-user-infra-wait-for-bootstrap.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra-vpc.adoc - -[id="installation-gcp-user-infra-wait-for-bootstrap_{context}"] -= Wait for bootstrap completion and remove bootstrap resources in GCP - -After you create all of the required infrastructure in Google Cloud Platform -(GCP), wait for the bootstrap process to complete on the machines that you -provisioned by using the Ignition config files that you generated with the -installation program. - -.Prerequisites - -* Configure a GCP account. -* Generate the Ignition config files for your cluster. -* Create and configure a VPC and associated subnets in GCP. -* Create and configure networking and load balancers in GCP. -* Create control plane and compute roles. -* Create the bootstrap machine. -* Create the control plane machines. - -.Procedure - -. Change to the directory that contains the installation program and run the -following command: -+ -[source,terminal] ----- -$ ./openshift-install wait-for bootstrap-complete --dir=<installation_directory> \ <1> - --log-level info <2> ----- -<1> For `<installation_directory>`, specify the path to the directory that you -stored the installation files in. -<2> To view different installation details, specify `warn`, `debug`, or -`error` instead of `info`. -+ -If the command exits without a `FATAL` warning, your production control plane -has initialized. - -. Delete the bootstrap resources: -+ -[source,terminal] ----- -$ gcloud compute backend-services remove-backend ${INFRA_ID}-api-internal-backend-service --region=${REGION} --instance-group=${INFRA_ID}-bootstrap-instance-group --instance-group-zone=${ZONE_0} -$ gsutil rm gs://${INFRA_ID}-bootstrap-ignition/bootstrap.ign -$ gsutil rb gs://${INFRA_ID}-bootstrap-ignition -$ gcloud deployment-manager deployments delete ${INFRA_ID}-bootstrap ----- diff --git a/modules/installation-generate-aws-user-infra-install-config.adoc b/modules/installation-generate-aws-user-infra-install-config.adoc deleted file mode 100644 index 9d9d0b7695a4..000000000000 --- a/modules/installation-generate-aws-user-infra-install-config.adoc +++ /dev/null @@ -1,129 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc - -ifeval::["{context}" == "installing-restricted-networks-aws"] -:restricted: -endif::[] - -[id="installation-generate-aws-user-infra-install-config_{context}"] -= Creating the installation configuration file - -Generate and customize the installation configuration file that the -installation program needs to deploy your cluster. - -.Prerequisites - -* You obtained the {product-title} installation program for user-provisioned infrastructure and the pull secret for your cluster. -ifdef::restricted[] -For a restricted network installation, these files are on your mirror host. -endif::restricted[] -* You checked that you are deploying your cluster to a region with an accompanying {op-system-first} AMI published by Red Hat. If you are deploying to a region that requires a custom AMI, such as an AWS GovCloud region, you must create the `install-config.yaml` file manually. - -.Procedure - -. Create the `install-config.yaml` file. -.. Change to the directory that contains the installation program and run the following command: -+ -[source,terminal] ----- -$ ./openshift-install create install-config --dir=<installation_directory> <1> ----- -<1> For `<installation_directory>`, specify the directory name to store the -files that the installation program creates. -+ -[IMPORTANT] -==== -Specify an empty directory. Some installation assets, like bootstrap X.509 -certificates have short expiration intervals, so you must not reuse an -installation directory. If you want to reuse individual files from another -cluster installation, you can copy them into your directory. However, the file -names for the installation assets might change between releases. Use caution -when copying installation files from an earlier {product-title} version. -==== -.. At the prompts, provide the configuration details for your cloud: -... Optional: Select an SSH key to use to access your cluster machines. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -... Select *aws* as the platform to target. -... If you do not have an AWS profile stored on your computer, enter the AWS -access key ID and secret access key for the user that you configured to run the -installation program. -+ -[NOTE] -==== -The AWS access key ID and secret access key are stored in `~/.aws/credentials` in the home directory of the current user on the installation host. You are prompted for the credentials by the installation program if the credentials for the exported profile are not present in the file. Any credentials that you provide to the installation program are stored in the file. -==== -... Select the AWS region to deploy the cluster to. -... Select the base domain for the Route 53 service that you configured for your cluster. -... Enter a descriptive name for your cluster. -... Paste the pull secret that you obtained from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. -ifdef::openshift-origin[] -This field is optional. -endif::[] - -ifdef::restricted[] -. Edit the `install-config.yaml` file to provide the additional information that -is required for an installation in a restricted network. -.. Update the `pullSecret` value to contain the authentication information for -your registry: -+ -[source,yaml] ----- -pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "you@example.com"}}}' ----- -+ -For `<local_registry>`, specify the registry domain name, and optionally the -port, that your mirror registry uses to serve content. For example -`registry.example.com` or `registry.example.com:5000`. For `<credentials>`, -specify the base64-encoded user name and password for your mirror registry. -.. Add the `additionalTrustBundle` parameter and value. The value must be the contents of the certificate file that you used for your mirror registry, which can be an exiting, trusted certificate authority or the self-signed certificate that you generated for the mirror registry. -+ -[source,yaml] ----- -additionalTrustBundle: | - -----BEGIN CERTIFICATE----- - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - -----END CERTIFICATE----- ----- -.. Add the image content resources: -+ -[source,yaml] ----- -imageContentSources: -- mirrors: - - <local_registry>/<local_repository_name>/release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <local_registry>/<local_repository_name>/release - source: registry.svc.ci.openshift.org/ocp/release ----- -+ -Use the `imageContentSources` section from the output of the command to mirror the repository or the values that you used when you mirrored the content from the media that you brought into your restricted network. - -.. Optional: Set the publishing strategy to `Internal`: -+ -[source,yaml] ----- -publish: Internal ----- -+ -By setting this option, you create an internal Ingress Controller and a private load balancer. -endif::restricted[] - -. Optional: Back up the `install-config.yaml` file. -+ -[IMPORTANT] -==== -The `install-config.yaml` file is consumed during the installation process. If -you want to reuse the file, you must back it up now. -==== - -ifeval::["{context}" == "installing-restricted-networks-aws"] -:!restricted: -endif::[] diff --git a/modules/installation-generate-ignition-configs.adoc b/modules/installation-generate-ignition-configs.adoc deleted file mode 100644 index 4496f3c49a2a..000000000000 --- a/modules/installation-generate-ignition-configs.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations-user-infra"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:restricted: -endif::[] - -[id="installation-generate-ignition-configs_{context}"] -= Creating the Ignition config files - -Because you must manually start the cluster machines, you must generate the -Ignition config files that the cluster needs to make its machines. - -[IMPORTANT] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== - -.Prerequisites - -* Obtain the {product-title} installation program and the pull secret for your cluster. -ifdef::restricted[] -For a restricted network installation, these files are on your mirror host. -endif::restricted[] - -.Procedure - -* Obtain the Ignition config files: -+ -[source,terminal] ----- -$ ./openshift-install create ignition-configs --dir=<installation_directory> <1> ----- -<1> For `<installation_directory>`, specify the directory name to store the -files that the installation program creates. -+ -[IMPORTANT] -==== -If you created an `install-config.yaml` file, specify the directory that contains -it. Otherwise, specify an empty directory. Some installation assets, like -bootstrap X.509 certificates have short expiration intervals, so you must not -reuse an installation directory. If you want to reuse individual files from another -cluster installation, you can copy them into your directory. However, the file -names for the installation assets might change between releases. Use caution -when copying installation files from an earlier {product-title} version. -==== -+ -The following files are generated -in the directory: -+ ----- -. -├── auth -│ ├── kubeadmin-password -│ └── kubeconfig -├── bootstrap.ign -├── master.ign -├── metadata.json -└── worker.ign ----- - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations-user-infra"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!restricted: -endif::[] diff --git a/modules/installation-getting-debug-information.adoc b/modules/installation-getting-debug-information.adoc deleted file mode 100644 index 4b8db190f640..000000000000 --- a/modules/installation-getting-debug-information.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-troubleshooting.adoc - -[id="installing-getting-debug-information_{context}"] -= Getting debug information from the installation program - -You can use any of the following actions to get debug information from the installation program. - -* Look at debug messages from a past installation in the hidden `.openshift_install.log` file. For example, enter: -+ -[source,terminal] ----- -$ cat ~/<installation_directory>/.openshift_install.log <1> ----- -<1> For `installation_directory`, specify the same directory you specified when you ran `./openshift-install create cluster`. - -* Change to the directory that contains the installation program and re-run it with `--log-level=debug`: -+ -[source,terminal] ----- -$ ./openshift-install create cluster --dir=<installation_directory> --log-level=debug <1> ----- -<1> For `installation_directory`, specify the same directory you specified when you ran `./openshift-install create cluster`. diff --git a/modules/installation-ibm-z-kvm-user-infra-machines-iso.adoc b/modules/installation-ibm-z-kvm-user-infra-machines-iso.adoc deleted file mode 100644 index 8b78b3d5e25c..000000000000 --- a/modules/installation-ibm-z-kvm-user-infra-machines-iso.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc - -[id="installation-user-infra-machines-iso-ibm-z_kvm_{context}"] -= Creating {op-system-first} machines - -Before you install a cluster on IBM Z infrastructure that you provision, you must install {op-system} as {op-system-base-full} guest virtual machines for the cluster to use. Complete the following steps to create the machines. - -.Prerequisites - -* At least 1 LPAR running {op-system-base} 8.3 with KVM, referred to as {op-system-base} KVM host in this procedure. -* A domain name server (DNS) that can perform hostname and reverse lookup for the nodes. - -.Procedure - -. Install the KVM/QEMU hypervisor on the {op-system-base} KVM host. - -. Obtain the {op-system-base} QEMU copy-on-write (QCOW2) disk image file from the link:https://access.redhat.com/downloads/content/290[Product Downloads] page on the Red Hat Customer Portal or from the link:https://mirror.openshift.com/pub/openshift-v4/s390x/dependencies/rhcos/latest/[{op-system} image mirror] page. -+ -[IMPORTANT] -==== -The {op-system} images might not change with every release of {product-title}. -You must download images with the highest version that is less than or equal -to the {product-title} version that you install. Only use the appropriate {op-system} QCOW2 image described in the following procedure. -==== -+ -. Download the QCOW2 disk image and Ignition files to a common directory on the {op-system-base} KVM host. -+ -For example: `/var/lib/libvirt/images` -+ -[NOTE] -==== -The Ignition files are generated by the {product-title} installer. -==== -. Create a new disk image with the QCOW2 disk image backing file for each KVM guest node. -+ -[source,terminal] ----- -qemu-img create -f qcow2 -F qcow2 -b /var/lib/libvirt/images/{source_rhcos_qemu} /var/lib/libvirt/images/{vmname}.qcow2 {size} ----- -+ -. Create the new KVM guest nodes using the Ignition file and the new disk image. -+ -[source,terminal] ----- -virt-install --noautoconsole - --connect qemu:///system - --name {vn_name} - --ram {memory} - --vcpus {vcpus} - --disk {disk} - --accelerate - --import - --network network={network},mac={mac} - --qemu-commandline="-drive -if=none,id=ignition,format=raw,file={ign_file},readonly=on -device virtio-blk,serial=ignition,drive=ignition" ----- \ No newline at end of file diff --git a/modules/installation-ibm-z-troubleshooting-and-debugging.adoc b/modules/installation-ibm-z-troubleshooting-and-debugging.adoc deleted file mode 100644 index 326bd33c6621..000000000000 --- a/modules/installation-ibm-z-troubleshooting-and-debugging.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_ibm_z/installing-ibm-z.adoc - -[id="installation-ibm-z-troubleshooting-and-debugging_{context}"] -= Collecting debugging information - -You can gather debugging information that might help you to troubleshoot and -debug certain issues with an {product-title} installation on IBM Z. - -.Prerequisites - -* The `oc` CLI tool installed. - -.Procedure - -. Log in to the cluster: -+ ----- -$ oc login ----- - -. On the node you want to gather hardware information about, start a debugging -container: -+ ----- -$ oc debug node/<nodename> ----- - -. Change to the */host* file system and start `toolbox`: -+ ----- -$ chroot /host -$ toolbox ----- - -. Collect the `dbginfo` data: -+ ----- -$ dbginfo.sh ----- - -. You can then retrieve the data, for example, using `scp`. diff --git a/modules/installation-ibm-z-user-infra-machines-iso.adoc b/modules/installation-ibm-z-user-infra-machines-iso.adoc deleted file mode 100644 index 0ed14a7e988d..000000000000 --- a/modules/installation-ibm-z-user-infra-machines-iso.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_ibm_z/installing-ibm-z.adoc - -[id="installation-user-infra-machines-iso-ibm-z_{context}"] -= Creating {op-system-first} machines - -Before you install a cluster on IBM Z infrastructure that you provision, you must install {op-system} on z/VM guest virtual machines for the cluster to use. Complete the following steps to create the machines. - -.Prerequisites - -* An HTTP or HTTPS server running on your provisioning machine that is accessible to the machines you create. - -.Procedure - -. Log in to Linux on your provisioning machine. - -. Obtain the {op-system-first} kernel, initramfs, and rootfs files from the link:https://mirror.openshift.com/pub/openshift-v4/s390x/dependencies/rhcos/latest/[{op-system} image mirror]. -+ -[IMPORTANT] -==== -The {op-system} images might not change with every release of {product-title}. -You must download images with the highest version that is less than or equal -to the {product-title} version that you install. Only use the appropriate kernel, initramfs, and rootfs artifacts described in the following procedure. -==== -+ -The file names contain the {product-title} version number. They resemble the following examples: - -* kernel: `rhcos-<version>-live-kernel-<architecture>` -* initramfs: `rhcos-<version>-live-initramfs.<architecture>.img` -* rootfs: `rhcos-<version>-live-rootfs.<architecture>.img` -+ -[NOTE] -==== -The rootfs image is the same for FCP and DASD. -==== -+ -. Create parameter files. The following parameters are specific for a particular virtual machine: -** For `ip=`, specify the following seven entries: -... The IP address for the machine. -... An empty string. -... The gateway. -... The netmask. -... The machine host and domain name in the form `hostname.domainname`. Omit this value to let {op-system} decide. -... The network interface name. Omit this value to let {op-system} decide. -... If you use static IP addresses, specify `none`. -** For `coreos.inst.ignition_url=`, specify the Ignition file for the machine role. Use `bootstrap.ign`, `master.ign`, or `worker.ign`. Only HTTP and HTTPS protocols are supported. -** For `coreos.live.rootfs_url=`, specify the matching rootfs artifact for the kernel and initramfs you are booting. Only HTTP and HTTPS protocols are supported. - -** For installations on DASD-type disks, complete the following tasks: -... For `coreos.inst.install_dev=`, specify `dasda`. -... Use `rd.dasd=` to specify the DASD where {op-system} is to be installed. -... Leave all other parameters unchanged. -+ -Example parameter file, `bootstrap-0.parm`, for the bootstrap machine: -+ -[source,terminal] ----- -rd.neednet=1 console=ttysclp0 coreos.inst.install_dev=dasda coreos.live.rootfs_url=http:// -cl1.provide.example.com:8080/assets/rhcos-live-rootfs.s390x.img -coreos.inst.ignition_url=http://cl1.provide.example.com:8080/ignition/bootstrap.ign -ip=172.18.78.2::172.18.78.1:255.255.255.0:::none nameserver=172.18.78.1 -rd.znet=qeth,0.0.bdf0,0.0.bdf1,0.0.bdf2,layer2=1,portno=0 zfcp.allow_lun_scan=0 cio_ignore=all, -!condev rd.dasd=0.0.3490 ----- - - -** For installations on FCP-type disks, complete the following tasks: -... Use `rd.zfcp=<adapter>,<wwpn>,<lun>` to specify the FCP disk where {op-system} is to be installed. For multipathing repeat this step for each additional path. -... For multipathing, set the following parameter: `rd.multipath=default`. -... For multipathing, set the install device as: `coreos.inst.install_dev=/dev/mapper/mpatha`. -... For single-path installation, set the install device as: `coreos.inst.install_dev=sda`. -+ -[NOTE] -==== -If additional LUNs are configured with NPIV, FCP requires `zfcp.allow_lun_scan=0`. -==== -... Leave all other parameters unchanged. -+ -[NOTE] -==== -Additional post-installation steps are required to fully enable multipathing. See “Completing installation on user-provisioned infrastructure” for more information. -==== -+ -The following is an example parameter file `bootstrap-0.parm` for the bootstrap machine with multipathing: -+ -[source,terminal] ----- -rd.neednet=1 rd.multipath=default console=ttysclp0 coreos.inst.install_dev=/dev/mapper/mpatha -coreos.live.rootfs_url=http://cl1.provide.example.com:8080/assets/rhcos-live-rootfs.s390x.img -coreos.inst.ignition_url=http://cl1.provide.example.com:8080/ignition/bootstrap.ign -ip=172.18.78.2::172.18.78.1:255.255.255.0:::none nameserver=172.18.78.1 -rd.znet=qeth,0.0.bdf0,0.0.bdf1,0.0.bdf2,layer2=1,portno=0 zfcp.allow_lun_scan=0 cio_ignore=all, -!condev -rd.zfcp=0.0.1987,0x50050763070bc5e3,0x4008400B00000000 -rd.zfcp=0.0.19C7,0x50050763070bc5e3,0x4008400B00000000 -rd.zfcp=0.0.1987,0x50050763071bc5e3,0x4008400B00000000 -rd.zfcp=0.0.19C7,0x50050763071bc5e3,0x4008400B00000000 ----- - -. Transfer the initramfs, kernel, parameter files, and {op-system} images to z/VM, for example with FTP. For details about how to transfer the files with FTP and boot from the virtual reader, see link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/installation_guide/sect-installing-zvm-s390[Installing under Z/VM]. -. Punch the files to the virtual reader of the z/VM guest virtual machine that is to become your bootstrap node. -+ -See link:https://www.ibm.com/support/knowledgecenter/en/SSB27U_7.1.0/com.ibm.zvm.v710.dmsb4/pun.htm[PUNCH] in the IBM Knowledge Center. -+ -[TIP] -==== -You can use the CP PUNCH command or, if you use Linux, the **vmur** command to transfer files between two z/VM guest virtual machines. -==== -+ -. Log in to CMS on the bootstrap machine. -. IPL the bootstrap machine from the reader: -+ ----- -$ ipl c ----- -+ -See link:https://www.ibm.com/support/knowledgecenter/en/SSB27U_7.1.0/com.ibm.zvm.v710.hcpb7/iplcommd.htm[IPL] in the IBM Knowledge Center. -+ -. Repeat this procedure for the other machines in the cluster. diff --git a/modules/installation-images-samples-disconnected-mirroring-assist.adoc b/modules/installation-images-samples-disconnected-mirroring-assist.adoc deleted file mode 100644 index 9a1c93f06248..000000000000 --- a/modules/installation-images-samples-disconnected-mirroring-assist.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-restricted-networks-preparations.adoc -// * openshift_images/samples-operator-alt-registry.adoc -// * openshift_images/configuring-samples-operator.adoc - -[id="installation-images-samples-disconnected-mirroring-assist_{context}"] -= Cluster Samples Operator assistance for mirroring - -During installation, {product-title} creates a config map named `imagestreamtag-to-image` in the `openshift-cluster-samples-operator` namespace. The `imagestreamtag-to-image` config map contains an entry, the populating image, for each image stream tag. - -The format of the key for each entry in the data field in the config map is `<image_stream_name>_<image_stream_tag_name>`. - -During a disconnected installation of {product-title}, the status of the Cluster Samples Operator is set to `Removed`. If you choose to change it to `Managed`, it installs samples. - -You can use this config map as a reference for which images need to be mirrored for your image streams to import. - -* While the Cluster Samples Operator is set to `Removed`, you can create your mirrored registry, or determine which existing mirrored registry you want to use. -* Mirror the samples you want to the mirrored registry using the new config map as your guide. -* Add any of the image streams you did not mirror to the `skippedImagestreams` list of the Cluster Samples Operator configuration object. -* Set `samplesRegistry` of the Cluster Samples Operator configuration object to the mirrored registry. -* Then set the Cluster Samples Operator to `Managed` to install the image streams you have mirrored. diff --git a/modules/installation-infrastructure-user-infra.adoc b/modules/installation-infrastructure-user-infra.adoc deleted file mode 100644 index 00daa7c8a4e8..000000000000 --- a/modules/installation-infrastructure-user-infra.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc - -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] - -[id="installation-infrastructure-user-infra_{context}"] -= Creating the user-provisioned infrastructure - -Before you deploy an {product-title} cluster that uses user-provisioned -infrastructure, you must create the underlying infrastructure. - -.Prerequisites - -* Review the link:https://access.redhat.com/articles/4128421[{product-title} 4.x Tested Integrations] -page before you create the supporting infrastructure for your cluster. - -.Procedure - -ifdef::ibm-z[] -. Set up static IP addresses. -. Set up an HTTP or HTTPS server to provide Ignition files to the cluster nodes. -endif::ibm-z[] -ifndef::ibm-z[] -. Configure DHCP or set static IP addresses on each node. -endif::ibm-z[] - -. Provision the required load balancers. - -. Configure the ports for your machines. - -. Configure DNS. - -. Ensure network connectivity. - -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] diff --git a/modules/installation-initializing-manual.adoc b/modules/installation-initializing-manual.adoc deleted file mode 100644 index 2e819ee26026..000000000000 --- a/modules/installation-initializing-manual.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc - -ifeval::["{context}" == "installing-azure-government-region"] -:azure-gov: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-aws-government-region"] -:aws-gov: -endif::[] -ifeval::["{context}" == "installing-aws-private"] -:aws-private: -endif::[] -ifeval::["{context}" == "installing-azure-private"] -:azure-private: -endif::[] -ifeval::["{context}" == "installing-gcp-private"] -:gcp-private: -endif::[] - -[id="installation-initializing-manual_{context}"] -= Manually creating the installation configuration file - -ifndef::aws-gov,azure-gov,aws-private,azure-private,gcp-private[] -For installations of {product-title} that use user-provisioned -infrastructure, you manually generate your installation configuration file. -endif::aws-gov,azure-gov,aws-private,azure-private,gcp-private[] -ifdef::aws-gov[] -When installing {product-title} on Amazon Web Services (AWS) into a region -requiring a custom {op-system-first} AMI, you must manually generate your -installation configuration file. -endif::aws-gov[] -ifdef::azure-gov[] -When installing {product-title} on Microsoft Azure into a government region, you -must manually generate your installation configuration file. -endif::azure-gov[] -ifdef::aws-private,azure-private,gcp-private[] -For installations of a private {product-title} cluster that are only accessible from an internal network and are not visible to the Internet, you must manually generate your installation configuration file. -endif::aws-private,azure-private,gcp-private[] - -.Prerequisites - -* Obtain the {product-title} installation program and the access token for your -cluster. -ifdef::restricted[] -* Obtain the `imageContentSources` section from the output of the command to -mirror the repository. -* Obtain the contents of the certificate for your mirror registry. -endif::restricted[] - -.Procedure - -. Create an installation directory to store your required installation assets -in: -+ -[source,terminal] ----- -$ mkdir <installation_directory> ----- -+ -[IMPORTANT] -==== -You must create a directory. Some installation assets, like bootstrap X.509 -certificates have short expiration intervals, so you must not reuse an -installation directory. If you want to reuse individual files from another -cluster installation, you can copy them into your directory. However, the file -names for the installation assets might change between releases. Use caution -when copying installation files from an earlier {product-title} version. -==== - -. Customize the following `install-config.yaml` file template and save -it in the `<installation_directory>`. -+ -[NOTE] -==== -You must name this configuration file `install-config.yaml`. -==== -ifdef::restricted[] -** Unless you use a registry that {op-system} trusts by default, such as -`docker.io`, you must provide the contents of the certificate for your mirror -repository in the `additionalTrustBundle` section. In most cases, you must -provide the certificate for your mirror. -** You must include the `imageContentSources` section from the output of the command to -mirror the repository. -endif::restricted[] - -. Back up the `install-config.yaml` file so that you can use it to install -multiple clusters. -+ -[IMPORTANT] -==== -The `install-config.yaml` file is consumed during the next step of the -installation process. You must back it up now. -==== - -ifeval::["{context}" == "installing-azure-government-region"] -:!azure-gov: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-aws-government-region"] -:!aws-gov: -endif::[] -ifeval::["{context}" == "installing-aws-private"] -:!aws-private: -endif::[] -ifeval::["{context}" == "installing-azure-private"] -:!azure-private: -endif::[] -ifeval::["{context}" == "installing-gcp-private"] -:!gcp-private: -endif::[] diff --git a/modules/installation-initializing.adoc b/modules/installation-initializing.adoc deleted file mode 100644 index 58550cf552e1..000000000000 --- a/modules/installation-initializing.adoc +++ /dev/null @@ -1,506 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-vpc.adoc -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-network-customizations -// * installing/installing_azure/installing-azure-vnet.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-network-customizations.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-installer-restricted.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_rhv/installing-rhv-customizations.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc - -// * installing/installing_gcp/installing-openstack-installer-restricted.adoc -// Consider also adding the installation-configuration-parameters.adoc module. -//YOU MUST SET AN IFEVAL FOR EACH NEW MODULE - -ifeval::["{context}" == "installing-aws-customizations"] -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-network-customizations"] -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-vpc"] -:aws: -endif::[] -ifeval::["{context}" == "installing-azure-customizations"] -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-network-customizations"] -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-vnet"] -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:azure: -endif::[] -ifeval::["{context}" == "installing-gcp-customizations"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-vpc"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-network-customizations"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-custom"] -:osp: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:osp: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:osp: -:osp-user: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:osp: -:osp-user: -endif::[] -ifeval::["{context}" == "installing-rhv-customizations"] -:rhv: -endif::[] -ifeval::["{context}" == "installing-rhv-default"] -:rhv: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-customizations"] -:vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:vmc: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:osp: -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:vsphere: -:restricted: -endif::[] - -[id="installation-initializing_{context}"] -= Creating the installation configuration file - -You can customize the {product-title} cluster you install on -ifdef::aws[] -Amazon Web Services (AWS). -endif::aws[] -ifdef::azure[] -Microsoft Azure. -endif::azure[] -ifdef::gcp[] -Google Cloud Platform (GCP). -endif::gcp[] -ifdef::osp[] -{rh-openstack-first}. -endif::osp[] -ifdef::vsphere,vmc[] -VMware vSphere. -endif::vsphere,vmc[] -ifdef::rhv[] -{rh-virtualization-first}. - -[WARNING] -==== -Due to a known issue with installing {product-title} versions 4.4 and 4.5 on {rh-virtualization-first} 4.4.1, you must customize `install-config.yaml` as described in link:https://access.redhat.com/solutions/5374251[Openshift IPI installation on {rh-virtualization}-4.x failed with "Error: timeout while waiting for state to become 'up' (last state: 'down', timeout: 10m0s)"]. This defect is fixed in {rh-virtualization} 4.4.2. -==== -ifndef::openshift-origin[] -[WARNING] -==== -Installing OpenShift Container Platform (OCP) version 4.6 on Red Hat Virtualization (RHV) requires RHV version 4.4. If you are running an earlier version of OCP on RHV 4.3, do not update it to OCP version 4.6. Red Hat has not tested running OCP version 4.6 on RHV version 4.3 and does not support this combination. Also see link:https://access.redhat.com/articles/4763741[{product-title} 4.x Tested Integrations (for x86_x64)]. -==== -endif::openshift-origin[] -endif::rhv[] - -.Prerequisites - -* Obtain the {product-title} installation program and the pull secret for your cluster. -ifdef::restricted[] -For a restricted network installation, these files are on your bastion host. -* Have the `imageContentSources` values that were generated during mirror registry creation. -* Obtain the contents of the certificate for your mirror registry. -* Retrieve a {op-system-first} image and upload it to an accessible location. -endif::restricted[] - -.Procedure - -. Create the `install-config.yaml` file. -+ -.. Change to the directory that contains the installation program and run the following command: -+ -[source,terminal] ----- -$ ./openshift-install create install-config --dir=<installation_directory> <1> ----- -<1> For `<installation_directory>`, specify the directory name to store the -files that the installation program creates. -+ -[IMPORTANT] -==== -Specify an empty directory. Some installation assets, like bootstrap X.509 -certificates have short expiration intervals, so you must not reuse an -installation directory. If you want to reuse individual files from another -cluster installation, you can copy them into your directory. However, the file -names for the installation assets might change between releases. Use caution -when copying installation files from an earlier {product-title} version. -==== -ifndef::rhv[] -.. At the prompts, provide the configuration details for your cloud: -... Optional: Select an SSH key to use to access your cluster machines. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -endif::rhv[] -ifdef::aws[] -... Select *AWS* as the platform to target. -... If you do not have an Amazon Web Services (AWS) profile stored on your computer, enter the AWS -access key ID and secret access key for the user that you configured to run the -installation program. -... Select the AWS region to deploy the cluster to. -... Select the base domain for the Route 53 service that you configured for your cluster. -endif::aws[] -ifdef::azure[] -... Select *azure* as the platform to target. -... If you do not have a Microsoft Azure profile stored on your computer, specify the -following Azure parameter values for your subscription and service principal: -**** *azure subscription id*: The subscription ID to use for the cluster. -Specify the `id` value in your account output. -**** *azure tenant id*: The tenant ID. Specify the `tenantId` value in your -account output. -**** *azure service principal client id*: The value of the `appId` parameter -for the service principal. -**** *azure service principal client secret*: The value of the `password` -parameter for the service principal. -... Select the region to deploy the cluster to. -... Select the base domain to deploy the cluster to. The base domain corresponds -to the Azure DNS Zone that you created for your cluster. -endif::azure[] -ifdef::gcp[] -... Select *gcp* as the platform to target. -... If you have not configured the service account key for your GCP account on -your computer, you must obtain it from GCP and paste the contents of the file -or enter the absolute path to the file. -... Select the project ID to provision the cluster in. The default value is -specified by the service account that you configured. -... Select the region to deploy the cluster to. -... Select the base domain to deploy the cluster to. The base domain corresponds -to the public DNS zone that you created for your cluster. -endif::gcp[] -ifdef::osp[] -... Select *openstack* as the platform to target. -... Specify the {rh-openstack-first} external network name to use for installing the cluster. -... Specify the floating IP address to use for external access to the OpenShift API. -... Specify a {rh-openstack} flavor with at least 16 GB RAM to use for control plane -and compute nodes. -... Select the base domain to deploy the cluster to. All DNS records will be -sub-domains of this base and will also include the cluster name. -endif::osp[] -ifdef::vsphere,vmc[] -... Select *vsphere* as the platform to target. -... Specify the name of your vCenter instance. -... Specify the user name and password for the vCenter account that has the required permissions to create the cluster. -+ -The installation program connects to your vCenter instance. -... Select the datacenter in your vCenter instance to connect to. -... Select the default vCenter datastore to use. -... Select the vCenter cluster to install the {product-title} cluster in. -... Select the network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured. -... Enter the virtual IP address that you configured for control plane API access. -... Enter the virtual IP address that you configured for cluster ingress. -... Enter the base domain. This base domain must be the same one that you used in the DNS records that you configured. -endif::vsphere,vmc[] -ifndef::osp[] -ifndef::rhv[] -... Enter a descriptive name for your cluster. -ifdef::vsphere,vmc[] -The cluster name must be the same one that you used in the DNS records that you configured. -endif::vsphere,vmc[] -endif::rhv[] -endif::osp[] -ifdef::osp[] -... Enter a name for your cluster. The name must be 14 or fewer characters long. -endif::osp[] -ifdef::azure[] -+ -[IMPORTANT] -==== -All Azure resources that are available through public endpoints are subject to -resource name restrictions, and you cannot create resources that use certain -terms. For a list of terms that Azure restricts, see -link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-reserved-resource-name[Resolve reserved resource name errors] -in the Azure documentation. -==== -endif::azure[] -ifdef::rhv[] -.. Respond to the installation program prompts. -... For `SSH Public Key`, select a password-less public key, such as `~/.ssh/id_rsa.pub`. This key authenticates connections with the new {product-title} cluster. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, select an SSH key that your `ssh-agent` process uses. -==== -... For `Platform`, select `ovirt`. -... For `Enter oVirt's API endpoint URL`, enter the URL of the {rh-virtualization} API using this format: -+ -[source,terminal] ----- -https://<engine-fqdn>/ovirt-engine/api <1> ----- -<1> For `<engine-fqdn>`, specify the fully qualified domain name of the {rh-virtualization} environment. -+ -For example: -+ -ifndef::openshift-origin[] -[source,terminal] ----- -$ curl -k -u ovirtadmin@internal:pw123 \ -https://rhv-env.virtlab.example.com/ovirt-engine/api ----- -endif::openshift-origin[] -ifdef::openshift-origin[] -[source,terminal] ----- -$ curl -k -u ovirtadmin@internal:pw123 \ -https://ovirtlab.example.com/ovirt-engine/api ----- -endif::openshift-origin[] -+ -... For `Is the oVirt CA trusted locally?`, enter `Yes` since you have already set up a CA certificate. Otherwise, enter `No`. -... For `oVirt's CA bundle`, if you entered `Yes` for the preceding question, copy the certificate content from `/etc/pki/ca-trust/source/anchors/ca.pem` and paste it here. Then, press `Enter` twice. Otherwise, if you entered `No` for the preceding question, this question does not appear. -... For `oVirt engine username`, enter the user name and profile of the {rh-virtualization} administrator using this format: -+ -[source,terminal] ----- -<username>@<profile> <1> ----- -<1> For `<username>`, specify the user name of an {rh-virtualization} administrator. For `<profile>`, specify the login profile, which you can get by going to the {rh-virtualization} Administration Portal login page and reviewing the *Profile* dropdown list. Together, the user name and profile should look similar to this example: -+ -[source,terminal] ----- -admin@internal ----- -+ -... For `oVirt engine password`, enter the {rh-virtualization} admin password. -... For `oVirt cluster`, select the cluster for installing {product-title}. -... For `oVirt storage domain`, select the storage domain for installing {product-title}. -... For `oVirt network`, select a virtual network that has access to the {rh-virtualization} Manager REST API. -... For `Internal API Virtual IP`, enter the static IP address you set aside for the cluster’s REST API. -... For `Internal DNS Virtual IP`, enter the static IP address you set aside for the cluster’s internal DNS service. -... For `Ingress virtual IP`, enter the static IP address you reserved for the wildcard apps domain. -... For `Base Domain`, enter the base domain of the {product-title} cluster. If this cluster is exposed to the outside world, this must be a valid domain recognized by DNS infrastructure. For example, enter: `virtlab.example.com` -... For `Cluster Name`, enter the name of the cluster. For example, `my-cluster`. Use cluster name from the externally registered/resolvable DNS entries you created for the {product-title} REST API and apps domain names. The installation program also gives this name to the cluster in the {rh-virtualization} environment. -... For `Pull Secret`, copy the pull secret from the `pull-secret.txt` file you downloaded earlier and paste it here. You can also get a copy of the same pull secret from the link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. -endif::rhv[] -ifndef::rhv[] -... Paste the pull secret that you obtained from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. -ifdef::openshift-origin[] -This field is optional. -endif::[] -endif::rhv[] -ifeval::["{context}" == "installing-gcp-user-infra"] -.. Optional: If you do not want the cluster to provision compute machines, empty -the compute pool by editing the resulting `install-config.yaml` file to set -`replicas` to `0` for the `compute` pool: -+ -[source,yaml] ----- -compute: -- hyperthreading: Enabled - name: worker - platform: {} - replicas: 0 <1> ----- -<1> Set to `0`. -endif::[] - -ifndef::restricted[] -. Modify the `install-config.yaml` file. You can find more information about -the available parameters in the *Installation configuration parameters* section. -endif::restricted[] - -ifdef::osp+restricted[] -. In the `install-config.yaml` file, set the value of `platform.openstack.clusterOSImage` to the image location or name. For example: -+ -[source,yaml] ----- -platform: - openstack: - clusterOSImage: http://mirror.example.com/images/rhcos-43.81.201912131630.0-openstack.x86_64.qcow2.gz?sha256=ffebbd68e8a1f2a245ca19522c16c86f67f9ac8e4e0c1f0a812b068b16f7265d ----- -endif::osp+restricted[] -ifdef::vsphere+restricted[] -. In the `install-config.yaml` file, set the value of `platform.vsphere.clusterOSImage` to the image location or name. For example: -+ -[source,yaml] ----- -platform: - vsphere: - clusterOSImage: http://mirror.example.com/images/rhcos-43.81.201912131630.0-vmware.x86_64.ova?sha256=ffebbd68e8a1f2a245ca19522c16c86f67f9ac8e4e0c1f0a812b068b16f7265d ----- -endif::vsphere+restricted[] -ifdef::restricted[] -. Edit the `install-config.yaml` file to provide the additional information that -is required for an installation in a restricted network. -.. Update the `pullSecret` value to contain the authentication information for -your registry: -+ -[source,yaml] ----- -pullSecret: '{"auths":{"<bastion_host_name>:5000": {"auth": "<credentials>","email": "you@example.com"}}}' ----- -+ -For `<bastion_host_name>`, specify the registry domain name -that you specified in the certificate for your mirror registry, and for -`<credentials>`, specify the base64-encoded user name and password for -your mirror registry. -.. Add the `additionalTrustBundle` parameter and value. -+ -[source,yaml] ----- -additionalTrustBundle: | - -----BEGIN CERTIFICATE----- - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - -----END CERTIFICATE----- ----- -+ -The value must be the contents of the certificate file that you used for your mirror registry, which can be an existing, trusted certificate authority or the self-signed certificate that you generated for the mirror registry. - -.. Add the image content resources, which look like this excerpt: -+ -[source,yaml] ----- -imageContentSources: -- mirrors: - - <bastion_host_name>:5000/<repo_name>/release - source: quay.example.com/openshift-release-dev/ocp-release -- mirrors: - - <bastion_host_name>:5000/<repo_name>/release - source: registry.example.com/ocp/release ----- -+ -To complete these values, use the `imageContentSources` that you recorded during mirror registry creation. - -. Make any other modifications to the `install-config.yaml` file that you require. You can find more information about -the available parameters in the *Installation configuration parameters* section. -endif::restricted[] - -. Back up the `install-config.yaml` file so that you can use -it to install multiple clusters. -+ -[IMPORTANT] -==== -The `install-config.yaml` file is consumed during the installation process. If -you want to reuse the file, you must back it up now. -==== - -ifdef::osp-user[You now have the file `install-config.yaml` in the directory that you specified.] - -ifeval::["{context}" == "installing-aws-customizations"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-network-customizations"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-vpc"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-azure-customizations"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-network-customizations"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-vnet"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:!azure: -endif::[] -ifeval::["{context}" == "installing-gcp-customizations"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-network-customizations"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-vpc"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-custom"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:!osp: -:!osp-user: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:!osp: -:!osp-user: -endif::[] -ifeval::["{context}" == "installing-rhv-customizations"] -:!rhv: -endif::[] -ifeval::["{context}" == "installing-rhv-default"] -:!rhv: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"] -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-customizations"] -:vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:vmc: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:!osp: -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:!vsphere: -:!restricted: -endif::[] diff --git a/modules/installation-installer-provisioned-vsphere-config-yaml.adoc b/modules/installation-installer-provisioned-vsphere-config-yaml.adoc deleted file mode 100644 index 0f536b3f7ec9..000000000000 --- a/modules/installation-installer-provisioned-vsphere-config-yaml.adoc +++ /dev/null @@ -1,152 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc - -ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"] -:network: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:network: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:restricted: -endif::[] - -[id="installation-installer-provisioned-vsphere-config-yaml_{context}"] -= Sample install-config.yaml file for an installer-provisioned VMware vSphere cluster - -You can customize the `install-config.yaml` file to specify more details about -your {product-title} cluster's platform or modify the values of the required -parameters. - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com <1> -compute: <2> -- hyperthreading: Enabled <3> - name: worker - replicas: 3 - platform: - vsphere: <4> - cpus: 2 - coresPerSocket: 2 - memoryMB: 8196 - osDisk: - diskSizeGB: 120 -controlPlane: <2> - hyperthreading: Enabled <3> - name: master - replicas: 3 - platform: - vsphere: <4> - cpus: 4 - coresPerSocket: 2 - memoryMB: 16384 - osDisk: - diskSizeGB: 120 -metadata: - name: cluster <5> -ifdef::network[] -networking: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineNetwork: - - cidr: 10.0.0.0/16 -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] - serviceNetwork: - - 172.30.0.0/16 -endif::network[] -platform: - vsphere: - vcenter: your.vcenter.server - username: username - password: password - datacenter: datacenter - defaultDatastore: datastore - folder: folder - network: VM_Network - cluster: vsphere_cluster_name - apiVIP: api_vip - ingressVIP: ingress_vip -ifdef::restricted[] - clusterOSImage: http://mirror.example.com/images/rhcos-48.83.202103221318-0-vmware.x86_64.ova <6> -endif::restricted[] -ifndef::openshift-origin[] -fips: false -endif::openshift-origin[] -ifndef::restricted[] -pullSecret: '{"auths": ...}' -endif::restricted[] -ifdef::restricted[] -pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "you@example.com"}}}' <7> -endif::restricted[] -sshKey: 'ssh-ed25519 AAAA...' -ifdef::restricted[] -additionalTrustBundle: | <8> - -----BEGIN CERTIFICATE----- - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - -----END CERTIFICATE----- -imageContentSources: <9> -- mirrors: - - <local_registry>/<local_repository_name>/release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <local_registry>/<local_repository_name>/release - source: registry.svc.ci.openshift.org/ocp/release -endif::restricted[] ----- -<1> The base domain of the cluster. All DNS records must be sub-domains of this -base and include the cluster name. -<2> The `controlPlane` section is a single mapping, but the compute section is a -sequence of mappings. To meet the requirements of the different data structures, -the first line of the `compute` section must begin with a hyphen, `-`, and the -first line of the `controlPlane` section must not. Although both sections -currently define a single machine pool, it is possible that future versions -of {product-title} will support defining multiple compute pools during -installation. Only one control plane pool is used. -<3> Whether to enable or disable simultaneous multithreading, or -`hyperthreading`. By default, simultaneous multithreading is enabled -to increase the performance of your machines' cores. You can disable it by -setting the parameter value to `Disabled`. If you disable simultaneous -multithreading in some cluster machines, you must disable it in all cluster -machines. -+ -[IMPORTANT] -==== -If you disable simultaneous multithreading, ensure that your capacity planning -accounts for the dramatically decreased machine performance. -Your machines must use at least 8 CPUs and 32 GB of RAM if you disable -simultaneous multithreading. -==== -<4> Optional: Provide additional configuration for the machine pool parameters for the compute and control plane machines. -<5> The cluster name that you specified in your DNS records. -ifdef::restricted[] -<6> The location of the {op-system-first} image that is accessible from the bastion server. -<7> For `<local_registry>`, specify the registry domain name, and optionally the -port, that your mirror registry uses to serve content. For example -`registry.example.com` or `registry.example.com:5000`. For `<credentials>`, -specify the base64-encoded user name and password for your mirror registry. -<8> Provide the contents of the certificate file that you used for your mirror registry. -<9> Provide the `imageContentSources` section from the output of the command to mirror the repository. -endif::restricted[] - -ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"] -:!network: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:!network: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:!restricted: -endif::[] diff --git a/modules/installation-installing-bare-metal.adoc b/modules/installation-installing-bare-metal.adoc deleted file mode 100644 index 31cd3d92604f..000000000000 --- a/modules/installation-installing-bare-metal.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc - -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:restricted: -endif::[] - -[id="installation-installing-bare-metal_{context}"] -= Creating the cluster - -To create the {product-title} cluster, you wait for the bootstrap process to -complete on the machines that you provisioned by using the -Ignition config files that you generated with the installation program. - -.Prerequisites - -* Create the required infrastructure for the cluster. -* You obtained the installation program and generated the Ignition config files -for your cluster. -* You used the Ignition config files to create {op-system} machines for your -cluster. -ifndef::restricted[] -* Your machines have direct Internet access or have an HTTP or HTTPS proxy available. -endif::restricted[] - -.Procedure - -. Monitor the bootstrap process: -+ -[source,terminal] ----- -$ ./openshift-install --dir=<installation_directory> wait-for bootstrap-complete \ <1> - --log-level=info <2> ----- -<1> For `<installation_directory>`, specify the path to the directory that you stored the installation files in. -<2> To view different installation details, specify `warn`, `debug`, or `error` instead of `info`. -+ -.Example output -[source,terminal] ----- -INFO Waiting up to 30m0s for the Kubernetes API at https://api.test.example.com:6443... -INFO API v1.20.0 up -INFO Waiting up to 30m0s for bootstrapping to complete... -INFO It is now safe to remove the bootstrap resources ----- -+ -The command succeeds when the Kubernetes API server signals that it has been -bootstrapped on the control plane machines. - -. After bootstrap process is complete, remove the bootstrap machine from the -load balancer. -+ -[IMPORTANT] -==== -You must remove the bootstrap machine from the load balancer at this point. You -can also remove or reformat the machine itself. -==== - -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!restricted: -endif::[] diff --git a/modules/installation-launching-installer.adoc b/modules/installation-launching-installer.adoc deleted file mode 100644 index d10b0169444c..000000000000 --- a/modules/installation-launching-installer.adoc +++ /dev/null @@ -1,516 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-default.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-default.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_gcp/installing-gcp-default.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_rhv/installing-rhv-customizations.adoc -// * installing/installing_rhv/installing-rhv-default.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// If you use this module in any other assembly, you must update the ifeval -// statements. - -ifeval::["{context}" == "installing-aws-customizations"] -:custom-config: -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-government-region"] -:custom-config: -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-network-customizations"] -:custom-config: -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-vpc"] -:custom-config: -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-default"] -:no-config: -:aws: -endif::[] -ifeval::["{context}" == "installing-azure-default"] -:no-config: -:azure: -endif::[] -ifeval::["{context}" == "installing-gcp-customizations"] -:custom-config: -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-vpc"] -:custom-config: -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-default"] -:no-config: -:gcp: -endif::[] -ifeval::["{context}" == "installing-azure-customizations"] -:custom-config: -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-government-region"] -:custom-config: -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-vnet"] -:custom-config: -:azure: -endif::[] -ifeval::["{context}" == "installing-azure-network-customizations"] -:custom-config: -:azure: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-custom"] -:osp: -:custom-config: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:osp: -:custom-config: -endif::[] -ifeval::["{context}" == "installing-openstack-installer"] -:osp: -endif::[] -ifeval::["{context}" == "installing-rhv-customizations"] -:custom-config: -:rhv: -endif::[] -ifeval::["{context}" == "installing-rhv-default"] -:no-config: -:rhv: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned"] -:no-config: -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] -:custom-config: -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"] -:custom-config: -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc"] -:no-config: -:vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-customizations"] -:custom-config: -:vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:custom-config: -:vmc: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:custom-config: -:vsphere: -endif::[] - -[id="installation-launching-installer_{context}"] -= Deploying the cluster - -You can install {product-title} on a compatible cloud platform. - -[IMPORTANT] -==== -You can run the `create cluster` command of the installation program only once, during initial installation. -==== - -.Prerequisites - -ifndef::osp,rhv,vsphere[* Configure an account with the cloud platform that hosts your cluster.] - -* Obtain the {product-title} installation program and the pull secret for your -cluster. - -.Procedure - -ifdef::gcp[] -. Remove any existing GCP credentials that do not use the service account key -for the GCP account that you configured for your cluster and that are stored in the -following locations: -** The `GOOGLE_CREDENTIALS`, `GOOGLE_CLOUD_KEYFILE_JSON`, or `GCLOUD_KEYFILE_JSON` -environment variables -** The `~/.gcp/osServiceAccount.json` file -** The `gcloud cli` default credentials -endif::gcp[] - -. Change to the directory that contains the installation program and initialize the cluster deployment: -+ -[source,terminal] ----- -$ ./openshift-install create cluster --dir=<installation_directory> \ <1> - --log-level=info <2> ----- -<1> For `<installation_directory>`, specify the -ifdef::custom-config[] -location of your customized `./install-config.yaml` file. -endif::custom-config[] -ifdef::no-config[] -directory name to store the files that the installation program creates. -endif::no-config[] -<2> To view different installation details, specify `warn`, `debug`, or -`error` instead of `info`. -ifdef::no-config[] -+ -[IMPORTANT] -==== -Specify an empty directory. Some installation assets, like bootstrap X.509 -certificates have short expiration intervals, so you must not reuse an -installation directory. If you want to reuse individual files from another -cluster installation, you can copy them into your directory. However, the file -names for the installation assets might change between releases. Use caution -when copying installation files from an earlier {product-title} version. -==== -+ --- -ifndef::rhv[] -Provide values at the prompts: - -.. Optional: Select an SSH key to use to access your cluster machines. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -ifdef::aws[] -.. Select *aws* as the platform to target. -.. If you do not have an Amazon Web Services (AWS) profile stored on your computer, enter the AWS -access key ID and secret access key for the user that you configured to run the -installation program. -+ -[NOTE] -==== -The AWS access key ID and secret access key are stored in `~/.aws/credentials` in the home directory of the current user on the installation host. You are prompted for the credentials by the installation program if the credentials for the exported profile are not present in the file. Any credentials that you provide to the installation program are stored in the file. -==== -.. Select the AWS region to deploy the cluster to. -.. Select the base domain for the Route 53 service that you configured for your cluster. -endif::aws[] -ifdef::azure[] -.. Select *azure* as the platform to target. -.. If you do not have a Microsoft Azure profile stored on your computer, specify the -following Azure parameter values for your subscription and service principal: -*** *azure subscription id*: The subscription ID to use for the cluster. -Specify the `id` value in your account output. -*** *azure tenant id*: The tenant ID. Specify the `tenantId` value in your -account output. -*** *azure service principal client id*: The value of the `appId` parameter -for the service principal. -*** *azure service principal client secret*: The value of the `password` -parameter for the service principal. -.. Select the region to deploy the cluster to. -.. Select the base domain to deploy the cluster to. The base domain corresponds -to the Azure DNS Zone that you created for your cluster. -endif::azure[] -ifdef::gcp[] -.. Select *gcp* as the platform to target. -.. If you have not configured the service account key for your GCP account on -your computer, you must obtain it from GCP and paste the contents of the file -or enter the absolute path to the file. -.. Select the project ID to provision the cluster in. The default value is -specified by the service account that you configured. -.. Select the region to deploy the cluster to. -.. Select the base domain to deploy the cluster to. The base domain corresponds -to the public DNS zone that you created for your cluster. -endif::gcp[] -ifdef::osp[] -.. Select *openstack* as the platform to target. -.. Specify the {rh-openstack-first} external network name to use for installing the cluster. -.. Specify the Floating IP address to use for external access to the OpenShift API. -.. Specify the {rh-openstack} flavor with at least 16 GB RAM to use for control plane -and compute nodes. -.. Select the base domain to deploy the cluster to. All DNS records will be -sub-domains of this base and will also include the cluster name. -endif::osp[] -ifdef::vsphere[] -.. Select *vsphere* as the platform to target. -.. Specify the name of your vCenter instance. -.. Specify the user name and password for the vCenter account that has the required permissions to create the cluster. -+ -The installation program connects to your vCenter instance. -.. Select the datacenter in your vCenter instance to connect to. -.. Select the default vCenter datastore to use. -.. Select the vCenter cluster to install the {product-title} cluster in. -.. Select the network in the vCenter instance that contains the virtual IP addresses and DNS records that you configured. -.. Enter the virtual IP address that you configured for control plane API access. -.. Enter the virtual IP address that you configured for cluster ingress. -.. Enter the base domain. This base domain must be the same one that you used in the DNS records that you configured. -endif::vsphere[] -.. Enter a descriptive name for your cluster. -ifdef::vsphere[] -The cluster name must be the same one that you used in the DNS records that you configured. -endif::vsphere[] -ifdef::azure[] -+ -[IMPORTANT] -==== -All Azure resources that are available through public endpoints are subject to -resource name restrictions, and you cannot create resources that use certain -terms. For a list of terms that Azure restricts, see -link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-reserved-resource-name[Resolve reserved resource name errors] -in the Azure documentation. -==== -endif::azure[] -ifdef::gcp[] -If you provide a name that is longer -than 6 characters, only the first 6 characters will be used in the infrastructure -ID that is generated from the cluster name. -endif::gcp[] -.. Paste the pull secret that you obtained from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. -ifdef::openshift-origin[] -This field is optional. -endif::[] -endif::rhv[] -ifdef::rhv[] -Respond to the installation program prompts. - -.. Optional: For `SSH Public Key`, select a password-less public key, such as `~/.ssh/id_rsa.pub`. This key authenticates connections with the new {product-title} cluster. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, select an SSH key that your `ssh-agent` process uses. -==== -.. For `Platform`, select `ovirt`. -.. For `Enter oVirt's API endpoint URL`, enter the URL of the {rh-virtualization} API using this format: -+ -[source,terminal] ----- -https://<engine-fqdn>/ovirt-engine/api <1> ----- -+ -<1> For `<engine-fqdn>`, specify the fully qualified domain name of the {rh-virtualization} environment. -+ -For example: -+ -ifndef::openshift-origin[] -[source,terminal] ----- -$ curl -k -u ovirtadmin@internal:pw123 \ -https://rhv-env.virtlab.example.com/ovirt-engine/api ----- -endif::openshift-origin[] -ifdef::openshift-origin[] -[source,terminal] ----- -$ curl -k -u ovirtadmin@internal:pw123 \ -https://ovirtlab.example.com/ovirt-engine/api ----- -endif::openshift-origin[] -+ -.. For `Is the oVirt CA trusted locally?`, enter `Yes` since you have already set up a CA certificate. Otherwise, enter `No`. -.. For `oVirt's CA bundle`, if you entered `Yes` for the preceding question, copy the certificate content from `/etc/pki/ca-trust/source/anchors/ca.pem` and paste it here. Then, press `Enter` twice. Otherwise, if you entered `No` for the preceding question, this question does not appear. -.. For `oVirt engine username`, enter the user name and profile of the {rh-virtualization} administrator using this format: -+ -[source,terminal] ----- -<username>@<profile> <1> ----- -+ -<1> For `<username>`, specify the user name of an {rh-virtualization} administrator. For `<profile>`, specify the login profile, which you can get by going to the {rh-virtualization} Administration Portal login page and reviewing the *Profile* dropdown list. Together, the user name and profile should look similar to this example: -+ -[source,terminal] ----- -admin@internal ----- -+ -.. For `oVirt engine password`, enter the {rh-virtualization} admin password. -.. For `oVirt cluster`, select the cluster for installing {product-title}. -.. For `oVirt storage domain`, select the storage domain for installing {product-title}. -.. For `oVirt network`, select a virtual network that has access to the {rh-virtualization} Manager REST API. -.. For `Internal API Virtual IP`, enter the static IP address you set aside for the cluster’s REST API. -.. For `Internal DNS Virtual IP`, enter the static IP address you set aside for the cluster’s internal DNS service. -.. For `Ingress virtual IP`, enter the static IP address you reserved for the wildcard apps domain. -.. For `Base Domain`, enter the base domain of the {product-title} cluster. If this cluster is exposed to the outside world, this must be a valid domain recognized by DNS infrastructure. For example, enter: `virtlab.example.com` -.. For `Cluster Name`, enter the name of the cluster. For example, `my-cluster`. Use cluster name from the externally registered/resolvable DNS entries you created for the {product-title} REST API and apps domain names. The installation program also gives this name to the cluster in the {rh-virtualization} environment. -.. For `Pull Secret`, copy the pull secret from the `pull-secret.txt` file you downloaded earlier and paste it here. You can also get a copy of the same pull secret from the link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. -endif::rhv[] --- -endif::no-config[] -ifdef::vmc[] -+ -[IMPORTANT] -==== -Use the `openshift-install` command from the bastion hosted in the VMC environment. -==== -endif::vmc[] -+ -[NOTE] -==== -If the cloud provider account that you configured on your host does not have sufficient -permissions to deploy the cluster, the installation process stops, and the -missing permissions are displayed. -==== -+ -When the cluster deployment completes, directions for accessing your cluster, -including a link to its web console and credentials for the `kubeadmin` user, -display in your terminal. -+ -.Example output -[source,terminal] ----- -... -INFO Install complete! -INFO To access the cluster as the system:admin user when using 'oc', run 'export KUBECONFIG=/home/myuser/install_dir/auth/kubeconfig' -INFO Access the OpenShift web-console here: https://console-openshift-console.apps.mycluster.example.com -INFO Login to the console with user: "kubeadmin", and password: "4vYBz-Ee6gm-ymBZj-Wt5AL" -INFO Time elapsed: 36m22s ----- -+ -[NOTE] -==== -The cluster access and credential information also outputs to `<installation_directory>/.openshift_install.log` when an installation succeeds. -==== -+ -[IMPORTANT] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== -+ -[IMPORTANT] -==== -You must not delete the installation program or the files that the installation -program creates. Both are required to delete the cluster. -==== - -ifdef::aws[] -. Optional: Remove or disable the `AdministratorAccess` policy from the IAM -account that you used to install the cluster. -+ -[NOTE] -==== -The elevated permissions provided by the `AdministratorAccess` policy are required only during installation. -==== -endif::aws[] - -ifdef::gcp[] -. Optional: You can reduce the number of permissions for the service account that you used to install the cluster. -** If you assigned the `Owner` role to your service account, you can remove that role and replace it with the `Viewer` role. -** If you included the `Service Account Key Admin` role, -you can remove it. -endif::gcp[] - - -ifeval::["{context}" == "installing-aws-customizations"] -:!custom-config: -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-government-region"] -:!custom-config: -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-network-customizations"] -:!custom-config: -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-vpc"] -:!custom-config: -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-default"] -:!no-config: -:!aws: -endif::[] -ifeval::["{context}" == "installing-azure-default"] -:!no-config: -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-network-customizations"] -:!custom-config: -:!azure: -endif::[] -ifeval::["{context}" == "installing-gcp-customizations"] -:!custom-config: -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-vpc"] -:!custom-config: -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-default"] -:!no-config: -:!gcp: -endif::[] -ifeval::["{context}" == "installing-azure-customizations"] -:!custom-config: -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-government-region"] -:!custom-config: -:!azure: -endif::[] -ifeval::["{context}" == "installing-azure-vnet"] -:!custom-config: -:!azure: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-custom"] -:!osp: -:!custom-config: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:!osp: -:!custom-config: -endif::[] -ifeval::["{context}" == "installing-openstack-installer"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-rhv-customizations"] -:!custom-config: -:!rhv: -endif::[] -ifeval::["{context}" == "installing-rhv-default"] -:!no-config: -:!rhv: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned"] -:!no-config: -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-customizations"] -:!custom-config: -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-installer-provisioned-network-customizations"] -:!custom-config: -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc"] -:!no-config: -:!vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-customizations"] -:!custom-config: -:!vmc: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:!custom-config: -:!vmc: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:!custom-config: -:!vsphere: -endif::[] diff --git a/modules/installation-local-registry-pull-secret.adoc b/modules/installation-local-registry-pull-secret.adoc deleted file mode 100644 index 45c07ff50f4b..000000000000 --- a/modules/installation-local-registry-pull-secret.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-restricted-networks-preparations.adoc -// * openshift_images/samples-operator-alt-registry.adoc - -[id="installation-local-registry-pull-secret_{context}"] -= Creating a pull secret for your mirror registry - -In a restricted network, you create a pull secret that contains only -the information for your registry. - -.Prerequisites - -* You configured a mirror registry to use in your restricted network and have its domain name and port as well as credentials for it. - -.Procedure - -. On the mirror host, generate the pull secret for your registry: -+ ----- -$ podman login --authfile ~/pullsecret_config.json <local_registry_host_name>:<local_registry_host_port> <1> ----- -<1> For `<local_registry_host_name>`, specify the registry domain name -for your mirror registry, such as `registry.example.com`. For -`<local_registry_host_port>`, specify the port that your mirror registry uses to -serve content. -+ -Provide your credentials for the mirror registry at the prompts. - -. View the pull secret that you created: -+ ----- -# cat ~/pullsecret_config.json - -{ "auths": { "<local_registry_host_name>:<local_registry_host_port>": { "auth": "ZHVtbXk6ZHVtbXk=" } } } ----- diff --git a/modules/installation-methods-for-different-architectures.adoc b/modules/installation-methods-for-different-architectures.adoc new file mode 100644 index 000000000000..fa75c9b9396f --- /dev/null +++ b/modules/installation-methods-for-different-architectures.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * installing/acs-installation-platforms.adoc +:_mod-docs-content-type: REFERENCE +[id="installation-methods-for-different-architectures_{context}"] += Installation methods for different architectures + +[role="_abstract"] +{rh-rhacs-first} supports the following architectures. For information on supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. Additionally, the following table gives information about installation methods available for each architecture. + +.Architectures and supported installation methods for each architecture +[%autowidth] +|=== +|*Supported architectures*|*Supported installation methods* + +|AMD64 +a|Operator (preferred), Helm charts, or `roxctl` CLI (not recommended) + +|ppc64le ({ibm-power}) +.2+a|Operator + +|s390x ({ibm-z} and {ibm-linuxone}) + +|AArch64 (`ARM64`) +|Operator (preferred), Helm charts, or `roxctl` CLI +|=== \ No newline at end of file diff --git a/modules/installation-mirror-repository.adoc b/modules/installation-mirror-repository.adoc deleted file mode 100644 index 6047b563ea6f..000000000000 --- a/modules/installation-mirror-repository.adoc +++ /dev/null @@ -1,254 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-restricted-networks-preparations.adoc -// * openshift_images/samples-operator-alt-registry.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-mirror-repository_{context}"] -= Mirroring the {product-title} image repository - -Mirror the {product-title} image repository to your registry to use during cluster installation or upgrade. - -.Prerequisites - -* Your mirror host has access to the Internet. -* You configured a mirror registry to use in your restricted network and -can access the certificate and credentials that you configured. -ifndef::openshift-origin[] -* You downloaded the pull secret from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site and modified it to include authentication to your mirror repository. -endif::[] -ifdef::openshift-origin[] -* You have created a pull secret for your mirror repository. -endif::[] - -* If you use self-signed certificates that do not set a Subject Alternative Name, you must precede the `oc` commands in this procedure with `GODEBUG=x509ignoreCN=0`. If you do not set this variable, the `oc` commands will fail with the following error: -+ -[source,terminal] ----- -x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0 ----- - -.Procedure - -Complete the following steps on the mirror host: - -. Review the -link:https://access.redhat.com/downloads/content/290/[{product-title} downloads page] -to determine the version of {product-title} that you want to install and determine the corresponding tag on the link:https://quay.io/repository/openshift-release-dev/ocp-release?tab=tags[Repository Tags] page. - -. Set the required environment variables: -.. Export the release version: -+ -[source,terminal] ----- -$ OCP_RELEASE=<release_version> ----- -+ -For `<release_version>`, specify the tag that corresponds to the version of {product-title} to -install, such as `4.5.4`. - -.. Export the local registry name and host port: -+ -[source,terminal] ----- -$ LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>' ----- -+ -For `<local_registry_host_name>`, specify the registry domain name for your mirror -repository, and for `<local_registry_host_port>`, specify the port that it -serves content on. - -.. Export the local repository name: -+ -[source,terminal] ----- -$ LOCAL_REPOSITORY='<local_repository_name>' ----- -+ -For `<local_repository_name>`, specify the name of the repository to create in your -registry, such as `ocp4/openshift4`. - -.. Export the name of the repository to mirror: -+ -ifndef::openshift-origin[] -[source,terminal] ----- -$ PRODUCT_REPO='openshift-release-dev' ----- -+ -For a production release, you must specify `openshift-release-dev`. -endif::[] -ifdef::openshift-origin[] -[source,terminal] ----- -$ PRODUCT_REPO='openshift' ----- -endif::[] - -.. Export the path to your registry pull secret: -+ -[source,terminal] ----- -$ LOCAL_SECRET_JSON='<path_to_pull_secret>' ----- -+ -For `<path_to_pull_secret>`, specify the absolute path to and file name of the pull secret for your mirror registry that you created. - -.. Export the release mirror: -+ -ifndef::openshift-origin[] -[source,terminal] ----- -$ RELEASE_NAME="ocp-release" ----- -+ -For a production release, you must specify `ocp-release`. -endif::[] -ifdef::openshift-origin[] -[source,terminal] ----- -$ RELEASE_NAME="okd" ----- -endif::[] - -ifndef::openshift-origin[] -.. Export the type of architecture for your server, such as `x86_64`: -+ -[source,terminal] ----- -$ ARCHITECTURE=<server_architecture> ----- -endif::[] - -.. Export the path to the directory to host the mirrored images: -+ -[source,terminal] ----- -$ REMOVABLE_MEDIA_PATH=<path> <1> ----- -<1> Specify the full path, including the initial forward slash (/) character. - -. Mirror the version images to the internal container registry: -** If your mirror host does not have Internet access, take the following actions: -... Connect the removable media to a system that is connected to the Internet. -... Review the images and configuration manifests to mirror: -+ -ifdef::openshift-origin[] -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ - --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} \ - --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ - --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE} --dry-run ----- -endif::[] -ifndef::openshift-origin[] -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ - --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \ - --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ - --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} --dry-run ----- -endif::[] - -... Record the entire `imageContentSources` section from the output of the previous -command. The information about your mirrors is unique to your mirrored repository, and you must add the `imageContentSources` section to the `install-config.yaml` file during installation. -... Mirror the images to a directory on the removable media: -+ -ifdef::openshift-origin[] -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} ----- -endif::[] -ifndef::openshift-origin[] -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} ----- -endif::[] - -... Take the media to the restricted network environment and upload the images to the local container registry. -+ -[source,terminal] ----- -$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} <1> ----- -+ -<1> For `REMOVABLE_MEDIA_PATH`, you must use the same path that you specified when you mirrored the images. - -** If the local container registry is connected to the mirror host, take the following actions: -... Directly push the release images to the local registry by using following command: -+ -ifdef::openshift-origin[] -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ - --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE} \ - --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ - --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE} ----- -endif::[] -ifndef::openshift-origin[] -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} \ - --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \ - --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} \ - --to-release-image=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE} ----- -endif::[] -+ -This command pulls the release information as a digest, and its output includes -the `imageContentSources` data that you require when you install your cluster. - -... Record the entire `imageContentSources` section from the output of the previous -command. The information about your mirrors is unique to your mirrored repository, and you must add the `imageContentSources` section to the `install-config.yaml` file during installation. -+ -[NOTE] -==== -The image name gets patched to Quay.io during the mirroring process, and the podman images will show Quay.io in the registry on the bootstrap virtual machine. -==== - -. To create the installation program that is based on the content that you -mirrored, extract it and pin it to the release: -** If your mirror host does not have Internet access, run the following command: -+ -[source,terminal] ----- -$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}" ----- -** If the local container registry is connected to the mirror host, run the following command: -+ -ifdef::openshift-origin[] -[source,terminal] ----- -$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}" ----- -endif::[] -ifndef::openshift-origin[] -[source,terminal] ----- -$ oc adm release extract -a ${LOCAL_SECRET_JSON} --command=openshift-install "${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}:${OCP_RELEASE}-${ARCHITECTURE}" ----- -endif::[] -+ -[IMPORTANT] -==== -To ensure that you use the correct images for the version of {product-title} -that you selected, you must extract the installation program from the mirrored -content. - -You must perform this step on a machine with an active Internet connection. - -If you are in a disconnected environment, use the `--image` flag as part of must-gather and point to the payload image. -==== -+ -. For clusters using installer-provisioned infrastructure, run the following command: -+ -[source,terminal] ----- -$ openshift-install ----- diff --git a/modules/installation-network-user-infra.adoc b/modules/installation-network-user-infra.adoc deleted file mode 100644 index ff2deaabe878..000000000000 --- a/modules/installation-network-user-infra.adoc +++ /dev/null @@ -1,295 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc -// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc -// * installing/installing_ibm_z/installing-ibm-power.adoc -// * installing/installing_ibm_z/installing-restricted-networks-ibm-power.adoc -// * installing/installing-rhv-restricted-network.adoc - -ifeval::["{context}" == "installing-vsphere"] -:vsphere: -endif::[] - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:vsphere: -endif::[] - -ifeval::["{context}" == "installing-vsphere-network-customizations"] -:vsphere: -endif::[] - -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:ibm-z-kvm: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:restricted: -endif::[] - -[id="installation-network-user-infra_{context}"] -= Networking requirements for user-provisioned infrastructure - -All the {op-system-first} machines require network in `initramfs` during boot -to fetch Ignition config from the machine config server. - -ifdef::ibm-z[] -During the initial boot, the machines require an HTTP or HTTPS server to -establish a network connection to download their Ignition config files. - -Ensure that the machines have persistent IP addresses and host names. -endif::ibm-z[] -ifndef::ibm-z[] -During the initial boot, the machines require either a DHCP server -or that static IP addresses be set on each host in the cluster to -establish a network connection, which allows them to download their Ignition config files. - -It is recommended to use the DHCP server to manage the machines for the cluster -long-term. Ensure that the DHCP server is configured to provide persistent IP -addresses and host names to the cluster machines. -endif::ibm-z[] - -The Kubernetes API server must be able to resolve the node names of the cluster -machines. If the API servers and worker nodes are in different zones, you can -configure a default DNS search zone to allow the API server to resolve the -node names. Another supported approach is to always refer to hosts by their -fully-qualified domain names in both the node objects and all DNS requests. - -You must configure the network connectivity between machines to allow cluster -components to communicate. Each machine must be able to resolve the host names -of all other machines in the cluster. - -ifdef::ibm-z-kvm[] -[NOTE] -==== -The {op-system-base} KVM host must be configured to use bridged networking in libvirt or MacVTap to connect the network to the virtual machines. The virtual machines must have access to the network, which is attached to the {op-system-base} KVM host. Virtual Networks, for example network address translation (NAT), within KVM are not a supported configuration. -==== -endif::ibm-z-kvm[] - -.All machines to all machines -[cols="2a,2a,5a",options="header"] -|=== - -|Protocol -|Port -|Description - -|ICMP -|N/A -|Network reachability tests - -.4+|TCP -|`1936` -|Metrics - -|`9000`-`9999` -|Host level services, including the node exporter on ports `9100`-`9101` and -the Cluster Version Operator on port `9099`. - -|`10250`-`10259` -|The default ports that Kubernetes reserves - -|`10256` -|openshift-sdn - -.3+|UDP -|`4789` -|VXLAN and Geneve - -|`6081` -|VXLAN and Geneve - -|`9000`-`9999` -|Host level services, including the node exporter on ports `9100`-`9101`. - -|TCP/UDP -|`30000`-`32767` -|Kubernetes node port - -|=== - -.All machines to control plane -[cols="2a,2a,5a",options="header"] -|=== - -|Protocol -|Port -|Description - -.2+|TCP -|`2379`-`2380` -|etcd server, peer, and metrics ports - -|`6443` -|Kubernetes API - -|=== - -[discrete] -== Network topology requirements - -The infrastructure that you provision for your cluster must meet the following -network topology requirements. - -ifndef::restricted,origin[] -[IMPORTANT] -==== -{product-title} requires all nodes to have internet access to pull images -for platform containers and provide telemetry data to Red Hat. -==== -endif::restricted,origin[] - -[discrete] -=== Load balancers - -Before you install {product-title}, you must provision two load balancers that meet the following requirements: - -. *API load balancer*: Provides a common endpoint for users, both human and machine, to interact with and configure the platform. Configure the following conditions: -+ --- - ** Layer 4 load balancing only. This can be referred to as Raw TCP, SSL Passthrough, or SSL Bridge mode. If you use SSL Bridge mode, you must enable Server Name Indication (SNI) for the API routes. - ** A stateless load balancing algorithm. The options vary based on the load balancer implementation. --- -+ -[NOTE] -==== -Session persistence is not required for the API load balancer to function properly. -==== -+ -Configure the following ports on both the front and back of the load balancers: -+ -.API load balancer -[cols="2,5,^2,^2,2",options="header"] -|=== - -|Port -|Back-end machines (pool members) -|Internal -|External -|Description - -|`6443` -|Bootstrap and control plane. You remove the bootstrap machine from the load -balancer after the bootstrap machine initializes the cluster control plane. You -must configure the `/readyz` endpoint for the API server health check probe. -|X -|X -|Kubernetes API server - -|`22623` -|Bootstrap and control plane. You remove the bootstrap machine from the load -balancer after the bootstrap machine initializes the cluster control plane. -|X -| -|Machine config server - -|=== -+ -[NOTE] -==== -The load balancer must be configured to take a maximum of 30 seconds from the -time the API server turns off the `/readyz` endpoint to the removal of the API -server instance from the pool. Within the time frame after `/readyz` returns an -error or becomes healthy, the endpoint must have been removed or added. Probing -every 5 or 10 seconds, with two successful requests to become healthy and three -to become unhealthy, are well-tested values. -==== - -. *Application Ingress load balancer*: Provides an Ingress point for application traffic flowing in from outside the cluster. Configure the following conditions: -+ --- - ** Layer 4 load balancing only. This can be referred to as Raw TCP, SSL Passthrough, or SSL Bridge mode. If you use SSL Bridge mode, you must enable Server Name Indication (SNI) for the Ingress routes. - ** A connection-based or session-based persistence is recommended, based on the options available and types of applications that will be hosted on the platform. --- -+ -Configure the following ports on both the front and back of the load balancers: -+ -.Application Ingress load balancer -[cols="2,5,^2,^2,2",options="header"] -|=== - -|Port -|Back-end machines (pool members) -|Internal -|External -|Description - -|`443` -|The machines that run the Ingress router pods, compute, or worker, by default. -|X -|X -|HTTPS traffic - -|`80` -|The machines that run the Ingress router pods, compute, or worker, by default. -|X -|X -|HTTP traffic - -|=== - -[TIP] -==== -If the true IP address of the client can be seen by the load balancer, enabling source IP-based session persistence can improve performance for applications that use end-to-end TLS encryption. -==== - -[NOTE] -==== -A working configuration for the Ingress router is required for an -{product-title} cluster. You must configure the Ingress router after the control -plane initializes. -==== - -ifdef::vsphere[] -[discrete] -== Ethernet adaptor hardware address requirements - -When provisioning VMs for the cluster, the ethernet interfaces configured for -each VM must use a MAC address from the VMware Organizationally Unique -Identifier (OUI) allocation ranges: - -* `00:05:69:00:00:00` to `00:05:69:FF:FF:FF` -* `00:0c:29:00:00:00` to `00:0c:29:FF:FF:FF` -* `00:1c:14:00:00:00` to `00:1c:14:FF:FF:FF` -* `00:50:56:00:00:00` to `00:50:56:FF:FF:FF` - -If a MAC address outside the VMware OUI is used, the cluster installation will -not succeed. -endif::vsphere[] - -ifdef::vsphere[] -:!vsphere: -endif::[] - -[discrete] -== NTP configuration - -An {product-title} cluster that is installed in a restricted network is configured to use a public Network Time Protocol (NTP) server by default. To avoid clock skew, reconfigure the cluster to use a private NTP server instead. For more information, see the documentation for _Configuring chrony time service_. - -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:!ibm-z-kvm: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:!restricted: -endif::[] diff --git a/modules/installation-obtaining-installer.adoc b/modules/installation-obtaining-installer.adoc deleted file mode 100644 index 89a4dec986ae..000000000000 --- a/modules/installation-obtaining-installer.adoc +++ /dev/null @@ -1,118 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-default.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-default.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_gcp/installing-gcp-default.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc -// * installing/installing_rhv/installing-rhv-default.adoc -// * installing/installing_rhv/installing-rhv-customizations.adoc -// * installing/installing_rhv/installing-rhv-user-infra.adoc - - -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:ibm-z-kvm: -endif::[] - -[id="installation-obtaining-installer_{context}"] -= Obtaining the installation program - -Before you install {product-title}, download the installation file on -ifdef::restricted[] -the mirror host. -endif::restricted[] -ifndef::restricted[] -ifdef::ibm-z,ibm-z-kvm[ your provisioning machine.] -ifndef::ibm-z,ibm-z-kvm[ a local computer.] -endif::restricted[] - -.Prerequisites - -ifdef::ibm-z,ibm-z-kvm[* You have a machine that runs Linux, for example Red Hat Enterprise Linux 8, with 500 MB of local disk space] -ifndef::ibm-z,ibm-z-kvm[* You have a computer that runs Linux or macOS, with 500 MB of local disk space] - -.Procedure - -ifndef::openshift-origin[] -. Access the link:https://cloud.redhat.com/openshift/install[Infrastructure Provider] -page on the {cloud-redhat-com} site. If you have a Red Hat account, log in with your credentials. If you do not, create an account. -. Select your infrastructure provider. -. Navigate to the page for your installation type, download the installation program for your operating system, and place the file in the directory where you will store the installation configuration files. -endif::[] -ifdef::openshift-origin[] -. Download installer from https://github.com/openshift/okd/releases -endif::[] - -+ -[IMPORTANT] -==== -The installation program creates several files on the computer that you use to install your cluster. You must keep the installation program and the files that the installation program creates after you finish installing the cluster. Both files are required to delete the cluster. -==== -+ -[IMPORTANT] -==== -Deleting the files created by the installation program does not remove your -cluster, even if the cluster failed during installation. To remove your cluster, complete the -{product-title} uninstallation procedures for your specific cloud -provider. -==== - -. Extract the installation program. For example, on a computer that uses a Linux -operating system, run the following command: -+ -[source,terminal] ----- -$ tar xvf openshift-install-linux.tar.gz ----- - -. From the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site, download your installation pull secret as a `.txt` file. This pull secret allows you to authenticate with the services that -are provided by the included authorities, including Quay.io, which serves the -container images for {product-title} components. -ifdef::openshift-origin[] -+ -If you do not use the pull secret from the {cloud-redhat-com} site: -+ -* Red Hat Operators are not available. -* The Telemetry and Insights operators do not send data to Red Hat. -* Content from the link:https://catalog.redhat.com/software/containers/explore[Red Hat Ecosystem Catalog Container images] registry, such as image streams and Operators, are not available. -endif::openshift-origin[] - -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:!ibm-z-kvm: -endif::[] diff --git a/modules/installation-operators-config.adoc b/modules/installation-operators-config.adoc deleted file mode 100644 index f7c1193546ee..000000000000 --- a/modules/installation-operators-config.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc - -[id="installation-operators-config_{context}"] -= Initial Operator configuration - -After the control plane initializes, you must immediately configure some -Operators so that they all become available. - -.Prerequisites - -* Your control plane has initialized. - -.Procedure - -. Watch the cluster components come online: -+ -[source,terminal] ----- -$ watch -n5 oc get clusteroperators ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -authentication 4.7.0 True False False 3h56m -baremetal 4.7.0 True False False 29h -cloud-credential 4.7.0 True False False 29h -cluster-autoscaler 4.7.0 True False False 29h -config-operator 4.7.0 True False False 6h39m -console 4.7.0 True False False 3h59m -csi-snapshot-controller 4.7.0 True False False 4h12m -dns 4.7.0 True False False 4h15m -etcd 4.7.0 True False False 29h -image-registry 4.7.0 True False False 3h59m -ingress 4.7.0 True False False 4h30m -insights 4.7.0 True False False 29h -kube-apiserver 4.7.0 True False False 29h -kube-controller-manager 4.7.0 True False False 29h -kube-scheduler 4.7.0 True False False 29h -kube-storage-version-migrator 4.7.0 True False False 4h2m -machine-api 4.7.0 True False False 29h -machine-approver 4.7.0 True False False 6h34m -machine-config 4.7.0 True False False 3h56m -marketplace 4.7.0 True False False 4h2m -monitoring 4.7.0 True False False 6h31m -network 4.7.0 True False False 29h -node-tuning 4.7.0 True False False 4h30m -openshift-apiserver 4.7.0 True False False 3h56m -openshift-controller-manager 4.7.0 True False False 4h36m -openshift-samples 4.7.0 True False False 4h30m -operator-lifecycle-manager 4.7.0 True False False 29h -operator-lifecycle-manager-catalog 4.7.0 True False False 29h -operator-lifecycle-manager-packageserver 4.7.0 True False False 3h59m -service-ca 4.7.0 True False False 29h -storage 4.7.0 True False False 4h30m ----- -. Configure the Operators that are not available. diff --git a/modules/installation-osp-about-kuryr.adoc b/modules/installation-osp-about-kuryr.adoc deleted file mode 100644 index c06cf0ea1554..000000000000 --- a/modules/installation-osp-about-kuryr.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-about-kuryr_{context}"] -= About Kuryr SDN - -link:https://docs.openstack.org/kuryr-kubernetes/latest/[Kuryr] is a container -network interface (CNI) plug-in solution that uses the -link:https://docs.openstack.org/neutron/latest/[Neutron] and -link:https://docs.openstack.org/octavia/latest/[Octavia] {rh-openstack-first} services -to provide networking for pods and Services. - -Kuryr and {product-title} integration is primarily designed for -{product-title} clusters running on {rh-openstack} VMs. Kuryr improves the -network performance by plugging {product-title} pods into {rh-openstack} SDN. -In addition, it provides interconnectivity between pods and -{rh-openstack} virtual instances. - -Kuryr components are installed as pods in {product-title} using the -`openshift-kuryr` namespace: - -* `kuryr-controller` - a single service instance installed on a `master` node. -This is modeled in {product-title} as a `Deployment` object. -* `kuryr-cni` - a container installing and configuring Kuryr as a CNI driver on -each {product-title} node. This is modeled in {product-title} as a `DaemonSet` object. - -The Kuryr controller watches the {product-title} API server for pod, service, and -namespace create, update, and delete events. It maps the {product-title} API -calls to corresponding objects in Neutron and Octavia. This means that every -network solution that implements the Neutron trunk port functionality can be -used to back {product-title} via Kuryr. This includes open source solutions -such as Open vSwitch (OVS) and Open Virtual Network (OVN) as well as -Neutron-compatible commercial SDNs. - -Kuryr is recommended for {product-title} deployments on encapsulated {rh-openstack} tenant -networks to avoid double encapsulation, such as running an encapsulated -{product-title} SDN over an {rh-openstack} network. - -If you use provider networks or tenant VLANs, you do not need to use Kuryr to -avoid double encapsulation. The performance benefit is negligible. Depending on -your configuration, though, using Kuryr to avoid having two overlays might still -be beneficial. - -Kuryr is not recommended in deployments where all of the following criteria are true: - -* The {rh-openstack} version is less than 16. -* The deployment uses UDP services, or a large number of TCP services on few hypervisors. - -or - -* The `ovn-octavia` Octavia driver is disabled. -* The deployment uses a large number of TCP services on few hypervisors. \ No newline at end of file diff --git a/modules/installation-osp-accessing-api-floating.adoc b/modules/installation-osp-accessing-api-floating.adoc deleted file mode 100644 index 3c2a125ed254..000000000000 --- a/modules/installation-osp-accessing-api-floating.adoc +++ /dev/null @@ -1,92 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-user.adoc - -ifeval::["{context}" == "installing-openstack-user"] -:osp-user: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:osp-user: -endif::[] - -[id="installation-osp-accessing-api-floating_{context}"] -= Enabling access with floating IP addresses - -Create floating IP (FIP) addresses for external access to the {product-title} -ifdef::osp-user[API, cluster applications, and the bootstrap process.] -ifndef::osp-user[API and cluster applications.] - -.Procedure - -. Using the {rh-openstack-first} CLI, create the API FIP: -+ -[source,terminal] ----- -$ openstack floating ip create --description "API <cluster_name>.<base_domain>" <external_network> ----- - -. Using the {rh-openstack-first} CLI, create the apps, or Ingress, FIP: -+ -[source,terminal] ----- -$ openstack floating ip create --description "Ingress <cluster_name>.<base_domain>" <external_network> ----- - -ifdef::osp-user[] -. By using the {rh-openstack-first} CLI, create the bootstrap FIP: -+ -[source,terminal] ----- -$ openstack floating ip create --description "bootstrap machine" <external_network> ----- -endif::osp-user[] - -. Add records that follow these patterns to your DNS server for the API and Ingress FIPs: -+ -[source,dns] ----- -api.<cluster_name>.<base_domain>. IN A <API_FIP> -*.apps.<cluster_name>.<base_domain>. IN A <apps_FIP> ----- -+ -[NOTE] -==== -If you do not control the DNS server, you can add the record to your `/etc/hosts` file. This action makes the API accessible to only you, which is not suitable for production deployment but does allow installation for development and testing. -==== - -. Add the FIPs to the -ifdef::osp-user[`inventory.yaml`] -ifndef::osp-user[`install-config.yaml`] -file as the values of the following -ifdef::osp-user[variables:] -ifndef::osp-user[parameters:] - -ifdef::osp-user[] -* `os_api_fip` -* `os_bootstrap_fip` -* `os_ingress_fip` -endif::osp-user[] - -ifndef::osp-user[] -* `platform.openstack.ingressFloatingIP` -* `platform.openstack.lbFloatingIP` -endif::osp-user[] - -If you use these values, you must also enter an external network as the value of the -ifdef::osp-user[`os_external_network` variable in the `inventory.yaml` file.] -ifndef::osp-user[`platform.openstack.externalNetwork` parameter in the `install-config.yaml` file.] - -[TIP] -==== -You can make {product-title} resources available outside of the cluster by assigning a floating IP address and updating your firewall configuration. -==== - -ifeval::["{context}" == "installing-openstack-user"] -:!osp-user: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:!osp-user: -endif::[] diff --git a/modules/installation-osp-accessing-api-no-floating.adoc b/modules/installation-osp-accessing-api-no-floating.adoc deleted file mode 100644 index 896c9bf2f6b3..000000000000 --- a/modules/installation-osp-accessing-api-no-floating.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc - -ifeval::["{context}" == "installing-openstack-installer-custom"] -:osp-ipi: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:osp-kuryr: -:osp-ipi: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:osp-upi: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:osp-kuryr: -:osp-upi: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:osp-ipi: -:osp-restricted: -endif::[] - -[id="installation-osp-accessing-api-no-floating_{context}"] -= Completing installation without floating IP addresses - -You can install {product-title} on {rh-openstack-first} without providing floating IP addresses. - -In the -ifdef::osp-ipi[`install-config.yaml`] -ifdef::osp-upi[`inventory.yaml`] -file, do not define the following -ifdef::osp-ipi[parameters:] -ifdef::osp-upi[variables:] - -ifdef::osp-ipi[] -* `platform.openstack.ingressFloatingIP` -* `platform.openstack.lbFloatingIP` - -If you cannot provide an external network, you can also leave `platform.openstack.externalNetwork` blank. If you do not provide a value for `platform.openstack.externalNetwork`, a router is not created for you, and, without additional action, the installer will fail to retrieve an image from Glance. You must configure external connectivity on your own. -endif::osp-ipi[] - -ifdef::osp-upi[] -* `os_api_fip` -* `os_bootstrap_fip` -* `os_ingress_fip` - -If you cannot provide an external network, you can also leave `os_external_network` blank. If you do not provide a value for `os_external_network`, a router is not created for you, and, without additional action, the installer will fail to retrieve an image from Glance. Later in the installation process, when you create network resources, you must configure external connectivity on your own. -endif::osp-upi[] - -If you run the installer -ifdef::osp-upi[with the `wait-for` command] -from a system that cannot reach the cluster API due to a lack of floating IP addresses or name resolution, installation fails. To prevent installation failure in these cases, you can use a proxy network or run the installer from a system that is on the same network as your machines. - -[NOTE] -==== -You can enable name resolution by creating DNS records for the API and Ingress ports. For example: - -[source,dns] ----- -api.<cluster_name>.<base_domain>. IN A <api_port_IP> -*.apps.<cluster_name>.<base_domain>. IN A <ingress_port_IP> ----- - -If you do not control the DNS server, you can add the record to your `/etc/hosts` file. This action makes the API accessible to only you, which is not suitable for production deployment but does allow installation for development and testing. -==== - -ifeval::["{context}" == "installing-openstack-installer-custom"] -:!osp-ipi: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:!osp-kuryr: -:!osp-ipi: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:!osp-upi: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:!osp-kuryr: -:!osp-upi: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-restricted"] -:!osp-ipi: -:!osp-restricted: -endif::[] diff --git a/modules/installation-osp-accessing-api.adoc b/modules/installation-osp-accessing-api.adoc deleted file mode 100644 index 22de3d2cddb0..000000000000 --- a/modules/installation-osp-accessing-api.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc -// -// Stub module. To be used with other FIP OSP modules only. - -[id="installation-osp-accessing-api_{context}"] -= Enabling access to the environment - -At deployment, all {product-title} machines are created in a {rh-openstack-first}-tenant network. Therefore, they are not accessible directly in most {rh-openstack} deployments. - -You can configure {product-title} API and application access by using floating IP addresses (FIPs) during installation. You can also complete an installation without configuring FIPs, but the installer will not configure a way to reach the API or applications externally. diff --git a/modules/installation-osp-api-octavia.adoc b/modules/installation-osp-api-octavia.adoc deleted file mode 100644 index 8d04a884c1ee..000000000000 --- a/modules/installation-osp-api-octavia.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/load-balancing-openstack.adoc - -[id="installation-osp-api-octavia_{context}"] -= Scaling clusters for application traffic by using Octavia - -{product-title} clusters that run on {rh-openstack-first} can use the Octavia load balancing service to distribute traffic across multiple virtual machines (VMs) or floating IP addresses. This feature mitigates the bottleneck that single machines or addresses create. - -If your cluster uses Kuryr, the Cluster Network Operator created an internal Octavia load balancer at deployment. You can use this load balancer for application network scaling. - -If your cluster does not use Kuryr, you must create your own Octavia load balancer to use it for application network scaling. \ No newline at end of file diff --git a/modules/installation-osp-api-scaling.adoc b/modules/installation-osp-api-scaling.adoc deleted file mode 100644 index 2cc1d5fa446f..000000000000 --- a/modules/installation-osp-api-scaling.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/load-balancing-openstack.adoc - -[id="installation-osp-api-scaling_{context}"] -= Scaling clusters by using Octavia - -If you want to use multiple API load balancers, or if your cluster does not use Kuryr, create an Octavia load balancer and then configure your cluster to use it. - -.Prerequisites - -* Octavia is available on your {rh-openstack-first} deployment. - -.Procedure - -. From a command line, create an Octavia load balancer that uses the Amphora driver: -+ -[source,terminal] ----- -$ openstack loadbalancer create --name API_OCP_CLUSTER --vip-subnet-id <id_of_worker_vms_subnet> ----- -+ -You can use a name of your choice instead of `API_OCP_CLUSTER`. - -. After the load balancer becomes active, create listeners: -+ -[source,terminal] ----- -$ openstack loadbalancer listener create --name API_OCP_CLUSTER_6443 --protocol HTTPS--protocol-port 6443 API_OCP_CLUSTER ----- -+ -[NOTE] -==== -To view the status of the load balancer, enter `openstack loadbalancer list`. -==== - -. Create a pool that uses the round robin algorithm and has session persistence enabled: -+ -[source,terminal] ----- -$ openstack loadbalancer pool create --name API_OCP_CLUSTER_pool_6443 --lb-algorithm ROUND_ROBIN --session-persistence type=<source_IP_address> --listener API_OCP_CLUSTER_6443 --protocol HTTPS ----- - -. To ensure that control plane machines are available, create a health monitor: -+ -[source,terminal] ----- -$ openstack loadbalancer healthmonitor create --delay 5 --max-retries 4 --timeout 10 --type TCP API_OCP_CLUSTER_pool_6443 ----- - -. Add the control plane machines as members of the load balancer pool: -+ -[source,terminal] ----- -$ for SERVER in $(MASTER-0-IP MASTER-1-IP MASTER-2-IP) -do - openstack loadbalancer member create --address $SERVER --protocol-port 6443 API_OCP_CLUSTER_pool_6443 -done ----- - -. Optional: To reuse the cluster API floating IP address, unset it: -+ -[source,terminal] ----- -$ openstack floating ip unset $API_FIP ----- - -. Add either the unset `API_FIP` or a new address to the created load balancer VIP: -+ -[source,terminal] ----- -$ openstack floating ip set --port $(openstack loadbalancer show -c <vip_port_id> -f value API_OCP_CLUSTER) $API_FIP ----- - -Your cluster now uses Octavia for load balancing. - -[NOTE] -==== -If Kuryr uses the Octavia Amphora driver, all traffic is routed through a single Amphora virtual machine (VM). - -You can repeat this procedure to create additional load balancers, which can alleviate the bottleneck. -==== diff --git a/modules/installation-osp-balancing-external-loads.adoc b/modules/installation-osp-balancing-external-loads.adoc deleted file mode 100644 index d37f7713291f..000000000000 --- a/modules/installation-osp-balancing-external-loads.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-load-balancing.adoc - -[id="installation-osp-balancing-external-loads_{context}"] -= Configuring an external load balancer - -Configure an external load balancer in {rh-openstack-first} to use your own load balancer, resolve external networking needs, or scale beyond what the default {product-title} load balancer can provide. - -The load balancer serves ports 6443, 443, and 80 to any users of the system. Port 22623 serves Ignition start-up configurations to the {product-title} machines and must not be reachable from outside the cluster. - -.Prerequisites - -* Access to a {rh-openstack} administrator's account -* The https://docs.openstack.org/python-openstackclient/latest/[{rh-openstack} client] installed on the target environment - -.Procedure - -. Using the {rh-openstack} CLI, add floating IP addresses to all of the control plane machines: -+ -[source,terminal] ----- -$ openstack floating ip create --port master-port-0 <public network> ----- -+ -[source,terminal] ----- -$ openstack floating ip create --port master-port-1 <public network> ----- -+ -[source,terminal] ----- -$ openstack floating ip create --port master-port-2 <public network> ----- - -. View the new floating IPs: -+ -[source,terminal] ----- -$ openstack server list ----- - -. Incorporate the listed floating IP addresses into the load balancer configuration to allow access the cluster via port 6443. -+ -.A HAProxy configuration for port 6443 -[source,txt] ----- -listen <cluster name>-api-6443 - bind 0.0.0.0:6443 - mode tcp - balance roundrobin - server <cluster name>-master-2 <floating ip>:6443 check - server <cluster name>-master-0 <floating ip>:6443 check - server <cluster name>-master-1 <floating ip>:6443 check ----- - -. Repeat the previous three steps for ports 443 and 80. - -. Enable network access from the load balancer network to the control plane machines on ports 6443, 443, and 80: -+ -[source,terminal] ----- -$ openstack security group rule create master --remote-ip <load balancer CIDR> --ingress --protocol tcp --dst-port 6443 ----- -+ -[source,terminal] ----- -$ openstack security group rule create master --remote-ip <load balancer CIDR> --ingress --protocol tcp --dst-port 443 ----- -+ -[source,terminal] ----- -$ openstack security group rule create master --remote-ip <load balancer CIDR> --ingress --protocol tcp --dst-port 80 ----- - -[TIP] -You can also specify a particular IP address with `/32`. - -. Update the DNS entry for `api.<cluster name>.<base domain>` to point to the new load balancer: -+ -[source,txt] ----- -<load balancer ip> api.<cluster-name>.<base domain> ----- -+ -The external load balancer is now available. - -. Verify the load balancer's functionality by using the following curl command: -+ -[source,terminal] ----- -$ curl https://<loadbalancer-ip>:6443/version --insecure ----- -+ -The output resembles the following example: -+ -[source,json] ----- -{ - "major": "1", - "minor": "11+", - "gitVersion": "v1.11.0+ad103ed", - "gitCommit": "ad103ed", - "gitTreeState": "clean", - "buildDate": "2019-01-09T06:44:10Z", - "goVersion": "go1.10.3", - "compiler": "gc", - "platform": "linux/amd64" -} ----- - -. Optional: Verify that the Ignition configuration files are available only from -within the cluster by running a curl command on port 22623 from outside the cluster: -+ -[source,terminal] ----- -$ curl https://<loadbalancer ip>:22623/config/master --insecure ----- -+ -The command fails. diff --git a/modules/installation-osp-bootstrap-machine.adoc b/modules/installation-osp-bootstrap-machine.adoc deleted file mode 100644 index d5871d5c0e6c..000000000000 --- a/modules/installation-osp-bootstrap-machine.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-bootstrap-machine_{context}"] -= Bootstrap machine - -During installation, a bootstrap machine is temporarily provisioned to stand up the -control plane. After the production control plane is ready, the bootstrap -machine is deprovisioned. - -The bootstrap machine requires: - -* An instance from the {rh-openstack} quota -* A port from the {rh-openstack} quota -* A flavor with at least 16 GB memory, 4 vCPUs, and 25 GB storage space \ No newline at end of file diff --git a/modules/installation-osp-config-yaml.adoc b/modules/installation-osp-config-yaml.adoc deleted file mode 100644 index 5d7e0f64de4a..000000000000 --- a/modules/installation-osp-config-yaml.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-config-yaml_{context}"] -= Sample customized `install-config.yaml` file for {rh-openstack} - -This sample `install-config.yaml` demonstrates all of the possible {rh-openstack-first} -customization options. - -[IMPORTANT] -This sample file is provided for reference only. You must obtain your -`install-config.yaml` file by using the installation program. - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com -controlPlane: - name: master - platform: {} - replicas: 3 -compute: -- name: worker - platform: - openstack: - type: ml.large - replicas: 3 -metadata: - name: example -networking: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineNetwork: - - cidr: 10.0.0.0/16 - serviceNetwork: - - 172.30.0.0/16 -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] -platform: - openstack: - cloud: mycloud - externalNetwork: external - computeFlavor: m1.xlarge - lbFloatingIP: 128.0.0.1 -ifndef::openshift-origin[] -fips: false -endif::openshift-origin[] -pullSecret: '{"auths": ...}' -sshKey: ssh-ed25519 AAAA... ----- diff --git a/modules/installation-osp-configuring-api-floating-ip.adoc b/modules/installation-osp-configuring-api-floating-ip.adoc deleted file mode 100644 index 4b8e613a466b..000000000000 --- a/modules/installation-osp-configuring-api-floating-ip.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/network-configuration.adoc - -[id="installation-osp-configuring-api-floating-ip_{context}"] -= Configuring application access with floating IP addresses - -After you install {product-title}, configure {rh-openstack-first} to allow application network traffic. - -[NOTE] -==== -You do not need to perform this procedure if you provided values for `platform.openstack.lbFloatingIP` and `platform.openstack.ingressFloatingIP` in the `install-config.yaml` file, or `os_api_fip` and `os_ingress_fip` in the `inventory.yaml` playbook, during installation. The floating IP addresses are already set. -==== - -.Prerequisites - -* {product-title} cluster must be installed -* Floating IP addresses are enabled as described in the {product-title} on {rh-openstack} installation documentation. - -.Procedure - -After you install the {product-title} cluster, attach a floating IP address to the ingress port: - -. Show the port: -+ -[source,terminal] ----- -$ openstack port show <cluster_name>-<cluster_ID>-ingress-port ----- - -. Attach the port to the IP address: -+ -[source,terminal] ----- -$ openstack floating ip set --port <ingress_port_ID> <apps_FIP> ----- - -. Add a wildcard `A` record for `*apps.` to your DNS file: -+ -[source,dns] ----- -*.apps.<cluster_name>.<base_domain> IN A <apps_FIP> ----- - -[NOTE] -==== -If you do not control the DNS server but want to enable application access for non-production purposes, you can add these hostnames to `/etc/hosts`: - -[source,dns] ----- -<apps_FIP> console-openshift-console.apps.<cluster name>.<base domain> -<apps_FIP> integrated-oauth-server-openshift-authentication.apps.<cluster name>.<base domain> -<apps_FIP> oauth-openshift.apps.<cluster name>.<base domain> -<apps_FIP> prometheus-k8s-openshift-monitoring.apps.<cluster name>.<base domain> -<apps_FIP> grafana-openshift-monitoring.apps.<cluster name>.<base domain> -<apps_FIP> <app name>.apps.<cluster name>.<base domain> ----- -==== diff --git a/modules/installation-osp-control-compute-machines.adoc b/modules/installation-osp-control-compute-machines.adoc deleted file mode 100644 index 9d84fd1595f9..000000000000 --- a/modules/installation-osp-control-compute-machines.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-control-compute-machines_{context}"] -= Control plane and compute machines - -By default, the {product-title} installation process stands up three control -plane and three compute machines. - -Each machine requires: - -* An instance from the {rh-openstack} quota -* A port from the {rh-openstack} quota -* A flavor with at least 16 GB memory, 4 vCPUs, and 25 GB storage space - -[TIP] -==== -Compute machines host the applications that you run on {product-title}; aim to -run as many as you can. -==== - -// == Compute machines - -// By default, the {product-title} installation program stands up three compute machines. - -// What about instances and ports? -// Each worker node requires: - -// * An instance from the {rh-openstack} quota -// * A port from the {rh-openstack} quota -// * A flavor with at least 16 GB memory, 4 vCPUs, and 25 GB storage space - -// Each compute machine requires a flavor with at least 8 GB memory, 2 vCPUs, and 25 GB storage space. diff --git a/modules/installation-osp-converting-ignition-resources.adoc b/modules/installation-osp-converting-ignition-resources.adoc deleted file mode 100644 index b5003e97bd39..000000000000 --- a/modules/installation-osp-converting-ignition-resources.adoc +++ /dev/null @@ -1,166 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc - -[id="installation-osp-converting-ignition-resources_{context}"] -= Preparing the bootstrap Ignition files - -The {product-title} installation process relies on bootstrap machines that are created from a bootstrap Ignition configuration file. - -Edit the file and upload it. Then, create a secondary bootstrap Ignition configuration file that -{rh-openstack-first} uses to download the primary file. - -.Prerequisites - -* You have the bootstrap Ignition file that the installer program generates, `bootstrap.ign`. -* The infrastructure ID from the installer's metadata file is set as an environment variable (`$INFRA_ID`). -** If the variable is not set, see *Creating the Kubernetes manifest and Ignition config files*. -* You have an HTTP(S)-accessible way to store the bootstrap Ignition file. -** The documented procedure uses the {rh-openstack} image service (Glance), but you can also use the {rh-openstack} storage service (Swift), Amazon S3, an internal HTTP server, or an ad hoc Nova server. - -.Procedure - -. Run the following Python script. The script modifies the bootstrap Ignition file to set the host name and, if available, CA certificate file when it runs: -+ -[source,python] ----- -import base64 -import json -import os - -with open('bootstrap.ign', 'r') as f: - ignition = json.load(f) - -files = ignition['storage'].get('files', []) - -infra_id = os.environ.get('INFRA_ID', 'openshift').encode() -hostname_b64 = base64.standard_b64encode(infra_id + b'-bootstrap\n').decode().strip() -files.append( -{ - 'path': '/etc/hostname', - 'mode': 420, - 'contents': { - 'source': 'data:text/plain;charset=utf-8;base64,' + hostname_b64 - } -}) - -ca_cert_path = os.environ.get('OS_CACERT', '') -if ca_cert_path: - with open(ca_cert_path, 'r') as f: - ca_cert = f.read().encode() - ca_cert_b64 = base64.standard_b64encode(ca_cert).decode().strip() - - files.append( - { - 'path': '/opt/openshift/tls/cloud-ca-cert.pem', - 'mode': 420, - 'contents': { - 'source': 'data:text/plain;charset=utf-8;base64,' + ca_cert_b64 - } - }) - -ignition['storage']['files'] = files; - -with open('bootstrap.ign', 'w') as f: - json.dump(ignition, f) ----- - -. Using the {rh-openstack} CLI, create an image that uses the bootstrap Ignition file: -+ -[source,terminal] ----- -$ openstack image create --disk-format=raw --container-format=bare --file bootstrap.ign <image_name> ----- - -. Get the image's details: -+ -[source,terminal] ----- -$ openstack image show <image_name> ----- -+ -Make a note of the `file` value; it follows the pattern `v2/images/<image_ID>/file`. -+ -[NOTE] -Verify that the image you created is active. - -. Retrieve the image service's public address: -+ -[source,terminal] ----- -$ openstack catalog show image ----- - -. Combine the public address with the image `file` value and save the result as the storage location. The location follows the pattern `<image_service_public_URL>/v2/images/<image_ID>/file`. - -. Generate an auth token and save the token ID: -+ -[source,terminal] ----- -$ openstack token issue -c id -f value ----- - -. Insert the following content into a file called `$INFRA_ID-bootstrap-ignition.json` and edit the placeholders to match your own values: -+ -[source,json] ----- -{ - "ignition": { - "config": { - "merge": [{ - "source": "<storage_url>", <1> - "httpHeaders": [{ - "name": "X-Auth-Token", <2> - "value": "<token_ID>" <3> - }] - }] - }, - "security": { - "tls": { - "certificateAuthorities": [{ - "source": "data:text/plain;charset=utf-8;base64,<base64_encoded_certificate>" <4> - }] - } - }, - "version": "3.1.0" - } -} ----- -<1> Replace the value of `ignition.config.merge.source` with the bootstrap Ignition file storage URL. -<2> Set `name` in `httpHeaders` to `"X-Auth-Token"`. -<3> Set `value` in `httpHeaders` to your token's ID. -<4> If the bootstrap Ignition file server uses a self-signed certificate, include the base64-encoded certificate. - -. Save the secondary Ignition config file. - -The bootstrap Ignition data will be passed to {rh-openstack} during installation. - -[WARNING] -The bootstrap Ignition file contains sensitive information, like `clouds.yaml` credentials. Ensure that you store it in a secure place, and delete it after you complete the installation process. - -// . If you are using Swift: -// .. Using the Swift CLI, create a container: -// + -// ---- -// $ swift post <container_name> -// ---- -// -// .. Upload the bootstrap Ignition file to the container: -// + -// ---- -// $ swift upload <container_name> bootstrap.ign -// ---- -// -// .. Set the container to be read-accessible: -// + -// ---- -// $ swift post <container_name> --read-acl ".r:*,.rlistings" -// ---- -// -// .. Retrieve the storage URL: -// + -// ---- -// $ swift stat -v -// ---- -// ** The URL should follow this format: `<storage_URL>/<container_name>/bootstrap.ign` -// May need to bring this back. diff --git a/modules/installation-osp-creating-bootstrap-machine.adoc b/modules/installation-osp-creating-bootstrap-machine.adoc deleted file mode 100644 index 9b8d6724d3d5..000000000000 --- a/modules/installation-osp-creating-bootstrap-machine.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc - -[id="installation-osp-creating-bootstrap-machine_{context}"] -= Creating the bootstrap machine on {rh-openstack} - -Create a bootstrap machine and give it the network access it needs to run on {rh-openstack-first}. Red Hat provides an Ansible playbook that you run to simplify this process. - -.Prerequisites -* You downloaded the modules in "Downloading playbook dependencies." -* You downloaded the playbooks in "Downloading the installation playbooks." -* The `inventory.yaml`, `common.yaml`, and `bootstrap.yaml` Ansible playbooks are in a common directory. -* The `metadata.json` file that the installation program created is in the same directory as the Ansible playbooks. - -.Procedure - -. On a command line, change the working directory to the location of the playbooks. - -. On a command line, run the `bootstrap.yaml` playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yaml bootstrap.yaml ----- - -. After the bootstrap server is active, view the logs to verify that the Ignition files were received: -+ -[source,terminal] ----- -$ openstack console log show "$INFRA_ID-bootstrap" ----- diff --git a/modules/installation-osp-creating-compute-machines.adoc b/modules/installation-osp-creating-compute-machines.adoc deleted file mode 100644 index aaf19acebc05..000000000000 --- a/modules/installation-osp-creating-compute-machines.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc - -[id="installation-osp-creating-compute-machines_{context}"] -= Creating compute machines on {rh-openstack} - -After standing up the control plane, create compute machines. Red Hat provides an Ansible playbook that you run to simplify this process. - -.Prerequisites -* You downloaded the modules in "Downloading playbook dependencies." -* You downloaded the playbooks in "Downloading the installation playbooks." -* The `inventory.yaml`, `common.yaml`, and `compute-nodes.yaml` Ansible playbooks are in a common directory. -* The `metadata.json` file that the installation program created is in the same directory as the Ansible playbooks. -* The control plane is active. - -.Procedure - -. On a command line, change the working directory to the location of the playbooks. - -. On a command line, run the playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yaml compute-nodes.yaml ----- - -.Next steps - -* Approve the certificate signing requests for the machines. diff --git a/modules/installation-osp-creating-control-plane-ignition.adoc b/modules/installation-osp-creating-control-plane-ignition.adoc deleted file mode 100644 index 7a5e758f97ba..000000000000 --- a/modules/installation-osp-creating-control-plane-ignition.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc - -[id="installation-osp-creating-control-plane-ignition_{context}"] -= Creating control plane Ignition config files on {rh-openstack} - -Installing {product-title} on {rh-openstack-first} on your own infrastructure requires control plane Ignition config files. You must create multiple config files. - -[NOTE] -As with the bootstrap Ignition configuration, you must explicitly define a host name for each control plane machine. - -.Prerequisites - -* The infrastructure ID from the installation program's metadata file is set as an environment variable (`$INFRA_ID`). -** If the variable is not set, see "Creating the Kubernetes manifest and Ignition config files." - -.Procedure - -* On a command line, run the following Python script: -+ -[source,terminal] ----- -$ for index in $(seq 0 2); do - MASTER_HOSTNAME="$INFRA_ID-master-$index\n" - python -c "import base64, json, sys; -ignition = json.load(sys.stdin); -storage = ignition.get('storage', {}); -files = storage.get('files', []); -files.append({'path': '/etc/hostname', 'mode': 420, 'contents': {'source': 'data:text/plain;charset=utf-8;base64,' + base64.standard_b64encode(b'$MASTER_HOSTNAME').decode().strip(), 'verification': {}}, 'filesystem': 'root'}); -storage['files'] = files; -ignition['storage'] = storage -json.dump(ignition, sys.stdout)" <master.ign >"$INFRA_ID-master-$index-ignition.json" -done ----- -+ -You now have three control plane Ignition files: `<INFRA_ID>-master-0-ignition.json`, `<INFRA_ID>-master-1-ignition.json`, -and `<INFRA_ID>-master-2-ignition.json`. \ No newline at end of file diff --git a/modules/installation-osp-creating-control-plane.adoc b/modules/installation-osp-creating-control-plane.adoc deleted file mode 100644 index ecbd24ec98d4..000000000000 --- a/modules/installation-osp-creating-control-plane.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc - -[id="installation-osp-creating-control-plane_{context}"] -= Creating the control plane machines on {rh-openstack} - -Create three control plane machines by using the Ignition config files that you generated. Red Hat provides an Ansible playbook that you run to simplify this process. - -.Prerequisites - -* You downloaded the modules in "Downloading playbook dependencies." -* You downloaded the playbooks in "Downloading the installation playbooks." -* The infrastructure ID from the installation program's metadata file is set as an environment variable (`$INFRA_ID`). -* The `inventory.yaml`, `common.yaml`, and `control-plane.yaml` Ansible playbooks are in a common directory. -* You have the three Ignition files that were created in "Creating control plane Ignition config files." - -.Procedure - -. On a command line, change the working directory to the location of the playbooks. - -. If the control plane Ignition config files aren't already in your working directory, copy them into it. - -. On a command line, run the `control-plane.yaml` playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yaml control-plane.yaml ----- - -. Run the following command to monitor the bootstrapping process: -+ -[source,terminal] ----- -$ openshift-install wait-for bootstrap-complete ----- -+ -You will see messages that confirm that the control plane machines are running and have joined the cluster: -+ -[source,terminal] ----- -INFO API v1.14.6+f9b5405 up -INFO Waiting up to 30m0s for bootstrapping to complete... -... -INFO It is now safe to remove the bootstrap resources ----- \ No newline at end of file diff --git a/modules/installation-osp-creating-image.adoc b/modules/installation-osp-creating-image.adoc deleted file mode 100644 index 7d4b2e034aad..000000000000 --- a/modules/installation-osp-creating-image.adoc +++ /dev/null @@ -1,56 +0,0 @@ -//Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc - -[id="installation-osp-creating-image_{context}"] -= Creating the {op-system-first} image - -The {product-title} installation program requires that a {op-system-first} image be present in the {rh-openstack-first} cluster. Retrieve the latest {op-system} image, then upload it using the {rh-openstack} CLI. - -.Prerequisites - -* The {rh-openstack} CLI is installed. - -.Procedure - -. Log in to the Red Hat Customer Portal's https://access.redhat.com/downloads/content/290[Product Downloads page]. - -. Under *Version*, select the most recent release of {product-title} {product-version} for {op-system-base-full} 8. -+ -[IMPORTANT] -==== -The {op-system} images might not change with every release of {product-title}. -You must download images with the highest version that is less than or equal to -the {product-title} version that you install. Use the image versions that match -your {product-title} version if they are available. -==== - -. Download the _{op-system-first} - OpenStack Image (QCOW)_. - -. Decompress the image. -+ -[NOTE] -==== -You must decompress the {rh-openstack} image before the cluster can use it. The name of the downloaded file might not contain a compression extension, like `.gz` or `.tgz`. To find out if or how the file is compressed, in a command line, enter: - -[source,terminal] ----- -$ file <name_of_downloaded_file> ----- - -==== - -. From the image that you downloaded, create an image that is named `rhcos` in your cluster by using the {rh-openstack} CLI: -+ -[source,terminal] ----- -$ openstack image create --container-format=bare --disk-format=qcow2 --file rhcos-${RHCOS_VERSION}-openstack.qcow2 rhcos ----- -+ -[IMPORTANT] -Depending on your {rh-openstack} environment, you might be able to upload the image in either link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/15/html/instances_and_images_guide/index[`.raw` or `.qcow2` formats]. If you use Ceph, you must use the `.raw` format. -+ -[WARNING] -If the installation program finds multiple images with the same name, it chooses one of them at random. To avoid this behavior, create unique names for resources in {rh-openstack}. - -After you upload the image to {rh-openstack}, it is usable in the installation process. diff --git a/modules/installation-osp-creating-network-resources.adoc b/modules/installation-osp-creating-network-resources.adoc deleted file mode 100644 index a4b6d2708b3d..000000000000 --- a/modules/installation-osp-creating-network-resources.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc - -[id="installation-osp-creating-network-resources_{context}"] -= Creating network resources on {rh-openstack} - -Create the network resources that an {product-title} on {rh-openstack-first} installation on your own infrastructure requires. To save time, run supplied Ansible playbooks that generate security groups, networks, subnets, routers, and ports. - -.Prerequisites - -* Python 3 is installed on your machine. -* You downloaded the modules in "Downloading playbook dependencies." -* You downloaded the playbooks in "Downloading the installation playbooks." - -.Procedure - -. Optional: Add an external network value to the `inventory.yaml` playbook: -+ -.Example external network value in the `inventory.yaml` Ansible playbook -[source,yaml] ----- -... - # The public network providing connectivity to the cluster. If not - # provided, the cluster external connectivity must be provided in another - # way. - - # Required for os_api_fip, os_ingress_fip, os_bootstrap_fip. - os_external_network: 'external' -... ----- -+ -[IMPORTANT] -==== -If you did not provide a value for `os_external_network` in the `inventory.yaml` file, you must ensure that VMs can access Glance and an external connection yourself. -==== - -. Optional: Add external network and floating IP (FIP) address values to the `inventory.yaml` playbook: -+ -.Example FIP values in the `inventory.yaml` Ansible playbook -[source,yaml] ----- -... - # OpenShift API floating IP address. If this value is non-empty, the - # corresponding floating IP will be attached to the Control Plane to - # serve the OpenShift API. - os_api_fip: '203.0.113.23' - - # OpenShift Ingress floating IP address. If this value is non-empty, the - # corresponding floating IP will be attached to the worker nodes to serve - # the applications. - os_ingress_fip: '203.0.113.19' - - # If this value is non-empty, the corresponding floating IP will be - # attached to the bootstrap machine. This is needed for collecting logs - # in case of install failure. - os_bootstrap_fip: '203.0.113.20' ----- -+ -[IMPORTANT] -==== -If you do not define values for `os_api_fip` and `os_ingress_fip`, you must perform post-installation network configuration. - -If you do not define a value for `os_bootstrap_fip`, the installer cannot download debugging information from failed installations. - -See "Enabling access to the environment" for more information. -==== - -. On a command line, create security groups by running the `security-groups.yaml` playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yaml security-groups.yaml ----- - -. On a command line, create a network, subnet, and router by running the `network.yaml` playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yaml network.yaml ----- - -. Optional: If you want to control the default resolvers that Nova servers use, run the {rh-openstack} CLI command: -+ -[source,terminal] ----- -$ openstack subnet set --dns-nameserver <server_1> --dns-nameserver <server_2> "$INFRA_ID-nodes" ----- \ No newline at end of file diff --git a/modules/installation-osp-custom-subnet.adoc b/modules/installation-osp-custom-subnet.adoc deleted file mode 100644 index 3c1f9077a31d..000000000000 --- a/modules/installation-osp-custom-subnet.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// - -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc - -[id="installation-osp-custom-subnet_{context}"] -= Custom subnets in {rh-openstack} deployments - -Optionally, you can deploy a cluster on a {rh-openstack-first} subnet of your choice. The subnet's GUID is passed as the value of `platform.openstack.machinesSubnet` in the `install-config.yaml` file. - -This subnet is used as the cluster's primary subnet. By default, nodes and ports are created on it. You can create nodes and ports on a different {rh-openstack} subnet by setting the value of the `platform.openstack.machinesSubnet` property to the subnet's UUID. - -Before you run the {product-title} installer with a custom subnet, verify that your configuration meets the following requirements: - -* The subnet that is used by `platform.openstack.machinesSubnet` has DHCP enabled. -* The CIDR of `platform.openstack.machinesSubnet` matches the CIDR of `networking.machineNetwork`. -* The installation program user has permission to create ports on this network, including ports with fixed IP addresses. - -Clusters that use custom subnets have the following limitations: - -* If you plan to install a cluster that uses floating IP addresses, the `platform.openstack.machinesSubnet` subnet must be attached to a router that is connected to the `externalNetwork` network. - -* If the `platform.openstack.machinesSubnet` value is set in the `install-config.yaml` file, the installation program does not create a private network or subnet for your {rh-openstack} machines. - -* You cannot use the `platform.openstack.externalDNS` property at the same time as a custom subnet. To add DNS to a cluster that uses a custom subnet, configure DNS on the {rh-openstack} network. - -[NOTE] -==== -By default, the API VIP takes x.x.x.5 and the Ingress VIP takes x.x.x.7 from your network's CIDR block. To override these default values, -set values for `platform.openstack.apiVIP` and `platform.openstack.ingressVIP` that are outside of the DHCP allocation pool. -==== diff --git a/modules/installation-osp-default-deployment.adoc b/modules/installation-osp-default-deployment.adoc deleted file mode 100644 index 1d9ad8951fc1..000000000000 --- a/modules/installation-osp-default-deployment.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-user.adoc - -[id="installation-osp-default-deployment_{context}"] -= Resource guidelines for installing {product-title} on {rh-openstack} - -To support an {product-title} installation, your {rh-openstack-first} quota must meet the following requirements: - -.Recommended resources for a default {product-title} cluster on {rh-openstack} -[options="header"] -|====================================== -|Resource | Value -|Floating IP addresses | 3 -|Ports | 15 -|Routers | 1 -|Subnets | 1 -|RAM | 112 GB -|vCPUs | 28 -|Volume storage | 275 GB -|Instances | 7 -|Security groups | 3 -|Security group rules | 60 -|====================================== - -A cluster might function with fewer than recommended resources, but its performance is not guaranteed. - -[IMPORTANT] -==== -If {rh-openstack} object storage (Swift) is available and operated by a user account with the `swiftoperator` role, it is used as the default backend for the {product-title} image registry. In this case, the volume storage requirement is 175 GB. Swift space requirements vary depending on the size of the image registry. -==== - -[NOTE] -By default, your security group and security group rule quotas might be low. If you encounter problems, run `openstack quota set --secgroups 3 --secgroup-rules 60 <project>` as an administrator to increase them. - -An {product-title} deployment comprises control plane machines, compute machines, and a bootstrap machine. \ No newline at end of file diff --git a/modules/installation-osp-default-kuryr-deployment.adoc b/modules/installation-osp-default-kuryr-deployment.adoc deleted file mode 100644 index 42382dd64fa7..000000000000 --- a/modules/installation-osp-default-kuryr-deployment.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-default-kuryr-deployment_{context}"] -= Resource guidelines for installing {product-title} on {rh-openstack} with Kuryr - -When using Kuryr SDN, the pods, services, namespaces, and network policies are -using resources from the {rh-openstack} quota; this increases the minimum -requirements. Kuryr also has some additional requirements on top of what a -default install requires. - -Use the following quota to satisfy a default cluster's minimum requirements: - -.Recommended resources for a default {product-title} cluster on {rh-openstack} with Kuryr - -[options="header"] -|============================================================================================== -|Resource | Value -|Floating IP addresses | 3 - plus the expected number of Services of LoadBalancer type -|Ports | 1500 - 1 needed per Pod -|Routers | 1 -|Subnets | 250 - 1 needed per Namespace/Project -|Networks | 250 - 1 needed per Namespace/Project -|RAM | 112 GB -|vCPUs | 28 -|Volume storage | 275 GB -|Instances | 7 -|Security groups | 250 - 1 needed per Service and per NetworkPolicy -|Security group rules | 1000 -|Load balancers | 100 - 1 needed per Service -|Load balancer listeners | 500 - 1 needed per Service-exposed port -|Load balancer pools | 500 - 1 needed per Service-exposed port -|============================================================================================== - -A cluster might function with fewer than recommended resources, but its performance is not guaranteed. - -[IMPORTANT] -==== -If {rh-openstack} object storage (Swift) is available and operated by a user account with the `swiftoperator` role, it is used as the default backend for the {product-title} image registry. In this case, the volume storage requirement is 175 GB. Swift space requirements vary depending on the size of the image registry. -==== - -[IMPORTANT] -==== -If you are using {rh-openstack-first} version 16 with the Amphora driver rather than the OVN Octavia driver, security groups are associated with service accounts instead of user projects. -==== - -Take the following notes into consideration when setting resources: - -* The number of ports that are required is larger than the number of pods. Kuryr -uses ports pools to have pre-created ports ready to be used by pods and speed up -the pods' booting time. - -* Each network policy is mapped into an {rh-openstack} security group, and -depending on the `NetworkPolicy` spec, one or more rules are added to the -security group. - -* Each service is mapped to an {rh-openstack} load balancer. Consider this requirement - when estimating the number of security groups required for the quota. -+ -If you are using -{rh-openstack} version 15 or earlier, or the `ovn-octavia driver`, each load balancer -has a security group with the user project. - -* The quota does not account for load balancer resources (such as VM -resources), but you must consider these resources when you decide the -{rh-openstack} deployment's size. The default installation will have more than -50 load balancers; the clusters must be able to accommodate them. -+ -If you are using {rh-openstack} version 16 with the OVN Octavia driver enabled, only one load balancer -VM is generated; services are load balanced through OVN flows. - -An {product-title} deployment comprises control plane machines, compute -machines, and a bootstrap machine. - -To enable Kuryr SDN, your environment must meet the following requirements: - -* Run {rh-openstack} 13+. -* Have Overcloud with Octavia. -* Use Neutron Trunk ports extension. -* Use `openvswitch` firewall driver if ML2/OVS Neutron driver is used instead -of `ovs-hybrid`. diff --git a/modules/installation-osp-deleting-bootstrap-resources.adoc b/modules/installation-osp-deleting-bootstrap-resources.adoc deleted file mode 100644 index 3d9f6b562b67..000000000000 --- a/modules/installation-osp-deleting-bootstrap-resources.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc - -[id="installation-osp-deleting-bootstrap-resources_{context}"] -= Deleting bootstrap resources from {rh-openstack} - -Delete the bootstrap resources that you no longer need. - -.Prerequisites -* You downloaded the modules in "Downloading playbook dependencies." -* You downloaded the playbooks in "Downloading the installation playbooks." -* The `inventory.yaml`, `common.yaml`, and `down-bootstrap.yaml` Ansible playbooks are in a common directory. -* The control plane machines are running. -** If you do not know the status of the machines, see "Verifying cluster status." - -.Procedure - -. On a command line, change the working directory to the location of the playbooks. - -. On a command line, run the `down-bootstrap.yaml` playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yaml down-bootstrap.yaml ----- - -The bootstrap port, server, and floating IP address are deleted. - -[WARNING] -If you did not disable the bootstrap Ignition file URL earlier, do so now. \ No newline at end of file diff --git a/modules/installation-osp-deploying-bare-metal-machines.adoc b/modules/installation-osp-deploying-bare-metal-machines.adoc deleted file mode 100644 index 1ec2e6839923..000000000000 --- a/modules/installation-osp-deploying-bare-metal-machines.adoc +++ /dev/null @@ -1,134 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-user.adoc - -ifeval::["{context}" == "installing-openstack-installer-custom"] -:osp-ipi: -endif::[] - -[id="installation-osp-deploying-bare-metal-machines_{context}"] -= Deploying a cluster with bare metal machines - -If you want your cluster to use bare metal machines, modify the -ifdef::osp-ipi[`install-config.yaml`] -ifndef::osp-ipi[`inventory.yaml`] -file. Your cluster can have both control plane and compute machines running on bare metal, or just compute machines. - -Bare-metal compute machines are not supported on clusters that use Kuryr. - -[NOTE] -==== -Be sure that your `install-config.yaml` file reflects whether the {rh-openstack} network that you use for bare metal workers supports floating IP addresses or not. - -==== - -.Prerequisites - -* The {rh-openstack} link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/bare_metal_provisioning/index[Bare Metal service (Ironic)] is enabled and accessible via the {rh-openstack} Compute API. - -* Bare metal is available as link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/bare_metal_provisioning/sect-configure#creating_the_bare_metal_flavor[a {rh-openstack} flavor]. - -* The {rh-openstack} network supports both VM and bare metal server attachment. - -* Your network configuration does not rely on a provider network. Provider networks are not supported. - -* If you want to deploy the machines on a pre-existing network, a {rh-openstack} subnet is provisioned. - -* If you want to deploy the machines on an installer-provisioned network, the {rh-openstack} Bare Metal service (Ironic) is able to listen for and interact with Preboot eXecution Environment (PXE) boot machines that run on tenant networks. - -ifdef::osp-ipi[] -* You created an `install-config.yaml` file as part of the {product-title} installation process. -endif::osp-ipi[] - -ifndef::osp-ipi[] -* You created an `inventory.yaml` file as part of the {product-title} installation process. -endif::osp-ipi[] - -.Procedure - -ifdef::osp-ipi[] -. In the `install-config.yaml` file, edit the flavors for machines: -.. If you want to use bare-metal control plane machines, change the value of `controlPlane.platform.openstack.type` to a bare metal flavor. -.. Change the value of `compute.platform.openstack.type` to a bare metal flavor. -.. If you want to deploy your machines on a pre-existing network, change the value of `platform.openstack.machinesSubnet` to the {rh-openstack} subnet UUID of the network. Control plane and compute machines must use the same subnet. -+ -.An example bare metal `install-config.yaml` file -[source,yaml] ----- -controlPlane: - platform: - openstack: - type: <bare_metal_control_plane_flavor> <1> -... - -compute: - - architecture: amd64 - hyperthreading: Enabled - name: worker - platform: - openstack: - type: <bare_metal_compute_flavor> <2> - replicas: 3 -... - -platform: - openstack: - machinesSubnet: <subnet_UUID> <3> -... ----- -<1> If you want to have bare-metal control plane machines, change this value to a bare metal flavor. -<2> Change this value to a bare metal flavor to use for compute machines. -<3> If you want to use a pre-existing network, change this value to the UUID of the {rh-openstack} subnet. - - -Use the updated `install-config.yaml` file to complete the installation process. -The compute machines that are created during deployment use the flavor that you -added to the file. -endif::osp-ipi[] - -ifndef::osp-ipi[] -. In the `inventory.yaml` file, edit the flavors for machines: -.. If you want to use bare-metal control plane machines, change the value of `os_flavor_master` to a bare metal flavor. -.. Change the value of `os_flavor_worker` to a bare metal flavor. -+ -.An example bare metal `inventory.yaml` file -[source,yaml] ----- -all: - hosts: - localhost: - ansible_connection: local - ansible_python_interpreter: "{{ansible_playbook_python}}" - - # User-provided values - os_subnet_range: '10.0.0.0/16' - os_flavor_master: 'my-bare-metal-flavor' <1> - os_flavor_worker: 'my-bare-metal-flavor' <2> - os_image_rhcos: 'rhcos' - os_external_network: 'external' -... ----- -<1> If you want to have bare-metal control plane machines, change this value to a bare metal flavor. -<2> Change this value to a bare metal flavor to use for compute machines. - -Use the updated `inventory.yaml` file to complete the installation process. -Machines that are created during deployment use the flavor that you -added to the file. -endif::osp-ipi[] - -[NOTE] -==== -The installer may time out while waiting for bare metal machines to boot. - -If the installer times out, restart and then complete the deployment by using the `wait-for` command of the installer. For example: - -[source,terminal] ----- -./openshift-install wait-for install-complete --log-level debug ----- -==== - -ifeval::["{context}" == "installing-openstack-installer-custom"] -:!osp-ipi: -endif::[] diff --git a/modules/installation-osp-describing-cloud-parameters.adoc b/modules/installation-osp-describing-cloud-parameters.adoc deleted file mode 100644 index afa8a3f2cfd8..000000000000 --- a/modules/installation-osp-describing-cloud-parameters.adoc +++ /dev/null @@ -1,91 +0,0 @@ -//Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-installer-user.adoc - -[id="installation-osp-describing-cloud-parameters_{context}"] -= Defining parameters for the installation program - -The {product-title} installation program relies on a file that is called `clouds.yaml`. The file describes {rh-openstack-first} configuration parameters, including the project name, log in information, and authorization service URLs. - -.Procedure - -. Create the `clouds.yaml` file: - -** If your {rh-openstack} distribution includes the Horizon web UI, generate a `clouds.yaml` file in it. -+ -[IMPORTANT] -==== -Remember to add a password to the `auth` field. You can also keep secrets in link:https://docs.openstack.org/os-client-config/latest/user/configuration.html#splitting-secrets[a separate file] from `clouds.yaml`. -==== - -** If your {rh-openstack} distribution does not include the Horizon web UI, or you do not want to use Horizon, create the file yourself. For detailed information about `clouds.yaml`, see https://docs.openstack.org/openstacksdk/latest/user/config/configuration.html#config-files[Config files] in the {rh-openstack} documentation. -+ -[source,yaml] ----- -clouds: - shiftstack: - auth: - auth_url: http://10.10.14.42:5000/v3 - project_name: shiftstack - username: shiftstack_user - password: XXX - user_domain_name: Default - project_domain_name: Default - dev-env: - region_name: RegionOne - auth: - username: 'devuser' - password: XXX - project_name: 'devonly' - auth_url: 'https://10.10.14.22:5001/v2.0' ----- - -. If your {rh-openstack} installation uses self-signed certificate authority (CA) certificates for endpoint authentication: -.. Copy the certificate authority file to your machine. -.. Add the machine to the certificate authority trust bundle: -+ -[source,terminal] ----- -$ sudo cp ca.crt.pem /etc/pki/ca-trust/source/anchors/ ----- - -.. Update the trust bundle: -+ -[source,terminal] ----- -$ sudo update-ca-trust extract ----- - -.. Add the `cacerts` key to the `clouds.yaml` file. The value must be an absolute, non-root-accessible path to the CA certificate: -+ -[source,yaml] ----- -clouds: - shiftstack: - ... - cacert: "/etc/pki/ca-trust/source/anchors/ca.crt.pem" ----- -+ -[TIP] -==== -After you run the installer with a custom CA certificate, you can update the certificate by editing the value of the `ca-cert.pem` key in the `cloud-provider-config` keymap. On a command line, run: -[source,terminal] ----- -$ oc edit configmap -n openshift-config cloud-provider-config ----- -==== - -. Place the `clouds.yaml` file in one of the following locations: -.. The value of the `OS_CLIENT_CONFIG_FILE` environment variable -.. The current directory -.. A Unix-specific user configuration directory, for example `~/.config/openstack/clouds.yaml` -.. A Unix-specific site configuration directory, for example `/etc/openstack/clouds.yaml` -+ -The installation program searches for `clouds.yaml` in that order. -//// -[TIP] -To set up an isolated development environment, you can use a bare metal host that runs CentOS 7. See https://github.com/shiftstack-dev-tools/ocp-doit[OpenShift Installer OpenStack Dev Scripts] for details. -//// diff --git a/modules/installation-osp-downloading-modules.adoc b/modules/installation-osp-downloading-modules.adoc deleted file mode 100644 index 7e6f9da1ead8..000000000000 --- a/modules/installation-osp-downloading-modules.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// * installing/installing_openstack/installing-openstack-installer-user.adoc -// * installing/installing_openstack/installing-openstack-installer-user-kuryr.adoc -// * installing/installing_openstack/uninstalling-openstack-user.adoc -// -//YOU MUST SET AN IFEVAL FOR EACH NEW MODULE - -ifeval::["{context}" == "installing-openstack-user"] -:osp-user: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:osp-user: -endif::[] -ifeval::["{context}" == "uninstalling-openstack-user"] -:osp-user-uninstall: -endif::[] - -[id="installation-osp-downloading-modules_{context}"] -= Downloading playbook dependencies - -ifdef::osp-user[] -The Ansible playbooks that simplify the installation process on user-provisioned -infrastructure require several Python modules. On the machine where you will run the installer, -add the modules' repositories and then download them. -endif::osp-user[] - -ifdef::osp-user-uninstall[] -The Ansible playbooks that simplify the removal process on user-provisioned -infrastructure require several Python modules. On the machine where you will run the process, -add the modules' repositories and then download them. -endif::osp-user-uninstall[] - -[NOTE] -These instructions assume that you are using {op-system-base-full} 8. - -.Prerequisites - -* Python 3 is installed on your machine. - -.Procedure - -. On a command line, add the repositories: - -.. Register with Red Hat Subscription Manager: -+ -[source,terminal] ----- -$ sudo subscription-manager register # If not done already ----- - -.. Pull the latest subscription data: -+ -[source,terminal] ----- -$ sudo subscription-manager attach --pool=$YOUR_POOLID # If not done already ----- - -.. Disable the current repositories: -+ -[source,terminal] ----- -$ sudo subscription-manager repos --disable=* # If not done already ----- - -.. Add the required repositories: -+ -[source,terminal] ----- -$ sudo subscription-manager repos \ - --enable=rhel-8-for-x86_64-baseos-rpms \ - --enable=openstack-16-tools-for-rhel-8-x86_64-rpms \ - --enable=ansible-2.9-for-rhel-8-x86_64-rpms \ - --enable=rhel-8-for-x86_64-appstream-rpms ----- - -ifdef::osp-user[] -. Install the modules: -+ -[source,terminal] ----- -$ sudo yum install python3-openstackclient ansible python3-openstacksdk python3-netaddr ----- -endif::osp-user[] - -ifdef::osp-user-uninstall[] -. Install the modules: -+ -[source,terminal] ----- -$ sudo yum install python3-openstackclient ansible python3-openstacksdk ----- -endif::osp-user-uninstall[] - -. Ensure that the `python` command points to `python3`: -+ -[source,terminal] ----- -$ sudo alternatives --set python /usr/bin/python3 ----- - -ifeval::["{context}" == "installing-openstack-user"] -:!osp-user: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:!osp-user: -endif::[] -ifeval::["{context}" == "uninstalling-cluster-openstack"] -:!osp-user-uninstall: -endif::[] \ No newline at end of file diff --git a/modules/installation-osp-downloading-playbooks.adoc b/modules/installation-osp-downloading-playbooks.adoc deleted file mode 100644 index a0e14c1109ad..000000000000 --- a/modules/installation-osp-downloading-playbooks.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc - -[id="installation-osp-downloading-playbooks_{context}"] -= Downloading the installation playbooks - -Download Ansible playbooks that you can use to install {product-title} on your own {rh-openstack-first} infrastructure. - -.Prerequisites - -* The curl command-line tool is available on your machine. - -.Procedure - -* To download the playbooks to your working directory, run the following script from a command line: -+ -[source,terminal,subs=attributes+] ----- -$ xargs -n 1 curl -O <<< ' - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/bootstrap.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/common.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/compute-nodes.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/control-plane.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/inventory.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/network.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/security-groups.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/down-bootstrap.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/down-compute-nodes.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/down-control-plane.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/down-load-balancers.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/down-network.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/down-security-groups.yaml - https://raw.githubusercontent.com/openshift/installer/release-{product-version}/upi/openstack/down-containers.yaml' ----- - -The playbooks are downloaded to your machine. - -[IMPORTANT] -==== -During the installation process, you can modify the playbooks to configure your deployment. - -Retain all playbooks for the life of your cluster. You must have the playbooks to remove your {product-title} cluster from {rh-openstack}. -==== - -[IMPORTANT] -==== -You must match any edits you make in the `bootstrap.yaml`, `compute-nodes.yaml`, `control-plane.yaml`, `network.yaml`, and `security-groups.yaml` files to the corresponding playbooks that are prefixed with `down-`. For example, edits to the `bootstrap.yaml` file must be reflected in the `down-bootstrap.yaml` file, too. If you do not edit both files, the supported cluster removal process will fail. -==== diff --git a/modules/installation-osp-emptying-worker-pools.adoc b/modules/installation-osp-emptying-worker-pools.adoc deleted file mode 100644 index ef8fdcfe8031..000000000000 --- a/modules/installation-osp-emptying-worker-pools.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// * installing/installing_openstack/installing-openstack-user.adoc -// * installing/installing_openstack/installing-openstack-user-kuryr.adoc - -[id="installation-osp-emptying-worker-pools_{context}"] -= Emptying compute machine pools - -To proceed with an installation that uses your own infrastructure, set the number of compute machines in the installation configuration file to zero. Later, you create these machines manually. - -.Prerequisites - -* You have the `install-config.yaml` file that was generated by the {product-title} installation program. - -.Procedure - -. On a command line, browse to the directory that contains `install-config.yaml`. - -. From that directory, either run a script to edit the `install-config.yaml` file or update the file manually: - -** To set the value by using a script, run: -+ -[source,terminal] ----- -$ python -c ' -import yaml; -path = "install-config.yaml"; -data = yaml.safe_load(open(path)); -data["compute"][0]["replicas"] = 0; -open(path, "w").write(yaml.dump(data, default_flow_style=False))' ----- - -** To set the value manually, open the file and set the value of `compute.<first entry>.replicas` to `0`. diff --git a/modules/installation-osp-enabling-swift.adoc b/modules/installation-osp-enabling-swift.adoc deleted file mode 100644 index 6f59fa9f6d46..000000000000 --- a/modules/installation-osp-enabling-swift.adoc +++ /dev/null @@ -1,36 +0,0 @@ -//Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-enabling-swift_{context}"] -= Enabling Swift on {rh-openstack} - -Swift is operated by a user account with the `swiftoperator` role. Add the role to an account before you run the installation program. - -[IMPORTANT] -==== -If link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.0/html-single/storage_guide/index#ch-manage-containers[the {rh-openstack-first} object storage service], commonly known as Swift, is available, {product-title} uses it as the image registry storage. If it is unavailable, the installation program relies on the {rh-openstack} block storage service, commonly known as Cinder. - -If Swift is present and you want to use it, you must enable access to it. If it is not present, or if you do not want to use it, skip this section. -==== - -.Prerequisites - -* You have a {rh-openstack} administrator account on the target environment. -* The Swift service is installed. -* On link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.0/html-single/deploying_an_overcloud_with_containerized_red_hat_ceph/index#ceph-rgw[Ceph RGW], the `account in url` option is enabled. - -.Procedure - -To enable Swift on {rh-openstack}: - -. As an administrator in the {rh-openstack} CLI, add the `swiftoperator` role to the account that will access Swift: -+ -[source,terminal] ----- -$ openstack role add --user <user> --project <project> swiftoperator ----- - -Your {rh-openstack} deployment can now use Swift for the image registry. diff --git a/modules/installation-osp-fixing-subnet.adoc b/modules/installation-osp-fixing-subnet.adoc deleted file mode 100644 index 978dd121bb64..000000000000 --- a/modules/installation-osp-fixing-subnet.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// * installing/installing_openstack/installing-openstack-installer-user.adoc -// -//YOU MUST SET AN IFEVAL FOR EACH NEW MODULE - -[id="installation-osp-fixing-subnet_{context}"] -= Setting a custom subnet for machines - -The IP range that the installation program uses by default might not match the Neutron subnet that you create when you install {product-title}. If necessary, update the CIDR value for new machines by editing the installation configuration file. - -.Prerequisites - -* You have the `install-config.yaml` file that was generated by the {product-title} installation program. - -.Procedure - -. On a command line, browse to the directory that contains `install-config.yaml`. - -. From that directory, either run a script to edit the `install-config.yaml` file or update the file manually: - -** To set the value by using a script, run: -+ -[source,terminal] ----- -$ python -c ' -import yaml; -path = "install-config.yaml"; -data = yaml.safe_load(open(path)); -data["networking"]["machineNetwork"] = [{"cidr": "192.168.0.0/18"}]; <1> -open(path, "w").write(yaml.dump(data, default_flow_style=False))' ----- -<1> Insert a value that matches your intended Neutron subnet, e.g. `192.0.2.0/24`. - -** To set the value manually, open the file and set the value of `networking.machineCIDR` to something that matches your intended Neutron subnet. diff --git a/modules/installation-osp-kuryr-api-scaling.adoc b/modules/installation-osp-kuryr-api-scaling.adoc deleted file mode 100644 index 2f3422e12f36..000000000000 --- a/modules/installation-osp-kuryr-api-scaling.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/load-balancing-openstack.adoc - -[id="installation-osp-kuryr-api-scaling_{context}"] -= Scaling clusters that use Kuryr by using Octavia - -If your cluster uses Kuryr, associate the API floating IP address of your cluster with the pre-existing Octavia load balancer. - -.Prerequisites - -* Your {product-title} cluster uses Kuryr. - -* Octavia is available on your {rh-openstack-first} deployment. - -.Procedure - -. Optional: From a command line, to reuse the cluster API floating IP address, unset it: -+ -[source,terminal] ----- -$ openstack floating ip unset $API_FIP ----- - -. Add either the unset `API_FIP` or a new address to the created load balancer VIP: -+ -[source,terminal] ----- -$ openstack floating ip set --port $(openstack loadbalancer show -c <vip_port_id> -f value ${OCP_CLUSTER}-kuryr-api-loadbalancer) $API_FIP ----- - -Your cluster now uses Octavia for load balancing. - -[NOTE] -==== -If Kuryr uses the Octavia Amphora driver, all traffic is routed through a single Amphora virtual machine (VM). - -You can repeat this procedure to create additional load balancers, which can alleviate the bottleneck. -==== \ No newline at end of file diff --git a/modules/installation-osp-kuryr-config-yaml.adoc b/modules/installation-osp-kuryr-config-yaml.adoc deleted file mode 100644 index 7f6e3a377110..000000000000 --- a/modules/installation-osp-kuryr-config-yaml.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-kuryr-config-yaml_{context}"] -= Sample customized `install-config.yaml` file for {rh-openstack} with Kuryr - -To deploy with Kuryr SDN instead of the default OpenShift SDN, you must -modify the `install-config.yaml` file to include `Kuryr` as the desired -`networking.networkType` and proceed with the default {product-title} SDN installation steps. -This sample `install-config.yaml` demonstrates all of the possible -{rh-openstack-first} customization options. - -[IMPORTANT] -==== -This sample file is provided for reference only. You must obtain your -`install-config.yaml` file by using the installation program. -==== - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com -controlPlane: - name: master - platform: {} - replicas: 3 -compute: -- name: worker - platform: - openstack: - type: ml.large - replicas: 3 -metadata: - name: example -networking: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineNetwork: - - cidr: 10.0.0.0/16 - serviceNetwork: - - 172.30.0.0/16 <1> - networkType: Kuryr -platform: - openstack: - cloud: mycloud - externalNetwork: external - computeFlavor: m1.xlarge - lbFloatingIP: 128.0.0.1 - trunkSupport: true <2> - octaviaSupport: true <2> -pullSecret: '{"auths": ...}' -sshKey: ssh-ed25519 AAAA... ----- -<1> The Amphora Octavia driver creates two ports per load balancer. As a -result, the service subnet that the installer creates is twice the size of the -CIDR that is specified as the value of the `serviceNetwork` property. The larger range is -required to prevent IP address conflicts. -<2> Both `trunkSupport` and `octaviaSupport` are automatically discovered by the -installer, so there is no need to set them. But if your environment does not -meet both requirements, Kuryr SDN will not properly work. Trunks are needed -to connect the pods to the {rh-openstack} network and Octavia is required to create the -{product-title} services. diff --git a/modules/installation-osp-kuryr-increase-quota.adoc b/modules/installation-osp-kuryr-increase-quota.adoc deleted file mode 100644 index 97b6b20f2849..000000000000 --- a/modules/installation-osp-kuryr-increase-quota.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-kuryr-increase-quota_{context}"] -= Increasing quota - -When using Kuryr SDN, you must increase quotas to satisfy the {rh-openstack-first} -resources used by pods, services, namespaces, and network policies. - -.Procedure - -* Increase the quotas for a project by running the following command: -+ -[source,terminal] ----- -$ sudo openstack quota set --secgroups 250 --secgroup-rules 1000 --ports 1500 --subnets 250 --networks 250 <project> ----- diff --git a/modules/installation-osp-kuryr-ingress-scaling.adoc b/modules/installation-osp-kuryr-ingress-scaling.adoc deleted file mode 100644 index 73a57400c100..000000000000 --- a/modules/installation-osp-kuryr-ingress-scaling.adoc +++ /dev/null @@ -1,122 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/load-balancing-openstack.adoc - -[id="installation-osp-kuryr-octavia-scale_{context}"] -= Scaling for ingress traffic by using {rh-openstack} Octavia - -You can use Octavia load balancers to scale Ingress controllers on clusters that use Kuryr. - -.Prerequisites - -* Your {product-title} cluster uses Kuryr. - -* Octavia is available on your {rh-openstack} deployment. - -.Procedure - -. To copy the current internal router service, on a command line, enter: -+ -[source,terminal] ----- -$ oc -n openshift-ingress get svc router-internal-default -o yaml > external_router.yaml ----- - -. In the file `external_router.yaml`, change the values of `metadata.name` and `spec.type` to -`LoadBalancer`. -+ -[source,yaml] -.Example router file ----- -apiVersion: v1 -kind: Service -metadata: - labels: - ingresscontroller.operator.openshift.io/owning-ingresscontroller: default - name: router-external-default <1> - namespace: openshift-ingress -spec: - ports: - - name: http - port: 80 - protocol: TCP - targetPort: http - - name: https - port: 443 - protocol: TCP - targetPort: https - - name: metrics - port: 1936 - protocol: TCP - targetPort: 1936 - selector: - ingresscontroller.operator.openshift.io/deployment-ingresscontroller: default - sessionAffinity: None - type: LoadBalancer <2> ----- -<1> Ensure that this value is descriptive, like `router-external-default`. -<2> Ensure that this value is `LoadBalancer`. - -[NOTE] -==== -You can delete timestamps and other information that is irrelevant to load balancing. -==== - -. From a command line, create a service from the `external_router.yaml` file: -+ -[source,terminal] ----- -$ oc apply -f external_router.yaml ----- - -. Verify that the external IP address of the service is the same as the one that is associated with the load balancer: -.. On a command line, retrieve the external IP address of the service: -+ -[source,terminal] ----- -$ oc -n openshift-ingress get svc ----- -+ -[source,terminal] -.Example output ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -router-external-default LoadBalancer 172.30.235.33 10.46.22.161 80:30112/TCP,443:32359/TCP,1936:30317/TCP 3m38s -router-internal-default ClusterIP 172.30.115.123 <none> 80/TCP,443/TCP,1936/TCP 22h ----- - -.. Retrieve the IP address of the load balancer: -+ -[source,terminal] ----- -$ openstack loadbalancer list | grep router-external ----- -+ -.Example output -[source,terminal] ----- -| 21bf6afe-b498-4a16-a958-3229e83c002c | openshift-ingress/router-external-default | 66f3816acf1b431691b8d132cc9d793c | 172.30.235.33 | ACTIVE | octavia | ----- - -.. Verify that the addresses you retrieved in the previous steps are associated with each other in the floating IP list: -+ -[source,terminal] ----- -$ openstack floating ip list | grep 172.30.235.33 ----- -+ -.Example output -[source,terminal] ----- -| e2f80e97-8266-4b69-8636-e58bacf1879e | 10.46.22.161 | 172.30.235.33 | 655e7122-806a-4e0a-a104-220c6e17bda6 | a565e55a-99e7-4d15-b4df-f9d7ee8c9deb | 66f3816acf1b431691b8d132cc9d793c | ----- - -You can now use the value of `EXTERNAL-IP` as the new Ingress address. - - -[NOTE] -==== -If Kuryr uses the Octavia Amphora driver, all traffic is routed through a single Amphora virtual machine (VM). - -You can repeat this procedure to create additional load balancers, which can alleviate the bottleneck. -==== diff --git a/modules/installation-osp-kuryr-known-limitations.adoc b/modules/installation-osp-kuryr-known-limitations.adoc deleted file mode 100644 index 5fe9a63019fd..000000000000 --- a/modules/installation-osp-kuryr-known-limitations.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-kuryr-known-limitations_{context}"] -= Known limitations of installing with Kuryr - -Using {product-title} with Kuryr SDN has several known limitations. - -[discrete] -[id="openstack-general-limitations_{context}"] -== {rh-openstack} general limitations - -Using {product-title} with Kuryr SDN has several limitations that apply to all versions and environments: - -* `Service` objects with the `NodePort` type are not supported. - -* Clusters that use the OVN Octavia provider driver support `Service` objects for which the `.spec.selector` property is unspecified only if the `.subsets.addresses` property of the `Endpoints` object includes the subnet of the nodes or pods. - -* If the subnet on which machines are created is not connected to a router, or if the subnet is connected, but the router has no external gateway set, Kuryr cannot create floating IPs for `Service` objects with type `LoadBalancer`. - -[discrete] -[id="openstack-version-limitations_{context}"] -== {rh-openstack} version limitations - -Using {product-title} with Kuryr SDN has several limitations that depend on the {rh-openstack} version. - -* {rh-openstack} versions before 16 use -the default Octavia load balancer driver (Amphora). This driver requires that one -Amphora load balancer VM is deployed per {product-title} service. Creating too many -services can cause you to run out of resources. -+ -Deployments of later versions of {rh-openstack} that have the OVN Octavia driver disabled also -use the Amphora driver. They are subject to the same resource concerns as earlier versions of {rh-openstack}. - -* Octavia {rh-openstack} versions before 16 do not support UDP listeners. Therefore, -{product-title} UDP services are not supported. - -* Octavia {rh-openstack} versions before 16 cannot listen to multiple protocols on the -same port. Services that expose the same port to different protocols, like TCP -and UDP, are not supported. - -[discrete] -[id="openstack-go-limitations_{context}"] -== {rh-openstack} environment limitations - -There are limitations when using Kuryr SDN that depend on your deployment environment. - -Because of Octavia's lack of support for the UDP protocol and multiple listeners, if the {rh-openstack} version is earlier than 16, Kuryr forces pods to use TCP for DNS resolution. - -In Go versions 1.12 and earlier, applications that are compiled with CGO support disabled use UDP only. In this case, -the native Go resolver does not recognize the `use-vc` option in `resolv.conf`, which controls whether TCP is forced for DNS resolution. -As a result, UDP is still used for DNS resolution, which fails. - -To ensure that TCP forcing is allowed, compile applications either with the environment variable `CGO_ENABLED` set to `1`, i.e. `CGO_ENABLED=1`, or ensure that the variable is absent. - -In Go versions 1.13 and later, TCP is used automatically if DNS resolution using UDP fails. - -[NOTE] -==== -musl-based containers, including Alpine-based containers, do not support the `use-vc` option. -==== - -[discrete] -[id="openstack-upgrade-limitations_{context}"] -== {rh-openstack} upgrade limitations - -As a result of the {rh-openstack} upgrade process, the Octavia API might be changed, and upgrades to the Amphora images that are used for load balancers might be required. - -You can address API changes on an individual basis. - -If the Amphora image is upgraded, the {rh-openstack} operator can handle existing load balancer VMs in two ways: - -* Upgrade each VM by triggering a triggering a link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.0/html/networking_guide/sec-octavia#update-running-amphora-instances[load balancer failover]. - -* Leave responsibility for upgrading the VMs to users. - -If the operator takes the first option, there might be short downtimes during failovers. - -If the operator takes the second option, the existing load balancers will not support upgraded Octavia -API features, like UDP listeners. In this case, users must recreate their Services to use these features. - -[IMPORTANT] -==== -If {product-title} detects a new Octavia version that supports UDP load balancing, it recreates the DNS service automatically. The service recreation ensures that the service default supports UDP load balancing. - -The recreation causes the DNS service approximately one minute of downtime. -==== diff --git a/modules/installation-osp-kuryr-neutron-configuration.adoc b/modules/installation-osp-kuryr-neutron-configuration.adoc deleted file mode 100644 index 4341f276ffd7..000000000000 --- a/modules/installation-osp-kuryr-neutron-configuration.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-kuryr-neutron-configuration_{context}"] -= Configuring Neutron - -Kuryr CNI leverages the Neutron Trunks extension to plug containers into the -{rh-openstack-first} SDN, so you must use the `trunks` extension for Kuryr to properly work. - -In addition, if you leverage the default ML2/OVS Neutron driver, the firewall -must be set to `openvswitch` instead of `ovs_hybrid` so that security groups are -enforced on trunk subports and Kuryr can properly handle network policies. diff --git a/modules/installation-osp-kuryr-octavia-configuration.adoc b/modules/installation-osp-kuryr-octavia-configuration.adoc deleted file mode 100644 index 523dad46cd46..000000000000 --- a/modules/installation-osp-kuryr-octavia-configuration.adoc +++ /dev/null @@ -1,269 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc - -[id="installation-osp-kuryr-octavia-configuration_{context}"] -= Configuring Octavia - -Kuryr SDN uses {rh-openstack-first}'s Octavia LBaaS to implement {product-title} services. Thus, -you must install and configure Octavia components in {rh-openstack} -to use Kuryr SDN. - -To enable Octavia, you must include the Octavia service during the installation -of the {rh-openstack} Overcloud, or upgrade the Octavia service if the Overcloud -already exists. The following steps for enabling Octavia apply to both a clean -install of the Overcloud or an Overcloud update. - -[NOTE] -==== -The following steps only capture the key pieces required during the -https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/13/html/director_installation_and_usage/[deployment of {rh-openstack}] -when dealing with Octavia. It is also important to note that -https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/13/html/director_installation_and_usage/configuring-a-container-image-source#registry-methods[registry methods] -vary. - -This example uses the local registry method. -==== - -.Procedure - -. If you are using the local registry, create a template to upload the images to -the registry. For example: -+ -[source,terminal] ----- -(undercloud) $ openstack overcloud container image prepare \ --e /usr/share/openstack-tripleo-heat-templates/environments/services-docker/octavia.yaml \ ---namespace=registry.access.redhat.com/rhosp13 \ ---push-destination=<local-ip-from-undercloud.conf>:8787 \ ---prefix=openstack- \ ---tag-from-label {version}-{release} \ ---output-env-file=/home/stack/templates/overcloud_images.yaml \ ---output-images-file /home/stack/local_registry_images.yaml ----- - -. Verify that the `local_registry_images.yaml` file contains the Octavia images. -For example: -+ -[source,yaml] ----- -... -- imagename: registry.access.redhat.com/rhosp13/openstack-octavia-api:13.0-43 - push_destination: <local-ip-from-undercloud.conf>:8787 -- imagename: registry.access.redhat.com/rhosp13/openstack-octavia-health-manager:13.0-45 - push_destination: <local-ip-from-undercloud.conf>:8787 -- imagename: registry.access.redhat.com/rhosp13/openstack-octavia-housekeeping:13.0-45 - push_destination: <local-ip-from-undercloud.conf>:8787 -- imagename: registry.access.redhat.com/rhosp13/openstack-octavia-worker:13.0-44 - push_destination: <local-ip-from-undercloud.conf>:8787 ----- -+ -[NOTE] -==== -The Octavia container versions vary depending upon the specific -{rh-openstack} release installed. -==== - -. Pull the container images from `registry.redhat.io` to the Undercloud node: -+ -[source,terminal] ----- -(undercloud) $ sudo openstack overcloud container image upload \ - --config-file /home/stack/local_registry_images.yaml \ - --verbose ----- -+ -This may take some time depending on the speed of your network and Undercloud -disk. - -. Since an Octavia load balancer is used to access the {product-title} API, you must -increase their listeners' default timeouts for the connections. The default -timeout is 50 seconds. Increase the timeout to 20 minutes by passing the -following file to the Overcloud deploy command: -+ -[source,terminal] ----- -(undercloud) $ cat octavia_timeouts.yaml -parameter_defaults: - OctaviaTimeoutClientData: 1200000 - OctaviaTimeoutMemberData: 1200000 ----- -+ -[NOTE] -==== -This is not needed for {rh-openstack} 14+. -==== - -. Install or update your Overcloud environment with Octavia: -+ -[source,terminal] ----- -$ openstack overcloud deploy --templates \ - -e /usr/share/openstack-tripleo-heat-templates/environments/services-docker/octavia.yaml \ - -e octavia_timeouts.yaml ----- -+ -[NOTE] -==== -This command only includes the files associated with Octavia; it varies based on -your specific installation of {rh-openstack}. See the {rh-openstack} -documentation for further information. For more information on customizing your -Octavia installation, see -https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/13/html-single/networking_guide/#planning_your_octavia_deployment[installation -of Octavia using Director]. -==== -+ -[NOTE] -==== -When leveraging Kuryr SDN, the Overcloud installation requires the Neutron `trunk` extension. This is available by default on director deployments. -Use the `openvswitch` firewall instead of the default `ovs-hybrid` when the Neutron -backend is ML2/OVS. There is no need for modifications if the backend is -ML2/OVN. -==== - -. In {rh-openstack} versions 13 and 15, add the project ID -to the `octavia.conf` configuration file after you create the project. -* To enforce -network policies across services, like when traffic goes through -the Octavia load balancer, you must ensure Octavia creates the Amphora VM -security groups on the user project. -+ -This change ensures that required load balancer security groups belong to that project, -and that they can be updated to enforce services isolation. -+ -[NOTE] -==== -This task is unnecessary in {rh-openstack} version 16 or later. - -Octavia implements a new ACL API that restricts access to the load -balancers VIP. -==== - -.. Get the project ID -+ -[source,terminal] ----- -$ openstack project show <project> ----- -+ -.Example output -[source,terminal] ----- -+-------------+----------------------------------+ -| Field | Value | -+-------------+----------------------------------+ -| description | | -| domain_id | default | -| enabled | True | -| id | PROJECT_ID | -| is_domain | False | -| name | *<project>* | -| parent_id | default | -| tags | [] | -+-------------+----------------------------------+ ----- - -.. Add the project ID to `octavia.conf` for the controllers. - -... Source the `stackrc` file: -+ -[source,terminal] ----- -$ source stackrc # Undercloud credentials ----- - -... List the Overcloud controllers: -+ -[source,terminal] ----- -$ openstack server list ----- -+ -.Example output -[source,terminal] ----- -+--------------------------------------+--------------+--------+-----------------------+----------------+------------+ -│ -| ID | Name | Status | Networks -| Image | Flavor | -│ -+--------------------------------------+--------------+--------+-----------------------+----------------+------------+ -│ -| 6bef8e73-2ba5-4860-a0b1-3937f8ca7e01 | controller-0 | ACTIVE | -ctlplane=192.168.24.8 | overcloud-full | controller | -│ -| dda3173a-ab26-47f8-a2dc-8473b4a67ab9 | compute-0 | ACTIVE | -ctlplane=192.168.24.6 | overcloud-full | compute | -│ -+--------------------------------------+--------------+--------+-----------------------+----------------+------------+ ----- - -... SSH into the controller(s). -+ -[source,terminal] ----- -$ ssh heat-admin@192.168.24.8 ----- - -... Edit the `octavia.conf` file to add the project into the list of projects where -Amphora security groups are on the user's account. -+ ----- -# List of project IDs that are allowed to have Load balancer security groups -# belonging to them. -amp_secgroup_allowed_projects = PROJECT_ID ----- - -.. Restart the Octavia worker so the new configuration loads. -+ -[source,terminal] ----- -controller-0$ sudo docker restart octavia_worker ----- - -[NOTE] -==== -Depending on your {rh-openstack} environment, Octavia might not support UDP -listeners. If you use Kuryr SDN on {rh-openstack} version 15 or earlier, UDP services are not supported. -{rh-openstack} version 16 or later support UDP. -==== - -[id="installation-osp-kuryr-octavia-driver_{context}"] -== The Octavia OVN Driver - -Octavia supports multiple provider drivers through the Octavia API. - -To see all available Octavia provider drivers, on a command line, enter: -[source,terminal] ----- -$ openstack loadbalancer provider list ----- - -.Example output -[source,terminal] ----- -+---------+-------------------------------------------------+ -| name    | description                                     | -+---------+-------------------------------------------------+ -| amphora | The Octavia Amphora driver.                     | -| octavia | Deprecated alias of the Octavia Amphora driver. | -| ovn     | Octavia OVN driver.                             | -+---------+-------------------------------------------------+ ----- - -Beginning with {rh-openstack} version 16, the Octavia OVN provider driver (`ovn`) is supported on -{product-title} on {rh-openstack} deployments. - -`ovn` is an integration driver for the load balancing -that Octavia and OVN provide. It supports basic load balancing capabilities, -and is based on OpenFlow rules. The driver is automatically enabled -in Octavia by Director on deployments that use OVN Neutron ML2. - -The Amphora provider driver is the default driver. If `ovn` is enabled, however, Kuryr uses it. - -If Kuryr uses `ovn` instead of Amphora, it offers the following benefits: - -* Decreased resource requirements. Kuryr does not require a load balancer VM for each service. -* Reduced network latency. -* Increased service creation speed by using OpenFlow rules instead of a VM for each service. -* Distributed load balancing actions across all nodes instead of centralized on Amphora VMs. diff --git a/modules/installation-osp-kuryr-octavia-upgrade.adoc b/modules/installation-osp-kuryr-octavia-upgrade.adoc deleted file mode 100644 index b3fefd8483d9..000000000000 --- a/modules/installation-osp-kuryr-octavia-upgrade.adoc +++ /dev/null @@ -1,107 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/load-balancing-openstack.adoc - -[id="installation-osp-kuryr-octavia-configure_{context}"] -= Using the Octavia OVN load balancer provider driver with Kuryr SDN - -If your {product-title} cluster uses Kuryr and was installed on a {rh-openstack-first} 13 cloud -that was later upgraded to {rh-openstack} 16, you can configure it to use the Octavia OVN provider driver. - -[IMPORTANT] -==== -Kuryr replaces existing load balancers after you change provider drivers. This process -results in some downtime. -==== - -.Prerequisites - -* Install the {rh-openstack} CLI, `openstack`. - -* Install the {product-title} CLI, `oc`. - -* Verify that the Octavia OVN driver on {rh-openstack} is enabled. -+ -[TIP] -==== -To view a list of available Octavia drivers, on a command line, enter `openstack loadbalancer provider list`. - -The `ovn` driver is displayed in the command's output. -==== - -.Procedure - -To change from the Octavia Amphora provider driver to Octavia OVN: - -. Open the `kuryr-config` ConfigMap. On a command line, enter: -+ -[source,terminal] ----- -$ oc -n openshift-kuryr edit cm kuryr-config ----- - -. In the ConfigMap, delete the line that contains `kuryr-octavia-provider: default`. For example: -+ -[source,yaml] ----- -... -kind: ConfigMap -metadata: - annotations: - networkoperator.openshift.io/kuryr-octavia-provider: default <1> -... ----- -<1> Delete this line. The cluster will regenerate it with `ovn` as the value. -+ -Wait for the Cluster Network Operator to detect the modification and to redeploy the `kuryr-controller` and `kuryr-cni` pods. This process might take several minutes. - -. Verify that the `kuryr-config` ConfigMap annotation is present with `ovn` as its value. On a command line, enter: -+ -[source,terminal] ----- -$ oc -n openshift-kuryr edit cm kuryr-config ----- -+ -The `ovn` provider value is displayed in the output: -+ -[source,yaml] ----- -... -kind: ConfigMap -metadata: - annotations: - networkoperator.openshift.io/kuryr-octavia-provider: ovn -... ----- - -. Verify that {rh-openstack} recreated its load balancers. - -.. On a command line, enter: -+ -[source,terminal] ----- -$ openstack loadbalancer list | grep amphora ----- -+ -A single Amphora load balancer is displayed. For example: -+ -[source,terminal] ----- -a4db683b-2b7b-4988-a582-c39daaad7981 | ostest-7mbj6-kuryr-api-loadbalancer | 84c99c906edd475ba19478a9a6690efd | 172.30.0.1 | ACTIVE | amphora ----- - -.. Search for `ovn` load balancers by entering: -+ -[source,terminal] ----- -$ openstack loadbalancer list | grep ovn ----- -+ -The remaining load balancers of the `ovn` type are displayed. For example: -+ -[source,terminal] ----- -2dffe783-98ae-4048-98d0-32aa684664cc | openshift-apiserver-operator/metrics | 84c99c906edd475ba19478a9a6690efd | 172.30.167.119 | ACTIVE | ovn -0b1b2193-251f-4243-af39-2f99b29d18c5 | openshift-etcd/etcd | 84c99c906edd475ba19478a9a6690efd | 172.30.143.226 | ACTIVE | ovn -f05b07fc-01b7-4673-bd4d-adaa4391458e | openshift-dns-operator/metrics | 84c99c906edd475ba19478a9a6690efd | 172.30.152.27 | ACTIVE | ovn ----- diff --git a/modules/installation-osp-modifying-networktype.adoc b/modules/installation-osp-modifying-networktype.adoc deleted file mode 100644 index 3eb1118b1f67..000000000000 --- a/modules/installation-osp-modifying-networktype.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// * installing/installing_openstack/installing-openstack-installer-user-kuryr.adoc -// -//YOU MUST SET AN IFEVAL FOR EACH NEW MODULE - -[id="installation-osp-modifying-networktype_{context}"] -= Modifying the network type - -By default, the installation program selects the `OpenShiftSDN` network type. To use Kuryr instead, change the value in the installation configuration file that the program generated. - -.Prerequisites - -* You have the file `install-config.yaml` that was generated by the {product-title} installation program - -.Procedure - -. In a command prompt, browse to the directory that contains `install-config.yaml`. - -. From that directory, either run a script to edit the `install-config.yaml` file or update the file manually: - -** To set the value by using a script, run: -+ -[source,terminal] ----- -$ python -c ' -import yaml; -path = "install-config.yaml"; -data = yaml.safe_load(open(path)); -data["networking"]["networkType"] = "Kuryr"; -open(path, "w").write(yaml.dump(data, default_flow_style=False))' ----- - -** To set the value manually, open the file and set `networking.networkType` to `"Kuryr"`. diff --git a/modules/installation-osp-restricted-config-yaml.adoc b/modules/installation-osp-restricted-config-yaml.adoc deleted file mode 100644 index 56d65bef7d6c..000000000000 --- a/modules/installation-osp-restricted-config-yaml.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer-restricted.adoc - -[id="installation-osp-restricted-config-yaml_{context}"] -= Sample customized `install-config.yaml` file for restricted OpenStack installations - -This sample `install-config.yaml` demonstrates all of the possible {rh-openstack-first} -customization options. - -[IMPORTANT] -==== -This sample file is provided for reference only. You must obtain your -`install-config.yaml` file by using the installation program. -==== - -[source, yaml] ----- -apiVersion: v1 -baseDomain: example.com -controlPlane: - name: master - platform: {} - replicas: 3 -compute: -- name: worker - platform: - openstack: - type: ml.large - replicas: 3 -metadata: - name: example -networking: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineCIDR: 10.0.0.0/16 - serviceNetwork: - - 172.30.0.0/16 -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] -platform: - openstack: - region: region1 - cloud: mycloud - externalNetwork: external - computeFlavor: m1.xlarge - lbFloatingIP: 128.0.0.1 -ifndef::openshift-origin[] -fips: false -endif::openshift-origin[] -pullSecret: '{"auths": ...}' -sshKey: ssh-ed25519 AAAA... -additionalTrustBundle: | - - -----BEGIN CERTIFICATE----- - - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - - -----END CERTIFICATE----- - -imageContentSources: -- mirrors: - - <mirror_registry>/<repo_name>/release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <mirror_registry>/<repo_name>/release - source: registry.svc.ci.openshift.org/ocp/release ----- diff --git a/modules/installation-osp-verifying-cluster-status.adoc b/modules/installation-osp-verifying-cluster-status.adoc deleted file mode 100644 index 5435325e19dc..000000000000 --- a/modules/installation-osp-verifying-cluster-status.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-installer-restricted.adoc -// * installing/installing_rhv/installing-rhv-default.adoc -// * installing/installing_rhv/installing-rhv-customizations.adoc -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -ifeval::["{context}" == "installing-rhv-user-infra"] -:rhv-user-infra: -endif::[] - -[id="installation-osp-verifying-cluster-status_{context}"] -= Verifying cluster status - -You can verify your {product-title} cluster's status during or after installation. - -.Procedure - -. In the cluster environment, export the administrator's kubeconfig file: -+ -ifdef::rhv-user-infra[] -[source,terminal] ----- -$ export KUBECONFIG=$ASSETS_DIR/auth/kubeconfig ----- -endif::rhv-user-infra[] -ifndef::rhv-user-infra[] -[source,terminal] ----- -$ export KUBECONFIG=<installation_directory>/auth/kubeconfig <1> ----- -<1> For `<installation_directory>`, specify the path to the directory that you stored the installation files in. -endif::rhv-user-infra[] -+ -The `kubeconfig` file contains information about the cluster that is used by the CLI to connect a client to the correct cluster and API server. - -. View the control plane and compute machines created after a deployment: -+ -[source,terminal] ----- -$ oc get nodes ----- - -. View your cluster's version: -+ -[source,terminal] ----- -$ oc get clusterversion ----- - -. View your Operators' status: -+ -[source,terminal] ----- -$ oc get clusteroperator ----- - -. View all running pods in the cluster: -+ -[source,terminal] ----- -$ oc get pods -A ----- - -ifeval::["{context}" == "installing-rhv-customizations"] -:!rhv-user-infra: -endif::[] diff --git a/modules/installation-osp-verifying-external-network.adoc b/modules/installation-osp-verifying-external-network.adoc deleted file mode 100644 index 96d5a584e4f9..000000000000 --- a/modules/installation-osp-verifying-external-network.adoc +++ /dev/null @@ -1,105 +0,0 @@ -//Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-user.adoc -// -// DNS resolution KI -ifeval::["{context}" == "installing-openstack-installer-custom"] -:osp-custom: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:osp-kuryr: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:osp-user: -endif::[] - -[id="installation-osp-verifying-external-network_{context}"] -= Verifying external network access - -The {product-title} installation process requires external network access. You must provide an external network value to it, or deployment fails. Before you begin the process, verify that a network with the external router type exists in {rh-openstack-first}. - -.Prerequisites - -* On {rh-openstack}, the `NeutronDhcpAgentDnsmasqDnsServers` parameter must be configured to allow DHCP agents to forward instances' DNS queries. One way to set this parameter is to: -.. link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/13/html/advanced_overcloud_customization/sect-understanding_heat_templates#sect-Environment_Files[Create a new environment file] in the template directory. -.. Provide link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/13/html-single/overcloud_parameters/index#networking-neutron-parameters[parameter values] in the file. For example: -+ -.Sample `neutron-dhcp-agent-dnsmasq-dns-servers.yaml` file - -[source,yaml] ----- -parameter_defaults: - NeutronDhcpAgentDnsmasqDnsServers: ['<DNS_server_address_1>','<DNS_server_address_2'] ----- -.. link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/13/html/advanced_overcloud_customization/sect-understanding_heat_templates#sect-Including_Environment_Files_in_Overcloud_Creation[Include the environment file] in your Overcloud deploy command. For example: -+ -[source,terminal] ----- -$ openstack overcloud deploy --templates -e neutron-dhcp-agent-dnsmasq-dns-servers.yaml ... ----- - -.Procedure - -. Using the {rh-openstack} CLI, verify the name and ID of the 'External' network: -+ -[source,terminal] ----- -$ openstack network list --long -c ID -c Name -c "Router Type" ----- -+ -.Example output -[source,terminal] ----- -+--------------------------------------+----------------+-------------+ -| ID | Name | Router Type | -+--------------------------------------+----------------+-------------+ -| 148a8023-62a7-4672-b018-003462f8d7dc | public_network | External | -+--------------------------------------+----------------+-------------+ ----- - -A network with an external router type appears in the network list. If at least one does not, see link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.0/html/director_installation_and_usage/performing-overcloud-post-installation-tasks#creating-a-default-floating-ip-network[Creating a default floating IP network] and link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.0/html/director_installation_and_usage/performing-overcloud-post-installation-tasks#creating-a-default-provider-network[Creating a default provider network]. - -ifdef::osp-custom,osp-kuryr[] -[IMPORTANT] -==== -If the external network's CIDR range overlaps one of the default network ranges, you must change the matching network ranges in the `install-config.yaml` file before you start the installation process. - -The default network ranges are: -[options="header"] -|==== -|Network |Range - -|`machineNetwork` -|10.0.0.0/16 - -|`serviceNetwork` -|172.30.0.0/16 - -|`clusterNetwork` -|10.128.0.0/14 -|==== -==== -endif::osp-custom,osp-kuryr[] - -ifdef::osp-custom,osp-kuryr[] -[WARNING] -If the installation program finds multiple networks with the same name, it sets one of them at random. To avoid this behavior, create unique names for resources in {rh-openstack}. -endif::osp-custom,osp-kuryr[] - -[NOTE] -==== -If the Neutron trunk service plug-in is enabled, a trunk port is created by default. For more information, see https://wiki.openstack.org/wiki/Neutron/TrunkPort[Neutron trunk port]. -==== - -ifeval::["{context}" == "installing-openstack-installer-custom"] -:!osp-custom: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:!osp-kuryr: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:!osp-user: -endif::[] diff --git a/modules/installation-osp-verifying-installation.adoc b/modules/installation-osp-verifying-installation.adoc deleted file mode 100644 index 2d5af4c609c7..000000000000 --- a/modules/installation-osp-verifying-installation.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/installing-openstack-user.adoc - -[id="installation-osp-verifying-installation_{context}"] -= Verifying a successful installation - -Verify that the {product-title} installation is complete. - -.Prerequisites - -* You have the installation program (`openshift-install`) - - -.Procedure - -* On a command line, enter: -+ -[source,terminal] ----- -$ openshift-install --log-level debug wait-for install-complete ----- - -The program outputs the console URL, as well as the administrator's login information. diff --git a/modules/installation-overview.adoc b/modules/installation-overview.adoc deleted file mode 100644 index 292786563d10..000000000000 --- a/modules/installation-overview.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/index.adoc -// * architecture/architecture-installation.adoc - -[id="installation-overview_{context}"] -= {product-title} installation overview - -The {product-title} installation program offers you flexibility. You can use the installation program to deploy a cluster on infrastructure that the installation program provisions and the cluster maintains or deploy a cluster on infrastructure that you prepare and maintain. - -These two basic types of {product-title} clusters are frequently called installer-provisioned infrastructure clusters and user-provisioned infrastructure clusters. - -Both types of clusters have the following characteristics: - -* Highly available infrastructure with no single points of failure is available by default -* Administrators maintain control over what updates are applied and when - -You use the same installation program to deploy both types of clusters. The main assets generated by the installation program are the Ignition config files for the bootstrap, master, and worker machines. With these three configurations and correctly configured infrastructure, you can start an {product-title} cluster. - -The {product-title} installation program uses a set of targets and dependencies to manage cluster installation. The installation program has a set of targets that it must achieve, and each target has a set of dependencies. Because each target is only concerned with its own dependencies, the installation program can act to achieve multiple targets in parallel. The ultimate target is a running cluster. By meeting dependencies instead of running commands, the installation program is able to recognize and use existing components instead of running the commands to create them again. - -The following diagram shows a subset of the installation targets and dependencies: - -.{product-title} installation targets and dependencies -image::targets-and-dependencies.png[{product-title} installation targets and dependencies] - -After installation, each cluster machine uses {op-system-first} as the operating system. {op-system} is the immutable container host version of {op-system-base-full} and features a {op-system-base} kernel with SELinux enabled by default. It includes the `kubelet`, which is the Kubernetes node agent, and the CRI-O container runtime, which is optimized for Kubernetes. - -Every control plane machine in an {product-title} {product-version} cluster must use {op-system}, which includes a critical first-boot provisioning tool called Ignition. This tool enables the cluster to configure the machines. Operating system updates are delivered as an Atomic OSTree repository that is embedded in a container image that is rolled out across the cluster by an Operator. Actual operating system changes are made in-place on each machine as an atomic operation by using rpm-ostree. Together, these technologies enable {product-title} to manage the operating system like it manages any other application on the cluster, via in-place upgrades that keep the entire platform up-to-date. These in-place updates can reduce the burden on operations teams. - -If you use {op-system} as the operating system for all cluster machines, the cluster manages all aspects of its components and machines, including the operating system. Because of this, only the installation program and the Machine Config Operator can change machines. The installation program uses Ignition config files to set the exact state of each machine, and the Machine Config Operator completes more changes to the machines, such as the application of new certificates or keys, after installation. diff --git a/modules/installation-performing-disconnected-mirror-without-registry.adoc b/modules/installation-performing-disconnected-mirror-without-registry.adoc deleted file mode 100644 index 1b956603c07e..000000000000 --- a/modules/installation-performing-disconnected-mirror-without-registry.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc - -[id="installation-performing-disconnected-mirror-without-registry"] -= Performing a mirror to disk for use in disconnected environments with a non-production mirror registry - -If a production mirror registry is not available, you can configure a simple mirror registry by using the disconnected procedure to serve container images that you downloaded to disk. - -.Procedure - -. Determine the IP of your host within the restricted network as `<private_ip>`. - -. On a local host, copy the required `imageContentSources` and `ImageContentSourcePolicy`: -.. Make the mirror directory and change to it: -+ ----- -$ mkdir <mirror_dir> ; cd <mirror_dir> ----- - -.. Mirror the images: -+ ----- -$ oc adm release mirror <product_version> --to file://openshift/release ----- - -. From within the restricted network, start an image mirror server on port 5000 on all interfaces on the host: -.. Change to the mirror directory: -+ ----- -$ cd MIRROR_DIR ----- - -.. Serve the images for the installation program to use: -+ ----- -$ oc image serve ----- - -This registry does not perform authentication and does not require TLS to guarantee integrity of the provided images. diff --git a/modules/installation-performing-disconnected-mirror.adoc b/modules/installation-performing-disconnected-mirror.adoc deleted file mode 100644 index f87630457d58..000000000000 --- a/modules/installation-performing-disconnected-mirror.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_restricted_networks/installing-restricted-networks-preparations.adoc - -[id="installation-performing-disconnected-mirror"] -= Mirroring the {product-title} image registry contents to disk for use in disconnected environments - -When you mirror images to disk, you download images as files. Then, you move your -mirror host, which can be a laptop or a removable media device, like a -USB drive, into the restricted network and complete the mirror -procedure. - -.Procedure - -. On a local host, test the mirror process: -+ ----- -$ oc adm release mirror <product_version> --to <mirror_repository> --dry-run ----- - -. On a local host, copy the required `imageContentSources` and `ImageContentSourcePolicy`: -.. Make the mirror directory and change to it: -+ ----- -$ mkdir <mirror_dir> ; cd <mirror_dir> ----- - -.. Mirror the images: -+ ----- -$ oc adm release mirror <product_version> --to file://openshift/release ----- - -. From within the restricted network, mirror the images to your restricted mirror repository: -+ ----- -$ oc adm release mirror file://openshift/release:<product_version>* --to <mirror_repository> ----- diff --git a/modules/installation-preparing-restricted-cluster-to-gather-support-data.adoc b/modules/installation-preparing-restricted-cluster-to-gather-support-data.adoc deleted file mode 100644 index c0a47bc29edb..000000000000 --- a/modules/installation-preparing-restricted-cluster-to-gather-support-data.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-restricted-networks-preparations.adoc - -[id="installation-preparing-restricted-cluster-to-gather-support-data_{context}"] -= Preparing your cluster to gather support data - -Clusters using a restricted network must import the default must-gather image to gather debugging data for Red Hat support. The must-gather image is not imported by default, and clusters on a restricted network do not have access to the internet to pull the latest image from a remote repository. - -.Procedure - -* Import the default must-gather image from your installation payload: -+ -[source,terminal] ----- -$ oc import-image is/must-gather -n openshift ----- - -When running the `oc adm must-gather` command, use the `--image` flag and point to the payload image, as in the following example: -[source,terminal] ----- -$ oc adm must-gather --image=$(oc adm release info --image-for must-gather) ----- diff --git a/modules/installation-process.adoc b/modules/installation-process.adoc deleted file mode 100644 index ffaede947eba..000000000000 --- a/modules/installation-process.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/index.adoc -// * architecture/architecture-installation.adoc - -[id="installation-process_{context}"] -= Installation process - -When you install an {product-title} cluster, you download the installation program from -ifndef::openshift-origin[] -the appropriate link:https://cloud.redhat.com/openshift/install[Infrastructure Provider] page on the {cloud-redhat-com} site. This site manages: - -* REST API for accounts -* Registry tokens, which are the pull secrets that you use to obtain the required components -* Cluster registration, which associates the cluster identity to your Red Hat account to facilitate the gathering of usage metrics -endif::[] -ifdef::openshift-origin[] -https://github.com/openshift/okd/releases. -endif::[] - -In {product-title} {product-version}, the installation program is a Go binary file that performs a series of file transformations on a set of assets. The way you interact with the installation program differs depending on your installation type. - -* For clusters with installer-provisioned infrastructure, you delegate the infrastructure bootstrapping and provisioning to the installation program instead of doing it yourself. The installation program creates all of the networking, machines, and operating systems that are required to support the cluster. - -* If you provision and manage the infrastructure for your cluster, you must provide all of the cluster infrastructure and resources, including the bootstrap machine, networking, load balancing, storage, and individual cluster machines. - -You use three sets of files during installation: an installation configuration file that is named `install-config.yaml`, Kubernetes manifests, and Ignition config files for your machine types. - -[IMPORTANT] -==== -It is possible to modify Kubernetes and the Ignition config files that control the underlying {op-system} operating system during installation. However, no validation is available to confirm the suitability of any modifications that you make to these objects. If you modify these objects, you might render your cluster non-functional. Because of this risk, modifying Kubernetes and Ignition config files is not supported unless you are following documented procedures or are instructed to do so by Red Hat support. -==== - -The installation configuration file is transformed into Kubernetes manifests, and then the manifests are wrapped into Ignition config files. The installation program uses these Ignition config files to create the cluster. - -The installation configuration files are all pruned when you run the installation program, so be sure to back up all configuration files that you want to use again. - -[IMPORTANT] -==== -You cannot modify the parameters that you set during installation, but you can modify many cluster attributes after installation. -==== - -[discrete] -== The installation process with installer-provisioned infrastructure - -The default installation type uses installer-provisioned infrastructure. By default, the installation program acts as an installation wizard, prompting you for values that it cannot determine on its own and providing reasonable default values for the remaining parameters. You can also customize the installation process to support advanced infrastructure scenarios. The installation program provisions the underlying infrastructure for the cluster. - -You can install either a standard cluster or a customized cluster. With a standard cluster, you provide minimum details that are required to install the cluster. With a customized cluster, you can specify more details about the platform, such as the number of machines that the control plane uses, the type of virtual machine that the cluster deploys, or the CIDR range for the Kubernetes service network. - -If possible, use this feature to avoid having to provision and maintain the cluster infrastructure. In all other environments, you use the installation program to generate the assets that you require to provision your cluster infrastructure. - -With installer-provisioned infrastructure clusters, {product-title} manages all aspects of the cluster, including the operating system itself. Each machine boots with a configuration that references resources hosted in the cluster that it joins. This configuration allows the cluster to manage itself as updates are applied. - -[discrete] -== The installation process with user-provisioned infrastructure - -You can also install {product-title} on infrastructure that you provide. You use the installation program to generate the assets that you require to provision the cluster infrastructure, create the cluster infrastructure, and then deploy the cluster to the infrastructure that you provided. - -If you do not use infrastructure that the installation program provisioned, you must manage and maintain the cluster resources yourself, including: - -* The underlying infrastructure for the control plane and compute machines that make up the cluster -* Load balancers -* Cluster networking, including the DNS records and required subnets -* Storage for the cluster infrastructure and applications - -If your cluster uses user-provisioned infrastructure, you have the option of adding RHEL worker machines to your cluster. - -[discrete] -== Installation process details - -Because each machine in the cluster requires information about the cluster when it is provisioned, {product-title} uses a temporary _bootstrap_ machine during initial configuration to provide the required information to the permanent control plane. It boots by using an Ignition config file that describes how to create the cluster. The bootstrap machine creates the master machines that make up the control plane. The control plane machines then create the compute machines, which are also known as worker machines. The following figure illustrates this process: - -.Creating the bootstrap, master, and worker machines -image::create-nodes.png[Creating bootstrap, master, and worker machines] - -After the cluster machines initialize, the bootstrap machine is destroyed. All clusters use the bootstrap process to initialize the cluster, but if you provision the infrastructure for your cluster, you must complete many of the steps manually. - -[IMPORTANT] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== - -Bootstrapping a cluster involves the following steps: - -. The bootstrap machine boots and starts hosting the remote resources required for the master machines to boot. (Requires manual intervention if you provision the infrastructure) -. The master machines fetch the remote resources from the bootstrap machine and finish booting. (Requires manual intervention if you provision the infrastructure) -. The master machines use the bootstrap machine to form an etcd cluster. -. The bootstrap machine starts a temporary Kubernetes control plane using the new etcd cluster. -. The temporary control plane schedules the production control plane to the master machines. -. The temporary control plane shuts down and passes control to the production control plane. -. The bootstrap machine injects {product-title} components into the production control plane. -. The installation program shuts down the bootstrap machine. (Requires manual intervention if you provision the infrastructure) -. The control plane sets up the worker nodes. -. The control plane installs additional services in the form of a set of Operators. - -The result of this bootstrapping process is a fully running {product-title} cluster. The cluster then downloads and configures remaining components needed for the day-to-day operation, including the creation of worker machines in supported environments. diff --git a/modules/installation-registry-storage-block-recreate-rollout-bare-metal.adoc b/modules/installation-registry-storage-block-recreate-rollout-bare-metal.adoc deleted file mode 100644 index f683b72bdb44..000000000000 --- a/modules/installation-registry-storage-block-recreate-rollout-bare-metal.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_baremetal/installing-bare-metal-network-customizations.adoc -// * installing/installing_baremetal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc - -[id="installation-registry-storage-block-recreate-rollout-bare-metal_{context}"] -= Configuring block registry storage - -To allow the image registry to use block storage types during upgrades as a cluster administrator, you can use the `Recreate` rollout strategy. - -[IMPORTANT] -==== -Block storage volumes are supported but not recommended for use with the image -registry on production clusters. An installation where the registry is -configured on block storage is not highly available because the registry cannot -have more than one replica. -==== - -.Procedure - -. To set the image registry storage as a block storage type, patch the registry so that it uses the `Recreate` rollout strategy and runs with only one (`1`) replica: -+ -[source,terminal] ----- -$ oc patch config.imageregistry.operator.openshift.io/cluster --type=merge -p '{"spec":{"rolloutStrategy":"Recreate","replicas":1}}' ----- -+ -. Provision the PV for the block storage device, and create a PVC for that volume. The requested block volume uses the ReadWriteOnce (RWO) access mode. -+ -. Edit the registry configuration so that it references the correct PVC. diff --git a/modules/installation-registry-storage-block-recreate-rollout.adoc b/modules/installation-registry-storage-block-recreate-rollout.adoc deleted file mode 100644 index a40e3f8fd657..000000000000 --- a/modules/installation-registry-storage-block-recreate-rollout.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc - -[id="installation-registry-storage-block-recreate-rollout_{context}"] -= Configuring block registry storage for VMware vSphere - -To allow the image registry to use block storage types such as vSphere Virtual Machine Disk (VMDK) during upgrades as a cluster administrator, you can use the `Recreate` rollout strategy. - -[IMPORTANT] -==== -Block storage volumes are supported but not recommended for use with image -registry on production clusters. An installation where the registry is -configured on block storage is not highly available because the registry cannot -have more than one replica. -==== - -.Procedure - -. To set the image registry storage as a block storage type, patch the registry so that it uses the `Recreate` rollout strategy and runs with only `1` replica: -+ -[source,terminal] ----- -$ oc patch config.imageregistry.operator.openshift.io/cluster --type=merge -p '{"spec":{"rolloutStrategy":"Recreate","replicas":1}}' ----- -+ -. Provision the PV for the block storage device, and create a PVC for that volume. The requested block volume uses the ReadWriteOnce (RWO) access mode. -.. Create a `pvc.yaml` file with the following contents to define a VMware vSphere `PersistentVolumeClaim` object: -+ -[source,yaml] ----- -kind: PersistentVolumeClaim -apiVersion: v1 -metadata: - name: image-registry-storage <1> -spec: - accessModes: - - ReadWriteOnce <2> - resources: - requests: - storage: 100Gi <3> ----- -<1> A unique name that represents the `PersistentVolumeClaim` object. -<2> The access mode of the PersistentVolumeClaim. With `ReadWriteOnce`, the volume can be mounted with read and write permissions by a single node. -<3> The size of the PersistentVolumeClaim. - -.. Create the `PersistentVolumeClaim` object from the file: -+ -[source,terminal] ----- -$ oc create -f pvc.yaml -n openshift-image-registry ----- - -+ -. Edit the registry configuration so that it references the correct PVC: -+ -[source,terminal] ----- -$ oc edit config.imageregistry.operator.openshift.io -o yaml ----- -+ -.Example output -[source,yaml] ----- -storage: - pvc: - claim: <1> ----- -<1> Creating a custom PVC allows you to leave the `claim` field blank for the default automatic creation of an `image-registry-storage` PVC. diff --git a/modules/installation-registry-storage-config.adoc b/modules/installation-registry-storage-config.adoc deleted file mode 100644 index bd17ce54a446..000000000000 --- a/modules/installation-registry-storage-config.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc - -ifeval::["{context}" == "installing-aws-user-infra"] -:aws: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-aws"] -:aws: -endif::[] - -[id="installation-registry-storage-config_{context}"] -= Image registry storage configuration - -ifdef::aws[] -Amazon Web Services provides default storage, which means the Image Registry -Operator is available after installation. However, if the Registry Operator -cannot create an S3 bucket and automatically configure storage, you must -manually configure registry storage. -endif::aws[] -ifndef::aws[] -The Image Registry Operator is not initially available for platforms that do -not provide default storage. After installation, you must configure your -registry to use storage so that the Registry Operator is made available. -endif::aws[] - -Instructions are shown for configuring a persistent volume, which is required for production clusters. Where applicable, instructions are shown for configuring an empty directory as the storage location, which is available for only non-production clusters. - -Additional instructions are provided for allowing the image registry to use block storage types by using the `Recreate` rollout strategy during upgrades. - -ifeval::["{context}" == "installing-aws-user-infra"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-aws"] -:!aws: -endif::[] diff --git a/modules/installation-registry-storage-non-production.adoc b/modules/installation-registry-storage-non-production.adoc deleted file mode 100644 index 7904c48e6910..000000000000 --- a/modules/installation-registry-storage-non-production.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc - -[id="installation-registry-storage-non-production_{context}"] -= Configuring storage for the image registry in non-production clusters - -You must configure storage for the Image Registry Operator. For non-production -clusters, you can set the image registry to an empty directory. If you do so, -all images are lost if you restart the registry. - -.Procedure - -* To set the image registry storage to an empty directory: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io cluster --type merge --patch '{"spec":{"storage":{"emptyDir":{}}}}' ----- -+ -[WARNING] -==== -Configure this option for only non-production clusters. -==== -+ -If you run this command before the Image Registry Operator initializes its -components, the `oc patch` command fails with the following error: -+ -[source,terminal] ----- -Error from server (NotFound): configs.imageregistry.operator.openshift.io "cluster" not found ----- -+ -Wait a few minutes and run the command again. diff --git a/modules/installation-requirements-user-infra-ibm-z-kvm.adoc b/modules/installation-requirements-user-infra-ibm-z-kvm.adoc deleted file mode 100644 index 62add6fdb4fb..000000000000 --- a/modules/installation-requirements-user-infra-ibm-z-kvm.adoc +++ /dev/null @@ -1,187 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc - - -[id="installation-requirements-user-infra_{context}"] -= Machine requirements for a cluster with user-provisioned infrastructure - -For a cluster that contains user-provisioned infrastructure, you must deploy all -of the required machines. - -One or more KVM host machines based on {op-system-base} 8.3 or later. Each {op-system-base} KVM host machine must have libvirt installed and running. The virtual machines are provisioned under each {op-system-base} KVM host machine. - - -[id="machine-requirements_{context}"] -== Required machines - -The smallest {product-title} clusters require the following nodes: - -* One temporary bootstrap machine - -* Three control plane, or master, machines - -* At least two compute machines, which are also known as worker machines - -[NOTE] -==== -The cluster requires the bootstrap machine to deploy the {product-title} cluster -on the three control plane machines. You can remove the bootstrap machine after -you install the cluster. -==== - -[IMPORTANT] -==== -To improve high availability of your cluster, distribute the control plane machines over different {op-system-base} instances on at least two physical machines. -==== - -The bootstrap, control plane, and compute machines must use {op-system-first} as the operating system. - -See link:https://access.redhat.com/articles/rhel-limits[Red Hat Enterprise Linux technology capabilities and limits]. - -[id="network-connectivity_{context}"] -== Network connectivity requirements - -The {product-title} installer creates the Ignition files, which are necessary for all the {op-system-first} virtual machines. The automated installation of {product-title} is performed by the bootstrap machine. It starts the installation of {product-title} on each node, starts the Kubernetes cluster, and then finishes. During this bootstrap, the virtual machine must have an established network connection either through a Dynamic Host Configuration Protocol (DHCP) server or static IP address. - -[id="ibm-z-network-connectivity_{context}"] -== IBM Z network connectivity requirements - -To install on IBM Z under {op-system-base} KVM, you need: - -* A {op-system-base} KVM host configured with an OSA or RoCE network adapter. -* Either a {op-system-base} KVM host that is configured to use bridged networking in libvirt or MacVTap to connect the network to the guests. -+ -See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/configuring_and_managing_virtualization/index#types-of-virtual-machine-network-connections_configuring-virtual-machine-network-connections[Types of virtual network connections]. - -[id="host-machine-resource-requirements_{context}"] -== Host machine resource requirements -The {op-system-base} KVM host in your environment must meet the following requirements to host the virtual machines that you plan for the {product-title} environment. See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_virtualization/getting-started-with-virtualization-in-rhel-8_configuring-and-managing-virtualization[Getting started with virtualization]. - -You can install {product-title} version {product-version} on the following IBM hardware: - -* IBM z15 (all models), IBM z14 (all models), IBM z13, and IBM z13s -* LinuxONE, any version - -[id="minimum-ibm-z-system-requirements_{context}"] -== Minimum IBM Z system environment - -[discrete] -=== Hardware requirements - -* 1 LPAR with 6 IFLs that supports SMT2 -* 1 OSA or RoCE network adapter - -[discrete] -=== Operating system requirements -* One LPAR running {op-system-base} 8.3 or later with KVM, which is managed via libvirt - -On your {op-system-base} KVM host, set up: - -* 3 guest virtual machines for {product-title} control plane machines -* 2 guest virtual machines for {product-title} compute machines -* 1 guest virtual machine for the temporary {product-title} bootstrap machine - -[id="minimum-resource-requirements_{context}"] -== Minimum resource requirements - -Each cluster virtual machine must meet the following minimum requirements: - -[cols="2,2,2,2,2",options="header"] -|=== - -|Virtual Machine -|Operating System -|vCPU ^[1]^ -|Virtual RAM -|Storage - -|Bootstrap -|{op-system} -|4 -|16 GB -|120 GB - -|Control plane -|{op-system} -|4 -|16 GB -|120 GB - -|Compute -|{op-system} -|2 -|8 GB -|120 GB - -|=== --- -^[1]^ 1 physical core (IFL) provides 2 logical cores (threads) when SMT-2 is enabled. The hypervisor can provide 2 or more vCPUs. --- - -[id="preferred-ibm-z-system-requirements_{context}"] -== Preferred IBM Z system environment - -[discrete] -=== Hardware requirements - -* 3 LPARs with 6 IFLs each that support SMT2 -* 1 or 2 OSA or RoCE network adapters, or both - -[discrete] -=== Operating system requirements - -* For high availability, 2 or 3 LPARs running {op-system-base} 8.3 or later with KVM, which are managed via libvirt. - -On your {op-system-base} KVM host, set up: - -* 3 guest virtual machines for {product-title} control plane machines, distributed across the {op-system-base} KVM host machines -* At least 6 guest virtual machines for {product-title} compute machines, distributed across the {op-system-base} KVM host machines -* 1 guest virtual machine for the temporary {product-title} bootstrap machine - -[id="preferred-resource-requirements_{context}"] -== Preferred resource requirements - -The preferred requirements for each cluster virtual machine are: - -[cols="2,2,2,2,2",options="header"] -|=== - -|Virtual Machine -|Operating System -|vCPU -|Virtual RAM -|Storage - -|Bootstrap -|{op-system} -|4 -|16 GB -|120 GB - -|Control plane -|{op-system} -|8 -|16 GB -|120 GB - -|Compute -|{op-system} -|6 -|8 GB -|120 GB - -|=== - -[id="csr_management_{context}"] -== Certificate signing requests management - -Because your cluster has limited access to automatic machine management when you -use infrastructure that you provision, you must provide a mechanism for approving -cluster certificate signing requests (CSRs) after installation. The -`kube-controller-manager` only approves the kubelet client CSRs. The -`machine-approver` cannot guarantee the validity of a serving certificate -that is requested by using kubelet credentials because it cannot confirm that -the correct machine issued the request. You must determine and implement a -method of verifying the validity of the kubelet serving certificate requests -and approving them. diff --git a/modules/installation-requirements-user-infra.adoc b/modules/installation-requirements-user-infra.adoc deleted file mode 100644 index c9245ad8c50f..000000000000 --- a/modules/installation-requirements-user-infra.adoc +++ /dev/null @@ -1,370 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_ibm_power/installing-ibm-power.adoc -// * installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing_ibm_z/installing-restricted-networks-ibm-z.adoc - -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-bare-metal"] -:bare-metal: -endif::[] -ifeval::["{context}" == "installing-bare-metal-network-customizations"] -:bare-metal: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:bare-metal: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vsphere-network-customizations"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:vsphere: -endif::[] - -[id="installation-requirements-user-infra_{context}"] -= Machine requirements for a cluster with user-provisioned infrastructure - -For a cluster that contains user-provisioned infrastructure, you must deploy all -of the required machines. - -[id="machine-requirements_{context}"] -== Required machines - -The smallest {product-title} clusters require the following hosts: - -* One temporary bootstrap machine - -* Three control plane, or master, machines - -* At least two compute machines, which are also known as worker machines. -ifdef::bare-metal[] -If you are running a three-node cluster, running zero compute machines is supported. Running one compute machine is not supported. -endif::bare-metal[] - -[NOTE] -==== -The cluster requires the bootstrap machine to deploy the {product-title} cluster -on the three control plane machines. You can remove the bootstrap machine after -you install the cluster. -==== - -[IMPORTANT] -==== -ifdef::ibm-z[] -To improve high availability of your cluster, distribute the control plane machines over different z/VM instances on at least two physical machines. -endif::ibm-z[] -ifndef::ibm-z[] -To maintain high availability of your cluster, use separate physical hosts for -these cluster machines. -endif::ibm-z[] -==== - -The bootstrap and control plane machines must use {op-system-first} as the operating system. - -ifndef::openshift-origin[] -Note that {op-system} is based on {op-system-base-full} 8 and inherits all of its hardware certifications and requirements. -endif::[] -See link:https://access.redhat.com/articles/rhel-limits[Red Hat Enterprise Linux technology capabilities and limits]. - -ifdef::vsphere[] -[IMPORTANT] -==== -All virtual machines must reside in the same datastore and in the same folder as the installer. -==== -endif::vsphere[] - - -[id="network-connectivity_{context}"] -== Network connectivity requirements - -All the {op-system-first} machines require network in `initramfs` during boot to fetch Ignition config files from the Machine Config Server. -ifdef::ibm-z[] -The machines are configured with static IP addresses. No DHCP server is required. -endif::ibm-z[] -ifndef::ibm-z[] -During the initial boot, the machines require either a DHCP server -or that static IP addresses be set to establish a network -connection to download their Ignition config files. -endif::ibm-z[] - -ifdef::ibm-z[] -[id="ibm-z-network-connectivity_{context}"] -== IBM Z network connectivity requirements - -To install on IBM Z under z/VM, you require a single z/VM virtual NIC in layer 2 mode. You also need: - -* A direct-attached OSA or RoCE network adapter -* A z/VM VSwitch set up. For a preferred setup, use OSA link aggregation. -endif::ibm-z[] - -[id="minimum-resource-requirements_{context}"] -== Minimum resource requirements - -Each cluster machine must meet the following minimum requirements: - -[cols="2,2,2,2,2",options="header"] -|=== - -|Machine -|Operating System -|vCPU ^[1]^ -|Virtual RAM -|Storage - -|Bootstrap -|{op-system} -ifdef::ibm-power[|2] -ifndef::ibm-power[|4] -|16 GB -|120 GB - -|Control plane -|{op-system} -ifdef::ibm-power[|2] -ifndef::ibm-power[|4] -|16 GB -|120 GB - -ifndef::openshift-origin[] -|Compute -ifdef::ibm-z,ibm-power[|{op-system}] -ifndef::ibm-z,ibm-power[|{op-system} or RHEL 7.8 - 7.9] -|2 -|8 GB -|120 GB -endif::openshift-origin[] - -ifdef::openshift-origin[] -|Compute -|{op-system} -|2 -|8 GB -|120 GB -endif::openshift-origin[] - -|=== --- -ifdef::ibm-z[] -^[1]^ 1 physical core (IFL) provides 2 logical cores (threads) when SMT-2 is enabled. The hypervisor can provide 2 or more vCPUs. -endif::ibm-z[] -ifndef::ibm-z[] -^[1]^ 1 physical core provides 2 vCPUs when hyper-threading is enabled. 1 physical core provides 1 vCPU when hyper-threading is not enabled. -endif::ibm-z[] --- - -ifdef::ibm-z[] -[id="minimum-ibm-z-system-requirements_{context}"] -== Minimum IBM Z system requirements - -You can install {product-title} version {product-version} on the following IBM hardware: - -* IBM Z, versions 13, 14, or 15 -* LinuxONE, any version - -[discrete] -=== Hardware requirements - -* 1 LPAR with 6 IFLs that supports SMT2 -* 1 OSA or RoCE network adapter - -[discrete] -=== Operating system requirements - -* One instance of z/VM 7.1 - -On your z/VM instance, set up: - -* 3 guest virtual machines for {product-title} control plane machines -* 2 guest virtual machines for {product-title} compute machines -* 1 guest virtual machine for the temporary {product-title} bootstrap machine - -[discrete] -=== Disk storage for the z/VM guest virtual machines - -* FICON attached disk storage (DASDs). These can be z/VM minidisks, fullpack minidisks, or dedicated DASDs, all of which must be formatted as CDL, which is the default. To reach the minimum required DASD size for {op-system-first} installations, you need extended address volumes (EAV). If available, use HyperPAV to ensure optimal performance. -* FCP attached disk storage - -[discrete] -=== Storage / Main Memory - -* 16 GB for {product-title} control plane machines -* 8 GB for {product-title} compute machines -* 16 GB for the temporary {product-title} bootstrap machine - -[id="preferred-ibm-z-system-requirements_{context}"] -== Preferred IBM Z system requirements - -[discrete] -=== Hardware requirements - -* 3 LPARs with 6 IFLs each that support SMT2 -* 1 or 2 OSA or RoCE network adapters, or both -* Hipersockets, which are attached to a node either directly as a device or by bridging with one z/VM VSWITCH to be transparent to the z/VM guest. To directly connect Hipersockets to a node, you must set up a gateway to the external network via a RHEL 8 guest to bridge to the Hipersockets network. - -[discrete] -=== Operating system requirements - -* 2 or 3 instances of z/VM 7.1 for high availability - -On your z/VM instances, set up: - -* 3 guest virtual machines for {product-title} control plane machines, one per z/VM instance -* At least 6 guest virtual machines for {product-title} compute machines, distributed across the z/VM instances -* 1 guest virtual machine for the temporary {product-title} bootstrap machine -* To ensure the availability of integral components in an overcommitted environment, increase the priority of the control plane using the CP command `SET SHARE`. Do the same for infrastructure plane machines if they exist. See link:https://www.ibm.com/support/knowledgecenter/en/SSB27U_7.1.0/com.ibm.zvm.v710.hcpb7/setshare.htm[SET SHARE] in the IBM Knowledge Center. - -[discrete] -=== Disk storage for the z/VM guest virtual machines - -* FICON attached disk storage (DASDs). These can be z/VM minidisks, fullpack minidisks, or dedicated DASDs, all of which must be formatted as CDL, which is the default. To reach the minimum required DASD size for {op-system-first} installations, you need extended address volumes (EAV). If available, use HyperPAV and High Performance FICON (zHPF) to ensure optimal performance. -* FCP attached disk storage - -[discrete] -=== Storage / Main Memory - -* 16 GB for {product-title} control plane machines -* 8 GB for {product-title} compute machines -* 16 GB for the temporary {product-title} bootstrap machine -endif::ibm-z[] - -ifdef::ibm-power[] - -[id="minimum-ibm-power-system-requirements_{context}"] -== Minimum IBM Power Systems requirements - -You can install {product-title} version {product-version} on the following IBM hardware: - -* IBM POWER8 or POWER9 processor-based systems - -[discrete] -=== Hardware requirements - -* 6 IBM Power bare metal servers or 6 LPARs across multiple PowerVM servers - -[discrete] -=== Operating system requirements - -* One instance of an IBM POWER8 or POWER9 processor-based system - -On your IBM Power instance, set up: - -* 3 guest virtual machines for {product-title} control plane machines -* 2 guest virtual machines for {product-title} compute machines -* 1 guest virtual machine for the temporary {product-title} bootstrap machine - -[discrete] -=== Disk storage for the IBM Power guest virtual machines - -* Storage provisioned by the Virtual I/O Server using vSCSI, NPIV (N-Port ID Virtualization) or SSP (shared storage pools) - -[discrete] -=== Network for the PowerVM guest virtual machines - -* Virtualized by the Virtual I/O Server using Shared Ethernet Adapter -* Virtualized by the Virtual I/O Server using IBM VNIC - -[discrete] -=== Storage / main memory - -* 120 GB / 16 GB for {product-title} control plane machines -* 120 GB / 8 GB for {product-title} compute machines -* 120 GB / 16 GB for the temporary {product-title} bootstrap machine - -[id="recommended-ibm-Power-system-requirements_{context}"] - -== Recommended IBM Power system requirements -[discrete] -=== Hardware requirements - -* 6 IBM Power bare metal servers or 6 LPARs across multiple PowerVM servers - -[discrete] -=== Operating system requirements - -* One instance of an IBM POWER8 or POWER9 processor-based system - -On your IBM Power instance, set up: - -* 3 guest virtual machines for {product-title} control plane machines -* 2 guest virtual machines for {product-title} compute machines -* 1 guest virtual machine for the temporary {product-title} bootstrap machine - -[discrete] -=== Disk storage for the IBM Power guest virtual machines - -* Storage provisioned by the Virtual I/O Server using vSCSI, NPIV (N-Port ID Virtualization) or SSP (shared storage pools) - -[discrete] -=== Network for the PowerVM guest virtual machines - -* Virtualized by the Virtual I/O Server using Shared Ethernet Adapter -* Virtualized by the Virtual I/O Server using IBM VNIC - -[discrete] -=== Storage / main memory - -* 120 GB / 32 GB for {product-title} control plane machines -* 120 GB / 32 GB for {product-title} compute machines -* 120 GB / 16 GB for the temporary {product-title} bootstrap machine - -endif::ibm-power[] - -[id="csr_management_{context}"] -== Certificate signing requests management - -Because your cluster has limited access to automatic machine management when you -use infrastructure that you provision, you must provide a mechanism for approving -cluster certificate signing requests (CSRs) after installation. The -`kube-controller-manager` only approves the kubelet client CSRs. The -`machine-approver` cannot guarantee the validity of a serving certificate -that is requested by using kubelet credentials because it cannot confirm that -the correct machine issued the request. You must determine and implement a -method of verifying the validity of the kubelet serving certificate requests -and approving them. - -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-bare-metal"] -:!bare-metal: -endif::[] -ifeval::["{context}" == "installing-bare-metal-network-customizations"] -:!bare-metal: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!bare-metal: -endif::[] diff --git a/modules/installation-restricted-network-samples.adoc b/modules/installation-restricted-network-samples.adoc deleted file mode 100644 index 7494b75eadf1..000000000000 --- a/modules/installation-restricted-network-samples.adoc +++ /dev/null @@ -1,130 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-restricted-networks-preparations.adoc -// * openshift_images/samples-operator-alt-registry.adoc - -ifeval::["{context}" == "installing-restricted-networks-preparations"] -:restrictednetwork: -endif::[] - -ifeval::["{context}" == "samples-operator-alt-registry"] -:samplesoperatoraltreg: -endif::[] - -[id="installation-restricted-network-samples_{context}"] -= Using Cluster Samples Operator image streams with alternate or mirrored registries - -Most image streams in the `openshift` namespace managed by the Cluster Samples Operator -point to images located in the Red Hat registry at link:https://registry.redhat.io[registry.redhat.io]. -ifdef::restrictednetwork[] -Mirroring -will not apply to these image streams. -endif::[] - -[IMPORTANT] -==== -The `jenkins`, `jenkins-agent-maven`, and `jenkins-agent-nodejs` image streams -come from the install payload and are managed by the Samples -ifdef::restrictednetwork[] -Operator, so no further mirroring procedures are needed for those image streams. -endif::[] -ifdef::samplesoperatoraltreg[] -Operator. -endif::[] - -Setting the `samplesRegistry` field in the Sample Operator configuration file to link:https://registry.redhat.io[registry.redhat.io] is redundant because it is already directed to link:https://registry.redhat.io[registry.redhat.io] for everything but Jenkins images and image streams. - -//// -The Cluster Samples Operator prevents the use of the following registries for the Jenkins image streams: - -* link:https://docker.io[docker.io] -* link:https://registry.redhat.io[registry.redhat.io] -* link:https://registry.access.redhat.com[registry.access.redhat.com] -* link:https://quay.io[quay.io]. -//// -==== - -[NOTE] -==== -The `cli`, `installer`, `must-gather`, and `tests` image streams, while -part of the install payload, are not managed by the Cluster Samples Operator. These are -not addressed in this procedure. -==== - -.Prerequisites -* Access to the cluster as a user with the `cluster-admin` role. -* Create a pull secret for your mirror registry. - -.Procedure - -. Access the images of a specific image stream to mirror, for example: -+ -[source,terminal] ----- -$ oc get is <imagestream> -n openshift -o json | jq .spec.tags[].from.name | grep registry.redhat.io ----- -+ -. Mirror images from link:https://registry.redhat.io[registry.redhat.io] associated with any image streams you need -ifdef::restrictednetwork[] -in the restricted network environment into one of the defined mirrors, for example: -endif::[] -ifdef::configsamplesoperator[] -into your defined preferred registry, for example: -endif::[] -+ -[source,terminal] ----- -$ oc image mirror registry.redhat.io/rhscl/ruby-25-rhel7:latest ${MIRROR_ADDR}/rhscl/ruby-25-rhel7:latest ----- - -. Create the cluster’s image configuration object: -+ -[source,terminal] ----- -$ oc create configmap registry-config --from-file=${MIRROR_ADDR_HOSTNAME}..5000=$path/ca.crt -n openshift-config ----- - -. Add the required trusted CAs for the mirror in the cluster’s image -configuration object: -+ -[source,terminal] ----- -$ oc patch image.config.openshift.io/cluster --patch '{"spec":{"additionalTrustedCA":{"name":"registry-config"}}}' --type=merge ----- - -. Update the `samplesRegistry` field in the Cluster Samples Operator configuration object -to contain the `hostname` portion of the mirror location defined in the mirror -configuration: -+ -[source,terminal] ----- -$ oc edit configs.samples.operator.openshift.io -n openshift-cluster-samples-operator ----- -+ -[NOTE] -==== -This is required because the image stream import process does not use the mirror or search mechanism at this time. -==== -+ -. Add any image streams that are not mirrored into the `skippedImagestreams` field -of the Cluster Samples Operator configuration object. Or if you do not want to support -any of the sample image streams, set the Cluster Samples Operator to `Removed` in the -Cluster Samples Operator configuration object. -+ -[NOTE] -==== -The Cluster Samples Operator issues alerts if image stream imports are failing but the Cluster Samples Operator is either periodically retrying or does not appear to be retrying them. -==== -+ -Many of the templates in the `openshift` namespace -reference the image streams. So using `Removed` to purge both the image streams -and templates will eliminate the possibility of attempts to use them if they -are not functional because of any missing image streams. - -ifeval::["{context}" == "installing-restricted-networks-preparations"] -:!restrictednetwork: -endif::[] - -ifeval::["{context}" == "samples-operator-alt-registry"] -:!samplesoperatoraltreg: -endif::[] diff --git a/modules/installation-rhv-about-inventory-yml.adoc b/modules/installation-rhv-about-inventory-yml.adoc deleted file mode 100644 index 4b99476c2a80..000000000000 --- a/modules/installation-rhv-about-inventory-yml.adoc +++ /dev/null @@ -1,187 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-about-inventory-yml_{context}"] -= The inventory.yml file - -You use the `inventory.yml` file to define and create elements of the {product-title} cluster you are installing. This includes elements such as the {op-system-first} image, virtual machine templates, bootstrap machine, control plane nodes, and worker nodes. You also use `inventory.yml` to destroy the cluster. - -The following `inventory.yml` example shows you the parameters and their default values. The quantities and numbers in these default values meet the requirements for running a production {product-title} cluster in a {rh-virtualization} environment. - -.Example `inventory.yml` file -[source,yaml] ----- ---- -all: - vars: - - ovirt_cluster: "Default" - ocp: - assets_dir: "{{ lookup('env', 'ASSETS_DIR') }}" - ovirt_config_path: "{{ lookup('env', 'HOME') }}/.ovirt/ovirt-config.yaml" - - # --- - # {op-system} section - # --- - rhcos: - image_url: "https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/latest/rhcos-openstack.x86_64.qcow2.gz" - local_cmp_image_path: "/tmp/rhcos.qcow2.gz" - local_image_path: "/tmp/rhcos.qcow2" - - # --- - # Profiles section - # --- - control_plane: - cluster: "{{ ovirt_cluster }}" - memory: 16GiB - sockets: 4 - cores: 1 - template: rhcos_tpl - operating_system: "rhcos_x64" - type: high_performance - graphical_console: - headless_mode: false - protocol: - - spice - - vnc - disks: - - size: 120GiB - name: os - interface: virtio_scsi - storage_domain: depot_nvme - nics: - - name: nic1 - network: lab - profile: lab - - compute: - cluster: "{{ ovirt_cluster }}" - memory: 16GiB - sockets: 4 - cores: 1 - template: worker_rhcos_tpl - operating_system: "rhcos_x64" - type: high_performance - graphical_console: - headless_mode: false - protocol: - - spice - - vnc - disks: - - size: 120GiB - name: os - interface: virtio_scsi - storage_domain: depot_nvme - nics: - - name: nic1 - network: lab - profile: lab - - # --- - # Virtual machines section - # --- - vms: - - name: "{{ metadata.infraID }}-bootstrap" - ocp_type: bootstrap - profile: "{{ control_plane }}" - type: server - - name: "{{ metadata.infraID }}-master0" - ocp_type: master - profile: "{{ control_plane }}" - - name: "{{ metadata.infraID }}-master1" - ocp_type: master - profile: "{{ control_plane }}" - - name: "{{ metadata.infraID }}-master2" - ocp_type: master - profile: "{{ control_plane }}" - - name: "{{ metadata.infraID }}-worker0" - ocp_type: worker - profile: "{{ compute }}" - - name: "{{ metadata.infraID }}-worker1" - ocp_type: worker - profile: "{{ compute }}" - - name: "{{ metadata.infraID }}-worker2" - ocp_type: worker - profile: "{{ compute }}" ----- - -[IMPORTANT] -==== -Enter values for parameters whose descriptions begin with "Enter." Otherwise, you can use the default value or replace it with a new value. -==== - -.General section - -* `ovirt_cluster`: Enter the name of an existing {rh-virtualization} cluster in which to install the {product-title} cluster. -* `ocp.assets_dir`: The path of a directory the `openshift-install` installation program creates to store the files that it generates. -* `ocp.ovirt_config_path`: The path of the `ovirt-config.yaml` file the installation program generates, for example, `./wrk/install-config.yaml`. This file contains the credentials required to interact with the REST API of the oVirt Engine/{rh-virtualization} Manager. - -.{op-system-first} section - -* `image_url`: Enter the URL of the {op-system} image you specified for download. -* `local_cmp_image_path`: The path of a local download directory for the compressed {op-system} image. -* `local_image_path`: The path of a local directory for the extracted {op-system} image. - -.Profiles section - -This section consists of two profiles: - -* `control_plane`: The profile of the bootstrap and control plane nodes. -* `compute`: The profile of workers nodes in the compute plane. - -These profiles have the following parameters. The default values of the parameters meet the minimum requirements for running a production cluster. You can increase or customize these values to meet your workload requirements. - -* `cluster`: The value gets the cluster name from `ovirt_cluster` in the General Section. -* `memory`: The amount of memory, in GB, for the virtual machine. -* `sockets`: The number of sockets for the virtual machine. -* `cores`: The number of cores for the virtual machine. -* `template`: The name of the virtual machine template. If plan to install multiple clusters, and these clusters use templates that contain different specifications, prepend the template name with the ID of the cluster. -* `operating_system`: The type of guest operating system in the virtual machine. With oVirt/{rh-virtualization} version 4.4, this value must be `rhcos_x64` so the value of `Ignition script` can be passed to the VM. -* `type`: Enter `server` as the type of the virtual machine. -+ -[IMPORTANT] -==== -You must change the value of the `type` parameter from `high_performance` to `server`. -==== -* `disks`: The disk specifications. The `control_plane` and `compute` nodes can have different storage domains. -* `size`: The minimum disk size. -* `name`: Enter the name of a disk connected to the target cluster in {rh-virtualization}. -* `interface`: Enter the interface type of the disk you specified. -* `storage_domain`: Enter the storage domain of the disk you specified. -* `nics`: Enter the `name` and `network` the virtual machines use. You can also specify the virtual network interface profile. By default, NICs obtain their MAC addresses from the oVirt/{rh-virtualization} MAC pool. - -.Virtual machines section - -This final section, `vms`, defines the virtual machines you plan to create and deploy in the cluster. By default, it provides the minimum number of control plane and worker nodes for a production environment. - -`vms` contains three required elements: - -* `name`: The name of the virtual machine. In this case, `metadata.infraID` prepends the virtual machine name with the infrastructure ID from the `metadata.yml` file. -* `ocp_type`: The role of the virtual machine in the OCP cluster. Possible values are `bootstrap`, `master`, `worker`. -* `profile`: The name of the profile from which each virtual machine inherits specifications. Possible values in this example are `control_plane` or `compute`. -+ -You can override the value a virtual machine inherits from its profile. To do this, you add the name of the profile attribute to the virtual machine in `inventory.yml` and assign it an overriding value. To see an example of this, examine the `name: "{{ metadata.infraID }}-bootstrap"` virtual machine in the preceding `inventory.yml` example: It has a `type` attribute whose value, `server`, overrides the value of the `type` attribute this virtual machine would otherwise inherit from the `control_plane` profile. - -// TBD https://issues.redhat.com/browse/OCPRHV-414 -// Consider documenting *additional* optional attributes in https://github.com/oVirt/ovirt-ansible-vm-infra that aren't already covered here. Hypothetically, it seems like a user could add these attributes to a profile and then want to override them in the inventory.yml. - -// TBD - Consider adding a topic on how related to: Configure DHCP to assign permanent IP addresses to the virtual machines, consider using the `mac_address` attribute to assign a fixed MAC address to each virtual machine. However, avoid using the same MAC address if you are deploying more than one cluster. We should consider creating a new topic to document this/these scenario(s). - -.Metadata variables - -For virtual machines, `metadata.infraID` prepends the name of the virtual machine with the infrastructure ID from the `metadata.json` file you create when you build the Ignition files. - -The playbooks use the following code to read `infraID` from the specific file located in the `ocp.assets_dir`. - -[source,yaml] ----- ---- -- name: include metadata.json vars - include_vars: - file: "{{ ocp.assets_dir }}/metadata.json" - name: metadata - - ... ----- diff --git a/modules/installation-rhv-building-ignition-files.adoc b/modules/installation-rhv-building-ignition-files.adoc deleted file mode 100644 index 6b4f8c6d7063..000000000000 --- a/modules/installation-rhv-building-ignition-files.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-building-ignition-files_{context}"] -= Building the Ignition files - -To build the Ignition files from the manifest files you just generated and modified, you run the installation program. This action creates a {op-system-first} machine, `initramfs`, which fetches the Ignition files and performs the configurations needed to create a node. - -In addition to the Ignition files, the installation program generates the following: - -* An `auth` directory that contains the admin credentials for connecting to the cluster with the `oc` and `kubectl` utilities. -* A `metadata.json` file that contains information such as the {product-title} cluster name, cluster ID, and infrastructure ID for the current installation. - -The Ansible playbooks for this installation process use the value of `infraID` as a prefix for the virtual machines they create. This prevents naming conflicts when there are multiple installations in the same oVirt/{rh-virtualization} cluster. - -[NOTE] -==== -Certificates in Ignition configuration files expire after 24 hours. Complete the cluster installation and keep the cluster running in a non-degraded state for 24 hours so that the first certificate rotation can finish. -==== - -.Procedure - -. To build the Ignition files, enter: -+ -[source,terminal] ----- -$ openshift-install create ignition-configs --dir $ASSETS_DIR ----- -+ -.Example output -[source,terminal] ----- -$ tree -. -└── wrk - ├── auth - │ ├── kubeadmin-password - │ └── kubeconfig - ├── bootstrap.ign - ├── master.ign - ├── metadata.json - └── worker.ign ----- diff --git a/modules/installation-rhv-creating-bootstrap-machine.adoc b/modules/installation-rhv-creating-bootstrap-machine.adoc deleted file mode 100644 index b44482dccbc2..000000000000 --- a/modules/installation-rhv-creating-bootstrap-machine.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-creating-bootstrap-machine_{context}"] -= Creating the bootstrap machine - -You create a bootstrap machine by running the `bootstrap.yml` playbook. This playbook starts the bootstrap virtual machine, and passes it the `bootstrap.ign` Ignition file from the assets directory. The bootstrap node configures itself so it can serve Ignition files to the control plane nodes. - -To monitor the bootstrap process, you use the console in the {rh-virtualization} Administration Portal or connect to the virtual machine by using SSH. - -.Procedure - -. Create the bootstrap machine: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yml bootstrap.yml ----- - -. Connect to the bootstrap machine using a console in the Administration Portal or SSH. Replace `<bootstrap_ip>` with the bootstrap node IP address. To use SSH, enter: -+ -[source,terminal] ----- -$ ssh core@<boostrap.ip> ----- - -. Collect `bootkube.service` journald unit logs for the release image service from the bootstrap node: -+ -[source,terminal] ----- -[core@ocp4-lk6b4-bootstrap ~]$ journalctl -b -f -u release-image.service -u bootkube.service ----- -+ -[NOTE] -==== -The `bootkube.service` log on the bootstrap node outputs etcd `connection refused` errors, indicating that the bootstrap server is unable to connect to etcd on master nodes. After etcd has started on each master node and the nodes have joined the cluster, the errors should stop. -==== diff --git a/modules/installation-rhv-creating-control-plane-nodes.adoc b/modules/installation-rhv-creating-control-plane-nodes.adoc deleted file mode 100644 index 9408a4be8fd5..000000000000 --- a/modules/installation-rhv-creating-control-plane-nodes.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-creating-control-plane-nodes_{context}"] -= Creating the control plane nodes - -You create the control plane nodes by running the `masters.yml` playbook. This playbook passes the `master.ign` Ignition file to each of the virtual machines. The Ignition file contains a directive for the control plane node to get the Ignition from a URL such as `https://api-int.ocp4.example.org:22623/config/master`. The port number in this URL is managed by the load balancer, and is accessible only inside the cluster. - -.Procedure - -. Create the control plane nodes: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yml masters.yml ----- - -. While the playbook creates your control plane, monitor the bootstrapping process: -+ -[source,terminal] ----- -$ openshift-install wait-for bootstrap-complete --dir $ASSETS_DIR ----- -+ -.Example output -[source,terminal] ----- -INFO API v1.18.3+b74c5ed up -INFO Waiting up to 40m0s for bootstrapping to complete... ----- - -. When all the pods on the control plane nodes and etcd are up and running, the installation program displays the following output. -+ -.Example output -[source,terminal] ----- -INFO It is now safe to remove the bootstrap resources ----- diff --git a/modules/installation-rhv-creating-install-config-file.adoc b/modules/installation-rhv-creating-install-config-file.adoc deleted file mode 100644 index cbfb82a4ba8b..000000000000 --- a/modules/installation-rhv-creating-install-config-file.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-creating-install-config-file_{context}"] -= Creating the install config file - -You create an installation configuration file by running the installation program, `openshift-install`, and responding to its prompts with information you specified or gathered earlier. - -When you finish responding to the prompts, the installation program creates an initial version of the `install-config.yaml` file in the assets directory you specified earlier, for example, `./wrk/install-config.yaml` - -The installation program also creates a file, `$HOME/.ovirt/ovirt-config.yaml`, that contains all the connection parameters that are required to reach the oVirt Engine/{rh-virtualization} Manager and use its REST API. - -**NOTE:** -The installation process does not use values you supply for some parameters, such as `Internal API virtual IP` and `Ingress virtual IP`, because you have already configured them in your infrastructure DNS. - -It also uses the values you supply for parameters in `inventory.yml`, like the ones for `oVirt cluster`, `oVirt storage`, and `oVirt network`. And uses a script to remove or replace these same values from `install-config.yaml` with the previously mentioned `virtual IPs`. -//For details, see xref:set-platform-to-none[]. - -.Procedure - -. Run the installation program: -+ -[source,terminal] ----- -$ openshift-install create install-config --dir $ASSETS_DIR ----- - -. Respond to the installation program's prompts with information about your system. -+ -.Example output -[source,terminal] ----- -? SSH Public Key /home/user/.ssh/id_dsa.pub -? Platform <ovirt> -? Engine FQDN[:PORT] [? for help] <engine.fqdn> -? Enter ovirt-engine username <ovirtadmin@internal> -? Enter password <******> -? oVirt cluster <cluster> -? oVirt storage <storage> -? oVirt network <net> -? Internal API virtual IP <172.16.0.252> -? Ingress virtual IP <172.16.0.251> -? Base Domain <example.org> -? Cluster Name <ocp4> -? Pull Secret [? for help] <********> ----- - -For `Internal API virtual IP` and `Ingress virtual IP`, supply the IP addresses you specified when you configured the DNS service. - -Together, the values you enter for the `oVirt cluster` and `Base Domain` prompts form the FQDN portion of URLs for the REST API and any applications you create, such as `\https://api.ocp4.example.org:6443/` and `\https://console-openshift-console.apps.ocp4.example.org`. - -To get your pull secret, visit https://cloud.redhat.com/openshift/install/pull-secret. diff --git a/modules/installation-rhv-creating-templates-virtual-machines.adoc b/modules/installation-rhv-creating-templates-virtual-machines.adoc deleted file mode 100644 index cfc67897151d..000000000000 --- a/modules/installation-rhv-creating-templates-virtual-machines.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-creating-templates-virtual-machines_{context}"] -= Creating templates and virtual machines - -After confirming the variables in the `inventory.yml`, you run the first Ansible provisioning playbook, `create-templates-and-vms.yml`. - -This playbook uses the connection parameters for the {rh-virtualization} Manager from `$HOME/.ovirt/ovirt-config.yaml` and reads `metadata.json` in the assets directory. - -If a local {op-system-first} image is not already present, the playbook downloads one from the URL you specified for `image_url` in `inventory.yml`. It extracts the image and uploads it to {rh-virtualization} to create templates. - -The playbook creates a template based on the `control_plane` and `compute` profiles in the `inventory.yml` file. If these profiles have different names, it creates two templates. - -When the playbook finishes, the virtual machines it creates are stopped. You can get information from them to help configure other infrastructure elements. For example, you can get the virtual machines' MAC addresses to configure DHCP to assign permanent IP addresses to the virtual machines. - -.Procedure - - -. In `inventory.yml`, under the `control_plane` and `compute` variables, change both instances of `type: high_performance` to `type: server`. - -. Optional: If you plan to perform multiple installations to the same cluster, create different templates for each OCP installation. In the `inventory.yml` file, prepend the value of `template` with `infraID`. For example: -+ -[source,yaml] ----- - control_plane: - cluster: "{{ ovirt_cluster }}" - memory: 16GiB - sockets: 4 - cores: 1 - template: "{{ metadata.infraID }}-rhcos_tpl" - operating_system: "rhcos_x64" - ... ----- - -. Create the templates and virtual machines: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yml create-templates-and-vms.yml ----- diff --git a/modules/installation-rhv-creating-worker-nodes-completing-installation.adoc b/modules/installation-rhv-creating-worker-nodes-completing-installation.adoc deleted file mode 100644 index 7321c1f59448..000000000000 --- a/modules/installation-rhv-creating-worker-nodes-completing-installation.adoc +++ /dev/null @@ -1,105 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-creating-worker-nodes-completing-installation_{context}"] -= Creating the worker nodes and completing the installation - -Creating worker nodes is similar to creating control plane nodes. However, worker nodes workers do not automatically join the cluster. To add them to the cluster, you review and approve the workers' pending CSRs (Certificate Signing Requests). - -After approving the first requests, you continue approving CSR until all of the worker nodes are approved. When you complete this process, the worker nodes become `Ready` and can have pods scheduled to run on them. - -Finally, monitor the command line to see when the installation process completes. - -.Procedure - -. Create the worker nodes: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yml workers.yml ----- - - -. To list all of the CSRs, enter: -+ -[source,terminal] ----- -$ oc get csr -A ----- -+ -Eventually, this command displays one CSR per node. For example: -+ -.Example output -[source,terminal] ----- -NAME AGE SIGNERNAME REQUESTOR CONDITION -csr-2lnxd 63m kubernetes.io/kubelet-serving system:node:ocp4-lk6b4-master0.ocp4.example.org Approved,Issued -csr-hff4q 64m kubernetes.io/kube-apiserver-client-kubelet system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Approved,Issued -csr-hsn96 60m kubernetes.io/kubelet-serving system:node:ocp4-lk6b4-master2.ocp4.example.org Approved,Issued -csr-m724n 6m2s kubernetes.io/kube-apiserver-client-kubelet system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending -csr-p4dz2 60m kubernetes.io/kube-apiserver-client-kubelet system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Approved,Issued -csr-t9vfj 60m kubernetes.io/kubelet-serving system:node:ocp4-lk6b4-master1.ocp4.example.org Approved,Issued -csr-tggtr 61m kubernetes.io/kube-apiserver-client-kubelet system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Approved,Issued -csr-wcbrf 7m6s kubernetes.io/kube-apiserver-client-kubelet system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending ----- - -. To filter the list and see only pending CSRs, enter: -+ -[source,terminal] ----- -$ watch "oc get csr -A | grep pending -i" ----- -+ -This command refreshes the output every two seconds and displays only pending CSRs. For example: -+ -.Example output -[source,terminal] ----- -Every 2.0s: oc get csr -A | grep pending -i - -csr-m724n 10m kubernetes.io/kube-apiserver-client-kubelet system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending -csr-wcbrf 11m kubernetes.io/kube-apiserver-client-kubelet system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending ----- - -. Inspect each pending request. For example: -+ -.Example output -[source,terminal] ----- -$ oc describe csr csr-m724n ----- -+ -.Example output -[source,terminal] ----- -Name: csr-m724n -Labels: <none> -Annotations: <none> -CreationTimestamp: Sun, 19 Jul 2020 15:59:37 +0200 -Requesting User: system:serviceaccount:openshift-machine-config-operator:node-bootstrapper -Signer: kubernetes.io/kube-apiserver-client-kubelet -Status: Pending -Subject: - Common Name: system:node:ocp4-lk6b4-worker1.ocp4.example.org - Serial Number: - Organization: system:nodes -Events: <none> ----- - -. If the CSR information is correct, approve the request: -+ -[source,terminal] ----- -$ oc adm certificate approve csr-m724n ----- - -. Wait for the installation process to finish: -+ -[source,terminal] ----- -$ openshift-install wait-for install-complete --dir $ASSETS_DIR --log-level debug ----- -+ -When the installation completes, the command line displays the URL of the {product-title} web console and the administrator user name and password. diff --git a/modules/installation-rhv-customizing-install-config-yaml.adoc b/modules/installation-rhv-customizing-install-config-yaml.adoc deleted file mode 100644 index ca991b104234..000000000000 --- a/modules/installation-rhv-customizing-install-config-yaml.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-customizing-install-config-yaml_{context}"] -= Customizing install-config.yaml - -Here, you use three Python scripts to override some of the installation program's default behaviors: - -* By default, the installation program uses the machine API to create nodes. To override this default behavior, you set the number of compute nodes to zero replicas. Later, you use Ansible playbooks to create the compute nodes. - -* By default, the installation program sets the IP range of the machine network for nodes. To override this default behavior, you set the IP range to match your infrastructure. - -* By default, the installation program sets the platform to `ovirt`. However, installing a cluster on user-provisioned infrastructure is more similar to installing a cluster on bare metal. Therefore, you delete the ovirt platform section from `install-config.yaml` and change the platform to `none`. Instead, you use `inventory.yml` to specify all of the required settings. - -NOTE: These snippets work with Python 3 and Python 2. - -// TBD - https://issues.redhat.com/browse/OCPRHV-414 -// Please discuss with engineering whether these three scripts can/should be combined into a single script. -// Also consider combining this topic with other customization topics. - -.Procedure -//TBD - Should we combine these into one script? - -. Set the number of compute nodes to zero replicas: -+ -[source,python] ----- -$ python3 -c 'import os, yaml -path = "%s/install-config.yaml" % os.environ["ASSETS_DIR"] -conf = yaml.safe_load(open(path)) -conf["compute"][0]["replicas"] = 0 -open(path, "w").write(yaml.dump(conf, default_flow_style=False))' ----- - - -. Set the IP range of the machine network. For example, to set the range to `172.16.0.0/16`, enter: -+ -[source,python] ----- -$ python3 -c 'import os, yaml -path = "%s/install-config.yaml" % os.environ["ASSETS_DIR"] -conf = yaml.safe_load(open(path)) -conf["networking"]["machineNetwork"][0]["cidr"] = "172.16.0.0/16" -open(path, "w").write(yaml.dump(conf, default_flow_style=False))' ----- - - -. Remove the `ovirt` section and change the platform to `none`: -+ -[source,python] ----- -$ python3 -c 'import os, yaml -path = "%s/install-config.yaml" % os.environ["ASSETS_DIR"] -conf = yaml.safe_load(open(path)) -platform = conf["platform"] -del platform["ovirt"] -platform["none"] = {} -open(path, "w").write(yaml.dump(conf, default_flow_style=False))' ----- diff --git a/modules/installation-rhv-destroying-cluster.adoc b/modules/installation-rhv-destroying-cluster.adoc deleted file mode 100644 index 4efef6a3e2b6..000000000000 --- a/modules/installation-rhv-destroying-cluster.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc - -[id="installation-rhv-destroying-cluster_{context}"] -= Destroying the cluster - -When you are finished using the cluster, you can destroy it and remove related configurations from your infrastructure. - -.Prerequisites -* You preserved the original files you used to create the cluster. - -.Procedure - -. Optional: To remove the cluster, enter: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yml \ - retire-bootstrap.yml \ - retire-masters.yml \ - retire-workers.yml ----- - -. Remove any previous configurations you added to DNS, load balancers, and any other infrastructure. diff --git a/modules/installation-rhv-downloading-ansible-playbooks.adoc b/modules/installation-rhv-downloading-ansible-playbooks.adoc deleted file mode 100644 index a867e69faae8..000000000000 --- a/modules/installation-rhv-downloading-ansible-playbooks.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc - -[id="installation-rhv-downloading-ansible-playbooks_{context}"] -= Downloading the Ansible playbooks - -Download the Ansible playbooks for installing {product-title} version {product-version} on {rh-virtualization}. - -.Procedure - -. On your installation machine, run the following commands: -+ -[source,terminal] ----- -$ mkdir playbooks -$ cd playbooks -$ curl -L -X GET https://api.github.com/repos/openshift/installer/contents/upi/ovirt\?ref\=$release-{product-version} | -grep 'download_url.*\.yml' | -awk '{ print $2 }' | sed -r 's/("|",)//g' | -xargs -n 1 curl -O ----- - -.Next steps - -* After you download these Ansible playbooks, you must also create the environment variable for the assets directory and customize the `inventory.yml` file before you create an installation configuration file by running the installation program. diff --git a/modules/installation-rhv-editing-manifests.adoc b/modules/installation-rhv-editing-manifests.adoc deleted file mode 100644 index da3ecf380d4f..000000000000 --- a/modules/installation-rhv-editing-manifests.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-editing-mantifests_{context}"] -= Generate manifest files - -Use the installation program to generate a set of manifest files in the assets directory. - -The command to generate the manifest files displays a warning message before it consumes the `install-config.yaml` file. - -If you plan to reuse the `install-config.yaml` file, create a backup copy of it before you back it up before you generate the manifest files. - -// TBD There isn't a clear reason to generate the manifest files. Is this step necessary? It seem like normally the user only does this if they need to edit the files to customize something. Unfortunately, the lead developer on this project has left the organization. Looking at similar commands/topics in the openshift-docs, it seems like this step is only taken when the user needs to perform a specific customization. - - -.Procedure - -. Optional: Create a backup copy of the `install-config.yaml` file: -+ -[source,terminal] ----- -$ cp install-config.yaml install-config.yaml.backup ----- - -. Generate a set of manifests in your assets directory: -+ -[source,terminal] ----- -$ openshift-install create manifests --dir $ASSETS_DIR ----- -+ -This command displays the following messages. -+ -.Example output -[source,terminal] ----- -INFO Consuming Install Config from target directory -WARNING Making control-plane schedulable by setting MastersSchedulable to true for Scheduler cluster settings ----- -+ -The command generates the following manifest files: -+ -.Example output -[source,terminal] ----- -$ tree -. -└── wrk - ├── manifests - │ ├── 04-openshift-machine-config-operator.yaml - │ ├── cluster-config.yaml - │ ├── cluster-dns-02-config.yml - │ ├── cluster-infrastructure-02-config.yml - │ ├── cluster-ingress-02-config.yml - │ ├── cluster-network-01-crd.yml - │ ├── cluster-network-02-config.yml - │ ├── cluster-proxy-01-config.yaml - │ ├── cluster-scheduler-02-config.yml - │ ├── cvo-overrides.yaml - │ ├── etcd-ca-bundle-configmap.yaml - │ ├── etcd-client-secret.yaml - │ ├── etcd-host-service-endpoints.yaml - │ ├── etcd-host-service.yaml - │ ├── etcd-metric-client-secret.yaml - │ ├── etcd-metric-serving-ca-configmap.yaml - │ ├── etcd-metric-signer-secret.yaml - │ ├── etcd-namespace.yaml - │ ├── etcd-service.yaml - │ ├── etcd-serving-ca-configmap.yaml - │ ├── etcd-signer-secret.yaml - │ ├── kube-cloud-config.yaml - │ ├── kube-system-configmap-root-ca.yaml - │ ├── machine-config-server-tls-secret.yaml - │ └── openshift-config-secret-pull-secret.yaml - └── openshift - ├── 99_kubeadmin-password-secret.yaml - ├── 99_openshift-cluster-api_master-user-data-secret.yaml - ├── 99_openshift-cluster-api_worker-user-data-secret.yaml - ├── 99_openshift-machineconfig_99-master-ssh.yaml - ├── 99_openshift-machineconfig_99-worker-ssh.yaml - └── openshift-install-manifests.yaml ----- - -.Next steps - -* Make control plane nodes non-schedulable. diff --git a/modules/installation-rhv-making-control-plane-nodes-non-schedulable.adoc b/modules/installation-rhv-making-control-plane-nodes-non-schedulable.adoc deleted file mode 100644 index e6ce4341d7ac..000000000000 --- a/modules/installation-rhv-making-control-plane-nodes-non-schedulable.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-making-control-plane-nodes-non-schedulable_{context}"] -= Making control-plane nodes non-schedulable - -// TBD - https://issues.redhat.com/browse/OCPRHV-414 -// Here's my version of the intro text from https://github.com/openshift/installer/blob/master/docs/user/ovirt/install_upi.md#set-control-plane-nodes-unschedulable . This information is confusing. Please discuss with engineering and provide a good concise explanation of why the user is doing this. - -// "Earlier, when you set the compute `replicas` to zero, it also made control-plane nodes schedulable, which is something you do not want at this stage in the process."" -// -// "NOTE: Router pods can run also on control-plane nodes but there are some Kubernetes limitations that prevent the ingress load balancer from reaching those pods."" - -Because you are manually creating and deploying the control plane machines, you must configure a manifest file to make the control plane nodes non-schedulable. - -.Procedure - -. To make the control plane nodes non-schedulable, enter: -+ -[source,terminal] ----- -$ python3 -c 'import os, yaml -path = "%s/manifests/cluster-scheduler-02-config.yml" % os.environ["ASSETS_DIR"] -data = yaml.safe_load(open(path)) -data["spec"]["mastersSchedulable"] = False -open(path, "w").write(yaml.dump(data, default_flow_style=False))' ----- diff --git a/modules/installation-rhv-removing-bootstrap-machine.adoc b/modules/installation-rhv-removing-bootstrap-machine.adoc deleted file mode 100644 index 0526935deec2..000000000000 --- a/modules/installation-rhv-removing-bootstrap-machine.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-removing-bootstrap-machine_{context}"] -= Removing the bootstrap machine - -After the `wait-for` command shows that the bootstrap process is complete, you must remove the bootstrap virtual machine to free up compute, memory, and storage resources. Also, remove settings for the bootstrap machine from the load balancer directives. - -.Procedure - - -. To remove the bootstrap machine from the cluster, enter: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yml retire-bootstrap.yml ----- - -. Remove settings for the bootstrap machine from the load balancer directives. diff --git a/modules/installation-rhv-removing-cluster-upi.adoc b/modules/installation-rhv-removing-cluster-upi.adoc deleted file mode 100644 index e6bf12e57f1c..000000000000 --- a/modules/installation-rhv-removing-cluster-upi.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc - -[id="installation-rhv-removing-cluster-upi_{context}"] -= Removing a cluster that uses user-provisioned infrastructure - -When you are finished using the cluster, you can remove a cluster that uses user-provisioned infrastructure from your cloud. - -.Prerequisites - -* Have the original playbook files, assets directory and files, and `$ASSETS_DIR` environment variable that you used to you install the cluster. Typically, you can achieve this by using the same computer you used when you installed the cluster. - -.Procedure - -. To remove the cluster, enter: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yml \ - retire-bootstrap.yml \ - retire-masters.yml \ - retire-workers.yml ----- - -. Remove any configurations you added to DNS, load balancers, and any other infrastructure for this cluster. diff --git a/modules/installation-rhv-specifying-rhcos-image-settings.adoc b/modules/installation-rhv-specifying-rhcos-image-settings.adoc deleted file mode 100644 index cc91a37b7cf9..000000000000 --- a/modules/installation-rhv-specifying-rhcos-image-settings.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installation-rhv-specifying-rhcos-image-settings_{context}"] -= Specifying the {op-system} image settings - -Update the {op-system-first} image settings of the `inventory.yml` file. Later, when you run this file one of the playbooks, it downloads a compressed {op-system-first} image from the `image_url` URL to the `local_cmp_image_path` directory. The playbook then uncompresses the image to the `local_image_path` directory and uses it to create oVirt/{rh-virtualization} templates. - -// TBD - https://issues.redhat.com/browse/OCPRHV-414 -// Consider combining this topic with another one after we've resolved the issue of getting the files. - -.Procedure - -. Locate the {op-system} image download page for the version of {product-title} you are installing, such as link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/latest/[Index of /pub/openshift-v4/dependencies/rhcos/latest/latest]. - -. From that download page, copy the URL of an OpenStack `qcow2` image, such as `\https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/latest/rhcos-openstack.x86_64.qcow2.gz`. - -. Edit the `inventory.yml` playbook you downloaded earlier. In it, paste the URL as the value for `image_url`. For example: -+ -[source,yaml] ----- -rhcos: - "https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/latest/rhcos-openstack.x86_64.qcow2.gz" ----- diff --git a/modules/installation-special-config-crony.adoc b/modules/installation-special-config-crony.adoc deleted file mode 100644 index 435a262f22b1..000000000000 --- a/modules/installation-special-config-crony.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-customizing.adoc -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="installation-special-config-chrony_{context}"] -= Configuring chrony time service - -You can set the time server and related settings used by the chrony time service (chronyd) -by modifying the contents of the `chrony.conf` file and passing those contents -to your nodes as a machine config. - -.Procedure - -. Create the contents of the `chrony.conf` file and encode it as base64. For example: -+ -[source,terminal] ----- -$ cat << EOF | base64 - pool 0.rhel.pool.ntp.org iburst <1> - driftfile /var/lib/chrony/drift - makestep 1.0 3 - rtcsync - logdir /var/log/chrony - EOF ----- -<1> Specify any valid, reachable time source. Alternately, you can specify any of the following NTP servers: `1.rhel.pool.ntp.org`, `2.rhel.pool.ntp.org`, or `3.rhel.pool.ntp.org`. -+ -.Example output -[source,terminal] ----- -ICAgIHNlcnZlciBjbG9jay5yZWRoYXQuY29tIGlidXJzdAogICAgZHJpZnRmaWxlIC92YXIvbGli -L2Nocm9ueS9kcmlmdAogICAgbWFrZXN0ZXAgMS4wIDMKICAgIHJ0Y3N5bmMKICAgIGxvZ2RpciAv -dmFyL2xvZy9jaHJvbnkK ----- - -. Create the `MachineConfig` object file, replacing the base64 string with the one you just created yourself. -This example adds the file to `master` nodes. You can change it to `worker` or make an -additional `MachineConfig` object for the `worker` role: -+ -[source,terminal] ----- -$ cat << EOF > ./99-masters-chrony-configuration.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: master - name: 99-masters-chrony-configuration -spec: - config: - ignition: - config: {} - security: - tls: {} - timeouts: {} - version: 3.2.0 - networkd: {} - passwd: {} - storage: - files: - - contents: - source: data:text/plain;charset=utf-8;base64,ICAgIHNlcnZlciBjbG9jay5yZWRoYXQuY29tIGlidXJzdAogICAgZHJpZnRmaWxlIC92YXIvbGliL2Nocm9ueS9kcmlmdAogICAgbWFrZXN0ZXAgMS4wIDMKICAgIHJ0Y3N5bmMKICAgIGxvZ2RpciAvdmFyL2xvZy9jaHJvbnkK - mode: 420 - overwrite: true - path: /etc/chrony.conf - osImageURL: "" -EOF ----- - -. Make a backup copy of the configuration file. - -. Apply the configuration in one of two ways: -+ -* If the cluster is not up yet, generate manifest files, add this file to the `openshift` -directory, and then continue to create the cluster. -+ -* If the cluster is already running, apply the file as follows: -+ -[source,terminal] ----- - $ oc apply -f ./99-masters-chrony-configuration.yaml ----- diff --git a/modules/installation-special-config-encrypt-disk-tang.adoc b/modules/installation-special-config-encrypt-disk-tang.adoc deleted file mode 100644 index 4782effaf549..000000000000 --- a/modules/installation-special-config-encrypt-disk-tang.adoc +++ /dev/null @@ -1,164 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-customizing.adoc - -[id="installation-special-config-encrypt-disk-tang_{context}"] -= Enabling Tang disk encryption -Use this procedure to enable Tang mode disk encryption during {product-title} deployment. - -[NOTE] -==== -On previous versions of {op-system}, disk encryption was configured by specifying `/etc/clevis.json` in the Ignition config. That file is not supported in clusters created with {product-title} 4.7 or above, and the LUKS device should be configured directly via the Ignition `luks` section. -==== - -.Procedure - -. Access a Red Hat Enterprise Linux server from which you can configure the encryption -settings and run `openshift-install` to install a cluster and `oc` to work with it. -. Set up or access an existing Tang server. See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption_security-hardening#network-bound-disk-encryption_configuring-automated-unlocking-of-encrypted-volumes-using-policy-based-decryption[Network-bound disk encryption] -for instructions. See link:https://youtu.be/2uLKvB8Z5D0[Securing Automated Decryption New Cryptography and Techniques] -for a presentation on Tang. - -. Add kernel arguments to configure networking when you do the {op-system-first} installations for your cluster. For example, to configure DHCP networking, identify `ip=dhcp`, or set static networking when you add parameters to the kernel command line. For both DHCP and static networking, you also must provide the `rd.neednet=1` kernel argument. - -[IMPORTANT] -==== -Skipping this step causes the second boot to fail. -==== - -[start=4] -. Install the `clevis` package, if it is not already installed: - -[source,terminal] ----- -$ sudo yum install clevis -y ----- - -[start=5] -. Generate a thumbprint from the Tang server. - -.. In the following command, replace the value of `url` with the Tang server URL: -+ -[source,terminal] ----- -$ echo nifty random wordwords \ - | clevis-encrypt-tang \ - '{"url":"https://tang.example.org/"}' ----- -+ -.Example output -[source,terminal] ----- -The advertisement contains the following signing keys: - -PLjNyRdGw03zlRoGjQYMahSZGu9 ----- - -.. When the `Do you wish to trust these keys? [ynYN]` prompt displays, type `Y`, and the thumbprint is displayed: -+ -.Example output -[source,terminal] ----- -eyJhbmc3SlRyMXpPenc3ajhEQ01tZVJiTi1oM... ----- -+ -.Example output -[source,terminal] ----- -ewogInVybCI6ICJodHRwczovL3RhbmcuZXhhbXBsZS5jb20iLAogInRocCI6ICJaUk1leTFjR3cwN3psVExHYlhuUWFoUzBHdTAiCn0K ----- - -. In the `openshift` directory, create master or worker files to encrypt disks for those nodes. - -[IMPORTANT] -==== -If you are also configuring boot disk mirroring on the affected nodes, record the server thumbprint for later use, and skip this step. You will configure disk encryption when configuring boot disk mirroring. -==== - -** For worker nodes, use the following command: -+ -[source,terminal] ----- -$ cat << EOF > ./99-openshift-worker-tang-encryption.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - name: worker-tang - labels: - machineconfiguration.openshift.io/role: worker -spec: - config: - ignition: - version: 3.2.0 - storage: - luks: - - name: root - device: /dev/disk/by-partlabel/root - clevis: - tang: - - url: https://tang.example.com - thumbprint: PLjNyRdGw03zlRoGjQYMahSZGu9 - options: [--cipher, aes-cbc-essiv:sha256] - wipeVolume: true - filesystems: - - device: /dev/mapper/root - format: xfs - wipeFilesystem: true - label: root -EOF ----- - -** For master nodes, use the following command: -+ -[source,terminal] ----- -$ cat << EOF > ./99-openshift-master-tang-encryption.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - name: master-tang - labels: - machineconfiguration.openshift.io/role: master -spec: - config: - ignition: - version: 3.2.0 - storage: - luks: - - name: root - device: /dev/disk/by-partlabel/root - clevis: - tang: - - url: https://tang.example.com - thumbprint: PLjNyRdGw03zlRoGjQYMahSZGu9 - options: [--cipher, aes-cbc-essiv:sha256] - wipeVolume: true - filesystems: - - device: /dev/mapper/root - format: xfs - wipeFilesystem: true - label: root -EOF ----- - -. Add the `rd.neednet=1` kernel argument, as shown in the following example: -+ -[source,yaml] ----- - apiVersion: machineconfiguration.openshift.io/v1 - kind: MachineConfig - metadata: - name: <node_type>-tang <.> - spec: - config: - ignition: - version: 3.2.0 - kernelArguments: - - rd.neednet=1 <.> ----- -+ -<1> Use the name you defined in the previous examples based on the type of node you are configuring, for example: `name: worker-tang`. -+ -<2> Required. - -. Continue with the remainder of the {product-title} deployment. diff --git a/modules/installation-special-config-encrypt-disk-tpm2.adoc b/modules/installation-special-config-encrypt-disk-tpm2.adoc deleted file mode 100644 index 73087d67dc2e..000000000000 --- a/modules/installation-special-config-encrypt-disk-tpm2.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-customizing.adoc - -[id="installation-special-config-encrypt-disk-tpm2_{context}"] -= Enabling TPM v2 disk encryption -Use this procedure to enable TPM v2 mode disk encryption during {product-title} deployment. - -[NOTE] -==== -On previous versions of {op-system}, disk encryption was configured by specifying `/etc/clevis.json` in the Ignition config. That file is not supported in clusters created with {product-title} 4.7 or above, and the LUKS device should be configured directly via the Ignition `luks` section. -==== - -.Procedure - -. Check to see if TPM v2 encryption needs to be enabled in the BIOS on each node. -This is required on most Dell systems. Check the manual for your computer. - -. Change to the directory that contains the installation program and generate the Kubernetes manifests for the cluster: -+ -[source,terminal] ----- -$ ./openshift-install create manifests --dir=<installation_directory> ----- - -. In the `openshift` directory, create master or worker files to encrypt disks for those nodes. - -[IMPORTANT] -==== -If you are also configuring boot disk mirroring on the affected nodes, skip this step. You will configure disk encryption when configuring boot disk mirroring. -==== - -** To create a worker file, run the following command: -+ -[source,terminal] ----- -$ cat << EOF > ./99-openshift-worker-tpmv2-encryption.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - name: worker-tpm - labels: - machineconfiguration.openshift.io/role: worker -spec: - config: - ignition: - version: 3.2.0 - storage: - luks: - - name: root - device: /dev/disk/by-partlabel/root - clevis: - tpm2: true - options: [--cipher, aes-cbc-essiv:sha256] - wipeVolume: true - filesystems: - - device: /dev/mapper/root - format: xfs - wipeFilesystem: true - label: root -EOF ----- -** To create a master file, run the following command: -+ -[source,terminal] ----- -$ cat << EOF > ./99-openshift-master-tpmv2-encryption.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - name: master-tpm - labels: - machineconfiguration.openshift.io/role: master -spec: - config: - ignition: - version: 3.2.0 - storage: - luks: - - name: root - device: /dev/disk/by-partlabel/root - clevis: - tpm2: true - options: [--cipher, aes-cbc-essiv:sha256] - wipeVolume: true - filesystems: - - device: /dev/mapper/root - format: xfs - wipeFilesystem: true - label: root -EOF ----- - -. Make a backup copy of the YAML file. You should do this because the file will be deleted when you create the cluster. - -. Continue with the remainder of the {product-title} deployment. diff --git a/modules/installation-special-config-encrypt-disk.adoc b/modules/installation-special-config-encrypt-disk.adoc deleted file mode 100644 index 7868f895a794..000000000000 --- a/modules/installation-special-config-encrypt-disk.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-customizing.adoc - -[id="installation-special-config-encrypt-disk_{context}"] -= Encrypting disks during installation - -During {product-title} installation, you can enable disk encryption on all master and worker nodes. -This feature: - -* Is available for installer-provisioned infrastructure -and user-provisioned infrastructure deployments -* Is supported on {op-system-first} systems only -* Sets up disk encryption during the manifest installation phase so all data written to disk, from first boot forward, is encrypted -* Encrypts data on the root filesystem only (`/dev/mapper/coreos-luks-root` on `/`) -* Requires no user intervention for providing passphrases -* Uses AES-256-CBC encryption -* Should be enabled for your cluster to support FIPS. - -There are two different supported encryption modes: - -* TPM v2: This is the preferred mode. TPM v2 stores passphrases in a secure cryptoprocessor. -To implement TPM v2 disk encryption, create an Ignition config file as described below. - -* Tang: To use Tang to encrypt your cluster, you need to use a Tang server. -Clevis implements decryption on the client side. -Tang encryption mode is only supported for bare metal installs. - -Follow one of the two procedures to enable disk encryption for the nodes in your cluster. diff --git a/modules/installation-special-config-kargs.adoc b/modules/installation-special-config-kargs.adoc deleted file mode 100644 index 265f0f80aed4..000000000000 --- a/modules/installation-special-config-kargs.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing-special-config.adoc - -[id="installation-special-config-kargs_{context}"] - -= Adding day-1 kernel arguments -Although it is often preferable to modify kernel arguments as a day-2 activity, -you might want to add kernel arguments to all master or worker nodes during initial cluster -installation. Here are some reasons you might want -to add kernel arguments during cluster installation so they take effect before -the systems first boot up: - -* You want to disable a feature, such as SELinux, so it has no impact on the systems when they first come up. -* You need to do some low-level network configuration before the systems start. - -To add kernel arguments to master or worker nodes, you can create a `MachineConfig` object -and inject that object into the set of manifest files used by Ignition during -cluster setup. - -For a listing of arguments you can pass to a RHEL 8 kernel at boot time, see -link:https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt[Kernel.org kernel parameters]. -It is best to only add kernel arguments with this procedure if they are needed to complete the initial -{product-title} installation. - -.Procedure - -. Change to the directory that contains the installation program and generate the Kubernetes manifests for the cluster: -+ -[source,terminal] ----- -$ ./openshift-install create manifests --dir=<installation_directory> ----- - -. Decide if you want to add kernel arguments to worker or master nodes. - -. In the `openshift` directory, create a file (for example, -`99-openshift-machineconfig-master-kargs.yaml`) to define a `MachineConfig` -object to add the kernel settings. -This example adds a `loglevel=7` kernel argument to master nodes: -+ -[source,terminal] ----- -$ cat << EOF > 99-openshift-machineconfig-master-kargs.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: master - name: 99-openshift-machineconfig-master-kargs -spec: - kernelArguments: - - 'loglevel=7' -EOF ----- -+ -You can change `master` to `worker` to add kernel arguments to worker nodes instead. -Create a separate YAML file to add to both master and worker nodes. - -You can now continue on to create the cluster. diff --git a/modules/installation-special-config-kmod.adoc b/modules/installation-special-config-kmod.adoc deleted file mode 100644 index b806c2d37b31..000000000000 --- a/modules/installation-special-config-kmod.adoc +++ /dev/null @@ -1,500 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing-special-config.adoc - -[id="installation-special-config-kmod_{context}"] -= Adding kernel modules to nodes - -For most common hardware, the Linux kernel includes the device driver -modules needed to use that hardware when the computer starts up. For -some hardware, however, modules are not available in Linux. Therefore, you must -find a way to provide those modules to each host computer. This -procedure describes how to do that for nodes in an {product-title} cluster. - -When a kernel module is first deployed by following these instructions, -the module is made available for the current kernel. If a new kernel -is installed, the kmods-via-containers software will rebuild and deploy -the module so a compatible version of that module is available with the -new kernel. - -The way that this feature is able to keep the module up to date on each -node is by: - -* Adding a systemd service to each node that starts at boot time to detect -if a new kernel has been installed and -* If a new kernel is detected, the -service rebuilds the module and installs it to the kernel - -For information on the software needed for this procedure, see the -link:https://github.com/kmods-via-containers/kmods-via-containers[kmods-via-containers] github site. - -A few important issues to keep in mind: - -* This procedure is Technology Preview. -* Software tools and examples are not yet available in official RPM form -and can only be obtained for now from unofficial `github.com` sites noted in the procedure. -* Third-party kernel modules you might add through these procedures are not supported by Red Hat. -* In this procedure, the software needed to build your kernel modules is -deployed in a RHEL 8 container. Keep in mind that modules are rebuilt -automatically on each node when that node gets a new kernel. For that -reason, each node needs access to a `yum` repository that contains the -kernel and related packages needed to rebuild the module. That content -is best provided with a valid RHEL subscription. - -[id="building-testing-kernel-module-container_{context}"] -== Building and testing the kernel module container - -Before deploying kernel modules to your {product-title} cluster, -you can test the process on a separate RHEL system. -Gather the kernel module’s source code, the KVC framework, and the -kmod-via-containers software. Then build and test the module. To do -that on a RHEL 8 system, do the following: - -.Procedure - -. Register a RHEL 8 system: -+ -[source,terminal] ----- -# subscription-manager register ----- - -. Attach a subscription to the RHEL 8 system: -+ -[source,terminal] ----- -# subscription-manager attach --auto ----- - -. Install software that is required to build the software and container: -+ -[source,terminal] ----- -# yum install podman make git -y ----- - -. Clone the `kmod-via-containers` repository: -.. Create a folder for the repository: -+ -[source,terminal] ----- -$ mkdir kmods; cd kmods ----- - -.. Clone the repository: -+ -[source,terminal] ----- -$ git clone https://github.com/kmods-via-containers/kmods-via-containers ----- - -. Install a KVC framework instance on your RHEL 8 build host to test the module. -This adds a `kmods-via-container` systemd service and loads it: - -.. Change to the `kmod-via-containers` directory: -+ -[source,terminal] ----- -$ cd kmods-via-containers/ ----- - -.. Install the KVC framework instance: -+ -[source,terminal] ----- -$ sudo make install ----- - -.. Reload the systemd manager configuration: -+ -[source,terminal] ----- -$ sudo systemctl daemon-reload ----- - -. Get the kernel module source code. The source code might be used to -build a third-party module that you do not -have control over, but is supplied by others. You will need content -similar to the content shown in the `kvc-simple-kmod` example that can -be cloned to your system as follows: -+ -[source,terminal] ----- -$ cd .. ; git clone https://github.com/kmods-via-containers/kvc-simple-kmod ----- - -. Edit the configuration file, `simple-kmod.conf` file, in this example, and -change the name of the Dockerfile to `Dockerfile.rhel`: - -.. Change to the `kvc-simple-kmod` directory: -+ -[source,terminal] ----- -$ cd kvc-simple-kmod ----- - -.. Rename the Dockerfile: -+ -[source,terminal] ----- -$ cat simple-kmod.conf ----- -+ -.Example Dockerfile -[source,terminal] ----- -KMOD_CONTAINER_BUILD_CONTEXT="https://github.com/kmods-via-containers/kvc-simple-kmod.git" -KMOD_CONTAINER_BUILD_FILE=Dockerfile.rhel -KMOD_SOFTWARE_VERSION=dd1a7d4 -KMOD_NAMES="simple-kmod simple-procfs-kmod" ----- - -. Create an instance of `kmods-via-containers@.service` for your kernel module, -`simple-kmod` in this example: -+ -[source,terminal] ----- -$ sudo make install ----- - -. Enable the `kmods-via-containers@.service` instance: -+ -[source,terminal] ----- -$ sudo kmods-via-containers build simple-kmod $(uname -r) ----- - -. Enable and start the systemd service: -.. Enable the service: -+ -[source,terminal] ----- -$ sudo systemctl enable kmods-via-containers@simple-kmod.service ----- - -.. Start the service: -+ -[source,terminal] ----- -$ sudo systemctl start kmods-via-containers@simple-kmod.service ----- - -.. Review the service status: -+ -[source,terminal] ----- -$ sudo systemctl status kmods-via-containers@simple-kmod.service ----- -+ -.Example output -[source,terminal] ----- -● kmods-via-containers@simple-kmod.service - Kmods Via Containers - simple-kmod - Loaded: loaded (/etc/systemd/system/kmods-via-containers@.service; - enabled; vendor preset: disabled) - Active: active (exited) since Sun 2020-01-12 23:49:49 EST; 5s ago... ----- - -. To confirm that the kernel modules are loaded, use the `lsmod` command to list the modules: -+ -[source,terminal] ----- -$ lsmod | grep simple_ ----- -+ -.Example output -[source,terminal] ----- -simple_procfs_kmod 16384 0 -simple_kmod 16384 0 ----- - -. Optional. Use other methods to check that the `simple-kmod` example is working: -** Look for a "Hello world" message in the kernel ring buffer with `dmesg`: -+ -[source,terminal] ----- -$ dmesg | grep 'Hello world' ----- -+ -.Example output -[source,terminal] ----- -[ 6420.761332] Hello world from simple_kmod. ----- - -** Check the value of `simple-procfs-kmod` in `/proc`: -+ -[source,terminal] ----- -$ sudo cat /proc/simple-procfs-kmod ----- -+ -.Example output -[source,terminal] ----- -simple-procfs-kmod number = 0 ----- - -** Run the `spkut` command to get more information from the module: -+ -[source,terminal] ----- -$ sudo spkut 44 ----- -+ -.Example output -[source,terminal] ----- -KVC: wrapper simple-kmod for 4.18.0-147.3.1.el8_1.x86_64 -Running userspace wrapper using the kernel module container... -+ podman run -i --rm --privileged - simple-kmod-dd1a7d4:4.18.0-147.3.1.el8_1.x86_64 spkut 44 -simple-procfs-kmod number = 0 -simple-procfs-kmod number = 44 ----- - -Going forward, when the system boots this service will check if a new -kernel is running. If there is a new kernel, the service builds a new -version of the kernel module and then loads it. If the module is already -built, it will just load it. - -[id="provisioning-kernel-module-to-ocp_{context}"] -== Provisioning a kernel module to {product-title} - -Depending on whether or not you must have the kernel module in place -when {product-title} cluster first boots, you can set up the -kernel modules to be deployed in one of two ways: - -* **Provision kernel modules at cluster install time (day-1)**: -You can create the content as a `MachineConfig` object and provide it to `openshift-install` -by including it with a set of manifest files. - -* **Provision kernel modules via Machine Config Operator (day-2)**: If you can wait until the -cluster is up and running to add your kernel module, you can deploy the kernel -module software via the Machine Config Operator (MCO). - -In either case, each node needs to be able to get the kernel packages and related -software packages at the time that a new kernel is detected. There are a few ways -you can set up each node to be able to obtain that content. - -* Provide RHEL entitlements to each node. -* Get RHEL entitlements from an existing RHEL host, from the `/etc/pki/entitlement` directory -and copy them to the same location as the other files you provide -when you build your Ignition config. -* Inside the Dockerfile, add pointers to a `yum` repository containing the kernel and other packages. -This must include new kernel packages as they are needed to match newly installed kernels. - -[id="provision-kernel-modules-via-machineconfig_{context}"] -=== Provision kernel modules via a `MachineConfig` object - -By packaging kernel module software with a `MachineConfig` object, you can -deliver that software to worker or master nodes at installation time -or via the Machine Config Operator. - -First create a base Ignition config that you would like to use. -At installation time, the Ignition config will -contain the ssh public key to add to the `authorized_keys` file for -the `core` user on the cluster. -To add the `MachineConfig` object later via the MCO instead, the SSH public key is not required. -For both type, the example simple-kmod service creates a systemd unit file, -which requires a `kmods-via-containers@simple-kmod.service`. - -[NOTE] -==== -The systemd unit is a workaround for an -link:https://github.com/coreos/ignition/issues/586[upstream bug] -and makes sure that the `kmods-via-containers@simple-kmod.service` gets started -on boot: -==== - -. Register a RHEL 8 system: -+ -[source,terminal] ----- -# subscription-manager register ----- - -. Attach a subscription to the RHEL 8 system: -+ -[source,terminal] ----- -# subscription-manager attach --auto ----- - -. Install software needed to build the software: -+ -[source,terminal] ----- -# yum install podman make git -y ----- - -. Create an Ignition config file that creates a systemd unit file: -.. Create a directory to host the Ignition config file: -+ -[source,terminal] ----- -$ mkdir kmods; cd kmods ----- - -.. Create the Ignition config file that creates a systemd unit file: -+ -[source,terminal] ----- -$ cat <<EOF > ./baseconfig.ign -{ - "ignition": { "version": "3.2.0" }, - "passwd": { - "users": [ - { - "name": "core", - "groups": ["sudo"], - "sshAuthorizedKeys": [ - "ssh-rsa AAAA" - ] - } - ] - }, - "systemd": { - "units": [{ - "name": "require-kvc-simple-kmod.service", - "enabled": true, - "contents": "[Unit]\nRequires=kmods-via-containers@simple-kmod.service\n[Service]\nType=oneshot\nExecStart=/usr/bin/true\n\n[Install]\nWantedBy=multi-user.target" - }] - } -} -EOF ----- -+ -[NOTE] -==== -You must add your public SSH key to the `baseconfig.ign` file -to use the file during `openshift-install`. -The public SSH key is not needed if you create the `MachineConfig` object using the MCO. -==== - -. Create a base MCO YAML snippet that uses the following configuration: -+ -[source,terminal] ----- -$ cat <<EOF > mc-base.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: 10-kvc-simple-kmod -spec: - config: -EOF ----- -+ -[NOTE] -==== -The `mc-base.yaml` is set to deploy the kernel module on `worker` nodes. -To deploy on master nodes, change the role from `worker` to `master`. -To do both, you could repeat the whole procedure using different file names -for the two types of deployments. -==== - -. Get the `kmods-via-containers` software: - -.. Clone the `kmods-via-containers` repository: -+ -[source,terminal] ----- -$ git clone https://github.com/kmods-via-containers/kmods-via-containers ----- - -.. Clone the `kvc-simple-kmod` repository: -+ -[source,terminal] ----- -$ git clone https://github.com/kmods-via-containers/kvc-simple-kmod ----- - -. Get your module software. In this example, `kvc-simple-kmod` is used: - -. Create a fakeroot directory and populate it with files that you want to -deliver via Ignition, using the repositories cloned earlier: - -.. Create the directory: -+ -[source,terminal] ----- -$ FAKEROOT=$(mktemp -d) ----- - -.. Change to the `kmod-via-containers` directory: -+ -[source,terminal] ----- -$ cd kmods-via-containers ----- - -.. Install the KVC framework instance: -+ -[source,terminal] ----- -$ make install DESTDIR=${FAKEROOT}/usr/local CONFDIR=${FAKEROOT}/etc/ ----- - -.. Change to the `kvc-simple-kmod` directory: -+ -[source,terminal] ----- -$ cd ../kvc-simple-kmod ----- - -.. Create the instance: -+ -[source,terminal] ----- -$ make install DESTDIR=${FAKEROOT}/usr/local CONFDIR=${FAKEROOT}/etc/ ----- - -. Get a tool called `filetranspiler` and dependent software: -+ -[source,terminal] ----- -$ cd .. ; sudo yum install -y python3 -git clone https://github.com/ashcrow/filetranspiler.git ----- - -. Generate a final machine config YAML (`mc.yaml`) -and have it include the base Ignition config, base machine config, and the fakeroot directory -with files you would like to deliver: -+ -[source,terminal] ----- -$ ./filetranspiler/filetranspile -i ./baseconfig.ign \ - -f ${FAKEROOT} --format=yaml --dereference-symlinks \ - | sed 's/^/ /' | (cat mc-base.yaml -) > 99-simple-kmod.yaml ----- - -. If the cluster is not up yet, generate manifest files and add this file to the -`openshift` directory. If the cluster is already running, apply the file as follows: -+ -[source,terminal] ----- -$ oc create -f 99-simple-kmod.yaml ----- -+ -Your nodes will start the `kmods-via-containers@simple-kmod.service` -service and the kernel modules will be loaded. - -. To confirm that the kernel modules are loaded, you can log in to a node -(using `oc debug node/<openshift-node>`, then `chroot /host`). -To list the modules, use the `lsmod` command: -+ -[source,terminal] ----- -$ lsmod | grep simple_ ----- -+ -.Example output -[source,terminal] ----- -simple_procfs_kmod 16384 0 -simple_kmod 16384 0 ----- diff --git a/modules/installation-special-config-mirrored-disk.adoc b/modules/installation-special-config-mirrored-disk.adoc deleted file mode 100644 index 1fe8a651b57c..000000000000 --- a/modules/installation-special-config-mirrored-disk.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-customizing.adoc - -[id="installation-special-config-mirrored-disk_{context}"] -= Mirroring disks during installation - -During {product-title} installation on master and worker nodes, you can enable mirroring of the boot disk to two or more redundant storage devices. A node continues to function after storage device failure as long as one device remains available. - -Mirroring does not support replacement of a failed disk. To restore the mirror to a pristine, non-degraded state, reprovision the node. - -[IMPORTANT] -==== -Mirroring is available only for user-provisioned infrastructure deployments on {op-system-first} systems. Mirroring support is available on x86_64 nodes booted with BIOS or UEFI and on ppc64le nodes. -==== - -.Procedure - -To enable boot disk mirroring during {product-title} deployment: - -. Follow the bare metal install procedure up to the point where you created Ignition configs for your installation. -+ -For example, you should have entered the following command: -+ -[source,terminal] ----- -$ openshift-install create ignition-configs --dir $HOME/clusterconfig ----- -+ -. Verify that the Ignition config files were created: -+ -[source,terminal] ----- -$ ls $HOME/clusterconfig/ ----- -+ -[source,terminal] -.Example output ----- -auth bootstrap.ign master.ign metadata.json worker.ign ----- - -. Create a {op-system} Config (RCC) with a reference to your `master.ign` or `worker.ign` config, depending on the type of node you are configuring. The RCC must specify the devices to be used for boot disk mirroring. If you want LUKS encryption on the mirrored root filesystem, you must configure it in this RCC. -+ -The following RCC example demonstrates how to create `$HOME/clusterconfig/worker-raid.rcc`: -+ -[source,yaml] -.RCC example ----- -variant: rhcos -version: 0.1.0 -ignition: - config: - merge: - - local: worker.ign <1> -boot_device: - mirror: - devices: <2> - - /dev/sda - - /dev/sdb - luks: <3> - tpm2: true <4> - tang: <5> - - url: https://tang.example.com - thumbprint: <tang_thumbprint> -storage: <6> - luks: - - name: root - options: [--cipher, aes-cbc-essiv:sha256] ----- -+ -<1> Use the name of the Ignition config for your node type. -<2> List all disk devices that should be included in the boot disk mirror, including the disk that {op-system} will be installed onto. -<3> Include this section if you want to encrypt the root filesystem. See "Encrypting disks during installation" for more details. -<4> Include this field if you want to use a Trusted Platform Module (TPM) to encrypt the root filesystem. See "Enabling TPM v2 disk encryption" for more details. -<5> Include this section if you want to use a Tang server. To obtain the server URL and thumbprint, follow the instructions in "Enabling Tang disk encryption". -<6> Include this section if you want to encrypt the root filesystem. -+ -. Run the Fedora CoreOS Config Transpiler (FCCT) tool to merge your RCC, such as `worker-raid.rcc`, with the Ignition config specified in the RCC that you created in the previous step: -+ -[source,terminal] ----- -$ podman run --pull=always --rm --volume $HOME/clusterconfig:/pwd --workdir /pwd \ - quay.io/coreos/fcct:release --files-dir . worker-raid.rcc --output worker-raid.ign ----- -+ -This command produces a combined Ignition config in `$HOME/clusterconfig/worker-raid.ign`. -+ -. Continue with the remainder of the {product-title} deployment, using the combined Ignition config to provision nodes. diff --git a/modules/installation-special-config-rtkernel.adoc b/modules/installation-special-config-rtkernel.adoc deleted file mode 100644 index 099f2b915e4e..000000000000 --- a/modules/installation-special-config-rtkernel.adoc +++ /dev/null @@ -1,127 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/install_config/installing-customizing.adoc - -[id="installation-special-config-rtkernel_{context}"] - -= Adding a real-time kernel to nodes (during installation) - -Some {product-title} workloads require a high degree of determinism. -While Linux is not a real-time operating system, the Linux real-time -kernel includes a preemptive scheduler that provides the operating -system with real-time characteristics. - -If your {product-title} workloads require these real-time characteristics, -you can set up your compute (worker) and/or master machines to use the -Linux real-time kernel when you first install the cluster. To do this, -create a `MachineConfig` object and inject that object into the set of manifest -files used by Ignition during cluster setup, as described in the following -procedure. - -[NOTE] -==== -This procedure is fully supported with bare metal installations using -systems that are certified for Red Hat Enterprise Linux for Real Time 8. -Real time support in {product-title} is also limited to specific subscriptions. -This procedure is also supported for use with Google Cloud Platform. -==== - -.Prerequisites -* For a bare metal installation of {product-title}, prepare masters and workers. -* Use {product-title} version 4.4 or later. - -.Procedure - -. Create the `intall-config.yaml` file using the installer or prepare it manually. -To create it using installer, run: -+ -[source,terminal] ----- -$ ./openshift-install create install-config --dir=<installation_directory> ----- - -. Generate the Kubernetes manifests for the cluster: -+ -[source,terminal] ----- -$ ./openshift-install create manifests --dir=<installation_directory> ----- - -. Decide if you want to add the real-time kernel to worker or master nodes. - -. In the `openshift` directory, create a file (for example, -`99-worker-realtime.yaml`) to define a `MachineConfig` object that applies a -real-time kernel to the selected nodes (worker nodes in this case): -+ -[source,terminal] ----- -$ cat << EOF > 99-worker-realtime.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: "worker" - name: 99-worker-realtime -spec: - kernelType: realtime -EOF ----- -+ -You can change `worker` to `master` to add kernel arguments to master nodes instead. -Create a separate YAML file to add to both master and worker nodes. - -. Create the cluster. You can now continue on to create the {product-title} cluster. -+ -[source,terminal] ----- -$ ./openshift-install create cluster --dir=<installation_directory> ----- - -. Check the real-time kernel: Once the cluster comes up, log in to the cluster -and run the following commands to make sure that the real-time kernel has -replaced the regular kernel for the set of worker or master nodes you -configured: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-139-200.us-east-2.compute.internal Ready master 111m v1.20.0 -ip-10-0-143-147.us-east-2.compute.internal Ready worker 103m v1.20.0 -ip-10-0-146-92.us-east-2.compute.internal Ready worker 101m v1.20.0 -ip-10-0-156-255.us-east-2.compute.internal Ready master 111m v1.20.0 -ip-10-0-164-74.us-east-2.compute.internal Ready master 111m v1.20.0 -ip-10-0-169-2.us-east-2.compute.internal Ready worker 102m v1.20.0 ----- -+ -[source,terminal] ----- -$ oc debug node/ip-10-0-143-147.us-east-2.compute.internal ----- -+ -.Example output -[source,terminal] ----- -Starting pod/ip-10-0-143-147us-east-2computeinternal-debug ... -To use host binaries, run `chroot /host` ----- -+ -[source,terminal] ----- -sh-4.4# uname -a ----- -+ -.Example output -[source,terminal] ----- -Linux <worker_node> 4.18.0-147.3.1.rt24.96.el8_1.x86_64 #1 SMP PREEMPT RT - Wed Nov 27 18:29:55 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux ----- -+ -The kernel name contains `rt` and text `PREEMPT RT` indicates that this is a -real-time kernel. diff --git a/modules/installation-three-node-cluster.adoc b/modules/installation-three-node-cluster.adoc deleted file mode 100644 index dd642285b40c..000000000000 --- a/modules/installation-three-node-cluster.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc [Eventually] -// * installing/installing_azure/installing-azure-user-infra.adoc [Eventually] -// * installing/installing_gcp/installing-gcp-user-infra.adoc [Eventually] -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc [Eventually] -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc [Eventually] -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc [Eventually] -// * installing/installing_vsphere/installing-vsphere.adoc [Eventually] -// * installing/installing_ibm_z/installing-ibm-z.adoc [Eventually] - -[id="installation-three-node-cluster_{context}"] -= Configuring a three-node cluster - -You can optionally install and run three-node clusters in {product-title} with no workers. This provides smaller, more resource efficient clusters for cluster administrators and developers to use for development, production, and testing. - -.Procedure - -* Edit the `install-config.yaml` file to set the number of compute replicas, which are also known as worker replicas, to `0`, as shown in the following `compute` stanza: -+ -[source,yaml] ----- -compute: -- name: worker - platform: {} - replicas: 0 ----- diff --git a/modules/installation-uninstall-clouds.adoc b/modules/installation-uninstall-clouds.adoc deleted file mode 100644 index 89f570bfb7b9..000000000000 --- a/modules/installation-uninstall-clouds.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/uninstalling-cluster-aws.adoc -// * installing/installing_azure/uninstalling-cluster-azure.adoc -// * installing/installing_gcp/uninstalling-cluster-gcp.adoc -// * installing/installing_osp/uninstalling-cluster-openstack.adoc -// * installing/installing_rhv/uninstalling-cluster-rhv.adoc -// * installing/installing_vmc/uninstalling-cluster-vmc.adoc -// * installing/installing_vsphere/uninstalling-cluster-vsphere-installer-provisioned.adoc - -ifeval::["{context}" == "uninstalling-cluster-aws"] -:aws: -endif::[] - -[id="installation-uninstall-clouds_{context}"] -= Removing a cluster that uses installer-provisioned infrastructure - -You can remove a cluster that uses installer-provisioned infrastructure from -your cloud. - -ifdef::aws[] -[NOTE] -==== -If you deployed your cluster to the AWS C2S Secret Region, the installation program does not support destroying the cluster; you must manually remove the cluster resources. -==== -endif::aws[] - -.Prerequisites - -* Have a copy of the installation program that you used to deploy the cluster. -* Have the files that the installation program generated when you created your -cluster. - -.Procedure - -. From the directory that contains the installation program on the computer that you used to install the cluster, run the following command: -+ -[source,terminal] ----- -$ ./openshift-install destroy cluster \ ---dir=<installation_directory> --log-level=info <1> <2> ----- -<1> For `<installation_directory>`, specify the path to the directory that you -stored the installation files in. -<2> To view different details, specify `warn`, `debug`, or `error` instead of `info`. -+ -[NOTE] -==== -You must specify the directory that contains the cluster definition files for -your cluster. The installation program requires the `metadata.json` file in this -directory to delete the cluster. -==== - -. Optional: Delete the `<installation_directory>` directory and the -{product-title} installation program. diff --git a/modules/installation-uninstall-infra.adoc b/modules/installation-uninstall-infra.adoc deleted file mode 100644 index 0d8b1acfb4c7..000000000000 --- a/modules/installation-uninstall-infra.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_openstack/uninstalling-openstack-user.adoc - -[id="installation-uninstall-infra_{context}"] -= Removing a cluster from {rh-openstack} that uses your own infrastructure - -You can remove an {product-title} cluster on {rh-openstack-first} that uses your own infrastructure. To complete the removal process quickly, run several Ansible playbooks. - -.Prerequisites - -* Python 3 is installed on your machine. -* You downloaded the modules in "Downloading playbook dependencies." -* You have the playbooks that you used to install the cluster. -* You modified the playbooks that are prefixed with `down-` to reflect any changes that you made to their corresponding installation playbooks. For example, changes to the `bootstrap.yaml` file are reflected in the `down-bootstrap.yaml` file. -* All of the playbooks are in a common directory. - -.Procedure - -. On a command line, run the playbooks that you downloaded: -+ -[source,terminal] ----- -$ ansible-playbook -i inventory.yaml \ - down-bootstrap.yaml \ - down-control-plane.yaml \ - down-compute-nodes.yaml \ - down-load-balancers.yaml \ - down-network.yaml \ - down-security-groups.yaml ----- - -. Remove any DNS record changes you made for the {product-title} installation. - -{product-title} is removed from your infrastructure. \ No newline at end of file diff --git a/modules/installation-user-infra-exporting-common-variables-arm-templates.adoc b/modules/installation-user-infra-exporting-common-variables-arm-templates.adoc deleted file mode 100644 index 6fa56bf527c1..000000000000 --- a/modules/installation-user-infra-exporting-common-variables-arm-templates.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-user-infra.adoc - -[id="installation-user-infra-exporting-common-variables-arm-templates_{context}"] -= Exporting common variables for ARM templates - -You must export a common set of variables that are used with the provided Azure -Resource Manager (ARM) templates used to assist in completing a user-provided -infrastructure install on Microsoft Azure. - -[NOTE] -==== -Specific ARM templates can also require additional exported variables, which are -detailed in their related procedures. -==== - -.Prerequisites - -* Obtain the {product-title} installation program and the pull secret for your cluster. - -.Procedure - -. Export common variables found in the `install-config.yaml` to be used by the -provided ARM templates: -+ -[source,terminal] ----- -$ export CLUSTER_NAME=<cluster_name><1> -$ export AZURE_REGION=<azure_region><2> -$ export SSH_KEY=<ssh_key><3> -$ export BASE_DOMAIN=<base_domain><4> -$ export BASE_DOMAIN_RESOURCE_GROUP=<base_domain_resource_group><5> ----- -<1> The value of the `.metadata.name` attribute from the `install-config.yaml` file. -<2> The region to deploy the cluster into, for example `centralus`. This is the value of the `.platform.azure.region` attribute from the `install-config.yaml` file. -<3> The SSH RSA public key file as a string. You must enclose the SSH key in quotes since it contains spaces. This is the value of the `.sshKey` attribute from the `install-config.yaml` file. -<4> The base domain to deploy the cluster to. The base domain corresponds to the public DNS zone that you created for your cluster. This is the value of the `.baseDomain` attribute from the `install-config.yaml` file. -<5> The resource group where the public DNS zone exists. This is the value of the `.platform.azure.baseDomainResourceGroupName` attribute from the `install-config.yaml` file. -+ -For example: -+ -[source,terminal] ----- -$ export CLUSTER_NAME=test-cluster -$ export AZURE_REGION=centralus -$ export SSH_KEY="ssh-rsa xxx/xxx/xxx= user@email.com" -$ export BASE_DOMAIN=example.com -$ export BASE_DOMAIN_RESOURCE_GROUP=ocp-cluster ----- - -. Export the kubeadmin credentials: -+ -[source,terminal] ----- -$ export KUBECONFIG=<installation_directory>/auth/kubeconfig <1> ----- -<1> For `<installation_directory>`, specify the path to the directory that you stored the installation files in. diff --git a/modules/installation-user-infra-exporting-common-variables.adoc b/modules/installation-user-infra-exporting-common-variables.adoc deleted file mode 100644 index a944fbf61ca8..000000000000 --- a/modules/installation-user-infra-exporting-common-variables.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-gcp-user-infra"] -:cp-first: Google Cloud Platform -:cp: GCP -:cp-template: Deployment Manager -endif::[] - -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:cp-first: Google Cloud Platform -:cp: GCP -:cp-template: Deployment Manager -endif::[] - -ifeval::["{context}" == "installing-restricted-networks-gcp-vpc"] -:cp-first: Google Cloud Platform -:cp: GCP -:cp-template: Deployment Manager -endif::[] - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:cp-first: Google Cloud Platform -:cp: GCP -:cp-template: Deployment Manager -:shared-vpc: -endif::[] - -[id="installation-user-infra-exporting-common-variables_{context}"] -= Exporting common variables for {cp-template} templates - -You must export a common set of variables that are used with the provided -{cp-template} templates used to assist in completing a user-provided -infrastructure install on {cp-first} ({cp}). - -[NOTE] -==== -Specific {cp-template} templates can also require additional exported -variables, which are detailed in their related procedures. -==== - -.Prerequisites - -* Obtain the {product-title} installation program and the pull secret for your cluster. -* Generate the Ignition config files for your cluster. -* Install the `jq` package. - -.Procedure - -. Export the following common variables to be used by the provided {cp-template} -templates: -+ -ifndef::shared-vpc[] -[source,terminal] ----- -$ export BASE_DOMAIN='<base_domain>' -$ export BASE_DOMAIN_ZONE_NAME='<base_domain_zone_name>' -$ export NETWORK_CIDR='10.0.0.0/16' -$ export MASTER_SUBNET_CIDR='10.0.0.0/19' -$ export WORKER_SUBNET_CIDR='10.0.32.0/19' - -$ export KUBECONFIG=<installation_directory>/auth/kubeconfig <1> -$ export CLUSTER_NAME=`jq -r .clusterName <installation_directory>/metadata.json` -$ export INFRA_ID=`jq -r .infraID <installation_directory>/metadata.json` -$ export PROJECT_NAME=`jq -r .gcp.projectID <installation_directory>/metadata.json` -$ export REGION=`jq -r .gcp.region <installation_directory>/metadata.json` ----- -<1> For `<installation_directory>`, specify the path to the directory that you stored the installation files in. -endif::shared-vpc[] -//you need some of these variables for the VPC, and you do that - -ifdef::shared-vpc[] -[source,terminal] ----- -$ export BASE_DOMAIN='<base_domain>' <1> -$ export BASE_DOMAIN_ZONE_NAME='<base_domain_zone_name>' <1> -$ export NETWORK_CIDR='10.0.0.0/16' - -$ export KUBECONFIG=<installation_directory>/auth/kubeconfig <2> -$ export CLUSTER_NAME=`jq -r .clusterName <installation_directory>/metadata.json` -$ export INFRA_ID=`jq -r .infraID <installation_directory>/metadata.json` -$ export PROJECT_NAME=`jq -r .gcp.projectID <installation_directory>/metadata.json` ----- -<1> Supply the values for the host project. -<2> For `<installation_directory>`, specify the path to the directory that you stored the installation files in. -endif::shared-vpc[] - -ifeval::["{context}" == "installing-gcp-user-infra"] -:!cp-first: -:!cp: -:!cp-template: -endif::[] - -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:!cp-first: -:!cp: -:!cp-template: -endif::[] - -ifeval::["{context}" == "installing-restricted-networks-gcp-vpc"] -:!cp-first: Google Cloud Platform -:!cp: GCP -:!cp-template: Deployment Manager -endif::[] - -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!cp-first: Google Cloud Platform -:!cp: GCP -:!cp-template: Deployment Manager -:!shared-vpc: -endif::[] diff --git a/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc b/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc deleted file mode 100644 index 74e8c185dd36..000000000000 --- a/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc +++ /dev/null @@ -1,360 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing_openstack/installing-openstack-user.adoc - - -ifeval::["{context}" == "installing-aws-user-infra"] -:aws: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-aws"] -:aws: -:restricted: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:azure: -:azure-user-infra: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:vsphere: -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:vmc: -:restricted: -endif::[] -ifeval::["{context}" == "installing-bare-metal"] -:baremetal: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:baremetal-restricted: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra"] -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:gcp: -:user-infra-vpc: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:gcp: -:restricted: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:osp: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:osp: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-user-infra"] -:vmc: -endif::[] -ifeval::["{context}" == "installing-platform-agnostic"] -:baremetal: -endif::[] - -[id="installation-user-infra-generate-k8s-manifest-ignition_{context}"] -= Creating the Kubernetes manifest and Ignition config files - -Because you must modify some cluster definition files and manually start the cluster machines, you must generate the Kubernetes manifest and Ignition config files that the cluster needs to make its machines. - -The installation configuration file transforms into the Kubernetes manifests. The manifests wrap into the Ignition configuration files, which are later used to create the cluster. - -[IMPORTANT] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== - -.Prerequisites - -* You obtained the {product-title} installation program. -ifdef::restricted,baremetal-restricted[] -For a restricted network installation, these files are on your mirror host. -endif::restricted,baremetal-restricted[] -* You created the `install-config.yaml` installation configuration file. - -.Procedure - -. Change to the directory that contains the installation program and generate the Kubernetes manifests for the cluster: -+ -[source,terminal] ----- -$ ./openshift-install create manifests --dir=<installation_directory> <1> ----- -+ -.Example output -[source,terminal] ----- -INFO Credentials loaded from the "myprofile" profile in file "/home/myuser/.aws/credentials" -INFO Consuming Install Config from target directory -INFO Manifests created in: install_dir/manifests and install_dir/openshift ----- -<1> For `<installation_directory>`, specify the installation directory that -contains the `install-config.yaml` file you created. - -ifdef::aws,azure,gcp[] -. Remove the Kubernetes manifest files that define the control plane machines: -+ -[source,terminal] ----- -$ rm -f <installation_directory>/openshift/99_openshift-cluster-api_master-machines-*.yaml ----- -+ -By removing these files, you prevent the cluster from automatically generating control plane machines. -endif::aws,azure,gcp[] - -ifdef::gcp[] -ifndef::user-infra-vpc[] -. Optional: If you do not want the cluster to provision compute machines, remove -the Kubernetes manifest files that define the worker machines: -endif::user-infra-vpc[] -endif::gcp[] -ifdef::aws,azure,user-infra-vpc[] -. Remove the Kubernetes manifest files that define the worker machines: -endif::aws,azure,user-infra-vpc[] -ifdef::aws,azure,gcp[] -+ -[source,terminal] ----- -$ rm -f <installation_directory>/openshift/99_openshift-cluster-api_worker-machineset-*.yaml ----- -+ -Because you create and manage the worker machines yourself, you do not need -to initialize these machines. -endif::aws,azure,gcp[] - -ifdef::osp,vsphere,vmc[] -. Remove the Kubernetes manifest files that define the control plane machines and compute machine sets: -+ -[source,terminal] ----- -$ rm -f openshift/99_openshift-cluster-api_master-machines-*.yaml openshift/99_openshift-cluster-api_worker-machineset-*.yaml ----- -+ -Because you create and manage these resources yourself, you do not have -to initialize them. -+ -* You can preserve the machine set files to create compute machines by using the machine API, but you must update references to them to match your environment. -endif::osp,vsphere,vmc[] - -ifdef::baremetal,baremetal-restricted[] -[WARNING] -==== -If you are running a three-node cluster, skip the following step to allow the masters to be schedulable. -==== -endif::baremetal,baremetal-restricted[] -. Check that the `mastersSchedulable` parameter in the `<installation_directory>/manifests/cluster-scheduler-02-config.yml` Kubernetes manifest file is set to `false`. This setting prevents pods from being scheduled on the control plane machines: -+ --- -.. Open the `<installation_directory>/manifests/cluster-scheduler-02-config.yml` file. -.. Locate the `mastersSchedulable` parameter and ensure that it is set to `false`. -.. Save and exit the file. --- - -ifdef::gcp,aws,azure[] -ifndef::user-infra-vpc[] -. Optional: If you do not want -link:https://github.com/openshift/cluster-ingress-operator[the Ingress Operator] -to create DNS records on your behalf, remove the `privateZone` and `publicZone` -sections from the `<installation_directory>/manifests/cluster-dns-02-config.yml` DNS configuration file: -endif::user-infra-vpc[] -ifdef::user-infra-vpc[] -. Remove the `privateZone` -sections from the `<installation_directory>/manifests/cluster-dns-02-config.yml` DNS configuration file: -endif::user-infra-vpc[] -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: DNS -metadata: - creationTimestamp: null - name: cluster -spec: - baseDomain: example.openshift.com - privateZone: <1> - id: mycluster-100419-private-zone -ifndef::user-infra-vpc[] - publicZone: <1> - id: example.openshift.com -endif::user-infra-vpc[] -status: {} ----- -<1> Remove this section completely. -+ -ifndef::user-infra-vpc[] -If you do so, you must add ingress DNS records manually in a later step. -endif::user-infra-vpc[] -endif::gcp,aws,azure[] - -ifdef::user-infra-vpc[] -. Configure the cloud provider for your VPC. -+ --- -.. Open the `<installation_directory>/manifests/cloud-provider-config.yaml` file. -.. Add the `network-project-id` parameter and set its value to the ID of project that hosts the shared VPC network. -.. Add the `network-name` parameter and set its value to the name of the shared VPC network that hosts the {product-title} cluster. -.. Replace the value of the `subnetwork-name` parameter with the value of the shared VPC subnet that hosts your compute machines. -+ --- -The contents of the `<installation_directory>/manifests/cloud-provider-config.yaml` resemble the following example: -+ -[source,yaml] ----- -config: |+ - [global] - project-id = example-project - regional = true - multizone = true - node-tags = opensh-ptzzx-master - node-tags = opensh-ptzzx-worker - node-instance-prefix = opensh-ptzzx - external-instance-groups-prefix = opensh-ptzzx - network-project-id = example-shared-vpc - network-name = example-network - subnetwork-name = example-worker-subnet ----- - -. If you deploy a cluster that is not on a private network, open the `<installation_directory>/manifests/cluster-ingress-default-ingresscontroller.yaml` file and replace the value of the `scope` parameter with `External`. The contents of the file resemble the following example: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - creationTimestamp: null - name: default - namespace: openshift-ingress-operator -spec: - endpointPublishingStrategy: - loadBalancer: - scope: External - type: LoadBalancerService -status: - availableReplicas: 0 - domain: '' - selector: '' ----- - -endif::user-infra-vpc[] - -ifdef::azure-user-infra[] -. When configuring Azure on user-provisioned infrastructure, you must export -some common variables defined in the manifest files to use later in the Azure -Resource Manager (ARM) templates: -.. Export the infrastructure ID by using the following command: -+ -[source,terminal] ----- -$ export INFRA_ID=<infra_id> <1> ----- -<1> The {product-title} cluster has been assigned an identifier (`INFRA_ID`) in the form of `<cluster_name>-<random_string>`. This will be used as the base name for most resources created using the provided ARM templates. This is the value of the `.status.infrastructureName` attribute from the `manifests/cluster-infrastructure-02-config.yml` file. - -.. Export the resource group by using the following command: -+ -[source,terminal] ----- -$ export RESOURCE_GROUP=<resource_group> <1> ----- -<1> All resources created in this Azure deployment exists as part of a link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups[resource group]. The resource group name is also based on the `INFRA_ID`, in the form of `<cluster_name>-<random_string>-rg`. This is the value of the `.status.platformStatus.azure.resourceGroupName` attribute from the `manifests/cluster-infrastructure-02-config.yml` file. -endif::azure-user-infra[] - -. To create the Ignition configuration files, run the following command from the directory that contains the installation program: -+ -[source,terminal] ----- -$ ./openshift-install create ignition-configs --dir=<installation_directory> <1> ----- -<1> For `<installation_directory>`, specify the same installation directory. -+ -The following files are generated in the directory: -+ ----- -. -├── auth -│ ├── kubeadmin-password -│ └── kubeconfig -├── bootstrap.ign -├── master.ign -├── metadata.json -└── worker.ign ----- - -ifdef::osp[] -. Export the metadata file's `infraID` key as an environment variable: -+ -[source,terminal] ----- -$ export INFRA_ID=$(jq -r .infraID metadata.json) ----- - -[TIP] -Extract the `infraID` key from `metadata.json` and use it as a prefix for all of the {rh-openstack} resources that you create. By doing so, you avoid name conflicts when making multiple deployments in the same project. -endif::osp[] - -ifeval::["{context}" == "installing-restricted-networks-aws"] -:!aws: -:!restricted: -endif::[] -ifeval::["{context}" == "installing-aws-user-infra"] -:!aws: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:!azure: -:!azure-user-infra: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra"] -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!gcp: -:!user-infra-vpc: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!vmc: -:!restricted: -endif::[] -ifeval::["{context}" == "installing-bare-metal"] -:!baremetal: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!baremetal-restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:!gcp: -:!restricted: -endif::[] -ifeval::["{context}" == "installing-osp-user"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-user-infra"] -:!vmc: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!vsphere: -:!restricted: -endif::[] -ifeval::["{context}" == "installing-platform-agnostic"] -:!baremetal: -endif::[] diff --git a/modules/installation-user-infra-generate.adoc b/modules/installation-user-infra-generate.adoc deleted file mode 100644 index 921a850006cb..000000000000 --- a/modules/installation-user-infra-generate.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_gcp/installing-gcp-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_gcp/installing-restricted-networks-gcp.adoc - -ifeval::["{context}" == "installing-restricted-networks-aws"] -:restricted: -:cp-first: Amazon Web Services -:cp: AWS -:aws: -endif::[] -ifeval::["{context}" == "installing-aws-user-infra"] -:cp-first: Amazon Web Services -:cp: AWS -:aws: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:cp-first: Microsoft Azure -:cp: Azure -:azure: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra"] -:cp-first: Google Cloud Platform -:cp: GCP -:gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:cp-first: Google Cloud Platform -:cp: GCP -:gcp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:cp-first: Google Cloud Platform -:cp: GCP -:gcp: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:cp-first: Red Hat OpenStack Platform -:cp: RHOSP -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:cp-first: Red Hat OpenStack Platform -:cp: RHOSP -endif::[] - -[id="installation-user-infra-generate_{context}"] -= Creating the installation files for {cp} - -ifdef::azure[] -To install {product-title} on {cp-first} using user-provisioned infrastructure, you must generate the files that the installation program needs to deploy your cluster and modify them so that the cluster creates only the machines that it will use. You generate and customize the `install-config.yaml` file, Kubernetes manifests, and Ignition config files. You also have the option to first set up a separate `var` partition during the preparation phases of installation. -endif::azure[] -ifdef::aws,gcp[] -To install {product-title} on {cp-first} ({cp}) using user-provisioned infrastructure, you must generate the files that the installation program needs to deploy your cluster and modify them so that the cluster creates only the machines that it will use. You generate and customize the `install-config.yaml` file, Kubernetes manifests, and Ignition config files. You also have the option to first set up a separate `var` partition during the preparation phases of installation. -endif::aws,gcp[] - -ifeval::["{context}" == "installing-restricted-networks-aws"] -:!restricted: -:!cp-first: -:!cp: -:!aws: -endif::[] -ifeval::["{context}" == "installing-aws-user-infra"] -:!cp-first: -:!cp: -:!aws: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:!cp-first: -:!cp: -:!azure: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra"] -:!cp-first: -:!cp: -:!gcp: -endif::[] -ifeval::["{context}" == "installing-gcp-user-infra-vpc"] -:!cp-first: Google Cloud Platform -:!cp: GCP -:!gcp: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-gcp"] -:!cp-first: -:!cp: -:!gcp: -endif::[] -ifeval::["{context}" == "installing-openstack-user"] -:!cp-first: Red Hat OpenStack Platform -:!cp: RHOSP -endif::[] -ifeval::["{context}" == "installing-openstack-user-kuryr"] -:!cp-first: Red Hat OpenStack Platform -:!cp: RHOSP -endif::[] diff --git a/modules/installation-user-infra-machines-advanced.adoc b/modules/installation-user-infra-machines-advanced.adoc deleted file mode 100644 index a35a2eb4de06..000000000000 --- a/modules/installation-user-infra-machines-advanced.adoc +++ /dev/null @@ -1,339 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing_bare_metal/installing-bare-metal-network-customizations.adoc - -[id="installation-user-infra-machines-advanced_{context}"] -= Advanced {op-system-first} installation configuration - -A key benefit for manually provisioning the {op-system-first} -nodes for {product-title} is to be able to do configuration that is not -available through default {product-title} installation methods. -This section describes some of the configurations that you can do using -techniques that include: - -* Passing kernel arguments to the live installer -* Running `coreos-installer` manually from the live system -* Embedding Ignition configs in an ISO - -The advanced configuration topics for manual {op-system-first} -installations detailed in this section relate to disk partitioning, networking, and using Ignition configs in different ways. - -[id="installation-user-infra-machines-advanced_network_{context}"] -== Using advanced networking options for PXE and ISO installations -Networking for {product-title} nodes uses DHCP by default to gather all -necessary configuration settings. To set up static IP addresses or configure special settings, such as bonding, you can do one of the following: - -* Pass special kernel parameters when you boot the live installer. - -* Use a machine config to copy networking files to the installed system. - -* Configure networking from a live installer shell prompt, then copy those settings to the installed system so that they take effect when the installed system first boots. - -To configure a PXE or iPXE installation, use one of the following options: - -* See the "Advanced RHCOS installation reference" tables. -* Use a machine config to copy networking files to the installed system. - -To configure an ISO installation, use the following procedure. - -.Procedure - -. Boot the ISO installer. -. From the live system shell prompt, configure networking for the live -system using available RHEL tools, such as `nmcli` or `nmtui`. -. Run the `coreos-installer` command to install the system, adding the `--copy-network` option to copy networking configuration. For example: -+ -[source,terminal] ----- -$ coreos-installer install --copy-network \ - --ignition-url=http://host/worker.ign /dev/sda ----- - -. Reboot into the installed system. - -[id="installation-user-infra-machines-advanced_disk_{context}"] -== Disk partitioning - -// This content is not modularized, so any updates to this "Disk partitioning" section should be checked against the module created for vSphere UPI parity in the module file named `installation-disk-partitioning.adoc` for consistency until such time as this large assembly can be modularized. - -In most cases, data partitions are originally created by installing {op-system}, rather than by installing another operating system. In such cases, the {product-title} installer should be allowed to configure your disk partitions. - -However, there are two cases where you might want to intervene to override the default partitioning when installing an -{product-title} node: - -* Create separate partitions: For greenfield installations on an empty -disk, you might want to add separate storage to a partition. This is -officially supported for making `/var` or a subdirectory of `/var`, such as `/var/lib/etcd`, a separate partition, but not both. -+ -[IMPORTANT] -==== -Kubernetes supports only two filesystem partitions. If you add more than one partition to the original configuration, Kubernetes cannot monitor all of them. -==== -* Retain existing partitions: For a brownfield installation where you are reinstalling {product-title} on an existing node and want to retain data partitions installed from your previous operating system, there are both boot arguments and options to `coreos-installer` that allow you to retain existing data partitions. - -[id="installation-user-infra-machines-advanced_vardisk_{context}"] -=== Creating a separate `/var` partition -In general, disk partitioning for {product-title} should be left to the -installer. However, there are cases where you might want to create separate partitions in a part of the filesystem that you expect to grow. - -{product-title} supports the addition of a single partition to attach -storage to either the `/var` partition or a subdirectory of `/var`. -For example: - -* `/var/lib/containers`: Holds container-related content that can grow -as more images and containers are added to a system. -* `/var/lib/etcd`: Holds data that you might want to keep separate for purposes such as performance optimization of etcd storage. -* `/var`: Holds data that you might want to keep separate for purposes such as auditing. - -Storing the contents of a `/var` directory separately makes it easier to grow storage for those areas as needed and reinstall {product-title} at a later date and keep that data intact. With this method, you will not have to pull all your containers again, nor will you have to copy massive log files when you update systems. - -Because `/var` must be in place before a fresh installation of -{op-system-first}, the following procedure sets up the separate `/var` partition -by creating a machine config that is inserted during the `openshift-install` -preparation phases of an {product-title} installation. - -.Procedure - -. Create a directory to hold the {product-title} installation files: -+ -[source,terminal] ----- -$ mkdir $HOME/clusterconfig ----- - -. Run `openshift-install` to create a set of files in the `manifest` and -`openshift` subdirectories. Answer the system questions as you are prompted: -+ -[source,terminal] ----- -$ openshift-install create manifests --dir $HOME/clusterconfig -? SSH Public Key ... -$ ls $HOME/clusterconfig/openshift/ -99_kubeadmin-password-secret.yaml -99_openshift-cluster-api_master-machines-0.yaml -99_openshift-cluster-api_master-machines-1.yaml -99_openshift-cluster-api_master-machines-2.yaml -... ----- - -. Create a `MachineConfig` object and add it to a file in the `openshift` directory. -For example, name the file `98-var-partition.yaml`, -change the disk device name to the name of the storage device on the `worker` systems, -and set the storage size as appropriate. This attaches storage to a separate `/var` -directory. - -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: 98-var-partition -spec: - config: - ignition: - version: 3.1.0 - storage: - disks: - - device: /dev/<device_name> <1> - partitions: - - sizeMiB: <partition_size> - startMiB: <partition_start_offset> <2> - label: var - filesystems: - - path: /var - device: /dev/disk/by-partlabel/var - format: xfs - systemd: - units: - - name: var.mount - enabled: true - contents: | - [Unit] - Before=local-fs.target - [Mount] - Where=/var - What=/dev/disk/by-partlabel/var - [Install] - WantedBy=local-fs.target ----- -+ -<1> The storage device name of the disk that you want to partition. -<2> When adding a data partition to the boot disk, a minimum value of 25000 mebibytes is recommended. The root file system is automatically resized to fill all available space up to the specified offset. If no value is specified, or if the specified value is smaller than the recommended minimum, the resulting root file system will be too small, and future reinstalls of {op-system} might overwrite the beginning of the data partition. - -. Run `openshift-install` again to create Ignition configs from a set of files in the `manifest` and -`openshift` subdirectories: -+ -[source,terminal] ----- -$ openshift-install create ignition-configs --dir $HOME/clusterconfig -$ ls $HOME/clusterconfig/ -auth bootstrap.ign master.ign metadata.json worker.ign ----- - -Now you can use the Ignition config files as input to the ISO or PXE manual installation procedures to install {op-system-first} systems. - -[id="installation-user-infra-machines-advanced_retaindisk_{context}"] -=== Retaining existing partitions -For an ISO installation, you can add options to the `coreos-installer` command line -that causes the installer to maintain one or more existing partitions. -For a PXE installation, you can `APPEND` `coreos.inst.*` options to preserve partitions. - -Saved partitions might be partitions from an existing {product-title} -system that has data partitions that you want to keep. Here are a few tips: - -* If you save existing partitions, and those partitions do not leave enough space for {op-system}, installation will fail without damaging the saved partitions. - -* Identify the disk partitions you want to keep either by partition -label or by number. - -.For an ISO installation - -This example preserves any partition in which the partition label begins with `data` (`data*`): - -[source,terminal] ----- -# coreos-installer install --ignition-url http://10.0.2.2:8080/user.ign \ - --save-partlabel 'data*' /dev/sda ----- - -The following example illustrates running the `coreos-installer` in a way that preserves -the sixth (6) partition on the disk: - -[source,terminal] ----- -# coreos-installer install --ignition-url http://10.0.2.2:8080/user.ign \ - --save-partindex 6 /dev/sda ----- - -This example preserves partitions 5 and higher: - -[source,terminal] ----- -# coreos-installer install --ignition-url http://10.0.2.2:8080/user.ign - --save-partindex 5- /dev/sda ----- - -In the previous examples where partition saving is used, `coreos-installer` recreates the partition immediately. - -.For a PXE installation - -This `APPEND` option preserves any partition in which the partition label begins with 'data' ('data*'): - -[source,terminal] ----- -coreos.inst.save_partlabel=data* ----- - -This `APPEND` option preserves partitions 5 and higher: - -[source,terminal] ----- -coreos.inst.save_partindex=5- ----- - -This `APPEND` option preserves partition 6: - -[source,terminal] ----- -coreos.inst.save_partindex=6 ----- - -[id="installation-user-infra-machines-advanced_ignition_{context}"] -== Identifying Ignition configs -When doing an {op-system} manual installation, there are two types of Ignition configs that you can provide, with different reasons for providing each one: - -* **Permanent install Ignition config**: Every manual {op-system} installation -needs to pass one of the Ignition config files generated by `openshift-installer`, -such as `bootstrap.ign`, `master.ign` and `worker.ign`, to carry out the -installation. -+ -[IMPORTANT] -==== -It is not recommended to modify these files. -==== -+ -For PXE installations, you pass the Ignition configs on the `APPEND` line using the -`coreos.inst.ignition_url=` option. For ISO installations, after the ISO boots to -the shell prompt, you identify the Ignition config on the `coreos-installer` -command line with the `--ignition-url=` option. In both cases, only HTTP and HTTPS -protocols are supported. -+ - -* **Live install Ignition config**: This type must be created manually and should be avoided if possible, as it is not supported by Red Hat. With this method, the Ignition config passes to the live install medium, runs immediately upon booting, and performs setup tasks before and/or after the {op-system} system installs to disk. This method should only be used for performing tasks that must be performed once and not applied again later, such as with advanced partitioning that cannot be done using a machine config. -+ -For PXE or ISO boots, you can create the Ignition config -and `APPEND` the `ignition.config.url=` option to identify the location of -the Ignition config. You also need to append `ignition.firstboot ignition.platform.id=metal` -or the `ignition.config.url` option will be ignored. - -[id="installation-user-infra-machines-advanced_embedignition_{context}"] -=== Embedding an Ignition config in the {op-system} ISO -You can embed a live install Ignition config directly in an {op-system} ISO image. When -the ISO image is booted, the embedded config will be applied automatically. - -[IMPORTANT] -==== -This type of configuration must be created manually and should be avoided if possible, as it is not supported by Red Hat. -==== - -.Procedure - -. Download the `coreos-installer` binary from the following image mirror page: https://mirror.openshift.com/pub/openshift-v4/clients/coreos-installer/latest/. - -. Retrieve the {op-system} ISO image and the Ignition config file, and copy them into an accessible directory, such as `/mnt`: -+ -[source,terminal] ----- -# cp rhcos-<version>-live.x86_64.iso live.ign /mnt/ -# chmod 644 /mnt/rhcos-<version>-live.x86_64.iso ----- - -. Run the following command to embed the Ignition config into the ISO: -+ -[source,terminal] ----- -# ./coreos-installer iso ignition embed -i /mnt/live.ign \ - /mnt/rhcos-<version>-live.x86_64.iso ----- -+ -You can now use that ISO to install {op-system} using the specified live install -Ignition config. -+ -[IMPORTANT] -==== -Using `coreos-installer iso ignition embed` to embed a file generated by `openshift-installer`, such as `bootstrap.ign`, `master.ign` and `worker.ign`, is unsupported and not recommended. -==== -+ -. To show the contents of the embedded Ignition config and direct it into a file, run: -+ -[source,terminal] ----- -# ./coreos-installer iso ignition show /mnt/rhcos-<version>-live.x86_64.iso > mylive.ign ----- -+ -[source,terminal] ----- -# diff -s live.ign mylive.ign ----- -+ -.Example output -[source,terminal] ----- -Files live.ign and mylive.ign are identical ----- - -. To remove the Ignition config and return the ISO to its pristine state so -you can reuse it, run: -+ -[source,terminal] ----- -# ./coreos-installer iso ignition remove /mnt/rhcos-<version>-live.x86_64.iso ----- -+ -You can now embed another Ignition config into the ISO or use the ISO in its -pristine state. diff --git a/modules/installation-user-infra-machines-iso.adoc b/modules/installation-user-infra-machines-iso.adoc deleted file mode 100644 index 024d208ae34d..000000000000 --- a/modules/installation-user-infra-machines-iso.adoc +++ /dev/null @@ -1,114 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc - -ifeval::["{context}" == "installing-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:ibm-power: -endif::[] - -[id="installation-user-infra-machines-iso_{context}"] -= Creating {op-system-first} machines using an ISO image - -Before you install a cluster on -ifdef::ibm-power[IBM Power Systems] -infrastructure that you provision, you must create -{op-system} machines for it to use. You can use an ISO image to create the -machines. - -.Prerequisites - -* Obtain the Ignition config files for your cluster. -* Have access to an HTTP server that can be accessed from your computer, and from the machines that you create. - -.Procedure - -. Upload the control plane, compute, and bootstrap Ignition config files that the -installation program created to your HTTP server. Note the URLs of these files. - -+ -[IMPORTANT] -==== -If you plan to add more compute machines to your cluster after you finish -installation, do not delete these files. -==== - -ifndef::openshift-origin[] -. Obtain the {op-system} images that are required for your preferred method -of installing operating system instances from the -ifndef::ibm-power[] -link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] -endif::ibm-power[] -ifdef::ibm-power[] -link:https://mirror.openshift.com/pub/openshift-v4/ppc64le/dependencies/rhcos/[{op-system} image mirror] -endif::ibm-power[] -page. -+ -[IMPORTANT] -==== -The {op-system} images might not change with every release of {product-title}. -You must download images with the highest version that is less than or equal -to the {product-title} version that you install. Use the image versions -that match your {product-title} version if they are available. -Use only ISO images for this procedure. -{op-system} qcow2 images are not supported for this installation type. -==== -+ -ISO file names resemble the following example: -+ -`rhcos-<version>-live.<architecture>.iso` -endif::openshift-origin[] -ifdef::openshift-origin[] -. Obtain the {op-system} images from the -link:https://getfedora.org/en/coreos/download?tab=metal_virtualized&stream=stable[{op-system} Downloads] page -endif::openshift-origin[] - -. Use the ISO to start the {op-system} installation. Use one of the following -installation options: -** Burn the ISO image to a disk and boot it directly. -** Use ISO redirection via a LOM interface. - -. Boot the ISO image. You can interrupt the installation boot process to -add kernel arguments. However, for this ISO procedure you should use -the `coreos-installer` command instead of adding kernel arguments. If you -run the live installer without options or interruption, the installer boots up to a -shell prompt on the live system, ready for you to install {op-system} to disk. - -. Review the _Advanced {op-system} installation reference_ -section for different ways of configuring features, such as networking -and disk partitions, before running the `coreos-installer`. - -. Run the `coreos-installer` command. At a minimum, you must identify -the Ignition config file location for your node type, and the -location of the disk you are installing to. Here is an example: -+ -[source,terminal] ----- -$ sudo coreos-installer install \ - --ignition-url=https://host/worker.ign /dev/sda ----- - -. After {op-system} installs, the system reboots. During the system reboot, -it applies the Ignition config file that you specified. - -. Continue to create the other machines for your cluster. -+ -[IMPORTANT] -==== -You must create the bootstrap and control plane machines at this time. If the -control plane machines are not made schedulable, which is the default, also -create at least two compute machines before you install the cluster. -==== - -ifeval::["{context}" == "installing-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:!ibm-power: -endif::[] diff --git a/modules/installation-user-infra-machines-pxe.adoc b/modules/installation-user-infra-machines-pxe.adoc deleted file mode 100644 index aa3d40c409f0..000000000000 --- a/modules/installation-user-infra-machines-pxe.adoc +++ /dev/null @@ -1,134 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc - -[id="installation-user-infra-machines-pxe_{context}"] -= Creating {op-system-first} machines by PXE or iPXE booting - -Before you install a cluster that uses manually-provisioned {op-system} nodes, such as bare metal, you must create {op-system} machines for it to use. You can use PXE or iPXE booting to create the machines. - -.Prerequisites - -* Obtain the Ignition config files for your cluster. -* Configure suitable PXE or iPXE infrastructure. -* Have access to an HTTP server that you can access from your computer. - -.Procedure - -. Upload the master, worker, and bootstrap Ignition config files that the -installation program created to your HTTP server. Note the URLs of these files. -+ -[IMPORTANT] -==== -You can add or change configuration settings in your Ignition configs -before saving them to your HTTP server. -If you plan to add more compute machines to your cluster after you finish -installation, do not delete these files. -==== - -ifndef::openshift-origin[] -. Obtain the {op-system} `kernel`, -`initramfs` and `rootfs` files from the -link:https://access.redhat.com/downloads/content/290[Product Downloads] page on the Red -Hat customer portal or the -link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/4.7/[{op-system} image mirror] -page. -+ -[IMPORTANT] -==== -The {op-system} artifacts might not change with every release of {product-title}. -You must download artifacts with the highest version that is less than or equal -to the {product-title} version that you install. Only use -the appropriate `kernel`, `initramfs`, and `rootfs` artifacts described below -for this procedure. -{op-system} qcow2 images are not supported for this installation type. -==== -+ -The file names contain the {product-title} version number. -They resemble the following examples: - -** `kernel`: `rhcos-<version>-live-kernel-<architecture>` -** `initramfs`: `rhcos-<version>-live-initramfs.<architecture>.img` -** `rootfs`: `rhcos-<version>-live-rootfs.<architecture>.img` -endif::openshift-origin[] -ifdef::openshift-origin[] -. Obtain the {op-system} `kernel`, `initramfs` and `rootfs` files from the -link:https://getfedora.org/en/coreos/download?tab=metal_virtualized&stream=stable[{op-system} Downloads] page -endif::openshift-origin[] - -. Upload the `rootfs`, `kernel`, and `initramfs` files -to your HTTP server. -+ -[IMPORTANT] -==== -If you plan to add more compute machines to your cluster after you finish -installation, do not delete these files. -==== - -. Configure the network boot infrastructure so that the machines boot from their -local disks after {op-system} is installed on them. - -. Configure PXE or iPXE installation for the {op-system} images. -+ -Modify one of the following example menu entries for your environment and verify -that the image and Ignition files are properly accessible: - -** For PXE: -+ ----- -DEFAULT pxeboot -TIMEOUT 20 -PROMPT 0 -LABEL pxeboot - KERNEL http://<HTTP_server>/rhcos-<version>-live-kernel-<architecture> <1> - APPEND initrd=http://<HTTP_server>/rhcos-<version>-live-initramfs.<architecture>.img coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-live-rootfs.<architecture>.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/bootstrap.ign <2> <3> ----- -<1> Specify the location of the live `kernel` file that you uploaded to your HTTP -server. -The URL must be HTTP, TFTP, or FTP; HTTPS and NFS are not supported. -<2> If you use multiple NICs, specify a single interface in the `ip` option. -For example, to use DHCP on a NIC that is named `eno1`, set `ip=eno1:dhcp`. -<3> Specify locations of the {op-system} files that you uploaded to your -HTTP server. The `initrd` parameter value is the location of the `initramfs` file, -the `coreos.live.rootfs_url` parameter value is the location of the -`rootfs` file, and the `coreos.inst.ignition_url` parameter value is the -location of the bootstrap Ignition config file. -You can also add more kernel arguments to the `APPEND` line to configure networking -or other boot options. -+ -[NOTE] -==== -This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `APPEND` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?]. -==== - -** For iPXE: -+ ----- -kernel http://<HTTP_server>/rhcos-<version>-live-kernel-<architecture> coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-live-rootfs.<architecture>.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/bootstrap.ign <1> <2> -initrd http://<HTTP_server>/rhcos-<version>-live-initramfs.<architecture>.img -boot ----- -<1> Specify locations of the {op-system} files that you uploaded to your -HTTP server. The `kernel` parameter value is the location of the `kernel` file, -the `initrd` parameter value is the location of the `initramfs` file. -The `coreos.live.rootfs_url` parameter value is the location of the `rootfs` file, -and the `coreos.inst.ignition_url` parameter value is the -location of the bootstrap Ignition config file. -<2> If you use multiple NICs, specify a single interface in the `ip` option. -For example, to use DHCP on a NIC that is named `eno1`, set `ip=eno1:dhcp`. -+ -[NOTE] -==== -This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `kernel` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?]. -==== -+ -. Continue to create the machines for your cluster. -+ -[IMPORTANT] -==== -You must create the bootstrap and control plane machines at this time. If the -control plane machines are not made schedulable, which is the default, also -create at least two compute machines before you install the cluster. -==== diff --git a/modules/installation-user-infra-machines-static-network.adoc b/modules/installation-user-infra-machines-static-network.adoc deleted file mode 100644 index 1aaee5bcefba..000000000000 --- a/modules/installation-user-infra-machines-static-network.adoc +++ /dev/null @@ -1,313 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_ibm_power/installing-ibm-power.adoc -// * installing/installing_ibm_power/installing-restricted-networks-ibm-power.adoc - -[id="installation-user-infra-machines-static-network_{context}"] -= Advanced {op-system} installation reference - -This section illustrates the networking configuration and other advanced options that allow you to modify the {op-system-first} manual installation process. The following tables describe the kernel arguments and command-line options you can use with the {op-system} live installer and the `coreos-installer` command. - -[discrete] -== Routing and bonding options at {op-system} boot prompt - -If you install {op-system} from an ISO image, you can add kernel arguments manually when you boot that image to configure the node's networking. If no networking arguments are used, the installation defaults to using DHCP. - -[IMPORTANT] -==== -When adding networking arguments, you must also add the `rd.neednet=1` kernel argument. -==== - -The following table describes how to use `ip=`, `nameserver=`, and `bond=` kernel arguments for live ISO installs. - -[NOTE] -==== -Ordering is important when adding kernel arguments: `ip=`, `nameserver=`, and then `bond=`. -==== - -.Routing and bonding options for ISO -|=== -|Description |Examples - -a|To configure an IP address, either use DHCP (`ip=dhcp`) or set an individual static IP address (`ip=<host_ip>`). If setting a static IP, you must then identify the DNS server IP address (`nameserver=<dns_ip>`) on each node. This example sets: + - -* The node's IP address to `10.10.10.2` + -* The gateway address to `10.10.10.254` + -* The netmask to `255.255.255.0` + -* The hostname to `core0.example.com` + -* The DNS server address to `4.4.4.41` - -a| ----- -ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:enp1s0:none -nameserver=4.4.4.41 ----- - -a|Specify multiple network interfaces by specifying multiple `ip=` entries. -a| ----- -ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:enp1s0:none -ip=10.10.10.3::10.10.10.254:255.255.255.0:core0.example.com:enp2s0:none ----- - -a|Disable DHCP on a single interface, such as when there are two or more network interfaces and only one interface is being used. -a| ----- -ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:enp1s0:none -ip=::::core0.example.com:enp2s0:none ----- - -a|You can combine DHCP -and static IP configurations on systems with -multiple network interfaces. -a| ----- -ip=enp1s0:dhcp -ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:enp2s0:none ----- - -a|You can provide multiple DNS servers by adding a `nameserver=` entry for each server. -a| ----- -nameserver=1.1.1.1 -nameserver=8.8.8.8 ----- - -a|Optional: Bonding multiple network interfaces to a single interface is supported -using the `bond=` option. In these two examples: - -* The syntax for configuring a bonded interface is: `bond=name[:network_interfaces][:options]` -* _name_ is the bonding device name (`bond0`), _network_interfaces_ -represents a comma-separated list of physical (ethernet) interfaces (`em1,em2`), -and _options_ is a comma-separated list of bonding options. Enter `modinfo bonding` to see available options. -* When you -create a bonded interface using `bond=`, you must specify how the IP address -is assigned and other -information for the bonded interface. -a| -To configure the bonded interface to use DHCP, set the bond's IP address -to `dhcp`. For example: - ----- -bond=bond0:em1,em2:mode=active-backup -ip=bond0:dhcp ----- - -To configure the bonded interface to use a static IP address, -enter the specific IP address you want and related information. For example: - ----- -bond=bond0:em1,em2:mode=active-backup -ip=10.10.10.2::10.10.10.254:255.255.255.0:core0.example.com:bond0:none ----- - -|=== - -[discrete] -== `coreos.inst` boot options for ISO or PXE install - -While you can pass most standard boot arguments to the live installer, there are several arguments that are specific to the {op-system} live installer. - -* For ISO, these options can be added by interrupting the boot at the bootloader menu. - -* For PXE or iPXE, these options must be added to the `APPEND` line before starting the PXE kernel. - -The following table shows the {op-system} live installer boot options for ISO and PXE installs. - -.`coreos.inst` boot options -|=== -|Argument |Description - -a|`coreos.inst.install_dev` - -a|Required. The block device on the system to install to. It is recommended to use the full path, such as `/dev/sda`, although `sda` is allowed. - -a|`coreos.inst.ignition_url` - -a|Optional: The URL of the Ignition config to embed into the installed system. If no URL is specified, no Ignition config is embedded. Only HTTP and HTTPS protocols are supported. - -a|`coreos.inst.save_partlabel` - -a|Optional: Comma-separated labels of partitions to preserve during the install. Glob-style wildcards are permitted. The specified partitions do not need to exist. - -a|`coreos.inst.save_partindex` - -a|Optional: Comma-separated indexes of partitions to preserve during the install. Ranges `m-n` are permitted, and either `m` or `n` can be omitted. The specified partitions do not need to exist. - -a|`coreos.inst.insecure` - -a|Optional: Permits the OS image that is specified by `coreos.inst.image_url` to be unsigned. - -a|`coreos.inst.image_url` - -a|Optional: Download and install the specified {op-system} image. - -* This argument should not be used in production environments and is intended for debugging purposes only. - -* While this argument can be used to install a version of {op-system} that does not match the live media, it is recommended that you instead use the media that matches the version you want to install. - -* If you are using `coreos.inst.image_url`, you must also use `coreos.inst.insecure`. This is because the bare-metal media are not GPG-signed for {product-title}. - -* Only HTTP and HTTPS protocols are supported. - -a|`coreos.inst.skip_reboot` - -a|Optional: The system will not reboot after installing. Once the install finishes, you will receive a prompt that allows you to inspect what is happening during installation. This argument should not be used in production environments and is intended for debugging purposes only. - -a|`coreos.inst.platform_id` - -a| Optional: The Ignition platform ID of the platform the {op-system} image is being installed on. Default is `metal`. This option determines whether or not to request an Ignition config from the cloud provider, such as VMware. For example: `coreos.inst.platform_id=vmware`. - -a|`ignition.config.url` - -a|Optional: The URL of the Ignition config for the live boot. For example, this can be used to customize how `coreos-installer` is invoked, or to run code before or after the installation. This is different from `coreos.inst.ignition_url`, which is the Ignition config for the installed system. -|=== - -[discrete] -== `coreos-installer` options for ISO install - -You can also install {op-system} by invoking the `coreos-installer` command directly from the command line. The kernel arguments in the previous table provide a shortcut for automatically invoking `coreos-installer` at boot time, but you can pass similar arguments directly to `coreos-installer` when running it from a shell prompt. - -The following table shows the options and subcommands you can pass to the `coreos-installer` command during a live install. - -.`coreos-installer` command-line options, arguments, and subcommands -|=== - -2+|_Command-line options_ - -|*Option* |*Description* - -a| `-u`, `--image-url <url>` -a|Specify the image URL manually. - -a|`-i,` `--ignition-file <path>` -a|Embed an Ignition config from a file. - -a|`I`, `--ignition-url <URL>` -a|Embed an Ignition config from a URL. - -a|`--ignition-hash <digest>` -a|Digest `type-value` of the Ignition config. - -a|`-p`, `--platform <name>` -a|Override the Ignition platform ID for the installed system. - -a|`--append-karg <arg>...` -a|Append a default kernel argument to the installed system. - -a|`--delete-karg <arg>...` -a|Delete a default kernel argument from the installed system. - -a|`-n`, `--copy-network` -a|Copy the network configuration from the install environment. - -a|`--network-dir <path>` -a|For use with `-n`. Default is `/etc/NetworkManager/system-connections/`. - -a|`--save-partlabel <lx>..` -a|Save partitions with this label glob. - -a|`--save-partindex <id>...` -a|Save partitions with this number or range. - -a|`--insecure` -a|Skip signature verification. - -a|`--insecure-ignition` -a|Allow Ignition URL without HTTPS or hash. - -a|`--architecture <name>` -a|Target CPU architecture. Default is `x86_64`. - -a|`--preserve-on-error` -a|Do not clear partition table on error. - -a|`-h`, `--help` -a|Print help information. - -a| `-f`, `--image-file <path>` -a|Specify a local image file manually. Used for debugging. - -a| -a| - -2+|_Command-line argument_ - -|*Argument* |*Description* - -a|`<device>` -a|The destination device. - -a| -a| - -2+|_coreos-installer embedded Ignition commands_ - -|*Command* |*Description* - -a|`$ coreos-installer iso ignition embed <options> --ignition-file <file_path> <ISO_image>` -a|Embed an Ignition config in an ISO image. - -a|`coreos-installer iso ignition show <options> <ISO_image>` -|Show the embedded Ignition config from an ISO image. - -a|`coreos-installer iso ignition remove <options> <ISO_image>` -a|Remove the embedded Ignition config from an ISO image. - -a| -a| - -2+|_coreos-installer ISO Ignition options_ - -|*Option* |*Description* - -a|`-f`, `--force` -a|Overwrite an existing Ignition config. - -a|`-i`, `--ignition-file <path>` -a|The Ignition config to be used. Default is `stdin`. - -a|`-o`, `--output <path>` -a|Write the ISO to a new output file. - -a|`-h`, `--help` -a|Print help information. - -a| -a| - -2+|_coreos-installer PXE Ignition commands_ - -|*Command* |*Description* - -2+|Note that not all of these options are accepted by all subcommands. - -a|`coreos-installer pxe ignition wrap <options>` -a|Wrap an Ignition config in an image. - -a|`coreos-installer pxe ignition unwrap <options> <image_name>` -a|Show the wrapped Ignition config in an image. - -a| -a| - -2+|_coreos-installer PXE Ignition options_ - -|*Option* |*Description* - -2+|Note that not all of these options are accepted by all subcommands. - -a|`-i`, `--ignition-file <path>` -a|The Ignition config to be used. Default is `stdin`. - -a|`-o,` `--output <path>` -a|Write the ISO to a new output file. - -a|`-h`, `--help` -a|Print help information. - -|=== diff --git a/modules/installation-vsphere-config-yaml.adoc b/modules/installation-vsphere-config-yaml.adoc deleted file mode 100644 index 54f0406832e4..000000000000 --- a/modules/installation-vsphere-config-yaml.adoc +++ /dev/null @@ -1,213 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere.adoc - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:restricted: -endif::[] - -[id="installation-vsphere-config-yaml_{context}"] -= Sample `install-config.yaml` file for VMware vSphere - -You can customize the `install-config.yaml` file to specify more details about -your {product-title} cluster's platform or modify the values of the required -parameters. - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com <1> -compute: -- hyperthreading: Enabled <2> <3> - name: worker - replicas: 0 <4> -controlPlane: - hyperthreading: Enabled <2> <3> - name: master - replicas: 3 <5> -metadata: - name: test <6> -platform: - vsphere: - vcenter: your.vcenter.server <7> - username: username <8> - password: password <9> - datacenter: datacenter <10> - defaultDatastore: datastore <11> - folder: "/<datacenter_name>/vm/<folder_name>/<subfolder_name>" <12> -ifndef::restricted[] -ifndef::openshift-origin[] -fips: false <13> -endif::openshift-origin[] -ifndef::openshift-origin[] -pullSecret: '{"auths": ...}' <14> -endif::openshift-origin[] -ifdef::openshift-origin[] -pullSecret: '{"auths": ...}' <13> -endif::openshift-origin[] -endif::restricted[] -ifdef::restricted[] -ifndef::openshift-origin[] -fips: false <13> -pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "you@example.com"}}}' <14> -endif::openshift-origin[] -ifdef::openshift-origin[] -pullSecret: '{"auths":{"<local_registry>": {"auth": "<credentials>","email": "you@example.com"}}}' <13> -endif::openshift-origin[] -endif::restricted[] -ifndef::openshift-origin[] -sshKey: 'ssh-ed25519 AAAA...' <15> -endif::openshift-origin[] -ifdef::openshift-origin[] -sshKey: 'ssh-ed25519 AAAA...' <14> -endif::openshift-origin[] -ifdef::restricted[] -ifndef::openshift-origin[] -additionalTrustBundle: | <16> - -----BEGIN CERTIFICATE----- - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - -----END CERTIFICATE----- -imageContentSources: <17> -- mirrors: - - <local_registry>/<local_repository_name>/release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <local_registry>/<local_repository_name>/release - source: registry.svc.ci.openshift.org/ocp/release -endif::openshift-origin[] -ifdef::openshift-origin[] -additionalTrustBundle: | <15> - -----BEGIN CERTIFICATE----- - ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - -----END CERTIFICATE----- -imageContentSources: <16> -- mirrors: - - <local_registry>/<local_repository_name>/release - source: quay.io/openshift-release-dev/ocp-release -- mirrors: - - <local_registry>/<local_repository_name>/release - source: registry.svc.ci.openshift.org/ocp/release -endif::openshift-origin[] -endif::restricted[] ----- -<1> The base domain of the cluster. All DNS records must be sub-domains of this -base and include the cluster name. -<2> The `controlPlane` section is a single mapping, but the compute section is a -sequence of mappings. To meet the requirements of the different data structures, -the first line of the `compute` section must begin with a hyphen, `-`, and the -first line of the `controlPlane` section must not. Although both sections -currently define a single machine pool, it is possible that future versions -of {product-title} will support defining multiple compute pools during -installation. Only one control plane pool is used. -<3> Whether to enable or disable simultaneous multithreading, or -`hyperthreading`. By default, simultaneous multithreading is enabled -to increase the performance of your machines' cores. You can disable it by -setting the parameter value to `Disabled`. If you disable simultaneous -multithreading in some cluster machines, you must disable it in all cluster -machines. -+ -[IMPORTANT] -==== -If you disable simultaneous multithreading, ensure that your capacity planning -accounts for the dramatically decreased machine performance. -Your machines must use at least 8 CPUs and 32 GB of RAM if you disable -simultaneous multithreading. -==== -<4> You must set the value of the `replicas` parameter to `0`. This parameter -controls the number of workers that the cluster creates and manages for you, -which are functions that the cluster does not perform when you -use user-provisioned infrastructure. You must manually deploy worker -machines for the cluster to use before you finish installing {product-title}. -<5> The number of control plane machines that you add to the cluster. Because -the cluster uses this values as the number of etcd endpoints in the cluster, the -value must match the number of control plane machines that you deploy. -<6> The cluster name that you specified in your DNS records. -<7> The fully-qualified host name or IP address of the vCenter server. -<8> The name of the user for accessing the server. This user must have at least -the roles and privileges that are required for -link:https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/vcp-roles.html[static or dynamic persistent volume provisioning] -in vSphere. -<9> The password associated with the vSphere user. -<10> The vSphere datacenter. -<11> The default vSphere datastore to use. -<12> Optional: For installer-provisioned infrastructure, the absolute path of an existing folder where the installation program creates the virtual machines, for example, `/<datacenter_name>/vm/<folder_name>/<subfolder_name>`. If you do not provide this value, the installation program creates a top-level folder in the datacenter virtual machine folder that is named with the infrastructure ID. If you are providing the infrastructure for the cluster, omit this parameter. -ifndef::openshift-origin[] -<13> Whether to enable or disable FIPS mode. By default, FIPS mode is not enabled. If FIPS mode is enabled, the {op-system-first} machines that {product-title} runs on bypass the default Kubernetes cryptography suite and use the cryptography modules that are provided with {op-system} instead. -endif::openshift-origin[] -ifndef::restricted[] -ifndef::openshift-origin[] -<14> The pull secret that you obtained from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. This pull secret allows you to authenticate with the services that are -provided by the included authorities, including Quay.io, which serves the -container images for {product-title} components. -endif::openshift-origin[] -ifdef::openshift-origin[] -<13> The pull secret that you obtained from the -link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. This pull secret allows you to authenticate with the services that are -provided by the included authorities, including Quay.io, which serves the -container images for {product-title} components. -<14> The public portion of the default SSH key for the `core` user in -{op-system-first}. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -endif::openshift-origin[] -endif::restricted[] -ifndef::openshift-origin[] -<15> The public portion of the default SSH key for the `core` user in -{op-system-first}. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -endif::openshift-origin[] -ifdef::restricted[] -ifdef::openshift-origin[] -<14> For `<local_registry>`, specify the registry domain name, and optionally the -port, that your mirror registry uses to serve content. For example -`registry.example.com` or `registry.example.com:5000`. For `<credentials>`, -specify the base64-encoded user name and password for your mirror registry. -<15> The public portion of the default SSH key for the `core` user in -{op-system-first}. -+ -[NOTE] -==== -For production {product-title} clusters on which you want to perform installation debugging or disaster recovery, specify an SSH key that your `ssh-agent` process uses. -==== -endif::openshift-origin[] -endif::restricted[] -ifdef::restricted[] -ifndef::openshift-origin[] -<16> Provide the contents of the certificate file that you used for your mirror -registry. -<17> Provide the `imageContentSources` section from the output of the command to -mirror the repository. -endif::openshift-origin[] -ifdef::openshift-origin[] -<15> Provide the contents of the certificate file that you used for your mirror -registry. -<16> Provide the `imageContentSources` section from the output of the command to -mirror the repository. -endif::openshift-origin[] -endif::restricted[] - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!restricted: -endif::[] -ifdef::openshift-origin[] -:!restricted: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!restricted: -endif::[] diff --git a/modules/installation-vsphere-infrastructure.adoc b/modules/installation-vsphere-infrastructure.adoc deleted file mode 100644 index 188b8d4a5095..000000000000 --- a/modules/installation-vsphere-infrastructure.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc - -[id="installation-vsphere-infrastructure_{context}"] -= VMware vSphere infrastructure requirements - -You must install the {product-title} cluster on a VMware vSphere version 6 or 7 instance that meets the requirements for the components that you use. - -.Minimum supported vSphere version for VMware components -|=== -|Component | Minimum supported versions |Description - -|Hypervisor -|vSphere 6.5 and later with HW version 13 -|This version is the minimum version that {op-system-first} supports. See the link:https://access.redhat.com/ecosystem/search/#/ecosystem/Red%20Hat%20Enterprise%20Linux?sort=sortTitle%20asc&vendors=VMware&category=Server[Red Hat Enterprise Linux 8 supported hypervisors list]. - -|Networking (NSX-T) -|vSphere 6.5U3 or vSphere 6.7U2 and later -|vSphere 6.5U3 or vSphere 6.7U2+ are required for {product-title}. VMware’s NSX Container Plug-in (NCP) is certified with {product-title} 4.6 and NSX-T 3.x+. - - -|Storage with in-tree drivers -|vSphere 6.5 and later -|This plug-in creates vSphere storage by using the in-tree storage drivers for vSphere included in {product-title}. - -|=== - -If you use a vSphere version 6.5 instance, consider upgrading to 6.7U3 or 7.0 before -you install {product-title}. - -[IMPORTANT] -==== -You must ensure that the time on your ESXi hosts is synchronized before you install {product-title}. See link:https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.vcenterhost.doc/GUID-8756D419-A878-4AE0-9183-C6D5A91A8FB1.html[Edit Time Configuration for a Host] in the VMware documentation. -==== diff --git a/modules/installation-vsphere-installer-infra-requirements.adoc b/modules/installation-vsphere-installer-infra-requirements.adoc deleted file mode 100644 index 35d607b88dce..000000000000 --- a/modules/installation-vsphere-installer-infra-requirements.adoc +++ /dev/null @@ -1,140 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc - -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:restricted: -endif::[] - -[id="installation-vsphere-installer-infra-requirements_{context}"] -= vCenter requirements - -Before you install an {product-title} cluster on your vCenter that uses infrastructure that the installer provisions, you must prepare your environment. - -[discrete] -[id="installation-vsphere-installer-infra-requirements-account_{context}"] -== Required vCenter account privileges - -To install an {product-title} cluster in a vCenter, the installation program requires access to an account with privileges to read and create the required resources. Using an account that has administrative privileges is the simplest way to access all of the necessary permissions. - -A user requires the following privileges to install an {product-title} cluster: - -* Datastore -** *Allocate space* -** *Browse datastore* -** *Low level file operations* -** *Remove file* -* Folder -** *Create folder* -** *Delete folder* -* vSphere Tagging -** All privileges -* Network -** *Assign network* -* Resource -** *Assign virtual machine to resource pool* -* Profile-driven storage -** All privileges -* vApp -** All privileges -* Virtual machine -** All privileges - -For more information about creating an account with only the required privileges, see link:https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.security.doc/GUID-5372F580-5C23-4E9C-8A4E-EF1B4DD9033E.html[vSphere Permissions and User Management Tasks] in the vSphere documentation. - -[discrete] -[id="installation-vsphere-installer-infra-requirements-vmotion_{context}"] -== Using {product-title} with vMotion - -[IMPORTANT] -==== -{product-title} generally supports compute-only vMotion. Using Storage vMotion can cause issues and is not supported. -==== - -If you are using vSphere volumes in your pods, migrating a VM across datastores either manually or through Storage vMotion causes invalid references within {product-title} persistent volume (PV) objects. These references prevent affected pods from starting up and can result in data loss. - -Similarly, {product-title} does not support selective migration of VMDKs across datastores, using datastore clusters for VM provisioning or for dynamic or static provisioning of PVs, or using a datastore that is part of a datastore cluster for dynamic or static provisioning of PVs. - -[discrete] -[id="installation-vsphere-installer-infra-requirements-resources_{context}"] -== Cluster resources - -When you deploy an {product-title} cluster that uses installer-provisioned infrastructure, the installation program must be able to create several resources in your vCenter instance. - -A standard {product-title} installation creates the following vCenter resources: - -* 1 Folder -* 1 Tag category -* 1 Tag -* Virtual machines: -** 1 template -** 1 temporary bootstrap node -** 3 control plane nodes -** 3 compute machines - -Although these resources use 856 GB of storage, the bootstrap node is destroyed during the cluster installation process. A minimum of 800 GB of storage is required to use a standard cluster. - -If you deploy more compute machines, the {product-title} cluster will use more storage. - -[discrete] -[id="installation-vsphere-installer-infra-requirements-limits_{context}"] -== Cluster limits - -Available resources vary between clusters. The number of possible clusters within a vCenter is limited primarily by available storage space and any limitations on the number of required resources. Be sure to consider both limitations to the vCenter resources that the cluster creates and the resources that you require to deploy a cluster, such as IP addresses and networks. - -[discrete] -[id="installation-vsphere-installer-infra-requirements-networking_{context}"] -== Networking requirements - -You must use DHCP for the network and ensure that the DHCP server is configured to provide persistent IP addresses to the cluster machines. -ifdef::restricted[] -The VM in your restricted network must have access to vCenter so that it can provision and manage nodes, persistent volume claims (PVCs), and other resources. -endif::restricted[] -Additionally, you must create the following networking resources before you install the {product-title} cluster: - -[discrete] -[id="installation-vsphere-installer-infra-requirements-_{context}"] -=== Required IP Addresses -An installer-provisioned vSphere installation requires two static IP addresses: - -* The **API** address is used to access the cluster API. -* The **Ingress** address is used for cluster ingress traffic. - -You must provide these IP addresses to the installation program when you install the {product-title} cluster. - -[discrete] -[id="installation-vsphere-installer-infra-requirements-dns-records_{context}"] -=== DNS records -You must create DNS records for two static IP addresses in the appropriate DNS server for the vCenter instance that hosts your {product-title} cluster. In each record, `<cluster_name>` is the cluster name and `<base_domain>` is the cluster base domain that you specify when you install the cluster. A complete DNS record takes the form: `<component>.<cluster_name>.<base_domain>.`. - -.Required DNS records -[cols="1a,5a,3a",options="header"] -|=== - -|Component -|Record -|Description - -|API VIP -|`api.<cluster_name>.<base_domain>.` -|This DNS A/AAAA or CNAME record must point to the load balancer -for the control plane machines. This record must be resolvable by both clients -external to the cluster and from all the nodes within the cluster. - -|Ingress VIP -|`*.apps.<cluster_name>.<base_domain>.` -|A wildcard DNS A/AAAA or CNAME record that points to the load balancer that targets the -machines that run the Ingress router pods, which are the worker nodes by -default. This record must be resolvable by both clients external to the cluster -and from all the nodes within the cluster. -|=== - -ifeval::["{context}" == "installing-restricted-networks-installer-provisioned-vsphere"] -:!restricted: -endif::[] diff --git a/modules/installation-vsphere-machines.adoc b/modules/installation-vsphere-machines.adoc deleted file mode 100644 index 5a7f3961aa34..000000000000 --- a/modules/installation-vsphere-machines.adoc +++ /dev/null @@ -1,141 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc - -[id="installation-vsphere-machines_{context}"] -= Creating {op-system-first} machines in vSphere - -Before you install a cluster that contains user-provisioned infrastructure on VMware vSphere, you must create {op-system} machines on vSphere hosts for it to use. - -.Prerequisites - -* Obtain the Ignition config files for your cluster. -* Create a link:https://docs.vmware.com/en/VMware-vSphere/6.0/com.vmware.vsphere.vcenterhost.doc/GUID-B1018F28-3F14-4DFE-9B4B-F48BBDB72C10.html[vSphere cluster]. - -.Procedure - -. Convert the control plane, compute, and bootstrap Ignition config files to Base64 encoding. - -+ -For example, if you use a Linux operating system, you can use the `base64` command to encode the files. -+ -[source,terminal] ----- -$ base64 -w0 <installation_directory>/master.ign > <installation_directory>/master.64 ----- -+ -[source,terminal] ----- -$ base64 -w0 <installation_directory>/worker.ign > <installation_directory>/worker.64 ----- -+ -[source,terminal] ----- -$ base64 -w0 <installation_directory>/bootstrap.ign > <installation_directory>/bootstrap.64 ----- -+ -[IMPORTANT] -==== -If you plan to add more compute machines to your cluster after you finish installation, do not delete these files. -==== - -ifndef::openshift-origin[] -. Obtain the {op-system} OVA image. Images are available from the link:https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/latest/[{op-system} image mirror] page. -+ -[IMPORTANT] -==== -The {op-system} images might not change with every release of {product-title}. You must download an image with the highest version that is less than or equal to the {product-title} version that you install. Use the image version that matches your {product-title} version if it is available. -==== -+ -The filename contains the {product-title} version number in the format `rhcos-vmware.<architecture>.ova`. -endif::openshift-origin[] -ifdef::openshift-origin[] -. Obtain the {op-system} images from the link:https://getfedora.org/en/coreos/download?tab=metal_virtualized&stream=stable[{op-system} Downloads] page -endif::openshift-origin[] - -. In the vSphere Client, create a folder in your datacenter to store your VMs. -.. Click the *VMs and Templates* view. -.. Right-click the name of your datacenter. -.. Click *New Folder* -> *New VM and Template Folder*. -.. In the window that is displayed, enter the folder name. If you did not specify an existing folder in the `install-config.yaml` file, then create a folder with the same name as the infrastructure ID. - -. In the vSphere Client, create a template for the OVA image. -+ -[NOTE] -==== -In the following steps, you use the same template for all of your cluster machines and provide the location for the Ignition config file for that machine type when you provision the VMs. -==== -.. From the *Hosts and Clusters* tab, right-click your cluster name and select *Deploy OVF Template*. -.. On the *Select an OVF* tab, specify the name of the {op-system} OVA file that you downloaded. -.. On the *Select a name and folder* tab, set a *Virtual machine name*, such as {op-system}. Click the name of your vSphere cluster and select the folder you created in the previous step. -.. On the *Select a compute resource* tab, click the name of your vSphere cluster. -.. On the *Select storage* tab, configure the storage options for your VM. -*** Select *Thin Provision* or *Thick Provision*, based on your storage preferences. -*** Select the datastore that you specified in your `install-config.yaml` file. -.. On the *Select network* tab, specify the network that you configured for the cluster, if available. -.. If you plan to use the same template for all cluster machine types, do not specify values on the *Customize template* tab. -+ -[IMPORTANT] -==== -If you plan to add more compute machines to your cluster after you finish -installation, do not delete this template. -==== - -. After the template deploys, deploy a VM for a machine in the cluster. -.. Right-click the template name and click *Clone* -> *Clone to Virtual Machine*. -.. On the *Select a name and folder* tab, specify a name for the VM. You might include the machine type in the name, such as `control-plane-0` or `compute-1`. -.. On the *Select a name and folder* tab, select the name of the folder that you created for the cluster. -.. On the *Select a compute resource* tab, select the name of a host in your datacenter. -+ -For a bootstrap machine, specify the URL of the bootstrap Ignition config file that you hosted. -+ -.. Optional: On the *Select storage* tab, customize the storage options. -.. On the *Select clone options*, select -*Customize this virtual machine's hardware*. -.. On the *Customize hardware* tab, click *VM Options* -> *Advanced*. -*** Optional: Override default DHCP networking in vSphere. To enable static IP networking: -+ -... Set your static IP configuration: -+ -[source,terminal] ----- -$ export IPCFG="ip=<ip>::<gateway>:<netmask>:<hostname>:<iface>:none nameserver=srv1 [nameserver=srv2 [nameserver=srv3 [...]]]" ----- -+ -.Example command -[source,terminal] ----- -$ export IPCFG="ip=192.168.100.101::192.168.100.254:255.255.255.0:::none nameserver=8.8.8.8" ----- - -... Set the `guestinfo.afterburn.initrd.network-kargs` property before booting a VM from an OVA in vSphere: -+ -[source,terminal] ----- -$ govc vm.change -vm "<vm_name>" -e "guestinfo.afterburn.initrd.network-kargs=${IPCFG}" ----- -+ -*** Optional: In the event of cluster performance issues, from the *Latency Sensitivity* list, select *High*. -*** Click *Edit Configuration*, and on the *Configuration Parameters* window, click *Add Configuration Params*. Define the following parameter names and values: -**** `guestinfo.ignition.config.data`: Paste the contents of the base64-encoded Ignition config file for this machine type. Note for the bootstrap node, the Ignition config file must be provided in `guestinfo.ignition.config.data` in the *Configuration Parameters* window. This is due to a restriction in the maximum size of data that can be provided in a vApp property. -**** `guestinfo.ignition.config.data.encoding`: Specify `base64`. -**** `disk.EnableUUID`: Specify `TRUE`. -*** Alternatively, prior to powering on the virtual machine, use vApp properties to: -**** Navigate to a virtual machine from the vCenter Server inventory. -**** On the *Configure* tab, expand *Settings* and select *vApp options.* -**** Scroll down and under *Properties*, apply the configurations that you just edited. -.. In the *Virtual Hardware* panel of the *Customize hardware* tab, modify the specified values as required. Ensure that the amount of RAM, CPU, and disk storage meets the minimum requirements for the -machine type. -.. Complete the configuration and power on the VM. - -. Create the rest of the machines for your cluster by following the preceding steps for each machine. -+ -[IMPORTANT] -==== -You must create the bootstrap and control plane machines at this time. Because some pods are deployed on compute machines by default, also create at least two compute machines before you install the cluster. -==== diff --git a/modules/installing-cluster-loader.adoc b/modules/installing-cluster-loader.adoc deleted file mode 100644 index 55640d6571c3..000000000000 --- a/modules/installing-cluster-loader.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// scalability_and_performance/using-cluster-loader.adoc - -[id="installing-cluster-loader_{context}"] -= Installing Cluster Loader - -.Procedure - -. To pull the container image, run: -+ -[source,terminal] ----- -$ sudo podman pull quay.io/openshift/origin-tests:4.7 ----- diff --git a/modules/installing-rhacs-kubernetes-steps.adoc b/modules/installing-rhacs-kubernetes-steps.adoc new file mode 100644 index 000000000000..00d71bc86148 --- /dev/null +++ b/modules/installing-rhacs-kubernetes-steps.adoc @@ -0,0 +1,68 @@ +// Module included in the following assemblies: +// +// * installing/acs-high-level-overview +:_mod-docs-content-type: CONCEPT +[id="installing-rhacs-kubernetes-steps_{context}"] += Installation steps for RHACS on Kubernetes + +[id="installing-kube-helm-steps"] +== Installing {product-title-short} on Kubernetes platforms by using Helm charts + +. Add the {product-title-short} Helm charts repository. +. Install the `central-services` Helm chart on the cluster that will contain Central, called the Central cluster. +. Log in to the {product-title-short} web console from the Central cluster and create an init bundle or cluster registration secret (CRS) that you need to apply to the cluster that you want to secure, called the secured cluster. The init bundle or the CRS contains the cryptographic artifacts that {product-title-short} uses to establish trusted connections between Central and secured clusters. ++ +-- +:FeatureName: Cluster registration secret +include::snippets/technology-preview.adoc[] +-- +. For each secured cluster, install the `secured-cluster-services` Helm chart by running one of the following commands: +* For an init bundle, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox \ + --create-namespace stackrox-secured-cluster-services rhacs/secured-cluster-services \ + -f <name_of_cluster_init_bundle.yaml> \ + -f <path_to_values_public.yaml> \// <1> + -f <path_to_values_private.yaml> \// <2> + --set imagePullSecrets.username=<username> \// <3> + --set imagePullSecrets.password=<password> <4> +---- +<1> Use the `-f` option to specify the paths for your public YAML configuration file. +<2> Use the `-f` option to specify the paths for your private YAML configuration file. +<3> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<4> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. +* For a CRS, run the following command: ++ +[source,terminal] +---- +$ helm install -n stackrox \ + --create-namespace stackrox-secured-cluster-services rhacs/secured-cluster-services \ + --set-file crs.file=<crs_file_name.yaml> \ <1> + -f <path_to_values_public.yaml> \// <2> + -f <path_to_values_private.yaml> \// <3> + --set imagePullSecrets.username=<username> \// <4> + --set imagePullSecrets.password=<password> <5> +---- +<1> Use the name of the file in which the generated CRS has been stored. +<2> Use the `-f` option to specify the paths for your public YAML configuration file. +<3> Use the `-f` option to specify the paths for your private YAML configuration file. +<4> Include the user name for your pull secret for Red{nbsp}Hat Container Registry authentication. +<5> Include the password for your pull secret for Red{nbsp}Hat Container Registry authentication. + +[id="installing-kube-roxctl-steps"] +== Installing {product-title-short} on Kubernetes platforms by using the `roxctl` CLI + +This installation method is also called the _manifest installation method_. + +. Install the `roxctl` CLI. +. On the Kubernetes cluster that will contain Central, perform these steps: +.. In the terminal window, run the interactive install command by using the `roxctl` CLI. +.. Run the setup shell script. +.. In the terminal window, create the Central resources by using the `kubectl create` command. +. Perform one of the following actions: +* In the {product-title-short} web console, create and download the sensor YAML file and keys. +* On the cluster that you want to secure, called the secured cluster, use the `roxctl sensor generate openshift` command. +. On the secured cluster, run the sensor installation script. + diff --git a/modules/installing-rhacs-ocp-steps.adoc b/modules/installing-rhacs-ocp-steps.adoc new file mode 100644 index 000000000000..f7084a437d87 --- /dev/null +++ b/modules/installing-rhacs-ocp-steps.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * installing/acs-high-level-overview +:_mod-docs-content-type: CONCEPT +[id="installing-rhacs-ocp-steps_{context}"] += Installation steps for RHACS on OpenShift Container Platform + +[id="installing-ocp-operator-steps"] +== Installing {product-title-short} on {osp} by using the {product-title-short} Operator + +. On the {osp} cluster, install the {product-title-short} Operator into the `rhacs-operator` project, or namespace. +. On the {osp} cluster that will contain Central, called the central cluster, use the {product-title-short} Operator to install Central services into the `stackrox` project. One central cluster can secure multiple clusters. +. Log in to the {product-title-short} web console from the central cluster, and then create an init bundle or cluster registration secret (CRS) and download it. The init bundle is then installed on the cluster that you want to secure, called the secured cluster. +. For the secured cluster: +.. Install the {product-title-short} Operator into the `rhacs-operator` namespace. +.. On the secured cluster, apply the init bundle or CRS that you created in {product-title-short} by performing one of these steps: +* Use the {ocp} web console to import the YAML file of the init bundle or CRS that you created. Make sure you are in the `stackrox` namespace. +* Use the OpenShift CLI to perform one of the following actions: +** If you created an init bundle, in the terminal window, run the `oc create -f <init_bundle.yaml> -n <stackrox>` command, specifying the path to the downloaded YAML file of the init bundle. +** If you created a CRS, in the terminal window, run the `oc create -f <file_name.yaml> -n <stackrox>` command, specifying the path to the downloaded CRS. +.. On the secured cluster, use the {product-title-short} Operator to install Secured Cluster services into the `stackrox` namespace. When creating these services, be sure to enter the address of Central in the *Central Endpoint* field so that the secured cluster can communicate with Central. + +[id="installing-ocp-helm-steps"] +== Installing {product-title-short} on {osp} by using Helm charts + +. Add the {product-title-short} Helm charts repository. +. Install the `central-services` Helm chart on the {osp} cluster that will contain Central, called the central cluster. +. Log in to the {product-title-short} web console on the Central cluster and create an init bundle or CRS. +. For each cluster that you want to secure, log in to the secured cluster and use the `helm install` command to install the `secured-cluster-services` Helm chart, specifying the path to the init bundle or CRS that you created. + +[id="installing-ocp-roxctl-steps"] +== Installing {product-title-short} on {osp} by using the `roxctl` CLI + +This installation method is also called the _manifest installation method_. + +. Install the `roxctl` CLI. +. On the {osp} cluster that will contain Central, perform these steps: +.. In the terminal window, run the interactive install command by using the `roxctl` CLI. +.. Run the setup shell script. +.. In the terminal window, create the Central resources by using the `oc create` command. +. Perform one of the following actions: +* In the {product-title-short} web console, create and download the sensor YAML file and keys. +* On the secured cluster, use the `roxctl sensor generate openshift` command. +. On the secured cluster, run the sensor installation script. + diff --git a/modules/installing-rhv-accessing-ocp-web-console.adoc b/modules/installing-rhv-accessing-ocp-web-console.adoc deleted file mode 100644 index 56eb8adada8e..000000000000 --- a/modules/installing-rhv-accessing-ocp-web-console.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-default.adoc -// * installing/installing_rhv/installing-rhv-custom.adoc - -[id="installing-rhv-accessing-ocp-web-console_{context}"] -= Accessing the {product-title} web console on {rh-virtualization} - -After the {product-title} cluster initializes, you can log into the {product-title} web console. - -.Procedure -. Optional: In the {rh-virtualization-first} Administration Portal, open *Compute* -> *Cluster*. -. Verify that the installation program creates the virtual machines. -. Return to the command line where the installation program is running. When the installation program finishes, it displays the user name and temporary password for logging into the {product-title} web console. -. In a browser, open the URL of the {product-title} web console. The URL uses this format: -+ ----- -console-openshift-console.apps.<clustername>.<basedomain> <1> ----- -<1> For `<clustername>.<basedomain>`, specify the cluster name and base domain. -+ -For example: -+ ----- -console-openshift-console.apps.my-cluster.virtlab.example.com ----- diff --git a/modules/installing-rhv-example-install-config-yaml.adoc b/modules/installing-rhv-example-install-config-yaml.adoc deleted file mode 100644 index 0447ff87bc13..000000000000 --- a/modules/installing-rhv-example-install-config-yaml.adoc +++ /dev/null @@ -1,138 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-custom.adoc -// * installing/installing_rhv/installing-rhv-default.adoc - -[id="installing-rhv-example-install-config-yaml_{context}"] -= Example `install-config.yaml` files for {rh-virtualization-first} - -You can customize the {product-title} cluster the installation program creates by changing the parameters and parameter values in the `install-config.yaml` file. - -The following example is specific to installing {product-title} on {rh-virtualization}. - -This file is located in the `<installation_directory>` you specified when you ran the following command. -[source,terminal] ----- -$ ./openshift-install create install-config --dir=<installation_directory> ----- - -[NOTE] -==== -* These example files are provided for reference only. You must obtain your -`install-config.yaml` file by using the installation program. -* Changing the `install-config.yaml` file can increase the resources your cluster requires. Verify that your {rh-virtualization} environment has those additional resources. Otherwise, the installation or cluster will fail. -==== - -.Example: This is the default `install-config.yaml` file - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com -compute: -- architecture: amd64 - hyperthreading: Enabled - name: worker - platform: {} - replicas: 3 -controlPlane: - architecture: amd64 - hyperthreading: Enabled - name: master - platform: {} - replicas: 3 -metadata: - creationTimestamp: null - name: my-cluster -networking: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineNetwork: - - cidr: 10.0.0.0/16 -ifndef::openshift-origin[] - networkType: OpenShiftSDN -endif::openshift-origin[] -ifdef::openshift-origin[] - networkType: OVNKubernetes -endif::openshift-origin[] - serviceNetwork: - - 172.30.0.0/16 -platform: - ovirt: - api_vip: 10.46.8.230 - ingress_vip: 192.168.1.5 - ovirt_cluster_id: 68833f9f-e89c-4891-b768-e2ba0815b76b - ovirt_storage_domain_id: ed7b0f4e-0e96-492a-8fff-279213ee1468 - ovirt_network_name: ovirtmgmt - vnicProfileID: 3fa86930-0be5-4052-b667-b79f0a729692 -publish: External -pullSecret: '{"auths": ...}' -sshKey: ssh-ed12345 AAAA... ----- - - -.Example: A minimal `install-config.yaml` file - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com -metadata: - name: test-cluster -platform: - ovirt: - api_vip: 10.46.8.230 - ingress_vip: 10.46.8.232 - ovirt_cluster_id: 68833f9f-e89c-4891-b768-e2ba0815b76b - ovirt_storage_domain_id: ed7b0f4e-0e96-492a-8fff-279213ee1468 - ovirt_network_name: ovirtmgmt - vnicProfileID: 3fa86930-0be5-4052-b667-b79f0a729692 -pullSecret: '{"auths": ...}' -sshKey: ssh-ed12345 AAAA... ----- - - -.Example: Custom machine pools in an `install-config.yaml` file - -[source,yaml] ----- -apiVersion: v1 -baseDomain: example.com -controlPlane: - name: master - platform: - ovirt: - cpu: - cores: 4 - sockets: 2 - memoryMB: 65536 - osDisk: - sizeGB: 100 - vmType: server - replicas: 3 -compute: -- name: worker - platform: - ovirt: - cpu: - cores: 4 - sockets: 4 - memoryMB: 65536 - osDisk: - sizeGB: 200 - vmType: server - replicas: 5 -metadata: - name: test-cluster -platform: - ovirt: - api_vip: 10.46.8.230 - ingress_vip: 10.46.8.232 - ovirt_cluster_id: 68833f9f-e89c-4891-b768-e2ba0815b76b - ovirt_storage_domain_id: ed7b0f4e-0e96-492a-8fff-279213ee1468 - ovirt_network_name: ovirtmgmt - vnicProfileID: 3fa86930-0be5-4052-b667-b79f0a729692 -pullSecret: '{"auths": ...}' -sshKey: ssh-ed25519 AAAA... ----- diff --git a/modules/installing-rhv-insecure-mode.adoc b/modules/installing-rhv-insecure-mode.adoc deleted file mode 100644 index c9c0d3729447..000000000000 --- a/modules/installing-rhv-insecure-mode.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-custom.adoc -// * installing/installing_rhv/installing-rhv-default.adoc -// * installing/installing_rhv/installing-rhv-user-infra.adoc - -[id="installing-rhv-insecure-mode_{context}"] -= Installing {product-title} on {rh-virtualization} in insecure mode - -By default, the installer creates a CA certificate, prompts you for confirmation, and stores the certificate to use during installation. You do not need to create or install one manually. - -Although it is not recommended, you can override this functionality and install {product-title} without verifying a certificate by installing {product-title} on {rh-virtualization} in *insecure* mode. - -[WARNING] -==== -Installing in *insecure* mode is not recommended, because it enables a potential attacker to perform a Man-in-the-Middle attack and capture sensitive credentials on the network. -==== - -.Procedure - -. Create a file named `~/.ovirt/ovirt-config.yaml`. - -. Add the following content to `ovirt-config.yaml`: -+ -[source,terminal] ----- -ovirt_url: \https://ovirt.example.com/ovirt-engine/api -ovirt_fqdn: ovirt.example.com -ovirt_pem_url: "" -ovirt_username: admin@internal -ovirt_password: super-secret-password -ovirt_insecure: true ----- - -. Run the installer. diff --git a/modules/installing-rhv-network-infrastructure-configuration-upi.adoc b/modules/installing-rhv-network-infrastructure-configuration-upi.adoc deleted file mode 100644 index e57c140a689d..000000000000 --- a/modules/installing-rhv-network-infrastructure-configuration-upi.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc - -[id="installing-rhv-network-infrastructure-configuration-upi_{context}"] -= Network infrastructure configuration for installing {product-title} on {rh-virtualization-first} - -Before installing {product-title}, configure your network environment to meet the following requirements. - -When they boot, virtual machines must have IP addresses get the Ignition config files. Consider configuring DHCP to provide persistent IP addresses and hostnames to the cluster machines. -// TBD - Day 0 versus day 2? Alternatives? - -.Firewall - -Configure your firewall so your cluster has access to required sites. - -.Network connectivity - -// TBD - What do we mean by "machine" here? Where do we configure this? Can this be done at this stage in the process? -Configure your network to enable the following connections: - -* Grant every machine access to every other machine on ports `30000`-`32767`. This provides connectivity to {product-title} components. - -* Grant every machine access to reserved ports `10250`-`10259` and `9000`-`9999`. - -* Grant every machine access on ports `2379`-`2380`. This provides access to etcd, peers, and metrics on the control plane. - -* Grant every machine access to the Kubernetes API on port `6443`. - -.Load balancers - -Configure one or two (preferred) layer-4 load balancers: - -* Provide load balancing for ports `6443` and `22623` on the control plane and bootstrap machines. Port `6443` provides access to the Kubernetes API server and must be reachable both internally and externally. Port `22623` must be accessible to nodes within the cluster. - -* Provide load balancing for port `443` and `80` for machines that run the Ingress router, which are usually worker nodes in the default configuration. Both ports must be accessible from within and outside the cluster. - -.DNS - -Configure infrastructure-provided DNS to allow the correct resolution of the main components and services. If you use only one load balancer, these DNS records can point to the same IP address. - -* Create DNS records for `api.<cluster_name>.<base_domain>` (internal and external resolution) and `api-int.<cluster_name>.<base_domain>` (internal resolution) that point to the load balancer for the control plane machines. - -* Create a DNS record for `*.apps.<cluster_name>.<base_domain>` that points to the load balancer for the Ingress router. For example, ports `443` and `80` of the compute machines. diff --git a/modules/installing-rhv-preparing-network-environment.adoc b/modules/installing-rhv-preparing-network-environment.adoc deleted file mode 100644 index 0dc5afef86a9..000000000000 --- a/modules/installing-rhv-preparing-network-environment.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-custom.adoc -// * installing/installing_rhv/installing-rhv-default.adoc - -[id="installing-rhv-preparing-network-environment_{context}"] -= Preparing the network environment on {rh-virtualization} - -Configure three static IP addresses for the {product-title} cluster and create DNS entries using two of these addresses. - -.Procedure - -. Reserve three static IP addresses -.. On the network where you plan to install {product-title}, identify three static IP addresses that are outside the DHCP lease pool. -.. Connect to a host on this network and verify that each of the IP addresses is not in use. For example, use Address Resolution Protocol (ARP) to check that none of the IP addresses have entries: -+ -[source,terminal] ----- -$ arp 10.35.1.19 ----- -+ -.Example output -[source,terminal] ----- -10.35.1.19 (10.35.1.19) -- no entry ----- - -.. Reserve three static IP addresses following the standard practices for your network environment. -.. Record these IP addresses for future reference. - -. Create DNS entries for the {product-title} REST API and apps domain names using this format: -+ -[source,dns] ----- -api.<cluster-name>.<base-domain> <ip-address> <1> -*.apps.<cluster-name>.<base-domain> <ip-address> <2> ----- -<1> For `<cluster-name>`, `<base-domain>`, and `<ip-address>`, specify the cluster name, base domain, and static IP address of your {product-title} API. -<2> Specify the cluster name, base domain, and static IP address of your {product-title} apps for Ingress and the load balancer. -+ -For example: -+ -[source,dns] ----- -api.my-cluster.virtlab.example.com 10.35.1.19 -*.apps.my-cluster.virtlab.example.com 10.35.1.20 ----- -+ -[NOTE] -==== -The third static IP address does not require a DNS entry. The {product-title} cluster uses that address for its internal DNS service. -==== diff --git a/modules/installing-rhv-requirements.adoc b/modules/installing-rhv-requirements.adoc deleted file mode 100644 index 24fd8fae4e6d..000000000000 --- a/modules/installing-rhv-requirements.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-custom.adoc -// * installing/installing_rhv/installing-rhv-default.adoc -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing_rhv/installing-rhv-restricted-network.adoc - -[id="installing-rhv-requirements_{context}"] -= Requirements for the {rh-virtualization} environment - -To install and run an {product-title} version {product-version} cluster, the {rh-virtualization} environment must meet the following requirements. - -Not meeting these requirements can cause the installation or process to fail. Additionally, not meeting these requirements can cause the {product-title} cluster to fail days or weeks after installation. - -The following requirements for CPU, memory, and storage resources are based on *default* values multiplied by the default number of virtual machines the installation program creates. These resources must be available *in addition to* what the {rh-virtualization} environment uses for non-{product-title} operations. - -By default, the installation program creates seven virtual machines during the installation process. First, it creates a bootstrap virtual machine to provide temporary services and a control plane while it creates the rest of the {product-title} cluster. When the installation program finishes creating the cluster, deleting the bootstrap machine frees up its resources. - -If you increase the number of virtual machines in the {rh-virtualization} environment, you must increase the resources accordingly. - -.Requirements - -* The {rh-virtualization} version is 4.4. -* The {rh-virtualization} environment has one data center whose state is *Up*. -* The {rh-virtualization} data center contains an {rh-virtualization} cluster. -* The {rh-virtualization} cluster has the following resources exclusively for the {product-title} cluster: -** Minimum 28 vCPUs: four for each of the seven virtual machines created during installation. -** 112 GiB RAM or more, including: -*** 16 GiB or more for the bootstrap machine, which provides the temporary control plane. -*** 16 GiB or more for each of the three control plane machines which provide the control plane. -*** 16 GiB or more for each of the three compute machines, which run the application workloads. -* The {rh-virtualization} storage domain must meet link:https://access.redhat.com/solutions/4770281[these etcd backend performance requirements]. -* In production environments, each virtual machine must have 120 GiB or more. Therefore, the storage domain must provide 840 GiB or more for the default {product-title} cluster. In resource-constrained or non-production environments, each virtual machine must have 32 GiB or more, so the storage domain must have 230 GiB or more for the default {product-title} cluster. -* To download images from the Red Hat Ecosystem Catalog during installation and update procedures, the {rh-virtualization} cluster must have access to an internet connection. The Telemetry service also needs an internet connection to simplify the subscription and entitlement process. -// TBD - What about the disconnected installation alternative? -* The {rh-virtualization} cluster must have a virtual network with access to the REST API on the {rh-virtualization} Manager. Ensure that DHCP is enabled on this network, because the VMs that the installer creates obtain their IP address by using DHCP. -* A user account and group with the following least privileges for installing and managing an {product-title} cluster on the target {rh-virtualization} cluster: -** `DiskOperator` -** `DiskCreator` -** `UserTemplateBasedVm` -** `TemplateOwner` -** `TemplateCreator` -** `ClusterAdmin` on the target cluster - - -[WARNING] -==== -Apply the principle of least privilege: Avoid using an administrator account with `SuperUser` privileges on {rh-virtualization} during the installation process. The installation program saves the credentials you provide to a temporary `ovirt-config.yaml` file that might be compromised. -==== diff --git a/modules/installing-rhv-setting-up-ca-certificate.adoc b/modules/installing-rhv-setting-up-ca-certificate.adoc deleted file mode 100644 index e3122cb6768b..000000000000 --- a/modules/installing-rhv-setting-up-ca-certificate.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-custom.adoc -// * installing/installing_rhv/installing-rhv-default.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installing-rhv-setting-up-ca-certificate_{context}"] -= Setting up the CA certificate for {rh-virtualization} - -Download the CA certificate from the {rh-virtualization-first} Manager and set it up on the installation machine. - -You can download the certificate from a webpage on the {rh-virtualization} Manager or by using a `curl` command. - -Later, you provide the certificate to the installation program. - -.Procedure - -. Use either of these two methods to download the CA certificate: -** Go to the Manager's webpage, `\https://<engine-fqdn>/ovirt-engine/`. Then, under *Downloads*, click the *CA Certificate* link. -** Run the following command: -+ -[source,terminal] ----- -$ curl -k 'https://<engine-fqdn>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA' -o /tmp/ca.pem <1> ----- -<1> For `<engine-fqdn>`, specify the fully qualified domain name of the {rh-virtualization} Manager, such as `rhv-env.virtlab.example.com`. - -. Configure the CA file to grant rootless user access to the Manager. Set the CA file permissions to have an octal value of `0644` (symbolic value: `-rw-r--r--`): -+ -[source,terminal] ----- -$ sudo chmod 0644 /tmp/ca.pem ----- -. For Linux, copy the CA certificate to the directory for server certificates. Use `-p` to preserve the permissions: -+ -[source,terminal] ----- -$ sudo cp -p /tmp/ca.pem /etc/pki/ca-trust/source/anchors/ca.pem ----- -. Add the certificate to the certificate manager for your operating system: -** For macOS, double-click the certificate file and use the *Keychain Access* utility to add the file to the *System* keychain. -** For Linux, update the CA trust: -+ -[source,terminal] ----- -$ sudo update-ca-trust ----- -+ -[NOTE] -==== -If you use your own certificate authority, make sure the system trusts it. -==== - -.Additional Resources -To learn more, see link:https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.0/html/rest_api_guide/documents-002_authentication_and_security[Authentication and Security] in the {rh-virtualization} documentation. diff --git a/modules/installing-rhv-setting-up-installation-machine.adoc b/modules/installing-rhv-setting-up-installation-machine.adoc deleted file mode 100644 index 41afc5cd7732..000000000000 --- a/modules/installing-rhv-setting-up-installation-machine.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-user-infra.adoc -// * installing/installing-rhv-restricted-network.adoc - -[id="installing-rhv-setting-up-installation-machine_{context}"] -= Setting up the installation machine - - -To run the binary `openshift-install` installation program and Ansible scripts, set up the {rh-virtualization} Manager or an {op-system-base-full} computer with network access to the {rh-virtualization} environment and the REST API on the {rh-virtualization} Manager/oVirt Engine. - -// The following steps include creating an `ASSETS_DIR` environment variable, which the installation program uses to create a directory of asset files. Later, the installation process reuses this variable to locate these asset files. - -.Procedure - -. Update or install Python3 and Ansible. For example: -+ -[source,terminal] ----- -# dnf update python3 ansible ----- - -. link:https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/html/python_sdk_guide/chap-overview#Installing_the_Software_Development_Kit[Install the `python3-ovirt-engine-sdk4` package] to get the Python Software Development Kit. - -. Install the `ovirt.image-template` Ansible role. On {rh-virtualization} Manager and other {op-system-base-full} machines, this role is distributed as the `ovirt-ansible-image-template` package. For example, enter: -+ -[source,terminal] ----- -# dnf install ovirt-ansible-image-template ----- - -. Install the `ovirt.vm-infra` Ansible role. On {rh-virtualization} Manager and other {op-system-base} machines, this role is distributed as the `ovirt-ansible-vm-infra` package. -+ -[source,terminal] ----- -# dnf install ovirt-ansible-vm-infra ----- - -. Create an environment variable and assign an absolute or relative path to it. For example, enter: -+ -[source,terminal] ----- -$ export ASSETS_DIR=./wrk ----- -+ -[NOTE] -==== -The installation program uses this variable to create a directory where it saves important installation-related files. Later, the installation process reuses this variable to locate those asset files. Avoid deleting this assets directory; it is required for uninstalling the cluster. -==== diff --git a/modules/installing-rhv-verifying-rhv-environment.adoc b/modules/installing-rhv-verifying-rhv-environment.adoc deleted file mode 100644 index 1fb617f18d3f..000000000000 --- a/modules/installing-rhv-verifying-rhv-environment.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_rhv/installing-rhv-custom.adoc -// * installing/installing_rhv/installing-rhv-default.adoc -// * installing/installing_rhv/installing-rhv-restricted-network.adoc - - -[id="installing-rhv-verifying-rhv-environment_{context}"] -= Verifying the requirements for the {rh-virtualization} environment - -Verify that the {rh-virtualization} environment meets the requirements to install and run an {product-title} cluster. Not meeting these requirements can cause failures. - -[IMPORTANT] -==== -These requirements are based on the default resources the installation program uses to create control plane and compute machines. These resources include vCPUs, memory, and storage. If you change these resources or increase the number of {product-title} machines, adjust these requirements accordingly. -==== - -.Procedure - -. Check that the {rh-virtualization} version supports installation of {product-title} version {product-version}. -.. In the {rh-virtualization} Administration Portal, click the *?* help icon in the upper-right corner and select *About*. -.. In the window that opens, make a note of the **{rh-virtualization} Software Version**. -.. Confirm that the {rh-virtualization} version is 4.4. For more information about supported version combinations, see link:https://access.redhat.com/articles/5485861[Support Matrix for {product-title} on {rh-virtualization}]. - -. Inspect the data center, cluster, and storage. -.. In the {rh-virtualization} Administration Portal, click *Compute* -> *Data Centers*. -.. Confirm that the data center where you plan to install {product-title} is accessible. -.. Click the name of that data center. -.. In the data center details, on the *Storage* tab, confirm the storage domain where you plan to install {product-title} is *Active*. -.. Record the *Domain Name* for use later on. -.. Confirm *Free Space* has at least 230 GiB. -.. Confirm that the storage domain meets link:https://access.redhat.com/solutions/4770281[these etcd backend performance requirements], which you link:https://access.redhat.com/solutions/3780861[can measure by using the fio performance benchmarking tool]. -.. In the data center details, click the *Clusters* tab. -.. Find the {rh-virtualization} cluster where you plan to install {product-title}. Record the cluster name for use later on. - -. Inspect the {rh-virtualization} host resources. -.. In the {rh-virtualization} Administration Portal, click *Compute > Clusters*. -.. Click the cluster where you plan to install {product-title}. -.. In the cluster details, click the *Hosts* tab. -.. Inspect the hosts and confirm they have a combined total of at least 28 *Logical CPU Cores* available _exclusively_ for the {product-title} cluster. -.. Record the number of available *Logical CPU Cores* for use later on. -.. Confirm that these CPU cores are distributed so that each of the seven virtual machines created during installation can have four cores. -.. Confirm that, all together, the hosts have 112 GiB of *Max free Memory for scheduling new virtual machines* distributed to meet the requirements for each of the following {product-title} machines: -** 16 GiB required for the bootstrap machine -** 16 GiB required for each of the three control plane machines -** 16 GiB for each of the three compute machines -.. Record the amount of *Max free Memory for scheduling new virtual machines* for use later on. -+ -. Verify that the virtual network for installing {product-title} has access to the {rh-virtualization} Manager’s REST API. From a virtual machine on this network, use curl to reach the {rh-virtualization} Manager’s REST API: -+ -[source,terminal] ----- -$ curl -k -u <username>@<profile>:<password> \ <1> -https://<engine-fqdn>/ovirt-engine/api <2> ----- -<1> For `<username>`, specify the user name of an {rh-virtualization} account with privileges to create and manage an {product-title} cluster on {rh-virtualization}. For `<profile>`, specify the login profile, which you can get by going to the {rh-virtualization} Administration Portal login page and reviewing the *Profile* dropdown list. For `<password>`, specify the password for that user name. -<2> For `<engine-fqdn>`, specify the fully qualified domain name of the {rh-virtualization} environment. -+ -For example: -+ -ifndef::openshift-origin[] -[source,terminal] ----- -$ curl -k -u ovirtadmin@internal:pw123 \ -https://rhv-env.virtlab.example.com/ovirt-engine/api ----- -endif::openshift-origin[] -ifdef::openshift-origin[] -[source,terminal] ----- -$ curl -k -u ovirtadmin@internal:pw123 \ -https://ovirtlab.example.com/ovirt-engine/api ----- -endif::openshift-origin[] diff --git a/modules/installing-sensor-by-using-the-generate-yaml-files.adoc b/modules/installing-sensor-by-using-the-generate-yaml-files.adoc new file mode 100644 index 000000000000..864349bd3d80 --- /dev/null +++ b/modules/installing-sensor-by-using-the-generate-yaml-files.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * cli/managing-secured-clusters.adoc +:_mod-docs-content-type: PROCEDURE +[id="installing-sensor-by-using-the-sensorsh-script_{context}"] += Installing Sensor by using the sensor.sh script + +When you generate the Sensor deployment files, `roxctl` creates a directory called `sensor-<cluster_name>` in your working directory. The script to install Sensor is located in this directory. + +.Procedure + +* Run the sensor installation script to install Sensor: ++ +[source,terminal,subs="+quotes"] +---- +$ ./sensor-_<cluster_name>_/sensor.sh +---- ++ +If you get a warning that you do not have the required permissions to install Sensor, follow the on-screen instructions, or contact your cluster administrator for help. \ No newline at end of file diff --git a/modules/installing-wmco-using-cli.adoc b/modules/installing-wmco-using-cli.adoc deleted file mode 100644 index 0c146fa577e9..000000000000 --- a/modules/installing-wmco-using-cli.adoc +++ /dev/null @@ -1,123 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/enabling-windows-container-workloads.adoc - -[id="installing-wmco-using-cli_{context}"] -= Installing the Windows Machine Config Operator using the CLI - -You can use the OpenShift CLI (`oc`) to install the Windows Machine Config Operator (WMCO). - -.Procedure - -. Create a namespace for the WMCO. - -.. Create a `Namespace` object YAML file for the WMCO. For example, `wmco-namespace.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-windows-machine-config-operator <1> - labels: - openshift.io/cluster-monitoring: "true" <2> ----- -<1> It is recommended to deploy the WMCO in the `openshift-windows-machine-config-operator` namespace. -<2> This label is required for enabling cluster monitoring for the WMCO. - -.. Create the namespace: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f wmco-namespace.yaml ----- - -. Create the Operator group for the WMCO. - -.. Create an `OperatorGroup` object YAML file. For example, `wmco-og.yaml`: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: windows-machine-config-operator - namespace: openshift-windows-machine-config-operator -spec: - targetNamespaces: - - openshift-windows-machine-config-operator ----- - -.. Create the Operator group: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f wmco-og.yaml ----- - -. Subscribe the namespace to the WMCO. - -.. Create a `Subscription` object YAML file. For example, `wmco-sub.yaml`: -+ -[source,yaml, subs="attributes+"] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: windows-machine-config-operator - namespace: openshift-windows-machine-config-operator -spec: - channel: "stable" <1> - installPlanApproval: "Automatic" <2> - name: "windows-machine-config-operator" - source: "redhat-operators" <3> - sourceNamespace: "openshift-marketplace" <4> ----- -<1> Specify `stable` as the channel. -<2> Set an approval strategy. You can set `Automatic` or `Manual`. -<3> Specify the `redhat-operators` catalog source, which contains the `windows-machine-config-operator` package manifests. If your {product-title} is installed on a restricted network, also known as a disconnected cluster, specify the name of the `CatalogSource` object you created when you configured the Operator LifeCycle Manager (OLM). -<4> Namespace of the catalog source. Use `openshift-marketplace` for the default OperatorHub catalog sources. - -.. Create the subscription: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f wmco-sub.yaml ----- -+ -The WMCO is now installed to the `openshift-windows-machine-config-operator`. - -. Verify the WMCO installation: -+ -[source,terminal] ----- -$ oc get csv -n openshift-windows-machine-config-operator ----- -+ -.Example output -[source,terminal] ----- -NAME DISPLAY VERSION REPLACES PHASE -windows-machine-config-operator.2.0.0 Windows Machine Config Operator 2.0.0 Succeeded ----- diff --git a/modules/installing-wmco-using-web-console.adoc b/modules/installing-wmco-using-web-console.adoc deleted file mode 100644 index 1637adb87e8d..000000000000 --- a/modules/installing-wmco-using-web-console.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/enabling-windows-container-workloads.adoc - -[id="installing-wmco-using-web-console_{context}"] -= Installing the Windows Machine Config Operator using the web console - -You can use the {product-title} web console to install the Windows Machine Config Operator (WMCO). - -.Procedure - -. From the *Administrator* perspective in the {product-title} web console, navigate to the *Operators -> OperatorHub* page. - -. Use the *Filter by keyword* box to search for `Windows Machine Config Operator` in the catalog. Click the *Windows Machine Config Operator* tile. - -. Review the information about the Operator and click *Install*. - -. On the *Install Operator* page: - -.. Select the *stable* channel as the *Update Channel*. The *stable* channel enables the latest stable release of the WMCO to be installed. - -.. The *Installation Mode* is preconfigured because the WMCO must be available in a single namespace only. - -.. Choose the *Installed Namespace* for the WMCO. The default Operator recommended namespace is `openshift-windows-machine-config-operator`. - -.. Click the *Enable Operator recommended cluster monitoring on the Namespace* checkbox to enable cluster monitoring for the WMCO. - -.. Select an *Approval Strategy*. -+ -* The *Automatic* strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available. -+ -* The *Manual* strategy requires a user with appropriate credentials to approve the Operator update. - -//TODO add image of Installation page when official Operator is available. - -. Click *Install*. The WMCO is now listed on the *Installed Operators* page. -+ -[NOTE] -==== -The WMCO is installed automatically into the namespace you defined, like `openshift-windows-machine-config-operator`. -==== - -. Verify that the *Status* shows *Succeeded* to confirm successful installation of the WMCO. diff --git a/modules/integrate-ci-check-existing-build-phase-policies.adoc b/modules/integrate-ci-check-existing-build-phase-policies.adoc new file mode 100644 index 000000000000..bfec2ff57f2c --- /dev/null +++ b/modules/integrate-ci-check-existing-build-phase-policies.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +:_mod-docs-content-type: PROCEDURE +[id="integrate-ci-check-existing-build-phase-policies_{context}"] += Checking existing build-time policies + +Use the {product-title-short} portal to check any existing build-time policies that you have configured in {product-title}. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. Use global search to search for `Lifecycle Stage:Build`. +//TODO: Add link for global search diff --git a/modules/integrate-circle-ci.adoc b/modules/integrate-circle-ci.adoc new file mode 100644 index 000000000000..aeabf251d8cd --- /dev/null +++ b/modules/integrate-circle-ci.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +:_mod-docs-content-type: PROCEDURE +[id="integrate-circle-ci_{context}"] += Using CircleCI + +You can integrate {product-title} with CircleCI. + +.Prerequisites +* You have a token with `read` and `write` permissions for the `Image` resource. +* You have a username and password for your Docker Hub account. + +.Procedure +. Log in to CircleCI and open an existing project or create a new project. +. Click *Project Settings*. +. Click *Environment variables*. +. Click *Add variable* and create the following three environment variables: +** *Name*: *STACKROX_CENTRAL_HOST* - The DNS name or IP address of Central. +** *Name*: *ROX_API_TOKEN* - The API token to access {product-title}. +** *Name*: *DOCKERHUB_PASSWORD* - The password for your Docker Hub account. +** *Name*: *DOCKERHUB_USER* - The username for your Docker Hub account. +. Create a directory called `.circleci` in the root directory of your local code repository for your selected project, if you do not already have a CircleCI configuration file. +. Create a `config.yml` configuration file with the following lines in the `.circleci` directory: ++ +[source,yaml] +---- +version: 2 +jobs: + check-policy-compliance: + docker: + - image: 'circleci/node:latest' + auth: + username: $DOCKERHUB_USER + password: $DOCKERHUB_PASSWORD + steps: + - checkout + - run: + name: Install roxctl + command: | + curl -H "Authorization: Bearer $ROX_API_TOKEN" https://$STACKROX_CENTRAL_HOST:443/api/cli/download/roxctl-linux -o roxctl && chmod +x ./roxctl + - run: + name: Scan images for policy deviations and vulnerabilities + command: | + ./roxctl image check --endpoint "$STACKROX_CENTRAL_HOST:443" --image "<your_registry/repo/image_name>" <1> + - run: + name: Scan deployment files for policy deviations + command: | + ./roxctl image check --endpoint "$STACKROX_CENTRAL_HOST:443" --image "<your_deployment_file>" <2> + # Important note: This step assumes the YAML file you'd like to test is located in the project. +workflows: + version: 2 + build_and_test: + jobs: + - check-policy-compliance +---- +<1> Replace `<your_registry/repo/image_name>` with your registry and image path. +<2> Replace `<your_deployment_file>` with the path to your deployment file. ++ +[NOTE] +==== +If you already have a `config.yml` file for CircleCI in your repository, add a new jobs section with the specified details in your existing configuration file. +==== +. After you commit the configuration file to your repository, go to the *Jobs* queue in your CircleCI dashboard to verify the build policy enforcement. diff --git a/modules/integrate-splunk-enable-http-event-collector.adoc b/modules/integrate-splunk-enable-http-event-collector.adoc new file mode 100644 index 000000000000..14f996b97de4 --- /dev/null +++ b/modules/integrate-splunk-enable-http-event-collector.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-splunk.adoc +:_mod-docs-content-type: PROCEDURE +[id="integrate-splunk-enable-http-event-collector_{context}"] += Enabling HTTP event collector + +You must enable HTTP event collector tokens before you can receive events. + +.Procedure +. In your Splunk dashboard, go to *Settings* -> *Data inputs*. +. Click *HTTP Event Collector*. +. Click *Global Settings*. +. In the dialog that opens, click *Enabled* and then click *Save*. diff --git a/modules/integrate-with-clair.adoc b/modules/integrate-with-clair.adoc new file mode 100644 index 000000000000..8f83f89a5fc4 --- /dev/null +++ b/modules/integrate-with-clair.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-vulnerability-scanners.adoc +:_mod-docs-content-type: PROCEDURE +[id="integrate-with-clair_{context}"] += Integrating with Clair + +Beginning with version 4.4, Clair scanning features are available in the new {product-title-short} scanner, Scanner V4, and do not require a separate integration. The instructions in this section are only required if you are using the Clair V4 scanner. + +Note the following guidance: + +* Starting with {product-title-short} 3.74, Red{nbsp}Hat deprecated the previous CoreOS Clair integration in favor of Clair V4 integration. A separate integration was required to use the Clair V4 Scanner. Beginning with version 4.4, this integration is no longer required if you are using Scanner V4. +* There is no planned support for the link:https://quay.github.io/clair/concepts/authentication.html[JWT-based authentication] option for Clair V4 integration in the next {product-title-short} 4.0 version. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Clair v4*. +. Click *New integration*. +. Enter the details for the following fields: +.. *Integration name*: The name of the integration. +.. *Endpoint*: The address of the scanner. +. (Optional) If you are not using a TLS certificate when connecting to the registry, select *Disable TLS certificate validation (insecure)*. +. (Optional) Click *Test* to test that the integration with the selected registry is working. +. Click *Save*. diff --git a/modules/integrate-with-gcr-container-analysis.adoc b/modules/integrate-with-gcr-container-analysis.adoc new file mode 100644 index 000000000000..a3cbe08a611c --- /dev/null +++ b/modules/integrate-with-gcr-container-analysis.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-vulnerability-scanners.adoc +:_mod-docs-content-type: PROCEDURE +[id="integrate-with-gcr-container-analysis_{context}"] += Integrating with Google Container Registry + +You can integrate {product-title} with Google Container Registry (GCR) for container analysis and vulnerability scanning. + +.Prerequisites +* You must have a service account key for the Google Container Registry. +* The associated service account has access to the registry. +See link:https://cloud.google.com/container-registry/docs/access-control[Configuring access control] for information about granting users and other projects access to GCR. +* If you are using link:https://cloud.google.com/container-registry/docs/container-analysis[GCR Container Analysis], you have granted the following roles to the service account: +** Container Analysis Notes Viewer +** Container Analysis Occurrences Viewer +** Storage Object Viewer + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Google Container Registry*. ++ +The *Configure image integration* modal box opens. +. Click *New Integration*. +. Enter the details for the following fields: +.. *Integration Name*: The name of the integration. +.. *Types*: Select *Scanner*. +.. *Registry Endpoint*: The address of the registry. +.. *Project*: The Google Cloud project name. +.. *Service account key (JSON)* Your service account key for authentication. +. Select *Test* (`checkmark` icon) to test that the integration with the selected registry is working. +. Select *Create* (`save` icon) to create the configuration. diff --git a/modules/integrate-with-qcr-scanner.adoc b/modules/integrate-with-qcr-scanner.adoc new file mode 100644 index 000000000000..767b189234a4 --- /dev/null +++ b/modules/integrate-with-qcr-scanner.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-vulnerability-scanners.adoc +:_mod-docs-content-type: PROCEDURE +[id="integrate-with-qcr-scanner_{context}"] += Integrating with Quay Container Registry to scan images + +You can integrate {product-title} with Quay Container Registry for scanning images. + +.Prerequisites +* You must have an OAuth token for authentication with the Quay Container Registry to scan images. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Red{nbsp}Hat Quay.io*. +. Click *New integration*. +. Enter the *Integration name.* +. Under *Type*, select *Scanner*. (If you are also integrating with the registry, select *Scanner + Registry*.) Enter information in the following fields: +** *Endpoint*: Enter the address of the registry. +** *OAuth token*: Enter the OAuth token that {product-title-short} uses to authenticate by using the API. +** Optional: *Robot username*: If you are configuring *Scanner + Registry* and are accessing the registry by using a Quay robot account, enter the user name in the format `_<namespace>+<accountname>_`. +** Optional: *Robot password*: If you are configuring *Scanner + Registry* and are accessing the registry by using a Quay robot account, enter the password for the robot account user name. +. Optional: If you are not using a TLS certificate when connecting to the registry, select *Disable TLS certificate validation (insecure)*. +. Optional: To create the integration without testing, select *Create integration without testing*. +. Select *Save*. + +[NOTE] +==== +If you are editing a Quay integration but do not want to update your credentials, verify that *Update stored credentials* is not selected. +==== \ No newline at end of file diff --git a/modules/interacting-serverless-apps-http2-gRPC.adoc b/modules/interacting-serverless-apps-http2-gRPC.adoc deleted file mode 100644 index d6f4066a427a..000000000000 --- a/modules/interacting-serverless-apps-http2-gRPC.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/serving-creating-managing-apps.adoc - -[id="interacting-serverless-apps-http2-gRPC_{context}"] -= Interacting with a serverless application using HTTP2 and gRPC - -{ServerlessProductName} supports only insecure or edge-terminated routes. - -Insecure or edge-terminated routes do not support HTTP2 on {product-title}. -These routes also do not support gRPC because gRPC is transported by HTTP2. - -If you use these protocols in your application, you must call the application using the ingress gateway directly. -To do this you must find the ingress gateway's public address and the application's specific host. - -.Procedure - -. Find the application host. See the instructions in _Verifying your serverless application deployment_. -. Find the ingress gateway's public address: -+ - -[source,terminal] ----- -$ oc -n knative-serving-ingress get svc kourier ----- - -+ -.Example output -+ - -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -kourier LoadBalancer 172.30.51.103 a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com 80:31380/TCP,443:31390/TCP 67m ----- - -+ -The public address is surfaced in the `EXTERNAL-IP` field, and in this case is `a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com`. - -. Manually set the host header of your HTTP request to the application’s host, but direct the request itself against the public address of the ingress gateway. -+ - -[source,terminal] ----- -$ curl -H "Host: hello-default.example.com" a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com ----- - -+ -.Example output -[source,terminal] ----- -Hello Serverless! ----- - -+ -You can also make a gRPC request by setting the authority to the application’s host, while directing the request against the ingress gateway directly: -+ - -[source,yaml] ----- -grpc.Dial( - "a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com:80", - grpc.WithAuthority("hello-default.example.com:80"), - grpc.WithInsecure(), -) ----- - -+ -[NOTE] -==== -Ensure that you append the respective port, 80 by default, to both hosts as shown in the previous example. -==== diff --git a/modules/introduction-to-rhacs.adoc b/modules/introduction-to-rhacs.adoc new file mode 100644 index 000000000000..17d15f0cd50e --- /dev/null +++ b/modules/introduction-to-rhacs.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_mod-docs-content-type: CONCEPT +[id="introduction-to-rhacs_{context}"] += Introduction to {product-title-short} + +{rh-rhacs-first} is an enterprise-ready, Kubernetes-native container security solution that helps you build, deploy, and run cloud-native applications more securely. + +{rh-rhacscs-first} provides Kubernetes-native security as a service. +With {product-title-managed-short}, Red{nbsp}Hat maintains, upgrades, and manages your Central services. + +Central services include the user interface (UI), data storage, {product-title-short} application programming interface (API), and image scanning capabilities. +You deploy your Central service through the link:https://console.redhat.com/[Red{nbsp}Hat Hybrid Cloud Console.] When you create a new ACS instance, Red{nbsp}Hat creates your individual control plane for {product-title-short}. + +{product-title-managed-short} allows you to secure self-managed clusters that communicate with a Central instance. +The clusters you secure, called Secured Clusters, are managed by you, and not by Red{nbsp}Hat. +Secured Cluster services include optional vulnerability scanning services, admission control services, and data collection services used for runtime monitoring and compliance. +You install Secured Cluster services on any OpenShift or Kubernetes cluster you want to secure. \ No newline at end of file diff --git a/modules/investigating-etcd-installation-issues.adoc b/modules/investigating-etcd-installation-issues.adoc deleted file mode 100644 index 4ad393e06399..000000000000 --- a/modules/investigating-etcd-installation-issues.adoc +++ /dev/null @@ -1,103 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="investigating-etcd-installation-issues_{context}"] -= Investigating etcd installation issues - -If you experience etcd issues during installation, you can check etcd pod status and collect etcd pod logs. You can also verify etcd DNS records and check DNS availability on master nodes. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have SSH access to your hosts. -* You have the fully qualified domain names of the master nodes. - -.Procedure - -. Check the status of etcd pods. -.. Review the status of pods in the `openshift-etcd` namespace: -+ -[source,terminal] ----- -$ oc get pods -n openshift-etcd ----- -+ -.. Review the status of pods in the `openshift-etcd-operator` namespace: -+ -[source,terminal] ----- -$ oc get pods -n openshift-etcd-operator ----- - -. If any of the pods listed by the previous commands are not showing a `Running` or a `Completed` status, gather diagnostic information for the pod. -.. Review events for the pod: -+ -[source,terminal] ----- -$ oc describe pod/<pod_name> -n <namespace> ----- -+ -.. Inspect the pod's logs: -+ -[source,terminal] ----- -$ oc logs pod/<pod_name> -n <namespace> ----- -+ -.. If the pod has more than one container, the preceding command will create an error, and the container names will be provided in the error message. Inspect logs for each container: -+ -[source,terminal] ----- -$ oc logs pod/<pod_name> -c <container_name> -n <namespace> ----- - -. If the API is not functional, review etcd pod and container logs on each master node by using SSH instead. Replace `<master-node>.<cluster_name>.<base_domain>` with appropriate values. -.. List etcd pods on each master node: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl pods --name=etcd- ----- -+ -.. For any pods not showing `Ready` status, inspect pod status in detail. Replace `<pod_id>` with the pod's ID listed in the output of the preceding command: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl inspectp <pod_id> ----- -+ -.. List containers related to a pod: -+ -// TODO: Once https://bugzilla.redhat.com/show_bug.cgi?id=1858239 has been resolved, replace the `grep` command below: -//[source,terminal] -//---- -//$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl ps --pod=<pod_id> -//---- -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl ps | grep '<pod_id>' ----- -+ -.. For any containers not showing `Ready` status, inspect container status in detail. Replace `<container_id>` with container IDs listed in the output of the preceding command: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl inspect <container_id> ----- -+ -.. Review the logs for any containers not showing a `Ready` status. Replace `<container_id>` with the container IDs listed in the output of the preceding command: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl logs -f <container_id> ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. Before attempting to collect diagnostic data over SSH, review whether the data collected by running `oc adm must gather` and other `oc` commands is sufficient instead. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>`. -==== -+ -. Validate primary and secondary DNS server connectivity from master nodes. diff --git a/modules/investigating-kernel-crashes.adoc b/modules/investigating-kernel-crashes.adoc deleted file mode 100644 index da04748e27f6..000000000000 --- a/modules/investigating-kernel-crashes.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-operating-system-issues.adoc - -[id="investigating-kernel-crashes"] -= Investigating kernel crashes - -== Enabling kdump - -The `kdump` service, included in `kexec-tools`, provides a crash-dumping mechanism. You can use this service to save the contents of the system’s memory for later analysis. - -The `kdump` service is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. - -For more information about the support scope of Red Hat Technology Preview -features, see https://access.redhat.com/support/offerings/techpreview/. - -{op-system} ships with `kexec-tools`, but manual configuration is required to enable `kdump`. - -.Procedure - -Perform the following steps to enable `kdump` on {op-system}. - -. To reserve memory for the crash kernel during the first kernel booting, provide kernel arguments by entering the following command: -+ -[source, terminal] ----- -# rpm-ostree kargs --append='crashkernel=256M' ----- - -. By default, the path in which the vmcore will be saved is `/var/crash`. It is also possible to write the dump over the network or to some other location on the local system by editing `/etc/kdump.conf`. For example, assuming `/var/usrlocal/cores` exists, enter the following command to edit `/etc/kdump.conf` to save the vmcore to `/var/usrlocal/cores`: -+ -[source, terminal] ----- -# sed -i "s/^path.*/path \/var\/usrlocal\/cores/" /etc/kdump.conf ----- -+ -For additional information, see `kdump.conf`, a manual page for the `/etc/kdump.conf` configuration file containing the full documentation of available options, and note the comments in `/etc/kdump.conf` and `/etc/sysconfig/kdump`. -ifdef::openshift-enterprise[] -Also refer to the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/system_design_guide/installing-and-configuring-kdump_system-design-guide#configuring-the-kdump-target_configuring-kdump-on-the-command-line[RHEL `kdump` documentation] for further information on configuring the dump target. -endif::[] -+ - -ifdef::openshift-enterprise[] -. Because `kdump` has trouble finding the correct bootimage location on {op-system}, the `KDUMP_BOOTDIR` variable must be manually set in `/etc/kdump.conf`. You can use `/proc/cmdline` to figure out the `ostree` boot location. For example: -+ -[source, terminal] ----- -# BOOT_LOC=/boot$(cat /proc/cmdline | egrep -o "/ostree/.*/vmlinuz" | sed -e "s|/vmlinuz||g") -# sed -i "s|^#KDUMP_BOOTDIR=\"/boot\"|KDUMP_BOOTDIR=\"${BOOT_LOC}\"|" /etc/sysconfig/kdump ----- - -. Configure `/etc/sysconfig/kdump` to not use the default link:https://man7.org/linux/man-pages/man2/kexec_file_load.2.html[file-based `kexec` syscall] for loading the crash kernel. -+ -[source, terminal] ----- -# sed -i "s|^KEXEC_ARGS=\"-s\"|KEXEC_ARGS=\"\"|" /etc/sysconfig/kdump ----- -endif::[] - -. Enable the `kdump` systemd service. -+ -[source, terminal] ----- -# systemctl enable kdump.service ----- - -. Reboot your system. -+ -[source, terminal] ----- -# systemctl reboot ----- - -. Ensure that `kdump` has loaded a crash kernel by checking that the `kdump.service` has started and exited successfully and that `cat /sys/kernel/kexec_crash_loaded` prints `1`. - -== Enabling kdump on day-1 -The `kdump` service is intended to be enabled per node to debug kernel problems. Because there are costs to having `kdump` enabled, and these costs accumulate with each additional `kdump`-enabled node, it is recommended that `kdump` only be enabled on each node as needed. Potential costs of enabling `kdump` on each node include: - -* Less available RAM due to memory being reserved for the crash kernel. -* Node unavailability while the kernel is dumping the core. -* Additional storage space being used to store the crash dumps. -* Not being production-ready because the `kdump` service is in link:https://access.redhat.com/support/offerings/techpreview[Technology Preview]. - -If you are aware of the downsides and trade-offs of having the `kdump` service enabled, it is possible to enable `kdump` in a cluster-wide fashion. Although machine-specific machine configs are not yet supported, you can perform the previous steps through a `systemd` unit in a `MachineConfig` object on day-1 and have kdump enabled on all nodes in the cluster. You can create a `MachineConfig` object and inject that object into the set of manifest files used by Ignition during cluster setup. See "Customizing nodes" in the _Installing -> Installation configuration_ section for more information and examples on how to use Ignition configs. - -== Testing the kdump configuration - -ifdef::openshift-enterprise[] -See the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/system_design_guide/installing-and-configuring-kdump_system-design-guide#testing-the-kdump-configuration_installing-and-configuring-kdump[Testing the kdump configuration] section in the {op-system-base} documentation for `kdump`. -endif::[] - -ifdef::openshift-origin[] -See the link:https://fedoraproject.org/wiki/How_to_use_kdump_to_debug_kernel_crashes#Step_2:_Capturing_the_Dump[Capturing the Dump] section in the {op-system-base} documentation for `kdump`. -endif::[] - -== Analyzing a core dump - -ifdef::openshift-enterprise[] -See the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/system_design_guide/installing-and-configuring-kdump_system-design-guide#analyzing-a-core-dump_installing-and-configuring-kdump[Analyzing a core dump] section in the {op-system-base} documentation for `kdump`. -endif::[] - -ifdef::openshift-origin[] -See the link:https://fedoraproject.org/wiki/How_to_use_kdump_to_debug_kernel_crashes#Step_3:_Dump_Analysis[Dump Analysis] section in the {op-system-base} documentation for `kdump`. -endif::[] - -.Additional resources -ifdef::openshift-origin[] -* link:https://docs.fedoraproject.org/en-US/fedora-coreos/debugging-kernel-crashes/[Fedora CoreOS Docs on debugging kernel crashes] -* link:https://fedoraproject.org/wiki/How_to_use_kdump_to_debug_kernel_crashes[Setting up kdump in Fedora] -endif::[] -ifdef::openshift-enterprise[] -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/system_design_guide/installing-and-configuring-kdump_system-design-guide[Setting up kdump in RHEL] -endif::[] -* link:https://www.kernel.org/doc/html/latest/admin-guide/kdump/kdump.html[Linux kernel documentation for kdump] -* kdump.conf(5) — a manual page for the `/etc/kdump.conf` configuration file containing the full documentation of available options -* kexec(8) — a manual page for `kexec` -* link:https://access.redhat.com/site/solutions/6038[Red Hat Knowledgebase article] regarding `kexec` and `kdump`. diff --git a/modules/investigating-kubelet-api-installation-issues.adoc b/modules/investigating-kubelet-api-installation-issues.adoc deleted file mode 100644 index 88211d572987..000000000000 --- a/modules/investigating-kubelet-api-installation-issues.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="investigating-kubelet-api-installation-issues_{context}"] -= Investigating master node kubelet and API server issues - -To investigate master node kubelet and API server issues during installation, check DNS, DHCP, and load balancer functionality. Also, verify that certificates have not expired. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have SSH access to your hosts. -* You have the fully qualified domain names of the master nodes. - -.Procedure - -. Verify that the API server's DNS record directs the kubelet on master nodes to [x-]`https://api-int.<cluster_name>.<base_domain>:6443`. Ensure that the record references the load balancer. - -. Ensure that the load balancer's port 6443 definition references each master node. - -. Check that unique master node host names have been provided by DHCP. - -. Inspect the `kubelet.service` journald unit logs on each master node. -.. Retrieve the logs using `oc`: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u kubelet ----- -+ -.. If the API is not functional, review the logs using SSH instead. Replace `<master-node>.<cluster_name>.<base_domain>` with appropriate values: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> journalctl -b -f -u kubelet.service ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. Before attempting to collect diagnostic data over SSH, review whether the data collected by running `oc adm must gather` and other `oc` commands is sufficient instead. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>`. -==== -+ -. Check for certificate expiration messages in the master node kubelet logs. -.. Retrieve the log using `oc`: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u kubelet | grep -is 'x509: certificate has expired' ----- -+ -.. If the API is not functional, review the logs using SSH instead. Replace `<master-node>.<cluster_name>.<base_domain>` with appropriate values: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> journalctl -b -f -u kubelet.service | grep -is 'x509: certificate has expired' ----- diff --git a/modules/investigating-master-node-installation-issues.adoc b/modules/investigating-master-node-installation-issues.adoc deleted file mode 100644 index 96445e8d01e3..000000000000 --- a/modules/investigating-master-node-installation-issues.adoc +++ /dev/null @@ -1,246 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="investigating-master-node-installation-issues_{context}"] -= Investigating master node installation issues - -If you experience master node installation issues, determine the master node, {product-title} software defined network (SDN), and network Operator status. Collect `kubelet.service`, `crio.service` journald unit logs, and master node container logs for visibility into master node agent, CRI-O container runtime, and pod activity. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have SSH access to your hosts. -* You have the fully qualified domain names of the bootstrap and master nodes. -* If you are hosting Ignition configuration files by using an HTTP server, you must have the HTTP server's fully qualified domain name and the port number. You must also have SSH access to the HTTP host. -+ -[NOTE] -==== -The initial `kubeadmin` password can be found in `<install_directory>/auth/kubeadmin-password` on the installation host. -==== - -.Procedure - -. If you have access to the master node's console, monitor the console until the node reaches the login prompt. During the installation, Ignition log messages are output to the console. - -. Verify Ignition file configuration. -+ -* If you are hosting Ignition configuration files by using an HTTP server. -+ -.. Verify the master node Ignition file URL. Replace `<http_server_fqdn>` with HTTP server's fully qualified domain name: -+ -[source,terminal] ----- -$ curl -I http://<http_server_fqdn>:<port>/master.ign <1> ----- -<1> The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. -+ -.. To verify that the Ignition file was received by the master node, query the HTTP server logs on the serving host. For example, if you are using an Apache web server to serve Ignition files: -+ -[source,terminal] ----- -$ grep -is 'master.ign' /var/log/httpd/access_log ----- -+ -If the master Ignition file is received, the associated `HTTP GET` log message will include a `200 OK` success status, indicating that the request succeeded. -+ -.. If the Ignition file was not received, check that it exists on the serving host directly. Ensure that the appropriate file and web server permissions are in place. -+ -* If you are using a cloud provider mechanism to inject Ignition configuration files into hosts as part of their initial deployment. -+ -.. Review the master node's console to determine if the mechanism is injecting the master node Ignition file correctly. - -. Check the availability of the master node's assigned storage device. - -. Verify that the master node has been assigned an IP address from the DHCP server. - -. Determine master node status. -.. Query master node status: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.. If one of the master nodes does not reach a `Ready` status, retrieve a detailed node description: -+ -[source,terminal] ----- -$ oc describe node <master_node> ----- -+ -[NOTE] -==== -It is not possible to run `oc` commands if an installation issue prevents the {product-title} API from running or if the kubelet is not running yet on each node: -==== -+ -. Determine {product-title} SDN status. -+ -.. Review `sdn-controller`, `sdn`, and `ovs` daemon set status, in the `openshift-sdn` namespace: -+ -[source,terminal] ----- -$ oc get daemonsets -n openshift-sdn ----- -+ -.. If those resources are listed as `Not found`, review pods in the `openshift-sdn` namespace: -+ -[source,terminal] ----- -$ oc get pods -n openshift-sdn ----- -+ -.. Review logs relating to failed {product-title} SDN pods in the `openshift-sdn` namespace: -+ -[source,terminal] ----- -$ oc logs <sdn_pod> -n openshift-sdn ----- - -. Determine cluster network configuration status. -.. Review whether the cluster's network configuration exists: -+ -[source,terminal] ----- -$ oc get network.config.openshift.io cluster -o yaml ----- -+ -.. If the installer failed to create the network configuration, generate the Kubernetes manifests again and review message output: -+ -[source,terminal] ----- -$ ./openshift-install create manifests ----- -+ -.. Review the pod status in the `openshift-network-operator` namespace to determine whether the Cluster Network Operator (CNO) is running: -+ -[source,terminal] ----- -$ oc get pods -n openshift-network-operator ----- -+ -.. Gather network Operator pod logs from the `openshift-network-operator` namespace: -+ -[source,terminal] ----- -$ oc logs pod/<network_operator_pod_name> -n openshift-network-operator ----- - -. Monitor `kubelet.service` journald unit logs on master nodes, after they have booted. This provides visibility into master node agent activity. -.. Retrieve the logs using `oc`: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u kubelet ----- -+ -.. If the API is not functional, review the logs using SSH instead. Replace `<master-node>.<cluster_name>.<base_domain>` with appropriate values: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> journalctl -b -f -u kubelet.service ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. Before attempting to collect diagnostic data over SSH, review whether the data collected by running `oc adm must gather` and other `oc` commands is sufficient instead. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>`. -==== -+ -. Retrieve `crio.service` journald unit logs on master nodes, after they have booted. This provides visibility into master node CRI-O container runtime activity. -.. Retrieve the logs using `oc`: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u crio ----- -+ -.. If the API is not functional, review the logs using SSH instead: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> journalctl -b -f -u crio.service ----- - -. Collect logs from specific subdirectories under `/var/log/` on master nodes. -.. Retrieve a list of logs contained within a `/var/log/` subdirectory. The following example lists files in `/var/log/openshift-apiserver/` on all master nodes: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master --path=openshift-apiserver ----- -+ -.. Inspect a specific log within a `/var/log/` subdirectory. The following example outputs `/var/log/openshift-apiserver/audit.log` contents from all master nodes: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master --path=openshift-apiserver/audit.log ----- -+ -.. If the API is not functional, review the logs on each node using SSH instead. The following example tails `/var/log/openshift-apiserver/audit.log`: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo tail -f /var/log/openshift-apiserver/audit.log ----- - -. Review master node container logs using SSH. -.. List the containers: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl ps -a ----- -+ -.. Retrieve a container's logs using `crictl`: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo crictl logs -f <container_id> ----- - -. If you experience master node configuration issues, verify that the MCO, MCO endpoint, and DNS record are functioning. The Machine Config Operator (MCO) manages operating system configuration during the installation procedure. Also verify system clock accuracy and certificate validity. -.. Test whether the MCO endpoint is available. Replace `<cluster_name>` with appropriate values: -+ -[source,terminal] ----- -$ curl https://api-int.<cluster_name>:22623/config/master ----- -+ -.. If the endpoint is unresponsive, verify load balancer configuration. Ensure that the endpoint is configured to run on port 22623. -+ -.. Verify that the MCO endpoint's DNS record is configured and resolves to the load balancer. -... Run a DNS lookup for the defined MCO endpoint name: -+ -[source,terminal] ----- -$ dig api-int.<cluster_name> @<dns_server> ----- -+ -... Run a reverse lookup to the assigned MCO IP address on the load balancer: -+ -[source,terminal] ----- -$ dig -x <load_balancer_mco_ip_address> @<dns_server> ----- -+ -.. Verify that the MCO is functioning from the bootstrap node directly. Replace `<bootstrap_fqdn>` with the bootstrap node's fully qualified domain name: -+ -[source,terminal] ----- -$ ssh core@<bootstrap_fqdn> curl https://api-int.<cluster_name>:22623/config/master ----- -+ -.. System clock time must be synchronized between bootstrap, master, and worker nodes. Check each node's system clock reference time and time synchronization statistics: -+ -[source,terminal] ----- -$ ssh core@<node>.<cluster_name>.<base_domain> chronyc tracking ----- -+ -.. Review certificate validity: -+ -[source,terminal] ----- -$ openssl s_client -connect api-int.<cluster_name>:22623 | openssl x509 -noout -text ----- diff --git a/modules/investigating-why-windows-machine-compute-node.adoc b/modules/investigating-why-windows-machine-compute-node.adoc deleted file mode 100644 index cabad03b981e..000000000000 --- a/modules/investigating-why-windows-machine-compute-node.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc - -[id="investigating-why-windows-machine-compute-node_{context}"] -= Investigating why Windows Machine does not become compute node - -There are various reasons why a Windows Machine does not become a compute node. The best way to investigate this problem is to collect the Windows Machine Config Operator (WMCO) logs. - -.Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You have created a Windows machine set. - -.Procedure - -* Run the following command to collect the WMCO logs: -+ -[source,terminal] ----- -$ oc logs -f $(oc get pods -o jsonpath={.items[0].metadata.name} -n openshift-windows-machine-config-operator) -n openshift-windows-machine-config-operator ----- diff --git a/modules/investigating-worker-node-installation-issues.adoc b/modules/investigating-worker-node-installation-issues.adoc deleted file mode 100644 index 6086cedae32b..000000000000 --- a/modules/investigating-worker-node-installation-issues.adoc +++ /dev/null @@ -1,223 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="investigating-worker-node-installation-issues_{context}"] -= Investigating worker node installation issues - -If you experience worker node installation issues, you can review the worker node status. Collect `kubelet.service`, `crio.service` journald unit logs and the worker node container logs for visibility into the worker node agent, CRI-O container runtime and pod activity. Additionally, you can check the Ignition file and Machine API Operator functionality. If worker node post-installation configuration fails, check Machine Config Operator (MCO) and DNS functionality. You can also verify system clock synchronization between the bootstrap, master, and worker nodes, and validate certificates. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have SSH access to your hosts. -* You have the fully qualified domain names of the bootstrap and worker nodes. -* If you are hosting Ignition configuration files by using an HTTP server, you must have the HTTP server's fully qualified domain name and the port number. You must also have SSH access to the HTTP host. -+ -[NOTE] -==== -The initial `kubeadmin` password can be found in `<install_directory>/auth/kubeadmin-password` on the installation host. -==== - -.Procedure - -. If you have access to the worker node's console, monitor the console until the node reaches the login prompt. During the installation, Ignition log messages are output to the console. - -. Verify Ignition file configuration. -+ -* If you are hosting Ignition configuration files by using an HTTP server. -+ -.. Verify the worker node Ignition file URL. Replace `<http_server_fqdn>` with HTTP server's fully qualified domain name: -+ -[source,terminal] ----- -$ curl -I http://<http_server_fqdn>:<port>/worker.ign <1> ----- -<1> The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. -+ -.. To verify that the Ignition file was received by the worker node, query the HTTP server logs on the HTTP host. For example, if you are using an Apache web server to serve Ignition files: -+ -[source,terminal] ----- -$ grep -is 'worker.ign' /var/log/httpd/access_log ----- -+ -If the worker Ignition file is received, the associated `HTTP GET` log message will include a `200 OK` success status, indicating that the request succeeded. -+ -.. If the Ignition file was not received, check that it exists on the serving host directly. Ensure that the appropriate file and web server permissions are in place. -+ -* If you are using a cloud provider mechanism to inject Ignition configuration files into hosts as part of their initial deployment. -+ -.. Review the worker node's console to determine if the mechanism is injecting the worker node Ignition file correctly. - -. Check the availability of the worker node's assigned storage device. - -. Verify that the worker node has been assigned an IP address from the DHCP server. - -. Determine worker node status. -.. Query node status: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.. Retrieve a detailed node description for any worker nodes not showing a `Ready` status: -+ -[source,terminal] ----- -$ oc describe node <worker_node> ----- -+ -[NOTE] -==== -It is not possible to run `oc` commands if an installation issue prevents the {product-title} API from running or if the kubelet is not running yet on each node. -==== -+ -. Unlike master nodes, worker nodes are deployed and scaled using the Machine API Operator. Check the status of the Machine API Operator. -.. Review Machine API Operator pod status: -+ -[source,terminal] ----- -$ oc get pods -n openshift-machine-api ----- -+ -.. If the Machine API Operator pod does not have a `Ready` status, detail the pod's events: -+ -[source,terminal] ----- -$ oc describe pod/<machine_api_operator_pod_name> -n openshift-machine-api ----- -+ -.. Inspect `machine-api-operator` container logs. The container runs within the `machine-api-operator` pod: -+ -[source,terminal] ----- -$ oc logs pod/<machine_api_operator_pod_name> -n openshift-machine-api -c machine-api-operator ----- -+ -.. Also inspect `kube-rbac-proxy` container logs. The container also runs within the `machine-api-operator` pod: -+ -[source,terminal] ----- -$ oc logs pod/<machine_api_operator_pod_name> -n openshift-machine-api -c kube-rbac-proxy ----- - -. Monitor `kubelet.service` journald unit logs on worker nodes, after they have booted. This provides visibility into worker node agent activity. -.. Retrieve the logs using `oc`: -+ -[source,terminal] ----- -$ oc adm node-logs --role=worker -u kubelet ----- -+ -.. If the API is not functional, review the logs using SSH instead. Replace `<worker-node>.<cluster_name>.<base_domain>` with appropriate values: -+ -[source,terminal] ----- -$ ssh core@<worker-node>.<cluster_name>.<base_domain> journalctl -b -f -u kubelet.service ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. Before attempting to collect diagnostic data over SSH, review whether the data collected by running `oc adm must gather` and other `oc` commands is sufficient instead. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>`. -==== -+ -. Retrieve `crio.service` journald unit logs on worker nodes, after they have booted. This provides visibility into worker node CRI-O container runtime activity. -.. Retrieve the logs using `oc`: -+ -[source,terminal] ----- -$ oc adm node-logs --role=worker -u crio ----- -+ -.. If the API is not functional, review the logs using SSH instead: -+ -[source,terminal] ----- -$ ssh core@<worker-node>.<cluster_name>.<base_domain> journalctl -b -f -u crio.service ----- - -. Collect logs from specific subdirectories under `/var/log/` on worker nodes. -.. Retrieve a list of logs contained within a `/var/log/` subdirectory. The following example lists files in `/var/log/sssd/` on all worker nodes: -+ -[source,terminal] ----- -$ oc adm node-logs --role=worker --path=sssd ----- -+ -.. Inspect a specific log within a `/var/log/` subdirectory. The following example outputs `/var/log/sssd/audit.log` contents from all worker nodes: -+ -[source,terminal] ----- -$ oc adm node-logs --role=worker --path=sssd/sssd.log ----- -+ -.. If the API is not functional, review the logs on each node using SSH instead. The following example tails `/var/log/sssd/sssd.log`: -+ -[source,terminal] ----- -$ ssh core@<worker-node>.<cluster_name>.<base_domain> sudo tail -f /var/log/sssd/sssd.log ----- - -. Review worker node container logs using SSH. -.. List the containers: -+ -[source,terminal] ----- -$ ssh core@<worker-node>.<cluster_name>.<base_domain> sudo crictl ps -a ----- -+ -.. Retrieve a container's logs using `crictl`: -+ -[source,terminal] ----- -$ ssh core@<worker-node>.<cluster_name>.<base_domain> sudo crictl logs -f <container_id> ----- - -. If you experience worker node configuration issues, verify that the MCO, MCO endpoint, and DNS record are functioning. The Machine Config Operator (MCO) manages operating system configuration during the installation procedure. Also verify system clock accuracy and certificate validity. -.. Test whether the MCO endpoint is available. Replace `<cluster_name>` with appropriate values: -+ -[source,terminal] ----- -$ curl https://api-int.<cluster_name>:22623/config/worker ----- -+ -.. If the endpoint is unresponsive, verify load balancer configuration. Ensure that the endpoint is configured to run on port 22623. -+ -.. Verify that the MCO endpoint's DNS record is configured and resolves to the load balancer. -... Run a DNS lookup for the defined MCO endpoint name: -+ -[source,terminal] ----- -$ dig api-int.<cluster_name> @<dns_server> ----- -+ -... Run a reverse lookup to the assigned MCO IP address on the load balancer: -+ -[source,terminal] ----- -$ dig -x <load_balancer_mco_ip_address> @<dns_server> ----- -+ -.. Verify that the MCO is functioning from the bootstrap node directly. Replace `<bootstrap_fqdn>` with the bootstrap node's fully qualified domain name: -+ -[source,terminal] ----- -$ ssh core@<bootstrap_fqdn> curl https://api-int.<cluster_name>:22623/config/worker ----- -+ -.. System clock time must be synchronized between bootstrap, master, and worker nodes. Check each node's system clock reference time and time synchronization statistics: -+ -[source,terminal] ----- -$ ssh core@<node>.<cluster_name>.<base_domain> chronyc tracking ----- -+ -.. Review certificate validity: -+ -[source,terminal] ----- -$ openssl s_client -connect api-int.<cluster_name>:22623 | openssl x509 -noout -text ----- diff --git a/modules/ipi-install-additional-install-config-parameters.adoc b/modules/ipi-install-additional-install-config-parameters.adoc deleted file mode 100644 index 4b2ae732d11c..000000000000 --- a/modules/ipi-install-additional-install-config-parameters.adoc +++ /dev/null @@ -1,246 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="additional-install-config-parameters_{context}"] -= Additional `install-config` parameters - -See the following tables for the required parameters, the `hosts` parameter, -and the `bmc` parameter for the `install-config.yaml` file. - -.Required parameters -|=== -|Parameters |Default |Description - - -| [[basedomain]] `baseDomain` -| -| The domain name for the cluster. For example, `example.com`. - -| [[sshkey]] `sshKey` -| -| The `sshKey` configuration setting contains the key in the `~/.ssh/id_rsa.pub` file required to access the control plane nodes and worker nodes. Typically, this key is from the `provisioner` node. - -| [[pullsecret]] `pullSecret` -| -| The `pullSecret` configuration setting contains a copy of the pull secret downloaded from the link:https://cloud.redhat.com/openshift/install/metal/user-provisioned[Install OpenShift on Bare Metal] page when preparing the provisioner node. - - -a|[[metadataname]] ----- -metadata: - name: ----- -| -|The name to be given to the {product-title} cluster. For example, `openshift`. - - -a|[[machinecidr]] ----- -networking: - machineCIDR: ----- -| -|The public CIDR (Classless Inter-Domain Routing) of the external network. For example, `10.0.0.0/24` -ifdef::upstream[] -ifeval::[{release} >= 4.5] -or `2620:52:0:1302::/64` -endif::[] -endif::[] -. - -a|[[workername]] ----- -compute: - - name: worker ----- -| -|The {product-title} cluster requires a name be provided for worker (or compute) nodes even if there are zero nodes. - - -a|[[computereplicas]] ----- -compute: - replicas: 2 ----- -| -|Replicas sets the number of worker (or compute) nodes in the {product-title} cluster. - - -a|[[controlplanename]] ----- -controlPlane: - name: master ----- -| -|The {product-title} cluster requires a name for control plane (master) nodes. - - -a|[[controlplanereplicas]] ----- -controlPlane: - replicas: 3 ----- -| -|Replicas sets the number of control plane (master) nodes included as part of the {product-title} cluster. - -ifeval::[{release} >= 4.4] -ifeval::[{release} <= 4.6] -a| [[provisioningNetworkInterface]]`provisioningNetworkInterface` | | The name of the network interface on control plane nodes connected to the -provisioning network. -endif::[] -endif::[] - - -| `defaultMachinePlatform` | | The default configuration used for machine pools without a platform configuration. - -| [[apivip]]`apiVIP` | `api.<clustername.clusterdomain>` | The VIP to use for internal API communication. - -This setting must either be provided or pre-configured in the DNS so that the -default name resolves correctly. - -| `disableCertificateVerification` | `False` | `redfish` and `redfish-virtualmedia` need this parameter to manage BMC addresses. The value should be `True` when using a self-signed certificate for BMC addresses. - -| [[ingressvip]]`ingressVIP` | `test.apps.<clustername.clusterdomain>` | The VIP to use for ingress traffic. - -ifeval::[{release} < 4.5] -Provide this setting or pre-configure it in the DNS so that the default name resolves correctly. -|[[dnsVIP]]`dnsVIP` | | The VIP to use for internal DNS communication. - -This setting has no default and must always be provided. -endif::[] - -|=== - - -[cols="1,1,3", options="header"] -.Optional Parameters -|=== -|Parameters -|Default -|Description - - -ifeval::[{release} > 4.3] -ifeval::[{release} < 4.6] -|`provisioningDHCPExternal` -| false -|Defines if the installer uses an external DHCP or the provisioner node DHCP. -endif::[] -endif::[] - -|`provisioningDHCPRange` -|`172.22.0.10,172.22.0.100` -|Defines the IP range for nodes on the `provisioning` network. - -a|`provisioningNetworkCIDR` -|`172.22.0.0/24` -|The CIDR for the network to use for provisioning. This option is required when not using the default address range on the `provisioning` network. - -|`clusterProvisioningIP` -|The third IP address of the `provisioningNetworkCIDR`. -|The IP address within the cluster where the provisioning services run. Defaults to the third IP address of the `provisioning` subnet. For example, `172.22.0.3`. - -|`bootstrapProvisioningIP` -|The second IP address of the `provisioningNetworkCIDR`. -|The IP address on the bootstrap VM where the provisioning services run while the installer is deploying the control plane (master) nodes. Defaults to the second IP address of the `provisioning` subnet. For example, `172.22.0.2` -ifeval::[{release} >= 4.5] -or `2620:52:0:1307::2` -endif::[] -. - -ifeval::[{release} == 4.6] -Set this parameter to an available IP address on the `baremetal` network when the `provisioningNetwork` configuration setting is set to `Disabled`. -endif::[] - -| `externalBridge` -| `baremetal` -| The name of the `baremetal` bridge of the hypervisor attached to the `baremetal` network. - -| `provisioningBridge` -| `provisioning` -| The name of the `provisioning` bridge on the `provisioner` host attached to the `provisioning` network. - -| `defaultMachinePlatform` -| -| The default configuration used for machine pools without a platform configuration. - -| `bootstrapOSImage` -| -| A URL to override the default operating system image for the bootstrap node. The URL must contain a SHA-256 hash of the image. For example: -`https://mirror.openshift.com/rhcos-<version>-qemu.qcow2.gz?sha256=<uncompressed_sha256>` -ifdef::upstream[] -ifeval::[{release} >= 4.5] - or `http://[2620:52:0:1307::1]/rhcos-<version>-qemu.x86_64.qcow2.gz?sha256=<uncompressed_sha256>` -endif::[] -endif::[] -. - -| `clusterOSImage` -| -| A URL to override the default operating system for cluster nodes. The URL must include a SHA-256 hash of the image. For example, `https://mirror.openshift.com/images/rhcos-<version>-openstack.qcow2.gz?sha256=<compressed_sha256>`. - - -| `provisioningNetwork` -| -| Set this parameter to `Disabled` to disable the requirement for a `provisioning` network. User may only do virtual media based provisioning, or bring up the cluster using assisted installation. If using power management, BMC's must be accessible from the machine networks. User must provide two IP addresses on the external network that are used for the provisioning services. -ifeval::[{release} >= 4.6] -Set this parameter to `managed`, which is the default, to fully manage the provisioning network, including DHCP, TFTP, and so on. - -Set this parameter to `unmanaged` to still enable the provisioning network but take care of manual configuration of DHCP. Virtual Media provisioning is recommended but PXE is still available if required. -endif::[] - -ifeval::[{release} == 4.6] -| `provisioningHostIP` -| -| Set this parameter to an available IP address on the `baremetal` network when the `provisioningNetwork` configuration setting is set to `Disabled`. -endif::[] - -ifeval::[{release} > 4.4] -| `httpProxy` -| -| Set this parameter to the appropriate HTTP proxy used within your environment. - -| `httpsProxy` -| -| Set this parameter to the appropriate HTTPS proxy used within your environment. - -| `noProxy` -| -| Set this parameter to the appropriate list of exclusions for proxy usage within your environment. -endif::[] - -|=== - -[id="hoststable"] -.Hosts - -The `hosts` parameter is a list of separate bare metal assets used to build the cluster. - -|=== -|Name |Default |Description -| [[name]]`name` -| -| The name of the `BareMetalHost` resource to associate with the details. For example, `openshift-master-0`. - - -| [[role]]`role` -| -| The role of the bare metal node. Either `master` or `worker`. - - -| `bmc` -| -| Connection details for the baseboard management controller. See the BMC addressing section for additional details. - - -| [[bootMACAddress]]`bootMACAddress` -| -| The MAC address of the NIC the host will use to boot on the `provisioning` network. - -ifeval::[{release} < 4.6] -| [[hardwareProfile]]`hardwareProfile` -| `default` -| This parameter exposes the device name that the installer attempts to deploy the {product-title} cluster for the control plane and worker nodes. The value defaults to `default` for control plane nodes and `unknown` for worker nodes. The list of profiles includes: `default`, `libvirt`, `dell`, `dell-raid`, and `openstack`. The `default` parameter attempts to install on `/dev/sda` of the {product-title} cluster nodes. -endif::[] -|=== diff --git a/modules/ipi-install-bmc-addressing.adoc b/modules/ipi-install-bmc-addressing.adoc deleted file mode 100644 index 83bc481a146f..000000000000 --- a/modules/ipi-install-bmc-addressing.adoc +++ /dev/null @@ -1,187 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="ipi-install-bmc-addressing_{context}"] - -= BMC addressing - -The `address` field for each `bmc` entry is a URL for connecting to the {product-title} cluster nodes, including the type of controller in the URL scheme and its location on the network. - -.IPMI - -IPMI hosts use `ipmi://<out-of-band-ip>:<port>` and defaults to port `623` if not specified. The following example demonstrates an IPMI configuration within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: ipmi://<out-of-band-ip> - username: <user> - password: <password> ----- - -.RedFish for HPE - -To enable RedFish, use `redfish://` or `redfish+http://` to disable TLS. The installer requires both the hostname or the IP address and the path to the system ID. The following example demonstrates a RedFish configuration within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: redfish://<out-of-band-ip>/redfish/v1/Systems/1 - username: <user> - password: <password> ----- - -While it is recommended to have a certificate of authority for the out-of-band management addresses, you must include `disableCertificateVerification: True` in the `bmc` configuration if using self-signed certificates. The following example demonstrates a RedFish configuration using the `disableCertificateVerification: True` configuration parameter within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: redfish://<out-of-band-ip>/redfish/v1/Systems/1 - username: <user> - password: <password> - disableCertificateVerification: True ----- - - -.RedFish for Dell - -To enable RedFish, use `redfish://` or `redfish+http://` to disable TLS. The installer requires both the hostname or the IP address and the path to the system ID. The following example demonstrates a RedFish configuration within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: redfish://<out-of-band-ip>/redfish/v1/Systems/System.Embedded.1 - username: <user> - password: <password> ----- - -While it is recommended to have a certificate of authority for the out-of-band management addresses, you must include `disableCertificateVerification: True` in the `bmc` configuration if using self-signed certificates. The following example demonstrates a RedFish configuration using the `disableCertificateVerification: True` configuration parameter within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: redfish://<out-of-band-ip>/redfish/v1/Systems/System.Embedded.1 - username: <user> - password: <password> - disableCertificateVerification: True ----- - -[NOTE] -==== -Currently RedFish is only supported on Dell with iDRAC firmware versions `4.20.20.20` through `04.40.00.00` for IPI on bare metal deployments. There is a known issue with version `04.40.00.00`. With iDRAC 9 firmware version `04.40.00.00`, the Virtual Console plug-in defaults to `eHTML5`, which causes problems with the *InsertVirtualMedia* workflow. Set the plug-in to `HTML5` to avoid this issue. The menu path is: *Configuration* -> *Virtual console* -> *Plug-in Type* -> *HTML5* . - -Ensure the {product-title} cluster nodes have AutoAttach Enabled through the iDRAC console. The menu path is: *Configuration* -> *Virtual Media* -> *Attach Mode* -> *AutoAttach* . -==== - - -.RedFish Virtual Media for HPE - -To enable RedFish Virtual Media for HPE servers, use `redfish-virtualmedia://` in the `address` setting. The following example demonstrates using RedFish Virtual Media within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: redfish-virtualmedia://<out-of-band-ip>/redfish/v1/Systems/1 - username: <user> - password: <password> ----- - -While it is recommended to have a certificate of authority for the out-of-band management addresses, you must include `disableCertificateVerification: True` in the `bmc` configuration if using self-signed certificates. The following example demonstrates a RedFish configuration using the `disableCertificateVerification: True` configuration parameter within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: redfish-virtualmedia://<out-of-band-ip>/redfish/v1/Systems/1 - username: <user> - password: <password> - disableCertificateVerification: True ----- - - -.RedFish Virtual Media for Dell - -For RedFish Virtual Media on Dell servers, use `idrac-virtualmedia://` in the `address` setting. - -ifeval::[{release} >= 4.6] -ifeval::[{release} < 4.7] -[NOTE] -==== -RedFish Virtual Media on Dell servers has a known issue in {product-title} 4.6, which will be resolved in the 4.6.1 point release. -==== -endif::[] -endif::[] - -The following example demonstrates using iDRAC Virtual Media within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: idrac-virtualmedia://<out-of-band-ip>/redfish/v1/Systems/System.Embedded.1 - username: <user> - password: <password> ----- - -While it is recommended to have a certificate of authority for the out-of-band management addresses, you must include `disableCertificateVerification: True` in the `bmc` configuration if using self-signed certificates. The following example demonstrates a RedFish configuration using the `disableCertificateVerification: True` configuration parameter within the `install-config.yaml` file. - -[source,yaml] ----- -platform: - baremetal: - hosts: - - name: openshift-master-0 - role: master - bmc: - address: idrac-virtualmedia://<out-of-band-ip>/redfish/v1/Systems/System.Embedded.1 - username: <user> - password: <password> - disableCertificateVerification: True ----- - - -[NOTE] -==== -Currently RedFish is only supported on Dell with iDRAC firmware versions `4.20.20.20` through `04.40.00.00` for IPI on bare metal deployments. There is a known issue with version `04.40.00.00`. With iDRAC 9 firmware version `04.40.00.00`, the Virtual Console plug-in defaults to `eHTML5`, which causes problems with the *InsertVirtualMedia* workflow. Set the plug-in to `HTML5` to avoid this issue. The menu path is: *Configuration* -> *Virtual console* -> *Plug-in Type* -> *HTML5* . - -Ensure the {product-title} cluster nodes have AutoAttach Enabled through the iDRAC console. The menu path is: *Configuration* -> *Virtual Media* -> *Attach Mode* -> *AutoAttach* . -==== diff --git a/modules/ipi-install-configuring-nodes.adoc b/modules/ipi-install-configuring-nodes.adoc deleted file mode 100644 index ea2baed5087c..000000000000 --- a/modules/ipi-install-configuring-nodes.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc - -[id="configuring-nodes_{context}"] -= Configuring nodes - -.Configuring nodes when using the `provisioning` network - -Each node in the cluster requires the following configuration for proper installation. - -[WARNING] -==== -A mismatch between nodes will cause an installation failure. -==== - -While the cluster nodes can contain more than two NICs, the installation process only focuses on the first two NICs: - -|=== -|NIC |Network |VLAN -| NIC1 | `provisioning` | <provisioning-vlan> -| NIC2 | `baremetal` | <baremetal-vlan> -|=== - -NIC1 is a non-routable network (`provisioning`) that is only used for the installation of the {product-title} cluster. - -The {op-system-base-full} 8.x installation process on the provisioner node might vary. To install {op-system-base-full} 8.x using a local Satellite server or a PXE server, PXE-enable NIC2. - - -|=== -|PXE |Boot order -| NIC1 PXE-enabled `provisioning` network | 1 -| NIC2 `baremetal` network. PXE-enabled is optional. | 2 -|=== - -[NOTE] -==== -Ensure PXE is disabled on all other NICs. -==== - -Configure the control plane and worker nodes as follows: - -|=== -|PXE | Boot order -| NIC1 PXE-enabled (provisioning network) | 1 -|=== - -ifeval::[{release} > 4.3] - -.Configuring nodes without the `provisioning` network - -The installation process requires one NIC: - -|=== -|NIC |Network |VLAN -| NICx | `baremetal` | <baremetal-vlan> -|=== - -NICx is a routable network (`baremetal`) that is used for the installation of the {product-title} cluster, and routable to the internet. - -endif::[] - -ifeval::[{release} > 4.6] -.Configuring nodes for Secure Boot - -Secure Boot prevents a node from booting unless it verifies the node is using only trusted software, such as UEFI firmware drivers, EFI applications and the operating system. Red Hat only supports Secure Boot when deploying with RedFish Virtual Media. - -To enable Secure Boot, refer to the hardware guide for the node. To enable Secure Boot, execute the following: - -. Boot the node and enter the BIOS menu. -. Set the node's boot mode to UEFI Enabled. -. Enable Secure Boot. -+ -[IMPORTANT] -==== -Red Hat does not support Secure Boot with self-generated keys. -==== -endif::[] diff --git a/modules/ipi-install-configuring-the-install-config-file.adoc b/modules/ipi-install-configuring-the-install-config-file.adoc deleted file mode 100644 index 0ce14a8d1cf2..000000000000 --- a/modules/ipi-install-configuring-the-install-config-file.adoc +++ /dev/null @@ -1,103 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="configuring-the-install-config-file_{context}"] - -= Configuring the `install-config.yaml` file - -The `install-config.yaml` file requires some additional details. -Most of the information is teaching the installer and the resulting cluster enough about the available hardware so that it is able to fully manage it. - -. Configure `install-config.yaml`. Change the appropriate variables to match the environment, including `pullSecret` and `sshKey`. -+ -[source,yaml] ----- -apiVersion: v1 -baseDomain: <domain> -metadata: - name: <cluster-name> -networking: - machineCIDR: <public-cidr> - networkType: OVNKubernetes -compute: -- name: worker - replicas: 2 -controlPlane: - name: master - replicas: 3 - platform: - baremetal: {} -platform: - baremetal: - apiVIP: <api-ip> - ingressVIP: <wildcard-ip> - provisioningBridge: provisioning - provisioningNetworkCIDR: 172.22.0.0/24 - hosts: - - name: openshift-master-0 - role: master - bmc: - address: ipmi://<out-of-band-ip> - username: <user> - password: <password> - bootMACAddress: <NIC1-mac-address> - - name: openshift-master-1 - role: master - bmc: - address: ipmi://<out-of-band-ip> - username: <user> - password: <password> - bootMACAddress: <NIC1-mac-address> - - name: openshift-master-2 - role: master - bmc: - address: ipmi://<out-of-band-ip> - username: <user> - password: <password> - bootMACAddress: <NIC1-mac-address> - - name: openshift-worker-0 - role: worker - bmc: - address: ipmi://<out-of-band-ip> - username: <user> - password: <password> - bootMACAddress: <NIC1-mac-address> - - name: openshift-worker-1 - role: worker - bmc: - address: ipmi://<out-of-band-ip> - username: <user> - password: <password> - bootMACAddress: <NIC1-mac-address> -pullSecret: '<pull_secret>' -sshKey: '<ssh_pub_key>' ----- - -. Create a directory to store cluster configs. -+ -[source,terminal] ----- -$ mkdir ~/clusterconfigs -$ cp install-config.yaml ~/clusterconfigs ----- - -. Ensure all bare metal nodes are powered off prior to installing the {product-title} cluster. -+ -[source,terminal] ----- -$ ipmitool -I lanplus -U <user> -P <password> -H <management-server-ip> power off ----- - -. Remove old bootstrap resources if any are left over from a previous deployment attempt. -+ -[source,terminal] ----- -for i in $(sudo virsh list | tail -n +3 | grep bootstrap | awk {'print $2'}); -do - sudo virsh destroy $i; - sudo virsh undefine $i; - sudo virsh vol-delete $i --pool default; - sudo virsh vol-delete $i.ign --pool default; -done ----- diff --git a/modules/ipi-install-configuring-the-metal3-config-file.adoc b/modules/ipi-install-configuring-the-metal3-config-file.adoc deleted file mode 100644 index 2641402a425b..000000000000 --- a/modules/ipi-install-configuring-the-metal3-config-file.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="configuring-the-metal3-config-file_{context}"] - -= Configuring the `metal3-config.yaml` file - -You must create and configure a ConfigMap `metal3-config.yaml` file. - -.Procedure - -. Create a ConfigMap `metal3-config.yaml.sample`. -+ ----- -$ vim metal3-config.yaml.sample ----- -+ -Provide the following contents: -+ ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: metal3-config - namespace: openshift-machine-api -data: - cache_url: '' - deploy_kernel_url: http://<provisioning_ip>:6180/images/ironic-python-agent.kernel - deploy_ramdisk_url: http://<provisioning_ip>:6180/images/ironic-python-agent.initramfs - dhcp_range: 172.22.0.10,172.22.0.100 - http_port: "6180" - ironic_endpoint: http://<provisioning_ip>:6385/v1/ - ironic_inspector_endpoint: http://172.22.0.3:5050/v1/ - provisioning_interface: <NIC1> - provisioning_ip: <provisioning_ip>/24 - rhcos_image_url: ${RHCOS_URI}${RHCOS_PATH} ----- -+ -[NOTE] -==== -Replace `<provisioning_ip>` with an available IP on the `provisioning` network. The default is `172.22.0.3`. -==== - -. Create the final ConfigMap. -+ ----- -$ export COMMIT_ID=$(./openshift-baremetal-install version | grep '^built from commit' | awk '{print $4}') -$ export RHCOS_PATH=$(curl -s -S https://raw.githubusercontent.com/openshift/installer/$COMMIT_ID/data/data/rhcos.json | jq .images.openstack.path | sed 's/"//g') -$ export RHCOS_URI=$(curl -s -S https://raw.githubusercontent.com/openshift/installer/$COMMIT_ID/data/data/rhcos.json | jq .baseURI | sed 's/"//g') -$ envsubst < metal3-config.yaml.sample > metal3-config.yaml ----- diff --git a/modules/ipi-install-creating-a-disconnected-registry.adoc b/modules/ipi-install-creating-a-disconnected-registry.adoc deleted file mode 100644 index ccb86b18a2ee..000000000000 --- a/modules/ipi-install-creating-a-disconnected-registry.adoc +++ /dev/null @@ -1,228 +0,0 @@ -// Module included in the following assemblies: -// -// * list of assemblies where this module is included -// install/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="ipi-install-creating-a-disconnected-registry_{context}"] - -= Creating a disconnected registry (optional) - -In some cases, you might want to install an {product-title} cluster using a local copy of the installation registry. This could be for enhancing network efficiency because the cluster nodes are on a network that does not have access to the internet. - -A local, or mirrored, copy of the registry requires the following: - -* A certificate for the registry node. This can be a self-signed certificate. -* A web server that a container on a system will serve. -* An updated pull secret that contains the certificate and local repository information. - -[NOTE] -==== -Creating a disconnected registry on a registry node is optional. The subsequent sections indicate that they are optional since they are steps you need to execute only when creating a disconnected registry on a registry node. You should execute all of the subsequent sub-sections labeled "(optional)" when creating a disconnected registry on a registry node. -==== - -== Preparing the registry node to host the mirrored registry (optional) - -Make the following changes to the registry node. - -.Procedure - -. Open the firewall port on the registry node. -+ -[source,terminal] ----- -[user@registry ~]$ sudo firewall-cmd --add-port=5000/tcp --zone=libvirt --permanent -[user@registry ~]$ sudo firewall-cmd --add-port=5000/tcp --zone=public --permanent -[user@registry ~]$ sudo firewall-cmd --reload ----- - -. Install the required packages for the registry node. -+ -[source,terminal] ----- -[user@registry ~]$ sudo yum -y install python3 podman httpd httpd-tools jq ----- - -. Create the directory structure where the repository information will be held. -+ -[source,terminal] ----- -[user@registry ~]$ sudo mkdir -p /opt/registry/{auth,certs,data} ----- - -== Generating the self-signed certificate (optional) - -Generate a self-signed certificate for the registry node and put it in the `/opt/registry/certs` directory. - -.Procedure - -. Adjust the certificate information as appropriate. -+ -[source,terminal] ----- -[user@registry ~]$ host_fqdn=$( hostname --long ) -[user@registry ~]$ cert_c="<Country Name>" # Country Name (C, 2 letter code) -[user@registry ~]$ cert_s="<State>" # Certificate State (S) -[user@registry ~]$ cert_l="<Locality>" # Certificate Locality (L) -[user@registry ~]$ cert_o="<Organization>" # Certificate Organization (O) -[user@registry ~]$ cert_ou="<Org Unit>" # Certificate Organizational Unit (OU) -[user@registry ~]$ cert_cn="${host_fqdn}" # Certificate Common Name (CN) - -[user@registry ~]$ openssl req \ - -newkey rsa:4096 \ - -nodes \ - -sha256 \ - -keyout /opt/registry/certs/domain.key \ - -x509 \ - -days 365 \ - -out /opt/registry/certs/domain.crt \ - -subj "/C=${cert_c}/ST=${cert_s}/L=${cert_l}/O=${cert_o}/OU=${cert_ou}/CN=${cert_cn}" ----- -+ -NOTE: When replacing `<Country Name>`, ensure that it only contains two letters. For example, `US`. - -. Update the registry node's `ca-trust` with the new certificate. -+ -[source,terminal] ----- -[user@registry ~]$ sudo cp /opt/registry/certs/domain.crt /etc/pki/ca-trust/source/anchors/ -[user@registry ~]$ sudo update-ca-trust extract ----- - -== Creating the registry podman container (optional) - -The registry container uses the `/opt/registry` directory for certificates, authentication files, and to store its data files. - -The registry container uses `httpd` and needs an `htpasswd` file for authentication. - -.Procedure - -. Create an `htpasswd` file in `/opt/registry/auth` for the container to use. -+ -[source,terminal] ----- -[user@registry ~]$ htpasswd -bBc /opt/registry/auth/htpasswd <user> <passwd> ----- -+ -Replace `<user>` with the user name and `<passwd>` with the password. - -. Create and start the registry container. -+ -[source,terminal] ----- -[user@registry ~]$ podman create \ - --name ocpdiscon-registry \ - -p 5000:5000 \ - -e "REGISTRY_AUTH=htpasswd" \ - -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry" \ - -e "REGISTRY_HTTP_SECRET=ALongRandomSecretForRegistry" \ - -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \ - -e "REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt" \ - -e "REGISTRY_HTTP_TLS_KEY=/certs/domain.key" \ - -e "REGISTRY_COMPATIBILITY_SCHEMA1_ENABLED=true" \ - -v /opt/registry/data:/var/lib/registry:z \ - -v /opt/registry/auth:/auth:z \ - -v /opt/registry/certs:/certs:z \ - docker.io/library/registry:2 ----- -+ -[source,terminal] ----- -[user@registry ~]$ podman start ocpdiscon-registry ----- - -== Copy and update the pull-secret (optional) - -Copy the pull secret file from the provisioner node to the registry node and modify it to include the authentication information for the new registry node. - -.Procedure - -. Copy the `pull-secret.txt` file. -+ -[source,terminal] ----- -[user@registry ~]$ scp kni@provisioner:/home/kni/pull-secret.txt pull-secret.txt ----- - -. Update the `host_fqdn` environment variable with the fully qualified domain name of the registry node. -+ -[source,terminal] ----- -[user@registry ~]$ host_fqdn=$( hostname --long ) ----- - -. Update the `b64auth` environment variable with the base64 encoding of the `http` credentials used to create the `htpasswd` file. -+ -[source,terminal] ----- -[user@registry ~]$ b64auth=$( echo -n '<username>:<passwd>' | openssl base64 ) ----- -+ -Replace `<username>` with the user name and `<passwd>` with the password. - -. Set the `AUTHSTRING` environment variable to use the `base64` authorization string. The `$USER` variable is an environment variable containing the name of the current user. -+ -[source,terminal] ----- -[user@registry ~]$ AUTHSTRING="{\"$host_fqdn:5000\": {\"auth\": \"$b64auth\",\"email\": \"$USER@redhat.com\"}}" ----- - -. Update the `pull-secret.txt` file. -+ -[source,terminal] ----- -[user@registry ~]$ jq ".auths += $AUTHSTRING" < pull-secret.txt > pull-secret-update.txt ----- - -== Mirroring the repository (optional) - -.Procedure - -. Copy the `oc` binary from the provisioner node to the registry node. -+ -[source,terminal] ----- -[user@registry ~]$ sudo scp kni@provisioner:/usr/local/bin/oc /usr/local/bin ----- - -. Mirror the remote install images to the local repository. -+ -[source,terminal] ----- -[user@registry ~]$ /usr/local/bin/oc adm release mirror \ - -a pull-secret-update.txt - --from=$UPSTREAM_REPO \ - --to-release-image=$LOCAL_REG/$LOCAL_REPO:${VERSION} \ - --to=$LOCAL_REG/$LOCAL_REPO ----- - -== Modify the `install-config.yaml` file to use the disconnected registry (optional) - -On the provisioner node, the `install-config.yaml` file should use the newly created pull-secret from the `pull-secret-update.txt` file. The `install-config.yaml` file must also contain the disconnected registry node's certificate and registry information. - -.Procedure - -. Add the disconnected registry node's certificate to the `install-config.yaml` file. The certificate should follow the `"additionalTrustBundle: |"` line and be properly indented, usually by two spaces. -+ -[source,terminal] ----- -$ echo "additionalTrustBundle: |" >> install-config.yaml -$ sed -e 's/^/ /' /opt/registry/certs/domain.crt >> install-config.yaml ----- - -. Add the mirror information for the registry to the `install-config.yaml` file. -+ -[source,terminal] ----- -$ echo "imageContentSources:" >> install-config.yaml -$ echo "- mirrors:" >> install-config.yaml -$ echo " - registry.example.com:5000/ocp4/openshift4" >> install-config.yaml -$ echo " source: quay.io/openshift-release-dev/ocp-v4.0-art-dev" >> install-config.yaml -$ echo "- mirrors:" >> install-config.yaml -$ echo " - registry.example.com:5000/ocp4/openshift4" >> install-config.yaml -$ echo " source: registry.svc.ci.openshift.org/ocp/release" >> install-config.yaml -$ echo "- mirrors:" >> install-config.yaml -$ echo " - registry.example.com:5000/ocp4/openshift4" >> install-config.yaml -$ echo " source: quay.io/openshift-release-dev/ocp-release" >> install-config.yaml ----- -+ -NOTE: Replace `registry.example.com` with the registry's fully qualified domain name. diff --git a/modules/ipi-install-creating-an-rhcos-images-cache.adoc b/modules/ipi-install-creating-an-rhcos-images-cache.adoc deleted file mode 100644 index 5eeac9bbdc9b..000000000000 --- a/modules/ipi-install-creating-an-rhcos-images-cache.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="ipi-install-creating-an-rhcos-images-cache_{context}"] - -= Creating an {op-system} images cache (optional) - -To employ image caching, you must download two images: the {op-system-first} image used by the bootstrap VM and the {op-system} image used by the installer to provision the different nodes. Image caching is optional, but especially useful when running the installer on a network with limited bandwidth. - -If you are running the installer on a network with limited bandwidth and the {op-system} images download takes more than 15 to 20 minutes, the installer will timeout. Caching images on a web server will help in such scenarios. - -Use the following steps to install a container that contains the images. - -. Install `podman`. -+ -[source,terminal] ----- -$ sudo dnf install -y podman ----- - -. Open firewall port `8080` to be used for {op-system} image caching. -+ -[source,terminal] ----- -$ sudo firewall-cmd --add-port=8080/tcp --zone=public --permanent ----- - -. Create a directory to store the `bootstraposimage` and `clusterosimage`. -+ -[source,terminal] ----- -$ mkdir /home/kni/rhcos_image_cache ----- - -. Set the appropriate SELinux context for the newly created directory. -+ -[source,terminal] ----- -$ sudo semanage fcontext -a -t httpd_sys_content_t "/home/kni/rhcos_image_cache(/.*)?" -$ sudo restorecon -Rv rhcos_image_cache/ ----- - -. Get the commit ID from the installer. The ID determines which images the installer needs to download. -+ -[source,terminal] ----- -$ export COMMIT_ID=$(/usr/local/bin/openshift-baremetal-install version | grep '^built from commit' | awk '{print $4}') ----- - -. Get the URI for the {op-system} image that the installer will deploy on the nodes. -+ -[source,terminal] ----- -$ export RHCOS_OPENSTACK_URI=$(curl -s -S https://raw.githubusercontent.com/openshift/installer/$COMMIT_ID/data/data/rhcos.json | jq .images.openstack.path | sed 's/"//g') ----- - -. Get the URI for the {op-system} image that the installer will deploy on the bootstrap VM. -+ -[source,terminal] ----- -$ export RHCOS_QEMU_URI=$(curl -s -S https://raw.githubusercontent.com/openshift/installer/$COMMIT_ID/data/data/rhcos.json | jq .images.qemu.path | sed 's/"//g') ----- - -. Get the path where the images are published. -+ -[source,terminal] ----- -$ export RHCOS_PATH=$(curl -s -S https://raw.githubusercontent.com/openshift/installer/$COMMIT_ID/data/data/rhcos.json | jq .baseURI | sed 's/"//g') ----- - -. Get the SHA hash for the {op-system} image that will be deployed on the bootstrap VM. -+ -[source,terminal] ----- -$ export RHCOS_QEMU_SHA_UNCOMPRESSED=$(curl -s -S https://raw.githubusercontent.com/openshift/installer/$COMMIT_ID/data/data/rhcos.json | jq -r '.images.qemu["uncompressed-sha256"]') ----- - -. Get the SHA hash for the {op-system} image that will be deployed on the nodes. -+ -[source,terminal] ----- -$ export RHCOS_OPENSTACK_SHA_COMPRESSED=$(curl -s -S https://raw.githubusercontent.com/openshift/installer/$COMMIT_ID/data/data/rhcos.json | jq -r '.images.openstack.sha256') ----- - -. Download the images and place them in the `/home/kni/rhcos_image_cache` directory. -+ -[source,terminal] ----- -$ curl -L ${RHCOS_PATH}${RHCOS_QEMU_URI} -o /home/kni/rhcos_image_cache -$ curl -L ${RHCOS_PATH}${RHCOS_OPENSTACK_URI} -o /home/kni/rhcos_image_cache ----- - -. Confirm SELinux type is of `httpd_sys_content_t` for the newly created files. -+ -[source,terminal] ----- -$ ls -Z /home/kni/rhcos_image_cache ----- - -. Create the pod. -+ -[source,terminal] ----- -$ podman run -d --name rhcos_image_cache \ --v /home/kni/rhcos_image_cache:/var/www/html \ --p 8080:8080/tcp \ -registry.centos.org/centos/httpd-24-centos7:latest ----- diff --git a/modules/ipi-install-creating-the-openshift-manifests.adoc b/modules/ipi-install-creating-the-openshift-manifests.adoc deleted file mode 100644 index aeda9cb3a3e8..000000000000 --- a/modules/ipi-install-creating-the-openshift-manifests.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="creating-the-openshift-manifests_{context}"] -= Creating the {product-title} manifests - -. Create the {product-title} manifests. -+ -[source,terminal] ----- -$ ./openshift-baremetal-install --dir ~/clusterconfigs create manifests ----- -+ -[source,terminal] ----- -INFO Consuming Install Config from target directory -WARNING Making control-plane schedulable by setting MastersSchedulable to true for Scheduler cluster settings -WARNING Discarding the Openshift Manifest that was provided in the target directory because its dependencies are dirty and it needs to be regenerated ----- - -ifeval::[{release} <= 4.3] -. Copy the `metal3-config.yaml` file to the `clusterconfigs/openshift` directory. -+ -[source,terminal] ----- -$ cp ~/metal3-config.yaml clusterconfigs/openshift/99_metal3-config.yaml ----- -endif::[] diff --git a/modules/ipi-install-deploying-routers-on-worker-nodes.adoc b/modules/ipi-install-deploying-routers-on-worker-nodes.adoc deleted file mode 100644 index acae8859fd16..000000000000 --- a/modules/ipi-install-deploying-routers-on-worker-nodes.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * list of assemblies where this module is included -// ipi-install-installation-workflow.adoc - -[id="deploying-routers-on-worker-nodes_{context}"] - -= Deploying routers on worker nodes - -During installation, the installer deploys router pods on worker nodes. By default, the installer installs two router pods. If the initial cluster has only one worker node, or if a deployed cluster requires additional routers to handle external traffic loads destined for services within the {product-title} cluster, you can create a `yaml` file to set an appropriate number of router replicas. - -[NOTE] -==== -By default, the installer deploys two routers. If the cluster has at least two worker nodes, you can skip this section. -==== - -[NOTE] -==== -If the cluster has no worker nodes, the installer deploys the two routers on the control plane nodes by default. If the cluster has no worker nodes, you can skip this section. -==== - -.Procedure - -. Create a `router-replicas.yaml` file. -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - name: default - namespace: openshift-ingress-operator -spec: - replicas: <num-of-router-pods> - endpointPublishingStrategy: - type: HostNetwork - nodePlacement: - nodeSelector: - matchLabels: - node-role.kubernetes.io/worker: "" ----- -+ -[NOTE] -==== -Replace `<num-of-router-pods>` with an appropriate value. If working with just one worker node, set `replicas:` to `1`. If working with more than 3 worker nodes, you can increase `replicas:` from the default value `2` as appropriate. -==== - -. Save and copy the `router-replicas.yaml` file to the `clusterconfigs/openshift` directory. -+ -[source,terminal] ----- -cp ~/router-replicas.yaml clusterconfigs/openshift/99_router-replicas.yaml ----- diff --git a/modules/ipi-install-deploying-the-cluster-via-the-openshift-installer.adoc b/modules/ipi-install-deploying-the-cluster-via-the-openshift-installer.adoc deleted file mode 100644 index 49960ba7f22b..000000000000 --- a/modules/ipi-install-deploying-the-cluster-via-the-openshift-installer.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id='deploying-the-cluster-via-the-openshift-installer_{context}'] -= Deploying the cluster via the {product-title} installer - -Run the {product-title} installer: - -[source,terminal] ----- -$ ./openshift-baremetal-install --dir ~/clusterconfigs --log-level debug create cluster ----- diff --git a/modules/ipi-install-extracting-the-openshift-installer.adoc b/modules/ipi-install-extracting-the-openshift-installer.adoc deleted file mode 100644 index 400f89ee1150..000000000000 --- a/modules/ipi-install-extracting-the-openshift-installer.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="extracting-the-openshift-installer_{context}"] -= Extracting the {product-title} installer - -After retrieving the installer, the next step is to extract it. - -.Procedure - -. Set the environment variables: -+ -[source,terminal] ----- -$ export cmd=openshift-baremetal-install -$ export pullsecret_file=~/pull-secret.txt -$ export extract_dir=$(pwd) ----- - -. Get the `oc` binary: -+ -[source,terminal] ----- -$ curl -s https://mirror.openshift.com/pub/openshift-v4/clients/ocp/$VERSION/openshift-client-linux.tar.gz | tar zxvf - oc ----- - -. Extract the installer: -+ -[source,terminal] ----- -$ sudo cp oc /usr/local/bin -$ oc adm release extract --registry-config "${pullsecret_file}" --command=$cmd --to "${extract_dir}" ${RELEASE_IMAGE} -$ sudo cp openshift-baremetal-install /usr/local/bin ----- diff --git a/modules/ipi-install-firmware-requirements-for-installing-with-virtual-media.adoc b/modules/ipi-install-firmware-requirements-for-installing-with-virtual-media.adoc deleted file mode 100644 index e22c850fb757..000000000000 --- a/modules/ipi-install-firmware-requirements-for-installing-with-virtual-media.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc - -[id='ipi-install-firmware-requirements-for-installing-with-virtual-media_{context}'] -= Firmware requirements for installing with virtual media - -The installer for installer-provisioned {product-title} clusters validates the hardware and firmware compatibility with RedFish virtual media. The following table lists supported firmware for installer-provisioned {product-title} clusters deployed with RedFish virtual media. - -.Firmware Compatibility for RedFish Virtual Media -[frame="topbot", options="header"] -|==== -|Hardware| Model | Management | Minimum Firmware Version -.2+| HP | 10th Generation | iLO5 | N/A -| 9th Generation | iLO4 | N/A - -.2+| Dell | 14th Generation | iDRAC 9 | v4.20.20.20 - 04.40.00.00 - -| 13th Generation .2+| iDRAC 8 | v2.75.75.75+ - -|==== - -[NOTE] -==== -Refer to the hardware documentation for the nodes or contact the hardware vendor for information on updating the firmware. - -There are no known firmware limitations for HP servers. - -For Dell servers, ensure the {product-title} cluster nodes have AutoAttach Enabled through the iDRAC console. The menu path is: *Configuration* -> *Virtual Media* -> *Attach Mode* -> *AutoAttach* . With iDRAC 9 firmware version `04.40.00.00`, the Virtual Console plug-in defaults to `eHTML5`, which causes problems with the *InsertVirtualMedia* workflow. Set the plug-in to `HTML5` to avoid this issue. The menu path is: *Configuration* -> *Virtual console* -> *Plug-in Type* -> *HTML5* . -==== - -[IMPORTANT] -==== -The installer will not initiate installation on a node if the node firmware is below the foregoing versions when installing with virtual media. -==== diff --git a/modules/ipi-install-following-the-installation.adoc b/modules/ipi-install-following-the-installation.adoc deleted file mode 100644 index 3c971d168cb6..000000000000 --- a/modules/ipi-install-following-the-installation.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="ipi-install-troubleshooting-following-the-installation_{context}"] - -= Following the installation - -During the deployment process, you can check the installation's overall status by issuing the `tail` command to the `.openshift_install.log` log file in the install directory folder. - -[source,terminal] ----- -$ tail -f /path/to/install-dir/.openshift_install.log ----- diff --git a/modules/ipi-install-installing-rhel-on-the-provisioner-node.adoc b/modules/ipi-install-installing-rhel-on-the-provisioner-node.adoc deleted file mode 100644 index 19c436eab3f7..000000000000 --- a/modules/ipi-install-installing-rhel-on-the-provisioner-node.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * list of assemblies where this module is included -// ipi-install-installation-workflow.adoc -[id="installing-rhel-on-the-provisioner-node_{context}"] -= Installing RHEL on the provisioner node - -With the networking configuration complete, the next step is to install {op-system-base} 8.x on the provisioner node. The installer uses the provisioner node as the orchestrator while installing the {product-title} cluster. For the purposes of this document, installing RHEL on the provisioner node is out of scope. However, options include but are not limited to using a RHEL Satellite server, PXE, or installation media. diff --git a/modules/ipi-install-ipv6-network-requirements.adoc b/modules/ipi-install-ipv6-network-requirements.adoc deleted file mode 100644 index 4af3c35e761d..000000000000 --- a/modules/ipi-install-ipv6-network-requirements.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// This is included in the following assemblies: -// -// ipi-install-prerequisites.adoc -[id="ipi-install-ipv6-network-requirements_{context}"] - -= IPv6 Network Requirements - -.SLAAC addressing - -If you do not plan to use SLAAC (Stateless Address AutoConfiguration) addresses on your {product-title} node, then it should be disabled for `baremetal` networks. That means that if the network equipment is configured to send SLAAC addresses when replying to Route Advertisements, you must configure the equipment so that it only sends the route and not the SLAAC address. - -.Procedure - -. Install `ndptool`. -+ -[source,terminal] ----- -$ sudo dnf install ndptool ----- - -. Turn down the `baremetal` interface on a control plane node, and then turn it back up. -+ -[source,terminal] ----- -$ sudo nmcli con down "Wired connection 5" && sudo nmcli con up "Wired connection 5" ----- -+ -[source,terminal] ----- -Connection 'Wired connection 5' successfully deactivated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/1983) -Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/2044) ----- - -. Activate the `ndptool` to check the route advertisements: -+ -[source,terminal] ----- -$ sudo ndptool monitor -t ra ----- -+ -[source,terminal] ----- -NDP payload len 80, from addr: fe80::c0a4:6464:bcb3:d657, iface: baremetal.153 - Type: RA - Hop limit: 64 - Managed address configuration: yes - Other configuration: no - Default router preference: medium - Router lifetime: 0s - Reachable time: unspecified - Retransmit time: unspecified - Source linkaddr: 1c:40:24:1b:0c:34 - Prefix: 2620:52:0:1303::/64, valid_time: 86400s, preferred_time: 14400s, on_link: yes, autonomous_addr_conf: no, router_addr: no - Route: ::/0, lifetime: 0s, preference: low ----- -+ -The `ndptool monitor` should report `Managed address configuration: yes`. - -.Network ranges and configurations - -Each environment requires different `baremetal` and `provisioning` network; and, will have a different IPv6 range for each network. Typically, only the `baremetal` network is routable. The `provisioning` network cannot be in the same broadcast domain as the `baremetal` network, because of additional services running, such as DHCP. - -.Route advertisements - -[IMPORTANT] -==== -Route advertisement must be enabled for both the `baremetal` and `provisioning` networks. -==== - -Both the `baremetal` and the `provisioning` networks must have route advertisement enabled. For the `baremetal` network, installer-provisioned installation uses the `radvd` daemon, and the `provisioning` network has route advertisement enabled in the Metal³ dnsmasq, so it requires no additional configuration. diff --git a/modules/ipi-install-modifying-install-config-for-no-provisioning-network.adoc b/modules/ipi-install-modifying-install-config-for-no-provisioning-network.adoc deleted file mode 100644 index b6bcf9a71999..000000000000 --- a/modules/ipi-install-modifying-install-config-for-no-provisioning-network.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// This is included in the following assemblies: -// -// ipi-install-configuration-files.adoc - -[id='modifying-install-config-for-no-provisioning-network_{context}'] - -= Modifying the `install-config.yaml` file for no `provisioning` network (optional) - -To deploy an {product-title} cluster without a `provisioning` network, make the following changes to the `install-config.yaml` file. - -ifeval::[{release} == 4.6] -[source,yaml] ----- -platform: - baremetal: - apiVIP: <apiVIP> - ingressVIP: <ingress/wildcard VIP> - provisioningNetwork: "Disabled" - provisioningHostIP: <baremetal_network_IP1> - bootstrapProvisioningIP: <baremetal_network_IP2> ----- - -[NOTE] -==== -Requires providing two IP addresses from the `baremetal` network for the `provisioningHostIP` and `bootstrapProvisioningIP` configuration settings, and removing the `provisioningBridge` and `provisioningNetworkCIDR` configuration settings. -==== -endif::[] - -ifeval::[{release} >= 4.7] -[source,yaml] ----- -platform: - baremetal: - apiVIP: <apiVIP> - ingressVIP: <ingress/wildcard VIP> - provisioningNetwork: "Disabled" ----- -endif::[] diff --git a/modules/ipi-install-network-requirements.adoc b/modules/ipi-install-network-requirements.adoc deleted file mode 100644 index 607f9a996119..000000000000 --- a/modules/ipi-install-network-requirements.adoc +++ /dev/null @@ -1,135 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc - -[id='network-requirements_{context}'] -= Network requirements - -Installer-provisioned installation of {product-title} involves several network requirements by default. First, installer-provisioned installation involves a non-routable `provisioning` network for provisioning the operating system on each bare metal node and a routable `baremetal` network. Since installer-provisioned installation deploys `ironic-dnsmasq`, the networks should have no other DHCP servers running on the same broadcast domain. Network administrators must reserve IP addresses for each node in the {product-title} cluster. - -.Network Time Protocol (NTP) - -It is recommended that each {product-title} node in the cluster have access to a Network Time Protocol (NTP) server that is discoverable using DHCP. While installation without an NTP server is possible, asynchronous server clocks can cause errors. Using an NTP server can prevent this issue. - -.Configuring NICs - -{product-title} deploys with two networks: - -- `provisioning`: The `provisioning` network is an *optional* non-routable network used for provisioning the underlying operating system on each node that is a part of the {product-title} cluster. When deploying using the `provisioning` network, the first NIC on each node, such as `eth0` or `eno1`, -*must* interface with the `provisioning` network. - -- `baremetal`: The `baremetal` network is a routable network. When deploying using the `provisioning` network, the second NIC on each node, such as `eth1` or `eno2`, *must* interface with the `baremetal` network. When deploying without a `provisioning` network, you can use any NIC on each node to interface with the `baremetal` network. - -[IMPORTANT] -==== -Each NIC should be on a separate VLAN corresponding to the appropriate network. -==== - -.Configuring the DNS server - -Clients access the {product-title} cluster nodes over the `baremetal` network. -A network administrator must configure a subdomain or subzone where the canonical name extension is the cluster name. - ----- -<cluster_name>.<domain-name> ----- - -For example: - ----- -test-cluster.example.com ----- - -ifdef::upstream[] -For assistance in configuring the DNS server, check xref:ipi-install-upstream-appendix[Appendix] section for: - -- xref:creating-dns-records-on-a-dns-server-option1_{context}[Creating DNS Records with Bind (Option 1)] -- xref:creating-dns-records-using-dnsmasq-option2_{context}[Creating DNS Records with dnsmasq (Option 2)] - -endif::[] - - -.Reserving IP addresses for nodes with the DHCP server - -For the `baremetal` network, a network administrator must reserve a number of IP addresses, including: - -ifeval::[{release} > 4.5] -. Two virtual IP addresses. -endif::[] -ifeval::[{release} <= 4.5] -. Three virtual IP addresses -endif::[] -+ -- One IP address for the API endpoint -- One IP address for the wildcard ingress endpoint -ifeval::[{release} <= 4.5] -- One IP address for the name server -endif::[] - -. One IP address for the provisioner node. -. One IP address for each control plane (master) node. -. One IP address for each worker node, if applicable. - -ifeval::[{release}>4.6] -[IMPORTANT] -.Reserving IP addresses so they become static IP addresses -==== -Some administrators prefer to use static IP addresses so that each node's IP address remains constant in the absence of a DHCP server. To use static IP addresses in the {product-title} cluster, *reserve the IP addresses with an infinite lease*. During deployment, the installer will reconfigure the NICs from DHCP assigned addresses to static IP addresses. NICs with DHCP leases that are not infinite will remain configured to use DHCP. -==== -endif::[] - -The following table provides an exemplary embodiment of fully qualified domain names. The API and Nameserver addresses begin with canonical name extensions. The host names of the control plane and worker nodes are exemplary, so you can use any host naming convention you prefer. - -[width="100%",cols="3,5,2",frame="topbot",options="header"] -|===== -| Usage | Host Name | IP -| API | api.<cluster_name>.<domain> | <ip> -| Ingress LB (apps) | *.apps.<cluster_name>.<domain> | <ip> -ifeval::[{release} <= 4.5] -| Nameserver | ns1.<cluster_name>.<domain> | <ip> -endif::[] -| Provisioner node | provisioner.<cluster_name>.<domain> | <ip> -| Master-0 | openshift-master-0.<cluster_name>.<domain> | <ip> -| Master-1 | openshift-master-1.<cluster_name>.<domain> | <ip> -| Master-2 | openshift-master-2.<cluster_name>.<domain> | <ip> -| Worker-0 | openshift-worker-0.<cluster_name>.<domain> | <ip> -| Worker-1 | openshift-worker-1.<cluster_name>.<domain> | <ip> -| Worker-n | openshift-worker-n.<cluster_name>.<domain> | <ip> -|===== - -ifdef::upstream[] -For assistance in configuring the DHCP server, check xref:ipi-install-upstream-appendix[Appendix] section for: - -- xref:creating-dhcp-reservations-option1_{context}[Creating DHCP reservations with dhcpd (Option 1)] -- xref:creating-dhcp-reservations-using-dnsmasq-option2_{context}[Creating DHCP reservations with dnsmasq (Option 2)] -endif::[] - -ifeval::[{release} == 4.6] -.Additional requirements with no provisioning network - -All installer-provisioned installations require a `baremetal` network. The `baremetal` network is a routable network used for external network access to the outside world. In addition to the IP address supplied to the {product-title} cluster node, installations without a `provisioning` network require the following: - -- Setting an available IP address from the `baremetal` network to the `bootstrapProvisioningIP` configuration setting within the `install-config.yaml` configuration file. - -- Setting an available IP address from the `baremetal` network to the `provisioningHostIP` configuration setting within the `install-config.yaml` configuration file. - -- Deploying the {product-title} cluster using RedFish Virtual Media/iDRAC Virtual Media. - -[NOTE] -==== -Configuring additional IP addresses for `bootstrapProvisioningIP` and `provisioningHostIP` is not required when using a `provisioning` network. -==== -endif::[] - -ifeval::[{release} > 4.6] -.State-driven network configuration requirements (Technology Preview) - -{product-title} supports additional post-installation state-driven network configuration on the secondary network interfaces of cluster nodes using `kubernetes-nmstate`. For example, system administrators might configure a secondary network interface on cluster nodes after installation for a storage network. - -[NOTE] -==== -Configuration must occur before scheduling pods. -==== - -State-driven network configuration requires installing `kubernetes-nmstate`, and also requires Network Manager running on the cluster nodes. See *OpenShift Virtualization > Kubernetes NMState (Tech Preview)* for additional details. -endif::[] diff --git a/modules/ipi-install-node-requirements.adoc b/modules/ipi-install-node-requirements.adoc deleted file mode 100644 index f3e12b926c41..000000000000 --- a/modules/ipi-install-node-requirements.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc - -[id='node-requirements_{context}'] - -= Node requirements - -Installer-provisioned installation involves a number of hardware node requirements: - -- **CPU architecture:** All nodes must use `x86_64` CPU architecture. - -- **Similar nodes:** Red Hat recommends nodes have an identical configuration per role. That is, Red Hat recommends nodes be the same brand and model with the same CPU, memory and storage configuration. - -ifeval::[{release} < 4.5] -- **Intelligent Platform Management Interface (IPMI):** Installer-provisioned installation requires IPMI enabled on each node. -endif::[] - -ifeval::[{release} > 4.4] -- **Baseboard Management Controller:** The `provisioner` node must be able to access the baseboard management controller (BMC) of each {product-title} cluster node. You may use IPMI, RedFish, or a proprietary protocol. -endif::[] - -- **Latest generation:** Nodes must be of the most recent generation. Installer-provisioned installation relies on BMC protocols, which must be compatible across nodes. Additionally, {op-system-base} 8 ships with the most recent drivers for RAID controllers. Ensure that the nodes are recent enough to support {op-system-base} 8 for the `provisioner` node and {op-system} 8 for the control plane and worker nodes. - -- **Registry node:** Optional: If setting up a disconnected mirrored registry, it is recommended the registry reside in its own node. - -- **Provisioner node:** Installer-provisioned installation requires one `provisioner` node. - -- **Control plane:** Installer-provisioned installation requires three control plane nodes for high availability. - -- **Worker nodes:** While not required, a typical production cluster has one or more worker nodes. Smaller clusters are more resource efficient for administrators and developers during development, production, and testing. - -- **Network interfaces:** Each node must have at least one 10GB network interface for the routable `baremetal` network. Each node must have one 10GB network interface for a `provisioning` network *when using the `provisioning` network* for deployment. Using the `provisioning` network is the default configuration. Network interface names must follow the same naming convention across all nodes. For example, the first NIC name on a node, such as `eth0` or `eno1`, must be the same name on all of the other nodes. The same principle applies to the remaining NICs on each node. - -ifeval::[{release} > 4.3] -- **Unified Extensible Firmware Interface (UEFI):** Installer-provisioned installation requires UEFI boot on all {product-title} nodes when using IPv6 addressing on the `provisioning` network. In addition, UEFI Device PXE Settings must be set to use the IPv6 protocol on the `provisioning` network NIC, but *omitting the `provisioning` network removes this requirement.* -endif::[] - -ifeval::[{release} > 4.6] -- **Secure Boot:** Many production scenarios require nodes with Secure Boot enabled to verify the node only boots with trusted software, such as UEFI firmware drivers, EFI applications and the operating system. To deploy a {product-title} cluster with Secure Boot, you must enable UEFI boot mode and Secure Boot on each control plane node and each worker node. Red Hat supports Secure Boot **only** when installer-provisioned installation uses Red Fish Virtual Media. Red Hat **does not** support Secure Boot with self-generated keys. -endif::[] diff --git a/modules/ipi-install-out-of-band-management.adoc b/modules/ipi-install-out-of-band-management.adoc deleted file mode 100644 index 4ccb8c8d84f5..000000000000 --- a/modules/ipi-install-out-of-band-management.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc - - -[id="out-of-band-management_{context}"] -= Out-of-band management - -Nodes will typically have an additional NIC used by the Baseboard Management Controllers (BMCs). These BMCs must be accessible from the `provisioner` node. - -Each node must be accessible via out-of-band management. When using an out-of-band management network, the `provisioner` node requires access to the out-of-band management network for a successful {product-title} 4 installation. - -The out-of-band management setup is out of scope for this document. We recommend setting up a separate management network for out-of-band management. However, using the `provisioning` network or the `baremetal` network are valid options. diff --git a/modules/ipi-install-preparing-the-bare-metal-node.adoc b/modules/ipi-install-preparing-the-bare-metal-node.adoc deleted file mode 100644 index 0228ecd662fb..000000000000 --- a/modules/ipi-install-preparing-the-bare-metal-node.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// This is included in the following assemblies: -// -// ipi-install-expanding-the-cluster.adoc - -[id='preparing-the-bare-metal-node_{context}'] - -= Preparing the bare metal node - -Expanding the cluster requires a DHCP server. Each node must have a DHCP reservation. - -ifeval::[{release}>4.6] -[IMPORTANT] -.Reserving IP addresses so they become static IP addresses -==== -Some administrators prefer to use static IP addresses so that each node's IP address remains constant in the absence of a DHCP server. To use static IP addresses in the {product-title} cluster, *reserve the IP addresses in the DHCP server with an infinite lease*. After the installer provisions the node successfully, the dispatcher script will check the node's network configuration. If the dispatcher script finds that the network configuration contains a DHCP infinite lease, it will recreate the connection as a static IP connection using the IP address from the DHCP infinite lease. NICs without DHCP infinite leases will remain unmodified. -==== -endif::[] - -Preparing the bare metal node requires executing the following procedure from the provisioner node. - -.Procedure - -. Get the `oc` binary, if needed. It should already exist on the provisioner node. -+ -[source,bash] ----- -[kni@provisioner ~]$ curl -s https://mirror.openshift.com/pub/openshift-v4/clients/ocp/$VERSION/openshift-client-linux-$VERSION.tar.gz | tar zxvf - oc ----- -+ -[source,bash] ----- -[kni@provisioner ~]$ sudo cp oc /usr/local/bin ----- - -. Power off the bare metal node via the baseboard management controller and ensure it is off. - -. Retrieve the user name and password of the bare metal node's baseboard management controller. Then, create `base64` strings from the user name and password. In the following example, the user name is `root` and the password is `calvin`. -+ -[source,bash] ----- -[kni@provisioner ~]$ echo -ne "root" | base64 ----- -+ -[source,bash] ----- -[kni@provisioner ~]$ echo -ne "calvin" | base64 ----- - -. Create a configuration file for the bare metal node. -+ -[source,bash] ----- -[kni@provisioner ~]$ vim bmh.yaml ----- -+ -[source,yaml] ----- ---- -apiVersion: v1 -kind: Secret -metadata: - name: openshift-worker-<num>-bmc-secret -type: Opaque -data: - username: <base64-of-uid> - password: <base64-of-pwd> ---- -apiVersion: metal3.io/v1alpha1 -kind: BareMetalHost -metadata: - name: openshift-worker-<num> -spec: - online: true - bootMACAddress: <NIC1-mac-address> - bmc: - address: <protocol>://<bmc-ip> - credentialsName: openshift-worker-<num>-bmc-secret ----- -+ -Replace `<num>` for the worker number of the bare metal node in the two `name` fields and the `credentialsName` field. Replace `<base64-of-uid>` with the `base64` string of the user name. Replace `<base64-of-pwd>` with the `base64` string of the password. Replace `<NIC1-mac-address>` with the MAC address of the bare metal node's first NIC. -+ -Refer to the BMC addressing section for additional BMC configuration options. Replace `<protocol>` with the BMC protocol, such as IPMI, RedFish, or others. -Replace `<bmc-ip>` with the IP address of the bare metal node's baseboard management controller. - -. Create the bare metal node. -+ -[source,bash] ----- -[kni@provisioner ~]$ oc -n openshift-machine-api create -f bmh.yaml ----- -+ -[source,bash] ----- -secret/openshift-worker-<num>-bmc-secret created -baremetalhost.metal3.io/openshift-worker-<num> created ----- -+ -Where `<num>` will be the worker number. - -. Power up and inspect the bare metal node. -+ -[source,bash] ----- -[kni@provisioner ~]$ oc -n openshift-machine-api get bmh openshift-worker-<num> ----- -+ -Where `<num>` is the worker node number. -+ -[source,bash] ----- -NAME STATUS PROVISIONING STATUS CONSUMER BMC HARDWARE PROFILE ONLINE ERROR -openshift-worker-<num> OK ready ipmi://<out-of-band-ip> unknown true ----- diff --git a/modules/ipi-install-preparing-the-provisioner-node-for-openshift-install.adoc b/modules/ipi-install-preparing-the-provisioner-node-for-openshift-install.adoc deleted file mode 100644 index d2f15b9f3250..000000000000 --- a/modules/ipi-install-preparing-the-provisioner-node-for-openshift-install.adoc +++ /dev/null @@ -1,162 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - -[id="preparing-the-provisioner-node-for-openshift-install_{context}"] -= Preparing the provisioner node for {product-title} installation - -Perform the following steps to prepare the environment. - -.Procedure - -. Log in to the provisioner node via `ssh`. - -. Create a non-root user (`kni`) and provide that user with `sudo` privileges. -+ -[source,terminal] ----- -# useradd kni -# passwd kni -# echo "kni ALL=(root) NOPASSWD:ALL" | tee -a /etc/sudoers.d/kni -# chmod 0440 /etc/sudoers.d/kni ----- - -. Create an `ssh` key for the new user. -+ -[source,terminal] ----- -# su - kni -c "ssh-keygen -t ed25519 -f /home/kni/.ssh/id_rsa -N ''" ----- - -. Log in as the new user on the provisioner node. -+ -[source,terminal] ----- -# su - kni -$ ----- - -. Use Red Hat Subscription Manager to register the provisioner node. -+ -[source,terminal] ----- -$ sudo subscription-manager register --username=<user> --password=<pass> --auto-attach -$ sudo subscription-manager repos --enable=rhel-8-for-x86_64-appstream-rpms --enable=rhel-8-for-x86_64-baseos-rpms ----- -+ -[NOTE] -==== -For more information about Red Hat Subscription Manager, see link:https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html-single/rhsm/index[Using and Configuring Red Hat Subscription Manager]. -==== - -. Install the following packages. -+ -[source,terminal] ----- -$ sudo dnf install -y libvirt qemu-kvm mkisofs python3-devel jq ipmitool ----- - -. Modify the user to add the `libvirt` group to the newly created user. -+ -[source,terminal] ----- -$ sudo usermod --append --groups libvirt <user> ----- - -. Restart `firewalld` and enable the `http` service. -+ -[source,terminal] ----- -$ sudo systemctl start firewalld -$ sudo firewall-cmd --zone=public --add-service=http --permanent -$ sudo firewall-cmd --reload ----- - -. Start and enable the `libvirtd` service. -+ -[source,terminal] ----- -$ sudo systemctl start libvirtd -$ sudo systemctl enable libvirtd --now ----- - -. Create the `default` storage pool and start it. -+ -[source,terminal] ----- -$ sudo virsh pool-define-as --name default --type dir --target /var/lib/libvirt/images -$ sudo virsh pool-start default -$ sudo virsh pool-autostart default ----- - -. Configure networking. -+ -[NOTE] -==== -This step can also be run from the web console. -==== -+ -[source,terminal] ----- -$ export PUB_CONN=<baremetal_nic_name> -$ export PROV_CONN=<prov_nic_name> -$ sudo nohup bash -c " - nmcli con down \"$PROV_CONN\" - nmcli con down \"$PUB_CONN\" - nmcli con delete \"$PROV_CONN\" - nmcli con delete \"$PUB_CONN\" - # RHEL 8.1 appends the word \"System\" in front of the connection, delete in case it exists - nmcli con down \"System $PUB_CONN\" - nmcli con delete \"System $PUB_CONN\" - nmcli connection add ifname provisioning type bridge con-name provisioning - nmcli con add type bridge-slave ifname \"$PROV_CONN\" master provisioning - nmcli connection add ifname baremetal type bridge con-name baremetal - nmcli con add type bridge-slave ifname \"$PUB_CONN\" master baremetal - pkill dhclient;dhclient baremetal - nmcli connection modify provisioning ipv6.addresses fd00:1101::1/64 ipv6.method manual - nmcli con down provisioning - nmcli con up provisioning -" ----- -+ -[NOTE] -==== -The `ssh` connection might disconnect after executing this step. - -The IPv6 address can be any address as long as it is not routable via the `baremetal` network. - -Ensure that UEFI is enabled and UEFI PXE settings are set to the IPv6 protocol when using IPv6 addressing. -==== - -. `ssh` back into the `provisioner` node (if required). -+ -[source,terminal] ----- -# ssh kni@provisioner.<cluster-name>.<domain> ----- - -. Verify the connection bridges have been properly created. -+ -[source,terminal] ----- -$ sudo nmcli con show ----- -+ -[source,terminal] ----- -NAME UUID TYPE DEVICE -baremetal 4d5133a5-8351-4bb9-bfd4-3af264801530 bridge baremetal -provisioning 43942805-017f-4d7d-a2c2-7cb3324482ed bridge provisioning -virbr0 d9bca40f-eee1-410b-8879-a2d4bb0465e7 bridge virbr0 -bridge-slave-eno1 76a8ed50-c7e5-4999-b4f6-6d9014dd0812 ethernet eno1 -bridge-slave-eno2 f31c3353-54b7-48de-893a-02d2b34c4736 ethernet eno2 ----- - -. Create a `pull-secret.txt` file. -+ -[source,terminal] ----- -$ vim pull-secret.txt ----- -+ -In a web browser, navigate to link:https://cloud.redhat.com/openshift/install/metal/user-provisioned[Install on Bare Metal with user-provisioned infrastructure], and scroll down to the **Downloads** section. Click **Copy pull secret**. Paste the contents into the `pull-secret.txt` file and save the contents in the `kni` user's home directory. diff --git a/modules/ipi-install-provisioning-the-bare-metal-node.adoc b/modules/ipi-install-provisioning-the-bare-metal-node.adoc deleted file mode 100644 index 841ba7ba8ff4..000000000000 --- a/modules/ipi-install-provisioning-the-bare-metal-node.adoc +++ /dev/null @@ -1,121 +0,0 @@ -// This is included in the following assemblies: -// -// ipi-install-expanding-the-cluster.adoc -[id='provisioning-the-bare-metal-node_{context}'] - -= Provisioning the bare metal node - -Provisioning the bare metal node requires executing the following procedure from the provisioner node. - -.Procedure - -. Ensure the `PROVISIONING STATUS` is `ready` before provisioning the bare metal node. -+ -[source,bash] ----- -$ oc -n openshift-machine-api get bmh openshift-worker-<num> ----- -+ -Where `<num>` is the worker node number. -+ -[source,bash] ----- -NAME STATUS PROVISIONING STATUS CONSUMER BMC HARDWARE PROFILE ONLINE ERROR -openshift-worker-<num> OK ready ipmi://<out-of-band-ip> unknown true ----- - -. Get a count of the number of worker nodes. -[source,bash] -+ ----- -$ oc get nodes ----- -+ -[source,bash] ----- -NAME STATUS ROLES AGE VERSION -provisioner.openshift.example.com Ready master 30h v1.16.2 -openshift-master-1.openshift.example.com Ready master 30h v1.16.2 -openshift-master-2.openshift.example.com Ready master 30h v1.16.2 -openshift-master-3.openshift.example.com Ready master 30h v1.16.2 -openshift-worker-0.openshift.example.com Ready master 30h v1.16.2 -openshift-worker-1.openshift.example.com Ready master 30h v1.16.2 ----- - -. Get the machine set. -+ -[source,bash] ----- -$ oc get machinesets -n openshift-machine-api ----- -+ -[source,bash] ----- -NAME DESIRED CURRENT READY AVAILABLE AGE -... -openshift-worker-0.example.com 1 1 1 1 55m -openshift-worker-1.example.com 1 1 1 1 55m ----- - -. Increase the number of worker nodes by one. -+ -[source,bash] ----- -$ oc scale --replicas=<num> machineset <machineset> -n openshift-machine-api ----- -+ -Replace `<num>` with the new number of worker nodes. Replace `<machineset>` with the name of the machine set from the previous step. - -. Check the status of the bare metal node. -+ -[source,bash] ----- -$ oc -n openshift-machine-api get bmh openshift-worker-<num> ----- -+ -Where `<num>` is the worker node number. The status changes from `ready` to `provisioning`. -+ -[source,bash] ----- -NAME STATUS PROVISIONING STATUS CONSUMER BMC HARDWARE PROFILE ONLINE ERROR -openshift-worker-<num> OK provisioning openshift-worker-<num>-65tjz ipmi://<out-of-band-ip> unknown true ----- -+ -The `provisioning` status remains until the {product-title} cluster provisions the node. This can take 30 minutes or more. Once complete, the status will change to `provisioned`. -+ -[source,bash] ----- -NAME STATUS PROVISIONING STATUS CONSUMER BMC HARDWARE PROFILE ONLINE ERROR -openshift-worker-<num> OK provisioned openshift-worker-<num>-65tjz ipmi://<out-of-band-ip> unknown true ----- - -. Once provisioned, ensure the bare metal node is ready. -+ -[source,bash] ----- -$ oc get nodes ----- -+ -[source,bash] ----- -NAME STATUS ROLES AGE VERSION -provisioner.openshift.example.com Ready master 30h v1.16.2 -openshift-master-1.openshift.example.com Ready master 30h v1.16.2 -openshift-master-2.openshift.example.com Ready master 30h v1.16.2 -openshift-master-3.openshift.example.com Ready master 30h v1.16.2 -openshift-worker-0.openshift.example.com Ready master 30h v1.16.2 -openshift-worker-1.openshift.example.com Ready master 30h v1.16.2 -openshift-worker-<num>.openshift.example.com Ready worker 3m27s v1.16.2 ----- -+ -You can also check the kubelet. -+ -[source,bash] ----- -$ ssh openshift-worker-<num> ----- -+ -[source,bash] ----- -[kni@openshift-worker-<num>]$ journalctl -fu kubelet ----- diff --git a/modules/ipi-install-required-data-for-installation.adoc b/modules/ipi-install-required-data-for-installation.adoc deleted file mode 100644 index 98bdf5cc66a3..000000000000 --- a/modules/ipi-install-required-data-for-installation.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc - -[id="required-data-for-installation_{context}"] -= Required data for installation - -Prior to the installation of the {product-title} cluster, gather the following information from all cluster nodes: - -* Out-of-band management IP -** Examples -*** Dell (iDRAC) IP -*** HP (iLO) IP - -.When using the `provisioning` network - -* NIC1 (`provisioning`) MAC address -* NIC2 (`baremetal`) MAC address - -.When omitting the `provisioning` network - -* NICx (`baremetal`) MAC address diff --git a/modules/ipi-install-retrieving-the-openshift-installer.adoc b/modules/ipi-install-retrieving-the-openshift-installer.adoc deleted file mode 100644 index 545526c070e4..000000000000 --- a/modules/ipi-install-retrieving-the-openshift-installer.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - - -[id="retrieving-the-openshift-installer_{context}"] -= Retrieving the {product-title} installer - -Use the `latest-4.x` version of the installer to deploy the latest generally -available version of {product-title}: - -[source,terminal] ----- -$ export VERSION=latest-4.7 -export RELEASE_IMAGE=$(curl -s https://mirror.openshift.com/pub/openshift-v4/clients/ocp/$VERSION/release.txt | grep 'Pull From: quay.io' | awk -F ' ' '{print $3}') ----- diff --git a/modules/ipi-install-root-device-hints.adoc b/modules/ipi-install-root-device-hints.adoc deleted file mode 100644 index 7f775263b30a..000000000000 --- a/modules/ipi-install-root-device-hints.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// This is included in the following assemblies: -// -// ipi-install-configuration-files.adoc - -[id='root-device-hints_{context}'] - -= Root device hints - -The `rootDeviceHints` parameter enables the installer to provision the {op-system-first} image to a particular device. The installer examines the devices in the order it discovers them, and compares the discovered values with the hint values. The installer uses the first discovered device that matches the hint value. The configuration can combine multiple hints, but a device must match all hints for the installer to select it. - -.Subfields - -|=== -| Subfield | Description - -| `deviceName` | A string containing a Linux device name like `/dev/vda`. The hint must match the actual value exactly. - -| `hctl` | A string containing a SCSI bus address like `0:0:0:0`. The hint must match the actual value exactly. - -| `model` | A string containing a vendor-specific device identifier. The hint can be a substring of the actual value. - -| `vendor` | A string containing the name of the vendor or manufacturer of the device. The hint can be a sub-string of the actual value. - -| `serialNumber` | A string containing the device serial number. The hint must match the actual value exactly. - -| `minSizeGigabytes` | An integer representing the minimum size of the device in gigabytes. - -| `wwn` | A string containing the unique storage identifier. The hint must match the actual value exactly. - -| `wwnWithExtension` | A string containing the unique storage identifier with the vendor extension appended. The hint must match the actual value exactly. - -| `wwnVendorExtension` | A string containing the unique vendor storage identifier. The hint must match the actual value exactly. - -| `rotational` | A boolean indicating whether the device should be a rotating disk (true) or not (false). - -|=== - -.Example usage - -[source,yaml] ----- - - name: master-0 - role: master - bmc: - address: ipmi://10.10.0.3:6203 - username: admin - password: redhat - bootMACAddress: de:ad:be:ef:00:40 - rootDeviceHints: - deviceName: "/dev/sda" ----- diff --git a/modules/ipi-install-setting-proxy-settings-within-install-config.adoc b/modules/ipi-install-setting-proxy-settings-within-install-config.adoc deleted file mode 100644 index 27cc7a1be2f4..000000000000 --- a/modules/ipi-install-setting-proxy-settings-within-install-config.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// This is included in the following assemblies: -// -// ipi-install-configuration-files.adoc -[id='ipi-install-setting-proxy-settings-within-install-config_{context}'] - -= Setting proxy settings within the `install-config.yaml` file (optional) - -To deploy an {product-title} cluster using a proxy, make the following changes to the `install-config.yaml` file. - -[source,yaml] ----- -apiVersion: v1 -baseDomain: <domain> -proxy: - httpProxy: http://USERNAME:PASSWORD@proxy.example.com:PORT - httpsProxy: https://USERNAME:PASSWORD@proxy.example.com:PORT - noProxy: <WILDCARD_OF_DOMAIN>,<PROVISIONING_NETWORK/CIDR>,<BMC_ADDRESS_RANGE/CIDR> ----- - -The following is an example of `noProxy` with values. - -[source,yaml] ----- -noProxy: .example.com,172.22.0.0/24,10.10.0.0/24 ----- - -With a proxy enabled, set the appropriate values of the proxy in the corresponding key/value pair. - -Key considerations: - -* If the proxy does not have an HTTPS proxy, change the value of `httpsProxy` from `https://` to `http://`. -* If using a provisioning network, include it in the `noProxy` setting, otherwise the installer will fail. -* Set all of the proxy settings as environment variables within the provisioner node. For example, `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. diff --git a/modules/ipi-install-troubleshooting-api-not-accessible.adoc b/modules/ipi-install-troubleshooting-api-not-accessible.adoc deleted file mode 100644 index a26b37849a18..000000000000 --- a/modules/ipi-install-troubleshooting-api-not-accessible.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-api-not-accessible_{context}"] - -= The API is not accessible - -When the cluster is running and clients cannot access the API, domain name resolution issues might impede access to the API. - -.Procedure - -. **Hostname Resolution:** Check the cluster nodes to ensure they have a fully qualified domain name, and not just `localhost.localdomain`. For example: -+ -[source,terminal] ----- -$ hostname ----- -+ -If a hostname is not set, set the correct hostname. For example: -+ -[source,terminal] ----- -$ hostnamectl set-hostname <hostname> ----- - -. **Incorrect Name Resolution:** Ensure that each node has the correct name resolution in the DNS server using `dig` and `nslookup`. For example: -+ -[source,terminal] ----- -$ dig api.<cluster-name>.example.com ----- -+ -[source,terminal] ----- -; <<>> DiG 9.11.4-P2-RedHat-9.11.4-26.P2.el8 <<>> api.<cluster-name>.example.com -;; global options: +cmd -;; Got answer: -;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 37551 -;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 2 - -;; OPT PSEUDOSECTION: -; EDNS: version: 0, flags:; udp: 4096 -; COOKIE: 866929d2f8e8563582af23f05ec44203d313e50948d43f60 (good) -;; QUESTION SECTION: -;api.<cluster-name>.example.com. IN A - -;; ANSWER SECTION: -api.<cluster-name>.example.com. 10800 IN A 10.19.13.86 - -;; AUTHORITY SECTION: -<cluster-name>.example.com. 10800 IN NS <cluster-name>.example.com. - -;; ADDITIONAL SECTION: -<cluster-name>.example.com. 10800 IN A 10.19.14.247 - -;; Query time: 0 msec -;; SERVER: 10.19.14.247#53(10.19.14.247) -;; WHEN: Tue May 19 20:30:59 UTC 2020 -;; MSG SIZE rcvd: 140 ----- -+ -The output in the foregoing example indicates that the appropriate IP address for the `api.<cluster-name>.example.com` VIP is `10.19.13.86`. This IP address should reside on the `baremetal` network. diff --git a/modules/ipi-install-troubleshooting-bootstrap-vm-cannot-boot.adoc b/modules/ipi-install-troubleshooting-bootstrap-vm-cannot-boot.adoc deleted file mode 100644 index 566f15cb056f..000000000000 --- a/modules/ipi-install-troubleshooting-bootstrap-vm-cannot-boot.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-bootstrap-vm-cannot-boot_{context}"] -= Bootstrap VM cannot boot up the cluster nodes - -During the deployment, it is possible for the bootstrap VM to fail to boot the cluster nodes, which prevents the VM from provisioning the nodes with the {op-system} image. This scenario can arise due to: - -* A problem with the `install-config.yaml` file. -* Issues with out-of-band network access via the baremetal network. - -To verify the issue, there are three containers related to `ironic`: - -* `ironic-api` -* `ironic-conductor` -* `ironic-inspector` - -.Procedure - -. Log in to the bootstrap VM: -+ -[source,bash] ----- -$ ssh core@172.22.0.2 ----- - -. To check the container logs, execute the following: -+ -[source,bash] ----- -[core@localhost ~]$ sudo podman logs -f <container-name> ----- -+ -Replace `<container-name>` with one of `ironic-api`, `ironic-conductor`, or `ironic-inspector`. If you encounter an issue where the control plane nodes are not booting up via PXE, check the `ironic-conductor` pod. The `ironic-conductor` pod contains the most detail about the attempt to boot the cluster nodes, because it attempts to log in to the node over IPMI. - -.Potential reason -The cluster nodes might be in the `ON` state when deployment started. - -.Solution -Power off the {product-title} cluster nodes before you begin the -installation over IPMI: - -[source,bash] ----- -$ ipmitool -I lanplus -U root -P <password> -H <out-of-band-ip> power off ----- diff --git a/modules/ipi-install-troubleshooting-bootstrap-vm-inspecting-logs.adoc b/modules/ipi-install-troubleshooting-bootstrap-vm-inspecting-logs.adoc deleted file mode 100644 index 9abaa1ff72d2..000000000000 --- a/modules/ipi-install-troubleshooting-bootstrap-vm-inspecting-logs.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-bootstrap-vm-inspecting-logs_{context}"] -= Inspecting logs - -When experiencing issues downloading or accessing the {op-system} images, first verify that the URL is correct in the `install-config.yaml` configuration file. - -.Example of internal webserver hosting {op-system} images -[source,yaml] ----- -bootstrapOSImage: http://<ip:port>/rhcos-43.81.202001142154.0-qemu.x86_64.qcow2.gz?sha256=9d999f55ff1d44f7ed7c106508e5deecd04dc3c06095d34d36bf1cd127837e0c -clusterOSImage: http://<ip:port>/rhcos-43.81.202001142154.0-openstack.x86_64.qcow2.gz?sha256=a1bda656fa0892f7b936fdc6b6a6086bddaed5dafacedcd7a1e811abb78fe3b0 ----- - -The `ipa-downloader` and `coreos-downloader` containers download resources from a webserver or the external link:https://quay.io[quay.io] registry, whichever the `install-config.yaml` configuration file specifies. Verify the following two containers are up and running and inspect their logs as needed: - -* `ipa-downloader` -* `coreos-downloader` - -.Procedure - -. Log in to the bootstrap VM: -+ -[source,bash] ----- -$ ssh core@172.22.0.2 ----- - -. Check the status of the `ipa-downloader` and `coreos-downloader` containers within the bootstrap VM: -+ -[source,bash] ----- -[core@localhost ~]$ podman logs -f ipa-downloader ----- -+ -[source,bash] ----- -[core@localhost ~]$ podman logs -f coreos-downloader ----- -+ -If the bootstrap VM cannot access the URL to the images, use the `curl` command to verify that the VM can access the images. - -. To inspect the `bootkube` logs that indicate if all the containers launched during the deployment phase, execute the following: -+ -[source,bash] ----- -[core@localhost ~]$ journalctl -xe ----- -+ -[source,bash] ----- -[core@localhost ~]$ journalctl -b -f -u bootkube.service ----- - -. Verify all the pods, including `dnsmasq`, `mariadb`, `httpd`, and `ironic`, are running: -+ -[source,bash] ----- -[core@localhost ~]$ sudo podman ps ----- - -. If there are issues with the pods, check the logs of the containers with issues. To check the log of the `ironic-api`, execute the following: -+ -[source,bash] ----- -[core@localhost ~]$ sudo podman logs <ironic-api> ----- diff --git a/modules/ipi-install-troubleshooting-bootstrap-vm.adoc b/modules/ipi-install-troubleshooting-bootstrap-vm.adoc deleted file mode 100644 index 5f858b90e168..000000000000 --- a/modules/ipi-install-troubleshooting-bootstrap-vm.adoc +++ /dev/null @@ -1,107 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-bootstrap-vm_{context}"] - -= Bootstrap VM issues - -The {product-title} installer spawns a bootstrap node virtual machine, which handles provisioning the {product-title} cluster nodes. - -.Procedure - -. About 10 to 15 minutes after triggering the installer, check to ensure the bootstrap VM is operational using the `virsh` command: -+ -[source,bash] ----- -$ sudo virsh list ----- -+ -[source,bash] ----- - Id Name State - -------------------------------------------- - 12 openshift-xf6fq-bootstrap running ----- - - -[NOTE] -==== -The name of the bootstrap VM is always the cluster name followed by a random set of characters and ending in the word "bootstrap." -==== - -If the bootstrap VM is not running after 10-15 minutes, troubleshoot why it is not running. Possible issues include: - -. Verify `libvirtd` is running on the system: -+ -[source,bash] ----- -$ systemctl status libvirtd ----- -+ -[source,bash] ----- -● libvirtd.service - Virtualization daemon - Loaded: loaded (/usr/lib/systemd/system/libvirtd.service; enabled; vendor preset: enabled) - Active: active (running) since Tue 2020-03-03 21:21:07 UTC; 3 weeks 5 days ago - Docs: man:libvirtd(8) - https://libvirt.org - Main PID: 9850 (libvirtd) - Tasks: 20 (limit: 32768) - Memory: 74.8M - CGroup: /system.slice/libvirtd.service - ├─ 9850 /usr/sbin/libvirtd ----- -+ -If the bootstrap VM is operational, log into it. - -. Use the `virsh console` command to find the IP address of the bootstrap VM: -+ -[source,bash] ----- -$ sudo virsh console example.com ----- -+ -[source,bash] ----- -Connected to domain example.com -Escape character is ^] - -Red Hat Enterprise Linux CoreOS 43.81.202001142154.0 (Ootpa) 4.3 -SSH host key: SHA256:BRWJktXZgQQRY5zjuAV0IKZ4WM7i4TiUyMVanqu9Pqg (ED25519) -SSH host key: SHA256:7+iKGA7VtG5szmk2jB5gl/5EZ+SNcJ3a2g23o0lnIio (ECDSA) -SSH host key: SHA256:DH5VWhvhvagOTaLsYiVNse9ca+ZSW/30OOMed8rIGOc (RSA) -ens3: fd35:919d:4042:2:c7ed:9a9f:a9ec:7 -ens4: 172.22.0.2 fe80::1d05:e52e:be5d:263f -localhost login: ----- -+ -[IMPORTANT] -==== -When deploying a {product-title} cluster without the `provisioning` network, you must use a public IP address and not a private IP address like `172.22.0.2`. -==== - - -. Once you obtain the IP address, log in to the bootstrap VM using the `ssh` command: -+ -[NOTE] -==== -In the console output of the previous step, you can use the IPv6 IP address provided by `ens3` or the IPv4 IP provided by `ens4`. -==== -+ -[source,bash] ----- -$ ssh core@172.22.0.2 ----- - -If you are not successful logging in to the bootstrap VM, you have likely encountered one of the following scenarios: - -* You cannot reach the `172.22.0.0/24` network. Verify network connectivity on the provisioner host specifically around the `provisioning` network bridge. This will not be the issue if you are not using the `provisioning` network. - -* You cannot reach the bootstrap VM via the public network. When attempting -to SSH via `baremetal` network, verify connectivity on the -`provisioner` host specifically around the `baremetal` network bridge. - -* You encountered `Permission denied (publickey,password,keyboard-interactive)`. When -attempting to access the bootstrap VM, a `Permission denied` error -might occur. Verify that the SSH key for the user attempting to log -into the VM is set within the `install-config.yaml` file. diff --git a/modules/ipi-install-troubleshooting-cleaning-up-previous-installations.adoc b/modules/ipi-install-troubleshooting-cleaning-up-previous-installations.adoc deleted file mode 100644 index f68f58cbd1ee..000000000000 --- a/modules/ipi-install-troubleshooting-cleaning-up-previous-installations.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-cleaning-up-previous-installations_{context}"] -= Cleaning up previous installations - -In the event of a previous failed deployment, remove the artifacts from the failed attempt before attempting to deploy {product-title} again. - -.Procedure - -. Power off all bare metal nodes prior to installing the {product-title} cluster: -+ -[source,terminal] ----- -$ ipmitool -I lanplus -U <user> -P <password> -H <management-server-ip> power off ----- - -. Remove all old bootstrap resources if any are left over from a previous deployment attempt: -+ -[source,bash] ----- -for i in $(sudo virsh list | tail -n +3 | grep bootstrap | awk {'print $2'}); -do - sudo virsh destroy $i; - sudo virsh undefine $i; - sudo virsh vol-delete $i --pool default; - sudo virsh vol-delete $i.ign --pool default; -done ----- - -. Remove the following from the `clusterconfigs` directory to prevent Terraform from failing: -+ -[source,terminal] ----- -$ rm -rf ~/clusterconfigs/auth ~/clusterconfigs/terraform* ~/clusterconfigs/tls ~/clusterconfigs/metadata.json ----- diff --git a/modules/ipi-install-troubleshooting-cluster-nodes-will-not-pxe.adoc b/modules/ipi-install-troubleshooting-cluster-nodes-will-not-pxe.adoc deleted file mode 100644 index c5cee83f3e3e..000000000000 --- a/modules/ipi-install-troubleshooting-cluster-nodes-will-not-pxe.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-cluster-nodes-will-not-pxe_{context}"] - -= Cluster nodes will not PXE boot - -When {product-title} cluster nodes will not PXE boot, execute the following checks on the cluster nodes that will not PXE boot. This procedure does not apply when installing a {product-title} cluster without the `provisioning` network. - -.Procedure - -. Check the network connectivity to the `provisioning` network. - -. Ensure PXE is enabled on the NIC for the `provisioning` network and PXE is disabled for all other NICs. - -. Verify that the `install-config.yaml` configuration file has the proper hardware profile and boot MAC address for the NIC connected to the `provisioning` network. For example: -+ -.Master node settings -+ ----- -bootMACAddress: 24:6E:96:1B:96:90 # MAC of bootable provisioning NIC -hardwareProfile: default #master node settings ----- -+ -.Worker node settings -+ ----- -bootMACAddress: 24:6E:96:1B:96:90 # MAC of bootable provisioning NIC -hardwareProfile: unknown #worker node settings ----- diff --git a/modules/ipi-install-troubleshooting-failed-ignition-during-firstboot.adoc b/modules/ipi-install-troubleshooting-failed-ignition-during-firstboot.adoc deleted file mode 100644 index 384f6644dbea..000000000000 --- a/modules/ipi-install-troubleshooting-failed-ignition-during-firstboot.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-failed-ignition-during-firstboot_{context}"] - -= Failed Ignition during Firstboot - -During the Firstboot, the Ignition configuration may fail. - -.Procedure - -. Connect to the node where the Ignition configuration failed: -+ -[source,terminal] ----- -Failed Units: 1 - machine-config-daemon-firstboot.service ----- - -. Restart the `machine-config-daemon-firstboot` service: -+ -[source,terminal] ----- -[core@worker-X ~]$ sudo systemctl restart machine-config-daemon-firstboot.service ----- diff --git a/modules/ipi-install-troubleshooting-install-config.adoc b/modules/ipi-install-troubleshooting-install-config.adoc deleted file mode 100644 index 8e156b0f9513..000000000000 --- a/modules/ipi-install-troubleshooting-install-config.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-install-config_{context}"] - -= Troubleshooting `install-config.yaml` - -The `install-config.yaml` configuration file represents all of the nodes that are part of the {product-title} cluster. The file contains the necessary options consisting of but not limited to `apiVersion`, `baseDomain`, `imageContentSources` and virtual IP addresses. If errors occur early in the deployment of the {product-title} cluster, the errors are likely in the `install-config.yaml` configuration file. - -.Procedure - -. Use the guidelines in link:https://www.redhat.com/sysadmin/yaml-tips[YAML-tips]. -. Verify the YAML syntax is correct using link:http://www.yamllint.com/[syntax-check]. -. Verify the {op-system-first} QEMU images are properly defined and accessible via the URL provided in the `install-config.yaml`. For example: -+ -[source,terminal] ----- -$ curl -s -o /dev/null -I -w "%{http_code}\n" http://webserver.example.com:8080/rhcos-44.81.202004250133-0-qemu.x86_64.qcow2.gz?sha256=7d884b46ee54fe87bbc3893bf2aa99af3b2d31f2e19ab5529c60636fbd0f1ce7 ----- -+ -If the output is `200`, there is a valid response from the webserver storing the bootstrap VM image. diff --git a/modules/ipi-install-troubleshooting-misc-issues.adoc b/modules/ipi-install-troubleshooting-misc-issues.adoc deleted file mode 100644 index 35b2483765cc..000000000000 --- a/modules/ipi-install-troubleshooting-misc-issues.adoc +++ /dev/null @@ -1,269 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-misc-issues_{context}"] - -= Miscellaneous issues - -== Addressing the `runtime network not ready` error - -After the deployment of a cluster you might receive the following error: - ----- -`runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:Network plugin returns error: Missing CNI default network` ----- - -The Cluster Network Operator is responsible for deploying the networking components in response to a special object created by the installer. It runs very early in the installation process, after the control plane (master) nodes have come up, but before the bootstrap control plane has been torn down. It can be indicative of more subtle installer issues, such as long delays in bringing up control plane (master) nodes or issues with `apiserver` communication. - -.Procedure - -. Inspect the pods in the `openshift-network-operator` namespace: -+ -[source,terminal] ----- -$ oc get all -n openshift-network-operator ----- -+ -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -pod/network-operator-69dfd7b577-bg89v 0/1 ContainerCreating 0 149m ----- - - -. On the `provisioner` node, determine that the network configuration exists: -+ -[source,terminal] ----- -$ kubectl get network.config.openshift.io cluster -oyaml ----- -+ -[source,terminal] ----- -apiVersion: config.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - serviceNetwork: - - 172.30.0.0/16 - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - networkType: OpenShiftSDN ----- -+ -If it does not exist, the installer did not create it. To determine why the installer did not create it, execute the following: -+ -[source,terminal] ----- -$ openshift-install create manifests ----- - -. Check that the `network-operator` is running: -+ -[source,terminal] ----- -$ kubectl -n openshift-network-operator get pods ----- - -. Retrieve the logs: -+ -[source,terminal] ----- -$ kubectl -n openshift-network-operator logs -l "name=network-operator" ----- -+ -On high availability clusters with three or more control plane (master) nodes, the Operator will perform leader election and all other Operators will sleep. For additional details, see https://github.com/openshift/installer/blob/master/docs/user/troubleshooting.md[Troubleshooting]. - -== Cluster nodes not getting the correct IPv6 address over DHCP - -If the cluster nodes are not getting the correct IPv6 address over DHCP, check the following: - -. Ensure the reserved IPv6 addresses reside outside the DHCP range. - -. In the IP address reservation on the DHCP server, ensure the reservation specifies the correct DHCP Unique Identifier (DUID). For example: -+ -[source,terminal] ----- -# This is a dnsmasq dhcp reservation, 'id:00:03:00:01' is the client id and '18:db:f2:8c:d5:9f' is the MAC Address for the NIC -id:00:03:00:01:18:db:f2:8c:d5:9f,openshift-master-1,[2620:52:0:1302::6] ----- - -. Ensure that route announcements are working. - -. Ensure that the DHCP server is listening on the required interfaces serving the IP address ranges. - - -== Cluster nodes not getting the correct hostname over DHCP - -During IPv6 deployment, cluster nodes must get their hostname over DHCP. Sometimes the `NetworkManager` does not assign the hostname immediately. A control plane (master) node might report an error such as: - ----- -Failed Units: 2 - NetworkManager-wait-online.service - nodeip-configuration.service ----- - -This error indicates that the cluster node likely booted without first receiving a hostname from the DHCP server, which causes `kubelet` to boot -with a `localhost.localdomain` hostname. To address the error, force the node to renew the hostname. - -.Procedure - -. Retrieve the `hostname`: -+ -[source,terminal] ----- -[core@master-X ~]$ hostname ----- -+ -If the hostname is `localhost`, proceed with the following steps. -+ -[NOTE] -==== -Where `X` is the master node number. -==== - -. Force the cluster node to renew the DHCP lease: -+ -[source,terminal] ----- -[core@master-X ~]$ sudo nmcli con up "<bare-metal-nic>" ----- -+ -Replace `<bare-metal-nic>` with the wired connection corresponding to the `baremetal` network. - -. Check `hostname` again: -+ -[source,terminal] ----- -[core@master-X ~]$ hostname ----- - -. If the hostname is still `localhost.localdomain`, restart `NetworkManager`: -+ -[source,terminal] ----- -[core@master-X ~]$ sudo systemctl restart NetworkManager ----- - -. If the hostname is still `localhost.localdomain`, wait a few minutes and check again. If the hostname remains `localhost.localdomain`, repeat the previous steps. - -. Restart the `nodeip-configuration` service: -+ -[source,terminal] ----- -[core@master-X ~]$ sudo systemctl restart nodeip-configuration.service ----- -+ -This service will reconfigure the `kubelet` service with the correct hostname references. - -. Reload the unit files definition since the kubelet changed in the previous step: -+ -[source,terminal] ----- -[core@master-X ~]$ sudo systemctl daemon-reload ----- - -. Restart the `kubelet` service: -+ -[source,terminal] ----- -[core@master-X ~]$ sudo systemctl restart kubelet.service ----- - -. Ensure `kubelet` booted with the correct hostname: -+ -[source,terminal] ----- -[core@master-X ~]$ sudo journalctl -fu kubelet.service ----- - -If the cluster node is not getting the correct hostname over DHCP after the cluster is up and running, such as during a reboot, the cluster will have a pending `csr`. **Do not** approve a `csr`, or other issues might arise. - -.Addressing a `csr` - -. Get CSRs on the cluster: -+ -[source,terminal] ----- -$ oc get csr ----- - -. Verify if a pending `csr` contains `Subject Name: localhost.localdomain`: -+ -[source,terminal] ----- -$ oc get csr <pending_csr> -o jsonpath='{.spec.request}' | base64 -d | openssl req -noout -text ----- - -. Remove any `csr` that contains `Subject Name: localhost.localdomain`: -+ -[source,terminal] ----- -$ oc delete csr <wrong_csr> ----- - -== Routes do not reach endpoints - -During the installation process, it is possible to encounter a Virtual Router Redundancy Protocol (VRRP) conflict. This conflict might occur if a previously used {product-title} node that was once part of a cluster deployment using a specific cluster name is still running but not part of the current {product-title} cluster deployment using that same cluster name. For example, a cluster was deployed using the cluster name `openshift`, deploying three control plane (master) nodes and three worker nodes. Later, a separate install uses the same cluster name `openshift`, but this redeployment only installed three control plane (master) nodes, leaving the three worker nodes from a previous deployment in an `ON` state. This might cause a Virtual Router Identifier (VRID) conflict and a VRRP conflict. - -. Get the route: -+ -[source,terminal] ----- -$ oc get route oauth-openshift ----- - -. Check the service endpoint: -+ -[source,terminal] ----- -$ oc get svc oauth-openshift ----- -+ -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -oauth-openshift ClusterIP 172.30.19.162 <none> 443/TCP 59m ----- - -. Attempt to reach the service from a control plane (master) node: -+ -[source,terminal] ----- -[core@master0 ~]$ curl -k https://172.30.19.162 ----- -+ -[source,terminal] ----- -{ - "kind": "Status", - "apiVersion": "v1", - "metadata": { - }, - "status": "Failure", - "message": "forbidden: User \"system:anonymous\" cannot get path \"/\"", - "reason": "Forbidden", - "details": { - }, - "code": 403 ----- - -. Identify the `authentication-operator` errors from the `provisioner` node: -+ -[source,terminal] ----- -$ oc logs deployment/authentication-operator -n openshift-authentication-operator ----- -+ -[source,terminal] ----- -Event(v1.ObjectReference{Kind:"Deployment", Namespace:"openshift-authentication-operator", Name:"authentication-operator", UID:"225c5bd5-b368-439b-9155-5fd3c0459d98", APIVersion:"apps/v1", ResourceVersion:"", FieldPath:""}): type: 'Normal' reason: 'OperatorStatusChanged' Status for clusteroperator/authentication changed: Degraded message changed from "IngressStateEndpointsDegraded: All 2 endpoints for oauth-server are reporting" ----- - -.Solution - -. Ensure that the cluster name for every deployment is unique, ensuring no conflict. - -. Turn off all the rogue nodes which are not part of the cluster deployment that are using the same cluster name. Otherwise, the authentication pod of the {product-title} cluster might never start successfully. diff --git a/modules/ipi-install-troubleshooting-ntp-out-of-sync.adoc b/modules/ipi-install-troubleshooting-ntp-out-of-sync.adoc deleted file mode 100644 index c741870cde19..000000000000 --- a/modules/ipi-install-troubleshooting-ntp-out-of-sync.adoc +++ /dev/null @@ -1,161 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-ntp-out-of-sync_{context}"] - -= NTP out of sync - -The deployment of {product-title} clusters depends on NTP synchronized clocks among the cluster nodes. Without synchronized clocks, the deployment may fail due to clock drift if the time difference is greater than two seconds. - -.Procedure - -. Check for differences in the `AGE` of the cluster nodes. For example: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -master-0.cloud.example.com Ready master 145m v1.16.2 -master-1.cloud.example.com Ready master 135m v1.16.2 -master-2.cloud.example.com Ready master 145m v1.16.2 -worker-2.cloud.example.com Ready worker 100m v1.16.2 ----- - -. Check for inconsistent timing delays due to clock drift. For example: -+ -[source,terminal] ----- -$ oc get bmh -n openshift-machine-api ----- -+ -[source,terminal] ----- -master-1 error registering master-1 ipmi://<out-of-band-ip> ----- -+ -[source,terminal] ----- -$ sudo timedatectl ----- -+ -[source,terminal] ----- - Local time: Tue 2020-03-10 18:20:02 UTC - Universal time: Tue 2020-03-10 18:20:02 UTC - RTC time: Tue 2020-03-10 18:36:53 - Time zone: UTC (UTC, +0000) -System clock synchronized: no - NTP service: active - RTC in local TZ: no ----- - -.Addressing clock drift in existing clusters - -. Create a `chrony.conf` file and encode it as `base64` string. For example: -+ -[source,terminal] ----- -$ cat << EOF | base 64 -server <NTP-server> iburst<1> -stratumweight 0 -driftfile /var/lib/chrony/drift -rtcsync -makestep 10 3 -bindcmdaddress 127.0.0.1 -bindcmdaddress ::1 -keyfile /etc/chrony.keys -commandkey 1 -generatecommandkey -noclientlog -logchange 0.5 -logdir /var/log/chrony -EOF ----- -<1> Replace `<NTP-server>` with the IP address of the NTP server. Copy the output. -+ ----- -[text-in-base-64] ----- - -. Create a `MachineConfig` object, replacing the `base64` string with -the `[text-in-base-64]` string generated in the output of the previous step. The following example adds the file to the control plane (master) nodes. You can modify the file for worker nodes or make an additional machine config for the worker role. -+ -[source,terminal] ----- -$ cat << EOF > ./99_masters-chrony-configuration.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - creationTimestamp: null - labels: - machineconfiguration.openshift.io/role: master - name: 99-master-etc-chrony-conf -spec: - config: - ignition: - config: {} - security: - tls: {} - timeouts: {} - version: 3.1.0 - networkd: {} - passwd: {} - storage: - files: - - contents: - source: data:text/plain;charset=utf-8;base64,[text-in-base-64]<1> - group: - name: root - mode: 420 - overwrite: true - path: /etc/chrony.conf - user: - name: root - osImageURL: "" ----- -<1> Replace `[text-in-base-64]` with the base64 string. - -. Make a backup copy of the configuration file. For example: -+ -[source,terminal] ----- -$ cp 99_masters-chrony-configuration.yaml 99_masters-chrony-configuration.yaml.backup ----- - -. Apply the configuration file: -+ -[source,terminal] ----- -$ oc apply -f ./masters-chrony-configuration.yaml ----- - -. Ensure the `System clock synchronized` value is **yes**: -+ -[source,terminal] ----- -$ sudo timedatectl ----- -+ -[source,terminal] ----- - Local time: Tue 2020-03-10 19:10:02 UTC - Universal time: Tue 2020-03-10 19:10:02 UTC - RTC time: Tue 2020-03-10 19:36:53 - Time zone: UTC (UTC, +0000) -System clock synchronized: yes - NTP service: active - RTC in local TZ: no ----- -+ -To setup clock synchronization prior to deployment, generate the manifest files and add this file to the `openshift` directory. For example: -+ -[source,terminal] ----- -$ cp chrony-masters.yaml ~/clusterconfigs/openshift/99_masters-chrony-configuration.yaml ----- -+ -Then, continue to create the cluster. diff --git a/modules/ipi-install-troubleshooting-registry-issues.adoc b/modules/ipi-install-troubleshooting-registry-issues.adoc deleted file mode 100644 index 9eb8a800da6d..000000000000 --- a/modules/ipi-install-troubleshooting-registry-issues.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-registry-issues_{context}"] - -= Issues with creating the registry - -When creating a disconnected registry, you might encounter a "User Not Authorized" error when attempting to mirror the registry. This error might occur if you fail to append the new authentication to the existing `pull-secret.txt` file. - -.Procedure - -. Check to ensure authentication is successful: -+ -[source,terminal] ----- -[user@registry ~]$ /usr/local/bin/oc adm release mirror \ - -a pull-secret-update.json - --from=$UPSTREAM_REPO \ - --to-release-image=$LOCAL_REG/$LOCAL_REPO:${VERSION} \ - --to=$LOCAL_REG/$LOCAL_REPO ----- -+ -[NOTE] -==== -Example output of the variables used to mirror the install images: - -[source,terminal] ----- -UPSTREAM_REPO=${RELEASE_IMAGE} -LOCAL_REG=<registry_FQDN>:<registry_port> -LOCAL_REPO='ocp4/openshift4' ----- - -The values of `RELEASE_IMAGE` and `VERSION` were set during the **Retrieving OpenShift Installer** step of the **Setting up the environment for an OpenShift installation** section. -==== - -. After mirroring the registry, confirm that you can access it in your -disconnected environment: -+ -[source,terminal] ----- -$ curl -k -u <user>:<password> https://registry.example.com:<registry-port>/v2/_catalog -{"repositories":["<Repo-Name>"]} ----- diff --git a/modules/ipi-install-troubleshooting-reviewing-the-installation.adoc b/modules/ipi-install-troubleshooting-reviewing-the-installation.adoc deleted file mode 100644 index 4cb682bfee67..000000000000 --- a/modules/ipi-install-troubleshooting-reviewing-the-installation.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// //installing/installing_bare_metal_ipi/installing_bare_metal_ipi/ipi-install-troubleshooting.adoc - -[id="ipi-install-troubleshooting-reviewing-the-installation_{context}"] - -= Reviewing the installation - -After installation, ensure the installer deployed the nodes and pods successfully. - -.Procedure - -. When the {product-title} cluster nodes are installed appropriately, the following `Ready` state is seen within the `STATUS` column: -+ -[source,bash] ----- -$ oc get nodes ----- -+ -[source,bash] ----- -NAME STATUS ROLES AGE VERSION -master-0.example.com Ready master,worker 4h v1.16.2 -master-1.example.com Ready master,worker 4h v1.16.2 -master-2.example.com Ready master,worker 4h v1.16.2 ----- - -. Confirm the installer deployed all pods successfully. The following command -removes any pods that are still running or have completed as part of the output. -+ -[source,bash] ----- -$ oc get pods --all-namespaces | grep -iv running | grep -iv complete ----- diff --git a/modules/ipi-install-validation-checklist-for-installation.adoc b/modules/ipi-install-validation-checklist-for-installation.adoc deleted file mode 100644 index 56c84373b0d0..000000000000 --- a/modules/ipi-install-validation-checklist-for-installation.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc - - -[id="validation-checklist-for-installation_{context}"] -= Validation checklist for installation - -* [ ] {product-title} installer has been retrieved. -* [ ] {product-title} installer has been extracted. -* [ ] Required parameters for the `install-config.yaml` have been configured. -* [ ] The `hosts` parameter for the `install-config.yaml` has been configured. -* [ ] The `bmc` parameter for the `install-config.yaml` has been configured. -* [ ] Conventions for the values configured in the `bmc` `address` field have been applied. -* [ ] Created a disconnected registry (optional). -* [ ] (optional) Validate disconnected registry settings if in use. -* [ ] (optional) Deployed routers on worker nodes. diff --git a/modules/ipi-install-validation-checklist-for-nodes.adoc b/modules/ipi-install-validation-checklist-for-nodes.adoc deleted file mode 100644 index bc442bff5c31..000000000000 --- a/modules/ipi-install-validation-checklist-for-nodes.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal_ipi/ipi-install-prerequisites.adoc - - -[id="validation-checklist-for-nodes_{context}"] -= Validation checklist for nodes - -.When using the `provisioning` network - -* [ ] NIC1 VLAN is configured for the `provisioning` network. -* [ ] NIC2 VLAN is configured for the `baremetal` network. -* [ ] NIC1 is PXE-enabled on the provisioner, control plane (master), and worker nodes. -* [ ] PXE has been disabled on all other NICs. -* [ ] Control plane and worker nodes are configured. -* [ ] All nodes accessible via out-of-band management. -* [ ] A separate management network has been created. (optional) -* [ ] Required data for installation. - -.When omitting the `provisioning` network - -* [ ] NICx VLAN is configured for the `baremetal` network. -* [ ] Control plane and worker nodes are configured. -* [ ] All nodes accessible via out-of-band management. -* [ ] A separate management network has been created. (optional) -* [ ] Required data for installation. diff --git a/modules/ipsec-impact-networking.adoc b/modules/ipsec-impact-networking.adoc deleted file mode 100644 index 96a02ce93f40..000000000000 --- a/modules/ipsec-impact-networking.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/optimizing-networking.adoc - -[id="ipsec-impact_{context}"] -= Impact of IPsec - -Because encrypting and decrypting node hosts uses CPU power, performance is affected both in throughput and CPU usage on the nodes when encryption is enabled, regardless of the IP security system being used. - -IPSec encrypts traffic at the IP payload level, before it hits the NIC, protecting fields that would otherwise be used for NIC offloading. This means that some NIC acceleration features might not be usable when IPSec is enabled and will lead to decreased throughput and increased CPU usage. diff --git a/modules/jaeger-architecture.adoc b/modules/jaeger-architecture.adoc deleted file mode 100644 index 90fce248ff30..000000000000 --- a/modules/jaeger-architecture.adoc +++ /dev/null @@ -1,25 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: --service_mesh/v1x/ossm-architecture.adoc --service_mesh/v2x/ossm-architecture.adoc --rhbjaeger-architecture.adoc -//// - -[id="jaeger-architecture_{context}"] -= Jaeger architecture - -Jaeger is made up of several components that work together to collect, store, and display tracing data. - -* *Jaeger Client* (Tracer, Reporter, instrumented application, client libraries)- Jaeger clients are language specific implementations of the OpenTracing API. They can be used to instrument applications for distributed tracing either manually or with a variety of existing open source frameworks, such as Camel (Fuse), Spring Boot (RHOAR), MicroProfile (RHOAR/Thorntail), Wildfly (EAP), and many more, that are already integrated with OpenTracing. - -* *Jaeger Agent* (Server Queue, Processor Workers) - The Jaeger agent is a network daemon that listens for spans sent over User Datagram Protocol (UDP), which it batches and sends to the collector. The agent is meant to be placed on the same host as the instrumented application. This is typically accomplished by having a sidecar in container environments like Kubernetes. - -* *Jaeger Collector* (Queue, Workers) - Similar to the Agent, the Collector is able to receive spans and place them in an internal queue for processing. This allows the collector to return immediately to the client/agent instead of waiting for the span to make its way to the storage. - -* *Storage* (Data Store) - Collectors require a persistent storage backend. Jaeger has a pluggable mechanism for span storage. Note that for this release, the only supported storage is Elasticsearch. - -* *Query* (Query Service) - Query is a service that retrieves traces from storage. - -* *Ingester* (Ingester Service) - Jaeger can use Apache Kafka as a buffer between the collector and the actual backing storage (Elasticsearch). Ingester is a service that reads data from Kafka and writes to another storage backend (Elasticsearch). - -* *Jaeger Console* – Jaeger provides a user interface that lets you visualize your distributed tracing data. On the Search page, you can find traces and explore details of the spans that make up an individual trace. diff --git a/modules/jaeger-config-collector.adoc b/modules/jaeger-config-collector.adoc deleted file mode 100644 index bb043409da3b..000000000000 --- a/modules/jaeger-config-collector.adoc +++ /dev/null @@ -1,64 +0,0 @@ -//// -This REFERENCE module included in the following assemblies: --rhbjaeger-deploy.adoc -//// - -[id="jaeger-config-collector_{context}"] -= Jaeger Collector configuration options - -The Jaeger Collector is the component responsible for receiving the spans that were captured by the tracer and writing them to a persistent storage (Elasticsearch) when using the `production` strategy, or to AMQ Streams when using the `streaming` strategy. - -The collectors are stateless and thus many instances of Jaeger Collector can be run in parallel. Collectors require almost no configuration, except for the location of the Elasticsearch cluster. - -.Jaeger Collector parameters used by the Operator -[options="header"] -[cols="l, a, a"] -|=== -|Parameter |Description |Values -|collector: - num-workers: -|The number of workers pulling from the queue. -|Integer, for example, `50` - -|collector: - queue-size: -|The size of the Collector queue. -|Integer, for example, `2000` - -|collector: - replicas: -|Specifies the number of Collector replicas to create. -|Integer, for example, `5` -|=== - - -.Jaeger parameters passed to the Collector -[options="header"] -[cols="l, a, a"] -|=== -|Parameter |Description |Values -|spec: - collector: - options: {} -|Configuration options that define the Jaeger Collector. -| - -|options: - kafka: - producer: - topic: jaeger-spans -|The `topic` parameter identifies the Kafka configuration used by the collector to produce the messages, and the ingester to consume the messages. -|Label for the producer - -|options: - kafka: - producer: - brokers: my-cluster-kafka-brokers.kafka:9092 -|Identifies the Kafka configuration used by the Collector to produce the messages. If brokers are not specified, and you have AMQ Streams 1.4.0+ installed, Jaeger will self-provision Kafka. -| - -|options: - log-level: -|Logging level for the collector. -|`trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic` -|=== diff --git a/modules/jaeger-config-default.adoc b/modules/jaeger-config-default.adoc deleted file mode 100644 index 8387100c6fb4..000000000000 --- a/modules/jaeger-config-default.adoc +++ /dev/null @@ -1,126 +0,0 @@ -//// -This REFERENCE module included in the following assemblies: -- rhbjaeger-deploying.adoc -//// - -[id="jaeger-config-default_{context}"] -= Jaeger default configuration options -:pantheon-module-type: REFERENCE - -The Jaeger custom resource (CR) defines the architecture and settings to be used when creating the Jaeger resources. You can modify these parameters to customize your Jaeger implementation to your business needs. - -.Jaeger generic YAML example -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: name -spec: - strategy: <deployment_strategy> - allInOne: - options: {} - resources: {} - agent: - options: {} - resources: {} - collector: - options: {} - resources: {} - sampling: - options: {} - storage: - type: - options: {} - query: - options: {} - resources: {} - ingester: - options: {} - resources: {} - options: {} ----- - -.Jaeger parameters -[options="header"] -|=== -|Parameter |Description |Values |Default value - -|`apiVersion:` -|Version of the Application Program Interface to use when creating the object. -|`jaegertracing.io/v1` -|`jaegertracing.io/v1` - -|`kind:` -|Defines the kind of Kubernetes object to create. -|`jaeger` -| - -|`metadata:` -|Data that helps uniquely identify the object, including a `name` string, `UID`, and optional `namespace`. -| -|OpenShift automatically generates the `UID` and completes the `namespace` with the name of the project where the object is created. - -|`name:` -|Name for the object. -|The name of your Jaeger instance. -|`jaeger-all-in-one-inmemory` - -|`spec:` -|Specification for the object to be created. -|Contains all of the configuration parameters for your Jaeger instance. When a common definition (for all Jaeger components) is required, it is defined under the spec node. When the definition relates to an individual component, it is placed under the spec/<component> node. -|N/A - -|`strategy:` -|Jaeger deployment strategy -|`allInOne`, `production`, or `streaming` -|`allInOne` - -|`allInOne:` -|Because the allInOne image deploys the agent, collector, query, ingester, Jaeger UI in a single pod, configuration for this deployment should nest component configuration under the allInOne parameter. -| -| - -|`agent:` -|Configuration options that define the Jaeger agent. -| -| - -|`collector:` -|Configuration options that define the Jaeger Collector. -| -| - -|`sampling:` -|Configuration options that define the sampling strategies for tracing. -| -| - -|`storage:` -|Configuration options that define the storage. All storage related options should be placed under `storage`, rather than under the `allInOne` or other component options. -| -| - -|`query:` -|Configuration options that define the Query service. -| -| - -|`ingester:` -|Configuration options that define the Ingester service. -| -| - -|=== - - -The following example YAML is the minimum required to create a Jaeger instance using the default settings. - -.Example minimum required jaeger-all-in-one.yaml -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: jaeger-all-in-one-inmemory ----- diff --git a/modules/jaeger-config-ingester.adoc b/modules/jaeger-config-ingester.adoc deleted file mode 100644 index 6b78486240c8..000000000000 --- a/modules/jaeger-config-ingester.adoc +++ /dev/null @@ -1,84 +0,0 @@ -//// -This REFERENCE module included in the following assemblies: --rhbjaeger-deploy.adoc -//// - -[id="jaeger-config-ingester_{context}"] -= Jaeger Ingester configuration options - -Ingester is a service that reads from a Kafka topic and writes to another storage backend (Elasticsearch). If you are using the `allInOne` or `production` deployment strategies, you do not need to configure the Ingester service. - -.Jaeger Ingester parameters used by the Operator -[options="header"] -[cols="l, a, a"] -|=== -|Parameter |Description |Values -|ingester: - deadlockInterval: -| Specifies the interval (in seconds or minutes) that the Ingester should wait for a message before terminating. -The deadlock interval is disabled by default (set to 0), to avoid the Ingester being terminated when no messages arrive while the system is being initialized. -|Minutes and seconds, for example, `1m0s`. Default value is `0`. -|=== - - -.Jaeger parameters passed to the Ingester -[options="header"] -[cols="l, a, a"] -|=== -|Parameter |Description |Values -|spec: - strategy: streaming - ingester: - options: {} -|Configuration options that define the Ingester service. -| - -|options: - kafka: - consumer: - topic: -|The `topic` parameter identifies the Kafka configuration used by the collector to produce the messages, and the ingester to consume the messages. -|Label for the consumer. For example, `jaeger-spans`. - -|options: - kafka: - consumer: - brokers: -|Identifies the Kafka configuration used by the Ingester to consume the messages. -|Label for the broker, for example, `my-cluster-kafka-brokers.kafka:9092`. - -|options: - log-level: -|Logging level for the Ingester. -|Possible values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`. -|=== - -.Streaming Collector and Ingester example -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: simple-streaming -spec: - strategy: streaming - collector: - options: - kafka: - producer: - topic: jaeger-spans - brokers: my-cluster-kafka-brokers.kafka:9092 - ingester: - options: - kafka: - consumer: - topic: jaeger-spans - brokers: my-cluster-kafka-brokers.kafka:9092 - ingester: - deadlockInterval: 5 - storage: - type: elasticsearch - options: - es: - server-urls: http://elasticsearch:9200 ----- diff --git a/modules/jaeger-config-query.adoc b/modules/jaeger-config-query.adoc deleted file mode 100644 index d6cfa8596274..000000000000 --- a/modules/jaeger-config-query.adoc +++ /dev/null @@ -1,65 +0,0 @@ -//// -This REFERENCE module included in the following assemblies: --rhbjaeger-deploy.adoc -//// - -[id="jaeger-config-query_{context}"] -= Jaeger Query configuration options - -Query is a service that retrieves traces from storage and hosts the user interface to display them. - -.Jaeger Query parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value - -|spec: - query: - options: {} - resources: {} -|Configuration options that define the Query service. -| -| - -|query: - additional-headers: -|Additional HTTP response headers. Can be specified multiple times. -|Format: "Key: Value" -| - -|query: - base-path: -|The base path for all jaeger-query HTTP routes can be set to a non-root value, for example, `/jaeger` would cause all UI URLs to start with `/jaeger`. This can be useful when running jaeger-query behind a reverse proxy. -|/{path} -| - -|query: - port: -|The port for the query service. -| -|16686 - -|options: - log-level: -|Logging level for Query. -|Possible values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`. -| -|=== - -.Sample Query configuration -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: "Jaeger" -metadata: - name: "my-jaeger" -spec: - strategy: allInOne - allInOne: - options: - log-level: debug - query: - base-path: /jaeger - ----- diff --git a/modules/jaeger-config-sampling.adoc b/modules/jaeger-config-sampling.adoc deleted file mode 100644 index 4bc10a8adb4e..000000000000 --- a/modules/jaeger-config-sampling.adoc +++ /dev/null @@ -1,75 +0,0 @@ -//// -This REFERENCE module included in the following assemblies: --rhbjaeger-deploy.adoc -//// - -[id="jaeger-config-sampling_{context}"] -= Jaeger sampling configuration options - -The Operator can be used to define sampling strategies that will be supplied to tracers that have been configured to use a remote sampler. - -While all traces are generated, only a few are sampled. Sampling a trace marks the trace for further processing and storage. - -[NOTE] -==== -This is not relevant if a trace was started by the Istio proxy as the sampling decision is made there. The Jaeger sampling decision is only relevant when the trace is started by an application using the Jaeger tracer. -==== - -When a service receives a request that contains no trace context, the Jaeger tracer will start a new trace, assign it a random trace ID, and make a sampling decision based on the currently installed sampling strategy. The sampling decision is propagated to all subsequent requests in the trace, so that other services are not making the sampling decision again. - -Jaeger libraries support the following samplers: - -* *Constant* - The sampler always makes the same decision for all traces. It either samples all traces (sampling.param=1) or none of them (sampling.param=0). - -* *Probabilistic* - The sampler makes a random sampling decision with the probability of sampling equal to the value of the `sampling.param` property. For example, with sampling.param=0.1 approximately 1 in 10 traces will be sampled. - -* *Rate Limiting* - The sampler uses a leaky bucket rate limiter to ensure that traces are sampled with a certain constant rate. For example, when sampling.param=2.0 it will sample requests with the rate of 2 traces per second. - -* *Remote* - The sampler consults the Jaeger agent for the appropriate sampling strategy to use in the current service. This allows controlling the sampling strategies in the services from a central configuration in the Jaeger backend. - -.Jaeger sampling parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value - -|spec: - sampling: - options: {} -|Configuration options that define the sampling strategies for tracing. -| -| - -|sampling: - type: -|Sampling strategy to use. (See descriptions above.) -|Valid values are `const`, `probabilistic`, `ratelimiting`, and `remote`. -|`remote` - -|sampling: - options: - type: - param: -|Parameters for the selected sampling strategy. (See examples above.) -|Decimal and integer values (0, .1, 1, 10) -|N/A -|=== - -This example defines a default sampling strategy that is probabilistic, with a 50% chance of the trace instances being sampled. - -.Probabilistic sampling example -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: with-sampling -spec: - strategy: allInOne - sampling: - options: - default_strategy: - type: probabilistic - param: 50 - ----- diff --git a/modules/jaeger-config-storage.adoc b/modules/jaeger-config-storage.adoc deleted file mode 100644 index e9153459ac3a..000000000000 --- a/modules/jaeger-config-storage.adoc +++ /dev/null @@ -1,617 +0,0 @@ -//// -This REFERENCE module included in the following assemblies: --rhbjaeger-deploy.adoc -//// - -[id="jaeger-config-storage_{context}"] -= Jaeger storage configuration options - -You configure storage for the Collector, Ingester, and Query services under `spec:storage`. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes. - -.Jaeger general storage parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|spec: - storage: - options: {} -|Configuration options that define the storage. -| -| - -|storage: - type: -|Type of storage to use for the deployment. -|`memory` or `elasticsearch`. -Memory storage is only appropriate for development, testing, demonstrations, and proof of concept environments as the data does not persist if the pod is shut down. For production environments Jaeger supports Elasticsearch for persistent storage. -|`memory` - -|storage: - secretname: -|Name of the secret, for example `jaeger-secret`. -| -|N/A -|=== - -.Elasticsearch index cleaner parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|storage: - esIndexCleaner: - enabled: -|When using Elasticsearch storage, by default a job is created to clean old traces from the index. This parameter enables or disables the index cleaner job. -|`true`/ `false` -|`true` - -|storage: - esIndexCleaner: - numberOfDays: -|Number of days to wait before deleting an index. -|Integer value -|`7` - -|storage: - esIndexCleaner: - schedule: -|Defines the schedule for how often to clean the Elasticsearch index. -|Cron expression -|"55 23 * * *" -|=== - -[id="jaeger-config-auto-provisioning-es_{context}"] -== Auto-provisioning an Elasticsearch instance - -When the `storage:type` is set to `elasticsearch` but there is no value set for `spec:storage:options:es:server-urls`, the Jaeger Operator uses the OpenShift Elasticsearch Operator to create an Elasticsearch cluster based on the configuration provided in the `storage` section of the custom resource file. - -.Restrictions - -* There can be only one Elasticsearch per namespace. -* You cannot share or reuse a {ProductName} logging Elasticsearch instance with Jaeger. The Elasticsearch cluster is meant to be dedicated for a single Jaeger instance. - -[NOTE] -==== -If you already have installed Elasticsearch as part of OpenShift logging, the Jaeger Operator can use the installed OpenShift Elasticsearch Operator to provision storage. -==== - -The following configuration parameters are for a _self-provisioned_ Elasticsearch instance, that is an instance created by the Jaeger Operator using the OpenShift Elasticsearch Operator. You specify configuration options for self-provisioned Elasticsearch under `spec:storage:elasticsearch` in your configuration file. - -.Elasticsearch resource configuration parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|elasticsearch: - nodeCount: -|Number of Elasticsearch nodes. For high availability use at least 3 nodes. Do not use 2 nodes as “split brain” problem can happen. -|Integer value. For example, Proof of concept = 1, -Minimum deployment =3 -|1 - -|elasticsearch: - resources: - requests: - cpu: -|Number of central processing units for requests, based on your environment’s configuration. -|Specified in cores or millicores (for example, 200m, 0.5, 1). For example, Proof of concept = 500m, -Minimum deployment =1 -|1Gi - -|elasticsearch: - resources: - requests: - memory: -|Available memory for requests, based on your environment’s configuration. -|Specified in bytes (for example, 200Ki, 50Mi, 5Gi). For example, Proof of concept = 1Gi, -Minimum deployment = 16Gi* -|500m - -|elasticsearch: - resources: - limits: - cpu: -|Limit on number of central processing units, based on your environment’s configuration. -|Specified in cores or millicores (for example, 200m, 0.5, 1). For example, Proof of concept = 500m, -Minimum deployment =1 -| - -|elasticsearch: - resources: - limits: - memory: -|Available memory limit based on your environment’s configuration. -|Specified in bytes (for example, 200Ki, 50Mi, 5Gi). For example, Proof of concept = 1Gi, -Minimum deployment = 16Gi* -| - -|elasticsearch: - redundancyPolicy: -|Data replication policy defines how Elasticsearch shards are replicated across data nodes in the cluster. If not specified,the Jaeger Operator automatically determines the most appropriate replication based on number of nodes. -|`ZeroRedundancy`(no replica shards), `SingleRedundancy`(one replica shard), `MultipleRedundancy`(each index is spread over half of the Data nodes), `FullRedundancy` (each index is fully replicated on every Data node in the cluster). -| - -| -3+|*Each Elasticsearch node can operate with a lower memory setting though this is NOT recommended for production deployments. For production use, you should have no less than 16Gi allocated to each Pod by default, but preferably allocate as much as you can, up to 64Gi per Pod. -|=== - -.Production storage example -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: simple-prod -spec: - strategy: production - storage: - type: elasticsearch - elasticsearch: - nodeCount: 3 - resources: - requests: - cpu: 1 - memory: 16Gi - limits: - memory: 16Gi ----- - -.Storage example with persistent storage: -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: simple-prod -spec: - strategy: production - storage: - type: elasticsearch - elasticsearch: - nodeCount: 1 - storage: # <1> - storageClassName: gp2 - size: 5Gi - resources: - requests: - cpu: 200m - memory: 4Gi - limits: - memory: 4Gi - redundancyPolicy: ZeroRedundancy ----- - -<1> Persistent storage configuration. In this case AWS `gp2` with `5Gi` size. When no value is specified, Jaeger uses `emptyDir`. The OpenShift Elasticsearch Operator provisions `PersistentVolumeClaim` and `PersistentVolume` which are not removed with Jaeger instance. You can mount the same volumes if you create a Jaeger instance with the same name and namespace. - - -[id="jaeger-config-external-es_{context}"] -== Connecting to an existing Elasticsearch instance - -Jaeger also allows you to use an existing (self-provisioned) Elasticsearch cluster for storage. You do this by specifying the URL of the existing cluster as the `spec:storage:options:es:server-urls` value in your configuration. - -.Restrictions - -* There can be only one Jaeger with self-provisioned Elasticsearch instance per namespace. - -[NOTE] -==== -Red Hat does not provide support for your external Elasticsearch instance. You can review the tested integrations matrix on the link:https://access.redhat.com/articles/5381021[Customer Portal]. -==== - -The following configuration parameters are for an _external_ Elasticsearch instance, that is, an instance that was not created using the OpenShift Elasticsearch Operator. You specify configuration options for external Elasticsearch under `spec:storage:options:es` in your configuration file. - -.General ES configuration parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|es: - server-urls: -|URL of the Elasticsearch instance. -|The fully-qualified domain name of the Elasticsearch server. -|`http://elasticsearch.<namespace>.svc:9200` - -|es: - max-doc-count: -|The maximum document count to return from an Elasticsearch query. This will also apply to aggregations. If you set both `es.max-doc-count` and `es.max-num-spans`, Elasticsearch will use the smaller value of the two. -| -|10000 - -|es: - max-num-spans: -|[*Deprecated* - Will be removed in a future release, use `es.max-doc-count` instead.] The maximum number of spans to fetch at a time, per query, in Elasticsearch. If you set both `es.max-num-spans` and `es.max-doc-count`, Elasticsearch will use the smaller value of the two. -| -|10000 - -|es: - max-span-age: -|The maximum lookback for spans in Elasticsearch. -| -|72h0m0s - -|es: - sniffer: -|The sniffer configuration for Elasticsearch. The client uses the sniffing process to find all nodes automatically. Disabled by default. -|`true`/ `false` -|`false` - -|es: - sniffer-tls-enabled: -|Option to enable TLS when sniffing an Elasticsearch Cluster, The client uses the sniffing process to find all nodes automatically. Disabled by default -|`true`/ `false` -|`false` - -|es: - timeout: -|Timeout used for queries. When set to zero there is no timeout. -| -|0s - -|es: - username: -|The username required by Elasticsearch. The basic authentication also loads CA if it is specified. See also `es.password`. -| -| - -|es: - password: -|The password required by Elasticsearch. See also, `es.username`. -| -| - -|es: - version: -|The major Elasticsearch version. If not specified, the value will be auto-detected from Elasticsearch. -| -|0 -|=== - -.ES data replication parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|es: - num-replicas: -|The number of replicas per index in Elasticsearch. -| -|1 - -|es: - num-shards: -|The number of shards per index in Elasticsearch. -| -|5 -|=== - -.ES index configuration parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|es: - create-index-templates: -|Automatically create index templates at application startup when set to `true`. When templates are installed manually, set to `false`. -|`true`/ `false` -|`true` - -|es: - index-prefix: -|Optional prefix for Jaeger indices. For example, setting this to "production" creates indices named "production-jaeger-*". -| -| -|=== - -.ES bulk processor configuration parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|es: - bulk: - actions: -|The number of requests that can be added to the queue before the bulk processor decides to commit updates to disk. -| -|1000 - -//What is the default here? The original text said "Set to zero to disable. By default, this is disabled." -|es: - bulk: - flush-interval: -|A `time.Duration` after which bulk requests are committed, regardless of other thresholds. To disable the bulk processor flush interval, set this to zero. -| -|200ms - -|es: - bulk: - size: -|The number of bytes that the bulk requests can take up before the bulk processor decides to commit updates to disk. -| -|5000000 - -|es: - bulk: - workers: -|The number of workers that are able to receive and commit bulk requests to Elasticsearch. -| -|1 -|=== - -.ES TLS configuration parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|es: - tls: - ca: -|Path to a TLS Certification Authority (CA) file used to verify the remote server(s). -| -|Will use the system truststore by default. - -|es: - tls: - cert: -|Path to a TLS Certificate file, used to identify this process to the remote server(s). -| -| - -|es: - tls: - enabled: -|Enable transport layer security (TLS) when talking to the remote server(s). Disabled by default. -|`true`/ `false` -|`false` - -|es: - tls: - key: -|Path to a TLS Private Key file, used to identify this process to the remote server(s). -| -| - -|es: - tls: - server-name: -|Override the expected TLS server name in the certificate of the remote server(s). -| -| -//Clarification of "if specified" for `token-file` and `username`, does that mean if this is set? Or that it only loads the CA if one is specified (that is, if es.tls.ca has a value?) -|es: - token-file: -|Path to a file containing the bearer token. This flag also loads the Certification Authority (CA) file if it is specified. -| -| -|=== - -.ES archive configuration parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value -|es-archive: - bulk: - actions: -|The number of requests that can be added to the queue before the bulk processor decides to commit updates to disk. -| -|0 - -//What is the default here? The original text said "Set to zero to disable. By default, this is disabled." -|es-archive: - bulk: - flush-interval: -|A `time.Duration` after which bulk requests are committed, regardless of other thresholds. To disable the bulk processor flush interval, set this to zero. -| -|0s - -|es-archive: - bulk: - size: -|The number of bytes that the bulk requests can take up before the bulk processor decides to commit updates to disk. -| -|0 - -|es-archive: - bulk: - workers: -|The number of workers that are able to receive and commit bulk requests to Elasticsearch. -| -|0 - -|es-archive: - create-index-templates: -|Automatically create index templates at application startup when set to `true`. When templates are installed manually, set to `false`. -|`true`/ `false` -|`false` - -|es-archive: - enabled: -|Enable extra storage. -|`true`/ `false` -|`false` - -|es-archive: - index-prefix: -|Optional prefix for Jaeger indices. For example, setting this to "production" creates indices named "production-jaeger-*". -| -| - -|es-archive: - max-doc-count: -|The maximum document count to return from an Elasticsearch query. This will also apply to aggregations. -| -|0 - -|es-archive: - max-num-spans: -|[*Deprecated* - Will be removed in a future release, use `es-archive.max-doc-count` instead.] The maximum number of spans to fetch at a time, per query, in Elasticsearch. -| -|0 - -|es-archive: - max-span-age: -|The maximum lookback for spans in Elasticsearch. -| -|0s - -|es-archive: - num-replicas: -|The number of replicas per index in Elasticsearch. -| -|0 - -|es-archive: - num-shards: -|The number of shards per index in Elasticsearch. -| -|0 - -|es-archive: - password: -|The password required by Elasticsearch. See also, `es.username`. -| -| - -|es-archive: - server-urls: -|The comma-separated list of Elasticsearch servers. Must be specified as fully qualified URLs, for example, `\http://localhost:9200`. -| -| - -|es-archive: - sniffer: -|The sniffer configuration for Elasticsearch. The client uses the sniffing process to find all nodes automatically. Disabled by default. -|`true`/ `false` -|`false` - -|es-archive: - sniffer-tls-enabled: -|Option to enable TLS when sniffing an Elasticsearch Cluster, The client uses the sniffing process to find all nodes automatically. Disabled by default. -|`true`/ `false` -|`false` - -|es-archive: - timeout: -|Timeout used for queries. When set to zero there is no timeout. -| -|0s - -|es-archive: - tls: - ca: -|Path to a TLS Certification Authority (CA) file used to verify the remote server(s). -| -|Will use the system truststore by default. - -|es-archive: - tls: - cert: -|Path to a TLS Certificate file, used to identify this process to the remote server(s). -| -| - -|es-archive: - tls: - enabled: -|Enable transport layer security (TLS) when talking to the remote server(s). Disabled by default. -|`true`/ `false` -|`false` - -|es-archive: - tls: - key: -|Path to a TLS Private Key file, used to identify this process to the remote server(s). -| -| - -|es-archive: - tls: - server-name: -|Override the expected TLS server name in the certificate of the remote server(s). -| -| - -//Clarification of "if specified" for next two rows, does that mean if this is set? Or that it only loads the CA if one is specified (that is, if es-archive.tls.ca has a value?) -|es-archive: - token-file: -|Path to a file containing the bearer token. This flag also loads the Certification Authority (CA) file if it is specified. -| -| - -|es-archive: - username: -|The username required by Elasticsearch. The basic authentication also loads CA if it is specified. See also `es-archive.password`. -| -| - -|es-archive: - version: -|The major Elasticsearch version. If not specified, the value will be auto-detected from Elasticsearch. -| -|0 -|=== - - -.Storage example with volume mounts -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: simple-prod -spec: - strategy: production - storage: - type: elasticsearch - options: - es: - server-urls: https://quickstart-es-http.default.svc:9200 - index-prefix: my-prefix - tls: - ca: /es/certificates/ca.crt - secretName: jaeger-secret - volumeMounts: - - name: certificates - mountPath: /es/certificates/ - readOnly: true - volumes: - - name: certificates - secret: - secretName: quickstart-es-http-certs-public ----- - -The following example shows a Jaeger CR using an external Elasticsearch cluster with TLS CA certificate mounted from a volume and user/password stored in a secret. - -.External Elasticsearch example: -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: simple-prod -spec: - strategy: production - storage: - type: elasticsearch - options: - es: - server-urls: https://quickstart-es-http.default.svc:9200 # <1> - index-prefix: my-prefix - tls: # <2> - ca: /es/certificates/ca.crt - secretName: jaeger-secret # <3> - volumeMounts: # <4> - - name: certificates - mountPath: /es/certificates/ - readOnly: true - volumes: - - name: certificates - secret: - secretName: quickstart-es-http-certs-public - ----- -<1> URL to Elasticsearch service running in default namespace. -<2> TLS configuration. In this case only CA certificate, but it can also contain es.tls.key and es.tls.cert when using mutual TLS. -<3> Secret which defines environment variables ES_PASSWORD and ES_USERNAME. Created by kubectl create secret generic jaeger-secret --from-literal=ES_PASSWORD=changeme --from-literal=ES_USERNAME=elastic -<4> Volume mounts and volumes which are mounted into all storage components. diff --git a/modules/jaeger-deploy-default.adoc b/modules/jaeger-deploy-default.adoc deleted file mode 100644 index efb4d4519a3b..000000000000 --- a/modules/jaeger-deploy-default.adoc +++ /dev/null @@ -1,115 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- rhbjaeger-deploying.adoc -//// - -[id="jaeger-deploy-default_{context}"] -= Deploying the default Jaeger strategy from the web console - -The custom resource definition (CRD) defines the configuration used when you deploy an instance of Jaeger. The default CR for Jaeger is named `jaeger-all-in-one-inmemory` and it is configured with minimal resources to ensure that you can successfully install it on a default {product-title} installation. You can use this default configuration to create a Jaeger instance that uses the `AllInOne` deployment strategy, or you can define your own custom resource file. - -[NOTE] -==== -In-memory storage is not persistent, which means that if the Jaeger pod shuts down, restarts, or is replaced, that your trace data will be lost. For persistent storage, you must use the `production` or `streaming` strategies, which use Elasticsearch as the default storage. -==== - - -.Prerequisites - -* The Jaeger Operator must be installed. -* Review the instructions for how to customize the Jaeger installation. -* An account with the `cluster-admin` role. - -[NOTE] -==== -Jaeger streaming is currently unsupported on IBM Z. -==== - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Create a new project, for example `jaeger-system`. - -.. Navigate to *Home* -> *Projects*. - -.. Click *Create Project*. - -.. Enter `jaeger-system` in the *Name* field. - -.. Click *Create*. - -. Navigate to *Operators* -> *Installed Operators*. - -. If necessary, select `jaeger-system` from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project. - -. Click the {ProductName} Operator. On the *Overview* tab, under *Provided APIs*, the Operator provides a single link. - -. Under *Jaeger* click *Create Instance*. - -. On the *Create Jaeger* page, to install using the defaults, click *Create* to create the Jaeger instance. - -. On the *Jaegers* page, click the name of the Jaeger instance, for example, `jaeger-all-in-one-inmemory`. - -. On the *Jaeger Details* page, click the *Resources* tab. Wait until the Pod has a status of "Running" before continuing. - - -[id="jaeger-create-cli_{context}"] -== Deploying default Jaeger from the CLI - -Follow this procedure to create an instance of Jaeger from the command line. - -.Prerequisites - -* An installed, verified {ProductName} Operator. -* Access to the OpenShift CLI (`oc`) that matches your {product-title} version. -* An account with the `cluster-admin` role. - -.Procedure - -. Log in to the {product-title} CLI as a user with the `cluster-admin` role. -+ -[source,terminal] ----- -$ oc login https://{HOSTNAME}:8443 ----- - -. Create a new project named `jaeger-system`. -+ -[source,terminal] ----- -$ oc new-project jaeger-system ----- - -. Create a custom resource file named `jaeger.yaml` that contains the following text: -+ -.Example jaeger-all-in-one.yaml -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: jaeger-all-in-one-inmemory ----- - -. Run the following command to deploy Jaeger: -+ -[source,terminal] ----- -$ oc create -n jaeger-system -f jaeger.yaml ----- - -. Run the following command to watch the progress of the pods during the installation process: -+ -[source,terminal] ----- -$ oc get pods -n jaeger-system -w ----- -+ -Once the installation process has completed, you should see output similar to the following: -+ -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -jaeger-all-in-one-inmemory-cdff7897b-qhfdx 2/2 Running 0 24s ----- diff --git a/modules/jaeger-deploy-production-es.adoc b/modules/jaeger-deploy-production-es.adoc deleted file mode 100644 index fac07aa070ae..000000000000 --- a/modules/jaeger-deploy-production-es.adoc +++ /dev/null @@ -1,129 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- rhbjaeger-deploying.adoc -//// - -[id="jaeger-deploy-production_{context}"] -= Deploying the Jaeger production strategy from the web console - -The `production` deployment strategy is intended for production environments, where long term storage of trace data is important, as well as a more scalable and highly available architecture is required. - -.Prerequisites - -* The OpenShift Elasticsearch Operator must be installed. -* The Jaeger Operator must be installed. -* Review the instructions for how to customize the Jaeger installation. -* An account with the `cluster-admin` role. - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Create a new project, for example `jaeger-system`. - -.. Navigate to *Home* -> *Projects*. - -.. Click *Create Project*. - -.. Enter `jaeger-system` in the *Name* field. - -.. Click *Create*. - -. Navigate to *Operators* -> *Installed Operators*. - -. If necessary, select `jaeger-system` from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project. - -. Click the Jaeger Operator. On the *Overview* tab, under *Provided APIs*, the Operator provides a single link. - -. Under *Jaeger* click *Create Instance*. - -. On the *Create Jaeger* page, replace the default `all-in-one` yaml text with your production YAML configuration, for example: - -+ -.Example jaeger-production.yaml file with Elasticsearch -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: jaeger-production - namespace: -spec: - strategy: production - ingress: - security: oauth-proxy - storage: - type: elasticsearch - elasticsearch: - nodeCount: 3 - redundancyPolicy: SingleRedundancy - esIndexCleaner: - enabled: true - numberOfDays: 7 - schedule: 55 23 * * * - esRollover: - schedule: '*/30 * * * *' ----- -+ - -. Click *Create* to create the Jaeger instance. - -. On the *Jaegers* page, click the name of the Jaeger instance, for example, `jaeger-prod-elasticsearch`. - -. On the *Jaeger Details* page, click the *Resources* tab. Wait until all the pods have a status of "Running" before continuing. - - -[id="jaeger-deploy-production-cli_{context}"] -== Deploying Jaeger production from the CLI - -Follow this procedure to create an instance of Jaeger from the command line. - -.Prerequisites - -* An installed, verified {ProductName} Operator. -* Access to the OpenShift CLI (`oc`). -* An account with the `cluster-admin` role. - -.Procedure - -. Log in to the {product-title} CLI as a user with the `cluster-admin` role. -+ -[source,terminal] ----- -$ oc login https://{HOSTNAME}:8443 ----- - -. Create a new project named `jaeger-system`. -+ -[source,terminal] ----- -$ oc new-project jaeger-system ----- - -. Create a custom resource file named `jaeger-production.yaml` that contains the text of the example file in the previous procedure. - -. Run the following command to deploy Jaeger: -+ -[source,terminal] ----- -$ oc create -n jaeger-system -f jaeger-production.yaml ----- -+ -. Run the following command to watch the progress of the pods during the installation process: -+ -[source,terminal] ----- -$ oc get pods -n jaeger-system -w ----- -+ -Once the installation process has completed, you should see output similar to the following: -+ -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -elasticsearch-cdm-jaegersystemjaegerproduction-1-6676cf568gwhlw 2/2 Running 0 10m -elasticsearch-cdm-jaegersystemjaegerproduction-2-bcd4c8bf5l6g6w 2/2 Running 0 10m -elasticsearch-cdm-jaegersystemjaegerproduction-3-844d6d9694hhst 2/2 Running 0 10m -jaeger-production-collector-94cd847d-jwjlj 1/1 Running 3 8m32s -jaeger-production-query-5cbfbd499d-tv8zf 3/3 Running 3 8m32s ----- diff --git a/modules/jaeger-deploy-streaming.adoc b/modules/jaeger-deploy-streaming.adoc deleted file mode 100644 index 852284d73277..000000000000 --- a/modules/jaeger-deploy-streaming.adoc +++ /dev/null @@ -1,146 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- rhbjaeger-deploying.adoc -//// - -[id="jaeger-deploy-streaming_{context}"] -= Deploying the Jaeger streaming strategy from the web console - -The `streaming` deployment strategy is intended for production environments, where long term storage of trace data is important, as well as a more scalable and highly available architecture is required. - -The `streaming` strategy provides a streaming capability that sits between the collector and the storage (Elasticsearch). This reduces the pressure on the storage under high load situations, and enables other trace post-processing capabilities to tap into the real time span data directly from the streaming platform (Kafka). - -[NOTE] -==== -The streaming strategy requires an additional Red Hat subscription for AMQ Streams. If you do not have an AMQ Streams subscription, contact your sales representative for more information. -==== - -.Prerequisites -* The AMQ Streams Operator must be installed. If using version 1.4.0 or higher you can use self-provisioning. If otherwise, you need to create the Kafka instance. -* The Jaeger Operator must be installed. -* Review the instructions for how to customize the Jaeger installation. -* An account with the `cluster-admin` role. - -[NOTE] -==== -Jaeger streaming is currently unsupported on IBM Z. -==== - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Create a new project, for example `jaeger-system`. - -.. Navigate to *Home* -> *Projects*. - -.. Click *Create Project*. - -.. Enter `jaeger-system` in the *Name* field. - -.. Click *Create*. - -. Navigate to *Operators* -> *Installed Operators*. - -. If necessary, select `jaeger-system` from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project. - -. Click the Jaeger Operator. On the *Overview* tab, under *Provided APIs*, the Operator provides a single link. - -. Under *Jaeger* click *Create Instance*. - -. On the *Create Jaeger* page, replace the default `all-in-one` yaml text with your streaming YAML configuration, for example: - -.Example jaeger-streaming.yaml file -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: jaeger-streaming -spec: - strategy: streaming - collector: - options: - kafka: - producer: - topic: jaeger-spans - #Note: If brokers are not defined,AMQStreams 1.4.0+ will self-provision Kafka. - brokers: my-cluster-kafka-brokers.kafka:9092 - storage: - type: elasticsearch - ingester: - options: - kafka: - consumer: - topic: jaeger-spans - brokers: my-cluster-kafka-brokers.kafka:9092 - ----- -//TODO - find out if this storage configuration is correct for OpenShift - -. Click *Create* to create the Jaeger instance. - -. On the *Jaegers* page, click the name of the Jaeger instance, for example, `jaeger-streaming`. - -. On the *Jaeger Details* page, click the *Resources* tab. Wait until all the pods have a status of "Running" before continuing. - - -[id="jaeger-deploy-streaming-cli_{context}"] -== Deploying Jaeger streaming from the CLI - -Follow this procedure to create an instance of Jaeger from the command line. - -.Prerequisites - -* An installed, verified {ProductName} Operator. -* Access to the OpenShift CLI (`oc`). -* An account with the `cluster-admin` role. - -Procedure - -. Log in to the {product-title} CLI as a user with the `cluster-admin` role. -+ -[source,terminal] ----- -$ oc login https://{HOSTNAME}:8443 ----- - -. Create a new project named `jaeger-system`. -+ -[source,terminal] ----- -$ oc new-project jaeger-system ----- - -. Create a custom resource file named `jaeger-streaming.yaml` that contains the text of the example file in the previous procedure. - -. Run the following command to deploy Jaeger: -+ -[source,terminal] ----- -$ oc create -n jaeger-system -f jaeger-streaming.yaml ----- -+ -. Run the following command to watch the progress of the pods during the installation process: -+ -[source,terminal] ----- -$ oc get pods -n jaeger-system -w ----- -+ -Once the installation process has completed, you should see output similar to the following: -+ -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -elasticsearch-cdm-jaegersystemjaegerstreaming-1-697b66d6fcztcnn 2/2 Running 0 5m40s -elasticsearch-cdm-jaegersystemjaegerstreaming-2-5f4b95c78b9gckz 2/2 Running 0 5m37s -elasticsearch-cdm-jaegersystemjaegerstreaming-3-7b6d964576nnz97 2/2 Running 0 5m5s -jaeger-streaming-collector-6f6db7f99f-rtcfm 1/1 Running 0 80s -jaeger-streaming-entity-operator-6b6d67cc99-4lm9q 3/3 Running 2 2m18s -jaeger-streaming-ingester-7d479847f8-5h8kc 1/1 Running 0 80s -jaeger-streaming-kafka-0 2/2 Running 0 3m1s -jaeger-streaming-query-65bf5bb854-ncnc7 3/3 Running 0 80s -jaeger-streaming-zookeeper-0 2/2 Running 0 3m39s ----- - diff --git a/modules/jaeger-document-attributes.adoc b/modules/jaeger-document-attributes.adoc deleted file mode 100644 index cad28a40e7d5..000000000000 --- a/modules/jaeger-document-attributes.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Standard document attributes to be used in the Jaeger documentation -// -// The following are shared by all RH Build of Jaeger documents: -:toc: -:toclevels: 4 -:toc-title: -:experimental: -// -// Product content attributes, that is, substitution variables in the files. -// -:product-title: OpenShift Container Platform -:ProductName: OpenShift Jaeger -:ProductShortName: Jaeger -:ProductRelease: -:ProductVersion: 1.20.0 -:product-build: -:DownloadURL: registry.redhat.io -:cloud-redhat-com: Red Hat OpenShift Cluster Manager -:kebab: image:kebab.png[title="Options menu"] -// -// Documentation publishing attributes used in the master-docinfo.xml file -// Note that the DocInfoProductName generates the URL for the product page. -// Changing the value changes the generated URL. -// - -:DocInfoProductName: Red Hat OpenShift Jaeger -:DocInfoProductName: OpenShift Jaeger -:DocInfoProductNumber: 1.20.0 -// -// Book Names: -// Defining the book names in document attributes instead of hard-coding them in -// the master.adoc files and in link references. -//This makes it easy to change the book name if necessary. -// Using the pattern ending in 'BookName' makes it easy to grep for occurrences -// throughout the topics -// -:RN_BookName: Red Hat OpenShift Jaeger Release Notes -:Install_BookName: Installing Red Hat OpenShift Jaeger -:Using_BookName: Using Red Hat OpenShift Jaeger diff --git a/modules/jaeger-features.adoc b/modules/jaeger-features.adoc deleted file mode 100644 index 1102223a9466..000000000000 --- a/modules/jaeger-features.adoc +++ /dev/null @@ -1,19 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: --service_mesh/v1x/ossm-architecture.adoc --service_mesh/v2x/ossm-architecture.adoc --rhbjaeger-architecture.adoc -//// - -[id="jaeger-features_{context}"] -= Jaeger features - -Jaeger tracing provides the following capabilities: - -* Integration with Kiali – When properly configured, you can view Jaeger data from the Kiali console. - -* High scalability – The Jaeger backend is designed to have no single points of failure and to scale with the business needs. - -* Distributed Context Propagation – Lets you connect data from different components together to create a complete end-to-end trace. - -* Backwards compatibility with Zipkin – Jaeger has APIs that enable it to be used as a drop-in replacement for Zipkin, but Red Hat is not supporting Zipkin compatibility in this release. diff --git a/modules/jaeger-install-elasticsearch.adoc b/modules/jaeger-install-elasticsearch.adoc deleted file mode 100644 index b74f0dd95d3a..000000000000 --- a/modules/jaeger-install-elasticsearch.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// - service_mesh/v1x/installing-ossm.adoc -// - rhbjaeger-installation.adoc - - -[id="jaeger-operator-install-elasticsearch_{context}"] -= Installing the OpenShift Elasticsearch Operator - -The default Jaeger deployment uses in-memory storage because it is designed to be installed quickly for those evaluating Jaeger, giving demonstrations, or using Jaeger in a test environment. If you plan to use Jaeger in production, you must install and configure a persistent storage option, in this case, Elasticsearch. - -.Prerequisites -* Access to the {product-title} web console. -* An account with the `cluster-admin` role. - -[WARNING] -==== -Do not install Community versions of the Operators. Community Operators are not supported. -==== - -[NOTE] -==== -If you have already installed the OpenShift Elasticsearch Operator as part of OpenShift Logging, you do not need to install the OpenShift Elasticsearch Operator again. The Jaeger Operator will create the Elasticsearch instance using the installed OpenShift Elasticsearch Operator. -==== - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Navigate to *Operators* -> *OperatorHub*. - -. Type *Elasticsearch* into the filter box to locate the OpenShift Elasticsearch Operator. - -. Click the *OpenShift Elasticsearch Operator* provided by Red Hat to display information about the Operator. - -. Click *Install*. - -. On the *Install Operator* page, under *Installation Mode* select *All namespaces on the cluster (default)*. This makes the Operator available to all projects in the cluster. - -. Under *Installed Namespaces* select *openshift-operators-redhat* from the menu. -+ -[NOTE] -==== -The Elasticsearch installation requires the *openshift-operators-redhat* namespace for the OpenShift Elasticsearch Operator. The other {ProductName} operators are installed in the `openshift-operators` namespace. -==== -+ -. Select the *Update Channel* that matches your {product-title} installation. For example, if you are installing on {product-title} version 4.6, select the 4.6 update channel. -+ -[NOTE] -==== -For {product-title} version 4.7 select the 4.6 update channel. -==== -+ - -. Select the *Automatic* Approval Strategy. -+ -[NOTE] -==== -The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. -==== - -. Click *Install*. - -. On the *Installed Operators* page, select the `openshift-operators-redhat` project. Wait until you see that the OpenShift Elasticsearch Operator shows a status of "InstallSucceeded" before continuing. diff --git a/modules/jaeger-install-overview.adoc b/modules/jaeger-install-overview.adoc deleted file mode 100644 index 70d9a5a18c80..000000000000 --- a/modules/jaeger-install-overview.adoc +++ /dev/null @@ -1,19 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: -- rhbjaeger-installation.adoc -//// - -[id="jaeger-install-overview_{context}"] -= Jaeger installation overview - -The steps for installing {ProductName} are as follows: - -* Review the documentation and determine your deployment strategy. - -* If your deployment strategy requires persistent storage, install the OpenShift Elasticsearch Operator via the OperatorHub. - -* Install the Jaeger Operator via the OperatorHub. - -* Modify the Jaeger YAML file to support your deployment strategy. - -* Deploy one or more instances of Jaeger to your {product-title} environment. diff --git a/modules/jaeger-install.adoc b/modules/jaeger-install.adoc deleted file mode 100644 index f0e42057c701..000000000000 --- a/modules/jaeger-install.adoc +++ /dev/null @@ -1,50 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- service_mesh/v1x/installing-ossm.adoc -- rhbjaeger-installation.adoc -//// - -[id="jaeger-operator-install_{context}"] -= Installing the Jaeger Operator - -To install Jaeger you use the link:https://operatorhub.io/[OperatorHub] to install the Jaeger Operator. - -By default the Operator is installed in the `openshift-operators` project. - -.Prerequisites -* Access to the {product-title} web console. -* An account with the `cluster-admin` role. -* If you require persistent storage, you must also install the OpenShift Elasticsearch Operator before installing the Jaeger Operator. - -[WARNING] -==== -Do not install Community versions of the Operators. Community Operators are not supported. -==== - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Navigate to *Operators* -> *OperatorHub*. - -. Type *Jaeger* into the filter to locate the Jaeger Operator. - -. Click the *Jaeger Operator* provided by Red Hat to display information about the Operator. - -. Click *Install*. - -. On the *Install Operator* page, select the *stable* Update Channel. This will automatically update Jaeger as new versions are released. If you select a maintenance channel, for example, *1.17-stable*, you will receive bug fixes and security patches for the length of the support cycle for that version. - -. Select *All namespaces on the cluster (default)*. This installs the Operator in the default `openshift-operators` project and makes the Operator available to all projects in the cluster. - -* Select an Approval Strategy. You can select *Automatic* or *Manual* updates. If you choose Automatic updates for an installed Operator, when a new version of that Operator is available, the Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention. If you select Manual updates, when a newer version of an Operator is available, the OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version. -+ -[NOTE] -==== -The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. -==== -+ - -. Click *Install*. - -. On the *Subscription Overview* page, select the `openshift-operators` project. Wait until you see that the Jaeger Operator shows a status of "InstallSucceeded" before continuing. diff --git a/modules/jaeger-product-overview.adoc b/modules/jaeger-product-overview.adoc deleted file mode 100644 index 7c2a9bd750c5..000000000000 --- a/modules/jaeger-product-overview.adoc +++ /dev/null @@ -1,22 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: --service_mesh/v1x/ossm-architecture.adoc --service_mesh/v2x/ossm-architecture.adoc --rhbjaeger-architecture.adoc -//// - -[id="jaeger-product-overview_{context}"] -= Jaeger overview - -As a service owner, you can use Jaeger to instrument your services to gather insights into your service architecture. -Jaeger is an open source distributed tracing platform that you can use for monitoring, network profiling, and troubleshooting the interaction between components in modern, cloud-native, microservices-based applications. - -Using Jaeger lets you perform the following functions: - -* Monitor distributed transactions - -* Optimize performance and latency - -* Perform root cause analysis - -Jaeger is based on the vendor-neutral link:https://opentracing.io/[OpenTracing] APIs and instrumentation. diff --git a/modules/jaeger-removing-instance-cli.adoc b/modules/jaeger-removing-instance-cli.adoc deleted file mode 100644 index 66a6effea72d..000000000000 --- a/modules/jaeger-removing-instance-cli.adoc +++ /dev/null @@ -1,84 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- rhbjaeger-installation.adoc -//// - -[id="jaeger-removing-cli_{context}"] -= Removing a Jaeger instance from the CLI - - -. Log in to the {product-title} CLI. -+ -[source,terminal] ----- -$ oc login ----- -+ -. To display the Jaeger instances run the command: -+ -[source,terminal] ----- -$ oc get deployments -n <jaeger-project> ----- -+ -The names of operators have the suffix `-operator`. The following example shows two Jaeger Operators and four Jaeger instances: -+ -[source,terminal] ----- -$ oc get deployments -n jaeger-system ----- -+ -You should see output similar to the following: -+ -[source,terminal] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -elasticsearch-operator 1/1 1 1 93m -jaeger-operator 1/1 1 1 49m -jaeger-test 1/1 1 1 7m23s -jaeger-test2 1/1 1 1 6m48s -tracing1 1/1 1 1 7m8s -tracing2 1/1 1 1 35m ----- -+ -. To remove an instance of Jaeger, run the command: -+ -[source,terminal] ----- -$ oc delete jaeger <deployment-name> -n <jaeger-project> ----- -+ -For example, -+ -[source,terminal] ----- -$ oc delete jaeger tracing2 -n jaeger-system ----- -+ - -. To verify the deletion, run `oc get deployment` again: -+ -[source,terminal] ----- -$ oc get deployments -n <jaeger-project> ----- - -+ -For example, -+ -[source,terminal] ----- -$ oc get deployments -n jaeger-system ----- -+ -Should generate output similar to the following: -+ -[source,terminal] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -elasticsearch-operator 1/1 1 1 94m -jaeger-operator 1/1 1 1 50m -jaeger-test 1/1 1 1 8m14s -jaeger-test2 1/1 1 1 7m39s -tracing1 1/1 1 1 7m59s ----- diff --git a/modules/jaeger-removing-instance.adoc b/modules/jaeger-removing-instance.adoc deleted file mode 100644 index 6a320570638a..000000000000 --- a/modules/jaeger-removing-instance.adoc +++ /dev/null @@ -1,28 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- rhbjaeger-removing.adoc -//// - -[id="jaeger-removing_{context}"] -= Removing a Jaeger instance using the web console - -[NOTE] -==== -When deleting an instance that uses the in-memory storage, all data will be permanently lost. Data stored in a persistent storage (such as Elasticsearch) will not be deleted when a Jaeger instance is removed. -==== - -.Procedure - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *Installed Operators*. - -. Select the name of the project where the Operators are installed from the Project menu, for example, `jaeger-system`. - -. Click the Jaeger Operator. - -. Click the *Jaeger* tab. - -. Click the Options menu {kebab} next to the instance you want to delete and select *Delete Jaeger*. - -. In the confirmation message, click *Delete*. diff --git a/modules/jaeger-rn-fixed-issues.adoc b/modules/jaeger-rn-fixed-issues.adoc deleted file mode 100644 index ea8b21a609bc..000000000000 --- a/modules/jaeger-rn-fixed-issues.adoc +++ /dev/null @@ -1,26 +0,0 @@ -//// -Module included in the following assemblies: -* jaeger-release-notes.adoc -* service_mesh/v1x/servicemesh-release-notes.adoc -* service_mesh/v2x/servicemesh-release-notes.adoc -//// - -[id="jaeger-rn-fixed-issues_{context}"] -= Jaeger Fixed issues -//// -Provide the following info for each issue if possible: -Consequence - What user action or situation would make this problem appear (If you have the foo option enabled and did x)? What did the customer experience as a result of the issue? What was the symptom? -Cause - Why did this happen? -Fix - What did we change to fix the problem? -Result - How has the behavior changed as a result? Try to avoid “It is fixed” or “The issue is resolved” or “The error no longer presents”. -//// - -* link:https://issues.redhat.com/browse/TRACING-1725[TRACING-1725] Follow-up to TRACING-1631. Additional fix to ensure that Elasticsearch certificates are properly reconciled when there are multiple Jaeger production instances, using same name but within different namespaces. See also link:https://bugzilla.redhat.com/show_bug.cgi?id=1918920[BZ-1918920]. - -* link:https://issues.jboss.org/browse/TRACING-1631[TRACING-1631] Multiple Jaeger production instances, using same name but within different namespaces, causing Elasticsearch certificate issue. When multiple service meshes were installed, all of the Jaeger Elasticsearch instances had the same Elasticsearch secret instead of individual secrets, which prevented the OpenShift Elasticsearch Operator from communicating with all of the Elasticsearch clusters. - -* link:https://issues.redhat.com/browse/TRACING-1300[TRACING-1300] Failed connection between Agent and Collector when using Istio sidecar. An update of the Jaeger Operator enabled TLS communication by default between a Jaeger sidecar agent and the Jaeger Collector. - -* link:https://issues.redhat.com/browse/TRACING-1208[TRACING-1208] Authentication "500 Internal Error" when accessing Jaeger UI. When trying to authenticate to the UI using OAuth, I get a 500 error because oauth-proxy sidecar doesn't trust the custom CA bundle defined at installation time with the `additionalTrustBundle`. - -* link:https://issues.redhat.com/browse/TRACING-1166[TRACING-1166] It is not currently possible to use the Jaeger streaming strategy within a disconnected environment. When a Kafka cluster is being provisioned, it results in a error: `Failed to pull image registry.redhat.io/amq7/amq-streams-kafka-24-rhel7@sha256:f9ceca004f1b7dccb3b82d9a8027961f9fe4104e0ed69752c0bdd8078b4a1076`. diff --git a/modules/jaeger-rn-known-issues.adoc b/modules/jaeger-rn-known-issues.adoc deleted file mode 100644 index 5628455b6d85..000000000000 --- a/modules/jaeger-rn-known-issues.adoc +++ /dev/null @@ -1,28 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v1x/servicemesh-release-notes.adoc -* service_mesh/v2x/servicemesh-release-notes.adoc -* rhbjaeger-release-notes.adoc -//// - -[id="jaeger-rn-known-issues_{context}"] -= Jaeger known issues - -//// -Consequence - What user action or situation would make this problem appear (Selecting the Foo option with the Bar version 1.3 plugin enabled results in an error message)? What did the customer experience as a result of the issue? What was the symptom? -Cause (if it has been identified) - Why did this happen? -Workaround (If there is one)- What can you do to avoid or negate the effects of this issue in the meantime? Sometimes if there is no workaround it is worthwhile telling readers to contact support for advice. Never promise future fixes. -Result - If the workaround does not completely address the problem. -//// - -These limitations exist in Jaeger: - -* Apache Spark is not supported. - -* Jaeger streaming via AMQ/Kafka is unsupported on IBM Z and IBM Power Systems. - -These are the known issues in Jaeger: - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1918920[BZ-1918920] The Elasticsearch pods does not get restarted automatically after an update. As a workaround, restart the pods manually. - -* link:https://issues.redhat.com/browse/TRACING-809[TRACING-809] Jaeger Ingester is incompatible with Kafka 2.3. When there are two or more instances of the Jaeger Ingester and enough traffic it will continuously generate rebalancing messages in the logs. This is due to a regression in Kafka 2.3 that was fixed in Kafka 2.3.1. For more information, see https://github.com/jaegertracing/jaeger/issues/1819[Jaegertracing-1819]. diff --git a/modules/jaeger-rn-new-features.adoc b/modules/jaeger-rn-new-features.adoc deleted file mode 100644 index 51e6e4fa4bdc..000000000000 --- a/modules/jaeger-rn-new-features.adoc +++ /dev/null @@ -1,25 +0,0 @@ -//// -Module included in the following assemblies: -- rhbjaeger-release-notes.adoc -//// -//// -Feature – Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes. -Reason – If known, include why has the enhancement been implemented (use case, performance, technology, etc.). For example, showcases integration of X with Y, demonstrates Z API feature, includes latest framework bug fixes. -Result – If changed, describe the current user experience. -//// - -[id="jaeger-rn-new-features_{context}"] -== New features {ProductName} 1.20.0 - -* This release of {ProductName} adds support for using an "external" Elasticsearch cluster to store tracing data, that is, an Elasticsearch instance not installed and created by the OpenShift Elasticsearch Operator. - -* This release adds autoscaling support for the Jaeger Collector and Ingester. -//// -Restore this bullet point when OSSMDOC-145 is complete -* This release enabled support for services or applications running outside of an OpenShift cluster to be able to report tracing data to Jaeger running within the OpenShift cluster. -//// - - -== New features {ProductName} 1.17.7 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. diff --git a/modules/jaeger-rn-technology-preview.adoc b/modules/jaeger-rn-technology-preview.adoc deleted file mode 100644 index 166106399a88..000000000000 --- a/modules/jaeger-rn-technology-preview.adoc +++ /dev/null @@ -1,23 +0,0 @@ -//// -Module included in the following assemblies: -- rhbjaeger-release-notes.adoc -//// - -[id="jaeger-rn-tech-preview_{context}"] -= Technology Preview -//// -Provide the following info for each issue if possible: -Description - Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes. Avoid the word “supports” as in [product] now supports [feature] to avoid customer confusion with full support. Say, for example, “available as a Technology Preview.” -Package - A brief description of what the customer has to install or enable to use the Technology Preview feature. (e.g., available in quickstart.zip on customer portal, JDF website, container on registry, enable option, etc.) -//// - -[IMPORTANT] -==== -Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. -These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/. -==== - -== {ProductName} 2.0.0 Technology Preview 1 -When you install the Jaeger Operator you can select a Technology Preview version of Jaeger. This gives you access to clients and infrastructure for exporting tracing data to Jaeger based on the link:https://opentelemetry.io/[OpenTelemetry framework]. Note that this version is not supported for production environments. - -The OpenTelemetry collector allows developers to instrument their code with vendor agnostic APIs, avoiding vendor lock-in and opening the door to a growing ecosystem of observability tooling. diff --git a/modules/jaeger-sidecar-automatic.adoc b/modules/jaeger-sidecar-automatic.adoc deleted file mode 100644 index c3b3650ffa0f..000000000000 --- a/modules/jaeger-sidecar-automatic.adoc +++ /dev/null @@ -1,38 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- rhbjaeger-deploying.adoc -//// - -[id="jaeger-sidecar-automatic_{context}"] -= Automatically injecting sidecars -:pantheon-module-type: PROCEDURE - -To enable this feature, you add the annotation `sidecar.jaegertracing.io/inject` set to either the string `true` or the Jaeger instance name as returned by `oc get jaegers`. -When you specify `true`, there should be only a single Jaeger instance for the same namespace as the deployment, otherwise, the Operator cannot determine which Jaeger instance to use. A specific Jaeger instance name on a deployment has a higher precedence than `true` applied on its namespace. - -The following snippet shows a simple application that will inject a sidecar, with the Jaeger Agent pointing to the single Jaeger instance available in the same namespace: - -.sample automatic sidecar injection -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: myapp - annotations: - "sidecar.jaegertracing.io/inject": "true" # <1> -spec: - selector: - matchLabels: - app: myapp - template: - metadata: - labels: - app: myapp - spec: - containers: - - name: myapp - image: acme/myapp:myversion ----- - -When the sidecar is injected, the Jaeger Agent can then be accessed at its default location on `localhost`. diff --git a/modules/jaeger-sidecar-manual.adoc b/modules/jaeger-sidecar-manual.adoc deleted file mode 100644 index b4e5b07edcb1..000000000000 --- a/modules/jaeger-sidecar-manual.adoc +++ /dev/null @@ -1,58 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- rhbjaeger-deploying.adoc -//// - -[id="jaeger-sidecar-manual_{context}"] -= Manually injecting sidecars -:pantheon-module-type: PROCEDURE - -For controller types other than `Deployments` (for example, `StatefulSets`, `DaemonSets`, etc.), you can manually define the Jaeger Agent sidecar in your specification. - -The following snippet shows the manual definition you can include in your containers section for a Jaeger Agent sidecar: - -.example sidecar definition for a StatefulSet -[source,yaml] ----- -apiVersion: apps/v1 -kind: StatefulSet -metadata: - name: example-statefulset - namespace: example-ns - labels: - app: example-app -spec: - - spec: - containers: - - name: example-app - image: acme/myapp:myversion - ports: - - containerPort: 8080 - protocol: TCP - - name: jaeger-agent - image: registry.redhat.io/distributed-tracing/jaeger-agent-rhel7:<version> - # The agent version must match the operator version - imagePullPolicy: IfNotPresent - ports: - - containerPort: 5775 - name: zk-compact-trft - protocol: UDP - - containerPort: 5778 - name: config-rest - protocol: TCP - - containerPort: 6831 - name: jg-compact-trft - protocol: UDP - - containerPort: 6832 - name: jg-binary-trft - protocol: UDP - - containerPort: 14271 - name: admin-http - protocol: TCP - args: - - --reporter.grpc.host-port=dns:///jaeger-collector-headless.example-ns:14250 - - --reporter.type=grpc ----- - -The Jaeger Agent can then be accessed at its default location on localhost. diff --git a/modules/jaeger-upgrading-es.adoc b/modules/jaeger-upgrading-es.adoc deleted file mode 100644 index 1aa8bf09977a..000000000000 --- a/modules/jaeger-upgrading-es.adoc +++ /dev/null @@ -1,88 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- jaeger_install/rhbjaeger-updating -//// - -[id="upgrading_es5_es6_{context}"] -= Upgrading from Elasticsearch 5 to Elasticsearch 6 - -When updating from Elasticsearch 5 to Elasticsearch 6, you must delete your Jaeger instance, then recreate the Jaeger instance because of an issue with certificates. Re-creating the Jaeger instance triggers creating a new set of certificates. If you are using persistent storage the same volumes can be mounted for the new Jaeger instance as long as the Jaeger name and namespace for the new Jaeger instance are the same as the deleted Jaeger instance. - -.Procedure if Jaeger is installed as part of Red Hat Service Mesh - -. Determine the name of your Jaeger custom resource file: -+ -[source,terminal] ----- -$ oc get jaeger -n istio-system ----- -+ -You should see something like the following: -+ -[source,terminal] ----- -NAME AGE -jaeger 3d21h ----- -+ -. Copy the generated custom resource file into a temporary directory: -+ -[source,terminal] ----- -$ oc get jaeger jaeger -oyaml -n istio-system > /tmp/jaeger-cr.yaml ----- -+ -. Delete the Jaeger instance: -+ -[source,terminal] ----- -$ oc delete jaeger jaeger -n istio-system ----- -+ -. Recreate the Jaeger instance from your copy of the custom resource file: -+ -[source,terminal] ----- -$ oc create -f /tmp/jaeger-cr.yaml -n istio-system ----- -+ -. Delete the copy of the generated custom resource file: -+ -[source,terminal] ----- -$ rm /tmp/jaeger-cr.yaml ----- - - -.Procedure if Jaeger not installed as part of Red Hat Service Mesh - -Before you begin, create a copy of your Jaeger custom resource file. - -. Delete the Jaeger instance by deleting the custom resource file: -+ -[source,terminal] ----- -$ oc delete -f <jaeger-cr-file> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc delete -f jaeger-prod-elasticsearch.yaml ----- -+ -. Recreate your Jaeger instance from the backup copy of your custom resource file: -+ -[source,terminal] ----- -$ oc create -f <jaeger-cr-file> ----- -+ -. Validate that your pods have restarted: -+ -[source,terminal] ----- -$ oc get pods -n jaeger-system -w ----- -+ diff --git a/modules/jira-configuring-acs.adoc b/modules/jira-configuring-acs.adoc new file mode 100644 index 000000000000..cbdc36a821ae --- /dev/null +++ b/modules/jira-configuring-acs.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-jira.adoc +:_mod-docs-content-type: PROCEDURE +[id="jira-configuring-acs_{context}"] += Configuring {product-title} + +Create a new integration in {product-title} by using the Jira server URL and user credentials. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *Jira Software*. +. Click *New integration*. +. Enter a name for *Integration name*. +. Enter the user credentials in the *Username* and *Password or API token* fields. +. For *Issue type*, enter a valid link:https://confluence.atlassian.com/adminjiracloud/issue-types-844500742.html[Jira Issue Type], for example *Task*, *Sub-task*, or *Bug*. +. Enter the Jira server URL in the *Jira URL* field. +. Enter the key of the project in which you want to create issues in the *Default project* field. +. Optional: Use the *Annotation key for project* field to create issues in different Jira projects by completing the following steps. You can use annotations to dynamically create issues. + +.. Add an annotation similar to the following example in your namespace or deployment YAML file, where `jira/project-key` is the annotation key that you specify in your Jira integration. You can create an annotation for the deployment or the namespace. ++ +[source,yaml,subs="+quotes"] +---- +annotations: +# ... + jira/project-key: <jira_project_key> +# ... +---- +.. Use the annotation key `jira/project-key` in the *Annotation key for project* field. +. If you use custom priorities in your Jira project, use the *Priority Mapping* toggle to configure custom priorities. +. If you use mandatory custom fields in your Jira project, enter them as JSON values in the *Default Fields JSON* field. For example: ++ +[source,json] +---- +{ + "customfield_10004": 3, + "customfield_20005": "Alerts", +} +---- +. Select *Test* to test that the integration with Jira is working. +. Select *Create* to generate the configuration. diff --git a/modules/k8s-nmstate-installing-the-kubernetes-nmstate-operator.adoc b/modules/k8s-nmstate-installing-the-kubernetes-nmstate-operator.adoc deleted file mode 100644 index e73e87fabfcf..000000000000 --- a/modules/k8s-nmstate-installing-the-kubernetes-nmstate-operator.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// This is included in the following assemblies: -// -// networking/k8s_nmstate/k8s-nmstate-about-the-kubernetes-nmstate-operator.adoc - -[id="installing-the-kubernetes-nmstate-operator_{context}"] - -= Installing the Kubernetes NMState Operator - -You must install the Kubernetes NMState Operator from the OpenShift web console while logged in with administrator privileges. Once installed, the Operator can deploy the NMState State Controller as a daemon set across all of the cluster nodes. - -.Procedure - -. Select *Operators* -> *OperatorHub*. - -. In the search field below *All Items*, enter `nmstate` and click *Enter* to search for the Kubernetes NMState Operator. - -. Click on the Kubernetes NMState Operator search result. - -. Click on *Install* to open the *Install Operator* window. - -. Under *Installed Namespace*, ensure the namespace is `openshift-nmstate`. If `openshift-nmstate` does not exist in the combo box, click on *Create Namespace* and enter `openshift-nmstate` in the *Name* field of the dialog box and press *Create*. - -. Click *Install* to install the Operator. - -. Once the Operator finishes installing, click *View Operator*. - -. Under *Provided APIs*, click *Create Instance* to open the dialog box for creating an instance of `kubernetes-nmstate`. - -. In the *Name* field of the dialog box, ensure the name of the instance is `nmstate.` -+ -[NOTE] -==== -The name restriction is a known issue. The instance is a singleton for the entire cluster. -==== - -. Accept the default settings and click *Create* to create the instance. - -.Summary - -Once complete, the Operator has deployed the NMState State Controller as a daemon set across all of the cluster nodes. diff --git a/modules/kn-trigger-describe.adoc b/modules/kn-trigger-describe.adoc deleted file mode 100644 index 0c3b7bd02495..000000000000 --- a/modules/kn-trigger-describe.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="kn-trigger-describe_{context}"] -= Describing a trigger using `kn` - -You can use the `kn trigger describe` command to print information about a trigger. - -.Procedure - -* Enter the command: -+ -[source,terminal] ----- -$ kn trigger describe <trigger_name> ----- -+ -.Example output -[source,terminal] ----- -Name: ping -Namespace: default -Labels: eventing.knative.dev/broker=default -Annotations: eventing.knative.dev/creator=kube:admin, eventing.knative.dev/lastModifier=kube:admin -Age: 2m -Broker: default -Filter: - type: dev.knative.event - -Sink: - Name: edisplay - Namespace: default - Resource: Service (serving.knative.dev/v1) - -Conditions: - OK TYPE AGE REASON - ++ Ready 2m - ++ BrokerReady 2m - ++ DependencyReady 2m - ++ Subscribed 2m - ++ SubscriberResolved 2m ----- diff --git a/modules/kn-trigger-filtering.adoc b/modules/kn-trigger-filtering.adoc deleted file mode 100644 index 9cd323875cc8..000000000000 --- a/modules/kn-trigger-filtering.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * /serverless/event_workflows/serverless-using-brokers.adoc - -[id="kn-trigger-filtering_{context}"] -= Filtering events using triggers - -In the following trigger example, only events with the attribute `type: dev.knative.samples.helloworld` will reach the event sink. - -[source,terminal] ----- -$ kn trigger create <trigger_name> --broker <broker_name> --filter type=dev.knative.samples.helloworld --sink ksvc:<service_name> ----- - -You can also filter events using multiple attributes. The following example shows how to filter events using the type, source, and extension attributes. - -[source,terminal] ----- -$ kn trigger create <trigger_name> --broker <broker_name> --sink ksvc:<service_name> \ ---filter type=dev.knative.samples.helloworld \ ---filter source=dev.knative.samples/helloworldsource \ ---filter myextension=my-extension-value ----- diff --git a/modules/kn-trigger-list.adoc b/modules/kn-trigger-list.adoc deleted file mode 100644 index 88f6c20d6c73..000000000000 --- a/modules/kn-trigger-list.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * /serverless/event_workflows/serverless-using-brokers.adoc - -[id="kn-trigger-list_{context}"] -= Listing triggers using `kn` - -The `kn trigger list` command prints a list of available triggers. - -.Procedure -. Print a list of available triggers: -+ -[source,terminal] ----- -$ kn trigger list ----- -+ -.Example output -[source,terminal] ----- -NAME BROKER SINK AGE CONDITIONS READY REASON -email default ksvc:edisplay 4s 5 OK / 5 True -ping default ksvc:edisplay 32s 5 OK / 5 True ----- - -. Optional: Print a list of triggers in JSON format: -+ -[source,terminal] ----- -$ kn trigger list -o json ----- -//example output? diff --git a/modules/kn-trigger-update.adoc b/modules/kn-trigger-update.adoc deleted file mode 100644 index 7626238802b7..000000000000 --- a/modules/kn-trigger-update.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="kn-trigger-update_{context}"] -= Updating a trigger using `kn` - -You can use the `kn trigger update` command with certain flags to update attributes for a trigger. - -.Procedure - -* Update a trigger: -+ -[source,terminal] ----- -$ kn trigger update <trigger_name> --filter <key=value> --sink <sink_name> [flags] ----- -** You can update a trigger to filter exact event attributes that match incoming events. For example, using the `type` attribute: -+ -[source,terminal] ----- -$ kn trigger update <trigger_name> --filter type=knative.dev.event ----- -** You can remove a filter attribute from a trigger. For example, you can remove the filter attribute with key `type`: -+ -[source,terminal] ----- -$ kn trigger update <trigger_name> --filter type- ----- -** You can use the `--sink` parameter to change the event sink of a trigger: -+ -[source,terminal] ----- -$ kn trigger update <trigger_name> --sink ksvc:my-event-sink ----- diff --git a/modules/knative-service-cluster-local.adoc b/modules/knative-service-cluster-local.adoc deleted file mode 100644 index ed592b01c864..000000000000 --- a/modules/knative-service-cluster-local.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-custom-domains.adoc - -[id="knative-service-cluster-local_{context}"] -= Setting cluster availability to `cluster-local` - -By default, Knative services are published to a public IP address. -Being published to a public IP address means that Knative services are public applications, and have a publicly accessible URL. - -Publicly accessible URLs are accessible from outside of the cluster. -However, developers may need to build back-end services that are only be accessible from inside the cluster, known as _private services_. -// Cluster administrators can configure private services for the cluster so that all services are private by default. -// Need to add additional details about editing the configmap for admins -Developers can label individual services in the cluster with the `serving.knative.dev/visibility=cluster-local` label to make them private. - -.Procedure - -* Set the visibility for your service by adding the `serving.knative.dev/visibility=cluster-local` label: -+ - -[source,terminal] ----- -$ oc label ksvc <service_name> serving.knative.dev/visibility=cluster-local ----- - -.Verification - -* Check that the URL for your service is now in the format `\http://<service_name>.<namespace>.svc.cluster.local`, by entering the following command and reviewing the output: -+ - -[source,termina] ----- -$ oc get ksvc ----- - -+ - -.Example output -[source,terminal] ----- -NAME URL LATESTCREATED LATESTREADY READY REASON -hello http://hello.default.svc.cluster.local hello-tx2g7 hello-tx2g7 True ----- diff --git a/modules/knative-serving-advanced-config.adoc b/modules/knative-serving-advanced-config.adoc deleted file mode 100644 index af217aebbff8..000000000000 --- a/modules/knative-serving-advanced-config.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// <List assemblies here, each on a new line> -// * /serverless/installing_serverless/serverless-install-config-options.adoc - -[id="knative-serving-advanced-config_{context}"] -= Knative Serving supported installation configuration options - -[IMPORTANT] -==== -Do not modify any YAML contained inside the `config` field. Some of the configuration values in this field are injected by the {ServerlessOperatorName}, and modifying them will cause your deployment to become unsupported. -==== - -image::serving-form-view.png[Create Knative Serving form in web console Administrator Perspective] - -[id="knative-serving-controller-custom-certs_{context}"] -== Controller Custom Certs - -If your registry uses a self-signed certificate, you must enable tag-to-digest resolution by creating a config map or secret. -To enable tag-to-digest resolution, the Knative Serving controller requires access to the container registry. - -The following example `KnativeServing` custom resource configuration uses a certificate in a config map named `certs` in the `knative-serving` namespace. -This example triggers the {ServerlessOperatorName} to: - -. Create and mount a volume containing the certificate in the controller. -. Set the required environment variable properly. - -.Example YAML -[source,yaml] ----- -apiVersion: operator.knative.dev/v1alpha1 -kind: KnativeServing -metadata: - name: knative-serving - namespace: knative-serving -spec: - controller-custom-certs: - name: config-service-ca - type: ConfigMap <1> ----- -<1> The supported types are `ConfigMap` and `Secret`. - -If no controller custom cert is specified, this setting defaults to use the `config-service-ca` config map. - -After tag-to-digest resolution is enabled, the {ServerlessOperatorName} automatically configures Knative Serving controller access to the registry. - -[IMPORTANT] -==== -The config map or secret must reside in the same namespace as the Knative Serving custom resource definition (CRD). -==== - -[id="knative-serving-high-availability_{context}"] -== High availability - -High availability, which can be configured using the `spec.high-availability` field, defaults to `2` replicas per controller if no number of replicas is specified by a user during the Knative Serving installation. - -You can set this to `1` to disable high availability, or add more replicas by setting a higher integer. - -.Example YAML -[source,yaml] ----- -apiVersion: operator.knative.dev/v1alpha1 -kind: KnativeServing -metadata: - name: knative-serving - namespace: knative-serving -spec: - high-availability: - replicas: 2 ----- diff --git a/modules/knative-serving-concurrent-autoscaling-requests.adoc b/modules/knative-serving-concurrent-autoscaling-requests.adoc deleted file mode 100644 index 9d5462785213..000000000000 --- a/modules/knative-serving-concurrent-autoscaling-requests.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/configuring-knative-serving-autoscaling.adoc - -[id="knative-serving-concurrent-autoscaling-requests_{context}"] -= Configuring concurrent requests for Knative Serving autoscaling - -You can specify the number of concurrent requests that should be handled by each instance of a revision container, or application, by adding the `target` annotation or the `containerConcurrency` field in the revision template. - -.Example revision template YAML using target annotation - -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: myapp -spec: - template: - metadata: - annotations: - autoscaling.knative.dev/target: 50 - spec: - containers: - - image: myimage ----- - -.Example revision template YAML using containerConcurrency annotation - -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: myapp -spec: - template: - metadata: - annotations: - spec: - containerConcurrency: 100 - containers: - - image: myimage ----- - -Adding a value for both `target` and `containerConcurrency` will target the `target` number of concurrent requests, but impose a hard limit of the `containerConcurrency` number of requests. - -For example, if the `target` value is 50 and the `containerConcurrency` value is 100, the targeted number of requests will be 50, but the hard limit will be 100. - -If the `containerConcurrency` value is less than the `target` value, the `target` value will be tuned down, since there is no need to target more requests than the number that can actually be handled. - -[NOTE] -==== -`containerConcurrency` should only be used if there is a clear need to limit how many requests reach the application at a given time. Using `containerConcurrency` is only advised if the application needs to have an enforced constraint of concurrency. -==== - -== Configuring concurrent requests using the target annotation - -The default target for the number of concurrent requests is `100`, but you can override this value by adding or modifying the `autoscaling.knative.dev/target` annotation value in the revision template. - -Here is an example of how this annotation is used in the revision template to set the target to `50`: - -[source,yaml] ----- -autoscaling.knative.dev/target: 50 ----- - -== Configuring concurrent requests using the containerConcurrency field - -`containerConcurrency` sets a hard limit on the number of concurrent requests handled. - -[source,yaml] ----- -containerConcurrency: 0 | 1 | 2-N ----- - -0:: allows unlimited concurrent requests. -1:: guarantees that only one request is handled at a time by a given instance of the revision container. -2 or more:: will limit request concurrency to that value. - -[NOTE] -==== -If there is no `target` annotation, autoscaling is configured as if `target` is equal to the value of `containerConcurrency`. -==== diff --git a/modules/kube-apiserver-operator.adoc b/modules/kube-apiserver-operator.adoc deleted file mode 100644 index 59113eceac20..000000000000 --- a/modules/kube-apiserver-operator.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="kube-apiserver-operator_{context}"] -= Kubernetes API Server Operator - -[discrete] -== Purpose - -The Kubernetes API Server Operator manages and updates the Kubernetes API server deployed on top of {product-title}. The Operator is based on the OpenShift library-go framework and it is installed using the Cluster Version Operator (CVO). - -[discrete] -== Project - -link:https://github.com/openshift/cluster-kube-apiserver-operator[openshift-kube-apiserver-operator] - -[discrete] -== CRDs - -* `kubeapiservers.operator.openshift.io` -** Scope: Cluser -** CR: `kubeapiserver` -** Validation: Yes - -[discrete] -== Configuration objects - -[source,terminal] ----- -$ oc edit kubeapiserver ----- diff --git a/modules/kube-controller-manager-operator.adoc b/modules/kube-controller-manager-operator.adoc deleted file mode 100644 index 3a23c4df9764..000000000000 --- a/modules/kube-controller-manager-operator.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="kube-controller-manager-operator_{context}"] -= Kubernetes Controller Manager Operator - -[discrete] -== Purpose - -The Kubernetes Controller Manager Operator manages and updates the Kubernetes Controller Manager deployed on top of {product-title}. The Operator is based on OpenShift `library-go` framework and it is installed via the Cluster Version Operator (CVO). - -It contains the following components: - -* Operator -* Bootstrap manifest renderer -* Installer based on static pods -* Configuration observer - -By default, the Operator exposes Prometheus metrics through the `metrics` service. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-kube-controller-manager-operator[cluster-kube-controller-manager-operator] diff --git a/modules/kubernetes-role-assignment.adoc b/modules/kubernetes-role-assignment.adoc new file mode 100644 index 000000000000..00e8ed426216 --- /dev/null +++ b/modules/kubernetes-role-assignment.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/review-cluster-configuration.adoc +:_mod-docs-content-type: PROCEDURE +[id="kubernetes-role-assignment_{context}"] += Finding Kubernetes roles and their assignment + +[role="_abstract"] +Use the *Configuration Management* view to get information about the Kubernetes roles that are assigned to specific users and groups. + +.Procedure +. Go to the {product-title-short} portal and click *Configuration Management*. +. Select *Role-Based Access Control* -> *Users and Groups* from the header in the *Configuration Management* view. +The *Users and Groups* view displays a list of Kubernetes users and groups, their assigned roles, and whether the `cluster-admin` role is enabled for each of them. +. Select a user or group to view more details about the associated cluster and namespace permissions. diff --git a/modules/launching-the-operator-provided-argocd-instance.adoc b/modules/launching-the-operator-provided-argocd-instance.adoc deleted file mode 100644 index 6e77919c5959..000000000000 --- a/modules/launching-the-operator-provided-argocd-instance.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module is included in the following assemblies: -// -// * openshift-docs/cicd/gitops/getting-started--with-openshift-gitops.adoc - -[id="launching-the-operator-provided-argocd-instance_{context}"] -= Launching the Operator provided Argo CD instance - -Red Hat OpenShift GitOps uses Argo CD to manage specific cluster-scoped resources, including: platform operators, optional Operator Lifecycle Manager (OLM) operators, and user management. - -To launch the Argo CD instance for your cluster configuration, ensure that the Red Hat OpenShift GitOps Operator is installed on your cluster. After the Operator is installed, it is applicable to all namespaces on the entire cluster. When you install the Red Hat OpenShift GitOps Operator, it automatically sets up a ready-to-use Argo CD instance that is available in the `openshift-gitops` namespace, and an Argo CD icon is displayed in the console toolbar. - -After you install the Red Hat OpenShift GitOps Operator, launch into the Argo CD instance from the *Console Application Launcher* to use Argo CD. - -.Prerequisites - -* You have installed the Red Hat OpenShift GitOps Operator. - -.Procedure - -. In the *Administrator* perspective of the web console, navigate to *Operators* -> *Installed Operators*. -. Navigate to *Red Hat applications* -> *Application Stages* -> *Argo CD*. The login page of the Argo CD UI is displayed in a new window. -. Obtain the password for the Argo CD instance: -.. Navigate to the *Developer* perspective of the web console. A list of available projects is displayed. -.. Navigate to the `openshift-gitops` project. -.. Select the *Secrets* tab. -.. Select the *argocd-cluster-cluster* instance to display the password. -.. Copy the password. -. Use this password to log into the Argo CD UI in the new window. diff --git a/modules/ldap-failover-configure-apache.adoc b/modules/ldap-failover-configure-apache.adoc deleted file mode 100644 index 6986b2a7c33b..000000000000 --- a/modules/ldap-failover-configure-apache.adoc +++ /dev/null @@ -1,191 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-ldap-failover.adoc - -[id="sssd-configuring-apache_{context}"] -= Configuring Apache to use SSSD - -.Procedure - -. Create a `/etc/pam.d/openshift` file that contains the -following contents: -+ ----- -auth required pam_sss.so -account required pam_sss.so ----- -+ -This configuration enables PAM, the pluggable authentication module, to use -`pam_sss.so` to determine authentication and access control when an -authentication request is issued for the `openshift` stack. - -. Edit the `/etc/httpd/conf.modules.d/55-authnz_pam.conf` file and uncomment - the following line: -+ ----- -LoadModule authnz_pam_module modules/mod_authnz_pam.so ----- - -. To configure the Apache `httpd.conf` file for remote basic authentication, -create the `openshift-remote-basic-auth.conf` file in the -`/etc/httpd/conf.d` directory. Use the following template to provide your -required settings and values: -+ -[IMPORTANT] -==== -Carefully review the template and customize its contents to fit your -environment. -==== -+ ----- -LoadModule request_module modules/mod_request.so -LoadModule php7_module modules/libphp7.so - -# Nothing needs to be served over HTTP. This virtual host simply redirects to -# HTTPS. -<VirtualHost *:80> - DocumentRoot /var/www/html - RewriteEngine On - RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R,L] -</VirtualHost> - -<VirtualHost *:443> - # This needs to match the certificates you generated. See the CN and X509v3 - # Subject Alternative Name in the output of: - # openssl x509 -text -in /etc/pki/tls/certs/remote-basic.example.com.crt - ServerName remote-basic.example.com - - DocumentRoot /var/www/html - - # Secure all connections with TLS - SSLEngine on - SSLCertificateFile /etc/pki/tls/certs/remote-basic.example.com.crt - SSLCertificateKeyFile /etc/pki/tls/private/remote-basic.example.com.key - SSLCACertificateFile /etc/pki/CA/certs/ca.crt - - # Require that TLS clients provide a valid certificate - SSLVerifyClient require - SSLVerifyDepth 10 - - # Other SSL options that may be useful - # SSLCertificateChainFile ... - # SSLCARevocationFile ... - - # Send logs to a specific location to make them easier to find - ErrorLog logs/remote_basic_error_log - TransferLog logs/remote_basic_access_log - LogLevel warn - - # PHP script that turns the Apache REMOTE_USER env var - # into a JSON formatted response that OpenShift understands - <Location /check_user.php> - # all requests not using SSL are denied - SSLRequireSSL - # denies access when SSLRequireSSL is applied - SSLOptions +StrictRequire - # Require both a valid basic auth user (so REMOTE_USER is always set) - # and that the CN of the TLS client matches that of the OpenShift master - <RequireAll> - Require valid-user - Require expr %{SSL_CLIENT_S_DN_CN} == 'system:openshift-master' - </RequireAll> - # Use basic auth since OpenShift will call this endpoint with a basic challenge - AuthType Basic - AuthName openshift - AuthBasicProvider PAM - AuthPAMService openshift - - # Store attributes in environment variables. Specify the email attribute that - # you confirmed. - LookupOutput Env - LookupUserAttr mail REMOTE_USER_MAIL - LookupUserGECOS REMOTE_USER_DISPLAY_NAME - - # Other options that might be useful - - # While REMOTE_USER is used as the sub field and serves as the immutable ID, - # REMOTE_USER_PREFERRED_USERNAME could be used to have a different username - # LookupUserAttr <attr_name> REMOTE_USER_PREFERRED_USERNAME - - # Group support may be added in a future release - # LookupUserGroupsIter REMOTE_USER_GROUP - </Location> - - # Deny everything else - <Location ~ "^((?!\/check_user\.php).)*$"> - Deny from all - </Location> -</VirtualHost> ----- - -. Create the `check_user.php` script in the `/var/www/html` directory. -Include the following code: -+ ----- -<?php -// Get the user based on the Apache var, this should always be -// set because we 'Require valid-user' in the configuration -$user = apache_getenv('REMOTE_USER'); - -// However, we assume it may not be set and -// build an error response by default -$data = array( - 'error' => 'remote PAM authentication failed' -); - -// Build a success response if we have a user -if (!empty($user)) { - $data = array( - 'sub' => $user - ); - // Map of optional environment variables to optional JSON fields - $env_map = array( - 'REMOTE_USER_MAIL' => 'email', - 'REMOTE_USER_DISPLAY_NAME' => 'name', - 'REMOTE_USER_PREFERRED_USERNAME' => 'preferred_username' - ); - - // Add all non-empty environment variables to JSON data - foreach ($env_map as $env_name => $json_name) { - $env_data = apache_getenv($env_name); - if (!empty($env_data)) { - $data[$json_name] = $env_data; - } - } -} - -// We always output JSON from this script -header('Content-Type: application/json', true); - -// Write the response as JSON -echo json_encode($data); -?> ----- - -. Enable Apache to load the module. Modify the -`/etc/httpd/conf.modules.d/55-lookup_identity.conf` file and uncomment the -following line: -+ ----- -LoadModule lookup_identity_module modules/mod_lookup_identity.so ----- - -. Set an SELinux boolean so that SElinux allows Apache to connect to SSSD over -D-BUS: -+ ----- -# setsebool -P httpd_dbus_sssd on ----- - -. Set a boolean to tell SELinux that it is acceptable for Apache to contact the -PAM subsystem: -+ ----- -# setsebool -P allow_httpd_mod_auth_pam on ----- - -. Start Apache: -+ ----- -# systemctl start httpd.service ----- diff --git a/modules/ldap-failover-configure-openshift.adoc b/modules/ldap-failover-configure-openshift.adoc deleted file mode 100644 index 48f5fc60d2f1..000000000000 --- a/modules/ldap-failover-configure-openshift.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-ldap-failover.adoc - -[id="sssd-for-ldap-configure-openshift_{context}"] -= Configuring {product-title} to use SSSD as the basic remote authentication server - -Modify the default configuration of your cluster to use the new identity -provider that you created. Complete the following steps on the first master host -listed in the Ansible host inventory file. - -.Procedure - -. Open the `/etc/origin/master/master-config.yaml` file. - -. Locate the `identityProviders` section and replace it with the following code: -+ ----- - identityProviders: - - name: sssd - challenge: true - login: true - mappingMethod: claim - provider: - apiVersion: v1 - kind: BasicAuthPasswordIdentityProvider - url: https://remote-basic.example.com/check_user.php - ca: /etc/origin/master/ca.crt - certFile: /etc/origin/master/openshift-master.crt - keyFile: /etc/origin/master/openshift-master.key ----- - -. Start {product-title} with the updated configuration: -+ ----- -# openshift start \ - --public-master=https://openshift.example.com:8443 \ - --master-config=/etc/origin/master/master-config.yaml \ - --node-config=/etc/origin/node-node1.example.com/node-config.yaml ----- - -. Test a login by using the `oc` CLI: -+ ----- -$ oc login https://openshift.example.com:8443 ----- -+ -You can log in only with valid LDAP credentials. -. List the identities and confirm that an email address is displayed for each -user name. Run the following command: -+ ----- -$ oc get identity -o yaml ----- diff --git a/modules/ldap-failover-configure-sssd.adoc b/modules/ldap-failover-configure-sssd.adoc deleted file mode 100644 index 1f7f69e5177f..000000000000 --- a/modules/ldap-failover-configure-sssd.adoc +++ /dev/null @@ -1,124 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-ldap-failover.adoc - -[id="sssd-configuring-sssd_{context}"] -= Configuring SSSD for LDAP failover -Complete these steps on the remote basic authentication server. - -You can configure the SSSD to retrieve attributes, such as email addresses and -display names, and pass them to {product-title} to display in the web interface. -In the following steps, you configure the SSSD to provide email addresses to -{product-title}. - -.Procedure - -. Install the required SSSD and the web server components: -+ ----- -# yum install -y sssd \ - sssd-dbus \ - realmd \ - httpd \ - mod_session \ - mod_ssl \ - mod_lookup_identity \ - mod_authnz_pam \ - php \ - mod_php ----- - -. Set up SSSD to authenticate this VM against the LDAP server. If the LDAP server -is a FreeIPA or Active Directory environment, then use `realmd` to join -this machine to the domain. -+ ----- -# realm join ldap.example.com ----- -+ -For more advanced cases, see the -https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/System-Level_Authentication_Guide/authconfig-ldap.html[System-Level Authentication Guide] - -. To use SSSD to manage failover situations for LDAP, add more entries to the - `/etc/sssd/sssd.conf` file on the `ldap_uri` line. Systems that are -enrolled with FreeIPA can automatically handle failover by using DNS SRV records. - -. Modify the `[domain/DOMAINNAME]` section of the `/etc/sssd/sssd.conf` file -and add this attribute: -+ ----- -[domain/example.com] -... -ldap_user_extra_attrs = mail <1> ----- -<1> Specify the correct attribute to retrieve email addresses for your LDAP -solution. For IPA, specify `mail`. Other LDAP solutions might use another -attribute, such as `email`. - -. Confirm that the `domain` parameter in the `/etc/sssd/sssd.conf` file -contains only the domain name listed in the `[domain/DOMAINNAME]` section. -+ ----- -domains = example.com ----- - -. Grant Apache permission to retrieve the email attribute. Add the following -lines to the `[ifp]` section of the `/etc/sssd/sssd.conf` file: -+ ----- -[ifp] -user_attributes = +mail -allowed_uids = apache, root ----- - -. To ensure that all of the changes are applied properly, restart SSSD: -+ ----- -$ systemctl restart sssd.service ----- - -. Test that the user information can be retrieved properly: -+ ----- -$ getent passwd <username> -username:*:12345:12345:Example User:/home/username:/usr/bin/bash ----- - -. Confirm that the mail attribute you specified returns an email address from -your domain: -+ ----- -# dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe \ - /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserAttr \ - string:username \ <1> - array:string:mail <2> - -method return time=1528091855.672691 sender=:1.2787 -> destination=:1.2795 serial=13 reply_serial=2 - array [ - dict entry( - string "mail" - variant array [ - string "username@example.com" - ] - ) - ] ----- -<1> Provide a user name in your LDAP solution. -<2> Specify the attribute that you configured. - -. Attempt to log in to the VM as an LDAP user and confirm that you can log in -using LDAP credentials. You can use either the local console or a remote service -like SSH to log in. - -[IMPORTANT] -==== -By default, all users can log in to the remote basic authentication server by using -their LDAP credentials. You can change this behavior: - -* If you use IPA joined systems, -link:https://www.freeipa.org/page/Howto/HBAC_and_allow_all[configure host-based access control]. -* If you use Active Directory joined systems, use a -link:https://docs.pagure.org/SSSD.sssd/design_pages/active_directory_gpo_integration.html[group policy object]. -* For other cases, see the -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system-level_authentication_guide/sssd[SSSD configuration] documentation. -==== diff --git a/modules/ldap-failover-generate-certs.adoc b/modules/ldap-failover-generate-certs.adoc deleted file mode 100644 index f7eb537ec8ea..000000000000 --- a/modules/ldap-failover-generate-certs.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-ldap-failover.adoc - -[id="sssd-generating-certificates_{context}"] -= Generating and sharing certificates with the remote basic authentication server - -Complete the following steps on the first master host listed in the Ansible host inventory file, -by default `/etc/ansible/hosts`. - -.Procedure - -. To ensure that communication between the remote basic authentication server and -{product-title} is trustworthy, create a set of Transport Layer Security (TLS) -certificates to use during the other phases of this set up. Run the following command: -+ ----- -# openshift start \ - --public-master=https://openshift.example.com:8443 \ - --write-config=/etc/origin/ ----- -+ -The output inclues the `/etc/origin/master/ca.crt` and -`/etc/origin/master/ca.key` signing certificates. -. Use the signing certificate to generate keys to use on the remote basic -authentication server: -+ ----- -# mkdir -p /etc/origin/remote-basic/ -# oc adm ca create-server-cert \ - --cert='/etc/origin/remote-basic/remote-basic.example.com.crt' \ - --key='/etc/origin/remote-basic/remote-basic.example.com.key' \ - --hostnames=remote-basic.example.com \ <1> - --signer-cert='/etc/origin/master/ca.crt' \ - --signer-key='/etc/origin/master/ca.key' \ - --signer-serial='/etc/origin/master/ca.serial.txt' ----- -+ -<1> A comma-separated list of all the host names and interface IP addresses that must access the -remote basic authentication server. -+ -[NOTE] -==== -The certificate files that you generate are valid for two years. You can alter -this period by changing the `--expire-days` and `--signer-expire-days` values, -but for security reasons, do not make them greater than 730. -==== -+ -[IMPORTANT] -==== -If you do not list all host names and interface IP addresses that must access the -remote basic authentication server, the HTTPS connection will fail. -==== -. Copy the necessary certificates and key to the remote basic authentication server: -+ ----- -# scp /etc/origin/master/ca.crt \ - root@remote-basic.example.com:/etc/pki/CA/certs/ - -# scp /etc/origin/remote-basic/remote-basic.example.com.crt \ - root@remote-basic.example.com:/etc/pki/tls/certs/ - -# scp /etc/origin/remote-basic/remote-basic.example.com.key \ - root@remote-basic.example.com:/etc/pki/tls/private/ ----- diff --git a/modules/ldap-failover-overview.adoc b/modules/ldap-failover-overview.adoc deleted file mode 100644 index afe0e3577db1..000000000000 --- a/modules/ldap-failover-overview.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-ldap-failover.adoc - -[id="sssd-for-ldap-overview_{context}"] - -{product-title} provides an authentication -provider for use with Lightweight Directory Access Protocol (LDAP) setups, but -it can connect to only a single LDAP server. During {product-title} installation, -you can configure the System Security -Services Daemon (SSSD) for LDAP failover to ensure access to your cluster if one -LDAP server fails. - -The setup for this configuration is advanced and requires a separate -authentication server, also called an *remote basic authentication server*, for -{product-title} to communicate with. You configure this server -to pass extra attributes, such as email addresses, to {product-title} so it can -display them in the web console. - -This topic describes how to complete this set up on a dedicated physical or -virtual machine (VM), but you can also configure SSSD in containers. - -[IMPORTANT] -==== -You must complete all sections of this topic. -==== diff --git a/modules/ldap-failover-prereqs.adoc b/modules/ldap-failover-prereqs.adoc deleted file mode 100644 index 4bf4a40eb217..000000000000 --- a/modules/ldap-failover-prereqs.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-ldap-failover.adoc - -[id="sssd-for-ldap-prereqs_{context}"] -= Prerequisites for configuring basic remote authentication - -* Before starting setup, you must know the following information about your -LDAP server: -** Whether the directory server is powered by -http://www.freeipa.org/page/Main_Page[FreeIPA], Active Directory, or another -LDAP solution. -** The Uniform Resource Identifier (URI) for the LDAP server, for example, -`ldap.example.com`. -** The location of the CA certificate for the LDAP server. -** Whether the LDAP server corresponds to RFC 2307 or RFC2307bis for user groups. -* Prepare the servers: -** `remote-basic.example.com`: A VM to use as the remote basic authentication server. -*** Select an operating system that includes SSSD version 1.12.0 for this server -such as Red Hat Enterprise Linux 7.0 or later. -ifeval::["{context}" == "sssd-ldap-failover-extend"] -*** Install mod_lookup_identity version 0.9.4 or later. You can obtain this -package link:https://github.com/adelton/mod_lookup_identity/releases[from -upstream]. -endif::[] -** `openshift.example.com`: A new installation of {product-title}. -*** You must not -have an authentication method configured for this cluster. -*** Do not start {product-title} on this cluster. diff --git a/modules/ldap-syncing-about.adoc b/modules/ldap-syncing-about.adoc deleted file mode 100644 index 10e628eb052a..000000000000 --- a/modules/ldap-syncing-about.adoc +++ /dev/null @@ -1,122 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-about_{context}"] -= About configuring LDAP sync - -Before you can run LDAP sync, you need a sync -configuration file. This file contains the following LDAP client configuration details: - -* Configuration for connecting to your LDAP server. -* Sync configuration options that are dependent on the schema used in your LDAP -server. -* An administrator-defined list of name mappings that maps {product-title} group names to groups in your LDAP server. - -The format of the configuration file depends upon the schema you are using: RFC 2307, Active Directory, or augmented Active Directory. - -[[ldap-client-configuration]] -LDAP client configuration:: - -The LDAP client configuration section of the configuration defines the connections to your LDAP server. - -The LDAP client configuration section of the configuration defines the connections to your LDAP server. - -.LDAP client configuration -[source,yaml] ----- -url: ldap://10.0.0.0:389 <1> -bindDN: cn=admin,dc=example,dc=com <2> -bindPassword: password <3> -insecure: false <4> -ca: my-ldap-ca-bundle.crt <5> ----- -<1> The connection protocol, IP address of the LDAP server hosting your -database, and the port to connect to, formatted as `scheme://host:port`. -<2> Optional distinguished name (DN) to use as the Bind DN. -{product-title} uses this if elevated privilege is required to retrieve entries for -the sync operation. -<3> Optional password to use to bind. {product-title} uses this if elevated privilege is -necessary to retrieve entries for the sync operation. This value may also be -provided in an environment variable, external file, or encrypted file. -<4> When `false`, secure -LDAP (`ldaps://`) URLs connect using TLS, and insecure LDAP (`ldap://`) URLs are -upgraded to TLS. When `true`, no TLS connection is made to the server and you cannot use `ldaps://` URL schemes. -<5> The certificate bundle to use for validating server certificates for the -configured URL. If empty, {product-title} uses system-trusted roots. This only applies -if `insecure` is set to `false`. - -[[ldap-query-definition]] -LDAP query definition:: -Sync configurations consist of LDAP query definitions for the entries that are -required for synchronization. The specific definition of an LDAP query depends -on the schema used to store membership information in the LDAP server. - -.LDAP query definition -[source,yaml] ----- -baseDN: ou=users,dc=example,dc=com <1> -scope: sub <2> -derefAliases: never <3> -timeout: 0 <4> -filter: (objectClass=person) <5> -pageSize: 0 <6> ----- -<1> The distinguished name (DN) of the branch of the directory where all -searches will start from. It is required that you specify the top of your -directory tree, but you can also specify a subtree in the directory. -<2> The scope of the search. Valid values are `base`, `one`, or `sub`. If this -is left undefined, then a scope of `sub` is assumed. Descriptions of the scope -options can be found in the table below. -<3> The behavior of the search with respect to aliases in the LDAP tree. Valid -values are `never`, `search`, `base`, or `always`. If this is left undefined, -then the default is to `always` dereference aliases. Descriptions of the -dereferencing behaviors can be found in the table below. -<4> The time limit allowed for the search by the client, in seconds. A value of -`0` imposes no client-side limit. -<5> A valid LDAP search filter. If this is left undefined, then the default is -`(objectClass=*)`. -<6> The optional maximum size of response pages from the server, measured in LDAP -entries. If set to `0`, no size restrictions will be made on pages of responses. -Setting paging sizes is necessary when queries return more entries than the -client or server allow by default. - -[[ldap-search]] -.LDAP search scope options -[cols="2a,8a",options="header"] -|=== -|LDAP search scope | Description -.^|`base` | Only consider the object specified by the base DN given for the query. -.^|`one` | Consider all of the objects on the same level in the tree as the base DN for -the query. -.^|`sub` | Consider the entire subtree rooted at the base DN given for the query. -|=== - -[[deref-aliases]] -.LDAP dereferencing behaviors -[cols="2a,8a",options="header"] -|=== -|Dereferencing behavior | Description -.^|`never` | Never dereference any aliases found in the LDAP tree. -.^|`search` | Only dereference aliases found while searching. -.^|`base` | Only dereference aliases while finding the base object. -.^|`always` | Always dereference all aliases found in the LDAP tree. -|=== - -[[user-defined-name-mapping]] -User-defined name mapping:: -A user-defined name mapping explicitly maps the names of {product-title} groups to -unique identifiers that find groups on your LDAP server. The mapping uses normal -YAML syntax. A user-defined mapping can contain an entry for every group in your -LDAP server or only a subset of those groups. If there are groups on the LDAP -server that do not have a user-defined name mapping, the default behavior during -sync is to use the attribute specified as the {product-title} group's name. - -.User-defined name mapping -[source,yaml] ----- -groupUIDNameMapping: - "cn=group1,ou=groups,dc=example,dc=com": firstgroup - "cn=group2,ou=groups,dc=example,dc=com": secondgroup - "cn=group3,ou=groups,dc=example,dc=com": thirdgroup ----- diff --git a/modules/ldap-syncing-activedir.adoc b/modules/ldap-syncing-activedir.adoc deleted file mode 100644 index e0aa6c0495d0..000000000000 --- a/modules/ldap-syncing-activedir.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-activedir_{context}"] -= Syncing groups using the Active Directory schema - -In the Active Directory schema, both users (Jane and Jim) exist in the LDAP -server as first-class entries, and group membership is stored in attributes on -the user. The following snippet of `ldif` defines the users and group for this -schema: - -.LDAP entries that use Active Directory schema: `active_directory.ldif` -[source,ldif] ----- -dn: ou=users,dc=example,dc=com -objectClass: organizationalUnit -ou: users - -dn: cn=Jane,ou=users,dc=example,dc=com -objectClass: person -objectClass: organizationalPerson -objectClass: inetOrgPerson -objectClass: testPerson -cn: Jane -sn: Smith -displayName: Jane Smith -mail: jane.smith@example.com -memberOf: admins <1> - -dn: cn=Jim,ou=users,dc=example,dc=com -objectClass: person -objectClass: organizationalPerson -objectClass: inetOrgPerson -objectClass: testPerson -cn: Jim -sn: Adams -displayName: Jim Adams -mail: jim.adams@example.com -memberOf: admins ----- -<1> The user's group memberships are listed as attributes on the user, and the -group does not exist as an entry on the server. The `memberOf` attribute does -not have to be a literal attribute on the user; in some LDAP servers, it is created -during search and returned to the client, but not committed to the database. - -.Prerequisites - -* Create the configuration file. - -.Procedure - -* Run the sync with the `active_directory_config.yaml` file: -+ -[source,terminal] ----- -$ oc adm groups sync --sync-config=active_directory_config.yaml --confirm ----- -+ -{product-title} creates the following group record as a result of the above sync -operation: -+ -.{product-title} group created by using the `active_directory_config.yaml` file -[source,yaml] ----- -apiVersion: user.openshift.io/v1 -kind: Group -metadata: - annotations: - openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 <1> - openshift.io/ldap.uid: admins <2> - openshift.io/ldap.url: LDAP_SERVER_IP:389 <3> - creationTimestamp: - name: admins <4> -users: <5> -- jane.smith@example.com -- jim.adams@example.com ----- -<1> The last time this {product-title} group was synchronized with the LDAP server, in ISO 6801 -format. -<2> The unique identifier for the group on the LDAP server. -<3> The IP address and host of the LDAP server where this group's record is -stored. -<4> The name of the group as listed in the LDAP server. -<5> The users that are members of the group, named as specified by the sync -file. diff --git a/modules/ldap-syncing-augmented-activedir.adoc b/modules/ldap-syncing-augmented-activedir.adoc deleted file mode 100644 index 43ce95e4c009..000000000000 --- a/modules/ldap-syncing-augmented-activedir.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-augmented-activedir_{context}"] -= Syncing groups using the augmented Active Directory schema - -In the augmented Active Directory schema, both users (Jane and Jim) and groups -exist in the LDAP server as first-class entries, and group membership is stored -in attributes on the user. The following snippet of `ldif` defines the users and -group for this schema: - -.LDAP entries that use augmented Active Directory schema: `augmented_active_directory.ldif` -[source,ldif] ----- -dn: ou=users,dc=example,dc=com -objectClass: organizationalUnit -ou: users - -dn: cn=Jane,ou=users,dc=example,dc=com -objectClass: person -objectClass: organizationalPerson -objectClass: inetOrgPerson -objectClass: testPerson -cn: Jane -sn: Smith -displayName: Jane Smith -mail: jane.smith@example.com -memberOf: cn=admins,ou=groups,dc=example,dc=com <1> - -dn: cn=Jim,ou=users,dc=example,dc=com -objectClass: person -objectClass: organizationalPerson -objectClass: inetOrgPerson -objectClass: testPerson -cn: Jim -sn: Adams -displayName: Jim Adams -mail: jim.adams@example.com -memberOf: cn=admins,ou=groups,dc=example,dc=com - -dn: ou=groups,dc=example,dc=com -objectClass: organizationalUnit -ou: groups - -dn: cn=admins,ou=groups,dc=example,dc=com <2> -objectClass: groupOfNames -cn: admins -owner: cn=admin,dc=example,dc=com -description: System Administrators -member: cn=Jane,ou=users,dc=example,dc=com -member: cn=Jim,ou=users,dc=example,dc=com ----- -<1> The user's group memberships are listed as attributes on the user. -<2> The group is a first-class entry on the LDAP server. - -.Prerequisites - -* Create the configuration file. - -.Procedure - -* Run the sync with the `augmented_active_directory_config.yaml` file: -+ -[source,terminal] ----- -$ oc adm groups sync --sync-config=augmented_active_directory_config.yaml --confirm ----- -+ -{product-title} creates the following group record as a result of the above sync -operation: -+ -.OpenShift group created by using the `augmented_active_directory_config.yaml` file - -[source,yaml] ----- -apiVersion: user.openshift.io/v1 -kind: Group -metadata: - annotations: - openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 <1> - openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com <2> - openshift.io/ldap.url: LDAP_SERVER_IP:389 <3> - creationTimestamp: - name: admins <4> -users: <5> -- jane.smith@example.com -- jim.adams@example.com ----- -<1> The last time this {product-title} group was synchronized with the LDAP server, in ISO 6801 format. -<2> The unique identifier for the group on the LDAP server. -<3> The IP address and host of the LDAP server where this group's record is stored. -<4> The name of the group as specified by the sync file. -<5> The users that are members of the group, named as specified by the sync file. diff --git a/modules/ldap-syncing-config-activedir.adoc b/modules/ldap-syncing-config-activedir.adoc deleted file mode 100644 index de8370dfc36b..000000000000 --- a/modules/ldap-syncing-config-activedir.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-config-activedir_{context}"] -= About the Active Directory configuration file - -The Active Directory schema requires you to provide an LDAP query definition for -user entries, as well as the attributes to represent them with in the internal -{product-title} group records. - -For clarity, the group you create in {product-title} should use attributes other -than the distinguished name whenever possible for user- or administrator-facing -fields. For example, identify the users of an {product-title} group by their e-mail, but define -the name of the group by the name of the group on the LDAP server. -The following configuration file creates these relationships: - -.LDAP sync configuration that uses Active Directory schema: `active_directory_config.yaml` -[source,yaml] ----- -kind: LDAPSyncConfig -apiVersion: v1 -url: ldap://LDAP_SERVICE_IP:389 -activeDirectory: - usersQuery: - baseDN: "ou=users,dc=example,dc=com" - scope: sub - derefAliases: never - filter: (objectclass=person) - pageSize: 0 - userNameAttributes: [ mail ] <1> - groupMembershipAttributes: [ memberOf ] <2> ----- -<1> The attribute to use as the name of the user in the {product-title} group record. -<2> The attribute on the user that stores the membership information. diff --git a/modules/ldap-syncing-config-augmented-activedir.adoc b/modules/ldap-syncing-config-augmented-activedir.adoc deleted file mode 100644 index 8bd4a07617c1..000000000000 --- a/modules/ldap-syncing-config-augmented-activedir.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-config-augmented-activedir_{context}"] -= About the augmented Active Directory configuration file - -The augmented Active Directory schema requires you to provide an LDAP query -definition for both user entries and group entries, as well as the attributes -with which to represent them in the internal {product-title} group records. - -For clarity, the group you create in {product-title} should use attributes other -than the distinguished name whenever possible for user- or administrator-facing -fields. For example, identify the users of an {product-title} group by their e-mail, -and use the name of the group as the common name. The following configuration -file creates these relationships. - -.LDAP sync configuration that uses augmented Active Directory schema: `augmented_active_directory_config.yaml` -[source,yaml] ----- -kind: LDAPSyncConfig -apiVersion: v1 -url: ldap://LDAP_SERVICE_IP:389 -augmentedActiveDirectory: - groupsQuery: - baseDN: "ou=groups,dc=example,dc=com" - scope: sub - derefAliases: never - pageSize: 0 - groupUIDAttribute: dn <1> - groupNameAttributes: [ cn ] <2> - usersQuery: - baseDN: "ou=users,dc=example,dc=com" - scope: sub - derefAliases: never - filter: (objectclass=person) - pageSize: 0 - userNameAttributes: [ mail ] <3> - groupMembershipAttributes: [ memberOf ] <4> ----- -<1> The attribute that uniquely identifies a group on the LDAP server. You -cannot specify `groupsQuery` filters when using DN for groupUIDAttribute. For -fine-grained filtering, use the whitelist / blacklist method. -<2> The attribute to use as the name of the group. -<3> The attribute to use as the name of the user in the {product-title} group record. -<4> The attribute on the user that stores the membership information. diff --git a/modules/ldap-syncing-config-rfc2307.adoc b/modules/ldap-syncing-config-rfc2307.adoc deleted file mode 100644 index 0d780ba9cfb2..000000000000 --- a/modules/ldap-syncing-config-rfc2307.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-config-rfc2307_{context}"] -= About the RFC 2307 configuration file - -The RFC 2307 schema requires you to provide an LDAP query definition for both user -and group entries, as well as the attributes with which to represent them in the -internal {product-title} records. - -For clarity, the group you create in {product-title} should use attributes other -than the distinguished name whenever possible for user- or administrator-facing -fields. For example, identify the users of an {product-title} group by their e-mail, and use the -name of the group as the common name. The following configuration file creates -these relationships: - -[NOTE] -==== -If using user-defined name mappings, your configuration file will differ. -==== - -.LDAP sync configuration that uses RFC 2307 schema: `rfc2307_config.yaml` -[source,yaml] ----- -kind: LDAPSyncConfig -apiVersion: v1 -url: ldap://LDAP_SERVICE_IP:389 <1> -insecure: false <2> -rfc2307: - groupsQuery: - baseDN: "ou=groups,dc=example,dc=com" - scope: sub - derefAliases: never - pageSize: 0 - groupUIDAttribute: dn <3> - groupNameAttributes: [ cn ] <4> - groupMembershipAttributes: [ member ] <5> - usersQuery: - baseDN: "ou=users,dc=example,dc=com" - scope: sub - derefAliases: never - pageSize: 0 - userUIDAttribute: dn <6> - userNameAttributes: [ mail ] <7> - tolerateMemberNotFoundErrors: false - tolerateMemberOutOfScopeErrors: false ----- -<1> The IP address and host of the LDAP server where this group's record is -stored. -<2> When `false`, secure -LDAP (`ldaps://`) URLs connect using TLS, and insecure LDAP (`ldap://`) URLs are -upgraded to TLS. When `true`, no TLS connection is made to the server and you cannot use `ldaps://` URL schemes. -<3> The attribute that uniquely identifies a group on the LDAP server. -You cannot specify `groupsQuery` filters when using DN for `groupUIDAttribute`. -For fine-grained filtering, use the whitelist / blacklist method. -<4> The attribute to use as the name of the group. -<5> The attribute on the group that stores the membership information. -<6> The attribute that uniquely identifies a user on the LDAP server. You -cannot specify `usersQuery` filters when using DN for userUIDAttribute. For -fine-grained filtering, use the whitelist / blacklist method. -<7> The attribute to use as the name of the user in the {product-title} group record. diff --git a/modules/ldap-syncing-examples.adoc b/modules/ldap-syncing-examples.adoc deleted file mode 100644 index bbd308ee093c..000000000000 --- a/modules/ldap-syncing-examples.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-examples_{context}"] -= LDAP group sync examples - -This section contains examples for the RFC 2307, Active Directory, and -augmented Active Directory schemas. - -[NOTE] -==== -These examples assume that all users are direct members of their respective -groups. Specifically, no groups have other groups as members. See -the Nested Membership Sync Example for information on -how to sync nested groups. -==== - diff --git a/modules/ldap-syncing-nesting.adoc b/modules/ldap-syncing-nesting.adoc deleted file mode 100644 index 35f1fe29fd57..000000000000 --- a/modules/ldap-syncing-nesting.adoc +++ /dev/null @@ -1,181 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-nesting_{context}"] -== LDAP nested membership sync example - -Groups in {product-title} do not nest. The LDAP server must flatten group -membership before the data can be consumed. Microsoft's Active Directory Server -supports this feature via the -link:https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[`LDAP_MATCHING_RULE_IN_CHAIN`] -rule, which has the OID `1.2.840.113556.1.4.1941`. Furthermore, only explicitly -whitelisted groups can be synced when using this matching rule. - -This section has an example for the augmented Active Directory schema, which -synchronizes a group named `admins` that has one user `Jane` and one group -`otheradmins` as members. The `otheradmins` group has one user member: `Jim`. -This example explains: - -* How the group and users are added to the LDAP server. -* What the LDAP sync configuration file looks like. -* What the resulting group record in {product-title} will be after synchronization. - -In the augmented Active Directory schema, both users (`Jane` and `Jim`) and -groups exist in the LDAP server as first-class entries, and group membership is -stored in attributes on the user or the group. The following snippet of `ldif` -defines the users and groups for this schema: - -.LDAP entries that use augmented Active Directory schema with nested members: `augmented_active_directory_nested.ldif` -[source,ldif] ----- -dn: ou=users,dc=example,dc=com -objectClass: organizationalUnit -ou: users - -dn: cn=Jane,ou=users,dc=example,dc=com -objectClass: person -objectClass: organizationalPerson -objectClass: inetOrgPerson -objectClass: testPerson -cn: Jane -sn: Smith -displayName: Jane Smith -mail: jane.smith@example.com -memberOf: cn=admins,ou=groups,dc=example,dc=com <1> - -dn: cn=Jim,ou=users,dc=example,dc=com -objectClass: person -objectClass: organizationalPerson -objectClass: inetOrgPerson -objectClass: testPerson -cn: Jim -sn: Adams -displayName: Jim Adams -mail: jim.adams@example.com -memberOf: cn=otheradmins,ou=groups,dc=example,dc=com <1> - -dn: ou=groups,dc=example,dc=com -objectClass: organizationalUnit -ou: groups - -dn: cn=admins,ou=groups,dc=example,dc=com <2> -objectClass: group -cn: admins -owner: cn=admin,dc=example,dc=com -description: System Administrators -member: cn=Jane,ou=users,dc=example,dc=com -member: cn=otheradmins,ou=groups,dc=example,dc=com - -dn: cn=otheradmins,ou=groups,dc=example,dc=com <2> -objectClass: group -cn: otheradmins -owner: cn=admin,dc=example,dc=com -description: Other System Administrators -memberOf: cn=admins,ou=groups,dc=example,dc=com <1> <3> -member: cn=Jim,ou=users,dc=example,dc=com ----- -<1> The user's and group's memberships are listed as attributes on the object. -<2> The groups are first-class entries on the LDAP server. -<3> The `otheradmins` group is a member of the `admins` group. - -When syncing nested groups with Active Directory, you must provide an LDAP query -definition for both user entries and group entries, as well as the attributes -with which to represent them in the internal {product-title} group records. -Furthermore, certain changes are required in this configuration: - -- The `oc adm groups sync` command must explicitly whitelist groups. -- The user's `groupMembershipAttributes` must include -`"memberOf:1.2.840.113556.1.4.1941:"` to comply with the -https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[`LDAP_MATCHING_RULE_IN_CHAIN`] -rule. -- The `groupUIDAttribute` must be set to `dn`. -- The `groupsQuery`: - * Must not set `filter`. - * Must set a valid `derefAliases`. - * Should not set `baseDN` as that value is ignored. - * Should not set `scope` as that value is ignored. - -For clarity, the group you create in {product-title} should use attributes other -than the distinguished name whenever possible for user- or administrator-facing -fields. For example, identify the users of an {product-title} group by their e-mail, and use the -name of the group as the common name. The following configuration file creates -these relationships: - -.LDAP sync configuration that uses augmented Active Directory schema with nested members: `augmented_active_directory_config_nested.yaml` -[source,yaml] ----- -kind: LDAPSyncConfig -apiVersion: v1 -url: ldap://LDAP_SERVICE_IP:389 -augmentedActiveDirectory: - groupsQuery: <1> - derefAliases: never - pageSize: 0 - groupUIDAttribute: dn <2> - groupNameAttributes: [ cn ] <3> - usersQuery: - baseDN: "ou=users,dc=example,dc=com" - scope: sub - derefAliases: never - filter: (objectclass=person) - pageSize: 0 - userNameAttributes: [ mail ] <4> - groupMembershipAttributes: [ "memberOf:1.2.840.113556.1.4.1941:" ] <5> ----- -<1> `groupsQuery` filters cannot be specified. The `groupsQuery` base DN and scope -values are ignored. `groupsQuery` must set a valid `derefAliases`. -<2> The attribute that uniquely identifies a group on the LDAP server. It must be set to `dn`. -<3> The attribute to use as the name of the group. -<4> The attribute to use as the name of the user in the {product-title} group -record. `mail` or `sAMAccountName` are preferred choices in most installations. -<5> The attribute on the user that stores the membership information. Note the use -of https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[`LDAP_MATCHING_RULE_IN_CHAIN`]. - -.Prerequisites - -* Create the configuration file. - -.Procedure - -* Run the sync with the `augmented_active_directory_config_nested.yaml` file: -+ -[source,terminal] ----- -$ oc adm groups sync \ - 'cn=admins,ou=groups,dc=example,dc=com' \ - --sync-config=augmented_active_directory_config_nested.yaml \ - --confirm ----- -+ -[NOTE] -==== -You must explicitly whitelist the `cn=admins,ou=groups,dc=example,dc=com` group. -==== -+ -{product-title} creates the following group record as a result of the above sync -operation: -+ -.OpenShift group created by using the `augmented_active_directory_config_nested.yaml` file -[source,yaml] ----- -apiVersion: user.openshift.io/v1 -kind: Group -metadata: - annotations: - openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 <1> - openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com <2> - openshift.io/ldap.url: LDAP_SERVER_IP:389 <3> - creationTimestamp: - name: admins <4> -users: <5> -- jane.smith@example.com -- jim.adams@example.com ----- -<1> The last time this {product-title} group was synchronized with the LDAP server, in ISO 6801 format. -<2> The unique identifier for the group on the LDAP server. -<3> The IP address and host of the LDAP server where this group's record is stored. -<4> The name of the group as specified by the sync file. -<5> The users that are members of the group, named as specified by the sync file. -Note that members of nested groups are included since the group membership was -flattened by the Microsoft Active Directory Server. diff --git a/modules/ldap-syncing-pruning.adoc b/modules/ldap-syncing-pruning.adoc deleted file mode 100644 index d1c70f572b47..000000000000 --- a/modules/ldap-syncing-pruning.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-pruning_{context}"] -= Running a group pruning job - -An administrator can also choose to remove groups from {product-title} records -if the records on the LDAP server that created them are no longer present. The -prune job will accept the same sync configuration file and whitelists or blacklists -as used for the sync job. - -For example: - -[source,terminal] ----- -$ oc adm prune groups --sync-config=/path/to/ldap-sync-config.yaml --confirm ----- - -[source,terminal] ----- -$ oc adm prune groups --whitelist=/path/to/whitelist.txt --sync-config=/path/to/ldap-sync-config.yaml --confirm ----- - -[source,terminal] ----- -$ oc adm prune groups --blacklist=/path/to/blacklist.txt --sync-config=/path/to/ldap-sync-config.yaml --confirm ----- diff --git a/modules/ldap-syncing-rfc2307-user-defined-error.adoc b/modules/ldap-syncing-rfc2307-user-defined-error.adoc deleted file mode 100644 index b00405152968..000000000000 --- a/modules/ldap-syncing-rfc2307-user-defined-error.adoc +++ /dev/null @@ -1,150 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-rfc2307-user-defined-error_{context}"] -= Syncing groups using RFC 2307 with user-defined error tolerances - -By default, if the groups being synced contain members whose entries are outside -of the scope defined in the member query, the group sync fails with an error: - ----- -Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in group "<group>" failed because of "search for entry with dn="<user-dn>" would search outside of the base dn specified (dn="<base-dn>")". ----- - -This often indicates a misconfigured `baseDN` in the `usersQuery` field. -However, in cases where the `baseDN` intentionally does not contain some of the -members of the group, setting `tolerateMemberOutOfScopeErrors: true` allows -the group sync to continue. Out of scope members will be ignored. - -Similarly, when the group sync process fails to locate a member for a group, it -fails outright with errors: - ----- -Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in group "<group>" failed because of "search for entry with base dn="<user-dn>" refers to a non-existent entry". -Error determining LDAP group membership for "<group>": membership lookup for user "<user>" in group "<group>" failed because of "search for entry with base dn="<user-dn>" and filter "<filter>" did not return any results". ----- - -This often indicates a misconfigured `usersQuery` field. However, in cases -where the group contains member entries that are known to be missing, setting -`tolerateMemberNotFoundErrors: true` allows the group sync to continue. -Problematic members will be ignored. - -[WARNING] -==== -Enabling error tolerances for the LDAP group sync causes the sync process to -ignore problematic member entries. If the LDAP group sync is not configured -correctly, this could result in synced {product-title} groups missing members. -==== - -.LDAP entries that use RFC 2307 schema with problematic group membership: `rfc2307_problematic_users.ldif` -[source,ldif] ----- - dn: ou=users,dc=example,dc=com - objectClass: organizationalUnit - ou: users - dn: cn=Jane,ou=users,dc=example,dc=com - objectClass: person - objectClass: organizationalPerson - objectClass: inetOrgPerson - cn: Jane - sn: Smith - displayName: Jane Smith - mail: jane.smith@example.com - dn: cn=Jim,ou=users,dc=example,dc=com - objectClass: person - objectClass: organizationalPerson - objectClass: inetOrgPerson - cn: Jim - sn: Adams - displayName: Jim Adams - mail: jim.adams@example.com - dn: ou=groups,dc=example,dc=com - objectClass: organizationalUnit - ou: groups - dn: cn=admins,ou=groups,dc=example,dc=com - objectClass: groupOfNames - cn: admins - owner: cn=admin,dc=example,dc=com - description: System Administrators - member: cn=Jane,ou=users,dc=example,dc=com - member: cn=Jim,ou=users,dc=example,dc=com - member: cn=INVALID,ou=users,dc=example,dc=com <1> - member: cn=Jim,ou=OUTOFSCOPE,dc=example,dc=com <2> ----- -<1> A member that does not exist on the LDAP server. -<2> A member that may exist, but is not under the `baseDN` in the -user query for the sync job. - -To tolerate the errors in the above example, the following additions to -your sync configuration file must be made: - -.LDAP sync configuration that uses RFC 2307 schema tolerating errors: `rfc2307_config_tolerating.yaml` -[source,yaml] ----- -kind: LDAPSyncConfig -apiVersion: v1 -url: ldap://LDAP_SERVICE_IP:389 -rfc2307: - groupsQuery: - baseDN: "ou=groups,dc=example,dc=com" - scope: sub - derefAliases: never - groupUIDAttribute: dn - groupNameAttributes: [ cn ] - groupMembershipAttributes: [ member ] - usersQuery: - baseDN: "ou=users,dc=example,dc=com" - scope: sub - derefAliases: never - userUIDAttribute: dn <1> - userNameAttributes: [ mail ] - tolerateMemberNotFoundErrors: true <2> - tolerateMemberOutOfScopeErrors: true <3> ----- -<1> The attribute that uniquely identifies a user on the LDAP server. You -cannot specify `usersQuery` filters when using DN for userUIDAttribute. For -fine-grained filtering, use the whitelist / blacklist method. -<2> When `true`, the sync job tolerates groups for which some members were not -found, and members whose LDAP entries are not found are ignored. The -default behavior for the sync job is to fail if a member of a group is not -found. -<3> When `true`, the sync job tolerates groups for which some members are outside -the user scope given in the `usersQuery` base DN, and members outside the member -query scope are ignored. The default behavior for the sync job is to fail if a -member of a group is out of scope. - -.Prerequisites - -* Create the configuration file. - -.Procedure - -* Run the sync with the `rfc2307_config_tolerating.yaml` file: -+ -[source,terminal] ----- -$ oc adm groups sync --sync-config=rfc2307_config_tolerating.yaml --confirm ----- -+ -{product-title} creates the following group record as a result of the above sync -operation: -+ -.{product-title} group created by using the `rfc2307_config.yaml` file -[source,yaml] ----- -apiVersion: user.openshift.io/v1 -kind: Group -metadata: - annotations: - openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 - openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com - openshift.io/ldap.url: LDAP_SERVER_IP:389 - creationTimestamp: - name: admins -users: <1> -- jane.smith@example.com -- jim.adams@example.com ----- -<1> The users that are members of the group, as specified by the sync file. -Members for which lookup encountered tolerated errors are absent. diff --git a/modules/ldap-syncing-rfc2307-user-defined.adoc b/modules/ldap-syncing-rfc2307-user-defined.adoc deleted file mode 100644 index 5183fc6f1abb..000000000000 --- a/modules/ldap-syncing-rfc2307-user-defined.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-rfc2307-user-defined_{context}"] -= Syncing groups using the RFC2307 schema with user-defined name mappings - -When syncing groups with user-defined name mappings, the configuration file -changes to contain these mappings as shown below. - -.LDAP sync configuration that uses RFC 2307 schema with user-defined name mappings: `rfc2307_config_user_defined.yaml` -[source,yaml] ----- -kind: LDAPSyncConfig -apiVersion: v1 -groupUIDNameMapping: - "cn=admins,ou=groups,dc=example,dc=com": Administrators <1> -rfc2307: - groupsQuery: - baseDN: "ou=groups,dc=example,dc=com" - scope: sub - derefAliases: never - pageSize: 0 - groupUIDAttribute: dn <2> - groupNameAttributes: [ cn ] <3> - groupMembershipAttributes: [ member ] - usersQuery: - baseDN: "ou=users,dc=example,dc=com" - scope: sub - derefAliases: never - pageSize: 0 - userUIDAttribute: dn <4> - userNameAttributes: [ mail ] - tolerateMemberNotFoundErrors: false - tolerateMemberOutOfScopeErrors: false ----- -<1> The user-defined name mapping. -<2> The unique identifier attribute that is used for the keys in the -user-defined name mapping. You cannot specify `groupsQuery` filters when using -DN for groupUIDAttribute. For fine-grained filtering, use the whitelist / blacklist method. -<3> The attribute to name {product-title} groups with if their unique identifier is -not in the user-defined name mapping. -<4> The attribute that uniquely identifies a user on the LDAP server. You -cannot specify `usersQuery` filters when using DN for userUIDAttribute. For -fine-grained filtering, use the whitelist / blacklist method. - -.Prerequisites - -* Create the configuration file. - -.Procedure - -* Run the sync with the `rfc2307_config_user_defined.yaml` file: -+ -[source,terminal] ----- -$ oc adm groups sync --sync-config=rfc2307_config_user_defined.yaml --confirm ----- -+ -{product-title} creates the following group record as a result of the above sync -operation: -+ -.{product-title} group created by using the `rfc2307_config_user_defined.yaml` file -[source,yaml] ----- -apiVersion: user.openshift.io/v1 -kind: Group -metadata: - annotations: - openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 - openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com - openshift.io/ldap.url: LDAP_SERVER_IP:389 - creationTimestamp: - name: Administrators <1> -users: -- jane.smith@example.com -- jim.adams@example.com ----- -<1> The name of the group as specified by the user-defined name mapping. diff --git a/modules/ldap-syncing-rfc2307.adoc b/modules/ldap-syncing-rfc2307.adoc deleted file mode 100644 index 87e9d5f28cba..000000000000 --- a/modules/ldap-syncing-rfc2307.adoc +++ /dev/null @@ -1,102 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-rfc2307_{context}"] -= Syncing groups using the RFC 2307 schema - -For the RFC 2307 schema, the following examples synchronize a group named `admins` that has two -members: `Jane` and `Jim`. The examples explain: - -* How the group and users are added to the LDAP server. -* What the resulting group record in {product-title} will be after synchronization. - -[NOTE] -==== -These examples assume that all users are direct members of their respective -groups. Specifically, no groups have other groups as members. See -the Nested Membership Sync Example for information on -how to sync nested groups. -==== - -In the RFC 2307 schema, both users (Jane and Jim) and groups exist on the LDAP -server as first-class entries, and group membership is stored in attributes on -the group. The following snippet of `ldif` defines the users and group for this -schema: - -.LDAP entries that use RFC 2307 schema: `rfc2307.ldif` -[source,ldif] ----- - dn: ou=users,dc=example,dc=com - objectClass: organizationalUnit - ou: users - dn: cn=Jane,ou=users,dc=example,dc=com - objectClass: person - objectClass: organizationalPerson - objectClass: inetOrgPerson - cn: Jane - sn: Smith - displayName: Jane Smith - mail: jane.smith@example.com - dn: cn=Jim,ou=users,dc=example,dc=com - objectClass: person - objectClass: organizationalPerson - objectClass: inetOrgPerson - cn: Jim - sn: Adams - displayName: Jim Adams - mail: jim.adams@example.com - dn: ou=groups,dc=example,dc=com - objectClass: organizationalUnit - ou: groups - dn: cn=admins,ou=groups,dc=example,dc=com <1> - objectClass: groupOfNames - cn: admins - owner: cn=admin,dc=example,dc=com - description: System Administrators - member: cn=Jane,ou=users,dc=example,dc=com <2> - member: cn=Jim,ou=users,dc=example,dc=com ----- -<1> The group is a first-class entry in the LDAP server. -<2> Members of a group are listed with an identifying reference as attributes on -the group. - -.Prerequisites - -* Create the configuration file. - -.Procedure - -* Run the sync with the `rfc2307_config.yaml` file: -+ -[source,terminal] ----- -$ oc adm groups sync --sync-config=rfc2307_config.yaml --confirm ----- -+ -{product-title} creates the following group record as a result of the above sync -operation: -+ -.{product-title} group created by using the `rfc2307_config.yaml` file -[source,yaml] ----- -apiVersion: user.openshift.io/v1 -kind: Group -metadata: - annotations: - openshift.io/ldap.sync-time: 2015-10-13T10:08:38-0400 <1> - openshift.io/ldap.uid: cn=admins,ou=groups,dc=example,dc=com <2> - openshift.io/ldap.url: LDAP_SERVER_IP:389 <3> - creationTimestamp: - name: admins <4> -users: <5> -- jane.smith@example.com -- jim.adams@example.com ----- -<1> The last time this {product-title} group was synchronized with the LDAP server, in ISO 6801 -format. -<2> The unique identifier for the group on the LDAP server. -<3> The IP address and host of the LDAP server where this group's record is -stored. -<4> The name of the group as specified by the sync file. -<5> The users that are members of the group, named as specified by the sync file. diff --git a/modules/ldap-syncing-running-all-ldap.adoc b/modules/ldap-syncing-running-all-ldap.adoc deleted file mode 100644 index 7c481bb80888..000000000000 --- a/modules/ldap-syncing-running-all-ldap.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing-groups.adoc - -[id="ldap-syncing-running-all-ldap_{context}"] -= Syncing the LDAP server with {product-title} - -You can sync all groups from the LDAP server with {product-title}. - -.Prerequisites - -* Create a sync configuration file. - -.Procedure - -* To sync all groups from the LDAP server with {product-title}: -+ -[source,terminal] ----- -$ oc adm groups sync --sync-config=config.yaml --confirm ----- -+ -[NOTE] -==== -By default, all group synchronization operations are dry-run, so you -must set the `--confirm` flag on the `oc adm groups sync` command to make -changes to {product-title} group records. -==== diff --git a/modules/ldap-syncing-running-openshift.adoc b/modules/ldap-syncing-running-openshift.adoc deleted file mode 100644 index ef02d5bd371e..000000000000 --- a/modules/ldap-syncing-running-openshift.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing-groups.adoc - -[id="ldap-syncing-running-openshift_{context}"] -= Syncing {product-title} groups with the LDAP server - -You can sync all groups already in {product-title} that correspond to groups in the -LDAP server specified in the configuration file. - -.Prerequisites - -* Create a sync configuration file. - -.Procedure - -* To sync {product-title} groups with the LDAP server: -+ -[source,terminal] ----- -$ oc adm groups sync --type=openshift --sync-config=config.yaml --confirm ----- -+ -[NOTE] -==== -By default, all group synchronization operations are dry-run, so you -must set the `--confirm` flag on the `oc adm groups sync` command to make -changes to {product-title} group records. -==== diff --git a/modules/ldap-syncing-running-subset.adoc b/modules/ldap-syncing-running-subset.adoc deleted file mode 100644 index 437675d5acd7..000000000000 --- a/modules/ldap-syncing-running-subset.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing-groups.adoc - -[id="ldap-syncing-running-subset_{context}"] -= Syncing subgroups from the LDAP server with {product-title} - -You can sync a subset of LDAP groups with {product-title} using whitelist files, -blacklist files, or both. - -[NOTE] -==== -You can use any combination of blacklist files, whitelist files, or whitelist -literals. Whitelist and blacklist files must contain one unique group identifier -per line, and you can include whitelist literals directly in the command itself. -These guidelines apply to groups found on LDAP servers as well as groups already -present in {product-title}. -==== - -.Prerequisites - -* Create a sync configuration file. - -.Procedure - -* To sync a subset of LDAP groups with {product-title}, use any the following commands: -+ -[source,terminal] ----- -$ oc adm groups sync --whitelist=<whitelist_file> \ - --sync-config=config.yaml \ - --confirm ----- -+ -[source,terminal] ----- -$ oc adm groups sync --blacklist=<blacklist_file> \ - --sync-config=config.yaml \ - --confirm ----- -+ -[source,terminal] ----- -$ oc adm groups sync <group_unique_identifier> \ - --sync-config=config.yaml \ - --confirm ----- -+ -[source,terminal] ----- -$ oc adm groups sync <group_unique_identifier> \ - --whitelist=<whitelist_file> \ - --blacklist=<blacklist_file> \ - --sync-config=config.yaml \ - --confirm ----- -+ -[source,terminal] ----- -$ oc adm groups sync --type=openshift \ - --whitelist=<whitelist_file> \ - --sync-config=config.yaml \ - --confirm ----- -+ -[NOTE] -==== -By default, all group synchronization operations are dry-run, so you -must set the `--confirm` flag on the `oc adm groups sync` command to make -changes to {product-title} group records. -==== diff --git a/modules/ldap-syncing-running.adoc b/modules/ldap-syncing-running.adoc deleted file mode 100644 index 67b9c7e31a9f..000000000000 --- a/modules/ldap-syncing-running.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing-groups.adoc - -[id="ldap-syncing-running_{context}"] -= Running LDAP sync - -Once you have created a sync configuration file, -you can begin to sync. {product-title} allows administrators to perform a number of -different sync types with the same server. - diff --git a/modules/ldap-syncing-spec.adoc b/modules/ldap-syncing-spec.adoc deleted file mode 100644 index d0cab2ef3feb..000000000000 --- a/modules/ldap-syncing-spec.adoc +++ /dev/null @@ -1,250 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/ldap-syncing.adoc - -[id="ldap-syncing-spec_{context}"] -= LDAP sync configuration specification - -The object specification for the configuration file is below. Note that the different schema -objects have different fields. For example, v1.ActiveDirectoryConfig has no `groupsQuery` -field whereas v1.RFC2307Config and v1.AugmentedActiveDirectoryConfig both do. - -[IMPORTANT] -==== -There is no support for binary attributes. All attribute data coming from the -LDAP server must be in the format of a UTF-8 encoded string. For example, never -use a binary attribute, such as `objectGUID`, as an ID attribute. You must use -string attributes, such as `sAMAccountName` or `userPrincipalName`, instead. -==== - -[[sync-ldap-v1-ldapsyncconfig]] -== v1.LDAPSyncConfig - -`LDAPSyncConfig` holds the necessary configuration options to define an LDAP -group sync. - -[options="header"] -|=== -|Name |Description |Schema - -|`kind` -|String value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: link:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds[] -|string - -|`apiVersion` -|Defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: link:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources[] -|string - -|`url` -|Host is the scheme, host and port of the LDAP server to connect to: `scheme://host:port` -|string - -|`bindDN` -|Optional DN to bind to the LDAP server with. -|string - -|`bindPassword` -|Optional password to bind with during the search phase. |v1.StringSource - -|`insecure` -|If `true`, indicates the connection should not use TLS. If `false`, `ldaps://` URLs connect using TLS, and `ldap://` URLs are upgraded to a TLS connection using StartTLS as specified in link:https://tools.ietf.org/html/rfc2830[]. If you set `insecure` to `true`, you cannot use `ldaps://` URL schemes. -|boolean - -|`ca` -|Optional trusted certificate authority bundle to use when making requests to the server. If empty, the default system roots are used. -|string - -|`groupUIDNameMapping` -|Optional direct mapping of LDAP group UIDs to {product-title} group names. -|object - -|`rfc2307` -|Holds the configuration for extracting data from an LDAP server set up in a fashion similar to RFC2307: first-class group and user entries, with group membership determined by a multi-valued attribute on the group entry listing its members. -|v1.RFC2307Config - -|`activeDirectory` -|Holds the configuration for extracting data from an LDAP server set up in a fashion similar to that used in Active Directory: first-class user entries, with group membership determined by a multi-valued attribute on members listing groups they are a member of. -|v1.ActiveDirectoryConfig - -|`augmentedActiveDirectory` -|Holds the configuration for extracting data from an LDAP server set up in a fashion similar to that used in Active Directory as described above, with one addition: first-class group entries exist and are used to hold metadata but not group membership. -|v1.AugmentedActiveDirectoryConfig -|=== - -[[sync-ldap-v1-stringsource]] -== v1.StringSource - -`StringSource` allows specifying a string inline, or externally via environment -variable or file. When it contains only a string value, it marshals to a simple -JSON string. - -[options="header"] -|=== -|Name |Description |Schema - -|`value` -|Specifies the cleartext value, or an encrypted value if `keyFile` is specified. -|string - -|`env` -|Specifies an environment variable containing the cleartext value, or an -encrypted value if the `keyFile` is specified. -|string - -|`file` -|References a file containing the cleartext value, or an encrypted value if a `keyFile` is specified. -|string - -|`keyFile` -|References a file containing the key to use to decrypt the value. -|string -|=== - -[[sync-ldap-v1-ldapquery]] -== v1.LDAPQuery - -`LDAPQuery` holds the options necessary to build an LDAP query. - -[options="header"] -|=== -|Name |Description |Schema - -|`baseDN` -|DN of the branch of the directory where all searches should start from. -|string - -|`scope` -|The optional scope of the search. Can be `base`: only the base object, `one`: -all objects on the base level, `sub`: the entire subtree. Defaults to `sub` -if not set. -|string - -|`derefAliases` -|The optional behavior of the search with regards to alisases. Can be `never`: -never dereference aliases, `search`: only dereference in searching, `base`: -only dereference in finding the base object, `always`: always dereference. -Defaults to `always` if not set. -|string - -|`timeout` -|Holds the limit of time in seconds that any request to the server can remain outstanding before the wait for a response is given up. If this is `0`, no client-side limit is imposed. -|integer - -|`filter` -|A valid LDAP search filter that retrieves all relevant entries from the LDAP server with the base DN. -|string - -|`pageSize` -|Maximum preferred page size, measured in LDAP entries. A page size of `0` means no paging will be done. -|integer -|=== - -[[sync-ldap-v1-rfc2307config]] -== v1.RFC2307Config - -`RFC2307Config` holds the necessary configuration options to define how an LDAP -group sync interacts with an LDAP server using the RFC2307 schema. - -[options="header"] -|=== -|Name |Description |Schema - -|`groupsQuery` -|Holds the template for an LDAP query that returns group entries. -|v1.LDAPQuery - -|`groupUIDAttribute` -|Defines which attribute on an LDAP group entry will be interpreted as its unique identifier. (`ldapGroupUID`) -|string - -|`groupNameAttributes` -|Defines which attributes on an LDAP group entry will be interpreted as its name to use for an {product-title} group. -|string array - -|`groupMembershipAttributes` -|Defines which attributes on an LDAP group entry will be interpreted as its members. The values contained in those attributes must be queryable by your `UserUIDAttribute`. -|string array - -|`usersQuery` -|Holds the template for an LDAP query that returns user entries. -|v1.LDAPQuery - -|`userUIDAttribute` -|Defines which attribute on an LDAP user entry will be interpreted as its unique identifier. It must correspond to values that will be found from the `GroupMembershipAttributes`. -|string - -|`userNameAttributes` -|Defines which attributes on an LDAP user entry will be used, in order, as its {product-title} user name. The first attribute with a non-empty value is used. This should match your `PreferredUsername` setting for your `LDAPPasswordIdentityProvider`. The attribute to use as the name of the user in the {product-title} group -record. `mail` or `sAMAccountName` are preferred choices in most installations. -|string array - -|`tolerateMemberNotFoundErrors` -|Determines the behavior of the LDAP sync job when missing user entries are encountered. If `true`, an LDAP query for users that does not find any will be tolerated and an only and error will be logged. If `false`, the LDAP sync job will fail if a query for users doesn't find any. The default value is `false`. Misconfigured LDAP sync jobs with this flag set to `true` can cause group membership to be removed, so it is recommended to use this flag with caution. -|boolean - -|`tolerateMemberOutOfScopeErrors` -|Determines the behavior of the LDAP sync job when out-of-scope user entries are encountered. If `true`, an LDAP query for a user that falls outside of the base DN given for the all user query will be tolerated and only an error will be logged. If `false`, the LDAP sync job will fail if a user query would search outside of the base DN specified by the all user query. Misconfigured LDAP sync jobs with this flag set to `true` can result in groups missing users, so it is recommended to use this flag with caution. -|boolean -|=== - -[[sync-ldap-v1-activedirectoryconfig]] -== v1.ActiveDirectoryConfig - -`ActiveDirectoryConfig` holds the necessary configuration options to define how -an LDAP group sync interacts with an LDAP server using the Active Directory -schema. - -[options="header"] -|=== -|Name |Description |Schema - -|`usersQuery` -|Holds the template for an LDAP query that returns user entries. -|v1.LDAPQuery - -|`userNameAttributes` -|Defines which attributes on an LDAP user entry will be interpreted as its {product-title} user name. The attribute to use as the name of the user in the {product-title} group -record. `mail` or `sAMAccountName` are preferred choices in most installations. -|string array - -|`groupMembershipAttributes` -|Defines which attributes on an LDAP user entry will be interpreted as the groups it is a member of. -|string array -|=== - -[[sync-ldap-v1-augmentedactivedirectoryconfig]] -== v1.AugmentedActiveDirectoryConfig - -`AugmentedActiveDirectoryConfig` holds the necessary configuration options to -define how an LDAP group sync interacts with an LDAP server using the augmented -Active Directory schema. - -[options="header"] -|=== -|Name |Description |Schema - -|`usersQuery` -|Holds the template for an LDAP query that returns user entries. -|v1.LDAPQuery - -|`userNameAttributes` -|Defines which attributes on an LDAP user entry will be interpreted as its {product-title} user name. The attribute to use as the name of the user in the {product-title} group -record. `mail` or `sAMAccountName` are preferred choices in most installations. -|string array - -|`groupMembershipAttributes` -|Defines which attributes on an LDAP user entry will be interpreted as the groups it is a member of. -|string array - -|`groupsQuery` -|Holds the template for an LDAP query that returns group entries. -|v1.LDAPQuery - -|`groupUIDAttribute` -|Defines which attribute on an LDAP group entry will be interpreted as its unique identifier. (`ldapGroupUID`) -|string - -|`groupNameAttributes` -|Defines which attributes on an LDAP group entry will be interpreted as its name to use for an {product-title} group. -|string array -|=== diff --git a/modules/limiting-the-amount-of-data-visible-in-the-compliance-dashboard.adoc b/modules/limiting-the-amount-of-data-visible-in-the-compliance-dashboard.adoc new file mode 100644 index 000000000000..c40fac5d6203 --- /dev/null +++ b/modules/limiting-the-amount-of-data-visible-in-the-compliance-dashboard.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="limiting-the-amount-of-data-visible-in-the-compliance-dashboard_{context}"] += Limiting the amount of data visible in the compliance dashboard + +By filtering the compliance data, you can focus your attention on a subset of clusters, industry standards, passed or failed controls, and limit the amount of data visible in the compliance dashboard. + +.Procedure + +. In the {product-title-short} portal, click *Compliance -> Dashboard*. +. Click either the *clusters*, *namespaces*, or *nodes* tab to open the details page. +. Enter your filtering criteria in the search bar, and then click *Enter*. diff --git a/modules/listing-alerts-that-are-firing.adoc b/modules/listing-alerts-that-are-firing.adoc deleted file mode 100644 index 9dc286438791..000000000000 --- a/modules/listing-alerts-that-are-firing.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc - -[id="listing-alerts-that-are-firing_{context}"] -= Listing alerts that are firing - -Alerts provide notifications when a set of defined conditions are true in an {product-title} cluster. You can review the alerts that are firing in your cluster by using the Alerting UI in the {product-title} web console. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. In the *Administrator* perspective, navigate to the *Monitoring* -> *Alerting* -> *Alerts* page. - -. Review the alerts that are firing, including their *Severity*, *State*, and *Source*. - -. Select an alert to view more detailed information in the *Alert Details* page. diff --git a/modules/lock-and-unlock-process-baselines.adoc b/modules/lock-and-unlock-process-baselines.adoc new file mode 100644 index 000000000000..23521043e89f --- /dev/null +++ b/modules/lock-and-unlock-process-baselines.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: PROCEDURE +[id="lock-and-unlock-process-baselines_{context}"] += Locking and unlocking the process baselines + +[role="_abstract"] +You can *Lock* the baseline to trigger violations for all processes not listed in the baseline and *Unlock* the baseline to stop triggering violations. + +.Procedure +. In the {product-title-short} portal, select *Risk* from the navigation menu. +. Select a deployment from the list of deployments in the default *Risk* view. +Deployment details open in a panel on the right. +. In the *Deployment* details panel, select the *Process Discovery* tab. +. Under the *Spec Container baselines* section: +* Click the *Lock* icon to trigger violations for processes that are not in the baseline. +* Click the *Unlock* icon to stop triggering violations for processes that are not in the baseline. diff --git a/modules/log-in-using-client-certificate.adoc b/modules/log-in-using-client-certificate.adoc new file mode 100644 index 000000000000..b3f48ca16d4a --- /dev/null +++ b/modules/log-in-using-client-certificate.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/enable-pki-authentication.adoc +:_mod-docs-content-type: PROCEDURE +[id="log-in-using-client-certificate_{context}"] += Logging in by using a client certificate + +After you configure PKI authentication, users see a certificate prompt in the {product-title-short} portal login page. +The prompt only shows up if a client certificate trusted by the configured root CA is installed on the user's system. + +Use the procedure described in this section to log in by using a client certificate. + +.Procedure +. Open the {product-title-short} portal. +. Select a certificate in the browser prompt. +. On the login page, select the authentication provider name option to log in with a certificate. +If you do not want to log in by using the certificate, you can also log in by using the administrator password or another login method. + +[NOTE] +==== +Once you use a client certificate to log into the {product-title-short} portal, you cannot log in with a different certificate unless you restart your browser. +==== diff --git a/modules/logging-in-by-using-the-web-console.adoc b/modules/logging-in-by-using-the-web-console.adoc deleted file mode 100644 index 9e710d20b432..000000000000 --- a/modules/logging-in-by-using-the-web-console.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc -// *installing/installing_aws/installing-aws-user-infra.adoc -// *installing/installing_aws/installing-restricted-networks-aws.adoc - -[id="logging-in-by-using-the-web-console_{context}"] -= Logging in to the cluster by using the web console - -The `kubeadmin` user exists by default after an {product-title} installation. You can log into your cluster as the `kubeadmin` user by using the {product-title} web console. - -.Prerequisites - -* You have access to the installation host. -* You completed a cluster installation and all cluster Operators are available. - -.Procedure - -. Obtain the password for the `kubeadmin` user from the `kubeadmin-password` file on the installation host: -+ -[source,terminal] ----- -$ cat <installation_directory>/auth/kubeadmin-password ----- -+ -[NOTE] -==== -Alternatively, you can obtain the `kubeadmin` password from the `<installation_directory>/.openshift_install.log` log file on the installation host. -==== - -. List the {product-title} web console route: -+ -[source,terminal] ----- -$ oc get routes -n openshift-console | grep 'console-openshift' ----- -+ -[NOTE] -==== -Alternatively, you can obtain the {product-title} route from the `<installation_directory>/.openshift_install.log` log file on the installation host. -==== -+ -.Example output -[source,terminal] ----- -console console-openshift-console.apps.<cluster_name>.<base_domain> console https reencrypt/Redirect None ----- - -. Navigate to the route detailed in the output of the preceding command in a web browser and log in as the `kubeadmin` user. diff --git a/modules/logging-into-a-cluster-after-installation.adoc b/modules/logging-into-a-cluster-after-installation.adoc deleted file mode 100644 index 66312ca83176..000000000000 --- a/modules/logging-into-a-cluster-after-installation.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc - -[id="logging-into-a-cluster-after-installation_{context}"] -= Logging into a cluster after an installation - -After an installation, the `kubeadmin` user exists by default. You can log into your cluster as the `kubeadmin` user by using the CLI or the {product-title} web console. - - diff --git a/modules/low-sev-security-policies.adoc b/modules/low-sev-security-policies.adoc new file mode 100644 index 000000000000..15f78dc7c167 --- /dev/null +++ b/modules/low-sev-security-policies.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/default-security-policies.adoc +:_mod-docs-content-type: REFERENCE +[id="low-sev-security-policies_{context}"] += Low severity security policies + +//// +In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly. + +Be sure to include a line break between the title and the module introduction. +//// + +[role="_abstract"] +The following table lists the default security policies in {product-title} that are of low severity. The policies are organized by lifecycle stage. + +.Low severity security policies +[options="header"] +|==== +|Life cycle stage |Name |Description | Status +|Build or Deploy |90-Day Image Age |Alerts when a deployment has not been updated in 90 days. |Enabled +|Build or Deploy |ADD Command used instead of COPY |Alerts when a deployment uses an ADD command. |Disabled +|Build or Deploy |Alpine Linux Package Manager (apk) in Image |Alerts when a deployment includes the Alpine Linux package manager (apk). |Enabled +|Build or Deploy |Curl in Image |Alerts when a deployment includes curl. |Disabled +|Build or Deploy |Docker CIS 4.1: Ensure That a User for the Container Has Been Created |Ensures that containers are running as non-root users. |Enabled +|Build or Deploy |Docker CIS 4.7: Alert on Update Instruction |Ensures that update instructions are not used alone in the Dockerfile. |Enabled +|Build or Deploy |Insecure specified in CMD |Alerts when a deployment uses 'insecure' in the command. |Enabled +|Build or Deploy |Latest tag |Alerts when a deployment includes images that use the 'latest' tag. |Enabled +|Build or Deploy |Red{nbsp}Hat Package Manager in Image |Alerts when a deployment includes components of the Red{nbsp}Hat, Fedora, or CentOS package management system. |Enabled +|Build or Deploy |Required Image Label |Alerts when a deployment includes images that are missing the specified label. |Disabled +|Build or Deploy |Ubuntu Package Manager Execution |Detects the usage of the Ubuntu package management system. |Enabled +|Build or Deploy |Ubuntu Package Manager in Image |Alerts when a deployment includes components of the Debian or Ubuntu package management system in the image. |Enabled +|Build or Deploy |Wget in Image | Alerts when a deployment includes wget. |Disabled +|Deploy |Drop All Capabilities |Alerts when a deployment does not drop all capabilities. |Disabled +|Deploy |Improper Usage of Orchestrator Secrets Volume |Alerts when a deployment uses a Dockerfile with 'VOLUME /run/secrets'. |Enabled +|Deploy |Kubernetes Dashboard Deployed |Alerts when a Kubernetes dashboard service is detected. |Enabled +|Deploy |Required Annotation: Email |Alerts when a deployment is missing the 'email' annotation. |Disabled +|Deploy |Required Annotation: Owner/Team |Alerts when a deployment is missing the 'owner' or 'team' annotation. |Disabled +|Deploy |Required Label: Owner/Team |Alerts when a deployment is missing the 'owner' or 'team' label. |Disabled +|Runtime |Alpine Linux Package Manager Execution |Alerts when the Alpine Linux package manager (apk) is run at run time. |Enabled +|Runtime |chkconfig Execution |Detects the usage of the ckconfig service manager, which is typically not used in a container. |Enabled +|Runtime |Compiler Tool Execution |Alerts when binary files that compile software are run at run time. |Enabled +|Runtime |Red{nbsp}Hat Package Manager Execution |Alerts when Red{nbsp}Hat, Fedora, or CentOS package manager programs are run at run time. |Enabled +|Runtime |Shell Management |Alerts when commands are run to add or remove a shell. |Disabled +|Runtime |systemctl Execution |Detects the usage of the systemctl service manager. |Enabled +|Runtime |systemd Execution |Detects the usage of the systemd service manager. |Enabled +|==== diff --git a/modules/machine-api-operator.adoc b/modules/machine-api-operator.adoc deleted file mode 100644 index 58679ccd0cfc..000000000000 --- a/modules/machine-api-operator.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="machine-api-operator_{context}"] -= Machine API Operator - -[discrete] -== Purpose - -The Machine API Operator manages the lifecycle of specific purpose custom resource definitions (CRD), controllers, and RBAC objects that extend the Kubernetes API. This declares the desired state of machines in a cluster. - -[discrete] -== Project - -link:https://github.com/openshift/machine-api-operator[machine-api-operator] - -[discrete] -== CRDs - -* `MachineSet` -* `Machine` -* `MachineHealthCheck` diff --git a/modules/machine-api-overview.adoc b/modules/machine-api-overview.adoc deleted file mode 100644 index de39d0901dc5..000000000000 --- a/modules/machine-api-overview.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating_machinesets/creating-machineset-aws.adoc -// * machine_management/creating_machinesets/creating-machineset-azure.adoc -// * machine_management/creating_machinesets/creating-machineset-gcp.adoc -// * machine_management/creating_machinesets/creating-machineset-osp.adoc -// * machine_management/creating_machinesets/creating-machineset-vsphere.adoc -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.adoc -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-azure.adoc -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc - -[id="machine-api-overview_{context}"] -= Machine API overview - -The Machine API is a combination of primary resources that are based on the upstream Cluster API project and custom {product-title} resources. - -For {product-title} {product-version} clusters, the Machine API performs all node host provisioning management actions after the cluster installation finishes. Because of this system, {product-title} {product-version} offers an elastic, dynamic provisioning method on top of public or private cloud infrastructure. - -The two primary resources are: - -Machines:: A fundamental unit that describes the host for a Node. A machine has a `providerSpec` specification, which describes the types of compute nodes that are offered for different cloud platforms. For example, a machine type for a worker node on Amazon Web Services (AWS) might define a specific machine type and required metadata. - -Machine sets:: `MachineSet` resources are groups of machines. Machine sets are to machines as replica sets are to pods. If you need more machines or must scale them down, you change the *replicas* field on the machine set to meet your compute need. - -The following custom resources add more capabilities to your cluster: - -Machine autoscaler:: The `MachineAutoscaler` resource automatically scales machines in a cloud. You can set the minimum and maximum scaling boundaries for nodes in a specified machine set, and the machine autoscaler maintains that range of nodes. The `MachineAutoscaler` object takes effect after a `ClusterAutoscaler` object exists. Both `ClusterAutoscaler` and `MachineAutoscaler` resources are made available by the `ClusterAutoscalerOperator` object. - -Cluster autoscaler:: This resource is based on the upstream cluster autoscaler project. In the {product-title} implementation, it is integrated with the Machine API by extending the machine set API. You can set cluster-wide scaling limits for resources such as cores, nodes, memory, GPU, and so on. You can set the priority so that the cluster prioritizes pods so that new nodes are not brought online for less important pods. You can also set the scaling policy so that you can scale up nodes but not scale them down. - -Machine health check:: The `MachineHealthCheck` resource detects when a machine is unhealthy, deletes it, and, on supported platforms, makes a new machine. - -In {product-title} version 3.11, you could not roll out a multi-zone architecture easily because the cluster did not manage machine provisioning. Beginning with {product-title} version 4.1, this process is easier. Each machine set is scoped to a single zone, so the installation program sends out machine sets across availability zones on your behalf. And then because your compute is dynamic, and in the face of a zone failure, you always have a zone for when you must rebalance your machines. The autoscaler provides best-effort balancing over the life of a cluster. diff --git a/modules/machine-autoscaler-about.adoc b/modules/machine-autoscaler-about.adoc deleted file mode 100644 index 9c446b48d0a7..000000000000 --- a/modules/machine-autoscaler-about.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/applying-autoscaling.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="machine-autoscaler-about_{context}"] -= About the machine autoscaler - -The machine autoscaler adjusts the number of Machines in the machine sets that you deploy in an {product-title} cluster. You can scale both the default `worker` machine set and any other machine sets that you create. The machine autoscaler makes more Machines when the cluster runs out of resources to support more deployments. Any changes to the values in `MachineAutoscaler` resources, such as the minimum or maximum number of instances, are immediately applied to the machine set they target. - -[IMPORTANT] -==== -You must deploy a machine autoscaler for the cluster autoscaler to scale your machines. The cluster autoscaler uses the annotations on machine sets that the machine autoscaler sets to determine the resources that it can scale. If you define a cluster autoscaler without also defining machine autoscalers, the cluster autoscaler will never scale your cluster. -==== diff --git a/modules/machine-autoscaler-cr.adoc b/modules/machine-autoscaler-cr.adoc deleted file mode 100644 index a2eb209b19e4..000000000000 --- a/modules/machine-autoscaler-cr.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/applying-autoscaling.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="machine-autoscaler-cr_{context}"] -= `MachineAutoscaler` resource definition - -This `MachineAutoscaler` resource definition shows the parameters and sample values for the machine autoscaler. - - -[source,yaml] ----- -apiVersion: "autoscaling.openshift.io/v1beta1" -kind: "MachineAutoscaler" -metadata: - name: "worker-us-east-1a" <1> - namespace: "openshift-machine-api" -spec: - minReplicas: 1 <2> - maxReplicas: 12 <3> - scaleTargetRef: <4> - apiVersion: machine.openshift.io/v1beta1 - kind: MachineSet <5> - name: worker-us-east-1a <6> ----- -<1> Specify the machine autoscaler name. To make it easier to identify which machine set this machine autoscaler scales, specify or include the name of the machine set to scale. The machine set name takes the following form: `<clusterid>-<machineset>-<aws-region-az>` -<2> Specify the minimum number machines of the specified type that must remain in the specified zone after the cluster autoscaler initiates cluster scaling. If running in AWS, GCP, Azure, or {rh-openstack}, this value can be set to `0`. For other providers, do not set this value to `0`. -<3> Specify the maximum number machines of the specified type that the cluster autoscaler can deploy in the specified AWS zone after it initiates cluster scaling. Ensure that the `maxNodesTotal` value in the `ClusterAutoscaler` resource definition is large enough to allow the machine autoscaler to deploy this number of machines. -<4> In this section, provide values that describe the existing machine set to scale. -<5> The `kind` parameter value is always `MachineSet`. -<6> The `name` value must match the name of an existing machine set, as shown in the `metadata.name` parameter value. \ No newline at end of file diff --git a/modules/machine-config-daemon-metrics.adoc b/modules/machine-config-daemon-metrics.adoc deleted file mode 100644 index c63b1b96c767..000000000000 --- a/modules/machine-config-daemon-metrics.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes/nodes-nodes-machine-config-daemon-metrics.adoc - -[id="machine-config-daemon-metrics_{context}"] -= Machine Config Daemon metrics - -Beginning with {product-title} 4.3, the Machine Config Daemon provides a set of metrics. These metrics can be accessed using the Prometheus Cluster Monitoring stack. - -The following table describes this set of metrics. - -[NOTE] -==== -Metrics marked with `*` in the `Name` and `Description` columns represent serious errors that might cause performance problems. Such problems might prevent updates and upgrades from proceeding. -==== - -[NOTE] -==== -While some entries contain commands for getting specific logs, the most comprehensive set of logs is available using the `oc adm must-gather` command. -==== - -[cols="1,1,2,2", options="header"] -.MCO metrics -|=== -|Name -|Format -|Description -|Notes - -|mcd_host_os_and_version -|[]string{"os", "version"} -|Shows the OS that MCD is running on, such as RHCOS or RHEL. In case of RHCOS, the version is provided. -| - -|ssh_accessed -|counter -|Shows the number of successful SSH authentications into the node. -|The non-zero value shows that someone might have made manual changes to the node. Such changes might cause irreconcilable errors due to the differences between the state on the disk and the state defined in the machine configuration. - -|mcd_drain* -|{"drain_time", "err"} -|Logs errors received during failed drain. * -|While drains might need multiple tries to succeed, terminal failed drains prevent updates from proceeding. The `drain_time` metric, which shows how much time the drain took, might help with troubleshooting. - -For further investigation, see the logs by running: - -`$ oc logs -f -n openshift-machine-config-operator machine-config-daemon-<hash> -c machine-config-daemon` - -|mcd_pivot_err* -|[]string{"pivot_target", "err"} -|Logs errors encountered during pivot. * -|Pivot errors might prevent OS upgrades from proceeding. - -For further investigation, run this command to access the node and see all its logs: - -`$ oc debug node/<node> -- chroot /host journalctl -u pivot.service` - -Alternatively, you can run this command to only see the logs from the `machine-config-daemon` container: - -`$ oc logs -f -n openshift-machine-config-operator machine-config-daemon-<hash> -c machine-config-daemon` - -|mcd_state -|[]string{"state", "reason"} -|State of Machine Config Daemon for the indicated node. Possible states are "Done", "Working", and "Degraded". In case of "Degraded", the reason is included. -|For further investigation, see the logs by running: - -`$ oc logs -f -n openshift-machine-config-operator machine-config-daemon-<hash> -c machine-config-daemon` - -|mcd_kubelet_state* -|[]string{"err"} -|Logs kubelet health failures. * -|This is expected to be empty, with failure count of 0. If failure count exceeds 2, the error indicating threshold is exceeded. This indicates a possible issue with the health of the kubelet. - -For further investigation, run this command to access the node and see all its logs: - -`$ oc debug node/<node> -- chroot /host journalctl -u kubelet` - -|mcd_reboot_err* -|[]string{"message", "err"} -|Logs the failed reboots and the corresponding errors. * -|This is expected to be empty, which indicates a successful reboot. - -For further investigation, see the logs by running: - -`$ oc logs -f -n openshift-machine-config-operator machine-config-daemon-<hash> -c machine-config-daemon` - -|mcd_update_state -|[]string{"config", "err"} -|Logs success or failure of configuration updates and the corresponding errors. -|The expected value is `rendered-master/rendered-worker-XXXX`. If the update fails, an error is present. - -For further investigation, see the logs by running: - -`$ oc logs -f -n openshift-machine-config-operator machine-config-daemon-<hash> -c machine-config-daemon` -|=== diff --git a/modules/machine-config-operator.adoc b/modules/machine-config-operator.adoc deleted file mode 100644 index 6ea569e4250c..000000000000 --- a/modules/machine-config-operator.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="machine-config-operator_{context}"] -= Machine Config Operator - -[discrete] -== Purpose - -The Machine Config Operator manages and applies configuration and updates of the base operating system and container runtime, including everything between the kernel and kubelet. - -There are four components: - -* `machine-config-server`: Provides Ignition configuration to new machines joining the cluster. -* `machine-config-controller`: Coordinates the upgrade of machines to the desired configurations defined by a `MachineConfig` object. Options are provided to control the upgrade for sets of machines individually. -* `machine-config-daemon`: Applies new machine configuration during update. Validates and verifies the state of the machine to the requested machine configuration. -* `machine-config`: Provides a complete source of machine configuration at installation, first start up, and updates for a machine. - -[discrete] -== Project - -link:https://github.com/openshift/machine-config-operator[openshift-machine-config-operator] diff --git a/modules/machine-config-overview.adoc b/modules/machine-config-overview.adoc deleted file mode 100644 index 06d2bd56120a..000000000000 --- a/modules/machine-config-overview.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="machine-config-overview-{context}"] -= Machine config overview - -The Machine Config Operator (MCO) manages updates to systemd, CRI-O and Kubelet, the kernel, Network Manager and other system features. It also offers a `MachineConfig` CRD that can write configuration files onto the host (see link:https://github.com/openshift/machine-config-operator#machine-config-operator[machine-config-operator]). Understanding what MCO does and how it interacts with other components is critical to making advanced, system-level changes to an {product-title} cluster. Here are some things you should know about MCO, machine configs, and how they are used: - -* A machine config can make a specific change to a file or service on the operating system of each system representing a pool of {product-title} nodes. - -* MCO applies changes to operating systems in pools of machines. All {product-title} clusters start with worker and master node pools. By adding more role labels, you can configure custom pools of nodes. For example, you can set up a custom pool of worker nodes that includes particular hardware features needed by an application. However, examples in this section focus on changes to the default pool types. - -* Some machine configuration must be in place before {product-title} is installed to disk. In most cases, this can be accomplished by creating -a machine config that is injected directly into the {product-title} installer process, instead of running as a post-installation machine config. In other cases, you might need to do bare metal installation where you pass kernel arguments at {product-title} installer start-up, to do such things as setting per-node individual IP addresses or advanced disk partitioning. - -* MCO manages items that are set in machine configs. Manual changes you do to your systems will not be overwritten by MCO, unless MCO is explicitly told to manage a conflicting file. In other words, MCO only makes specific updates you request, it does not claim control over the whole node. - -* Manual changes to nodes are strongly discouraged. If you need to decommission a node and start a new one, those direct changes would be lost. - -* MCO is only supported for writing to files in `/etc` and `/var` directories, although there are symbolic links to some directories that can be writeable by being symbolically linked to one of those areas. The `/opt` directory is an example. - -* Ignition is the configuration format used in MachineConfigs. See the link:https://coreos.github.io/ignition/configuration-v3_2/[Ignition Configuration Specification v3.2.0] for details. - -* Although Ignition config settings can be delivered directly at {product-title} installation time, and are formatted in the same way that MCO delivers Ignition configs, MCO has no way of seeing what those original Ignition configs are. Therefore, you should wrap Ignition config settings into a machine config before deploying them. - -* When a file managed by MCO changes outside of MCO, the Machine Config Daemon (MCD) sets the node as `degraded`. It will not overwrite the -offending file, however, and should continue to operate in a `degraded` state. - -* A key reason for using a machine config is that it will be applied when you spin up new nodes for a pool in your {product-title} cluster. The `machine-api-operator` provisions a new machine and MCO configures it. - -MCO uses link:https://coreos.github.io/ignition/[Ignition] as the configuration format. {product-title} 4.6 moved from Ignition config specification version 2 to version 3. - -== What can you change with machine configs? -The kinds of components that MCO can change include: - -* **config**: Create Ignition config objects (see the link:https://coreos.github.io/ignition/configuration-v3_2/[Ignition configuration specification]) to do things like modify files, systemd services, and other features on {product-title} machines, including: -- **Configuration files**: Create or overwrite files in the `/var` or `/etc` directory. -- **systemd units**: Create and set the status of a systemd service or add to an existing systemd service by dropping in additional settings. -- **users and groups**: Change ssh keys in the passwd section post-installation. -* **kernelArguments**: Add arguments to the kernel command line when {product-title} nodes boot. -* **kernelType**: Optionally identify a non-standard kernel to use instead of the standard kernel. Use `realtime` to use the RT kernel (for RAN). This is only supported on select platforms. -ifndef::openshift-origin[] -* **fips**: Enable link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/security_hardening/index#using-the-system-wide-cryptographic-policies_security-hardening[FIPS] mode. FIPS should be set at installation-time setting and not a post-installation procedure. -endif::openshift-origin[] -* **extensions**: Extend {op-system} features by adding selected pre-packaged software. For this feature, available extensions include link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/security_hardening/index#protecting-systems-against-intrusive-usb-devices_security-hardening[usbguard] and kernel modules. -* **Custom resources (for `ContainerRuntime` and `Kubelet`)**: Outside of machine configs, MCO manages two special custom resources for modifying CRI-O container runtime settings (`ContainerRuntime` CR) and the Kubelet service (`Kubelet` CR). - -The MCO is not the only Operator that can change operating system components on {product-title} nodes. Other Operators can modify operating system-level features as well. One example is the Node Tuning Operator, which allows you to do node-level tuning through Tuned daemon profiles. - -Tasks for the MCO configuration that can be done post-installation are included in the following procedures. See descriptions of {op-system} bare metal installation for system configuration tasks that must be done during or before {product-title} installation. - -== Project - -See the link:https://github.com/openshift/machine-config-operator[openshift-machine-config-operator] GitHub site for details. diff --git a/modules/machine-delete.adoc b/modules/machine-delete.adoc deleted file mode 100644 index 79d91a328eea..000000000000 --- a/modules/machine-delete.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/delete-machine.adoc -// * windows_containers/removing-windows-nodes.adoc - -[id="machine-delete_{context}"] -= Deleting a specific machine - -You can delete a specific machine. - -.Prerequisites - -* Install an {product-title} cluster. -* Install the OpenShift CLI (`oc`). -* Log into `oc` as a user with `cluster-admin` permission. - -.Procedure - -. View the machines that are in the cluster and identify the one to delete: -+ -[source,terminal] ----- -$ oc get machine -n openshift-machine-api ----- -+ -The command output contains a list of machines in the `<clusterid>-worker-<cloud_region>` format. - -. Delete the machine: -+ -[source,terminal] ----- -$ oc delete machine <machine> -n openshift-machine-api ----- - -+ -[IMPORTANT] -==== -By default, the machine controller tries to drain the node that is backed by the machine until it succeeds. In some situations, such as with a misconfigured pod disruption budget, the drain operation might not be able to succeed in preventing the machine from being deleted. You can skip draining the node by annotating "machine.openshift.io/exclude-node-draining" in a specific machine. If the machine being deleted belongs to a machine set, a new machine is immediately created to satisfy the specified number of replicas. -==== diff --git a/modules/machine-health-checks-about.adoc b/modules/machine-health-checks-about.adoc deleted file mode 100644 index 21384d84e5e8..000000000000 --- a/modules/machine-health-checks-about.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/deploying-machine-health-checks.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="machine-health-checks-about_{context}"] -= About machine health checks - -You can define conditions under which machines in a cluster are considered unhealthy by using a `MachineHealthCheck` resource. -Machines matching the conditions are automatically remediated. - -To monitor machine health, create a `MachineHealthCheck` custom resource (CR) that includes a label for the set of machines to monitor and a condition to check, such as staying in the `NotReady` status for 15 minutes or displaying a permanent condition in the node-problem-detector. - -The controller that observes a `MachineHealthCheck` CR checks for the condition that you defined. If a machine fails the health check, the machine is automatically deleted and a new one is created to take its place. When a machine is deleted, you see a `machine deleted` event. - -[NOTE] -==== -For machines with the master role, the machine health check reports the number of unhealthy nodes, but the machine is not deleted. For example: - -.Example output -[source,terminal] ----- -$ oc get machinehealthcheck example -n openshift-machine-api ----- -[source,terminal] ----- -NAME MAXUNHEALTHY EXPECTEDMACHINES CURRENTHEALTHY -example 40% 3 1 ----- - -To limit the disruptive impact of machine deletions, the controller drains and deletes only one node at a time. If there are more unhealthy machines than the `maxUnhealthy` threshold allows for in the targeted pool of machines, the controller stops deleting machines and you must manually intervene. -==== - -To stop the check, remove the custom resource. - -[id="machine-health-checks-bare-metal_{context}"] -== MachineHealthChecks on Bare Metal - -Machine deletion on bare metal cluster triggers reprovisioning of a bare metal host. -Usually bare metal reprovisioning is a lengthy process, during which the cluster -is missing compute resources and applications might be interrupted. -To change the default remediation process from machine deletion to host power-cycle, -annotate the MachineHealthCheck resource with the -`machine.openshift.io/remediation-strategy: external-baremetal` annotation. - -After you set the annotation, unhealthy machines are power-cycled by using -BMC credentials. - -[id="machine-health-checks-limitations_{context}"] -== Limitations when deploying machine health checks - -There are limitations to consider before deploying a machine health check: - -* Only machines owned by a machine set are remediated by a machine health check. -* Control plane machines are not currently supported and are not remediated if they are unhealthy. -* If the node for a machine is removed from the cluster, a machine health check considers the machine to be unhealthy and remediates it immediately. -* If the corresponding node for a machine does not join the cluster after the `nodeStartupTimeout`, the machine is remediated. -* A machine is remediated immediately if the `Machine` resource phase is `Failed`. diff --git a/modules/machine-health-checks-creating.adoc b/modules/machine-health-checks-creating.adoc deleted file mode 100644 index 5deeee61064c..000000000000 --- a/modules/machine-health-checks-creating.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/deploying-machine-health-checks.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="machine-health-checks-creating_{context}"] -= Creating a `MachineHealthCheck` resource - -You can create a `MachineHealthCheck` resource for all `MachineSets` in your cluster. -You should not create a `MachineHealthCheck` resource that targets control plane machines. - -.Prerequisites - -* Install the `oc` command line interface. - -.Procedure - -. Create a `healthcheck.yml` file that contains the definition of your machine health check. - -. Apply the `healthcheck.yml` file to your cluster: -+ -[source,terminal] ----- -$ oc apply -f healthcheck.yml ----- diff --git a/modules/machine-health-checks-resource.adoc b/modules/machine-health-checks-resource.adoc deleted file mode 100644 index c45dc1cf5c19..000000000000 --- a/modules/machine-health-checks-resource.adoc +++ /dev/null @@ -1,131 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/deploying-machine-health-checks.adoc -// * post_installation_configuration/node-tasks.adoc - - -[id="machine-health-checks-resource_{context}"] -= Sample `MachineHealthCheck` resource - -The `MachineHealthCheck` resource resembles one of the following YAML files: - -.`MachineHealthCheck` for bare metal -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineHealthCheck -metadata: - name: example <1> - namespace: openshift-machine-api - annotations: - machine.openshift.io/remediation-strategy: external-baremetal <2> -spec: - selector: - matchLabels: - machine.openshift.io/cluster-api-machine-role: <role> <3> - machine.openshift.io/cluster-api-machine-type: <role> <3> - machine.openshift.io/cluster-api-machineset: <cluster_name>-<label>-<zone> <4> - unhealthyConditions: - - type: "Ready" - timeout: "300s" <5> - status: "False" - - type: "Ready" - timeout: "300s" <5> - status: "Unknown" - maxUnhealthy: "40%" <6> - nodeStartupTimeout: "10m" <7> ----- - -<1> Specify the name of the machine health check to deploy. -<2> For bare metal clusters, you must include the `machine.openshift.io/remediation-strategy: external-baremetal` annotation in the `annotations` section to enable power-cycle remediation. With this remediation strategy, unhealthy hosts are rebooted instead of removed from the cluster. -<3> Specify a label for the machine pool that you want to check. -<4> Specify the machine set to track in `<cluster_name>-<label>-<zone>` format. For example, `prod-node-us-east-1a`. -<5> Specify the timeout duration for a node condition. If a condition is met for the duration of the timeout, the machine will be remediated. Long timeouts can result in long periods of downtime for a workload on an unhealthy machine. -<6> Specify the amount of unhealthy machines allowed in the targeted pool. This can be set as a percentage or an integer. -<7> Specify the timeout duration that a machine health check must wait for a node to join the cluster before a machine is determined to be unhealthy. - -[NOTE] -==== -The `matchLabels` are examples only; you must map your machine groups based on your specific needs. -==== - -.`MachineHealthCheck` for all other installation types -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineHealthCheck -metadata: - name: example <1> - namespace: openshift-machine-api -spec: - selector: - matchLabels: - machine.openshift.io/cluster-api-machine-role: <role> <2> - machine.openshift.io/cluster-api-machine-type: <role> <2> - machine.openshift.io/cluster-api-machineset: <cluster_name>-<label>-<zone> <3> - unhealthyConditions: - - type: "Ready" - timeout: "300s" <4> - status: "False" - - type: "Ready" - timeout: "300s" <4> - status: "Unknown" - maxUnhealthy: "40%" <5> - nodeStartupTimeout: "10m" <6> ----- -<1> Specify the name of the machine health check to deploy. -<2> Specify a label for the machine pool that you want to check. -<3> Specify the machine set to track in `<cluster_name>-<label>-<zone>` format. For example, `prod-node-us-east-1a`. -<4> Specify the timeout duration for a node condition. If a condition is met for the duration of the timeout, the machine will be remediated. Long timeouts can result in long periods of downtime for a workload on an unhealthy machine. -<5> Specify the amount of unhealthy machines allowed in the targeted pool. This can be set as a percentage or an integer. -<6> Specify the timeout duration that a machine health check must wait for a node to join the cluster before a machine is determined to be unhealthy. - -[NOTE] -==== -The `matchLabels` are examples only; you must map your machine groups based on your specific needs. -==== - -[id="machine-health-checks-short-circuiting_{context}"] -== Short-circuiting machine health check remediation - -Short circuiting ensures that machine health checks remediate machines only when the cluster is healthy. -Short-circuiting is configured through the `maxUnhealthy` field in the `MachineHealthCheck` resource. - -If the user defines a value for the `maxUnhealthy` field, -before remediating any machines, the `MachineHealthCheck` compares the value of `maxUnhealthy` -with the number of machines within its target pool that it has determined to be unhealthy. -Remediation is not performed if the number of unhealthy machines exceeds the `maxUnhealthy` limit. - -[IMPORTANT] -==== -If `maxUnhealthy` is not set, the value defaults to `100%` and the machines are remediated regardless of the state of the cluster. -==== - -The `maxUnhealthy` field can be set as either an integer or percentage. -There are different remediation implementations depending on the `maxUnhealthy` value. - -=== Setting `maxUnhealthy` by using an absolute value - -If `maxUnhealthy` is set to `2`: - -* Remediation will be performed if 2 or fewer nodes are unhealthy -* Remediation will not be performed if 3 or more nodes are unhealthy - -These values are independent of how many machines are being checked by the machine health check. - -=== Setting `maxUnhealthy` by using percentages - -If `maxUnhealthy` is set to `40%` and there are 25 machines being checked: - -* Remediation will be performed if 10 or fewer nodes are unhealthy -* Remediation will not be performed if 11 or more nodes are unhealthy - -If `maxUnhealthy` is set to `40%` and there are 6 machines being checked: - -* Remediation will be performed if 2 or fewer nodes are unhealthy -* Remediation will not be performed if 3 or more nodes are unhealthy - -[NOTE] -==== -The allowed number of machines is rounded down when the percentage of `maxUnhealthy` machines that are checked is not a whole number. -==== diff --git a/modules/machine-user-infra-machines-iso.adoc b/modules/machine-user-infra-machines-iso.adoc deleted file mode 100644 index 946b17bf673d..000000000000 --- a/modules/machine-user-infra-machines-iso.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_infra/adding-bare-metal-compute-user-infra.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="machine-user-infra-machines-iso_{context}"] -= Creating more {op-system} machines using an ISO image - -You can create more {op-system-first} compute machines for your bare metal cluster by using an ISO image to create the machines. - -.Prerequisites - -* Obtain the URL of the Ignition config file for the compute machines for your cluster. You uploaded this file to your HTTP server during installation. - -.Procedure - -. Use the ISO file to install {op-system} on more compute machines. Use the same method that you used when you created machines before you installed the cluster: -** Burn the ISO image to a disk and boot it directly. -** Use ISO redirection with a LOM interface. - -. After the instance boots, press the `TAB` or `E` key to edit the kernel command line. -. Add the parameters to the kernel command line: -+ -[source,terminal] ----- -coreos.inst.install_dev=sda <1> -coreos.inst.ignition_url=http://example.com/worker.ign <2> ----- -<1> Specify the block device of the system to install to. -<2> Specify the URL of the compute Ignition config file. Only HTTP and HTTPS protocols are supported. - -. Press `Enter` to complete the installation. After {op-system} installs, the system reboots. After the system reboots, it applies the Ignition config file that you specified. - -. Continue to create more compute machines for your cluster. diff --git a/modules/machine-user-infra-machines-pxe.adoc b/modules/machine-user-infra-machines-pxe.adoc deleted file mode 100644 index f4a83a419e47..000000000000 --- a/modules/machine-user-infra-machines-pxe.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_infra/adding-bare-metal-compute-user-infra.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="machine-user-infra-machines-pxe_{context}"] -= Creating more {op-system} machines by PXE or iPXE booting - -You can create more {op-system-first} compute machines for your bare metal cluster by using PXE or iPXE booting. - -.Prerequisites - -* Obtain the URL of the Ignition config file for the compute machines for your cluster. You uploaded this file to your HTTP server during installation. -* Obtain the URLs of the {op-system} ISO image, compressed metal BIOS, `kernel`, and `initramfs` files that you uploaded to your HTTP server during cluster installation. -* You have access to the PXE booting infrastructure that you used to create the machines for your {product-title} cluster during installation. The machines must boot from their local disks after {op-system} is installed on them. -* If you use UEFI, you have access to the `grub.conf` file that you modified during {product-title} installation. - -.Procedure - -. Confirm that your PXE or iPXE installation for the {op-system} images is correct. - -** For PXE: -+ ----- -DEFAULT pxeboot -TIMEOUT 20 -PROMPT 0 -LABEL pxeboot - KERNEL http://<HTTP_server>/rhcos-<version>-installer-live-kernel-<architecture> <1> - APPEND initrd=http://<HTTP_server>/rhcos-<version>-installer-live-initramfs.<architecture>.img coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/worker.ign coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-installer-live-rootfs.<architecture>.img <2> ----- -<1> Specify the location of the live `kernel` file that you uploaded to your HTTP server. -<2> Specify locations of the {op-system} files that you uploaded to your HTTP server. The `initrd` parameter value is the location of the live `initramfs` file, the `coreos.inst.ignition_url` parameter value is the location of the worker Ignition config file, and the `coreos.live.rootfs_url` parameter value is the location of the live `rootfs` file. The `coreos.inst.ignition_url` and `coreos.live.rootfs_url` parameters only support HTTP and HTTPS. -+ -+ -[NOTE] -==== -This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `APPEND` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?]. -==== - -** For iPXE: -+ ----- -kernel http://<HTTP_server>/rhcos-<version>-installer-kernel-<architecture> coreos.inst.install_dev=/dev/sda coreos.inst.ignition_url=http://<HTTP_server>/worker.ign coreos.live.rootfs_url=http://<HTTP_server>/rhcos-<version>-installer-live-rootfs.<architecture>.img <1> -initrd=http://<HTTP_server>/rhcos-<version>-installer-live-initramfs.<architecture>.img <2> ----- -<1> Specify locations of the {op-system} files that you uploaded to your HTTP server. The `kernel` parameter value is the location of the `kernel` file, the `coreos.inst.ignition_url` parameter value is the location of the worker Ignition config file, and the `coreos.live.rootfs_url` parameter value is the location of the live `rootfs` file. The `coreos.inst.ignition_url` and `coreos.live.rootfs_url` parameters only support HTTP and HTTPS. -<2> Specify the location of the `initramfs` file that you uploaded to your HTTP server. -+ -+ -[NOTE] -==== -This configuration does not enable serial console access on machines with a graphical console. To configure a different console, add one or more `console=` arguments to the `kernel` line. For example, add `console=tty0 console=ttyS0` to set the first PC serial port as the primary console and the graphical console as a secondary console. For more information, see link:https://access.redhat.com/articles/7212[How does one set up a serial terminal and/or console in Red Hat Enterprise Linux?]. -==== - -. Use the PXE or iPXE infrastructure to create the required compute machines for your cluster. diff --git a/modules/machine-user-provisioned-limitations.adoc b/modules/machine-user-provisioned-limitations.adoc deleted file mode 100644 index 45ad0fe3eb73..000000000000 --- a/modules/machine-user-provisioned-limitations.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/applying_autoscaling.adoc -// * machine_management/creating-infrastructure-machinesets.adoc -// * machine_management/creating-machinesets.adoc -// * machine_management/deploying-machine-health-checks.adoc -// * machine_management/manually-scaling-machinesets.adoc -// * post_installation_configuration/node-tasks.adoc - -[IMPORTANT] -==== -This process is not applicable to clusters where you manually provisioned the machines yourself. You can use the advanced machine management and scaling capabilities only in clusters where the machine API is operational. -==== diff --git a/modules/machine-vsphere-machines.adoc b/modules/machine-vsphere-machines.adoc deleted file mode 100644 index 9f094a141149..000000000000 --- a/modules/machine-vsphere-machines.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * machine_management/user_infra/adding-vsphere-compute-user-infra.adoc - -[id="machine-vsphere-machines_{context}"] -= Creating more {op-system-first} machines in vSphere - -You can create more compute machines for your cluster that uses user-provisioned infrastructure on VMware vSphere. - -.Prerequisites - -* Obtain the base64-encoded Ignition file for your compute machines. -* You have access to the vSphere template that you created for your cluster. - -.Procedure - -. After the template deploys, deploy a VM for a machine in the cluster. -.. Right-click the template's name and click *Clone* -> *Clone to Virtual Machine*. -.. On the *Select a name and folder* tab, specify a name for the VM. You might include the machine type in the name, such as `compute-1`. -.. On the *Select a name and folder* tab, select the name of the folder that you created for the cluster. -.. On the *Select a compute resource* tab, select the name of a host in your datacenter. -.. Optional: On the *Select storage* tab, customize the storage options. -.. On the *Select clone options*, select *Customize this virtual machine's hardware*. -.. On the *Customize hardware* tab, click *VM Options* -> *Advanced*. -*** From the *Latency Sensitivity* list, select *High*. -*** Click *Edit Configuration*, and on the *Configuration Parameters* window, click *Add Configuration Params*. Define the following parameter names and values: -**** `guestinfo.ignition.config.data`: Paste the contents of the base64-encoded compute Ignition config file for this machine type. -**** `guestinfo.ignition.config.data.encoding`: Specify `base64`. -**** `disk.EnableUUID`: Specify `TRUE`. -.. In the *Virtual Hardware* panel of the *Customize hardware* tab, modify the specified values as required. Ensure that the amount of RAM, CPU, and disk storage meets the minimum requirements for the machine type. Also, make sure to select the correct network under *Add network adapter* if there are multiple networks available. -.. Complete the configuration and power on the VM. - -. Continue to create more compute machines for your cluster. diff --git a/modules/machineconfig-modify-journald.adoc b/modules/machineconfig-modify-journald.adoc deleted file mode 100644 index a3d6256e73df..000000000000 --- a/modules/machineconfig-modify-journald.adoc +++ /dev/null @@ -1,111 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/post_installation_configuration/machine-configuration-tasks.adoc -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="machineconfig-modify-journald_{context}"] -= Configuring journald settings - -If you need to configure settings for the `journald` service on {product-title} nodes, you can do that by modifying the appropriate configuration file and passing the file to the appropriate pool of nodes as a machine config. - -This procedure describes how to modify `journald` rate limiting settings in the `/etc/systemd/journald.conf` file and apply them to worker nodes. See the `journald.conf` man page for information on how to use that file. - -.Prerequisites -* Have a running {product-title} cluster (version 4.4 or later). -* Log in to the cluster as a user with administrative privileges. - -.Procedure - -. Create the contents of the `/etc/systemd/journald.conf` file and encode it as base64. For example: -+ -[source,terminal] ----- -$ cat > /tmp/jrnl.conf <<EOF -# Disable rate limiting -RateLimitInterval=1s -RateLimitBurst=10000 -Storage=volatile -Compress=no -MaxRetentionSec=30s -EOF ----- - -. Convert the temporary `journal.conf` file to base64 and save it into a variable (`jrnl_cnf`): -+ -[source,terminal] ----- -$ export jrnl_cnf=$( cat /tmp/jrnl.conf | base64 -w0 ) -$ echo $jrnl_cnf -IyBEaXNhYmxlIHJhdGUgbGltaXRpbmcKUmF0ZUxpbWl0SW50ZXJ2YWw9MXMKUmF0ZUxpbWl0QnVyc3Q9MTAwMDAKU3RvcmFnZT12b2xhdGlsZQpDb21wcmVzcz1ubwpNYXhSZXRlbnRpb25TZWM9MzBzCg== ----- - -. Create the machine config, including the encoded contents of `journald.conf` (`jrnl_cnf` variable): -+ -[source,terminal] ----- -$ cat > /tmp/40-worker-custom-journald.yaml <<EOF -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: 40-worker-custom-journald -spec: - config: - ignition: - config: {} - security: - tls: {} - timeouts: {} - version: 3.1.0 - networkd: {} - passwd: {} - storage: - files: - - contents: - source: data:text/plain;charset=utf-8;base64,${jrnl_cnf} - verification: {} - filesystem: root - mode: 420 - path: /etc/systemd/journald.conf - systemd: {} - osImageURL: "" -EOF ----- - -. Apply the machine config to the pool: -+ -[source,terminal] ----- -$ oc apply -f /tmp/40-worker-custom-journald.yaml ----- - -. Check that the new machine config is applied and that the nodes are not in a degraded state. It might take a few minutes. The worker pool will show the updates in progress, as each node successfully has the new machine config applied: -+ -[source,terminal] ----- -$ oc get machineconfigpool -NAME CONFIG UPDATED UPDATING DEGRADED MACHINECOUNT READYMACHINECOUNT UPDATEDMACHINECOUNT DEGRADEDMACHINECOUNT AGE -master rendered-master-35 True False False 3 3 3 0 34m -worker rendered-worker-d8 False True False 3 1 1 0 34m ----- - -. To check that the change was applied, you can log in to a worker node: -+ -[source,terminal] ----- -$ oc get node | grep worker -ip-10-0-0-1.us-east-2.compute.internal Ready worker 39m v0.0.0-master+$Format:%h$ -$ oc debug node/ip-10-0-0-1.us-east-2.compute.internal -Starting pod/ip-10-0-141-142us-east-2computeinternal-debug ... -... -sh-4.2# chroot /host -sh-4.4# cat /etc/systemd/journald.conf -# Disable rate limiting -RateLimitInterval=1s -RateLimitBurst=10000 -Storage=volatile -Compress=no -MaxRetentionSec=30s -sh-4.4# exit ----- diff --git a/modules/machineset-creating b/modules/machineset-creating deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/modules/machineset-creating-dedicated-instances.adoc b/modules/machineset-creating-dedicated-instances.adoc deleted file mode 100644 index f5d43a9598e4..000000000000 --- a/modules/machineset-creating-dedicated-instances.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating_machinesets/creating-machineset-aws.adoc - -[id="machineset-creating-dedicated-instance_{context}"] -= Creating Dedicated Instances by using machine sets - -You can run a machine that is backed by a Dedicated Instance by using Machine API integration. Set the `tenancy` field in your machine set YAML file to launch a Dedicated Instance on AWS. - -.Procedure - -* Specify a dedicated tenancy under the `providerSpec` field: -+ -[source,yaml] ----- -providerSpec: - placement: - tenancy: dedicated ----- diff --git a/modules/machineset-creating-non-guaranteed-instances.adoc b/modules/machineset-creating-non-guaranteed-instances.adoc deleted file mode 100644 index a97a1d8f0c06..000000000000 --- a/modules/machineset-creating-non-guaranteed-instances.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating_machinesets/creating-machineset-aws.adoc -// * machine_management/creating_machinesets/creating-machineset-gcp.adoc -// * machine_management/creating_machinesets/creating-machineset-azure.adoc - -ifeval::["{context}" == "creating-machineset-aws"] -:aws: -endif::[] -ifeval::["{context}" == "creating-machineset-azure"] -:azure: -endif::[] -ifeval::["{context}" == "creating-machineset-gcp"] -:gcp: -endif::[] - -[id="machineset-creating-non-guaranteed-instance_{context}"] -ifdef::aws[= Creating Spot Instances by using machine sets] -ifdef::azure[= Creating Spot VMs by using machine sets] -ifdef::gcp[= Creating preemptible VM instances by using machine sets] - -ifdef::aws[You can launch a Spot Instance on AWS by adding `spotMarketOptions` to your machine set YAML file.] -ifdef::azure[You can launch a Spot VM on Azure by adding `spotVMOptions` to your machine set YAML file.] -ifdef::gcp[You can launch a preemptible VM instance on GCP by adding `preemptible` to your machine set YAML file.] - -.Procedure -* Add the following line under the `providerSpec` field: -+ -ifdef::aws[] -[source,yaml] ----- -providerSpec: - value: - spotMarketOptions: {} ----- -+ -You can optionally set the `spotMarketOptions.maxPrice` field to limit the cost of the Spot Instance. For example you can set `maxPrice: '2.50'`. -+ -If the `maxPrice` is set, this value is used as the hourly maximum spot price. If it is not set, the maximum price defaults to charge up to the On-Demand Instance price. -+ -[NOTE] -==== -It is strongly recommended to use the default On-Demand price as the `maxPrice` value and to not set the maximum price for Spot Instances. -==== -endif::aws[] -ifdef::azure[] -[source,yaml] ----- -providerSpec: - value: - spotVMOptions: {} ----- -+ -You can optionally set the `spotVMOptions.maxPrice` field to limit the cost of the Spot VM. For example you can set `maxPrice: '0.98765'`. If the `maxPrice` is set, this value is used as the hourly maximum spot price. If it is not set, the maximum price defaults to `-1` and charges up to the standard VM price. -+ -Azure caps Spot VM prices at the standard price. Azure will not evict an instance due to pricing if the instance is set with the default `maxPrice`. However, an instance can still be evicted due to capacity restrictions. - -[NOTE] -==== -It is strongly recommended to use the default standard VM price as the `maxPrice` value and to not set the maximum price for Spot VMs. -==== -endif::azure[] -ifdef::gcp[] -[source,yaml] ----- -providerSpec: - value: - preemptible: true ----- -+ -If `preemptible` is set to `true`, the machine is labelled as an `interruptable-instance` after the instance is launched. - -endif::gcp[] diff --git a/modules/machineset-creating.adoc b/modules/machineset-creating.adoc deleted file mode 100644 index 013c63954b8f..000000000000 --- a/modules/machineset-creating.adoc +++ /dev/null @@ -1,211 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * machine_management/creating_machinesets/creating-machineset-aws.adoc -// * machine_management/creating_machinesets/creating-machineset-azure.adoc -// * machine_management/creating_machinesets/creating-machineset-gcp.adoc -// * machine_management/creating_machinesets/creating-machineset-osp.adoc -// * machine_management/creating_machinesets/creating-machineset-vsphere.adoc -// * post_installation_configuration/cluster-tasks.adoc -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.adoc -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-azure.adoc -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc - -ifeval::["{context}" == "creating-windows-machineset-aws"] -:win: -endif::[] -ifeval::["{context}" == "creating-windows-machineset-azure"] -:win: -endif::[] -ifeval::["{context}" == "creating-windows-machineset-vsphere"] -:win: -endif::[] - -ifeval::["{context}" == "creating-machineset-vsphere"] -:vsphere: -endif::[] - -[id="machineset-creating_{context}"] -= Creating a machine set - -In addition to the ones created by the installation program, you can create your own machine sets to dynamically manage the machine compute resources for specific workloads of your choice. - -.Prerequisites - -* Deploy an {product-title} cluster. -* Install the OpenShift CLI (`oc`). -* Log in to `oc` as a user with `cluster-admin` permission. -ifdef::vsphere[] -* Create a tag inside your vCenter instance based on the cluster API name. This tag is utilized by the machine set to associate the {product-title} nodes to the provisioned virtual machines (VM). For directions on creating tags in vCenter, see the VMware documentation for link:https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.vcenterhost.doc/GUID-E8E854DD-AA97-4E0C-8419-CE84F93C4058.html[vSphere Tags and Attributes]. -* Have the necessary permissions to deploy VMs in your vCenter instance and have the required access to the datastore specified. -endif::vsphere[] - -.Procedure - -. Create a new YAML file that contains the machine set custom resource (CR) sample, as shown, and is named `<file_name>.yaml`. -+ -Ensure that you set the `<clusterID>` and `<role>` parameter values. - -.. If you are not sure about which value to set for a specific field, you can check an existing machine set from your cluster. -+ -[source,terminal] ----- -$ oc get machinesets -n openshift-machine-api ----- -+ -.Example output -[source,terminal] ----- -NAME DESIRED CURRENT READY AVAILABLE AGE -agl030519-vplxk-worker-us-east-1a 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1b 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1c 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1d 0 0 55m -agl030519-vplxk-worker-us-east-1e 0 0 55m -agl030519-vplxk-worker-us-east-1f 0 0 55m ----- - -.. Check values of a specific machine set: -+ -[source,terminal] ----- -$ oc get machineset <machineset_name> -n \ - openshift-machine-api -o yaml ----- -+ -.Example output -[source,yaml] ----- -... -template: - metadata: - labels: - machine.openshift.io/cluster-api-cluster: agl030519-vplxk <1> - machine.openshift.io/cluster-api-machine-role: worker <2> - machine.openshift.io/cluster-api-machine-type: worker - machine.openshift.io/cluster-api-machineset: agl030519-vplxk-worker-us-east-1a ----- -<1> The cluster ID. -<2> A default node label. - -. Create the new `MachineSet` CR: -+ -[source,terminal] ----- -$ oc create -f <file_name>.yaml ----- - -. View the list of machine sets: -+ -[source,terminal] ----- -$ oc get machineset -n openshift-machine-api ----- -+ -.Example output -[source,terminal] ----- -ifdef::win[] -NAME DESIRED CURRENT READY AVAILABLE AGE -agl030519-vplxk-windows-worker-us-east-1a 1 1 1 1 11m -agl030519-vplxk-worker-us-east-1a 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1b 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1c 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1d 0 0 55m -agl030519-vplxk-worker-us-east-1e 0 0 55m -agl030519-vplxk-worker-us-east-1f 0 0 55m -endif::win[] -ifndef::win[] -NAME DESIRED CURRENT READY AVAILABLE AGE -agl030519-vplxk-infra-us-east-1a 1 1 1 1 11m -agl030519-vplxk-worker-us-east-1a 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1b 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1c 1 1 1 1 55m -agl030519-vplxk-worker-us-east-1d 0 0 55m -agl030519-vplxk-worker-us-east-1e 0 0 55m -agl030519-vplxk-worker-us-east-1f 0 0 55m -endif::win[] ----- -+ -When the new machine set is available, the `DESIRED` and `CURRENT` values match. If the machine set is not available, wait a few minutes and run the command again. - -. After the new machine set is available, check status of the machine and the node that it references: -+ -[source,terminal] ----- -$ oc describe machine <name> -n openshift-machine-api ----- -+ -For example: -+ -[source,terminal] ----- -ifdef::win[] -$ oc describe machine agl030519-vplxk-windows-worker-us-east-1a -n openshift-machine-api -endif::win[] -ifndef::win[] -$ oc describe machine agl030519-vplxk-infra-us-east-1a -n openshift-machine-api -endif::win[] ----- -+ -.Example output -[source,terminal] ----- -status: - addresses: - - address: 10.0.133.18 - type: InternalIP - - address: "" - type: ExternalDNS - - address: ip-10-0-133-18.ec2.internal - type: InternalDNS - lastUpdated: "2019-05-03T10:38:17Z" - nodeRef: - kind: Node - name: ip-10-0-133-18.ec2.internal - uid: 71fb8d75-6d8f-11e9-9ff3-0e3f103c7cd8 - providerStatus: - apiVersion: awsproviderconfig.openshift.io/v1beta1 - conditions: - - lastProbeTime: "2019-05-03T10:34:31Z" - lastTransitionTime: "2019-05-03T10:34:31Z" - message: machine successfully created - reason: MachineCreationSucceeded - status: "True" - type: MachineCreation - instanceId: i-09ca0701454124294 - instanceState: running - kind: AWSMachineProviderStatus ----- - -. View the new node and confirm that the new node has the label that you specified: -+ -[source,terminal] ----- -$ oc get node <node_name> --show-labels ----- -+ -Review the command output and confirm that `node-role.kubernetes.io/<your_label>` is in the `LABELS` list. - -[NOTE] -==== -Any change to a machine set is not applied to existing machines owned by the machine set. For example, labels edited or added to an existing machine set are not propagated to existing machines and nodes associated with the machine set. -==== - -ifeval::["{context}" == "creating-machineset-aws"] -.Next steps -If you need machine sets in other availability zones, repeat this process to create more machine sets. -endif::[] - -ifeval::["{context}" == "creating-machineset-vsphere"] -:!vsphere: -endif::[] -ifeval::["{context}" == "creating-windows-machineset-aws"] -:!win: -endif::[] -ifeval::["{context}" == "creating-windows-machineset-azure"] -:!win: -endif::[] -ifeval::["{context}" == "creating-windows-machineset-vsphere"] -:!win: -endif::[] diff --git a/modules/machineset-dedicated-instances.adoc b/modules/machineset-dedicated-instances.adoc deleted file mode 100644 index 5c672366fe0f..000000000000 --- a/modules/machineset-dedicated-instances.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating_machinesets/creating-machineset-aws.adoc - -[id="machineset-dedicated-instance_{context}"] -= Machine sets that deploy machines as Dedicated Instances - -You can create a machine set running on AWS that deploys machines as Dedicated Instances. Dedicated Instances run in a virtual private cloud (VPC) on hardware that is dedicated to a single customer. These Amazon EC2 instances are physically isolated at the host hardware level. The isolation of Dedicated Instances occurs even if the instances belong to different AWS accounts that are linked to a single payer account. However, other instances that are not dedicated can share hardware with Dedicated Instances if they belong to the same AWS account. - -Instances with either public or dedicated tenancy are supported by the Machine API. Instances with public tenancy run on shared hardware. Public tenancy is the default tenancy. Instances with dedicated tenancy run on single-tenant hardware. diff --git a/modules/machineset-delete-policy.adoc b/modules/machineset-delete-policy.adoc deleted file mode 100644 index 9decc44152e0..000000000000 --- a/modules/machineset-delete-policy.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/manually-scaling-machineset.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="machineset-delete-policy_{context}"] -= The machine set deletion policy - -`Random`, `Newest`, and `Oldest` are the three supported deletion options. The default is `Random`, meaning that random machines are chosen and deleted when scaling machine sets down. The deletion policy can be set according to the use case by modifying the particular machine set: - -[source,yaml] ----- -spec: - deletePolicy: <delete_policy> - replicas: <desired_replica_count> ----- - -Specific machines can also be prioritized for deletion by adding the annotation `machine.openshift.io/cluster-api-delete-machine` to the machine of interest, regardless of the deletion policy. - -[IMPORTANT] -==== -By default, the {product-title} router pods are deployed on workers. Because the router is required to access some cluster resources, including the web console, do not scale the worker machine set to `0` unless you first relocate the router pods. -==== - -[NOTE] -==== -Custom machine sets can be used for use cases requiring that services run on specific nodes and that those services are ignored by the controller when the worker machine sets are scaling down. This prevents service disruption. -==== diff --git a/modules/machineset-enabling-customer-managed-encryption.adoc b/modules/machineset-enabling-customer-managed-encryption.adoc deleted file mode 100644 index bc643198e61a..000000000000 --- a/modules/machineset-enabling-customer-managed-encryption.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating_machinesets/creating-machineset-gcp.adoc - -[id="machineset-enabling-customer-managed-encryption_{context}"] -= Enabling customer-managed encryption keys for a machine set - -Google Cloud Platform (GCP) Compute Engine allows users to supply an encryption key to encrypt data on disks at rest. The key is used to encrypt the data encryption key, not to encrypt the customer's data. By default, Compute Engine encrypts this data by using Compute Engine keys. - -You can enable encryption with a customer-managed key by using the Machine API. You must first link:https://cloud.google.com/compute/docs/disks/customer-managed-encryption#before_you_begin[create a KMS key] and assign the correct permissions to a service account. The KMS key name, key ring name, and location are required to allow a service account to use your key. - -[NOTE] -==== -If you do not want to use a dedicated service account for the KMS encryption, the Compute Engine default service account is used instead. You must grant the default service account permission to access the keys if you do not use a dedicated service account. The Compute Engine default service account name follows the `service-<project_number>@compute-system.iam.gserviceaccount.com` pattern. -==== - -.Procedure - -. Run the following command with your KMS key name, key ring name, and location to allow a specific service account to use your KMS key and to grant the service account the correct IAM role: -+ -[source,terminal] ----- -gcloud kms keys add-iam-policy-binding <key_name> \ - --keyring <key_ring_name> \ - --location <key_ring_location> \ - --member "serviceAccount:service-<project_number>@compute-system.iam.gserviceaccount.com” \ - --role roles/cloudkms.cryptoKeyEncrypterDecrypter ----- - -. Configure the encryption key under the `providerSpec` field in your machine set YAML file. For example: -+ -[source,yaml] ----- -providerSpec: - value: - … - disks: - - type: … - … - encryptionKey: - kmsKey: - name: machine-encryption-key <1> - keyRing: openshift-encrpytion-ring <2> - location: global <3> - projectID: openshift-gcp-project <4> - kmsKeyServiceAccount: openshift-service-account@openshift-gcp-project.iam.gserviceaccount.com <5> ----- -<1> The name of the customer-managed encryption key that is used for the disk encryption. -<2> The name of the KMS key ring that the KMS key belongs to. -<3> The GCP location in which the KMS key ring exists. -<4> Optional: The ID of the project in which the KMS key ring exists. If a project ID is not set, the machine set `projectID` in which the machine set was created is used. -<5> Optional: The service account that is used for the encryption request for the given KMS key. If a service account is not set, the Compute Engine default service account is used. -+ -After a new machine is created by using the updated `providerSpec` object configuration, the disk encryption key is encrypted with the KMS key. diff --git a/modules/machineset-manually-scaling.adoc b/modules/machineset-manually-scaling.adoc deleted file mode 100644 index 227893879c9b..000000000000 --- a/modules/machineset-manually-scaling.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/manually-scaling-machineset.adoc -// * post_installation_configuration/cluster-tasks.adoc -// * windows_containers/scheduling-windows-workloads.adoc - -[id="machineset-manually-scaling_{context}"] -= Scaling a machine set manually - -If you must add or remove an instance of a machine in a machine set, you can manually scale the machine set. - -This guidance is relevant to fully automated, installer-provisioned infrastructure installations. Customized, user-provisioned infrastructure installations does not have machine sets. - -.Prerequisites - -* Install an {product-title} cluster and the `oc` command line. -* Log in to `oc` as a user with `cluster-admin` permission. - -.Procedure - -. View the machine sets that are in the cluster: -+ -[source,terminal] ----- -$ oc get machinesets -n openshift-machine-api ----- -+ -The machine sets are listed in the form of `<clusterid>-worker-<aws-region-az>`. - -. Scale the machine set: -+ -[source,terminal] ----- -$ oc scale --replicas=2 machineset <machineset> -n openshift-machine-api ----- -+ -Or: -+ -[source,terminal] ----- -$ oc edit machineset <machineset> -n openshift-machine-api ----- -+ -You can scale the machine set up or down. It takes several minutes for the new machines to be available. diff --git a/modules/machineset-modifying.adoc b/modules/machineset-modifying.adoc deleted file mode 100644 index e20462ff4f5b..000000000000 --- a/modules/machineset-modifying.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// -// * machine_management/modifying-machineset.adoc -// * scalability_and_performance/recommended-cluster-scaling-practices.adoc - -[id="machineset-modifying_{context}"] -= Modifying a machine set - -To make changes to a machine set, edit the `MachineSet` YAML. Then, remove all machines associated with the machine set by deleting each machine or scaling down the machine set to `0` replicas. Then, scale the replicas back to the desired number. Changes you make to a machine set do not affect existing machines. - -If you need to scale a machine set without making other changes, you do not need to delete the machines. - -[NOTE] -==== -By default, the {product-title} router pods are deployed on workers. Because the router is required to access some cluster resources, including the web console, do not scale the worker machine set to `0` unless you first relocate the router pods. -==== - -.Prerequisites - -* Install an {product-title} cluster and the `oc` command line. -* Log in to `oc` as a user with `cluster-admin` permission. - -.Procedure - -. Edit the machine set: -+ -[source,terminal] ----- -$ oc edit machineset <machineset> -n openshift-machine-api ----- - -. Scale down the machine set to `0`: -+ -[source,terminal] ----- -$ oc scale --replicas=0 machineset <machineset> -n openshift-machine-api ----- -+ -Or: -+ -[source,terminal] ----- -$ oc edit machineset <machineset> -n openshift-machine-api ----- -+ -Wait for the machines to be removed. - -. Scale up the machine set as needed: -+ -[source,terminal] ----- -$ oc scale --replicas=2 machineset <machineset> -n openshift-machine-api ----- -+ -Or: -+ -[source,terminal] ----- -$ oc edit machineset <machineset> -n openshift-machine-api ----- -+ -Wait for the machines to start. The new machines contain changes you made to the machine set. diff --git a/modules/machineset-non-guaranteed-instance.adoc b/modules/machineset-non-guaranteed-instance.adoc deleted file mode 100644 index e95b57093335..000000000000 --- a/modules/machineset-non-guaranteed-instance.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating_machinesets/creating-machineset-aws.adoc -// * machine_management/creating_machinesets/creating-machineset-gcp.adoc -// * machine_management/creating_machinesets/creating-machineset-azure.adoc - -ifeval::["{context}" == "creating-machineset-aws"] -:aws: -endif::[] -ifeval::["{context}" == "creating-machineset-azure"] -:azure: -endif::[] -ifeval::["{context}" == "creating-machineset-gcp"] -:gcp: -endif::[] - -[id="machineset-non-guaranteed-instance_{context}"] -ifdef::aws[= Machine sets that deploy machines as Spot Instances] -ifdef::azure[= Machine sets that deploy machines as Spot VMs] -ifdef::gcp[= Machine sets that deploy machines as preemptible VM instances] -ifdef::aws[] -You can save on costs by creating a machine set running on AWS that deploys machines as non-guaranteed Spot Instances. Spot Instances utilize unused AWS EC2 capacity and are less expensive than On-Demand Instances. You can use Spot Instances for workloads that can tolerate interruptions, such as batch or stateless, horizontally scalable workloads. -endif::aws[] -ifdef::azure[] -You can save on costs by creating a machine set running on Azure that deploys machines as non-guaranteed Spot VMs. Spot VMs utilize unused Azure capacity and are less expensive than standard VMs. You can use Spot VMs for workloads that can tolerate interruptions, such as batch or stateless, horizontally scalable workloads. -endif::azure[] -ifdef::gcp[] -You can save on costs by creating a machine set running on GCP that deploys machines as non-guaranteed preemptible VM instances. Preemptible VM instances utilize excess Compute Engine capacity and are less expensive than normal instances. You can use preemptible VM instances for workloads that can tolerate interruptions, such as batch or stateless, horizontally scalable workloads. -endif::gcp[] - -[IMPORTANT] -==== -It is strongly recommended that control plane machines are not created on -ifdef::aws[Spot Instances] -ifdef::azure[Spot VMs] -ifdef::gcp[preemptible VM instances] -due to the increased likelihood of the instance being terminated. Manual intervention is required to replace a terminated control plane node. -==== - -ifdef::aws[] -AWS EC2 can terminate a Spot Instance at any time. AWS gives a two-minute warning to the user when an interruption occurs. {product-title} begins to remove the workloads from the affected instances when AWS issues the termination warning. - -Interruptions can occur when using Spot Instances for the following reasons: - -* The instance price exceeds your maximum price -* The demand for Spot Instances increases -* The supply of Spot Instances decreases - -When AWS terminates an instance, a termination handler running on the Spot Instance node deletes the machine resource. To satisfy the machine set `replicas` quantity, the machine set creates a machine that requests a Spot Instance. -endif::aws[] -ifdef::azure[] -Azure can terminate a Spot VM at any time. Azure gives a 30-second warning to the user when an interruption occurs. {product-title} begins to remove the workloads from the affected instances when Azure issues the termination warning. - -Interruptions can occur when using Spot VMs for the following reasons: - -* The instance price exceeds your maximum price -* The supply of Spot VMs decreases -* Azure needs capacity back - - -When Azure terminates an instance, a termination handler running on the Spot VM node deletes the machine resource. To satisfy the machine set `replicas` quantity, the machine set creates a machine that requests a Spot VM. -endif::azure[] -ifdef::gcp[] -GCP Compute Engine can terminate a preemptible VM instance at any time. Compute Engine sends a preemption notice to the user indicating that an interruption will occur in 30 seconds. {product-title} begins to remove the workloads from the affected instances when Compute Engine issues the preemption notice. An ACPI G3 Mechanical Off signal is sent to the operating system after 30 seconds if the instance is not stopped. The preemptible VM instance is then transitioned to a `TERMINATED` state by Compute Engine. - -Interruptions can occur when using preemptible VM instances for the following reasons: - -* There is a system or maintenance event -* The supply of preemptible VM instances decreases -* The instance reaches the end of the allotted 24-hour period for preemptible VM instances - -When GCP terminates an instance, a termination handler running on the preemptible VM instance node deletes the machine resource. To satisfy the machine set `replicas` quantity, the machine set creates a machine that requests a preemptible VM instance. -endif::gcp[] diff --git a/modules/machineset-osp-adding-bare-metal.adoc b/modules/machineset-osp-adding-bare-metal.adoc deleted file mode 100644 index ada1af60a255..000000000000 --- a/modules/machineset-osp-adding-bare-metal.adoc +++ /dev/null @@ -1,93 +0,0 @@ -[id="machineset-osp-adding-bare-metal_{context}"] -= Adding bare-metal compute machines to a {rh-openstack} cluster -// TODO -// Mothballed -// Reintroduce when feature is available. -You can add bare-metal compute machines to an {product-title} cluster after you deploy it -on {rh-openstack-first}. In this configuration, all machines are attached to an -existing, installer-provisioned network, and traffic between control plane and -compute machines is routed between subnets. - -[NOTE] -==== -Bare-metal compute machines are not supported on clusters that use Kuryr. -==== - -.Prerequisites - -* The {rh-openstack} link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/bare_metal_provisioning/index[Bare Metal service (Ironic)] is enabled and accessible by using the {rh-openstack} Compute API. - -* Bare metal is available as link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.1/html/bare_metal_provisioning/sect-configure#creating_the_bare_metal_flavor[an {rh-openstack} flavor]. - -* You deployed a {product-title} cluster on installer-provisioned infrastructure. - -* Your {rh-openstack} cloud provider is configured to route traffic between the installer-created VM -subnet and the pre-existing bare metal subnet. - -.Procedure -. Create a file called `baremetalMachineSet.yaml`, and then add the bare metal flavor to it: -+ -FIXME: May require update before publication. -.A sample bare metal MachineSet file -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_ID> - machine.openshift.io/cluster-api-machine-role: <node_role> - machine.openshift.io/cluster-api-machine-type: <node_role> - name: <infrastructure_ID>-<node_role> - namespace: openshift-machine-api -spec: - replicas: <number_of_replicas> - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructure_ID> - machine.openshift.io/cluster-api-machineset: <infrastructure_ID>-<node_role> - template: - metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_ID> - machine.openshift.io/cluster-api-machine-role: <node_role> - machine.openshift.io/cluster-api-machine-type: <node_role> - machine.openshift.io/cluster-api-machineset: <infrastructure_ID>-<node_role> - spec: - providerSpec: - value: - apiVersion: openstackproviderconfig.openshift.io/v1alpha1 - cloudName: openstack - cloudsSecret: - name: openstack-cloud-credentials - namespace: openshift-machine-api - flavor: <nova_flavor> - image: <glance_image_name_or_location> - kind: OpenstackProviderSpec - networks: - - filter: {} - subnets: - - filter: - name: <subnet_name> - tags: openshiftClusterID=<infrastructure_ID> - securityGroups: - - filter: {} - name: <infrastructure_ID>-<node_role> - serverMetadata: - Name: <infrastructure_ID>-<node_role> - openshiftClusterID: <infrastructure_ID> - tags: - - openshiftClusterID=<infrastructure_ID> - trunk: true - userDataSecret: - name: <node_role>-user-data ----- - -. On a command line, to create the MachineSet resource, type: -+ -[source,terminal] ----- -$ oc create -v baremetalMachineSet.yaml ----- - -You can now use bare-metal compute machines in your {product-title} cluster. diff --git a/modules/machineset-yaml-aws.adoc b/modules/machineset-yaml-aws.adoc deleted file mode 100644 index a60bc379e8d8..000000000000 --- a/modules/machineset-yaml-aws.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * machine_management/creating_machinesets/creating-machineset-aws.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="machineset-yaml-aws_{context}"] -= Sample YAML for a machine set custom resource on AWS - -This sample YAML defines a machine set that runs in the `us-east-1a` Amazon Web Services (AWS) zone and creates nodes that are labeled with `node-role.kubernetes.io/<role>: ""` - -In this sample, `<infrastructureID>` is the infrastructure ID label that is based on the cluster ID that you set when you provisioned the cluster, and `<role>` is the node label to add. - -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - name: <infrastructureID>-<role>-<zone> <2> - namespace: openshift-machine-api -spec: - replicas: 1 - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - machine.openshift.io/cluster-api-machineset: <infrastructureID>-<role>-<zone> <2> - template: - metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - machine.openshift.io/cluster-api-machine-role: <role> <3> - machine.openshift.io/cluster-api-machine-type: <role> <3> - machine.openshift.io/cluster-api-machineset: <infrastructureID>-<role>-<zone> <2> - spec: - metadata: - labels: - node-role.kubernetes.io/<role>: "" <3> - providerSpec: - value: - ami: - id: ami-046fe691f52a953f9 <4> - apiVersion: awsproviderconfig.openshift.io/v1beta1 - blockDevices: - - ebs: - iops: 0 - volumeSize: 120 - volumeType: gp2 - credentialsSecret: - name: aws-cloud-credentials - deviceIndex: 0 - iamInstanceProfile: - id: <infrastructureID>-worker-profile <1> - instanceType: m4.large - kind: AWSMachineProviderConfig - placement: - availabilityZone: us-east-1a - region: us-east-1 - securityGroups: - - filters: - - name: tag:Name - values: - - <infrastructureID>-worker-sg <1> - subnet: - filters: - - name: tag:Name - values: - - <infrastructureID>-private-us-east-1a <1> - tags: - - name: kubernetes.io/cluster/<infrastructureID> <1> - value: owned - userDataSecret: - name: worker-user-data ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. If you have the OpenShift CLI installed, you can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- -<2> Specify the infrastructure ID, node label, and zone. -<3> Specify the node label to add. -<4> Specify a valid {op-system-first} AMI for your AWS zone for your {product-title} nodes. diff --git a/modules/machineset-yaml-azure.adoc b/modules/machineset-yaml-azure.adoc deleted file mode 100644 index 52cb73a72c14..000000000000 --- a/modules/machineset-yaml-azure.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * machine_management/creating-machineset-azure.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="machineset-yaml-azure_{context}"] -= Sample YAML for a machine set custom resource on Azure - -This sample YAML defines a machine set that runs in the `1` Microsoft Azure zone in the `centralus` region and creates nodes that are labeled with `node-role.kubernetes.io/<role>: ""` - -In this sample, `<infrastructureID>` is the infrastructure ID label that is based on the cluster ID that you set when you provisioned the cluster, and `<role>` is the node label to add. - -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - machine.openshift.io/cluster-api-machine-role: <role> <2> - machine.openshift.io/cluster-api-machine-type: <role> <2> - name: <infrastructureID>-<role>-<region> <3> - namespace: openshift-machine-api -spec: - replicas: 1 - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - machine.openshift.io/cluster-api-machineset: <infrastructureID>-<role>-<region> <3> - template: - metadata: - creationTimestamp: null - labels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - machine.openshift.io/cluster-api-machine-role: <role> <2> - machine.openshift.io/cluster-api-machine-type: <role> <2> - machine.openshift.io/cluster-api-machineset: <infrastructureID>-<role>-<region> <3> - spec: - metadata: - creationTimestamp: null - labels: - node-role.kubernetes.io/<role>: "" <2> - providerSpec: - value: - apiVersion: azureproviderconfig.openshift.io/v1beta1 - credentialsSecret: - name: azure-cloud-credentials - namespace: openshift-machine-api - image: - offer: "" - publisher: "" - resourceID: /resourceGroups/<infrastructureID>-rg/providers/Microsoft.Compute/images/<infrastructureID> - sku: "" - version: "" - internalLoadBalancer: "" - kind: AzureMachineProviderSpec - location: centralus - managedIdentity: <infrastructureID>-identity <1> - metadata: - creationTimestamp: null - natRule: null - networkResourceGroup: "" - osDisk: - diskSizeGB: 128 - managedDisk: - storageAccountType: Premium_LRS - osType: Linux - publicIP: false - publicLoadBalancer: "" - resourceGroup: <infrastructureID>-rg <1> - sshPrivateKey: "" - sshPublicKey: "" - subnet: <infrastructureID>-<role>-subnet <1> <2> - userDataSecret: - name: <role>-user-data <2> - vmSize: Standard_D2s_v3 - vnet: <infrastructureID>-vnet <1> - zone: "1" <4> ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. If you have the OpenShift CLI installed, you can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- -<2> Specify the node label to add. -<3> Specify the infrastructure ID, node label, and region. -<4> Specify the zone within your region to place Machines on. Be sure that your region supports the zone that you specify. diff --git a/modules/machineset-yaml-gcp.adoc b/modules/machineset-yaml-gcp.adoc deleted file mode 100644 index 40c7654e0ed7..000000000000 --- a/modules/machineset-yaml-gcp.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * machine_management/creating-machineset-gcp.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="machineset-yaml-gcp_{context}"] -= Sample YAML for a machine set custom resource on GCP - -This sample YAML defines a machine set that runs in Google Cloud Platform (GCP) and creates nodes that are labeled with `node-role.kubernetes.io/<role>: ""` - -In this sample, `<infrastructureID>` is the infrastructure ID label that is based on the cluster ID that you set when you provisioned the cluster, and `<role>` is the node label to add. - -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - name: <infrastructureID>-w-a <1> - namespace: openshift-machine-api -spec: - replicas: 1 - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - machine.openshift.io/cluster-api-machineset: <infrastructureID>-w-a <1> - template: - metadata: - creationTimestamp: null - labels: - machine.openshift.io/cluster-api-cluster: <infrastructureID> <1> - machine.openshift.io/cluster-api-machine-role: <role> <3> - machine.openshift.io/cluster-api-machine-type: <role> <3> - machine.openshift.io/cluster-api-machineset: <infrastructureID>-w-a <1> - spec: - metadata: - labels: - node-role.kubernetes.io/<role>: "" <3> - providerSpec: - value: - apiVersion: gcpprovider.openshift.io/v1beta1 - canIPForward: false - credentialsSecret: - name: gcp-cloud-credentials - deletionProtection: false - disks: - - autoDelete: true - boot: true - image: <infrastructureID>-rhcos-image <1> - labels: null - sizeGb: 128 - type: pd-ssd - kind: GCPMachineProviderSpec - machineType: n1-standard-4 - metadata: - creationTimestamp: null - networkInterfaces: - - network: <infrastructureID>-network <1> - subnetwork: <infrastructureID>-<role>-subnet <2> - projectID: <project_name> <4> - region: us-central1 - serviceAccounts: - - email: <infrastructureID>-w@<project_name>.iam.gserviceaccount.com <1> <4> - scopes: - - https://www.googleapis.com/auth/cloud-platform - tags: - - <infrastructureID>-<role> <2> - userDataSecret: - name: worker-user-data - zone: us-central1-a ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. If you have the OpenShift CLI installed, you can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- -<2> Specify the infrastructure ID and node label. -<3> Specify the node label to add. -<4> Specify the name of the GCP project that you use for your cluster. diff --git a/modules/machineset-yaml-osp.adoc b/modules/machineset-yaml-osp.adoc deleted file mode 100644 index 03072bef106b..000000000000 --- a/modules/machineset-yaml-osp.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * machine_management/creating_machinesets/creating-machineset-osp.adoc - -[id="machineset-yaml-osp_{context}"] -= Sample YAML for a machine set custom resource on {rh-openstack} - -This sample YAML defines a machine set that runs on {rh-openstack-first} and creates nodes that are labeled with `node-role.openshift.io/<node_role>: ""` - -In this sample, `infrastructure_ID` is the infrastructure ID label that is based on the cluster ID that you set when you provisioned the cluster, and `node_role` is the node label to add. - -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_ID> <1> - machine.openshift.io/cluster-api-machine-role: <node_role> <2> - machine.openshift.io/cluster-api-machine-type: <node_role> <2> - name: <infrastructure_ID>-<node_role> <3> - namespace: openshift-machine-api -spec: - replicas: <number_of_replicas> - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructure_ID> <1> - machine.openshift.io/cluster-api-machineset: <infrastructure_ID>-<node_role> <3> - template: - metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_ID> <1> - machine.openshift.io/cluster-api-machine-role: <node_role> <2> - machine.openshift.io/cluster-api-machine-type: <node_role> <2> - machine.openshift.io/cluster-api-machineset: <infrastructure_ID>-<node_role> <3> - spec: - providerSpec: - value: - apiVersion: openstackproviderconfig.openshift.io/v1alpha1 - cloudName: openstack - cloudsSecret: - name: openstack-cloud-credentials - namespace: openshift-machine-api - flavor: <nova_flavor> - image: <glance_image_name_or_location> - serverGroupID: <optional_UUID_of_server_group> <4> - kind: OpenstackProviderSpec - networks: <5> - - filter: {} - subnets: - - filter: - name: <subnet_name> - tags: openshiftClusterID=<infrastructure_ID> - primarySubnet: <rhosp_subnet_UUID> <6> - securityGroups: - - filter: {} - name: <infrastructure_ID>-<node_role> - serverMetadata: - Name: <infrastructure_ID>-<node_role> - openshiftClusterID: <infrastructure_ID> - tags: - - openshiftClusterID=<infrastructure_ID> - trunk: true - userDataSecret: - name: <node_role>-user-data <2> - availabilityZone: <optional_openstack_availability_zone> ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. If you have the OpenShift CLI installed, you can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- -<2> Specify the node label to add. -<3> Specify the infrastructure ID and node label. -<4> To set a server group policy for the MachineSet, enter the value that is returned from -link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/16.0/html/command_line_interface_reference/server#server_group_create[creating a server group]. For most deployments, `anti-affinity` or `soft-anti-affinity` policies are recommended. -<5> Required for deployments to multiple networks. If deploying to multiple networks, this list must include the network that is used as the `primarySubnet` value. -<6> Specify the {rh-openstack} subnet that you want the endpoints of nodes to be published on. Usually, this is the same subnet that is used as the value of `machinesSubnet` in the `install-config.yaml` file. \ No newline at end of file diff --git a/modules/machineset-yaml-rhv.adoc b/modules/machineset-yaml-rhv.adoc deleted file mode 100644 index 9998145fcb19..000000000000 --- a/modules/machineset-yaml-rhv.adoc +++ /dev/null @@ -1,108 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * machine_management/creating_machinesets/creating-machineset-rhv.adoc - -[id="machineset-yaml-rhv_{context}"] -= Sample YAML for a machine set custom resource on {rh-virtualization} - -This sample YAML defines a machine set that runs on {rh-virtualization} and creates nodes that are labeled with `node-role.kubernetes.io/<node_role>: ""`. - -In this sample, `<infrastructure_id>` is the infrastructure ID label that is based on the cluster ID that you set when you provisioned the cluster, and `<role>` is the node label to add. - -[source,yaml,subs="+quotes"] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machine-role: <role> <2> - machine.openshift.io/cluster-api-machine-type: <role> <2> - name: <infrastructure_id>-<role> <3> - namespace: openshift-machine-api -spec: - replicas: <number_of_replicas> <4> - Selector: <5> - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role> <3> - template: - metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machine-role: <role> <2> - machine.openshift.io/cluster-api-machine-type: <role> <2> - machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role> <3> - spec: - metadata: - labels: - node-role.kubernetes.io/<role>: "" <2> - providerSpec: - value: - apiVersion: ovirtproviderconfig.machine.openshift.io/v1beta1 - cluster_id: <ovirt_cluster_id> <6> - template_name: <ovirt_template_name> <7> - instance_type_id: <instance_type_id> <8> - cpu: <9> - sockets: <number_of_sockets> <10> - cores: <number_of_cores> <11> - threads: <number_of_threads> <12> - memory_mb: <memory_size> <13> - os_disk: <14> - size_gb: <disk_size> <15> - network_interfaces: <16> - vnic_profile_id: <vnic_profile_id> <17> - credentialsSecret: - name: ovirt-credentials <18> - kind: OvirtMachineProviderSpec - type: <workload_type> <19> - userDataSecret: - name: worker-user-data ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. If you have the OpenShift CLI (`oc`) installed, you can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- - -<2> Specify the node label to add. - -<3> Specify the infrastructure ID and node label. These two strings together cannot be longer than 35 characters. - -<4> Specify the number of machines to create. - -<5> Selector for the machines. - -<6> Specify the UUID for the {rh-virtualization} cluster to which this VM instance belongs. - -<7> Specify the {rh-virtualization} VM template to use to create the machine. - -<8> Optional: Specify the VM instance type. If you include this parameter, you do not need to specify the hardware parameters of the VM including CPU and memory because this parameter overrides all hardware parameters. - -<9> Optional: The CPU field contains the CPU's configuration, including sockets, cores, and threads. - -<10> Optional: Specify the number of sockets for a VM. - -<11> Optional: Specify the number of cores per socket. - -<12> Optional: Specify the number of threads per core. - -<13> Optional: Specify the size of a VM's memory in MiB. - -<14> Optional: Root disk of the node. - -<15> Optional: Specify the size of the bootable disk in GiB. - -<16> Optional: List of the network interfaces of the VM. If you include this parameter, {product-title} discards all network interfaces from the template and creates new ones. - -<17> Optional: Specify the vNIC profile ID. - -<18> Specify the name of the secret that holds the {rh-virtualization} credentials. -<19> Optional: Specify the workload type for which the instance is optimized. This value affects the `{rh-virtualization} VM` parameter. Supported values: `desktop`, `server`, `high_performance`. - -[NOTE] -==== -Because {rh-virtualization} uses a template when creating a VM, if you do not specify a value for an optional parameter, {rh-virtualization} uses the value for that parameter that is specified in the template. -==== diff --git a/modules/machineset-yaml-vsphere.adoc b/modules/machineset-yaml-vsphere.adoc deleted file mode 100644 index a39d984eb2e8..000000000000 --- a/modules/machineset-yaml-vsphere.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/creating-infrastructure-machinesets.adoc -// * machine_management/creating_machinesets/creating-machineset-vsphere.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="machineset-yaml-vsphere_{context}"] -= Sample YAML for a machine set custom resource on vSphere - -This sample YAML defines a machine set that runs on VMware vSphere and creates nodes that are labeled with `node-role.kubernetes.io/<role>: ""`. - -In this sample, `<infrastructure_id>` is the infrastructure ID label that is based on the cluster ID that you set when you provisioned the cluster, and `<role>` is the node label to add. - -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - creationTimestamp: null - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - name: <infrastructure_id>-<role> <2> - namespace: openshift-machine-api -spec: - replicas: 1 - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role> <2> - template: - metadata: - creationTimestamp: null - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machine-role: <role> <3> - machine.openshift.io/cluster-api-machine-type: <role> <3> - machine.openshift.io/cluster-api-machineset: <infrastructure_id>-<role> <2> - spec: - metadata: - creationTimestamp: null - labels: - node-role.kubernetes.io/<role>: "" <3> - providerSpec: - value: - apiVersion: vsphereprovider.openshift.io/v1beta1 - credentialsSecret: - name: vsphere-cloud-credentials - diskGiB: 120 - kind: VSphereMachineProviderSpec - memoryMiB: 8192 - metadata: - creationTimestamp: null - network: - devices: - - networkName: "<vm_network_name>" <4> - numCPUs: 4 - numCoresPerSocket: 1 - snapshot: "" - template: <vm_template_name> <5> - userDataSecret: - name: worker-user-data - workspace: - datacenter: <vcenter_datacenter_name> <6> - datastore: <vcenter_datastore_name> <7> - folder: <vcenter_vm_folder_path> <8> - resourcepool: <vsphere_resource_pool> <9> - server: <vcenter_server_ip> <10> ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. If you have the OpenShift CLI (`oc`) installed, you can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- -<2> Specify the infrastructure ID and node label. -<3> Specify the node label to add. -<4> Specify the vSphere VM network to deploy the machine set to. -<5> Specify the vSphere VM template to use, such as `user-5ddjd-rhcos`. -<6> Specify the vCenter Datacenter to deploy the machine set on. -<7> Specify the vCenter Datastore to deploy the machine set on. -<8> Specify the path to the vSphere VM folder in vCenter, such as `/dc1/vm/user-inst-5ddjd`. -<9> Specify the vSphere resource pool for your VMs. -<10> Specify the vCenter server IP or fully qualified domain name. diff --git a/modules/manage-access-for-specific-users-or-groups.adoc b/modules/manage-access-for-specific-users-or-groups.adoc new file mode 100644 index 000000000000..d7536b557ad0 --- /dev/null +++ b/modules/manage-access-for-specific-users-or-groups.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +// applies to old versions, do not maintain +:_mod-docs-content-type: PROCEDURE +[id="manage-access-for-specific-users-or-groups_{context}"] += Managing access for specific users or groups + +[role="_abstract"] +In addition to setting up a *Minimum access role*, you can create rules that govern access to {product-title} resources. +You can create and apply these rules based on the metadata keys and values you set up in your authentication provider. + +[NOTE] +==== +The metadata keys are always dependent upon the configurations in your authentication provider. +For example: + +* Allowed metadata keys for OpenID Connect (OIDC) are only: +** `name` +** `email` +** `uid` +** `groups` +* However, for Security Assertion Markup Language (SAML)-based authentication providers, there are no restrictions and you can define custom attributes as metadata keys. +==== + +.Prerequisites +* You must have the *Admin* role, or read and write permissions for the `Access` resource to create, modify, and delete custom roles. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Under *Auth Providers*, select the authentication provider for which you want to configure user roles. +. Click *Edit Provider*. +. Under section 2 *Assign StackRox roles to your <auth_provider> users*, click on *Add New Rule*. +. Click on the *Key* to which this role applies. +. Select a *Value* for the key. +. Select the *Role* you want to assign to users matching the specified key and value. +. Click *Save*. + +[NOTE] +==== +* You can add more than one rule using these steps. +* When you select a *Value*, only users who accessed the system before using that value appear as an option. +You can type in custom values for users who did not log in yet. +* If a user matches to more than one of the defined rules, the user gets permissions from every matching rule. +==== diff --git a/modules/managing-central-log-level.adoc b/modules/managing-central-log-level.adoc new file mode 100644 index 000000000000..dcc2b77caf20 --- /dev/null +++ b/modules/managing-central-log-level.adoc @@ -0,0 +1,8 @@ +// Module included in the following assemblies: +// +// * cli/debugging-issues.adoc +:_mod-docs-content-type: CONCEPT +[id="managing-central-log-level_{context}"] += Managing Central log level + +You can use these logs to debug issues with the system. \ No newline at end of file diff --git a/modules/managing-feature-flags.adoc b/modules/managing-feature-flags.adoc new file mode 100644 index 000000000000..c5c6ee0534af --- /dev/null +++ b/modules/managing-feature-flags.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * configuration/managing-preview-features.adoc + +:_mod-docs-content-type: PROCEDURE +[id="managing-feature-flags_{context}"] += Managing feature flags + +[id="prerequisites_{context}"] +== Prerequisites +* You have access to the environment where the {product-title-short} component is deployed. +* You have permission to modify environment variables. +* You understand that the Technology Preview features might be incomplete and are provided with limited support. +* You know if the flag for the Technology Preview feature needs to be configured before the deployment. Check the installation manifests to see if they use the required flag. + +.Procedure + +. Identify the environment variable name associated with the feature flag. +Consult the release notes or the `/v1/featureflags` API endpoint to identify the flag for the feature you want to enable or disable. + +. Modify the feature flag by completing one of the following actions: +* To enable a feature, configure the environment variable associated with the flag by setting its value to `true`. Configure this directly on the Kubernetes deployment or during installation by using the Helm chart or the Operator custom resource (CR). +* To disable a feature, set the environment variable associated with the flag to `false`. + +. After the application is restarted or redeployed, verify that the feature has been enabled or disabled by completing the following steps: + +* Check the output of the `/v1/featureflags` API endpoint. +* Check the application functionality related to the feature. +* Review logs or monitoring tools for any errors or confirmation messages. + +[id="best-practices_{context}"] +== Best practices +Follow these best practices for using the feature flag: + +* Always test feature changes in a staging environment before applying them to production. +* Keep a record of all feature flags and their current status. +* Be prepared to revert the changes if the feature causes issues. + +[id="troubleshooting_{context}"] +== Troubleshooting +Follow these troubleshooting guidelines: + +* If the feature does not appear, ensure that the environment variable is correctly named and set. Check application logs for any errors related to feature flag parsing. +* If enabling a feature causes application errors, disable the feature and contact Red Hat Support. diff --git a/modules/manual-configuration-image-registry-acr.adoc b/modules/manual-configuration-image-registry-acr.adoc new file mode 100644 index 000000000000..0b97e241c2e4 --- /dev/null +++ b/modules/manual-configuration-image-registry-acr.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-acr_{context}"] += Manually configuring Microsoft Azure Container Registry + +You can integrate {product-title} with Microsoft Azure Container Registry. + +.Prerequisites +* You have either an Azure managed or Azure workload identity. ++ +For more information about Azure managed identities, see link:https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview[What are managed identities for Azure resources?] (Microsoft Azure documentation). ++ +For more information about Azure workload identities, see link:https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation[Workload identity federation] (Microsoft Azure documentation). +* You have the *Reader* role for the identity over a scope that includes the container registry. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Microsoft Azure Container Registry*. +. Click *New integration*. +. Enter the details for the following fields: +.. *Integration name*: The name of the integration. +.. *Endpoint*: The address of the registry. +.. *Username* and *Password*. +.. Optional: Select the *Use workload identity* checkbox, if you want to authenticate by using an Azure managed or workload identity. +. Select *Create integration without testing* to create the integration without testing the connection to the registry. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/manual-configuration-image-registry-dtr.adoc b/modules/manual-configuration-image-registry-dtr.adoc new file mode 100644 index 000000000000..de68379a2e25 --- /dev/null +++ b/modules/manual-configuration-image-registry-dtr.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-dtr_{context}"] += Manually configuring Docker Trusted Registry + +You can integrate {product-title} with Docker Trusted Registry. + +.Prerequisites +* You must have a username and a password for authentication with the Docker Trusted Registry. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Docker Trusted Registry*. +. Click *New integration*. +. Enter the details for the following fields: +.. *Integration name*: The name of the integration. +.. *Type*: Select *Registry*. +.. *Endpoint*: The address of the registry. +.. *Username* and *Password*. +. If you are not using a TLS certificate when connecting to the registry, select *Disable TLS certificate validation (insecure)*. +. Select *Create integration without testing* to create the integration without testing the connection to the registry. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/manual-configuration-image-registry-ecr.adoc b/modules/manual-configuration-image-registry-ecr.adoc new file mode 100644 index 000000000000..424a30671303 --- /dev/null +++ b/modules/manual-configuration-image-registry-ecr.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-ecr_{context}"] += Manually configuring Amazon Elastic Container Registry + +You can use {product-title} to create and modify Amazon Elastic Container Registry (ECR) integrations manually. If you are deploying from Amazon ECR, integrations for the Amazon ECR registries are usually automatically generated. However, you might want to create integrations on your own to scan images outside deployments. You can also modify the parameters of an automatically-generated integration. For example, you can change the authentication method used by an automatically-generated Amazon ECR integration to use AssumeRole authentication or other authorization models. + +[IMPORTANT] +==== +To erase changes you made to an automatically-generated ECR integration, delete the integration, and {product-title} creates a new integration for you with the automatically-generated parameters when you deploy images from Amazon ECR. +==== + +.Prerequisites +* You must have an Amazon Identity and Access Management (IAM) access key ID and a secret access key. Alternatively, you can use a node-level IAM proxy such as `kiam` or `kube2iam`. +* The access key must have read access to ECR. See link:https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/[How do I create an AWS access key?] for more information. +* If you are running {product-title} in Amazon Elastic Kubernetes Service (EKS) and want to integrate with an ECR from a separate Amazon account, you must first set a repository policy statement in your ECR. Follow the instructions at link:https://docs.aws.amazon.com/AmazonECR/latest/userguide/set-repository-policy.html[Setting a repository policy statement] and for *Actions*, choose the following scopes of the Amazon ECR API operations: + +** ecr:BatchCheckLayerAvailability +** ecr:BatchGetImage +** ecr:DescribeImages +** ecr:GetDownloadUrlForLayer +** ecr:ListImages + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Amazon ECR*. +. Click *New integration*, or click one of the automatically-generated integrations to open it, then click *Edit*. +. Enter or modify the details for the following fields: +.. *Update stored credentials*: Clear this box if you are modifying an integration without updating the credentials such as access keys and passwords. +.. *Integration name*: The name of the integration. +.. *Registry ID*: The ID of the registry. +.. *Endpoint*: The address of the registry. This value is required only if you are using a private virtual private cloud (VPC) endpoint for Amazon ECR. This field is not enabled when the AssumeRole option is selected. +.. *Region*: The region for the registry; for example, `us-west-1`. +. If you are using IAM, select *Use Container IAM role*. Otherwise, clear the *Use Container IAM role* box and enter the *Access key ID* and *Secret access key*. +. If you are using AssumeRole authentication, select *Use AssumeRole* and enter the details for the following fields: +.. *AssumeRole ID*: The ID of the role to assume. +.. *AssumeRole External ID* (optional): If you are using an link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html[external ID with AssumeRole], you can enter it here. +. Select *Create integration without testing* to create the integration without testing the connection to the registry. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/manual-configuration-image-registry-gar.adoc b/modules/manual-configuration-image-registry-gar.adoc new file mode 100644 index 000000000000..dc6eca9d2c6d --- /dev/null +++ b/modules/manual-configuration-image-registry-gar.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc + +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-gar_{context}"] += Manually configuring Google Artifact Registry + +You can integrate {rh-rhacs-first} with the Google Artifact Registry (GAR). + +.Prerequisites +* You have a workload identity or service account key for authentication. ++ +For more information, see link:https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity[Authenticate to Google Cloud APIs from GKE workloads] (Google Cloud documentation). +* You have the artifact registry reader Identity +and Access Management (IAM) role, `roles/artifactregistry.reader` for the associated service account. + +.Procedure +. In the {product-title-short} portal, click *Platform Configuration* -> *Integrations*. +. In the *Image Integrations* section, click *Google Artifact Registry*. +. To create a new integration, click *New integration*. +. Enter a name for your integration. +. Enter the address of your registry. +. Optional: Enter the name of your Google Cloud project. {product-title-short} matches the images against the project of the registry. If you do not specify the project name, {product-title-short} matches the images against all the projects. +. Optional: Select the *Use workload identity* checkbox to authenticate by using a workload identity. +. Enter your service account key for authentication. +. Optional: Select the *Create integration without testing* checkbox to create your integration without testing the connection to the registry. +. Optional: To test your integration with the selected registry, click *Test*. +. To save your integration, click *Save*. \ No newline at end of file diff --git a/modules/manual-configuration-image-registry-gcr.adoc b/modules/manual-configuration-image-registry-gcr.adoc new file mode 100644 index 000000000000..682346c3465d --- /dev/null +++ b/modules/manual-configuration-image-registry-gcr.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc + +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-gcr_{context}"] += Manually configuring Google Container Registry + +You can integrate {rh-rhacs-first} with Google Container Registry (GCR). + +.Prerequisites +* You have a workload identity or service account key for authentication. ++ +For more information, see link:https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity[Authenticate to Google Cloud APIs from GKE workloads] (Google Cloud documentation). +* You have access to the registry for the associated service account. ++ +For more information, see link:https://cloud.google.com/container-registry/docs/access-control[Access control with IAM] (Google Cloud documentation). +* You have granted the following roles to the service account, if you use GCR Container Analysis: ++ +** Container Analysis Notes Viewer +** Container Analysis Occurrences Viewer +** Storage Object Viewer ++ +For more information, see link:https://cloud.google.com/container-registry/docs/container-analysis[Container analysis and vulnerability scanning] (Google Cloud documentation). + +.Procedure +. In the {product-title-short} portal, click *Platform Configuration* -> *Integrations*. +. In the *Image Integrations* section, click *Google Container Registry*. +. To create a new integration, click *New integration*. +. Enter a name for your integration. +. Choose the appropriate type of integration that you want to configure: +** To configure an integration that includes the container image registry, select *Registry*. +** To configure an integration that includes Scanner, select *Scanner*. +** To configure an integration that includes the container image registry and Scanner, select *Registry+Scanner*. +. Enter the address of your registry. +. Optional: Enter the name of your Google Cloud project. {product-title-short} matches the images against the project of the registry. If you do not specify the project name, {product-title-short} matches the images against all the projects. +. Optional: Select the *Use workload identity* checkbox to authenticate by using a workload identity. +. Enter your service account key for authentication. +. Optional: Select the *Create integration without testing* checkbox to create your integration without testing the connection to the registry. +. Optional: To test your integration with the selected registry, click *Test*. +. To save your integration, click *Save*. \ No newline at end of file diff --git a/modules/manual-configuration-image-registry-ghcr.adoc b/modules/manual-configuration-image-registry-ghcr.adoc new file mode 100644 index 000000000000..4e3ef1b1d10f --- /dev/null +++ b/modules/manual-configuration-image-registry-ghcr.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-ghcr_{context}"] += Manually configuring GitHub Container Registry + +You can integrate {product-title} with GitHub Container Registry (GHCR). + +.Prerequisites +* You need a GitHub account and personal access token with at least `packages:read` permissions. See link:https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry[Working with the Container registry] for more information. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. In the *Image Integrations* section, select *GitHub Container Registry*. +. Click *New integration*. +. Enter the details for the following fields: +.. *Integration name*: The name of the integration. +.. *Endpoint*: The address of the registry. +.. *Username*: The GitHub username. Leave blank for anonymous access. +.. *GitHub Token*: The GitHub personal access token. Leave blank for anonymous access. +. Select *Create integration without testing* to create the integration without testing the connection to the registry. Enable this option to allow anonymous access. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/manual-configuration-image-registry-ibm.adoc b/modules/manual-configuration-image-registry-ibm.adoc new file mode 100644 index 000000000000..0d42b9022ce2 --- /dev/null +++ b/modules/manual-configuration-image-registry-ibm.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-ibm_{context}"] += Manually configuring IBM Cloud Container Registry + +You can integrate {product-title} with IBM Cloud Container Registry. + +.Prerequisites +* You must have an API key for authentication with the IBM Cloud Container Registry. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *IBM Cloud Container Registry*. +. Click *New integration*. +. Enter the details for the following fields: +.. *Integration name*: The name of the integration. +.. *Endpoint*: The address of the registry. +.. *API key*. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/manual-configuration-image-registry-jfrog.adoc b/modules/manual-configuration-image-registry-jfrog.adoc new file mode 100644 index 000000000000..7154e02c6afc --- /dev/null +++ b/modules/manual-configuration-image-registry-jfrog.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-jfrog_{context}"] += Manually configuring JFrog Artifactory + +You can integrate {product-title} with JFrog Artifactory. + +.Prerequisites +* You must have a username and a password for authentication with JFrog Artifactory. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *JFrog Artifactory*. +. Click *New integration*. +. Enter the details for the following fields: +.. *Integration name*: The name of the integration. +.. *Endpoint*: The address of the registry. +.. *Username* and *Password*. +. If you are not using a TLS certificate when connecting to the registry, select *Disable TLS certificate validation (insecure)*. +. Select *Create integration without testing* to create the integration without testing the connection to the registry. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/manual-configuration-image-registry-ocp.adoc b/modules/manual-configuration-image-registry-ocp.adoc new file mode 100644 index 000000000000..4bcfc5671114 --- /dev/null +++ b/modules/manual-configuration-image-registry-ocp.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-ocp_{context}"] += Manually configuring {ocp} registry + +You can integrate {product-title} with {ocp} built-in container image registry. + +.Prerequisites +* You need a username and a password for authentication with the {ocp} registry. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Generic Docker Registry*. +. Click *New integration*. +. Enter the details for the following fields: +.. *Integration name*: The name of the integration. +.. *Endpoint*: The address of the registry. +.. *Username* and *Password*. +. If you are not using a TLS certificate when connecting to the registry, select *Disable TLS certificate validation (insecure)*. +. Select *Create integration without testing* to create the integration without testing the connection to the registry. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/manual-configuration-image-registry-qcr.adoc b/modules/manual-configuration-image-registry-qcr.adoc new file mode 100644 index 000000000000..342dd5bdbba3 --- /dev/null +++ b/modules/manual-configuration-image-registry-qcr.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-qcr_{context}"] += Manually configuring Quay Container Registry + +You can integrate {product-title} ({product-title-short}) with Quay Container Registry. You can integrate with Quay by using the following methods: + +* Integrating with the Quay public repository (registry): This method does not require authentication. +* Integrating with a Quay private registry: + +** By using a robot account: This method requires that you create a robot account to use with Quay (recommended). See the link:https://docs.redhat.com/en/documentation/red_hat_quay/3.14/html/about_quay_io/allow-robot-access-user-repo[Red{nbsp}Hat Quay Robot Account overview] topic in Quay documentation for more information. +** By using keyless authentication with external secret: This method uses OIDC federation and the External Secrets Operator (ESO). For more information, see "Enabling Quay registry keyless authentication using external secret". + +* Integrating with Quay to use the Quay scanner rather than the {product-title-short} scanner: This method uses the API and requires an OAuth token for authentication. For more information, see "Integrating with Quay Container Registry to scan images" in the "Additional resources" section. + +.Prerequisites +* For authentication with a Quay private registry, you need the credentials associated with a robot account or an OAuth token (deprecated). + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Red{nbsp}Hat Quay.io*. +. Click *New integration*. +. Enter the *Integration name.* +. Enter the *Endpoint*, or the address of the registry. +.. If you are integrating with the Quay public repository, under *Type*, select *Registry*, and then go to the next step. +.. If you are integrating with a Quay private registry, under *Type*, select *Registry* and enter information in the following fields: +** *Robot username*: If you are accessing the registry by using a Quay robot account, enter the user name in the format `_<namespace>+<accountname>_`. +** *Robot password*: If you are accessing the registry by using a Quay robot account, enter the password for the robot account user name. +** *OAuth token*: If you are accessing the registry by using an OAuth token (deprecated), enter it in this field. +. Optional: If you are not using a TLS certificate when connecting to the registry, select *Disable TLS certificate validation (insecure)*. +. Optional: To create the integration without testing, select *Create integration without testing*. +. Select *Save*. + +[NOTE] +==== +If you are editing a Quay integration but do not want to update your credentials, verify that *Update stored credentials* is not selected. +==== \ No newline at end of file diff --git a/modules/manual-configuration-image-registry-redhat.adoc b/modules/manual-configuration-image-registry-redhat.adoc new file mode 100644 index 000000000000..ee9a4c1c78f9 --- /dev/null +++ b/modules/manual-configuration-image-registry-redhat.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-configuration-image-registry-redhat_{context}"] += Manually configuring Red Hat Container Registry + +You can integrate {product-title} with Red{nbsp}Hat Container Registry. + +.Prerequisites +* You must have a username and a password for authentication with the Red{nbsp}Hat Container Registry. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *Image Integrations* section, select *Red{nbsp}Hat Registry*. +. Click *New integration*. +. Enter the details for the following fields: +.. *Integration name*: The name of the integration. +.. *Endpoint*: The address of the registry. +.. *Username* and *Password*. +. Select *Create integration without testing* to create the integration without testing the connection to the registry. +. Select *Test* to test that the integration with the selected registry is working. +. Select *Save*. diff --git a/modules/manual-upgrade-secured-clusters.adoc b/modules/manual-upgrade-secured-clusters.adoc new file mode 100644 index 000000000000..badd492a1b57 --- /dev/null +++ b/modules/manual-upgrade-secured-clusters.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * configuration/configure-automatic-upgrades.adoc +:_mod-docs-content-type: PROCEDURE +[id="manual-upgrade-secured-clusters_{context}"] += Upgrading secured clusters manually from the RHACS portal + +If you do not want to enable automatic upgrades, you can manage your secured cluster upgrades by using the *Clusters* view. + +To manually trigger upgrades for your secured clusters: + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. +. Take one of the following actions: +* To upgrade a single cluster, select the *Upgrade available* option under the *Sensor Upgrade* column for the cluster you want to upgrade. +* To upgrade multiple clusters at a time, select the checkboxes next to the *Name* column for the clusters you want to update, and then click *Upgrade*. diff --git a/modules/manually-create-identity-access-management.adoc b/modules/manually-create-identity-access-management.adoc deleted file mode 100644 index 5e3a74291df0..000000000000 --- a/modules/manually-create-identity-access-management.adoc +++ /dev/null @@ -1,176 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/manually-creating-iam.adoc -// * installing/installing_azure/manually-creating-iam-azure.adoc -// * installing/installing_gcp/manually-creating-iam-gcp.adoc - -ifeval::["{context}" == "manually-creating-iam-aws"] -:aws: -endif::[] -ifeval::["{context}" == "manually-creating-iam-azure"] -:azure: -endif::[] -ifeval::["{context}" == "manually-creating-iam-gcp"] -:google-cloud-platform: -endif::[] - -[id="manually-create-iam_{context}"] -= Manually create IAM - -The Cloud Credential Operator (CCO) can be put into manual mode prior to -installation in environments where the cloud identity and access management -(IAM) APIs are not reachable, or the administrator prefers not to store an -administrator-level credential secret in the cluster `kube-system` namespace. - -.Procedure - -. Change to the directory that contains the installation program and create the `install-config.yaml` file: -+ -[source,terminal] ----- -$ openshift-install create install-config --dir=<installation_directory> ----- - -. Edit the `install-config.yaml` configuration file so that it contains the `credentialsMode` parameter set to `Manual`. -+ -.Example `install-config.yaml` configuration file -[source,yaml] ----- -apiVersion: v1 -baseDomain: cluster1.example.com -credentialsMode: Manual <1> -compute: -- architecture: amd64 - hyperthreading: Enabled -... ----- -<1> This line is added to set the `credentialsMode` parameter to `Manual`. - -. To generate the manifests, run the following command from the directory that contains the installation program: -+ -[source,terminal] ----- -$ openshift-install create manifests --dir=<installation_directory> <1> ----- -<1> For `<installation_directory>`, specify the directory name to store the -files that the installation program creates. - -. From the directory that contains the installation program, obtain details of the {product-title} release image that your `openshift-install` binary is built to use: -+ -[source,terminal] ----- -$ openshift-install version ----- -+ -.Example output -[source,terminal] ----- -release image quay.io/openshift-release-dev/ocp-release:4.y.z-x86_64 ----- - -. Locate all `CredentialsRequest` objects in this release image that target the cloud you are deploying on: -+ -[source,terminal] -ifdef::aws[] ----- -$ oc adm release extract quay.io/openshift-release-dev/ocp-release:4.y.z-x86_64 --credentials-requests --cloud=aws ----- -endif::aws[] -ifdef::azure[] ----- -$ oc adm release extract quay.io/openshift-release-dev/ocp-release:4.y.z-x86_64 --credentials-requests --cloud=azure ----- -endif::azure[] -ifdef::google-cloud-platform[] ----- -$ oc adm release extract quay.io/openshift-release-dev/ocp-release:4.y.z-x86_64 --credentials-requests --cloud=gcp ----- -endif::google-cloud-platform[] -+ -This command creates a YAML file for each `CredentialsRequest` object. -+ -ifdef::aws[] -.Sample `CredentialsRequest` object -[source,yaml] ----- -apiVersion: cloudcredential.openshift.io/v1 -kind: CredentialsRequest -metadata: - name: cloud-credential-operator-iam-ro - namespace: openshift-cloud-credential-operator -spec: - secretRef: - name: cloud-credential-operator-iam-ro-creds - namespace: openshift-cloud-credential-operator - providerSpec: - apiVersion: cloudcredential.openshift.io/v1 - kind: AWSProviderSpec - statementEntries: - - effect: Allow - action: - - iam:GetUser - - iam:GetUserPolicy - - iam:ListAccessKeys - resource: "*" ----- -endif::aws[] -ifdef::azure[] -.Sample `CredentialsRequest` object -[source,yaml] ----- -apiVersion: cloudcredential.openshift.io/v1 -kind: CredentialsRequest -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: openshift-image-registry-azure - namespace: openshift-cloud-credential-operator -spec: - secretRef: - name: installer-cloud-credentials - namespace: openshift-image-registry - providerSpec: - apiVersion: cloudcredential.openshift.io/v1 - kind: AzureProviderSpec - roleBindings: - - role: Contributor ----- -endif::azure[] -ifdef::google-cloud-platform[] -.Sample `CredentialsRequest` object -[source,yaml] ----- -apiVersion: cloudcredential.openshift.io/v1 -kind: CredentialsRequest -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: openshift-image-registry-gcs - namespace: openshift-cloud-credential-operator -spec: - secretRef: - name: installer-cloud-credentials - namespace: openshift-image-registry - providerSpec: - apiVersion: cloudcredential.openshift.io/v1 - kind: GCPProviderSpec - predefinedRoles: - - roles/storage.admin - - roles/iam.serviceAccountUser - skipServiceCheck: true ----- -endif::google-cloud-platform[] - -. Create YAML files for secrets in the `openshift-install` manifests directory that you generated previously. The secrets must be stored using the namespace and secret name defined in the `spec.secretRef` for each `CredentialsRequest` object. The format for the secret data varies for each cloud provider. - -. From the directory that contains the installation program, proceed with your cluster creation: -+ -[source,terminal] ----- -$ openshift-install create cluster --dir=<installation_directory> ----- -+ -[IMPORTANT] -==== -Before upgrading a cluster that uses manually maintained credentials, you must ensure that the CCO is in an upgradeable state. For details, see the _Upgrading clusters with manually maintained credentials_ section of the installation content for your cloud provider. -==== diff --git a/modules/manually-gathering-logs-with-ssh.adoc b/modules/manually-gathering-logs-with-ssh.adoc deleted file mode 100644 index e4845899d39f..000000000000 --- a/modules/manually-gathering-logs-with-ssh.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/installing-troubleshooting.adoc - -[id="installation-manually-gathering-logs-with-SSH_{context}"] -= Manually gathering logs with SSH access to your host(s) - -Manually gather logs in situations where `must-gather` or automated collection -methods do not work. - -.Prerequisites - -* You must have SSH access to your host(s). - -.Procedure - -. Collect the `bootkube.service` service logs from the bootstrap host using the -`journalctl` command by running: -+ -[source,terminal] ----- -$ journalctl -b -f -u bootkube.service ----- - -. Collect the bootstrap host's container logs using the podman logs. This is shown -as a loop to get all of the container logs from the host: -+ -[source,terminal] ----- -$ for pod in $(sudo podman ps -a -q); do sudo podman logs $pod; done ----- - -. Alternatively, collect the host's container logs using the `tail` command by -running: -+ -[source,terminal] ----- -# tail -f /var/lib/containers/storage/overlay-containers/*/userdata/ctr.log ----- - -. Collect the `kubelet.service` and `crio.service` service logs from the master -and worker hosts using the `journalctl` command by running: -+ -[source,terminal] ----- -$ journalctl -b -f -u kubelet.service -u crio.service ----- - -. Collect the master and worker host container logs using the `tail` command by -running: -+ -[source,terminal] ----- -$ sudo tail -f /var/log/containers/* ----- diff --git a/modules/manually-gathering-logs-without-ssh.adoc b/modules/manually-gathering-logs-without-ssh.adoc deleted file mode 100644 index 2e40bed32de0..000000000000 --- a/modules/manually-gathering-logs-without-ssh.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/installing-troubleshooting.adoc - -[id="installation-manually-gathering-logs-without-SSH_{context}"] -= Manually gathering logs without SSH access to your host(s) - -Manually gather logs in situations where `must-gather` or automated collection -methods do not work. - -If you do not have SSH access to your node, you can access the systems journal -to investigate what is happening on your host. - -.Prerequisites - -* Your {product-title} installation must be complete. -* Your API service is still functional. -* You have system administrator privileges. - -.Procedure - -. Access `journald` unit logs under `/var/log` by running: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u kubelet ----- - -. Access host file paths under `/var/log` by running: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master --path=openshift-apiserver ----- diff --git a/modules/manually-maintained-credentials-upgrade.adoc b/modules/manually-maintained-credentials-upgrade.adoc deleted file mode 100644 index 5592a9f61412..000000000000 --- a/modules/manually-maintained-credentials-upgrade.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/manually-creating-iam.adoc -// * installing/installing_azure/manually-creating-iam-azure.adoc -// * installing/installing_gcp/manually-creating-iam-gcp.adoc -// * authentication/managing_cloud_provider_credentials/cco-mode-manual.adoc - -[id="manually-maintained-credentials-upgrade_{context}"] -= Upgrading clusters with manually maintained credentials - -If credentials are added in a future release, the Cloud Credential Operator (CCO) `upgradable` status for a cluster with manually maintained credentials changes to `false`. For minor release, for example, from 4.6 to 4.7, this status prevents you from upgrading until you have addressed any updated permissions. For z-stream releases, for example, from 4.6.10 to 4.6.11, the upgrade is not blocked, but the credentials must still be updated for the new release. - -Use the *Administrator* perspective of the web console to determine if the CCO is upgradeable. - -. Navigate to *Administration* -> *Cluster Settings*. - -. To view the CCO status details, click *cloud-credential* in the *Cluster Operators* list. - -. If the *Upgradeable* status in the *Conditions* section is *False*, examine the `CredentialsRequest` custom resource for the new release and update the manually maintained credentials on your cluster to match before upgrading. - -In addition to creating new credentials for the release image that you are -upgrading to, you must review the required permissions for existing credentials -and accommodate any new permissions requirements for existing components in the -new release. The CCO cannot detect these mismatches and will not set -`upgradable` to `false` in this case. - -The _Manually creating IAM_ section of the installation content for your cloud provider explains how to obtain and use the credentials required for your cloud. diff --git a/modules/manually-removing-cloud-creds.adoc b/modules/manually-removing-cloud-creds.adoc deleted file mode 100644 index 0598126b5436..000000000000 --- a/modules/manually-removing-cloud-creds.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/cluster-tasks.adoc - -[id="manually-removing-cloud-creds_{context}"] -= Removing cloud provider credentials - -After installing an {product-title} cluster with the Cloud Credential Operator (CCO) in mint mode, you can remove the administrator-level credential secret from the `kube-system` namespace in the cluster. The administrator-level credential is not required unless something that requires an administrator-level credential needs to be changed, for instance during an upgrade. - -[NOTE] -==== -Prior to a non z-stream upgrade, you must reinstate the credential secret with the administrator-level credential. If the credential is not present, the upgrade might be blocked. -==== - -.Prerequisites - -* Your cluster is installed on a platform that supports removing cloud credentials from the CCO. Supported platforms are AWS and GCP. - -.Procedure - -. In the *Administrator* perspective of the web console, navigate to *Workloads* -> *Secrets*. - -. In the table on the *Secrets* page, find the root secret for your cloud provider. -+ -[cols=2,options=header] -|=== -|Platform -|Secret name - -|AWS -|`aws-creds` - -|GCP -|`gcp-credentials` - -|=== - -. Click the *Options* menu {kebab} in the same row as the secret and select *Delete Secret*. diff --git a/modules/manually-rotating-cloud-creds.adoc b/modules/manually-rotating-cloud-creds.adoc deleted file mode 100644 index 50a260d40c27..000000000000 --- a/modules/manually-rotating-cloud-creds.adoc +++ /dev/null @@ -1,159 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/cluster-tasks.adoc - -[id="manually-rotating-cloud-creds_{context}"] -= Rotating cloud provider credentials manually - -If your cloud provider credentials are changed for any reason, you must manually update the secret that the Cloud Credential Operator (CCO) uses to manage cloud provider credentials. - -The process for rotating cloud credentials depends on the mode that the CCO is configured to use. After you rotate credentials for a cluster that is using mint mode, you must manually remove the component credentials that were created by the removed credential. - -//// -[NOTE] -==== -You can also use the command line interface to complete all parts of this procedure. -==== -//// - -.Prerequisites - -* Your cluster is installed on a platform that supports rotating cloud credentials manually with the CCO mode that you are using: - -** For mint mode, AWS, Azure, and GCP are supported. - -** For passthrough mode, AWS, Azure, GCP, {rh-openstack-first}, {rh-virtualization-first}, and VMware vSphere are supported. - -* You have changed the credentials that are used to interface with your cloud provider. - -* The new credentials have sufficient permissions for the mode CCO is configured to use in your cluster. - -.Procedure - -. In the *Administrator* perspective of the web console, navigate to *Workloads* -> *Secrets*. - -. In the table on the *Secrets* page, find the root secret for your cloud provider. -+ -[cols=2,options=header] -|=== -|Platform -|Secret name - -|AWS -|`aws-creds` - -|Azure -|`azure-credentials` - -|GCP -|`gcp-credentials` - -|=== - -. Click the *Options* menu {kebab} in the same row as the secret and select *Edit Secret*. - -. Record the contents of the *Value* field or fields. You can use this information to verify that the value is different after updating the credentials. - -. Update the text in the *Value* field or fields with the new authentication information for your cloud provider, and then click *Save*. - -. If the CCO for your cluster is configured to use mint mode, delete each component secret that is referenced by the individual `CredentialsRequest` objects. - -.. Log in to the {product-title} CLI as a user with the `cluster-admin` role. - -.. Get the names and namespaces of all referenced component secrets: -+ -[source,terminal] ----- -$ oc -n openshift-cloud-credential-operator get CredentialsRequest -o json | jq -r '.items[] | select (.spec[].kind=="<provider_spec>") | .spec.secretRef' ----- -+ -Where `<provider_spec>` is the corresponding value for your cloud provider: `AWSProviderSpec` for AWS, `AzureProviderSpec` for Azure, or `GCPProviderSpec` for GCP. -+ -.Partial example output for AWS -+ -[source,json] ----- -{ - "name": "ebs-cloud-credentials", - "namespace": "openshift-cluster-csi-drivers" -} -{ - "name": "cloud-credential-operator-iam-ro-creds", - "namespace": "openshift-cloud-credential-operator" -} -... ----- - -.. Delete each of the referenced component secrets: -+ -[source,terminal] ----- -$ oc delete secret <secret_name> -n <secret_namespace> ----- -+ -Where `<secret_name>` is the name of a secret and `<secret_namespace>` is the namespace that contains the secret. -+ -.Example deletion of an AWS secret -+ -[source,terminal] ----- -$ oc delete secret ebs-cloud-credentials -n openshift-cluster-csi-drivers ----- -+ -You do not need to manually delete the credentials from your provider console. Deleting the referenced component secrets will cause the CCO to delete the existing credentials from the platform and create new ones. - -. To verify that the credentials have changed: - -.. In the *Administrator* perspective of the web console, navigate to *Workloads* -> *Secrets*. - -.. Verify that the contents of the *Value* field or fields are different than the previously recorded information. - -//// -// Provider-side verification also possible, though cluster-side is cleaner process. -. To verify that the credentials have changed from the console of your cloud provider: - -.. Get the `CredentialsRequest` CR names for your platform: -+ -[source,terminal] ----- -$ oc -n openshift-cloud-credential-operator get CredentialsRequest -o json | jq -r '.items[] | select (.spec[].kind=="<provider_spec>") | .metadata.name' ----- -+ -Where `<provider_spec>` is the corresponding value for your cloud provider: `AWSProviderSpec` for AWS, `AzureProviderSpec` for Azure, or `GCPProviderSpec` for GCP. -+ -.Example output for AWS -+ -[source,terminal] ----- -aws-ebs-csi-driver-operator -cloud-credential-operator-iam-ro -openshift-image-registry -openshift-ingress -openshift-machine-api-aws ----- - -.. Get the IAM username that corresponds to each `CredentialsRequest` CR name: -+ -[source,terminal] ----- -$ oc get credentialsrequest <cr_name> -n openshift-cloud-credential-operator -o json | jq -r ".status.providerStatus" ----- -+ -Where `<cr_name>` is the name of a `CredentialsRequest` CR. -+ -.Example output for AWS -+ -[source,json] ----- -{ - "apiVersion": "cloudcredential.openshift.io/v1", - "kind": "AWSProviderStatus", - "policy": "<example-iam-username-policy>", - "user": "<example-iam-username>" -} ----- -+ -Where `<example-iam-username>` is the name of an IAM user on the cloud provider. - -.. For each IAM username, view the details for the user on the cloud provider. The credentials should show that they were created after being rotated on the cluster. -//// diff --git a/modules/master-node-sizing.adoc b/modules/master-node-sizing.adoc deleted file mode 100644 index a49b4dc1cfdb..000000000000 --- a/modules/master-node-sizing.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/recommended-host-practices.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="master-node-sizing_{context}"] -= Control plane node sizing - -The control plane node resource requirements depend on the number of nodes in the cluster. The following control plane node size recommendations are based on the results of control plane density focused testing. - -[options="header",cols="3*"] -|=== -| Number of worker nodes |CPU cores |Memory (GB) - -| 25 -| 4 -| 16 - -| 100 -| 8 -| 32 - -| 250 -| 16 -| 96 - -|=== - -[IMPORTANT] -==== -Because you cannot modify the control plane node size in a running {product-title} {product-version} cluster, you must estimate your total node count and use the suggested control plane node size during installation. -==== - -[NOTE] -==== -In {product-title} {product-version}, half of a CPU core (500 millicore) is now reserved by the system by default compared to {product-title} 3.11 and previous versions. The sizes are determined taking that into consideration. -==== diff --git a/modules/medium-sev-security-policies.adoc b/modules/medium-sev-security-policies.adoc new file mode 100644 index 000000000000..742fd84f4149 --- /dev/null +++ b/modules/medium-sev-security-policies.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/default-security-policies.adoc +:_mod-docs-content-type: REFERENCE +[id="medium-sev-security-policies_{context}"] += Medium severity security policies + +//// +In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly. + +Be sure to include a line break between the title and the module introduction. +//// + +[role="_abstract"] +The following table lists the default security policies in {product-title} that are of medium severity. The policies are organized by lifecycle stage. + +.Medium severity security policies +[options="header"] +|==== +|Life cycle stage |Name |Description | Status + +|Build |Docker CIS 4.4: Ensure images are scanned and rebuilt to include security patches |Alerts when images are not scanned and rebuilt to include security patches. It is important to scan images often to find vulnerabilities, rebuild the images to include security patches, and then instantiate containers for the images. |Disabled +|Deploy |30-Day Scan Age |Alerts when a deployment has not been scanned in 30 days. |Enabled +|Deploy |CAP_SYS_ADMIN capability added |Alerts when a deployment includes containers that are escalating with CAP_SYS_ADMIN. |Enabled +|Deploy |Container using read-write root filesystem |Alerts when a deployment includes containers that have read-write root file systems. |Disabled +|Deploy |Container with privilege escalation allowed |Alerts when a container might be running with unintended privileges, creating a security risk. This situation can happen when a container process that has more privileges than its parent process allows the container to run with unintended privileges. |Enabled +|Deploy |Deployments should have at least one Ingress Network Policy |Alerts if deployments are missing an Ingress Network Policy. |Disabled +|Deploy |Deployments with externally exposed endpoints |Detects if a deployment has any service that is externally exposed through any methods. Deployments with services exposed outside of the cluster are at a higher risk of attempted intrusions because they are reachable outside of the cluster. This policy provides an alert so that you can verify that service exposure outside of the cluster is required. If the service is only needed for intra-cluster communication, use service type ClusterIP. |Disabled +|Deploy |Docker CIS 5.1: Ensure that, if applicable, an AppArmor profile is enabled |Uses AppArmor to protect the Linux operating system and applications by enforcing a security policy that is known as an AppArmor profile. AppArmor is a Linux application security system that is available on some Linux distributions by default, such as Debian and Ubuntu. |Enabled +|Deploy |Docker CIS 5.15: Ensure that the host's process namespace is not shared |Creates process-level isolation between the containers and the host. The Process ID (PID) namespace isolates the process ID space, which means that processes in different PID namespaces can have the same PID. |Enabled +|Deploy |Docker CIS 5.16: Ensure that the host's IPC namespace is not shared |Alerts when the IPC namespace on the host is shared with containers. The IPC (POSIX/SysV IPC) namespace separates named shared memory segments, semaphores, and message queues. |Enabled +|Deploy| Docker CIS 5.19: Ensure mount propagation mode is not enabled |Alerts when mount propagation mode is enabled. When mount propagation mode is enabled, you can mount container volumes in Bidirectional, Host to Container, and None modes. Do not use Bidirectional mount propagation mode unless it is explicitly needed. |Enabled +|Deploy |Docker CIS 5.21: Ensure the default seccomp profile is not disabled |Alerts when the seccomp profile is disabled. The seccomp profile uses an allowlist to permit common system calls and blocks all others. |Disabled +|Deploy |Docker CIS 5.7: Ensure privileged ports are not mapped within containers |Alerts when privileged ports are mapped within containers. The TCP/IP port numbers that are lower than 1024 are privileged ports. Normal users and processes can not use them for security reasons, but containers might map their ports to privileged ports. |Enabled +|Deploy |Docker CIS 5.9 and 5.20: Ensure that the host's network namespace is not shared |Alerts when the host's network namespace is shared. When HostNetwork is enabled, the container is not placed inside a separate network stack, and the container's networking is not containerized. As a result, the container has full access to the host's network interfaces, and a shared UTS namespace is enabled. The UTS namespace provides isolation between the hostname and the NIS domain name, and it sets the hostname and the domain, which are visible to running processes in that namespace. Processes that run within containers do not typically require to know the hostname or the domain name, so the UTS namespace should not be shared with the host.|Enabled +|Deploy |Images with no scans|Alerts when a deployment includes images that were not scanned. |Disabled +|Runtime |Kubernetes Actions: Port Forward to Pod |Alerts when the Kubernetes API receives a port forward request. |Enabled +|Deploy |Mount Container Runtime Socket |Alerts when a deployment has a volume mount on the container runtime socket. |Enabled +|Deploy |Mounting Sensitive Host Directories |Alerts when a deployment mounts sensitive host directories. |Enabled +|Deploy |No resource requests or limits specified |Alerts when a deployment includes containers that do not have resource requests and limits. |Enabled +|Deploy |Pod Service Account Token Automatically Mounted |Protects pod default service account tokens from being compromised by minimizing the mounting of the default service account token to only those pods whose applications require interaction with the Kubernetes API. |Enabled +|Deploy |Privileged Container |Alerts when a deployment includes containers that run in privileged mode. |Enabled +|Runtime |crontab Execution |Detects the usage of the crontab scheduled jobs editor. |Enabled +|Runtime |Netcat Execution Detected |Detects when netcat runs in a container. |Enabled +|Runtime |OpenShift: Advanced Cluster Security Central Admin Secret Accessed |Alerts when someone accesses the Red{nbsp}Hat Advanced Cluster Security Central secret. |Enabled +|Runtime |OpenShift: Kubernetes Secret Accessed by an Impersonated User |Alerts when someone impersonates a user to access a secret in the cluster. |Enabled +|Runtime |Remote File Copy Binary Execution |Alerts when a deployment runs a remote file copy tool. |Enabled +|==== + + + +//// +[role="_additional-resources"] +.Additional resources + +* A bulleted list of links to other closely-related material. These links can include `link:` and `xref:` macros. +* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. +//// \ No newline at end of file diff --git a/modules/metering-cluster-capacity-examples.adoc b/modules/metering-cluster-capacity-examples.adoc deleted file mode 100644 index 5fd550066ba1..000000000000 --- a/modules/metering-cluster-capacity-examples.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-usage-examples.adoc - -[id="metering-cluster-capacity-examples_{context}"] -= Measure cluster capacity hourly and daily - -The following Report demonstrates how to measure cluster capacity both hourly and daily. The daily Report works by aggregating the hourly Report's results. - -The following report measures cluster CPU capacity every hour. - -.Hourly CPU capacity by cluster example - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: cluster-cpu-capacity-hourly -spec: - query: "cluster-cpu-capacity" - schedule: - period: "hourly" <1> ----- -<1> You could change this period to `daily` to get a daily report, but with larger data sets it is more efficient to use an hourly report, then aggregate your hourly data into a daily report. - -The following report aggregates the hourly data into a daily report. - -.Daily CPU capacity by cluster example - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: cluster-cpu-capacity-daily <1> -spec: - query: "cluster-cpu-capacity" <2> - inputs: <3> - - name: ClusterCpuCapacityReportName - value: cluster-cpu-capacity-hourly - schedule: - period: "daily" ----- - -<1> To stay organized, remember to change the name of your Report if you change any of the other values. -<2> You can also measure `cluster-memory-capacity`. Remember to update the query in the associated hourly report as well. -<3> The `inputs` section configures this report to aggregate the hourly report. Specifically, `value: cluster-cpu-capacity-hourly` is the name of the hourly report that gets aggregated. diff --git a/modules/metering-cluster-usage-examples.adoc b/modules/metering-cluster-usage-examples.adoc deleted file mode 100644 index 227f5e85e97b..000000000000 --- a/modules/metering-cluster-usage-examples.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-usage-examples.adoc - -[id="metering-cluster-usage-examples_{context}"] -= Measure cluster usage with a one-time Report - -The following Reports to measure cluster usage from a specific starting date forward. The Report only runs once, after you save it and apply it. - -.CPU usage by cluster example - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: cluster-cpu-usage-2019 <1> -spec: - reportingStart: '2019-01-01T00:00:00Z' <2> - reportingEnd: '2019-12-30T23:59:59Z' - query: cluster-cpu-usage <3> - runImmediately: true <4> ----- -<1> To stay organized, remember to change the name of your Report if you change any of the other values. -<2> Configures the Reports to start using data from the `reportingStart` timestamp until the `reportingEnd` timestamp. -<3> Adjust your query here. You can also measure cluster usage with the `cluster-memory-usage` query. -<4> This tells the Report to run immediately after saving it and applying it. diff --git a/modules/metering-cluster-utilization-examples.adoc b/modules/metering-cluster-utilization-examples.adoc deleted file mode 100644 index c31fcfb2737a..000000000000 --- a/modules/metering-cluster-utilization-examples.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-usage-examples.adoc - -[id="metering-cluster-utilization-examples_{context}"] -= Measure cluster utilization using cron expressions - -You can also use cron expressions when configuring the period of your reports. The following report measures cluster utilization by looking at CPU utilization from 9am-5pm every weekday. - -.Weekday CPU utilization by cluster example - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: cluster-cpu-utilization-weekdays <1> -spec: - query: "cluster-cpu-utilization" <2> - schedule: - period: "cron" - expression: 0 0 * * 1-5 <3> ----- -<1> To say organized, remember to change the name of your Report if you change any of the other values. -<2> Adjust your query here. You can also measure cluster utilization with the `cluster-memory-utilization` query. -<3> For cron periods, normal cron expressions are valid. diff --git a/modules/metering-configure-persistentvolumes.adoc b/modules/metering-configure-persistentvolumes.adoc deleted file mode 100644 index eba2b89dc84a..000000000000 --- a/modules/metering-configure-persistentvolumes.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-hive-metastore.adoc - -[id="metering-configure-persistentvolumes_{context}"] -= Configuring PersistentVolumes - -By default, Hive requires one PersistentVolume to operate. - -`hive-metastore-db-data` is the main PersistentVolumeClaim (PVC) required by default. This PVC is used by the Hive metastore to store metadata about tables, such as table name, columns, and location. Hive metastore is used by Presto and the Hive server to look up table metadata when processing queries. You remove this requirement by using MySQL or PostgreSQL for the Hive metastore database. - -To install, Hive metastore requires that dynamic volume provisioning be enabled via a StorageClass, a persistent volume of the correct size must be manually pre-created, or that you use a pre-existing MySQL or PostgreSQL database. - -== Configuring the storage class for Hive metastore -To configure and specify a StorageClass for the `hive-metastore-db-data` PVC, specify the StorageClass in your MeteringConfig. An example StorageClass section is included in `metastore-storage.yaml` file below. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - hive: - spec: - metastore: - storage: - # Default is null, which means using the default storage class if it exists. - # If you wish to use a different storage class, specify it here - # class: "null" <1> - size: "5Gi" ----- -<1> Uncomment this line and replace `null` with the name of the StorageClass to use. Leaving the value `null` will cause metering to use the default StorageClass for the cluster. - -== Configuring the volume sizes for the Hive Metastore -Use the `metastore-storage.yaml` file below as a template. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - hive: - spec: - metastore: - storage: - # Default is null, which means using the default storage class if it exists. - # If you wish to use a different storage class, specify it here - # class: "null" - size: "5Gi" <1> ----- -<1> Replace the value for `size` with your desired capacity. The example file shows "5Gi". diff --git a/modules/metering-debugging.adoc b/modules/metering-debugging.adoc deleted file mode 100644 index 174aedaaf185..000000000000 --- a/modules/metering-debugging.adoc +++ /dev/null @@ -1,226 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-troubleshooting-debugging.adoc - -[id="metering-debugging_{context}"] -= Debugging metering - -Debugging metering is much easier when you interact directly with the various components. The sections below detail how you can connect and query Presto and Hive as well as view the dashboards of the Presto and HDFS components. - -[NOTE] -==== -All of the commands in this section assume you have installed metering through OperatorHub in the `openshift-metering` namespace. -==== - -[id="metering-get-reporting-operator-logs_{context}"] -== Get reporting operator logs -Use the command below to follow the logs of the `reporting-operator`: - -[source,terminal] ----- -$ oc -n openshift-metering logs -f "$(oc -n openshift-metering get pods -l app=reporting-operator -o name | cut -c 5-)" -c reporting-operator ----- - -[id="metering-query-presto-using-presto-cli_{context}"] -== Query Presto using presto-cli -The following command opens an interactive presto-cli session where you can query Presto. This session runs in the same container as Presto and launches an additional Java instance, which can create memory limits for the pod. If this occurs, you should increase the memory request and limits of the Presto pod. - -By default, Presto is configured to communicate using TLS. You must use the following command to run Presto queries: - -[source,terminal] ----- -$ oc -n openshift-metering exec -it "$(oc -n openshift-metering get pods -l app=presto,presto=coordinator -o name | cut -d/ -f2)" -- /usr/local/bin/presto-cli --server https://presto:8080 --catalog hive --schema default --user root --keystore-path /opt/presto/tls/keystore.pem ----- - -Once you run this command, a prompt appears where you can run queries. Use the `show tables from metering;` query to view the list of tables: - -[source,terminal] ----- -$ presto:default> show tables from metering; ----- - -.Example output -[source,terminal] ----- - Table - - datasource_your_namespace_cluster_cpu_capacity_raw - datasource_your_namespace_cluster_cpu_usage_raw - datasource_your_namespace_cluster_memory_capacity_raw - datasource_your_namespace_cluster_memory_usage_raw - datasource_your_namespace_node_allocatable_cpu_cores - datasource_your_namespace_node_allocatable_memory_bytes - datasource_your_namespace_node_capacity_cpu_cores - datasource_your_namespace_node_capacity_memory_bytes - datasource_your_namespace_node_cpu_allocatable_raw - datasource_your_namespace_node_cpu_capacity_raw - datasource_your_namespace_node_memory_allocatable_raw - datasource_your_namespace_node_memory_capacity_raw - datasource_your_namespace_persistentvolumeclaim_capacity_bytes - datasource_your_namespace_persistentvolumeclaim_capacity_raw - datasource_your_namespace_persistentvolumeclaim_phase - datasource_your_namespace_persistentvolumeclaim_phase_raw - datasource_your_namespace_persistentvolumeclaim_request_bytes - datasource_your_namespace_persistentvolumeclaim_request_raw - datasource_your_namespace_persistentvolumeclaim_usage_bytes - datasource_your_namespace_persistentvolumeclaim_usage_raw - datasource_your_namespace_persistentvolumeclaim_usage_with_phase_raw - datasource_your_namespace_pod_cpu_request_raw - datasource_your_namespace_pod_cpu_usage_raw - datasource_your_namespace_pod_limit_cpu_cores - datasource_your_namespace_pod_limit_memory_bytes - datasource_your_namespace_pod_memory_request_raw - datasource_your_namespace_pod_memory_usage_raw - datasource_your_namespace_pod_persistentvolumeclaim_request_info - datasource_your_namespace_pod_request_cpu_cores - datasource_your_namespace_pod_request_memory_bytes - datasource_your_namespace_pod_usage_cpu_cores - datasource_your_namespace_pod_usage_memory_bytes -(32 rows) - -Query 20190503_175727_00107_3venm, FINISHED, 1 node -Splits: 19 total, 19 done (100.00%) -0:02 [32 rows, 2.23KB] [19 rows/s, 1.37KB/s] - -presto:default> ----- - -[id="metering-query-hive-using-beeline_{context}"] -== Query Hive using beeline -The following opens an interactive beeline session where you can query Hive. This session runs in the same container as Hive and launches an additional Java instance, which can create memory limits for the pod. If this occurs, you should increase the memory request and limits of the Hive pod. - -[source,terminal] ----- -$ oc -n openshift-metering exec -it $(oc -n openshift-metering get pods -l app=hive,hive=server -o name | cut -d/ -f2) -c hiveserver2 -- beeline -u 'jdbc:hive2://127.0.0.1:10000/default;auth=noSasl' ----- - -Once you run this command, a prompt appears where you can run queries. Use the `show tables;` query to view the list of tables: - -[source,terminal] ----- -$ 0: jdbc:hive2://127.0.0.1:10000/default> show tables from metering; ----- - -.Example output -[source,terminal] ----- -+----------------------------------------------------+ -| tab_name | -+----------------------------------------------------+ -| datasource_your_namespace_cluster_cpu_capacity_raw | -| datasource_your_namespace_cluster_cpu_usage_raw | -| datasource_your_namespace_cluster_memory_capacity_raw | -| datasource_your_namespace_cluster_memory_usage_raw | -| datasource_your_namespace_node_allocatable_cpu_cores | -| datasource_your_namespace_node_allocatable_memory_bytes | -| datasource_your_namespace_node_capacity_cpu_cores | -| datasource_your_namespace_node_capacity_memory_bytes | -| datasource_your_namespace_node_cpu_allocatable_raw | -| datasource_your_namespace_node_cpu_capacity_raw | -| datasource_your_namespace_node_memory_allocatable_raw | -| datasource_your_namespace_node_memory_capacity_raw | -| datasource_your_namespace_persistentvolumeclaim_capacity_bytes | -| datasource_your_namespace_persistentvolumeclaim_capacity_raw | -| datasource_your_namespace_persistentvolumeclaim_phase | -| datasource_your_namespace_persistentvolumeclaim_phase_raw | -| datasource_your_namespace_persistentvolumeclaim_request_bytes | -| datasource_your_namespace_persistentvolumeclaim_request_raw | -| datasource_your_namespace_persistentvolumeclaim_usage_bytes | -| datasource_your_namespace_persistentvolumeclaim_usage_raw | -| datasource_your_namespace_persistentvolumeclaim_usage_with_phase_raw | -| datasource_your_namespace_pod_cpu_request_raw | -| datasource_your_namespace_pod_cpu_usage_raw | -| datasource_your_namespace_pod_limit_cpu_cores | -| datasource_your_namespace_pod_limit_memory_bytes | -| datasource_your_namespace_pod_memory_request_raw | -| datasource_your_namespace_pod_memory_usage_raw | -| datasource_your_namespace_pod_persistentvolumeclaim_request_info | -| datasource_your_namespace_pod_request_cpu_cores | -| datasource_your_namespace_pod_request_memory_bytes | -| datasource_your_namespace_pod_usage_cpu_cores | -| datasource_your_namespace_pod_usage_memory_bytes | -+----------------------------------------------------+ -32 rows selected (13.101 seconds) -0: jdbc:hive2://127.0.0.1:10000/default> ----- - -[id="metering-port-forward-hive-web-ui_{context}"] -== Port-forward to the Hive web UI -Run the following command to port-forward to the Hive web UI: - -[source,terminal] ----- -$ oc -n openshift-metering port-forward hive-server-0 10002 ----- - -You can now open http://127.0.0.1:10002 in your browser window to view the Hive web interface. - -[id="metering-port-forward-hdfs_{context}"] -== Port-forward to HDFS -Run the following command to port-forward to the HDFS namenode: - -[source,terminal] ----- -$ oc -n openshift-metering port-forward hdfs-namenode-0 9870 ----- - -You can now open http://127.0.0.1:9870 in your browser window to view the HDFS web interface. - -Run the following command to port-forward to the first HDFS datanode: - -[source,terminal] ----- -$ oc -n openshift-metering port-forward hdfs-datanode-0 9864 <1> ----- -<1> To check other datanodes, replace `hdfs-datanode-0` with the pod you want to view information on. - -[id="metering-ansible-operator_{context}"] -== Metering Ansible Operator -Metering uses the Ansible Operator to watch and reconcile resources in a cluster environment. When debugging a failed metering installation, it can be helpful to view the Ansible logs or status of your MeteringConfig custom resource. - -[id="metering-accessing-ansible-logs_{context}"] -=== Accessing Ansible logs -In the default installation, the Metering Operator is deployed as a pod. In this case, you can check the logs of the Ansible container within this pod: - -[source,terminal] ----- -$ oc -n openshift-metering logs $(oc -n openshift-metering get pods -l app=metering-operator -o name | cut -d/ -f2) -c ansible ----- - -Alternatively, you can view the logs of the Operator container (replace `-c ansible` with `-c operator`) for condensed output. - -[id="metering-checking-meteringconfig-status_{context}"] -=== Checking the MeteringConfig Status -It can be helpful to view the `.status` field of your MeteringConfig custom resource to debug any recent failures. The following command shows status messages with type `Invalid`: - -[source,terminal] ----- -$ oc -n openshift-metering get meteringconfig operator-metering -o=jsonpath='{.status.conditions[?(@.type=="Invalid")].message}' ----- -// $ oc -n openshift-metering get meteringconfig operator-metering -o json | jq '.status' - -[id="metering-checking-meteringconfig-events_{context}"] -=== Checking MeteringConfig Events -Check events that the Metering Operator is generating. This can be helpful during installation or upgrade to debug any resource failures. Sort events by the last timestamp: - -[source,terminal] ----- -$ oc -n openshift-metering get events --field-selector involvedObject.kind=MeteringConfig --sort-by='.lastTimestamp' ----- - -.Example output with latest changes in the MeteringConfig resources -[source,terminal] ----- -LAST SEEN TYPE REASON OBJECT MESSAGE -4m40s Normal Validating meteringconfig/operator-metering Validating the user-provided configuration -4m30s Normal Started meteringconfig/operator-metering Configuring storage for the metering-ansible-operator -4m26s Normal Started meteringconfig/operator-metering Configuring TLS for the metering-ansible-operator -3m58s Normal Started meteringconfig/operator-metering Configuring reporting for the metering-ansible-operator -3m53s Normal Reconciling meteringconfig/operator-metering Reconciling metering resources -3m47s Normal Reconciling meteringconfig/operator-metering Reconciling monitoring resources -3m41s Normal Reconciling meteringconfig/operator-metering Reconciling HDFS resources -3m23s Normal Reconciling meteringconfig/operator-metering Reconciling Hive resources -2m59s Normal Reconciling meteringconfig/operator-metering Reconciling Presto resources -2m35s Normal Reconciling meteringconfig/operator-metering Reconciling reporting-operator resources -2m14s Normal Reconciling meteringconfig/operator-metering Reconciling reporting resources ----- diff --git a/modules/metering-exposing-the-reporting-api.adoc b/modules/metering-exposing-the-reporting-api.adoc deleted file mode 100644 index 516f61d5bc2c..000000000000 --- a/modules/metering-exposing-the-reporting-api.adoc +++ /dev/null @@ -1,156 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-reporting-operator.adoc - -[id="metering-exposing-the-reporting-api_{context}"] -= Exposing the reporting API - -On {product-title} the default metering installation automatically exposes a Route, making the reporting API available. This provides the following features: - -* Automatic DNS -* Automatic TLS based on the cluster CA - -Also, the default installation makes it possible to use the OpenShift service for serving certificates to protect the reporting API with TLS. The OpenShift OAuth proxy is deployed as a side-car container for `reporting-operator`, which protects the reporting API with authentication. - -[id="metering-openshift-authentication_{context}"] -== Using OpenShift Authentication -By default, the reporting API is secured with TLS and authentication. This is done by configuring the `reporting-operator` to deploy a pod containing both the `reporting-operator's` container, and a sidecar container running OpenShift auth-proxy. - -To access the reporting API, the metering operator exposes a route. Once that route has been installed, you can run the following command to get the route's hostname. - -[source,terminal] ----- -$ METERING_ROUTE_HOSTNAME=$(oc -n openshift-metering get routes metering -o json | jq -r '.status.ingress[].host') ----- - -Next, set up authentication using either a service account token or basic authentication with a username/password. - -[id="metering-authenticate-using-service-account_{context}"] -=== Authenticate using a service account token -With this method, you use the token in the reporting Operator's service account, and pass that bearer token to the Authorization header in the following command: - -[source,terminal] ----- -$ TOKEN=$(oc -n openshift-metering serviceaccounts get-token reporting-operator) -curl -H "Authorization: Bearer $TOKEN" -k "https://$metering_route_hostname/api/v1/reports/get?name=[Report%20Name]&namespace=openshift-metering&format=[Format]" ----- - -Be sure to replace the `name=[Report Name]` and `format=[Format]` parameters in the URL above. The `format` parameter can be json, csv, or tabular. - -[id="metering-authenticate-using-username-password_{context}"] -=== Authenticate using a username and password -We are able to do basic authentication using a username and password combination, which is specified in the contents of a htpasswd file. By default, we create a secret containing an empty htpasswd data. You can, however, configure the `reporting-operator.spec.authProxy.htpasswd.data` and `reporting-operator.spec.authProxy.htpasswd.createSecret` keys to use this method. - -Once you have specified the above in your MeteringConfig, you can run the following command: - -[source,terminal] ----- -$ curl -u testuser:password123 -k "https://$metering_route_hostname/api/v1/reports/get?name=[Report%20Name]&namespace=openshift-metering&format=[Format]" ----- - -Be sure to replace `testuser:password123` with a valid username and password combination. - -[id="metering-manually-configure-authentication_{context}"] -== Manually Configuring Authentication -To manually configure, or disable OAuth in the `reporting-operator`, you must set `spec.tls.enabled: false` in your MeteringConfig. - -[WARNING] -==== -This also disables all TLS/authentication between the `reporting-operator`, presto, and hive. You would need to manually configure these resources yourself. -==== - -Authentication can be enabled by configuring the following options. Enabling authentication configures the `reporting-operator` pod to run the OpenShift auth-proxy as a sidecar container in the pod. This adjusts the ports so that the `reporting-operator` API isn't exposed directly, but instead is proxied to via the auth-proxy sidecar container. - -* reporting-operator.spec.authProxy.enabled -* reporting-operator.spec.authProxy.cookie.createSecret -* reporting-operator.spec.authProxy.cookie.seed - -You need to set `reporting-operator.spec.authProxy.enabled` and `reporting-operator.spec.authProxy.cookie.createSecret` to `true` and `reporting-operator.spec.authProxy.cookie.seed` to a 32-character random string. - -You can generate a 32-character random string using the following command. - -[source,terminal] ----- -$ openssl rand -base64 32 | head -c32; echo. ----- - -[id="metering-token-authentication_{context}"] -=== Token authentication -When the following options are set to `true`, authentication using a bearer token is enabled for the reporting REST API. Bearer tokens can come from serviceAccounts or users. - -* reporting-operator.spec.authProxy.subjectAccessReview.enabled -* reporting-operator.spec.authProxy.delegateURLs.enabled - -When authentication is enabled, the Bearer token used to query the reporting API of the user or `serviceAccount` must be granted access using one of the following roles: - -* report-exporter -* reporting-admin -* reporting-viewer -* metering-admin -* metering-viewer - -The `metering-operator` is capable of creating RoleBindings for you, granting these permissions by specifying a list of subjects in the `spec.permissions` section. For an example, see the following `advanced-auth.yaml` example configuration. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - permissions: - # anyone in the "metering-admins" group can create, update, delete, etc any - # metering.openshift.io resources in the namespace. - # This also grants permissions to get query report results from the reporting REST API. - meteringAdmins: - - kind: Group - name: metering-admins - # Same as above except read only access and for the metering-viewers group. - meteringViewers: - - kind: Group - name: metering-viewers - # the default serviceaccount in the namespace "my-custom-ns" can: - # create, update, delete, etc reports. - # This also gives permissions query the results from the reporting REST API. - reportingAdmins: - - kind: ServiceAccount - name: default - namespace: my-custom-ns - # anyone in the group reporting-readers can get, list, watch reports, and - # query report results from the reporting REST API. - reportingViewers: - - kind: Group - name: reporting-readers - # anyone in the group cluster-admins can query report results - # from the reporting REST API. So can the user bob-from-accounting. - reportExporters: - - kind: Group - name: cluster-admins - - kind: User - name: bob-from-accounting - - reporting-operator: - spec: - authProxy: - # htpasswd.data can contain htpasswd file contents for allowing auth - # using a static list of usernames and their password hashes. - # - # username is 'testuser' password is 'password123' - # generated htpasswdData using: `htpasswd -nb -s testuser password123` - # htpasswd: - # data: | - # testuser:{SHA}y/2sYAj5yrQIN4TL0YdPdmGNKpc= - # - # change REPLACEME to the output of your htpasswd command - htpasswd: - data: | - REPLACEME ----- - -Alternatively, you can use any role which has rules granting `get` permissions to `reports/export`. This means `get` access to the `export` sub-resource of the Report resources in the namespace of the `reporting-operator`. For example: `admin` and `cluster-admin`. - -By default, the `reporting-operator` and `metering-operator` `serviceAccounts` both have these permissions, and their tokens can be used for authentication. - -[id="metering-basic-authentication_{context}"] -=== Basic authentication (username/password) -For basic authentication you can supply a username and password in `reporting-operator.spec.authProxy.htpasswd.data`. The username and password must be the same format as those found in an htpasswd file. When set, you can use HTTP basic authentication to provide your username and password that has a corresponding entry in the `htpasswdData` contents. diff --git a/modules/metering-install-operator.adoc b/modules/metering-install-operator.adoc deleted file mode 100644 index 7280bbbfef53..000000000000 --- a/modules/metering-install-operator.adoc +++ /dev/null @@ -1,131 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-installing-metering.adoc - -[id="metering-install-operator_{context}"] -= Installing the Metering Operator - -You can install metering by deploying the Metering Operator. The Metering Operator creates and manages the components of the metering stack. - -[NOTE] -==== -You cannot create a Project starting with `openshift-` using the web console or by using the `oc new-project` command in the CLI. -==== - -[NOTE] -==== -If the Metering Operator is installed using a namespace other than `openshift-metering`, the Metering reports are only viewable using the CLI. It is strongly suggested throughout the installation steps to use the `openshift-metering` namespace. -==== - -[id="metering-install-web-console_{context}"] -== Installing metering using the web console -You can use the {product-title} web console to install the Metering Operator. - -.Procedure - -. Create a namespace object YAML file for the Metering Operator with the `oc create -f <file-name>.yaml` command. You must use the CLI to create the namespace. For example, `metering-namespace.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-metering <1> - annotations: - openshift.io/node-selector: "" <2> - labels: - openshift.io/cluster-monitoring: "true" ----- -<1> It is strongly recommended to deploy metering in the `openshift-metering` namespace. -<2> Include this annotation before configuring specific node selectors for the operand pods. - -. In the {product-title} web console, click *Operators* -> *OperatorHub*. Filter for `metering` to find the Metering Operator. - -. Click the Metering card, review the package description, and then click *Install*. -. Select an *Update Channel*, *Installation Mode*, and *Approval Strategy*. -. Click *Install*. - -. Verify that the Metering Operator is installed by switching to the *Operators* -> *Installed Operators* page. The Metering Operator has a *Status* of *Succeeded* when the installation is complete. -+ -[NOTE] -==== -It might take several minutes for the Metering Operator to appear. -==== - -. Click *Metering* on the *Installed Operators* page for Operator *Details*. From the *Details* page you can create different resources related to metering. - -To complete the metering installation, create a MeteringConfig resource to configure metering and install the components of the metering stack. - -[id="metering-install-cli_{context}"] -== Installing metering using the CLI - -You can use the {product-title} CLI to install the Metering Operator. - -.Procedure - -. Create a namespace object YAML file for the Metering Operator. You must use the CLI to create the namespace. For example, `metering-namespace.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-metering <1> - annotations: - openshift.io/node-selector: "" <2> - labels: - openshift.io/cluster-monitoring: "true" ----- -<1> It is strongly recommended to deploy metering in the `openshift-metering` namespace. -<2> Include this annotation before configuring specific node selectors for the operand pods. - -. Create the namespace object: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f openshift-metering.yaml ----- -. Create the OperatorGroup object YAML file. For example, `metering-og`: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: openshift-metering <1> - namespace: openshift-metering <2> -spec: - targetNamespaces: - - openshift-metering ----- -<1> The name is arbitrary. -<2> Specify the `openshift-metering` namespace. - -. Create a Subscription object YAML file to subscribe a namespace to the Metering Operator. This object targets the most recently released version in the `redhat-operators` CatalogSource. For example, `metering-sub.yaml`: -+ -[source,yaml, subs="attributes+"] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: metering-ocp <1> - namespace: openshift-metering <2> -spec: - channel: "{product-version}" <3> - source: "redhat-operators" <4> - sourceNamespace: "openshift-marketplace" - name: "metering-ocp" - installPlanApproval: "Automatic" <5> ----- -<1> The name is arbitrary. -<2> You must specify the `openshift-metering` namespace. -<3> Specify {product-version} as the channel. -<4> Specify the `redhat-operators` CatalogSource, which contains the `metering-ocp` package manifests. If your {product-title} is installed on a restricted network, also known as a disconnected cluster, specify the name of the CatalogSource object you created when you configured the Operator LifeCycle Manager (OLM). -<5> Specify "Automatic" install plan approval. diff --git a/modules/metering-install-prerequisites.adoc b/modules/metering-install-prerequisites.adoc deleted file mode 100644 index e4c41cfcb81b..000000000000 --- a/modules/metering-install-prerequisites.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-installing-metering.adoc - -[id="metering-install-prerequisites_{context}"] -= Prerequisites - -Metering requires the following components: - -* A StorageClass for dynamic volume provisioning. Metering supports a number of different storage solutions. -* 4GB memory and 4 CPU cores available cluster capacity and at least one node with 2 CPU cores and 2GB memory capacity available. -* The minimum resources needed for the largest single Pod installed by metering are 2GB of memory and 2 CPU cores. -** Memory and CPU consumption may often be lower, but will spike when running reports, or collecting data for larger clusters. - diff --git a/modules/metering-install-verify.adoc b/modules/metering-install-verify.adoc deleted file mode 100644 index 8b0c49a69821..000000000000 --- a/modules/metering-install-verify.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-installing-metering.adc - -[id="metering-install-verify_{context}"] -= Verifying the metering installation - -You can verify the metering installation by performing any of the following checks: - -* Check the Metering Operator ClusterServiceVersion (CSV) for the metering version. This can be done through either the web console or CLI. -+ --- -.Procedure (UI) - . Navigate to *Operators* -> *Installed Operators* in the `openshift-metering` namespace. - . Click *Metering Operator*. - . Click *Subscription* for *Subscription Details*. - . Check the *Installed Version*. - -.Procedure (CLI) -* Check the Metering Operator CSV in the `openshift-metering` namespace: -+ -[source,terminal] ----- -$ oc --namespace openshift-metering get csv ----- -+ -.Example output -[source,terminal,subs="attributes+"] ----- -NAME DISPLAY VERSION REPLACES PHASE -elasticsearch-operator.{product-version}.0-202006231303.p0 OpenShift Elasticsearch Operator {product-version}.0-202006231303.p0 Succeeded -metering-operator.v{product-version}.0 Metering {product-version}.0 Succeeded ----- --- - -* Check that all required pods in the `openshift-metering` namespace are created. This can be done through either the web console or CLI. -+ --- -[NOTE] -==== -Many pods rely on other components to function before they themselves can be considered ready. Some pods may restart if other pods take too long to start. This is to be expected during the Metering Operator installation. -==== - -.Procedure (UI) -* Navigate to *Workloads* -> *Pods* in the metering namespace and verify that pods are being created. This can take several minutes after installing the metering stack. - -.Procedure (CLI) -* Check that all required pods in the `openshift-metering` namespace are created: -+ -[source,terminal] ----- -$ oc -n openshift-metering get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -hive-metastore-0 2/2 Running 0 3m28s -hive-server-0 3/3 Running 0 3m28s -metering-operator-68dd64cfb6-2k7d9 2/2 Running 0 5m17s -presto-coordinator-0 2/2 Running 0 3m9s -reporting-operator-5588964bf8-x2tkn 2/2 Running 0 2m40s ----- --- - -* Verify that the `ReportDataSources` are beginning to import data, indicated by a valid timestamp in the `EARLIEST METRIC` column. This might take several minutes. Filter out the "-raw" `ReportDataSources`, which do not import data: -+ -[source,terminal] ----- -$ oc get reportdatasources -n openshift-metering | grep -v raw ----- -+ -.Example output -[source,terminal] ----- -NAME EARLIEST METRIC NEWEST METRIC IMPORT START IMPORT END LAST IMPORT TIME AGE -node-allocatable-cpu-cores 2019-08-05T16:52:00Z 2019-08-05T18:52:00Z 2019-08-05T16:52:00Z 2019-08-05T18:52:00Z 2019-08-05T18:54:45Z 9m50s -node-allocatable-memory-bytes 2019-08-05T16:51:00Z 2019-08-05T18:51:00Z 2019-08-05T16:51:00Z 2019-08-05T18:51:00Z 2019-08-05T18:54:45Z 9m50s -node-capacity-cpu-cores 2019-08-05T16:51:00Z 2019-08-05T18:29:00Z 2019-08-05T16:51:00Z 2019-08-05T18:29:00Z 2019-08-05T18:54:39Z 9m50s -node-capacity-memory-bytes 2019-08-05T16:52:00Z 2019-08-05T18:41:00Z 2019-08-05T16:52:00Z 2019-08-05T18:41:00Z 2019-08-05T18:54:44Z 9m50s -persistentvolumeclaim-capacity-bytes 2019-08-05T16:51:00Z 2019-08-05T18:29:00Z 2019-08-05T16:51:00Z 2019-08-05T18:29:00Z 2019-08-05T18:54:43Z 9m50s -persistentvolumeclaim-phase 2019-08-05T16:51:00Z 2019-08-05T18:29:00Z 2019-08-05T16:51:00Z 2019-08-05T18:29:00Z 2019-08-05T18:54:28Z 9m50s -persistentvolumeclaim-request-bytes 2019-08-05T16:52:00Z 2019-08-05T18:30:00Z 2019-08-05T16:52:00Z 2019-08-05T18:30:00Z 2019-08-05T18:54:34Z 9m50s -persistentvolumeclaim-usage-bytes 2019-08-05T16:52:00Z 2019-08-05T18:30:00Z 2019-08-05T16:52:00Z 2019-08-05T18:30:00Z 2019-08-05T18:54:36Z 9m49s -pod-limit-cpu-cores 2019-08-05T16:52:00Z 2019-08-05T18:30:00Z 2019-08-05T16:52:00Z 2019-08-05T18:30:00Z 2019-08-05T18:54:26Z 9m49s -pod-limit-memory-bytes 2019-08-05T16:51:00Z 2019-08-05T18:40:00Z 2019-08-05T16:51:00Z 2019-08-05T18:40:00Z 2019-08-05T18:54:30Z 9m49s -pod-persistentvolumeclaim-request-info 2019-08-05T16:51:00Z 2019-08-05T18:40:00Z 2019-08-05T16:51:00Z 2019-08-05T18:40:00Z 2019-08-05T18:54:37Z 9m49s -pod-request-cpu-cores 2019-08-05T16:51:00Z 2019-08-05T18:18:00Z 2019-08-05T16:51:00Z 2019-08-05T18:18:00Z 2019-08-05T18:54:24Z 9m49s -pod-request-memory-bytes 2019-08-05T16:52:00Z 2019-08-05T18:08:00Z 2019-08-05T16:52:00Z 2019-08-05T18:08:00Z 2019-08-05T18:54:32Z 9m49s -pod-usage-cpu-cores 2019-08-05T16:52:00Z 2019-08-05T17:57:00Z 2019-08-05T16:52:00Z 2019-08-05T17:57:00Z 2019-08-05T18:54:10Z 9m49s -pod-usage-memory-bytes 2019-08-05T16:52:00Z 2019-08-05T18:08:00Z 2019-08-05T16:52:00Z 2019-08-05T18:08:00Z 2019-08-05T18:54:20Z 9m49s ----- - -After all pods are ready and you have verified that data is being imported, you can begin using metering to collect data and report on your cluster. diff --git a/modules/metering-overview.adoc b/modules/metering-overview.adoc deleted file mode 100644 index e910555c5d96..000000000000 --- a/modules/metering-overview.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-installing-metering.adoc -// * metering/metering-using-metering.adoc - -[id="metering-overview_{context}"] -= Metering overview - -Metering is a general purpose data analysis tool that enables you to write reports to process data from different data sources. -As a cluster administrator, you can use metering to analyze what is happening in your cluster. -You can either write your own, or use predefined SQL queries to define how you want to process data from the different data sources you have available. - -Metering focuses primarily on in-cluster metric data using Prometheus as a default data source, enabling users of metering to do reporting on pods, namespaces, and most other Kubernetes resources. - -You can install metering on {product-title} 4.x clusters and above. - -[id="metering-resources_{context}"] -== Metering resources - -Metering has many resources which can be used to manage the deployment and installation of metering, as well as the reporting functionality metering provides. - -Metering is managed using the following CustomResourceDefinitions (CRDs): - -[cols="1,7"] -|=== - -|*MeteringConfig* |Configures the metering stack for deployment. Contains customizations and configuration options to control each component that makes up the metering stack. - -|*Reports* |Controls what query to use, when, and how often the query should be run, and where to store the results. - -|*ReportQueries* |Contains the SQL queries used to perform analysis on the data contained within ReportDataSources. - -|*ReportDataSources* |Controls the data available to ReportQueries and Reports. Allows configuring access to different databases for use within metering. - -|=== diff --git a/modules/metering-prometheus-connection.adoc b/modules/metering-prometheus-connection.adoc deleted file mode 100644 index fbb095e7fa4c..000000000000 --- a/modules/metering-prometheus-connection.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-reporting-operator.adoc - -[id="metering-prometheus-connection_{context}"] -= Prometheus connection - -When you install metering on {product-title}, Prometheus is available at https://prometheus-k8s.openshift-monitoring.svc:9091/. - -To secure the connection to Prometheus, the default metering installation uses the {product-title} certificate authority. If your Prometheus instance uses a different CA, the CA can be injected through a ConfigMap. See the following example. - -[source,yaml] ----- -spec: - reporting-operator: - spec: - config: - prometheus: - certificateAuthority: - useServiceAccountCA: false - configMap: - enabled: true - create: true - name: reporting-operator-certificate-authority-config - filename: "internal-ca.crt" - value: | - -----BEGIN CERTIFICATE----- - (snip) - -----END CERTIFICATE----- ----- - -Alternatively, to use the system certificate authorities for publicly valid certificates, set both `useServiceAccountCA` and `configMap.enabled` to `false`. - -The `reporting-operator` can also be configured to use a specified bearer token to auth with Prometheus. See the following example. - -[source,yaml] ----- -spec: - reporting-operator: - spec: - config: - prometheus: - metricsImporter: - auth: - useServiceAccountToken: false - tokenSecret: - enabled: true - create: true - value: "abc-123" ----- diff --git a/modules/metering-reports.adoc b/modules/metering-reports.adoc deleted file mode 100644 index a352c9348cc1..000000000000 --- a/modules/metering-reports.adoc +++ /dev/null @@ -1,384 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-about-reports.adoc -[id="metering-reports_{context}"] -= Reports - -The Report custom resource is used to manage the execution and status of reports. -Metering produces reports derived from usage data sources, which can be used in further analysis and filtering. - -A single Report resource represents a job that manages a database table and updates it with new information according to a schedule. The Report exposes the data in that table via the reporting-operator HTTP API. -Reports with a `spec.schedule` field set are always running and track what time periods it has collected data for. This ensures that if metering is shutdown or unavailable for an extended period of time, it backfills the data starting where it left off. -If the schedule is unset, then the Report runs once for the time specified by the `reportingStart` and `reportingEnd`. -By default, reports wait for ReportDataSources to have fully imported any data covered in the reporting period. -If the Report has a schedule, it waits to run until the data in the period currently being processed has finished importing. - -[id="metering-example-report-with-schedule_{context}"] -== Example Report with a Schedule - -The following example Report contains information on every Pod's CPU requests, and runs every hour, adding the last hours worth of data each time it runs. -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: pod-cpu-request-hourly -spec: - query: "pod-cpu-request" - reportingStart: "2019-07-01T00:00:00Z" - schedule: - period: "hourly" - hourly: - minute: 0 - second: 0 ----- - -[id="metering-example-report-without-schedule_{context}"] -== Example Report without a Schedule (Run-Once) - -The following example Report contains information on every Pod's CPU requests for all of July. -After completion, it does not run again. -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: pod-cpu-request-hourly -spec: - query: "pod-cpu-request" - reportingStart: "2019-07-01T00:00:00Z" - reportingEnd: "2019-07-31T00:00:00Z" ----- - -[id="metering-query_{context}"] -== query - -Names the ReportQuery used to generate the report. -The report query controls the schema of the report as well as how the results are processed. - -*`query` is a required field.* - -Use the following command to list available ReportQuery objects: -[source,terminal] ----- -$ oc -n openshift-metering get reportqueries ----- -.Example output -[source,terminal] ----- -NAME AGE -cluster-cpu-capacity 23m -cluster-cpu-capacity-raw 23m -cluster-cpu-usage 23m -cluster-cpu-usage-raw 23m -cluster-cpu-utilization 23m -cluster-memory-capacity 23m -cluster-memory-capacity-raw 23m -cluster-memory-usage 23m -cluster-memory-usage-raw 23m -cluster-memory-utilization 23m -cluster-persistentvolumeclaim-request 23m -namespace-cpu-request 23m -namespace-cpu-usage 23m -namespace-cpu-utilization 23m -namespace-memory-request 23m -namespace-memory-usage 23m -namespace-memory-utilization 23m -namespace-persistentvolumeclaim-request 23m -namespace-persistentvolumeclaim-usage 23m -node-cpu-allocatable 23m -node-cpu-allocatable-raw 23m -node-cpu-capacity 23m -node-cpu-capacity-raw 23m -node-cpu-utilization 23m -node-memory-allocatable 23m -node-memory-allocatable-raw 23m -node-memory-capacity 23m -node-memory-capacity-raw 23m -node-memory-utilization 23m -persistentvolumeclaim-capacity 23m -persistentvolumeclaim-capacity-raw 23m -persistentvolumeclaim-phase-raw 23m -persistentvolumeclaim-request 23m -persistentvolumeclaim-request-raw 23m -persistentvolumeclaim-usage 23m -persistentvolumeclaim-usage-raw 23m -persistentvolumeclaim-usage-with-phase-raw 23m -pod-cpu-request 23m -pod-cpu-request-raw 23m -pod-cpu-usage 23m -pod-cpu-usage-raw 23m -pod-memory-request 23m -pod-memory-request-raw 23m -pod-memory-usage 23m -pod-memory-usage-raw 23m ----- - -ReportQueries with the `-raw` suffix are used by other ReportQueries to build more complex queries, and should not be used directly for reports. - -`namespace-` prefixed queries aggregate Pod CPU/memory requests by namespace, providing a list of namespaces and their overall usage based on resource requests. - -`pod-` prefixed queries are similar to `namespace-` prefixed queries but aggregate information by Pod rather than namespace. These queries include the Pod's namespace and node. - -`node-` prefixed queries return information about each node's total available resources. - -`aws-` prefixed queries are specific to AWS. Queries suffixed with `-aws` return the same data as queries of the same name without the suffix, and correlate usage with the EC2 billing data. - -The `aws-ec2-billing-data` report is used by other queries, and should not be used as a standalone report. The `aws-ec2-cluster-cost` report provides a total cost based on the nodes included in the cluster, and the sum of their costs for the time period being reported on. - -Use the following command to get the ReportQuery as YAML, and check the `spec.columns` field. For example, run: - -[source,terminal] ----- -$ oc -n openshift-metering get reportqueries namespace-memory-request -o yaml ----- - -.Example output -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: ReportQuery -metadata: - name: namespace-memory-request - labels: - operator-metering: "true" -spec: - columns: - - name: period_start - type: timestamp - unit: date - - name: period_end - type: timestamp - unit: date - - name: namespace - type: varchar - unit: kubernetes_namespace - - name: pod_request_memory_byte_seconds - type: double - unit: byte_seconds ----- - -[id="metering-schedule_{context}"] -== schedule - -The `spec.schedule` configuration block defines when the report runs. -The main fields in the `schedule` section are `period`, and then depending on the value of `period`, the fields `hourly`, `daily`, `weekly`, and `monthly` allow you to fine-tune when the report runs. - -For example, if `period` is set to `weekly`, you can add a `weekly` field to the `spec.schedule` block. -The following example will run once a week on Wednesday, at 1 PM (hour 13 in the day). -[source,yaml] ----- -... - schedule: - period: "weekly" - weekly: - dayOfWeek: "wednesday" - hour: 13 -... ----- - -[id="metering-period_{context}"] -=== period - -Valid values of `schedule.period` are listed below, and the options available to set for a given period are also listed. - -* `hourly` -** `minute` -** `second` -* `daily` -** `hour` -** `minute` -** `second` -* `weekly` -** `dayOfWeek` -** `hour` -** `minute` -** `second` -* `monthly` -** `dayOfMonth` -** `hour` -** `minute` -** `second` -* `cron` -** `expression` - -Generally, the `hour`, `minute`, `second` fields control when in the day the report runs, and `dayOfWeek`/`dayOfMonth` control what day of the week, or day of month the report runs on, if it is a weekly or monthly report period. - -For each of these fields, there is a range of valid values: - -* `hour` is an integer value between 0-23. -* `minute` is an integer value between 0-59. -* `second` is an integer value between 0-59. -* `dayOfWeek` is a string value that expects the day of the week (spelled out). -* `dayOfMonth` is an integer value between 1-31. - -For cron periods, normal cron expressions are valid: - -* `expression: "*/5 * * * *"` - -[id="metering-reportingStart_{context}"] -== reportingStart - -To support running a Report against existing data, you can set the `spec.reportingStart` field to a link:https://tools.ietf.org/html/rfc3339#section-5.8[RFC3339 timestamp] to tell the Report to run according to its `schedule` starting from `reportingStart` rather than the current time. -One important thing to understand is that this will result in the reporting-operator running many queries in succession for each interval in the schedule that is between the `reportingStart` time and the current time. -This could be thousands of queries if the period is less than daily and the `reportingStart` is more than a few months back. -If `reportingStart` is left unset, the Report will run at the next full reportingPeriod after the time the report is created. - -As an example of how to use this field, if you had data already collected dating back to January 1st, 2019, which you want to include in your Report, you can create a report with the following values: - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: pod-cpu-request-hourly -spec: - query: "pod-cpu-request" - schedule: - period: "hourly" - reportingStart: "2019-01-01T00:00:00Z" ----- - -[id="metering-reportingEnd_{context}"] -== reportingEnd - -To configure a Report to only run until a specified time, you can set the `spec.reportingEnd` field to an link:https://tools.ietf.org/html/rfc3339#section-5.8[RFC3339 timestamp]. -The value of this field will cause the Report to stop running on its schedule after it has finished generating reporting data for the period covered from its start time until `reportingEnd`. -Because a schedule will most likely not align with reportingEnd, the last period in the schedule will be shortened to end at the specified reportingEnd time. -If left unset, then the Report will run forever, or until a `reportingEnd` is set on the Report. - -For example, if you want to create a report that runs once a week for the month of July: -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: pod-cpu-request-hourly -spec: - query: "pod-cpu-request" - schedule: - period: "weekly" - reportingStart: "2019-07-01T00:00:00Z" - reportingEnd: "2019-07-31T00:00:00Z" ----- - -[id="metering-expiration_{context}"] -== expiration - -Add the `expiration` field to set a retention period on a scheduled metering Report. You can avoid manually removing the Report by setting the `expiration` duration value. The retention period is equal to the Report `creationDate` plus the `expiration` duration. The Report is removed from the cluster at the end of the retention period if no other Reports or ReportQueries depend on the expiring Report. Deleting the Report from the cluster can take several minutes. - -[NOTE] -==== -Setting the `expiration` field is not recommended for roll-up or aggregated reports. If a Report is depended upon by other Reports or ReportQueries, then the Report is not removed at the end of the retention period. You can view the `report-operator` logs at debug level for the timing output around a Report retention decision. -==== - -For example, the following scheduled Report is deleted 30 minutes after the `creationDate` of the Report: -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: pod-cpu-request-hourly -spec: - query: "pod-cpu-request" - schedule: - period: "weekly" - reportingStart: "2020-09-01T00:00:00Z" - expiration: "30m" <1> ----- -<1> Valid time units for the `expiration` duration are `ns`, `us` (or `µs`), `ms`, `s`, `m`, and `h`. - -[NOTE] -==== -The `expiration` retention period for a Report is not precise and works on the order of several minutes, not nanoseconds. -==== - -[id="metering-runImmediately_{context}"] -== runImmediately - -When `runImmediately` is set to `true`, the report runs immediately. This behavior ensures that the report is immediately processed and queued without requiring additional scheduling parameters. - -[NOTE] -==== -When `runImmediately` is set to `true` you must set a `reportingEnd` and `reportingStart` value. -==== - -[id="metering-inputs_{context}"] -== inputs - -The `spec.inputs` field of a Report can be used to override or set values defined in a ReportQuery's `spec.inputs` field. - -It is a list of name-value pairs: - -[source,yaml] ----- -spec: - inputs: - - name: "NamespaceCPUUsageReportName" <1> - value: "namespace-cpu-usage-hourly" <2> ----- - -<1> The `name` of an input must exist in the ReportQuery's `inputs` list. -<2> The `value` of the input must be the correct type for the input's `type`. - -// TODO(chance): include modules/metering-reportquery-inputs.adoc module - -[id="metering-roll-up-reports_{context}"] -== Roll-up Reports - -Report data is stored in the database much like metrics themselves, and therefore, can be used in aggregated or roll-up reports. -A simple use case for a roll-up report is to spread the time required to produce a report over a longer period of time; instead of: requiring a monthly report to query and add all data over an entire month, the task can be split into daily reports that each run over a thirtieth of the data. - -A custom roll-up report requires a custom report query. -The ReportQuery template processor provides a function: `reportTableName` that can get the necessary table name from a Report's `metadata.name`. - -Below is a snippet taken from a built-in query: - -.pod-cpu.yaml -[source,yaml] ----- -spec: -... - inputs: - - name: ReportingStart - type: time - - name: ReportingEnd - type: time - - name: NamespaceCPUUsageReportName - type: Report - - name: PodCpuUsageRawDataSourceName - type: ReportDataSource - default: pod-cpu-usage-raw -... - - query: | -... - {|- if .Report.Inputs.NamespaceCPUUsageReportName |} - namespace, - sum(pod_usage_cpu_core_seconds) as pod_usage_cpu_core_seconds - FROM {| .Report.Inputs.NamespaceCPUUsageReportName | reportTableName |} -... ----- - -.Example `aggregated-report.yaml` roll-up report -[source,yaml] ----- -spec: - query: "namespace-cpu-usage" - inputs: - - name: "NamespaceCPUUsageReportName" - value: "namespace-cpu-usage-hourly" ----- - -// TODO(chance): replace the comment below with an include on the modules/metering-rollup-report.adoc -// For more information on setting up a roll-up report, see the [roll-up report guide](rollup-reports.md). - -[id="metering-report-status_{context}"] -=== Report Status - -The execution of a scheduled report can be tracked using its status field. Any errors occurring during the preparation of a report will be recorded here. - -The `status` field of a Report currently has two fields: - -* `conditions`: Conditions is a list of conditions, each of which have a `type`, `status`, `reason`, and `message` field. Possible values of a condition's `type` field are `Running` and `Failure`, indicating the current state of the scheduled report. The `reason` indicates why its `condition` is in its current state with the `status` being either `true`, `false` or, `unknown`. The `message` provides a human readable indicating why the condition is in the current state. For detailed information on the `reason` values see link:https://github.com/operator-framework/operator-metering/blob/master/pkg/apis/metering/v1/util/report_util.go#L10[`pkg/apis/metering/v1/util/report_util.go`]. -* `lastReportTime`: Indicates the time Metering has collected data up to. diff --git a/modules/metering-store-data-in-azure.adoc b/modules/metering-store-data-in-azure.adoc deleted file mode 100644 index e2bef4c5d754..000000000000 --- a/modules/metering-store-data-in-azure.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-persistent-storage.adoc - -[id="metering-store-data-in-azure_{context}"] -= Storing data in Microsoft Azure - -To store data in Azure blob storage you must use an existing container. Edit the `spec.storage` section in the example `azure-blob-storage.yaml` file below. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - storage: - type: "hive" - hive: - type: "azure" - azure: - container: "bucket1" <1> - secretName: "my-azure-secret" <2> - rootDirectory: "/testDir" <3> ----- -<1> Specify the container name. -<2> Specify a secret in the metering namespace. See the examples that follow for more details. -<3> You can optionally specify the directory where you would like to store your data. - -Use the example secret below as a template. - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: your-azure-secret -data: - azure-storage-account-name: "dGVzdAo=" - azure-secret-access-key: "c2VjcmV0Cg==" ----- - -You can use the following command to create the secret. - -[source,terminal] ----- -$ oc create secret -n openshift-metering generic your-azure-secret --from-literal=azure-storage-account-name=your-storage-account-name --from-literal=azure-secret-access-key=your-secret-key ----- diff --git a/modules/metering-store-data-in-gcp.adoc b/modules/metering-store-data-in-gcp.adoc deleted file mode 100644 index 5c3ab091a4f2..000000000000 --- a/modules/metering-store-data-in-gcp.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-persistent-storage.adoc - -[id="metering-store-data-in-gcp_{context}"] -= Storing data in Google Cloud Storage - -To store your data in Google Cloud Storage you must use an existing bucket. Edit the `spec.storage` section in the example `gcs-storage.yaml` file below. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - storage: - type: "hive" - hive: - type: "gcs" - gcs: - bucket: "metering-gcs/test1" <1> - secretName: "my-gcs-secret" <2> ----- -<1> Specify the name of the bucket. You can optionally specify the directory within the bucket where you would like to store your data. -<2> Specify a secret in the metering namespace. Use the example that follows for more details. - -Use the example secret below as a template: - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: your-gcs-secret -data: - gcs-service-account.json: "c2VjcmV0Cg==" ----- - -You can use the following command to create the secret. - -[source,terminal] ----- -$ oc create secret -n openshift-metering generic your-gcs-secret --from-file gcs-service-account.json=/path/to/your/service-account-key.json ----- diff --git a/modules/metering-store-data-in-s3-compatible.adoc b/modules/metering-store-data-in-s3-compatible.adoc deleted file mode 100644 index c00ba35ac9a3..000000000000 --- a/modules/metering-store-data-in-s3-compatible.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-persistent-storage.adoc - -[id="metering-store-data-in-s3-compatible_{context}"] -= Storing data in S3-compatible storage - -To use S3-compatible storage such as Noobaa, edit the `spec.storage` section in the example `s3-compatible-storage.yaml` file below. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - storage: - type: "hive" - hive: - type: "s3Compatible" - s3Compatible: - bucket: "bucketname" <1> - endpoint: "http://example:port-number" <2> - secretName: "my-aws-secret" <3> ----- -<1> Specify the name of your S3-compatible bucket. -<2> Specify the endpoint for your storage. -<3> The name of a secret in the metering namespace containing the AWS credentials in the `data.aws-access-key-id` and `data.aws-secret-access-key` fields. See the example that follows for more details. - -Use the example secret below as a template. - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: your-aws-secret -data: - aws-access-key-id: "dGVzdAo=" - aws-secret-access-key: "c2VjcmV0Cg==" ----- diff --git a/modules/metering-store-data-in-s3.adoc b/modules/metering-store-data-in-s3.adoc deleted file mode 100644 index 5649fc0a20b9..000000000000 --- a/modules/metering-store-data-in-s3.adoc +++ /dev/null @@ -1,128 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-persistent-storage.adoc - -[id="metering-store-data-in-s3_{context}"] -= Storing data in Amazon S3 - -Metering can use an existing Amazon S3 bucket or create a bucket for storage. - -[NOTE] -==== -Metering does not manage or delete any S3 bucket data. You must manually clean up S3 buckets that are used to store metering data. -==== - -To use Amazon S3 for storage, edit the `spec.storage` section in the example `s3-storage.yaml` file below. - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - storage: - type: "hive" - hive: - type: "s3" - s3: - bucket: "bucketname/path/" <1> - region: "us-west-1" <2> - secretName: "my-aws-secret" <3> - # Set to false if you want to provide an existing bucket, instead of - # having metering create the bucket on your behalf. - createBucket: true <4> ----- -<1> Specify the name of the bucket where you would like to store your data. You may optionally specify the path within the bucket. -<2> Specify the region of your bucket. -<3> The name of a secret in the metering namespace containing the AWS credentials in the `data.aws-access-key-id` and `data.aws-secret-access-key` fields. See the examples that follow for more details. -<4> Set this field to `false` if you want to provide an existing S3 bucket, or if you do not want to provide IAM credentials that have `CreateBucket` permissions. - -Use the example secret below as a template. - -[NOTE] -==== -The values of the `aws-access-key-id` and `aws-secret-access-key` must be base64 encoded. -==== - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: your-aws-secret -data: - aws-access-key-id: "dGVzdAo=" - aws-secret-access-key: "c2VjcmV0Cg==" ----- - -You can use the following command to create the secret. - -[NOTE] -==== -This command automatically base64 encodes your `aws-access-key-id` and `aws-secret-access-key` values. - -==== - -[source,terminal] ----- -$ oc create secret -n openshift-metering generic your-aws-secret --from-literal=aws-access-key-id=your-access-key --from-literal=aws-secret-access-key=your-secret-key ----- - -The `aws-access-key-id` and `aws-secret-access-key` credentials must have read and write access to the bucket. For an example of an IAM policy granting the required permissions, see the `aws/read-write.json` file below. - -[source,json] ----- -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "1", - "Effect": "Allow", - "Action": [ - "s3:AbortMultipartUpload", - "s3:DeleteObject", - "s3:GetObject", - "s3:HeadBucket", - "s3:ListBucket", - "s3:ListMultipartUploadParts", - "s3:PutObject" - ], - "Resource": [ - "arn:aws:s3:::operator-metering-data/*", - "arn:aws:s3:::operator-metering-data" - ] - } - ] -} ----- - -If you left `spec.storage.hive.s3.createBucket` set to `true`, or unset, then you should use the `aws/read-write-create.json` file below, which contains permissions for creating and deleting buckets. - -[source,json] ----- -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "1", - "Effect": "Allow", - "Action": [ - "s3:AbortMultipartUpload", - "s3:DeleteObject", - "s3:GetObject", - "s3:HeadBucket", - "s3:ListBucket", - "s3:CreateBucket", - "s3:DeleteBucket", - "s3:ListMultipartUploadParts", - "s3:PutObject" - ], - "Resource": [ - "arn:aws:s3:::operator-metering-data/*", - "arn:aws:s3:::operator-metering-data" - ] - } - ] -} ----- diff --git a/modules/metering-store-data-in-shared-volumes.adoc b/modules/metering-store-data-in-shared-volumes.adoc deleted file mode 100644 index 7656001dbeb4..000000000000 --- a/modules/metering-store-data-in-shared-volumes.adoc +++ /dev/null @@ -1,148 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-persistent-storage.adoc - -[id="metering-store-data-in-shared-volumes_{context}"] -= Storing data in shared volumes - -Metering does not configure storage by default. However, you can use any ReadWriteMany persistent volume (PV) or any storage class that provisions a ReadWriteMany PV for Metering storage. - -[NOTE] -==== -NFS is not recommended to use in production. Using an NFS server on RHEL as a storage back end can fail to meet metering requirements and to provide the performance that is needed for the Metering Operator to work appropriately. - -Other NFS implementations on the marketplace might not have these issues, such as a Parallel Network File System (pNFS). pNFS is an NFS implementation with distributed and parallel capability. Contact the individual NFS implementation vendor for more information on any testing that was possibly completed against {product-title} core components. -==== - -.Procedure - -. Modify the `shared-storage.yaml` file to use a ReadWriteMany persistent volume for storage: -+ -.Example `shared-storage.yaml` file --- -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: MeteringConfig -metadata: - name: "operator-metering" -spec: - storage: - type: "hive" - hive: - type: "sharedPVC" - sharedPVC: - claimName: "metering-nfs" <1> - # Uncomment the lines below to provision a new PVC using the specified storageClass. <2> - # createPVC: true - # storageClass: "my-nfs-storage-class" - # size: 5Gi ----- - -Select one of the configuration options below: - -<1> Set `storage.hive.sharedPVC.claimName` to the name of an existing ReadWriteMany persistent volume claim (PVC). This configuration is necessary if you do not have dynamic volume provisioning or want to have more control over how the persistent volume is created. - -<2> Set `storage.hive.sharedPVC.createPVC` to `true` and set the `storage.hive.sharedPVC.storageClass` to the name of a storage class with ReadWriteMany access mode. This configuration uses dynamic volume provisioning to create a volume automatically. --- - -. Create the following resource objects that are required to deploy an NFS server for metering. Use the `oc create -f <file-name>.yaml` command to create the object YAML files. -.. Configure a `PersistentVolume` resource object: -+ -.Example `nfs_persistentvolume.yaml` file -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: nfs - labels: - role: nfs-server -spec: - capacity: - storage: 5Gi - accessModes: - - ReadWriteMany - storageClassName: nfs-server <1> - nfs: - path: "/" - server: REPLACEME - persistentVolumeReclaimPolicy: Delete ----- -<1> Must exactly match the `[kind: StorageClass].metadata.name` field value. - -.. Configure a `Pod` resource object with the `nfs-server` role: -+ -.Example `nfs_server.yaml` file -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: nfs-server - labels: - role: nfs-server -spec: - containers: - - name: nfs-server - image: <image_name> <1> - imagePullPolicy: IfNotPresent - ports: - - name: nfs - containerPort: 2049 - securityContext: - privileged: true - volumeMounts: - - mountPath: "/mnt/data" - name: local - volumes: - - name: local - emptyDir: {} ----- -<1> Install your NFS server image. - -.. Configure a `Service` resource object with the `nfs-server` role: -+ -.Example `nfs_service.yaml` file -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: nfs-service - labels: - role: nfs-server -spec: - ports: - - name: 2049-tcp - port: 2049 - protocol: TCP - targetPort: 2049 - selector: - role: nfs-server - sessionAffinity: None - type: ClusterIP ----- - -.. Configure a `StorageClass` resource object: -+ -.Example `nfs_storageclass.yaml` file -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: nfs-server <1> -provisioner: example.com/nfs -parameters: - archiveOnDelete: "false" -reclaimPolicy: Delete -volumeBindingMode: Immediate ----- -<1> Must exactly match the `[kind: PersistentVolume].spec.storageClassName` field value. - - -[WARNING] -==== -Configuration of your NFS storage, and any relevant resource objects, will vary depending on the NFS server image that you use for Metering storage. -==== diff --git a/modules/metering-troubleshooting.adoc b/modules/metering-troubleshooting.adoc deleted file mode 100644 index 1829153a56d8..000000000000 --- a/modules/metering-troubleshooting.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-troubleshooting-debugging.adoc - -[id="metering-troubleshooting_{context}"] -= Troubleshooting metering - -A common issue with metering is pods failing to start. Pods might fail to start due to lack of resources or if they have a dependency on a resource that does not exist, such as a StorageClass or Secret. - -[id="metering-not-enough-compute-resources_{context}"] -== Not enough compute resources - -A common issue when installing or running metering is lack of compute resources. Ensure that metering is allocated the minimum resource requirements described in the installation prerequisites. - -To determine if the issue is with resources or scheduling, follow the troubleshooting instructions included in the Kubernetes document https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#troubleshooting[Managing Compute Resources for Containers]. - -[id="metering-storageclass-not-configured_{context}"] -== StorageClass not configured - -Metering requires that a default StorageClass be configured for dynamic provisioning. - -See the documentation on configuring metering for information on how to check if there are any StorageClasses configured for the cluster, how to set the default, and how to configure metering to use a StorageClass other than the default. - -[id="metering-secret-not-configured-correctly_{context}"] -== Secret not configured correctly - -A common issue with metering is providing the incorrect secret when configuring your persistent storage. Be sure to review the example configuration files and create you secret according to the guidelines for your storage provider. diff --git a/modules/metering-uninstall-crds.adoc b/modules/metering-uninstall-crds.adoc deleted file mode 100644 index 2c902d3caebd..000000000000 --- a/modules/metering-uninstall-crds.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-uninstall.adoc - -[id="metering-uninstall-crds_{context}"] -= Uninstalling metering CustomResourceDefinitions - -The metering CustomResourceDefinitions (CRDs) remain in the cluster after the Metering -Operator is uninstalled and the `openshift-metering` namespace is deleted. - -[IMPORTANT] -==== -Deleting the metering CRDs disrupts any additional metering installations in other namespaces in your cluster. -Ensure that there are no other metering installations before proceeding. -==== - -.Prerequisites - -* The MeteringConfig custom resource in the `openshift-metering` namespace is deleted. -* The `openshift-metering` namespace is deleted. - -.Procedure - -* Delete the remaining metering CRDs: -+ -[source,terminal] ----- -$ oc get crd -o name | grep "metering.openshift.io" | xargs oc delete ----- diff --git a/modules/metering-uninstall.adoc b/modules/metering-uninstall.adoc deleted file mode 100644 index d1ebf57b69e2..000000000000 --- a/modules/metering-uninstall.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-uninstall.adoc - -[id="metering-uninstall_{context}"] -= Uninstalling a metering namespace - -Uninstall your metering namespace, for example the `openshift-metering` namespace, by removing the MeteringConfig resource and deleting the `openshift-metering` namespace. - -.Prerequisites - -* The Metering Operator is removed from your cluster. - -.Procedure - -. Remove all resources created by the Metering Operator: -+ -[source,terminal] ----- -$ oc --namespace openshift-metering delete meteringconfig --all ----- - -. After the previous step is complete, verify that all pods in the `openshift-metering` namespace are deleted or are reporting a terminating state: -+ -[source,terminal] ----- -$ oc --namespace openshift-metering get pods ----- - -. Delete the `openshift-metering` namespace: -+ -[source,terminal] ----- -$ oc delete namespace openshift-metering ----- diff --git a/modules/metering-use-mysql-or-postgresql-for-hive.adoc b/modules/metering-use-mysql-or-postgresql-for-hive.adoc deleted file mode 100644 index 7135166249b1..000000000000 --- a/modules/metering-use-mysql-or-postgresql-for-hive.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/configuring_metering/metering-configure-hive-metastore.adoc - -[id="metering-use-mysql-or-postgresql-for-hive_{context}"] -= Using MySQL or PostgreSQL for the Hive metastore - -The default installation of metering configures Hive to use an embedded Java database called Derby. This is unsuited for larger environments and can be replaced with either a MySQL or PostgreSQL database. Use the following example configuration files if your deployment requires a MySQL or PostgreSQL database for Hive. - -There are three configuration options you can use to control the database that is used by Hive metastore: `url`, `driver`, and `secretName`. - -Create your MySQL or Postgres instance with a user name and password. Then create a secret by using the OpenShift CLI (`oc`) or a YAML file. The `secretName` you create for this secret must map to the `spec.hive.spec.config.db.secretName` field in the `MeteringConfig` object resource. - -.Procedure - -. Create a secret using the OpenShift CLI (`oc`) or by using a YAML file: -+ -* Create a secret by using the following command: -+ -[source,terminal] ----- -$ oc --namespace openshift-metering create secret generic <YOUR_SECRETNAME> --from-literal=username=<YOUR_DATABASE_USERNAME> --from-literal=password=<YOUR_DATABASE_PASSWORD> ----- -+ -* Create a secret by using a YAML file. For example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: <YOUR_SECRETNAME> <1> -data: - username: <BASE64_ENCODED_DATABASE_USERNAME> <2> - password: <BASE64_ENCODED_DATABASE_PASSWORD> <3> ----- -<1> The name of the secret. -<2> Base64 encoded database user name. -<3> Base64 encoded database password. - -. Create a configuration file to use a MySQL or PostgreSQL database for Hive: -+ -* To use a MySQL database for Hive, use the example configuration file below. Metering supports configuring the internal Hive metastore to use the MySQL server versions 5.6, 5.7, and 8.0. -+ --- -[source,yaml] ----- -spec: - hive: - spec: - metastore: - storage: - create: false - config: - db: - url: "jdbc:mysql://mysql.example.com:3306/hive_metastore" <1> - driver: "com.mysql.cj.jdbc.Driver" - secretName: "REPLACEME" <2> ----- -[NOTE] -==== -When configuring Metering to work with older MySQL server versions, such as 5.6 or 5.7, you might need to add the link:https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-usagenotes-known-issues-limitations.html[`enabledTLSProtocols` JDBC URL parameter] when configuring the internal Hive metastore. -==== -<1> To use the TLS v1.2 cipher suite, set `url` to `"jdbc:mysql://<hostname>:<port>/<schema>?enabledTLSProtocols=TLSv1.2"`. -<2> The name of the secret containing the base64-encrypted user name and password database credentials. --- -+ -You can pass additional JDBC parameters using the `spec.hive.config.url`. For more details, see the link:https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-configuration-properties.html[MySQL Connector/J 8.0 documentation]. -+ -* To use a PostgreSQL database for Hive, use the example configuration file below: -+ -[source,yaml] ----- -spec: - hive: - spec: - metastore: - storage: - create: false - config: - db: - url: "jdbc:postgresql://postgresql.example.com:5432/hive_metastore" - driver: "org.postgresql.Driver" - username: "REPLACEME" - password: "REPLACEME" ----- -+ -You can pass additional JDBC parameters using the `spec.hive.config.url`. For more details, see the link:https://jdbc.postgresql.org/documentation/head/connect.html#connection-parameters[PostgreSQL JDBC driver documentation]. diff --git a/modules/metering-viewing-report-results.adoc b/modules/metering-viewing-report-results.adoc deleted file mode 100644 index 80e98d7200fd..000000000000 --- a/modules/metering-viewing-report-results.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-using-metering.adoc -[id="metering-viewing-report-results_{context}"] -= Viewing Report results - -Viewing a Report's results involves querying the reporting-api `Route` and authenticating to the API using your {product-title} credentials. -Reports can be retrieved as `JSON`, `CSV`, or `Tabular` formats. - -.Prerequisites - -* Metering is installed. -* To access Report results, you must either be a cluster administrator, or you need to be granted access using the `report-exporter` role in the `openshift-metering` namespace. - -.Procedure - -. Change to the `openshift-metering` project: -+ -[source,terminal] ----- -$ oc project openshift-metering ----- - -. Query the reporting API for results: - -.. Create a variable for the metering `reporting-api` route then get the route: -+ -[source,terminal] ----- -$ meteringRoute="$(oc get routes metering -o jsonpath='{.spec.host}')" ----- -+ -[source,terminal] ----- -$ echo "$meteringRoute" ----- - -.. Get the token of your current user to be used in the request: -+ -[source,terminal] ----- -$ token="$(oc whoami -t)" ----- - -.. Set `reportName` to the name of the Report you created: -+ -[source,terminal] ----- -$ reportName=namespace-cpu-request-2019 ----- - -.. Set `reportFormat` to one of `csv`, `json`, or `tabular` to specify the output format of the API response: -+ -[source,terminal] ----- -$ reportFormat=csv ----- - -.. To get the results, use `curl` to make a request to the reporting API for your Report: -+ -[source,terminal] ----- -$ curl --insecure -H "Authorization: Bearer ${token}" "https://${meteringroute}/api/v1/reports/get?name=${reportName}&namespace=openshift-metering&format=$reportFormat" ----- -+ -.Example output with `reportName=namespace-cpu-request-2019` and `reportFormat=csv` -[source,terminal] ----- -period_start,period_end,namespace,pod_request_cpu_core_seconds -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-apiserver,11745.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-apiserver-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-authentication,522.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-authentication-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-cloud-credential-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-cluster-machine-approver,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-cluster-node-tuning-operator,3385.800000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-cluster-samples-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-cluster-version,522.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-console,522.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-console-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-controller-manager,7830.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-controller-manager-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-dns,34372.800000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-dns-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-etcd,23490.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-image-registry,5993.400000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-ingress,5220.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-ingress-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-kube-apiserver,12528.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-kube-apiserver-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-kube-controller-manager,8613.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-kube-controller-manager-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-machine-api,1305.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-machine-config-operator,9637.800000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-metering,19575.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-monitoring,6256.800000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-network-operator,261.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-sdn,94503.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-service-ca,783.000000 -2019-01-01 00:00:00 +0000 UTC,2019-12-30 23:59:59 +0000 UTC,openshift-service-ca-operator,261.000000 ----- diff --git a/modules/metering-writing-reports.adoc b/modules/metering-writing-reports.adoc deleted file mode 100644 index 7d39606623de..000000000000 --- a/modules/metering-writing-reports.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * metering/metering-using-metering.adoc -[id="metering-writing-reports_{context}"] -= Writing Reports - -Writing a Report is the way to process and analyze data using Metering. - -To write a Report, you must define a Report resource in a YAML file, specify the required parameters, and create it in the `openshift-metering` namespace by using `oc`. - -.Prerequisites - -* Metering is installed. - -.Procedure - -. Change to the `openshift-metering` project: -+ -[source,terminal] ----- -$ oc project openshift-metering ----- - -. Create a Report resource as a YAML file: -+ -.. Create a YAML file with the following content: -+ -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: namespace-cpu-request-2019 <2> - namespace: openshift-metering -spec: - reportingStart: '2019-01-01T00:00:00Z' - reportingEnd: '2019-12-30T23:59:59Z' - query: namespace-cpu-request <1> - runImmediately: true <3> ----- -<1> The `query` specifies ReportQuery used to generate the Report. Change this based on what you want to report on. For a list of options, run `oc get reportqueries | grep -v raw`. -<2> Use a descriptive name about what the Report does for `metadata.name`. A good name is the query, and the schedule or period you used. -<3> Set `runImmediately` to `true` for it to run with whatever data is available, or set it to `false` if you want it to wait for `reportingEnd` to pass. - -.. Run the following command to create the Report: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -.Example output -[source,terminal] ----- -report.metering.openshift.io/namespace-cpu-request-2019 created ----- -+ - -. You can list Reports and their `Running` status with the following command: -+ -[source,terminal] ----- -$ oc get reports ----- -+ -.Example output -[source,terminal] ----- -NAME QUERY SCHEDULE RUNNING FAILED LAST REPORT TIME AGE -namespace-cpu-request-2019 namespace-cpu-request Finished 2019-12-30T23:59:59Z 26s ----- diff --git a/modules/metrics-and-logging.adoc b/modules/metrics-and-logging.adoc new file mode 100644 index 000000000000..fb650e5b4b0e --- /dev/null +++ b/modules/metrics-and-logging.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_mod-docs-content-type: CONCEPT +[id="metrics-and-logging_{context}"] += Metrics and Logging + +[id="service-metrics_{context}"] +== Service metrics + +Service metrics are internal only. +Red{nbsp}Hat provides and maintains the service at the agreed upon level. +Service metrics are accessible only to authorized Red{nbsp}Hat personnel. For more information, see link:https://www.redhat.com/licenses/Appendix_4_Red_Hat_Online_Services_20221213.pdf[PRODUCT APPENDIX 4 RED HAT ONLINE SERVICES]. + +[id="customer-metrics_{context}"] +== Customer metrics + +Core usage capacity metrics are available either through link:https://access.redhat.com/articles/subscription-watch[Subscription Watch] or the link:https://console.redhat.com/beta/application-services/subscriptions/acs[Subscriptions page]. + + +[id="service-logging_{context}"] +== Service logging + +System logs for all components of the {rh-rhacscs-first} are internal and available only to Red{nbsp}Hat personnel. +Red{nbsp}Hat does not provide user access to component logs. For more information, see link:https://www.redhat.com/licenses/Appendix_4_Red_Hat_Online_Services_20221213.pdf[PRODUCT APPENDIX 4 RED HAT ONLINE SERVICES]. diff --git a/modules/migrate-scope-collections.adoc b/modules/migrate-scope-collections.adoc new file mode 100644 index 000000000000..09c5fe6d26bd --- /dev/null +++ b/modules/migrate-scope-collections.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * operating/create-use-collections.adoc +:_mod-docs-content-type: CONCEPT +[id="migrate-scope-collections_{context}"] += Migration of access scopes to collections + +Database changes in {product-title-short} from `rocksdb` to PostgreSQL are provided as a Technology Preview beginning with release 3.74 and are generally available in release 4.0. When the database is migrated from `rocksdb` to PostgreSQL, existing access scopes used in vulnerability reporting are migrated to collections. You can verify that the migration resulted in the correct configuration for your existing reports by navigating to *Vulnerability Management* -> *Reporting* and viewing the report information. + +The migration process creates collection objects for access scopes that were used in report configurations. {product-title-short} generates two or more collections for a single access scope, depending on the complexity of the access scope. The generated collections for a given access scope include the following types: + +* Embedded collections: To mimic the exact selection logic of the original access scope, {product-title-short} generates one or more collections where matched deployments result in the same selection of clusters and namespaces as the original access scope. The collection name is in the format of `System-generated embedded collection _number_ for the scope` where _number_ is a number starting from 0. ++ +[NOTE] +==== +These embedded collections will not have any attached collections. They have cluster and namespace selection rules, but no deployment rules because the original access scopes did not filter on deployments. +==== +* Root collection for the access scope: This collection is added to the report configurations. The collection name is in the format of `System-generated root collection for the scope`. This collection does not define any rules, but attaches one or more embedded collections. The combination of these embedded collections results in the same selection of clusters and namespaces as the original access scope. + +For access scopes that define cluster or namespace label selectors, {product-title-short} can only migrate those scopes that have the 'IN' operator between the key and values. Access scopes with label selectors that were created by using the {product-title-short} portal used the 'IN' operator by default. Migration of scopes that used the 'NOT_IN', 'EXISTS' and 'NOT_EXISTS' operators is not supported. If a collection cannot be created for an access scope, log messages are created during the migration. Log messages have the following format: + +---- +Failed to create collections for scope _scope-name_: Unsupported operator NOT_IN in scope's label selectors. Only operator 'IN' is supported. +The scope is attached to the following report configurations: [list of report configs]; Please manually create an equivalent collection and edit the listed report configurations to use this collection. Note that reports will not function correctly until a collection is attached. +---- + +You can also click the report in *Vulnerability Management* -> *Reporting* to view the report information page. This page contains a message if a report needs a collection attached to it. + +[NOTE] +==== +The original access scopes are not removed during the migration. If you created an access scope only for use in filtering vulnerability management reports, you can manually remove the access scope. +==== diff --git a/modules/migrating-custom-types-pkg-apis.adoc b/modules/migrating-custom-types-pkg-apis.adoc deleted file mode 100644 index 011996e0711d..000000000000 --- a/modules/migrating-custom-types-pkg-apis.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc - -[id="migrating-custom-types-from-pkg-apis_{context}"] -= Migrating custom types from pkg/apis - -Migrate your project's custom types to the updated Operator SDK v0.1.0 usage. - -.Prerequisites - -- Operator SDK v0.1.0 CLI installed on the development workstation -- `memcached-operator` project previously deployed using an earlier version of -Operator SDK -- New project created using Operator SDK v0.1.0 - -.Procedure - -. *Create the scaffold API for custom types.* - -.. Create the API for your custom resource (CR) in the new project with -`operator-sdk add api --api-version=<apiversion> --kind=<kind>`: -+ ----- -$ cd memcached-operator -$ operator-sdk add api --api-version=cache.example.com/v1alpha1 --kind=Memcached - -$ tree pkg/apis -pkg/apis/ -├── addtoscheme_cache_v1alpha1.go -├── apis.go -└── cache - └── v1alpha1 - ├── doc.go - ├── memcached_types.go - ├── register.go - └── zz_generated.deepcopy.go ----- - -.. Repeat the previous command for as many custom types as you had defined in your -old project. Each type will be defined in the file -`pkg/apis/<group>/<version>/<kind>_types.go`. - -. *Copy the contents of the type.* - -.. Copy the `Spec` and `Status` contents of the -`pkg/apis/<group>/<version>/types.go` file from the old project to the new -project's `pkg/apis/<group>/<version>/<kind>_types.go` file. - -.. Each `<kind>_types.go` file has an `init()` function. Be sure not to remove that -since that registers the type with the Manager's scheme: -+ ----- -func init() { - SchemeBuilder.Register(&Memcached{}, &MemcachedList{}) ----- diff --git a/modules/migrating-reconcile-code.adoc b/modules/migrating-reconcile-code.adoc deleted file mode 100644 index c1270b149a64..000000000000 --- a/modules/migrating-reconcile-code.adoc +++ /dev/null @@ -1,304 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc - -[id="migrating-reconcile-code_{context}"] -= Migrating reconcile code - -Migrate your project's reconcile code to the update Operator SDK v0.1.0 usage. - -.Prerequisites - -- Operator SDK v0.1.0 CLI installed on the development workstation -- `memcached-operator` project previously deployed using an earlier version of -Operator SDK -- Custom types migrated from `pkg/apis/` - -.Procedure - -. *Add a controller to watch your CR.* -+ -In v0.0.x projects, resources to be watched were previously defined in -`cmd/<operator-name>/main.go`: -+ ----- -sdk.Watch("cache.example.com/v1alpha1", "Memcached", "default", time.Duration(5)*time.Second) ----- -+ -For v0.1.0 projects, you must define a -link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg#hdr-Controller[Controller] -to watch resources: - -.. Add a controller to watch your CR type with `operator-sdk add controller --api-version=<apiversion> --kind=<kind>`. -+ ----- -$ operator-sdk add controller --api-version=cache.example.com/v1alpha1 --kind=Memcached - -$ tree pkg/controller -pkg/controller/ -├── add_memcached.go -├── controller.go -└── memcached - └── memcached_controller.go ----- - -.. Inspect the `add()` function in your `pkg/controller/<kind>/<kind>_controller.go` file: -+ ----- -import ( - cachev1alpha1 "github.com/example-inc/memcached-operator/pkg/apis/cache/v1alpha1" - ... -) - -func add(mgr manager.Manager, r reconcile.Reconciler) error { - c, err := controller.New("memcached-controller", mgr, controller.Options{Reconciler: r}) - - // Watch for changes to the primary resource Memcached - err = c.Watch(&source.Kind{Type: &cachev1alpha1.Memcached{}}, &handler.EnqueueRequestForObject{}) - - // Watch for changes to the secondary resource pods and enqueue reconcile requests for the owner Memcached - err = c.Watch(&source.Kind{Type: &corev1.Pod{}}, &handler.EnqueueRequestForOwner{ - IsController: true, - OwnerType: &cachev1alpha1.Memcached{}, - }) -} ----- -+ -Remove the second `Watch()` or modify it to watch a secondary resource type that -is owned by your CR. -+ -Watching multiple resources lets you trigger the reconcile loop for multiple -resources relevant to your application. See the -link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg#hdr-Watching_and_EventHandling[watching and eventhandling] -documentation and the Kubernetes -link:https://github.com/kubernetes/community/blob/master/contributors/devel/controllers.md#guidelines[controller conventions] -documentation for more details. -+ -If your operator is watching more than one CR type, you can do one of the -following depending on your application: -+ --- -** If the CR is owned by your primary CR, watch it as a secondary resource in -the same controller to trigger the reconcile loop for the primary resource. -+ ----- -// Watch for changes to the primary resource Memcached - err = c.Watch(&source.Kind{Type: &cachev1alpha1.Memcached{}}, &handler.EnqueueRequestForObject{}) - - // Watch for changes to the secondary resource AppService and enqueue reconcile requests for the owner Memcached - err = c.Watch(&source.Kind{Type: &appv1alpha1.AppService{}}, &handler.EnqueueRequestForOwner{ - IsController: true, - OwnerType: &cachev1alpha1.Memcached{}, - }) ----- - -** Add a new controller to watch and reconcile the CR independently of the other CR. -+ ----- -$ operator-sdk add controller --api-version=app.example.com/v1alpha1 --kind=AppService ----- -+ ----- - // Watch for changes to the primary resource AppService - err = c.Watch(&source.Kind{Type: &appv1alpha1.AppService{}}, &handler.EnqueueRequestForObject{}) ----- --- - -. *Copy and modify reconcile code from `pkg/stub/handler.go`.* -+ -In a v0.1.0 project, the reconcile code is defined in the `Reconcile()` method -of a controller's -link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Reconciler[Reconciler]. -This is similar to the `Handle()` function in the older project. Note the -difference in the arguments and return values: -+ --- -- Reconcile: -+ ----- - func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Result, error) ----- - -- Handle: -+ ----- - func (h *Handler) Handle(ctx context.Context, event sdk.Event) error ----- --- -+ -Instead of receiving an `sdk.Event` (with the object), the `Reconcile()` -function receives a -link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Request[Request] -(`Name`/`Namespace` key) to lookup the object. -+ -If the `Reconcile()` function returns an error, the controller will requeue and -retry the `Request`. If no error is returned, then depending on the -link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result[Result], -the controller will either not retry the `Request`, immediately retry, or retry -after a specified duration. - -.. Copy the code from the old project's `Handle()` function over the existing code -in your controller's `Reconcile()` function. Be sure to keep the initial section -in the `Reconcile()` code that looks up the object for the `Request` and checks -to see if it is deleted. -+ ----- -import ( - apierrors "k8s.io/apimachinery/pkg/api/errors" - cachev1alpha1 "github.com/example-inc/memcached-operator/pkg/apis/cache/v1alpha1" - ... -) -func (r *ReconcileMemcached) Reconcile(request reconcile.Request) (reconcile.Result, error) { - // Fetch the Memcached instance - instance := &cachev1alpha1.Memcached{} - err := r.client.Get(context.TODO() - request.NamespacedName, instance) - if err != nil { - if apierrors.IsNotFound(err) { - // Request object not found, could have been deleted after reconcile request. - // Owned objects are automatically garbage collected. - // Return and don't requeue - return reconcile.Result{}, nil - } - // Error reading the object - requeue the request. - return reconcile.Result{}, err - } - - // Rest of your reconcile code goes here. - ... -} ----- - -.. Change the return values in your reconcile code: - -... Replace `return err` with `return reconcile.Result{}, err`. - -... Replace `return nil` with `return reconcile.Result{}, nil`. - -.. To periodically reconcile a CR in your controller, you can set the -link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Result[RequeueAfter] -field for `reconcile.Result`. This will cause the controller to requeue the -`Request` and trigger the reconcile after the desired duration. Note that the -default value of `0` means no requeue. -+ ----- -reconcilePeriod := 30 * time.Second -reconcileResult := reconcile.Result{RequeueAfter: reconcilePeriod} -... - -// Update the status -err := r.client.Update(context.TODO(), memcached) -if err != nil { - log.Printf("failed to update memcached status: %v", err) - return reconcileResult, err -} -return reconcileResult, nil ----- - -.. Replace the calls to the SDK client (Create, Update, Delete, Get, List) with the -reconciler's client. -+ -See the examples below and the `controller-runtime` -link:https://github.com/operator-framework/operator-sdk/blob/master/doc/user/client.md[client API documentation] -in the `operator-sdk` project for more details: -+ ----- -// Create -dep := &appsv1.Deployment{...} -err := sdk.Create(dep) -// v0.0.1 -err := r.client.Create(context.TODO(), dep) - -// Update -err := sdk.Update(dep) -// v0.0.1 -err := r.client.Update(context.TODO(), dep) - -// Delete -err := sdk.Delete(dep) -// v0.0.1 -err := r.client.Delete(context.TODO(), dep) - -// List -podList := &corev1.PodList{} -labelSelector := labels.SelectorFromSet(labelsForMemcached(memcached.Name)) -listOps := &metav1.ListOptions{LabelSelector: labelSelector} -err := sdk.List(memcached.Namespace, podList, sdk.WithListOptions(listOps)) -// v0.1.0 -listOps := &client.ListOptions{Namespace: memcached.Namespace, LabelSelector: labelSelector} -err := r.client.List(context.TODO(), listOps, podList) - -// Get -dep := &appsv1.Deployment{APIVersion: "apps/v1", Kind: "Deployment", Name: name, Namespace: namespace} -err := sdk.Get(dep) -// v0.1.0 -dep := &appsv1.Deployment{} -err = r.client.Get(context.TODO(), types.NamespacedName{Name: name, Namespace: namespace}, dep) ----- - -.. Copy and initialize any other fields that you may have had in your `Handler` -struct into the `Reconcile<Kind>` struct: -+ ----- -// newReconciler returns a new reconcile.Reconciler -func newReconciler(mgr manager.Manager) reconcile.Reconciler { - return &ReconcileMemcached{client: mgr.GetClient(), scheme: mgr.GetScheme(), foo: "bar"} -} - -// ReconcileMemcached reconciles a Memcached object -type ReconcileMemcached struct { - client client.Client - scheme *runtime.Scheme - // Other fields - foo string -} ----- - -. *Copy changes from `main.go`.* -+ -The main function for a v0.1.0 operator in `cmd/manager/main.go` sets up the -link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager[Manager], -which registers the custom resources and starts all the controllers. -+ -There is no requirement to migrate the SDK functions `sdk.Watch()`,`sdk.Handle()`, and -`sdk.Run()` from the old `main.go` since that logic is now defined in a -controller. -+ -However, if there are any Operator-specific flags or settings defined in the old -`main.go` file, copy those over. -+ -If you have any third party resource types registered with the SDK's scheme, see -link:https://github.com/operator-framework/operator-sdk/blob/master/doc/user-guide.md#adding-3rd-party-resources-to-your-operator[Advanced Topics] -in the `operator-sdk` project for how to register those with the Manager's -scheme in the new project. - -. *Copy user defined files.* -+ -If there are any user defined `pkgs`, scripts, or documentation in the older -project, copy these files into the new project. - -. *Copy changes to deployment manifests.* -+ -For any updates made to the following manifests in the old project, copy over -the changes to their corresponding files in the new project. Be careful not to -directly overwrite the files, but inspect and make any changes necessary: -+ --- -* `tmp/build/Dockerfile` to `build/Dockerfile` -** There is no tmp directory in the new project layout -* RBAC rules updates from `deploy/rbac.yaml` to `deploy/role.yaml` and -`deploy/role_binding.yaml` -* `deploy/cr.yaml` to `deploy/crds/<group>_<version>_<kind>_cr.yaml` -* `deploy/crd.yaml` to `deploy/crds/<group>_<version>_<kind>_crd.yaml` --- - -. *Copy user defined dependencies.* -+ -For any user defined dependencies added to the old project's `Gopkg.toml`, copy -and append them to the new project's `Gopkg.toml`. Run `dep ensure` to update -the vendor in the new project. - -. *Confirm your changes.* -+ -At this point, you should be able to build and run your Operator to verify that -it works. diff --git a/modules/migrating-sccs-during-the-manual-upgrade.adoc b/modules/migrating-sccs-during-the-manual-upgrade.adoc new file mode 100644 index 000000000000..eefcc7c9df47 --- /dev/null +++ b/modules/migrating-sccs-during-the-manual-upgrade.adoc @@ -0,0 +1,374 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-roxctl.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="migrating-sccs-during-the-manual-upgrade_{context}"] += Migrating SCCs during the manual upgrade + +ifeval::["{context}" == "upgrade-cloudsvc-roxctl"] +:cloud-svc: +endif::[] + +By migrating the security context constraints (SCCs) during the manual upgrade by using `roxctl` CLI, you can seamlessly transition the {rh-rhacs-first} services to use the {osp} SCCs, ensuring compatibility and optimal security configurations across Central and all secured clusters. + +.Procedure + +ifndef::cloud-svc[] +. List all of the {product-title-short} services that are deployed on Central and all secured clusters: +endif::cloud-svc[] +ifdef::cloud-svc[] +. List all of the {product-title-short} services that are deployed on all secured clusters: +endif::cloud-svc[] ++ +[source,terminal] +---- +$ oc -n stackrox describe pods | grep 'openshift.io/scc\|^Name:' +---- ++ +.Example output ++ +[source,text,subs="+quotes"] +---- +Name: admission-control-6f4dcc6b4c-2phwd + *openshift.io/scc: stackrox-admission-control* +#... +Name: central-575487bfcb-sjdx8 + *openshift.io/scc: stackrox-central* +Name: central-db-7c7885bb-6bgbd + *openshift.io/scc: stackrox-central-db* +Name: collector-56nkr + *openshift.io/scc: stackrox-collector* +#... +Name: scanner-68fc55b599-f2wm6 + *openshift.io/scc: stackrox-scanner* +Name: scanner-68fc55b599-fztlh +#... +Name: sensor-84545f86b7-xgdwf + *openshift.io/scc: stackrox-sensor* +#... +---- ++ +In this example, you can see that each pod has its own custom SCC, which is specified through the `openshift.io/scc` field. + +. Add the required roles and role bindings to use the {osp} SCCs instead of the {product-title-short} custom SCCs. +ifndef::cloud-svc[] ++ +To add the required roles and role bindings to use the {osp} SCCs for the Central cluster, complete the following steps: + +.. Create a file named `update-central.yaml` that defines the role and role binding resources by using the following content: ++ +.Example YAML file +[%collapsible] +==== +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role # <1> +metadata: + annotations: + email: support@stackrox.com + owner: stackrox + labels: + app.kubernetes.io/component: central + app.kubernetes.io/instance: stackrox-central-services + app.kubernetes.io/name: stackrox + app.kubernetes.io/part-of: stackrox-central-services + app.kubernetes.io/version: 4.4.0 + name: use-central-db-scc # <2> + namespace: stackrox # <3> +Rules: # <4> +- apiGroups: + - security.openshift.io + resourceNames: + - nonroot-v2 + resources: + - securitycontextconstraints + verbs: + - use +- - - +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + annotations: + email: support@stackrox.com + owner: stackrox + labels: + app.kubernetes.io/component: central + app.kubernetes.io/instance: stackrox-central-services + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: stackrox + app.kubernetes.io/part-of: stackrox-central-services + app.kubernetes.io/version: 4.4.0 + name: use-central-scc + namespace: stackrox +rules: +- apiGroups: + - security.openshift.io + resourceNames: + - nonroot-v2 + resources: + - securitycontextconstraints + verbs: + - use +- - - +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + annotations: + email: support@stackrox.com + owner: stackrox + labels: + app.kubernetes.io/component: scanner + app.kubernetes.io/instance: stackrox-central-services + app.kubernetes.io/name: stackrox + app.kubernetes.io/part-of: stackrox-central-services + app.kubernetes.io/version: 4.4.0 + name: use-scanner-scc + namespace: stackrox +rules: +- apiGroups: + - security.openshift.io + resourceNames: + - nonroot-v2 + resources: + - securitycontextconstraints + verbs: + - use +- - - +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding # <5> +metadata: + annotations: + email: support@stackrox.com + owner: stackrox + labels: + app.kubernetes.io/component: central + app.kubernetes.io/instance: stackrox-central-services + app.kubernetes.io/name: stackrox + app.k ubernetes.io/part-of: stackrox-central-services + app.kubernetes.io/version: 4.4.0 + name: central-db-use-scc # <6> + namespace: stackrox +roleRef: # <7> + apiGroup: rbac.authorization.k8s.io + kind: Role + name: use-central-db-scc +subjects: # <8> +- kind: ServiceAccount + name: central-db + namespace: stackrox +- - - +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + annotations: + email: support@stackrox.com + owner: stackrox + labels: + app.kubernetes.io/component: central + app.kubernetes.io/instance: stackrox-central-services + app.kubernetes.io/name: stackrox + app.kubernetes.io/part-of: stackrox-central-services + app.kubernetes.io/version: 4.4.0 + name: central-use-scc + namespace: stackrox +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: use-central-scc +subjects: +- kind: ServiceAccount + name: central + namespace: stackrox +- - - +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + annotations: + email: support@stackrox.com + owner: stackrox + labels: + app.kubernetes.io/component: scanner + app.kubernetes.io/instance: stackrox-central-services + app.kubernetes.io/name: stackrox + app.kubernetes.io/part-of: stackrox-central-services + app.kubernetes.io/version: 4.4.0 + name: scanner-use-scc + namespace: stackrox +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: use-scanner-scc +subjects: +- kind: ServiceAccount + name: scanner + namespace: stackrox +- - - +---- +<1> The type of Kubernetes resource, in this example, `Role`. +<2> The name of the role resource. +<3> The namespace in which the role is created. +<4> Describes the permissions granted by the role resource. +<5> The type of Kubernetes resource, in this example, `RoleBinding`. +<6> The name of the role binding resource. +<7> Specifies the role to bind in the same namespace. +<8> Specifies the subjects that are bound to the role. +==== + +.. Create the role and role binding resources specified in the `update-central.yaml` file by running the following command: ++ +[source,terminal] +---- +$ oc -n stackrox create -f ./update-central.yaml +---- +endif::cloud-svc[] +. To add the required roles and role bindings to use the {osp} SCCs for all secured clusters, complete the following steps: + +.. Create a file named `upgrade-scs.yaml` that defines the role and role binding resources by using the following content: ++ +.Example YAML file +[%collapsible] +==== +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role # <1> +metadata: + annotations: + email: support@stackrox.com + owner: stackrox + labels: + app.kubernetes.io/component: collector + app.kubernetes.io/instance: stackrox-secured-cluster-services + app.kubernetes.io/name: stackrox + app.kubernetes.io/part-of: stackrox-secured-cluster-services + app.kubernetes.io/version: 4.4.0 + auto-upgrade.stackrox.io/component: sensor + name: use-privileged-scc # <2> + namespace: stackrox # <3> +rules: # <4> +- apiGroups: + - security.openshift.io + resourceNames: + - privileged + resources: + - securitycontextconstraints + verbs: + - use +- - - +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding # <5> +metadata: + annotations: + email: support@stackrox.com + owner: stackrox + labels: + app.kubernetes.io/component: collector + app.kubernetes.io/instance: stackrox-secured-cluster-services + app.kubernetes.io/name: stackrox + app.kubernetes.io/part-of: stackrox-secured-cluster-services + app.kubernetes.io/version: 4.4.0 + auto-upgrade.stackrox.io/component: sensor + name: collector-use-scc # <6> + namespace: stackrox +roleRef: # <7> + apiGroup: rbac.authorization.k8s.io + kind: Role + name: use-privileged-scc +subjects: # <8> +- kind: ServiceAccount + name: collector + namespace: stackrox +- - - +---- +<1> The type of Kubernetes resource, in this example, `Role`. +<2> The name of the role resource. +<3> The namespace in which the role is created. +<4> Describes the permissions granted by the role resource. +<5> The type of Kubernetes resource, in this example, `RoleBinding`. +<6> The name of the role binding resource. +<7> Specifies the role to bind in the same namespace. +<8> Specifies the subjects that are bound to the role. +==== + +.. Create the role and role binding resources specified in the `upgrade-scs.yaml` file by running the following command: ++ +[source,terminal] +---- +$ oc -n stackrox create -f ./update-scs.yaml +---- ++ +[IMPORTANT] +==== +You must run this command on each secured cluster to create the role and role bindings specified in the `upgrade-scs.yaml` file. +==== + +. Delete the SCCs that are specific to {product-title-short}: +ifndef::cloud-svc[] +.. To delete the SCCs that are specific to the Central cluster, run the following command: ++ +[source,terminal] +---- +$ oc delete scc/stackrox-central scc/stackrox-central-db scc/stackrox-scanner +---- +endif::cloud-svc[] +.. To delete the SCCs that are specific to all secured clusters, run the following command: ++ +[source,terminal] +---- +$ oc delete scc/stackrox-admission-control scc/stackrox-collector scc/stackrox-sensor +---- ++ +[IMPORTANT] +==== +You must run this command on each secured cluster to delete the SCCs that are specific to each secured cluster. +==== + +.Verification + +* Ensure that all the pods are using the correct SCCs by running the following command: ++ +[source,terminal] +---- +$ oc -n stackrox describe pods | grep 'openshift.io/scc\|^Name:' +---- ++ +Compare the output with the following table: ++ +[cols="2,2,2",options="header"] +|=== +|Component |Previous custom SCC |New {osp} 4 SCC + +|Central +|`stackrox-central` +|`nonroot-v2` + +|Central-db +|`stackrox-central-db` +|`nonroot-v2` + +|Scanner +|`stackrox-scanner` +|`nonroot-v2` + +|Scanner-db +|`stackrox-scanner` +|`nonroot-v2` + +|Admission Controller +|`stackrox-admission-control` +|`restricted-v2` + +|Collector +|`stackrox-collector` +|`privileged` + +|Sensor +|`stackrox-sensor` +|`restricted-v2` +|=== + +ifeval::["{context}" == "upgrade-cloudsvc-roxctl"] +:!cloud-svc: +endif::[] \ No newline at end of file diff --git a/modules/migration-about-migration-hooks.adoc b/modules/migration-about-migration-hooks.adoc deleted file mode 100644 index dc94c377251a..000000000000 --- a/modules/migration-about-migration-hooks.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/migrating-application-workloads-3-4.adoc -// * migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc - -[id='migration-about-migration-hooks_{context}'] -= About migration hooks - -You can use migration hooks to run custom code at certain points during a migration with the {mtc-full} ({mtc-short}). You can add up to four migration hooks to a single migration plan, with each hook running at a different phase of the migration. - -Migration hooks perform tasks such as customizing application quiescence, manually migrating unsupported data types, and updating applications after migration. - -A migration hook runs on a source or a target cluster at one of the following migration steps: - -* `PreBackup`: Before resources are backed up on the source cluster -* `PostBackup`: After resources are backed up on the source cluster -* `PreRestore`: Before resources are restored on the target cluster -* `PostRestore`: After resources are restored on the target cluster - -You can create a hook by using an Ansible playbook or a custom hook container. - -.Ansible playbook - -The Ansible playbook is mounted on a hook container as a config map. The hook container runs as a job, using the cluster, service account, and namespace specified in the `MigPlan` custom resource (CR). The job continues to run until it reaches the the default limit of 6 retries or a successful completion. This continues even if the initial pod is evicted or killed. - -The default Ansible runtime image is `registry.redhat.io/rhmtc/openshift-migration-hook-runner-rhel7:latest`. This image is based on the Ansible Runner image and includes `python-openshift` for Ansible Kubernetes resources and an updated `oc` binary. - -Optional: You can use a custom Ansible runtime image containing additional Ansible modules or tools instead of the default image. - -.Custom hook container - -You can create a custom hook container that includes Ansible playbooks or custom code. diff --git a/modules/migration-adding-cluster-to-cam.adoc b/modules/migration-adding-cluster-to-cam.adoc deleted file mode 100644 index e0c43dc95abf..000000000000 --- a/modules/migration-adding-cluster-to-cam.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='migration-adding-cluster-to-cam_{context}'] -= Adding a cluster to the {mtc-short} web console - -You can add a cluster to the {mtc-full} ({mtc-short}) web console. - -.Prerequisites - -* If you are using direct image migration, the source cluster must not have an HTTP proxy configured. -* If you are using Azure snapshots to copy data: -** You must specify the Azure resource group name for the cluster. -** The clusters must be in the same Azure resource group. -** The clusters must be in the same geographic location. - -.Procedure - -. Log in to the cluster. -. Obtain the `migration-controller` service account token: -+ -[source,terminal] ----- -$ oc sa get-token migration-controller -n openshift-migration ----- -+ -.Example output -+ -[source,terminal] ----- -eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJtaWciLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlY3JldC5uYW1lIjoibWlnLXRva2VuLWs4dDJyIiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQubmFtZSI6Im1pZyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VydmljZS1hY2NvdW50LnVpZCI6ImE1YjFiYWMwLWMxYmYtMTFlOS05Y2NiLTAyOWRmODYwYjMwOCIsInN1YiI6InN5c3RlbTpzZXJ2aWNlYWNjb3VudDptaWc6bWlnIn0.xqeeAINK7UXpdRqAtOj70qhBJPeMwmgLomV9iFxr5RoqUgKchZRG2J2rkqmPm6vr7K-cm7ibD1IBpdQJCcVDuoHYsFgV4mp9vgOfn9osSDp2TGikwNz4Az95e81xnjVUmzh-NjDsEpw71DH92iHV_xt2sTwtzftS49LpPW2LjrV0evtNBP_t_RfskdArt5VSv25eORl7zScqfe1CiMkcVbf2UqACQjo3LbkpfN26HAioO2oH0ECPiRzT0Xyh-KwFutJLS9Xgghyw-LD9kPKcE_xbbJ9Y4Rqajh7WdPYuB0Jd9DPVrslmzK-F6cgHHYoZEv0SvLQi-PO0rpDrcjOEQQ ----- - -. In the {mtc-short} web console, click *Clusters*. -. Click *Add cluster*. -. Fill in the following fields: - -* *Cluster name*: The cluster name can contain lower-case letters (`a-z`) and numbers (`0-9`). It must not contain spaces or international characters. -* *URL*: Specify the API server URL, for example, `\https://<www.example.com>:8443`. -* *Service account token*: Paste the `migration-controller` service account token. -* *Exposed route host to image registry*: If you are using direct image migration, specify the exposed route to the image registry of the source cluster, for example, `www.example.apps.cluster.com`. -+ -You can specify a port. The default port is `5000`. - -* *Azure cluster*: You must select this option if you use Azure snapshots to copy your data. -* *Azure resource group*: This field is displayed if *Azure cluster* is selected. Specify the Azure resource group. -* *Require SSL verification*: Optional: Select this option to verify SSL connections to the cluster. -* *CA bundle file*: This field is displayed if *Require SSL verification* is selected. If you created a custom CA certificate bundle file for self-signed certificates, click *Browse*, select the CA bundle file, and upload it. - -. Click *Add cluster*. -+ -The cluster appears in the *Clusters* list. diff --git a/modules/migration-adding-replication-repository-to-cam.adoc b/modules/migration-adding-replication-repository-to-cam.adoc deleted file mode 100644 index 61cdd87cd294..000000000000 --- a/modules/migration-adding-replication-repository-to-cam.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='migration-adding-replication-repository-to-cam_{context}'] -= Adding a replication repository to the {mtc-short} web console - -You can add an object storage bucket as a replication repository to the {mtc-full} ({mtc-short}) web console. - -.Prerequisites - -* You must configure an object storage bucket for migrating the data. - -.Procedure - -. In the {mtc-short} web console, click *Replication repositories*. -. Click *Add repository*. -. Select a *Storage provider type* and fill in the following fields: - -* *AWS* for AWS S3, MCG, and generic S3 providers: - -** *Replication repository name*: Specify the replication repository name in the {mtc-short} web console. -** *S3 bucket name*: Specify the name of the S3 bucket you created. -** *S3 bucket region*: Specify the S3 bucket region. *Required* for AWS S3. *Optional* for other S3 providers. -** *S3 endpoint*: Specify the URL of the S3 service, not the bucket, for example, `\https://<s3-storage.apps.cluster.com>`. *Required* for a generic S3 provider. You must use the `https://` prefix. - -** *S3 provider access key*: Specify the `<AWS_SECRET_ACCESS_KEY>` for AWS or the S3 provider access key for MCG. -** *S3 provider secret access key*: Specify the `<AWS_ACCESS_KEY_ID>` for AWS or the S3 provider secret access key for MCG. -** *Require SSL verification*: Clear this check box if you are using a generic S3 provider. -** If you use a custom CA bundle, click *Browse* and browse to the Base64-encoded CA bundle file. - -* *GCP*: - -** *Replication repository name*: Specify the replication repository name in the {mtc-short} web console. -** *GCP bucket name*: Specify the name of the GCP bucket. -** *GCP credential JSON blob*: Specify the string in the `credentials-velero` file. - -* *Azure*: - -** *Replication repository name*: Specify the replication repository name in the {mtc-short} web console. -** *Azure resource group*: Specify the resource group of the Azure Blob storage. -** *Azure storage account name*: Specify the Azure Blob storage account name. -** *Azure credentials - INI file contents*: Specify the string in the `credentials-velero` file. - -. Click *Add repository* and wait for connection validation. - -. Click *Close*. -+ -The new repository appears in the *Replication repositories* list. diff --git a/modules/migration-changing-migration-plan-limits.adoc b/modules/migration-changing-migration-plan-limits.adoc deleted file mode 100644 index e6e5892901a4..000000000000 --- a/modules/migration-changing-migration-plan-limits.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='migration-changing-migration-plan-limits_{context}'] -= Increasing limits for large migrations - -You can increase the limits on migration objects and container resources for large migrations with the {mtc-full} ({mtc-short}). - -[IMPORTANT] -==== -You must test these changes before you perform a migration in a production environment. -==== - -.Procedure - -. Edit the `MigrationController` CR manifest: -+ -[source,terminal] ----- -$ oc edit migrationcontroller -n openshift-migration ----- - -. Update the following parameters: -+ -[source,yaml] ----- -... -mig_controller_limits_cpu: "1" <1> -mig_controller_limits_memory: "10Gi" <2> -... -mig_controller_requests_cpu: "100m" <3> -mig_controller_requests_memory: "350Mi" <4> -... -mig_pv_limit: 100 <5> -mig_pod_limit: 100 <6> -mig_namespace_limit: 10 <7> -... ----- -<1> Specifies the number of CPUs available to the `MigrationController` CR. -<2> Specifies the amount of memory available to the `MigrationController` CR. -<3> Specifies the number of CPU units available for `MigrationController` CR requests. `100m` represents 0.1 CPU units (100 * 1e-3). -<4> Specifies the amount of memory available for `MigrationController` CR requests. -<5> Specifies the number of persistent volumes that can be migrated. -<6> Specifies the number of pods that can be migrated. -<7> Specifies the number of namespaces that can be migrated. - -. Create a migration plan that uses the updated parameters to verify the changes. -+ -If your migration plan exceeds the `MigrationController` CR limits, the {mtc-short} console displays a warning message when you save the migration plan. diff --git a/modules/migration-configuring-aws-s3.adoc b/modules/migration-configuring-aws-s3.adoc deleted file mode 100644 index 8c33bd8f479a..000000000000 --- a/modules/migration-configuring-aws-s3.adoc +++ /dev/null @@ -1,147 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/configuring-replication-repository-3-4.adoc -// * migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc -// * migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc - -[id='migration-configuring-aws-s3_{context}'] -= Configuring an AWS S3 storage bucket as a replication repository - -You can configure an AWS S3 storage bucket as a replication repository for the {mtc-full} ({mtc-short}). - -.Prerequisites - -* The AWS S3 storage bucket must be accessible to the source and target clusters. -* You must have the link:https://aws.amazon.com/cli/[AWS CLI] installed. -* If you are using the snapshot copy method: -** You must have access to EC2 Elastic Block Storage (EBS). -** The source and target clusters must be in the same region. -** The source and target clusters must have the same storage class. -** The storage class must be compatible with snapshots. - -.Procedure - -. Create an AWS S3 bucket: -+ -[source,terminal] ----- -$ aws s3api create-bucket \ - --bucket <bucket_name> \ <1> - --region <bucket_region> <2> ----- -<1> Specify your S3 bucket name. -<2> Specify your S3 bucket region, for example, `us-east-1`. - -. Create the IAM user `velero`: -+ -[source,terminal] ----- -$ aws iam create-user --user-name velero ----- - -. Create an EC2 EBS snapshot policy: -+ -[source,terminal] ----- -$ cat > velero-ec2-snapshot-policy.json <<EOF -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "ec2:DescribeVolumes", - "ec2:DescribeSnapshots", - "ec2:CreateTags", - "ec2:CreateVolume", - "ec2:CreateSnapshot", - "ec2:DeleteSnapshot" - ], - "Resource": "*" - } - ] -} -EOF ----- - -. Create an AWS S3 access policy for one or for all S3 buckets: -+ -[source,terminal] ----- -$ cat > velero-s3-policy.json <<EOF -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:GetObject", - "s3:DeleteObject", - "s3:PutObject", - "s3:AbortMultipartUpload", - "s3:ListMultipartUploadParts" - ], - "Resource": [ - "arn:aws:s3:::<bucket_name>/*" <1> - ] - }, - { - "Effect": "Allow", - "Action": [ - "s3:ListBucket", - "s3:GetBucketLocation", - "s3:ListBucketMultipartUploads" - ], - "Resource": [ - "arn:aws:s3:::<bucket_name>" <1> - ] - } - ] -} -EOF ----- -<1> To grant access to a single S3 bucket, specify the bucket name. To grant access to all AWS S3 buckets, specify `*` instead of a bucket name as in the following example: -+ -.Example output -[source,terminal] ----- -"Resource": [ - "arn:aws:s3:::*" ----- - -. Attach the EC2 EBS policy to `velero`: -+ -[source,terminal] ----- -$ aws iam put-user-policy \ - --user-name velero \ - --policy-name velero-ebs \ - --policy-document file://velero-ec2-snapshot-policy.json ----- - -. Attach the AWS S3 policy to `velero`: -+ -[source,terminal] ----- -$ aws iam put-user-policy \ - --user-name velero \ - --policy-name velero-s3 \ - --policy-document file://velero-s3-policy.json ----- - -. Create an access key for `velero`: -+ -[source,terminal] ----- -$ aws iam create-access-key --user-name velero -{ - "AccessKey": { - "UserName": "velero", - "Status": "Active", - "CreateDate": "2017-07-31T22:24:41.576Z", - "SecretAccessKey": <AWS_SECRET_ACCESS_KEY>, <1> - "AccessKeyId": <AWS_ACCESS_KEY_ID> <1> - } -} ----- -<1> Record the `AWS_SECRET_ACCESS_KEY` and the `AWS_ACCESS_KEY_ID` for adding the AWS repository to the {mtc-short} web console. diff --git a/modules/migration-configuring-azure.adoc b/modules/migration-configuring-azure.adoc deleted file mode 100644 index 1db6e4ccc7f5..000000000000 --- a/modules/migration-configuring-azure.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/configuring-replication-repository-3-4.adoc -// * migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc -// * migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc - -[id='migration-configuring-azure_{context}'] -= Configuring a Microsoft Azure Blob storage container as a replication repository - -You can configure a Microsoft Azure Blob storage container as a replication repository for the {mtc-full} ({mtc-short}). - -.Prerequisites - -* You must have an link:https://docs.microsoft.com/en-us/azure/storage/common/storage-quickstart-create-account?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-portal[Azure storage account]. -* You must have the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest[Azure CLI] installed. -* The Azure Blob storage container must be accessible to the source and target clusters. -* If you are using the snapshot copy method: -** The source and target clusters must be in the same region. -** The source and target clusters must have the same storage class. -** The storage class must be compatible with snapshots. - -.Procedure - -. Set the `AZURE_RESOURCE_GROUP` variable: -+ -[source,terminal] ----- -$ AZURE_RESOURCE_GROUP=Velero_Backups ----- - -. Create an Azure resource group: -+ -[source,terminal] ----- -$ az group create -n $AZURE_RESOURCE_GROUP --location <CentralUS> <1> ----- -<1> Specify your location. - -. Set the `AZURE_STORAGE_ACCOUNT_ID` variable: -+ -[source,terminal] ----- -$ AZURE_STORAGE_ACCOUNT_ID=velerobackups ----- - -. Create an Azure storage account: -+ -[source,terminal] ----- -$ az storage account create \ - --name $AZURE_STORAGE_ACCOUNT_ID \ - --resource-group $AZURE_RESOURCE_GROUP \ - --sku Standard_GRS \ - --encryption-services blob \ - --https-only true \ - --kind BlobStorage \ - --access-tier Hot ----- - -. Set the `BLOB_CONTAINER` variable: -+ -[source,terminal] ----- -$ BLOB_CONTAINER=velero ----- - -. Create an Azure Blob storage container: -+ -[source,terminal] ----- -$ az storage container create \ - -n $BLOB_CONTAINER \ - --public-access off \ - --account-name $AZURE_STORAGE_ACCOUNT_ID ----- - -. Create a service principal and credentials for `velero`: -+ -[source,terminal] ----- -$ AZURE_SUBSCRIPTION_ID=`az account list --query '[?isDefault].id' -o tsv` \ - AZURE_TENANT_ID=`az account list --query '[?isDefault].tenantId' -o tsv` \ - AZURE_CLIENT_SECRET=`az ad sp create-for-rbac --name "velero" --role "Contributor" --query 'password' -o tsv` \ - AZURE_CLIENT_ID=`az ad sp list --display-name "velero" --query '[0].appId' -o tsv` ----- - -. Save the service principal credentials in the `credentials-velero` file: -+ -[source,terminal] ----- -$ cat << EOF > ./credentials-velero -AZURE_SUBSCRIPTION_ID=${AZURE_SUBSCRIPTION_ID} -AZURE_TENANT_ID=${AZURE_TENANT_ID} -AZURE_CLIENT_ID=${AZURE_CLIENT_ID} -AZURE_CLIENT_SECRET=${AZURE_CLIENT_SECRET} -AZURE_RESOURCE_GROUP=${AZURE_RESOURCE_GROUP} -AZURE_CLOUD_NAME=AzurePublicCloud -EOF ----- diff --git a/modules/migration-configuring-gcp.adoc b/modules/migration-configuring-gcp.adoc deleted file mode 100644 index 21dd5f0428db..000000000000 --- a/modules/migration-configuring-gcp.adoc +++ /dev/null @@ -1,127 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/configuring-replication-repository-3-4.adoc -// * migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc -// * migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc - -[id='migration-configuring-gcp_{context}'] -= Configuring a Google Cloud Provider storage bucket as a replication repository - -You can configure a Google Cloud Provider (GCP) storage bucket as a replication repository for the {mtc-full} ({mtc-short}). - -.Prerequisites - -* The GCP storage bucket must be accessible to the source and target clusters. -* You must have link:https://cloud.google.com/storage/docs/gsutil_install[`gsutil`] installed. -* If you are using the snapshot copy method: -** The source and target clusters must be in the same region. -** The source and target clusters must have the same storage class. -** The storage class must be compatible with snapshots. - -.Procedure - -. Log in to `gsutil`: -+ -[source,terminal] ----- -$ gsutil init ----- -+ -.Example output -[source,terminal] ----- -Welcome! This command will take you through the configuration of gcloud. - -Your current configuration has been set to: [default] - -To continue, you must login. Would you like to login (Y/n)? ----- - -. Set the `BUCKET` variable: -+ -[source,terminal] ----- -$ BUCKET=<bucket_name> <1> ----- -<1> Specify your bucket name. - -. Create a storage bucket: -+ -[source,terminal] ----- -$ gsutil mb gs://$BUCKET/ ----- - -. Set the `PROJECT_ID` variable to your active project: -+ -[source,terminal] ----- -$ PROJECT_ID=`gcloud config get-value project` ----- - -. Create a `velero` IAM service account: -+ -[source,terminal] ----- -$ gcloud iam service-accounts create velero \ - --display-name "Velero Storage" ----- - -. Create the `SERVICE_ACCOUNT_EMAIL` variable: -+ -[source,terminal] ----- -$ SERVICE_ACCOUNT_EMAIL=`gcloud iam service-accounts list \ - --filter="displayName:Velero Storage" \ - --format 'value(email)'` ----- - -. Create the `ROLE_PERMISSIONS` variable: -+ -[source,terminal] ----- -$ ROLE_PERMISSIONS=( - compute.disks.get - compute.disks.create - compute.disks.createSnapshot - compute.snapshots.get - compute.snapshots.create - compute.snapshots.useReadOnly - compute.snapshots.delete - compute.zones.get -) ----- - -. Create the `velero.server` custom role: -+ -[source,terminal] ----- -$ gcloud iam roles create velero.server \ - --project $PROJECT_ID \ - --title "Velero Server" \ - --permissions "$(IFS=","; echo "${ROLE_PERMISSIONS[*]}")" ----- - -. Add IAM policy binding to the project: -+ -[source,terminal] ----- -$ gcloud projects add-iam-policy-binding $PROJECT_ID \ - --member serviceAccount:$SERVICE_ACCOUNT_EMAIL \ - --role projects/$PROJECT_ID/roles/velero.server ----- - -. Update the IAM service account: -+ -[source,terminal] ----- -$ gsutil iam ch serviceAccount:$SERVICE_ACCOUNT_EMAIL:objectAdmin gs://${BUCKET} ----- - -. Save the IAM service account keys to the `credentials-velero` file in the current directory: -+ -[source,terminal] ----- -$ gcloud iam service-accounts keys create credentials-velero \ - --iam-account $SERVICE_ACCOUNT_EMAIL ----- diff --git a/modules/migration-configuring-mcg.adoc b/modules/migration-configuring-mcg.adoc deleted file mode 100644 index d3d89fdc3b8e..000000000000 --- a/modules/migration-configuring-mcg.adoc +++ /dev/null @@ -1,190 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/configuring-replication-repository-3-4.adoc -// * migration/migrating_4_1_4/configuring-replication-repository-4-1-4.adoc -// * migration/migrating_4_2_4/configuring-replication-repository-4-2-4.adoc - -[id='migration-configuring-mcg_{context}'] -= Configuring a Multi-Cloud Object Gateway storage bucket as a replication repository - -You can install the OpenShift Container Storage Operator and configure a Multi-Cloud Object Gateway (MCG) storage bucket as a replication repository for the {mtc-full} ({mtc-short}). - -[id='installing-the-ocs-operator_{context}'] -== Installing the OpenShift Container Storage Operator - -You can install the OpenShift Container Storage Operator from OperatorHub. - -ifdef::openshift-origin[] -.Prerequisites - -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in _Obtaining the installation program_ in the installation documentation for your platform. -+ -If you have the pull secret, add the `redhat-operators` catalog to the OperatorHub custom resource (CR) as shown in _Configuring {product-title} to use Red Hat Operators_. -endif::[] - -.Procedure - -. In the {product-title} web console, click *Operators* -> *OperatorHub*. -. Use *Filter by keyword* (in this case, *OCS*) to find the *OpenShift Container Storage Operator*. -. Select the *OpenShift Container Storage Operator* and click *Install*. -. Select an *Update Channel*, *Installation Mode*, and *Approval Strategy*. -. Click *Install*. -+ -On the *Installed Operators* page, the *OpenShift Container Storage Operator* appears in the *openshift-storage* project with the status *Succeeded*. - -[id='configuring-mcg-storage-bucket_{context}'] -== Creating the Multi-Cloud Object Gateway storage bucket - -You can create the Multi-Cloud Object Gateway (MCG) storage bucket's custom resources (CRs). - -.Procedure - -. Log in to the {product-title} cluster: -+ -[source,terminal] ----- -$ oc login ----- - -. Create the `NooBaa` CR configuration file, `noobaa.yml`, with the following content: -+ -[source,yaml] ----- -apiVersion: noobaa.io/v1alpha1 -kind: NooBaa -metadata: - name: noobaa - namespace: openshift-storage -spec: - dbResources: - requests: - cpu: 0.5 <1> - memory: 1Gi - coreResources: - requests: - cpu: 0.5 <1> - memory: 1Gi ----- -<1> For a very small cluster, you can change the `cpu` value to `0.1`. - -. Create the `NooBaa` object: -+ -[source,terminal] ----- -$ oc create -f noobaa.yml ----- - -. Create the `BackingStore` CR configuration file, `bs.yml`, with the following content: -+ -[source,yaml] ----- -apiVersion: noobaa.io/v1alpha1 -kind: BackingStore -metadata: - finalizers: - - noobaa.io/finalizer - labels: - app: noobaa - name: mcg-pv-pool-bs - namespace: openshift-storage -spec: - pvPool: - numVolumes: 3 <1> - resources: - requests: - storage: 50Gi <2> - storageClass: gp2 <3> - type: pv-pool ----- -<1> Specify the number of volumes in the persistent volume pool. -<2> Specify the size of the volumes. -<3> Specify the storage class. - -. Create the `BackingStore` object: -+ -[source,terminal] ----- -$ oc create -f bs.yml ----- - -. Create the `BucketClass` CR configuration file, `bc.yml`, with the following content: -+ -[source,yaml] ----- -apiVersion: noobaa.io/v1alpha1 -kind: BucketClass -metadata: - labels: - app: noobaa - name: mcg-pv-pool-bc - namespace: openshift-storage -spec: - placementPolicy: - tiers: - - backingStores: - - mcg-pv-pool-bs - placement: Spread ----- - -. Create the `BucketClass` object: -+ -[source,terminal] ----- -$ oc create -f bc.yml ----- - -. Create the `ObjectBucketClaim` CR configuration file, `obc.yml`, with the following content: -+ -[source,yaml] ----- -apiVersion: objectbucket.io/v1alpha1 -kind: ObjectBucketClaim -metadata: - name: migstorage - namespace: openshift-storage -spec: - bucketName: migstorage <1> - storageClassName: openshift-storage.noobaa.io - additionalConfig: - bucketclass: mcg-pv-pool-bc ----- -<1> Record the bucket name for adding the replication repository to the {mtc-short} web console. - -. Create the `ObjectBucketClaim` object: -+ -[source,terminal] ----- -$ oc create -f obc.yml ----- - -. Watch the resource creation process to verify that the `ObjectBucketClaim` status is `Bound`: -+ -[source,terminal] ----- -$ watch -n 30 'oc get -n openshift-storage objectbucketclaim migstorage -o yaml' ----- -+ -This process can take five to ten minutes. - -. Obtain and record the following values, which are required when you add the replication repository to the {mtc-short} web console: - -* S3 endpoint: -+ -[source,terminal] ----- -$ oc get route -n openshift-storage s3 ----- - -* S3 provider access key: -+ -[source,terminal] ----- -$ oc get secret -n openshift-storage migstorage -o go-template='{{ .data.AWS_ACCESS_KEY_ID }}' | base64 -d ----- - -* S3 provider secret access key: -+ -[source,terminal] ----- -$ oc get secret -n openshift-storage migstorage -o go-template='{{ .data.AWS_SECRET_ACCESS_KEY }}' | base64 -d ----- diff --git a/modules/migration-creating-ca-bundle.adoc b/modules/migration-creating-ca-bundle.adoc deleted file mode 100644 index 091e31a34a18..000000000000 --- a/modules/migration-creating-ca-bundle.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='creating-ca-bundle_{context}'] -= Creating a CA certificate bundle file - -If you use a self-signed certificate to secure a cluster or a replication repository for the {mtc-full} ({mtc-short}), certificate verification might fail with the following error message: `Certificate signed by unknown authority`. - -You can create a custom CA certificate bundle file and upload it in the {mtc-short} web console when you add a cluster or a replication repository. - -.Procedure - -Download a CA certificate from a remote endpoint and save it as a CA bundle file: - -[source,terminal] ----- -$ echo -n | openssl s_client -connect <host_FQDN>:<port> \ <1> - | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > <ca_bundle.cert> <2> ----- -<1> Specify the host FQDN and port of the endpoint, for example, `api.my-cluster.example.com:6443`. -<2> Specify the name of the CA bundle file. diff --git a/modules/migration-creating-migration-plan-cam.adoc b/modules/migration-creating-migration-plan-cam.adoc deleted file mode 100644 index 7de267aef707..000000000000 --- a/modules/migration-creating-migration-plan-cam.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='migration-creating-migration-plan-cam_{context}'] -= Creating a migration plan in the {mtc-short} web console - -You can create a migration plan in the {mtc-full} ({mtc-short}) web console. - -You can use _direct image migration_ and _direct volume migration_ to migrate images or volumes directly from the source cluster to the target cluster. Direct migration improves performance significantly. - -.Prerequisites - -* You must add source and target clusters and a replication repository to the {mtc-short} web console. -* Clusters: -** The clusters must have network access to each other. -** The clusters must have network access to the replication repository. -** The clusters must be able to communicate using OpenShift routes on port 443. -** The clusters must have no `Critical` conditions. -** The clusters must be in a `Ready` state. - -* The migration plan name must not exceed 253 lower-case alphanumeric characters (`a-z, 0-9`) and must not contain spaces or underscores (`_`). -* PV `Move` copy method: The clusters must have network access to the remote volume. -* PV `Snapshot` copy method: -** The clusters must have the same cloud provider (AWS, GCP, or Azure). -** The clusters must be located in the same geographic region. -** The storage class must be the same on the source and target clusters. - -* Direct image migration: -** The source cluster must have its internal registry exposed to external traffic. -** The exposed registry route of the source cluster must be added to the cluster configuration by using either the {mtc-short} web console or the `exposedRegistryPath` parameter in the `MigCluster` CR manifest. - -* Direct volume migration: -** The PVs to be migrated must be valid. -** The PVs must be in a `bound` state. -** The PVs must be copied by using the file system copy method. -** The source cluster must not have an HTTP proxy configured. - -.Procedure - -. In the {mtc-short} web console, click *Migration plans*. -. Click *Add migration plan*. -. Enter the *Plan name* and click *Next*. -. Select a *Source cluster*. -. Select a *Target cluster*. -. Select a *Replication repository*. -. Select the projects to be migrated and click *Next*. -. Select a *Source cluster*, a *Target cluster*, and a *Repository*, and click *Next*. -. On the *Namespaces* page, select the projects to be migrated and click *Next*. -. On the *Persistent volumes* page, click a *Migration type* for each PV: - -* The *Copy* option copies the data from the PV of a source cluster to the replication repository and then restores it on a newly created PV, with similar characteristics, in the target cluster. -* The *Move* option unmounts a remote volume, for example, NFS, from the source cluster, creates a PV resource on the target cluster pointing to the remote volume, and then mounts the remote volume on the target cluster. Applications running on the target cluster use the same remote volume that the source cluster was using. The remote volume must be accessible to the source and target clusters. - -. Click *Next*. -. On the *Copy options* page, select a *Copy method* for each PV: - -* *Snapshot copy* backs up and restores data using the cloud provider's snapshot functionality. It is significantly faster than *Filesystem copy*. -* *Filesystem copy* backs up the files on the source cluster and restores them on the target cluster. - -. You can select *Verify copy* to verify data migrated with *Filesystem copy*. Data is verified by generating a checksum for each source file and checking the checksum after restoration. Data verification significantly reduces performance. - -. Select a *Target storage class*. -+ -You can change the storage class of data migrated with *Filesystem copy*. -. Click *Next*. -. On the *Migration options* page, the *Direct image migration* option is selected if you specified an exposed image registry route for the source cluster. The *Direct PV migration* option is selected if you are migrating data with *Filesystem copy*. -+ -The direct migration options copy images and files directly from the source cluster to the target cluster. This option is much faster than copying images and files from the source cluster to the replication repository and then from the replication repository to the target cluster. -. Click *Next*. -. Optional: On the *Hooks* page, click *Add Hook* to add a hook to the migration plan. -+ -A hook runs custom code. You can add up to four hooks to a single migration plan. Each hook runs during a different migration step. - -.. Enter the name of the hook to display in the web console. -.. If the hook is an Ansible playbook, select *Ansible playbook* and click *Browse* to upload the playbook or paste the contents of the playbook in the field. -.. Optional: Specify an Ansible runtime image if you are not using the default hook image. -.. If the hook is not an Ansible playbook, select *Custom container image* and specify the image name and path. -+ -A custom container image can include Ansible playbooks. - -.. Select *Source cluster* or *Target cluster*. -.. Enter the *Service account name* and the *Service account namespace*. -.. Select the migration step for the hook: - -* *preBackup*: Before the application workload is backed up on the source cluster -* *postBackup*: After the application workload is backed up on the source cluster -* *preRestore*: Before the application workload is restored on the target cluster -* *postRestore*: After the application workload is restored on the target cluster - -.. Click *Add*. - -. Click *Finish*. -+ -The migration plan is displayed in the *Migration plans* list. diff --git a/modules/migration-debugging-velero-resources.adoc b/modules/migration-debugging-velero-resources.adoc deleted file mode 100644 index fdb8d0737c3d..000000000000 --- a/modules/migration-debugging-velero-resources.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id="migration-debugging-velero-resources_{context}"] -= Using the Velero CLI to debug Backup and Restore CRs - -You can debug the `Backup` and `Restore` custom resources (CRs) and partial migration failures with the Velero command line interface (CLI). The Velero CLI runs in the `velero` pod. - -[id="velero-command-syntax_{context}"] -== Velero command syntax - -Velero CLI commands use the following syntax: -[source,terminal] ----- -$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero <resource> <command> <resource_id> ----- - -You can specify `velero-<pod> -n openshift-migration` in place of `$(oc get pods -n openshift-migration -o name | grep velero)`. - -[id="help-command_{context}"] -== Help command - -The Velero `help` command lists all the Velero CLI commands: -[source,terminal] ----- -$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero --help ----- - -[id="describe-command_{context}"] -== Describe command - -The Velero `describe` command provides a summary of warnings and errors associated with a Velero resource: -[source,terminal] ----- -$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero <resource> describe <resource_id> ----- - -.Example -[source,terminal] ----- -$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero backup describe 0e44ae00-5dc3-11eb-9ca8-df7e5254778b-2d8ql ----- - -[id="logs-command_{context}"] -== Logs command - -The Velero `logs` command provides the logs associated with a Velero resource: -[source,terminal] ----- -velero <resource> logs <resource_id> ----- - -.Example -[source,terminal] ----- -$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -- ./velero restore logs ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf ----- diff --git a/modules/migration-downloading-logs.adoc b/modules/migration-downloading-logs.adoc deleted file mode 100644 index 2ae67eaeacbc..000000000000 --- a/modules/migration-downloading-logs.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id='migration-downloading-logs_{context}'] -= Downloading migration logs - -You can download the `Velero`, `Restic`, and `MigrationController` pod logs in the {mtc-full} ({mtc-short}) web console to troubleshoot a failed migration. - -.Procedure - -. In the {mtc-short} console, click *Migration plans* to view the list of migration plans. -. Click the *Options* menu {kebab} of a specific migration plan and select *Logs*. -. Click *Download Logs* to download the logs of the `MigrationController`, `Velero`, and `Restic` pods for all clusters. -+ -You can download a single log by selecting the cluster, log source, and pod source, and then clicking *Download Selected*. -+ -You can access a pod log from the CLI by using the `oc logs` command: -+ -[source,terminal] ----- -$ oc logs <pod-name> -f -n openshift-migration <1> ----- -<1> Specify the pod name. diff --git a/modules/migration-dvm-error-node-selectors.adoc b/modules/migration-dvm-error-node-selectors.adoc deleted file mode 100644 index 21a2e04532d4..000000000000 --- a/modules/migration-dvm-error-node-selectors.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id="migration-dvm-error-node-selectors_{context}"] -= Direct volume migration does not complete - -If direct volume migration does not complete, the target cluster might not have the same `node-selector` annotations as the source cluster. - -{mtc-full} ({mtc-short}) migrates namespaces with all annotations to preserve security context constraints and scheduling requirements. During direct volume migration, {mtc-short} creates Rsync transfer pods on the target cluster in the namespaces that were migrated from the source cluster. If a target cluster namespace does not have the same annotations as the source cluster namespace, the Rsync transfer pods cannot be scheduled. The Rsync pods remain in a `Pending` state. - -You can identify and fix this issue by performing the following procedure. - -.Procedure - -. Check the status of the `MigMigration` CR: -+ -[source,terminal] ----- -$ oc describe migmigration <pod_name> -n openshift-migration ----- -+ -The output includes the following status message: -+ -.Example output -[source,terminal] ----- -... -Some or all transfer pods are not running for more than 10 mins on destination cluster -... ----- - -. On the source cluster, obtain the details of a migrated namespace: -+ -[source,terminal] ----- -$ oc get namespace <namespace> -o yaml <1> ----- -<1> Specify the migrated namespace. - -. On the target cluster, edit the migrated namespace: -+ -[source,terminal] ----- -$ oc edit namespace <namespace> ----- - -. Add missing `openshift.io/node-selector` annotations to the migrated namespace as in the following example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - annotations: - openshift.io/node-selector: "region=east" -... ----- - -. Run the migration plan again. diff --git a/modules/migration-error-messages.adoc b/modules/migration-error-messages.adoc deleted file mode 100644 index 8613b7ee9493..000000000000 --- a/modules/migration-error-messages.adoc +++ /dev/null @@ -1,180 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id='migration-error-messages_{context}'] -= Error messages and resolutions - -This section describes common error messages you might encounter with the {mtc-full} ({mtc-short}) and how to resolve their underlying causes. - -[id='ca-certificate-error-in-console_{context}'] -== CA certificate error in the {mtc-short} console - -If a `CA certificate error` message is displayed the first time you try to access the {mtc-short} console, the likely cause is the use of self-signed CA certificates in one of the clusters. - -To resolve this issue, navigate to the `oauth-authorization-server` URL displayed in the error message and accept the certificate. To resolve this issue permanently, add the certificate to the trust store of your web browser. - -If an `Unauthorized` message is displayed after you have accepted the certificate, navigate to the {mtc-short} console and refresh the web page. - -[id='oauth-timeout-error-in-console_{context}'] -== OAuth timeout error in the {mtc-short} console - -If a `connection has timed out` message is displayed in the {mtc-short} console after you have accepted a self-signed certificate, the causes are likely to be the following: - -* Interrupted network access to the OAuth server -* Interrupted network access to the {product-title} console -* Proxy configuration that blocks access to the `oauth-authorization-server` URL. See link:https://access.redhat.com/solutions/5514491[MTC console inaccessible because of OAuth timeout error] for details. - -You can determine the cause of the timeout. - -.Procedure - -. Navigate to the {mtc-short} console and inspect the elements with the browser web inspector. -. Check the `MigrationUI` pod log: -+ -[source,terminal] ----- -$ oc logs <MigrationUI_Pod> -n openshift-migration ----- - -[id='podvolumebackups-timeout-error-in-velero-log_{context}'] -== `PodVolumeBackups` timeout error in `Velero` pod log - -If a migration fails because Restic times out, the following error is displayed in the `Velero` pod log. - -.Example output -[source,terminal] ----- -level=error msg="Error backing up item" backup=velero/monitoring error="timed out waiting for all PodVolumeBackups to complete" error.file="/go/src/github.com/heptio/velero/pkg/restic/backupper.go:165" error.function="github.com/heptio/velero/pkg/restic.(*backupper).BackupPodVolumes" group=v1 ----- - -The default value of `restic_timeout` is one hour. You can increase this parameter for large migrations, keeping in mind that a higher value may delay the return of error messages. - -.Procedure - -. In the {product-title} web console, navigate to *Operators* -> *Installed Operators*. -. Click *{mtc-full} Operator*. -. In the *MigrationController* tab, click *migration-controller*. -. In the *YAML* tab, update the following parameter value: -+ -[source,yaml] ----- -spec: - restic_timeout: 1h <1> ----- -<1> Valid units are `h` (hours), `m` (minutes), and `s` (seconds), for example, `3h30m15s`. - -. Click *Save*. - -[id='resticverifyerrors-in-the-migmigration-custom-resource_{context}'] -== `ResticVerifyErrors` in the `MigMigration` custom resource - -If data verification fails when migrating a persistent volume with the file system data copy method, the following error is displayed in the `MigMigration` CR. - -.Example output -[source,yaml] ----- -status: - conditions: - - category: Warn - durable: true - lastTransitionTime: 2020-04-16T20:35:16Z - message: There were verify errors found in 1 Restic volume restores. See restore `<registry-example-migration-rvwcm>` - for details <1> - status: "True" - type: ResticVerifyErrors <2> ----- -<1> The error message identifies the `Restore` CR name. -<2> `ResticVerifyErrors` is a general error warning type that includes verification errors. - -[NOTE] -==== -A data verification error does not cause the migration process to fail. -==== - -You can check the `Restore` CR to identify the source of the data verification error. - -.Procedure - -. Log in to the target cluster. -. View the `Restore` CR: -+ -[source,terminal] ----- -$ oc describe <registry-example-migration-rvwcm> -n openshift-migration ----- -+ -The output identifies the persistent volume with `PodVolumeRestore` errors. -+ -.Example output -[source,yaml] ----- -status: - phase: Completed - podVolumeRestoreErrors: - - kind: PodVolumeRestore - name: <registry-example-migration-rvwcm-98t49> - namespace: openshift-migration - podVolumeRestoreResticErrors: - - kind: PodVolumeRestore - name: <registry-example-migration-rvwcm-98t49> - namespace: openshift-migration ----- - -. View the `PodVolumeRestore` CR: -+ -[source,terminal] ----- -$ oc describe <migration-example-rvwcm-98t49> ----- -+ -The output identifies the `Restic` pod that logged the errors. -+ -.Example output -[source,yaml] ----- - completionTimestamp: 2020-05-01T20:49:12Z - errors: 1 - resticErrors: 1 - ... - resticPod: <restic-nr2v5> ----- - -. View the `Restic` pod log to locate the errors: -+ -[source,terminal] ----- -$ oc logs -f <restic-nr2v5> ----- - -ifeval::["{mtc-version}" < "1.3"] -[id='restic-permission-denied-error-for-nfs-storage_{context}'] -== `restic: permission denied` error for NFS storage - -If you are migrating data from NFS storage and `root_squash` is enabled, `Restic` maps to `nfsnobody` and does not have permission to perform the migration. The following error is displayed in the `Restic` pod log. - -.Example output -[source,terminal] ----- -backup=openshift-migration/<backup_id> controller=pod-volume-backup error="fork/exec /usr/bin/restic: permission denied" error.file="/go/src/github.com/vmware-tanzu/velero/pkg/controller/pod_volume_backup_controller.go:280" error.function="github.com/vmware-tanzu/velero/pkg/controller.(*podVolumeBackupController).processBackup" logSource="pkg/controller/pod_volume_backup_controller.go:280" name=<backup_id> namespace=openshift-migration ----- - -You can resolve this issue by creating a supplemental group for Restic and adding the group ID to the `MigrationController` CR manifest. - -.Procedure - -. Create a supplemental group for Restic on the NFS storage. -. Set the `setgid` bit on the NFS directories so that group ownership is inherited. -. Add the `restic_supplemental_groups` parameter to the `MigrationController` CR manifest on the source and target clusters: -+ -[source,yaml] ----- -spec: - restic_supplemental_groups: <group_id> <1> ----- -<1> Specify the supplemental group ID. - -. Wait for the `Restic` pods to restart so that the changes are applied. -endif::[] diff --git a/modules/migration-excluding-resources.adoc b/modules/migration-excluding-resources.adoc deleted file mode 100644 index ab51eac438bf..000000000000 --- a/modules/migration-excluding-resources.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='migration-excluding-resources_{context}'] -= Excluding resources from a migration plan - -You can exclude resources, for example, image streams, persistent volumes (PVs), or subscriptions, from a {mtc-full} ({mtc-short}) migration plan to reduce the resource load for migration or to migrate images or PVs with a different tool. - -By default, the {mtc-short} excludes service catalog resources and Operator Lifecycle Manager (OLM) resources from migration. These resources are parts of the service catalog API group and the OLM API group, neither of which is supported for migration at this time. - -.Procedure - -. Edit the `MigrationController` CR manifest: -+ -[source,terminal] ----- -$ oc edit migrationcontroller -n openshift-migration ----- - -. Update the `spec` section by adding a parameter to exclude specific resources or by adding a resource to the `excluded_resources` parameter if it does not have its own exclusion parameter: -+ -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigrationController -metadata: - name: migration-controller - namespace: openshift-migration -spec: - disable_image_migration: true <1> - disable_pv_migration: true <2> - ... - excluded_resources: <3> - - imagetags - - templateinstances - - clusterserviceversions - - packagemanifests - - subscriptions - - servicebrokers - - servicebindings - - serviceclasses - - serviceinstances - - serviceplans - - operatorgroups - - events ----- -<1> Add `disable_image_migration: true` to exclude image streams from the migration. Do not edit the `excluded_resources` parameter. `imagestreams` is added to `excluded_resources` when the `MigrationController` pod restarts. -<2> Add `disable_pv_migration: true` to exclude PVs from the migration plan. Do not edit the `excluded_resources` parameter. `persistentvolumes` and `persistentvolumeclaims` are added to `excluded_resources` when the `MigrationController` pod restarts. Disabling PV migration also disables PV discovery when you create the migration plan. -<3> You can add {product-title} resources to the `excluded_resources` list. Do not delete the default excluded resources. These resources are problematic to migrate and must be excluded. - -. Wait two minutes for the `MigrationController` pod to restart so that the changes are applied. - -. Verify that the resource is excluded: -+ -[source,terminal] ----- -$ oc get deployment -n openshift-migration migration-controller -o yaml | grep EXCLUDED_RESOURCES -A1 ----- -+ -The output contains the excluded resources: -+ -.Example output -[source,yaml] ----- - - name: EXCLUDED_RESOURCES - value: - imagetags,templateinstances,clusterserviceversions,packagemanifests,subscriptions,servicebrokers,servicebindings,serviceclasses,serviceinstances,serviceplans,imagestreams,persistentvolumes,persistentvolumeclaims ----- diff --git a/modules/migration-installing-cam-operator-ocp-3.adoc b/modules/migration-installing-cam-operator-ocp-3.adoc deleted file mode 100644 index cc82b03e5693..000000000000 --- a/modules/migration-installing-cam-operator-ocp-3.adoc +++ /dev/null @@ -1,151 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/deploying-cam-3-4.adoc - -[id="migration-installing-cam-operator-ocp-3_{context}"] -ifdef::migrating-3-4[] -= Installing the {mtc-full} on an {product-title} 3 source cluster - -You can install the {mtc-full} ({mtc-short}) manually on an {product-title} 3 source cluster. -endif::[] -ifdef::disconnected-3-4[] -= Installing the {mtc-full} on an {product-title} 3 source cluster in a restricted environment - -You can create a manifest file based on the {mtc-full} ({mtc-short}) Operator image and edit the manifest to point to your local image registry. Then, you can use the local image to create the {mtc-full} Operator on an {product-title} 3 source cluster. -endif::[] - -[IMPORTANT] -==== -You must install the same {mtc-short} version on the {product-title} 3 and 4 clusters. The {mtc-full} Operator on the {product-title} 4 cluster is updated automatically by Operator Lifecycle Manager. - -To ensure that you have the latest version on the {product-title} 3 cluster, download the `operator.yml` and `controller-3.yml` files when you are ready to create and run the migration plan. -==== - -.Prerequisites - -* Access to `registry.redhat.io` -* Podman installed -ifdef::migrating-3-4[] -* {product-title} 3 cluster configured to pull images from `registry.redhat.io` -+ -To pull images, you must link:https://access.redhat.com/solutions/3772061[create an image stream secret] and copy it to each node in your cluster. -endif::[] -ifdef::disconnected-3-4[] -* Linux workstation with unrestricted network access -* Mirror registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] -* Custom Operator catalog pushed to a mirror registry -endif::[] - -.Procedure - -ifdef::migrating-3-4[] -. Log in to `registry.redhat.io` with your Red Hat Customer Portal credentials: -endif::[] -ifdef::disconnected-3-4[] -. On the workstation with unrestricted network access, log in to `registry.redhat.io` with your Red Hat Customer Portal credentials: -endif::[] -+ -[source,terminal] ----- -$ sudo podman login registry.redhat.io ----- - -. Download the `operator.yml` file: -+ -[source,terminal,subs="attributes+"] ----- -$ sudo podman cp $(sudo podman create registry.redhat.io/rhmtc/openshift-migration-rhel7-operator:v{mtc-version-z}):/operator.yml ./ ----- - -. Download the `controller-3.yml` file: -+ -[source,terminal,subs="attributes+"] ----- -$ sudo podman cp $(sudo podman create registry.redhat.io/rhmtc/openshift-migration-rhel7-operator:v{mtc-version-z}):/controller-3.yml ./ ----- - -ifdef::disconnected-3-4[] -. Obtain the Operator image value from the `mapping.txt` file that was created when you ran the `oc adm catalog mirror` on the {product-title} 4 cluster: -+ -[source,terminal,subs="attributes+"] ----- -$ grep openshift-migration-rhel7-operator ./mapping.txt | grep rhmtc ----- -+ -The output shows the mapping between the `registry.redhat.io` image and your mirror registry image. -+ -.Example output -[source,terminal] ----- -registry.redhat.io/rhmtc/openshift-migration-rhel7-operator@sha256:468a6126f73b1ee12085ca53a312d1f96ef5a2ca03442bcb63724af5e2614e8a=<registry.apps.example.com>/rhmtc/openshift-migration-rhel7-operator ----- - -. Update the `image` and `REGISTRY` values in the `operator.yml` file: -+ -[source,yaml] ----- -containers: - - name: ansible - image: <registry.apps.example.com>/rhmtc/openshift-migration-rhel7-operator@sha256:<468a6126f73b1ee12085ca53a312d1f96ef5a2ca03442bcb63724af5e2614e8a> <1> -... - - name: operator - image: <registry.apps.example.com>/rhmtc/openshift-migration-rhel7-operator@sha256:<468a6126f73b1ee12085ca53a312d1f96ef5a2ca03442bcb63724af5e2614e8a> <2> -... - env: - - name: REGISTRY - value: <registry.apps.example.com> <3> ----- -<1> Specify your mirror registry and the `sha256` value of the Operator image in the `mapping.txt` file. -<2> Specify your mirror registry and the `sha256` value of the Operator image in the `mapping.txt` file. -<3> Specify your mirror registry. -endif::[] - -. Log in to your {product-title} 3 cluster. - -ifdef::migrating-3-4[] -. Verify that the cluster can authenticate with `registry.redhat.io`: -+ -[source,terminal] ----- -$ oc run test --image registry.redhat.io/ubi8 --command sleep infinity ----- -endif::[] - -. Create the {mtc-full} Operator object: -+ -[source,terminal] ----- -$ oc create -f operator.yml ----- -+ -.Example output -[source,terminal] ----- -namespace/openshift-migration created -rolebinding.rbac.authorization.k8s.io/system:deployers created -serviceaccount/migration-operator created -customresourcedefinition.apiextensions.k8s.io/migrationcontrollers.migration.openshift.io created -role.rbac.authorization.k8s.io/migration-operator created -rolebinding.rbac.authorization.k8s.io/migration-operator created -clusterrolebinding.rbac.authorization.k8s.io/migration-operator created -deployment.apps/migration-operator created -Error from server (AlreadyExists): error when creating "./operator.yml": -rolebindings.rbac.authorization.k8s.io "system:image-builders" already exists <1> -Error from server (AlreadyExists): error when creating "./operator.yml": -rolebindings.rbac.authorization.k8s.io "system:image-pullers" already exists ----- -<1> You can ignore `Error from server (AlreadyExists)` messages. They are caused by the {mtc-full} Operator creating resources for earlier versions of {product-title} 3 that are provided in later releases. - -. Create the `MigrationController` object: -+ -[source,terminal] ----- -$ oc create -f controller-3.yml ----- - -. Verify that the `Velero` and `Restic` pods are running: -+ -[source,terminal] ----- -$ oc get pods -n openshift-migration ----- diff --git a/modules/migration-installing-cam-operator-ocp-4.adoc b/modules/migration-installing-cam-operator-ocp-4.adoc deleted file mode 100644 index 29fe7dec5d63..000000000000 --- a/modules/migration-installing-cam-operator-ocp-4.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/deploying-cam-3-4.adoc -// * migration/migrating_4_1_4/deploying-cam-4-1-4.adoc -// * migration/migrating_4_2_4/deploying-cam-4-2-4.adoc - -[id="migration-installing-cam-operator-ocp-4_{context}"] -ifdef::source-4-1-4[] -= Installing the {mtc-full} on an {product-title} 4.1 source cluster -endif::[] -ifdef::source-4-2-4[] -= Installing the {mtc-full} on an {product-title} 4.2 source cluster -endif::[] -ifdef::disconnected-source-4-1-4[] -= Installing the {mtc-full} on an {product-title} 4.1 source cluster in a restricted environment -endif::[] -ifdef::disconnected-source-4-2-4[] -= Installing the {mtc-full} on an {product-title} 4.2 source cluster in a restricted environment -endif::[] -ifdef::migrating-3-4,target-4-1-4,target-4-2-4[] -= Installing the {mtc-full} on an {product-title} {product-version} target cluster -endif::[] -ifdef::disconnected-3-4,disconnected-target-4-1-4,disconnected-target-4-2-4[] -= Installing the {mtc-full} on an {product-title} {product-version} target cluster in a restricted environment -endif::[] - -ifdef::source-4-1-4,source-4-2-4,disconnected-source-4-1-4,disconnected-source-4-2-4[] -You can install the {mtc-full} ({mtc-short}) on an {product-title} 4 source cluster by using Operator Lifecycle Manager (OLM) to install the {mtc-full} Operator. -endif::[] - -ifdef::migrating-3-4,target-4-1-4,target-4-2-4,disconnected-3-4,disconnected-target-4-1-4,disconnected-target-4-2-4[] -You can install the {mtc-full} ({mtc-short}) on an {product-title} {product-version} target cluster by using Operator Lifecycle Manager (OLM) to install the {mtc-full} Operator. - -{mtc-short} is installed on the target cluster by default. -endif::[] - -ifdef::disconnected-3-4,disconnected-target-4-1-4,disconnected-target-4-2-4,disconnected-source-4-1-4,disconnected-source-4-2-4[] -.Prerequisites - -* You have created a custom Operator catalog and pushed it to a mirror registry. -* You have configured OLM to install the {mtc-full} Operator from the mirror registry. -endif::[] - -.Procedure - -ifdef::disconnected-3-4,disconnected-target-4-1-4,disconnected-source-4-2-4,disconnected-target-4-2-4,migrating-3-4,target-4-2-4,source-4-2-4,target-4-1-4[] -. In the {product-title} web console, click *Operators* -> *OperatorHub*. -endif::[] -ifdef::source-4-1-4[] -. In the {product-title} web console, click *Catalog* -> *OperatorHub*. -endif::[] -. Use the *Filter by keyword* field to find the *{mtc-full} Operator*. -. Select the *{mtc-full} Operator* and click *Install*. -ifdef::migrating-3-4[] -+ -[NOTE] -==== -Do not change the subscription approval option to *Automatic*. The {mtc-full} Operator version must be the same on the source and the target clusters. -==== -endif::[] - -ifdef::target-4-2-4,source-4-2-4,target-4-1-4[] -. In the *Subscription* tab, change the *Approval* option to *Automatic*. -endif::[] -. Click *Install*. -+ -On the *Installed Operators* page, the *{mtc-full} Operator* appears in the *openshift-migration* project with the status *Succeeded*. - -. Click *{mtc-full} Operator*. -. Under *Provided APIs*, locate the *Migration Controller* tile, and click *Create Instance*. - -ifdef::source-4-1-4[] -. Update the `migration_controller` and `migration_ui` parameters and add the `deprecated_cors_configuration` parameter to the manifest: -+ -[source,yaml] ----- -spec: -... - migration_controller: false - migration_ui: false -... - deprecated_cors_configuration: true ----- -endif::[] -ifdef::source-4-2-4[] -. Update the `migration_controller` and `migration_ui` parameters in the manifest: -+ -[source,yaml] ----- -spec: -... - migration_controller: false - migration_ui: false ----- -endif::[] - -. Click *Create*. -. Click *Workloads* -> *Pods* to verify that the {mtc-short} pods are running. diff --git a/modules/migration-installing-cpma.adoc b/modules/migration-installing-cpma.adoc deleted file mode 100644 index 3c8abf10d5f2..000000000000 --- a/modules/migration-installing-cpma.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/migrating-application-workloads-3-to-4.adoc - -[id='migration-installing-cpma_{context}'] -= Installing the Control Plane Migration Assistant - -The Control Plane Migration Assistant (CPMA) is a CLI-based tool that assists you in migrating the control plane from {product-title} 3.7 (or later) to {product-version} with the {mtc-full} ({mtc-short}). - -You can download the CPMA binary file from the Red Hat Customer Portal and install it on Linux, macOS, or Windows operating systems. - -.Procedure - -. In the link:https://access.redhat.com[Red Hat Customer Portal], navigate to *Downloads* -> *Red Hat {product-title}*. -. On the *Download Red Hat {product-title}* page, select *Red Hat {product-title}* from the *Product Variant* list. -. Select *CPMA 1.0 for RHEL 7* from the *Version* list. This binary works on RHEL 7 and RHEL 8. -. Click *Download Now* to download `cpma` for Linux and macOS or `cpma.exe` for Windows. -. Save the file in a directory defined as `$PATH` for Linux and macOS or `%PATH%` for Windows. -. For Linux, make the file executable: -+ -[source,terminal] ----- -$ sudo chmod +x cpma ----- diff --git a/modules/migration-known-issues.adoc b/modules/migration-known-issues.adoc deleted file mode 100644 index 7bc796c73abd..000000000000 --- a/modules/migration-known-issues.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id='migration-known-issues_{context}'] -= Known issues - -This release has the following known issues: - -* During migration, the {mtc-full} ({mtc-short}) preserves the following namespace annotations: - -** `openshift.io/sa.scc.mcs` -** `openshift.io/sa.scc.supplemental-groups` -** `openshift.io/sa.scc.uid-range` -+ -These annotations preserve the UID range, ensuring that the containers retain their file system permissions on the target cluster. There is a risk that the migrated UIDs could duplicate UIDs within an existing or future namespace on the target cluster. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1748440[*BZ#1748440*]) - -* If an AWS bucket is added to the {mtc-short} web console and then deleted, its status remains `True` because the `MigStorage` CR is not updated. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1738564[*BZ#1738564*]) - -* Most cluster-scoped resources are not yet handled by {mtc-short}. If your applications require cluster-scoped resources, you might have to create them manually on the target cluster. - -* If a migration fails, the migration plan does not retain custom PV settings for quiesced pods. You must manually roll back the migration, delete the migration plan, and create a new migration plan with your PV settings. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1784899[*BZ#1784899*]) - -* If a large migration fails because Restic times out, you can increase the `restic_timeout` parameter value (default: `1h`) in the `MigrationController` CR. - -* If you select the data verification option for PVs that are migrated with the file system copy method, performance is significantly slower. - -ifeval::["{mtc-version}" < "1.4"] -* If you are migrating data from NFS storage and `root_squash` is enabled, `Restic` maps to `nfsnobody`. The migration fails and a permission error is displayed in the `Restic` pod log. You can resolve this issue by creating a supplemental group for Restic. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1873641[*BZ#1873641*]) - -* If Velero has an invalid `BackupStorageLocation` during start-up, it will crash-loop until the invalid `BackupStorageLocation` is removed. This scenario is triggered by incorrect credentials, a non-existent S3 bucket, and other configuration errors. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1881707[*BZ#1881707*]) -endif::[] diff --git a/modules/migration-launching-cam.adoc b/modules/migration-launching-cam.adoc deleted file mode 100644 index 76ea3c6db471..000000000000 --- a/modules/migration-launching-cam.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id="migration-launching-cam_{context}"] -= Launching the {mtc-short} web console - -You can launch the {mtc-full} ({mtc-short}) web console in a browser. - -.Procedure - -. Log in to the {product-title} cluster on which you have installed {mtc-short}. -. Obtain the {mtc-short} web console URL by entering the following command: -+ -[source,terminal] ----- -$ oc get -n openshift-migration route/migration -o go-template='https://{{ .spec.host }}' ----- -+ -The output resembles the following: `\https://migration-openshift-migration.apps.cluster.openshift.com`. - -. Launch a browser and navigate to the {mtc-short} web console. -+ -[NOTE] -==== -If you try to access the {mtc-short} web console immediately after installing the {mtc-full} Operator, the console might not load because the Operator is still configuring the cluster. Wait a few minutes and retry. -==== - -. If you are using self-signed CA certificates, you will be prompted to accept the CA certificate of the source cluster API server. The web page guides you through the process of accepting the remaining certificates. - -. Log in with your {product-title} *username* and *password*. diff --git a/modules/migration-migrating-applications-api.adoc b/modules/migration-migrating-applications-api.adoc deleted file mode 100644 index 73cd9a9d821e..000000000000 --- a/modules/migration-migrating-applications-api.adoc +++ /dev/null @@ -1,368 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='migration-migrating-applications-api_{context}'] -= Migrating your applications with the {mtc-full} API - -You can migrate your applications on the command line with the {mtc-full} ({mtc-short}) API. - -You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters. - -This procedure describes how to perform indirect migration and direct migration: - -* Indirect migration: Images, volumes, and Kubernetes objects are copied from the source cluster to the replication repository and then from the replication repository to the destination cluster. -* Direct migration: Images or volumes are copied directly from the source cluster to the destination cluster. Direct image migration and direct volume migration have significant performance benefits. - -You create the following custom resources (CRs) to perform a migration: - -* `MigCluster` CR: Defines a `host`, local, or remote cluster -+ -The `migration-controller` pod runs on the `host` cluster. - -* `Secret` CR: Contains credentials for a remote cluster or storage -* `MigStorage` CR: Defines a replication repository -+ -Different storage providers require different parameters in the `MigStorage` CR manifest. - -* `MigPlan` CR: Defines a migration plan -* `MigMigration` CR: Performs a migration defined in an associated `MigPlan` -+ -You can create multiple `MigMigration` CRs for a single `MigPlan` CR for the following purposes: -+ -* To perform stage migrations, which copy most of the data without stopping the application, before running a migration. Stage migrations improve the performance of the migration. -* To cancel a migration in progress -* To roll back a completed migration - -.Prerequisites - -* You must have `cluster-admin` privileges for all clusters. -* You must install the {product-title} CLI (`oc`). -* You must install the {mtc-full} Operator on all clusters. -* The _version_ of the installed {mtc-full} Operator must be the same on all clusters. -* You must configure an object storage as a replication repository. -* If you are using direct image migration, you must expose a secure registry route on all remote clusters. -* If you are using direct volume migration, the source cluster must not have an HTTP proxy configured. - -.Procedure - -. Create a `MigCluster` CR manifest for the `host` cluster called `host-cluster.yaml`: -+ -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigCluster -metadata: - name: host - namespace: openshift-migration -spec: - isHostCluster: true ----- - -. Create a `MigCluster` CR for the `host` cluster: -+ -[source,terminal] ----- -$ oc create -f host-cluster.yaml -n openshift-migration ----- - -. Create a `Secret` CR manifest for each remote cluster called `cluster-secret.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: <cluster_secret> - namespace: openshift-config -type: Opaque -data: - saToken: <sa_token> <1> ----- -<1> Specify the base64-encoded `migration-controller` service account (SA) token of the remote cluster. -+ -You can obtain the SA token by running the following command: -+ -[source,terminal] ----- -$ oc sa get-token migration-controller -n openshift-migration | base64 -w 0 ----- - -. Create a `Secret` CR for each remote cluster: -+ -[source,terminal] ----- -$ oc create -f cluster-secret.yaml ----- - -. Create a `MigCluster` CR manifest for each remote cluster called `remote-cluster.yaml`: -+ -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigCluster -metadata: - name: <remote_cluster> - namespace: openshift-migration -spec: - exposedRegistryPath: <exposed_registry_route> <1> - insecure: false <2> - isHostCluster: false - serviceAccountSecretRef: - name: <remote_cluster_secret> <3> - namespace: openshift-config - url: <remote_cluster_url> <4> ----- -<1> Optional: Specify the exposed registry route, for example, `docker-registry-default.apps.example.com` if you are using direct image migration. -<2> SSL verification is enabled if `false`. CA certificates are not required or checked if `true`. -<3> Specify the `Secret` CR of the remote cluster. -<4> Specify the URL of the remote cluster. - -. Create a `MigCluster` CR for each remote cluster: -+ -[source,terminal] ----- -$ oc create -f remote-cluster.yaml -n openshift-migration ----- - -. Verify that all clusters are in a `Ready` state: -+ -[source,terminal] ----- -$ oc describe cluster <cluster_name> ----- - -. Create a `Secret` CR manifest for the replication repository called `storage-secret.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - namespace: openshift-config - name: <migstorage_creds> -type: Opaque -data: - aws-access-key-id: <key_id_base64> <1> - aws-secret-access-key: <secret_key_base64> <2> ----- -<1> Specify the key ID in base64 format. -<2> Specify the secret key in base64 format. -+ -AWS credentials are base64-encoded by default. If you are using another storage provider, you must encode your credentials by running the following command with each key: -+ -[source,terminal] ----- -$ echo -n "<key>" | base64 -w 0 <1> ----- -<1> Specify the key ID or the secret key. Both keys must be base64-encoded. - -. Create the `Secret` CR for the replication repository: -+ -[source,terminal] ----- -$ oc create -f storage-secret.yaml ----- - -. Create a `MigStorage` CR manifest for the replication repository called `migstorage.yaml`: -+ -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigStorage -metadata: - name: <storage_name> - namespace: openshift-migration -spec: - backupStorageConfig: - awsBucketName: <bucket_name> <1> - credsSecretRef: - name: <storage_secret_ref> <2> - namespace: openshift-config - backupStorageProvider: <storage_provider_name> <3> - volumeSnapshotConfig: - credsSecretRef: - name: <storage_secret_ref> <4> - namespace: openshift-config - volumeSnapshotProvider: <storage_provider_name> <5> ----- -<1> Specify the bucket name. -<2> Specify the `Secrets` CR of the object storage. You must ensure that the credentials stored in the `Secrets` CR of the object storage are correct. -<3> Specify the storage provider. -<4> Optional: If you are copying data by using snapshots, specify the `Secrets` CR of the object storage. You must ensure that the credentials stored in the `Secrets` CR of the object storage are correct. -<5> Optional: If you are copying data by using snapshots, specify the storage provider. - -. Create the `MigStorage` CR: -+ -[source,terminal] ----- -$ oc create -f migstorage.yaml -n openshift-migration ----- - -. Verify that the `MigStorage` CR is in a `Ready` state: -+ -[source,terminal] ----- -$ oc describe migstorage <migstorage_name> ----- - -. Create a `MigPlan` CR manifest called `migplan.yaml`: -+ -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigPlan -metadata: - name: <migration_plan> - namespace: openshift-migration -spec: - destMigClusterRef: - name: host - namespace: openshift-migration - indirectImageMigration: true <1> - indirectVolumeMigration: true <2> - migStorageRef: - name: <migstorage_ref> <3> - namespace: openshift-migration - namespaces: - - <application_namespace> <4> - srcMigClusterRef: - name: <remote_cluster_ref> <5> - namespace: openshift-migration ----- -<1> Direct image migration is enabled if `false`. -<2> Direct volume migration is enabled if `false`. -<3> Specify the name of the `MigStorage` CR instance. -<4> Specify one or more namespaces to be migrated. -<5> Specify the name of the source cluster `MigCluster` instance. - -. Create the `MigPlan` CR: -+ -[source,terminal] ----- -$ oc create -f migplan.yaml -n openshift-migration ----- - -. View the `MigPlan` instance to verify that it is in a `Ready` state: -+ -[source,terminal] ----- -$ oc describe migplan <migplan_name> -n openshift-migration ----- - -. Create a `MigMigration` CR manifest called `migmigration.yaml`: -+ -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigMigration -metadata: - name: <migmigration_name> - namespace: openshift-migration -spec: - migPlanRef: - name: <migplan_name> <1> - namespace: openshift-migration - quiescePods: true <2> - stage: false <3> - rollback: false <4> ----- -<1> Specify the `MigPlan` CR name. -<2> The pods on the source cluster are stopped before migration if `true`. -<3> A stage migration, which copies most of the data without stopping the application, is performed if `true`. -<4> A completed migration is rolled back if `true`. - -. Create the `MigMigration` CR to start the migration defined in the `MigPlan` CR: -+ -[source,terminal] ----- -$ oc create -f migmigration.yaml -n openshift-migration ----- - -. Verify the progress of the migration by watching the `MigMigration` CR: -+ -[source,terminal] ----- -$ oc watch migmigration <migmigration_name> -n openshift-migration ----- -+ -The output resembles the following: -+ -.Example output -+ -[source,yaml] ----- -Name: c8b034c0-6567-11eb-9a4f-0bc004db0fbc -Namespace: openshift-migration -Labels: migration.openshift.io/migplan-name=django -Annotations: openshift.io/touch: e99f9083-6567-11eb-8420-0a580a81020c -API Version: migration.openshift.io/v1alpha1 -Kind: MigMigration -... -Spec: - Mig Plan Ref: - Name: my_application - Namespace: openshift-migration - Stage: false -Status: - Conditions: - Category: Advisory - Last Transition Time: 2021-02-02T15:04:09Z - Message: Step: 19/47 - Reason: InitialBackupCreated - Status: True - Type: Running - Category: Required - Last Transition Time: 2021-02-02T15:03:19Z - Message: The migration is ready. - Status: True - Type: Ready - Category: Required - Durable: true - Last Transition Time: 2021-02-02T15:04:05Z - Message: The migration registries are healthy. - Status: True - Type: RegistriesHealthy - Itinerary: Final - Observed Digest: 7fae9d21f15979c71ddc7dd075cb97061895caac5b936d92fae967019ab616d5 - Phase: InitialBackupCreated - Pipeline: - Completed: 2021-02-02T15:04:07Z - Message: Completed - Name: Prepare - Started: 2021-02-02T15:03:18Z - Message: Waiting for initial Velero backup to complete. - Name: Backup - Phase: InitialBackupCreated - Progress: - Backup openshift-migration/c8b034c0-6567-11eb-9a4f-0bc004db0fbc-wpc44: 0 out of estimated total of 0 objects backed up (5s) - Started: 2021-02-02T15:04:07Z - Message: Not started - Name: StageBackup - Message: Not started - Name: StageRestore - Message: Not started - Name: DirectImage - Message: Not started - Name: DirectVolume - Message: Not started - Name: Restore - Message: Not started - Name: Cleanup - Start Timestamp: 2021-02-02T15:03:18Z -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Running 57s migmigration_controller Step: 2/47 - Normal Running 57s migmigration_controller Step: 3/47 - Normal Running 57s (x3 over 57s) migmigration_controller Step: 4/47 - Normal Running 54s migmigration_controller Step: 5/47 - Normal Running 54s migmigration_controller Step: 6/47 - Normal Running 52s (x2 over 53s) migmigration_controller Step: 7/47 - Normal Running 51s (x2 over 51s) migmigration_controller Step: 8/47 - Normal Ready 50s (x12 over 57s) migmigration_controller The migration is ready. - Normal Running 50s migmigration_controller Step: 9/47 - Normal Running 50s migmigration_controller Step: 10/47 ----- diff --git a/modules/migration-mtc-cr-manifests.adoc b/modules/migration-mtc-cr-manifests.adoc deleted file mode 100644 index 6fd7d69c1c67..000000000000 --- a/modules/migration-mtc-cr-manifests.adoc +++ /dev/null @@ -1,365 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id="migration-mtc-cr-manifests_{context}"] -= {mtc-short} custom resource manifests - -{mtc-full} ({mtc-short}) uses the following custom resource (CR) manifests to create CRs for migrating applications. - -[id="directimagemigration_{context}"] -== DirectImageMigration - -The `DirectImageMigration` CR copies images directly from the source cluster to the destination cluster. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: DirectImageMigration -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: <directimagemigration_name> -spec: - srcMigClusterRef: - name: <source_cluster_ref> <1> - namespace: openshift-migration - destMigClusterRef: - name: <destination_cluster_ref> <2> - namespace: openshift-migration - namespaces: - - <namespace> <3> ----- -<1> Specify the `MigCluster` CR name of the source cluster. -<2> Specify the `MigCluster` CR name of the destination cluster. -<3> Specify one or more namespaces containing images to be migrated. - -[id="directimagestreammigration_{context}"] -== DirectImageStreamMigration - -The `DirectImageStreamMigration` CR copies image stream references directly from the source cluster to the destination cluster. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: DirectImageStreamMigration -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: directimagestreammigration_name -spec: - srcMigClusterRef: - name: <source_cluster_ref> <1> - namespace: openshift-migration - destMigClusterRef: - name: <destination_cluster_ref> <2> - namespace: openshift-migration - imageStreamRef: - name: <image_stream_name> <3> - namespace: <source_image_stream_namespace> <4> - destNamespace: <destination_image_stream_namespace> <5> ----- -<1> Specify the `MigCluster` CR name of the source cluster. -<2> Specify the `MigCluster` CR name of the destination cluster. -<3> Specify the image stream name. -<4> Specify the image stream namespace on the source cluster. -<5> Specify the image stream namespace on the destination cluster. - -[id="directvolumemigration_{context}"] -== DirectVolumeMigration - -The `DirectVolumeMigration` CR copies persistent volumes (PVs) directly from the source cluster to the destination cluster. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: DirectVolumeMigration -metadata: - name: <directvolumemigration_name> - namespace: openshift-migration -spec: - createDestinationNamespaces: false <1> - deleteProgressReportingCRs: false <2> - destMigClusterRef: - name: host <3> - namespace: openshift-migration - persistentVolumeClaims: - - name: <pvc_name> <4> - namespace: <pvc_namespace> <5> - srcMigClusterRef: - name: <source_cluster_ref> <6> - namespace: openshift-migration ----- -<1> Namespaces are created for the PVs on the destination cluster if `true`. -<2> The `DirectVolumeMigrationProgress` CRs are deleted after migration if `true`. The default value is `false` so that `DirectVolumeMigrationProgress` CRs are retained for troubleshooting. -<3> Update the cluster name if the destination cluster is not the host cluster. -<4> Specify one or more PVCs to be migrated with direct volume migration. -<5> Specify the namespace of each PVC. -<6> Specify the `MigCluster` CR name of the source cluster. - -[id="directvolumemigrationprogress_{context}"] -== DirectVolumeMigrationProgress - -The `DirectVolumeMigrationProgress` CR shows the progress of the `DirectVolumeMigration` CR. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: DirectVolumeMigrationProgress -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: directvolumemigrationprogress_name -spec: - clusterRef: - name: source_cluster - namespace: openshift-migration - podRef: - name: rsync_pod - namespace: openshift-migration ----- - -[id="miganalytic_{context}"] -== MigAnalytic - -The `MigAnalytic` CR collects the number of images, Kubernetes resources, and the PV capacity from an associated `MigPlan` CR. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigAnalytic -metadata: - annotations: - migplan: <migplan_name> <1> - name: miganalytic_name - namespace: openshift-migration - labels: - migplan: <migplan_name> <2> -spec: - analyzeImageCount: true <3> - analyzeK8SResources: true <4> - analyzePVCapacity: true <5> - listImages: false <6> - listImagesLimit: 50 <7> - migPlanRef: - name: migplan_name <8> - namespace: openshift-migration ----- -<1> Specify the `MigPlan` CR name associated with the `MigAnalytic` CR. -<2> Specify the `MigPlan` CR name associated with the `MigAnalytic` CR. -<3> Optional: The number of images is returned if `true`. -<4> Optional: Returns the number, kind, and API version of the Kubernetes resources if `true`. -<5> Optional: Returns the PV capacity if `true`. -<6> Returns a list of image names if `true`. Default is `false` so that the output is not excessively long. -<7> Optional: Specify the maximum number of image names to return if `listImages` is `true`. -<8> Specify the `MigPlan` CR name associated with the `MigAnalytic` CR. - -[id="migcluster_{context}"] -== MigCluster - -The `MigCluster` CR defines a host, local, or remote cluster. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigCluster -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: host <1> - namespace: openshift-migration -spec: - isHostCluster: true <2> - azureResourceGroup: <azure_resource_group> <3> - caBundle: <ca_bundle_base64> <4> - insecure: false <5> - refresh: false <6> -# The 'restartRestic' parameter is relevant for a source cluster. -# restartRestic: true <7> -# The following parameters are relevant for a remote cluster. -# isHostCluster: false -# exposedRegistryPath: <8> -# url: <destination_cluster_url> <9> -# serviceAccountSecretRef: -# name: <source_secret_ref> <10> -# namespace: openshift-config ----- -<1> Optional: Update the cluster name if the `migration-controller` pod is not running on this cluster. -<2> The `migration-controller` pod runs on this cluster if `true`. -<3> Optional: If the storage provider is Microsoft Azure, specify the resource group. -<4> Optional: If you created a certificate bundle for self-signed CA certificates and if the `insecure` parameter value is `false`, specify the base64-encoded certificate bundle. -<5> SSL verification is enabled if `false`. -<6> The cluster is validated if `true`. -<7> The `restic` pods are restarted on the source cluster after the `stage` pods are created if `true`. -<8> Optional: If you are using direct image migration, specify the exposed registry path of a remote cluster. -<9> Specify the URL of the remote cluster. -<10> Specify the name of the `Secret` CR for the remote cluster. - -[id="mighook_{context}"] -== MigHook - -The `MigHook` CR defines an Ansible playbook or a custom image that runs tasks at a specified stage of the migration. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigHook -metadata: - generateName: <hook_name_prefix> <1> - name: <hook_name> <2> - namespace: openshift-migration -spec: - activeDeadlineSeconds: <3> - custom: false <4> - image: <hook_image> <5> - playbook: <ansible_playbook_base64> <6> - targetCluster: source <7> ----- -<1> Optional: A unique hash is appended to the value for this parameter so that each migration hook has a unique name. You do not need to specify the value of the `name` parameter. -<2> Specify the migration hook name, unless you specify the value of the `generateName` parameter. -<3> Optional: Specify the maximum number of seconds that a hook can run. The default value is `1800`. -<4> The hook is a custom image if `true`. The custom image can include Ansible or it can be written in a different programming language. -<5> Specify the custom image, for example, `quay.io/konveyor/hook-runner:latest`. Required if `custom` is `true`. -<6> Specify the entire base64-encoded Ansible playbook. Required if `custom` is `false`. -<7> Specify `source` or `destination` as the cluster on which the hook will run. - -[id="migmigration_{context}"] -== MigMigration - -The `MigMigration` CR runs an associated `MigPlan` CR. - -You can create multiple `MigMigration` CRs associated with the same `MigPlan` CR for the following scenarios: - -* You can run multiple _stage_ or incremental migrations to copy data without stopping the pods on the source cluster. Running stage migrations improves the performance of the actual migration. -* You can cancel a migration in progress. -* You can roll back a migration. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigMigration -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: migmigration_name - namespace: openshift-migration -spec: - canceled: false <1> - rollback: false <2> - stage: false <3> - quiescePods: true <4> - keepAnnotations: true <5> - verify: false <6> - migPlanRef: - name: <migplan_ref> <7> - namespace: openshift-migration ----- -<1> A migration in progress is canceled if `true`. -<2> A completed migration is rolled back if `true`. -<3> Data is copied incrementally and the pods on the source cluster are not stopped if `true`. -<4> The pods on the source cluster are scaled to `0` after the `Backup` stage of a migration if `true`. -<5> The labels and annotations applied during the migration are retained if `true`. -<6> The status of the migrated pods on the destination cluster are checked and the names of pods that are not in a `Running` state are returned if `true`. -<7> `migPlanRef.name`: Specify the name of the associated `MigPlan` CR. - -[id="migplan_{context}"] -== MigPlan - -The `MigPlan` CR defines the parameters of a migration plan. It contains a group of virtual machines that are being migrated with the same parameters. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigPlan -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: migplan_name - namespace: openshift-migration -spec: - closed: false <1> - srcMigClusterRef: - name: <source_migcluster_ref> <2> - namespace: openshift-migration - destMigClusterRef: - name: <destination_migcluster_ref> <3> - namespace: openshift-migration - hooks: <4> - - executionNamespace: <namespace> <5> - phase: <migration_phase> <6> - reference: - name: <mighook_name> <7> - namespace: <hook_namespace> <8> - serviceAccount: <service_account> <9> - indirectImageMigration: true <10> - indirectVolumeMigration: false <11> - migStorageRef: - name: <migstorage_name> <12> - namespace: openshift-migration - namespaces: - - <namespace> <13> - refresh: false <14> ----- -<1> The migration has completed if `true`. You cannot create another `MigMigration` CR for this `MigPlan` CR. -<2> Specify the name of the source cluster `MigCluster` CR. -<3> Specify the name of the destination cluster `MigCluster` CR. -<4> Optional: You can specify up to four migration hooks. -<5> Optional: Specify the namespace in which the hook will run. -<6> Optional: Specify the migration phase during which a hook runs. One hook can be assigned to one phase. The expected values are `PreBackup`, `PostBackup`, `PreRestore`, and `PostRestore`. -<7> Optional: Specify the name of the `MigHook` CR. -<8> Optional: Specify the namespace of `MigHook` CR. -<9> Optional: Specify a service account with `cluster-admin` privileges. -<10> Direct image migration is disabled if `true`. Images are copied from the source cluster to the replication repository and from the replication repository to the destination cluster. -<11> Direct volume migration is disabled if `true`. PVs are copied from the source cluster to the replication repository and from the replication repository to the destination cluster. -<12> Specify the name of `MigStorage` CR. -<13> Specify one or more namespaces. -<14> The `MigPlan` CR is validated if `true`. - -[id="migstorage_{context}"] -== MigStorage - -The `MigStorage` CR describes the object storage for the replication repository. You can configure Amazon Web Services, Microsoft Azure, Google Cloud Storage, and generic S3-compatible cloud storage, for example, Minio or NooBaa. - -Different providers require different parameters. - -[source,yaml] ----- -apiVersion: migration.openshift.io/v1alpha1 -kind: MigStorage -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: migstorage_name - namespace: openshift-migration -spec: - backupStorageProvider: <storage_provider> <1> - volumeSnapshotProvider: <2> - backupStorageConfig: - awsBucketName: <3> - awsRegion: <4> - credsSecretRef: - namespace: openshift-config - name: <storage_secret> <5> - awsKmsKeyId: <6> - awsPublicUrl: <7> - awsSignatureVersion: <8> - volumeSnapshotConfig: - awsRegion: <9> - credsSecretRef: - namespace: openshift-config - name: <10> - refresh: false <11> ----- -<1> Specify the storage provider. -<2> Optional: If you are using the snapshot copy method, specify the storage provider. -<3> If you are using AWS, specify the bucket name. -<4> If you are using AWS, specify the bucket region, for example, `us-east-1`. -<5> Specify the name of the `Secret` CR that you created for the `MigStorage` CR. -<6> Optional: If you are using the AWS Key Management Service, specify the unique identifier of the key. -<7> Optional: If you granted public access to the AWS bucket, specify the bucket URL. -<8> Optional: Specify the AWS signature version for authenticating requests to the bucket, for example, `4`. -<9> Optional: If you are using the snapshot copy method, specify the geographical region of the clusters. -<10> Optional: If you are using the snapshot copy method, specify the name of the `Secret` CR that you created for the `MigStorage` CR. -<11> The cluster is validated if `true`. diff --git a/modules/migration-mtc-custom-resources.adoc b/modules/migration-mtc-custom-resources.adoc deleted file mode 100644 index 085108f5dd93..000000000000 --- a/modules/migration-mtc-custom-resources.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// -// * migration/migrating_3_4/migrating-application-workloads-3-4.adoc -// * migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc - -[id='migration-mtc-custom-resources_{context}'] -= {mtc-full} custom resources - -The {mtc-full} ({mtc-short}) creates the following custom resources (CRs): - -image::migration-architecture.png[migration architecture diagram] - -image:darkcircle-1.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migcluster_types.go[MigCluster] (configuration, {mtc-short} cluster): Cluster definition - -image:darkcircle-2.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migstorage_types.go[MigStorage] (configuration, {mtc-short} cluster): Storage definition - -image:darkcircle-3.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migplan_types.go[MigPlan] (configuration, {mtc-short} cluster): Migration plan - -The `MigPlan` CR describes the source and target clusters, replication repository, and namespaces being migrated. It is associated with 0, 1, or many `MigMigration` CRs. - -[NOTE] -==== -Deleting a `MigPlan` CR deletes the associated `MigMigration` CRs. -==== - -image:darkcircle-4.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/backupstoragelocation_types.go[BackupStorageLocation] (configuration, {mtc-short} cluster): Location of `Velero` backup objects - -image:darkcircle-5.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/volume_snapshot_location.go[VolumeSnapshotLocation] (configuration, {mtc-short} cluster): Location of `Velero` volume snapshots - -image:darkcircle-6.png[20,20] link:https://github.com/konveyor/mig-controller/blob/master/pkg/apis/migration/v1alpha1/migmigration_types.go[MigMigration] (action, {mtc-short} cluster): Migration, created every time you stage or migrate data. Each `MigMigration` CR is associated with a `MigPlan` CR. - -image:darkcircle-7.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/backup.go[Backup] (action, source cluster): When you run a migration plan, the `MigMigration` CR creates two `Velero` backup CRs on each source cluster: - -* Backup CR #1 for Kubernetes objects -* Backup CR #2 for PV data - -image:darkcircle-8.png[20,20] link:https://github.com/vmware-tanzu/velero/blob/main/pkg/apis/velero/v1/restore.go[Restore] (action, target cluster): When you run a migration plan, the `MigMigration` CR creates two `Velero` restore CRs on the target cluster: - -* Restore CR #1 (using Backup CR #2) for PV data -* Restore CR #2 (using Backup CR #1) for Kubernetes objects diff --git a/modules/migration-mtc-workflow.adoc b/modules/migration-mtc-workflow.adoc deleted file mode 100644 index 2c92f58ab262..000000000000 --- a/modules/migration-mtc-workflow.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-application-workloads-3-4.adoc -// * migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc - -[id='migration-mtc-workflow_{context}'] -= {mtc-full} workflow - -You use the {mtc-full} ({mtc-short}) to migrate Kubernetes resources, persistent volume data, and internal container images from an {product-title} source cluster to an {product-title} {product-version} target cluster by using the {mtc-short} web console or the Kubernetes API. - -The ({mtc-short}) migrates the following resources: - -* A namespace specified in a migration plan. - -* Namespace-scoped resources: When the {mtc-short} migrates a namespace, it migrates all the objects and resources associated with that namespace, such as services or pods. Additionally, if a resource that exists in the namespace but not at the cluster level depends on a resource that exists at the cluster level, the {mtc-short} migrates both resources. -+ -For example, a security context constraint (SCC) is a resource that exists at the cluster level and a service account (SA) is a resource that exists at the namespace level. If an SA exists in a namespace that the {mtc-short} migrates, the {mtc-short} automatically locates any SCCs that are linked to the SA and also migrates those SCCs. Similarly, the {mtc-short} migrates persistent volume claims that are linked to the persistent volumes of the namespace. - -* Custom resources (CRs) and custom resource definitions (CRDs): The {mtc-short} automatically migrates any CRs that exist at the namespace level as well as the CRDs that are linked to those CRs. - -Migrating an application with the {mtc-short} web console involves the following steps: - -. Install the {mtc-full} Operator on all clusters. -+ -You can install the {mtc-full} Operator in a restricted environment with limited or no internet access. The source and target clusters must have network access to each other and to a mirror registry. - -. Configure the replication repository, an intermediate object storage that {mtc-short} uses to migrate data. -+ -The source and target clusters must have network access to the replication repository during migration. In a restricted environment, you can use an internally hosted S3 storage repository. If you are using a proxy server, you must configure it to allow network traffic between the replication repository and the clusters. - -. Add the source cluster to the {mtc-short} web console. -. Add the replication repository to the {mtc-short} web console. -. Create a migration plan, with one of the following data migration options: - -* *Copy*: {mtc-short} copies the data from the source cluster to the replication repository, and from the replication repository to the target cluster. -+ -[NOTE] -==== -If you are using direct image migration or direct volume migration, the images or volumes are copied directly from the source cluster to the target cluster. -==== -+ -image::migration-PV-copy.png[] - -* *Move*: {mtc-short} unmounts a remote volume, for example, NFS, from the source cluster, creates a PV resource on the target cluster pointing to the remote volume, and then mounts the remote volume on the target cluster. Applications running on the target cluster use the same remote volume that the source cluster was using. The remote volume must be accessible to the source and target clusters. -+ -[NOTE] -==== -Although the replication repository does not appear in this diagram, it is required for migration. -==== -+ -image::migration-PV-move.png[] - -. Run the migration plan, with one of the following options: - -* *Stage* (optional) copies data to the target cluster without stopping the application. -+ -Staging can be run multiple times so that most of the data is copied to the target before migration. This minimizes the duration of the migration and application downtime. - -* *Migrate* stops the application on the source cluster and recreates its resources on the target cluster. Optionally, you can migrate the workload without stopping the application. - -image::OCP_3_to_4_App_migration.png[] diff --git a/modules/migration-partial-failure-velero.adoc b/modules/migration-partial-failure-velero.adoc deleted file mode 100644 index ed0374b7ba91..000000000000 --- a/modules/migration-partial-failure-velero.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id="migration-partial-failure-velero_{context}"] -= Debugging a partial migration failure - -You can debug a partial migration failure warning message by using the Velero CLI to examine the `Restore` custom resource (CR) logs. - -A partial failure occurs when Velero encounters an issue that does not cause a migration to fail. For example, if a custom resource definition (CRD) is missing or if there is a discrepancy between CRD versions on the source and target clusters, the migration completes but the CR is not created on the target cluster. - -Velero logs the issue as a partial failure and then processes the rest of the objects in the `Backup` CR. - -.Procedure - -. Check the status of a `MigMigration` CR: -+ -[source,terminal] ----- -$ oc get migmigration <migmigration> -o yaml ----- -+ -.Example output -+ -[source,yaml] ----- -status: - conditions: - - category: Warn - durable: true - lastTransitionTime: "2021-01-26T20:48:40Z" - message: 'Final Restore openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf: partially failed on destination cluster' - status: "True" - type: VeleroFinalRestorePartiallyFailed - - category: Advisory - durable: true - lastTransitionTime: "2021-01-26T20:48:42Z" - message: The migration has completed with warnings, please look at `Warn` conditions. - reason: Completed - status: "True" - type: SucceededWithWarnings ----- - -. Check the status of the `Restore` CR by using the Velero `describe` command: -+ -[source,yaml] ----- -$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -n openshift-migration -- ./velero restore describe <restore> ----- -+ -.Example output -+ -[source,yaml] ----- -Phase: PartiallyFailed (run 'velero restore logs ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf' for more information) - -Errors: - Velero: <none> - Cluster: <none> - Namespaces: - migration-example: error restoring example.com/migration-example/migration-example: the server could not find the requested resource ----- - -. Check the `Restore` CR logs by using the Velero `logs` command: -+ -[source,yaml] ----- -$ oc exec $(oc get pods -n openshift-migration -o name | grep velero) -n openshift-migration -- ./velero restore logs <restore> ----- -+ -.Example output -+ -[source,yaml] ----- -time="2021-01-26T20:48:37Z" level=info msg="Attempting to restore migration-example: migration-example" logSource="pkg/restore/restore.go:1107" restore=openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf -time="2021-01-26T20:48:37Z" level=info msg="error restoring migration-example: the server could not find the requested resource" logSource="pkg/restore/restore.go:1170" restore=openshift-migration/ccc7c2d0-6017-11eb-afab-85d0007f5a19-x4lbf ----- -+ -The `Restore` CR log error message, `the server could not find the requested resource`, indicates the cause of the partially failed migration. diff --git a/modules/migration-prerequisites.adoc b/modules/migration-prerequisites.adoc deleted file mode 100644 index 5db4df33e5ac..000000000000 --- a/modules/migration-prerequisites.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='migration-prerequisites_{context}'] -= Prerequisites - -The {mtc-full} ({mtc-short}) has the following prerequisites: - -ifdef::migrating-3-4[] -* You must have `podman` installed. -* The source cluster must be {product-title} 3.7, 3.9, 3.10, or 3.11. -endif::[] -* You must upgrade the source cluster to the latest z-stream release. -* You must have `cluster-admin` privileges on all clusters. -* The source and target clusters must have unrestricted network access to the replication repository. -* The cluster on which the `MigrationController` CR is installed must have unrestricted network access to the other clusters. -* If your application uses images from the `openshift` namespace, the required versions of the images must be present on the target cluster. You can manually update an image stream tag in order to use a deprecated {product-title} 3 image on an {product-title} {product-version} cluster. diff --git a/modules/migration-rolling-back-migration-cli.adoc b/modules/migration-rolling-back-migration-cli.adoc deleted file mode 100644 index 397fbef73166..000000000000 --- a/modules/migration-rolling-back-migration-cli.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id='migration-rolling-back-migration-cli_{context}'] -== Rolling back a migration from the CLI - -You can roll back a migration by creating a `MigMigration` custom resource (CR) from the CLI. - -If your application was stopped during a failed migration, you must roll back the migration to prevent data corruption in the persistent volume. - -Rollback is not required if the application was not stopped during migration because the original application is still running on the source cluster. - -.Procedure - -. Create a `MigMigration` CR based on the following example: -+ -[source,yaml] ----- -$ cat << EOF | oc apply -f - -apiVersion: migration.openshift.io/v1alpha1 -kind: MigMigration -metadata: - labels: - controller-tools.k8s.io: "1.0" - name: migration-rollback - namespace: openshift-migration -spec: -... - rollback: true -... - migPlanRef: - name: <migplan_name> <1> - namespace: openshift-migration -EOF ----- -<1> Specify the name of the associated `MigPlan` CR. - -. In the {mtc-short} web console, verify that the migrated project resources have been removed from the target cluster. -. Verify that the migrated project resources are present in the source cluster and that the application is running. diff --git a/modules/migration-rolling-back-migration-web-console.adoc b/modules/migration-rolling-back-migration-web-console.adoc deleted file mode 100644 index c5e1ae9d8ea6..000000000000 --- a/modules/migration-rolling-back-migration-web-console.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id='migration-rolling-back-migration-web-console_{context}'] -= Rolling back a migration in the {mtc-short} web console - -You can roll back a migration by using the {mtc-full} ({mtc-short}) web console. - -If your application was stopped during a failed migration, you must roll back the migration to prevent data corruption in the persistent volume. - -Rollback is not required if the application was not stopped during migration because the original application is still running on the source cluster. - -.Procedure - -. In the {mtc-short} web console, click *Migration plans*. -. Click the Options menu {kebab} beside a migration plan and select *Rollback*. -. Click *Rollback* and wait for rollback to complete. -+ -In the migration plan details, *Rollback succeeded* is displayed. - -. Verify that rollback was successful in the {product-title} web console of the source cluster: - -.. Click *Home* -> *Projects*. -.. Click the migrated project to view its status. -.. In the *Routes* section, click *Location* to verify that the application is functioning, if applicable. -.. Click *Workloads* -> *Pods* to verify that the pods are running in the migrated namespace. -.. Click *Storage* -> *Persistent volumes* to verify that the migrated persistent volume is correctly provisioned. diff --git a/modules/migration-running-migration-plan-cam.adoc b/modules/migration-running-migration-plan-cam.adoc deleted file mode 100644 index 6254a9b89765..000000000000 --- a/modules/migration-running-migration-plan-cam.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id='migration-running-migration-plan-cam_{context}'] -= Running a migration plan in the {mtc-short} web console - -You can stage or migrate applications and data with the migration plan you created in the {mtc-full} ({mtc-short}) web console. - -[NOTE] -==== -{mtc-short} sets the reclaim policy of migrated persistent volumes (PVs) to `Retain` on the target cluster. - -The `Backup` custom resource contains a `PVOriginalReclaimPolicy` annotation that indicates the original reclaim policy. You can manually restore the reclaim policy of the migrated PVs. -==== - -.Prerequisites - -The {mtc-short} web console must contain the following: - -* Source cluster in a `Ready` state -* Target cluster in a `Ready` state -* Replication repository -* Valid migration plan - -.Procedure - -. Log in to the source cluster. -. Delete old images: -+ -[source,terminal] ----- -$ oc adm prune images ----- - -. Log in to the {mtc-short} web console and click *Migration plans*. -. Click the *Options* menu {kebab} next to a migration plan and select *Stage* to copy data from the source cluster to the target cluster without stopping the application. -+ -You can run *Stage* multiple times to reduce the actual migration time. - -. When you are ready to migrate the application workload, the *Options* menu {kebab} beside a migration plan and select *Migrate*. - -. Optional: In the *Migrate* window, you can select *Do not stop applications on the source cluster during migration*. -. Click *Migrate*. -. When the migration is complete, verify that the application migrated successfully in the {product-title} web console: - -.. Click *Home* -> *Projects*. -.. Click the migrated project to view its status. -.. In the *Routes* section, click *Location* to verify that the application is functioning, if applicable. -.. Click *Workloads* -> *Pods* to verify that the pods are running in the migrated namespace. -.. Click *Storage* -> *Persistent volumes* to verify that the migrated persistent volumes are correctly provisioned. diff --git a/modules/migration-understanding-cpma.adoc b/modules/migration-understanding-cpma.adoc deleted file mode 100644 index 7de14384772e..000000000000 --- a/modules/migration-understanding-cpma.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/migrating-application-workloads-3-4.adoc - -[id='migration-understanding-cpma_{context}'] -= About the Control Plane Migration Assistant - -The Control Plane Migration Assistant (CPMA) is a CLI-based tool that assists you in migrating the control plane from {product-title} 3.7 (or later) to {product-version} with the {mtc-full} ({mtc-short}). CPMA processes the {product-title} 3 configuration files and generates custom resource (CR) manifest files, which are consumed by {product-title} {product-version} Operators. - -Because {product-title} 3 and 4 have significant configuration differences, not all parameters are processed. CPMA can generate a report that describes whether features are supported fully, partially, or not at all. - -.Configuration files - -CPMA uses the Kubernetes and {product-title} APIs to access the following configuration files on an {product-title} 3 cluster: - -* Master configuration file (default: `/etc/origin/master/master-config.yaml`) -* CRI-O configuration file (default: `/etc/crio/crio.conf`) -* etcd configuration file (default: `/etc/etcd/etcd.conf`) -* Image registries file (default: `/etc/containers/registries.conf`) -* Dependent configuration files: -** Password files (for example, HTPasswd) -** Config maps -** Secrets - -.Manifests - -CPMA generates manifests for the following configurations: - -* API server CA certificate: `100_CPMA-cluster-config-APISecret.yaml` -+ -[NOTE] -==== -If you are using an unsigned API server CA certificate, you must add the certificate manually to the target cluster. -==== - -* CRI-O: `100_CPMA-crio-config.yaml` -* Cluster resource quota: `100_CPMA-cluster-quota-resource-x.yaml` -* Project resource quota: `100_CPMA-resource-quota-x.yaml` -* Portable image registry (`/etc/registries/registries.conf`) and portable image policy (`etc/origin/master/master-config.yam`): `100_CPMA-cluster-config-image.yaml` -* OAuth providers: `100_CPMA-cluster-config-oauth.yaml` -* Project configuration: `100_CPMA-cluster-config-project.yaml` -* Scheduler: `100_CPMA-cluster-config-scheduler.yaml` -* SDN: `100_CPMA-cluster-config-sdn.yaml` diff --git a/modules/migration-understanding-data-copy-methods.adoc b/modules/migration-understanding-data-copy-methods.adoc deleted file mode 100644 index 54dff65e91f2..000000000000 --- a/modules/migration-understanding-data-copy-methods.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-application-workloads-3-4.adoc -// * migration/migrating_4_1_4/migrating-application-workloads-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-application-workloads-4-2-4.adoc - -[id='migration-understanding-data-copy-methods_{context}'] -= About data copy methods - -The {mtc-full} ({mtc-short}) supports the file system and snapshot data copy methods for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider. - -[id='file-system-copy-method_{context}'] -== File system copy method - -{mtc-short} copies data files from the source cluster to the replication repository, and from there to the target cluster. - -[cols="1,1", options="header"] -.File system copy method summary -|=== -|Benefits |Limitations -a|* Clusters can have different storage classes. -* Supported for all S3 storage providers. -* Optional data verification with checksum. -* Supports direct volume migration, which significantly increases performance. -a|* Slower than the snapshot copy method. -* Optional data verification significantly reduces performance. -|=== - -[id='snapshot-copy-method_{context}'] -== Snapshot copy method - -{mtc-short} copies a snapshot of the source cluster data to the replication repository of a cloud provider. The data is restored on the target cluster. - -AWS, Google Cloud Provider, and Microsoft Azure support the snapshot copy method. - -[cols="1,1", options="header"] -.Snapshot copy method summary -|=== -|Benefits |Limitations -a|* Faster than the file system copy method. -a|* Cloud provider must support snapshots. -* Clusters must be on the same cloud provider. -* Clusters must be in the same location or region. -* Clusters must have the same storage class. -* Storage class must be compatible with snapshots. -* Does not support direct volume migration. -|=== - -[id="direct-migration_{context}"] -== Direct volume migration and direct image migration - -You can use _direct image migration_ and _direct volume migration_ to migrate images and data directly from the source cluster to the target cluster. - -Direct migration has significant performance benefits because it skips the intermediate steps of backing up files from the source cluster to the replication repository and restoring files from the replication repository to the target cluster. - -Direct migration uses link:https://rsync.samba.org/[Rsync] to transfer the files. - -[NOTE] -==== -Direct image migration and direct volume migration have additional prerequisites. -==== diff --git a/modules/migration-updating-deprecated-gvks.adoc b/modules/migration-updating-deprecated-gvks.adoc deleted file mode 100644 index d6ce322bcc0c..000000000000 --- a/modules/migration-updating-deprecated-gvks.adoc +++ /dev/null @@ -1,130 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// for CAM 1.2/4.4 only - -[id='migration-gvk-incompatibility_{context}'] -= Updating deprecated APIs - -In {product-title} {product-version}, some APIs that are used by {product-title} 3.x are link:https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/[deprecated]. - -If your source cluster uses deprecated APIs, the following warning message is displayed when you create a migration plan in the {mtc-full} ({mtc-short}): - -[source,terminal] ----- -Some namespaces contain GVKs incompatible with destination cluster ----- - -You can click *See details* to view the namespace and the incompatible APIs. This warning message does not block the migration. - -During migration with the {mtc-full} ({mtc-short}), the deprecated APIs are saved in the `Velero` Backup #1 for Kubernetes objects. You can download the `Velero` Backup, extract the deprecated API `yaml` files, and update them with the `oc convert` command. Then you can create the updated APIs on the target cluster. - -.Procedure - -. Run the migration plan. - -. View the `MigPlan` CR: -+ -[source,terminal] ----- -$ oc describe migplan <migplan_name> -n openshift-migration <1> ----- -<1> Specify the name of the migration plan. -+ -The output is similar to the following: -+ -[source,yaml] ----- -metadata: - ... - uid: 79509e05-61d6-11e9-bc55-02ce4781844a <1> -status: - ... - conditions: - - category: Warn - lastTransitionTime: 2020-04-30T17:16:23Z - message: 'Some namespaces contain GVKs incompatible with destination cluster. - See: `incompatibleNamespaces` for details' - status: "True" - type: GVKsIncompatible - incompatibleNamespaces: - - gvks: <2> - - group: batch - kind: cronjobs - version: v2alpha1 - - group: batch - kind: scheduledjobs - version: v2alpha1 ----- -<1> Record the `MigPlan` UID. -<2> Record the deprecated APIs listed in the `gvks` section. - -. Get the `MigMigration` name associated with the `MigPlan` UID: -+ -[source,terminal] ----- -$ oc get migmigration -o json | jq -r '.items[] | select(.metadata.ownerReferences[].uid=="<migplan_uid>") | .metadata.name' <1> ----- -<1> Specify the `MigPlan` UID. - -. Get the `MigMigration` UID associated with the `MigMigration` name: -+ -[source,terminal] ----- -$ oc get migmigration <migmigration_name> -o jsonpath='{.metadata.uid}' <1> ----- -<1> Specify the `MigMigration` name. - -. Get the `Velero` Backup name associated with the `MigMigration` UID: -+ -[source,terminal] ----- -$ oc get backup.velero.io --selector migration-initial-backup="<migmigration_uid>" -o jsonpath={.items[*].metadata.name} <1> ----- -<1> Specify the `MigMigration` UID. - -. Download the contents of the `Velero` Backup to your local machine by running the command for your storage provider: - -* AWS S3: -+ -[source,terminal] ----- -$ aws s3 cp s3://<bucket_name>/velero/backups/<backup_name> <backup_local_dir> --recursive <1> ----- -<1> Specify the bucket, backup name, and your local backup directory name. - -* GCP: -+ -[source,terminal] ----- -$ gsutil cp gs://<bucket_name>/velero/backups/<backup_name> <backup_local_dir> --recursive <1> ----- -<1> Specify the bucket, backup name, and your local backup directory name. - -* Azure: -+ -[source,terminal] ----- -$ azcopy copy 'https://velerobackups.blob.core.windows.net/velero/backups/%3Cbackup_name%3E' '<backup_local_dir>' --recursive <1> ----- -<1> Specify the backup name and your local backup directory name. - -. Extract the `Velero` Backup archive file: -+ -[source,terminal] ----- -$ tar -xfv <backup_local_dir>/<backup_name>.tar.gz -C <backup_local_dir> ----- - -. Run `oc convert` in offline mode on each deprecated API: -+ -[source,terminal] ----- -$ oc convert -f <backup_local_dir>/resources/<gvk>.json ----- - -. Create the converted API on the target cluster: -+ -[source,terminal] ----- -$ oc create -f <gvk>.json ----- diff --git a/modules/migration-updating-internal-images.adoc b/modules/migration-updating-internal-images.adoc deleted file mode 100644 index a95629f5fd8e..000000000000 --- a/modules/migration-updating-internal-images.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc - -[id='migration-updating-internal-images_{context}'] -= Updating internal images manually - -If your application uses images from the `openshift` namespace, the required versions of the images must be present on the target cluster. - -If the {product-title} 3 image is deprecated in {product-title} {product-version}, you can manually update the image stream tag using Podman. - -.Prerequisites - -* You must have Podman installed. -* You must have `cluster-admin` privileges. - -.Procedure - -. Expose the internal registries on the source and target clusters. -. If you are using insecure registries, add your registry host values to the `[registries.insecure]` section of `/etc/container/registries.conf` to ensure that Podman does not encounter a TLS verification error. -. Log in to the source cluster registry: -+ -[source,terminal] ----- -$ podman login -u $(oc whoami) -p $(oc whoami -t) --tls-verify=false <source_cluster> ----- - -. Log in to the target cluster registry: -+ -[source,terminal] ----- -$ podman login -u $(oc whoami) -p $(oc whoami -t) --tls-verify=false <target_cluster> ----- - -. Pull the deprecated image: -+ -[source,terminal] ----- -$ podman pull <source_cluster>/openshift/<image> ----- - -. Tag the image for the target cluster registry: -+ -[source,terminal] ----- -$ podman tag <source_cluster>/openshift/<image> <target_cluster>/openshift/<image> ----- - -. Push the image to the target cluster 4 registry: -+ -[source,terminal] ----- -$ podman push <target_cluster>/openshift/<image> ----- - -. Verify that the image has a valid image stream on the target cluster: -+ -[source,terminal] ----- -$ oc get imagestream -n openshift | grep <image> ----- -+ -.Example output -[source,terminal] ----- -<image> <target_cluster>/openshift/<image> <versions> -more... 6 seconds ago ----- diff --git a/modules/migration-upgrading-from-mtc-1-3.adoc b/modules/migration-upgrading-from-mtc-1-3.adoc deleted file mode 100644 index 3a02f6e51dcb..000000000000 --- a/modules/migration-upgrading-from-mtc-1-3.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/upgrading-migration-tool-3-4.adoc -// * migration/migrating_4_1_4/upgrading-migration-tool-4-1-4.adoc -// * migration/migrating_4_2_4/upgrading-migration-tool-4-2-4.adoc - -[id="migration-upgrading-from-mtc-1-3_{context}"] -= Upgrading {mtc-short} 1.3 - -If you are upgrading {mtc-full} ({mtc-short}) version 1.3.x, you must manually update the `indirectImageMigration` and `indirectVolumeMigration` parameters in the `MigPlan` custom resource (CR). - -Because the `indirectImageMigration` and `indirectVolumeMigration` parameters do not exist in version 1.3, their default value in version 1.4 is `false`, which means that direct image migration and direct volume migration are enabled. Because the direct migration requirements are not fulfilled, the migration plan cannot reach a `Ready` state unless these parameter values are changed to `true`. - -.Prerequisites - -* You must have upgraded {mtc-short} from version 1.3.x to 1.4. -* You must have `cluster-admin` privileges. - -.Procedure - -. Log in to the target cluster. -. Get the `MigPlan` CR: -+ -[source,terminal] ----- -$ oc get migplan <migplan> -o yaml -n openshift-migration ----- - -. Change the following parameter values to `true` and save the file: -+ -[source,yaml] ----- -... -spec: - indirectImageMigration: true - indirectVolumeMigration: true ----- - -. Apply the changes: -+ -[source,terminal] ----- -$ oc replace -f <migplan>.yaml -n openshift-migration ----- - -. Verify the changes by viewing the updated `MigPlan` CR: -+ -[source,terminal] ----- -$ oc get migplan <migplan> -o yaml -n openshift-migration ----- diff --git a/modules/migration-upgrading-migration-tool-3.adoc b/modules/migration-upgrading-migration-tool-3.adoc deleted file mode 100644 index 7c091a01da59..000000000000 --- a/modules/migration-upgrading-migration-tool-3.adoc +++ /dev/null @@ -1,105 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/upgrading-migration-tool-3-4.adoc - -[id='migration-upgrading-migration-tool-3_{context}'] -= Upgrading the {mtc-full} on an {product-title} 3 cluster - -You can upgrade {mtc-full} ({mtc-short}) on an {product-title} 3 cluster by downloading the latest `operator.yml` file and replacing the existing {mtc-full} Operator. - -.Prerequisites - -* Access to `registry.redhat.io` -* Podman installed - -.Procedure - -. Log in to `registry.redhat.io` with your Red Hat Customer Portal credentials: -+ -[source,terminal] ----- -$ sudo podman login registry.redhat.io ----- - -. Download the latest `operator.yml` file: -+ -[source,terminal,subs="attributes+"] ----- -$ sudo podman cp $(sudo podman create registry.redhat.io/rhmtc/openshift-migration-rhel7-operator:v{mtc-version-z}):/operator.yml ./ ----- - -. Replace the {mtc-full} Operator: -+ -[source,terminal] ----- -$ oc replace --force -f operator.yml ----- - -. If you are upgrading {mtc-short} 1.1.2 or earlier versions, delete the `Restic` pods to apply the changes: -+ -[source,terminal] ----- -$ oc delete pod <restic_pod> ----- - -. If you are upgrading {mtc-short} 1.2 or later versions, scale the `migration-operator` deployment to `0` to stop the deployment: -+ -[source,terminal] ----- -$ oc scale -n openshift-migration --replicas=0 deployment/migration-operator ----- - -. Scale the `migration-operator` deployment to `1` to start the deployment and apply the changes: -+ -[source,terminal] ----- -$ oc scale -n openshift-migration --replicas=1 deployment/migration-operator ----- - -. Verify that the `migration-operator` was upgraded to {mtc-version-z}: -+ -[source,terminal] ----- -$ oc -o yaml -n openshift-migration get deployment/migration-operator | grep image: | awk -F ":" '{ print $NF }' ----- - -. Download the latest `controller-3.yml` file: -+ -[source,terminal,subs="attributes+"] ----- -$ sudo podman cp $(sudo podman create registry.redhat.io/rhmtc/openshift-migration-rhel7-operator:v{mtc-version-z}):/controller-3.yml ./ ----- - -. Create the `migration-controller` object: -+ -[source,terminal] ----- -$ oc create -f controller-3.yml ----- - -. If your {product-title} version is 3.10 or earlier, set the security context constraint of the `migration-controller` service account to `anyuid` to enable direct image migration and direct volume migration: -+ -[source,terminal] ----- -$ oc adm policy add-scc-to-user anyuid -z migration-controller -n openshift-migration ----- - -. Verify that the {mtc-short} pods are running: -+ -[source,terminal] ----- -$ oc get pods -n openshift-migration ----- - -. If you have already added your {product-title} 3 source cluster to the {mtc-short} console, you must update the service account token because the upgrade deletes and restores the `openshift-migration` namespace: - -.. Obtain the service account token: -+ -[source,terminal] ----- -$ oc sa get-token migration-controller -n openshift-migration ----- - -.. In the {mtc-short} console, click *Clusters*, click the Options menu {kebab} next to the source cluster, and select *Edit*. - -.. Enter the new service account token in the *Service account token* field, click *Update cluster*, and then click *Close*. diff --git a/modules/migration-upgrading-migration-tool-4.adoc b/modules/migration-upgrading-migration-tool-4.adoc deleted file mode 100644 index d2fbde1173df..000000000000 --- a/modules/migration-upgrading-migration-tool-4.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/upgrading-migration-tool-3-4.adoc -// * migration/migrating_4_1_4/upgrading-migration-tool-4-1-4.adoc -// * migration/migrating_4_2_4/upgrading-migration-tool-4-2-4.adoc - -[id='migration-upgrading-migration-tool-4_{context}'] -= Upgrading the {mtc-full} on an {product-title} 4 cluster - -You can upgrade the {mtc-full} ({mtc-short}) on an {product-title} 4 cluster using the {product-title} console. - -ifdef::migrating-4-1-4,migrating-4-2-4[] -If you selected the *Automatic* approval option when you installed the {mtc-full} Operator, the Operator is updated automatically. - -The following procedure enables you to change the *Manual* approval option to *Automatic* or to change the release channel. -endif::[] - -.Procedure - -. In the {product-title} console, navigate to *Operators* -> *Installed Operators*. -. Click *{mtc-full} Operator*. -ifdef::migrating-4-1-4,migrating-4-2-4[] -. In the *Subscription* tab, change the *Approval* option to *Automatic*. -. Optional: Edit the *Channel*. -+ -Updating the subscription deploys the updated {mtc-full} Operator and updates the {mtc-short} components. -endif::[] - -. Under *Provided APIs*, locate the *Migration Controller* tile, and click *Create Instance*. -ifdef::migrating-4-1-4[] -. If you are upgrading {mtc-short} on a 4.1 _source_ cluster, update the `migration_controller` and `migration_ui` parameters and add the `deprecated_cors_configuration` parameter to the `migration_controller` manifest: -+ -[source,yaml] ----- -spec: -... - migration_controller: false - migration_ui: false - deprecated_cors_configuration: true ----- -+ -[NOTE] -==== -You do not need to update the manifest of the target cluster. -==== -endif::[] - -ifdef::migrating-4-2-4[] -. If you are upgrading {mtc-short} on a 4.2 _source_ cluster, update the `migration_controller` and `migration_ui` parameters in the `migration_controller` manifest: -+ -[source,yaml] ----- -spec: -... - migration_controller: false - migration_ui: false ----- -+ -[NOTE] -==== -You do not need to update the manifest of the target cluster. -==== -endif::[] - -. Click *Create*. -. Click *Workloads* -> *Pods* to verify that the {mtc-short} pods are running. diff --git a/modules/migration-using-cpma.adoc b/modules/migration-using-cpma.adoc deleted file mode 100644 index 3fca287b4f77..000000000000 --- a/modules/migration-using-cpma.adoc +++ /dev/null @@ -1,110 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/migrating-application-workloads-3-4.adoc -[id='migration-using-cpma_{context}'] -= Using the Control Plane Migration Assistant - -The Control Plane Migration Assistant (CPMA) generates CR manifests, which are consumed by {product-title} {product-version} Operators. The CPMA also creates a report that indicates which {product-title} 3 features are supported fully, partially, or not at all. - -CPMA can run in remote mode, retrieving the configuration files from the source cluster using SSH, or in local mode, using local copies of the source cluster's configuration files. - -.Prerequisites - -* The source cluster must be {product-title} 3.7 or later. -* The source cluster must be updated to the latest synchronous release. -* An environment health check must be run on the source cluster to confirm that there are no diagnostic errors or warnings. -* The CPMA binary must be executable. -* You must have `cluster-admin` privileges for the source cluster. - -.Procedure - -. Log in to the {product-title} 3 cluster: -+ -[source,terminal] ----- -$ oc login https://<master1.example.com> <1> ----- -<1> Specify the master node. You must be logged in to receive a token for the Kubernetes and {product-title} APIs. - -. Run the CPMA: -+ -[source,terminal] ----- -$ cpma --manifests=false <1> ----- -<1> The `--manifests=false` option runs the CPMA without generating CR manifests. -+ -Each prompt requires you to provide input, as in the following example: -+ -.Example output -[source,terminal] ----- -? Do you wish to save configuration for future use? true -? What will be the source for OCP3 config files? Remote host <1> -? Path to crio config file /etc/crio/crio.conf -? Path to etcd config file /etc/etcd/etcd.conf -? Path to master config file /etc/origin/master/master-config.yaml -? Path to node config file /etc/origin/node/node-config.yaml -? Path to registries config file /etc/containers/registries.conf -? Do wish to find source cluster using KUBECONFIG or prompt it? KUBECONFIG -? Select cluster obtained from KUBECONFIG contexts master1-example-com:443 -? Select master node master1.example.com -? SSH login root <2> -? SSH Port 22 -? Path to private SSH key /home/user/.ssh/openshift_key -? Path to application data, skip to use current directory . -INFO[29 Aug 19 00:07 UTC] Starting manifest and report generation -INFO[29 Aug 19 00:07 UTC] Transform:Starting for - API -INFO[29 Aug 19 00:07 UTC] APITransform::Extract -INFO[29 Aug 19 00:07 UTC] APITransform::Transform:Reports -INFO[29 Aug 19 00:07 UTC] Transform:Starting for - Cluster -INFO[29 Aug 19 00:08 UTC] ClusterTransform::Transform:Reports -INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportQuotas -INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportPVs -INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportNamespaces -INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportNodes -INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportRBAC -INFO[29 Aug 19 00:08 UTC] ClusterReport::ReportStorageClasses -INFO[29 Aug 19 00:08 UTC] Transform:Starting for - Crio -INFO[29 Aug 19 00:08 UTC] CrioTransform::Extract -WARN[29 Aug 19 00:08 UTC] Skipping Crio: No configuration file available -INFO[29 Aug 19 00:08 UTC] Transform:Starting for - Docker -INFO[29 Aug 19 00:08 UTC] DockerTransform::Extract -INFO[29 Aug 19 00:08 UTC] DockerTransform::Transform:Reports -INFO[29 Aug 19 00:08 UTC] Transform:Starting for - ETCD -INFO[29 Aug 19 00:08 UTC] ETCDTransform::Extract -INFO[29 Aug 19 00:08 UTC] ETCDTransform::Transform:Reports -INFO[29 Aug 19 00:08 UTC] Transform:Starting for - OAuth -INFO[29 Aug 19 00:08 UTC] OAuthTransform::Extract -INFO[29 Aug 19 00:08 UTC] OAuthTransform::Transform:Reports -INFO[29 Aug 19 00:08 UTC] Transform:Starting for - SDN -INFO[29 Aug 19 00:08 UTC] SDNTransform::Extract -INFO[29 Aug 19 00:08 UTC] SDNTransform::Transform:Reports -INFO[29 Aug 19 00:08 UTC] Transform:Starting for - Image -INFO[29 Aug 19 00:08 UTC] ImageTransform::Extract -INFO[29 Aug 19 00:08 UTC] ImageTransform::Transform:Reports -INFO[29 Aug 19 00:08 UTC] Transform:Starting for - Project -INFO[29 Aug 19 00:08 UTC] ProjectTransform::Extract -INFO[29 Aug 19 00:08 UTC] ProjectTransform::Transform:Reports -INFO[29 Aug 19 00:08 UTC] Flushing reports to disk -INFO[29 Aug 19 00:08 UTC] Report:Added: report.json -INFO[29 Aug 19 00:08 UTC] Report:Added: report.html -INFO[29 Aug 19 00:08 UTC] Successfully finished transformations ----- -<1> The `Remote host` option runs the CPMA in remote mode. -<2> `SSH login`: The SSH user must have `sudo` permissions on the {product-title} 3 cluster to access the configuration files. -+ -The CPMA creates the following files and directory in the current directory if you did not specify an output directory: - -* `cpma.yaml` file: Configuration options that you provided when you ran the CPMA -* `master1.example.com/`: Configuration files from the master node -* `report.json`: JSON-encoded report -* `report.html`: HTML-encoded report - -. Open the `report.html` file in a browser to view the CPMA report. - -. If you generate CR manifests, apply the CR manifests to the {product-title} {product-version} cluster, as shown in the following example: -+ -[source,terminal] ----- -$ oc apply -f 100_CPMA-cluster-config-secret-htpasswd-secret.yaml ----- diff --git a/modules/migration-using-mig-log-reader.adoc b/modules/migration-using-mig-log-reader.adoc deleted file mode 100644 index cf67d6ef55e4..000000000000 --- a/modules/migration-using-mig-log-reader.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id='migration-using-mig-log-reader_{context}'] -= Using the migration log reader - -You can use the migration log reader to display a single filtered view of all the migration logs. - -.Procedure - -. Get the `mig-log-reader` pod: -+ -[source,terminal] ----- -$ oc -n openshift-migration get pods | grep log ----- - -. Enter the following command to display a single migration log: -+ -[source,terminal] ----- -$ oc -n openshift-migration logs -f <mig-log-reader-pod> -c color <1> ----- -<1> The `-c plain` option displays the log without colors. diff --git a/modules/migration-using-must-gather.adoc b/modules/migration-using-must-gather.adoc deleted file mode 100644 index 71445797438b..000000000000 --- a/modules/migration-using-must-gather.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc - -[id="migration-using-must-gather_{context}"] -= Using `must-gather` to collect data - -You must run the `must-gather` tool if you open a customer support case on the link:https://access.redhat.com[Red Hat Customer Portal] for the {mtc-full} ({mtc-short}). - -The `openshift-migration-must-gather-rhel8` image for {mtc-short} collects migration-specific logs and data that are not collected by the default `must-gather` image. - -.Procedure - -. Navigate to the directory where you want to store the `must-gather` data. -. Run the `must-gather` command: -+ -[source,terminal,subs="attributes+"] ----- -$ oc adm must-gather --image=openshift-migration-must-gather-rhel8:v{mtc-version-z} ----- - -. Remove authentication keys and other sensitive information. -. Create an archive file containing the contents of the `must-gather` data directory: -+ -[source,terminal] ----- -$ tar cvaf must-gather.tar.gz must-gather.local.<uid>/ ----- - -. Upload the compressed file as an attachment to your customer support case. diff --git a/modules/migration-viewing-migration-crs.adoc b/modules/migration-viewing-migration-crs.adoc deleted file mode 100644 index 792459074c5a..000000000000 --- a/modules/migration-viewing-migration-crs.adoc +++ /dev/null @@ -1,207 +0,0 @@ -// Module included in the following assemblies: -// -// * migration/migrating_3_4/troubleshooting-3-4.adoc -// * migration/migrating_4_1_4/troubleshooting-4-1-4.adoc -// * migration/migrating_4_2_4/troubleshooting-4-2-4.adoc -[id='migration-viewing-migration-crs_{context}'] -= Viewing {mtc-short} custom resources - -You can view the following {mtc-full} ({mtc-short}) custom resources (CRs) to troubleshoot a failed migration: - -* `MigCluster` -* `MigStorage` -* `MigPlan` -* `BackupStorageLocation` -+ -The `BackupStorageLocation` CR contains a `migrationcontroller` label to identify the {mtc-short} instance that created the CR: -+ -[source,yaml] ----- - labels: - migrationcontroller: ebe13bee-c803-47d0-a9e9-83f380328b93 ----- - -* `VolumeSnapshotLocation` -+ -The `VolumeSnapshotLocation` CR contains a `migrationcontroller` label to identify the {mtc-short} instance that created the CR: -+ -[source,yaml] ----- - labels: - migrationcontroller: ebe13bee-c803-47d0-a9e9-83f380328b93 ----- - -* `MigMigration` -* `Backup` -+ -{mtc-short} changes the reclaim policy of migrated persistent volumes (PVs) to `Retain` on the target cluster. The `Backup` CR contains an `openshift.io/orig-reclaim-policy` annotation that indicates the original reclaim policy. You can manually restore the reclaim policy of the migrated PVs. - -* `Restore` - -.Procedure - -. List the `MigMigration` CRs in the `openshift-migration` namespace: -+ -[source,terminal] ----- -$ oc get migmigration -n openshift-migration ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -88435fe0-c9f8-11e9-85e6-5d593ce65e10 6m42s ----- - -. Inspect the `MigMigration` CR: -+ -[source,terminal] ----- -$ oc describe migmigration 88435fe0-c9f8-11e9-85e6-5d593ce65e10 -n openshift-migration ----- -+ -The output is similar to the following examples. - -.`MigMigration` example output -[source,yaml] ----- -name: 88435fe0-c9f8-11e9-85e6-5d593ce65e10 -namespace: openshift-migration -labels: <none> -annotations: touch: 3b48b543-b53e-4e44-9d34-33563f0f8147 -apiVersion: migration.openshift.io/v1alpha1 -kind: MigMigration -metadata: - creationTimestamp: 2019-08-29T01:01:29Z - generation: 20 - resourceVersion: 88179 - selfLink: /apis/migration.openshift.io/v1alpha1/namespaces/openshift-migration/migmigrations/88435fe0-c9f8-11e9-85e6-5d593ce65e10 - uid: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6 -spec: - migPlanRef: - name: socks-shop-mig-plan - namespace: openshift-migration - quiescePods: true - stage: false -status: - conditions: - category: Advisory - durable: True - lastTransitionTime: 2019-08-29T01:03:40Z - message: The migration has completed successfully. - reason: Completed - status: True - type: Succeeded - phase: Completed - startTimestamp: 2019-08-29T01:01:29Z -events: <none> ----- - -.`Velero` backup CR #2 example output that describes the PV data -[source,yaml] ----- -apiVersion: velero.io/v1 -kind: Backup -metadata: - annotations: - openshift.io/migrate-copy-phase: final - openshift.io/migrate-quiesce-pods: "true" - openshift.io/migration-registry: 172.30.105.179:5000 - openshift.io/migration-registry-dir: /socks-shop-mig-plan-registry-44dd3bd5-c9f8-11e9-95ad-0205fe66cbb6 - openshift.io/orig-reclaim-policy: delete - creationTimestamp: "2019-08-29T01:03:15Z" - generateName: 88435fe0-c9f8-11e9-85e6-5d593ce65e10- - generation: 1 - labels: - app.kubernetes.io/part-of: migration - migmigration: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6 - migration-stage-backup: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6 - velero.io/storage-location: myrepo-vpzq9 - name: 88435fe0-c9f8-11e9-85e6-5d593ce65e10-59gb7 - namespace: openshift-migration - resourceVersion: "87313" - selfLink: /apis/velero.io/v1/namespaces/openshift-migration/backups/88435fe0-c9f8-11e9-85e6-5d593ce65e10-59gb7 - uid: c80dbbc0-c9f8-11e9-95ad-0205fe66cbb6 -spec: - excludedNamespaces: [] - excludedResources: [] - hooks: - resources: [] - includeClusterResources: null - includedNamespaces: - - sock-shop - includedResources: - - persistentvolumes - - persistentvolumeclaims - - namespaces - - imagestreams - - imagestreamtags - - secrets - - configmaps - - pods - labelSelector: - matchLabels: - migration-included-stage-backup: 8886de4c-c9f8-11e9-95ad-0205fe66cbb6 - storageLocation: myrepo-vpzq9 - ttl: 720h0m0s - volumeSnapshotLocations: - - myrepo-wv6fx -status: - completionTimestamp: "2019-08-29T01:02:36Z" - errors: 0 - expiration: "2019-09-28T01:02:35Z" - phase: Completed - startTimestamp: "2019-08-29T01:02:35Z" - validationErrors: null - version: 1 - volumeSnapshotsAttempted: 0 - volumeSnapshotsCompleted: 0 - warnings: 0 ----- - -.`Velero` restore CR #2 example output that describes the Kubernetes resources - -[source,yaml] ----- -apiVersion: velero.io/v1 -kind: Restore -metadata: - annotations: - openshift.io/migrate-copy-phase: final - openshift.io/migrate-quiesce-pods: "true" - openshift.io/migration-registry: 172.30.90.187:5000 - openshift.io/migration-registry-dir: /socks-shop-mig-plan-registry-36f54ca7-c925-11e9-825a-06fa9fb68c88 - creationTimestamp: "2019-08-28T00:09:49Z" - generateName: e13a1b60-c927-11e9-9555-d129df7f3b96- - generation: 3 - labels: - app.kubernetes.io/part-of: migration - migmigration: e18252c9-c927-11e9-825a-06fa9fb68c88 - migration-final-restore: e18252c9-c927-11e9-825a-06fa9fb68c88 - name: e13a1b60-c927-11e9-9555-d129df7f3b96-gb8nx - namespace: openshift-migration - resourceVersion: "82329" - selfLink: /apis/velero.io/v1/namespaces/openshift-migration/restores/e13a1b60-c927-11e9-9555-d129df7f3b96-gb8nx - uid: 26983ec0-c928-11e9-825a-06fa9fb68c88 -spec: - backupName: e13a1b60-c927-11e9-9555-d129df7f3b96-sz24f - excludedNamespaces: null - excludedResources: - - nodes - - events - - events.events.k8s.io - - backups.velero.io - - restores.velero.io - - resticrepositories.velero.io - includedNamespaces: null - includedResources: null - namespaceMapping: null - restorePVs: true -status: - errors: 0 - failureReason: "" - phase: Completed - validationErrors: null - warnings: 15 ----- diff --git a/modules/migration-writing-ansible-playbook-hook.adoc b/modules/migration-writing-ansible-playbook-hook.adoc deleted file mode 100644 index 44a6661c4815..000000000000 --- a/modules/migration-writing-ansible-playbook-hook.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// * migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc -// * migration/migrating_4_1_4/migrating-applications-with-cam-4-1-4.adoc -// * migration/migrating_4_2_4/migrating-applications-with-cam-4-2-4.adoc - -[id="migration-writing-ansible-playbook-hook_{context}"] -= Writing an Ansible playbook for a migration hook - -You can write an Ansible playbook to use as a migration hook. The hook is added to a migration plan by using the {mtc-short} web console or by specifying values for the `spec.hooks` parameters in the `MigPlan` custom resource (CR) manifest. - -The Ansible playbook is mounted onto a hook container as a config map. The hook container runs as a job, using the cluster, service account, and namespace specified in the `MigPlan` CR. The hook container uses a specified service account token so that the tasks do not require authentication before they run in the cluster. - -[id="migration-writing-ansible-playbook-hook-ansible-modules_{context}"] -== Ansible modules - -You can use the Ansible `shell` module to run `oc` commands. - -.Example `shell` module -[source,yaml] ----- -- hosts: localhost - gather_facts: false - tasks: - - name: get pod name - shell: oc get po --all-namespaces ----- - -You can use `kubernetes.core` modules, such as `k8s_info`, to interact with Kubernetes resources. - -.Example `k8s_facts` module -[source,yaml] ----- -- hosts: localhost - gather_facts: false - tasks: - - name: Get pod - k8s_info: - kind: pods - api: v1 - namespace: openshift-migration - name: "{{ lookup( 'env', 'HOSTNAME') }}" - register: pods - - - name: Print pod name - debug: - msg: "{{ pods.resources[0].metadata.name }}" ----- - -You can use the `fail` module to produce a non-zero exit status in cases where a non-zero exit status would not normally be produced, ensuring that the success or failure of a hook is detected. Hooks run as jobs and the success or failure status of a hook is based on the exit status of the job container. - -.Example `fail` module -[source,yaml] ----- -- hosts: localhost - gather_facts: false - tasks: - - name: Set a boolean - set_fact: - do_fail: true - - - name: "fail" - fail: - msg: "Cause a failure" - when: do_fail ----- - -[id="migration-writing-ansible-playbook-hook-environment-variables_{context}"] -== Environment variables - -The `MigPlan` CR name and migration namespaces are passed as environment variables to the hook container. These variables are accessed by using the `lookup` plug-in. - -.Example environment variables -[source,yaml] ----- -- hosts: localhost - gather_facts: false - tasks: - - set_fact: - namespaces: "{{ (lookup( 'env', 'migration_namespaces')).split(',') }}" - - - debug: - msg: "{{ item }}" - with_items: "{{ namespaces }}" - - - debug: - msg: "{{ lookup( 'env', 'migplan_name') }}" ----- diff --git a/modules/mint-mode-with-removal-of-admin-credential.adoc b/modules/mint-mode-with-removal-of-admin-credential.adoc deleted file mode 100644 index 5eb9739f4b1b..000000000000 --- a/modules/mint-mode-with-removal-of-admin-credential.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/manually-creating-iam.adoc - -[id="mint-mode-with-removal-or-rotation-of-admin-credential_{context}"] -= Mint mode with removal or rotation of the administrator-level credential - -Currently, this mode is only supported on AWS and GCP. - -In this mode, a user installs {product-title} with an administrator-level credential just like the normal mint mode. However, this process removes the administrator-level credential secret from the cluster post-installation. - -The administrator can have the Cloud Credential Operator make its own request for a read-only credential that allows it to verify if all `CredentialsRequest` objects have their required permissions, thus the administrator-level credential is not required unless something needs to be changed. After the associated credential is removed, it can be deleted or deactivated on the underlying cloud, if desired. - -[NOTE] -==== -Prior to a non z-stream upgrade, you must reinstate the credential secret with the administrator-level credential. If the credential is not present, the upgrade might be blocked. -==== - -The administrator-level credential is not stored in the cluster permanently. - -Following these steps still requires the administrator-level credential in the cluster for brief periods of time. It also requires manually re-instating the secret with administrator-level credentials for each upgrade. diff --git a/modules/mint-mode.adoc b/modules/mint-mode.adoc deleted file mode 100644 index b9e472f16b00..000000000000 --- a/modules/mint-mode.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/manually-creating-iam.adoc -// * installing/installing_azure/manually-creating-iam-azure.adoc -// * installing/installing_gcp/manually-creating-iam-gcp.adoc - -[id="mint-mode_{context}"] -= Mint mode - -Mint mode is the default and recommended Cloud Credential Operator (CCO) credentials mode for {product-title}. In this mode, the CCO uses the provided administrator-level cloud credential to run the cluster. Mint mode is supported for AWS, GCP, and Azure. - -In mint mode, the `admin` credential is stored in the `kube-system` namespace and then used by the CCO to process the `CredentialsRequest` objects in the cluster and create users for each with specific permissions. - -The benefits of mint mode include: - -* Each cluster component has only the permissions it requires -* Automatic, on-going reconciliation for cloud credentials, including additional credentials or permissions that might be required for upgrades - -One drawback is that mint mode requires `admin` credential storage in a cluster `kube-system` secret. diff --git a/modules/mod-docs-ocp-conventions.adoc b/modules/mod-docs-ocp-conventions.adoc deleted file mode 100644 index bc4b64b96c70..000000000000 --- a/modules/mod-docs-ocp-conventions.adoc +++ /dev/null @@ -1,154 +0,0 @@ -// Module included in the following assemblies: -// -// * mod_docs_guide/mod-docs-conventions-ocp.adoc - -// Base the file name and the ID on the module title. For example: -// * file name: my-reference-a.adoc -// * ID: [id="my-reference-a"] -// * Title: = My reference A - -[id="mod-docs-ocp-conventions_{context}"] -= Modular docs OpenShift conventions - -These Modular Docs conventions for OpenShift docs build on top of the CCS -modular docs guidelines. - -These guidelines and conventions should be read along with the: - -* General CCS -link:https://redhat-documentation.github.io/modular-docs/[modular docs guidelines]. -* link:https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc markup conventions] -* link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/contributing.adoc[OpenShift Contribution Guide] -* link:https://github.com/openshift/openshift-docs/blob/master/contributing_to_docs/doc_guidelines.adoc[OpenShift Documentation Guidelines] - -IMPORTANT: If some convention is duplicated, the convention in this guide -supersedes all others. - -[id="ocp-ccs-conventions_{context}"] -== OpenShift CCS conventions - -* All assemblies must define a context that is unique. -+ -Add this context at the top of the page, just before the first anchor id. -+ -Example: -+ ----- -:context: assembly-gsg ----- - -* All assemblies must include the `modules/common-attributes.adoc` file near the -context statement. This file contains the standard attributes for the collection. -+ -`include::modules/common-attributes.adoc[leveloffset=+1]` - -* All anchor ids must follow the format: -+ ----- -[id="<anchor-name-with-dashes>_{context}"] ----- -+ -Anchor name is _connected_ to the `&#123;context&#125;` using a dash. -+ -Example: -+ ----- -[id="creating-your-first-content_{context}"] ----- - -* All modules anchor ids must have the `&#123;context&#125;` variable. -+ -This is just reiterating the format described in the previous bullet point. - -* A comment section must be present at the top of each module and assembly, as -shown in the link:https://github.com/redhat-documentation/modular-docs/tree/master/modular-docs-manual/files[modular docs templates]. -+ -The modules comment section must list which assemblies this module has been -included in, while the assemblies comment section must include other assemblies -that it itself is included in, if any. -+ -Example comment section in an assembly: -+ ----- -// This assembly is included in the following assemblies: -// -// NONE ----- -+ -Example comment section in a module: -+ ----- -// Module included in the following assemblies: -// -// mod_docs_guide/mod-docs-conventions-ocp.adoc ----- - -* All modules must go in the modules directory which is present in the top level -of the openshift-docs repository. These modules must follow the file naming -conventions specified in the -link:https://redhat-documentation.github.io/modular-docs/[modular docs guidelines]. - -* All assemblies must go in the relevant guide/book. If you can't find a relevant - guide/book, reach out to a member of the OpenShift CCS team. So guides/books contain assemblies, which - contain modules. - -* modules and images folders are symlinked to the top level folder from each book/guide folder. - -* In your assemblies, when you are linking to the content in other books, you must -use the relative path starting like so: -+ ----- -xref:../architecture/architecture.adoc#architecture[architecture] overview. ----- -+ -[IMPORTANT] -==== -You must not include xrefs in modules or create an xref to a module. You can -only use xrefs to link from one assembly to another. -==== - -* All modules in assemblies must be included using the following format (replace 'ilude' with 'include'): -+ -`ilude::modules/<file_name_of_module>.adoc[]` -+ -_OR_ -+ -`ilude::modules/<file_name_of_module>.adoc[leveloffset=+<offset_by>]` -+ -if it requires a leveloffset. -+ -Example: -+ -`include::modules/creating-your-first-content.adoc[leveloffset=+1]` - -NOTE: There is no `..` at the starting of the path. - -//// -* If your assembly is in a subfolder of a guide/book directory, you must add a -statement to the assembly’s metadata to use `relfileprefix`. -+ -This adjusts all the xref links in your modules to start from the root -directory. -+ -At the top of the assembly (in the metadata section), add the following line: -+ ----- -:relfileprefix: ../ ----- -+ -NOTE: There is a space between the second : and the ../. - -+ -The only difference in including a module in the _install_config/index.adoc_ -assembly and _install_config/install/planning.adoc_ assembly is the addition of -the `:relfileprefix: ../` attribute at the top of the -_install_config/install/planning.adoc_ assembly. The actual inclusion of -module remains the same as described in the previous bullet. - -+ -NOTE: This strategy is in place so that links resolve correctly on both -docs.openshift.com and portal docs. -//// - -* Do not use 3rd level folders even though AsciiBinder permits it. If you need -to, work out a better way to organize your content. diff --git a/modules/modify-a-custom-role.adoc b/modules/modify-a-custom-role.adoc new file mode 100644 index 000000000000..7933234ba04e --- /dev/null +++ b/modules/modify-a-custom-role.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="modify-a-custom-role_{context}"] += Modifying a custom role + +[role="_abstract"] +From the *Access Control* view, you can modify permissions for the custom roles that you have created. + +.Prerequisites +* You must have the *Admin* role, or read and write permissions for the `Access` resource to create, modify, and delete custom roles. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Click on the *Roles and Permissions* tab. +. From the *StackRox Roles* panel, select the name of the role you want to modify. +. Click *Edit* on the role details panel. +. Modify permissions as required, and then click *Save* to save the changes. + +[NOTE] +==== +You cannot modify `read` and `write` permissions for the default system roles. +==== diff --git a/modules/modify-existing-security-policies.adoc b/modules/modify-existing-security-policies.adoc new file mode 100644 index 000000000000..2eb5ddcc071c --- /dev/null +++ b/modules/modify-existing-security-policies.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="modify-existing-security-policies_{context}"] += Modifying existing security policies + +[role="_abstract"] +You can edit the policies you have created and the existing default policies provided by {product-title} that you have cloned. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. From the *Policies* page, select the policy you want to edit. +. Select *Actions* -> *Edit policy*. ++ +[NOTE] +==== +You cannot edit default policies. You must clone a default policy and edit the cloned policy. +==== +. Edit the fields that you want to change and click *Save*. diff --git a/modules/modify-policy-categories-using-tab.adoc b/modules/modify-policy-categories-using-tab.adoc new file mode 100644 index 000000000000..4b150d92012f --- /dev/null +++ b/modules/modify-policy-categories-using-tab.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="modify-policy-categories-using-tab_{context}"] += Modifying policy categories by using the Policy categories tab + +Beginning with version 3.74, {product-title-short} provides a new method to create and manage policy categories in {product-title-managed} or in {product-title-short} if you have the PostgreSQL database enabled. All policy workflows other than policy creation remain unchanged when using this feature. + +You can also configure policy categories by using the `PolicyCategoryService` API object. For more information, go to *Help* -> *API reference* in the {product-title-short} portal. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. +. Click the *Policy categories* tab. This tab provides a list of existing categories and allows you to filter the list by category name. You can also click *Show all categories* and select the checkbox to remove default or custom categories from the displayed list. +. Click a policy name to edit or delete it. Default policy categories cannot be selected, edited, or deleted. diff --git a/modules/modify-unavailable-workers.adoc b/modules/modify-unavailable-workers.adoc deleted file mode 100644 index c721340fe37b..000000000000 --- a/modules/modify-unavailable-workers.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/recommended-host-practices.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="modify-unavailable-workers_{context}"] -= Modifying the number of unavailable worker nodes - -By default, only one machine is allowed to be unavailable when applying the kubelet-related configuration to the available worker nodes. For a large cluster, it can take a long time for the configuration change to be reflected. At any time, you can adjust the number of machines that are updating to speed up the process. - -.Procedure - -. Run: -+ -[source,terminal] ----- -$ oc edit machineconfigpool worker ----- - -. Set `maxUnavailable` to the value that you want: -+ -[source,yaml] ----- -spec: - maxUnavailable: <node_count> ----- -+ -[IMPORTANT] -==== -When setting the value, consider the number of worker nodes that can be -unavailable without affecting the applications running on the cluster. -==== diff --git a/modules/modifying-platform-component-definitions.adoc b/modules/modifying-platform-component-definitions.adoc new file mode 100644 index 000000000000..6cd525db47ef --- /dev/null +++ b/modules/modifying-platform-component-definitions.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * configuration/customizing-platform-components.adoc +:_mod-docs-content-type: PROCEDURE +[id="modifying-platform-component-definitions_{context}"] += Modifying platform component definitions + +You can define platform components by using namespaces to segment platform security findings from user workloads. + +.Prerequisites +* You must have the `Administration` role with `read` permission to view the platform component configuration options. +* You must have the `Administration` role with `write` permission to modify the platform component configuration. + +.Procedure + +. In the RHACS portal, go to **Platform Configuration** > **System Configuration**. +. On the *System Configuration* view header, click **Edit**. +. Under the **Platform components configuration** section, click on the **Red{nbsp}Hat layered products** tab. Components found in Red{nbsp}Hat layered and partner product namespaces are included in the platform definition by default. +.. To modify the Red{nbsp}Hat layered products definition, enter one or more namespaces using regular expressions, separated by a pipe `|` symbol. For more information on the syntax structure, see the link:https://github.com/google/re2/wiki/syntax[RE2 syntax reference]. +. Click on the **Custom components** tab. +.. To add a custom platform component, click **Add custom platform component**. You can add more than one. +.. In the new **Custom component** entry, enter a descriptive **Name**. +.. Enter the **Namespace rules (Regex)** for this custom component. Enter one or more namespaces using regular expressions, separated by a pipe `|` symbol. For more information on the syntax structure, see the link:https://github.com/google/re2/wiki/syntax[RE2 syntax reference]. +. Click **Save**. diff --git a/modules/modifying-template-for-new-projects.adoc b/modules/modifying-template-for-new-projects.adoc deleted file mode 100644 index 0e758a92370a..000000000000 --- a/modules/modifying-template-for-new-projects.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/projects/configuring-project-creation.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="modifying-template-for-new-projects_{context}"] -= Modifying the template for new projects - -As a cluster administrator, you can modify the default project template so that -new projects are created using your custom requirements. - -To create your own custom project template: - -.Procedure - -. Log in as a user with `cluster-admin` privileges. - -. Generate the default project template: -+ -[source,terminal] ----- -$ oc adm create-bootstrap-project-template -o yaml > template.yaml ----- - -. Use a text editor to modify the generated `template.yaml` file by adding -objects or modifying existing objects. - -. The project template must be created in the `openshift-config` namespace. Load -your modified template: -+ -[source,terminal] ----- -$ oc create -f template.yaml -n openshift-config ----- - -. Edit the project configuration resource using the web console or CLI. - -** Using the web console: -... Navigate to the *Administration* -> *Cluster Settings* page. -... Click *Global Configuration* to view all configuration resources. -... Find the entry for *Project* and click *Edit YAML*. - -** Using the CLI: -... Edit the `project.config.openshift.io/cluster` resource: -+ -[source,terminal] ----- -$ oc edit project.config.openshift.io/cluster ----- - -. Update the `spec` section to include the `projectRequestTemplate` and `name` -parameters, and set the name of your uploaded project template. The default name -is `project-request`. -+ -.Project configuration resource with custom project template -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Project -metadata: - ... -spec: - projectRequestTemplate: - name: <template_name> ----- - -. After you save your changes, create a new project to verify that your changes -were successfully applied. diff --git a/modules/monitor-osp-disable-helm.adoc b/modules/monitor-osp-disable-helm.adoc new file mode 100644 index 000000000000..148740f385bc --- /dev/null +++ b/modules/monitor-osp-disable-helm.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// configuration/monitor-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="monitor-osp-disable-helm_{context}"] += Disabling {osp} monitoring for Central services by using Helm + +To disable the default monitoring by using Helm, change the configuration options in the `central-services` Helm chart. For more information on configuration options, see the documents in the "Additional resources" section. + +.Procedure +. Update the configuration file with the following value: ++ +[source,yaml] +---- +monitoring.openshift.enabled: false +---- +. Run the `helm upgrade` command and specify the configuration files. \ No newline at end of file diff --git a/modules/monitor-osp-disable-operator.adoc b/modules/monitor-osp-disable-operator.adoc new file mode 100644 index 000000000000..ea4e6ffb5575 --- /dev/null +++ b/modules/monitor-osp-disable-operator.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// configuration/monitor-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="monitor-osp-disable-operator_{context}"] += Disabling {osp} monitoring for Central services by using the {product-title-short} Operator + +To disable the default monitoring by using the Operator, change the configuration of the `Central` custom resource as shown in the following example. For more information on configuration options, see "Central configuration options using the Operator" in the "Additional resources" section. + +.Procedure +. On the {ocp} web console, go to the *Operators* -> *Installed Operators* page. +. Select the {product-title-short} Operator from the list of installed Operators. +. Click on the *Central* tab. +. From the list of Central instances, click on a Central instance for which you want to enable monitoring. +. Click on the *YAML* tab and update the YAML configuration as shown in the following example: ++ +[source,yaml] +---- +monitoring: + openshift: + enabled: false +---- \ No newline at end of file diff --git a/modules/monitoring-about-cluster-monitoring.adoc b/modules/monitoring-about-cluster-monitoring.adoc deleted file mode 100644 index 652390afc974..000000000000 --- a/modules/monitoring-about-cluster-monitoring.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc -// * monitoring/understanding-the-monitoring-stack.adoc - -// This module uses a conditionalized title so that the module -// can be re-used in associated products but the title is not -// included in the existing OpenShift assembly. - -[id="about-openshift-monitoring_{context}"] -ifeval::["{context}" == "understanding-the-monitoring-stack"] -:ocp-monitoring: -endif::[] - -ifndef::ocp-monitoring[] -= About {product-title} monitoring -endif::ocp-monitoring[] -:ocp-monitoring!: - -{product-title} includes a pre-configured, pre-installed, and self-updating monitoring stack that provides *monitoring for core platform components*. {product-title} delivers monitoring best practices out of the box. A set of alerts are included by default that immediately notify cluster administrators about issues with a cluster. Default dashboards in the {product-title} web console include visual representations of cluster metrics to help you to quickly understand the state of your cluster. - -After installing {product-title} {product-version}, cluster administrators can optionally enable *monitoring for user-defined projects*. By using this feature, cluster administrators, developers, and other users can specify how services and pods are monitored in their own projects. You can then query metrics, review dashboards, and manage alerting rules and silences for your own projects in the {product-title} web console. - -[NOTE] -==== -Cluster administrators can grant developers and other users permission to monitor their own projects. Privileges are granted by assigning one of the predefined monitoring roles. -==== - -[id="about-openshift-monitoring_{context}"] -ifeval::["{context}" == "understanding-the-monitoring-stack"] -:!ocp-monitoring: -endif::[] diff --git a/modules/monitoring-accessing-alerting-rules-for-your-project.adoc b/modules/monitoring-accessing-alerting-rules-for-your-project.adoc deleted file mode 100644 index a7fb1eceb2d8..000000000000 --- a/modules/monitoring-accessing-alerting-rules-for-your-project.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="accessing-alerting-rules-for-your-project_{context}"] -= Accessing alerting rules for user-defined projects - -To list alerting rules for a user-defined project, you must have been assigned the `monitoring-rules-view` role for the project. - -.Prerequisites - -* You have enabled monitoring for user-defined projects. -* You are logged in as a user that has the `monitoring-rules-view` role for your project. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. You can list alerting rules in `<project>`: -+ -[source,terminal] ----- -$ oc -n <project> get prometheusrule ----- - -. To list the configuration of an alerting rule, run the following: -+ -[source,terminal] ----- -$ oc -n <project> get prometheusrule <rule> -o yaml ----- diff --git a/modules/monitoring-accessing-the-alerting-ui.adoc b/modules/monitoring-accessing-the-alerting-ui.adoc deleted file mode 100644 index 203c316fc452..000000000000 --- a/modules/monitoring-accessing-the-alerting-ui.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="accessing_the_alerting_ui_{context}"] -= Accessing the Alerting UI in the Administrator and Developer perspectives - -The Alerting UI is accessible through the Administrator perspective and the Developer perspective in the {product-title} web console. - -* In the *Administrator* perspective, select *Monitoring* -> *Alerting*. The three main pages in the Alerting UI in this perspective are the *Alerts*, *Silences*, and *Alerting Rules* pages. - -//Next to the title of each of these pages is a link to the Alertmanager interface. - -* In the *Developer* perspective, select *Monitoring* -> *<project_name>* -> *Alerts*. In this perspective, alerts, silences, and alerting rules are all managed from the *Alerts* page. The results shown in the *Alerts* page are specific to the selected project. - -[NOTE] -==== -In the Developer perspective, you can select from core {product-title} and user-defined projects that you have access to in the *Project:* list. However, alerts, silences, and alerting rules relating to core {product-title} projects are not displayed if you do not have `cluster-admin` privileges. -==== diff --git a/modules/monitoring-accessing-third-party-uis-using-the-cli.adoc b/modules/monitoring-accessing-third-party-uis-using-the-cli.adoc deleted file mode 100644 index 678fa4640419..000000000000 --- a/modules/monitoring-accessing-third-party-uis-using-the-cli.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/accessing-third-party-uis.adoc - -[id="accessing-third-party-uis-using-the-cli_{context}"] -= Accessing third-party monitoring UIs by using the CLI - -You can obtain URLs for the Prometheus, Alertmanager, and Grafana web UIs by using the OpenShift CLI (`oc`) tool. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Run the following to list routes for the `openshift-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring get routes ----- -+ -.Example output -[source,terminal] ----- -NAME HOST/PORT ... -alertmanager-main alertmanager-main-openshift-monitoring.apps._url_.openshift.com ... -grafana grafana-openshift-monitoring.apps._url_.openshift.com ... -prometheus-k8s prometheus-k8s-openshift-monitoring.apps._url_.openshift.com ... -thanos-querier thanos-querier-openshift-monitoring.apps._url_.openshift.com ... ----- - -. Navigate to a `HOST/PORT` route by using a web browser. - -. Select *Log in with OpenShift* to log in using your OpenShift credentials. diff --git a/modules/monitoring-accessing-third-party-uis-using-the-web-console.adoc b/modules/monitoring-accessing-third-party-uis-using-the-web-console.adoc deleted file mode 100644 index a7dc6ebfcbfc..000000000000 --- a/modules/monitoring-accessing-third-party-uis-using-the-web-console.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/accessing-third-party-uis.adoc - -[id="accessing-third-party-uis-using-the-web-console_{context}"] -= Accessing third-party monitoring UIs by using the web console - -You can access the Alertmanager, Grafana, Prometheus, and Thanos Querier web UIs through the {product-title} web console. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. In the *Administrator* perspective, navigate to *Networking* -> *Routes*. -+ -[NOTE] -==== -Access to the third-party Alertmanager, Grafana, Prometheus, and Thanos Querier UIs is not available from the Developer perspective. -==== - -. Select the `openshift-monitoring` project in the *Project:* list. - -. Access a third-party monitoring UI: - -* Select the URL in the `alertmanager-main` row to open the login page for the Alertmanager UI. - -* Select the URL in the `grafana` row to open the login page for the Grafana UI. - -* Select the URL in the `prometheus-k8s` row to open the login page for the Prometheus UI. - -* Select the URL in the `thanos-querier` row to open the login page for the Thanos Querier UI. - -. Choose *Log in with OpenShift* to log in using your OpenShift credentials. diff --git a/modules/monitoring-and-analyzing-the-health-of-your-clusters.adoc b/modules/monitoring-and-analyzing-the-health-of-your-clusters.adoc new file mode 100644 index 000000000000..61980e783a14 --- /dev/null +++ b/modules/monitoring-and-analyzing-the-health-of-your-clusters.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="monitoring-and-analyzing-the-health-of-your-clusters_{context}"] += Monitoring and analyzing the health of your clusters + +By viewing the status of a profile check, you can efficiently monitor and analyze the health of your clusters. + +[IMPORTANT] +==== +Wait until the Compliance Operator returns the scan results. It might take a few minutes. +==== + +.Procedure + +. In the {product-title-short} portal, click *Compliance -> OpenShift Coverage*. +. Select a cluster to view the details of the individual scans. +. Optional: Choose the appropriate method to re-organize the information in the *Coverage* page. +** To filter the scan results based on a scan schedule, from the drop-down list, select the scan schedule. If you do not select a particular scan schedule, *All scan schedules* is selected automatically. +** To filter the scan results based on an entity and its attributes, do any of the following tasks: ++ +[IMPORTANT] +==== +To select multiple entities and attributes, click the right arrow icon to add another search criteria. +==== ++ +*** To filter the scan results based on a profile check, enter the name of the profile check in the search bar to view the status. +*** To filter the scan results based on cluster attributes, from the drop-down list, select *Cluster*, and then select an attribute. Enter the details of the cluster attribute in the search bar to view the status. ++ +The following values are associated with the attributes of a cluster: ++ +**** `ID` +**** `Name` +**** `Label` +**** `Type` +**** `Platform Type` + +. Optional: From the *Compliance status* drop-down list, select one or more statuses by using which you want to filter the scan details. ++ +The following values are associated with how you want to filter the scan details: + +** `Pass` +** `Fail` +** `Error` +** `Info` +** `Manual` +** `Not Applicable` +** `Inconsistent` \ No newline at end of file diff --git a/modules/monitoring-applying-custom-alertmanager-configuration.adoc b/modules/monitoring-applying-custom-alertmanager-configuration.adoc deleted file mode 100644 index 86b843ef09ef..000000000000 --- a/modules/monitoring-applying-custom-alertmanager-configuration.adoc +++ /dev/null @@ -1,108 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="applying-custom-alertmanager-configuration_{context}"] -= Applying a custom Alertmanager configuration - -You can overwrite the default Alertmanager configuration by editing the `alertmanager-main` secret inside the `openshift-monitoring` project. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -To change the Alertmanager configuration from the CLI: - -. Print the currently active Alertmanager configuration into file `alertmanager.yaml`: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring get secret alertmanager-main --template='{{ index .data "alertmanager.yaml" }}' | base64 -d > alertmanager.yaml ----- -+ -. Edit the configuration in `alertmanager.yaml`: -+ -[source,yaml] ----- -global: - resolve_timeout: 5m -route: - group_wait: 30s - group_interval: 5m - repeat_interval: 12h - receiver: default - routes: - - match: - alertname: Watchdog - repeat_interval: 5m - receiver: watchdog - - match: - service: <your_service> <1> - routes: - - match: - <your_matching_rules> <2> - receiver: <receiver> <3> -receivers: -- name: default -- name: watchdog -- name: <receiver> - <receiver_configuration> ----- -<1> `service` specifies the service that fires the alerts. -<2> `<your_matching_rules>` specifies the target alerts. -<3> `receiver` specifies the receiver to use for the alert. -+ -The following Alertmanager configuration example configures PagerDuty as an alert receiver: -+ -[source,yaml,subs=quotes] ----- -global: - resolve_timeout: 5m -route: - group_wait: 30s - group_interval: 5m - repeat_interval: 12h - receiver: default - routes: - - match: - alertname: Watchdog - repeat_interval: 5m - receiver: watchdog - *- match: - service: example-app - routes: - - match: - severity: critical - receiver: team-frontend-page* -receivers: -- name: default -- name: watchdog -*- name: team-frontend-page - pagerduty_configs: - - service_key: "_your-key_"* ----- -+ -With this configuration, alerts of `critical` severity that are fired by the `example-app` service are sent using the `team-frontend-page` receiver. Typically these types of alerts would be paged to an individual or a critical response team. -+ -. Apply the new configuration in the file: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring create secret generic alertmanager-main --from-file=alertmanager.yaml --dry-run -o=yaml | oc -n openshift-monitoring replace secret --filename=- ----- - -To change the Alertmanager configuration from the {product-title} web console: - -. Navigate to the *Administration* -> *Cluster Settings* -> *Global Configuration* -> *Alertmanager* -> *YAML* page of the web console. - -. Modify the YAML configuration file. - -. Select *Save*. - -.Additional resources - -* See link:https://www.pagerduty.com/[the PagerDuty official site] for more information on PagerDuty -* See link:https://www.pagerduty.com/docs/guides/prometheus-integration-guide/[the PagerDuty Prometheus Integration Guide] to learn how to retrieve the `service_key` -* See link:https://prometheus.io/docs/alerting/configuration/[Alertmanager configuration] for configuring alerting through different alert receivers diff --git a/modules/monitoring-assigning-tolerations-to-monitoring-components.adoc b/modules/monitoring-assigning-tolerations-to-monitoring-components.adoc deleted file mode 100644 index b3065c005b3e..000000000000 --- a/modules/monitoring-assigning-tolerations-to-monitoring-components.adoc +++ /dev/null @@ -1,123 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="assigning-tolerations-to-monitoring-components_{context}"] -= Assigning tolerations to monitoring components - -You can assign tolerations to any of the monitoring stack components to enable moving them to tainted nodes. - -.Prerequisites - -* *If you are configuring core {product-title} monitoring components*: -** You have access to the cluster as a user with the `cluster-admin` role. -** You have created the `cluster-monitoring-config` `ConfigMap` object. -* *If you are configuring components that monitor user-defined projects*: -** You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -** You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `ConfigMap` object: -** *To assign tolerations to a component that monitors core {product-title} projects*: -.. Edit the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -.. Specify `tolerations` for the component: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - <component>: - tolerations: - <toleration_specification> ----- -+ -Substitute `<component>` and `<toleration_specification>` accordingly. -+ -For example, `oc adm taint nodes node1 key1=value1:NoSchedule` adds a taint to `node1` with the key `key1` and the value `value1`. This prevents monitoring components from deploying pods on `node1` unless a toleration is configured for that taint. The following example configures the `alertmanagerMain` component to tolerate the example taint: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - alertmanagerMain: - tolerations: - - key: "key1" - operator: "Equal" - value: "value1" - effect: "NoSchedule" ----- - -** *To assign tolerations to a component that monitors user-defined projects*: -.. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- - -.. Specify `tolerations` for the component: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - <component>: - tolerations: - <toleration_specification> ----- -+ -Substitute `<component>` and `<toleration_specification>` accordingly. -+ -For example, `oc adm taint nodes node1 key1=value1:NoSchedule` adds a taint to `node1` with the key `key1` and the value `value1`. This prevents monitoring components from deploying pods on `node1` unless a toleration is configured for that taint. The following example configures the `thanosRuler` component to tolerate the example taint: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - thanosRuler: - tolerations: - - key: "key1" - operator: "Equal" - value: "value1" - effect: "NoSchedule" ----- - -. Save the file to apply the changes. The new component placement configuration is applied automatically. -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== -+ -[WARNING] -==== -When changes are saved to a monitoring config map, the pods and other resources in the related project might be redeployed. The running monitoring processes in that project might also be restarted. -==== diff --git a/modules/monitoring-attaching-additional-labels-to-your-time-series-and-alerts.adoc b/modules/monitoring-attaching-additional-labels-to-your-time-series-and-alerts.adoc deleted file mode 100644 index c56880438ecf..000000000000 --- a/modules/monitoring-attaching-additional-labels-to-your-time-series-and-alerts.adoc +++ /dev/null @@ -1,134 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="attaching-additional-labels-to-your-time-series-and-alerts_{context}"] -= Attaching additional labels to your time series and alerts - -Using the external labels feature of Prometheus, you can attach custom labels to all time series and alerts leaving Prometheus. - -.Prerequisites - -* *If you are configuring core {product-title} monitoring components*: -** You have access to the cluster as a user with the `cluster-admin` role. -** You have created the `cluster-monitoring-config` `ConfigMap` object. -* *If you are configuring components that monitor user-defined projects*: -** You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -** You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `ConfigMap` object: -** *To attach custom labels to all time series and alerts leaving the Prometheus instance that monitors core {product-title} projects*: -.. Edit the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -.. Define a map of labels you want to add for every metric under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - prometheusK8s: - externalLabels: - <key>: <value> <1> ----- -+ -<1> Substitute `<key>: <value>` with a map of key-value pairs where `<key>` is a unique name for the new label and `<value>` is its value. -+ -[WARNING] -==== -Do not use `prometheus` or `prometheus_replica` as key names, because they are reserved and will be overwritten. -==== -+ -For example, to add metadata about the region and environment to all time series and alerts, use: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - prometheusK8s: - externalLabels: - region: eu - environment: prod ----- - -** *To attach custom labels to all time series and alerts leaving the Prometheus instance that monitors user-defined projects*: -.. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- - -.. Define a map of labels you want to add for every metric under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - prometheus: - externalLabels: - <key>: <value> <1> ----- -+ -<1> Substitute `<key>: <value>` with a map of key-value pairs where `<key>` is a unique name for the new label and `<value>` is its value. -+ -[WARNING] -==== -Do not use `prometheus` or `prometheus_replica` as key names, because they are reserved and will be overwritten. -==== -+ -[NOTE] -==== -In the `openshift-user-workload-monitoring` project, Prometheus handles metrics and Thanos Ruler handles alerting and recording rules. Setting `externalLabels` for `prometheus` in the `user-workload-monitoring-config` `ConfigMap` object will only configure external labels for metrics and not for any rules. -==== -+ -For example, to add metadata about the region and environment to all time series and alerts related to user-defined projects, use: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - prometheus: - externalLabels: - region: eu - environment: prod ----- - -. Save the file to apply the changes. The new configuration is applied automatically. -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== -+ -[WARNING] -==== -When changes are saved to a monitoring config map, the pods and other resources in the related project might be redeployed. The running monitoring processes in that project might also be restarted. -==== diff --git a/modules/monitoring-components-for-monitoring-user-defined-projects.adoc b/modules/monitoring-components-for-monitoring-user-defined-projects.adoc deleted file mode 100644 index 883add25be29..000000000000 --- a/modules/monitoring-components-for-monitoring-user-defined-projects.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/understanding-the-monitoring-stack.adoc - -[id="components-for-monitoring-user-defined-projects_{context}"] -= Components for monitoring user-defined projects - -{product-title} {product-version} includes an optional enhancement to the monitoring stack that enables you to monitor services and pods in user-defined projects. This feature includes the following components: - -.Components for monitoring user-defined projects -[options="header"] -|=== - -|Component|Description - -|Prometheus Operator -|The Prometheus Operator (PO) in the `openshift-user-workload-monitoring` project creates, configures, and manages Prometheus and Thanos Ruler instances in the same project. - -|Prometheus -|Prometheus is the monitoring system through which monitoring is provided for user-defined projects. Prometheus sends alerts to Alertmanager for processing. - -|Thanos Ruler -|The Thanos Ruler is a rule evaluation engine for Prometheus that is deployed as a separate process. In {product-title} {product-version}, Thanos Ruler provides rule and alerting evaluation for the monitoring of user-defined projects. - -|=== - -[NOTE] -==== -The components in the preceding table are deployed after monitoring is enabled for user-defined projects. -==== - -All of the components in the monitoring stack are monitored by the stack and are automatically updated when {product-title} is updated. diff --git a/modules/monitoring-configurable-monitoring-components.adoc b/modules/monitoring-configurable-monitoring-components.adoc deleted file mode 100644 index bf05199cb58a..000000000000 --- a/modules/monitoring-configurable-monitoring-components.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="configurable-monitoring-components_{context}"] -= Configurable monitoring components - -This table shows the monitoring components you can configure and the keys used to specify the components in the `cluster-monitoring-config` and `user-workload-monitoring-config` `ConfigMap` objects: - -.Configurable monitoring components -[options="header"] -|==== -|Component |cluster-monitoring-config config map key |user-workload-monitoring-config config map key -|Prometheus Operator |`prometheusOperator` |`prometheusOperator` -|Prometheus |`prometheusK8s` |`prometheus` -|Alertmanager |`alertmanagerMain` | -|kube-state-metrics |`kubeStateMetrics` | -|openshift-state-metrics |`openshiftStateMetrics` | -|Grafana |`grafana` | -|Telemeter Client |`telemeterClient` | -|Prometheus Adapter |`k8sPrometheusAdapter` | -|Thanos Querier |`thanosQuerier` | -|Thanos Ruler | |`thanosRuler` -|==== - -[NOTE] -==== -The Prometheus key is called `prometheusK8s` in the `cluster-monitoring-config` `ConfigMap` object and `prometheus` in the `user-workload-monitoring-config` `ConfigMap` object. -==== diff --git a/modules/monitoring-configuring-a-local-persistent-volume-claim.adoc b/modules/monitoring-configuring-a-local-persistent-volume-claim.adoc deleted file mode 100644 index 0a688128c6f9..000000000000 --- a/modules/monitoring-configuring-a-local-persistent-volume-claim.adoc +++ /dev/null @@ -1,177 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="configuring-a-local-persistent-volume-claim_{context}"] -= Configuring a local persistent volume claim - -For monitoring components to use a persistent volume (PV), you must configure a persistent volume claim (PVC). - -.Prerequisites - -* *If you are configuring core {product-title} monitoring components*: -** You have access to the cluster as a user with the `cluster-admin` role. -** You have created the `cluster-monitoring-config` `ConfigMap` object. -* *If you are configuring components that monitor user-defined projects*: -** You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -** You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `ConfigMap` object: -** *To configure a PVC for a component that monitors core {product-title} projects*: -.. Edit the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -.. Add your PVC configuration for the component under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - <component>: - volumeClaimTemplate: - spec: - storageClassName: <storage_class> - resources: - requests: - storage: <amount_of_storage> ----- -+ -See the link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims[Kubernetes documentation on PersistentVolumeClaims] for information on how to specify `volumeClaimTemplate`. -+ -The following example configures a PVC that claims local persistent storage for the Prometheus instance that monitors core {product-title} components: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - *prometheusK8s*: - volumeClaimTemplate: - spec: - storageClassName: *local-storage* - resources: - requests: - storage: *40Gi* ----- -+ -In the above example, the storage class created by the Local Storage Operator is called `local-storage`. -+ -The following example configures a PVC that claims local persistent storage for Alertmanager: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - *alertmanagerMain*: - volumeClaimTemplate: - spec: - storageClassName: *local-storage* - resources: - requests: - storage: *40Gi* ----- - -** *To configure a PVC for a component that monitors user-defined projects*: -.. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- - -.. Add your PVC configuration for the component under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - <component>: - volumeClaimTemplate: - spec: - storageClassName: <storage_class> - resources: - requests: - storage: <amount_of_storage> ----- -+ -See the link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims[Kubernetes documentation on PersistentVolumeClaims] for information on how to specify `volumeClaimTemplate`. -+ -The following example configures a PVC that claims local persistent storage for the Prometheus instance that monitors user-defined projects: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - *prometheus*: - volumeClaimTemplate: - spec: - storageClassName: *local-storage* - resources: - requests: - storage: *40Gi* ----- -+ -In the above example, the storage class created by the Local Storage Operator is called `local-storage`. -+ -The following example configures a PVC that claims local persistent storage for Thanos Ruler: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - *thanosRuler*: - volumeClaimTemplate: - spec: - storageClassName: *local-storage* - resources: - requests: - storage: *40Gi* ----- - -. Save the file to apply the changes. The pods affected by the new configuration are restarted automatically and the new storage configuration is applied. -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== -+ -[WARNING] -==== -When changes are saved to a monitoring config map, the pods and other resources in the related project might be redeployed. The running monitoring processes in that project might also be restarted. -==== diff --git a/modules/monitoring-configuring-alert-receivers.adoc b/modules/monitoring-configuring-alert-receivers.adoc deleted file mode 100644 index 308036a9c820..000000000000 --- a/modules/monitoring-configuring-alert-receivers.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc -// * post_installation_configuration/configuring-alert-notifications.adoc - -[id="configuring-alert-receivers_{context}"] -= Configuring alert receivers - -You can configure alert receivers to ensure that you learn about important issues with your cluster. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. In the *Administrator* perspective, navigate to *Administration* -> *Cluster Settings* -> *Global Configuration* -> *Alertmanager*. -+ -[NOTE] -==== -Alternatively, you can navigate to the same page through the notification drawer. Select the bell icon at the top right of the {product-title} web console and choose *Configure* in the *AlertmanagerReceiverNotConfigured* alert. -==== - -. Select *Create Receiver* in the *Receivers* section of the page. - -. In the *Create Receiver* form, add a *Receiver Name* and choose a *Receiver Type* from the list. - -. Edit the receiver configuration: -+ -* For PagerDuty receivers: -+ -.. Choose an integration type and add a PagerDuty integration key. -+ -.. Add the URL of your PagerDuty installation. -+ -.. Select *Show advanced configuration* if you want to edit the client and incident details or the severity specification. -+ -* For webhook receivers: -+ -.. Add the endpoint to send HTTP POST requests to. -+ -.. Select *Show advanced configuration* if you want to edit the default option to send resolved alerts to the receiver. -+ -* For email receivers: -+ -.. Add the email address to send notifications to. -+ -.. Add SMTP configuration details, including the address to send notifications from, the smarthost and port number used for sending emails, the hostname of the SMTP server, and authentication details. -+ -.. Choose whether TLS is required. -+ -.. Select *Show advanced configuration* if you want to edit the default option not to send resolved alerts to the receiver or edit the body of email notifications configuration. -+ -* For Slack receivers: -+ -.. Add the URL of the Slack webhook. -+ -.. Add the Slack channel or user name to send notifications to. -+ -.. Select *Show advanced configuration* if you want to edit the default option not to send resolved alerts to the receiver or edit the icon and username configuration. You can also choose whether to find and link channel names and usernames. - -. By default, firing alerts with labels that match all of the selectors will be sent to the receiver. If you want label values for firing alerts to be matched exactly before they are sent to the receiver: -.. Add routing label names and values in the *Routing Labels* section of the form. -+ -.. Select *Regular Expression* if want to use a regular expression. -+ -.. Select *Add Label* to add further routing labels. - -. Select *Create* to create the receiver. diff --git a/modules/monitoring-configuring-cluster-for-application-monitoring.adoc b/modules/monitoring-configuring-cluster-for-application-monitoring.adoc deleted file mode 100644 index 94c24d136e55..000000000000 --- a/modules/monitoring-configuring-cluster-for-application-monitoring.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/application-monitoring.adoc - -[id="configuring-cluster-for-application-monitoring_{context}"] -= Configuring cluster for application monitoring - -Before application developers can monitor their applications, the human operator of the cluster needs to configure the cluster accordingly. This procedure shows how to. - -.Prerequisites - -* You must log in as a user that belongs to a role with administrative privileges for the cluster. - -.Procedure - -. In the {product-title} web console, navigate to the *Operators* -> *OperatorHub* page and install the Prometheus Operator in the namespace where your application is. - -. Navigate to the *Operators* -> *Installed Operators* page and install Prometheus, Alertmanager, Prometheus Rule, and Service Monitor in the same namespace. diff --git a/modules/monitoring-configuring-monitoring-for-an-application.adoc b/modules/monitoring-configuring-monitoring-for-an-application.adoc deleted file mode 100644 index b766703eec2d..000000000000 --- a/modules/monitoring-configuring-monitoring-for-an-application.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/application-monitoring.adoc - -[id="configuring-monitoring-for-an-application_{context}"] -= Configuring monitoring for an application - -This procedure shows, on an example, how an application developer can deploy an application and configure monitoring for it. - -.Prerequisites - -* Make sure you configured the cluster for application monitoring. In this example, it is presumed that Prometheus and Alertmanager instances were installed in the `default` project. - -.Procedure - -. Create a YAML file for your configuration. In this example, it is called `deploy.yaml`. - -. Add configuration for deploying a sample application: -+ -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-app - namespace: default -spec: - selector: - matchLabels: - app: example-app - replicas: 1 - template: - metadata: - labels: - app: example-app - spec: - containers: - - name: example-app - image: quay.io/brancz/prometheus-example-app:v0.2.0 - ports: - - name: web - containerPort: 8080 ---- ----- - -. Add configuration for exposing the sample application as a service: -+ -[source,yaml] ----- -kind: Service -apiVersion: v1 -metadata: - name: example-app - namespace: default - labels: - tier: frontend -spec: - selector: - app: example-app - ports: - - name: web - port: 8080 ---- ----- - -. Add configuration for creating a service monitor for the sample application. This will add your application as a target for monitoring: -+ -[source,yaml] ----- -apiVersion: monitoring.coreos.com/v1 -kind: ServiceMonitor -metadata: - name: example-app - namespace: default - labels: - k8s-app: example-app -spec: - selector: - matchLabels: - tier: frontend - endpoints: - - port: web ----- - -. Apply the configuration file to the cluster: -+ -[source,terminal] ----- -$ oc apply -f deploy.yaml ----- - -. Forward a port to the Prometheus UI. In this example, port 9090 is used: -+ -[source,terminal] ----- -$ oc port-forward -n openshift-user-workload-monitoring svc/prometheus-operated 9090 ----- - -. Navigate to the Prometheus UI at http://localhost:9090/targets to see the sample application being monitored. diff --git a/modules/monitoring-configuring-the-monitoring-stack.adoc b/modules/monitoring-configuring-the-monitoring-stack.adoc deleted file mode 100644 index 21bf6b5d899b..000000000000 --- a/modules/monitoring-configuring-the-monitoring-stack.adoc +++ /dev/null @@ -1,133 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="configuring-the-monitoring-stack_{context}"] -= Configuring the monitoring stack - -In {product-title} {product-version}, you can configure the monitoring stack using the `cluster-monitoring-config` or `user-workload-monitoring-config` `ConfigMap` objects. Config maps configure the Cluster Monitoring Operator (CMO), which in turn configures the components of the stack. - -.Prerequisites - -* *If you are configuring core {product-title} monitoring components*: -** You have access to the cluster as a user with the `cluster-admin` role. -** You have created the `cluster-monitoring-config` `ConfigMap` object. -* *If you are configuring components that monitor user-defined projects*: -** You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -** You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `ConfigMap` object. -** *To configure core {product-title} monitoring components*: -.. Edit the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -.. Add your configuration under `data/config.yaml` as a key-value pair `<component_name>:{nbsp}<component_configuration>`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - <component>: - <configuration_for_the_component> ----- -+ -Substitute `<component>` and `<configuration_for_the_component>` accordingly. -+ -The following example `ConfigMap` object configures a persistent volume claim (PVC) for Prometheus. This relates to the Prometheus instance that monitors core {product-title} components only: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - prometheusK8s: <1> - volumeClaimTemplate: - spec: - storageClassName: fast - volumeMode: Filesystem - resources: - requests: - storage: 40Gi ----- -<1> Defines the Prometheus component and the subsequent lines define its configuration. - -** *To configure components that monitor user-defined projects*: -.. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- - -.. Add your configuration under `data/config.yaml` as a key-value pair `<component_name>:{nbsp}<component_configuration>`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - <component>: - <configuration_for_the_component> ----- -+ -Substitute `<component>` and `<configuration_for_the_component>` accordingly. -+ -The following example `ConfigMap` object configures a data retention period and minimum container resource requests for Prometheus. This relates to the Prometheus instance that monitors user-defined projects only: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - prometheus: <1> - retention: 24h <2> - resources: - requests: - cpu: 200m <3> - memory: 2Gi <4> ----- -<1> Defines the Prometheus component and the subsequent lines define its configuration. -<2> Configures a twenty-four hour data retention period for the Prometheus instance that monitors user-defined projects. -<3> Defines a minimum resource request of 200 millicores for the Prometheus container. -<4> Defines a minimum pod resource request of 2 GiB of memory for the Prometheus container. -+ -[NOTE] -==== -The Prometheus config map component is called `prometheusK8s` in the `cluster-monitoring-config` `ConfigMap` object and `prometheus` in the `user-workload-monitoring-config` `ConfigMap` object. -==== - -. Save the file to apply the changes to the `ConfigMap` object. The pods affected by the new configuration are restarted automatically. -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== -+ -[WARNING] -==== -When changes are saved to a monitoring config map, the pods and other resources in the related project might be redeployed. The running monitoring processes in that project might also be restarted. -==== diff --git a/modules/monitoring-contents-of-the-metrics-ui.adoc b/modules/monitoring-contents-of-the-metrics-ui.adoc deleted file mode 100644 index 243f8a8edf39..000000000000 --- a/modules/monitoring-contents-of-the-metrics-ui.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="contents-of-the-metrics-ui_{context}"] -= Contents of the Metrics UI - -This section shows and explains the contents of the Metrics UI, a web interface to Prometheus. - -The *Metrics* page is accessible by clicking *Monitoring* -> *Metrics* in the {product-title} web console. - -image::monitoring-metrics-screen.png[] - -. Actions. -* Add query. -* Expand or collapse all query tables. -* Delete all queries. -. Hide the plot. -. The interactive plot. -. The catalog of available metrics. -. Add query. -. Run queries. -. Query forms. -. Expand or collapse the form. -. The query. -. Clear query. -. Enable or disable query. -. Actions for a specific query. -* Enable or disable query. -* Show or hide all series of the query from the plot. -* Delete query. -. The metrics table for a query. -. Color assigned to the graph of the metric. Selecting the square shows or hides the graph. - -Additionally, there is a link to the old Prometheus interface next to the title of the page. diff --git a/modules/monitoring-creating-a-role-for-setting-up-metrics-collection.adoc b/modules/monitoring-creating-a-role-for-setting-up-metrics-collection.adoc deleted file mode 100644 index af2a54cb8824..000000000000 --- a/modules/monitoring-creating-a-role-for-setting-up-metrics-collection.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/monitoring-your-own-services.adoc - -[id="creating-a-role-for-setting-up-metrics-collection_{context}"] -= Creating a role for setting up metrics collection - -This procedure shows how to create a role that allows a user to set up metrics collection for a service as described in "Setting up metrics collection". - -.Procedure - -. Create a YAML file for the new role. In this example, it is called `custom-metrics-role.yaml`. - -. Fill the file with the configuration for the `monitor-crd-edit` role: -+ -[source,yaml] ----- -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: monitor-crd-edit -rules: -- apiGroups: ["monitoring.coreos.com"] - resources: ["prometheusrules", "servicemonitors", "podmonitors"] - verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] ----- -+ -This role enables a user to set up metrics collection for services. - -. Apply the configuration file to the cluster: -+ ----- -$ oc apply -f custom-metrics-role.yaml ----- -+ -Now the role is created. diff --git a/modules/monitoring-creating-alerting-rules-for-user-defined-projects.adoc b/modules/monitoring-creating-alerting-rules-for-user-defined-projects.adoc deleted file mode 100644 index 1f1363145de2..000000000000 --- a/modules/monitoring-creating-alerting-rules-for-user-defined-projects.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="creating-alerting-rules-for-user-defined-projects_{context}"] -= Creating alerting rules for user-defined projects - -You can create alerting rules for user-defined projects. Those alerting rules will fire alerts based on the values of chosen metrics. - -.Prerequisites - -* You have enabled monitoring for user-defined projects. -* You are logged in as a user that has the `monitoring-rules-edit` role for the project where you want to create an alerting rule. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Create a YAML file for alerting rules. In this example, it is called `example-app-alerting-rule.yaml`. - -. Add an alerting rule configuration to the YAML file. For example: -+ -[NOTE] -==== -When you create an alerting rule, a project label is enforced on it if a rule with the same name exists in another project. -==== -+ -[source,yaml] ----- -apiVersion: monitoring.coreos.com/v1 -kind: PrometheusRule -metadata: - name: example-alert - namespace: ns1 -spec: - groups: - - name: example - rules: - - alert: VersionAlert - expr: version{job="prometheus-example-app"} == 0 ----- -+ -This configuration creates an alerting rule named `example-alert`. The alerting rule fires an alert when the `version` metric exposed by the sample service becomes `0`. -+ -[IMPORTANT] -==== -A user-defined alerting rule can include metrics for its own project and cluster metrics. You cannot include metrics for another user-defined project. - -For example, an alerting rule for the user-defined project `ns1` can have metrics from `ns1` and cluster metrics, such as the CPU and memory metrics. However, the rule cannot include metrics from `ns2`. - -Additionally, you cannot create alerting rules for the `openshift-*` core OpenShift projects. {product-title} monitoring by default provides a set of alerting rules for these projects. -==== - -. Apply the configuration file to the cluster: -+ -[source,terminal] ----- -$ oc apply -f example-app-alerting-rule.yaml ----- -+ -It takes some time to create the alerting rule. diff --git a/modules/monitoring-creating-alerting-rules.adoc b/modules/monitoring-creating-alerting-rules.adoc deleted file mode 100644 index bc00020ff02f..000000000000 --- a/modules/monitoring-creating-alerting-rules.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="creating-alerting-rules-for-user-defined-projects_{context}"] -= Creating alerting rules for user-defined projects - -For user-defined projects you can create alerting rules. Those alerting rules will fire alerts based on the values of chosen metrics. - -.Prerequisites - -* You have enabled monitoring for user-defined projects. -* You are logged in as a user that has the `monitoring-rules-edit` role for the project where you want to create an alerting rule. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Create a YAML file for alerting rules. In this example, it is called `example-app-alerting-rule.yaml`. - -. Add an alerting rule configuration to the YAML file. For example: -+ -[NOTE] -==== -When you create an alerting rule, a project label is enforced on it if a rule with the same name exists in another project. -==== -+ -[source,yaml] ----- -apiVersion: monitoring.coreos.com/v1 -kind: PrometheusRule -metadata: - name: example-alert - namespace: ns1 -spec: - groups: - - name: example - rules: - - alert: VersionAlert - expr: version{job="prometheus-example-app"} == 0 ----- -+ -This configuration creates an alerting rule named `example-alert`. The alerting rule fires an alert when the `version` metric exposed by the sample service becomes `0`. -+ -[IMPORTANT] -==== -A user-defined alerting rule can include metrics for its own project and cluster metrics. You cannot include metrics for another user-defined project. - -For example, an alerting rule for the user-defined project `ns1` can have metrics from `ns1` and cluster metrics, such as the CPU and memory metrics. However, the rule cannot include metrics from `ns2`. - -Additionally, you cannot create alerting rules for the `openshift-*` core OpenShift projects. {product-title} monitoring by default provides a set of alerting rules for these projects. -==== - -. Apply the configuration file to the cluster: -+ -[source,terminal] ----- -$ oc apply -f example-app-alerting-rule.yaml ----- -+ -It takes some time to create the alerting rule. diff --git a/modules/monitoring-creating-cluster-monitoring-configmap.adoc b/modules/monitoring-creating-cluster-monitoring-configmap.adoc deleted file mode 100644 index d11370ee0e5b..000000000000 --- a/modules/monitoring-creating-cluster-monitoring-configmap.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="creating-cluster-monitoring-configmap_{context}"] -= Creating a cluster monitoring config map - -To configure core {product-title} monitoring components, you must create the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project. - -[NOTE] -==== -When you save your changes to the `cluster-monitoring-config` `ConfigMap` object, some or all of the pods in the `openshift-monitoring` project might be redeployed. It can sometimes take a while for these components to redeploy. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Check whether the `cluster-monitoring-config` `ConfigMap` object exists: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring get configmap cluster-monitoring-config ----- - -. If the `ConfigMap` object does not exist: -.. Create the following YAML manifest. In this example the file is called `cluster-monitoring-config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | ----- -+ -.. Apply the configuration to create the `ConfigMap` object: -+ -[source,terminal] ----- -$ oc apply -f cluster-monitoring-config.yaml ----- diff --git a/modules/monitoring-creating-scrape-sample-alerts.adoc b/modules/monitoring-creating-scrape-sample-alerts.adoc deleted file mode 100644 index 11b02951cfc9..000000000000 --- a/modules/monitoring-creating-scrape-sample-alerts.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="creating-scrape-sample-alerts_{context}"] -= Creating scrape sample alerts - -You can create alerts that notify you when: - -* The target cannot be scraped or is not available for the specified `for` duration -* A scrape sample threshold is reached or is exceeded for the specified `for` duration - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -* You have enabled monitoring for user-defined projects. -* You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have limited the number of samples that can be accepted per target scrape in user-defined projects, by using `enforcedSampleLimit`. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Create a YAML file with alerts that inform you when the targets are down and when the enforced sample limit is approaching. The file in this example is called `monitoring-stack-alerts.yaml`: -+ -[source,yaml] ----- -apiVersion: monitoring.coreos.com/v1 -kind: PrometheusRule -metadata: - labels: - prometheus: k8s - role: alert-rules - name: monitoring-stack-alerts <1> - namespace: ns1 <2> -spec: - groups: - - name: general.rules - rules: - - alert: TargetDown <3> - annotations: - message: '{{ printf "%.4g" $value }}% of the {{ $labels.job }}/{{ $labels.service - }} targets in {{ $labels.namespace }} namespace are down.' <4> - expr: 100 * (count(up == 0) BY (job, namespace, service) / count(up) BY (job, - namespace, service)) > 10 - for: 10m <5> - labels: - severity: warning <6> - - alert: ApproachingEnforcedSamplesLimit <7> - annotations: - message: '{{ $labels.container }} container of the {{ $labels.pod }} pod in the {{ $labels.namespace }} namespace consumes {{ $value | humanizePercentage }} of the samples limit budget.' <8> - expr: scrape_samples_scraped/50000 > 0.8 <9> - for: 10m <10> - labels: - severity: warning <11> ----- -<1> Defines the name of the alerting rule. -<2> Specifies the user-defined project where the alerting rule will be deployed. -<3> The `TargetDown` alert will fire if the target cannot be scraped or is not available for the `for` duration. -<4> The message that will be output when the `TargetDown` alert fires. -<5> The conditions for the `TargetDown` alert must be true for this duration before the alert is fired. -<6> Defines the severity for the `TargetDown` alert. -<7> The `ApproachingEnforcedSamplesLimit` alert will fire when the defined scrape sample threshold is reached or exceeded for the specified `for` duration. -<8> The message that will be output when the `ApproachingEnforcedSamplesLimit` alert fires. -<9> The threshold for the `ApproachingEnforcedSamplesLimit` alert. In this example the alert will fire when the number of samples per target scrape has exceeded 80% of the enforced sample limit of `50000`. The `for` duration must also have passed before the alert will fire. The `<number>` in the expression `scrape_samples_scraped/<number> > <threshold>` must match the `enforcedSampleLimit` value defined in the `user-workload-monitoring-config` `ConfigMap` object. -<10> The conditions for the `ApproachingEnforcedSamplesLimit` alert must be true for this duration before the alert is fired. -<11> Defines the severity for the `ApproachingEnforcedSamplesLimit` alert. - -. Apply the configuration to the user-defined project: -+ -[source,terminal] ----- -$ oc apply -f monitoring-stack-alerts.yaml ----- diff --git a/modules/monitoring-creating-user-defined-workload-monitoring-configmap.adoc b/modules/monitoring-creating-user-defined-workload-monitoring-configmap.adoc deleted file mode 100644 index fcf8da61df2c..000000000000 --- a/modules/monitoring-creating-user-defined-workload-monitoring-configmap.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="creating-user-defined-workload-monitoring-configmap_{context}"] -= Creating a user-defined workload monitoring config map - -To configure the components that monitor user-defined projects, you must create the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project. - -[NOTE] -==== -When you save your changes to the `user-workload-monitoring-config` `ConfigMap` object, some or all of the pods in the `openshift-user-workload-monitoring` project might be redeployed. It can sometimes take a while for these components to redeploy. You can create and configure the config map before you first enable monitoring for user-defined projects, to prevent having to redeploy the pods often. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Check whether the `user-workload-monitoring-config` `ConfigMap` object exists: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring get configmap user-workload-monitoring-config ----- - -. If the `user-workload-monitoring-config` `ConfigMap` object does not exist: -.. Create the following YAML manifest. In this example the file is called `user-workload-monitoring-config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | ----- -+ -.. Apply the configuration to create the `ConfigMap` object: -+ -[source,terminal] ----- -$ oc apply -f user-workload-monitoring-config.yaml ----- -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== diff --git a/modules/monitoring-custom-prometheus.adoc b/modules/monitoring-custom-prometheus.adoc new file mode 100644 index 000000000000..31434f748e2d --- /dev/null +++ b/modules/monitoring-custom-prometheus.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * configuration/monitor-acs.adoc +:_mod-docs-content-type: CONCEPT +[id="monitoring-custom-prometheus_{context}"] += Monitoring with custom Prometheus + +link:https://prometheus.io/[Prometheus] is an open-source monitoring and alerting platform. +You can use it to monitor health and availability of Central and Sensor components of {product-title-short}. When you enable monitoring, {product-title-short} creates a new monitoring service on port number 9090 and a network policy allowing inbound connections to that port. + +[NOTE] +==== +This monitoring service exposes an endpoint that is not encrypted by TLS and has no authorization. +Use this only when you do not want to use {osp} monitoring. +==== + +Before you can use custom Prometheus monitoring, if you have {osp}, you must disable the default monitoring. If you are using Kubernetes, you do not need to perform this step. \ No newline at end of file diff --git a/modules/monitoring-default-monitoring-components.adoc b/modules/monitoring-default-monitoring-components.adoc deleted file mode 100644 index 53f11c6dc9cb..000000000000 --- a/modules/monitoring-default-monitoring-components.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/understanding-the-monitoring-stack.adoc - -[id="default-monitoring-components_{context}"] -= Default monitoring components - -By default, the {product-title} {product-version} monitoring stack includes these components: - -.Default monitoring stack components -[options="header"] -|=== - -|Component|Description - -|Cluster Monitoring Operator -|The Cluster Monitoring Operator (CMO) is a central component of the monitoring stack. It deploys and manages Prometheus instances, the Thanos Querier, the Telemeter Client, and metrics targets and ensures that they are up to date. The CMO is deployed by the Cluster Version Operator (CVO). - -|Prometheus Operator -|The Prometheus Operator (PO) in the `openshift-monitoring` project creates, configures, and manages platform Prometheus instances and Alertmanager instances. It also automatically generates monitoring target configurations based on Kubernetes label queries. - -|Prometheus -|Prometheus is the monitoring system on which the {product-title} monitoring stack is based. Prometheus is a time-series database and a rule evaluation engine for metrics. Prometheus sends alerts to Alertmanager for processing. - -|Prometheus Adapter -|The Prometheus Adapter (PA in the preceding diagram) translates Kubernetes node and pod queries for use in Prometheus. The resource metrics that are translated include CPU and memory utilization metrics. The Prometheus Adapter exposes the cluster resource metrics API for horizontal pod autoscaling. The Prometheus Adapter is also used by the `oc adm top nodes` and `oc adm top pods` commands. - -|Alertmanager -|The Alertmanager service handles alerts received from Prometheus. Alertmanager is also responsible for sending the alerts to external notification systems. - -|`kube-state-metrics` agent -|The `kube-state-metrics` exporter agent (KSM in the preceding diagram) converts Kubernetes objects to metrics that Prometheus can use. - -|`openshift-state-metrics` agent -|The `openshift-state-metrics` exporter (OSM in the preceding diagram) expands upon `kube-state-metrics` by adding metrics for {product-title}-specific resources. - -|`node-exporter` agent -|The `node-exporter` agent (NE in the preceding diagram) collects metrics about every node in a cluster. The `node-exporter` agent is deployed on every node. - -|Thanos Querier -|The Thanos Querier aggregates and optionally deduplicates core {product-title} metrics and metrics for user-defined projects under a single, multi-tenant interface. - -|Grafana -|The Grafana analytics platform provides dashboards for analyzing and visualizing the metrics. The Grafana instance that is provided with the monitoring stack, along with its dashboards, is read-only. - -|Telemeter Client -|The Telemeter Client sends a subsection of the data from platform Prometheus instances to Red Hat to facilitate Remote Health Monitoring for clusters. - -|=== - -All of the components in the monitoring stack are monitored by the stack and are automatically updated when {product-title} is updated. diff --git a/modules/monitoring-default-monitoring-targets.adoc b/modules/monitoring-default-monitoring-targets.adoc deleted file mode 100644 index 981620d7861d..000000000000 --- a/modules/monitoring-default-monitoring-targets.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/understanding-the-monitoring-stack.adoc - -[id="default-monitoring-targets_{context}"] -= Default monitoring targets - -In addition to the components of the stack itself, the default monitoring stack monitors: - -* CoreDNS -* Elasticsearch (if Logging is installed) -* etcd -* Fluentd (if Logging is installed) -* HAProxy -* Image registry -* Kubelets -* Kubernetes apiserver -* Kubernetes controller manager -* Kubernetes scheduler -* Metering (if Metering is installed) -* OpenShift apiserver -* OpenShift controller manager -* Operator Lifecycle Manager (OLM) - -[NOTE] -==== -Each {product-title} component is responsible for its monitoring configuration. For problems with the monitoring of an {product-title} component, open a bug in Bugzilla against that component, not against the general monitoring component. -==== - -Other {product-title} framework components might be exposing metrics as well. For details, see their respective documentation. diff --git a/modules/monitoring-deploying-a-sample-service.adoc b/modules/monitoring-deploying-a-sample-service.adoc deleted file mode 100644 index 53c077838153..000000000000 --- a/modules/monitoring-deploying-a-sample-service.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="deploying-a-sample-service_{context}"] -= Deploying a sample service - -To test monitoring of a service in a user-defined project, you can deploy a sample service. - -.Procedure - -. Create a YAML file for the service configuration. In this example, it is called `prometheus-example-app.yaml`. - -. Add the following deployment and service configuration details to the file: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: ns1 ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - app: prometheus-example-app - name: prometheus-example-app - namespace: ns1 -spec: - replicas: 1 - selector: - matchLabels: - app: prometheus-example-app - template: - metadata: - labels: - app: prometheus-example-app - spec: - containers: - - image: quay.io/brancz/prometheus-example-app:v0.2.0 - imagePullPolicy: IfNotPresent - name: prometheus-example-app ---- -apiVersion: v1 -kind: Service -metadata: - labels: - app: prometheus-example-app - name: prometheus-example-app - namespace: ns1 -spec: - ports: - - port: 8080 - protocol: TCP - targetPort: 8080 - name: web - selector: - app: prometheus-example-app - type: ClusterIP ----- -+ -This configuration deploys a service named `prometheus-example-app` in the user-defined `ns1` project. This service exposes the custom `version` metric. - -. Apply the configuration to the cluster: -+ -[source,terminal] ----- -$ oc apply -f prometheus-example-app.yaml ----- -+ -It takes some time to deploy the service. - -. You can check that the pod is running: -+ -[source,terminal] ----- -$ oc -n ns1 get pod ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -prometheus-example-app-7857545cb7-sbgwq 1/1 Running 0 81m ----- diff --git a/modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc b/modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc deleted file mode 100644 index 2b9aec33cdd1..000000000000 --- a/modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/troubleshooting-monitoring-issues.adoc -// * support/troubleshooting/investigating-monitoring-issues.adoc - -[id="determining-why-prometheus-is-consuming-disk-space_{context}"] -= Determining why Prometheus is consuming a lot of disk space - -Developers can create labels to define attributes for metrics in the form of key-value pairs. The number of potential key-value pairs corresponds to the number of possible values for an attribute. An attribute that has an unlimited number of potential values is called an unbound attribute. For example, a `customer_id` attribute is unbound because it has an infinite number of possible values. - -Every assigned key-value pair has a unique time series. The use of many unbound attributes in labels can result in an exponential increase in the number of time series created. This can impact Prometheus performance and can consume a lot of disk space. - -You can use the following measures when Prometheus consumes a lot of disk: - -* *Check the number of scrape samples* that are being collected. -* *Reduce the number of unique time series that are created* by reducing the number of unbound attributes that are assigned to user-defined metrics. -+ -[NOTE] -==== -Using attributes that are bound to a limited set of possible values reduces the number of potential key-value pair combinations. -==== -+ -* *Enforce limits on the number of samples that can be scraped* across user-defined projects. This requires cluster administrator privileges. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. In the *Administrator* perspective, navigate to *Monitoring* -> *Metrics*. - -. Run the following Prometheus Query Language (PromQL) query in the *Expression* field. This returns the ten metrics that have the highest number of scrape samples: -+ -[source,terminal] ----- -topk(10,count by (job)({__name__=~".+"})) ----- - -. Investigate the number of unbound label values assigned to metrics with higher than expected scrape sample counts. -** *If the metrics relate to a user-defined project*, review the metrics key-value pairs assigned to your workload. These are implemented through Prometheus client libraries at the application level. Try to limit the number of unbound attributes referenced in your labels. - -** *If the metrics relate to a core {product-title} project*, create a Red Hat support case on the link:https://access.redhat.com/[Red Hat Customer Portal]. diff --git a/modules/monitoring-disabling-monitoring-for-user-defined-projects.adoc b/modules/monitoring-disabling-monitoring-for-user-defined-projects.adoc deleted file mode 100644 index d5169ebf8c18..000000000000 --- a/modules/monitoring-disabling-monitoring-for-user-defined-projects.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/enabling-monitoring-for-user-defined-projects.adoc - -[id="disabling-monitoring-for-user-defined-projects_{context}"] -= Disabling monitoring for user-defined projects - -After enabling monitoring for user-defined projects, you can disable it again by setting `enableUserWorkload: false` in the cluster monitoring `ConfigMap` object. - -[NOTE] -==== -Alternatively, you can remove `enableUserWorkload: true` to disable monitoring for user-defined projects. -==== - -.Procedure - -. Edit the `cluster-monitoring-config` `ConfigMap` object: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- -+ -.. Set `enableUserWorkload:` to `false` under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - enableUserWorkload: false ----- - -. Save the file to apply the changes. Monitoring for user-defined projects is then disabled automatically. - -. Check that the `prometheus-operator`, `prometheus-user-workload` and `thanos-ruler-user-workload` pods are terminated in the `openshift-user-workload-monitoring` project. This might take a short while: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring get pod ----- -+ -.Example output -[source,terminal] ----- -No resources found in openshift-user-workload-monitoring project. ----- - -[NOTE] -==== -The `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project is not automatically deleted when monitoring for user-defined projects is disabled. This is to preserve any custom configurations that you may have created in the `ConfigMap` object. -==== diff --git a/modules/monitoring-editing-silences.adoc b/modules/monitoring-editing-silences.adoc deleted file mode 100644 index 576aaecef6b7..000000000000 --- a/modules/monitoring-editing-silences.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="editing-silences_{context}"] -= Editing silences - -You can edit a silence, which will expire the existing silence and create a new one with the changed configuration. - -.Procedure - -To edit a silence in the *Administrator* perspective: - -. Navigate to the *Monitoring* -> *Alerting* -> *Silences* page. - -. For the silence you want to modify, select the {kebab} in the last column and choose *Edit silence*. -+ -Alternatively, you can select *Actions* -> *Edit Silence* in the *Silence Details* page for a silence. - -. In the *Edit Silence* page, enter your changes and select *Silence*. This will expire the existing silence and create one with the chosen configuration. - -To edit a silence in the *Developer* perspective: - -. Navigate to the *Monitoring* -> *<project_name>* -> *Alerts* page. - -. Expand the details for an alert by selecting *>* to the left of the alert name. Select the name of the alert in the expanded view to open the *Alert Details* page for the alert. - -. Select the name of a silence in the *Silenced By* section in that page to navigate to the *Silence Details* page for the silence. - -. Select the name of a silence to navigate to its *Silence Details* page. - -. Select *Actions* -> *Edit Silence* in the *Silence Details* page for a silence. - -. In the *Edit Silence* page, enter your changes and select *Silence*. This will expire the existing silence and create one with the chosen configuration. diff --git a/modules/monitoring-enabling-monitoring-for-user-defined-projects.adoc b/modules/monitoring-enabling-monitoring-for-user-defined-projects.adoc deleted file mode 100644 index 4ed32dd49635..000000000000 --- a/modules/monitoring-enabling-monitoring-for-user-defined-projects.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/enabling-monitoring-for-user-defined-projects.adoc - -[id="enabling-monitoring-for-user-defined-projects_{context}"] -= Enabling monitoring for user-defined projects - -Cluster administrators can enable monitoring for user-defined projects by setting the `enableUserWorkload: true` field in the cluster monitoring `ConfigMap` object. - -[IMPORTANT] -==== -In {product-title} {product-version} you must remove any custom Prometheus instances before enabling monitoring for user-defined projects. -==== - -[NOTE] -==== -You must have access to the cluster as a user with the `cluster-admin` role to enable monitoring for user-define projects in {product-title}. Cluster administrators can then optionally grant users permission to configure the components that are responsible for monitoring user-defined projects. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have created the `cluster-monitoring-config` `ConfigMap` object. -* You have optionally created and configured the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project. You can add configuration options to this `ConfigMap` object for the components that monitor user-defined projects. -+ -[NOTE] -==== -Every time you save configuration changes to the `user-workload-monitoring-config` `ConfigMap` object, the pods in the `openshift-user-workload-monitoring` project are redeployed. It can sometimes take a while for these components to redeploy. You can create and configure the `ConfigMap` object before you first enable monitoring for user-defined projects, to prevent having to redeploy the pods often. -==== - -.Procedure - -. Edit the `cluster-monitoring-config` `ConfigMap` object: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -. Add `enableUserWorkload: true` under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - enableUserWorkload: true <1> ----- -<1> When set to `true`, the `enableUserWorkload` parameter enables monitoring for user-defined projects in a cluster. - -. Save the file to apply the changes. Monitoring for user-defined projects is then enabled automatically. -+ -[WARNING] -==== -When changes are saved to the `cluster-monitoring-config` `ConfigMap` object, the pods and other resources in the `openshift-monitoring` project might be redeployed. The running monitoring processes in that project might also be restarted. -==== - -. Check that the `prometheus-operator`, `prometheus-user-workload` and `thanos-ruler-user-workload` pods are running in the `openshift-user-workload-monitoring` project. It might take a short while for the pods to start: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring get pod ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -prometheus-operator-6f7b748d5b-t7nbg 2/2 Running 0 3h -prometheus-user-workload-0 4/4 Running 1 3h -prometheus-user-workload-1 4/4 Running 1 3h -thanos-ruler-user-workload-0 3/3 Running 0 3h -thanos-ruler-user-workload-1 3/3 Running 0 3h ----- diff --git a/modules/monitoring-expiring-silences.adoc b/modules/monitoring-expiring-silences.adoc deleted file mode 100644 index b0580273b821..000000000000 --- a/modules/monitoring-expiring-silences.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="expiring-silences_{context}"] -= Expiring silences - -You can expire a silence. Expiring a silence deactivates it forever. - -.Procedure - -To expire a silence in the *Administrator* perspective: - -. Navigate to the *Monitoring* -> *Alerting* -> *Silences* page. - -. For the silence you want to modify, select the {kebab} in the last column and choose *Expire silence*. -+ -Alternatively, you can select *Actions* -> *Expire Silence* in the *Silence Details* page for a silence. - -To expire a silence in the *Developer* perspective: - -. Navigate to the *Monitoring* -> *<project_name>* -> *Alerts* page. - -. Expand the details for an alert by selecting *>* to the left of the alert name. Select the name of the alert in the expanded view to open the *Alert Details* page for the alert. - -. Select the name of a silence in the *Silenced By* section in that page to navigate to the *Silence Details* page for the silence. - -. Select the name of a silence to navigate to its *Silence Details* page. - -. Select *Actions* -> *Expire Silence* in the *Silence Details* page for a silence. diff --git a/modules/monitoring-exploring-the-visualized-metrics.adoc b/modules/monitoring-exploring-the-visualized-metrics.adoc deleted file mode 100644 index 91a0fdda094f..000000000000 --- a/modules/monitoring-exploring-the-visualized-metrics.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="exploring-the-visualized-metrics_{context}"] -= Exploring the visualized metrics - -After running the queries, the metrics are displayed on an interactive plot. The X-axis in the plot represents time and the Y-axis represents metrics values. Each metric is shown as a colored line on the graph. You can manipulate the plot interactively and explore the metrics. - -.Procedure - -In the *Administrator* perspective: - -. Initially, all metrics from all enabled queries are shown on the plot. You can select which metrics are shown. -+ -[NOTE] -==== -By default, the query table shows an expanded view that lists every metric and its current value. You can select *˅* to minimize the expanded view for a query. -==== - -* To hide all metrics from a query, click {kebab} for the query and click *Hide all series*. - -* To hide a specific metric, go to the query table and click the colored square near the metric name. - -. To zoom into the plot and change the time range, do one of the following: - -* Visually select the time range by clicking and dragging on the plot horizontally. - -* Use the menu in the left upper corner to select the time range. - -. To reset the time range, select *Reset Zoom*. - -. To display outputs for all queries at a specific point in time, hold the mouse cursor on the plot at that point. The query outputs will appear in a pop-up box. - -. To hide the plot, select *Hide Graph*. - -In the *Developer* perspective: - -. To zoom into the plot and change the time range, do one of the following: - -* Visually select the time range by clicking and dragging on the plot horizontally. - -* Use the menu in the left upper corner to select the time range. - -. To reset the time range, select *Reset Zoom*. - -. To display outputs for all queries at a specific point in time, hold the mouse cursor on the plot at that point. The query outputs will appear in a pop-up box. diff --git a/modules/monitoring-exposing-custom-application-metrics-for-horizontal-pod-autoscaling.adoc b/modules/monitoring-exposing-custom-application-metrics-for-horizontal-pod-autoscaling.adoc deleted file mode 100644 index e57f7e9ba647..000000000000 --- a/modules/monitoring-exposing-custom-application-metrics-for-horizontal-pod-autoscaling.adoc +++ /dev/null @@ -1,277 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/application-monitoring.adoc -// * monitoring/exposing-custom-application-metrics-for-autoscaling.adoc - -[id="exposing-custom-application-metrics-for-horizontal-pod-autoscaling_{context}"] -= Exposing custom application metrics for horizontal pod autoscaling - -You can use the `prometheus-adapter` resource to expose custom application metrics for the horizontal pod autoscaler. - -.Prerequisites - -* You have a custom Prometheus instance installed. In this example, it is presumed that Prometheus was installed in a user-defined `custom-prometheus` project. -+ -[NOTE] -==== -Custom Prometheus instances and the Prometheus Operator installed through Operator Lifecycle Manager (OLM) can cause issues with user-defined workload monitoring if it is enabled. Custom Prometheus instances are not supported in {product-title}. -==== -+ -* You have deployed an application and a service in a user-defined project. In this example, it is presumed that the application and its service monitor were installed in a user-defined `custom-prometheus` project. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Create a YAML file for your configuration. In this example, the file is called `deploy.yaml`. - -. Add configuration details for creating the service account, roles, and role bindings for `prometheus-adapter`: -+ -[source,yaml,subs=quotes] ----- -kind: ServiceAccount -apiVersion: v1 -metadata: - name: custom-metrics-apiserver - namespace: custom-prometheus ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: custom-metrics-server-resources -rules: -- apiGroups: - - custom.metrics.k8s.io - resources: ["\*"] - verbs: ["*"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: custom-metrics-resource-reader -rules: -- apiGroups: - - "" - resources: - - namespaces - - pods - - services - verbs: - - get - - list ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: custom-metrics:system:auth-delegator -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: system:auth-delegator -subjects: -- kind: ServiceAccount - name: custom-metrics-apiserver - namespace: custom-prometheus ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: custom-metrics-auth-reader - namespace: kube-system -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: extension-apiserver-authentication-reader -subjects: -- kind: ServiceAccount - name: custom-metrics-apiserver - namespace: custom-prometheus ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: custom-metrics-resource-reader -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: custom-metrics-resource-reader -subjects: -- kind: ServiceAccount - name: custom-metrics-apiserver - namespace: custom-prometheus ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: hpa-controller-custom-metrics -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: custom-metrics-server-resources -subjects: -- kind: ServiceAccount - name: horizontal-pod-autoscaler - namespace: kube-system ---- ----- - -. Add configuration details for the custom metrics for `prometheus-adapter`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: adapter-config - namespace: custom-prometheus -data: - config.yaml: | - rules: - - seriesQuery: 'http_requests_total{namespace!="",pod!=""}' <1> - resources: - overrides: - namespace: {resource: "namespace"} - pod: {resource: "pod"} - service: {resource: "service"} - name: - matches: "^(.*)_total" - as: "${1}_per_second" <2> - metricsQuery: 'sum(rate(<<.Series>>{<<.LabelMatchers>>}[2m])) by (<<.GroupBy>>)' ---- ----- -<1> Specifies the chosen metric to be the number of HTTP requests. -<2> Specifies the frequency for the metric. - -. Add configuration details for registering `prometheus-adapter` as an API service: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: Service -metadata: - annotations: - service.alpha.openshift.io/serving-cert-secret-name: prometheus-adapter-tls - labels: - name: prometheus-adapter - name: prometheus-adapter - namespace: custom-prometheus -spec: - ports: - - name: https - port: 443 - targetPort: 6443 - selector: - app: prometheus-adapter - type: ClusterIP ---- -apiVersion: apiregistration.k8s.io/v1beta1 -kind: APIService -metadata: - name: v1beta1.custom.metrics.k8s.io -spec: - service: - name: prometheus-adapter - namespace: custom-prometheus - group: custom.metrics.k8s.io - version: v1beta1 - insecureSkipTLSVerify: true - groupPriorityMinimum: 100 - versionPriority: 100 ---- ----- - -. List the Prometheus Adapter image: -+ -[source,terminal] ----- -$ oc get -n openshift-monitoring deploy/prometheus-adapter -o jsonpath="{..image}" ----- - -. Add configuration details for deploying `prometheus-adapter`: -+ -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - app: prometheus-adapter - name: prometheus-adapter - namespace: custom-prometheus -spec: - replicas: 1 - selector: - matchLabels: - app: prometheus-adapter - template: - metadata: - labels: - app: prometheus-adapter - name: prometheus-adapter - spec: - serviceAccountName: custom-metrics-apiserver - containers: - - name: prometheus-adapter - image: quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:a46915a206cd7d97f240687c618dd59e8848fcc3a0f51e281f3384153a12c3e0 <1> - args: - - --secure-port=6443 - - --tls-cert-file=/var/run/serving-cert/tls.crt - - --tls-private-key-file=/var/run/serving-cert/tls.key - - --logtostderr=true - - --prometheus-url=http://prometheus-operated.default.svc:9090/ - - --metrics-relist-interval=1m - - --v=4 - - --config=/etc/adapter/config.yaml - ports: - - containerPort: 6443 - volumeMounts: - - mountPath: /var/run/serving-cert - name: volume-serving-cert - readOnly: true - - mountPath: /etc/adapter/ - name: config - readOnly: true - - mountPath: /tmp - name: tmp-vol - volumes: - - name: volume-serving-cert - secret: - secretName: prometheus-adapter-tls - - name: config - configMap: - name: adapter-config - - name: tmp-vol - emptyDir: {} ----- -<1> Specifies the Prometheus Adapter image found in the previous step. - -. Apply the configuration to the cluster: -+ -[source,terminal] ----- -$ oc apply -f deploy.yaml ----- -+ -.Example output -[source,terminal] ----- -serviceaccount/custom-metrics-apiserver created -clusterrole.rbac.authorization.k8s.io/custom-metrics-server-resources created -clusterrole.rbac.authorization.k8s.io/custom-metrics-resource-reader created -clusterrolebinding.rbac.authorization.k8s.io/custom-metrics:system:auth-delegator created -rolebinding.rbac.authorization.k8s.io/custom-metrics-auth-reader created -clusterrolebinding.rbac.authorization.k8s.io/custom-metrics-resource-reader created -clusterrolebinding.rbac.authorization.k8s.io/hpa-controller-custom-metrics created -configmap/adapter-config created -service/prometheus-adapter created -apiservice.apiregistration.k8s.io/v1.custom.metrics.k8s.io created -deployment.apps/prometheus-adapter created ----- - -. Verify that the `prometheus-adapter` pod in your user-defined project is in a `Running` state. In this example the project is `custom-prometheus`: -+ -[source,terminal] ----- -$ oc -n custom-prometheus get pods prometheus-adapter-<string> ----- - -. The metrics for the application are now exposed and they can be used to configure horizontal pod autoscaling. diff --git a/modules/monitoring-getting-information-about-alerts-silences-and-alerting-rules.adoc b/modules/monitoring-getting-information-about-alerts-silences-and-alerting-rules.adoc deleted file mode 100644 index 6b2ae9400783..000000000000 --- a/modules/monitoring-getting-information-about-alerts-silences-and-alerting-rules.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="getting-information-about-alerts-silences-and-alerting-rules_{context}"] -= Getting information about alerts, silences, and alerting rules - -The Alerting UI provides detailed information about alerts and their governing alerting rules and silences. - -.Prerequisites - -* You have access to the cluster as a developer or as a user with view permissions for the project that you are viewing metrics for. - -.Procedure - -*To obtain information about alerts in the Administrator perspective*: - -. Open the {product-title} web console and navigate to the *Monitoring* -> *Alerting* -> *Alerts* page. - -. Optional: Search for alerts by name using the *Name* field in the search list. - -. Optional: Filter alerts by state, severity, and source by selecting filters in the *Filter* list. - -. Optional: Sort the alerts by clicking one or more of the *Name*, *Severity*, *State*, and *Source* column headers. - -. Select the name of an alert to navigate to its *Alert Details* page. The page includes a graph that illustrates alert time series data. It also provides information about the alert, including: -+ --- -** A description of the alert -** Messages associated with the alerts -** Labels attached to the alert -** A link to its governing alerting rule -** Silences for the alert, if any exist --- - -*To obtain information about silences in the Administrator perspective*: - -. Navigate to the *Monitoring* -> *Alerting* -> *Silences* page. - -. Optional: Filter the silences by name using the *Search by name* field. - -. Optional: Filter silences by state by selecting filters in the *Filter* list. By default, *Active* and *Pending* filters are applied. - -. Optional: Sort the silences by clicking one or more of the *Name*, *Firing Alerts*, and *State* column headers. - -. Select the name of a silence to navigate to its *Silence Details* page. The page includes the following details: -+ --- -* Alert specification -* Start time -* End time -* Silence state -* Number and list of firing alerts --- - -*To obtain information about alerting rules in the Administrator perspective*: - -. Navigate to the *Monitoring* -> *Alerting* -> *Alerting Rules* page. - -. Optional: Filter alerting rules by state, severity, and source by selecting filters in the *Filter* list. - -. Optional: Sort the alerting rules by clicking one or more of the *Name*, *Severity*, *Alert State*, and *Source* column headers. - -. Select the name of an alerting rule to navigate to its *Alerting Rule Details* page. The page provides the following details about the alerting rule: -+ --- -** Alerting rule name, severity, and description -** The expression that defines the condition for firing the alert -** The time for which the condition should be true for an alert to fire -** A graph for each alert governed by the alerting rule, showing the value with which the alert is firing -** A table of all alerts governed by the alerting rule --- - -*To obtain information about alerts, silences, and alerting rules in the Developer perspective*: - -. Navigate to the *Monitoring* -> *<project_name>* -> *Alerts* page. - -. View details for an alert, silence, or an alerting rule: - -* *Alert Details* can be viewed by selecting *>* to the left of an alert name and then selecting the alert in the list. - -* *Silence Details* can be viewed by selecting a silence in the *Silenced By* section of the *Alert Details* page. The *Silence Details* page includes the following information: -+ --- -* Alert specification -* Start time -* End time -* Silence state -* Number and list of firing alerts --- - -* *Alerting Rule Details* can be viewed by selecting *View Alerting Rule* in the {kebab} menu on the right of an alert in the *Alerts* page. - -[NOTE] -==== -Only alerts, silences, and alerting rules relating to the selected project are displayed in the *Developer* perspective. -==== diff --git a/modules/monitoring-granting-user-permissions-using-the-cli.adoc b/modules/monitoring-granting-user-permissions-using-the-cli.adoc deleted file mode 100644 index 0848f386a9e7..000000000000 --- a/modules/monitoring-granting-user-permissions-using-the-cli.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/enabling-monitoring-for-user-defined-projects.adoc - -[id="granting-user-permissions-using-the-cli_{context}"] -= Granting user permissions by using the CLI - -You can grant users permissions to monitor their own projects, by using the OpenShift CLI (`oc`). - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* The user account that you are assigning the role to already exists. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -* Assign a monitoring role to a user for a project: -+ -[source,terminal] ----- -$ oc policy add-role-to-user <role> <user> -n <namespace> <1> ----- -<1> Substitute `<role>` with `monitoring-rules-view`, `monitoring-rules-edit`, or `monitoring-edit`. -+ -[IMPORTANT] -==== -Whichever role you choose, you must bind it against a specific project as a cluster administrator. -==== -+ -As an example, substitute `<role>` with `monitoring-edit`, `<user>` with `johnsmith`, and `<namespace>` with `ns1`. This assigns the user `johnsmith` permission to set up metrics collection and to create alerting rules in the `ns1` namespace. diff --git a/modules/monitoring-granting-user-permissions-using-the-web-console.adoc b/modules/monitoring-granting-user-permissions-using-the-web-console.adoc deleted file mode 100644 index 589d642a98c1..000000000000 --- a/modules/monitoring-granting-user-permissions-using-the-web-console.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/enabling-monitoring-for-user-defined-projects.adoc - -[id="granting-user-permissions-using-the-web-console_{context}"] -= Granting user permissions by using the web console - -You can grant users permissions to monitor their own projects, by using the {product-title} web console. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* The user account that you are assigning the role to already exists. - -.Procedure - -. In the *Administrator* perspective within the {product-title} web console, navigate to *User Management* -> *Role Bindings* -> *Create Binding*. - -. In the *Binding Type* section, select the "Namespace Role Binding" type. - -. In the *Name* field, enter a name for the role binding. - -. In the *Namespace* field, select the user-defined project where you want to grant the access. -+ -[IMPORTANT] -==== -The monitoring role will be bound to the project that you apply in the *Namespace* field. The permissions that you grant to a user by using this procedure will apply only to the selected project. -==== - -. Select `monitoring-rules-view`, `monitoring-rules-edit`, or `monitoring-edit` in the *Role Name* list. - -. In the *Subject* section, select *User*. - -. In the *Subject Name* field, enter the name of the user. - -. Select *Create* to apply the role binding. diff --git a/modules/monitoring-granting-users-permission-to-configure-monitoring-for-user-defined-projects.adoc b/modules/monitoring-granting-users-permission-to-configure-monitoring-for-user-defined-projects.adoc deleted file mode 100644 index 85c54d6e235b..000000000000 --- a/modules/monitoring-granting-users-permission-to-configure-monitoring-for-user-defined-projects.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/enabling-monitoring-for-user-defined-projects.adoc - -[id="granting-users-permission-to-configure-monitoring-for-user-defined-projects_{context}"] -= Granting users permission to configure monitoring for user-defined projects - -You can grant users permission to configure monitoring for user-defined projects. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* The user account that you are assigning the role to already exists. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -* Assign the `user-workload-monitoring-config-edit` role to a user in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring adm policy add-role-to-user \ - user-workload-monitoring-config-edit <user> \ - --role-namespace openshift-user-workload-monitoring ----- diff --git a/modules/monitoring-granting-users-permission-to-monitor-user-defined-projects.adoc b/modules/monitoring-granting-users-permission-to-monitor-user-defined-projects.adoc deleted file mode 100644 index f649435b1d86..000000000000 --- a/modules/monitoring-granting-users-permission-to-monitor-user-defined-projects.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/enabling-monitoring-for-user-defined-projects.adoc - -[id="granting-users-permission-to-monitor-user-defined-projects_{context}"] -= Granting users permission to monitor user-defined projects - -Cluster administrators can monitor all core {product-title} and user-defined projects. - -Cluster administrators can grant developers and other users permission to monitor their own projects. Privileges are granted by assigning one of the following monitoring roles: - -* The *monitoring-rules-view* role provides read access to `PrometheusRule` custom resources for a project. - -* The *monitoring-rules-edit* role grants a user permission to create, modify, and deleting `PrometheusRule` custom resources for a project. - -* The *monitoring-edit* role grants the same privileges as the `monitoring-rules-edit` role. Additionally, it enables a user to create new scrape targets for services or pods. With this role, you can also create, modify, and delete `ServiceMonitor` and `PodMonitor` resources. - -You can also grant users permission to configure the components that are responsible for monitoring user-defined projects: - -* The *user-workload-monitoring-config-edit* role in the `openshift-user-workload-monitoring` project enables you to edit the `user-workload-monitoring-config` `ConfigMap` object. With this role, you can edit the `ConfigMap` object to configure Prometheus, Prometheus Operator and Thanos Ruler for user-defined workload monitoring. - -This section provides details on how to assign these roles by using the {product-title} web console or the CLI. diff --git a/modules/monitoring-installation-progress.adoc b/modules/monitoring-installation-progress.adoc deleted file mode 100644 index 33f8e6c6e4ab..000000000000 --- a/modules/monitoring-installation-progress.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="monitoring-installation-progress_{context}"] -= Monitoring installation progress - -You can monitor high-level installation, bootstrap, and control plane logs as an {product-title} installation progresses. This provides greater visibility into how an installation progresses and helps identify the stage at which an installation failure occurs. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have SSH access to your hosts. -* You have the fully qualified domain names of the bootstrap and master nodes. -+ -[NOTE] -==== -The initial `kubeadmin` password can be found in `<install_directory>/auth/kubeadmin-password` on the installation host. -==== - -.Procedure - -. Watch the installation log as the installation progresses: -+ -[source,terminal] ----- -$ tail -f ~/<installation_directory>/.openshift_install.log ----- - -. Monitor the `bootkube.service` journald unit log on the bootstrap node, after it has booted. This provides visibility into the bootstrapping of the first control plane. Replace `<bootstrap_fqdn>` with the bootstrap node's fully qualified domain name: -+ -[source,terminal] ----- -$ ssh core@<bootstrap_fqdn> journalctl -b -f -u bootkube.service ----- -+ -[NOTE] -==== -The `bootkube.service` log on the bootstrap node outputs etcd `connection refused` errors, indicating that the bootstrap server is unable to connect to etcd on master nodes. After etcd has started on each master node and the nodes have joined the cluster, the errors should stop. -==== -+ -. Monitor `kubelet.service` journald unit logs on master nodes, after they have booted. This provides visibility into master node agent activity. -.. Monitor the logs using `oc`: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u kubelet ----- -.. If the API is not functional, review the logs using SSH instead. Replace `<master-node>.<cluster_name>.<base_domain>` with appropriate values: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> journalctl -b -f -u kubelet.service ----- - -. Monitor `crio.service` journald unit logs on master nodes, after they have booted. This provides visibility into master node CRI-O container runtime activity. -.. Monitor the logs using `oc`: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u crio ----- -+ -.. If the API is not functional, review the logs using SSH instead. Replace `<master-node>.<cluster_name>.<base_domain>` with appropriate values: -+ -[source,terminal] ----- -$ ssh core@master-N.cluster_name.sub_domain.domain journalctl -b -f -u crio.service ----- diff --git a/modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc b/modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc deleted file mode 100644 index dd6baa16b25a..000000000000 --- a/modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc +++ /dev/null @@ -1,160 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/troubleshooting-monitoring-issues.adoc -// * support/troubleshooting/investigating-monitoring-issues.adoc - -[id="investigating-why-user-defined-metrics-are-unavailable_{context}"] -= Investigating why user-defined metrics are unavailable - -`ServiceMonitor` resources enable you to determine how to use the metrics exposed by a service in user-defined projects. Follow the steps outlined in this procedure if you have created a `ServiceMonitor` resource but cannot see any corresponding metrics in the Metrics UI. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have enabled and configured monitoring for user-defined workloads. -* You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have created a `ServiceMonitor` resource. - -.Procedure - -. *Check that the corresponding labels match* in the service and `ServiceMonitor` resource configurations. -.. Obtain the label defined in the service. The following example queries the `prometheus-example-app` service in the `ns1` project: -+ -[source,terminal] ----- -$ oc -n ns1 get service prometheus-example-app -o yaml ----- -+ -.Example output -[source,terminal] ----- - labels: - app: prometheus-example-app ----- -+ -.. Check that the `matchLabels` `app` label in the `ServiceMonitor` resource configuration matches the label output in the preceding step: -+ -[source,terminal] ----- -$ oc -n ns1 get servicemonitor prometheus-example-monitor -o yaml ----- -+ -.Example output ----- -spec: - endpoints: - - interval: 30s - port: web - scheme: http - selector: - matchLabels: - app: prometheus-example-app ----- -+ -[NOTE] -==== -You can check service and `ServiceMonitor` resource labels as a developer with view permissions for the project. -==== - -. *Inspect the logs for the Prometheus Operator* in the `openshift-user-workload-monitoring` project. -.. List the pods in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -prometheus-operator-776fcbbd56-2nbfm 2/2 Running 0 132m -prometheus-user-workload-0 5/5 Running 1 132m -prometheus-user-workload-1 5/5 Running 1 132m -thanos-ruler-user-workload-0 3/3 Running 0 132m -thanos-ruler-user-workload-1 3/3 Running 0 132m ----- -+ -.. Obtain the logs from the `prometheus-operator` container in the `prometheus-operator` pod. In the following example, the pod is called `prometheus-operator-776fcbbd56-2nbfm`: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring logs prometheus-operator-776fcbbd56-2nbfm -c prometheus-operator ----- -+ -If there is a issue with the service monitor, the logs might include an error similar to this example: -+ -[source,terminal] ----- -level=warn ts=2020-08-10T11:48:20.906739623Z caller=operator.go:1829 component=prometheusoperator msg="skipping servicemonitor" error="it accesses file system via bearer token file which Prometheus specification prohibits" servicemonitor=eagle/eagle namespace=openshift-user-workload-monitoring prometheus=user-workload ----- - -. *Review the target status for your project* in the Prometheus UI directly. -.. Establish port-forwarding to the Prometheus instance in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc port-forward -n openshift-user-workload-monitoring pod/prometheus-user-workload-0 9090 ----- -+ -.. Open http://localhost:9090/targets in a web browser and review the status of the target for your project directly in the Prometheus UI. Check for error messages relating to the target. - -. *Configure debug level logging for the Prometheus Operator* in the `openshift-user-workload-monitoring` project. -.. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- -+ -.. Add `logLevel: debug` for `prometheusOperator` under `data/config.yaml` to set the log level to `debug`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - prometheusOperator: - logLevel: debug ----- -+ -.. Save the file to apply the changes. -+ -[NOTE] -==== -The `prometheus-operator` in the `openshift-user-workload-monitoring` project restarts automatically when you apply the log-level change. -==== -+ -.. Confirm that the `debug` log-level has been applied to the `prometheus-operator` deployment in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring get deploy prometheus-operator -o yaml | grep "log-level" ----- -+ -.Example output -[source,terminal] ----- - - --log-level=debug ----- -+ -Debug level logging will show all calls made by the Prometheus Operator. -+ -.. Check that the `prometheus-operator` pod is running: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring get pods ----- -+ -[NOTE] -==== -If an unrecognized Prometheus Operator `loglevel` value is included in the config map, the `prometheus-operator` pod might not restart successfully. -==== -+ -.. Review the debug logs to see if the Prometheus Operator is using the `ServiceMonitor` resource. Review the logs for other related errors. diff --git a/modules/monitoring-limiting-scrape-samples-in-user-defined-projects.adoc b/modules/monitoring-limiting-scrape-samples-in-user-defined-projects.adoc deleted file mode 100644 index a757f89b2dba..000000000000 --- a/modules/monitoring-limiting-scrape-samples-in-user-defined-projects.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="controlling-the-impact-of-unbound-attributes-in-user-defined-projects_{context}"] -= Controlling the impact of unbound metrics attributes in user-defined projects - -Developers can create labels to define attributes for metrics in the form of key-value pairs. The number of potential key-value pairs corresponds to the number of possible values for an attribute. An attribute that has an unlimited number of potential values is called an unbound attribute. For example, a `customer_id` attribute is unbound because it has an infinite number of possible values. - -Every assigned key-value pair has a unique time series. The use of many unbound attributes in labels can result in an exponential increase in the number of time series created. This can impact Prometheus performance and can consume a lot of disk space. - -Cluster administrators can use the following measures to control the impact of unbound metrics attributes in user-defined projects: - -* *Limit the number of samples that can be accepted* per target scrape in user-defined projects -* *Create alerts* that fire when a scrape sample threshold is reached or when the target cannot be scraped - -[NOTE] -==== -Limiting scrape samples can help prevent the issues caused by adding many unbound attributes to labels. Developers can also prevent the underlying cause by limiting the number of unbound attributes that they define for metrics. Using attributes that are bound to a limited set of possible values reduces the number of potential key-value pair combinations. -==== diff --git a/modules/monitoring-listing-alerting-rules-for-all-projects-in-a-single-view.adoc b/modules/monitoring-listing-alerting-rules-for-all-projects-in-a-single-view.adoc deleted file mode 100644 index 5c10dbdfaa0d..000000000000 --- a/modules/monitoring-listing-alerting-rules-for-all-projects-in-a-single-view.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="listing-alerting-rules-for-all-projects-in-a-single-view_{context}"] -= Listing alerting rules for all projects in a single view - -As a cluster administrator, you can list alerting rules for core {product-title} and user-defined projects together in a single view. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. In the *Administrator* perspective, navigate to *Monitoring* -> *Alerting* -> *Alerting Rules*. - -. Select the *Platform* and *User* sources in the *Filter* drop-down menu. -+ -[NOTE] -==== -The *Platform* source is selected by default. -==== diff --git a/modules/monitoring-maintenance-and-support.adoc b/modules/monitoring-maintenance-and-support.adoc deleted file mode 100644 index 92eeba9c4ca6..000000000000 --- a/modules/monitoring-maintenance-and-support.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="maintenance-and-support_{context}"] -= Maintenance and support for monitoring - -The supported way of configuring {product-title} Monitoring is by configuring it using the options described in this document. *Do not use other configurations, as they are unsupported.* Configuration paradigms might change across Prometheus releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use configurations other than those described in this section, your changes will disappear because the `cluster-monitoring-operator` reconciles any differences. The Operator resets everything to the defined state by default and by design. diff --git a/modules/monitoring-managing-alerting-rules.adoc b/modules/monitoring-managing-alerting-rules.adoc deleted file mode 100644 index aab1dbfd4e2b..000000000000 --- a/modules/monitoring-managing-alerting-rules.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="managing-alerting-rules_{context}"] -= Managing alerting rules - -{product-title} monitoring ships with a set of default alerting rules. As a cluster administrator, you can view the default alerting rules. - -In {product-title} {product-version}, you can create, view, edit, and remove alerting rules in user-defined projects. - -.Alerting rule considerations - -* The default alerting rules are used specifically for the {product-title} cluster. - -* Some alerting rules intentionally have identical names. They send alerts about the same event with different thresholds, different severity, or both. - -* Inhibition rules prevent notifications for lower severity alerts that are firing when a higher severity alert is also firing. diff --git a/modules/monitoring-managing-silences.adoc b/modules/monitoring-managing-silences.adoc deleted file mode 100644 index 00a4c6b0fe52..000000000000 --- a/modules/monitoring-managing-silences.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="managing-silences_{context}"] -= Managing silences - -You can create a silence to stop receiving notifications about an alert when it is firing. It might be useful to silence an alert after being first notified, while you resolve the underlying issue. - -When creating a silence, you must specify whether it becomes active immediately or at a later time. You must also set a duration period after which the silence expires. - -You can view, edit, and expire existing silences. diff --git a/modules/monitoring-modifying-retention-time-for-prometheus-metrics-data.adoc b/modules/monitoring-modifying-retention-time-for-prometheus-metrics-data.adoc deleted file mode 100644 index 7293dec5fbe9..000000000000 --- a/modules/monitoring-modifying-retention-time-for-prometheus-metrics-data.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="modifying-retention-time-for-prometheus-metrics-data_{context}"] -= Modifying the retention time for Prometheus metrics data - -By default, the {product-title} monitoring stack configures the retention time for Prometheus data to be 15 days. You can modify the retention time to change how soon the data is deleted. - -.Prerequisites - -* *If you are configuring core {product-title} monitoring components*: -** You have access to the cluster as a user with the `cluster-admin` role. -** You have created the `cluster-monitoring-config` `ConfigMap` object. -* *If you are configuring components that monitor user-defined projects*: -** You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -** You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `ConfigMap` object: -** *To modify the retention time for the Prometheus instance that monitors core {product-title} projects*: -.. Edit the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -.. Add your retention time configuration under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - prometheusK8s: - retention: <time_specification> ----- -+ -Substitute `<time_specification>` with a number directly followed by `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), or `y` (years). -+ -The following example sets the retention time to 24 hours for the Prometheus instance that monitors core {product-title} components: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - prometheusK8s: - retention: *24h* ----- - -** *To modify the retention time for the Prometheus instance that monitors user-defined projects*: -.. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- - -.. Add your retention time configuration under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - prometheus: - retention: <time_specification> ----- -+ -Substitute `<time_specification>` with a number directly followed by `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), or `y` (years). -+ -The following example sets the retention time to 24 hours for the Prometheus instance that monitors user-defined projects: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - prometheus: - retention: *24h* ----- - -. Save the file to apply the changes. The pods affected by the new configuration are restarted automatically. -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== -+ -[WARNING] -==== -When changes are saved to a monitoring config map, the pods and other resources in the related project might be redeployed. The running monitoring processes in that project might also be restarted. -==== diff --git a/modules/monitoring-moving-monitoring-components-to-different-nodes.adoc b/modules/monitoring-moving-monitoring-components-to-different-nodes.adoc deleted file mode 100644 index 0d2257ef338a..000000000000 --- a/modules/monitoring-moving-monitoring-components-to-different-nodes.adoc +++ /dev/null @@ -1,181 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="moving-monitoring-components-to-different-nodes_{context}"] -= Moving monitoring components to different nodes - -You can move any of the monitoring stack components to specific nodes. - -.Prerequisites - -* *If you are configuring core {product-title} monitoring components*: -** You have access to the cluster as a user with the `cluster-admin` role. -** You have created the `cluster-monitoring-config` `ConfigMap` object. -* *If you are configuring components that monitor user-defined projects*: -** You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -** You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `ConfigMap` object: -** *To move a component that monitors core {product-title} projects*: -.. Edit the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -.. Specify the `nodeSelector` constraint for the component under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - <component>: - nodeSelector: - <node_key>: <node_value> - <node_key>: <node_value> - <...> ----- -+ -Substitute `<component>` accordingly and substitute `<node_key>: <node_value>` with the map of key-value pairs that specifies a group of destination nodes. Often, only a single key-value pair is used. -+ -The component can only run on nodes that have each of the specified key-value pairs as labels. The nodes can have additional labels as well. -+ -[IMPORTANT] -==== -Many of the monitoring components are deployed by using multiple pods across different nodes in the cluster to maintain high availability. When moving monitoring components to labeled nodes, ensure that enough matching nodes are available to maintain resilience for the component. If only one label is specified, ensure that enough nodes contain that label to distribute all of the pods for the component across separate nodes. Alternatively, you can specify multiple labels each relating to individual nodes. -==== -+ -[NOTE] -==== -If monitoring components remain in a `Pending` state after configuring the `nodeSelector` constraint, check the pod logs for errors relating to taints and tolerations. -==== -+ -For example, to move monitoring components for core {product-title} projects to specific nodes that are labeled `nodename: controlplane1`, `nodename: worker1`, `nodename: worker2`, and `nodename: worker2`, use: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - prometheusOperator: - nodeSelector: - nodename: controlplane1 - prometheusK8s: - nodeSelector: - nodename: worker1 - nodename: worker2 - alertmanagerMain: - nodeSelector: - nodename: worker1 - nodename: worker2 - kubeStateMetrics: - nodeSelector: - nodename: worker1 - grafana: - nodeSelector: - nodename: worker1 - telemeterClient: - nodeSelector: - nodename: worker1 - k8sPrometheusAdapter: - nodeSelector: - nodename: worker1 - nodename: worker2 - openshiftStateMetrics: - nodeSelector: - nodename: worker1 - thanosQuerier: - nodeSelector: - nodename: worker1 - nodename: worker2 ----- - -** *To move a component that monitors user-defined projects*: -.. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- - -.. Specify the `nodeSelector` constraint for the component under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - <component>: - nodeSelector: - <node_key>: <node_value> - <node_key>: <node_value> - <...> ----- -+ -Substitute `<component>` accordingly and substitute `<node_key>: <node_value>` with the map of key-value pairs that specifies the destination nodes. Often, only a single key-value pair is used. -+ -The component can only run on nodes that have each of the specified key-value pairs as labels. The nodes can have additional labels as well. -+ -[IMPORTANT] -==== -Many of the monitoring components are deployed by using multiple pods across different nodes in the cluster to maintain high availability. When moving monitoring components to labeled nodes, ensure that enough matching nodes are available to maintain resilience for the component. If only one label is specified, ensure that enough nodes contain that label to distribute all of the pods for the component across separate nodes. Alternatively, you can specify multiple labels each relating to individual nodes. -==== -+ -[NOTE] -==== -If monitoring components remain in a `Pending` state after configuring the `nodeSelector` constraint, check the pod logs for errors relating to taints and tolerations. -==== -+ -For example, to move monitoring components for user-defined projects to specific worker nodes labeled `nodename: worker1`, `nodename: worker2`, and `nodename: worker2`, use: -+ -[source,yaml,subs=quotes] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - prometheusOperator: - nodeSelector: - nodename: worker1 - prometheus: - nodeSelector: - nodename: worker1 - nodename: worker2 - thanosRuler: - nodeSelector: - nodename: worker1 - nodename: worker2 ----- - -. Save the file to apply the changes. The components affected by the new configuration are moved to the new nodes automatically. -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== -+ -[WARNING] -==== -When changes are saved to a monitoring config map, the pods and other resources in the related project might be redeployed. The running monitoring processes in that project might also be restarted. -==== diff --git a/modules/monitoring-optimizing-alerting-for-user-defined-projects.adoc b/modules/monitoring-optimizing-alerting-for-user-defined-projects.adoc deleted file mode 100644 index 10c57e5d9cc9..000000000000 --- a/modules/monitoring-optimizing-alerting-for-user-defined-projects.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="Optimizing-alerting-for-user-defined-projects_{context}"] -= Optimizing alerting for user-defined projects - -You can optimize alerting for your own projects by considering the following recommendations when creating alerting rules: - -* *Minimize the number of alerting rules that you create for your project*. Create alerting rules that notify you of conditions that impact you. It is more difficult to notice relevant alerts if you generate many alerts for conditions that do not impact you. - -* *Create alerting rules for symptoms instead of causes*. Create alerting rules that notify you of conditions regardless of the underlying cause. The cause can then be investigated. You will need many more alerting rules if each relates only to a specific cause. Some causes are then likely to be missed. - -* *Plan before you write your alerting rules*. Determine what symptoms are important to you and what actions you want to take if they occur. Then build an alerting rule for each symptom. - -* *Provide clear alert messaging*. State the symptom and recommended actions in the alert message. - -* *Include severity levels in your alerting rules*. The severity of an alert depends on how you need to react if the reported symptom occurs. For example, a critical alert should be triggered if a symptom requires immediate attention by an individual or a critical response team. - -* *Optimize alert routing*. Deploy an alerting rule directly on the Prometheus instance in the `openshift-user-workload-monitoring` project if the rule does not query default {product-title} metrics. This reduces latency for alerting rules and minimizes the load on monitoring components. -+ -[WARNING] -==== -Default {product-title} metrics for user-defined projects provide information about CPU and memory usage, bandwidth statistics, and packet rate information. Those metrics cannot be included in an alerting rule if you route the rule directly to the Prometheus instance in the `openshift-user-workload-monitoring` project. Alerting rule optimization should be used only if you have read the documentation and have a comprehensive understanding of the monitoring architecture. -==== diff --git a/modules/monitoring-osp.adoc b/modules/monitoring-osp.adoc new file mode 100644 index 000000000000..36c35bfa94a4 --- /dev/null +++ b/modules/monitoring-osp.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * configuration/monitor-acs.adoc +:_mod-docs-content-type: CONCEPT +[id="monitoring-osp_{context}"] += Monitoring with {osp} + +Monitoring with {osp} is enabled by default. No configuration is required for this default behavior. + +[IMPORTANT] +==== +If you have previously configured monitoring with the Prometheus Operator, consider removing your custom `ServiceMonitor` resources. {product-title-short} ships with a pre-configured `ServiceMonitor` for {osp} monitoring. Multiple `ServiceMonitors` might result in duplicated scraping. +==== + +Monitoring with {osp} is not supported by Scanner. If you want to monitor Scanner, you must first disable the default {osp} monitoring. Then, configure custom Prometheus monitoring. + +For more information on disabling {osp} monitoring, see "Disabling {osp} monitoring for Central services by using the {product-title-short} Operator" or "Disabling {osp} monitoring for Central services by using Helm". For more information on configuring Prometheus, see "Monitoring with custom Prometheus". \ No newline at end of file diff --git a/modules/monitoring-querying-metrics-for-all-projects-as-an-administrator.adoc b/modules/monitoring-querying-metrics-for-all-projects-as-an-administrator.adoc deleted file mode 100644 index 9467199c1984..000000000000 --- a/modules/monitoring-querying-metrics-for-all-projects-as-an-administrator.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="querying-metrics-for-all-projects-as-an-administrator_{context}"] -= Querying metrics for all projects as a cluster administrator - -As a cluster administrator or as a user with view permissions for all projects, you can access metrics for all default {product-title} and user-defined projects in the Metrics UI. - -[NOTE] -==== -Only cluster administrators have access to the third-party UIs provided with {product-title} Monitoring. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role or with view permissions for all projects. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. In the *Administrator* perspective within the {product-title} web console, select *Monitoring* -> *Metrics*. - -. Select *Insert Metric at Cursor* to view a list of predefined queries. - -. To create a custom query, add your Prometheus Query Language (PromQL) query to the *Expression* field. - -. To add multiple queries, select *Add Query*. - -. To delete a query, select {kebab} next to the query, then choose *Delete query*. - -. To disable a query from being run, select {kebab} next to the query and choose *Disable query*. - -. Select *Run Queries* to run the queries that you have created. The metrics from the queries are visualized on the plot. If a query is invalid, the UI shows an error message. -+ -[NOTE] -==== -Queries that operate on large amounts of data might time out or overload the browser when drawing time series graphs. To avoid this, select *Hide graph* and calibrate your query using only the metrics table. Then, after finding a feasible query, enable the plot to draw the graphs. -==== - -. Optional: The page URL now contains the queries you ran. To use this set of queries again in the future, save this URL. - -.Additional resources - -* See the link:https://prometheus.io/docs/prometheus/latest/querying/basics/[Prometheus query documentation] for more information about creating PromQL queries. diff --git a/modules/monitoring-querying-metrics-for-user-defined-projects-as-a-developer.adoc b/modules/monitoring-querying-metrics-for-user-defined-projects-as-a-developer.adoc deleted file mode 100644 index e166131d60ae..000000000000 --- a/modules/monitoring-querying-metrics-for-user-defined-projects-as-a-developer.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="querying-metrics-for-user-defined-projects-as-a-developer_{context}"] -= Querying metrics for user-defined projects as a developer - -You can access metrics for a user-defined project as a developer or as a user with view permissions for the project. - -In the *Developer* perspective, the Metrics UI includes some predefined CPU, memory, bandwidth, and network packet queries for the selected project. You can also run custom Prometheus Query Language (PromQL) queries for CPU, memory, bandwidth, network packet and application metrics for the project. - -[NOTE] -==== -Developers can only use the *Developer* perspective and not the *Administrator* perspective. As a developer you can only query metrics for one project at a time. Developers cannot access the third-party UIs provided with {product-title} monitoring. -==== - -.Prerequisites - -* You have access to the cluster as a developer or as a user with view permissions for the project that you are viewing metrics for. -* You have enabled monitoring for user-defined projects. -* You have deployed a service in a user-defined project. -* You have created a `ServiceMonitor` custom resource definition (CRD) for the service to define how the service is monitored. - -.Procedure - -. From the *Developer* perspective in the {product-title} web console, select *Monitoring* -> *Metrics*. - -. Select the project that you want to view metrics for in the *Project:* list. - -. Choose a query from the *Select Query* list, or run a custom PromQL query by selecting *Show PromQL*. -+ -[NOTE] -==== -In the *Developer* perspective, you can only run one query at a time. -==== - -.Additional resources - -* See the link:https://prometheus.io/docs/prometheus/latest/querying/basics/[Prometheus query documentation] for more information about creating PromQL queries. diff --git a/modules/monitoring-querying-metrics.adoc b/modules/monitoring-querying-metrics.adoc deleted file mode 100644 index b584d6e98ae1..000000000000 --- a/modules/monitoring-querying-metrics.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="querying-metrics_{context}"] -= Querying metrics - -The {product-title} monitoring dashboard enables you to run Prometheus Query Language (PromQL) queries to examine metrics visualized on a plot. This functionality provides information about the state of a cluster and any user-defined workloads that you are monitoring. - -As a *cluster administrator*, you can query metrics for all core {product-title} and user-defined projects. - -As a *developer*, you must specify a project name when querying metrics. You must have the required privileges to view metrics for the selected project. diff --git a/modules/monitoring-reducing-latency-for-alerting-rules-that-do-not-query-platform-metrics.adoc b/modules/monitoring-reducing-latency-for-alerting-rules-that-do-not-query-platform-metrics.adoc deleted file mode 100644 index 822fa03be851..000000000000 --- a/modules/monitoring-reducing-latency-for-alerting-rules-that-do-not-query-platform-metrics.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="reducing-latency-for-alerting-rules-that-do-not-query-platform-metrics_{context}"] -= Reducing latency for alerting rules that do not query platform metrics - -If an alerting rule for a user-defined project does not query default cluster metrics, you can deploy the rule directly on the Prometheus instance in the `openshift-user-workload-monitoring` project. This reduces latency for alerting rules by bypassing Thanos Ruler when it is not required. This also helps to minimize the overall load on monitoring components. - -[WARNING] -==== -Default {product-title} metrics for user-defined projects provide information about CPU and memory usage, bandwidth statistics, and packet rate information. Those metrics cannot be included in an alerting rule if you deploy the rule directly to the Prometheus instance in the `openshift-user-workload-monitoring` project. The procedure outlined in this section should only be used if you have read the documentation and have a comprehensive understanding of the monitoring architecture. -==== - -.Prerequisites - -* You have enabled monitoring for user-defined projects. -* You are logged in as a user that has the `monitoring-rules-edit` role for the project where you want to create an alerting rule. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Create a YAML file for alerting rules. In this example, it is called `example-app-alerting-rule.yaml`. - -. Add an alerting rule configuration to the YAML file that includes a label with the key `openshift.io/prometheus-rule-evaluation-scope` and value `leaf-prometheus`. For example: -+ -[source,yaml] ----- -apiVersion: monitoring.coreos.com/v1 -kind: PrometheusRule -metadata: - name: example-alert - namespace: ns1 - labels: - openshift.io/prometheus-rule-evaluation-scope: leaf-prometheus -spec: - groups: - - name: example - rules: - - alert: VersionAlert - expr: version{job="prometheus-example-app"} == 0 ----- - -If that label is present, the alerting rule is deployed on the Prometheus instance in the `openshift-user-workload-monitoring` project. If the label is not present, the alerting rule is deployed to Thanos Ruler. - -. Apply the configuration file to the cluster: -+ -[source,terminal] ----- -$ oc apply -f example-app-alerting-rule.yaml ----- -+ -It takes some time to create the alerting rule. diff --git a/modules/monitoring-removing-alerting-rules-for-user-defined-projects.adoc b/modules/monitoring-removing-alerting-rules-for-user-defined-projects.adoc deleted file mode 100644 index 188b7f2e588b..000000000000 --- a/modules/monitoring-removing-alerting-rules-for-user-defined-projects.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="removing-alerting-rules-for-user-defined-projects_{context}"] -= Removing alerting rules for user-defined projects - -You can remove alerting rules for user-defined projects. - -.Prerequisites - -* You have enabled monitoring for user-defined projects. -* You are logged in as a user that has the `monitoring-rules-edit` role for the project where you want to create an alerting rule. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -* To remove rule `<foo>` in `<namespace>`, run the following: -+ -[source,terminal] ----- -$ oc -n <namespace> delete prometheusrule <foo> ----- diff --git a/modules/monitoring-reviewing-monitoring-dashboards-admin.adoc b/modules/monitoring-reviewing-monitoring-dashboards-admin.adoc deleted file mode 100644 index ca3680235ac4..000000000000 --- a/modules/monitoring-reviewing-monitoring-dashboards-admin.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/reviewing-monitoring-dashboards.adoc - -[id="reviewing-monitoring-dashboards-admin_{context}"] -= Reviewing monitoring dashboards as a cluster administrator - -In the *Administrator* perspective, you can view dashboards relating to core {product-title} cluster components. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. In the *Administrator* perspective in the {product-title} web console, navigate to *Monitoring* -> *Dashboards*. - -. Choose a dashboard in the *Dashboard* list. Some dashboards, such as *etcd* and *Prometheus* dashboards, produce additional sub-menus when selected. - -. Optional: Select a time range for the graphs in the *Time Range* list. - -. Optional: Select a *Refresh Interval*. - -. Hover over each of the graphs within a dashboard to display detailed information about specific items. diff --git a/modules/monitoring-reviewing-monitoring-dashboards-developer.adoc b/modules/monitoring-reviewing-monitoring-dashboards-developer.adoc deleted file mode 100644 index 6ebf4d01182b..000000000000 --- a/modules/monitoring-reviewing-monitoring-dashboards-developer.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/reviewing-monitoring-dashboards.adoc - -[id="reviewing-monitoring-dashboards-developer_{context}"] -= Reviewing monitoring dashboards as a developer - -In the Developer perspective, you can view dashboards relating to a selected project. You must have access to monitor a project to view dashboard information for it. - -.Prerequisites - -* You have access to the cluster as a developer or as a user with view permissions for the project that you are viewing the dashboard for. - -.Procedure - -. In the Developer perspective in the {product-title} web console, navigate to *Monitoring* -> *Dashboard*. - -. Choose a project in the *Project:* list. - -. Choose a workload in the *All Workloads* list. - -. Optional: Select a time range for the graphs in the *Time Range* list. - -. Optional: Select a *Refresh Interval*. - -. Hover over each of the graphs within a dashboard to display detailed information about specific items. diff --git a/modules/monitoring-running-metrics-queries.adoc b/modules/monitoring-running-metrics-queries.adoc deleted file mode 100644 index cd75b750c694..000000000000 --- a/modules/monitoring-running-metrics-queries.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/examining-cluster-metrics.adoc - -[id="running-metrics-queries_{context}"] -= Running metrics queries - -You begin working with metrics by entering one or several Prometheus Query Language (PromQL) queries. - -.Procedure - -. Open the {product-title} web console and navigate to the *Monitoring* -> *Metrics* page. - -. In the query field, enter your PromQL query. -* To show all available metrics and PromQL functions, click *Insert Metric at Cursor*. -. For multiple queries, click *Add Query*. -. For deleting queries, click {kebab} for the query, then select *Delete query*. -. For keeping but not running a query, click the *Disable query* button. -. Once you finish creating queries, click the *Run Queries* button. The metrics from the queries are visualized on the plot. If a query is invalid, the UI shows an error message. -+ -[NOTE] -==== -Queries that operate on large amounts of data might timeout or overload the browser when drawing timeseries graphs. To avoid this, hide the graph and calibrate your query using only the metrics table. Then, after finding a feasible query, enable the plot to draw the graphs. -==== -+ -. Optional: The page URL now contains the queries you ran. To use this set of queries again in the future, save this URL. - -.Additional resources - -See the link:https://prometheus.io/docs/prometheus/latest/querying/basics/[Prometheus Query Language documentation]. diff --git a/modules/monitoring-searching-alerts-silences-and-alerting-rules.adoc b/modules/monitoring-searching-alerts-silences-and-alerting-rules.adoc deleted file mode 100644 index 5871bfaed551..000000000000 --- a/modules/monitoring-searching-alerts-silences-and-alerting-rules.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="searching-alerts-silences-and-alerting-rules_{context}"] -= Searching and filtering alerts, silences, and alerting rules - -You can filter the alerts, silences, and alerting rules that are displayed in the Alerting UI. This section provides a description of each of the available filtering options. - -[discrete] -== Understanding alert filters - -In the *Administrator* perspective, the *Alerts* page in the Alerting UI provides details about alerts relating to default {product-title} and user-defined projects. The page includes a summary of severity, state, and source for each alert. The time at which an alert went into its current state is also shown. - -You can filter by alert state, severity, and source. By default, only *Platform* alerts that are *Firing* are displayed. The following describes each alert filtering option: - -* *Alert State* filters: -** *Firing*. The alert is firing because the alert condition is true and the optional `for` duration has passed. The alert will continue to fire as long as the condition remains true. -** *Pending*. The alert is active but is waiting for the duration that is specified in the alerting rule before it fires. -** *Silenced*. The alert is now silenced for a defined time period. Silences temporarily mute alerts based on a set of label selectors that you define. Notifications will not be sent for alerts that match all the listed values or regular expressions. - -* *Severity* filters: -** *Critical*. The condition that triggered the alert could have a critical impact. The alert requires immediate attention when fired and is typically paged to an individual or to a critical response team. -** *Warning*. The alert provides a warning notification about something that might require attention to prevent a problem from occurring. Warnings are typically routed to a ticketing system for non-immediate review. -** *Info*. The alert is provided for informational purposes only. -** *None*. The alert has no defined severity. -** You can also create custom severity definitions for alerts relating to user-defined projects. - -* *Source* filters: -** *Platform*. Platform-level alerts relate only to default {product-title} projects. These projects provide core {product-title} functionality. -** *User*. User alerts relate to user-defined projects. These alerts are user-created and are customizable. User-defined workload monitoring can be enabled post-installation to provide observability into your own workloads. - -[discrete] -== Understanding silence filters - -In the *Administrator* perspective, the *Silences* page in the Alerting UI provides details about silences applied to alerts in default {product-title} and user-defined projects. The page includes a summary of the state of each silence and the time at which a silence ends. - -You can filter by silence state. By default, only *Active* and *Pending* silences are displayed. The following describes each silence state filter option: - -* *Silence State* filters: -** *Active*. The silence is active and the alert will be muted until the silence is expired. -** *Pending*. The silence has been scheduled and it is not yet active. -** *Expired*. The silence has expired and notifications will be sent if the conditions for an alert are true. - -[discrete] -== Understanding alerting rule filters - -In the *Administrator* perspective, the *Alerting Rules* page in the Alerting UI provides details about alerting rules relating to default {product-title} and user-defined projects. The page includes a summary of the state, severity, and source for each alerting rule. - -You can filter alerting rules by alert state, severity, and source. By default, only *Platform* alerting rules are displayed. The following describes each alerting rule filtering option: - -* *Alert State* filters: -** *Firing*. The alert is firing because the alert condition is true and the optional `for` duration has passed. The alert will continue to fire as long as the condition remains true. -** *Pending*. The alert is active but is waiting for the duration that is specified in the alerting rule before it fires. -** *Silenced*. The alert is now silenced for a defined time period. Silences temporarily mute alerts based on a set of label selectors that you define. Notifications will not be sent for alerts that match all the listed values or regular expressions. -** *Not Firing*. The alert is not firing. - -* *Severity* filters: -** *Critical*. The conditions defined in the alerting rule could have a critical impact. When true, these conditions require immediate attention. Alerts relating to the rule are typically paged to an individual or to a critical response team. -** *Warning*. The conditions defined in the alerting rule might require attention to prevent a problem from occurring. Alerts relating to the rule are typically routed to a ticketing system for non-immediate review. -** *Info*. The alerting rule provides informational alerts only. -** *None*. The alerting rule has no defined severity. -** You can also create custom severity definitions for alerting rules relating to user-defined projects. - -* *Source* filters: -** *Platform*. Platform-level alerting rules relate only to default {product-title} projects. These projects provide core {product-title} functionality. -** *User*. User-defined workload alerting rules relate to user-defined projects. These alerting rules are user-created and are customizable. User-defined workload monitoring can be enabled post-installation to provide observability into your own workloads. - -[discrete] -== Searching and filtering alerts, silences, and alerting rules in the Developer perspective - -In the *Developer* perspective, the Alerts page in the Alerting UI provides a combined view of alerts and silences relating to the selected project. A link to the governing alerting rule is provided for each displayed alert. - -In this view, you can filter by alert state and severity. By default, all alerts in the selected project are displayed if you have permission to access the project. These filters are the same as those described for the *Administrator* perspective. diff --git a/modules/monitoring-sending-notifications-to-external-systems.adoc b/modules/monitoring-sending-notifications-to-external-systems.adoc deleted file mode 100644 index 5b88411fa5fd..000000000000 --- a/modules/monitoring-sending-notifications-to-external-systems.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc -// * post_installation_configuration/configuring-alert-notifications.adoc - -[id="sending-notifications-to-external-systems_{context}"] -= Sending notifications to external systems - -In {product-title} {product-version}, firing alerts can be viewed in the Alerting UI. Alerts are not configured by default to be sent to any notification systems. You can configure {product-title} to send alerts to the following receiver types: - -* PagerDuty -* Webhook -* Email -* Slack - -Routing alerts to receivers enables you to send timely notifications to the appropriate teams when failures occur. For example, critical alerts require immediate attention and are typically paged to an individual or a critical response team. Alerts that provide non-critical warning notifications might instead be routed to a ticketing system for non-immediate review. - -.Checking that alerting is operational by using the watchdog alert - -{product-title} monitoring includes a watchdog alert that fires continuously. Alertmanager repeatedly sends watchdog alert notifications to configured notification providers. The provider is usually configured to notify an administrator when it stops receiving the watchdog alert. This mechanism helps you quickly identify any communication issues between Alertmanager and the notification provider. diff --git a/modules/monitoring-setting-a-scrape-sample-limit-for-user-defined-projects.adoc b/modules/monitoring-setting-a-scrape-sample-limit-for-user-defined-projects.adoc deleted file mode 100644 index 0f74cf9bd5c7..000000000000 --- a/modules/monitoring-setting-a-scrape-sample-limit-for-user-defined-projects.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="setting-a-scrape-sample-limit-for-user-defined-projects_{context}"] -= Setting a scrape sample limit for user-defined projects - -You can limit the number of samples that can be accepted per target scrape in user-defined projects. - -[WARNING] -==== -If you set a sample limit, no further sample data is ingested for that target scrape after the limit is reached. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -* You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- - -. Add the `enforcedSampleLimit` configuration to `data/config.yaml` to limit the number of samples that can be accepted per target scrape in user-defined projects: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - prometheus: - enforcedSampleLimit: 50000 <1> ----- -<1> A value is required if this parameter is specified. This `enforcedSampleLimit` example limits the number of samples that can be accepted per target scrape in user-defined projects to 50,000. - -. Save the file to apply the changes. The limit is applied automatically. -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== -+ -[WARNING] -==== -When changes are saved to the `user-workload-monitoring-config` `ConfigMap` object, the pods and other resources in the `openshift-user-workload-monitoring` project might be redeployed. The running monitoring processes in that project might also be restarted. -==== diff --git a/modules/monitoring-setting-log-levels-for-monitoring-components.adoc b/modules/monitoring-setting-log-levels-for-monitoring-components.adoc deleted file mode 100644 index fd2896269c00..000000000000 --- a/modules/monitoring-setting-log-levels-for-monitoring-components.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="setting-log-levels-for-monitoring-components_{context}"] -= Setting log levels for monitoring components - -You can configure the log level for Prometheus Operator, Prometheus, Thanos Querier, and Thanos Ruler. - -The following log levels can be applied to each of those components in the `cluster-monitoring-config` and `user-workload-monitoring-config` `ConfigMap` objects: - -* `debug`. Log debug, informational, warning, and error messages. -* `info`. Log informational, warning, and error messages. -* `warn`. Log warning and error messages only. -* `error`. Log error messages only. - -The default log level is `info`. - -.Prerequisites - -* *If you are setting a log level for Prometheus Operator, Prometheus, or Thanos Querier in the `openshift-monitoring` project*: -** You have access to the cluster as a user with the `cluster-admin` role. -** You have created the `cluster-monitoring-config` `ConfigMap` object. -* *If you are setting a log level for Prometheus Operator, Prometheus, or Thanos Ruler in the `openshift-user-workload-monitoring` project*: -** You have access to the cluster as a user with the `cluster-admin` role, or as a user with the `user-workload-monitoring-config-edit` role in the `openshift-user-workload-monitoring` project. -** You have created the `user-workload-monitoring-config` `ConfigMap` object. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `ConfigMap` object: -** *To set a log level for a component in the `openshift-monitoring` project*: -.. Edit the `cluster-monitoring-config` `ConfigMap` object in the `openshift-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-monitoring edit configmap cluster-monitoring-config ----- - -.. Add `logLevel: <log_level>` for a component under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cluster-monitoring-config - namespace: openshift-monitoring -data: - config.yaml: | - <component>: <1> - logLevel: <log_level> <2> ----- -<1> The monitoring component that you are applying a log level to. -<2> The log level to apply to the component. - -** *To set a log level for a component in the `openshift-user-workload-monitoring` project*: -.. Edit the `user-workload-monitoring-config` `ConfigMap` object in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring edit configmap user-workload-monitoring-config ----- - -.. Add `logLevel: <log_level>` for a component under `data/config.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-workload-monitoring-config - namespace: openshift-user-workload-monitoring -data: - config.yaml: | - <component>: <1> - logLevel: <log_level> <2> ----- -<1> The monitoring component that you are applying a log level to. -<2> The log level to apply to the component. - -. Save the file to apply the changes. The pods for the component restarts automatically when you apply the log-level change. -+ -[NOTE] -==== -Configurations applied to the `user-workload-monitoring-config` `ConfigMap` object are not activated unless a cluster administrator has enabled monitoring for user-defined projects. -==== -+ -[WARNING] -==== -When changes are saved to a monitoring config map, the pods and other resources in the related project might be redeployed. The running monitoring processes in that project might also be restarted. -==== - -. Confirm that the log-level has been applied by reviewing the deployment or pod configuration in the related project. The following example checks the log level in the `prometheus-operator` deployment in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring get deploy prometheus-operator -o yaml | grep "log-level" ----- -+ -.Example output -[source,terminal] ----- - - --log-level=debug ----- - -. Check that the pods for the component are running. The following example lists the status of pods in the `openshift-user-workload-monitoring` project: -+ -[source,terminal] ----- -$ oc -n openshift-user-workload-monitoring get pods ----- -+ -[NOTE] -==== -If an unrecognized `loglevel` value is included in the `ConfigMap` object, the pods for the component might not restart successfully. -==== diff --git a/modules/monitoring-setting-up-metrics-collection-for-user-defined-projects.adoc b/modules/monitoring-setting-up-metrics-collection-for-user-defined-projects.adoc deleted file mode 100644 index 92a45bacb505..000000000000 --- a/modules/monitoring-setting-up-metrics-collection-for-user-defined-projects.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="setting-up-metrics-collection-for-user-defined-projects_{context}"] -= Setting up metrics collection for user-defined projects - -You can create a `ServiceMonitor` resource to scrape metrics from a service endpoint in a user-defined project. This assumes that your application uses a Prometheus client library to expose metrics to the `/metrics` canonical name. - -This section describes how to deploy a sample service in a user-defined project and then create a `ServiceMonitor` resource that defines how that service should be monitored. diff --git a/modules/monitoring-silencing-alerts.adoc b/modules/monitoring-silencing-alerts.adoc deleted file mode 100644 index 93a05351b3e2..000000000000 --- a/modules/monitoring-silencing-alerts.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-alerts.adoc - -[id="silencing-alerts_{context}"] -= Silencing alerts - -You can either silence a specific alert or silence alerts that match a specification that you define. - -.Prerequisites - -* You have access to the cluster as a developer or as a user with `edit` permissions for the project that you are viewing metrics for. - -.Procedure - -To silence a specific alert: - -* In the *Administrator* perspective: - -. Navigate to the *Monitoring* -> *Alerting* -> *Alerts* page of the {product-title} web console. - -. For the alert that you want to silence, select the {kebab} in the right-hand column and select *Silence Alert*. The *Silence Alert* form will appear with a pre-populated specification for the chosen alert. - -. Optional: Modify the silence. - -. You must add a comment before creating the silence. - -. To create the silence, select *Silence*. - -* In the *Developer* perspective: - -. Navigate to the *Monitoring* -> *<project_name>* -> *Alerts* page in the {product-title} web console. - -. Expand the details for an alert by selecting *>* to the left of the alert name. Select the name of the alert in the expanded view to open the *Alert Details* page for the alert. - -. Select *Silence Alert*. The *Silence Alert* form will appear with a prepopulated specification for the chosen alert. - -. Optional: Modify the silence. - -. You must add a comment before creating the silence. - -. To create the silence, select *Silence*. - -To silence a set of alerts by creating an alert specification in the *Administrator* perspective: - -. Navigate to the *Monitoring* -> *Alerting* -> *Silences* page in the {product-title} web console. - -. Select *Create Silence*. - -. Set the schedule, duration, and label details for an alert in the *Create Silence* form. You must also add a comment for the silence. - -. To create silences for alerts that match the label sectors that you entered in the previous step, select *Silence*. diff --git a/modules/monitoring-specifying-how-a-service-is-monitored.adoc b/modules/monitoring-specifying-how-a-service-is-monitored.adoc deleted file mode 100644 index 2dab79cb8a25..000000000000 --- a/modules/monitoring-specifying-how-a-service-is-monitored.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="specifying-how-a-service-is-monitored_{context}"] -= Specifying how a service is monitored - -To use the metrics exposed by your service, you must configure {product-title} monitoring to scrape metrics from the `/metrics` endpoint. You can do this using a `ServiceMonitor` custom resource definition (CRD) that specifies how a service should be monitored, or a `PodMonitor` CRD that specifies how a pod should be monitored. The former requires a `Service` object, while the latter does not, allowing Prometheus to directly scrape metrics from the metrics endpoint exposed by a pod. - -[NOTE] -==== -In {product-title} {product-version}, you can use the `tlsConfig` property for a `ServiceMonitor` resource to specify the TLS configuration to use when scraping metrics from an endpoint. The `tlsConfig` property is not yet available for `PodMonitor` resources. If you need to use a TLS configuration when scraping metrics, you must use `ServiceMonitor` resource. -==== - -This procedure shows you how to create a `ServiceMonitor` resource for a service in a user-defined project. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role or the `monitoring-edit` role. -* You have enabled monitoring for user-defined projects. -* For this example, you have deployed the `prometheus-example-app` sample service in the `ns1` project. - -.Procedure - -. Create a YAML file for the `ServiceMonitor` resource configuration. In this example, the file is called `example-app-service-monitor.yaml`. - -. Add the following `ServiceMonitor` resource configuration details: -+ -[source,yaml] ----- -apiVersion: monitoring.coreos.com/v1 -kind: ServiceMonitor -metadata: - labels: - k8s-app: prometheus-example-monitor - name: prometheus-example-monitor - namespace: ns1 -spec: - endpoints: - - interval: 30s - port: web - scheme: http - selector: - matchLabels: - app: prometheus-example-app ----- -+ -This defines a `ServiceMonitor` resource that scrapes the metrics exposed by the `prometheus-example-app` sample service, which includes the `version` metric. - -. Apply the configuration to the cluster: -+ -[source,terminal] ----- -$ oc apply -f example-app-service-monitor.yaml ----- -+ -It takes some time to deploy the `ServiceMonitor` resource. - -. You can check that the `ServiceMonitor` resource is running: -+ -[source,terminal] ----- -$ oc -n ns1 get servicemonitor ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -prometheus-example-monitor 81m ----- - -.Additional resources - -* See the link:https://github.com/openshift/prometheus-operator/blob/release-4.5/Documentation/api.md[Prometheus Operator API documentation] for more information on `ServiceMonitor` and `PodMonitor` resources. diff --git a/modules/monitoring-support-considerations.adoc b/modules/monitoring-support-considerations.adoc deleted file mode 100644 index 45ec97b03f53..000000000000 --- a/modules/monitoring-support-considerations.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="support-considerations_{context}"] -= Support considerations for monitoring - -The following modifications are explicitly not supported: - -* *Creating additional `ServiceMonitor`, `PodMonitor`, and `PrometheusRule` objects in the `openshift-&#42;`, and `kube-&#42;` projects.* -* *Modifying any resources or objects deployed in the `openshift-monitoring` or `openshift-user-workload-monitoring` projects.* The resources created by the {product-title} monitoring stack are not meant to be used by any other resources, as there are no guarantees about their backward compatibility. -+ -[NOTE] -==== -The Alertmanager configuration is deployed as a secret resource in the `openshift-monitoring` project. To configure additional routes for Alertmanager, you need to decode, modify, and then encode that secret. This procedure is a supported exception to the preceding statement. -==== -+ -* *Modifying resources of the stack.* The {product-title} monitoring stack ensures its resources are always in the state it expects them to be. If they are modified, the stack will reset them. -* *Deploying user-defined workloads to `openshift-&#42;`, and `kube-&#42;` projects.* These projects are reserved for Red Hat provided components and they should not be used for user-defined workloads. -* *Modifying the monitoring stack Grafana instance.* -* *Installing custom Prometheus instances on {product-title}.* -* *Enabling symptom based monitoring by using the `Probe` custom resource definition (CRD) in Prometheus Operator.* -* *Modifying Alertmanager configurations by using the `AlertmanagerConfig` CRD in Prometheus Operator.* diff --git a/modules/monitoring-targets-for-user-defined-projects.adoc b/modules/monitoring-targets-for-user-defined-projects.adoc deleted file mode 100644 index 75b9eb3147b0..000000000000 --- a/modules/monitoring-targets-for-user-defined-projects.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/understanding-the-monitoring-stack.adoc - -[id="monitoring-targets-for-user-defined-projects_{context}"] -= Monitoring targets for user-defined projects - -When monitoring is enabled for user-defined projects, you can monitor: - -* Metrics provided through service endpoints in user-defined projects. -* Pods running in user-defined projects. diff --git a/modules/monitoring-understanding-metrics.adoc b/modules/monitoring-understanding-metrics.adoc deleted file mode 100644 index 5b7c70cc2a59..000000000000 --- a/modules/monitoring-understanding-metrics.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/managing-metrics.adoc - -[id="understanding-metrics_{context}"] -= Understanding metrics - -In {product-title} {product-version}, cluster components are monitored by scraping metrics exposed through service endpoints. You can also configure metrics collection for user-defined projects. Metrics enable you to monitor how cluster components and your own workloads are performing. - -You can define the metrics that you want to provide for your own workloads by using Prometheus client libraries at the application level. - -In {product-title}, metrics are exposed through an HTTP service endpoint under the `/metrics` canonical name. You can list all available metrics for a service by running a `curl` query against `\http://<endpoint>/metrics`. For instance, you can expose a route to the `prometheus-example-app` example application and then run the following to view all of its available metrics: - -[source,terminal] ----- -$ curl http://<example_app_endpoint>/metrics ----- - -.Example output -[source,terminal] ----- -# HELP http_requests_total Count of all HTTP requests -# TYPE http_requests_total counter -http_requests_total{code="200",method="get"} 4 -http_requests_total{code="404",method="get"} 2 -# HELP version Version information about this binary -# TYPE version gauge -version{version="v0.1.0"} 1 ----- - -.Additional resources - -* See the link:https://prometheus.io/docs/instrumenting/clientlibs/[Prometheus documentation] for details on Prometheus client libraries. diff --git a/modules/monitoring-understanding-the-monitoring-stack.adoc b/modules/monitoring-understanding-the-monitoring-stack.adoc deleted file mode 100644 index 3d217cdd9a32..000000000000 --- a/modules/monitoring-understanding-the-monitoring-stack.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc -// * monitoring/understanding-the-monitoring-stack.adoc - -// This module uses a conditionalized title so that the module -// can be re-used in associated products but the title is not -// included in the existing OpenShift assembly. - -[id="understanding-the-monitoring-stack_{context}"] -= Understanding the monitoring stack - -The {product-title} monitoring stack is based on the link:https://prometheus.io/[Prometheus] open source project and its wider ecosystem. The monitoring stack includes the following: - -* *Default platform monitoring components*. A set of platform monitoring components are installed in the `openshift-monitoring` project by default during an {product-title} installation. This provides monitoring for core {product-title} components including Kubernetes services. The default monitoring stack also enables remote health monitoring for clusters. These components are illustrated in the *Installed by default* section in the following diagram. - -* *Components for monitoring user-defined projects*. After optionally enabling monitoring for user-defined projects, additional monitoring components are installed in the `openshift-user-workload-monitoring` project. This provides monitoring for user-defined projects. These components are illustrated in the *User* section in the following diagram. - -image:monitoring-architecture.svg[{product-title} monitoring architecture] diff --git a/modules/monitoring-unmanaged-monitoring-operators.adoc b/modules/monitoring-unmanaged-monitoring-operators.adoc deleted file mode 100644 index 6cb3251484ab..000000000000 --- a/modules/monitoring-unmanaged-monitoring-operators.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * monitoring/configuring-the-monitoring-stack.adoc - -[id="unmanaged-monitoring-operators_{context}"] -= Support policy for monitoring Operators - -Monitoring Operators ensure that {product-title} monitoring resources function as designed and tested. If Cluster Version Operator (CVO) control of an Operator is overridden, the Operator does not respond to configuration changes, reconcile the intended state of cluster objects, or receive updates. - -While overriding CVO control for an Operator can be helpful during debugging, this is unsupported and the cluster administrator assumes full control of the individual component configurations and upgrades. - -.Overriding the Cluster Version Operator - -The `spec.overrides` parameter can be added to the configuration for the CVO to allow administrators to provide a list of overrides to the behavior of the CVO for a component. Setting the `spec.overrides[].unmanaged` parameter to `true` for a component blocks cluster upgrades and alerts the administrator after a CVO override has been set: - -[source,terminal] ----- -Disabling ownership via cluster version overrides prevents upgrades. Please remove overrides before continuing. ----- - -[WARNING] -==== -Setting a CVO override puts the entire cluster in an unsupported state and prevents the monitoring stack from being reconciled to its intended state. This impacts the reliability features built into Operators and prevents updates from being received. Reported issues must be reproduced after removing any overrides for support to proceed. -==== diff --git a/modules/namespace-conditions-for-platform-components.adoc b/modules/namespace-conditions-for-platform-components.adoc new file mode 100644 index 000000000000..5cdc3c1a706c --- /dev/null +++ b/modules/namespace-conditions-for-platform-components.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: REFERENCE +[id="namespace-conditions-for-platform-components_{context}"] += Namespace conditions for platform components + +By understanding the namespace conditions for platform components, you can identify and manage the namespaces that fall under {ocp}, layered products, and third party partners in your environment. + +.Namespace conditions for platform components +[cols="1,3", options="header"] +|=== +|Platform component +|Namespace condition + +|{ocp} +a| * Namespace starts with `openshift-` +* Namespace starts with `kube-` + +|Layered products +a| * namespace = `stackrox` +* Namespace starts with `rhacs-operator` +* Namespace starts with `open-cluster-management` +* namespace = `multicluster-engine` +* namespace = `aap` +* namespace = `hive` + +|Third party partners +a| * namespace = `nvidia-gpu-operator` +|=== + +{rh-rhacs-first} identifies the workloads belonging to platform components by using the following regex pattern: + +[source,text] +---- +^kube-.*|^openshift-.*|^stackrox$|^rhacs-operator$|^open-cluster-management$|^multicluster-engine$|^aap$|^hive$|^nvidia-gpu-operator$ +---- + +The platform definition is not yet customizable. You can see the impact of the definition in your environment by using the global search. To do a global search, follow these steps: + +. Click *Search*. +. Select *Show Orchestrator Components*. +. Apply the filter `Platform Component: true`. \ No newline at end of file diff --git a/modules/namespace-exclusions.adoc b/modules/namespace-exclusions.adoc new file mode 100644 index 000000000000..30a3a3dcb3a4 --- /dev/null +++ b/modules/namespace-exclusions.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +// * operating/manage_security_policies/about-security-policies.adoc +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: CONCEPT +[id="namespace-exclusions_{context}"] += Namespace exclusions + +By default, {product-title-short} excludes certain administrative namespaces, such as the `stackrox`, `kube-system`, and `istio-system` namespaces, from enforcement blocking. The reason for this is that some items in these namespaces must be deployed for {product-title-short} to work correctly. + +In addition, the {product-title-short} admission controller bypasses requests that originate from a `service` account in a `system` namespace. Consider this factor when deploying the CI/CD tool of your choice. diff --git a/modules/network-graph-20-view.adoc b/modules/network-graph-20-view.adoc new file mode 100644 index 000000000000..82378d228370 --- /dev/null +++ b/modules/network-graph-20-view.adoc @@ -0,0 +1,95 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="network-graph-20-view_{context}"] += About the network graph + +[role="_abstract"] + +The network graph provides high-level and detailed information about deployments, network flows, and network policies in your environment. + +{product-title-short} processes all network policies in each secured cluster to show you which deployments can contact each other and which can reach external networks. It also monitors running deployments and tracks traffic between them. You can view the following items in the network graph: + +Internal entities:: These represent a connection between a deployment and an IP address that belongs to the private address space as defined in link:https://datatracker.ietf.org/doc/html/rfc1918[RFC 1918]. For more information, see "Connections involving internal entities". +External entities:: These represent a connection between a deployment and an IP address that does not belong to the private address space as defined in link:https://datatracker.ietf.org/doc/html/rfc1918[RFC 1918]. For more information, see "External entities and connections in the network graph". +Network components:: From the top menu, you can select namespaces (indicated by the *NS* label) and deployments (indicated by the *D* label) to display on the graph for a chosen cluster (indicated by the *CL* label). You can further filter deployments by using the drop-down list and selecting criteria on which to filter, such as common vulnerabilities and exposures (CVEs), labels, and images. +Network flows:: You can select one of the following flows for the graph: +Active traffic:: Selecting this default option shows observed traffic, focused on the namespace or specific deployment that you selected. You can select the time period for which to display information. +Inactive flows:: Selecting this option shows potential flows allowed by your network policies, helping you identify missing network policies needed to achieve tighter isolation. You can select the time period for which to display information. +Network policies:: You can view existing policies for a selected component or view components that have no policies. You can also simulate network policies from the network graph view. See "Simulating network policies from the network graph" for more information. + +[id="navigation-user-interface_{context}"] +== Displays, navigation, and the user interface in the network graph + +You can use the network graph, shown in the following graphic, to click on items and view additional information about them. You can also perform actions within the graph such as adding a network flow to your baseline. + +.Network graph example +image::network-graph-20-overview-updated.png[Overview of the Network graph showing deployments] + +The following tips can help you use the network graph: + +* Opening the legend provides information about the symbols in use and their meaning. The legend shows explanatory text for symbols representing namespaces, deployments, and connections on the network graph. +* Selecting additional display options from the drop-down list controls whether the graph displays icons such as the network policy status badge, active external traffic badge, and port and protocol labels for edge connections. +* {product-title-short} detects changes in network traffic, such as nodes joining or leaving. If changes are detected, the network graph displays a notification showing the number of updates available. To avoid interrupting your focus, the graph is not updated automatically. Click the notification to update the graph. + +When you click an item in the graph, the rearranged side panel with collapsible sections presents information about that item. You can click on the following items: + +* Deployments +* Namespaces +* External entities +* CIDR blocks +* External groups + +The side panel displays relevant information based on the item in the graph that you have selected. The *D* or *NS* label next to the item name in the header (in this example, "visa-processor") indicates if it is a deployment or a namespace. The following example illustrates the side panel for a deployment. + +.Side panel for a deployment example +image::network-graph-20-deployment-mode-updated.png[Side panel for a deployment] + +When viewing a namespace, the side panel includes a search bar and a list of deployments. You can click on a deployment to view its information. The side panel also includes a *Network policies* tab. From this tab, you can view, copy to the clipboard, or export any network policy defined in that namespace, as shown in the following example. + +.Side panel for a namespace example +image::network-graph-20-namespace-mode.png[Side panel for a namespace showing network policy information] + +[id="external-entities-connections_{context}"] +== External entities and connections in the network graph + +The network graph view shows network connections between managed clusters and external sources. +In addition, {product-title-short} automatically discovers and highlights public Classless Inter-Domain Routing (CIDR) address blocks, such as Google Cloud, AWS, Microsoft Azure, Oracle Cloud, and Cloudflare. +Using this information, you can identify deployments with active external connections and decide if they are making or receiving unauthorized connections from outside your network. + +By default, the external connections point to a common *External Entities* icon and different CIDR address blocks in the network graph. +However, you can choose not to show auto-discovered CIDR blocks by clicking *Manage CIDR blocks* and deselecting *Auto-discovered CIDR blocks*. + +{product-title-short} includes IP ranges for the following cloud providers: + +* Google Cloud +* AWS +* Microsoft Azure +* Oracle Cloud +* Cloudflare + +{product-title-short} fetches and updates the cloud providers' IP ranges every 7 days, and updates CIDR blocks daily. +If you are using offline mode, you can update these ranges by installing new support packages. + +The following image provides an example of the network graph. In this example, based on the options that the user has chosen, the graph depicts deployments in the selected namespace. Traffic flows are not displayed until you click on an item such as a deployment. The graph uses a red badge to indicate deployments that are missing policies and therefore allowing all network traffic. + +[id="internal-entities-connections_{context}"] +== Connections involving internal entities + +The network graph is useful for identifying deployments with active connections to entities that do not belong to any known deployment or CIDR block. Some of these connections never reach outside of the cluster and are made within the cluster's private network. The network graph represents those as connections to or from _internal entities_. + +Connections with internal entities represent a connection between a deployment and an IP address that belongs to the private address space as defined in http://datatracker.ietf.org/doc/html/rfc1918[RFC 1918]. In some cases, Sensor is unable to identify one or both deployments involved in a connection. In that case, the system analyzes the IP address and decides whether the connection is internal or external. + +The following scenarios can lead to a connection being categorized as one involving internal entities: + +* A change of IP address or the deletion of a deployment accepting connections (the server) while the party initiating the connection (the client) still attempts to reach it +* A deployment communicating with the orchestrator API +* A deployment communicating using a networking CNI plugin, for example, Calico +* A restart of Sensor, resulting in a reset of the mapping of IP addresses to past deployments, for example, when Sensor does not recognize the IP addresses of past entities or past IP addresses of existing entities +* A connection that involves an entity not managed by the orchestrator (in some cases, that might be seen as _outside of the cluster_) but is using an IP address from the private address space as defined in RFC 1918 + +Internal entities are indicated with an icon as shown in the following graphic. Clicking on *Internal entities* shows the flows for these entities. + +.Internal entities example +image::network-graph-internal-entities.png[Network graph showing internal entities] diff --git a/modules/network-policies-tab.adoc b/modules/network-policies-tab.adoc new file mode 100644 index 000000000000..2e9d0f5b13b5 --- /dev/null +++ b/modules/network-policies-tab.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: CONCEPT +[id="network-policies-tab_{context}"] += Network policies tab + +The *Network policies* section lists the network policies associated with a namespace. \ No newline at end of file diff --git a/modules/node-tuning-operator-supported-tuned-daemon-plug-ins.adoc b/modules/node-tuning-operator-supported-tuned-daemon-plug-ins.adoc deleted file mode 100644 index b8cd0a813b8e..000000000000 --- a/modules/node-tuning-operator-supported-tuned-daemon-plug-ins.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/using-node-tuning-operator.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="supported-tuned-daemon-plug-ins_{context}"] -= Supported TuneD daemon plug-ins - -Excluding the `[main]` section, the following TuneD plug-ins are supported when -using custom profiles defined in the `profile:` section of the Tuned CR: - -* audio -* cpu -* disk -* eeepc_she -* modules -* mounts -* net -* scheduler -* scsi_host -* selinux -* sysctl -* sysfs -* usb -* video -* vm - -There is some dynamic tuning functionality provided by some of these plug-ins -that is not supported. The following TuneD plug-ins are currently not supported: - -* bootloader -* script -* systemd - - -See -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/customizing-tuned-profiles_monitoring-and-managing-system-status-and-performance#available-tuned-plug-ins_customizing-tuned-profiles[Available -TuneD Plug-ins] and -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/getting-started-with-tuned_monitoring-and-managing-system-status-and-performance[Getting -Started with TuneD] for more information. diff --git a/modules/node-tuning-operator.adoc b/modules/node-tuning-operator.adoc deleted file mode 100644 index b5cc24263aa8..000000000000 --- a/modules/node-tuning-operator.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/using-node-tuning-operator.adoc -// * operators/operator-reference.adoc -// * post_installation_configuration/node-tasks.adoc - -ifeval::["{context}" == "red-hat-operators"] -:operators: -endif::[] -ifeval::["{context}" == "node-tuning-operator"] -:perf: -endif::[] - -[id="about-node-tuning-operator_{context}"] -ifdef::operators[] -= Node Tuning Operator -endif::operators[] -ifdef::perf[] -= About the Node Tuning Operator -endif::perf[] -ifdef::operators[] -[discrete] -== Purpose -endif::operators[] -The Node Tuning Operator helps you manage node-level tuning by orchestrating the TuneD daemon. The majority of high-performance applications require some level of kernel tuning. The Node Tuning Operator provides a unified management interface to users of node-level sysctls and more flexibility to add custom tuning specified by user needs. - -The Operator manages the containerized TuneD daemon for {product-title} as a Kubernetes daemon set. It ensures the custom tuning specification is passed to all containerized TuneD daemons running in the cluster in the format that the daemons understand. The daemons run on all nodes in the cluster, one per node. - -Node-level settings applied by the containerized TuneD daemon are rolled back on an event that triggers a profile change or when the containerized TuneD daemon is terminated gracefully by receiving and handling a termination signal. - -The Node Tuning Operator is part of a standard {product-title} installation in version 4.1 and later. -ifdef::operators[] -[discrete] -== Project - -link:https://github.com/openshift/cluster-node-tuning-operator[cluster-node-tuning-operator] -endif::operators[] diff --git a/modules/nodes-cluster-enabling-features-cluster.adoc b/modules/nodes-cluster-enabling-features-cluster.adoc deleted file mode 100644 index 2f214c2bce6e..000000000000 --- a/modules/nodes-cluster-enabling-features-cluster.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-enabling-features.adoc -// * post_installation_configuration/cluster-tasks.adoc - -[id="nodes-cluster-enabling-features-cluster_{context}"] -= Enabling Technology Preview features using feature gates - -You can turn on Technology Preview features on for all nodes in the cluster by -editing the `FeatureGate` custom resource, named `cluster`, in the `openshift-config` project. - -The following Technology Preview features are enabled by feature gates: - -* `RotateKubeletServerCertificate` - -* `SupportPodPidsLimit` - -[IMPORTANT] -==== -Turning on Technology Preview features using the `FeatureGate` custom resource cannot be undone and prevents upgrades. -==== - -.Procedure - -To turn on the Technology Preview features for the entire cluster: - -. In the {product-title} web console, switch to the *Administration* -> *Custom Resource Definitions* page. - -. On the *Custom Resource Definitions* page, click *FeatureGate*. - -. On the *Custom Resource Definitions* page, click *Actions* -> *View Instances*. - -. On the *Feature Gates* page, click *Create Feature Gates*. - -. Add the `featureSet` parameter: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: FeatureGate -metadata: - name: cluster -spec: - featureSet: "TechPreviewNoUpgrade" <1> ----- -<1> Add the `featureSet: "TechPreviewNoUpgrade"` parameter. - -. Click *Save*. diff --git a/modules/nodes-cluster-features-about.adoc b/modules/nodes-cluster-features-about.adoc deleted file mode 100644 index 4154700e1358..000000000000 --- a/modules/nodes-cluster-features-about.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-enabling-features.adoc - -[id="nodes-cluster-features-about_{context}"] -= Understanding feature gates and Technology Preview features - -You can use the `FeatureGate` custom resource to enable Technology Preview -features throughout your cluster. This allows you, for example, to enable -Technology Preview features on test clusters where you can fully test them while -ensuring they are disabled on production clusters. - -[IMPORTANT] -==== -After turning Technology Preview features on using feature gates, they cannot be -turned off and cluster upgrades are prevented. - -ifndef::openshift-origin[] -For more information about the support scope of Red Hat Technology Preview features, -see link:https://access.redhat.com/support/offerings/techpreview/[]. -endif::[] -==== - - -//// -If you disable a feature that appears in the web console, you might see that feature, but -no objects are listed. For example, if you disable builds, you can see the *Builds* tab in the web console, but there are no builds present. - -If you attempt to use commands associated with a disabled feature, such as `oc start-build`, {product-title} -displays an error. - -[NOTE] -==== -If you disable a feature that any application in the cluster relies on, the application might not -function properly, depending upon the feature disabled and how the application uses that feature. -==== -//// diff --git a/modules/nodes-cluster-limit-ranges-about.adoc b/modules/nodes-cluster-limit-ranges-about.adoc deleted file mode 100644 index 405fd2b6c6e3..000000000000 --- a/modules/nodes-cluster-limit-ranges-about.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/cluster/limit-ranges.adoc - -[id="nodes-cluster-limit-ranges-about_{context}"] -= About limit ranges - -A limit range, defined by a `LimitRange` object, restricts resource -consumption in a project. In the project you can set specific resource -limits for a pod, container, image, image stream, or -persistent volume claim (PVC). - -All requests to create and modify resources are evaluated against each -`LimitRange` object in the project. If the resource violates any of the -enumerated constraints, the resource is rejected. - -ifdef::openshift-online[] -[IMPORTANT] -==== -For {product-title} Pro, the maximum Pod memory is 3Gi. The minimum Pod or -container memory that you can specify is 100Mi. - -==== -endif::[] - -The following shows a limit range object for all components: pod, container, -image, image stream, or PVC. You can configure limits for any or all of these -components in the same object. You create a different limit range object for -each project where you want to control resources. - -.Sample limit range object for a container - -[source,yaml] ----- -apiVersion: "v1" -kind: "LimitRange" -metadata: - name: "resource-limits" -spec: - limits: - - type: "Container" - max: - cpu: "2" - memory: "1Gi" - min: - cpu: "100m" - memory: "4Mi" - default: - cpu: "300m" - memory: "200Mi" - defaultRequest: - cpu: "200m" - memory: "100Mi" - maxLimitRequestRatio: - cpu: "10" ----- diff --git a/modules/nodes-cluster-limit-ranges-creating.adoc b/modules/nodes-cluster-limit-ranges-creating.adoc deleted file mode 100644 index b7dc652c8fe0..000000000000 --- a/modules/nodes-cluster-limit-ranges-creating.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/cluster/limit-ranges.adoc - -[id="nodes-cluster-limit-creating_{context}"] -= Creating a Limit Range - -To apply a limit range to a project: - -. Create a `LimitRange` object with your required specifications: -+ -[source,yaml] ----- -apiVersion: "v1" -kind: "LimitRange" -metadata: - name: "resource-limits" <1> -spec: - limits: - - type: "Pod" <2> - max: - cpu: "2" - memory: "1Gi" - min: - cpu: "200m" - memory: "6Mi" - - type: "Container" <3> - max: - cpu: "2" - memory: "1Gi" - min: - cpu: "100m" - memory: "4Mi" - default: <4> - cpu: "300m" - memory: "200Mi" - defaultRequest: <5> - cpu: "200m" - memory: "100Mi" - maxLimitRequestRatio: <6> - cpu: "10" - - type: openshift.io/Image <7> - max: - storage: 1Gi - - type: openshift.io/ImageStream <8> - max: - openshift.io/image-tags: 20 - openshift.io/images: 30 - - type: "PersistentVolumeClaim" <9> - min: - storage: "2Gi" - max: - storage: "50Gi" ----- -<1> Specify a name for the `LimitRange` object. -<2> To set limits for a pod, specify the minimum and maximum CPU and memory requests as needed. -<3> To set limits for a container, specify the minimum and maximum CPU and memory requests as needed. -<4> Optional. For a container, specify the default amount of CPU or memory that a container can use, if not specified in the `Pod` spec. -<5> Optional. For a container, specify the default amount of CPU or memory that a container can request, if not specified in the `Pod` spec. -<6> Optional. For a container, specify the maximum limit-to-request ratio that can be specified in the `Pod` spec. -<7> To set limits for an Image object, set the maximum size of an image that can be pushed to an internal registry. -<8> To set limits for an image stream, set the maximum number of image tags and references that can be in the `ImageStream` object file, as needed. -<9> To set limits for a persistent volume claim, set the minimum and maximum amount of storage that can be requested. - -. Create the object: -+ ----- -$ oc create -f <limit_range_file> -n <project> <1> ----- -<1> Specify the name of the YAML file you created and the project where you want the limits to apply. diff --git a/modules/nodes-cluster-limit-ranges-deleting.adoc b/modules/nodes-cluster-limit-ranges-deleting.adoc deleted file mode 100644 index 24b63725ae3d..000000000000 --- a/modules/nodes-cluster-limit-ranges-deleting.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/cluster/limit-ranges.adoc - -[id="nodes-cluster-limit-ranges-deleting_{context}"] -= Deleting a Limit Range - - -To remove any active `LimitRange` object to no longer enforce the limits in a project: - -. Run the following command: -+ ----- -$ oc delete limits <limit_name> ----- diff --git a/modules/nodes-cluster-limit-ranges-limits.adoc b/modules/nodes-cluster-limit-ranges-limits.adoc deleted file mode 100644 index 126b843ec59f..000000000000 --- a/modules/nodes-cluster-limit-ranges-limits.adoc +++ /dev/null @@ -1,277 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/cluster/limit-ranges.adoc - -[id="nodes-cluster-limit-ranges-limits_{context}"] -= About component limits - -The following examples show limit range parameters for each component. The -examples are broken out for clarity. You can create a single `LimitRange` object -for any or all components as necessary. - -[id="nodes-cluster-limit-container-limits"] -== Container limits - -A limit range allows you to specify the minimum and maximum CPU and memory that each container -in a pod can request for a specific project. If a container is created in the project, -the container CPU and memory requests in the `Pod` spec must comply with the values set in the -`LimitRange` object. If not, the pod does not get created. - -* The container CPU or memory request and limit must be greater than or equal to the -`min` resource constraint for containers that are specified in the `LimitRange` object. - -* The container CPU or memory request must be less than or equal to the -`max` resource constraint for containers that are specified in the `LimitRange` object. -+ -If the `LimitRange` object defines a `max` CPU, you do not need to define a CPU -`request` value in the `Pod` spec. But you must specify a CPU `limit` value that -satisfies the maximum CPU constraint specified in the limit range. - -* The ratio of the container limits to requests must be -less than or equal to the `maxLimitRequestRatio` value for containers that -is specified in the `LimitRange` object. -+ -If the `LimitRange` object defines a `maxLimitRequestRatio` constraint, any new -containers must have both a `request` and a `limit` value. {product-title} -calculates the limit-to-request ratio by dividing the `limit` by the -`request`. This value should be a non-negative integer greater than 1. -+ -For example, if a container has `cpu: 500` in the `limit` value, and -`cpu: 100` in the `request` value, the limit-to-request ratio for `cpu` is -`5`. This ratio must be less than or equal to the `maxLimitRequestRatio`. - -If the `Pod` spec does not specify a container resource memory or limit, -the `default` or `defaultRequest` CPU and memory values for containers -specified in the limit range object are assigned to the container. - -.Container `LimitRange` object definition - -[source,yaml] ----- -apiVersion: "v1" -kind: "LimitRange" -metadata: - name: "resource-limits" <1> -spec: - limits: - - type: "Container" - max: - cpu: "2" <2> - memory: "1Gi" <3> - min: - cpu: "100m" <4> - memory: "4Mi" <5> - default: - cpu: "300m" <6> - memory: "200Mi" <7> - defaultRequest: - cpu: "200m" <8> - memory: "100Mi" <9> - maxLimitRequestRatio: - cpu: "10" <10> ----- -<1> The name of the LimitRange object. -<2> The maximum amount of CPU that a single container in a pod can request. -<3> The maximum amount of memory that a single container in a pod can request. -<4> The minimum amount of CPU that a single container in a pod can request. -Not setting a `min` value or setting `0` is unlimited, allowing the -Pod to consume more than the `max` CPU value. -<5> The minimum amount of memory that a single container in a pod can request. -Not setting a `min` value or setting `0` is unlimited, allowing the -Pod to consume more than the `max` memory value. -<6> The default amount of CPU that a container can use if not specified in the `Pod` spec. -<7> The default amount of memory that a container can use if not specified in the `Pod` spec. -<8> The default amount of CPU that a container can request if not specified in the `Pod` spec. -<9> The default amount of memory that a container can request if not specified in the `Pod` spec. -<10> The maximum limit-to-request ratio for a container. - - -[id="nodes-cluster-limit-pod-limits"] -== Pod limits - -A limit range allows you to specify the minimum and maximum CPU and memory limits for all containers -across a pod in a given project. To create a container in the project, the container CPU and memory -requests in the `Pod` spec must comply with the values set in the `LimitRange` object. If not, -the pod does not get created. - -Across all containers in a pod, the following must hold true: - -* The container CPU or memory request and limit must be greater than or equal to the -`min` resource constraints for pods that are specified in the `LimitRange` object. - -* The container CPU or memory request and limit must be less than or equal to the -`max` resource constraints for pods that are specified in the `LimitRange` object. - -* The ratio of the container limits to requests must be less than or equal to -the `maxLimitRequestRatio` constraint specified in the `LimitRange` object. - -.Pod `LimitRange` object definition - -[source,yaml] ----- -apiVersion: "v1" -kind: "LimitRange" -metadata: - name: "resource-limits" <1> -spec: - limits: - - type: "Pod" - max: - cpu: "2" <2> - memory: "1Gi" <3> - min: - cpu: "200m" <4> - memory: "6Mi" <5> - maxLimitRequestRatio: - cpu: "10" <6> ----- -<1> The name of the limit range object. -<2> The maximum amount of CPU that a pod can request across all containers. -<3> The maximum amount of memory that a pod can request across all containers. -<4> The minimum amount of CPU that a pod can request across all containers. -Not setting a `min` value or setting `0` is unlimited, allowing the pod to -consume more than the `max` CPU value. -<5> The minimum amount of memory that a pod can request across all containers. -Not setting a `min` value or setting `0` is unlimited, allowing the pod to -consume more than the `max` memory value. -<6> The maximum limit-to-request ratio for a container. - -[id="nodes-cluster-limit-image-limits"] -== Image limits - -A `LimitRange` object allows you to specify the maximum size of an image -that can be pushed to an internal registry. - -When pushing images to an internal registry, the following must hold true: - -* The size of the image must be less than or equal to the `max` size for -images that is specified in the `LimitRange` object. - -.Image `LimitRange` object definition - -[source,yaml] ----- -apiVersion: "v1" -kind: "LimitRange" -metadata: - name: "resource-limits" <1> -spec: - limits: - - type: openshift.io/Image - max: - storage: 1Gi <2> ----- -<1> The name of the `LimitRange` object. -<2> The maximum size of an image that can be pushed to an internal registry. - -ifdef::openshift-enterprise,openshift-origin[] -[NOTE] -==== -To prevent blobs that exceed the limit from being uploaded to the registry, the -registry must be configured to enforce quotas. -==== -endif::[] - -[WARNING] -==== -The image size is not always available in the manifest of an uploaded image. -This is especially the case for images built with Docker 1.10 or higher and -pushed to a v2 registry. If such an image is pulled with an older Docker daemon, -the image manifest is converted by the registry to schema v1 lacking all -the size information. No storage limit set on images prevent it from being -uploaded. - -link:https://github.com/openshift/origin/issues/7706[The issue] is being -addressed. -==== - -[id="nodes-cluster-limit-stream-limits"] -== Image stream limits - -A `LimitRange` object allows you to specify limits for image streams. - -For each image stream, the following must hold true: - -* The number of image tags in an `ImageStream` specification must be less -than or equal to the `openshift.io/image-tags` constraint in the `LimitRange` object. - -* The number of unique references to images in an `ImageStream` specification -must be less than or equal to the `openshift.io/images` constraint in the limit -range object. - -.Imagestream `LimitRange` object definition - -[source,yaml] ----- -apiVersion: "v1" -kind: "LimitRange" -metadata: - name: "resource-limits" <1> -spec: - limits: - - type: openshift.io/ImageStream - max: - openshift.io/image-tags: 20 <2> - openshift.io/images: 30 <3> ----- -<1> The name of the `LimitRange` object. -<2> The maximum number of unique image tags in the `imagestream.spec.tags` -parameter in imagestream spec. -<3> The maximum number of unique image references in the `imagestream.status.tags` -parameter in the `imagestream` spec. - -The `openshift.io/image-tags` resource represents unique image -references. Possible references are an `*ImageStreamTag*`, an -`*ImageStreamImage*` and a `*DockerImage*`. Tags can be created using -the `oc tag` and `oc import-image` commands. No distinction -is made between internal and external references. However, each unique reference -tagged in an `ImageStream` specification is counted just once. It does not -restrict pushes to an internal container image registry in any way, but is useful for tag -restriction. - -The `openshift.io/images` resource represents unique image names recorded in -image stream status. It allows for restriction of a number of images that can be -pushed to the internal registry. Internal and external references are not -distinguished. - -[id="nodes-cluster-limit-pvc-limits"] -== Persistent volume claim limits - -A `LimitRange` object allows you to restrict the storage requested in a persistent volume claim (PVC). - -Across all persistent volume claims in a project, the following must hold true: - -* The resource request in a persistent volume claim (PVC) must be greater than or equal -the `min` constraint for PVCs that is specified in the `LimitRange` object. - -* The resource request in a persistent volume claim (PVC) must be less than or equal -the `max` constraint for PVCs that is specified in the `LimitRange` object. - -.PVC `LimitRange` object definition - -[source,yaml] ----- -apiVersion: "v1" -kind: "LimitRange" -metadata: - name: "resource-limits" <1> -spec: - limits: - - type: "PersistentVolumeClaim" - min: - storage: "2Gi" <2> - max: - storage: "50Gi" <3> ----- -<1> The name of the `LimitRange` object. -<2> The minimum amount of storage that can be requested in a persistent volume claim. -<3> The maximum amount of storage that can be requested in a persistent volume claim. - -ifdef::openshift-dedicated[] -[id="nodes-cluster-limit-project-limits"] -== Project limits - -You can enforce different limits on the number of projects that -your users can create, as well as on managing limits and quotas on project -resources. -endif::openshift-dedicated[] diff --git a/modules/nodes-cluster-limit-ranges-viewing.adoc b/modules/nodes-cluster-limit-ranges-viewing.adoc deleted file mode 100644 index 550e5b321b88..000000000000 --- a/modules/nodes-cluster-limit-ranges-viewing.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/cluster/limit-ranges.adoc - -[id="nodes-cluster-limit-viewing_{context}"] -= Viewing a limit - -You can view any limits defined in a project by navigating in the web -console to the project's *Quota* page. - -You can also use the CLI to view limit range details: - -. Get the list of `LimitRange` object defined in the project. For example, for a -project called *demoproject*: -+ ----- -$ oc get limits -n demoproject ----- -+ ----- -NAME CREATED AT -resource-limits 2020-07-15T17:14:23Z ----- - -. Describe the `LimitRange` object you are interested in, for example the -`resource-limits` limit range: -+ ----- -$ oc describe limits resource-limits -n demoproject ----- -+ ----- -Name: resource-limits -Namespace: demoproject -Type Resource Min Max Default Request Default Limit Max Limit/Request Ratio ----- -------- --- --- --------------- ------------- ----------------------- -Pod cpu 200m 2 - - - -Pod memory 6Mi 1Gi - - - -Container cpu 100m 2 200m 300m 10 -Container memory 4Mi 1Gi 100Mi 200Mi - -openshift.io/Image storage - 1Gi - - - -openshift.io/ImageStream openshift.io/image - 12 - - - -openshift.io/ImageStream openshift.io/image-tags - 10 - - - -PersistentVolumeClaim storage - 50Gi - - - ----- - diff --git a/modules/nodes-cluster-node-overcommit.adoc b/modules/nodes-cluster-node-overcommit.adoc deleted file mode 100644 index 4c09d4c871a1..000000000000 --- a/modules/nodes-cluster-node-overcommit.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/clusters/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-node-overcommit_{context}"] -= Node-level overcommit - -You can use various ways to control overcommit on specific nodes, such as quality of service (QOS) -guarantees, CPU limits, or reserve resources. You can also disable overcommit for specific nodes -and specific projects. diff --git a/modules/nodes-cluster-overcommit-about.adoc b/modules/nodes-cluster-overcommit-about.adoc deleted file mode 100644 index ca00e3634ced..000000000000 --- a/modules/nodes-cluster-overcommit-about.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc - -[id="nodes-cluster-overcommit-about_{context}"] -= Understanding overcommitment - -Requests and limits enable administrators to allow and manage the overcommitment of resources on a node. The scheduler uses requests for scheduling your container and providing a minimum service guarantee. Limits constrain the amount of compute resource that may be consumed on your node. - -{product-title} administrators can control the level of overcommit and manage container density on nodes by configuring masters to override the ratio between request and limit set on developer containers. In conjunction with a per-project `LimitRange` object specifying limits and defaults, this adjusts the container limit and request to achieve the desired level of overcommit. - -[NOTE] -==== -That these overrides have no effect if no limits have been set on containers. Create a `LimitRange` object with default limits, per individual project, or in the project template, to ensure that the overrides apply. -==== - -After these overrides, the container limits and requests must still be validated by any `LimitRange` object in the project. It is possible, for example, for developers to specify a limit close to the minimum limit, and have the request then be overridden below the minimum limit, causing the pod to be forbidden. This unfortunate user experience should be addressed with future work, but for now, configure this capability and `LimitRange` objects with caution. - - diff --git a/modules/nodes-cluster-overcommit-buffer-chunk.adoc b/modules/nodes-cluster-overcommit-buffer-chunk.adoc deleted file mode 100644 index dbec0821a566..000000000000 --- a/modules/nodes-cluster-overcommit-buffer-chunk.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * cluster-logging-collector.adoc - - -[id="understandin-fluentd-buffering_{context}"] -= Understanding Buffer Chunk Limiting for Fluentd - -If the Fluentd logger is unable to keep up with a high number of logs, it will need -to switch to file buffering to reduce memory usage and prevent data loss. - -Fluentd file buffering stores records in _chunks_. Chunks are stored in _buffers_. - -[NOTE] -==== -To modify the `FILE_BUFFER_LIMIT` or `BUFFER_SIZE_LIMIT` parameters -in the Fluentd daemonset as described below, you must set OpenShift Logging to the unmanaged state. -Operators in an unmanaged state are unsupported and the cluster administrator assumes full control of the individual component configurations and upgrades. -==== - -The Fluentd `buffer_chunk_limit` is determined by the environment variable -`BUFFER_SIZE_LIMIT`, which has the default value `8m`. The file buffer size per -output is determined by the environment variable `FILE_BUFFER_LIMIT`, which has -the default value `256Mi`. The permanent volume size must be larger than -`FILE_BUFFER_LIMIT` multiplied by the output. - -On the Fluentd pods, permanent volume */var/lib/fluentd* should be -prepared by the PVC or hostmount, for example. That area is then used for the -file buffers. - -The `buffer_type` and `buffer_path` are configured in the Fluentd configuration files as -follows: - ----- -$ egrep "buffer_type|buffer_path" *.conf -output-es-config.conf: - buffer_type file - buffer_path `/var/lib/fluentd/buffer-output-es-config` -output-es-ops-config.conf: - buffer_type file - buffer_path `/var/lib/fluentd/buffer-output-es-ops-config` ----- - -The Fluentd `buffer_queue_limit` is the value of the variable `BUFFER_QUEUE_LIMIT`. This value is `32` by default. - -The environment variable `BUFFER_QUEUE_LIMIT` is calculated as `(FILE_BUFFER_LIMIT / (number_of_outputs * BUFFER_SIZE_LIMIT))`. - -If the `BUFFER_QUEUE_LIMIT` variable has the default set of values: - -* `FILE_BUFFER_LIMIT = 256Mi` -* `number_of_outputs = 1` -* `BUFFER_SIZE_LIMIT = 8Mi` - -The value of `buffer_queue_limit` will be `32`. To change the `buffer_queue_limit`, you must change the value of `FILE_BUFFER_LIMIT`. - -In this formula, `number_of_outputs` is `1` if all the logs are sent to a single resource, and it is incremented by `1` for each additional resource. For example, the value of `number_of_outputs` is: - - * `1` - if all logs are sent to a single Elasticsearch pod - * `2` - if application logs are sent to an Elasticsearch pod and ops logs are sent to -another Elasticsearch pod - * `4` - if application logs are sent to an Elasticsearch pod, ops logs are sent to -another Elasticsearch pod, and both of them are forwarded to other Fluentd instances diff --git a/modules/nodes-cluster-overcommit-configure-nodes.adoc b/modules/nodes-cluster-overcommit-configure-nodes.adoc deleted file mode 100644 index 0ddba437f813..000000000000 --- a/modules/nodes-cluster-overcommit-configure-nodes.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-overcommit-configure-nodes_{context}"] -= Understanding nodes overcommitment - -In an overcommitted environment, it is important to properly configure your node to provide best system behavior. - -When the node starts, it ensures that the kernel tunable flags for memory -management are set properly. The kernel should never fail memory allocations -unless it runs out of physical memory. - -To ensure this behavior, {product-title} configures the kernel to always overcommit -memory by setting the `vm.overcommit_memory` parameter to `1`, overriding the -default operating system setting. - -{product-title} also configures the kernel not to panic when it runs out of memory -by setting the `vm.panic_on_oom` parameter to `0`. A setting of 0 instructs the -kernel to call oom_killer in an Out of Memory (OOM) condition, which kills -processes based on priority - -You can view the current setting by running the following commands on your nodes: - -[source,terminal] ----- -$ sysctl -a |grep commit ----- - -.Example output -[source,terminal] ----- -vm.overcommit_memory = 1 ----- - -[source,terminal] ----- -$ sysctl -a |grep panic ----- - -.Example output -[source,terminal] ----- -vm.panic_on_oom = 0 ----- - -[NOTE] -==== -The above flags should already be set on nodes, and no further action is -required. -==== - -You can also perform the following configurations for each node: - -* Disable or enforce CPU limits using CPU CFS quotas - -* Reserve resources for system processes - -* Reserve memory across quality of service tiers diff --git a/modules/nodes-cluster-overcommit-node-disable.adoc b/modules/nodes-cluster-overcommit-node-disable.adoc deleted file mode 100644 index 5efe6a6051d0..000000000000 --- a/modules/nodes-cluster-overcommit-node-disable.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-overcommit-node-disable_{context}"] -= Disabling overcommitment for a node - -When enabled, overcommitment can be disabled on each node. - -.Procedure - -To disable overcommitment in a node run the following command on that node: - -[source,terminal] ----- -$ sysctl -w vm.overcommit_memory=0 ----- diff --git a/modules/nodes-cluster-overcommit-node-enforcing.adoc b/modules/nodes-cluster-overcommit-node-enforcing.adoc deleted file mode 100644 index e45582e353af..000000000000 --- a/modules/nodes-cluster-overcommit-node-enforcing.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-overcommit-node-enforcing_{context}"] - -= Disabling or enforcing CPU limits using CPU CFS quotas - -Nodes by default enforce specified CPU limits using the Completely Fair Scheduler (CFS) quota support in the Linux kernel. - -If you disable CPU limit enforcement, it is important to understand the impact on your node: - -* If a container has a CPU request, the request continues to be enforced by CFS shares in the Linux kernel. -* If a container does not have a CPU request, but does have a CPU limit, the CPU request defaults to the specified CPU limit, and is enforced by CFS shares in the Linux kernel. -* If a container has both a CPU request and limit, the CPU request is enforced by CFS shares in the Linux kernel, and the CPU limit has no impact on the node. - -.Prerequisites - -. Obtain the label associated with the static `MachineConfigPool` CRD for the type of node you want to configure. Perform one of the following steps: - -.. View the machine config pool: -+ -[source,terminal] ----- -$ oc describe machineconfigpool <name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe machineconfigpool worker ----- -+ -.Example output -[source,terminal] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool -metadata: - creationTimestamp: 2019-02-08T14:52:39Z - generation: 1 - labels: - custom-kubelet: small-pods <1> ----- -<1> If a label has been added it appears under `labels`. - -.. If the label is not present, add a key/value pair: -+ -[source,terminal] ----- -$ oc label machineconfigpool worker custom-kubelet=small-pods ----- - -.Procedure - -. Create a custom resource (CR) for your configuration change. -+ -.Sample configuration for a disabling CPU limits -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: disable-cpu-units <1> -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: small-pods <2> - kubeletConfig: - cpuCfsQuota: <3> - - "false" ----- -<1> Assign a name to CR. -<2> Specify the label to apply the configuration change. -<3> Set the `cpuCfsQuota` parameter to `false`. - diff --git a/modules/nodes-cluster-overcommit-node-resources.adoc b/modules/nodes-cluster-overcommit-node-resources.adoc deleted file mode 100644 index 31493079187e..000000000000 --- a/modules/nodes-cluster-overcommit-node-resources.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-overcommit-node-resources_{context}"] - -= Reserving resources for system processes - -To provide more reliable scheduling and minimize node resource overcommitment, -each node can reserve a portion of its resources for use by system daemons -that are required to run on your node for your cluster to function. -In particular, it is recommended that you reserve resources for incompressible resources such as memory. - -.Procedure - -To explicitly reserve resources for non-pod processes, allocate node resources by specifying resources -available for scheduling. -For more details, see Allocating Resources for Nodes. diff --git a/modules/nodes-cluster-overcommit-project-disable.adoc b/modules/nodes-cluster-overcommit-project-disable.adoc deleted file mode 100644 index 3173c6d36b6e..000000000000 --- a/modules/nodes-cluster-overcommit-project-disable.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-overcommit-project-disable_{context}"] -= Disabling overcommitment for a project - -When enabled, overcommitment can be disabled per-project. -For example, you can allow infrastructure components to be configured independently of overcommitment. - -.Procedure - -To disable overcommitment in a project: - -. Edit the project object file - -. Add the following annotation: -+ -[source,yaml] ----- -quota.openshift.io/cluster-resource-override-enabled: "false" ----- - -. Create the project object: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- diff --git a/modules/nodes-cluster-overcommit-qos-about.adoc b/modules/nodes-cluster-overcommit-qos-about.adoc deleted file mode 100644 index b0a5205720d0..000000000000 --- a/modules/nodes-cluster-overcommit-qos-about.adoc +++ /dev/null @@ -1,102 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-overcommit-qos-about_{context}"] -= Understanding overcomitment and quality of service classes - -A node is _overcommitted_ when it has a pod scheduled that makes no request, or -when the sum of limits across all pods on that node exceeds available machine -capacity. - -In an overcommitted environment, it is possible that the pods on the node will -attempt to use more compute resource than is available at any given point in -time. When this occurs, the node must give priority to one pod over another. The -facility used to make this decision is referred to as a Quality of Service (QoS) -Class. - -For each compute resource, a container is divided into one of three QoS classes -with decreasing order of priority: - -.Quality of Service Classes -[options="header",cols="1,1,5"] -|=== -|Priority |Class Name |Description - -|1 (highest) -|*Guaranteed* -|If limits and optionally requests are set (not equal to 0) for all resources -and they are equal, then the container is classified as *Guaranteed*. - -|2 -|*Burstable* -|If requests and optionally limits are set (not equal to 0) for all resources, -and they are not equal, then the container is classified as *Burstable*. - -|3 (lowest) -|*BestEffort* -|If requests and limits are not set for any of the resources, then the container -is classified as *BestEffort*. -|=== - -Memory is an incompressible resource, so in low memory situations, containers -that have the lowest priority are terminated first: - -- *Guaranteed* containers are considered top priority, and are guaranteed to -only be terminated if they exceed their limits, or if the system is under memory -pressure and there are no lower priority containers that can be evicted. -- *Burstable* containers under system memory pressure are more likely to be -terminated once they exceed their requests and no other *BestEffort* containers -exist. -- *BestEffort* containers are treated with the lowest priority. Processes in -these containers are first to be terminated if the system runs out of memory. - -[id="qos-about-reserve_{context}"] -== Understanding how to reserve memory across quality of service tiers - -You can use the `qos-reserved` parameter to specify a percentage of memory to be reserved -by a pod in a particular QoS level. This feature attempts to reserve requested resources to exclude pods -from lower OoS classes from using resources requested by pods in higher QoS classes. - -{product-title} uses the `qos-reserved` parameter as follows: - -- A value of `qos-reserved=memory=100%` will prevent the `Burstable` and `BestEffort` QOS classes from consuming memory -that was requested by a higher QoS class. This increases the risk of inducing OOM -on `BestEffort` and `Burstable` workloads in favor of increasing memory resource guarantees -for `Guaranteed` and `Burstable` workloads. - -- A value of `qos-reserved=memory=50%` will allow the `Burstable` and `BestEffort` QOS classes -to consume half of the memory requested by a higher QoS class. - -- A value of `qos-reserved=memory=0%` -will allow a `Burstable` and `BestEffort` QoS classes to consume up to the full node -allocatable amount if available, but increases the risk that a `Guaranteed` workload -will not have access to requested memory. This condition effectively disables this feature. - -[id="qos-about-swap_{context}"] -= Understanding swap memory and QOS - -You can disable swap by default on your nodes to preserve quality of -service (QOS) guarantees. Otherwise, physical resources on a node can oversubscribe, -affecting the resource guarantees the Kubernetes scheduler makes during pod -placement. - -For example, if two guaranteed pods have reached their memory limit, each -container could start using swap memory. Eventually, if there is not enough swap -space, processes in the pods can be terminated due to the system being -oversubscribed. - -Failing to disable swap results in nodes not recognizing that they are -experiencing *MemoryPressure*, resulting in pods not receiving the memory they -made in their scheduling request. As a result, additional pods are placed on the -node to further increase memory pressure, ultimately increasing your risk of -experiencing a system out of memory (OOM) event. - -[IMPORTANT] -==== -If swap is enabled, any out-of-resource handling eviction thresholds for available memory will not work as -expected. Take advantage of out-of-resource handling to allow pods to be evicted -from a node when it is under memory pressure, and rescheduled on an alternative -node that has no such pressure. -==== diff --git a/modules/nodes-cluster-overcommit-resource-requests.adoc b/modules/nodes-cluster-overcommit-resource-requests.adoc deleted file mode 100644 index 13269625505c..000000000000 --- a/modules/nodes-cluster-overcommit-resource-requests.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-overcommit-resource-requests_{context}"] -= Resource requests and overcommitment - -For each compute resource, a container may specify a resource request and limit. -Scheduling decisions are made based on the request to ensure that a node has -enough capacity available to meet the requested value. If a container specifies -limits, but omits requests, the requests are defaulted to the limits. A -container is not able to exceed the specified limit on the node. - -The enforcement of limits is dependent upon the compute resource type. If a -container makes no request or limit, the container is scheduled to a node with -no resource guarantees. In practice, the container is able to consume as much of -the specified resource as is available with the lowest local priority. In low -resource situations, containers that specify no resource requests are given the -lowest quality of service. - -Scheduling is based on resources requested, while quota and hard limits refer -to resource limits, which can be set higher than requested resources. The -difference between request and limit determines the level of overcommit; -for instance, if a container is given a memory request of 1Gi and a memory limit -of 2Gi, it is scheduled based on the 1Gi request being available on the node, -but could use up to 2Gi; so it is 200% overcommitted. diff --git a/modules/nodes-cluster-overcommit-resources-containers.adoc b/modules/nodes-cluster-overcommit-resources-containers.adoc deleted file mode 100644 index c6a1c9d127a7..000000000000 --- a/modules/nodes-cluster-overcommit-resources-containers.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-overcommit-reserving-memory_{context}"] -= Understanding compute resources and containers -The node-enforced behavior for compute resources is specific to the resource -type. - -[id="understanding-container-CPU-requests_{context}"] -== Understanding container CPU requests - -A container is guaranteed the amount of CPU it requests and is additionally able -to consume excess CPU available on the node, up to any limit specified by the -container. If multiple containers are attempting to use excess CPU, CPU time is -distributed based on the amount of CPU requested by each container. - -For example, if one container requested 500m of CPU time and another container -requested 250m of CPU time, then any extra CPU time available on the node is -distributed among the containers in a 2:1 ratio. If a container specified a -limit, it will be throttled not to use more CPU than the specified limit. -CPU requests are enforced using the CFS shares support in the Linux kernel. By -default, CPU limits are enforced using the CFS quota support in the Linux kernel -over a 100ms measuring interval, though this can be disabled. - -[id="understanding-memory-requests-container_{context}"] -== Understanding container memory requests - -A container is guaranteed the amount of memory it requests. A container can use -more memory than requested, but once it exceeds its requested amount, it could -be terminated in a low memory situation on the node. -If a container uses less memory than requested, it will not be terminated unless -system tasks or daemons need more memory than was accounted for in the node's -resource reservation. If a container specifies a limit on memory, it is -immediately terminated if it exceeds the limit amount. - -//// -Not in 4.1 -[id="containers-ephemeral_{context}"] -== Understanding containers and ephemeral storage - -[NOTE] -==== -The {product-title} cluster uses ephemeral storage to store information that does not have to persist after the cluster is destroyed. -==== - -A container is guaranteed the amount of ephemeral storage it requests. A -container can use more ephemeral storage than requested, but once it exceeds its -requested amount, it can be terminated if the available ephemeral disk space gets -too low. - -If a container uses less ephemeral storage than requested, it will not be -terminated unless system tasks or daemons need more local ephemeral storage than -was accounted for in the node's resource reservation. If a container specifies a -limit on ephemeral storage, it is immediately terminated if it exceeds the limit -amount. -//// diff --git a/modules/nodes-cluster-project-overcommit.adoc b/modules/nodes-cluster-project-overcommit.adoc deleted file mode 100644 index d72f35148505..000000000000 --- a/modules/nodes-cluster-project-overcommit.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/clusters/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-project-overcommit_{context}"] -= Project-level limits - -To help control overcommit, you can set per-project resource limit ranges, -specifying memory and CPU limits and defaults for a project that overcommit -cannot exceed. - -For information on project-level resource limits, see Additional Resources. - -Alternatively, you can disable overcommitment for specific projects. diff --git a/modules/nodes-cluster-resource-configure-about.adoc b/modules/nodes-cluster-resource-configure-about.adoc deleted file mode 100644 index ed05e2e0e489..000000000000 --- a/modules/nodes-cluster-resource-configure-about.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-resource-configure.adoc - -[id="nodes-cluster-resource-configure-about_{context}"] -= Understanding managing application memory - -It is recommended to fully read the overview of how {product-title} manages -Compute Resources before proceeding. - -For each kind of resource (memory, CPU, storage), {product-title} allows -optional *request* and *limit* values to be placed on each container in a -pod. - -Note the following about memory requests and memory limits: - -* *Memory request* - - - The memory request value, if specified, influences the {product-title} - scheduler. The scheduler considers the memory request when scheduling a - container to a node, then fences off the requested memory on the chosen node - for the use of the container. - - - If a node’s memory is exhausted, {product-title} prioritizes evicting its - containers whose memory usage most exceeds their memory request. In serious - cases of memory exhaustion, the node OOM killer may select and kill a - process in a container based on a similar metric. - - - The cluster administrator can assign quota or assign default values for the memory request value. - - - The cluster administrator can override the memory request values that a developer specifies, to manage cluster overcommit. - -* *Memory limit* - - - The memory limit value, if specified, provides a hard limit on the memory - that can be allocated across all the processes in a container. - - - If the memory allocated by all of the processes in a container exceeds the - memory limit, the node Out of Memory (OOM) killer will immediately select and kill a - process in the container. - - - If both memory request and limit are specified, the memory limit value must - be greater than or equal to the memory request. - - - The cluster administrator can assign quota or assign default values for the memory limit value. - - - The minimum memory limit is 12 MB. If a container fails to start due to a `Cannot allocate memory` pod event, the memory limit is too low. -Either increase or remove the memory limit. Removing the limit allows pods to consume unbounded node resources. - -[id="nodes-cluster-resource-configure-about-memory_{context}"] -== Managing application memory strategy - -The steps for sizing application memory on {product-title} are as follows: - -. *Determine expected container memory usage* -+ -Determine expected mean and peak container memory usage, empirically if -necessary (for example, by separate load testing). Remember to consider all the -processes that may potentially run in parallel in the container: for example, -does the main application spawn any ancillary scripts? - -. *Determine risk appetite* -+ -Determine risk appetite for eviction. If the risk appetite is low, the -container should request memory according to the expected peak usage plus a -percentage safety margin. If the risk appetite is higher, it may be more -appropriate to request memory according to the expected mean usage. - -. *Set container memory request* -+ -Set container memory request based on the above. The more accurately the -request represents the application memory usage, the better. If the request is -too high, cluster and quota usage will be inefficient. If the request is too -low, the chances of application eviction increase. - -. *Set container memory limit, if required* -+ -Set container memory limit, if required. Setting a limit has the effect of -immediately killing a container process if the combined memory usage of all -processes in the container exceeds the limit, and is therefore a mixed blessing. -On the one hand, it may make unanticipated excess memory usage obvious early -("fail fast"); on the other hand it also terminates processes abruptly. -+ -Note that some {product-title} clusters may require a limit value to be set; -some may override the request based on the limit; and some application images -rely on a limit value being set as this is easier to detect than a request -value. -+ -If the memory limit is set, it should not be set to less than the expected peak -container memory usage plus a percentage safety margin. - -. *Ensure application is tuned* -+ -Ensure application is tuned with respect to configured request and limit values, -if appropriate. This step is particularly relevant to applications which pool -memory, such as the JVM. The rest of this page discusses this. diff --git a/modules/nodes-cluster-resource-configure-evicted.adoc b/modules/nodes-cluster-resource-configure-evicted.adoc deleted file mode 100644 index 3a5cc4725177..000000000000 --- a/modules/nodes-cluster-resource-configure-evicted.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-resource-configure.adoc - -[id="nodes-cluster-resource-configure-evicted_{context}"] -= Understanding pod eviction - -{product-title} may evict a pod from its node when the node’s memory is -exhausted. Depending on the extent of memory exhaustion, the eviction may or -may not be graceful. Graceful eviction implies the main process (PID 1) of each -container receiving a SIGTERM signal, then some time later a SIGKILL signal if -the process has not exited already. Non-graceful eviction implies the main -process of each container immediately receiving a SIGKILL signal. - -An evicted pod has phase *Failed* and reason *Evicted*. It will not be -restarted, regardless of the value of `restartPolicy`. However, controllers -such as the replication controller will notice the pod’s failed status and create -a new pod to replace the old one. - -[source,terminal] ----- -$ oc get pod test ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -test 0/1 Evicted 0 1m ----- - -[source,terminal] ----- -$ oc get pod test -o yaml ----- - -.Example output -[source,terminal] ----- -... -status: - message: 'Pod The node was low on resource: [MemoryPressure].' - phase: Failed - reason: Evicted ----- diff --git a/modules/nodes-cluster-resource-configure-jdk.adoc b/modules/nodes-cluster-resource-configure-jdk.adoc deleted file mode 100644 index 0c9c9225e346..000000000000 --- a/modules/nodes-cluster-resource-configure-jdk.adoc +++ /dev/null @@ -1,106 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-resource-configure.adoc - -[id="nodes-cluster-resource-configure-jdk_{context}"] -= Understanding OpenJDK settings for {product-title} - -The default OpenJDK settings do not work well with containerized -environments. As a result, some additional Java memory -settings must always be provided whenever running the OpenJDK in a container. - -The JVM memory layout is complex, version dependent, and describing it in detail -is beyond the scope of this documentation. However, as a starting point for -running OpenJDK in a container, at least the following three memory-related -tasks are key: - -. Overriding the JVM maximum heap size. - -. Encouraging the JVM to release unused memory to the operating system, if - appropriate. - -. Ensuring all JVM processes within a container are appropriately configured. - -Optimally tuning JVM workloads for running in a container is beyond the scope of -this documentation, and may involve setting multiple additional JVM options. - -[id="nodes-cluster-resource-configure-jdk-heap_{context}"] -== Understanding how to override the JVM maximum heap size - -For many Java workloads, the JVM heap is the largest single consumer of memory. -Currently, the OpenJDK defaults to allowing up to 1/4 (1/`-XX:MaxRAMFraction`) -of the compute node’s memory to be used for the heap, regardless of whether the -OpenJDK is running in a container or not. It is therefore *essential* to -override this behavior, especially if a container memory limit is also set. - -There are at least two ways the above can be achieved: - -. If the container memory limit is set and the experimental options are - supported by the JVM, set `-XX:+UnlockExperimentalVMOptions - -XX:+UseCGroupMemoryLimitForHeap`. -+ -This sets `-XX:MaxRAM` to the container memory limit, and the maximum heap size -(`-XX:MaxHeapSize` / `-Xmx`) to 1/`-XX:MaxRAMFraction` (1/4 by default). - -. Directly override one of `-XX:MaxRAM`, `-XX:MaxHeapSize` or `-Xmx`. -+ -This option involves hard-coding a value, but has the advantage of allowing a -safety margin to be calculated. - -[id="nodes-cluster-resource-configure-jdk-unused_{context}"] -== Understanding how to encourage the JVM to release unused memory to the operating system - -By default, the OpenJDK does not aggressively return unused memory to the -operating system. This may be appropriate for many containerized Java -workloads, but notable exceptions include workloads where additional active -processes co-exist with a JVM within a container, whether those additional -processes are native, additional JVMs, or a combination of the two. - -The {product-title} Jenkins maven slave image uses the following JVM arguments to encourage the JVM -to release unused memory to the operating system: - -[source,terminal] ----- --XX:+UseParallelGC --XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=10 -XX:GCTimeRatio=4 --XX:AdaptiveSizePolicyWeight=90. ----- - -These arguments are intended to return heap -memory to the operating system whenever allocated memory exceeds 110% of in-use -memory (`-XX:MaxHeapFreeRatio`), spending up to 20% of CPU time in the garbage -collector (`-XX:GCTimeRatio`). At no time will the application heap allocation -be less than the initial heap allocation (overridden by `-XX:InitialHeapSize` / -`-Xms`). Detailed additional information is available -link:https://developers.redhat.com/blog/2014/07/15/dude-wheres-my-paas-memory-tuning-javas-footprint-in-openshift-part-1/[Tuning Java's footprint in OpenShift (Part 1)], -link:https://developers.redhat.com/blog/2014/07/22/dude-wheres-my-paas-memory-tuning-javas-footprint-in-openshift-part-2/[Tuning Java's footprint in OpenShift (Part 2)], -and at -link:https://developers.redhat.com/blog/2017/04/04/openjdk-and-containers/[OpenJDK -and Containers]. - -[id="nodes-cluster-resource-configure-jdk-proc_{context}"] -== Understanding how to ensure all JVM processes within a container are appropriately configured - -In the case that multiple JVMs run in the same container, it is essential to -ensure that they are all configured appropriately. For many workloads it will -be necessary to grant each JVM a percentage memory budget, leaving a perhaps -substantial additional safety margin. - -Many Java tools use different environment variables (`JAVA_OPTS`, `GRADLE_OPTS`, -`MAVEN_OPTS`, and so on) to configure their JVMs and it can be challenging to ensure -that the right settings are being passed to the right JVM. - -The `JAVA_TOOL_OPTIONS` environment variable is always respected by the OpenJDK, -and values specified in `JAVA_TOOL_OPTIONS` will be overridden by other options -specified on the JVM command line. By default, to ensure that these options are -used by default for all JVM workloads run in the slave image, the {product-title} Jenkins -maven slave image sets: - -[source,terminal] ----- -JAVA_TOOL_OPTIONS="-XX:+UnlockExperimentalVMOptions --XX:+UseCGroupMemoryLimitForHeap -Dsun.zip.disableMemoryMapping=true" ----- - -This does not guarantee that additional options are not required, but is -intended to be a helpful starting point. diff --git a/modules/nodes-cluster-resource-configure-oom.adoc b/modules/nodes-cluster-resource-configure-oom.adoc deleted file mode 100644 index 21195a810b87..000000000000 --- a/modules/nodes-cluster-resource-configure-oom.adoc +++ /dev/null @@ -1,140 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-resource-configure.adoc - -[id="nodes-cluster-resource-configure-oom_{context}"] -= Understanding OOM kill policy - -{product-title} can kill a process in a container if the total memory usage of -all the processes in the container exceeds the memory limit, or in serious cases -of node memory exhaustion. - -When a process is Out of Memory (OOM) killed, this might result in the container -exiting immediately. If the container PID 1 process receives the *SIGKILL*, the -container will exit immediately. Otherwise, the container behavior is -dependent on the behavior of the other processes. - -For example, a container process exited with code 137, indicating it received a SIGKILL signal. - -If the container does not exit immediately, an OOM kill is detectable as -follows: - -. Access the pod using a remote shell: -+ -[source,terminal] ----- -# oc rsh test ----- - -. Run the following command to see the current OOM kill count in `/sys/fs/cgroup/memory/memory.oom_control`: -+ -[source,terminal] ----- -$ grep '^oom_kill ' /sys/fs/cgroup/memory/memory.oom_control -oom_kill 0 ----- - -. Run the following command to provoke an OOM kill: -+ -[source,terminal] ----- -$ sed -e '' </dev/zero ----- -+ -.Example output -[source,terminal] ----- -Killed ----- - -. Run the following command to view the exit status of the `sed` command: -+ -[source,terminal] ----- -$ echo $? ----- -+ -.Example output -[source,terminal] ----- -137 ----- -+ -The `137` code indicates the container process exited with code 137, indicating it received a SIGKILL signal. - -. Run the following command to see that the OOM kill counter in `/sys/fs/cgroup/memory/memory.oom_control` incremented: -+ -[source,terminal] ----- -$ grep '^oom_kill ' /sys/fs/cgroup/memory/memory.oom_control -oom_kill 1 ----- -+ -If one or more processes in a pod are OOM killed, when the pod subsequently -exits, whether immediately or not, it will have phase *Failed* and reason -*OOMKilled*. An OOM-killed pod might be restarted depending on the value of -`restartPolicy`. If not restarted, controllers such as the -replication controller will notice the pod’s failed status and create a new pod -to replace the old one. -+ -Use the follwing command to get the pod status: -+ -[source,terminal] ----- -$ oc get pod test ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -test 0/1 OOMKilled 0 1m ----- - -* If the pod has not restarted, run the following command to view the pod: -+ -[source,terminal] ----- -$ oc get pod test -o yaml ----- -+ -.Example output -[source,terminal] ----- -... -status: - containerStatuses: - - name: test - ready: false - restartCount: 0 - state: - terminated: - exitCode: 137 - reason: OOMKilled - phase: Failed ----- - -* If restarted, run the following command to view the pod: -+ -[source,terminal] ----- -$ oc get pod test -o yaml ----- -+ -.Example output -[source,terminal] ----- -... -status: - containerStatuses: - - name: test - ready: true - restartCount: 1 - lastState: - terminated: - exitCode: 137 - reason: OOMKilled - state: - running: - phase: Running ----- diff --git a/modules/nodes-cluster-resource-configure-request-limit.adoc b/modules/nodes-cluster-resource-configure-request-limit.adoc deleted file mode 100644 index f5e0a45eaae3..000000000000 --- a/modules/nodes-cluster-resource-configure-request-limit.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-resource-configure.adoc - -[id="nodes-cluster-resource-configure-request-limit_{context}"] -= Finding the memory request and limit from within a pod - -An application wishing to dynamically discover its memory request and limit from -within a pod should use the Downward API. - -.Procedure - -. Configure the pod to add the `MEMORY_REQUEST` and `MEMORY_LIMIT` stanzas: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: test -spec: - containers: - - name: test - image: fedora:latest - command: - - sleep - - "3600" - env: - - name: MEMORY_REQUEST <1> - valueFrom: - resourceFieldRef: - containerName: test - resource: requests.memory - - name: MEMORY_LIMIT <2> - valueFrom: - resourceFieldRef: - containerName: test - resource: limits.memory - resources: - requests: - memory: 384Mi - limits: - memory: 512Mi ----- -<1> Add this stanza to discover the application memory request value. -<2> Add this stanza to discover the application memory limit value. - -. Create the pod: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- - -. Access the pod using a remote shell: -+ -[source,terminal] ----- -$ oc rsh test ----- - -. Check that the requested values were applied: -+ -[source,terminal] ----- -$ env | grep MEMORY | sort ----- -+ -.Example output -[source,terminal] ----- -MEMORY_LIMIT=536870912 -MEMORY_REQUEST=402653184 ----- - -[NOTE] -==== -The memory limit value can also be read from inside the container by the -`/sys/fs/cgroup/memory/memory.limit_in_bytes` file. -==== diff --git a/modules/nodes-cluster-resource-configure.adoc b/modules/nodes-cluster-resource-configure.adoc deleted file mode 100644 index d92ff32d68d2..000000000000 --- a/modules/nodes-cluster-resource-configure.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/clusters/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-resource-configure_{context}"] -= Configuring cluster-level overcommit - - -The Cluster Resource Override Operator requires a `ClusterResourceOverride` custom resource (CR) -and a label for each project where you want the Operator to control overcommit. - -.Prerequisites - -* The Cluster Resource Override Operator has no effect if limits have not -been set on containers. You must specify default limits for a project using a `LimitRange` object or configure limits in `Pod` specs for the overrides to apply. - -.Procedure - -To modify cluster-level overcommit: - -. Edit the `ClusterResourceOverride` CR: -+ -[source,yaml] ----- -apiVersion: operator.autoscaling.openshift.io/v1 -kind: ClusterResourceOverride -metadata: -- name: cluster -spec: - memoryRequestToLimitPercent: 50 <1> - cpuRequestToLimitPercent: 25 <2> - limitCPUToMemoryPercent: 200 <3> ----- -<1> Optional. Specify the percentage to override the container memory limit, if used, between 1-100. The default is 50. -<2> Optional. Specify the percentage to override the container CPU limit, if used, between 1-100. The default is 25. -<3> Optional. Specify the percentage to override the container memory limit, if used. Scaling 1Gi of RAM at 100 percent is equal to 1 CPU core. This is processed prior to overriding the CPU request, if configured. The default is 200. - -. Ensure the following label has been added to the Namespace object for each project where you want the Cluster Resource Override Operator to control overcommit: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - -.... - - labels: - clusterresourceoverrides.admission.autoscaling.openshift.io/enabled: "true" <1> - -.... - ----- -<1> Add this label to each project. diff --git a/modules/nodes-cluster-resource-levels-about.adoc b/modules/nodes-cluster-resource-levels-about.adoc deleted file mode 100644 index be291ce0715a..000000000000 --- a/modules/nodes-cluster-resource-levels-about.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-resource-about.adoc - -[id="nodes-cluster-resource-levels-about_{context}"] -= Understanding the {product-title} cluster capacity tool - -The cluster capacity tool simulates a sequence of scheduling decisions to -determine how many instances of an input pod can be scheduled on the cluster -before it is exhausted of resources to provide a more accurate estimation. - -[NOTE] -==== -The remaining allocatable capacity is a rough estimation, because it does not -count all of the resources being distributed among nodes. It analyzes only the -remaining resources and estimates the available capacity that is still -consumable in terms of a number of instances of a pod with given requirements -that can be scheduled in a cluster. - -Also, pods might only have scheduling support on particular sets of nodes based -on its selection and affinity criteria. As a result, the estimation of which -remaining pods a cluster can schedule can be difficult. -==== - -You can run the cluster capacity analysis tool as a stand-alone utility from -the command line, or as a job in a pod inside an {product-title} cluster. -Running it as job inside of a pod enables you to run it multiple times without intervention. diff --git a/modules/nodes-cluster-resource-levels-command.adoc b/modules/nodes-cluster-resource-levels-command.adoc deleted file mode 100644 index cf8654ac813b..000000000000 --- a/modules/nodes-cluster-resource-levels-command.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-resource-levels.adoc - -[id="nodes-cluster-resource-levels-command_{context}"] -= Running the cluster capacity tool on the command line - -You can run the {product-title} cluster capacity tool from the command line -to estimate the number of pods that can be scheduled onto your cluster. - -.Prerequisites - -* Download and install link:https://github.com/kubernetes-incubator/cluster-capacity[the *cluster-capacity* tool]. - -* Create a sample `Pod` spec file, which the tool uses for estimating resource usage. The `podspec` specifies its resource -requirements as `limits` or `requests`. The cluster capacity tool takes the -pod's resource requirements into account for its estimation analysis. -+ -An example of the `Pod` spec input is: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: small-pod - labels: - app: guestbook - tier: frontend -spec: - containers: - - name: php-redis - image: gcr.io/google-samples/gb-frontend:v4 - imagePullPolicy: Always - resources: - limits: - cpu: 150m - memory: 100Mi - requests: - cpu: 150m - memory: 100Mi ----- - - -.Procedure - -To use the tool on the command line: - -. Run the following command: -+ -[source,terminal] ----- -$ ./cluster-capacity --kubeconfig <path-to-kubeconfig> \ <1> - --podspec <path-to-pod-spec> <2> ----- -<1> Specify the path to your Kubernetes configuration file. -<2> Specify the path to the sample `Pod` spec file -+ -You can also add the `--verbose` option to output a detailed description of how -many pods can be scheduled on each node in the cluster: -+ -[source,terminal] ----- -$ ./cluster-capacity --kubeconfig <path-to-kubeconfig> \ - --podspec <path-to-pod-spec> --verbose ----- -+ -.Example output -[source,terminal] ----- -small-pod pod requirements: - - CPU: 150m - - Memory: 100Mi - -The cluster can schedule 52 instance(s) of the pod small-pod. - -Termination reason: Unschedulable: No nodes are available that match all of the -following predicates:: Insufficient cpu (2). - -Pod distribution among nodes: -small-pod - - 192.168.124.214: 26 instance(s) - - 192.168.124.120: 26 instance(s) ----- -+ -In the above example, the number of estimated pods that can be scheduled onto -the cluster is 52. diff --git a/modules/nodes-cluster-resource-levels-job.adoc b/modules/nodes-cluster-resource-levels-job.adoc deleted file mode 100644 index 9eb71fca676a..000000000000 --- a/modules/nodes-cluster-resource-levels-job.adoc +++ /dev/null @@ -1,176 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-cluster-resource-levels.adoc - -[id="nodes-cluster-resource-levels-job_{context}"] -= Running the cluster capacity tool as a job inside a pod - -Running the cluster capacity tool as a job inside of a pod has the advantage of -being able to be run multiple times without needing user intervention. Running -the cluster capacity tool as a job involves using a `ConfigMap` object. - -.Prerequisites - -Download and install link:https://github.com/kubernetes-incubator/cluster-capacity[the cluster capacity tool]. - -.Procedure - -To run the cluster capacity tool: - -. Create the cluster role: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - ----- -+ -.Example output -[source,terminal] ----- -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: cluster-capacity-role -rules: -- apiGroups: [""] - resources: ["pods", "nodes", "persistentvolumeclaims", "persistentvolumes", "services", "replicationcontrollers"] - verbs: ["get", "watch", "list"] -- apiGroups: ["apps"] - resources: ["replicasets", "statefulsets"] - verbs: ["get", "watch", "list"] -- apiGroups: ["policy"] - resources: ["poddisruptionbudgets"] - verbs: ["get", "watch", "list"] -- apiGroups: ["storage.k8s.io"] - resources: ["storageclasses"] - verbs: ["get", "watch", "list"] -EOF ----- - -. Create the service account: -+ -[source,terminal] ----- -$ oc create sa cluster-capacity-sa ----- - -. Add the role to the service account: -+ -[source,terminal] ----- -$ oc adm policy add-cluster-role-to-user cluster-capacity-role \ - system:serviceaccount:default:cluster-capacity-sa ----- - -. Define and create the `Pod` spec: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: small-pod - labels: - app: guestbook - tier: frontend -spec: - containers: - - name: php-redis - image: gcr.io/google-samples/gb-frontend:v4 - imagePullPolicy: Always - resources: - limits: - cpu: 150m - memory: 100Mi - requests: - cpu: 150m - memory: 100Mi ----- - -. The cluster capacity analysis is mounted in a volume using a -`ConfigMap` object named `cluster-capacity-configmap` to mount input pod spec file -`pod.yaml` into a volume `test-volume` at the path `/test-pod`. -+ -If you haven't created a `ConfigMap` object, create one before creating the job: -+ ----- -$ oc create configmap cluster-capacity-configmap \ - --from-file=pod.yaml=pod.yaml ----- - -. Create the job using the below example of a job specification file: -+ -[source,yaml] ----- -apiVersion: batch/v1 -kind: Job -metadata: - name: cluster-capacity-job -spec: - parallelism: 1 - completions: 1 - template: - metadata: - name: cluster-capacity-pod - spec: - containers: - - name: cluster-capacity - image: openshift/origin-cluster-capacity - imagePullPolicy: "Always" - volumeMounts: - - mountPath: /test-pod - name: test-volume - env: - - name: CC_INCLUSTER <1> - value: "true" - command: - - "/bin/sh" - - "-ec" - - | - /bin/cluster-capacity --podspec=/test-pod/pod.yaml --verbose - restartPolicy: "Never" - serviceAccountName: cluster-capacity-sa - volumes: - - name: test-volume - configMap: - name: cluster-capacity-configmap ----- -<1> A required environment variable letting the cluster capacity tool - know that it is running inside a cluster as a pod. - + -The `pod.yaml` key of the `ConfigMap` object is the same as the `Pod` spec file -name, though it is not required. By doing this, the input pod spec file can be -accessed inside the pod as `/test-pod/pod.yaml`. - -. Run the cluster capacity image as a job in a pod: -+ -[source,terminal] ----- -$ oc create -f cluster-capacity-job.yaml ----- - -. Check the job logs to find the number of pods that can be scheduled in the - cluster: -+ -[source,terminal] ----- -$ oc logs jobs/cluster-capacity-job ----- -+ -.Example output -[source,terminal] ----- -small-pod pod requirements: - - CPU: 150m - - Memory: 100Mi - -The cluster can schedule 52 instance(s) of the pod small-pod. - -Termination reason: Unschedulable: No nodes are available that match all of the -following predicates:: Insufficient cpu (2). - -Pod distribution among nodes: -small-pod - - 192.168.124.214: 26 instance(s) - - 192.168.124.120: 26 instance(s) ----- diff --git a/modules/nodes-cluster-resource-override-deploy-cli.adoc b/modules/nodes-cluster-resource-override-deploy-cli.adoc deleted file mode 100644 index d21d903293f4..000000000000 --- a/modules/nodes-cluster-resource-override-deploy-cli.adoc +++ /dev/null @@ -1,214 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/clusters/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-resource-override-deploy-cli_{context}"] -= Installing the Cluster Resource Override Operator using the CLI - -You can use the {product-title} CLI to install the Cluster Resource Override Operator to help control overcommit in your cluster. - -.Prerequisites - -* The Cluster Resource Override Operator has no effect if limits have not been set on containers. You must specify default limits for a project using a `LimitRange` object or configure limits in `Pod` specs for the overrides to apply. - -.Procedure - -To install the Cluster Resource Override Operator using the CLI: - -. Create a namespace for the Cluster Resource Override Operator: - -.. Create a `Namespace` object YAML file (for example, `cro-namespace.yaml`) for the Cluster Resource Override Operator: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: clusterresourceoverride-operator ----- - -.. Create the namespace: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f cro-namespace.yaml ----- - -. Create an Operator group: - -.. Create an `OperatorGroup` object YAML file (for example, cro-og.yaml) for the Cluster Resource Override Operator: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: clusterresourceoverride-operator - namespace: clusterresourceoverride-operator -spec: - targetNamespaces: - - clusterresourceoverride-operator ----- - -.. Create the Operator Group: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f cro-og.yaml ----- - -. Create a subscription: - -.. Create a `Subscription` object YAML file (for example, cro-sub.yaml) for the Cluster Resource Override Operator: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: clusterresourceoverride - namespace: clusterresourceoverride-operator -spec: - channel: "4.7" - name: clusterresourceoverride - source: redhat-operators - sourceNamespace: openshift-marketplace ----- - -.. Create the subscription: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f cro-sub.yaml ----- - -. Create a `ClusterResourceOverride` custom resource (CR) object in the `clusterresourceoverride-operator` namespace: - -.. Change to the `clusterresourceoverride-operator` namespace. -+ -[source,terminal] ----- -$ oc project clusterresourceoverride-operator ----- - -.. Create a `ClusterResourceOverride` object YAML file (for example, cro-cr.yaml) for the Cluster Resource Override Operator: -+ -[source,yaml] ----- -apiVersion: operator.autoscaling.openshift.io/v1 -kind: ClusterResourceOverride -metadata: - name: cluster <1> -spec: - podResourceOverride: - spec: - memoryRequestToLimitPercent: 50 <2> - cpuRequestToLimitPercent: 25 <3> - limitCPUToMemoryPercent: 200 <4> ----- -<1> The name must be `cluster`. -<2> Optional. Specify the percentage to override the container memory limit, if used, between 1-100. The default is 50. -<3> Optional. Specify the percentage to override the container CPU limit, if used, between 1-100. The default is 25. -<4> Optional. Specify the percentage to override the container memory limit, if used. Scaling 1Gi of RAM at 100 percent is equal to 1 CPU core. This is processed prior to overriding the CPU request, if configured. The default is 200. - -.. Create the `ClusterResourceOverride` object: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f cro-cr.yaml ----- - -. Verify the current state of the admission webhook by checking the status of the cluster custom resource. -+ -[source,terminal] ----- -$ oc get clusterresourceoverride cluster -n clusterresourceoverride-operator -o yaml ----- -+ -The `mutatingWebhookConfigurationRef` section appears when the webhook is called. -+ -.Example output -[source,yaml] ----- -apiVersion: operator.autoscaling.openshift.io/v1 -kind: ClusterResourceOverride -metadata: - annotations: - kubectl.kubernetes.io/last-applied-configuration: | - {"apiVersion":"operator.autoscaling.openshift.io/v1","kind":"ClusterResourceOverride","metadata":{"annotations":{},"name":"cluster"},"spec":{"podResourceOverride":{"spec":{"cpuRequestToLimitPercent":25,"limitCPUToMemoryPercent":200,"memoryRequestToLimitPercent":50}}}} - creationTimestamp: "2019-12-18T22:35:02Z" - generation: 1 - name: cluster - resourceVersion: "127622" - selfLink: /apis/operator.autoscaling.openshift.io/v1/clusterresourceoverrides/cluster - uid: 978fc959-1717-4bd1-97d0-ae00ee111e8d -spec: - podResourceOverride: - spec: - cpuRequestToLimitPercent: 25 - limitCPUToMemoryPercent: 200 - memoryRequestToLimitPercent: 50 -status: - -.... - - mutatingWebhookConfigurationRef: <1> - apiVersion: admissionregistration.k8s.io/v1beta1 - kind: MutatingWebhookConfiguration - name: clusterresourceoverrides.admission.autoscaling.openshift.io - resourceVersion: "127621" - uid: 98b3b8ae-d5ce-462b-8ab5-a729ea8f38f3 - -.... - ----- -<1> Reference to the `ClusterResourceOverride` admission webhook. - -//// -. When the webhook is called, you can add a label to any Namespaces where you want overrides enabled: -+ ----- -$ oc edit namespace <name> ----- -+ ----- -apiVersion: v1 -kind: Namespace -metadata: - -.... - - labels: - clusterresourceoverrides.admission.autoscaling.openshift.io: enabled <1> ----- -<1> Add the `clusterresourceoverrides.admission.autoscaling.openshift.io: enabled` label to the Namespace. -//// diff --git a/modules/nodes-cluster-resource-override-deploy-console.adoc b/modules/nodes-cluster-resource-override-deploy-console.adoc deleted file mode 100644 index e5ebb4802023..000000000000 --- a/modules/nodes-cluster-resource-override-deploy-console.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/clusters/nodes-cluster-overcommit.adoc - -[id="nodes-cluster-resource-override-deploy-console_{context}"] -= Installing the Cluster Resource Override Operator using the web console - -You can use the {product-title} web console to install the Cluster Resource Override Operator to help control overcommit in your cluster. - -.Prerequisites - -* The Cluster Resource Override Operator has no effect if limits have not -been set on containers. You must specify default limits for a project using a `LimitRange` object or configure limits in `Pod` specs for the overrides to apply. - -.Procedure - -To install the Cluster Resource Override Operator using the {product-title} web console: - -. In the {product-title} web console, navigate to *Home* -> *Projects* - -.. Click *Create Project*. - -.. Specify `clusterresourceoverride-operator` as the name of the project. - -.. Click *Create*. - -. Navigate to *Operators* -> *OperatorHub*. - -.. Choose *ClusterResourceOverride Operator* from the list of available Operators and click *Install*. - -.. On the *Install Operator* page, make sure *A specific Namespace on the cluster* is selected for *Installation Mode*. - -.. Make sure *clusterresourceoverride-operator* is selected for *Installed Namespace*. - -.. Select an *Update Channel* and *Approval Strategy*. - -.. Click *Install*. - -. On the *Installed Operators* page, click *ClusterResourceOverride*. - -.. On the *ClusterResourceOverride Operator* details page, click *Create Instance*. - -.. On the *Create ClusterResourceOverride* page, edit the YAML template to set the overcommit values as needed: -+ ----- -apiVersion: operator.autoscaling.openshift.io/v1 -kind: ClusterResourceOverride -metadata: - name: cluster <1> -spec: - podResourceOverride: - spec: - memoryRequestToLimitPercent: 50 <2> - cpuRequestToLimitPercent: 25 <3> - limitCPUToMemoryPercent: 200 <4> ----- -<1> The name must be `cluster`. -<2> Optional. Specify the percentage to override the container memory limit, if used, between 1-100. The default is 50. -<3> Optional. Specify the percentage to override the container CPU limit, if used, between 1-100. The default is 25. -<4> Optional. Specify the percentage to override the container memory limit, if used. Scaling 1Gi of RAM at 100 percent is equal to 1 CPU core. This is processed prior to overriding the CPU request, if configured. The default is 200. - -.. Click *Create*. - -. Check the current state of the admission webhook by checking the status of the cluster custom resource: - -.. On the *ClusterResourceOverride Operator* page, click *cluster*. - -.. On the *ClusterResourceOverride Details* age, click *YAML*. The `mutatingWebhookConfigurationRef` section appears when the webhook is called. -+ ----- -apiVersion: operator.autoscaling.openshift.io/v1 -kind: ClusterResourceOverride -metadata: - annotations: - kubectl.kubernetes.io/last-applied-configuration: | - {"apiVersion":"operator.autoscaling.openshift.io/v1","kind":"ClusterResourceOverride","metadata":{"annotations":{},"name":"cluster"},"spec":{"podResourceOverride":{"spec":{"cpuRequestToLimitPercent":25,"limitCPUToMemoryPercent":200,"memoryRequestToLimitPercent":50}}}} - creationTimestamp: "2019-12-18T22:35:02Z" - generation: 1 - name: cluster - resourceVersion: "127622" - selfLink: /apis/operator.autoscaling.openshift.io/v1/clusterresourceoverrides/cluster - uid: 978fc959-1717-4bd1-97d0-ae00ee111e8d -spec: - podResourceOverride: - spec: - cpuRequestToLimitPercent: 25 - limitCPUToMemoryPercent: 200 - memoryRequestToLimitPercent: 50 -status: - -.... - - mutatingWebhookConfigurationRef: <1> - apiVersion: admissionregistration.k8s.io/v1beta1 - kind: MutatingWebhookConfiguration - name: clusterresourceoverrides.admission.autoscaling.openshift.io - resourceVersion: "127621" - uid: 98b3b8ae-d5ce-462b-8ab5-a729ea8f38f3 - -.... - ----- -<1> Reference to the `ClusterResourceOverride` admission webhook. - -//// -. When the webhook is called, you can add a label to any Namespaces where you want overrides enabled: - -.. Click `Administration` -> `Namespaces`. - -.. Click the Namespace to edit then click *YAML*. - -.. Add the label under `metadata`: -+ ----- -apiVersion: v1 -kind: Namespace -metadata: - -.... - - labels: - clusterresourceoverrides.admission.autoscaling.openshift.io: enabled <1> ----- -<1> Add the `clusterresourceoverrides.admission.autoscaling.openshift.io: enabled` label to the Namespace. -//// diff --git a/modules/nodes-cluster-resource-override-deploy.adoc b/modules/nodes-cluster-resource-override-deploy.adoc deleted file mode 100644 index 868a7c0a8f4d..000000000000 --- a/modules/nodes-cluster-resource-override-deploy.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/clusters/nodes-cluster-overcommit.adoc - -[id="nodes-cluster-resource-override-deploy_{context}"] -= Installing the Cluster Resource Override Operator - -You can use the {product-title} console or CLI to install the Cluster Logging Operator. diff --git a/modules/nodes-cluster-resource-override.adoc b/modules/nodes-cluster-resource-override.adoc deleted file mode 100644 index 01ea8c417119..000000000000 --- a/modules/nodes-cluster-resource-override.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/clusters/nodes-cluster-overcommit.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-cluster-resource-override_{context}"] -= Cluster-level overcommit using the Cluster Resource Override Operator - -The Cluster Resource Override Operator is an admission webhook that allows you to control the level of overcommit and manage -container density across all the nodes in your cluster. The Operator controls how nodes in specific projects can exceed defined memory and CPU limits. - -You must install the Cluster Resource Override Operator using the {product-title} console or CLI as shown in the following sections. -During the installation, you create a `ClusterResourceOverride` custom resource (CR), where you set the level of overcommit, as shown in the -following example: - -[source,yaml] ----- -apiVersion: operator.autoscaling.openshift.io/v1 -kind: ClusterResourceOverride -metadata: -- name: cluster <1> -spec: - memoryRequestToLimitPercent: 50 <2> - cpuRequestToLimitPercent: 25 <3> - limitCPUToMemoryPercent: 200 <4> ----- -<1> The name must be `cluster`. -<2> Optional. If a container memory limit has been specified or defaulted, the memory request is overridden to this percentage of the limit, between 1-100. The default is 50. -<3> Optional. If a container CPU limit has been specified or defaulted, the CPU request is overridden to this percentage of the limit, between 1-100. The default is 25. -<4> Optional. If a container memory limit has been specified or defaulted, the CPU limit is overridden to a percentage of the memory limit, if specified. Scaling 1Gi of RAM at 100 percent is equal to 1 CPU core. This is processed prior to overriding the CPU request (if configured). The default is 200. - -[NOTE] -==== -The Cluster Resource Override Operator overrides have no effect if limits have not -been set on containers. Create a `LimitRange` object with default limits per individual project -or configure limits in `Pod` specs for the overrides to apply. -==== - -When configured, overrides can be enabled per-project by applying the following -label to the Namespace object for each project: - -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - -.... - - labels: - clusterresourceoverrides.admission.autoscaling.openshift.io/enabled: "true" - -.... - ----- - -The Operator watches for the `ClusterResourceOverride` CR and ensures that the `ClusterResourceOverride` admission webhook is installed into the same namespace as the operator. diff --git a/modules/nodes-containers-copying-files-about.adoc b/modules/nodes-containers-copying-files-about.adoc deleted file mode 100644 index 33c0973063d6..000000000000 --- a/modules/nodes-containers-copying-files-about.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-copying-files.adoc - -[id="nodes-containers-copying-files-about_{context}"] -= Understanding how to copy files - -The `oc rsync` command, or remote sync, is a useful tool for copying database archives to and from your pods for backup and restore purposes. -You can also use `oc rsync` to copy source code changes into a running pod for development debugging, when the running pod supports hot reload of source files. - -[source,terminal] ----- -$ oc rsync <source> <destination> [-c <container>] ----- - -== Requirements - -Specifying the Copy Source:: -The source argument of the `oc rsync` command must point to either a local -directory or a pod directory. Individual files are not supported. - -When specifying a pod directory the directory name must be prefixed with the pod -name: - -[source,terminal] ----- -<pod name>:<dir> ----- - -If the directory name ends in a path separator (`/`), only the contents of the directory are copied to the destination. Otherwise, the -directory and its contents are copied to the destination. - -Specifying the Copy Destination:: -The destination argument of the `oc rsync` command must point to a directory. If -the directory does not exist, but `rsync` is used for copy, the directory is -created for you. - -Deleting Files at the Destination:: -The `--delete` flag may be used to delete any files in the remote directory that -are not in the local directory. - -Continuous Syncing on File Change:: -Using the `--watch` option causes the command to monitor the source path for any -file system changes, and synchronizes changes when they occur. With this -argument, the command runs forever. - -Synchronization occurs after short quiet periods to ensure a -rapidly changing file system does not result in continuous synchronization -calls. - -When using the `--watch` option, the behavior is effectively the same as -manually invoking `oc rsync` repeatedly, including any arguments normally passed -to `oc rsync`. Therefore, you can control the behavior via the same flags used -with manual invocations of `oc rsync`, such as `--delete`. diff --git a/modules/nodes-containers-copying-files-procedure.adoc b/modules/nodes-containers-copying-files-procedure.adoc deleted file mode 100644 index 474ed6d00752..000000000000 --- a/modules/nodes-containers-copying-files-procedure.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-copying-files.adoc - -[id="nodes-containers-copying-files-procedure_{context}"] -= Copying files to and from containers - -Support for copying local files to or from a container is built into the CLI. - -.Prerequisites - -When working with `oc rsync`, note the following: - -rsync must be installed:: -The `oc rsync` command uses the local `rsync` tool if present on the client -machine and the remote container. - -If `rsync` is not found locally or in the remote container, a *tar* archive -is created locally and sent to the container where the *tar* utility is used to -extract the files. If *tar* is not available in the remote container, the -copy will fail. - -The *tar* copy method does not provide the same functionality as `oc rsync`. For -example, `oc rsync` creates the destination directory if it does not exist and -only sends files that are different between the source and the destination. - -[NOTE] -==== -In Windows, the `cwRsync` client should be installed and added to the PATH for -use with the `oc rsync` command. -==== - -.Procedure - -* To copy a local directory to a pod directory: -+ -[source,terminal] ----- -$ oc rsync <local-dir> <pod-name>:/<remote-dir> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc rsync /home/user/source devpod1234:/src ----- -+ -.Example output -[source,terminal] ----- -WARNING: cannot use rsync: rsync not available in container -status.txt ----- - -* To copy a pod directory to a local directory: -+ -[source,terminal] ----- -$ oc rsync devpod1234:/src /home/user/source ----- -+ -.Example output -[source,terminal] ----- -$ oc rsync devpod1234:/src/status.txt /home/user/ -WARNING: cannot use rsync: rsync not available in container -status.txt ----- diff --git a/modules/nodes-containers-copying-files-rsync.adoc b/modules/nodes-containers-copying-files-rsync.adoc deleted file mode 100644 index fe98c17f0d06..000000000000 --- a/modules/nodes-containers-copying-files-rsync.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-copying-files.adoc - -[id="nodes-containers-copying-files-rsync_{context}"] -= Using advanced Rsync features - -The `oc rsync` command exposes fewer command line options than standard `rsync`. -In the case that you want to use a standard `rsync` command line option that is -not available in `oc rsync`, for example the `--exclude-from=FILE` option, it -might be possible to use standard `rsync` 's `--rsh` (`-e`) option or `RSYNC_RSH` -environment variable as a workaround, as follows: - -[source,terminal] ----- -$ rsync --rsh='oc rsh' --exclude-from=FILE SRC POD:DEST ----- - -or: - -Export the `RSYNC_RSH` variable: - -[source,terminal] ----- -$ export RSYNC_RSH='oc rsh' ----- - -Then, run the rsync command: - -[source,terminal] ----- -$ rsync --exclude-from=FILE SRC POD:DEST ----- - -Both of the above examples configure standard `rsync` to use `oc rsh` as its -remote shell program to enable it to connect to the remote pod, and are an -alternative to running `oc rsync`. diff --git a/modules/nodes-containers-downward-api-about.adoc b/modules/nodes-containers-downward-api-about.adoc deleted file mode 100644 index 305e26c2a1c6..000000000000 --- a/modules/nodes-containers-downward-api-about.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-projected-volumes-about_{context}"] -= Expose Pod information to Containers using the Downward API - -The Downward API contains such information as the pod's name, project, and resource values. Containers can consume -information from the downward API using environment variables or a volume -plug-in. - -Fields within the pod are selected using the `FieldRef` API type. `FieldRef` -has two fields: - -[options="header"] -|=== -|Field |Description - -|`fieldPath` -|The path of the field to select, relative to the pod. - -|`apiVersion` -|The API version to interpret the `fieldPath` selector within. -|=== - -Currently, the valid selectors in the v1 API include: - -[options="header"] -|=== -|Selector |Description - -|`metadata.name` -|The pod's name. This is supported in both environment variables and volumes. - -|`metadata.namespace` -|The pod's namespace.This is supported in both environment variables and volumes. - -|`metadata.labels` -|The pod's labels. This is only supported in volumes and not in environment variables. - -|`metadata.annotations` -|The pod's annotations. This is only supported in volumes and not in environment variables. - -|`status.podIP` -|The pod's IP. This is only supported in environment variables and not volumes. -|=== - -The `apiVersion` field, if not specified, defaults to the API version of the -enclosing pod template. diff --git a/modules/nodes-containers-downward-api-container-configmaps.adoc b/modules/nodes-containers-downward-api-container-configmaps.adoc deleted file mode 100644 index e552432207d0..000000000000 --- a/modules/nodes-containers-downward-api-container-configmaps.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-configmaps_{context}"] -= Consuming configuration maps using the Downward API - -When creating pods, you can use the Downward API to inject configuration map values -so image and application authors can create an image for specific environments. - -.Procedure - -. Create a `*_configmap.yaml_*` file: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: myconfigmap -data: - mykey: myvalue ----- - -. Create a `ConfigMap` object from the `*_configmap.yaml_*` file: -+ -[source,terminal] ----- -$ oc create -f configmap.yaml ----- - -. Create a `*_pod.yaml_*` file that references the above `ConfigMap` object: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-env-test-pod -spec: - containers: - - name: env-test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "-c", "env" ] - env: - - name: MY_CONFIGMAP_VALUE - valueFrom: - configMapKeyRef: - name: myconfigmap - key: mykey - restartPolicy: Always ----- - -. Create the pod from the `*_pod.yaml_*` file: -+ -[source,terminal] ----- -$ oc create -f pod.yaml ----- - -. Check the container's logs for the `MY_CONFIGMAP_VALUE` value: -+ -[source,terminal] ----- -$ oc logs -p dapi-env-test-pod ----- diff --git a/modules/nodes-containers-downward-api-container-envars.adoc b/modules/nodes-containers-downward-api-container-envars.adoc deleted file mode 100644 index 27b10a3ef00a..000000000000 --- a/modules/nodes-containers-downward-api-container-envars.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-envars_{context}"] -= Referencing environment variables - -When creating pods, you can reference the value of a previously defined -environment variable by using the `$()` syntax. If the environment variable -reference can not be resolved, the value will be left as the provided -string. - -.Procedure - -. Create a `*_pod.yaml_*` file that references an existing `environment variable`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-env-test-pod -spec: - containers: - - name: env-test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "-c", "env" ] - env: - - name: MY_EXISTING_ENV - value: my_value - - name: MY_ENV_VAR_REF_ENV - value: $(MY_EXISTING_ENV) - restartPolicy: Never ----- - -. Create the pod from the `*_pod.yaml_*` file: -+ -[source,terminal] ----- -$ oc create -f pod.yaml ----- - -. Check the container's logs for the `MY_ENV_VAR_REF_ENV` value: -+ -[source,terminal] ----- -$ oc logs -p dapi-env-test-pod ----- diff --git a/modules/nodes-containers-downward-api-container-escaping.adoc b/modules/nodes-containers-downward-api-container-escaping.adoc deleted file mode 100644 index 24619c1c65e0..000000000000 --- a/modules/nodes-containers-downward-api-container-escaping.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-escaping_{context}"] -= Escaping environment variable references - -When creating a pod, you can escape an environment variable reference by using -a double dollar sign. The value will then be set to a single dollar sign version -of the provided value. - -.Procedure - -. Create a `*_pod.yaml_*` file that references an existing `environment variable`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-env-test-pod -spec: - containers: - - name: env-test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "-c", "env" ] - env: - - name: MY_NEW_ENV - value: $$(SOME_OTHER_ENV) - restartPolicy: Never ----- - -. Create the pod from the `*_pod.yaml_*` file: -+ -[source,terminal] ----- -$ oc create -f pod.yaml ----- - -. Check the container's logs for the `MY_NEW_ENV` value: -+ -[source,terminal] ----- -$ oc logs -p dapi-env-test-pod ----- diff --git a/modules/nodes-containers-downward-api-container-resources-envars.adoc b/modules/nodes-containers-downward-api-container-resources-envars.adoc deleted file mode 100644 index 1be2f6be04ae..000000000000 --- a/modules/nodes-containers-downward-api-container-resources-envars.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-resources-envars_{context}"] -= Consuming container resources using environment variables - -When creating pods, you can use the Downward API to inject information about -computing resource requests and limits using environment variables. - -.Procedure - -To use environment variables: - -. When creating a pod configuration, specify environment variables that -correspond to the contents of the `resources` field in the `*spec.container*` -field: -+ -[source,yaml] ----- -.... -spec: - containers: - - name: test-container - image: gcr.io/google_containers/busybox:1.24 - command: [ "/bin/sh", "-c", "env" ] - resources: - requests: - memory: "32Mi" - cpu: "125m" - limits: - memory: "64Mi" - cpu: "250m" - env: - - name: MY_CPU_REQUEST - valueFrom: - resourceFieldRef: - resource: requests.cpu - - name: MY_CPU_LIMIT - valueFrom: - resourceFieldRef: - resource: limits.cpu - - name: MY_MEM_REQUEST - valueFrom: - resourceFieldRef: - resource: requests.memory - - name: MY_MEM_LIMIT - valueFrom: - resourceFieldRef: - resource: limits.memory -.... ----- -+ -If the resource limits are not included in the container configuration, the -downward API defaults to the node's CPU and memory allocatable values. - -. Create the pod from the `*_pod.yaml_*` file: -+ -[source,terminal] ----- -$ oc create -f pod.yaml ----- diff --git a/modules/nodes-containers-downward-api-container-resources-plugin.adoc b/modules/nodes-containers-downward-api-container-resources-plugin.adoc deleted file mode 100644 index 4f935aa2e23c..000000000000 --- a/modules/nodes-containers-downward-api-container-resources-plugin.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-resources-plugin_{context}"] -= Consuming container resources using a volume plug-in - -When creating pods, you can use the Downward API to inject information about -computing resource requests and limits using a volume plug-in. - -.Procedure - -To use the Volume Plug-in: - -. When creating a pod configuration, use the `spec.volumes.downwardAPI.items` -field to describe the desired resources that correspond to the -`spec.resources` field: -+ -[source,yaml] ----- -.... -spec: - containers: - - name: client-container - image: gcr.io/google_containers/busybox:1.24 - command: ["sh", "-c", "while true; do echo; if [[ -e /etc/cpu_limit ]]; then cat /etc/cpu_limit; fi; if [[ -e /etc/cpu_request ]]; then cat /etc/cpu_request; fi; if [[ -e /etc/mem_limit ]]; then cat /etc/mem_limit; fi; if [[ -e /etc/mem_request ]]; then cat /etc/mem_request; fi; sleep 5; done"] - resources: - requests: - memory: "32Mi" - cpu: "125m" - limits: - memory: "64Mi" - cpu: "250m" - volumeMounts: - - name: podinfo - mountPath: /etc - readOnly: false - volumes: - - name: podinfo - downwardAPI: - items: - - path: "cpu_limit" - resourceFieldRef: - containerName: client-container - resource: limits.cpu - - path: "cpu_request" - resourceFieldRef: - containerName: client-container - resource: requests.cpu - - path: "mem_limit" - resourceFieldRef: - containerName: client-container - resource: limits.memory - - path: "mem_request" - resourceFieldRef: - containerName: client-container - resource: requests.memory -.... ----- -+ -If the resource limits are not included in the container configuration, the -Downward API defaults to the node's CPU and memory allocatable values. - -. Create the pod from the `*_volume-pod.yaml_*` file: -+ -[source,terminal] ----- -$ oc create -f volume-pod.yaml ----- diff --git a/modules/nodes-containers-downward-api-container-resources.adoc b/modules/nodes-containers-downward-api-container-resources.adoc deleted file mode 100644 index 0a6ee856782a..000000000000 --- a/modules/nodes-containers-downward-api-container-resources.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-resources-api_{context}"] -= Understanding how to consume container resources using the Downward API - -When creating pods, you can use the Downward API to inject information about -computing resource requests and limits so that image and application authors can -correctly create an image for specific environments. - -You can do this using environment variable or a volume plug-in. - diff --git a/modules/nodes-containers-downward-api-container-secrets.adoc b/modules/nodes-containers-downward-api-container-secrets.adoc deleted file mode 100644 index 471387319e75..000000000000 --- a/modules/nodes-containers-downward-api-container-secrets.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-secrets_{context}"] -= Consuming secrets using the Downward API - -When creating pods, you can use the downward API to inject secrets -so image and application authors can create an image -for specific environments. - -.Procedure - -. Create a `secret.yaml` file: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: mysecret -data: - password: cGFzc3dvcmQ= - username: ZGV2ZWxvcGVy -type: kubernetes.io/basic-auth ----- - -. Create a `Secret` object from the `secret.yaml` file: -+ -[source,terminal] ----- -$ oc create -f secret.yaml ----- - -. Create a `pod.yaml` file that references the `username` field from the above `Secret` object: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-env-test-pod -spec: - containers: - - name: env-test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "-c", "env" ] - env: - - name: MY_SECRET_USERNAME - valueFrom: - secretKeyRef: - name: mysecret - key: username - restartPolicy: Never ----- - -. Create the pod from the `pod.yaml` file: -+ -[source,terminal] ----- -$ oc create -f pod.yaml ----- - -. Check the container's logs for the `MY_SECRET_USERNAME` value: -+ -[source,terminal] ----- -$ oc logs -p dapi-env-test-pod ----- diff --git a/modules/nodes-containers-downward-api-container-values-envars.adoc b/modules/nodes-containers-downward-api-container-values-envars.adoc deleted file mode 100644 index 8e30810cc4ca..000000000000 --- a/modules/nodes-containers-downward-api-container-values-envars.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-values-envars_{context}"] -= Consuming container values using environment variables - -When using a container's environment variables, use the `EnvVar` type's `valueFrom` field (of type `EnvVarSource`) -to specify that the variable's value should come from a `FieldRef` -source instead of the literal value specified by the `value` field. - -Only constant attributes of the pod can be consumed this way, as environment -variables cannot be updated once a process is started in a way that allows the -process to be notified that the value of a variable has changed. The fields -supported using environment variables are: - -- Pod name -- Pod project/namespace - -.Procedure - -To use environment variables - -. Create a `pod.yaml` file: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dapi-env-test-pod -spec: - containers: - - name: env-test-container - image: gcr.io/google_containers/busybox - command: [ "/bin/sh", "-c", "env" ] - env: - - name: MY_POD_NAME - valueFrom: - fieldRef: - fieldPath: metadata.name - - name: MY_POD_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - restartPolicy: Never ----- - -. Create the pod from the `pod.yaml` file: -+ -[source,terminal] ----- -$ oc create -f pod.yaml ----- - -. Check the container's logs for the `MY_POD_NAME` and `MY_POD_NAMESPACE` -values: -+ -[source,terminal] ----- -$ oc logs -p dapi-env-test-pod ----- diff --git a/modules/nodes-containers-downward-api-container-values-plugin.adoc b/modules/nodes-containers-downward-api-container-values-plugin.adoc deleted file mode 100644 index ec75eea8e810..000000000000 --- a/modules/nodes-containers-downward-api-container-values-plugin.adoc +++ /dev/null @@ -1,91 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-values-plugin_{context}"] -= Consuming container values using a volume plug-in - -You containers can consume API values using a volume plug-in. - -Containers can consume: - -* Pod name - -* Pod project/namespace - -* Pod annotations - -* Pod labels - -.Procedure - -To use the volume plug-in: - -. Create a `volume-pod.yaml` file: -+ -[source,yaml] ----- -kind: Pod -apiVersion: v1 -metadata: - labels: - zone: us-east-coast - cluster: downward-api-test-cluster1 - rack: rack-123 - name: dapi-volume-test-pod - annotations: - annotation1: "345" - annotation2: "456" -spec: - containers: - - name: volume-test-container - image: gcr.io/google_containers/busybox - command: ["sh", "-c", "cat /tmp/etc/pod_labels /tmp/etc/pod_annotations"] - volumeMounts: - - name: podinfo - mountPath: /tmp/etc - readOnly: false - volumes: - - name: podinfo - downwardAPI: - defaultMode: 420 - items: - - fieldRef: - fieldPath: metadata.name - path: pod_name - - fieldRef: - fieldPath: metadata.namespace - path: pod_namespace - - fieldRef: - fieldPath: metadata.labels - path: pod_labels - - fieldRef: - fieldPath: metadata.annotations - path: pod_annotations - restartPolicy: Never ----- - -. Create the pod from the `volume-pod.yaml` file: -+ -[source,terminal] ----- -$ oc create -f volume-pod.yaml ----- - -. Check the container's logs and verify the presence of the configured fields: -+ -[source,terminal] ----- -$ oc logs -p dapi-volume-test-pod ----- -+ -.Example output -[source,terminal] ----- -cluster=downward-api-test-cluster1 -rack=rack-123 -zone=us-east-coast -annotation1=345 -annotation2=456 -kubernetes.io/config.source=api ----- diff --git a/modules/nodes-containers-downward-api-container-values.adoc b/modules/nodes-containers-downward-api-container-values.adoc deleted file mode 100644 index 670b59c154f2..000000000000 --- a/modules/nodes-containers-downward-api-container-values.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-downward-api.adoc - -[id="nodes-containers-downward-api-container-values_{context}"] -= Understanding how to consume container values using the downward API - -You containers can consume API values using environment variables or a volume plug-in. -Depending on the method you choose, containers can consume: - -* Pod name - -* Pod project/namespace - -* Pod annotations - -* Pod labels - -Annotations and labels are available using only a volume plug-in. - diff --git a/modules/nodes-containers-events-about.adoc b/modules/nodes-containers-events-about.adoc deleted file mode 100644 index 2583e4f50098..000000000000 --- a/modules/nodes-containers-events-about.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-events.adoc - -[id="nodes-containers-events-about_{context}"] -= Understanding events - -Events allow {product-title} to record -information about real-world events in a resource-agnostic manner. They also -allow developers and administrators to consume information about system -components in a unified way. - -ifdef::openshift-online[] -[id="event-failure-notifications_{context}"] -== Failure Notifications - -For each of your projects, you can choose to receive email notifications -about various failures, including dead or failed deployments, dead builds, and -dead or failed persistent volume claims (PVCs). - -See Notifications. -endif::[] diff --git a/modules/nodes-containers-events-list.adoc b/modules/nodes-containers-events-list.adoc deleted file mode 100644 index df5168717f39..000000000000 --- a/modules/nodes-containers-events-list.adoc +++ /dev/null @@ -1,483 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-events.adoc - -[id="nodes-containers-events-list_{context}"] -= List of events - -This section describes the events of {product-title}. - -.Configuration events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`FailedValidation` -|Failed pod configuration validation. -|=== - -.Container events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`BackOff` -|Back-off restarting failed the container. - -|`Created` -|Container created. - -|`Failed` -|Pull/Create/Start failed. - -|`Killing` -|Killing the container. - -|`Started` -|Container started. - -|`Preempting` -|Preempting other pods. - -|`ExceededGracePeriod` -|Container runtime did not stop the pod within specified grace period. - -|=== - -.Health events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`Unhealthy` -|Container is unhealthy. -|=== - -.Image events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`BackOff` -|Back off Ctr Start, image pull. - -|`ErrImageNeverPull` -|The image's *NeverPull Policy* is violated. - -|`Failed` -|Failed to pull the image. - -|`InspectFailed` -|Failed to inspect the image. - -|`Pulled` -|Successfully pulled the image or the container image is already present on the machine. - -|`Pulling` -|Pulling the image. -|=== - -.Image Manager events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`FreeDiskSpaceFailed` -|Free disk space failed. - -|`InvalidDiskCapacity` -|Invalid disk capacity. -|=== - -.Node events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`FailedMount` -|Volume mount failed. - -|`HostNetworkNotSupported` -|Host network not supported. - -|`HostPortConflict` -|Host/port conflict. - -|`InsufficientFreeCPU` -|Insufficient free CPU. - -|`InsufficientFreeMemory` -|Insufficient free memory. - -|`KubeletSetupFailed` -|Kubelet setup failed. - -|`NilShaper` -|Undefined shaper. - -|`NodeNotReady` -|Node is not ready. - -|`NodeNotSchedulable` -|Node is not schedulable. - -|`NodeReady` -|Node is ready. - -|`NodeSchedulable` -|Node is schedulable. - -|`NodeSelectorMismatching` -|Node selector mismatch. - -|`OutOfDisk` -|Out of disk. - -|`Rebooted` -|Node rebooted. - -|`Starting` -|Starting kubelet. - -|`FailedAttachVolume` -|Failed to attach volume. - -|`FailedDetachVolume` -|Failed to detach volume. - -|`VolumeResizeFailed` -|Failed to expand/reduce volume. - -|`VolumeResizeSuccessful` -| Successfully expanded/reduced volume. - -|`FileSystemResizeFailed` -|Failed to expand/reduce file system. - -|`FileSystemResizeSuccessful` -| Successfully expanded/reduced file system. - -|`FailedUnMount` -|Failed to unmount volume. - -|`FailedMapVolume` -|Failed to map a volume. - -|`FailedUnmapDevice` -|Failed unmaped device. - -|`AlreadyMountedVolume` -|Volume is already mounted. - -|`SuccessfulDetachVolume` -|Volume is successfully detached. - -|`SuccessfulMountVolume` -|Volume is successfully mounted. - -|`SuccessfulUnMountVolume` -|Volume is successfully unmounted. - -|`ContainerGCFailed` -|Container garbage collection failed. - -|`ImageGCFailed` -|Image garbage collection failed. - -|`FailedNodeAllocatableEnforcement` -|Failed to enforce System Reserved Cgroup limit. - -|`NodeAllocatableEnforced` -|Enforced System Reserved Cgroup limit. - -|`UnsupportedMountOption` -|Unsupported mount option. - -|`SandboxChanged` -|Pod sandbox changed. - -|`FailedCreatePodSandBox` -|Failed to create pod sandbox. - -|`FailedPodSandBoxStatus` -|Failed pod sandbox status. - -|=== - -.Pod worker events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`FailedSync` -|Pod sync failed. -|=== - -.System Events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`SystemOOM` -|There is an OOM (out of memory) situation on the cluster. -|=== - -.Pod events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`FailedKillPod` -|Failed to stop a pod. - -|`FailedCreatePodContainer` -|Failed to create a pod container. - -|`Failed` -|Failed to make pod data directories. - -|`NetworkNotReady` -|Network is not ready. - -|`FailedCreate` -|Error creating: `<error-msg>`. - -|`SuccessfulCreate` -|Created pod: `<pod-name>`. - -|`FailedDelete` -|Error deleting: `<error-msg>`. - -|`SuccessfulDelete` -|Deleted pod: `<pod-id>`. - -|=== - -.Horizontal Pod AutoScaler events -[cols="2,8",options="header"] -|=== -| Name | Description - -|SelectorRequired -|Selector is required. - -|`InvalidSelector` -|Could not convert selector into a corresponding internal selector object. - -|`FailedGetObjectMetric` -|HPA was unable to compute the replica count. - -|`InvalidMetricSourceType` -|Unknown metric source type. - -|`ValidMetricFound` -|HPA was able to successfully calculate a replica count. - -|`FailedConvertHPA` -|Failed to convert the given HPA. - -|`FailedGetScale` -|HPA controller was unable to get the target's current scale. - -|`SucceededGetScale` -|HPA controller was able to get the target's current scale. - -|`FailedComputeMetricsReplicas` -|Failed to compute desired number of replicas based on listed metrics. - -|`FailedRescale` -|New size: `<size>`; reason: `<msg>`; error: `<error-msg>`. - -|`SuccessfulRescale` -|New size: `<size>`; reason: `<msg>`. - -|`FailedUpdateStatus` -|Failed to update status. - -|=== - -.Network events (openshift-sdn) -[cols="2,8",options="header"] -|=== -| Name | Description - -|`Starting` -|Starting OpenShift-SDN. - -|`NetworkFailed` -|The pod's network interface has been lost and the pod will be stopped. -|=== - -.Network events (kube-proxy) -[cols="2,8",options="header"] -|=== -| Name | Description - -|`NeedPods` -|The service-port `<serviceName>:<port>` needs pods. -|=== - -.Volume events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`FailedBinding` -|There are no persistent volumes available and no storage class is set. - -|`VolumeMismatch` -|Volume size or class is different from what is requested in claim. - -|`VolumeFailedRecycle` -|Error creating recycler pod. - -|`VolumeRecycled` -|Occurs when volume is recycled. - -|`RecyclerPod` -|Occurs when pod is recycled. - -|`VolumeDelete` -|Occurs when volume is deleted. - -|`VolumeFailedDelete` -|Error when deleting the volume. - -|`ExternalProvisioning` -|Occurs when volume for the claim is provisioned either manually or via external software. - -|`ProvisioningFailed` -|Failed to provision volume. - -|`ProvisioningCleanupFailed` -|Error cleaning provisioned volume. - -|`ProvisioningSucceeded` -|Occurs when the volume is provisioned successfully. - -|`WaitForFirstConsumer` -|Delay binding until pod scheduling. - -|=== - -.Lifecycle hooks -[cols="2,8",options="header"] -|=== -| Name | Description - -|`FailedPostStartHook` -|Handler failed for pod start. - -|`FailedPreStopHook` -|Handler failed for pre-stop. - -|`UnfinishedPreStopHook` -|Pre-stop hook unfinished. -|=== - -.Deployments -[cols="2,8",options="header"] -|=== -| Name | Description - -|`DeploymentCancellationFailed` -|Failed to cancel deployment. - -|`DeploymentCancelled` -|Canceled deployment. - -|`DeploymentCreated` -|Created new replication controller. - -|`IngressIPRangeFull` -|No available Ingress IP to allocate to service. - -|=== - -.Scheduler events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`FailedScheduling` -|Failed to schedule pod: `<pod-namespace>/<pod-name>`. This event is raised for -multiple reasons, for example: `AssumePodVolumes` failed, Binding rejected etc. - -|`Preempted` -|By `<preemptor-namespace>/<preemptor-name>` on node `<node-name>`. - -|`Scheduled` -|Successfully assigned `<pod-name>` to `<node-name>`. - -|=== - -.Daemon set events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`SelectingAll` -|This daemon set is selecting all pods. A non-empty selector is required. - -|`FailedPlacement` -|Failed to place pod on `<node-name>`. - -|`FailedDaemonPod` -|Found failed daemon pod `<pod-name>` on node `<node-name>`, will try to kill it. - -|=== - -.LoadBalancer service events -[cols="2,8",options="header"] -|=== -| Name | Description - -|`CreatingLoadBalancerFailed` -|Error creating load balancer. - -|`DeletingLoadBalancer` -|Deleting load balancer. - -|`EnsuringLoadBalancer` -|Ensuring load balancer. - -|`EnsuredLoadBalancer` -|Ensured load balancer. - -|`UnAvailableLoadBalancer` -|There are no available nodes for `LoadBalancer` service. - -|`LoadBalancerSourceRanges` -|Lists the new `LoadBalancerSourceRanges`. For example, `<old-source-range> -> <new-source-range>`. - -|`LoadbalancerIP` -|Lists the new IP address. For example, `<old-ip> -> <new-ip>`. - -|`ExternalIP` -|Lists external IP address. For example, `Added: <external-ip>`. - -|`UID` -|Lists the new UID. For example, `<old-service-uid> -> <new-service-uid>`. - -|`ExternalTrafficPolicy` -|Lists the new `ExternalTrafficPolicy`. For example, `<old-policy> -> <new-policy>`. - -|`HealthCheckNodePort` -|Lists the new `HealthCheckNodePort`. For example, `<old-node-port> -> new-node-port>`. - -|`UpdatedLoadBalancer` -|Updated load balancer with new hosts. - -|`LoadBalancerUpdateFailed` -|Error updating load balancer with new hosts. - -|`DeletingLoadBalancer` -|Deleting load balancer. - -|`DeletingLoadBalancerFailed` -|Error deleting load balancer. - -|`DeletedLoadBalancer` -|Deleted load balancer. - -|=== diff --git a/modules/nodes-containers-events-viewing.adoc b/modules/nodes-containers-events-viewing.adoc deleted file mode 100644 index b09aa31441a3..000000000000 --- a/modules/nodes-containers-events-viewing.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-events.adoc - -[id="nodes-containers-events-viewing-cli_{context}"] -= Viewing events using the CLI - -You can get a list of events in a given project using the CLI. - -.Procedure - -* To view events in a project use the following command: -+ -[source,terminal] ----- -$ oc get events [-n <project>] <1> ----- -<1> The name of the project. -+ -For example: -+ -[source,terminal] ----- -$ oc get events -n openshift-config ----- -+ -.Example output -[source,terminal] ----- -LAST SEEN TYPE REASON OBJECT MESSAGE -97m Normal Scheduled pod/dapi-env-test-pod Successfully assigned openshift-config/dapi-env-test-pod to ip-10-0-171-202.ec2.internal -97m Normal Pulling pod/dapi-env-test-pod pulling image "gcr.io/google_containers/busybox" -97m Normal Pulled pod/dapi-env-test-pod Successfully pulled image "gcr.io/google_containers/busybox" -97m Normal Created pod/dapi-env-test-pod Created container -9m5s Warning FailedCreatePodSandBox pod/dapi-volume-test-pod Failed create pod sandbox: rpc error: code = Unknown desc = failed to create pod network sandbox k8s_dapi-volume-test-pod_openshift-config_6bc60c1f-452e-11e9-9140-0eec59c23068_0(748c7a40db3d08c07fb4f9eba774bd5effe5f0d5090a242432a73eee66ba9e22): Multus: Err adding pod to network "openshift-sdn": cannot set "openshift-sdn" ifname to "eth0": no netns: failed to Statfs "/proc/33366/ns/net": no such file or directory -8m31s Normal Scheduled pod/dapi-volume-test-pod Successfully assigned openshift-config/dapi-volume-test-pod to ip-10-0-171-202.ec2.internal ----- - - -* To view events in your project from the {product-title} console. -+ -. Launch the {product-title} console. -+ -. Click *Home* -> *Events* and select your project. - -. Move to resource that you want to see events. For example: *Home* -> *Projects* -> <project-name> -> <resource-name>. -+ -Many objects, such as pods and deployments, have their own -*Events* tab as well, which shows events related to that object. diff --git a/modules/nodes-containers-init-about.adoc b/modules/nodes-containers-init-about.adoc deleted file mode 100644 index 35eeb362d003..000000000000 --- a/modules/nodes-containers-init-about.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-init.adoc - -[id="nodes-containers-init-about_{context}"] -= Understanding Init Containers - -You can use an Init Container resource to perform tasks before the rest of a pod is deployed. - -A pod can have Init Containers in addition to application containers. Init -containers allow you to reorganize setup scripts and binding code. - -An Init Container can: - -* Contain and run utilities that are not desirable to include in the app Container image for security reasons. -* Contain utilities or custom code for setup that is not present in an app image. For example, there is no requirement to make an image FROM another image just to use a tool like sed, awk, python, or dig during setup. -* Use Linux namespaces so that they have different filesystem views from app containers, such as access to secrets that application containers are not able to access. - -Each Init Container must complete successfully before the next one is started. So, Init Containers provide an easy way to block or delay the startup of app containers until some set of preconditions are met. - -For example, the following are some ways you can use Init Containers: - -* Wait for a service to be created with a shell command like: -+ -[source,terminal] ----- -for i in {1..100}; do sleep 1; if dig myservice; then exit 0; fi; done; exit 1 ----- - -* Register this Pod with a remote server from the downward API with a command like: -+ -[source,terminal] ----- -$ curl -X POST http://$MANAGEMENT_SERVICE_HOST:$MANAGEMENT_SERVICE_PORT/register -d ‘instance=$()&ip=$()’ ----- - -* Wait for some time before starting the app Container with a command like `sleep 60`. - -* Clone a git repository into a volume. - -* Place values into a configuration file and run a template tool to dynamically generate a configuration file for the main app Container. For example, place the POD_IP value in a configuration and generate the main app configuration file using Jinja. - -See the link:https://kubernetes.io/docs/concepts/workloads/pods/init-containers/[Kubernetes documentation] for more information. diff --git a/modules/nodes-containers-init-creating.adoc b/modules/nodes-containers-init-creating.adoc deleted file mode 100644 index a6b26595b306..000000000000 --- a/modules/nodes-containers-init-creating.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-init.adoc - -[id="nodes-containers-init-creating_{context}"] -= Creating Init Containers - -The following example outlines a simple Pod which has two Init Containers. The first waits for `myservice` and the second waits for `mydb`. Once both containers complete, the pod begins. - -.Procedure - -. Create a YAML file for the Init Container: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: myapp-pod - labels: - app: myapp -spec: - containers: - - name: myapp-container - image: busybox - command: ['sh', '-c', 'echo The app is running! && sleep 3600'] - initContainers: - - name: init-myservice - image: busybox - command: ['sh', '-c', 'until nslookup myservice; do echo waiting for myservice; sleep 2; done;'] - - name: init-mydb - image: busybox - command: ['sh', '-c', 'until nslookup mydb; do echo waiting for mydb; sleep 2; done;'] ----- - -. Create a YAML file for the `myservice` service. -+ -[source,yaml] ----- -kind: Service -apiVersion: v1 -metadata: - name: myservice -spec: - ports: - - protocol: TCP - port: 80 - targetPort: 9376 ----- - -. Create a YAML file for the `mydb` service. -+ -[source,yaml] ----- -kind: Service -apiVersion: v1 -metadata: - name: mydb -spec: - ports: - - protocol: TCP - port: 80 - targetPort: 9377 ----- - -. Run the following command to create the `myapp-pod`: -+ -[source,terminal] ----- -$ oc create -f myapp.yaml ----- -+ -.Example output -[source,terminal] ----- -pod/myapp-pod created ----- - -. View the status of the pod: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -myapp-pod 0/1 Init:0/2 0 5s ----- -+ -Note that the pod status indicates it is waiting - -. Run the following commands to create the services: -+ -[source,terminal] ----- -$ oc create -f mydb.yaml ----- -+ -[source,terminal] ----- -$ oc create -f myservice.yaml ----- - -. View the status of the pod: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -myapp-pod 1/1 Running 0 2m ----- - diff --git a/modules/nodes-containers-port-forwarding-about.adoc b/modules/nodes-containers-port-forwarding-about.adoc deleted file mode 100644 index fc67942fb9e5..000000000000 --- a/modules/nodes-containers-port-forwarding-about.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-port-forwarding.adoc - -[id="nodes-containers-port-forwarding-about_{context}"] -= Understanding port forwarding - -You can use the CLI to forward one or more local ports to a pod. This allows you -to listen on a given or random port locally, and have data forwarded to and from -given ports in the pod. - -Support for port forwarding is built into the CLI: - -[source,terminal] ----- -$ oc port-forward <pod> [<local_port>:]<remote_port> [...[<local_port_n>:]<remote_port_n>] ----- - -The CLI listens on each local port specified by the user, forwarding using the protocol described below. - -Ports may be specified using the following formats: - -[horizontal] -`5000`:: The client listens on port 5000 locally and forwards to 5000 in the -pod. -`6000:5000`:: The client listens on port 6000 locally and forwards to 5000 in -the pod. -`:5000` or `0:5000`:: The client selects a free local port and forwards to 5000 -in the pod. - -{product-title} handles port-forward requests from clients. Upon receiving a request, {product-title} upgrades the response and waits for the client -to create port-forwarding streams. When {product-title} receives a new stream, it copies data between the stream and the pod’s port. - -Architecturally, there are options for forwarding to a pod’s port. The supported {product-title} implementation invokes `nsenter` directly on the node host -to enter the pod’s network namespace, then invokes `socat` to copy data between the stream and the pod’s port. However, a custom implementation could -include running a _helper_ pod that then runs `nsenter` and `socat`, so that those binaries are not required to be installed on the host. - diff --git a/modules/nodes-containers-port-forwarding-protocol.adoc b/modules/nodes-containers-port-forwarding-protocol.adoc deleted file mode 100644 index 703bb6e8ea0e..000000000000 --- a/modules/nodes-containers-port-forwarding-protocol.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-port-forwarding.adoc - -[id="nodes-containers-port-forwarding-protocol_{context}"] -= Protocol for initiating port forwarding from a client - -Clients initiate port forwarding to a pod by issuing a request to the -Kubernetes API server: - ----- -/proxy/nodes/<node_name>/portForward/<namespace>/<pod> ----- - -In the above URL: - -- `<node_name>` is the FQDN of the node. -- `<namespace>` is the namespace of the target pod. -- `<pod>` is the name of the target pod. - -For example: - ----- -/proxy/nodes/node123.openshift.com/portForward/myns/mypod ----- - -After sending a port forward request to the API server, the client upgrades the -connection to one that supports multiplexed streams; the current implementation -uses link:http://www.chromium.org/spdy[*SPDY*]. - -The client creates a stream with the `port` header containing the target port in -the pod. All data written to the stream is delivered via the kubelet to the -target pod and port. Similarly, all data sent from the pod for that forwarded -connection is delivered back to the same stream in the client. - -The client closes all streams, the upgraded connection, and the underlying -connection when it is finished with the port forwarding request. - diff --git a/modules/nodes-containers-port-forwarding-using.adoc b/modules/nodes-containers-port-forwarding-using.adoc deleted file mode 100644 index 409b1d3b4400..000000000000 --- a/modules/nodes-containers-port-forwarding-using.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-port-forwarding.adoc - -[id="nodes-containers-port-forwarding-using_{context}"] -= Using port forwarding - -You can use the CLI to port-forward one or more local ports to a pod. - -.Procedure - -Use the following command to listen on the specified port in a pod: - -[source,terminal] ----- -$ oc port-forward <pod> [<local_port>:]<remote_port> [...[<local_port_n>:]<remote_port_n>] ----- - -For example: - -* Use the following command to listen on ports `5000` and `6000` locally and forward data to and from ports `5000` and `6000` in the pod: -+ -[source,terminal] ----- -$ oc port-forward <pod> 5000 6000 ----- -+ -.Example output -[source,terminal] ----- -Forwarding from 127.0.0.1:5000 -> 5000 -Forwarding from [::1]:5000 -> 5000 -Forwarding from 127.0.0.1:6000 -> 6000 -Forwarding from [::1]:6000 -> 6000 ----- - -* Use the following command to listen on port `8888` locally and forward to `5000` in the pod: -+ -[source,terminal] ----- -$ oc port-forward <pod> 8888:5000 ----- -+ -.Example output -[source,terminal] ----- -Forwarding from 127.0.0.1:8888 -> 5000 -Forwarding from [::1]:8888 -> 5000 ----- - -* Use the following command to listen on a free port locally and forward to `5000` in the pod: -+ -[source,terminal] ----- -$ oc port-forward <pod> :5000 ----- -+ -.Example output -[source,terminal] ----- -Forwarding from 127.0.0.1:42390 -> 5000 -Forwarding from [::1]:42390 -> 5000 ----- -+ -Or: -+ -[source,terminal] ----- -$ oc port-forward <pod> 0:5000 ----- - diff --git a/modules/nodes-containers-projected-volumes-about.adoc b/modules/nodes-containers-projected-volumes-about.adoc deleted file mode 100644 index 9ea22508461f..000000000000 --- a/modules/nodes-containers-projected-volumes-about.adoc +++ /dev/null @@ -1,181 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-projected-volumes.adoc - -[id="nodes-containers-projected-volumes-about_{context}"] -= Understanding projected volumes - -Projected volumes can map any combination of these volume sources into a single directory, allowing the user to: - -* automatically populate a single volume with the keys from multiple secrets, config maps, and with downward API information, -so that I can synthesize a single directory with various sources of information; -* populate a single volume with the keys from multiple secrets, config maps, and with downward API information, -explicitly specifying paths for each item, so that I can have full control over the contents of that volume. - -The following general scenarios show how you can use projected volumes. - -*Config map, secrets, Downward API.*:: -Projected volumes allow you to deploy containers with configuration data that includes passwords. -An application using these resources could be deploying {rh-openstack-first} on Kubernetes. The configuration data might have to be assembled differently depending on if the services are going to be used for production or for testing. If a pod is labeled with production or testing, the downward API selector `metadata.labels` can be used to produce the correct {rh-openstack} configs. - -*Config map + secrets.*:: -Projected volumes allow you to deploy containers involving configuration data and passwords. -For example, you might execute a config map with some sensitive encrypted tasks that are decrypted using a vault password file. - -*ConfigMap + Downward API.*:: -Projected volumes allow you to generate a config including the pod name (available via the `metadata.name` selector). This application can then pass the pod name along with requests to easily determine the source without using IP tracking. - -*Secrets + Downward API.*:: -Projected volumes allow you to use a secret as a public key to encrypt the namespace of the pod (available via the `metadata.namespace` selector). -This example allows the Operator to use the application to deliver the namespace information securely without using an encrypted transport. - -[id="projected-volumes-examples_{context}"] -== Example `Pod` specs - -The following are examples of `Pod` specs for creating projected volumes. - -.Pod with a secret, a Downward API, and a config map - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: volume-test -spec: - containers: - - name: container-test - image: busybox - volumeMounts: <1> - - name: all-in-one - mountPath: "/projected-volume"<2> - readOnly: true <3> - volumes: <4> - - name: all-in-one <5> - projected: - defaultMode: 0400 <6> - sources: - - secret: - name: mysecret <7> - items: - - key: username - path: my-group/my-username <8> - - downwardAPI: <9> - items: - - path: "labels" - fieldRef: - fieldPath: metadata.labels - - path: "cpu_limit" - resourceFieldRef: - containerName: container-test - resource: limits.cpu - - configMap: <10> - name: myconfigmap - items: - - key: config - path: my-group/my-config - mode: 0777 <11> ----- - -<1> Add a `volumeMounts` section for each container that needs the secret. -<2> Specify a path to an unused directory where the secret will appear. -<3> Set `readOnly` to `true`. -<4> Add a `volumes` block to list each projected volume source. -<5> Specify any name for the volume. -<6> Set the execute permission on the files. -<7> Add a secret. Enter the name of the secret object. Each secret you want to use must be listed. -<8> Specify the path to the secrets file under the `mountPath`. Here, the secrets file is in *_/projected-volume/my-group/my-username_*. -<9> Add a Downward API source. -<10> Add a ConfigMap source. -<11> Set the mode for the specific projection - -[NOTE] -==== -If there are multiple containers in the pod, each container needs a `volumeMounts` section, but only one `volumes` section is needed. -==== - - -.Pod with multiple secrets with a non-default permission mode set - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: volume-test -spec: - containers: - - name: container-test - image: busybox - volumeMounts: - - name: all-in-one - mountPath: "/projected-volume" - readOnly: true - volumes: - - name: all-in-one - projected: - defaultMode: 0755 - sources: - - secret: - name: mysecret - items: - - key: username - path: my-group/my-username - - secret: - name: mysecret2 - items: - - key: password - path: my-group/my-password - mode: 511 ----- - -[NOTE] -==== -The `defaultMode` can only be specified at the projected level and not for each -volume source. However, as illustrated above, you can explicitly set the `mode` -for each individual projection. -==== - -[id="projected-volumes-pathing_{context}"] -== Pathing Considerations - -*Collisions Between Keys when Configured Paths are Identical*:: If you configure any keys with the same path, the pod spec will not be accepted as valid. -In the following example, the specified path for `mysecret` and `myconfigmap` are the same: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: volume-test -spec: - containers: - - name: container-test - image: busybox - volumeMounts: - - name: all-in-one - mountPath: "/projected-volume" - readOnly: true - volumes: - - name: all-in-one - projected: - sources: - - secret: - name: mysecret - items: - - key: username - path: my-group/data - - configMap: - name: myconfigmap - items: - - key: config - path: my-group/data ----- - -Consider the following situations related to the volume file paths. - -*Collisions Between Keys without Configured Paths*:: The only run-time validation that can occur is when all the paths are known at pod creation, similar to the above scenario. Otherwise, when a conflict occurs the most recent specified resource will overwrite anything preceding it -(this is true for resources that are updated after pod creation as well). - -*Collisions when One Path is Explicit and the Other is Automatically Projected*:: In the event that there is a collision due to a user specified path matching data that is automatically projected, -the latter resource will overwrite anything preceding it as before diff --git a/modules/nodes-containers-projected-volumes-creating.adoc b/modules/nodes-containers-projected-volumes-creating.adoc deleted file mode 100644 index 61139c764cf5..000000000000 --- a/modules/nodes-containers-projected-volumes-creating.adoc +++ /dev/null @@ -1,229 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-projected-volumes.adoc - -[id="nodes-containers-projected-volumes-creating_{context}"] -= Configuring a Projected Volume for a Pod - -When creating projected volumes, consider the volume file path situations described in _Understanding projected volumes_. - -The following example shows how to use a projected volume to mount an existing secret volume source. The steps can be used to create a user name and password secrets from local files. You then create a pod that runs one container, using a projected volume to mount the secrets into the same shared directory. - -.Procedure - -To use a projected volume to mount an existing secret volume source. - -. Create files containing the secrets, entering the following, replacing the password and user information as appropriate: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: mysecret -type: Opaque -data: - pass: MWYyZDFlMmU2N2Rm - user: YWRtaW4= ----- -+ -The `user` and `pass` values can be any valid string that is *base64* encoded. -+ -The following example shows `admin` in base64: -+ -[source,terminal] ----- -$ echo -n "admin" | base64 ----- -+ -.Example output -[source,terminal] ----- -YWRtaW4= ----- -+ -The following example shows the password `1f2d1e2e67df` in base64:. -+ -[source,terminal] ----- -$ echo -n "1f2d1e2e67df" | base64 ----- -+ -.Example output -[source,terminal] ----- -MWYyZDFlMmU2N2Rm ----- - -. Use the following command to create the secrets: -+ -[source,terminal] ----- -$ oc create -f <secrets-filename> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f secret.yaml ----- -+ -.Example output -[source,terminal] ----- -secret "mysecret" created ----- - -. You can check that the secret was created using the following commands: -+ -[source,terminal] ----- -$ oc get secret <secret-name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get secret mysecret ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE DATA AGE -mysecret Opaque 2 17h ----- -+ -[source,terminal] ----- -$ oc get secret <secret-name> -o yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get secret mysecret -o yaml ----- -+ -[source,yaml] ----- -apiVersion: v1 -data: - pass: MWYyZDFlMmU2N2Rm - user: YWRtaW4= -kind: Secret -metadata: - creationTimestamp: 2017-05-30T20:21:38Z - name: mysecret - namespace: default - resourceVersion: "2107" - selfLink: /api/v1/namespaces/default/secrets/mysecret - uid: 959e0424-4575-11e7-9f97-fa163e4bd54c -type: Opaque ----- - -. Create a pod configuration file similar to the following that includes a `volumes` section: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: test-projected-volume -spec: - containers: - - name: test-projected-volume - image: busybox - args: - - sleep - - "86400" - volumeMounts: - - name: all-in-one - mountPath: "/projected-volume" - readOnly: true - volumes: - - name: all-in-one - projected: - sources: - - secret: <1> - name: user - - secret: <1> - name: pass ----- -<1> The name of the secret you created. - -. Create the pod from the configuration file: -+ -[source,terminal] ----- -$ oc create -f <your_yaml_file>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f secret-pod.yaml ----- -+ -.Example output -[source,terminal] ----- -pod "test-projected-volume" created ----- - -. Verify that the pod container is running, and then watch for changes to -the pod: -+ -[source,terminal] ----- -$ oc get pod <name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get pod test-projected-volume ----- -+ -The output should appear similar to the following: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -test-projected-volume 1/1 Running 0 14s ----- - -. In another terminal, use the `oc exec` command to open a shell to the running container: -+ -[source,terminal] ----- -$ oc exec -it <pod> <command> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc exec -it test-projected-volume -- /bin/sh ----- - -. In your shell, verify that the `projected-volumes` directory contains your projected sources: -+ -[source,terminal] ----- -/ # ls ----- -+ -.Example output -[source,terminal] ----- -bin home root tmp -dev proc run usr -etc projected-volume sys var ----- diff --git a/modules/nodes-containers-remote-commands-about.adoc b/modules/nodes-containers-remote-commands-about.adoc deleted file mode 100644 index 6ade85ee9c03..000000000000 --- a/modules/nodes-containers-remote-commands-about.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-remote-commands.adoc - -[id="nodes-containers-remote-commands-about_{context}"] -= Executing remote commands in containers - -Support for remote container command execution is built into the CLI. - -.Procedure - -To run a command in a container: - -[source,terminal] ----- -$ oc exec <pod> [-c <container>] <command> [<arg_1> ... <arg_n>] ----- - -For example: - -[source,terminal] ----- -$ oc exec mypod date ----- - -.Example output -[source,terminal] ----- -Thu Apr 9 02:21:53 UTC 2015 ----- - -[IMPORTANT] -==== -link:https://access.redhat.com/errata/RHSA-2015:1650[For security purposes], the -`oc exec` command does not work when accessing privileged containers except when -the command is executed by a `cluster-admin` user. -==== diff --git a/modules/nodes-containers-remote-commands-protocol.adoc b/modules/nodes-containers-remote-commands-protocol.adoc deleted file mode 100644 index 1d950629fffb..000000000000 --- a/modules/nodes-containers-remote-commands-protocol.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-remote-commands.adoc - -[id="nodes-containers-remote-commands-protocol_{context}"] -= Protocol for initiating a remote command from a client - -Clients initiate the execution of a remote command in a container by issuing a -request to the Kubernetes API server: - -[source, terminal] ----- -/proxy/nodes/<node_name>/exec/<namespace>/<pod>/<container>?command=<command> ----- - -In the above URL: - -- `<node_name>` is the FQDN of the node. -- `<namespace>` is the project of the target pod. -- `<pod>` is the name of the target pod. -- `<container>` is the name of the target container. -- `<command>` is the desired command to be executed. - -For example: - -[source, terminal] ----- -/proxy/nodes/node123.openshift.com/exec/myns/mypod/mycontainer?command=date ----- - -Additionally, the client can add parameters to the request to indicate if: - -- the client should send input to the remote container's command (stdin). -- the client's terminal is a TTY. -- the remote container's command should send output from stdout to the client. -- the remote container's command should send output from stderr to the client. - -After sending an `exec` request to the API server, the client upgrades the -connection to one that supports multiplexed streams; the current implementation -uses *SPDY*. - -The client creates one stream each for stdin, stdout, and stderr. To distinguish -among the streams, the client sets the `streamType` header on the stream to one -of `stdin`, `stdout`, or `stderr`. - -The client closes all streams, the upgraded connection, and the underlying -connection when it is finished with the remote command execution request. diff --git a/modules/nodes-containers-sysctls-about.adoc b/modules/nodes-containers-sysctls-about.adoc deleted file mode 100644 index 15ac935ddaf7..000000000000 --- a/modules/nodes-containers-sysctls-about.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/containers/nodes-containers-sysctls.adoc - -[id="nodes-containers-sysctls-about_{context}"] -= About sysctls - -In Linux, the sysctl interface allows an administrator to modify kernel -parameters at runtime. Parameters are available via the *_/proc/sys/_* virtual -process file system. The parameters cover various subsystems, such as: - -- kernel (common prefix: *_kernel._*) -- networking (common prefix: *_net._*) -- virtual memory (common prefix: *_vm._*) -- MDADM (common prefix: *_dev._*) - -More subsystems are described in -link:https://www.kernel.org/doc/Documentation/sysctl/README[Kernel documentation]. -To get a list of all parameters, run: - -[source,terminal] ----- -$ sudo sysctl -a ----- - -[[namespaced-vs-node-level-sysctls]] -== Namespaced versus node-level sysctls - -A number of sysctls are _namespaced_ in the Linux kernels. This means that -you can set them independently for each pod on a node. Being namespaced is a -requirement for sysctls to be accessible in a pod context within Kubernetes. - -The following sysctls are known to be namespaced: - -- *_kernel.shm*_* -- *_kernel.msg*_* -- *_kernel.sem_* -- *_fs.mqueue.*_* - -Additionally, most of the sysctls in the *net.** group are known -to be namespaced. Their namespace adoption differs based on the kernel -version and distributor. - -Sysctls that are not namespaced are called _node-level_ and must be set -manually by the cluster administrator, either by means of the underlying Linux -distribution of the nodes, such as by modifying the *_/etc/sysctls.conf_* file, -or by using a daemon set with privileged containers. - -[NOTE] -==== -Consider marking nodes with special sysctls as tainted. Only schedule pods onto -them that need those sysctl settings. Use the taints and toleration feature to mark the nodes. -==== - -[[safe-vs-unsafe-sysclts]] -== Safe versus unsafe sysctls - -Sysctls are grouped into _safe_ and _unsafe_ sysctls. - -For a sysctl to be considered safe, it must use proper -namespacing and must be properly isolated between pods on the same -node. This means that if you set a sysctl for one pod it must not: - -- Influence any other pod on the node -- Harm the node's health -- Gain CPU or memory resources outside of the resource limits of a pod - -{product-title} supports, or whitelists, the following sysctls -in the safe set: - -- *_kernel.shm_rmid_forced_* -- *_net.ipv4.ip_local_port_range_* -- *_net.ipv4.tcp_syncookies_* - -All safe sysctls are enabled by default. You can use a sysctl in a pod by modifying -the `Pod` spec. - -Any sysctl not whitelisted by {product-title} is considered unsafe for {product-title}. -Note that being namespaced alone is not sufficient for the sysctl to be considered safe. - -All unsafe sysctls are disabled by default, and the cluster administrator must -manually enable them on a per-node basis. Pods with disabled unsafe sysctls -are scheduled but do not launch. - -[source,terminal] ----- -$ oc get pod ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -hello-pod 0/1 SysctlForbidden 0 14s ----- diff --git a/modules/nodes-containers-sysctls-setting.adoc b/modules/nodes-containers-sysctls-setting.adoc deleted file mode 100644 index 771b531dc839..000000000000 --- a/modules/nodes-containers-sysctls-setting.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/containers/nodes-containers-sysctls.adoc - -[id="nodes-containers-sysctls-setting_{context}"] -= Setting sysctls for a pod - -You can set sysctls on pods using the pod's `securityContext`. The `securityContext` -applies to all containers in the same pod. - -Safe sysctls are allowed by default. A pod with unsafe sysctls fails -to launch on any node unless the cluster administrator explicitly enables unsafe sysctls for -that node. As with node-level sysctls, use the taints and toleration feature -or labels on nodes to schedule those pods onto the right nodes. - -The following example uses the pod `securityContext` to set a safe sysctl -`kernel.shm_rmid_forced` and two unsafe sysctls, `net.ipv4.route.min_pmtu` and -`kernel.msgmax`. There is no distinction between _safe_ and _unsafe_ sysctls in -the specification. - -[WARNING] -==== -To avoid destabilizing your operating system, modify sysctl parameters only -after you understand their effects. -==== - -.Procedure - -To use safe and unsafe sysctls: - -. Modify the YAML file that defines the pod and add the `securityContext` spec, as -shown in the following example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: sysctl-example -spec: - securityContext: - sysctls: - - name: kernel.shm_rmid_forced - value: "0" - - name: net.ipv4.route.min_pmtu - value: "552" - - name: kernel.msgmax - value: "65536" - ... ----- - -. Create the pod: -+ -[source,terminal] ----- -$ oc apply -f <file-name>.yaml ----- -+ -If the unsafe sysctls are not allowed for the node, the pod is scheduled, -but does not deploy: -+ -[source,terminal] ----- -$ oc get pod ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -hello-pod 0/1 SysctlForbidden 0 14s ----- diff --git a/modules/nodes-containers-sysctls-unsafe.adoc b/modules/nodes-containers-sysctls-unsafe.adoc deleted file mode 100644 index 1a649ac636ea..000000000000 --- a/modules/nodes-containers-sysctls-unsafe.adoc +++ /dev/null @@ -1,126 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/containers/nodes-containers-sysctls.adoc - -[id="nodes-containers-sysctls-unsafe_{context}"] -= Enabling unsafe sysctls - -A cluster administrator can allow certain unsafe sysctls for very special -situations such as high performance or real-time application tuning. - -If you want to use unsafe sysctls, a cluster administrator must enable them -individually for a specific type of node. The sysctls must be namespaced. - -You can further control which sysctls can be set in pods by specifying lists of sysctls or sysctl patterns in the `forbiddenSysctls` and `allowedUnsafeSysctls` fields of the Security Context Constraints. - -- The `forbiddenSysctls` option excludes specific sysctls. -- The `allowedUnsafeSysctls` option controls specific needs such as high performance or real-time application tuning. - -[WARNING] -==== -Due to their nature of being unsafe, the use of unsafe sysctls is -at-your-own-risk and can lead to severe problems, such as improper behavior of -containers, resource shortage, or breaking a node. -==== - -.Procedure - -. Add a label to the machine config pool where the containers where containers -with the unsafe sysctls will run: -+ -[source,terminal] ----- -$ oc edit machineconfigpool worker ----- -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool -metadata: - creationTimestamp: 2019-02-08T14:52:39Z - generation: 1 - labels: - custom-kubelet: sysctl <1> ----- -<1> Add a `key: pair` label. - -. Create a `KubeletConfig` custom resource (CR): -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: custom-kubelet -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: sysctl <1> - kubeletConfig: - allowedUnsafeSysctls: <2> - - "kernel.msg*" - - "net.ipv4.route.min_pmtu" ----- -<1> Specify the label from the machine config pool. -<2> List the unsafe sysctls you want to allow. - -. Create the object: -+ -[source,terminal] ----- -$ oc apply -f set-sysctl-worker.yaml ----- -+ -A new `MachineConfig` object named in the `99-worker-XXXXXX-XXXXX-XXXX-XXXXX-kubelet` format is created. - -. Wait for the cluster to reboot usng the `machineconfigpool` object `status` fields: -+ -For example: -+ -[source,yaml] ----- -status: - conditions: - - lastTransitionTime: '2019-08-11T15:32:00Z' - message: >- - All nodes are updating to - rendered-worker-ccbfb5d2838d65013ab36300b7b3dc13 - reason: '' - status: 'True' - type: Updating ----- -+ -A message similar to the following appears when the cluster is ready: -+ -[source,yaml] ----- - - lastTransitionTime: '2019-08-11T16:00:00Z' - message: >- - All nodes are updated with - rendered-worker-ccbfb5d2838d65013ab36300b7b3dc13 - reason: '' - status: 'True' - type: Updated ----- - -. When the cluster is ready, check for the merged `KubeletConfig` object in the new `MachineConfig` object: -+ -[source,terminal] ----- -$ oc get machineconfig 99-worker-XXXXXX-XXXXX-XXXX-XXXXX-kubelet -o json | grep ownerReference -A7 ----- -+ -[source,yaml] ----- - "ownerReferences": [ - { - "apiVersion": "machineconfiguration.openshift.io/v1", - "blockOwnerDeletion": true, - "controller": true, - "kind": "KubeletConfig", - "name": "custom-kubelet", - "uid": "3f64a766-bae8-11e9-abe8-0a1a2a4813f2" ----- -+ -You can now add unsafe sysctls to pods as needed. diff --git a/modules/nodes-containers-volumes-about.adoc b/modules/nodes-containers-volumes-about.adoc deleted file mode 100644 index 615dfa3b4f59..000000000000 --- a/modules/nodes-containers-volumes-about.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-volumes.adoc - -[id="nodes-containers-volumes-about_{context}"] -= Understanding volumes - -Volumes are mounted file systems available to pods and their -containers which may be backed by a number of host-local or network attached -storage endpoints. Containers are not persistent by default; on restart, their contents are -cleared. - -To ensure that the file system on the volume contains no errors and, if errors -are present, to repair them when possible, {product-title} invokes the `fsck` -utility prior to the `mount` utility. This occurs when either adding a volume or -updating an existing volume. - -The simplest volume type is `emptyDir`, which is a temporary directory on a -single machine. Administrators may also allow you to request a persistent volume that is automatically attached -to your pods. - -[NOTE] -==== -`emptyDir` volume storage may be restricted by a quota based on the pod's -FSGroup, if the FSGroup parameter is enabled by your cluster administrator. -==== - diff --git a/modules/nodes-containers-volumes-adding.adoc b/modules/nodes-containers-volumes-adding.adoc deleted file mode 100644 index ce362312e03f..000000000000 --- a/modules/nodes-containers-volumes-adding.adoc +++ /dev/null @@ -1,114 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-volumes.adoc - -[id="nodes-containers-volumes-adding_{context}"] -= Adding volumes to a pod - -You can add volumes and volume mounts to a pod. - -.Procedure - -To add a volume, a volume mount, or both to pod templates: - -[source,terminal] ----- -$ oc set volume <object_type>/<name> --add [options] ----- - -.Supported Options for Adding Volumes -[cols="3a*",options="header"] -|=== - -|Option |Description |Default - -|`--name` -|Name of the volume. -|Automatically generated, if not specified. - -|`-t, --type` -|Name of the volume source. Supported values: `emptyDir`, `hostPath`, `secret`, -`configmap`, `persistentVolumeClaim` or `projected`. -|`emptyDir` - -|`-c, --containers` -|Select containers by name. It can also take wildcard `'*'` that matches any -character. -|`'*'` - -|`-m, --mount-path` -|Mount path inside the selected containers. -| - -|`--path` -|Host path. Mandatory parameter for `--type=hostPath`. -| - -|`--secret-name` -|Name of the secret. Mandatory parameter for `--type=secret`. -| - -|`--configmap-name` -|Name of the configmap. Mandatory parameter for `--type=configmap`. -| - -|`--claim-name` -|Name of the persistent volume claim. Mandatory parameter for -`--type=persistentVolumeClaim`. -| - -|`--source` -|Details of volume source as a JSON string. Recommended if the desired volume -source is not supported by `--type`. -| - -|`-o, --output` -|Display the modified objects instead of updating them on the server. Supported -values: `json`, `yaml`. -| - -|`--output-version` -|Output the modified objects with the given version. -|`api-version` -|=== - - -For example: - -* To add a new volume source *emptyDir* to the *registry* `DeploymentConfig` object: -+ -[source,terminal] ----- -$ oc set volume dc/registry --add ----- - -* To add volume *v1* with secret *secret1* for replication controller *r1* and mount -inside the containers at *_/data_*: -+ -[source,terminal] ----- -$ oc set volume rc/r1 --add --name=v1 --type=secret --secret-name='secret1' --mount-path=/data ----- - -* To add existing persistent volume *v1* with claim name *pvc1* to deployment -configuration *_dc.json_* on disk, mount the volume on container *c1* at -*_/data_*, and update the `DeploymentConfig` object on the server: -+ -[source,terminal] ----- -$ oc set volume -f dc.json --add --name=v1 --type=persistentVolumeClaim \ - --claim-name=pvc1 --mount-path=/data --containers=c1 ----- - -* To add a volume *v1* based on Git repository -*$$https://github.com/namespace1/project1$$* with revision *5125c45f9f563* for -all replication controllers: -+ -[source,terminal] ----- -$ oc set volume rc --all --add --name=v1 \ - --source='{"gitRepo": { - "repository": "https://github.com/namespace1/project1", - "revision": "5125c45f9f563" - }}' ----- diff --git a/modules/nodes-containers-volumes-cli.adoc b/modules/nodes-containers-volumes-cli.adoc deleted file mode 100644 index f922926e9b8e..000000000000 --- a/modules/nodes-containers-volumes-cli.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-volumes.adoc - -[id="nodes-containers-volumes-cli_{context}"] -= Working with volumes using the {product-title} CLI - -You can use the CLI command `oc set volume` to add and remove volumes and -volume mounts for any object that has a pod template like replication controllers or -deployment configs. You can also list volumes in pods or any -object that has a pod template. - -The `oc set volume` command uses the following general syntax: - -[source,terminal] ----- -$ oc set volume <object_selection> <operation> <mandatory_parameters> <options> ----- - - -Object selection:: -Specify one of the following for the `object_selection` parameter in the `oc set volume` command: - -[id="vol-object-selection_{context}"] -.Object Selection -[cols="3a*",options="header"] -|=== - -|Syntax |Description |Example - -|`_<object_type>_ _<name>_` -|Selects `_<name>_` of type `_<object_type>_`. -|`deploymentConfig registry` - -|`_<object_type>_/_<name>_` -|Selects `_<name>_` of type `_<object_type>_`. -|`deploymentConfig/registry` - -|`_<object_type>_` -`--selector=_<object_label_selector>_` -|Selects resources of type `_<object_type>_` that matched the given label -selector. -|`deploymentConfig` -`--selector="name=registry"` - -|`_<object_type>_ --all` -|Selects all resources of type `_<object_type>_`. -|`deploymentConfig --all` - -|`-f` or -`--filename=_<file_name>_` -|File name, directory, or URL to file to use to edit the resource. -|`-f registry-deployment-config.json` -|=== - - -Operation:: -Specify `--add` or `--remove` for the `operation` parameter in the `oc set volume` command. - -Mandatory parameters:: -Any mandatory parameters are specific to the -selected operation and are discussed in later sections. - -Options:: -Any options are specific to the -selected operation and are discussed in later sections. diff --git a/modules/nodes-containers-volumes-listing.adoc b/modules/nodes-containers-volumes-listing.adoc deleted file mode 100644 index 42ecde0c45c6..000000000000 --- a/modules/nodes-containers-volumes-listing.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-volumes.adoc - -[id="nodes-containers-volumes-listing_{context}"] -= Listing volumes and volume mounts in a pod - -You can list volumes and volume mounts in pods or pod templates: - -.Procedure - -To list volumes: - -[source,terminal] ----- -$ oc set volume <object_type>/<name> [options] ----- - -List volume supported options: -[cols="3a*",options="header"] -|=== - -|Option |Description |Default - -|`--name` -|Name of the volume. -| - -|`-c, --containers` -|Select containers by name. It can also take wildcard `'*'` that matches any -character. -|`'*'` -|=== - -For example: - -* To list all volumes for pod *p1*: -+ -[source,terminal] ----- -$ oc set volume pod/p1 ----- - -* To list volume *v1* defined on all deployment configs: -+ -[source,terminal] ----- -$ oc set volume dc --all --name=v1 ----- diff --git a/modules/nodes-containers-volumes-removing.adoc b/modules/nodes-containers-volumes-removing.adoc deleted file mode 100644 index c5313de1a167..000000000000 --- a/modules/nodes-containers-volumes-removing.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-volumes.adoc - -[id="nodes-containers-volumes-removing_{context}"] -= Removing volumes and volume mounts from a pod - -You can remove a volume or volume mount from a pod. - -.Procedure - -To remove a volume from pod templates: - -[source,terminal] ----- -$ oc set volume <object_type>/<name> --remove [options] ----- - -.Supported options for removing volumes -[cols="3a*",options="header"] -|=== - -|Option |Description |Default - -|`--name` -|Name of the volume. -| - -|`-c, --containers` -|Select containers by name. It can also take wildcard `'*'` that matches any character. -|`'*'` - -|`--confirm` -|Indicate that you want to remove multiple volumes at once. -| - -|`-o, --output` -|Display the modified objects instead of updating them on the server. Supported values: `json`, `yaml`. -| - -|`--output-version` -|Output the modified objects with the given version. -|`api-version` -|=== - -For example: - -* To remove a volume *v1* from the `DeploymentConfig` object *d1*: -+ -[source,terminal] ----- -$ oc set volume dc/d1 --remove --name=v1 ----- - -* To unmount volume *v1* from container *c1* for the `DeploymentConfig` object *d1* and remove the volume *v1* if it is not referenced by any containers on *d1*: -+ -[source,terminal] ----- -$ oc set volume dc/d1 --remove --name=v1 --containers=c1 ----- - -* To remove all volumes for replication controller *r1*: -+ -[source,terminal] ----- -$ oc set volume rc/r1 --remove --confirm ----- diff --git a/modules/nodes-containers-volumes-subpath.adoc b/modules/nodes-containers-volumes-subpath.adoc deleted file mode 100644 index 5e7dd6284b85..000000000000 --- a/modules/nodes-containers-volumes-subpath.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-volumes.adoc - -[id="nodes-containers-volumes-subpath_{context}"] -= Configuring volumes for multiple uses in a pod - -You can configure a volume to allows you to share one volume for -multiple uses in a single pod using the `volumeMounts.subPath` property to specify a `subPath` value inside a volume -instead of the volume's root. - -.Procedure - -. View the list of files in the volume, run the `oc rsh` command: -+ -[source,terminal] ----- -$ oc rsh <pod> ----- -+ -.Example output -[source,terminal] ----- -sh-4.2$ ls /path/to/volume/subpath/mount -example_file1 example_file2 example_file3 ----- - -. Specify the `subPath`: -+ -.Example `Pod` spec with `subPath` parameter -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: my-site -spec: - containers: - - name: mysql - image: mysql - volumeMounts: - - mountPath: /var/lib/mysql - name: site-data - subPath: mysql <1> - - name: php - image: php - volumeMounts: - - mountPath: /var/www/html - name: site-data - subPath: html <2> - volumes: - - name: site-data - persistentVolumeClaim: - claimName: my-site-data ----- -<1> Databases are stored in the `mysql` folder. -<2> HTML content is stored in the `html` folder. diff --git a/modules/nodes-containers-volumes-updating.adoc b/modules/nodes-containers-volumes-updating.adoc deleted file mode 100644 index 6a8dae50f56b..000000000000 --- a/modules/nodes-containers-volumes-updating.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-containers-volumes.adoc - -[id="nodes-containers-volumes-updating_{context}"] -= Updating volumes and volume mounts in a pod - -You can modify the volumes and volume mounts in a pod. - -.Procedure - -Updating existing volumes using the `--overwrite` option: - -[source,terminal] ----- -$ oc set volume <object_type>/<name> --add --overwrite [options] ----- - -For example: - -* To replace existing volume *v1* for replication controller *r1* with existing -persistent volume claim *pvc1*: -+ -[source,terminal] ----- -$ oc set volume rc/r1 --add --overwrite --name=v1 --type=persistentVolumeClaim --claim-name=pvc1 ----- - -* To change the `DeploymentConfig` object *d1* mount point to *_/opt_* for volume *v1*: -+ -[source,terminal] ----- -$ oc set volume dc/d1 --add --overwrite --name=v1 --mount-path=/opt ----- diff --git a/modules/nodes-descheduler-about.adoc b/modules/nodes-descheduler-about.adoc deleted file mode 100644 index 73aaf6e87957..000000000000 --- a/modules/nodes-descheduler-about.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-descheduler.adoc - -[id="nodes-descheduler-about_{context}"] -= About the descheduler - -You can use the descheduler to evict pods based on specific strategies so that the pods can be rescheduled onto more appropriate nodes. - -You can benefit from descheduling running pods in situations such as the following: - -* Nodes are underutilized or overutilized. -* Pod and node affinity requirements, such as taints or labels, have changed and the original scheduling decisions are no longer appropriate for certain nodes. -* Node failure requires pods to be moved. -* New nodes are added to clusters. -* Pods have been restarted too many times. - -[IMPORTANT] -==== -The descheduler does not schedule replacement of evicted pods. The scheduler automatically performs this task for the evicted pods. -==== - -When the descheduler decides to evict pods from a node, it employs the following general mechanism: - -* Critical pods with `priorityClassName` set to `system-cluster-critical` or `system-node-critical` are never evicted. -* Static, mirrored, or stand-alone pods that are not part of a replication controller, replica set, deployment, or job are never evicted because these pods will not be recreated. -* Pods associated with daemon sets are never evicted. -* Pods with local storage are never evicted. -* Best effort pods are evicted before burstable and guaranteed pods. -* All types of pods with the `descheduler.alpha.kubernetes.io/evict` annotation are eligible for eviction. This annotation is used to override checks that prevent eviction, and the user can select which pod is evicted. Users should know how and if the pod will be recreated. -* Pods subject to pod disruption budget (PDB) are not evicted if descheduling violates its pod disruption budget (PDB). The pods are evicted by using eviction subresource to handle PDB. diff --git a/modules/nodes-descheduler-configuring-interval.adoc b/modules/nodes-descheduler-configuring-interval.adoc deleted file mode 100644 index 9aee5827dced..000000000000 --- a/modules/nodes-descheduler-configuring-interval.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-descheduler.adoc - -[id="nodes-descheduler-configuring-interval_{context}"] -= Configuring the descheduler interval - -You can configure the amount of time between descheduler runs. The default is 3600 seconds (one hour). - -.Prerequisites - -* Cluster administrator privileges - -.Procedure - -. Edit the `KubeDescheduler` object: -+ -[source,terminal] ----- -$ oc edit kubedeschedulers.operator.openshift.io cluster -n openshift-kube-descheduler-operator ----- - -. Update the `deschedulingIntervalSeconds` field to the desired value: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1beta1 -kind: KubeDescheduler -metadata: - name: cluster - namespace: openshift-kube-descheduler-operator -spec: - deschedulingIntervalSeconds: 3600 <1> -... ----- -<1> Set the number of seconds between descheduler runs. A value of `0` in this field runs the descheduler once and exits. - -. Save the file to apply the changes. diff --git a/modules/nodes-descheduler-configuring-profiles.adoc b/modules/nodes-descheduler-configuring-profiles.adoc deleted file mode 100644 index 41c4060e50e4..000000000000 --- a/modules/nodes-descheduler-configuring-profiles.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-descheduler.adoc - -[id="nodes-descheduler-configuring-profiles_{context}"] -= Configuring descheduler profiles - -You can configure which profiles the descheduler uses to evict pods. - -.Prerequisites - -* Cluster administrator privileges - -.Procedure - -. Edit the `KubeDescheduler` object: -+ -[source,terminal] ----- -$ oc edit kubedeschedulers.operator.openshift.io cluster -n openshift-kube-descheduler-operator ----- - -. Specify one or more profiles in the `spec.profiles` section. -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1beta1 -kind: KubeDescheduler -metadata: - name: cluster - namespace: openshift-kube-descheduler-operator -spec: - deschedulingIntervalSeconds: 3600 - logLevel: Normal - managementState: Managed - operatorLogLevel: Normal - profiles: - - AffinityAndTaints <1> - - TopologyAndDuplicates <2> - - LifecycleAndUtilization <3> ----- -<1> Enable the `AffinityAndTaints` profile, which evicts pods that violate inter-pod anti-affinity, node affinity, and node taints. -<2> Enable the `TopologyAndDuplicates` profile, which evicts pods in an effort to evenly spread similar pods, or pods of the same topology domain, among nodes. -<3> Enable the `LifecycleAndUtilization` profile, which evicts long-running pods and balances resource usage between nodes. -+ -You can enable multiple profiles; the order that the profiles are specified in is not important. - -. Save the file to apply the changes. diff --git a/modules/nodes-descheduler-installing.adoc b/modules/nodes-descheduler-installing.adoc deleted file mode 100644 index c4c5faab6936..000000000000 --- a/modules/nodes-descheduler-installing.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-descheduler.adoc - -[id="nodes-descheduler-installing_{context}"] -= Installing the descheduler - -The descheduler is not available by default. To enable the descheduler, you must install the Kube Descheduler Operator from OperatorHub and enable one or more descheduler profiles. - -.Prerequisites - -* Cluster administrator privileges. -* Access to the {product-title} web console. -ifdef::openshift-origin[] -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in _Obtaining the installation program_ in the installation documentation for your platform. -+ -If you have the pull secret, add the `redhat-operators` catalog to the OperatorHub custom resource (CR) as shown in _Configuring {product-title} to use Red Hat Operators_. -endif::[] - -.Procedure - -. Log in to the {product-title} web console. -. Create the required namespace for the Kube Descheduler Operator. -.. Navigate to *Administration* -> *Namespaces* and click *Create Namespace*. -.. Enter `openshift-kube-descheduler-operator` in the *Name* field and click *Create*. -. Install the Kube Descheduler Operator. -.. Navigate to *Operators* -> *OperatorHub*. -.. Type *Kube Descheduler Operator* into the filter box. -.. Select the *Kube Descheduler Operator* and click *Install*. -.. On the *Install Operator* page, select *A specific namespace on the cluster*. Select *openshift-kube-descheduler-operator* from the drop-down menu. -.. Adjust the values for the *Update Channel* and *Approval Strategy* to the desired values. -.. Click *Install*. -. Create a descheduler instance. -.. From the *Operators* -> *Installed Operators* page, click the *Kube Descheduler Operator*. -.. Select the *Kube Descheduler* tab and click *Create KubeDescheduler*. -.. Edit the settings as necessary and click *Create*. - -You can now configure the profiles for the descheduler. If you did not adjust the profiles when creating the descheduler instance from the web console, the `AffinityAndTaints` profile is enabled by default. diff --git a/modules/nodes-descheduler-profiles.adoc b/modules/nodes-descheduler-profiles.adoc deleted file mode 100644 index 7250d4934f86..000000000000 --- a/modules/nodes-descheduler-profiles.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-descheduler.adoc - -[id="nodes-descheduler-profiles_{context}"] -= Descheduler profiles - -The following descheduler profiles are available: - -`AffinityAndTaints`:: This profile evicts pods that violate inter-pod anti-affinity, node affinity, and node taints. -+ -It enables the following strategies: -+ -* `RemovePodsViolatingInterPodAntiAffinity`: removes pods that are violating inter-pod anti-affinity. -* `RemovePodsViolatingNodeAffinity`: removes pods that are violating node affinity. -* `RemovePodsViolatingNodeTaints`: removes pods that are violating `NoSchedule` taints on nodes. -+ -Pods with a node affinity type of `requiredDuringSchedulingIgnoredDuringExecution` are removed. - -`TopologyAndDuplicates`:: This profile evicts pods in an effort to evenly spread similar pods, or pods of the same topology domain, among nodes. -+ -It enables the following strategies: -+ -* `RemovePodsViolatingTopologySpreadConstraint`: finds unbalanced topology domains and tries to evict pods from larger ones when `DoNotSchedule` constraints are violated. -* `RemoveDuplicates`: ensures that there is only one pod associated with a replica set, replication controller, deployment, or job running on same node. If there are more, those duplicate pods are evicted for better pod distribution in a cluster. - -`LifecycleAndUtilization`:: This profile evicts long-running pods and balances resource usage between nodes. -+ -It enables the following strategies: -+ -* `RemovePodsHavingTooManyRestarts`: removes pods that have been restarted too many times. -+ -Pods that are restarted more than 100 times are removed. This includes restarts for Init Containers. - -* `LowNodeUtilization`: finds nodes that are underutilized and evicts pods, if possible, from overutilized nodes in the hope that recreation of evicted pods will be scheduled on these underutilized nodes. -+ -A node is considered underutilized if its usage is below 20% for all thresholds (CPU, memory, and number of pods). -+ -A node is considered overutilized if its usage is above 50% for any of the thresholds (CPU, memory, and number of pods). - -* `PodLifeTime`: evicts pods that are too old. -+ -Pods that are older than 24 hours are removed. diff --git a/modules/nodes-descheduler-uninstalling.adoc b/modules/nodes-descheduler-uninstalling.adoc deleted file mode 100644 index 02f68b9c7996..000000000000 --- a/modules/nodes-descheduler-uninstalling.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-descheduler.adoc - -[id="nodes-descheduler-uninstalling_{context}"] -= Uninstalling the descheduler - -You can remove the descheduler from your cluster by removing the descheduler instance and uninstalling the Kube Descheduler Operator. This procedure also cleans up the `KubeDescheduler` CRD and `openshift-kube-descheduler-operator` namespace. - -.Prerequisites - -* Cluster administrator privileges. -* Access to the {product-title} web console. - -.Procedure - -. Log in to the {product-title} web console. -. Delete the descheduler instance. -.. From the *Operators* -> *Installed Operators* page, click *Kube Descheduler Operator*. -.. Select the *Kube Descheduler* tab. -.. Click the Options menu {kebab} next to the *cluster* entry and select *Delete KubeDescheduler*. -.. In the confirmation dialog, click *Delete*. -. Uninstall the Kube Descheduler Operator. -.. Navigate to *Operators* -> *Installed Operators*, -.. Click the Options menu {kebab} next to the *Kube Descheduler Operator* entry and select *Uninstall Operator*. -.. In the confirmation dialog, click *Uninstall*. -. Delete the `openshift-kube-descheduler-operator` namespace. -.. Navigate to *Administration* -> *Namespaces*. -.. Enter `openshift-kube-descheduler-operator` into the filter box. -.. Click the Options menu {kebab} next to the *openshift-kube-descheduler-operator* entry and select *Delete Namespace*. -.. In the confirmation dialog, enter `openshift-kube-descheduler-operator` and click *Delete*. -. Delete the `KubeDescheduler` CRD. -.. Navigate to *Administration* -> *Custom Resource Definitions*. -.. Enter `KubeDescheduler` into the filter box. -.. Click the Options menu {kebab} next to the *KubeDescheduler* entry and select *Delete CustomResourceDefinition*. -.. In the confirmation dialog, click *Delete*. diff --git a/modules/nodes-edge-remote-workers-network.adoc b/modules/nodes-edge-remote-workers-network.adoc deleted file mode 100644 index f26b0b435592..000000000000 --- a/modules/nodes-edge-remote-workers-network.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/nodes-edge-remote-workers.adoc - -[id="nodes-edge-remote-workers-network_{context}"] -= Network separation with remote worker nodes - -All nodes send heartbeats to the Kubernetes Controller Manager Operator (kube controller) in the {product-title} cluster every 10 seconds. If the cluster does not receive heartbeats from a node, {product-title} responds using several default mechanisms. - -{product-title} is designed to be resilient to network partitions and other disruptions. You can mitigate some of the more common disruptions, such as interruptions from software upgrades, network splits, and routing issues. Mitigation strategies include ensuring that pods on remote worker nodes request the correct amount of CPU and memory resources, configuring an appropriate replication policy, using redundancy across zones, and using Pod Disruption Budgets on workloads. - -If the kube controller loses contact with a node after a configured period, the node controller on the control plane updates the node health to `Unhealthy` and marks the node `Ready` condition as `Unknown`. In response, the scheduler stops scheduling pods to that node. The on-premise node controller adds a `node.kubernetes.io/unreachable` taint with a `NoExecute` effect to the node and schedules pods on the node for eviction after five minutes, by default. - -On that node, the kubelet adds a `node.kubernetes.io/unreachable` taint with a `NoExecute` effect to the node and begins to evict pods on the node after five minutes, by default. - -If a workload controller, such as a `Deployment` object or `StatefulSet` object, is directing traffic to pods on the unhealthy node and other nodes can reach the cluster, {product-title} routes the traffic away from the pods on the node. Nodes that cannot reach the cluster do not get updated with the new traffic routing. As a result, the workloads on those nodes might continue to attempt to reach the unhealthy node. - -You can mitigate the effects of connection loss by: - -* using daemon sets to create pods that tolerate the taints -* using static pods that automatically restart if a node goes down -* using Kubernetes zones to control pod eviction -* configuring pod tolerations to delay or avoid pod eviction -* configuring the kubelet to control the timing of when it marks nodes as unhealthy. diff --git a/modules/nodes-edge-remote-workers-power.adoc b/modules/nodes-edge-remote-workers-power.adoc deleted file mode 100644 index b48d1311150b..000000000000 --- a/modules/nodes-edge-remote-workers-power.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/nodes-edge-remote-workers.adoc - -[id="nodes-edge-remote-workers-power_{context}"] -= Power loss on remote worker nodes - -If a remote worker node loses power or restarts ungracefully, {product-title} responds using several default mechanisms. - -If the Kubernetes Controller Manager Operator (kube controller) loses contact with a node after a configured period, the control plane updates the node health to `Unhealthy` and marks the node `Ready` condition as `Unknown`. In response, the scheduler stops scheduling pods to that node. The on-premise node controller adds a `node.kubernetes.io/unreachable` taint with a `NoExecute` effect to the node and schedules pods on the node for eviction after five minutes, by default. - -On the node, the pods must be restarted when the node recovers power and reconnects with the control plane. - -[NOTE] -==== -If you want the pods to restart immediately upon restart, use static pods. -==== - -After the node restarts, the kubelet also restarts and attempts to restart the pods that were scheduled on the node. If the connection to the control plane takes longer than the default five minutes, the control plane cannot update the node health and remove the `node.kubernetes.io/unreachable` taint. On the node, the kubelet terminates any running pods. When these conditions are cleared, the scheduler can start scheduling pods to that node. - -You can mitigate the effects of power loss by: - -* using daemon sets to create pods that tolerate the taints -* using static pods that automatically restart with a node -* configuring pods tolerations to delay or avoid pod eviction -* configuring the kubelet to control the timing of when the node controller marks nodes as unhealthy. - diff --git a/modules/nodes-edge-remote-workers-strategies.adoc b/modules/nodes-edge-remote-workers-strategies.adoc deleted file mode 100644 index 7910a5f61e9d..000000000000 --- a/modules/nodes-edge-remote-workers-strategies.adoc +++ /dev/null @@ -1,167 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/nodes-edge-remote-workers.adoc - -[id="nodes-edge-remote-workers-strategies_{context}"] -= Remote worker node strategies - -If you use remote worker nodes, consider which objects to use to run your applications. - -It is recommend to use daemon sets or static pods based on the behavior you want in the event of network issues or power loss. In addition, you can use Kubernetes zones and tolerations to control or avoid pod evictions if the control plane cannot reach remote worker nodes. - -[id="nodes-edge-remote-workers-strategies-daemonsets_{context}"] -Daemon sets:: -Daemon sets are the best approach to managing pods on remote worker nodes for the following reasons: --- -* Daemon sets do not typically need rescheduling behavior. If a node disconnects from the cluster, pods on the node can continue to run. {product-title} does not change the state of daemon set pods, and leaves the pods in the state they last reported. For example, if a daemon set pod is in the `Running` state, when a node stops communicating, the pod keeps running and is assumed to be running by {product-title}. - -* Daemon set pods, by default, are created with `NoExecute` tolerations for the `node.kubernetes.io/unreachable` and `node.kubernetes.io/not-ready` taints with no `tolerationSeconds` value. These default values ensure that daemon set pods are never evicted if the control plane cannot reach a node. For example: -+ -.Tolerations added to daemon set pods by default -[source,yaml] ----- - tolerations: - - key: node.kubernetes.io/not-ready - operator: Exists - effect: NoExecute - - key: node.kubernetes.io/unreachable - operator: Exists - effect: NoExecute - - key: node.kubernetes.io/disk-pressure - operator: Exists - effect: NoSchedule - - key: node.kubernetes.io/memory-pressure - operator: Exists - effect: NoSchedule - - key: node.kubernetes.io/pid-pressure - operator: Exists - effect: NoSchedule - - key: node.kubernetes.io/unschedulable - operator: Exists - effect: NoSchedule ----- - -* Daemon sets can use labels to ensure that a workload runs on a matching worker node. - -* You can use an {product-title} service endpoint to load balance daemon set pods. - -[NOTE] -==== -Daemon sets do not schedule pods after a reboot of the node if {product-title} cannot reach the node. -==== --- - -[id="nodes-edge-remote-workers-strategies-static_{context}"] -Static pods:: -If you want pods restart if a node reboots, after a power loss for example, consider link:https://kubernetes.io/docs/tasks/configure-pod-container/static-pod/[static pods]. The kubelet on a node automatically restarts static pods as node restarts. - -[NOTE] -==== -Static pods cannot use secrets and config maps. -==== - -[id="nodes-edge-remote-workers-strategies-zones_{context}"] -Kubernetes zones:: -link:https://kubernetes.io/docs/setup/best-practices/multiple-zones/[Kubernetes zones] can slow down the rate or, in some cases, completely stop pod evictions. - -When the control plane cannot reach a node, the node controller, by default, applies `node.kubernetes.io/unreachable` taints and evicts pods at a rate of 0.1 nodes per second. However, in a cluster that uses Kubernetes zones, pod eviction behavior is altered. - -If a zone is fully disrupted, where all nodes in the zone have a `Ready` condition that is `False` or `Unknown`, the control plane does not apply the `node.kubernetes.io/unreachable` taint to the nodes in that zone. - -For partially disrupted zones, where more than 55% of the nodes have a `False` or `Unknown` condition, the pod eviction rate is reduced to 0.01 nodes per second. Nodes in smaller clusters, with fewer than 50 nodes, are not tainted. Your cluster must have more than three zones for these behavior to take effect. - -You assign a node to a specific zone by applying the `topology.kubernetes.io/region` label in the node specification. - -.Sample node labels for Kubernetes zones -[source,yaml] ----- -kind: Node -apiVersion: v1 -metadata: - labels: - topology.kubernetes.io/region=east ----- - -[id="nodes-edge-remote-workers-strategies-kubeconfig_{context}"] -`KubeletConfig` objects:: --- -You can adjust the amount of time that the kubelet checks the state of each node. - -To set the interval that affects the timing of when the on-premise node controller marks nodes with the `Unhealthy` or `Unreachable` condition, create a `KubeletConfig` object that contains the `node-status-update-frequency` and `node-status-report-frequency` parameters. - -The kubelet on each node determines the node status as defined by the `node-status-update-frequency` setting and reports that status to the cluster based on the `node-status-report-frequency` setting. By default, the kubelet determines the pod status every 10 seconds and reports the status every minute. However, if the node state changes, the kubelet reports the change to the cluster immediately. {product-title} uses the `node-status-report-frequency` setting only when the Node Lease feature gate is enabled, which is the default state in {product-title} clusters. If the Node Lease feature gate is disabled, the node reports its status based on the `node-status-update-frequency` setting. - -.Example kubelet config -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: disable-cpu-units -spec: - machineConfigPoolSelector: - matchLabels: - machineconfiguration.openshift.io/role: worker <1> - kubeletConfig: - node-status-update-frequency: <2> - - "10s" - node-status-report-frequency: <3> - - "1m" ----- -<1> Specify the type of node type to which this `KubeletConfig` object applies using the label from the `MachineConfig` object. -<2> Specify the frequency that the kubelet checks the status of a node associated with this `MachineConfig` object. The default value is `10s`. If you change this default, the `node-status-report-frequency` value is changed to the same value. -<3> Specify the frequency that the kubelet reports the status of a node associated with this `MachineConfig` object. The default value is `1m`. - -This parameter works with the `node-monitor-grace-period` and the `pod-eviction-timeout` parameters, which are not configurable. - -* The `node-monitor-grace-period` parameter specifies how long the {product-title} waits after a node associated with a `MachineConfig` object is marked `Unhealthy` if the controller manager does not receive the node heartbeat. Workloads on the node continue to run after this time. If the remote worker node rejoins the cluster after the `node-monitor-grace-period` expires, pods continue to run. New pods can be scheduled to that node. The `node-monitor-grace-period` interval is `40s`. The `node-status-update-frequency` value must be lower than the `node-monitor-grace-period` value. - -* The `pod-eviction-timeout` parameter specifies the amount of time {product-title} waits after marking a node that is associated with a `MachineConfig` object as `Unreachable` to start marking pods for eviction. Evicted pods are rescheduled on other nodes. If the remote worker node rejoins the cluster after `pod-eviction-timeout` expires, the pods running on the remote worker node are terminated because the node controller has evicted the pods on-premise. Pods can then be rescheduled to that node. The `pod-eviction-timeout` period is `5m0s`. --- - -[id="nodes-edge-remote-workers-strategies-tolerations_{context}"] -Tolerations:: -You can use pod tolerations to mitigate the effects if the on-premise node controller adds a `node.kubernetes.io/unreachable` taint with a `NoExecute` effect to a node it cannot reach. - -A taint with the `NoExecute` effect affects pods that are running on the node in the following ways: - -* Pods that do not tolerate the taint are queued for eviction. -* Pods that tolerate the taint without specifying a `tolerationSeconds` value in their toleration specification remain bound forever. -* Pods that tolerate the taint with a specified `tolerationSeconds` value remain bound for the specified amount of time. After the time elapses, the pods are queued for eviction. - -You can delay or avoid pod eviction by configuring pods tolerations with the `NoExecute` effect for the `node.kubernetes.io/unreachable` and `node.kubernetes.io/not-ready` taints. - -.Example toleration in a pod spec -[source,yaml] ----- -... -tolerations: -- key: "node.kubernetes.io/unreachable" - operator: "Exists" - effect: "NoExecute" <1> - tolerationSeconds: 0 -- key: "node.kubernetes.io/not-ready" - operator: "Exists" - effect: "NoExecute" <2> - tolerationSeconds: 0 -... ----- -<1> The `NoExecute` effect with `tolerationSeconds`: 0 allows pods to remain if the control plane cannot reach the node. -<2> The `NoExecute` effect with `tolerationSeconds`: 0 allows pods to remain if the control plane marks the node as `Unhealthy`. - -{product-title} uses the `tolerationSeconds` value after the `pod-eviction-timeout` value elapses. - -Other types of {product-title} objects:: -You can use replica sets, deployments, and replication controllers. The scheduler can reschedule these pods onto other nodes after the node is disconnected for five minutes. Rescheduling onto other nodes can be beneficial for some workloads, such as REST APIs, where an administrator can guarantee a specific number of pods are running and accessible. - -[NOTE] -==== -When working with remote worker nodes, rescheduling pods on different nodes might not be acceptable if remote worker nodes are intended to be reserved for specific functions. -==== - -[id="nodes-edge-remote-workers-strategies-statefulset_{context}"] -https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/[stateful sets] do not get restarted when there is an outage. The pods remain in the `terminating` state until the control plane can acknowledge that the pods are terminated. - -To avoid scheduling a to a node that does not have access to the same type of persistent storage, {product-title} cannot migrate pods that require persistent volumes to other zones in the case of network separation. - - diff --git a/modules/nodes-nodes-audit-config-about.adoc b/modules/nodes-nodes-audit-config-about.adoc deleted file mode 100644 index 137fdac8ab83..000000000000 --- a/modules/nodes-nodes-audit-config-about.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * security/audit-log-policy-config.adoc - -[id="about-audit-log-profiles_{context}"] -= About audit log policy profiles - -Audit log profiles define how to log requests that come to the OpenShift API server, the Kubernetes API server, and the OAuth API server. - -{product-title} provides the following predefined audit policy profiles: - -[cols="1,2",options="header"] -|=== -|Profile -|Description - -|`Default` -|Logs only metadata for read and write requests; does not log request bodies. This is the default policy. - -|`WriteRequestBodies` -|In addition to logging metadata for all requests, logs request bodies for every write request to the API servers (`create`, `update`, `patch`). This profile has more resource overhead than the `Default` profile. ^[1]^ - -|`AllRequestBodies` -|In addition to logging metadata for all requests, logs request bodies for every read and write request to the API servers (`get`, `list`, `create`, `update`, `patch`). This profile has the most resource overhead. ^[1]^ -|=== -[.small] --- -1. Sensitive resources, such as `Secret`, `Route`, and `OAuthClient` objects, are never logged past the metadata level. OAuth tokens are not logged at all if your cluster was upgraded from {product-title} 4.5, because their object names might contain secret information. --- - -By default, {product-title} uses the `Default` audit log profile. You can use another audit policy profile that also logs request bodies, but be aware of the increased resource usage (CPU, memory, and I/O). diff --git a/modules/nodes-nodes-audit-log-basic-viewing.adoc b/modules/nodes-nodes-audit-log-basic-viewing.adoc deleted file mode 100644 index 569f6ebc6ca2..000000000000 --- a/modules/nodes-nodes-audit-log-basic-viewing.adoc +++ /dev/null @@ -1,132 +0,0 @@ -// Module included in the following assemblies: -// -// * security/audit-log-view.adoc - -[id="nodes-nodes-audit-log-basic-viewing_{context}"] -= Viewing the audit logs - -You can view the logs for the OpenShift API server, Kubernetes API server, and OpenShift OAuth API server for each master node. - -.Procedure - -To view the audit logs: - -* View the OpenShift API server logs: - -.. List the OpenShift API server logs that are available for each master node: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master --path=openshift-apiserver/ ----- -+ -.Example output -[source,terminal] ----- -ci-ln-m0wpfjb-f76d1-vnb5x-master-0 audit-2021-03-09T00-12-19.834.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-0 audit.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-1 audit-2021-03-09T00-11-49.835.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-1 audit.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-2 audit-2021-03-09T00-13-00.128.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-2 audit.log ----- - -.. View a specific OpenShift API server log by providing the node name and the log name: -+ -[source,terminal] ----- -$ oc adm node-logs <node_name> --path=openshift-apiserver/<log_name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm node-logs ci-ln-m0wpfjb-f76d1-vnb5x-master-0 --path=openshift-apiserver/audit-2021-03-09T00-12-19.834.log ----- -+ -.Example output -[source,terminal] ----- -{"kind":"Event","apiVersion":"audit.k8s.io/v1","level":"Metadata","auditID":"381acf6d-5f30-4c7d-8175-c9c317ae5893","stage":"ResponseComplete","requestURI":"/metrics","verb":"get","user":{"username":"system:serviceaccount:openshift-monitoring:prometheus-k8s","uid":"825b60a0-3976-4861-a342-3b2b561e8f82","groups":["system:serviceaccounts","system:serviceaccounts:openshift-monitoring","system:authenticated"]},"sourceIPs":["10.129.2.6"],"userAgent":"Prometheus/2.23.0","responseStatus":{"metadata":{},"code":200},"requestReceivedTimestamp":"2021-03-08T18:02:04.086545Z","stageTimestamp":"2021-03-08T18:02:04.107102Z","annotations":{"authorization.k8s.io/decision":"allow","authorization.k8s.io/reason":"RBAC: allowed by ClusterRoleBinding \"prometheus-k8s\" of ClusterRole \"prometheus-k8s\" to ServiceAccount \"prometheus-k8s/openshift-monitoring\""}} ----- - -* View the Kubernetes API server logs: - -.. List the Kubernetes API server logs that are available for each master node: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master --path=kube-apiserver/ ----- -+ -.Example output -[source,terminal] ----- -ci-ln-m0wpfjb-f76d1-vnb5x-master-0 audit-2021-03-09T14-07-27.129.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-0 audit.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-1 audit-2021-03-09T19-24-22.620.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-1 audit.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-2 audit-2021-03-09T18-37-07.511.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-2 audit.log ----- - -.. View a specific Kubernetes API server log by providing the node name and the log name: -+ -[source,terminal] ----- -$ oc adm node-logs <node_name> --path=kube-apiserver/<log_name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm node-logs ci-ln-m0wpfjb-f76d1-vnb5x-master-0 --path=kube-apiserver/audit-2021-03-09T14-07-27.129.log ----- -+ -.Example output -[source,terminal] ----- -{"kind":"Event","apiVersion":"audit.k8s.io/v1","level":"Metadata","auditID":"cfce8a0b-b5f5-4365-8c9f-79c1227d10f9","stage":"ResponseComplete","requestURI":"/api/v1/namespaces/openshift-kube-scheduler/serviceaccounts/openshift-kube-scheduler-sa","verb":"get","user":{"username":"system:serviceaccount:openshift-kube-scheduler-operator:openshift-kube-scheduler-operator","uid":"2574b041-f3c8-44e6-a057-baef7aa81516","groups":["system:serviceaccounts","system:serviceaccounts:openshift-kube-scheduler-operator","system:authenticated"]},"sourceIPs":["10.128.0.8"],"userAgent":"cluster-kube-scheduler-operator/v0.0.0 (linux/amd64) kubernetes/$Format","objectRef":{"resource":"serviceaccounts","namespace":"openshift-kube-scheduler","name":"openshift-kube-scheduler-sa","apiVersion":"v1"},"responseStatus":{"metadata":{},"code":200},"requestReceivedTimestamp":"2021-03-08T18:06:42.512619Z","stageTimestamp":"2021-03-08T18:06:42.516145Z","annotations":{"authentication.k8s.io/legacy-token":"system:serviceaccount:openshift-kube-scheduler-operator:openshift-kube-scheduler-operator","authorization.k8s.io/decision":"allow","authorization.k8s.io/reason":"RBAC: allowed by ClusterRoleBinding \"system:openshift:operator:cluster-kube-scheduler-operator\" of ClusterRole \"cluster-admin\" to ServiceAccount \"openshift-kube-scheduler-operator/openshift-kube-scheduler-operator\""}} ----- - -* View the OpenShift OAuth API server logs: - -.. List the OpenShift OAuth API server logs that are available for each master node: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master --path=oauth-apiserver/ ----- -+ -.Example output -[source,terminal] ----- -ci-ln-m0wpfjb-f76d1-vnb5x-master-0 audit-2021-03-09T13-06-26.128.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-0 audit.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-1 audit-2021-03-09T18-23-21.619.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-1 audit.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-2 audit-2021-03-09T17-36-06.510.log -ci-ln-m0wpfjb-f76d1-vnb5x-master-2 audit.log ----- - -.. View a specific OpenShift OAuth API server log by providing the node name and the log name: -+ -[source,terminal] ----- -$ oc adm node-logs <node_name> --path=oauth-apiserver/<log_name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm node-logs ci-ln-m0wpfjb-f76d1-vnb5x-master-0 --path=oauth-apiserver/audit-2021-03-09T13-06-26.128.log ----- -+ -.Example output -[source,terminal] ----- -{"kind":"Event","apiVersion":"audit.k8s.io/v1","level":"Metadata","auditID":"dd4c44e2-3ea1-4830-9ab7-c91a5f1388d6","stage":"ResponseComplete","requestURI":"/apis/user.openshift.io/v1/users/~","verb":"get","user":{"username":"system:serviceaccount:openshift-monitoring:prometheus-k8s","groups":["system:serviceaccounts","system:serviceaccounts:openshift-monitoring","system:authenticated"]},"sourceIPs":["10.0.32.4","10.128.0.1"],"userAgent":"dockerregistry/v0.0.0 (linux/amd64) kubernetes/$Format","objectRef":{"resource":"users","name":"~","apiGroup":"user.openshift.io","apiVersion":"v1"},"responseStatus":{"metadata":{},"code":200},"requestReceivedTimestamp":"2021-03-08T17:47:43.653187Z","stageTimestamp":"2021-03-08T17:47:43.660187Z","annotations":{"authorization.k8s.io/decision":"allow","authorization.k8s.io/reason":"RBAC: allowed by ClusterRoleBinding \"basic-users\" of ClusterRole \"basic-user\" to Group \"system:authenticated\""}} ----- diff --git a/modules/nodes-nodes-audit-log-basic.adoc b/modules/nodes-nodes-audit-log-basic.adoc deleted file mode 100644 index 5e42a81065ad..000000000000 --- a/modules/nodes-nodes-audit-log-basic.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * security/audit-log-view.adoc - -[id="nodes-pods-audit-log-basic_{context}"] -= About the API audit log - -Audit works at the API server level, logging all requests coming to the server. Each audit log contains the following information: - -.Audit log fields -[cols="1,2",options="header"] -|=== -|Field |Description -|`level` | The audit level at which the event was generated. -|`auditID` |A unique audit ID, generated for each request. -|`stage` |The stage of the request handling when this event instance was generated. -|`requestURI` |The request URI as sent by the client to a server. -|`verb` |The Kubernetes verb associated with the request. For non-resource requests, this is the lowercase HTTP method. -|`user` |The authenticated user information. -|`impersonatedUser` |Optional. The impersonated user information, if the request is impersonating another user. -|`sourceIPs` |Optional. The source IPs, from where the request originated and any intermediate proxies. -|`userAgent` |Optional. The user agent string reported by the client. Note that the user agent is provided by the client, and must not be trusted. -|`objectRef` |Optional. The object reference this request is targeted at. This does not apply for `List`-type requests, or non-resource requests. -|`responseStatus` |Optional. The response status, populated even when the `ResponseObject` is not a `Status` type. For successful responses, this will only include the code. For non-status type error responses, this will be auto-populated with the error message. -|`requestObject` |Optional. The API object from the request, in JSON format. The `RequestObject` is recorded as is in the request (possibly re-encoded as JSON), prior to version conversion, defaulting, admission or merging. It is an external versioned object type, and might not be a valid object on its own. This is omitted for non-resource requests and is only logged at request level and higher. -|`responseObject` |Optional. The API object returned in the response, in JSON format. The `ResponseObject` is recorded after conversion to the external type, and serialized as JSON. This is omitted for non-resource requests and is only logged at response level. -|`requestReceivedTimestamp` |The time that the request reached the API server. -|`stageTimestamp` |The time that the request reached the current audit stage. -|`annotations` |Optional. An unstructured key value map stored with an audit event that may be set by plug-ins invoked in the request serving chain, including authentication, authorization and admission plug-ins. Note that these annotations are for the audit event, and do not correspond to the `metadata.annotations` of the submitted object. Keys should uniquely identify the informing component to avoid name collisions, for example `podsecuritypolicy.admission.k8s.io/policy`. Values should be short. Annotations are included in the metadata level. -|=== - -Example output for the Kubernetes API server: - ----- -{"kind":"Event","apiVersion":"audit.k8s.io/v1","level":"Metadata","auditID":"ad209ce1-fec7-4130-8192-c4cc63f1d8cd","stage":"ResponseComplete","requestURI":"/api/v1/namespaces/openshift-kube-controller-manager/configmaps/cert-recovery-controller-lock?timeout=35s","verb":"update","user":{"username":"system:serviceaccount:openshift-kube-controller-manager:localhost-recovery-client","uid":"dd4997e3-d565-4e37-80f8-7fc122ccd785","groups":["system:serviceaccounts","system:serviceaccounts:openshift-kube-controller-manager","system:authenticated"]},"sourceIPs":["::1"],"userAgent":"cluster-kube-controller-manager-operator/v0.0.0 (linux/amd64) kubernetes/$Format","objectRef":{"resource":"configmaps","namespace":"openshift-kube-controller-manager","name":"cert-recovery-controller-lock","uid":"5c57190b-6993-425d-8101-8337e48c7548","apiVersion":"v1","resourceVersion":"574307"},"responseStatus":{"metadata":{},"code":200},"requestReceivedTimestamp":"2020-04-02T08:27:20.200962Z","stageTimestamp":"2020-04-02T08:27:20.206710Z","annotations":{"authorization.k8s.io/decision":"allow","authorization.k8s.io/reason":"RBAC: allowed by ClusterRoleBinding \"system:openshift:operator:kube-controller-manager-recovery\" of ClusterRole \"cluster-admin\" to ServiceAccount \"localhost-recovery-client/openshift-kube-controller-manager\""}} ----- diff --git a/modules/nodes-nodes-audit-policy.adoc b/modules/nodes-nodes-audit-policy.adoc deleted file mode 100644 index 1f3c7a810321..000000000000 --- a/modules/nodes-nodes-audit-policy.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * security/audit-log-policy-config.adoc - -[id="configuring-audit-policy_{context}"] -= Configuring the audit log policy - -You can configure the audit log policy to use when logging requests that come to the API servers. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Edit the `APIServer` resource: -+ -[source,terminal] ----- -$ oc edit apiserver cluster ----- - -. Update the `spec.audit.profile` field: -+ -[source,yaml] ----- - apiVersion: config.openshift.io/v1 - kind: APIServer - metadata: - ... - spec: - audit: - profile: WriteRequestBodies <1> ----- -<1> Set to `Default`, `WriteRequestBodies`, or `AllRequestBodies`. The default profile is `Default`. - -. Save the file to apply the changes. - -. Verify that a new revision of the Kubernetes API server pods has rolled out. This will take several minutes. -+ -[source,terminal] ----- -$ oc get kubeapiserver -o=jsonpath='{range .items[0].status.conditions[?(@.type=="NodeInstallerProgressing")]}{.reason}{"\n"}{.message}{"\n"}' ----- -+ -Review the `NodeInstallerProgressing` status condition for the Kubernetes API server to verify that all nodes are at the latest revision. The output shows `AllNodesAtLatestRevision` upon successful update: -+ -[source,terminal] ----- -AllNodesAtLatestRevision -3 nodes are at revision 12 <1> ----- -<1> In this example, the latest revision number is `12`. -+ -If the output shows a message similar to one of the following, this means that the update is still in progress. Wait a few minutes and try again. - -** `3 nodes are at revision 11; 0 nodes have achieved new revision 12` -** `2 nodes are at revision 11; 1 nodes are at revision 12` diff --git a/modules/nodes-nodes-garbage-collection-configuring.adoc b/modules/nodes-nodes-garbage-collection-configuring.adoc deleted file mode 100644 index b913db473d39..000000000000 --- a/modules/nodes-nodes-garbage-collection-configuring.adoc +++ /dev/null @@ -1,142 +0,0 @@ - -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-garbage-collection.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-nodes-garbage-collection-configuring_{context}"] -= Configuring garbage collection for containers and images - -As an administrator, you can configure how {product-title} performs garbage collection by creating a `kubeletConfig` object for each machine config pool. - -[NOTE] -==== -{product-title} supports only one `kubeletConfig` object for each machine config pool. -==== - -You can configure any combination of the following: - -* soft eviction for containers -* hard eviction for containers -* eviction for images - -For soft container eviction you can also configure a grace period before eviction. - -.Prerequisites - -. Obtain the label associated with the static `MachineConfigPool` CRD for the type of node you want to configure. -Perform one of the following steps: - -.. View the machine config pool: -+ -[source,terminal] ----- -$ oc describe machineconfigpool <name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe machineconfigpool worker ----- -+ -.Example output -[source,yaml] ----- -Name: worker -Namespace: -Labels: custom-kubelet=small-pods <1> ----- -<1> If a label has been added it appears under `Labels`. - -.. If the label is not present, add a key/value pair: -+ -[source,terminal] ----- -$ oc label machineconfigpool worker custom-kubelet=small-pods ----- - -.Procedure - -. Create a custom resource (CR) for your configuration change. -+ -.Sample configuration for a container garbage collection CR: -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: worker-kubeconfig <1> -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: small-pods <2> - kubeletConfig: - evictionSoft: <3> - memory.available: "500Mi" <4> - nodefs.available: "10%" - nodefs.inodesFree: "5%" - imagefs.available: "15%" - imagefs.inodesFree: "10%" - evictionSoftGracePeriod: <5> - memory.available: "1m30s" - nodefs.available: "1m30s" - nodefs.inodesFree: "1m30s" - imagefs.available: "1m30s" - imagefs.inodesFree: "1m30s" - evictionHard: - memory.available: "200Mi" - nodefs.available: "5%" - nodefs.inodesFree: "4%" - imagefs.available: "10%" - imagefs.inodesFree: "5%" - evictionPressureTransitionPeriod: 0s <6> - imageMinimumGCAge: 5m <7> - imageGCHighThresholdPercent: 80 <8> - imageGCLowThresholdPercent: 75 <9> ----- -<1> Name for the object. -<2> Selector label. -<3> Type of eviction: `EvictionSoft` and `EvictionHard`. -<4> Eviction thresholds based on a specific eviction trigger signal. -<5> Grace periods for the soft eviction. This parameter does not apply to `eviction-hard`. -<6> The duration to wait before transitioning out of an eviction pressure condition -<7> The minimum age for an unused image before the image is removed by garbage collection. -<8> The percent of disk usage (expressed as an integer) which triggers image garbage collection. -<9> The percent of disk usage (expressed as an integer) to which image garbage collection attempts to free. - -. Create the object: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f gc-container.yaml ----- -+ -.Example output -[source,terminal] ----- -kubeletconfig.machineconfiguration.openshift.io/gc-container created ----- - -. Verify that garbage collection is active. The Machine Config Pool you specified in the custom resource appears with `UPDATING` as 'true` until the change is fully implemented: -+ -[source,terminal] ----- -$ oc get machineconfigpool ----- -+ -.Example output -[source,terminal] ----- -NAME CONFIG UPDATED UPDATING -master rendered-master-546383f80705bd5aeaba93 True False -worker rendered-worker-b4c51bb33ccaae6fc4a6a5 False True ----- diff --git a/modules/nodes-nodes-garbage-collection-containers.adoc b/modules/nodes-nodes-garbage-collection-containers.adoc deleted file mode 100644 index e93c07376e5f..000000000000 --- a/modules/nodes-nodes-garbage-collection-containers.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-garbage-collection.adoc -// * post_installation_configuration/node-tasks.adoc - - -[id="nodes-nodes-garbage-collection-containers_{context}"] -= Understanding how terminated containers are removed though garbage collection - -Container garbage collection can be performed using eviction thresholds. - -When eviction thresholds are set for garbage collection, the node tries to keep any container for any pod accessible from the API. If the pod has been deleted, the containers will be as well. Containers are preserved as long the pod is not deleted and the eviction threshold is not reached. If the node is under disk pressure, it will remove containers and their logs will no longer be accessible using `oc logs`. - -* *eviction-soft* - A soft eviction threshold pairs an eviction threshold with a required administrator-specified grace period. - -* *eviction-hard* - A hard eviction threshold has no grace period, and if observed, {product-title} takes immediate action. - -If a node is oscillating above and below a soft eviction threshold, but not exceeding its associated grace period, the corresponding node would constantly oscillate between `true` and `false`. As a consequence, the scheduler could make poor scheduling decisions. - -To protect against this oscillation, use the `eviction-pressure-transition-period` flag to control how long {product-title} must wait before transitioning out of a pressure condition. {product-title} will not set an eviction threshold as being met for the specified pressure condition for the period specified before toggling the condition back to false. diff --git a/modules/nodes-nodes-garbage-collection-images.adoc b/modules/nodes-nodes-garbage-collection-images.adoc deleted file mode 100644 index b5e3f400f99f..000000000000 --- a/modules/nodes-nodes-garbage-collection-images.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-garbage-collection.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-nodes-garbage-collection-images_{context}"] -= Understanding how images are removed though garbage collection - -Image garbage collection relies on disk usage as reported by *cAdvisor* on the -node to decide which images to remove from the node. - -The policy for image garbage collection is based on two conditions: - -* The percent of disk usage (expressed as an integer) which triggers image -garbage collection. The default is *85*. - -* The percent of disk usage (expressed as an integer) to which image garbage -collection attempts to free. Default is *80*. - -For image garbage collection, you can modify any of the following variables using -a custom resource. - -.Variables for configuring image garbage collection - -[options="header",cols="1,3"] -|=== - -|Setting |Description - -|`imageMinimumGCAge` -|The minimum age for an unused image before the image is removed by garbage collection. The default is *2m*. - -|`imageGCHighThresholdPercent` -|The percent of disk usage, expressed as an integer, which triggers image -garbage collection. The default is *85*. - -|`imageGCLowThresholdPercent` -|The percent of disk usage, expressed as an integer, to which image garbage -collection attempts to free. The default is *80*. -|=== - -Two lists of images are retrieved in each garbage collector run: - -1. A list of images currently running in at least one pod. -2. A list of images available on a host. - -As new containers are run, new images appear. All images are marked with a time -stamp. If the image is running (the first list above) or is newly detected (the -second list above), it is marked with the current time. The remaining images are -already marked from the previous spins. All images are then sorted by the time -stamp. - -Once the collection starts, the oldest images get deleted first until the -stopping criterion is met. diff --git a/modules/nodes-nodes-jobs-about.adoc b/modules/nodes-nodes-jobs-about.adoc deleted file mode 100644 index 2fc2795364f8..000000000000 --- a/modules/nodes-nodes-jobs-about.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-jobs.adoc - -[id="nodes-nodes-jobs-about_{context}"] -= Understanding jobs and cron jobs - -A job tracks the overall progress of a task and updates its status with information -about active, succeeded, and failed pods. Deleting a job cleans up any pods it created. -Jobs are part of the Kubernetes API, which can be managed -with `oc` commands like other object types. - -There are two possible resource types that allow creating run-once objects in {product-title}: - -Job:: -A regular job is a run-once object that creates a task and ensures the job finishes. - -There are three main types of task suitable to run as a job: - -* Non-parallel jobs: -** A job that starts only one pod, unless the pod fails. -** The job is complete as soon as its pod terminates successfully. - -* Parallel jobs with a fixed completion count: -** a job that starts multiple pods. -** The job represents the overall task and is complete when there is one successful pod for each value in the range `1` to the `completions` value. - -* Parallel jobs with a work queue: -** A job with multiple parallel worker processes in a given pod. -** {product-title} coordinates pods to determine what each should work on or use an external queue service. -** Each pod is independently capable of determining whether or not all peer pods are complete and that the entire job is done. -** When any pod from the job terminates with success, no new pods are created. -** When at least one pod has terminated with success and all pods are terminated, the job is successfully completed. -** When any pod has exited with success, no other pod should be doing any work for this task or writing any output. Pods should all be in the process of exiting. - -For more information about how to make use of the different types of job, see link:https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/#job-patterns[Job Patterns] in the Kubernetes documentation. - -Cron job:: - -A job can be scheduled to run multiple times, using a cron job. - -A _cron job_ builds on a regular job by allowing you to specify -how the job should be run. Cron jobs are part of the -link:http://kubernetes.io/docs/user-guide/cron-jobs[Kubernetes] API, which -can be managed with `oc` commands like other object types. - -Cron jobs are useful for creating periodic and recurring tasks, like running backups or sending emails. -Cron jobs can also schedule individual tasks for a specific time, such as if you want to schedule a job for a low activity period. A cron job creates a `Job` object based on the timezone configured on the control plane node that runs the cronjob controller. - -[WARNING] -==== -A cron job creates a `Job` object approximately once per execution time of its -schedule, but there are circumstances in which it fails to create a job or -two jobs might be created. Therefore, jobs must be idempotent and you must -configure history limits. -==== - -[id="jobs-create_{context}"] -= Understanding how to create jobs - -Both resource types require a job configuration that consists of the following key parts: - -- A pod template, which describes the pod that {product-title} creates. -- The `parallelism` parameter, which specifies how many pods running in parallel at any point in time should execute a job. -** For non-parallel jobs, leave unset. When unset, defaults to `1`. -- The `completions` parameter, specifying how many successful pod completions are needed to finish a job. -** For non-parallel jobs, leave unset. When unset, defaults to `1`. -** For parallel jobs with a fixed completion count, specify a value. -** For parallel jobs with a work queue, leave unset. When unset defaults to the `parallelism` value. - -[id="jobs-set-max_{context}"] -== Understanding how to set a maximum duration for jobs - -When defining a job, you can define its maximum duration by setting -the `activeDeadlineSeconds` field. It is specified in seconds and is not -set by default. When not set, there is no maximum duration enforced. - -The maximum duration is counted from the time when a first pod gets scheduled in -the system, and defines how long a job can be active. It tracks overall time of -an execution. After reaching the specified timeout, the job is terminated by {product-title}. - -[id="jobs-set-backoff_{context}"] -== Understanding how to set a job back off policy for pod failure - -A job can be considered failed, after a set amount of retries due to a -logical error in configuration or other similar reasons. Failed pods associated with the job are recreated by the controller with -an exponential back off delay (`10s`, `20s`, `40s` …) capped at six minutes. The -limit is reset if no new failed pods appear between controller checks. - -Use the `spec.backoffLimit` parameter to set the number of retries for a job. - -[id="jobs-artifacts_{context}"] -== Understanding how to configure a cron job to remove artifacts - -Cron jobs can leave behind artifact resources such as jobs or pods. As a user it is important -to configure history limits so that old jobs and their pods are properly cleaned. There are two fields within cron job's spec responsible for that: - -* `.spec.successfulJobsHistoryLimit`. The number of successful finished jobs to retain (defaults to 3). - -* `.spec.failedJobsHistoryLimit`. The number of failed finished jobs to retain (defaults to 1). - -[TIP] -==== -* Delete cron jobs that you no longer need: -+ -[source,terminal] ----- -$ oc delete cronjob/<cron_job_name> ----- -+ -Doing this prevents them from generating unnecessary artifacts. - -* You can suspend further executions by setting the `spec.suspend` to true. All subsequent executions are suspended until you reset to `false`. -==== - -[id="jobs-limits_{context}"] -= Known limitations - -The job specification restart policy only applies to the _pods_, and not the _job controller_. However, the job controller is hard-coded to keep retrying jobs to completion. - -As such, `restartPolicy: Never` or `--restart=Never` results in the same behavior as `restartPolicy: OnFailure` or `--restart=OnFailure`. That is, when a job fails it is restarted automatically until it succeeds (or is manually discarded). The policy only sets which subsystem performs the restart. - -With the `Never` policy, the _job controller_ performs the restart. With each attempt, the job controller increments the number of failures in the job status and create new pods. This means that with each failed attempt, the number of pods increases. - -With the `OnFailure` policy, _kubelet_ performs the restart. Each attempt does not increment the number of failures in the job status. In addition, kubelet will retry failed jobs starting pods on the same nodes. diff --git a/modules/nodes-nodes-jobs-creating-cron.adoc b/modules/nodes-nodes-jobs-creating-cron.adoc deleted file mode 100644 index a217a8e66b67..000000000000 --- a/modules/nodes-nodes-jobs-creating-cron.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-jobs.adoc - -[id="nodes-nodes-jobs-creating-cron_{context}"] -= Creating cron jobs - -You create a cron job in {product-title} by creating a job object. - -.Procedure - -To create a cron job: - -. Create a YAML file similar to the following: -+ -[source,yaml] ----- -apiVersion: batch/v1beta1 -kind: CronJob -metadata: - name: pi -spec: - schedule: "*/1 * * * *" <1> - concurrencyPolicy: "Replace" <2> - startingDeadlineSeconds: 200 <3> - suspend: true <4> - successfulJobsHistoryLimit: 3 <5> - failedJobsHistoryLimit: 1 <6> - jobTemplate: <7> - spec: - template: - metadata: - labels: <8> - parent: "cronjobpi" - spec: - containers: - - name: pi - image: perl - command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"] - restartPolicy: OnFailure <9> ----- -+ -<1> Schedule for the job specified in link:https://en.wikipedia.org/wiki/Cron[cron format]. In this example, the job will run every minute. -<2> An optional concurrency policy, specifying how to treat concurrent jobs within a cron job. Only one of the following concurrent policies may be specified. If not specified, this defaults to allowing concurrent executions. -* `Allow` allows cron jobs to run concurrently. -* `Forbid` forbids concurrent runs, skipping the next run if the previous has not -finished yet. -* `Replace` cancels the currently running job and replaces -it with a new one. -<3> An optional deadline (in seconds) for starting the job if it misses its -scheduled time for any reason. Missed jobs executions will be counted as failed -ones. If not specified, there is no deadline. -<4> An optional flag allowing the suspension of a cron job. If set to `true`, -all subsequent executions will be suspended. -<5> The number of successful finished jobs to retain (defaults to 3). -<6> The number of failed finished jobs to retain (defaults to 1). -<7> Job template. This is similar to the job example. -<8> Sets a label for jobs spawned by this cron job. -<9> The restart policy of the pod. This does not apply to the job controller. -+ -[NOTE] -==== -The `.spec.successfulJobsHistoryLimit` and `.spec.failedJobsHistoryLimit` fields are optional. -These fields specify how many completed and failed jobs should be kept. By default, they are -set to `3` and `1` respectively. Setting a limit to `0` corresponds to keeping none of the corresponding -kind of jobs after they finish. -==== - -. Create the cron job: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- - -[NOTE] -==== -You can also create and launch a cron job from a single command using `oc create cronjob`. The following command creates and launches a cron job similar to the one specified in the previous example: - -[source,terminal] ----- -$ oc create cronjob pi --image=perl --schedule='*/1 * * * *' -- perl -Mbignum=bpi -wle 'print bpi(2000)' ----- - -With `oc create cronjob`, the `--schedule` option accepts schedules in link:https://en.wikipedia.org/wiki/Cron[cron format]. - -==== diff --git a/modules/nodes-nodes-jobs-creating.adoc b/modules/nodes-nodes-jobs-creating.adoc deleted file mode 100644 index 39def6d2d15e..000000000000 --- a/modules/nodes-nodes-jobs-creating.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-jobs.adoc - -[id="nodes-nodes-jobs-creating_{context}"] -= Creating jobs - -You create a job in {product-title} by creating a job object. - -.Procedure - -To create a job: - -. Create a YAML file similar to the following: -+ -[source,yaml] ----- -apiVersion: batch/v1 -kind: Job -metadata: - name: pi -spec: - parallelism: 1 <1> - completions: 1 <2> - activeDeadlineSeconds: 1800 <3> - backoffLimit: 6 <4> - template: <5> - metadata: - name: pi - spec: - containers: - - name: pi - image: perl - command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"] - restartPolicy: OnFailure <6> ----- -1. Optionally, specify how many pod replicas a job should run in parallel; defaults to `1`. -* For non-parallel jobs, leave unset. When unset, defaults to `1`. -2. Optionally, specify how many successful pod completions are needed to mark a job completed. -* For non-parallel jobs, leave unset. When unset, defaults to `1`. -* For parallel jobs with a fixed completion count, specify the number of completions. -* For parallel jobs with a work queue, leave unset. When unset defaults to the `parallelism` value. -3. Optionally, specify the maximum duration the job can run. -4. Optionally, specify the number of retries for a job. This field defaults to six. -5. Specify the template for the pod the controller creates. -6. Specify the restart policy of the pod: -* `Never`. Do not restart the job. -* `OnFailure`. Restart the job only if it fails. -* `Always`. Always restart the job. -+ -For details on how {product-title} uses restart policy with failed containers, see -the link:https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#example-states[Example States] in the Kubernetes documentation. - -. Create the job: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- - -[NOTE] -==== -You can also create and launch a job from a single command using `oc create job`. The following command creates and launches a job similar to the one specified in the previous example: - -[source,terminal] ----- -$ oc create job pi --image=perl -- perl -Mbignum=bpi -wle 'print bpi(2000)' ----- -==== diff --git a/modules/nodes-nodes-kernel-arguments.adoc b/modules/nodes-nodes-kernel-arguments.adoc deleted file mode 100644 index 9b858ecd4419..000000000000 --- a/modules/nodes-nodes-kernel-arguments.adoc +++ /dev/null @@ -1,172 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-working.adoc -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="nodes-nodes-kernel-arguments_{context}"] -= Adding kernel arguments to nodes - -In some special cases, you might want to add kernel arguments -to a set of nodes in your cluster. -This should only be done with caution and clear understanding -of the implications of the arguments you set. - -[WARNING] -==== -Improper use of kernel arguments can result in your systems becoming unbootable. -==== - -Examples of kernel arguments you could set include: - -* **selinux=0**: Disables Security Enhanced Linux (SELinux). -While not recommended for production, disabling SELinux can -improve performance by 2% - 3%. - -* **nosmt**: Disables symmetric multithreading (SMT) in the kernel. -Multithreading allows multiple logical threads for each CPU. -You could consider `nosmt` in multi-tenant environments to reduce -risks from potential cross-thread attacks. By disabling SMT, you essentially choose security over performance. - -See link:https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt[Kernel.org kernel parameters] -for a list and descriptions of kernel arguments. - -In the following procedure, you create a `MachineConfig` object that identifies: - -* A set of machines to which you want to add the kernel argument. -In this case, machines with a worker role. -* Kernel arguments that are appended to the end of the existing kernel arguments. -* A label that indicates where in the list of machine configs the change is applied. - -.Prerequisites -* Have administrative privilege to a working {product-title} cluster. - -.Procedure - -. List existing `MachineConfig` objects for your {product-title} cluster to determine how to -label your machine config: -+ -[source,terminal] ----- -$ oc get MachineConfig ----- -+ -.Example output -[source,terminal] ----- -NAME GENERATEDBYCONTROLLER IGNITIONVERSION AGE -00-master 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -00-worker 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -01-master-container-runtime 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -01-master-kubelet 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -01-worker-container-runtime 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -01-worker-kubelet 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -99-master-generated-registries 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -99-master-ssh 3.1.0 40m -99-worker-generated-registries 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -99-worker-ssh 3.1.0 40m -rendered-master-23e785de7587df95a4b517e0647e5ab7 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -rendered-worker-5d596d9293ca3ea80c896a1191735bb1 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m ----- - -. Create a `MachineConfig` object file that identifies the kernel argument (for example, `05-worker-kernelarg-selinuxoff.yaml`) -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker<1> - name: 05-worker-kernelarg-selinuxoff<2> -spec: - config: - ignition: - version: 3.1.0 - kernelArguments: - - selinux=0<3> ----- -+ -<1> Applies the new kernel argument only to worker nodes. -<2> Named to identify where it fits among the machine configs (05) and what it does (adds -a kernel argument to turn off SELinux). -<3> Identifies the exact kernel argument as `selinux=0`. - -. Create the new machine config: -+ -[source,terminal] ----- -$ oc create -f 05-worker-kernelarg-selinuxoff.yaml ----- - -. Check the machine configs to see that the new one was added: -+ -[source,terminal] ----- -$ oc get MachineConfig ----- -+ -.Example output -[source,terminal] ----- -NAME GENERATEDBYCONTROLLER IGNITIONVERSION AGE -00-master 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -00-worker 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -01-master-container-runtime 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -01-master-kubelet 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -01-worker-container-runtime 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -01-worker-kubelet 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m - -05-worker-kernelarg-selinuxoff 3.1.0 105s - -99-master-generated-registries 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -99-master-ssh 3.1.0 40m -99-worker-generated-registries 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -99-worker-ssh 3.1.0 40m -rendered-master-23e785de7587df95a4b517e0647e5ab7 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m -rendered-worker-5d596d9293ca3ea80c896a1191735bb1 52dd3ba6a9a527fc3ab42afac8d12b693534c8c9 3.2.0 33m ----- - -. Check the nodes: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-136-161.ec2.internal Ready worker 28m v1.20.0 -ip-10-0-136-243.ec2.internal Ready master 34m v1.20.0 -ip-10-0-141-105.ec2.internal Ready,SchedulingDisabled worker 28m v1.20.0 -ip-10-0-142-249.ec2.internal Ready master 34m v1.20.0 -ip-10-0-153-11.ec2.internal Ready worker 28m v1.20.0 -ip-10-0-153-150.ec2.internal Ready master 34m v1.20.0 ----- -+ -You can see that scheduling on each worker node is disabled as the change is being applied. - -. Check that the kernel argument worked by going to one of the worker nodes and listing -the kernel command line arguments (in `/proc/cmdline` on the host): -+ -[source,terminal] ----- -$ oc debug node/ip-10-0-141-105.ec2.internal ----- -+ -.Example output -[source,terminal] ----- -Starting pod/ip-10-0-141-105ec2internal-debug ... -To use host binaries, run `chroot /host` - -sh-4.2# cat /host/proc/cmdline -BOOT_IMAGE=/ostree/rhcos-... console=tty0 console=ttyS0,115200n8 -rootflags=defaults,prjquota rw root=UUID=fd0... ostree=/ostree/boot.0/rhcos/16... -coreos.oem.id=qemu coreos.oem.id=ec2 ignition.platform.id=ec2 selinux=0 - -sh-4.2# exit ----- -+ -You should see the `selinux=0` argument added to the other kernel arguments. diff --git a/modules/nodes-nodes-managing-about.adoc b/modules/nodes-nodes-managing-about.adoc deleted file mode 100644 index e977ee0104fa..000000000000 --- a/modules/nodes-nodes-managing-about.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-managing.adoc - -[id="nodes-nodes-managing-about_{context}"] -= Modifying nodes - -To make configuration changes to a cluster, or machine pool, you must create a custom resource definition (CRD), or `KubeletConfig` object. {product-title} uses the Machine Config Controller to watch for changes introduced through the CRD to apply the changes to the cluster. - -.Procedure - -. Obtain the label associated with the static CRD, Machine Config Pool, for the type of node you want to configure. -Perform one of the following steps: - -.. Check current labels of the desired machine config pool. -+ -For example: -+ -[source,terminal] ----- -$ oc get machineconfigpool --show-labels ----- -+ -.Example output -[source,terminal] ----- -NAME CONFIG UPDATED UPDATING DEGRADED LABELS -master rendered-master-e05b81f5ca4db1d249a1bf32f9ec24fd True False False operator.machineconfiguration.openshift.io/required-for-upgrade= -worker rendered-worker-f50e78e1bc06d8e82327763145bfcf62 True False False ----- - -.. Add a custom label to the desired machine config pool. -+ -For example: -+ -[source,terminal] ----- -$ oc label machineconfigpool worker custom-kubelet=enabled ----- - - -. Create a `kubeletconfig` custom resource (CR) for your configuration change. -+ -For example: -+ -.Sample configuration for a *custom-config* CR -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: custom-config <1> -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: enabled <2> - kubeletConfig: <3> - podsPerCore: 10 - maxPods: 250 - systemReserved: - cpu: 2000m - memory: 1Gi ----- -<1> Assign a name to CR. -<2> Specify the label to apply the configuration change, this is the label you added to the machine config pool. -<3> Specify the new value(s) you want to change. - -. Create the CR object. -+ -[source,terminal] ----- -$ oc create -f <file-name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f master-kube-config.yaml ----- - -Most https://github.com/kubernetes/kubelet/blob/master/config/v1beta1/types.go[KubeletConfig Options] can be set by the user. The following options are not allowed to be overwritten: - -* CgroupDriver -* ClusterDNS -* ClusterDomain -* RuntimeRequestTimeout -* StaticPodPath diff --git a/modules/nodes-nodes-managing-max-pods-proc.adoc b/modules/nodes-nodes-managing-max-pods-proc.adoc deleted file mode 100644 index 8a510c783754..000000000000 --- a/modules/nodes-nodes-managing-max-pods-proc.adoc +++ /dev/null @@ -1,111 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-managing-max-pods.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-nodes-managing-max-pods-about_{context}"] -= Configuring the maximum number of pods per node - -Two parameters control the maximum number of pods that can be scheduled to a node: `podsPerCore` and `maxPods`. If you use both options, the lower of the two limits the number of pods on a node. - -For example, if `podsPerCore` is set to `10` on a node with 4 processor cores, the maximum number of pods allowed on the node will be 40. - -.Prerequisites - -. Obtain the label associated with the static `MachineConfigPool` CRD for the type of node you want to configure. -Perform one of the following steps: - -.. View the machine config pool: -+ -[source,terminal] ----- -$ oc describe machineconfigpool <name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe machineconfigpool worker ----- -+ -.Example output -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool -metadata: - creationTimestamp: 2019-02-08T14:52:39Z - generation: 1 - labels: - custom-kubelet: small-pods <1> ----- -<1> If a label has been added it appears under `labels`. - -.. If the label is not present, add a key/value pair: -+ -[source,terminal] ----- -$ oc label machineconfigpool worker custom-kubelet=small-pods ----- - -.Procedure - -. Create a custom resource (CR) for your configuration change. -+ -.Sample configuration for a `max-pods` CR -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: set-max-pods <1> -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: small-pods <2> - kubeletConfig: - podsPerCore: 10 <3> - maxPods: 250 <4> ----- -<1> Assign a name to CR. -<2> Specify the label to apply the configuration change. -<3> Specify the number of pods the node can run based on the number of processor cores on the node. -<4> Specify the number of pods the node can run to a fixed value, regardless of the properties of the node. -+ -[NOTE] -==== -Setting `podsPerCore` to `0` disables this limit. -==== -+ -In the above example, the default value for `podsPerCore` is `10` and the default value for `maxPods` is `250`. This means that unless the node has 25 cores or more, by default, `podsPerCore` will be the limiting factor. - -. List the `MachineConfigPool` CRDs to see if the change is applied. The `UPDATING` column reports `True` if the change is picked up by the Machine Config Controller: -+ -[source,terminal] ----- -$ oc get machineconfigpools ----- -+ -.Example output -[source,terminal] ----- -NAME CONFIG UPDATED UPDATING DEGRADED -master master-9cc2c72f205e103bb534 False False False -worker worker-8cecd1236b33ee3f8a5e False True False ----- -+ -Once the change is complete, the `UPDATED` column reports `True`. -+ -[source,terminal] ----- -$ oc get machineconfigpools ----- -+ -.Example output -[source,terminal] ----- -NAME CONFIG UPDATED UPDATING DEGRADED -master master-9cc2c72f205e103bb534 False True False -worker worker-8cecd1236b33ee3f8a5e True False False ----- diff --git a/modules/nodes-nodes-rebooting-affinity.adoc b/modules/nodes-nodes-rebooting-affinity.adoc deleted file mode 100644 index fea78bc74cb4..000000000000 --- a/modules/nodes-nodes-rebooting-affinity.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-rebooting.adoc - -[id="nodes-nodes-rebooting-affinity_{context}"] -= Rebooting a node using pod anti-affinity - -Pod anti-affinity is slightly different than node anti-affinity. Node anti-affinity can be -violated if there are no other suitable locations to deploy a pod. Pod -anti-affinity can be set to either required or preferred. - -With this in place, if only two infrastructure nodes are available and one is rebooted, the container image registry -pod is prevented from running on the other node. `*oc get pods*` reports the pod as unready until a suitable node is available. -Once a node is available and all pods are back in ready state, the next node can be restarted. - -.Procedure - -To reboot a node using pod anti-affinity: - -. Edit the node specification to configure pod anti-affinity: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: with-pod-antiaffinity -spec: - affinity: - podAntiAffinity: <1> - preferredDuringSchedulingIgnoredDuringExecution: <2> - - weight: 100 <3> - podAffinityTerm: - labelSelector: - matchExpressions: - - key: registry <4> - operator: In <5> - values: - - default - topologyKey: kubernetes.io/hostname ----- -<1> Stanza to configure pod anti-affinity. -<2> Defines a preferred rule. -<3> Specifies a weight for a preferred rule. The node with the highest weight is preferred. -<4> Description of the pod label that determines when the anti-affinity rule applies. Specify a key and value for the label. -<5> The operator represents the relationship between the label on the existing pod and the set of values in the `matchExpression` parameters in the specification for the new pod. Can be `In`, `NotIn`, `Exists`, or `DoesNotExist`. -+ -This example assumes the container image registry pod has a label of -`registry=default`. Pod anti-affinity can use any Kubernetes match -expression. - -. Enable the `MatchInterPodAffinity` scheduler predicate in the scheduling policy file. - diff --git a/modules/nodes-nodes-rebooting-infrastructure.adoc b/modules/nodes-nodes-rebooting-infrastructure.adoc deleted file mode 100644 index b1c175f12051..000000000000 --- a/modules/nodes-nodes-rebooting-infrastructure.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-rebooting.adoc - -[id="nodes-nodes-rebooting-infrastructure_{context}"] -= About rebooting nodes running critical infrastructure - -When rebooting nodes that host critical {product-title} infrastructure components, such as router pods, registry pods, and monitoring pods, ensure that there are at least three nodes available to run these components. - -The following scenario demonstrates how service interruptions can occur with applications running on {product-title} when only two nodes are available: - -- Node A is marked unschedulable and all pods are evacuated. -- The registry pod running on that node is now redeployed on node B. Node B is now running both registry pods. -- Node B is now marked unschedulable and is evacuated. -- The service exposing the two pod endpoints on node B loses all endpoints, for a brief period of time, until they are redeployed to node A. - -When using three nodes for infrastructure components, this process does not result in a service disruption. However, due to pod scheduling, the last node that is evacuated and brought back into rotation does not have a registry pod. One of the other nodes has two registry pods. To schedule the third registry pod on the last node, use pod anti-affinity to prevent the scheduler from locating two registry pods on the same node. diff --git a/modules/nodes-nodes-rebooting-router.adoc b/modules/nodes-nodes-rebooting-router.adoc deleted file mode 100644 index 40ae18b52baf..000000000000 --- a/modules/nodes-nodes-rebooting-router.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-rebooting.adoc - -[id="nodes-nodes-rebooting-router_{context}"] -= Understanding how to reboot nodes running routers - -In most cases, a pod running an {product-title} router exposes a host port. - -The `PodFitsPorts` scheduler predicate ensures that no router pods using the -same port can run on the same node, and pod anti-affinity is achieved. If the -routers are relying on IP failover for high availability, there is nothing else that is needed. - -For router pods relying on an external service such as AWS Elastic Load Balancing for high -availability, it is that service's responsibility to react to router pod restarts. - -In rare cases, a router pod may not have a host port configured. In those cases, -it is important to follow the recommended restart process for infrastructure nodes. diff --git a/modules/nodes-nodes-resources-configuring-about.adoc b/modules/nodes-nodes-resources-configuring-about.adoc deleted file mode 100644 index 86f19fb39b1b..000000000000 --- a/modules/nodes-nodes-resources-configuring-about.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-resources-configuring.adoc - -[id="nodes-nodes-resources-configuring-about_{context}"] -= Understanding how to allocate resources for nodes - -CPU and memory resources reserved for node components in {product-title} are based on two node settings: - -[options="header",cols="1,2"] -|=== -|Setting |Description - -|`kube-reserved` -| This setting is not used with {product-title}. Add the CPU and memory resources that you planned to reserve to the `system-reserved` setting. - -|`system-reserved` -| This setting identifies the resources to reserve for the node components and system components. The default settings depend on the {product-title} and Machine Config Operator versions. Confirm the default `systemReserved` parameter on the `machine-config-operator` repository. -|=== - -If a flag is not set, the defaults are used. If none of the flags are set, the -allocated resource is set to the node's capacity as it was before the -introduction of allocatable resources. - -[NOTE] -==== -Any CPUs specifically reserved using the `reservedSystemCPUs` parameter are not available for allocation using `kube-reserved` or `system-reserved`. -==== - -[id="computing-allocated-resources_{context}"] -== How {product-title} computes allocated resources - -An allocated amount of a resource is computed based on the following formula: - ----- -[Allocatable] = [Node Capacity] - [system-reserved] - [Hard-Eviction-Thresholds] ----- - -[NOTE] -==== -The withholding of `Hard-Eviction-Thresholds` from `Allocatable` improves system reliability because the value for `Allocatable` is enforced for pods at the node level. -==== - -If `Allocatable` is negative, it is set to `0`. - -Each node reports the system resources that are used by the container runtime and kubelet. To simplify configuring the `system-reserved` parameter, view the resource use for the node by using the node summary API. The node summary is available at `/api/v1/nodes/<node>/proxy/stats/summary`. - -[id="allocate-node-enforcement_{context}"] -== How nodes enforce resource constraints - -The node is able to limit the total amount of resources that pods can consume based on the configured allocatable value. This feature significantly improves the reliability of the node by preventing pods from using CPU and memory resources that are needed by system services such as the container runtime and node agent. To improve node reliability, administrators should reserve resources based on a target for resource use. - -The node enforces resource constraints by using a new cgroup hierarchy that enforces quality of service. All pods are launched in a dedicated cgroup hierarchy that is separate from system daemons. - -Administrators should treat system daemons similar to pods that have a guaranteed quality of service. System daemons can burst within their bounding control groups and this behavior must be managed as part of cluster deployments. Reserve CPU and memory resources for system daemons by specifying the amount of CPU and memory resources in `system-reserved`. - -Enforcing `system-reserved` limits can prevent critical system services from receiving CPU and memory resources. As a result, a critical system service can be ended by the out-of-memory killer. The recommendation is to enforce `system-reserved` only if you have profiled the nodes exhaustively to determine precise estimates and you are confident that critical system services can recover if any process in that group is ended by the out-of-memory killer. - -[id="allocate-eviction-thresholds_{context}"] -== Understanding Eviction Thresholds - -If a node is under memory pressure, it can impact the entire node and all pods running on the node. For example, a system daemon that uses more than its reserved amount of memory can trigger an out-of-memory event. To avoid or reduce the probability of system out-of-memory events, the node provides out-of-resource handling. - -You can reserve some memory using the `--eviction-hard` flag. The node attempts to evict -pods whenever memory availability on the node drops below the absolute value or percentage. -If system daemons do not exist on a node, pods are limited to the memory -`capacity - eviction-hard`. For this reason, resources set aside as a buffer for eviction -before reaching out of memory conditions are not available for pods. - -The following is an example to illustrate the impact of node allocatable for memory: - -* Node capacity is `32Gi` -* --system-reserved is `3Gi` -* --eviction-hard is set to `100Mi`. - -For this node, the effective node allocatable value is `28.9Gi`. If the node and system components use all their reservation, the memory available for pods is `28.9Gi`, and kubelet evicts pods when it exceeds this threshold. - -If you enforce node allocatable, `28.9Gi`, with top-level cgroups, then pods can never exceed `28.9Gi`. Evictions are not performed unless system daemons consume more than `3.1Gi` of memory. - -If system daemons do not use up all their reservation, with the above example, -pods would face memcg OOM kills from their bounding cgroup before node evictions kick in. -To better enforce QoS under this situation, the node applies the hard eviction thresholds to -the top-level cgroup for all pods to be `Node Allocatable + Eviction Hard Thresholds`. - -If system daemons do not use up all their reservation, the node will evict pods whenever -they consume more than `28.9Gi` of memory. If eviction does not occur in time, a pod -will be OOM killed if pods consume `29Gi` of memory. - -[id="allocate-scheduler-policy_{context}"] -== How the scheduler determines resource availability - -The scheduler uses the value of `node.Status.Allocatable` instead of -`node.Status.Capacity` to decide if a node will become a candidate for pod -scheduling. - -By default, the node will report its machine capacity as fully schedulable by -the cluster. diff --git a/modules/nodes-nodes-resources-configuring-setting.adoc b/modules/nodes-nodes-resources-configuring-setting.adoc deleted file mode 100644 index d4ab1fc55153..000000000000 --- a/modules/nodes-nodes-resources-configuring-setting.adoc +++ /dev/null @@ -1,123 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-resources-configuring.adoc - -[id="nodes-nodes-resources-configuring-setting_{context}"] -= Configuring allocated resources for nodes - -{product-title} supports the CPU and memory resource types for allocation. The `ephemeral-resource` resource type is supported as well. For the `cpu` type, the resource quantity is specified in units of cores, such as `200m`, `0.5`, or `1`. For `memory` and `ephemeral-storage`, it is specified in units of bytes, such as `200Ki`, `50Mi`, or `5Gi`. - -As an administrator, you can set these using a custom resource (CR) through a set of `<resource_type>=<resource_quantity>` pairs -(e.g., *cpu=200m,memory=512Mi*). - -.Prerequisites - -. To help you determine values for the `system-reserved` setting, you can introspect the resource use for a node by using the node summary API. Enter the following command for your node: -+ -[source,terminal] ----- -$ oc get --raw /api/v1/nodes/<node>/proxy/stats/summary ----- -+ -For example, to access the resources from `cluster.node22` node, you can enter: -+ -[source,terminal] ----- -$ oc get --raw /api/v1/nodes/cluster.node22/proxy/stats/summary ----- -+ -.Example output -[source,json] ----- -{ - "node": { - "nodeName": "cluster.node22", - "systemContainers": [ - { - "cpu": { - "usageCoreNanoSeconds": 929684480915, - "usageNanoCores": 190998084 - }, - "memory": { - "rssBytes": 176726016, - "usageBytes": 1397895168, - "workingSetBytes": 1050509312 - }, - "name": "kubelet" - }, - { - "cpu": { - "usageCoreNanoSeconds": 128521955903, - "usageNanoCores": 5928600 - }, - "memory": { - "rssBytes": 35958784, - "usageBytes": 129671168, - "workingSetBytes": 102416384 - }, - "name": "runtime" - } - ] - } -} ----- - -. Obtain the label associated with the static `MachineConfigPool` CRD for the type of node you want to configure. -Perform one of the following steps: - -.. View the Machine Config Pool: -+ -[source,terminal] ----- -$ oc describe machineconfigpool <name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe machineconfigpool worker ----- -+ -.Example output -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool -metadata: - creationTimestamp: 2019-02-08T14:52:39Z - generation: 1 - labels: - custom-kubelet: small-pods <1> ----- -<1> If a label has been added it appears under `labels`. - -.. If the label is not present, add a key/value pair: -+ -[source,terminal] ----- -$ oc label machineconfigpool worker custom-kubelet=small-pods ----- - -.Procedure - -. Create a custom resource (CR) for your configuration change. -+ -.Sample configuration for a resource allocation CR -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: set-allocatable <1> -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: small-pods <2> - kubeletConfig: - systemReserved: - cpu: 1000m - memory: 1Gi ----- -<1> Assign a name to CR. -<2> Specify the label from the Machine Config Pool. diff --git a/modules/nodes-nodes-resources-cpus-reserve.adoc b/modules/nodes-nodes-resources-cpus-reserve.adoc deleted file mode 100644 index 9729a4957481..000000000000 --- a/modules/nodes-nodes-resources-cpus-reserve.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-resources-cpus - -[id="nodes-nodes-resources-cpus-reserve_{context}"] -= Reserving CPUs for nodes - -To explicitly define a list of CPUs that are reserved for specific nodes, create a `KubeletConfig` custom resource (CR) to define the `reservedSystemCPUs` parameter. This list supersedes the CPUs that might be reserved using the `systemReserved` and `kubeReserved` parameters. - -.Procedure - -. Obtain the label associated with the machine config pool (MCP) for the type of node you want to configure: -+ -[source,terminal] ----- -$ oc describe machineconfigpool <name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe machineconfigpool worker ----- -+ -.Example output -[source,yaml] ----- -Name: worker -Namespace: -Labels: machineconfiguration.openshift.io/mco-built-in= - pools.operator.machineconfiguration.openshift.io/worker= <1> -Annotations: <none> -API Version: machineconfiguration.openshift.io/v1 -Kind: MachineConfigPool -... ----- -<1> Get the MCP label. - -. Create a YAML file for the `KubeletConfig` CR: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: set-reserved-cpus <1> -spec: - kubeletConfig: - reservedSystemCPUs: "0,1,2,3" <2> - machineConfigPoolSelector: - matchLabels: - pools.operator.machineconfiguration.openshift.io/worker: "" <3> ----- -<1> Specify a name for the CR. -<2> Specify the core IDs of the CPUs you want to reserve for the nodes associated with the MCP. -<3> Specify the label from the MCP. - -. Create the CR object: -+ -[source,terminal] ----- -$ oc create -f <file_name>.yaml ----- - diff --git a/modules/nodes-nodes-rtkernel-arguments.adoc b/modules/nodes-nodes-rtkernel-arguments.adoc deleted file mode 100644 index 14a4e7fa86df..000000000000 --- a/modules/nodes-nodes-rtkernel-arguments.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes/nodes-nodes-working.adoc -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="nodes-nodes-rtkernel-arguments_{context}"] -= Adding a real-time kernel to nodes - -Some {product-title} workloads require a high degree of determinism.While Linux is not a real-time operating system, the Linux real-time -kernel includes a preemptive scheduler that provides the operating system with real-time characteristics. - -If your {product-title} workloads require these real-time characteristics, you can switch your machines to the Linux real-time kernel. For {product-title}, {product-version} you can make this switch using a `MachineConfig` object. Although making the change is as simple as changing a machine config `kernelType` setting to `realtime`, there are a few other considerations before making the change: - -* Currently, real-time kernel is supported only on worker nodes, and only for radio access network (RAN) use. -* The following procedure is fully supported with bare metal installations that use systems that are certified for Red Hat Enterprise Linux for Real Time 8. -* Real-time support in {product-title} is limited to specific subscriptions. -* The following procedure is also supported for use with Google Cloud Platform. - -.Prerequisites -* Have a running {product-title} cluster (version 4.4 or later). -* Log in to the cluster as a user with administrative privileges. - -.Procedure - -. Create a machine config for the real-time kernel: Create a YAML file (for example, `99-worker-realtime.yaml`) that contains a `MachineConfig` -object for the `realtime` kernel type. This example tells the cluster to use a real-time kernel for all worker nodes: -+ -[source,terminal] ----- -$ cat << EOF > 99-worker-realtime.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: "worker" - name: 99-worker-realtime -spec: - kernelType: realtime -EOF ----- - -. Add the machine config to the cluster. Type the following to add the machine config to the cluster: -+ -[source,terminal] ----- -$ oc create -f 99-worker-realtime.yaml ----- - -. Check the real-time kernel: Once each impacted node reboots, log in to the cluster and run the following commands to make sure that the real-time kernel has replaced the regular kernel for the set of nodes you configured: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-143-147.us-east-2.compute.internal Ready worker 103m v1.20.0 -ip-10-0-146-92.us-east-2.compute.internal Ready worker 101m v1.20.0 -ip-10-0-169-2.us-east-2.compute.internal Ready worker 102m v1.20.0 ----- -+ -[source,terminal] ----- -$ oc debug node/ip-10-0-143-147.us-east-2.compute.internal ----- -+ -.Example output -[source,terminal] ----- -Starting pod/ip-10-0-143-147us-east-2computeinternal-debug ... -To use host binaries, run `chroot /host` - -sh-4.4# uname -a -Linux <worker_node> 4.18.0-147.3.1.rt24.96.el8_1.x86_64 #1 SMP PREEMPT RT - Wed Nov 27 18:29:55 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux ----- -+ -The kernel name contains `rt` and text “PREEMPT RT” indicates that this is a real-time kernel. - -. To go back to the regular kernel, delete the `MachineConfig` object: -+ -[source,terminal] ----- -$ oc delete -f 99-worker-realtime.yaml ----- diff --git a/modules/nodes-nodes-viewing-listing-pods.adoc b/modules/nodes-nodes-viewing-listing-pods.adoc deleted file mode 100644 index ca0a592d62f2..000000000000 --- a/modules/nodes-nodes-viewing-listing-pods.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-viewing.adoc - -[id="nodes-nodes-viewing-listing-pods_{context}"] -= Listing pods on a node in your cluster - -You can list all the pods on a specific node. - -.Procedure - -* To list all or selected pods on one or more nodes: -+ -[source,terminal] ----- -$ oc describe node <node1> <node2> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe node ip-10-0-128-218.ec2.internal ----- - -* To list all or selected pods on selected nodes: -+ -[source,terminal] ----- -$ oc describe --selector=<node_selector> ----- -+ -[source,terminal] ----- -$ oc describe node --selector=kubernetes.io/os ----- -+ -Or: -+ -[source,terminal] ----- -$ oc describe -l=<pod_selector> ----- -+ -[source,terminal] ----- -$ oc describe node -l node-role.kubernetes.io/worker ----- - -* To list all pods on a specific node, including terminated pods: -+ -[source,terminal] ----- -$ oc get pod --all-namespaces --field-selector=spec.nodeName=<nodename> ----- diff --git a/modules/nodes-nodes-viewing-listing.adoc b/modules/nodes-nodes-viewing-listing.adoc deleted file mode 100644 index 8d7336bc4961..000000000000 --- a/modules/nodes-nodes-viewing-listing.adoc +++ /dev/null @@ -1,244 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-viewing.adoc - -[id="nodes-nodes-viewing-listing_{context}"] -= About listing all the nodes in a cluster - -You can get detailed information on the nodes in the cluster. - -* The following command lists all nodes: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -The following example is a cluster with healthy nodes: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -master.example.com Ready master 7h v1.20.0 -node1.example.com Ready worker 7h v1.20.0 -node2.example.com Ready worker 7h v1.20.0 ----- -+ -The following example is a cluster with one unhealthy node: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -master.example.com Ready master 7h v1.20.0 -node1.example.com NotReady,SchedulingDisabled worker 7h v1.20.0 -node2.example.com Ready worker 7h v1.20.0 ----- -+ -The conditions that trigger a `NotReady` status are shown later in this section. - -* The `-o wide` option provides additional information on nodes. -+ -[source,terminal] ----- -$ oc get nodes -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME -master.example.com Ready master 171m v1.20.0+39c0afe 10.0.129.108 <none> Red Hat Enterprise Linux CoreOS 48.83.202103210901-0 (Ootpa) 4.18.0-240.15.1.el8_3.x86_64 cri-o://1.21.0-30.rhaos4.8.gitf2f339d.el8-dev -node1.example.com Ready worker 72m v1.20.0+39c0afe 10.0.129.222 <none> Red Hat Enterprise Linux CoreOS 48.83.202103210901-0 (Ootpa) 4.18.0-240.15.1.el8_3.x86_64 cri-o://1.21.0-30.rhaos4.8.gitf2f339d.el8-dev -node2.example.com Ready worker 164m v1.20.0+39c0afe 10.0.142.150 <none> Red Hat Enterprise Linux CoreOS 48.83.202103210901-0 (Ootpa) 4.18.0-240.15.1.el8_3.x86_64 cri-o://1.21.0-30.rhaos4.8.gitf2f339d.el8-dev ----- - -* The following command lists information about a single node: -+ -[source,terminal] ----- -$ oc get node <node> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get node node1.example.com ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -node1.example.com Ready worker 7h v1.20.0 ----- - -* The following command provides more detailed information about a specific node, including the reason for -the current condition: -+ -[source,terminal] ----- -$ oc describe node <node> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe node node1.example.com ----- -+ -.Example output -[source,yaml] ----- -Name: node1.example.com <1> -Roles: worker <2> -Labels: beta.kubernetes.io/arch=amd64 <3> - beta.kubernetes.io/instance-type=m4.large - kubernetes.io/os=linux - failure-domain.beta.kubernetes.io/region=us-east-2 - failure-domain.beta.kubernetes.io/zone=us-east-2a - kubernetes.io/hostname=ip-10-0-140-16 - node-role.kubernetes.io/worker= -Annotations: cluster.k8s.io/machine: openshift-machine-api/ahardin-worker-us-east-2a-q5dzc <4> - machineconfiguration.openshift.io/currentConfig: worker-309c228e8b3a92e2235edd544c62fea8 - machineconfiguration.openshift.io/desiredConfig: worker-309c228e8b3a92e2235edd544c62fea8 - machineconfiguration.openshift.io/state: Done - volumes.kubernetes.io/controller-managed-attach-detach: true -CreationTimestamp: Wed, 13 Feb 2019 11:05:57 -0500 -Taints: <none> <5> -Unschedulable: false -Conditions: <6> - Type Status LastHeartbeatTime LastTransitionTime Reason Message - ---- ------ ----------------- ------------------ ------ ------- - OutOfDisk False Wed, 13 Feb 2019 15:09:42 -0500 Wed, 13 Feb 2019 11:05:57 -0500 KubeletHasSufficientDisk kubelet has sufficient disk space available - MemoryPressure False Wed, 13 Feb 2019 15:09:42 -0500 Wed, 13 Feb 2019 11:05:57 -0500 KubeletHasSufficientMemory kubelet has sufficient memory available - DiskPressure False Wed, 13 Feb 2019 15:09:42 -0500 Wed, 13 Feb 2019 11:05:57 -0500 KubeletHasNoDiskPressure kubelet has no disk pressure - PIDPressure False Wed, 13 Feb 2019 15:09:42 -0500 Wed, 13 Feb 2019 11:05:57 -0500 KubeletHasSufficientPID kubelet has sufficient PID available - Ready True Wed, 13 Feb 2019 15:09:42 -0500 Wed, 13 Feb 2019 11:07:09 -0500 KubeletReady kubelet is posting ready status -Addresses: <7> - InternalIP: 10.0.140.16 - InternalDNS: ip-10-0-140-16.us-east-2.compute.internal - Hostname: ip-10-0-140-16.us-east-2.compute.internal -Capacity: <8> - attachable-volumes-aws-ebs: 39 - cpu: 2 - hugepages-1Gi: 0 - hugepages-2Mi: 0 - memory: 8172516Ki - pods: 250 -Allocatable: - attachable-volumes-aws-ebs: 39 - cpu: 1500m - hugepages-1Gi: 0 - hugepages-2Mi: 0 - memory: 7558116Ki - pods: 250 -System Info: <9> - Machine ID: 63787c9534c24fde9a0cde35c13f1f66 - System UUID: EC22BF97-A006-4A58-6AF8-0A38DEEA122A - Boot ID: f24ad37d-2594-46b4-8830-7f7555918325 - Kernel Version: 3.10.0-957.5.1.el7.x86_64 - OS Image: Red Hat Enterprise Linux CoreOS 410.8.20190520.0 (Ootpa) - Operating System: linux - Architecture: amd64 - Container Runtime Version: cri-o://1.16.0-0.6.dev.rhaos4.3.git9ad059b.el8-rc2 - Kubelet Version: v1.20.0 - Kube-Proxy Version: v1.20.0 -PodCIDR: 10.128.4.0/24 -ProviderID: aws:///us-east-2a/i-04e87b31dc6b3e171 -Non-terminated Pods: (13 in total) <10> - Namespace Name CPU Requests CPU Limits Memory Requests Memory Limits - --------- ---- ------------ ---------- --------------- ------------- - openshift-cluster-node-tuning-operator tuned-hdl5q 0 (0%) 0 (0%) 0 (0%) 0 (0%) - openshift-dns dns-default-l69zr 0 (0%) 0 (0%) 0 (0%) 0 (0%) - openshift-image-registry node-ca-9hmcg 0 (0%) 0 (0%) 0 (0%) 0 (0%) - openshift-ingress router-default-76455c45c-c5ptv 0 (0%) 0 (0%) 0 (0%) 0 (0%) - openshift-machine-config-operator machine-config-daemon-cvqw9 20m (1%) 0 (0%) 50Mi (0%) 0 (0%) - openshift-marketplace community-operators-f67fh 0 (0%) 0 (0%) 0 (0%) 0 (0%) - openshift-monitoring alertmanager-main-0 50m (3%) 50m (3%) 210Mi (2%) 10Mi (0%) - openshift-monitoring grafana-78765ddcc7-hnjmm 100m (6%) 200m (13%) 100Mi (1%) 200Mi (2%) - openshift-monitoring node-exporter-l7q8d 10m (0%) 20m (1%) 20Mi (0%) 40Mi (0%) - openshift-monitoring prometheus-adapter-75d769c874-hvb85 0 (0%) 0 (0%) 0 (0%) 0 (0%) - openshift-multus multus-kw8w5 0 (0%) 0 (0%) 0 (0%) 0 (0%) - openshift-sdn ovs-t4dsn 100m (6%) 0 (0%) 300Mi (4%) 0 (0%) - openshift-sdn sdn-g79hg 100m (6%) 0 (0%) 200Mi (2%) 0 (0%) -Allocated resources: - (Total limits may be over 100 percent, i.e., overcommitted.) - Resource Requests Limits - -------- -------- ------ - cpu 380m (25%) 270m (18%) - memory 880Mi (11%) 250Mi (3%) - attachable-volumes-aws-ebs 0 0 -Events: <11> - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal NodeHasSufficientPID 6d (x5 over 6d) kubelet, m01.example.com Node m01.example.com status is now: NodeHasSufficientPID - Normal NodeAllocatableEnforced 6d kubelet, m01.example.com Updated Node Allocatable limit across pods - Normal NodeHasSufficientMemory 6d (x6 over 6d) kubelet, m01.example.com Node m01.example.com status is now: NodeHasSufficientMemory - Normal NodeHasNoDiskPressure 6d (x6 over 6d) kubelet, m01.example.com Node m01.example.com status is now: NodeHasNoDiskPressure - Normal NodeHasSufficientDisk 6d (x6 over 6d) kubelet, m01.example.com Node m01.example.com status is now: NodeHasSufficientDisk - Normal NodeHasSufficientPID 6d kubelet, m01.example.com Node m01.example.com status is now: NodeHasSufficientPID - Normal Starting 6d kubelet, m01.example.com Starting kubelet. - ... ----- -<1> The name of the node. -<2> The role of the node, either `master` or `worker`. -<3> The labels applied to the node. -<4> The annotations applied to the node. -<5> The taints applied to the node. -<6> The node conditions and status. The `conditions` stanza lists the `Ready`, `PIDPressure`, `PIDPressure`, `MemoryPressure`, `DiskPressure` and `OutOfDisk` status. These condition are described later in this section. -<7> The IP address and host name of the node. -<8> The pod resources and allocatable resources. -<9> Information about the node host. -<10> The pods on the node. -<11> The events reported by the node. - -Among the information shown for nodes, the following node conditions appear in the output of the commands shown in this section: - -[discrete] -[id="machine-health-checks-resource-conditions"] -.Node Conditions -[cols="3a,8a",options="header"] -|=== - -|Condition |Description - -|`Ready` -|If `true`, the node is healthy and ready to accept pods. If `false`, the node is not healthy and is not accepting pods. If `unknown`, the node controller has not received a heartbeat from the node for the `node-monitor-grace-period` (the default is 40 seconds). - -|`DiskPressure` -|If `true`, the disk capacity is low. - -|`MemoryPressure` -|If `true`, the node memory is low. - -|`PIDPressure` -|If `true`, there are too many processes on the node. - -|`OutOfDisk` -|If `true`, the node has insufficient free space on the node for adding new pods. - -|`NetworkUnavailable` -| If `true`, the network for the node is not correctly configured. - -|`NotReady` -|If `true`, one of the underlying components, such as the container runtime or network, is experiencing issues or is not yet configured. - -|`SchedulingDisabled` -|Pods cannot be scheduled for placement on the node. - -|=== - diff --git a/modules/nodes-nodes-viewing-memory.adoc b/modules/nodes-nodes-viewing-memory.adoc deleted file mode 100644 index 0e4ed57d79b6..000000000000 --- a/modules/nodes-nodes-viewing-memory.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-viewing.adoc - -[id="nodes-nodes-viewing-memory_{context}"] -= Viewing memory and CPU usage statistics on your nodes - -You can display usage statistics about nodes, which provide the runtime -environments for containers. These usage statistics include CPU, memory, and -storage consumption. - -.Prerequisites - -* You must have `cluster-reader` permission to view the usage statistics. - -* Metrics must be installed to view the usage statistics. - -.Procedure - -* To view the usage statistics: -+ -[source,terminal] ----- -$ oc adm top nodes ----- -+ -.Example output -[source,terminal] ----- -NAME CPU(cores) CPU% MEMORY(bytes) MEMORY% -ip-10-0-12-143.ec2.compute.internal 1503m 100% 4533Mi 61% -ip-10-0-132-16.ec2.compute.internal 76m 5% 1391Mi 18% -ip-10-0-140-137.ec2.compute.internal 398m 26% 2473Mi 33% -ip-10-0-142-44.ec2.compute.internal 656m 43% 6119Mi 82% -ip-10-0-146-165.ec2.compute.internal 188m 12% 3367Mi 45% -ip-10-0-19-62.ec2.compute.internal 896m 59% 5754Mi 77% -ip-10-0-44-193.ec2.compute.internal 632m 42% 5349Mi 72% ----- - -* To view the usage statistics for nodes with labels: -+ -[source,terminal] ----- -$ oc adm top node --selector='' ----- -+ -You must choose the selector (label query) to filter on. Supports `=`, `==`, and `!=`. diff --git a/modules/nodes-nodes-working-deleting-bare-metal.adoc b/modules/nodes-nodes-working-deleting-bare-metal.adoc deleted file mode 100644 index 766692dc63c1..000000000000 --- a/modules/nodes-nodes-working-deleting-bare-metal.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-working.adoc -// * virt/virtual_machines/virt-triggering-vm-failover-resolving-failed-node.adoc - -[id="nodes-nodes-working-deleting-bare-metal_{context}"] -= Deleting nodes from a bare metal cluster - -When you delete a node using the CLI, the node object is deleted in Kubernetes, -but the pods that exist on the node are not deleted. Any bare pods not backed by -a replication controller become inaccessible to {product-title}. Pods backed by -replication controllers are rescheduled to other available nodes. You must -delete local manifest pods. - -.Procedure - -Delete a node from an {product-title} cluster running on bare metal by completing -the following steps: - -. Mark the node as unschedulable: -+ -[source,terminal] ----- -$ oc adm cordon <node_name> ----- - -. Drain all pods on your node: -+ -[source,terminal] ----- -$ oc adm drain <node_name> --force=true ----- - -. Delete your node from the cluster: -+ -[source,terminal] ----- -$ oc delete node <node_name> ----- - -Although the node object is now deleted from the cluster, it can still rejoin -the cluster after reboot or if the kubelet service is restarted. To permanently -delete the node and all its data, you must -link:https://access.redhat.com/solutions/84663[decommission the node]. diff --git a/modules/nodes-nodes-working-deleting.adoc b/modules/nodes-nodes-working-deleting.adoc deleted file mode 100644 index 9ebfc5e7f8e5..000000000000 --- a/modules/nodes-nodes-working-deleting.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-working.adoc - -[id="nodes-nodes-working-deleting_{context}"] -= Deleting nodes from a cluster - -When you delete a node using the CLI, the node object is deleted in Kubernetes, -but the pods that exist on the node are not deleted. Any bare pods not -backed by a replication controller become inaccessible to {product-title}. -Pods backed by replication controllers are rescheduled to other available -nodes. You must delete local manifest pods. - -.Procedure - -To delete a node from the {product-title} cluster, edit the appropriate `MachineSet` object: - -[NOTE] -==== -If you are running cluster on bare metal, you cannot delete a node by editing -`MachineSet` objects. Machine sets are only available when a cluster is integrated with a cloud provider. Instead you must unschedule and drain the node before manually -deleting it. -==== - -. View the machine sets that are in the cluster: -+ -[source,terminal] ----- -$ oc get machinesets -n openshift-machine-api ----- -+ -The machine sets are listed in the form of <clusterid>-worker-<aws-region-az>. - -. Scale the machine set: -+ -[source,terminal] ----- -$ oc scale --replicas=2 machineset <machineset> -n openshift-machine-api ----- - -For more information on scaling your cluster using a machine set, see _Manually scaling a machine set_. diff --git a/modules/nodes-nodes-working-evacuating.adoc b/modules/nodes-nodes-working-evacuating.adoc deleted file mode 100644 index 8aeba271b8e0..000000000000 --- a/modules/nodes-nodes-working-evacuating.adoc +++ /dev/null @@ -1,116 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-working.adoc - -[id="nodes-nodes-working-evacuating_{context}"] -= Understanding how to evacuate pods on nodes - -Evacuating pods allows you to migrate all or selected pods from a given node or -nodes. - -You can only evacuate pods backed by a replication controller. The replication controller creates new pods on -other nodes and removes the existing pods from the specified node(s). - -Bare pods, meaning those not backed by a replication controller, are unaffected by default. -You can evacuate a subset of pods by specifying a pod-selector. Pod selectors are -based on labels, so all the pods with the specified label will be evacuated. - -.Procedure - -. Mark the nodes unschedulable before performing the pod evacuation. - -.. Mark the node as unschedulable: -+ -[source,terminal] ----- -$ oc adm cordon <node1> ----- -+ -.Example output -[source,terminal] ----- -node/<node1> cordoned ----- - -.. Check that the node status is `NotReady,SchedulingDisabled`: -+ -[source,terminal] ----- -$ oc get node <node1> ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -<node1> NotReady,SchedulingDisabled worker 1d v1.20.0 ----- - -. Evacuate the pods using one of the following methods: - -** Evacuate all or selected pods on one or more nodes: -+ -[source,terminal] ----- -$ oc adm drain <node1> <node2> [--pod-selector=<pod_selector>] ----- - -** Force the deletion of bare pods using the `--force` option. When set to -`true`, deletion continues even if there are pods not managed by a replication -controller, replica set, job, daemon set, or stateful set: -+ -[source,terminal] ----- -$ oc adm drain <node1> <node2> --force=true ----- - -** Set a period of time in seconds for each Pod to -terminate gracefully, use `--grace-period`. If negative, the default value specified in the Pod will -be used: -+ -[source,terminal] ----- -$ oc adm drain <node1> <node2> --grace-period=-1 ----- - -** Ignore pods managed by daemon sets using the `--ignore-daemonsets` flag set to `true`: -+ -[source,terminal] ----- -$ oc adm drain <node1> <node2> --ignore-daemonsets=true ----- - -** Set the length of time to wait before giving up using the `--timeout` flag. A -value of `0` sets an infinite length of time: -+ -[source,terminal] ----- -$ oc adm drain <node1> <node2> --timeout=5s ----- - -** Delete pods even if there are pods using emptyDir using the `--delete-local-data` flag set to `true`. Local data is deleted when the node -is drained: -+ -[source,terminal] ----- -$ oc adm drain <node1> <node2> --delete-local-data=true ----- - -** List objects that will be migrated without actually performing the evacuation, -using the `--dry-run` option set to `true`: -+ -[source,terminal] ----- -$ oc adm drain <node1> <node2> --dry-run=true ----- -+ -Instead of specifying specific node names (for example, `<node1> <node2>`), you -can use the `--selector=<node_selector>` option to evacuate pods on selected -nodes. - -. Mark the node as schedulable when done. -+ -[source,terminal] ----- -$ oc adm uncordon <node1> ----- diff --git a/modules/nodes-nodes-working-marking.adoc b/modules/nodes-nodes-working-marking.adoc deleted file mode 100644 index 1d22cb7825ce..000000000000 --- a/modules/nodes-nodes-working-marking.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-working.adoc - -[id="nodes-nodes-working-marking_{context}"] -= Understanding how to mark nodes as unschedulable or schedulable - -By default, healthy nodes with a `Ready` status are -marked as schedulable, meaning that new pods are allowed for placement on the -node. Manually marking a node as unschedulable blocks any new pods from being -scheduled on the node. Existing pods on the node are not affected. - -* The following command marks a node or nodes as unschedulable: -+ -.Example output -[source,terminal] ----- -$ oc adm cordon <node> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm cordon node1.example.com ----- -+ -.Example output -[source,terminal] ----- -node/node1.example.com cordoned - -NAME LABELS STATUS -node1.example.com kubernetes.io/hostname=node1.example.com Ready,SchedulingDisabled ----- - -* The following command marks a currently unschedulable node or nodes as schedulable: -+ -[source,terminal] ----- -$ oc adm uncordon <node1> ----- -+ -Alternatively, instead of specifying specific node names (for example, `<node>`), you can use the `--selector=<node_selector>` option to mark selected -nodes as schedulable or unschedulable. diff --git a/modules/nodes-nodes-working-master-schedulable.adoc b/modules/nodes-nodes-working-master-schedulable.adoc deleted file mode 100644 index 0f9d7f6e3e54..000000000000 --- a/modules/nodes-nodes-working-master-schedulable.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-working.adoc - -[id="nodes-nodes-working-master-schedulable_{context}"] -= Configuring master nodes as schedulable - -You can configure master nodes to be -schedulable, meaning that new pods are allowed for placement on the master -nodes. By default, master nodes are not schedulable. - -You can set the masters to be schedulable, but must retain the worker nodes. - -[NOTE] -==== -You can deploy {product-title} with no worker nodes on a bare metal cluster. -In this case, the master nodes are marked schedulable by default. -==== - -You can allow or disallow master nodes to be schedulable by configuring the -`mastersSchedulable` field. - -.Procedure - -. Edit the `schedulers.config.openshift.io` resource. -+ -[source,terminal] ----- -$ oc edit schedulers.config.openshift.io cluster ----- - -. Configure the `mastersSchedulable` field. -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Scheduler -metadata: - creationTimestamp: "2019-09-10T03:04:05Z" - generation: 1 - name: cluster - resourceVersion: "433" - selfLink: /apis/config.openshift.io/v1/schedulers/cluster - uid: a636d30a-d377-11e9-88d4-0a60097bee62 -spec: - mastersSchedulable: false <1> - policy: - name: "" -status: {} ----- -<1> Set to `true` to allow master nodes to be schedulable, or `false` to -disallow master nodes to be schedulable. - -. Save the file to apply the changes. diff --git a/modules/nodes-nodes-working-updating.adoc b/modules/nodes-nodes-working-updating.adoc deleted file mode 100644 index 95468147be13..000000000000 --- a/modules/nodes-nodes-working-updating.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-nodes-working.adoc - -[id="nodes-nodes-working-updating_{context}"] -= Understanding how to update labels on nodes - -You can update any label on a node. - -Node labels are not persisted after a node is deleted even if the node is backed up by a Machine. - -[NOTE] -==== -Any change to a `MachineSet` object is not applied to existing machines owned by the machine set. -For example, labels edited or added to an existing `MachineSet` object are not propagated to existing machines and nodes -associated with the machine set. -==== - -* The following command adds or updates labels on a node: -+ -[source,terminal] ----- -$ oc label node <node> <key_1>=<value_1> ... <key_n>=<value_n> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc label nodes webconsole-7f7f6 unhealthy=true ----- - -* The following command updates all pods in the namespace: -+ -[source,terminal] ----- -$ oc label pods --all <key_1>=<value_1> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc label pods --all status=unhealthy ----- - diff --git a/modules/nodes-pods-about.adoc b/modules/nodes-pods-about.adoc deleted file mode 100644 index d0322aebe983..000000000000 --- a/modules/nodes-pods-about.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-using.adoc - -[id="nodes-pods-about_{context}"] -= About pods - -{product-title} leverages the Kubernetes concept of a _pod_, which is one or more containers deployed -together on one host, and the smallest compute unit that can be defined, -deployed, and managed. Pods are the rough equivalent of a machine instance (physical or virtual) to a container. - -You can view a list of pods associated with a specific project or view usage statistics about pods. diff --git a/modules/nodes-pods-autoscaling-about.adoc b/modules/nodes-pods-autoscaling-about.adoc deleted file mode 100644 index 249b60416135..000000000000 --- a/modules/nodes-pods-autoscaling-about.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-autoscaling-about.adoc - -[id="nodes-pods-autoscaling-about_{context}"] -= Understanding horizontal pod autoscalers - -You can create a horizontal pod autoscaler to specify the minimum and maximum number of pods -you want to run, as well as the CPU utilization or memory utilization your pods should target. - -After you create a horizontal pod autoscaler, {product-title} begins to query the CPU and/or memory resource metrics on the pods. -When these metrics are available, the horizontal pod autoscaler computes -the ratio of the current metric utilization with the desired metric utilization, -and scales up or down accordingly. The query and scaling occurs at a regular interval, -but can take one to two minutes before metrics become available. - -For replication controllers, this scaling corresponds directly to the replicas -of the replication controller. For deployment configurations, scaling corresponds -directly to the replica count of the deployment configuration. Note that autoscaling -applies only to the latest deployment in the `Complete` phase. - -{product-title} automatically accounts for resources and prevents unnecessary autoscaling -during resource spikes, such as during start up. Pods in the `unready` state -have `0 CPU` usage when scaling up and the autoscaler ignores the pods when scaling down. -Pods without known metrics have `0% CPU` usage when scaling up and `100% CPU` when scaling down. -This allows for more stability during the HPA decision. To use this feature, you must configure -readiness checks to determine if a new pod is ready for use. - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -To use horizontal pod autoscalers, your cluster administrator must have -properly configured cluster metrics. -endif::openshift-origin,openshift-enterprise,openshift-webscale[] - -== Supported metrics - -The following metrics are supported by horizontal pod autoscalers: - -.Metrics -[cols="3a,5a,5a",options="header"] -|=== - -|Metric |Description |API version - -|CPU utilization -|Number of CPU cores used. Can be used to calculate a percentage of the pod's requested CPU. -|`autoscaling/v1`, `autoscaling/v2beta2` - -|Memory utilization -|Amount of memory used. Can be used to calculate a percentage of the pod's requested memory. -|`autoscaling/v2beta2` -|=== - -[IMPORTANT] -==== -For memory-based autoscaling, memory usage must increase and decrease -proportionally to the replica count. On average: - -* An increase in replica count must lead to an overall decrease in memory -(working set) usage per-pod. -* A decrease in replica count must lead to an overall increase in per-pod memory -usage. - -Use the {product-title} web console to check the memory behavior of your application -and ensure that your application meets these requirements before using -memory-based autoscaling. -==== diff --git a/modules/nodes-pods-autoscaling-creating-cpu.adoc b/modules/nodes-pods-autoscaling-creating-cpu.adoc deleted file mode 100644 index 98d5020b6251..000000000000 --- a/modules/nodes-pods-autoscaling-creating-cpu.adoc +++ /dev/null @@ -1,238 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-autoscaling-about.adoc - -[id="nodes-pods-autoscaling-creating-cpu_{context}"] - -= Creating a horizontal pod autoscaler for CPU utilization - -You can create a horizontal pod autoscaler (HPA) for an existing `DeploymentConfig` or `ReplicationController` object -that automatically scales the pods associated with that object to maintain the CPU usage you specify. - -The HPA increases and decreases the number of replicas between the minimum and maximum numbers to maintain the specified CPU utilization across all pods. - -When autoscaling for CPU utilization, you can use the `oc autoscale` command and specify the minimum and maximum number of pods you want to run at any given time and the average CPU utilization your pods should target. If you do not specify a minimum, the pods are given default values from the {product-title} server. -To autoscale for a specific CPU value, create a `HorizontalPodAutoscaler` object with the target CPU and pod limits. - -.Prerequisites - -To use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics. -You can use the `oc describe PodMetrics <pod-name>` command to determine if metrics are configured. If metrics are -configured, the output appears similar to the following, with `Cpu` and `Memory` displayed under `Usage`. - -[source,terminal] ----- -$ oc describe PodMetrics openshift-kube-scheduler-ip-10-0-135-131.ec2.internal ----- - -.Example output -[source,yaml,options="nowrap"] ----- -Name: openshift-kube-scheduler-ip-10-0-135-131.ec2.internal -Namespace: openshift-kube-scheduler -Labels: <none> -Annotations: <none> -API Version: metrics.k8s.io/v1beta1 -Containers: - Name: wait-for-host-port - Usage: - Memory: 0 - Name: scheduler - Usage: - Cpu: 8m - Memory: 45440Ki -Kind: PodMetrics -Metadata: - Creation Timestamp: 2019-05-23T18:47:56Z - Self Link: /apis/metrics.k8s.io/v1beta1/namespaces/openshift-kube-scheduler/pods/openshift-kube-scheduler-ip-10-0-135-131.ec2.internal -Timestamp: 2019-05-23T18:47:56Z -Window: 1m0s -Events: <none> ----- - -.Procedure - -To create a horizontal pod autoscaler for CPU utilization: - -. Perform one of the following one of the following: - -** To scale based on the percent of CPU utilization, create a `HorizontalPodAutoscaler` object for an existing `DeploymentConfig` object: -+ -[source,terminal] ----- -$ oc autoscale dc/<dc-name> \// <1> - --min <number> \// <2> - --max <number> \// <3> - --cpu-percent=<percent> <4> ----- -+ -<1> Specify the name of the `DeploymentConfig` object. The object must exist. -<2> Optionally, specify the minimum number of replicas when scaling down. -<3> Specify the maximum number of replicas when scaling up. -<4> Specify the target average CPU utilization over all the pods, represented as a percent of requested CPU. If not specified or negative, a default autoscaling policy is used. - -** To scale based on the percent of CPU utilization, create a `HorizontalPodAutoscaler` object for an existing replication controller: -+ -[source,terminal] ----- -$ oc autoscale rc/<rc-name> <1> - --min <number> \// <2> - --max <number> \// <3> - --cpu-percent=<percent> <4> ----- -+ -<1> Specify the name of the replication controller. The object must exist. -<2> Specify the minimum number of replicas when scaling down. -<3> Specify the maximum number of replicas when scaling up. -<4> Specify the target average CPU utilization over all the pods, represented as a percent of requested CPU. If not specified or negative, a default autoscaling policy is used. - -** To scale for a specific CPU value, create a YAML file similar to the following for an existing `DeploymentConfig` object or replication controller: -+ -.. Create a YAML file similar to the following: -+ -[source,yaml,options="nowrap"] ----- -apiVersion: autoscaling/v2beta2 <1> -kind: HorizontalPodAutoscaler -metadata: - name: cpu-autoscale <2> - namespace: default -spec: - scaleTargetRef: - apiVersion: v1 <3> - kind: ReplicationController <4> - name: example <5> - minReplicas: 1 <6> - maxReplicas: 10 <7> - metrics: <8> - - type: Resource - resource: - name: cpu <9> - target: - type: AverageValue <10> - averageValue: 500m <11> ----- -<1> Use the `autoscaling/v2beta2` API. -<2> Specify a name for this horizontal pod autoscaler object. -<3> Specify the API version of the object to scale: -* For a replication controller, use `v1`, -* For a `DeploymentConfig` object, use `apps.openshift.io/v1`. -<4> Specify the kind of object to scale, either `ReplicationController` or `DeploymentConfig`. -<5> Specify the name of the object to scale. The object must exist. -<6> Specify the minimum number of replicas when scaling down. -<7> Specify the maximum number of replicas when scaling up. -<8> Use the `metrics` parameter for memory utilization. -<9> Specify `cpu` for CPU utilization. -<10> Set to `AverageValue`. -<11> Set to `averageValue` with the targeted CPU value. - -.. Create the horizontal pod autoscaler: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- - -. Verify that the horizontal pod autoscaler was created: -+ -[source,terminal] ----- -$ oc get hpa cpu-autoscale ----- -+ -.Example output -[source,terminal] ----- -NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE -cpu-autoscale ReplicationController/example 173m/500m 1 10 1 20m ----- - -For example, the following command creates a horizontal pod autoscaler that maintains between 3 and 7 replicas of the pods that are controlled by the `image-registry` `DeploymentConfig` object to maintain an average CPU utilization of 75% across all pods. - -[source,terminal] ----- -$ oc autoscale dc/image-registry --min 3 --max 7 --cpu-percent=75 ----- - -.Example output -[source,terminal] ----- -deploymentconfig "image-registry" autoscaled ----- - -The command creates a horizontal pod autoscaler with the following definition: - -[source,terminal] ----- -$ oc edit hpa frontend -n openshift-image-registry ----- - -.Example output -[source,yaml] ----- -apiVersion: autoscaling/v1 -kind: HorizontalPodAutoscaler -metadata: - creationTimestamp: "2020-02-21T20:19:28Z" - name: image-registry - namespace: default - resourceVersion: "32452" - selfLink: /apis/autoscaling/v1/namespaces/default/horizontalpodautoscalers/frontend - uid: 1a934a22-925d-431e-813a-d00461ad7521 -spec: - maxReplicas: 7 - minReplicas: 3 - scaleTargetRef: - apiVersion: apps.openshift.io/v1 - kind: DeploymentConfig - name: image-registry - targetCPUUtilizationPercentage: 75 -status: - currentReplicas: 5 - desiredReplicas: 0 ----- - -The following example shows autoscaling for the `image-registry` `DeploymentConfig` object. The initial deployment requires 3 pods. The HPA object increased that minimum to 5 and will increase the pods up to 7 if CPU usage on the pods reaches 75%: - -. View the current state of the `image-registry` deployment: -+ -[source,terminal] ----- -$ oc get dc image-registry ----- -+ -.Example output -[source,terminal] ----- -NAME REVISION DESIRED CURRENT TRIGGERED BY -image-registry 1 3 3 config ----- - -. Autoscale the `image-registry` `DeploymentConfig` object: -+ -[source,terminal] ----- -$ oc autoscale dc/image-registry --min=5 --max=7 --cpu-percent=75 ----- -+ -.Example output -[source,terminal] ----- -horizontalpodautoscaler.autoscaling/image-registry autoscaled ----- - -. View the new state of the deployment: -+ -[source,terminal] ----- -$ oc get dc image-registry ----- -+ -There are now 5 pods in the deployment: -+ -.Example output -[source,terminal] ----- -NAME REVISION DESIRED CURRENT TRIGGERED BY -image-registry 1 5 5 config ----- diff --git a/modules/nodes-pods-autoscaling-creating-memory.adoc b/modules/nodes-pods-autoscaling-creating-memory.adoc deleted file mode 100644 index a22eb87ad66d..000000000000 --- a/modules/nodes-pods-autoscaling-creating-memory.adoc +++ /dev/null @@ -1,228 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-autoscaling-about.adoc - -[id="nodes-pods-autoscaling-creating-memory_{context}"] - -= Creating a horizontal pod autoscaler object for memory utilization - -You can create a horizontal pod autoscaler (HPA) for an existing `DeploymentConfig` object or `ReplicationController` object -that automatically scales the pods associated with that object to maintain the average memory utilization you specify, -either a direct value or a percentage of requested memory. - -The HPA increases and decreases the number of replicas between the minimum and maximum numbers to maintain -the specified memory utilization across all pods. - -For memory utilization, you can specify the minimum and maximum number of pods and the average memory utilization -your pods should target. If you do not specify a minimum, the pods are given default values from the {product-title} server. - -.Prerequisites - -To use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics. -You can use the `oc describe PodMetrics <pod-name>` command to determine if metrics are configured. If metrics are -configured, the output appears similar to the following, with `Cpu` and `Memory` displayed under `Usage`. - -[source,terminal] ----- -$ oc describe PodMetrics openshift-kube-scheduler-ip-10-0-129-223.compute.internal -n openshift-kube-scheduler ----- - -.Example output -[source,yaml,options="nowrap"] ----- -Name: openshift-kube-scheduler-ip-10-0-129-223.compute.internal -Namespace: openshift-kube-scheduler -Labels: <none> -Annotations: <none> -API Version: metrics.k8s.io/v1beta1 -Containers: - Name: scheduler - Usage: - Cpu: 2m - Memory: 41056Ki - Name: wait-for-host-port - Usage: - Memory: 0 -Kind: PodMetrics -Metadata: - Creation Timestamp: 2020-02-14T22:21:14Z - Self Link: /apis/metrics.k8s.io/v1beta1/namespaces/openshift-kube-scheduler/pods/openshift-kube-scheduler-ip-10-0-129-223.compute.internal -Timestamp: 2020-02-14T22:21:14Z -Window: 5m0s -Events: <none> - ----- - -.Procedure - -To create a horizontal pod autoscaler for memory utilization: - -. Create a YAML file for one of the following: - -** To scale for a specific memory value, create a `HorizontalPodAutoscaler` object similar to the following for an existing `DeploymentConfig` object or replication controller: -+ -.Example output -[source,yaml,options="nowrap"] ----- -apiVersion: autoscaling/v2beta2 <1> -kind: HorizontalPodAutoscaler -metadata: - name: hpa-resource-metrics-memory <2> - namespace: default -spec: - scaleTargetRef: - apiVersion: v1 <3> - kind: ReplicationController <4> - name: example <5> - minReplicas: 1 <6> - maxReplicas: 10 <7> - metrics: <8> - - type: Resource - resource: - name: memory <9> - target: - type: AverageValue <10> - averageValue: 500Mi <11> - behavior: <12> - scaleDown: - stabilizationWindowSeconds: 300 - policies: - - type: Pods - value: 4 - periodSeconds: 60 - - type: Percent - value: 10 - periodSeconds: 60 - selectPolicy: Max ----- -<1> Use the `autoscaling/v2beta2` API. -<2> Specify a name for this horizontal pod autoscaler object. -<3> Specify the API version of the object to scale: -* For a replication controller, use `v1`, -* For a `DeploymentConfig` object, use `apps.openshift.io/v1`. -<4> Specify the kind of object to scale, either `ReplicationController` or `DeploymentConfig`. -<5> Specify the name of the object to scale. The object must exist. -<6> Specify the minimum number of replicas when scaling down. -<7> Specify the maximum number of replicas when scaling up. -<8> Use the `metrics` parameter for memory utilization. -<9> Specify `memory` for memory utilization. -<10> Set the type to `AverageValue`. -<11> Specify `averageValue` and a specific memory value. -<12> Optional: Specify a scaling policy to control the rate of scaling up or down. - -** To scale for a percentage, create a `HorizontalPodAutoscaler` object similar to the following: -+ -.Example output -[source,yaml,options="nowrap"] ----- -apiVersion: autoscaling/v2beta2 <1> -kind: HorizontalPodAutoscaler -metadata: - name: memory-autoscale <2> - namespace: default -spec: - scaleTargetRef: - apiVersion: apps.openshift.io/v1 <3> - kind: DeploymentConfig <4> - name: example <5> - minReplicas: 1 <6> - maxReplicas: 10 <7> - metrics: <8> - - type: Resource - resource: - name: memory <9> - target: - type: Utilization <10> - averageUtilization: 50 <11> - behavior: <12> - scaleUp: - stabilizationWindowSeconds: 180 - policies: - - type: Pods - value: 6 - periodSeconds: 120 - - type: Percent - value: 10 - periodSeconds: 120 - selectPolicy: Max ----- -<1> Use the `autoscaling/v2beta2` API. -<2> Specify a name for this horizontal pod autoscaler object. -<3> Specify the API version of the object to scale: -* For a replication controller, use `v1`, -* For a `DeploymentConfig` object, use `apps.openshift.io/v1`. -<4> Specify the kind of object to scale, either `ReplicationController` or `DeploymentConfig`. -<5> Specify the name of the object to scale. The object must exist. -<6> Specify the minimum number of replicas when scaling down. -<7> Specify the maximum number of replicas when scaling up. -<8> Use the `metrics` parameter for memory utilization. -<9> Specify `memory` for memory utilization. -<10> Set to `Utilization`. -<11> Specify `averageUtilization` and a target average memory utilization over all the pods, -represented as a percent of requested memory. The target pods must have memory requests configured. -<12> Optional: Specify a scaling policy to control the rate of scaling up or down. - -. Create the horizontal pod autoscaler: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f hpa.yaml ----- -+ -.Example output -[source,terminal] ----- -horizontalpodautoscaler.autoscaling/hpa-resource-metrics-memory created ----- - -. Verify that the horizontal pod autoscaler was created: -+ -[source,terminal] ----- -$ oc get hpa hpa-resource-metrics-memory ----- -+ -.Example output -[source,terminal] ----- -NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE -hpa-resource-metrics-memory ReplicationController/example 2441216/500Mi 1 10 1 20m ----- -+ -[source,terminal] ----- -$ oc describe hpa hpa-resource-metrics-memory ----- -+ -.Example output -[source,yaml] ----- -Name: hpa-resource-metrics-memory -Namespace: default -Labels: <none> -Annotations: <none> -CreationTimestamp: Wed, 04 Mar 2020 16:31:37 +0530 -Reference: ReplicationController/example -Metrics: ( current / target ) - resource memory on pods: 2441216 / 500Mi -Min replicas: 1 -Max replicas: 10 -ReplicationController pods: 1 current / 1 desired -Conditions: - Type Status Reason Message - ---- ------ ------ ------- - AbleToScale True ReadyForNewScale recommended size matches current size - ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from memory resource - ScalingLimited False DesiredWithinRange the desired count is within the acceptable range -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal SuccessfulRescale 6m34s horizontal-pod-autoscaler New size: 1; reason: All metrics below target ----- diff --git a/modules/nodes-pods-autoscaling-policies.adoc b/modules/nodes-pods-autoscaling-policies.adoc deleted file mode 100644 index 9407418ea68a..000000000000 --- a/modules/nodes-pods-autoscaling-policies.adoc +++ /dev/null @@ -1,106 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-autoscaling.adoc - -[id="nodes-pods-autoscaling-policies_{context}"] -= Scaling policies - -The `autoscaling/v2beta2` API allows you to add _scaling policies_ to a horizontal pod autoscaler. A scaling policy controls how the {product-title} horizontal pod autoscaler (HPA) scales pods. Scaling policies allow you to restrict the rate that HPAs scale pods up or down by setting a specific number or specific percentage to scale in a specified period of time. You can also define a _stabilization window_, which uses previously computed desired states to control scaling if the metrics are fluctuating. You can create multiple policies for the same scaling direction, and determine which policy is used, based on the amount of change. You can also restrict the scaling by timed iterations. The HPA scales pods during an iteration, then performs scaling, as needed, in further iterations. - -.Sample HPA object with a scaling policy -[source, yaml] ----- -apiVersion: autoscaling/v2beta2 -kind: HorizontalPodAutoscaler -metadata: - name: hpa-resource-metrics-memory - namespace: default -spec: - behavior: - scaleDown: <1> - policies: <2> - - type: Pods <3> - value: 4 <4> - periodSeconds: 60 <5> - - type: Percent - value: 10 <6> - periodSeconds: 60 - selectPolicy: Min <7> - stabilizationWindowSeconds: 300 <8> - scaleUp: <9> - policies: - - type: Pods - value: 5 <10> - periodSeconds: 70 - - type: Percent - value: 12 <11> - periodSeconds: 80 - selectPolicy: Max - stabilizationWindowSeconds: 0 -... ----- -<1> Specifies the direction for the scaling policy, either `scaleDown` or `scaleUp`. This example creates a policy for scaling down. -<2> Defines the scaling policy. -<3> Determines if the policy scales by a specific number of pods or a percentage of pods during each iteration. The default value is `pods`. -<4> Determines the amount of scaling, either the number of pods or percentage of pods, during each iteration. There is no default value for scaling down by number of pods. -<5> Determines the length of a scaling iteration. The default value is `15` seconds. -<6> The default value for scaling down by percentage is 100%. -<7> Determines which policy to use first, if multiple policies are defined. Specify `Max` to use the policy that allows the highest amount of change, `Min` to use the policy that allows the lowest amount of change, or `Disabled` to prevent the HPA from scaling in that policy direction. The default value is `Max`. -<8> Determines the time period the HPA should look back at desired states. The default value is `0`. -<9> This example creates a policy for scaling up. -<10> The amount of scaling up by the number of pods. The default value for scaling up the number of pods is 4%. -<11> The amount of scaling up by the percentage of pods. The default value for scaling up by percentage is 100%. - -.Example policy for scaling down -[source,yaml] ----- -apiVersion: autoscaling/v2beta2 -kind: HorizontalPodAutoscaler -metadata: - name: hpa-resource-metrics-memory - namespace: default -spec: -... - minReplicas: 20 -... - behavior: - scaleDown: - stabilizationWindowSeconds: 300 - policies: - - type: Pods - value: 4 - periodSeconds: 30 - - type: Percent - value: 10 - periodSeconds: 60 - selectPolicy: Max - scaleUp: - selectPolicy: Disabled ----- - -In this example, when the number of pods is greater than 40, the percent-based policy is used for scaling down, as that policy results in a larger change, as required by the `selectPolicy`. - -If there are 80 pod replicas, in the first iteration the HPA reduces the pods by 8, which is 10% of the 80 pods (based on the `type: Percent` and `value: 10` parameters), over one minute (`periodSeconds: 60`). For the next iteration, the number of pods is 72. The HPA calculates that 10% of the remaining pods is 7.2, which it rounds up to 8 and scales down 8 pods. On each subsequent iteration, the number of pods to be scaled is re-calculated based on the number of remaining pods. When the number of pods falls below 40, the pods-based policy is applied, because the pod-based number is greater than the percent-based number. The HPA reduces 4 pods at a time (`type: Pods` and `value: 4`), over 30 seconds (`periodSeconds: 30`), until there are 20 replicas remaining (`minReplicas`). - -The `selectPolicy: Disabled` parameter prevents the HPA from scaling up the pods. You can manually scale up by adjusting the number of replicas in the replica set or deployment set, if needed. - -If set, you can view the scaling policy by using the `oc edit` command: - -[source,terminal] ----- -$ oc edit hpa hpa-resource-metrics-memory ----- - -.Example output -[source,terminal] ----- -apiVersion: autoscaling/v1 -kind: HorizontalPodAutoscaler -metadata: - annotations: - autoscaling.alpha.kubernetes.io/behavior:\ -'{"ScaleUp":{"StabilizationWindowSeconds":0,"SelectPolicy":"Max","Policies":[{"Type":"Pods","Value":4,"PeriodSeconds":15},{"Type":"Percent","Value":100,"PeriodSeconds":15}]},\ -"ScaleDown":{"StabilizationWindowSeconds":300,"SelectPolicy":"Min","Policies":[{"Type":"Pods","Value":4,"PeriodSeconds":60},{"Type":"Percent","Value":10,"PeriodSeconds":60}]}}' -... ----- - diff --git a/modules/nodes-pods-autoscaling-status-about.adoc b/modules/nodes-pods-autoscaling-status-about.adoc deleted file mode 100644 index d86aa13b3333..000000000000 --- a/modules/nodes-pods-autoscaling-status-about.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-autoscaling-about.adoc - -[id="nodes-pods-autoscaling-status-about_{context}"] - -= Understanding horizontal pod autoscaler status conditions - -You can use the status conditions set to determine -whether or not the horizontal pod autoscaler (HPA) is able to scale and whether or not it is currently restricted -in any way. - -The HPA status conditions are available with the `v2beta1` version of the -autoscaling API. - -The HPA responds with the following status conditions: - -* The `AbleToScale` condition indicates whether HPA is able to fetch and update metrics, as well as whether any backoff-related conditions could prevent scaling. -** A `True` condition indicates scaling is allowed. -** A `False` condition indicates scaling is not allowed for the reason specified. - -* The `ScalingActive` condition indicates whether the HPA is enabled (for example, the replica count of the target is not zero) and is able to calculate desired metrics. -** A `True` condition indicates metrics is working properly. -** A `False` condition generally indicates a problem with fetching metrics. - -* The `ScalingLimited` condition indicates that the desired scale was capped by the maximum or minimum of the horizontal pod autoscaler. -** A `True` condition indicates that you need to raise or lower the minimum or maximum replica count in order to scale. -** A `False` condition indicates that the requested scaling is allowed. -+ -[source,terminal] ----- -$ oc describe hpa cm-test ----- -+ -.Example output -[source,yaml] ----- -Name: cm-test -Namespace: prom -Labels: <none> -Annotations: <none> -CreationTimestamp: Fri, 16 Jun 2017 18:09:22 +0000 -Reference: ReplicationController/cm-test -Metrics: ( current / target ) - "http_requests" on pods: 66m / 500m -Min replicas: 1 -Max replicas: 4 -ReplicationController pods: 1 current / 1 desired -Conditions: <1> - Type Status Reason Message - ---- ------ ------ ------- - AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale - ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from pods metric http_request - ScalingLimited False DesiredWithinRange the desired replica count is within the acceptable range -Events: ----- -<1> The horizontal pod autoscaler status messages. - -// The above output and bullets from https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/#appendix-horizontal-pod-autoscaler-status-conditions - -The following is an example of a pod that is unable to scale: - -.Example output -[source,yaml] ----- -Conditions: - Type Status Reason Message - ---- ------ ------ ------- - AbleToScale False FailedGetScale the HPA controller was unable to get the target's current scale: no matches for kind "ReplicationController" in group "apps" -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Warning FailedGetScale 6s (x3 over 36s) horizontal-pod-autoscaler no matches for kind "ReplicationController" in group "apps" ----- - -The following is an example of a pod that could not obtain the needed metrics for scaling: - -.Example output -[source,yaml] ----- -Conditions: - Type Status Reason Message - ---- ------ ------ ------- - AbleToScale True SucceededGetScale the HPA controller was able to get the target's current scale - ScalingActive False FailedGetResourceMetric the HPA was unable to compute the replica count: unable to get metrics for resource cpu: no metrics returned from heapster ----- - -The following is an example of a pod where the requested autoscaling was less than the required minimums: - -.Example output -[source,yaml] ----- -Conditions: - Type Status Reason Message - ---- ------ ------ ------- - AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale - ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from pods metric http_request - ScalingLimited False DesiredWithinRange the desired replica count is within the acceptable range ----- diff --git a/modules/nodes-pods-autoscaling-status-viewing.adoc b/modules/nodes-pods-autoscaling-status-viewing.adoc deleted file mode 100644 index ea14c836d994..000000000000 --- a/modules/nodes-pods-autoscaling-status-viewing.adoc +++ /dev/null @@ -1,91 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-autoscaling-about.adoc - -[id="nodes-pods-autoscaling-status-viewing_{context}"] - -= Viewing horizontal pod autoscaler status conditions - -You can view the status conditions set on a pod by the horizontal pod autoscaler (HPA). - -[NOTE] -==== -The horizontal pod autoscaler status conditions are available with the `v2beta1` version of the -autoscaling API. -==== - -.Prerequisites - -To use horizontal pod autoscalers, your cluster administrator must have properly configured cluster metrics. -You can use the `oc describe PodMetrics <pod-name>` command to determine if metrics are configured. If metrics are -configured, the output appears similar to the following, with `Cpu` and `Memory` displayed under `Usage`. - -[source,terminal] ----- -$ oc describe PodMetrics openshift-kube-scheduler-ip-10-0-135-131.ec2.internal ----- - -.Example output -[source,terminal] ----- -Name: openshift-kube-scheduler-ip-10-0-135-131.ec2.internal -Namespace: openshift-kube-scheduler -Labels: <none> -Annotations: <none> -API Version: metrics.k8s.io/v1beta1 -Containers: - Name: wait-for-host-port - Usage: - Memory: 0 - Name: scheduler - Usage: - Cpu: 8m - Memory: 45440Ki -Kind: PodMetrics -Metadata: - Creation Timestamp: 2019-05-23T18:47:56Z - Self Link: /apis/metrics.k8s.io/v1beta1/namespaces/openshift-kube-scheduler/pods/openshift-kube-scheduler-ip-10-0-135-131.ec2.internal -Timestamp: 2019-05-23T18:47:56Z -Window: 1m0s -Events: <none> ----- - -.Procedure - -To view the status conditions on a pod, use the following command with the name of the pod: - -[source,terminal] ----- -$ oc describe hpa <pod-name> ----- - -For example: - -[source,terminal] ----- -$ oc describe hpa cm-test ----- - -The conditions appear in the `Conditions` field in the output. - -.Example output -[source,terminal] ----- -Name: cm-test -Namespace: prom -Labels: <none> -Annotations: <none> -CreationTimestamp: Fri, 16 Jun 2017 18:09:22 +0000 -Reference: ReplicationController/cm-test -Metrics: ( current / target ) - "http_requests" on pods: 66m / 500m -Min replicas: 1 -Max replicas: 4 -ReplicationController pods: 1 current / 1 desired -Conditions: <1> - Type Status Reason Message - ---- ------ ------ ------- - AbleToScale True ReadyForNewScale the last scale time was sufficiently old as to warrant a new scale - ScalingActive True ValidMetricFound the HPA was able to successfully calculate a replica count from pods metric http_request - ScalingLimited False DesiredWithinRange the desired replica count is within the acceptable range ----- diff --git a/modules/nodes-pods-configuring-bandwidth.adoc b/modules/nodes-pods-configuring-bandwidth.adoc deleted file mode 100644 index 3c3776e041cb..000000000000 --- a/modules/nodes-pods-configuring-bandwidth.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-configuring.adoc -// * nodes/nodes-cluster-pods-configuring - -[id="nodes-pods-configuring-bandwidth_{context}"] -= Limiting the bandwidth available to pods - -You can apply quality-of-service traffic shaping to a pod and effectively limit -its available bandwidth. Egress traffic (from the pod) is handled by policing, -which simply drops packets in excess of the configured rate. Ingress traffic (to -the pod) is handled by shaping queued packets to effectively handle data. The -limits you place on a pod do not affect the bandwidth of other pods. - -.Procedure - -To limit the bandwidth on a pod: - -. Write an object definition JSON file, and specify the data traffic speed using -`kubernetes.io/ingress-bandwidth` and `kubernetes.io/egress-bandwidth` -annotations. For example, to limit both pod egress and ingress bandwidth to 10M/s: -+ -.Limited Pod Object Definition -[source,json] ----- -{ - "kind": "Pod", - "spec": { - "containers": [ - { - "image": "openshift/hello-openshift", - "name": "hello-openshift" - } - ] - }, - "apiVersion": "v1", - "metadata": { - "name": "iperf-slow", - "annotations": { - "kubernetes.io/ingress-bandwidth": "10M", - "kubernetes.io/egress-bandwidth": "10M" - } - } -} ----- - -. Create the pod using the object definition: -+ -[source,terminal] ----- -$ oc create -f <file_or_dir_path> ----- diff --git a/modules/nodes-pods-configuring-pod-critical.adoc b/modules/nodes-pods-configuring-pod-critical.adoc deleted file mode 100644 index 4efb6db55cd6..000000000000 --- a/modules/nodes-pods-configuring-pod-critical.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-configuring.adoc -// * nodes/nodes-cluster-pods-configuring - -[id="nodes-pods-configuring-critical_{context}"] -= Preventing pod removal using critical pods - -There are a number of core components that are critical to a fully functional cluster, -but, run on a regular cluster node rather than the master. A cluster might stop working properly if a critical add-on is evicted. - -Pods marked as critical are not allowed to be evicted. - -.Procedure - -To make a pod critical: - -. Create a `Pod` spec or edit existing pods to include the `system-cluster-critical` priority class: -+ -[source,yaml] ----- -spec: - template: - metadata: - name: critical-pod - priorityClassName: system-cluster-critical <1> ----- -<1> Default priority class for pods that should never be evicted from a node. -+ -Alternatively, you can specify `system-node-critical` for pods that are important to the cluster -but can be removed if necessary. - -. Create the pod: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- diff --git a/modules/nodes-pods-configuring-restart.adoc b/modules/nodes-pods-configuring-restart.adoc deleted file mode 100644 index 74d6e96cc54c..000000000000 --- a/modules/nodes-pods-configuring-restart.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-configuring.adoc -// * nodes/nodes-cluster-pods-configuring - -[id="nodes-pods-configuring-restart_{context}"] -= Configuring how pods behave after restart - -A pod restart policy determines how {product-title} responds when Containers in that pod exit. -The policy applies to all Containers in that pod. - -The possible values are: - -* `Always` - Tries restarting a successfully exited Container on the pod continuously, with an exponential back-off delay (10s, 20s, 40s) until the pod is restarted. The default is `Always`. -* `OnFailure` - Tries restarting a failed Container on the pod with an exponential back-off delay (10s, 20s, 40s) capped at 5 minutes. -* `Never` - Does not try to restart exited or failed Containers on the pod. Pods immediately fail and exit. - -After the pod is bound to a node, the pod will never be bound to another node. This means that a controller is necessary in order for a pod to survive node failure: - -[cols="3",options="header"] -|=== - -|Condition -|Controller Type -|Restart Policy - -|Pods that are expected to terminate (such as batch computations) -|Job -|`OnFailure` or `Never` - -|Pods that are expected to not terminate (such as web servers) -|Replication controller -| `Always`. - -|Pods that must run one-per-machine -|Daemon set -|Any -|=== - -If a Container on a pod fails and the restart policy is set to `OnFailure`, the pod stays on the node and the Container is restarted. If you do not want the Container to -restart, use a restart policy of `Never`. - -If an entire pod fails, {product-title} starts a new pod. Developers must address the possibility that applications might be restarted in a new pod. In particular, -applications must handle temporary files, locks, incomplete output, and so forth caused by previous runs. - -[NOTE] -==== -Kubernetes architecture expects reliable endpoints from cloud providers. When a cloud provider is down, the kubelet prevents {product-title} from restarting. - -If the underlying cloud provider endpoints are not reliable, do not install a cluster using cloud provider integration. Install the cluster as if it was in a no-cloud environment. It is not recommended to toggle cloud provider integration on or off in an installed cluster. -==== - -For details on how {product-title} uses restart policy with failed Containers, see -the link:https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#example-states[Example States] in the Kubernetes documentation. diff --git a/modules/nodes-pods-configuring-run-once.adoc b/modules/nodes-pods-configuring-run-once.adoc deleted file mode 100644 index cfcdfb9f0e4d..000000000000 --- a/modules/nodes-pods-configuring-run-once.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-configuring.adoc -// * nodes/nodes-cluster-pods-configuring - -[id="nodes-pods-configuring-run-once_{context}"] -= Limiting the duration of run-once pods - -{product-title} relies on run-once pods to perform tasks such as deploying a pod -or performing a build. Run-once pods are pods that have a `RestartPolicy` of -`Never` or `OnFailure`. - -The cluster administrator can use the `RunOnceDuration` admission control -plug-in to force a limit on the time that those run-once pods can be active. -Once the time limit expires, the cluster will try to actively terminate those -pods. The main reason to have such a limit is to prevent tasks such as builds to -run for an excessive amount of time. - -The plug-in configuration should include the default active deadline for -run-once pods. This deadline is enforced globally, but can be superseded on -a per-project basis. - -.Procedure - -To install the `RunOnceDuration` admission controller: - -. Create an *AdmissionConfiguration* object that references the file: -+ -[source,yaml] ----- -kind: AdmissionConfiguration -apiVersion: apiserver.k8s.io/v1alpha1 -plugins: -- name: RunOnceDurationConfig - activeDeadlineSecondsOverride: 3600 <1> ----- - -<1> Specify the global default for run-once pods in seconds. - - diff --git a/modules/nodes-pods-daemonsets-creating.adoc b/modules/nodes-pods-daemonsets-creating.adoc deleted file mode 100644 index e2d2acdf7005..000000000000 --- a/modules/nodes-pods-daemonsets-creating.adoc +++ /dev/null @@ -1,131 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-daemonsets.adoc - -[id="nodes-pods-daemonsets-creating_{context}"] -= Creating daemonsets - -When creating daemon sets, the `nodeSelector` field is used to indicate the -nodes on which the daemon set should deploy replicas. - -.Prerequisites - -* Before you start using daemon sets, disable the default project-wide node selector -in your namespace, by setting the namespace annotation `openshift.io/node-selector` to an empty string: -+ -[source,terminal] ----- -$ oc patch namespace myproject -p \ - '{"metadata": {"annotations": {"openshift.io/node-selector": ""}}}' ----- - -* If you are creating a new project, overwrite the default node selector: -+ -[source,terminal] ----- -`oc adm new-project <name> --node-selector=""`. ----- - -.Procedure - -To create a daemon set: - -. Define the daemon set yaml file: -+ -[source,yaml] ----- -apiVersion: apps/v1 -kind: DaemonSet -metadata: - name: hello-daemonset -spec: - selector: - matchLabels: - name: hello-daemonset <1> - template: - metadata: - labels: - name: hello-daemonset <2> - spec: - nodeSelector: <3> - role: worker - containers: - - image: openshift/hello-openshift - imagePullPolicy: Always - name: registry - ports: - - containerPort: 80 - protocol: TCP - resources: {} - terminationMessagePath: /dev/termination-log - serviceAccount: default - terminationGracePeriodSeconds: 10 ----- -<1> The label selector that determines which pods belong to the daemon set. -<2> The pod template's label selector. Must match the label selector above. -<3> The node selector that determines on which nodes pod replicas should be deployed. -A matching label must be present on the node. - -. Create the daemon set object: -+ -[source,terminal] ----- -$ oc create -f daemonset.yaml ----- - -. To verify that the pods were created, and that each node has a pod replica: -+ -.. Find the daemonset pods: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] ----- -hello-daemonset-cx6md 1/1 Running 0 2m -hello-daemonset-e3md9 1/1 Running 0 2m ----- -+ -.. View the pods to verify the pod has been placed onto the node: -+ -[source,terminal] ----- -$ oc describe pod/hello-daemonset-cx6md|grep Node ----- -+ -.Example output -[source,terminal] ----- -Node: openshift-node01.hostname.com/10.14.20.134 ----- -+ -[source,terminal] ----- -$ oc describe pod/hello-daemonset-e3md9|grep Node ----- -+ -.Example output -[source,terminal] ----- -Node: openshift-node02.hostname.com/10.14.20.137 ----- - -[IMPORTANT] -==== -* If you update a daemon set pod template, the existing pod -replicas are not affected. - -* If you delete a daemon set and then create a new daemon set -with a different template but the same label selector, it recognizes any -existing pod replicas as having matching labels and thus does not update them or -create new replicas despite a mismatch in the pod template. - -* If you change node labels, the daemon set adds pods to nodes that match the new labels and deletes pods -from nodes that do not match the new labels. - -To update a daemon set, force new pod replicas to be created by deleting the old -replicas or nodes. -==== diff --git a/modules/nodes-pods-plugins-about.adoc b/modules/nodes-pods-plugins-about.adoc deleted file mode 100644 index 7189f664def5..000000000000 --- a/modules/nodes-pods-plugins-about.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-plugin.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-pods-plugins-about_{context}"] -= Understanding device plug-ins - -The device plug-in provides a consistent and portable solution to consume hardware -devices across clusters. The device plug-in provides support for these devices -through an extension mechanism, which makes these devices available to -Containers, provides health checks of these devices, and securely shares them. - -[IMPORTANT] -==== -{product-title} supports the device plug-in API, but the device plug-in -Containers are supported by individual vendors. -==== - -A device plug-in is a gRPC service running on the nodes (external to -the `kubelet`) that is responsible for managing specific -hardware resources. Any device plug-in must support following remote procedure -calls (RPCs): - -[source,golang] ----- -service DevicePlugin { - // GetDevicePluginOptions returns options to be communicated with Device - // Manager - rpc GetDevicePluginOptions(Empty) returns (DevicePluginOptions) {} - - // ListAndWatch returns a stream of List of Devices - // Whenever a Device state change or a Device disappears, ListAndWatch - // returns the new list - rpc ListAndWatch(Empty) returns (stream ListAndWatchResponse) {} - - // Allocate is called during container creation so that the Device - // Plug-in can run device specific operations and instruct Kubelet - // of the steps to make the Device available in the container - rpc Allocate(AllocateRequest) returns (AllocateResponse) {} - - // PreStartcontainer is called, if indicated by Device Plug-in during - // registration phase, before each container start. Device plug-in - // can run device specific operations such as reseting the device - // before making devices available to the container - rpc PreStartcontainer(PreStartcontainerRequest) returns (PreStartcontainerResponse) {} -} ----- - -[discrete] -=== Example device plug-ins -* link:https://github.com/GoogleCloudPlatform/Container-engine-accelerators/tree/master/cmd/nvidia_gpu[Nvidia GPU device plug-in for COS-based operating system] -* link:https://github.com/NVIDIA/k8s-device-plugin[Nvidia official GPU device plug-in] -* link:https://github.com/vikaschoudhary16/sfc-device-plugin[Solarflare device plug-in] -* link:https://github.com/kubevirt/kubernetes-device-plugins[KubeVirt device plug-ins: vfio and kvm] - - -[NOTE] -==== -For easy device plug-in reference implementation, there is a stub device plug-in -in the Device Manager code: -*_vendor/k8s.io/kubernetes/pkg/kubelet/cm/deviceplugin/device_plugin_stub.go_*. -==== - -== Methods for deploying a device plug-in - -* Daemon sets are the recommended approach for device plug-in deployments. -* Upon start, the device plug-in will try to create a UNIX domain socket at -*_/var/lib/kubelet/device-plugin/_* on the node to serve RPCs from Device Manager. -* Since device plug-ins must manage hardware resources, access to the host -file system, as well as socket creation, they must be run in a privileged -security context. -* More specific details regarding deployment steps can be found with each device -plug-in implementation. diff --git a/modules/nodes-pods-plugins-device-mgr.adoc b/modules/nodes-pods-plugins-device-mgr.adoc deleted file mode 100644 index 95202dab60ae..000000000000 --- a/modules/nodes-pods-plugins-device-mgr.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-plugins.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-pods-plugins-device-mgr_{context}"] -= Understanding the Device Manager - -Device Manager provides a mechanism for advertising specialized node hardware resources -with the help of plug-ins known as device plug-ins. - -You can advertise specialized hardware without requiring any upstream code changes. - -[IMPORTANT] -==== -{product-title} supports the device plug-in API, but the device plug-in -Containers are supported by individual vendors. -==== - -Device Manager advertises devices as *Extended Resources*. User pods can consume -devices, advertised by Device Manager, using the same *Limit/Request* mechanism, -which is used for requesting any other *Extended Resource*. - -Upon start, the device plug-in registers itself with Device Manager invoking `Register` on the -*_/var/lib/kubelet/device-plugins/kubelet.sock_* and starts a gRPC service at -*_/var/lib/kubelet/device-plugins/<plugin>.sock_* for serving Device Manager -requests. - -Device Manager, while processing a new registration request, invokes -`ListAndWatch` remote procedure call (RPC) at the device plug-in service. In -response, Device Manager gets a list of *Device* objects from the plug-in over a -gRPC stream. Device Manager will keep watching on the stream for new updates -from the plug-in. On the plug-in side, the plug-in will also keep the stream -open and whenever there is a change in the state of any of the devices, a new -device list is sent to the Device Manager over the same streaming connection. - -While handling a new pod admission request, Kubelet passes requested `Extended -Resources` to the Device Manager for device allocation. Device Manager checks in -its database to verify if a corresponding plug-in exists or not. If the plug-in exists -and there are free allocatable devices as well as per local cache, `Allocate` -RPC is invoked at that particular device plug-in. - -Additionally, device plug-ins can also perform several other device-specific -operations, such as driver installation, device initialization, and device -resets. These functionalities vary from implementation to implementation. diff --git a/modules/nodes-pods-plugins-install.adoc b/modules/nodes-pods-plugins-install.adoc deleted file mode 100644 index 1c3c40c2388e..000000000000 --- a/modules/nodes-pods-plugins-install.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-plugins.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-pods-plugins-install_{context}"] -= Enabling Device Manager - -Enable Device Manager to implement a device plug-in to advertise specialized -hardware without any upstream code changes. - -Device Manager provides a mechanism for advertising specialized node hardware resources -with the help of plug-ins known as device plug-ins. - -. Obtain the label associated with the static `MachineConfigPool` CRD for the type of node you want to configure. -Perform one of the following steps: - -.. View the machine config: -+ -[source,terminal] ----- -# oc describe machineconfig <name> ----- -+ -For example: -+ -[source,terminal] ----- -# oc describe machineconfig 00-worker ----- -+ -.Example output -[source,terminal] ----- -Name: 00-worker -Namespace: -Labels: machineconfiguration.openshift.io/role=worker <1> ----- -<1> Label required for the Device Manager. - -.Procedure - -. Create a custom resource (CR) for your configuration change. -+ -.Sample configuration for a Device Manager CR -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: devicemgr <1> -spec: - machineConfigPoolSelector: - matchLabels: - machineconfiguration.openshift.io: devicemgr <2> - kubeletConfig: - feature-gates: - - DevicePlugins=true <3> ----- -<1> Assign a name to CR. -<2> Enter the label from the Machine Config Pool. -<3> Set `DevicePlugins` to 'true`. - -. Create the Device Manager: -+ -[source,terminal] ----- -$ oc create -f devicemgr.yaml ----- -+ -.Example output -[source,terminal] ----- -kubeletconfig.machineconfiguration.openshift.io/devicemgr created ----- - -. Ensure that Device Manager was actually enabled by confirming that -*_/var/lib/kubelet/device-plugins/kubelet.sock_* is created on the node. This is -the UNIX domain socket on which the Device Manager gRPC server listens for new -plug-in registrations. This sock file is created when the Kubelet is started -only if Device Manager is enabled. diff --git a/modules/nodes-pods-pod-disruption-about.adoc b/modules/nodes-pods-pod-disruption-about.adoc deleted file mode 100644 index 9701d6c199c7..000000000000 --- a/modules/nodes-pods-pod-disruption-about.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-configuring.adoc -// * nodes/nodes-cluster-pods-configuring -// * post_installation_configuration/cluster-tasks.adoc - -[id="nodes-pods-configuring-pod-distruption-about_{context}"] -= Understanding how to use pod disruption budgets to specify the number of pods that must be up - -A _pod disruption budget_ is part of the -link:http://kubernetes.io/docs/admin/disruptions/[Kubernetes] API, which can be -managed with `oc` commands like other object types. They -allow the specification of safety constraints on pods during operations, such as -draining a node for maintenance. - -`PodDisruptionBudget` is an API object that specifies the minimum number or -percentage of replicas that must be up at a time. Setting these in projects can -be helpful during node maintenance (such as scaling a cluster down or a cluster -upgrade) and is only honored on voluntary evictions (not on node failures). - -A `PodDisruptionBudget` object's configuration consists of the following key -parts: - -* A label selector, which is a label query over a set of pods. -* An availability level, which specifies the minimum number of pods that must be - available simultaneously, either: -** `minAvailable` is the number of pods must always be available, even during a disruption. -** `maxUnavailable` is the number of pods can be unavailable during a disruption. - -[NOTE] -==== -A `maxUnavailable` of `0%` or `0` or a `minAvailable` of `100%` or equal to the number of replicas -is permitted but can block nodes from being drained. -==== - -You can check for pod disruption budgets across all projects with the following: - -[source,terminal] ----- -$ oc get poddisruptionbudget --all-namespaces ----- - -.Example output -[source,terminal] ----- -NAMESPACE NAME MIN-AVAILABLE SELECTOR -another-project another-pdb 4 bar=foo -test-project my-pdb 2 foo=bar ----- - -The `PodDisruptionBudget` is considered healthy when there are at least -`minAvailable` pods running in the system. Every pod above that limit can be evicted. - -[NOTE] -==== -Depending on your pod priority and preemption settings, -lower-priority pods might be removed despite their pod disruption budget requirements. -==== diff --git a/modules/nodes-pods-pod-disruption-configuring.adoc b/modules/nodes-pods-pod-disruption-configuring.adoc deleted file mode 100644 index 8f8e0f11f7fc..000000000000 --- a/modules/nodes-pods-pod-disruption-configuring.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-configuring.adoc -// * nodes/nodes-cluster-pods-configuring -// * post_installation_configuration/cluster-tasks.adoc - -[id="nodes-pods-pod-disruption-configuring_{context}"] -= Specifying the number of pods that must be up with pod disruption budgets - -You can use a `PodDisruptionBudget` object to specify the minimum number or -percentage of replicas that must be up at a time. - -.Procedure - -To configure a pod disruption budget: - -. Create a YAML file with the an object definition similar to the following: -+ -[source,yaml] ----- -apiVersion: policy/v1beta1 <1> -kind: PodDisruptionBudget -metadata: - name: my-pdb -spec: - minAvailable: 2 <2> - selector: <3> - matchLabels: - foo: bar ----- -<1> `PodDisruptionBudget` is part of the `policy/v1beta1` API group. -<2> The minimum number of pods that must be available simultaneously. This can -be either an integer or a string specifying a percentage, for example, `20%`. -<3> A label query over a set of resources. The result of `matchLabels` and - `matchExpressions` are logically conjoined. -+ -Or: -+ -[source,yaml] ----- -apiVersion: policy/v1beta1 <1> -kind: PodDisruptionBudget -metadata: - name: my-pdb -spec: - maxUnavailable: 25% <2> - selector: <3> - matchLabels: - foo: bar ----- -<1> `PodDisruptionBudget` is part of the `policy/v1beta1` API group. -<2> The maximum number of pods that can be unavailable simultaneously. This can -be either an integer or a string specifying a percentage, for example, `20%`. -<3> A label query over a set of resources. The result of `matchLabels` and - `matchExpressions` are logically conjoined. - -. Run the following command to add the object to project: -+ -[source,terminal] ----- -$ oc create -f </path/to/file> -n <project_name> ----- diff --git a/modules/nodes-pods-priority-about.adoc b/modules/nodes-pods-priority-about.adoc deleted file mode 100644 index 049a3bd334e2..000000000000 --- a/modules/nodes-pods-priority-about.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-priority.adoc - -[id="nodes-pods-priority-about_{context}"] -= Understanding pod priority - -When you use the Pod Priority and Preemption feature, the scheduler orders pending pods by their priority, and a pending pod is placed ahead of other pending pods with lower priority in the scheduling queue. As a result, the higher priority pod might be scheduled sooner than pods with lower priority if its scheduling requirements are met. If a pod cannot be scheduled, scheduler continues to schedule other lower priority pods. - -[id="admin-guide-priority-preemption-priority-class_{context}"] -== Pod priority classes - -You can assign pods a priority class, which is a non-namespaced object that defines a mapping from a name to the integer value of the priority. The higher the value, the higher the priority. - -A priority class object can take any 32-bit integer value smaller than or equal to 1000000000 (one billion). Reserve numbers larger than one billion for critical pods that should not be preempted or evicted. By default, {product-title} has two reserved priority classes for critical system pods to have guaranteed scheduling. - -[source,terminal] ----- -$ oc get priorityclasses ----- - -.Example output -[source,terminal] ----- -NAME VALUE GLOBAL-DEFAULT AGE -cluster-logging 1000000 false 29s -system-cluster-critical 2000000000 false 72m -system-node-critical 2000001000 false 72m ----- - -* *system-node-critical* - This priority class has a value of 2000001000 and is used for all pods that should never be evicted from a node. Examples of pods that have this priority class are `sdn-ovs`, `sdn`, and so forth. A number of critical components include the `system-node-critical` priority class by default, for example: -+ -** master-api -** master-controller -** master-etcd -** sdn -** sdn-ovs -** sync - -* *system-cluster-critical* - This priority class has a value of 2000000000 (two billion) and is used with pods that are important for the cluster. Pods with this priority class can be evicted from a node in certain circumstances. For example, pods configured with the `system-node-critical` priority class can take priority. However, this priority class does ensure guaranteed scheduling. Examples of pods that can have this priority class are fluentd, add-on components like descheduler, and so forth. -A number of critical components include the `system-cluster-critical` priority class by default, for example: -+ -** fluentd -** metrics-server -** descheduler - -* *cluster-logging* - This priority is used by Fluentd to make sure Fluentd pods are scheduled to nodes over other apps. - -[NOTE] -==== -If you upgrade your existing cluster, the priority of your existing pods is effectively zero. However, existing pods with -the `scheduler.alpha.kubernetes.io/critical-pod` annotation are automatically converted to `system-cluster-critical` class. -Fluentd OpenShift Logging pods with the annotation are converted to the `cluster-logging` priority class. -==== - -[id="admin-guide-priority-preemption-names_{context}"] -== Pod priority names - -After you have one or more priority classes, you can create pods that specify a priority class name in a `Pod` spec. The priority admission controller uses the priority class name field to populate the integer value of the priority. If the named priority class is not found, the pod is rejected. diff --git a/modules/nodes-pods-priority-configuring.adoc b/modules/nodes-pods-priority-configuring.adoc deleted file mode 100644 index 2d58d269b0bb..000000000000 --- a/modules/nodes-pods-priority-configuring.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-priority.adoc - -[id="nodes-pods-priority-configuring_{context}"] -= Configuring priority and preemption - -You apply pod priority and preemption by creating a priority class object and associating pods to the priority using the -`priorityClassName` in your `Pod` specs. - -.Sample priority class object -[source,yaml] ----- -apiVersion: scheduling.k8s.io/v1 -kind: PriorityClass -metadata: - name: high-priority <1> -value: 1000000 <2> -preemptionPolicy: PreemptLowerPriority <3> -globalDefault: false <4> -description: "This priority class should be used for XYZ service pods only." <5> ----- -<1> The name of the priority class object. -<2> The priority value of the object. -<3> Optional field that indicates whether this priority class is preempting or non-preempting. The preemption policy defaults to `PreemptLowerPriority`, which allows pods of that priority class to preempt lower-priority pods. If the preemption policy is set to `Never`, pods in that priority class are non-preempting. -<4> Optional field that indicates whether this priority class should be used for pods without a priority class name specified. This field is `false` by default. Only one priority class with `globalDefault` set to `true` can exist in the cluster. If there is no priority class with `globalDefault:true`, the priority of pods with no priority class name is zero. Adding a priority class with `globalDefault:true` affects only pods created after the priority class is added and does not change the priorities of existing pods. -<5> Optional arbitrary text string that describes which pods developers should use with this priority class. - -.Procedure - -To configure your cluster to use priority and preemption: - -. Create one or more priority classes: - -.. Specify a name and value for the priority. - -.. Optionally specify the `globalDefault` field in the priority class and a description. - -. Create a `Pod` spec or edit existing pods to include the name of a priority class, similar to the following: -+ -.Sample `Pod` spec with priority class name -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: nginx - labels: - env: test -spec: - containers: - - name: nginx - image: nginx - imagePullPolicy: IfNotPresent - priorityClassName: high-priority <1> ----- -<1> Specify the priority class to use with this pod. - -. Create the pod: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -You can add the priority name directly to the pod configuration or to a pod template. diff --git a/modules/nodes-pods-priority-preempt-about.adoc b/modules/nodes-pods-priority-preempt-about.adoc deleted file mode 100644 index 0b07296107e7..000000000000 --- a/modules/nodes-pods-priority-preempt-about.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-priority.adoc - -[id="nodes-pods-priority-preempt-about_{context}"] -= Understanding pod preemption - -When a developer creates a pod, the pod goes into a queue. If the developer configured the pod for pod priority or preemption, the scheduler picks a pod from the queue and tries to schedule the pod on a node. If the scheduler cannot find space on an appropriate node that satisfies all the specified requirements of the pod, preemption logic is triggered for the pending pod. - -When the scheduler preempts one or more pods on a node, the `nominatedNodeName` field of higher-priority `Pod` spec is set to the name of the node, along with the `nodename` field. The scheduler uses the `nominatedNodeName` field to keep track of the resources reserved for pods and also provides information to the user about preemptions in the clusters. - -After the scheduler preempts a lower-priority pod, the scheduler honors the graceful termination period of the pod. If another node becomes available while scheduler is waiting for the lower-priority pod to terminate, the scheduler can schedule the higher-priority pod on that node. As a result, the `nominatedNodeName` field and `nodeName` field of the `Pod` spec might be different. - -Also, if the scheduler preempts pods on a node and is waiting for termination, and a pod with a higher-priority pod than the pending pod needs to be scheduled, the scheduler can schedule the higher-priority pod instead. In such a case, the scheduler clears the `nominatedNodeName` of the pending pod, making the pod eligible for another node. - -Preemption does not necessarily remove all lower-priority pods from a node. The scheduler can schedule a pending pod by removing a portion of the lower-priority pods. - -The scheduler considers a node for pod preemption only if the pending pod can be scheduled on the node. - -[id="non-preempting-priority-class_{context}"] -== Non-preempting priority classes (Technology Preview) - -Pods with the preemption policy set to `Never` are placed in the scheduling queue ahead of lower-priority pods, but they cannot preempt other pods. A non-preempting pod waiting to be scheduled stays in the scheduling queue until sufficient resources are free and it can be scheduled. Non-preempting pods, like other pods, are subject to scheduler back-off. This means that if the scheduler tries unsuccessfully to schedule these pods, they are retried with lower frequency, allowing other pods with lower priority to be scheduled before them. - -Non-preempting pods can still be preempted by other, high-priority pods. - -[id="priority-preemption-other_{context}"] -== Pod preemption and other scheduler settings - -If you enable pod priority and preemption, consider your other scheduler settings: - -Pod priority and pod disruption budget:: -A pod disruption budget specifies the minimum number or percentage of replicas that must be up at a time. If you specify pod disruption budgets, {product-title} respects them when preempting pods at a best effort level. The scheduler attempts to preempt pods without violating the pod disruption budget. If no such pods are found, lower-priority pods might be preempted despite their pod disruption budget requirements. - -Pod priority and pod affinity:: -Pod affinity requires a new pod to be scheduled on the same node as other pods with the same label. - -If a pending pod has inter-pod affinity with one or more of the lower-priority pods on a node, the scheduler cannot preempt the lower-priority pods without violating the affinity requirements. In this case, the scheduler looks for another node to schedule the pending pod. However, there is no guarantee that the scheduler can find an appropriate node and pending pod might not be scheduled. - -To prevent this situation, carefully configure pod affinity with equal-priority pods. - -//// -Under consideration for future release -Pod priority and cross-node preemption:: -If the scheduler is considering preempting pods on a node so that a pending pod can be scheduled, the scheduler can preempt a pod on different node to schedule the pending pod. -//// - -[id="priority-preemption-graceful_{context}"] -== Graceful termination of preempted pods - -When preempting a pod, the scheduler waits for the pod graceful termination period to expire, allowing the pod to finish working and exit. If the pod does not exit after the period, the scheduler kills the pod. This graceful termination period creates a time gap between the point that the scheduler preempts the pod and the time when the pending pod can be scheduled on the node. - -To minimize this gap, configure a small graceful termination period for lower-priority pods. diff --git a/modules/nodes-pods-secrets-about.adoc b/modules/nodes-pods-secrets-about.adoc deleted file mode 100644 index de42c6630555..000000000000 --- a/modules/nodes-pods-secrets-about.adoc +++ /dev/null @@ -1,179 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-secrets.adoc - -[id="nodes-pods-secrets-about_{context}"] -= Understanding secrets - -The `Secret` object type provides a mechanism to hold sensitive information such -as passwords, {product-title} client configuration files, -private source repository credentials, and so on. Secrets decouple sensitive -content from the pods. You can mount secrets into containers using a volume -plug-in or the system can use secrets to perform actions on behalf of a pod. - -Key properties include: - -- Secret data can be referenced independently from its definition. -- Secret data volumes are backed by temporary file-storage facilities (tmpfs) and never come to rest on a node. -- Secret data can be shared within a namespace. - -.YAML `Secret` object definition - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: test-secret - namespace: my-namespace -type: Opaque <1> -data: <2> - username: dmFsdWUtMQ0K <3> - password: dmFsdWUtMg0KDQo= -stringData: <4> - hostname: myapp.mydomain.com <5> ----- -<1> Indicates the structure of the secret’s key names and values. -<2> The allowable format for the keys in the `data` field must meet the -guidelines in the *DNS_SUBDOMAIN* value in -link:https://github.com/kubernetes/kubernetes/blob/v1.0.0/docs/design/identifiers.md[the -Kubernetes identifiers glossary]. -<3> The value associated with keys in the `data` map must be base64 encoded. -<4> Entries in the `stringData` map are converted to base64 -and the entry will then be moved to the `data` map automatically. This field -is write-only; the value will only be returned via the `data` field. -<5> The value associated with keys in the `stringData` map is made up of -plain text strings. - -You must create a secret before creating the pods that depend on that secret. - -When creating secrets: - -- Create a secret object with secret data. -- Update the pod's service account to allow the reference to the secret. -- Create a pod, which consumes the secret as an environment variable or as a file -(using a `secret` volume). - - -[id="nodes-pods-secrets-about-types_{context}"] -== Types of secrets - -The value in the `type` field indicates the structure of the secret's key names and values. The type can be used to -enforce the presence of user names and keys in the secret object. If you do not want validation, use the `opaque` type, -which is the default. - -Specify one of the following types to trigger minimal server-side validation to ensure the presence of specific key names in the secret data: - -* `kubernetes.io/service-account-token`. Uses a service account token. -* `kubernetes.io/basic-auth`. Use with Basic Authentication. -* `kubernetes.io/ssh-auth`. Use with SSH Key Authentication. -* `kubernetes.io/tls`. Use with TLS certificate authorities. - -Specify `type: Opaque` if you do not want validation, which means the secret does not claim to conform to any convention for key names or values. -An _opaque_ secret, allows for unstructured `key:value` pairs that can contain arbitrary values. - -[NOTE] -==== -You can specify other arbitrary types, such as `example.com/my-secret-type`. These types are not enforced server-side, -but indicate that the creator of the secret intended to conform to the key/value requirements of that type. -==== - -For examples of different secret types, see the code samples in _Using Secrets_. - -[id="nodes-pods-secrets-about-examples_{context}"] -== Example secret configurations - -The following are sample secret configuration files. - -.YAML `Secret` object that creates four files - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: test-secret -data: - username: dmFsdWUtMQ0K <1> - password: dmFsdWUtMQ0KDQo= <2> -stringData: - hostname: myapp.mydomain.com <3> - secret.properties: |- <4> - property1=valueA - property2=valueB ----- -<1> File contains decoded values. -<2> File contains decoded values. -<3> File contains the provided string. -<4> File contains the provided data. - -.YAML of a pod populating files in a volume with secret data - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: secret-example-pod -spec: - containers: - - name: secret-test-container - image: busybox - command: [ "/bin/sh", "-c", "cat /etc/secret-volume/*" ] - volumeMounts: - # name must match the volume name below - - name: secret-volume - mountPath: /etc/secret-volume - readOnly: true - volumes: - - name: secret-volume - secret: - secretName: test-secret - restartPolicy: Never ----- - -.YAML of a pod populating environment variables with secret data - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: secret-example-pod -spec: - containers: - - name: secret-test-container - image: busybox - command: [ "/bin/sh", "-c", "export" ] - env: - - name: TEST_SECRET_USERNAME_ENV_VAR - valueFrom: - secretKeyRef: - name: test-secret - key: username - restartPolicy: Never ----- - -.YAML of a build config populating environment variables with secret data - -[source,yaml] ----- -apiVersion: v1 -kind: BuildConfig -metadata: - name: secret-example-bc -spec: - strategy: - sourceStrategy: - env: - - name: TEST_SECRET_USERNAME_ENV_VAR - valueFrom: - secretKeyRef: - name: test-secret - key: username ----- - -[id="nodes-pods-secrets-about-keys_{context}"] -== Secret data keys - -Secret keys must be in a DNS subdomain. diff --git a/modules/nodes-pods-secrets-certificates-about.adoc b/modules/nodes-pods-secrets-certificates-about.adoc deleted file mode 100644 index 1de2a54603c6..000000000000 --- a/modules/nodes-pods-secrets-certificates-about.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-secrets.adoc - -[id="nodes-pods-secrets-certificates-about_{context}"] -= About using signed certificates with secrets - -To secure communication to your service, you can configure {product-title} to generate a signed -serving certificate/key pair that you can add into a secret in a project. - -A _service serving certificate secret_ is intended to support complex middleware -applications that need out-of-the-box certificates. It has the same settings as -the server certificates generated by the administrator tooling for nodes and -masters. - -.Service `Pod` spec configured for a service serving certificates secret. - -[source,yaml] ----- -apiVersion: v1 - kind: Service - metadata: - name: registry - annotations: - service.alpha.openshift.io/serving-cert-secret-name: registry-cert<1> -.... ----- -<1> Specify the name for the certificate - -Other pods can trust cluster-created certificates (which are only signed for -internal DNS names), by using the CA bundle in the -*_/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt_* file that is -automatically mounted in their pod. - -The signature algorithm for this feature is `x509.SHA256WithRSA`. To manually -rotate, delete the generated secret. A new certificate is created. - diff --git a/modules/nodes-pods-secrets-certificates-creating.adoc b/modules/nodes-pods-secrets-certificates-creating.adoc deleted file mode 100644 index 0decfdb5c65a..000000000000 --- a/modules/nodes-pods-secrets-certificates-creating.adoc +++ /dev/null @@ -1,129 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-secrets.adoc - -[id="nodes-pods-secrets-certificates-creating_{context}"] -= Generating signed certificates for use with secrets - -To use a signed serving certificate/key pair with a pod, create or edit the service to add -the `service.alpha.openshift.io/serving-cert-secret-name` annotation, then add the secret to the pod. - -.Procedure - -To create a _service serving certificate secret_: - -. Edit the `Pod` spec for your service. - -. Add the `service.alpha.openshift.io/serving-cert-secret-name` annotation -with the name you want to use for your secret. -+ -[source,yaml] ----- -kind: Service -apiVersion: v1 -metadata: - name: my-service - annotations: - service.alpha.openshift.io/serving-cert-secret-name: my-cert <1> -spec: - selector: - app: MyApp - ports: - - protocol: TCP - port: 80 - targetPort: 9376 ----- -+ -The certificate and key are in PEM format, stored in `tls.crt` and `tls.key` -respectively. - -. Create the service: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- - -. View the secret to make sure it was created: - -.. View a list of all secrets: -+ -[source,terminal] ----- -$ oc get secrets ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE DATA AGE -my-cert kubernetes.io/tls 2 9m ----- -+ -.. View details on your secret: -+ -[source,terminal] ----- -$ oc describe secret my-cert ----- -+ -.Example output -[source,terminal] ----- -Name: my-cert -Namespace: openshift-console -Labels: <none> -Annotations: service.alpha.openshift.io/expiry: 2023-03-08T23:22:40Z - service.alpha.openshift.io/originating-service-name: my-service - service.alpha.openshift.io/originating-service-uid: 640f0ec3-afc2-4380-bf31-a8c784846a11 - service.beta.openshift.io/expiry: 2023-03-08T23:22:40Z - -Type: kubernetes.io/tls - -Data -==== -tls.key: 1679 bytes -tls.crt: 2595 bytes ----- - -. Edit your `Pod` spec with that secret. -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: my-service-pod -spec: - containers: - - name: mypod - image: redis - volumeMounts: - - name: foo - mountPath: "/etc/foo" - volumes: - - name: foo - secret: - secretName: my-cert - items: - - key: username - path: my-group/my-username - mode: 511 ----- -+ -When it is available, your pod will run. -The certificate will be good for the internal service DNS name, -`<service.name>.<service.namespace>.svc`. -+ -The certificate/key pair is automatically replaced when it gets -close to expiration. View the expiration date in the -`service.alpha.openshift.io/expiry` annotation on the secret, which is in -RFC3339 format. -+ -[NOTE] -==== -In most cases, the service DNS name -`<service.name>.<service.namespace>.svc` is not externally routable. The -primary use of `<service.name>.<service.namespace>.svc` is for intracluster or -intraservice communication, and with re-encrypt routes. -==== diff --git a/modules/nodes-pods-secrets-creating-opaque.adoc b/modules/nodes-pods-secrets-creating-opaque.adoc deleted file mode 100644 index 549dda5c6a70..000000000000 --- a/modules/nodes-pods-secrets-creating-opaque.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-secrets.adoc - -[id="nodes-pods-secrets-creating-opaque_{context}"] -= Creating an opaque secret - -As an administrator, you can create a opaque secret, which allows for unstructured `key:value` pairs that can contain arbitrary values. - -.Procedure - -. Create a `Secret` object in a YAML file on master. -+ -For example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: mysecret -type: Opaque <1> -data: - username: dXNlci1uYW1l - password: cGFzc3dvcmQ= ----- -<1> Specifies an opaque secret. - -. Use the following command to create a `Secret` object: -+ -[source,terminal] ----- -$ oc create -f <filename> ----- - -. To use the secret in a pod: - -.. Update the service account for the pod where you want to use the secret to allow the reference to the secret. - -.. Create the pod, which consumes the secret as an environment variable or as a file -(using a `secret` volume). diff --git a/modules/nodes-pods-secrets-creating.adoc b/modules/nodes-pods-secrets-creating.adoc deleted file mode 100644 index 226d8dcfd20b..000000000000 --- a/modules/nodes-pods-secrets-creating.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-secrets.adoc - -[id="nodes-pods-secrets-creating_{context}"] -= Understanding how to create secrets - -As an administrator you must create a secret before developers can create the pods that depend on that secret. - -When creating secrets: - -- Create a secret object with secret data. -- Update the pod's service account to allow the reference to the secret. -- Create a pod, which consumes the secret as an environment variable or as a file -(using a `secret` volume). - -== Secret creation restrictions - -To use a secret, a pod needs to reference the secret. A secret can be used with -a pod in three ways: - -- To populate environment variables for containers. -- As files in a volume mounted on one or more of its containers. -- By kubelet when pulling images for the pod. - -Volume type secrets write data into the container as a file using the volume -mechanism. Image pull secrets use service accounts for the automatic injection of -the secret into all pods in a namespace. - -When a template contains a secret definition, the only way for the template to -use the provided secret is to ensure that the secret volume sources are -validated and that the specified object reference actually points to a `Secret` object. Therefore, a secret needs to be created before any pods that -depend on it. The most effective way to ensure this is to have it get injected -automatically through the use of a service account. - -Secret API objects reside in a namespace. They can only be referenced by pods in -that same namespace. - -Individual secrets are limited to 1MB in size. This is to discourage the -creation of large secrets that could exhaust apiserver and kubelet memory. -However, creation of a number of smaller secrets could also exhaust memory. diff --git a/modules/nodes-pods-secrets-troubleshooting.adoc b/modules/nodes-pods-secrets-troubleshooting.adoc deleted file mode 100644 index a7a0b9a5d651..000000000000 --- a/modules/nodes-pods-secrets-troubleshooting.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-secrets.adoc - -[id="nodes-pods-secrets-troubleshooting_{context}"] -= Troubleshooting secrets - -If a service certificate generation fails with (service's -`service.alpha.openshift.io/serving-cert-generation-error` annotation -contains): - -[source,terminal] ----- -secret/ssl-key references serviceUID 62ad25ca-d703-11e6-9d6f-0e9c0057b608, which does not match 77b6dd80-d716-11e6-9d6f-0e9c0057b60 ----- - -The service that generated the certificate no longer exists, or has a different -`serviceUID`. You must force certificates regeneration by removing the old -secret, and clearing the following annotations on the service -`service.alpha.openshift.io/serving-cert-generation-error`, -`service.alpha.openshift.io/serving-cert-generation-error-num`: - -. Delete the secret: -+ -[source,terminal] ----- -$ oc delete secret <secret_name> ----- - -. Clear the annotations: -+ -[source,terminal] ----- -$ oc annotate service <service_name> service.alpha.openshift.io/serving-cert-generation-error- ----- -+ -[source,terminal] ----- -$ oc annotate service <service_name> service.alpha.openshift.io/serving-cert-generation-error-num- ----- - -[NOTE] -==== -The command removing annotation has a `-` after the annotation name to be -removed. -==== diff --git a/modules/nodes-pods-secrets-updating.adoc b/modules/nodes-pods-secrets-updating.adoc deleted file mode 100644 index a9d8be4c1a68..000000000000 --- a/modules/nodes-pods-secrets-updating.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-secrets.adoc - -[id="nodes-pods-secrets-updating_{context}"] -= Understanding how to update secrets - -When you modify the value of a secret, the value (used by an already running pod) will not dynamically change. To change a secret, you must delete the -original pod and create a new pod (perhaps with an identical PodSpec). - -Updating a secret follows the same workflow as deploying a new Container image. You can use the `kubectl rolling-update` command. - -The `resourceVersion` value in a secret is not specified when it is referenced. Therefore, if a secret is updated at the same time as pods are starting, the version of the secret that is used for the pod is not defined. - -[NOTE] -==== -Currently, it is not possible to check the resource version of a secret object that was used when a pod was created. It is planned that pods will report this information, so that a controller could restart ones using a old `resourceVersion`. In the interim, do not update the data of existing secrets, but create new ones with distinct names. -==== diff --git a/modules/nodes-pods-using-about.adoc b/modules/nodes-pods-using-about.adoc deleted file mode 100644 index f2f580530eeb..000000000000 --- a/modules/nodes-pods-using-about.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-using.adoc - -[id="nodes-pods-using-about_{context}"] -= Understanding pods - -Pods are the rough equivalent of a machine instance (physical or virtual) to a Container. Each pod is allocated its own internal IP address, therefore owning its entire port space, and containers within pods can share their local storage and networking. - -Pods have a lifecycle; they are defined, then they are assigned to run on -a node, then they run until their container(s) exit or they are removed -for some other reason. Pods, depending on policy and exit code, might be -removed after exiting, or can be retained to enable access to -the logs of their containers. - -{product-title} treats pods as largely immutable; changes cannot be made to -a pod definition while it is running. {product-title} implements changes by -terminating an existing pod and recreating it with modified configuration, -base image(s), or both. Pods are also treated as expendable, and do not -maintain state when recreated. Therefore pods should usually be managed by -higher-level controllers, rather than directly by users. - -ifdef::openshift-enterprise,openshift-webscale[] -[NOTE] -==== -For the maximum number of pods per {product-title} node host, see the Cluster Limits. -==== -endif::[] -ifdef::openshift-dedicated[] -[IMPORTANT] -==== -The recommended maximum number of pods per {product-title} node host is 35. You -can have no more than 40 pods per node. -==== -endif::[] - -[WARNING] -==== -Bare pods that are not managed by a replication controller will be not rescheduled upon node disruption. -==== diff --git a/modules/nodes-pods-using-example.adoc b/modules/nodes-pods-using-example.adoc deleted file mode 100644 index ddeb78030cd1..000000000000 --- a/modules/nodes-pods-using-example.adoc +++ /dev/null @@ -1,136 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-using.adoc - -[id="nodes-pods-using-example_{context}"] -= Example pod configurations - -{product-title} leverages the Kubernetes concept of a _pod_, which is one or more containers deployed -together on one host, and the smallest compute unit that can be defined, -deployed, and managed. - -The following is an example definition of a pod that provides a long-running -service, which is actually a part of the {product-title} infrastructure: the -integrated container image registry. It demonstrates many features of pods, most of -which are discussed in other topics and thus only briefly mentioned here: - -[id="example-pod-definition_{context}"] -.`Pod` object definition (YAML) - -[source,yaml] ----- -kind: Pod -apiVersion: v1 -metadata: - name: example - namespace: default - selfLink: /api/v1/namespaces/default/pods/example - uid: 5cc30063-0265780783bc - resourceVersion: '165032' - creationTimestamp: '2019-02-13T20:31:37Z' - labels: <1> - app: hello-openshift - annotations: - openshift.io/scc: anyuid -spec: - restartPolicy: Always <2> - serviceAccountName: default - imagePullSecrets: - - name: default-dockercfg-5zrhb - priority: 0 - schedulerName: default-scheduler - terminationGracePeriodSeconds: 30 - nodeName: ip-10-0-140-16.us-east-2.compute.internal - securityContext: <3> - seLinuxOptions: - level: 's0:c11,c10' - containers: <4> - - resources: {} - terminationMessagePath: /dev/termination-log - name: hello-openshift - securityContext: - capabilities: - drop: - - MKNOD - procMount: Default - ports: - - containerPort: 8080 - protocol: TCP - imagePullPolicy: Always - volumeMounts: <5> - - name: default-token-wbqsl - readOnly: true - mountPath: /var/run/secrets/kubernetes.io/serviceaccount - terminationMessagePolicy: File - image: registry.redhat.io/openshift4/ose-ogging-eventrouter:v4.3 <6> - serviceAccount: default <7> - volumes: <8> - - name: default-token-wbqsl - secret: - secretName: default-token-wbqsl - defaultMode: 420 - dnsPolicy: ClusterFirst -status: - phase: Pending - conditions: - - type: Initialized - status: 'True' - lastProbeTime: null - lastTransitionTime: '2019-02-13T20:31:37Z' - - type: Ready - status: 'False' - lastProbeTime: null - lastTransitionTime: '2019-02-13T20:31:37Z' - reason: ContainersNotReady - message: 'containers with unready status: [hello-openshift]' - - type: ContainersReady - status: 'False' - lastProbeTime: null - lastTransitionTime: '2019-02-13T20:31:37Z' - reason: ContainersNotReady - message: 'containers with unready status: [hello-openshift]' - - type: PodScheduled - status: 'True' - lastProbeTime: null - lastTransitionTime: '2019-02-13T20:31:37Z' - hostIP: 10.0.140.16 - startTime: '2019-02-13T20:31:37Z' - containerStatuses: - - name: hello-openshift - state: - waiting: - reason: ContainerCreating - lastState: {} - ready: false - restartCount: 0 - image: openshift/hello-openshift - imageID: '' - qosClass: BestEffort ----- - -<1> Pods can be "tagged" with one or more labels, which can then -be used to select and manage groups of pods in a single operation. The labels -are stored in key/value format in the `metadata` hash. One label in this -example is `registry=default`. -<2> The pod restart policy with possible values `Always`, `OnFailure`, and `Never`. The default value is `Always`. -<3> {product-title} defines a security context for containers which specifies whether they are allowed to run as -privileged containers, run as a user of their choice, and more. The default context is very restrictive -but administrators can modify this as needed. -<4> `containers` specifies an array of one or more container definitions. -<5> The container specifies where external storage volumes are mounted within the container. In this case, there is a volume for storing access to credentials the registry needs for making requests against the {product-title} API. -<6> Each container in the pod is instantiated from its own container image. -<7> Pods making requests against the {product-title} API is a common enough pattern -that there is a `serviceAccount` field for specifying which service account user the pod should -authenticate as when making the requests. This enables fine-grained access -control for custom infrastructure components. -<8> The pod defines storage volumes that are available to its container(s) to -use. In this case, it provides an ephemeral volume for the registry storage and -a `secret` volume containing the service account credentials. - -[NOTE] -==== -This pod definition does not include attributes that -are filled by {product-title} automatically after the pod is created and -its lifecycle begins. The -link:https://kubernetes.io/docs/concepts/workloads/pods/pod/[Kubernetes pod documentation] has details about the functionality and purpose of pods. -==== diff --git a/modules/nodes-pods-vertical-autoscaler-about.adoc b/modules/nodes-pods-vertical-autoscaler-about.adoc deleted file mode 100644 index db8ba40d3613..000000000000 --- a/modules/nodes-pods-vertical-autoscaler-about.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-vertical-autoscaler.adoc - -[id="nodes-pods-vertical-autoscaler-about_{context}"] -= About the Vertical Pod Autoscaler Operator - -The Vertical Pod Autoscaler Operator (VPA) is implemented as an API resource and a custom resource (CR). The CR determines the actions the Vertical Pod Autoscaler Operator should take with the pods associated with a specific workload object, such as a daemon set, replication controller, and so forth. - -The VPA automatically computes historic and current CPU and memory usage for the containers in those pods and can use this data to automatically re-deploy pods with optimized resource limits and requests to ensure that these pods are operating efficiently at all times. When re-deploying pods, the VPA honors any Pod Disruption Budget set for applications. If you do not want the VPA to automatically re-deploy pods, you can use this resource information to manually update the pods as needed. - -When configured to update pods automatically, the VPA reduces resources for pods that are requesting more resources then they are using and increase resources for pods that are not requesting enough. - -For example, if you have a pod that uses 50% of the CPU but only requests 10%, the VPA determines that the pod is consuming more CPU than requested and restarts the pods with higher resources. - -For developers, the VPA helps ensure their pods stay up during periods of high demand by scheduling pods onto nodes so that appropriate resources are available for each pod. - -Administrators can use the VPA to better utilize cluster resources, such as preventing pods from reserving more CPU resources than needed. The VPA monitors the resources that workloads are actually using and adjusts the resource requirements so capacity is available to other workloads. The VPA also maintains the ratios between limits and requests that are specified in initial container configuration. - -[NOTE] -==== -If you stop running the VPA or delete a specific VPA CR in your cluster, the resource requests for the pods already modified by the VPA do not change. Any new pods get the resources defined in the workload object, not the previous recommendations made by the VPA. -==== diff --git a/modules/nodes-pods-vertical-autoscaler-configuring.adoc b/modules/nodes-pods-vertical-autoscaler-configuring.adoc deleted file mode 100644 index 4832bb098da0..000000000000 --- a/modules/nodes-pods-vertical-autoscaler-configuring.adoc +++ /dev/null @@ -1,106 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-vertical-autoscaler.adoc - -[id="nodes-pods-vertical-autoscaler-configuring_{context}"] -= Using the Vertical Pod Autoscaler Operator - -You can use the Vertical Pod Autoscaler Operator (VPA) by creating a VPA custom resource (CR). The CR indicates which pods it should analyze and determines the actions the VPA should take with those pods. - -.Procedure - -To create a VPA CR for a specific workload object: - -. Change to the project where the workload object you want to scale is located. - -.. Create a VPA CR YAML file: -+ -[source,yaml] ----- -apiVersion: autoscaling.k8s.io/v1 -kind: VerticalPodAutoscaler -metadata: - name: vpa-recommender -spec: - targetRef: - apiVersion: "apps/v1" - kind: Deployment <1> - name: frontend <2> - updatePolicy: - updateMode: "Auto" <3> - resourcePolicy: <4> - containerPolicies: - - containerName: my-opt-sidecar - mode: "Off" ----- -<1> Specify the type of workload object you want this VPA to manage: `Deployment`, `StatefulSet`, `Job`, `DaemonSet`, `ReplicaSet`, or `ReplicationController`. -<2> Specify the name of an existing workload object you want this VPA to manage. -<3> Specify the VPA mode: -* `auto` to automatically apply the recommended resources on pods associated with the controller. The VPA terminates existing pods and creates new pods with the recommended resource limits and requests. -* `recreate` to automatically apply the recommended resources on pods associated with the workload object. The VPA terminates existing pods and creates new pods with the recommended resource limits and requests. The `recreate` mode should be used rarely, only if you need to ensure that the pods are restarted whenever the resource request changes. -* `initial` to automatically apply the recommended resources when pods associated with the workload object are created. The VPA does not update the pods as it learns new resource recommendations. -* `off` to only generate resource recommendations for the pods associated with the workload object. The VPA does not update the pods as it learns new resource recommendations and does not apply the recommendations to new pods. -<4> Optional. Specify the containers you want to opt-out and set the mode to `Off`. - - -.. Create the VPA CR: -+ -[source,terminal] ----- -$ oc create -f <file-name>.yaml ----- -+ -After a few moments, the VPA learns the resource usage of the containers in the pods associated with the workload object. -+ -You can view the VPA recommendations using the following command: -+ -[source,terminal] ----- -$ oc get vpa <vpa-name> --output yaml ----- -+ -The output shows the recommendations for CPU and memory requests, similar to the following: -+ -.Example output -[source,yaml] ----- -... -status: - -... - - recommendation: - containerRecommendations: - - containerName: frontend - lowerBound: <1> - cpu: 25m - memory: 262144k - target: <2> - cpu: 25m - memory: 262144k - uncappedTarget: <3> - cpu: 25m - memory: 262144k - upperBound: <4> - cpu: 262m - memory: "274357142" - - containerName: backend - lowerBound: - cpu: 12m - memory: 131072k - target: - cpu: 12m - memory: 131072k - uncappedTarget: - cpu: 12m - memory: 131072k - upperBound: - cpu: 476m - memory: "498558823" - -... ----- -<1> `lowerBound` is the minimum recommended resource levels. -<2> `target` is the recommended resource levels. -<3> `upperBound` is the highest recommended resource levels. -<4> `uncappedTarget` is the most recent resource recommendations. diff --git a/modules/nodes-pods-vertical-autoscaler-install.adoc b/modules/nodes-pods-vertical-autoscaler-install.adoc deleted file mode 100644 index 9ea0ffc8ec41..000000000000 --- a/modules/nodes-pods-vertical-autoscaler-install.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-vertical-autoscaler.adoc - -[id="nodes-pods-vertical-autoscaler-install_{context}"] -= Installing the Vertical Pod Autoscaler Operator - -You can use the {product-title} web console to install the Vertical Pod Autoscaler Operator (VPA). - -ifdef::openshift-origin[] -.Prerequisites - -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in _Obtaining the installation program_ in the installation documentation for your platform. -+ -If you have the pull secret, add the `redhat-operators` catalog to the OperatorHub custom resource (CR) as shown in _Configuring {product-title} to use Red Hat Operators_. -endif::[] - -.Procedure - -. In the {product-title} web console, click *Operators* -> *OperatorHub*. - -. Choose *VerticalPodAutoscaler* from the list of available Operators, and click *Install*. - -. On the *Install Operator* page, ensure that the *Operator recommended namespace* option -is selected. This installs the Operator in the mandatory `openshift-vertical-pod-autoscaler` namespace, which -is automatically created if it does not exist. - -. Click *Install*. - -. Verify the install by listing the VPA Operator components: - -.. Navigate to *Workloads* -> *Pods*. - -.. Select the `openshift-vertical-pod-autoscaler` project from the drop-down menu and verify that there are four pods running. - -.. Navigate to *Workloads* -> *Deployments* to verify that there are four deployments running. - -. Optional. Verify the install in the {product-title} CLI using the following command: -+ -[source,terminal] ----- -$ oc get all -n openshift-vertical-pod-autoscaler ----- -+ -The output shows four pods and four deplyoments: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -pod/vertical-pod-autoscaler-operator-85b4569c47-2gmhc 1/1 Running 0 3m13s -pod/vpa-admission-plugin-default-67644fc87f-xq7k9 1/1 Running 0 2m56s -pod/vpa-recommender-default-7c54764b59-8gckt 1/1 Running 0 2m56s -pod/vpa-updater-default-7f6cc87858-47vw9 1/1 Running 0 2m56s - -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -service/vpa-webhook ClusterIP 172.30.53.206 <none> 443/TCP 2m56s - -NAME READY UP-TO-DATE AVAILABLE AGE -deployment.apps/vertical-pod-autoscaler-operator 1/1 1 1 3m13s -deployment.apps/vpa-admission-plugin-default 1/1 1 1 2m56s -deployment.apps/vpa-recommender-default 1/1 1 1 2m56s -deployment.apps/vpa-updater-default 1/1 1 1 2m56s - -NAME DESIRED CURRENT READY AGE -replicaset.apps/vertical-pod-autoscaler-operator-85b4569c47 1 1 1 3m13s -replicaset.apps/vpa-admission-plugin-default-67644fc87f 1 1 1 2m56s -replicaset.apps/vpa-recommender-default-7c54764b59 1 1 1 2m56s -replicaset.apps/vpa-updater-default-7f6cc87858 1 1 1 2m56s ----- - diff --git a/modules/nodes-pods-vertical-autoscaler-uninstall.adoc b/modules/nodes-pods-vertical-autoscaler-uninstall.adoc deleted file mode 100644 index 9d18906db9aa..000000000000 --- a/modules/nodes-pods-vertical-autoscaler-uninstall.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-vertical-autoscaler.adoc - -[id="nodes-pods-vertical-autoscaler-uninstall_{context}"] -= Uninstalling the Vertical Pod Autoscaler Operator - -You can remove the Vertical Pod Autoscaler Operator (VPA) from your {product-title} cluster. After uninstalling, the resource requests for the pods already modified by an existing VPA CR do not change. Any new pods get the resources defined in the workload object, not the previous recommendations made by the Vertical Pod Autoscaler Operator. - -[NOTE] -==== -You can remove a specific VPA using the `oc delete vpa <vpa-name>` command. The same actions apply for resource requests as uninstalling the vertical pod autoscaler. -==== - -.Prerequisites - -* The Vertical Pod Autoscaler Operator must be installed. - -.Procedure - -. In the {product-title} web console, click *Operators* → *Installed Operators*. - -. Switch to the *openshift-vertical-pod-autoscaler* project. - -. Find the *VerticalPodAutoscaler* Operator and click the Options menu. Select *Uninstall Operator*. - -. In the dialog box, click *Uninstall*. diff --git a/modules/nodes-pods-vertical-autoscaler-using-about.adoc b/modules/nodes-pods-vertical-autoscaler-using-about.adoc deleted file mode 100644 index c5cde6660d2f..000000000000 --- a/modules/nodes-pods-vertical-autoscaler-using-about.adoc +++ /dev/null @@ -1,281 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-vertical-autoscaler.adoc - -[id="nodes-pods-vertical-autoscaler-using-about_{context}"] -= About Using the Vertical Pod Autoscaler Operator - -To use the Vertical Pod Autoscaler Operator (VPA), you create a VPA custom resource (CR) for a workload object in your cluster. The VPA learns and applies the optimal CPU and memory resources for the pods associated with that workload object. You can use a VPA with a deployment, stateful set, job, daemon set, replica set, or replication controller workload object. The VPA CR must be in the same project as the pods you want to monitor. - -You use the VPA CR to associate a workload object and specify which mode the VPA operates in: - -* The `Auto` and `Recreate` modes automatically apply the VPA CPU and memory recommendations throughout the pod lifetime. -* The `Initial` mode automatically applies VPA recommendations only at pod creation. -* The `Off` mode only provides recommended resource limits and requests, allowing you to manually apply the recommendations. The `off` mode does not update pods. - -You can also use the CR to opt-out certain containers from VPA evaluation and updates. - -For example, a pod has the following limits and requests: - -[source,yaml] ----- -resources: - limits: - cpu: 1 - memory: 500Mi - requests: - cpu: 500m - memory: 100Mi ----- - -After creating a VPA that is set to `auto`, the VPA learns the resource usage and terminates and recreates the pod with new resource limits and requests: - -[source,yaml] ----- -resources: - limits: - cpu: 50m - memory: 1250Mi - requests: - cpu: 25m - memory: 262144k ----- - -You can view the VPA recommendations using the following command: - -[source,terminal] ----- -$ oc get vpa <vpa-name> --output yaml ----- - -The output shows the recommendations for CPU and memory requests, similar to the following: - -.Example output -[source,yaml] ----- -... -status: - -... - - recommendation: - containerRecommendations: - - containerName: frontend - lowerBound: - cpu: 25m - memory: 262144k - target: - cpu: 25m - memory: 262144k - uncappedTarget: - cpu: 25m - memory: 262144k - upperBound: - cpu: 262m - memory: "274357142" - - containerName: backend - lowerBound: - cpu: 12m - memory: 131072k - target: - cpu: 12m - memory: 131072k - uncappedTarget: - cpu: 12m - memory: 131072k - upperBound: - cpu: 476m - memory: "498558823" - -... ----- - -The output shows the recommended resources, `target`, the minimum recommended resources, `lowerBound`, the highest recommended resources, `upperBound`, and the most recent resource recommendations, `uncappedTarget`. - -The VPA uses the `lowerBound` and `upperBound` values to determine if a pod needs to be updated. If a pod has resource requests below the `lowerBound` values or above the `upperBound` values, the VPA terminates and recreates the pod with the `target` values. - -[id="nodes-pods-vertical-autoscaler-using-auto_{context}"] -== Automatically applying VPA recommendations -To use the VPA to automatically update pods, create a VPA CR for a specific workload object with `updateMode` set to `Auto` or `Recreate`. - -When the pods are created for the workload object, the VPA constantly monitors the containers to analyze their CPU and memory needs. The VPA deletes and redeploys pods with new container resource limits and requests to meet those needs, honoring any Pod Disruption Budget set for your applications. The recommendations are added to the `status` field of the VPA CR for reference. - -.Example VPA CR for the `Auto` mode -[source,yaml] ----- -apiVersion: autoscaling.k8s.io/v1 -kind: VerticalPodAutoscaler -metadata: - name: vpa-recommender -spec: - targetRef: - apiVersion: "apps/v1" - kind: Deployment <1> - name: frontend <2> - updatePolicy: - updateMode: "Auto" <3> ----- -<1> The type of workload object you want this VPA CR to manage. -<2> The name of workload object you want this VPA CR to manage. -<3> Set the mode to `Auto` or `Recreate`: -* `Auto`. The VPA assigns resource requests on pod creation and updates the existing pods by terminating them when the requested resources differ significantly from the new recommendation. -* `Recreate`. The VPA assigns resource requests on pod creation and updates the existing pods by terminating them when the requested resources differ significantly from the new recommendation. This mode should be used rarely, only if you need to ensure that the pods are restarted whenever the resource request changes. - -[NOTE] -==== -There must be operating pods in the project before the VPA can determine recommended resources and apply the recommendations to new pods. -==== - -[id="nodes-pods-vertical-autoscaler-using-pod_{context}"] -== Automatically applying VPA recommendations on pod creation -To use the VPA to apply the recommended resources only when a pod is first deployed, create a VPA CR for a specific workload object with `updateMode` set to `Initial`. - -When the pods are created for that workload object, the VPA analyzes the CPU and memory needs of the containers and assigns the recommended container resource limits and requests. The VPA does not update the pods as it learns new resource recommendations. - -.Example VPA CR for the `Initial` mode -[source,yaml] ----- -apiVersion: autoscaling.k8s.io/v1 -kind: VerticalPodAutoscaler -metadata: - name: vpa-recommender -spec: - targetRef: - apiVersion: "apps/v1" - kind: Deployment <1> - name: frontend <2> - updatePolicy: - updateMode: "Initial" <3> ----- -<1> The type of workload object you want this VPA CR to manage. -<2> The name of workload object you want this VPA CR to manage. -<3> Set the mode to `Initial`. The VPA assigns resources when pods are created and does not change the resources during the lifetime of the pod. - -[NOTE] -==== -There must be operating pods in the project before a VPA can determine recommended resources and apply the recommendations to new pods. -==== - -[id="nodes-pods-vertical-autoscaler-using-manual_{context}"] -== Manually applying VPA recommendations - -To use the VPA to only determine the recommended CPU and memory values, create a VPA CR for a specific workload object with `updateMode` set to `off`. - -When the pods are created for that workload object, the VPA analyzes the CPU and memory needs of the containers and records those recommendations in the `status` field of the VPA CR. The VPA does not update the pods as it determines new resource recommendations. - -.Example VPA CR for the `Off` mode -[source,yaml] ----- -apiVersion: autoscaling.k8s.io/v1 -kind: VerticalPodAutoscaler -metadata: - name: vpa-recommender -spec: - targetRef: - apiVersion: "apps/v1" - kind: Deployment <1> - name: frontend <2> - updatePolicy: - updateMode: "Off" <3> ----- -<1> The type of workload object you want this VPA CR to manage. -<2> The name of workload object you want this VPA CR to manage. -<3> Set the mode to `Off`. - -You can view the recommendations using the following command. - -[source,terminal] ----- -$ oc get vpa <vpa-name> --output yaml ----- - -With the recommendations, you can edit the workload object to add CPU and memory requests, then delete and redeploy the pods using the recommended resources. - -[NOTE] -==== -There must be operating pods in the project before a VPA can determine recommended resources. -==== - -[id="nodes-pods-vertical-autoscaler-using-exempt_{context}"] -== Exempting containers from applying VPA recommendations - -If your workload object has multiple containers and you do not want the VPA to evaluate and act on all of the containers, create a VPA CR for a specific workload object and add a `resourcePolicy` to opt-out specific containers. - -When the VPA updates the pods with recommended resources, any containers with a `resourcePolicy` are not updated and the VPA does not present recommendations for those containers in the pod. - -[source,yaml] ----- -apiVersion: autoscaling.k8s.io/v1 -kind: VerticalPodAutoscaler -metadata: - name: vpa-recommender -spec: - targetRef: - apiVersion: "apps/v1" - kind: Deployment <1> - name: frontend <2> - updatePolicy: - updateMode: "Auto" <3> - resourcePolicy: <4> - containerPolicies: - - containerName: my-opt-sidecar - mode: "Off" ----- -<1> The type of workload object you want this VPA CR to manage. -<2> The name of workload object you want this VPA CR to manage. -<3> Set the mode to `Auto`, `Recreate`, or `Off`. The `Recreate` mode should be used rarely, only if you need to ensure that the pods are restarted whenever the resource request changes. -<4> Specify the containers you want to opt-out and set `mode` to `Off`. - -For example, a pod has two containers, the same resource requests and limits: - -[source,yaml] ----- -... -spec: - containers: - name: frontend - resources: - limits: - cpu: 1 - memory: 500Mi - requests: - cpu: 500m - memory: 100Mi -... - name: backend - resources: - limits: - cpu: "1" - memory: 500Mi - requests: - cpu: 500m - memory: 100Mi -... ----- - -After launching a VPA CR with the `backend` container set to opt-out, the VPA terminates and recreates the pod with the recommended resources applied only to the `frontend` container: - -[source,yaml] ----- -... -spec: - containers: - name: frontend - resources: - limits: - cpu: 50m - memory: 1250Mi - requests: - cpu: 25m - memory: 262144k -... - name: backend - resources: - limits: - cpu: "1" - memory: 500Mi - requests: - cpu: 500m - memory: 100Mi -... ----- diff --git a/modules/nodes-pods-viewing-project.adoc b/modules/nodes-pods-viewing-project.adoc deleted file mode 100644 index d2d8b90bc488..000000000000 --- a/modules/nodes-pods-viewing-project.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-viewing.adoc - -[id="nodes-pods-viewing-project_{context}"] -= Viewing pods in a project - -You can view a list of pods associated with the current project, including the number of replica, the current status, number or restarts and the age of the pod. - -.Procedure - -To view the pods in a project: - -. Change to the project: -+ -[source,terminal] ----- -$ oc project <project-name> ----- - -. Run the following command: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get pods -n openshift-console ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -console-698d866b78-bnshf 1/1 Running 2 165m -console-698d866b78-m87pm 1/1 Running 2 165m ----- -+ -Add the `-o wide` flags to view the pod IP address and the node where the pod is located. -+ -[source,terminal] ----- -$ oc get pods -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE -console-698d866b78-bnshf 1/1 Running 2 166m 10.128.0.24 ip-10-0-152-71.ec2.internal <none> -console-698d866b78-m87pm 1/1 Running 2 166m 10.129.0.23 ip-10-0-173-237.ec2.internal <none> ----- diff --git a/modules/nodes-pods-viewing-usage.adoc b/modules/nodes-pods-viewing-usage.adoc deleted file mode 100644 index 18a8d5dba3c1..000000000000 --- a/modules/nodes-pods-viewing-usage.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-pods-viewing.adoc - -[id="nodes-pods-viewing-usage_{context}"] -= Viewing pod usage statistics - -You can display usage statistics about pods, which provide the runtime -environments for containers. These usage statistics include CPU, memory, and -storage consumption. - -.Prerequisites - -* You must have `cluster-reader` permission to view the usage statistics. - -* Metrics must be installed to view the usage statistics. - -.Procedure - -To view the usage statistics: - -. Run the following command: -+ -[source,terminal] ----- -$ oc adm top pods ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm top pods -n openshift-console ----- -+ -.Example output -[source,terminal] ----- -NAME CPU(cores) MEMORY(bytes) -console-7f58c69899-q8c8k 0m 22Mi -console-7f58c69899-xhbgg 0m 25Mi -downloads-594fcccf94-bcxk8 3m 18Mi -downloads-594fcccf94-kv4p6 2m 15Mi ----- - -. Run the following command to view the usage statistics for pods with labels: -+ -[source,terminal] ----- -$ oc adm top pod --selector='' ----- -+ -You must choose the selector (label query) to filter on. Supports `=`, `==`, and `!=`. diff --git a/modules/nodes-scheduler-default-about.adoc b/modules/nodes-scheduler-default-about.adoc deleted file mode 100644 index 93999ef8810f..000000000000 --- a/modules/nodes-scheduler-default-about.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-default.adoc - -[id="nodes-scheduler-default-about_{context}"] -= Understanding default scheduling - -The existing generic scheduler is the default platform-provided scheduler -_engine_ that selects a node to host the pod in a three-step operation: - - -Filters the Nodes:: -The available nodes are filtered based on the constraints or requirements -specified. This is done by running each node through the list of filter -functions called _predicates_. - -Prioritize the Filtered List of Nodes:: -This is achieved by passing each node through a series of priority_ functions -that assign it a score between 0 - 10, with 0 indicating a bad fit and 10 -indicating a good fit to host the pod. The scheduler configuration can also take -in a simple _weight_ (positive numeric value) for each priority function. The -node score provided by each priority function is multiplied by the weight -(default weight for most priorities is 1) and then combined by adding the scores for each node -provided by all the priorities. This weight attribute can be used by -administrators to give higher importance to some priorities. - -Select the Best Fit Node:: -The nodes are sorted based on their scores and the node with the highest score -is selected to host the pod. If multiple nodes have the same high score, then -one of them is selected at random. - -[id="nodes-scheduler-default-about-understanding_{context}"] -== Understanding Scheduler Policy - -The selection of the predicate and priorities defines the policy for the scheduler. - -The scheduler configuration file is a JSON file, which must be named `policy.cfg`, that specifies the predicates and priorities the scheduler -will consider. - -In the absence of the scheduler policy file, the default scheduler behavior is used. - -// we are working on how to configures this in 4.0 right now in https://github.com/openshift/api/pull/181 - -[IMPORTANT] -==== -The predicates and priorities defined in -the scheduler configuration file completely override the default scheduler -policy. If any of the default predicates and priorities are required, -you must explicitly specify the functions in the policy configuration. -==== - -.Sample scheduler config map -[source,yaml] ----- -apiVersion: v1 -data: - policy.cfg: | - { - "kind" : "Policy", - "apiVersion" : "v1", - "predicates" : [ - {"name" : "MaxGCEPDVolumeCount"}, - {"name" : "GeneralPredicates"}, <1> - {"name" : "MaxAzureDiskVolumeCount"}, - {"name" : "MaxCSIVolumeCountPred"}, - {"name" : "CheckVolumeBinding"}, - {"name" : "MaxEBSVolumeCount"}, - {"name" : "MatchInterPodAffinity"}, - {"name" : "CheckNodeUnschedulable"}, - {"name" : "NoDiskConflict"}, - {"name" : "NoVolumeZoneConflict"}, - {"name" : "PodToleratesNodeTaints"} - ], - "priorities" : [ - {"name" : "LeastRequestedPriority", "weight" : 1}, - {"name" : "BalancedResourceAllocation", "weight" : 1}, - {"name" : "ServiceSpreadingPriority", "weight" : 1}, - {"name" : "NodePreferAvoidPodsPriority", "weight" : 1}, - {"name" : "NodeAffinityPriority", "weight" : 1}, - {"name" : "TaintTolerationPriority", "weight" : 1}, - {"name" : "ImageLocalityPriority", "weight" : 1}, - {"name" : "SelectorSpreadPriority", "weight" : 1}, - {"name" : "InterPodAffinityPriority", "weight" : 1}, - {"name" : "EqualPriority", "weight" : 1} - ] - } -kind: ConfigMap -metadata: - creationTimestamp: "2019-09-17T08:42:33Z" - name: scheduler-policy - namespace: openshift-config - resourceVersion: "59500" - selfLink: /api/v1/namespaces/openshift-config/configmaps/scheduler-policy - uid: 17ee8865-d927-11e9-b213-02d1e1709840` ----- -<1> The `GeneralPredicates` predicate represents the `PodFitsResources`, `HostName`, `PodFitsHostPorts`, and `MatchNodeSelector` predicates. -Because you are not allowed to configure the same predicate multiple times, the `GeneralPredicates` predicate cannot be used alongside -any of the four represented predicates. - -//// -.Typical predicate string ----- -\n\t{\"name\" : \"<PredicateName>\", \"label\" : \"<label>\", \"<condition>\" : \"<state>\"}, ----- -* `name` is the name of the predicate, such as `labelsPresence`. -* `label` and `<label>` is the node label:value pair to match to apply the predicate, such `label:rack`. -* `<condition>` and `<state>` is when the predicate should be applied, such as `presence:true`. - -.Typical priority string ----- -\n\t{\"name\" : \"<PredicateName>\", \"label\" : \"<label>\", \"<condition>\" : \"<state>\", \"weight\" : <weight>}, ----- -* `name` is the name of the priority, such as `labelsPresence`. -* `label` and `<label>` is the node `label:value` pair to match to apply the priority, such `label:rack`. -* `<condition>` and `<state>` is when the priority should be applied, such as `presence:true`. -* `weight` and `<weight> is the numerical weight to apply to the priority. -//// diff --git a/modules/nodes-scheduler-default-creating.adoc b/modules/nodes-scheduler-default-creating.adoc deleted file mode 100644 index 49cf4d646d3e..000000000000 --- a/modules/nodes-scheduler-default-creating.adoc +++ /dev/null @@ -1,112 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-default.adoc - - -[id="nodes-scheduler-default-creating_{context}"] -= Creating a scheduler policy file - -//Made changes to this file to match https://github.com/openshift/openshift-docs/pull/13626/files#diff-ba6ab177a3e2867eaefe07f48bd6e158 - -You can change the default scheduling behavior by creating a JSON file with the desired predicates and priorities. You then generate a config map from the JSON file and point the `cluster` Scheduler object to use the config map. - -.Procedure - -To configure the scheduler policy: - -. Create a JSON file named `policy.cfg` with the desired predicates and priorities. -+ -.Sample scheduler JSON file -[source,json] ----- -{ -"kind" : "Policy", -"apiVersion" : "v1", -"predicates" : [ <1> - {"name" : "MaxGCEPDVolumeCount"}, - {"name" : "GeneralPredicates"}, - {"name" : "MaxAzureDiskVolumeCount"}, - {"name" : "MaxCSIVolumeCountPred"}, - {"name" : "CheckVolumeBinding"}, - {"name" : "MaxEBSVolumeCount"}, - {"name" : "MatchInterPodAffinity"}, - {"name" : "CheckNodeUnschedulable"}, - {"name" : "NoDiskConflict"}, - {"name" : "NoVolumeZoneConflict"}, - {"name" : "PodToleratesNodeTaints"} - ], -"priorities" : [ <2> - {"name" : "LeastRequestedPriority", "weight" : 1}, - {"name" : "BalancedResourceAllocation", "weight" : 1}, - {"name" : "ServiceSpreadingPriority", "weight" : 1}, - {"name" : "NodePreferAvoidPodsPriority", "weight" : 1}, - {"name" : "NodeAffinityPriority", "weight" : 1}, - {"name" : "TaintTolerationPriority", "weight" : 1}, - {"name" : "ImageLocalityPriority", "weight" : 1}, - {"name" : "SelectorSpreadPriority", "weight" : 1}, - {"name" : "InterPodAffinityPriority", "weight" : 1}, - {"name" : "EqualPriority", "weight" : 1} - ] -} ----- -<1> Add the predicates as needed. -<2> Add the priorities as needed. - -. Create a config map based on the scheduler JSON file: -+ -[source,terminal] ----- -$ oc create configmap -n openshift-config --from-file=policy.cfg <configmap-name> <1> ----- -<1> Enter a name for the config map. -+ -For example: -+ -[source,terminal] ----- -$ oc create configmap -n openshift-config --from-file=policy.cfg scheduler-policy ----- -+ -.Example output -[source,terminal] ----- -configmap/scheduler-policy created ----- - -. Edit the Scheduler Operator custom resource to add the config map: -+ -[source,terminal] ----- -$ oc patch Scheduler cluster --type='merge' -p '{"spec":{"policy":{"name":"<configmap-name>"}}}' --type=merge <1> ----- -+ -<1> Specify the name of the config map. -+ -For example: -+ -[source,terminal] ----- -$ oc patch Scheduler cluster --type='merge' -p '{"spec":{"policy":{"name":"scheduler-policy"}}}' --type=merge ----- -+ -After making the change to the `Scheduler` config resource, wait for the `openshift-kube-apiserver` pods to redeploy. This can take several minutes. Until the pods redeploy, new scheduler does not take effect. - -. Verify the scheduler policy is configured by viewing the log of a scheduler pod in the `openshift-kube-scheduler` namespace. The following command checks for the predicates and priorities that are being registered by the scheduler: -+ -[source,terminal] ----- -$ oc logs <scheduler-pod> | grep predicates ----- -+ -For example: -+ -[source,terminal] ----- -$ oc logs openshift-kube-scheduler-ip-10-0-141-29.ec2.internal | grep predicates ----- -+ -.Example output -[source,terminal] ----- -Creating scheduler with fit predicates 'map[MaxGCEPDVolumeCount:{} MaxAzureDiskVolumeCount:{} CheckNodeUnschedulable:{} NoDiskConflict:{} NoVolumeZoneConflict:{} GeneralPredicates:{} MaxCSIVolumeCountPred:{} CheckVolumeBinding:{} MaxEBSVolumeCount:{} MatchInterPodAffinity:{} PodToleratesNodeTaints:{}]' and priority functions 'map[InterPodAffinityPriority:{} LeastRequestedPriority:{} ServiceSpreadingPriority:{} ImageLocalityPriority:{} SelectorSpreadPriority:{} EqualPriority:{} BalancedResourceAllocation:{} NodePreferAvoidPodsPriority:{} NodeAffinityPriority:{} TaintTolerationPriority:{}]' ----- diff --git a/modules/nodes-scheduler-default-modifying.adoc b/modules/nodes-scheduler-default-modifying.adoc deleted file mode 100644 index 8de3c7591ba7..000000000000 --- a/modules/nodes-scheduler-default-modifying.adoc +++ /dev/null @@ -1,161 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-default.adoc - -[id="nodes-scheduler-default-modifying_{context}"] -= Modifying scheduler policies - -//Made changes to this file to match https://github.com/openshift/openshift-docs/pull/13626/files#diff-ba6ab177a3e2867eaefe07f48bd6e158 - -You change scheduling behavior by creating or editing your scheduler policy config map in the `openshift-config` project. -Add and remove predicates and priorities to the config map to create a _scheduler policy_. - - -.Procedure - -To modify the current custom scheduling, use one of the following methods: - -* Edit the scheduler policy config map: -+ -[source,terminal] ----- -$ oc edit configmap <configmap-name> -n openshift-config ----- -+ -For example: -+ -[source,terminal] ----- -$ oc edit configmap scheduler-policy -n openshift-config ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -data: - policy.cfg: | - { - "kind" : "Policy", - "apiVersion" : "v1", - "predicates" : [ <1> - {"name" : "MaxGCEPDVolumeCount"}, - {"name" : "GeneralPredicates"}, - {"name" : "MaxAzureDiskVolumeCount"}, - {"name" : "MaxCSIVolumeCountPred"}, - {"name" : "CheckVolumeBinding"}, - {"name" : "MaxEBSVolumeCount"}, - {"name" : "MatchInterPodAffinity"}, - {"name" : "CheckNodeUnschedulable"}, - {"name" : "NoDiskConflict"}, - {"name" : "NoVolumeZoneConflict"}, - {"name" : "PodToleratesNodeTaints"} - ], - "priorities" : [ <2> - {"name" : "LeastRequestedPriority", "weight" : 1}, - {"name" : "BalancedResourceAllocation", "weight" : 1}, - {"name" : "ServiceSpreadingPriority", "weight" : 1}, - {"name" : "NodePreferAvoidPodsPriority", "weight" : 1}, - {"name" : "NodeAffinityPriority", "weight" : 1}, - {"name" : "TaintTolerationPriority", "weight" : 1}, - {"name" : "ImageLocalityPriority", "weight" : 1}, - {"name" : "SelectorSpreadPriority", "weight" : 1}, - {"name" : "InterPodAffinityPriority", "weight" : 1}, - {"name" : "EqualPriority", "weight" : 1} - ] - } -kind: ConfigMap -metadata: - creationTimestamp: "2019-09-17T17:44:19Z" - name: scheduler-policy - namespace: openshift-config - resourceVersion: "15370" - selfLink: /api/v1/namespaces/openshift-config/configmaps/scheduler-policy ----- -<1> Add or remove predicates as needed. -<2> Add, remove, or change the weight of predicates as needed. -+ -It can take a few minutes for the scheduler to restart the pods with the updated policy. - -* Change the policies and predicates being used: - -. Remove the scheduler policy config map: -+ -[source,terminal] ----- -$ oc delete configmap -n openshift-config <name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc delete configmap -n openshift-config scheduler-policy ----- - -. Edit the `policy.cfg` file to add and remove policies and predicates as needed. -+ -For example: -+ -[source,terminal] ----- -$ vi policy.cfg ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -data: - policy.cfg: | - { - "kind" : "Policy", - "apiVersion" : "v1", - "predicates" : [ - {"name" : "MaxGCEPDVolumeCount"}, - {"name" : "GeneralPredicates"}, - {"name" : "MaxAzureDiskVolumeCount"}, - {"name" : "MaxCSIVolumeCountPred"}, - {"name" : "CheckVolumeBinding"}, - {"name" : "MaxEBSVolumeCount"}, - {"name" : "MatchInterPodAffinity"}, - {"name" : "CheckNodeUnschedulable"}, - {"name" : "NoDiskConflict"}, - {"name" : "NoVolumeZoneConflict"}, - {"name" : "PodToleratesNodeTaints"} - ], - "priorities" : [ - {"name" : "LeastRequestedPriority", "weight" : 1}, - {"name" : "BalancedResourceAllocation", "weight" : 1}, - {"name" : "ServiceSpreadingPriority", "weight" : 1}, - {"name" : "NodePreferAvoidPodsPriority", "weight" : 1}, - {"name" : "NodeAffinityPriority", "weight" : 1}, - {"name" : "TaintTolerationPriority", "weight" : 1}, - {"name" : "ImageLocalityPriority", "weight" : 1}, - {"name" : "SelectorSpreadPriority", "weight" : 1}, - {"name" : "InterPodAffinityPriority", "weight" : 1}, - {"name" : "EqualPriority", "weight" : 1} - ] - } ----- - -. Re-create the scheduler policy config map based on the scheduler JSON file: -+ -[source,terminal] ----- -$ oc create configmap -n openshift-config --from-file=policy.cfg <configmap-name> <1> ----- -<1> Enter a name for the config map. -+ -For example: -+ -[source,terminal] ----- -$ oc create configmap -n openshift-config --from-file=policy.cfg scheduler-policy ----- -+ -.Example output -[source,terminal] ----- -configmap/scheduler-policy created ----- diff --git a/modules/nodes-scheduler-default-predicates.adoc b/modules/nodes-scheduler-default-predicates.adoc deleted file mode 100644 index 53fc8c1e2a92..000000000000 --- a/modules/nodes-scheduler-default-predicates.adoc +++ /dev/null @@ -1,298 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-default.adoc - -[id="nodes-scheduler-default-predicates_{context}"] -= Understanding the scheduler predicates - -Predicates are rules that filter out unqualified nodes. - -There are several predicates provided by default in {product-title}. Some of -these predicates can be customized by providing certain parameters. Multiple -predicates can be combined to provide additional filtering of nodes. - -[id="static-predicates_{context}"] -== Static Predicates -These predicates do not take any configuration parameters or inputs from the -user. These are specified in the scheduler configuration using their exact -name. - -[id="default-predicates_{context}"] -=== Default Predicates - -The default scheduler policy includes the following predicates: - -The `NoVolumeZoneConflict` predicate checks that the volumes a pod requests -are available in the zone. - -[source,yaml] ----- -{"name" : "NoVolumeZoneConflict"} ----- - -The `MaxEBSVolumeCount` predicate checks the maximum number of volumes that can be attached to an AWS instance. - -[source,yaml] ----- -{"name" : "MaxEBSVolumeCount"} ----- - -The `MaxAzureDiskVolumeCount` predicate checks the maximum number of Azure Disk Volumes. - -[source,yaml] ----- -{"name" : "MaxAzureDiskVolumeCount"} ----- - -The `PodToleratesNodeTaints` predicate checks if a pod can tolerate the node taints. - -[source,yaml] ----- -{"name" : "PodToleratesNodeTaints"} ----- - -The `CheckNodeUnschedulable` predicate checks if a pod can be scheduled on a node with `Unschedulable` spec. - -[source,yaml] ----- -{"name" : "CheckNodeUnschedulable"} ----- - -The `CheckVolumeBinding` predicate evaluates if a pod can fit based on the volumes, it requests, for both bound and unbound PVCs. - -* For PVCs that are bound, the predicate checks that the corresponding PV's node affinity is satisfied by the given node. -* For PVCs that are unbound, the predicate searched for available PVs that can satisfy the PVC requirements and that -the PV node affinity is satisfied by the given node. - -The predicate returns true if all bound PVCs have compatible PVs with the node, and if all unbound PVCs can be matched with an available and node-compatible PV. - -[source,yaml] ----- -{"name" : "CheckVolumeBinding"} ----- - -// The `CheckVolumeBinding` predicate must be enabled in non-default schedulers. - -The `NoDiskConflict` predicate checks if the volume requested by a pod is available. - -[source,yaml] ----- -{"name" : "NoDiskConflict"} ----- - -The `MaxGCEPDVolumeCount` predicate checks the maximum number of Google Compute Engine (GCE) Persistent Disks (PD). - -[source,yaml] ----- -{"name" : "MaxGCEPDVolumeCount"} ----- - -`MaxCSIVolumeCountPred` - - -The `MatchInterPodAffinity` predicate checks if the pod affinity/anti-affinity rules permit the pod. - -[source,yaml] ----- -{"name" : "MatchInterPodAffinity"} ----- - -[id="other-predicates_{context}"] -=== Other Static Predicates - -{product-title} also supports the following predicates: - -[NOTE] -==== -The `CheckNode-*` predicates cannot be used if the Taint Nodes By Condition feature is enabled. -The Taint Nodes By Condition feature is enabled by default. -==== - -The `CheckNodeCondition` predicate checks if a pod can be scheduled on a node reporting *out of disk*, *network unavailable*, or *not ready* conditions. - -[source,yaml] ----- -{"name" : "CheckNodeCondition"} ----- - -The `CheckNodeLabelPresence` predicate checks if all of the specified labels exist on a node, regardless of their value. - -[source,yaml] ----- -{"name" : "CheckNodeLabelPresence"} ----- - -The `checkServiceAffinity` predicate checks that ServiceAffinity labels are homogeneous for pods that are scheduled on a node. - -[source,yaml] ----- -{"name" : "checkServiceAffinity"} ----- - -The `PodToleratesNodeNoExecuteTaints` predicate checks if a pod tolerations can tolerate a node `NoExecute` taints. - -[source,yaml] ----- -{"name" : "PodToleratesNodeNoExecuteTaints"} ----- - -[id="admin-guide-scheduler-general-predicates_{context}"] -== General Predicates - -The following general predicates check whether non-critical predicates and essential predicates pass. Non-critical predicates are the predicates -that only non-critical pods must pass and essential predicates are the predicates that all pods must pass. - -_The default scheduler policy includes the general predicates._ - -[discrete] -=== Non-critical general predicates - -The `PodFitsResources` predicate determines a fit based on resource availability -(CPU, memory, GPU, and so forth). The -nodes can declare their resource capacities and then pods can specify what -resources they require. Fit is based on requested, rather than used -resources. - -[source,yaml] ----- -{"name" : "PodFitsResources"} ----- - -[discrete] -==== Essential general predicates - -The `PodFitsHostPorts` predicate determines if a node has free ports for the requested pod ports (absence -of port conflicts). - -[source,yaml] ----- -{"name" : "PodFitsHostPorts"} ----- - -The `HostName` predicate determines fit based on the presence of the Host parameter -and a string match with the name of the host. - -[source,yaml] ----- -{"name" : "HostName"} ----- - -The `MatchNodeSelector` predicate determines fit based on node selector (nodeSelector) queries -defined in the pod. - -[source,yaml] ----- -{"name" : "MatchNodeSelector"} ----- - -//// -[id="configurable-predicates_{context}"] -== Configurable Predicates - -// per sjenning Nope - -You can configure these predicates in the scheduler policy Configmap -in the `openshift-config` project, to add labels to affect -how the predicate functions. - -Since these are configurable, multiple predicates -of the same type (but different configuration parameters) can be combined as -long as their user-defined names are different. - -For information on using these priorities, see Modifying Scheduler Policy. - -*ServiceAffinity* places pods on nodes based on the service running on that pod. -Placing pods of the same service on the same or co-located nodes can lead to higher efficiency. - -This predicate attempts to place pods with specific labels -in its node selector on nodes that have the same label. - -If the pod does not specify the labels in its -node selector, then the first pod is placed on any node based on availability -and all subsequent pods of the service are scheduled on nodes that have the -same label values as that node. - -[source,json] ----- -"predicates":[ - { - "name":"<name>", <1> - "argument":{ - "serviceAffinity":{ - "labels":[ - "<label>" <2> - ] - } - } - } - ], ----- -<1> Specify a name for the predicate. -<2> Specify a label to match. - -For example: - -[source,json] ----- - "name":"ZoneAffinity", - "argument":{ - "serviceAffinity":{ - "labels":[ - "rack" - ] - } - } ----- - -For example. if the first pod of a service had a node selector `rack` was scheduled to a node with label `region=rack`, -all the other subsequent pods belonging to the same service will be scheduled on nodes -with the same `region=rack` label. - -Multiple-level labels are also supported. Users can also specify all pods for a service to -be scheduled on nodes within the same region and within the same zone (under the region). - -The `labelsPresence` parameter checks whether a particular node has a specific label. The labels create node _groups_ that the -`LabelPreference` priority uses. Matching by label can be useful, for example, where nodes have their physical location or status defined by labels. - -[source,json] ----- -"predicates":[ - { - "name":"<name>", <1> - "argument":{ - "labelsPresence":{ - "labels":[ - "<label>" <2> - ], - "presence": true <3> - } - } - } - ], ----- -<1> Specify a name for the predicate. -<2> Specify a label to match. -<3> Specify whether the labels are required, either `true` or `false`. -+ -* For `presence:false`, if any of the requested labels are present in the node labels, -the pod cannot be scheduled. If the labels are not present, the pod can be scheduled. -+ -* For `presence:true`, if all of the requested labels are present in the node labels, -the pod can be scheduled. If all of the labels are not present, the pod is not scheduled. - -For example: - -[source,json] ----- - "name":"RackPreferred", - "argument":{ - "labelsPresence":{ - "labels":[ - "rack", - "region" - ], - "presence": true - } - } ----- -//// diff --git a/modules/nodes-scheduler-default-priorities.adoc b/modules/nodes-scheduler-default-priorities.adoc deleted file mode 100644 index 5f8edba3ca0e..000000000000 --- a/modules/nodes-scheduler-default-priorities.adoc +++ /dev/null @@ -1,226 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-default.adoc - -[id="nodes-scheduler-default-priorities_{context}"] -= Understanding the scheduler priorities - -Priorities are rules that rank nodes according to preferences. - -A custom set of priorities can be specified to configure the scheduler. -There are several priorities provided by default in {product-title}. -Other priorities can be customized by providing certain -parameters. Multiple priorities can be combined and different weights -can be given to each to impact the prioritization. - -[id="static-priority-functions_{context}"] -== Static Priorities - -Static priorities do not take any configuration parameters from -the user, except weight. A weight is required to be specified and cannot be 0 or negative. - -These are specified in the scheduler policy config map in the `openshift-config` project. - -[id="default-priorities_{context}"] -=== Default Priorities - -The default scheduler policy includes the following priorities. Each of -the priority function has a weight of `1` except `NodePreferAvoidPodsPriority`, -which has a weight of `10000`. - -The `NodeAffinityPriority` priority prioritizes nodes according to node affinity scheduling preferences - -[source,yaml] ----- -{"name" : "NodeAffinityPriority", "weight" : 1} ----- - -The `TaintTolerationPriority` priority prioritizes nodes that have a fewer number of _intolerable_ taints on them for a pod. An intolerable taint is one which has key `PreferNoSchedule`. - -[source,yaml] ----- -{"name" : "TaintTolerationPriority", "weight" : 1} ----- - -The `ImageLocalityPriority` priority prioritizes nodes that already have requested pod container's images. - -[source,yaml] ----- -{"name" : "ImageLocalityPriority", "weight" : 1} ----- - -The `SelectorSpreadPriority` priority looks for services, replication controllers (RC), -replication sets (RS), and stateful sets that match the pod, -then finds existing pods that match those selectors. -The scheduler favors nodes that have fewer existing matching pods. Then, it schedules the pod on a node with the smallest number of -pods that match those selectors as the pod being scheduled. - -[source,yaml] ----- -{"name" : "SelectorSpreadPriority", "weight" : 1} ----- - -The `InterPodAffinityPriority` priority computes a sum by iterating through the elements of `weightedPodAffinityTerm` and adding -_weight_ to the sum if the corresponding PodAffinityTerm is satisfied for that node. The node(s) with the highest sum are the most preferred. - -[source,yaml] ----- -{"name" : "InterPodAffinityPriority", "weight" : 1} ----- - -The `LeastRequestedPriority` priority favors nodes with fewer requested resources. It -calculates the percentage of memory and CPU requested by pods scheduled on the -node, and prioritizes nodes that have the highest available/remaining capacity. - -[source,yaml] ----- -{"name" : "LeastRequestedPriority", "weight" : 1} ----- - -The `BalancedResourceAllocation` priority favors nodes with balanced resource usage rate. -It calculates the difference between the consumed CPU and memory as a fraction -of capacity, and prioritizes the nodes based on how close the two metrics are to -each other. This should always be used together with `LeastRequestedPriority`. - -[source,yaml] ----- -{"name" : "BalancedResourceAllocation", "weight" : 1} ----- - -The `NodePreferAvoidPodsPriority` priority ignores pods that are owned by a controller other than a replication controller. - -[source,yaml] ----- -{"name" : "NodePreferAvoidPodsPriority", "weight" : 10000} ----- - -[id="other-priorities_{context}"] -=== Other Static Priorities - -{product-title} also supports the following priorities: - -The `EqualPriority` priority gives an equal weight of `1` to all nodes, if no priority -configurations are provided. We recommend using this priority only for testing environments. - -[source,yaml] ----- -{"name" : "EqualPriority", "weight" : 1} ----- - -//https://github.com/kubernetes/kubernetes/issues/41712 -The `MostRequestedPriority` priority prioritizes nodes with most requested resources. It calculates the percentage of memory and CPU -requested by pods scheduled on the node, and prioritizes based on the maximum of the average of the fraction of requested to capacity. - -[source,yaml] ----- -{"name" : "MostRequestedPriority", "weight" : 1} ----- - -The `ServiceSpreadingPriority` priority spreads pods by minimizing the number of pods -belonging to the same service onto the same machine. - -[source,yaml] ----- -{"name" : "ServiceSpreadingPriority", "weight" : 1} ----- - -[id="configurable-priority-functions_{context}"] -== Configurable Priorities - -You can configure these priorities in the scheduler policy config map, -in the `openshift-config` namespace, to add labels to affect how the priorities work. - -The type of the priority -function is identified by the argument that they take. Since these are -configurable, multiple priorities of the same type (but different -configuration parameters) can be combined as long as their user-defined names -are different. - -For information on using these priorities, see Modifying Scheduler Policy. - -The `ServiceAntiAffinity` priority takes a label and ensures a good spread of the pods -belonging to the same service across the group of nodes based on the label -values. It gives the same score to all nodes that have the same value for the -specified label. It gives a higher score to nodes within a group with the least -concentration of pods. - -[source,json] ----- -{ -"kind": "Policy", -"apiVersion": "v1", - -"priorities":[ - { - "name":"<name>", <1> - "weight" : 1 <2> - "argument":{ - "serviceAntiAffinity":{ - "label": "<label>" <3> - } - } - } - ] -} ----- -<1> Specify a name for the priority. -<2> Specify a weight. Enter a non-zero positive value. -<3> Specify a label to match. - -For example: - -[source,json] ----- -{ -"kind": "Policy", -"apiVersion": "v1", -"priorities": [ - { - "name":"RackSpread", - "weight" : 1, - "argument": { - "serviceAntiAffinity": { - "label": "rack" - } - } - } - ] -} ----- - -[NOTE] -==== -In some situations using the `ServiceAntiAffinity` parameter based on custom labels does not spread pod as expected. -See link:https://access.redhat.com/solutions/3432401[this Red Hat Solution]. -==== - -The `labelPreference` parameter gives priority based on the specified label. -If the label is present on a node, that node is given priority. -If no label is specified, priority is given to nodes that do not have a label. -If multiple priorities with the `labelPreference` parameter are set, -all of the priorities must have the same weight. - -[source,json] ----- -{ -"kind": "Policy", -"apiVersion": "v1", -"priorities":[ - { - "name":"<name>", <1> - "weight" : 1 <2> - "argument":{ - "labelPreference":{ - "label": "<label>", <3> - "presence": true <4> - } - } - } - ] -} - ----- -<1> Specify a name for the priority. -<2> Specify a weight. Enter a non-zero positive value. -<3> Specify a label to match. -<4> Specify whether the label is required, either `true` or `false`. diff --git a/modules/nodes-scheduler-default-sample.adoc b/modules/nodes-scheduler-default-sample.adoc deleted file mode 100644 index 3c66058f728b..000000000000 --- a/modules/nodes-scheduler-default-sample.adoc +++ /dev/null @@ -1,221 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-default.adoc - -[id="nodes-scheduler-default-sample_{context}"] -= Sample Policy Configurations - -The configuration below specifies the default scheduler configuration, if it -were to be specified using the scheduler policy file. - -[source,yaml] ----- -{ -"kind": "Policy", -"apiVersion": "v1", -"predicates": [ - { - "name": "RegionZoneAffinity", <1> - "argument": { - "serviceAffinity": { <2> - "labels": ["region, zone"] <3> - } - } - } - ], -"priorities": [ - { - "name":"RackSpread", <4> - "weight" : 1, - "argument": { - "serviceAntiAffinity": { <5> - "label": "rack" <6> - } - } - } - ] -} ----- - -<1> The name for the predicate. -<2> The type of predicate. -<3> The labels for the predicate. -<4> The name for the priority. -<5> The type of priority. -<6> The labels for the priority. - - -In all of the sample configurations below, the list of predicates and priority -functions is truncated to include only the ones that pertain to the use case -specified. In practice, a complete/meaningful scheduler policy should include -most, if not all, of the default predicates and priorities listed above. - -The following example defines three topological levels, region (affinity) -> zone (affinity) -> rack (anti-affinity): - -[source,yaml] ----- -{ -"kind": "Policy", -"apiVersion": "v1", -"predicates": [ - { - "name": "RegionZoneAffinity", - "argument": { - "serviceAffinity": { - "labels": ["region, zone"] - } - } - } - ], -"priorities": [ - { - "name":"RackSpread", - "weight" : 1, - "argument": { - "serviceAntiAffinity": { - "label": "rack" - } - } - } - ] -} ----- - - -The following example defines three topological levels, `city` (affinity) -> `building` -(anti-affinity) -> `room` (anti-affinity): - -[source,yaml] ----- -{ -"kind": "Policy", -"apiVersion": "v1", -"predicates": [ - { - "name": "CityAffinity", - "argument": { - "serviceAffinity": { - "label": "city" - } - } - } - ], -"priorities": [ - { - "name":"BuildingSpread", - "weight" : 1, - "argument": { - "serviceAntiAffinity": { - "label": "building" - } - } - }, - { - "name":"RoomSpread", - "weight" : 1, - "argument": { - "serviceAntiAffinity": { - "label": "room" - } - } - } - ] -} ----- - -The following example defines a policy to only use nodes with the 'region' label defined and prefer nodes with the 'zone' -label defined: - -[source,yaml] ----- -{ -"kind": "Policy", -"apiVersion": "v1", -"predicates": [ - { - "name": "RequireRegion", - "argument": { - "labelPreference": { - "labels": ["region"], - "presence": true - } - } - } - ], -"priorities": [ - { - "name":"ZonePreferred", - "weight" : 1, - "argument": { - "labelPreference": { - "label": "zone", - "presence": true - } - } - } - ] -} ----- - -The following example combines both static and configurable predicates and -also priorities: - -[source,yaml] ----- -{ -"kind": "Policy", -"apiVersion": "v1", -"predicates": [ - { - "name": "RegionAffinity", - "argument": { - "serviceAffinity": { - "labels": ["region"] - } - } - }, - { - "name": "RequireRegion", - "argument": { - "labelsPresence": { - "labels": ["region"], - "presence": true - } - } - }, - { - "name": "BuildingNodesAvoid", - "argument": { - "labelsPresence": { - "label": "building", - "presence": false - } - } - }, - {"name" : "PodFitsPorts"}, - {"name" : "MatchNodeSelector"} - ], -"priorities": [ - { - "name": "ZoneSpread", - "weight" : 2, - "argument": { - "serviceAntiAffinity":{ - "label": "zone" - } - } - }, - { - "name":"ZonePreferred", - "weight" : 1, - "argument": { - "labelPreference":{ - "label": "zone", - "presence": true - } - } - }, - {"name" : "ServiceSpreadingPriority", "weight" : 1} - ] -} ----- diff --git a/modules/nodes-scheduler-node-affinity-about.adoc b/modules/nodes-scheduler-node-affinity-about.adoc deleted file mode 100644 index 18061e3c2cc5..000000000000 --- a/modules/nodes-scheduler-node-affinity-about.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-affinity.adoc - -[id="nodes-scheduler-node-affinity-about_{context}"] -= Understanding node affinity - -Node affinity allows a pod to specify an affinity towards a group of nodes it can be placed on. The node does not have control over the placement. - -For example, you could configure a pod to only run on a node with a specific CPU or in a specific availability zone. - -There are two types of node affinity rules: _required_ and _preferred_. - -Required rules *must* be met before a pod can be scheduled on a node. Preferred rules specify that, if the rule is met, the scheduler tries to enforce the rules, but does not guarantee enforcement. - -[NOTE] -==== -If labels on a node change at runtime that results in an node affinity rule on a pod no longer being met, the pod continues to run on the node. -==== - -You configure node affinity through the `Pod` spec file. You can specify a required rule, a preferred rule, or both. If you specify both, the node must first meet the required rule, then attempts to meet the preferred rule. - -The following example is a `Pod` spec with a rule that requires the pod be placed on a node with a label whose key is `e2e-az-NorthSouth` and whose value is either `e2e-az-North` or `e2e-az-South`: - -.Example pod configuration file with a node affinity required rule -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: with-node-affinity -spec: - affinity: - nodeAffinity: <1> - requiredDuringSchedulingIgnoredDuringExecution: <2> - nodeSelectorTerms: - - matchExpressions: - - key: e2e-az-NorthSouth <3> - operator: In <4> - values: - - e2e-az-North <3> - - e2e-az-South <3> - containers: - - name: with-node-affinity - image: docker.io/ocpqe/hello-pod ----- - -<1> The stanza to configure node affinity. -<2> Defines a required rule. -<3> The key/value pair (label) that must be matched to apply the rule. -<4> The operator represents the relationship between the label on the node and the set of values in the `matchExpression` parameters in the `Pod` spec. This value can be `In`, `NotIn`, `Exists`, or `DoesNotExist`, `Lt`, or `Gt`. - -The following example is a node specification with a preferred rule that a node with a label whose key is `e2e-az-EastWest` and whose value is either `e2e-az-East` or `e2e-az-West` is preferred for the pod: - -.Example pod configuration file with a node affinity preferred rule -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: with-node-affinity -spec: - affinity: - nodeAffinity: <1> - preferredDuringSchedulingIgnoredDuringExecution: <2> - - weight: 1 <3> - preference: - matchExpressions: - - key: e2e-az-EastWest <4> - operator: In <5> - values: - - e2e-az-East <4> - - e2e-az-West <4> - containers: - - name: with-node-affinity - image: docker.io/ocpqe/hello-pod ----- - -<1> The stanza to configure node affinity. -<2> Defines a preferred rule. -<3> Specifies a weight for a preferred rule. The node with highest weight is preferred. -<4> The key/value pair (label) that must be matched to apply the rule. -<5> The operator represents the relationship between the label on the node and -the set of values in the `matchExpression` parameters in the `Pod` spec. -This value can be `In`, `NotIn`, `Exists`, or `DoesNotExist`, `Lt`, or `Gt`. - -There is no explicit _node anti-affinity_ concept, but using the `NotIn` or `DoesNotExist` operator replicates that behavior. - -[NOTE] -==== -If you are using node affinity and node selectors in the same pod configuration, note the following: - -* If you configure both `nodeSelector` and `nodeAffinity`, both conditions must be satisfied for the pod to be scheduled onto a candidate node. - -* If you specify multiple `nodeSelectorTerms` associated with `nodeAffinity` types, then the pod can be scheduled onto a node if one of the `nodeSelectorTerms` is satisfied. - -* If you specify multiple `matchExpressions` associated with `nodeSelectorTerms`, then the pod can be scheduled onto a node only if all `matchExpressions` are satisfied. -==== - diff --git a/modules/nodes-scheduler-node-affinity-configuring-preferred.adoc b/modules/nodes-scheduler-node-affinity-configuring-preferred.adoc deleted file mode 100644 index b0911e3839db..000000000000 --- a/modules/nodes-scheduler-node-affinity-configuring-preferred.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-affinity.adoc - -[id="nodes-scheduler-node-affinity-configuring-preferred_{context}"] -= Configuring a preferred node affinity rule - -Preferred rules specify that, if the rule is met, the scheduler tries to enforce the rules, but does not guarantee enforcement. - -.Procedure - -The following steps demonstrate a simple configuration that creates a node and a pod that the scheduler tries to place on the node. - -. Add a label to a node using the `oc label node` command: -+ -[source,terminal] ----- -$ oc label node node1 e2e-az-name=e2e-az3 ----- - -. In the `Pod` spec, use the `nodeAffinity` stanza to configure the `preferredDuringSchedulingIgnoredDuringExecution` parameter: -+ -.. Specify a weight for the node, as a number 1-100. The node with highest weight is preferred. -+ -.. Specify the key and values that must be met. If you want the new pod to be scheduled on the node you edited, use the same `key` and `value` parameters as the label in the node: -+ -[source,yaml] ----- -spec: - affinity: - nodeAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 1 - preference: - matchExpressions: - - key: e2e-az-name - operator: In - values: - - e2e-az3 ----- -+ -.. Specify an `operator`. The operator can be `In`, `NotIn`, `Exists`, `DoesNotExist`, `Lt`, or `Gt`. For example, use the Operator `In` to require the label to be in the node. - -. Create the pod. -+ -[source,terminal] ----- -$ oc create -f e2e-az3.yaml ----- diff --git a/modules/nodes-scheduler-node-affinity-configuring-required.adoc b/modules/nodes-scheduler-node-affinity-configuring-required.adoc deleted file mode 100644 index 4427aec94eb7..000000000000 --- a/modules/nodes-scheduler-node-affinity-configuring-required.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-affinity.adoc - -[id="nodes-scheduler-node-affinity-configuring-required_{context}"] -= Configuring a required node affinity rule - -Required rules *must* be met before a pod can be scheduled on a node. - -.Procedure - -The following steps demonstrate a simple configuration that creates a node and a pod that the scheduler is required to place on the node. - -. Add a label to a node using the `oc label node` command: -+ -[source,terminal] ----- -$ oc label node node1 e2e-az-name=e2e-az1 ----- - -. In the `Pod` spec, use the `nodeAffinity` stanza to configure the `requiredDuringSchedulingIgnoredDuringExecution` parameter: -+ -.. Specify the key and values that must be met. If you want the new pod to be scheduled on the node you edited, use the same `key` and `value` parameters as the label in the node. -+ -.. Specify an `operator`. The operator can be `In`, `NotIn`, `Exists`, `DoesNotExist`, `Lt`, or `Gt`. For example, use the operator `In` to require the label to be in the node: -+ -.Example output -[source,yaml] ----- -spec: - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: e2e-az-name - operator: In - values: - - e2e-az1 - - e2e-az2 ----- - -. Create the pod: -+ -[source,terminal] ----- -$ oc create -f e2e-az2.yaml ----- diff --git a/modules/nodes-scheduler-node-affinity-example.adoc b/modules/nodes-scheduler-node-affinity-example.adoc deleted file mode 100644 index 36185b1e4de7..000000000000 --- a/modules/nodes-scheduler-node-affinity-example.adoc +++ /dev/null @@ -1,122 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-affinity.adoc - -[id="nodes-scheduler-node-affinity-examples_{context}"] -= Sample node affinity rules - -The following examples demonstrate node affinity. - -[id="admin-guide-sched-affinity-examples1_{context}"] -== Node affinity with matching labels - -The following example demonstrates node affinity for a node and pod with matching labels: - -* The Node1 node has the label `zone:us`: -+ -[source,terminal] ----- -$ oc label node node1 zone=us ----- - -* The pod-s1 pod has the `zone` and `us` key/value pair under a required node affinity rule: -+ -[source,terminal] ----- -$ cat pod-s1.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: pod-s1 -spec: - containers: - - image: "docker.io/ocpqe/hello-pod" - name: hello-pod - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: "zone" - operator: In - values: - - us ----- - -* The pod-s1 pod can be scheduled on Node1: -+ -[source,terminal] ----- -$ oc get pod -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE -pod-s1 1/1 Running 0 4m IP1 node1 ----- - -[id="admin-guide-sched-affinity-examples2_{context}"] -== Node affinity with no matching labels - -The following example demonstrates node affinity for a node and pod without matching labels: - -* The Node1 node has the label `zone:emea`: -+ -[source,terminal] ----- -$ oc label node node1 zone=emea ----- - -* The pod-s1 pod has the `zone` and `us` key/value pair under a required node affinity rule: -+ -[source,terminal] ----- -$ cat pod-s1.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: pod-s1 -spec: - containers: - - image: "docker.io/ocpqe/hello-pod" - name: hello-pod - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: "zone" - operator: In - values: - - us ----- - -* The pod-s1 pod cannot be scheduled on Node1: -+ -[source,terminal] ----- -$ oc describe pod pod-s1 ----- -+ -.Example output -[source,terminal] ----- -... - -Events: - FirstSeen LastSeen Count From SubObjectPath Type Reason - --------- -------- ----- ---- ------------- -------- ------ - 1m 33s 8 default-scheduler Warning FailedScheduling No nodes are available that match all of the following predicates:: MatchNodeSelector (1). ----- diff --git a/modules/nodes-scheduler-node-names-configuring.adoc b/modules/nodes-scheduler-node-names-configuring.adoc deleted file mode 100644 index 47bdf615b954..000000000000 --- a/modules/nodes-scheduler-node-names-configuring.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-names.adoc - -[id="nodes-scheduler-node-name-configuring_{context}"] -= Configuring the Pod Node Constraints admission controller to use names - -You can configure the Pod Node Constraints admission controller to ensure that pods are only placed onto nodes with a specific name. - -.Prerequisites - -Ensure you have the desired labels -ifdef::openshift-dedicated[] -(request changes by opening a support case on the -https://access.redhat.com/support/[Red Hat Customer Portal]) -endif::openshift-dedicated[] -and node selector set up in your environment. - -For example, make sure that your pod configuration features the `nodeName` -value indicating the desired label: - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -spec: - nodeName: <value> ----- - -.Procedure - -To configure the Pod Node Constraints admission controller: - -. Create a file containing the admission controller information: -+ -[source,yaml] ----- -podNodeSelectorPluginConfig: - clusterDefaultNodeSelector: name-of-node-selector - namespace1: name-of-node-selector - namespace2: name-of-node-selector ----- -+ -For example: -+ -[source,yaml] ----- -podNodeConstraintsPluginConfig: - clusterDefaultNodeSelector: ns1 - ns1: region=west,env=test,infra=fedora,os=fedora ----- - -. Create an *AdmissionConfiguration* object that references the file: -+ -[source,yaml] ----- -kind: AdmissionConfiguration -apiVersion: apiserver.k8s.io/v1alpha1 -plugins: -- name: PodNodeConstraints - path: podnodeconstraints.yaml ----- - diff --git a/modules/nodes-scheduler-node-projects-about.adoc b/modules/nodes-scheduler-node-projects-about.adoc deleted file mode 100644 index 85396cf06c66..000000000000 --- a/modules/nodes-scheduler-node-projects-about.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-projects.adoc - -[id="nodes-scheduler-node-projects-about_{context}"] -= Understanding how to constrain pods by project name - -The Pod Node Selector admission controller determines where a pod can be placed using labels on projects and node selectors specified in pods. A new pod will be placed on a node associated with a project only if the node selectors in the pod match the labels in the project. - -After the pod is created, the node selectors are merged into the pod so that the `Pod` spec includes the labels originally included in the specification and any new labels from the node selectors. The example below illustrates the merging effect. - -The Pod Node Selector admission controller also allows you to create a list of labels that are permitted in a specific project. This list acts as a whitelist that lets developers know what labels are acceptable to use in a project and gives administrators greater control over labeling in a cluster. - -The Pod Node Selector uses the annotation key `scheduler.alpha.kubernetes.io/node-selector` to assign node selectors to namespaces. - -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - annotations: - scheduler.alpha.kubernetes.io/node-selector: name-of-node-selector - name: namespace3 ----- - -This admission controller has the following behavior: - -. If the Namespace has an annotation with a key scheduler.alpha.kubernetes.io/node-selector, use its value as the node selector. -. If the namespace lacks such an annotation, use the `clusterDefaultNodeSelector` defined in the `PodNodeSelector` plug-in configuration file as the node selector. -. Evaluate the pod’s node selector against the namespace node selector for conflicts. Conflicts result in rejection. -. Evaluate the pod’s node selector against the namespace-specific whitelist defined the plug-in configuration file. Conflicts result in rejection. - - diff --git a/modules/nodes-scheduler-node-projects-configuring.adoc b/modules/nodes-scheduler-node-projects-configuring.adoc deleted file mode 100644 index fcc1f265e851..000000000000 --- a/modules/nodes-scheduler-node-projects-configuring.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-projects.adoc - -[id="nodes-scheduler-node-projects-configuring_{context}"] -= Configuring the Pod Node Selector admission controller to use projects - -You can configure the Pod Node Selector admission controller to ensure that pods are only placed onto nodes in specific projects. -The Pod Node Selector admission controller uses a configuration file to set options for the behavior of the backend. - -.Procedure - -. Create a file containing the admission controller information: -+ -[source,yaml] ----- -podNodeSelectorPluginConfig: - clusterDefaultNodeSelector: <node-selector> - namespace1: <node-selector> - namespace2: <node-selector> ----- -+ -For example: -+ -[source,yaml] ----- -podNodeSelectorPluginConfig: - clusterDefaultNodeSelector: region=west - ns1: os=centos,region=west ----- - -. Create an *AdmissionConfiguration* object that references the file: -+ -[source,yaml] ----- -kind: AdmissionConfiguration -apiVersion: apiserver.k8s.io/v1alpha1 -plugins: -- name: PodNodeSelector - path: podnodeselector.yaml ----- - - diff --git a/modules/nodes-scheduler-node-selectors-about.adoc b/modules/nodes-scheduler-node-selectors-about.adoc deleted file mode 100644 index 80471081a4fc..000000000000 --- a/modules/nodes-scheduler-node-selectors-about.adoc +++ /dev/null @@ -1,226 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-selector.adoc - -[id="nodes-scheduler-node-selectors-about_{context}"] -= About node selectors - -You can use node selectors on pods and labels on nodes to control where the pod is scheduled. With node selectors, {product-title} schedules the pods on nodes that contain matching labels. - -You can use a node selector to place specific pods on specific nodes, cluster-wide node selectors to place new pods on specific nodes anywhere in the cluster, and project node selectors to place new pods in a project on specific nodes. - -For example, as a cluster administrator, you can create an infrastructure where application developers can deploy pods only onto the nodes closest to their geographical location by including a node selector in every pod they create. In this example, the cluster consists of five data centers spread across two regions. In the U.S., label the nodes as `us-east`, `us-central`, or `us-west`. In the Asia-Pacific region (APAC), label the nodes as `apac-east` or `apac-west`. The developers can add a node selector to the pods they create to ensure the pods get scheduled on those nodes. - -A pod is not scheduled if the `Pod` object contains a node selector, but no node has a matching label. - -[IMPORTANT] -==== -If you are using node selectors and node affinity in the same pod configuration, the following rules control pod placement onto nodes: - -* If you configure both `nodeSelector` and `nodeAffinity`, both conditions must be satisfied for the pod to be scheduled onto a candidate node. - -* If you specify multiple `nodeSelectorTerms` associated with `nodeAffinity` types, then the pod can be scheduled onto a node if one of the `nodeSelectorTerms` is satisfied. - -* If you specify multiple `matchExpressions` associated with `nodeSelectorTerms`, then the pod can be scheduled onto a node only if all `matchExpressions` are satisfied. -==== - -Node selectors on specific pods and nodes:: -+ -You can control which node a specific pod is scheduled on by using node selectors and labels. -+ -To use node selectors and labels, first label the node to avoid pods being descheduled, then add the node selector to the pod. -+ -[NOTE] -==== -You cannot add a node selector directly to an existing scheduled pod. You must label the object that controls the pod, such as deployment config. -==== -+ -For example, the following `Node` object has the `region: east` label: -+ -.Sample `Node` object with a label -[source,yaml] ----- -kind: Node -apiVersion: v1 -metadata: - name: ip-10-0-131-14.ec2.internal - selfLink: /api/v1/nodes/ip-10-0-131-14.ec2.internal - uid: 7bc2580a-8b8e-11e9-8e01-021ab4174c74 - resourceVersion: '478704' - creationTimestamp: '2019-06-10T14:46:08Z' - labels: - beta.kubernetes.io/os: linux - failure-domain.beta.kubernetes.io/zone: us-east-1a - node.openshift.io/os_version: '4.5' - node-role.kubernetes.io/worker: '' - failure-domain.beta.kubernetes.io/region: us-east-1 - node.openshift.io/os_id: rhcos - beta.kubernetes.io/instance-type: m4.large - kubernetes.io/hostname: ip-10-0-131-14 - beta.kubernetes.io/arch: amd64 - region: east <1> ----- -<1> Label to match the pod node selector. -+ -A pod has the `type: user-node,region: east` node selector: -+ -.Sample `Pod` object with node selectors -[source,yaml] ----- -apiVersion: v1 -kind: Pod - -.... - -spec: - nodeSelector: <1> - region: east - type: user-node ----- -<1> Node selectors to match the node label. -+ -When you create the pod using the example pod spec, it can be scheduled on the example node. - -Default cluster-wide node selectors:: -+ -With default cluster-wide node selectors, when you create a pod in that cluster, {product-title} adds the default node selectors to the pod and schedules -the pod on nodes with matching labels. -+ -For example, the following `Scheduler` object has the default cluster-wide `region=east` and `type=user-node` node selectors: -+ -.Example Scheduler Operator Custom Resource -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Scheduler -metadata: - name: cluster -... - -spec: - defaultNodeSelector: type=user-node,region=east -... - ----- -+ -A node in that cluster has the `type=user-node,region=east` labels: -+ -.Example `Node` object -[source,yaml] ----- -apiVersion: v1 -kind: Node -metadata: - name: ci-ln-qg1il3k-f76d1-hlmhl-worker-b-df2s4 -... - labels: - region: east - type: user-node -... - ----- -+ -.Example `Pod` object with a node selector -[source,terminal] ----- -apiVersion: v1 -kind: Pod -... - -spec: - nodeSelector: - region: east -... - ----- -+ -When you create the pod using the example pod spec in the example cluster, the pod is created with the cluster-wide node selector and is scheduled on the labeled node: -+ -[source,terminal] -.Example pod list with the pod on the labeled node ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -pod-s1 1/1 Running 0 20s 10.131.2.6 ci-ln-qg1il3k-f76d1-hlmhl-worker-b-df2s4 <none> <none> ----- -+ -[NOTE] -==== -If the project where you create the pod has a project node selector, that selector takes preference over a cluster-wide node selector. Your pod is not created or scheduled if the pod does not have the project node selector. -==== - -Project node selectors:: -+ -With project node selectors, when you create a pod in this project, {product-title} adds the node selectors to the pod and schedules the pods on a node with matching labels. If there is a cluster-wide default node selector, a project node selector takes preference. -+ -For example, the following project has the `region=east` node selector: -+ -.Example `Namespace` object -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: east-region - annotations: - openshift.io/node-selector: "region=east" -... - ----- -+ -The following node has the `type=user-node,region=east` labels: -+ -.Example `Node` object -[source,yaml] ----- -apiVersion: v1 -kind: Node -metadata: - name: ci-ln-qg1il3k-f76d1-hlmhl-worker-b-df2s4 -... - labels: - region: east - type: user-node -... - ----- -+ -When you create the pod using the example pod spec in this example project, the pod is created with the project node selectors and is scheduled on the labeled node: -+ -.Example Pod object -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - namespace: east-region -... -spec: - nodeSelector: - region: east - type: user-node -... ----- -+ -[source,terminal] -.Example pod list with the pod on the labeled node ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -pod-s1 1/1 Running 0 20s 10.131.2.6 ci-ln-qg1il3k-f76d1-hlmhl-worker-b-df2s4 <none> <none> ----- -+ -A pod in the project is not created or scheduled if the pod contains different node selectors. For example, if you deploy the following pod into the example project, it is not be created: -+ -.Example Pod object with an invalid node selector -[source,yaml] ----- -apiVersion: v1 -kind: Pod -... - -spec: - nodeSelector: - region: west - -.... ----- - diff --git a/modules/nodes-scheduler-node-selectors-cluster.adoc b/modules/nodes-scheduler-node-selectors-cluster.adoc deleted file mode 100644 index f4f530c6f30c..000000000000 --- a/modules/nodes-scheduler-node-selectors-cluster.adoc +++ /dev/null @@ -1,167 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-selector.adoc - -[id="nodes-scheduler-node-selectors-cluster_{context}"] -= Creating default cluster-wide node selectors - -You can use default cluster-wide node selectors on pods together with labels on nodes to constrain all pods created in a cluster to specific nodes. - -With cluster-wide node selectors, when you create a pod in that cluster, {product-title} adds the default node selectors to the pod and schedules -the pod on nodes with matching labels. - -You configure cluster-wide node selectors by editing the Scheduler Operator custom resource (CR). You add labels to a node, a machine set, or a machine config. Adding the label to the machine set ensures that if the node or machine goes down, new nodes have the label. Labels added to a node or machine config do not persist if the node or machine goes down. - -[NOTE] -==== -You can add additional key/value pairs to a pod. But you cannot add a different value for a default key. -==== - -.Procedure - -To add a default cluster-wide node selector: - -. Edit the Scheduler Operator CR to add the default cluster-wide node selectors: -+ -[source,terminal] ----- -$ oc edit scheduler cluster ----- -+ -.Example Scheduler Operator CR with a node selector -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Scheduler -metadata: - name: cluster -... - -spec: - defaultNodeSelector: type=user-node,region=east <1> - mastersSchedulable: false - policy: - name: "" ----- -<1> Add a node selector with the appropriate `<key>:<value>` pairs. -+ -After making this change, wait for the pods in the `openshift-kube-apiserver` project to redeploy. This can take several minutes. The default cluster-wide node selector does not take effect until the pods redeploy. - -. Add labels to a node by using a machine set or editing the node directly: - -* Use a machine set to add labels to nodes managed by the machine set when a node is created: - -.. Run the following command to add labels to a `MachineSet` object: -+ -[source,terminal] ----- -$ oc patch MachineSet <name> --type='json' -p='[{"op":"add","path":"/spec/template/spec/metadata/labels", "value":{"<key>"="<value>","<key>"="<value>"}}]' -n openshift-machine-api <1> ----- -<1> Add a `<key>/<value>` pair for each label. -+ -For example: -+ -[source,terminal] ----- -$ oc patch MachineSet ci-ln-l8nry52-f76d1-hl7m7-worker-c --type='json' -p='[{"op":"add","path":"/spec/template/spec/metadata/labels", "value":{"type":"user-node","region":"east"}}]' -n openshift-machine-api ----- -+ -.. Verify that the labels are added to the `MachineSet` object by using the `oc edit` command: -+ -For example: -+ -[source,terminal] ----- -$ oc edit MachineSet ci-ln-l8nry52-f76d1-hl7m7-worker-c -n openshift-machine-api ----- -+ -.Example output -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: -... -spec: -... - template: - metadata: -... - spec: - metadata: - labels: - region: east - type: user-node ----- - -.. Redeploy the nodes associated with that machine set by scaling down to `0` and scaling up the nodes: -+ -For example: -+ -[source,terminal] ----- -$ oc scale --replicas=0 MachineSet ci-ln-l8nry52-f76d1-hl7m7-worker-c -n openshift-machine-api ----- -+ -[source,terminal] ----- -$ oc scale --replicas=1 MachineSet ci-ln-l8nry52-f76d1-hl7m7-worker-c -n openshift-machine-api ----- - -.. When the nodes are ready and available, verify that the label is added to the nodes by using the `oc get` command: -+ -[source,terminal] ----- -$ oc get nodes -l <key>=<value> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get nodes -l type=user-node ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ci-ln-l8nry52-f76d1-hl7m7-worker-c-vmqzp Ready worker 61s v1.18.3+002a51f ----- - -* Add labels directly to a node: - -.. Edit the `Node` object for the node: -+ -[source,terminal] ----- -$ oc label nodes <name> <key>=<value> ----- -+ -For example, to label a node: -+ -[source,terminal] ----- -$ oc label nodes ci-ln-l8nry52-f76d1-hl7m7-worker-b-tgq49 type=user-node region=east ----- - -.. Verify that the labels are added to the node using the `oc get` command: -+ -[source,terminal] ----- -$ oc get nodes -l <key>=<value>,<key>=<value> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get nodes -l type=user-node,region=east ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ci-ln-l8nry52-f76d1-hl7m7-worker-b-tgq49 Ready worker 17m v1.18.3+002a51f ----- diff --git a/modules/nodes-scheduler-node-selectors-configuring.adoc b/modules/nodes-scheduler-node-selectors-configuring.adoc deleted file mode 100644 index 0d21c9805091..000000000000 --- a/modules/nodes-scheduler-node-selectors-configuring.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-selector.adoc - -[id="nodes-scheduler-node-selectors-configuring_{context}"] -= Configuring the Pod Node Constraints admission controller to use node selectors - -You can configure the Pod Node Constraints admission controller to ensure that pods are only placed onto nodes with specific labels. - -.Prerequisites - -. Ensure you have the desired labels -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -labels on your nodes. -endif::openshift-enterprise,openshift-webscale,openshift-origin[] -ifdef::openshift-dedicated[] -labels on your nodes (request changes by opening a support case on the -https://access.redhat.com/support/[Red Hat Customer Portal]). -endif::openshift-dedicated[] -and node selector set up in your environment. -+ -For example, make sure that your pod configuration features the `nodeSelector` -value indicating the desired label: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -spec: - nodeSelector: - <key>: <value> -... ----- - -. Create a file containing the admission controller information: -+ -[source,yaml] ----- -podNodeSelectorPluginConfig: - clusterDefaultNodeSelector: name-of-node-selector - namespace1: name-of-node-selector - namespace2: name-of-node-selector ----- -+ -For example: -+ -[source,yaml] ----- -podNodeConstraintsPluginConfig: - clusterDefaultNodeSelector: ns1 - ns1: region=west,env=test,infra=fedora,os=fedora ----- - -. Create an *AdmissionConfiguration* object that references the file: -+ -[source,yaml] ----- -kind: AdmissionConfiguration -apiVersion: apiserver.k8s.io/v1alpha1 -plugins: -- name: PodNodeConstraints - path: podnodeconstraints.yaml - nodeSelectorLabelBlacklist: - kubernetes.io/hostname - - <label> ----- - -[NOTE] -==== -If you are using node selectors and node affinity in the same pod configuration, note the following: - -* If you configure both `nodeSelector` and `nodeAffinity`, both conditions must be satisfied for the pod to be scheduled onto a candidate node. - -* If you specify multiple `nodeSelectorTerms` associated with `nodeAffinity` types, then the pod can be scheduled onto a node if one of the `nodeSelectorTerms` is satisfied. - -* If you specify multiple `matchExpressions` associated with `nodeSelectorTerms`, then the pod can be scheduled onto a node only if all `matchExpressions` are satisfied. -==== - diff --git a/modules/nodes-scheduler-node-selectors-pod.adoc b/modules/nodes-scheduler-node-selectors-pod.adoc deleted file mode 100644 index 7a8b3fe4d6a0..000000000000 --- a/modules/nodes-scheduler-node-selectors-pod.adoc +++ /dev/null @@ -1,184 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-selector.adoc - -[id="nodes-scheduler-node-selectors-pod_{context}"] -= Using node selectors to control pod placement - -You can use node selectors on pods and labels on nodes to control where the pod is scheduled. With node selectors, {product-title} schedules the pods on nodes that contain matching labels. - -You add labels to a node, a machine set, or a machine config. Adding the label to the machine set ensures that if the node or machine goes down, new nodes have the label. Labels added to a node or machine config do not persist if the node or machine goes down. - -To add node selectors to an existing pod, add a node selector to the controlling object for that pod, such as a `ReplicaSet` object, `DaemonSet` object, `StatefulSet` object, `Deployment` object, or `DeploymentConfig` object. -Any existing pods under that controlling object are recreated on a node with a matching label. If you are creating a new pod, you can add the node selector directly to the `Pod` spec. - -[NOTE] -==== -You cannot add a node selector directly to an existing scheduled pod. -==== - -.Prerequisites - -To add a node selector to existing pods, determine the controlling object for that pod. -For example, the `router-default-66d5cf9464-m2g75` pod is controlled by the `router-default-66d5cf9464` -replica set: - -[source,terminal] ----- -$ oc describe pod router-default-66d5cf9464-7pwkc ----- - -.Example output -[source,yaml] ----- -Name: router-default-66d5cf9464-7pwkc -Namespace: openshift-ingress - -.... - -Controlled By: ReplicaSet/router-default-66d5cf9464 ----- - -The web console lists the controlling object under `ownerReferences` in the pod YAML: - -.Example output -[source,yaml] ----- - ownerReferences: - - apiVersion: apps/v1 - kind: ReplicaSet - name: router-default-66d5cf9464 - uid: d81dd094-da26-11e9-a48a-128e7edf0312 - controller: true - blockOwnerDeletion: true ----- - -.Procedure - -. Add labels to a node by using a machine set or editing the node directly: - -* Use a `MachineSet` object to add labels to nodes managed by the machine set when a node is created: - -.. Run the following command to add labels to a `MachineSet` object: -+ -[source,terminal] ----- -$ oc patch MachineSet <name> --type='json' -p='[{"op":"add","path":"/spec/template/spec/metadata/labels", "value":{"<key>"="<value>","<key>"="<value>"}}]' -n openshift-machine-api ----- -+ -For example: -+ -[source,terminal] ----- -$ oc patch MachineSet abc612-msrtw-worker-us-east-1c --type='json' -p='[{"op":"add","path":"/spec/template/spec/metadata/labels", "value":{"type":"user-node","region":"east"}}]' -n openshift-machine-api ----- - -.. Verify that the labels are added to the `MachineSet` object by using the `oc edit` command: -+ -For example: -+ -[source,terminal] ----- -$ oc edit MachineSet abc612-msrtw-worker-us-east-1c -n openshift-machine-api ----- -+ -.Example `MachineSet` object -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet - -.... - -spec: -... - template: - metadata: -... - spec: - metadata: - labels: - region: east - type: user-node -.... ----- - -* Add labels directly to a node: - -.. Edit the `Node` object for the node: -+ -[source,terminal] ----- -$ oc label nodes <name> <key>=<value> ----- -+ -For example, to label a node: -+ -[source,terminal] ----- -$ oc label nodes ip-10-0-142-25.ec2.internal type=user-node region=east ----- - -.. Verify that the labels are added to the node: -+ -[source,terminal] ----- -$ oc get nodes -l type=user-node,region=east ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-142-25.ec2.internal Ready worker 17m v1.18.3+002a51f ----- - -. Add the matching node selector a pod: -+ -* To add a node selector to existing and future pods, add a node selector to the controlling object for the pods: -+ -.Example `ReplicaSet` object with labels -[source,yaml] ----- -kind: ReplicaSet - -.... - -spec: - -.... - - template: - metadata: - creationTimestamp: null - labels: - ingresscontroller.operator.openshift.io/deployment-ingresscontroller: default - pod-template-hash: 66d5cf9464 - spec: - nodeSelector: - beta.kubernetes.io/os: linux - node-role.kubernetes.io/worker: '' - type: user-node <1> ----- -<1> Add the node selector. - -* To add a node selector to a specific, new pod, add the selector to the `Pod` object directly: -+ -.Example `Pod` object with a node selector -[source,yaml] ----- -apiVersion: v1 -kind: Pod - -.... - -spec: - nodeSelector: - region: east - type: user-node ----- -+ -[NOTE] -==== -You cannot add a node selector directly to an existing scheduled pod. -==== diff --git a/modules/nodes-scheduler-node-selectors-project.adoc b/modules/nodes-scheduler-node-selectors-project.adoc deleted file mode 100644 index a1b23b062253..000000000000 --- a/modules/nodes-scheduler-node-selectors-project.adoc +++ /dev/null @@ -1,180 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-selector.adoc - -[id="nodes-scheduler-node-selectors-project_{context}"] -= Creating project-wide node selectors - -You can use node selectors in a project together with labels on nodes to constrain all pods created in that project to the labeled nodes. - -When you create a pod in this project, {product-title} adds the node selectors to the pods in the project and schedules the pods on a node with matching labels in the project. If there is a cluster-wide default node selector, a project node selector takes preference. - -You add node selectors to a project by editing the `Namespace` object to add the `openshift.io/node-selector` parameter. You add labels to a node, a machine set, or a machine config. Adding the label to the machine set ensures that if the node or machine goes down, new nodes have the label. Labels added to a node or machine config do not persist if the node or machine goes down. - -A pod is not scheduled if the `Pod` object contains a node selector, but no project has a matching node selector. When you create a pod from that spec, you receive an error similar to the following message: - -.Example error message -[source,terminal] ----- -Error from server (Forbidden): error when creating "pod.yaml": pods "pod-4" is forbidden: pod node label selector conflicts with its project node label selector ----- - -[NOTE] -==== -You can add additional key/value pairs to a pod. But you cannot add a different value for a project key. -==== - -.Procedure - -To add a default project node selector: - -. Create a project or edit an existing project to add the `openshift.io/node-selector` parameter: -+ -[source,terminal] ----- -$ oc edit project <name> ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -kind: Project -metadata: - annotations: - openshift.io/node-selector: "type=user-node,region=east" <1> - openshift.io/sa.scc.mcs: s0:c17,c14 - openshift.io/sa.scc.supplemental-groups: 1000300000/10000 - openshift.io/sa.scc.uid-range: 1000300000/10000 - creationTimestamp: 2019-06-10T14:39:45Z - labels: - openshift.io/run-level: "0" - name: demo - resourceVersion: "401885" - selfLink: /api/v1/namespaces/openshift-kube-apiserver - uid: 96ecc54b-8b8d-11e9-9f54-0a9ae641edd0 -spec: - finalizers: - - kubernetes -status: - phase: Active ----- -<1> Add the `openshift.io/node-selector` with the appropriate `<key>:<value>` pairs. - -. Add labels to a node by using a machine set or editing the node directly: - -* Use a `MachineSet` object to add labels to nodes managed by the machine set when a node is created: - -.. Run the following command to add labels to a `MachineSet` object: -+ -[source,terminal] ----- -$ oc patch MachineSet <name> --type='json' -p='[{"op":"add","path":"/spec/template/spec/metadata/labels", "value":{"<key>"="<value>","<key>"="<value>"}}]' -n openshift-machine-api ----- -+ -For example: -+ -[source,terminal] ----- -$ oc patch MachineSet ci-ln-l8nry52-f76d1-hl7m7-worker-c --type='json' -p='[{"op":"add","path":"/spec/template/spec/metadata/labels", "value":{"type":"user-node","region":"east"}}]' -n openshift-machine-api ----- - -.. Verify that the labels are added to the `MachineSet` object by using the `oc edit` command: -+ -For example: -+ -[source,terminal] ----- -$ oc edit MachineSet ci-ln-l8nry52-f76d1-hl7m7-worker-c -n openshift-machine-api ----- -+ -.Example output -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: -... -spec: -... - template: - metadata: -... - spec: - metadata: - labels: - region: east - type: user-node ----- - -.. Redeploy the nodes associated with that machine set: -+ -For example: -+ -[source,terminal] ----- -$ oc scale --replicas=0 MachineSet ci-ln-l8nry52-f76d1-hl7m7-worker-c -n openshift-machine-api ----- -+ -[source,terminal] ----- -$ oc scale --replicas=1 MachineSet ci-ln-l8nry52-f76d1-hl7m7-worker-c -n openshift-machine-api ----- - -.. When the nodes are ready and available, verify that the label is added to the nodes by using the `oc get` command: -+ -[source,terminal] ----- -$ oc get nodes -l <key>=<value> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get nodes -l type=user-node ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ci-ln-l8nry52-f76d1-hl7m7-worker-c-vmqzp Ready worker 61s v1.18.3+002a51f ----- - -* Add labels directly to a node: - -.. Edit the `Node` object to add labels: -+ -[source,terminal] ----- -$ oc label <resource> <name> <key>=<value> ----- -+ -For example, to label a node: -+ -[source,terminal] ----- -$ oc label nodes ci-ln-l8nry52-f76d1-hl7m7-worker-c-tgq49 type=user-node region=east ----- - -.. Verify that the labels are added to the `Node` object using the `oc get` command: -+ -[source,terminal] ----- -$ oc get nodes -l <key>=<value> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc get nodes -l type=user-node,region=east ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ci-ln-l8nry52-f76d1-hl7m7-worker-b-tgq49 Ready worker 17m v1.18.3+002a51f ----- diff --git a/modules/nodes-scheduler-pod-affinity-about.adoc b/modules/nodes-scheduler-pod-affinity-about.adoc deleted file mode 100644 index 4bb3d98f9128..000000000000 --- a/modules/nodes-scheduler-pod-affinity-about.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-pod-affinity.adoc - -[id="nodes-scheduler-pod-affinity-about_{context}"] -= Understanding pod affinity - -_Pod affinity_ and _pod anti-affinity_ allow you to constrain which nodes your pod is eligible to be scheduled on based on the key/value labels on other pods. - -* Pod affinity can tell the scheduler to locate a new pod on the same node as other pods if the label selector on the new pod matches the label on the current pod. -* Pod anti-affinity can prevent the scheduler from locating a new pod on the same node as pods with the same labels if the label selector on the new pod matches the label on the current pod. - -For example, using affinity rules, you could spread or pack pods within a service or relative to pods in other services. Anti-affinity rules allow you to prevent pods of a particular service from scheduling on the same nodes as pods of another service that are known to interfere with the performance of the pods of the first service. Or, you could spread the pods of a service across nodes or availability zones to reduce correlated failures. - -There are two types of pod affinity rules: _required_ and _preferred_. - -Required rules *must* be met before a pod can be scheduled on a node. Preferred rules specify that, if the rule is met, the scheduler tries to enforce the rules, but does not guarantee enforcement. - -[NOTE] -==== -Depending on your pod priority and preemption settings, the scheduler might not be able to find an appropriate node for a pod without violating affinity -requirements. If so, a pod might not be scheduled. - -To prevent this situation, carefully configure pod affinity with equal-priority pods. -==== - -You configure pod affinity/anti-affinity through the `Pod` spec files. You can specify a required rule, a preferred rule, or both. If you specify both, the node must first meet the required rule, then attempts to meet the preferred rule. - -The following example shows a `Pod` spec configured for pod affinity and anti-affinity. - -In this example, the pod affinity rule indicates that the pod can schedule onto a node only if that node has at least one already-running pod with a label that has the key `security` and value `S1`. The pod anti-affinity rule says that the pod prefers to not schedule onto a node if that node is already running a pod with label having key `security` and value `S2`. - -.Sample `Pod` config file with pod affinity -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: with-pod-affinity -spec: - affinity: - podAffinity: <1> - requiredDuringSchedulingIgnoredDuringExecution: <2> - - labelSelector: - matchExpressions: - - key: security <3> - operator: In <4> - values: - - S1 <3> - topologyKey: failure-domain.beta.kubernetes.io/zone - containers: - - name: with-pod-affinity - image: docker.io/ocpqe/hello-pod ----- - -<1> Stanza to configure pod affinity. -<2> Defines a required rule. -<3> The key and value (label) that must be matched to apply the rule. -<4> The operator represents the relationship between the label on the existing pod and the set of values in the `matchExpression` parameters in the specification for the new pod. Can be `In`, `NotIn`, `Exists`, or `DoesNotExist`. - -.Sample `Pod` config file with pod anti-affinity -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: with-pod-antiaffinity -spec: - affinity: - podAntiAffinity: <1> - preferredDuringSchedulingIgnoredDuringExecution: <2> - - weight: 100 <3> - podAffinityTerm: - labelSelector: - matchExpressions: - - key: security <4> - operator: In <5> - values: - - S2 - topologyKey: kubernetes.io/hostname - containers: - - name: with-pod-affinity - image: docker.io/ocpqe/hello-pod ----- - -<1> Stanza to configure pod anti-affinity. -<2> Defines a preferred rule. -<3> Specifies a weight for a preferred rule. The node with the highest weight is preferred. -<4> Description of the pod label that determines when the anti-affinity rule applies. Specify a key and value for the label. -<5> The operator represents the relationship between the label on the existing pod and the set of values in the `matchExpression` parameters in the specification for the new pod. Can be `In`, `NotIn`, `Exists`, or `DoesNotExist`. - -[NOTE] -==== -If labels on a node change at runtime such that the affinity rules on a pod are no longer met, the pod continues to run on the node. -==== - diff --git a/modules/nodes-scheduler-pod-affinity-configuring.adoc b/modules/nodes-scheduler-pod-affinity-configuring.adoc deleted file mode 100644 index 761d95ec6360..000000000000 --- a/modules/nodes-scheduler-pod-affinity-configuring.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-pod-affinity.adoc - -[id="nodes-scheduler-pod-affinity-configuring_{context}"] -= Configuring a pod affinity rule - -The following steps demonstrate a simple two-pod configuration that creates pod with a label and a pod that uses affinity to allow scheduling with that pod. - -.Procedure - -. Create a pod with a specific label in the `Pod` spec: -+ -[source,yaml] ----- -$ cat team4.yaml -apiVersion: v1 -kind: Pod -metadata: - name: security-s1 - labels: - security: S1 -spec: - containers: - - name: security-s1 - image: docker.io/ocpqe/hello-pod ----- - -. When creating other pods, edit the `Pod` spec as follows: -+ -.. Use the `podAffinity` stanza to configure the `requiredDuringSchedulingIgnoredDuringExecution` parameter or `preferredDuringSchedulingIgnoredDuringExecution` parameter: -+ -.. Specify the key and value that must be met. If you want the new pod to be scheduled with the other pod, use the same `key` and `value` parameters as the label on the first pod. -+ -[source,yaml] ----- - podAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - - labelSelector: - matchExpressions: - - key: security - operator: In - values: - - S1 - topologyKey: failure-domain.beta.kubernetes.io/zone ----- -+ -.. Specify an `operator`. The operator can be `In`, `NotIn`, `Exists`, or `DoesNotExist`. For example, use the operator `In` to require the label to be in the node. -+ -.. Specify a `topologyKey`, which is a prepopulated link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#interlude-built-in-node-labels[Kubernetes label] that the system uses to denote such a topology domain. - -. Create the pod. -+ -[source,terminal] ----- -$ oc create -f <pod-spec>.yaml ----- diff --git a/modules/nodes-scheduler-pod-affinity-example.adoc b/modules/nodes-scheduler-pod-affinity-example.adoc deleted file mode 100644 index 1b2cb5c1378e..000000000000 --- a/modules/nodes-scheduler-pod-affinity-example.adoc +++ /dev/null @@ -1,162 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-node-affinity.adoc - -[id="nodes-scheduler-pod-affinity-example_{context}"] -= Sample pod affinity and anti-affinity rules - -The following examples demonstrate pod affinity and pod anti-affinity. - -[id="nodes-scheduler-pod-affinity-example-affinity_{context}"] -== Pod Affinity - -The following example demonstrates pod affinity for pods with matching labels and label selectors. - -* The pod *team4* has the label `team:4`. -+ -[source,yaml] ----- -$ cat team4.yaml -apiVersion: v1 -kind: Pod -metadata: - name: team4 - labels: - team: "4" -spec: - containers: - - name: ocp - image: docker.io/ocpqe/hello-pod ----- - -* The pod *team4a* has the label selector `team:4` under `podAffinity`. -+ -[source,yaml] ----- -$ cat pod-team4a.yaml -apiVersion: v1 -kind: Pod -metadata: - name: team4a -spec: - affinity: - podAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - - labelSelector: - matchExpressions: - - key: team - operator: In - values: - - "4" - topologyKey: kubernetes.io/hostname - containers: - - name: pod-affinity - image: docker.io/ocpqe/hello-pod ----- - -* The *team4a* pod is scheduled on the same node as the *team4* pod. - -[id="nodes-scheduler-pod-affinity-example-antiaffinity_{context}"] -== Pod Anti-affinity - -The following example demonstrates pod anti-affinity for pods with matching labels and label selectors. - -* The pod *pod-s1* has the label `security:s1`. -+ -[source,yaml] ----- -cat pod-s1.yaml -apiVersion: v1 -kind: Pod -metadata: - name: pod-s1 - labels: - security: s1 -spec: - containers: - - name: ocp - image: docker.io/ocpqe/hello-pod ----- - -* The pod *pod-s2* has the label selector `security:s1` under `podAntiAffinity`. -+ -[source,yaml] ----- -cat pod-s2.yaml -apiVersion: v1 -kind: Pod -metadata: - name: pod-s2 -spec: - affinity: - podAntiAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - - labelSelector: - matchExpressions: - - key: security - operator: In - values: - - s1 - topologyKey: kubernetes.io/hostname - containers: - - name: pod-antiaffinity - image: docker.io/ocpqe/hello-pod ----- - -* The pod *pod-s2* cannot be scheduled on the same node as `pod-s1`. - -[id="nodes-scheduler-pod-affinity-example-no-labels_{context}"] -== Pod Affinity with no Matching Labels - -The following example demonstrates pod affinity for pods without matching labels and label selectors. - -* The pod *pod-s1* has the label `security:s1`. -+ -[source,yaml] ----- -$ cat pod-s1.yaml -apiVersion: v1 -kind: Pod -metadata: - name: pod-s1 - labels: - security: s1 -spec: - containers: - - name: ocp - image: docker.io/ocpqe/hello-pod ----- - -* The pod *pod-s2* has the label selector `security:s2`. -+ -[source,yaml] ----- -$ cat pod-s2.yaml -apiVersion: v1 -kind: Pod -metadata: - name: pod-s2 -spec: - affinity: - podAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - - labelSelector: - matchExpressions: - - key: security - operator: In - values: - - s2 - topologyKey: kubernetes.io/hostname - containers: - - name: pod-affinity - image: docker.io/ocpqe/hello-pod ----- - -* The pod *pod-s2* is not scheduled unless there is a node with a pod that has the `security:s2` label. If there is no other pod with that label, the new pod remains in a pending state: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE -pod-s2 0/1 Pending 0 32s <none> ----- diff --git a/modules/nodes-scheduler-pod-anti-affinity-configuring.adoc b/modules/nodes-scheduler-pod-anti-affinity-configuring.adoc deleted file mode 100644 index 1616444fad9c..000000000000 --- a/modules/nodes-scheduler-pod-anti-affinity-configuring.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-pod-affinity.adoc - -[id="nodes-scheduler-pod-anti-affinity-configuring_{context}"] -= Configuring a pod anti-affinity rule - -The following steps demonstrate a simple two-pod configuration that creates pod with a label and a pod that uses an anti-affinity preferred rule to attempt to prevent scheduling with that pod. - -.Procedure - -. Create a pod with a specific label in the `Pod` spec: -+ -[source,yaml] ----- -$ cat team4.yaml -apiVersion: v1 -kind: Pod -metadata: - name: security-s2 - labels: - security: S2 -spec: - containers: - - name: security-s2 - image: docker.io/ocpqe/hello-pod ----- - -. When creating other pods, edit the `Pod` spec to set the following parameters: - -. Use the `podAntiAffinity` stanza to configure the `requiredDuringSchedulingIgnoredDuringExecution` parameter or `preferredDuringSchedulingIgnoredDuringExecution` parameter: -+ -.. Specify a weight for the node, 1-100. The node that with highest weight is preferred. -+ -.. Specify the key and values that must be met. If you want the new pod to not be scheduled with the other pod, use the same `key` and `value` parameters as the label on the first pod. -+ -[source,yaml] ----- - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: security - operator: In - values: - - S2 - topologyKey: kubernetes.io/hostname ----- -+ -.. For a preferred rule, specify a weight, 1-100. -+ -.. Specify an `operator`. The operator can be `In`, `NotIn`, `Exists`, or `DoesNotExist`. For example, use the operator `In` to require the label to be in the node. - -. Specify a `topologyKey`, which is a prepopulated link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#interlude-built-in-node-labels[Kubernetes label] that the system uses to denote such a topology domain. - -. Create the pod. -+ -[source,terminal] ----- -$ oc create -f <pod-spec>.yaml ----- diff --git a/modules/nodes-scheduler-pod-topology-spread-constraints-about.adoc b/modules/nodes-scheduler-pod-topology-spread-constraints-about.adoc deleted file mode 100644 index 70cd7ebefb8b..000000000000 --- a/modules/nodes-scheduler-pod-topology-spread-constraints-about.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-scheduler-pod-topology-spread-constraints - -[id="nodes-scheduler-pod-topology-spread-constraints-about_{context}"] -= About pod topology spread constraints - -By using a _pod topology spread constraint_, you provide fine-grained control over the distribution of pods across failure domains to help achieve high availability and more efficient resource utilization. - -{product-title} administrators can label nodes to provide topology information, such as regions, zones, nodes, or other user-defined domains. After these labels are set on nodes, users can then define pod topology spread constraints to control the placement of pods across these topology domains. - -You specify which pods to group together, which topology domains they are spread among, and the acceptable skew. Only pods within the same namespace are matched and grouped together when spreading due to a constraint. - -// TODO Mention about relationship to affinity/anti-affinity? diff --git a/modules/nodes-scheduler-pod-topology-spread-constraints-configuring.adoc b/modules/nodes-scheduler-pod-topology-spread-constraints-configuring.adoc deleted file mode 100644 index dbe4bb54f9cd..000000000000 --- a/modules/nodes-scheduler-pod-topology-spread-constraints-configuring.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-scheduler-pod-topology-spread-constraints - -[id="nodes-scheduler-pod-topology-spread-constraints-configuring_{context}"] -= Configuring pod topology spread constraints - -The following steps demonstrate how to configure pod topology spread constraints to distribute pods that match the specified labels based on their zone. - -You can specify multiple pod topology spread constraints, but you must ensure that they do not conflict with each other. All pod topology spread constraints must be satisfied for a pod to be placed. - -.Prerequisites - -* A cluster administrator has added the required labels to nodes. - -.Procedure - -. Create a `Pod` spec and specify a pod topology spread constraint: -+ -.Example `pod-spec.yaml` file -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: my-pod - labels: - foo: bar -spec: - topologySpreadConstraints: - - maxSkew: 1 <1> - topologyKey: topology.kubernetes.io/zone <2> - whenUnsatisfiable: DoNotSchedule <3> - labelSelector: <4> - matchLabels: - foo: bar <5> - containers: - - image: "docker.io/ocpqe/hello-pod" - name: hello-pod ----- -<1> The maximum difference in number of pods between any two topology domains. The default is `1`, and you cannot specify a value of `0`. -<2> The key of a node label. Nodes with this key and identical value are considered to be in the same topology. -<3> How to handle a pod if it does not satisfy the spread constraint. The default is `DoNotSchedule`, which tells the scheduler not to schedule the pod. Set to `ScheduleAnyway` to still schedule the pod, but the scheduler prioritizes honoring the skew to not make the cluster more imbalanced. -<4> Pods that match this label selector are counted and recognized as a group when spreading to satisfy the constraint. Be sure to specify a label selector, otherwise no pods can be matched. -<5> Be sure that this `Pod` spec also sets its labels to match this label selector if you want it to be counted properly in the future. - -. Create the pod: -+ -[source,terminal] ----- -$ oc create -f pod-spec.yaml ----- diff --git a/modules/nodes-scheduler-pod-topology-spread-constraints-examples.adoc b/modules/nodes-scheduler-pod-topology-spread-constraints-examples.adoc deleted file mode 100644 index cc440e1bc29e..000000000000 --- a/modules/nodes-scheduler-pod-topology-spread-constraints-examples.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-scheduler-pod-topology-spread-constraints - -[id="nodes-scheduler-pod-topology-spread-constraints-examples_{context}"] -= Example pod topology spread constraints - -The following examples demonstrate pod topology spread constraint configurations. - -[id="nodes-scheduler-pod-topology-spread-constraints-example-single_{context}"] -== Single pod topology spread constraint example - -// TODO: Add a diagram? - -This example `Pod` spec defines one pod topology spread constraint. It matches on pods labeled `foo:bar`, distributes among zones, specifies a skew of `1`, and does not schedule the pod if it does not meet these requirements. - -[source,yaml] ----- -kind: Pod -apiVersion: v1 -metadata: - name: my-pod - labels: - foo: bar -spec: - topologySpreadConstraints: - - maxSkew: 1 - topologyKey: topology.kubernetes.io/zone - whenUnsatisfiable: DoNotSchedule - labelSelector: - matchLabels: - foo: bar - containers: - - image: "docker.io/ocpqe/hello-pod" - name: hello-pod ----- - -[id="nodes-scheduler-pod-topology-spread-constraints-example-multiple_{context}"] -== Multiple pod topology spread constraints example - -// TODO: Add a diagram? - -This example `Pod` spec defines two pod topology spread constraints. Both match on pods labeled `foo:bar`, specify a skew of `1`, and do not schedule the pod if it does not meet these requirements. - -The first constraint distributes pods based on a user-defined label `node`, and the second constraint distributes pods based on a user-defined label `rack`. Both constraints must be met for the pod to be scheduled. - -[source,yaml] ----- -kind: Pod -apiVersion: v1 -metadata: - name: my-pod-2 - labels: - foo: bar -spec: - topologySpreadConstraints: - - maxSkew: 1 - topologyKey: node - whenUnsatisfiable: DoNotSchedule - labelSelector: - matchLabels: - foo: bar - - maxSkew: 1 - topologyKey: rack - whenUnsatisfiable: DoNotSchedule - labelSelector: - matchLabels: - foo: bar - containers: - - image: "docker.io/ocpqe/hello-pod" - name: hello-pod ----- diff --git a/modules/nodes-scheduler-profiles-about.adoc b/modules/nodes-scheduler-profiles-about.adoc deleted file mode 100644 index 466db7d097b9..000000000000 --- a/modules/nodes-scheduler-profiles-about.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-scheduler-profiles.adoc - -[id="nodes-scheduler-profiles-about_{context}"] -= About scheduler profiles - -You can specify a scheduler profile to control how pods are scheduled onto nodes. - -[NOTE] -==== -Scheduler profiles are an alternative to configuring a scheduler policy. Do not set both a scheduler policy and a scheduler profile. If both are set, the scheduler policy takes precedence. -==== - -The following scheduler profiles are available: - -`LowNodeUtilization`:: This profile attempts to spread pods evenly across nodes to get low resource usage per node. This profile provides the default scheduler behavior. - -`HighNodeUtilization`:: This profile attempts to place as many pods as possible on to as few nodes as possible. This minimizes node count and has high resource usage per node. - -`NoScoring`:: This is a low-latency profile that strives for the quickest scheduling cycle by disabling all score plug-ins. This might sacrifice better scheduling decisions for faster ones. diff --git a/modules/nodes-scheduler-profiles-configuring.adoc b/modules/nodes-scheduler-profiles-configuring.adoc deleted file mode 100644 index f2adcc210001..000000000000 --- a/modules/nodes-scheduler-profiles-configuring.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-scheduler-profiles.adoc - -[id="nodes-scheduler-profiles-configuring_{context}"] -= Configuring a scheduler profile - -You can configure the scheduler to use a scheduler profile. - -[NOTE] -==== -Do not set both a scheduler policy and a scheduler profile. If both are set, the scheduler policy takes precedence. -==== - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Edit the `Scheduler` object: -+ -[source,terminal] ----- -$ oc edit scheduler cluster ----- - -. Specify the profile to use in the `spec.profile` field: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Scheduler -metadata: - ... - name: cluster - resourceVersion: "601" - selfLink: /apis/config.openshift.io/v1/schedulers/cluster - uid: b351d6d0-d06f-4a99-a26b-87af62e79f59 -spec: - mastersSchedulable: false - policy: - name: "" - profile: LowNodeUtilization <1> ----- -<1> Set to `LowNodeUtilization`, `HighNodeUtilization`, or `NoScoring`. - -. Save the file to apply the changes. diff --git a/modules/nodes-scheduler-taints-tolerations-about.adoc b/modules/nodes-scheduler-taints-tolerations-about.adoc deleted file mode 100644 index f6ae0f423e70..000000000000 --- a/modules/nodes-scheduler-taints-tolerations-about.adoc +++ /dev/null @@ -1,300 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-scheduler-taints-tolerations.adoc -// * post_installation_configuration/node-tasks.adoc - - -[id="nodes-scheduler-taints-tolerations-about_{context}"] -= Understanding taints and tolerations - -A _taint_ allows a node to refuse a pod to be scheduled unless that pod has a matching _toleration_. - -You apply taints to a node through the `Node` specification (`NodeSpec`) and apply tolerations to a pod through the `Pod` specification (`PodSpec`). When you apply a taint a node, the scheduler cannot place a pod on that node unless the pod can tolerate the taint. - -.Example taint in a node specification -[source,yaml] ----- -spec: -.... - template: -.... - spec: - taints: - - effect: NoExecute - key: key1 - value: value1 -.... ----- - -.Example toleration in a `Pod` spec -[source,yaml] ----- -spec: -.... - template: -.... - spec - tolerations: - - key: "key1" - operator: "Equal" - value: "value1" - effect: "NoExecute" - tolerationSeconds: 3600 -.... ----- - - -Taints and tolerations consist of a key, value, and effect. - -[id="taint-components-table_{context}"] -.Taint and toleration components -[cols="3a,8a",options="header"] -|=== - -|Parameter |Description - -|`key` -|The `key` is any string, up to 253 characters. The key must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores. - -|`value` -| The `value` is any string, up to 63 characters. The value must begin with a letter or number, and may contain letters, numbers, hyphens, dots, and underscores. - -|`effect` - -|The effect is one of the following: -[frame=none] -[cols="2a,3a"] -!==== -!`NoSchedule` ^[1]^ -!* New pods that do not match the taint are not scheduled onto that node. -* Existing pods on the node remain. -!`PreferNoSchedule` -!* New pods that do not match the taint might be scheduled onto that node, but the scheduler tries not to. -* Existing pods on the node remain. -!`NoExecute` -!* New pods that do not match the taint cannot be scheduled onto that node. -* Existing pods on the node that do not have a matching toleration are removed. -!==== - -|`operator` -|[frame=none] -[cols="2,3"] -!==== -!`Equal` -!The `key`/`value`/`effect` parameters must match. This is the default. -!`Exists` -!The `key`/`effect` parameters must match. You must leave a blank `value` parameter, which matches any. -!==== - -|=== -[.small] --- -1. If you add a `NoSchedule` taint to a master node, the node must have the `node-role.kubernetes.io/master=:NoSchedule` taint, which is added by default. -+ -For example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Node -metadata: - annotations: - machine.openshift.io/machine: openshift-machine-api/ci-ln-62s7gtb-f76d1-v8jxv-master-0 - machineconfiguration.openshift.io/currentConfig: rendered-master-cdc1ab7da414629332cc4c3926e6e59c -... -spec: - taints: - - effect: NoSchedule - key: node-role.kubernetes.io/master -... ----- --- - -A toleration matches a taint: - -* If the `operator` parameter is set to `Equal`: -** the `key` parameters are the same; -** the `value` parameters are the same; -** the `effect` parameters are the same. - -* If the `operator` parameter is set to `Exists`: -** the `key` parameters are the same; -** the `effect` parameters are the same. - -The following taints are built into {product-title}: - -* `node.kubernetes.io/not-ready`: The node is not ready. This corresponds to the node condition `Ready=False`. -* `node.kubernetes.io/unreachable`: The node is unreachable from the node controller. This corresponds to the node condition `Ready=Unknown`. -* `node.kubernetes.io/out-of-disk`: The node has insufficient free space on the node for adding new pods. This corresponds to the node condition `OutOfDisk=True`. -* `node.kubernetes.io/memory-pressure`: The node has memory pressure issues. This corresponds to the node condition `MemoryPressure=True`. -* `node.kubernetes.io/disk-pressure`: The node has disk pressure issues. This corresponds to the node condition `DiskPressure=True`. -* `node.kubernetes.io/network-unavailable`: The node network is unavailable. -* `node.kubernetes.io/unschedulable`: The node is unschedulable. -* `node.cloudprovider.kubernetes.io/uninitialized`: When the node controller is started with an external cloud provider, this taint is set on a node to mark it as unusable. After a controller from the cloud-controller-manager initializes this node, the kubelet removes this taint. - - -[id="nodes-scheduler-taints-tolerations-about-seconds_{context}"] -== Understanding how to use toleration seconds to delay pod evictions - -You can specify how long a pod can remain bound to a node before being evicted by specifying the `tolerationSeconds` parameter in the `Pod` specification or `MachineSet` object. If a taint with the `NoExecute` effect is added to a node, a pod that does tolerate the taint, which has the `tolerationSeconds` parameter, the pod is not evicted until that time period expires. - -.Example output -[source,yaml] ----- -spec: -.... - template: -.... - spec - tolerations: - - key: "key1" - operator: "Equal" - value: "value1" - effect: "NoExecute" - tolerationSeconds: 3600 ----- - -Here, if this pod is running but does not have a matching toleration, the pod stays bound to the node for 3,600 seconds and then be evicted. If the taint is removed before that time, the pod is not evicted. - -[id="nodes-scheduler-taints-tolerations-about-multiple_{context}"] -== Understanding how to use multiple taints - -You can put multiple taints on the same node and multiple tolerations on the same pod. {product-title} processes multiple taints and tolerations as follows: - -. Process the taints for which the pod has a matching toleration. -. The remaining unmatched taints have the indicated effects on the pod: -+ -* If there is at least one unmatched taint with effect `NoSchedule`, {product-title} cannot schedule a pod onto that node. -* If there is no unmatched taint with effect `NoSchedule` but there is at least one unmatched taint with effect `PreferNoSchedule`, {product-title} tries to not schedule the pod onto the node. -* If there is at least one unmatched taint with effect `NoExecute`, {product-title} evicts the pod from the node if it is already running on the node, or the pod is not scheduled onto the node if it is not yet running on the node. -+ -** Pods that do not tolerate the taint are evicted immediately. -+ -** Pods that tolerate the taint without specifying `tolerationSeconds` in their `Pod` specification remain bound forever. -+ -** Pods that tolerate the taint with a specified `tolerationSeconds` remain bound for the specified amount of time. - -For example: - -* Add the following taints to the node: -+ -[source,terminal] ----- -$ oc adm taint nodes node1 key1=value1:NoSchedule ----- -+ -[source,terminal] ----- -$ oc adm taint nodes node1 key1=value1:NoExecute ----- -+ -[source,terminal] ----- -$ oc adm taint nodes node1 key2=value2:NoSchedule ----- - -* The pod has the following tolerations: -+ -[source,yaml] ----- -spec: -.... - template: -.... - spec - tolerations: - - key: "key1" - operator: "Equal" - value: "value1" - effect: "NoSchedule" - - key: "key1" - operator: "Equal" - value: "value1" - effect: "NoExecute" ----- - -In this case, the pod cannot be scheduled onto the node, because there is no toleration matching the third taint. The pod continues running if it is already running on the node when the taint is added, because the third taint is the only -one of the three that is not tolerated by the pod. - -[id="nodes-scheduler-taints-tolerations-about-taintNodesByCondition_{context}"] -== Understanding pod scheduling and node conditions (taint node by condition) - -The Taint Nodes By Condition feature, which is enabled by default, automatically taints nodes that report conditions such as memory pressure and disk pressure. If a node reports a condition, a taint is added until the condition clears. The taints have the `NoSchedule` effect, which means no pod can be scheduled on the node unless the pod has a matching toleration. - -The scheduler checks for these taints on nodes before scheduling pods. If the taint is present, the pod is scheduled on a different node. Because the scheduler checks for taints and not the actual node conditions, you configure the scheduler to ignore some of these node conditions by adding appropriate pod tolerations. - -To ensure backward compatibility, the daemon set controller automatically adds the following tolerations to all daemons: - -* node.kubernetes.io/memory-pressure -* node.kubernetes.io/disk-pressure -* node.kubernetes.io/out-of-disk (only for critical pods) -* node.kubernetes.io/unschedulable (1.10 or later) -* node.kubernetes.io/network-unavailable (host network only) - -You can also add arbitrary tolerations to daemon sets. - -[id="nodes-scheduler-taints-tolerations-about-taintBasedEvictions_{context}"] -== Understanding evicting pods by condition (taint-based evictions) - -The Taint-Based Evictions feature, which is enabled by default, evicts pods from a node that experiences specific conditions, such as `not-ready` and `unreachable`. -When a node experiences one of these conditions, {product-title} automatically adds taints to the node, and starts evicting and rescheduling the pods on different nodes. - -Taint Based Evictions have a `NoExecute` effect, where any pod that does not tolerate the taint is evicted immediately and any pod that does tolerate the taint will never be evicted, unless the pod uses the `tolerationSeconds` parameter. - -The `tolerationSeconds` parameter allows you to specify how long a pod stays bound to a node that has a node condition. If the condition still exists after the `tolerationSeconds` period, the taint remains on the node and the pods with a matching toleration are evicted. If the condition clears before the `tolerationSeconds` period, pods with matching tolerations are not removed. - -If you use the `tolerationSeconds` parameter with no value, pods are never evicted because of the not ready and unreachable node conditions. - -[NOTE] -==== -{product-title} evicts pods in a rate-limited way to prevent massive pod evictions in scenarios such as the master becoming partitioned from the nodes. -==== - -{product-title} automatically adds a toleration for `node.kubernetes.io/not-ready` and `node.kubernetes.io/unreachable` with `tolerationSeconds=300`, unless the `Pod` configuration specifies either toleration. - -[source,yaml] ----- -spec: -.... - template: -.... - spec - tolerations: - - key: node.kubernetes.io/not-ready - operator: Exists - effect: NoExecute - tolerationSeconds: 300 <1> - - key: node.kubernetes.io/unreachable - operator: Exists - effect: NoExecute - tolerationSeconds: 300 ----- - -<1> These tolerations ensure that the default pod behavior is to remain bound for five minutes after one of these node conditions problems is detected. - -You can configure these tolerations as needed. For example, if you have an application with a lot of local state, you might want to keep the pods bound to node for a longer time in the event of network partition, allowing for the partition to recover and avoiding pod eviction. - -Pods spawned by a daemon set are created with `NoExecute` tolerations for the following taints with no `tolerationSeconds`: - -* `node.kubernetes.io/unreachable` -* `node.kubernetes.io/not-ready` - -As a result, daemon set pods are never evicted because of these node conditions. - -[id="nodes-scheduler-taints-tolerations-all_{context}"] -== Tolerating all taints - -You can configure a pod to tolerate all taints by adding an `operator: "Exists"` toleration with no `key` and `value` parameters. -Pods with this toleration are not removed from a node that has taints. - -.`Pod` spec for tolerating all taints -[source,yaml] ----- -spec: -.... - template: -.... - spec - tolerations: - - operator: "Exists" ----- diff --git a/modules/nodes-scheduler-taints-tolerations-adding-machineset.adoc b/modules/nodes-scheduler-taints-tolerations-adding-machineset.adoc deleted file mode 100644 index e6547493a36c..000000000000 --- a/modules/nodes-scheduler-taints-tolerations-adding-machineset.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-taints-tolerations.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-scheduler-taints-tolerations-adding-machineset_{context}"] -= Adding taints and tolerations using a machine set - -You can add taints to nodes using a machine set. All nodes associated with the `MachineSet` object are updated with the taint. Tolerations respond to taints added by a machine set in the same manner as taints added directly to the nodes. - -.Procedure - -. Add a toleration to a pod by editing the `Pod` spec to include a `tolerations` stanza: -+ -.Sample pod configuration file with `Equal` operator -[source,yaml] ----- -spec: -.... - template: -.... - spec: - tolerations: - - key: "key1" <1> - value: "value1" - operator: "Equal" - effect: "NoExecute" - tolerationSeconds: 3600 <2> ----- -<1> The toleration parameters, as described in the *Taint and toleration components* table. -<2> The `tolerationSeconds` parameter specifies how long a pod is bound to a node before being evicted. -+ -For example: -+ -.Sample pod configuration file with `Exists` operator -[source,yaml] ----- -spec: -.... - template: -.... - spec: - tolerations: - - key: "key1" - operator: "Exists" - effect: "NoExecute" - tolerationSeconds: 3600 ----- - -. Add the taint to the `MachineSet` object: - -.. Edit the `MachineSet` YAML for the nodes you want to taint or you can create a new `MachineSet` object: -+ -[source,terminal] ----- -$ oc edit machineset <machineset> ----- - -.. Add the taint to the `spec.template.spec` section: -+ -.Example taint in a node specification -[source,yaml] ----- -spec: -.... - template: -.... - spec: - taints: - - effect: NoExecute - key: key1 - value: value1 -.... ----- -+ -This example places a taint that has the key `key1`, value `value1`, and taint effect `NoExecute` on the nodes. - -.. Scale down the machine set to 0: -+ -[source,terminal] ----- -$ oc scale --replicas=0 machineset <machineset> -n openshift-machine-api ----- -+ -Wait for the machines to be removed. - -.. Scale up the machine set as needed: -+ -[source,terminal] ----- -$ oc scale --replicas=2 machineset <machineset> -n openshift-machine-api ----- -+ -Wait for the machines to start. The taint is added to the nodes associated with the `MachineSet` object. - diff --git a/modules/nodes-scheduler-taints-tolerations-adding.adoc b/modules/nodes-scheduler-taints-tolerations-adding.adoc deleted file mode 100644 index 64dad9c75611..000000000000 --- a/modules/nodes-scheduler-taints-tolerations-adding.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-taints-tolerations.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-scheduler-taints-tolerations-adding_{context}"] -= Adding taints and tolerations - -You add tolerations to pods and taints to nodes to allow the node to control which pods should or should not be scheduled on them. For existing pods and nodes, you should add the toleration to the pod first, then add the taint to the node to avoid pods being removed from the node before you can add the toleration. - -.Procedure - -. Add a toleration to a pod by editing the `Pod` spec to include a `tolerations` stanza: -+ -.Sample pod configuration file with an Equal operator -[source,yaml] ----- -spec: -.... - template: -.... - spec: - tolerations: - - key: "key1" <1> - value: "value1" - operator: "Equal" - effect: "NoExecute" - tolerationSeconds: 3600 <2> ----- -<1> The toleration parameters, as described in the *Taint and toleration components* table. -<2> The `tolerationSeconds` parameter specifies how long a pod can remain bound to a node before being evicted. -+ -For example: -+ -.Sample pod configuration file with an Exists operator -[source,yaml] ----- -spec: -.... - template: -.... - spec: - tolerations: - - key: "key1" - operator: "Exists" <1> - effect: "NoExecute" - tolerationSeconds: 3600 ----- -<1> The `Exists` operator does not take a `value`. -+ -This example places a taint on `node1` that has key `key1`, value `value1`, and taint effect `NoExecute`. - -. Add a taint to a node by using the following command with the parameters described in the *Taint and toleration components* table: -+ -[source,terminal] ----- -$ oc adm taint nodes <node_name> <key>=<value>:<effect> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm taint nodes node1 key1=value1:NoExecute ----- -+ -This command places a taint on `node1` that has key `key1`, value `value1`, and effect `NoExecute`. -+ -[NOTE] -==== -If you add a `NoSchedule` taint to a master node, the node must have the `node-role.kubernetes.io/master=:NoSchedule` taint, which is added by default. - -For example: - -[source,yaml] ----- -apiVersion: v1 -kind: Node -metadata: - annotations: - machine.openshift.io/machine: openshift-machine-api/ci-ln-62s7gtb-f76d1-v8jxv-master-0 - machineconfiguration.openshift.io/currentConfig: rendered-master-cdc1ab7da414629332cc4c3926e6e59c -... -spec: - taints: - - effect: NoSchedule - key: node-role.kubernetes.io/master -... - ----- -==== -+ -The tolerations on the Pod match the taint on the node. A pod with either toleration can be scheduled onto `node1`. - diff --git a/modules/nodes-scheduler-taints-tolerations-binding.adoc b/modules/nodes-scheduler-taints-tolerations-binding.adoc deleted file mode 100644 index a9173d4c082e..000000000000 --- a/modules/nodes-scheduler-taints-tolerations-binding.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-taints-tolerations.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-scheduler-taints-tolerations-bindings_{context}"] -= Binding a user to a node using taints and tolerations - -If you want to dedicate a set of nodes for exclusive use by a particular set of users, add a toleration to their pods. Then, add a corresponding taint to those nodes. The pods with the tolerations are allowed to use the tainted nodes, or any other nodes in the cluster. - -If you want ensure the pods are scheduled to only those tainted nodes, also add a label to the same set of nodes and add a node affinity to the pods so that the pods can only be scheduled onto nodes with that label. - -.Procedure - -To configure a node so that users can use only that node: - -. Add a corresponding taint to those nodes: -+ -For example: -+ -[source,terminal] ----- -$ oc adm taint nodes node1 dedicated=groupName:NoSchedule ----- - -. Add a toleration to the pods by writing a custom admission controller. - - diff --git a/modules/nodes-scheduler-taints-tolerations-removing.adoc b/modules/nodes-scheduler-taints-tolerations-removing.adoc deleted file mode 100644 index 921d7e551ac5..000000000000 --- a/modules/nodes-scheduler-taints-tolerations-removing.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/nodes-scheduler-taints-tolerations.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-scheduler-taints-tolerations-removing_{context}"] -= Removing taints and tolerations - -You can remove taints from nodes and tolerations from pods as needed. You should add the toleration to the pod first, then add the taint to the node to avoid pods being removed from the node before you can add the toleration. - -.Procedure - -To remove taints and tolerations: - -. To remove a taint from a node: -+ -[source,terminal] ----- -$ oc adm taint nodes <node-name> <key>- ----- -+ -For example: -+ -[source,terminal] ----- -$ oc adm taint nodes ip-10-0-132-248.ec2.internal key1- ----- -+ -.Example output -[source,terminal] ----- -node/ip-10-0-132-248.ec2.internal untainted ----- - -. To remove a toleration from a pod, edit the `Pod` spec to remove the toleration: -+ -[source,yaml] ----- -spec: -.... - template: -.... - spec: - tolerations: - - key: "key2" - operator: "Exists" - effect: "NoExecute" - tolerationSeconds: 3600 ----- diff --git a/modules/nodes-scheduler-taints-tolerations-special.adoc b/modules/nodes-scheduler-taints-tolerations-special.adoc deleted file mode 100644 index 88f46c0f26ae..000000000000 --- a/modules/nodes-scheduler-taints-tolerations-special.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * nodes/scheduling/nodes-scheduler-taints-tolerations.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="nodes-scheduler-taints-tolerations-special_{context}"] -= Controlling nodes with special hardware using taints and tolerations - -In a cluster where a small subset of nodes have specialized hardware, you can use taints and tolerations to keep pods that do not need the specialized hardware off of those nodes, leaving the nodes for pods that do need the specialized hardware. You can also require pods that need specialized hardware to use specific nodes. - -You can achieve this by adding a toleration to pods that need the special hardware and tainting the nodes that have the specialized hardware. - -.Procedure - -To ensure nodes with specialized hardware are reserved for specific pods: - -. Add a toleration to pods that need the special hardware. -+ -For example: -+ -[source,yaml] ----- -spec: -.... - template: -.... - spec: - tolerations: - - key: "disktype" - value: "ssd" - operator: "Equal" - effect: "NoSchedule" - tolerationSeconds: 3600 ----- - -. Taint the nodes that have the specialized hardware using one of the following commands: -+ -[source,terminal] ----- -$ oc adm taint nodes <node-name> disktype=ssd:NoSchedule ----- -+ -Or: -+ -[source,terminal] ----- -$ oc adm taint nodes <node-name> disktype=ssd:PreferNoSchedule ----- diff --git a/modules/nw-about-multicast.adoc b/modules/nw-about-multicast.adoc deleted file mode 100644 index 4895a3dab9ad..000000000000 --- a/modules/nw-about-multicast.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/enabling-multicast.adoc -// * networking/ovn_kubernetes_network_provider/enabling-multicast.adoc - -ifeval::["{context}" == "openshift-sdn-enabling-multicast"] -:openshift-sdn: -:sdn: OpenShift SDN -endif::[] -ifeval::["{context}" == "ovn-kubernetes-enabling-multicast"] -:ovn: -:sdn: OVN-Kubernetes -endif::[] - -[id="nw-about-multicast_{context}"] -= About multicast - -With IP multicast, data is broadcast to many IP addresses simultaneously. - -[IMPORTANT] -==== -At this time, multicast is best used for low-bandwidth coordination or service -discovery and not a high-bandwidth solution. -==== - -Multicast traffic between {product-title} pods is disabled by default. If you are using the {sdn} default Container Network Interface (CNI) network provider, you can enable multicast on a per-project basis. - -ifdef::openshift-sdn[] -When using the OpenShift SDN network plug-in in `networkpolicy` isolation mode: - -* Multicast packets sent by a pod will be delivered to all other pods in the project, regardless of `NetworkPolicy` objects. Pods might be able to communicate over multicast even when they cannot communicate over unicast. -* Multicast packets sent by a pod in one project will never be delivered to pods in any other project, even if there are `NetworkPolicy` objects that allow communication between the projects. - -When using the OpenShift SDN network plug-in in `multitenant` isolation mode: - -* Multicast packets sent by a pod will be delivered to all other pods in the -project. -* Multicast packets sent by a pod in one project will be delivered to pods in -other projects only if each project is joined together and multicast is enabled -in each joined project. -endif::openshift-sdn[] - -ifeval::["{context}" == "openshift-sdn-enabling-multicast"] -:!openshift-sdn: -endif::[] -ifeval::["{context}" == "ovn-kubernetes-enabling-multicast"] -:!ovn: -endif::[] -ifdef::sdn[] -:!sdn: -endif::sdn[] diff --git a/modules/nw-annotating-a-route-with-a-cookie-name.adoc b/modules/nw-annotating-a-route-with-a-cookie-name.adoc deleted file mode 100644 index 0ce96c537a01..000000000000 --- a/modules/nw-annotating-a-route-with-a-cookie-name.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module filename: nw-annotating-a-route-with-a-cookie-name.adoc -// Use module with the following module: -// nw-using-cookies-keep-route-statefulness.adoc -// -// Module included in the following assemblies: -// -// * networking/configuring-routing.adoc - -[id="nw-annotating-a-route-with-a-cookie-name_{context}"] -= Annotating a route with a cookie - -You can set a cookie name to overwrite the default, auto-generated one for the -route. This allows the application receiving route traffic to know the cookie -name. By deleting the cookie it can force the next request to re-choose an -endpoint. So, if a server was overloaded it tries to remove the requests from the -client and redistribute them. - -.Procedure - -. Annotate the route with the desired cookie name: -+ -[source,terminal] ----- -$ oc annotate route <route_name> router.openshift.io/<cookie_name>="-<cookie_annotation>" ----- -+ -For example, to annotate the cookie name of `my_cookie` to the `my_route` with -the annotation of `my_cookie_annotation`: -+ -[source,terminal] ----- -$ oc annotate route my_route router.openshift.io/my_cookie="-my_cookie_annotation" ----- - -. Save the cookie, and access the route: -+ -[source,terminal] ----- -$ curl $my_route -k -c /tmp/my_cookie ----- diff --git a/modules/nw-aws-nlb-existing-cluster.adoc b/modules/nw-aws-nlb-existing-cluster.adoc deleted file mode 100644 index 095e38c3e8bd..000000000000 --- a/modules/nw-aws-nlb-existing-cluster.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws-network-load-balancer.adoc - -[id="nw-aws-nlb-existing-cluster_{context}"] -= Configuring an Ingress Controller Network Load Balancer on an existing AWS cluster - -You can create an Ingress Controller backed by an AWS Network Load Balancer (NLB) on an existing cluster. - -.Prerequisites - -* You must have an installed AWS cluster. -* `PlatformStatus` of the infrastructure resource must be AWS. -** To verify that the `PlatformStatus` is AWS, run: -+ -[source,terminal] ----- -$ oc get infrastructure/cluster -o jsonpath='{.status.platformStatus.type}' -AWS ----- - -.Procedure - -Create an Ingress Controller backed by an AWS NLB on an existing cluster. - -. Create the Ingress Controller manifest: -+ -[source,terminal] ----- - $ cat ingresscontroller-aws-nlb.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - name: $my_ingress_controller<1> - namespace: openshift-ingress-operator -spec: - domain: $my_unique_ingress_domain<2> - endpointPublishingStrategy: - type: LoadBalancerService - loadBalancer: - scope: External<3> - providerParameters: - type: AWS - aws: - type: NLB ----- -<1> Replace `$my_ingress_controller` with a unique name for the Ingress Controller. -<2> Replace `$my_unique_ingress_domain` with a domain name that is unique among all Ingress Controllers in the cluster. -<3> You can replace `External` with `Internal` to use an internal NLB. - -. Create the resource in the cluster: -+ -[source,terminal] ----- -$ oc create -f ingresscontroller-aws-nlb.yaml ----- diff --git a/modules/nw-aws-nlb-new-cluster.adoc b/modules/nw-aws-nlb-new-cluster.adoc deleted file mode 100644 index eeaebd6484c1..000000000000 --- a/modules/nw-aws-nlb-new-cluster.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws-network-load-balancer.adoc - -[id="nw-aws-nlb-new-cluster_{context}"] -= Configuring an Ingress Controller Network Load Balancer on a new AWS cluster - -You can create an Ingress Controller backed by an AWS Network Load Balancer (NLB) on a new cluster. - -.Prerequisites - -* Create the `install-config.yaml` file and complete any modifications to it. - -.Procedure - -Create an Ingress Controller backed by an AWS NLB on a new cluster. - -. Change to the directory that contains the installation program and create the manifests: -+ -[source,terminal] ----- -$ ./openshift-install create manifests --dir=<installation_directory> <1> ----- -<1> For `<installation_directory>`, specify the name of the directory that -contains the `install-config.yaml` file for your cluster. - -. Create a file that is named `cluster-ingress-default-ingresscontroller.yaml` in the `<installation_directory>/manifests/` directory: -+ -[source,terminal] ----- -$ touch <installation_directory>/manifests/cluster-ingress-default-ingresscontroller.yaml <1> ----- -<1> For `<installation_directory>`, specify the directory name that contains the -`manifests/` directory for your cluster. -+ -After creating the file, several network configuration files are in the -`manifests/` directory, as shown: -+ -[source,terminal] ----- -$ ls <installation_directory>/manifests/cluster-ingress-default-ingresscontroller.yaml ----- -+ -.Example output -[source,terminal] ----- -cluster-ingress-default-ingresscontroller.yaml ----- - -. Open the `cluster-ingress-default-ingresscontroller.yaml` file in an editor and enter a custom resource (CR) that describes the Operator configuration you want: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - creationTimestamp: null - name: default - namespace: openshift-ingress-operator -spec: - endpointPublishingStrategy: - loadBalancer: - scope: External - providerParameters: - type: AWS - aws: - type: NLB - type: LoadBalancerService ----- - -. Save the `cluster-ingress-default-ingresscontroller.yaml` file and quit the text editor. -. Optional: Back up the `manifests/cluster-ingress-default-ingresscontroller.yaml` file. The installation program deletes the `manifests/` directory when creating the cluster. diff --git a/modules/nw-cluster-network-operator.adoc b/modules/nw-cluster-network-operator.adoc deleted file mode 100644 index 3f1d5fbbe64e..000000000000 --- a/modules/nw-cluster-network-operator.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// * networking/cluster-network-operator.adoc - -[id="nw-cluster-network-operator_{context}"] -= Cluster Network Operator - -The Cluster Network Operator implements the `network` API from the `operator.openshift.io` API group. -The Operator deploys the OpenShift SDN default Container Network Interface (CNI) network provider plug-in, or the default network provider plug-in that you selected during cluster installation, by using a daemon set. - -.Procedure - -The Cluster Network Operator is deployed during installation as a Kubernetes -`Deployment`. - -. Run the following command to view the Deployment status: -+ -[source,terminal] ----- -$ oc get -n openshift-network-operator deployment/network-operator ----- -+ -.Example output -[source,terminal] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -network-operator 1/1 1 1 56m ----- - -. Run the following command to view the state of the Cluster Network Operator: -+ -[source,terminal] ----- -$ oc get clusteroperator/network ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -network 4.5.4 True False False 50m ----- -+ -The following fields provide information about the status of the operator: -`AVAILABLE`, `PROGRESSING`, and `DEGRADED`. The `AVAILABLE` field is `True` when -the Cluster Network Operator reports an available status condition. diff --git a/modules/nw-cno-logs.adoc b/modules/nw-cno-logs.adoc deleted file mode 100644 index f8afa53f86a1..000000000000 --- a/modules/nw-cno-logs.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/cluster-network-operator.adoc - -[id="nw-cno-logs_{context}"] -= Viewing Cluster Network Operator logs - -You can view Cluster Network Operator logs by using the `oc logs` command. - -.Procedure - -* Run the following command to view the logs of the Cluster Network Operator: -+ -[source,terminal] ----- -$ oc logs --namespace=openshift-network-operator deployment/network-operator ----- diff --git a/modules/nw-cno-status.adoc b/modules/nw-cno-status.adoc deleted file mode 100644 index aab9c6da9a0b..000000000000 --- a/modules/nw-cno-status.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/cluster-network-operator.adoc - -[id="nw-cno-status_{context}"] -= Viewing Cluster Network Operator status - -You can inspect the status and view the details of the Cluster Network Operator -using the `oc describe` command. - -.Procedure - -* Run the following command to view the status of the Cluster Network Operator: -+ -[source,terminal] ----- -$ oc describe clusteroperators/network ----- diff --git a/modules/nw-cno-view.adoc b/modules/nw-cno-view.adoc deleted file mode 100644 index 96a370a15d15..000000000000 --- a/modules/nw-cno-view.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/cluster-network-operator.adoc - -[id="nw-cno-view_{context}"] -= Viewing the cluster network configuration - -Every new {product-title} installation has a `network.config` object named -`cluster`. - -.Procedure - -* Use the `oc describe` command to view the cluster network configuration: -+ -[source,terminal] ----- -$ oc describe network.config/cluster ----- -+ -.Example output -[source,terminal] ----- -Name: cluster -Namespace: -Labels: <none> -Annotations: <none> -API Version: config.openshift.io/v1 -Kind: Network -Metadata: - Self Link: /apis/config.openshift.io/v1/networks/cluster -Spec: <1> - Cluster Network: - Cidr: 10.128.0.0/14 - Host Prefix: 23 - Network Type: OpenShiftSDN - Service Network: - 172.30.0.0/16 -Status: <2> - Cluster Network: - Cidr: 10.128.0.0/14 - Host Prefix: 23 - Cluster Network MTU: 8951 - Network Type: OpenShiftSDN - Service Network: - 172.30.0.0/16 -Events: <none> ----- -<1> The `Spec` field displays the configured state of the cluster network. -<2> The `Status` field displays the current state of the cluster network -configuration. - -//// -* Use the `oc describe` command to view the cluster network configuration: -+ -[source,terminal] ----- -$ oc describe network.operator/cluster - -Name: cluster -Namespace: -Labels: <none> -Annotations: <none> -API Version: operator.openshift.io/v1 -Kind: Network -Metadata: - Self Link: /apis/operator.openshift.io/v1/networks/cluster -Spec: - Cluster Network: - Cidr: 10.128.0.0/14 - Host Prefix: 23 - Default Network: - Type: OpenShiftSDN - Service Network: - 172.30.0.0/16 -Status: -Events: <none> ----- -//// diff --git a/modules/nw-configure-ingress-access-logging.adoc b/modules/nw-configure-ingress-access-logging.adoc deleted file mode 100644 index 95b41b8ff36d..000000000000 --- a/modules/nw-configure-ingress-access-logging.adoc +++ /dev/null @@ -1,126 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc - -[id="nw-configure-ingress-access-logging_{context}"] -= Configuring Ingress access logging - -You can configure the Ingress Controller to enable access logs. If you have clusters that do not receive much traffic, then you can log to a sidecar. If you have high traffic clusters, to avoid exceeding the capacity of the logging stack or to integrate with a logging infrastructure outside of {product-title}, you can forward logs to a custom syslog endpoint. You can also specify the format for access logs. - -Container logging is useful to enable access logs on low-traffic clusters when there is no existing Syslog logging infrastructure, or for short-term use while diagnosing problems with the Ingress Controller. - -Syslog is needed for high-traffic clusters where access logs could exceed the OpenShift Logging stack's capacity, or for environments where any logging solution needs to integrate with an existing Syslog logging infrastructure. The Syslog use-cases can overlap. - -.Prerequisites - -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -Configure Ingress access logging to a sidecar. - -* To configure Ingress access logging, you must specify a destination using `spec.logging.access.destination`. To specify logging to a sidecar container, you must specify `Container` `spec.logging.access.destination.type`. The following example is an Ingress Controller definition that logs to a `Container` destination: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - name: default - namespace: openshift-ingress-operator -spec: - replicas: 2 - endpointPublishingStrategy: - type: NodePortService <1> - logging: - access: - destination: - type: Container ----- -<1> `NodePortService` is not required to configure Ingress access logging to a sidecar. Ingress logging is compatible with any `endpointPublishingStrategy`. -+ -* When you configure the Ingress Controller to log to a sidecar, the operator creates a container named `logs` inside the Ingress Controller Pod: -+ -[source,terminal] ----- -$ oc -n openshift-ingress logs deployment.apps/router-default -c logs ----- -+ -.Example output -[source,terminal] ----- -2020-05-11T19:11:50.135710+00:00 router-default-57dfc6cd95-bpmk6 router-default-57dfc6cd95-bpmk6 haproxy[108]: 174.19.21.82:39654 [11/May/2020:19:11:50.133] public be_http:hello-openshift:hello-openshift/pod:hello-openshift:hello-openshift:10.128.2.12:8080 0/0/1/0/1 200 142 - - --NI 1/1/0/0/0 0/0 "GET / HTTP/1.1" ----- - -Configure Ingress access logging to a Syslog endpoint. - -* To configure Ingress access logging, you must specify a destination using `spec.logging.access.destination`. To specify logging to a Syslog endpoint destination, you must specify `Syslog` for `spec.logging.access.destination.type`. If the destination type is `Syslog`, you must also specify a destination endpoint using `spec.logging.access.destination.syslog.endpoint` and you can specify a facility using `spec.logging.access.destination.syslog.facility`. The following example is an Ingress Controller definition that logs to a `Syslog` destination: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - name: default - namespace: openshift-ingress-operator -spec: - replicas: 2 - endpointPublishingStrategy: - type: NodePortService - logging: - access: - destination: - type: Syslog - syslog: - address: 1.2.3.4 - port: 10514 ----- -+ -[NOTE] -==== -The `syslog` destination port must be UDP. -==== - -Configure Ingress access logging with a specific log format. - -* You can specify `spec.logging.access.httpLogFormat` to customize the log format. The following example is an Ingress Controller definition that logs to a `syslog` endpoint with IP address 1.2.3.4 and port 10514: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - name: default - namespace: openshift-ingress-operator -spec: - replicas: 2 - endpointPublishingStrategy: - type: NodePortService - logging: - access: - destination: - type: Syslog - syslog: - address: 1.2.3.4 - port: 10514 - httpLogFormat: '%ci:%cp [%t] %ft %b/%s %B %bq %HM %HU %HV' ----- - -Disable Ingress access logging. - -* To disable Ingress access logging, leave `spec.logging` or `spec.logging.access` empty: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - name: default - namespace: openshift-ingress-operator -spec: - replicas: 2 - endpointPublishingStrategy: - type: NodePortService - logging: - access: null ----- diff --git a/modules/nw-configuring-high-performance-multicast-with-sriov.adoc b/modules/nw-configuring-high-performance-multicast-with-sriov.adoc deleted file mode 100644 index f94f5314aff3..000000000000 --- a/modules/nw-configuring-high-performance-multicast-with-sriov.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/using-sriov-multicast.adoc - -[id="nw-configuring-high-performance-multicast-with-sriov_{context}"] -= Configuring high performance multicast - -The OpenShift SDN default Container Network Interface (CNI) network provider supports multicast between pods on the default network. This is best used for low-bandwidth coordination or service discovery, and not high-bandwidth applications. -For applications such as streaming media, like Internet Protocol television (IPTV) and multipoint videoconferencing, you can utilize Single Root I/O Virtualization (SR-IOV) hardware to provide near-native performance. - -When using additional SR-IOV interfaces for multicast: - -* Multicast packages must be sent or received by a pod through the additional SR-IOV interface. -* The physical network which connects the SR-IOV interfaces decides the -multicast routing and topology, which is not controlled by {product-title}. - -[id="nw-using-an-sriov-interface-for-multicast_{context}"] -= Using an SR-IOV interface for multicast - -The follow procedure creates an example SR-IOV interface for multicast. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster with a user that has the `cluster-admin` role. - -.Procedure - -. Create a `SriovNetworkNodePolicy` object: -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: policy-example - namespace: openshift-sriov-network-operator -spec: - resourceName: example - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - numVfs: 4 - nicSelector: - vendor: "8086" - pfNames: ['ens803f0'] - rootDevices: ['0000:86:00.0'] ----- - -. Create a `SriovNetwork` object: -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetwork -metadata: - name: net-example - namespace: openshift-sriov-network-operator -spec: - networkNamespace: default - ipam: | <1> - { - "type": "host-local", <1> - "subnet": "10.56.217.0/24", - "rangeStart": "10.56.217.171", - "rangeEnd": "10.56.217.181", - "routes": [ - {"dst": "224.0.0.0/5"}, - {"dst": "232.0.0.0/5"} - ], - "gateway": "10.56.217.1" - } - resourceName: example ----- -<1> If you choose to configure DHCP as IPAM, ensure that you provision the following default routes through your DHCP server: `224.0.0.0/5` and `232.0.0.0/5`. This is to override the static multicast route set by the default network provider. - -. Create a pod with multicast application: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: testpmd - namespace: default - annotations: - k8s.v1.cni.cncf.io/networks: nic1 -spec: - containers: - - name: example - image: rhel7:latest - securityContext: - capabilities: - add: ["NET_ADMIN"] <1> - command: [ "sleep", "infinity"] ----- -<1> The `NET_ADMIN` capability is required only if your application needs to -assign the multicast IP address to the SR-IOV interface. Otherwise, it can be -omitted. diff --git a/modules/nw-configuring-route-timeouts.adoc b/modules/nw-configuring-route-timeouts.adoc deleted file mode 100644 index 57c1b3c34b1a..000000000000 --- a/modules/nw-configuring-route-timeouts.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module filename: nw-configuring-route-timeouts.adoc -// Module included in the following assemblies: -// * networking/configuring-routing.adoc - -[id="nw-configuring-route-timeouts_{context}"] -= Configuring route timeouts - -You can configure the default timeouts for an existing route when you -have services in need of a low timeout, which is required for Service Level -Availability (SLA) purposes, or a high timeout, for cases with a slow -back end. - -.Prerequisites -* You need a deployed Ingress Controller on a running cluster. - -.Procedure -. Using the `oc annotate` command, add the timeout to the route: -+ -[source,terminal] ----- -$ oc annotate route <route_name> \ - --overwrite haproxy.router.openshift.io/timeout=<timeout><time_unit> <1> ----- -<1> Supported time units are microseconds (us), milliseconds (ms), seconds (s), -minutes (m), hours (h), or days (d). -+ -The following example sets a timeout of two seconds on a route named `myroute`: -+ -[source,terminal] ----- -$ oc annotate route myroute --overwrite haproxy.router.openshift.io/timeout=2s ----- diff --git a/modules/nw-create-load-balancer-service.adoc b/modules/nw-create-load-balancer-service.adoc deleted file mode 100644 index 6cbde8cf6823..000000000000 --- a/modules/nw-create-load-balancer-service.adoc +++ /dev/null @@ -1,116 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/getting-traffic-cluster.adoc - -[id="nw-create-load-balancer-service_{context}"] -= Creating a load balancer service - -Use the following procedure to create a load balancer service. - -.Prerequisites - -* Make sure that the project and service you want to expose exist. - -.Procedure - -To create a load balancer service: - -. Log in to {product-title}. - -. Load the project where the service you want to expose is located. -+ -[source,terminal] ----- -$ oc project project1 ----- - -. Open a text file on the master node and paste the following text, editing the -file as needed: -+ -.Sample load balancer configuration file ----- -apiVersion: v1 -kind: Service -metadata: - name: egress-2 <1> -spec: - ports: - - name: db - port: 3306 <2> - loadBalancerIP: - type: LoadBalancer <3> - selector: - name: mysql <4> ----- -<1> Enter a descriptive name for the load balancer service. -<2> Enter the same port that the service you want to expose is listening on. -<3> Enter `loadbalancer` as the type. -<4> Enter the name of the service. - -. Save and exit the file. - -. Run the following command to create the service: -+ -[source,terminal] ----- -$ oc create -f <file-name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f mysql-lb.yaml ----- - -. Execute the following command to view the new service: -+ -[source,terminal] ----- -$ oc get svc ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -egress-2 LoadBalancer 172.30.22.226 ad42f5d8b303045-487804948.example.com 3306:30357/TCP 15m ----- -+ -The service has an external IP address automatically assigned if there is a cloud -provider enabled. - -. On the master, use a tool, such as cURL, to make sure you can reach the service -using the public IP address: -+ -[source,terminal] ----- -$ curl <public-ip>:<port> ----- -+ -For example: -+ -[source,terminal] ----- -$ curl 172.29.121.74:3306 ----- -+ -The examples in this section use a MySQL service, which requires a client application. -If you get a string of characters with the `Got packets out of order` message, -you are connecting with the service: -+ -If you have a MySQL client, log in with the standard CLI command: -+ -[source,terminal] ----- -$ mysql -h 172.30.131.89 -u admin -p ----- -+ -.Example output -[source,terminal] ----- -Enter password: -Welcome to the MariaDB monitor. Commands end with ; or \g. - -MySQL [(none)]> ----- diff --git a/modules/nw-creating-project-and-service.adoc b/modules/nw-creating-project-and-service.adoc deleted file mode 100644 index d5758c5ff6d5..000000000000 --- a/modules/nw-creating-project-and-service.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc - -[id="nw-creating-project-and-service_{context}"] -= Creating a project and service - -If the project and service that you want to expose do not exist, first create -the project, then the service. - -If the project and service already exist, skip to the procedure on exposing the -service to create a route. - -.Prerequisites - -* Install the `oc` CLI and log in as a cluster administrator. - -.Procedure - -. Create a new project for your service: -+ -[source,terminal] ----- -$ oc new-project <project_name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc new-project myproject ----- - -. Use the `oc new-app` command to create a service. For example: -+ -[source,terminal] ----- -$ oc new-app \ - -e MYSQL_USER=admin \ - -e MYSQL_PASSWORD=redhat \ - -e MYSQL_DATABASE=mysqldb \ - registry.redhat.io/rhscl/mysql-80-rhel7 ----- - -. Run the following command to see that the new service is created: -+ -[source,terminal] ----- -$ oc get svc -n myproject ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -mysql-80-rhel7 ClusterIP 172.30.63.31 <none> 3306/TCP 4m55s ----- -+ -By default, the new service does not have an external IP address. diff --git a/modules/nw-disabling-multicast.adoc b/modules/nw-disabling-multicast.adoc deleted file mode 100644 index 800085e0b47b..000000000000 --- a/modules/nw-disabling-multicast.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/disabling-multicast.adoc -// * networking/ovn_kubernetes_network_provider/disabling-multicast.adoc - -ifeval::["{context}" == "openshift-sdn-disabling-multicast"] -:namespace: netnamespace -:annotation: netnamespace.network.openshift.io/multicast-enabled- -endif::[] -ifeval::["{context}" == "ovn-kubernetes-disabling-multicast"] -:namespace: namespace -:annotation: k8s.ovn.org/multicast-enabled- -endif::[] - -[id="nw-disabling-multicast_{context}"] -= Disabling multicast between pods - -You can disable multicast between pods for your project. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster with a user that has the `cluster-admin` role. - -.Procedure - -* Disable multicast by running the following command: -+ -[source,terminal,subs="attributes+"] ----- -$ oc annotate {namespace} <namespace> \ <1> - {annotation} ----- -+ -<1> The `namespace` for the project you want to disable multicast for. - -ifeval::["{context}" == "openshift-sdn-disabling-multicast"] -:!annotation: -:!namespace: -endif::[] -ifeval::["{context}" == "ovn-kubernetes-disabling-multicast"] -:!annotation: -:!namespace: -endif::[] diff --git a/modules/nw-dns-forward.adoc b/modules/nw-dns-forward.adoc deleted file mode 100644 index 3936a57f05c8..000000000000 --- a/modules/nw-dns-forward.adoc +++ /dev/null @@ -1,100 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/dns-operator.adoc - -[id="nw-dns-forward_{context}"] -= Using DNS forwarding - -You can use DNS forwarding to override the forwarding configuration identified in `/etc/resolv.conf` on a per-zone basis by specifying which name server should be used for a given zone. If the forwarded zone is the Ingress domain managed by {product-title}, then the upstream name server must be authorized for the domain. - -.Procedure - -. Modify the DNS Operator object named `default`: -+ -[source,terminal] ----- -$ oc edit dns.operator/default ----- -+ -This allows the Operator to create and update the ConfigMap named `dns-default` with additional server configuration blocks based on `Server`. If none of the servers has a zone that matches the query, then name resolution falls back to the name servers that are specified in `/etc/resolv.conf`. -+ -.Sample DNS -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: DNS -metadata: - name: default -spec: - servers: - - name: foo-server <1> - zones: <2> - - foo.com - forwardPlugin: - upstreams: <3> - - 1.1.1.1 - - 2.2.2.2:5353 - - name: bar-server - zones: - - bar.com - - example.com - forwardPlugin: - upstreams: - - 3.3.3.3 - - 4.4.4.4:5454 ----- -<1> `name` must comply with the `rfc6335` service name syntax. -<2> `zones` must conform to the definition of a `subdomain` in `rfc1123`. The cluster domain, `cluster.local`, is an invalid `subdomain` for `zones`. -<3> A maximum of 15 `upstreams` is allowed per `forwardPlugin`. -+ -[NOTE] -==== -If `servers` is undefined or invalid, the ConfigMap only contains the default server. -==== -+ -. View the ConfigMap: -+ -[source,terminal] ----- -$ oc get configmap/dns-default -n openshift-dns -o yaml ----- -+ -.Sample DNS ConfigMap based on previous sample DNS -[source,yaml] ----- -apiVersion: v1 -data: - Corefile: | - foo.com:5353 { - forward . 1.1.1.1 2.2.2.2:5353 - } - bar.com:5353 example.com:5353 { - forward . 3.3.3.3 4.4.4.4:5454 <1> - } - .:5353 { - errors - health - kubernetes cluster.local in-addr.arpa ip6.arpa { - pods insecure - upstream - fallthrough in-addr.arpa ip6.arpa - } - prometheus :9153 - forward . /etc/resolv.conf { - policy sequential - } - cache 30 - reload - } -kind: ConfigMap -metadata: - labels: - dns.operator.openshift.io/owning-dns: default - name: dns-default - namespace: openshift-dns ----- -<1> Changes to the `forwardPlugin` triggers a rolling update of the CoreDNS daemon set. - -.Additional resources - -* For more information on DNS forwarding, see the link:https://coredns.io/plugins/forward/[CoreDNS forward documentation]. diff --git a/modules/nw-dns-operator-logs.adoc b/modules/nw-dns-operator-logs.adoc deleted file mode 100644 index b5ecaeba3fdc..000000000000 --- a/modules/nw-dns-operator-logs.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * dns/dns-operator.adoc - -[id="nw-dns-operator-logs_{context}"] -= DNS Operator logs - -You can view DNS Operator logs by using the `oc logs` command. - -.Procedure - -View the logs of the DNS Operator: -[source,terminal] ----- -$ oc logs -n openshift-dns-operator deployment/dns-operator -c dns-operator ----- diff --git a/modules/nw-dns-operator-status.adoc b/modules/nw-dns-operator-status.adoc deleted file mode 100644 index 3fada46d5eaa..000000000000 --- a/modules/nw-dns-operator-status.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * dns/dns-operator.adoc - -[id="nw-dns-operator-status_{context}"] -= DNS Operator status - -You can inspect the status and view the details of the DNS Operator -using the `oc describe` command. - -.Procedure - -View the status of the DNS Operator: -[source,terminal] ----- -$ oc describe clusteroperators/dns ----- diff --git a/modules/nw-dns-operator.adoc b/modules/nw-dns-operator.adoc deleted file mode 100644 index b4e085bf926e..000000000000 --- a/modules/nw-dns-operator.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// * networking/dns/dns-operator.adoc - -[id="dns-operator_{context}"] -= DNS Operator - -The DNS Operator implements the `dns` API from the `operator.openshift.io` API -group. The Operator deploys CoreDNS using a daemon set, creates a service for -the daemon set, and configures the kubelet to instruct pods to use the CoreDNS -service IP address for name resolution. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -.Procedure - -The DNS Operator is deployed during installation with a `Deployment` object. - -. Use the `oc get` command to view the deployment status: -+ -[source,terminal] ----- -$ oc get -n openshift-dns-operator deployment/dns-operator ----- -+ -.Example output -[source,terminal] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -dns-operator 1/1 1 1 23h ----- - -. Use the `oc get` command to view the state of the DNS Operator: -+ -[source,terminal] ----- -$ oc get clusteroperator/dns ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -dns 4.1.0-0.11 True False False 92m ----- -+ -`AVAILABLE`, `PROGRESSING` and `DEGRADED` provide information about the status of the operator. `AVAILABLE` is `True` when at least 1 pod from the CoreDNS daemon set reports an `Available` status condition. -endif::[] diff --git a/modules/nw-dns-view.adoc b/modules/nw-dns-view.adoc deleted file mode 100644 index 212732840ed7..000000000000 --- a/modules/nw-dns-view.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * dns/dns-operator.adoc - -[id="nw-dns-view_{context}"] -= View the default DNS - -Every new {product-title} installation has a `dns.operator` named `default`. - -.Procedure - -. Use the `oc describe` command to view the default `dns`: -+ -[source,terminal] ----- -$ oc describe dns.operator/default ----- -+ -.Example output -[source,terminal] ----- -Name: default -Namespace: -Labels: <none> -Annotations: <none> -API Version: operator.openshift.io/v1 -Kind: DNS -... -Status: - Cluster Domain: cluster.local <1> - Cluster IP: 172.30.0.10 <2> -... ----- -<1> The Cluster Domain field is the base DNS domain used to construct fully -qualified pod and service domain names. -<2> The Cluster IP is the address pods query for name resolution. The IP is -defined as the 10th address in the service CIDR range. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -. To find the service CIDR of your cluster, -use the `oc get` command: -+ -[source,terminal] ----- -$ oc get networks.config/cluster -o jsonpath='{$.status.serviceNetwork}' ----- - -.Example output -[source,terminal] ----- -[172.30.0.0/16] ----- -endif::[] diff --git a/modules/nw-egress-ips-about.adoc b/modules/nw-egress-ips-about.adoc deleted file mode 100644 index cfc4fbd2581e..000000000000 --- a/modules/nw-egress-ips-about.adoc +++ /dev/null @@ -1,219 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/assigning-egress-ips.adoc -// * networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc - -ifeval::["{context}" == "egress-ips"] -:openshift-sdn: -endif::[] -ifeval::["{context}" == "configuring-egress-ips-ovn"] -:ovn: -endif::[] - -ifdef::ovn[] -[id="nw-egress-ips-about_{context}"] -= Egress IP address architectural design and implementation - -The {product-title} egress IP address functionality allows you to ensure that the traffic from one or more pods in one or more namespaces has a consistent source IP address for services outside the cluster network. - -For example, you might have a pod that periodically queries a database that is hosted on a server outside of your cluster. To enforce access requirements for the server, a packet filtering device is configured to allow traffic only from specific IP addresses. -To ensure that you can reliably allow access to the server from only that specific pod, you can configure a specific egress IP address for the pod that makes the requests to the server. - -An egress IP address is implemented as an additional IP address on the primary network interface of a node and must be in the same subnet as the primary IP address of the node. The additional IP address must not be assigned to any other node in the cluster. - -[id="nw-egress-ips-platform-support_{context}"] -== Platform support - -Support for the egress IP address functionality on various platforms is summarized in the following table: - -[IMPORTANT] -==== -The egress IP address implementation is not compatible with Amazon Web Services (AWS), Azure Cloud, or any other public cloud platform incompatible with the automatic layer 2 network manipulation required by the egress IP feature. -==== - -[cols="1,1",options="header"] -|=== - -| Platform | Supported - -| Bare metal | Yes -| vSphere | Yes -| {rh-openstack-first} | No -| Public cloud | No - -|=== - -[id="nw-egress-ips-considerations_{context}"] -== Assignment of egress IPs to pods - -To assign one or more egress IPs to a namespace or specific pods in a namespace, the following conditions must be satisfied: - -- At least one node in your cluster must have the `k8s.ovn.org/egress-assignable: ""` label. -- An `EgressIP` object exists that defines one or more egress IP addresses to use as the source IP address for traffic leaving the cluster from pods in a namespace. - -[IMPORTANT] -==== -If you create `EgressIP` objects prior to labeling any nodes in your cluster for egress IP assignment, {product-title} might assign every egress IP address to the first node with the `k8s.ovn.org/egress-assignable: ""` label. - -To ensure that egress IP addresses are widely distributed across nodes in the cluster, always apply the label to the nodes you intent to host the egress IP addresses before creating any `EgressIP` objects. -==== - -[id="nw-egress-ips-node-assignment_{context}"] -== Assignment of egress IPs to nodes - -When creating an `EgressIP` object, the following conditions apply to nodes that are labeled with the `k8s.ovn.org/egress-assignable: ""` label: - -- An egress IP address is never assigned to more than one node at a time. -- An egress IP address is equally balanced between available nodes that can host the egress IP address. -- If the `spec.EgressIPs` array in an `EgressIP` object specifies more than one IP address, no node will ever host more than one of the specified addresses. -- If a node becomes unavailable, any egress IP addresses assigned to it are automatically reassigned, subject to the previously described conditions. - -When a pod matches the selector for multiple `EgressIP` objects, there is no guarantee which of the egress IP addresses that are specified in the `EgressIP` objects is assigned as the egress IP address for the pod. - -[id="nw-egress-ips-node-architecture_{context}"] -== Architectural diagram of an egress IP address configuration - -The following diagram depicts an egress IP address configuration. The diagram describes four pods in two different namespaces running on three nodes in a cluster. The nodes are assigned IP addresses from the `192.168.126.0/18` CIDR block on the host network. - -// Source: https://github.com/redhataccess/documentation-svg-assets/blob/master/for-web/121_OpenShift/121_OpenShift_engress_IP_Topology_1020.svg -image::nw-egress-ips-diagram.svg[Architectural diagram for the egress IP feature.] - -Both Node 1 and Node 3 are labeled with `k8s.ovn.org/egress-assignable: ""` and thus available for the assignment of egress IP addresses. - -The dashed lines in the diagram depict the traffic flow from pod1, pod2, and pod3 traveling through the pod network to egress the cluster from Node 1 and Node 3. When an external service receives traffic from any of the pods selected by the example `EgressIP` object, the source IP address is either `192.168.126.10` or `192.168.126.102`. - -The following resources from the diagram are illustrated in detail: - -`Namespace` objects:: -+ --- -The namespaces are defined in the following manifest: - -.Namespace objects -[source,yaml] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: namespace1 - labels: - env: prod ---- -apiVersion: v1 -kind: Namespace -metadata: - name: namespace2 - labels: - env: prod ----- --- - -`EgressIP` object:: -+ --- -The following `EgressIP` object describes a configuration that selects all pods in any namespace with the `env` label set to `prod`. The egress IP addresses for the selected pods are `192.168.126.10` and `192.168.126.102`. - -.`EgressIP` object -[source,yaml] ----- -apiVersion: k8s.ovn.org/v1 -kind: EgressIP -metadata: - name: egressips-prod -spec: - egressIPs: - - 192.168.126.10 - - 192.168.126.102 - namespaceSelector: - matchLabels: - env: prod -status: - assignments: - - node: node1 - egressIP: 192.168.126.10 - - node: node3 - egressIP: 192.168.126.102 ----- - -For the configuration in the previous example, {product-title} assigns both egress IP addresses to the available nodes. The `status` field reflects whether and where the egress IP addresses are assigned. --- -endif::ovn[] - -ifdef::openshift-sdn[] -[id="nw-egress-ips-about_{context}"] -= Egress IP address assignment for project egress traffic - -By configuring an egress IP address for a project, all outgoing external connections from the specified project will share the same, fixed source IP address. -External resources can recognize traffic from a particular project based on the egress IP address. -An egress IP address assigned to a project is different from the egress router, which is used to send traffic to specific destinations. - -Egress IP addresses are implemented as additional IP addresses on the primary network interface of the node and must be in the same subnet as the node's primary IP address. - -[IMPORTANT] -==== -Egress IP addresses must not be configured in any Linux network configuration files, such as `ifcfg-eth0`. - -Allowing additional IP addresses on the primary network interface might require extra configuration when using some cloud or VM solutions. -==== - -You can assign egress IP addresses to namespaces by setting the `egressIPs` parameter of the `NetNamespace` object. After an egress IP is associated with a project, OpenShift SDN allows you to assign egress IPs to hosts in two ways: - -* In the _automatically assigned_ approach, an egress IP address range is assigned to a node. -* In the _manually assigned_ approach, a list of one or more egress IP address is assigned to a node. - -Namespaces that request an egress IP address are matched with nodes that can host those egress IP addresses, and then the egress IP addresses are assigned to those nodes. -If the `egressIPs` parameter is set on a `NetNamespace` object, but no node hosts that egress IP address, then egress traffic from the namespace will be dropped. - -High availability of nodes is automatic. -If a node that hosts an egress IP address is unreachable and there are nodes that are able to host that egress IP address, then the egress IP address will move to a new node. -When the unreachable node comes back online, the egress IP address automatically moves to balance egress IP addresses across nodes. - -[IMPORTANT] -==== -The following limitations apply when using egress IP addresses with the OpenShift SDN cluster network provider: - -- You cannot use manually assigned and automatically assigned egress IP addresses on the same nodes. -- If you manually assign egress IP addresses from an IP address range, you must not make that range available for automatic IP assignment. -- You cannot share egress IP addresses across multiple namespaces using the OpenShift SDN egress IP address implementation. -ifeval::["{product-version}" >= "4.6"] -If you need to share IP addresses across namespaces, the OVN-Kubernetes cluster network provider egress IP address implementation allows you to span IP addresses across multiple namespaces. -endif::[] -==== - -[NOTE] -==== -If you use OpenShift SDN in multitenant mode, you cannot use egress IP addresses with any namespace that is joined to another namespace by the projects that are associated with them. -For example, if `project1` and `project2` are joined by running the `oc adm pod-network join-projects --to=project1 project2` command, neither project can use an egress IP address. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1645577[BZ#1645577]. -==== - -[id="considerations-automatic-egress-ips"] -== Considerations when using automatically assigned egress IP addresses - -When using the automatic assignment approach for egress IP addresses the following considerations apply: - -- You set the `egressCIDRs` parameter of each node's `HostSubnet` resource to indicate the range of egress IP addresses that can be hosted by a node. -{product-title} sets the `egressIPs` parameter of the `HostSubnet` resource based on the IP address range you specify. -- Only a single egress IP address per namespace is supported when using the automatic assignment mode. - -If the node hosting the namespace's egress IP address is unreachable, {product-title} will reassign the egress IP address to another node with a compatible egress IP address range. -The automatic assignment approach works best for clusters installed in environments with flexibility in associating additional IP addresses with nodes. - -[id="considerations-manual-egress-ips"] -== Considerations when using manually assigned egress IP addresses - -When using the manual assignment approach for egress IP addresses the following considerations apply: - -- You set the `egressIPs` parameter of each node's `HostSubnet` resource to indicate the IP addresses that can be hosted by a node. -- Multiple egress IP addresses per namespace are supported. - -When a namespace has multiple egress IP addresses, if the node hosting the first egress IP address is unreachable, {product-title} will automatically switch to using the next available egress IP address until the first egress IP address is reachable again. - -This approach is recommended for clusters installed in public cloud environments, where there can be limitations on associating additional IP addresses with nodes. -endif::openshift-sdn[] - -ifdef::openshift-sdn[] -:!openshift-sdn: -endif::openshift-sdn[] -ifdef::ovn[] -:!ovn: -endif::ovn[] diff --git a/modules/nw-egress-ips-assign.adoc b/modules/nw-egress-ips-assign.adoc deleted file mode 100644 index b5b1f0580be2..000000000000 --- a/modules/nw-egress-ips-assign.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc - -[id="nw-egress-ips-assign_{context}"] -= Assigning an egress IP address to a namespace - -You can assign one or more egress IP addresses to a namespace or to specific pods in a namespace. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in to the cluster as a cluster administrator. -* Configure at least one node to host an egress IP address. - -.Procedure - -. Create an `EgressIP` object: -.. Create a `<egressips_name>.yaml` file where `<egressips_name>` is the name of the object. -.. In the file that you created, define an `EgressIPs` object, as in the following example: -+ -[source,yaml] ----- -apiVersion: k8s.ovn.org/v1 -kind: EgressIP -metadata: - name: egress-project1 -spec: - egressIPs: - - 192.168.127.10 - - 192.168.127.11 - namespaceSelector: - matchLabels: - env: qa ----- - -. To create the object, enter the following command. -+ -[source,terminal] ----- -$ oc apply -f <egressips_name>.yaml <1> ----- -<1> Replace `<egressips_name>` with the name of the object. -+ -.Example output -[source,terminal] ----- -egressips.k8s.ovn.org/<egressips_name> created ----- - -. Optional: Save the `<egressips_name>.yaml` file so that you can make changes later. diff --git a/modules/nw-egress-ips-automatic.adoc b/modules/nw-egress-ips-automatic.adoc deleted file mode 100644 index eaad2942d367..000000000000 --- a/modules/nw-egress-ips-automatic.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/assigning-egress-ips.adoc - -[id="nw-egress-ips-automatic_{context}"] -= Configuring automatically assigned egress IP addresses for a namespace - -In {product-title} you can enable automatic assignment of an egress IP address -for a specific namespace across one or more nodes. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Update the `NetNamespace` object with the egress IP address using the -following JSON: -+ -[source,terminal] ----- - $ oc patch netnamespace <project_name> --type=merge -p \ <1> - '{ - "egressIPs": [ - "<ip_address>" <2> - ] - }' ----- -<1> Specify the name of the project. -<2> Specify a single egress IP address. Using multiple IP addresses is not -supported. -+ -For example, to assign `project1` to an IP address of 192.168.1.100 and -`project2` to an IP address of 192.168.1.101: -+ -[source,terminal] ----- -$ oc patch netnamespace project1 --type=merge -p \ - '{"egressIPs": ["192.168.1.100"]}' -$ oc patch netnamespace project2 --type=merge -p \ - '{"egressIPs": ["192.168.1.101"]}' ----- -+ -. Indicate which nodes can host egress IP addresses by setting the `egressCIDRs` -parameter for each host using the following JSON: -+ -[source,terminal] ----- -$ oc patch hostsubnet <node_name> --type=merge -p \ <1> - '{ - "egressCIDRs": [ - "<ip_address_range_1>", "<ip_address_range_2>" <2> - ] - }' ----- -<1> Specify a node name. -<2> Specify one or more IP address ranges in CIDR format. -+ -For example, to set `node1` and `node2` to host egress IP addresses -in the range 192.168.1.0 to 192.168.1.255: -+ -[source,terminal] ----- -$ oc patch hostsubnet node1 --type=merge -p \ - '{"egressCIDRs": ["192.168.1.0/24"]}' -$ oc patch hostsubnet node2 --type=merge -p \ - '{"egressCIDRs": ["192.168.1.0/24"]}' ----- -+ -{product-title} automatically assigns specific egress IP addresses to -available nodes in a balanced way. In this case, it assigns the egress IP -address 192.168.1.100 to `node1` and the egress IP address 192.168.1.101 to -`node2` or vice versa. diff --git a/modules/nw-egress-ips-node.adoc b/modules/nw-egress-ips-node.adoc deleted file mode 100644 index fcf458550f27..000000000000 --- a/modules/nw-egress-ips-node.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc - -[id="nw-egress-ips-node_{context}"] -= Labeling a node to host egress IP addresses - -You can apply the `k8s.ovn.org/egress-assignable=""` label to a node in your cluster so that {product-title} can assign one or more egress IP addresses to the node. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in to the cluster as a cluster administrator. - -.Procedure - -* To label a node so that it can host one or more egress IP addresses, enter the following command: -+ -[source,terminal] ----- -$ oc label nodes <node_name> k8s.ovn.org/egress-assignable="" <1> ----- -+ -<1> The name of the node to label. diff --git a/modules/nw-egress-ips-object.adoc b/modules/nw-egress-ips-object.adoc deleted file mode 100644 index 8d6c006d1177..000000000000 --- a/modules/nw-egress-ips-object.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc - -[id="nw-egress-ips-object_{context}"] -= EgressIP object - -The following YAML describes the API for the `EgressIP` object. The scope of the object is cluster-wide; it is not created in a namespace. - -[source,yaml] ----- -apiVersion: k8s.ovn.org/v1 -kind: EgressIP -metadata: - name: <name> <1> -spec: - egressIPs: <2> - - <ip_address> - namespaceSelector: <3> - ... - podSelector: <4> - ... ----- -<1> The name for the `EgressIPs` object. - -<2> An array of one or more IP addresses. - -<3> One or more selectors for the namespaces to associate the egress IP addresses with. - -<4> Optional: One or more selectors for pods in the specified namespaces to associate egress IP addresses with. Applying these selectors allows for the selection of a subset of pods within a namespace. - -The following YAML describes the stanza for the namespace selector: - -.Namespace selector stanza -[source,yaml] ----- -namespaceSelector: <1> - matchLabels: - <label_name>: <label_value> ----- -<1> One or more matching rules for namespaces. If more than one match rule is provided, all matching namespaces are selected. - -The following YAML describes the optional stanza for the pod selector: - -.Pod selector stanza -[source,yaml] ----- -podSelector: <1> - matchLabels: - <label_name>: <label_value> ----- -<1> Optional: One or more matching rules for pods in the namespaces that match the specified `namespaceSelector` rules. If specified, only pods that match are selected. Others pods in the namespace are not selected. - -In the following example, the `EgressIP` object associates the `192.168.126.11` and `192.168.126.102` egress IP addresses with pods that have the `app` label set to `web` and are in the namespaces that have the `env` label set to `prod`: - -.Example `EgressIP` object -[source,yaml] ----- -apiVersion: k8s.ovn.org/v1 -kind: EgressIP -metadata: - name: egress-group1 -spec: - egressIPs: - - 192.168.126.11 - - 192.168.126.102 - podSelector: - matchLabels: - app: web - namespaceSelector: - matchLabels: - env: prod ----- - -In the following example, the `EgressIP` object associates the `192.168.127.30` and `192.168.127.40` egress IP addresses with any pods that do not have the `environment` label set to `development`: - -.Example `EgressIP` object -[source,yaml] ----- -apiVersion: k8s.ovn.org/v1 -kind: EgressIP -metadata: - name: egress-group2 -spec: - egressIPs: - - 192.168.127.30 - - 192.168.127.40 - namespaceSelector: - matchExpressions: - - key: environment - operator: NotIn - values: - - development ----- diff --git a/modules/nw-egress-ips-static.adoc b/modules/nw-egress-ips-static.adoc deleted file mode 100644 index 1b525027ca68..000000000000 --- a/modules/nw-egress-ips-static.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/assigning-egress-ips.adoc - -[id="nw-egress-ips-static_{context}"] -= Configuring manually assigned egress IP addresses for a namespace - -In {product-title} you can associate one or more egress IP addresses with a namespace. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Update the `NetNamespace` object by specifying the following JSON -object with the desired IP addresses: -+ -[source,terminal] ----- -$ oc patch netnamespace <project> --type=merge -p \ <1> - '{ - "egressIPs": [ <2> - "<ip_address>" - ] - }' ----- -<1> Specify the name of the project. -<2> Specify one or more egress IP addresses. The `egressIPs` parameter is an -array. -+ -For example, to assign the `project1` project to an IP address of -`192.168.1.100`: -+ -[source,terminal] ----- -$ oc patch netnamespace project1 --type=merge \ - -p '{"egressIPs": ["192.168.1.100"]}' ----- -+ -You can set `egressIPs` to two or more IP addresses on different nodes to -provide high availability. If multiple egress IP addresses are set, pods use the -first IP in the list for egress, but if the node hosting that IP address fails, -pods switch to using the next IP in the list after a short delay. - -. Manually assign the egress IP to the node hosts. Set the `egressIPs` parameter -on the `HostSubnet` object on the node host. Using the following JSON, include -as many IPs as you want to assign to that node host: -+ -[source,terminal] ----- -$ oc patch hostsubnet <node_name> --type=merge -p \ <1> - '{ - "egressIPs": [ <2> - "<ip_address_1>", - "<ip_address_N>" - ] - }' ----- -<1> Specify the name of the node. -<2> Specify one or more egress IP addresses. The `egressIPs` field is an array. -+ -For example, to specify that `node1` should have the egress IPs `192.168.1.100`, -`192.168.1.101`, and `192.168.1.102`: -+ -[source,terminal] ----- -$ oc patch hostsubnet node1 --type=merge -p \ - '{"egressIPs": ["192.168.1.100", "192.168.1.101", "192.168.1.102"]}' ----- -+ -In the previous example, all egress traffic for `project1` will be routed to the -node hosting the specified egress IP, and then connected (using NAT) to that IP -address. diff --git a/modules/nw-egress-router-about.adoc b/modules/nw-egress-router-about.adoc deleted file mode 100644 index 75b8d0414bd6..000000000000 --- a/modules/nw-egress-router-about.adoc +++ /dev/null @@ -1,176 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/using-an-egress-router.adoc -// * networking/ovn_kubernetes_network_provider/using-an-egress-router-ovn.adoc - -ifeval::["{context}" == "using-an-egress-router-ovn"] -:ovn: -:egress-pod-image-name: registry.redhat.io/openshift3/ose-pod - -// Image names are different for OKD -ifdef::openshift-origin[] -:egress-pod-image-name: quay.io/openshift/origin-pod -endif::[] - -endif::[] - -ifeval::["{context}" == "using-an-egress-router"] -:openshift-sdn: -endif::[] - -[id="nw-egress-router-about_{context}"] -= About an egress router pod - -The {product-title} egress router pod redirects traffic to a specified remote server from a private source IP address that is not used for any other purpose. An egress router pod enables you to send network traffic to servers that are set up to allow access only from specific IP addresses. - -[NOTE] -==== -The egress router pod is not intended for every outgoing connection. Creating large numbers of egress router pods can exceed the limits of your network hardware. For example, creating an egress router pod for every project or application could exceed the number of local MAC addresses that the network interface can handle before reverting to filtering MAC addresses in software. -==== - -[IMPORTANT] -==== -The egress router image is not compatible with Amazon AWS, Azure Cloud, or any other cloud platform that does not support layer 2 manipulations due to their incompatibility with macvlan traffic. -==== - -[id="nw-egress-router-about-modes_{context}"] -== Egress router modes - -In _redirect mode_, an egress router pod configures `iptables` rules to redirect traffic from its own IP address to one or more destination IP addresses. Client pods that need to use the reserved source IP address must be modified to connect to the egress router rather than connecting directly to the destination IP. - -ifdef::openshift-sdn[] -In _HTTP proxy mode_, an egress router pod runs as an HTTP proxy on port `8080`. This mode only works for clients that are connecting to HTTP-based or HTTPS-based services, but usually requires fewer changes to the client pods to get them to work. Many programs can be told to use an HTTP proxy by setting an environment variable. - -In _DNS proxy mode_, an egress router pod runs as a DNS proxy for TCP-based services from its own IP address to one or more destination IP addresses. To make use of the reserved, source IP address, client pods must be modified to connect to the egress router pod rather than connecting directly to the destination IP address. This modification ensures that external destinations treat traffic as though it were coming from a known source. - -Redirect mode works for all services except for HTTP and HTTPS. For HTTP and HTTPS services, use HTTP proxy mode. For TCP-based services with IP addresses or domain names, use DNS proxy mode. -endif::openshift-sdn[] - -ifdef::ovn[] -[NOTE] -==== -The egress router CNI plug-in supports redirect mode only. This is a difference with the egress router implementation that you can deploy with OpenShift SDN. Unlike the egress router for OpenShift SDN, the egress router CNI plug-in does not support _HTTP proxy mode_ or _DNS proxy mode_. -==== -endif::ovn[] - -[id="nw-egress-router-about-router-pod-implementation_{context}"] -== Egress router pod implementation - -ifdef::openshift-sdn[] -The egress router pod setup is performed by an initialization container. That container runs in a privileged context so that it can configure the macvlan interface and set up `iptables` rules. After the initialization container finishes setting up the `iptables` rules, it exits. Next the egress router pod executes the container to handle the egress router traffic. The image used varies depending on the egress router mode. - -The environment variables determine which addresses the egress-router image uses. The image configures the macvlan interface to use `EGRESS_SOURCE` as its IP address, with `EGRESS_GATEWAY` as the IP address for the gateway. - -Network Address Translation (NAT) rules are set up so that connections to the cluster IP address of the pod on any TCP or UDP port are redirected to the same port on IP address specified by the `EGRESS_DESTINATION` variable. - -If only some of the nodes in your cluster are capable of claiming the specified source IP address and using the specified gateway, you can specify a `nodeName` or `nodeSelector` to identify which nodes are acceptable. -endif::openshift-sdn[] - -ifdef::ovn[] -The egress router implementation uses the egress router Container Network Interface (CNI) plug-in. The plug-in adds a secondary network interface to a pod. - -An egress router is a pod that has two network interfaces. For example, the pod can have `eth0` and `net1` network interfaces. The `eth0` interface is on the cluster network and the pod continues to use the interface for ordinary cluster-related network traffic. The `net1` interface is on a secondary network and has an IP address and gateway for that network. Other pods in the {product-title} cluster can access the egress router service and the service enables the pods to access external services. The egress router acts as a bridge between pods and an external system. - -Traffic that leaves the egress router exits through a node, but the packets -have the MAC address of the `net1` interface from the egress router pod. -endif::ovn[] - -[id="nw-egress-router-about-deployments_{context}"] -== Deployment considerations - -An egress router pod adds an additional IP address and MAC address to the primary network interface of the node. As a result, you might need to configure your hypervisor or cloud provider to allow the additional address. - -{rh-openstack-first}:: - -If you deploy {product-title} on {rh-openstack}, you must allow traffic from the IP and MAC addresses of the egress router pod on your OpenStack environment. If you do not allow the traffic, then link:https://access.redhat.com/solutions/2803331[communication will fail]: -+ -[source,terminal] ----- -$ openstack port set --allowed-address \ - ip_address=<ip_address>,mac_address=<mac_address> <neutron_port_uuid> ----- - -{rh-virtualization-first}:: - -If you are using link:https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/html/administration_guide/sect-virtual_network_interface_cards#Explanation_of_Settings_in_the_VM_Interface_Profile_Window[{rh-virtualization}], you must select *No Network Filter* for the Virtual Network Interface Card (vNIC). - -VMware vSphere:: - -If you are using VMware vSphere, see the link:https://docs.vmware.com/en/VMware-vSphere/6.0/com.vmware.vsphere.security.doc/GUID-3507432E-AFEA-4B6B-B404-17A020575358.html[VMWare documentation for securing vSphere standard switches]. View and change VMWare vSphere default settings by selecting the host virtual switch from the vSphere Web Client. - -Specifically, ensure that the following are enabled: - -* https://docs.vmware.com/en/VMware-vSphere/6.0/com.vmware.vsphere.security.doc/GUID-942BD3AA-731B-4A05-8196-66F2B4BF1ACB.html[MAC Address Changes] -* https://docs.vmware.com/en/VMware-vSphere/6.0/com.vmware.vsphere.security.doc/GUID-7DC6486F-5400-44DF-8A62-6273798A2F80.html[Forged Transits] -* https://docs.vmware.com/en/VMware-vSphere/6.0/com.vmware.vsphere.security.doc/GUID-92F3AB1F-B4C5-4F25-A010-8820D7250350.html[Promiscuous Mode Operation] - -[id="nw-egress-router-about-failover_{context}"] -== Failover configuration - -To avoid downtime, you can deploy an egress router pod with a `Deployment` resource, as in the following example. To create a new `Service` object for the example deployment, use the `oc expose deployment/egress-demo-controller` command. - -ifdef::openshift-sdn[] -[source,yaml,subs="attributes+"] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: egress-demo-controller -spec: - replicas: 1 <1> - selector: - matchLabels: - name: egress-router - template: - metadata: - name: egress-router - labels: - name: egress-router - annotations: - pod.network.openshift.io/assign-macvlan: "true" - spec: <2> - initContainers: - ... - containers: - ... ----- -endif::openshift-sdn[] - -ifdef::ovn[] -[source,yaml,subs="attributes+"] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: egress-demo-controller -spec: - replicas: 1 <1> - selector: - matchLabels: - name: egress-router - template: - metadata: - name: egress-router - labels: - name: egress-router - annotations: - k8s.v1.cni.cncf.io/networks: egress-router-redirect - spec: <2> - containers: - - name: egress-router-redirect - image: {egress-pod-image-name} ----- -endif::ovn[] -<1> Ensure that replicas is set to `1`, because only one pod can use a given egress source IP address at any time. This means that only a single copy of the router runs on a node. - -<2> Specify the `Pod` object template for the egress router pod. - -// Clear temporary attributes -ifdef::openshift-sdn[] -:!openshift-sdn: -endif::[] - -ifdef::ovn[] -:!ovn: -:!egress-pod-image-name: -endif::[] \ No newline at end of file diff --git a/modules/nw-egress-router-configmap.adoc b/modules/nw-egress-router-configmap.adoc deleted file mode 100644 index 0c06d68297c4..000000000000 --- a/modules/nw-egress-router-configmap.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/configuring-egress-router-configmap.adoc - -[id="configuring-egress-router-configmap_{context}"] -= Configuring an egress router destination mappings with a config map - -For a large or frequently-changing set of destination mappings, you can use a config map to externally maintain the list. -An advantage of this approach is that permission to edit the config map can be delegated to users without `cluster-admin` privileges. Because the egress router pod requires a privileged container, it is not possible for users without `cluster-admin` privileges to edit the pod definition directly. - -[NOTE] -==== -The egress router pod does not automatically update when the config map changes. -You must restart the egress router pod to get updates. -==== - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create a file containing the mapping data for the egress router pod, as in the following example: -+ ----- -# Egress routes for Project "Test", version 3 - -80 tcp 203.0.113.25 - -8080 tcp 203.0.113.26 80 -8443 tcp 203.0.113.26 443 - -# Fallback -203.0.113.27 ----- -+ -You can put blank lines and comments into this file. - -. Create a `ConfigMap` object from the file: -+ -[source,terminal] ----- -$ oc delete configmap egress-routes --ignore-not-found ----- -+ -[source,terminal] ----- -$ oc create configmap egress-routes \ - --from-file=destination=my-egress-destination.txt ----- -+ -In the previous command, the `egress-routes` value is the name of the `ConfigMap` object to create and `my-egress-destination.txt` is the name of the file that the data is read from. - -. Create an egress router pod definition and specify the `configMapKeyRef` stanza for the `EGRESS_DESTINATION` field in the environment stanza: -+ -[source,yaml] ----- -... -env: -- name: EGRESS_DESTINATION - valueFrom: - configMapKeyRef: - name: egress-routes - key: destination -... ----- diff --git a/modules/nw-egress-router-dest-var.adoc b/modules/nw-egress-router-dest-var.adoc deleted file mode 100644 index d30a79c41912..000000000000 --- a/modules/nw-egress-router-dest-var.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/deploying-egress-router-layer3-redirection.adoc -// * networking/openshift_sdn/deploying-egress-router-http-redirection.adoc -// * networking/openshift_sdn/deploying-egress-router-dns-redirection.adoc - -// Every redirection mode supports an expanded environment variable - -// Conditional per flavor of Pod -ifeval::["{context}" == "deploying-egress-router-layer3-redirection"] -:redirect: -endif::[] -ifeval::["{context}" == "deploying-egress-router-http-redirection"] -:http: -endif::[] -ifeval::["{context}" == "deploying-egress-router-dns-redirection"] -:dns: -endif::[] - -[id="nw-egress-router-dest-var_{context}"] -= Egress destination configuration format - -ifdef::redirect[] -When an egress router pod is deployed in redirect mode, you can specify redirection rules by using one or more of the following formats: - -- `<port> <protocol> <ip_address>` - Incoming connections to the given `<port>` should be redirected to the same port on the given `<ip_address>`. `<protocol>` is either `tcp` or `udp`. -- `<port> <protocol> <ip_address> <remote_port>` - As above, except that the connection is redirected to a different `<remote_port>` on `<ip_address>`. -- `<ip_address>` - If the last line is a single IP address, then any connections on any other port will be redirected to the corresponding port on that IP address. If there is no fallback IP address then connections on other ports are rejected. - -In the example that follows several rules are defined: - -- The first line redirects traffic from local port `80` to port `80` on `203.0.113.25`. -- The second and third lines redirect local ports `8080` and `8443` to remote ports `80` and `443` on `203.0.113.26`. -- The last line matches traffic for any ports not specified in the previous rules. - -.Example configuration -[source,text] ----- -80 tcp 203.0.113.25 -8080 tcp 203.0.113.26 80 -8443 tcp 203.0.113.26 443 -203.0.113.27 ----- -endif::redirect[] - -ifdef::http[] -When an egress router pod is deployed in HTTP proxy mode, you can specify redirection rules by using one or more of the following formats. Each line in the configuration specifies one group of connections to allow or deny: - -- An IP address allows connections to that IP address, such as `192.168.1.1`. -- A CIDR range allows connections to that CIDR range, such as `192.168.1.0/24`. -- A host name allows proxying to that host, such as `www.example.com`. -- A domain name preceded by `+*.+` allows proxying to that domain and all of its subdomains, such as `*.example.com`. -- A `!` followed by any of the previous match expressions denies the connection instead. -- If the last line is `*`, then anything that is not explicitly denied is allowed. Otherwise, anything that is not allowed is denied. - -You can also use `*` to allow connections to all remote destinations. - -.Example configuration -[source,text] ----- -!*.example.com -!192.168.1.0/24 -192.168.2.1 -* ----- -endif::http[] - -ifdef::dns[] -When the router is deployed in DNS proxy mode, you specify a list of port and destination mappings. A destination may be either an IP address or a DNS name. - -An egress router pod supports the following formats for specifying port and destination mappings: - -Port and remote address:: - -You can specify a source port and a destination host by using the two field format: `<port> <remote_address>`. - -The host can be an IP address or a DNS name. If a DNS name is provided, DNS resolution occurs at runtime. For a given host, the proxy connects to the specified source port on the destination host when connecting to the destination host IP address. - -.Port and remote address pair example -[source,text] ----- -80 172.16.12.11 -100 example.com ----- - -Port, remote address, and remote port:: - -You can specify a source port, a destination host, and a destination port by using the three field format: `<port> <remote_address> <remote_port>`. - -The three field format behaves identically to the two field version, with the exception that the destination port can be different than the source port. - -.Port, remote address, and remote port example -[source,text] ----- -8080 192.168.60.252 80 -8443 web.example.com 443 ----- -endif::dns[] - -// unload flavors -ifdef::redirect[] -:!redirect: -endif::[] -ifdef::http[] -:!http: -endif::[] -ifdef::dns[] -:!dns: -endif::[] diff --git a/modules/nw-egress-router-dns-mode.adoc b/modules/nw-egress-router-dns-mode.adoc deleted file mode 100644 index 92768b926e63..000000000000 --- a/modules/nw-egress-router-dns-mode.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/deploying-egress-router-dns-redirection.adoc - -[id="nw-egress-router-dns-mode_{context}"] -= Deploying an egress router pod in DNS proxy mode - -In _DNS proxy mode_, an egress router pod acts as a DNS proxy for TCP-based services from its own IP address to one or more destination IP addresses. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create an egress router pod. - -. Create a service for the egress router pod: - -.. Create a file named `egress-router-service.yaml` that contains the following YAML. Set `spec.ports` to the list of ports that you defined previously for the `EGRESS_DNS_PROXY_DESTINATION` environment variable. -+ -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: egress-dns-svc -spec: - ports: - ... - type: ClusterIP - selector: - name: egress-dns-proxy ----- -+ -For example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: egress-dns-svc -spec: - ports: - - name: con1 - protocol: TCP - port: 80 - targetPort: 80 - - name: con2 - protocol: TCP - port: 100 - targetPort: 100 - type: ClusterIP - selector: - name: egress-dns-proxy ----- - -.. To create the service, enter the following command: -+ -[source,terminal] ----- -$ oc create -f egress-router-service.yaml ----- -+ -Pods can now connect to this service. The connections are proxied to the corresponding ports on the external server, using the reserved egress IP address. diff --git a/modules/nw-egress-router-http-proxy-mode.adoc b/modules/nw-egress-router-http-proxy-mode.adoc deleted file mode 100644 index 77e91066ac74..000000000000 --- a/modules/nw-egress-router-http-proxy-mode.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/deploying-egress-router-http-redirection.adoc - -[id="nw-egress-router-http-proxy-mode_{context}"] -= Deploying an egress router pod in HTTP proxy mode - -In _HTTP proxy mode_, an egress router pod runs as an HTTP proxy on port `8080`. This mode only works for clients that are connecting to HTTP-based or HTTPS-based services, but usually requires fewer changes to the client pods to get them to work. Many programs can be told to use an HTTP proxy by setting an environment variable. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create an egress router pod. - -. To ensure that other pods can find the IP address of the egress router pod, create a service to point to the egress router pod, as in the following example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: egress-1 -spec: - ports: - - name: http-proxy - port: 8080 <1> - type: ClusterIP - selector: - name: egress-1 ----- -<1> Ensure the `http` port is set to `8080`. - -. To configure the client pod (not the egress proxy pod) to use the HTTP proxy, set the `http_proxy` or `https_proxy` variables: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: app-1 - labels: - name: app-1 -spec: - containers: - env: - - name: http_proxy - value: http://egress-1:8080/ <1> - - name: https_proxy - value: http://egress-1:8080/ - ... ----- -<1> The service created in the previous step. -+ -[NOTE] -==== -Using the `http_proxy` and `https_proxy` environment variables is not necessary for all setups. If the above does not create a working setup, then consult the documentation for the tool or software you are running in the pod. -==== diff --git a/modules/nw-egress-router-network-attachment.adoc b/modules/nw-egress-router-network-attachment.adoc deleted file mode 100644 index 019a913aa41f..000000000000 --- a/modules/nw-egress-router-network-attachment.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/deploying-egress-router-ovn-redirection.adoc - -ifeval::["{context}" == "deploying-egress-router-ovn-redirection"] -:redirect: -:router-type: redirect -endif::[] - -[id="nw-egress-router-network-attachment_{context}"] -= Network attachment definition for an egress router in {router-type} mode - -Before a pod can act as an egress router, you must specify the network interface configuration as a `NetworkAttachmentDefinition` object. The object specifies information such as the IP address to attach to the egress router pod, the network destinations, and a network gateway. As the pod for the egress router starts, Multus uses the network attachment definition to add a network interface with the specified properties to the pod. - -.Example network attachment definition -[source,yaml] ----- -apiVersion: "k8s.cni.cncf.io/v1" -kind: NetworkAttachmentDefinition -metadata: - name: egress-router-redirect <.> -spec: - config: '{ - "cniVersion": "0.4.0", - "type": "egress-router", - "name": "egress-router", - "ip": { - "addresses": [ - "192.168.12.99/24" <.> - ], - "destinations": [ - "192.168.12.91/32" <.> - ], - "gateway": "192.168.12.1" <.> - } - }' ----- -<.> The name of the network attachment definition is used later in the specification for the egress router pod. - -<.> The `addresses` key specifies the reserved source IP address to use with the additional network interface. Specify a single IP address in CIDR notation, such as `192.168.12.99/24`. - -<.> The `destinations` key specifies a single IP address in CIDR notation that the egress router sends packets to. The network address translation (NAT) tables for the egress router pod are configured so that connections to the cluster IP address of the pod are redirected to the same port on the destination IP address. Using this example, connections to the pod are redirected to `192.168.12.91`, with a source IP address of `192.168.12.99`. - -<.> The `gateway` key specifies the IP address for the network gateway. - -// clear temporary attributes -:!router-type: -ifdef::redirect[] -:!redirect: -endif::[] diff --git a/modules/nw-egress-router-pod-ovn.adoc b/modules/nw-egress-router-pod-ovn.adoc deleted file mode 100644 index c0c248c81278..000000000000 --- a/modules/nw-egress-router-pod-ovn.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/deploying-egress-router-ovn-redirection.adoc - -ifeval::["{context}" == "deploying-egress-router-ovn-redirection"] -:redirect: -:router-type: redirect -// Like nw-egress-router-pod, monitor bz-1896170 -:egress-pod-image-name: registry.redhat.com/openshift3/ose-pod -endif::[] - -// Images are different for OKD -ifdef::openshift-origin[] - -ifdef::redirect[] -:egress-pod-image-name: quay.io/openshift/origin-pod -endif::[] - -endif::[] - -[id="nw-egress-router-cni-pod_{context}"] -= Egress router pod specification for {router-type} mode - -After you create a network attachment definition, you add a pod that references the definition. - -.Example egress router pod specification -[source,yaml,subs="attributes+"] ----- -apiVersion: v1 -kind: Pod -metadata: - name: egress-router-pod - annotations: - k8s.v1.cni.cncf.io/networks: egress-router-redirect <.> -spec: - containers: - - name: egress-router-pod - image: {egress-pod-image-name} ----- -<.> The specified network must match the name of the network attachment definition. You can specify a namespace, interface name, or both, by replacing the values in the following pattern: `<namespace>/<network>@<interface>`. By default, Multus adds a secondary network interface to the pod with a name such as `net1`, `net2`, and so on. - -// Clear temporary attributes -:!router-type: -:!egress-pod-image-name: -ifdef::redirect[] -:!redirect: -endif::[] diff --git a/modules/nw-egress-router-pod.adoc b/modules/nw-egress-router-pod.adoc deleted file mode 100644 index 05357a891cf4..000000000000 --- a/modules/nw-egress-router-pod.adoc +++ /dev/null @@ -1,233 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/deploying-egress-router-layer3-redirection.adoc -// * networking/openshift_sdn/deploying-egress-router-http-redirection.adoc -// * networking/openshift_sdn/deploying-egress-router-dns-redirection.adoc - -// Conditional per flavor of Pod -ifeval::["{context}" == "deploying-egress-router-layer3-redirection"] -:redirect: -:router-type: redirect -endif::[] -ifeval::["{context}" == "deploying-egress-router-http-redirection"] -:http: -:router-type: HTTP -endif::[] -ifeval::["{context}" == "deploying-egress-router-dns-redirection"] -:dns: -:router-type: DNS -endif::[] - -:egress-router-image-name: openshift4/ose-egress-router -:egress-router-image-url: registry.redhat.io/{egress-router-image-name} - -ifdef::http[] -:egress-http-proxy-image-name: openshift4/ose-egress-http-proxy -:egress-http-proxy-image-url: registry.redhat.io/{egress-http-proxy-image-name} -endif::[] -ifdef::dns[] -:egress-dns-proxy-image-name: openshift4/ose-egress-dns-proxy -:egress-dns-proxy-image-url: registry.redhat.io/{egress-dns-proxy-image-name} -endif::[] -ifdef::redirect[] -:egress-pod-image-name: openshift4/ose-pod -:egress-pod-image-url: registry.redhat.io/{egress-pod-image-name} -endif::[] - -// All the images are different for OKD -ifdef::openshift-origin[] - -:egress-router-image-name: openshift/origin-egress-router -:egress-router-image-url: {egress-router-image-name} - -ifdef::http[] -:egress-http-proxy-image-name: openshift/origin-egress-http-proxy -:egress-http-proxy-image-url: {egress-http-proxy-image-name} -endif::[] -ifdef::dns[] -:egress-dns-proxy-image-name: openshift/origin-egress-dns-proxy -:egress-dns-proxy-image-url: {egress-dns-proxy-image-name} -endif::[] -ifdef::redirect[] -:egress-pod-image-name: openshift/origin-pod -:egress-pod-image-url: {egress-pod-image-name} -endif::[] - -endif::openshift-origin[] - -[id="nw-egress-router-pod_{context}"] -= Egress router pod specification for {router-type} mode - -Define the configuration for an egress router pod in the `Pod` object. The following YAML describes the fields for the configuration of an egress router pod in {router-type} mode: - -// Because redirect needs privileged access to setup `EGRESS_DESTINATION` -// and the other modes do not, this ends up needing its own almost -// identical Pod. It's not possible to use conditionals for an unequal -// number of callouts. - -ifdef::redirect[] -[source,yaml,subs="attributes+"] ----- -apiVersion: v1 -kind: Pod -metadata: - name: egress-1 - labels: - name: egress-1 - annotations: - pod.network.openshift.io/assign-macvlan: "true" <1> -spec: - initContainers: - - name: egress-router - image: {egress-router-image-url} - securityContext: - privileged: true - env: - - name: EGRESS_SOURCE <2> - value: <egress_router> - - name: EGRESS_GATEWAY <3> - value: <egress_gateway> - - name: EGRESS_DESTINATION <4> - value: <egress_destination> - - name: EGRESS_ROUTER_MODE - value: init - containers: - - name: egress-router-wait - image: {egress-pod-image-url} ----- -<1> Before starting the `egress-router` container, create a macvlan network interface on the primary network interface and move that interface into the pod network namespace. You must include the quotation marks around the `"true"` value. To create the macvlan interface on a network interface other than the primary one, set the annotation value to the name of that interface. For example, `eth1`. -<2> IP address from the physical network that the node is on that is reserved for use by the egress router pod. Optional: You can include the subnet length, the `/24` suffix, so that a proper route to the local subnet is set. If you do not specify a subnet length, then the egress router can access only the host specified with the `EGRESS_GATEWAY` variable and no other hosts on the subnet. -<3> Same value as the default gateway used by the node. -<4> External server to direct traffic to. Using this example, connections to the pod are redirected to `203.0.113.25`, with a source IP address of `192.168.12.99`. - -.Example egress router Pod specification -[source,yaml,subs="attributes+"] ----- -apiVersion: v1 -kind: Pod -metadata: - name: egress-multi - labels: - name: egress-multi - annotations: - pod.network.openshift.io/assign-macvlan: "true" -spec: - initContainers: - - name: egress-router - image: {egress-router-image-url} - securityContext: - privileged: true - env: - - name: EGRESS_SOURCE - value: 192.168.12.99/24 - - name: EGRESS_GATEWAY - value: 192.168.12.1 - - name: EGRESS_DESTINATION - value: | - 80 tcp 203.0.113.25 - 8080 tcp 203.0.113.26 80 - 8443 tcp 203.0.113.26 443 - 203.0.113.27 - - name: EGRESS_ROUTER_MODE - value: init - containers: - - name: egress-router-wait - image: {egress-pod-image-url} ----- -endif::redirect[] - -// Many conditionals because DNS offers one additional env variable. - -ifdef::dns,http[] -[source,yaml,subs="attributes+"] ----- -apiVersion: v1 -kind: Pod -metadata: - name: egress-1 - labels: - name: egress-1 - annotations: - pod.network.openshift.io/assign-macvlan: "true" <1> -spec: - initContainers: - - name: egress-router - image: {egress-router-image-url} - securityContext: - privileged: true - env: - - name: EGRESS_SOURCE <2> - value: <egress-router> - - name: EGRESS_GATEWAY <3> - value: <egress-gateway> - - name: EGRESS_ROUTER_MODE -ifdef::dns[] - value: dns-proxy -endif::dns[] -ifdef::http[] - value: http-proxy -endif::http[] - containers: - - name: egress-router-pod -ifdef::dns[] - image: {egress-dns-proxy-image-url} - securityContext: - privileged: true -endif::dns[] -ifdef::http[] - image: {egress-http-proxy-image-url} -endif::http[] - env: -ifdef::http[] - - name: EGRESS_HTTP_PROXY_DESTINATION <4> - value: |- - ... -endif::http[] -ifdef::dns[] - - name: EGRESS_DNS_PROXY_DESTINATION <4> - value: |- - ... - - name: EGRESS_DNS_PROXY_DEBUG <5> - value: "1" -endif::dns[] - ... ----- -<1> Before starting the `egress-router` container, create a macvlan network interface on the primary network interface and move that interface into the pod network namespace. You must include the quotation marks around the `"true"` value. To create the macvlan interface on a network interface other than the primary one, set the annotation value to the name of that interface. For example, `eth1`. -<2> IP address from the physical network that the node is on that is reserved for use by the egress router pod. Optional: You can include the subnet length, the `/24` suffix, so that a proper route to the local subnet is set. If you do not specify a subnet length, then the egress router can access only the host specified with the `EGRESS_GATEWAY` variable and no other hosts on the subnet. -<3> Same value as the default gateway used by the node. -ifdef::http[] -<4> A string or YAML multi-line string specifying how to configure the proxy. Note that this is specified as an environment variable in the HTTP proxy container, not with the other environment variables in the init container. -endif::http[] -ifdef::dns[] -<4> Specify a list of one or more proxy destinations. -<5> Optional: Specify to output the DNS proxy log output to `stdout`. -endif::dns[] -endif::[] - -// unload flavors -ifdef::redirect[] -:!redirect: -endif::[] -ifdef::http[] -:!http: -endif::[] -ifdef::dns[] -:!dns: -endif::[] -ifdef::router-type[] -:!router-type: -endif::[] - -// unload images -ifdef::egress-router-image-name[] -:!egress-router-image-name: -endif::[] -ifdef::egress-router-image-url[] -:!egress-router-image-url: -endif::[] -ifdef::egress-pod-image-name[] -:!egress-pod-image-name: -endif::[] -ifdef::egress-pod-image-url[] -:!egress-pod-image-url: -endif::[] diff --git a/modules/nw-egress-router-redirect-mode-ovn.adoc b/modules/nw-egress-router-redirect-mode-ovn.adoc deleted file mode 100644 index d64731f60606..000000000000 --- a/modules/nw-egress-router-redirect-mode-ovn.adoc +++ /dev/null @@ -1,139 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/deploying-egress-router-ovn-redirection.adoc - -[id="nw-egress-router-redirect-mode-ovn_{context}"] -= Deploying an egress router pod in redirect mode - -You can deploy an egress router pod to redirect traffic from its own reserved source IP address to one or more destination IP addresses. - -After you add an egress router pod, the client pods that need to use the reserved source IP address must be modified to connect to the egress router rather than connecting directly to the destination IP. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create a network attachment definition. - -. Create an egress router pod. - -. To ensure that other pods can find the IP address of the egress router pod, create a service that uses the egress router pod, as in the following example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: egress-1 -spec: - ports: - - name: database - protocol: TCP - port: 3306 - type: ClusterIP - selector: - name: egress-router-pod ----- -+ -After you create the service, your pods can connect to the service. The egress router pod redirects the connection to the corresponding port on the destination IP address. The connections originate from the reserved source IP address. - -.Verification - -To verify that the egress router pod started and has the secondary network interface, complete the following procedure: - -. View the events for the egress router pod: -+ -[source,terminal] ----- -$ oc get events --field-selector involvedObject.name=egress-router-pod ----- -+ -If the pod references the network attachment definition, the previous command returns output that is similar to the following: -+ -.Example output -+ -[source,terminal] ----- -LAST SEEN TYPE REASON OBJECT MESSAGE -5m4s Normal Scheduled pod/egress-router-pod Successfully assigned default/egress-router-pod to ci-ln-9x2bnsk-f76d1-j2v6g-worker-c-24g65 -5m3s Normal AddedInterface pod/egress-router-pod Add eth0 [10.129.2.31/23] -5m3s Normal AddedInterface pod/egress-router-pod Add net1 [192.168.12.99/24] from default/egress-router-redirect ----- - -. Optional: View the routing table for the egress router pod. -// Terminology from support-collecting-network-trace.adoc -.. Get the node name for the egress router pod: -+ -[source,terminal] ----- -$ POD_NODENAME=$(oc get pod egress-router-pod -o jsonpath="{.spec.nodeName}") ----- - -.. Enter into a debug session on the target node. This step instantiates a debug pod called `<node_name>-debug`: -+ -[source,terminal] ----- -$ oc debug node/$POD_NODENAME ----- - -.. Set `/host` as the root directory within the debug shell. The debug pod mounts the root file system of the host in `/host` within the pod. By changing the root directory to `/host`, you can run binaries from the executable paths of the host: -+ -[source,terminal] ----- -# chroot /host ----- - -.. From within the `chroot` environment console, get the container ID: -+ -[source,terminal] ----- -# crictl ps --name egress-router-redirect | awk '{print $1}' ----- -+ -.Example output -[source,terminal] ----- -CONTAINER -bac9fae69ddb6 ----- - -.. Determine the process ID of the container. In this example, the container ID is `bac9fae69ddb6`: -+ -[source,terminal] ----- -# crictl inspect -o yaml bac9fae69ddb6 | grep 'pid:' | awk '{print $2}' ----- -+ -.Example output -[source,terminal] ----- -68857 ----- - -.. Enter the network namespace of the container: -+ -[source,terminal] ----- -# nsenter -n -t 68857 ----- - -.. Display the routing table: -+ -[source,terminal] ----- -# ip route ----- -+ -In the following example output, the `net1` network interface is the default route. Traffic for the cluster network uses the `eth0` network interface. Traffic for the `192.168.12.0/24` network uses the `net1` network interface and originates from the reserved source IP address `192.168.12.99`. The pod routes all other traffic to the gateway at IP address `192.168.12.1`. Routing for the service network is not shown. -+ -.Example output -[source,terminal] ----- -default via 192.168.12.1 dev net1 -10.129.2.0/23 dev eth0 proto kernel scope link src 10.129.2.31 -192.168.12.0/24 dev net1 proto kernel scope link src 192.168.12.99 -192.168.12.1 dev net1 ----- diff --git a/modules/nw-egress-router-redirect-mode.adoc b/modules/nw-egress-router-redirect-mode.adoc deleted file mode 100644 index a662740c5010..000000000000 --- a/modules/nw-egress-router-redirect-mode.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/deploying-egress-router-layer3-redirection.adoc - -[id="nw-egress-router-redirect-mode_{context}"] -= Deploying an egress router pod in redirect mode - -In _redirect mode_, an egress router pod sets up iptables rules to redirect traffic from its own IP address to one or more destination IP addresses. Client pods that need to use the reserved source IP address must be modified to connect to the egress router rather than connecting directly to the destination IP. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create an egress router pod. - -. To ensure that other pods can find the IP address of the egress router pod, create a service to point to the egress router pod, as in the following example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: egress-1 -spec: - ports: - - name: http - port: 80 - - name: https - port: 443 - type: ClusterIP - selector: - name: egress-1 ----- -+ -Your pods can now connect to this service. Their connections are redirected to -the corresponding ports on the external server, using the reserved egress IP -address. diff --git a/modules/nw-egressnetworkpolicy-about.adoc b/modules/nw-egressnetworkpolicy-about.adoc deleted file mode 100644 index 69a34c9b1003..000000000000 --- a/modules/nw-egressnetworkpolicy-about.adoc +++ /dev/null @@ -1,111 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/configuring-egress-firewall.adoc -// * networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc - -ifeval::["{context}" == "configuring-egress-firewall-ovn"] -:ovn: -:kind: EgressFirewall -endif::[] -ifeval::["{context}" == "openshift-sdn-egress-firewall"] -:openshift-sdn: -:kind: EgressNetworkPolicy -endif::[] - -[id="nw-egressnetworkpolicy-about_{context}"] -= How an egress firewall works in a project - -As a cluster administrator, you can use an _egress firewall_ to -limit the external hosts that some or all pods can access from within the -cluster. An egress firewall supports the following scenarios: - -- A pod can only connect to internal hosts and cannot initiate connections to -the public Internet. -- A pod can only connect to the public Internet and cannot initiate connections -to internal hosts that are outside the {product-title} cluster. -- A pod cannot reach specified internal subnets or hosts outside the {product-title} cluster. -- A pod can connect to only specific external hosts. - -For example, you can allow one project access to a specified IP range but deny the same access to a different project. Or you can restrict application developers from updating from Python pip mirrors, and force updates to come only from approved sources. - -You configure an egress firewall policy by creating an {kind} custom resource (CR) object. The egress firewall matches network traffic that meets any of the following criteria: - -- An IP address range in CIDR format -- A DNS name that resolves to an IP address -ifdef::ovn[] -- A port number -- A protocol that is one of the following protocols: TCP, UDP, and SCTP -endif::ovn[] - -ifdef::openshift-sdn[] -[IMPORTANT] -==== -You must have OpenShift SDN configured to use either the network policy or multitenant mode to configure an egress firewall. - -If you use network policy mode, an egress firewall is compatible with only one policy per namespace and will not work with projects that share a network, such as global projects. -==== -endif::openshift-sdn[] - -[WARNING] -==== -Egress firewall rules do not apply to traffic that goes through routers. Any user with permission to create a Route CR object can bypass egress firewall policy rules by creating a route that points to a forbidden destination. -==== - -[id="limitations-of-an-egress-firewall_{context}"] -== Limitations of an egress firewall - -An egress firewall has the following limitations: - -* No project can have more than one {kind} object. - -ifdef::openshift-sdn[] -* A maximum of one {kind} object with a maximum of 1,000 rules can be defined per project. - -* The `default` project cannot use an egress firewall. - -* When using the OpenShift SDN default Container Network Interface (CNI) network provider in multitenant mode, the following limitations apply: - - - Global projects cannot use an egress firewall. You can make a project global by using the `oc adm pod-network make-projects-global` command. - - - Projects merged by using the `oc adm pod-network join-projects` command cannot use an egress firewall in any of the joined projects. -endif::openshift-sdn[] - -Violating any of these restrictions results in a broken egress firewall for the project, and might cause all external network traffic to be dropped. - -[id="policy-rule-order_{context}"] -== Matching order for egress firewall policy rules - -The egress firewall policy rules are evaluated in the order that they are defined, from first to last. The first rule that matches an egress connection from a pod applies. Any subsequent rules are ignored for that connection. - -[id="domain-name-server-resolution_{context}"] -== How Domain Name Server (DNS) resolution works - -If you use DNS names in any of your egress firewall policy rules, proper resolution of the domain names is subject to the following restrictions: - -ifdef::openshift-sdn[] -* Domain name updates are polled based on a time-to-live (TTL) duration. By default, the duration is 30 seconds. When the egress firewall controller queries the local name servers for a domain name, if the response includes a TTL that is less than 30 seconds, the controller sets the duration to the returned value. If the TTL in the response is greater than 30 minutes, the controller sets the duration to 30 minutes. If the TTL is between 30 seconds and 30 minutes, the controller ignores the value and sets the duration to 30 seconds. -endif::openshift-sdn[] -ifdef::ovn[] -* Domain name updates are polled based on a time-to-live (TTL) duration. By default, the duration is 30 minutes. When the egress firewall controller queries the local name servers for a domain name, if the response includes a TTL and the TTL is less than 30 minutes, the controller sets the duration for that DNS name to the returned value. Each DNS name is queried after the TTL for the DNS record expires. -endif::ovn[] - -* The pod must resolve the domain from the same local name servers when necessary. Otherwise the IP addresses for the domain known by the egress firewall controller and the pod can be different. If the IP addresses for a host name differ, the egress firewall might not be enforced consistently. - -* Because the egress firewall controller and pods asynchronously poll the same local name server, the pod might obtain the updated IP address before the egress controller does, which causes a race condition. Due to this current limitation, domain name usage in {kind} objects is only recommended for domains with infrequent IP address changes. - -[NOTE] -==== -The egress firewall always allows pods access to the external interface of the node that the pod is on for DNS resolution. - -If you use domain names in your egress firewall policy and your DNS resolution is not handled by a DNS server on the local node, then you must add egress firewall rules that allow access to your DNS server’s IP addresses. if you are using domain names in your pods. -==== - -ifdef::ovn[] -:!ovn: -endif::[] -ifdef::openshift-sdn[] -:!openshift-sdn: -endif::[] -ifdef::kind[] -:!kind: -endif::[] diff --git a/modules/nw-egressnetworkpolicy-create.adoc b/modules/nw-egressnetworkpolicy-create.adoc deleted file mode 100644 index 9d787fae9cb8..000000000000 --- a/modules/nw-egressnetworkpolicy-create.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/configuring-egress-firewall.adoc -// * networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc - -ifeval::["{context}" == "openshift-sdn-egress-firewall"] -:kind: EgressNetworkPolicy -:obj: egressnetworkpolicy.network.openshift.io/v1 -:cni: OpenShift SDN -endif::[] -ifeval::["{context}" == "configuring-egress-firewall-ovn"] -:kind: EgressFirewall -:obj: egressfirewall.k8s.ovn.org/v1 -:cni: OVN-Kubernetes -endif::[] - -[id="nw-networkpolicy-create_{context}"] -= Creating an egress firewall policy object - -As a cluster administrator, you can create an egress firewall policy object for a project. - -[IMPORTANT] -==== -If the project already has an {kind} object defined, you must edit the existing policy to make changes to the egress firewall rules. -==== - -.Prerequisites - -* A cluster that uses the {cni} default Container Network Interface (CNI) network provider plug-in. -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster as a cluster administrator. - -.Procedure - -. Create a policy rule: -.. Create a `<policy_name>.yaml` file where `<policy_name>` describes the egress -policy rules. -.. In the file you created, define an egress policy object. - -. Enter the following command to create the policy object. Replace `<policy_name>` with the name of the policy and `<project>` with the project that the rule applies to. -+ -[source,terminal] ----- -$ oc create -f <policy_name>.yaml -n <project> ----- -+ -In the following example, a new {kind} object is created in a project named `project1`: -+ -[source,terminal] ----- -$ oc create -f default.yaml -n project1 ----- -+ -.Example output -[source,terminal,subs="attributes"] ----- -{obj} created ----- - -. Optional: Save the `<policy_name>.yaml` file so that you can make changes later. - -ifdef::kind[] -:!kind: -endif::[] -ifdef::obj[] -:!obj: -endif::[] -ifdef::cni[] -:!cni: -endif::[] diff --git a/modules/nw-egressnetworkpolicy-delete.adoc b/modules/nw-egressnetworkpolicy-delete.adoc deleted file mode 100644 index 817efa5599b3..000000000000 --- a/modules/nw-egressnetworkpolicy-delete.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift-sdn/removing-egress-firewall.adoc -// * networking/ovn_kubernetes_network_provider/removing-egress-firewall-ovn.adoc - -ifeval::["{context}" == "openshift-sdn-egress-firewall"] -:kind: EgressNetworkPolicy -:res: egressnetworkpolicy -:cni: OpenShift SDN -endif::[] -ifeval::["{context}" == "removing-egress-firewall-ovn"] -:kind: EgressFirewall -:res: egressfirewall -:cni: OVN-Kubernetes -endif::[] - -[id="nw-egressnetworkpolicy-delete_{context}"] -= Removing an {kind} object - -As a cluster administrator, you can remove an egress firewall from a project. - -.Prerequisites - -* A cluster using the {cni} default Container Network Interface (CNI) network provider plug-in. -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster as a cluster administrator. - -.Procedure - -. Find the name of the {kind} object for the project. Replace `<project>` with the name of the project. -+ -[source,terminal,subs="attributes+"] ----- -$ oc get -n <project> {res} ----- - -. Enter the following command to delete the {kind} object. Replace `<project>` with the name of the project and `<name>` with the name of the object. -+ -[source,terminal,subs="attributes+"] ----- -$ oc delete -n <project> {res} <name> ----- - -ifdef::kind[] -:!kind: -endif::[] -ifdef::res[] -:!res: -endif::[] -ifdef::cni[] -:!cni: -endif::[] diff --git a/modules/nw-egressnetworkpolicy-edit.adoc b/modules/nw-egressnetworkpolicy-edit.adoc deleted file mode 100644 index c3ed797f131a..000000000000 --- a/modules/nw-egressnetworkpolicy-edit.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/editing-egress-firewall.adoc -// * networking/ovn_kubernetes_network_provider/editing-egress-firewall-ovn.adoc - -ifeval::["{context}" == "openshift-sdn-egress-firewall"] -:kind: EgressNetworkPolicy -:res: egressnetworkpolicy -:cni: OpenShift SDN -endif::[] -ifeval::["{context}" == "editing-egress-firewall-ovn"] -:kind: EgressFirewall -:res: egressfirewall -:cni: OVN-Kubernetes -endif::[] - -[id="nw-egressnetworkpolicy-edit_{context}"] -= Editing an {kind} object - -As a cluster administrator, you can update the egress firewall for a project. - -.Prerequisites - -* A cluster using the {cni} default Container Network Interface (CNI) network provider plug-in. -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster as a cluster administrator. - -.Procedure - -. Find the name of the {kind} object for the project. Replace `<project>` with the name of the project. -+ -[source,terminal,subs="attributes+"] ----- -$ oc get -n <project> {res} ----- - -. Optional: If you did not save a copy of the {kind} object when you created the egress network firewall, enter the following command to create a copy. -+ -[source,terminal,subs="attributes+"] ----- -$ oc get -n <project> {res} <name> -o yaml > <filename>.yaml ----- -+ -Replace `<project>` with the name of the project. Replace `<name>` with the name of the object. Replace `<filename>` with the name of the file to save the YAML to. - -. After making changes to the policy rules, enter the following command to replace the {kind} object. Replace `<filename>` with the name of the file containing the updated {kind} object. -+ -[source,terminal] ----- -$ oc replace -f <filename>.yaml ----- - -ifdef::kind[] -:!kind: -endif::[] -ifdef::res[] -:!res: -endif::[] -ifdef::cni[] -:!cni: -endif::[] diff --git a/modules/nw-egressnetworkpolicy-object.adoc b/modules/nw-egressnetworkpolicy-object.adoc deleted file mode 100644 index 707dd130435c..000000000000 --- a/modules/nw-egressnetworkpolicy-object.adoc +++ /dev/null @@ -1,167 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/configuring-egress-firewall.adoc -// * networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc - -ifeval::["{context}" == "openshift-sdn-egress-firewall"] -:kind: EgressNetworkPolicy -:api: network.openshift.io/v1 -:openshift-sdn: -endif::[] -ifeval::["{context}" == "configuring-egress-firewall-ovn"] -:kind: EgressFirewall -:api: k8s.ovn.org/v1 -:ovn: -endif::[] - -[id="nw-egressnetworkpolicy-object_{context}"] -= {kind} custom resource (CR) object - -You can define one or more rules for an egress firewall. A rule is either an `Allow` rule or a `Deny` rule, with a specification for the traffic that the rule applies to. - -The following YAML describes an {kind} CR object: - -.{kind} object -[source,yaml,subs="attributes+"] ----- -apiVersion: {api} -kind: {kind} -metadata: -ifdef::openshift-sdn[] - name: <name> <1> -endif::openshift-sdn[] -ifdef::ovn[] - name: <name> <1> -endif::ovn[] -spec: - egress: <2> - ... ----- -ifdef::openshift-sdn[] -<1> A name for your egress firewall policy. -endif::openshift-sdn[] -ifdef::ovn[] -<1> The name for the object must be `default`. -endif::ovn[] - -<2> A collection of one or more egress network policy rules as described in the following section. - -[id="egressnetworkpolicy-rules_{context}"] -== {kind} rules - -The following YAML describes an egress firewall rule object. The `egress` stanza expects an array of one or more objects. - -// - OVN-Kubernetes does not support DNS -// - OpenShift SDN does not support port and protocol specification - -.Egress policy rule stanza -ifdef::openshift-sdn[] -[source,yaml] ----- -egress: -- type: <type> <1> - to: <2> - cidrSelector: <cidr> <3> - dnsName: <dns_name> <4> ----- -<1> The type of rule. The value must be either `Allow` or `Deny`. - -<2> A stanza describing an egress traffic match rule. A value for either the `cidrSelector` field or the `dnsName` field for the rule. You cannot use both fields in the same rule. - -<3> An IP address range in CIDR format. - -<4> A domain name. -endif::openshift-sdn[] -ifdef::ovn[] -[source,yaml] ----- -egress: -- type: <type> <1> - to: <2> - cidrSelector: <cidr> <3> - dnsName: <dns_name> <4> - ports: <5> - ... ----- -<1> The type of rule. The value must be either `Allow` or `Deny`. - -<2> A stanza describing an egress traffic match rule that specifies the `cidrSelector` field or the `dnsName` field. You cannot use both fields in the same rule. - -<3> An IP address range in CIDR format. - -<4> A DNS domain name. - -<5> Optional: A stanza describing a collection of network ports and protocols for the rule. - -.Ports stanza -[source,yaml] ----- -ports: -- port: <port> <1> - protocol: <protocol> <2> ----- -<1> A network port, such as `80` or `443`. If you specify a value for this field, you must also specify a value for `protocol`. - -<2> A network protocol. The value must be either `TCP`, `UDP`, or `SCTP`. -endif::ovn[] - -[id="egressnetworkpolicy-example_{context}"] -== Example {kind} CR objects - -The following example defines several egress firewall policy rules: - -[source,yaml,subs="attributes+"] ----- -apiVersion: {api} -kind: {kind} -metadata: - name: default -spec: - egress: <1> - - type: Allow - to: - cidrSelector: 1.2.3.0/24 -ifdef::openshift-sdn[] - - type: Allow - to: - dnsName: www.example.com -endif::openshift-sdn[] - - type: Deny - to: - cidrSelector: 0.0.0.0/0 ----- -<1> A collection of egress firewall policy rule objects. - -ifdef::ovn[] -The following example defines a policy rule that denies traffic to the host at the `172.16.1.1` IP address, if the traffic is using either the TCP protocol and destination port `80` or any protocol and destination port `443`. - -[source,yaml,subs="attributes+"] ----- -apiVersion: {api} -kind: {kind} -metadata: - name: default -spec: - egress: - - type: Deny - to: - cidrSelector: 172.16.1.1 - ports: - - port: 80 - protocol: TCP - - port: 443 ----- -endif::ovn[] - -ifdef::kind[] -:!kind: -endif::[] -ifdef::api[] -:!api: -endif::[] -ifdef::ovn[] -:!ovn: -endif::[] -ifdef::openshift-sdn[] -:!openshift-sdn: -endif::[] diff --git a/modules/nw-egressnetworkpolicy-view.adoc b/modules/nw-egressnetworkpolicy-view.adoc deleted file mode 100644 index afe86149e951..000000000000 --- a/modules/nw-egressnetworkpolicy-view.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/configuring-egress-firewall.adoc -// * networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc - -ifeval::["{context}" == "openshift-sdn-viewing-egress-firewall"] -:kind: EgressNetworkPolicy -:res: egressnetworkpolicy -:cni: OpenShift SDN -endif::[] -ifeval::["{context}" == "viewing-egress-firewall-ovn"] -:kind: EgressFirewall -:res: egressfirewall -:cni: OVN-Kubernetes -endif::[] - -[id="nw-egressnetworkpolicy-view_{context}"] -= Viewing an {kind} object - -You can view an {kind} object in your cluster. - -.Prerequisites - -* A cluster using the {cni} default Container Network Interface (CNI) network provider plug-in. -* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`. -* You must log in to the cluster. - -.Procedure - -. Optional: To view the names of the {kind} objects defined in your cluster, -enter the following command: -+ -[source,terminal,subs="attributes"] ----- -$ oc get {res} --all-namespaces ----- - -. To inspect a policy, enter the following command. Replace `<policy_name>` with the name of the policy to inspect. -+ -[source,terminal,subs="attributes+"] ----- -$ oc describe {res} <policy_name> ----- -+ -[source,terminal] -.Example output ----- -Name: default -Namespace: project1 -Created: 20 minutes ago -Labels: <none> -Annotations: <none> -Rule: Allow to 1.2.3.0/24 -Rule: Allow to www.example.com -Rule: Deny to 0.0.0.0/0 ----- - -ifdef::kind[] -:!kind: -endif::[] -ifdef::res[] -:!res: -endif::[] -ifdef::cni[] -:!cni: -endif::[] diff --git a/modules/nw-enabling-hsts.adoc b/modules/nw-enabling-hsts.adoc deleted file mode 100644 index eb9ce5943e4a..000000000000 --- a/modules/nw-enabling-hsts.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module filename: nw-enabling-hsts.adoc -// Module included in the following assemblies: -// * networking/configuring-routing.adoc - -[id="nw-enabling-hsts_{context}"] -= Enabling HTTP strict transport security - -HTTP Strict Transport Security (HSTS) policy is a security enhancement, which -ensures that only HTTPS traffic is allowed on the host. Any HTTP requests are -dropped by default. This is useful for ensuring secure interactions with -websites, or to offer a secure application for the user's benefit. - -When HSTS is enabled, HSTS adds a Strict Transport Security header to HTTPS -responses from the site. You can use the `insecureEdgeTerminationPolicy` value -in a route to redirect to send HTTP to HTTPS. However, when HSTS is enabled, the -client changes all requests from the HTTP URL to HTTPS before the request is -sent, eliminating the need for a redirect. This is not required to be supported -by the client, and can be disabled by setting `max-age=0`. - -[IMPORTANT] -==== -HSTS works only with secure routes (either edge terminated or re-encrypt). The -configuration is ineffective on HTTP or passthrough routes. -==== - -.Procedure -* To enable HSTS on a route, add the `haproxy.router.openshift.io/hsts_header` -value to the edge terminated or re-encrypt route: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Route -metadata: - annotations: - haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload <1> <2> <3> ----- -+ -<1> `max-age` is the only required parameter. -It measures the length of time, in seconds, that the -HSTS policy is in effect. The client updates `max-age` whenever a response -with a HSTS header is received from the host. When `max-age` times out, the -client discards the policy. -+ -<2> `includeSubDomains` is optional. When included, it tells the client -that all subdomains -of the host are to be treated the same as the host. -+ -<3> `preload` is optional. When `max-age` is greater than 0, then including -`preload` in `haproxy.router.openshift.io/hsts_header` allows external -services to include this site in their HSTS preload lists. For example, sites -such as Google can construct a list of sites that have `preload` set. Browsers -can then use these lists to determine which sites they can communicate with -over HTTPS, -before they have interacted with the site. Without `preload` set, browsers must -have interacted with the site over HTTPS to get the header. diff --git a/modules/nw-enabling-multicast.adoc b/modules/nw-enabling-multicast.adoc deleted file mode 100644 index 3affe2d16475..000000000000 --- a/modules/nw-enabling-multicast.adoc +++ /dev/null @@ -1,140 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/enabling-multicast.adoc -// * networking/ovn_kubernetes_network_provider/enabling-multicast.adoc - -ifeval::["{context}" == "openshift-sdn-enabling-multicast"] -:namespace: netnamespace -:annotation: netnamespace.network.openshift.io/multicast-enabled=true -endif::[] -ifeval::["{context}" == "ovn-kubernetes-enabling-multicast"] -:namespace: namespace -:annotation: k8s.ovn.org/multicast-enabled=true -endif::[] - -[id="nw-enabling-multicast_{context}"] -= Enabling multicast between pods - -You can enable multicast between pods for your project. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster with a user that has the `cluster-admin` role. - -.Procedure - -* Run the following command to enable multicast for a project. Replace `<namespace>` with the namespace for the project you want to enable multicast for. -+ -[source,terminal,subs="attributes+"] ----- -$ oc annotate {namespace} <namespace> \ - {annotation} ----- - -.Verification - -To verify that multicast is enabled for a project, complete the following procedure: - -. Change your current project to the project that you enabled multicast for. Replace `<project>` with the project name. -+ -[source,terminal] ----- -$ oc project <project> ----- - -. Create a pod to act as a multicast receiver: -+ -[source,terminal] ----- -$ cat <<EOF| oc create -f - -apiVersion: v1 -kind: Pod -metadata: - name: mlistener - labels: - app: multicast-verify -spec: - containers: - - name: mlistener - image: registry.access.redhat.com/ubi8 - command: ["/bin/sh", "-c"] - args: - ["dnf -y install socat hostname && sleep inf"] - ports: - - containerPort: 30102 - name: mlistener - protocol: UDP -EOF ----- - -. Create a pod to act as a multicast sender: -+ -[source,terminal] ----- -$ cat <<EOF| oc create -f - -apiVersion: v1 -kind: Pod -metadata: - name: msender - labels: - app: multicast-verify -spec: - containers: - - name: msender - image: registry.access.redhat.com/ubi8 - command: ["/bin/sh", "-c"] - args: - ["dnf -y install socat && sleep inf"] -EOF ----- - -. Start the multicast listener. - -.. Get the IP address for the Pod: -+ -[source,terminal] ----- -$ POD_IP=$(oc get pods mlistener -o jsonpath='{.status.podIP}') ----- - -.. To start the multicast listener, in a new terminal window or tab, enter the following command: -+ -[source,terminal] ----- -$ oc exec mlistener -i -t -- \ - socat UDP4-RECVFROM:30102,ip-add-membership=224.1.0.1:$POD_IP,fork EXEC:hostname ----- - -. Start the multicast transmitter. - -.. Get the pod network IP address range: -+ -[source,terminal] ----- -$ CIDR=$(oc get Network.config.openshift.io cluster \ - -o jsonpath='{.status.clusterNetwork[0].cidr}') ----- - -.. To send a multicast message, enter the following command: -+ -[source,terminal] ----- -$ oc exec msender -i -t -- \ - /bin/bash -c "echo | socat STDIO UDP4-DATAGRAM:224.1.0.1:30102,range=$CIDR,ip-multicast-ttl=64" ----- -+ -If multicast is working, the previous command returns the following output: -+ ----- -mlistener ----- - -ifeval::["{context}" == "openshift-sdn-enabling-multicast"] -:!annotation: -:!namespace: -endif::[] -ifeval::["{context}" == "ovn-kubernetes-enabling-multicast"] -:!annotation: -:!namespace: -endif::[] diff --git a/modules/nw-endpoint-route53.adoc b/modules/nw-endpoint-route53.adoc deleted file mode 100644 index c7d6156acf25..000000000000 --- a/modules/nw-endpoint-route53.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-government-region.adoc - -[id="nw-endpoint-route53_{context}"] -= Ingress Operator endpoint configuration for AWS Route 53 - -If you install in either Amazon Web Services (AWS) GovCloud (US) US-West or US-East region, the Ingress Operator uses `us-gov-west-1` region for Route53 and tagging API clients. - -The Ingress Operator uses `https://tagging.us-gov-west-1.amazonaws.com` as the tagging API endpoint if a tagging custom endpoint is configured that includes the string 'us-gov-east-1'. - -For more information on AWS GovCloud (US) endpoints, see the link:https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/using-govcloud-endpoints.html[Service Endpoints] in the AWS documentation about GovCloud (US). - -[IMPORTANT] -==== -Private, disconnected installations are not supported for AWS GovCloud when you install in the `us-gov-east-1` region. -==== - -.Example Route 53 configuration -[source,yaml] ----- -platform: - aws: - region: us-gov-west-1 - serviceEndpoints: - - name: ec2 - url: https://ec2.us-gov-west-1.amazonaws.com - - name: elasticloadbalancing - url: https://elasticloadbalancing.us-gov-west-1.amazonaws.com - - name: route53 - url: https://route53.us-gov.amazonaws.com <1> - - name: tagging - url: https://tagging.us-gov-west-1.amazonaws.com <2> ----- -<1> Route 53 defaults to `https://route53.us-gov.amazonaws.com` for both AWS GovCloud (US) regions. -<2> Only the US-West region has endpoints for tagging. Omit this parameter if your cluster is in another region. diff --git a/modules/nw-exposing-service.adoc b/modules/nw-exposing-service.adoc deleted file mode 100644 index ad0d255440cf..000000000000 --- a/modules/nw-exposing-service.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc - -ifeval::["{context}" == "configuring-ingress-cluster-traffic-nodeport"] -:nodeport: -endif::[] - -[id="nw-exposing-service_{context}"] -= Exposing the service by creating a route - -You can expose the service as a route by using the `oc expose` command. - -.Procedure - -To expose the service: - -. Log in to {product-title}. - -. Log in to the project where the service you want to expose is located: -+ -[source,terminal] ----- -$ oc project project1 ----- - -ifndef::nodeport[] -. Run the following command to expose the route: -+ -[source,terminal] ----- -$ oc expose service <service_name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc expose service mysql-80-rhel7 ----- -+ -.Example output -[source,terminal] ----- -route "mysql-80-rhel7" exposed ----- - -. Use a tool, such as cURL, to make sure you can reach the service using the -cluster IP address for the service: -+ -[source,terminal] ----- -$ curl <pod_ip>:<port> ----- -+ -For example: -+ -[source,terminal] ----- -$ curl 172.30.131.89:3306 ----- -+ -The examples in this section use a MySQL service, which requires a client -application. If you get a string of characters with the `Got packets out of order` -message, you are connected to the service. -+ -If you have a MySQL client, log in with the standard CLI command: -+ -[source,terminal] ----- -$ mysql -h 172.30.131.89 -u admin -p ----- -+ -.Example output -[source,terminal] ----- -Enter password: -Welcome to the MariaDB monitor. Commands end with ; or \g. - -MySQL [(none)]> ----- -endif::nodeport[] -ifdef::nodeport[] -. To expose a node port for the application, enter the following command. {product-title} automatically selects an available port in the `30000-32767` range. -+ -[source,terminal] ----- -$ oc expose dc mysql-80-rhel7 --type=NodePort --name=mysql-ingress ----- - -. Optional: To confirm the service is available with a node port exposed, enter the following command: -+ -[source,terminal] ----- -$ oc get svc -n myproject ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -mysql-80-rhel7 ClusterIP 172.30.217.127 <none> 3306/TCP 9m44s -mysql-ingress NodePort 172.30.107.72 <none> 3306:31345/TCP 39s ----- - -. Optional: To remove the service created automatically by the `oc new-app` command, enter the following command: -+ -[source,terminal] ----- -$ oc delete svc mysql-80-rhel7 ----- -endif::nodeport[] - -//Potentially add verification step, "If a verification step is needed, it would -//look something like oc get route mysql-55-rhel7 and curl with the host from the -//output of the oc get route command." - -ifdef::nodeport[] -:!nodeport: -endif::[] diff --git a/modules/nw-externalip-about.adoc b/modules/nw-externalip-about.adoc deleted file mode 100644 index c564249d95eb..000000000000 --- a/modules/nw-externalip-about.adoc +++ /dev/null @@ -1,179 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc - -[id="nw-externalip-about_{context}"] -= About ExternalIP - -For non-cloud environments, {product-title} supports the assignment of external IP addresses to a `Service` object `spec.externalIPs[]` field through the *ExternalIP* facility. -By setting this field, {product-title} assigns an additional virtual IP address to the service. The IP address can be outside the service network defined for the cluster. -A service configured with an ExternalIP functions similarly to a service with `type=NodePort`, allowing you to direct traffic to a local node for load balancing. - -You must configure your networking infrastructure to ensure that the external IP address blocks that you define are routed to the cluster. - -{product-title} extends the ExternalIP functionality in Kubernetes by adding the following capabilities: - -- Restrictions on the use of external IP addresses by users through a configurable policy -- Allocation of an external IP address automatically to a service upon request - -[WARNING] -==== -Disabled by default, use of ExternalIP functionality can be a security risk, because in-cluster traffic to an external IP address is directed to that service. -This could allow cluster users to intercept sensitive traffic destined for external resources. -==== - -[IMPORTANT] -==== -This feature is supported only in non-cloud deployments. -For cloud deployments, use the load balancer services for automatic deployment of a cloud load balancer to target the endpoints of a service. -==== - -You can assign an external IP address in the following ways: - -Automatic assignment of an external IP:: -{product-title} automatically assigns an IP address from the `autoAssignCIDRs` CIDR block to the `spec.externalIPs[]` array when you create a `Service` object with `spec.type=LoadBalancer` set. -In this case, {product-title} implements a non-cloud version of the load balancer service type and assigns IP addresses to the services. -Automatic assignment is disabled by default and must be configured by a cluster administrator as described in the following section. - -Manual assignment of an external IP:: -{product-title} uses the IP addresses assigned to the `spec.externalIPs[]` array when you create a `Service` object. You cannot specify an IP address that is already in use by another service. - -[id="configuration-externalip_{context}"] -== Configuration for ExternalIP - -Use of an external IP address in {product-title} is governed by the following fields in the `Network.config.openshift.io` CR named `cluster`: - -* `spec.externalIP.autoAssignCIDRs` defines an IP address block used by the load balancer when choosing an external IP address for the service. {product-title} supports only a single IP address block for automatic assignment. This can be simpler than having to manage the port space of a limited number of shared IP addresses when manually assigning ExternalIPs to services. If automatic assignment is enabled, a `Service` object with `spec.type=LoadBalancer` is allocated an external IP address. -* `spec.externalIP.policy` defines the permissible IP address blocks when manually specifying an IP address. {product-title} does not apply policy rules to IP address blocks defined by `spec.externalIP.autoAssignCIDRs`. - -If routed correctly, external traffic from the configured external IP address block can reach service endpoints through any TCP or UDP port that the service exposes. - -[IMPORTANT] -==== -You must ensure that the IP address block you assign terminates at one or more nodes in your cluster. -==== - -{product-title} supports both the automatic and manual assignment of IP -addresses, and each address is guaranteed to be assigned to a maximum of one -service. This ensures that each service can expose its chosen ports regardless -of the ports exposed by other services. - -[NOTE] -==== -To use IP address blocks defined by `autoAssignCIDRs` in {product-title}, you must configure the necessary IP address assignment and routing for your host network. -==== - -The following YAML describes a service with an external IP address configured: - -.Example `Service` object with `spec.externalIPs[]` set -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: http-service -spec: - clusterIP: 172.30.163.110 - externalIPs: - - 192.168.132.253 - externalTrafficPolicy: Cluster - ports: - - name: highport - nodePort: 31903 - port: 30102 - protocol: TCP - targetPort: 30102 - selector: - app: web - sessionAffinity: None - type: LoadBalancer -status: - loadBalancer: - ingress: - - ip: 192.168.132.253 ----- - -[id="restrictions-on-ip-assignment_{context}"] -== Restrictions on the assignment of an external IP address - -As a cluster administrator, you can specify IP address blocks to allow and to reject. - -Restrictions apply only to users without `cluster-admin` privileges. A cluster administrator can always set the service `spec.externalIPs[]` field to any IP address. - -You configure IP address policy with a `policy` object defined by specifying the `spec.ExternalIP.policy` field. -The policy object has the following shape: - -[source,json] ----- -{ - "policy": { - "allowedCIDRs": [], - "rejectedCIDRs": [] - } -} ----- - -When configuring policy restrictions, the following rules apply: - -- If `policy={}` is set, then creating a `Service` object with `spec.ExternalIPs[]` set will fail. This is the default for {product-title}. -- If `policy=null` is set, then creating a `Service` object with `spec.ExternalIPs[]` set to any IP address is allowed. -- If `policy` is set and either `policy.allowedCIDRs[]` or `policy.rejectedCIDRs[]` is set, the following rules apply: - -* If `allowedCIDRs[]` and `rejectedCIDRs[]` are both set, then `rejectedCIDRs[]` has precedence over `allowedCIDRs[]`. -* If `allowedCIDRs[]` is set, creating a `Service` object with `spec.ExternalIPs[]` will succeed only if the specified IP addresses are allowed. -* If `rejectedCIDRs[]` is set, creating a `Service` object with `spec.ExternalIPs[]` will succeed only if the specified IP addresses are not rejected. - -[id="example-policy-objects_{context}"] -== Example policy objects - -The examples that follow demonstrate several different policy configurations. - -- In the following example, the policy prevents {product-title} from creating any service with an external IP address specified: -+ -.Example policy to reject any value specified for `Service` object `spec.externalIPs[]` -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - externalIP: - policy: {} - ... ----- - -- In the following example, both the `allowedCIDRs` and `rejectedCIDRs` fields are set. -+ -.Example policy that includes both allowed and rejected CIDR blocks -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - externalIP: - policy: - allowedCIDRs: - - 172.16.66.10/23 - rejectedCIDRs: - - 172.16.66.10/24 - ... ----- - -- In the following example, `policy` is set to `null`. -If set to `null`, when inspecting the configuration object by entering `oc get networks.config.openshift.io -o yaml`, the `policy` field will not appear in the output. -+ -.Example policy to allow any value specified for `Service` object `spec.externalIPs[]` -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - externalIP: - policy: null - ... ----- diff --git a/modules/nw-externalip-configuring.adoc b/modules/nw-externalip-configuring.adoc deleted file mode 100644 index a3b502f19d35..000000000000 --- a/modules/nw-externalip-configuring.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc - -[id="nw-externalip-configuring_{context}"] -= Configure external IP address blocks for your cluster - -As a cluster administrator, you can configure the following ExternalIP settings: - -- An ExternalIP address block used by {product-title} to automatically populate the `spec.clusterIP` field for a `Service` object. -- A policy object to restrict what IP addresses may be manually assigned to the `spec.clusterIP` array of a `Service` object. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Optional: To display the current external IP configuration, enter the following command: -+ -[source,terminal] ----- -$ oc describe networks.config cluster ----- - -. To edit the configuration, enter the following command: -+ -[source,terminal] ----- -$ oc edit networks.config cluster ----- - -. Modify the ExternalIP configuration, as in the following example: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - ... - externalIP: <1> - ... ----- -<1> Specify the configuration for the `externalIP` stanza. - -. To confirm the updated ExternalIP configuration, enter the following command: -+ -[source,terminal] ----- -$ oc get networks.config cluster -o go-template='{{.spec.externalIP}}{{"\n"}}' ----- diff --git a/modules/nw-externalip-object.adoc b/modules/nw-externalip-object.adoc deleted file mode 100644 index 440cea43bac4..000000000000 --- a/modules/nw-externalip-object.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc - -[id="nw-externalip-object_{context}"] -= ExternalIP address block configuration - -The configuration for ExternalIP address blocks is defined by a Network custom resource (CR) named `cluster`. The Network CR is part of the `config.openshift.io` API group. - -[IMPORTANT] -==== -During cluster installation, the Cluster Version Operator (CVO) automatically creates a Network CR named `cluster`. -Creating any other CR objects of this type is not supported. -==== - -The following YAML describes the ExternalIP configuration: - -.Network.config.openshift.io CR named `cluster` -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - externalIP: - autoAssignCIDRs: [] <1> - policy: <2> - ... ----- -<1> Defines the IP address block in CIDR format that is available for automatic assignment of external IP addresses to a service. -Only a single IP address range is allowed. - -<2> Defines restrictions on manual assignment of an IP address to a service. -If no restrictions are defined, specifying the `spec.externalIP` field in a `Service` object is not allowed. -By default, no restrictions are defined. - -The following YAML describes the fields for the `policy` stanza: - -.Network.config.openshift.io `policy` stanza -[source,yaml] ----- -policy: - allowedCIDRs: [] <1> - rejectedCIDRs: [] <2> ----- -<1> A list of allowed IP address ranges in CIDR format. -<2> A list of rejected IP address ranges in CIDR format. - -[discrete] -== Example external IP configurations - -Several possible configurations for external IP address pools are displayed in the following examples: - -- The following YAML describes a configuration that enables automatically assigned external IP addresses: -+ -.Example configuration with `spec.externalIP.autoAssignCIDRs` set -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - ... - externalIP: - autoAssignCIDRs: - - 192.168.132.254/29 ----- - -- The following YAML configures policy rules for the allowed and rejected CIDR ranges: -+ -.Example configuration with `spec.externalIP.policy` set -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - ... - externalIP: - policy: - allowedCIDRs: - - 192.168.132.0/29 - - 192.168.132.8/29 - rejectedCIDRs: - - 192.168.132.7/32 ----- diff --git a/modules/nw-http2-haproxy.adoc b/modules/nw-http2-haproxy.adoc deleted file mode 100644 index 270cdd65efdf..000000000000 --- a/modules/nw-http2-haproxy.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ingress-operator.adoc - -[id="nw-http2-haproxy_{context}"] -= Enabling HTTP/2 Ingress connectivity - -You can enable transparent end-to-end HTTP/2 connectivity in HAProxy. It allows application owners to make use of HTTP/2 protocol capabilities, including single connection, header compression, binary streams, and more. - -You can enable HTTP/2 connectivity for an individual Ingress Controller or for the entire cluster. - -To enable the use of HTTP/2 for the connection from the client to HAProxy, a route must specify a custom certificate. A route that uses the default certificate cannot use HTTP/2. This restriction is necessary to avoid problems from connection coalescing, where the client re-uses a connection for different routes that use the same certificate. - -The connection from HAProxy to the application pod can use HTTP/2 only for re-encrypt routes and not for edge-terminated or insecure routes. This restriction is because HAProxy uses Application-Level Protocol Negotiation (ALPN), which is a TLS extension, to negotiate the use of HTTP/2 with the back-end. The implication is that end-to-end HTTP/2 is possible with passthrough and re-encrypt and not with insecure or edge-terminated routes. - -[IMPORTANT] -==== -For non-passthrough routes, the Ingress Controller negotiates its connection to the application independently of the connection from the client. This means a client may connect to the Ingress Controller and negotiate HTTP/1.1, and the Ingress Controller may then connect to the application, negotiate HTTP/2, and forward the request from the client HTTP/1.1 connection using the HTTP/2 connection to the application. This poses a problem if the client subsequently tries to upgrade its connection from HTTP/1.1 to the WebSocket protocol, because the Ingress Controller cannot forward WebSocket to HTTP/2 and cannot upgrade its HTTP/2 connection to WebSocket. Consequently, if you have an application that is intended to accept WebSocket connections, it must not allow negotiating the HTTP/2 protocol or else clients will fail to upgrade to the WebSocket protocol. -==== - -.Procedure - -Enable HTTP/2 on a single Ingress Controller. - -* To enable HTTP/2 on an Ingress Controller, enter the `oc annotate` command: -+ -[source,terminal] ----- -$ oc -n openshift-ingress-operator annotate ingresscontrollers/<ingresscontroller_name> ingress.operator.openshift.io/default-enable-http2=true ----- -+ -Replace `<ingresscontroller_name>` with the name of the Ingress Controller to annotate. - -Enable HTTP/2 on the entire cluster. - -* To enable HTTP/2 for the entire cluster, enter the `oc annotate` command: -+ -[source,terminal] ----- -$ oc annotate ingresses.config/cluster ingress.operator.openshift.io/default-enable-http2=true ----- diff --git a/modules/nw-ingress-configuring-application-domain.adoc b/modules/nw-ingress-configuring-application-domain.adoc deleted file mode 100644 index 890e5838ea06..000000000000 --- a/modules/nw-ingress-configuring-application-domain.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc -// - -[id="nw-ingress-configuring-application-domain_{context}"] -= Configuring application domain for the Ingress Controller Operator on AWS - -//OpenShift Dedicated or Amazon RH OpenShift cluster administrator - -As a cluster administrator, you can specify an alternative default domain for user-created routes by configuring `appsDomain` field. If you specify an alternative domain, it overrides the default cluster domain for the purpose of determining the default host for a new route. - -For example, you can use the DNS domain for your company as the default domain for routes and ingresses for applications running on your cluster. - -.Prerequisites - -//* You deployed an {OSD} cluster. -* You deployed an {product-title} cluster on AWS infrastructure. -* You installed the `oc` command line interface. - -.Procedure - -. Configure the `appsDomain` field by specifying an alternative default domain for user-created routes. -+ -.. Edit the Ingress Controller Operator: -+ -[source,terminal] ----- -$ oc edit ingresses.config/cluster -o yaml ----- -+ -.. Edit the YAML file: -+ -.Sample `appsDomain` configuration to `apps.acme.io` -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Ingress -metadata: - name: cluster -spec: - domain: apps.<domain_url> - appsDomain: apps.acme.io ----- -+ -. Verify that an existing route contains the new domain name by exposing the route and verifying the route domain change: -//+ -//.. Access the Ingress Controller Operator YAML file: -//+ -//[source,terminal] -//---- -//$ oc get ingresses.config/cluster -o yaml -//---- -+ -[NOTE] -==== -Wait for the `openshift-apiserver` finish rolling updates before exposing the route. -==== -+ -.. Expose the route: -+ -[source,terminal] ----- -$ oc expose service hello-openshift -route.route.openshift.io/hello-openshift exposed ----- -+ -.. Verify route domain change: -+ -[source,terminal] ----- -$ oc get routes -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -hello-openshift hello-openshift-my-project.apps.acme.io hello-openshift 8080-tcp None ----- diff --git a/modules/nw-ingress-controller-configuration-parameters.adoc b/modules/nw-ingress-controller-configuration-parameters.adoc deleted file mode 100644 index ed1088eb497f..000000000000 --- a/modules/nw-ingress-controller-configuration-parameters.adoc +++ /dev/null @@ -1,155 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc - -[id="nw-ingress-controller-configuration-parameters_{context}"] -= Ingress controller configuration parameters - -The `ingresscontrollers.operator.openshift.io` resource offers the following -configuration parameters. - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`domain` -|`domain` is a DNS name serviced by the Ingress controller and is used to configure multiple features: - -* For the `LoadBalancerService` endpoint publishing strategy, `domain` is used to configure DNS records. See `endpointPublishingStrategy`. - -* When using a generated default certificate, the certificate is valid for `domain` and its `subdomains`. See `defaultCertificate`. - -* The value is published to individual Route statuses so that users know where to target external DNS records. - -The `domain` value must be unique among all Ingress controllers and cannot be updated. - -If empty, the default value is `ingress.config.openshift.io/cluster` `.spec.domain`. - -|`appsDomain` -|`appsDomain` is an optional domain for AWS infrastructure to use instead of the one specified in the `domain` field when a Route is created without specifying an explicit host. If a value is entered for `appsDomain`, this value is used to generate default host values for the Route. Unlike `domain`, `appsDomain` can be modified after installation. You can use this parameter only if you set up a new Ingress Controller that uses a wildcard certificate. - -|`replicas` -|`replicas` is the desired number of Ingress controller replicas. If not set, the default value is `2`. - -|`endpointPublishingStrategy` -|`endpointPublishingStrategy` is used to publish the Ingress controller endpoints to other networks, enable load balancer integrations, and provide access to other systems. - -If not set, the default value is based on `infrastructure.config.openshift.io/cluster` `.status.platform`: - -* AWS: `LoadBalancerService` (with external scope) -* Azure: `LoadBalancerService` (with external scope) -* GCP: `LoadBalancerService` (with external scope) -* Bare metal: `NodePortService` -* Other: `HostNetwork` - -The `endpointPublishingStrategy` value cannot be updated. - -|`defaultCertificate` -|The `defaultCertificate` value is a reference to a secret that contains the default certificate that is served by the Ingress controller. When Routes do not specify their own certificate, `defaultCertificate` is used. - -The secret must contain the following keys and data: -* `tls.crt`: certificate file contents -* `tls.key`: key file contents - -If not set, a wildcard certificate is automatically generated and used. The certificate is valid for the Ingress controller `domain` and `subdomains`, and -the generated certificate's CA is automatically integrated with the -cluster's trust store. - -The in-use certificate, whether generated or user-specified, is automatically integrated with {product-title} built-in OAuth server. - -|`namespaceSelector` -|`namespaceSelector` is used to filter the set of namespaces serviced by the -Ingress controller. This is useful for implementing shards. - -|`routeSelector` -|`routeSelector` is used to filter the set of Routes serviced by the Ingress controller. This is useful for implementing shards. - -|`nodePlacement` -|`nodePlacement` enables explicit control over the scheduling of the Ingress controller. - -If not set, the defaults values are used. - -[NOTE] -==== -The `nodePlacement` parameter includes two parts, `nodeSelector` and `tolerations`. For example: - ----- -nodePlacement: - nodeSelector: - matchLabels: - beta.kubernetes.io/os: linux - tolerations: - - effect: NoSchedule - operator: Exists ----- -==== - -|`tlsSecurityProfile` -|`tlsSecurityProfile` specifies settings for TLS connections for Ingress controllers. - -If not set, the default value is based on the `apiservers.config.openshift.io/cluster` resource. - -When using the `Old`, `Intermediate`, and `Modern` profile types, the effective profile configuration is subject to change between releases. For example, given a specification to use the `Intermediate` profile deployed on release `X.Y.Z`, an upgrade to release `X.Y.Z+1` may cause a new profile configuration to be applied to the Ingress controller, resulting in a rollout. - -The minimum TLS version for Ingress controllers is `1.1`, and the maximum TLS version is `1.2`. - -[IMPORTANT] -==== -The HAProxy Ingress controller image does not support TLS `1.3` and because the `Modern` profile requires TLS `1.3`, it is not supported. The Ingress Operator converts the `Modern` profile to `Intermediate`. - -The Ingress Operator also converts the TLS `1.0` of an `Old` or `Custom` profile to `1.1`, and TLS `1.3` of a `Custom` profile to `1.2`. -==== - -[NOTE] -==== -Ciphers and the minimum TLS version of the configured security profile are reflected in the `TLSProfile` status. -==== - -|`routeAdmission` -|`routeAdmission` defines a policy for handling new route claims, such as allowing or denying claims across namespaces. - -`namespaceOwnership` describes how host name claims across namespaces should be handled. The default is `Strict`. - -* `Strict`: does not allow routes to claim the same host name across namespaces. -* `InterNamespaceAllowed`: allows routes to claim different paths of the same host name across namespaces. - -`wildcardPolicy` describes how routes with wildcard policies are handled by the Ingress Controller. - -* `WildcardsAllowed`: Indicates routes with any wildcard policy are admitted by the Ingress Controller. - -* `WildcardsDisallowed`: Indicates only routes with a wildcard policy of `None` are admitted by the Ingress Controller. Updating `wildcardPolicy` from `WildcardsAllowed` to `WildcardsDisallowed` causes admitted routes with a wildcard policy of `Subdomain` to stop working. These routes must be recreated to a wildcard policy of `None` to be readmitted by the Ingress Controller. `WildcardsDisallowed` is the default setting. - -|`IngressControllerLogging` -|`logging` defines parameters for what is logged where. If this field is empty, operational logs are enabled but access logs are disabled. - -* `access` describes how client requests are logged. If this field is empty, access logging is disabled. -** `destination` describes a destination for log messages. -*** `type` is the type of destination for logs: -**** `Container` specifies that logs should go to a sidecar container. The Ingress Operator configures the container, named *logs*, on the Ingress Controller pod and configures the Ingress Controller to write logs to the container. The expectation is that the administrator configures a custom logging solution that reads logs from this container. Using container logs means that logs may be dropped if the rate of logs exceeds the container runtime capacity or the custom logging solution capacity. -**** `Syslog` specifies that logs are sent to a Syslog endpoint. The administrator must specify an endpoint that can receive Syslog messages. The expectation is that the administrator has configured a custom Syslog instance. -*** `container` describes parameters for the `Container` logging destination type. Currently there are no parameters for container logging, so this field must be empty. -*** `syslog` describes parameters for the `Syslog` logging destination type: -**** `address` is the IP address of the syslog endpoint that receives log messages. -**** `port` is the UDP port number of the syslog endpoint that receives log messages. -**** `facility` specifies the syslog facility of log messages. If this field is empty, the facility is `local1`. Otherwise, it must specify a valid syslog facility: `kern`, `user`, `mail`, `daemon`, `auth`, `syslog`, `lpr`, `news`, `uucp`, `cron`, `auth2`, `ftp`, `ntp`, `audit`, `alert`, `cron2`, `local0`, `local1`, `local2`, `local3`. `local4`, `local5`, `local6`, or `local7`. -** `httpLogFormat` specifies the format of the log message for an HTTP request. If this field is empty, log messages use the implementation's default HTTP log format. For HAProxy's default HTTP log format, see link:http://cbonte.github.io/haproxy-dconv/2.0/configuration.html#8.2.3[the HAProxy documentation]. - -|`httpHeaders` -|`httpHeaders` defines the policy for HTTP headers. - -By setting the `forwardedHeaderPolicy` for the `IngressControllerHTTPHeaders`, you specify when and how the Ingress controller sets the `Forwarded`, `X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Proto`, and `X-Forwarded-Proto-Version` HTTP headers. - -By default, the policy is set to `Append`. - -* `Append` specifies that the Ingress Controller appends the headers, preserving any existing headers. -* `Replace` specifies that the Ingress Controller sets the headers, removing any existing headers. -* `IfNone` specifies that the Ingress Controller sets the headers if they are not already set. -* `Never` specifies that the Ingress Controller never sets the headers, preserving any existing headers. - -|=== - - -[NOTE] -==== -All parameters are optional. -==== diff --git a/modules/nw-ingress-controller-endpoint-publishing-strategies.adoc b/modules/nw-ingress-controller-endpoint-publishing-strategies.adoc deleted file mode 100644 index 80e042bbfc81..000000000000 --- a/modules/nw-ingress-controller-endpoint-publishing-strategies.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc - -[id="nw-ingress-controller-endpoint-publishing-strategies_{context}"] -= Ingress controller endpoint publishing strategy - -*`NodePortService` endpoint publishing strategy* - -The `NodePortService` endpoint publishing strategy publishes the Ingress Controller using a Kubernetes NodePort service. - -In this configuration, the Ingress Controller deployment uses container networking. A `NodePortService` is created to publish the deployment. The specific node ports are dynamically allocated by {product-title}; however, to support static port allocations, your changes to the node port field of the managed `NodePortService` are preserved. - -[NOTE] -==== -The Ingress Operator ignores any updates to `.spec.ports[].nodePort` fields of the service. - -By default, ports are allocated automatically and you can access the port allocations for integrations. However, sometimes static port allocations are necessary to integrate with existing infrastructure which may not be easily reconfigured in response to dynamic ports. To achieve integrations with static node ports, you can update the managed service resource directly. -==== - -For more information, see the link:https://kubernetes.io/docs/concepts/services-networking/service/#nodeport[Kubernetes Services documentation on `NodePort`]. - -*`HostNetwork` endpoint publishing strategy* - -The `HostNetwork` endpoint publishing strategy publishes the Ingress Controller on node ports where the Ingress Controller is deployed. - -An Ingress controller with the `HostNetwork` endpoint publishing strategy can have only one pod replica per node. If you want _n_ replicas, you must use at least _n_ nodes where those replicas can be scheduled. Because each pod replica requests ports `80` and `443` on the node host where it is scheduled, a replica cannot be scheduled to a node if another pod on the same node is using those ports. diff --git a/modules/nw-ingress-controller-status.adoc b/modules/nw-ingress-controller-status.adoc deleted file mode 100644 index 5102d247f1ce..000000000000 --- a/modules/nw-ingress-controller-status.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc - -[id="nw-ingress-controller-status_{context}"] -= View Ingress Controller status - -Your can view the status of a particular Ingress Controller. - -.Procedure - -* View the status of an Ingress Controller: -+ -[source,terminal] ----- -$ oc describe --namespace=openshift-ingress-operator ingresscontroller/<name> ----- diff --git a/modules/nw-ingress-controller-tls-profiles.adoc b/modules/nw-ingress-controller-tls-profiles.adoc deleted file mode 100644 index e1ef9c189085..000000000000 --- a/modules/nw-ingress-controller-tls-profiles.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc - -[id="nw-ingress-controller-tls-profiles_{context}"] -= Ingress controller TLS profiles - -The `tlsSecurityProfile` parameter defines the schema for a TLS security profile. This object is used by operators to apply TLS security settings to operands. - -There are four TLS security profile types: - -* `Old` -* `Intermediate` -* `Modern` -* `Custom` - -The `Old`, `Intermediate`, and `Modern` profiles are based on link:https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations[recommended configurations]. The `Custom` profile provides the ability to specify individual TLS security profile parameters. - -.Sample `Old` profile configuration -[source,yaml] ----- -spec: - tlsSecurityProfile: - type: Old ----- - -.Sample `Intermediate` profile configuration -[source,yaml] ----- -spec: - tlsSecurityProfile: - type: Intermediate ----- - -.Sample `Modern` profile configuration -[source,yaml] ----- -spec: - tlsSecurityProfile: - type: Modern ----- - -The `Custom` profile is a user-defined TLS security profile. - -[WARNING] -==== -You must be careful using a `Custom` profile, because invalid configurations can cause problems. -==== - -.Sample `Custom` profile -[source,yaml] ----- -spec: - tlsSecurityProfile: - type: Custom - custom: - ciphers: - - ECDHE-ECDSA-AES128-GCM-SHA256 - - ECDHE-RSA-AES128-GCM-SHA256 - minTLSVersion: VersionTLS11 ----- diff --git a/modules/nw-ingress-creating-a-passthrough-route.adoc b/modules/nw-ingress-creating-a-passthrough-route.adoc deleted file mode 100644 index 3973ab3050a9..000000000000 --- a/modules/nw-ingress-creating-a-passthrough-route.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/routes.adoc - -[id="nw-ingress-creating-a-passthrough-route_{context}"] -= Creating a passthrough route - -You can configure a secure route using passthrough termination by using the `oc create route` command. With passthrough termination, encrypted traffic is sent straight to the destination without the router providing TLS termination. Therefore no key or certificate is required on the route. - -.Prerequisites - -* You must have a service that you want to expose. - -.Procedure - -* Create a `Route` resource: -+ -[source,terminal] ----- -$ oc create route passthrough route-passthrough-secured --service=frontend --port=8080 ----- -+ -If you examine the resulting `Route` resource, it should look similar to the following: -+ -.A Secured Route Using Passthrough Termination -[source,yaml] ----- -apiVersion: v1 -kind: Route -metadata: - name: route-passthrough-secured <1> -spec: - host: www.example.com - port: - targetPort: 8080 - tls: - termination: passthrough <2> - insecureEdgeTerminationPolicy: None <3> - to: - kind: Service - name: frontend ----- -<1> The name of the object, which is limited to 63 characters. -<2> The `*termination*` field is set to `passthrough`. This is the only required `tls` field. -<3> Optional `insecureEdgeTerminationPolicy`. The only valid values are are `None`, `Redirect`, or empty for disabled. -+ -The destination pod is responsible for serving certificates for the -traffic at the endpoint. This is currently the only method that can support requiring client certificates, also known as two-way authentication. diff --git a/modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc b/modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc deleted file mode 100644 index 7fb3139053d2..000000000000 --- a/modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/routes.adoc - -[id="nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate_{context}"] -= Creating a re-encrypt route with a custom certificate - -You can configure a secure route using reencrypt TLS termination with a custom -certificate by using the `oc create route` command. - -.Prerequisites - -* You must have a certificate/key pair in PEM-encoded files, where the certificate -is valid for the route host. - -* You may have a separate CA certificate in a PEM-encoded file that completes -the certificate chain. - -* You must have a separate destination CA certificate in a PEM-encoded file. - -* You must have a service that you want to expose. - -[NOTE] -==== -Password protected key files are not supported. To remove a passphrase from a -key file, use the following command: - -[source,terminal] ----- -$ openssl rsa -in password_protected_tls.key -out tls.key ----- -==== - -.Procedure - -This procedure creates a `Route` resource with a custom certificate and -reencrypt TLS termination. The following assumes that the certificate/key pair -are in the `tls.crt` and `tls.key` files in the current working directory. You -must also specify a destination CA certificate to enable the Ingress Controller -to trust the service's certificate. You may also specify a CA certificate if -needed to complete the certificate chain. Substitute the actual path names for -`tls.crt`, `tls.key`, `cacert.crt`, and (optionally) `ca.crt`. Substitute the -name of the `Service` resource that you want to expose for `frontend`. -Substitute the appropriate host name for `www.example.com`. - -* Create a secure `Route` resource using reencrypt TLS termination and a custom -certificate: -+ -[source,terminal] ----- -$ oc create route reencrypt --service=frontend --cert=tls.crt --key=tls.key --dest-ca-cert=destca.crt --ca-cert=ca.crt --hostname=www.example.com ----- -+ -If you examine the resulting `Route` resource, it should look similar to the -following: -+ -.YAML Definition of the Secure Route -[source,yaml] ----- -apiVersion: v1 -kind: Route -metadata: - name: frontend -spec: - host: www.example.com - to: - kind: Service - name: frontend - tls: - termination: reencrypt - key: |- - -----BEGIN PRIVATE KEY----- - [...] - -----END PRIVATE KEY----- - certificate: |- - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE----- - caCertificate: |- - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE----- - destinationCACertificate: |- - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE----- ----- -+ -See `oc create route reencrypt --help` for more options. diff --git a/modules/nw-ingress-creating-a-route-via-an-ingress.adoc b/modules/nw-ingress-creating-a-route-via-an-ingress.adoc deleted file mode 100644 index b1d74451b879..000000000000 --- a/modules/nw-ingress-creating-a-route-via-an-ingress.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/routes/route-configuration.adoc - -[id="nw-ingress-creating-a-route-via-an-ingress_{context}"] -= Creating a route through an Ingress object - -Some ecosystem components have an integration with Ingress resources but not with -route resources. To cover this case, {product-title} automatically creates -managed route objects when an Ingress object is created. These route objects are deleted -when the corresponding Ingress objects are deleted. - -.Procedure - -. Define an Ingress object in the {product-title} console or by entering the oc `create` command: -+ -.YAML Definition of an Ingress -[source,yaml] ----- -apiVersion: networking.k8s.io/v1 -kind: Ingress -metadata: - name: frontend - annotations: - route.openshift.io/termination: "reencrypt" <1> -spec: - rules: - - host: www.example.com - http: - paths: - - backend: - serviceName: frontend - servicePort: 443 - tls: - - hosts: - - www.example.com - secretName: example-com-tls-certificate ----- -+ -<1> The `route.openshift.io/termination` annotation can be used to configure the `spec.tls.termination` field of the `Route` -as `Ingress` has no field for this. The accepted values are `edge`, `passthrough` and `reencrypt`. All -other values are silently ignored. When unset, `edge` is used. - -+ -[source,terminal] ----- -$ oc apply -f ingress.yaml ----- -+ - -. List your routes: -+ -[source,terminal] ----- -$ oc get routes ----- -+ -The result includes an autogenerated route whose name starts with `frontend-`: -+ -[source,terminal] ----- -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -frontend-gnztq www.example.com frontend 443 reencrypt/Redirect None ----- -+ -If you inspect this route, it looks this: -+ -.YAML Definition of an autogenerated route -[source,yaml] ----- -apiVersion: route.openshift.io/v1 -kind: Route -metadata: - name: frontend-gnztq - ownerReferences: - - apiVersion: networking.k8s.io/v1 - controller: true - kind: Ingress - name: frontend - uid: 4e6c59cc-704d-4f44-b390-617d879033b6 -spec: - host: www.example.com - to: - kind: Service - name: frontend - tls: - certificate: | - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE----- - insecureEdgeTerminationPolicy: Redirect - key: | - -----BEGIN RSA PRIVATE KEY----- - [...] - -----END RSA PRIVATE KEY----- - termination: reencrypt ----- diff --git a/modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc b/modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc deleted file mode 100644 index 2a00e201785a..000000000000 --- a/modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/routes.adoc - -[id="nw-ingress-creating-an-edge-route-with-a-custom-certificate_{context}"] -= Creating an edge route with a custom certificate - -You can configure a secure route using edge TLS termination with a custom -certificate by using the `oc create route` command. With an edge route, the -Ingress Controller terminates TLS encryption before forwarding traffic to the -destination pod. The route specifies the TLS certificate and key that the -Ingress Controller uses for the route. - -.Prerequisites - -* You must have a certificate/key pair in PEM-encoded files, where the certificate -is valid for the route host. - -* You may have a separate CA certificate in a PEM-encoded file that completes -the certificate chain. - -* You must have a service that you want to expose. - -[NOTE] -==== -Password protected key files are not supported. To remove a passphrase from a -key file, use the following command: - -[source,terminal] ----- -$ openssl rsa -in password_protected_tls.key -out tls.key ----- -==== - -.Procedure - -This procedure creates a `Route` resource with a custom certificate and edge TLS -termination. The following assumes that the certificate/key pair are in the -`tls.crt` and `tls.key` files in the current working directory. You may also -specify a CA certificate if needed to complete the certificate chain. -Substitute the actual path names for `tls.crt`, `tls.key`, and (optionally) -`ca.crt`. Substitute the name of the service that you want to expose -for `frontend`. Substitute the appropriate host name for `www.example.com`. - -* Create a secure `Route` resource using edge TLS termination and a custom certificate. -+ -[source,terminal] ----- -$ oc create route edge --service=frontend --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=www.example.com ----- -+ -If you examine the resulting `Route` resource, it should look similar to the -following: -+ -.YAML Definition of the Secure Route -[source,yaml] ----- -apiVersion: v1 -kind: Route -metadata: - name: frontend -spec: - host: www.example.com - to: - kind: Service - name: frontend - tls: - termination: edge - key: |- - -----BEGIN PRIVATE KEY----- - [...] - -----END PRIVATE KEY----- - certificate: |- - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE----- - caCertificate: |- - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE----- ----- -+ -See `oc create route edge --help` for more options. diff --git a/modules/nw-ingress-default-internal.adoc b/modules/nw-ingress-default-internal.adoc deleted file mode 100644 index 48dc73e93dc5..000000000000 --- a/modules/nw-ingress-default-internal.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ingress-operator.adoc - -[id="nw-ingress-default-internal_{context}"] -= Configuring the default Ingress Controller for your cluster to be internal - -You can configure the `default` Ingress Controller for your cluster to be internal by deleting and recreating it. - -[WARNING] -==== -If your cloud provider is Microsoft Azure, you must have at least one public load balancer that points to your nodes. -If you do not, all of your nodes will lose egress connectivity to the internet. -==== - -[IMPORTANT] -==== -If you want to change the `scope` for an `IngressController` object, you must delete and then recreate that `IngressController` object. You cannot change the `.spec.endpointPublishingStrategy.loadBalancer.scope` parameter after the custom resource (CR) is created. -==== - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Configure the `default` Ingress Controller for your cluster to be internal by deleting and recreating it. -+ -[source,terminal] ----- -$ oc replace --force --wait --filename - <<EOF -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - namespace: openshift-ingress-operator - name: default -spec: - endpointPublishingStrategy: - type: LoadBalancerService - loadBalancer: - scope: Internal -EOF ----- diff --git a/modules/nw-ingress-operator-logs.adoc b/modules/nw-ingress-operator-logs.adoc deleted file mode 100644 index 87bc1d85f0b6..000000000000 --- a/modules/nw-ingress-operator-logs.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc - -[id="nw-ingress-operator-logs_{context}"] -= View Ingress Controller logs - -You can view your Ingress Controller logs. - -.Procedure - -* View your Ingress Controller logs: -+ -[source,terminal] ----- -$ oc logs --namespace=openshift-ingress-operator deployments/ingress-operator ----- diff --git a/modules/nw-ingress-operator-status.adoc b/modules/nw-ingress-operator-status.adoc deleted file mode 100644 index 371be4187725..000000000000 --- a/modules/nw-ingress-operator-status.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc - -[id="nw-ingress-operator-status_{context}"] -= View Ingress Operator status - -You can view and inspect the status of your Ingress Operator. - -.Procedure - -* View your Ingress Operator status: -+ -[source,terminal] ----- -$ oc describe clusteroperators/ingress ----- diff --git a/modules/nw-ingress-select-route.adoc b/modules/nw-ingress-select-route.adoc deleted file mode 100644 index 8e4fa812d6e8..000000000000 --- a/modules/nw-ingress-select-route.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress.adoc - -[id="nw-ingress-select-route_{context}"] -= Configure Ingress to use routes - -//PLACEHOLDER diff --git a/modules/nw-ingress-setting-a-custom-default-certificate.adoc b/modules/nw-ingress-setting-a-custom-default-certificate.adoc deleted file mode 100644 index 29550cca5b39..000000000000 --- a/modules/nw-ingress-setting-a-custom-default-certificate.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ingress-operator.adoc - -[id="nw-ingress-setting-a-custom-default-certificate_{context}"] -= Setting a custom default certificate - -As an administrator, you can configure an Ingress Controller to use a custom -certificate by creating a Secret resource and editing the `IngressController` -custom resource (CR). - -.Prerequisites - -* You must have a certificate/key pair in PEM-encoded files, where the -certificate is signed by a trusted certificate authority or by a private trusted -certificate authority that you configured in a custom PKI. - -* Your certificate is valid for the Ingress domain. - -* You must have an `IngressController` CR. You may use the default one: -+ -[source,terminal] ----- -$ oc --namespace openshift-ingress-operator get ingresscontrollers ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -default 10m ----- - -[NOTE] -==== -If you have intermediate certificates, they must be included in the `tls.crt` -file of the secret containing a custom default certificate. Order matters when -specifying a certificate; list your intermediate certificate(s) after any server -certificate(s). -==== - -.Procedure - -The following assumes that the custom certificate and key pair are in the -`tls.crt` and `tls.key` files in the current working directory. Substitute the -actual path names for `tls.crt` and `tls.key`. You also may substitute another -name for `custom-certs-default` when creating the Secret resource and -referencing it in the IngressController CR. - -[NOTE] -==== -This action will cause the Ingress Controller to be redeployed, using a rolling deployment strategy. -==== - -. Create a Secret resource containing the custom certificate in the -`openshift-ingress` namespace using the `tls.crt` and `tls.key` files. -+ -[source,terminal] ----- -$ oc --namespace openshift-ingress create secret tls custom-certs-default --cert=tls.crt --key=tls.key ----- -+ -. Update the IngressController CR to reference the new certificate secret: -+ -[source,terminal] ----- -$ oc patch --type=merge --namespace openshift-ingress-operator ingresscontrollers/default \ - --patch '{"spec":{"defaultCertificate":{"name":"custom-certs-default"}}}' ----- -+ -. Verify the update was effective: -+ -[source,terminal] ----- -$ oc get --namespace openshift-ingress-operator ingresscontrollers/default \ - --output jsonpath='{.spec.defaultCertificate}' ----- -+ -.Example output -[source,terminal] ----- -map[name:custom-certs-default] ----- -+ -The certificate secret name should match the value used to update the CR. - -Once the IngressController CR has been modified, the Ingress Operator -updates the Ingress Controller's deployment to use the custom certificate. diff --git a/modules/nw-ingress-setting-internal-lb.adoc b/modules/nw-ingress-setting-internal-lb.adoc deleted file mode 100644 index fcbc9f101145..000000000000 --- a/modules/nw-ingress-setting-internal-lb.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ingress-operator.adoc - -[id="nw-ingress-setting-internal-lb_{context}"] -= Configuring an Ingress Controller to use an internal load balancer - -When creating an Ingress Controller on cloud platforms, the Ingress Controller is published by a public cloud load balancer by default. -As an administrator, you can create an Ingress Controller that uses an internal cloud load balancer. - -[WARNING] -==== -If your cloud provider is Microsoft Azure, you must have at least one public load balancer that points to your nodes. -If you do not, all of your nodes will lose egress connectivity to the internet. -==== - -[IMPORTANT] -==== -If you want to change the `scope` for an `IngressController` object, you must delete and then recreate that `IngressController` object. You cannot change the `.spec.endpointPublishingStrategy.loadBalancer.scope` parameter after the custom resource (CR) is created. -==== - -See the link:https://kubernetes.io/docs/concepts/services-networking/service/#internal-load-balancer[Kubernetes Services documentation] -for implementation details. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create an `IngressController` custom resource (CR) in a file named `<name>-ingress-controller.yaml`, such as in the following example: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - namespace: openshift-ingress-operator - name: <name> <1> -spec: - domain: <domain> <2> - endpointPublishingStrategy: - type: LoadBalancerService - loadBalancer: - scope: Internal <3> ----- -<1> Replace `<name>` with a name for the `IngressController` object. -<2> Specify the `domain` for the application published by the controller. -<3> Specify a value of `Internal` to use an internal load balancer. - -. Create the Ingress Controller defined in the previous step by running the following command: -+ -[source,terminal] ----- -$ oc create -f <name>-ingress-controller.yaml <1> ----- -<1> Replace `<name>` with the name of the `IngressController` object. - -. Optional: Confirm that the Ingress Controller was created by running the following command: -+ -[source,terminal] ----- -$ oc --all-namespaces=true get ingresscontrollers ----- diff --git a/modules/nw-ingress-sharding-namespace-labels.adoc b/modules/nw-ingress-sharding-namespace-labels.adoc deleted file mode 100644 index 1d93acde4e35..000000000000 --- a/modules/nw-ingress-sharding-namespace-labels.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc -// * ingress-operator.adoc - -[id="nw-ingress-sharding-namespace-labels_{context}"] -= Configuring Ingress Controller sharding by using namespace labels - -Ingress Controller sharding by using namespace labels means that the Ingress -Controller serves any route in any namespace that is selected by the namespace -selector. - -Ingress Controller sharding is useful when balancing incoming traffic load among -a set of Ingress Controllers and when isolating traffic to a specific Ingress -Controller. For example, company A goes to one Ingress Controller and company B -to another. - -.Procedure - -. Edit the `router-internal.yaml` file: -+ -[source,terminal] ----- -# cat router-internal.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -items: -- apiVersion: operator.openshift.io/v1 - kind: IngressController - metadata: - name: sharded - namespace: openshift-ingress-operator - spec: - domain: <apps-sharded.basedomain.example.net> - nodePlacement: - nodeSelector: - matchLabels: - node-role.kubernetes.io/worker: "" - namespaceSelector: - matchLabels: - type: sharded - status: {} -kind: List -metadata: - resourceVersion: "" - selfLink: "" ----- - -. Apply the Ingress Controller `router-internal.yaml` file: -+ -[source,terminal] ----- -# oc apply -f router-internal.yaml ----- -+ -The Ingress Controller selects routes in any namespace that is selected by the -namespace selector that have the label `type: sharded`. diff --git a/modules/nw-ingress-sharding-route-labels.adoc b/modules/nw-ingress-sharding-route-labels.adoc deleted file mode 100644 index e393a3ecd2b3..000000000000 --- a/modules/nw-ingress-sharding-route-labels.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc -// * networking/ingress-operator.adoc - -[id="nw-ingress-sharding-route-labels_{context}"] -= Configuring Ingress Controller sharding by using route labels - -Ingress Controller sharding by using route labels means that the Ingress -Controller serves any route in any namespace that is selected by the route -selector. - -Ingress Controller sharding is useful when balancing incoming traffic load among -a set of Ingress Controllers and when isolating traffic to a specific Ingress -Controller. For example, company A goes to one Ingress Controller and company B -to another. - -.Procedure - -. Edit the `router-internal.yaml` file: -+ -[source,terminal] ----- -# cat router-internal.yaml -apiVersion: v1 -items: -- apiVersion: operator.openshift.io/v1 - kind: IngressController - metadata: - name: sharded - namespace: openshift-ingress-operator - spec: - domain: <apps-sharded.basedomain.example.net> - nodePlacement: - nodeSelector: - matchLabels: - node-role.kubernetes.io/worker: "" - routeSelector: - matchLabels: - type: sharded - status: {} -kind: List -metadata: - resourceVersion: "" - selfLink: "" ----- - -. Apply the Ingress Controller `router-internal.yaml` file: -+ -[source,terminal] ----- -# oc apply -f router-internal.yaml ----- -+ -The Ingress Controller selects routes in any namespace that have the label -`type: sharded`. diff --git a/modules/nw-ingress-sharding.adoc b/modules/nw-ingress-sharding.adoc deleted file mode 100644 index 76a9864363c9..000000000000 --- a/modules/nw-ingress-sharding.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc -// * ingress-operator.adoc - -[id="nw-ingress-sharding_{context}"] -= Ingress Controller sharding - -As the primary mechanism for traffic to enter the cluster, the demands on the Ingress Controller, or router, can be significant. As a cluster administrator, you can shard the routes to: - -* Balance Ingress Controllers, or routers, with several routes to speed up responses to changes. -* Allocate certain routes to have different reliability guarantees than other routes. -* Allow certain Ingress Controllers to have different policies defined. -* Allow only specific routes to use additional features. -* Expose different routes on different addresses so that internal and external users can see different routes, for example. - -Ingress Controller can use either route labels or namespace labels as a sharding method. diff --git a/modules/nw-ingress-view.adoc b/modules/nw-ingress-view.adoc deleted file mode 100644 index 7f58db57ad6b..000000000000 --- a/modules/nw-ingress-view.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc - -[id="nw-ingress-view_{context}"] -= View the default Ingress Controller - -The Ingress Operator is a core feature of {product-title} and is enabled out of the -box. - -Every new {product-title} installation has an `ingresscontroller` named default. It -can be supplemented with additional Ingress Controllers. If the default -`ingresscontroller` is deleted, the Ingress Operator will automatically recreate it -within a minute. - -.Procedure - -* View the default Ingress Controller: -+ -[source,terminal] ----- -$ oc describe --namespace=openshift-ingress-operator ingresscontroller/default ----- diff --git a/modules/nw-installation-ingress-config-asset.adoc b/modules/nw-installation-ingress-config-asset.adoc deleted file mode 100644 index 5542d6f151b5..000000000000 --- a/modules/nw-installation-ingress-config-asset.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ingress/configuring_ingress_operator.adoc - - -[id="nw-installation-ingress-config-asset_{context}"] -= The Ingress configuration asset - -The installation program generates an asset with an `Ingress` resource in the -`config.openshift.io` API group, `cluster-ingress-02-config.yml`. - -.YAML Definition of the `Ingress` resource -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Ingress -metadata: - name: cluster -spec: - domain: apps.openshiftdemos.com ----- - -The installation program stores this asset in the -`cluster-ingress-02-config.yml` file in -the `manifests/` directory. This `Ingress` resource defines the cluster-wide -configuration for Ingress. This Ingress configuration is used as follows: - -* The Ingress Operator uses the domain from the cluster Ingress configuration as -the domain for the default Ingress Controller. - -* The OpenShift API server operator uses the domain from the cluster Ingress -configuration as the domain used when generating a default host for a `Route` -resource that does not specify an explicit host. diff --git a/modules/nw-kube-proxy-config.adoc b/modules/nw-kube-proxy-config.adoc deleted file mode 100644 index de95cd736b7b..000000000000 --- a/modules/nw-kube-proxy-config.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/configuring-kube-proxy.adoc - -[id="nw-kube-proxy-config_{context}"] -= kube-proxy configuration parameters - -You can modify the following `kubeProxyConfig` parameters. - -IMPORTANT: Because of performance improvements introduced in {product-title} 4.3 and greater, adjusting the `iptablesSyncPeriod` parameter is no longer necessary. - -.Parameters -[cols="30%,30%,30%,10%",options="header"] -|==== -|Parameter|Description|Values|Default - -|`iptablesSyncPeriod` -|The refresh period for `iptables` rules. -|A time interval, such as `30s` or `2m`. Valid -suffixes include `s`, `m`, and `h` and are described in the -link:https://golang.org/pkg/time/#ParseDuration[Go time package] documentation. -|`30s` - -|`proxyArguments.iptables-min-sync-period` -|The minimum duration before refreshing `iptables` rules. This parameter ensures -that the refresh does not happen too frequently. By default, a refresh starts as soon as a change that affects `iptables` rules occurs. -|A time interval, such as `30s` or `2m`. Valid suffixes include `s`, -`m`, and `h` and are described in the -link:https://golang.org/pkg/time/#ParseDuration[Go time package] -|`0s` - -|==== diff --git a/modules/nw-kube-proxy-configuring.adoc b/modules/nw-kube-proxy-configuring.adoc deleted file mode 100644 index 53508aef56fb..000000000000 --- a/modules/nw-kube-proxy-configuring.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/configuring-kube-proxy.adoc - -[id="nw-kube-proxy-configuring_{context}"] -= Modifying the kube-proxy configuration - -You can modify the Kubernetes network proxy configuration for your cluster. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in to a running cluster with the `cluster-admin` role. - -.Procedure - -. Edit the `Network.operator.openshift.io` custom resource (CR) by running the -following command: -+ -[source,terminal] ----- -$ oc edit network.operator.openshift.io cluster ----- - -. Modify the `kubeProxyConfig` parameter in the CR with your changes to the -kube-proxy configuration, such as in the following example CR: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - kubeProxyConfig: - iptablesSyncPeriod: 30s - proxyArguments: - iptables-min-sync-period: ["30s"] ----- - -. Save the file and exit the text editor. -+ -The syntax is validated by the `oc` command when you save the file and exit the -editor. If your modifications contain a syntax error, the editor opens the file -and displays an error message. - -. Enter the following command to confirm the configuration update: -+ -[source,terminal] ----- -$ oc get networks.operator.openshift.io -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -items: -- apiVersion: operator.openshift.io/v1 - kind: Network - metadata: - name: cluster - spec: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - defaultNetwork: - type: OpenShiftSDN - kubeProxyConfig: - iptablesSyncPeriod: 30s - proxyArguments: - iptables-min-sync-period: - - 30s - serviceNetwork: - - 172.30.0.0/16 - status: {} -kind: List ----- - -. Optional: Enter the following command to confirm that the Cluster Network -Operator accepted the configuration change: -+ -[source,terminal] ----- -$ oc get clusteroperator network ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -network 4.1.0-0.9 True False False 1m ----- -+ -The `AVAILABLE` field is `True` when the configuration update is applied -successfully. diff --git a/modules/nw-kube-proxy-sync.adoc b/modules/nw-kube-proxy-sync.adoc deleted file mode 100644 index ee65a93d8830..000000000000 --- a/modules/nw-kube-proxy-sync.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/configuring-kube-proxy.adoc - -[id="nw-kube-proxy-sync_{context}"] -= About iptables rules synchronization - -The synchronization period determines how frequently the Kubernetes network -proxy (kube-proxy) syncs the iptables rules on a node. - -A sync begins when either of the following events occurs: - -* An event occurs, such as service or endpoint is added to or removed from the -cluster. -* The time since the last sync exceeds the sync period defined for kube-proxy. diff --git a/modules/nw-modifying-operator-install-config.adoc b/modules/nw-modifying-operator-install-config.adoc deleted file mode 100644 index 9bf0253542ec..000000000000 --- a/modules/nw-modifying-operator-install-config.adoc +++ /dev/null @@ -1,141 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_azure/installing-azure-network-customizations.adoc -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_gcp/installing-gcp-network-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc - -ifeval::["{context}" == "installing-bare-metal-network-customizations"] -:ignition-config: -endif::[] -ifeval::["{context}" == "installing-vsphere-network-customizations"] -:ignition-config: -:vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations-user-infra"] -:ignition-config: -:vmc: -endif::[] - -[id="modifying-nwoperator-config-startup_{context}"] -= Modifying advanced network configuration parameters - -You can modify the advanced network configuration parameters only before you -install the cluster. Advanced configuration customization lets you integrate -your cluster into your existing network environment by specifying an MTU or -VXLAN port, by allowing customization of -link:https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/[kube-proxy] -settings, and by specifying a different `mode` for the `openshiftSDNConfig` -parameter. - -[IMPORTANT] -==== -Modifying the {product-title} manifest files created by the installation program is not supported. Applying a manifest file that you create, as in the following procedure, is supported. -==== - -.Prerequisites - -* Create the `install-config.yaml` file and complete any modifications to it. -ifdef::ignition-config[] -* Create the Ignition config files for your cluster. -endif::ignition-config[] - -.Procedure - -. Change to the directory that contains the installation program and create the manifests: -+ -[source,terminal] ----- -$ ./openshift-install create manifests --dir=<installation_directory> <1> ----- -<1> For `<installation_directory>`, specify the name of the directory that -contains the `install-config.yaml` file for your cluster. - -. Create a file that is named `cluster-network-03-config.yml` in the -`<installation_directory>/manifests/` directory: -+ -[source,terminal] ----- -$ touch <installation_directory>/manifests/cluster-network-03-config.yml <1> ----- -<1> For `<installation_directory>`, specify the directory name that contains the -`manifests/` directory for your cluster. -+ -After creating the file, several network configuration files are in the -`manifests/` directory, as shown: -+ -[source,terminal] ----- -$ ls <installation_directory>/manifests/cluster-network-* ----- -+ -.Example output -[source,terminal] ----- -cluster-network-01-crd.yml -cluster-network-02-config.yml -cluster-network-03-config.yml ----- - -. Open the `cluster-network-03-config.yml` file in an editor and enter a custom resource (CR) that -describes the Operator configuration you want: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: <1> - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - serviceNetwork: - - 172.30.0.0/16 - defaultNetwork: - type: OpenShiftSDN - openshiftSDNConfig: - mode: NetworkPolicy - mtu: 1450 - vxlanPort: 4789 ----- -<1> The parameters for the `spec` parameter are only an example. Specify your -configuration for the Cluster Network Operator in the CR. -+ -The CNO provides default values for the parameters in the CR, so you must -specify only the parameters that you want to change. - -. Save the `cluster-network-03-config.yml` file and quit the text editor. -. Optional: Back up the `manifests/cluster-network-03-config.yml` file. The -installation program deletes the `manifests/` directory when creating the -cluster. - -ifdef::vsphere,vmc[] -. Remove the Kubernetes manifest files that define the control plane machines and compute machineSets: -+ -[source,terminal] ----- -$ rm -f openshift/99_openshift-cluster-api_master-machines-*.yaml openshift/99_openshift-cluster-api_worker-machineset-*.yaml ----- -+ -Because you create and manage these resources yourself, you do not have -to initialize them. -+ -* You can preserve the MachineSet files to create compute machines by using the machine API, but you must update references to them to match your environment. -endif::vsphere,vmc[] - -ifeval::["{context}" == "installing-bare-metal-network-customizations"] -:!ignition-config: -endif::[] -ifeval::["{context}" == "installing-vsphere-network-customizations"] -:!ignition-config: -:!vsphere: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations-user-infra"] -:!ignition-config: -:!vmc: -endif::[] diff --git a/modules/nw-multitenant-global.adoc b/modules/nw-multitenant-global.adoc deleted file mode 100644 index 5c3f048663ce..000000000000 --- a/modules/nw-multitenant-global.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// * networking/multitenant-isolation.adoc - -[id="nw-multitenant-global_{context}"] -= Disabling network isolation for a project - -You can disable network isolation for a project. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster with a user that has the `cluster-admin` role. - -.Procedure - -* Run the following command for the project: -+ -[source,terminal] ----- -$ oc adm pod-network make-projects-global <project1> <project2> ----- -+ -Alternatively, instead of specifying specific project names, you can use the -`--selector=<project_selector>` option to specify projects based upon an -associated label. diff --git a/modules/nw-multitenant-isolation.adoc b/modules/nw-multitenant-isolation.adoc deleted file mode 100644 index 4cc779d78136..000000000000 --- a/modules/nw-multitenant-isolation.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// * networking/multitenant-isolation.adoc - -[id="nw-multitenant-isolation_{context}"] -= Isolating a project - -You can isolate a project so that pods and services in other projects cannot -access its pods and services. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster with a user that has the `cluster-admin` role. - -.Procedure - -* To isolate the projects in the cluster, run the following command: -+ -[source,terminal] ----- -$ oc adm pod-network isolate-projects <project1> <project2> ----- -+ -Alternatively, instead of specifying specific project names, you can use the -`--selector=<project_selector>` option to specify projects based upon an -associated label. diff --git a/modules/nw-multitenant-joining.adoc b/modules/nw-multitenant-joining.adoc deleted file mode 100644 index 028dcf9b2a9b..000000000000 --- a/modules/nw-multitenant-joining.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// * networking/multitenant-isolation.adoc - -[id="nw-multitenant-joining_{context}"] -= Joining projects - -You can join two or more projects to allow network traffic between pods and -services in different projects. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster with a user that has the `cluster-admin` role. - -.Procedure - -. Use the following command to join projects to an existing project network: -+ -[source,terminal] ----- -$ oc adm pod-network join-projects --to=<project1> <project2> <project3> ----- -+ -Alternatively, instead of specifying specific project names, you can use the -`--selector=<project_selector>` option to specify projects based upon an -associated label. - -. Optional: Run the following command to view the pod networks that you have -joined together: -+ -[source,terminal] ----- -$ oc get netnamespaces ----- -+ -Projects in the same pod-network have the same network ID in the *NETID* column. diff --git a/modules/nw-multus-add-pod.adoc b/modules/nw-multus-add-pod.adoc deleted file mode 100644 index f423824987dc..000000000000 --- a/modules/nw-multus-add-pod.adoc +++ /dev/null @@ -1,148 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/attaching-pod.adoc -// * networking/hardware_networks/add-pod.adoc - -ifeval::["{context}" == "configuring-sr-iov"] -:sriov: -endif::[] - -ifeval::["{product-version}" == "4.3"] -:bz: -endif::[] -ifeval::["{product-version}" == "4.4"] -:bz: -endif::[] -ifeval::["{product-version}" == "4.5"] -:bz: -endif::[] - -[id="nw-multus-add-pod_{context}"] -= Adding a pod to an additional network - -You can add a pod to an additional network. The pod continues to send normal cluster-related network traffic over the default network. - -When a pod is created additional networks are attached to it. However, if a pod already exists, you cannot attach additional networks to it. - -The pod must be in the same namespace as the additional network. - -ifdef::sriov[] -[NOTE] -===== -If a network attachment is managed by the SR-IOV Network Operator, the SR-IOV Network Resource Injector adds the `resource` field to the `Pod` object automatically. -===== - -ifdef::bz[] -[IMPORTANT] -==== -When specifying an SR-IOV hardware network for a `Deployment` object or a `ReplicationController` object, you must specify the namespace of the `NetworkAttachmentDefinition` object. For more information, see the following bugs: link:https://bugzilla.redhat.com/show_bug.cgi?id=1846333[BZ#1846333] and link:https://bugzilla.redhat.com/show_bug.cgi?id=1840962[BZ#1840962]. -==== -endif::bz[] -endif::sriov[] - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in to the cluster. -ifdef::sriov[] -* Install the SR-IOV Operator. -* Create either an `SriovNetwork` object or an `SriovIBNetwork` object to attach the pod to. -endif::sriov[] - -.Procedure - -. Add an annotation to the `Pod` object. Only one of the following annotation formats can be used: - -.. To attach an additional network without any customization, add an annotation with the following format. Replace `<network>` with the name of the additional network to associate with the pod: -+ -[source,yaml] ----- -metadata: - annotations: - k8s.v1.cni.cncf.io/networks: <network>[,<network>,...] <1> ----- -<1> To specify more than one additional network, separate each network -with a comma. Do not include whitespace between the comma. If you specify -the same additional network multiple times, that pod will have multiple network -interfaces attached to that network. - -.. To attach an additional network with customizations, add an annotation with the following format: -+ -[source,yaml] ----- -metadata: - annotations: - k8s.v1.cni.cncf.io/networks: |- - [ - { - "name": "<network>", <1> - "namespace": "<namespace>", <2> - "default-route": ["<default-route>"] <3> - } - ] ----- -<1> Specify the name of the additional network defined by a `NetworkAttachmentDefinition` object. -<2> Specify the namespace where the `NetworkAttachmentDefinition` object is defined. -<3> Optional: Specify an override for the default route, such as `192.168.17.1`. - -. To create the pod, enter the following command. Replace `<name>` with the name of the pod. -+ -[source,terminal] ----- -$ oc create -f <name>.yaml ----- - -. Optional: To Confirm that the annotation exists in the `Pod` CR, enter the following command, replacing `<name>` with the name of the pod. -+ -[source,terminal] ----- -$ oc get pod <name> -o yaml ----- -+ -In the following example, the `example-pod` pod is attached to the `net1` -additional network: -+ -[source,terminal] ----- -$ oc get pod example-pod -o yaml -apiVersion: v1 -kind: Pod -metadata: - annotations: - k8s.v1.cni.cncf.io/networks: macvlan-bridge - k8s.v1.cni.cncf.io/networks-status: |- <1> - [{ - "name": "openshift-sdn", - "interface": "eth0", - "ips": [ - "10.128.2.14" - ], - "default": true, - "dns": {} - },{ - "name": "macvlan-bridge", - "interface": "net1", - "ips": [ - "20.2.2.100" - ], - "mac": "22:2f:60:a5:f8:00", - "dns": {} - }] - name: example-pod - namespace: default -spec: - ... -status: - ... ----- -<1> The `k8s.v1.cni.cncf.io/networks-status` parameter is a JSON array of -objects. Each object describes the status of an additional network attached -to the pod. The annotation value is stored as a plain text value. - -ifeval::["{context}" == "configuring-sr-iov"] -:!sriov: -endif::[] - -ifdef::bz[] -:!bz: -endif::bz[] diff --git a/modules/nw-multus-advanced-annotations.adoc b/modules/nw-multus-advanced-annotations.adoc deleted file mode 100644 index 62090ea71194..000000000000 --- a/modules/nw-multus-advanced-annotations.adoc +++ /dev/null @@ -1,204 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/attaching-pod.adoc - -[id="nw-multus-advanced-annotations_{context}"] -= Specifying pod-specific addressing and routing options - -When attaching a pod to an additional network, you may want to specify further properties -about that network in a particular pod. This allows you to change some aspects of routing, as well -as specify static IP addresses and MAC addresses. To accomplish this, you can use the JSON formatted annotations. - -.Prerequisites - -* The pod must be in the same namespace as the additional network. -* Install the OpenShift Command-line Interface (`oc`). -* You must log in to the cluster. -ifdef::sriov[] -* You must have the SR-IOV Operator installed and a `SriovNetwork` object defined. -endif::sriov[] - -.Procedure - -To add a pod to an additional network while specifying addressing and/or routing options, complete the following steps: - -. Edit the `Pod` resource definition. If you are editing an existing `Pod` resource, run the -following command to edit its definition in the default editor. Replace `<name>` -with the name of the `Pod` resource to edit. -+ -[source,terminal] ----- -$ oc edit pod <name> ----- - -. In the `Pod` resource definition, add the `k8s.v1.cni.cncf.io/networks` -parameter to the pod `metadata` mapping. The `k8s.v1.cni.cncf.io/networks` -accepts a JSON string of a list of objects that reference the name of `NetworkAttachmentDefinition` custom resource (CR) names -in addition to specifying additional properties. -+ -[source,yaml] ----- -metadata: - annotations: - k8s.v1.cni.cncf.io/networks: '[<network>[,<network>,...]]' <1> ----- -<1> Replace `<network>` with a JSON object as shown in the following examples. The single quotes are required. - -. In the following example the annotation specifies which network attachment will have the default route, -using the `default-route` parameter. -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: example-pod - annotations: - k8s.v1.cni.cncf.io/networks: ' - { - "name": "net1" - }, - { - "name": "net2", <1> - "default-route": ["192.0.2.1"] <2> - }' -spec: - containers: - - name: example-pod - command: ["/bin/bash", "-c", "sleep 2000000000000"] - image: centos/tools ----- -<1> The `name` key is the name of the additional network to associate -with the pod. -<2> The `default-route` key specifies a value of a gateway for traffic to be routed over if no other -routing entry is present in the routing table. If more than one `default-route` key is specified, -this will cause the pod to fail to become active. - -The default route will cause any traffic that is not specified in other routes to be routed to the gateway. - -[IMPORTANT] -==== -Setting the default route to an interface other than the default network interface for {product-title} -may cause traffic that is anticipated for pod-to-pod traffic to be routed over another interface. -==== - -To verify the routing properties of a pod, the `oc` command may be used to execute the `ip` command within a pod. - -[source,terminal] ----- -$ oc exec -it <pod_name> -- ip route ----- - -[NOTE] -==== -You may also reference the pod's `k8s.v1.cni.cncf.io/networks-status` to see which additional network has been -assigned the default route, by the presence of the `default-route` key in the JSON-formatted list of objects. -==== - -To set a static IP address or MAC address for a pod you can use the JSON formatted annotations. This requires you create networks that specifically allow for this functionality. This can be specified in a rawCNIConfig for the CNO. - -. Edit the CNO CR by running the following command: -+ -[source,terminal] ----- -$ oc edit networks.operator.openshift.io cluster ----- - -The following YAML describes the configuration parameters for the CNO: - -.Cluster Network Operator YAML configuration -[source,yaml] ----- -name: <name> <1> -namespace: <namespace> <2> -rawCNIConfig: '{ <3> - ... -}' -type: Raw ----- -<1> Specify a name for the additional network attachment that you are -creating. The name must be unique within the specified `namespace`. - -<2> Specify the namespace to create the network attachment in. If -you do not specify a value, then the `default` namespace is used. - -<3> Specify the CNI plug-in configuration in JSON format, which -is based on the following template. - -The following object describes the configuration parameters for utilizing static MAC address -and IP address using the macvlan CNI plug-in: - -.macvlan CNI plug-in JSON configuration object using static IP and MAC address -[source,json] ----- -{ - "cniVersion": "0.3.1", - "plugins": [{ <1> - "type": "macvlan", - "capabilities": { "ips": true }, <2> - "master": "eth0", <3> - "mode": "bridge", - "ipam": { - "type": "static" - } - }, { - "capabilities": { "mac": true }, <4> - "type": "tuning" - }] -} ----- - -<1> The `plugins` field specifies a configuration list of CNI configurations. - -<2> The `capabilities` key denotes that a request is being made to enable the static IP functionality of a CNI plug-ins runtime configuration capabilities. - -<3> The `master` field is specific to the macvlan plug-in. - -<4> Here the `capabilities` key denotes that a request is made to enable the static MAC address functionality of a CNI plug-in. - -The above network attachment may then be referenced in a JSON formatted annotation, along with keys to specify which -static IP and MAC address will be assigned to a given pod. - -Edit the desired pod with: - -[source,terminal] ----- -$ oc edit pod <name> ----- - -.macvlan CNI plug-in JSON configuration object using static IP and MAC address - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: example-pod - annotations: - k8s.v1.cni.cncf.io/networks: '[ - { - "name": "<name>", <1> - "ips": [ "192.0.2.205/24" ], <2> - "mac": "CA:FE:C0:FF:EE:00" <3> - } - ]' ----- - -<1> Use the `<name>` as provided when creating the `rawCNIConfig` above. - -<2> Provide the desired IP address. - -<3> Provide the desired MAC address. - -[NOTE] -==== -Static IP addresses and MAC addresses do not have to be used at the same time, you may use them -individually, or together. -==== - -To verify the IP address and MAC properties of a pod with additional networks, use the `oc` command to execute the ip command within a pod. - -[source,terminal] ----- -$ oc exec -it <pod_name> -- ip a ----- diff --git a/modules/nw-multus-bridge-object.adoc b/modules/nw-multus-bridge-object.adoc deleted file mode 100644 index fb2b86d04dee..000000000000 --- a/modules/nw-multus-bridge-object.adoc +++ /dev/null @@ -1,126 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-bridge.adoc - -[id="nw-multus-bridge-object_{context}"] -= Configuration for bridge - -The configuration for an additional network attachment that uses the bridge -Container Network Interface (CNI) plug-in is provided in two parts: - -* Cluster Network Operator (CNO) configuration -* CNI plug-in configuration - -The CNO configuration specifies the name for the additional network attachment -and the namespace to create the attachment in. The plug-in -is configured by a JSON object specified by the `rawCNIConfig` parameter in -the CNO configuration. - -The following YAML describes the configuration parameters for the CNO: - -.Cluster Network Operator YAML configuration -[source,yaml] ----- -name: <name> <1> -namespace: <namespace> <2> -rawCNIConfig: '{ <3> - ... -}' -type: Raw ----- -<1> Specify a name for the additional network attachment that you are -creating. The name must be unique within the specified `namespace`. - -<2> Specify the namespace to create the network attachment in. If -you do not specify a value, then the `default` namespace is used. - -<3> Specify the CNI plug-in configuration in JSON format, which -is based on the following template. - -The following object describes the configuration parameters for the bridge CNI -plug-in: - -.bridge CNI plug-in JSON configuration object -[source,json] ----- -{ - "cniVersion": "0.3.1", - "name": "<name>", <1> - "type": "bridge", - "bridge": "<bridge>", <2> - "ipam": { <3> - ... - }, - "ipMasq": false, <4> - "isGateway": false, <5> - "isDefaultGateway": false, <6> - "forceAddress": false, <7> - "hairpinMode": false, <8> - "promiscMode": false, <9> - "vlan": <vlan>, <10> - "mtu": <mtu> <11> -} ----- -<1> Specify the value for the `name` parameter you provided previously for -the CNO configuration. - -<2> Specify the name of the virtual bridge to use. If the bridge -interface does not exist on the host, it is created. The default value is -`cni0`. - -<3> Specify a configuration object for the ipam CNI plug-in. The plug-in -manages IP address assignment for the network attachment definition. - -<4> Set to `true` to enable IP masquerading for traffic that leaves the -virtual network. The source IP address for all traffic is rewritten to the -bridge's IP address. If the bridge does not have an IP address, this setting has -no effect. The default value is `false`. - -<5> Set to `true` to assign an IP address to the bridge. The -default value is `false`. - -<6> Set to `true` to configure the bridge as the default -gateway for the virtual network. The default value is `false`. If -`isDefaultGateway` is set to `true`, then `isGateway` is also set to `true` -automatically. - -<7> Set to `true` to allow assignment of a previously assigned -IP address to the virtual bridge. When set to `false`, if an IPv4 address or an -IPv6 address from overlapping subsets is assigned to the virtual bridge, an -error occurs. The default value is `false`. - -<8> Set to `true` to allow the virtual bridge to send an ethernet -frame back through the virtual port it was received on. This mode is also known -as _reflective relay_. The default value is `false`. - -<9> Set to `true` to enable promiscuous mode on the bridge. The -default value is `false`. - -<10> Specify a virtual LAN (VLAN) tag as an integer value. By default, -no VLAN tag is assigned. - -<11> Set the maximum transmission unit (MTU) to the specified value. The -default value is automatically set by the kernel. - -[id="nw-multus-bridge-config-example_{context}"] -== bridge configuration example - -The following example configures an additional network named `bridge-net`: - -[source,yaml] ----- -name: bridge-net -namespace: work-network -type: Raw -rawCNIConfig: '{ <1> - "cniVersion": "0.3.1", - "name": "work-network", - "type": "bridge", - "isGateway": true, - "vlan": 2, - "ipam": { - "type": "dhcp" - } -}' ----- -<1> The CNI configuration object is specified as a YAML string. diff --git a/modules/nw-multus-create-network.adoc b/modules/nw-multus-create-network.adoc deleted file mode 100644 index fb3b808611bf..000000000000 --- a/modules/nw-multus-create-network.adoc +++ /dev/null @@ -1,245 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-macvlan.adoc -// * networking/multiple_networks/configuring-ipvlan.adoc -// * networking/multiple_networks/configuring-bridge.adoc -// * networking/multiple_networks/configuring-host-device.adoc - -// Configuring Multus plug-ins using the Cluster Network Operator -// is nearly identical in each case. - -ifeval::["{context}" == "configuring-macvlan-basic"] -:plugin: macvlan -:macvlan: -:yaml: -endif::[] -// This is necessary for Whereabouts CNI which is JSON-only -ifeval::["{context}" == "configuring-macvlan"] -:plugin: macvlan -:macvlan: -:json: -endif::[] -ifeval::["{context}" == "configuring-ipvlan"] -:plugin: ipvlan -:json: -endif::[] -ifeval::["{context}" == "configuring-bridge"] -:plugin: bridge -:json: -endif::[] -ifeval::["{context}" == "configuring-host-device"] -:plugin: host-device -:json: -endif::[] - -[id="nw-multus-create-network_{context}"] -= Creating an additional network attachment with the {plugin} CNI plug-in - -The Cluster Network Operator (CNO) manages additional network definitions. When -you specify an additional network to create, the CNO creates the -`NetworkAttachmentDefinition` object automatically. - -[IMPORTANT] -==== -Do not edit the `NetworkAttachmentDefinition` objects that the Cluster Network -Operator manages. Doing so might disrupt network traffic on your additional -network. -==== - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -To create an additional network for your cluster, complete the following steps: - -. Edit the CNO CR by running the following command: -+ -[source,terminal] ----- -$ oc edit networks.operator.openshift.io cluster ----- - -. Modify the CR that you are creating by adding the configuration for the -additional network you are creating, as in the following example CR. -+ -ifdef::yaml[] -The following YAML configures the {plugin} CNI plug-in: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - additionalNetworks: <1> - - name: test-network-1 - namespace: test-1 - type: SimpleMacvlan - simpleMacvlanConfig: - ipamConfig: - type: static - staticIPAMConfig: - addresses: - - address: 10.1.1.7/24 ----- -endif::yaml[] -ifdef::json[] -The following YAML configures the {plugin} CNI plug-in: -endif::json[] -+ -ifeval::["{plugin}" == "bridge"] -[source,yaml,subs="attributes+"] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - additionalNetworks: <1> - - name: test-network-1 - namespace: test-1 - type: Raw - rawCNIConfig: '{ - "cniVersion": "0.3.1", - "name": "test-network-1", - "type": "{plugin}", - "ipam": { - "type": "static", - "addresses": [ - { - "address": "192.168.1.23/24" - } - ] - } - }' ----- -endif::[] -ifeval::["{plugin}" == "host-device"] -[source,yaml,subs="attributes+"] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - additionalNetworks: <1> - - name: test-network-1 - namespace: test-1 - type: Raw - rawCNIConfig: '{ - "cniVersion": "0.3.1", - "name": "test-network-1", - "type": "{plugin}", - "device": "eth1", - "ipam": { - "type": "static", - "addresses": [ - { - "address": "192.168.1.23/24" - } - ] - } - }' ----- -endif::[] -ifeval::["{plugin}" == "ipvlan"] -[source,yaml,subs="attributes+"] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - additionalNetworks: <1> - - name: test-network-1 - namespace: test-1 - type: Raw - rawCNIConfig: '{ - "cniVersion": "0.3.1", - "name": "test-network-1", - "type": "{plugin}", - "master": "eth1", - "mode": "l2", - "ipam": { - "type": "static", - "addresses": [ - { - "address": "192.168.1.23/24" - } - ] - } - }' ----- -endif::[] -ifdef::macvlan+json[] -[source,yaml,subs="attributes+"] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - additionalNetworks: <1> - - name: test-network-1 - namespace: test-1 - type: Raw - rawCNIConfig: '{ - "cniVersion": "0.3.1", - "name": "test-network-1", - "type": "{plugin}", - "master": "eth1", - "ipam": { - "type": "static", - "addresses": [ - { - "address": "192.168.1.23/24" - } - ] - } - }' ----- -endif::[] -<1> Specify the configuration for the additional network attachment definition. - -. Save your changes and quit the text editor to commit your changes. - -. Confirm that the CNO created the NetworkAttachmentDefinition object by running the following command. Replace `<namespace>` with the namespace that you specified when configuring the network attachment. There might be a delay before the CNO creates the object. -+ -[source,terminal] ----- -$ oc get network-attachment-definitions -n <namespace> ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -test-network-1 14m ----- - -ifeval::["{context}" == "configuring-macvlan-basic"] -:!macvlan: -:!plugin: -:!yaml: -endif::[] -ifeval::["{context}" == "configuring-macvlan"] -:!macvlan: -:!plugin: -:!json: -endif::[] -ifeval::["{context}" == "configuring-ipvlan"] -:!plugin: -:!json: -endif::[] -ifeval::["{context}" == "configuring-bridge"] -:!plugin: -:!json: -endif::[] -ifeval::["{context}" == "configuring-host-device"] -:!plugin: -:!json: -endif::[] diff --git a/modules/nw-multus-delete-network.adoc b/modules/nw-multus-delete-network.adoc deleted file mode 100644 index 8aedf56e5fd0..000000000000 --- a/modules/nw-multus-delete-network.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/remove-additional-network.adoc - -[id="nw-multus-delete-network_{context}"] -= Removing an additional network attachment definition - -As a cluster administrator, you can remove an additional network from your -{product-title} cluster. The additional network is not removed from any pods it -is attached to. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -To remove an additional network from your cluster, complete the following steps: - -. Edit the Cluster Network Operator (CNO) in your default text editor by running -the following command: -+ -[source,terminal] ----- -$ oc edit networks.operator.openshift.io cluster ----- - -. Modify the CR by removing the configuration from the `additionalNetworks` -collection for the network attachment definition you are removing. -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - additionalNetworks: [] <1> ----- -<1> If you are removing the configuration mapping for the only additional -network attachment definition in the `additionalNetworks` collection, you must -specify an empty collection. - -. Save your changes and quit the text editor to commit your changes. - -. Optional: Confirm that the additional network CR was deleted by running the following command: -+ -[source,terminal] ----- -$ oc get network-attachment-definition --all-namespaces ----- diff --git a/modules/nw-multus-edit-network.adoc b/modules/nw-multus-edit-network.adoc deleted file mode 100644 index f71875921496..000000000000 --- a/modules/nw-multus-edit-network.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/edit-additional-network.adoc - -[id="nw-multus-edit-network_{context}"] -= Modifying an additional network attachment definition - -As a cluster administrator, you can make changes to an existing additional -network. Any existing pods attached to the additional network will not be updated. - -.Prerequisites - -* You have configured an additional network for your cluster. -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -To edit an additional network for your cluster, complete the following steps: - -. Run the following command to edit the Cluster Network Operator (CNO) CR in -your default text editor: -+ -[source,terminal] ----- -$ oc edit networks.operator.openshift.io cluster ----- - -. In the `additionalNetworks` collection, update the additional network with -your changes. - -. Save your changes and quit the text editor to commit your changes. - -. Optional: Confirm that the CNO updated the `NetworkAttachmentDefinition` object by running the following command. Replace `<network-name>` with the name of the additional network to display. There might be a delay before the CNO updates the `NetworkAttachmentDefinition` object to reflect your changes. -+ -[source,terminal] ----- -$ oc get network-attachment-definitions <network-name> -o yaml ----- -+ -For example, the following console output displays a `NetworkAttachmentDefinition` object that is named `net1`: -+ -[source,terminal] ----- -$ oc get network-attachment-definitions net1 -o go-template='{{printf "%s\n" .spec.config}}' -{ "cniVersion": "0.3.1", "type": "macvlan", -"master": "ens5", -"mode": "bridge", -"ipam": {"type":"static","routes":[{"dst":"0.0.0.0/0","gw":"10.128.2.1"}],"addresses":[{"address":"10.128.2.100/23","gateway":"10.128.2.1"}],"dns":{"nameservers":["172.30.0.10"],"domain":"us-west-2.compute.internal","search":["us-west-2.compute.internal"]}} } ----- diff --git a/modules/nw-multus-host-device-object.adoc b/modules/nw-multus-host-device-object.adoc deleted file mode 100644 index 73b1887182a8..000000000000 --- a/modules/nw-multus-host-device-object.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-host-device.adoc - -[id="nw-multus-host-device-object_{context}"] -= Configuration for host-device - -The configuration for an additional network attachment that uses the host-device -Container Network Interface (CNI) plug-in is provided in two parts: - -* Cluster Network Operator (CNO) configuration -* CNI plug-in configuration - -The CNO configuration specifies the name for the additional network attachment -and the namespace to create the attachment in. The plug-in -is configured by a JSON object specified by the `rawCNIConfig` parameter in -the CNO configuration. - -The following YAML describes the configuration parameters for the CNO: - -.Cluster Network Operator YAML configuration -[source,yaml] ----- -name: <name> <1> -namespace: <namespace> <2> -rawCNIConfig: '{ <3> - ... -}' -type: Raw ----- -<1> Specify a name for the additional network attachment that you are -creating. The name must be unique within the specified `namespace`. - -<2> Specify the namespace to create the network attachment in. If -you do not specify a value, the `default` namespace is used. - -<3> Specify the CNI plug-in configuration in JSON format, which -is based on the following template. - -IMPORTANT: Specify your network device by setting only one of the -following parameters: `device`, `hwaddr`, `kernelpath`, or `pciBusID`. - -The following object describes the configuration parameters for the host-device CNI -plug-in: - -// containernetworking/plugins/.../host-device.go#L50 -.host-device CNI plug-in JSON configuration object -[source,json] ----- -{ - "cniVersion": "0.3.1", - "name": "<name>", <1> - "type": "host-device", - "device": "<device>", <2> - "hwaddr": "<hwaddr>", <3> - "kernelpath": "<kernelpath>", <4> - "pciBusID": "<pciBusID>", <5> - "ipam": { <6> - ... - } -} ----- -<1> Specify the value for the `name` parameter you provided previously for -the CNO configuration. - -<2> Specify the name of the device, such as `eth0`. - -<3> Specify the device hardware MAC address. - -<4> Specify the Linux kernel device path, such as -`/sys/devices/pci0000:00/0000:00:1f.6`. - -<5> Specify the PCI address of the network device, such as `0000:00:1f.6`. - -<6> Specify a configuration object for the ipam CNI plug-in. The plug-in -manages IP address assignment for the attachment definition. - -[id="nw-multus-hostdev-config-example_{context}"] -== host-device configuration example - -The following example configures an additional network named `hostdev-net`: - -[source,yaml] ----- -name: hostdev-net -namespace: work-network -type: Raw -rawCNIConfig: '{ <1> - "cniVersion": "0.3.1", - "name": "work-network", - "type": "host-device", - "device": "eth1", - "ipam": { - "type": "dhcp" - } -}' ----- -<1> The CNI configuration object is specified as a YAML string. diff --git a/modules/nw-multus-ipam-object.adoc b/modules/nw-multus-ipam-object.adoc deleted file mode 100644 index 28ab9de853c3..000000000000 --- a/modules/nw-multus-ipam-object.adoc +++ /dev/null @@ -1,359 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-macvlan.adoc -// * networking/multiple_networks/configuring-ipvlan.adoc -// * networking/multiple_networks/configuring-bridge.adoc -// * networking/multiple_networks/configuring-host-device.adoc -// * networking/hardware_networks/configuring-sriov-net-attach.adoc -// * virt/virtual_machines/vm_networking/virt-defining-an-sriov-network.adoc - -// Because the Cluster Network Operator abstracts the configuration for -// Macvlan, including IPAM configuration, this must be provided as YAML -// for the Macvlan CNI plug-in only. In the future other Multus plug-ins -// might be managed the same way by the CNO. - -ifeval::["{context}" == "configuring-macvlan-basic"] -:yaml: -endif::[] -ifeval::["{context}" != "configuring-macvlan-basic"] -:json: -endif::[] -ifeval::["{context}" == "configuring-sriov-net-attach"] -:sr-iov: -endif::[] - -[id="nw-multus-ipam-object_{context}"] -= Configuration for ipam CNI plug-in - -The ipam Container Network Interface (CNI) plug-in provides IP address management (IPAM) for other CNI plug-ins. - -ifdef::json[] -You can use the following methods for IP address assignment: - -- Static assignment. -- Dynamic assignment through a DHCP server. The DHCP server you specify must be reachable from the additional network. -- Dynamic assignment through the Whereabouts IPAM CNI plug-in. -endif::json[] - -ifdef::yaml[] -The following YAML configuration describes the parameters that you can set. -endif::yaml[] - -//// -IMPORTANT: If you set the `type` parameter to the `DHCP` value, you cannot set -any other parameters. -//// - -ifdef::json[] -[id="nw-multus-static_{context}"] -== Static IP address assignment configuration - -The following JSON describes the configuration for static IP address assignment: - -.Static assignment configuration -[source,json] ----- -{ - "ipam": { - "type": "static", - "addresses": [ <1> - { - "address": "<address>", <2> - "gateway": "<gateway>" <3> - } - ], - "routes": [ <4> - { - "dst": "<dst>", <5> - "gw": "<gw>" <6> - } - ], - "dns": { <7> - "nameservers": ["<nameserver>"], <8> - "domain": "<domain>", <9> - "search": ["<search_domain>"] <10> - } - } -} ----- -<1> An array describing IP addresses to assign to the virtual interface. Both -IPv4 and IPv6 IP addresses are supported. - -<2> An IP address and network prefix that you specify. For example, if you specify `10.10.21.10/24`, then the additional network is assigned an IP address of `10.10.21.10` and the netmask is `255.255.255.0`. - -<3> The default gateway to route egress network traffic to. - -<4> An array describing routes to configure inside the pod. - -<5> The IP address range in CIDR format, such as `192.168.17.0/24`, or `0.0.0.0/0` for the default route. - -<6> The gateway where network traffic is routed. - -<7> Optional: DNS configuration. - -<8> An of array of one or more IP addresses for to send DNS queries to. - -<9> The default domain to append to a host name. For example, if the -domain is set to `example.com`, a DNS lookup query for `example-host` is -rewritten as `example-host.example.com`. - -<10> An array of domain names to append to an unqualified host name, -such as `example-host`, during a DNS lookup query. - -[id="nw-multus-dhcp_{context}"] -== Dynamic IP address assignment configuration - -The following JSON describes the configuration for dynamic IP address address assignment with DHCP. - -.Renewal of DHCP leases -[IMPORTANT] -==== -A pod obtains its original DHCP lease when it is created. The lease must be periodically renewed by a minimal DHCP server deployment running on the cluster. - -ifdef::sr-iov[] -The SR-IOV Network Operator does not create a DHCP server deployment; The Cluster Network Operator is responsible for creating the minimal DHCP server deployment. -endif::sr-iov[] - -To trigger the deployment of the DHCP server, you must create a shim network attachment by editing the Cluster Network Operator configuration, as in the following example: - -.Example shim network attachment definition -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - ... - additionalNetworks: - - name: dhcp-shim - namespace: default - type: Raw - rawCNIConfig: |- - { - "name": "dhcp-shim", - "cniVersion": "0.3.1", - "type": "bridge", - "ipam": { - "type": "dhcp" - } - } ----- -==== - -.DHCP assignment configuration -[source,json] ----- -{ - "ipam": { - "type": "dhcp" - } -} ----- - -[id="nw-multus-whereabouts_{context}"] -== Dynamic IP address assignment configuration with Whereabouts - -The Whereabouts CNI plug-in allows the dynamic assignment of an IP address to an additional network without the use of a DHCP server. - -The following JSON describes the configuration for dynamic IP address assignment with Whereabouts: - -.Whereabouts assignment configuration -[source,json] ----- -{ - "ipam": { - "type": "whereabouts", - "range": "<range>", <1> - "exclude": ["<exclude_part>, ..."], <2> - } -} ----- -<1> Specify an IP address and range in CIDR notation. IP addresses are assigned from within this range of addresses. -<2> Optional: Specify a list of IP addresses and ranges in CIDR notation. IP addresses within an excluded address range are not assigned. - -//// -[NOTE] -===== -Whereabouts can be used for both IPv4 and IPv6 addresses. -===== -//// - -[id="nw-multus-static-example_{context}"] -== Static IP address assignment configuration example - -You can configure ipam for static IP address assignment: - -[source,json] ----- -{ - "ipam": { - "type": "static", - "addresses": [ - { - "address": "191.168.1.7" - } - ] - } -} ----- - -[id="nw-multus-dhcp-example_{context}"] -== Dynamic IP address assignment configuration example using DHCP - -You can configure ipam for DHCP: - -[source,json] ----- -{ - "ipam": { - "type": "dhcp" - } -} ----- - -[id="nw-multus-whereabouts-example_{context}"] -== Dynamic IP address assignment configuration example using Whereabouts - -You can configure ipam to use Whereabouts: - -[source,json] ----- -{ - "ipam": { - "type": "whereabouts", - "range": "192.0.2.192/27", - "exclude": [ - "192.0.2.192/30", - "192.0.2.196/32" - ] - } -} ----- -endif::json[] - -// YAML configuration is only relevant to `simpleMacvlanConfig` -// This is limited by the fields that the CNO accepts - -ifdef::yaml[] -.ipam CNI plug-in YAML configuration object -[source,yaml] ----- -ipamConfig: - type: <type> <1> - ... <2> ----- -<1> Specify `static` to configure the plug-in to manage IP address assignment. -Specify `DHCP` to allow a DHCP server to manage IP address assignment. You -cannot specify any additional parameters if you specify a value of `DHCP`. - -<2> If you set the `type` parameter to `static`, then provide the -`staticIPAMConfig` parameter. - -[id="nw-multus-static-config_{context}"] -== Static ipam configuration YAML - -The following YAML describes a configuration for static IP address assignment: - -.Static ipam configuration YAML -[source,yaml] ----- -ipamConfig: - type: static - staticIPAMConfig: - addresses: <1> - - address: <address> <2> - gateway: <gateway> <3> - routes: <4> - - destination: <destination> <5> - gateway: <gateway> <6> - dns: <7> - nameservers: <8> - - <nameserver> - domain: <domain> <9> - search: <10> - - <search_domain> ----- -<1> A collection of mappings that define IP addresses to assign to the virtual -interface. Both IPv4 and IPv6 IP addresses are supported. - -<2> An IP address and network prefix that you specify. For example, if you specify `10.10.21.10/24`, then the additional network is assigned an IP address of `10.10.21.10` and the netmask is `255.255.255.0`. - -<3> The default gateway to route egress network traffic to. - -<4> A collection of mappings describing routes to configure inside the pod. - -<5> The IP address range in CIDR format, such as `192.168.17.0/24`, or `0.0.0.0/0` for the default route. - -<6> The gateway where network traffic is routed. - -<7> Optional: The DNS configuration. - -<8> A collection of one or more IP addresses for to send DNS queries to. - -<9> The default domain to append to a host name. For example, if the -domain is set to `example.com`, a DNS lookup query for `example-host` is -rewritten as `example-host.example.com`. - -<10> An array of domain names to append to an unqualified host name, -such as `example-host`, during a DNS lookup query. - -[id="nw-multus-dynamic-config_{context}"] -== Dynamic ipam configuration YAML - -The following YAML describes a configuration for static IP address assignment: - -.Dynamic ipam configuration YAML -[source,yaml] ----- -ipamConfig: - type: DHCP ----- - -[id="nw-multus-static-example-yaml_{context}"] -== Static IP address assignment configuration example - -The following example shows an ipam configuration for static IP addresses: - -[source,yaml] ----- -ipamConfig: - type: static - staticIPAMConfig: - addresses: - - address: 198.51.100.11/24 - gateway: 198.51.100.10 - routes: - - destination: 0.0.0.0/0 - gateway: 198.51.100.1 - dns: - nameservers: - - 198.51.100.1 - - 198.51.100.2 - domain: testDNS.example - search: - - testdomain1.example - - testdomain2.example ----- - -[id="nw-multus-dynamic-example-yaml_{context}"] -== Dynamic IP address assignment configuration example - -The following example shows an ipam configuration for DHCP: - -[source,yaml] ----- -ipamConfig: - type: DHCP ----- -endif::yaml[] - -ifeval::["{context}" == "configuring-macvlan-basic"] -:!yaml: -endif::[] -ifeval::["{context}" != "configuring-macvlan-basic"] -:!json: -endif::[] -ifeval::["{context}" == "configuring-sriov-net-attach"] -:!sr-iov: -endif::[] diff --git a/modules/nw-multus-ipvlan-object.adoc b/modules/nw-multus-ipvlan-object.adoc deleted file mode 100644 index 23acb615f7b5..000000000000 --- a/modules/nw-multus-ipvlan-object.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-ipvlan.adoc - -[id="nw-multus-ipvlan-object_{context}"] -= Configuration for ipvlan - -The configuration for an additional network attachment that uses the ipvlan -Container Network Interface (CNI) plug-in is provided in two parts: - -* Cluster Network Operator (CNO) configuration -* CNI plug-in configuration - -The CNO configuration specifies the name for the additional network attachment -and the namespace to create the attachment in. The plug-in -is configured by a JSON object specified by the `rawCNIConfig` parameter in -the CNO configuration. - -The following YAML describes the configuration parameters for the CNO: - -.Cluster Network Operator YAML configuration -[source,yaml] ----- -name: <name> <1> -namespace: <namespace> <2> -rawCNIConfig: '{ <3> - ... -}' -type: Raw ----- -<1> Specify a name for the additional network attachment that you are -creating. The name must be unique within the specified `namespace`. - -<2> Specify the namespace to create the network attachment in. If -you do not specify a value, then the `default` namespace is used. - -<3> Specify the CNI plug-in configuration in JSON format, which -is based on the following template. - -The following object describes the configuration parameters for the ipvlan CNI -plug-in: - -.ipvlan CNI plug-in JSON configuration object -[source,json] ----- -{ - "cniVersion": "0.3.1", - "name": "<name>", <1> - "type": "ipvlan", - "mode": "<mode>", <2> - "master": "<master>", <3> - "mtu": <mtu>, <4> - "ipam": { <5> - ... - } -} ----- -<1> Specify the value for the `name` parameter you provided previously for -the CNO configuration. - -<2> Specify the operating mode for the virtual network. The value must -be `l2`, `l3`, or `l3s`. The default value is `l2`. - -<3> Specify the ethernet interface to associate with the network -attachment. If a `master` is not specified, the interface for the default -network route is used. - -<4> Set the maximum transmission unit (MTU) to the specified value. The -default value is automatically set by the kernel. - -<5> Specify a configuration object for the ipam CNI plug-in. The plug-in -manages IP address assignment for the attachment definition. - -[id="nw-multus-ipvlan-config-example_{context}"] -== ipvlan configuration example - -The following example configures an additional network named `ipvlan-net`: - -[source,yaml] ----- -name: ipvlan-net -namespace: work-network -type: Raw -rawCNIConfig: '{ <1> - "cniVersion": "0.3.1", - "name": "work-network", - "type": "ipvlan", - "master": "eth1", - "mode": "l3", - "ipam": { - "type": "dhcp" - } -}' ----- -<1> The CNI configuration object is specified as a YAML string. diff --git a/modules/nw-multus-macvlan-object.adoc b/modules/nw-multus-macvlan-object.adoc deleted file mode 100644 index 966c03dcef29..000000000000 --- a/modules/nw-multus-macvlan-object.adoc +++ /dev/null @@ -1,161 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-macvlan.adoc - -ifeval::["{context}" == "configuring-macvlan-basic"] -:yaml: -endif::[] -// This is necessary for Whereabouts CNI which is JSON-only -ifeval::["{context}" == "configuring-macvlan"] -:json: -endif::[] - -// Content duplicated because the callouts are identical -// and must be changed simultaneously if edited. The numbers -// do not easily line up, so the content is duplicated in each section. - -[id="nw-multus-macvlan-object_{context}"] -= Configuration for macvlan CNI plug-in - -ifdef::json[] -The configuration for an additional network attachment that uses the macvlan -Container Network Interface (CNI) plug-in is provided in two parts: - -* Cluster Network Operator (CNO) configuration -* CNI plug-in configuration - -The CNO configuration specifies the name for the additional network attachment -and the namespace to create the attachment in. The plug-in -is configured by a JSON object specified by the `rawCNIConfig` parameter in -the CNO configuration. - -The following YAML describes the configuration parameters for the CNO: - -.Cluster Network Operator YAML configuration -[source,yaml] ----- -name: <name> <1> -namespace: <namespace> <2> -rawCNIConfig: '{ <3> - ... -}' -type: Raw ----- -<1> Specify a name for the additional network attachment that you are -creating. The name must be unique within the specified `namespace`. - -<2> Specify the namespace to create the network attachment in. If -you do not specify a value, then the `default` namespace is used. - -<3> Specify the CNI plug-in configuration in JSON format, which -is based on the following template. - -The following object describes the configuration parameters for the macvlan CNI -plug-in: - -.macvlan CNI plug-in JSON configuration object -[source,json] ----- -{ - "cniVersion": "0.3.1", - "name": "<name>", <1> - "type": "macvlan", - "mode": "<mode>", <2> - "master": "<master>", <3> - "mtu": <mtu>, <4> - "ipam": { <5> - ... - } -} ----- -<1> Specify a name for the additional network attachment that you are creating. The name must be unique within the specified `namespace`. - -<2> Configures traffic visibility on the virtual network. Must be either `bridge`, `passthru`, `private`, or `vepa`. If a value is not provided, the default value is `bridge`. - -<3> The ethernet interface to associate with the virtual interface. If a value is not specified, then the host system's primary ethernet interface is used. - -<4> Set the maximum transmission unit (MTU) to the specified value. The default value is automatically set by the kernel. - -<5> Specify a configuration object for the ipam CNI plug-in. The plug-in manages IP address assignment for the attachment definition. -endif::json[] - -ifdef::yaml[] -The following YAML describes the configuration parameters for the macvlan -Container Network Interface (CNI) plug-in: - -.macvlan YAML configuration -[source,yaml] ----- -name: <name> <1> -namespace: <namespace> <2> -type: SimpleMacvlan -simpleMacvlanConfig: - master: <master> <3> - mode: <mode> <4> - mtu: <mtu> <5> - ipamConfig: <6> - ... ----- -<1> Specify a name for the additional network attachment that you are -creating. The name must be unique within the specified `namespace`. - -<2> Specify the namespace to create the network attachment in. If -a value is not specified, the `default` namespace is used. - -<3> The ethernet interface to associate with the virtual interface. If -a value for `master` is not specified, then the host system's primary ethernet -interface is used. - -<4> Configures traffic visibility on the virtual network. Must be either -`bridge`, `passthru`, `private`, or `vepa`. If a value for `mode` is not -provided, the default value is `bridge`. - -<5> Set the maximum transmission unit (MTU) to the specified value. The -default value is automatically set by the kernel. - -<6> Specify a configuration object for the ipam CNI plug-in. The -plug-in manages IP address assignment for the attachment definition. -endif::yaml[] - -[id="nw-multus-macvlan-config-example_{context}"] -== macvlan configuration example - -The following example configures an additional network named `macvlan-net`: - -ifdef::yaml[] -[source,yaml] ----- -name: macvlan-net -namespace: work-network -type: SimpleMacvlan -simpleMacvlanConfig: - ipamConfig: - type: DHCP ----- -endif::yaml[] -ifdef::json[] -[source,yaml] ----- -name: macvlan-net -namespace: work-network -type: Raw -rawCNIConfig: |- - { - "cniVersion": "0.3.1", - "name": "macvlan-net", - "type": "macvlan", - "master": "eth1", - "mode": "bridge", - "ipam": { - "type": "dhcp" - } - } ----- -endif::json[] - -ifeval::["{context}" == "configuring-macvlan-basic"] -:!yaml: -endif::[] -ifeval::["{context}" == "configuring-macvlan"] -:!json: -endif::[] diff --git a/modules/nw-multus-remove-pod.adoc b/modules/nw-multus-remove-pod.adoc deleted file mode 100644 index ae7985ae73a0..000000000000 --- a/modules/nw-multus-remove-pod.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/removing-pod.adoc - -[id="nw-multus-remove-pod_{context}"] -= Removing a pod from an additional network - -You can remove a pod from an additional network only by deleting the pod. - -.Prerequisites - -* An additional network is attached to the pod. -* Install the OpenShift CLI (`oc`). -* Log in to the cluster. - -.Procedure - -* To delete the pod, enter the following command: -+ -[source,terminal] ----- -$ oc delete pod <name> -n <namespace> ----- -+ --- -* `<name>` is the name of the pod. -* `<namespace>` is the namespace that contains the pod. --- diff --git a/modules/nw-ne-openshift-dns.adoc b/modules/nw-ne-openshift-dns.adoc deleted file mode 100644 index 3bf03d6c308f..000000000000 --- a/modules/nw-ne-openshift-dns.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// * understanding-networking.adoc - - -[id="nw-ne-openshift-dns_{context}"] -= {product-title} DNS - -If you are running multiple services, such as front-end and back-end services for -use with multiple pods, environment variables are created for user names, -service IPs, and more so the front-end pods can communicate with the back-end -services. If the service is deleted and recreated, a new IP address can be -assigned to the service, and requires the front-end pods to be recreated to pick -up the updated values for the service IP environment variable. Additionally, the -back-end service must be created before any of the front-end pods to ensure that -the service IP is generated properly, and that it can be provided to the -front-end pods as an environment variable. - -For this reason, {product-title} has a built-in DNS so that the services can be -reached by the service DNS as well as the service IP/port. diff --git a/modules/nw-networkpolicy-about.adoc b/modules/nw-networkpolicy-about.adoc deleted file mode 100644 index 267e8ff18968..000000000000 --- a/modules/nw-networkpolicy-about.adoc +++ /dev/null @@ -1,139 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/about-network-policy.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="nw-networkpolicy-about_{context}"] -= About network policy - -In a cluster using a Kubernetes Container Network Interface (CNI) plug-in that supports Kubernetes network policy, network isolation is controlled entirely by `NetworkPolicy` objects. -In {product-title} {product-version}, OpenShift SDN supports using network policy in its default network isolation mode. - -[NOTE] -==== -IPBlock is supported by network policy with limitations for OpenShift SDN; it supports IPBlock without except clauses. If you create a policy with an IPBlock section that includes an except clause, the SDN pods log warnings and the entire IPBlock section of that policy is ignored. -==== - -[WARNING] -==== -Network policy does not apply to the host network namespace. Pods with host networking enabled are unaffected by network policy rules. -==== - -By default, all pods in a project are accessible from other pods and network endpoints. To isolate one or more pods in a project, you can create `NetworkPolicy` objects in that project to indicate the allowed incoming connections. Project administrators can create and delete `NetworkPolicy` objects within their own project. - -If a pod is matched by selectors in one or more `NetworkPolicy` objects, then the pod will accept only connections that are allowed by at least one of those `NetworkPolicy` objects. A pod that is not selected by any `NetworkPolicy` objects is fully accessible. - -The following example `NetworkPolicy` objects demonstrate supporting different scenarios: - -* Deny all traffic: -+ -To make a project deny by default, add a `NetworkPolicy` object that matches all pods but accepts no traffic: -+ -[source,yaml] ----- -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: deny-by-default -spec: - podSelector: - ingress: [] ----- - -* Only allow connections from the {product-title} Ingress Controller: -+ -To make a project allow only connections from the {product-title} Ingress Controller, add the following `NetworkPolicy` object. -+ -[IMPORTANT] -==== -For the OVN-Kubernetes network provider plug-in, when the Ingress Controller is configured to use the `HostNetwork` endpoint publishing strategy, there is no supported way to apply network policy so that ingress traffic is allowed and all other traffic is denied. -==== -+ -[source,yaml] ----- -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: allow-from-openshift-ingress -spec: - ingress: - - from: - - namespaceSelector: - matchLabels: - network.openshift.io/policy-group: ingress - podSelector: {} - policyTypes: - - Ingress ----- -+ -If the Ingress Controller is configured with `endpointPublishingStrategy: HostNetwork`, then the Ingress Controller pod runs on the host network. -When running on the host network, the traffic from the Ingress Controller is assigned the `netid:0` Virtual Network ID (VNID). -The `netid` for the namespace that is associated with the Ingress Operator is different, so the `matchLabel` in the `allow-from-openshift-ingress` network policy does not match traffic from the `default` Ingress Controller. -With OpenShift SDN, the `default` namespace is assigned the `netid:0` VNID and you can allow traffic from the `default` Ingress Controller by labeling your `default` namespace with `network.openshift.io/policy-group: ingress`. - -* Only accept connections from pods within a project: -+ -To make pods accept connections from other pods in the same project, but reject all other connections from pods in other projects, add the following `NetworkPolicy` object: -+ -[source,yaml] ----- -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: allow-same-namespace -spec: - podSelector: - ingress: - - from: - - podSelector: {} ----- - -* Only allow HTTP and HTTPS traffic based on pod labels: -+ -To enable only HTTP and HTTPS access to the pods with a specific label (`role=frontend` in following example), add a `NetworkPolicy` object similar to the following: -+ -[source,yaml] ----- -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: allow-http-and-https -spec: - podSelector: - matchLabels: - role: frontend - ingress: - - ports: - - protocol: TCP - port: 80 - - protocol: TCP - port: 443 ----- - -* Accept connections by using both namespace and pod selectors: -+ -To match network traffic by combining namespace and pod selectors, you can use a `NetworkPolicy` object similar to the following: -+ -[source,yaml] ----- -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: allow-pod-and-namespace-both -spec: - podSelector: - matchLabels: - name: test-pods - ingress: - - from: - - namespaceSelector: - matchLabels: - project: project_name - podSelector: - matchLabels: - name: test-pods ----- - -`NetworkPolicy` objects are additive, which means you can combine multiple `NetworkPolicy` objects together to satisfy complex network requirements. - -For example, for the `NetworkPolicy` objects defined in previous samples, you can define both `allow-same-namespace` and `allow-http-and-https` policies within the same project. Thus allowing the pods with the label `role=frontend`, to accept any connection allowed by each policy. That is, connections on any port from pods in the same namespace, and connections on ports `80` and `443` from pods in any namespace. diff --git a/modules/nw-networkpolicy-create.adoc b/modules/nw-networkpolicy-create.adoc deleted file mode 100644 index 99d204e2e28e..000000000000 --- a/modules/nw-networkpolicy-create.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/creating-network-policy.adoc -// * networking/configuring-networkpolicy.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="nw-networkpolicy-create_{context}"] - -= Creating a network policy - -To define granular rules describing ingress network traffic allowed for projects -in your cluster, you can create a network policy. - -.Prerequisites - -* Your cluster is using a default CNI network provider that supports `NetworkPolicy` objects, such as the OpenShift SDN network provider with `mode: NetworkPolicy` set. This mode is the default for OpenShift SDN. -* You installed the OpenShift CLI (`oc`). -* You are logged in to the cluster with a user with `cluster-admin` privileges. - -.Procedure - -. Create a policy rule: -.. Create a `<policy-name>.yaml` file where `<policy-name>` describes the policy -rule. -.. In the file you just created define a policy object, such as in the following -example: -+ -[source,yaml] ----- -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: <policy-name> <1> -spec: - podSelector: - ingress: [] ----- -<1> Specify a name for the policy object. - -. Run the following command to create the policy object: -+ -[source,terminal] ----- -$ oc create -f <policy-name>.yaml -n <project> ----- -+ -In the following example, a new `NetworkPolicy` object is created in a project -named `project1`: -+ -[source,terminal] ----- -$ oc create -f default-deny.yaml -n project1 ----- -+ -.Example output -[source,terminal] ----- -networkpolicy "default-deny" created ----- diff --git a/modules/nw-networkpolicy-delete.adoc b/modules/nw-networkpolicy-delete.adoc deleted file mode 100644 index 7798f064f749..000000000000 --- a/modules/nw-networkpolicy-delete.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/deleting-network-policy.adoc -// * networking/configuring-networkpolicy.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="nw-networkpolicy-delete_{context}"] - -= Deleting a network policy - -You can delete a network policy. - -.Prerequisites - -* You installed the OpenShift CLI (`oc`). -* You are logged in to the cluster with a user with `cluster-admin` privileges. - -.Procedure - -* To delete a `NetworkPolicy` object, enter the following command. Replace `<policy-name>` with the name of the object. -+ -[source,terminal] ----- -$ oc delete networkpolicy <policy-name> ----- diff --git a/modules/nw-networkpolicy-edit.adoc b/modules/nw-networkpolicy-edit.adoc deleted file mode 100644 index 511b7ae04f70..000000000000 --- a/modules/nw-networkpolicy-edit.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/editing-network-policy.adoc - -[id="nw-networkpolicy-edit_{context}"] - -= Editing a network policy - -You can edit a network policy in a namespace. - -.Prerequisites - -* Your cluster is using a default CNI network provider that supports `NetworkPolicy` objects, such as the OpenShift SDN network provider with `mode: NetworkPolicy` set. This mode is the default for OpenShift SDN. -* You installed the OpenShift CLI (`oc`). -* You are logged in to the cluster with a user with `cluster-admin` privileges. - -.Procedure - -. Optional: List the current `NetworkPolicy` objects. -.. If you want to list the policy objects in a specific namespace, enter the following command. Replace `<namespace>` with the namespace for a project. -+ -[source,terminal] ----- -$ oc get networkpolicy -n <namespace> ----- - -.. If you want to list the policy objects for the entire cluster, enter the following command: -+ -[source,terminal] ----- -$ oc get networkpolicy --all-namespaces ----- - -. Edit the `NetworkPolicy` object. - -.. If you saved the network policy definition in a file, edit the file and make any necessary changes, and then enter the following command. Replace `<policy-file>` with the name of the file containing the object definition. -+ -[source,terminal] ----- -$ oc apply -f <policy-file>.yaml ----- - -.. If you need to update the `NetworkPolicy` object directly, you can enter the following command. Replace `<policy-name>` with the name of the `NetworkPolicy` object and `<namespace>` with the name of the project where the object exists. -+ -[source,terminal] ----- -$ oc edit <policy-name> -n <namespace> ----- - -. Confirm that the `NetworkPolicy` object is updated. Replace `<namespace>` with the name of the project where the object exists. -+ -[source,terminal] ----- -$ oc get networkpolicy -n <namespace> -o yaml ----- diff --git a/modules/nw-networkpolicy-multitenant-isolation.adoc b/modules/nw-networkpolicy-multitenant-isolation.adoc deleted file mode 100644 index 85592278584a..000000000000 --- a/modules/nw-networkpolicy-multitenant-isolation.adoc +++ /dev/null @@ -1,151 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/multitenant-network-policy.adoc -// * networking/configuring-networkpolicy.adoc -// * post_installation_configuration/network-configuration.adoc - -ifeval::[{product-version} >= 4.6] -:ovn: -endif::[] - -[id="nw-networkpolicy-multitenant-isolation_{context}"] -= Configuring multitenant isolation by using network policy - -You can configure your project to isolate it from pods and services in other -project namespaces. - -.Prerequisites - -* Your cluster is using a cluster network provider that supports `NetworkPolicy` objects, such as -ifndef::ovn[] -the OpenShift SDN network provider with `mode: NetworkPolicy` set. -endif::ovn[] -ifdef::ovn[] -the OVN-Kubernetes network provider or the OpenShift SDN network provider with `mode: NetworkPolicy` set. -endif::ovn[] -This mode is the default for OpenShift SDN. -* You installed the OpenShift CLI (`oc`). -* You are logged in to the cluster with a user with `cluster-admin` privileges. - -.Procedure - -. Create the following `NetworkPolicy` objects: -.. A policy named `allow-from-openshift-ingress`. -+ -[IMPORTANT] -==== -For the OVN-Kubernetes network provider plug-in, when the Ingress Controller is configured to use the `HostNetwork` endpoint publishing strategy, there is no supported way to apply network policy so that ingress traffic is allowed and all other traffic is denied. -==== -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: allow-from-openshift-ingress -spec: - ingress: - - from: - - namespaceSelector: - matchLabels: - network.openshift.io/policy-group: ingress - podSelector: {} - policyTypes: - - Ingress -EOF ----- - -.. A policy named `allow-from-openshift-monitoring`: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: allow-from-openshift-monitoring -spec: - ingress: - - from: - - namespaceSelector: - matchLabels: - network.openshift.io/policy-group: monitoring - podSelector: {} - policyTypes: - - Ingress -EOF ----- - -.. A policy named `allow-same-namespace`: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: allow-same-namespace -spec: - podSelector: - ingress: - - from: - - podSelector: {} -EOF ----- - -. If the `default` Ingress Controller configuration has the `spec.endpointPublishingStrategy: HostNetwork` value set, you must apply a label to the `default` {product-title} namespace to allow network traffic between the Ingress Controller and the project: - -.. Determine if your `default` Ingress Controller uses the `HostNetwork` endpoint publishing strategy: -+ -[source,terminal] ----- -$ oc get --namespace openshift-ingress-operator ingresscontrollers/default \ - --output jsonpath='{.status.endpointPublishingStrategy.type}' ----- - -.. If the previous command reports the endpoint publishing strategy as `HostNetwork`, set a label on the `default` namespace: -+ -[source,terminal] ----- -$ oc label namespace default 'network.openshift.io/policy-group=ingress' ----- - -. Confirm that the `NetworkPolicy` object exists in your current project -by running the following command: -+ -[source,terminal] ----- -$ oc get networkpolicy <policy-name> -o yaml ----- -+ -In the following example, the `allow-from-openshift-ingress` `NetworkPolicy` -object is displayed: -+ -[source,terminal] ----- -$ oc get -n project1 networkpolicy allow-from-openshift-ingress -o yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: allow-from-openshift-ingress - namespace: project1 -spec: - ingress: - - from: - - namespaceSelector: - matchLabels: - network.openshift.io/policy-group: ingress - podSelector: {} - policyTypes: - - Ingress ----- - -ifdef::ovn[] -:!ovn: -endif::ovn[] diff --git a/modules/nw-networkpolicy-object.adoc b/modules/nw-networkpolicy-object.adoc deleted file mode 100644 index b3d9ea1f41bd..000000000000 --- a/modules/nw-networkpolicy-object.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/creating-network-policy.adoc -// * networking/network_policy/viewing-network-policy.adoc -// * networking/network_policy/editing-network-policy.adoc -// * networking/configuring-networkpolicy.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="nw-networkpolicy-object_{context}"] - -= Example NetworkPolicy object - -The following annotates an example NetworkPolicy object: - -[source,yaml] ----- -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: allow-27107 <1> -spec: - podSelector: <2> - matchLabels: - app: mongodb - ingress: - - from: - - podSelector: <3> - matchLabels: - app: app - ports: <4> - - protocol: TCP - port: 27017 ----- -<1> The `name` of the NetworkPolicy object. -<2> A selector describing the pods the policy applies to. The policy object can -only select pods in the project that the NetworkPolicy object is defined. -<3> A selector matching the pods that the policy object allows ingress traffic -from. The selector will match pods in any project. -<4> A list of one or more destination ports to accept traffic on. diff --git a/modules/nw-networkpolicy-optimize.adoc b/modules/nw-networkpolicy-optimize.adoc deleted file mode 100644 index ff0c917f1d1b..000000000000 --- a/modules/nw-networkpolicy-optimize.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/about-network-policy.adoc - -[id="nw-networkpolicy-optimize_{context}"] -= Optimizations for network policy - -Use a network policy to isolate pods that are differentiated from one another by labels within a namespace. - -[NOTE] -==== -The guidelines for efficient use of network policy rules applies to only the OpenShift SDN cluster network provider. -==== - -It is inefficient to apply `NetworkPolicy` objects to large numbers of individual pods in a single namespace. Pod labels do not exist at the IP address level, so a network policy generates a separate Open vSwitch (OVS) flow rule for every possible link between every pod selected with a `podSelector`. - -For example, if the spec `podSelector` and the ingress `podSelector` within a `NetworkPolicy` object each match 200 pods, then 40,000 (200*200) OVS flow rules are generated. This might slow down a node. - -When designing your network policy, refer to the following guidelines: - -* Reduce the number of OVS flow rules by using namespaces to contain groups of pods that need to be isolated. -+ -`NetworkPolicy` objects that select a whole namespace, by using the `namespaceSelector` or an empty `podSelector`, generate only a single OVS flow rule that matches the VXLAN virtual network ID (VNID) of the namespace. - -* Keep the pods that do not need to be isolated in their original namespace, and move the pods that require isolation into one or more different namespaces. - -* Create additional targeted cross-namespace network policies to allow the specific traffic that you do want to allow from the isolated pods. diff --git a/modules/nw-networkpolicy-project-defaults.adoc b/modules/nw-networkpolicy-project-defaults.adoc deleted file mode 100644 index 04dc8235a82c..000000000000 --- a/modules/nw-networkpolicy-project-defaults.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/default-network-policy.adoc -// * networking/configuring-networkpolicy.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="nw-networkpolicy-project-defaults_{context}"] -= Adding network policies to the new project template - -As a cluster administrator, you can add network policies to the default template for new projects. -{product-title} will automatically create all the `NetworkPolicy` objects specified in the template in the project. - -.Prerequisites - -* Your cluster is using a default CNI network provider that supports `NetworkPolicy` objects, such as the OpenShift SDN network provider with `mode: NetworkPolicy` set. This mode is the default for OpenShift SDN. -* You installed the OpenShift CLI (`oc`). -* You must log in to the cluster with a user with `cluster-admin` privileges. -* You must have created a custom default project template for new projects. - -.Procedure - -. Edit the default template for a new project by running the following command: -+ -[source,terminal] ----- -$ oc edit template <project_template> -n openshift-config ----- -+ -Replace `<project_template>` with the name of the default template that you -configured for your cluster. The default template name is `project-request`. - -. In the template, add each `NetworkPolicy` object as an element to the `objects` parameter. The `objects` parameter accepts a collection of one or more objects. -+ -In the following example, the `objects` parameter collection includes several `NetworkPolicy` objects. -+ -[IMPORTANT] -==== -For the OVN-Kubernetes network provider plug-in, when the Ingress Controller is configured to use the `HostNetwork` endpoint publishing strategy, there is no supported way to apply network policy so that ingress traffic is allowed and all other traffic is denied. -==== -+ -[source,yaml] ----- -objects: -- apiVersion: networking.k8s.io/v1 - kind: NetworkPolicy - metadata: - name: allow-from-same-namespace - spec: - podSelector: - ingress: - - from: - - podSelector: {} -- apiVersion: networking.k8s.io/v1 - kind: NetworkPolicy - metadata: - name: allow-from-openshift-ingress - spec: - ingress: - - from: - - namespaceSelector: - matchLabels: - network.openshift.io/policy-group: ingress - podSelector: {} - policyTypes: - - Ingress -... ----- - -. Optional: Create a new project to confirm that your network policy objects are created successfully by running the following commands: - -.. Create a new project: -+ -[source,terminal] ----- -$ oc new-project <project> <1> ----- -<1> Replace `<project>` with the name for the project you are creating. - -.. Confirm that the network policy objects in the new project template exist in the new project: -+ -[source,terminal] ----- -$ oc get networkpolicy -NAME POD-SELECTOR AGE -allow-from-openshift-ingress <none> 7s -allow-from-same-namespace <none> 7s ----- diff --git a/modules/nw-networkpolicy-view.adoc b/modules/nw-networkpolicy-view.adoc deleted file mode 100644 index 8c6230e0eee8..000000000000 --- a/modules/nw-networkpolicy-view.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/network_policy/viewing-network-policy.adoc -// * networking/configuring-networkpolicy.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="nw-networkpolicy-view_{context}"] -= Viewing network policies - -You can list the network policies in your cluster. - -.Prerequisites - -* You installed the OpenShift CLI (`oc`). -* You are logged in to the cluster with a user with `cluster-admin` privileges. - -.Procedure - -* To view `NetworkPolicy` objects defined in your cluster, run the following -command: -+ -[source,terminal] ----- -$ oc get networkpolicy ----- diff --git a/modules/nw-nodeport-service-range-edit.adoc b/modules/nw-nodeport-service-range-edit.adoc deleted file mode 100644 index 4ec23670ae1a..000000000000 --- a/modules/nw-nodeport-service-range-edit.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring-node-port-service-range.adoc - -[id="nw-nodeport-service-range-edit_{context}"] -= Expanding the node port range - -You can expand the node port range for the cluster. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in to the cluster with a user with `cluster-admin` privileges. - -.Procedure - -. To expand the node port range, enter the following command. Replace `<port>` with the largest port number in the new range. -+ -[source,terminal] ----- -$ oc patch network.config.openshift.io cluster --type=merge -p \ - '{ - "spec": - { "serviceNodePortRange": "30000-<port>" } - }' ----- -+ -.Example output -[source,terminal] ----- -network.config.openshift.io/cluster patched ----- - -. To confirm that the configuration is active, enter the following command. It can take several minutes for the update to apply. -+ -[source,terminal] ----- -$ oc get configmaps -n openshift-kube-apiserver config \ - -o jsonpath="{.data['config\.yaml']}" | \ - grep -Eo '"service-node-port-range":["[[:digit:]]+-[[:digit:]]+"]' ----- -+ -.Example output -[source,terminal] ----- -"service-node-port-range":["30000-33000"] ----- diff --git a/modules/nw-openshift-sdn-modes.adoc b/modules/nw-openshift-sdn-modes.adoc deleted file mode 100644 index ccb6789635a2..000000000000 --- a/modules/nw-openshift-sdn-modes.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/openshift_sdn/about-openshift-sdn.adoc - -[id="nw-openshift-sdn-modes_{context}"] -= OpenShift SDN network isolation modes - -OpenShift SDN provides three SDN modes for configuring the pod network: - -* _Network policy_ mode allows project administrators to configure their own -isolation policies using `NetworkPolicy` objects. Network policy is the default mode in {product-title} {product-version}. - -* _Multitenant_ mode provides project-level isolation for pods and services. Pods from different projects cannot send packets to or receive packets from pods and services of a different project. You can disable isolation for a project, allowing it to send network traffic to all pods and services in the entire cluster and receive network traffic from those pods and services. - -* _Subnet_ mode provides a flat pod network where every pod can communicate with every other pod and service. The network policy mode provides the same functionality as subnet mode. diff --git a/modules/nw-operator-cr.adoc b/modules/nw-operator-cr.adoc deleted file mode 100644 index f3fdbd644a60..000000000000 --- a/modules/nw-operator-cr.adoc +++ /dev/null @@ -1,278 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/cluster-network-operator.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_azure/installing-azure-network-customizations.adoc -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_gcp/installing-gcp-network-customizations.adoc -// * post_installation_configuration/network-configuration.adoc - -// Installation assemblies need different details than the CNO operator does -ifeval::["{context}" == "cluster-network-operator"] -:operator: -endif::[] - -ifeval::["{context}" == "post-install-network-configuration"] -:post-install-network-configuration: -endif::[] - -[id="nw-operator-cr_{context}"] -= Cluster Network Operator configuration - -The configuration for the cluster network is specified as part of the Cluster Network Operator (CNO) configuration and stored in a custom resource (CR) object that is named `cluster`. The CR specifies the parameters for the `Network` API in the `operator.openshift.io` API group. - -ifdef::post-install-network-configuration[] -[NOTE] -==== -After cluster installation, you cannot modify the configuration for the cluster network provider. -==== -endif::post-install-network-configuration[] -ifndef::post-install-network-configuration[] -You can specify the cluster network configuration for your {product-title} cluster by setting the parameter values for the `defaultNetwork` parameter in the CNO CR. The following CR displays the default configuration for the CNO and explains both the parameters you can configure and the valid parameter values: - -.Cluster Network Operator custom resource -[source,yaml] -ifndef::operator[] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - clusterNetwork: <1> - - cidr: 10.128.0.0/14 - hostPrefix: 23 - serviceNetwork: <1> - - 172.30.0.0/16 - defaultNetwork: <2> - ... - kubeProxyConfig: <3> - iptablesSyncPeriod: 30s <4> - proxyArguments: - iptables-min-sync-period: <5> - - 0s ----- -<1> Specified in the `install-config.yaml` file. - -<2> Configures the default Container Network Interface (CNI) network provider for the cluster network. - -<3> The parameters for this object specify the `kube-proxy` configuration. If you do not specify the parameter values, the Cluster Network Operator applies the displayed default parameter values. If you are using the OVN-Kubernetes default CNI network provider, the kube-proxy configuration has no effect. - -<4> The refresh period for `iptables` rules. The default value is `30s`. Valid suffixes include `s`, `m`, and `h` and are described in the link:https://golang.org/pkg/time/#ParseDuration[Go time package] documentation. -+ -NOTE: Because of performance improvements introduced in {product-title} 4.3 and greater, adjusting the `iptablesSyncPeriod` parameter is no longer necessary. - -<5> The minimum duration before refreshing `iptables` rules. This parameter ensures that the refresh does not happen too frequently. Valid suffixes include `s`, `m`, and `h` and are described in the link:https://golang.org/pkg/time/#ParseDuration[Go time package]. -endif::operator[] - -ifdef::operator[] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - clusterNetwork: <1> - - cidr: 10.128.0.0/14 - hostPrefix: 23 - serviceNetwork: <2> - - 172.30.0.0/16 - defaultNetwork: <3> - ... - kubeProxyConfig: <4> - iptablesSyncPeriod: 30s <5> - proxyArguments: - iptables-min-sync-period: <6> - - 0s ----- -<1> A list specifying the blocks of IP addresses from which pod IP addresses are -allocated and the subnet prefix length assigned to each individual node. - -<2> A block of IP addresses for services. The OpenShift SDN Container Network Interface (CNI) network provider supports only a single IP address block for the service network. - -<3> Configures the default CNI network provider for the cluster network. - -<4> The parameters for this object specify the Kubernetes network proxy (kube-proxy) configuration. If you are using the OVN-Kubernetes default CNI network provider, the kube-proxy configuration has no effect. - -<5> The refresh period for `iptables` rules. The default value is `30s`. Valid suffixes include `s`, `m`, and `h` and are described in the link:https://golang.org/pkg/time/#ParseDuration[Go time package] documentation. -+ -NOTE: Because of performance improvements introduced in {product-title} 4.3 and greater, adjusting the `iptablesSyncPeriod` parameter is no longer necessary. - -<6> The minimum duration before refreshing `iptables` rules. This parameter ensures that the refresh does not happen too frequently. Valid suffixes include `s`, `m`, and `h` and are described in the link:https://golang.org/pkg/time/#ParseDuration[Go time package]. -endif::operator[] - -ifdef::openshift-origin[] -[NOTE] -==== -{product-title} uses the OVN-Kubernetes Container Network Interface (CNI) cluster network provider by default. -==== -endif::openshift-origin[] - -[id="nw-operator-configuration-parameters-for-openshift-sdn_{context}"] -== Configuration parameters for the OpenShift SDN CNI cluster network provider - -The following YAML object describes the configuration parameters for -the OpenShift SDN default Container Network Interface (CNI) network provider. - -ifdef::operator[] -NOTE: You can only change the configuration for your default CNI network provider during cluster installation. -endif::operator[] - -[source,yaml] -ifndef::operator[] ----- -defaultNetwork: - type: OpenShiftSDN <1> - openshiftSDNConfig: <2> - mode: NetworkPolicy <3> - mtu: 1450 <4> - vxlanPort: 4789 <5> ----- -<1> Specified in the `install-config.yaml` file. - -<2> Specify only if you want to override part of the OpenShift SDN -configuration. - -<3> Configures the network isolation mode for OpenShift SDN. The allowed values -are `Multitenant`, `Subnet`, or `NetworkPolicy`. The default value is -`NetworkPolicy`. - -<4> The maximum transmission unit (MTU) for the VXLAN overlay network. This is detected automatically based on the MTU of the primary network interface. You do not normally need to override the detected MTU. -+ -If the auto-detected value is not what you expected it to be, confirm that the MTU on the primary network interface on your nodes is correct. You cannot use this option to change the MTU value of the primary network interface on the nodes. -+ -If your cluster requires different MTU values for different nodes, you must set this value to `50` less than the lowest MTU value in your cluster. For example, if some nodes in your cluster have an MTU of `9001`, and some have an MTU of `1500`, you must set this value to `1450`. - -<5> The port to use for all VXLAN packets. The default value is `4789`. If you -are running in a virtualized environment with existing nodes that are part of -another VXLAN network, then you might be required to change this. For example, -when running an OpenShift SDN overlay on top of VMware NSX-T, you must select an -alternate port for VXLAN, since both SDNs use the same default VXLAN port -number. -+ -On Amazon Web Services (AWS), you can select an alternate port for the VXLAN -between port `9000` and port `9999`. -endif::operator[] - -ifdef::operator[] ----- -defaultNetwork: - type: OpenShiftSDN <1> - openshiftSDNConfig: <2> - mode: NetworkPolicy <3> - mtu: 1450 <4> - vxlanPort: 4789 <5> ----- -<1> The default CNI network provider plug-in that is used. - -<2> OpenShift SDN specific configuration parameters. - -<3> The network isolation mode for OpenShift SDN. - -<4> The maximum transmission unit (MTU) for the VXLAN overlay network. This -value is normally configured automatically. - -<5> The port to use for all VXLAN packets. The default value is `4789`. -endif::operator[] - -[id="nw-operator-configuration-parameters-for-ovn-sdn_{context}"] -== Configuration parameters for the OVN-Kubernetes CNI cluster network provider - -The following YAML object describes the configuration parameters for the OVN-Kubernetes default CNI network provider. - -ifdef::operator[] -NOTE: You can only change the configuration for your default CNI network provider during cluster installation. -endif::operator[] - -[source,yaml] ----- -defaultNetwork: - type: OVNKubernetes <1> - ovnKubernetesConfig: <2> - mtu: 1400 <3> - genevePort: 6081 <4> - ipsecConfig: {} <5> ----- -ifndef::operator[] -<1> Specified in the `install-config.yaml` file. -endif::operator[] - -ifdef::operator[] -<1> The default CNI network provider plug-in that is used. -endif::operator[] - -ifndef::operator[] -<2> Specify only if you want to override part of the OVN-Kubernetes configuration. -endif::operator[] - -ifdef::operator[] -<2> OVN-Kubernetes specific configuration parameters. -endif::operator[] - -ifndef::operator[] -<3> The maximum transmission unit (MTU) for the Geneve (Generic Network Virtualization Encapsulation) overlay network. This is detected automatically based on the MTU of the primary network interface. You do not normally need to override the detected MTU. -+ -If the auto-detected value is not what you expected it to be, confirm that the MTU on the primary network interface on your nodes is correct. You cannot use this option to change the MTU value of the primary network interface on the nodes. -+ -If your cluster requires different MTU values for different nodes, you must set this value to `100` less than the lowest MTU value in your cluster. For example, if some nodes in your cluster have an MTU of `9001`, and some have an MTU of `1500`, you must set this value to `1400`. -endif::operator[] - -ifdef::operator[] -<3> The MTU for the Geneve (Generic Network Virtualization Encapsulation) -overlay network. This value is normally configured automatically. -endif::operator[] - -<4> The UDP port for the Geneve overlay network. - -ifndef::operator[] -<5> Specify an empty object to enable IPsec encryption. -endif::operator[] - -ifdef::operator[] -<5> If the field is present, IPsec is enabled for the cluster. -endif::operator[] - - -[id="nw-operator-example-cr_{context}"] -== Cluster Network Operator example configuration - -A complete CR object for the CNO is displayed in the following example: - -.Cluster Network Operator example CR -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: Network -metadata: - name: cluster -spec: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - serviceNetwork: - - 172.30.0.0/16 - defaultNetwork: - type: OpenShiftSDN - openshiftSDNConfig: - mode: NetworkPolicy - mtu: 1450 - vxlanPort: 4789 - kubeProxyConfig: - iptablesSyncPeriod: 30s - proxyArguments: - iptables-min-sync-period: - - 0s ----- -endif::post-install-network-configuration[] - -ifeval::["{context}" == "cluster-network-operator"] -:!operator: -endif::[] - -ifdef::post-install-network-configuration[] -:!post-install-network-configuration: -endif::[] diff --git a/modules/nw-osp-configuring-external-load-balancer.adoc b/modules/nw-osp-configuring-external-load-balancer.adoc deleted file mode 100644 index a16d81093ff8..000000000000 --- a/modules/nw-osp-configuring-external-load-balancer.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// TODO -// * networking/TBD -// * networking/load-balancing-openstack.adoc -// For thinking and reviewing, adding to networking/load-balancing-openstack.adoc - -[id="nw-osp-configuring-external-load-balancer_{context}"] -= Configuring an external load balancer - -You can configure a {product-title} cluster on {rh-openstack-first} to use an external load balancer in place of the default load balancer. - -// Maybe an About mod in support - -.Prerequisites - -* On your load balancer, TCP over ports 6443, 443, and 80 must be available to any users of your system. - -* Load balance the API port, 6443, between each of the control plane nodes. - -* Load balance the application ports, 443 and 80, between all of the compute nodes. - -* On your load balancer, port 22623, which is used to serve ignition start-up configurations to nodes, is not exposed outside of the cluster. - -* Your load balancer must be able to access every machine in your cluster. Methods to allow this access include: -** Attaching the load balancer to the cluster's machine subnet. -** Attaching floating IP addresses to machines that use the load balancer. - -.Procedure - -. Enable access to the cluster from your load balancer on ports 6443, 443, and 80. -+ -As an example, note this HAProxy configuration: -+ -.A section of a sample HAProxy configuration -[source,text] ----- -... -listen my-cluster-api-6443 - bind 0.0.0.0:6443 - mode tcp - balance roundrobin - server my-cluster-master-2 192.0.2.2:6443 check - server my-cluster-master-0 192.0.2.3:6443 check - server my-cluster-master-1 192.0.2.1:6443 check -listenmy-cluster-apps-443 - bind 0.0.0.0:443 - mode tcp - balance roundrobin - server my-cluster-worker-0 192.0.2.6:443 check - server my-cluster-worker-1 192.0.2.5:443 check - server my-cluster-worker-2 192.0.2.4:443 check -listenmy-cluster-apps-80 - bind 0.0.0.0:80 - mode tcp - balance roundrobin - server my-cluster-worker-0 192.0.2.7:80 check - server my-cluster-worker-1 192.0.2.9:80 check - server my-cluster-worker-2 192.0.2.8:80 check ----- - -. Add records to your DNS server for the cluster API and apps over the load balancer. For example: -+ -[source,dns] ----- -<load_balancer_ip_address> api.<cluster_name>.<base_domain> -<load_balancer_ip_address> apps.<cluster_name>.<base_domain> ----- - -. From a command line, use `curl` to verify that the external load balancer and DNS configuration are operational. - -.. Verify that the cluster API is accessible: -+ -[source,terminal] ----- -$ curl https://<loadbalancer_ip_address>:6443/version --insecure ----- -+ -If the configuration is correct, you receive a JSON object in response: -+ -[source,json] ----- -{ - "major": "1", - "minor": "11+", - "gitVersion": "v1.11.0+ad103ed", - "gitCommit": "ad103ed", - "gitTreeState": "clean", - "buildDate": "2019-01-09T06:44:10Z", - "goVersion": "go1.10.3", - "compiler": "gc", - "platform": "linux/amd64" -} ----- - -.. Verify that cluster applications are accessible: -+ -[NOTE] -==== -You can also verify application accessibility by opening the {product-title} console in a web browser. -==== -+ -[source, terminal] ----- -$ curl http://console-openshift-console.apps.<cluster_name>.<base_domain> -I -L --insecure ----- -+ -If the configuration is correct, you receive an HTTP response: -+ -[source,terminal] ----- -HTTP/1.1 302 Found -content-length: 0 -location: https://console-openshift-console.apps.<cluster-name>.<base domain>/ -cache-control: no-cacheHTTP/1.1 200 OK -referrer-policy: strict-origin-when-cross-origin -set-cookie: csrf-token=39HoZgztDnzjJkq/JuLJMeoKNXlfiVv2YgZc09c3TBOBU4NI6kDXaJH1LdicNhN1UsQWzon4Dor9GWGfopaTEQ==; Path=/; Secure -x-content-type-options: nosniff -x-dns-prefetch-control: off -x-frame-options: DENY -x-xss-protection: 1; mode=block -date: Tue, 17 Nov 2020 08:42:10 GMT -content-type: text/html; charset=utf-8 -set-cookie: 1e2670d92730b515ce3a1bb65da45062=9b714eb87e93cf34853e87a92d6894be; path=/; HttpOnly; Secure; SameSite=None -cache-control: private ----- diff --git a/modules/nw-ovn-ipsec-certificates.adoc b/modules/nw-ovn-ipsec-certificates.adoc deleted file mode 100644 index c6d33dc12e00..000000000000 --- a/modules/nw-ovn-ipsec-certificates.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc - -[id="nw-ovn-ipsec-certificates_{context}"] -= Security certificate generation and rotation - -The Cluster Network Operator (CNO) generates a self-signed X.509 certificate authority (CA) that is used by IPsec for encryption. Certificate signing requests (CSRs) from each node are automatically fulfilled by the CNO. - -The CA is valid for 10 years. The individual node certificates are valid for 5 years and are automatically rotated after 4 1/2 years elapse. diff --git a/modules/nw-ovn-ipsec-encryption.adoc b/modules/nw-ovn-ipsec-encryption.adoc deleted file mode 100644 index 5b074829aa77..000000000000 --- a/modules/nw-ovn-ipsec-encryption.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc - -[id="nw-ovn-ipsec-encryption_{context}"] -= Encryption protocol and tunnel mode for IPsec - -The encrypt cipher used is `AES-GCM-16-256`. The integrity check value (ICV) is `16` bytes. The key length is `256` bits. - -The IPsec tunnel mode used is _Transport mode_, a mode that encrypts end-to-end communication. diff --git a/modules/nw-ovn-ipsec-traffic.adoc b/modules/nw-ovn-ipsec-traffic.adoc deleted file mode 100644 index c64004f3fe66..000000000000 --- a/modules/nw-ovn-ipsec-traffic.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc - -[id="nw-ovn-ipsec-traffic_{context}"] -= Types of network traffic flows encrypted by IPsec - -With IPsec enabled, only the following network traffic flows between pods are encrypted: - -* Traffic between pods on different nodes on the cluster network -* Traffic from a pod on the host network to a pod on the cluster network - -The following traffic flows are not encrypted: - -* Traffic between pods on the same node on the cluster network -* Traffic between pods on the host network -* Traffic from a pod on the cluster network to a pod on the host network - -The encrypted and unencrypted flows are illustrated in the following diagram: - -image::nw-ipsec-encryption.png[IPsec encrypted and unencrypted traffic flows] diff --git a/modules/nw-ovn-kubernetes-features.adoc b/modules/nw-ovn-kubernetes-features.adoc deleted file mode 100644 index 9813acf6c738..000000000000 --- a/modules/nw-ovn-kubernetes-features.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc - -[id="nw-ovn-kubernetes-features_{context}"] -= OVN-Kubernetes features - -The OVN-Kubernetes default Container Network Interface (CNI) network provider implements the following features: - -// OVN (Open Virtual Network) is consistent with upstream usage. - -* Uses OVN (Open Virtual Network) to manage network traffic flows. OVN is a community developed, vendor agnostic network virtualization solution. -* Implements Kubernetes network policy support, including ingress and egress rules. -* Uses the Geneve (Generic Network Virtualization Encapsulation) protocol rather than VXLAN to create an overlay network between nodes. diff --git a/modules/nw-ovn-kubernetes-matrix.adoc b/modules/nw-ovn-kubernetes-matrix.adoc deleted file mode 100644 index feb000cc477d..000000000000 --- a/modules/nw-ovn-kubernetes-matrix.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc - -[id="nw-ovn-kubernetes-matrix_{context}"] -= Supported default CNI network provider feature matrix - -{product-title} offers two supported choices, OpenShift SDN and OVN-Kubernetes, for the default Container Network Interface (CNI) network provider. The following table summarizes the current feature support for both network providers: - -.Default CNI network provider feature comparison -[cols="50%,25%,25%",options="header"] -|=== -ifeval::["{context}" == "about-ovn-kubernetes"] -|Feature|OVN-Kubernetes|OpenShift SDN - -|Egress IPs|Supported|Supported - -|Egress firewall ^[1]^|Supported|Supported - -|Egress router|Partially supported ^[3]^|Supported - -|IPsec encryption|Supported|Not supported - -|Kubernetes network policy|Supported|Partially supported ^[2]^ - -|Multicast|Supported|Supported -endif::[] -ifeval::["{context}" == "about-openshift-sdn"] -|Feature|OpenShift SDN|OVN-Kubernetes - -|Egress IPs|Supported|Supported - -|Egress firewall ^[1]^|Supported|Supported - -|Egress router|Supported|Partially supported ^[3]^ - -|IPsec encryption|Not supported|Supported - -|Kubernetes network policy|Partially supported ^[2]^|Supported - -|Multicast|Supported|Supported -endif::[] -|=== -[.small] --- -1. Egress firewall is also known as egress network policy in OpenShift SDN. This is not the same as network policy egress. - -2. Network policy for OpenShift SDN does not support egress rules and some `ipBlock` rules. - -3. Egress router for OVN-Kubernetes supports only redirect mode. --- diff --git a/modules/nw-ovn-kubernetes-metrics.adoc b/modules/nw-ovn-kubernetes-metrics.adoc deleted file mode 100644 index 4b0751cbba65..000000000000 --- a/modules/nw-ovn-kubernetes-metrics.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc - -[id="nw-ovn-kubernetes-metrics_{context}"] -= Exposed metrics for OVN-Kubernetes - -The OVN-Kubernetes default Container Network Interface (CNI) network provider exposes certain metrics for use by the Prometheus-based {product-title} cluster monitoring stack. - -// openshift/ovn-kubernetes => go-controller/pkg/metrics/master.go - -.Metrics exposed by OVN-Kubernetes -[cols="2a,8a",options="header"] -|=== -|Name |Description - -|`ovnkube_master_pod_creation_latency_seconds` -|The latency between when a pod is created and when the pod is annotated by OVN-Kubernetes. The higher the latency, the more time that elapses before a pod is available for network connectivity. - -|=== - -//// -|`ovnkube_master_nb_e2e_timestamp` -|A timestamp persisted to the OVN (Open Virtual Network) northbound database and updated frequently. -//// diff --git a/modules/nw-ovn-kubernetes-migration-about.adoc b/modules/nw-ovn-kubernetes-migration-about.adoc deleted file mode 100644 index 79814be317b4..000000000000 --- a/modules/nw-ovn-kubernetes-migration-about.adoc +++ /dev/null @@ -1,137 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/migrate-from-openshift-sdn.adoc - -[id="nw-ovn-kubernetes-migration-about_{context}"] -= Migration to the OVN-Kubernetes network provider - -Migrating to the OVN-Kubernetes Container Network Interface (CNI) cluster network provider is a manual process that includes some downtime during which your cluster is unreachable. Although a rollback procedure is provided, the migration is intended to be a one-way process. - -A migration to the OVN-Kubernetes cluster network provider is supported on installer-provisioned clusters on the following platforms: - -* Bare metal hardware -* Amazon Web Services (AWS) -* Google Cloud Platform (GCP) -* Microsoft Azure -* {rh-openstack-first} -* VMware vSphere - -[NOTE] -==== -Performing a migration on a user-provisioned cluster is not supported. -==== - -[id="considerations-migrating-ovn-kubernetes-network-provider_{context}"] -== Considerations for migrating to the OVN-Kubernetes network provider - -The subnets assigned to nodes and the IP addresses assigned to individual pods are not preserved during the migration. - -While the OVN-Kubernetes network provider implements many of the capabilities present in the OpenShift SDN network provider, the configuration is not the same. - -If your cluster uses any of the following OpenShift SDN capabilities, you must manually configure the same capability in OVN-Kubernetes: - -* Namespace isolation -* Egress IP addresses -* Egress network policies -* Egress router pods -* Multicast - -The following sections highlight the differences in configuration between the aforementioned capabilities in OVN-Kubernetes and OpenShift SDN. - -[discrete] -[id="namespace-isolation_{context}"] -=== Namespace isolation - -OVN-Kubernetes supports only the network policy isolation mode. - -[IMPORTANT] -==== -If your cluster is using OpenShift SDN configured in either the multitenant or subnet isolation modes, you cannot migrate to the OVN-Kubernetes network provider. -==== - -[discrete] -[id="egress-ip-addresses_{context}"] -=== Egress IP addresses - -The differences in configuring an egress IP address between OVN-Kubernetes and OpenShift SDN is described in the following table: - -.Differences in egress IP address configuration -[cols="1a,1a",options="header"] -|=== -|OVN-Kubernetes|OpenShift SDN - -| -* Create an `EgressIPs` object -* Add an annotation on a `Node` object - -| -* Patch a `NetNamespace` object -* Patch a `HostSubnet` object -|=== - -For more information on using egress IP addresses in OVN-Kubernetes, see "Configuring an egress IP address". - -[discrete] -[id="egress-network-policies_{context}"] -=== Egress network policies - -The difference in configuring an egress network policy, also known as an egress firewall, between OVN-Kubernetes and OpenShift SDN is described in the following table: - -.Differences in egress network policy configuration -[cols="1a,1a",options="header"] -|=== -|OVN-Kubernetes|OpenShift SDN - -| -* Create an `EgressFirewall` object in a namespace - -| -* Create an `EgressNetworkPolicy` object in a namespace -|=== - -For more information on using an egress firewall in OVN-Kubernetes, see "Configuring an egress firewall for a project". - -[discrete] -[id="egress-router-pods_{context}"] -=== Egress router pods - -[discrete] -[id="multicast_{context}"] -=== Multicast - -The difference between enabling multicast traffic on OVN-Kubernetes and OpenShift SDN is described in the following table: - -.Differences in multicast configuration -[cols="1a,1a",options="header"] -|=== -|OVN-Kubernetes|OpenShift SDN - -| -* Add an annotation on a `Namespace` object - -| -* Add an annotation on a `NetNamespace` object -|=== - -For more information on using multicast in OVN-Kubernetes, see "Enabling multicast for a project". - -[discrete] -[id="network-policies_{context}"] -=== Network policies - -OVN-Kubernetes fully supports the Kubernetes `NetworkPolicy` API in the `networking.k8s.io/v1` API group. No changes are necessary in your network policies when migrating from OpenShift SDN. - -[id="how-the-migration-process-works_{context}"] -== How the migration process works - -The migration process works as follows: - -. Set a temporary annotation set on the Cluster Network Operator (CNO) configuration object. This annotation triggers the CNO to watch for a change to the `defaultNetwork` field. - -. Suspend the Machine Config Operator (MCO) to ensure that it does not interrupt the migration. - -. Update the `defaultNetwork` field. The update causes the CNO to destroy the OpenShift SDN control plane pods and deploy the OVN-Kubernetes control plane pods. Additionally, it updates the Multus objects to reflect the new cluster network provider. - -. Reboot each node in the cluster. Because the existing pods in the cluster are unaware of the change to the cluster network provider, rebooting each node ensures that each node is drained of pods. New pods are attached to the new cluster network provided by OVN-Kubernetes. - -. Enable the MCO after all nodes in the cluster reboot. The MCO rolls out an update to the systemd configuration necessary to complete the migration. The MCO updates a single machine per pool at a time by default, so the total time the migration takes increases with the size of the cluster. diff --git a/modules/nw-ovn-kubernetes-migration.adoc b/modules/nw-ovn-kubernetes-migration.adoc deleted file mode 100644 index 98be6245f4cd..000000000000 --- a/modules/nw-ovn-kubernetes-migration.adoc +++ /dev/null @@ -1,308 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/migrate-from-openshift-sdn.adoc - -[id="nw-ovn-kubernetes-migration_{context}"] -= Migrating to the OVN-Kubernetes default CNI network provider - -As a cluster administrator, you can change the default Container Network Interface (CNI) network provider for your cluster to OVN-Kubernetes. -During the migration, you must reboot every node in your cluster. - -[IMPORTANT] -==== -While performing the migration, your cluster is unavailable and workloads might be interrupted. -Perform the migration only when an interruption in service is acceptable. -==== - -.Prerequisites - -* A cluster installed on installer-provisioned infrastructure and configured with the OpenShift SDN default CNI network provider in the network policy isolation mode. -* Install the OpenShift CLI (`oc`). -* Access to the cluster as a user with the `cluster-admin` role. -* A recent backup of the etcd database is available. -* The cluster is in a known good state, without any errors. -* A reboot can be triggered manually for each node. - -.Procedure - -. To backup the configuration for the cluster network, enter the following command: -+ -[source,terminal] ----- -$ oc get Network.config.openshift.io cluster -o yaml > cluster-openshift-sdn.yaml ----- - -. To enable the migration, set an annotation on the Cluster Network Operator configuration object by entering the following command: -+ -[source,terminal] ----- -$ oc annotate Network.operator.openshift.io cluster \ - 'networkoperator.openshift.io/network-migration'="" ----- - -. Stop all of the machine configuration pools managed by the Machine Config Operator (MCO): - -** Stop the master configuration pool: -+ -[source,terminal] ----- -$ oc patch MachineConfigPool master --type='merge' --patch \ - '{ "spec": { "paused": true } }' ----- - -** Stop the worker configuration pool: -+ -[source,terminal] ----- -$ oc patch MachineConfigPool worker --type='merge' --patch \ - '{ "spec":{ "paused" :true } }' ----- - -. Configure the OVN-Kubernetes cluster network provider by using one of the following commands: - -** To specify the network provider without changing the cluster network IP address block, enter the following command: -+ -[source,terminal] ----- -$ oc patch Network.config.openshift.io cluster \ - --type='merge' --patch '{ "spec": { "networkType": "OVNKubernetes" } }' ----- - -** To specify a different cluster network IP address block, enter the following command: -+ -[source,terminal] ----- -$ oc patch Network.config.openshift.io cluster \ - --type='merge' --patch '{ - "spec": { - "clusterNetwork": [ - "cidr": "<cidr>", - "hostPrefix": "<prefix>" - ] - "networkType": "OVNKubernetes" - } - }' ----- -+ -where `cidr` is a CIDR block and `prefix` is the slice of the CIDR block apportioned to each node in your cluster. You cannot use any CIDR block that overlaps with the `100.64.0.0/16` CIDR block, because the OVN-Kubernetes network provider uses this block internally. -+ -IMPORTANT: You cannot change the service network address block during the migration. - -. Optional: You can customize the following settings for OVN-Kubernetes to meet your network infrastructure requirements: -+ --- -* Maximum transmission unit (MTU) -* Geneve (Generic Network Virtualization Encapsulation) overlay network port --- -+ -To customize either of the previously noted settings, enter and customize the following command. If you do not need to change the default value, omit the key from the patch. -+ -[source,terminal] ----- -$ oc patch Network.operator.openshift.io cluster --type=merge \ - --patch '{ - "spec":{ - "defaultNetwork":{ - "ovnKubernetesConfig":{ - "mtu":<mtu>, - "genevePort":<port> - }}}}' ----- -+ --- -`mtu`:: -The MTU for the Geneve overlay network. This value is normally configured automatically, but if the nodes in your cluster do not all use the same MTU, then you must set this explicitly to `100` less than the smallest node MTU value. -`port`:: -The UDP port for the Geneve overlay network. If a value is not specified, the default is `6081`. The port cannot be the same as the VXLAN port that is used by OpenShift SDN. The default value for the VXLAN port is `4789`. --- -+ -.Example patch command to update `mtu` field -[source,terminal] ----- -$ oc patch Network.operator.openshift.io cluster --type=merge \ - --patch '{ - "spec":{ - "defaultNetwork":{ - "ovnKubernetesConfig":{ - "mtu":1200 - }}}}' ----- - -. Wait until the Multus daemon set rollout completes. -+ -[source,terminal] ----- -$ oc -n openshift-multus rollout status daemonset/multus ----- -+ -The name of the Multus pods is in form of `multus-<xxxxx>` where `<xxxxx>` is a random sequence of letters. It might take several moments for the pods to restart. -+ -.Example output -[source,text] ----- -Waiting for daemon set "multus" rollout to finish: 1 out of 6 new pods have been updated... -... -Waiting for daemon set "multus" rollout to finish: 5 of 6 updated pods are available... -daemon set "multus" successfully rolled out ----- - -. To complete the migration, reboot each node in your cluster. For example, you can use a bash script similar to the following example. The script assumes that you can connect to each host by using `ssh` and that you have configured `sudo` to not prompt for a password. -+ -[source,bash] ----- -#!/bin/bash - -for ip in $(oc get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="InternalIP")].address}') -do - echo "reboot node $ip" - ssh -o StrictHostKeyChecking=no core@$ip sudo shutdown -r -t 3 -done ----- -+ -If ssh access is not available, you might be able to reboot each node through the management portal for your infrastructure provider. - -. After the nodes in your cluster have rebooted, start all of the machine configuration pools: -+ --- -* Start the master configuration pool: -+ -[source,terminal] ----- -$ oc patch MachineConfigPool master --type='merge' --patch \ - '{ "spec": { "paused": false } }' ----- - -* Start the worker configuration pool: -+ -[source,terminal] ----- -$ oc patch MachineConfigPool worker --type='merge' --patch \ - '{ "spec": { "paused": false } }' ----- --- -+ -As the MCO updates machines in each config pool, it reboots each node. -+ -By default the MCO updates a single machine per pool at a time, so the time that the migration requires to complete grows with the size of the cluster. - -. Confirm the status of the new machine configuration on the hosts: -.. To list the machine configuration state and the name of the applied machine configuration, enter the following command: -+ -[source,terminal] ----- -$ oc describe node | egrep "hostname|machineconfig" ----- -+ -.Example output -[source,terminal] ----- -kubernetes.io/hostname=master-0 -machineconfiguration.openshift.io/currentConfig: rendered-master-c53e221d9d24e1c8bb6ee89dd3d8ad7b -machineconfiguration.openshift.io/desiredConfig: rendered-master-c53e221d9d24e1c8bb6ee89dd3d8ad7b -machineconfiguration.openshift.io/reason: -machineconfiguration.openshift.io/state: Done ----- -+ -Verify that the following statements are true: -+ --- - * The value of `machineconfiguration.openshift.io/state` field is `Done`. - * The value of the `machineconfiguration.openshift.io/currentConfig` field is equal to the value of the `machineconfiguration.openshift.io/desiredConfig` field. --- - -.. To confirm that the machine config is correct, enter the following command: -+ -[source,terminal] ----- -$ oc get machineconfig <config_name> -o yaml | grep ExecStart ----- -+ -where `<config_name>` is the name of the machine config from the `machineconfiguration.openshift.io/currentConfig` field. -+ -The machine config must include the following update to the systemd configuration: -+ -[source,plain] ----- -ExecStart=/usr/local/bin/configure-ovs.sh OVNKubernetes ----- - -. Confirm that the migration succeeded: - -.. To confirm that the default CNI network provider is OVN-Kubernetes, enter the following command. The value of `status.networkType` must be `OVNKubernetes`. -+ -[source,terminal] ----- -$ oc get network.config/cluster -o jsonpath='{.status.networkType}{"\n"}' ----- - -.. To confirm that the cluster nodes are in the `Ready` state, enter the following command: -+ -[source,terminal] ----- -$ oc get nodes ----- - -.. If a node is stuck in the `NotReady` state, investigate the machine config daemon pod logs and resolve any errors. - -... To list the pods, enter the following command: -+ -[source,terminal] ----- -$ oc get pod -n openshift-machine-config-operator ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -machine-config-controller-75f756f89d-sjp8b 1/1 Running 0 37m -machine-config-daemon-5cf4b 2/2 Running 0 43h -machine-config-daemon-7wzcd 2/2 Running 0 43h -machine-config-daemon-fc946 2/2 Running 0 43h -machine-config-daemon-g2v28 2/2 Running 0 43h -machine-config-daemon-gcl4f 2/2 Running 0 43h -machine-config-daemon-l5tnv 2/2 Running 0 43h -machine-config-operator-79d9c55d5-hth92 1/1 Running 0 37m -machine-config-server-bsc8h 1/1 Running 0 43h -machine-config-server-hklrm 1/1 Running 0 43h -machine-config-server-k9rtx 1/1 Running 0 43h ----- -+ -The names for the config daemon pods are in the following format: `machine-config-daemon-<seq>`. The `<seq>` value is a random five character alphanumeric sequence. - -... Display the pod log for the first machine config daemon pod shown in the previous output by enter the following command: -+ -[source,terminal] ----- -$ oc logs <pod> -n openshift-machine-config-operator ----- -+ -where `pod` is the name of a machine config daemon pod. - -... Resolve any errors in the logs shown by the output from the previous command. - -.. To confirm that your pods are not in an error state, enter the following command: -+ -[source,terminal] ----- -$ oc get pods --all-namespaces -o wide --sort-by='{.spec.nodeName}' ----- -+ -If pods on a node are in an error state, reboot that node. - -. Complete the following steps only if the migration succeeds and your cluster is in a good state: - -.. To remove the migration annotation from the Cluster Network Operator configuration object, enter the following command: -+ -[source,terminal] ----- -$ oc annotate Network.operator.openshift.io cluster \ - networkoperator.openshift.io/network-migration- ----- - -.. To remove the OpenShift SDN network provider namespace, enter the following command: -+ -[source,terminal] ----- -$ oc delete namespace openshift-sdn ----- diff --git a/modules/nw-ovn-kubernetes-rollback.adoc b/modules/nw-ovn-kubernetes-rollback.adoc deleted file mode 100644 index a91f7044d9b9..000000000000 --- a/modules/nw-ovn-kubernetes-rollback.adoc +++ /dev/null @@ -1,268 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/ovn_kubernetes_network_provider/rollback-to-openshift-sdn.adoc - -[id="nw-ovn-kubernetes-rollback_{context}"] -= Rolling back the default CNI network provider to OpenShift SDN - -As a cluster administrator, you can rollback your cluster to the OpenShift SDN default Container Network Interface (CNI) network provider. -During the rollback, you must reboot every node in your cluster. - -[IMPORTANT] -==== -Only rollback to OpenShift SDN if the migration to OVN-Kubernetes fails. -==== - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Access to the cluster as a user with the `cluster-admin` role. -* A cluster installed on infrastructure configured with the OVN-Kubernetes default CNI network provider. - -.Procedure - -. To enable the migration, set an annotation on the Cluster Network Operator configuration object by entering the following command: -+ -[source,terminal] ----- -$ oc annotate Network.operator.openshift.io cluster \ - 'networkoperator.openshift.io/network-migration'="" ----- - -. Stop all of the machine configuration pools managed by the Machine Config Operator (MCO): - -** Stop the master configuration pool: -+ -[source,terminal] ----- -$ oc patch MachineConfigPool master --type='merge' --patch \ - '{ "spec": { "paused": true } }' ----- - -** Stop the worker configuration pool: -+ -[source,terminal] ----- -$ oc patch MachineConfigPool worker --type='merge' --patch \ - '{ "spec":{ "paused" :true } }' ----- - -. To configure the OpenShift SDN cluster network provider, enter the following command: -+ -[source,terminal] ----- -$ oc patch Network.config.openshift.io cluster \ - --type='merge' --patch '{ "spec": { "networkType": "OpenShiftSDN" } }' ----- - -. Optional: You can customize the following settings for OpenShift SDN to meet your network infrastructure requirements: -+ --- -* Maximum transmission unit (MTU) -* VXLAN port --- -+ -To customize either or both of the previously noted settings, customize and enter the following command. If you do not need to change the default value, omit the key from the patch. -+ -[source,terminal] ----- -$ oc patch Network.operator.openshift.io cluster --type=merge \ - --patch '{ - "spec":{ - "defaultNetwork":{ - "openshiftSDNConfig":{ - "mtu":<mtu>, - "vxlanPort":<port> - }}}}' ----- -+ --- -`mtu`:: -The MTU for the VXLAN overlay network. This value is normally configured automatically, but if the nodes in your cluster do not all use the same MTU, then you must set this explicitly to `50` less than the smallest node MTU value. -`port`:: -The UDP port for the VXLAN overlay network. If a value is not specified, the default is `4789`. The port cannot be the same as the Geneve port that is used by OVN-Kubernetes. The default value for the Geneve port is `6081`. --- -+ -.Example patch command -[source,terminal] ----- -$ oc patch Network.operator.openshift.io cluster --type=merge \ - --patch '{ - "spec":{ - "defaultNetwork":{ - "openshiftSDNConfig":{ - "mtu":1200 - }}}}' ----- - -. Wait until the Multus daemon set rollout completes. -+ -[source,terminal] ----- -$ oc -n openshift-multus rollout status daemonset/multus ----- -+ -The name of the Multus pods is in form of `multus-<xxxxx>` where `<xxxxx>` is a random sequence of letters. It might take several moments for the pods to restart. -+ -.Example output -[source,text] ----- -Waiting for daemon set "multus" rollout to finish: 1 out of 6 new pods have been updated... -... -Waiting for daemon set "multus" rollout to finish: 5 of 6 updated pods are available... -daemon set "multus" successfully rolled out ----- - -. To complete the rollback, reboot each node in your cluster. For example, you could use a bash script similar to the following. The script assumes that you can connect to each host by using `ssh` and that you have configured `sudo` to not prompt for a password. -+ -[source,bash] ----- -#!/bin/bash - -for ip in $(oc get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="InternalIP")].address}') -do - echo "reboot node $ip" - ssh -o StrictHostKeyChecking=no core@$ip sudo shutdown -r -t 3 -done ----- -+ -If ssh access is not available, you might be able to reboot each node through the management portal for your infrastructure provider. - -. After the nodes in your cluster have rebooted, start all of the machine configuration pools: -+ --- -* Start the master configuration pool: -+ -[source,terminal] ----- -$ oc patch MachineConfigPool master --type='merge' --patch \ - '{ "spec": { "paused": false } }' ----- - -* Start the worker configuration pool: -+ -[source,terminal] ----- -$ oc patch MachineConfigPool worker --type='merge' --patch \ - '{ "spec": { "paused": false } }' ----- --- -+ -As the MCO updates machines in each config pool, it reboots each node. -+ -By default the MCO updates a single machine per pool at a time, so the time that the migration requires to complete grows with the size of the cluster. - -. Confirm the status of the new machine configuration on the hosts: -.. To list the machine configuration state and the name of the applied machine configuration, enter the following command: -+ -[source,terminal] ----- -$ oc describe node | egrep "hostname|machineconfig" ----- -+ -.Example output -[source,terminal] ----- -kubernetes.io/hostname=master-0 -machineconfiguration.openshift.io/currentConfig: rendered-master-c53e221d9d24e1c8bb6ee89dd3d8ad7b -machineconfiguration.openshift.io/desiredConfig: rendered-master-c53e221d9d24e1c8bb6ee89dd3d8ad7b -machineconfiguration.openshift.io/reason: -machineconfiguration.openshift.io/state: Done ----- -+ -Verify that the following statements are true: -+ --- - * The value of `machineconfiguration.openshift.io/state` field is `Done`. - * The value of the `machineconfiguration.openshift.io/currentConfig` field is equal to the value of the `machineconfiguration.openshift.io/desiredConfig` field. --- - -.. To confirm that the machine config is correct, enter the following command: -+ -[source,terminal] ----- -$ oc get machineconfig <config_name> -o yaml ----- -+ -where `<config_name>` is the name of the machine config from the `machineconfiguration.openshift.io/currentConfig` field. - -. Confirm that the migration succeeded: - -.. To confirm that the default CNI network provider is OVN-Kubernetes, enter the following command. The value of `status.networkType` must be `OpenShiftSDN`. -+ -[source,terminal] ----- -$ oc get network.config/cluster -o jsonpath='{.status.networkType}{"\n"}' ----- - -.. To confirm that the cluster nodes are in the `Ready` state, enter the following command: -+ -[source,terminal] ----- -$ oc get nodes ----- - -.. If a node is stuck in the `NotReady` state, investigate the machine config daemon pod logs and resolve any errors. - -... To list the pods, enter the following command: -+ -[source,terminal] ----- -$ oc get pod -n openshift-machine-config-operator ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -machine-config-controller-75f756f89d-sjp8b 1/1 Running 0 37m -machine-config-daemon-5cf4b 2/2 Running 0 43h -machine-config-daemon-7wzcd 2/2 Running 0 43h -machine-config-daemon-fc946 2/2 Running 0 43h -machine-config-daemon-g2v28 2/2 Running 0 43h -machine-config-daemon-gcl4f 2/2 Running 0 43h -machine-config-daemon-l5tnv 2/2 Running 0 43h -machine-config-operator-79d9c55d5-hth92 1/1 Running 0 37m -machine-config-server-bsc8h 1/1 Running 0 43h -machine-config-server-hklrm 1/1 Running 0 43h -machine-config-server-k9rtx 1/1 Running 0 43h ----- -+ -The names for the config daemon pods are in the following format: `machine-config-daemon-<seq>`. The `<seq>` value is a random five character alphanumeric sequence. - -... To display the pod log for each machine config daemon pod shown in the previous output, enter the following command: -+ -[source,terminal] ----- -$ oc logs <pod> -n openshift-machine-config-operator ----- -+ -where `pod` is the name of a machine config daemon pod. - -... Resolve any errors in the logs shown by the output from the previous command. - -.. To confirm that your pods are not in an error state, enter the following command: -+ -[source,terminal] ----- -$ oc get pods --all-namespaces -o wide --sort-by='{.spec.nodeName}' ----- -+ -If pods on a node are in an error state, reboot that node. - -. Complete the following steps only if the migration succeeds and your cluster is in a good state: - -.. To remove the migration annotation from the Cluster Network Operator configuration object, enter the following command: -+ -[source,terminal] ----- -$ oc annotate Network.operator.openshift.io cluster \ - networkoperator.openshift.io/network-migration- ----- - -.. To remove the OVN-Kubernetes network provider namespace, enter the following command: -+ -[source,terminal] ----- -$ oc delete namespace openshift-ovn-kubernetes ----- diff --git a/modules/nw-path-based-routes.adoc b/modules/nw-path-based-routes.adoc deleted file mode 100644 index 5baad7684300..000000000000 --- a/modules/nw-path-based-routes.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module filename: nw-path-based-routes.adoc -// Module included in the following assemblies: -// * networking/routes/route-configuration.adoc - -[id="nw-path-based-routes_{context}"] -= Path-based routes - -Path-based routes specify a path component that can be compared against a URL, which requires that the traffic for the route be HTTP based. Thus, multiple routes can be served using the same host name, each with a different path. Routers should match routes based on the most specific path to the least. However, this depends on the router implementation. - -The following table shows example routes and their accessibility: - -.Route availability -[cols="3*", options="header"] -|=== -|Route | When Compared to | Accessible -.2+|_www.example.com/test_ |_www.example.com/test_|Yes -|_www.example.com_|No -.2+|_www.example.com/test_ and _www.example.com_ | _www.example.com/test_|Yes -|_www.example.com_|Yes -.2+|_www.example.com_|_www.example.com/text_|Yes (Matched by the host, not the route) -|_www.example.com_|Yes -|=== - -.An unsecured route with a path - -[source,yaml] ----- -apiVersion: v1 -kind: Route -metadata: - name: route-unsecured -spec: - host: www.example.com - path: "/test" <1> - to: - kind: Service - name: service-name ----- -<1> The path is the only added attribute for a path-based route. - -[NOTE] -==== -Path-based routing is not available when using passthrough TLS, as the router does not terminate TLS in that case and cannot read the contents of the request. -==== diff --git a/modules/nw-pdncc-view.adoc b/modules/nw-pdncc-view.adoc deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/modules/nw-pod-network-connectivity-check-object.adoc b/modules/nw-pod-network-connectivity-check-object.adoc deleted file mode 100644 index 924f08fe1a03..000000000000 --- a/modules/nw-pod-network-connectivity-check-object.adoc +++ /dev/null @@ -1,162 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/verifying-connectivity-endpoint.adoc - -[id="nw-pod-network-connectivity-check-object_{context}"] -= PodNetworkConnectivityCheck object fields - -The `PodNetworkConnectivityCheck` object fields are described in the following tables. - -.PodNetworkConnectivityCheck object fields -[cols="2,1,3a",options="header"] -|=== - -|Field|Type|Description - -|`metadata.name` -|`string` -|The name of the object in the following format: `<source>-to-<target>`. The destination described by `<target>` includes one of following strings: - -* `load-balancer-api-external` -* `load-balancer-api-internal` -* `kubernetes-apiserver-endpoint` -* `kubernetes-apiserver-service-cluster` -* `network-check-target` -* `openshift-apiserver-endpoint` -* `openshift-apiserver-service-cluster` - -|`metadata.namespace` -|`string` -|The namespace that the object is associated with. This value is always `openshift-network-diagnostics`. - -|`spec.sourcePod` -|`string` -|The name of the pod where the connection check originates, such as `network-check-source-596b4c6566-rgh92`. - -|`spec.targetEndpoint` -|`string` -|The target of the connection check, such as `api.devcluster.example.com:6443`. - -|`spec.tlsClientCert` -|`object` -|Configuration for the TLS certificate to use. - -|`spec.tlsClientCert.name` -|`string` -|The name of the TLS certificate used, if any. The default value is an empty string. - -|`status` -|`object` -|An object representing the condition of the connection test and logs of recent connection successes and failures. - -|`status.conditions` -|`array` -|The latest status of the connection check and any previous statuses. - -|`status.failures` -|`array` -|Connection test logs from unsuccessful attempts. - -|`status.outages` -|`array` -|Connect test logs covering the time periods of any outages. - -|`status.successes` -|`array` -|Connection test logs from successful attempts. - -|=== - -The following table describes the fields for objects in the `status.conditions` array: - -.status.conditions -[cols="2,1,3",options="header"] -|=== -|Field |Type |Description - -|`lastTransitionTime` -|`string` -|The time that the condition of the connection transitioned from one status to another. - -|`message` -|`string` -|The details about last transition in a human readable format. - -|`reason` -|`string` -|The last status of the transition in a machine readable format. - -|`status` -|`string` -|The status of the condition. - -|`type` -|`string` -|The type of the condition. - -|=== - -The following table describes the fields for objects in the `status.conditions` array: - -.status.outages -[cols="2,1,3",options="header"] -|=== -|Field |Type |Description - -|`end` -|`string` -|The timestamp from when the connection failure is resolved. - -|`endLogs` -|`array` -|Connection log entries, including the log entry related to the successful end of the outage. - -|`message` -|`string` -|A summary of outage details in a human readable format. - -|`start` -|`string` -|The timestamp from when the connection failure is first detected. - -|`startLogs` -|`array` -|Connection log entries, including the original failure. - -|=== - -[discrete] -== Connection log fields - -The fields for a connection log entry are described in the following table. The object is used in the the following fields: - -* `status.failures[]` -* `status.successes[]` -* `status.outages[].startLogs[]` -* `status.outages[].endLogs[]` - -.Connection log object -[cols="2,1,3",options="header"] -|=== -|Field |Type |Description - -|`latency` -|`string` -|Records the duration of the action. - -|`message` -|`string` -|Provides the status in a human readable format. - -|`reason` -|`string` -|Provides the reason for status in a machine readable format. The value is one of `TCPConnect`, `TCPConnectError`, `DNSResolve`, `DNSError`. - -|`success` -|`boolean` -|Indicates if the log entry is a success or failure. - -|`time` -|`string` -|The start time of connection check. -|=== diff --git a/modules/nw-pod-network-connectivity-checks.adoc b/modules/nw-pod-network-connectivity-checks.adoc deleted file mode 100644 index 26909fffd0c4..000000000000 --- a/modules/nw-pod-network-connectivity-checks.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/verifying-connectivity-endpoint.adoc - -[id="nw-pod-network-connectivity-checks_{context}"] -= Connection health checks performed - -To verify that cluster resources are reachable, a TCP connection is made to each of the following cluster API services: - -* Kubernetes API server service -* Kubernetes API server endpoints -* OpenShift API server service -* OpenShift API server endpoints -* Load balancers - -To verify that services and service endpoints are reachable on every node in the cluster, a TCP connection is made to each of the following targets: - -* Health check target service -* Health check target endpoints diff --git a/modules/nw-pod-network-connectivity-implementation.adoc b/modules/nw-pod-network-connectivity-implementation.adoc deleted file mode 100644 index 66c86af6a9d3..000000000000 --- a/modules/nw-pod-network-connectivity-implementation.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/verifying-connectivity-endpoint.adoc - -[id="nw-pod-network-connectivity-implementation_{context}"] -= Implementation of connection health checks - -The connectivity check controller orchestrates connection verification checks in your cluster. The results for the connection tests are stored in `PodNetworkConnectivity` objects in the `openshift-network-diagnostics` namespace. Connection tests are performed every minute in parallel. - -The Cluster Network Operator (CNO) deploys several resources to the cluster to send and receive connectivity health checks: - -Health check source:: This program deploys in a single pod replica set managed by a `Deployment` object. The program consumes `PodNetworkConnectivity` objects and connects to the `spec.targetEndpoint` specified in each object. - -Health check target:: A pod deployed as part of a daemon set on every node in the cluster. The pod listens for inbound health checks. The presence of this pod on every node allows for the testing of connectivity to each node. diff --git a/modules/nw-pod-network-connectivity-verify.adoc b/modules/nw-pod-network-connectivity-verify.adoc deleted file mode 100644 index bef5d503f19f..000000000000 --- a/modules/nw-pod-network-connectivity-verify.adoc +++ /dev/null @@ -1,205 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/verifying-connectivity-endpoint.adoc - -[id="nw-pod-network-connectivity-verify_{context}"] -= Verifying network connectivity for an endpoint - -As a cluster administrator, you can verify the connectivity of an endpoint, such as an API server, load balancer, service, or pod. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. To list the current `PodNetworkConnectivityCheck` objects, enter the following command: -+ -[source,terminal] ----- -$ oc get podnetworkconnectivitycheck -n openshift-network-diagnostics ----- -+ -.Example output -[source,terminal] ----- -NAME                                                                                                                                AGE -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0   75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-1   73m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-2   75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-kubernetes-apiserver-service-cluster                               75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-kubernetes-default-service-cluster                                 75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-load-balancer-api-external                                         75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-load-balancer-api-internal                                         75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-network-check-target-ci-ln-x5sv9rb-f76d1-4rzrp-master-0            75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-network-check-target-ci-ln-x5sv9rb-f76d1-4rzrp-master-1            75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-network-check-target-ci-ln-x5sv9rb-f76d1-4rzrp-master-2            75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-network-check-target-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh      74m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-network-check-target-ci-ln-x5sv9rb-f76d1-4rzrp-worker-c-n8mbf      74m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-network-check-target-ci-ln-x5sv9rb-f76d1-4rzrp-worker-d-4hnrz      74m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-network-check-target-service-cluster                               75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-openshift-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0    75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-openshift-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-1    75m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-openshift-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-2    74m -network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-openshift-apiserver-service-cluster                                75m ----- - -. View the connection test logs: -.. From the output of the previous command, identify the endpoint that you want to review the connectivity logs for. -.. To view the object, enter the following command: -+ -[source,terminal] ----- -$ oc get podnetworkconnectivitycheck <name> \ - -n openshift-network-diagnostics -o yaml ----- -+ -where `<name>` specifies the name of the `PodNetworkConnectivityCheck` object. -+ -.Example output -[source,terminal] ----- -apiVersion: controlplane.operator.openshift.io/v1alpha1 -kind: PodNetworkConnectivityCheck -metadata: -  name: network-check-source-ci-ln-x5sv9rb-f76d1-4rzrp-worker-b-6xdmh-to-kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0 -  namespace: openshift-network-diagnostics - ... -spec: -  sourcePod: network-check-source-7c88f6d9f-hmg2f -  targetEndpoint: 10.0.0.4:6443 -  tlsClientCert: -    name: "" -status: -  conditions: -  - lastTransitionTime: "2021-01-13T20:11:34Z" -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnectSuccess -    status: "True" -    type: Reachable -  failures: -  - latency: 2.241775ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: failed -      to establish a TCP connection to 10.0.0.4:6443: dial tcp 10.0.0.4:6443: connect: -      connection refused' -    reason: TCPConnectError -    success: false -    time: "2021-01-13T20:10:34Z" -  - latency: 2.582129ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: failed -      to establish a TCP connection to 10.0.0.4:6443: dial tcp 10.0.0.4:6443: connect: -      connection refused' -    reason: TCPConnectError -    success: false -    time: "2021-01-13T20:09:34Z" -  - latency: 3.483578ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: failed -      to establish a TCP connection to 10.0.0.4:6443: dial tcp 10.0.0.4:6443: connect: -      connection refused' -    reason: TCPConnectError -    success: false -    time: "2021-01-13T20:08:34Z" -  outages: -  - end: "2021-01-13T20:11:34Z" -    endLogs: -    - latency: 2.032018ms -      message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: -        tcp connection to 10.0.0.4:6443 succeeded' -      reason: TCPConnect -      success: true -      time: "2021-01-13T20:11:34Z" -    - latency: 2.241775ms -      message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: -        failed to establish a TCP connection to 10.0.0.4:6443: dial tcp 10.0.0.4:6443: -        connect: connection refused' -      reason: TCPConnectError -      success: false -      time: "2021-01-13T20:10:34Z" -    - latency: 2.582129ms -      message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: -        failed to establish a TCP connection to 10.0.0.4:6443: dial tcp 10.0.0.4:6443: -        connect: connection refused' -      reason: TCPConnectError -      success: false -      time: "2021-01-13T20:09:34Z" -    - latency: 3.483578ms -      message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: -        failed to establish a TCP connection to 10.0.0.4:6443: dial tcp 10.0.0.4:6443: -        connect: connection refused' -      reason: TCPConnectError -      success: false -      time: "2021-01-13T20:08:34Z" -    message: Connectivity restored after 2m59.999789186s -    start: "2021-01-13T20:08:34Z" -    startLogs: -    - latency: 3.483578ms -      message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: -        failed to establish a TCP connection to 10.0.0.4:6443: dial tcp 10.0.0.4:6443: -        connect: connection refused' -      reason: TCPConnectError -      success: false -      time: "2021-01-13T20:08:34Z" -  successes: -  - latency: 2.845865ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:14:34Z" -  - latency: 2.926345ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:13:34Z" -  - latency: 2.895796ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:12:34Z" -  - latency: 2.696844ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:11:34Z" -  - latency: 1.502064ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:10:34Z" -  - latency: 1.388857ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:09:34Z" -  - latency: 1.906383ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:08:34Z" -  - latency: 2.089073ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:07:34Z" -  - latency: 2.156994ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:06:34Z" -  - latency: 1.777043ms -    message: 'kubernetes-apiserver-endpoint-ci-ln-x5sv9rb-f76d1-4rzrp-master-0: tcp -      connection to 10.0.0.4:6443 succeeded' -    reason: TCPConnect -    success: true -    time: "2021-01-13T21:05:34Z" ----- diff --git a/modules/nw-proxy-configure-object.adoc b/modules/nw-proxy-configure-object.adoc deleted file mode 100644 index 709c6f55fd6b..000000000000 --- a/modules/nw-proxy-configure-object.adoc +++ /dev/null @@ -1,130 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring-a-custom-pki.adoc -// * networking/enable-cluster-wide-proxy.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="nw-proxy-configure-object_{context}"] -= Enabling the cluster-wide proxy - -The Proxy object is used to manage the cluster-wide egress proxy. When a cluster is -installed or upgraded without the proxy configured, a Proxy object is still -generated but it will have a nil `spec`. For example: - -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Proxy -metadata: - name: cluster -spec: - trustedCA: - name: "" -status: ----- - -A cluster administrator can configure the proxy for {product-title} by modifying -this `cluster` Proxy object. - -[NOTE] -==== -Only the Proxy object named `cluster` is supported, and no additional -proxies can be created. -==== - -.Prerequisites - -* Cluster administrator permissions -* {product-title} `oc` CLI tool installed - -.Procedure - -. Create a ConfigMap that contains any additional CA certificates required for -proxying HTTPS connections. -+ -[NOTE] -==== -You can skip this step if the proxy’s identity certificate is signed by an -authority from the RHCOS trust bundle. -==== - -.. Create a file called `user-ca-bundle.yaml` with the following contents, and provide the values of your PEM-encoded certificates: -+ -[source,yaml] ----- -apiVersion: v1 -data: - ca-bundle.crt: | <1> - <MY_PEM_ENCODED_CERTS> <2> -kind: ConfigMap -metadata: - name: user-ca-bundle <3> - namespace: openshift-config <4> ----- -<1> This data key must be named `ca-bundle.crt`. -<2> One or more PEM-encoded X.509 certificates used to sign the proxy's -identity certificate. -<3> The ConfigMap name that will be referenced from the Proxy object. -<4> The ConfigMap must be in the `openshift-config` namespace. - -.. Create the ConfigMap from this file: -+ -[source,terminal] ----- -$ oc create -f user-ca-bundle.yaml ----- - -. Use the `oc edit` command to modify the Proxy object: -+ -[source,terminal] ----- -$ oc edit proxy/cluster ----- - -. Configure the necessary fields for the proxy: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Proxy -metadata: - name: cluster -spec: - httpProxy: http://<username>:<pswd>@<ip>:<port> <1> - httpsProxy: http://<username>:<pswd>@<ip>:<port> <2> - noProxy: example.com <3> - readinessEndpoints: - - http://www.google.com <4> - - https://www.google.com - trustedCA: - name: user-ca-bundle <5> ----- -+ --- -<1> A proxy URL to use for creating HTTP connections outside the cluster. The -URL scheme must be `http`. -<2> A proxy URL to use for creating HTTPS connections outside the cluster. If -this is not specified, then `httpProxy` is used for both HTTP and HTTPS -connections. -<3> A comma-separated list of destination domain names, domains, IP addresses or -other network CIDRs to exclude proxying. -+ -Preface a domain with `.` to match subdomains only. For example, `.y.com` matches `x.y.com`, but not `y.com`. Use `*` to bypass proxy for all destinations. -If you scale up workers that are not included in the network defined by the `networking.machineNetwork[].cidr` field from the installation configuration, you must add them to this list to prevent connection issues. -+ -This field is ignored if neither the `httpProxy` or `httpsProxy` fields are set. -<4> One or more URLs external to the cluster to use to perform a readiness check -before writing the `httpProxy` and `httpsProxy` values to status. -<5> A reference to the ConfigMap in the `openshift-config` namespace that -contains additional CA certificates required for proxying HTTPS connections. -Note that the ConfigMap must already exist before referencing it here. This -field is required unless the proxy's identity certificate is signed by an -authority from the RHCOS trust bundle. --- - -. Save the file to apply the changes. - -[NOTE] -==== -The URL scheme must be `http`. The `https` scheme is currently not supported. -==== diff --git a/modules/nw-proxy-remove.adoc b/modules/nw-proxy-remove.adoc deleted file mode 100644 index a249c2165976..000000000000 --- a/modules/nw-proxy-remove.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/enable-cluster-wide-proxy.adoc - -[id="nw-proxy-remove_{context}"] -= Removing the cluster-wide proxy - -The `cluster` Proxy object cannot be deleted. To remove the proxy from a cluster, -remove all `spec` fields from the Proxy object. - -.Prerequisites - -* Cluster administrator permissions -* {product-title} `oc` CLI tool installed - -.Procedure - -. Use the `oc edit` command to modify the proxy: -+ -[source,terminal] ----- -$ oc edit proxy/cluster ----- - -. Remove all `spec` fields from the Proxy object. For example: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Proxy -metadata: - name: cluster -spec: {} -status: {} ----- - -. Save the file to apply the changes. diff --git a/modules/nw-ptp-configuring-linuxptp.adoc b/modules/nw-ptp-configuring-linuxptp.adoc deleted file mode 100644 index b527961be12c..000000000000 --- a/modules/nw-ptp-configuring-linuxptp.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-ptp.adoc - -[id="configuring-linuxptp_{context}"] -= Configuring Linuxptp services - -The PTP Operator adds the `PtpConfig.ptp.openshift.io` custom resource definition (CRD) to {product-title}. -You can configure the Linuxptp services (ptp4l, phc2sys) by creating a `PtpConfig` custom resource (CR) object. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. -* You must have installed the PTP Operator. - -.Procedure - -. Create the following `PtpConfig` CR, and then save the YAML in the `<name>-ptp-config.yaml` file. Replace `<name>` with the name for this configuration. -+ -[source,yaml] ----- -apiVersion: ptp.openshift.io/v1 -kind: PtpConfig -metadata: - name: <name> <1> - namespace: openshift-ptp <2> -spec: - profile: <3> - - name: "profile1" <4> - interface: "ens787f1" <5> - ptp4lOpts: "-s -2" <6> - phc2sysOpts: "-a -r" <7> - recommend: <8> - - profile: "profile1" <9> - priority: 10 <10> - match: <11> - - nodeLabel: "node-role.kubernetes.io/worker" <12> - nodeName: "dev-worker-0" <13> ----- -<1> Specify a name for the `PtpConfig` CR. -<2> Specify the namespace where the PTP Operator is installed. -<3> Specify an array of one or more `profile` objects. -<4> Specify the name of a profile object which is used to uniquely identify a profile object. -<5> Specify the network interface name to use by the `ptp4l` service, for example `ens787f1`. -<6> Specify system config options for the `ptp4l` service, for example `-s -2`. This should not include the interface name `-i <interface>` and service config file `-f /etc/ptp4l.conf` because these will be automatically appended. -<7> Specify system config options for the `phc2sys` service, for example `-a -r`. -<8> Specify an array of one or more `recommend` objects which define rules on how the `profile` should be applied to nodes. -<9> Specify the `profile` object name defined in the `profile` section. -<10> Specify the `priority` with an integer value between `0` and `99`. A larger number gets lower priority, so a priority of `99` is lower than a priority of `10`. If a node can be matched with multiple profiles according to rules defined in the `match` field, the profile with the higher priority will be applied to that node. -<11> Specify `match` rules with `nodeLabel` or `nodeName`. -<12> Specify `nodeLabel` with the `key` of `node.Labels` from the node object. -<13> Specify `nodeName` with `node.Name` from the node object. - -. Create the CR by running the following command: -+ -[source,terminal] ----- -$ oc create -f <filename> <1> ----- -<1> Replace `<filename>` with the name of the file you created in the previous step. - - -. Optional: Check that the `PtpConfig` profile is applied to nodes that match with `nodeLabel` or `nodeName`. -+ -[source,terminal] ----- -$ oc get pods -n openshift-ptp -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES -linuxptp-daemon-4xkbb 1/1 Running 0 43m 192.168.111.15 dev-worker-0 <none> <none> -linuxptp-daemon-tdspf 1/1 Running 0 43m 192.168.111.11 dev-master-0 <none> <none> -ptp-operator-657bbb64c8-2f8sj 1/1 Running 0 43m 10.128.0.116 dev-master-0 <none> <none> - -$ oc logs linuxptp-daemon-4xkbb -n openshift-ptp -I1115 09:41:17.117596 4143292 daemon.go:107] in applyNodePTPProfile -I1115 09:41:17.117604 4143292 daemon.go:109] updating NodePTPProfile to: -I1115 09:41:17.117607 4143292 daemon.go:110] ------------------------------------ -I1115 09:41:17.117612 4143292 daemon.go:102] Profile Name: profile1 <1> -I1115 09:41:17.117616 4143292 daemon.go:102] Interface: ens787f1 <2> -I1115 09:41:17.117620 4143292 daemon.go:102] Ptp4lOpts: -s -2 <3> -I1115 09:41:17.117623 4143292 daemon.go:102] Phc2sysOpts: -a -r <4> -I1115 09:41:17.117626 4143292 daemon.go:116] ------------------------------------ -I1115 09:41:18.117934 4143292 daemon.go:186] Starting phc2sys... -I1115 09:41:18.117985 4143292 daemon.go:187] phc2sys cmd: &{Path:/usr/sbin/phc2sys Args:[/usr/sbin/phc2sys -a -r] Env:[] Dir: Stdin:<nil> Stdout:<nil> Stderr:<nil> ExtraFiles:[] SysProcAttr:<nil> Process:<nil> ProcessState:<nil> ctx:<nil> lookPathErr:<nil> finished:false childFiles:[] closeAfterStart:[] closeAfterWait:[] goroutine:[] errch:<nil> waitDone:<nil>} -I1115 09:41:19.118175 4143292 daemon.go:186] Starting ptp4l... -I1115 09:41:19.118209 4143292 daemon.go:187] ptp4l cmd: &{Path:/usr/sbin/ptp4l Args:[/usr/sbin/ptp4l -m -f /etc/ptp4l.conf -i ens787f1 -s -2] Env:[] Dir: Stdin:<nil> Stdout:<nil> Stderr:<nil> ExtraFiles:[] SysProcAttr:<nil> Process:<nil> ProcessState:<nil> ctx:<nil> lookPathErr:<nil> finished:false childFiles:[] closeAfterStart:[] closeAfterWait:[] goroutine:[] errch:<nil> waitDone:<nil>} -ptp4l[102189.864]: selected /dev/ptp5 as PTP clock -ptp4l[102189.886]: port 1: INITIALIZING to LISTENING on INIT_COMPLETE -ptp4l[102189.886]: port 0: INITIALIZING to LISTENING on INIT_COMPLETE ----- -<1> `Profile Name` is the name that is applied to node `dev-worker-0`. -<2> `Interface` is the PTP device specified in the `profile1` interface field. The `ptp4l` service runs on this interface. -<3> `Ptp4lOpts` are the ptp4l sysconfig options specified in `profile1` Ptp4lOpts field. -<4> `Phc2sysOpts` are the phc2sys sysconfig options specified in `profile1` Phc2sysOpts field. diff --git a/modules/nw-ptp-device-discovery.adoc b/modules/nw-ptp-device-discovery.adoc deleted file mode 100644 index 63df5eed1b09..000000000000 --- a/modules/nw-ptp-device-discovery.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-ptp.adoc - -[id="discover-ptp-devices_{context}"] -= Automated discovery of PTP network devices - -The PTP Operator adds the `NodePtpDevice.ptp.openshift.io` custom resource definition (CRD) to {product-title}. -The PTP Operator will search your cluster for PTP capable network devices on each node. The Operator creates and updates a `NodePtpDevice` custom resource (CR) object for each node that provides a compatible PTP device. - -One CR is created for each node, and shares the same name as the node. -The `.status.devices` list provides information about the PTP devices on a node. - -The following is an example of a `NodePtpDevice` CR created by the PTP Operator: - -[source,yaml] ----- -apiVersion: ptp.openshift.io/v1 -kind: NodePtpDevice -metadata: - creationTimestamp: "2019-11-15T08:57:11Z" - generation: 1 - name: dev-worker-0 <1> - namespace: openshift-ptp <2> - resourceVersion: "487462" - selfLink: /apis/ptp.openshift.io/v1/namespaces/openshift-ptp/nodeptpdevices/dev-worker-0 - uid: 08d133f7-aae2-403f-84ad-1fe624e5ab3f -spec: {} -status: - devices: <3> - - name: eno1 - - name: eno2 - - name: ens787f0 - - name: ens787f1 - - name: ens801f0 - - name: ens801f1 - - name: ens802f0 - - name: ens802f1 - - name: ens803 ----- -<1> The value for the `name` parameter is the same as the name of the node. -<2> The CR is created in `openshift-ptp` namespace by PTP Operator. -<3> The `devices` collection includes a list of all of the PTP capable devices discovered by the Operator on the node. diff --git a/modules/nw-ptp-installing-operator.adoc b/modules/nw-ptp-installing-operator.adoc deleted file mode 100644 index 5c2edd7622f2..000000000000 --- a/modules/nw-ptp-installing-operator.adoc +++ /dev/null @@ -1,139 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/multiple_networks/configuring-ptp.adoc - -[id="installing-ptp-operator_{context}"] -= Installing the PTP Operator - -As a cluster administrator, you can install the PTP Operator using the {product-title} CLI or the web console. - -[id="install-ptp-operator-cli_{context}"] -== CLI: Installing the PTP Operator - -As a cluster administrator, you can install the Operator using the CLI. - -.Prerequisites - -* A cluster installed on bare-metal hardware with nodes that have hardware that supports PTP. -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. To create a namespace for the PTP Operator, enter the following command: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-ptp - labels: - name: openshift-ptp - openshift.io/cluster-monitoring: "true" -EOF ----- - -. To create an Operator group for the Operator, enter the following command: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: ptp-operators - namespace: openshift-ptp -spec: - targetNamespaces: - - openshift-ptp -EOF ----- - -. Subscribe to the PTP Operator. - -.. Run the following command to set the {product-title} major and minor version as an environment variable, which is used as the `channel` value in the next -step. -+ -[source,terminal] ----- -$ OC_VERSION=$(oc version -o yaml | grep openshiftVersion | \ - grep -o '[0-9]*[.][0-9]*' | head -1) ----- - -.. To create a subscription for the PTP Operator, enter the following command: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: ptp-operator-subscription - namespace: openshift-ptp -spec: - channel: "${OC_VERSION}" - name: ptp-operator - source: redhat-operators - sourceNamespace: openshift-marketplace -EOF ----- - -. To verify that the Operator is installed, enter the following command: -+ -[source,terminal] ----- -$ oc get csv -n openshift-ptp \ - -o custom-columns=Name:.metadata.name,Phase:.status.phase ----- -+ -.Example output -[source,terminal] ----- -Name Phase -ptp-operator.4.4.0-202006160135 Succeeded ----- - -[id="install-ptp-operator-web-console_{context}"] -== Web console: Installing the PTP Operator - -As a cluster administrator, you can install the Operator using the web console. - -[NOTE] -==== -You have to create the namespace and operator group as mentioned -in the previous section. -==== - -.Procedure - -. Install the PTP Operator using the {product-title} web console: - -.. In the {product-title} web console, click *Operators* -> *OperatorHub*. - -.. Choose *PTP Operator* from the list of available Operators, and then click *Install*. - -.. On the *Install Operator* page, under *A specific namespace on the cluster* select *openshift-ptp*. Then, click *Install*. - -. Optional: Verify that the PTP Operator installed successfully: - -.. Switch to the *Operators* -> *Installed Operators* page. - -.. Ensure that *PTP Operator* is listed in the *openshift-ptp* project with a *Status* of *InstallSucceeded*. -+ -[NOTE] -==== -During installation an Operator might display a *Failed* status. -If the installation later succeeds with an *InstallSucceeded* message, you can ignore the *Failed* message. -==== - -+ -If the operator does not appear as installed, to troubleshoot further: - -+ -* Go to the *Operators* -> *Installed Operators* page and inspect -the *Operator Subscriptions* and *Install Plans* tabs for any failure or errors -under *Status*. -* Go to the *Workloads* -> *Pods* page and check the logs for pods in the -`openshift-ptp` project. diff --git a/modules/nw-route-admission-policy.adoc b/modules/nw-route-admission-policy.adoc deleted file mode 100644 index 0bcba0baf089..000000000000 --- a/modules/nw-route-admission-policy.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configure-ingress-operator.adoc -// * networking/routes/route-configuration.adoc - -[id="nw-route-admission-policy_{context}"] -= Configuring the route admission policy - -Administrators and application developers can run applications in multiple namespaces with the same domain name. This is for organizations where multiple teams develop microservices that are exposed on the same host name. - -[WARNING] -==== -Allowing claims across namespaces should only be enabled for clusters with trust between namespaces, otherwise a malicious user could take over a host name. For this reason, the default admission policy disallows host name claims across namespaces. -==== - -.Prerequisites - -* Cluster administrator privileges. - -.Procedure - -* Edit the `.spec.routeAdmission` field of the `ingresscontroller` resource variable using the following command: -+ -[source,terminal] ----- -$ oc -n openshift-ingress-operator patch ingresscontroller/default --patch '{"spec":{"routeAdmission":{"namespaceOwnership":"InterNamespaceAllowed"}}}' --type=merge ----- -+ -.Sample Ingress Controller configuration -[source,yaml] ----- -spec: - routeAdmission: - namespaceOwnership: InterNamespaceAllowed -... ----- diff --git a/modules/nw-route-specific-annotations.adoc b/modules/nw-route-specific-annotations.adoc deleted file mode 100644 index 40887bf84fea..000000000000 --- a/modules/nw-route-specific-annotations.adoc +++ /dev/null @@ -1,144 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/routes/route-configuration.adoc - -[id="nw-route-specific-annotations_{context}"] -= Route-specific annotations - -The Ingress Controller can set the default options for all the routes it exposes. An individual route can override some of these defaults by providing specific configurations in its annotations. - - -//For all the variables outlined in this section, you can set annotations on the -//*route definition* for the route to alter its configuration. - -.Route annotations -[cols="3*", options="header"] -|=== -|Variable | Description | Environment variable used as default -|`haproxy.router.openshift.io/balance`| Sets the load-balancing algorithm. Available options are `source`, `roundrobin`, and `leastconn`. | `ROUTER_TCP_BALANCE_SCHEME` for passthrough routes. Otherwise, use `ROUTER_LOAD_BALANCE_ALGORITHM`. -|`haproxy.router.openshift.io/disable_cookies`| Disables the use of cookies to track related connections. If set to `true` or `TRUE`, the balance algorithm is used to choose which back-end serves connections for each incoming HTTP request. | -|`router.openshift.io/cookie_name`| Specifies an optional cookie to use for -this route. The name must consist of any combination of upper and lower case letters, digits, "_", -and "-". The default is the hashed internal key name for the route. | -|`haproxy.router.openshift.io/pod-concurrent-connections`| Sets the maximum number of connections that are allowed to a backing pod from a router. Note: if there are multiple pods, each can have this many connections. But if you have multiple routers, there is no coordination among them, each may connect this many times. If not set, or set to 0, there is no limit. | -|`haproxy.router.openshift.io/rate-limit-connections`| Setting `true` or `TRUE` to enables rate limiting functionality. | -|`haproxy.router.openshift.io/rate-limit-connections.concurrent-tcp`| Limits the number of concurrent TCP connections shared by an IP address. | -|`haproxy.router.openshift.io/rate-limit-connections.rate-http`| Limits the rate at which an IP address can make HTTP requests. | -|`haproxy.router.openshift.io/rate-limit-connections.rate-tcp`| Limits the rate at which an IP address can make TCP connections. | -|`haproxy.router.openshift.io/timeout` | Sets a server-side timeout for the route. (TimeUnits) | `ROUTER_DEFAULT_SERVER_TIMEOUT` -|`router.openshift.io/haproxy.health.check.interval`| Sets the interval for the back-end health checks. (TimeUnits) | `ROUTER_BACKEND_CHECK_INTERVAL` -|`haproxy.router.openshift.io/ip_whitelist` -| Sets a whitelist for the route. The whitelist is a space-separated list of IP addresses and CIDR ranges for the approved source addresses. Requests from IP addresses that are not in the whitelist are dropped. | -|`haproxy.router.openshift.io/hsts_header` | Sets a Strict-Transport-Security header for the edge terminated or re-encrypt route. | -|`haproxy.router.openshift.io/log-send-hostname` | Sets the `hostname` field in the Syslog header. Uses the host name of the system. `log-send-hostname` is enabled by default if any Ingress API logging method, such as sidecar or Syslog facility, is enabled for the router. | -|`haproxy.router.openshift.io/rewrite-target` | Sets the rewrite path of the request on the backend. | -|`haproxy.router.openshift.io/cookie-same-site` | Sets a value to restrict cookies. The values are: - -`Lax`: cookies are transferred between the visited site and third-party sites. - -`Strict`: cookies are restricted to the visited site. - -`None`: cookies are restricted to the visited site. - -This value is applicable to re-encrypt and edge routes only. For more information, see the link:https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite cookies documentation].| - -|`haproxy.router.openshift.io/set-forwarded-headers` | Sets the policy for handling the `Forwarded` and `X-Forwarded-For` HTTP headers per route. The values are: - -`append`: appends the header, preserving any existing header. This is the default value. - -`replace`: sets the header, removing any existing header. - -`never`: never sets the header, but preserves any existing header. - -`if-none`: sets the header if it is not already set.| `ROUTER_SET_FORWARDED_HEADERS` - -|=== - -[NOTE] -==== -Environment variables cannot be edited. -==== - -.A route setting custom timeout -[source,yaml] ----- -apiVersion: v1 -kind: Route -metadata: - annotations: - haproxy.router.openshift.io/timeout: 5500ms <1> -... ----- -<1> Specifies the new timeout with HAProxy supported units (`us`, `ms`, `s`, `m`, `h`, `d`). If the unit is not provided, `ms` is the default. - -[NOTE] -==== -Setting a server-side timeout value for passthrough routes too low can cause -WebSocket connections to timeout frequently on that route. -==== - -.A route that allows only one specific IP address -[source,yaml] ----- -metadata: - annotations: - haproxy.router.openshift.io/ip_whitelist: 192.168.1.10 ----- - -.A route that allows several IP addresses -[source,yaml] ----- -metadata: - annotations: - haproxy.router.openshift.io/ip_whitelist: 192.168.1.10 192.168.1.11 192.168.1.12 ----- - -.A route that allows an IP address CIDR network -[source,yaml] ----- -metadata: - annotations: - haproxy.router.openshift.io/ip_whitelist: 192.168.1.0/24 ----- - -.A route that allows both IP an address and IP address CIDR networks -[source,yaml] ----- -metadata: - annotations: - haproxy.router.openshift.io/ip_whitelist: 180.5.61.153 192.168.1.0/24 10.0.0.0/8 ----- - -.A route specifying a rewrite target -[source,yaml] ----- -apiVersion: v1 -kind: Route -metadata: - annotations: - haproxy.router.openshift.io/rewrite-target: / <1> -... ----- -<1> Sets `/` as rewrite path of the request on the backend. - -Setting the `haproxy.router.openshift.io/rewrite-target` annotation on a route specifies that the Ingress Controller should rewrite paths in HTTP requests using this route before forwarding the requests to the backend application. -The part of the request path that matches the path specified in `spec.path` is replaced with the rewrite target specified in the annotation. - -The following table provides examples of the path rewriting behavior for various combinations of `spec.path`, request path, and rewrite target. - -.rewrite-target examples: -[cols="4*", options="header"] -|=== -|Route.spec.path|Request path|Rewrite target| Forwarded request path -|/foo|/foo|/|/ -|/foo|/foo/|/|/ -|/foo|/foo/bar|/|/bar -|/foo|/foo/bar/|/|/bar/ -|/foo|/foo|/bar|/bar -|/foo|/foo/|/bar|/bar/ -|/foo|/foo/bar|/baz|/baz/bar -|/foo|/foo/bar/|/baz|/baz/bar/ -|/foo/|/foo|/|N/A (request path does not match route path) -|/foo/|/foo/|/|/ -|/foo/|/foo/bar|/|/bar -|=== diff --git a/modules/nw-scaling-ingress-controller.adoc b/modules/nw-scaling-ingress-controller.adoc deleted file mode 100644 index 7707a5895213..000000000000 --- a/modules/nw-scaling-ingress-controller.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module filename: nw-scaling-ingress-controller.adoc -// Module included in the following assemblies: -// * networking/ingress-controller-configuration.adoc - -[id="nw-ingress-controller-configuration_{context}"] -= Scaling an Ingress Controller - -Manually scale an Ingress Controller to meeting routing performance or -availability requirements such as the requirement to increase throughput. `oc` -commands are used to scale the `IngressController` resource. The following -procedure provides an example for scaling up the default `IngressController`. - -.Procedure -. View the current number of available replicas for the default `IngressController`: -+ -[source,terminal] ----- -$ oc get -n openshift-ingress-operator ingresscontrollers/default -o jsonpath='{$.status.availableReplicas}' ----- -+ -.Example output -[source,terminal] ----- -2 ----- - -. Scale the default `IngressController` to the desired number of replicas using -the `oc patch` command. The following example scales the default `IngressController` -to 3 replicas: -+ -[source,terminal] ----- -$ oc patch -n openshift-ingress-operator ingresscontroller/default --patch '{"spec":{"replicas": 3}}' --type=merge ----- -+ -.Example output -[source,terminal] ----- -ingresscontroller.operator.openshift.io/default patched ----- - -. Verify that the default `IngressController` scaled to the number of replicas -that you specified: -+ -[source,terminal] ----- -$ oc get -n openshift-ingress-operator ingresscontrollers/default -o jsonpath='{$.status.availableReplicas}' ----- -+ -.Example output -[source,terminal] ----- -3 ----- - -[NOTE] -==== -Scaling is not an immediate action, as it takes time to create the desired number of replicas. -==== diff --git a/modules/nw-sctp-about.adoc b/modules/nw-sctp-about.adoc deleted file mode 100644 index 8e399516ddbd..000000000000 --- a/modules/nw-sctp-about.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/using-sctp.adoc - -[id="nw-sctp-about_{context}"] -= Support for Stream Control Transmission Protocol (SCTP) on {product-title} - -As a cluster administrator, you can enable SCTP on the hosts in the cluster. -On {op-system-first}, the SCTP module is disabled by default. - -SCTP is a reliable message based protocol that runs on top of an IP network. - -When enabled, you can use SCTP as a protocol with pods, services, and network policy. -A `Service` object must be defined with the `type` parameter set to either the `ClusterIP` or `NodePort` value. - -[id="example_configurations_{context}"] -== Example configurations using SCTP protocol - -You can configure a pod or service to use SCTP by setting the `protocol` parameter to the `SCTP` value in the pod or service object. - -In the following example, a pod is configured to use SCTP: - -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - namespace: project1 - name: example-pod -spec: - containers: - - name: example-pod -... - ports: - - containerPort: 30100 - name: sctpserver - protocol: SCTP ----- - -In the following example, a service is configured to use SCTP: - -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - namespace: project1 - name: sctpserver -spec: -... - ports: - - name: sctpserver - protocol: SCTP - port: 30100 - targetPort: 30100 - type: ClusterIP ----- - -In the following example, a `NetworkPolicy` object is configured to apply to SCTP network traffic on port `80` from any pods with a specific label: - -[source,yaml] ----- -kind: NetworkPolicy -apiVersion: networking.k8s.io/v1 -metadata: - name: allow-sctp-on-http -spec: - podSelector: - matchLabels: - role: web - ingress: - - ports: - - protocol: SCTP - port: 80 ----- diff --git a/modules/nw-sctp-enabling.adoc b/modules/nw-sctp-enabling.adoc deleted file mode 100644 index c98d652759de..000000000000 --- a/modules/nw-sctp-enabling.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/using-sctp.adoc - -[id="nw-sctp-enabling_{context}"] -= Enabling Stream Control Transmission Protocol (SCTP) - -As a cluster administrator, you can load and enable the blacklisted SCTP kernel module on worker nodes in your cluster. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Create a file named `load-sctp-module.yaml` that contains the following YAML definition: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: load-sctp-module -spec: - config: - ignition: - version: 3.1.0 - storage: - files: - - contents: - source: data:, - mode: 420 - overwrite: true - path: /etc/modprobe.d/sctp-blacklist.conf - - contents: - source: data:text/plain;charset=utf-8,sctp - mode: 420 - overwrite: true - path: /etc/modules-load.d/sctp-load.conf ----- - -. To create the `MachineConfig` object, enter the following command: -+ -[source,terminal] ----- -$ oc create -f load-sctp-module.yaml ----- - -. Optional: To watch the status of the nodes while the MachineConfig Operator applies the configuration change, enter the following command. When the status of a node transitions to `Ready`, the configuration update is applied. -+ -[source,terminal] ----- -$ oc get nodes ----- diff --git a/modules/nw-sctp-verifying.adoc b/modules/nw-sctp-verifying.adoc deleted file mode 100644 index 2846780bc490..000000000000 --- a/modules/nw-sctp-verifying.adoc +++ /dev/null @@ -1,153 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/using-sctp.adoc - -:image: registry.access.redhat.com/ubi8/ubi - -ifdef::openshift-origin[] -:image: fedora:31 -endif::[] - -[id="nw-sctp-verifying_{context}"] -= Verifying Stream Control Transmission Protocol (SCTP) is enabled - -You can verify that SCTP is working on a cluster by creating a pod with an application that listens for SCTP traffic, associating it with a service, and then connecting to the exposed service. - -.Prerequisites - -* Access to the Internet from the cluster to install the `nc` package. -* Install the OpenShift CLI (`oc`). -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Create a pod starts an SCTP listener: - -.. Create a file named `sctp-server.yaml` that defines a pod with the following YAML: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: v1 -kind: Pod -metadata: - name: sctpserver - labels: - app: sctpserver -spec: - containers: - - name: sctpserver - image: {image} - command: ["/bin/sh", "-c"] - args: - ["dnf install -y nc && sleep inf"] - ports: - - containerPort: 30102 - name: sctpserver - protocol: SCTP ----- - -.. Create the pod by entering the following command: -+ -[source,terminal] ----- -$ oc create -f sctp-server.yaml ----- - -. Create a service for the SCTP listener pod. - -.. Create a file named `sctp-service.yaml` that defines a service with the following YAML: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: sctpservice - labels: - app: sctpserver -spec: - type: NodePort - selector: - app: sctpserver - ports: - - name: sctpserver - protocol: SCTP - port: 30102 - targetPort: 30102 ----- - -.. To create the service, enter the following command: -+ -[source,terminal] ----- -$ oc create -f sctp-service.yaml ----- - -. Create a pod for the SCTP client. - -.. Create a file named `sctp-client.yaml` with the following YAML: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: v1 -kind: Pod -metadata: - name: sctpclient - labels: - app: sctpclient -spec: - containers: - - name: sctpclient - image: {image} - command: ["/bin/sh", "-c"] - args: - ["dnf install -y nc && sleep inf"] ----- - -.. To create the `Pod` object, enter the following command: -+ -[source,terminal] ----- -$ oc apply -f sctp-client.yaml ----- - -. Run an SCTP listener on the server. - -.. To connect to the server pod, enter the following command: -+ -[source,terminal] ----- -$ oc rsh sctpserver ----- - -.. To start the SCTP listener, enter the following command: -+ -[source,terminal] ----- -$ nc -l 30102 --sctp ----- - -. Connect to the SCTP listener on the server. - -.. Open a new terminal window or tab in your terminal program. - -.. Obtain the IP address of the `sctpservice` service. Enter the following command: -+ -[source,terminal] ----- -$ oc get services sctpservice -o go-template='{{.spec.clusterIP}}{{"\n"}}' ----- - -.. To connect to the client pod, enter the following command: -+ -[source,terminal] ----- -$ oc rsh sctpclient ----- - -.. To start the SCTP client, enter the following command. Replace `<cluster_IP>` with the cluster IP address of the `sctpservice` service. -+ -[source,terminal] ----- -# nc <cluster_IP> 30102 --sctp ----- diff --git a/modules/nw-service-externalip-create.adoc b/modules/nw-service-externalip-create.adoc deleted file mode 100644 index 5bb4aad4f526..000000000000 --- a/modules/nw-service-externalip-create.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc - -[id="nw-service-externalip-create_{context}"] -= Attaching an ExternalIP to a service - -You can attach an ExternalIP to a service. If your cluster is configured to allocate an ExternalIP automatically, you might not need to manually attach an ExternalIP to the service. - -.Procedure - -. Optional: To confirm what IP address ranges are configured for use with ExternalIP, enter the following command: -+ -[source,terminal] ----- -$ oc get networks.config cluster -o jsonpath='{.spec.externalIP}{"\n"}' ----- -+ -If `autoAssignCIDRs` is set, {product-title} automatically assigns an ExternalIP to a new `Service` object if the `spec.externalIPs` field is not specified. - -. Attach an ExternalIP to the service. - -.. If you are creating a new service, specify the `spec.externalIPs` field and provide an array of one or more valid IP addresses. For example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: svc-with-externalip -spec: - ... - externalIPs: - - 192.174.120.10 ----- - -.. If you are attaching an ExternalIP to an existing service, enter the following command. Replace `<name>` with the service name. Replace `<ip_address>` with a valid ExternalIP address. You can provide multiple IP addresses separated by commas. -+ -[source,terminal] ----- -$ oc patch svc <name> -p \ - '{ - "spec": { - "externalIPs": [ "<ip_address>" ] - } - }' ----- -+ -For example: -+ -[source,terminal] ----- -$ oc patch svc mysql-55-rhel7 -p '{"spec":{"externalIPs":["192.174.120.10"]}}' ----- -+ -.Example output -[source,terminal] ----- -"mysql-55-rhel7" patched ----- - -. To confirm that an ExternalIP address is attached to the service, enter the following command. If you specified an ExternalIP for a new service, you must create the service first. -+ -[source,terminal] ----- -$ oc get svc ----- -+ -.Example output -[source,terminal] ----- -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -mysql-55-rhel7 172.30.131.89 192.174.120.10 3306/TCP 13m ----- diff --git a/modules/nw-sriov-add-pod-runtimeconfig.adoc b/modules/nw-sriov-add-pod-runtimeconfig.adoc deleted file mode 100644 index f44f960dcafc..000000000000 --- a/modules/nw-sriov-add-pod-runtimeconfig.adoc +++ /dev/null @@ -1,103 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-configuring-sr-iov-network.adoc -// * virt/virtual_machines/vm_networking/virt-defining-an-sriov-network.adoc - -// Deprecating in OCP; This is identical in practice to adding a pod -// to an additional network. - -[id="nw-sriov-add-pod-runtimeconfig_{context}"] -= Configuring static MAC and IP addresses on additional SR-IOV networks - -You can configure static MAC and IP addresses on an SR-IOV network by specifying Container Network Interface (CNI) `runtimeConfig` data in a pod annotation. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges when creating the `SriovNetwork` object. - -.Procedure - -. Create the following `SriovNetwork` object, and then save the YAML in the `<name>-sriov-network.yaml` file. Replace `<name>` with a name for this additional network. -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetwork -metadata: - name: <name> <1> - namespace: openshift-sriov-network-operator <2> -spec: - networkNamespace: <target_namespace> <3> - ipam: '{ "type": "static" }' <4> - capabilities: '{ "mac": true, "ips": true }' <5> - resourceName: <sriov_resource_name> <6> ----- -<1> Replace `<name>` with a name for the object. The SR-IOV Network Operator creates a `NetworkAttachmentDefinition` object with same name. -<2> Specify the namespace where the SR-IOV Network Operator is installed. -<3> Replace `<target_namespace>` with the namespace where the `NetworkAttachmentDefinition` object is created. -<4> Specify static type for the ipam CNI plug-in as a YAML block scalar. -<5> Specify `mac` and `ips` `capabilities` to `true`. -<6> Replace `<sriov_resource_name>` with the value for the `spec.resourceName` parameter from the `SriovNetworkNodePolicy` object that defines the SR-IOV hardware for this additional network. - -. Create the object by running the following command: -+ -[source,terminal] ----- -$ oc create -f <filename> <1> ----- -<1> Replace `<filename>` with the name of the file you created in the previous step. - -. Optional: Confirm that the NetworkAttachmentDefinition CR associated with the `SriovNetwork` object that you created in the previous step exists by running the following command. Replace `<namespace>` with the namespace you specified in the `SriovNetwork` object. -+ -[source,terminal] ----- -$ oc get net-attach-def -n <namespace> ----- - -[NOTE] -===== -Do not modify or delete a `SriovNetwork` custom resource (CR) if it is attached to any pods in the `running` state. -===== - -. Create the following SR-IOV pod spec, and then save the YAML in the `<name>-sriov-pod.yaml` file. Replace `<name>` with a name for this pod. -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: sample-pod - annotations: - k8s.v1.cni.cncf.io/networks: '[ - { - "name": "<name>", <1> - "mac": "20:04:0f:f1:88:01", <2> - "ips": ["192.168.10.1/24", "2001::1/64"] <3> - } -]' -spec: - containers: - - name: sample-container - image: <image> - imagePullPolicy: IfNotPresent - command: ["sleep", "infinity"] ----- -<1> Specify the name of the SR-IOV network attachment definition CR. -<2> Specify the MAC address for the SR-IOV device that is allocated from the resource type defined in the SR-IOV network attachment definition CR. -<3> Specify addresses for the SR-IOV device which is allocated from the resource type defined in the SR-IOV network attachment definition CR. Both IPv4 and IPv6 addresses are supported. - -. Create the sample SR-IOV pod by running the following command: -+ -[source,terminal] ----- -$ oc create -f <filename> <1> ----- -<1> Replace `<filename>` with the name of the file you created in the previous step. - -. Optional: Confirm that `mac` and `ips` addresses are applied to the SR-IOV device by running the following command. Replace `<namespace>` with the namespace you specified in the `SriovNetwork` object. -+ -[source,terminal] ----- -$ oc exec sample-pod -n <namespace> -- ip addr show ----- diff --git a/modules/nw-sriov-app-netutil.adoc b/modules/nw-sriov-app-netutil.adoc deleted file mode 100644 index 174906f89e6e..000000000000 --- a/modules/nw-sriov-app-netutil.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/about-sriov.adoc - -[id="nw-sriov-app-netutil_{context}"] -= DPDK library for use with container applications - -An link:https://github.com/openshift/app-netutil[optional library], `app-netutil`, provides several API methods for gathering network information about a pod from within a container running within that pod. - -This library is intended to assist with integrating SR-IOV virtual functions (VFs) in Data Plane Development Kit (DPDK) mode into the container. -The library provides both a Golang API and a C API. - -Currently there are three API methods implemented: - -`GetCPUInfo()`:: This function determines which CPUs are available to the container and returns the list to the caller. - -`GetHugepages()`:: This function determines the amount of hugepage memory requested in the `Pod` spec for each container and returns the values to the caller. -+ -[NOTE] -==== -Exposing hugepages via Kubernetes Downward API is an alpha feature in Kubernetes 1.20 and is not enabled in {product-title}. The API can be tested by enabling the feature gate, `FEATURE_GATES="DownwardAPIHugePages=true"` on Kubernetes 1.20 or greater. -==== - -`GetInterfaces()`:: This function determines the set of interfaces in the container and returns the list, along with the interface type and type specific data. - -There is also a sample Docker image, `dpdk-app-centos`, which can run one of the following DPDK sample applications based on an environmental variable in the pod-spec: `l2fwd`, `l3wd` or `testpmd`. This Docker image provides an example of integrating the `app-netutil` into the container image itself. The library can also integrate into an `init-container` which collects the required data and passes the data to an existing DPDK workload. diff --git a/modules/nw-sriov-configuring-device.adoc b/modules/nw-sriov-configuring-device.adoc deleted file mode 100644 index 6187d8194c3f..000000000000 --- a/modules/nw-sriov-configuring-device.adoc +++ /dev/null @@ -1,106 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/configuring-sriov-device.adoc -// * virt/node_network/virt-configuring-sriov-device-for-vms.adoc - -ifeval::["{context}" == "configuring-sriov-device"] -:ocp-sriov: -endif::[] - -ifeval::["{context}" == "virt-configuring-sriov-device-for-vms"] -:virt-sriov: -endif::[] - -[id="nw-sriov-configuring-device_{context}"] -= Configuring SR-IOV network devices - -The SR-IOV Network Operator adds the `SriovNetworkNodePolicy.sriovnetwork.openshift.io` CustomResourceDefinition to {product-title}. -You can configure an SR-IOV network device by creating a SriovNetworkNodePolicy custom resource (CR). - -[NOTE] -===== -When applying the configuration specified in a `SriovNetworkNodePolicy` object, the SR-IOV Operator might drain the nodes, and in some cases, reboot nodes. - -It might take several minutes for a configuration change to apply. -===== - -.Prerequisites - -* You installed the OpenShift CLI (`oc`). -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the SR-IOV Network Operator. -* You have enough available nodes in your cluster to handle the evicted workload from drained nodes. -* You have not selected any control plane nodes for SR-IOV network device configuration. - -.Procedure - -. Create an `SriovNetworkNodePolicy` object, and then save the YAML in the `<name>-sriov-node-network.yaml` file. Replace `<name>` with the name for this configuration. - -ifdef::virt-sriov[] -// The list breaks because of the [NOTE] -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: <name> <1> - namespace: openshift-sriov-network-operator <2> -spec: - resourceName: <sriov_resource_name> <3> - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" <4> - priority: <priority> <5> - mtu: <mtu> <6> - numVfs: <num> <7> - nicSelector: <8> - vendor: "<vendor_code>" <9> - deviceID: "<device_id>" <10> - pfNames: ["<pf_name>", ...] <11> - rootDevices: ["<pci_bus_id>", "..."] <12> - deviceType: vfio-pci <13> - isRdma: false <14> ----- -<1> Specify a name for the CR object. -<2> Specify the namespace where the SR-IOV Operator is installed. -<3> Specify the resource name of the SR-IOV device plug-in. You can create multiple `SriovNetworkNodePolicy` objects for a resource name. -<4> Specify the node selector to select which nodes are configured. -Only SR-IOV network devices on selected nodes are configured. The SR-IOV -Container Network Interface (CNI) plug-in and device plug-in are deployed only on selected nodes. -<5> Optional: Specify an integer value between `0` and `99`. A smaller number gets higher priority, so a priority of `10` is higher than a priority of `99`. The default value is `99`. -<6> Optional: Specify a value for the maximum transmission unit (MTU) of the virtual function. The maximum MTU value can vary for different NIC models. -<7> Specify the number of the virtual functions (VF) to create for the SR-IOV physical network device. For an Intel Network Interface Card (NIC), the number of VFs cannot be larger than the total VFs supported by the device. For a Mellanox NIC, the number of VFs cannot be larger than `128`. -<8> The `nicSelector` mapping selects the Ethernet device for the Operator to configure. You do not need to specify values for all the parameters. It is recommended to identify the Ethernet adapter with enough precision to minimize the possibility of selecting an Ethernet device unintentionally. -If you specify `rootDevices`, you must also specify a value for `vendor`, `deviceID`, or `pfNames`. -If you specify both `pfNames` and `rootDevices` at the same time, ensure that they point to an identical device. -<9> Optional: Specify the vendor hex code of the SR-IOV network device. The only allowed values are either `8086` or `15b3`. -<10> Optional: Specify the device hex code of SR-IOV network device. The only allowed values are `158b`, `1015`, `1017`. -<11> Optional: The parameter accepts an array of one or more physical function (PF) names for the Ethernet device. -<12> The parameter accepts an array of one or more PCI bus addresses for the physical function of the Ethernet device. Provide the address in the following format: `0000:02:00.1`. -<13> The `vfio-pci` driver type is required for virtual functions in {VirtProductName}. -<14> Optional: Specify whether to enable remote direct memory access (RDMA) mode. For a Mellanox card, set `isRdma` to `false`. The default value is `false`. -+ -[NOTE] -==== -If `isRDMA` flag is set to `true`, you can continue to use the RDMA enabled VF as a normal network device. -A device can be used in either mode. -==== -endif::virt-sriov[] - -[start=2] -. Create the `SriovNetworkNodePolicy` object: -+ -[source,terminal] ----- -$ oc create -f <name>-sriov-node-network.yaml ----- -+ -where `<name>` specifies the name for this configuration. -+ -After applying the configuration update, all the pods in `sriov-network-operator` namespace transition to the `Running` status. - -. To verify that the SR-IOV network device is configured, enter the following command. Replace `<node_name>` with the name of a node with the SR-IOV network device that you just configured. -+ -[source,terminal] ----- -$ oc get sriovnetworknodestates -n openshift-sriov-network-operator <node_name> -o jsonpath='{.status.syncStatus}' ----- diff --git a/modules/nw-sriov-configuring-operator.adoc b/modules/nw-sriov-configuring-operator.adoc deleted file mode 100644 index 142e9d0dd686..000000000000 --- a/modules/nw-sriov-configuring-operator.adoc +++ /dev/null @@ -1,161 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/configuring-sriov-operator.adoc - -[id="nw-sriov-configuring-operator_{context}"] -= Configuring the SR-IOV Network Operator - -[IMPORTANT] -==== -Modifying the SR-IOV Network Operator configuration is not normally necessary. -The default configuration is recommended for most use cases. -Complete the steps to modify the relevant configuration only if the default behavior of the Operator is not compatible with your use case. -==== - -The SR-IOV Network Operator adds the `SriovOperatorConfig.sriovnetwork.openshift.io` CustomResourceDefinition resource. -The operator automatically creates a SriovOperatorConfig custom resource (CR) named `default` in the `openshift-sriov-network-operator` namespace. - -[NOTE] -===== -The `default` CR contains the SR-IOV Network Operator configuration for your cluster. -To change the operator configuration, you must modify this CR. -===== - -The `SriovOperatorConfig` object provides several fields for configuring the operator: - -* `enableInjector` allows project administrators to enable or disable the Network Resources Injector daemon set. -* `enableOperatorWebhook` allows project administrators to enable or disable the Operator Admission Controller webhook daemon set. -* `configDaemonNodeSelector` allows project administrators to schedule the SR-IOV Network Config Daemon on selected nodes. - -[id="about-network-resource-injector_{context}"] -== About the Network Resources Injector - -The Network Resources Injector is a Kubernetes Dynamic Admission Controller -application. It provides the following capabilities: - -* Mutation of resource requests and limits in `Pod` specification to add an SR-IOV resource name according to an SR-IOV network attachment definition annotation. -* Mutation of `Pod` specifications with downward API volume to expose pod annotations and labels to the running container as files under the `/etc/podnetinfo` path. - -By default the Network Resources Injector is enabled by the SR-IOV operator and runs as a daemon set on all master nodes. The following is an example of Network Resources Injector pods running in a cluster with three master nodes: - -[source,terminal] ----- -$ oc get pods -n openshift-sriov-network-operator ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -network-resources-injector-5cz5p 1/1 Running 0 10m -network-resources-injector-dwqpx 1/1 Running 0 10m -network-resources-injector-lktz5 1/1 Running 0 10m ----- - -[id="about-sr-iov-operator-admission-control-webhook_{context}"] -== About the SR-IOV Operator admission controller webhook - -The SR-IOV Operator Admission Controller webhook is a Kubernetes Dynamic -Admission Controller application. It provides the following capabilities: - -* Validation of the `SriovNetworkNodePolicy` CR when it is created or updated. -* Mutation of the `SriovNetworkNodePolicy` CR by setting the default value for the `priority` and `deviceType` fields when the CR is created or updated. - -By default the SR-IOV Operator Admission Controller webhook is enabled by the operator and runs as a daemon set on all master nodes. -The following is an example of the Operator Admission Controller webhook pods running in a cluster with three master nodes: - -[source,terminal] ----- -$ oc get pods -n openshift-sriov-network-operator ----- - -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -operator-webhook-9jkw6 1/1 Running 0 16m -operator-webhook-kbr5p 1/1 Running 0 16m -operator-webhook-rpfrl 1/1 Running 0 16m ----- - -[id="about-custom-node-selectors_{context}"] -== About custom node selectors - -The SR-IOV Network Config daemon discovers and configures the SR-IOV network devices on cluster nodes. -By default, it is deployed to all the `worker` nodes in the cluster. -You can use node labels to specify on which nodes the SR-IOV Network Config daemon runs. - -[id="disable-enable-network-resource-injector_{context}"] -== Disabling or enabling the Network Resources Injector - -To disable or enable the Network Resources Injector, which is enabled by default, complete the following procedure. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. -* You must have installed the SR-IOV Operator. - -.Procedure - -- Set the `enableInjector` field. Replace `<value>` with `false` to disable the feature or `true` to enable the feature. -+ -[source,terminal] ----- -$ oc patch sriovoperatorconfig default \ - --type=merge -n openshift-sriov-network-operator \ - --patch '{ "spec": { "enableInjector": <value> } }' ----- - -[id="disable-enable-sr-iov-operator-admission-control-webhook_{context}"] -== Disabling or enabling the SR-IOV Operator admission controller webhook - -To disable or enable the admission controller webhook, which is enabled by default, complete the following procedure. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. -* You must have installed the SR-IOV Operator. - -.Procedure - -- Set the `enableOperatorWebhook` field. Replace `<value>` with `false` to disable the feature or `true` to enable it: -+ -[source,terminal] ----- -$ oc patch sriovoperatorconfig default --type=merge \ - -n openshift-sriov-network-operator \ - --patch '{ "spec": { "enableOperatorWebhook": <value> } }' ----- - -[id="configuring-custom-nodeselector_{context}"] -== Configuring a custom NodeSelector for the SR-IOV Network Config daemon - -The SR-IOV Network Config daemon discovers and configures the SR-IOV network devices on cluster nodes. By default, it is deployed to all the `worker` nodes in the cluster. You can use node labels to specify on which nodes the SR-IOV Network Config daemon runs. - -To specify the nodes where the SR-IOV Network Config daemon is deployed, complete the following procedure. - -[IMPORTANT] -===== -When you update the `configDaemonNodeSelector` field, the SR-IOV Network Config daemon is recreated on each selected node. -While the daemon is recreated, cluster users are unable to apply any new SR-IOV Network node policy or create new SR-IOV pods. -===== - -.Procedure - -- To update the node selector for the operator, enter the following command: -+ -[source,terminal] ----- -$ oc patch sriovoperatorconfig default --type=json \ - -n openshift-sriov-network-operator \ - --patch '[{ - "op": "replace", - "path": "/spec/configDaemonNodeSelector", - "value": {<node-label>} - }]' ----- -+ -Replace `<node-label>` with a label to apply as in the following example: -`"node-role.kubernetes.io/worker": ""`. diff --git a/modules/nw-sriov-device-discovery.adoc b/modules/nw-sriov-device-discovery.adoc deleted file mode 100644 index c4133da166db..000000000000 --- a/modules/nw-sriov-device-discovery.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/configuring-sriov-device.adoc -// * virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc - -[id="discover-sr-iov-devices_{context}"] -= Automated discovery of SR-IOV network devices - -The SR-IOV Network Operator searches your cluster for SR-IOV capable network devices on worker nodes. -The Operator creates and updates a SriovNetworkNodeState custom resource (CR) for each worker node that provides a compatible SR-IOV network device. - -The CR is assigned the same name as the worker node. -The `status.interfaces` list provides information about the network devices on a node. - -[IMPORTANT] -==== -Do not modify a `SriovNetworkNodeState` object. -The Operator creates and manages these resources automatically. -==== - -[id="example-sriovnetworknodestate_{context}"] -== Example `SriovNetworkNodeState` object - -The following YAML is an example of a `SriovNetworkNodeState` object created by the SR-IOV Network Operator: - -.An SriovNetworkNodeState object -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodeState -metadata: - name: node-25 <1> - namespace: openshift-sriov-network-operator - ownerReferences: - - apiVersion: sriovnetwork.openshift.io/v1 - blockOwnerDeletion: true - controller: true - kind: SriovNetworkNodePolicy - name: default -spec: - dpConfigVersion: "39824" -status: - interfaces: <2> - - deviceID: "1017" - driver: mlx5_core - mtu: 1500 - name: ens785f0 - pciAddress: "0000:18:00.0" - totalvfs: 8 - vendor: 15b3 - - deviceID: "1017" - driver: mlx5_core - mtu: 1500 - name: ens785f1 - pciAddress: "0000:18:00.1" - totalvfs: 8 - vendor: 15b3 - - deviceID: 158b - driver: i40e - mtu: 1500 - name: ens817f0 - pciAddress: 0000:81:00.0 - totalvfs: 64 - vendor: "8086" - - deviceID: 158b - driver: i40e - mtu: 1500 - name: ens817f1 - pciAddress: 0000:81:00.1 - totalvfs: 64 - vendor: "8086" - - deviceID: 158b - driver: i40e - mtu: 1500 - name: ens803f0 - pciAddress: 0000:86:00.0 - totalvfs: 64 - vendor: "8086" - syncStatus: Succeeded ----- -<1> The value of the `name` field is the same as the name of the worker node. -<2> The `interfaces` stanza includes a list of all of the SR-IOV devices discovered by the Operator on the worker node. diff --git a/modules/nw-sriov-dpdk-example-intel.adoc b/modules/nw-sriov-dpdk-example-intel.adoc deleted file mode 100644 index c0481ff68c83..000000000000 --- a/modules/nw-sriov-dpdk-example-intel.adoc +++ /dev/null @@ -1,138 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/using-dpdk-and-rdma.adoc - -[id="example-vf-use-in-dpdk-mode-intel_{context}"] -= Using a virtual function in DPDK mode with an Intel NIC - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Install the SR-IOV Network Operator. -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create the following `SriovNetworkNodePolicy` object, and then save the YAML in the `intel-dpdk-node-policy.yaml` file. -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: intel-dpdk-node-policy - namespace: openshift-sriov-network-operator -spec: - resourceName: intelnics - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - priority: <priority> - numVfs: <num> - nicSelector: - vendor: "8086" - deviceID: "158b" - pfNames: ["<pf_name>", ...] - rootDevices: ["<pci_bus_id>", "..."] - deviceType: vfio-pci <1> ----- -<1> Specify the driver type for the virtual functions to `vfio-pci`. -+ -[NOTE] -===== -Please refer to the `Configuring SR-IOV network devices` section for a detailed explanation on each option in `SriovNetworkNodePolicy`. - -When applying the configuration specified in a `SriovNetworkNodePolicy` object, the SR-IOV Operator may drain the nodes, and in some cases, reboot nodes. -It may take several minutes for a configuration change to apply. -Ensure that there are enough available nodes in your cluster to handle the evicted workload beforehand. - -After the configuration update is applied, all the pods in `openshift-sriov-network-operator` namespace will change to a `Running` status. -===== - -. Create the `SriovNetworkNodePolicy` object by running the following command: -+ -[source,terminal] ----- -$ oc create -f intel-dpdk-node-policy.yaml ----- - -. Create the following `SriovNetwork` object, and then save the YAML in the `intel-dpdk-network.yaml` file. -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetwork -metadata: - name: intel-dpdk-network - namespace: openshift-sriov-network-operator -spec: - networkNamespace: <target_namespace> - ipam: "{}" <1> - vlan: <vlan> - resourceName: intelnics ----- -<1> Specify an empty object `"{}"` for the ipam CNI plug-in. DPDK works in userspace mode and does not require an IP address. -+ -[NOTE] -===== -Please refer to the `Configuring SR-IOV additional network` section for a detailed explanation on each option in `SriovNetwork`. -===== -+ -. Create the `SriovNetworkNodePolicy` object by running the following command: -+ -[source,terminal] ----- -$ oc create -f intel-dpdk-network.yaml ----- - -. Create the following `Pod` spec, and then save the YAML in the `intel-dpdk-pod.yaml` file. -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dpdk-app - namespace: <target_namespace> <1> - annotations: - k8s.v1.cni.cncf.io/networks: intel-dpdk-network -spec: - containers: - - name: testpmd - image: <DPDK_image> <2> - securityContext: - capabilities: - add: ["IPC_LOCK"] <3> - volumeMounts: - - mountPath: /dev/hugepages <4> - name: hugepage - resources: - limits: - openshift.io/intelnics: "1" <5> - memory: "1Gi" - cpu: "4" <6> - hugepages-1Gi: "4Gi" <7> - requests: - openshift.io/intelnics: "1" - memory: "1Gi" - cpu: "4" - hugepages-1Gi: "4Gi" - command: ["sleep", "infinity"] - volumes: - - name: hugepage - emptyDir: - medium: HugePages ----- -<1> Specify the same `target_namespace` where the `SriovNetwork` object `intel-dpdk-network` is created. If you would like to create the pod in a different namespace, change `target_namespace` in both the `Pod` spec and the `SriovNetowrk` object. -<2> Specify the DPDK image which includes your application and the DPDK library used by application. -<3> Specify the `IPC_LOCK` capability which is required by the application to allocate hugepage memory inside container. -<4> Mount a hugepage volume to the DPDK pod under `/dev/hugepages`. The hugepage volume is backed by the emptyDir volume type with the medium being `Hugepages`. -<5> Optional: Specify the number of DPDK devices allocated to DPDK pod. This resource request and limit, if not explicitly specified, will be automatically added by the SR-IOV network resource injector. The SR-IOV network resource injector is an admission controller component managed by the SR-IOV Operator. It is enabled by default and can be disabled by setting `enableInjector` option to `false` in the default `SriovOperatorConfig` CR. -<6> Specify the number of CPUs. The DPDK pod usually requires exclusive CPUs to be allocated from the kubelet. This is achieved by setting CPU Manager policy to `static` and creating a pod with `Guaranteed` QoS. -<7> Specify hugepage size `hugepages-1Gi` or `hugepages-2Mi` and the quantity of hugepages that will be allocated to the DPDK pod. Configure `2Mi` and `1Gi` hugepages separately. Configuring `1Gi` hugepage requires adding kernel arguments to Nodes. For example, adding kernel arguments `default_hugepagesz=1GB`, `hugepagesz=1G` and `hugepages=16` will result in `16*1Gi` hugepages be allocated during system boot. - -. Create the DPDK pod by running the following command: -+ -[source,terminal] ----- -$ oc create -f intel-dpdk-pod.yaml ----- diff --git a/modules/nw-sriov-dpdk-example-mellanox.adoc b/modules/nw-sriov-dpdk-example-mellanox.adoc deleted file mode 100644 index 87a322b0da03..000000000000 --- a/modules/nw-sriov-dpdk-example-mellanox.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/using-dpdk-and-rdma.adoc - -[id="example-vf-use-in-dpdk-mode-mellanox_{context}"] -= Using a virtual function in DPDK mode with a Mellanox NIC - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Install the SR-IOV Network Operator. -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create the following `SriovNetworkNodePolicy` object, and then save the YAML in the `mlx-dpdk-node-policy.yaml` file. -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: mlx-dpdk-node-policy - namespace: openshift-sriov-network-operator -spec: - resourceName: mlxnics - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - priority: <priority> - numVfs: <num> - nicSelector: - vendor: "15b3" - deviceID: "1015" <1> - pfNames: ["<pf_name>", ...] - rootDevices: ["<pci_bus_id>", "..."] - deviceType: netdevice <2> - isRdma: true <3> ----- -<1> Specify the device hex code of the SR-IOV network device. The only allowed values for Mellanox cards are `1015`, `1017`. -<2> Specify the driver type for the virtual functions to `netdevice`. Mellanox SR-IOV VF can work in DPDK mode without using the `vfio-pci` device type. VF device appears as a kernel network interface inside a container. -<3> Enable RDMA mode. This is required by Mellanox cards to work in DPDK mode. -+ -[NOTE] -===== -Please refer to `Configuring SR-IOV network devices` section for detailed explanation on each option in `SriovNetworkNodePolicy`. - -When applying the configuration specified in a `SriovNetworkNodePolicy` object, the SR-IOV Operator may drain the nodes, and in some cases, reboot nodes. -It may take several minutes for a configuration change to apply. -Ensure that there are enough available nodes in your cluster to handle the evicted workload beforehand. - -After the configuration update is applied, all the pods in the `openshift-sriov-network-operator` namespace will change to a `Running` status. -===== - -. Create the `SriovNetworkNodePolicy` object by running the following command: -+ -[source,terminal] ----- -$ oc create -f mlx-dpdk-node-policy.yaml ----- - -. Create the following `SriovNetwork` object, and then save the YAML in the `mlx-dpdk-network.yaml` file. -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetwork -metadata: - name: mlx-dpdk-network - namespace: openshift-sriov-network-operator -spec: - networkNamespace: <target_namespace> - ipam: |- <1> - ... - vlan: <vlan> - resourceName: mlxnics ----- -<1> Specify a configuration object for the ipam CNI plug-in as a YAML block scalar. The plug-in manages IP address assignment for the attachment definition. -+ -[NOTE] -===== -Please refer to `Configuring SR-IOV additional network` section for detailed explanation on each option in `SriovNetwork`. -===== - -. Create the `SriovNetworkNodePolicy` object by running the following command: -+ -[source,terminal] ----- -$ oc create -f mlx-dpdk-network.yaml ----- - -. Create the following `Pod` spec, and then save the YAML in the `mlx-dpdk-pod.yaml` file. -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dpdk-app - namespace: <target_namespace> <1> - annotations: - k8s.v1.cni.cncf.io/networks: mlx-dpdk-network -spec: - containers: - - name: testpmd - image: <DPDK_image> <2> - securityContext: - capabilities: - add: ["IPC_LOCK","NET_RAW"] <3> - volumeMounts: - - mountPath: /dev/hugepages <4> - name: hugepage - resources: - limits: - openshift.io/mlxnics: "1" <5> - memory: "1Gi" - cpu: "4" <6> - hugepages-1Gi: "4Gi" <7> - requests: - openshift.io/mlxnics: "1" - memory: "1Gi" - cpu: "4" - hugepages-1Gi: "4Gi" - command: ["sleep", "infinity"] - volumes: - - name: hugepage - emptyDir: - medium: HugePages ----- -<1> Specify the same `target_namespace` where `SriovNetwork` object `mlx-dpdk-network` is created. If you would like to create the pod in a different namespace, change `target_namespace` in both `Pod` spec and `SriovNetowrk` object. -<2> Specify the DPDK image which includes your application and the DPDK library used by application. -<3> Specify the `IPC_LOCK` capability which is required by the application to allocate hugepage memory inside the container and `NET_RAW` for the application to access the network interface. -<4> Mount the hugepage volume to the DPDK pod under `/dev/hugepages`. The hugepage volume is backed by the emptyDir volume type with the medium being `Hugepages`. -<5> Optional: Specify the number of DPDK devices allocated to the DPDK pod. This resource request and limit, if not explicitly specified, will be automatically added by SR-IOV network resource injector. The SR-IOV network resource injector is an admission controller component managed by SR-IOV Operator. It is enabled by default and can be disabled by setting the `enableInjector` option to `false` in the default `SriovOperatorConfig` CR. -<6> Specify the number of CPUs. The DPDK pod usually requires exclusive CPUs be allocated from kubelet. This is achieved by setting CPU Manager policy to `static` and creating a pod with `Guaranteed` QoS. -<7> Specify hugepage size `hugepages-1Gi` or `hugepages-2Mi` and the quantity of hugepages that will be allocated to DPDK pod. Configure `2Mi` and `1Gi` hugepages separately. Configuring `1Gi` hugepage requires adding kernel arguments to Nodes. - -. Create the DPDK pod by running the following command: -+ -[source,terminal] ----- -$ oc create -f mlx-dpdk-pod.yaml ----- diff --git a/modules/nw-sriov-example-vf-function-in-pod.adoc b/modules/nw-sriov-example-vf-function-in-pod.adoc deleted file mode 100644 index 3c917d19dab3..000000000000 --- a/modules/nw-sriov-example-vf-function-in-pod.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/about-sriov.adoc - -[id="example-vf-use-in-pod_{context}"] -= Example use of a virtual function in a pod - -You can run a remote direct memory access (RDMA) or a Data Plane Development Kit (DPDK) application in a pod with SR-IOV VF attached. - -This example shows a pod using a virtual function (VF) in RDMA mode: - -.`Pod` spec that uses RDMA mode -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: rdma-app - annotations: - k8s.v1.cni.cncf.io/networks: sriov-rdma-mlnx -spec: - containers: - - name: testpmd - image: <RDMA_image> - imagePullPolicy: IfNotPresent - securityContext: - capabilities: - add: ["IPC_LOCK"] - command: ["sleep", "infinity"] ----- - -The following example shows a pod with a VF in DPDK mode: - -.`Pod` spec that uses DPDK mode -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: dpdk-app - annotations: - k8s.v1.cni.cncf.io/networks: sriov-dpdk-net -spec: - containers: - - name: testpmd - image: <DPDK_image> - securityContext: - capabilities: - add: ["IPC_LOCK"] - volumeMounts: - - mountPath: /dev/hugepages - name: hugepage - resources: - limits: - memory: "1Gi" - cpu: "2" - hugepages-1Gi: "4Gi" - requests: - memory: "1Gi" - cpu: "2" - hugepages-1Gi: "4Gi" - command: ["sleep", "infinity"] - volumes: - - name: hugepage - emptyDir: - medium: HugePages ----- diff --git a/modules/nw-sriov-ibnetwork-object.adoc b/modules/nw-sriov-ibnetwork-object.adoc deleted file mode 100644 index 1ea652ef10de..000000000000 --- a/modules/nw-sriov-ibnetwork-object.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/configuring-sriov-ib-attach.adoc - -[id="nw-sriov-ibnetwork-object_{context}"] -= InfiniBand device configuration object - -You can configure an InfiniBand (IB) network device by defining an `SriovIBNetwork` object. - -The following YAML describes an `SriovIBNetwork` object: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovIBNetwork -metadata: - name: <name> <1> - namespace: openshift-sriov-network-operator <2> -spec: - resourceName: <sriov_resource_name> <3> - networkNamespace: <target_namespace> <4> - ipam: |- <5> - {} - linkState: <link_state> <6> - capabilities: <capabilities> <7> ----- -<1> A name for the object. The SR-IOV Network Operator creates a `NetworkAttachmentDefinition` object with same name. - -<2> The namespace where the SR-IOV Operator is installed. - -<3> The value for the `spec.resourceName` parameter from the `SriovNetworkNodePolicy` object that defines the SR-IOV hardware for this additional network. - -<4> The target namespace for the `SriovIBNetwork` object. Only pods in the target namespace can attach to the network device. - -<5> Optional: A configuration object for the IPAM CNI plug-in as a YAML block scalar. The plug-in manages IP address assignment for the attachment definition. - -<6> Optional: The link state of virtual function (VF). Allowed values are `enable`, `disable` and `auto`. - -<7> Optional: The capabilities to configure for this network. You can specify `"{ "ips": true }"` to enable IP address support or `"{ "infinibandGUID": true }"` to enable IB Global Unique Identifier (GUID) support. diff --git a/modules/nw-sriov-installing-operator.adoc b/modules/nw-sriov-installing-operator.adoc deleted file mode 100644 index f6ccc3e75036..000000000000 --- a/modules/nw-sriov-installing-operator.adoc +++ /dev/null @@ -1,183 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/installing-sriov-operator.adoc - -ifeval::["{product-version}" == "4.2"] -:run-level: -endif::[] -ifeval::["{product-version}" == "4.3"] -:run-level: -endif::[] -ifeval::["{product-version}" == "4.4"] -:run-level: -endif::[] - -[id="installing-sr-iov-operator_{context}"] -= Installing SR-IOV Network Operator - -As a cluster administrator, you can install the SR-IOV Network Operator by using the {product-title} CLI or the web console. - -[id="install-operator-cli_{context}"] -== CLI: Installing the SR-IOV Network Operator - -As a cluster administrator, you can install the Operator using the CLI. - -.Prerequisites - -* A cluster installed on bare-metal hardware with nodes that have hardware that supports SR-IOV. -* Install the OpenShift CLI (`oc`). -* An account with `cluster-admin` privileges. - -.Procedure - -. To create the `openshift-sriov-network-operator` namespace, enter the following command: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-sriov-network-operator -ifdef::run-level[] - labels: - openshift.io/run-level: "1" -endif::run-level[] -EOF ----- - -. To create an OperatorGroup CR, enter the following command: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: sriov-network-operators - namespace: openshift-sriov-network-operator -spec: - targetNamespaces: - - openshift-sriov-network-operator -EOF ----- - -. Subscribe to the SR-IOV Network Operator. - -.. Run the following command to get the {product-title} major and minor version. It is required for the `channel` value in the next -step. -+ -[source,terminal] ----- -$ OC_VERSION=$(oc version -o yaml | grep openshiftVersion | \ - grep -o '[0-9]*[.][0-9]*' | head -1) ----- - -.. To create a Subscription CR for the SR-IOV Network Operator, enter the following command: -+ -[source,terminal] ----- -$ cat << EOF| oc create -f - -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: sriov-network-operator-subscription - namespace: openshift-sriov-network-operator -spec: - channel: "${OC_VERSION}" - name: sriov-network-operator - source: redhat-operators - sourceNamespace: openshift-marketplace -EOF ----- - -. To verify that the Operator is installed, enter the following command: -+ -[source,terminal] ----- -$ oc get csv -n openshift-sriov-network-operator \ - -o custom-columns=Name:.metadata.name,Phase:.status.phase ----- -+ -.Example output -[source,terminal] ----- -Name Phase -sriov-network-operator.4.4.0-202006160135 Succeeded ----- - -[id="install-operator-web-console_{context}"] -== Web console: Installing the SR-IOV Network Operator - -As a cluster administrator, you can install the Operator using the web console. - -[NOTE] -==== -You must create the operator group by using the CLI. -==== - -.Prerequisites - -* A cluster installed on bare-metal hardware with nodes that have hardware that supports SR-IOV. -* Install the OpenShift CLI (`oc`). -* An account with `cluster-admin` privileges. - -.Procedure - -. Create a namespace for the SR-IOV Network Operator: - -.. In the {product-title} web console, click *Administration* -> *Namespaces*. - -.. Click *Create Namespace*. - -.. In the *Name* field, enter `openshift-sriov-network-operator`, and then click *Create*. - -ifdef::run-level[] -.. In the *Filter by name* field, enter `openshift-sriov-network-operator`. - -.. From the list of results, click `openshift-sriov-network-operator`, and then click *YAML*. - -.. Update the namespace by adding the following stanza to the namespace definition: -+ -[source,yaml] ----- - labels: - openshift.io/run-level: "1" ----- - -.. Click *Save*. -endif::run-level[] - -. Install the SR-IOV Network Operator: - -.. In the {product-title} web console, click *Operators* -> *OperatorHub*. - -.. Select *SR-IOV Network Operator* from the list of available Operators, and then click *Install*. - -.. On the *Install Operator* page, under *A specific namespace on the cluster*, select *openshift-sriov-network-operator*. - -.. Click *Install*. - -. Verify that the SR-IOV Network Operator is installed successfully: - -.. Navigate to the *Operators* -> *Installed Operators* page. - -.. Ensure that *SR-IOV Network Operator* is listed in the *openshift-sriov-network-operator* project with a *Status* of *InstallSucceeded*. -+ -[NOTE] -==== -During installation an Operator might display a *Failed* status. -If the installation later succeeds with an *InstallSucceeded* message, you can ignore the *Failed* message. -==== - -+ -If the operator does not appear as installed, to troubleshoot further: - -+ -* Inspect the *Operator Subscriptions* and *Install Plans* tabs for any failure or errors under *Status*. -* Navigate to the *Workloads* -> *Pods* page and check the logs for pods in the -`openshift-sriov-network-operator` project. - -ifdef::run-level[] -:!run-level: -endif::[] diff --git a/modules/nw-sriov-network-attachment.adoc b/modules/nw-sriov-network-attachment.adoc deleted file mode 100644 index d07a07b2f689..000000000000 --- a/modules/nw-sriov-network-attachment.adoc +++ /dev/null @@ -1,206 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/configuring-sriov-net-attach.adoc -// * virt/virtual_machines/vm_networking/virt-defining-an-sriov-network.adoc - -// Note: IB does not support ipam with `type=dhcp`. - -ifeval::["{context}" == "configuring-sriov-net-attach"] -:rs: SriovNetwork -:ocp-sriov-net: -:object: pods -endif::[] - -ifeval::["{context}" == "configuring-sriov-ib-attach"] -:rs: SriovIBNetwork -:ocp-sriov-net: -:object: pods -endif::[] - -ifeval::["{context}" == "virt-defining-an-sriov-network"] -:rs: SriovNetwork -:virt-sriov-net: -:object: pods or virtual machines -endif::[] - -ifdef::ocp-sriov-net[] -[id="nw-sriov-network-attachment_{context}"] -= Configuring SR-IOV additional network - -You can configure an additional network that uses SR-IOV hardware by creating a `{rs}` object. -When you create a `{rs}` object, the SR-IOV Operator automatically creates a `NetworkAttachmentDefinition` object. - -ifdef::virt-sriov-net[] -Users can then attach virtual machines to the SR-IOV network by specifying the network in the virtual machine configurations. -endif::virt-sriov-net[] - -[NOTE] -===== -Do not modify or delete a `{rs}` object if it is attached to any {object} in the `running` state. -===== - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create a `{rs}` object, and then save the YAML in the `<name>.yaml` file, where `<name>` is a name for this additional network. The object specification might resemble the following example: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: {rs} -metadata: - name: attach1 - namespace: openshift-sriov-network-operator -spec: - resourceName: net1 - networkNamespace: project2 - ipam: |- - { - "type": "host-local", - "subnet": "10.56.217.0/24", - "rangeStart": "10.56.217.171", - "rangeEnd": "10.56.217.181", - "gateway": "10.56.217.1" - } ----- - -. To create the object, enter the following command: -+ -[source,terminal] ----- -$ oc create -f <name>.yaml ----- -+ -where `<name>` specifies the name of the additional network. - -. Optional: To confirm that the `NetworkAttachmentDefinition` object that is associated with the `{rs}` object that you created in the previous step exists, enter the following command. Replace `<namespace>` with the networkNamespace you specified in the `{rs}` object. -+ -[source,terminal] ----- -$ oc get net-attach-def -n <namespace> ----- -endif::ocp-sriov-net[] - -// LEGACY -ifdef::virt-sriov-net[] -[id="nw-sriov-network-attachment_{context}"] -= Configuring SR-IOV additional network - -You can configure an additional network that uses SR-IOV hardware by creating a `SriovNetwork` object. -When you create a `SriovNetwork` object, the SR-IOV Operator automatically creates a `NetworkAttachmentDefinition` object. - -ifdef::virt-sriov-net[] -Users can then attach virtual machines to the SR-IOV network by specifying the network in the virtual machine configurations. - -endif::virt-sriov-net[] -[NOTE] -===== -Do not modify or delete a `SriovNetwork` object if it is attached to any {object} in the `running` state. -===== - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create the following `SriovNetwork` object, and then save the YAML in the `<name>-sriov-network.yaml` file. Replace `<name>` with a name for this additional network. - -// The list breaks because of the [NOTE] -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetwork -metadata: - name: <name> <1> - namespace: openshift-sriov-network-operator <2> -spec: - resourceName: <sriov_resource_name> <3> - networkNamespace: <target_namespace> <4> - vlan: <vlan> <5> - spoofChk: "<spoof_check>" <6> - linkState: <link_state> <7> - maxTxRate: <max_tx_rate> <8> - minTxRate: <min_rx_rate> <9> - vlanQoS: <vlan_qos> <10> - trust: "<trust_vf>" <11> - capabilities: <capabilities> <12> -ifdef::ocp-sriov-net[] - ipam: {} <7> - linkState: <link_state> <8> - maxTxRate: <max_tx_rate> <9> - minTxRate: <min_tx_rate> <10> - vlanQoS: <vlan_qos> <11> - trust: "<trust_vf>" <12> - capabilities: <capabilities> <13> -endif::ocp-sriov-net[] ----- -<1> Replace `<name>` with a name for the object. The SR-IOV Network Operator creates a `NetworkAttachmentDefinition` object with same name. -<2> Specify the namespace where the SR-IOV Network Operator is installed. -<3> Replace `<sriov_resource_name>` with the value for the `.spec.resourceName` parameter from the `SriovNetworkNodePolicy` object that defines the SR-IOV hardware for this additional network. -<4> Replace `<target_namespace>` with the target namespace for the SriovNetwork. Only {object} in the target namespace can attach to the SriovNetwork. -<5> Optional: Replace `<vlan>` with a Virtual LAN (VLAN) ID for the additional network. The integer value must be from `0` to `4095`. The default value is `0`. -<6> Optional: Replace `<spoof_check>` with the spoof check mode of the VF. The allowed values are the strings `"on"` and `"off"`. -+ -[IMPORTANT] -==== -You must enclose the value you specify in quotes or the CR is rejected by the SR-IOV Network Operator. -==== -<7> Optional: Replace `<link_state>` with the link state of virtual function (VF). Allowed value are `enable`, `disable` and `auto`. -<8> Optional: Replace `<max_tx_rate>` with a maximum transmission rate, in Mbps, for the VF. -<9> Optional: Replace `<min_tx_rate>` with a minimum transmission rate, in Mbps, for the VF. This value should always be less than or equal to Maximum transmission rate. -+ -[NOTE] -==== -Intel NICs do not support the `minTxRate` parameter. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1772847[BZ#1772847]. -==== -<10> Optional: Replace `<vlan_qos>` with an IEEE 802.1p priority level for the VF. The default value is `0`. -<11> Optional: Replace `<trust_vf>` with the trust mode of the VF. The allowed values are the strings `"on"` and `"off"`. -+ -[IMPORTANT] -==== -You must enclose the value you specify in quotes or the CR is rejected by the SR-IOV Network Operator. -==== -<12> Optional: Replace `<capabilities>` with the capabilities to configure for this network. -ifdef::ocp-sriov-net[] -You can specify `"{ "ips": true }"` to enable IP address support or `"{ "mac": true }"` to enable MAC address support. -<13> A configuration object for the IPAM CNI plug-in as a YAML block scalar. The plug-in manages IP address assignment for the attachment definition. -endif::ocp-sriov-net[] - -[start=2] -. To create the object, enter the following command. Replace `<name>` with a name for this additional network. -+ -[source,terminal] ----- -$ oc create -f <name>-sriov-network.yaml ----- - -. Optional: To confirm that the `NetworkAttachmentDefinition` object associated with the `SriovNetwork` object that you created in the previous step exists, enter the following command. Replace `<namespace>` with the namespace you specified in the `SriovNetwork` object. -+ -[source,terminal] ----- -$ oc get net-attach-def -n <namespace> ----- -// LEGACY -endif::virt-sriov-net[] - -ifdef::object[] -:!object: -endif::[] - -ifdef::rs[] -:!rs: -endif::[] - -ifdef::virt-sriov-net[] -:!virt-sriov-net: -endif::[] - -ifdef::ocp-sriov-net[] -:!ocp-sriov-net: -endif::[] diff --git a/modules/nw-sriov-network-object.adoc b/modules/nw-sriov-network-object.adoc deleted file mode 100644 index bfc184c4cc8b..000000000000 --- a/modules/nw-sriov-network-object.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/configuring-sriov-net-attach.adoc - -// Because of an existing issue in go-yaml, the strings 'on' and 'off' -// are interpreted as booleans, not strings. The SR-IOV admission controller -// will reject 'spoofCheck' and 'trust' if the values are not strings. -// So these values must be explicitly quoted in the YAML. -// https://github.com/go-yaml/yaml/issues/214 - -ifeval::["{context}" == "configuring-sriov-net-attach"] -:ocp-sriov-net: -:object: pods -endif::[] - -ifeval::["{context}" == "virt-defining-an-sriov-network"] -:virt-sriov-net: -:object: pods or virtual machines -endif::[] - -[id="nw-sriov-network-object_{context}"] -= Ethernet device configuration object - -You can configure an Ethernet network device by defining an `SriovNetwork` object. - -The following YAML describes an `SriovNetwork` object: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetwork -metadata: - name: <name> <1> - namespace: openshift-sriov-network-operator <2> -spec: - resourceName: <sriov_resource_name> <3> - networkNamespace: <target_namespace> <4> - vlan: <vlan> <5> - spoofChk: "<spoof_check>" <6> -ifdef::ocp-sriov-net[] - ipam: |- <7> - {} - linkState: <link_state> <8> - maxTxRate: <max_tx_rate> <9> - minTxRate: <min_tx_rate> <10> - vlanQoS: <vlan_qos> <11> - trust: "<trust_vf>" <12> - capabilities: <capabilities> <13> -endif::ocp-sriov-net[] ----- -<1> A name for the object. The SR-IOV Network Operator creates a `NetworkAttachmentDefinition` object with same name. -<2> The namespace where the SR-IOV Network Operator is installed. -<3> The value for the `spec.resourceName` parameter from the `SriovNetworkNodePolicy` object that defines the SR-IOV hardware for this additional network. -<4> The target namespace for the `SriovNetwork` object. Only {object} in the target namespace can attach to the additional network. -<5> Optional: A Virtual LAN (VLAN) ID for the additional network. The integer value must be from `0` to `4095`. The default value is `0`. -<6> Optional: The spoof check mode of the VF. The allowed values are the strings `"on"` and `"off"`. -+ -[IMPORTANT] -==== -You must enclose the value you specify in quotes or the object is rejected by the SR-IOV Network Operator. -==== -+ -ifdef::ocp-sriov-net[] -<7> A configuration object for the IPAM CNI plug-in as a YAML block scalar. The plug-in manages IP address assignment for the attachment definition. -<8> Optional: The link state of virtual function (VF). Allowed value are `enable`, `disable` and `auto`. -<9> Optional: A maximum transmission rate, in Mbps, for the VF. -<10> Optional: A minimum transmission rate, in Mbps, for the VF. This value must be less than or equal to the maximum transmission rate. -+ -[NOTE] -==== -Intel NICs do not support the `minTxRate` parameter. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1772847[BZ#1772847]. -==== -+ -<11> Optional: An IEEE 802.1p priority level for the VF. The default value is `0`. -<12> Optional: The trust mode of the VF. The allowed values are the strings `"on"` and `"off"`. -+ -[IMPORTANT] -==== -You must enclose the value that you specify in quotes, or the SR-IOV Network Operator rejects the object. -==== -+ -<13> Optional: The capabilities to configure for this additional network. You can specify `"{ "ips": true }"` to enable IP address support or `"{ "mac": true }"` to enable MAC address support. -endif::ocp-sriov-net[] - -ifdef::object[] -:object!: -endif::[] -ifdef::ocp-sriov-net[] -:ocp-sriov-net!: -endif::[] -ifdef::virt-sriov-net[] -:virt-sriov-net!: -endif::[] diff --git a/modules/nw-sriov-networknodepolicy-object.adoc b/modules/nw-sriov-networknodepolicy-object.adoc deleted file mode 100644 index 8a20f1fec6c9..000000000000 --- a/modules/nw-sriov-networknodepolicy-object.adoc +++ /dev/null @@ -1,126 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/configuring-sriov-device.adoc - -[id="nw-sriov-networknodepolicy-object_{context}"] -= SR-IOV network node configuration object - -You specify the SR-IOV network device configuration for a node by creating an SR-IOV network node policy. The API object for the policy is part of the `sriovnetwork.openshift.io` API group. - -The following YAML describes an SR-IOV network node policy: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: <name> <1> - namespace: openshift-sriov-network-operator <2> -spec: - resourceName: <sriov_resource_name> <3> - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" <4> - priority: <priority> <5> - mtu: <mtu> <6> - numVfs: <num> <7> - nicSelector: <8> - vendor: "<vendor_code>" <9> - deviceID: "<device_id>" <10> - pfNames: ["<pf_name>", ...] <11> - rootDevices: ["<pci_bus_id>", ...] <12> - netFilter: "<filter_string>" <13> - deviceType: <device_type> <14> - isRdma: false <15> - linkType: <link_type> <16> ----- -<1> The name for the custom resource object. - -<2> The namespace where the SR-IOV Operator is installed. - -<3> The resource name of the SR-IOV device plug-in. You can create multiple SR-IOV network node policies for a resource name. - -<4> The node selector specifies the nodes to configure. Only SR-IOV network devices on the selected nodes are configured. The SR-IOV Container Network Interface (CNI) plug-in and device plug-in are deployed on selected nodes only. - -<5> Optional: The priority is an integer value between `0` and `99`. A smaller value receives higher priority. For example, a priority of `10` is a higher priority than `99`. The default value is `99`. - -<6> Optional: The maximum transmission unit (MTU) of the virtual function. The maximum MTU value can vary for different network interface controller (NIC) models. - -<7> The number of the virtual functions (VF) to create for the SR-IOV physical network device. For an Intel network interface controller (NIC), the number of VFs cannot be larger than the total VFs supported by the device. For a Mellanox NIC, the number of VFs cannot be larger than `128`. - -<8> The NIC selector identifies the device for the Operator to configure. You do not have to specify values for all the parameters. It is recommended to identify the network device with enough precision to avoid selecting a device unintentionally. -+ -If you specify `rootDevices`, you must also specify a value for `vendor`, `deviceID`, or `pfNames`. If you specify both `pfNames` and `rootDevices` at the same time, ensure that they refer to the same device. If you specify a value for `netFilter`, then you do not need to specify any other parameter because a network ID is unique. - -<9> Optional: The vendor hexadecimal code of the SR-IOV network device. The only allowed values are `8086` and `15b3`. - -<10> Optional: The device hexadecimal code of the SR-IOV network device. The only allowed values are `158b`, `1015`, and `1017`. - -<11> Optional: An array of one or more physical function (PF) names for the device. - -<12> Optional: An array of one or more PCI bus addresses for the PF of the device. Provide the address in the following format: `0000:02:00.1`. - -<13> Optional: The platform-specific network filter. The only supported platform is {rh-openstack-first}. Acceptable values use the following format: `openstack/NetworkID:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. Replace `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` with the value from the `/var/config/openstack/latest/network_data.json` metadata file. - -<14> Optional: The driver type for the virtual functions. The only allowed values are `netdevice` and `vfio-pci`. The default value is `netdevice`. -+ -For a Mellanox NIC to work in Data Plane Development Kit (DPDK) mode on bare metal nodes, use the `netdevice` driver type and set `isRdma` to `true`. - -<15> Optional: Whether to enable remote direct memory access (RDMA) mode. The default value is `false`. -+ -If the `isRDMA` parameter is set to `true`, you can continue to use the RDMA-enabled VF as a normal network device. A device can be used in either mode. - -<16> Optional: The link type for the VFs. You can specify one of the following values: `eth` or `ib`. Specify `eth` for Ethernet or `ib` for InfiniBand. The default value is `eth`. -+ -When `linkType` is set to `ib`, `isRdma` is automatically set to `true` by the SR-IOV Network Operator webhook. When `linkType` is set to `ib`, `deviceType` should not be set to `vfio-pci`. - -[id="sr-iov-network-node-configuration-examples_{context}"] -== SR-IOV network node configuration examples - -The following example describes the configuration for an InfiniBand device: - -.Example configuration for an InfiniBand device -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: policy-ib-net-1 - namespace: openshift-sriov-network-operator -spec: - resourceName: ibnic1 - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - numVfs: 4 - nicSelector: - vendor: "15b3" - deviceID: "101b" - rootDevices: - - "0000:19:00.0" - linkType: ib - isRdma: true ----- - -The following example describes the configuration for an SR-IOV network device in a {rh-openstack} virtual machine: - -.Example configuration for an SR-IOV device in a virtual machine -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: policy-sriov-net-openstack-1 - namespace: openshift-sriov-network-operator -spec: - resourceName: sriovnic1 - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - numVfs: 1 <1> - nicSelector: - vendor: "15b3" - deviceID: "101b" - netFilter: "openstack/NetworkID:ea24bd04-8674-4f69-b0ee-fa0b3bd20509" <2> ----- - -<1> The `numVfs` field is always set to `1` when configuring the node network policy for a virtual machine. - -<2> The `netFilter` field must refer to a network ID when the virtual machine is deployed on {rh-openstack}. Valid values for `netFilter` are available from an `SriovNetworkNodeState` object. diff --git a/modules/nw-sriov-nic-partitioning.adoc b/modules/nw-sriov-nic-partitioning.adoc deleted file mode 100644 index 18705d41deff..000000000000 --- a/modules/nw-sriov-nic-partitioning.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/configuring-sriov-device.adoc - -[id="nw-sriov-nic-partitioning_{context}"] -= Virtual function (VF) partitioning for SR-IOV devices - -In some cases, you might want to split virtual functions (VFs) from the same physical function (PF) into multiple resource pools. -For example, you might want some of the VFs to load with the default driver and the remaining VFs load with the `vfio-pci` driver. -In such a deployment, the `pfNames` selector in your SriovNetworkNodePolicy custom resource (CR) can be used to specify a range of VFs for a pool using the following format: `<pfname>#<first_vf>-<last_vf>`. - -For example, the following YAML shows the selector for an interface named `netpf0` with VF `2` through `7`: - -[source,yaml] ----- -pfNames: ["netpf0#2-7"] ----- - -* `netpf0` is the PF interface name. -* `2` is the first VF index (0-based) that is included in the range. -* `7` is the last VF index (0-based) that is included in the range. - -You can select VFs from the same PF by using different policy CRs if the following requirements are met: - -* The `numVfs` value must be identical for policies that select the same PF. -* The VF index must be in the range of `0` to `<numVfs>-1`. For example, if you have a policy with `numVfs` set to `8`, then the `<first_vf>` value must not be smaller than `0`, and the `<last_vf>` must not be larger than `7`. -* The VFs ranges in different policies must not overlap. -* The `<first_vf>` must not be larger than the `<last_vf>`. - -The following example illustrates NIC partitioning for an SR-IOV device. - -The policy `policy-net-1` defines a resource pool `net-1` that contains the VF `0` of PF `netpf0` with the default VF driver. -The policy `policy-net-1-dpdk` defines a resource pool `net-1-dpdk` that contains the VF `8` to `15` of PF `netpf0` with the `vfio` VF driver. - -Policy `policy-net-1`: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: policy-net-1 - namespace: openshift-sriov-network-operator -spec: - resourceName: net1 - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - numVfs: 16 - nicSelector: - pfNames: ["netpf0#0-0"] - deviceType: netdevice ----- - -Policy `policy-net-1-dpdk`: - -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: policy-net-1-dpdk - namespace: openshift-sriov-network-operator -spec: - resourceName: net1dpdk - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - numVfs: 16 - nicSelector: - pfNames: ["netpf0#8-15"] - deviceType: vfio-pci ----- diff --git a/modules/nw-sriov-rdma-example-mellanox.adoc b/modules/nw-sriov-rdma-example-mellanox.adoc deleted file mode 100644 index 7dd685a27c19..000000000000 --- a/modules/nw-sriov-rdma-example-mellanox.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/using-dpdk-and-rdma.adoc - -[id="example-vf-use-in-rdma-mode-mellanox_{context}"] -= Using a virtual function in RDMA mode with a Mellanox NIC - -RDMA over Converged Ethernet (RoCE) is the only supported mode when using RDMA -on {product-title}. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Install the SR-IOV Network Operator. -* Log in as a user with `cluster-admin` privileges. - -.Procedure - -. Create the following `SriovNetworkNodePolicy` object, and then save the YAML in the `mlx-rdma-node-policy.yaml` file. -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetworkNodePolicy -metadata: - name: mlx-rdma-node-policy - namespace: openshift-sriov-network-operator -spec: - resourceName: mlxnics - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - priority: <priority> - numVfs: <num> - nicSelector: - vendor: "15b3" - deviceID: "1015" <1> - pfNames: ["<pf_name>", ...] - rootDevices: ["<pci_bus_id>", "..."] - deviceType: netdevice <2> - isRdma: true <3> ----- -<1> Specify the device hex code of SR-IOV network device. The only allowed values for Mellanox cards are `1015`, `1017`. -<2> Specify the driver type for the virtual functions to `netdevice`. -<3> Enable RDMA mode. -+ -[NOTE] -===== -Please refer to the `Configuring SR-IOV network devices` section for a detailed explanation on each option in `SriovNetworkNodePolicy`. - -When applying the configuration specified in a `SriovNetworkNodePolicy` object, the SR-IOV Operator may drain the nodes, and in some cases, reboot nodes. -It may take several minutes for a configuration change to apply. -Ensure that there are enough available nodes in your cluster to handle the evicted workload beforehand. - -After the configuration update is applied, all the pods in the `openshift-sriov-network-operator` namespace will change to a `Running` status. -===== - -. Create the `SriovNetworkNodePolicy` object by running the following command: -+ -[source,terminal] ----- -$ oc create -f mlx-rdma-node-policy.yaml ----- - -. Create the following `SriovNetwork` object, and then save the YAML in the `mlx-rdma-network.yaml` file. -+ -[source,yaml] ----- -apiVersion: sriovnetwork.openshift.io/v1 -kind: SriovNetwork -metadata: - name: mlx-rdma-network - namespace: openshift-sriov-network-operator -spec: - networkNamespace: <target_namespace> - ipam: |- <1> - ... - vlan: <vlan> - resourceName: mlxnics ----- -<1> Specify a configuration object for the ipam CNI plug-in as a YAML block scalar. The plug-in manages IP address assignment for the attachment definition. -+ -[NOTE] -===== -Please refer to `Configuring SR-IOV additional network` section for detailed explanation on each option in `SriovNetwork`. -===== - -. Create the `SriovNetworkNodePolicy` object by running the following command: -+ -[source,terminal] ----- -$ oc create -f mlx-rdma-network.yaml ----- - -. Create the following `Pod` spec, and then save the YAML in the `mlx-rdma-pod.yaml` file. -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: rdma-app - namespace: <target_namespace> <1> - annotations: - k8s.v1.cni.cncf.io/networks: mlx-rdma-network -spec: - containers: - - name: testpmd - image: <RDMA_image> <2> - securityContext: - capabilities: - add: ["IPC_LOCK"] <3> - volumeMounts: - - mountPath: /dev/hugepages <4> - name: hugepage - resources: - limits: - memory: "1Gi" - cpu: "4" <5> - hugepages-1Gi: "4Gi" <6> - requests: - memory: "1Gi" - cpu: "4" - hugepages-1Gi: "4Gi" - command: ["sleep", "infinity"] - volumes: - - name: hugepage - emptyDir: - medium: HugePages ----- -<1> Specify the same `target_namespace` where `SriovNetwork` object `mlx-rdma-network` is created. If you would like to create the pod in a different namespace, change `target_namespace` in both `Pod` spec and `SriovNetowrk` object. -<2> Specify the RDMA image which includes your application and RDMA library used by application. -<3> Specify the `IPC_LOCK` capability which is required by the application to allocate hugepage memory inside the container. -<4> Mount the hugepage volume to RDMA pod under `/dev/hugepages`. The hugepage volume is backed by the emptyDir volume type with the medium being `Hugepages`. -<5> Specify number of CPUs. The RDMA pod usually requires exclusive CPUs be allocated from the kubelet. This is achieved by setting CPU Manager policy to `static` and create pod with `Guaranteed` QoS. -<6> Specify hugepage size `hugepages-1Gi` or `hugepages-2Mi` and the quantity of hugepages that will be allocated to the RDMA pod. Configure `2Mi` and `1Gi` hugepages separately. Configuring `1Gi` hugepage requires adding kernel arguments to Nodes. - -. Create the RDMA pod by running the following command: -+ -[source,terminal] ----- -$ oc create -f mlx-rdma-pod.yaml ----- diff --git a/modules/nw-sriov-runtime-config.adoc b/modules/nw-sriov-runtime-config.adoc deleted file mode 100644 index 07b34087c3f2..000000000000 --- a/modules/nw-sriov-runtime-config.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/add-pod.adoc - -[id="nw-sriov-runtime-config_{context}"] -= Runtime configuration for a network attachment - -When attaching a pod to an additional network, you can specify a runtime configuration to make specific customizations for the pod. For example, you can request a specific MAC hardware address. - -You specify the runtime configuration by setting an annotation in the pod specification. The annotation key is `k8s.v1.cni.cncf.io/networks`, and it accepts a JSON object that describes the runtime configuration. - -[id="runtime-config-ethernet_{context}"] -== Runtime configuration for an Ethernet-based SR-IOV attachment - -The following JSON describes the runtime configuration options for an Ethernet-based SR-IOV network attachment. - -[source,json] ----- -[ - { - "name": "<name>", <1> - "mac": "<mac_address>", <2> - "ips": ["<cidr_range>"] <3> - } -] ----- -<1> The name of the SR-IOV network attachment definition CR. -<2> Optional: The MAC address for the SR-IOV device that is allocated from the resource type defined in the SR-IOV network attachment definition CR. To use this feature, you also must specify `{ "mac": true }` in the `SriovNetwork` object. -<3> Optional: IP addresses for the SR-IOV device that is allocated from the resource type defined in the SR-IOV network attachment definition CR. Both IPv4 and IPv6 addresses are supported. To use this feature, you also must specify `{ "ips": true }` in the `SriovNetwork` object. - -.Example runtime configuration -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: sample-pod - annotations: - k8s.v1.cni.cncf.io/networks: |- - [ - { - "name": "net1", - "mac": "20:04:0f:f1:88:01", - "ips": ["192.168.10.1/24", "2001::1/64"] - } - ] -spec: - containers: - - name: sample-container - image: <image> - imagePullPolicy: IfNotPresent - command: ["sleep", "infinity"] ----- - -[id="runtime-config-infiniband_{context}"] -== Runtime configuration for an InfiniBand-based SR-IOV attachment - -The following JSON describes the runtime configuration options for an InfiniBand-based SR-IOV network attachment. - -[source,json] ----- -[ - { - "name": "<network_attachment>", <1> - "infiniband-guid": "<guid>", <2> - "ips": ["<cidr_range>"] <3> - } -] ----- -<1> The name of the SR-IOV network attachment definition CR. -<2> The InfiniBand GUID for the SR-IOV device. To use this feature, you also must specify `{ "infinibandGUID": true }` in the `SriovIBNetwork` object. -<3> The IP addresses for the SR-IOV device that is allocated from the resource type defined in the SR-IOV network attachment definition CR. Both IPv4 and IPv6 addresses are supported. To use this feature, you also must specify `{ "ips": true }` in the `SriovIBNetwork` object. - -.Example runtime configuration -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: sample-pod - annotations: - k8s.v1.cni.cncf.io/networks: |- - [ - { - "name": "ib1", - "infiniband-guid": "c2:11:22:33:44:55:66:77", - "ips": ["192.168.10.1/24", "2001::1/64"] - } - ] -spec: - containers: - - name: sample-container - image: <image> - imagePullPolicy: IfNotPresent - command: ["sleep", "infinity"] ----- diff --git a/modules/nw-sriov-supported-devices.adoc b/modules/nw-sriov-supported-devices.adoc deleted file mode 100644 index fb3d9eb7524b..000000000000 --- a/modules/nw-sriov-supported-devices.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/about-sriov.adoc - -[id="supported-devices_{context}"] -= Supported devices - -{product-title} supports the following network interface controller (NIC) models: - -* Intel X710 10GbE SFP+ with vendor ID `0x8086` and device ID `0x1572` -* Intel XXV710 25GbE SFP28 with vendor ID `0x8086` and device ID `0x158b` -* Mellanox MT27710 Family [ConnectX-4 Lx] 25GbE dual-port SFP28 with vendor ID `0x15b3` and device ID `0x1015` -* Mellanox MT27800 Family [ConnectX-5] 25GbE dual-port SFP28 with vendor ID `0x15b3` and device ID `0x1017` -* Mellanox MT27800 Family [ConnectX-5] 100GbE with vendor ID `0x15b3` and device ID `0x1017` -* Mellanox MT27700 Family [ConnectX-4] VPI adapter card, EDR IB (100Gb/s), single-port QSFP28 with vendor ID `0x15b3` and device ID `0x1013` -* Mellanox MT27800 Family [ConnectX-5] VPI adapter card, EDR IB (100Gb/s), single-port QSFP28 with vendor ID `0x15b3` and device ID `0x1017` -* Mellanox MT28908 Family [ConnectX-6] VPI adapter card, 100Gb/s (HDR100, EDR IB), single-port QSFP56 with vendor ID `0x15b3` and device ID `0x101b` -* Mellanox MT28908 Family [ConnectX-6] VPI adapter card, HDR200 IB (200Gb/s), single-port QSFP56 with vendor ID `0x15b3` and device ID `0x101b` diff --git a/modules/nw-sriov-topology-manager.adoc b/modules/nw-sriov-topology-manager.adoc deleted file mode 100644 index 4c1d959957ec..000000000000 --- a/modules/nw-sriov-topology-manager.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/hardware_networks/add-pod.adoc - -[id="nw-sriov-topology-manager_{context}"] -= Creating a non-uniform memory access (NUMA) aligned SR-IOV pod - -You can create a NUMA aligned SR-IOV pod by restricting SR-IOV and the CPU resources allocated from the same NUMA node with `restricted` or `single-numa-node` Topology Manager polices. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Enable a LatencySensitive profile and configure the CPU Manager policy to `static`. - -.Procedure - -. Create the following SR-IOV pod spec, and then save the YAML in the `<name>-sriov-pod.yaml` file. Replace `<name>` with a name for this pod. -+ -The following example shows an SR-IOV pod spec: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: sample-pod - annotations: - k8s.v1.cni.cncf.io/networks: <name> <1> -spec: - containers: - - name: sample-container - image: <image> <2> - command: ["sleep", "infinity"] - resources: - limits: - memory: "1Gi" <3> - cpu: "2" <4> - requests: - memory: "1Gi" - cpu: "2" ----- -<1> Replace `<name>` with the name of the SR-IOV network attachment definition CR. -<2> Replace `<image>` with the name of the `sample-pod` image. -<3> To create the SR-IOV pod with guaranteed QoS, set `memory limits` equal to `memory requests`. -<4> To create the SR-IOV pod with guaranteed QoS, set `cpu limits` equals to `cpu requests`. - -. Create the sample SR-IOV pod by running the following command: -+ -[source,terminal] ----- -$ oc create -f <filename> <1> ----- -<1> Replace `<filename>` with the name of the file you created in the previous step. - -. Confirm that the `sample-pod` is configured with guaranteed QoS. -+ -[source,terminal] ----- -$ oc describe pod sample-pod ----- - -. Confirm that the `sample-pod` is allocated with exclusive CPUs. -+ -[source,terminal] ----- -$ oc exec sample-pod -- cat /sys/fs/cgroup/cpuset/cpuset.cpus ----- - -. Confirm that the SR-IOV device and CPUs that are allocated for the `sample-pod` are on the same NUMA node. -+ -[source,terminal] ----- -$ oc exec sample-pod -- cat /sys/fs/cgroup/cpuset/cpuset.cpus ----- diff --git a/modules/nw-throughput-troubleshoot.adoc b/modules/nw-throughput-troubleshoot.adoc deleted file mode 100644 index 11b251c657de..000000000000 --- a/modules/nw-throughput-troubleshoot.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module filename: nw-throughput-troubleshoot.adoc -// Module included in the following assemblies: -// * networking/configuring-routing.adoc - -[id="nw-throughput-troubleshoot_{context}"] -= Troubleshooting throughput issues -Sometimes applications deployed through {product-title} can cause -network throughput issues such as unusually high latency between -specific services. - -Use the following methods to analyze performance issues if pod logs do not -reveal any cause of the problem: - -* Use a packet analyzer, such as ping or link:http://www.tcpdump.org/[tcpdump] -to analyze traffic between a pod and its node. -+ -For example, run the tcpdump tool on each pod while reproducing the behavior -that led to the issue. -Review the captures on both sides to compare send and receive timestamps to -analyze the latency of traffic to and from a pod. -Latency can occur in {product-title} if a node interface is overloaded with -traffic from other pods, storage devices, or the data plane. -+ -[source,terminal] ----- -$ tcpdump -s 0 -i any -w /tmp/dump.pcap host <podip 1> && host <podip 2> <1> ----- -+ -<1> `podip` is the IP address for the pod. Run the `oc get pod <pod_name> -o wide` command to get -the IP address of a pod. -+ -tcpdump generates a file at `/tmp/dump.pcap` containing all traffic between -these two pods. Ideally, run the analyzer shortly -before the issue is reproduced and stop the analyzer shortly after the issue -is finished reproducing to minimize the size of the file. -You can also run a packet analyzer between the nodes (eliminating the SDN from - the equation) with: -+ -[source,terminal] ----- -$ tcpdump -s 0 -i any -w /tmp/dump.pcap port 4789 ----- - -* Use a bandwidth measuring tool, such as iperf, to measure streaming throughput -and UDP throughput. Run the tool from the pods first, then from the nodes, -to locate any bottlenecks. - -ifdef::openshift-enterprise,openshift-webscale[] -** For information on installing and using iperf, see this link:https://access.redhat.com/solutions/33103[Red Hat Solution]. -endif::openshift-enterprise,openshift-webscale[] diff --git a/modules/nw-using-cookies-keep-route-statefulness.adoc b/modules/nw-using-cookies-keep-route-statefulness.adoc deleted file mode 100644 index e244e2037b33..000000000000 --- a/modules/nw-using-cookies-keep-route-statefulness.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module filename: nw-using-cookies-keep-route-statefulness.adoc -// Use module with the following module: -// nw-annotating-a-route-with-a-cookie-name.adoc -// -// Module included in the following assemblies: -// -// * networking/configuring-routing.adoc -[id="nw-using-cookies-keep-route-statefulness_{context}"] -= Using cookies to keep route statefulness - -{product-title} provides sticky sessions, which enables stateful application -traffic by ensuring all traffic hits the same endpoint. However, if the endpoint -pod terminates, whether through restart, scaling, or a change in configuration, -this statefulness can disappear. - -{product-title} can use cookies to configure session persistence. The Ingress -controller selects an endpoint to handle any user requests, and creates a cookie -for the session. The cookie is passed back in the response to the request and -the user sends the cookie back with the next request in the session. The cookie -tells the Ingress Controller which endpoint is handling the session, ensuring -that client requests use the cookie so that they are routed to the same pod. diff --git a/modules/nw-using-ingress-and-routes.adoc b/modules/nw-using-ingress-and-routes.adoc deleted file mode 100644 index d206ceb645c1..000000000000 --- a/modules/nw-using-ingress-and-routes.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/configuring-ingress-cluster-traffic-ingress-controller.adoc - -[id="nw-using-ingress-and-routes_{context}"] -= Using Ingress Controllers and routes - -The Ingress Operator manages Ingress Controllers and wildcard DNS. - -Using an Ingress Controller is the most common way to allow external access to -an {product-title} cluster. - -An Ingress Controller is configured to accept external requests and proxy them -based on the configured routes. This is limited to HTTP, HTTPS using SNI, and -TLS using SNI, which is sufficient for web applications and services that work -over TLS with SNI. - -Work with your administrator to configure an Ingress Controller -to accept external requests and proxy them based on the -configured routes. - -The administrator can create a wildcard DNS entry and then set up an Ingress -Controller. Then, you can work with the edge Ingress Controller without -having to contact the administrators. - -When a set of routes is created in various projects, the overall set of routes -is available to the set of Ingress Controllers. Each Ingress Controller admits -routes from the set of routes. By default, all Ingress Controllers -admit all routes. - -The Ingress Controller: - -* Has two replicas by default, which means it should be running on two worker nodes. -* Can be scaled up to have more replicas on more nodes. diff --git a/modules/nw-using-ingress-forwarded.adoc b/modules/nw-using-ingress-forwarded.adoc deleted file mode 100644 index 040bbf5e5d26..000000000000 --- a/modules/nw-using-ingress-forwarded.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring-ingress-controller - -[id="nw-using-ingress-forwarded_{context}"] -= Using X-Forwarded headers - -You configure the HAProxy Ingress Controller to specify a policy for how to handle HTTP headers including `Forwarded` and `X-Forwarded-For`. The Ingress Operator uses the `HTTPHeaders` field to configure the `ROUTER_SET_FORWARDED_HEADERS` environment variable of the Ingress Controller. - -.Procedure - -. Configure the `HTTPHeaders` field for the Ingress Controller. -.. Use the following command to edit the `IngressController` resource: -+ -[source,terminal] ----- -$ oc edit IngressController ----- -+ -.. Under `spec`, set the `HTTPHeaders` policy field to `Append`, `Replace`, `IfNone`, or `Never`: -+ -[source,yaml] ----- -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - name: default - namespace: openshift-ingress-operator -spec: - httpHeaders: - forwardedHeaderPolicy: Append ----- - - -[discrete] -== Example use cases - -*As a cluster administrator, you can:* - -* Configure an external proxy that injects the `X-Forwarded-For` header into each request before forwarding it to an Ingress Controller. -+ -To configure the Ingress Controller to pass the header through unmodified, you specify the `never` policy. The Ingress Controller then never sets the headers, and applications receive only the headers that the external proxy provides. - - -* Configure the Ingress Controller to pass the `X-Forwarded-For` header that your external proxy sets on external cluster requests through unmodified. -+ -To configure the Ingress Controller to set the `X-Forwarded-For` header on internal cluster requests, which do not go through the external proxy, specify the `if-none` policy. If an HTTP request already has the header set through the external proxy, then the Ingress Controller preserves it. If the header is absent because the request did not come through the proxy, then the Ingress Controller adds the header. - -*As an application developer, you can:* - -* Configure an application-specific external proxy that injects the `X-Forwarded-For` header. -+ -To configure an Ingress Controller to pass the header through unmodified for an application's Route, without affecting the policy for other Routes, add an annotation `haproxy.router.openshift.io/set-forwarded-headers: if-none` or `haproxy.router.openshift.io/set-forwarded-headers: never` on the Route for the application. -+ -[NOTE] -==== -You can set the `haproxy.router.openshift.io/set-forwarded-headers` annotation on a per route basis, independent from the globally set value for the Ingress Controller. -==== diff --git a/modules/nw-using-load-balancer-getting-traffic.adoc b/modules/nw-using-load-balancer-getting-traffic.adoc deleted file mode 100644 index 7e37be14ecf3..000000000000 --- a/modules/nw-using-load-balancer-getting-traffic.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * ingress/getting-traffic-cluster.adoc - -[id="nw-using-load-balancer-getting-traffic_{context}"] -= Using a load balancer to get traffic into the cluster - -If you do not need a specific external IP address, you can configure a load -balancer service to allow external access to an {product-title} cluster. - -A load balancer service allocates a unique IP. The load balancer has a single -edge router IP, which can be a virtual IP (VIP), but is still a single machine -for initial load balancing. - -[NOTE] -==== -If a pool is configured, it is done at the infrastructure level, not by a cluster -administrator. -==== diff --git a/modules/nw-using-nodeport.adoc b/modules/nw-using-nodeport.adoc deleted file mode 100644 index a123564fb1d0..000000000000 --- a/modules/nw-using-nodeport.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc - -[id="nw-using-nodeport_{context}"] -= Using a NodePort to get traffic into the cluster - -Use a `NodePort`-type `Service` resource to expose a service on a specific port -on all nodes in the cluster. The port is specified in the `Service` resource's -`.spec.ports[*].nodePort` field. - -[IMPORTANT] -==== -Using a node port requires additional port resources. -==== - -A `NodePort` exposes the service on a static port on the node's IP address. -``NodePort``s are in the `30000` to `32767` range by default, which means a -`NodePort` is unlikely to match a service’s intended port. For example, port -`8080` may be exposed as port `31020` on the node. - -The administrator must ensure the external IP addresses are routed to the nodes. - -``NodePort``s and external IPs are independent and both can be used -concurrently. diff --git a/modules/nw-using-service-external-ip.adoc b/modules/nw-using-service-external-ip.adoc deleted file mode 100644 index ad18f1bf02d3..000000000000 --- a/modules/nw-using-service-external-ip.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc - -[id="nw-service-external-ip_{context}"] -= Using a service external IP to get traffic into the cluster - -One method to expose a service is to assign an external IP address directly to -the service you want to make accessible from outside the cluster. - -The external IP address that you use must be provisioned on your infrastructure -platform and attached to a cluster node. - -With an external IP on the service, {product-title} sets up NAT rules to -allow traffic arriving at any cluster node attached to that IP address to be -sent to one of the internal pods. This is similar to the internal -service IP addresses, but the external IP tells {product-title} that this -service should also be exposed externally at the given IP. The administrator -must assign the IP address to a host (node) interface on one of the nodes in the -cluster. Alternatively, the address can be used as a virtual IP (VIP). - -These IP addresses are not managed by {product-title}. The cluster administrator is responsible for ensuring that traffic arrives at a node with this IP address. diff --git a/modules/oauth-configuring-internal-oauth.adoc b/modules/oauth-configuring-internal-oauth.adoc deleted file mode 100644 index 3bce07962c0a..000000000000 --- a/modules/oauth-configuring-internal-oauth.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-internal-oauth.adoc - -[id="oauth-configuring-internal-oauth_{context}"] -= Configuring the internal OAuth server's token duration - -You can configure default options for the internal OAuth server's -token duration. - -[IMPORTANT] -==== -By default, tokens are only valid for 24 hours. Existing sessions -expire after this time elapses. -==== - -If the default time is insufficient, then this can be modified using -the following procedure. - -.Procedure - -. Create a configuration file that contains the token duration options. The -following file sets this to 48 hours, twice the default. -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: - name: cluster -spec: - tokenConfig: - accessTokenMaxAgeSeconds: 172800 <1> ----- -<1> Set `accessTokenMaxAgeSeconds` to control the lifetime of access tokens. -The default lifetime is 24 hours, or 86400 seconds. This attribute cannot -be negative. - -. Apply the new configuration file: -+ -[NOTE] -==== -Because you update the existing OAuth server, you must use the `oc apply` -command to apply the change. -==== -+ -[source,terminal] ----- -$ oc apply -f </path/to/file.yaml> ----- - -. Confirm that the changes are in effect: -+ -[source,terminal] ----- -$ oc describe oauth.config.openshift.io/cluster ----- -+ -.Example output -[source,terminal] ----- -... -Spec: - Token Config: - Access Token Max Age Seconds: 172800 -... ----- diff --git a/modules/oauth-configuring-token-inactivity-timeout-clients.adoc b/modules/oauth-configuring-token-inactivity-timeout-clients.adoc deleted file mode 100644 index 7290eb42f050..000000000000 --- a/modules/oauth-configuring-token-inactivity-timeout-clients.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-oauth-clients.adoc - -[id="oauth-token-inactivity-timeout_{context}"] -= Configuring token inactivity timeout for an OAuth client - -You can configure OAuth clients to expire OAuth tokens after a set period of inactivity. By default, no token inactivity timeout is set. - -[NOTE] -==== -If the token inactivity timeout is also configured in the internal OAuth server configuration, the timeout that is set in the OAuth client overrides that value. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have configured an identity provider (IDP). - -.Procedure - -* Update the `OAuthClient` configuration to set a token inactivity timeout. - -.. Edit the `OAuthClient` object: -+ -[source,terminal] ----- -$ oc edit oauthclient <oauth_client> <1> ----- -<1> Replace `<oauth_client>` with the OAuth client to configure, for example, `console`. -+ -Add the `accessTokenInactivityTimeoutSeconds` field and set your timeout value: -+ -[source,yaml] ----- -apiVersion: oauth.openshift.io/v1 -grantMethod: auto -kind: OAuthClient -metadata: -... -accessTokenInactivityTimeoutSeconds: 600 <1> ----- -<1> The minimum allowed timeout value in seconds is `300`. - -.. Save the file to apply the changes. - -.Verification - -. Log in to the cluster with an identity from your IDP. Be sure to use the OAuth client that you just configured. - -. Perform an action and verify that it was successful. - -. Wait longer than the configured timeout without using the identity. In this procedure's example, wait longer than 600 seconds. - -. Try to perform an action from the same identity's session. -+ -This attempt should fail because the token should have expired due to inactivity longer than the configured timeout. diff --git a/modules/oauth-configuring-token-inactivity-timeout.adoc b/modules/oauth-configuring-token-inactivity-timeout.adoc deleted file mode 100644 index 469249407487..000000000000 --- a/modules/oauth-configuring-token-inactivity-timeout.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-internal-oauth.adoc - -[id="oauth-token-inactivity-timeout_{context}"] -= Configuring token inactivity timeout for the internal OAuth server - -You can configure OAuth tokens to expire after a set period of inactivity. By default, no token inactivity timeout is set. - -[NOTE] -==== -If the token inactivity timeout is also configured in your OAuth client, that value overrides the timeout that is set in the internal OAuth server configuration. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have configured an identity provider (IDP). - -.Procedure - -. Update the `OAuth` configuration to set a token inactivity timeout. - -.. Edit the `OAuth` object: -+ -[source,terminal] ----- -$ oc edit oauth cluster ----- -+ -Add the `spec.tokenConfig.accessTokenInactivityTimeout` field and set your timeout value: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OAuth -metadata: -... -spec: - tokenConfig: - accessTokenInactivityTimeout: 400s <1> ----- -<1> Set a value with the appropriate units, for example `400s` for 400 seconds, or `30m` for 30 minutes. The minimum allowed timeout value is `300s`. - -.. Save the file to apply the changes. - -. Check that the OAuth server pods have restarted: -+ -[source,terminal] ----- -$ oc get clusteroperators authentication ----- -+ -Do not continue to the next step until `PROGRESSING` is listed as `False`, as shown in the following output: -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -authentication 4.7.0 True False False 145m ----- - -. Check that a new revision of the Kubernetes API server pods has rolled out. This will take several minutes. -+ -[source,terminal] ----- -$ oc get clusteroperators kube-apiserver ----- -+ -Do not continue to the next step until `PROGRESSING` is listed as `False`, as shown in the following output: -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE -kube-apiserver 4.7.0 True False False 145m ----- -+ -If `PROGRESSING` is showing `True`, wait a few minutes and try again. - -.Verification - -. Log in to the cluster with an identity from your IDP. - -. Execute a command and verify that it was successful. - -. Wait longer than the configured timeout without using the identity. In this procedure's example, wait longer than 400 seconds. - -. Try to execute a command from the same identity's session. -+ -This command should fail because the token should have expired due to inactivity longer than the configured timeout. -+ -.Example output -[source,terminal] ----- -error: You must be logged in to the server (Unauthorized) ----- diff --git a/modules/oauth-default-clients.adoc b/modules/oauth-default-clients.adoc deleted file mode 100644 index 33a59aa0558f..000000000000 --- a/modules/oauth-default-clients.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-oauth-clients.adoc - -[id="oauth-default-clients_{context}"] -= Default OAuth clients - -The following OAuth clients are automatically created when starting the {product-title} API: - -[cols="2,3",options="header"] -|=== - -|OAuth client |Usage - -|`openshift-browser-client` -|Requests tokens at `<namespace_route>/oauth/token/request` with a user-agent that can handle interactive logins. ^[1]^ - -|`openshift-challenging-client` -|Requests tokens with a user-agent that can handle `WWW-Authenticate` challenges. - -|=== -[.small] --- -1. `<namespace_route>` refers to the namespace route. This is found by -running the following command: -+ -[source,terminal] ----- -$ oc get route oauth-openshift -n openshift-authentication -o json | jq .spec.host ----- --- diff --git a/modules/oauth-delete-tokens.adoc b/modules/oauth-delete-tokens.adoc deleted file mode 100644 index 89e9c4ca57f3..000000000000 --- a/modules/oauth-delete-tokens.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-oauth-access-tokens.adoc - -[id="oauth-delete-tokens_{context}"] -= Deleting user-owned OAuth access tokens - -The `oc logout` command only invalidates the OAuth token for the active session. You can use the following procedure to delete any user-owned OAuth tokens that are no longer needed. - -Deleting an OAuth access token logs out the user from all sessions that use the token. - -.Procedure - -* Delete the user-owned OAuth access token: -+ -[source,terminal] ----- -$ oc delete useroauthaccesstokens <token_name> ----- -+ -.Example output -[source,terminal] ----- -useroauthaccesstoken.oauth.openshift.io "<token_name>" deleted ----- diff --git a/modules/oauth-internal-options.adoc b/modules/oauth-internal-options.adoc deleted file mode 100644 index b0944f99c583..000000000000 --- a/modules/oauth-internal-options.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-internal-oauth.adoc - -[id="oauth-internal-options_{context}"] -= Options for the internal OAuth server - -Several configuration options are available for the internal OAuth server. - -[id="oauth-token-duration_{context}"] -== OAuth token duration options - -The internal OAuth server generates two kinds of tokens: - -[cols="1,2",options="header"] -|=== - -|Token -|Description - -|Access tokens -|Longer-lived tokens that grant access to the API. - -|Authorize codes -|Short-lived tokens whose only use is to be exchanged for -an access token. - -|=== - -You can configure the default duration for both types of token. If necessary, -you can override the duration of the access token by using an `OAuthClient` -object definition. - -[id="oauth-grant-options_{context}"] -== OAuth grant options - -When the OAuth server receives token requests for a client to which the user -has not previously granted permission, the action that the OAuth server -takes is dependent on the OAuth client's grant strategy. - -The OAuth client requesting token must provide its own grant strategy. - -You can apply the following default methods: - -[cols="1,2",options="header"] -|=== - -|Grant option -|Description - -|`auto` -|Auto-approve the grant and retry the request. - -|`prompt` -|Prompt the user to approve or deny the grant. - -|=== diff --git a/modules/oauth-internal-tokens.adoc b/modules/oauth-internal-tokens.adoc deleted file mode 100644 index d023b76163ea..000000000000 --- a/modules/oauth-internal-tokens.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-internal-oauth.adoc - -[id="oauth-token-request-flows_{context}"] -= OAuth token request flows and responses - -The OAuth server supports standard -link:https://tools.ietf.org/html/rfc6749#section-4.1[authorization code grant] -and the link:https://tools.ietf.org/html/rfc6749#section-4.2[implicit grant] -OAuth authorization flows. - -When requesting an OAuth token using the implicit grant flow -(`response_type=token`) with a client_id configured to request `WWW-Authenticate challenges` -(like `openshift-challenging-client`), these are the possible server -responses from `/oauth/authorize`, and how they should be handled: - -[cols="2a,8a,8a",options="header"] -|=== -|Status | Content | Client response -|302 | `Location` header containing an `access_token` parameter in the URL fragment (link:https://tools.ietf.org/html/rfc6749#section-4.2.2[RFC 6749 section 4.2.2]) | Use the `access_token` value as the OAuth token. -|302 | `Location` header containing an `error` query parameter (link:https://tools.ietf.org/html/rfc6749#section-4.1.2.1[RFC 6749 section 4.1.2.1]) | Fail, optionally surfacing the `error` (and optional `error_description`) query values to the user. -|302 | Other `Location` header | Follow the redirect, and process the result using these rules. -|401 | `WWW-Authenticate` header present | Respond to challenge if type is recognized (e.g. `Basic`, `Negotiate`, etc), resubmit request, and process the result using these rules. -|401 | `WWW-Authenticate` header missing | No challenge authentication is possible. Fail and show response body (which might contain links or details on alternate methods to obtain an OAuth token). -|Other | Other | Fail, optionally surfacing response body to the user. -|=== diff --git a/modules/oauth-list-tokens.adoc b/modules/oauth-list-tokens.adoc deleted file mode 100644 index 1248fac5f5e4..000000000000 --- a/modules/oauth-list-tokens.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-oauth-access-tokens.adoc - -[id="oauth-list-tokens_{context}"] -= Listing user-owned OAuth access tokens - -You can list your user-owned OAuth access tokens. Token names are not sensitive and cannot be used to log in. - -.Procedure - -* List all user-owned OAuth access tokens: -+ -[source,terminal] ----- -$ oc get useroauthaccesstokens ----- -+ -.Example output -[source,terminal] ----- -NAME CLIENT NAME CREATED EXPIRES REDIRECT URI SCOPES -<token1> openshift-challenging-client 2021-01-11T19:25:35Z 2021-01-12 19:25:35 +0000 UTC https://oauth-openshift.apps.example.com/oauth/token/implicit user:full -<token2> openshift-browser-client 2021-01-11T19:27:06Z 2021-01-12 19:27:06 +0000 UTC https://oauth-openshift.apps.example.com/oauth/token/display user:full -<token3> console 2021-01-11T19:26:29Z 2021-01-12 19:26:29 +0000 UTC https://console-openshift-console.apps.example.com/auth/callback user:full ----- - -* List user-owned OAuth access tokens for a particular OAuth client: -+ -[source,terminal] ----- -$ oc get useroauthaccesstokens --field-selector=clientName="console" ----- -+ -.Example output -[source,terminal] ----- -NAME CLIENT NAME CREATED EXPIRES REDIRECT URI SCOPES -<token3> console 2021-01-11T19:26:29Z 2021-01-12 19:26:29 +0000 UTC https://console-openshift-console.apps.example.com/auth/callback user:full ----- diff --git a/modules/oauth-register-additional-client.adoc b/modules/oauth-register-additional-client.adoc deleted file mode 100644 index 2013f26b17eb..000000000000 --- a/modules/oauth-register-additional-client.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-oauth-clients.adoc - -[id="oauth-register-additional-client_{context}"] -= Registering an additional OAuth client - -If you need an additional OAuth client to manage authentication for your -{product-title} cluster, you can register one. - -.Procedure - -* To register additional OAuth clients: -+ -[source,yaml] ----- -$ oc create -f <(echo ' -kind: OAuthClient -apiVersion: oauth.openshift.io/v1 -metadata: - name: demo <1> -secret: "..." <2> -redirectURIs: - - "http://www.example.com/" <3> -grantMethod: prompt <4> -') ----- -<1> The `name` of the OAuth client is used as the `client_id` parameter when -making requests to `<namespace_route>/oauth/authorize` and -`<namespace_route>/oauth/token`. -<2> The `secret` is used as the `client_secret` parameter when making requests -to `<namespace_route>/oauth/token`. -<3> The `redirect_uri` parameter specified in requests to -`<namespace_route>/oauth/authorize` and `<namespace_route>/oauth/token` - must be equal to or prefixed by one of the URIs listed in the -`redirectURIs` parameter value. -<4> The `grantMethod` is used to determine what action to take when this -client requests tokens and has not yet been granted access by the user. -Specify `auto` to automatically approve the grant and retry the request, -or `prompt` to prompt the user to approve or deny the grant. diff --git a/modules/oauth-server-metadata.adoc b/modules/oauth-server-metadata.adoc deleted file mode 100644 index dbb02a71e6c8..000000000000 --- a/modules/oauth-server-metadata.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-internal-oauth.adoc - -[id="oauth-server-metadata_{context}"] -= OAuth server metadata - -Applications running in {product-title} might have to discover information -about the built-in OAuth server. For example, they might have to discover -what the address of the `<namespace_route>` is without manual -configuration. To aid in this, {product-title} implements the IETF -link:https://tools.ietf.org/html/draft-ietf-oauth-discovery-10[OAuth 2.0 Authorization Server Metadata] draft specification. - -Thus, any application running inside the cluster can issue a `GET` request -to *_\https://openshift.default.svc/.well-known/oauth-authorization-server_* -to fetch the following information: - ----- -{ - "issuer": "https://<namespace_route>", <1> - "authorization_endpoint": "https://<namespace_route>/oauth/authorize", <2> - "token_endpoint": "https://<namespace_route>/oauth/token", <3> - "scopes_supported": [ <4> - "user:full", - "user:info", - "user:check-access", - "user:list-scoped-projects", - "user:list-projects" - ], - "response_types_supported": [ <5> - "code", - "token" - ], - "grant_types_supported": [ <6> - "authorization_code", - "implicit" - ], - "code_challenge_methods_supported": [ <7> - "plain", - "S256" - ] -} ----- -<1> The authorization server's issuer identifier, which is a URL that uses the -`https` scheme and has no query or fragment components. This is the location -where `.well-known` link:https://tools.ietf.org/html/rfc5785[RFC 5785] resources -containing information about the authorization server are published. -<2> URL of the authorization server's authorization endpoint. See -link:https://tools.ietf.org/html/rfc6749[RFC 6749]. -<3> URL of the authorization server's token endpoint. See -link:https://tools.ietf.org/html/rfc6749[RFC 6749]. -<4> JSON array containing a list of the OAuth 2.0 -link:https://tools.ietf.org/html/rfc6749[RFC 6749] scope values that this -authorization server supports. Note that not all supported scope values are -advertised. -<5> JSON array containing a list of the OAuth 2.0 `response_type` values that this -authorization server supports. The array values used are the same as those used -with the `response_types` parameter defined by "OAuth 2.0 Dynamic Client -Registration Protocol" in link:https://tools.ietf.org/html/rfc7591[RFC 7591]. -<6> JSON array containing a list of the OAuth 2.0 grant type values that this -authorization server supports. The array values used are the same as those used -with the `grant_types` parameter defined by -`OAuth 2.0 Dynamic Client Registration Protocol` in -link:https://tools.ietf.org/html/rfc7591[RFC 7591]. -<7> JSON array containing a list of PKCE -link:https://tools.ietf.org/html/rfc7636[RFC 7636] code challenge methods -supported by this authorization server. Code challenge method values are used in -the `code_challenge_method` parameter defined in -link:https://tools.ietf.org/html/rfc7636#section-4.3[Section 4.3 of RFC 7636]. -The valid code challenge method values are those registered in the IANA -`PKCE Code Challenge Methods` registry. See -link:http://www.iana.org/assignments/oauth-parameters[IANA OAuth Parameters]. diff --git a/modules/oauth-server-overview.adoc b/modules/oauth-server-overview.adoc deleted file mode 100644 index ea50ca16e5e8..000000000000 --- a/modules/oauth-server-overview.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-authentication.adoc -// * authentication/configuring-internal-oauth.adoc - - -[id="oauth-server-overview_{context}"] -= {product-title} OAuth server - -The {product-title} master includes a built-in OAuth server. Users obtain OAuth -access tokens to authenticate themselves to the API. - -When a person requests a new OAuth token, the OAuth server uses the configured -identity provider -to determine the identity of the person making the request. - -It then determines what user that identity maps to, creates an access token for -that user, and returns the token for use. diff --git a/modules/oauth-token-requests.adoc b/modules/oauth-token-requests.adoc deleted file mode 100644 index 491f34d3699a..000000000000 --- a/modules/oauth-token-requests.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-authentication.adoc - -[id="oauth-token-requests_{context}"] -== OAuth token requests - -Every request for an OAuth token must specify the OAuth client that will -receive and use the token. The following OAuth clients are automatically -created when starting the {product-title} API: - -[options="header"] -|=== - -|OAuth client |Usage - -|`openshift-browser-client` -|Requests tokens at `<namespace_route>/oauth/token/request` with a user-agent that can handle interactive logins. ^[1]^ - -|`openshift-challenging-client` -|Requests tokens with a user-agent that can handle `WWW-Authenticate` challenges. - -|=== -[.small] --- -1. `<namespace_route>` refers to the namespace route. This is found by -running the following command: -+ -[source,terminal] ----- -$ oc get route oauth-openshift -n openshift-authentication -o json | jq .spec.host ----- --- - -All requests for OAuth tokens involve a request to -`<namespace_route>/oauth/authorize`. Most authentication integrations place an -authenticating proxy in front of this endpoint, or configure -{product-title} to validate credentials against a backing identity provider. -Requests to `<namespace_route>/oauth/authorize` can come from user-agents that -cannot display interactive login pages, such as the CLI. Therefore, -{product-title} supports authenticating using a `WWW-Authenticate` -challenge in addition to interactive login flows. - -If an authenticating proxy is placed in front of the -`<namespace_route>/oauth/authorize` endpoint, it sends unauthenticated, -non-browser user-agents `WWW-Authenticate` challenges rather than -displaying an interactive login page or redirecting to an interactive -login flow. - -[NOTE] -==== -To prevent cross-site request forgery (CSRF) attacks against browser -clients, only send Basic authentication challenges with if a -`X-CSRF-Token` header is on the request. Clients that expect -to receive Basic `WWW-Authenticate` challenges must set this header to a -non-empty value. - -If the authenticating proxy cannot support `WWW-Authenticate` challenges, -or if {product-title} is configured to use an identity provider that does -not support WWW-Authenticate challenges, you must use a browser to manually -obtain a token from -`<namespace_route>/oauth/token/request`. -==== diff --git a/modules/oauth-troubleshooting-api-events.adoc b/modules/oauth-troubleshooting-api-events.adoc deleted file mode 100644 index f52b0ac2b9f1..000000000000 --- a/modules/oauth-troubleshooting-api-events.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring-internal-oauth.adoc - -[id="oauth-troubleshooting-api-events_{context}"] -= Troubleshooting OAuth API events - -In some cases the API server returns an `unexpected condition` error message -that is difficult to debug without direct access to the API master log. -The underlying reason for the error is purposely obscured in order -to avoid providing an unauthenticated user with information about the server's state. - -A subset of these errors is related to service account OAuth configuration issues. -These issues are captured in events that can be viewed by non-administrator users. When encountering -an `unexpected condition` server error during OAuth, run `oc get events` to view these events under `ServiceAccount`. - -The following example warns of a service account that is missing a proper OAuth redirect URI: - -[source,terminal] ----- -$ oc get events | grep ServiceAccount ----- - -.Example output -[source,terminal] ----- -1m 1m 1 proxy ServiceAccount Warning NoSAOAuthRedirectURIs service-account-oauth-client-getter system:serviceaccount:myproject:proxy has no redirectURIs; set serviceaccounts.openshift.io/oauth-redirecturi.<some-value>=<redirect> or create a dynamic URI using serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference> ----- - -Running `oc describe sa/<service_account_name>` reports any OAuth events associated with the given service account name. - -[source,terminal] ----- -$ oc describe sa/proxy | grep -A5 Events ----- - -.Example output -[source,terminal] ----- -Events: - FirstSeen LastSeen Count From SubObjectPath Type Reason Message - --------- -------- ----- ---- ------------- -------- ------ ------- - 3m 3m 1 service-account-oauth-client-getter Warning NoSAOAuthRedirectURIs system:serviceaccount:myproject:proxy has no redirectURIs; set serviceaccounts.openshift.io/oauth-redirecturi.<some-value>=<redirect> or create a dynamic URI using serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference> ----- - -The following is a list of the possible event errors: - -**No redirect URI annotations or an invalid URI is specified** - -[source,terminal] ----- -Reason Message -NoSAOAuthRedirectURIs system:serviceaccount:myproject:proxy has no redirectURIs; set serviceaccounts.openshift.io/oauth-redirecturi.<some-value>=<redirect> or create a dynamic URI using serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference> ----- - -**Invalid route specified** - -[source,terminal] ----- -Reason Message -NoSAOAuthRedirectURIs [routes.route.openshift.io "<name>" not found, system:serviceaccount:myproject:proxy has no redirectURIs; set serviceaccounts.openshift.io/oauth-redirecturi.<some-value>=<redirect> or create a dynamic URI using serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference>] ----- - -**Invalid reference type specified** - -[source,terminal] ----- -Reason Message -NoSAOAuthRedirectURIs [no kind "<name>" is registered for version "v1", system:serviceaccount:myproject:proxy has no redirectURIs; set serviceaccounts.openshift.io/oauth-redirecturi.<some-value>=<redirect> or create a dynamic URI using serviceaccounts.openshift.io/oauth-redirectreference.<some-value>=<reference>] ----- - -**Missing SA tokens** - -[source,terminal] ----- -Reason Message -NoSAOAuthTokens system:serviceaccount:myproject:proxy has no tokens ----- diff --git a/modules/oauth-view-details-tokens.adoc b/modules/oauth-view-details-tokens.adoc deleted file mode 100644 index 551d7b355f40..000000000000 --- a/modules/oauth-view-details-tokens.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-oauth-access-tokens.adoc - -[id="oauth-view-details-tokens_{context}"] -= Viewing the details of a user-owned OAuth access token - -You can view the details of a user-owned OAuth access token. - -.Procedure - -* Describe the details of a user-owned OAuth access token: -+ -[source,terminal] ----- -$ oc describe useroauthaccesstokens <token_name> ----- -+ -.Example output -[source,terminal] ----- -Name: <token_name> <1> -Namespace: -Labels: <none> -Annotations: <none> -API Version: oauth.openshift.io/v1 -Authorize Token: sha256~Ksckkug-9Fg_RWn_AUysPoIg-_HqmFI9zUL_CgD8wr8 -Client Name: openshift-browser-client <2> -Expires In: 86400 <3> -Inactivity Timeout Seconds: 317 <4> -Kind: UserOAuthAccessToken -Metadata: - Creation Timestamp: 2021-01-11T19:27:06Z - Managed Fields: - API Version: oauth.openshift.io/v1 - Fields Type: FieldsV1 - fieldsV1: - f:authorizeToken: - f:clientName: - f:expiresIn: - f:redirectURI: - f:scopes: - f:userName: - f:userUID: - Manager: oauth-server - Operation: Update - Time: 2021-01-11T19:27:06Z - Resource Version: 30535 - Self Link: /apis/oauth.openshift.io/v1/useroauthaccesstokens/<token_name> - UID: f9d00b67-ab65-489b-8080-e427fa3c6181 -Redirect URI: https://oauth-openshift.apps.example.com/oauth/token/display -Scopes: - user:full <5> -User Name: <user_name> <6> -User UID: 82356ab0-95f9-4fb3-9bc0-10f1d6a6a345 -Events: <none> ----- -<1> The token name, which is the sha256 hash of the token. Token names are not sensitive and cannot be used to log in. -<2> The client name, which describes where the token originated from. -<3> The value in seconds from the creation time before this token expires. -<4> If there is a token inactivity timeout set for the OAuth server, this is the value in seconds from the creation time before this token can no longer be used. -<5> The scopes for this token. -<6> The user name associated with this token. diff --git a/modules/object-collections.adoc b/modules/object-collections.adoc new file mode 100644 index 000000000000..9e1126e2c9f4 --- /dev/null +++ b/modules/object-collections.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/create-use-collections.adoc +:_mod-docs-content-type: CONCEPT +[id="understanding-object-collections_{context}"] += Understanding deployment collections + +Deployment collections are only available to {product-title-short} customers using the PostgreSQL database. By default, {product-title-managed-short} uses the PostgreSQL database, and it is also used by default when installing {product-title-short} release 4.0 and later. {product-title-short} customers using an earlier release than 3.74 can migrate to the PostgreSQL database with help from Red{nbsp}Hat. + +An {product-title-short} collection is a user-defined, named reference. It defines a logical grouping by using selection rules. Those rules can match a deployment, namespace, or cluster name or label. You can specify rules by using exact matches or regular expressions. Collections are resolved at run time and can refer to objects that do not exist at the time of the collection definition. Collections can be constructed by using other collections to describe complex hierarchies. + +Collections provide you with a language to describe how your dynamic infrastructure is organized, eliminating the need for cloning and repetitive editing of {product-title-short} properties such as inclusion and exclusion scopes. + +You can use collections to identify any group of deployments in your system, such as: + +* An infrastructure area that is owned by a specific development team +* An application that requires different policy exceptions when running in a development or in a production cluster +* A distributed application that spans multiple namespaces, defined with a common deployment label +* An entire production or test environment + +Collections can be created and managed by using the {product-title-short} portal. The collection editor helps you apply selection rules at the deployment, namespace, and cluster level. You can use simple and complex rules, including regular expressions. For regular expressions, link:https://github.com/google/re2/wiki/Syntax[RE2 syntax] is supported. Perl syntax is not supported. + +You can define a collection by selecting one or more deployments, namespaces, or clusters, as shown in the following image. This image shows a collection that contains deployments with the name `reporting` or that contain `db` in the name. The collection includes deployments matching those names in the namespace with a specific label of `kubernetes.io/metadata.name=medical`, and in clusters named `production`. + +image::collection-rules.png[Collection rules showing rules configured for deployments with names matching, namespaces with labels matching exactly, and clusters with names matching] + +The collection editor also helps you to describe complex hierarchies by attaching, or nesting, other collections. The editor provides a real-time preview side panel that helps you understand the rules you are applying by showing the resulting matches to the rules that you have configured. The following image provides an example of results from a collection named "Sensitive User Data" with a set of collection rules (not shown). The "Sensitive User Data" collection has two attached collections, "Credit card processors" and "Medical records", and each of those collections has its own collection rules. The results shown in the side panel include items that match the rules configured for all three collections. + +image::collection-side-panel.png[Collection results from configuring a collection with two attached collections] \ No newline at end of file diff --git a/modules/odc-accessing-developer-perspective.adoc b/modules/odc-accessing-developer-perspective.adoc deleted file mode 100644 index 87464287dd51..000000000000 --- a/modules/odc-accessing-developer-perspective.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// web_console/odc-about-developer-perspective.adoc - -[id="accessing-developer-perspective_{context}"] -= Accessing the Developer perspective - -The *Developer* perspective in the {product-title} web console provides workflows specific to developer use cases. - -You can access the *Developer* perspective from the web console as follows: - -.Procedure - -. Log in to the {product-title} web console using your login credentials. The default view for the {product-title} web console is the *Administrator* perspective. -. Use the perspective switcher to switch to the *Developer* perspective. The *Topology* view with a list of all the projects in your cluster is displayed. -+ -.Developer perspective -image::odc_developer_perspective.png[] -+ -. Select an existing project from the list or use the *Project* drop-down list to create a new project. - -If you have no workloads or applications in the project, the *Topology* view displays the available options to create applications. If you have existing workloads, the *Topology* view graphically displays your workload nodes. diff --git a/modules/odc-adding-health-checks.adoc b/modules/odc-adding-health-checks.adoc deleted file mode 100644 index 1ce55d014277..000000000000 --- a/modules/odc-adding-health-checks.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application-health - -[id="odc-adding-health-checks"] -= Adding health checks using the Developer perspective - -You can use the *Topology* view to add health checks to your deployed application. - -.Prerequisites: -* You have switched to the *Developer* perspective in the web console. -* You have created and deployed an application on {product-title} using the *Developer* perspective. - -.Procedure -. In the *Topology* view, click on the application node to see the side panel. If the container does not have health checks added to ensure the smooth running of your application, a *Health Checks* notification is displayed with a link to add health checks. -. In the displayed notification, click the *Add Health Checks* link. -. Alternatively, you can also click the *Actions* drop-down list and select *Add Health Checks*. Note that if the container already has health checks, you will see the *Edit Health Checks* option instead of the add option. -. In the *Add Health Checks* form, if you have deployed multiple containers, use the *Container* drop-down list to ensure that the appropriate container is selected. -. Click the required health probe links to add them to the container. Default data for the health checks is prepopulated. You can add the probes with the default data or further customize the values and then add them. For example, to add a Readiness probe that checks if your container is ready to handle requests: -.. Click *Add Readiness Probe*, to see a form containing the parameters for the probe. -.. Click the *Type* drop-down list to select the request type you want to add. For example, in this case, select *Container Command* to select the command that will be executed inside the container. -.. In the *Command* field, add an argument `cat`, similarly, you can add multiple arguments for the check, for example, add another argument `/tmp/healthy`. -.. Retain or modify the default values for the other parameters as required, and click the check mark at the bottom of the form. The *Readiness Probe Added* message is displayed. -. Click *Add* to add the health check. You are redirected to the *Topology* view and the container is restarted. -. In the side panel, verify that the probes have been added by clicking on the deployed Pod under the *Pods* section. -. In the *Pod Details* page, click the listed container in the *Containers* section. -. In the *Container Details* page, verify that the Readiness probe - *Exec Command* `cat` `/tmp/healthy` has been added to the container. diff --git a/modules/odc-connecting-components.adoc b/modules/odc-connecting-components.adoc deleted file mode 100644 index 3799e05bc511..000000000000 --- a/modules/odc-connecting-components.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc - -[id="odc-connecting-components_{context}"] -= Connecting components within an application and across applications - -In addition to grouping multiple components within an application, you can also use the *Topology* view to connect components with each other. You can either use a binding connector or a visual one to connect components. - -A binding connection between the components can be established only if the target node is an Operator-backed service. This is indicated by the *Create a binding connector* tool-tip which appears when you drag an arrow to such a target node. When an application is connected to a service using a binding connector a service binding request is created. Then, the Service Binding Operator controller uses an intermediate secret to inject the necessary binding data into the application deployment as environment variables. After the request is successful, the application is redeployed establishing an interaction between the connected components. - -A visual connector establishes only a visual connection between the components, depicting an intent to connect. No interaction between the components is established. If the target node is not an Operator-backed service the *Create a visual connector* tool-tip is displayed when you drag an arrow to a target node. - -== Creating a visual connection between components - -You can depict an intent to connect application components using the visual connector. - -This procedure walks through an example of creating a visual connection between a MongoDB service and a Node.js application. - -.Prerequisites - -* Ensure that you have created and deployed a Node.js application using the *Developer* perspective. -* Ensure that you have created and deployed a MongoDB service using the *Developer* perspective. - -.Procedure - -. Hover over the MongoDB service to see a dangling arrow on the node. -+ -.Connector -image::odc_connector.png[] - -. Click and drag the arrow towards the Node.js component to connect the MongoDB service with it. -. Click on the MongoDB service to see the *Overview* Panel. In the *Annotations* section, click the edit icon to see the *Key = `app.openshift.io/connects-to`* and *Value = `[{"apiVersion":"apps.openshift.io/v1","kind":"DeploymentConfig","name":"nodejs-ex"}]`* annotation added to the service. - -Similarly you can create other applications and components and establish connections between them. - -.Connecting multiple applications -image::odc_connecting_multiple_applications.png[] - -== Creating a binding connection between components - -[IMPORTANT] -==== -Service Binding is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. - -For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/. -==== - -[NOTE] -==== -Currently, a few specific Operators like the *etcd* and the *PostgresSQL Database* Operator's service instances are bindable. -==== - -You can establish a binding connection with Operator-backed components. - -This procedure walks through an example of creating a binding connection between a PostgreSQL Database service and a Node.js application. To create a binding connection with a service that is backed by the PostgreSQL Database Operator, you must first add the Red Hat-provided PostgreSQL Database Operator to the *OperatorHub* using a `CatalogSource` resource, and then install the Operator. -The PostreSQL Database Operator then creates and manages the `Database` resource, which exposes the binding information in secrets, config maps, status, and spec attributes. - -.Prerequisites -* Ensure that you have created and deployed a Node.js application using the *Developer* perspective. -* Ensure that you have installed the *Service Binding Operator* from OperatorHub. - -.Procedure -. Create a `CatalogSource` resource that adds the PostgresSQL Database Operator provided by Red Hat to the *OperatorHub*. -.. In the *+Add* view, click the *YAML* option to see the *Import YAML* screen. -.. Add the following YAML file to apply the `CatalogSource` resource: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: sample-db-operators - namespace: openshift-marketplace -spec: - sourceType: grpc - image: quay.io/redhat-developer/sample-db-operators-olm:v1 - displayName: Sample DB OLM registry - updateStrategy: - registryPoll: - interval: 30m ----- -.. Click *Create* to create the `CatalogSource` resource in your cluster. -. Install the Red Hat-provided *PostgreSQL Database* Operator: -.. In the *Administrator* perspective of the console, navigate to *Operators -> OperatorHub*. -.. In the *Database* category, select the *PostgreSQL Database* Operator and install it. -. Create a database (DB) instance for the application: -.. Switch to the *Developer* perspective and ensure that you are in the appropriate project, for example, `test-project`. -.. In the *+Add* view, click the *YAML* option to see the *Import YAML* screen. -.. Add the service instance YAML in the editor and click *Create* to deploy the service. Following is an example of what the service YAML will look like: -+ -[source,YAML] ----- -apiVersion: postgresql.baiju.dev/v1alpha1 -kind: Database -metadata: - name: db-demo -spec: - image: docker.io/postgres - imageName: postgres - dbName: db-demo ----- -A DB instance is now deployed in the *Topology* view. - -. In the *Topology* view, hover over the Node.js component to see a dangling arrow on the node. -. Click and drag the arrow towards the *db-demo-postgresql* service to make a binding connection with the Node.js application. A service binding request is created and the *Service Binding Operator* controller injects the DB connection information into the application deployment as environment variables. After the request is successful, the application is redeployed and the connection is established. -+ -.Binding connector -image::odc-binding-connector.png[] diff --git a/modules/odc-creating-apiserversource.adoc b/modules/odc-creating-apiserversource.adoc deleted file mode 100644 index 3033a77d6c07..000000000000 --- a/modules/odc-creating-apiserversource.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-apiserversource.adoc - -[id="odc-creating-apiserversource_{context}"] -= Creating an API server source event source using the Developer perspective - -.Procedure - -. In the *Developer* perspective, navigate to *+Add* → *Event Source*. The *Event Sources* page is displayed. -. Optional: If you have multiple providers for your event sources, select the required provider from the *Providers* list to filter the available event sources from the provider. -. Select *ApiServerSource* and then click *Create Event Source*. The *Create Event Source* page is displayed. -. Configure the *ApiServerSource* settings by using the *Form view* or *YAML view*: -+ -[NOTE] -==== -You can switch between the *Form view* and *YAML view*. The data is persisted when switching between the views. -==== -.. Enter `v1` as the *APIVERSION* and `Event` as the *KIND*. -// .. Select *Resource* as the *Mode*. *Mode* is the mode that the receive adapter controller runs in. `Ref` sends only the reference to the resource. `Resource` sends the full resource. -// TODO: clarify what this is used for. Out of scope for this PR since not required. -.. Select the *Service Account Name* for the service account that you created. -.. Select the *Sink* for the event source. A *Sink* can be either a *Resource*, such as a channel, broker, or service, or a *URI*. -. Click *Create*. - -.Verification - -* After you have created the API server source, you will see it connected to the service it is sinked to in the *Topology* view. -+ -image::toplogy-odc-apiserver.png[ApiServerSource Topology view] - -[NOTE] -==== -If a URI sink is used, modify the URI by right-clicking on *URI sink* -> *Edit URI*. -==== diff --git a/modules/odc-creating-projects-using-developer-perspective.adoc b/modules/odc-creating-projects-using-developer-perspective.adoc deleted file mode 100644 index a1cb6070ce38..000000000000 --- a/modules/odc-creating-projects-using-developer-perspective.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="odc-creating-projects-using-developer-perspective_{context}"] -= Creating a project using the Developer perspective in the web console - -You can use the *Developer* perspective in the {product-title} web console to create a project in your cluster. - -[NOTE] -==== -Projects starting with `openshift-` and `kube-` are considered critical by {product-title}. As such, {product-title} does not allow you to create projects starting with `openshift-` or `kube-` using the *Developer* perspective. Cluster administrators can create these projects using the `oc adm new-project` command. -==== - -[NOTE] -==== -You cannot assign an SCC to pods created in one of the default namespaces: `default`, `kube-system`, `kube-public`, `openshift-node`, `openshift-infra`, and `openshift`. You cannot use these namespaces for running pods or services. -==== - -.Prerequisites - -* Ensure that you have the appropriate roles and permissions to create projects, applications, and other workloads in {product-title}. - -.Procedure -You can create a project using the *Developer* perspective, as follows: - -. Click the *Project* drop-down menu to see a list of all available projects. Select *Create Project*. -+ -.Create project -image::odc_create_project.png[] - -. In the *Create Project* dialog box, enter a unique name, such as `myproject`, in the *Name* field. -. Optional: Add the *Display Name* and *Description* details for the project. -. Click *Create*. -. Use the left navigation panel to navigate to the *Project* view and see the dashboard for your project. -. Optional: -+ -* Use the *Project* drop-down menu at the top of the screen and select *all projects* to list all of the projects in your cluster. -* Use the *Details* tab to see the project details. -* If you have adequate permissions for a project, you can use the *Project Access* tab to provide or revoke _administrator_, _edit_, and _view_ privileges for the project. diff --git a/modules/odc-creating-sample-applications.adoc b/modules/odc-creating-sample-applications.adoc deleted file mode 100644 index 96171354c924..000000000000 --- a/modules/odc-creating-sample-applications.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-creating-sample-applications.adoc - -[id="odc-creating-sample-applications_{context}"] -= Creating Sample applications - -You can use the basic sample applications in the *+Add* flow of the *Developer* perspective to create, build, and deploy applications quickly. - -The following procedure explains the *Samples* option in the *Developer* perspective to create a sample application. - -.Procedure - -. In the *+Add* view, click *Samples* to see the *Samples* page. -. On the *Samples* page, select one of the available sample applications to see the *Create Sample Application* form. -. In the *Create Sample Application Form*: -* In the *Name* field, the deployment name is displayed by default. You can modify this name as required. -* In the *Builder Image Version*, a builder image is selected by default. You can modify this image version by using the *Builder Image Version* drop-down list. -* A sample Git repository URL is added by default. -. Click *Create* to create the sample application. The build status of the sample application is displayed on the *Topology* view. After the sample application is created, you can see the deployment added to the application. diff --git a/modules/odc-deleting-apiserversource.adoc b/modules/odc-deleting-apiserversource.adoc deleted file mode 100644 index 5af9e7998d76..000000000000 --- a/modules/odc-deleting-apiserversource.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-apiserversource.adoc - -[id="odc-deleting-apiserversource_{context}"] -= Deleting an API server source using the Developer perspective - -.Procedure - -. Navigate to the *Topology* view. -. Right-click the API server source and select *Delete ApiServerSource*. -+ -image::delete-apiserversource-odc.png[Delete the ApiServerSource] diff --git a/modules/odc-deleting-applications-using-developer-perspective.adoc b/modules/odc-deleting-applications-using-developer-perspective.adoc deleted file mode 100644 index 190987ef8626..000000000000 --- a/modules/odc-deleting-applications-using-developer-perspective.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-deleting-applications.adoc - -[id="odc-deleting-applications-using-developer-perspective_{context}"] -= Deleting applications using the Developer perspective - -You can delete an application and all of its associated components using the *Topology* view in the *Developer* perspective: - -. Click the application you want to delete to see the side panel with the resource details of the application. -. Click the *Actions* drop-down menu displayed on the upper right of the panel, and select *Delete Application* to see a confirmation dialog box. -. Enter the name of the application and click *Delete* to delete it. - -You can also right-click the application you want to delete and click *Delete Application* to delete it. diff --git a/modules/odc-editing-application-configuration-using-developer-perspective.adoc b/modules/odc-editing-application-configuration-using-developer-perspective.adoc deleted file mode 100644 index c4bbb808e387..000000000000 --- a/modules/odc-editing-application-configuration-using-developer-perspective.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-editing-applications.adoc - -[id="odc-editing-application-configuration-using-developer-perspective_{context}"] -= Editing the application configuration using the Developer perspective - -You can use the *Topology* view in the *Developer* perspective to edit the configuration of your application. - -[NOTE] -==== -Currently, only configurations of applications created by using the *From Git*, *Container Image*, *From Catalog*, or *From Dockerfile* options in the *Add* workflow of the *Developer* perspective can be edited. Configurations of applications created by using the CLI or the *YAML* option from the *Add* workflow cannot be edited. -==== - -.Prerequisites -Ensure that you have created an application using the *From Git*, *Container Image*, *From Catalog*, or *From Dockerfile* options in the *Add* workflow. - -.Procedure - -. After you have created an application and it is displayed in the *Topology* view, right-click the application to see the edit options available. -+ -.Edit application -image::odc_edit_app.png[] -+ -. Click *Edit _application-name_* to see the *Add* workflow you used to create the application. The form is pre-populated with the values you had added while creating the application. -. Edit the necessary values for the application. -+ -[NOTE] -==== -You cannot edit the *Name* field in the *General* section, the CI/CD pipelines, or the *Create a route to the application* field in the *Advanced Options* section. -==== -+ -. Click *Save* to restart the build and deploy a new image. -+ -.Edit and redeploy application -image::odc_edit_redeploy.png[] diff --git a/modules/odc-editing-health-checks.adoc b/modules/odc-editing-health-checks.adoc deleted file mode 100644 index 8b267ab46923..000000000000 --- a/modules/odc-editing-health-checks.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application-health - -[id="odc-editing-health-checks"] -= Editing health checks using the Developer perspective - -You can use the *Topology* view to edit health checks added to your application, modify them, or add more health checks. - -.Prerequisites: -* You have switched to the *Developer* perspective in the web console. -* You have created and deployed an application on {product-title} using the *Developer* perspective. -* You have added health checks to your application. - -.Procedure -. In the *Topology* view, right-click your application and select *Edit Health Checks*. Alternatively, in the side panel, click the *Actions* drop-down list and select *Edit Health Checks*. -. In the *Edit Health Checks* page: - -* To remove a previously added health probe, click the minus sign adjoining it. -* To edit the parameters of an existing probe: -+ -.. Click the *Edit Probe* link next to a previously added probe to see the parameters for the probe. -.. Modify the parameters as required, and click the check mark to save your changes. -+ -* To add a new health probe, in addition to existing health checks, click the add probe links. For example, to add a Liveness probe that checks if your container is running: -+ -.. Click *Add Liveness Probe*, to see a form containing the parameters for the probe. -.. Edit the probe parameters as required, and click the check mark at the bottom of the form. The *Liveness Probe Added* message is displayed. -. Click *Save* to save your modifications and add the additional probes to your container. You are redirected to the *Topology* view. -. In the side panel, verify that the probes have been added by clicking on the deployed pod under the *Pods* section. -. In the *Pod Details* page, click the listed container in the *Containers* section. -. In the *Container Details* page, verify that the Liveness probe - `HTTP Get 10.129.4.65:8080/` has been added to the container, in addition to the earlier existing probes. diff --git a/modules/odc-editing-source-code-using-developer-perspective.adoc b/modules/odc-editing-source-code-using-developer-perspective.adoc deleted file mode 100644 index ec959d94790d..000000000000 --- a/modules/odc-editing-source-code-using-developer-perspective.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-editing-applications.adoc - -[id="odc-editing-source-code-using-developer-perspective_{context}"] -= Editing the source code of an application using the Developer perspective - -You can use the *Topology* view in the *Developer* perspective to edit the source code of your application. - -.Procedure - -* In the *Topology* view, click the *Edit Source code* icon, displayed at the bottom-right of the deployed application, to access your source code and modify it. -+ -[NOTE] -==== -This feature is available only when you create applications using the *From Git*, *From Catalog*, and the *From Dockerfile* options. -==== -+ -If the *Eclipse Che* Operator is installed in your cluster, a Che workspace (image:odc_che_workspace.png[title="Che Workspace"]) is created and you are directed to the workspace to edit your source code. If it is not installed, you will be directed to the Git repository (image:odc_git_repository.png[title="Git Repository"]) your source code is hosted in. diff --git a/modules/odc-grouping-multiple-components.adoc b/modules/odc-grouping-multiple-components.adoc deleted file mode 100644 index 11b0b19e6a3a..000000000000 --- a/modules/odc-grouping-multiple-components.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc - -[id="odc-grouping-multiple-components_{context}"] -= Grouping multiple components within an application - -You can use the *+Add* view to add multiple components or services to your project and use the *Topology* view to group applications and resources within an application group. -The following procedure adds a MariaDB database service to an existing application with a Node.js component. - - -.Prerequisites - -* Ensure that you have created and deployed a Node.js application on {product-title} using the *Developer* perspective. - -.Procedure - -. Create and deploy the MariaDB service to your project: -.. In the *Developer* perspective, navigate to the *+Add* view and select the *From Catalog* option to view all available services in the *Developer Catalog*. -.. Select *Databases* to list all the database services and then click *MariaDB* option to see the details for the service. -.. Click *Instantiate Template* to see an automatically populated template with details for the MariaDB service, and then click *Create* to create and view the MariaDB service in the *Topology* view. - -. To add the MariaDB service to the existing application group, press kbd:[Shift]+ drag the *mariadb* pod to the application group that contains the Node.Js component. The MariaDB service is added to the existing application group. - -. Click the MariaDB service node and confirm that the `app.kubernetes.io/part-of=<application-name>` label is in the *Labels* section in the *Overview* Panel. Adding a component to an application group automatically adds the required labels to the component. -+ -.Application grouping -image::odc_app_grouping_label.png[] - -You can remove a component from an application group by selecting the component and using kbd:[Shift]+ drag to drag it out of the application group. diff --git a/modules/odc-importing-codebase-from-git-to-create-application.adoc b/modules/odc-importing-codebase-from-git-to-create-application.adoc deleted file mode 100644 index 59c49cc4e70a..000000000000 --- a/modules/odc-importing-codebase-from-git-to-create-application.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc - -[id="odc-importing-codebase-from-git-to-create-application_{context}"] -= Importing a codebase from Git to create an application - -You can use the *Developer* perspective to create, build, and deploy an application on {product-title} using an existing codebase in GitHub. - -The following procedure walks you through the *From Git* option in the *Developer* perspective to create an application. - -.Procedure - -. In the *+Add* view, click *From Git* to see the *Import from git* form. -. In the *Git* section, enter the Git repository URL for the codebase you want to use to create an application. For example, enter the URL of this sample Node.js application `\https://github.com/sclorg/nodejs-ex`. The URL is then validated. -. Optional: You can click *Show Advanced Git Options* to add details such as: - -* *Git Reference* to point to code in a specific branch, tag, or commit to be used to build the application. -* *Context Dir* to specify the subdirectory for the application source code you want to use to build the application. -* *Source Secret* to create a *Secret Name* with credentials for pulling your source code from a private repository. - -. In the *Builder* section, after the URL is validated, an appropriate builder image is detected, indicated by a star, and automatically selected. For the `https://github.com/sclorg/nodejs-ex` Git URL, the Node.js builder image is selected by default. If a builder image is not auto-detected, select a builder image. If required, you can change the version using the *Builder Image Version* drop-down list. - -. In the *General* section: -.. In the *Application* field, enter a unique name for the application grouping, for example, `myapp`. Ensure that the application name is unique in a namespace. -.. The *Name* field to identify the resources created for this application is automatically populated based on the Git repository URL if there are no existing applications. If there are existing applications, you can choose to deploy the component within an existing application, create a new application, or keep the component unassigned. -+ -[NOTE] -==== -The resource name must be unique in a namespace. Modify the resource name if you get an error. -==== - -. In the *Resources* section, select: - -* *Deployment*, to create an application in plain Kubernetes style. -* *Deployment Config*, to create an OpenShift style application. -* *Knative Service*, to create a microservice. - -+ -[NOTE] -==== -The *Knative Service* option is displayed in the *Import from git* form only if the *Serverless Operator* is installed in your cluster. For further details refer to documentation on installing OpenShift Serverless. -==== -. In the *Pipelines* section, select *Add Pipeline*, and then click *Show Pipeline Visualization* to see the pipeline for the application. -. In the *Advanced Options* section, the *Create a route to the application* is selected by default so that you can access your application using a publicly available URL. You can clear the check box if you do not want to expose your application on a public route. -. Optional: You can use the following advanced options to further customize your application: - -Routing:: -Click the *Routing* link to: -* Customize the hostname for the route. -* Specify the path the router watches. -* Select the target port for the traffic from the drop-down list. -* Secure your route by selecting the *Secure Route* check box. Select the required TLS termination type and set a policy for insecure traffic from the respective drop-down lists. -+ -For serverless applications, the Knative Service manages all the routing options above. However, you can customize the target port for traffic, if required. If the target port is not specified, the default port of `8080` is used. - -Health Checks:: -Click the *Health Checks* link to add Readiness, Liveness, and Startup probes to your application. All the probes have prepopulated default data; you can add the probes with the default data or customize it as required. -+ -To customize the health probes: -+ -* Click *Add Readiness Probe*, if required, modify the parameters to check if the container is ready to handle requests, and select the check mark to add the probe. -* Click *Add Liveness Probe*, if required, modify the parameters to check if a container is still running, and select the check mark to add the probe. -* Click *Add Startup Probe*, if required, modify the parameters to check if the application within the container has started, and select the check mark to add the probe. -+ -For each of the probes, you can specify the request type - *HTTP GET*, *Container Command*, or *TCP Socket*, from the drop-down list. The form changes as per the selected request type. You can then modify the default values for the other parameters, such as the success and failure thresholds for the probe, number of seconds before performing the first probe after the container starts, frequency of the probe, and the timeout value. - - -Build Configuration and Deployment:: -Click the *Build Configuration* and *Deployment* links to see the respective configuration options. Some options are selected by default; you can customize them further by adding the necessary triggers and environment variables. -+ -For serverless applications, the *Deployment* option is not displayed as the Knative configuration resource maintains the desired state for your deployment instead of a DeploymentConfig. - -Scaling:: -Click the *Scaling* link to define the number of pods or instances of the application you want to deploy initially. -+ -For serverless applications, you can: - -* Set the upper and lower limit for the number of pods that can be set by the autoscaler. If the lower limit is not specified, it defaults to zero. -* Define the soft limit for the required number of concurrent requests per instance of the application at a given time. It is the recommended configuration for autoscaling. If not specified, it takes the value specified in the cluster configuration. -* Define the hard limit for the number of concurrent requests allowed per instance of the application at a given time. This is configured in the revision template. If not specified, it defaults to the value specified in the cluster configuration. - -Resource Limit:: -Click the *Resource Limit* link to set the amount of *CPU* and *Memory* resources a container is guaranteed or allowed to use when running. - -Labels:: -Click the *Labels* link to add custom labels to your application. - -. Click *Create* to create the application and see its build status in the *Topology* view. diff --git a/modules/odc-installing-helm-charts.adoc b/modules/odc-installing-helm-charts.adoc deleted file mode 100644 index f36aee890148..000000000000 --- a/modules/odc-installing-helm-charts.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-working-with-helm-charts-using-developer-perspective.adoc - -[id="odc-installing-helm-charts_{context}"] -= Installing Helm charts - -You can use either the *Developer* perspective or the CLI to create Helm releases and see them in the *Developer* perspective of the web console. - -.Procedure -To create Helm releases from the Helm charts provided in the *Developer Catalog*: - -. In the *Developer* perspective, navigate to the *+Add* view and select a project. Then click *Helm Chart* option to see all the Helm Charts in the *Developer Catalog*. -. Select a chart and read the description, README, and other details about the chart. -. Click *Install Helm Chart*. -+ -.Helm charts in developer catalog -image::odc_helm_chart_devcatalog.png[] -+ -. In the *Install Helm Chart* page: -.. Enter a unique name for the release in the *Release Name* field. -.. Select the required chart version from the *Chart Version* drop-down list. -.. Configure your Helm chart by using the *Form View* or the *YAML View*. -+ -[NOTE] -==== -Where available, you can switch between the *YAML View* and *Form View*. The data is persisted when switching between the views. -==== -+ -.. Click *Install* to create a Helm release. You will be redirected to the *Topology* view where the release is displayed. If the Helm chart has release notes, the chart is pre-selected and the right panel displays the release notes for that release. - -You can upgrade, rollback, or uninstall a Helm release by using the *Actions* button on the side panel or by right-clicking a Helm release. diff --git a/modules/odc-installing-web-terminal.adoc b/modules/odc-installing-web-terminal.adoc deleted file mode 100644 index ac35ed740013..000000000000 --- a/modules/odc-installing-web-terminal.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// web_console/odc-about-web-terminal.adoc - -[id="odc-installing-web-terminal_{context}"] -= Installing the web terminal - -You can install the web terminal using the Web Terminal Operator listed in the {product-title} OperatorHub. When you install the Web Terminal Operator, the custom resource definitions (CRDs) that are required for the command line configuration, such as the `DevWorkspace` CRD, are automatically installed. The web console creates the required resources when you open the web terminal. - -.Prerequisites -* Access to an {product-title} cluster using an account with `cluster-admin` permissions. - -.Procedure -. In the *Administrator* perspective of the web console, navigate to *Operators -> OperatorHub*. -. Use the *Filter by keyword* box to search for the `Web Terminal` Operator in the catalog, and then click the *Web Terminal* tile. -. Read the brief description about the Operator on the *Web Terminal* page, and then click *Install*. -. On the *Install Operator* page, retain the default values for all fields. - -** The *alpha* option in the *Update Channel* menu enables installation of the latest release of the Web Terminal Operator. -** The *All namespaces on the cluster* option in the *Installation Mode* menu enables the Operator to watch and be available to all namespaces in the cluster. -** The *openshift-operators* option in the *Installed Namespace* menu installs the Operator in the default `openshift-operators` namespace. -** The *Automatic* option in the *Approval Strategy* menu ensures that the future upgrades to the Operator are handled automatically by the Operator Lifecycle Manager. - -. Click *Install*. -. In the *Installed Operators* page, click the *View operator* to verify that the Operator is listed on the *Installed Operators* page. -. After the Operator is installed, refresh your page to see the command line terminal icon on the upper right of the console. diff --git a/modules/odc-interacting-with-applications-and-components.adoc b/modules/odc-interacting-with-applications-and-components.adoc deleted file mode 100644 index d98fc4421e86..000000000000 --- a/modules/odc-interacting-with-applications-and-components.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc - -[id="odc-interacting-with-applications-and-components_{context}"] -= Interacting with applications and components - -The *Topology* view in the *Developer* perspective of the web console provides the following options to interact with applications and components: - -* Click *Open URL* (image:odc_open_url.png[title="Application Link"]) to see your application exposed by the route on a public URL. -* Click *Edit Source code* to access your source code and modify it. -+ -[NOTE] -==== -This feature is available only when you create applications using the *From Git*, *From Catalog*, and the *From Dockerfile* options. -==== -+ -* Hover your cursor over the lower left icon on the Pod to see the name of the latest build and its status. The status of the application build is indicated as *New* (image:odc_build_new.png[title="New Build"]), *Pending* (image:odc_build_pending.png[title="Pending Build"]), *Running* (image:odc_build_running.png[title="Running Build"]), *Completed* (image:odc_build_completed.png[title="Completed Build"]), *Failed* (image:odc_build_failed.png[title="Failed Build"]), and *Canceled* (image:odc_build_canceled.png[title="Canceled Build"]). -* The status or phase of the pod is indicated by different colors and tooltips as *Running* (image:odc_pod_running.png[title="Pod Running"]), *Not Ready* (image:odc_pod_not_ready.png[title="Pod Not Ready"]), *Warning*(image:odc_pod_warning.png[title="Pod Warning"]), *Failed*(image:odc_pod_failed.png[title="Pod Failed"]), *Pending*(image:odc_pod_pending.png[title="Pod Pending"]), *Succeeded*(image:odc_pod_succeeded.png[title="Pod Succeeded"]), *Terminating*(image:odc_pod_terminating.png[title="Pod Terminating"]), or *Unknown*(image:odc_pod_unknown.png[title="Pod Unknown"]). -For more information about pod status, see the link:https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-phase[Kubernetes documentation]. -* After you create an application and an image is deployed, the status is shown as *Pending*. After the application is built, it is displayed as *Running*. -+ -.Application topology -image::odc_application_topology.png[] -+ -The application resource name is appended with indicators for the different types of resource objects as follows: -+ -** *CJ*: `CronJob` -** *D*: `Deployment` -** *DC*: `DeploymentConfig` -** *DS*: `DaemonSet` -** *J*: `Job` -** *P*: `Pod` -** *SS*: `StatefulSet` -** image:odc_serverless_app.png[title="Serverless Application"] (Knative): A serverless application -+ -[NOTE] -==== -Serverless applications take some time to load and display on the *Graph view*. When you deploy a serverless application, it first creates a service resource and then a revision. After that, it is deployed and displayed on the *Graph view*. If it is the only workload, you might be redirected to the *Add* page. After the revision is deployed, the serverless application is displayed on the *Graph view*. -==== diff --git a/modules/odc-labels-and-annotations-used-for-topology-view.adoc b/modules/odc-labels-and-annotations-used-for-topology-view.adoc deleted file mode 100644 index 76eddc511502..000000000000 --- a/modules/odc-labels-and-annotations-used-for-topology-view.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc - -[id="odc-labels-and-annotations-used-for-topology-view_{context}"] -= Labels and annotations used for the Topology view - -The *Topology* view uses the following labels and annotations: - -Icon displayed in the node:: Icons in the node are defined by looking for matching icons using the `app.openshift.io/runtime` label, followed by the `app.kubernetes.io/name` label. This matching is done using a predefined set of icons. -Link to the source code editor or the source:: The `app.openshift.io/vcs-uri` annotation is used to create links to the source code editor. -Node Connector:: The `app.openshift.io/connects-to` annotation is used to connect the nodes. -App grouping:: The `app.kubernetes.io/part-of=<appname>` label is used to group the applications, services, and components. - -For detailed information on the labels and annotations {product-title} applications must use, see link:https://github.com/gorkem/app-labels/blob/master/labels-annotation-for-openshift.adoc[Guidelines for labels and annotations for OpenShift applications]. diff --git a/modules/odc-monitoring-application-health-using-developer-perspective.adoc b/modules/odc-monitoring-application-health-using-developer-perspective.adoc deleted file mode 100644 index 643921638b08..000000000000 --- a/modules/odc-monitoring-application-health-using-developer-perspective.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application-health - -[id="odc-monitoring-application-health-using-developer-perspective"] -= Monitoring application health using the Developer perspective - -You can use the *Developer* perspective to add three types of health probes to your container to ensure that your application is healthy: - -* Use the Readiness probe to check if the container is ready to handle requests. -* Use the Liveness probe to check if the container is running. -* Use the Startup probe to check if the application within the container has started. - -You can add health checks either while creating and deploying an application, or after you have deployed an application. diff --git a/modules/odc-monitoring-health-checks.adoc b/modules/odc-monitoring-health-checks.adoc deleted file mode 100644 index 41b49d46e06a..000000000000 --- a/modules/odc-monitoring-health-checks.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application-health - -[id="odc-monitoring-health-checks"] -= Monitoring health check failures using the Developer perspective - -In case an application health check fails, you can use the *Topology* view to monitor these health check violations. - -.Prerequisites: -* You have switched to the *Developer* perspective in the web console. -* You have created and deployed an application on {product-title} using the *Developer* perspective. -* You have added health checks to your application. - -.Procedure -. In the *Topology* view, click on the application node to see the side panel. -. Click the *Monitoring* tab to see the health check failures in the *Events (Warning)* section. -. Click the down arrow adjoining *Events (Warning)* to see the details of the health check failure. diff --git a/modules/odc-monitoring-your-application-metrics.adoc b/modules/odc-monitoring-your-application-metrics.adoc deleted file mode 100644 index e7f34629af63..000000000000 --- a/modules/odc-monitoring-your-application-metrics.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/odc-monitoring-project-and-application-metrics-using-developer-perspective.adoc - -[id="odc-monitoring-your-application-metrics_{context}"] -= Monitoring your application metrics - -After you create applications in your project and deploy them, you can use the *Topology* view in the *Developer* perspective to see the alerts and metrics for your application. Critical and warning alerts for your application are indicated on the workload node in the *Topology* view. - -.Procedure -To see the alerts for your workload: - -. In the *Topology* view, click the workload to see the workload details in the right panel. -. Click the *Monitoring* tab to see the critical and warning alerts for the application; graphs for metrics, such as CPU, memory, and bandwidth usage; and all the events for the application. -+ -[NOTE] -==== -Only critical and warning alerts in the *Firing* state are displayed in the *Topology* view. Alerts in the *Silenced*, *Pending* and *Not Firing* states are not displayed. -==== -+ -.Monitoring application metrics -image::odc_app_metrics.png[] -+ -.. Click the alert listed in the right panel to see the alert details in the *Alert Details* page. -.. Click any of the charts to go to the *Metrics* tab to see the detailed metrics for the application. -.. Click *View monitoring dashboard* to see the monitoring dashboard for that application. diff --git a/modules/odc-monitoring-your-project-metrics.adoc b/modules/odc-monitoring-your-project-metrics.adoc deleted file mode 100644 index 925960cd94ab..000000000000 --- a/modules/odc-monitoring-your-project-metrics.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/odc-monitoring-project-and-application-metrics-using-developer-perspective.adoc - -[id="odc-monitoring-your-project-metrics_{context}"] -= Monitoring your project metrics - -After you create applications in your project and deploy them, you can use the *Developer* perspective in the web console to see the metrics for your project. - -.Procedure - -. On the left navigation panel of the *Developer* perspective, click *Monitoring* to see the *Dashboard*, *Metrics*, *Alerts*, and *Events* for your project. - -* Use the *Dashboard* tab to see graphs depicting the CPU, memory, and bandwidth consumption and network related information, such as the rate of transmitted and received packets and the rate of dropped packets. -+ -.Monitoring dashboard -image::odc_project_dashboard.png[] -+ -Use the following options to see further details: - -** Select a workload from the *All Workloads* list to see the filtered metrics for the selected workload. -** Select an option from the *Time Range* list to determine the time frame for the data being captured. -** Select an option from the *Refresh Interval* list to determine the time period after which the data is refreshed. -** Hover your cursor over the graphs to see specific details for your pod. -** Click on any of the graphs displayed to see the details for that particular metric in the *Metrics* page. - -* Use the *Metrics* tab to query for the required project metric. -+ -.Monitoring metrics -image::odc_project_metrics.png[] -+ -.. In the *Select Query* list, select an option to filter the required details for your project. The filtered metrics for all the application pods in your project are displayed in the graph. The pods in your project are also listed below. -.. From the list of pods, clear the colored square boxes to remove the metrics for specific pods to further filter your query result. -.. Click *Show PromQL* to see the Prometheus query. You can further modify this query with the help of prompts to customize the query and filter the metrics you want to see for that namespace. -.. Use the drop-down list to set a time range for the data being displayed. You can click *Reset Zoom* to reset it to the default time range. -.. Optionally, in the *Select Query* list, select *Custom Query* to create a custom Prometheus query and filter relevant metrics. - -* Use the *Alerts* tab to see the rules that trigger alerts for the applications in your project, identify the alerts firing in the project, and silence them if required. -+ -.Monitoring alerts -image::odc_project_alerts.png[] -+ -** Use the *Filter* list to filter the alerts by their *Alert State* and *Severity*. - -** Click on an alert to go to the details page for that alert. In the *Alerts Details* page, you can click the *View Metrics* button to see the metrics for the alert. - -** Use the *Notifications* toggle adjoining an alert rule to silence all the alerts for that rule, and then select the duration for which the alerts will be silenced from the *Silence for* list. -You must have the permissions to edit alerts to see the *Notifications* toggle. - -** Use the *Options* menu {kebab} adjoining an alert rule to see the details of the alerting rule. - -* Use the *Events* tab to see the events for your project. -+ -.Monitoring events -image::odc_project_events.png[] -+ -You can filter the displayed events using the following options: - -** In the *Resources* list, select a resource to see events for that resource. -** In the *All Types* list, select a type of event to see events relevant to that type. -** Search for specific events using the *Filter events by names or messages* field. diff --git a/modules/odc-providing-project-permissions-using-developer-perspective.adoc b/modules/odc-providing-project-permissions-using-developer-perspective.adoc deleted file mode 100644 index 4c3efb1c6eec..000000000000 --- a/modules/odc-providing-project-permissions-using-developer-perspective.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="odc-providing-project-permissions-using-developer-perspective_{context}"] -= Providing access permissions to your project using the Developer perspective - -You can use the *Project* view in the *Developer* perspective to grant or revoke access permissions to your project. - -.Procedure -To add users to your project and provide *Admin*, *Edit*, or *View* access to them: - -. In the *Developer* perspective, navigate to the *Project* view. -. In the *Project* page, select the *Project Access* tab. -. Click *Add Access* to add a new row of permissions to the default ones. -+ -.Project permissions -image::odc_project_permissions.png[] -. Enter the user name, click the *Select a role* drop-down list, and select an appropriate role. -. Click *Save* to add the new permissions. - -You can also use: - -* The *Select a role* drop-down list, to modify the access permissions of an existing user. -* The *Remove Access* icon, to completely remove the access permissions of an existing user to the project. - -[NOTE] -==== -Advanced role-based access control is managed in the *Roles* and *Roles Binding* views in the *Administrator* perspective. -==== diff --git a/modules/odc-rolling-back-helm-release.adoc b/modules/odc-rolling-back-helm-release.adoc deleted file mode 100644 index 1082a87229e9..000000000000 --- a/modules/odc-rolling-back-helm-release.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-working-with-helm-charts-using-developer-perspective.adoc - -[id="odc-rolling-back-helm-release_{context}"] -= Rolling back a Helm release - -If a release fails, you can rollback the Helm release to a previous version. - -.Procedure -To rollback a release using the *Helm* view: - -. In the *Developer* perspective, navigate to the *Helm* view to see the *Helm Releases* in the namespace. -. Click the *Options* menu {kebab} adjoining the listed release, and select *Rollback*. -. In the *Rollback Helm Release* page, select the *Revision* you want to rollback to and click *Rollback*. -. In the *Helm Releases* page, click on the chart to see the details and resources for that release. -. Go to the *Revision History* tab to see all the revisions for the chart. -+ -.Helm revision history -image::odc_helm_revision_history.png[] -+ -. If required, you can further use the *Options* menu {kebab} adjoining a particular revision and select the revision to rollback to. diff --git a/modules/odc-scaling-application-pods-and-checking-builds-and-routes.adoc b/modules/odc-scaling-application-pods-and-checking-builds-and-routes.adoc deleted file mode 100644 index ba5cbb97c3d4..000000000000 --- a/modules/odc-scaling-application-pods-and-checking-builds-and-routes.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc - -[id="odc-scaling-application-pods-and-checking-builds-and-routes_{context}"] -= Scaling application pods and checking builds and routes - -The *Topology* view provides the details of the deployed components in the *Overview* panel. You can use the *Overview* and *Resources* tabs to scale the application pods, check build status, services, and routes as follows: - - -* Click on the component node to see the *Overview* panel to the right. Use the *Overview* tab to: - -** Scale your pods using the up and down arrows to increase or decrease the number of instances of the application manually. For serverless applications, the pods are automatically scaled down to zero when idle and scaled up depending on the channel traffic. -** Check the *Labels*, *Annotations*, and *Status* of the application. - -* Click the *Resources* tab to: - -** See the list of all the pods, view their status, access logs, and click on the pod to see the pod details. -** See the builds, their status, access logs, and start a new build if needed. -** See the services and routes used by the component. - -+ -For serverless applications, the *Resources* tab provides information on the revision, routes, and the configurations used for that component. diff --git a/modules/odc-splitting-traffic-between-revisions-using-developer-perspective.adoc b/modules/odc-splitting-traffic-between-revisions-using-developer-perspective.adoc deleted file mode 100644 index ead8e45f53f6..000000000000 --- a/modules/odc-splitting-traffic-between-revisions-using-developer-perspective.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/splitting-traffic-between-revisions-knative.adoc - -[id="odc-splitting-traffic-between-revisions-using-developer-perspective_{context}"] -= Splitting traffic between revisions using the Developer perspective - -After you create a serverless application, the serverless application is displayed in the *Topology* view of the *Developer* perspective. The application revision is represented by the node and the serverless resource service is indicated by a quadrilateral around the node. - -Any new change in the code or the service configuration triggers a revision, a snapshot of the code at a given time. For a service, you can manage the traffic between the revisions of the service by splitting and routing it to the different revisions as required. - -.Procedure -To split traffic between multiple revisions of an application in the *Topology* view: - -. Click the serverless resource service, indicated by the quadrilateral, to see its overview in the side panel. -. Click the *Resources* tab, to see a list of *Revisions* and *Routes* for the service. -+ -.Serverless application -image::odc-serverless-app.png[] - -. Click the service, indicated by the *S* icon at the top of the side panel, to see an overview of the service details. -. Click the *YAML* tab and modify the service configuration in the YAML editor, and click *Save*. For example, change the `timeoutseconds` from 300 to 301 . This change in the configuration triggers a new revision. In the *Topology* view, the latest revision is displayed and the *Resources* tab for the service now displays the two revisions. -. In the *Resources* tab, click the btn:[Set Traffic Distribution] button to see the traffic distribution dialog box: -.. Add the split traffic percentage portion for the two revisions in the *Splits* field. -.. Add tags to create custom URLs for the two revisions. -.. Click *Save* to see two nodes representing the two revisions in the Topology view. -+ -.Serverless application revisions -image::odc-serverless-revisions.png[] diff --git a/modules/odc-starting-recreate-deployment.adoc b/modules/odc-starting-recreate-deployment.adoc deleted file mode 100644 index 8545329fa4b1..000000000000 --- a/modules/odc-starting-recreate-deployment.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/deployment-strategies.adoc - -[id="odc-starting-recreate-deployment_{context}"] -= Starting a recreate deployment using the Developer perspective - -You can switch the deployment strategy from the default rolling update to a recreate update using the *Developer* perspective in the web console. - -.Prerequisites -* Ensure that you are in the *Developer* perspective of the web console. -* Ensure that you have created an application using the *Add* view and see it deployed in the *Topology* view. - -.Procedure - -To switch to a recreate update strategy and to upgrade an application: - -. In the *Actions* drop-down menu, select *Edit Deployment Config* to see the deployment configuration details of the application. -. In the YAML editor, change the `spec.strategy.type` to `Recreate` and click *Save*. -. In the *Topology* view, select the node to see the *Overview* tab in the side panel. The *Update Strategy* is now set to *Recreate*. -. Use the *Actions* drop-down menu to select *Start Rollout* to start an update using the recreate strategy. The recreate strategy first terminates pods for the older version of the application and then spins up pods for the new version. -+ -.Recreate update -image::odc-recreate-update.png[] diff --git a/modules/odc-starting-rolling-deployment.adoc b/modules/odc-starting-rolling-deployment.adoc deleted file mode 100644 index 369a1de673c8..000000000000 --- a/modules/odc-starting-rolling-deployment.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/deployments/deployment-strategies.adoc - -[id="odc-starting-rolling-deployment_{context}"] -= Starting a rolling deployment using the Developer perspective - -.Prerequisites -* Ensure that you are in the *Developer* perspective of the web console. -* Ensure that you have created an application using the *Add* view and see it deployed in the *Topology* view. - -.Procedure - -To start a rolling deployment to upgrade an application: - -. In the *Topology* view of the *Developer* perspective, click on the application node to see the *Overview* tab in the side panel. Note that the *Update Strategy* is set to the default *Rolling* strategy. -. In the *Actions* drop-down menu, select *Start Rollout* to start a rolling update. The rolling deployment spins up the new version of the application and then terminates the old one. -+ -.Rolling update -image::odc-rolling-update.png[] diff --git a/modules/odc-uninstalling-helm-release.adoc b/modules/odc-uninstalling-helm-release.adoc deleted file mode 100644 index ac92cc419f04..000000000000 --- a/modules/odc-uninstalling-helm-release.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-working-with-helm-charts-using-developer-perspective.adoc - -[id="odc-uninstalling-helm-release_{context}"] -= Uninstalling a Helm release - -.Procedure -. In the *Topology* view, right-click the Helm release and select *Uninstall Helm Release*. -. In the confirmation prompt, enter the name of the chart and click *Uninstall*. diff --git a/modules/odc-uninstalling-web-terminal.adoc b/modules/odc-uninstalling-web-terminal.adoc deleted file mode 100644 index 053c8b83cc6e..000000000000 --- a/modules/odc-uninstalling-web-terminal.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// Module included in the following assemblies: -// -// web_console/odc-about-web-terminal.adoc - -[id="odc-uninstalling-web-terminal_{context}"] -= Uninstalling the web terminal - -Uninstalling the web terminal is a two-step process: - -. Delete the components and custom resources (CRs) that were added when you installed the Operator. -. Uninstall the Web Terminal Operator. - -Uninstalling the Web Terminal Operator does not remove any of its custom resource definitions (CRDs) or managed resources that are created when the Operator is installed. These components must be manually uninstalled for security purposes. Removing these components also allows you to save cluster resources by ensuring that terminals do not idle when the Operator is uninstalled. - -.Prerequisites -* Access to an {product-title} cluster using an account with `cluster-admin` permissions. - -== Deleting the web terminal components and custom resources - -Use the CLI to delete the CRs that are created during installation of the Web Terminal Operator. - -.Procedure -. Run the following commands to ensure that all `DevWorkspace` CRs are removed along with their related Kubernetes objects, such as deployments. -+ -[source,terminal] ----- -$ oc delete devworkspaces.workspace.devfile.io --all-namespaces --all --wait ----- -+ -[source,terminal] ----- -$ oc delete workspaceroutings.controller.devfile.io --all-namespaces --all --wait ----- -+ -[source,terminal] ----- -$ oc delete components.controller.devfile.io --all-namespaces --all --wait ----- -+ -[WARNING] -==== -If this step is not complete, finalizers make it difficult to fully uninstall the Operator easily. -==== -+ -. Run the following commands to remove the CRDs: -+ -[source,terminal] ----- -$ oc delete customresourcedefinitions.apiextensions.k8s.io workspaceroutings.controller.devfile.io ----- -+ -[source,terminal] ----- -$ oc delete customresourcedefinitions.apiextensions.k8s.io components.controller.devfile.io ----- -+ -[source,terminal] ----- -$ oc delete customresourcedefinitions.apiextensions.k8s.io devworkspaces.workspace.devfile.io ----- -+ -. Remove the `DevWorkspace-Webhook-Server` deployment: -+ -[source,terminal] ----- -$ oc delete deployment/devworkspace-webhook-server -n openshift-operators ----- -+ -[NOTE] -==== -When you run this and the following steps, you cannot use the `oc exec` commands to run commands in a container. After you remove the webhooks you will be able to use the `oc exec` commands again. -==== -+ -. Run the following commands to remove any lingering services, secrets, and config maps: -+ -[source,terminal] ----- -$ oc delete all --selector app.kubernetes.io/part-of=devworkspace-operator,app.kubernetes.io/name=devworkspace-webhook-server ----- -+ -[source,terminal] ----- -$ oc delete serviceaccounts devworkspace-webhook-server -n openshift-operators ----- -+ -[source,terminal] ----- -$ oc delete configmap devworkspace-controller -n openshift-operators ----- -+ -[source,terminal] ----- -$ oc delete clusterrole devworkspace-webhook-server ----- -+ -[source,terminal] ----- -$ oc delete clusterrolebinding devworkspace-webhook-server ----- -+ -. Run the following commands to remove mutating or validating webhook configurations: -+ -[source,terminal] ----- -$ oc delete mutatingwebhookconfigurations controller.devfile.io ----- -+ -[source,terminal] ----- -$ oc delete validatingwebhookconfigurations controller.devfile.io ----- - -== Uninstalling the Operator using the web console - -.Procedure - -. In the *Administrator* perspective of the web console, navigate to *Operators -> Installed Operators*. -. Scroll the filter list or type a keyword into the *Filter by name* box to find the *Web Terminal* Operator. -. Click the Options menu {kebab} for the Web Terminal Operator, and then select *Uninstall Operator*. -. In the *Uninstall Operator* confirmation dialog box, click *Uninstall* to remove the Operator, Operator deployments, and pods from the cluster. The Operator stops running and no longer receives updates. diff --git a/modules/odc-upgrading-helm-release.adoc b/modules/odc-upgrading-helm-release.adoc deleted file mode 100644 index 8d77443f180a..000000000000 --- a/modules/odc-upgrading-helm-release.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-working-with-helm-charts-using-developer-perspective.adoc - -[id="odc-upgrading-helm-release_{context}"] -= Upgrading a Helm release - -You can upgrade a Helm release to upgrade to a new chart version or update your release configuration. - -.Procedure - -. In the *Topology* view, select the Helm release to see the side panel. -. Click *Actions* -> *Upgrade Helm Release*. -. In the *Upgrade Helm Release* page, select the *Chart Version* you want to upgrade to, and then click *Upgrade* to create another Helm release. The *Helm Releases* page displays the two revisions. diff --git a/modules/odc-using-the-developer-catalog-to-add-services-or-components.adoc b/modules/odc-using-the-developer-catalog-to-add-services-or-components.adoc deleted file mode 100644 index 0a71f6aa11e9..000000000000 --- a/modules/odc-using-the-developer-catalog-to-add-services-or-components.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc - -[id="odc-using-the-developer-catalog-to-add-services-or-components_{context}"] -= Using the Developer Catalog to add services or components to your application - -You use the Developer Catalog to deploy applications and services based on Operator backed services such as Databases, Builder Images, and Helm Charts. The Developer Catalog contains a collection of application components, services, event sources, or source-to-image builders that you can add to your project. Cluster administrators can customize the content made available in the catalog. - -.Procedure - -. In the *Developer* perspective, navigate to the *+Add* -> *From Catalog* to view all the available services in the *Developer Catalog*. -. Under *All Items*, select the kind of service or the component you need to add to your project. For this example, select *Databases* to list all the database services and then click *MariaDB* to see the details for the service. -+ -.Developer Catalog -image::odc_devcatalog_mariadb.png[] -+ -. Click *Instantiate Template* to see an automatically populated template with details for the *MariaDB* service, and then click *Create* to create and view the MariaDB service in the *Topology* view. -+ -.MariaDB in Topology -image::odc_devcatalog_toplogy.png[] -+ diff --git a/modules/odc-using-web-terminal.adoc b/modules/odc-using-web-terminal.adoc deleted file mode 100644 index 14cab448fc71..000000000000 --- a/modules/odc-using-web-terminal.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// web_console/odc-about-web-terminal.adoc - -[id="odc-using-web-terminal_{context}"] -= Using the web terminal - -After the Web Terminal Operator is installed, you can use the web terminal as follows: - -. To launch the web terminal, click the command line terminal icon (image:odc-wto-icon.png[title="wto icon"]) on the upper right of the console. A web terminal instance is displayed in the *Command line terminal* pane. This instance is automatically logged in with your credentials. -. Select the project where the `DevWorkspace` CR must be created from the *Project* drop-down list. By default, the current project is selected. -+ -[NOTE] -==== -* The `DevWorkspace` CR is created only if it does not already exist. -* The `openshift-terminal` project is the default project used for cluster administrators. They do not have the option to choose another project. -==== -+ -. Click *Start* to initialize the web terminal using the selected project. - -After the web terminal is initialized, you can use the preinstalled CLI tools like `oc`, `kubectl`, `odo`, `kn`, `tkn`, `helm`, `kubens`, and `kubectx` in the web terminal. diff --git a/modules/odc-viewing-application-topology.adoc b/modules/odc-viewing-application-topology.adoc deleted file mode 100644 index a310f37813e5..000000000000 --- a/modules/odc-viewing-application-topology.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc - -[id="odc-viewing-application-topology_{context}"] -= Viewing the topology of your application - -You can navigate to the *Topology* view using the left navigation panel in the *Developer* perspective. After you deploy an application, you are directed automatically to the *Graph view* where you can see the status of the application pods, quickly access the application on a public URL, access the source code to modify it, and see the status of your last build. You can zoom in and out to see more details for a particular application. - -The *Topology* view also provides you the option to monitor your applications using the *List* view. Use the *List view* icon (image:odc_list_view_icon.png[title="List view icon"]) to see a list of all your applications and use the *Graph view* icon (image:odc_topology_view_icon.png[title="Topology view icon"]) to switch back to the graph view. - -You can customize the views as required using the following: - -* Use the *Find by name* field to find the required components. Search results may appear outside of the visible area; click *Fit to Screen* from the lower-left toolbar to resize the *Topology* view to show all components. -* Use the *Display Options* drop-down list to configure the *Topology* view of the various application groupings. The options are available depending on the types of components deployed in the project: - -** *Mode* (*Connectivity* or *Consumption*) -*** Connectivity: Select to show all the connections between the different nodes in the topology. -*** Consumption: Select to show the resource consumption for all nodes in the topology. -** *Expand* group -*** Virtual Machines: Toggle to show or hide the virtual machines. -*** Application Groupings: Clear to condense the application groups into cards with an overview of an application group and alerts associated with it. -*** Helm Releases: Clear to condense the components deployed as Helm Release into cards with an overview of a given release. -*** Knative Services: Clear to condense the Knative Service components into cards with an overview of a given component. -*** Operator Groupings: Clear to condense the components deployed with an Operator into cards with an overview of the given group. -** *Show* elements based on *Pod Count* or *Labels* -*** Pod Count: Select to show the number of pods of a component in the component icon. -*** Labels: Toggle to show or hide the component labels. diff --git a/modules/olm-about-opm.adoc b/modules/olm-about-opm.adoc deleted file mode 100644 index 3acbbebf0d2d..000000000000 --- a/modules/olm-about-opm.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-packaging-formats.adoc -// * cli_reference/opm-cli.adoc - -[id="olm-about-opm_{context}"] -= About opm - -The `opm` CLI tool is provided by the Operator Framework for use with the Operator Bundle Format. This tool allows you to create and maintain catalogs of Operators from a list of bundles, called an _index_, that are similar to software repositories. The result is a container image, called an _index image_, which can be stored in a container registry and then installed on a cluster. - -An index contains a database of pointers to Operator manifest content that can be queried through an included API that is served when the container image is run. On {product-title}, Operator Lifecycle Manager (OLM) can use the index image as a catalog by referencing it in a `CatalogSource` object, which polls the image at regular intervals to enable frequent updates to installed Operators on the cluster. diff --git a/modules/olm-accessing-images-private-registries.adoc b/modules/olm-accessing-images-private-registries.adoc deleted file mode 100644 index b65305c6a6e4..000000000000 --- a/modules/olm-accessing-images-private-registries.adoc +++ /dev/null @@ -1,203 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/managing-custom-catalogs.adoc - -[id="olm-accessing-images-private-registries_{context}"] -= Accessing images for Operators from private registries - -If certain images relevant to Operators managed by Operator Lifecycle Manager (OLM) are hosted in an authenticated container image registry, also known as a private registry, OLM and OperatorHub are unable to pull the images by default. To enable access, you can create a pull secret that contains the authentication credentials for the registry. By referencing one or more pull secrets in a catalog source, OLM can handle placing the secrets in the Operator and catalog namespace to allow installation. - -Other images required by an Operator or its Operands might require access to private registries as well. OLM does not handle placing the secrets in target tenant namespaces for this scenario, but authentication credentials can be added to the global cluster pull secret or individual namespace service accounts to enable the required access. - -The following types of images should be considered when determining whether Operators managed by OLM have appropriate pull access: - -Index or catalog images:: A `CatalogSource` object can reference an index image or a catalog image, which are catalog sources packaged as container images hosted in images registries. Index images use the Bundle Format and reference bundle images, while catalog images use the Package Manifest Format. If an index or catalog image is hosted in a private registry, a secret can be used to enable pull access. - -Bundle images:: Operator bundle images are metadata and manifests packaged as container images that represent a unique version of an Operator. If any bundle images referenced in a catalog source are hosted in one or more private registries, a secret can be used to enable pull access. - -Operator and Operand images:: If an Operator installed from a catalog source uses a private image, either for the Operator image itself or one of the Operand images it watches, the Operator will fail to install because the deployment will not have access to the required registry authentication. Referencing secrets in a catalog source does not enable OLM to place the secrets in target tenant namespaces in which Operands are installed. -+ -Instead, the authentication details can be added to the global cluster pull secret in the `openshift-config` namespace, which provides access to all namespaces on the cluster. Alternatively, if providing access to the entire cluster is not permissible, the pull secret can be added to the `default` service accounts of the target tenant namespaces. - -.Prerequisites - -* At least one of the following hosted in a private registry: -** An index image or catalog image. -** An Operator bundle image. -** An Operator or Operand image. - -.Procedure - -. Create a secret for each required private registry. - -.. Log in to the private registry to create or update your registry credentials file: -+ -[source,terminal] ----- -$ podman login <registry>:<port> ----- -+ -[NOTE] -==== -The file path of your registry credentials can be different depending on the container tool used to log in to the registry. For the `podman` CLI, the default location is `${XDG_RUNTIME_DIR}/containers/auth.json`. For the `docker` CLI, the default location is `/root/.docker/config.json`. -==== - -.. It is recommended to include credentials for only one registry per secret, and manage credentials for multiple registries in separate secrets. Multiple secrets can be included in a `CatalogSource` object in later steps, and {product-title} will merge the secrets into a single virtual credentials file for use during an image pull. -+ -A registry credentials file can, by default, store details for more than one registry. Verify the current contents of your file. For example: -+ -.File storing credentials for two registries -[source,json] ----- -{ - "auths": { - "registry.redhat.io": { - "auth": "FrNHNydQXdzclNqdg==" - }, - "quay.io": { - "auth": "Xd2lhdsbnRib21iMQ==" - } - } -} ----- -+ -Because this file is used to create secrets in later steps, ensure that you are storing details for only one registry per file. This can be accomplished by using either of the following methods: -+ --- -* Use the `podman logout <registry>` command to remove credentials for additional registries until only the one registry you want remains. -* Edit your registry credentials file and separate the registry details to be stored in multiple files. For example: -+ -.File storing credentials for one registry -[source,json] ----- -{ - "auths": { - "registry.redhat.io": { - "auth": "FrNHNydQXdzclNqdg==" - } - } -} ----- -+ -.File storing credentials for another registry -[source,json] ----- -{ - "auths": { - "quay.io": { - "auth": "Xd2lhdsbnRib21iMQ==" - } - } -} ----- --- - -.. Create a secret in the `openshift-marketplace` namespace that contains the authentication credentials for a private registry: -+ -[source,terminal] ----- -$ oc create secret generic <secret_name> \ - -n openshift-marketplace \ - --from-file=.dockerconfigjson=<path/to/registry/credentials> \ - --type=kubernetes.io/dockerconfigjson ----- -+ -Repeat this step to create additional secrets for any other required private registries, updating the `--from-file` flag to specify another registry credentials file path. - -. Create or update an existing `CatalogSource` object to reference one or more secrets: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: my-operator-catalog - namespace: openshift-marketplace -spec: - sourceType: grpc - secrets: <1> - - "<secret_name_1>" - - "<secret_name_2>" - image: <registry>:<port>/<namespace>/<image>:<tag> - displayName: My Operator Catalog - publisher: <publisher_name> - updateStrategy: - registryPoll: - interval: 30m ----- -<1> Add a `spec.secrets` section and specify any required secrets. - -. If any Operator or Operand images that are referenced by a subscribed Operator require access to a private registry, you can either provide access to all namespaces in the cluster, or individual target tenant namespaces. - -* To provide access to all namespaces in the cluster, add authentication details to the global cluster pull secret in the `openshift-config` namespace. -+ -[WARNING] -==== -Cluster resources must adjust to the new global pull secret, which can temporarily limit the usability of the cluster. -==== - -.. Extract the `.dockerconfigjson` file from the global pull secret: -+ -[source,terminal] ----- -$ oc extract secret/pull-secret -n openshift-config --confirm ----- - -.. Update the `.dockerconfigjson` file with your authentication credentials for the required private registry or registries and save it as a new file: -+ -[source,terminal] ----- -$ cat .dockerconfigjson | \ - jq --compact-output '.auths["<registry>:<port>/<namespace>/"] |= . + {"auth":"<token>"}' \//<1> - > new_dockerconfigjson ----- -<1> Replace `<registry>:<port>/<namespace>` with the private registry details and `<token>` with your authentication credentials. - -.. Update the global pull secret with the new file: -+ -[source,terminal] ----- -$ oc set data secret/pull-secret -n openshift-config \ - --from-file=.dockerconfigjson=new_dockerconfigjson ----- - -* To update an individual namespace, add a pull secret to the service account for the Operator that requires access in the target tenant namespace. - -.. Recreate the secret that you created for the `openshift-marketplace` in the tenant namespace: -+ -[source,terminal] ----- -$ oc create secret generic <secret_name> \ - -n <tenant_namespace> \ - --from-file=.dockerconfigjson=<path/to/registry/credentials> \ - --type=kubernetes.io/dockerconfigjson ----- - -.. Verify the name of the service account for the Operator by searching the tenant namespace: -+ -[source,terminal] ----- -$ oc get sa -n <tenant_namespace> <1> ----- -<1> If the Operator was installed in an individual namespace, search that namespace. If the Operator was installed for all namespaces, search the `openshift-operators` namespace. -+ -.Example output -[source,terminal] ----- -NAME SECRETS AGE -builder 2 6m1s -default 2 6m1s -deployer 2 6m1s -etcd-operator 2 5m18s <1> ----- -<1> Service account for an installed etcd Operator. - -.. Link the secret to the service account for the Operator: -+ -[source,terminal] ----- -$ oc secrets link <operator_sa> \ - -n <tenant_namespace> \ - <secret_name> \ - --for=pull ----- diff --git a/modules/olm-adding-new-crd-version.adoc b/modules/olm-adding-new-crd-version.adoc deleted file mode 100644 index b9cce86e1ff4..000000000000 --- a/modules/olm-adding-new-crd-version.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="olm-dependency-resolution-adding-new-crd-version_{context}"] -= Adding a new CRD version - -.Procedure - -To add a new version of a CRD to your Operator: - -. Add a new entry in the CRD resource under the `versions` section of your CSV. -+ -For example, if the current CRD has a version `v1alpha1` and you want to add a new version `v1beta1` and mark it as the new storage version, add a new entry for `v1beta1`: -+ -[source,yaml] ----- -versions: - - name: v1alpha1 - served: true - storage: false - - name: v1beta1 <1> - served: true - storage: true ----- -<1> New entry. - -. Ensure the referencing version of the CRD in the `owned` section of your CSV is updated if the CSV intends to use the new version: -+ -[source,yaml] ----- -customresourcedefinitions: - owned: - - name: cluster.example.com - version: v1beta1 <1> - kind: cluster - displayName: Cluster ----- -<1> Update the `version`. - -. Push the updated CRD and CSV to your bundle. diff --git a/modules/olm-approving-pending-upgrade.adoc b/modules/olm-approving-pending-upgrade.adoc deleted file mode 100644 index 26f6d70e6d76..000000000000 --- a/modules/olm-approving-pending-upgrade.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-upgrading-operators.adoc - -[id="olm-approving-pending-upgrade_{context}"] -= Manually approving a pending Operator upgrade - -If an installed Operator has the approval strategy in its subscription set to *Manual*, when new updates are released in its current update channel, the update must be manually approved before installation can begin. - -.Prerequisites - -* An Operator previously installed using Operator Lifecycle Manager (OLM). - -.Procedure - -. In the *Administrator* perspective of the {product-title} web console, navigate to *Operators -> Installed Operators*. - -. Operators that have a pending upgrade display a status with *Upgrade available*. Click the name of the Operator you want to upgrade. - -. Click the *Subscription* tab. Any upgrades requiring approval are displayed next to *Upgrade Status*. For example, it might display *1 requires approval*. - -. Click *1 requires approval*, then click *Preview Install Plan*. - -. Review the resources that are listed as available for upgrade. When satisfied, click *Approve*. - -. Navigate back to the *Operators -> Installed Operators* page to monitor the progress of the upgrade. When complete, the status changes to *Succeeded* and *Up to date*. diff --git a/modules/olm-arch-catalog-operator.adoc b/modules/olm-arch-catalog-operator.adoc deleted file mode 100644 index aa47be10dafd..000000000000 --- a/modules/olm-arch-catalog-operator.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-arch.adoc -// * operators/operator-reference.adoc - -[id="olm-arch-catalog-operator_{context}"] -= Catalog Operator - -The Catalog Operator is responsible for resolving and installing cluster service versions (CSVs) and the required resources they specify. It is also responsible for watching catalog sources for updates to packages in channels and upgrading them, automatically if desired, to the latest available versions. - -To track a package in a channel, you can create a `Subscription` object configuring the desired package, channel, and the `CatalogSource` object you want to use for pulling updates. When updates are found, an appropriate `InstallPlan` object is written into the namespace on behalf of the user. - -The Catalog Operator uses the following workflow: - -. Connect to each catalog source in the cluster. -. Watch for unresolved install plans created by a user, and if found: -.. Find the CSV matching the name requested and add the CSV as a resolved resource. -.. For each managed or required CRD, add the CRD as a resolved resource. -.. For each required CRD, find the CSV that manages it. -. Watch for resolved install plans and create all of the discovered resources for it, if approved by a user or automatically. -. Watch for catalog sources and subscriptions and create install plans based on them. diff --git a/modules/olm-arch-catalog-registry.adoc b/modules/olm-arch-catalog-registry.adoc deleted file mode 100644 index 1b3d72f338d7..000000000000 --- a/modules/olm-arch-catalog-registry.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-arch.adoc -// * operators/operator-reference.adoc - -[id="olm-arch-catalog-registry_{context}"] -= Catalog Registry - -The Catalog Registry stores CSVs and CRDs for creation in a cluster and stores metadata about packages and channels. - -A _package manifest_ is an entry in the Catalog Registry that associates a package identity with sets of CSVs. Within a package, channels point to a particular CSV. Because CSVs explicitly reference the CSV that they replace, a package manifest provides the Catalog Operator with all of the information that is required to update a CSV to the latest version in a channel, stepping through each intermediate version. diff --git a/modules/olm-arch-olm-operator.adoc b/modules/olm-arch-olm-operator.adoc deleted file mode 100644 index a0c1520ac49c..000000000000 --- a/modules/olm-arch-olm-operator.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-arch.adoc -// * operators/operator-reference.adoc - -[id="olm-arch-olm-operator_{context}"] -= OLM Operator - -The OLM Operator is responsible for deploying applications defined by CSV resources after the required resources specified in the CSV are present in the cluster. - -The OLM Operator is not concerned with the creation of the required resources; you can choose to manually create these resources using the CLI or using the Catalog Operator. This separation of concern allows users incremental buy-in in terms of how much of the OLM framework they choose to leverage for their application. - -The OLM Operator uses the following workflow: - -. Watch for cluster service versions (CSVs) in a namespace and check that requirements are met. -. If requirements are met, run the install strategy for the CSV. -+ -[NOTE] -==== -A CSV must be an active member of an Operator group for the install strategy to run. -==== diff --git a/modules/olm-arch-os-support.adoc b/modules/olm-arch-os-support.adoc deleted file mode 100644 index 3da8f6bbe805..000000000000 --- a/modules/olm-arch-os-support.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="olm-arch-os-support_{context}"] -= Architecture and operating system support for Operators - -The following strings are supported in Operator Lifecycle Manager (OLM) on {product-title} when labeling or filtering Operators that support multiple architectures and operating systems: - -.Architectures supported on {product-title} -[options="header"] -|=== -|Architecture |String - -|AMD64 -|`amd64` - -|64-bit PowerPC little-endian -|`ppc64le` - -|IBM Z -|`s390x` -|=== - -.Operating systems supported on {product-title} -[options="header"] -|=== -|Operating system |String - -|Linux -|`linux` - -|z/OS -|`zos` -|=== - -[NOTE] -==== -Different versions of {product-title} and other Kubernetes-based distributions -might support a different set of architectures and operating systems. -==== diff --git a/modules/olm-architecture.adoc b/modules/olm-architecture.adoc deleted file mode 100644 index 2deef19dfd7a..000000000000 --- a/modules/olm-architecture.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc -// * operators/operator-reference.adoc - -[id="olm-architecture_{context}"] -ifeval::["{context}" != "red-hat-operators"] -= Component responsibilities -endif::[] -ifeval::["{context}" == "red-hat-operators"] -= CRDs -endif::[] - -Operator Lifecycle Manager (OLM) is composed of two Operators: the OLM Operator and the Catalog Operator. - -Each of these Operators is responsible for managing the custom resource definitions (CRDs) that are the basis for the OLM framework: - -.CRDs managed by OLM and Catalog Operators -[cols="2a,1a,1a,8a",options="header"] -|=== -|Resource |Short name |Owner |Description - -|`ClusterServiceVersion` (CSV) -|`csv` -|OLM -|Application metadata: name, version, icon, required resources, installation, and so on. - -|`InstallPlan` -|`ip` -|Catalog -|Calculated list of resources to be created to automatically install or upgrade a CSV. - -|`CatalogSource` -|`catsrc` -|Catalog -|A repository of CSVs, CRDs, and packages that define an application. - -|`Subscription` -|`sub` -|Catalog -|Keeps CSVs up to date by tracking a channel in a package. - -|`OperatorGroup` -|`og` -|OLM -|Configures all Operators deployed in the same namespace as the `OperatorGroup` object to watch for their custom resource (CR) in a list of namespaces or cluster-wide. -|=== - -Each of these Operators is also responsible for creating the following resources: - -.Resources created by OLM and Catalog Operators -[options="header"] -|=== -|Resource |Owner - -|`Deployments` -.4+.^|OLM - -|`ServiceAccounts` -|`(Cluster)Roles` -|`(Cluster)RoleBindings` - -|`CustomResourceDefinitions` (CRDs) -.2+.^|Catalog -|`ClusterServiceVersions` -|=== diff --git a/modules/olm-building-operator-catalog-image.adoc b/modules/olm-building-operator-catalog-image.adoc deleted file mode 100644 index 49a1e4f3414a..000000000000 --- a/modules/olm-building-operator-catalog-image.adoc +++ /dev/null @@ -1,111 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc - -ifdef::openshift-origin[] -:registry-image: quay.io/openshift/origin-operator-registry:4.7.0 -endif::[] -ifndef::openshift-origin[] -:registry-image: registry.redhat.io/openshift4/ose-operator-registry:v4.7 -endif::[] - -[id="olm-building-operator-catalog-image_{context}"] -= Building a Package Manifest Format catalog image - -Cluster administrators can build a custom Operator catalog image based on the Package Manifest Format to be used by Operator Lifecycle Manager (OLM). The catalog image can be pushed to a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2]. For a cluster on a restricted network, this registry can be a registry that the cluster has network access to, such as a mirror registry created during a restricted network cluster installation. - -For this example, the procedure assumes use of a mirror registry that has access to both your network and the Internet. - -[NOTE] -==== -Only the Linux version of the `oc` client can be used for this procedure, because the Windows and macOS versions do not provide the `oc adm catalog build` command. -==== - -.Prerequisites - -* Workstation with unrestricted network access -* `oc` version 4.3.5+ Linux client -* `podman` version 1.9.3+ -* Access to mirror registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] -* If you are working with private registries, set the `REG_CREDS` environment variable to the file path of your registry credentials for use in later steps. For example, for the `podman` CLI: -+ -[source,terminal] ----- -$ REG_CREDS=${XDG_RUNTIME_DIR}/containers/auth.json ----- -* If you are working with private namespaces that your link:https://quay.io[quay.io] account has access to, you must set a Quay authentication token. Set the `AUTH_TOKEN` environment variable for use with the `--auth-token` flag by making a request against the login API using your link:https://quay.io[quay.io] credentials: -+ -[source,terminal] ----- -$ AUTH_TOKEN=$(curl -sH "Content-Type: application/json" \ - -XPOST https://quay.io/cnr/api/v1/users/login -d ' - { - "user": { - "username": "'"<quay_username>"'", - "password": "'"<quay_password>"'" - } - }' | jq -r '.token') ----- - -.Procedure - -. On the workstation with unrestricted network access, authenticate with the target mirror registry: -+ -[source,terminal] ----- -$ podman login <registry_host_name> ----- - -ifndef::openshift-origin[] -. Authenticate with `registry.redhat.io` so that the base image can be pulled -during the build: -+ -[source,terminal] ----- -$ podman login registry.redhat.io ----- -endif::[] - -. Build a catalog image based on the `redhat-operators` catalog from Quay.io, tagging and pushing it to your mirror registry: -+ -[source,terminal,subs="attributes+"] ----- -$ oc adm catalog build \ - --appregistry-org redhat-operators \//<1> - --from={registry-image} \//<2> - --filter-by-os="linux/amd64" \//<3> - --to=<registry_host_name>:<port>/olm/redhat-operators:v1 \//<4> - [-a ${REG_CREDS}] \//<5> - [--insecure] \//<6> - [--auth-token "${AUTH_TOKEN}"] <7> ----- -<1> Organization (namespace) to pull from an App Registry instance. -<2> Set `--from` to the Operator Registry base image using the tag that matches the target {product-title} cluster major and minor version. -<3> Set `--filter-by-os` to the operating system and architecture to use for the base image, which must match the target {product-title} cluster. Valid values are `linux/amd64`, `linux/ppc64le`, and `linux/s390x`. -<4> Name your catalog image and include a tag, for example, `v1`. -<5> Optional: If required, specify the location of your registry credentials file. -<6> Optional: If you do not want to configure trust for the target registry, add the `--insecure` flag. -<7> Optional: If other application registry catalogs are used that are not public, specify a Quay authentication token. -+ -.Example output -[source,terminal] ----- -INFO[0013] loading Bundles dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 -... -Pushed sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 to example_registry:5000/olm/redhat-operators:v1 ----- -+ -Sometimes invalid manifests are accidentally introduced catalogs provided by Red Hat; when this happens, you might see some errors: -+ -.Example output with errors -[source,terminal] ----- -... -INFO[0014] directory dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 file=4.2 load=package -W1114 19:42:37.876180 34665 builder.go:141] error building database: error loading package into db: fuse-camel-k-operator.v7.5.0 specifies replacement that couldn't be found -Uploading ... 244.9kB/s ----- -+ -These errors are usually non-fatal, and if the Operator package mentioned does not contain an Operator you plan to install or a dependency of one, then they can be ignored. - -:!registry-image: diff --git a/modules/olm-bundle-format-dependencies-file.adoc b/modules/olm-bundle-format-dependencies-file.adoc deleted file mode 100644 index 8a1fd8691610..000000000000 --- a/modules/olm-bundle-format-dependencies-file.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-packaging-format.adoc -// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc - -[id="olm-bundle-format-dependencies_{context}"] -= Dependencies file - -The dependencies of an Operator are listed in a `dependencies.yaml` file in the `metadata/` folder of a bundle. This file is optional and currently only used to specify explicit Operator-version dependencies. - -The dependency list contains a `type` field for each item to specify what kind of dependency this is. There are two supported types of Operator dependencies: - -* `olm.package`: This type indicates a dependency for a specific Operator version. The dependency information must include the package name and the version of the package in semver format. For example, you can specify an exact version such as `0.5.2` or a range of versions such as `>0.5.1`. -* `olm.gvk`: With a `gvk` type, the author can specify a dependency with group/version/kind (GVK) information, similar to existing CRD and API-based usage in a CSV. This is a path to enable Operator authors to consolidate all dependencies, API or explicit versions, to be in the same place. - -In the following example, dependencies are specified for a Prometheus Operator and etcd CRDs: - -.Example `dependencies.yaml` file -[source,yaml] ----- -dependencies: - - type: olm.package - value: - packageName: prometheus - version: ">0.27.0" - - type: olm.gvk - value: - group: etcd.database.coreos.com - kind: EtcdCluster - version: v1beta2 ----- diff --git a/modules/olm-bundle-format.adoc b/modules/olm-bundle-format.adoc deleted file mode 100644 index b88c2b8d6fb9..000000000000 --- a/modules/olm-bundle-format.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-packaging-format.adoc - -[id="olm-bundle-format_{context}"] -= Bundle Format - -The _Bundle Format_ for Operators is a new packaging format introduced by the Operator Framework. To improve scalability and to better enable upstream users hosting their own catalogs, the Bundle Format specification simplifies the distribution of Operator metadata. - -An Operator bundle represents a single version of an Operator. On-disk _bundle manifests_ are containerized and shipped as a _bundle image_, which is a non-runnable container image that stores the Kubernetes manifests and Operator metadata. Storage and distribution of the bundle image is then managed using existing container tools like `podman` and `docker` and container registries such as Quay. - -Operator metadata can include: - -* Information that identifies the Operator, for example its name and version. -* Additional information that drives the UI, for example its icon and some example custom resources (CRs). -* Required and provided APIs. -* Related images. - -When loading manifests into the Operator Registry database, the following requirements are validated: - -* The bundle must have at least one channel defined in the annotations. -* Every bundle has exactly one cluster service version (CSV). -* If a CSV owns a custom resource definition (CRD), that CRD must exist in the bundle. - -[id="olm-bundle-format-manifests_{context}"] -== Manifests - -Bundle manifests refer to a set of Kubernetes manifests that define the deployment and RBAC model of the Operator. - -A bundle includes one CSV per directory and typically the CRDs that define the owned APIs of the CSV in its `/manifests` directory. - -.Example Bundle Format layout -[source,terminal] ----- -etcd -├── manifests -│ ├── etcdcluster.crd.yaml -│ └── etcdoperator.clusterserviceversion.yaml -│ └── secret.yaml -│ └── configmap.yaml -└── metadata - └── annotations.yaml - └── dependencies.yaml ----- - -[discrete] -[id="olm-bundle-format-manifests-optional_{context}"] -=== Additionally supported objects - -The following object types can also be optionally included in the `/manifests` directory of a bundle: - -.Supported optional object types -* `Secret` -* `ConfigMap` -* `Service` -* `PodDisruptionBudget` -* `PriorityClass` -* `VerticalPodAutoScaler` - -When these optional objects are included in a bundle, Operator Lifecycle Manager (OLM) can create them from the bundle and manage their lifecycle along with the CSV: - -.Lifecycle for optional objects -* When the CSV is deleted, OLM deletes the optional object. -* When the CSV is upgraded: -** If the name of the optional object is the same, OLM updates it in place. -** If the name of the optional object has changed between versions, OLM deletes and recreates it. - -[id="olm-bundle-format-annotations_{context}"] -== Annotations - -A bundle also includes an `annotations.yaml` file in its `/metadata` directory. This file defines higher level aggregate data that helps describe the format and package information about how the bundle should be added into an index of bundles: - -.Example `annotations.yaml` -[source,yaml] ----- -annotations: - operators.operatorframework.io.bundle.mediatype.v1: "registry+v1" <1> - operators.operatorframework.io.bundle.manifests.v1: "manifests/" <2> - operators.operatorframework.io.bundle.metadata.v1: "metadata/" <3> - operators.operatorframework.io.bundle.package.v1: "test-operator" <4> - operators.operatorframework.io.bundle.channels.v1: "beta,stable" <5> - operators.operatorframework.io.bundle.channel.default.v1: "stable" <6> ----- -<1> The media type or format of the Operator bundle. The `registry+v1` format means it contains a CSV and its associated Kubernetes objects. -<2> The path in the image to the directory that contains the Operator manifests. This label is reserved for future use and currently defaults to `manifests/`. The value `manifests.v1` implies that the bundle contains Operator manifests. -<3> The path in the image to the directory that contains metadata files about the bundle. This label is reserved for future use and currently defaults to `metadata/`. The value `metadata.v1` implies that this bundle has Operator metadata. -<4> The package name of the bundle. -<5> The list of channels the bundle is subscribing to when added into an Operator Registry. -<6> The default channel an Operator should be subscribed to when installed from a registry. - -[NOTE] -==== -In case of a mismatch, the `annotations.yaml` file is authoritative because the on-cluster Operator Registry that relies on these annotations only has access to this file. -==== diff --git a/modules/olm-catalogsource.adoc b/modules/olm-catalogsource.adoc deleted file mode 100644 index 586b8454cdcd..000000000000 --- a/modules/olm-catalogsource.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc - -[id="olm-catalogsource_{context}"] -= Catalog source - -A catalog source represents a store of metadata that OLM can query to discover and install Operators and their dependencies. The spec of a `CatalogSource` object indicates how to construct a pod or how to communicate with a service that serves the Operator Registry gRPC API. - -There are three primary `sourceTypes` for a `CatalogSource` object: - -* `grpc` with an `image` reference: OLM pulls the image and runs the pod, which is expected to serve a compliant API. -* `grpc` with an `address` field: OLM attempts to contact the gRPC API at the given address. This should not be used in most cases. -* `internal` or `configmap`: OLM parses the ConfigMap data and runs a pod that can serve the gRPC API over it. - -The following example defines a catalog source for OperatorHub.io content: - -.Example `CatalogSource` object -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: operatorhubio-catalog - namespace: olm -spec: - sourceType: grpc - image: quay.io/operatorhubio/catalog:latest <1> - priority: -400 - displayName: Community Operators - publisher: OperatorHub.io - updateStrategy: - registryPoll: <2> - interval: 30m ----- -<1> Specify catalog image. -<2> Automatically check for new versions at a given interval to keep up to date. - -The `name` of the `CatalogSource` object is used as input to a subscription, which instructs OLM where to look to find a requested Operator: - -.Example `Subscription` object referencing a catalog source -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: my-operator - namespace: olm -spec: - channel: stable - name: my-operator - source: operatorhubio-catalog ----- diff --git a/modules/olm-changing-update-channel.adoc b/modules/olm-changing-update-channel.adoc deleted file mode 100644 index f85724480b9c..000000000000 --- a/modules/olm-changing-update-channel.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-upgrading-operators.adoc - -[id="olm-changing-update-channel_{context}"] -= Changing the update channel for an Operator - -The subscription of an installed Operator specifies an update channel, which is used to track and receive updates for the Operator. To upgrade the Operator to start tracking and receiving updates from a newer channel, you can change the update channel in the subscription. - -The names of update channels in a subscription can differ between Operators, but the naming scheme should follow a common convention within a given Operator. For example, channel names might follow a minor release update stream for the application provided by the Operator (`1.2`, `1.3`) or a release frequency (`stable`, `fast`). - -[NOTE] -==== -Installed Operators cannot change to a channel that is older than the current channel. -==== - -If the approval strategy in the subscription is set to *Automatic*, the upgrade process initiates as soon as a new Operator version is available in the selected channel. If the approval strategy is set to *Manual*, you must manually approve pending upgrades. - -.Prerequisites - -* An Operator previously installed using Operator Lifecycle Manager (OLM). - -.Procedure - -. In the *Administrator* perspective of the {product-title} web console, navigate to *Operators -> Installed Operators*. - -. Click the name of the Operator you want to change the update channel for. - -. Click the *Subscription* tab. - -. Click the name of the update channel under *Channel*. - -. Click the newer update channel that you want to change to, then click *Save*. - -. For subscriptions with an *Automatic* approval strategy, the upgrade begins automatically. Navigate back to the *Operators -> Installed Operators* page to monitor the progress of the upgrade. When complete, the status changes to *Succeeded* and *Up to date*. -+ -For subscriptions with a *Manual* approval strategy, you can manually approve the upgrade from the *Subscription* tab. diff --git a/modules/olm-crds.adoc b/modules/olm-crds.adoc deleted file mode 100644 index 664e2c6ad39a..000000000000 --- a/modules/olm-crds.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc - -[id="olm-resources_{context}"] -= OLM resources - -The following custom resource definitions (CRDs) are defined and managed by Operator Lifecycle Manager (OLM): - -.CRDs managed by OLM and Catalog Operators -[cols="2a,2a,8a",options="header"] -|=== -|Resource |Short name |Description - -|`ClusterServiceVersion` (CSV) -|`csv` -|Application metadata. For example: name, version, icon, required resources. - -|`CatalogSource` -|`catsrc` -|A repository of CSVs, CRDs, and packages that define an application. - -|`Subscription` -|`sub` -|Keeps CSVs up to date by tracking a channel in a package. - -|`InstallPlan` -|`ip` -|Calculated list of resources to be created to automatically install or upgrade a CSV. - -|`OperatorGroup` -|`og` -|Configures all Operators deployed in the same namespace as the `OperatorGroup` object to watch for their custom resource (CR) in a list of namespaces or cluster-wide. - -|`OperatorConditions` -|- -|Creates a communication channel between OLM and an Operator it manages. Operators can write to the `Status.Conditions` array to communicate complex states to OLM. -|=== diff --git a/modules/olm-creating-catalog-from-index.adoc b/modules/olm-creating-catalog-from-index.adoc deleted file mode 100644 index 51d50fc02b1e..000000000000 --- a/modules/olm-creating-catalog-from-index.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-restricted-networks.adoc -// * operators/admin/managing-custom-catalogs.adoc -// * migration/migrating_3_4/deploying-cam-3-4.adoc -// * migration/migrating_4_1_4/deploying-cam-4-1-4.adoc -// * migration/migrating_4_2_4/deploying-cam-4-2-4.adoc - -ifdef::openshift-origin[] -:index-image: catalog -:tag: latest -endif::[] -ifndef::openshift-origin[] -:index-image: redhat-operator-index -:tag: v{product-version} -endif::[] -ifeval::["{context}" == "olm-restricted-networks"] -:olm-restricted-networks: -endif::[] - -[id="olm-creating-catalog-from-index_{context}"] -= Creating a catalog from an index image - -You can create an Operator catalog from an index image and apply it to an {product-title} cluster for use with Operator Lifecycle Manager (OLM). - -.Prerequisites - -* An index image built and pushed to a registry. - -.Procedure - -. Create a `CatalogSource` object that references your index image. -ifdef::olm-restricted-networks[] -If you used the `oc adm catalog mirror` command to mirror your catalog to a target registry, you can use the generated `catalogSource.yaml` file as a starting point. -endif::[] - -.. Modify the following to your specifications and save it as a `catalogSource.yaml` file: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: -ifdef::olm-restricted-networks[] - name: my-operator-catalog <.> -endif::[] -ifndef::olm-restricted-networks[] - name: my-operator-catalog -endif::[] - namespace: openshift-marketplace -spec: - sourceType: grpc - image: <registry>:<port>/<namespace>/{index-image}:{tag} <.> - displayName: My Operator Catalog - publisher: <publisher_name> <.> - updateStrategy: - registryPoll: <.> - interval: 30m ----- -ifdef::olm-restricted-networks[] -<.> If you mirrored content to local files before uploading to a registry, remove any backslash (`/`) characters from the `metadata.name` field to avoid an "invalid resource name" error when you create the object. -endif::[] -<.> Specify your index image. -<.> Specify your name or an organization name publishing the catalog. -<.> Catalog sources can automatically check for new versions to keep up to date. - -.. Use the file to create the `CatalogSource` object: -+ -[source,terminal] ----- -$ oc apply -f catalogSource.yaml ----- - -. Verify the following resources are created successfully. - -.. Check the pods: -+ -[source,terminal] ----- -$ oc get pods -n openshift-marketplace ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -my-operator-catalog-6njx6 1/1 Running 0 28s -marketplace-operator-d9f549946-96sgr 1/1 Running 0 26h ----- - -.. Check the catalog source: -+ -[source,terminal] ----- -$ oc get catalogsource -n openshift-marketplace ----- -+ -.Example output -[source,terminal] ----- -NAME DISPLAY TYPE PUBLISHER AGE -my-operator-catalog My Operator Catalog grpc 5s ----- - -.. Check the package manifest: -+ -[source,terminal] ----- -$ oc get packagemanifest -n openshift-marketplace ----- -+ -.Example output -[source,terminal] ----- -NAME CATALOG AGE -jaeger-product My Operator Catalog 93s ----- - -You can now install the Operators from the *OperatorHub* page on your {product-title} web console. - -:!index-image: -:!tag: -ifeval::["{context}" == "olm-restricted-networks"] -:!olm-restricted-networks: -endif::[] diff --git a/modules/olm-creating-etcd-cluster-from-operator.adoc b/modules/olm-creating-etcd-cluster-from-operator.adoc deleted file mode 100644 index f575f6e28df2..000000000000 --- a/modules/olm-creating-etcd-cluster-from-operator.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * /operators/user/olm-creating-apps-from-installed-operators.adoc - -[id="olm-creating-etcd-cluster-from-operator_{context}"] -= Creating an etcd cluster using an Operator - -This procedure walks through creating a new etcd cluster using the etcd Operator, managed by Operator Lifecycle Manager (OLM). - -.Prerequisites - -* Access to an {product-title} {product-version} cluster. -* The etcd Operator already installed cluster-wide by an administrator. - -.Procedure - -. Create a new project in the {product-title} web console for this procedure. This example uses a project called `my-etcd`. - -. Navigate to the *Operators -> Installed Operators* page. The Operators that have been installed to the cluster by the cluster administrator and are available for use are shown here as a list of cluster service versions (CSVs). CSVs are used to launch and manage the software provided by the Operator. -+ -[TIP] -==== -You can get this list from the CLI using: - -[source,terminal] ----- -$ oc get csv ----- -==== - -. On the *Installed Operators* page, click the etcd Operator to view more details and available actions. -+ -As shown under *Provided APIs*, this Operator makes available three new resource types, including one for an *etcd Cluster* (the `EtcdCluster` resource). These objects work similar to the built-in native Kubernetes ones, such as `Deployment` or `ReplicaSet`, but contain logic specific to managing etcd. - -. Create a new etcd cluster: - -.. In the *etcd Cluster* API box, click *Create instance*. - -.. The next screen allows you to make any modifications to the minimal starting template of an `EtcdCluster` object, such as the size of the cluster. For now, click *Create* to finalize. This triggers the Operator to start up the pods, services, and other components of the new etcd cluster. - -. Click on the *example* etcd cluster, then click the *Resources* tab to see that your project now contains a number of resources created and configured automatically by the Operator. -+ -Verify that a Kubernetes service has been created that allows you to access the database from other pods in your project. - -. All users with the `edit` role in a given project can create, manage, and delete application instances (an etcd cluster, in this example) managed by Operators that have already been created in the project, in a self-service manner, just like a cloud service. If you want to enable additional users with this ability, project administrators can add the role using the following command: -+ -[source,terminal] ----- -$ oc policy add-role-to-user edit <user> -n <target_project> ----- - -You now have an etcd cluster that will react to failures and rebalance data as pods become unhealthy or are migrated between nodes in the cluster. Most importantly, cluster administrators or developers with proper access can now easily use the database with their applications. diff --git a/modules/olm-creating-index-image.adoc b/modules/olm-creating-index-image.adoc deleted file mode 100644 index fcad09bf2526..000000000000 --- a/modules/olm-creating-index-image.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc - -[id="olm-creating-index-image_{context}"] -= Creating an index image - -You can create an index image using the `opm` CLI. - -.Prerequisites - -* `opm` version 1.12.3+ -* `podman` version 1.9.3+ -* A bundle image built and pushed to a registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] - -.Procedure - -. Start a new index: -+ -[source,terminal] ----- -$ opm index add \ - --bundles <registry>/<namespace>/<bundle_image_name>:<tag> \//<1> - --tag <registry>/<namespace>/<index_image_name>:<tag> \//<2> - [--binary-image <registry_base_image>] <3> ----- -<1> Comma-separated list of bundle images to add to the index. -<2> The image tag that you want the index image to have. -<3> Optional: An alternative registry base image to use for serving the catalog. - -. Push the index image to a registry. - -.. If required, authenticate with your target registry: -+ -[source,terminal] ----- -$ podman login <registry> ----- - -.. Push the index image: -+ -[source,terminal] ----- -$ podman push <registry>/<namespace>/test-catalog:latest ----- diff --git a/modules/olm-csv.adoc b/modules/olm-csv.adoc deleted file mode 100644 index 9297c436acb7..000000000000 --- a/modules/olm-csv.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc - -[id="olm-csv_{context}"] -= Cluster service version - -A _cluster service version_ (CSV) represents a specific version of a running Operator on an {product-title} cluster. It is a YAML manifest created from Operator metadata that assists Operator Lifecycle Manager (OLM) in running the Operator in the cluster. - -OLM requires this metadata about an Operator to ensure that it can be kept running safely on a cluster, and to provide information about how updates should be applied as new versions of the Operator are published. This is similar to packaging software for a traditional operating system; think of the packaging step for OLM as the stage at which you make your `rpm`, `dep`, or `apk` bundle. - -A CSV includes the metadata that accompanies an Operator container image, used to populate user interfaces with information such as its name, version, description, labels, repository link, and logo. - -A CSV is also a source of technical information required to run the Operator, such as which custom resources (CRs) it manages or depends on, RBAC rules, cluster requirements, and install strategies. This information tells OLM how to create required resources and set up the Operator as a deployment. - -//// -Metadata:: -* Application metadata: -** Name, description, version (semver compliant), links, labels, icon, etc. - -Install strategy:: -* Type: Deployment -** Set of service accounts and required permissions -** Set of Deployments. - -Custom Resource Definitions (CRDs):: -* Type -* Owned: Managed by this service -* Required: Must exist in the cluster for this service to run -* Resources: A list of resources that the Operator interacts with -* Descriptors: Annotate CRD spec and status fields to provide semantic information -//// diff --git a/modules/olm-defining-csv-webhooks.adoc b/modules/olm-defining-csv-webhooks.adoc deleted file mode 100644 index 6efc7e36949b..000000000000 --- a/modules/olm-defining-csv-webhooks.adoc +++ /dev/null @@ -1,110 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="olm-defining-csv-webhook_{context}"] -= Defining webhooks - -Webhooks allow Operator authors to intercept, modify, and accept or reject resources before they are saved to the object store and handled by the Operator controller. Operator Lifecycle Manager (OLM) can manage the lifecycle of these webhooks when they are shipped alongside your Operator. - -The cluster service version (CSV) resource of an Operator can include a `webhookdefinitions` section to define the following types of webhooks: - -* Admission webhooks (validating and mutating) -* Conversion webhooks - -.Procedure - -* Add a `webhookdefinitions` section to the `spec` section of the CSV of your Operator and include any webhook definitions using a `type` of `ValidatingAdmissionWebhook`, `MutatingAdmissionWebhook`, or `ConversionWebhook`. The following example contains all three types of webhooks: -+ -.CSV containing webhooks -[source,yaml] ----- - apiVersion: operators.coreos.com/v1alpha1 - kind: ClusterServiceVersion - metadata: - name: webhook-operator.v0.0.1 - spec: - customresourcedefinitions: - owned: - - kind: WebhookTest - name: webhooktests.webhook.operators.coreos.io <1> - version: v1 - install: - spec: - deployments: - - name: webhook-operator-webhook - ... - ... - ... - strategy: deployment - installModes: - - supported: false - type: OwnNamespace - - supported: false - type: SingleNamespace - - supported: false - type: MultiNamespace - - supported: true - type: AllNamespaces - webhookdefinitions: - - type: ValidatingAdmissionWebhook <2> - admissionReviewVersions: - - v1beta1 - - v1 - containerPort: 443 - targetPort: 4343 - deploymentName: webhook-operator-webhook - failurePolicy: Fail - generateName: vwebhooktest.kb.io - rules: - - apiGroups: - - webhook.operators.coreos.io - apiVersions: - - v1 - operations: - - CREATE - - UPDATE - resources: - - webhooktests - sideEffects: None - webhookPath: /validate-webhook-operators-coreos-io-v1-webhooktest - - type: MutatingAdmissionWebhook <3> - admissionReviewVersions: - - v1beta1 - - v1 - containerPort: 443 - targetPort: 4343 - deploymentName: webhook-operator-webhook - failurePolicy: Fail - generateName: mwebhooktest.kb.io - rules: - - apiGroups: - - webhook.operators.coreos.io - apiVersions: - - v1 - operations: - - CREATE - - UPDATE - resources: - - webhooktests - sideEffects: None - webhookPath: /mutate-webhook-operators-coreos-io-v1-webhooktest - - type: ConversionWebhook <4> - admissionReviewVersions: - - v1beta1 - - v1 - containerPort: 443 - targetPort: 4343 - deploymentName: webhook-operator-webhook - generateName: cwebhooktest.kb.io - sideEffects: None - webhookPath: /convert - conversionCRDs: - - webhooktests.webhook.operators.coreos.io <5> -... ----- -<1> The CRDs targeted by the conversion webhook must exist here. -<2> A validating admission webhook. -<3> A mutating admission webhook. -<4> A conversion webhook. -<5> The `spec.PreserveUnknownFields` property of each CRD must be set to `false` or `nil`. diff --git a/modules/olm-deleting-operators-from-a-cluster-using-cli.adoc b/modules/olm-deleting-operators-from-a-cluster-using-cli.adoc deleted file mode 100644 index 755a3ae1f00a..000000000000 --- a/modules/olm-deleting-operators-from-a-cluster-using-cli.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-deleting-operators-from-a-cluster.adoc - -[id="olm-deleting-operator-from-a-cluster-using-cli_{context}"] -= Deleting Operators from a cluster using the CLI - -Cluster administrators can delete installed Operators from a selected namespace by using the CLI. - -.Prerequisites - -- Access to an {product-title} cluster using an account with -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -`cluster-admin` permissions. -endif::[] -ifdef::openshift-dedicated[] -`dedicated-admins-cluster` permissions. -endif::[] -- `oc` command installed on workstation. - -.Procedure - -. Check the current version of the subscribed Operator (for example, `jaeger`) in the `currentCSV` field: -+ -[source,terminal] ----- -$ oc get subscription jaeger -n openshift-operators -o yaml | grep currentCSV ----- -+ -.Example output -[source,terminal] ----- - currentCSV: jaeger-operator.v1.8.2 ----- - -. Delete the subscription (for example, `jaeger`): -+ -[source,terminal] ----- -$ oc delete subscription jaeger -n openshift-operators ----- -+ -.Example output -[source,terminal] ----- -subscription.operators.coreos.com "jaeger" deleted ----- - -. Delete the CSV for the Operator in the target namespace using the `currentCSV` value from the previous step: -+ -[source,terminal] ----- -$ oc delete clusterserviceversion jaeger-operator.v1.8.2 -n openshift-operators ----- -+ -.Example output -[source,terminal] ----- -clusterserviceversion.operators.coreos.com "jaeger-operator.v1.8.2" deleted ----- diff --git a/modules/olm-deleting-operators-from-a-cluster-using-web-console.adoc b/modules/olm-deleting-operators-from-a-cluster-using-web-console.adoc deleted file mode 100644 index 4eabb9956b62..000000000000 --- a/modules/olm-deleting-operators-from-a-cluster-using-web-console.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-deleting-operators-from-a-cluster.adoc - -[id="olm-deleting-operators-from-a-cluster-using-web-console_{context}"] -= Deleting Operators from a cluster using the web console - -Cluster administrators can delete installed Operators from a selected namespace by using the web console. - -.Prerequisites - -- Access to an {product-title} cluster web console using an account with -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -`cluster-admin` permissions. -endif::[] -ifdef::openshift-dedicated[] -`dedicated-admins-cluster` permissions. -endif::[] - -.Procedure - -. From the *Operators* → *Installed Operators* page, scroll or type a keyword into the *Filter by name* to find the Operator you want. Then, click on it. - -. On the right-hand side of the *Operator Details* page, select *Uninstall Operator* from the *Actions* drop-down menu. -+ -An *Uninstall Operator?* dialog box is displayed, reminding you that: -+ -[.small] --- -*Removing the Operator will not remove any of its custom resource definitions or managed resources. If your Operator has deployed applications on the cluster or configured off-cluster resources, these will continue to run and need to be cleaned up manually.* --- -+ -The Operator, any Operator deployments, and pods are removed by this action. Any resources managed by the Operator, including CRDs and CRs, are not removed. The web console enables dashboards and navigation items for some Operators. To remove these after uninstalling the Operator, you might need to manually delete the Operator CRDs. - -. Select *Uninstall*. This Operator stops running and no longer receives updates. diff --git a/modules/olm-dependencies-best-practices.adoc b/modules/olm-dependencies-best-practices.adoc deleted file mode 100644 index 0f7cc497de5f..000000000000 --- a/modules/olm-dependencies-best-practices.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc - -[id="olm-dependency-best-practices_{context}"] -= Dependency best practices - -When specifying dependencies, there are best practices you should consider. - -Depend on APIs or a specific version range of Operators:: -Operators can add or remove APIs at any time; always specify an `olm.gvk` dependency on any APIs your Operators requires. The exception to this is if you are specifying `olm.package` constraints instead. - -Set a minimum version:: -The Kubernetes documentation on API changes describes what changes are allowed for Kubernetes-style Operators. These versioning conventions allow an Operator to update an API without bumping the API version, as long as the API is backwards-compatible. -+ -For Operator dependencies, this means that knowing the API version of a dependency might not be enough to ensure the dependent Operator works as intended. -+ -For example: -+ --- -* TestOperator v1.0.0 provides v1alpha1 API version of the `MyObject` resource. -* TestOperator v1.0.1 adds a new field `spec.newfield` to `MyObject`, but still at v1alpha1. --- -+ -Your Operator might require the ability to write `spec.newfield` into the `MyObject` resource. An `olm.gvk` constraint alone is not enough for OLM to determine that you need TestOperator v1.0.1 and not TestOperator v1.0.0. -+ -Whenever possible, if a specific Operator that provides an API is known ahead of time, specify an additional `olm.package` constraint to set a minimum. - -Omit a maximum version or allow a very wide range:: -Because Operators provide cluster-scoped resources such as API services and CRDs, an Operator that specifies a small window for a dependency might unnecessarily constrain updates for other consumers of that dependency. -+ -Whenever possible, do not set a maximum version. Alternatively, set a very wide semantic range to prevent conflicts with other Operators. For example, `>1.0.0 <2.0.0`. -+ -Unlike with conventional package managers, Operator authors explicitly encode that updates are safe through channels in OLM. If an update is available for an existing subscription, it is assumed that the Operator author is indicating that it can update from the previous version. Setting a maximum version for a dependency overrides the update stream of the author by unnecessarily truncating it at a particular upper bound. -+ -[NOTE] -==== -Cluster administrators cannot override dependencies set by an Operator author. -==== -+ -However, maximum versions can and should be set if there are known incompatibilities that must be avoided. Specific versions can be omitted with the version range syntax, for example `> 1.0.0 !1.2.1`. diff --git a/modules/olm-dependencies-caveats.adoc b/modules/olm-dependencies-caveats.adoc deleted file mode 100644 index 3f7936c309f0..000000000000 --- a/modules/olm-dependencies-caveats.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc - -[id="olm-dependency-caveats_{context}"] -= Dependency caveats - -When specifying dependencies, there are caveats you should consider. - -No compound constraints (AND):: -There is currently no method for specifying an AND relationship between constraints. In other words, there is no way to specify that one Operator depends on another Operator that both provides a given API and has version `>1.1.0`. -+ -This means that when specifying a dependency such as: -+ -[source,yaml] ----- -dependencies: -- type: olm.package - value: - packageName: etcd - version: ">3.1.0" -- type: olm.gvk - value: - group: etcd.database.coreos.com - kind: EtcdCluster - version: v1beta2 ----- -+ -It would be possible for OLM to satisfy this with two Operators: one that provides EtcdCluster and one that has version `>3.1.0`. Whether that happens, or whether an Operator is selected that satisfies both constraints, depends on the ordering that potential options are visited. Dependency preferences and ordering options are well-defined and can be reasoned about, but to exercise caution, Operators should stick to one mechanism or the other. - -Cross-namespace compatibility:: -OLM performs dependency resolution at the namespace scope. It is possible to get into an update deadlock if updating an Operator in one namespace would be an issue for an Operator in another namespace, and vice-versa. diff --git a/modules/olm-dependency-resolution-about.adoc b/modules/olm-dependency-resolution-about.adoc deleted file mode 100644 index 299430b515d4..000000000000 --- a/modules/olm-dependency-resolution-about.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc - -[id="olm-dependency-resolution-about_{context}"] -= About dependency resolution - -OLM manages the dependency resolution and upgrade lifecycle of running Operators. In many ways, the problems OLM faces are similar to other operating system package managers like `yum` and `rpm`. - -However, there is one constraint that similar systems do not generally have that OLM does: because Operators are always running, OLM attempts to ensure that you are never left with a set of Operators that do not work with each other. - -This means that OLM must never do the following: - -- Install a set of Operators that require APIs that cannot be provided. -- Update an Operator in a way that breaks another that depends upon it. diff --git a/modules/olm-dependency-resolution-crd-upgrades.adoc b/modules/olm-dependency-resolution-crd-upgrades.adoc deleted file mode 100644 index 9c5721d23f4d..000000000000 --- a/modules/olm-dependency-resolution-crd-upgrades.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="olm-dependency-resolution-crd-upgrades_{context}"] -= CRD upgrades - -OLM upgrades a custom resource definition (CRD) immediately if it is owned by a singular cluster service version (CSV). If a CRD is owned by multiple CSVs, then the CRD is upgraded when it has satisfied all of the following backward compatible conditions: - -- All existing serving versions in the current CRD are present in the new CRD. -- All existing instances, or custom resources, that are associated with the serving versions of the CRD are valid when validated against the validation schema of the new CRD. diff --git a/modules/olm-dependency-resolution-examples.adoc b/modules/olm-dependency-resolution-examples.adoc deleted file mode 100644 index fd30b57a7899..000000000000 --- a/modules/olm-dependency-resolution-examples.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc - -[id="olm-dependency-resolution-examples_{context}"] -= Example dependency resolution scenarios - -In the following examples, a _provider_ is an Operator which "owns" a CRD or API service. - -[discrete] -=== Example: Deprecating dependent APIs - -A and B are APIs (CRDs): - -* The provider of A depends on B. -* The provider of B has a subscription. -* The provider of B updates to provide C but deprecates B. - -This results in: - -* B no longer has a provider. -* A no longer works. - -This is a case OLM prevents with its upgrade strategy. - -[discrete] -=== Example: Version deadlock - -A and B are APIs: - -* The provider of A requires B. -* The provider of B requires A. -* The provider of A updates to (provide A2, require B2) and deprecate A. -* The provider of B updates to (provide B2, require A2) and deprecate B. - -If OLM attempts to update A without simultaneously updating B, or vice-versa, it is unable to progress to new versions of the Operators, even though a new compatible set can be found. - -This is another case OLM prevents with its upgrade strategy. diff --git a/modules/olm-dependency-resolution-preferences.adoc b/modules/olm-dependency-resolution-preferences.adoc deleted file mode 100644 index 91ece1fccce4..000000000000 --- a/modules/olm-dependency-resolution-preferences.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-dependency-resolution.adoc - -[id="olm-dependency-resolution-preferences_{context}"] -= Dependency preferences - -There can be many options that equally satisfy a dependency of an Operator. The dependency resolver in Operator Lifecycle Manager (OLM) determines which option best fits the requirements of the requested Operator. As an Operator author or user, it can be important to understand how these choices are made so that dependency resolution is clear. - -[id="olm-dependency-catalog-priority_{context}"] -== Catalog priority - -On {product-title} cluster, OLM reads catalog sources to know which Operators are available for installation. - -.Example `CatalogSource` object -[source,yaml] ----- -apiVersion: "operators.coreos.com/v1alpha1" -kind: "CatalogSource" -metadata: - name: "my-operators" - namespace: "operators" -spec: - sourceType: grpc - image: example.com/my/operator-index:v1 - displayName: "My Operators" - priority: 100 ----- - -A `CatalogSource` object has a `priority` field, which is used by the resolver to know how to prefer options for a dependency. - -There are two rules that govern catalog preference: - -* Options in higher-priority catalogs are preferred to options in lower-priority catalogs. -* Options in the same catalog as the dependent are preferred to any other catalogs. - -[id="olm-dependency-catalog-ordering_{context}"] -== Channel ordering - -An Operator package in a catalog is a collection of update channels that a user can subscribe to in a {product-title} cluster. Channels can be used to provide a particular stream of updates for a minor release (`1.2`, `1.3`) or a release frequency (`stable`, `fast`). - -It is likely that a dependency might be satisfied by Operators in the same package, but different channels. For example, version `1.2` of an Operator might exist in both the `stable` and `fast` channels. - -Each package has a default channel, which is always preferred to non-default channels. If no option in the default channel can satisfy a dependency, options are considered from the remaining channels in lexicographic order of the channel name. - -[id="olm-dependency-order-winthin-channel_{context}"] -== Order within a channel - -There are almost always multiple options to satisfy a dependency within a single channel. For example, Operators in one package and channel provide the same set of APIs. - -When a user creates a subscription, they indicate which channel to receive updates from. This immediately reduces the search to just that one channel. But within the channel, it is likely that many Operators satisfy a dependency. - -Within a channel, newer Operators that are higher up in the update graph are preferred. If the head of a channel satisfies a dependency, it will be tried first. - -[id="olm-dependency-preferences-other_{context}"] -== Other constraints - -In addition to the constraints supplied by package dependencies, OLM includes additional constraints to represent the desired user state and enforce resolution invariants. - -[id="olm-dependency-sub-constraint_{context}"] -=== Subscription constraint - -A subscription constraint filters the set of Operators that can satisfy a subscription. Subscriptions are user-supplied constraints for the dependency resolver. They declare the intent to either install a new Operator if it is not already on the cluster, or to keep an existing Operator updated. - -[id="olm-dependency-package-constraint_{context}"] -=== Package constraint - -Within a namespace, no two Operators may come from the same package. diff --git a/modules/olm-enabling-operator-for-multi-arch.adoc b/modules/olm-enabling-operator-for-multi-arch.adoc deleted file mode 100644 index 64ce5d292e6a..000000000000 --- a/modules/olm-enabling-operator-for-multi-arch.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="olm-enabling-operator-for-multi-arch_{context}"] -= Enabling your Operator for multiple architectures and operating systems - -Operator Lifecycle Manager (OLM) assumes that all Operators run on Linux hosts. However, as an Operator author, you can specify whether your Operator supports managing workloads on other architectures, if worker nodes are available in the {product-title} cluster. - -If your Operator supports variants other than AMD64 and Linux, you can add labels to the cluster service version (CSV) that provides the Operator to list the supported variants. Labels indicating supported architectures and operating systems are defined by the following: - -[source,yaml] ----- -labels: - operatorframework.io/arch.<arch>: supported <1> - operatorframework.io/os.<os>: supported <2> ----- -<1> Set `<arch>` to a supported string. -<2> Set `<os>` to a supported string. - -[NOTE] -==== -Only the labels on the channel head of the default channel are considered for filtering package manifests by label. This means, for example, that providing an additional architecture for an Operator in the non-default channel is possible, but that architecture is not available for filtering in the `PackageManifest` API. -==== - -If a CSV does not include an `os` label, it is treated as if it has the following Linux support label by default: - -[source,yaml] ----- -labels: - operatorframework.io/os.linux: supported ----- - -If a CSV does not include an `arch` label, it is treated as if it has the following AMD64 support label by default: - -[source,yaml] ----- -labels: - operatorframework.io/arch.amd64: supported ----- - -If an Operator supports multiple node architectures or operating systems, you can add multiple labels, as well. - -.Prerequisites - -* An Operator project with a CSV. -* To support listing multiple architectures and operating systems, your Operator image referenced in the CSV must be a manifest list image. -* For the Operator to work properly in restricted network, or disconnected, environments, the image referenced must also be specified using a digest (SHA) and not by a tag. - -.Procedure - -* Add a label in the `metadata.labels` of your CSV for each supported architecture and operating system that your Operator supports: -+ -[source,yaml] ----- -labels: - operatorframework.io/arch.s390x: supported - operatorframework.io/os.zos: supported - operatorframework.io/os.linux: supported <1> - operatorframework.io/arch.amd64: supported <1> ----- -<1> After you add a new architecture or operating system, you must also now include the default `os.linux` and `arch.amd64` variants explicitly. diff --git a/modules/olm-enabling-operator-restricted-network.adoc b/modules/olm-enabling-operator-restricted-network.adoc deleted file mode 100644 index 38170e1d573e..000000000000 --- a/modules/olm-enabling-operator-restricted-network.adoc +++ /dev/null @@ -1,112 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="olm-enabling-operator-for-restricted-network_{context}"] -= Enabling your Operator for restricted network environments - -As an Operator author, your Operator must meet additional requirements to run properly in a restricted network, or disconnected, environment. - -.Operator requirements for supporting disconnected mode - -* In the cluster service version (CSV) of your Operator: -** List any _related images_, or other container images that your Operator might require to perform their functions. -** Reference all specified images by a digest (SHA) and not by a tag. -* All dependencies of your Operator must also support running in a disconnected mode. -* Your Operator must not require any off-cluster resources. -// TODO: Include more info w/ better steps on how to do this: -//* You must understand the {product-title} proxy configuration. - -For the CSV requirements, you can make the following changes as the Operator author. - -.Prerequisites - -* An Operator project with a CSV. - -.Procedure - -. Use SHA references to related images in two places in the CSV for your Operator: - -.. Update `spec.relatedImages`: -+ -[source,yaml] ----- -... -spec: - relatedImages: <1> - - name: etcd-operator <2> - image: quay.io/etcd-operator/operator@sha256:d134a9865524c29fcf75bbc4469013bc38d8a15cb5f41acfddb6b9e492f556e4 <3> - - name: etcd-image - image: quay.io/etcd-operator/etcd@sha256:13348c15263bd8838ec1d5fc4550ede9860fcbb0f843e48cbccec07810eebb68 -... ----- -<1> Create a `relatedImages` section and set the list of related images. -<2> Specify a unique identifier for the image. -<3> Specify each image by a digest (SHA), not by an image tag. - -.. Update the `env` section in the deployment when declaring environment variables that inject the image that the Operator should use: -+ -[source,yaml] ----- -spec: - install: - spec: - deployments: - - name: etcd-operator-v3.1.1 - spec: - replicas: 1 - selector: - matchLabels: - name: etcd-operator - strategy: - type: Recreate - template: - metadata: - labels: - name: etcd-operator - spec: - containers: - - args: - - /opt/etcd/bin/etcd_operator_run.sh - env: - - name: WATCH_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.annotations['olm.targetNamespaces'] - - name: ETCD_OPERATOR_DEFAULT_ETCD_IMAGE <1> - value: quay.io/etcd-operator/etcd@sha256:13348c15263bd8838ec1d5fc4550ede9860fcbb0f843e48cbccec07810eebb68 <2> - - name: ETCD_LOG_LEVEL - value: INFO - image: quay.io/etcd-operator/operator@sha256:d134a9865524c29fcf75bbc4469013bc38d8a15cb5f41acfddb6b9e492f556e4 <3> - imagePullPolicy: IfNotPresent - livenessProbe: - httpGet: - path: /healthy - port: 8080 - initialDelaySeconds: 10 - periodSeconds: 30 - name: etcd-operator - readinessProbe: - httpGet: - path: /ready - port: 8080 - initialDelaySeconds: 10 - periodSeconds: 30 - resources: {} - serviceAccountName: etcd-operator - strategy: deployment ----- -<1> Inject the images referenced by the Operator by using environment variables. -<2> Specify each image by a digest (SHA), not by an image tag. -<3> Also reference the Operator container image by a digest (SHA), not by an image tag. - -. Add the `Disconnected` annotation, which indicates that the Operator works in a disconnected environment: -+ -[source,yaml] ----- -metadata: - annotations: - operators.openshift.io/infrastructure-features: '["Disconnected"]' ----- -+ -Operators can be filtered in OperatorHub by this infrastructure feature. diff --git a/modules/olm-injecting-custom-ca.adoc b/modules/olm-injecting-custom-ca.adoc deleted file mode 100644 index 93f4adda57ce..000000000000 --- a/modules/olm-injecting-custom-ca.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-configuring-proxy-support.adoc - -[id="olm-inject-custom-ca_{context}"] -= Injecting a custom CA certificate - -When a cluster administrator adds a custom CA certificate to a cluster using a config map, the Cluster Network Operator merges the user-provided certificates and system CA certificates into a single bundle. You can inject this merged bundle into your Operator running on Operator Lifecycle Manager (OLM), which is useful if you have a man-in-the-middle HTTPS proxy. - -.Prerequisites - -- Access to an {product-title} cluster using an account with -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -`cluster-admin` permissions. -endif::[] -ifdef::openshift-dedicated[] -`dedicated-admins-cluster` permissions. -endif::[] -- Custom CA certificate added to the cluster using a config map. -- Desired Operator installed and running on OLM. - -.Procedure - -. Create an empty config map in the namespace where the subscription for your Operator exists and include the following label: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: trusted-ca <1> - labels: - config.openshift.io/inject-trusted-cabundle: "true" <2> ----- -<1> Name of the config map. -<2> Requests the Cluster Network Operator to inject the merged bundle. -+ -After creating this config map, it is immediately populated with the certificate contents of the merged bundle. - -. Update your the `Subscription` object to include a `spec.config` section that mounts the `trusted-ca` config map as a volume to each container within a pod that requires a custom CA: -+ -[source,yaml] ----- -kind: Subscription -metadata: - name: my-operator -spec: - package: etcd - channel: alpha - config: <1> - - selector: - matchLabels: - <labels_for_pods> <2> - volumes: <3> - - name: trusted-ca - configMap: - name: trusted-ca - items: - - key: ca-bundle.crt <4> - path: tls-ca-bundle.pem <5> - volumeMounts: <6> - - name: trusted-ca - mountPath: /etc/pki/ca-trust/extracted/pem - readOnly: true ----- -<1> Add a `config` section if it does not exist. -<2> Specify labels to match pods that are owned by the Operator. -<3> Create a `trusted-ca` volume. -<4> `ca-bundle.crt` is required as the config map key. -<5> `tls-ca-bundle.pem` is required as the config map path. -<6> Create a `trusted-ca` volume mount. diff --git a/modules/olm-installing-from-operatorhub-using-cli.adoc b/modules/olm-installing-from-operatorhub-using-cli.adoc deleted file mode 100644 index 17d5f0c67a42..000000000000 --- a/modules/olm-installing-from-operatorhub-using-cli.adoc +++ /dev/null @@ -1,135 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/user/olm-installing-operators-in-namespace.adoc -// * operators/admin/olm-adding-operators-to-cluster.adoc -// * post_installation_configuration/preparing-for-users.adoc -// -// Module watched for changes by Ecosystem Catalog team: -// https://projects.engineering.redhat.com/projects/RHEC/summary - -ifeval::["{context}" == "olm-installing-operators-in-namespace"] -:olm-user: -endif::[] - -[id="olm-installing-operator-from-operatorhub-using-cli_{context}"] -= Installing from OperatorHub using the CLI - -Instead of using the {product-title} web console, you can install an Operator from OperatorHub using the CLI. Use the `oc` command to create or update a `Subscription` object. - -.Prerequisites - -ifndef::olm-user[] -- Access to an {product-title} cluster using an account with -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -`cluster-admin` permissions. -endif::[] -ifdef::openshift-dedicated[] -`dedicated-admins-cluster` permissions. -endif::[] -endif::[] - -ifdef::olm-user[] -- Access to an {product-title} cluster using an account with Operator installation permissions. -endif::[] - -- Install the `oc` command to your local system. - -.Procedure - -. View the list of Operators available to the cluster from OperatorHub: -+ -[source,terminal] ----- -$ oc get packagemanifests -n openshift-marketplace ----- -+ -.Example output -[source,terminal] ----- -NAME CATALOG AGE -3scale-operator Red Hat Operators 91m -advanced-cluster-management Red Hat Operators 91m -amq7-cert-manager Red Hat Operators 91m -... -couchbase-enterprise-certified Certified Operators 91m -crunchy-postgres-operator Certified Operators 91m -mongodb-enterprise Certified Operators 91m -... -etcd Community Operators 91m -jaeger Community Operators 91m -kubefed Community Operators 91m -... ----- -+ -Note the catalog for your desired Operator. - -. Inspect your desired Operator to verify its supported install modes and available channels: -+ -[source,terminal] ----- -$ oc describe packagemanifests <operator_name> -n openshift-marketplace ----- - -. An Operator group, defined by an `OperatorGroup` object, selects target namespaces in which to generate required RBAC access for all Operators in the same namespace as the Operator group. -+ -The namespace to which you subscribe the Operator must have an Operator group that matches the install mode of the Operator, either the `AllNamespaces` or `SingleNamespace` mode. If the Operator you intend to install uses the `AllNamespaces`, then the `openshift-operators` namespace already has an appropriate Operator group in place. -+ -However, if the Operator uses the `SingleNamespace` mode and you do not already have an appropriate Operator group in place, you must create one. -+ -[NOTE] -==== -The web console version of this procedure handles the creation of the `OperatorGroup` and `Subscription` objects automatically behind the scenes for you when choosing `SingleNamespace` mode. -==== - -.. Create an `OperatorGroup` object YAML file, for example `operatorgroup.yaml`: -+ -.Example `OperatorGroup` object -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: <operatorgroup_name> - namespace: <namespace> -spec: - targetNamespaces: - - <namespace> ----- - -.. Create the `OperatorGroup` object: -+ -[source,terminal] ----- -$ oc apply -f operatorgroup.yaml ----- - -. Create a `Subscription` object YAML file to subscribe a namespace to an Operator, for example `sub.yaml`: -+ -.Example `Subscription` object -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: <subscription_name> - namespace: openshift-operators <1> -spec: - channel: <channel_name> <2> - name: <operator_name> <3> - source: redhat-operators <4> - sourceNamespace: openshift-marketplace <5> ----- -<1> For `AllNamespaces` install mode usage, specify the `openshift-operators` namespace. Otherwise, specify the relevant single namespace for `SingleNamespace` install mode usage. -<2> Name of the channel to subscribe to. -<3> Name of the Operator to subscribe to. -<4> Name of the catalog source that provides the Operator. -<5> Namespace of the catalog source. Use `openshift-marketplace` for the default OperatorHub catalog sources. - -. Create the `Subscription` object: -+ -[source,terminal] ----- -$ oc apply -f sub.yaml ----- -+ -At this point, OLM is now aware of the selected Operator. A cluster service version (CSV) for the Operator should appear in the target namespace, and APIs provided by the Operator should be available for creation. diff --git a/modules/olm-installing-from-operatorhub-using-web-console.adoc b/modules/olm-installing-from-operatorhub-using-web-console.adoc deleted file mode 100644 index 547a7fa32efa..000000000000 --- a/modules/olm-installing-from-operatorhub-using-web-console.adoc +++ /dev/null @@ -1,103 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/user/olm-installing-operators-in-namespace.adoc -// * operators/admin/olm-adding-operators-to-cluster.adoc -// * post_installation_configuration/preparing-for-users.adoc -// -// Module watched for changes by Ecosystem Catalog team: -// https://projects.engineering.redhat.com/projects/RHEC/summary - -// Add additional ifevals here, but before context == olm-adding-operators-to-a-cluster -ifeval::["{context}" != "olm-adding-operators-to-a-cluster"] -:filter-type: jaeger -:filter-operator: Jaeger -:olm-admin: -endif::[] -ifeval::["{context}" == "olm-installing-operators-in-namespace"] -:filter-type: advanced -:filter-operator: Advanced Cluster Management for Kubernetes -:olm-admin!: -:olm-user: -endif::[] - -// Keep this ifeval last -ifeval::["{context}" == "olm-adding-operators-to-a-cluster"] -:filter-type: advanced -:filter-operator: Advanced Cluster Management for Kubernetes -:olm-admin: -endif::[] - -[id="olm-installing-from-operatorhub-using-web-console_{context}"] -= Installing from OperatorHub using the web console - -You can install and subscribe to an Operator from OperatorHub using the {product-title} web console. - -.Prerequisites - -ifdef::olm-admin[] -- Access to an {product-title} cluster using an account with -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -`cluster-admin` permissions. -endif::[] -ifdef::openshift-dedicated[] -`dedicated-admins-cluster` permissions. -endif::[] -endif::[] - -ifdef::olm-user[] -- Access to an {product-title} cluster using an account with Operator installation permissions. -endif::[] - -.Procedure - -. Navigate in the web console to the *Operators → OperatorHub* page. - -. Scroll or type a keyword into the *Filter by keyword* box to find the Operator you want. For example, type `{filter-type}` to find the {filter-operator} Operator. -+ -You can also filter options by *Infrastructure Features*. For example, select *Disconnected* if you want to see Operators that work in disconnected environments, also known as restricted network environments. - -. Select the Operator to display additional information. -+ -[NOTE] -==== -Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing. -==== - -. Read the information about the Operator and click *Install*. - -. On the *Install Operator* page: - -ifdef::olm-admin[] -.. Select one of the following: -*** *All namespaces on the cluster (default)* installs the Operator in the default `openshift-operators` namespace to watch and be made available to all namespaces in the cluster. This option is not always available. -*** *A specific namespace on the cluster* allows you to choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace. -ifdef::openshift-dedicated[] -If you are installing the Cluster Logging Operator, choose this option to select the `openshift-logging` namespace. -endif::[] -endif::[] -ifdef::olm-user[] -.. Choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace. -endif::[] - -.. Select an *Update Channel* (if more than one is available). - -.. Select *Automatic* or *Manual* approval strategy, as described earlier. - -. Click *Install* to make the Operator available to the selected namespaces on this {product-title} cluster. - -.. If you selected a *Manual* approval strategy, the upgrade status of the subscription remains *Upgrading* until you review and approve the install plan. -+ -After approving on the *Install Plan* page, the subscription upgrade status moves to *Up to date*. - -.. If you selected an *Automatic* approval strategy, the upgrade status should resolve to *Up to date* without intervention. - -. After the upgrade status of the subscription is *Up to date*, select *Operators → Installed Operators* to verify that the cluster service version (CSV) of the installed Operator eventually shows up. The *Status* should ultimately resolve to *InstallSucceeded* in the relevant namespace. -+ -[NOTE] -==== -For the *All namespaces...* installation mode, the status resolves to *InstallSucceeded* in the `openshift-operators` namespace, but the status is *Copied* if you check in other namespaces. -==== -+ -If it does not: - -.. Check the logs in any pods in the `openshift-operators` project (or other relevant namespace if *A specific namespace...* installation mode was selected) on the *Workloads → Pods* page that are reporting issues to troubleshoot further. diff --git a/modules/olm-installing-operators-from-operatorhub-configure.adoc b/modules/olm-installing-operators-from-operatorhub-configure.adoc deleted file mode 100644 index d9b6fb523701..000000000000 --- a/modules/olm-installing-operators-from-operatorhub-configure.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/user/olm-installing-operators-in-namespace.adoc -// * operators/admin/olm-adding-operators-to-cluster.adoc -// * post_installation_configuration/preparing-for-users.adoc -// -// Module watched for changes by Ecosystem Catalog team: -// https://projects.engineering.redhat.com/projects/RHEC/summary - - -[id="olm-installing-operators-from-operatorhub-configure_{context}"] -= Configuring {product-title} to use Red Hat Operators - -In {product-title}, Red Hat Operators are not available by default. You can access and install these Operators if you have a pull secret from the Red Hat OpenShift Cluster Manager site by editing the `OperatorHub` custom resource (CR). - -.Prerequisites - -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in the installation procedure. - -.Procedure - -To access the Red Hat Operators in a {product-title} cluster: - -. Edit the `OperatorHub` CR using the web console or CLI: - -.. Using the CLI: - -... Edit the `OperatorHub` CR: -+ -[source,terminal] ----- -$ oc edit OperatorHub cluster ----- - -... Add `redhat-operators` to the list of sources as `disabled: false`: -+ -.Example `OperatorHub` CR -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OperatorHub -metadata: - name: cluster -spec: - disableAllDefaultSources: true - sources: - - disabled: false <1> - name: redhat-operators - - disabled: false - name: community-operators ----- -<1> Add the `name: redhat-operators` and `disabled: false` parameters. - -.. Using the web console: - -... Switch to the *Administration* -> *Custom Resource Definitions* page. - -... On the *Custom Resource Definitions* page, click *OperatorHub*. - -... On the *Custom Resource Definition Overview* page, click *Instances*. - -... On the *Instances* tab, click *cluster*. - -... On the *Instances* tab, click *YAML*. - -... In the YAML field, add `redhat-operators` to the list of sources as `disabled: false`: -+ -.Example `OperatorHub` CR -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OperatorHub -metadata: - name: cluster -spec: - disableAllDefaultSources: true - sources: - - disabled: false <1> - name: redhat-operators - - disabled: false - name: community-operators ----- -<1> Add the `name: redhat-operators` and `disabled: false` parameters. - -... Click *Save*. - -. Log out of the web console, and then log back in. diff --git a/modules/olm-installing-operators-from-operatorhub.adoc b/modules/olm-installing-operators-from-operatorhub.adoc deleted file mode 100644 index ad3eb0d2f624..000000000000 --- a/modules/olm-installing-operators-from-operatorhub.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/user/olm-installing-operators-in-namespace.adoc -// * operators/admin/olm-adding-operators-to-cluster.adoc -// * post_installation_configuration/preparing-for-users.adoc -// -// Module watched for changes by Ecosystem Catalog team: -// https://projects.engineering.redhat.com/projects/RHEC/summary - -ifeval::["{context}" == "olm-installing-operators-in-namespace"] -:olm-user: -endif::[] - -[id="olm-installing-operators-from-operatorhub_{context}"] -= Operator installation with OperatorHub - -OperatorHub is a user interface for discovering Operators; it works in conjunction with Operator Lifecycle Manager (OLM), which installs and manages Operators on a cluster. - -ifndef::olm-user[] -As a cluster administrator, you can install an Operator from OperatorHub using the {product-title} -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -web console or CLI. Subscribing an Operator to one or more namespaces makes the Operator available to developers on your cluster. -endif::[] -ifdef::openshift-dedicated[] -web console. You can then subscribe the Operator to the default `openshift-operators` namespace to make it available for developers on your cluster. When you subscribe the Operator to all namespaces, the Operator is installed in the `openshift-operators` namespace; this installation method is not supported by all Operators. - -In {product-title} clusters, a curated list of Operators is made available for installation from OperatorHub. Administrators can only install Operators to the default `openshift-operators` namespace, except for the Logging Operator, which requires the `openshift-logging` namespace. - -[NOTE] -==== -Privileged and custom Operators cannot be installed. -==== -endif::[] -endif::[] - -ifdef::olm-user[] -As a user with the proper permissions, you can install an Operator from OperatorHub using the {product-title} web console or CLI. -endif::[] - -During installation, you must determine the following initial settings for the Operator: - -ifndef::olm-user[] -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -Installation Mode:: Choose *All namespaces on the cluster (default)* to have the Operator installed on all namespaces or choose individual namespaces, if available, to only install the Operator on selected namespaces. This example chooses *All namespaces...* to make the Operator available to all users and projects. -endif::[] -ifdef::openshift-dedicated[] -Installation Mode:: In {product-title} clusters, you can choose *All namespaces on the cluster (default)* to have the Operator installed on all namespaces. This makes the Operator available to all users and projects. -endif::[] -endif::[] -ifdef::olm-user[] -Installation Mode:: Choose a specific namespace in which to install the Operator. -endif::[] - -Update Channel:: If an Operator is available through multiple channels, you can choose which channel you want to subscribe to. For example, to deploy from the *stable* channel, if available, select it from the list. - -Approval Strategy:: You can choose automatic or manual updates. -+ -If you choose automatic updates for an installed Operator, when a new version of that Operator is available in the selected channel, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention. -+ -If you select manual updates, when a newer version of an Operator is available, OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version. diff --git a/modules/olm-installing-opm.adoc b/modules/olm-installing-opm.adoc deleted file mode 100644 index ac511c929f18..000000000000 --- a/modules/olm-installing-opm.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/opm-cli.adoc - -[id="olm-installing-opm_{context}"] -= Installing opm - -You can install the `opm` CLI tool on your Linux, macOS, or Windows workstation. - -.Prerequisites - -* For Linux, you must provide the following packages: -** `podman` version 1.9.3+ (version 2.0+ recommended) -** `glibc` version 2.28+ - -.Procedure - -. Navigate to the link:https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/latest-4.7/[OpenShift mirror site] and download the latest version of the tarball that matches your operating system. - -. Unpack the archive. - -** For Linux or macOS: -+ -[source,terminal,subs="attributes+"] ----- -$ tar xvf <file> ----- - -** For Windows, unzip the archive with a ZIP program. - -. Place the file anywhere in your `PATH`. -+ --- -* For Linux or macOS: - -.. Check your `PATH`: -+ -[source,terminal] ----- -$ echo $PATH ----- - -.. Move the file. For example: -+ -[source,terminal] ----- -$ sudo mv ./opm /usr/local/bin/ ----- - -* For Windows: - -.. Check your `PATH`: -+ -[source,terminal] ----- -C:\> path ----- - -.. Move the file: -+ -[source,terminal] ----- -C:\> move opm.exe <directory> ----- --- - -.Verification - -* After you install the `opm` CLI, verify that it is available: -+ -[source,terminal] ----- -$ opm version ----- -+ -.Example output -[source,terminal] ----- -Version: version.Version{OpmVersion:"v1.15.4-2-g6183dbb3", GitCommit:"6183dbb3567397e759f25752011834f86f47a3ea", BuildDate:"2021-02-13T04:16:08Z", GoOs:"linux", GoArch:"amd64"} ----- diff --git a/modules/olm-installing-specific-version-cli.adoc b/modules/olm-installing-specific-version-cli.adoc deleted file mode 100644 index 334d53d4c009..000000000000 --- a/modules/olm-installing-specific-version-cli.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/user/olm-installing-operators-in-namespace.adoc -// * operators/admin/olm-adding-operators-to-cluster.adoc - -ifeval::["{context}" == "olm-installing-operators-in-namespace"] -:olm-user: -endif::[] - -[id="olm-installing-specific-version-cli_{context}"] -= Installing a specific version of an Operator - -You can install a specific version of an Operator by setting the cluster service version (CSV) in a `Subscription` object. - -.Prerequisites - -ifndef::olm-user[] -- Access to an {product-title} cluster using an account with -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -`cluster-admin` permissions -endif::[] -ifdef::openshift-dedicated[] -`dedicated-admins-cluster` permissions -endif::[] -endif::[] - -ifdef::olm-user[] -- Access to an {product-title} cluster using an account with Operator installation permissions -endif::[] - -- OpenShift CLI (`oc`) installed - -.Procedure - -. Create a `Subscription` object YAML file that subscribes a namespace to an Operator with a specific version by setting the `startingCSV` field. Set the `installPlanApproval` field to `Manual` to prevent the Operator from automatically upgrading if a later version exists in the catalog. -+ -For example, the following `sub.yaml` file can be used to install the Red Hat Quay Operator specifically to version 3.4.0: -+ -.Subscription with a specific starting Operator version -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: quay-operator - namespace: quay -spec: - channel: quay-v3.4 - installPlanApproval: Manual <1> - name: quay-operator - source: redhat-operators - sourceNamespace: openshift-marketplace - startingCSV: quay-operator.v3.4.0 <2> ----- -<1> Set the approval strategy to `Manual` in case your specified version is superseded by a later version in the catalog. This plan prevents an automatic upgrade to a later version and requires manual approval before the starting CSV can complete the installation. -<2> Set a specific version of an Operator CSV. - -. Create the `Subscription` object: -+ -[source,terminal] ----- -$ oc apply -f sub.yaml ----- - -. Manually approve the pending install plan to complete the Operator installation. diff --git a/modules/olm-installplan.adoc b/modules/olm-installplan.adoc deleted file mode 100644 index 8f4752ad6674..000000000000 --- a/modules/olm-installplan.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc - -[id="olm-installplan_{context}"] -= Install plan - -An _install plan_, defined by an `InstallPlan` object, describes a set of resources to be created to install or upgrade to a specific version of an Operator, as defined by a cluster service version (CSV). diff --git a/modules/olm-metrics.adoc b/modules/olm-metrics.adoc deleted file mode 100644 index 0e70340be1ba..000000000000 --- a/modules/olm-metrics.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc - -[id="olm-metrics_{context}"] -= Exposed metrics - -Operator Lifecycle Manager (OLM) exposes certain OLM-specific resources for use by the Prometheus-based {product-title} cluster monitoring stack. - -.Metrics exposed by OLM -[cols="2a,8a",options="header"] -|=== -|Name |Description - -|`catalog_source_count` -|Number of catalog sources. - -|`csv_abnormal` -|When reconciling a cluster service version (CSV), present whenever a CSV version is in any state other than `Succeeded`, for example when it is not installed. Includes the `name`, `namespace`, `phase`, `reason`, and `version` labels. A Prometheus alert is created when this metric is present. - -|`csv_count` -|Number of CSVs successfully registered. - -|`csv_succeeded` -|When reconciling a CSV, represents whether a CSV version is in a `Succeeded` state (value `1`) or not (value `0`). Includes the `name`, `namespace`, and `version` labels. - -|`csv_upgrade_count` -|Monotonic count of CSV upgrades. - -|`install_plan_count` -|Number of install plans. - -|`subscription_count` -|Number of subscriptions. - -|`subscription_sync_total` -|Monotonic count of subscription syncs. Includes the `channel`, `installed` CSV, and subscription `name` labels. - -|=== diff --git a/modules/olm-mirroring-catalog.adoc b/modules/olm-mirroring-catalog.adoc deleted file mode 100644 index 1ae60680c008..000000000000 --- a/modules/olm-mirroring-catalog.adoc +++ /dev/null @@ -1,199 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-restricted-networks.adoc -// * migration/migrating_3_4/deploying-cam-3-4.adoc -// * migration/migrating_4_1_4/deploying-cam-4-1-4.adoc -// * migration/migrating_4_2_4/deploying-cam-4-2-4.adoc - -ifdef::openshift-origin[] -:index-image-pullspec: quay.io/operatorhubio/catalog:latest -:index-image: catalog -:example-registry: example.com -endif::[] -ifndef::openshift-origin[] -:index-image-pullspec: registry.redhat.io/redhat/redhat-operator-index:v{product-version} -:index-image: redhat-operator-index -:example-registry: registry.redhat.io -endif::[] - -[id="olm-mirror-catalog_{context}"] -= Mirroring an Operator catalog - -You can mirror the Operator content of a Red Hat-provided catalog, or a custom catalog, into a container image registry using the `oc adm catalog mirror` command. The target registry must support link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2]. For a cluster on a restricted network, this registry can be one that the cluster has network access to, such as a mirror registry created during a restricted network cluster installation. - -The `oc adm catalog mirror` command also automatically mirrors the index image that is specified during the mirroring process, whether it be a Red Hat-provided index image or your own custom-built index image, to the target registry. You can then use the mirrored index image to create a catalog source that allows Operator Lifecycle Manager (OLM) to load the mirrored catalog onto your {product-title} cluster. - -.Prerequisites - -* Workstation with unrestricted network access. -* `podman` version 1.9.3 or later. -* Access to mirror registry that supports -link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2]. -* Decide which namespace on your mirror registry you will use to store the mirrored Operator content. For example, you might create an `olm-mirror` namespace. -* If your mirror registry does not have Internet access, connect removable media to your workstation with unrestricted network access. -* If you are working with private registries, set the `REG_CREDS` environment variable to the file path of your registry credentials for use in later steps. For example, for the `podman` CLI: -+ -[source,terminal] ----- -$ REG_CREDS=${XDG_RUNTIME_DIR}/containers/auth.json ----- - -.Procedure - -ifndef::openshift-origin[] -. If you want to mirror a Red Hat-provided catalog, run the following command on your workstation with unrestricted network access to authenticate with `registry.redhat.io`: -+ -[source,terminal] ----- -$ podman login registry.redhat.io ----- -endif::[] - -. The `oc adm catalog mirror` command extracts the contents of an index image to generate the manifests required for mirroring. The default behavior of the command generates manifests, then automatically mirrors all of the image content from the index image, as well as the index image itself, to your mirror registry. Alternatively, if your mirror registry is on a completely disconnected, or _airgapped_, host, you can first mirror the content to removable media, move the media to the disconnected environment, then mirror the content from the media to the registry. - -** *Option A: If your mirror registry is on the same network* as your workstation with unrestricted network access, take the following actions on your workstation: - -.. If your mirror registry requires authentication, run the following command to log in to the registry: -+ -[source,terminal] ----- -$ podman login <mirror_registry> ----- - -.. Run the following command to mirror the content: -+ -[source,terminal] ----- -$ oc adm catalog mirror \ - <index_image> \//<1> - <mirror_registry>:<port>/<namespace> \//<2> - [-a ${REG_CREDS}] \//<3> - [--insecure] \//<4> - [--index-filter-by-os='<platform>/<arch>'] \//<5> - [--manifests-only] <6> ----- -<1> Specify the index image for the catalog you want to mirror. For example, this might be a pruned index image that you created previously, or one of the source index images for the default catalogs, such as `{index-image-pullspec}`. -<2> Specify the target registry and namespace to mirror the Operator content to, where `<namespace>` is any existing namespace on the registry. For example, you might create an `olm-mirror` namespace to push all mirrored content to. -<3> Optional: If required, specify the location of your registry credentials file. -<4> Optional: If you do not want to configure trust for the target registry, add the `--insecure` flag. -<5> Optional: Specify which platform and architecture of the index image to select when multiple variants are available. Images are passed as `'<platform>/<arch>[/<variant>]'`. This does not apply to images referenced by the index. Valid values are `linux/amd64`, `linux/ppc64le`, and `linux/s390x`. -<6> Optional: Generate only the manifests required for mirroring, and do not actually mirror the image content to a registry. This option can be useful for reviewing what will be mirrored, and it allows you to make any changes to the mapping list if you require only a subset of packages. You can then use the `mapping.txt` file with the `oc image mirror` command to mirror the modified list of images in a later step. This flag is intended for only advanced selective mirroring of content from the catalog; the `opm index prune` command, if you used it previously to prune the index image, is suitable for most catalog management use cases. -+ -.Example output -[source,terminal,subs="attributes+"] ----- -src image has index label for database path: /database/index.db -using database path mapping: /database/index.db:/tmp/153048078 -wrote database to /tmp/153048078 <1> -... -wrote mirroring manifests to manifests-{index-image}-1614211642 <2> ----- -<1> Directory for the temporary `index.db` database generated by the command. -<2> Record the manifests directory name that is generated. This directory name is used in a later step. - -** *Option B: If your mirror registry is on a disconnected host,* take the following actions. - -.. Run the following command on your workstation with unrestricted network access to mirror the content to local files: -+ -[source,terminal] ----- -$ oc adm catalog mirror \ - <index_image> \//<1> - file:///local/index \//<2> - [-a ${REG_CREDS}] \ - [--insecure] ----- -<1> Specify the index image for the catalog you want to mirror. For example, this might be a pruned index image that you created previously, or one of the source index images for the default catalogs, such as `{index-image-pullspec}`. -<2> Mirrors content to local files in your current directory. -+ -.Example output -[source,terminal] ----- -... -info: Mirroring completed in 5.93s (5.915MB/s) -wrote mirroring manifests to manifests-my-index-1614985528 <1> - -To upload local images to a registry, run: - - oc adm catalog mirror file://local/index/myrepo/my-index:v1 REGISTRY/REPOSITORY <2> ----- -<1> Record the manifests directory name that is generated. This directory name is used in a later step. -<2> Record the expanded `file://` path that based on your provided index image. This path is used in a later step. - -.. Copy the `v2/` directory that is generated in your current directory to removable media. - -.. Physically remove the media and attach it to a host in the disconnected environment that has access to the mirror registry. - -.. If your mirror registry requires authentication, run the following command on your host in the disconnected environment to log in to the registry: -+ -[source,terminal] ----- -$ podman login <mirror_registry> ----- - -.. Run the following command from the parent directory containing the `v2/` directory to upload the images from local files to the mirror registry: -+ -[source,terminal] ----- -$ oc adm catalog mirror \ - file://local/index/<repo>/<index_image>:<tag> \//<1> - <mirror_registry>:<port>/<namespace> \//<2> - [-a ${REG_CREDS}] \ - [--insecure] ----- -<1> Specify the `file://` path from the previous command output. -<2> Specify the target registry and namespace to mirror the Operator content to, where `<namespace>` is any existing namespace on the registry. For example, you might create an `olm-mirror` namespace to push all mirrored content to. - -. After mirroring the content to your registry, inspect the manifests directory that is generated in your current directory. -+ -[NOTE] -==== -The manifests directory name is used in a later step. -==== -+ -If you mirrored content to a registry on the same network in the previous step, the directory name takes the following form: -+ -[source,text] ----- -manifests-<index_image_name>-<random_number> ----- -+ -If you mirrored content to a registry on a disconnected host in the previous step, the directory name takes the following form: -+ -[source,text] ----- -manifests-index/<namespace>/<index_image_name>-<random_number> ----- -+ -The manifests directory contains the following files, some of which might require further modification: -+ --- -* The `catalogSource.yaml` file is a basic definition for a `CatalogSource` object that is pre-populated with your index image tag and other relevant metadata. This file can be used as is or modified to add the catalog source to your cluster. -+ -[IMPORTANT] -==== -If you mirrored the content to local files, you must modify your `catalogSource.yaml` file to remove any backslash (`/`) characters from the `metadata.name` field. Otherwise, when you attempt to create the object, it fails with an "invalid resource name" error. -==== -* The `imageContentSourcePolicy.yaml` file defines an `ImageContentSourcePolicy` object that can configure nodes to translate between the image references stored in Operator manifests and the mirrored registry. -* The `mapping.txt` file contains all of the source images and where to map them in the target registry. This file is compatible with the `oc image mirror` command and can be used to further customize the mirroring configuration. -+ -[IMPORTANT] -==== -If you used the `--manifests-only` flag during the mirroring process and want to further trim the subset of packages to be mirrored, see the steps in the "Mirroring a Package Manifest Format catalog image" procedure about modifying your `mapping.txt` file and using the file with the `oc image mirror` command. After following those further actions, you can continue this procedure. -==== --- - -. On a host with access to the disconnected cluster, create the `ImageContentSourcePolicy` object by running the following command to specify the `imageContentSourcePolicy.yaml` file in your manifests directory: -+ -[source,terminal,subs="attributes+"] ----- -$ oc create -f <path/to/manifests/dir>/imageContentSourcePolicy.yaml ----- -+ -where `<path/to/manifests/dir>` is the path to the manifests directory for your mirrored content. - -You can now create a `CatalogSource` object to reference your mirrored index image and Operator content. - -:!index-image-pullspec: -:!index-image: -:!example-registry: diff --git a/modules/olm-mirroring-package-manifest-catalog.adoc b/modules/olm-mirroring-package-manifest-catalog.adoc deleted file mode 100644 index ebb0f77fb631..000000000000 --- a/modules/olm-mirroring-package-manifest-catalog.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc - -[id="olm-mirroring-package-manifest-catalog_{context}"] -= Mirroring a Package Manifest Format catalog image - -Cluster administrators can mirror a custom Operator catalog image based on the Package Manifest Format into a registry and use a catalog source to load the content onto their cluster. For this example, the procedure uses a custom `redhat-operators` catalog image previously built and pushed to a supported registry. - -.Prerequisites - -* Workstation with unrestricted network access -* A custom Operator catalog image based on the Package Manifest Format pushed to a supported registry -* `oc` version 4.3.5+ -* `podman` version 1.9.3+ -* Access to mirror registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] -* If you are working with private registries, set the `REG_CREDS` environment variable to the file path of your registry credentials for use in later steps. For example, for the `podman` CLI: -+ -[source,terminal] ----- -$ REG_CREDS=${XDG_RUNTIME_DIR}/containers/auth.json ----- - -.Procedure - -. The `oc adm catalog mirror` command extracts the contents of your custom Operator catalog image to generate the manifests required for mirroring. You can choose to either: -+ --- -* Allow the default behavior of the command to automatically mirror all of the image content to your mirror registry after generating manifests, or -* Add the `--manifests-only` flag to only generate the manifests required for mirroring, but do not actually mirror the image content to a registry yet. This can be useful for reviewing what will be mirrored, and it allows you to make any changes to the mapping list if you only require a subset of the content. You can then use that file with the `oc image mirror` command to mirror the modified list of images in a later step. --- -+ -On your workstation with unrestricted network access, run the following command: -+ -[source,terminal] ----- -$ oc adm catalog mirror \ - <registry_host_name>:<port>/olm/redhat-operators:v1 \//<1> - <registry_host_name>:<port> \ - [-a ${REG_CREDS}] \//<2> - [--insecure] \//<3> - [--index-filter-by-os='<platform>/<arch>'] \//<4> - [--manifests-only] <5> ----- -<1> Specify your Operator catalog image. -<2> Optional: If required, specify the location of your registry credentials file. -<3> Optional: If you do not want to configure trust for the target registry, add the `--insecure` flag. -<4> Optional: Specify which platform and architecture of the catalog image to select when multiple variants are available. Images are passed as `'<platform>/<arch>[/<variant>]'`. This does not apply to images referenced by the catalog image. Valid values are `linux/amd64`, `linux/ppc64le`, and `linux/s390x`. -<5> Optional: Only generate the manifests required for mirroring and do not actually mirror the image content to a registry. -+ -.Example output -[source,terminal] ----- -using database path mapping: /:/tmp/190214037 -wrote database to /tmp/190214037 -using database at: /tmp/190214037/bundles.db <1> -... ----- -<1> Temporary database generated by the command. -+ -After running the command, a `manifests-<index_image_name>-<random_number>/` directory is created in the current directory and generates the following files: -+ --- -* The `catalogSource.yaml` file is a basic definition for a `CatalogSource` object that is pre-populated with your catalog image tag and other relevant metadata. This file can be used as is or modified to add the catalog source to your cluster. -* The `imageContentSourcePolicy.yaml` file defines an `ImageContentSourcePolicy` object that can configure nodes to translate between the image references stored in Operator manifests and the mirrored registry. -* The `mapping.txt` file contains all of the source images and where to map them in the target registry. This file is compatible with the `oc image mirror` command and can be used to further customize the mirroring configuration. --- - -. If you used the `--manifests-only` flag in the previous step and want to mirror only a subset of the content: - -.. Modify the list of images in your `mapping.txt` file to your specifications. If you are unsure of the exact names and versions of the subset of images you want to mirror, use the following steps to find them: - -... Run the `sqlite3` tool against the temporary database that was generated by the `oc adm catalog mirror` command to retrieve a list of images matching a general search query. The output helps inform how you will later edit your `mapping.txt` file. -+ -For example, to retrieve a list of images that are similar to the string `clusterlogging.4.3`: -+ -[source,terminal] ----- -$ echo "select * from related_image \ - where operatorbundle_name like 'clusterlogging.4.3%';" \ - | sqlite3 -line /tmp/190214037/bundles.db <1> ----- -<1> Refer to the previous output of the `oc adm catalog mirror` command to find the path of the database file. -+ -.Example output -[source,terminal] ----- -image = registry.redhat.io/openshift-logging/kibana6-rhel8@sha256:aa4a8b2a00836d0e28aa6497ad90a3c116f135f382d8211e3c55f34fb36dfe61 -operatorbundle_name = clusterlogging.4.3.33-202008111029.p0 - -image = registry.redhat.io/openshift4/ose-oauth-proxy@sha256:6b4db07f6e6c962fc96473d86c44532c93b146bbefe311d0c348117bf759c506 -operatorbundle_name = clusterlogging.4.3.33-202008111029.p0 -... ----- - -... Use the results from the previous step to edit the `mapping.txt` file to only include the subset of images you want to mirror. -+ -For example, you can use the `image` values from the previous example output to find that the following matching lines exist in your `mapping.txt` file: -+ -.Matching image mappings in `mapping.txt` -[source,txt] ----- -registry.redhat.io/openshift-logging/kibana6-rhel8@sha256:aa4a8b2a00836d0e28aa6497ad90a3c116f135f382d8211e3c55f34fb36dfe61=<registry_host_name>:<port>/kibana6-rhel8:a767c8f0 -registry.redhat.io/openshift4/ose-oauth-proxy@sha256:6b4db07f6e6c962fc96473d86c44532c93b146bbefe311d0c348117bf759c506=<registry_host_name>:<port>/openshift4-ose-oauth-proxy:3754ea2b ----- -+ -In this example, if you only want to mirror these images, you would then remove all other entries in the `mapping.txt` file and leave only the above two lines. - -.. Still on your workstation with unrestricted network access, use your modified `mapping.txt` file to mirror the images to your registry using the `oc image mirror` command: -+ -[source,terminal] ----- -$ oc image mirror \ - [-a ${REG_CREDS}] \ - -f ./manifests-redhat-operators-<random_number>/mapping.txt ----- - -. Create the `ImageContentSourcePolicy` object: -+ -[source,terminal] ----- -$ oc create -f ./manifests-redhat-operators-<random_number>/imageContentSourcePolicy.yaml ----- - -You can now create a `CatalogSource` object to reference your mirrored content. diff --git a/modules/olm-operator-framework.adoc b/modules/olm-operator-framework.adoc deleted file mode 100644 index 4c2bb19d18c8..000000000000 --- a/modules/olm-operator-framework.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm-what-operators-are.adoc - -[id="olm-operator-framework_{context}"] -= Operator Framework - -The Operator Framework is a family of tools and capabilities to deliver on the customer experience described above. It is not just about writing code; testing, delivering, and updating Operators is just as important. The Operator Framework components consist of open source tools to tackle these problems: - -Operator SDK:: -The Operator SDK assists Operator authors in bootstrapping, building, testing, and packaging their own Operator based on their expertise without requiring knowledge of Kubernetes API complexities. - -Operator Lifecycle Manager:: -Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. Deployed by default in {product-title} {product-version}. - -Operator Registry:: -The Operator Registry stores cluster service versions (CSVs) and custom resource definitions (CRDs) for creation in a cluster and stores Operator metadata about packages and channels. It runs in a Kubernetes or OpenShift cluster to provide this Operator catalog data to OLM. - -OperatorHub:: -OperatorHub is a web console for cluster administrators to discover and select Operators to install on their cluster. It is deployed by default in {product-title}. - -Operator Metering:: -Operator Metering collects operational metrics about Operators on the cluster for Day 2 management and aggregating usage metrics. - -These tools are designed to be composable, so you can use any that are useful to you. diff --git a/modules/olm-operator-maturity-model.adoc b/modules/olm-operator-maturity-model.adoc deleted file mode 100644 index 8309c4fbc0bb..000000000000 --- a/modules/olm-operator-maturity-model.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm-what-operators-are.adoc - -[id="olm-maturity-model_{context}"] -= Operator maturity model - -The level of sophistication of the management logic encapsulated within an Operator can vary. This logic is also in general highly dependent on the type of the service represented by the Operator. - -One can however generalize the scale of the maturity of the encapsulated operations of an Operator for certain set of capabilities that most Operators can include. To this end, the following Operator maturity model defines five phases of maturity for generic day two operations of an Operator: - -.Operator maturity model -image::operator-maturity-model.png[] - -The above model also shows how these capabilities can best be developed through -the Helm, Go, and Ansible capabilities of the Operator SDK. diff --git a/modules/olm-operatorconditions-about.adoc b/modules/olm-operatorconditions-about.adoc deleted file mode 100644 index 847e6f885fd8..000000000000 --- a/modules/olm-operatorconditions-about.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc -// * operators/understanding/olm/olm-operatorconditions.adoc - -[id="olm-about-operatorconditions_{context}"] -ifeval::["{context}" == "olm-understanding-olm"] -= Operator conditions -endif::[] -ifeval::["{context}" != "olm-understanding-olm"] -= About Operator conditions -endif::[] - -As part of its role in managing the lifecycle of an Operator, Operator Lifecycle Manager (OLM) infers the state of an Operator from the state of Kubernetes resources that define the Operator. While this approach provides some level of assurance that an Operator is in a given state, there are many instances where an Operator might need to communicate information to OLM that could not be inferred otherwise. This information can then be used by OLM to better manage the lifecycle of the Operator. - -OLM provides a custom resource definition (CRD) called `OperatorCondition` that allows Operators to communicate conditions to OLM. There are a set of supported conditions that influence management of the Operator by OLM when present in the `Status.Conditions` array of an `OperatorCondition` resource. diff --git a/modules/olm-operatorgroups-about.adoc b/modules/olm-operatorgroups-about.adoc deleted file mode 100644 index 3e48d9484f4c..000000000000 --- a/modules/olm-operatorgroups-about.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-about_{context}"] -ifeval::["{context}" == "olm-understanding-olm"] -= Operator groups -endif::[] -ifeval::["{context}" != "olm-understanding-olm"] -= About Operator groups -endif::[] - -An _Operator group_, defined by the `OperatorGroup` resource, provides multitenant configuration to OLM-installed Operators. An Operator group selects target namespaces in which to generate required RBAC access for its member Operators. - -The set of target namespaces is provided by a comma-delimited string stored in the `olm.targetNamespaces` annotation of a cluster service version (CSV). This annotation is applied to the CSV instances of member Operators and is projected into their deployments. diff --git a/modules/olm-operatorgroups-copied-csvs.adoc b/modules/olm-operatorgroups-copied-csvs.adoc deleted file mode 100644 index b756cdb803bf..000000000000 --- a/modules/olm-operatorgroups-copied-csvs.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-copied-csvs_{context}"] -= Copied CSVs - -OLM creates copies of all active member CSVs of an Operator group in each of the target namespaces of that Operator group. The purpose of a copied CSV is to tell users of a target namespace that a specific Operator is configured to watch resources created there. - -Copied CSVs have a status reason `Copied` and are updated to match the status of their source CSV. The `olm.targetNamespaces` annotation is stripped from copied CSVs before they are created on the cluster. Omitting the target namespace selection avoids the duplication of target namespaces between tenants. - -Copied CSVs are deleted when their source CSV no longer exists or the Operator group that their source CSV belongs to no longer targets the namespace of the copied CSV. diff --git a/modules/olm-operatorgroups-csv-annotations.adoc b/modules/olm-operatorgroups-csv-annotations.adoc deleted file mode 100644 index 69af98113ccd..000000000000 --- a/modules/olm-operatorgroups-csv-annotations.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-csv-annotations_{context}"] -= Operator group CSV annotations - -Member CSVs of an Operator group have the following annotations: - -[cols="1,1",options="header"] -|=== -|Annotation |Description - -|`olm.operatorGroup=<group_name>` -|Contains the name of the Operator group. - -|`olm.operatorGroupNamespace=<group_namespace>` -|Contains the namespace of the Operator group. - -|`olm.targetNamespaces=<target_namespaces>` -|Contains a comma-delimited string that lists the target namespace selection of the Operator group. -|=== - -[NOTE] -==== -All annotations except `olm.targetNamespaces` are included with copied CSVs. Omitting the `olm.targetNamespaces` annotation on copied CSVs prevents the duplication of target namespaces between tenants. -==== diff --git a/modules/olm-operatorgroups-intersections.adoc b/modules/olm-operatorgroups-intersections.adoc deleted file mode 100644 index a3859b2a6bde..000000000000 --- a/modules/olm-operatorgroups-intersections.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-intersection_{context}"] -= Operator group intersection - -Two Operator groups are said to have _intersecting provided APIs_ if the intersection of their target namespace sets is not an empty set and the intersection of their provided API sets, defined by `olm.providedAPIs` annotations, is not an empty set. - -A potential issue is that Operator groups with intersecting provided APIs can compete for the same resources in the set of intersecting namespaces. - -[NOTE] -==== -When checking intersection rules, an Operator group namespace is always included as part of its selected target namespaces. -==== - -[discrete] -[id="olm-operatorgroups-intersection-rules_{context}"] -=== Rules for intersection - -Each time an active member CSV synchronizes, OLM queries the cluster for the set of intersecting provided APIs between the Operator group of the CSV and all others. OLM then checks if that set is an empty set: - -* If `true` and the CSV's provided APIs are a subset of the Operator group's: -** Continue transitioning. -* If `true` and the CSV's provided APIs are _not_ a subset of the Operator group's: -** If the Operator group is static: -*** Clean up any deployments that belong to the CSV. -*** Transition the CSV to a failed state with status reason -`CannotModifyStaticOperatorGroupProvidedAPIs`. -** If the Operator group is _not_ static: -*** Replace the Operator group's `olm.providedAPIs` annotation with the union of itself and the CSV's provided APIs. -* If `false` and the CSV's provided APIs are _not_ a subset of the Operator group's: -** Clean up any deployments that belong to the CSV. -** Transition the CSV to a failed state with status reason `InterOperatorGroupOwnerConflict`. -* If `false` and the CSV's provided APIs are a subset of the Operator group's: -** If the Operator group is static: -*** Clean up any deployments that belong to the CSV. -*** Transition the CSV to a failed state with status reason `CannotModifyStaticOperatorGroupProvidedAPIs`. -** If the Operator group is _not_ static: -*** Replace the Operator group's `olm.providedAPIs` annotation with the difference between itself and the CSV's provided APIs. - -[NOTE] -==== -Failure states caused by Operator groups are non-terminal. -==== - -The following actions are performed each time an Operator group synchronizes: - -* The set of provided APIs from active member CSVs is calculated from the cluster. Note that copied CSVs are ignored. -* The cluster set is compared to `olm.providedAPIs`, and if `olm.providedAPIs` contains any extra APIs, then those APIs are pruned. -* All CSVs that provide the same APIs across all namespaces are requeued. This notifies conflicting CSVs in intersecting groups that their conflict has possibly been resolved, either through resizing or through deletion of the conflicting CSV. diff --git a/modules/olm-operatorgroups-membership.adoc b/modules/olm-operatorgroups-membership.adoc deleted file mode 100644 index 8246b9643801..000000000000 --- a/modules/olm-operatorgroups-membership.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-membership_{context}"] -= Operator group membership - -An Operator is considered a _member_ of an Operator group if the following conditions are true: - -* The CSV of the Operator exists in the same namespace as the Operator group. -* The install modes in the CSV of the Operator support the set of namespaces targeted by the Operator group. - -An install mode in a CSV consists of an `InstallModeType` field and a boolean `Supported` field. The spec of a CSV can contain a set of install modes of four distinct `InstallModeTypes`: - -.Install modes and supported Operator groups -[cols="1,2",options="header"] -|=== -|InstallModeType |Description - -|`OwnNamespace` -|The Operator can be a member of an Operator group that selects its own namespace. - -|`SingleNamespace` -|The Operator can be a member of an Operator group that selects one namespace. - -|`MultiNamespace` -|The Operator can be a member of an Operator group that selects more than one namespace. - -|`AllNamespaces` -|The Operator can be a member of an Operator group that selects all namespaces (target namespace set is the empty string `""`). -|=== - -[NOTE] -==== -If the spec of a CSV omits an entry of `InstallModeType`, then that type is considered unsupported unless support can be inferred by an existing entry that implicitly supports it. -==== diff --git a/modules/olm-operatorgroups-provided-apis-annotations.adoc b/modules/olm-operatorgroups-provided-apis-annotations.adoc deleted file mode 100644 index eb3ec36b6295..000000000000 --- a/modules/olm-operatorgroups-provided-apis-annotations.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-provided-apis-annotation_{context}"] -= Provided APIs annotation - -A _group/version/kind (GVK)_ is a unique identifier for a Kubernetes API. Information about what GVKs are provided by an Operator group are shown in an `olm.providedAPIs` annotation. The value of the annotation is a string consisting of `<kind>.<version>.<group>` delimited with commas. The GVKs of CRDs and API services provided by all active member CSVs of an Operator group are included. - -Review the following example of an `OperatorGroup` object with a single active member CSV that provides the `PackageManifest` resource: - -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - annotations: - olm.providedAPIs: PackageManifest.v1alpha1.packages.apps.redhat.com - name: olm-operators - namespace: local - ... -spec: - selector: {} - serviceAccount: - metadata: - creationTimestamp: null - targetNamespaces: - - local -status: - lastUpdated: 2019-02-19T16:18:28Z - namespaces: - - local ----- diff --git a/modules/olm-operatorgroups-rbac.adoc b/modules/olm-operatorgroups-rbac.adoc deleted file mode 100644 index 632417d666fb..000000000000 --- a/modules/olm-operatorgroups-rbac.adoc +++ /dev/null @@ -1,129 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-rbac_{context}"] -= Role-based access control - -When an Operator group is created, three cluster roles are generated. Each contains a single aggregation rule with a cluster role selector set to match a label, as shown below: - -[cols="1,1",options="header"] -|=== -|Cluster role |Label to match - -|`<operatorgroup_name>-admin` -|`olm.opgroup.permissions/aggregate-to-admin: <operatorgroup_name>` - -|`<operatorgroup_name>-edit` -|`olm.opgroup.permissions/aggregate-to-edit: <operatorgroup_name>` - -|`<operatorgroup_name>-view` -|`olm.opgroup.permissions/aggregate-to-view: <operatorgroup_name>` -|=== - -The following RBAC resources are generated when a CSV becomes an active member of an Operator group, as long as the CSV is watching all namespaces with the `AllNamespaces` install mode and is not in a failed state with reason `InterOperatorGroupOwnerConflict`: - -* Cluster roles for each API resource from a CRD -* Cluster roles for each API resource from an API service -* Additional roles and role bindings - -[id="olm-resources-per-api-resource-crd_{context}"] -.Cluster roles generated for each API resource from a CRD -[cols="1,1a",options="header"] -|=== -|Cluster role |Settings - -|`<kind>.<group>-<version>-admin` -|Verbs on `<kind>`: - -* `*` - -Aggregation labels: - -* `rbac.authorization.k8s.io/aggregate-to-admin: true` -* `olm.opgroup.permissions/aggregate-to-admin: <operatorgroup_name>` - -|`<kind>.<group>-<version>-edit` -|Verbs on `<kind>`: - -* `create` -* `update` -* `patch` -* `delete` - -Aggregation labels: - -* `rbac.authorization.k8s.io/aggregate-to-edit: true` -* `olm.opgroup.permissions/aggregate-to-edit: <operatorgroup_name>` - -|`<kind>.<group>-<version>-view` -|Verbs on `<kind>`: - -* `get` -* `list` -* `watch` - -Aggregation labels: - -* `rbac.authorization.k8s.io/aggregate-to-view: true` -* `olm.opgroup.permissions/aggregate-to-view: <operatorgroup_name>` - -|`<kind>.<group>-<version>-view-crdview` -|Verbs on `apiextensions.k8s.io` `customresourcedefinitions` `<crd-name>`: - -* `get` - -Aggregation labels: - -* `rbac.authorization.k8s.io/aggregate-to-view: true` -* `olm.opgroup.permissions/aggregate-to-view: <operatorgroup_name>` - -|=== - -[id="olm-resources-per-api-resource-api_{context}"] -.Cluster roles generated for each API resource from an API service -[cols="1,1a",options="header"] -|=== -|Cluster role |Settings - -|`<kind>.<group>-<version>-admin` -|Verbs on `<kind>`: - -* `*` - -Aggregation labels: - -* `rbac.authorization.k8s.io/aggregate-to-admin: true` -* `olm.opgroup.permissions/aggregate-to-admin: <operatorgroup_name>` - -|`<kind>.<group>-<version>-edit` -|Verbs on `<kind>`: - -* `create` -* `update` -* `patch` -* `delete` - -Aggregation labels: - - * `rbac.authorization.k8s.io/aggregate-to-edit: true` - * `olm.opgroup.permissions/aggregate-to-edit: <operatorgroup_name>` - -|`<kind>.<group>-<version>-view` -|Verbs on `<kind>`: - -* `get` -* `list` -* `watch` - -Aggregation labels: - -* `rbac.authorization.k8s.io/aggregate-to-view: true` -* `olm.opgroup.permissions/aggregate-to-view: <operatorgroup_name>` - -|=== - -[id="olm-resources-additional-roles-rolebindings_{context}"] -.Additional roles and role bindings -* If the CSV defines exactly one target namespace that contains `*`, then a cluster role and corresponding cluster role binding are generated for each permission defined in the `permissions` field of the CSV. All resources generated are given the `olm.owner: <csv_name>` and `olm.owner.namespace: <csv_namespace>` labels. -* If the CSV does _not_ define exactly one target namespace that contains `*`, then all roles and role bindings in the Operator namespace with the `olm.owner: <csv_name>` and `olm.owner.namespace: <csv_namespace>` labels are copied into the target namespace. diff --git a/modules/olm-operatorgroups-static.adoc b/modules/olm-operatorgroups-static.adoc deleted file mode 100644 index 46a1e72b46a9..000000000000 --- a/modules/olm-operatorgroups-static.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-static_{context}"] -= Static Operator groups - -An Operator group is _static_ if its `spec.staticProvidedAPIs` field is set to `true`. As a result, OLM does not modify the `olm.providedAPIs` annotation of an Operator group, which means that it can be set in advance. This is useful when a user wants to use an Operator group to prevent resource contention in a set of namespaces but does not have active member CSVs that provide the APIs for those resources. - -Below is an example of an Operator group that protects `Prometheus` resources in all namespaces with the `something.cool.io/cluster-monitoring: "true"` annotation: - -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: cluster-monitoring - namespace: cluster-monitoring - annotations: - olm.providedAPIs: Alertmanager.v1.monitoring.coreos.com,Prometheus.v1.monitoring.coreos.com,PrometheusRule.v1.monitoring.coreos.com,ServiceMonitor.v1.monitoring.coreos.com -spec: - staticProvidedAPIs: true - selector: - matchLabels: - something.cool.io/cluster-monitoring: "true" ----- diff --git a/modules/olm-operatorgroups-target-namespace.adoc b/modules/olm-operatorgroups-target-namespace.adoc deleted file mode 100644 index bef8ff5aafe1..000000000000 --- a/modules/olm-operatorgroups-target-namespace.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-target-namespace_{context}"] -= Target namespace selection - -You can explicitly name the target namespace for an Operator group using the `spec.targetNamespaces` parameter: - -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: my-group - namespace: my-namespace -spec: - targetNamespaces: - - my-namespace ----- - -You can alternatively specify a namespace using a label selector with the `spec.selector` parameter: - -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: my-group - namespace: my-namespace -spec: - selector: - cool.io/prod: "true" ----- - -[IMPORTANT] -==== -Listing multiple namespaces via `spec.targetNamespaces` or use of a label selector via `spec.selector` is not recommended, as the support for more than one target namespace in an Operator group will likely be removed in a future release. -==== - -If both `spec.targetNamespaces` and `spec.selector` are defined, `spec.selector` is ignored. Alternatively, you can omit both `spec.selector` and `spec.targetNamespaces` to specify a _global_ Operator group, which selects all namespaces: - -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: my-group - namespace: my-namespace ----- - -The resolved set of selected namespaces is shown in the `status.namespaces` parameter of an Opeator group. The `status.namespace` of a global Operator group contains the empty string (`""`), which signals to a consuming Operator that it should watch all namespaces. diff --git a/modules/olm-operatorgroups-troubleshooting.adoc b/modules/olm-operatorgroups-troubleshooting.adoc deleted file mode 100644 index 7f901906e517..000000000000 --- a/modules/olm-operatorgroups-troubleshooting.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-operatorgroups.adoc - -[id="olm-operatorgroups-troubleshooting_{context}"] -= Troubleshooting Operator groups - -[discrete] -[id="olm-operatorgroups-troubleshooting-membership_{context}"] -=== Membership - -* If more than one Operator group exists in a single namespace, any CSV created in that namespace transitions to a failure state with the reason `TooManyOperatorGroups`. CSVs in a failed state for this reason transition to pending after the number of Operator groups in their namespaces reaches one. -* If the install modes of a CSV do not support the target namespace selection of the Operator group in its namespace, the CSV transitions to a failure state with the reason `UnsupportedOperatorGroup`. CSVs in a failed state for this reason transition to pending after either the target namespace selection of the Operator group changes to a supported configuration, or the install modes of the CSV are modified to support the target namespace selection. diff --git a/modules/olm-operatorhub-architecture.adoc b/modules/olm-operatorhub-architecture.adoc deleted file mode 100644 index bdd718001359..000000000000 --- a/modules/olm-operatorhub-architecture.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm-understanding-operatorhub.adoc - -[id="olm-operatorhub-arch_{context}"] -= OperatorHub architecture - -The OperatorHub UI component is driven by the Marketplace Operator by default on {product-title} in the `openshift-marketplace` namespace. - -[id="olm-operatorhub-arch-operatorhub_crd_{context}"] -== OperatorHub custom resource - -The Marketplace Operator manages an `OperatorHub` custom resource (CR) named `cluster` that manages the default `CatalogSource` objects provided with OperatorHub. You can modify this resource to enable or disable the default catalogs, which is useful when configuring {product-title} in restricted network environments. - -.Example `OperatorHub` custom resource -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: OperatorHub -metadata: - name: cluster -spec: - disableAllDefaultSources: true <1> - sources: [ <2> - { - name: "community-operators", - disabled: false - } - ] ----- -<1> `disableAllDefaultSources` is an override that controls availability of all default catalogs that are configured by default during an {product-title} installation. -<2> Disable default catalogs individually by changing the `disabled` parameter value per source. diff --git a/modules/olm-operatorhub-overview.adoc b/modules/olm-operatorhub-overview.adoc deleted file mode 100644 index f4e67e7ec810..000000000000 --- a/modules/olm-operatorhub-overview.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm-understanding-operatorhub.adoc - -[id="olm-operatorhub-overview_{context}"] -= About OperatorHub - -_OperatorHub_ is the web console interface in {product-title} that cluster administrators use to discover and install Operators. With one click, an Operator can be pulled from its off-cluster source, installed and subscribed on the cluster, and made ready for engineering teams to self-service manage the product across deployment environments using Operator Lifecycle Manager (OLM). - -ifndef::openshift-origin[] -Cluster administrators can choose from catalogs grouped into the following categories: - -[cols="2a,8a",options="header"] -|=== -|Category |Description - -|Red Hat Operators -|Red Hat products packaged and shipped by Red Hat. Supported by Red Hat. - -|Certified Operators -|Products from leading independent software vendors (ISVs). Red Hat partners with ISVs to package and ship. Supported by the ISV. - -|Red Hat Marketplace -|Certified software that can be purchased from link:https://marketplace.redhat.com/[Red Hat Marketplace]. - -|Community Operators -|Optionally-visible software maintained by relevant representatives in the link:https://github.com/operator-framework/community-operators[operator-framework/community-operators] GitHub repository. No official support. - -|Custom Operators -|Operators you add to the cluster yourself. If you have not added any custom Operators, the *Custom* category does not appear in the web console on your OperatorHub. -|=== -endif::[] - -Operators on OperatorHub are packaged to run on OLM. This includes a YAML file called a cluster service version (CSV) containing all of the CRDs, RBAC rules, deployments, and container images required to install and securely run the Operator. It also contains user-visible information like a description of its features and supported Kubernetes versions. - -The Operator SDK can be used to assist developers packaging their Operators for use on OLM and OperatorHub. If you have a commercial application that you want to make accessible to your customers, get it included using the certification workflow provided on the Red Hat Partner Connect portal at link:https://connect.redhat.com[connect.redhat.com]. diff --git a/modules/olm-overriding-operatorconditions.adoc b/modules/olm-overriding-operatorconditions.adoc deleted file mode 100644 index aa2f32c0e37e..000000000000 --- a/modules/olm-overriding-operatorconditions.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-operatorconditions.adoc - -[id="olm-supported-operatorconditions_{context}"] -= Overriding Operator conditions - -As a cluster administrator, you might want to ignore a supported Operator condition reported by an Operator. When present, Operator conditions in the `Spec.Overrides` array override the conditions in the `Status.Conditions` array, allowing cluster administrators to deal with situations where an Operator is incorrectly reporting a state to Operator Lifecycle Manager (OLM). - -For example, consider a known version of an Operator that always communicates that it is not upgradeable. In this instance, you might want to upgrade the Operator despite the Operator communicating that it is not upgradeable. This could be accomplished by overriding the Operator condition by adding the condition `type` and `status` to the `Spec.Overrides` array in the `OperatorCondition` resource. - -.Prerequisites - -* An Operator with an `OperatorCondition` resource, installed using OLM. - -.Procedure - -. Edit the `OperatorCondition` resource for the Operator: -+ -[source,terminal] ----- -$ oc edit operatorcondition <name> ----- - -. Add a `Spec.Overrides` array to the object: -+ -.Example Operator condition override -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorCondition -metadata: - name: my-operator - namespace: operators -spec: - overrides: - - type: Upgradeable <1> - status: "True" - reason: "upgradeIsSafe" - message: "This is a known issue with the Operator where it always reports that it cannot be upgraded." -status: - conditions: - - type: Upgradeable - status: "False" - reason: "migration" - message: "The operator is performing a migration." - lastTransitionTime: "2020-08-24T23:15:55Z" ----- -<1> Allows the cluster administrator to change the upgrade readiness to `True`. diff --git a/modules/olm-overriding-proxy-settings.adoc b/modules/olm-overriding-proxy-settings.adoc deleted file mode 100644 index f4296a65261d..000000000000 --- a/modules/olm-overriding-proxy-settings.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-configuring-proxy-support.adoc - -[id="olm-overriding-proxy-settings_{context}"] -= Overriding proxy settings of an Operator - -If a cluster-wide egress proxy is configured, Operators running with Operator Lifecycle Manager (OLM) inherit the cluster-wide proxy settings on their deployments. Cluster administrators can also override these proxy settings by configuring the subscription of an Operator. - -[IMPORTANT] -==== -Operators must handle setting environment variables for proxy settings in the pods for any managed Operands. -==== - -.Prerequisites - -- Access to an {product-title} cluster using an account with -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -`cluster-admin` permissions. -endif::[] -ifdef::openshift-dedicated[] -`dedicated-admins-cluster` permissions. -endif::[] - -.Procedure - -. Navigate in the web console to the *Operators → OperatorHub* page. - -. Select the Operator and click *Install*. - -. On the *Install Operator* page, modify the `Subscription` object to include one or more of the following environment variables in the `spec` section: -+ --- -* `HTTP_PROXY` -* `HTTPS_PROXY` -* `NO_PROXY` --- -+ -For example: -+ -.`Subscription` object with proxy setting overrides -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: etcd-config-test - namespace: openshift-operators -spec: - config: - env: - - name: HTTP_PROXY - value: test_http - - name: HTTPS_PROXY - value: test_https - - name: NO_PROXY - value: test - channel: clusterwide-alpha - installPlanApproval: Automatic - name: etcd - source: community-operators - sourceNamespace: openshift-marketplace - startingCSV: etcdoperator.v0.9.4-clusterwide ----- -+ -[NOTE] -==== -These environment variables can also be unset using an empty value to remove any previously set cluster-wide or custom proxy settings. -==== -+ -OLM handles these environment variables as a unit; if at least one of them is set, all three are considered overridden and the cluster-wide defaults are not used for the deployments of the subscribed Operator. - -. Click *Install* to make the Operator available to the selected namespaces. - -. After the CSV for the Operator appears in the relevant namespace, you can verify that custom proxy environment variables are set in the deployment. For example, using the CLI: -+ -[source,terminal] ----- -$ oc get deployment -n openshift-operators \ - etcd-operator -o yaml \ - | grep -i "PROXY" -A 2 ----- -+ -.Example output -[source,terminal] ----- - - name: HTTP_PROXY - value: test_http - - name: HTTPS_PROXY - value: test_https - - name: NO_PROXY - value: test - image: quay.io/coreos/etcd-operator@sha256:66a37fd61a06a43969854ee6d3e21088a98b93838e284a6086b13917f96b0d9c -... ----- diff --git a/modules/olm-overview.adoc b/modules/olm-overview.adoc deleted file mode 100644 index ae21716bba8e..000000000000 --- a/modules/olm-overview.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc -// * operators/operator-reference.adoc - -[id="olm-overview_{context}"] -ifeval::["{context}" != "red-hat-operators"] -= What is Operator Lifecycle Manager? -endif::[] -ifeval::["{context}" == "red-hat-operators"] -= Purpose -endif::[] - -_Operator Lifecycle Manager_ (OLM) helps users install, update, and manage the lifecycle of Kubernetes native applications (Operators) and their associated services running across their {product-title} clusters. It is part of the link:https://operatorframework.io/[Operator Framework], an open source toolkit designed to manage Operators in an effective, automated, and scalable way. - -.Operator Lifecycle Manager workflow -image::olm-workflow.png[] - -OLM runs by default in {product-title} {product-version}, which aids cluster administrators in installing, upgrading, and granting access to Operators running on their cluster. The {product-title} web console provides management screens for cluster administrators to install Operators, as well as grant specific projects access to use the catalog of Operators available on the cluster. - -For developers, a self-service experience allows provisioning and configuring instances of databases, monitoring, and big data services without having to be subject matter experts, because the Operator has that knowledge baked into it. diff --git a/modules/olm-package-manifest-format-catalogsource.adoc b/modules/olm-package-manifest-format-catalogsource.adoc deleted file mode 100644 index 52f69c1308fa..000000000000 --- a/modules/olm-package-manifest-format-catalogsource.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc - -[id="olm-package-manifest-format-catalogsource_{context}"] -= Creating a catalog from a Package Manifest Format catalog image - -Cluster administrators use a custom Operator catalog image based on the Package Manifest Format to create a catalog source that loads the Operator content onto their cluster. For this example, the procedure uses a custom `redhat-operators` catalog image previously built and pushed to a supported registry. - -.Prerequisites - -* A custom Operator catalog image based on the Package Manifest Format pushed to a supported registry -* `oc` version 4.3.5+ - -.Procedure - -. Create a `CatalogSource` object that references your catalog image. - -.. Modify the following to your specifications and save it as a -`catalogsource.yaml` file: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: my-operator-catalog - namespace: openshift-marketplace -spec: - sourceType: grpc - image: <registry_host_name>:<port>/olm/redhat-operators:v1 <1> - displayName: My Operator Catalog - publisher: grpc - updateStrategy: - registryPoll: - interval: 30m <2> ----- -<1> Specify your custom Operator catalog image. -<2> Catalog sources can automatically check for new versions to keep up to date. - -.. Use the file to create the `CatalogSource` object: -+ -[source,terminal] ----- -$ oc create -f catalogsource.yaml ----- - -. Verify the following resources are created successfully. - -.. Check the pods: -+ -[source,terminal] ----- -$ oc get pods -n openshift-marketplace ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -my-operator-catalog-6njx6 1/1 Running 0 28s -marketplace-operator-d9f549946-96sgr 1/1 Running 0 26h ----- - -.. Check the catalog source: -+ -[source,terminal] ----- -$ oc get catalogsource -n openshift-marketplace ----- -+ -.Example output -[source,terminal] ----- -NAME DISPLAY TYPE PUBLISHER AGE -my-operator-catalog My Operator Catalog grpc 5s ----- - -.. Check the package manifest: -+ -[source,terminal] ----- -$ oc get packagemanifest -n openshift-marketplace ----- -+ -.Example output -[source,terminal] ----- -NAME CATALOG AGE -etcd My Operator Catalog 34s ----- - -You can now install the Operators from your customer catalog by using the *OperatorHub* page on your {product-title} cluster web console. diff --git a/modules/olm-package-manifest-format.adoc b/modules/olm-package-manifest-format.adoc deleted file mode 100644 index 1d590a72e3a4..000000000000 --- a/modules/olm-package-manifest-format.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-packaging-formats.adoc - -[id="olm-package-manifest-format_{context}"] -= Package Manifest Format - -The _Package Manifest Format_ for Operators is the legacy packaging format introduced by the Operator Framework. While this format is deprecated in {product-title} 4.5, it is still supported and Operators provided by Red Hat are currently shipped using this method. - -In this format, a version of an Operator is represented by a single cluster service version (CSV) and typically the custom resource definitions (CRDs) that define the owned APIs of the CSV, though additional objects may be included. - -All versions of the Operator are nested in a single directory: - -.Example Package Manifest Format layout -[source,terminal] ----- -etcd -├── 0.6.1 -│ ├── etcdcluster.crd.yaml -│ └── etcdoperator.clusterserviceversion.yaml -├── 0.9.0 -│ ├── etcdbackup.crd.yaml -│ ├── etcdcluster.crd.yaml -│ ├── etcdoperator.v0.9.0.clusterserviceversion.yaml -│ └── etcdrestore.crd.yaml -├── 0.9.2 -│ ├── etcdbackup.crd.yaml -│ ├── etcdcluster.crd.yaml -│ ├── etcdoperator.v0.9.2.clusterserviceversion.yaml -│ └── etcdrestore.crd.yaml -└── etcd.package.yaml ----- - -It also includes a `<name>.package.yaml` file that is the _package manifest_ that defines the package name and channels details: - -.Example package manifest -[source,yaml] ----- -packageName: etcd -channels: -- name: alpha - currentCSV: etcdoperator.v0.9.2 -- name: beta - currentCSV: etcdoperator.v0.9.0 -- name: stable - currentCSV: etcdoperator.v0.9.2 -defaultChannel: alpha ----- - -When loading package manifests into the Operator Registry database, the following requirements are validated: - -* Every package has at least one channel. -* Every CSV pointed to by a channel in a package exists. -* Every version of an Operator has exactly one CSV. -* If a CSV owns a CRD, that CRD must exist in the directory of the Operator version. -* If a CSV replaces another, both the old and the new must exist in the package. diff --git a/modules/olm-policy-fine-grained-permissions.adoc b/modules/olm-policy-fine-grained-permissions.adoc deleted file mode 100644 index 8291f79e917d..000000000000 --- a/modules/olm-policy-fine-grained-permissions.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-creating-policy.adoc - -[id="olm-policy-fine-grained-permissions_{context}"] -= Fine-grained permissions - -Operator Lifecycle Manager (OLM) uses the service account specified in an Operator group to create or update the following resources related to the Operator being installed: - -* `ClusterServiceVersion` -* `Subscription` -* `Secret` -* `ServiceAccount` -* `Service` -* `ClusterRole` and `ClusterRoleBinding` -* `Role` and `RoleBinding` - -To confine Operators to a designated namespace, cluster administrators can start by granting the following permissions to the service account: - -[NOTE] -==== -The following role is a generic example and additional rules might be required based on the specific Operator. -==== - -[source,yaml] ----- -kind: Role -rules: -- apiGroups: ["operators.coreos.com"] - resources: ["subscriptions", "clusterserviceversions"] - verbs: ["get", "create", "update", "patch"] -- apiGroups: [""] - resources: ["services", "serviceaccounts"] - verbs: ["get", "create", "update", "patch"] -- apiGroups: ["rbac.authorization.k8s.io"] - resources: ["roles", "rolebindings"] - verbs: ["get", "create", "update", "patch"] -- apiGroups: ["apps"] <1> - resources: ["deployments"] - verbs: ["list", "watch", "get", "create", "update", "patch", "delete"] -- apiGroups: [""] <1> - resources: ["pods"] - verbs: ["list", "watch", "get", "create", "update", "patch", "delete"] ----- -<1> Add permissions to create other resources, such as deployments and pods shown here. - -In addition, if any Operator specifies a pull secret, the following permissions must also be added: - -[source,yaml] ----- -kind: ClusterRole <1> -rules: -- apiGroups: [""] - resources: ["secrets"] - verbs: ["get"] ---- -kind: Role -rules: -- apiGroups: [""] - resources: ["secrets"] - verbs: ["create", "update", "patch"] ----- -<1> Required to get the secret from the OLM namespace. diff --git a/modules/olm-policy-scenarios.adoc b/modules/olm-policy-scenarios.adoc deleted file mode 100644 index 60ff5083ebb5..000000000000 --- a/modules/olm-policy-scenarios.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-creating-policy.adoc - -[id="olm-policy-scenarios_{context}"] -= Installation scenarios - -When determining whether an Operator can be installed or upgraded on a cluster, Operator Lifecycle Manager (OLM) considers the following scenarios: - -* A cluster administrator creates a new Operator group and specifies a service account. All Operator(s) associated with this Operator group are installed and run against the privileges granted to the service account. - -* A cluster administrator creates a new Operator group and does not specify any service account. {product-title} maintains backward compatibility, so the default behavior remains and Operator installs and upgrades are permitted. - -* For existing Operator groups that do not specify a service account, the default behavior remains and Operator installs and upgrades are permitted. - -* A cluster administrator updates an existing Operator group and specifies a service account. OLM allows the existing Operator to continue to run with their current privileges. When such an existing Operator is going through an upgrade, it is reinstalled and run against the privileges granted to the service account like any new Operator. - -* A service account specified by an Operator group changes by adding or removing permissions, or the existing service account is swapped with a new one. When existing Operators go through an upgrade, it is reinstalled and run against the privileges granted to the updated service account like any new Operator. - -* A cluster administrator removes the service account from an Operator group. The default behavior remains and Operator installs and upgrades are permitted. diff --git a/modules/olm-policy-scoping-operator-install.adoc b/modules/olm-policy-scoping-operator-install.adoc deleted file mode 100644 index 44bb364655fd..000000000000 --- a/modules/olm-policy-scoping-operator-install.adoc +++ /dev/null @@ -1,111 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-creating-policy.adoc - -[id="olm-policy-scoping-operator-install_{context}"] -= Scoping Operator installations - -To provide scoping rules to Operator installations and upgrades on Operator Lifecycle Manager (OLM), associate a service account with an Operator group. - -Using this example, a cluster administrator can confine a set of Operators to a designated namespace. - -.Procedure - -. Create a new namespace: -+ -[source,terminal] ----- -$ cat <<EOF | oc create -f - -apiVersion: v1 -kind: Namespace -metadata: - name: scoped -EOF ----- - -. Allocate permissions that you want the Operator(s) to be confined to. This involves creating a new service account, relevant role(s), and role binding(s). -+ -[source,terminal] ----- -$ cat <<EOF | oc create -f - -apiVersion: v1 -kind: ServiceAccount -metadata: - name: scoped - namespace: scoped -EOF ----- -+ -The following example grants the service account permissions to do anything in the designated namespace for simplicity. In a production environment, you should create a more fine-grained set of permissions: -+ -[source,terminal] ----- -$ cat <<EOF | oc create -f - -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: scoped - namespace: scoped -rules: -- apiGroups: ["*"] - resources: ["*"] - verbs: ["*"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: scoped-bindings - namespace: scoped -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: scoped -subjects: -- kind: ServiceAccount - name: scoped - namespace: scoped -EOF ----- - -. Create an `OperatorGroup` object in the designated namespace. This Operator group targets the designated namespace to ensure that its tenancy is confined to it. -+ -In addition, Operator groups allow a user to specify a service account. Specify the service account created in the previous step: -+ -[source,terminal] ----- -$ cat <<EOF | oc create -f - -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: scoped - namespace: scoped -spec: - serviceAccountName: scoped - targetNamespaces: - - scoped -EOF ----- -+ -Any Operator installed in the designated namespace is tied to this Operator group and therefore to the service account specified. - -. Create a `Subscription` object in the designated namespace to install an Operator: -+ -[source,terminal] ----- -$ cat <<EOF | oc create -f - -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: etcd - namespace: scoped -spec: - channel: singlenamespace-alpha - name: etcd - source: <catalog_source_name> <1> - sourceNamespace: <catalog_source_namespace> <2> -EOF ----- -<1> Specify a catalog source that already exists in the designated namespace or one that is in the global catalog namespace. -<2> Specify a namespace where the catalog source was created. -+ -Any Operator tied to this Operator group is confined to the permissions granted to the specified service account. If the Operator requests permissions that are outside the scope of the service account, the installation fails with relevant errors. diff --git a/modules/olm-policy-troubleshooting.adoc b/modules/olm-policy-troubleshooting.adoc deleted file mode 100644 index c457314eb878..000000000000 --- a/modules/olm-policy-troubleshooting.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-creating-policy.adoc - -[id="olm-policy-troubleshooting_{context}"] -= Troubleshooting permission failures - -If an Operator installation fails due to lack of permissions, identify the errors using the following procedure. - -.Procedure - -. Review the `Subscription` object. Its status has an object reference `installPlanRef` that points to the `InstallPlan` object that attempted to create the necessary `[Cluster]Role[Binding]` object(s) for the Operator: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: Subscription -metadata: - name: etcd - namespace: scoped -status: - installPlanRef: - apiVersion: operators.coreos.com/v1 - kind: InstallPlan - name: install-4plp8 - namespace: scoped - resourceVersion: "117359" - uid: 2c1df80e-afea-11e9-bce3-5254009c9c23 ----- - -. Check the status of the `InstallPlan` object for any errors: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: InstallPlan -status: - conditions: - - lastTransitionTime: "2019-07-26T21:13:10Z" - lastUpdateTime: "2019-07-26T21:13:10Z" - message: 'error creating clusterrole etcdoperator.v0.9.4-clusterwide-dsfx4: clusterroles.rbac.authorization.k8s.io - is forbidden: User "system:serviceaccount:scoped:scoped" cannot create resource - "clusterroles" in API group "rbac.authorization.k8s.io" at the cluster scope' - reason: InstallComponentFailed - status: "False" - type: Installed - phase: Failed ----- -+ -The error message tells you: -+ -* The type of resource it failed to create, including the API group of the resource. In this case, it was `clusterroles` in the `rbac.authorization.k8s.io` group. -* The name of the resource. -* The type of error: `is forbidden` tells you that the user does not have enough permission to do the operation. -* The name of the user who attempted to create or update the resource. In this case, it refers to the service account specified in the Operator group. -* The scope of the operation: `cluster scope` or not. -+ -The user can add the missing permission to the service account and then iterate. -+ -[NOTE] -==== -Operator Lifecycle Manager (OLM) does not currently provide the complete list of errors on the first try. -==== diff --git a/modules/olm-policy-understanding.adoc b/modules/olm-policy-understanding.adoc deleted file mode 100644 index c9053efe188c..000000000000 --- a/modules/olm-policy-understanding.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-creating-policy.adoc - -[id="olm-policy-understanding_{context}"] -= Understanding Operator installation policy - -Using Operator Lifecycle Manager (OLM), cluster administrators can choose to specify a service account for an Operator group so that all Operators associated with the group are deployed and run against the privileges granted to the service account. - -The `APIService` and `CustomResourceDefinition` resources are always created by OLM using the `cluster-admin` role. A service account associated with an Operator group should never be granted privileges to write these resources. - -If the specified service account does not have adequate permissions for an Operator that is being installed or upgraded, useful and contextual information is added to the status of the respective resource(s) so that it is easy for the cluster administrator to troubleshoot and resolve the issue. - -Any Operator tied to this Operator group is now confined to the permissions granted to the specified service account. If the Operator asks for permissions that are outside the scope of the service account, the install fails with appropriate errors. diff --git a/modules/olm-policy-workflow.adoc b/modules/olm-policy-workflow.adoc deleted file mode 100644 index 75d894694bb6..000000000000 --- a/modules/olm-policy-workflow.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-creating-policy.adoc - -[id="olm-policy-workflow_{context}"] -= Installation workflow - -When an Operator group is tied to a service account and an Operator is installed or upgraded, Operator Lifecycle Manager (OLM) uses the following workflow: - -. The given `Subscription` object is picked up by OLM. -. OLM fetches the Operator group tied to this subscription. -. OLM determines that the Operator group has a service account specified. -. OLM creates a client scoped to the service account and uses the scoped client to install the Operator. This ensures that any permission requested by the Operator is always confined to that of the service account in the Operator group. -. OLM creates a new service account with the set of permissions specified in the CSV and assigns it to the Operator. The Operator runs as the assigned service account. diff --git a/modules/olm-pruning-index-image.adoc b/modules/olm-pruning-index-image.adoc deleted file mode 100644 index 309c20f4f772..000000000000 --- a/modules/olm-pruning-index-image.adoc +++ /dev/null @@ -1,153 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-restricted-networks.adoc -// * operators/admin/olm-managing-custom-catalogs.adoc -// * migration/migrating_3_4/deploying-cam-3-4.adoc -// * migration/migrating_4_1_4/deploying-cam-4-1-4.adoc -// * migration/migrating_4_2_4/deploying-cam-4-2-4.adoc - -ifdef::openshift-origin[] -:catalog-name: catalog -:index-image-pullspec: quay.io/operatorhubio/catalog:latest -:index-image: catalog:latest -:registry-image: quay.io/openshift/origin-operator-registry:4.7.0 -:package1: couchdb-operator -:package2: eclipse-che -:package3: etcd -endif::[] -ifndef::openshift-origin[] -:catalog-name: redhat-operators -:index-image-pullspec: registry.redhat.io/redhat/redhat-operator-index:v{product-version} -:index-image: redhat-operator-index:v{product-version} -:registry-image: registry.redhat.io/openshift4/ose-operator-registry:v4.7 -:package1: advanced-cluster-management -:package2: jaeger-product -:package3: quay-operator -endif::[] - -[id="olm-pruning-index-image_{context}"] -= Pruning an index image - -An index image, based on the Operator Bundle Format, is a containerized snapshot of an Operator catalog. You can prune an index of all but a specified list of packages, which creates a copy of the source index containing only the Operators that you want. - -ifeval::["{context}" != "olm-managing-custom-catalogs"] -When configuring Operator Lifecycle Manager (OLM) to use mirrored content on restricted network {product-title} clusters, use this pruning method if you want to only mirror a subset of Operators from the default catalogs. - -For the steps in this procedure, the target registry is an existing mirror registry that is accessible by your workstation with unrestricted network access. This example also shows pruning the index image for the default `{catalog-name}` catalog, but the process is the same for any index image. -endif::[] - -.Prerequisites - -ifeval::["{context}" != "olm-managing-custom-catalogs"] -* Workstation with unrestricted network access -endif::[] -* `podman` version 1.9.3+ -* link:https://github.com/fullstorydev/grpcurl[`grpcurl`] -* `opm` version 1.12.3+ -* Access to a registry that supports -link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] - -.Procedure - -ifndef::openshift-origin[] -ifeval::["{context}" != "olm-managing-custom-catalogs"] -. Authenticate with `registry.redhat.io`: -+ -[source,terminal] ----- -$ podman login registry.redhat.io ----- -endif::[] -endif::[] - -. Authenticate with your target registry: -+ -[source,terminal] ----- -$ podman login <target_registry> ----- - -. Determine the list of packages you want to include in your pruned index. - -.. Run the source index image that you want to prune in a container. For example: -+ -[source,terminal,subs="attributes+"] ----- -$ podman run -p50051:50051 \ - -it {index-image-pullspec} ----- -+ -.Example output -[source,terminal,subs="attributes+"] ----- -Trying to pull {index-image-pullspec}... -Getting image source signatures -Copying blob ae8a0c23f5b1 done -... -INFO[0000] serving registry database=/database/index.db port=50051 ----- - -.. In a separate terminal session, use the `grpcurl` command to get a list of the packages provided by the index: -+ -[source,terminal] ----- -$ grpcurl -plaintext localhost:50051 api.Registry/ListPackages > packages.out ----- - -.. Inspect the `packages.out` file and identify which package names from this list you want to keep in your pruned index. For example: -+ -.Example snippets of packages list -[source,text,subs="attributes+"] ----- -... -{ - "name": "{package1}" -} -... -{ - "name": "{package2}" -} -... -{ -{ - "name": "{package3}" -} -... ----- - -.. In the terminal session where you executed the `podman run` command, press kbd:[Ctrl] and kbd:[C] to stop the container process. - -. Run the following command to prune the source index of all but the specified packages: -+ -[source,text,subs="attributes+"] ----- -$ opm index prune \ - -f {index-image-pullspec} \// <1> - -p {package1},{package2},{package3} \// <2> - [-i {registry-image}] \// <3> - -t <target_registry>:<port>/<namespace>/{index-image} <4> ----- -<1> Index to prune. -<2> Comma-separated list of packages to keep. -<3> Required only for IBM Power Systems and IBM Z images: Operator Registry base image with the tag that matches the target {product-title} cluster major and minor version. -<4> Custom tag for new index image being built. - -. Run the following command to push the new index image to your target registry: -+ -[source,text,subs="attributes+"] ----- -$ podman push <target_registry>:<port>/<namespace>/{index-image} ----- -+ -where `<namespace>` is any existing namespace on the registry. -ifeval::["{context}" != "olm-managing-custom-catalogs"] -For example, you might create an `olm-mirror` namespace to push all mirrored content to. -endif::[] - -:!catalog-name: -:!index-image-pullspec: -:!index-image: -:!registry-image: -:!package1: -:!package2: -:!package3: diff --git a/modules/olm-refresh-subs.adoc b/modules/olm-refresh-subs.adoc deleted file mode 100644 index 7fc7cf636ce0..000000000000 --- a/modules/olm-refresh-subs.adoc +++ /dev/null @@ -1,107 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-operator-issues.adoc - -[id="olm-refresh-subs_{context}"] -= Refreshing failing subscriptions - -In Operator Lifecycle Manager (OLM), if you subscribe to an Operator that references images that are not accessible on your network, you can find jobs in the `openshift-marketplace` namespace that are failing with the following errors: - -.Example output -[source,terminal] ----- -ImagePullBackOff for -Back-off pulling image "example.com/openshift4/ose-elasticsearch-operator-bundle@sha256:6d2587129c846ec28d384540322b40b05833e7e00b25cca584e004af9a1d292e" ----- - -.Example output -[source,terminal] ----- -rpc error: code = Unknown desc = error pinging docker registry example.com: Get "https://example.com/v2/": dial tcp: lookup example.com on 10.0.0.1:53: no such host ----- - -As a result, the subscription is stuck in this failing state and the Operator is unable to install or upgrade. - -You can refresh a failing subscription by deleting the subscription, cluster service version (CSV), and other related objects. After recreating the subscription, OLM then reinstalls the correct version of the Operator. - -.Prerequisites - -* You have a failing subscription that is unable to pull an inaccessible bundle image. -* You have confirmed that the correct bundle image is accessible. - -.Procedure - -. Get the names of the `Subscription` and `ClusterServiceVersion` objects from the namespace where the Operator is installed: -+ -[source,terminal] ----- -$ oc get sub,csv -n <namespace> ----- -+ -.Example output -[source,terminal] ----- -NAME PACKAGE SOURCE CHANNEL -subscription.operators.coreos.com/elasticsearch-operator elasticsearch-operator redhat-operators 5.0 - -NAME DISPLAY VERSION REPLACES PHASE -clusterserviceversion.operators.coreos.com/elasticsearch-operator.5.0.0-65 OpenShift Elasticsearch Operator 5.0.0-65 Succeeded ----- - -. Delete the subscription: -+ -[source,terminal] ----- -$ oc delete subscription <subscription_name> -n <namespace> ----- - -. Delete the cluster service version: -+ -[source,terminal] ----- -$ oc delete csv <csv_name> -n <namespace> ----- - -. Get the names of any failing jobs and related config maps in the `openshift-marketplace` namespace: -+ -[source,terminal] ----- -$ oc get job,configmap -n openshift-marketplace ----- -+ -.Example output -[source,terminal] ----- -NAME COMPLETIONS DURATION AGE -job.batch/1de9443b6324e629ddf31fed0a853a121275806170e34c926d69e53a7fcbccb 1/1 26s 9m30s - -NAME DATA AGE -configmap/1de9443b6324e629ddf31fed0a853a121275806170e34c926d69e53a7fcbccb 3 9m30s ----- - -. Delete the job: -+ -[source,terminal] ----- -$ oc delete job <job_name> -n openshift-marketplace ----- -+ -This ensures pods that try to pull the inaccessible image are not recreated. - -. Delete the config map: -+ -[source,terminal] ----- -$ oc delete configmap <configmap_name> -n openshift-marketplace ----- - -. Reinstall the Operator using OperatorHub in the web console. - -.Verification - -* Check that the Operator has been reinstalled successfully: -+ -[source,terminal] ----- -$ oc get sub,csv,installplan -n <namespace> ----- diff --git a/modules/olm-removing-catalogs.adoc b/modules/olm-removing-catalogs.adoc deleted file mode 100644 index 18e8ae053855..000000000000 --- a/modules/olm-removing-catalogs.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc - -[id="olm-removing-catalogs_{context}"] -= Removing custom catalogs - -As a cluster administrator, you can remove custom Operator catalogs that have been previously added to your cluster by deleting the related catalog source. - -.Procedure - -. In the *Administrator* perspective of the web console, navigate to *Administration* -> *Cluster Settings*. - -. Click the *Global Configuration* tab, and then click *OperatorHub*. - -. Click the *Sources* tab. - -. Select the *Options* menu {kebab} for the catalog that you want to remove, and then click *Delete CatalogSource*. diff --git a/modules/olm-removing-crd-version.adoc b/modules/olm-removing-crd-version.adoc deleted file mode 100644 index e3e5c1e25995..000000000000 --- a/modules/olm-removing-crd-version.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="olm-dependency-resolution-removing-crd-version_{context}"] -= Deprecating or removing a CRD version - -Operator Lifecycle Manager (OLM) does not allow a serving version of a custom resource definition (CRD) to be removed right away. Instead, a deprecated version of the CRD must be first disabled by setting the `served` field in the CRD to `false`. Then, the non-serving version can be removed on the subsequent CRD upgrade. - -.Procedure - -To deprecate and remove a specific version of a CRD: - -. Mark the deprecated version as non-serving to indicate this version is no longer in use and may be removed in a subsequent upgrade. For example: -+ -[source,yaml] ----- -versions: - - name: v1alpha1 - served: false <1> - storage: true ----- -<1> Set to `false`. - -. Switch the `storage` version to a serving version if the version to be deprecated is currently the `storage` version. For example: -+ -[source,yaml] ----- -versions: - - name: v1alpha1 - served: false - storage: false <1> - - name: v1beta1 - served: true - storage: true <1> ----- -<1> Update the `storage` fields accordingly. -+ -[NOTE] -==== -To remove a specific version that is or was the `storage` version from a CRD, that version must be removed from the `storedVersion` in the status of the CRD. OLM will attempt to do this for you if it detects a stored version no longer exists in the new CRD. -==== - -. Upgrade the CRD with the above changes. - -. In subsequent upgrade cycles, the non-serving version can be removed completely from the CRD. For example: -+ -[source,yaml] ----- -versions: - - name: v1beta1 - served: true - storage: true ----- - -. Ensure the referencing CRD version in the `owned` section of your CSV is updated accordingly if that version is removed from the CRD. diff --git a/modules/olm-restricted-networks-configuring-operatorhub.adoc b/modules/olm-restricted-networks-configuring-operatorhub.adoc deleted file mode 100644 index 547efee24d24..000000000000 --- a/modules/olm-restricted-networks-configuring-operatorhub.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-restricted-networks.adoc -// * operators/admin/olm-managing-custom-catalogs.adoc -// * migration/migrating_3_4/deploying-cam-3-4.adoc -// * migration/migrating_4_1_4/deploying-cam-4-1-4.adoc -// * migration/migrating_4_2_4/deploying-cam-4-2-4.adoc - -ifeval::["{context}" == "olm-restricted-networks"] -:olm-restricted-networks: -endif::[] -ifeval::["{context}" == "olm-managing-custom-catalogs"] -:olm-managing-custom-catalogs: -endif::[] - -[id="olm-restricted-networks-operatorhub_{context}"] -= Disabling the default OperatorHub sources - -Operator catalogs that source content provided by Red Hat and community projects are configured for OperatorHub by default during an {product-title} installation. -ifdef::olm-restricted-networks[] -Before configuring OperatorHub to instead use local catalog sources in a restricted network environment, you must disable the default catalogs as a cluster administrator. -endif::[] -ifdef::olm-managing-custom-catalogs[] -As a cluster administrator, you can disable the set of default catalogs. -endif::[] - -.Procedure - -* Disable the sources for the default catalogs by adding `disableAllDefaultSources: true` to the `OperatorHub` object: -+ -[source,terminal] ----- -$ oc patch OperatorHub cluster --type json \ - -p '[{"op": "add", "path": "/spec/disableAllDefaultSources", "value": true}]' ----- - -[TIP] -==== -Alternatively, you can use the web console to manage catalog sources. From the *Administration* -> *Cluster Settings* -> *Global Configuration* -> *OperatorHub* page, click the *Sources* tab, where you can create, delete, disable, and enable individual sources. -==== - -ifeval::["{context}" == "olm-restricted-networks"] -:!olm-restricted-networks: -endif::[] -ifeval::["{context}" == "olm-managing-custom-catalogs"] -:!olm-managing-custom-catalogs: -endif::[] diff --git a/modules/olm-status-conditions.adoc b/modules/olm-status-conditions.adoc deleted file mode 100644 index f94ef3252aeb..000000000000 --- a/modules/olm-status-conditions.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-status.adoc -// * support/troubleshooting/troubleshooting-operator-issues.adoc - -[id="olm-status-conditions_{context}"] -= Operator subscription condition types - -Subscriptions can report the following condition types: - -.Subscription condition types -[cols="1,2",options="header"] -|=== -|Condition |Description - -|`CatalogSourcesUnhealthy` -|Some or all of the catalog sources to be used in resolution are unhealthy. - -|`InstallPlanMissing` -|An install plan for a subscription is missing. - -|`InstallPlanPending` -|An install plan for a subscription is pending installation. - -|`InstallPlanFailed` -|An install plan for a subscription has failed. - -|=== - -[NOTE] -==== -Default {product-title} cluster Operators are managed by the Cluster Version Operator (CVO) and they do not have a `Subscription` object. Application Operators are managed by Operator Lifecycle Manager (OLM) and they have a `Subscription` object. -==== diff --git a/modules/olm-status-viewing-cli.adoc b/modules/olm-status-viewing-cli.adoc deleted file mode 100644 index dff52b440b9b..000000000000 --- a/modules/olm-status-viewing-cli.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-status.adoc -// * support/troubleshooting/troubleshooting-operator-issues.adoc - -[id="olm-status-viewing-cli_{context}"] -= Viewing Operator subscription status using the CLI - -You can view Operator subscription status using the CLI. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. List Operator subscriptions: -+ -[source,terminal] ----- -$ oc get subs -n <operator_namespace> ----- - -. Use the `oc describe` command to inspect a `Subscription` resource: -+ -[source,terminal] ----- -$ oc describe sub <subscription_name> -n <operator_namespace> ----- - -. In the command output, find the `Conditions` section for the status of Operator subscription condition types. In the following example, the `CatalogSourcesUnhealthy` condition type has a status of `false` because all available catalog sources are healthy: -+ -.Example output -[source,terminal] ----- -Conditions: - Last Transition Time: 2019-07-29T13:42:57Z - Message: all available catalogsources are healthy - Reason: AllCatalogSourcesHealthy - Status: False - Type: CatalogSourcesUnhealthy ----- - -[NOTE] -==== -Default {product-title} cluster Operators are managed by the Cluster Version Operator (CVO) and they do not have a `Subscription` object. Application Operators are managed by Operator Lifecycle Manager (OLM) and they have a `Subscription` object. -==== diff --git a/modules/olm-subscription.adoc b/modules/olm-subscription.adoc deleted file mode 100644 index 5c68202c6c2e..000000000000 --- a/modules/olm-subscription.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-understanding-olm.adoc - -[id="olm-subscription_{context}"] -= Subscription - -A subscription, defined by a `Subscription` object, represents an intention to install an Operator. It is the custom resource that relates an Operator to a catalog source. - -Subscriptions describe which channel of an Operator package to subscribe to, and whether to perform updates automatically or manually. If set to automatic, the subscription ensures Operator Lifecycle Manager (OLM) manages and upgrades the Operator to ensure that the latest version is always running in the cluster. - -.Example `Subscription` object -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: my-operator - namespace: operators -spec: - channel: stable - name: my-operator - source: my-catalog - sourceNamespace: operators ----- - -This `Subscription` object defines the name and namespace of the Operator, as well as the catalog from which the Operator data can be found. The channel, such as `alpha`, `beta`, or `stable`, helps determine which Operator stream should be installed from the catalog source. - -The names of channels in a subscription can differ between Operators, but the naming scheme should follow a common convention within a given Operator. For example, channel names might follow a minor release update stream for the application provided by the Operator (`1.2`, `1.3`) or a release frequency (`stable`, `fast`). - -In addition to being easily visible from the {product-title} web console, it is possible to identify when there is a newer version of an Operator available by inspecting the status of the related subscription. The value associated with the `currentCSV` field is the newest version that is known to OLM, and `installedCSV` is the version that is installed on the cluster. diff --git a/modules/olm-supported-operatorconditions.adoc b/modules/olm-supported-operatorconditions.adoc deleted file mode 100644 index 2de5e73ac9a2..000000000000 --- a/modules/olm-supported-operatorconditions.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-operatorconditions.adoc - -[id="olm-supported-operatorconditions_{context}"] -= Supported conditions - -Operator Lifecycle Manager (OLM) supports the following Operator conditions. - -[id="olm-upgradeable-operatorcondition_{context}"] -== Upgradeable condition - -The `Upgradeable` Operator condition prevents an existing cluster service version (CSV) from being replaced by a newer version of the CSV. This condition is useful when: - -* An Operator is about to start a critical process and should not be upgraded until the process is completed. -* An Operator is performing a migration of custom resources (CRs) that must be completed before the Operator is ready to be upgraded. - -.Example `Upgradeable` Operator condition -[source,yaml] ----- -apiVersion: operators.coreos.com/v1 -kind: OperatorCondition -metadata: - name: my-operator - namespace: operators -status: - conditions: - - type: Upgradeable <1> - status: "False" <2> - reason: "migration" - message: "The Operator is performing a migration." - lastTransitionTime: "2020-08-24T23:15:55Z" ----- -<1> Name of the condition. -<2> A `False` value indicates the Operator is not ready to be upgraded. OLM prevents a CSV that replaces the existing CSV of the Operator from leaving the `Pending` phase. diff --git a/modules/olm-terms.adoc b/modules/olm-terms.adoc deleted file mode 100644 index 6fc71290bb24..000000000000 --- a/modules/olm-terms.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-common-terms.adoc - -[id="olm-common-terms-glossary_{context}"] -= Common Operator Framework terms - -[id="olm-common-terms-bundle_{context}"] -== Bundle -In the Bundle Format, a _bundle_ is a collection of an Operator CSV, manifests, and metadata. Together, they form a unique version of an Operator that can be installed onto the cluster. - -[id="olm-common-terms-bundle-image_{context}"] -== Bundle image -In the Bundle Format, a _bundle image_ is a container image that is built from Operator manifests and that contains one bundle. Bundle images are stored and distributed by Open Container Initiative (OCI) spec container registries, such as Quay.io or DockerHub. - -[id="olm-common-terms-catalogsource_{context}"] -== Catalog source -A _catalog source_ is a repository of CSVs, CRDs, and packages that define an application. - -[id="olm-common-terms-catalog-image_{context}"] -== Catalog image -In the Package Manifest Format, a _catalog image_ is a containerized datastore that describes a set of Operator metadata and update metadata that can be installed onto a cluster using OLM. - -[id="olm-common-terms-channel_{context}"] -== Channel -A _channel_ defines a stream of updates for an Operator and is used to roll out updates for subscribers. The head points to the latest version of that channel. For example, a `stable` channel would have all stable versions of an Operator arranged from the earliest to the latest. - -An Operator can have several channels, and a subscription binding to a certain channel would only look for updates in that channel. - -[id="olm-common-terms-channel-head_{context}"] -== Channel head -A _channel head_ refers to the latest known update in a particular channel. - -[id="olm-common-terms-csv_{context}"] -== Cluster service version -A _cluster service version (CSV)_ is a YAML manifest created from Operator -metadata that assists OLM in running the Operator in a cluster. It is the -metadata that accompanies an Operator container image, used to populate user -interfaces with information such as its logo, description, and version. - -It is also a source of technical information that is required to run the Operator, like the RBAC rules it requires and which custom resources (CRs) it manages or depends on. - -[id="olm-common-terms-dependency_{context}"] -== Dependency -An Operator may have a _dependency_ on another Operator being present in the cluster. For example, the Vault Operator has a dependency on the etcd Operator for its data persistence layer. - -OLM resolves dependencies by ensuring that all specified versions of Operators and CRDs are installed on the cluster during the installation phase. This dependency is resolved by finding and installing an Operator in a catalog that satisfies the required CRD API, and is not related to packages or bundles. - -[id="olm-common-terms-index-image_{context}"] -== Index image -In the Bundle Format, an _index image_ refers to an image of a database (a database snapshot) that contains information about Operator bundles including CSVs and CRDs of all versions. This index can host a history of Operators on a cluster and be maintained by adding or removing Operators using the `opm` CLI tool. - -[id="olm-common-terms-installplan_{context}"] -== Install plan -An _install plan_ is a calculated list of resources to be created to automatically install or upgrade a CSV. - -[id="olm-common-terms-operatorgroup_{context}"] -== Operator group - -An _Operator group_ configures all Operators deployed in the same namespace as the `OperatorGroup` object to watch for their CR in a list of namespaces or cluster-wide. - -[id="olm-common-terms-package_{context}"] -== Package -In the Bundle Format, a _package_ is a directory that encloses all released history of an Operator with each version. A released version of an Operator is described in a CSV manifest alongside the CRDs. - -[id="olm-common-terms-registry_{context}"] -== Registry -A _registry_ is a database that stores bundle images of Operators, each with all of its latest and historical versions in all channels. - -[id="olm-common-terms-subscription_{context}"] -== Subscription -A _subscription_ keeps CSVs up to date by tracking a channel in a package. - -[id="olm-common-terms-update-graph_{context}"] -== Update graph -An _update graph_ links versions of CSVs together, similar to the update graph of any other packaged software. Operators can be installed sequentially, or certain versions can be skipped. The update graph is expected to grow only at the head with newer versions being added. diff --git a/modules/olm-testing-operator-catalog-image.adoc b/modules/olm-testing-operator-catalog-image.adoc deleted file mode 100644 index 9bf717aeb262..000000000000 --- a/modules/olm-testing-operator-catalog-image.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc - -[id="olm-testing-operator-catalog-image_{context}"] -= Testing a Package Manifest Format catalog image - -You can validate Operator catalog image content by running it as a container and querying its gRPC API. To further test the image, you can then resolve a subscription in Operator Lifecycle Manager (OLM) by referencing the image in a catalog source. For this example, the procedure uses a custom `redhat-operators` catalog image previously built and pushed to a supported registry. - -.Prerequisites - -* A custom Package Manifest Format catalog image pushed to a supported registry -* `podman` version 1.9.3+ -* `oc` version 4.3.5+ -* Access to mirror registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] -* link:https://github.com/fullstorydev/grpcurl[`grpcurl`] - -.Procedure - -. Pull the Operator catalog image: -+ -[source,terminal] ----- -$ podman pull <registry_host_name>:<port>/olm/redhat-operators:v1 ----- - -. Run the image: -+ -[source,terminal] ----- -$ podman run -p 50051:50051 \ - -it <registry_host_name>:<port>/olm/redhat-operators:v1 ----- - -. Query the running image for available packages using `grpcurl`: -+ -[source,terminal] ----- -$ grpcurl -plaintext localhost:50051 api.Registry/ListPackages ----- -+ -.Example output -[source,terminal] ----- -{ - "name": "3scale-operator" -} -{ - "name": "amq-broker" -} -{ - "name": "amq-online" -} ----- - -. Get the latest Operator bundle in a channel: -+ -[source,terminal] ----- -$ grpcurl -plaintext -d '{"pkgName":"kiali-ossm","channelName":"stable"}' localhost:50051 api.Registry/GetBundleForChannel ----- -+ -.Example output -[source,terminal] ----- -{ - "csvName": "kiali-operator.v1.0.7", - "packageName": "kiali-ossm", - "channelName": "stable", -... ----- - -. Get the digest of the image: -+ -[source,terminal] ----- -$ podman inspect \ - --format='{{index .RepoDigests 0}}' \ - <registry_host_name>:<port>/olm/redhat-operators:v1 ----- -+ -.Example output -[source,terminal] ----- -example_registry:5000/olm/redhat-operators@sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 ----- - -. Assuming an Operator group exists in namespace `my-ns` that supports your Operator and its dependencies, create a `CatalogSource` object using the image digest. For example: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: custom-redhat-operators - namespace: my-ns -spec: - sourceType: grpc - image: example_registry:5000/olm/redhat-operators@sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 - displayName: Red Hat Operators ----- - -. Create a subscription that resolves the latest available `servicemeshoperator` and its dependencies from your catalog image: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: servicemeshoperator - namespace: my-ns -spec: - source: custom-redhat-operators - sourceNamespace: my-ns - name: servicemeshoperator - channel: "1.0" ----- diff --git a/modules/olm-understanding-operator-catalog-images.adoc b/modules/olm-understanding-operator-catalog-images.adoc deleted file mode 100644 index b2704b5a3dc7..000000000000 --- a/modules/olm-understanding-operator-catalog-images.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc -// * operators/admin/olm-restricted-networks.adoc - -:tag: v{product-version} - -[id="olm-understanding-operator-catalog-images_{context}"] -= Understanding Operator catalogs - -An Operator catalog is a repository of metadata that Operator Lifecycle Manager (OLM) can query to discover and install Operators and their dependencies on a cluster. OLM always installs Operators from the latest version of a catalog. As of {product-title} 4.6, Red Hat-provided catalogs are distributed using _index images_. - -An index image, based on the Operator Bundle Format, is a containerized snapshot of a catalog. It is an immutable artifact that contains the database of pointers to a set of Operator manifest content. A catalog can reference an index image to source its content for OLM on the cluster. - -[NOTE] -==== -Starting in {product-title} 4.6, index images provided by Red Hat replace the App Registry catalog images, based on the deprecated Package Manifest Format, that are distributed for previous versions of {product-title} 4. While App Registry catalog images are not distributed by Red Hat for {product-title} 4.6 and later, custom catalog images based on the Package Manifest Format are still supported. -==== - -ifndef::openshift-origin[] -The following catalogs are distributed by Red Hat: - -.Red Hat-provided Operator catalogs -[cols="20%,55%,25%",options="header"] -|=== -|Catalog -|Index image -|Description - -|`redhat-operators` -|`registry.redhat.io/redhat/redhat-operator-index:{tag}` -|Red Hat products packaged and shipped by Red Hat. Supported by Red Hat. - -|`certified-operators` -|`registry.redhat.io/redhat/certified-operator-index:{tag}` -|Products from leading independent software vendors (ISVs). Red Hat partners with ISVs to package and ship. Supported by the ISV. - -|`redhat-marketplace` -|`registry.redhat.io/redhat/redhat-marketplace-index:{tag}` -|Certified software that can be purchased from link:https://marketplace.redhat.com/[Red Hat Marketplace]. - -|`community-operators` -|`registry.redhat.io/redhat/community-operator-index:{tag}` -|Software maintained by relevant representatives in the link:https://github.com/operator-framework/community-operators[operator-framework/community-operators] GitHub repository. No official support. -|=== -endif::[] - -As catalogs are updated, the latest versions of Operators change, and older versions may be removed or altered. In addition, when OLM runs on an {product-title} cluster in a restricted network environment, it is unable to access the catalogs directly from the Internet to pull the latest content. - -As a cluster administrator, you can create your own custom index image, either based on a Red Hat-provided catalog or from scratch, which can be used to source the catalog content on the cluster. Creating and updating your own index image provides a method for customizing the set of Operators available on the cluster, while also avoiding the aforementioned restricted network environment issues. - -[IMPORTANT] -==== -When creating custom catalog images, previous versions of {product-title} 4 required using the `oc adm catalog build` command, which has been deprecated for several releases. With the availability of Red Hat-provided index images starting in {product-title} 4.6, catalog builders should start switching to using the `opm index` command to manage index images before the `oc adm catalog build` command is removed in a future release. -==== - -:!tag: diff --git a/modules/olm-updating-index-image.adoc b/modules/olm-updating-index-image.adoc deleted file mode 100644 index 8e68b279fd8b..000000000000 --- a/modules/olm-updating-index-image.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc -// * operators/admin/olm-restricted-network.adoc - -ifdef::openshift-origin[] -:index-image: catalog -endif::[] -ifndef::openshift-origin[] -:index-image: redhat-operator-index -endif::[] - -[id="olm-updating-index-image_{context}"] -= Updating an index image - -After configuring OperatorHub to use a catalog source that references a custom index image, cluster administrators can keep the available Operators on their cluster up to date by adding bundle images to the index image. - -You can update an existing index image using the `opm index add` command. -ifeval::["{context}" == "olm-restricted-networks"] -For restricted networks, the updated content must also be mirrored again to the cluster. -endif::[] - -.Prerequisites - -* `opm` version 1.12.3+ -* `podman` version 1.9.3+ -* An index image built and pushed to a registry. -* An existing catalog source referencing the index image. - -.Procedure - -. Update the existing index by adding bundle images: -+ -[source,terminal] ----- -$ opm index add \ - --bundles <registry>/<namespace>/<new_bundle_image>:<tag> \//<1> - --from-index <registry>/<namespace>/<existing_index_image>:<tag> \//<2> - --tag <registry>/<namespace>/<existing_index_image>:<tag> <3> ----- -<1> A comma-separated list of additional bundle images to add to the index. -<2> The existing index that was previously pushed. -<3> The image tag that you want the updated index image to have. - -. Push the updated index image: -+ -[source,terminal] ----- -$ podman push <registry>/<namespace>/<existing_index_image>:<tag> ----- - -ifeval::["{context}" == "olm-restricted-networks"] -. Follow the steps in the _Mirroring an Operator catalog_ procedure again to mirror the updated content. However, when you get to the step about creating the `ImageContentSourcePolicy` (ICSP) object, use the `oc replace` command instead of the `oc create` command. For example: -+ -[source,terminal,subs="attributes+"] ----- -$ oc replace -f ./manifests-{index-image}-<random_number>/imageContentSourcePolicy.yaml ----- -+ -This change is required because the object already exists and must be updated. -+ -[NOTE] -==== -Normally, the `oc apply` command can be used to update existing objects that were previously created using `oc apply`. However, due to a known issue regarding the size of the `metadata.annotations` field in ICSP objects, the `oc replace` command must be used for this step currently. -==== -endif::[] - -. After Operator Lifecycle Manager (OLM) automatically polls the index image referenced in the catalog source at its regular interval, verify that the new packages are successfully added: -+ -[source,terminal] ----- -$ oc get packagemanifests -n openshift-marketplace ----- - -:!index-image: diff --git a/modules/olm-updating-operator-catalog-image.adoc b/modules/olm-updating-operator-catalog-image.adoc deleted file mode 100644 index 658594fe1a97..000000000000 --- a/modules/olm-updating-operator-catalog-image.adoc +++ /dev/null @@ -1,161 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-custom-catalogs.adoc - -ifdef::openshift-origin[] -:registry-image: quay.io/openshift/origin-operator-registry:4.7.0 -endif::[] -ifndef::openshift-origin[] -:registry-image: registry.redhat.io/openshift4/ose-operator-registry:v4.7 -endif::[] - -[id="olm-updating-operator-catalog-image_{context}"] -= Updating a Package Manifest Format catalog image - -After a cluster administrator has configured OperatorHub to use custom Operator catalog images, administrators can keep their {product-title} cluster up to date with the latest Operators by capturing updates made to App Registry catalogs provided by Red Hat. This is done by building and pushing a new Operator catalog image, then replacing the existing `spec.image` parameter in the `CatalogSource` object with the new image digest. - -For this example, the procedure assumes a custom `redhat-operators` catalog image is already configured for use with OperatorHub. - -[NOTE] -==== -Only the Linux version of the `oc` client can be used for this procedure, because the Windows and macOS versions do not provide the `oc adm catalog build` command. -==== - -.Prerequisites - -* Workstation with unrestricted network access -* `oc` version 4.3.5+ Linux client -* `podman` version 1.9.3+ -* Access to mirror registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2/[Docker v2-2] -* OperatorHub configured to use custom catalog images -* If you are working with private registries, set the `REG_CREDS` environment variable to the file path of your registry credentials for use in later steps. For example, for the `podman` CLI: -+ -[source,terminal] ----- -$ REG_CREDS=${XDG_RUNTIME_DIR}/containers/auth.json ----- -* If you are working with private namespaces that your link:https://quay.io[quay.io] account has access to, you must set a Quay authentication token. Set the `AUTH_TOKEN` environment variable for use with the `--auth-token` flag by making a request against the login API using your link:https://quay.io[quay.io] credentials: -+ -[source,terminal] ----- -$ AUTH_TOKEN=$(curl -sH "Content-Type: application/json" \ - -XPOST https://quay.io/cnr/api/v1/users/login -d ' - { - "user": { - "username": "'"<quay_username>"'", - "password": "'"<quay_password>"'" - } - }' | jq -r '.token') ----- - -.Procedure - -. On the workstation with unrestricted network access, authenticate with the target mirror registry: -+ -[source,terminal] ----- -$ podman login <registry_host_name> ----- - -. Authenticate with `registry.redhat.io` so that the base image can be pulled during the build: -+ -[source,terminal] ----- -$ podman login registry.redhat.io ----- - -. Build a new catalog image based on the `redhat-operators` catalog from Quay.io, tagging and pushing it to your mirror registry: -+ -[source,terminal,subs="attributes+"] ----- -$ oc adm catalog build \ - --appregistry-org redhat-operators \//<1> - --from={registry-image} \//<2> - --filter-by-os="linux/amd64" \//<3> - --to=<registry_host_name>:<port>/olm/redhat-operators:v2 \//<4> - [-a ${REG_CREDS}] \//<5> - [--insecure] \//<6> - [--auth-token "${AUTH_TOKEN}"] <7> ----- -<1> Organization (namespace) to pull from an App Registry instance. -<2> Set `--from` to the Operator Registry base image using the tag that matches the target {product-title} cluster major and minor version. -<3> Set `--filter-by-os` to the operating system and architecture to use for the base image, which must match the target {product-title} cluster. Valid values are `linux/amd64`, `linux/ppc64le`, and `linux/s390x`. -<4> Name your catalog image and include a tag, for example, `v2` because it is the updated catalog. -<5> Optional: If required, specify the location of your registry credentials file. -<6> Optional: If you do not want to configure trust for the target registry, add the `--insecure` flag. -<7> Optional: If other application registry catalogs are used that are not public, specify a Quay authentication token. -+ -.Example output -[source,terminal] ----- -INFO[0013] loading Bundles dir=/var/folders/st/9cskxqs53ll3wdn434vw4cd80000gn/T/300666084/manifests-829192605 -... -Pushed sha256:f73d42950021f9240389f99ddc5b0c7f1b533c054ba344654ff1edaf6bf827e3 to example_registry:5000/olm/redhat-operators:v2 ----- - -. Mirror the contents of your catalog to your target registry. The following `oc adm catalog mirror` command extracts the contents of your custom Operator catalog image to generate the manifests required for mirroring and mirrors the images to your registry: -+ -[source,terminal] ----- -$ oc adm catalog mirror \ - <registry_host_name>:<port>/olm/redhat-operators:v2 \//<1> - <registry_host_name>:<port> \ - [-a ${REG_CREDS}] \//<2> - [--insecure] \//<3> - [--index-filter-by-os='<platform>/<arch>'] <4> ----- -<1> Specify your new Operator catalog image. -<2> Optional: If required, specify the location of your registry credentials file. -<3> Optional: If you do not want to configure trust for the target registry, add the `--insecure` flag. -<4> Optional: Specify which platform and architecture of the catalog image to select when multiple variants are available. Images are passed as `'<platform>/<arch>[/<variant>]'`. This does not apply to images referenced by the catalog image. Valid values are `linux/amd64`, `linux/ppc64le`, and `linux/s390x`. - -. Apply the newly generated manifests: -+ -[source,terminal] ----- -$ oc replace -f ./manifests-redhat-operators-<random_number> ----- -+ -[IMPORTANT] -==== -It is possible that you do not need to apply the `imageContentSourcePolicy.yaml` manifest. Complete a `diff` of the files to determine if changes are necessary. -==== - -. Update your `CatalogSource` object that references your catalog image. - -.. If you have your original `catalogsource.yaml` file for this `CatalogSource` object: - -... Edit your `catalogsource.yaml` file to reference your new catalog image in the `spec.image` field: -+ -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: my-operator-catalog - namespace: openshift-marketplace -spec: - sourceType: grpc - image: <registry_host_name>:<port>/olm/redhat-operators:v2 <1> - displayName: My Operator Catalog - publisher: grpc ----- -<1> Specify your new Operator catalog image. - -... Use the updated file to replace the `CatalogSource` object: -+ -[source,terminal] ----- -$ oc replace -f catalogsource.yaml ----- - -.. Alternatively, edit the catalog source using the following command and reference your new catalog image in the `spec.image` parameter: -+ -[source,terminal] ----- -$ oc edit catalogsource <catalog_source_name> -n openshift-marketplace ----- - -Updated Operators should now be available from the *OperatorHub* page on your {product-title} cluster. - -:!registry-image: diff --git a/modules/olm-updating-use-operatorconditions.adoc b/modules/olm-updating-use-operatorconditions.adoc deleted file mode 100644 index 2e657ba36683..000000000000 --- a/modules/olm-updating-use-operatorconditions.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/admin/olm-managing-operatorconditions.adoc - -[id="olm-updating-use-operatorconditions_{context}"] -= Updating your Operator to use Operator conditions - -Operator Lifecycle Manager (OLM) automatically creates an `OperatorCondition` resource for each `ClusterServiceVersion` resource that it reconciles. All service accounts in the CSV are granted the RBAC to interact with the `OperatorCondition` owned by the Operator. - -An Operator author can develop their Operator to use the `operator-lib` library such that, after the Operator has been deployed by OLM, it can set its own conditions. For more on writing logic to set Operator conditions as an Operator author, see the Operator SDK documentation. - -[id="olm-updating-use-operatorconditions-defaults_{context}"] -== Setting defaults - -In an effort to remain backwards compatible, OLM treats the absence of an `OperatorCondition` resource as opting out of the condition. Therefore, an Operator that opts in to using Operator conditions should set default conditions before the ready probe for the pod is set to `true`. This provides the Operator with a grace period to update the condition to the correct state. diff --git a/modules/olm-upgrades.adoc b/modules/olm-upgrades.adoc deleted file mode 100644 index dcf02693d872..000000000000 --- a/modules/olm-upgrades.adoc +++ /dev/null @@ -1,153 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm/olm-workflow.adoc - -[id="olm-upgrades_{context}"] -= Operator installation and upgrade workflow in OLM - -In the Operator Lifecycle Manager (OLM) ecosystem, the following resources are used to resolve Operator installations and upgrades: - -* `ClusterServiceVersion` (CSV) -* `CatalogSource` -* `Subscription` - -Operator metadata, defined in CSVs, can be stored in a collection called a catalog source. OLM uses catalog sources, which use the link:https://github.com/operator-framework/operator-registry[Operator Registry API], to query for available Operators as well as upgrades for installed Operators. - -.Catalog source overview -image::olm-catalogsource.png[] - -Within a catalog source, Operators are organized into _packages_ and streams of updates called _channels_, which should be a familiar update pattern from {product-title} or other software on a continuous release cycle like web browsers. - -.Packages and channels in a Catalog source -image::olm-channels.png[] - -A user indicates a particular package and channel in a particular catalog source in a _subscription_, for example an `etcd` package and its `alpha` channel. If a subscription is made to a package that has not yet been installed in the namespace, the latest Operator for that package is installed. - -[NOTE] -==== -OLM deliberately avoids version comparisons, so the "latest" or "newest" Operator available from a given _catalog_ -> _channel_ -> _package_ path does not necessarily need to be the highest version number. It should be thought of more as the _head_ reference of a channel, similar to a Git repository. -==== - -Each CSV has a `replaces` parameter that indicates which Operator it replaces. This builds a graph of CSVs that can be queried by OLM, and updates can be shared between channels. Channels can be thought of as entry points into the graph of updates: - -.OLM graph of available channel updates -image::olm-replaces.png[] - -.Example channels in a package -[source,yaml] ----- -packageName: example -channels: -- name: alpha - currentCSV: example.v0.1.2 -- name: beta - currentCSV: example.v0.1.3 -defaultChannel: alpha ----- - -For OLM to successfully query for updates, given a catalog source, package, channel, and CSV, a catalog must be able to return, unambiguously and deterministically, a single CSV that `replaces` the input CSV. - -[id="olm-upgrades-example-upgrade-path_{context}"] -== Example upgrade path - -For an example upgrade scenario, consider an installed Operator corresponding to CSV version `0.1.1`. OLM queries the catalog source and detects an upgrade in the subscribed channel with new CSV version `0.1.3` that replaces an older but not-installed CSV version `0.1.2`, which in turn replaces the older and installed CSV version `0.1.1`. - -OLM walks back from the channel head to previous versions via the `replaces` field specified in the CSVs to determine the upgrade path `0.1.3` -> `0.1.2` -> `0.1.1`; the direction of the arrow indicates that the former replaces the latter. OLM upgrades the Operator one version at the time until it reaches the channel head. - -For this given scenario, OLM installs Operator version `0.1.2` to replace the existing Operator version `0.1.1`. Then, it installs Operator version `0.1.3` to replace the previously installed Operator version `0.1.2`. At this point, the installed operator version `0.1.3` matches the channel head and the upgrade is completed. - -[id="olm-upgrades-skipping_{context}"] -== Skipping upgrades - -The basic path for upgrades in OLM is: - -* A catalog source is updated with one or more updates to an Operator. -* OLM traverses every version of the Operator until reaching the latest version the catalog source contains. - -However, sometimes this is not a safe operation to perform. There will be cases where a published version of an Operator should never be installed on a cluster if it has not already, for example because a version introduces a serious vulnerability. - -In those cases, OLM must consider two cluster states and provide an update graph that supports both: - -* The "bad" intermediate Operator has been seen by the cluster and installed. -* The "bad" intermediate Operator has not yet been installed onto the cluster. - -By shipping a new catalog and adding a _skipped_ release, OLM is ensured that it can always get a single unique update regardless of the cluster state and whether it has seen the bad update yet. - -.Example CSV with skipped release -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: etcdoperator.v0.9.2 - namespace: placeholder - annotations: -spec: - displayName: etcd - description: Etcd Operator - replaces: etcdoperator.v0.9.0 - skips: - - etcdoperator.v0.9.1 ----- - -Consider the following example of *Old CatalogSource* and *New CatalogSource*. - -.Skipping updates -image::olm-skipping-updates.png[] - -This graph maintains that: - -* Any Operator found in *Old CatalogSource* has a single replacement in *New CatalogSource*. -* Any Operator found in *New CatalogSource* has a single replacement in *New CatalogSource*. -* If the bad update has not yet been installed, it will never be. - -[id="olm-upgrades-replacing-multiple_{context}"] -== Replacing multiple Operators - -Creating *New CatalogSource* as described requires publishing CSVs that `replace` one Operator, but can `skip` several. This can be accomplished using the `skipRange` annotation: - -[source,yaml] ----- -olm.skipRange: <semver_range> ----- - -where `<semver_range>` has the version range format supported by the link:https://github.com/blang/semver#ranges[semver library]. - -When searching catalogs for updates, if the head of a channel has a `skipRange` annotation and the currently installed Operator has a version field that falls in the range, OLM updates to the latest entry in the channel. - -The order of precedence is: - -. Channel head in the source specified by `sourceName` on the subscription, if the other criteria for skipping are met. -. The next Operator that replaces the current one, in the source specified by `sourceName`. -. Channel head in another source that is visible to the subscription, if the other criteria for skipping are met. -. The next Operator that replaces the current one in any source visible to the -subscription. - -.Example CSV with `skipRange` -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: elasticsearch-operator.v4.1.2 - namespace: <namespace> - annotations: - olm.skipRange: '>=4.1.0 <4.1.2' ----- - -[id="olm-upgrades-z-stream_{context}"] -== Z-stream support - -A _z-stream_, or patch release, must replace all previous z-stream releases for the same minor version. OLM does not consider major, minor, or patch versions, it just needs to build the correct graph in a catalog. - -In other words, OLM must be able to take a graph as in *Old CatalogSource* and, similar to before, generate a graph as in *New CatalogSource*: - -.Replacing several Operators -image::olm-z-stream.png[] - -This graph maintains that: - -* Any Operator found in *Old CatalogSource* has a single replacement in *New CatalogSource*. -* Any Operator found in *New CatalogSource* has a single replacement in *New CatalogSource*. -* Any z-stream release in *Old CatalogSource* will update to the latest z-stream release in *New CatalogSource*. -* Unavailable releases can be considered "virtual" graph nodes; their content does not need to exist, the registry just needs to respond as if the graph looks like this. diff --git a/modules/olm-webhook-considerations.adoc b/modules/olm-webhook-considerations.adoc deleted file mode 100644 index 1d0e85e00b61..000000000000 --- a/modules/olm-webhook-considerations.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="olm-webhook-considerations_{context}"] -= Webhook considerations for OLM - -When deploying an Operator with webhooks using Operator Lifecycle Manager (OLM), you must define the following: - -* The `type` field must be set to either `ValidatingAdmissionWebhook`, `MutatingAdmissionWebhook`, or `ConversionWebhook`, or the CSV will be placed in a failed phase. - -* The CSV must contain a deployment whose name is equivalent to the value supplied in the `deploymentName` field of the `webhookdefinition`. - -When the webhook is created, OLM ensures that the webhook only acts upon namespaces that match the Operator group that the Operator is deployed in. - -[discrete] -[id="olm-webhook-ca_{context}"] -=== Certificate authority constraints - -OLM is configured to provide each deployment with a single certificate authority (CA). The logic that generates and mounts the CA into the deployment was originally used by the API service lifecycle logic. As a result: - -* The TLS certificate file is mounted to the deployment at `/apiserver.local.config/certificates/apiserver.crt`. -* The TLS key file is mounted to the deployment at `/apiserver.local.config/certificates/apiserver.key`. - -[discrete] -[id="olm-admission-webhook-constraints_{context}"] -=== Admission webhook rules constraints - -To prevent an Operator from configuring the cluster into an unrecoverable state, OLM places the CSV in the failed phase if the rules defined in an admission webhook intercept any of the following requests: - -* Requests that target all groups -* Requests that target the `operators.coreos.com` group -* Requests that target the `ValidatingWebhookConfigurations` or `MutatingWebhookConfigurations` resources - -[discrete] -[id="olm-conversion-webhook-constraints_{context}"] -=== Conversion webhook constraints - -OLM places the CSV in the failed phase if a conversion webhook definition does not adhere to the following constraints: - -* CSVs featuring a conversion webhook can only support the `AllNamespaces` install mode. -* The CRD targeted by the conversion webhook must have its -`spec.preserveUnknownFields` field set to `false` or `nil`. -* The conversion webhook defined in the CSV must target an owned CRD. -* There can only be one conversion webhook on the entire cluster for a given CRD. diff --git a/modules/olm-why-use-operators.adoc b/modules/olm-why-use-operators.adoc deleted file mode 100644 index 9ba31d44e5b7..000000000000 --- a/modules/olm-why-use-operators.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/understanding/olm-what-operators-are.adoc - -[id="olm-why-use-operators_{context}"] -= Why use Operators? - -Operators provide: - --- -- Repeatability of installation and upgrade. -- Constant health checks of every system component. -- Over-the-air (OTA) updates for OpenShift components and ISV content. -- A place to encapsulate knowledge from field engineers and spread it to all users, not just one or two. --- - -Why deploy on Kubernetes?:: -Kubernetes (and by extension, {product-title}) contains all of the primitives needed to build complex distributed systems – secret handling, load balancing, service discovery, autoscaling – that work across on-premise and cloud providers. - -Why manage your app with Kubernetes APIs and `kubectl` tooling?:: -These APIs are feature rich, have clients for all platforms and plug into the cluster’s access control/auditing. An Operator uses the Kubernetes extension mechanism, custom resource definitions (CRDs), so your custom object, link:https://marketplace.redhat.com/en-us/products/mongodb-enterprise-advanced-from-ibm[for example `MongoDB`], looks and acts just like the built-in, native Kubernetes objects. - -How do Operators compare with service brokers?:: -A service broker is a step towards programmatic discovery and deployment of an app. However, because it is not a long running process, it cannot execute Day 2 operations like upgrade, failover, or scaling. Customizations and parameterization of tunables are provided at install time, versus an Operator that is constantly watching the current state of your cluster. Off-cluster services are a good match for a service broker, although Operators exist for these as well. diff --git a/modules/on-demand-backups-roxctl-admin-pass.adoc b/modules/on-demand-backups-roxctl-admin-pass.adoc new file mode 100644 index 000000000000..d72eeff9d7f3 --- /dev/null +++ b/modules/on-demand-backups-roxctl-admin-pass.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/backing-up-acs.adoc +// *troubleshooting_central/restoring-central-database-by-using-the-roxctl-cli.adoc + +:_mod-docs-content-type: PROCEDURE +[id="on-demand-backups-roxctl-admin-pass_{context}"] += On-demand backups by using the administrator password + +[role="_abstract"] +You can back up the entire database of {product-title-short} by using your administrator password. + +.Prerequisites + +* You have the administrator password. +* You have installed the `roxctl` CLI. + +.Procedure + +. Set the `ROX_ENDPOINT` environment variable by running the following command: ++ +[source,terminal] +---- +$ export ROX_ENDPOINT=<address>:<port_number> +---- + +. Initiate a backup for Central by running the following command: ++ +[source,terminal] +---- +$ roxctl -p <admin_password> central backup <1> +---- ++ +<1> For `<admin_password>`, specify the administrator password. ++ +By default, the `roxctl` CLI saves the backup file in the directory in which you run the command. +You can use the `--output` option to specify the backup file location. \ No newline at end of file diff --git a/modules/on-demand-backups-roxctl-api.adoc b/modules/on-demand-backups-roxctl-api.adoc new file mode 100644 index 000000000000..479b5d0f8310 --- /dev/null +++ b/modules/on-demand-backups-roxctl-api.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/backing-up-acs.adoc +// *troubleshooting_central/backing-up-central-database-by-using-the-roxctl-cli.adoc + +:_mod-docs-content-type: PROCEDURE +[id="on-demand-backups-roxctl-api_{context}"] += On-demand backups by using an API token + +[role="_abstract"] +You can back up the entire database of {product-title-short} by using an API token. + +.Prerequisites + +* You have an API token with the `Admin` role. +* You have installed the `roxctl` CLI. + +.Procedure + +. Set the `ROX_API_TOKEN` and the `ROX_ENDPOINT` environment variables by running the following commands: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN=<api_token> +---- ++ +[source,terminal] +---- +$ export ROX_ENDPOINT=<address>:<port_number> +---- + +. Initiate a backup for Central by running the following command: ++ +[source,terminal] +---- +$ roxctl central backup <1> +---- ++ +<1> You can use the `--output` option to specify the backup file location. ++ +By default, the `roxctl` CLI saves the backup file in the directory where you run the command. diff --git a/modules/online-telemetry-collected-data.adoc b/modules/online-telemetry-collected-data.adoc new file mode 100644 index 000000000000..1dfbb70f90a6 --- /dev/null +++ b/modules/online-telemetry-collected-data.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * configuration/online-telemetry.adoc +:_mod-docs-content-type: CONCEPT +[id="online-telemetry-collected-data_{context}"] += Collected data + +{product-title} sends the following data once every 24 hours: + +* *Storage information*: Details about the database size and the amount of free space available in attached volumes. +* *{product-title} components health information*: Details about {product-title} components versions, their memory usage, and any reported errors. +* *Coarse-grained usage statistics*: Details about API endpoint invocation counts and reported error statuses. +It does not include the actual data sent in API requests. +* *Nodes information*: Details about the nodes in each secured cluster. +It includes kernel and operating system versions, resource pressure, and taints. +* *Environment information*: Details about each secured cluster, including Kubernetes or {ocp} version, Istio version (if applicable), cloud provider type and other similar information. + +[IMPORTANT] +==== +The collection frequency is once every 24 hours. +However, if there are any performance-related events, such as rapidly increasing error counts or new errors, {product-title} increases this frequency up to once every hour. +Once sufficient information is gathered to resolve the issues, the frequency changes back to once every 24 hours. +==== diff --git a/modules/op-about-pipelinerun.adoc b/modules/op-about-pipelinerun.adoc deleted file mode 100644 index 0b3d5da6bea7..000000000000 --- a/modules/op-about-pipelinerun.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/op-creating-applications-with-cicd-pipelines.adoc - -[id="about-pipelinerun_{context}"] -= PipelineRun - -A _PipelineRun_ instantiates a Pipeline for execution with specific inputs, outputs, and execution parameters on a cluster. A corresponding TaskRun is created for each Task automatically in the PipelineRun. - -All the Tasks in the Pipeline are executed in the defined sequence until all Tasks are successful or a Task fails. The `status` field tracks and stores the progress of each TaskRun in the PipelineRun for monitoring and auditing purpose. - -The following example shows a PipelineRun to run the `build-and-deploy` Pipeline with relevant resources and parameters: -[source,yaml] ----- -apiVersion: tekton.dev/v1beta1 <1> -kind: PipelineRun <2> -metadata: - name: build-deploy-api-pipelinerun <3> -spec: - pipelineRef: - name: build-and-deploy <4> - params: <5> - - name: deployment-name - value: vote-api - - name: git-url - value: https://github.com/openshift-pipelines/vote-api.git - - name: IMAGE - value: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/vote-api - workspaces: <6> - - name: shared-workspace - volumeClaimTemplate: - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 500Mi ----- -<1> PipelineRun API version `v1beta1`. -<2> Specifies the type of Kubernetes object. In this example, `PipelineRun`. -<3> Unique name to identify this PipelineRun. -<4> Name of the Pipeline to be run. In this example, `build-and-deploy`. -<5> Specifies the list of parameters required to run the Pipeline. -<6> Workspace used by the PipelineRun. diff --git a/modules/op-about-pipelines.adoc b/modules/op-about-pipelines.adoc deleted file mode 100644 index d03dae8980ca..000000000000 --- a/modules/op-about-pipelines.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Ths module is included in the following assembly: -// -// *openshift_pipelines/op-creating-applications-with-cicd-pipelines.adoc - -[id="about-pipelines_{context}"] -= Pipelines - -A _Pipeline_ is a collection of `Task` resources arranged in a specific order of execution. You can define a CI/CD workflow for your application using pipelines containing one or more tasks. - -A `Pipeline` resource definition consists of a number of fields or attributes, which together enable the pipeline to accomplish a specific goal. Each `Pipeline` resource definition must contain at least one `Task` resource, which ingests specific inputs and produces specific outputs. The pipeline definition can also optionally include _Conditions_, _Workspaces_, _Parameters_, or _Resources_ depending on the application requirements. - -The following example shows the `build-and-deploy` pipeline, which builds an application image from a Git repository using the `buildah` `ClusterTask` resource: - -[source,yaml,subs="attributes+"] ----- -apiVersion: tekton.dev/v1beta1 <1> -kind: Pipeline <2> -metadata: - name: build-and-deploy <3> -spec: <4> - workspaces: <5> - - name: shared-workspace - params: <6> - - name: deployment-name - type: string - description: name of the deployment to be patched - - name: git-url - type: string - description: url of the git repo for the code of deployment - - name: git-revision - type: string - description: revision to be used from repo of the code for deployment - default: "{pipelines-ver}" - - name: IMAGE - type: string - description: image to be built from the code - tasks: <7> - - name: fetch-repository - taskRef: - name: git-clone - kind: ClusterTask - workspaces: - - name: output - workspace: shared-workspace - params: - - name: url - value: $(params.git-url) - - name: subdirectory - value: "" - - name: deleteExisting - value: "true" - - name: revision - value: $(params.git-revision) - - name: build-image <8> - taskRef: - name: buildah - kind: ClusterTask - params: - - name: TLSVERIFY - value: "false" - - name: IMAGE - value: $(params.IMAGE) - workspaces: - - name: source - workspace: shared-workspace - runAfter: - - fetch-repository - - name: apply-manifests <9> - taskRef: - name: apply-manifests - workspaces: - - name: source - workspace: shared-workspace - runAfter: <10> - - build-image - - name: update-deployment - taskRef: - name: update-deployment - workspaces: - - name: source - workspace: shared-workspace - params: - - name: deployment - value: $(params.deployment-name) - - name: IMAGE - value: $(params.IMAGE) - runAfter: - - apply-manifests ----- -<1> Pipeline API version `v1beta1`. -<2> Specifies the type of Kubernetes object. In this example, `Pipeline`. -<3> Unique name of this Pipeline. -<4> Specifies the definition and structure of the Pipeline. -<5> Workspaces used across all the Tasks in the Pipeline. -<6> Parameters used across all the Tasks in the Pipeline. -<7> Specifies the list of Tasks used in the Pipeline. -<8> Task `build-image`, which uses the `buildah` ClusterTask to build application images from a given Git repository. -<9> Task `apply-manifests`, which uses a user-defined Task with the same name. -<10> Specifies the sequence in which Tasks are run in a Pipeline. In this example, the `apply-manifests` Task is run only after the `build-image` Task is completed. diff --git a/modules/op-about-taskrun.adoc b/modules/op-about-taskrun.adoc deleted file mode 100644 index 05e1b401b31c..000000000000 --- a/modules/op-about-taskrun.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Ths module is included in the following assembly: -// -// *openshift_pipelines/op-creating-applications-with-cicd-pipelines.adoc - -[id="about-taskrun_{context}"] -= TaskRun - -A _TaskRun_ instantiates a Task for execution with specific inputs, outputs, and execution parameters on a cluster. It can be invoked on its own or as part of a PipelineRun. - -A Task consists of one or more Steps that execute container images, and each container image performs a specific piece of build work. A TaskRun executes the Steps in a Task in the specified order, until all Steps execute successfully or a failure occurs. - -The following example shows a TaskRun that runs the `apply-manifests` Task with the relevant input parameters: -[source,yaml] ----- -apiVersion: tekton.dev/v1beta1 <1> -kind: TaskRun <2> -metadata: - name: apply-manifests-taskrun <3> -spec: <4> - serviceAccountName: pipeline - taskRef: <5> - kind: Task - name: apply-manifests - workspaces: <6> - - name: source - persistentVolumeClaim: - claimName: source-pvc ----- -<1> TaskRun API version `v1beta1`. -<2> Specifies the type of Kubernetes object. In this example, `TaskRun`. -<3> Unique name to identify this TaskRun. -<4> Definition of the TaskRun. For this TaskRun, the Task and the required workspace are specified. -<5> Name of the Task reference used for this TaskRun. This TaskRun executes the `apply-manifests` Task. -<6> Workspace used by the TaskRun. diff --git a/modules/op-about-tasks.adoc b/modules/op-about-tasks.adoc deleted file mode 100644 index 799d90969b01..000000000000 --- a/modules/op-about-tasks.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="about-tasks_{context}"] -= Tasks - -_Tasks_ are the building blocks of a Pipeline and consist of sequentially executed Steps. Tasks are reusable and can be used in multiple Pipelines. - -_Steps_ are a series of commands that achieve a specific goal, such as building an image. Every Task runs as a pod, and each Step runs as a container within that pod. Because Steps run within the same pod, they can access the same volumes for caching files, config maps, and secrets. - -The following example shows the `apply-manifests` Task. - -[source,yaml] ----- -apiVersion: tekton.dev/v1beta1 <1> -kind: Task <2> -metadata: - name: apply-manifests <3> -spec: <4> - workspaces: - - name: source - params: - - name: manifest_dir - description: The directory in source that contains yaml manifests - type: string - default: "k8s" - steps: - - name: apply - image: image-registry.openshift-image-registry.svc:5000/openshift/cli:latest - workingDir: /workspace/source - command: ["/bin/bash", "-c"] - args: - - |- - echo Applying manifests in $(params.manifest_dir) directory - oc apply -f $(params.manifest_dir) - echo ----------------------------------- ----- -<1> The Task API version, `v1beta1`. -<2> The type of Kubernetes object, `Task`. -<3> The unique name of this Task. -<4> The list of parameters and Steps in the Task and the workspace used by the Task. - -This Task starts the pod and runs a container inside that pod using the specified image to run the specified commands. diff --git a/modules/op-about-triggers.adoc b/modules/op-about-triggers.adoc deleted file mode 100644 index 28a423aa148d..000000000000 --- a/modules/op-about-triggers.adoc +++ /dev/null @@ -1,141 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="about-triggers_{context}"] -= Triggers - -Use _Triggers_ in conjunction with pipelines to create a full-fledged CI/CD system where Kubernetes resources define the entire CI/CD execution. Triggers capture the external events and process them to extract key pieces of information. Mapping this event data to a set of predefined parameters triggers a series of tasks that can then create and deploy Kubernetes resources and instantiate the pipeline. - -For example, you define a CI/CD workflow using {pipelines-title} for your application. The pipeline must start for any new changes to take effect in the application repository. Triggers automate this process by capturing and processing any change event and by triggering a pipeline run that deploys the new image with the latest changes. - -Triggers consist of the following main resources that work together to form a reusable, decoupled, and self-sustaining CI/CD system: - -* The `TriggerBinding` resource validates events, extracts the fields from an event payload, and stores them as parameters. -* The `TriggerTemplate` resource acts as a standard for the way resources must be created. It specifies the way parameterized data from the `TriggerBinding` resource should be used. -A trigger template receives input from the trigger binding, and then performs a series of actions that results in creation of new pipeline resources, and initiation of a new pipeline run. - -* The `EventListener` resource provides an endpoint, or an event sink, that listens for incoming HTTP-based events with a JSON payload. It extracts event parameters from each `TriggerBinding` resource, and then processes this data to create Kubernetes resources as specified by the corresponding `TriggerTemplate` resource. The `EventListener` resource also performs lightweight event processing or basic filtering on the payload using event `interceptors`, which identify the type of payload and optionally modify it. Currently, pipeline triggers support four types of interceptors: _Webhook Interceptors_, _GitHub Interceptors_, _GitLab Interceptors_, and _Common Expression Language (CEL) Interceptors_. - -* The `Trigger` resource connects the `TriggerBinding` and `TriggerTemplate` resources, and this `Trigger` resource is referenced in the `EventListener` specification. -//image::op-triggers.png[] - -The following example shows a code snippet of the `TriggerBinding` resource, which extracts the Git repository information from the received event payload: - -[source,yaml] ----- -apiVersion: triggers.tekton.dev/v1alpha1 <1> -kind: TriggerBinding <2> -metadata: - name: vote-app <3> -spec: - params: <4> - - name: git-repo-url - value: $(body.repository.url) - - name: git-repo-name - value: $(body.repository.name) - - name: git-revision - value: $(body.head_commit.id) ----- - -<1> The API version of the `TriggerBinding` resource. In this example, `v1alpha1`. -<2> Specifies the type of Kubernetes object. In this example, `TriggerBinding`. -<3> Unique name to identify the `TriggerBinding` resource. -<4> List of parameters which will be extracted from the received event payload and passed to the `TriggerTemplate` resource. In this example, the Git repository URL, name, and revision are extracted from the body of the event payload. - - -The following example shows a code snippet of a `TriggerTemplate` resource, which creates a pipeline run using the Git repository information received from the `TriggerBinding` resource you just created: - -[source,yaml,subs="attributes+"] ----- -apiVersion: triggers.tekton.dev/v1alpha1 <1> -kind: TriggerTemplate <2> -metadata: - name: vote-app <3> -spec: - params: <4> - - name: git-repo-url - description: The git repository url - - name: git-revision - description: The git revision - default: {pipelines-ver} - - name: git-repo-name - description: The name of the deployment to be created / patched - - resourcetemplates: <5> - - apiVersion: tekton.dev/v1beta1 - kind: PipelineRun - metadata: - name: build-deploy-$(tt.params.git-repo-name)-$(uid) - spec: - serviceAccountName: pipeline - pipelineRef: - name: build-and-deploy - params: - - name: deployment-name - value: $(tt.params.git-repo-name) - - name: git-url - value: $(tt.params.git-repo-url) - - name: git-revision - value: $(tt.params.git-revision) - - name: IMAGE - value: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/$(tt.params.git-repo-name) - workspaces: - - name: shared-workspace - volumeClaimTemplate: - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 500Mi ----- - -<1> The API version of the `TriggerTemplate` resource. In this example, `v1alpha1`. -<2> Specifies the type of Kubernetes object. In this example, `TriggerTemplate`. -<3> Unique name to identify the `TriggerTemplate` resource. -<4> Parameters supplied by the `TriggerBinding` or `EventListerner` resources. -<5> List of templates that specify the way resources must be created using the parameters received through the `TriggerBinding` or `EventListener` resources. - - -The following example shows a code snippet of a `Trigger` resource, named `vote-trigger` that connects the `TriggerBinding` and `TriggerTemplate` resources. - -[source,yaml] ----- -apiVersion: triggers.tekton.dev/v1alpha1 <1> -kind: Trigger <2> -metadata: - name: vote-trigger <3> -spec: - serviceAccountName: pipeline <4> - bindings: - - ref: vote-app <5> - template: <6> - ref: vote-app ----- -<1> The API version of the `Trigger` resource. In this example, `v1alpha1`. -<2> Specifies the type of Kubernetes object. In this example, `Trigger`. -<3> Unique name to identify the `Trigger` resource. -<4> Service account name to be used. -<5> Name of the `TriggerBinding` resource to be connected to the `TriggerTemplate` resource. -<6> Name of the `TriggerTemplate` resource to be connected to the `TriggerBinding` resource. - - -The following example shows an `EventListener` resource, which references the `Trigger` resource named `vote-trigger`. - -[source,yaml] ----- -apiVersion: triggers.tekton.dev/v1alpha1 <1> -kind: EventListener <2> -metadata: - name: vote-app <3> -spec: - serviceAccountName: pipeline <4> - triggers: - - triggerRef: vote-trigger <5> ----- -<1> The API version of the `EventListener` resource. In this example, `v1alpha1`. -<2> Specifies the type of Kubernetes object. In this example, `EventListener`. -<3> Unique name to identify the `EventListener` resource. -<4> Service account name to be used. -<5> Name of the `Trigger` resource referenced by the `EventListener` resource. diff --git a/modules/op-about-workspace.adoc b/modules/op-about-workspace.adoc deleted file mode 100644 index d6813ebfea32..000000000000 --- a/modules/op-about-workspace.adoc +++ /dev/null @@ -1,104 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="about-workspaces_{context}"] -= Workspaces - -[NOTE] -==== -It is recommended that you use Workspaces instead of PipelineResources in OpenShift Pipelines, as PipelineResources are difficult to debug, limited in scope, and make Tasks less reusable. -==== - -Workspaces declare shared storage volumes that a Task in a Pipeline needs at runtime. Instead of specifying the actual location of the volumes, Workspaces enable you to declare the filesystem or parts of the filesystem that would be required at runtime. You must provide the specific location details of the volume that is mounted into that Workspace in a TaskRun or a PipelineRun. This separation of volume declaration from runtime storage volumes makes the Tasks reusable, flexible, and independent of the user environment. - -With Workspaces, you can: - -* Store Task inputs and outputs -* Share data among Tasks -* Use it as a mount point for credentials held in Secrets -* Use it as a mount point for configurations held in ConfigMaps -* Use it as a mount point for common tools shared by an organization -* Create a cache of build artifacts that speed up jobs - -You can specify Workspaces in the TaskRun or PipelineRun using: - -* A read-only ConfigMaps or Secret -* An existing PersistentVolumeClaim shared with other Tasks -* A PersistentVolumeClaim from a provided VolumeClaimTemplate -* An emptyDir that is discarded when the TaskRun completes - -The following example shows a code snippet of the `build-and-deploy` Pipeline, which declares a `shared-workspace` Workspace for the `build-image` and `apply-manifests` Tasks as defined in the Pipeline. - -[source,yaml] ----- -apiVersion: tekton.dev/v1beta1 -kind: Pipeline -metadata: - name: build-and-deploy -spec: - workspaces: <1> - - name: shared-workspace - params: -... - tasks: <2> - - name: build-image - taskRef: - name: buildah - kind: ClusterTask - params: - - name: TLSVERIFY - value: "false" - - name: IMAGE - value: $(params.IMAGE) - workspaces: <3> - - name: source <4> - workspace: shared-workspace <5> - runAfter: - - fetch-repository - - name: apply-manifests - taskRef: - name: apply-manifests - workspaces: <6> - - name: source - workspace: shared-workspace - runAfter: - - build-image -... ----- -<1> List of Workspaces shared between the Tasks defined in the Pipeline. A Pipeline can define as many Workspaces as required. In this example, only one Workspace named `shared-workspace` is declared. -<2> Definition of Tasks used in the Pipeline. This snippet defines two Tasks, `build-image` and `apply-manifests`, which share a common Workspace. -<3> List of Workspaces used in the `build-image` Task. A Task definition can include as many Workspaces as it requires. However, it is recommended that a Task uses at most one writable Workspace. -<4> Name that uniquely identifies the Workspace used in the Task. This Task uses one Workspace named `source`. -<5> Name of the Pipeline Workspace used by the Task. Note that the Workspace `source` in turn uses the Pipeline Workspace named `shared-workspace`. -<6> List of Workspaces used in the `apply-manifests` Task. Note that this Task shares the `source` Workspace with the `build-image` Task. - -Workspaces help tasks share data, and allow you to specify one or more volumes that each task in the pipeline requires during execution. You can create a persistent volume claim or provide a volume claim template that creates a persistent volume claim for you. - -The following code snippet of the `build-deploy-api-pipelinerun` PipelineRun uses a volume claim template to create a persistent volume claim for defining the storage volume for the `shared-workspace` Workspace used in the `build-and-deploy` Pipeline. - -[source,yaml] ----- -apiVersion: tekton.dev/v1beta1 -kind: PipelineRun -metadata: - name: build-deploy-api-pipelinerun -spec: - pipelineRef: - name: build-and-deploy - params: -... - - workspaces: <1> - - name: shared-workspace <2> - volumeClaimTemplate: <3> - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 500Mi ----- -<1> Specifies the list of Pipeline Workspaces for which volume binding will be provided in the PipelineRun. -<2> The name of the Workspace in the Pipeline for which the volume is being provided. -<3> Specifies a volume claim template that creates a persistent volume claim to define the storage volume for the workspace. diff --git a/modules/op-adding-triggers.adoc b/modules/op-adding-triggers.adoc deleted file mode 100644 index 4534ad645dc1..000000000000 --- a/modules/op-adding-triggers.adoc +++ /dev/null @@ -1,170 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="adding-triggers_{context}"] -= Adding Triggers to a Pipeline - -Triggers enable pipelines to respond to external GitHub events, such as push events and pull requests. After you assemble and start a Pipeline for the application, add the `TriggerBinding`, `TriggerTemplate`, `Trigger`, and `EventListener` resources to capture the GitHub events. - -[discrete] -.Procedure -. Copy the content of the following sample `TriggerBinding` YAML file and save it: -+ -[source,yaml] ----- -apiVersion: triggers.tekton.dev/v1alpha1 -kind: TriggerBinding -metadata: - name: vote-app -spec: - params: - - name: git-repo-url - value: $(body.repository.url) - - name: git-repo-name - value: $(body.repository.name) - - name: git-revision - value: $(body.head_commit.id) ----- - -. Create the `TriggerBinding` resource: -+ -[source,terminal] ----- -$ oc create -f <triggerbinding-yaml-file-name.yaml> ----- -+ -Alternatively, you can create the `TriggerBinding` resource directly from the `pipelines-tutorial` Git repository: -+ -[source,terminal,subs="attributes+"] ----- -$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/{pipelines-ver}/03_triggers/01_binding.yaml ----- - -. Copy the content of the following sample `TriggerTemplate` YAML file and save it: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: triggers.tekton.dev/v1alpha1 -kind: TriggerTemplate -metadata: - name: vote-app -spec: - params: - - name: git-repo-url - description: The git repository url - - name: git-revision - description: The git revision - default: {pipelines-ver} - - name: git-repo-name - description: The name of the deployment to be created / patched - - resourcetemplates: - - apiVersion: tekton.dev/v1beta1 - kind: PipelineRun - metadata: - name: build-deploy-$(tt.params.git-repo-name)-$(uid) - spec: - serviceAccountName: pipeline - pipelineRef: - name: build-and-deploy - params: - - name: deployment-name - value: $(tt.params.git-repo-name) - - name: git-url - value: $(tt.params.git-repo-url) - - name: git-revision - value: $(tt.params.git-revision) - - name: IMAGE - value: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/$(tt.params.git-repo-name) - workspaces: - - name: shared-workspace - volumeClaimTemplate: - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 500Mi ----- -+ -The template specifies a volume claim template to create a persistent volume claim for defining the storage volume for the workspace. Therefore, you do not need to create a persistent volume claim to provide data storage. - -. Create the `TriggerTemplate` resource: -+ -[source,terminal] ----- -$ oc create -f <triggertemplate-yaml-file-name.yaml> ----- -+ -Alternatively, you can create the `TriggerTemplate` resource directly from the `pipelines-tutorial` Git repository: -+ -[source,terminal,subs="attributes+"] ----- -$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/{pipelines-ver}/03_triggers/02_template.yaml ----- - -. Copy the contents of the following sample `Trigger` YAML file and save it: -+ -[source,yaml] ----- -apiVersion: triggers.tekton.dev/v1alpha1 -kind: Trigger -metadata: - name: vote-trigger -spec: - serviceAccountName: pipeline - bindings: - - ref: vote-app - template: - ref: vote-app ----- - -. Create the `Trigger` resource: -+ -[source,terminal] ----- -$ oc create -f <trigger-yaml-file-name.yaml> ----- -+ -Alternatively, you can create the `Trigger` resource directly from the `pipelines-tutorial` Git repository: -+ -[source,terminal,subs="attributes+"] ----- -$ oc create -f https://github.com/openshift/pipelines-tutorial/blob/{pipelines-ver}/03_triggers/03_trigger.yaml ----- - -. Copy the contents of the following sample `EventListener` YAML file and save it: -+ -[source,yaml] ----- -apiVersion: triggers.tekton.dev/v1alpha1 -kind: EventListener -metadata: - name: vote-app -spec: - serviceAccountName: pipeline - triggers: - - triggerRef: vote-trigger ----- - -. Create the `EventListener` resource: -+ -[source,terminal] ----- -$ oc create -f <eventlistener-yaml-file-name.yaml> ----- -+ -Alternatively, you can create the `EvenListener` resource directly from the `pipelines-tutorial` Git repository: -+ -[source,terminal,subs="attributes+"] ----- -$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/{pipelines-ver}/03_triggers/04_event_listener.yaml ----- - -. Expose the `EventListener` service as an {product-title} route to make it publicly accessible: -+ -[source,terminal] ----- -$ oc expose svc el-vote-app ----- diff --git a/modules/op-assembling-a-pipeline.adoc b/modules/op-assembling-a-pipeline.adoc deleted file mode 100644 index 1f661af580ae..000000000000 --- a/modules/op-assembling-a-pipeline.adoc +++ /dev/null @@ -1,134 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="assembling-a-pipeline_{context}"] -= Assembling a Pipeline - -A Pipeline represents a CI/CD flow and is defined by the Tasks to be executed. It is designed to be generic and reusable in multiple applications and environments. - -A Pipeline specifies how the Tasks interact with each other and their order of execution using the `from` and `runAfter` parameters. It uses the `workspaces` field to specify one or more volumes that each Task in the Pipeline requires during execution. - -In this section, you will create a Pipeline that takes the source code of the application from GitHub and then builds and deploys it on {product-title}. - -//The image below displays the various components of `pipelines-tutorial` Pipeline, and how these components interact with each other. - -//image::op-assemble-a-pipeline.png[] - - -The Pipeline performs the following tasks for the back-end application `vote-api` and front-end application `vote-ui`: - -* Clones the source code of the application from the Git repository by referring to the `git-url` and `git-revision` parameters. -* Builds the container image using the `buildah` ClusterTask. -* Pushes the image to the internal image registry by referring to the `image` parameter. -* Deploys the new image on {product-title} by using the `apply-manifests` and `update-deployment` Tasks. - -[discrete] -.Procedure - -. Copy the contents of the following sample Pipeline YAML file and save it: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: tekton.dev/v1beta1 -kind: Pipeline -metadata: - name: build-and-deploy -spec: - workspaces: - - name: shared-workspace - params: - - name: deployment-name - type: string - description: name of the deployment to be patched - - name: git-url - type: string - description: url of the git repo for the code of deployment - - name: git-revision - type: string - description: revision to be used from repo of the code for deployment - default: "{pipelines-ver}" - - name: IMAGE - type: string - description: image to be built from the code - tasks: - - name: fetch-repository - taskRef: - name: git-clone - kind: ClusterTask - workspaces: - - name: output - workspace: shared-workspace - params: - - name: url - value: $(params.git-url) - - name: subdirectory - value: "" - - name: deleteExisting - value: "true" - - name: revision - value: $(params.git-revision) - - name: build-image - taskRef: - name: buildah - kind: ClusterTask - params: - - name: TLSVERIFY - value: "false" - - name: IMAGE - value: $(params.IMAGE) - workspaces: - - name: source - workspace: shared-workspace - runAfter: - - fetch-repository - - name: apply-manifests - taskRef: - name: apply-manifests - workspaces: - - name: source - workspace: shared-workspace - runAfter: - - build-image - - name: update-deployment - taskRef: - name: update-deployment - workspaces: - - name: source - workspace: shared-workspace - params: - - name: deployment - value: $(params.deployment-name) - - name: IMAGE - value: $(params.IMAGE) - runAfter: - - apply-manifests ----- -+ -The Pipeline definition abstracts away the specifics of the Git source repository and image registries. These details are added as `params` when a Pipeline is triggered and executed. - -. Create the Pipeline: -+ ----- -$ oc create -f <pipeline-yaml-file-name.yaml> ----- -+ -Alternatively, you can also execute the YAML file directly from the Git repository: -+ -[source,terminal,subs="attributes+"] ----- -$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/{pipelines-ver}/01_pipeline/04_pipeline.yaml ----- - -. Use the `tkn pipeline list` command to verify that the Pipeline is added to the application: -+ ----- -$ tkn pipeline list ----- -+ -The output verifies that the `build-and-deploy` Pipeline was created: -+ ----- -NAME AGE LAST RUN STARTED DURATION STATUS -build-and-deploy 1 minute ago --- --- --- --- ----- diff --git a/modules/op-constructing-pipelines-using-pipeline-builder.adoc b/modules/op-constructing-pipelines-using-pipeline-builder.adoc deleted file mode 100644 index d3bc4c2e3616..000000000000 --- a/modules/op-constructing-pipelines-using-pipeline-builder.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/working-with-pipelines-using-the-developer-perspective.adoc - -[id="op-constructing-pipelines-using-pipeline-builder_{context}"] -= Constructing Pipelines using the Pipeline Builder - -In the *Developer* perspective of the console, you can use the *+Add* -> *Pipeline* -> *Pipeline builder* option to: - -* Configure pipelines using either the *Pipeline builder* or the *YAML view*. -* Construct a pipeline flow using existing tasks and cluster tasks. When you install the OpenShift Pipelines Operator, it adds reusable pipeline cluster tasks to your cluster. -* Specify the type of resources required for the pipeline run, and if required, add additional parameters to the pipeline. -* Reference these pipeline resources in each of the tasks in the pipeline as input and output resources. -* If required, reference any additional parameters added to the pipeline in the task. The parameters for a task are prepopulated based on the specifications of the task. -* Use the Operator-installed, reusable snippets and samples to create detailed pipelines. - -.Procedure - -. In the *+Add* view of the *Developer* perspective, click the *Pipeline* tile to see the *Pipeline builder* page. -. Configure the pipeline using either the *Pipeline builder* view or the *YAML view*. -+ -[NOTE] -==== -The *Pipeline builder* view supports a limited number of fields whereas the *YAML view* supports all available fields. Optionally, you can also use the Operator-installed, reusable snippets and samples to create detailed Pipelines. -==== -+ -.YAML view -image::op-pipeline-yaml.png[] -+ -To configure your pipeline using the *Pipeline Builder*: - -.. Enter a unique name for the pipeline. -.. Select a task from the *Select Task* list to add a task to the pipeline. This example uses the *s2i-nodejs* task. -*** To add sequential tasks to the pipeline, click the plus icon to the right or left of the task, and from the *Select Task* list, select the task you want to add to the pipeline. For this example, use the plus icon to the right of the *s2i-nodejs* task to add an *openshift-client* task. -*** To add a parallel task to the existing task, click the plus icon displayed next to the task, and from the *Select Task* list, select the parallel task you want to add to the pipeline. -+ -.Pipeline Builder -image::op-pipeline-builder.png[] -+ -.. Click *Add Resources* to specify the name and type of resources that the pipeline run will use. These resources are then used by the tasks in the pipeline as inputs and outputs. -For this example: -... Add an input resource. In the *Name* field, enter `Source`, and then from the *Resource Type* drop-down list, select *Git*. -... Add an output resource. In the *Name* field, enter `Img`, and then from the *Resource Type* drop-down list, select *Image*. -.. Optional: The *Parameters* for a task are prepopulated based on the specifications of the task. If required, use the *Add Parameters* link to add additional parameters. -+ -.. A *Missing Resources* warning is displayed on a task if the resources for the task are not specified. Click the *s2i-nodejs* task to see the side panel with details for the task. -+ -.Tasks details in Pipelines Builder -image::op-pipeline-builder-task-details.png[] -+ -.. In the task side panel, specify the resources and parameters for the *s2i-nodejs* task: - -... In the *Input Resources* -> *Source* section, the *Select Resources* drop-down list displays the resources that you added to the pipeline. For this example, select *Source*. -... In the *Output Resources* -> *Image* section, click the *Select Resources* list, and select *Img*. -... If required, in the *Parameters* section, add more parameters to the default ones, by using the `$(params.<param-name>)` syntax. -... Similarly, add an input resource for the *openshift-client* task. -. Click *Create* to create and view the pipeline in the *Pipeline Details* page. -. Click the *Actions* drop-down menu, and then click *Start* to start the Pipeline. diff --git a/modules/op-creating-pipeline-tasks.adoc b/modules/op-creating-pipeline-tasks.adoc deleted file mode 100644 index 2f9fa30afe1b..000000000000 --- a/modules/op-creating-pipeline-tasks.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="creating-pipeline-tasks_{context}"] -= Creating Pipeline Tasks - -[discrete] -.Procedure - -. Install the `apply-manifests` and `update-deployment` task resources from the `pipelines-tutorial` repository, which contains a list of reusable tasks for pipelines: -+ -[source,terminal,subs="attributes+"] ----- -$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/{pipelines-ver}/01_pipeline/01_apply_manifest_task.yaml -$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/{pipelines-ver}/01_pipeline/02_update_deployment_task.yaml ----- - -. Use the `tkn task list` command to list the tasks you created: -+ -[source,terminal] ----- -$ tkn task list ----- -+ -The output verifies that the `apply-manifests` and `update-deployment` task resources were created: -+ -[source,terminal] ----- -NAME DESCRIPTION AGE -apply-manifests 1 minute ago -update-deployment 48 seconds ago ----- - -. Use the `tkn clustertasks list` command to list the Operator-installed additional cluster tasks, for example, `buildah` and `s2i-python-3`: -+ -[NOTE] -==== -To use the `buildah` cluster task in a restricted environment, you must ensure that the Dockerfile uses an internal image stream as the base image. -==== -+ -[source,terminal] ----- -$ tkn clustertasks list ----- -+ -The output lists the Operator-installed `ClusterTask` resources: -+ -[source,terminal] ----- -NAME DESCRIPTION AGE -buildah 1 day ago -git-clone 1 day ago -s2i-php 1 day ago -tkn 1 day ago ----- diff --git a/modules/op-creating-project-and-checking-pipeline-service-account.adoc b/modules/op-creating-project-and-checking-pipeline-service-account.adoc deleted file mode 100644 index e3b824e056b0..000000000000 --- a/modules/op-creating-project-and-checking-pipeline-service-account.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-cicd-solutions-using-openshift-pipelines.adoc - -[id="creating-project-and-checking-pipeline-service-account_{context}"] -= Creating a project and checking your Pipeline ServiceAccount - -[discrete] -.Procedure - -. Log in to your {product-title} cluster: -+ ----- -$ oc login -u <login> -p <password> https://openshift.example.com:6443 ----- - -. Create a project for the sample application. For this example workflow, create the `pipelines-tutorial` project: -+ ----- -$ oc new-project pipelines-tutorial ----- -+ -[NOTE] -==== -If you create a project with a different name, be sure to update the resource URLs used in the example with your project name. -==== -. View the `pipeline` ServiceAccount: -+ -{pipelines-title} Operator adds and configures a ServiceAccount named `pipeline` that has sufficient permissions to build and push an image. This ServiceAccount is used by PipelineRun. -+ ----- -$ oc get serviceaccount pipeline ----- diff --git a/modules/op-creating-webhooks.adoc b/modules/op-creating-webhooks.adoc deleted file mode 100644 index e3a84fe0270a..000000000000 --- a/modules/op-creating-webhooks.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="creating-webhooks_{context}"] -= Creating Webhooks - -_Webhooks_ are HTTP POST messages that are received by the EventListeners whenever a configured event occurs in your repository. The event payload is then mapped to TriggerBindings, and processed by TriggerTemplates. The TriggerTemplates eventually start one or more PipelineRuns, leading to the creation and deployment of Kubernetes resources. - -In this section, you will configure a Webhook URL on your forked Git repositories `vote-ui` and `vote-api`. This URL points to the publicly accessible EventListener service route. - -[NOTE] -==== -Adding Webhooks requires administrative privileges to the repository. If you do not have administrative access to your repository, contact your system administrator for adding Webhooks. -==== - -[discrete] -.Procedure - -. Get the Webhook URL: -+ ----- -$ echo "URL: $(oc get route el-vote-app --template='http://{{.spec.host}}/')" ----- -+ -Note the URL obtained in the output. - -. Configure Webhooks manually on the front-end repository: - -.. Open the front-end Git repository `vote-ui` in your browser. -.. Click *Settings* -> *Webhooks* -> *Add Webhook* -.. On the *Webhooks/Add Webhook* page: -+ -... Enter the Webhook URL from step 1 in *Payload URL* field -... Select *application/json* for the *Content type* -... Specify the secret in the *Secret* field -... Ensure that the *Just the push event* is selected -... Select *Active* -... Click *Add Webhook* - -. Repeat step 2 for the back-end repository `vote-api`. diff --git a/modules/op-defining-and-creating-pipelineresources.adoc b/modules/op-defining-and-creating-pipelineresources.adoc deleted file mode 100644 index 29f3e549d649..000000000000 --- a/modules/op-defining-and-creating-pipelineresources.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="defining-and-creating-pipelineresources_{context}"] -= Defining and creating PipelineResources - -_PipelineResources_ are artifacts that are used as inputs or outputs of a Task. - -After you create Tasks, create PipelineResources that contain the specifics of the Git repository and the image registry to be used in the Pipeline during execution: -[NOTE] -==== -If you are not in the `pipelines-tutorial` namespace, and are using another namespace, ensure you update the front-end and back-end image resource to the correct URL with your namespace in the steps below. For example: ----- -image-registry.openshift-image-registry.svc:5000/<namespace-name>/vote-api:latest ----- -==== -[discrete] -.Procedure -. Create a PipelineResource that defines the Git repository for the front-end application: -+ ----- -$ tkn resource create -? Enter a name for a pipeline resource : ui-repo -? Select a resource type to create : git -? Enter a value for url : http://github.com/openshift-pipelines/vote-ui.git -? Enter a value for revision : release-tech-preview-1 ----- -+ -The output verifies that the `ui-repo` PipelineResource was created. -+ ----- -New git resource "ui-repo" has been created ----- - -. Create a PipelineResource that defines the {product-title} internal image registry to where you want to push the front-end image: -+ ----- -$ tkn resource create -? Enter a name for a pipeline resource : ui-image -? Select a resource type to create : image -? Enter a value for url : image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/ui:latest -? Enter a value for digest : ----- -+ -The output verifies that the `ui-image` PipelineResource was created. -+ ----- -New image resource "ui-image" has been created ----- - -. Create a PipelineResource that defines the Git repository for the back-end application: -+ ----- -$ tkn resource create -? Enter a name for a pipeline resource : api-repo -? Select a resource type to create : git -? Enter a value for url : http://github.com/openshift-pipelines/vote-api.git -? Enter a value for revision : release-tech-preview-1 ----- -+ -The output verifies that the `api-repo` PipelineResource was created. -+ ----- -New git resource "api-repo" has been created ----- - -. Create a PipelineResource that defines the {product-title} internal image registry to where you want to push the back-end image: -+ ----- -$ tkn resource create -? Enter a name for a pipeline resource : api-image -? Select a resource type to create : image -? Enter a value for url : image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/api:latest -? Enter a value for digest : ----- -+ -The output verifies that the `api-image` PipelineResource was created. -+ ----- -New image resource "api-image" has been created ----- - -. View the list of `resources` created: -+ ----- -$ tkn resource list ----- -+ -The output lists all the PipelineResource that were created. -+ ----- -NAME TYPE DETAILS -api-repo git url: http://github.com/openshift-pipelines/vote-api.git -ui-repo git url: http://github.com/openshift-pipelines/vote-ui.git -api-image image url: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/api:latest -ui-image image url: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/ui:latest ----- diff --git a/modules/op-deleting-pipelines.adoc b/modules/op-deleting-pipelines.adoc deleted file mode 100644 index fe0669713c3c..000000000000 --- a/modules/op-deleting-pipelines.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/working-with-pipelines-using-the-developer-perspective.adoc - -[id="op-deleting-pipelines_{context}"] -= Deleting Pipelines - -You can delete the Pipelines in your cluster using the *Developer* perspective of the web console. - -.Procedure -. In the *Pipelines* view of the *Developer* perspective, click the *Options* {Kebab} menu adjoining a Pipeline, and select *Delete Pipeline*. -. In the *Delete Pipeline* confirmation prompt, click *Delete* to confirm the deletion. diff --git a/modules/op-deleting-the-pipelines-component-and-custom-resources.adoc b/modules/op-deleting-the-pipelines-component-and-custom-resources.adoc deleted file mode 100644 index 5191c3369871..000000000000 --- a/modules/op-deleting-the-pipelines-component-and-custom-resources.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// */openshift_pipelines/uninstalling-pipelines.adoc - -[id='op-deleting-the-pipelines-component-and-custom-resources_{context}'] -= Deleting the {pipelines-title} components and Custom Resources - -Delete the Custom Resources (CRs) created by default during installation of the {pipelines-title} Operator. - -[discrete] -.Procedure -. In the *Administrator* perspective of the web console, navigate to *Administration* -> *Custom Resource Definition*. - -. Type `config.operator.tekton.dev` in the *Filter by name* box to search for the {pipelines-title} Operator CRs. - -. Click *CRD Config* to see the *Custom Resource Definition Details* page. - -. Click the *Actions* drop-down menu and select *Delete Custom Resource Definition*. - -+ -[NOTE] -==== -Deleting the CRs will delete the {pipelines-title} components, and all the Tasks and Pipelines on the cluster will be lost. -==== - -. Click *Delete* to confirm the deletion of the CRs. diff --git a/modules/op-editing-pipelines.adoc b/modules/op-editing-pipelines.adoc deleted file mode 100644 index dd04d278824a..000000000000 --- a/modules/op-editing-pipelines.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/working-with-pipelines-using-the-developer-perspective.adoc - -[id="op-editing-pipelines_{context}"] -= Editing Pipelines - -You can edit the Pipelines in your cluster using the *Developer* perspective of the web console: - -.Procedure - -. In the *Pipelines* view of the *Developer* perspective, select the Pipeline you want to edit to see the details of the Pipeline. -In the *Pipeline Details* page, click *Actions* and select *Edit Pipeline*. -. In the *Pipeline Builder* page: -* You can add additional Tasks, parameters, or resources to the Pipeline. -* You can click the Task you want to modify to see the Task details in the side panel and modify the required Task details, such as the display name, parameters and resources. -* Alternatively, to delete the Task, click the Task, and in the side panel, click *Actions* and select *Remove Task*. -. Click *Save* to save the modified Pipeline. diff --git a/modules/op-installing-pipelines-operator-in-web-console.adoc b/modules/op-installing-pipelines-operator-in-web-console.adoc deleted file mode 100644 index f44af1f46cae..000000000000 --- a/modules/op-installing-pipelines-operator-in-web-console.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// */openshift_pipelines/installing-pipelines.adoc -[id="op-installing-pipelines-operator-in-web-console_{context}"] -= Installing the {pipelines-title} Operator in web console - -You can install {pipelines-title} using the Operator listed in the {product-title} OperatorHub. When you install the {pipelines-title} Operator, the custom resources (CRs) required for the pipelines configuration are automatically installed along with the Operator. - -The default Operator custom resource definition (CRD) `config.operator.tekton.dev` is now replaced by `tektonconfigs.operator.tekton.dev`. In addition, the Operator provides the following additional CRDs to individually manage OpenShift Pipelines components: - `tektonpipelines.operator.tekton.dev`, `tektontriggers.operator.tekton.dev` and `tektonaddons.operator.tekton.dev`. - -If you have OpenShift Pipelines already installed on your cluster, the existing installation is seamlessly upgraded. The Operator will replace the instance of `config.operator.tekton.dev` on your cluster with an instance of `tektonconfigs.operator.tekton.dev` and additional objects of the other CRDs as necessary. - -[WARNING] -==== -If you manually changed your existing installation, such as, changing the target namespace in the `config.operator.tekton.dev` CRD instance by making changes to the `resource name - cluster` field, then the upgrade path is not smooth. In such cases, the recommended workflow is to uninstall your installation and reinstall the {pipelines-title} Operator. -==== - -The {pipelines-title} Operator now provides the option to choose the components that you want to install by specifying profiles as part of the `TektonConfig` CR. The `TektonConfig` CR is automatically installed when the Operator is installed. -The supported profiles are: - -* Basic: This installs only Tekton pipelines. -* Default: This installs Tekton pipeline and Tekton triggers. -* All: This is the default profile used when the `TektonConfig` CR is installed. This profile installs all of the Tekton components: Tekton Pipelines, Tekton Triggers, Tekton Addons(which include `ClusterTasks`, `ClusterTriggerBindings`, `ConsoleCLIDownload`, `ConsoleQuickStart` and `ConsoleYAMLSample` resources). - -[discrete] -.Procedure - -. In the *Administrator* perspective of the web console, navigate to *Operators* -> *OperatorHub*. - -. Use the *Filter by keyword* box to search for `{pipelines-title}` Operator in the catalog. Click the *{pipelines-title}* Operator tile. - -. Read the brief description about the Operator on the *{pipelines-title}* Operator page. Click *Install*. - -. On the *Install Operator* page: -+ -.. Select *All namespaces on the cluster (default)* for the *Installation Mode*. This mode installs the Operator in the default `openshift-operators` namespace, which enables the Operator to watch and be made available to all namespaces in the cluster. - -.. Select *Automatic* for the *Approval Strategy*. This ensures that the future upgrades to the Operator are handled automatically by the Operator Lifecycle Manager (OLM). If you select the *Manual* approval strategy, OLM creates an update request. As a cluster administrator, you must then manually approve the OLM update request to update the Operator to the new version. - -.. Select an *Update Channel*. - -*** The *Stable* channel enables installation of the latest stable release of the {pipelines-title} Operator. -*** The *preview* channel enables installation of the latest preview version of the {pipelines-title} Operator, which may contain features that are not yet available from the *Stable* channel. - -. Click *Install*. You will see the Operator listed on the *Installed Operators* page. -+ -[NOTE] -==== -The Operator is installed automatically into the `openshift-operators` namespace. -==== -+ -. Verify that the *Status* is set to *Succeeded Up to date* to confirm successful installation of {pipelines-title} Operator. diff --git a/modules/op-installing-pipelines-operator-using-the-cli.adoc b/modules/op-installing-pipelines-operator-using-the-cli.adoc deleted file mode 100644 index de2c81734fe0..000000000000 --- a/modules/op-installing-pipelines-operator-using-the-cli.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_pipelines/installing-pipelines.adoc - -[id="op-installing-pipelines-operator-using-the-cli_{context}"] -= Installing the OpenShift Pipelines Operator using the CLI - -You can install {pipelines-title} Operator from the OperatorHub using the CLI. - -[discrete] -.Procedure - -. Create a Subscription object YAML file to subscribe a namespace to the {pipelines-title} Operator, -for example, `sub.yaml`: -+ -.Example Subscription -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: openshift-pipelines-operator - namespace: openshift-operators -spec: - channel: <channel name> <1> - name: openshift-pipelines-operator-rh <2> - source: redhat-operators <3> - sourceNamespace: openshift-marketplace <4> ----- -<1> Specify the channel name from where you want to subscribe the Operator -<2> Name of the Operator to subscribe to. -<3> Name of the CatalogSource that provides the Operator. -<4> Namespace of the CatalogSource. Use `openshift-marketplace` for the default OperatorHub CatalogSources. - -. Create the Subscription object: -+ ----- -$ oc apply -f sub.yaml ----- -+ -The {pipelines-title} Operator is now installed in the default target namespace `openshift-operators`. diff --git a/modules/op-installing-tkn-on-linux-using-rpm.adoc b/modules/op-installing-tkn-on-linux-using-rpm.adoc deleted file mode 100644 index e2a19fc49604..000000000000 --- a/modules/op-installing-tkn-on-linux-using-rpm.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/installing-tkn.adoc - -[id="installing-tkn-on-linux-using-rpm"] - -= Installing {pipelines-title} CLI (tkn) on Linux using an RPM - -For {op-system-base-full} version 8, you can install the {pipelines-title} CLI (`tkn`) as an RPM. - -.Prerequisites - -* You have an active {product-title} subscription on your Red Hat account. -* You have root or sudo privileges on your local system. - -.Procedure - -. Register with Red Hat Subscription Manager: -+ -[source,terminal] ----- -# subscription-manager register ----- - -. Pull the latest subscription data: -+ -[source,terminal] ----- -# subscription-manager refresh ----- - -. List the available subscriptions: -+ -[source,terminal] ----- -# subscription-manager list --available --matches '*pipelines*' ----- - -. In the output for the previous command, find the pool ID for your {product-title} subscription and attach the subscription to the registered system: -+ -[source,terminal] ----- -# subscription-manager attach --pool=<pool_id> ----- - -. Enable the repositories required by {pipelines-title}: -+ -[source,terminal] ----- -# subscription-manager repos --enable="pipelines-1.3-for-rhel-8-x86_64-rpms" ----- - -. Install the `openshift-pipelines-client` package: -+ -[source,terminal] ----- -# yum install openshift-pipelines-client ----- - -After you install the CLI, it is available using the `tkn` command: - -[source,terminal] ----- -$ tkn version ----- diff --git a/modules/op-installing-tkn-on-linux.adoc b/modules/op-installing-tkn-on-linux.adoc deleted file mode 100644 index bdfb9e792eaf..000000000000 --- a/modules/op-installing-tkn-on-linux.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/installing-tkn.adoc - -[id="installing-tkn-on-linux"] - -= Installing {pipelines-title} CLI (tkn) on Linux - -For Linux distributions, you can download the CLI directly as a `tar.gz` archive. - -.Procedure - -. Download the relevant CLI. - -* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.15.0/tkn-linux-amd64-0.15.0.tar.gz[Linux (x86_64, amd64)] - -* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.15.0/tkn-linux-s390x-0.15.0.tar.gz[Linux on IBM Z and LinuxONE (s390x)] - -* link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.15.0/tkn-linux-ppc64le-0.15.0.tar.gz[Linux on IBM Power Systems (ppc64le)] - -. Unpack the archive: -+ -[source,terminal] ----- -$ tar xvzf <file> ----- - -. Place the `tkn` binary in a directory that is on your `PATH`. - -. To check your `PATH`, run: -+ -[source,terminal] ----- -$ echo $PATH ----- diff --git a/modules/op-installing-tkn-on-macos.adoc b/modules/op-installing-tkn-on-macos.adoc deleted file mode 100644 index c024fb35842f..000000000000 --- a/modules/op-installing-tkn-on-macos.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/installing-tkn.adoc - -[id="installing-tkn-on-macos"] - -= Installing {pipelines-title} CLI (tkn) on macOS - -For macOS, the `tkn` CLI is provided as a `tar.gz` archive. - -.Procedure - -. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.15.0/tkn-macos-amd64-0.15.0.tar.gz[CLI]. - -. Unpack and unzip the archive. - -. Move the `tkn` binary to a directory on your PATH. - -. To check your `PATH`, open a terminal window and run: -+ -[source,terminal] ----- -$ echo $PATH ----- diff --git a/modules/op-installing-tkn-on-windows.adoc b/modules/op-installing-tkn-on-windows.adoc deleted file mode 100644 index 4a1034997ab8..000000000000 --- a/modules/op-installing-tkn-on-windows.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/installing-tkn.adoc - -[id="installing-tkn-on-windows"] - -= Installing {pipelines-title} CLI (tkn) on Windows - -For Windows, the `tkn` CLI is provided as a `zip` archive. - -.Procedure - -. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/pipeline/0.15.0/tkn-windows-amd64-0.15.0.zip[CLI]. - -. Unzip the archive with a ZIP program. - -. Add the location of your `tkn.exe` file to your `PATH` environment variable. - -. To check your `PATH`, open the command prompt and run the command: -+ -[source,terminal] ----- -C:\> path ----- diff --git a/modules/op-interacting-with-pipelines-using-the-developer-perspective.adoc b/modules/op-interacting-with-pipelines-using-the-developer-perspective.adoc deleted file mode 100644 index 43f2a9f89c66..000000000000 --- a/modules/op-interacting-with-pipelines-using-the-developer-perspective.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Ths module is included in the following assembly: -// -// *openshift_pipelines/working-with-pipelines-using-the-developer-perspective.adoc - -[id="op-interacting-with-pipelines-using-the-developer-perspective_{context}"] -= Interacting with pipelines using the Developer perspective - -The *Pipelines* view in the *Developer* perspective lists all the pipelines in a project, along with the following details: - -* The namespace in which the pipeline was created -* The last pipeline run -* The status of the tasks in the pipeline run -* The status of the pipeline run -* The creation time of the last pipeline run - -[Discrete] -.Procedure -. In the *Pipelines* view of the *Developer* perspective, select a project from the *Project* drop-down list to see the pipelines in that project. -. Click the required pipeline to see the *Pipeline details* page. By default, the *Details* tab opens and provides a visual representation of all the serial and parallel tasks in the pipeline. The tasks are also listed in the lower right portion of the page. You can click the listed *Tasks* to view the task details. -+ -.Pipeline details -image::op-pipeline-details.png[Pipeline details] -+ -. Optionally, in the *Pipeline details* page: -* Click the *Metrics* tab to see the following information about pipelines: -** *Pipeline Success Ratio* -** *Number of Pipeline Runs* -** *Pipeline Run Duration* -** *Task Run Duration* -+ -You can use this information to improve the pipeline workflow and eliminate issues early in the pipeline lifecycle. -+ -* Click the *YAML* tab to edit the YAML file for the pipeline. -* Click the *Pipeline Runs* tab to see the completed, running, or failed runs for the pipeline. -+ -[NOTE] -==== -The *Details* section of the *Pipeline Run Details* page displays a *Log Snippet* of the failed pipeline run. *Log Snippet* provides a general error message and a snippet of the log. A link to the *Logs* section provides quick access to the details about the failed run. -The *Log Snippet* is also displayed in the the *Details* section of the *Task Run Details* page. -==== -You can use the Options menu {kebab} to stop a running pipeline, to rerun a pipeline using the same parameters and resources as that of the previous pipeline execution, or to delete a pipeline run. -* Click the *Parameters* tab to see the parameters defined in the pipeline. You can also add or edit additional parameters, as required. -* Click the *Resources* tab to see the resources defined in the pipeline. You can also add or edit additional resources, as required. diff --git a/modules/op-mirroring-images-to-run-pipelines-in-restricted-environment.adoc b/modules/op-mirroring-images-to-run-pipelines-in-restricted-environment.adoc deleted file mode 100644 index 25c4e016ee1d..000000000000 --- a/modules/op-mirroring-images-to-run-pipelines-in-restricted-environment.adoc +++ /dev/null @@ -1,204 +0,0 @@ -// Module included in the following assemblies: -// -// pipelines/creating-applications-with-cicd-pipelines - -[id="op-mirroring-images-to-run-pipelines-in-restricted-environment_{context}"] -= Mirroring images to run pipelines in a restricted environment - - -To run OpenShift Pipelines in a disconnected cluster or a cluster provisioned in a restricted environment, you must ensure that either the Samples Operator is configured for a restricted network, or a cluster administrator has created a cluster with a mirrored registry. - -The following procedure uses the `pipelines-tutorial` example to create a pipeline for an application in a restricted environment using a cluster with a mirrored registry. To ensure that the `pipelines-tutorial` example works in a restricted environment, you must mirror the respective builder images from the mirror registry for the front-end interface, `vote-ui`; back-end interface, `vote-api`; and the `cli`. - -.Procedure - -. Mirror the builder image from the mirror registry for the front-end interface, `vote-ui`. -.. Verify that the required images tag is not imported: -+ -[source,terminal] ----- -$ oc describe imagestream python -n openshift ----- -+ -.Example output -[source,terminal] ----- -Name: python -Namespace: openshift -[...] - -3.8-ubi8 (latest) - tagged from registry.redhat.io/ubi8/python-38:latest - prefer registry pullthrough when referencing this tag - - Build and run Python 3.8 applications on UBI 8. For more information about using this builder image, including OpenShift considerations, see https://github.com/sclorg/s2i-python-container/blob/master/3.8/README.md. - Tags: builder, python - Supports: python:3.8, python - Example Repo: https://github.com/sclorg/django-ex.git - -[...] ----- - -.. Mirror the supported image tag to the private registry: -+ -[source,terminal] ----- -$ oc image mirror registry.redhat.io/ubi8/python-38:latest <mirror-registry>:<port>/ubi8/python-38 ----- - -.. Import the image: -+ -[source,terminal] ----- -$ oc tag <mirror-registry>:<port>/ubi8/python-38 python:latest --scheduled -n openshift ----- -+ -You must periodically re-import the image. The `--scheduled` flag enables automatic re-import of the image. - -.. Verify that the images with the given tag have been imported: -+ -[source,terminal] ----- -$ oc describe imagestream python -n openshift ----- -+ -.Example output -[source,terminal] ----- -Name: python -Namespace: openshift -[...] - -latest - updates automatically from registry <mirror-registry>:<port>/ubi8/python-38 - - * <mirror-registry>:<port>/ubi8/python-38@sha256:3ee3c2e70251e75bfeac25c0c33356add9cc4abcbc9c51d858f39e4dc29c5f58 - -[...] ----- - -. Mirror the builder image from the mirror registry for the back-end interface, `vote-api`. -.. Verify that the required images tag is not imported: -+ -[source,terminal] ----- -$ oc describe imagestream golang -n openshift ----- -+ -.Example output -[source,terminal] ----- -Name: golang -Namespace: openshift -[...] - -1.14.7-ubi8 (latest) - tagged from registry.redhat.io/ubi8/go-toolset:1.14.7 - prefer registry pullthrough when referencing this tag - - Build and run Go applications on UBI 8. For more information about using this builder image, including OpenShift considerations, see https://github.com/sclorg/golang-container/blob/master/README.md. - Tags: builder, golang, go - Supports: golang - Example Repo: https://github.com/sclorg/golang-ex.git - -[...] ----- - -.. Mirror the supported image tag to the private registry: -+ -[source,terminal] ----- -$ oc image mirror registry.redhat.io/ubi8/go-toolset:1.14.7 <mirror-registry>:<port>/ubi8/go-toolset ----- - -.. Import the image: -+ -[source,terminal] ----- -$ oc tag <mirror-registry>:<port>/ubi8/go-toolset golang:latest --scheduled -n openshift ----- -+ -You must periodically re-import the image. The `--scheduled` flag enables automatic re-import of the image. - -.. Verify that the images with the given tag have been imported: -+ -[source,terminal] ----- -$ oc describe imagestream golang -n openshift ----- -+ -.Example output -[source,terminal] ----- -Name: golang -Namespace: openshift -[...] - -latest - updates automatically from registry <mirror-registry>:<port>/ubi8/go-toolset - - * <mirror-registry>:<port>/ubi8/go-toolset@sha256:59a74d581df3a2bd63ab55f7ac106677694bf612a1fe9e7e3e1487f55c421b37 - -[...] ----- - -. Mirror the builder image from the mirror registry for the `cli`. -.. Verify that the required images tag is not imported: -+ -[source,terminal] ----- -$ oc describe imagestream cli -n openshift ----- -+ -.Example output -[source,terminal] ----- -Name: cli -Namespace: openshift -[...] - -latest - updates automatically from registry quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:65c68e8c22487375c4c6ce6f18ed5485915f2bf612e41fef6d41cbfcdb143551 - - * quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:65c68e8c22487375c4c6ce6f18ed5485915f2bf612e41fef6d41cbfcdb143551 - -[...] ----- - -.. Mirror the supported image tag to the private registry: -+ -[source,terminal] ----- -$ oc image mirror quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:65c68e8c22487375c4c6ce6f18ed5485915f2bf612e41fef6d41cbfcdb143551 <mirror-registry>:<port>/openshift-release-dev/ocp-v4.0-art-dev:latest ----- - -.. Import the image: -+ -[source,terminal] ----- -$ oc tag <mirror-registry>:<port>/openshift-release-dev/ocp-v4.0-art-dev cli:latest --scheduled -n openshift ----- -+ -You must periodically re-import the image. The `--scheduled` flag enables automatic re-import of the image. - -.. Verify that the images with the given tag have been imported: -+ -[source,terminal] ----- -$ oc describe imagestream cli -n openshift ----- -+ -.Example output -[source,terminal] ----- -Name: cli -Namespace: openshift -[...] - -latest - updates automatically from registry <mirror-registry>:<port>/openshift-release-dev/ocp-v4.0-art-dev - - * <mirror-registry>:<port>/openshift-release-dev/ocp-v4.0-art-dev@sha256:65c68e8c22487375c4c6ce6f18ed5485915f2bf612e41fef6d41cbfcdb143551 - -[...] ----- diff --git a/modules/op-pipelines-concepts.adoc b/modules/op-pipelines-concepts.adoc deleted file mode 100644 index 2592ee5a2405..000000000000 --- a/modules/op-pipelines-concepts.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_pipelines/understanding-openshift-pipelines.adoc - -[id='op-pipelines-concepts_{context}'] -= {pipelines-title} concepts - -{pipelines-title} provide a set of standard Custom Resource Definitions (CRDs) that act as the building blocks from which you can assemble a CI/CD pipeline for your application. - -Task:: A Task is the smallest configurable unit in a Pipeline. It is essentially a function of inputs and outputs that form the Pipeline build. It can run individually or as a part of a Pipeline. A Pipeline includes one or more Tasks, where each Task consists of one or more Steps. Steps are a series of commands that are sequentially executed by the Task. - -Pipeline:: A Pipeline consists of a series of Tasks that are executed to construct complex workflows that automate the build, deployment, and delivery of applications. It is a collection of PipelineResources, parameters, and one or more Tasks. A Pipeline interacts with the outside world by using PipelineResources, which are added to Tasks as inputs and outputs. - -PipelineRun:: A PipelineRun is the running instance of a Pipeline. A PipelineRun initiates a Pipeline and manages the creation of a TaskRun for each Task being executed in the Pipeline. - -TaskRun:: A TaskRun is automatically created by a PipelineRun for each Task in a Pipeline. It is the result of running an instance of a Task in a Pipeline. It can also be manually created if a Task runs outside of a Pipeline. - -Workspace:: A Workspace is a storage volume that a Task requires at runtime to receive input or provide output. A Task or Pipeline declares the Workspace, and a TaskRun or PipelineRun provides the actual location of the storage volume, which mounts on the declared Workspace. This makes the Task flexible, reusable, and allows the Workspaces to be shared across multiple Tasks. - -Trigger:: A Trigger captures an external event, such as a Git pull request and processes the event payload to extract key pieces of information. This extracted information is then mapped to a set of predefined parameters, which trigger a series of tasks that may involve creation and deployment of Kubernetes resources. You can use Triggers along with Pipelines to create full-fledged CI/CD systems where the execution is defined entirely through Kubernetes resources. - -Condition:: A Condition refers to a validation or check, which is executed before a Task is run in your Pipeline. Conditions are like `if` statements which perform logical tests, with a return value of `True` or `False`. A Task is executed if all Conditions return `True`, but if any of the Conditions fail, the Task and all subsequent Tasks are skipped. You can use Conditions in your Pipeline to create complex workflows covering multiple scenarios. - -//image::openshift_pipelines_architecture.png[{pipelines-title} Architecture] diff --git a/modules/op-pipelines-operator-in-restricted-environment.adoc b/modules/op-pipelines-operator-in-restricted-environment.adoc deleted file mode 100644 index 056b38a3e9f0..000000000000 --- a/modules/op-pipelines-operator-in-restricted-environment.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// */openshift_pipelines/installing-pipelines.adoc -[id="op-pipelines-operator-in-restricted-environment_{context}"] -= {pipelines-title} Operator in a restricted environment - -The {pipelines-title} Operator enables support for installation of pipelines in a restricted network environment. - -The Operator installs a proxy webhook that sets the proxy environment variables in the containers of the pod created by tekton-controllers based on the `cluster` proxy object. It also sets the proxy environment variables in the `TektonPipelines`, `TektonTriggers`, `Controllers`, `Webhooks`, and `Operator Proxy Webhook` resources. - -By default, the proxy webhook is disabled for the `openshift-pipelines` namespace. To disable it for any other namespace, you can add the `operator.tekton.dev/disable-proxy: true` label to the `namespace` object. diff --git a/modules/op-release-notes-1-0.adoc b/modules/op-release-notes-1-0.adoc deleted file mode 100644 index b6ab4d975b8a..000000000000 --- a/modules/op-release-notes-1-0.adoc +++ /dev/null @@ -1,133 +0,0 @@ -// Module included in the following assembly: -// -// * openshift_pipelines/op-release-notes.adoc - -[id="op-release-notes-1-0_{context}"] -= Release notes for {pipelines-title} Technology Preview 1.0 - -[id="new-features-1-0_{context}"] -== New features -{pipelines-title} Technology Preview (TP) 1.0 is now available on {product-title} 4.4. {pipelines-title} TP 1.0 is updated to support: - -* Tekton Pipelines 0.11.3 -* Tekton `tkn` CLI 0.9.0 -* Tekton Triggers 0.4.0 -* ClusterTasks based on Tekton Catalog 0.11 - -In addition to the fixes and stability improvements, the following sections highlight what is new in {pipelines-title} 1.0. - -[id="pipeline-new-features-1-0_{context}"] -=== Pipelines -* Support for v1beta1 API Version. -* Support for an improved LimitRange. Previously, LimitRange was specified exclusively for the TaskRun and the PipelineRun. Now there is no need to explicitly specify the LimitRange. The minimum LimitRange across the namespace is used. -* Support for sharing data between Tasks using TaskResults and TaskParams. -* Pipelines can now be configured to not overwrite the `HOME` environment variable and `workingDir` of Steps. -* Similar to Task Steps, `sidecars` now support script mode. -* You can now specify a different scheduler name in TaskRun `podTemplate`. -* Support for variable substitution using Star Array Notation. -* Tekton Controller can now be configured to monitor an individual namespace. -* A new description field is now added to the specification of Pipeline, Task, ClusterTask, Resource, and Condition. -* Addition of proxy parameters to Git PipelineResources. - -[id="cli-new-features-1-0_{context}"] -=== Pipelines CLI - -* The `describe` subcommand is now added for the following `tkn` resources: `eventlistener`, `condition`, `triggertemplate`, `clustertask`, and `triggerbinding`. -* Support added for `v1beta1` to the following commands along with backward comptibility for `v1alpha1`: `clustertask`, `task`, `pipeline`, `pipelinerun`, and `taskrun`. -* The following commands can now list output from all namespaces using the `--all-namespaces` flag option: -** `tkn task list` -** `tkn pipeline list` -** `tkn taskrun list` -** `tkn pipelinerun list` -+ -The output of these commands is also enhanced to display information without headers using the `--no-headers` flag option. - -* You can now start a Pipeline using default parameter values by specifying `--use-param-defaults` flag in the `tkn pipelines start` command. -* Support for Workspace is now added to `tkn pipeline start` and `tkn task start` commands. -* A new `clustertriggerbinding` command is now added with the following subcommands: `describe`, `delete`, and `list`. -* You can now directly start a pipeline run using a local or remote `yaml` file. -* The `describe` subcommand now displays an enhanced and detailed output. With the addition of new fields, such as `description`, `timeout`, `param description`, and `sidecar status`, the command output now provides more detailed information about a specific `tkn` resource. -* The `tkn task log` command now displays logs directly if only one task is present in the namespace. - -[id="triggers-new-features-1-0_{context}"] -=== Triggers -* Triggers can now create both `v1alpha1` and `v1beta1` Pipeline resources. -* Support for new Common Expression Language (CEL) interceptor function - `compareSecret`. This function securely compares strings to secrets in CEL expressions. -* Support for authentication and authorization at the EventListener Trigger level. - - -[id="deprecated-features-1-0_{context}"] -== Deprecated features -The following items are deprecated in this release: - -* The environment variable `$HOME`, and variable `workingDir` in the Steps specification are deprecated and might be changed in a future release. Currently in a Step container, `HOME` and `workingDir` are overwritten to `/tekton/home` and `/workspace` respectively. -+ -In a later release, these two fields will not be modified, and will be set to values defined in the container image and Task YAML. -For this release, use flags `disable-home-env-overwrite` and `disable-working-directory-overwrite` to disable overwriting of the `HOME` and `workingDir` variables. - -* The following commands are deprecated and might be removed in the future release: -** `tkn pipeline create` -** `tkn task create` - -* The `-f` flag with the `tkn resource create` command is now deprecated. It might be removed in the future release. - -* The `-t` flag and the `--timeout` flag (with seconds format) for the `tkn clustertask create` command are now deprecated. Only duration timeout format is now supported, for example `1h30s`. These deprecated flags might be removed in the future release. - -[id="known-issues-1-4-0_{context}"] -== Known issues -* If you are upgrading from an older version of {pipelines-title}, you must delete your existing deployments before upgrading to {pipelines-title} version 1.0. To delete an existing deployment, you must first delete Custom Resources and then uninstall the {pipelines-title} Operator. For more details, see the uninstalling {pipelines-title} section. -* Submitting the same `v1alpha1` Tasks more than once results in an error. Use `oc replace` instead of `oc apply` when re-submitting a `v1alpha1` Task. -* The `buildah` ClusterTask does not work when a new user is added to a container. -+ -When the Operator is installed, the `--storage-driver` flag for the `buildah` ClusterTask is not specified, therefore the flag is set to its default value. In some cases, this causes the storage driver to be set incorrectly. When a new user is added, the incorrect storage-driver results in the failure of the `buildah` ClusterTask with the following error: -+ ----- -useradd: /etc/passwd.8: lock file already used -useradd: cannot lock /etc/passwd; try again later. ----- -+ -As a workaround, manually set the `--storage-driver` flag value to `overlay` in the `buildah-task.yaml` file: -+ -. Login to your cluster as a `cluster-admin`: -+ ----- -$ oc login -u <login> -p <password> https://openshift.example.com:6443 ----- -. Use the `oc edit` command to edit `buildah` ClusterTask: -+ ----- -$ oc edit clustertask buildah ----- -+ -The current version of the `buildah` clustertask YAML file opens in the editor set by your `EDITOR` environment variable. -. Under the `steps` field, locate the following `command` field: -+ ----- - command: ['buildah', 'bud', '--format=$(params.FORMAT)', '--tls-verify=$(params.TLSVERIFY)', '--layers', '-f', '$(params.DOCKERFILE)', '-t', '$(resources.outputs.image.url)', '$(params.CONTEXT)'] ----- - -. Replace the `command` field with the following: -+ ----- - command: ['buildah', '--storage-driver=overlay', 'bud', '--format=$(params.FORMAT)', '--tls-verify=$(params.TLSVERIFY)', '--no-cache', '-f', '$(params.DOCKERFILE)', '-t', '$(params.IMAGE)', '$(params.CONTEXT)'] ----- -. Save the file and exit. - - -+ -Alternatively, you can also modify the `buildah` ClusterTask YAML file directly on the web console by navigating to *Pipelines* -> *Cluster Tasks* -> *buildah*. Select *Edit Cluster Task* from the *Actions* menu and replace the `command` field as shown in the previous procedure. - -[id="fixed-issues-1-0_{context}"] -== Fixed issues -* Previously, the `DeploymentConfig` Task triggered a new deployment build even when an image build was already in progress. This caused the deployment of the Pipeline to fail. With this fix, the `deploy task` command is now replaced with the `oc rollout status` command which waits for the in-progress deployment to finish. -* Support for `APP_NAME` parameter is now added in Pipeline templates. -* Previously, the Pipeline template for Java S2I failed to look up the image in the registry. With this fix, the image is looked up using the existing image PipelineResources instead of the user provided `IMAGE_NAME` parameter. -* All the OpenShift Pipelines images are now based on the Red Hat Universal Base Images (UBI). -* Previously, when the Pipeline was installed in a namespace other than `tekton-pipelines`, the `tkn version` command displayed the Pipeline version as `unknown`. With this fix, the `tkn version` command now displays the correct Pipeline version in any namespace. -* The `-c` flag is no longer supported for the `tkn version` command. -* Non-admin users can now list the ClusterTriggerBindings. -* The EventListener CompareSecret function is now fixed for the CEL Interceptor. -* The `list`, `describe`, and `start` subcommands for `task` and `clustertask` now correctly display the output in case a Task and ClusterTask have the same name. -* Previously, the OpenShift Pipelines Operator modified the privileged security context constraints (SCCs), which caused an error during cluster upgrade. This error is now fixed. -* In the `tekton-pipelines` namespace, the timeouts of all TaskRuns and PipelineRuns are now set to the value of `default-timeout-minutes` field using the ConfigMap. -* Previously, the Pipelines section in the web console was not displayed for non-admin users. This issue is now resolved. diff --git a/modules/op-release-notes-1-1.adoc b/modules/op-release-notes-1-1.adoc deleted file mode 100644 index 03ccfd24340a..000000000000 --- a/modules/op-release-notes-1-1.adoc +++ /dev/null @@ -1,108 +0,0 @@ -// Module included in the following assembly: -// -// * openshift_pipelines/op-release-notes.adoc - -[id="op-release-notes-1-1_{context}"] -= Release notes for {pipelines-title} Technology Preview 1.1 - -[id="new-features-1-1_{context}"] -== New features -{pipelines-title} Technology Preview (TP) 1.1 is now available on {product-title} 4.5. {pipelines-title} TP 1.1 is updated to support: - -* Tekton Pipelines 0.14.3 -* Tekton `tkn` CLI 0.11.0 -* Tekton Triggers 0.6.1 -* ClusterTasks based on Tekton Catalog 0.14 - -In addition to the fixes and stability improvements, the following sections highlight what is new in {pipelines-title} 1.1. - -[id="pipeline-new-features-1-1_{context}"] -=== Pipelines - -* Workspaces can now be used instead of PipelineResources. It is recommended that you use Workspaces in OpenShift Pipelines, as PipelineResources are difficult to debug, limited in scope, and make Tasks less reusable. For more details on Workspaces, see Understanding OpenShift Pipelines. -* Workspace support for VolumeClaimTemplates has been added: -** The VolumeClaimTemplate for a PipelineRun and TaskRun can now be added as a volume source for Workspaces. The tekton-controller then creates a PersistentVolumeClaim (PVC) using the template that is seen as a PVC for all TaskRuns in the Pipeline. Thus you do not need to define the PVC configuration every time it binds a workspace that spans multiple tasks. -** Support to find the name of the PersistentVolumeClaim when a VolumeClaimTemplate is used as a volume source is now available using variable substitution. -* Support for improving audits: -** The `PipelineRun.Status` field now contains the status of every TaskRun in the Pipeline and the Pipeline specification used to instantiate a PipelineRun to monitor the progress of the PipelineRun. -** Pipeline results have been added to the pipeline specification and `PipelineRun` status. -** The `TaskRun.Status` field now contains the exact Task specification used to instantiate the `TaskRun`. -* Support to apply the default parameter to Conditions. -* A TaskRun created by referencing a ClusterTask now adds the `tekton.dev/clusterTask` label instead of the `tekton.dev/task` label. -* The `kubeconfigwriter` now adds the `ClientKeyData` and the `ClientCertificateData` configurations in the Resource structure to enable replacement of the pipeline resource type cluster with the kubeconfig-creator Task. -* The names of the `feature-flags` and the `config-defaults` ConfigMaps are now customizable. -* Support for HostNetwork in the PodTemplate used by TaskRun is now available. -* An Affinity Assistant is now available to support node affinity in TaskRuns that share workspace volume. By default, this is disabled on OpenShift Pipelines. -* The PodTemplate has been updated to specify `imagePullSecrets` to identify secrets that the container runtime should use to authorize container image pulls when starting a pod. -* Support for emitting warning events from the TaskRun controller if the controller fails to update the TaskRun. -* Standard or recommended k8s labels have been added to all resources to identify resources belonging to an application or component. -* The Entrypoint process is now notified for signals and these signals are then propagated using a dedicated PID Group of the Entrypoint process. -* The PodTemplate can now be set on a Task level at runtime using `TaskRunSpecs`. -* Support for emitting Kubernetes events: -** The controller now emits events for additional TaskRun lifecycle events - `taskrun started` and `taskrun running`. -** The PipelineRun controller now emits an event every time a Pipeline starts. -* In addition to the default Kubernetes events, support for CloudEvents for TaskRuns is now available. The controller can be configured to send any TaskRun events, such as create, started, and failed, as cloud events. -* Support for using the `$context.<task|taskRun|pipeline|pipelineRun>.name` variable to reference the appropriate name when in PipelineRuns and TaskRuns. -* Validation for PipelineRun parameters is now available to ensure that all the parameters required by the Pipeline are provided by the PipelineRun. This also allows PipelineRuns to provide extra parameters in addition to the required parameters. -* You can now specify Tasks within a Pipeline that will always execute before the pipeline exits, either after finishing all tasks successfully or after a Task in the Pipeline failed, using the `finally` field in the Pipeline YAML file. -* The `git-clone` ClusterTask is now available. - -[id="cli-new-features-1-1_{context}"] -=== Pipelines CLI - -* Support for embedded Trigger binding is now available to the `tkn evenlistener describe` command. -* Support to recommend subcommands and make suggestions if an incorrect subcommand is used. -* The `tkn task describe` command now auto selects the task if only one task is present in the Pipeline. -* You can now start a Task using default parameter values by specifying the `--use-param-defaults` flag in the `tkn task start` command. -* You can now specify a volumeClaimTemplate for PipelineRuns or TaskRuns using the `--workspace` option with the `tkn pipeline start` or `tkn task start` commands. -* The `tkn pipelinerun logs` command now displays logs for the final tasks listed in the `finally` section. -* Interactive mode support has now been provided to the `tkn task start` command and the `describe` subcommand for the following tkn resources: `pipeline`, `pipelinerun`, `task`, `taskrun`, `clustertask`, and `pipelineresource`. -* The `tkn version` command now displays the version of the Triggers installed in the cluster. -* The `tkn pipeline describe` command now displays parameter values and timeouts specified for Tasks used in the Pipeline. -* Support added for the `--last` option for the `tkn pipelinerun describe` and the `tkn taskrun describe` commands to describe the most recent PipelineRun or TaskRun, respectively. -* The `tkn pipeline describe` command now displays the conditions applicable to the Tasks in the Pipeline. -* You can now use the `--no-headers` and `--all-namespaces` flags with the `tkn resource list` command. - -[id="triggers-new-features-1-1_{context}"] -=== Triggers -* The following Common Expression Language (CEL) functions are now available: -** `parseURL` to parse and extract portions of a URL -** `parseJSON` to parse JSON value types embedded in a string in the `payload` field of the `deployment` webhook -* A new interceptor for webhooks from Bitbucket has been added. -* EventListeners now display the `Address URL` and the `Available status` as additional fields when listed with the `kubectl get` command. -* TriggerTemplate params now use the `$(tt.params.<paramName>)` syntax instead of `$(params.<paramName>)` to reduce the confusion between TriggerTemplate and ResourceTemplates params. -* You can now add `tolerations` in the EventListener CRD to ensure that EventListeners are deployed with the same configuration even if all nodes are tainted due to security or management issues. -* You can now add a Readiness Probe for EventListener Deployment at `URL/live`. -* Support for embedding TriggerBinding specifications in EventListener Triggers. -* Trigger resources are now annotated with the recommended `app.kubernetes.io` labels. - - -[id="deprecated-features-1-1_{context}"] -== Deprecated features -The following items are deprecated in this release: - -* The `--namespace` or `-n` flags for all cluster-wide commands, including the `clustertask` and `clustertriggerbinding` commands, are deprecated. It will be removed in a future release. -* The `name` field in `triggers.bindings` within an EventListener has been deprecated in favor of the `ref` field and will be removed in a future release. -* Variable interpolation in TriggerTemplates using `$(params)` has been deprecated in favor of using `$(tt.params)` to reduce confusion with the Pipeline variable interpolation syntax. The `$(params.<paramName>)` syntax will be removed in a future release. -* The `tekton.dev/task` label is deprecated on ClusterTasks. -* The `TaskRun.Status.ResourceResults.ResourceRef` field is deprecated and will be removed. -* The `tkn pipeline create`, `tkn task create`, and `tkn resource create -f` subcommands have been removed. -* Namespace validation has been removed from `tkn` commands. -* The default timeout of `1h` and the `-t` flag for the `tkn ct start` command have been removed. -* The `s2i` ClusterTask has been deprecated. - - -[id="known-issues-1-1_{context}"] -== Known issues -* Conditions do not support Workspaces. -* The `--workspace` option and the interactive mode is not supported for the `tkn clustertask start` command. -* Support of backward compatibility for `$(params.<paramName>)` forces you to use TriggerTemplates with pipeline specific params as the Triggers webhook is unable to differentiate Trigger params from pipelines params. -* Pipeline metrics report incorrect values when you run a promQL query for `tekton_taskrun_count` and `tekton_taskrun_duration_seconds_count`. -* PipelineRuns and TaskRuns continue to be in the `Running` and `Running(Pending)` states respectively even when a non existing PVC name is given to a Workspace. - -[id="fixed-issues-1-1_{context}"] -== Fixed issues -* Previously, the `tkn task delete <name> --trs` command would delete both the Task and ClusterTask if the name of the Task and ClusterTask were the same. With this fix, the command deletes only the TaskRuns that are created by the Task `<name>`. -* Previously the `tkn pr delete -p <name> --keep 2` command would disregard the `-p` flag when used with the `--keep` flag and would delete all the PipelineRuns except the latest two. With this fix, the command deletes only the PipelineRuns that are created by the Pipeline `<name>`, except for the latest two. -* The `tkn triggertemplate describe` output now displays ResourceTemplates in a table format instead of YAML format. -* Previously the `buildah` ClusterTask failed when a new user was added to a container. With this fix, the issue has been resolved. diff --git a/modules/op-release-notes-1-2.adoc b/modules/op-release-notes-1-2.adoc deleted file mode 100644 index b1e09e479d47..000000000000 --- a/modules/op-release-notes-1-2.adoc +++ /dev/null @@ -1,132 +0,0 @@ -// Module included in the following assembly: -// -// * openshift_pipelines/op-release-notes.adoc - -[id="op-release-notes-1-2_{context}"] -= Release notes for {pipelines-title} Technology Preview 1.2 - -[id="new-features-1-2_{context}"] -== New features -{pipelines-title} Technology Preview (TP) 1.2 is now available on {product-title} 4.6. {pipelines-title} TP 1.2 is updated to support: - -* Tekton Pipelines 0.16.3 -* Tekton `tkn` CLI 0.13.1 -* Tekton Triggers 0.8.1 -* ClusterTasks based on Tekton Catalog 0.16 -* IBM Power Systems on {product-title} 4.6 -* IBM Z and LinuxONE on {product-title} 4.6 - -In addition to the fixes and stability improvements, the following sections highlight what is new in {pipelines-title} 1.2. - -[id="pipeline-new-features-1-2_{context}"] -=== Pipelines - -* This release of {pipelines-title} adds support for a disconnected installation. - -+ -[NOTE] -==== -Installations in restricted environments are currently not supported on IBM Power Systems, IBM Z, and LinuxONE. -==== - -* You can now use the `when` field, instead of `conditions`, to run a task only when certain criteria are met. The key components of `WhenExpressions` are `Input`, `Operator`, and `Values`. If all the `WhenExpressions` evaluate to `True`, then the task is run. If any of the `WhenExpressions` evaluate to `False`, the task is skipped. -* Step statuses are now updated if a task run is canceled or times out. -* Support for Git Large File Storage (LFS) is now available to build the base image used by `git-init`. -* You can now use the `taskSpec` field to specify metadata, such as labels and annotations, when a task is embedded in a pipeline. -* Cloud events are now supported by pipeline runs. Retries with `backoff` are now enabled for cloud events sent by the cloud event pipeline resource. -* You can now set a default `Workspace` configuration for any workspace that a `Task` resource declares, but that a `TaskRun` resource does not explicitly provide. -* Support is available for namespace variable interpolation for the `PipelineRun` namespace and `TaskRun` namespace. -* Validation for `TaskRun` objects is now added to check that not more than one persistent volume claim workspace is used when a `TaskRun` resource is associated with an Affinity Assistant. If more than one persistent volume claim workspace is used, the task run fails with a `TaskRunValidationFailed` condition. Note that by default, the Affinity Assistant is disabled in {pipelines-title}, so you will need to enable the assistant to use it. - -[id="cli-new-features-1-2_{context}"] -=== Pipelines CLI - -* The `tkn task describe`, `tkn taskrun describe`, `tkn clustertask describe`, `tkn pipeline describe`, and `tkn pipelinerun describe` commands now: -** Automatically select the `Task`, `TaskRun`, `ClusterTask`, `Pipeline` and `PipelineRun` resource, respectively, if only one of them is present. -** Display the results of the `Task`, `TaskRun`, `ClusterTask`, `Pipeline` and `PipelineRun` resource in their outputs, respectively. -** Display workspaces declared in the `Task`, `TaskRun`, `ClusterTask`, `Pipeline` and `PipelineRun` resource in their outputs, respectively. -* You can now use the `--prefix-name` option with the `tkn clustertask start` command to specify a prefix for the name of a task run. -* Interactive mode support has now been provided to the `tkn clustertask start` command. -* You can now specify `PodTemplate` properties supported by pipelines using local or remote file definitions for `TaskRun` and `PipelineRun` objects. -* You can now use the `--use-params-defaults` option with the `tkn clustertask start` command to use the default values set in the `ClusterTask` configuration and create the task run. -* The `--use-param-defaults` flag for the `tkn pipeline start` command now prompts the interactive mode if the default values have not been specified for some of the parameters. - -[id="triggers-new-features-1-2_{context}"] -=== Triggers - -* The Common Expression Language (CEL) function named `parseYAML` has been added to parse a YAML string into a map of strings. -* Error messages for parsing CEL expressions have been improved to make them more granular while evaluating expressions and when parsing the hook body for creating the evaluation environment. -* Support is now available for marshaling boolean values and maps if they are used as the values of expressions in a CEL overlay mechanism. -* The following fields have been added to the `EventListener` object: -** The `replicas` field enables the event listener to run more than one pod by specifying the number of replicas in the YAML file. -** The `NodeSelector` field enables the `EventListener` object to schedule the event listener pod to a specific node. -* Webhook interceptors can now parse the `EventListener-Request-URL` header to extract parameters from the original request URL being handled by the event listener. -* Annotations from the event listener can now be propagated to the deployment, services, and other pods. Note that custom annotations on services or deployment are overwritten, and hence, must be added to the event listener annotations so that they are propagated. -* Proper validation for replicas in the `EventListener` specification is now available for cases when a user specifies the `spec.replicas` values as `negative` or `zero`. -* You can now specify the `TriggerCRD` object inside the `EventListener` spec as a reference using the `TriggerRef` field to create the `TriggerCRD` object separately and then bind it inside the `EventListener` spec. -* Validation and defaults for the `TriggerCRD` object are now available. - -[id="deprecated-features-1-2_{context}"] -== Deprecated features - -* `$(params)` are now removed and replaced by `$(tt.params)` to avoid confusion between the `resourcetemplate` and `triggertemplate` parameters. -* The `ServiceAccount` reference of the optional `EventListenerTrigger`-based authentication level has changed from an object reference to a `ServiceAccountName` string. This ensures that the `ServiceAccount` reference is in the same namespace as the `EventListenerTrigger` object. -* The `Conditions` custom resource definition (CRD) is now deprecated; use the `WhenExpressions` CRD instead. -* The `PipelineRun.Spec.ServiceAccountNames` object is being deprecated and replaced by the `PipelineRun.Spec.TaskRunSpec[].ServiceAccountName` object. - -[id="known-issues-1-2_{context}"] -== Known issues - -* This release of {pipelines-title} adds support for a disconnected installation. However, some images used by the cluster tasks must be mirrored for them to work in disconnected clusters. -* Pipelines in the `openshift` namespace are not deleted after you uninstall the {pipelines-title} Operator. Use the `oc delete pipelines -n openshift --all` command to delete the pipelines. -* Uninstalling the {pipelines-title} Operator does not remove the event listeners. -+ -As a workaround, to remove the `EventListener` and `Pod` CRDs: -+ -. Edit the `EventListener` object with the `foregroundDeletion` finalizers: -+ -[source,terminal] ----- -$ oc patch el/<eventlistener_name> -p '{"metadata":{"finalizers":["foregroundDeletion"]}}' --type=merge ----- -+ -For example: -+ -[source,terminal] ----- -$ oc patch el/github-listener-interceptor -p '{"metadata":{"finalizers":["foregroundDeletion"]}}' --type=merge ----- -+ -. Delete the `EventListener` CRD: -+ -[source,terminal] ----- -$ oc patch crd/eventlisteners.triggers.tekton.dev -p '{"metadata":{"finalizers":[]}}' --type=merge ----- - -* When you run a multi-arch container image task without command specification on an IBM Power Systems (ppc64le) or IBM Z (s390x) cluster, the `TaskRun` resource fails with the following error: -+ -[source,terminal] ----- -Error executing command: fork/exec /bin/bash: exec format error ----- -+ -As a workaround, use an architecture specific container image or specify the sha256 digest to point to the correct architecture. -To get the sha256 digest enter: -+ -[source,terminal] ----- -$ skopeo inspect --raw <image_name>| jq '.manifests[] | select(.platform.architecture == "<architecture>") | .digest' ----- - -[id="fixed-issues-1-2_{context}"] -== Fixed issues - -* A simple syntax validation to check the CEL filter, overlays in the Webhook validator, and the expressions in the interceptor has now been added. -* Triggers no longer overwrite annotations set on the underlying deployment and service objects. -* Previously, an event listener would stop accepting events. This fix adds an idle timeout of 120 seconds for the `EventListener` sink to resolve this issue. -* Previously, canceling a pipeline run with a `Failed(Canceled)` state gave a success message. This has been fixed to display an error instead. -* The `tkn eventlistener list` command now provides the status of the listed event listeners, thus enabling you to easily identify the available ones. -* Consistent error messages are now displayed for the `triggers list` and `triggers describe` commands when triggers are not installed or when a resource cannot be found. -* Previously, a large number of idle connections would build up during cloud event delivery. The `DisableKeepAlives: true` parameter was added to the `cloudeventclient` config to fix this issue. Thus, a new connection is set up for every cloud event. -* Previously, the `creds-init` code would write empty files to the disk even if credentials of a given type were not provided. This fix modifies the `creds-init` code to write files for only those credentials that have actually been mounted from correctly annotated secrets. diff --git a/modules/op-release-notes-1-3.adoc b/modules/op-release-notes-1-3.adoc deleted file mode 100644 index 277af7ff8f24..000000000000 --- a/modules/op-release-notes-1-3.adoc +++ /dev/null @@ -1,153 +0,0 @@ -// Module included in the following assembly: -// -// * openshift_pipelines/op-release-notes.adoc - -[id="op-release-notes-1-3_{context}"] -= Release notes for {pipelines-title} Technology Preview 1.3 - -[id="new-features-1-3_{context}"] -== New features -{pipelines-title} Technology Preview (TP) 1.3 is now available on {product-title} 4.7. {pipelines-title} TP 1.3 is updated to support: - -* Tekton Pipelines 0.19.0 -* Tekton `tkn` CLI 0.15.0 -* Tekton Triggers 0.10.2 -* ClusterTasks based on Tekton Catalog 0.19.0 -* IBM Power Systems on {product-title} 4.7 -* IBM Z and LinuxONE on {product-title} 4.7 - -In addition to the fixes and stability improvements, the following sections highlight what is new in {pipelines-title} 1.3. - -[id="pipeline-new-features-1-3_{context}"] -=== Pipelines - -* Tasks that build images, such as S2I and Buildah tasks, now emit a URL of the image built that includes the image SHA. - -* Conditions in pipeline tasks that reference custom tasks are disallowed because the `Conditions` custom resource definition (CRD) has been deprecated. - -* Variable expansion is now added in the `Task` CRD for the following fields: -`spec.steps[].imagePullPolicy` and `spec.sidecar[].imagePullPolicy`. - -* You can disable the built-in credential mechanism in Tekton by setting the `disable-creds-init` feature-flag to `true`. - -* Resolved `When` expressions are now listed in the `Skipped Tasks` and the `Task Runs` sections in the `Status` field of the `PipelineRun` configuration. - -* The `git init` command can now clone recursive submodules. - -* A `Task` CR author can now specify a timeout for a step in the `Task` spec. - -* You can now base the entry point image on `distroless/static:nonroot` and give it a mode to copy itself to the destination, without relying on the `cp` command being present in the base image. - -* You can now use the configuration flag `require-git-ssh-secret-known-hosts` to disallow omitting known hosts in the Git SSH secret. When the flag value is set to `true`, you must include the `known_host` field in the Git SSH secret. The default value for the flag is `false`. - -* The concept of optional workspaces is now introduced. A task or pipeline might declare a workspace optional and conditionally change their behavior based on its presence. A task run or pipeline run might also omit that workspace, thereby modifying the task or pipeline behavior. The default task run workspaces are not added in place of an omitted optional workspace. - -* Credentials initialization in Tekton now detects an SSH credential that is used with a non-SSH URL, and vice versa in Git pipeline resources, and logs a warning in the step containers. - -* The task run controller emits a warning event if the affinity specified by the pod template is overwritten by the affinity assistant. - -* The task run reconciler now records metrics for cloud events that are emitted once a task run is completed. This includes retries. - -[id="cli-new-features-1-3_{context}"] -=== Pipelines CLI - -* Support for `--no-headers flag` is now added to the following commands: -`tkn condition list`,`tkn triggerbinding list`,`tkn eventlistener list`,`tkn clustertask list`, `tkn clustertriggerbinding list`. - -* When used together, the `--last` or `--use` options override the `--prefix-name` and `--timeout` options. - -* The `tkn eventlistener logs` command is now added to view the `EventListener` logs. - -* The `tekton hub` commands are now integrated into the `tkn` CLI. - -* The `--nocolour` option is now changed to `--no-color`. - -* The `--all-namespaces` flag is added to the following commands: -`tkn triggertemplate list`, `tkn condition list`, `tkn triggerbinding list`, `tkn eventlistener list`. - -[id="triggers-new-features-1-3_{context}"] -=== Triggers - -* You can now specify your resource information in the `EventListener` template. - -* It is now mandatory for `EventListener` service accounts to have the `list` and `watch` verbs, in addition to the `get` verb for all the triggers resources. This enables you to use `Listers` to fetch data from `EventListeners`, `Triggers`, `TriggerBindings`, `TriggerTemplates`, and `ClusterTriggerBindings` resources. You can use this feature to create a `Sink` object rather than specifying multiple informers, and directly make calls to the API server. - -* A new Interceptor interface is added to support immutable input event bodies. Interceptors can now add data or fields to a new `extensions` field, and cannot modify the input bodies making them immutable. The CEL interceptor uses this new Interceptor interface. - -* A `namespaceSelector` field is added to the `EventListener` resource. Use it to specify the namespaces from where the `EventListener` resource can fetch the `Trigger` object for processing events. To use the `namespaceSelector` field, the service account for the `EventListener` must have a cluster role. - -* The triggers `EventListener` resource now supports end-to-end secure connection to the `eventlistener` pod. - -* The escaping parameters behavior in the `TriggerTemplates` resource by replacing `"` with `\"` is now removed. - -* A new `resources` field, supporting Kubernetes resources, is introduced as part of the `EventListener` spec. - -* A new functionality for the CEL interceptor, with support for upper and lower-casing of ASCII strings, is added. - -* You can embed `TriggerBinding` resources by using the `name` and `value` fields in a trigger, or an event listener. - -* The `PodSecurityPolicy` configuration is updated to run in restricted environments. It ensures that containers must run as non-root. In addition, the role-based access control for using the pod security policy is moved from cluster-scoped to namespace-scoped. This ensures that the triggers cannot use other pod security policies that are unrelated to a namespace. - -* Support for embedded trigger templates is now added. You can either use the `name` field to refer to an embedded template or embed the template inside the `spec` field. - - -[id="deprecated-features-1-3_{context}"] -== Deprecated features - -* Pipeline templates that use `PipelineResources` CRDs are now deprecated and will be removed in a future release. - -* The `template.name` field is deprecated in favor of the `template.ref` field and will be removed in a future release. - -* The `-c` shorthand for the `--check` command has been removed. In addition, global `tkn` flags are added to the `version` command. - - -[id="known-issues-1-3_{context}"] -== Known issues - -* CEL overlays add fields to a new top-level `extensions` function, instead of modifying the incoming event body. `TriggerBinding` resources can access values within this new `extensions` function using the `$(extensions.<key>)` syntax. Update your binding to use `$(extensions.<key>)` instead of `$(body.<overlay-key>)` . - -* The escaping parameters behavior by replacing `"` with `\"` is now removed. If you need to retain the old escaping parameters behavior add the `tekton.dev/old-escape-quotes: true"` annotation to your `TriggerTemplate` specification. - -* You can embed `TriggerBinding` resources by using the `name` and `value` fields inside a trigger or an event listener. However, you cannot specify both `name` and `ref` fields for a single binding. Use the `ref` field to refer to a `TriggerBinding` resource and the `name` field for embedded bindings. - -* An interceptor cannot attempt to reference a `Secret` outside the namespace of an `EventListener`. You must include secrets in the namespace of the `EventListener`. - -* In Triggers 0.9.0 and later, if a body or header based `TriggerBinding` parameter is missing or malformed in an event payload, the default values are used instead of displaying an error. - -* `Tasks` and `Pipelines` created with `WhenExpressions` using Tekton Pipelines 0.16.x must be reapplied to fix their JSON annotations. - -* When a pipeline accepts an optional workspace and gives it to a `PipelineTask`, the `PipelineRun` stalls if the workspace is not provided. - -* To use the Buildah cluster task in a disconnected environment, ensure that the Dockerfile uses an internal image stream as the base image, and then use it in the same manner as any S2I cluster task. - - -[id="fixed-issues-1-3_{context}"] -== Fixed issues - -* Extensions added by a CEL Interceptor are passed on to webhook interceptors by adding the `Extensions` field within the event body. - -* The activity timeout for log readers is now configurable using the `LogOptions` field. However, the default behavior of timeout in 10 seconds is retained. - -* The `log` command ignores the `--follow` flag when a task run or pipeline run is complete, and reads available logs instead of live logs. - -* References to the following Tekton resources: `EventListener`, `TriggerBinding`, `ClusterTriggerBinding`, `Condition`, and `TriggerTemplate` are now standardized and made consistent across all user-facing messages in `tkn` commands. - -* Previously, if you started a canceled task run or pipeline run with the `--use-taskrun <canceled-task-run-name>`, `--use-pipelinerun <canceled-pipeline-run-name>` or `--last` flags, the new run would be canceled. This bug is now fixed. - -* The `tkn pr desc` command is now enhanced to ensure that it does not fail in case of pipeline runs with conditions. - -* When you delete a task run using `tkn tr delete` with the `--task` option, and a cluster task exists with the same name, the task runs for the cluster task also gets deleted. As a workaround, filter the task runs by using the `TaskRefKind` field. - -* The `tkn triggertemplate describe` command would display only part of the `apiVersion` in the output. For example, only `triggers.tekton.dev` was displayed instead of `triggers.tekton.dev/v1alpha1`. This bug is now fixed. - -* The webhook, under certain conditions, would fail to acquire a lease and not function correctly. This bug is now fixed. - -* Pipelines with `When` expressions created in v0.16.3 can now be run in v0.17.1 and later. After an upgrade, you do not need to reapply pipeline definitions created in previous versions because both the uppercase and lowercase first letters for the annotations are now supported. - -* By default, the `leader-election-ha` is now enabled for high availability. When the controller flag `disable-ha` is set to `true`, it disables high availability support. - -* Issues with duplicate cloud events are now fixed. Cloud events are now sent only when a condition changes the state, reason, or message. - -* When a service account name is missing from a `PipelineRun` or `TaskRun` spec, the controller uses the service account name from the `config-defaults` config map. If the service account name is also missing in the `config-defaults` config map, the controller now sets it to `default` in the spec. - -* Validation for compatibility with the affinity assistant is now supported when the same persistent volume claim is used for multiple workspaces, but with different subpaths. diff --git a/modules/op-running-a-pipeline.adoc b/modules/op-running-a-pipeline.adoc deleted file mode 100644 index 79c5bab7498d..000000000000 --- a/modules/op-running-a-pipeline.adoc +++ /dev/null @@ -1,85 +0,0 @@ -// This module is included in the following assembly: -// -// // *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="running-a-pipeline_{context}"] -= Running a Pipeline - -A `PipelineRun` resource starts a pipeline and ties it to the Git and image resources that should be used for the specific invocation. It automatically creates and starts the `TaskRun` resources for each task in the pipeline. - -[discrete] -.Procedure - -. Start the pipeline for the back-end application: -+ -[source,yaml,subs="attributes+"] ----- -$ tkn pipeline start build-and-deploy \ - -w name=shared-workspace,volumeClaimTemplateFile=https://raw.githubusercontent.com/openshift/pipelines-tutorial/{pipelines-ver}/01_pipeline/03_persistent_volume_claim.yaml \ - -p deployment-name=vote-api \ - -p git-url=https://github.com/openshift-pipelines/vote-api.git \ - -p IMAGE=image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/vote-api ----- -+ -The previous command uses a volume claim template, which creates a persistent volume claim for the pipeline execution. - -. To track the progress of the pipeline run, enter the following command:: -+ -[source,yaml] ----- -$ tkn pipelinerun logs <pipelinerun_id> -f ----- -+ -The <pipelinerun_id> in the above command is the ID for the `PipelineRun` that was returned in the output of the previous command. - -. Start the Pipeline for the front-end application: -+ -[source,yaml,subs="attributes+"] ----- -$ tkn pipeline start build-and-deploy \ - -w name=shared-workspace,volumeClaimTemplateFile=https://raw.githubusercontent.com/openshift/pipelines-tutorial/{pipelines-ver}/01_pipeline/03_persistent_volume_claim.yaml \ - -p deployment-name=vote-ui \ - -p git-url=https://github.com/openshift-pipelines/vote-ui.git \ - -p IMAGE=image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/vote-ui ----- - -. To track the progress of the pipeline run, enter the following command: -+ -[source,yaml] ----- -$ tkn pipelinerun logs <pipelinerun_id> -f ----- -+ -The <pipelinerun_id> in the above command is the ID for the `PipelineRun` that was returned in the output of the previous command. - -. After a few minutes, use `tkn pipelinerun list` command to verify that the Pipeline ran successfully by listing all the PipelineRuns: -+ -[source,yaml] ----- -$ tkn pipelinerun list ----- -+ -The output lists the PipelineRuns: -+ -[source,yaml] ----- - - NAME STARTED DURATION STATUS - build-and-deploy-run-xy7rw 1 hour ago 2 minutes Succeeded - build-and-deploy-run-z2rz8 1 hour ago 19 minutes Succeeded ----- - -. Get the application route: -+ -[source,yaml] ----- -$ oc get route vote-ui --template='http://{{.spec.host}}/' ----- -Note the output of the previous command. You can access the application using this route. - -. To rerun the last pipeline run, using the pipeline resources and service account of the previous pipeline, run: -+ -[source,yaml] ----- -$ tkn pipeline start build-and-deploy --last ----- diff --git a/modules/op-starting-pipelines.adoc b/modules/op-starting-pipelines.adoc deleted file mode 100644 index d69cb0f981ef..000000000000 --- a/modules/op-starting-pipelines.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/working-with-pipelines-using-the-developer-perspective.adoc - -[id="op-starting-pipelines_{context}"] -= Starting pipelines - -After you create a pipeline, you need to start it to execute the included tasks in the defined sequence. You can start a pipeline from the *Pipelines* view, the *Pipeline Details* page, or the *Topology* view. - -.Procedure -To start a pipeline using the *Pipelines* view: - -. In the *Pipelines* view of the *Developer* perspective, click the *Options* {Kebab} menu adjoining a pipeline, and select *Start*. -. The *Start Pipeline* dialog box displays the *Git Resources* and the *Image Resources* based on the pipeline definition. -+ -[NOTE] -==== -For pipelines created using the *From Git* option, the *Start Pipeline* dialog box also displays an `APP_NAME` field in the *Parameters* section, and all the fields in the dialog box are prepopulated by the pipeline template. -==== -+ -.. If you have resources in your namespace, the *Git Resources* and the *Image Resources* fields are prepopulated with those resources. If required, use the drop-downs to select or create the required resources and customize the pipeline run instance. -. Optional: Modify the *Advanced Options* to add the credentials that authenticate the specified private Git server or the image registry. -+ -.. Under *Advanced Options*, click *Show Credentials Options* and select *Add Secret*. -.. In the *Create Source Secret* section, specify the following: - -... A unique *Secret Name* for the secret. -... In the *Designated provider to be authenticated* section, specify the provider to be authenticated in the *Access to* field, and the base *Server URL*. -... Select the *Authentication Type* and provide the credentials: -* For the *Authentication Type* `Image Registry Credentials`, specify the *Registry Server Address* that you want to authenticate, and provide your credentials in the *Username*, *Password*, and *Email* fields. -+ -Select *Add Credentials* if you want to specify an additional *Registry Server Address*. - -* For the *Authentication Type* `Basic Authentication`, specify the values for the *UserName* and *Password or Token* fields. -* For the *Authentication Type* `SSH Keys`, specify the value of the *SSH Private Key* field. -... Select the check mark to add the secret. - -+ -You can add multiple secrets based upon the number of resources in your pipeline. - -. Click *Start* to start the pipeline. -. The *Pipeline Run Details* page displays the pipeline being executed. After the pipeline starts, the tasks and steps within each task are executed. -You can: -* Hover over the tasks to see the time taken to execute each step. -* Click on a task to see the logs for each step in the task. -* Click the *Logs* tab to see the logs relating to the execution sequence of the tasks. You can also expand the pane and download the logs individually or in bulk, by using the relevant button. -* Click the *Events* tab to see the stream of events generated by a pipeline run. -+ -You can use the *Task Runs*, *Logs*, and *Events* tabs to assist in debugging a failed pipeline run or a failed task run. -+ -.Pipeline run details -image::op_pipeline_run.png[Pipeline run details] -+ -//Add workspace and credential steps in this section. -//Probably need a sep section for logging and monitoring pipelines. -. For pipelines created using the *From Git* option, you can use the *Topology* view to interact with pipelines after you start them: -+ -[NOTE] -==== -To see the pipelines created using the *Pipeline Builder* in the *Topology* view, customize the pipeline labels to link the pipeline with the application workload. -==== -+ -.. On the left navigation panel, click *Topology*, and click on the application to see the pipeline runs listed in the side panel. -.. In the *Pipeline Runs* section, click *Start Last Run* to start a new pipeline run with the same parameters and resources as the previous one. This option is disabled if a pipeline run has not been initiated. -+ -.Pipelines in Topology view -image::op_pipeline_topology.png[Pipelines in Topology view] -+ -.. In the *Topology* page, hover to the left of the application to see the status of the pipeline run for the application. -+ -[NOTE] -==== -The side panel of the application node in the *Topology* page displays a *Log Snippet* when a pipeline run fails on a specific task run. You can view the *Log Snippet* in the *Pipeline Runs* section, under the *Resources* tab. *Log Snippet* provides a general error message and a snippet of the log. A link to the *Logs* section provides quick access to the details about the failed run. -==== diff --git a/modules/op-tkn-clustertask-management.adoc b/modules/op-tkn-clustertask-management.adoc deleted file mode 100644 index 3cf38ebb058c..000000000000 --- a/modules/op-tkn-clustertask-management.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-reference.adoc - -[id="op-tkn-clustertask-management-commands_{context}"] -= ClusterTask management commands - -== clustertask -Manage ClusterTasks. - -.Example: Display help -[source,terminal] ----- -$ tkn clustertask --help ----- - -== clustertask delete -Delete a ClusterTask resource in a cluster. - -.Example: Delete `mytask1` and `mytask2` ClusterTasks -[source,terminal] ----- -$ tkn clustertask delete mytask1 mytask2 ----- - -== clustertask describe -Describe a ClusterTask. - -.Example: Describe the `mytask` ClusterTask -[source,terminal] ----- -$ tkn clustertask describe mytask1 ----- - -== clustertask list -List ClusterTasks. - -.Example: List ClusterTasks -[source,terminal] ----- -$ tkn clustertask list ----- -== clustertask start -Start ClusterTasks. - -.Example: Start the `mytask` ClusterTask -[source,terminal] ----- -$ tkn clustertask start mytask ----- diff --git a/modules/op-tkn-condition-management.adoc b/modules/op-tkn-condition-management.adoc deleted file mode 100644 index 85de7af82356..000000000000 --- a/modules/op-tkn-condition-management.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-references.adoc - -[id="op-tkn-condition-management_{context}"] -= Condition management commands - -== condition -Manage Conditions. - -.Example: Display help -[source,terminal] ----- -$ tkn condition --help ----- - -== condition delete -Delete a Condition. - -.Example: Delete the `mycondition1` Condition from a namespace -[source,terminal] ----- -$ tkn condition delete mycondition1 -n myspace ----- - -== condition describe -Describe a Condition. - -.Example: Describe the `mycondition1` Condition in a namespace -[source,terminal] ----- -$ tkn condition describe mycondition1 -n myspace ----- - -== condition list -List Conditions. - -.Example: List Conditions in a namespace -[source,terminal] ----- -$ tkn condition list -n myspace ----- diff --git a/modules/op-tkn-enabling-tab-completion.adoc b/modules/op-tkn-enabling-tab-completion.adoc deleted file mode 100644 index 99fcfa7280b6..000000000000 --- a/modules/op-tkn-enabling-tab-completion.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/installing-tkn.adoc - -[id="op-tkn-enabling-tab-completion_{context}"] -= Enabling tab completion - -After you install the `tkn` CLI, you can enable tab completion to automatically complete `tkn` commands or suggest options when you press Tab. - -.Prerequisites - -* You must have the `tkn` CLI tool installed. -* You must have `bash-completion` installed on your local system. - -.Procedure - -The following procedure enables tab completion for Bash. - -. Save the Bash completion code to a file: -+ -[source,terminal] ----- -$ tkn completion bash > tkn_bash_completion ----- - -. Copy the file to `/etc/bash_completion.d/`: -+ -[source,terminal] ----- -$ sudo cp tkn_bash_completion /etc/bash_completion.d/ ----- -+ -Alternatively, you can save the file to a local directory and source it from your `.bashrc` file instead. - -Tab completion is enabled when you open a new terminal. diff --git a/modules/op-tkn-pipeline-management.adoc b/modules/op-tkn-pipeline-management.adoc deleted file mode 100644 index 558e14dd070d..000000000000 --- a/modules/op-tkn-pipeline-management.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-references.adoc - -[id="op-tkn-pipeline-management_{context}"] -= Pipelines management commands - -== pipeline -Manage Pipelines. - -.Example: Display help -[source,terminal] ----- -$ tkn pipeline --help ----- - -== pipeline delete - -Delete a Pipeline. - -.Example: Delete the `mypipeline` Pipeline from a namespace -[source,terminal] ----- -$ tkn pipeline delete mypipeline -n myspace ----- - -== pipeline describe -Describe a Pipeline. - -.Example: Describe `mypipeline` Pipeline -[source,terminal] ----- -$ tkn pipeline describe mypipeline ----- - -== pipeline list -List Pipelines. - -.Example: Display a list of Pipelines -[source,terminal] ------ -$ tkn pipeline list ------ - -== pipeline logs -Display Pipeline logs for a specific Pipeline. - -.Example: Stream live logs for the `mypipeline` Pipeline -[source,terminal] ----- -$ tkn pipeline logs -f mypipeline ----- - -== pipeline start -Start a Pipeline. - -.Example: Start `mypipeline` Pipeline -[source,terminal] ----- -$ tkn pipeline start mypipeline ----- diff --git a/modules/op-tkn-pipeline-resource-management.adoc b/modules/op-tkn-pipeline-resource-management.adoc deleted file mode 100644 index 7c58e462b307..000000000000 --- a/modules/op-tkn-pipeline-resource-management.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-reference.adoc - -[id="op-tkn-pipeline-resource-management_{context}"] -= Pipeline Resource management commands - -== resource -Manage Pipeline Resources. - -.Example: Display help -[source,terminal] ----- -$ tkn resource -h ----- - -== resource create -Create a Pipeline Resource. - -.Example: Create a Pipeline Resource in a namespace -[source,terminal] ----- -$ tkn resource create -n myspace ----- -This is an interactive command that asks for input on the name of the Resource, type of the Resource, and the values based on the type of the Resource. - -== resource delete -Delete a Pipeline Resource. - -.Example: Delete the `myresource` Pipeline Resource from a namespace -[source,terminal] ----- -$ tkn resource delete myresource -n myspace ----- - -== resource describe -Describe a Pipeline Resource. - -.Example: Describe the `myresource` Pipeline Resource -[source,terminal] ----- -$ tkn resource describe myresource -n myspace ----- -== resource list -List Pipeline Resources. - -.Example: List all Pipeline Resources in a namespace -[source,terminal] ----- -$ tkn resource list -n myspace ----- diff --git a/modules/op-tkn-pipeline-run.adoc b/modules/op-tkn-pipeline-run.adoc deleted file mode 100644 index f03330771ffc..000000000000 --- a/modules/op-tkn-pipeline-run.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-references.adoc - -[id="op-tkn-pipeline-run_{context}"] -= PipelineRun commands - - -== pipelinerun -Manage PipelineRuns. - -.Example: Display help -[source,terminal] ----- -$ tkn pipelinerun -h ----- - -== pipelinerun cancel -Cancel a PipelineRun. - -.Example: Cancel the `mypipelinerun` PipelineRun from a namespace -[source,terminal] ----- -$ tkn pipelinerun cancel mypipelinerun -n myspace ----- - -== pipelinerun delete -Delete a PipelineRun. - -.Example: Delete PipelineRuns from a namespace -[source,terminal] ----- -$ tkn pipelinerun delete mypipelinerun1 mypipelinerun2 -n myspace ----- - -== pipelinerun describe -Describe a PipelineRun. - -.Example: Describe the `mypipelinerun` PipelineRun in a namespace -[source,terminal] ----- -$ tkn pipelinerun describe mypipelinerun -n myspace ----- - -== pipelinerun list -List PipelineRuns. - -.Example: Display a list of PipelineRuns in a namespace -[source,terminal] ----- -$ tkn pipelinerun list -n myspace ----- - -== pipelinerun logs -Display the logs of a PipelineRun. - -.Example: Display the logs of the `mypipelinerun` PipelineRun with all tasks and steps in a namespace -[source,terminal] ----- -$ tkn pipelinerun logs mypipelinerun -a -n myspace ----- diff --git a/modules/op-tkn-task-management.adoc b/modules/op-tkn-task-management.adoc deleted file mode 100644 index a5ae808e90d5..000000000000 --- a/modules/op-tkn-task-management.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-reference.adoc - -[id="op-tkn-task-management_{context}"] -= Task management commands - -== task -Manage Tasks. - -.Example: Display help -[source,terminal] ----- -$ tkn task -h ----- - -== task delete -Delete a Task. - -.Example: Delete `mytask1` and `mytask2` Tasks from a namespace -[source,terminal] ----- -$ tkn task delete mytask1 mytask2 -n myspace ----- - -== task describe -Describe a Task. - -.Example: Describe the `mytask` Task in a namespace -[source,terminal] ----- -$ tkn task describe mytask -n myspace ----- - -== task list -List Tasks. - -.Example: List all the Tasks in a namespace -[source,terminal] ----- -$ tkn task list -n myspace ----- - -== task logs -Display Task logs. - -.Example: Display logs for the `mytaskrun` TaskRun of the `mytask` Task -[source,terminal] ----- -$ tkn task logs mytask mytaskrun -n myspace ----- - -== task start -Start a Task. - -.Example: Start the `mytask` Task in a namespace -[source,terminal] ----- -$ tkn task start mytask -s <ServiceAccountName> -n myspace ----- diff --git a/modules/op-tkn-task-run.adoc b/modules/op-tkn-task-run.adoc deleted file mode 100644 index a5f195b698ca..000000000000 --- a/modules/op-tkn-task-run.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-reference.adoc - -[id="op-tkn-task-run_{context}"] -= TaskRun commands - -== taskrun -Manage TaskRuns. - -.Example: Display help -[source,terminal] ----- -$ tkn taskrun -h ----- - -== taskrun cancel -Cancel a TaskRun. - -.Example: Cancel the `mytaskrun` TaskRun from a namespace -[source,terminal] ----- -$ tkn taskrun cancel mytaskrun -n myspace ----- - -== taskrun delete -Delete a TaskRun. - -.Example: Delete `mytaskrun1` and `mytaskrun2` TaskRuns from a namespace -[source,terminal] ----- -$ tkn taskrun delete mytaskrun1 mytaskrun2 -n myspace ----- - -== taskrun describe -Describe a TaskRun. - -.Example: Describe the `mytaskrun` TaskRun in a namespace -[source,terminal] ----- -$ tkn taskrun describe mytaskrun -n myspace ----- - -== taskrun list -List TaskRuns. - -.Example: List all TaskRuns in a namespace -[source,terminal] ----- -$ tkn taskrun list -n myspace ----- - - -== taskrun logs -Display TaskRun logs. - -.Example: Display live logs for the `mytaskrun` TaskRun in a namespace - -[source,terminal] ----- -$ tkn taskrun logs -f mytaskrun -n myspace ----- diff --git a/modules/op-tkn-trigger-management.adoc b/modules/op-tkn-trigger-management.adoc deleted file mode 100644 index e27f4dade95b..000000000000 --- a/modules/op-tkn-trigger-management.adoc +++ /dev/null @@ -1,144 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-reference.adoc - -[id="op-tkn-trigger-management_{context}"] -= Trigger management commands - -== eventlistener -Manage EventListeners. - -.Example: Display help -[source,terminal] ----- -$ tkn eventlistener -h ----- - -== eventlistener delete -Delete an EventListener. - -.Example: Delete `mylistener1` and `mylistener2` EventListeners in a namespace -[source,terminal] ----- -$ tkn eventlistener delete mylistener1 mylistener2 -n myspace ----- -== eventlistener describe -Describe an EventListener. - -.Example: Describe the `mylistener` EventListener in a namespace -[source,terminal] ----- -$ tkn eventlistener describe mylistener -n myspace ----- - -== eventlistener list -List EventListeners. - -.Example: List all the EventListeners in a namespace -[source,terminal] ----- -$ tkn eventlistener list -n myspace ----- - -== triggerbinding -Manage TriggerBindings. - -.Example: Display TriggerBindings help -[source,terminal] ----- -$ tkn triggerbinding -h ----- - -== triggerbinding delete -Delete a TriggerBinding. - -.Example: Delete `mybinding1` and `mybinding2` TriggerBindings in a namespace -[source,terminal] ----- -$ tkn triggerbinding delete mybinding1 mybinding2 -n myspace ----- -== triggerbinding describe -Describe a TriggerBinding. - -.Example: Describe the `mybinding` TriggerBinding in a namespace -[source,terminal] ----- -$ tkn triggerbinding describe mybinding -n myspace ----- - -== triggerbinding list -List TriggerBindings. - -.Example: List all the TriggerBindings in a namespace -[source,terminal] ----- -$ tkn triggerbinding list -n myspace ----- - -== triggertemplate -Manage TriggerTemplates. - -.Example: Display TriggerTemplate help -[source,terminal] ----- -$ tkn triggertemplate -h ----- -== triggertemplate delete -Delete a TriggerTemplate. - -.Example: Delete `mytemplate1` and `mytemplate2` TriggerTemplates in a namespace -[source,terminal] ----- -$ tkn triggertemplate delete mytemplate1 mytemplate2 -n `myspace` ----- -== triggertemplate describe -Describe a TriggerTemplate. - -.Example: Describe the `mytemplate` TriggerTemplate in a namespace -[source,terminal] ----- -$ tkn triggertemplate describe mytemplate -n `myspace` ----- - -== triggertemplate list -List TriggerTemplates. - -.Example: List all the TriggerTemplates in a namespace -[source,terminal] ----- -$ tkn triggertemplate list -n myspace ----- -== clustertriggerbinding -Manage ClusterTriggerBindings. - -.Example: Display ClusterTriggerBindings help -[source,terminal] ----- -$ tkn clustertriggerbinding -h ----- - -== clustertriggerbinding delete -Delete a ClusterTriggerBinding. - -.Example: Delete `myclusterbinding1` and `myclusterbinding2` ClusterTriggerBindings -[source,terminal] ----- -$ tkn clustertriggerbinding delete myclusterbinding1 myclusterbinding2 ----- -== clustertriggerbinding describe -Describe a ClusterTriggerBinding. - -.Example: Describe the `myclusterbinding` ClusterTriggerBinding -[source,terminal] ----- -$ tkn clustertriggerbinding describe myclusterbinding ----- - -== clustertriggerbinding list -List ClusterTriggerBindings. - -.Example: List all ClusterTriggerBindings -[source,terminal] ----- -$ tkn clustertriggerbinding list ----- diff --git a/modules/op-tkn-utility-commands.adoc b/modules/op-tkn-utility-commands.adoc deleted file mode 100644 index 9daff0363b55..000000000000 --- a/modules/op-tkn-utility-commands.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/tkn_cli/op-tkn-reference.adoc - -[id="op-tkn-utility-commands_{context}"] -= Utility commands - -== tkn -Parent command for `tkn` CLI. - -.Example: Display all options -[source,terminal] ----- -$ tkn ----- - -== completion [shell] -Print shell completion code which must be evaluated to provide interactive completion. Supported shells are `bash` and `zsh`. - -.Example: Completion code for `bash` shell -[source,terminal] ----- -$ tkn completion bash ----- - -== version -Print version information of the `tkn` CLI. - -.Example: Check the `tkn` version -[source,terminal] ----- -$ tkn version ----- diff --git a/modules/op-triggering-a-pipelinerun.adoc b/modules/op-triggering-a-pipelinerun.adoc deleted file mode 100644 index 3683b94c3b51..000000000000 --- a/modules/op-triggering-a-pipelinerun.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// This module is included in the following assembly: -// -// *openshift_pipelines/creating-applications-with-cicd-pipelines.adoc - -[id="triggering-a-pipeline_{context}"] -= Triggering a pipeline run - -Whenever a `push` event occurs in the Git repository, the configured Webhook sends an event payload to the publicly exposed `EventListener` service route. The `EventListener` service of the application processes the payload, and passes it to the relevant `TriggerBinding` and `TriggerTemplate` resource pairs. The `TriggerBinding` resource extracts the parameters and the `TriggerTemplate` resource uses these parameters and specifies the way the resources must be created. This may rebuild and redeploy the application. - -In this section, you push an empty commit to the front-end `vote-ui` repository, which then triggers the pipeline run. - -[discrete] -.Procedure - -. From the terminal, clone your forked Git repository `vote-ui`: -+ -[source,terminal,subs="attributes+"] ----- -$ git clone git@github.com:<your GitHub ID>/vote-ui.git -b {pipelines-ver} ----- -. Push an empty commit: -+ -[source,terminal,subs="attributes+"] ----- -$ git commit -m "empty-commit" --allow-empty && git push origin {pipelines-ver} ----- -. Check if the pipeline run was triggered: -+ ----- -$ tkn pipelinerun list ----- -+ -Notice that a new pipeline run was initiated. diff --git a/modules/op-uninstalling-the-pipelines-operator.adoc b/modules/op-uninstalling-the-pipelines-operator.adoc deleted file mode 100644 index e06eb76cd0cc..000000000000 --- a/modules/op-uninstalling-the-pipelines-operator.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// */openshift_pipelines/uninstalling-pipelines.adoc - -[id='op-uninstalling-the-pipelines-operator_{context}'] -= Uninstalling the {pipelines-title} Operator - -[discrete] -.Procedure -. From the *Operators* -> *OperatorHub* page, use the *Filter by keyword* box to search for `{pipelines-title} Operator`. - -. Click the *OpenShift Pipelines Operator* tile. The Operator tile indicates it is installed. - -. In the *OpenShift Pipelines Operator* descriptor page, click *Uninstall*. diff --git a/modules/open-risk-view.adoc b/modules/open-risk-view.adoc new file mode 100644 index 000000000000..c93b808e5c06 --- /dev/null +++ b/modules/open-risk-view.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: PROCEDURE +[id="open-risk-view_{context}"] += Opening the risk view + +You can analyze all risks in the *Risk* view and take corrective action. + +.Procedure +* Go to the {product-title-short} portal and select *Risk* from the navigation menu. diff --git a/modules/openshift-apiserver-operator.adoc b/modules/openshift-apiserver-operator.adoc deleted file mode 100644 index 5a01af6dab62..000000000000 --- a/modules/openshift-apiserver-operator.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="openshift-apiserver-operator_{context}"] -= OpenShift API Server Operator - -[discrete] -== Purpose - -The OpenShift API Server Operator installs and maintains the `openshift-apiserver` on a cluster. - -[discrete] -== Project - -link:https://github.com/openshift/cluster-openshift-apiserver-operator[openshift-apiserver-operator] - -[discrete] -== CRDs - -* `openshiftapiservers.operator.openshift.io` -** Scope: Cluster -** CR: `openshiftapiserver` -** Validation: Yes diff --git a/modules/openshift-cluster-maximums-environment.adoc b/modules/openshift-cluster-maximums-environment.adoc deleted file mode 100644 index ae9778332f70..000000000000 --- a/modules/openshift-cluster-maximums-environment.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc - -[id="cluster-maximums-environment_{context}"] -= {product-title} environment and configuration on which the cluster maximums are tested - -AWS cloud platform: - -[options="header",cols="8*"] -|=== -| Node |Flavor |vCPU |RAM(GiB) |Disk type|Disk size(GiB)/IOS |Count |Region - -| Master/etcd ^[1]^ -| r5.4xlarge -| 16 -| 128 -| io1 -| 220 / 3000 -| 3 -| us-west-2 - -| Infra ^[2]^ -| m5.12xlarge -| 48 -| 192 -| gp2 -| 100 -| 3 -| us-west-2 - -| Workload ^[3]^ -| m5.4xlarge -| 16 -| 64 -| gp2 -| 500 ^[4]^ -| 1 -| us-west-2 - -| Worker -| m5.2xlarge -| 8 -| 32 -| gp2 -| 100 -| 3/25/250/500 ^[5]^ -| us-west-2 - -|=== -[.small] --- -1. io1 disks with 3000 IOPS are used for master/etcd nodes as etcd is I/O intensive and latency sensitive. -2. Infra nodes are used to host Monitoring, Ingress, and Registry components to ensure they have enough resources to run at large scale. -3. Workload node is dedicated to run performance and scalability workload generators. -4. Larger disk size is used so that there is enough space to store the large amounts of data that is collected during the performance and scalability test run. -5. Cluster is scaled in iterations and performance and scalability tests are executed at the specified node counts. --- diff --git a/modules/openshift-cluster-maximums-major-releases.adoc b/modules/openshift-cluster-maximums-major-releases.adoc deleted file mode 100644 index 3d392a960045..000000000000 --- a/modules/openshift-cluster-maximums-major-releases.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc - -[id="cluster-maximums-major-releases_{context}"] -= {product-title} tested cluster maximums for major releases - -Tested Cloud Platforms for {product-title} 3.x: {rh-openstack-first}, Amazon Web Services and Microsoft Azure. -Tested Cloud Platforms for {product-title} 4.x: Amazon Web Services, Microsoft Azure and Google Cloud Platform. - -[options="header",cols="3*"] -|=== -| Maximum type |3.x tested maximum |4.x tested maximum - -| Number of nodes -| 2,000 -| 2,000 - -| Number of pods ^[1]^ -| 150,000 -| 150,000 - -| Number of pods per node -| 250 -| 500 ^[2]^ - -| Number of pods per core -| There is no default value. -| There is no default value. - -| Number of namespaces ^[3]^ -| 10,000 -| 10,000 - -| Number of builds -| 10,000 (Default pod RAM 512 Mi) - Pipeline Strategy -| 10,000 (Default pod RAM 512 Mi) - Source-to-Image (S2I) build strategy - -| Number of pods per namespace ^[4]^ -| 25,000 -| 25,000 - -| Number of services ^[5]^ -| 10,000 -| 10,000 - -| Number of services per namespace -| 5,000 -| 5,000 - -| Number of back-ends per service -| 5,000 -| 5,000 - -| Number of deployments per namespace ^[4]^ -| 2,000 -| 2,000 - -|=== -[.small] --- -1. The pod count displayed here is the number of test pods. The actual number of pods depends on the application’s memory, CPU, and storage requirements. -2. This was tested on a cluster with 100 worker nodes with 500 pods per worker node. The default `maxPods` is still 250. To get to 500 `maxPods`, the cluster must be created with a `maxPods` set to `500` using a custom kubelet config. If you need 500 user pods, you need a `hostPrefix` of `22` because there are 10-15 system pods already running on the node. The maximum number of pods with attached persistent volume claims (PVC) depends on storage backend from where PVC are allocated. In our tests, only OpenShift Container Storage v4 (OCS v4) was able to satisfy the number of pods per node discussed in this document. -3. When there are a large number of active projects, etcd might suffer from poor performance if the keyspace grows excessively large and exceeds the space quota. Periodic maintenance of etcd, including defragmentaion, is highly recommended to free etcd storage. -4. There are a number of control loops in the system that must iterate over all objects in a given namespace as a reaction to some changes in state. Having a large number of objects of a given type in a single namespace can make those loops expensive and slow down processing given state changes. The limit assumes that the system has enough CPU, memory, and disk to satisfy the application requirements. -5. Each service port and each service back-end has a corresponding entry in iptables. The number of back-ends of a given service impact the size of the endpoints objects, which impacts the size of data that is being sent all over the system. --- diff --git a/modules/openshift-cluster-maximums.adoc b/modules/openshift-cluster-maximums.adoc deleted file mode 100644 index adb91f283fb3..000000000000 --- a/modules/openshift-cluster-maximums.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc - -[id="cluster-maximums_{context}"] -= {product-title} tested cluster maximums - -[options="header",cols="7*"] -|=== -| Maximum type |4.1 and 4.2 tested maximum |4.3 tested maximum |4.4 tested maximum |4.5 tested maximum |4.6 tested maximum |4.7 tested maximum - -| Number of nodes -| 2,000 -| 2,000 -| 250 -| 500 -| 500 -| 500 - -| Number of pods ^[1]^ -| 150,000 -| 150,000 -| 62,500 -| 62,500 -| 62,500 -| 62,500 - -| Number of pods per node -| 250 -| 500 -| 500 -| 500 -| 500 -| 500 - -| Number of pods per core -| There is no default value. -| There is no default value. -| There is no default value. -| There is no default value. -| There is no default value. -| There is no default value. - -| Number of namespaces ^[2]^ -| 10,000 -| 10,000 -| 10,000 -| 10,000 -| 10,000 -| 10,000 - -| Number of builds -| 10,000 (Default pod RAM 512 Mi) - Pipeline Strategy -| 10,000 (Default pod RAM 512 Mi) - Source-to-Image (S2I) build strategy -| 10,000 (Default pod RAM 512 Mi) - Source-to-Image (S2I) build strategy -| 10,000 (Default pod RAM 512 Mi) - Source-to-Image (S2I) build strategy -| 10,000 (Default pod RAM 512 Mi) - Source-to-Image (S2I) build strategy -| 10,000 (Default pod RAM 512 Mi) - Source-to-Image (S2I) build strategy - -| Number of pods per namespace ^[3]^ -| 25,000 -| 25,000 -| 25,000 -| 25,000 -| 25,000 -| 25,000 - -| Number of services ^[4]^ -| 10,000 -| 10,000 -| 10,000 -| 10,000 -| 10,000 -| 10,000 - -| Number of services per namespace -| 5,000 -| 5,000 -| 5,000 -| 5,000 -| 5,000 -| 5,000 - -| Number of back ends per service -| 5,000 -| 5,000 -| 5,000 -| 5,000 -| 5,000 -| 5,000 - -| Number of deployments per namespace ^[3]^ -| 2,000 -| 2,000 -| 2,000 -| 2,000 -| 2,000 -| 2,000 - -|=== -[.small] --- -1. The pod count displayed here is the number of test pods. The actual number of pods depends on the application’s memory, CPU, and storage requirements. -2. When there are a large number of active projects, etcd might suffer from poor performance if the keyspace grows excessively large and exceeds the space quota. Periodic maintenance of etcd, including defragmentaion, is highly recommended to free etcd storage. -3. There are a number of control loops in the system that must iterate over all objects in a given namespace as a reaction to some changes in state. Having a large number of objects of a given type in a single namespace can make those loops expensive and slow down processing given state changes. The limit assumes that the system has enough CPU, memory, and disk to satisfy the application requirements. -4. Each service port and each service back end has a corresponding entry in iptables. The number of back ends of a given service impact the size of the endpoints objects, which impacts the size of data that is being sent all over the system. --- - -In {product-title} {product-version}, half of a CPU core (500 millicore) is reserved by the system compared to {product-title} 3.11 and previous versions. diff --git a/modules/operator-marketplace.adoc b/modules/operator-marketplace.adoc deleted file mode 100644 index c0cfddcf08de..000000000000 --- a/modules/operator-marketplace.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="marketplace-operator_{context}"] -= Marketplace Operator - -[discrete] -== Purpose - -The Marketplace Operator is a conduit to bring off-cluster Operators to your cluster. - -[discrete] -== Project - -link:https://github.com/operator-framework/operator-marketplace[operator-marketplace] diff --git a/modules/operator-upgrade-centraldb-cannot-be-scheduled.adoc b/modules/operator-upgrade-centraldb-cannot-be-scheduled.adoc new file mode 100644 index 000000000000..f13661482a7d --- /dev/null +++ b/modules/operator-upgrade-centraldb-cannot-be-scheduled.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-operator.adoc +:_mod-docs-content-type: REFERENCE +[id="operator-upgrade-centraldb-cannot-be-scheduled_{context}"] += Central DB cannot be scheduled + +[role="_abstract"] +Follow the instructions here to troubleshoot a failing Central DB pod during an upgrade: + +. Check the status of the `central-db` pod: ++ +[source,terminal] +---- +$ oc -n <namespace> get pod -l app=central-db <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +. If the status of the pod is `Pending`, use the describe command to get more details: ++ +[source,terminal] +---- +$ oc -n <namespace> describe po/<central-db-pod-name> <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +. You might see the `FailedScheduling` warning message: ++ +[source,terminal] +---- +Type Reason Age From Message +---- ------ ---- ---- ------- +Warning FailedScheduling 54s default-scheduler 0/7 nodes are available: 1 Insufficient memory, 3 node(s) had untolerated taint {node-role.kubernetes.io/master: }, 4 Insufficient cpu. preemption: 0/7 nodes are available: 3 Preemption is not helpful for scheduling, 4 No preemption victims found for incoming pod. +---- +. This warning message suggests that the scheduled node had insufficient memory to accommodate the pod's resource requirements. If you have a small environment, consider increasing resources on the nodes or adding a larger node that can support the database. ++ +Otherwise, consider decreasing the resource requirements for the `central-db` pod in the custom resource under `central` -> `db` -> `resources`. However, running central with fewer resources than the recommended minimum might lead to degraded performance for {product-title-short}. diff --git a/modules/operator-upgrade-change-subscription-channel.adoc b/modules/operator-upgrade-change-subscription-channel.adoc new file mode 100644 index 000000000000..b6628de66617 --- /dev/null +++ b/modules/operator-upgrade-change-subscription-channel.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-operator.adoc +// * cloud_service/upgrade-cloudsvc-operator.adoc +:_mod-docs-content-type: PROCEDURE +[id="operator-upgrade-change-subscription-channel_{context}"] += Changing the subscription channel + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:cloud-svc: +endif::[] + +[role="_abstract"] +You can change the update channel for the {product-title-short} Operator by using the {ocp} web console or by using the command line. For upgrading to {product-title-short} 4.0 from {product-title-short} 3.74, you must change the update channel. + +[IMPORTANT] +==== +ifndef::cloud-svc[] +You must change the subscription channel for all clusters where you installed the {product-title-short} Operator, including Central and all secured clusters. +endif::[] +ifdef::cloud-svc[] +You must change the subscription channel for all secured clusters where you installed the {product-title-short} Operator. +endif::[] +==== + +.Prerequisites +ifndef::cloud-svc[] +* You must verify that you are using the latest {product-title-short} 3.74 Operator and there are no pending manual Operator upgrades. +* You must verify that you backed up your Central database. +endif::[] +* You have access to an {ocp} cluster web console using an account with `cluster-admin` permissions. + +== Changing the subscription channel by using the web console +Use the following instructions for changing the subscription channel by using the web console: + +.Procedure +. In the *Administrator* perspective of the {ocp} web console, go to *Operators* → *Installed Operators*. +. Click the {product-title-short} Operator. +. Click the *Subscription* tab. +. Click the name of the update channel under *Update Channel*. +. Select *stable*, then click *Save*. +. For subscriptions with an *Automatic* approval strategy, the update begins automatically. Go back to the *Operators* → *Installed Operators* page to monitor the progress of the update. When complete, the status changes to *Succeeded* and *Up to date*. ++ +For subscriptions with a *Manual* approval strategy, you can manually approve the update from the *Subscription* tab. + +== Changing the subscription channel by using command line +Use the following instructions for changing the subscription channel by using command line: + +.Procedure +* Run the following command to change the subscription channel to `stable`: ++ +[source,terminal] +---- +$ oc -n rhacs-operator \ <1> + patch subscriptions.operators.coreos.com rhacs-operator \ + --type=merge --patch='{ "spec": { "channel": "stable" }}' +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +During the update, the {product-title-short} Operator provisions a new deployment called `central-db` and your data begins migrating. It takes around 30 minutes and happens only after you upgrade. + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:!cloud-svc: +endif::[] diff --git a/modules/operator-upgrade-fail-to-deploy.adoc b/modules/operator-upgrade-fail-to-deploy.adoc new file mode 100644 index 000000000000..cabfab6ba623 --- /dev/null +++ b/modules/operator-upgrade-fail-to-deploy.adoc @@ -0,0 +1,80 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-operator.adoc +// * cloud_service/upgrade-cloudsvc-operator.adoc +:_mod-docs-content-type: REFERENCE +[id="operator-upgrade-fail-to-deploy_{context}"] += Central or Secured cluster fails to deploy + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:cloud-svc: +endif::[] + +[role="_abstract"] +When {product-title-short} Operator has the following conditions, you must check the custom resource conditions to find the issue: + +ifndef::cloud-svc[] +* If the Operator fails to deploy Central or Secured Cluster +endif::cloud-svc[] +ifdef::cloud-svc[] +* If the Operator fails to deploy Secured Cluster +endif::cloud-svc[] +* If the Operator fails to apply CR changes to actual resources + +ifndef::cloud-svc[] +* For Central, run the following command to check the conditions: ++ +[source,terminal] +---- +$ oc -n rhacs-operator describe centrals.platform.stackrox.io <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +endif::cloud-svc[] +* For Secured clusters, run the following command to check the conditions: ++ +[source,terminal] +---- +$ oc -n rhacs-operator describe securedclusters.platform.stackrox.io <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +You can identify configuration errors from the conditions output: + +.Example output +[source,terminal] +---- + Conditions: + Last Transition Time: 2023-04-19T10:49:57Z + Status: False + Type: Deployed + Last Transition Time: 2023-04-19T10:49:57Z + Status: True + Type: Initialized + Last Transition Time: 2023-04-19T10:59:10Z + Message: Deployment.apps "central" is invalid: spec.template.spec.containers[0].resources.requests: Invalid value: "50": must be less than or equal to cpu limit + Reason: ReconcileError + Status: True + Type: Irreconcilable + Last Transition Time: 2023-04-19T10:49:57Z + Message: No proxy configuration is desired + Reason: NoProxyConfig + Status: False + Type: ProxyConfigFailed + Last Transition Time: 2023-04-19T10:49:57Z + Message: Deployment.apps "central" is invalid: spec.template.spec.containers[0].resources.requests: Invalid value: "50": must be less than or equal to cpu limit + Reason: InstallError + Status: True + Type: ReleaseFailed +---- + +Additionally, you can view {product-title-short} pod logs to find more information about the issue. Run the following command to view the logs: + +[source,terminal] +---- +oc -n rhacs-operator logs deploy/rhacs-operator-controller-manager manager <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:!cloud-svc: +endif::[] \ No newline at end of file diff --git a/modules/operator-upgrade-modify-central-custom-resource-external-db.adoc b/modules/operator-upgrade-modify-central-custom-resource-external-db.adoc new file mode 100644 index 000000000000..4fe82ab6b782 --- /dev/null +++ b/modules/operator-upgrade-modify-central-custom-resource-external-db.adoc @@ -0,0 +1,58 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-operator.adoc +:_mod-docs-content-type: PROCEDURE +[id="operator-upgrade-modify-central-custom-resource-external-db_{context}"] += Modifying Central custom resource for external database + +.Prerequisites +* You must have a database in your database instance that supports PostgreSQL 13 or 15 and a user with the following permissions: +** Connection rights to the database. +** `Usage` and `Create` on the schema. +** `Select`, `Insert`, `Update`, and `Delete` on all tables in the schema. +** `Usage` on all sequences in the schema. ++ +[NOTE] +==== +Postgres 15 is the recommended and supported version. Red{nbsp}Hat has deprecated the support for Postgres 13 and will remove it in the newer versions of {product-title-short}. +==== + +.Procedure +. Create a password secret in the deployed namespace by using the {ocp} web console or the terminal. +** On the {ocp} web console, go to the *Workloads* → *Secrets* page. Create a *Key/Value secret* with the key `password` and the value as the path of a plain text file containing the password for the superuser of the provisioned database. +** Or, run the following command in your terminal: ++ +[source,terminal] +---- +$ oc create secret generic external-db-password \ <1> + --from-file=password=<password.txt> <2> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +<2> Replace `password.txt` with the path of the file which has the plain text password. +. Go to the {product-title} operator page in the {ocp} web console. Select *Central* in the top navigation bar and select the instance you want to connect to the database. +. Go to the *YAML editor* view. +. For *`db.passwordSecret.name`* specify the referenced secret that you created in earlier steps. For example, `external-db-password`. +. For *`db.connectionString`* specify the connection string in `keyword=value` format, for example, `host=<host> port=5432 database=stackrox user=stackrox sslmode=verify-ca` +. For *`db.persistence`* delete the entire block. +. If necessary, you can specify a Certificate Authority for Central to trust the database certificate by adding a TLS block under the top-level spec, as shown in the following example: + +** Update the central custom resource with the following configuration: ++ +[source,terminal] +---- +spec: + tls: + additionalCAs: + - name: db-ca + content: | + <certificate> + central: + db: + isEnabled: Default <1> + connectionString: "host=<host> port=5432 user=<user> sslmode=verify-ca" + passwordSecret: + name: external-db-password +---- +<1> You must not change the value of `IsEnabled` to `Enabled`. + +. Click *Save*. diff --git a/modules/operator-upgrade-modify-central-custom-resource.adoc b/modules/operator-upgrade-modify-central-custom-resource.adoc new file mode 100644 index 000000000000..f3e97c18fa50 --- /dev/null +++ b/modules/operator-upgrade-modify-central-custom-resource.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-operator.adoc +:_mod-docs-content-type: PROCEDURE +[id="operator-upgrade-modify-central-custom-resource_{context}"] += Modifying the Central custom resource + +[role="_abstract"] +The Central DB service requires persistent storage. If you have not configured a default storage class for the Central cluster that is an SSD or is high performance, you must reinstall and configure the `Central` custom resource (CR) with the storage class for the Central DB persistent volume claim (PVC). + +When changing the `storageClassName`, because of limitations with the Kubernetes storage layer, you cannot modify a claim's storage class after it is bound; therefore, you must re-create the Central CR. + +[NOTE] +==== +Skip this section if you have already configured a default storage class for Central. +==== + +.Procedure +. Back up and uninstall the Central instance. +. Reinstall {product-title-short} and configure the Central custom resource as shown in the following example: ++ +[source,terminal] +---- +spec: + central: + db: + isEnabled: Default <1> + persistence: + persistentVolumeClaim: <2> + claimName: central-db + size: 100Gi + storageClassName: <storage-class-name> +---- +<1> You must not change the value of `IsEnabled` to `Enabled`. +<2> If this claim exists, your cluster uses the existing claim; otherwise, it creates a new claim. +. Restore the Central database backup by using the `roxctl` CLI. + diff --git a/modules/operators-overview.adoc b/modules/operators-overview.adoc deleted file mode 100644 index 4e4b8ba01270..000000000000 --- a/modules/operators-overview.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture.adoc - -[id="operators-overview_{context}"] -= Operators in {product-title} - -In {product-title}, Operators are the preferred method of packaging, deploying, -and managing services on the control plane. They also provide advantages to -applications that users run. Operators integrate with -Kubernetes APIs and CLI tools such as `kubectl` and `oc` commands. They provide -the means of watching over an application, performing health checks, managing -over-the-air updates, and ensuring that the applications remain in your -specified state. - -Because CRI-O and the Kubelet run on every node, almost every other cluster -function can be managed on the control plane by using Operators. Operators are -among the most important components of {product-title} {product-version}. -Components that are added to the control plane by using Operators include -critical networking and credential services. - -The Operator that manages the other Operators in an {product-title} cluster is -the Cluster Version Operator. - -{product-title} {product-version} uses different classes of Operators to perform -cluster operations and run services on the cluster for your applications to use. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[id="platform-operators_{context}"] -== Platform Operators in {product-title} - -In {product-title} {product-version}, all cluster functions are divided into a series -of platform Operators. Platform Operators manage a particular area of -cluster functionality, such as cluster-wide application logging, management of -the Kubernetes control plane, or the machine provisioning system. - -Each Operator provides you with a simple API for determining cluster -functionality. The Operator hides the details of managing the lifecycle of that -component. Operators can manage a single component or tens of components, but -the end goal is always to reduce operational burden by automating common actions. -Operators also offer a more granular configuration experience. You configure each -component by modifying the API that the Operator exposes instead of modifying a -global configuration file. - -endif::[] - -[id="OLM-operators_{context}"] -== Operators managed by OLM - -The Cluster Operator Lifecycle Management (OLM) component manages Operators -that are available for use in applications. It does not manage the Operators that -comprise {product-title}. -OLM is a framework that manages Kubernetes-native applications as Operators. -Instead of managing Kubernetes manifests, it manages Kubernetes Operators. -OLM manages two classes of Operators, Red Hat Operators and certified Operators. - -Some Red Hat Operators drive the cluster functions, like the scheduler and -problem detectors. Others are provided for you to manage yourself and use in -your applications, like etcd. {product-title} also offers certified Operators, -which the community built and maintains. These certified Operators provide an -API layer to traditional applications so you can manage the application through -Kubernetes constructs. diff --git a/modules/optimizing-mtu-networking.adoc b/modules/optimizing-mtu-networking.adoc deleted file mode 100644 index 4e6139c653e4..000000000000 --- a/modules/optimizing-mtu-networking.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/optimizing-networking.adoc - -[id="optimizing-mtu_{context}"] -= Optimizing the MTU for your network - -There are two important maximum transmission units (MTUs): the network interface card (NIC) MTU and the cluster network MTU. - -The NIC MTU is only configured at the time of {product-title} installation. The MTU must be less than or equal to the maximum supported value of the NIC of your network. If you are optimizing for throughput, choose the largest possible value. If you are optimizing for lowest latency, choose a lower value. - -The SDN overlay's MTU must be less than the NIC MTU by 50 bytes at a minimum. This accounts for the SDN overlay header. So, on a normal ethernet network, set this to `1450`. On a jumbo frame ethernet network, set this to `8950`. - -For OVN and Geneve, the MTU must be less than the NIC MTU by 100 bytes at a minimum. - -[NOTE] -==== -This 50 byte overlay header is relevant to the OpenShift SDN. Other SDN solutions might require the value to be more or less. -==== diff --git a/modules/options-inherited-from-the-parent-command.adoc b/modules/options-inherited-from-the-parent-command.adoc new file mode 100644 index 000000000000..ac52a7e2a577 --- /dev/null +++ b/modules/options-inherited-from-the-parent-command.adoc @@ -0,0 +1,81 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc +// * command-reference/roxctl-cluster.adoc +// * command-reference/roxctl-completion.adoc +// * command-reference/roxctl-declarative-config.adoc +// * command-reference/roxctl-deployment.adoc +// * command-reference/roxctl-helm.adoc +// * command-reference/roxctl-image.adoc +// * command-reference/roxctl-netpol.adoc +// * command-reference/roxctl-scanner.adoc +// * command-reference/roxctl-sensor.adoc +// * command-reference/roxctl-version.adoc +// * command-reference/roxctl-collector.adoc + + +ifeval::["{context}" == "roxctl-completion"] +:roxctlcompletion: +endif::[] +ifeval::["{context}" == "roxctl-version"] +:roxctlversion: +endif::[] + +:_mod-docs-content-type: REFERENCE +[id="options-inherited-from-the-parent-command_{context}"] += {commandname} command options inherited from the parent command + +The `{commandname}` command supports the following options inherited from the parent `roxctl` command: + +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--ca string` +|Specify a custom CA certificate file path for secure connections. Alternatively, you can specify the file path by using the `ROX_CA_CERT_FILE` environment variable. + +|`--direct-grpc` +|Set `--direct-grpc` for improved connection performance. Alternatively, by setting the `ROX_DIRECT_GRPC_CLIENT` environment variable to `true`, you can enable direct gRPC . The default value is `false`. + +|`-e`, `--endpoint string` +|Set the endpoint for the service to contact. Alternatively, you can set the endpoint by using the `ROX_ENDPOINT` environment variable. The default value is `localhost:8443`. + +|`--force-http1` +|Force the use of HTTP/1 for all connections. Alternatively, by setting the `ROX_CLIENT_FORCE_HTTP1` environment variable to `true`, you can force the use of HTTP/1. The default value is `false`. + +|`--insecure` +|Enable insecure connection options. Alternatively, by setting the `ROX_INSECURE_CLIENT` environment variable to `true`, you can enable insecure connection options. The default value is `false`. + +|`--insecure-skip-tls-verify` +a|Skip the TLS certificate validation. Alternatively, by setting the `ROX_INSECURE_CLIENT_SKIP_TLS_VERIFY` environment variable to `true`, you can skip the TLS certificate validation. The default value is `false`. + +|`--no-color` +|Disable the color output. Alternatively, by setting the `ROX_NO_COLOR environment variable` to `true`, you can disable the color output. The default value is `false`. + +|`-p`, `--password string` +|Specify the password for basic authentication. Alternatively, you can set the password by using the `ROX_ADMIN_PASSWORD` environment variable. + +|`--plaintext` +|Use an unencrypted connection. Alternatively, by setting the `ROX_PLAINTEXT` environment variable to `true`, you can enable an unencrypted connection. The default value is `false`. + +|`-s`, `--server-name string` +|Set the TLS server name to use for SNI. Alternatively, you can set the server name by using the `ROX_SERVER_NAME` environment variable. + +|`--token-file string` +|Use the API token provided in the specified file for authentication. Alternatively, you can set the token by using the `ROX_API_TOKEN` environment variable. +|=== + + +ifndef::roxctlcompletion,roxctlversion[] +[NOTE] +==== +These options are applicable to all the sub-commands of the `{commandname}` command. +==== +endif::roxctlcompletion,roxctlversion[] + +ifeval::["{context}" == "roxctl-completion"] +:!roxctlcompletion: +endif::[] +ifeval::["{context}" == "roxctl-version"] +:!roxctlversion: +endif::[] \ No newline at end of file diff --git a/modules/osdk-about-openapi-validation.adoc b/modules/osdk-about-openapi-validation.adoc deleted file mode 100644 index 49408283ce12..000000000000 --- a/modules/osdk-about-openapi-validation.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-about-openapi-validation_{context}"] -= About OpenAPI validation - -OpenAPIv3 schemas are added to CRD manifests in the `spec.validation` block when the manifests are generated. This validation block allows Kubernetes to validate the properties in a Memcached custom resource (CR) when it is created or updated. - -Markers, or annotations, are available to configure validations for your API. These markers always have a `+kubebuilder:validation` prefix. - -.Additional resources - -* For more details on the usage of markers in API code, see the following Kubebuilder documentation: -** link:https://book.kubebuilder.io/reference/generating-crd.html[CRD generation] -** link:https://book.kubebuilder.io/reference/markers.html[Markers] -** link:https://book.kubebuilder.io/reference/markers/crd-validation.html[List of OpenAPIv3 validation markers] - -* For more details about OpenAPIv3 validation schemas in CRDs, see the link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema[Kubernetes documentation]. diff --git a/modules/osdk-ansible-cr-status-about.adoc b/modules/osdk-ansible-cr-status-about.adoc deleted file mode 100644 index 13291154c527..000000000000 --- a/modules/osdk-ansible-cr-status-about.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc - -[id="osdk-ansible-cr-status-about_{context}"] -= About custom resource status in Ansible-based Operators - -Ansible-based Operators automatically update custom resource (CR) link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#status-subresource[`status` subresources] with generic information about the previous Ansible run. This includes the number of successful and failed tasks and relevant error messages as shown: - -[source,yaml] ----- -status: - conditions: - - ansibleResult: - changed: 3 - completion: 2018-12-03T13:45:57.13329 - failures: 1 - ok: 6 - skipped: 0 - lastTransitionTime: 2018-12-03T13:45:57Z - message: 'Status code was -1 and not [200]: Request failed: <urlopen error [Errno - 113] No route to host>' - reason: Failed - status: "True" - type: Failure - - lastTransitionTime: 2018-12-03T13:46:13Z - message: Running reconciliation - reason: Running - status: "True" - type: Running ----- - -Ansible-based Operators also allow Operator authors to supply custom status values with the `k8s_status` Ansible module, which is included in the link:https://galaxy.ansible.com/operator_sdk/util[`operator_sdk.util` collection]. This allows the author to update the `status` from within Ansible with any key-value pair as desired. - -By default, Ansible-based Operators always include the generic Ansible run output as shown above. If you would prefer your application did _not_ update the status with Ansible output, you can track the status manually from your application. diff --git a/modules/osdk-ansible-cr-status-manual.adoc b/modules/osdk-ansible-cr-status-manual.adoc deleted file mode 100644 index 12eaf30c3ba4..000000000000 --- a/modules/osdk-ansible-cr-status-manual.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc - -[id="osdk-ansible-cr-status-manual_{context}"] -= Tracking custom resource status manually - -You can use the `operator_sdk.util` collection to modify your Ansible-based Operator to track custom resource (CR) status manually from your application. - -.Prerequisites - -* Ansible-based Operator project created by using the Operator SDK - -.Procedure - -. Update the `watches.yaml` file with a `manageStatus` field set to `false`: -+ -[source,yaml] ----- -- version: v1 - group: api.example.com - kind: <kind> - role: <role> - manageStatus: false ----- - -. Use the `operator_sdk.util.k8s_status` Ansible module to update the subresource. For example, to update with key `test` and value `data`, `operator_sdk.util` can be used as shown: -+ -[source,yaml] ----- -- operator_sdk.util.k8s_status: - api_version: app.example.com/v1 - kind: <kind> - name: "{{ ansible_operator_meta.name }}" - namespace: "{{ ansible_operator_meta.namespace }}" - status: - test: data ----- - -. You can declare collections in the `meta/main.yml` file for the role, which is included for scaffolded Ansible-based Operators: -+ -[source,yaml] ----- -collections: - - operator_sdk.util ----- - -. After declaring collections in the role meta, you can invoke the `k8s_status` module directly: -+ -[source,yaml] ----- -k8s_status: - ... - status: - key1: value1 ----- diff --git a/modules/osdk-ansible-create-api.adoc b/modules/osdk-ansible-create-api.adoc deleted file mode 100644 index 19d7363fbe89..000000000000 --- a/modules/osdk-ansible-create-api.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc - -[id="osdk-ansible-create-api-controller_{context}"] -= Creating an API - -Use the Operator SDK CLI to create a Memcached API. - -.Procedure - -* Run the following command to create an API with group `cache`, version, `v1`, and kind `Memcached`: -+ -[source,terminal] ----- -$ operator-sdk create api \ - --group cache \ - --version v1 \ - --kind Memcached \ - --generate-role <1> ----- -<1> Generates an Ansible role for the API. - -After creating the API, your Operator project updates with the following structure: - -Memcached CRD:: Includes a sample `Memcached` resource - -Manager:: Program that reconciles the state of the cluster to the desired state by using: -+ --- -* A reconciler, either an Ansible role or playbook -* A `watches.yaml` file, which connects the `Memcached` resource to the `memcached` Ansible role --- diff --git a/modules/osdk-ansible-custom-resource-files.adoc b/modules/osdk-ansible-custom-resource-files.adoc deleted file mode 100644 index d94ed3378622..000000000000 --- a/modules/osdk-ansible-custom-resource-files.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-support.adoc - -[id="osdk-ansible-custom-resource-files_{context}"] -= Custom resource files - -Operators use the Kubernetes extension mechanism, custom resource definitions (CRDs), so your custom resource (CR) looks and acts just like the built-in, native Kubernetes objects. - -The CR file format is a Kubernetes resource file. The object has mandatory and optional fields: - -.Custom resource fields -[cols="3,7",options="header"] -|=== -|Field -|Description - -|`apiVersion` -|Version of the CR to be created. - -|`kind` -|Kind of the CR to be created. - -|`metadata` -|Kubernetes-specific metadata to be created. - -|`spec` (optional) -|Key-value list of variables which are passed to Ansible. This field is empty by default. - -|`status` -|Summarizes the current state of the object. For Ansible-based Operators, the link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#status-subresource[`status` subresource] is enabled for CRDs and managed by the `operator_sdk.util.k8s_status` Ansible module by default, which includes `condition` information to the CR `status`. - -|`annotations` -|Kubernetes-specific annotations to be appended to the CR. -|=== - -The following list of CR annotations modify the behavior of the Operator: - -.Ansible-based Operator annotations -[cols="3,7",options="header"] -|=== -|Annotation -|Description - -|`ansible.operator-sdk/reconcile-period` -|Specifies the reconciliation interval for the CR. This value is parsed using the standard Golang package link:https://golang.org/pkg/time/[`time`]. Specifically, link:https://golang.org/pkg/time/#ParseDuration[`ParseDuration`] is used which applies the default suffix of `s`, giving the value in seconds. -|=== - -.Example Ansible-based Operator annotation -[source,yaml] ----- -apiVersion: "test1.example.com/v1alpha1" -kind: "Test1" -metadata: - name: "example" -annotations: - ansible.operator-sdk/reconcile-period: "30s" ----- diff --git a/modules/osdk-ansible-extra-variables.adoc b/modules/osdk-ansible-extra-variables.adoc deleted file mode 100644 index fc8d00022f8c..000000000000 --- a/modules/osdk-ansible-extra-variables.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-support.adoc - -[id="osdk-ansible-extra-variables_{context}"] -= Extra variables sent to Ansible - -Extra variables can be sent to Ansible, which are then managed by the Operator. The `spec` section of the custom resource (CR) passes along the key-value pairs as extra variables. This is equivalent to extra variables passed in to the `ansible-playbook` command. - -The Operator also passes along additional variables under the `meta` field for the name of the CR and the namespace of the CR. - -For the following CR example: - -[source,yaml] ----- -apiVersion: "app.example.com/v1alpha1" -kind: "Database" -metadata: - name: "example" -spec: - message:"Hello world 2" - newParameter: "newParam" ----- - -The structure passed to Ansible as extra variables is: - -[source,json] ----- -{ "meta": { - "name": "<cr_name>", - "namespace": "<cr_namespace>", - }, - "message": "Hello world 2", - "new_parameter": "newParam", - "_app_example_com_database": { - <full_crd> - }, -} ----- - -The `message` and `newParameter` fields are set in the top level as extra variables, and `meta` provides the relevant metadata for the CR as defined in the Operator. The `meta` fields can be accessed using dot notation in Ansible, for example: - -[source,yaml] ----- ---- -- debug: - msg: "name: {{ ansible_operator_meta.name }}, {{ ansible_operator_meta.namespace }}" ----- diff --git a/modules/osdk-ansible-inside-operator-local.adoc b/modules/osdk-ansible-inside-operator-local.adoc deleted file mode 100644 index bc6604dcfb1b..000000000000 --- a/modules/osdk-ansible-inside-operator-local.adoc +++ /dev/null @@ -1,123 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc - -[id="osdk-ansible-inside-operator-local_{context}"] -= Testing an Ansible-based Operator locally - -You can test the logic inside of an Ansible-based Operator running locally by using the `make run` command from the top-level directory of your Operator project. The `make run` Makefile target runs the `ansible-operator` binary locally, which reads from the `watches.yaml` file and uses your `~/.kube/config` file to communicate with a Kubernetes cluster just as the `k8s` modules do. - -[NOTE] -==== -You can customize the roles path by setting the environment variable `ANSIBLE_ROLES_PATH` or by using the `ansible-roles-path` flag. If the role is not found in the `ANSIBLE_ROLES_PATH` value, the Operator looks for it in `{{current directory}}/roles`. -==== - -.Prerequisites - -- link:https://ansible-runner.readthedocs.io/en/latest/install.html[Ansible Runner] version v1.1.0+ -- link:https://github.com/ansible/ansible-runner-http[Ansible Runner HTTP Event Emitter plug-in] version v1.0.0+ -- Performed the previous steps for testing the Kubernetes Collection locally - -.Procedure - -. Install your custom resource definition (CRD) and proper role-based access control (RBAC) definitions for your custom resource (CR): -+ -[source,terminal] ----- -$ make install ----- -+ -.Example output -[source,terminal] ----- -/usr/bin/kustomize build config/crd | kubectl apply -f - -customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com created ----- - -. Run the `make run` command: -+ -[source,terminal] ----- -$ make run ----- -+ -.Example output -[source,terminal] ----- -/home/user/memcached-operator/bin/ansible-operator run -{"level":"info","ts":1612739145.2871568,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.3.0","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"} -... -{"level":"info","ts":1612739148.347306,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":":8080"} -{"level":"info","ts":1612739148.3488882,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2} -{"level":"info","ts":1612739148.3490262,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false} -{"level":"info","ts":1612739148.3490646,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"} -{"level":"info","ts":1612739148.350217,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"} -{"level":"info","ts":1612739148.3506632,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"} -{"level":"info","ts":1612739148.350784,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"} -{"level":"info","ts":1612739148.5511978,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"} -{"level":"info","ts":1612739148.5512562,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8} ----- -+ -With the Operator now watching your CR for events, the creation of a CR will trigger your Ansible role to run. -+ -[NOTE] -==== -Consider an example `config/samples/<gvk>.yaml` CR manifest: - -[source,yaml] ----- -apiVersion: <group>.example.com/v1alpha1 -kind: <kind> -metadata: - name: "<kind>-sample" ----- - -Because the `spec` field is not set, Ansible is invoked with no extra variables. Passing extra variables from a CR to Ansible is covered in another section. It is important to set reasonable defaults for the Operator. -==== - -. Create an instance of your CR with the default variable `state` set to `present`: -+ -[source,terminal] ----- -$ oc apply -f config/samples/<gvk>.yaml ----- - -. Check that the `example-config` config map was created: -+ -[source,terminal] ----- -$ oc get configmaps ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS AGE -example-config Active 3s ----- - -. Modify your `config/samples/<gvk>.yaml` file to set the `state` field to `absent`. For example: -+ -[source,yaml] ----- -apiVersion: cache.example.com/v1 -kind: Memcached -metadata: - name: memcached-sample -spec: - state: absent ----- - -. Apply the changes: -+ -[source,terminal] ----- -$ oc apply -f config/samples/<gvk>.yaml ----- - -. Confirm that the config map is deleted: -+ -[source,terminal] ----- -$ oc get configmap ----- diff --git a/modules/osdk-ansible-inside-operator-logs-full-result.adoc b/modules/osdk-ansible-inside-operator-logs-full-result.adoc deleted file mode 100644 index 4594a7e66932..000000000000 --- a/modules/osdk-ansible-inside-operator-logs-full-result.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc - -[id="osdk-ansible-inside-operator-logs-full-result_{context}"] -= Enabling full Ansible results in logs - -You can set the environment variable `ANSIBLE_DEBUG_LOGS` to `True` to enable checking the full Ansible result in logs, which can be helpful when debugging. - -.Procedure - -* Edit the `config/manager/manager.yaml` and `config/default/manager_auth_proxy_patch.yaml` files to include the following configuration: -+ -[source,terminal] ----- - containers: - - name: manager - env: - - name: ANSIBLE_DEBUG_LOGS - value: "True" ----- diff --git a/modules/osdk-ansible-inside-operator-logs-verbose.adoc b/modules/osdk-ansible-inside-operator-logs-verbose.adoc deleted file mode 100644 index 3eda07a023f7..000000000000 --- a/modules/osdk-ansible-inside-operator-logs-verbose.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc - -[id="osdk-ansible-inside-operator-logs-verbose_{context}"] -= Enabling verbose debugging in logs - -While developing an Ansible-based Operator, it can be helpful to enable additional debugging in logs. - -.Procedure - -* Add the `ansible.sdk.operatorframework.io/verbosity` annotation to your custom resource to enable the verbosity level that you want. For example: -+ -[source,terminal] ----- -apiVersion: "cache.example.com/v1alpha1" -kind: "Memcached" -metadata: - name: "example-memcached" - annotations: - "ansible.sdk.operatorframework.io/verbosity": "4" -spec: - size: 4 ----- diff --git a/modules/osdk-ansible-inside-operator-logs-view.adoc b/modules/osdk-ansible-inside-operator-logs-view.adoc deleted file mode 100644 index 6c8d08e59a33..000000000000 --- a/modules/osdk-ansible-inside-operator-logs-view.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc - -[id="osdk-ansible-inside-operator-logs-view_{context}"] -= Viewing Ansible logs - -.Prerequisites - -* Ansible-based Operator running as a deployment on a cluster - -.Procedure - -* To view logs from an Ansible-based Operator, run the following command: -+ -[source,terminal] ----- -$ oc logs deployment/<project_name>-controller-manager \ - -c manager \//<1> - -n <namespace> <2> ----- -<1> View logs from the `manager` container. -<2> If you used the `make deploy` command to run the Operator as a deployment, use the `<project_name>-system` namespace. -+ -.Example output -[source,terminal] ----- -{"level":"info","ts":1612732105.0579333,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.3.0","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"} -{"level":"info","ts":1612732105.0587437,"logger":"cmd","msg":"WATCH_NAMESPACE environment variable not set. Watching all namespaces.","Namespace":""} -I0207 21:08:26.110949 7 request.go:645] Throttling request took 1.035521578s, request: GET:https://172.30.0.1:443/apis/flowcontrol.apiserver.k8s.io/v1alpha1?timeout=32s -{"level":"info","ts":1612732107.768025,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":"127.0.0.1:8080"} -{"level":"info","ts":1612732107.768796,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2} -{"level":"info","ts":1612732107.7688773,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false} -{"level":"info","ts":1612732107.7688901,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"} -{"level":"info","ts":1612732107.770032,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"} -I0207 21:08:27.770185 7 leaderelection.go:243] attempting to acquire leader lease memcached-operator-system/memcached-operator... -{"level":"info","ts":1612732107.770202,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"} -I0207 21:08:27.784854 7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator -{"level":"info","ts":1612732107.7850506,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"} -{"level":"info","ts":1612732107.8853772,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"} -{"level":"info","ts":1612732107.8854098,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4} ----- diff --git a/modules/osdk-ansible-inside-operator-logs.adoc b/modules/osdk-ansible-inside-operator-logs.adoc deleted file mode 100644 index 37ee2096fb9d..000000000000 --- a/modules/osdk-ansible-inside-operator-logs.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc - -[id="osdk-ansible-inside-operator-logs_{context}"] -= Ansible logs - -Ansible-based Operators provide logs about the Ansible run, which can be useful for debugging your Ansible tasks. The logs can also contain detailed information about the internals of the Operator and its interactions with Kubernetes. diff --git a/modules/osdk-ansible-k8s-install.adoc b/modules/osdk-ansible-k8s-install.adoc deleted file mode 100644 index 89011a4298c9..000000000000 --- a/modules/osdk-ansible-k8s-install.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-k8s-collection.adoc - -[id="osdk-ansible-installing-k8s-collection_{context}"] -= Installing the Kubernetes Collection for Ansible - -You can install the Kubernetes Collection for Ansible on your local workstation. - -.Procedure - -. Install Ansible 2.9+: -+ -[source,terminal] ----- -$ sudo dnf install ansible ----- - -. Install the link:https://github.com/openshift/openshift-restclient-python[OpenShift python client] package: -+ -[source,terminal] ----- -$ pip3 install openshift ----- - -. Install the Kubernetes Collection using one of the following methods: - -* You can install the collection directly from Ansible Galaxy: -+ -[source,terminal] ----- -$ ansible-galaxy collection install community.kubernetes ----- - -* If you have already initialized your Operator, you might have a `requirements.yml` file at the top level of your project. This file specifies Ansible dependencies that must be installed for your Operator to function. By default, this file installs the `community.kubernetes` collection as well as the `operator_sdk.util` collection, which provides modules and plug-ins for Operator-specific fuctions. -+ -To install the dependent modules from the `requirements.yml` file: -+ -[source,terminal] ----- -$ ansible-galaxy collection install -r requirements.yml ----- diff --git a/modules/osdk-ansible-k8s-local.adoc b/modules/osdk-ansible-k8s-local.adoc deleted file mode 100644 index 880514782732..000000000000 --- a/modules/osdk-ansible-k8s-local.adoc +++ /dev/null @@ -1,122 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-k8s-collection.adoc - -[id="osdk-ansible-k8s-local_{context}"] -= Testing the Kubernetes Collection locally - -Operator developers can run the Ansible code from their local machine as opposed to running and rebuilding the Operator each time. - -.Prerequisites - -* Initialize an Ansible-based Operator project and create an API that has a generated Ansible role by using the Operator SDK -* Install the Kubernetes Collection for Ansible - -.Procedure - -. In your Ansible-based Operator project directory, modify the `roles/<kind>/tasks/main.yml` file with the Ansible logic that you want. The `roles/<kind>/` directory is created when you use the `--generate-role` flag while creating an API. The `<kind>` replaceable matches the kind that you specified for the API. -+ -The following example creates and deletes a config map based on the value of a variable named `state`: -+ -[source,yaml] ----- ---- -- name: set ConfigMap example-config to {{ state }} - community.kubernetes.k8s: - api_version: v1 - kind: ConfigMap - name: example-config - namespace: default <1> - state: "{{ state }}" - ignore_errors: true <2> ----- -<1> Change this value if you want the config map to be created in a different namespace from `default`. -<2> Setting `ignore_errors: true` ensures that deleting a nonexistent config map does not fail. - -. Modify the `roles/<kind>/defaults/main.yml` file to set `state` to `present` by default: -+ -[source,yaml] ----- ---- -state: present ----- - -. Create an Ansible playbook by creating a `playbook.yml` file in the top-level of your project directory, and include your `<kind>` role: -+ -[source,yaml] ----- ---- -- hosts: localhost - roles: - - <kind> ----- - -. Run the playbook: -+ -[source,terminal] ----- -$ ansible-playbook playbook.yml ----- -+ -.Example output -[source,terminal] ----- -[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all' - -PLAY [localhost] ******************************************************************************** - -TASK [Gathering Facts] ******************************************************************************** -ok: [localhost] - -TASK [memcached : set ConfigMap example-config to present] ******************************************************************************** -changed: [localhost] - -PLAY RECAP ******************************************************************************** -localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - ----- - -. Verify that the config map was created: -+ -[source,terminal] ----- -$ oc get configmaps ----- -+ -.Example output -[source,terminal] ----- -NAME DATA AGE -example-config 0 2m1s ----- - -. Rerun the playbook setting `state` to `absent`: -+ -[source,terminal] ----- -$ ansible-playbook playbook.yml --extra-vars state=absent ----- -+ -.Example output -[source,terminal] ----- -[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all' - -PLAY [localhost] ******************************************************************************** - -TASK [Gathering Facts] ******************************************************************************** -ok: [localhost] - -TASK [memcached : set ConfigMap example-config to absent] ******************************************************************************** -changed: [localhost] - -PLAY RECAP ******************************************************************************** -localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 ----- - -. Verify that the config map was deleted: -+ -[source,terminal] ----- -$ oc get configmaps ----- diff --git a/modules/osdk-ansible-modify-manager.adoc b/modules/osdk-ansible-modify-manager.adoc deleted file mode 100644 index 853780a1b130..000000000000 --- a/modules/osdk-ansible-modify-manager.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc - -[id="osdk-ansible-modify-manager_{context}"] -= Modifying the manager - -Update your Operator project to provide the reconcile logic, in the form of an Ansible role, which runs every time a `Memcached` resource is created, updated, or deleted. - -.Procedure - -. Update the `roles/memcached/tasks/main.yml` file with the following structure: -+ -[source,yaml] ----- ---- -- name: start memcached - community.kubernetes.k8s: - definition: - kind: Deployment - apiVersion: apps/v1 - metadata: - name: '{{ ansible_operator_meta.name }}-memcached' - namespace: '{{ ansible_operator_meta.namespace }}' - spec: - replicas: "{{size}}" - selector: - matchLabels: - app: memcached - template: - metadata: - labels: - app: memcached - spec: - containers: - - name: memcached - command: - - memcached - - -m=64 - - -o - - modern - - -v - image: "docker.io/memcached:1.4.36-alpine" - ports: - - containerPort: 11211 ----- -+ -This `memcached` role ensures a `memcached` deployment exist and sets the deployment size. - -. Set default values for variables used in your Ansible role by editing the `roles/memcached/defaults/main.yml` file: -+ -[source,yaml] ----- ---- -# defaults file for Memcached -size: 1 ----- - -. Update the `Memcached` sample resource in the `config/samples/cache_v1_memcached.yaml` file with the following structure: -+ -[source,yaml] ----- -apiVersion: cache.example.com/v1 -kind: Memcached -metadata: - name: memcached-sample -spec: - size: 3 ----- -+ -The key-value pairs in the custom resource (CR) spec are passed to Ansible as extra variables. - -[NOTE] -==== -The names of all variables in the `spec` field are converted to snake case, meaning lowercase with an underscore, by the Operator before running Ansible. For example, `serviceAccount` in the spec becomes `service_account` in Ansible. - -You can disable this case conversion by setting the `snakeCaseParameters` option to `false` in your `watches.yaml` file. It is recommended that you perform some type validation in Ansible on the variables to ensure that your application is receiving expected input. -==== diff --git a/modules/osdk-ansible-project-layout.adoc b/modules/osdk-ansible-project-layout.adoc deleted file mode 100644 index 04cbcd601b74..000000000000 --- a/modules/osdk-ansible-project-layout.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-project-layout.adoc - -[id="osdk-ansible-project-layout_{context}"] -= Ansible-based project layout - -Ansible-based Operator projects generated using the `operator-sdk init --plugins ansible` command contain the following directories and files: - -[options="header",cols="1,4"] -|=== - -|File or directory |Purpose - -|`Dockerfile` -|Dockerfile for building the container image for the Operator. - -|`Makefile` -|Targets for building, publishing, deploying the container image that wraps the Operator binary, and targets for installing and uninstalling the custom resource definition (CRD). - -|`PROJECT` -|YAML file containing metadata information for the Operator. - -|`config/crd` -|Base CRD files and the `kustomization.yaml` file settings. - -|`config/default` -|Collects all Operator manifests for deployment. Use by the `make deploy` command. - -|`config/manager` -|Controller manager deployment. - -|`config/prometheus` -|`ServiceMonitor` resource for monitoring the Operator. - -|`config/rbac` -|Role and role binding for leader election and authentication proxy. - -|`config/samples` -|Sample resources created for the CRDs. - -|`config/testing` -|Sample configurations for testing. - -|`playbooks/` -|A subdirectory for the playbooks to run. - -|`roles/` -|Subdirectory for the roles tree to run. - -|`watches.yaml` -|Group/version/kind (GVK) of the resources to watch, and the Ansible invocation method. New entries are added by using the `create api` command. - -|`requirements.yml` -|YAML file containing the Ansible collections and role dependencies to install during a build. - -|`molecule/` -|Molecule scenarios for end-to-end testing of your role and Operator. - -|=== diff --git a/modules/osdk-ansible-runner-directory.adoc b/modules/osdk-ansible-runner-directory.adoc deleted file mode 100644 index 757b8116a53c..000000000000 --- a/modules/osdk-ansible-runner-directory.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-support.adoc - -[id="osdk-ansible-runner-directory_{context}"] -= Ansible Runner directory - -Ansible Runner keeps information about Ansible runs in the container. This is located at `/tmp/ansible-operator/runner/<group>/<version>/<kind>/<namespace>/<name>`. - -.Additional resources - -- To learn more about the `runner` directory, see the link:https://ansible-runner.readthedocs.io/en/latest/index.html[Ansible Runner documentation]. diff --git a/modules/osdk-ansible-watches-file.adoc b/modules/osdk-ansible-watches-file.adoc deleted file mode 100644 index 9bfc105a5209..000000000000 --- a/modules/osdk-ansible-watches-file.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/ansible/osdk-ansible-support.adoc - -[id="osdk-ansible-watches-file_{context}"] -= watches.yaml file - -A _group/version/kind (GVK)_ is a unique identifier for a Kubernetes API. The `watches.yaml` file contains a list of mappings from custom resources (CRs), identified by its GVK, to an Ansible role or playbook. The Operator expects this mapping file in a predefined location at `/opt/ansible/watches.yaml`. - -.`watches.yaml` file mappings -[cols="3,7",options="header"] -|=== -|Field -|Description - -|`group` -|Group of CR to watch. - -|`version` -|Version of CR to watch. - -|`kind` -|Kind of CR to watch - -|`role` (default) -|Path to the Ansible role added to the container. For example, if your `roles` directory is at `/opt/ansible/roles/` and your role is named `busybox`, this value would be `/opt/ansible/roles/busybox`. This field is mutually exclusive with the `playbook` field. - -|`playbook` -|Path to the Ansible playbook added to the container. This playbook is expected to be a way to call roles. This field is mutually exclusive with the `role` field. - -|`reconcilePeriod` (optional) -|The reconciliation interval, how often the role or playbook is run, for a given CR. - -|`manageStatus` (optional) -|When set to `true` (default), the Operator manages the status of the CR generically. When set to `false`, the status of the CR is managed elsewhere, by the specified role or playbook or in a separate controller. -|=== - -.Example `watches.yaml` file -[source,yaml] ----- -- version: v1alpha1 <1> - group: test1.example.com - kind: Test1 - role: /opt/ansible/roles/Test1 - -- version: v1alpha1 <2> - group: test2.example.com - kind: Test2 - playbook: /opt/ansible/playbook.yml - -- version: v1alpha1 <3> - group: test3.example.com - kind: Test3 - playbook: /opt/ansible/test3.yml - reconcilePeriod: 0 - manageStatus: false ----- -<1> Simple example mapping `Test1` to the `test1` role. -<2> Simple example mapping `Test2` to a playbook. -<3> More complex example for the `Test3` kind. Disables re-queuing and managing the CR status in the playbook. - -[id="osdk-ansible-watches-file-advanced_{context}"] -== Advanced options - -Advanced features can be enabled by adding them to your `watches.yaml` file per GVK. They can go below the `group`, `version`, `kind` and `playbook` or `role` fields. - -Some features can be overridden per resource using an annotation on that CR. The options that can be overridden have the annotation specified below. - -.Advanced watches.yaml file options -[cols="3,2,4,2,1",options="header"] -|=== -|Feature -|YAML key -|Description -|Annotation for override -|Default value - -|Reconcile period -|`reconcilePeriod` -|Time between reconcile runs for a particular CR. -|`ansbile.operator-sdk/reconcile-period` -|`1m` - -|Manage status -|`manageStatus` -|Allows the Operator to manage the `conditions` section of each CR `status` section. -| -|`true` - -|Watch dependent resources -|`watchDependentResources` -|Allows the Operator to dynamically watch resources that are created by Ansible. -| -|`true` - -|Watch cluster-scoped resources -|`watchClusterScopedResources` -|Allows the Operator to watch cluster-scoped resources that are created by Ansible. -| -|`false` - -|Max runner artifacts -|`maxRunnerArtifacts` -|Manages the number of link:https://ansible-runner.readthedocs.io/en/latest/intro.html#runner-artifacts-directory-hierarchy[artifact directories] that Ansible Runner keeps in the Operator container for each individual resource. -|`ansible.operator-sdk/max-runner-artifacts` -|`20` -|=== - -.Example watches.yml file with advanced options -[source,yaml] ----- -- version: v1alpha1 - group: app.example.com - kind: AppService - playbook: /opt/ansible/playbook.yml - maxRunnerArtifacts: 30 - reconcilePeriod: 5s - manageStatus: False - watchDependentResources: False ----- diff --git a/modules/osdk-apiservices.adoc b/modules/osdk-apiservices.adoc deleted file mode 100644 index 616907d2a35d..000000000000 --- a/modules/osdk-apiservices.adoc +++ /dev/null @@ -1,108 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-apiservices_{context}"] -= Understanding your API services - -As with CRDs, there are two types of API services that your Operator may use: _owned_ and _required_. - -[id="osdk-apiservices-owned_{context}"] -== Owned API services - -When a CSV owns an API service, it is responsible for describing the deployment of the extension `api-server` that backs it and the group/version/kind (GVK) it provides. - -An API service is uniquely identified by the group/version it provides and can be listed multiple times to denote the different kinds it is expected to provide. - -.Owned API service fields -[cols="2a,5a,2",options="header"] -|=== -|Field |Description |Required/optional - -|`Group` -|Group that the API service provides, for example `database.example.com`. -|Required - -|`Version` -|Version of the API service, for example `v1alpha1`. -|Required - -|`Kind` -|A kind that the API service is expected to provide. -|Required - -|`Name` -|The plural name for the API service provided. -|Required - -|`DeploymentName` -|Name of the deployment defined by your CSV that corresponds to your API service (required for owned API services). During the CSV pending phase, the OLM Operator searches the `InstallStrategy` of your CSV for a `Deployment` spec with a matching name, and if not found, does not transition the CSV to the "Install Ready" phase. -|Required - -|`DisplayName` -|A human readable version of your API service name, for example `MongoDB Standalone`. -|Required - -|`Description` -|A short description of how this API service is used by the Operator or a description of the functionality provided by the API service. -|Required - -|`Resources` -a|Your API services own one or more types of Kubernetes objects. These are listed in the resources section to inform your users of the objects they might need to troubleshoot or how to connect to the application, such as the service or ingress rule that exposes a database. - -It is recommended to only list out the objects that are important to a human, not an exhaustive list of everything you orchestrate. For example, do not list config maps that store internal state that are not meant to be modified by a user. -|Optional - -|`SpecDescriptors`, `StatusDescriptors`, and `ActionDescriptors` -|Essentially the same as for owned CRDs. -|Optional -|=== - -[id="osdk-apiservices-resource-creation_{context}"] -=== API service resource creation - -Operator Lifecycle Manager (OLM) is responsible for creating or replacing the service and API service resources for each unique owned API service: - -* Service pod selectors are copied from the CSV deployment matching the `DeploymentName` field of the API service description. - -* A new CA key/certificate pair is generated for each installation and the base64-encoded CA bundle is embedded in the respective API service resource. - -[id="osdk-apiservices-service-certs_{context}"] -=== API service serving certificates - -OLM handles generating a serving key/certificate pair whenever an owned API service is being installed. The serving certificate has a common name (CN) containing the host name of the generated `Service` resource and is signed by the private key of the CA bundle embedded in the corresponding API service resource. - -The certificate is stored as a type `kubernetes.io/tls` secret in the deployment namespace, and a volume named `apiservice-cert` is automatically appended to the volumes section of the deployment in the CSV matching the `DeploymentName` field of the API service description. - -If one does not already exist, a volume mount with a matching name is also appended to all containers of that deployment. This allows users to define a volume mount with the expected name to accommodate any custom path requirements. The path of the generated volume mount defaults to `/apiserver.local.config/certificates` and any existing volume mounts with the same path are replaced. - -[id="osdk-apiservice-required_{context}"] -== Required API services - -OLM ensures all required CSVs have an API service that is available and all expected GVKs are discoverable before attempting installation. This allows a CSV to rely on specific kinds provided by API services it does not own. - -.Required API service fields -[cols="2a,5a,2",options="header"] -|=== -|Field |Description |Required/optional - -|`Group` -|Group that the API service provides, for example `database.example.com`. -|Required - -|`Version` -|Version of the API service, for example `v1alpha1`. -|Required - -|`Kind` -|A kind that the API service is expected to provide. -|Required - -|`DisplayName` -|A human readable version of your API service name, for example `MongoDB Standalone`. -|Required - -|`Description` -|A short description of how this API service is used by the Operator or a description of the functionality provided by the API service. -|Required -|=== diff --git a/modules/osdk-building-helm-operator.adoc b/modules/osdk-building-helm-operator.adoc deleted file mode 100644 index bccdb7cc7214..000000000000 --- a/modules/osdk-building-helm-operator.adoc +++ /dev/null @@ -1,350 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-helm.adoc - -[id="osdk-building-helm-operator_{context}"] -= Building a Helm-based Operator using the Operator SDK - -This procedure walks through an example of building a simple Nginx Operator powered by a Helm chart using tools and libraries provided by the Operator SDK. - -[TIP] -==== -It is best practice to build a new Operator for each chart. This can allow for more native-behaving Kubernetes APIs (for example, `oc get Nginx`) and flexibility if you ever want to write a fully-fledged Operator in Go, migrating away from a Helm-based Operator. -==== - -.Prerequisites - -- Operator SDK CLI installed on the development workstation -- Access to a Kubernetes-based cluster v1.11.3+ (for example {product-title} {product-version}) using an account with `cluster-admin` permissions -- OpenShift CLI (`oc`) v{product-version}+ installed - -.Procedure - -. *Create a new Operator project.* A namespace-scoped Operator watches and manages resources in a single namespace. Namespace-scoped Operators are preferred because of their flexibility. They enable decoupled upgrades, namespace isolation for failures and monitoring, and differing API definitions. -+ -To create a new Helm-based, namespace-scoped `nginx-operator` project, use the following command: -+ -[source,terminal] ----- -$ operator-sdk new nginx-operator \ - --api-version=example.com/v1alpha1 \ - --kind=Nginx \ - --type=helm ----- -+ -[source,terminal] ----- -$ cd nginx-operator ----- -+ -This creates the `nginx-operator` project specifically for watching the Nginx resource with API version `example.com/v1apha1` and kind `Nginx`. - -. *Customize the Operator logic.* -+ -For this example, the `nginx-operator` executes the following reconciliation logic for each `Nginx` custom resource (CR): -+ --- -* Create an Nginx deployment if it does not exist. -* Create an Nginx service if it does not exist. -* Create an Nginx ingress if it is enabled and does not exist. -* Ensure that the deployment, service, and optional ingress match the desired configuration (for example, replica count, image, service type) as specified by the Nginx CR. --- -+ -By default, the `nginx-operator` watches `Nginx` resource events as shown in the `watches.yaml` file and executes Helm releases using the specified chart: -+ -[source,yaml] ----- -- version: v1alpha1 - group: example.com - kind: Nginx - chart: /opt/helm/helm-charts/nginx ----- - -.. *Review the Nginx Helm chart.* -+ -When a Helm Operator project is created, the Operator SDK creates an example Helm chart that contains a set of templates for a simple Nginx release. -+ -For this example, templates are available for deployment, service, and ingress resources, along with a `NOTES.txt` template, which Helm chart developers use to convey helpful information about a release. -+ -If you are not already familiar with Helm Charts, review the link:https://docs.helm.sh/developing_charts/[Helm Chart developer documentation]. - -.. *Understand the Nginx CR spec.* -+ -Helm uses a concept called link:https://docs.helm.sh/using_helm/#customizing-the-chart-before-installing[values] to provide customizations to the defaults of a Helm chart, which are defined in the `values.yaml` file. -+ -Override these defaults by setting the desired values in the CR spec. You can use the number of replicas as an example: - -... First, inspect the `helm-charts/nginx/values.yaml` file to find that the chart has a value called `replicaCount` and it is set to `1` by default. To have 2 Nginx instances in your deployment, your CR spec must contain `replicaCount: 2`. -+ -Update the `deploy/crds/example.com_v1alpha1_nginx_cr.yaml` file to look like the following: -+ -[source,yaml] ----- -apiVersion: example.com/v1alpha1 -kind: Nginx -metadata: - name: example-nginx -spec: - replicaCount: 2 ----- - -... Similarly, the default service port is set to `80`. To instead use `8080`, update the `deploy/crds/example.com_v1alpha1_nginx_cr.yaml` file again by adding the service port override: -+ -[source,yaml] ----- -apiVersion: example.com/v1alpha1 -kind: Nginx -metadata: - name: example-nginx -spec: - replicaCount: 2 - service: - port: 8080 ----- -+ -The Helm Operator applies the entire spec as if it was the contents of a values file, just like the `helm install -f ./overrides.yaml` command works. - -. *Deploy the CRD.* -+ -Before running the Operator, Kubernetes must know about the new custom resource definition (CRD) that the Operator will be watching. Deploy the following CRD: -+ -[source,terminal] ----- -$ oc create -f deploy/crds/example_v1alpha1_nginx_crd.yaml ----- - -. *Build and run the Operator.* -+ -There are two ways to build and run the Operator: -+ --- -* As a pod inside a Kubernetes cluster. -* As a Go program outside the cluster using the `operator-sdk up` command. --- -+ -Choose one of the following methods: - -.. *Run as a pod* inside a Kubernetes cluster. This is the preferred -method for production use. - -... Build the `nginx-operator` image and push it to a registry: -+ -[source,terminal] ----- -$ operator-sdk build quay.io/example/nginx-operator:v0.0.1 ----- -+ -[source,terminal] ----- -$ podman push quay.io/example/nginx-operator:v0.0.1 ----- - -... Deployment manifests are generated in the `deploy/operator.yaml` file. The deployment image in this file needs to be modified from the placeholder `REPLACE_IMAGE` to the previous built image. To do this, run: -+ -[source,terminal] ----- -$ sed -i 's|REPLACE_IMAGE|quay.io/example/nginx-operator:v0.0.1|g' deploy/operator.yaml ----- - -... Deploy the `nginx-operator` manifests: -+ -[source,terminal] ----- -$ oc create -f deploy/service_account.yaml ----- -+ -[source,terminal] ----- -$ oc create -f deploy/role.yaml ----- -+ -[source,terminal] ----- -$ oc create -f deploy/role_binding.yaml ----- -+ -[source,terminal] ----- -$ oc create -f deploy/operator.yaml ----- - -... Verify that the `nginx-operator` deployment is up and running: -+ -[source,terminal] ----- -$ oc get deployment ----- -+ -.Example output -[source,terminal] ----- -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -nginx-operator 1 1 1 1 1m ----- - -.. *Run outside the cluster.* This method is preferred during the development cycle to speed up deployment and testing. -+ -It is important that the chart path referenced in the `watches.yaml` file exists on your machine. By default, the `watches.yaml` file is scaffolded to work with an Operator image built with the `operator-sdk build` command. When developing and testing your Operator with the `operator-sdk run --local` command, the SDK looks in your local file system for this path. - -... Create a symlink at this location to point to the path of your Helm chart: -+ -[source,terminal] ----- -$ sudo mkdir -p /opt/helm/helm-charts ----- -+ -[source,terminal] ----- -$ sudo ln -s $PWD/helm-charts/nginx /opt/helm/helm-charts/nginx ----- - -... To run the Operator locally with the default Kubernetes configuration file present at `$HOME/.kube/config`: -+ -[source,terminal] ----- -$ operator-sdk run --local ----- -+ -To run the Operator locally with a provided Kubernetes configuration file: -+ -[source,terminal] ----- -$ operator-sdk run --local --kubeconfig=<path_to_config> ----- - -. *Deploy the `Nginx` CR.* -+ -Apply the `Nginx` CR that you modified earlier: -+ -[source,terminal] ----- -$ oc apply -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml ----- -+ -Ensure that the `nginx-operator` creates the deployment for the CR: -+ -[source,terminal] ----- -$ oc get deployment ----- -+ -.Example output -[source,terminal] ----- -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -example-nginx-b9phnoz9spckcrua7ihrbkrt1 2 2 2 2 1m ----- -+ -Check the pods to confirm two replicas were created: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -example-nginx-b9phnoz9spckcrua7ihrbkrt1-f8f9c875d-fjcr9 1/1 Running 0 1m -example-nginx-b9phnoz9spckcrua7ihrbkrt1-f8f9c875d-ljbzl 1/1 Running 0 1m ----- -+ -Check that the service port is set to `8080`: -+ -[source,terminal] ----- -$ oc get service ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -example-nginx-b9phnoz9spckcrua7ihrbkrt1 ClusterIP 10.96.26.3 <none> 8080/TCP 1m ----- - -. *Update the `replicaCount` and remove the port.* -+ -Change the `spec.replicaCount` field from `2` to `3`, remove the `spec.service` field, and apply the change: -+ -[source,terminal] ----- -$ cat deploy/crds/example.com_v1alpha1_nginx_cr.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: "example.com/v1alpha1" -kind: "Nginx" -metadata: - name: "example-nginx" -spec: - replicaCount: 3 ----- -+ -[source,terminal] ----- -$ oc apply -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml ----- -+ -Confirm that the Operator changes the deployment size: -+ -[source,terminal] ----- -$ oc get deployment ----- -+ -.Example output -[source,terminal] ----- -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -example-nginx-b9phnoz9spckcrua7ihrbkrt1 3 3 3 3 1m ----- -+ -Check that the service port is set to the default `80`: -+ -[source,terminal] ----- -$ oc get service ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -example-nginx-b9phnoz9spckcrua7ihrbkrt1 ClusterIP 10.96.26.3 <none> 80/TCP 1m ----- - -. *Clean up the resources:* -+ -[source,terminal] ----- -$ oc delete -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/operator.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/role_binding.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/role.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/service_account.yaml ----- -+ -[source,terminal] ----- -$ oc delete -f deploy/crds/example_v1alpha1_nginx_crd.yaml ----- diff --git a/modules/osdk-bundle-deploy-olm.adoc b/modules/osdk-bundle-deploy-olm.adoc deleted file mode 100644 index 9819b4c8b7e0..000000000000 --- a/modules/osdk-bundle-deploy-olm.adoc +++ /dev/null @@ -1,126 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc -// * operators/operator_sdk/osdk-working-bundle-images.adoc - -ifeval::["{context}" == "osdk-golang-tutorial"] -:golang: -endif::[] -ifeval::["{context}" == "osdk-working-bundle-images"] -:golang: -endif::[] - -[id="osdk-bundle-deploy-olm_{context}"] -= Bundling an Operator and deploying with Operator Lifecycle Manager - -Operator Lifecycle Manager (OLM) helps you to install, update, and generally manage the lifecycle of Operators and their associated services on a Kubernetes cluster. OLM is installed by default on {product-title} and runs as a Kubernetes extension so that you can use the web console and the OpenShift CLI (`oc`) for all Operator lifecycle management functions without any additional tools. - -The Operator Bundle Format is the default packaging method for Operator SDK and OLM. You can get your Operator ready for OLM by using the Operator SDK to build, push, validate, and run a bundle image with OLM. - -.Prerequisites - -- Operator SDK CLI installed on a development workstation -- OpenShift CLI (`oc`) v{product-version}+ installed -- Operator Lifecycle Manager (OLM) installed on a Kubernetes-based cluster (v1.16.0 or later if you use `apiextensions.k8s.io/v1` CRDs, for example {product-title} {product-version}) -- Logged into the cluster with `oc` using an account with `cluster-admin` permissions -- Operator project initialized by using the Operator SDK -ifdef::golang[] -- If your Operator is Go-based, your project must have been updated to use supported images for running on {product-title} -endif::[] - -.Procedure - -. Run the following `make` commands in your Operator project directory to build and push your Operator image. Modify the `IMG` argument in the following steps to reference a repository that you have access to. You can obtain an account for storing containers at repository sites such as Quay.io. - -.. Build the image: -+ -[source,terminal] ----- -$ make docker-build IMG=<registry>/<user>/<operator_image_name>:<tag> ----- - -.. Push the image to a repository: -+ -[source,terminal] ----- -$ make docker-push IMG=<registry>/<user>/<operator_image_name>:<tag> ----- - -. Update your `Makefile` by setting the `IMG` URL to your Operator image name and tag that you pushed: -+ -[source,terminal] ----- -$ # Image URL to use all building/pushing image targets -IMG ?= <registry>/<user>/<operator_image_name>:<tag> ----- -+ -This value is used for subsequent operations. - -. Create your Operator bundle manifest by running the `make bundle` command, which invokes several commands, including the Operator SDK `generate bundle` and `bundle validate` subcommands: -+ -[source,terminal] ----- -$ make bundle ----- -+ -Bundle manifests for an Operator describe how to display, create, and manage an application. The `make bundle` command creates the following files and directories in your Operator project: -+ --- -* A bundle manifests directory named `bundle/manifests` that contains a `ClusterServiceVersion` object -* A bundle metadata directory named `bundle/metadata` -* All custom resource definitions (CRDs) in a `config/crd` directory -* A Dockerfile `bundle.Dockerfile` --- -+ -These files are then automatically validated by using `operator-sdk bundle validate` to ensure the on-disk bundle representation is correct. - -. Build and push your bundle image by running the following commands. OLM consumes Operator bundles using an index image, which reference one or more bundle images. - -.. Build the bundle image. Set `BUNDLE_IMAGE` with the details for the registry, user namespace, and image tag where you intend to push the image: -+ -[source,terminal] ----- -$ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag> ----- - -.. Push the bundle image: -+ -[source,terminal] ----- -$ docker push <registry>/<user>/<bundle_image_name>:<tag> ----- - -. Check the status of OLM on your cluster by using the following Operator SDK command: -+ -[source,terminal] ----- -$ operator-sdk olm status \ - --olm-namespace=openshift-operator-lifecycle-manager ----- - -. Run the Operator on your cluster by using the OLM integration in Operator SDK: -+ -[source,terminal] ----- -$ operator-sdk run bundle \ - [-n <namespace>] \//<1> - <registry>/<user>/<bundle_image_name>:<tag> ----- -<1> By default, the command installs the Operator in the currently active project in your `~/.kube/config` file. You can add the `-n` flag to set a different namespace scope for the installation. -+ -This command performs the following actions: -+ --- -* Create an index image with your bundle image injected. -* Create a catalog source that points to your new index image, which enables OperatorHub to discover your Operator. -* Deploy your Operator to your cluster by creating an Operator group, subscription, install plan, and all other required objects, including RBAC. --- - -ifeval::["{context}" == "osdk-golang-tutorial"] -:!golang: -endif::[] -ifeval::["{context}" == "osdk-working-bundle-images"] -:!golang: -endif::[] diff --git a/modules/osdk-bundle-upgrade-olm.adoc b/modules/osdk-bundle-upgrade-olm.adoc deleted file mode 100644 index 80878f9eb21f..000000000000 --- a/modules/osdk-bundle-upgrade-olm.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-working-bundle-images.adoc - -[id="osdk-bundle-upgrade-olm_{context}"] -= Testing an Operator upgrade on Operator Lifecycle Manager - -You can quickly test upgrading your Operator by using Operator Lifecycle Manager (OLM) integration in the Operator SDK, without requiring you to manually manage index images and catalog sources. - -The `run bundle-upgrade` subcommand automates triggering an installed Operator to upgrade to a later version by specifying a bundle image for the later version. - -.Prerequisites - -- Operator installed with OLM by using the `run bundle` subcommand -- A bundle image that represents a later version of the installed Operator - -.Procedure - -. If your Operator has not already been installed on OLM with the `run bundle` subcommand, install the earlier version of your Operator by specifying the bundle image. For example, for a Memcached Operator: -+ -[source,terminal] ----- -$ operator-sdk run bundle <registry>/<user>/memcached-operator:v0.0.1 ----- -+ -.Example output -[source,terminal] ----- -INFO[0009] Successfully created registry pod: quay-io-demo-memcached-operator-v0-0-1 -INFO[0009] Created CatalogSource: memcached-operator-catalog -INFO[0010] OperatorGroup "operator-sdk-og" created -INFO[0010] Created Subscription: memcached-operator-v0-0-1-sub -INFO[0013] Approved InstallPlan install-bqggr for the Subscription: memcached-operator-v0-0-1-sub -INFO[0013] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to reach 'Succeeded' phase -INFO[0013] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to appear -INFO[0019] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Succeeded ----- - -. Upgrade the installed Operator by specifying the bundle image for the later Operator version: -+ -[source,terminal] ----- -$ operator-sdk run bundle-upgrade <registry>/<user>/memcached-operator:v0.0.2 ----- -+ -.Example output -[source,terminal] ----- -INFO[0002] Found existing subscription with name memcached-operator-v0-0-1-sub and namespace my-project -INFO[0002] Found existing catalog source with name memcached-operator-catalog and namespace my-project -INFO[0009] Successfully created registry pod: quay-io-demo-memcached-operator-v0-0-2 -INFO[0009] Updated catalog source memcached-operator-catalog with address and annotations -INFO[0010] Deleted previous registry pod with name "quay-io-demo-memcached-operator-v0-0-1" -INFO[0041] Approved InstallPlan install-gvcjh for the Subscription: memcached-operator-v0-0-1-sub -INFO[0042] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.2" to reach 'Succeeded' phase -INFO[0042] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: InstallReady -INFO[0043] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Installing -INFO[0044] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Succeeded -INFO[0044] Successfully upgraded to "memcached-operator.v0.0.2" ----- - -. Clean up the installed Operators: -+ -[source,terminal] ----- -$ operator-sdk cleanup memcached-operator ----- diff --git a/modules/osdk-cli-ref-bundle.adoc b/modules/osdk-cli-ref-bundle.adoc deleted file mode 100644 index 13f66844cd7c..000000000000 --- a/modules/osdk-cli-ref-bundle.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-bundle_{context}"] -= bundle - -The `operator-sdk bundle` command manages Operator bundle metadata. - -[id="osdk-cli-ref-bundle-validate_{context}"] -== validate - -The `bundle validate` subcommand validates an Operator bundle. - -.`bundle validate` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`-h`, `--help` -|Help output for the `bundle validate` subcommand. - -|`--index-builder` (string) -|Tool to pull and unpack bundle images. Only used when validating a bundle image. Available options are `docker`, which is the default, `podman`, or `none`. - -|`--list-optional` -|List all optional validators available. When set, no validators are run. - -|`--select-optional` (string) -|Label selector to select optional validators to run. When run with the `--list-optional` flag, lists available optional validators. - -|=== diff --git a/modules/osdk-cli-ref-cleanup.adoc b/modules/osdk-cli-ref-cleanup.adoc deleted file mode 100644 index d93021cd69b6..000000000000 --- a/modules/osdk-cli-ref-cleanup.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-cleanup_{context}"] -= cleanup - -The `operator-sdk cleanup` command destroys and removes resources that were created for an Operator that was deployed with the `run` command. - -.`cleanup` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`-h`, `--help` -|Help output for the `run bundle` subcommand. - -|`--kubeconfig` (string) -|Path to the `kubeconfig` file to use for CLI requests. - -|`n`, `--namespace` (string) -|If present, namespace in which to run the CLI request. - -|`--timeout <duration>` -|Time to wait for the command to complete before failing. The default value is `2m0s`. - -|=== diff --git a/modules/osdk-cli-ref-completion.adoc b/modules/osdk-cli-ref-completion.adoc deleted file mode 100644 index e8c402509c4b..000000000000 --- a/modules/osdk-cli-ref-completion.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-completion_{context}"] -= completion - -The `operator-sdk completion` command generates shell completions to make issuing CLI commands quicker and easier. - -.`completion` subcommands -[options="header",cols="1,3"] -|=== -|Subcommand |Description - -|`bash` -|Generate bash completions. - -|`zsh` -|Generate zsh completions. -|=== - -.`completion` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`-h, --help` -|Usage help output. -|=== - -For example: - -[source,terminal] ----- -$ operator-sdk completion bash ----- - -.Example output -[source,terminal] ----- -# bash completion for operator-sdk -*- shell-script -*- -... -# ex: ts=4 sw=4 et filetype=sh ----- diff --git a/modules/osdk-cli-ref-create.adoc b/modules/osdk-cli-ref-create.adoc deleted file mode 100644 index 6ec86e4e1025..000000000000 --- a/modules/osdk-cli-ref-create.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-create_{context}"] -= create - -The `operator-sdk create` command is used to create, or _scaffold_, a Kubernetes API. - -[id="osdk-cli-ref-create-api_{context}"] -== api - -The `create api` subcommand scaffolds a Kubernetes API. The subcommand must be run in a project that was initialized with the `init` command. - -.`create api` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`-h`, `--help` -|Help output for the `run bundle` subcommand. - -|=== diff --git a/modules/osdk-cli-ref-generate-bundle.adoc b/modules/osdk-cli-ref-generate-bundle.adoc deleted file mode 100644 index a92cadc699ec..000000000000 --- a/modules/osdk-cli-ref-generate-bundle.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-generate-bundle_{context}"] -= bundle - -The `generate bundle` subcommand generates a set of bundle manifests, metadata, and a `bundle.Dockerfile` file for your Operator project. - -[NOTE] -==== -Typically, you run the `generate kustomize manifests` subcommand first to generate the input link:https://kustomize.io/[Kustomize] bases that are used by the `generate bundle` subcommand. However, you can use the `make bundle` command in an initialized project to automate running these commands in sequence. -==== - -.`generate bundle` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`--channels` (string) -|Comma-separated list of channels to which the bundle belongs. The default value is `alpha`. - -|`--crds-dir` (string) -|Root directory for `CustomResoureDefinition` manifests. - -|`--default-channel` (string) -|The default channel for the bundle. - -|`--deploy-dir` (string) -|Root directory for Operator manifests, such as deployments and RBAC. This directory is different from the directory passed to the `--input-dir` flag. - -|`-h`, `--help` -|Help for `generate bundle` - -|`--input-dir` (string) -|Directory from which to read an existing bundle. This directory is the parent of your bundle `manifests` directory and is different from the `--deploy-dir` directory. - -|`--kustomize-dir` (string) -|Directory containing Kustomize bases and a `kustomization.yaml` file for bundle manifests. The default path is `config/manifests`. - -|`--manifests` -|Generate bundle manifests. - -|`--metadata` -|Generate bundle metadata and Dockerfile. - -|`--output-dir` (string) -|Directory to write the bundle to. - -|`--overwrite` -|Overwrite the bundle metadata and Dockerfile if they exist. The default value is `true`. - -|`--package` (string) -|Package name for the bundle. - -|`-q`, `--quiet` -|Run in quiet mode. - -|`--stdout` -|Write bundle manifest to standard out. - -|`--version` (string) -|Semantic version of the Operator in the generated bundle. Set only when creating a new bundle or upgrading the Operator. - -|=== diff --git a/modules/osdk-cli-ref-generate-kustomize.adoc b/modules/osdk-cli-ref-generate-kustomize.adoc deleted file mode 100644 index de4e3efc9415..000000000000 --- a/modules/osdk-cli-ref-generate-kustomize.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-generate-kustomize_{context}"] -= kustomize - -The `generate kustomize` subcommand contains subcommands that generate link:https://kustomize.io/[Kustomize] data for the Operator. - -[id="osdk-cli-ref-generate-kustomize-manifests_{context}"] -== manifests - -The `generate kustomize manifests` subcommand generates or regenerates Kustomize bases and a `kustomization.yaml` file in the `config/manifests` directory, which are used to build bundle manifests by other Operator SDK commands. This command interactively asks for UI metadata, an important component of manifest bases, by default unless a base already exists or you set the `--interactive=false` flag. - -.`generate kustomize manifests` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`--apis-dir` (string) -|Root directory for API type definitions. - -|`-h`, `--help` -|Help for `generate kustomize manifests`. - -|`--input-dir` (string) -|Directory containing existing Kustomize files. - -|`--interactive` -|When set to `false`, if no Kustomize base exists, an interactive command prompt is presented to accept custom metadata. - -|`--output-dir` (string) -|Directory where to write Kustomize files. - -|`--package` (string) -|Package name. - -|`-q`, `--quiet` -|Run in quiet mode. - -|=== diff --git a/modules/osdk-cli-ref-generate.adoc b/modules/osdk-cli-ref-generate.adoc deleted file mode 100644 index f102a98685c1..000000000000 --- a/modules/osdk-cli-ref-generate.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-generate_{context}"] -= generate - -The `operator-sdk generate` command invokes a specific generator to generate code or manifests. diff --git a/modules/osdk-cli-ref-init.adoc b/modules/osdk-cli-ref-init.adoc deleted file mode 100644 index b134085ae096..000000000000 --- a/modules/osdk-cli-ref-init.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-init_{context}"] -= init - -The `operator-sdk init` command initializes a Operator project and generates, or _scaffolds_, a default project directory layout for the given plug-in. - -This command writes the following files: - -* Boilerplate license file -* `PROJECT` file with the domain and repository -* `Makefile` to build the project -* `go.mod` file with project dependencies -* `kustomization.yaml` file for customizing manifests -* Patch file for customizing images for manager manifests -* Patch file for enabling Prometheus metrics -* `main.go` file to run - -.`init` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`--help, -h` -|Help output for the `init` command. - -|`--plugins` (string) -|Name and optionally version of the plug-in to initialize the project with. Available plug-ins are `ansible.sdk.operatorframework.io/v1`, `go.kubebuilder.io/v2`, `go.kubebuilder.io/v3`, and `helm.sdk.operatorframework.io/v1`. - -|`--project-version` -|Project version. Available values are `2` and `3-alpha`, which is the default. -|=== diff --git a/modules/osdk-cli-ref-run-bundle-upgrade.adoc b/modules/osdk-cli-ref-run-bundle-upgrade.adoc deleted file mode 100644 index 2ebd03063b00..000000000000 --- a/modules/osdk-cli-ref-run-bundle-upgrade.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-run-bundle-upgrade_{context}"] -= bundle-upgrade - -The `run bundle-upgrade` subcommand upgrades an Operator that was previously installed in the bundle format with Operator Lifecycle Manager (OLM). - -.`run bundle-upgrade` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`--timeout <duration>` -|Upgrade timeout. The default value is `2m0s`. - -|`--kubeconfig` (string) -|Path to the `kubeconfig` file to use for CLI requests. - -|`n`, `--namespace` (string) -|If present, namespace in which to run the CLI request. - -|`-h`, `--help` -|Help output for the `run bundle` subcommand. - -|=== diff --git a/modules/osdk-cli-ref-run-bundle.adoc b/modules/osdk-cli-ref-run-bundle.adoc deleted file mode 100644 index a3c936cb660c..000000000000 --- a/modules/osdk-cli-ref-run-bundle.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-run-bundle_{context}"] -= bundle - -The `run bundle` subcommand deploys an Operator in the bundle format with Operator Lifecycle Manager (OLM). - -.`run bundle` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`--index-image` (string) -|Index image in which to inject a bundle. The default image is `quay.io/operator-framework/upstream-opm-builder:latest`. - -|`--install-mode <install_mode_value>` -|Install mode supported by the cluster service version (CSV) of the Operator, for example `AllNamespaces` or `SingleNamespace`. - -|`--timeout <duration>` -|Install timeout. The default value is `2m0s`. - -|`--kubeconfig` (string) -|Path to the `kubeconfig` file to use for CLI requests. - -|`n`, `--namespace` (string) -|If present, namespace in which to run the CLI request. - -|`-h`, `--help` -|Help output for the `run bundle` subcommand. - -|=== diff --git a/modules/osdk-cli-ref-run.adoc b/modules/osdk-cli-ref-run.adoc deleted file mode 100644 index 3263b9c15a75..000000000000 --- a/modules/osdk-cli-ref-run.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-run_{context}"] -= run - -The `operator-sdk run` command provides options that can launch the Operator in various environments. diff --git a/modules/osdk-cli-ref-scorecard.adoc b/modules/osdk-cli-ref-scorecard.adoc deleted file mode 100644 index 56b1e8ad9e23..000000000000 --- a/modules/osdk-cli-ref-scorecard.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-ref.adoc -// * operators/operator_sdk/osdk-cli-ref.adoc - -[id="osdk-cli-ref-scorecard_{context}"] -= scorecard - -The `operator-sdk scorecard` command runs the scorecard tool to validate an Operator bundle and provide suggestions for improvements. The command takes one argument, either a bundle image or directory containing manifests and metadata. If the argument holds an image tag, the image must be present remotely. - -.`scorecard` flags -[options="header",cols="1,3"] -|=== -|Flag |Description - -|`-c`, `--config` (string) -|Path to scorecard configuration file. The default path is `bundle/tests/scorecard/config.yaml`. - -|`-h`, `--help` -|Help output for the `scorecard` command. - -|`--kubeconfig` (string) -|Path to `kubeconfig` file. - -|`-L`, `--list` -|List which tests are available to run. - -|`-n`, --namespace (string) -|Namespace in which to run the test images. - -|`-o`, `--output` (string) -|Output format for results. Available values are `text`, which is the default, and `json`. - -|`-l`, `--selector` (string) -|Label selector to determine which tests are run. - -|`-s`, `--service-account` (string) -|Service account to use for tests. The default value is `default`. - -|`-x`, `--skip-cleanup` -|Disable resource cleanup after tests are run. - -|`-w`, `--wait-time <duration>` -|Seconds to wait for tests to complete, for example `35s`. The default value is `30s`. - -|=== diff --git a/modules/osdk-common-prereqs.adoc b/modules/osdk-common-prereqs.adoc deleted file mode 100644 index 2c07bde165a2..000000000000 --- a/modules/osdk-common-prereqs.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-quickstart.adoc -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/helm/osdk-helm-quickstart.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc -// * operators/operator_sdk/osdk-working-bundle-images.adoc - -ifeval::["{context}" == "osdk-ansible-quickstart"] -:ansible: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:ansible: -endif::[] - -[id="osdk-common-prereqs_{context}"] -= Prerequisites - -- xref:../../../operators/operator_sdk/osdk-installing-cli.adoc#osdk-installing-cli[Operator SDK CLI installed] -- xref:../../../cli_reference/openshift_cli/getting-started-cli.adoc#getting-started-cli[OpenShift CLI (`oc`) v{product-version}+ installed] -ifdef::golang[] -- link:https://golang.org/dl/[Go] v1.13+ -- link:https://www.mercurial-scm.org/downloads[Mercurial] v3.9+ -endif::[] -ifdef::ansible[] -- link:https://docs.ansible.com/ansible/latest/index.html[Ansible] version v2.9.0+ -- link:https://ansible-runner.readthedocs.io/en/latest/install.html[Ansible Runner] version v1.1.0+ -- link:https://github.com/ansible/ansible-runner-http[Ansible Runner HTTP Event Emitter plug-in] version v1.0.0+ -- link:https://pypi.org/project/openshift/[OpenShift Python client] version v0.11.2+ -endif::[] -- Logged into an {product-title} {product-version} cluster with `oc` with an account that has `cluster-admin` permissions -- To allow the cluster pull the image, the repository where you push your image must be set as public, or you must configure an image pull secret. - -ifeval::["{context}" == "osdk-ansible-quickstart"] -:!ansible: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:!ansible: -endif::[] diff --git a/modules/osdk-crd-templates.adoc b/modules/osdk-crd-templates.adoc deleted file mode 100644 index 01e4542829fe..000000000000 --- a/modules/osdk-crd-templates.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-crds-templates_{context}"] -= CRD templates - -Users of your Operator must be made aware of which options are required versus optional. You can provide templates for each of your custom resource definitions (CRDs) with a minimum set of configuration as an annotation named `alm-examples`. Compatible UIs will pre-fill this template for users to further customize. - -The annotation consists of a list of the kind, for example, the CRD name and the corresponding `metadata` and `spec` of the Kubernetes object. - -The following full example provides templates for `EtcdCluster`, `EtcdBackup` and `EtcdRestore`: - -[source,yaml] ----- -metadata: - annotations: - alm-examples: >- - [{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdCluster","metadata":{"name":"example","namespace":"default"},"spec":{"size":3,"version":"3.2.13"}},{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdRestore","metadata":{"name":"example-etcd-cluster"},"spec":{"etcdCluster":{"name":"example-etcd-cluster"},"backupStorageType":"S3","s3":{"path":"<full-s3-path>","awsSecret":"<aws-secret>"}}},{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdBackup","metadata":{"name":"example-etcd-cluster-backup"},"spec":{"etcdEndpoints":["<etcd-cluster-endpoints>"],"storageType":"S3","s3":{"path":"<full-s3-path>","awsSecret":"<aws-secret>"}}}] ----- diff --git a/modules/osdk-crds.adoc b/modules/osdk-crds.adoc deleted file mode 100644 index b6f2883e79c7..000000000000 --- a/modules/osdk-crds.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-crds_{context}"] -= Understanding your custom resource definitions (CRDs) - -There are two types of custom resource definitions (CRDs) that your Operator can use: ones that are _owned_ by it and ones that it depends on, which are _required_. diff --git a/modules/osdk-create-cr.adoc b/modules/osdk-create-cr.adoc deleted file mode 100644 index 3fa369a9b791..000000000000 --- a/modules/osdk-create-cr.adoc +++ /dev/null @@ -1,226 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -ifeval::["{context}" == "osdk-golang-tutorial"] -:golang: -:app-proper: Memcached -:app: memcached -:group: cache -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:ansible: -:app-proper: Memcached -:app: memcached -:group: cache -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:helm: -:app-proper: Nginx -:app: nginx -:group: demo -endif::[] - -[id="osdk-create-cr_{context}"] -= Creating a custom resource - -After your Operator is installed, you can test it by creating a custom resource (CR) that is now provided on the cluster by the Operator. - -.Prerequisites - -* Example {app-proper} Operator, which provides the `{app-proper}` CR, installed on a cluster - -.Procedure - -. Change to the namespace where your Operator is installed. For example, if you deployed the Operator using the `make deploy` command: -+ -[source,terminal,subs="attributes+"] ----- -$ oc project {app}-operator-system ----- - -. Edit the sample `{app-proper}` CR manifest at `config/samples/{group}_v1_{app}.yaml` to contain the following specification: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: {group}.example.com/v1 -kind: {app-proper} -metadata: - name: {app}-sample -... -spec: -... -ifdef::helm[] - replicaCount: 3 -endif::[] -ifndef::helm[] - size: 3 -endif::[] ----- - -. Create the CR: -+ -[source,terminal,subs="attributes+"] ----- -$ oc apply -f config/samples/{group}_v1_{app}.yaml ----- - -. Ensure that the `{app-proper}` Operator creates the deployment for the sample CR with the correct size: -+ -[source,terminal] ----- -$ oc get deployments ----- -+ -.Example output -[source,terminal] -ifdef::helm[] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -nginx-operator-controller-manager 1/1 1 1 8m -nginx-sample 3/3 3 3 1m ----- -endif::[] -ifndef::helm[] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -memcached-operator-controller-manager 1/1 1 1 8m -memcached-sample 3/3 3 3 1m ----- -endif::[] - -. Check the pods and CR status to confirm the status is updated with the {app-proper} pod names. - -.. Check the pods: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -.Example output -[source,terminal] -ifdef::helm[] ----- -NAME READY STATUS RESTARTS AGE -nginx-sample-6fd7c98d8-7dqdr 1/1 Running 0 1m -nginx-sample-6fd7c98d8-g5k7v 1/1 Running 0 1m -nginx-sample-6fd7c98d8-m7vn7 1/1 Running 0 1m ----- -endif::[] -ifndef::helm[] ----- -NAME READY STATUS RESTARTS AGE -memcached-sample-6fd7c98d8-7dqdr 1/1 Running 0 1m -memcached-sample-6fd7c98d8-g5k7v 1/1 Running 0 1m -memcached-sample-6fd7c98d8-m7vn7 1/1 Running 0 1m ----- -endif::[] - -.. Check the CR status: -+ -[source,terminal,subs="attributes+"] ----- -$ oc get {app}/{app}-sample -o yaml ----- -+ -.Example output -[source,yaml,subs="attributes+"] ----- -apiVersion: {group}.example.com/v1 -kind: {app-proper} -metadata: -... - name: {app}-sample -... -spec: -ifdef::helm[] - replicaCount: 3 -endif::[] -ifndef::helm[] - size: 3 -endif::[] -status: - nodes: - - {app}-sample-6fd7c98d8-7dqdr - - {app}-sample-6fd7c98d8-g5k7v - - {app}-sample-6fd7c98d8-m7vn7 ----- - -. Update the deployment size. - -.. Update `config/samples/{group}_v1_{app}.yaml` file to change the `spec.size` field in the `{app-proper}` CR from `3` to `5`: -+ -[source,terminal,subs="attributes+"] ----- -$ oc patch {app} {app}-sample \ -ifdef::helm[] - -p '{"spec":{"replicaCount": 5}}' \ -endif::[] -ifndef::helm[] - -p '{"spec":{"size": 5}}' \ -endif::[] - --type=merge ----- - -.. Confirm that the Operator changes the deployment size: -+ -[source,terminal] ----- -$ oc get deployments ----- -+ -.Example output -[source,terminal] -ifdef::helm[] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -nginx-operator-controller-manager 1/1 1 1 10m -nginx-sample 5/5 5 5 3m ----- -endif::[] -ifndef::helm[] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -memcached-operator-controller-manager 1/1 1 1 10m -memcached-sample 5/5 5 5 3m ----- -endif::[] - -. Clean up the resources that have been created as part of this tutorial. - -* If you used the `make deploy` command to test the Operator, run the following command: -+ -[source,terminal] ----- -$ make undeploy ----- - -* If you used the `operator-sdk run bundle` command to test the Operator, run the following command: -+ -[source,terminal] ----- -$ operator-sdk cleanup <project_name> ----- - - -ifeval::["{context}" == "osdk-golang-tutorial"] -:!golang: -:!app-proper: -:!app: -:!group: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:!ansible: -:!app-proper: -:!app: -:!group: -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:!helm: -:!app-proper: -:!app: -:!group: -endif::[] diff --git a/modules/osdk-create-project.adoc b/modules/osdk-create-project.adoc deleted file mode 100644 index 009bab01c58d..000000000000 --- a/modules/osdk-create-project.adoc +++ /dev/null @@ -1,137 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -ifeval::["{context}" == "osdk-golang-tutorial"] -:golang: -:type: Go -:app: memcached -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:ansible: -:type: Ansible -:app: memcached -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:helm: -:type: Helm -:app: nginx -endif::[] - -[id="osdk-create-project_{context}"] -= Creating a project - -Use the Operator SDK CLI to create a project called `{app}-operator`. - -.Procedure - -. Create a directory for the project: -+ -[source,terminal,subs="attributes+"] ----- -$ mkdir -p $HOME/projects/{app}-operator ----- - -. Change to the directory: -+ -[source,terminal,subs="attributes+"] ----- -$ cd $HOME/projects/{app}-operator ----- - -ifdef::golang[] -. Activate support for Go modules: -+ -[source,terminal] ----- -$ export GO111MODULE=on ----- -endif::[] - -. Run the `operator-sdk init` command -ifdef::ansible[] -with the `ansible` plug-in -endif::[] -ifdef::helm[] -with the `helm` plug-in -endif::[] -to initialize the project: -+ -[source,terminal,subs="attributes+"] -ifdef::golang[] ----- -$ operator-sdk init \ - --domain=example.com \ - --repo=github.com/example-inc/{app}-operator ----- -+ -[NOTE] -==== -The `operator-sdk init` command uses the Go plug-in by default. -==== -+ -The `operator-sdk init` command generates a `go.mod` file to be used with link:https://golang.org/ref/mod[Go modules]. The `--repo` flag is required when creating a project outside of `$GOPATH/src/`, because generated files require a valid module path. - -. To enable your Go-based Operator to run on {product-title}, edit the `config/manager/manager.yaml` file and replace the following line: -+ -[source,yaml] ----- -runAsUser: 65532 ----- -+ -with: -+ -[source,yaml] ----- -runAsNonRoot: true ----- -+ -[NOTE] -==== -This step is a temporary workaround required for Go-based Operators only. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1914406#c1[BZ#1914406]. -==== -endif::[] -ifdef::ansible[] ----- -$ operator-sdk init \ - --plugins=ansible \ - --domain=example.com ----- -endif::[] -ifdef::helm[] ----- -$ operator-sdk init \ - --plugins=helm \ - --domain=example.com \ - --group=demo \ - --version=v1 \ - --kind=Nginx ----- -+ -[NOTE] -==== -By default, the `helm` plug-in initializes a project using a boilerplate Helm chart. You can use additional flags, such as the `--helm-chart` flag, to initialize a project using an existing Helm chart. -==== -+ -The `init` command creates the `nginx-operator` project specifically for watching a resource with API version `example.com/v1` and kind `Nginx`. - -. For Helm-based projects, the `init` command generates the RBAC rules in the `config/rbac/role.yaml` file based on the resources that would be deployed by the default manifest for the chart. Verify that the rules generated in this file meet the permission requirements of the Operator. -endif::[] - -ifeval::["{context}" == "osdk-golang-tutorial"] -:!golang: -:!type: -:!app: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:!ansible: -:!type: -:!app: -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:!helm: -:!type: -:!app: -endif::[] diff --git a/modules/osdk-csv-bundle-files.adoc b/modules/osdk-csv-bundle-files.adoc deleted file mode 100644 index b13790dc3e5e..000000000000 --- a/modules/osdk-csv-bundle-files.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-csv-bundle-files_{context}"] -= Generated files and resources - -The `make bundle` command creates the following files and directories in your Operator project: - -* A bundle manifests directory named `bundle/manifests` that contains a `ClusterServiceVersion` (CSV) object -* A bundle metadata directory named `bundle/metadata` -* All custom resource definitions (CRDs) in a `config/crd` directory -* A Dockerfile `bundle.Dockerfile` - -The following resources are typically included in a CSV: - -Role:: Defines Operator permissions within a namespace. -ClusterRole:: Defines cluster-wide Operator permissions. -Deployment:: Defines how an Operand of an Operator is run in pods. -CustomResourceDefinition (CRD):: Defines custom resources that your Operator reconciles. -Custom resource examples:: Examples of resources adhering to the spec of a particular CRD. diff --git a/modules/osdk-csv-composition-configuration.adoc b/modules/osdk-csv-composition-configuration.adoc deleted file mode 100644 index 8d8cf66ed201..000000000000 --- a/modules/osdk-csv-composition-configuration.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-configuring-csv-composition_{context}"] -= CSV composition configuration - -Operator authors can configure CSV composition by populating several fields in the `deploy/olm-catalog/csv-config.yaml` file: - -[cols="2a,8a",options="header"] -|=== -|Field |Description - -|`operator-path` (string) -|The Operator resource manifest file path. Default: `deploy/operator.yaml`. - -|`crd-cr-path-list` (string(, string)*) -|A list of CRD and CR manifest file paths. Default: `[deploy/crds/*_{crd,cr}.yaml]`. - -|`rbac-path-list` (string(, string)*) -|A list of RBAC role manifest file paths. Default: `[deploy/role.yaml]`. -|=== diff --git a/modules/osdk-csv-manual-annotations.adoc b/modules/osdk-csv-manual-annotations.adoc deleted file mode 100644 index 3770b27bbf11..000000000000 --- a/modules/osdk-csv-manual-annotations.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-csv-manual-annotations_{context}"] -= Operator metadata annotations - -Operator developers can manually define certain annotations in the metadata of a cluster service version (CSV) to enable features or highlight capabilities in user interfaces (UIs), such as OperatorHub. - -The following table lists Operator metadata annotations that can be manually defined using `metadata.annotations` fields. - -.Annotations -[cols="5a,5a",options="header"] -|=== -|Field |Description - -|`alm-examples` -|Provide custom resource definition (CRD) templates with a minimum set of configuration. Compatible UIs pre-fill this template for users to further customize. - -|`operatorframework.io/initialization-resource` -|Specify a single required custom resource that must be created at the time that the Operator is installed. Must include a template that contains a complete YAML definition. - -|`operatorframework.io/suggested-namespace` -|Set a suggested namespace where the Operator should be deployed. - -|`operators.openshift.io/infrastructure-features` -|Infrastructure features supported by the Operator. Users can view and filter by these features when discovering Operators through OperatorHub in the web console. Valid, case-sensitive values: - -- `disconnected`: Operator supports being mirrored into disconnected catalogs, including all dependencies, and does not require Internet access. All related images required for mirroring are listed by the Operator. -- `cnf`: Operator provides a Cloud-native Network Functions (CNF) Kubernetes plug-in. -- `cni`: Operator provides a Container Network Interface (CNI) Kubernetes plug-in. -- `csi`: Operator provides a Container Storage Interface (CSI) Kubernetes plug-in. -- `fips`: Operator accepts the FIPS mode of the underlying platform and works on nodes that are booted into FIPS mode. -- `proxy-aware`: Operator supports running on a cluster behind a proxy. Operator accepts the standard proxy environment variables `HTTP_PROXY` and `HTTPS_PROXY`, which Operator Lifecycle Manager (OLM) provides to the Operator automatically when the cluster is configured to use a proxy. Required environment variables are passed down to Operands for managed workloads. - -|`operators.openshift.io/valid-subscription` -|Free-form array for listing any specific subscriptions that are required to use the Operator. For example, `'["3Scale Commercial License", "Red Hat Managed Integration"]'`. - -|`operators.operatorframework.io/internal-objects` -|Hides CRDs in the UI that are not meant for user manipulation. - -|=== - -[discrete] -[id="osdk-csv-manual-annotations-examples_{context}"] -== Example use cases - -.Operator supports disconnected and proxy-aware -[source,terminal] ----- -operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]' ----- - -.Operator requires an OpenShift Container Platform license -[source,terminal] ----- -operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]' ----- - -.Operator requires a 3scale license -[source,terminal] ----- -operators.openshift.io/valid-subscription: '["3Scale Commercial License", "Red Hat Managed Integration"]' ----- - -.Operator supports disconnected and proxy-aware, and requires an OpenShift Container Platform license -[source,terminal] ----- -operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]' -operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]' ----- diff --git a/modules/osdk-csv-ver.adoc b/modules/osdk-csv-ver.adoc deleted file mode 100644 index 1d297583e3d6..000000000000 --- a/modules/osdk-csv-ver.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-csv-ver_{context}"] -= Version management - -The `--version` flag for the `generate bundle` subcommand supplies a semantic version for your bundle when creating one for the first time and when upgrading an existing one. - -By setting the `VERSION` variable in your `Makefile`, the `--version` flag is automatically invoked using that value when the `generate bundle` subcommand is run by the `make bundle` command. The CSV version is the same as the Operator version, and a new CSV is generated when upgrading Operator versions. diff --git a/modules/osdk-generating-a-csv.adoc b/modules/osdk-generating-a-csv.adoc deleted file mode 100644 index 46c768618ffb..000000000000 --- a/modules/osdk-generating-a-csv.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-generating-a-csv_{context}"] -= Generating a CSV - -.Prerequisites - -- An Operator project generated using the Operator SDK - -.Procedure - -. In your Operator project, configure your CSV composition by modifying the `deploy/olm-catalog/csv-config.yaml` file, if desired. - -. Generate the CSV: -+ -[source,terminal] ----- -$ operator-sdk generate csv --csv-version <version> ----- - -. In the new CSV generated in the `deploy/olm-catalog/` directory, ensure all required, manually-defined fields are set appropriately. diff --git a/modules/osdk-golang-controller-configs.adoc b/modules/osdk-golang-controller-configs.adoc deleted file mode 100644 index ad3974d94e12..000000000000 --- a/modules/osdk-golang-controller-configs.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-controller-configs_{context}"] -= Controller configurations - -You can initialize a controller by using many other useful configurations. For example: - -* Set the maximum number of concurrent reconciles for the controller by using the `MaxConcurrentReconciles` option, which defaults to `1`: -+ -[source,go] ----- -func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error { - return ctrl.NewControllerManagedBy(mgr). - For(&cachev1.Memcached{}). - Owns(&appsv1.Deployment{}). - WithOptions(controller.Options{ - MaxConcurrentReconciles: 2, - }). - Complete(r) -} ----- - -* Filter watch events using predicates. - -* Choose the type of link:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/handler#hdr-EventHandlers[EventHandler] to change how a watch event translates to reconcile requests for the reconcile loop. For Operator relationships that are more complex than primary and secondary resources, you can use the `EnqueueRequestsFromMapFunc` handler to transform a watch event into an arbitrary set of reconcile requests. - -For more details on these and other configurations, see the upstream link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/builder#example-Builder[Builder] and link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller[Controller] GoDocs. diff --git a/modules/osdk-golang-controller-rbac-markers.adoc b/modules/osdk-golang-controller-rbac-markers.adoc deleted file mode 100644 index 5288edd8aff9..000000000000 --- a/modules/osdk-golang-controller-rbac-markers.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-controller-rbac-markers_{context}"] -= Permissions and RBAC manifests - -The controller requires certain RBAC permissions to interact with the resources it manages. These are specified using RBAC markers, such as the following: - -[source,go] ----- -// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds,verbs=get;list;watch;create;update;patch;delete -// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/status,verbs=get;update;patch -// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/finalizers,verbs=update -// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete -// +kubebuilder:rbac:groups=core,resources=pods,verbs=get;list; - -func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { - ... -} ----- - -The `ClusterRole` object manifest at `config/rbac/role.yaml` is generated from the previous markers by using the `controller-gen` utility whenever the `make manifests` command is run. diff --git a/modules/osdk-golang-controller-reconcile-loop.adoc b/modules/osdk-golang-controller-reconcile-loop.adoc deleted file mode 100644 index 0dfed92cec0d..000000000000 --- a/modules/osdk-golang-controller-reconcile-loop.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-controller-reconcile-loop_{context}"] -= Reconcile loop - -Every controller has a reconciler object with a `Reconcile()` method that implements the reconcile loop. The reconcile loop is passed the `Request` argument, which is a namespace and name key used to find the primary resource object, `Memcached`, from the cache: - -[source,go] ----- -import ( - ctrl "sigs.k8s.io/controller-runtime" - - cachev1 "github.com/example-inc/memcached-operator/api/v1" - ... -) - -func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { - // Lookup the Memcached instance for this reconcile request - memcached := &cachev1.Memcached{} - err := r.Get(ctx, req.NamespacedName, memcached) - ... -} ----- - -Based on the return values, result, and error, the request might be requeued and the reconcile loop might be triggered again: - -[source,go] ----- -// Reconcile successful - don't requeue -return ctrl.Result{}, nil -// Reconcile failed due to error - requeue -return ctrl.Result{}, err -// Requeue for any reason other than an error -return ctrl.Result{Requeue: true}, nil ----- - -You can set the `Result.RequeueAfter` to requeue the request after a grace period as well: - -[source,go] ----- -import "time" - -// Reconcile for any reason other than an error after 5 seconds -return ctrl.Result{RequeueAfter: time.Second*5}, nil ----- - -[NOTE] -==== -You can return `Result` with `RequeueAfter` set to periodically reconcile a CR. -==== - -For more on reconcilers, clients, and interacting with resource events, see the link:https://sdk.operatorframework.io/docs/building-operators/golang/references/client/[Controller Runtime Client API] documentation. diff --git a/modules/osdk-golang-controller-resources.adoc b/modules/osdk-golang-controller-resources.adoc deleted file mode 100644 index 8843455cd9f1..000000000000 --- a/modules/osdk-golang-controller-resources.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-controller-resources_{context}"] -= Resources watched by the controller - -The `SetupWithManager()` function in `controllers/memcached_controller.go` specifies how the controller is built to watch a CR and other resources that are owned and managed by that controller. - -[source,go] ----- -import ( - ... - appsv1 "k8s.io/api/apps/v1" - ... -) - -func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error { - return ctrl.NewControllerManagedBy(mgr). - For(&cachev1.Memcached{}). - Owns(&appsv1.Deployment{}). - Complete(r) -} ----- - -`NewControllerManagedBy()` provides a controller builder that allows various controller configurations. - -`For(&cachev1.Memcached{})` specifies the `Memcached` type as the primary resource to watch. For each Add, Update, or Delete event for a `Memcached` type, the reconcile loop is sent a reconcile `Request` argument, which consists of a namespace and name key, for that `Memcached` object. - -`Owns(&appsv1.Deployment{})` specifies the `Deployment` type as the secondary resource to watch. For each `Deployment` type Add, Update, or Delete event, the event handler maps each event to a reconcile request for the owner of the deployment. In this case, the owner is the `Memcached` object for which the deployment was created. diff --git a/modules/osdk-golang-create-api-controller.adoc b/modules/osdk-golang-create-api-controller.adoc deleted file mode 100644 index ea119d0754aa..000000000000 --- a/modules/osdk-golang-create-api-controller.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-create-api-controller_{context}"] -= Creating an API and controller - -Use the Operator SDK CLI to create a custom resource definition (CRD) API and controller. - -.Procedure - -. Run the following command to create an API with group `cache`, version, `v1`, and kind `Memcached`: -+ -[source,terminal] ----- -$ operator-sdk create api \ - --group=cache \ - --version=v1 \ - --kind=Memcached ----- - -. When prompted, enter `y` for creating both the resource and controller: -+ -[source,terminal] ----- -Create Resource [y/n] -y -Create Controller [y/n] -y ----- -+ -.Example output -[source,terminal] ----- -Writing scaffold for you to edit... -api/v1/memcached_types.go -controllers/memcached_controller.go -... ----- - -This process generates the `Memcached` resource API at `api/v1/memcached_types.go` and the controller at `controllers/memcached_controller.go`. diff --git a/modules/osdk-golang-define-api.adoc b/modules/osdk-golang-define-api.adoc deleted file mode 100644 index cbca2750f78c..000000000000 --- a/modules/osdk-golang-define-api.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-define-api_{context}"] -= Defining the API - -Define the API for the `Memcached` custom resource (CR). - -.Procedure - -. Modify the Go type definitions at `api/v1/memcached_types.go` to have the following `spec` and `status`: -+ -[source,go] ----- -// MemcachedSpec defines the desired state of Memcached -type MemcachedSpec struct { - // +kubebuilder:validation:Minimum=0 - // Size is the size of the memcached deployment - Size int32 `json:"size"` -} - -// MemcachedStatus defines the observed state of Memcached -type MemcachedStatus struct { - // Nodes are the names of the memcached pods - Nodes []string `json:"nodes"` -} ----- - -. Add the `+kubebuilder:subresource:status` marker to add a `status` subresource to the CRD manifest: -+ -[source,go] ----- -// Memcached is the Schema for the memcacheds API -// +kubebuilder:subresource:status <1> -type Memcached struct { - metav1.TypeMeta `json:",inline"` - metav1.ObjectMeta `json:"metadata,omitempty"` - - Spec MemcachedSpec `json:"spec,omitempty"` - Status MemcachedStatus `json:"status,omitempty"` -} ----- -<1> Add this line. -+ -This enables the controller to update the CR status without changing the rest of the CR object. - -. Update the generated code for the resource type: -+ -[source,terminal] ----- -$ make generate ----- -+ -[TIP] -==== -After you modify a `*_types.go` file, you must run the `make generate` command to update the generated code for that resource type. -==== -+ -The above Makefile target invokes the `controller-gen` utility to update the `api/v1/zz_generated.deepcopy.go` file. This ensures your API Go type definitions implement the `runtime.Object` interface that all Kind types must implement. diff --git a/modules/osdk-golang-generate-crd.adoc b/modules/osdk-golang-generate-crd.adoc deleted file mode 100644 index 14a0e6ee28a0..000000000000 --- a/modules/osdk-golang-generate-crd.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-generate-crd_{context}"] -= Generating CRD manifests - -After the API is defined with `spec` and `status` fields and custom resource definition (CRD) validation markers, you can generate CRD manifests. - -.Procedure - -* Run the following command to generate and update CRD manifests: -+ -[source,terminal] ----- -$ make manifests ----- -+ -This Makefile target invokes the `controller-gen` utility to generate the CRD manifests in the `config/crd/bases/cache.example.com_memcacheds.yaml` file. - -[id="osdk-golang-generate-crd-validation_{context}"] -== About OpenAPI validation - -OpenAPIv3 schemas are added to CRD manifests in the `spec.validation` block when the manifests are generated. This validation block allows Kubernetes to validate the properties in a Memcached custom resource (CR) when it is created or updated. - -Markers, or annotations, are available to configure validations for your API. These markers always have a `+kubebuilder:validation` prefix. - -.Additional resources - -* For more details on the usage of markers in API code, see the following Kubebuilder documentation: -** link:https://book.kubebuilder.io/reference/generating-crd.html[CRD generation] -** link:https://book.kubebuilder.io/reference/markers.html[Markers] -** link:https://book.kubebuilder.io/reference/markers/crd-validation.html[List of OpenAPIv3 validation markers] - -* For more details about OpenAPIv3 validation schemas in CRDs, see the link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema[Kubernetes documentation]. diff --git a/modules/osdk-golang-implement-controller.adoc b/modules/osdk-golang-implement-controller.adoc deleted file mode 100644 index be2e8e62a0e5..000000000000 --- a/modules/osdk-golang-implement-controller.adoc +++ /dev/null @@ -1,223 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-implement-controller_{context}"] -= Implementing the controller - -After creating a new API and controller, you can implement the controller logic. - -.Procedure - -* For this example, replace the generated controller file `controllers/memcached_controller.go` with following example implementation: -+ -.Example `memcached_controller.go` -[%collapsible] -==== -[source,golang] ----- -/* -Copyright 2020. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -*/ - -package controllers - -import ( - appsv1 "k8s.io/api/apps/v1" - corev1 "k8s.io/api/core/v1" - "k8s.io/apimachinery/pkg/api/errors" - metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" - "k8s.io/apimachinery/pkg/types" - "reflect" - - "context" - - "github.com/go-logr/logr" - "k8s.io/apimachinery/pkg/runtime" - ctrl "sigs.k8s.io/controller-runtime" - "sigs.k8s.io/controller-runtime/pkg/client" - - cachev1alpha1 "github.com/example/memcached-operator/api/v1alpha1" -) - -// MemcachedReconciler reconciles a Memcached object -type MemcachedReconciler struct { - client.Client - Log logr.Logger - Scheme *runtime.Scheme -} - -// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds,verbs=get;list;watch;create;update;patch;delete -// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/status,verbs=get;update;patch -// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/finalizers,verbs=update -// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete -// +kubebuilder:rbac:groups=core,resources=pods,verbs=get;list; - -// Reconcile is part of the main kubernetes reconciliation loop which aims to -// move the current state of the cluster closer to the desired state. -// TODO(user): Modify the Reconcile function to compare the state specified by -// the Memcached object against the actual cluster state, and then -// perform operations to make the cluster state reflect the state specified by -// the user. -// -// For more details, check Reconcile and its Result here: -// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.7.0/pkg/reconcile -func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { - log := r.Log.WithValues("memcached", req.NamespacedName) - - // Fetch the Memcached instance - memcached := &cachev1alpha1.Memcached{} - err := r.Get(ctx, req.NamespacedName, memcached) - if err != nil { - if errors.IsNotFound(err) { - // Request object not found, could have been deleted after reconcile request. - // Owned objects are automatically garbage collected. For additional cleanup logic use finalizers. - // Return and don't requeue - log.Info("Memcached resource not found. Ignoring since object must be deleted") - return ctrl.Result{}, nil - } - // Error reading the object - requeue the request. - log.Error(err, "Failed to get Memcached") - return ctrl.Result{}, err - } - - // Check if the deployment already exists, if not create a new one - found := &appsv1.Deployment{} - err = r.Get(ctx, types.NamespacedName{Name: memcached.Name, Namespace: memcached.Namespace}, found) - if err != nil && errors.IsNotFound(err) { - // Define a new deployment - dep := r.deploymentForMemcached(memcached) - log.Info("Creating a new Deployment", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name) - err = r.Create(ctx, dep) - if err != nil { - log.Error(err, "Failed to create new Deployment", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name) - return ctrl.Result{}, err - } - // Deployment created successfully - return and requeue - return ctrl.Result{Requeue: true}, nil - } else if err != nil { - log.Error(err, "Failed to get Deployment") - return ctrl.Result{}, err - } - - // Ensure the deployment size is the same as the spec - size := memcached.Spec.Size - if *found.Spec.Replicas != size { - found.Spec.Replicas = &size - err = r.Update(ctx, found) - if err != nil { - log.Error(err, "Failed to update Deployment", "Deployment.Namespace", found.Namespace, "Deployment.Name", found.Name) - return ctrl.Result{}, err - } - // Spec updated - return and requeue - return ctrl.Result{Requeue: true}, nil - } - - // Update the Memcached status with the pod names - // List the pods for this memcached's deployment - podList := &corev1.PodList{} - listOpts := []client.ListOption{ - client.InNamespace(memcached.Namespace), - client.MatchingLabels(labelsForMemcached(memcached.Name)), - } - if err = r.List(ctx, podList, listOpts...); err != nil { - log.Error(err, "Failed to list pods", "Memcached.Namespace", memcached.Namespace, "Memcached.Name", memcached.Name) - return ctrl.Result{}, err - } - podNames := getPodNames(podList.Items) - - // Update status.Nodes if needed - if !reflect.DeepEqual(podNames, memcached.Status.Nodes) { - memcached.Status.Nodes = podNames - err := r.Status().Update(ctx, memcached) - if err != nil { - log.Error(err, "Failed to update Memcached status") - return ctrl.Result{}, err - } - } - - return ctrl.Result{}, nil -} - -// deploymentForMemcached returns a memcached Deployment object -func (r *MemcachedReconciler) deploymentForMemcached(m *cachev1alpha1.Memcached) *appsv1.Deployment { - ls := labelsForMemcached(m.Name) - replicas := m.Spec.Size - - dep := &appsv1.Deployment{ - ObjectMeta: metav1.ObjectMeta{ - Name: m.Name, - Namespace: m.Namespace, - }, - Spec: appsv1.DeploymentSpec{ - Replicas: &replicas, - Selector: &metav1.LabelSelector{ - MatchLabels: ls, - }, - Template: corev1.PodTemplateSpec{ - ObjectMeta: metav1.ObjectMeta{ - Labels: ls, - }, - Spec: corev1.PodSpec{ - Containers: []corev1.Container{{ - Image: "memcached:1.4.36-alpine", - Name: "memcached", - Command: []string{"memcached", "-m=64", "-o", "modern", "-v"}, - Ports: []corev1.ContainerPort{{ - ContainerPort: 11211, - Name: "memcached", - }}, - }}, - }, - }, - }, - } - // Set Memcached instance as the owner and controller - ctrl.SetControllerReference(m, dep, r.Scheme) - return dep -} - -// labelsForMemcached returns the labels for selecting the resources -// belonging to the given memcached CR name. -func labelsForMemcached(name string) map[string]string { - return map[string]string{"app": "memcached", "memcached_cr": name} -} - -// getPodNames returns the pod names of the array of pods passed in -func getPodNames(pods []corev1.Pod) []string { - var podNames []string - for _, pod := range pods { - podNames = append(podNames, pod.Name) - } - return podNames -} - -// SetupWithManager sets up the controller with the Manager. -func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error { - return ctrl.NewControllerManagedBy(mgr). - For(&cachev1alpha1.Memcached{}). - Owns(&appsv1.Deployment{}). - Complete(r) -} ----- -==== -+ -The example controller runs the following reconciliation logic for each `Memcached` custom resource (CR): -+ --- -* Create a Memcached deployment if it does not exist. -* Ensure that the deployment size is the same as specified by the `Memcached` CR spec. -* Update the `Memcached` CR status with the names of the `memcached` pods. --- diff --git a/modules/osdk-golang-manager.adoc b/modules/osdk-golang-manager.adoc deleted file mode 100644 index 1c2a727ca4a3..000000000000 --- a/modules/osdk-golang-manager.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-manager_{context}"] -= About the Manager - -The main program for the Operator is the `main.go` file, which initializes and runs the link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Manager[Manager]. The Manager automatically registers the Scheme for all custom resource (CR) API definitions and sets up and runs controllers and webhooks. - -The Manager can restrict the namespace that all controllers watch for resources: - -[source,go] ----- -mgr, err := ctrl.NewManager(cfg, manager.Options{Namespace: namespace}) ----- - -By default, the Manager watches the namespace where the Operator runs. To watch all namespaces, you can leave the `namespace` option empty: - -[source,go] ----- -mgr, err := ctrl.NewManager(cfg, manager.Options{Namespace: ""}) ----- - -You can also use the link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/cache#MultiNamespacedCacheBuilder[`MultiNamespacedCacheBuilder`] function to watch a specific set of namespaces: - -[source,go] ----- -var namespaces []string <1> -mgr, err := ctrl.NewManager(cfg, manager.Options{ <2> - NewCache: cache.MultiNamespacedCacheBuilder(namespaces), -}) ----- -<1> List of namespaces. -<2> Creates a `Cmd` struct to provide shared dependencies and start components. diff --git a/modules/osdk-golang-multi-group-apis.adoc b/modules/osdk-golang-multi-group-apis.adoc deleted file mode 100644 index 2c8fd722c575..000000000000 --- a/modules/osdk-golang-multi-group-apis.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-golang-multi-group-apis_{context}"] -= About multi-group APIs - -Before you create an API and controller, consider whether your Operator requires multiple API groups. This tutorial covers the default case of a single group API, but to change the layout of your project to support multi-group APIs, you can run the following command: - -[source,terminal] ----- -$ operator-sdk edit --multigroup=true ----- - -This command updates the `PROJECT` file, which should look like the following example: - -[source,yaml] ----- -domain: example.com -layout: go.kubebuilder.io/v3 -multigroup: true -... ----- - -For multi-group projects, the API Go type files are created in the `apis/<group>/<version>/` directory, and the controllers are created in the `controllers/<group>/` directory. The Dockerfile is then updated accordingly. - -.Additional resource - -* For more details on migrating to a multi-group project, see the link:https://book.kubebuilder.io/migration/multi-group.html[Kubebuilder documentation]. diff --git a/modules/osdk-golang-project-layout.adoc b/modules/osdk-golang-project-layout.adoc deleted file mode 100644 index 6f3e25dbcd09..000000000000 --- a/modules/osdk-golang-project-layout.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-project-layout.adoc - -[id="osdk-golang-project-layout_{context}"] -= Go-based project layout - -Go-based Operator projects, the default type, generated using the `operator-sdk init` command contain the following files and directories: - -[options="header",cols="1,4"] -|=== - -|File or directory |Purpose - -|`main.go` -|Main program of the Operator. This instantiates a new manager that registers all custom resource definitions (CRDs) in the `apis/` directory and starts all controllers in the `controllers/` directory. - -|`apis/` -|Directory tree that defines the APIs of the CRDs. You must edit the `apis/<version>/<kind>_types.go` files to define the API for each resource type and import these packages in your controllers to watch for these resource types. - -|`controllers/` -|Controller implementations. Edit the `controller/<kind>_controller.go` files to define the reconcile logic of the controller for handling a resource type of the specified kind. - -|`config/` -|Kubernetes manifests used to deploy your controller on a cluster, including CRDs, RBAC, and certificates. - -|`Makefile` -|Targets used to build and deploy your controller. - -|`Dockerfile` -|Instructions used by a container engine to build your Operator. - -|`manifests/` -|Kubernetes manifests for registering CRDs, setting up RBAC, and deploying the Operator as a deployment. - -|=== diff --git a/modules/osdk-helm-charts.adoc b/modules/osdk-helm-charts.adoc deleted file mode 100644 index ae752a6d16ad..000000000000 --- a/modules/osdk-helm-charts.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/helm/osdk-helm-support.adoc - -[id="osdk-helm-charts_{context}"] -= Helm charts - -One of the Operator SDK options for generating an Operator project includes leveraging an existing Helm chart to deploy Kubernetes resources as a unified application, without having to write any Go code. Such Helm-based Operators are designed to excel at stateless applications that require very little logic when rolled out, because changes should be applied to the Kubernetes objects that are generated as part of the chart. This may sound limiting, but can be sufficient for a surprising amount of use-cases as shown by the proliferation of Helm charts built by the Kubernetes community. - -The main function of an Operator is to read from a custom object that represents your application instance and have its desired state match what is running. In the case of a Helm-based Operator, the `spec` field of the object is a list of configuration options that are typically described in the Helm `values.yaml` file. Instead of setting these values with flags using the Helm CLI (for example, `helm install -f values.yaml`), you can express them within a custom resource (CR), which, as a native Kubernetes object, enables the benefits of RBAC applied to it and an audit trail. - -For an example of a simple CR called `Tomcat`: - -[source,yaml] ----- -apiVersion: apache.org/v1alpha1 -kind: Tomcat -metadata: - name: example-app -spec: - replicaCount: 2 ----- - -The `replicaCount` value, `2` in this case, is propagated into the template of the chart where the following is used: - -[source,yaml] ----- -{{ .Values.replicaCount }} ----- - -After an Operator is built and deployed, you can deploy a new instance of an app by creating a new instance of a CR, or list the different instances running in all environments using the `oc` command: - -[source,terminal] ----- -$ oc get Tomcats --all-namespaces ----- - -There is no requirement use the Helm CLI or install Tiller; Helm-based Operators import code from the Helm project. All you have to do is have an instance of the Operator running and register the CR with a custom resource definition (CRD). Because it obeys RBAC, you can more easily prevent production changes. diff --git a/modules/osdk-helm-existing-chart.adoc b/modules/osdk-helm-existing-chart.adoc deleted file mode 100644 index 8e59d06a5fc3..000000000000 --- a/modules/osdk-helm-existing-chart.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -[id="osdk-helm-existing-chart_{context}"] -= Existing Helm charts - -Instead of creating your project with a boilerplate Helm chart, you can alternatively use an existing chart, either from your local file system or a remote chart repository, by using the following flags: - -* `--helm-chart` -* `--helm-chart-repo` -* `--helm-chart-version` - -If the `--helm-chart` flag is specified, the `--group`, `--version`, and `--kind` flags become optional. If left unset, the following default values are used: - -[options="header"] -|=== -|Flag |Value - -|`--domain` -|`my.domain` - -|`--group` -|`charts` - -|`--version` -|`v1` - -|`--kind` -|Deduced from the specified chart -|=== - -If the `--helm-chart` flag specifies a local chart archive, for example `example-chart-1.2.0.tgz`, or directory, the chart is validated and unpacked or copied into the project. Otherwise, the Operator SDK attempts to fetch the chart from a remote repository. - -If a custom repository URL is not specified by the `--helm-chart-repo` flag, the following chart reference formats are supported: - -[cols="1,4",options="header"] -|=== -|Format |Description - -|`<repo_name>/<chart_name>` -|Fetch the Helm chart named `<chart_name>` from the helm chart repository named `<repo_name>`, as specified in the `$HELM_HOME/repositories/repositories.yaml` file. Use the `helm repo add` command to configure this file. - -|`<url>` -|Fetch the Helm chart archive at the specified URL. -|=== - -If a custom repository URL is specified by `--helm-chart-repo`, the following chart reference format is supported: - -[cols="1,4",options="header"] -|=== -|Format |Description - -|`<chart_name>` -|Fetch the Helm chart named `<chart_name>` in the Helm chart repository specified by the `--helm-chart-repo` URL value. -|=== - -If the `--helm-chart-version` flag is unset, the Operator SDK fetches the latest available version of the Helm chart. Otherwise, it fetches the specified version. The optional `--helm-chart-version` flag is not used when the chart specified with the `--helm-chart` flag refers to a specific version, for example when it is a local path or a URL. - -For more details and examples, run: - -[source,terminal] ----- -$ operator-sdk init --plugins helm --help ----- diff --git a/modules/osdk-helm-logic.adoc b/modules/osdk-helm-logic.adoc deleted file mode 100644 index e50f41b3fb08..000000000000 --- a/modules/osdk-helm-logic.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -[id="osdk-helm-logic_{context}"] -= Understanding the Operator logic - -For this example, the `nginx-operator` project executes the following reconciliation logic for each `Nginx` custom resource (CR): - -* Create an Nginx deployment if it does not exist. -* Create an Nginx service if it does not exist. -* Create an Nginx ingress if it is enabled and does not exist. -* Ensure that the deployment, service, and optional ingress match the desired configuration as specified by the `Nginx` CR, for example the replica count, image, and service type. - -By default, the `nginx-operator` project watches `Nginx` resource events as shown in the `watches.yaml` file and executes Helm releases using the specified chart: - -[source,yaml] ----- -# Use the 'create api' subcommand to add watches to this file. -- group: demo - version: v1 - kind: Nginx - chart: helm-charts/nginx -# +kubebuilder:scaffold:watch ----- diff --git a/modules/osdk-helm-modify-cr.adoc b/modules/osdk-helm-modify-cr.adoc deleted file mode 100644 index 45d0322e7aee..000000000000 --- a/modules/osdk-helm-modify-cr.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -[id="osdk-helm-modify-cr_{context}"] -= Modifying the custom resource spec - -Helm uses a concept called link:https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing[values] to provide customizations to the defaults of a Helm chart, which are defined in the `values.yaml` file. - -You can override these defaults by setting the desired values in the custom resource (CR) spec. You can use the number of replicas as an example. - -.Procedure - -. The `helm-charts/nginx/values.yaml` file has a value called `replicaCount` set to `1` by default. To have two Nginx instances in your deployment, your CR spec must contain `replicaCount: 2`. -+ -Edit the `config/samples/demo_v1_nginx.yaml` file to set `replicaCount: 2`: -+ -[source,yaml] ----- -apiVersion: demo.example.com/v1 -kind: Nginx -metadata: - name: nginx-sample -... -spec: -... - replicaCount: 2 ----- - -. Similarly, the default service port is set to `80`. To use `8080`, edit the `config/samples/demo_v1_nginx.yaml` file to set `spec.port: 8080`,which adds the service port override: -+ -[source,yaml] ----- -apiVersion: demo.example.com/v1 -kind: Nginx -metadata: - name: nginx-sample -spec: - replicaCount: 2 - service: - port: 8080 ----- - -The Helm Operator applies the entire spec as if it was the contents of a values file, just like the `helm install -f ./overrides.yaml` command. diff --git a/modules/osdk-helm-project-layout.adoc b/modules/osdk-helm-project-layout.adoc deleted file mode 100644 index 79fd4ee44df7..000000000000 --- a/modules/osdk-helm-project-layout.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/helm/osdk-helm-project-layout.adoc - -[id="osdk-helm-project-layout_{context}"] -= Helm-based project layout - -Helm-based Operator projects generated using the `operator-sdk init --plugins helm` command contain the following directories and files: - -[options="header",cols="1,4"] -|=== - -|File/folders |Purpose - -|`config` -|link:https://kustomize.io/[Kustomize] manifests for deploying the Operator on a Kubernetes cluster. - -|`helm-charts/` -|Helm chart initialized with the `operator-sdk create api` command. - -|`Dockerfile` -|Used to build the Operator image with the `make docker-build` command. - -|`watches.yaml` -|Group/version/kind (GVK) and Helm chart location. - -|`Makefile` -|Targets used to manage the project. - -|`PROJECT` -|YAML file containing metadata information for the Operator. - -|=== diff --git a/modules/osdk-helm-sample-chart.adoc b/modules/osdk-helm-sample-chart.adoc deleted file mode 100644 index b8b576e06580..000000000000 --- a/modules/osdk-helm-sample-chart.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -[id="osdk-helm-sample-chart_{context}"] -= Sample Helm chart - -When a Helm Operator project is created, the Operator SDK creates a sample Helm chart that contains a set of templates for a simple Nginx release. - -For this example, templates are available for deployment, service, and ingress resources, along with a `NOTES.txt` template, which Helm chart developers use to convey helpful information about a release. - -If you are not already familiar with Helm charts, review the link:https://docs.helm.sh/developing_charts/[Helm developer documentation]. diff --git a/modules/osdk-hiding-internal-objects.adoc b/modules/osdk-hiding-internal-objects.adoc deleted file mode 100644 index 085c087e2249..000000000000 --- a/modules/osdk-hiding-internal-objects.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-hiding-internal-objects_{context}"] -= Hiding internal objects - -It is common practice for Operators to use custom resource definitions (CRDs) internally to accomplish a task. These objects are not meant for users to manipulate and can be confusing to users of the Operator. For example, a database Operator might have a `Replication` CRD that is created whenever a user creates a Database object with `replication: true`. - -As an Operator author, you can hide any CRDs in the user interface that are not meant for user manipulation by adding the `operators.operatorframework.io/internal-objects` annotation to the cluster service version (CSV) of your Operator. - -.Procedure - -. Before marking one of your CRDs as internal, ensure that any debugging information or configuration that might be required to manage the application is reflected on the status or `spec` block of your CR, if applicable to your Operator. - -. Add the `operators.operatorframework.io/internal-objects` annotation to the CSV of your Operator to specify any internal objects to hide in the user interface: -+ -.Internal object annotation -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: my-operator-v1.2.3 - annotations: - operators.operatorframework.io/internal-objects: '["my.internal.crd1.io","my.internal.crd2.io"]' <1> -... ----- -<1> Set any internal CRDs as an array of strings. diff --git a/modules/osdk-how-csv-gen-works.adoc b/modules/osdk-how-csv-gen-works.adoc deleted file mode 100644 index 5871c86d1ef0..000000000000 --- a/modules/osdk-how-csv-gen-works.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-how-csv-gen-works_{context}"] -= How CSV generation works - -Operator bundle manifests, which include cluster service versions (CSVs), describe how to display, create, and manage an application with Operator Lifecycle Manager (OLM). The CSV generator in the Operator SDK, called by the `generate bundle` subcommand, is the first step towards publishing your Operator to a catalog and deploying it with OLM. The subcommand requires certain input manifests to construct a CSV manifest; all inputs are read when the command is invoked, along with a CSV base, to idempotently generate or regenerate a CSV. - -Typically, the `generate kustomize manifests` subcommand would be run first to generate the input link:https://kustomize.io/[Kustomize] bases that are consumed by the `generate bundle` subcommand. However, the Operator SDK provides the `make bundle` command, which automates several tasks, including running the following subcommands in order: - -. `generate kustomize manifests` -. `generate bundle` -. `bundle validate` diff --git a/modules/osdk-init-resource.adoc b/modules/osdk-init-resource.adoc deleted file mode 100644 index 5d171fcf2155..000000000000 --- a/modules/osdk-init-resource.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-init-resource_{context}"] -= Initializing required custom resources - -An Operator might require the user to instantiate a custom resource before the Operator can be fully functional. However, it can be challenging for a user to determine what is required or how to define the resource. - -As an Operator developer, you can specify a single required custom resource that must be created at the time that the Operator is installed by adding the `operatorframework.io/initialization-resource` annotation to the cluster service version (CSV). The annotation must include a template that contains a complete YAML definition that is required to initialize the resource during installation. - -If this annotation is defined, after installing the Operator from the {product-title} web console, the user is prompted to create the resource using the template provided in the CSV. - -.Procedure - -* Add the `operatorframework.io/initialization-resource` annotation to the CSV of your Operator to specify a required custom resource. For example, the following annotation requires the creation of a `StorageCluster` resource and provides a full YAML definition: -+ -.Initialization resource annotation -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: ClusterServiceVersion -metadata: - name: my-operator-v1.2.3 - annotations: - operatorframework.io/initialization-resource: |- - { - "apiVersion": "ocs.openshift.io/v1", - "kind": "StorageCluster", - "metadata": { - "name": "example-storagecluster" - }, - "spec": { - "manageNodes": false, - "monPVCTemplate": { - "spec": { - "accessModes": [ - "ReadWriteOnce" - ], - "resources": { - "requests": { - "storage": "10Gi" - } - }, - "storageClassName": "gp2" - } - }, - "storageDeviceSets": [ - { - "count": 3, - "dataPVCTemplate": { - "spec": { - "accessModes": [ - "ReadWriteOnce" - ], - "resources": { - "requests": { - "storage": "1Ti" - } - }, - "storageClassName": "gp2", - "volumeMode": "Block" - } - }, - "name": "example-deviceset", - "placement": {}, - "portable": true, - "resources": {} - } - ] - } - } -... ----- diff --git a/modules/osdk-installing-cli-linux-macos.adoc b/modules/osdk-installing-cli-linux-macos.adoc deleted file mode 100644 index 1712155a40bb..000000000000 --- a/modules/osdk-installing-cli-linux-macos.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// * cli_reference/osdk/cli-osdk-install.adoc -// * operators/operator_sdk/osdk-installing-cli.adoc - -:ocp_ver: latest -:osdk_ver: v1.3.0 - -[id="osdk-installing-cli-linux-macos_{context}"] -= Installing the Operator SDK CLI - -You can install the OpenShift SDK CLI tool on Linux. - -.Prerequisites - -- link:https://golang.org/dl/[Go] v1.13+ -ifdef::openshift-origin[] -- link:https://docs.docker.com/install/[`docker`] v17.03+, link:https://github.com/containers/libpod/blob/master/install.md[`podman`] v1.2.0+, or link:https://github.com/containers/buildah/blob/master/install.md[`buildah`] v1.7+ -endif::[] -ifndef::openshift-origin[] -- `docker` v17.03+, `podman` v1.9.3+, or `buildah` v1.7+ -endif::[] - -.Procedure - -. Navigate to the link:https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/operator-sdk/{ocp_ver}/[OpenShift mirror site]. - -. From the `{ocp_ver}` directory, download the latest version of the tarball for Linux. - -. Unpack the archive: -+ -[source,terminal,subs="attributes+"] ----- -$ tar xvf operator-sdk-{osdk_ver}-ocp-linux-x86_64.tar.gz ----- - -. Make the file executable: -+ -[source,terminal] ----- -$ chmod +x operator-sdk ----- - -. Move the extracted `operator-sdk` binary to a directory that is on your `PATH`. -+ -[TIP] -==== -To check your `PATH`: - -[source,terminal] ----- -$ echo $PATH ----- -==== -+ -[source,terminal] ----- -$ sudo mv ./operator-sdk /usr/local/bin/operator-sdk ----- - -.Verification - -* After you install the Operator SDK CLI, verify that it is available: -+ -[source,terminal] ----- -$ operator-sdk version ----- -+ -.Example output -[source,terminal,subs="attributes+"] ----- -operator-sdk version: "{osdk_ver}-ocp", ... ----- - -:!ocp_ver: -:!osdk_ver: diff --git a/modules/osdk-leader-election-types.adoc b/modules/osdk-leader-election-types.adoc deleted file mode 100644 index ef01bbe28098..000000000000 --- a/modules/osdk-leader-election-types.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/oosdk-leader-election.adoc - -[id="osdk-leader-for-life-election_{context}"] -= Using Leader-for-life election - -With the Leader-for-life election implementation, a call to `leader.Become()` blocks the Operator as it retries until it can become the leader by creating the config map named `memcached-operator-lock`: - -[source,go] ----- -import ( - ... - "github.com/operator-framework/operator-sdk/pkg/leader" -) - -func main() { - ... - err = leader.Become(context.TODO(), "memcached-operator-lock") - if err != nil { - log.Error(err, "Failed to retry for leader lock") - os.Exit(1) - } - ... -} ----- - -If the Operator is not running inside a cluster, `leader.Become()` simply returns without error to skip the leader election since it cannot detect the name of the Operator. - -[id="osdk-leader-with-lease-election_{context}"] -= Using Leader-with-lease election - -The Leader-with-lease implementation can be enabled using the link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options[Manager Options] for leader election: - -[source,go] ----- -import ( - ... - "sigs.k8s.io/controller-runtime/pkg/manager" -) - -func main() { - ... - opts := manager.Options{ - ... - LeaderElection: true, - LeaderElectionID: "memcached-operator-lock" - } - mgr, err := manager.New(cfg, opts) - ... -} ----- - -When the Operator is not running in a cluster, the Manager returns an error when starting because it cannot detect the namespace of the Operator to create the config map for leader election. You can override this namespace by setting the `LeaderElectionNamespace` option for the Manager. diff --git a/modules/osdk-manager-file.adoc b/modules/osdk-manager-file.adoc deleted file mode 100644 index 47e21fd96d85..000000000000 --- a/modules/osdk-manager-file.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc - -[id="osdk-manager-file_{context}"] -= Manager file - -The main program for the Operator is the manager file at `cmd/manager/main.go`. The manager automatically registers the scheme for all custom resources (CRs) defined under `pkg/apis/` and runs all controllers under `pkg/controller/`. - -The manager can restrict the namespace that all controllers watch for resources: - -[source,go] ----- -mgr, err := manager.New(cfg, manager.Options{Namespace: namespace}) ----- - -By default, the controller watches the namespace that the Operator runs in. To watch all namespaces, you can leave the namespace option empty: - -[source,go] ----- -mgr, err := manager.New(cfg, manager.Options{Namespace: ""}) ----- - -//// -TODO: Doc on manager options(Sync period, leader election, registering 3rd party types) -//// diff --git a/modules/osdk-manually-defined-csv-fields.adoc b/modules/osdk-manually-defined-csv-fields.adoc deleted file mode 100644 index 09ba700f1fac..000000000000 --- a/modules/osdk-manually-defined-csv-fields.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-manually-defined-csv-fields_{context}"] -= Manually-defined CSV fields - -Many CSV fields cannot be populated using generated, generic manifests that are not specific to Operator SDK. These fields are mostly human-written metadata about the Operator and various custom resource definitions (CRDs). - -Operator authors must directly modify their cluster service version (CSV) YAML file, adding personalized data to the following required fields. The Operator SDK gives a warning during CSV generation when a lack of data in any of the required fields is detected. - -The following tables detail which manually-defined CSV fields are required and which are optional. - -.Required -[cols="2a,8a",options="header"] -|=== -|Field |Description - -|`metadata.name` -|A unique name for this CSV. Operator version should be included in the name to ensure uniqueness, for example `app-operator.v0.1.1`. - -|`metadata.capabilities` -|The capability level according to the Operator maturity model. Options include `Basic Install`, `Seamless Upgrades`, `Full Lifecycle`, `Deep Insights`, and `Auto Pilot`. - -|`spec.displayName` -|A public name to identify the Operator. - -|`spec.description` -|A short description of the functionality of the Operator. - -|`spec.keywords` -|Keywords describing the Operator. - -|`spec.maintainers` -|Human or organizational entities maintaining the Operator, with a `name` and `email`. - -|`spec.provider` -|The provider of the Operator (usually an organization), with a `name`. - -|`spec.labels` -|Key-value pairs to be used by Operator internals. - -|`spec.version` -|Semantic version of the Operator, for example `0.1.1`. - -|`spec.customresourcedefinitions` -|Any CRDs the Operator uses. This field is populated automatically by the Operator SDK if any CRD YAML files are present in `deploy/`. However, several fields not in the CRD manifest spec require user input: - -- `description`: description of the CRD. -- `resources`: any Kubernetes resources leveraged by the CRD, for example `Pod` and `StatefulSet` objects. -- `specDescriptors`: UI hints for inputs and outputs of the Operator. -|=== - - -.Optional -[cols="2a,8a",options="header"] -|=== -|Field |Description - -|`spec.replaces` -|The name of the CSV being replaced by this CSV. - -|`spec.links` -|URLs (for example, websites and documentation) pertaining to the Operator or application being managed, each with a `name` and `url`. - -|`spec.selector` -|Selectors by which the Operator can pair resources in a cluster. - -|`spec.icon` -|A base64-encoded icon unique to the Operator, set in a `base64data` field with a `mediatype`. - -|`spec.maturity` -|The level of maturity the software has achieved at this version. Options include `planning`, `pre-alpha`, `alpha`, `beta`, `stable`, `mature`, `inactive`, and `deprecated`. - -|`metadata.annotations` -|=== - -Further details on what data each field above should hold are found in the link:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/building-your-csv.md[CSV spec]. - -[NOTE] -==== -Several YAML fields currently requiring user intervention can potentially be parsed from Operator code. -==== diff --git a/modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc b/modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc deleted file mode 100644 index 813b0003c2ad..000000000000 --- a/modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-monitoring-prometheus.adoc - -[id="osdk-monitoring-prometheus-metrics-helper-modifying-port_{context}"] -= Modifying the metrics port - -Operator authors can modify the port that metrics are exposed on. - -.Prerequisites - -* Go-based Operator generated using the Operator SDK -* Kubernetes-based cluster with the Prometheus Operator deployed - -.Procedure - -* In the `cmd/manager/main.go` file of the generated Operator, change the value of `metricsPort` in the following line: -+ -[source,go] ----- -var metricsPort int32 = 8383 ----- diff --git a/modules/osdk-monitoring-prometheus-metrics-helper.adoc b/modules/osdk-monitoring-prometheus-metrics-helper.adoc deleted file mode 100644 index e85a452fbe35..000000000000 --- a/modules/osdk-monitoring-prometheus-metrics-helper.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-monitoring-prometheus.adoc - -[id="osdk-monitoring-prometheus-metrics-helper_{context}"] -= Metrics helper - -In Go-based Operators generated using the Operator SDK, the following function exposes general metrics about the running program: - -[source,go] ----- -func ExposeMetricsPort(ctx context.Context, port int32) (*v1.Service, error) ----- - -These metrics are inherited from the `controller-runtime` library API. By default, the metrics are served on `0.0.0.0:8383/metrics`. - -A `Service` object is created with the metrics port exposed, which can be then accessed by Prometheus. The `Service` object is garbage collected when the leader pod's `root` owner is deleted. - -The following example is present in the `cmd/manager/main.go` file in all Operators generated using the Operator SDK: - -[source,go] ----- -import( - "github.com/operator-framework/operator-sdk/pkg/metrics" - "machine.openshift.io/controller-runtime/pkg/manager" -) - -var ( - // Change the below variables to serve metrics on a different host or port. - metricsHost = "0.0.0.0" <1> - metricsPort int32 = 8383 <2> -) -... -func main() { - ... - // Pass metrics address to controller-runtime manager - mgr, err := manager.New(cfg, manager.Options{ - Namespace: namespace, - MetricsBindAddress: fmt.Sprintf("%s:%d", metricsHost, metricsPort), - }) - - ... - // Create Service object to expose the metrics port. - _, err = metrics.ExposeMetricsPort(ctx, metricsPort) - if err != nil { - // handle error - log.Info(err.Error()) - } - ... -} ----- -<1> The host that the metrics are exposed on. -<2> The port that the metrics are exposed on. diff --git a/modules/osdk-monitoring-prometheus-operator-support.adoc b/modules/osdk-monitoring-prometheus-operator-support.adoc deleted file mode 100644 index 195c61b4218a..000000000000 --- a/modules/osdk-monitoring-prometheus-operator-support.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-monitoring-prometheus.adoc - -[id="osdk-monitoring-prometheus-operator-support_{context}"] -= Prometheus Operator support - -link:https://prometheus.io/[Prometheus] is an open-source systems monitoring and alerting toolkit. The Prometheus Operator creates, configures, and manages Prometheus clusters running on Kubernetes-based clusters, such as {product-title}. - -Helper functions exist in the Operator SDK by default to automatically set up metrics in any generated Go-based Operator for use on clusters where the Prometheus Operator is deployed. diff --git a/modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc b/modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc deleted file mode 100644 index 61649e5b3332..000000000000 --- a/modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-monitoring-prometheus.adoc - -[id="osdk-monitoring-prometheus-servicemonitor-creating_{context}"] -= Creating service monitors - -Operator authors can add service target discovery of created monitoring services using the `metrics.CreateServiceMonitor()` helper function, which accepts the newly created service. - -.Prerequisites - -* Go-based Operator generated using the Operator SDK -* Kubernetes-based cluster with the Prometheus Operator deployed - -.Procedure - -* Add the `metrics.CreateServiceMonitor()` helper function to your Operator code: -+ -[source,go] ----- -import( - "k8s.io/api/core/v1" - "github.com/operator-framework/operator-sdk/pkg/metrics" - "machine.openshift.io/controller-runtime/pkg/client/config" -) -func main() { - - ... - // Populate below with the Service(s) for which you want to create ServiceMonitors. - services := []*v1.Service{} - // Create one ServiceMonitor per application per namespace. - // Change the below value to name of the Namespace you want the ServiceMonitor to be created in. - ns := "default" - // restConfig is used for talking to the Kubernetes apiserver - restConfig := config.GetConfig() - - // Pass the Service(s) to the helper function, which in turn returns the array of ServiceMonitor objects. - serviceMonitors, err := metrics.CreateServiceMonitors(restConfig, ns, services) - if err != nil { - // Handle errors here. - } - ... -} ----- diff --git a/modules/osdk-monitoring-prometheus-servicemonitor.adoc b/modules/osdk-monitoring-prometheus-servicemonitor.adoc deleted file mode 100644 index 70606580b43e..000000000000 --- a/modules/osdk-monitoring-prometheus-servicemonitor.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-monitoring-prometheus.adoc - -[id="osdk-monitoring-prometheus-servicemonitor_{context}"] -= Service monitors - -A `ServiceMonitor` is a custom resource provided by the Prometheus Operator that discovers the `Endpoints` in `Service` objects and configures Prometheus to monitor those pods. - -In Go-based Operators generated using the Operator SDK, the `GenerateServiceMonitor()` helper function can take a `Service` object and generate a `ServiceMonitor` object based on it. - -.Additional resources - -* See the link:https://github.com/coreos/prometheus-operator/blob/7a25bf6b6bb2347dacb235659b73bc210117acc7/Documentation/design.md#servicemonitor[Prometheus Operator documentation] for more information about the `ServiceMonitor` custom resource definition (CRD). diff --git a/modules/osdk-operatorconditions.adoc b/modules/osdk-operatorconditions.adoc deleted file mode 100644 index ee168ce8534b..000000000000 --- a/modules/osdk-operatorconditions.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-operatorconditions_{context}"] -= Enabling Operator conditions - -Operator Lifecycle Manager (OLM) provides Operators with a channel to communicate complex states that influence OLM behavior while managing the Operator. By default, OLM creates an `OperatorCondition` custom resource definition (CRD) when it installs an Operator. Based on the conditions set in the `OperatorCondition` custom resource (CR), the behavior of OLM changes accordingly. - -To support Operator conditions, an Operator must be able to read the `OperatorCondition` CR created by OLM and have the ability to: - -* Get the specific condition. -* Set the status of a specific condition. - -This can be accomplished by using the link:https://github.com/operator-framework/operator-lib/tree/v0.3.0[`operator-lib`] library. An Operator author can provide a link:https://github.com/kubernetes-sigs/controller-runtime/tree/master/pkg/client[`controller-runtime` client] in their Operator for the library to access the `OperatorCondition` CR owned by the Operator in the cluster. - -The library provides a generic `Conditions` interface, which has the following methods to `Get` and `Set` a `conditionType` in the `OperatorCondition` CR: - -`Get`:: To get the specific condition, the library uses the `client.Get` function from `controller-runtime`, which requires an `ObjectKey` of type `types.NamespacedName` present in `conditionAccessor`. - -`Set`:: To update the status of the specific condition, the library uses the `client.Update` function from `controller-runtime`. An error occurs if the `conditionType` is not present in the CRD. - -The Operator is allowed to modify only the `status` subresource of the CR. Operators can either delete or update the `status.conditions` array to include the condition. For more details on the format and description of the fields present in the conditions, see the upstream link:https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Condition[Condition GoDocs]. - -[NOTE] -==== -Operator SDK v1.3.0 supports `operator-lib` v0.3.0. -==== - -.Prerequisites - -* An Operator project generated using the Operator SDK. - -.Procedure - -To enable Operator conditions in your Operator project: - -. In the `go.mod` file of your Operator project, add `operator-framework/operator-lib` as a required library: -+ -[source,go] ----- -module github.com/example-inc/memcached-operator - -go 1.15 - -require ( - k8s.io/apimachinery v0.19.2 - k8s.io/client-go v0.19.2 - sigs.k8s.io/controller-runtime v0.7.0 - operator-framework/operator-lib v0.3.0 -) ----- - -. Write your own constructor in your Operator logic that: -+ --- -* Accepts a `controller-runtime` client. -* Accepts a `conditionType`. -* Returns a `Condition` interface to update or add conditions. --- -+ -Because OLM currently supports the `Upgradeable` condition, you can create an interface that has methods to access the `Upgradeable` condition. For example: -+ -[source,go] ----- -import ( - ... - apiv1 "github.com/operator-framework/api/pkg/operators/v1" -) - -func NewUpgradeable(cl client.Client) (Condition, error) { - return NewCondition(cl, "apiv1.OperatorUpgradeable") -} - -cond, err := NewUpgradeable(cl); ----- -+ -In this example, the `NewUpgradeable` constructor is further used to create a variable `cond` of type `Condition`. The `cond` variable would in turn have `Get` and `Set` methods, which can be used for handling the OLM `Upgradeable` condition. diff --git a/modules/osdk-owned-crds.adoc b/modules/osdk-owned-crds.adoc deleted file mode 100644 index e1d7a6706433..000000000000 --- a/modules/osdk-owned-crds.adoc +++ /dev/null @@ -1,117 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-crds-owned_{context}"] -= Owned CRDs - -The custom resource definitions (CRDs) owned by your Operator are the most important part of your CSV. This establishes the link between your Operator and the required RBAC rules, dependency management, and other Kubernetes concepts. - -It is common for your Operator to use multiple CRDs to link together concepts, such as top-level database configuration in one object and a representation of replica sets in another. Each one should be listed out in the CSV file. - -.Owned CRD fields -[cols="2a,5a,2",options="header"] -|=== -|Field |Description |Required/optional - -|`Name` -|The full name of your CRD. -|Required - -|`Version` -|The version of that object API. -|Required - -|`Kind` -|The machine readable name of your CRD. -|Required - -|`DisplayName` -|A human readable version of your CRD name, for example `MongoDB Standalone`. -|Required - -|`Description` -|A short description of how this CRD is used by the Operator or a description of the functionality provided by the CRD. -|Required - -|`Group` -|The API group that this CRD belongs to, for example `database.example.com`. -|Optional - -|`Resources` -a|Your CRDs own one or more types of Kubernetes objects. These are listed in the `resources` section to inform your users of the objects they might need to troubleshoot or how to connect to the application, such as the service or ingress rule that exposes a database. - -It is recommended to only list out the objects that are important to a human, not an exhaustive list of everything you orchestrate. For example, do not list config maps that store internal state that are not meant to be modified by a user. -|Optional - -|`SpecDescriptors`, `StatusDescriptors`, and `ActionDescriptors` -a|These descriptors are a way to hint UIs with certain inputs or outputs of your Operator that are most important to an end user. If your CRD contains the name of a secret or config map that the user must provide, you can specify that here. These items are linked and highlighted in compatible UIs. - -There are three types of descriptors: - -* `SpecDescriptors`: A reference to fields in the `spec` block of an object. -* `StatusDescriptors`: A reference to fields in the `status` block of an object. -* `ActionDescriptors`: A reference to actions that can be performed on an object. - -All descriptors accept the following fields: - -* `DisplayName`: A human readable name for the `Spec`, `Status`, or `Action`. -* `Description`: A short description of the `Spec`, `Status`, or `Action` and how it is used by the Operator. -* `Path`: A dot-delimited path of the field on the object that this descriptor describes. -* `X-Descriptors`: Used to determine which "capabilities" this descriptor has and which UI component to use. See the *openshift/console* project for a canonical link:https://github.com/openshift/console/tree/release-4.3/frontend/packages/operator-lifecycle-manager/src/components/descriptors/types.ts[list of React UI X-Descriptors] for {product-title}. - -Also see the *openshift/console* project for more information on link:https://github.com/openshift/console/tree/release-4.3/frontend/packages/operator-lifecycle-manager/src/components/descriptors[Descriptors] in general. -|Optional - -|=== - -The following example depicts a `MongoDB Standalone` CRD that requires some user input in the form of a secret and config map, and orchestrates services, stateful sets, pods and config maps: - -[id="osdk-crds-owned-example_{context}"] -.Example owned CRD -[source,yaml] ----- - - displayName: MongoDB Standalone - group: mongodb.com - kind: MongoDbStandalone - name: mongodbstandalones.mongodb.com - resources: - - kind: Service - name: '' - version: v1 - - kind: StatefulSet - name: '' - version: v1beta2 - - kind: Pod - name: '' - version: v1 - - kind: ConfigMap - name: '' - version: v1 - specDescriptors: - - description: Credentials for Ops Manager or Cloud Manager. - displayName: Credentials - path: credentials - x-descriptors: - - 'urn:alm:descriptor:com.tectonic.ui:selector:core:v1:Secret' - - description: Project this deployment belongs to. - displayName: Project - path: project - x-descriptors: - - 'urn:alm:descriptor:com.tectonic.ui:selector:core:v1:ConfigMap' - - description: MongoDB version to be installed. - displayName: Version - path: version - x-descriptors: - - 'urn:alm:descriptor:com.tectonic.ui:label' - statusDescriptors: - - description: The status of each of the pods for the MongoDB cluster. - displayName: Pod Status - path: pods - x-descriptors: - - 'urn:alm:descriptor:com.tectonic.ui:podStatuses' - version: v1 - description: >- - MongoDB Deployment consisting of only one host. No replication of - data. ----- diff --git a/modules/osdk-prepare-supported-images.adoc b/modules/osdk-prepare-supported-images.adoc deleted file mode 100644 index bb4c3b6bdade..000000000000 --- a/modules/osdk-prepare-supported-images.adoc +++ /dev/null @@ -1,97 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -:osdk_ver: v1.3.0 -ifeval::["{context}" == "osdk-golang-tutorial"] -:golang: -:type: Go -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:ansible: -:type: Ansible -:type_lc: ansible -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:helm: -:type: Helm -:type_lc: helm -endif::[] - -[id="osdk-prepare-supported-images_{context}"] -= Preparing your Operator to use supported images - -Before running your {type}-based Operator on {product-title}, update your project to use supported images. - -.Procedure - -ifdef::golang[] -. Update the project root-level Dockerfile to use supported images. Change the default runner image reference from: -+ -[source,terminal] ----- -FROM gcr.io/distroless/static:nonroot ----- -+ -to: -+ -[source,terminal] ----- -FROM registry.access.redhat.com/ubi8/ubi-minimal:latest ----- - -. Depending on the Go project version, your Dockerfile might contain a `USER 65532:65532` or `USER nonroot:nonroot` directive. In either case, remove the line, as it is not required by the supported runner image. -endif::[] - -ifdef::ansible,helm[] -. Update the project root-level Dockerfile to use supported images. Change the default builder image reference from: -+ -[source,terminal,subs="attributes+"] ----- -FROM quay.io/operator-framework/{type_lc}-operator:{osdk_ver} ----- -+ -to: -+ -[source,terminal,subs="attributes+"] ----- -FROM registry.redhat.io/openshift4/ose-{type_lc}-operator:v{product-version} ----- -+ -[IMPORTANT] -==== -Use the builder image version that matches your Operator SDK version. Failure to do so can result in problems due to project layout, or _scaffolding_, differences, particularly when mixing newer upstream versions of the Operator SDK with downstream {product-title} builder images. -==== -endif::[] - -. In the `config/default/manager_auth_proxy_patch.yaml` file, change the `image` value from: -+ -[source,terminal] ----- -gcr.io/kubebuilder/kube-rbac-proxy:<tag> ----- -+ -to use the supported image: -+ -[source,terminal,subs="attributes+"] ----- -registry.redhat.io/openshift4/ose-kube-rbac-proxy:v{product-version} ----- - -:!osdk_ver: -ifeval::["{context}" == "osdk-golang-tutorial"] -:!golang: -:!type: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:!ansible: -:!type: -:!type_lc: -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:!helm: -:!type: -:!type_lc: -endif::[] diff --git a/modules/osdk-project-file.adoc b/modules/osdk-project-file.adoc deleted file mode 100644 index de36f1361a7c..000000000000 --- a/modules/osdk-project-file.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -ifeval::["{context}" == "osdk-golang-tutorial"] -:golang: -:type: Go -:app: memcached -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:ansible: -:type: Ansible -:app: memcached -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:helm: -:type: Helm -:app: nginx -endif::[] - -[id="osdk-project-file_{context}"] -= PROJECT file - -Among the files generated by the `operator-sdk init` command is a Kubebuilder `PROJECT` file. Subsequent `operator-sdk` commands, as well as `help` output, that are run from the project root read this file and are aware that the project type is {type}. For example: - -[source,yaml] -ifdef::golang[] ----- -domain: example.com -layout: go.kubebuilder.io/v3 -projectName: memcached-operator -repo: github.com/example-inc/memcached-operator -version: 3-alpha -plugins: - manifests.sdk.operatorframework.io/v2: {} - scorecard.sdk.operatorframework.io/v2: {} ----- -endif::[] -ifdef::ansible[] ----- -domain: example.com -layout: ansible.sdk.operatorframework.io/v1 -projectName: memcached-operator -version: 3-alpha ----- -endif::[] -ifdef::helm[] ----- -domain: example.com -layout: helm.sdk.operatorframework.io/v1 -projectName: helm-operator -resources: -- group: demo - kind: Nginx - version: v1 -version: 3-alpha ----- -endif::[] - -ifeval::["{context}" == "osdk-golang-tutorial"] -:!golang: -:!type: -:!app: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:!ansible: -:!type: -:!app: -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:!helm: -:!type: -:!app: -endif::[] diff --git a/modules/osdk-quickstart.adoc b/modules/osdk-quickstart.adoc deleted file mode 100644 index 2b867449bdf4..000000000000 --- a/modules/osdk-quickstart.adoc +++ /dev/null @@ -1,225 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-quickstart.adoc -// * operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc -// * operators/operator_sdk/helm/osdk-helm-quickstart.adoc - -ifeval::["{context}" == "osdk-golang-quickstart"] -:golang: -:type: Go -:app-proper: Memcached -:app: memcached -:group: cache -endif::[] -ifeval::["{context}" == "osdk-ansible-quickstart"] -:ansible: -:type: Ansible -:app-proper: Memcached -:app: memcached -:group: cache -endif::[] -ifeval::["{context}" == "osdk-helm-quickstart"] -:helm: -:type: Helm -:app-proper: Nginx -:app: nginx -:group: demo -endif::[] - -[id="osdk-quickstart_{context}"] -= Creating and deploying {type}-based Operators - -You can build and deploy a simple {type}-based Operator for {app-proper} by using the Operator SDK. - -.Procedure - -. *Create a project.* - -.. Create your project: -+ -[source,terminal,subs="attributes+"] ----- -$ mkdir {app}-operator ----- - -.. Change into the project directory: -+ -[source,terminal,subs="attributes+"] ----- -$ cd {app}-operator ----- - -.. Run the `operator-sdk init` command -ifdef::ansible[] -with the `ansible` plug-in -endif::[] -ifdef::helm[] -with the `helm` plug-in -endif::[] -to initialize the project: -+ -[source,terminal,subs="attributes+"] -ifdef::golang[] ----- -$ operator-sdk init \ - --domain=example.com \ - --repo=github.com/example-inc/{app}-operator ----- -+ -The command uses the Go plug-in by default. -endif::[] -ifdef::ansible[] ----- -$ operator-sdk init \ - --plugins=ansible \ - --domain=example.com ----- -endif::[] -ifdef::helm[] ----- -$ operator-sdk init \ - --plugins=helm ----- -endif::[] - -ifdef::golang[] -.. To enable your Go-based Operator to run on {product-title}, edit the `config/manager/manager.yaml` file and replace the following line: -+ -[source,yaml] ----- -runAsUser: 65532 ----- -+ -with: -+ -[source,yaml] ----- -runAsNonRoot: true ----- -+ -[NOTE] -==== -This step is a temporary workaround required for Go-based Operators only. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1914406#c1[BZ#1914406]. -==== -endif::[] - -. *Create an API.* -+ -Create a simple {app-proper} API: -+ -[source,terminal,subs="attributes+"] -ifdef::golang[] ----- -$ operator-sdk create api \ - --resource=true \ - --controller=true \ - --group {group} \ - --version v1 \ - --kind {app-proper} ----- -endif::[] -ifdef::ansible[] ----- -$ operator-sdk create api \ - --group {group} \ - --version v1 \ - --kind {app-proper} \ - --generate-role <1> ----- -<1> Generates an Ansible role for the API. -endif::[] -ifdef::helm[] ----- -$ operator-sdk create api \ - --group {group} \ - --version v1 \ - --kind {app-proper} ----- -+ -This API uses the built-in Helm chart boilerplate from the `helm create` command. -endif::[] - -. *Build and push the Operator image.* -+ -Use the default `Makefile` targets to build and push your Operator. Set `IMG` with a pull spec for your image that uses a registry you can push to: -+ -[source,terminal] ----- -$ make docker-build docker-push IMG=<registry>/<user>/<image_name>:<tag> ----- - -. *Run the Operator.* - -.. Install the CRD: -+ -[source,terminal] ----- -$ make install ----- - -.. Deploy the project to the cluster. Set `IMG` to the image that you pushed: -+ -[source,terminal] ----- -$ make deploy IMG=<registry>/<user>/<image_name>:<tag> ----- - -. *Create a sample custom resource (CR).* - -.. Create a sample CR: -+ -[source,terminal,subs="attributes+"] ----- -$ oc apply -f config/samples/{group}_v1_{app}.yaml \ - -n {app}-operator-system ----- - -.. Watch for the CR to reconcile the Operator: -+ -[source,terminal,subs="attributes+"] ----- -$ oc logs deployment.apps/{app}-operator-controller-manager \ - -c manager \ - -n {app}-operator-system ----- -ifdef::ansible[] -+ -.Example output -[source,terminal] ----- -... -I0205 17:48:45.881666 7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator -{"level":"info","ts":1612547325.8819902,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"} -{"level":"info","ts":1612547325.98242,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"} -{"level":"info","ts":1612547325.9824686,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4} -{"level":"info","ts":1612547348.8311093,"logger":"runner","msg":"Ansible-runner exited successfully","job":"4037200794235010051","name":"memcached-sample","namespace":"memcached-operator-system"} ----- -endif::[] - -. *Clean up.* -+ -Run the following command to clean up the resources that have been created as part of this procedure: -+ -[source,terminal] ----- -$ make undeploy ----- - -ifeval::["{context}" == "osdk-golang-quickstart"] -:!golang: -:!type: -:!app-proper: -:!app: -endif::[] -ifeval::["{context}" == "osdk-ansible-quickstart"] -:!ansible: -:!type: -:!app-proper: -:!app: -endif::[] -ifeval::["{context}" == "osdk-helm-quickstart"] -:!helm: -:!type: -:!app-proper: -:!app: -endif::[] diff --git a/modules/osdk-required-crds.adoc b/modules/osdk-required-crds.adoc deleted file mode 100644 index 8de26ca9e2d4..000000000000 --- a/modules/osdk-required-crds.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-crds-required_{context}"] -= Required CRDs - -Relying on other required CRDs is completely optional and only exists to reduce the scope of individual Operators and provide a way to compose multiple Operators together to solve an end-to-end use case. - -An example of this is an Operator that might set up an application and install an etcd cluster (from an etcd Operator) to use for distributed locking and a Postgres database (from a Postgres Operator) for data storage. - -Operator Lifecycle Manager (OLM) checks against the available CRDs and Operators in the cluster to fulfill these requirements. If suitable versions are found, the Operators are started within the desired namespace and a service account created for each Operator to create, watch, and modify the Kubernetes resources required. - -.Required CRD fields -[cols="2a,5a,2",options="header"] -|=== -|Field |Description |Required/optional - -|`Name` -|The full name of the CRD you require. -|Required - -|`Version` -|The version of that object API. -|Required - -|`Kind` -|The Kubernetes object kind. -|Required - -|`DisplayName` -|A human readable version of the CRD. -|Required - -|`Description` -|A summary of how the component fits in your larger architecture. -|Required -|=== - -.Example required CRD -[source,yaml] ----- - required: - - name: etcdclusters.etcd.database.coreos.com - version: v1beta2 - kind: EtcdCluster - displayName: etcd Cluster - description: Represents a cluster of etcd nodes. ----- diff --git a/modules/osdk-run-deployment.adoc b/modules/osdk-run-deployment.adoc deleted file mode 100644 index 5988b298825c..000000000000 --- a/modules/osdk-run-deployment.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -ifeval::["{context}" == "osdk-golang-tutorial"] -:golang: -endif::[] - -[id="osdk-run-deployment_{context}"] -ifeval::["{context}" != "osdk-ansible-inside-operator"] -= Running as a deployment on the cluster -endif::[] -ifeval::["{context}" == "osdk-ansible-inside-operator"] -= Testing an Ansible-based Operator on the cluster - -After you have tested your custom Ansible logic locally inside of an Operator, you can test the Operator inside of a pod on an {product-title} cluster, which is prefered for production use. -endif::[] - -You can run your Operator project as a deployment on your cluster. - -ifdef::golang[] -.Prerequisites - -* Prepared your Go-based Operator to run on {product-title} by updating the project to use supported images -endif::[] - -.Procedure - -. Run the following `make` commands to build and push the Operator image. Modify the `IMG` argument in the following steps to reference a repository that you have access to. You can obtain an account for storing containers at repository sites such as Quay.io. - -.. Build the image: -+ -[source,terminal] ----- -$ make docker-build IMG=<registry>/<user>/<image_name>:<tag> ----- - -.. Push the image to a repository: -+ -[source,terminal] ----- -$ make docker-push IMG=<registry>/<user>/<image_name>:<tag> ----- -+ -[NOTE] -==== -The name and tag of the image, for example `IMG=<registry>/<user>/<image_name>:<tag>`, in both the commands can also be set in your Makefile. Modify the `IMG ?= controller:latest` value to set your default image name. -==== - -. Run the following command to deploy the Operator: -+ -[source,terminal] ----- -$ make deploy IMG=<registry>/<user>/<image_name>:<tag> ----- -+ -By default, this command creates a namespace with the name of your Operator project in the form `<project_name>-system` and is used for the deployment. This command also installs the RBAC manifests from `config/rbac`. - -. Verify that the Operator is running: -+ -[source,terminal] ----- -$ oc get deployment -n <project_name>-system ----- -+ -.Example output -[source,terminal] ----- -NAME READY UP-TO-DATE AVAILABLE AGE -<project_name>-controller-manager 1/1 1 1 8m ----- - -ifeval::["{context}" == "osdk-golang-tutorial"] -:!golang: -endif::[] diff --git a/modules/osdk-run-locally.adoc b/modules/osdk-run-locally.adoc deleted file mode 100644 index 1ef9724587ad..000000000000 --- a/modules/osdk-run-locally.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -ifeval::["{context}" == "osdk-golang-tutorial"] -:golang: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:ansible: -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:helm: -endif::[] - -[id="osdk-run-locally_{context}"] -= Running locally outside the cluster - -You can run your Operator project as a Go program outside of the cluster. This is useful for development purposes to speed up deployment and testing. - -.Procedure - -* Run the following command to install the custom resource definitions (CRDs) in the cluster configured in your `~/.kube/config` file and run the Operator locally: -+ -[source,terminal] ----- -$ make install run ----- -+ -.Example output -[source,terminal] -ifdef::golang[] ----- -... -2021-01-10T21:09:29.016-0700 INFO controller-runtime.metrics metrics server is starting to listen {"addr": ":8080"} -2021-01-10T21:09:29.017-0700 INFO setup starting manager -2021-01-10T21:09:29.017-0700 INFO controller-runtime.manager starting metrics server {"path": "/metrics"} -2021-01-10T21:09:29.018-0700 INFO controller-runtime.manager.controller.memcached Starting EventSource {"reconciler group": "cache.example.com", "reconciler kind": "Memcached", "source": "kind source: /, Kind="} -2021-01-10T21:09:29.218-0700 INFO controller-runtime.manager.controller.memcached Starting Controller {"reconciler group": "cache.example.com", "reconciler kind": "Memcached"} -2021-01-10T21:09:29.218-0700 INFO controller-runtime.manager.controller.memcached Starting workers {"reconciler group": "cache.example.com", "reconciler kind": "Memcached", "worker count": 1} ----- -endif::[] -ifdef::ansible[] ----- -... -{"level":"info","ts":1612589622.7888272,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"} -{"level":"info","ts":1612589622.7897573,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"} -{"level":"info","ts":1612589622.789971,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"} -{"level":"info","ts":1612589622.7899997,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"} -{"level":"info","ts":1612589622.8904517,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"} -{"level":"info","ts":1612589622.8905244,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8} ----- -endif::[] -ifdef::helm[] ----- -... -{"level":"info","ts":1612652419.9289865,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":":8080"} -{"level":"info","ts":1612652419.9296563,"logger":"helm.controller","msg":"Watching resource","apiVersion":"demo.example.com/v1","kind":"Nginx","namespace":"","reconcilePeriod":"1m0s"} -{"level":"info","ts":1612652419.929983,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"} -{"level":"info","ts":1612652419.930015,"logger":"controller-runtime.manager.controller.nginx-controller","msg":"Starting EventSource","source":"kind source: demo.example.com/v1, Kind=Nginx"} -{"level":"info","ts":1612652420.2307851,"logger":"controller-runtime.manager.controller.nginx-controller","msg":"Starting Controller"} -{"level":"info","ts":1612652420.2309358,"logger":"controller-runtime.manager.controller.nginx-controller","msg":"Starting workers","worker count":8} ----- -endif::[] - -ifeval::["{context}" == "osdk-golang-tutorial"] -:!golang: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:!ansible: -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:!helm: -endif::[] diff --git a/modules/osdk-run-operator.adoc b/modules/osdk-run-operator.adoc deleted file mode 100644 index 699da565eeba..000000000000 --- a/modules/osdk-run-operator.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/golang/osdk-golang-tutorial.adoc -// * operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc -// * operators/operator_sdk/helm/osdk-helm-tutorial.adoc - -ifeval::["{context}" == "osdk-golang-tutorial"] -:golang: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:ansible: -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:helm: -endif::[] - -[id="osdk-run-operator_{context}"] -= Running the Operator - -There are three ways you can use the Operator SDK CLI to build and run your Operator: - -* Run locally outside the cluster as a Go program. -* Run as a deployment on the cluster. -* Bundle your Operator and use Operator Lifecycle Manager (OLM) to deploy on the cluster. - -ifdef::golang[] -[NOTE] -==== -Before running your Go-based Operator as either a deployment on {product-title} or as a bundle that uses OLM, ensure that your project has been updated to use supported images. -==== -endif::[] - -ifeval::["{context}" == "osdk-golang-tutorial"] -:!golang: -endif::[] -ifeval::["{context}" == "osdk-ansible-tutorial"] -:!ansible: -endif::[] -ifeval::["{context}" == "osdk-helm-tutorial"] -:!helm: -endif::[] diff --git a/modules/osdk-scorecard-about.adoc b/modules/osdk-scorecard-about.adoc deleted file mode 100644 index ed5550d88a5f..000000000000 --- a/modules/osdk-scorecard-about.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-scorecard.adoc - -[id="osdk-about-scorecard_{context}"] -= About the scorecard tool - -While the Operator SDK `bundle validate` subcommand can validate local bundle directories and remote bundle images for content and structure, you can use the `scorecard` command to run tests on your Operator based on a configuration file and test images. These tests are implemented within test images that are configured and constructed to be executed by the scorecard. - -The scorecard assumes it is run with access to a configured Kubernetes cluster, such as {product-title}. The scorecard runs each test within a pod, from which pod logs are aggregated and test results are sent to the console. The scorecard has built-in basic and Operator Lifecycle Manager (OLM) tests and also provides a means to execute custom test definitions. - -.Scorecard workflow -. Create all resources required by any related custom resources (CRs) and the Operator -. Create a proxy container in the deployment of the Operator to record calls to the API server and run tests -. Examine parameters in the CRs - -The scorecard tests make no assumptions as to the state of the Operator being tested. Creating Operators and CRs for an Operators are beyond the scope of the scorecard itself. Scorecard tests can, however, create whatever resources they require if the tests are designed for resource creation. - -.`scorecard` command syntax -[source,terminal] ----- -$ operator-sdk scorecard <bundle_dir_or_image> [flags] ----- - -The scorecard requires a positional argument for either the on-disk path to -your Operator bundle or the name of a bundle image. - -For further information about the flags, run: - -[source,terminal] ----- -$ operator-sdk scorecard -h ----- diff --git a/modules/osdk-scorecard-config.adoc b/modules/osdk-scorecard-config.adoc deleted file mode 100644 index bbe279c0d42f..000000000000 --- a/modules/osdk-scorecard-config.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-scorecard.adoc - -:osdk_ver: v1.3.0 - -[id="osdk-scorecard-config_{context}"] -= Scorecard configuration - -The scorecard tool uses a configuration that allows you to configure internal plug-ins, as well as several global configuration options. Tests are driven by a configuration file named `config.yaml`, which is generated by the `make bundle` command, located in your `bundle/` directory: - -[source,terminal] ----- -./bundle -... -└── tests - └── scorecard - └── config.yaml ----- - -.Example scorecard configuration file -[source,yaml,subs="attributes+"] ----- -kind: Configuration -apiversion: scorecard.operatorframework.io/v1alpha3 -metadata: - name: config -stages: -- parallel: true - tests: - - image: quay.io/operator-framework/scorecard-test:{osdk_ver} - entrypoint: - - scorecard-test - - basic-check-spec - labels: - suite: basic - test: basic-check-spec-test - - image: quay.io/operator-framework/scorecard-test:{osdk_ver} - entrypoint: - - scorecard-test - - olm-bundle-validation - labels: - suite: olm - test: olm-bundle-validation-test ----- - -The configuration file defines each test that scorecard can execute. The -following fields of the scorecard configuration file define the test as follows: - -[cols="3,7",options="header"] -|=== -|Configuration field |Description - -|`image` -|Test container image name that implements a test - -|`entrypoint` -|Command and arguments that are invoked in the test image to execute a test - -|`labels` -|Scorecard-defined or custom labels that select which tests to run -|=== - -:!osdk_ver: diff --git a/modules/osdk-scorecard-custom-tests.adoc b/modules/osdk-scorecard-custom-tests.adoc deleted file mode 100644 index f28cb0a9765a..000000000000 --- a/modules/osdk-scorecard-custom-tests.adoc +++ /dev/null @@ -1,155 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-scorecard.adoc - -[id="osdk-scorecard-custom-tests_{context}"] -= Custom scorecard tests - -The scorecard tool can run custom tests that follow these mandated conventions: - -* Tests are implemented within a container image -* Tests accept an entrypoint which include a command and arguments -* Tests produce `v1alpha3` scorecard output in JSON format with no extraneous logging in the test output -* Tests can obtain the bundle contents at a shared mount point of `/bundle` -* Tests can access the Kubernetes API using an in-cluster client connection - -Writing custom tests in other programming languages is possible if the test -image follows the above guidelines. - -The following example shows of a custom test image written in Go: - -.Example custom scorecard test -[%collapsible] -==== -[source,go] ----- -// Copyright 2020 The Operator-SDK Authors -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package main - -import ( - "encoding/json" - "fmt" - "log" - "os" - - scapiv1alpha3 "github.com/operator-framework/api/pkg/apis/scorecard/v1alpha3" - apimanifests "github.com/operator-framework/api/pkg/manifests" -) - -// This is the custom scorecard test example binary -// As with the Redhat scorecard test image, the bundle that is under -// test is expected to be mounted so that tests can inspect the -// bundle contents as part of their test implementations. -// The actual test is to be run is named and that name is passed -// as an argument to this binary. This argument mechanism allows -// this binary to run various tests all from within a single -// test image. - -const PodBundleRoot = "/bundle" - -func main() { - entrypoint := os.Args[1:] - if len(entrypoint) == 0 { - log.Fatal("Test name argument is required") - } - - // Read the pod's untar'd bundle from a well-known path. - cfg, err := apimanifests.GetBundleFromDir(PodBundleRoot) - if err != nil { - log.Fatal(err.Error()) - } - - var result scapiv1alpha3.TestStatus - - // Names of the custom tests which would be passed in the - // `operator-sdk` command. - switch entrypoint[0] { - case CustomTest1Name: - result = CustomTest1(cfg) - case CustomTest2Name: - result = CustomTest2(cfg) - default: - result = printValidTests() - } - - // Convert scapiv1alpha3.TestResult to json. - prettyJSON, err := json.MarshalIndent(result, "", " ") - if err != nil { - log.Fatal("Failed to generate json", err) - } - fmt.Printf("%s\n", string(prettyJSON)) - -} - -// printValidTests will print out full list of test names to give a hint to the end user on what the valid tests are. -func printValidTests() scapiv1alpha3.TestStatus { - result := scapiv1alpha3.TestResult{} - result.State = scapiv1alpha3.FailState - result.Errors = make([]string, 0) - result.Suggestions = make([]string, 0) - - str := fmt.Sprintf("Valid tests for this image include: %s %s", - CustomTest1Name, - CustomTest2Name) - result.Errors = append(result.Errors, str) - return scapiv1alpha3.TestStatus{ - Results: []scapiv1alpha3.TestResult{result}, - } -} - -const ( - CustomTest1Name = "customtest1" - CustomTest2Name = "customtest2" -) - -// Define any operator specific custom tests here. -// CustomTest1 and CustomTest2 are example test functions. Relevant operator specific -// test logic is to be implemented in similarly. - -func CustomTest1(bundle *apimanifests.Bundle) scapiv1alpha3.TestStatus { - r := scapiv1alpha3.TestResult{} - r.Name = CustomTest1Name - r.State = scapiv1alpha3.PassState - r.Errors = make([]string, 0) - r.Suggestions = make([]string, 0) - almExamples := bundle.CSV.GetAnnotations()["alm-examples"] - if almExamples == "" { - fmt.Println("no alm-examples in the bundle CSV") - } - - return wrapResult(r) -} - -func CustomTest2(bundle *apimanifests.Bundle) scapiv1alpha3.TestStatus { - r := scapiv1alpha3.TestResult{} - r.Name = CustomTest2Name - r.State = scapiv1alpha3.PassState - r.Errors = make([]string, 0) - r.Suggestions = make([]string, 0) - almExamples := bundle.CSV.GetAnnotations()["alm-examples"] - if almExamples == "" { - fmt.Println("no alm-examples in the bundle CSV") - } - return wrapResult(r) -} - -func wrapResult(r scapiv1alpha3.TestResult) scapiv1alpha3.TestStatus { - return scapiv1alpha3.TestStatus{ - Results: []scapiv1alpha3.TestResult{r}, - } -} ----- -==== diff --git a/modules/osdk-scorecard-output.adoc b/modules/osdk-scorecard-output.adoc deleted file mode 100644 index 2ed4a7c1b5cd..000000000000 --- a/modules/osdk-scorecard-output.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-scorecard.adoc - -:osdk_ver: v1.3.0 - -[id="osdk-scorecard-output_{context}"] -= Scorecard output - -The `--output` flag for the `scorecard` command specifies the scorecard results output format: either `text` or `json`. - -.Example JSON output snippet -[%collapsible] -==== -[source,json,subs="attributes+"] ----- -{ - "apiVersion": "scorecard.operatorframework.io/v1alpha3", - "kind": "TestList", - "items": [ - { - "kind": "Test", - "apiVersion": "scorecard.operatorframework.io/v1alpha3", - "spec": { - "image": "quay.io/operator-framework/scorecard-test:{osdk_ver}", - "entrypoint": [ - "scorecard-test", - "olm-bundle-validation" - ], - "labels": { - "suite": "olm", - "test": "olm-bundle-validation-test" - } - }, - "status": { - "results": [ - { - "name": "olm-bundle-validation", - "log": "time=\"2020-06-10T19:02:49Z\" level=debug msg=\"Found manifests directory\" name=bundle-test\ntime=\"2020-06-10T19:02:49Z\" level=debug msg=\"Found metadata directory\" name=bundle-test\ntime=\"2020-06-10T19:02:49Z\" level=debug msg=\"Getting mediaType info from manifests directory\" name=bundle-test\ntime=\"2020-06-10T19:02:49Z\" level=info msg=\"Found annotations file\" name=bundle-test\ntime=\"2020-06-10T19:02:49Z\" level=info msg=\"Could not find optional dependencies file\" name=bundle-test\n", - "state": "pass" - } - ] - } - } - ] -} ----- -==== - -.Example text output snippet -[%collapsible] -==== -[source,text,subs="attributes+"] ----- --------------------------------------------------------------------------------- -Image: quay.io/operator-framework/scorecard-test:{osdk_ver} -Entrypoint: [scorecard-test olm-bundle-validation] -Labels: - "suite":"olm" - "test":"olm-bundle-validation-test" -Results: - Name: olm-bundle-validation - State: pass - Log: - time="2020-07-15T03:19:02Z" level=debug msg="Found manifests directory" name=bundle-test - time="2020-07-15T03:19:02Z" level=debug msg="Found metadata directory" name=bundle-test - time="2020-07-15T03:19:02Z" level=debug msg="Getting mediaType info from manifests directory" name=bundle-test - time="2020-07-15T03:19:02Z" level=info msg="Found annotations file" name=bundle-test - time="2020-07-15T03:19:02Z" level=info msg="Could not find optional dependencies file" name=bundle-test ----- -==== - -[NOTE] -==== -The output format spec matches the link:https://pkg.go.dev/github.com/operator-framework/api/pkg/apis/scorecard/v1alpha3#Test[`Test`] type layout. -==== - -:!osdk_ver: diff --git a/modules/osdk-scorecard-parallel.adoc b/modules/osdk-scorecard-parallel.adoc deleted file mode 100644 index bc22f6ffce1b..000000000000 --- a/modules/osdk-scorecard-parallel.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-scorecard.adoc - -[id="osdk-scorecard-parallel_{context}"] -= Enabling parallel testing - -As an Operator author, you can define separate stages for your tests using the scorecard configuration file. Stages run sequentially in the order they are defined in the configuration file. A stage contains a list of tests and a configurable `parallel` setting. - -By default, or when a stage explicitly sets `parallel` to `false`, tests in a stage are run sequentially in the order they are defined in the configuration file. Running tests one at a time is helpful to guarantee that no two tests interact and conflict with each other. - -However, if tests are designed to be fully isolated, they can be parallelized. - -.Procedure - -* To run a set of isolated tests in parallel, include them in the same stage and set `parallel` to `true`: -+ -[source,terminal] ----- -apiVersion: scorecard.operatorframework.io/v1alpha3 -kind: Configuration -metadata: - name: config -stages: -- parallel: true <1> - tests: - - entrypoint: - - scorecard-test - - basic-check-spec - image: quay.io/operator-framework/scorecard-test:v1.3.0 - labels: - suite: basic - test: basic-check-spec-test - - entrypoint: - - scorecard-test - - olm-bundle-validation - image: quay.io/operator-framework/scorecard-test:v1.3.0 - labels: - suite: olm - test: olm-bundle-validation-test ----- -<1> Enables parallel testing -+ -All tests in a parallel stage are executed simultaneously, and scorecard waits for all of them to finish before proceding to the next stage. This can make your tests run much faster. diff --git a/modules/osdk-scorecard-run.adoc b/modules/osdk-scorecard-run.adoc deleted file mode 100644 index 3b78eaf54c26..000000000000 --- a/modules/osdk-scorecard-run.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-scorecard.adoc - -[id="osdk-scorecard-run_{context}"] -= Running the scorecard tool - -A default set of Kustomize files are generated by the Operator SDK after running the `init` command. The default `bundle/tests/scorecard/config.yaml` file that is generated can be immediately used to run the scorecard tool against your Operator, or you can modify this file to your test specifications. - -.Prerequisites - -* Operator project generated by using the Operator SDK - -.Procedure - -. Generate or regenerate your bundle manifests and metadata for your Operator: -+ -[source,terminal] ----- -$ make bundle ----- -+ -This command automatically adds scorecard annotations to your bundle metadata, which is used by the `scorecard` command to run tests. - -. Run the scorecard against the on-disk path to your Operator bundle or the name of a bundle image: -+ -[source,terminal] ----- -$ operator-sdk scorecard <bundle_dir_or_image> ----- diff --git a/modules/osdk-scorecard-select-tests.adoc b/modules/osdk-scorecard-select-tests.adoc deleted file mode 100644 index 822365703a05..000000000000 --- a/modules/osdk-scorecard-select-tests.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-scorecard.adoc - -[id="osdk-scorecard-select-tests_{context}"] -= Selecting tests - -Scorecard tests are selected by setting the `--selector` CLI flag to a set of label strings. If a selector flag is not supplied, then all the tests within the scorecard configuration file are run. - -Tests are run serially with test results being aggregated by the scorecard and written to standard output, or _stdout_. - -.Procedure - -. To select a single test, for example `basic-check-spec-test`, specify the test by using the `--selector` flag: -+ -[source,terminal] ----- -$ operator-sdk scorecard <bundle_dir_or_image> \ - -o text \ - --selector=test=basic-check-spec-test ----- - -. To select a suite of tests, for example `olm`, specify a label that is used by all of the OLM tests: -+ -[source,terminal] ----- -$ operator-sdk scorecard <bundle_dir_or_image> \ - -o text \ - --selector=suite=olm ----- - -. To select multiple tests, specify the test names by using the `selector` flag using the following syntax: -+ -[source,terminal] ----- -$ operator-sdk scorecard <bundle_dir_or_image> \ - -o text \ - --selector='test in (basic-check-spec-test,olm-bundle-validation-test)' ----- diff --git a/modules/osdk-scorecard-tests.adoc b/modules/osdk-scorecard-tests.adoc deleted file mode 100644 index b3d3a3cec3dd..000000000000 --- a/modules/osdk-scorecard-tests.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-scorecard.adoc - -[id="osdk-scorecard-tests_{context}"] -= Built-in scorecard tests - -The scorecard ships with pre-defined tests that are arranged into suites: the basic test suite and the Operator Lifecycle Manager (OLM) suite. - -[id="osdk-scorecard-basic-tests_{context}"] -.Basic test suite -[cols="3,7,3",options="header"] -|=== -|Test |Description |Short name - -|Spec Block Exists -|This test checks the custom resource (CR) created in the cluster to make sure that all CRs have a `spec` block. -|`basic-check-spec-test` -|=== - -[id="osdk-scorecard-olm-tests_{context}"] -.OLM test suite - -[cols="3,7,3",options="header"] -|=== -|Test |Description |Short name - -|Bundle Validation -|This test validates the bundle manifests found in the bundle that is passed into scorecard. If the bundle contents contain errors, then the test result output includes the validator log as well as error messages from the validation library. -|`olm-bundle-validation-test` - -|Provided APIs Have Validation -|This test verifies that the custom resource definitions (CRDs) for the provided CRs contain a validation section and that there is validation for each `spec` and `status` field detected in the CR. -|`olm-crds-have-validation-test` - -|Owned CRDs Have Resources Listed -|This test makes sure that the CRDs for each CR provided via the `cr-manifest` option have a `resources` subsection in the `owned` CRDs section of the ClusterServiceVersion (CSV). If the test detects used resources that are not listed in the resources section, it lists them in the suggestions at the end of the test. Users are required to fill out the resources section after initial code generation for this test to pass. -|`olm-crds-have-resources-test` - -|Spec Fields With Descriptors -|This test verifies that every field in the CRs `spec` sections has a corresponding descriptor listed in the CSV. -|`olm-spec-descriptors-test` - -|Status Fields With Descriptors -|This test verifies that every field in the CRs `status` sections have a corresponding descriptor listed in the CSV. -|`olm-status-descriptors-test` -|=== diff --git a/modules/osdk-suggested-namespace.adoc b/modules/osdk-suggested-namespace.adoc deleted file mode 100644 index 415e9e9cdf53..000000000000 --- a/modules/osdk-suggested-namespace.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-generating-csvs.adoc - -[id="osdk-suggested-namespace_{context}"] -= Setting a suggested namespace - -Some Operators must be deployed in a specific namespace, or with ancillary resources in specific namespaces, to work properly. If resolved from a subscription, Operator Lifecycle Manager (OLM) defaults the namespaced resources of an Operator to the namespace of its subscription. - -As an Operator author, you can instead express a desired target namespace as part of your cluster service version (CSV) to maintain control over the final namespaces of the resources installed for their Operators. When adding the Operator to a cluster using OperatorHub, this enables the web console to autopopulate the suggested namespace for the cluster administrator during the installation process. - -.Procedure - -* In your CSV, set the `operatorframework.io/suggested-namespace` annotation to your suggested namespace: -+ -[source,yaml] ----- -metadata: - annotations: - operatorframework.io/suggested-namespace: <namespace> <1> ----- -<1> Set your suggested namespace. diff --git a/modules/osdk-workflow.adoc b/modules/osdk-workflow.adoc deleted file mode 100644 index efc7b0962f0e..000000000000 --- a/modules/osdk-workflow.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator_sdk/osdk-about.adoc - -[id="osdk-workflow_{context}"] -= Development workflow - -The Operator SDK provides the following workflow to develop a new Operator: - -. Create an Operator project by using the Operator SDK command-line interface (CLI). -. Define new resource APIs by adding custom resource definitions (CRDs). -. Specify resources to watch by using the Operator SDK API. -. Define the Operator reconciling logic in a designated handler and use the Operator SDK API to interact with resources. -. Use the Operator SDK CLI to build and generate the Operator deployment manifests. - -.Operator SDK workflow -image::osdk-workflow.png[] - -At a high level, an Operator that uses the Operator SDK processes events for watched resources in an Operator author-defined handler and takes actions to reconcile the state of the application. diff --git a/modules/ossm-about-collecting-ossm-data.adoc b/modules/ossm-about-collecting-ossm-data.adoc deleted file mode 100644 index c1122dabae66..000000000000 --- a/modules/ossm-about-collecting-ossm-data.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/servicemesh-release-notes.adoc -// * service_mesh/v2x/servicemesh-release-notes.adoc - - -[id="ossm-about-collecting-ossm-data_{context}"] -= About collecting service mesh data - -You can use the `oc adm must-gather` CLI command to collect information about your cluster, including features and objects associated with {ProductName}. - -To collect {ProductName} data with `must-gather`, you must specify the {ProductName} image: - -[source,terminal] ----- -$ oc adm must-gather --image=registry.redhat.io/openshift-service-mesh/istio-must-gather-rhel7 ----- diff --git a/modules/ossm-architecture-1x.adoc b/modules/ossm-architecture-1x.adoc deleted file mode 100644 index 69775fe75977..000000000000 --- a/modules/ossm-architecture-1x.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// -service_mesh/v1x/ossm-architecture.adoc - -[id="ossm-architecture-1x_{context}"] -= {ProductName} Architecture - -{ProductName} is logically split into a data plane and a control plane: - -The *data plane* is a set of intelligent proxies deployed as sidecars. These proxies intercept and control all inbound and outbound network communication between microservices in the service mesh. Sidecar proxies also communicate with Mixer, the general-purpose policy and telemetry hub. - -* *Envoy proxy* intercepts all inbound and outbound traffic for all services in the service mesh. Envoy is deployed as a sidecar to the relevant service in the same pod. - -The *control plane* manages and configures proxies to route traffic, and configures Mixers to enforce policies and collect telemetry. - -* *Mixer* enforces access control and usage policies (such as authorization, rate limits, quotas, authentication, and request tracing) and collects telemetry data from the Envoy proxy and other services. -* *Pilot* configures the proxies at runtime. Pilot provides service discovery for the Envoy sidecars, traffic management capabilities for intelligent routing (for example, A/B tests or canary deployments), and resiliency (timeouts, retries, and circuit breakers). -* *Citadel* issues and rotates certificates. Citadel provides strong service-to-service and end-user authentication with built-in identity and credential management. You can use Citadel to upgrade unencrypted traffic in the service mesh. Operators can enforce policies based on service identity rather than on network controls using Citadel. -* *Galley* ingests the service mesh configuration, then validates, processes, and distributes the configuration. Galley protects the other service mesh components from obtaining user configuration details from {product-title}. - -{ProductName} also uses the *istio-operator* to manage the installation of the control plane. An _Operator_ is a piece of software that enables you to implement and automate common activities in your OpenShift cluster. It acts as a controller, allowing you to set or change the desired state of objects in your cluster. diff --git a/modules/ossm-architecture.adoc b/modules/ossm-architecture.adoc deleted file mode 100644 index f3e0494cf0ec..000000000000 --- a/modules/ossm-architecture.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// -service_mesh/v2x/ossm-architecture.adoc - -[id="ossm-architecture_{context}"] -= {ProductName} Architecture - -{ProductName} is logically split into a data plane and a control plane: - -The *data plane* is a set of intelligent proxies deployed as sidecars. These proxies intercept and control all inbound and outbound network communication between microservices in the service mesh. - -* *Envoy proxy* intercepts all inbound and outbound traffic for all services in the service mesh. Envoy is deployed as a sidecar to the relevant service in the same pod. - -The *control plane* manages and configures Istiod to enforce proxies to route traffic. - -Istiod provides service discovery, configuration and certificate management. It converts high-level routing rules to Envoy configurations and propagates them to the sidecars at runtime. - -Secret Discovery Service (SDS) distributes certificates and keys to sidecars directly from Istiod. - -{ProductName} also uses the *istio-operator* to manage the installation of the control plane. An _Operator_ is a piece of software that enables you to implement and automate common activities in your OpenShift cluster. It acts as a controller, allowing you to set or change the desired state of objects in your cluster. diff --git a/modules/ossm-auto-route-1x.adoc b/modules/ossm-auto-route-1x.adoc deleted file mode 100644 index 20af42dd9bc4..000000000000 --- a/modules/ossm-auto-route-1x.adoc +++ /dev/null @@ -1,77 +0,0 @@ -//// -This TASK module included in the following assemblies: -// * service_mesh/v1x/ossm-traffic-manage.adoc -//// - -[id="ossm-auto-route_{context}"] -= Automatic route creation - -OpenShift routes for Istio Gateways are automatically managed in {ProductName}. Every time an Istio Gateway is created, updated or deleted inside the service mesh, an OpenShift route is created, updated or deleted. - -[id="ossm-auto-route-enable_{context}"] -== Enabling Automatic Route Creation -A {ProductName} control plane component called Istio OpenShift Routing (IOR) synchronizes the gateway route. Enable IOR as part of the control plane deployment. - -If the Gateway contains a TLS section, the OpenShift Route will be configured to support TLS. - -. In the `ServiceMeshControlPlane` resource, add the `ior_enabled` parameter and set it to `true`. For example, see the following resource snippet: - -[source,yaml] ----- -spec: - istio: - gateways: - istio-egressgateway: - autoscaleEnabled: false - autoscaleMin: 1 - autoscaleMax: 5 - istio-ingressgateway: - autoscaleEnabled: false - autoscaleMin: 1 - autoscaleMax: 5 - ior_enabled: true ----- - - -[id="ossm-auto-route-subdomains_{context}"] -== Subdomains - -{ProductName} creates the route with the subdomain, but {product-title} must be configured to enable it. Subdomains, for example `*.domain.com`, are supported but not by default. - -If the following gateway is created: - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: Gateway -metadata: - name: gateway1 -spec: - selector: - istio: ingressgateway - servers: - - port: - number: 80 - name: http - protocol: HTTP - hosts: - - www.bookinfo.com - - bookinfo.example.com ----- - -Then, the following OpenShift Routes are created automatically. You can check that the routes are created with the following command. - -[source,terminal] ----- -$ oc -n <control_plane_namespace> get routes ----- - -.Expected output -[source,terminal] ----- -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -gateway1-lvlfn bookinfo.example.com istio-ingressgateway <all> None -gateway1-scqhv www.bookinfo.com istio-ingressgateway <all> None ----- - -If the gateway is deleted, {ProductName} deletes the routes. However, routes created manually are never modified by {ProductName}. diff --git a/modules/ossm-auto-route.adoc b/modules/ossm-auto-route.adoc deleted file mode 100644 index fe692e55148f..000000000000 --- a/modules/ossm-auto-route.adoc +++ /dev/null @@ -1,67 +0,0 @@ -//// -This TASK module included in the following assemblies: -// * service_mesh/v2x/ossm-traffic-manage.adoc -//// - -[id="ossm-auto-route_{context}"] -= Automatic route creation - -OpenShift routes for Istio Gateways are automatically managed in {ProductName}. Every time an Istio Gateway is created, updated or deleted inside the service mesh, an OpenShift route is created, updated or deleted. - -[id="ossm-auto-route-enable_{context}"] -== Disabling Automatic Route Creation - -By default, the `ServiceMeshControlPlane` automatically synchronizes the Gateway resources with OpenShift routes. - -You can disable integration between Istio Gateways and OpenShift Routes by setting the `ServiceMeshControlPlane` field `gateways.openshiftRoute.enabled` to `false`. For example, see the following resource snippet. - -[source,yaml] ----- -spec: - gateways: - openshiftRoute: - enabled: false ----- - -[id="ossm-auto-route-subdomains_{context}"] -== Subdomains - -{ProductName} creates the route with the subdomain, but {product-title} must be configured to enable it. Subdomains, for example `*.domain.com`, are supported but not by default. - -If the following gateway is created: - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: Gateway -metadata: - name: gateway1 -spec: - selector: - istio: ingressgateway - servers: - - port: - number: 80 - name: http - protocol: HTTP - hosts: - - www.bookinfo.com - - bookinfo.example.com ----- - -Then, the following OpenShift Routes are created automatically. You can check that the routes are created with the following command. - -[source,terminal] ----- -$ oc -n <control_plane_namespace> get routes ----- - -.Expected output -[source,terminal] ----- -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -gateway1-lvlfn bookinfo.example.com istio-ingressgateway <all> None -gateway1-scqhv www.bookinfo.com istio-ingressgateway <all> None ----- - -If the gateway is deleted, {ProductName} deletes the routes. However, routes created manually are never modified by {ProductName}. diff --git a/modules/ossm-automatic-sidecar-injection.adoc b/modules/ossm-automatic-sidecar-injection.adoc deleted file mode 100644 index c34bd03d9dee..000000000000 --- a/modules/ossm-automatic-sidecar-injection.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -// * service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc - -[id="ossm-automatic-sidecar-injection_{context}"] -= Enabling automatic sidecar injection - -When deploying an application into the {ProductName} you must opt in to injection by specifying the `sidecar.istio.io/inject` annotation with a value of `"true"`. Opting in ensures that the sidecar injection does not interfere with other OpenShift features such as builder pods used by numerous frameworks within the OpenShift ecosystem. - -.Prerequisites - -* Identify the deployments for which you want to enable automatic sidecar injection. -* Locate the application's YAML configuration file. - -.Procedure - -. Open the application's configuration YAML file in an editor. - -. Add `sidecar.istio.io/inject` to the configuration YAML with a value of `"true"` as illustrated here: -+ -.Sleep test application example -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - app: sleep - name: sleep -spec: - replicas: 1 - selector: - matchLabels: - app: sleep - template: - metadata: - annotations: - sidecar.istio.io/inject: "true" - labels: - app: sleep - spec: - containers: - - name: sleep - image: tutum/curl - command: ["/bin/sleep","infinity"] - imagePullPolicy: IfNotPresent ----- - -. Save the configuration file. diff --git a/modules/ossm-config-network-policy.adoc b/modules/ossm-config-network-policy.adoc deleted file mode 100644 index 560d63525da9..000000000000 --- a/modules/ossm-config-network-policy.adoc +++ /dev/null @@ -1,15 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: -* service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc -//// - -[id="ossm-config-network-policy_{context}"] - -== Setting the correct network policy - -{ProductShortName} creates network policies in the control plane and member namespaces to allow traffic between them. Before you deploy, consider the following conditions to ensure the services in your mesh that were previously exposed through an {product-title} route. - -* Traffic into the mesh must always go through the ingress-gateway for Istio to work properly. -* Deploy services external to the mesh in separate namespaces that are not in any mesh. -* Non-mesh services that need to be deployed within a service mesh enlisted namespace should label their deployments `maistra.io/expose-route: "true"`, which ensures {product-title} routes to these services still work. diff --git a/modules/ossm-configuring-jaeger-existing-v1x.adoc b/modules/ossm-configuring-jaeger-existing-v1x.adoc deleted file mode 100644 index 5f68528769a3..000000000000 --- a/modules/ossm-configuring-jaeger-existing-v1x.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-custom-resources.adoc - -[id="ossm-configuring-jaeger-existing-v1x_{context}"] -= Connecting to an existing Jaeger instance - -In order for the SMCP to connect to an existing Jaeger instance, the following must be true: - -* The Jaeger instance is deployed in the same namespace as the control plane, for example, into the `istio-system` namespace. - -* To enable secure communication between services, you should enable the oauth-proxy, which secures communication to your Jaeger instance, and make sure the secret is mounted into your Jaeger instance so Kiali can communicate with it. - -* To use a custom or already existing Jaeger instance, set `spec.istio.tracing.enabled` to "false" to disable the deployment of a Jaeger instance. - -* Supply the correct jaeger-collector endpoint to Mixer by setting `spec.istio.global.tracer.zipkin.address` to the hostname and port of your jaeger-collector service. The hostname of the service is usually `<jaeger-instance-name>-collector.<namespace>.svc.cluster.local`. - -* Supply the correct jaeger-query endpoint to Kiali for gathering traces by setting `spec.istio.kiali.jaegerInClusterURL` to the hostname of your jaeger-query service - the port is normally not required, as it uses 443 by default. The hostname of the service is usually `<jaeger-instance-name>-query.<namespace>.svc.cluster.local`. - -* Supply the dashboard URL of your Jaeger instance to Kiali to enable accessing Jaeger through the Kiali console. You can retrieve the URL from the OpenShift route that is created by the Jaeger Operator. If your Jaeger resource is called `external-jaeger` and resides in the `istio-system` project, you can retrieve the route using the following command: -+ -[source,terminal] ----- -$ oc get route -n istio-system external-jaeger ----- -+ -.Example output -[source,terminal] ----- -NAME HOST/PORT PATH SERVICES [...] -external-jaeger external-jaeger-istio-system.apps.test external-jaeger-query [...] ----- -+ -The value under `HOST/PORT` is the externally accessible URL of the Jaeger dashboard. - - -.Example Jaeger resource -[source,yaml] ----- -apiVersion: jaegertracing.io/v1 -kind: "Jaeger" -metadata: - name: "external-jaeger" - # Deploy to the Control Plane Namespace - namespace: istio-system -spec: - # Set Up Authentication - ingress: - enabled: true - security: oauth-proxy - openshift: - # This limits user access to the Jaeger instance to users who have access - # to the control plane namespace. Make sure to set the correct namespace here - sar: '{"namespace": "istio-system", "resource": "pods", "verb": "get"}' - htpasswdFile: /etc/proxy/htpasswd/auth - - volumeMounts: - - name: secret-htpasswd - mountPath: /etc/proxy/htpasswd - volumes: - - name: secret-htpasswd - secret: - secretName: htpasswd - ----- - -The following `ServiceMeshControlPlane` example assumes that you have deployed Jaeger using the Jaeger Operator and the example Jaeger resource. - -.Example `ServiceMeshControlPlane` with external Jaeger -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -metadata: - name: external-jaeger - namespace: istio-system -spec: - version: v1.1 - istio: - tracing: - # Disable Jaeger deployment by service mesh operator - enabled: false - global: - tracer: - zipkin: - # Set Endpoint for Trace Collection - address: external-jaeger-collector.istio-system.svc.cluster.local:9411 - kiali: - # Set Jaeger dashboard URL - dashboard: - jaegerURL: https://external-jaeger-istio-system.apps.test - # Set Endpoint for Trace Querying - jaegerInClusterURL: external-jaeger-query.istio-system.svc.cluster.local ----- diff --git a/modules/ossm-configuring-jaeger-v1x.adoc b/modules/ossm-configuring-jaeger-v1x.adoc deleted file mode 100644 index 55dc4c5132ca..000000000000 --- a/modules/ossm-configuring-jaeger-v1x.adoc +++ /dev/null @@ -1,183 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-custom-resources.adoc - -[id="ossm-configuring-jaeger_{context}"] -= Configuring Jaeger - -When the {ProductShortName} Operator creates the `ServiceMeshControlPlane` resource it can also create the resources for distributed tracing. {ProductShortName} uses Jaeger for distributed tracing. - -You can specify your Jaeger configuration in either of two ways: - -* Configure Jaeger in the `ServiceMeshControlPlane` resource. There are some limitations with this approach. - -* Configure Jaeger in a custom `Jaeger` resource and then reference that Jaeger instance in the `ServiceMeshControlPlane` resource. If a Jaeger resource matching the value of `name` exists, the control plane will use the existing installation. This approach lets you fully customize your Jaeger configuration. - -The default Jaeger parameters specified in the `ServiceMeshControlPlane` are as follows: - -.Default `all-in-one` Jaeger parameters -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - version: v1.1 - istio: - tracing: - enabled: true - jaeger: - template: all-in-one ----- - -.Jaeger parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value - -|tracing: - enabled: -|This parameter enables/disables installing and deploying tracing by the Service Mesh Operator. Installing Jaeger is enabled by default. To use an existing Jaeger deployment, set this value to `false`. -|`true`/`false` -|`true` - -|jaeger: - template: -|This parameter specifies which Jaeger deployment strategy to use. -|* `all-in-one`- For development, testing, demonstrations, and proof of concept. -* `production-elasticsearch` - For production use. -|`all-in-one` -|=== - -[NOTE] -==== -The default template in the `ServiceMeshControlPlane` resource is the `all-in-one` deployment strategy which uses in-memory storage. For production, the only supported storage option is Elasticsearch, therefore you must configure the `ServiceMeshControlPlane` to request the `production-elasticsearch` template when you deploy {ProductShortName} within a production environment. -==== - - -[id="ossm-configuring-jaeger-elasticsearch_{context}"] -== Configuring Elasticsearch - -The default Jaeger deployment strategy uses the `all-in-one` template so that the installation can be completed using minimal resources. However, because the `all-in-one` template uses in-memory storage, it is only recommended for development, demo, or testing purposes and should NOT be used for production environments. - -If you are deploying {ProductShortName} and Jaeger in a production environment you must change the template to the `production-elasticsearch` template, which uses Elasticsearch for Jaeger's storage needs. - -Elasticsearch is a memory intensive application. The initial set of nodes specified in the default {product-title} installation may not be large enough to support the Elasticsearch cluster. You should modify the default Elasticsearch configuration to match your use case and the resources you have requested for your {product-title} installation. You can adjust both the CPU and memory limits for each component by modifying the resources block with valid CPU and memory values. Additional nodes must be added to the cluster if you want to run with the recommended amount (or more) of memory. Ensure that you do not exceed the resources requested for your {product-title} installation. - -.Default "production" Jaeger parameters with Elasticsearch -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - istio: - tracing: - enabled: true - ingress: - enabled: true - jaeger: - template: production-elasticsearch - elasticsearch: - nodeCount: 3 - redundancyPolicy: - resources: - requests: - cpu: "1" - memory: "16Gi" - limits: - cpu: "1" - memory: "16Gi" ----- - -.Elasticsearch parameters -[options="header"] -[cols="l, a, a, a, a"] -|=== -|Parameter |Description |Values |Default Value |Examples - -|tracing: - enabled: -|This parameter enables/disables tracing in {ProductShortName}. Jaeger is installed by default. -|`true`/`false` -|`true` -| - -|ingress: - enabled: -|This parameter enables/disables ingress for Jaeger. -|`true`/`false` -|`true` -| - -|jaeger: - template: -|This parameter specifies which Jaeger deployment strategy to use. -|`all-in-one`/`production-elasticsearch` -|`all-in-one` -| - -|elasticsearch: - nodeCount: -|Number of Elasticsearch nodes to create. -|Integer value. -|1 -|Proof of concept = 1, -Minimum deployment =3 - -|requests: - cpu: -|Number of central processing units for requests, based on your environment’s configuration. -|Specified in cores or millicores (for example, 200m, 0.5, 1). -|1Gi -|Proof of concept = 500m, -Minimum deployment =1 - -|requests: - memory: -|Available memory for requests, based on your environment’s configuration. -|Specified in bytes (for example, 200Ki, 50Mi, 5Gi). -|500m -|Proof of concept = 1Gi, -Minimum deployment = 16Gi* - -|limits: - cpu: -|Limit on number of central processing units, based on your environment’s configuration. -|Specified in cores or millicores (for example, 200m, 0.5, 1). -| -|Proof of concept = 500m, -Minimum deployment =1 - -|limits: - memory: -|Available memory limit based on your environment’s configuration. -|Specified in bytes (for example, 200Ki, 50Mi, 5Gi). -| -|Proof of concept = 1Gi, -Minimum deployment = 16Gi* - -| -4+|{asterisk} Each Elasticsearch node can operate with a lower memory setting though this is *not* recommended for production deployments. For production use, you should have no less than 16Gi allocated to each pod by default, but preferably allocate as much as you can, up to 64Gi per pod. -|=== - - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Navigate to *Operators* -> *Installed Operators*. - -. Click the {ProductName} Operator. - -. Click the *Istio Service Mesh Control Plane* tab. - -. Click the name of your control plane file, for example, `basic-install`. - -. Click the *YAML* tab. - -. Edit the Jaeger parameters, replacing the default `all-in-one` template with parameters for the `production-elasticsearch` template, modified for your use case. Ensure that the indentation is correct. - -. Click *Save*. - -. Click *Reload*. -{product-title} redeploys Jaeger and creates the Elasticsearch resources based on the specified parameters. diff --git a/modules/ossm-configuring-jaeger.adoc b/modules/ossm-configuring-jaeger.adoc deleted file mode 100644 index 18d54f2cd3ed..000000000000 --- a/modules/ossm-configuring-jaeger.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/customizing-installation-ossm.adoc - - -[id="ossm-specifying-jaeger-configuration_{context}"] -= Specifying Jaeger Configuration - -You configure Jaeger under the `addons` section of `ServiceMeshControlPlane` resource. - -You can specify your Jaeger configuration in either of two ways: - -* Specify the Jaeger configuration in the `ServiceMeshControlPlane` resource under `spec.addons.jaeger.install`. There are some limitations with this approach. For example, you cannot configure a `streaming` deployment strategy via the control plane. - -* Configure and deploy a Jaeger instance and then specify the `name` of the Jaeger resource as the value for `spec.addons.jaeger.name` in the `ServiceMeshControlPlane` resource. If a Jaeger resource matching the value of `name` exists, the control plane will use the existing installation. This approach lets you fully customize your Jaeger configuration. diff --git a/modules/ossm-configuring-kiali.adoc b/modules/ossm-configuring-kiali.adoc deleted file mode 100644 index 7b68ccedc085..000000000000 --- a/modules/ossm-configuring-kiali.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="configuring-kiali_{context}"] -= Configuring Kiali - -When the {ProductShortName} Operator creates the `ServiceMeshControlPlane` it also processes the Kiali resource. The Kiali Operator then uses this object when creating Kiali instances. - -The default Kiali parameters specified in the `ServiceMeshControlPlane` are as follows: - -.Example Kiali parameters -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - kiali: - enabled: true - dashboard: - viewOnlyMode: false - ingress: - enabled: true ----- - -.Kiali parameters -[options="header"] -[cols="l, a, a, a"] -|=== -|Parameter |Description |Values |Default value - -|enabled -|This parameter enables/disables Kiali. Kiali is enabled by default. -|`true`/`false` -|`true` - -|dashboard - viewOnlyMode -|This parameter enables/disables view-only mode for the Kiali console. When view-only mode is enabled, users cannot use the console to make changes to the {ProductShortname}. -|`true`/`false` -|`false` - -|ingress - enabled -|This parameter enables/disables ingress for Kiali. -|`true`/`false` -|`true` -|=== - -[id="configuring-kiali-grafana_{context}"] -== Configuring Kiali for Grafana - -When you install Kiali and Grafana as part of {ProductName} the Operator configures the following by default: - -* Grafana is enabled as an external service for Kiali -* Grafana authorization for the Kiali console -* Grafana URL for the Kiali console - -Kiali can automatically detect the Grafana URL. However if you have a custom Grafana installation that is not easily auto-detectable by Kiali, you must update the URL value in the `ServiceMeshControlPlane` resource. - -.Additional Grafana parameters -[source,yaml] ----- -spec: - kiali: - enabled: true - dashboard: - viewOnlyMode: false - grafanaURL: "https://grafana-istio-system.127.0.0.1.nip.io/" - ingress: - enabled: true - ----- - -[id="configuring-kiali-jaeger_{context}"] -== Configuring Kiali for Jaeger - -When you install Kiali and Jaeger as part of {ProductName} the Operator configures the following by default: - -* Jaeger is enabled as an external service for Kiali -* Jaeger authorization for the Kiali console -* Jaeger URL for the Kiali console - -Kiali can automatically detect the Jaeger URL. However if you have a custom Jaeger installation that is not easily auto-detectable by Kiali, you must update the URL value in the `ServiceMeshControlPlane` resource. - -.Additional Jaeger parameters -[source,yaml] ----- -spec: - kiali: - enabled: true - dashboard: - viewOnlyMode: false - jaegerURL: "http://jaeger-query-istio-system.127.0.0.1.nip.io/" - ingress: - enabled: true ----- diff --git a/modules/ossm-control-plane-deploy-1x.adoc b/modules/ossm-control-plane-deploy-1x.adoc deleted file mode 100644 index 8b5f94cdea37..000000000000 --- a/modules/ossm-control-plane-deploy-1x.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc - -[id="ossm-control-plane-deploy-1x_{context}"] -= Deploying the {ProductName} control plane - -//// -TODO - Flesh out how multitenancy affects this, link to control plate template topic. -//// - -The `ServiceMeshControlPlane` resource defines the configuration to be used during installation. You can deploy the default configuration provided by Red Hat or customize the `ServiceMeshControlPlane` file to fit your business needs. - -You can deploy the {ProductShortName} control plane by using the {product-title} web console or from the command line using the `oc` client tool. - -[id="ossm-control-plane-deploy-operatorhub_{context}"] -== Deploying the control plane from the web console - -Follow this procedure to deploy the {ProductName} control plane by using the web console. - -.Prerequisites - -* The {ProductName} Operator must be installed. -* Review the instructions for how to customize the {ProductName} installation. -* An account with the `cluster-admin` role. - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Create a project named `istio-system`. - -.. Navigate to *Home* -> *Projects*. - -.. Click *Create Project*. - -.. Enter `istio-system` in the *Name* field. - -.. Click *Create*. - -. Navigate to *Operators* -> *Installed Operators*. - -. If necessary, select `istio-system` from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project. - -. Click the {ProductName} Operator. Under *Provided APIs*, the Operator provides links to create two resource types: -** A `ServiceMeshControlPlane` resource -** A `ServiceMeshMemberRoll` resource - -. Under *Istio Service Mesh Control Plane* click *Create ServiceMeshControlPlane*. - -. On the *Create Service Mesh Control Plane* page, modify the YAML for the default `ServiceMeshControlPlane` template as needed. -+ -[NOTE] -==== -For additional information about customizing the control plane, see customizing the {ProductName} installation. For production, you _must_ change the default Jaeger template. -==== - -. Click *Create* to create the control plane. The Operator creates pods, services, and {ProductShortName} control plane components based on your configuration parameters. - -. Click the *Istio Service Mesh Control Plane* tab. - -. Click the name of the new control plane. - -. Click the *Resources* tab to see the {ProductName} control plane resources the Operator created and configured. - - -[id="ossm-control-plane-deploy-cli_{context}"] -== Deploying the control plane from the CLI - -Follow this procedure to deploy the {ProductName} control plane the command line. - -.Prerequisites - -* The {ProductName} Operator must be installed. -* Review the instructions for how to customize the {ProductName} installation. -* An account with the `cluster-admin` role. -* Access to the OpenShift CLI (`oc`). - -.Procedure - -. Log in to the {product-title} CLI as a user with the `cluster-admin` role. -+ -[source,terminal] ----- -$ oc login https://{HOSTNAME}:6443 ----- - -. Create a project named `istio-system`. -+ -[source,terminal] ----- -$ oc new-project istio-system ----- - -. Create a `ServiceMeshControlPlane` file named `istio-installation.yaml` using the example found in "Customize the {ProductName} installation". You can customize the values as needed to match your use case. For production deployments you _must_ change the default Jaeger template. - -. Run the following command to deploy the control plane: -+ -[source,terminal] ----- -$ oc create -n istio-system -f istio-installation.yaml ----- -+ -. Execute the following command to see the status of the control plane installation. -+ -[source,terminal] ----- -$ oc get smcp -n istio-system ----- -+ -The installation has finished successfully when the STATUS column is `InstallSuccessful`. -+ ----- -NAME READY STATUS TEMPLATE VERSION AGE -basic-install 9/9 InstallSuccessful default v1.1 4m25s ----- -+ -. Run the following command to watch the progress of the Pods during the installation process: -+ ----- -$ oc get pods -n istio-system -w ----- -+ -You should see output similar to the following: -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -grafana-7bf5764d9d-2b2f6 2/2 Running 0 28h -istio-citadel-576b9c5bbd-z84z4 1/1 Running 0 28h -istio-egressgateway-5476bc4656-r4zdv 1/1 Running 0 28h -istio-galley-7d57b47bb7-lqdxv 1/1 Running 0 28h -istio-ingressgateway-dbb8f7f46-ct6n5 1/1 Running 0 28h -istio-pilot-546bf69578-ccg5x 2/2 Running 0 28h -istio-policy-77fd498655-7pvjw 2/2 Running 0 28h -istio-sidecar-injector-df45bd899-ctxdt 1/1 Running 0 28h -istio-telemetry-66f697d6d5-cj28l 2/2 Running 0 28h -jaeger-896945cbc-7lqrr 2/2 Running 0 11h -kiali-78d9c5b87c-snjzh 1/1 Running 0 22h -prometheus-6dff867c97-gr2n5 2/2 Running 0 28h ----- diff --git a/modules/ossm-control-plane-deploy.adoc b/modules/ossm-control-plane-deploy.adoc deleted file mode 100644 index 322973b2f479..000000000000 --- a/modules/ossm-control-plane-deploy.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/installing-ossm.adoc - -[id="ossm-control-plane-deploy_{context}"] -= Deploying the {ProductName} control plane - -//// -TODO - Flesh out how multitenancy affects this, link to control plate template topic. -//// - -The `ServiceMeshControlPlane` resource defines the configuration to be used during installation. - -You can deploy a basic installation of the {ProductShortName} control plane by using the {product-title} web console or from the command line using the `oc` client tool. - -To get started, deploy the basic installation with the following steps. You can customize the `ServiceMeshControlPlane` resource later. - -[NOTE] -==== -The control plane should be installed in a separate namespace from the data plane. The `istio-system` namespace is used as an example throughout the {ProductShortName} documentation, but you can deploy your control plane in any namespace as long as it is separate from your applications. -==== - -[id="ossm-control-plane-deploy-operatorhub_{context}"] -== Deploying the control plane from the web console - -Follow this procedure to deploy a basic {ProductName} control plane by using the web console. - -.Prerequisites - -* The {ProductName} Operator must be installed. -* Review the instructions for how to customize the {ProductName} installation. -* An account with the `cluster-admin` role. - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Create a project named `istio-system`. - -.. Navigate to *Home* -> *Projects*. - -.. Click *Create Project*. - -.. Enter `istio-system` in the *Name* field. - -.. Click *Create*. - -. Navigate to *Operators* -> *Installed Operators*. - -. In the Project menu, select `istio-system`. You may have to wait a few moments for the Operators to be copied to the new project. - -. Click the {ProductName} Operator, then click *Istio Service Mesh Control Plane*. - -. On the *Istio Service Mesh Control Plane* page, click *Create ServiceMeshControlPlane*. - -. On the *Create ServiceMeshControlPlane* page, you can modify the default `ServiceMeshControlPlane` template with the form, or select the YAML view to customize your installation. - -. Click *Create* to create the control plane. The Operator creates pods, services, and {ProductShortName} control plane components based on your configuration parameters. - -. Click the *Istio Service Mesh Control Plane* tab. - -. Click the name of the new control plane. - -. Click the *Resources* tab to see the {ProductName} control plane resources the Operator created and configured. - - -[id="ossm-control-plane-deploy-cli_{context}"] -== Deploying the control plane from the CLI - -Follow this procedure to deploy a basic {ProductName} control plane the command line. - -.Prerequisites - -* The {ProductName} Operator must be installed. -* Review the instructions for how to customize the {ProductName} installation. -* An account with the `cluster-admin` role. -* Access to the OpenShift CLI (`oc`). - -.Procedure - -. Log in to the {product-title} CLI as a user with the `cluster-admin` role. -+ -[source,terminal] ----- -$ oc login https://{HOSTNAME}:6443 ----- -+ -. Create a project named `istio-system`. -+ -[source,terminal] ----- -$ oc new-project istio-system ----- -+ -. Create a `ServiceMeshControlPlane` file named `istio-installation.yaml` using the following example in "Customize the {ProductName} installation". For production deployments you _must_ customize the default link:https://github.com/maistra/istio-operator/blob/maistra-2.0/deploy/examples/maistra_v2_servicemeshcontrolplane_cr_auth.yaml[template]. -+ -.Example version 2.0 istio-installation.yaml -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: basic - namespace: istio-system -spec: - version: v2.0 - tracing: - type: Jaeger - sampling: 10000 - addons: - jaeger: - name: jaeger - install: - storage: - type: Memory - kiali: - enabled: true - name: kiali - grafana: - enabled: true ----- -+ -. Run the following command to deploy the control plane, where `<istio_installation.yaml>` includes the full path to your file. -+ -[source,terminal] ----- -$ oc create -n istio-system -f <istio_installation.yaml> ----- -+ -. Execute the following command to see the status of the control plane installation. -+ -[source,terminal] ----- -$ oc get smcp -n istio-system ----- -+ -The installation has finished successfully when the `STATUS` column is `ComponentsReady`. -+ ----- -NAME READY STATUS PROFILES VERSION AGE IMAGE REGISTRY -basic 9/9 ComponentsReady ["default"] 2.0.0 3m31s ----- diff --git a/modules/ossm-control-plane-profiles.adoc b/modules/ossm-control-plane-profiles.adoc deleted file mode 100644 index ca11c06b79cb..000000000000 --- a/modules/ossm-control-plane-profiles.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc - -[id="ossm-control-plane-profiles_{context}"] -= Creating control plane profiles - -You can create reusable configurations with `ServiceMeshControlPlane` profiles. Individual users can extend the profiles they create with their own configurations. Profiles can also inherit configuration information from other profiles. For example, you can create an accounting control plane for the accounting team and a marketing control plane for the marketing team. If you create a development template and a production template, members of the marketing team and the accounting team can extend the development and production profiles with team specific customization. - -When you configure control plane profiles, which follow the same syntax as the `ServiceMeshControlPlane`, users inherit settings in a hierarchical fashion. The Operator is delivered with a `default` profile with default settings for {ProductName}. - -[id="ossm-create-configmap_{context}"] -== Creating the ConfigMap - -To add custom profiles you must create a ConfigMap named `smcp-templates` in the `openshift-operators` project and mount the ConfigMap in the Operator container at `/usr/local/share/istio-operator/templates`. - -.Prerequisites - -* An installed, verified {ProductShortName} Operator. -* An account with the `cluster-admin` role. -* Location of the Operator deployment. -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - -.Procedure - -. Log in to the {product-title} CLI as a cluster administrator. - -. From the CLI, run this command to create the ConfigMap named `smcp-templates` in the `openshift-operators` project and replace `<profiles-directory>` with the location of the `ServiceMeshControlPlane` files on your local disk: -+ -[source,terminal] ----- -$ oc create configmap --from-file=<profiles-directory> smcp-templates -n openshift-operators ----- - -. Locate the Operator ClusterServiceVersion name. -+ -[source,terminal] ----- -$ oc get clusterserviceversion -n openshift-operators | grep 'Service Mesh' ----- -+ -.Example output -[source,terminal] ----- -maistra.v2.0.0 Red Hat OpenShift Service Mesh 2.0.0 Succeeded ----- - -. Edit the Operator cluster service version to instruct the Operator to use the `smcp-templates` ConfigMap. -+ -[source,terminal] ----- -$ oc edit clusterserviceversion -n openshift-operators servicemeshoperator.v2.0.0.1 ----- - -. Add a volume mount and volume to the Operator deployment. -+ -[source,yaml] ----- -deployments: - - name: istio-operator - spec: - template: - spec: - containers: - volumeMounts: - - name: smcp-templates - mountPath: /usr/local/share/istio-operator/templates/ - volumes: - - name: smcp-templates - configMap: - name: smcp-templates -... ----- -. Save your changes and exit the editor. - -. You can use the `profiles` parameter in the `ServiceMeshControlPlane` to specify one or more templates. -+ -[source,yaml] ----- - apiVersion: maistra.io/v2 - kind: ServiceMeshControlPlane - metadata: - name: minimal-install - spec: - profiles: - - default ----- diff --git a/modules/ossm-control-plane-remove.adoc b/modules/ossm-control-plane-remove.adoc deleted file mode 100644 index 8bd88848d6de..000000000000 --- a/modules/ossm-control-plane-remove.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc -// * service_mesh/v2x/installing-ossm.adoc - -[id="ossm-control-plane-remove_{context}"] -= Removing the {ProductName} control plane - -You can remove the {ProductShortName} control plane by using the {product-title} web console or the CLI. - - -[id="ossm-control-plane-remove-operatorhub_{context}"] -== Removing the control plane with the web console - -Follow this procedure to remove the {ProductName} control plane by using the web console. - -.Prerequisites - -* The {ProductName} control plane must be deployed. - -.Procedure - -. Log in to the {product-title} web console. - -. Click the *Project* menu and choose the `istio-system` project from the list. - -. Navigate to *Operators* -> *Installed Operators*. - -. Click on *Service Mesh Control Plane* under *Provided APIs*. - -. Click the `ServiceMeshControlPlane` menu {kebab}. - -. Click *Delete Service Mesh Control Plane*. - -. Click *Delete* on the confirmation dialog window to remove the `ServiceMeshControlPlane`. - - - -[id="ossm-control-plane-remove-cli_{context}"] -== Removing the control plane from the CLI - -Follow this procedure to remove the {ProductName} control plane by using the CLI. - -.Prerequisites -* The {ProductName} control plane must be deployed. -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - -.Procedure - -[NOTE] -==== -When you remove the `ServiceMeshControlPlane`, {ProductShortName} tells the Operator to begin uninstalling everything it installed. -==== - -[TIP] -==== -You can use the shortened `smcp` alias in place of `servicemeshcontrolplane`. -==== - -. Log in to the {product-title} CLI. - -. Run this command to retrieve the name of the installed `ServiceMeshControlPlane`: -+ -[source,terminal] ----- -$ oc get servicemeshcontrolplanes -n istio-system ----- - -+ -. Replace `<name_of_custom_resource>` with the output from the previous command, and run this command to remove the custom resource: -+ -[source,terminal] ----- -$ oc delete servicemeshcontrolplanes -n istio-system <name_of_custom_resource> ----- diff --git a/modules/ossm-control-plane-templates-1x.adoc b/modules/ossm-control-plane-templates-1x.adoc deleted file mode 100644 index d065f7f73533..000000000000 --- a/modules/ossm-control-plane-templates-1x.adoc +++ /dev/null @@ -1,95 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc - -[id="ossm-control-plane-templates-1x_{context}"] -= Creating control plane templates - -You can create reusable configurations with `ServiceMeshControlPlane` templates. Individual users can extend the templates they create with their own configurations. Templates can also inherit configuration information from other templates. For example, you can create an accounting control plane for the accounting team and a marketing control plane for the marketing team. If you create a development template and a production template, members of the marketing team and the accounting team can extend the development and production templates with team specific customization. - -When you configure control plane templates, which follow the same syntax as the `ServiceMeshControlPlane`, users inherit settings in a hierarchical fashion. The Operator is delivered with a `default` template with default settings for {ProductName}. To add custom templates you must create a ConfigMap named `smcp-templates` in the `openshift-operators` project and mount the ConfigMap in the Operator container at `/usr/local/share/istio-operator/templates`. - -[id="ossm-create-configmap_{context}"] -== Creating the ConfigMap -//// -TODO -Write a ConfigMap overview/definition -//// - -Follow this procedure to create the ConfigMap. - -.Prerequisites - -* An installed, verified {ProductShortName} Operator. -* An account with the `cluster-admin` role. -* Location of the Operator deployment. -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - -.Procedure - -. Log in to the {product-title} CLI as a cluster administrator. - -. From the CLI, run this command to create the ConfigMap named `smcp-templates` in the `openshift-operators` project and replace `<templates-directory>` with the location of the `ServiceMeshControlPlane` files on your local disk: -+ -[source,terminal] ----- -$ oc create configmap --from-file=<templates-directory> smcp-templates -n openshift-operators ----- - -. Locate the Operator ClusterServiceVersion name. -+ -[source,terminal] ----- -$ oc get clusterserviceversion -n openshift-operators | grep 'Service Mesh' ----- -+ -.Example output -[source,terminal] ----- -maistra.v1.0.0 Red Hat OpenShift Service Mesh 1.0.0 Succeeded ----- - -. Edit the Operator cluster service version to instruct the Operator to use the `smcp-templates` ConfigMap. -+ -[source,terminal] ----- -$ oc edit clusterserviceversion -n openshift-operators maistra.v1.0.0 ----- - -. Add a volume mount and volume to the Operator deployment. -+ -[source,yaml] ----- -deployments: - - name: istio-operator - spec: - template: - spec: - containers: - volumeMounts: - - name: discovery-cache - mountPath: /home/istio-operator/.kube/cache/discovery - - name: smcp-templates - mountPath: /usr/local/share/istio-operator/templates/ - volumes: - - name: discovery-cache - emptyDir: - medium: Memory - - name: smcp-templates - configMap: - name: smcp-templates -... ----- -. Save your changes and exit the editor. - -. You can now use the `template` parameter in the `ServiceMeshControlPlane` to specify a template. -+ -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -metadata: - name: minimal-install -spec: - template: default ----- diff --git a/modules/ossm-cr-example-1x.adoc b/modules/ossm-cr-example-1x.adoc deleted file mode 100644 index 48376f8c444e..000000000000 --- a/modules/ossm-cr-example-1x.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc - -[id="ossm-cr-example-1x_{context}"] -= {ProductName} custom resources - -[NOTE] -==== -The `istio-system` project is used as an example throughout the {ProductShortName} documentation, but you can use other projects as necessary. -==== - -A _custom resource_ allows you to extend the API in an {ProductName} project or cluster. When you deploy {ProductShortName} it creates a default `ServiceMeshControlPlane` that you can modify to change the project parameters. - -The {ProductShortName} operator extends the API by adding the `ServiceMeshControlPlane` resource type, which enables you to create `ServiceMeshControlPlane` objects within projects. By creating a `ServiceMeshControlPlane` object, you instruct the Operator to install a {ProductShortName} control plane into the project, configured with the parameters you set in the `ServiceMeshControlPlane` object. - -This example `ServiceMeshControlPlane` definition contains all of the supported parameters and deploys {ProductName} {ProductVersion} images based on Red Hat Enterprise Linux (RHEL). - -[IMPORTANT] -==== -The 3scale Istio Adapter is deployed and configured in the custom resource file. It also requires a working 3scale account (link:https://www.3scale.net/signup/[SaaS] or link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.4/html/infrastructure/onpremises-installation[On-Premises]). -==== - -.Example istio-installation.yaml - -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -metadata: - name: basic-install -spec: - - istio: - global: - proxy: - resources: - requests: - cpu: 100m - memory: 128Mi - limits: - cpu: 500m - memory: 128Mi - - gateways: - istio-egressgateway: - autoscaleEnabled: false - istio-ingressgateway: - autoscaleEnabled: false - ior_enabled: false - - mixer: - policy: - autoscaleEnabled: false - - telemetry: - autoscaleEnabled: false - resources: - requests: - cpu: 100m - memory: 1G - limits: - cpu: 500m - memory: 4G - - pilot: - autoscaleEnabled: false - traceSampling: 100 - - kiali: - enabled: true - - grafana: - enabled: true - - tracing: - enabled: true - jaeger: - template: all-in-one ----- diff --git a/modules/ossm-cr-example.adoc b/modules/ossm-cr-example.adoc deleted file mode 100644 index 52a596c34c8c..000000000000 --- a/modules/ossm-cr-example.adoc +++ /dev/null @@ -1,279 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-cr-example_{context}"] -= {ProductName} custom resources - -[NOTE] -==== -The `istio-system` project is used as an example throughout the {ProductShortName} documentation, but you can use other projects as necessary. -==== - -A _custom resource_ allows you to extend the API in an {ProductName} project or cluster. When you deploy {ProductShortName} it creates a default `ServiceMeshControlPlane` that you can modify to change the project parameters. - -The {ProductShortName} operator extends the API by adding the `ServiceMeshControlPlane` resource type, which enables you to create `ServiceMeshControlPlane` objects within projects. By creating a `ServiceMeshControlPlane` object, you instruct the Operator to install a {ProductShortName} control plane into the project, configured with the parameters you set in the `ServiceMeshControlPlane` object. - -This example `ServiceMeshControlPlane` definition contains all of the supported parameters and deploys {ProductName} {ProductVersion} images based on Red Hat Enterprise Linux (RHEL). - -[IMPORTANT] -==== -The 3scale Istio Adapter is deployed and configured in the custom resource file. It also requires an active 3scale account (link:https://www.3scale.net/signup/[SaaS] or link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.4/html/infrastructure/onpremises-installation[On-Premises]). -==== - -.Example `ServiceMeshControlPlane` resource - -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: basic -spec: - proxy: - resources: - requests: - cpu: 100m - memory: 128Mi - limits: - cpu: 500m - memory: 128Mi - tracing: - type: Jaeger - gateways: - ingress: # istio-ingressgateway - service: - type: ClusterIP - ports: - - name: status-port - port: 15020 - - name: http2 - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 - meshExpansionPorts: [] - egress: # istio-egressgateway - service: - type: ClusterIP - ports: - - name: status-port - port: 15020 - - name: http2 - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 - additionalIngress: - some-other-ingress-gateway: {} - additionalEgress: - some-other-egress-gateway: {} - - policy: - type: Istiod # or Mixer - mixer: # only applies if policy.type: Mixer - enableChecks: false - failOpen: false - - telemetry: - type: Istiod # or Mixer - mixer: # only applies if telemetry.type: Mixer, for v1 telemetry - sessionAffinity: false - batching: - maxEntries: 100 - maxTime: 1s - adapters: - kubernetesenv: true - stdio: - enabled: true - outputAsJSON: true - addons: - grafana: - enabled: true - install: - config: - env: {} - envSecrets: {} - persistence: - storageClassName: "" - accessMode: ReadWriteOnce - capacity: 5Gi - service: - ingress: - contextPath: /grafana - tls: - termination: reencrypt - kiali: - name: kiali - enabled: true - install: # install kiali CR if not present - dashboard: - viewOnly: false - enableGrafana: true - enableTracing: true - enablePrometheus: true - service: - ingress: - contextPath: /kiali - jaeger: - name: jaeger - install: - storage: - type: Memory # or Elasticsearch - memory: - maxTraces: 100000 - elasticsearch: - nodeCount: 3 - storage: {} - redundancyPolicy: SingleRedundancy - indexCleaner: {} - ingress: {} # jaeger ingress configuration - runtime: - components: - pilot: - deployment: - replicas: 2 - pod: - affinity: {} - container: - resources: - limits: {} - requirements: {} - grafana: - deployment: {} - pod: {} - kiali: - deployment: {} - pod: {} ----- - -The following table lists the parameters for the `ServiceMeshControlPlane` resource. - -.`ServiceMeshControlPlane` resource parameters -|=== -|Name |Description |Type - -|`apiVersion` -|APIVersion defines the versioned schema of this representation of an object. Servers convert recognized schemas to the latest internal value, and may reject unrecognized values. The value for {ProductName} version 2.0 is `maistra.io/v2`. -|The value for {ProductName} version 2.0 is maistra.io/v2. - -|kind -|Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. -|Not configurable - -|metadata -|Metadata about this `ServiceMeshControlPlane` instance You can provide a name for your control plane installation to keep track of your work, for example, `basic-install`, or `production`. -|string - -|spec -|The specification of the desired state of this `ServiceMeshControlPlane`. This includes the configuration options for all components that comprise the control plane. -|For more information, see Table 2. - -|status -|The current status of this `ServiceMeshControlPlane` and the components that comprise the control plane. -|For more information, see Table 3. -|=== - -The following table lists the specifications for the `ServiceMeshControlPlane` resource. These parameters configure {ProductName} for your microservices and apps. - -.`ServiceMeshControlPlane` resource spec -|=== -|Name |Description |Configurable parameters - -|`addons` -| You use the `addons` parameter to configure additional features beyond core control plane components, such as visualization, or metric storage. -|`3scale`, `grafana`, `jaeger`, `kiali`, and `prometheus`. - -|`cluster` -|The `cluster` parameter sets the general configuration of the cluster (cluster name, network name, multi-cluster, mesh expansion, etc.) -|`meshExpansion`, `multiCluster`, `name`, and `network` - -|`gateways` -| You use the `gateways` parameter to configure ingress and egress gateways for the mesh. -|`enabled`, `additionalEgress`, `additionalIngress`, `egress`, `ingress`, and `openshiftRoute` - -|`general` -|The `general` parameter represents general control plane configuration that does not fit anywhere else. -|`logging` and `validationMessages` - -|`policy` -|You use the `policy` parameter to configure policy checking for the control plane. Policy checking can be enabled by setting `spec.policy.enabled` to `true`. -|`mixer` `remote`, or `type`. `type` can be set to `Istiod`, `Mixer` or `None`. - -|`profiles` -|You select the `ServiceMeshControlPlane` profile to use for default values using the `profiles` parameter. -|`default` - -|`proxy` -| You use the `proxy` parameter to configure the default behavior for sidecars. -|`accessLogging`, `adminPort`, `concurrency`, and `envoyMetricsService` - -|`runtime` -| You use the `runtime` parameter to configure the control plane components. -|`components`, and `defaults` - -|`security` -| The `security` parameter allows you to configure aspects of security for the control plane. -|`certificateAuthority`, `controlPlane`, `identity`, `dataPlane` and `trust` - -|`techPreview` -|The `techPreview` parameter enables early access to features that are in technology techPreview. -|N/A - -|`telemetry` -|If `spec.mixer.telemetry.enabled` is set to `true`, telemetry is enabled. -|`mixer`, `remote`, and `type`. `type` can be set to `Istiod`, `Mixer` or `None`. - -|`tracing` -|You use the `tracing` parameter to enables distributed tracing for the mesh. -|`sampling`, `type`. `type` can be set to `Jaeger` or `None`. - -|`version` -|You use the `version` parameter to specify what Maistra version of the control plane to install. When creating a `ServiceMeshControlPlane` with an empty version, the admission webhook sets the version to the current version. New `ServiceMeshControlPlanes` with an empty version are set to `v2.0`. Existing `ServiceMeshControlPlanes` with an empty version keep their setting. -|string -|=== - -`ControlPlaneStatus` represents the current state of your service mesh. - -.`ServiceMeshControlPlane` resource `ControlPlaneStatus` -|=== -|Name |Description |Type - -|`annotations` -|The `annotations` parameter stores additional, usually redundant status information, such as the number of components deployed by the `ServiceMeshControlPlane`. These statuses are used by the command line tool, `oc`, which does not yet allow counting objects in JSONPath expressions. -|Not configurable - -|`conditions` -|Represents the latest available observations of the object’s current state. `Reconciled` indicates whether the operator has finished reconciling the actual state of deployed components with the configuration in the `ServiceMeshControlPlane` resource. `Installed` indicates whether the control plane has been installed. `Ready` indicates whether all control plane components are ready -|string - -|`components` -|Shows the status of each deployed control plane component. -|string - -|`appliedSpec` -|The resulting specification of the configuration options after all profiles have been applied. -|`ControlPlaneSpec` - -|`appliedValues` -|The resulting values.yaml used to generate the charts. -|`ControlPlaneSpec` - -|`chartVersion` -|The version of the charts that were last processed for this resource. -|string - -|`observedGeneration` -|The generation observed by the controller during the most recent reconciliation. The information in the status pertains to this particular generation of the object. The `status.conditions` are not up-to-date if the `status.observedGeneration` field doesn't match `metadata.generation`. -|integer - -|`operatorVersion` -|The version of the operator that last processed this resource. -|string - -|`readiness` -|The readiness status of components & owned resources -|string -|=== diff --git a/modules/ossm-cr-gateway.adoc b/modules/ossm-cr-gateway.adoc deleted file mode 100644 index dfc757cbfdcd..000000000000 --- a/modules/ossm-cr-gateway.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-cr-gateway_{context}"] -= Istio gateway configuration - -Here is an example that illustrates the Istio gateway parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values. - -.Example gateway parameters -[source,yaml] ----- - gateways: - egress: - enabled: true - runtime: - deployment: - autoScaling: - enabled: true - maxReplicas: 5 - minReplicas: 1 - enabled: true - ingress: - enabled: true - runtime: - deployment: - autoScaling: - enabled: true - maxReplicas: 5 - minReplicas: 1 ----- - - -.Istio Gateway parameters -|=== -|Parameter |Description |Values |Default value - -|`gateways.egress.runtime.deployment.autoScaling.enabled` -|This parameter enables/disables autoscaling. -|`true`/`false` -|`true` - -|`gateways.egress.runtime.deployment.autoScaling.minReplicas` -|The minimum number of pods to deploy for the egress gateway based on the `autoscaleEnabled` setting. -|A valid number of allocatable pods based on your environment's configuration. -|`1` - -|`gateways.egress.runtime.deployment.autoScaling.maxReplicas` -|The maximum number of pods to deploy for the egress gateway based on the `autoscaleEnabled` setting. -|A valid number of allocatable pods based on your environment's configuration. -|`5` - -|`gateways.ingress.runtime.deployment.autoScaling.enabled` -|This parameter enables/disables autoscaling. -|`true`/`false` -|`true` - -|`gateways.ingress.runtime.deployment.autoScaling.minReplicas` -|The minimum number of pods to deploy for the ingress gateway based on the `autoscaleEnabled` setting. -|A valid number of allocatable pods based on your environment's configuration. -|`1` - -|`gateways.ingress.runtime.deployment.autoScaling.maxReplicas` -|The maximum number of pods to deploy for the ingress gateway based on the `autoscaleEnabled` setting. -|A valid number of allocatable pods based on your environment's configuration. -|`5` -|=== diff --git a/modules/ossm-cr-istio-global-1x.adoc b/modules/ossm-cr-istio-global-1x.adoc deleted file mode 100644 index 98884895f3ad..000000000000 --- a/modules/ossm-cr-istio-global-1x.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-cr-istio-global_{context}"] -= Istio global example - -Here is an example that illustrates the Istio global parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values. - -[NOTE] -==== -In order for the 3scale Istio Adapter to work, `disablePolicyChecks` must be `false`. -==== - -.Example global parameters -[source,yaml] ----- - istio: - global: - tag: 1.1.0 - hub: registry.redhat.io/openshift-service-mesh/ - proxy: - resources: - requests: - cpu: 10m - memory: 128Mi - limits: - mtls: - enabled: false - disablePolicyChecks: true - policyCheckFailOpen: false - imagePullSecrets: - - MyPullSecret ----- - -.Global parameters -|=== -|Parameter |Description |Values |Default value - -|`disablePolicyChecks` -|This parameter enables/disables policy checks. -|`true`/`false` -|`true` - -|`policyCheckFailOpen` -|This parameter indicates whether traffic is allowed to pass through to the Envoy sidecar when the Mixer policy service cannot be reached. -|`true`/`false` -|`false` - -|`tag` -|The tag that the Operator uses to pull the Istio images. -|A valid container image tag. -|`1.1.0` - -|`hub` -|The hub that the Operator uses to pull Istio images. -|A valid image repository. -|`maistra/` or `registry.redhat.io/openshift-service-mesh/` - -|`mtls` -|This parameter controls whether to enable/disable Mutual Transport Layer Security (mTLS) between services by default. -|`true`/`false` -|`false` - -|`imagePullSecrets` -|If access to the registry providing the Istio images is secure, list an link:https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod[imagePullSecret] here. -|redhat-registry-pullsecret OR quay-pullsecret -|None -|=== - -These parameters are specific to the proxy subset of global parameters. - -.Proxy parameters -|=== -|Type |Parameter |Description |Values |Default value - -|`requests` -|`cpu` -|The amount of CPU resources requested for Envoy proxy. -|CPU resources, specified in cores or millicores (for example, 200m, 0.5, 1) based on your environment’s configuration. -|`10m` - -| -|`memory` -|The amount of memory requested for Envoy proxy -|Available memory in bytes(for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`128Mi` - -|Limits -|`cpu` -|The maximum amount of CPU resources requested for Envoy proxy. -|CPU resources, specified in cores or millicores (for example, 200m, 0.5, 1) based on your environment’s configuration. -|`2000m` - -| -|`memory` -|The maximum amount of memory Envoy proxy is permitted to use. -|Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`1024Mi` -|=== diff --git a/modules/ossm-cr-istio-global.adoc b/modules/ossm-cr-istio-global.adoc deleted file mode 100644 index 39e4c99c86f2..000000000000 --- a/modules/ossm-cr-istio-global.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-cr-istio-global_{context}"] -= Istio global example - -Here is an example that illustrates the Istio global parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values. - -[NOTE] -==== -In order for the 3scale Istio Adapter to work, `disablePolicyChecks` must be `false`. -==== - -.Example global parameters -[source,yaml] ----- - istio: - global: - tag: 1.1.0 - hub: registry.redhat.io/openshift-service-mesh/ - proxy: - resources: - requests: - cpu: 10m - memory: 128Mi - limits: - mtls: - enabled: false - disablePolicyChecks: true - policyCheckFailOpen: false - imagePullSecrets: - - MyPullSecret ----- - -.Global parameters -|=== -|Parameter |Description |Values |Default value - -|`disablePolicyChecks` -|This parameter enables/disables policy checks. -|`true`/`false` -|`true` - -|`policyCheckFailOpen` -|This parameter indicates whether traffic is allowed to pass through to the Envoy sidecar when the Mixer policy service cannot be reached. -|`true`/`false` -|`false` - -|`tag` -|The tag that the Operator uses to pull the Istio images. -|A valid container image tag. -|`1.1.0` - -|`hub` -|The hub that the Operator uses to pull Istio images. -|A valid image repository. -|`maistra/` or `registry.redhat.io/openshift-service-mesh/` - -|`mtls` -|This parameter controls whether to enable/disable Mutual Transport Layer Security (mTLS) between services by default. -|`true`/`false` -|`false` - -|`imagePullSecrets` -|If access to the registry providing the Istio images is secure, list an link:https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod[imagePullSecret] here. -|redhat-registry-pullsecret OR quay-pullsecret -|None -|=== - -These parameters are specific to the proxy subset of global parameters. - -.Proxy parameters -|=== -|Type |Parameter |Description |Values |Default value - -|`requests` -|`cpu` -|The amount of CPU resources requested for Envoy proxy. -|CPU resources, specified in cores or millicores (for example, 200m, 0.5, 1) based on your environment’s configuration. -|`10m` - -| -|`memory` -|The amount of memory requested for Envoy proxy -|Available memory in bytes(for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`128Mi` - -|`limits` -|`cpu` -|The maximum amount of CPU resources requested for Envoy proxy. -|CPU resources, specified in cores or millicores (for example, 200m, 0.5, 1) based on your environment’s configuration. -|`2000m` - -| -|`memory` -|The maximum amount of memory Envoy proxy is permitted to use. -|Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`1024Mi` -|=== diff --git a/modules/ossm-cr-mixer-1x.adoc b/modules/ossm-cr-mixer-1x.adoc deleted file mode 100644 index 24de5ea7b7bd..000000000000 --- a/modules/ossm-cr-mixer-1x.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc - -[id="ossm-cr-mixer-1x_{context}"] -= Istio Mixer configuration - -Here is an example that illustrates the Mixer parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values. - -.Example mixer parameters -[source,yaml] ----- -mixer: - enabled: true - policy: - autoscaleEnabled: false - telemetry: - autoscaleEnabled: false - resources: - requests: - cpu: 10m - memory: 128Mi - limits: - ----- - - -.Istio Mixer policy parameters -|=== -|Parameter |Description |Values |Default value - -|`enabled` -|This parameter enables/disables Mixer. -|`true`/`false` -|`true` - -|`autoscaleEnabled` -|This parameter enables/disables autoscaling. Disable this for small environments. -|`true`/`false` -|`true` - -|`autoscaleMin` -|The minimum number of pods to deploy based on the `autoscaleEnabled` setting. -|A valid number of allocatable pods based on your environment's configuration. -|`1` - -|`autoscaleMax` -|The maximum number of pods to deploy based on the `autoscaleEnabled` setting. -|A valid number of allocatable pods based on your environment's configuration. -|`5` -|=== - - -.Istio Mixer telemetry parameters -|=== -|Type |Parameter |Description |Values |Default - -|Requests -|`cpu` -|The percentage of CPU resources requested for Mixer telemetry. -|CPU resources in millicores based on your environment's configuration. -|`10m` - -| -|`memory` -|The amount of memory requested for Mixer telemetry. -|Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`128Mi` - -|Limits -|`cpu` -|The maximum percentage of CPU resources Mixer telemetry is permitted to use. -|CPU resources in millicores based on your environment's configuration. -|`4800m` - -| -|`memory` -|The maximum amount of memory Mixer telemetry is permitted to use. -|Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`4G` -|=== diff --git a/modules/ossm-cr-mixer.adoc b/modules/ossm-cr-mixer.adoc deleted file mode 100644 index 42e6b0f9e3e1..000000000000 --- a/modules/ossm-cr-mixer.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-cr-mixer_{context}"] -= Istio Mixer configuration - -Here is an example that illustrates the Mixer parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values. - -.Example mixer parameters -[source,yaml] ----- -mixer: - enabled: true - policy: - autoscaleEnabled: false - telemetry: - autoscaleEnabled: false - resources: - requests: - cpu: 10m - memory: 128Mi - limits: - ----- - - -.Istio Mixer policy parameters -|=== -|Parameter |Description |Values |Default value - -|`enabled` -|This parameter enables/disables Mixer. -|`true`/`false` -|`true` - -|`autoscaleEnabled` -|This parameter enables/disables autoscaling. Disable this for small environments. -|`true`/`false` -|`true` - -|`autoscaleMin` -|The minimum number of pods to deploy based on the `autoscaleEnabled` setting. -|A valid number of allocatable pods based on your environment's configuration. -|`1` - -|`autoscaleMax` -|The maximum number of pods to deploy based on the `autoscaleEnabled` setting. -|A valid number of allocatable pods based on your environment's configuration. -|`5` -|=== - - -.Istio Mixer telemetry parameters -|=== -|Type |Parameter |Description |Values |Default - -|Requests -|`cpu` -|The percentage of CPU resources requested for Mixer telemetry. -|CPU resources in millicores based on your environment's configuration. -|`10m` - -| -|`memory` -|The amount of memory requested for Mixer telemetry. -|Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`128Mi` - -|Limits -|`cpu` -|The maximum percentage of CPU resources Mixer telemetry is permitted to use. -|CPU resources in millicores based on your environment's configuration. -|`4800m` - -| -|`memory` -|The maximum amount of memory Mixer telemetry is permitted to use. -|Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`4G` -|=== diff --git a/modules/ossm-cr-parameters.adoc b/modules/ossm-cr-parameters.adoc deleted file mode 100644 index 57d4a05132b1..000000000000 --- a/modules/ossm-cr-parameters.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-cr-parameters_{context}"] -= `ServiceMeshControlPlane` parameters - -The following examples illustrate use of the `ServiceMeshControlPlane` parameters and the tables provide additional information about supported parameters. - -[IMPORTANT] -==== -The resources you configure for {ProductName} with these parameters, including CPUs, memory, and the number of pods, are based on the configuration of your OpenShift cluster. Configure these parameters based on the available resources in your current cluster configuration. -==== diff --git a/modules/ossm-cr-pilot-1x.adoc b/modules/ossm-cr-pilot-1x.adoc deleted file mode 100644 index 1516cac2fcdf..000000000000 --- a/modules/ossm-cr-pilot-1x.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc - -[id="ossm-cr-pilot-1x_{context}"] -= Istio Pilot configuration - -Here is an example that illustrates the Istio Pilot parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values. - -.Example pilot parameters -[source,yaml] ----- - pilot: - resources: - requests: - cpu: 100m - memory: 128Mi - autoscaleEnabled: false - traceSampling: 100 ----- - -.Istio Pilot parameters -|=== -|Parameter |Description |Values |Default value - -|`cpu` -|The percentage of CPU resources requested for Pilot. -|CPU resources in millicores based on your environment's configuration. -|`10m` - -|`memory` -|The amount of memory requested for Pilot. -|Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`128Mi` - -|`autoscaleEnabled` -|This parameter enables/disables autoscaling. Disable this for small environments. -|`true`/`false` -|`true` - - -|`traceSampling` -|This value controls how often random sampling occurs. *Note:* Increase for development or testing. -|A valid percentage. -|`1.0` -|=== diff --git a/modules/ossm-cr-pilot.adoc b/modules/ossm-cr-pilot.adoc deleted file mode 100644 index ac23e87ea981..000000000000 --- a/modules/ossm-cr-pilot.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-cr-pilot_{context}"] -= Istio Pilot configuration - -You can configure Pilot to schedule or set limits on resource allocation. -The following example illustrates the Pilot parameters for the `ServiceMeshControlPlane` and a description of the available parameters with appropriate values. - -.Example pilot parameters -[source,yaml] ----- -spec: - runtime: - components: - pilot: - deployment: - autoScaling: - enabled: true - minReplicas: 1 - maxReplicas: 5 - targetCPUUtilizationPercentage: 85 - pod: - tolerations: - - key: node.kubernetes.io/unreachable - operator: Exists - effect: NoExecute - tolerationSeconds: 60 - affinity: - podAntiAffinity: - requiredDuringScheduling: - - key: istio - topologyKey: kubernetes.io/hostname - operator: In - values: - - pilot - container: - resources: - limits: - cpu: 100m - memory: 128M ----- - -.Istio Pilot parameters -|=== -|Parameter |Description |Values |Default value - -|`cpu` -|The percentage of CPU resources requested for Pilot. -|CPU resources in millicores based on your environment's configuration. -|`10m` - -|`memory` -|The amount of memory requested for Pilot. -|Available memory in bytes (for example, 200Ki, 50Mi, 5Gi) based on your environment’s configuration. -|`128Mi` - -|`autoscaleEnabled` -|This parameter enables/disables autoscaling. Disable this for small environments. -|`true`/`false` -|`true` - - -|`traceSampling` -|This value controls how often random sampling occurs. *Note:* Increase for development or testing. -|A valid percentage. -|`1.0` -|=== diff --git a/modules/ossm-cr-threescale-1x.adoc b/modules/ossm-cr-threescale-1x.adoc deleted file mode 100644 index 792be2a6ca61..000000000000 --- a/modules/ossm-cr-threescale-1x.adoc +++ /dev/null @@ -1,104 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc - -[id="ossm-cr-threescale-1x_{context}"] - -= 3scale configuration - -Here is an example that illustrates the 3scale Istio Adapter parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values. - -.Example 3scale parameters -[source,yaml] ----- -threeScale: - enabled: false - PARAM_THREESCALE_LISTEN_ADDR: 3333 - PARAM_THREESCALE_LOG_LEVEL: info - PARAM_THREESCALE_LOG_JSON: true - PARAM_THREESCALE_LOG_GRPC: false - PARAM_THREESCALE_REPORT_METRICS: true - PARAM_THREESCALE_METRICS_PORT: 8080 - PARAM_THREESCALE_CACHE_TTL_SECONDS: 300 - PARAM_THREESCALE_CACHE_REFRESH_SECONDS: 180 - PARAM_THREESCALE_CACHE_ENTRIES_MAX: 1000 - PARAM_THREESCALE_CACHE_REFRESH_RETRIES: 1 - PARAM_THREESCALE_ALLOW_INSECURE_CONN: false - PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS: 10 - PARAM_THREESCALE_GRPC_CONN_MAX_SECONDS: 60 ----- - -.3scale parameters -|=== -|Parameter |Description |Values |Default value - -|`enabled` -|Whether to use the 3scale adapter -|`true`/`false` -|`false` - -|`PARAM_THREESCALE_LISTEN_ADDR` -|Sets the listen address for the gRPC server -|Valid port number -|`3333` - -|`PARAM_THREESCALE_LOG_LEVEL` -|Sets the minimum log output level. -|`debug`, `info`, `warn`, `error`, or `none` -|`info` - -|`PARAM_THREESCALE_LOG_JSON` -|Controls whether the log is formatted as JSON -|`true`/`false` -|`true` - -|`PARAM_THREESCALE_LOG_GRPC` -|Controls whether the log contains gRPC info -|`true`/`false` -|`true` - -|`PARAM_THREESCALE_REPORT_METRICS` -|Controls whether 3scale system and backend metrics are collected and reported to Prometheus -|`true`/`false` -|`true` - -|`PARAM_THREESCALE_METRICS_PORT` -|Sets the port that the 3scale `/metrics` endpoint can be scrapped from -|Valid port number -|`8080` - -|`PARAM_THREESCALE_CACHE_TTL_SECONDS` -|Time period, in seconds, to wait before purging expired items from the cache -|Time period in seconds -|`300` - -|`PARAM_THREESCALE_CACHE_REFRESH_SECONDS` -|Time period before expiry when cache elements are attempted to be refreshed -|Time period in seconds -|`180` - -|`PARAM_THREESCALE_CACHE_ENTRIES_MAX` -|Max number of items that can be stored in the cache at any time. Set to `0` to disable caching -|Valid number -|`1000` - -|`PARAM_THREESCALE_CACHE_REFRESH_RETRIES` -|The number of times unreachable hosts are retried during a cache update loop -|Valid number -|`1` - -|`PARAM_THREESCALE_ALLOW_INSECURE_CONN` -|Allow to skip certificate verification when calling `3scale` APIs. Enabling this is not recommended. -|`true`/`false` -|`false` - -|`PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS` -|Sets the number of seconds to wait before terminating requests to 3scale System and Backend -|Time period in seconds -|`10` - -|`PARAM_THREESCALE_GRPC_CONN_MAX_SECONDS` -|Sets the maximum amount of seconds (+/-10% jitter) a connection may exist before it is closed -|Time period in seconds -|60 -|=== diff --git a/modules/ossm-cr-threescale.adoc b/modules/ossm-cr-threescale.adoc deleted file mode 100644 index 60fd852f760b..000000000000 --- a/modules/ossm-cr-threescale.adoc +++ /dev/null @@ -1,124 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-cr-threescale_{context}"] - -= 3scale configuration - -Here is an example that illustrates the 3scale Istio Adapter parameters for the {ProductName} custom resource and a description of the available parameters with appropriate values. - -.Example 3scale parameters -[source,yaml] ----- -threeScale: - enabled: false - PARAM_THREESCALE_LISTEN_ADDR: 3333 - PARAM_THREESCALE_LOG_LEVEL: info - PARAM_THREESCALE_LOG_JSON: true - PARAM_THREESCALE_LOG_GRPC: false - PARAM_THREESCALE_REPORT_METRICS: true - PARAM_THREESCALE_METRICS_PORT: 8080 - PARAM_THREESCALE_CACHE_TTL_SECONDS: 300 - PARAM_THREESCALE_CACHE_REFRESH_SECONDS: 180 - PARAM_THREESCALE_CACHE_ENTRIES_MAX: 1000 - PARAM_THREESCALE_CACHE_REFRESH_RETRIES: 1 - PARAM_THREESCALE_ALLOW_INSECURE_CONN: false - PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS: 10 - PARAM_THREESCALE_GRPC_CONN_MAX_SECONDS: 60 - PARAM_USE_CACHED_BACKEND: false - PARAM_BACKEND_CACHE_FLUSH_INTERVAL_SECONDS: 15 - PARAM_BACKEND_CACHE_POLICY_FAIL_CLOSED: true ----- - -.3scale parameters -|=== -|Parameter |Description |Values |Default value - -|`enabled` -|Whether to use the 3scale adapter -|`true`/`false` -|`false` - -|`PARAM_THREESCALE_LISTEN_ADDR` -|Sets the listen address for the gRPC server -|Valid port number -|`3333` - -|`PARAM_THREESCALE_LOG_LEVEL` -|Sets the minimum log output level. -|`debug`, `info`, `warn`, `error`, or `none` -|`info` - -|`PARAM_THREESCALE_LOG_JSON` -|Controls whether the log is formatted as JSON -|`true`/`false` -|`true` - -|`PARAM_THREESCALE_LOG_GRPC` -|Controls whether the log contains gRPC info -|`true`/`false` -|`true` - -|`PARAM_THREESCALE_REPORT_METRICS` -|Controls whether 3scale system and backend metrics are collected and reported to Prometheus -|`true`/`false` -|`true` - -|`PARAM_THREESCALE_METRICS_PORT` -|Sets the port that the 3scale `/metrics` endpoint can be scrapped from -|Valid port number -|`8080` - -|`PARAM_THREESCALE_CACHE_TTL_SECONDS` -|Time period, in seconds, to wait before purging expired items from the cache -|Time period in seconds -|`300` - -|`PARAM_THREESCALE_CACHE_REFRESH_SECONDS` -|Time period before expiry when cache elements are attempted to be refreshed -|Time period in seconds -|`180` - -|`PARAM_THREESCALE_CACHE_ENTRIES_MAX` -|Max number of items that can be stored in the cache at any time. Set to `0` to disable caching -|Valid number -|`1000` - -|`PARAM_THREESCALE_CACHE_REFRESH_RETRIES` -|The number of times unreachable hosts are retried during a cache update loop -|Valid number -|`1` - -|`PARAM_THREESCALE_ALLOW_INSECURE_CONN` -|Allow to skip certificate verification when calling `3scale` APIs. Enabling this is not recommended. -|`true`/`false` -|`false` - -|`PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS` -|Sets the number of seconds to wait before terminating requests to 3scale System and Backend -|Time period in seconds -|`10` - -|`PARAM_THREESCALE_GRPC_CONN_MAX_SECONDS` -|Sets the maximum amount of seconds (+/-10% jitter) a connection may exist before it is closed -|Time period in seconds -|60 - - -|`PARAM_USE_CACHE_BACKEND` -|If true, attempt to create an in-memory apisonator cache for authorization requests -|`true`/`false` -|`false` - -|`PARAM_BACKEND_CACHE_FLUSH_INTERVAL_SECONDS` -|If the backend cache is enabled, this sets the interval in seconds for flushing the cache against 3scale -|Time period in seconds -|15 - -|`PARAM_BACKEND_CACHE_POLICY_FAIL_CLOSED` -|Whenever the backend cache cannot retrieve authorization data, whether to deny (closed) or allow (open) requests -|`true`/`false` -|`true` -|=== diff --git a/modules/ossm-deploying-jaeger.adoc b/modules/ossm-deploying-jaeger.adoc deleted file mode 100644 index 145c5d43011a..000000000000 --- a/modules/ossm-deploying-jaeger.adoc +++ /dev/null @@ -1,104 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/ossm-custom-resources.adoc - - -[id="ossm-deploying-jaeger_{context}"] -= Deploying Jaeger - -The Jaeger Operator currently supports the following deployment strategies: - -* *allInOne* (Default) - This strategy is intended for development, testing, and demo purposes; it is not intended for production use. The main backend components, Agent, Collector and Query service, are all packaged into a single executable which is configured (by default) to use in-memory storage. -+ -[NOTE] -==== -In-memory storage is not persistent, which means that if the Jaeger instance shuts down, restarts, or is replaced, your trace data will be lost. And in-memory storage cannot be scaled, since each pod has its own memory. For persistent storage, you must use the `production` or `streaming` strategies, which use Elasticsearch as the default storage. -==== - -* *production* - The production strategy is intended for production environments, where long term storage of trace data is important, as well as a more scalable and highly available architecture is required. Each of the backend components is therefore deployed separately. The Agent can be injected as a sidecar on the instrumented application. The Query and Collector services are configured with a supported storage type - currently Elasticsearch. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes. - -* *streaming* - The streaming strategy is designed to augment the production strategy by providing a streaming capability that effectively sits between the Collector and the backend storage (Elasticsearch). This provides the benefit of reducing the pressure on the backend storage, under high load situations, and enables other trace post-processing capabilities to tap into the real time span data directly from the streaming platform (https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/using_amq_streams_on_openshift/index[AMQ Streams]/ https://kafka.apache.org/documentation/[Kafka]). - -[NOTE] -==== -The streaming strategy requires an additional Red Hat subscription for AMQ Streams. -==== - -[id="ossm-deploying-jaeger-default_{context}"] -== Default Jaeger deployment - -To use the default `allInOne` Jaeger deployment strategy set `spec.addons.jaeger.install.storage.type` to `Memory`. You can accept the defaults or specify additional configuration options under `install`. If you do not specify Jaeger configuration options, the Control Plane will use the `allInOne` deployment strategy by default. - -.Control Plane default Jaeger parameters (Memory) -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: basic -spec: - version: v2.0 - tracing: - sampling: 10000 - type: Jaeger - addons: - jaeger: - name: jaeger - install: - storage: - type: Memory ----- - -[id="ossm-deploying-jaeger-production_{context}"] -== Production Jaeger deployment - -To use the `production` deployment strategy, set `spec.addons.jaeger.install.storage.type` to 'Elasticsearch' and specify additional configuration options under `install`. Or you can create and configure your Jaeger instance and set `spec.addons.jaeger.name` to the name of the Jaeger instance, for example `jaeger-production`. - -.Control Plane default Jaeger parameters (Elasticsearch) -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: production -spec: - version: v2.0 - tracing: - sampling: 10000 - type: Jaeger - addons: - jaeger: - name: jaeger-production - install: - storage: - type: Elasticsearch - ingress: - enabled: true - runtime: - components: - tracing.jaeger.elasticsearch: # only supports resources and image name - container: - resources: {} ----- - -[id="ossm-deploying-jaeger-streaming_{context}"] -== Streaming Jaeger deployment - -To use the `streaming` deployment strategy you create and configure your Jaeger instance first, then set `spec.addons.jaeger.name` to the name of the Jaeger instance, for example, `jaeger-streaming`. - -.Sample connection to an existing Jaeger instance -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: basic -spec: - version: v2.0 - tracing: - sampling: 10 - type: Jaeger - addons: - jaeger: - name: jaeger-streaming ----- diff --git a/modules/ossm-document-attributes-1x.adoc b/modules/ossm-document-attributes-1x.adoc deleted file mode 100644 index 680512e6be00..000000000000 --- a/modules/ossm-document-attributes-1x.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Standard document attributes to be used in the Service Mesh documentation -// -// The following are shared by all RHOSSM documents: -:toc: -:toclevels: 4 -:toc-title: -:experimental: -// -// Product content attributes, that is, substitution variables in the files. -// -:product-title: OpenShift Container Platform -:ProductName: Red Hat OpenShift Service Mesh -:ProductShortName: Service Mesh -:ProductRelease: -:ProductVersion: 1.1.12 -:MaistraVersion: 1.1 -:product-build: -:DownloadURL: registry.redhat.io -:cloud-redhat-com: Red Hat OpenShift Cluster Manager -:kebab: image:kebab.png[title="Options menu"] -// -// Documentation publishing attributes used in the master-docinfo.xml file -// Note that the DocInfoProductName generates the URL for the product page. -// Changing the value changes the generated URL. -// -:DocInfoProductName: OpenShift Service Mesh -:DocInfoProductNumber: 1.0 -// -// Book Names: -// Defining the book names in document attributes instead of hard-coding them in -// the master.adoc files and in link references. This makes it easy to change the -// book name if necessary. -// Using the pattern ending in 'BookName' makes it easy to grep for occurrences -// throughout the topics -// -:Install_BookName: Installing Red Hat OpenShift Service Mesh -:Using_BookName: Using Red Hat OpenShift Service Mesh -:RN_BookName: Red Hat OpenShift Service Mesh Release Notes diff --git a/modules/ossm-document-attributes.adoc b/modules/ossm-document-attributes.adoc deleted file mode 100644 index cf14fb9f4f6a..000000000000 --- a/modules/ossm-document-attributes.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Standard document attributes to be used in the Service Mesh documentation -// -// The following are shared by all RHOSSM documents: -:toc: -:toclevels: 4 -:toc-title: -:experimental: -// -// Product content attributes, that is, substitution variables in the files. -// -:product-title: OpenShift Container Platform -:ProductName: Red Hat OpenShift Service Mesh -:ProductShortName: Service Mesh -:ProductRelease: -:ProductVersion: 2.0.2 -:MaistraVersion: 2.0 -:product-build: -:DownloadURL: registry.redhat.io -:cloud-redhat-com: Red Hat OpenShift Cluster Manager -:kebab: image:kebab.png[title="Options menu"] -// -// Documentation publishing attributes used in the master-docinfo.xml file -// Note that the DocInfoProductName generates the URL for the product page. -// Changing the value changes the generated URL. -// -:DocInfoProductName: OpenShift Service Mesh -:DocInfoProductNumber: 2.0 -// -// Book Names: -// Defining the book names in document attributes instead of hard-coding them in -// the master.adoc files and in link references. This makes it easy to change the -// book name if necessary. -// Using the pattern ending in 'BookName' makes it easy to grep for occurrences -// throughout the topics -// -:Install_BookName: Installing Red Hat OpenShift Service Mesh -:Using_BookName: Using Red Hat OpenShift Service Mesh -:RN_BookName: Red Hat OpenShift Service Mesh Release Notes diff --git a/modules/ossm-enabling-jaeger.adoc b/modules/ossm-enabling-jaeger.adoc deleted file mode 100644 index 62158186f25d..000000000000 --- a/modules/ossm-enabling-jaeger.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/customizing-installation-ossm.adoc - - -[id="ossm-enabling-tracing_{context}"] -= Enabling and disabling tracing - -You enable tracing by specifying a tracing type and a sampling rate. - -.Default `all-in-one` Jaeger parameters -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: basic -spec: - version: v2.0 - tracing: - sampling: 100 - type: Jaeger ----- - -Currently the only tracing type that is supported is `Jaeger`. Jaeger is enabled by default. To disable tracing, set `type` to `None`. - -The sampling rate determines how often a trace is generated. You configure `sampling` as a scaled integer representing 0.01% increments. For example setting the value to `1` samples 0.01% of traces and a setting of `10000` samples 100% of traces. diff --git a/modules/ossm-install-kiali.adoc b/modules/ossm-install-kiali.adoc deleted file mode 100644 index 3d4ccc55a563..000000000000 --- a/modules/ossm-install-kiali.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc -// * service_mesh/v2x/installing-ossm.adoc - -[id="ossm-install-kiali_{context}"] -= Installing the Kiali Operator - -You must install the Kiali Operator for the {ProductName} Operator to install the control plane. - -[WARNING] -==== -Do not install Community versions of the Operators. Community Operators are not supported. -==== - - -.Prerequisites - -* Access to the {product-title} web console. - -.Procedure - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *OperatorHub*. - -. Type *Kiali* into the filter box to find the Kiali Operator. - -. Click the *Kiali Operator* provided by Red Hat to display information about the Operator. - -. Click *Install*. - -. On the *Operator Installation* page, select the *stable* Update Channel. - -. Select *All namespaces on the cluster (default)*. This installs the Operator in the default `openshift-operators` project and makes the Operator available to all projects in the cluster. - -. Select the *Automatic* Approval Strategy. -+ -[NOTE] -==== -The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. -==== - -. Click *Install*. - -. The *Installed Operators* page displays the Kiali Operator's installation progress. diff --git a/modules/ossm-install-ossm-operator.adoc b/modules/ossm-install-ossm-operator.adoc deleted file mode 100644 index 4c5d8bec1b9a..000000000000 --- a/modules/ossm-install-ossm-operator.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// - service_mesh/v1x/installing-ossm.adoc -// - service_mesh/v2x/installing-ossm.adoc - -[id="ossm-install-ossm-operator_{context}"] -= Installing the {ProductName} Operator - -.Prerequisites - -* Access to the {product-title} web console. -* The OpenShift Elasticsearch Operator must be installed. -* The Jaeger Operator must be installed. -* The Kiali Operator must be installed. - -.Procedure - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *OperatorHub*. - -. Type *{ProductName}* into the filter box to find the {ProductName} Operator. - -. Click the {ProductName} Operator to display information about the Operator. - -. Click *Install*. - -. On the *Operator Installation* page, select the *stable* Update Channel. - -. In the *Installation Mode* section, select *All namespaces on the cluster (default)*. This installs the Operator in the default `openshift-operators` project and makes the Operator available to all projects in the cluster. - -. Select the *Automatic* Approval Strategy. -+ -[NOTE] -==== -The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. -==== - -. Click *Install*. diff --git a/modules/ossm-installation-activities.adoc b/modules/ossm-installation-activities.adoc deleted file mode 100644 index 4a3e40f7562c..000000000000 --- a/modules/ossm-installation-activities.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/preparing-ossm-installation.adoc -// * service_mesh/v2x/preparing-ossm-installation.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="ossm-installation-activities_{context}"] -= {ProductName} installation activities - -To install the {ProductName} Operator, you must first install these Operators: - -* *Elasticsearch* - Based on the open source link:https://www.elastic.co/[Elasticsearch] project that enables you to configure and manage an Elasticsearch cluster for tracing and logging with Jaeger. -* *Jaeger* - based on the open source link:https://www.jaegertracing.io/[Jaeger] project, lets you perform tracing to monitor and troubleshoot transactions in complex distributed systems. -* *Kiali* - based on the open source link:https://www.kiali.io/[Kiali] project, provides observability for your service mesh. By using Kiali you can view configurations, monitor traffic, and view and analyze traces in a single console. - -After you install the OpenShift Elasticsearch, Jaeger, and Kiali Operators, then you install the {ProductName} Operator. The {ProductShortName} Operator defines and monitors the `ServiceMeshControlPlane` resources that manage the deployment, updating, and deletion of the {ProductShortName} components. - -* *{ProductName}* - based on the open source link:https://istio.io/[Istio] project, lets you connect, secure, control, and observe the microservices that make up your applications. diff --git a/modules/ossm-jaeger-config-elasticsearch-v1x.adoc b/modules/ossm-jaeger-config-elasticsearch-v1x.adoc deleted file mode 100644 index d978414fa2f8..000000000000 --- a/modules/ossm-jaeger-config-elasticsearch-v1x.adoc +++ /dev/null @@ -1,130 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-custom-resources.adoc - -[id="ossm-jaeger-config-elasticsearch-v1x_{context}"] -= Configuring Elasticsearch - -The default Jaeger deployment strategy uses the `all-in-one` template so that the installation can be completed using minimal resources. However, because the `all-in-one` template uses in-memory storage, it is only recommended for development, demo, or testing purposes and should NOT be used for production environments. - -If you are deploying {ProductShortName} and Jaeger in a production environment you must change the template to the `production-elasticsearch` template, which uses Elasticsearch for Jaeger's storage needs. - -Elasticsearch is a memory intensive application. The initial set of nodes specified in the default {product-title} installation may not be large enough to support the Elasticsearch cluster. You should modify the default Elasticsearch configuration to match your use case and the resources you have requested for your {product-title} installation. You can adjust both the CPU and memory limits for each component by modifying the resources block with valid CPU and memory values. Additional nodes must be added to the cluster if you want to run with the recommended amount (or more) of memory. Ensure that you do not exceed the resources requested for your {product-title} installation. - -.Default "production" Jaeger parameters with Elasticsearch -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - istio: - tracing: - enabled: true - ingress: - enabled: true - jaeger: - template: production-elasticsearch - elasticsearch: - nodeCount: 3 - redundancyPolicy: - resources: - requests: - cpu: "1" - memory: "16Gi" - limits: - cpu: "1" - memory: "16Gi" ----- - -.Elasticsearch parameters -[options="header"] -[cols="l, a, a, a, a"] -|=== -|Parameter |Description |Values |Default Value |Examples - -|tracing: - enabled: -|This parameter enables/disables tracing in {ProductShortName}. Jaeger is installed by default. -|`true`/`false` -|`true` -| - -|ingress: - enabled: -|This parameter enables/disables ingress for Jaeger. -|`true`/`false` -|`true` -| - -|jaeger: - template: -|This parameter specifies which Jaeger deployment strategy to use. -|`all-in-one`/`production-elasticsearch` -|`all-in-one` -| - -|elasticsearch: - nodeCount: -|Number of Elasticsearch nodes to create. -|Integer value. -|1 -|Proof of concept = 1, -Minimum deployment =3 - -|requests: - cpu: -|Number of central processing units for requests, based on your environment’s configuration. -|Specified in cores or millicores (for example, 200m, 0.5, 1). -|1Gi -|Proof of concept = 500m, -Minimum deployment =1 - -|requests: - memory: -|Available memory for requests, based on your environment’s configuration. -|Specified in bytes (for example, 200Ki, 50Mi, 5Gi). -|500m -|Proof of concept = 1Gi, -Minimum deployment = 16Gi* - -|limits: - cpu: -|Limit on number of central processing units, based on your environment’s configuration. -|Specified in cores or millicores (for example, 200m, 0.5, 1). -| -|Proof of concept = 500m, -Minimum deployment =1 - -|limits: - memory: -|Available memory limit based on your environment’s configuration. -|Specified in bytes (for example, 200Ki, 50Mi, 5Gi). -| -|Proof of concept = 1Gi, -Minimum deployment = 16Gi* - -| -4+|{asterisk} Each Elasticsearch node can operate with a lower memory setting though this is *not* recommended for production deployments. For production use, you should have no less than 16Gi allocated to each pod by default, but preferably allocate as much as you can, up to 64Gi per pod. -|=== - - -.Procedure - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Navigate to *Operators* -> *Installed Operators*. - -. Click the {ProductName} Operator. - -. Click the *Istio Service Mesh Control Plane* tab. - -. Click the name of your control plane file, for example, `basic-install`. - -. Click the *YAML* tab. - -. Edit the Jaeger parameters, replacing the default `all-in-one` template with parameters for the `production-elasticsearch` template, modified for your use case. Ensure that the indentation is correct. - -. Click *Save*. - -. Click *Reload*. -{product-title} redeploys Jaeger and creates the Elasticsearch resources based on the specified parameters. diff --git a/modules/ossm-jaeger-config-es-cleaner-v1x.adoc b/modules/ossm-jaeger-config-es-cleaner-v1x.adoc deleted file mode 100644 index a4e2963f519d..000000000000 --- a/modules/ossm-jaeger-config-es-cleaner-v1x.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-custom-resources.adoc - -[id="ossm-jaeger-config-es-cleaner-v1x_{context}"] -= Configuring the Elasticsearch index cleaner job - -When the {ProductShortName} Operator creates the `ServiceMeshControlPlane` it also creates the custom resource (CR) for Jaeger. The Jaeger operator then uses this CR when creating Jaeger instances. - -When using Elasticsearch storage, by default a job is created to clean old traces from it. To configure the options for this job, you edit the Jaeger custom resource (CR), to customize it for your use case. The relevant options are listed below. - -[source,yaml] ----- - apiVersion: jaegertracing.io/v1 - kind: Jaeger - spec: - strategy: production - storage: - type: elasticsearch - esIndexCleaner: - enabled: false - numberOfDays: 7 - schedule: "55 23 * * *" - ----- - -.Elasticsearch index cleaner parameters -|=== -|Parameter |Values |Description - -|enabled: -|true/ false -|Enable or disable the index cleaner job. - -|numberOfDays: -|integer value -|Number of days to wait before deleting an index. - -|schedule: -|"55 23 * * *" -|Cron expression for the job to run -|=== diff --git a/modules/ossm-jaeger-service-mesh.adoc b/modules/ossm-jaeger-service-mesh.adoc deleted file mode 100644 index 63be1c044f3f..000000000000 --- a/modules/ossm-jaeger-service-mesh.adoc +++ /dev/null @@ -1,18 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: --service_mesh/v1x/ossm-vs-community.adoc --service_mesh/v2x/ossm-vs-community.adoc -//// - -[id="ossm-jaeger-service-mesh_{context}"] -= Jaeger and service mesh - -Installing Jaeger with the Service Mesh on {product-title} differs from community Jaeger installations in multiple ways. These modifications are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on {product-title}. - -* Jaeger has been enabled by default for {ProductShortName}. -* Ingress has been enabled by default for {ProductShortName}. -* The name for the Zipkin port name has changed to `jaeger-collector-zipkin` (from `http`) -* Jaeger uses Elasticsearch for storage by default. -* The community version of Istio provides a generic "tracing" route. {ProductName} uses a "jaeger" route that is installed by the Jaeger operator and is already protected by OAuth. -* {ProductName} uses a sidecar for the Envoy proxy, and Jaeger also uses a sidecar, for the Jaeger agent. -These two sidecars are configured separately and should not be confused with each other. The proxy sidecar creates spans related to the pod's ingress and egress traffic. The agent sidecar receives the spans emitted by the application and sends them to the Jaeger Collector. diff --git a/modules/ossm-kiali-architecture.adoc b/modules/ossm-kiali-architecture.adoc deleted file mode 100644 index 486fd443609e..000000000000 --- a/modules/ossm-kiali-architecture.adoc +++ /dev/null @@ -1,26 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: --service_mesh/v1x/ossm-architecture.adoc --service_mesh/v2x/ossm-architecture.adoc -//// - -[id="ossm-kiali-architecture_{context}"] -= Kiali architecture - -Kiali is composed of two components: the Kiali application and the Kiali console. - -* *Kiali application* (back end) – This component runs in the container application platform and communicates with the service mesh components, retrieves and processes data, and exposes this data to the console. The Kiali application does not need storage. When deploying the application to a cluster, configurations are set in ConfigMaps and secrets. - -* *Kiali console* (front end) – The Kiali console is a web application. The Kiali application serves the Kiali console, which then queries the back end for data to present it to the user. - -In addition, Kiali depends on external services and components provided by the container application platform and Istio. - -* *Red Hat Service Mesh* (Istio) - Istio is a Kiali requirement. Istio is the component that provides and controls the service mesh. Although Kiali and Istio can be installed separately, Kiali depends on Istio and will not work if it is not present. Kiali needs to retrieve Istio data and configurations, which are exposed through Prometheus and the cluster API. - -* *Prometheus* - A dedicated Prometheus instance is included as part of the {ProductName} installation. When Istio telemetry is enabled, metrics data is stored in Prometheus. Kiali uses this Prometheus data to determine the mesh topology, display metrics, calculate health, show possible problems, and so on. Kiali communicates directly with Prometheus and assumes the data schema used by Istio Telemetry. Prometheus is an Istio dependency and a hard dependency for Kiali, and many of Kiali’s features will not work without Prometheus. - -* *Cluster API* - Kiali uses the API of the {product-title} (cluster API) to fetch and resolve service mesh configurations. Kiali queries the cluster API to retrieve, for example, definitions for namespaces, services, deployments, pods, and other entities. Kiali also makes queries to resolve relationships between the different cluster entities. The cluster API is also queried to retrieve Istio configurations like virtual services, destination rules, route rules, gateways, quotas, and so on. - -* *Jaeger* - Jaeger is optional, but is installed by default as part of the {ProductName} installation. When you install Jaeger as part of the default {ProductName} installation, the Kiali console includes a tab to display Jaeger’s tracing data. Note that tracing data will not be available if you disable Istio’s distributed tracing feature. Also note that user must have access to the namespace where the control plane is installed to view Jaeger data. - -* *Grafana* - Grafana is optional, but is installed by default as part of the {ProductName} installation. When available, the metrics pages of Kiali display links to direct the user to the same metric in Grafana. Note that user must have access to the namespace where the control plane is installed to view links to the Grafana dashboard and view Grafana data. diff --git a/modules/ossm-kiali-features.adoc b/modules/ossm-kiali-features.adoc deleted file mode 100644 index f2f08113f46a..000000000000 --- a/modules/ossm-kiali-features.adoc +++ /dev/null @@ -1,24 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: --service_mesh/v1x/ossm-architecture.adoc --service_mesh/v2x/ossm-architecture.adoc -//// - -[id="ossm-kiali-features_{context}"] -= Kiali features -//In the title include nouns or noun phrases that are used in the body text. -//Do not start the title of concept modules with a verb.. - -The Kiali console is integrated with Red Hat Service Mesh and provides the following capabilities: - -* *Health* – Quickly identify issues with applications, services, or workloads. - -* *Topology* – Visualize how your applications, services, or workloads communicate via the Kiali graph. - -* *Metrics* – Predefined metrics dashboards let you chart service mesh and application performance for Go, Node.js. Quarkus, Spring Boot, Thorntail and Vert.x. You can also create your own custom dashboards. - -* *Tracing* – Integration with Jaeger lets you follow the path of a request through various microservices that make up an application. - -* *Validations* – Perform advanced validations on the most common Istio objects (Destination Rules, Service Entries, Virtual Services, and so on). - -* *Configuration* – Optional ability to create, update and delete Istio routing configuration using wizards or directly in the YAML editor in the Kiali Console. diff --git a/modules/ossm-kiali-overview.adoc b/modules/ossm-kiali-overview.adoc deleted file mode 100644 index c21b0d239018..000000000000 --- a/modules/ossm-kiali-overview.adoc +++ /dev/null @@ -1,14 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: --service_mesh/v1x/ossm-architecture.adoc --service_mesh/v2x/ossm-architecture.adoc -//// - -[id="ossm-kiali-overview_{context}"] -= Kiali overview - -Kiali provides observability into the {ProductShortName} running on {product-title}. Kiali helps you define, validate, and observe your Istio service mesh. It helps you to understand the structure of your service mesh by inferring the topology, and also provides information about the health of your service mesh. - -Kiali provides an interactive graph view of your namespace in real time that provides visibility into features like circuit breakers, request rates, latency, and even graphs of traffic flows. Kiali offers insights about components at different levels, from Applications to Services and Workloads, and can display the interactions with contextual information and charts on the selected graph node or edge. Kiali also provides the ability to validate your Istio configurations, such as gateways, destination rules, virtual services, mesh policies, and more. Kiali provides detailed metrics, and a basic Grafana integration is available for advanced queries. Distributed tracing is provided by integrating Jaeger into the Kiali console. - -Kiali is installed by default as part of the {ProductName}. diff --git a/modules/ossm-kiali-service-mesh.adoc b/modules/ossm-kiali-service-mesh.adoc deleted file mode 100644 index 759082e2aeb7..000000000000 --- a/modules/ossm-kiali-service-mesh.adoc +++ /dev/null @@ -1,17 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: --service_mesh/v1x/ossm-vs-community.adoc --service_mesh/v2x/ossm-vs-community.adoc - -//// - -[id="ossm-kiali-service-mesh_{context}"] -= Kiali and service mesh - -Installing Kiali via the Service Mesh on {product-title} differs from community Kiali installations in multiple ways. These modifications are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on {product-title}. - -* Kiali has been enabled by default. -* Ingress has been enabled by default. -* Updates have been made to the Kiali ConfigMap. -* Updates have been made to the ClusterRole settings for Kiali. -* Users should not manually edit the ConfigMap or the Kiali custom resource files as those changes might be overwritten by the {ProductShortName} or Kiali operators. All configuration for Kiali running on {ProductName} is done in the `ServiceMeshControlPlane` custom resource file and there are limited configuration options. Updating the operator files should be restricted to those users with cluster-admin privileges. diff --git a/modules/ossm-load-test-results.adoc b/modules/ossm-load-test-results.adoc deleted file mode 100644 index de13995bc913..000000000000 --- a/modules/ossm-load-test-results.adoc +++ /dev/null @@ -1,75 +0,0 @@ -//// -This module included in the following assemblies: -- /v2x/ossm-performance-scalability.adoc -//// - -[id="ossm-load-test-results_{context}"] -= Load test results - -The upstream Istio community load tests mesh consists of *1000* services and *2000* sidecars with 70,000 mesh-wide requests per second. -Running the tests using Istio 1.6.8, generated the following results: - -* The Envoy proxy uses *0.5 vCPU* and *50 MB memory* per 1000 requests per second going through the proxy. -* Istiod uses *1 vCPU* and *1.5 GB* of memory. -* The Envoy proxy adds *3.12 ms* to the 90th percentile latency. -* The legacy `istio-telemetry` service (disabled by default in Service Mesh 2.0) uses *0.6 vCPU* per 1000 mesh-wide requests per second for deployments that use Mixer. -// TODO The Envoy numbers goes down in 1.9, check for the latest data with next version of Istio. -The data plane components, the Envoy proxies, handle data flowing through the system. The control plane component, Istiod, configures the data plane. The data plane and control plane have distinct performance concerns. - -== Control plane performance - -Istiod configures sidecar proxies based on user authored configuration files and the current state of the system. -In a Kubernetes environment, Custom Resource Definitions (CRDs) and deployments constitute the configuration and state of the system. -The Istio configuration objects like gateways and virtual services, provide the user-authored configuration. -To produce the configuration for the proxies, Istiod processes the combined configuration and system state from the Kubernetes environment and the user-authored configuration. - -The control plane supports thousands of services, spread across thousands of pods with a similar number of user authored virtual services and other configuration objects. -Istiod's CPU and memory requirements scale with the number of configurations and possible system states. -The CPU consumption scales with the following factors: - -* The rate of deployment changes. -* The rate of configuration changes. -* The number of proxies connecting to Istiod. - -However this part is inherently horizontally scalable. - -//Do we support namespace isolation? When namespace isolation is enabled, a single Istiod instance can support 1000 services, 2000 sidecars with 1 vCPU and 1.5 GB of memory. -//You can increase the number of Istiod instances to reduce the amount of time it takes for the configuration to reach all proxies. - -== Data plane performance - -Data plane performance depends on many factors, for example: - -* Number of client connections -* Target request rate -* Request size and response size -* Number of proxy worker threads -* Protocol -* CPU cores -* Number and types of proxy filters, specifically telemetry v2 related filters. - -The latency, throughput, and the proxies' CPU and memory consumption are measured as a function of these factors. - -=== CPU and memory consumption - -Since the sidecar proxy performs additional work on the data path, it consumes CPU and memory. As of Istio 1.1, a proxy consumes about 0.6 vCPU per 1000 requests per second. -//TODO As of Istio 1.7, a proxy consumes about 0.5 vCPU per 1000 requests per second. - -The memory consumption of the proxy depends on the total configuration state the proxy holds. -A large number of listeners, clusters, and routes can increase memory usage. -//Istio 1.1 introduced namespace isolation to limit the scope of the configuration sent to a proxy. In a large namespace, the proxy consumes approximately 50 MB of memory. - -Since the proxy normally doesn't buffer the data passing through, request rate doesn't affect the memory consumption. - -=== Additional latency - -Since Istio injects a sidecar proxy on the data path, latency is an important consideration. Istio adds an authentication filter, a telemetry filter, and a metadata exchange filter to the proxy. -Every additional filter adds to the path length inside the proxy and affects latency. - -The Envoy proxy collects raw telemetry data after a response is sent to the client. -The time spent collecting raw telemetry for a request does not contribute to the total time taken to complete that request. -However, since the worker is busy handling the request, the worker won't start handling the next request immediately. -This process adds to the queue wait time of the next request and affects average and tail latencies. -The actual tail latency depends on the traffic pattern. - -Inside the mesh, a request traverses the client-side proxy and then the server-side proxy. In the default configuration of Istio 1.6.8 (that is, Istio with telemetry v2), the two proxies add about 3.12 ms and 3.13 ms to the 90th and 99th percentile latency, respectively, over the baseline data plane latency. diff --git a/modules/ossm-member-roll-create.adoc b/modules/ossm-member-roll-create.adoc deleted file mode 100644 index b124c5247ae2..000000000000 --- a/modules/ossm-member-roll-create.adoc +++ /dev/null @@ -1,156 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc -// * service_mesh/v2x/installing-ossm.adoc - -[id="ossm-member-roll-create_{context}"] -= Creating the {ProductName} member roll - -The `ServiceMeshMemberRoll` lists the projects belonging to the control plane. Only projects listed in the `ServiceMeshMemberRoll` are affected by the control plane. A project does not belong to a service mesh until you add it to the member roll for a particular control plane deployment. - -You must create a `ServiceMeshMemberRoll` resource named `default` in the same project as the `ServiceMeshControlPlane`. - - -[NOTE] -==== -The member projects are only updated if the {ProductShortName} control plane installation succeeds. -==== - -[id="ossm-member-roll-create-console_{context}"] -== Creating the member roll from the web console - -Follow this procedure to add one or more projects to the {ProductShortName} member roll by using the web console. - -.Prerequisites -* An installed, verified {ProductName} Operator. -* Location of the installed `ServiceMeshControlPlane`. -* List of existing projects to add to the service mesh. - -.Procedure - -. If you do not already have projects for your mesh, or you are starting from scratch, create a project. It must be different from `istio-system`. - -.. Navigate to *Home* -> *Projects*. - -.. Enter a name in the *Name* field. - -.. Click *Create*. - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *Installed Operators*. - -. Click the *Project* menu and choose the project where your `ServiceMeshControlPlane` is deployed from the list, for example `istio-system`. - -. Click the {ProductName} Operator. - -. Click the *All Instances* tab. - -. Click *Create New*, and then select *Create Istio Service Mesh Member Roll*. - -+ -[NOTE] -==== -It can take a short time for the Operator to finish copying the resources, therefore you may need to refresh the screen to see the *Create Istio Service Mesh Member Roll* button. -==== - -. On the *Create Service Mesh Member Roll* page, modify the YAML to add your projects as members. You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource. - -. Click *Create* to save the Service Mesh Member Roll. - - -[id="ossm-member-roll-create-cli_{context}"] -== Creating the member roll from the CLI - -Follow this procedure to add a project to the `ServiceMeshMemberRoll` from the command line. - -.Prerequisites - -* An installed, verified {ProductName} Operator. -* Location of the installed `ServiceMeshControlPlane`. -* List of projects to add to the service mesh. -* Access to the OpenShift CLI (`oc`). - -.Procedure - -. Log in to the {product-title} CLI. -+ -[source,terminal] ----- -$ oc login ----- -+ -. Create a `ServiceMeshMemberRoll` resource in the same project as the `ServiceMeshControlPlane` resource, in our example that is `istio-system`. The resource must be named `default`. -+ -[source,terminal] ----- -$ oc create -n istio-system -f servicemeshmemberroll-default.yaml ----- -+ -.Example servicemeshmemberroll-default.yaml - -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshMemberRoll -metadata: - name: default - namespace: istio-system -spec: - members: - # a list of projects joined into the service mesh - - your-project-name - - another-project-name ----- -+ -. Modify the default YAML to add your projects as `members`. You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource. - -[id="ossm-member-roll-create-member_{context}"] -== Creating the {ProductName} members - -`ServiceMeshMember` resources can be created by service mesh users who don't have privileges to add members to the `ServiceMeshMemberRoll` directly. While project administrators are automatically given permission to create the `ServiceMeshMember` resource in their project, they cannot point it to any `ServiceMeshControlPlane` until the service mesh administrator explicitly grants access to the service mesh. Administrators can grant users permissions to access the mesh by granting them the `mesh-user` user role, for example: - ----- -$ oc policy add-role-to-user -n <control_plane_namespace> --role-namespace <control_plane_namespace> mesh-user <user_name>. ----- - -Administrators can modify the `mesh user` role binding in the control plane project to specify the users and groups that are granted access. The `ServiceMeshMember` adds the project to the `ServiceMeshMemberRoll` within the control plane project that it references. - -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshMember -metadata: - name: default -spec: - controlPlaneRef: - namespace: <control_plane_namespace> - name: minimal-install ----- - -The mesh-users role binding is created automatically after the administrator creates the `ServiceMeshControlPlane` resource. An administrator can use the following command to add a role to a user. - ----- -$ oc policy add-role-to-user ----- - -The administrator can also create the `mesh-user` role binding before the administrator creates the `ServiceMeshControlPlane` resource. For example, the administrator can create it in the same `oc apply` operation as the `ServiceMeshControlPlane` resource. - -This example adds a role binding for `alice`: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - namespace: <control_plane_namespace> - name: mesh-users -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: mesh-user -subjects: -- apiGroup: rbac.authorization.k8s.io - kind: User - name: alice ----- diff --git a/modules/ossm-member-roll-delete.adoc b/modules/ossm-member-roll-delete.adoc deleted file mode 100644 index 9a3f75620fa3..000000000000 --- a/modules/ossm-member-roll-delete.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc -// * service_mesh/v2x/installing-ossm.adoc - -[id="ossm-member-roll-delete_{context}"] -= Removing the {ProductName} member roll - -The `ServiceMeshMemberRoll` resource is automatically deleted when you delete the `ServiceMeshControlPlane` resource it is associated with. diff --git a/modules/ossm-member-roll-modify.adoc b/modules/ossm-member-roll-modify.adoc deleted file mode 100644 index 96585989e5fc..000000000000 --- a/modules/ossm-member-roll-modify.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc -// * service_mesh/v2x/installing-ossm.adoc - -[id="ossm-member-roll-modify_{context}"] -= Adding or removing projects from the service mesh - -Follow this procedure to modify an existing {ProductShortName} `ServiceMeshMemberRoll` resource using the web console. - -* You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource. - -* The `ServiceMeshMemberRoll` resource is deleted when its corresponding `ServiceMeshControlPlane` resource is deleted. - -[id="ossm-member-roll-modify-console_{context}"] -== Modifying the member roll from the web console - -.Prerequisites -* An installed, verified {ProductName} Operator. -* An existing `ServiceMeshMemberRoll` resource. -* Name of the project with the `ServiceMeshMemberRoll` resource. -* Names of the projects you want to add or remove from the mesh. - -.Procedure - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *Installed Operators*. - -. Click the *Project* menu and choose the project where your `ServiceMeshControlPlane` is deployed from the list, for example `istio-system`. - -. Click the {ProductName} Operator. - -. Click the *Istio Service Mesh Member Roll* tab. - -. Click the `default` link. - -. Click the YAML tab. - -. Modify the YAML to add or remove projects as members. You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource. - -. Click *Save*. - -. Click *Reload*. - -[id="ossm-member-roll-modify-cli_{context}"] -== Modifying the member roll from the CLI - -Follow this procedure to modify an existing {ProductShortName} member roll using the command line. - -.Prerequisites - -* An installed, verified {ProductName} Operator. -* An existing `ServiceMeshMemberRoll` resource. -* Name of the project with the `ServiceMeshMemberRoll` resource. -* Names of the projects you want to add or remove from the mesh. -* Access to the OpenShift CLI (`oc`). - - -.Procedure - -. Log in to the {product-title} CLI. - -. Edit the `ServiceMeshMemberRoll` resource. -+ -[source,terminal] ----- -$ oc edit smmr -n <controlplane-namespace> ----- -+ - -. Modify the YAML to add or remove projects as members. You can add any number of projects, but a project can only belong to *one* `ServiceMeshMemberRoll` resource. - -+ -.Example servicemeshmemberroll-default.yaml - -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshMemberRoll -metadata: - name: default - namespace: istio-system -spec: - members: - # a list of projects joined into the service mesh - - your-project-name - - another-project-name ----- diff --git a/modules/ossm-mixer-policy-1x.adoc b/modules/ossm-mixer-policy-1x.adoc deleted file mode 100644 index f38d566eb3b3..000000000000 --- a/modules/ossm-mixer-policy-1x.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc - -[id="ossm-mixer-policy-1x_{context}"] -= Updating Mixer policy enforcement - -In previous versions of {ProductName}, Mixer’s policy enforcement was enabled by default. Mixer policy enforcement is now disabled by default. You must enable it before running policy tasks. - -.Prerequisites -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - - -.Procedure - -. Log in to the {product-title} CLI. - -. Run this command to check the current Mixer policy enforcement status: -+ -[source,terminal] ----- -$ oc get cm -n istio-system istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks ----- - -. If `disablePolicyChecks: true`, edit the {ProductShortName} ConfigMap: -+ -[source,terminal] ----- -$ oc edit cm -n istio-system istio ----- - -. Locate `disablePolicyChecks: true` within the ConfigMap and change the value to `false`. - -. Save the configuration and exit the editor. - -. Re-check the Mixer policy enforcement status to ensure it is set to `false`. diff --git a/modules/ossm-mixer-policy.adoc b/modules/ossm-mixer-policy.adoc deleted file mode 100644 index da6ce049e9aa..000000000000 --- a/modules/ossm-mixer-policy.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc - -[id="ossm-mixer-policy_{context}"] -= Updating Mixer policy enforcement - -In previous versions of {ProductName}, Mixer’s policy enforcement was enabled by default. Mixer policy enforcement is now disabled by default. You must enable it before running policy tasks. - -.Prerequisites -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - - -.Procedure - -. Log in to the {product-title} CLI. - -. Run this command to check the current Mixer policy enforcement status: -+ -[source,terminal] ----- -$ oc get cm -n istio-system istio -o jsonpath='{.data.mesh}' | grep disablePolicyChecks ----- - -. If `disablePolicyChecks: true`, edit the {ProductShortName} ConfigMap: -+ -[source,terminal] ----- -$ oc edit cm -n istio-system istio ----- - -. Locate `disablePolicyChecks: true` within the ConfigMap and change the value to `false`. - -. Save the configuration and exit the editor. - -. Re-check the Mixer policy enforcement status to ensure it is set to `false`. diff --git a/modules/ossm-multitenant.adoc b/modules/ossm-multitenant.adoc deleted file mode 100644 index fa3494dc54e0..000000000000 --- a/modules/ossm-multitenant.adoc +++ /dev/null @@ -1,41 +0,0 @@ -//// -Module included in the following assemblies: --ossm-vs-community.adoc -//// - -[id="ossm-multitenant-install_{context}"] -= {ProductName} multitenant installation - -Whereas upstream Istio takes a single tenant approach, {ProductName} supports multiple independent control planes within the cluster. {ProductName} uses a multitenant operator to manage the control plane lifecycle. - -{ProductName} installs a multitenant control plane by default. You specify the projects that can access the {ProductShortName}, and isolate the {ProductShortName} from other control plane instances. - -[id="ossm-mt-vs-clusterwide_{context}"] -== Multitenancy versus cluster-wide installations - -The main difference between a multitenant installation and a cluster-wide installation is the scope of privileges used by the control plane deployments, for example, Galley and Pilot. The components no longer use cluster-scoped Role Based Access Control (RBAC) resource `ClusterRoleBinding`. - -Every project in the `ServiceMeshMemberRoll` `members` list will have a `RoleBinding` for each service account associated with the control plane deployment and each control plane deployment will only watch those member projects. Each member project has a `maistra.io/member-of` label added to it, where the `member-of` value is the project containing the control plane installation. - -{ProductName} configures each member project to ensure network access between itself, the control plane, and other member projects. The exact configuration differs depending on how OpenShift software-defined networking (SDN) is configured. See About OpenShift SDN for additional details. - -If the {product-title} cluster is configured to use the SDN plug-in: - -* *`NetworkPolicy`*: {ProductName} creates a `NetworkPolicy` resource in each member project allowing ingress to all pods from the other members and the control plane. If you remove a member from {ProductShortName}, this `NetworkPolicy` resource is deleted from the project. -+ -[NOTE] -==== -This also restricts ingress to only member projects. If you require ingress from non-member projects, you need to create a `NetworkPolicy` to allow that traffic through. -==== - -* *Multitenant*: {ProductName} joins the `NetNamespace` for each member project to the `NetNamespace` of the control plane project (the equivalent of running `oc adm pod-network join-projects --to control-plane-project member-project`). If you remove a member from the {ProductShortName}, its `NetNamespace` is isolated from the control plane (the equivalent of running `oc adm pod-network isolate-projects member-project`). - -* *Subnet*: No additional configuration is performed. - -[id="ossm-cluster-scoped-resources_{context}"] -== Cluster scoped resources - -Upstream Istio has two cluster scoped resources that it relies on. The `MeshPolicy` and the `ClusterRbacConfig`. These are not compatible with a multitenant cluster and have been replaced as described below. - -* _ServiceMeshPolicy_ replaces MeshPolicy for configuration of control-plane-wide authentication policies. This must be created in the same project as the control plane. -* _ServicemeshRbacConfig_ replaces ClusterRbacConfig for configuration of control-plane-wide role based access control. This must be created in the same project as the control plane. diff --git a/modules/ossm-observability-access.adoc b/modules/ossm-observability-access.adoc deleted file mode 100644 index 4b59ef41f4b8..000000000000 --- a/modules/ossm-observability-access.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -//* service_mesh/v1x/ossm-observability.adoc -//* service_mesh/v2x/ossm-observability.adoc - -[id="ossm-observability-access-console_{context}"] -= Accessing the Kiali console - -To access the Kiali console you must have {ProductName} installed and projects configured for the service mesh. - -.For administrators - -1. Use the perspective switcher to switch to the Administrator perspective. - -2. Click *Home* > *Overview*. - -3. In the Launcher section, click `Open on Kiali`. - -4. Log in to the Kiali console with the same user name and password as you use to access the {product-title} console. - -.For developers - -1. Use the perspective switcher to switch to the Developer perspective. - -2. Click *Topology*. - -3. Click `Kiali` from a node in the topology you have configured for the service mesh. Or click the *Kiali* link in the toolbar. - -4. Log in to the Kiali console with the same user name and password as you use to access the {product-title} console. - -.Procedure from the command line - -. Run this command from the CLI to obtain the route and Kiali URL: -+ -[source,terminal] ----- -$ oc get routes ----- -+ -In the output on the `kiali` line, use the URL in the HOST/PORT column to open the Kiali console. Log in to the Kiali console with the same user name and password as you use to access the {product-title} console. Select the project for your service in the *Namespace* field. - -When you first log in to the Kiali Console, you see the Overview page which displays all the namespaces in your mesh that you have permission to view. diff --git a/modules/ossm-observability-visual.adoc b/modules/ossm-observability-visual.adoc deleted file mode 100644 index 1c7fe1e63e56..000000000000 --- a/modules/ossm-observability-visual.adoc +++ /dev/null @@ -1,34 +0,0 @@ -//// -This module is included in the following assemblies: -* service_mesh/v1x/ossm-observability.adoc -* service_mesh/v2x/ossm-observability.adoc -//// - -[id="ossm-observability-visual_{context}"] -= Visualizing your service - -The Kiali operator works with the telemetry data gathered in {ProductName} to provide graphs and real time network diagrams of the applications, services, and workloads in your namespace. - -The Overview page displays all the namespaces that have services in your mesh. You can reveal deeper insights about the data traveling through your Service mesh or help identify problems with services or workloads in your service mesh with the following graphs and visualizations. - -[id="ossm-observability-topology_{context}"] -== Namespace graphs - -The namespace graph is a map of the services, deployments and workflows in your namespace and arrows that show how data flows through them. To view a namespace graph: - -1. Click *Graph* in the main navigation. -+ -2. Select `bookinfo` from the *Namespace* menu. - - -If your application uses version tags, like the Bookinfo sample application, you can see a Version graph. Select a graph from the Graph Type drop down menu. There are several graphs to choose from: - -* The App graph shows an aggregate workload for all applications that are labeled the same. - -* The Versioned App graph shows a node for each version of an app. All versions of an app are grouped together. - -* The Workload graph shows a node for each workload in your service mesh. This graph does not require you to use the app and version labels. If your app does not use version labels, use this the graph. - -* The Service graph shows a node for each service in your mesh but excludes all apps and workloads from the graph. It provides a high level view and aggregates all traffic for defined services. - -To view a summary of metrics, select any node or edge in the graph to display its metric details in the summary details panel. diff --git a/modules/ossm-recommended-resources.adoc b/modules/ossm-recommended-resources.adoc deleted file mode 100644 index 73b0f4384974..000000000000 --- a/modules/ossm-recommended-resources.adoc +++ /dev/null @@ -1,40 +0,0 @@ -//// -This module included in the following assemblies: -- /v2x/ossm-performance-scalability.adoc -//// - -[id="ossm-recommended-resources_{context}"] -= Recommended compute resources - -By default, `spec.proxy` has the settings `cpu:10m` and `memory:128M`. If you are using Pilot, `spec.runtime.components.pilot` has the same default values. -The settings in the following example are based on 1,000 services and 1,000 requests per second. You can change the values for `cpu` and `memory` as necessary based on your environment. - -.Example version 2.0 ServiceMeshControlPlane -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: basic - namespace: istio-system -spec: - version: v2.0 - proxy: - runtime: - container: - resources: - requests: - cpu: 600m - memory: 50Mi - limits: {} - - runtime: - components: - pilot: - container: - resources: - requests: - cpu: 1000m - memory: 1.6Gi - limits: {} ----- diff --git a/modules/ossm-remove-cleanup-1x.adoc b/modules/ossm-remove-cleanup-1x.adoc deleted file mode 100644 index 49092be446b3..000000000000 --- a/modules/ossm-remove-cleanup-1x.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc - - -[id="ossm-remove-cleanup-1x_{context}"] -= Clean up Operator resources - -Follow this procedure to manually remove resources left behind after removing the {ProductName} Operator using the OpenShift console. - -.Prerequisites - -* An account with cluster administration access. -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - -.Procedure - -. Log in to the {product-title} CLI as a cluster administrator. - -. Run the following commands to clean up resources after uninstalling the Operators. If you intend to keep using Jaeger as a stand alone service without service mesh, do not delete the Jaeger resources. -+ -[NOTE] -==== -The Operators are installed in the `openshift-operators` namespace by default. If you installed the Operators in another namespace, replace `openshift-operators` with the name of the project where the {ProductName} Operator was installed. -==== -+ -[source,terminal] ----- -$ oc delete validatingwebhookconfiguration/openshift-operators.servicemesh-resources.maistra.io ----- -+ -[source,terminal] ----- -$ oc delete mutatingwebhookconfigurations/openshift-operators.servicemesh-resources.maistra.io ----- -+ -[source,terminal] ----- -$ oc delete -n openshift-operators daemonset/istio-node ----- -+ -[source,terminal] ----- -$ oc delete clusterrole/istio-admin clusterrole/istio-cni clusterrolebinding/istio-cni ----- -// needs a slash? What is the format here? -+ -[source,terminal] ----- -$ oc delete clusterrole istio-view istio-edit ----- -+ -[source,terminal] ----- -$ oc delete clusterrole jaegers.jaegertracing.io-v1-admin jaegers.jaegertracing.io-v1-crdview jaegers.jaegertracing.io-v1-edit jaegers.jaegertracing.io-v1-view ----- -+ -[source,terminal] ----- -$ oc get crds -o name | grep '.*\.istio\.io' | xargs -r -n 1 oc delete ----- -+ -[source,terminal] ----- -$ oc get crds -o name | grep '.*\.maistra\.io' | xargs -r -n 1 oc delete ----- -+ -[source,terminal] ----- -$ oc get crds -o name | grep '.*\.kiali\.io' | xargs -r -n 1 oc delete ----- -+ -[source,terminal] ----- -$ oc delete crds jaegers.jaegertracing.io ----- -+ -[source,terminal] ----- -$ oc delete svc admission-controller -n <operator-project> ----- -+ -[source,terminal] ----- -$ oc delete project <istio-system-project> ----- diff --git a/modules/ossm-remove-cleanup.adoc b/modules/ossm-remove-cleanup.adoc deleted file mode 100644 index 847557d9e055..000000000000 --- a/modules/ossm-remove-cleanup.adoc +++ /dev/null @@ -1,90 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/installing-ossm.adoc - - -[id="ossm-remove-cleanup_{context}"] -= Clean up Operator resources - -Follow this procedure to manually remove resources left behind after removing the {ProductName} Operator using the OpenShift console. - -.Prerequisites - -* An account with cluster administration access. -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - -.Procedure - -. Log in to the {product-title} CLI as a cluster administrator. - -. Run the following commands to clean up resources after uninstalling the Operators. If you intend to keep using Jaeger as a stand alone service without service mesh, do not delete the Jaeger resources. -+ -[NOTE] -==== -The Operators are installed in the `openshift-operators` namespace by default. If you installed the Operators in another namespace, replace `openshift-operators` with the name of the project where the {ProductName} Operator was installed. -==== -+ -[source,terminal] ----- -$ oc delete validatingwebhookconfiguration/openshift-operators.servicemesh-resources.maistra.io ----- -+ -[source,terminal] ----- -$ oc delete mutatingwebhookconfigurations/openshift-operators.servicemesh-resources.maistra.io ----- -+ -[source,terminal] ----- -$ oc delete svc maistra-admission-controller -n openshift-operators ----- -+ -[source,terminal] ----- -$ oc delete -n openshift-operators daemonset/istio-node ----- -+ -[source,terminal] ----- -$ oc delete clusterrole/istio-admin clusterrole/istio-cni clusterrolebinding/istio-cni ----- -+ -[source,terminal] ----- -$ oc delete clusterrole istio-view istio-edit ----- -+ -[source,terminal] ----- -$ oc delete clusterrole jaegers.jaegertracing.io-v1-admin jaegers.jaegertracing.io-v1-crdview jaegers.jaegertracing.io-v1-edit jaegers.jaegertracing.io-v1-view ----- -+ -[source,terminal] ----- -$ oc get crds -o name | grep '.*\.istio\.io' | xargs -r -n 1 oc delete ----- -+ -[source,terminal] ----- -$ oc get crds -o name | grep '.*\.maistra\.io' | xargs -r -n 1 oc delete ----- -+ -[source,terminal] ----- -$ oc get crds -o name | grep '.*\.kiali\.io' | xargs -r -n 1 oc delete ----- -+ -[source,terminal] ----- -$ oc delete crds jaegers.jaegertracing.io ----- -+ -[source,terminal] ----- -$ oc delete secret -n openshift-operators maistra-operator-serving-cert ----- -+ -[source,terminal] ----- -$ oc delete cm -n openshift-operators maistra-operator-cabundle ----- diff --git a/modules/ossm-remove-operators.adoc b/modules/ossm-remove-operators.adoc deleted file mode 100644 index a242d0abb1a9..000000000000 --- a/modules/ossm-remove-operators.adoc +++ /dev/null @@ -1,110 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc -// * service_mesh/v2x/installing-ossm.adoc - -[id="ossm-operatorhub-remove-operators_{context}"] -= Removing the installed Operators - -You must remove the Operators to successfully remove {ProductName}. Once you remove the {ProductName} Operator, you must remove the Kiali Operator, the Jaeger Operator, and the OpenShift Elasticsearch Operator. - -[id="ossm-remove-operator-servicemesh_{context}"] -== Removing the {ProductName} Operator - -Follow this procedure to remove the {ProductName} Operator. - -.Prerequisites - -* Access to the {product-title} web console. -* The {ProductName} Operator must be installed. - -.Procedure - -. Log in to the {product-title} web console. - -. From the *Operators* → *Installed Operators* page, scroll or type a keyword into the *Filter by name* to find the {ProductName} Operator. Then, click on it. - -. On the right-hand side of the *Operator Details* page, select *Uninstall Operator* from the *Actions* drop-down menu. - -. When prompted by the *Remove Operator Subscription* window, optionally select the -*Also completely remove the Operator from the selected namespace* -check box if you want all components related to the installation to be removed. -This removes the CSV, which in turn removes the pods, Deployments, CRDs, and CRs associated with the Operator. - -[id="ossm-remove-operator-kiali_{context}"] -== Removing the Kiali Operator - -Follow this procedure to remove the Kiali Operator. - -.Prerequisites - -* Access to the {product-title} web console. -* The Kiali Operator must be installed. - -.Procedure - -. Log in to the {product-title} web console. - -. From the *Operators* → *Installed Operators* page, scroll or type a keyword into -the *Filter by name* to find the Kiali Operator. Then, click on it. - -. On the right-hand side of the *Operator Details* page, select *Uninstall -Operator* from the *Actions* drop-down menu. - -. When prompted by the *Remove Operator Subscription* window, optionally select the -*Also completely remove the Operator from the selected namespace* -check box if you want all components related to the installation to be removed. -This removes the CSV, which in turn removes the pods, Deployments, CRDs, and CRs -associated with the Operator. - -[id="ossm-remove-operator-jaeger_{context}"] -== Removing the Jaeger Operator - -Follow this procedure to remove the Jaeger Operator. - -.Prerequisites - -* Access to the {product-title} web console. -* The Jaeger Operator must be installed. - -.Procedure - -. Log in to the {product-title} web console. - -. From the *Operators* → *Installed Operators* page, scroll or type a keyword into -the *Filter by name* to find the Jaeger Operator. Then, click on it. - -. On the right-hand side of the *Operator Details* page, select *Uninstall -Operator* from the *Actions* drop-down menu. - -. When prompted by the *Remove Operator Subscription* window, optionally select the -*Also completely remove the Operator from the selected namespace* -check box if you want all components related to the installation to be removed. -This removes the CSV, which in turn removes the pods, Deployments, CRDs, and CRs -associated with the Operator. - -[id="ossm-remove-operator-elasticsearch_{context}"] -== Removing the OpenShift Elasticsearch Operator - -Follow this procedure to remove the OpenShift Elasticsearch Operator. - -.Prerequisites - -* Access to the {product-title} web console. -* The OpenShift Elasticsearch Operator must be installed. - -.Procedure - -. Log in to the {product-title} web console. - -. From the *Operators* → *Installed Operators* page, scroll or type a keyword into -the *Filter by name* to find the OpenShift Elasticsearch Operator. Then, click on it. - -. On the right-hand side of the *Operator Details* page, select *Uninstall -Operator* from the *Actions* drop-down menu. - -. When prompted by the *Remove Operator Subscription* window, optionally select the -*Also completely remove the Operator from the selected namespace* -check box if you want all components related to the installation to be removed. -This removes the CSV, which in turn removes the pods, Deployments, CRDs, and CRs -associated with the Operator. diff --git a/modules/ossm-rn-deprecated-features-1x.adoc b/modules/ossm-rn-deprecated-features-1x.adoc deleted file mode 100644 index 22fbeb4d64c9..000000000000 --- a/modules/ossm-rn-deprecated-features-1x.adoc +++ /dev/null @@ -1,35 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v1x/servicemesh-release-notes.adoc -//// - -[id="ossm-deprecated-features-1x_{context}"] -//// -Description - Description of the any features (including technology previews) that have been removed from the product. Write the description from a customer perspective, what UI elements, commands, or options are no longer available. -Consequence or a recommended replacement - Description of what the customer can no longer do, and recommended replacement (if known). -//// -= Deprecated features -Some features available in previous releases have been deprecated or removed. - -Deprecated functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. - -== Deprecated features {ProductName} 1.1.5 - -The following custom resources were deprecated in release 1.1.5 and were removed in release 1.1.12 - -* `Policy` - The `Policy` resource is deprecated and will be replaced by the `PeerAuthentication` resource in a future release. -* `MeshPolicy` - The `MeshPolicy` resource is deprecated and will be replaced by the `PeerAuthentication` resource in a future release. -* `v1alpha1` RBAC API -The v1alpha1 RBAC policy is deprecated by the v1beta1 `AuthorizationPolicy`. RBAC (Role Based Access Control) defines `ServiceRole` and `ServiceRoleBinding` objects. -** `ServiceRole` -** `ServiceRoleBinding` -* `RbacConfig` - `RbacConfig` implements the Custom Resource Definition for controlling Istio RBAC behavior. -** `ClusterRbacConfig`(versions prior to {ProductName} 1.0) -** `ServiceMeshRbacConfig` ({ProductName} version 1.0 and later) -* In Kiali, the `login` and `LDAP` strategies are deprecated. A future version will introduce authentication using OpenID providers. - -The following components are also deprecated in this release and will be replaced by the *Istiod* component in a future release. - -* *Mixer* - access control and usage policies -* *Pilot* - service discovery and proxy configuration -* *Citadel* - certificate generation -* *Galley* - configuration validation and distribution diff --git a/modules/ossm-rn-deprecated-features.adoc b/modules/ossm-rn-deprecated-features.adoc deleted file mode 100644 index 8220ca5edb67..000000000000 --- a/modules/ossm-rn-deprecated-features.adoc +++ /dev/null @@ -1,33 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v2x/servicemesh-release-notes.adoc -//// - -[id="ossm-deprecated-features_{context}"] -//// -Description - Description of the any features (including technology previews) that have been removed from the product. Write the description from a customer perspective, what UI elements, commands, or options are no longer available. -Consequence or a recommended replacement - Description of what the customer can no longer do, and recommended replacement (if known). -//// -= Deprecated features -Some features available in previous releases have been deprecated or removed. - -Deprecated functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. - -== Deprecated features {ProductName} 2.0 - -The Mixer component was deprecated in release 2.0 and will be removed in release 2.1. While using Mixer for implementing extensions was still supported in release 2.0, extensions should have been migrated to the new link:https://istio.io/latest/blog/2020/wasm-announce/[WebAssembly] mechanism. - -The following resource types are no longer supported in {ProductName} 2.0: - -* `Policy` (authentication.istio.io/v1alpha1) is no longer supported. Depending on the specific configuration in your Policy resource, you may have to configure multiple resources to achieve the same effect. -** Use `RequestAuthentication` (security.istio.io/v1beta1) -** Use `PeerAuthentication` (security.istio.io/v1beta1) -* `ServiceMeshPolicy` (maistra.io/v1) is no longer supported. -** Use `RequestAuthentication` or `PeerAuthentication`, as mentioned above, but place in the control plane namespace. -* `RbacConfig` (rbac.istio.io/v1alpha1) is no longer supported. -** Replaced by `AuthorizationPolicy` (security.istio.io/v1beta1), which encompasses behavior of `RbacConfig`, `ServiceRole`, and `ServiceRoleBinding`. -* `ServiceMeshRbacConfig` (maistra.io/v1) is no longer supported. -** Use `AuthorizationPolicy` as above, but place in control plane namespace. -* `ServiceRole` (rbac.istio.io/v1alpha1) is no longer supported. -* `ServiceRoleBinding` (rbac.istio.io/v1alpha1) is no longer supported. -* In Kiali, the `login` and `LDAP` strategies are deprecated. A future version will introduce authentication using OpenID providers. diff --git a/modules/ossm-rn-fixed-issues-1x.adoc b/modules/ossm-rn-fixed-issues-1x.adoc deleted file mode 100644 index 6274c685fc24..000000000000 --- a/modules/ossm-rn-fixed-issues-1x.adoc +++ /dev/null @@ -1,70 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v1x/servicemesh-release-notes.adoc -//// - -[id="ossm-rn-fixed-issues-1x_{context}"] -= Fixed issues - -//// -Provide the following info for each issue if possible: -Consequence - What user action or situation would make this problem appear (If you have the foo option enabled and did x)? What did the customer experience as a result of the issue? What was the symptom? -Cause - Why did this happen? -Fix - What did we change to fix the problem? -Result - How has the behavior changed as a result? Try to avoid “It is fixed” or “The issue is resolved” or “The error no longer presents”. -//// - -The following issues been resolved in the current release: - -[id="ossm-rn-fixed-issues-ossm_{context}"] -== {ProductShortName} fixed issues - -* link:https://issues.jboss.org/browse/OSSM-99[OSSM-99] Workloads generated from direct Pod without labels may crash Kiali. - -* link:https://issues.jboss.org/browse/OSSM-93[OSSM-93] IstioConfigList can't filter by two or more names. - -* link:https://issues.jboss.org/browse/OSSM-92[OSSM-92] Cancelling unsaved changes on the VS/DR YAML edit page does not cancel the changes. - -* link:https://issues.jboss.org/browse/OSSM-90[OSSM-90] Traces not available on the service details page. - -[id="ossm-rn-fixed-issues-maistra_{context}"] -* link:https://issues.redhat.com/projects/MAISTRA/issues/MAISTRA-1649[MAISTRA-1649] Headless services conflict when in different namespaces. When deploying headless services within different namespaces the endpoint configuration is merged and results in invalid Envoy configurations being pushed to the sidecars. - -* link:https://issues.redhat.com/browse/MAISTRA-1541[MAISTRA-1541] Panic in kubernetesenv when the controller is not set on owner reference. If a pod has an ownerReference which does not specify the controller, this will cause a panic within the `kubernetesenv cache.go` code. - -* link:https://issues.redhat.com/browse/MAISTRA-1352[MAISTRA-1352] Cert-manager Custom Resource Definitions (CRD) from the control plane installation have been removed for this release and future releases. If you have already installed {ProductName}, the CRDs must be removed manually if cert-manager is not being used. - -* link:https://issues.jboss.org/browse/MAISTRA-1001[MAISTRA-1001] Closing HTTP/2 connections could lead to segmentation faults in `istio-proxy`. - -* link:https://issues.jboss.org/browse/MAISTRA-932[MAISTRA-932] Added the `requires` metadata to add dependency relationship between Jaeger operator and OpenShift Elasticsearch Operator. Ensures that when the Jaeger operator is installed, it automatically deploys the OpenShift Elasticsearch Operator if it is not available. - -* link:https://issues.jboss.org/browse/MAISTRA-862[MAISTRA-862] Galley dropped watches and stopped providing configuration to other components after many namespace deletions and re-creations. - -* link:https://issues.jboss.org/browse/MAISTRA-833[MAISTRA-833] Pilot stopped delivering configuration after many namespace deletions and re-creations. - -* link:https://issues.jboss.org/browse/MAISTRA-684[MAISTRA-684] The default Jaeger version in the `istio-operator` is 1.12.0, which does not match Jaeger version 1.13.1 that shipped in {ProductName} 0.12.TechPreview. - -* link:https://issues.jboss.org/browse/MAISTRA-622[MAISTRA-622] In Maistra 0.12.0/TP12, permissive mode does not work. The user has the option to use Plain text mode or Mutual TLS mode, but not permissive. - -* link:https://issues.jboss.org/browse/MAISTRA-572[MAISTRA-572] Jaeger cannot be used with Kiali. In this release Jaeger is configured to use the OAuth proxy, but is also only configured to work through a browser and does not allow service access. Kiali cannot properly communicate with the Jaeger endpoint and it considers Jaeger to be disabled. See also link:https://issues.jboss.org/browse/TRACING-591[TRACING-591]. - -* link:https://issues.jboss.org/browse/MAISTRA-357[MAISTRA-357] In OpenShift 4 Beta on AWS, it is not possible, by default, to access a TCP or HTTPS service through the ingress gateway on a port other than port 80. The AWS load balancer has a health check that verifies if port 80 on the service endpoint is active. Without a service running on port 80, the load balancer health check fails. - -* link:https://issues.jboss.org/browse/MAISTRA-348[MAISTRA-348] OpenShift 4 Beta on AWS does not support ingress gateway traffic on ports other than 80 or 443. If you configure your ingress gateway to handle TCP traffic with a port number other than 80 or 443, you have to use the service hostname provided by the AWS load balancer rather than the OpenShift router as a workaround. - -* link:https://issues.jboss.org/browse/MAISTRA-193[MAISTRA-193] Unexpected console info messages are visible when health checking is enabled for citadel. - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1821432[Bug 1821432] Toggle controls in {product-title} Control Resource details page do not update the CR correctly. UI Toggle controls in the Service Mesh Control Plane (SMCP) Overview page in the {product-title} web console sometimes update the wrong field in the resource. To update a ServiceMeshControlPlane resource, edit the YAML content directly or update the resource from the command line instead of clicking the toggle controls. - -[id="ossm-rn-fixed-issues-kiali_{context}"] -== Kiali fixed issues - -* link:https://issues.jboss.org/browse/KIALI-3239[KIALI-3239] If a Kiali Operator pod has failed with a status of “Evicted” it blocks the Kiali operator from deploying. The workaround is to delete the Evicted pod and redeploy the Kiali operator. - -* link:https://issues.jboss.org/browse/KIALI-3118[KIALI-3118] After changes to the ServiceMeshMemberRoll, for example adding or removing projects, the Kiali pod restarts and then displays errors on the Graph page while the Kiali pod is restarting. - -* link:https://issues.jboss.org/browse/KIALI-3096[KIALI-3096] Runtime metrics fail in {ProductShortName}. There is an OAuth filter between the {ProductShortname} and Prometheus, requiring a bearer token to be passed to Prometheus before access is granted. Kiali has been updated to use this token when communicating to the Prometheus server, but the application metrics are currently failing with 403 errors. - -* link:https://issues.jboss.org/browse/KIALI-3070[KIALI-3070] This bug only affects custom dashboards, not the default dashboards. When you select labels in metrics settings and refresh the page, your selections are retained in the menu but your selections are not displayed on the charts. - -* link:https://github.com/kiali/kiali/issues/1603[KIALI-2686] When the control plane has many namespaces, it can lead to performance issues. diff --git a/modules/ossm-rn-fixed-issues.adoc b/modules/ossm-rn-fixed-issues.adoc deleted file mode 100644 index c7bb65e54ff1..000000000000 --- a/modules/ossm-rn-fixed-issues.adoc +++ /dev/null @@ -1,56 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v2x/servicemesh-release-notes.adoc -//// - -[id="ossm-rn-fixed-issues_{context}"] -= Fixed issues - -//// -Provide the following info for each issue if possible: -Consequence - What user action or situation would make this problem appear (If you have the foo option enabled and did x)? What did the customer experience as a result of the issue? What was the symptom? -Cause - Why did this happen? -Fix - What did we change to fix the problem? -Result - How has the behavior changed as a result? Try to avoid “It is fixed” or “The issue is resolved” or “The error no longer presents”. -//// - -The following issues been resolved in the current release: - -[id="ossm-rn-fixed-issues-ossm_{context}"] -== {ProductShortName} fixed issues - -* link:https://issues.redhat.com/browse/OSSM-296[OSSM-296] When adding health configuration to the Kiali custom resource (CR) is it not being replicated to the Kiali configmap. - -* link:https://issues.redhat.com/browse/OSSM-291[OSSM-291] In the Kiali console, on the Applications, Services, and Workloads pages, the "Remove Label from Filters" function is not working. - -* link:https://issues.redhat.com/browse/OSSM-289[OSSM-289] In the Kiali console, on the Service Details pages for the 'istio-ingressgateway' and 'jaeger-query' services there are no Traces being displayed. The traces exist in Jaeger. - -* link:https://issues.redhat.com/browse/OSSM-287[OSSM-287] In the Kiali console there are no traces being displayed on the Graph Service. - -* link:https://issues.redhat.com/browse/MAISTRA-2010[MAISTRA-2010] AuthorizationPolicy does not support `request.regex.headers` field. The `validatingwebhook` rejects any AuthorizationPolicy with the field, and even if you disable that, Pilot tries to validate it using the same code, and it does not work. - -* link:https://issues.jboss.org/browse/MAISTRA-1979[MAISTRA-1979] _Migration to 2.0_ The conversion webhook drops the following important fields when converting `SMCP.status` from v2 to v1: - -** conditions -** components -** observedGeneration -** annotations -+ -Upgrading the operator to 2.0 might break client tools that read the SMCP status using the maistra.io/v1 version of the resource. -+ -This also causes the READY and STATUS columns to be empty when you run `oc get servicemeshcontrolplanes.v1.maistra.io`. - -* link:https://issues.jboss.org/browse/MAISTRA-1089[MAISTRA-1089] _Migration to 2.0_ Gateways created in a non-control plane namespace are automatically deleted. Users will need to manually delete these resources after removing the gateway definition from the SMCP spec. - -* link:https://issues.redhat.com/browse/MAISTRA-1983[MAISTRA-1983] _Migration to 2.0_ Upgrading to 2.0.0 with an existing invalid `ServiceMeshControlPlane` cannot easily be repaired. The invalid items in the `ServiceMeshControlPlane` resource caused an unrecoverable error. The fix makes the errors recoverable. You can delete the invalid resource and replace it with a new one or edit the resource to fix the errors. For more information about editing your resource, see [Configuring the Red Hat OpenShift Service Mesh installation]. - -* link:https://issues.redhat.com/browse/MAISTRA-1502[Maistra-1502] As a result of CVEs fixes in version 1.0.10, the Istio dashboards are not available from the *Home Dashboard* menu in Grafana. The Istio dashboards still exist. To access them, click the *Dashboard* menu in the navigation panel and select the *Manage* tab. - -* link:https://issues.jboss.org/browse/MAISTRA-858[MAISTRA-858] The following Envoy log messages describing link:https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated[deprecated options and configurations associated with Istio 1.1.x] are expected: -+ -** [2019-06-03 07:03:28.943][19][warning][misc] [external/envoy/source/common/protobuf/utility.cc:129] Using deprecated option 'envoy.api.v2.listener.Filter.config'. This configuration will be removed from Envoy soon. -** [2019-08-12 22:12:59.001][13][warning][misc] [external/envoy/source/common/protobuf/utility.cc:174] Using deprecated option 'envoy.api.v2.Listener.use_original_dst' from file lds.proto. This configuration will be removed from Envoy soon. - -* link:https://issues.jboss.org/browse/MAISTRA-193[MAISTRA-193] Unexpected console info messages are visible when health checking is enabled for citadel. - -* link:https://bugzilla.redhat.com/show_bug.cgi?id=1821432[Bug 1821432] Toggle controls in {product-title} Control Resource details page do not update the CR correctly. UI Toggle controls in the Service Mesh Control Plane (SMCP) Overview page in the {product-title} web console sometimes update the wrong field in the resource. To update a SMCP, edit the YAML content directly or update the resource from the command line instead of clicking the toggle controls. diff --git a/modules/ossm-rn-known-issues-1x.adoc b/modules/ossm-rn-known-issues-1x.adoc deleted file mode 100644 index 17139a75fd70..000000000000 --- a/modules/ossm-rn-known-issues-1x.adoc +++ /dev/null @@ -1,64 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v1x/servicemesh-release-notes.adoc -//// - -[id="ossm-rn-known-issues-1x_{context}"] -= Known issues - -//// -Consequence - What user action or situation would make this problem appear (Selecting the Foo option with the Bar version 1.3 plugin enabled results in an error message)? What did the customer experience as a result of the issue? What was the symptom? -Cause (if it has been identified) - Why did this happen? -Workaround (If there is one)- What can you do to avoid or negate the effects of this issue in the meantime? Sometimes if there is no workaround it is worthwhile telling readers to contact support for advice. Never promise future fixes. -Result - If the workaround does not completely address the problem. -//// - -These limitations exist in {ProductName}: - -* link:https://github.com/istio/old_issues_repo/issues/115[{ProductName} does not support IPv6], as it is not supported by the upstream Istio project, nor fully supported by OpenShift. - -* Graph layout - The layout for the Kiali graph can render differently, depending on your application architecture and the data to display (number of graph nodes and their interactions). Because it is difficult if not impossible to create a single layout that renders nicely for every situation, Kiali offers a choice of several different layouts. To choose a different layout, you can choose a different *Layout Schema* from the *Graph Settings* menu. - -* The first time you access related services such as Jaeger and Grafana, from the Kiali console, you must accept the certificate and re-authenticate using your {product-title} login credentials. This happens due to an issue with how the framework displays embedded pages in the console. - -[id="ossm-rn-known-issues-ossm_{context}"] -== {ProductShortName} known issues - -These are the known issues in {ProductName}: - -* link:https://access.redhat.com/solutions/4970771[Jaeger/Kiali Operator upgrade blocked with operator pending] When upgrading the Jaeger or Kiali Operators with Service Mesh 1.0.x installed, the operator status shows as Pending. There is a solution in progress and a workaround. See the linked Knowledge Base article for more information. - -* link:https://github.com/istio/istio/issues/14743[Istio-14743] Due to limitations in the version of Istio that this release of {ProductName} is based on, there are several applications that are currently incompatible with {ProductShortName}. See the linked community issue for details. - -* link:https://issues.jboss.org/browse/MAISTRA-858[MAISTRA-858] The following Envoy log messages describing link:https://www.envoyproxy.io/docs/envoy/latest/intro/deprecated[deprecated options and configurations associated with Istio 1.1.x] are expected: -+ -** [2019-06-03 07:03:28.943][19][warning][misc] [external/envoy/source/common/protobuf/utility.cc:129] Using deprecated option 'envoy.api.v2.listener.Filter.config'. This configuration will be removed from Envoy soon. -** [2019-08-12 22:12:59.001][13][warning][misc] [external/envoy/source/common/protobuf/utility.cc:174] Using deprecated option 'envoy.api.v2.Listener.use_original_dst' from file lds.proto. This configuration will be removed from Envoy soon. - -* link:https://issues.jboss.org/browse/MAISTRA-806[MAISTRA-806] Evicted Istio Operator Pod causes mesh and CNI not to deploy. -+ -If the `istio-operator` pod is evicted while deploying the control pane, delete the evicted `istio-operator` pod. -+ -* link:https://issues.jboss.org/browse/MAISTRA-681[MAISTRA-681] When the control plane has many namespaces, it can lead to performance issues. - -* link:https://issues.jboss.org/browse/MAISTRA-465[MAISTRA-465] The Maistra Operator fails to create a service for operator metrics. - -* link:https://issues.jboss.org/browse/MAISTRA-453[MAISTRA-453] If you create a new project and deploy pods immediately, sidecar injection does not occur. The operator fails to add the `maistra.io/member-of` before the pods are created, therefore the pods must be deleted and recreated for sidecar injection to occur. - -* link:https://issues.jboss.org/browse/MAISTRA-158[MAISTRA-158] Applying multiple gateways referencing the same hostname will cause all gateways to stop functioning. - - - -[id="ossm-rn-known-issues-kiali_{context}"] -== Kiali known issues - -[NOTE] -==== -New issues for Kiali should be created in the link:https://issues.redhat.com/projects/OSSM/[OpenShift Service Mesh] project with the `Component` set to `Kiali`. -==== - -These are the known issues in Kiali: - -* link:https://issues.jboss.org/browse/KIALI-2206[KIALI-2206] When you are accessing the Kiali console for the first time, and there is no cached browser data for Kiali, the “View in Grafana” link on the Metrics tab of the Kiali Service Details page redirects to the wrong location. The only way you would encounter this issue is if you are accessing Kiali for the first time. - -* link:https://github.com/kiali/kiali/issues/507[KIALI-507] Kiali does not support Internet Explorer 11. This is because the underlying frameworks do not support Internet Explorer. To access the Kiali console, use one of the two most recent versions of the Chrome, Edge, Firefox or Safari browser. diff --git a/modules/ossm-rn-known-issues.adoc b/modules/ossm-rn-known-issues.adoc deleted file mode 100644 index b8cd3dfc8762..000000000000 --- a/modules/ossm-rn-known-issues.adoc +++ /dev/null @@ -1,79 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v2x/servicemesh-release-notes.adoc -//// - -[id="ossm-rn-known-issues_{context}"] -= Known issues - -//// -Consequence - What user action or situation would make this problem appear (Selecting the Foo option with the Bar version 1.3 plugin enabled results in an error message)? What did the customer experience as a result of the issue? What was the symptom? -Cause (if it has been identified) - Why did this happen? -Workaround (If there is one)- What can you do to avoid or negate the effects of this issue in the meantime? Sometimes if there is no workaround it is worthwhile telling readers to contact support for advice. Never promise future fixes. -Result - If the workaround does not completely address the problem. -//// - -These limitations exist in {ProductName}: - -* link:https://github.com/istio/old_issues_repo/issues/115[{ProductName} does not support IPv6], as it is not supported by the upstream Istio project, nor fully supported by OpenShift. - -* Graph layout - The layout for the Kiali graph can render differently, depending on your application architecture and the data to display (number of graph nodes and their interactions). Because it is difficult if not impossible to create a single layout that renders nicely for every situation, Kiali offers a choice of several different layouts. To choose a different layout, you can choose a different *Layout Schema* from the *Graph Settings* menu. - -* The first time you access related services such as Jaeger and Grafana, from the Kiali console, you must accept the certificate and re-authenticate using your {product-title} login credentials. This happens due to an issue with how the framework displays embedded pages in the console. - -* The Bookinfo sample application cannot be installed on IBM Z and IBM Power Systems. - -* WebAssembly is unsupported on IBM Z and IBM Power Systems. - -[id="ossm-rn-known-issues-ossm_{context}"] -== {ProductShortName} known issues - -These are the known issues in {ProductName}: - -* link:https://github.com/istio/istio/issues/14743[Istio-14743] Due to limitations in the version of Istio that this release of {ProductName} is based on, there are several applications that are currently incompatible with {ProductShortName}. See the linked community issue for details. - -* link:https://issues.redhat.com/browse/OSSM-285[OSSM-285] When trying to access the Kiali console, receive the following error message "Error trying to get OAuth Metadata". The workaround is to restart the Kiali pod. - -* link:https://issues.jboss.org/browse/MAISTRA-1947[MAISTRA-1947] _Technology Preview_ Updates to ServiceMeshExtensions are not applied. The workaround is to remove and recreate the ServiceMeshExtensions. - -* link:https://issues.jboss.org/browse/MAISTRA-1621[MAISTRA-1621] _Migration to 2.0_ Prometheus scraping (`spec.addons.prometheus.scrape` set to `true`) does not work when mTLS is enabled. Additionally, Kiali displays extraneous graph data when mTLS is disabled. -+ -This problem can be addressed by excluding port 15020 from proxy configuration, for example, -+ -[source,yaml] ----- -spec: - proxy: - networking: - trafficControl: - inbound: - excludedPorts: - - 15020 ----- -+ -* link:https://issues.jboss.org/browse/MAISTRA-806[MAISTRA-806] Evicted Istio Operator Pod causes mesh and CNI not to deploy. -+ -If the `istio-operator` pod is evicted while deploying the control pane, delete the evicted `istio-operator` pod. -+ -* link:https://issues.jboss.org/browse/MAISTRA-681[MAISTRA-681] When the control plane has many namespaces, it can lead to performance issues. - -* link:https://issues.jboss.org/browse/MAISTRA-465[MAISTRA-465] The Maistra Operator fails to create a service for operator metrics. - -* link:https://issues.jboss.org/browse/MAISTRA-453[MAISTRA-453] If you create a new project and deploy pods immediately, sidecar injection does not occur. The operator fails to add the `maistra.io/member-of` before the pods are created, therefore the pods must be deleted and recreated for sidecar injection to occur. - -* link:https://issues.jboss.org/browse/MAISTRA-158[MAISTRA-158] Applying multiple gateways referencing the same hostname will cause all gateways to stop functioning. - - -[id="ossm-rn-known-issues-kiali_{context}"] -== Kiali known issues - -[NOTE] -==== -New issues for Kiali should be created in the link:https://issues.redhat.com/projects/OSSM/[OpenShift Service Mesh] project with the `Component` set to `Kiali`. -==== - -These are the known issues in Kiali: - -* link:https://issues.jboss.org/browse/KIALI-2206[KIALI-2206] When you are accessing the Kiali console for the first time, and there is no cached browser data for Kiali, the “View in Grafana” link on the Metrics tab of the Kiali Service Details page redirects to the wrong location. The only way you would encounter this issue is if you are accessing Kiali for the first time. - -* link:https://github.com/kiali/kiali/issues/507[KIALI-507] Kiali does not support Internet Explorer 11. This is because the underlying frameworks do not support Internet Explorer. To access the Kiali console, use one of the two most recent versions of the Chrome, Edge, Firefox or Safari browser. diff --git a/modules/ossm-rn-new-features-1x.adoc b/modules/ossm-rn-new-features-1x.adoc deleted file mode 100644 index d55a8646eccc..000000000000 --- a/modules/ossm-rn-new-features-1x.adoc +++ /dev/null @@ -1,351 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v1x/servicemesh-release-notes.adoc -//// - -[id="ossm-rn-new-features-1x_{context}"] -= New Features - -//// -Feature – Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes. -Reason – If known, include why has the enhancement been implemented (use case, performance, technology, etc.). For example, showcases integration of X with Y, demonstrates Z API feature, includes latest framework bug fixes. There may not have been a 'problem' previously, but system behaviour may have changed. -Result – If changed, describe the current user experience -//// -{ProductName} provides a number of key capabilities uniformly across a network of services: - -* *Traffic Management* - Control the flow of traffic and API calls between services, make calls more reliable, and make the network more robust in the face of adverse conditions. -* *Service Identity and Security* - Provide services in the mesh with a verifiable identity and provide the ability to protect service traffic as it flows over networks of varying degrees of trustworthiness. -* *Policy Enforcement* - Apply organizational policy to the interaction between services, ensure access policies are enforced and resources are fairly distributed among consumers. Policy changes are made by configuring the mesh, not by changing application code. -* *Telemetry* - Gain understanding of the dependencies between services and the nature and flow of traffic between them, providing the ability to quickly identify issues. - -== Component versions included in {ProductName} version {ProductVersion} - -|=== -|Component |Version - -|Istio -|1.4.8 - -|Jaeger -|1.17.9 - -|Kiali -|1.12.14 - -|3scale Istio Adapter -|1.0.0 -|=== - -== New features {ProductName} 1.1.12 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 1.1.11 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 1.1.10 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 1.1.9 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 1.1.8 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 1.1.7 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 1.1.6 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 1.1.5 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -This release also added support for configuring cipher suites. - -== New features {ProductName} 1.1.4 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -[NOTE] -==== -There are manual steps that must be completed to address CVE-2020-8663. -==== - -[id="manual-updates-cve-2020-8663_{context}"] -=== Manual updates required by CVE-2020-8663 - -The fix for link:https://bugzilla.redhat.com/show_bug.cgi?id=1844254[CVE-2020-8663]`: envoy: Resource exhaustion when accepting too many connections` added a configurable limit on downstream connections. The configuration option for this limit must be configured to mitigate this vulnerability. - -[IMPORTANT] -==== -These manual steps are required to mitigate this CVE whether you are using the 1.1 version or the 1.0 version of {ProductName}. -==== - -This new configuration option is called `overload.global_downstream_max_connections`, and it is configurable as a proxy `runtime` setting. Perform the following steps to configure limits at the Ingress Gateway. - -.Procedure - -. Create a file named `bootstrap-override.json` with the following text to force the proxy to override the bootstrap template and load runtime configuration from disk: -+ - { -  "runtime": { -    "symlink_root": "/var/lib/istio/envoy/runtime" -  } - } -+ -. Create a secret from the `bootstrap-override.json` file, replacing <SMCPnamespace> with the namespace where you created the service mesh control plane (SMCP): -+ -[source,terminal] ----- -$ oc create secret generic -n <SMCPnamespace> gateway-bootstrap --from-file=bootstrap-override.json ----- -+ -. Update the SMCP configuration to activate the override. - -+ -.Updated SMCP configuration example #1 -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - istio: - gateways: - istio-ingressgateway: - env: - ISTIO_BOOTSTRAP_OVERRIDE: /var/lib/istio/envoy/custom-bootstrap/bootstrap-override.json - secretVolumes: - - mountPath: /var/lib/istio/envoy/custom-bootstrap - name: custom-bootstrap - secretName: gateway-bootstrap ----- -+ - -. To set the new configuration option, create a secret that has the desired value for the `overload.global_downstream_max_connections` setting. The following example uses a value of `10000`: -+ -[source,terminal] ----- -$ oc create secret generic -n <SMCPnamespace> gateway-settings --from-literal=overload.global_downstream_max_connections=10000 ----- -+ - -. Update the SMCP again to mount the secret in the location where Envoy is looking for runtime configuration: - -.Updated SMCP configuration example #2 -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - template: default -#Change the version to "v1.0" if you are on the 1.0 stream. - version: v1.1 - istio: - gateways: - istio-ingressgateway: - env: - ISTIO_BOOTSTRAP_OVERRIDE: /var/lib/istio/envoy/custom-bootstrap/bootstrap-override.json - secretVolumes: - - mountPath: /var/lib/istio/envoy/custom-bootstrap - name: custom-bootstrap - secretName: gateway-bootstrap - # below is the new secret mount - - mountPath: /var/lib/istio/envoy/runtime - name: gateway-settings - secretName: gateway-settings - ----- - -[id="upgrading_es5_es6_{context}"] -=== Upgrading from Elasticsearch 5 to Elasticsearch 6 - -When updating from Elasticsearch 5 to Elasticsearch 6, you must delete your Jaeger instance, then recreate the Jaeger instance because of an issue with certificates. Re-creating the Jaeger instance triggers creating a new set of certificates. If you are using persistent storage the same volumes can be mounted for the new Jaeger instance as long as the Jaeger name and namespace for the new Jaeger instance are the same as the deleted Jaeger instance. - -.Procedure if Jaeger is installed as part of Red Hat Service Mesh - -. Determine the name of your Jaeger custom resource file: -+ -[source,terminal] ----- -$ oc get jaeger -n istio-system ----- -+ -You should see something like the following: -+ -[source,terminal] ----- -NAME AGE -jaeger 3d21h ----- -+ -. Copy the generated custom resource file into a temporary directory: -+ -[source,terminal] ----- -$ oc get jaeger jaeger -oyaml -n istio-system > /tmp/jaeger-cr.yaml ----- -+ -. Delete the Jaeger instance: -+ -[source,terminal] ----- -$ oc delete jaeger jaeger -n istio-system ----- -+ -. Recreate the Jaeger instance from your copy of the custom resource file: -+ -[source,terminal] ----- -$ oc create -f /tmp/jaeger-cr.yaml -n istio-system ----- -+ -. Delete the copy of the generated custom resource file: -+ -[source,terminal] ----- -$ rm /tmp/jaeger-cr.yaml ----- - - -.Procedure if Jaeger not installed as part of Red Hat Service Mesh - -Before you begin, create a copy of your Jaeger custom resource file. - -. Delete the Jaeger instance by deleting the custom resource file: -+ -[source,terminal] ----- -$ oc delete -f <jaeger-cr-file> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc delete -f jaeger-prod-elasticsearch.yaml ----- -+ -. Recreate your Jaeger instance from the backup copy of your custom resource file: -+ -[source,terminal] ----- -$ oc create -f <jaeger-cr-file> ----- -+ -. Validate that your Pods have restarted: -+ -[source,terminal] ----- -$ oc get pods -n jaeger-system -w ----- -+ - - - - -== New features {ProductName} 1.1.3 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 1.1.2 - -This release of {ProductName} addresses a security vulnerability. - -== New features {ProductName} 1.1.1 - -This release of {ProductName} adds support for a disconnected installation. - -== New features {ProductName} 1.1.0 - -This release of {ProductName} adds support for Istio 1.4.6 and Jaeger 1.17.1. - -[id="ossm-manual-updates-1.0-1.1_{context}"] -=== Manual updates from 1.0 to 1.1 - -If you are updating from {ProductName} 1.0 to 1.1, you must update the `ServiceMeshControlPlane` resource to update the control plane components to the new version. - -. In the web console, click the {ProductName} Operator. - -. Click the *Project* menu and choose the project where your `ServiceMeshControlPlane` is deployed from the list, for example `istio-system`. - -. Click the name of your control plane, for example `basic-install`. - -. Click YAML and add a version field to the `spec:` of your `ServiceMeshControlPlane` resource. For example, to update to {ProductName} 1.1.0, add `version: v1.1`. - ----- -spec: - version: v1.1 - ... ----- - -The version field specifies the version of ServiceMesh to install and defaults to the latest available version. - - -== New features {ProductName} 1.0.11 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -[NOTE] -==== -There are manual steps that must be completed to address CVE-2020-8663. See instructions above. -==== - -== New features {ProductName} 1.0.10 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs). - -== New features {ProductName} 1.0.9 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs). - -== New features {ProductName} 1.0.8 - -This release of {ProductName} addresses compatibility issues with {product-title} 4.4. You must upgrade {ProductName} to 1.0.8 before you upgrade from {product-title} 4.3 to {product-title} 4.4. - -== New features {ProductName} 1.0.7 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs). - -== New features {ProductName} 1.0.6 - -This release contains internal improvements. - -== New features {ProductName} 1.0.5 - -This release contains internal improvements. - -== New features {ProductName} 1.0.4 - -This release of {ProductName} adds support for Kiali 1.0.9, and addresses Common Vulnerabilities and Exposures (CVEs). - -== New features {ProductName} 1.0.3 - -This release of {ProductName} adds support for Kiali 1.0.8, and addresses Common Vulnerabilities and Exposures (link:https://access.redhat.com/errata/RHSA-2019:4222[CVEs]). - -== New features {ProductName} 1.0.2 - -This release of {ProductName} adds support for Istio 1.1.17, Jaeger 1.13.1, Kiali 1.0.7, and the 3scale Istio Adapter 1.0 and {product-title} 4.2. - -== New features {ProductName} 1.0.1 - -This release of {ProductName} adds support for Istio 1.1.11, Jaeger 1.13.1, Kiali 1.0.6, and the 3scale Istio Adapter 1.0 and {product-title} 4.1. - -== New features {ProductName} 1.0 - -This release of {ProductName} adds support for Istio 1.1.11, Jaeger 1.13.1, Kiali 1.0.5, and the 3scale Istio Adapter 1.0 and {product-title} 4.1. - -Other notable changes in this release include the following: - -* The Kubernetes Container Network Interface (CNI) plug-in is always on. -* The control plane is configured for multitenancy by default. Single tenant, cluster-wide control plane configurations are deprecated. -* The OpenShift Elasticsearch, Jaeger, Kiali, and {ProductShortName} Operators are installed from OperatorHub. -* You can create and specify control plane templates. -* Automatic route creation was removed from this release. diff --git a/modules/ossm-rn-new-features.adoc b/modules/ossm-rn-new-features.adoc deleted file mode 100644 index 255716a7873a..000000000000 --- a/modules/ossm-rn-new-features.adoc +++ /dev/null @@ -1,67 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v2x/servicemesh-release-notes.adoc -//// - -[id="ossm-rn-new-features_{context}"] -= New features - -//// -Feature – Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes. -Reason – If known, include why has the enhancement been implemented (use case, performance, technology, etc.). For example, showcases integration of X with Y, demonstrates Z API feature, includes latest framework bug fixes. There may not have been a 'problem' previously, but system behaviour may have changed. -Result – If changed, describe the current user experience -//// -{ProductName} provides a number of key capabilities uniformly across a network of services: - -* *Traffic Management* - Control the flow of traffic and API calls between services, make calls more reliable, and make the network more robust in the face of adverse conditions. -* *Service Identity and Security* - Provide services in the mesh with a verifiable identity and provide the ability to protect service traffic as it flows over networks of varying degrees of trustworthiness. -* *Policy Enforcement* - Apply organizational policy to the interaction between services, ensure access policies are enforced and resources are fairly distributed among consumers. Policy changes are made by configuring the mesh, not by changing application code. -* *Telemetry* - Gain understanding of the dependencies between services and the nature and flow of traffic between them, providing the ability to quickly identify issues. - -== Component versions included in {ProductName} version {ProductVersion} - -|=== -|Component |Version - -|Istio -|1.6.14 - -|Jaeger -|1.20.3 - -|Kiali -|1.24.6 - -|3scale Istio Adapter -|2.0.0 -|=== - - -== New features {ProductName} 2.0.2 - -This release of {ProductName} adds support for IBM Z and IBM Power Systems. It also addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 2.0.1 - -This release of {ProductName} addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. - -== New features {ProductName} 2.0 - -This release of {ProductName} adds support for Istio 1.6.5, Jaeger 1.20.0, Kiali 1.24.2, and the 3scale Istio Adapter 2.0 and OpenShift Container Platform 4.6. - -In addition, this release has the following new features: - -* Introduces a re-architected control plane. The Mixer component has been deprecated and will be removed in a future release. The other control plane components, Pilot, Galley, Citadel, have been combined into a single binary known as Istiod. The "d" stands for daemon. -** Simplifies installation, upgrades, and management of the control plane. -** Reduces the control plane's resource usage and startup time. -** Improves performance by reducing inter-control plane communication over networking. - -* Adds support for Envoy's Secret Discovery Service (SDS). SDS is a more secure and efficient mechanism for delivering secrets to Envoy side car proxies. -** Removes the need to use Kubernetes Secrets, which have well known security risks. -** Improves performance during certificate rotation, as proxies no longer require a restart to recognize new certificates. - -* Adds support for Istio's Telemetry v2 architecture, which is built using WebAssembly extensions. This new architecture brings significant performance improvements. - -* Updates the ServiceMeshControlPlane resource to v2 with a streamlined configuration to make it easier to manage the Control Plane. - -* Introduces WebAssembly extensions as a link:https://access.redhat.com/support/offerings/techpreview[Technology Preview] feature. diff --git a/modules/ossm-rn-technology-preview.adoc b/modules/ossm-rn-technology-preview.adoc deleted file mode 100644 index 563561a6caae..000000000000 --- a/modules/ossm-rn-technology-preview.adoc +++ /dev/null @@ -1,31 +0,0 @@ -//// -Module included in the following assemblies: -- v2x\servicemesh-release-notes.adoc -//// - -[id="ossm-rn-tech-preview_{context}"] -= Technology Preview - -[IMPORTANT] -==== -Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. -These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/. -==== - -= WebAsssembly Technology Preview - -{ProductName} 2.0.0 introduces support for WebAssembly extensions to Envoy Proxy. - -Up through release 1.5, Istio implemented extensions using the Mixer Telemetry and Policy components. In -link:https://istio.io/latest/news/releases/1.5.x/announcing-1.5/upgrade-notes/#mixer-deprecation[Istio 1.5] Mixer was deprecated and link:https://istio.io/latest/news/releases/1.5.x/announcing-1.5/upgrade-notes/#mixer-deprecation[WebAssembly was introduced] as the new mechanism for extensions in Istio. Envoy now allows extensions using WebAssembly (“WASM”) - a format for executing code written in multiple programming languages. Mixer has been deprecated as of Istio 1.5, and will be removed in 1.8. Going forward, extensions to Istio will be implemented with Envoy plugins written with WebAssembly. - -The new Telemetry architecture is based on these WebAssembly extensions. For {ProductShortName} 2.0, we are introducing WebAssembly extensions as a Tech Preview feature. WebAssembly extensions is the new way of extending Istio functionality, replacing the Mixer component, which has been deprecated and will eventually be removed. - -[NOTE] -==== -Note that built-in Istio WASM extensions are not included in the proxy binary and that WASM filters from the upstream Istio community are not supported in {ProductName} 2.0. -==== - -= OVNKubernetes Technology Preview - -{ProductName} 2.0.1 introduces support for the OVN-Kubernetes network type on {product-title} 4.7. \ No newline at end of file diff --git a/modules/ossm-routing-bookinfo-example.adoc b/modules/ossm-routing-bookinfo-example.adoc deleted file mode 100644 index 68fc2ca76366..000000000000 --- a/modules/ossm-routing-bookinfo-example.adoc +++ /dev/null @@ -1,171 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-traffic-manage.adoc -// * service_mesh/v2x/ossm-traffic-manage.adoc - -[id="ossm-routing-bookinfo_{context}"] -= Routing example using the bookinfo application - -The {ProductShortName} Bookinfo sample application consists of four separate microservices, each with multiple versions. Three different versions, one of the microservices called `reviews`, have been deployed and are running concurrently. - -.Prerequisites: - -* Deploy the Bookinfo sample application to work with the following examples. - -.About this task - -To illustrate the problem this causes, access the bookinfo app `/product page` in a browser and refresh several times. - -Sometimes the book review output contains star ratings and other times it does not. Without an explicit default service version to route to, {ProductShortName} routes requests to all available versions one after the other. - -This tutorial helps you apply rules that route all traffic to `v1` (version 1) of the microservices. Later, you can apply a rule to route traffic based on the value of an HTTP request header. - -[id="ossm-routing-bookinfo-applying_{context}"] -== Applying a virtual service - -To route to one version only, apply virtual services that set the default version for the micro-services. In the following example, the virtual service routes all traffic to `v1` of each micro-service - -1. Run the following command to apply the virtual services: -+ -[source,terminal] ----- -$ oc apply -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/virtual-service-all-v1.yaml ----- -+ -2. To test the command was successful, display the defined routes with the following command: -+ -[source,terminal] ----- -$ oc get virtualservices -o yaml ----- -+ -That command returns the following YAML file. -+ -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - name: details - ... -spec: - hosts: - - details - http: - - route: - - destination: - host: details - subset: v1 ---- -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - name: productpage - ... -spec: - gateways: - - bookinfo-gateway - - mesh - hosts: - - productpage - http: - - route: - - destination: - host: productpage - subset: v1 ---- -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - name: ratings - ... -spec: - hosts: - - ratings - http: - - route: - - destination: - host: ratings - subset: v1 ---- -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - name: reviews - ... -spec: - hosts: - - reviews - http: - - route: - - destination: - host: reviews - subset: v1 ----- -+ -You have configured {ProductShortName} to route to the `v1` version of the Bookinfo microservices, most importantly the `reviews` service version 1. - -[id="ossm-routing-bookinfo-test_{context}"] -== Test the new routing configuration - -You can easily test the new configuration by once again refreshing the `/productpage` of the Bookinfo app. - -1. Open the Bookinfo site in your browser. The URL is `http://$GATEWAY_URL/productpage`, where `$GATEWAY_URL` is the External IP address of the ingress. -+ -The reviews part of the page displays with no rating stars, no matter how many times you refresh. This is because you configured {ProductShortName} to route all traffic for the reviews service to the version `reviews:v1` and this version of the service does not access the star ratings service. -+ -Your service mesh now routes traffic to one version of a service. - -[id="ossm-routing-bookinfo-route_{context}"] -== Route based on user identity - -Next, change the route configuration so that all traffic from a specific user is routed to a specific service version. In this case, all traffic from a user named `jason` will be routed to the service `reviews:v2`. - -Note that {ProductShortName} doesn't have any special, built-in understanding of user identity. This example is enabled by the fact that the `productpage` service adds a custom `end-user` header to all outbound HTTP requests to the reviews service. - -1. Run the following command to enable user-based routing: -+ -[source,terminal] ----- -$ oc apply -f https://raw.githubusercontent.com/Maistra/istio/maistra-1.1/samples/bookinfo/networking/virtual-service-reviews-test-v2.yaml ----- -+ -2. Confirm the rule is created: -+ -[source,terminal] ----- -$ oc get virtualservice reviews -o yaml ----- -+ -That command returns the following YAML file. -+ -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - name: reviews - ... -spec: - hosts: - - reviews - http: - - match: - - headers: - end-user: - exact: jason - route: - - destination: - host: reviews - subset: v2 - - route: - - destination: - host: reviews - subset: v1 ----- -+ -3. On the `/productpage` of the Bookinfo app, log in as user `jason`. Refresh the browser. What do you see? The star ratings appear next to each review. -+ -4. Log in as another user (pick any name you wish). Refresh the browser. Now the stars are gone. This is because traffic is routed to `reviews:v1` for all users except Jason. - -You have successfully configured {ProductShortName} to route traffic based on user identity. diff --git a/modules/ossm-routing-ingress.adoc b/modules/ossm-routing-ingress.adoc deleted file mode 100644 index 9f13768831c8..000000000000 --- a/modules/ossm-routing-ingress.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-traffic-manage.adoc -// * service_mesh/v2x/ossm-traffic-manage.adoc - -[id="ossm-routing-ingress_{context}"] -= Managing ingress traffic - -In {ProductName}, the Ingress Gateway enables Service Mesh features such as monitoring, security, and route rules to be applied to traffic entering the cluster. Configure {ProductShortName} to expose a service outside of the service mesh using an {ProductShortName} gateway. - -[id="ossm-routing-determine-ingress_{context}"] -== Determining the ingress IP and ports - -Run the following command to determine if your Kubernetes cluster is running in an environment that supports external load balancers: - -[source,terminal] ----- -$ oc get svc istio-ingressgateway -n istio-system ----- - -That command returns the `NAME`, `TYPE`, `CLUSTER-IP`, `EXTERNAL-IP`, `PORT(S)`, and `AGE` of each item in your namespace. - -If the `EXTERNAL-IP` value is set, your environment has an external load balancer that you can use for the ingress gateway. - -If the `EXTERNAL-IP` value is `<none>`, or perpetually `<pending>`, your environment does not provide an external load balancer for the ingress gateway. You can access the gateway using the service's https://kubernetes.io/docs/concepts/services-networking/service/#nodeport[node port]. - -Choose the instructions for your environment: - -.Configuring routing with a load balancer - -Follow these instructions if your environment has an external load balancer. - -Set the ingress IP and ports: - -[source,terminal] ----- -$ export INGRESS_HOST=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}') ----- - -[source,terminal] ----- -$ export INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].port}') ----- - -[source,terminal] ----- -$ export SECURE_INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].port}') ----- - -In some environments, the load balancer may be exposed using a host name instead of an IP address. For that case, the ingress gateway's `EXTERNAL-IP` value is not be an IP address. Instead, it's a host name, and the previous command fails to set the `INGRESS_HOST` environment variable. - -Use the following command to correct the `INGRESS_HOST` value: - -[source,terminal] ----- -$ export INGRESS_HOST=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') ----- - -.Configuring routing without a load balancer - -Follow these instructions if your environment does not have an external load balancer. You must use a node port instead. - -Set the ingress ports: - -[source,terminal] ----- -$ export INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].nodePort}') ----- - -[source,terminal] ----- -$ export SECURE_INGRESS_PORT=$(oc -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].nodePort}') ----- diff --git a/modules/ossm-routing.adoc b/modules/ossm-routing.adoc deleted file mode 100644 index 8257fc283653..000000000000 --- a/modules/ossm-routing.adoc +++ /dev/null @@ -1,288 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-traffic-manage.adoc -// * service_mesh/v2x/ossm-traffic-manage.adoc - -[id="ossm-routing_{context}"] -= Routing and managing traffic - -Configure your service mesh by adding your own traffic configuration to {ProductName} with a custom resource definitions in a YAML file. - -[id="ossm-routing-traffic-management-vs_{context}"] -== Traffic management with virtual services - -You can route requests dynamically to multiple versions of a microservice through {ProductName} with a virtual service. With virtual services, you can: - -* Address multiple application services through a single virtual service. If your mesh uses Kubernetes, for example, you can configure a virtual service to handle all services in a specific namespace. Mapping a single virtual service to many services is particularly useful in facilitating turning a monolithic application into a composite service built out of distinct microservices without requiring the consumers of the service to adapt to the transition. -* Configure traffic rules in combination with gateways to control ingress and egress traffic. - -[id="ossm-routing-vs_{context}"] -=== Configuring virtual services - -Requests are routed to a services within a service mesh with virtual services. Each virtual service consists of a set of routing rules that are evaluated in order. {ProductName} matches each given request to the virtual service to a specific real destination within the mesh. - -Without virtual services, {ProductName} distributes traffic using round-robin load balancing between all service instances. With a virtual service, you can specify traffic behavior for one or more hostnames. Routing rules in the virtual service tell {ProductName} how to send the traffic for the virtual service to appropriate destinations. Route destinations can be versions of the same service or entirely different services. - -The following example routes requests to different versions of a service depending on which user connects to the application. Use this command to apply this example YAML file, or one you create. - -[source,terminal] ----- -$ oc apply -f - <<EOF -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - name: reviews -spec: - hosts: - - reviews - http: - - match: - - headers: - end-user: - exact: jason - route: - - destination: - host: reviews - subset: v2 - - route: - - destination: - host: reviews - subset: v3 -EOF ----- - -[id="ossm-routing-config-v-host_{context}"] -== Configuring your virtual host - -The following sections explain each field in the YAML file and explain how you can create a virtual host in a virtual service. - -[id="ossm-routing-hosts_{context}"] -=== Hosts - -The `hosts` field lists the virtual service’s user-addressable destination that these routing rules apply to. This is the address or addresses the client uses when sending requests to the service. - -The virtual service hostname can be an IP address, a DNS name, or, depending on the platform, a short name that resolves to a fully qualified domain name. - -[source,yaml] ----- -spec: - hosts: - - reviews ----- - -[id="ossm-routing-routing-rules_{context}"] -=== Routing rules - -The `http` section contains the virtual service’s routing rules, describing match conditions and actions for routing HTTP/1.1, HTTP2, and gRPC traffic sent to the destination specified in the hosts field. A routing rule consists of the destination where you want the traffic to go and zero or more match conditions, depending on your use case. - -.Match condition - -The first routing rule in the example has a condition and begins with the match field. In this example, this routing applies to all requests from the user `jason`. Add the `headers`, `end-user`, and `exact` fields to select the appropriate requests. - -[source,yaml] ----- -spec: - hosts: - - reviews - http: - - match: - - headers: - end-user: - exact: jason ----- - -.Destination - -The `destination` field in the route section specifies the actual destination for traffic that matches this condition. Unlike the virtual service’s host, the destination’s host must be a real destination that exists in the {ProductName} service registry. This can be a mesh service with proxies or a non-mesh service added using a service entry. In this example, the host name is a Kubernetes service name: - -[source,yaml] ----- -spec: - hosts: - - reviews - http: - - match: - - headers: - end-user: - exact: jason - route: - - destination: - host: reviews - subset: v2 ----- - -[id="ossm-routing-dr_{context}"] -=== Destination rules - -Destination rules are applied after virtual service routing rules are evaluated, so they apply to the traffic’s real destination. Virtual services route traffic to a destination. Destination rules configure what happens to traffic at that destination. - -[id="ossm-routing-lb_{context}"] -==== Load balancing options - -By default, {ProductName} uses a round-robin load balancing policy, where each service instance in the instance pool gets a request in turn. {ProductName} also supports the following models, which you can specify in destination rules for requests to a particular service or service subset. - -* Random: Requests are forwarded at random to instances in the pool. -* Weighted: Requests are forwarded to instances in the pool according to a specific percentage. -* Least requests: Requests are forwarded to instances with the least number of requests. - -.Destination rule example - -The following example destination rule configures three different subsets for the `my-svc` destination service, with different load balancing policies: - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: DestinationRule -metadata: - name: my-destination-rule -spec: - host: my-svc - trafficPolicy: - loadBalancer: - simple: RANDOM - subsets: - - name: v1 - labels: - version: v1 - - name: v2 - labels: - version: v2 - trafficPolicy: - loadBalancer: - simple: ROUND_ROBIN - - name: v3 - labels: - version: v3 ----- - -[id="ossm-routing-gw_{context}"] -=== Gateways - -You can use a gateway to manage inbound and outbound traffic for your mesh to specify which traffic you want to enter or leave the mesh. Gateway configurations are applied to standalone Envoy proxies that are running at the edge of the mesh, rather than sidecar Envoy proxies running alongside your service workloads. - -Unlike other mechanisms for controlling traffic entering your systems, such as the Kubernetes Ingress APIs, {ProductName} gateways let you use the full power and flexibility of traffic routing. The {ProductName} gateway resource can layer 4-6 load balancing properties such as ports to expose, {ProductName} TLS settings. Instead of adding application-layer traffic routing (L7) to the same API resource, you can bind a regular {ProductName} virtual service to the gateway and manage gateway traffic like any other data plane traffic in a service mesh. - -Gateways are primarily used to manage ingress traffic, but you can also configure egress gateways. An egress gateway lets you configure a dedicated exit node for the traffic leaving the mesh, letting you limit which services have access to external networks, or to enable secure control of egress traffic to add security to your mesh, for example. You can also use a gateway to configure a purely internal proxy. - -.Gateway example - -The following example shows a possible gateway configuration for external HTTPS ingress traffic: - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: Gateway -metadata: - name: ext-host-gwy -spec: - selector: - istio: ingressgateway # use istio default controller - servers: - - port: - number: 443 - name: https - protocol: HTTPS - hosts: - - ext-host.example.com - tls: - mode: SIMPLE - serverCertificate: /tmp/tls.crt - privateKey: /tmp/tls.key ----- - -This gateway configuration lets HTTPS traffic from `ext-host.example.com` into the mesh on port 443, but doesn’t specify any routing for the traffic. - -To specify routing and for the gateway to work as intended, you must also bind the gateway to a virtual service. You do this using the virtual service’s gateways field, as shown in the following example: - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - name: virtual-svc -spec: - hosts: - - ext-host.example.com - gateways: - - ext-host-gwy ----- - -You can then configure the virtual service with routing rules for the external traffic. - -[id="ossm-routing-se_{context}"] -=== Service entries - -A service entry adds an entry to the service registry that {ProductName} maintains internally. After you add the service entry, the Envoy proxies can send traffic to the service as if it was a service in your mesh. Configuring service entries allows you to manage traffic for services running outside of the mesh, including the following tasks: - -* Redirect and forward traffic for external destinations, such as APIs consumed from the web, or traffic to services in legacy infrastructure. -* Define retry, timeout, and fault injection policies for external destinations. -* Run a mesh service in a Virtual Machine (VM) by adding VMs to your mesh. -* Logically add services from a different cluster to the mesh to configure a multicluster {ProductName} mesh on Kubernetes. -* You don’t need to add a service entry for every external service that you want your mesh services to use. By default, {ProductName} configures the Envoy proxies to pass requests through to unknown services. However, you can’t use {ProductName} features to control the traffic to destinations that aren’t registered in the mesh. - -.Service entry examples -The following example mesh-external service entry adds the `ext-resource` external dependency to the {ProductName} service registry: - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: ServiceEntry -metadata: - name: svc-entry -spec: - hosts: - - ext-svc.example.com - ports: - - number: 443 - name: https - protocol: HTTPS - location: MESH_EXTERNAL - resolution: DNS ----- - -Specify the external resource using the hosts field. You can qualify it fully or use a wildcard prefixed domain name. - -You can configure virtual services and destination rules to control traffic to a service entry in the same way you configure traffic for any other service in the mesh. For example, the following destination rule configures the traffic route to use mutual TLS to secure the connection to the `ext-svc.example.com` external service that is configured using the service entry: - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: DestinationRule -metadata: - name: ext-res-dr -spec: - host: ext-svc.example.com - trafficPolicy: - tls: - mode: MUTUAL - clientCertificate: /etc/certs/myclientcert.pem - privateKey: /etc/certs/client_private_key.pem - caCertificates: /etc/certs/rootcacerts.pem ----- - -[id="ossm-routing-sc_{context}"] -=== Sidecar - -By default, {ProductName} configures every Envoy proxy to accept traffic on all the ports of its associated workload, and to reach every workload in the mesh when forwarding traffic. You can use a sidecar configuration to do the following: - -* Fine-tune the set of ports and protocols that an Envoy proxy accepts. -* Limit the set of services that the Envoy proxy can reach. -* You might want to limit sidecar reachability like this in larger applications, where having every proxy configured to reach every other service in the mesh can potentially affect mesh performance due to high memory usage. - -.Sidecar example - -You can specify that you want a sidecar configuration to apply to all workloads in a particular namespace, or choose specific workloads using a `workloadSelector`. For example, the following sidecar configuration configures all services in the `bookinfo` namespace to only reach services running in the same namespace and the {ProductName} control plane (currently needed to use the {ProductName} policy and telemetry features): - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: Sidecar -metadata: - name: default - namespace: bookinfo -spec: - egress: - - hosts: - - "./*" - - "istio-system/*" ----- diff --git a/modules/ossm-security-auth-policy.adoc b/modules/ossm-security-auth-policy.adoc deleted file mode 100644 index db5828dc75ed..000000000000 --- a/modules/ossm-security-auth-policy.adoc +++ /dev/null @@ -1,181 +0,0 @@ -//// -Module included in the following assemblies: --service_mesh/v2x/ossm-security.adoc -//// - -[id="ossm-vs-istio_{context}"] -= Configuring Role Based Access Control (RBAC) - -Role-based access control (RBAC) objects determine whether a user or service is allowed to perform a given action within a project. You can define mesh-, namespace-, and workload-wide access control for your workloads in the mesh. - -To configure RBAC, create an `AuthorizationPolicy` resource in the namespace for which you are configuring access. If you are configuring mesh-wide access, use `istio-system`. - -For example, with RBAC, you can create policies that: - -* Configure intra-project communication. -* Allow or deny full access to all workloads in the default namespace. -* Allow or deny ingress gateway access. -* Require a token for access. - -An authorization policy includes a selector, an action, and a list of rules: - -* The `selector` field specifies the target of the policy. -* The `action` field specifies whether to allow or deny the request. -* The `rules` field specifies when to trigger the action. -** The `from` field specifies constraints on the request origin. -** The `to` field specifies constraints on request target and parameters. -** The `when` field specifies additional conditions that to apply the rule. - -.Procedure - -. Create your `AuthorizationPolicy` resource. The following example shows a resource that updates the ingress-policy `AuthorizationPolicy` to deny an IP address from accessing the ingress gateway. -+ -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: ingress-policy - namespace: istio-system -spec: - selector: - matchLabels: - app: istio-ingressgateway - action: DENY - rules: - - from: - - source: - ipBlocks: ["1.2.3.4"] ----- -+ -. Run the following command after you write your resource to create your resource in your namespace. The namespace must match your `metadata.namespace` field in your `AuthorizationPolicy` resource. -+ -[source,terminal] ----- -$ oc create -n istio-system -f <filename> ----- - -.Next steps - -Consider the following examples for other common configurations. - -== Configure intra-project communication - -You can use `AuthorizationPolicy` to configure your control plane to allow or deny the traffic communicating with your mesh or services in your mesh. - -=== Restrict access to services outside a namespace - -You can deny requests from any source that is not in the `bookinfo` namespace with the following `AuthorizationPolicy` resource example. - -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: httpbin-deny - namespace: bookinfo -spec: - selector: - matchLabels: - app: httpbin - version: v1 - action: DENY - rules: - - from: - - source: - notNamespaces: ["bookinfo"] ----- - -=== Creating allow-all and default deny-all authorization policies - -The following example shows an allow-all authorization policy that allows full access to all workloads in the `bookinfo` namespace. - -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: allow-all - namespace: bookinfo -spec: - action: ALLOW - rules: - - {} ----- - -The following example shows a policy that denies any access to all workloads in the `bookinfo` namespace. - -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: deny-all - namespace: bookinfo -spec: - {} ----- - -== Allow or deny access to the ingress gateway - -You can set an authorization policy to add allow or deny lists based on IP addresses. - -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: ingress-policy - namespace: istio-system -spec: - selector: - matchLabels: - app: istio-ingressgateway - action: ALLOW - rules: - - from: - - source: - ipBlocks: ["1.2.3.4", "5.6.7.0/24"] ----- - -== Restrict access with JSON Web Token - -You can restrict what can access your mesh with a JSON Web Token (JWT). After authentication, a user or service can access routes, services that are associated with that token. - -Create a `RequestAuthentication` resource, which defines the authentication methods that are supported by a workload. The following example accepts a JWT issued by `http://localhost:8080/auth/realms/master`. - -[source,yaml] ----- -apiVersion: "security.istio.io/v1beta1" -kind: "RequestAuthentication" -metadata: - name: "jwt-example" - namespace: bookinfo -spec: - selector: - matchLabels: - app: httpbin - jwtRules: - - issuer: "http://localhost:8080/auth/realms/master" - jwksUri: "http://keycloak.default.svc:8080/auth/realms/master/protocol/openid-connect/certs" ----- - -Then, create an `AuthorizationPolicy` resource in the same namespace to work with `RequestAuthentication` resource you created. The following example requires a JWT to be present in the `Authorization` header when sending a request to `httpbin` workloads. - -[source,yaml] ----- -apiVersion: "security.istio.io/v1beta1" -kind: "AuthorizationPolicy" -metadata: - name: "frontend-ingress" - namespace: bookinfo -spec: - selector: - matchLabels: - app: httpbin - action: DENY - rules: - - from: - - source: - notRequestPrincipals: ["*"] ----- diff --git a/modules/ossm-security-cert-manage-1x.adoc b/modules/ossm-security-cert-manage-1x.adoc deleted file mode 100644 index 839ed8a84a89..000000000000 --- a/modules/ossm-security-cert-manage-1x.adoc +++ /dev/null @@ -1,169 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-security.adoc - - -[id="ossm-cert-manage_{context}"] -= Adding an external certificate authority key and certificate - -By default, {ProductName} generates self-signed root certificate and key, and uses them to sign the workload certificates. You can also use the user-defined certificate and key to sign workload certificates, with user-defined root certificate. This task demonstrates an example to plug certificates and key into {ProductShortName}. - -.Prerequisites - -* You must have installed {ProductName} with mutual TLS enabled to configure certificates. -* This example uses the certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repository]. For production, use your own certificates from your certificate authority. -* You must deploy the Bookinfo sample application to verify the results with these instructions. - -[id="ossm-cert-manage-add-cert-key_{context}"] -== Adding an existing certificate and key - -To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is called `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is called `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file. - -Add the certificates to {ProductShortName} by following these steps. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-1.1/samples/certs[Maistra repo] locally and replace `<path>` with the path to your certificates. - -. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`. -+ -[source,terminal] ----- -$ oc create secret generic cacerts -n istio-system --from-file=<path>/ca-cert.pem \ - --from-file=<path>/ca-key.pem --from-file=<path>/root-cert.pem \ - --from-file=<path>/cert-chain.pem ----- -+ -. In the `ServiceMeshControlPlane` resource set `global.mtls.enabled` to `true` and `security.selfSigned` set to `false`. {ProductShortName} reads the certificates and key from the secret-mount files. -+ -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - istio: - global: - mtls: - enabled: true - security: - selfSigned: false ----- -+ -. To make sure the workloads add the new certificates promptly, delete the secrets generated by {ProductShortName}, named `istio.*`. In this example, `istio.default`. {ProductShortName} issues new certificates for the workloads. -+ -[source,terminal] ----- -$ oc delete secret istio.default ----- - -[id="ossm-cert-manage-verify-cert_{context}"] -== Verifying your certificates - -Use the Bookinfo sample application to verify your certificates are mounted correctly. First, retrieve the mounted certificates. Then, verify the certificates mounted on the pod. - -. Store the pod name in the variable `RATINGSPOD`. -+ -[source,terminal] ----- -$ RATINGSPOD=`oc get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'` ----- -+ -. Run the following commands to retrieve the certificates mounted on the proxy. -+ -[source,terminal] ----- -$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/root-cert.pem > /tmp/pod-root-cert.pem ----- -+ -The file `/tmp/pod-root-cert.pem` contains the root certificate propagated to the pod. -+ -[source,terminal] ----- -$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem ----- -+ -The file `/tmp/pod-cert-chain.pem` contains the workload certificate and the CA certificate propagated to the pod. -+ -. Verify the root certificate is the same as the one specified by the Operator. Replace `<path>` with the path to your certificates. -+ -[source,terminal] ----- -$ openssl x509 -in <path>/root-cert.pem -text -noout > /tmp/root-cert.crt.txt ----- -+ -[source,terminal] ----- -$ openssl x509 -in /tmp/pod-root-cert.pem -text -noout > /tmp/pod-root-cert.crt.txt ----- -+ -[source,terminal] ----- -$ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt ----- -+ -Expect the output to be empty. -+ -. Verify the CA certificate is the same as the one specified by Operator. Replace `<path>` with the path to your certificates. -+ -[source,terminal] ----- -$ sed '0,/^-----END CERTIFICATE-----/d' /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-ca.pem ----- -+ -[source,terminal] ----- -$ openssl x509 -in <path>/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt ----- -+ -[source,terminal] ----- -$ openssl x509 -in /tmp/pod-cert-chain-ca.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt ----- -+ -[source,terminal] ----- -$ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt ----- -+ -Expect the output to be empty. -+ -. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates. -+ -[source,terminal] ----- -$ head -n 21 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-workload.pem ----- -+ -[source,terminal] ----- -$ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) /tmp/pod-cert-chain-workload.pem ----- -+ -.Example output -[source,terminal] ----- -/tmp/pod-cert-chain-workload.pem: OK ----- - -[id="ossm-cert-cleanup_{context}"] -== Removing the certificates - -To remove the certificates you added, follow these steps. - -. Remove the secret `cacerts`. -+ -[source,terminal] ----- -$ oc delete secret cacerts -n istio-system ----- -+ -. Redeploy {ProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource. -+ -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - istio: - global: - mtls: - enabled: true - security: - selfSigned: true ----- diff --git a/modules/ossm-security-cert-manage.adoc b/modules/ossm-security-cert-manage.adoc deleted file mode 100644 index e00ee8c2beba..000000000000 --- a/modules/ossm-security-cert-manage.adoc +++ /dev/null @@ -1,167 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/ossm-security.adoc - -[id="ossm-cert-manage_{context}"] -= Adding an external certificate authority key and certificate - -By default, {ProductName} generates self-signed root certificate and key, and uses them to sign the workload certificates. You can also use the user-defined certificate and key to sign workload certificates, with user-defined root certificate. This task demonstrates an example to plug certificates and key into {ProductShortName}. - -.Prerequisites - -* You must have installed {ProductName} with mutual TLS enabled to configure certificates. -* This example uses the certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repository]. For production, use your own certificates from your certificate authority. -* You must deploy the Bookinfo sample application to verify the results with these instructions. - -[id="ossm-cert-manage-add-cert-key_{context}"] -== Adding an existing certificate and key - -To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is called `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is called `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file. - -Add the certificates to {ProductShortName} by following these steps. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repository] locally and replace `<path>` with the path to your certificates. - -. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`. -+ -[source,terminal] ----- -$ oc create secret generic cacerts -n istio-system --from-file=<path>/ca-cert.pem \ - --from-file=<path>/ca-key.pem --from-file=<path>/root-cert.pem \ - --from-file=<path>/cert-chain.pem ----- -+ -. In the `ServiceMeshControlPlane` resource set `spec.security.dataPlane.mtls: true` to `true` and configure your certificateAuthority like the following example. The default `rootCADir` is `/etc/cacerts`. You do not need to set the `privateKey` if the key and certs are mounted in the default location. {ProductShortName} reads the certificates and key from the secret-mount files. -+ -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -spec: - security: - dataPlane: - mtls: true - certificateAuthority: - type: Istiod - istiod: - type: PrivateKey - privateKey: - rootCADir: /etc/cacerts ----- -+ -. To make sure the workloads add the new certificates promptly, delete the secrets generated by {ProductShortName}, named `istio.*`. In this example, `istio.default`. {ProductShortName} issues new certificates for the workloads. -+ -[source,terminal] ----- -$ oc delete secret istio.default ----- - -[id="ossm-cert-manage-verify-cert_{context}"] -== Verifying your certificates - -Use the Bookinfo sample application to verify your certificates are mounted correctly. First, retrieve the mounted certificates. Then, verify the certificates mounted on the pod. - -. Store the pod name in the variable `RATINGSPOD`. -+ -[source,terminal] ----- -$ RATINGSPOD=`oc get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'` ----- -+ -. Run the following commands to retrieve the certificates mounted on the proxy. -+ -[source,terminal] ----- -$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /var/run/secrets/istio/root-cert.pem > /tmp/pod-root-cert.pem ----- -+ -The file `/tmp/pod-root-cert.pem` contains the root certificate propagated to the pod. -+ -[source,terminal] ----- -$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem ----- -+ -The file `/tmp/pod-cert-chain.pem` contains the workload certificate and the CA certificate propagated to the pod. -+ -. Verify the root certificate is the same as the one specified by the Operator. Replace `<path>` with the path to your certificates. -+ -[source,terminal] ----- -$ openssl x509 -in <path>/root-cert.pem -text -noout > /tmp/root-cert.crt.txt ----- -+ -[source,terminal] ----- -$ openssl x509 -in /tmp/pod-root-cert.pem -text -noout > /tmp/pod-root-cert.crt.txt ----- -+ -[source,terminal] ----- -$ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt ----- -+ -Expect the output to be empty. -+ -. Verify the CA certificate is the same as the one specified by Operator. Replace `<path>` with the path to your certificates. -+ -[source,terminal] ----- -$ sed '0,/^-----END CERTIFICATE-----/d' /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-ca.pem ----- -+ -[source,terminal] ----- -$ openssl x509 -in <path>/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt ----- -+ -[source,terminal] ----- -$ openssl x509 -in /tmp/pod-cert-chain-ca.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt ----- -+ -[source,terminal] ----- -$ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt ----- -+ -Expect the output to be empty. -+ -. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates. -+ -[source,terminal] ----- -$ head -n 21 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-workload.pem ----- -+ -[source,terminal] ----- -$ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) /tmp/pod-cert-chain-workload.pem ----- -+ -.Example output -[source,terminal] ----- -/tmp/pod-cert-chain-workload.pem: OK ----- - -[id="ossm-cert-cleanup_{context}"] -== Removing the certificates - -To remove the certificates you added, follow these steps. - -. Remove the secret `cacerts`. -+ -[source,terminal] ----- -$ oc delete secret cacerts -n istio-system ----- -+ -. Redeploy {ProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource. -+ -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -spec: - dataPlane: - mtls: true ----- diff --git a/modules/ossm-security-cipher.adoc b/modules/ossm-security-cipher.adoc deleted file mode 100644 index 25e23b0d58b9..000000000000 --- a/modules/ossm-security-cipher.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-security.adoc -// * service_mesh/v2x/ossm-security.adoc - -[id="ossm-security-cipher_{context}"] -= Configuring cipher suites and ECDH curves - -Cipher suites and Elliptic-curve Diffie–Hellman (ECDH curves) can help you secure your service mesh. You can define a comma separated list of cipher suites using `spec.istio.global.tls.cipherSuites` and ECDH curves using `spec.istio.global.tls.ecdhCurves` in your `ServiceMeshControlPlane` resource. If either of these attributes are empty, then the default values are used. - -The `cipherSuites` setting is effective if your service mesh uses TLS 1.2 or earlier. It has no effect when negotiating with TLS 1.3. - -Set your cipher suites in the comma separated list in order of priority. For example, `ecdhCurves: CurveP256, CurveP384` sets `CurveP256` as a higher priority than `CurveP384`. - -[NOTE] -==== -You must include either `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` or `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256` when you configure the cipher suite. HTTP/2 support requires at least one of these cipher suites. - -==== - -The supported cipher suites are: - -* TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 -* TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 -* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 -* TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 -* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 -* TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 -* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 -* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA -* TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 -* TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA -* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA -* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA -* TLS_RSA_WITH_AES_128_GCM_SHA256 -* TLS_RSA_WITH_AES_256_GCM_SHA384 -* TLS_RSA_WITH_AES_128_CBC_SHA256 -* TLS_RSA_WITH_AES_128_CBC_SHA -* TLS_RSA_WITH_AES_256_CBC_SHA -* TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA -* TLS_RSA_WITH_3DES_EDE_CBC_SHA - -The supported ECDH Curves are: - -* CurveP256 -* CurveP384 -* CurveP521 -* X25519 diff --git a/modules/ossm-security-mtls-1x.adoc b/modules/ossm-security-mtls-1x.adoc deleted file mode 100644 index a1ef5202c51e..000000000000 --- a/modules/ossm-security-mtls-1x.adoc +++ /dev/null @@ -1,106 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/ossm-security.adoc - -[id="ossm-security-mtls_{context}"] -= Enabling mutual Transport Layer Security (mTLS) - -Mutual Transport Layer Security (mTLS) is a protocol where two parties authenticate each other. It is the default mode of authentication in some protocols (IKE, SSH) and optional in others (TLS). - -mTLS can be used without changes to the application or service code. The TLS is handled entirely by the service mesh infrastructure and between the two sidecar proxies. - -By default, {ProductName} is set to permissive mode, where the sidecars in {ProductShortName} accept both plain-text traffic and connections that are encrypted using mTLS. If a service in your mesh is communicating with a service outside the mesh, strict mTLS could break communication between those services. Use permissive mode while you migrate your workloads to {ProductShortName}. - -[id="ossm-security-enabling-strict-mtls_{context}"] -== Enabling strict mTLS across the mesh - -If your workloads do not communicate with services outside your mesh and communication will not be interrupted by only accepting encrypted connections, you can enable mTLS across your mesh quickly. Set `spec.istio.global.mtls.enabled` to `true` in your `ServiceMeshControlPlane` resource. The operator creates the required resources. - -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshControlPlane -spec: - istio: - global: - mtls: - enabled: true ----- - -[id="ossm-security-mtls-sidecars-incoming-services_{context}"] -=== Configuring sidecars for incoming connections for specific services - -You can also configure mTLS for individual services or namespaces by creating a policy. - -[source,yaml] ----- -apiVersion: "authentication.istio.io/v1alpha1" -kind: "Policy" -metadata: - name: default - namespace: <NAMESPACE> -spec: - peers: - - mtls: {} ----- - -[id="ossm-security-mtls-sidecars-outgoing_{context}"] -== Configuring sidecars for outgoing connections - -Create a destination rule to configure {ProductShortName} to use mTLS when sending requests to other services in the mesh. - -[source,yaml] ----- -apiVersion: "networking.istio.io/v1alpha3" -kind: "DestinationRule" -metadata: - name: "default" - namespace: <CONTROL_PLANE_NAMESPACE>> -spec: - host: "*.local" - trafficPolicy: - tls: - mode: ISTIO_MUTUAL ----- - -[id="ossm-security-min-max-tls_{context}"] -== Setting the minimum and maximum protocol versions - -If your environment has specific requirements for encrypted traffic in your service mesh, you can control the cryptographic functions that are allowed by setting the `spec.security.controlPlane.tls.minProtocolVersion` or `spec.security.controlPlane.tls.maxProtocolVersion` in your `ServiceMeshControlPlane` resource. Those values, configured in your control plane resource, define the minimum and maximum TLS version used by mesh components when communicating securely over TLS. - -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: basic-install - namespace: istio-system -spec: - security: - controlPlane: - tls: - minProtocolVersion: TLSv1_2 - maxProtocolVersion: TLSv1_3 ----- - -The default is `TLS_AUTO` and does not specify a version of TLS. - -.Valid values -|=== -|Value|Description - -|`TLS_AUTO` -| default - -|`TLSv1_0` -|TLS version 1.0 - -|`TLSv1_1` -|TLS version 1.1 - -|`TLSv1_2` -|TLS version 1.2 - -|`TLSv1_3` -|TLS version 1.3 -|=== diff --git a/modules/ossm-security-mtls.adoc b/modules/ossm-security-mtls.adoc deleted file mode 100644 index 003729ee1e96..000000000000 --- a/modules/ossm-security-mtls.adoc +++ /dev/null @@ -1,138 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/ossm-security.adoc - -[id="ossm-security-mtls_{context}"] -= Enabling mutual Transport Layer Security (mTLS) - -Mutual Transport Layer Security (mTLS) is a protocol where two parties authenticate each other. It is the default mode of authentication in some protocols (IKE, SSH) and optional in others (TLS). mTLS can be used without changes to the application or service code. The TLS is handled entirely by the service mesh infrastructure and between the two sidecar proxies. - -By default, mTLS in {ProductName} is enabled and set to permissive mode, where the sidecars in {ProductShortName} accept both plain-text traffic and connections that are encrypted using mTLS. If a service in your mesh is communicating with a service outside the mesh, strict mTLS could break communication between those services. Use permissive mode while you migrate your workloads to {ProductShortName}. Then, you can enable strict mTLS across your mesh, namespace, or application. - -Enabling mTLS across your mesh at the control plane level secures all the traffic in your mesh without rewriting your applications and workflows. You can secure namespaces in your mesh at the data plane level in the `ServiceMeshControlPlane` resource or at the application level with `PeerAuthentication` and `DestinationRule` resources to configure how incoming and outgoing connections encrypt traffic. - -[id="ossm-security-enabling-strict-mtls_{context}"] -== Enabling strict mTLS across the mesh - -You can quickly enable mTLS across your mesh if your workloads do not communicate with outside services, and communication will not be interrupted by accepting only encrypted connections. mTLS for all data plane communication is disabled by default. You can enable it by setting `spec.security.dataPlane.mtls` to `true` in the `ServiceMeshControlPlane` resource. The Operator creates the required resources. - -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -spec: - version: v2.0 - security: - dataPlane: - mtls: true ----- - -You can also enable mTLS by using the {product-title} web console. - -.Procedure - -. Log in to the web console. - -. Click the *Project* menu and choose the `istio-system` project from the list. - -. Click *Operators* -> *Installed Operators*. - -. Click on *Service Mesh Control Plane* under *Provided APIs*. - -. Click the name of your `ServiceMeshControlPlane` resource, for example, `production`. - -. On the Details page, click the toggle in the *Security* section for *Data Plane Security*. - -[id="ossm-security-mtls-sidecars-incoming-services_{context}"] -=== Configuring sidecars for incoming connections for specific services - -You can also configure mTLS for individual services or namespaces by creating a policy. - -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: PeerAuthentication -metadata: - name: default - namespace: <namespace> -spec: - mtls: - mode: STRICT ----- - -[NOTE] -==== -If you are not using automatic mTLS and you are setting PeerAuthentication to STRICT, you must create a `DestinationRule` resource for your service. -==== - -[id="ossm-security-mtls-sidecars-outgoing_{context}"] -== Configuring sidecars for outgoing connections - -Create a destination rule to configure {ProductShortName} to use mTLS when sending requests to other services in the mesh. - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: DestinationRule -metadata: - name: default - namespace: <namespace> -spec: - host: "*.<namespace>.svc.cluster.local" - trafficPolicy: - tls: - mode: ISTIO_MUTUAL ----- - -[id="ossm-security-min-max-tls_{context}"] -== Setting the minimum and maximum protocol versions - -If your environment has specific requirements for encrypted traffic in your service mesh, you can control the cryptographic functions that are allowed by setting the `spec.security.controlPlane.tls.minProtocolVersion` or `spec.security.controlPlane.tls.maxProtocolVersion` in your `ServiceMeshControlPlane` resource. Those values, configured in your control plane resource, define the minimum and maximum TLS version used by mesh components when communicating securely over TLS. - -[source,yaml] ----- -kind: ServiceMeshControlPlane -spec: - security: - controlPlane: - tls: - minProtocolVersion: TLSv1_2 ----- - -The default is `TLS_AUTO` and does not specify a version of TLS. - -.Valid values -|=== -|Value|Description - -|`TLS_AUTO` -| default - -|`TLSv1_0` -|TLS version 1.0 - -|`TLSv1_1` -|TLS version 1.1 - -|`TLSv1_2` -|TLS version 1.2 - -|`TLSv1_3` -|TLS version 1.3 -|=== - -[id="ossm-security-enabling-controlplane_{context}"] -== Enabling strict mTLS for Mixer telemetry or policy components - -Secure connections are always used when proxies communicate with the control plane regardless of the `spec.security.controlPlane.mtls` setting. If you use Mixer telemetry or policy, set `spec.security.controlPlane.mtls` to `true` in your `ServiceMeshControlPlane` resource to enable strict mTLS. - -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -spec: - version: v2.0 - security: - controlPlane: - mtls: true ----- diff --git a/modules/ossm-servicemesh-overview.adoc b/modules/ossm-servicemesh-overview.adoc deleted file mode 100644 index 8440770cc624..000000000000 --- a/modules/ossm-servicemesh-overview.adoc +++ /dev/null @@ -1,22 +0,0 @@ -//// -Module included in the following assemblies: -* service_mesh/v1x/ossm-architecture.adoc -* service_mesh/v2x/ossm-architecture.adoc -* service_mesh/v1x/servicemesh-release-notes.adoc -* service_mesh/v2x/servicemesh-release-notes.adoc -//// - -[id="ossm-servicemesh-overview_{context}"] -= {ProductName} overview - -{ProductName} is a platform that provides behavioral insight and operational control over the service mesh, providing a uniform way to connect, secure, and monitor microservice applications. - -The term _service mesh_ describes the network of microservices that make up applications in a distributed microservice architecture and the interactions between those microservices. As a service mesh grows in size and complexity, it can become harder to understand and manage. - -Based on the open source link:https://istio.io/[Istio] project, {ProductName} adds a transparent layer on existing distributed applications without requiring any changes to the service code. You add {ProductName} support to services by deploying a special sidecar proxy throughout your environment that intercepts all network communication between microservices. You configure and manage the service mesh using the control plane features. - -{ProductName} provides an easy way to create a network of deployed services that provides discovery, load balancing, service-to-service authentication, failure recovery, metrics, and monitoring. A service mesh also provides more complex operational functionality, including A/B testing, canary releases, rate limiting, access control, and end-to-end authentication. - -== Making open source more inclusive - -Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see link:https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language[our CTO Chris Wright's message]. diff --git a/modules/ossm-sidecar-injection.adoc b/modules/ossm-sidecar-injection.adoc deleted file mode 100644 index 59e40bde4a08..000000000000 --- a/modules/ossm-sidecar-injection.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -// * service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc - -[id="ossm-sidecar-injection_{context}"] -= {ProductName}'s sidecar injection - -{ProductName} relies on a proxy sidecar within the application's pod to provide {ProductShortName} capabilities to the application. You can enable automatic sidecar injection or manage it manually. Red Hat recommends automatic injection using the annotation with no need to label projects. This ensures that your application contains the appropriate configuration for the {ProductShortName} upon deployment. This method requires fewer privileges and does not conflict with other OpenShift capabilities such as builder pods. - -[NOTE] -==== -The upstream version of Istio injects the sidecar by default if you have labeled the project. {ProductName} requires you to opt in to having the sidecar automatically injected to a deployment, so you are not required to label the project. This avoids injecting a sidecar if it is not wanted (for example, in build or deploy pods). - -The webhook checks the configuration of pods deploying into all projects to see if they are opting in to injection with the appropriate annotation. -==== - -[id="ossm-sidecar-injection-env-var_{context}"] -== Setting environment variables on the proxy in applications through annotations - -You can set environment variables on the sidecar proxy for applications by adding pod annotations in the deployment in the `injection-template.yaml` file. The environment variables are injected to the sidecar. - -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: resource -spec: - replicas: 7 - selector: - matchLabels: - app: resource - template: - metadata: - annotations: - sidecar.maistra.io/proxyEnv: "{ \"maistra_test_env\": \"env_value\", \"maistra_test_env_2\": \"env_value_2\" }" ----- - -[WARNING] -==== -`maistra.io/` labels and annotations should never be included in user-created resources, because they indicate that the resources are generated and managed by the Operator. If you are copying content from an Operator-generated resource when creating your own resources, do not include labels or annotations that start with `maistra.io/` or your resource will be overwritten or deleted by the Operator during the next reconciliation. -==== \ No newline at end of file diff --git a/modules/ossm-supported-configurations-v1x.adoc b/modules/ossm-supported-configurations-v1x.adoc deleted file mode 100644 index 0b744f8ae251..000000000000 --- a/modules/ossm-supported-configurations-v1x.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/preparing-ossm-install.adoc -// * service_mesh/v1x/servicemesh-release-notes.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="ossm-supported-configurations-v1x_{context}"] -= {ProductName} supported configurations - -The following are the only supported configurations for the {ProductName}: - -* Red Hat {product-title} version 4.x. - -[NOTE] -==== -OpenShift Online and OpenShift Dedicated are not supported for {ProductName}. -==== - -* The deployment must be contained to a single {product-title} cluster that is not federated. -* This release of {ProductName} is only available on {product-title} x86_64. -* This release only supports configurations where all {ProductShortName} components are contained in the OpenShift cluster in which it operates. It does not support management of microservices that reside outside of the cluster, or in a multi-cluster scenario. -* This release only supports configurations that do not integrate external services such as virtual machines. - -For additional information about {ProductName} lifecycle and supported configurations, refer to the link:https://access.redhat.com/support/policy/updates/openshift#ossm[Support Policy]. - -[id="ossm-supported-configurations-kiali_{context}"] -== Supported configurations for Kiali on {ProductName} - -* The Kiali observability console is only supported on the two most recent releases of the Chrome, Edge, Firefox, or Safari browsers. - -[id="ossm-supported-configurations-adapters_{context}"] -== Supported Mixer adapters - -* This release only supports the following Mixer adapter: -** 3scale Istio Adapter diff --git a/modules/ossm-supported-configurations.adoc b/modules/ossm-supported-configurations.adoc deleted file mode 100644 index 0e4f91d6828f..000000000000 --- a/modules/ossm-supported-configurations.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v2x/preparing-ossm-install.adoc -// * service_mesh/v2x/servicemesh-release-notes.adoc -// * post_installation_configuration/network-configuration.adoc (once 2.0 released) - -[id="ossm-supported-configurations_{context}"] -= {ProductName} supported configurations - -The following are the only supported configurations for the {ProductName}: - -* Red Hat {product-title} version 4.x. - -[NOTE] -==== -OpenShift Online and OpenShift Dedicated are not supported for {ProductName}. -==== - -* The deployment must be contained to a single {product-title} cluster that is not federated. -* This release of {ProductName} is only available on {product-title} x86_64, IBM Z, and IBM Power Systems. -** IBM Z is only supported on {product-title} 4.6 and later. -** IBM Power Systems is only supported on {product-title} 4.6 and later. -* This release only supports configurations where all {ProductShortName} components are contained in the OpenShift cluster in which it operates. It does not support management of microservices that reside outside of the cluster, or in a multi-cluster scenario. -* This release only supports configurations that do not integrate external services such as virtual machines. - -For additional information about {ProductName} lifecycle and supported configurations, refer to the link:https://access.redhat.com/support/policy/updates/openshift#ossm[Support Policy]. - -[id="ossm-supported-configurations-networks_{context}"] -== Supported network configurations - -{ProductName} supports the following network configurations. - -* Openshift-SDN -* OVN-Kubernetes is supported as a technology preview in {product-title} version 4.7. - -[id="ossm-supported-configurations-kiali_{context}"] -== Supported configurations for Kiali on {ProductName} - -* The Kiali observability console is only supported on the two most recent releases of the Chrome, Edge, Firefox, or Safari browsers. - -[id="ossm-supported-configurations-adapters_{context}"] -== Supported Mixer adapters - -* This release only supports the following Mixer adapter: -** 3scale Istio Adapter diff --git a/modules/ossm-threescale-authentication.adoc b/modules/ossm-threescale-authentication.adoc deleted file mode 100644 index 96d19f133ab9..000000000000 --- a/modules/ossm-threescale-authentication.adoc +++ /dev/null @@ -1,161 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-authentication_{context}"] -= Authenticating requests -This release supports the following authentication methods: - -* *Standard API Keys*: single randomized strings or hashes acting as an identifier and a secret token. -* *Application identifier and key pairs*: immutable identifier and mutable secret key strings. -* *OpenID authentication method*: client ID string parsed from the JSON Web Token. - - -[id="ossm-threescale-authentication-patterns_{context}"] -== Applying authentication patterns -Modify the `instance` custom resource, as illustrated in the following authentication method examples, to configure authentication behavior. You can accept the authentication credentials from: - -* Request headers -* Request parameters -* Both request headers and query parameters - -[NOTE] -==== -When specifying values from headers, they must be lower case. For example, if you want to send a header as `User-Key`, this must be referenced in the configuration as `request.headers["user-key"]`. -==== - -[id="ossm-threescale-apikey-authentication_{context}"] -=== API key authentication method -{ProductShortName} looks for the API key in query parameters and request headers as specified in the `user` option in the `subject` custom resource parameter. It checks the values in the order given in the custom resource file. You can restrict the search for the API key to either query parameters or request headers by omitting the unwanted option. - -In this example, {ProductShortName} looks for the API key in the `user_key` query parameter. If the API key is not in the query parameter, {ProductShortName} then checks the `user-key` header. - -.API key authentication method example - -[source,yaml] ----- -apiVersion: "config.istio.io/v1alpha2" -kind: instance -metadata: - name: threescale-authorization - namespace: istio-system -spec: - template: authorization - params: - subject: - user: request.query_params["user_key"] | request.headers["user-key"] | "" - action: - path: request.url_path - method: request.method | "get" ----- - -If you want the adapter to examine a different query parameter or request header, change the name as appropriate. For example, to check for the API key in a query parameter named “key”, change `request.query_params["user_key"]` to `request.query_params["key"]`. - -[id="ossm-threescale-appidapikey-authentication_{context}"] -=== Application ID and application key pair authentication method -{ProductShortName} looks for the application ID and application key in query parameters and request headers, as specified in the `properties` option in the `subject` custom resource parameter. The application key is optional. It checks the values in the order given in the custom resource file. You can restrict the search for the credentials to either query parameters or request headers by not including the unwanted option. - -In this example, {ProductShortName} looks for the application ID and application key in the query parameters first, moving on to the request headers if needed. - -.Application ID and application key pair authentication method example - -[source,yaml] ----- -apiVersion: "config.istio.io/v1alpha2" -kind: instance -metadata: - name: threescale-authorization - namespace: istio-system -spec: - template: authorization - params: - subject: - app_id: request.query_params["app_id"] | request.headers["app-id"] | "" - app_key: request.query_params["app_key"] | request.headers["app-key"] | "" - action: - path: request.url_path - method: request.method | "get" ----- - -If you want the adapter to examine a different query parameter or request header, change the name as appropriate. For example, to check for the application ID in a query parameter named `identification`, change `request.query_params["app_id"]` to `request.query_params["identification"]`. - -[id="ossm-threescale-openid-authentication_{context}"] -=== OpenID authentication method -To use the _OpenID Connect (OIDC) authentication method_, use the `properties` value on the `subject` field to set `client_id`, and optionally `app_key`. - -You can manipulate this object using the methods described previously. In the example configuration shown below, the client identifier (application ID) is parsed from the JSON Web Token (JWT) under the label _azp_. You can modify this as needed. - -.OpenID authentication method example - -[source,yaml] ----- - apiVersion: "config.istio.io/v1alpha2" - kind: instance - metadata: - name: threescale-authorization - spec: - template: threescale-authorization - params: - Subject: - properties: - app_key: request.query_params["app_key"] | request.headers["app-key"] | "" - client_id: request.auth.claims["azp"] | "" - action: - path: request.url_path - method: request.method | "get" - service: destination.labels["service-mesh.3scale.net/service-id"] | "" ----- - -For this integration to work correctly, OIDC must still be done in 3scale for the client to be created in the identity provider (IdP). You should create a link:https://istio.io/latest/docs/tasks/security/authorization/authz-jwt/[Request authorization] for the service you want to protect in the same namespace as that service. The JWT is passed in the `Authorization` header of the request. - -In the sample `RequestAuthentication` defined below, replace `issuer`, `jwksUri`, and `selector` as appropriate. - -.OpenID Policy example - -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: RequestAuthentication -metadata: - name: jwt-example - namespace: bookinfo -spec: - selector: - matchLabels: - app: productpage - jwtRules: - - issuer: >- - http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak - jwksUri: >- - http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak/protocol/openid-connect/certs ----- - -[id="ossm-threescale-hybrid-authentication_{context}"] -=== Hybrid authentication method -You can choose to not enforce a particular authentication method and accept any valid credentials for either method. If both an API key and an application ID/application key pair are provided, {ProductShortName} uses the API key. - -In this example, {ProductShortName} checks for an API key in the query parameters, then the request headers. If there is no API key, it then checks for an application ID and key in the query parameters, then the request headers. - -.Hybrid authentication method example - -[source,yaml] ----- -apiVersion: "config.istio.io/v1alpha2" -kind: instance -metadata: - name: threescale-authorization -spec: - template: authorization - params: - subject: - user: request.query_params["user_key"] | request.headers["user-key"] | - properties: - app_id: request.query_params["app_id"] | request.headers["app-id"] | "" - app_key: request.query_params["app_key"] | request.headers["app-key"] | "" - client_id: request.auth.claims["azp"] | "" - action: - path: request.url_path - method: request.method | "get" - service: destination.labels["service-mesh.3scale.net/service-id"] | "" ----- diff --git a/modules/ossm-threescale-caching.adoc b/modules/ossm-threescale-caching.adoc deleted file mode 100644 index 92ca525838ca..000000000000 --- a/modules/ossm-threescale-caching.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-caching_{context}"] -= Caching behavior -Responses from 3scale System APIs are cached by default within the adapter. Entries will be purged from the cache when they become older than the `cacheTTLSeconds` value. Also by default, automatic refreshing of cached entries will be attempted seconds before they expire, based on the `cacheRefreshSeconds` value. You can disable automatic refreshing by setting this value higher than the `cacheTTLSeconds` value. - -Caching can be disabled entirely by setting `cacheEntriesMax` to a non-positive value. - -By using the refreshing process, cached values whose hosts become unreachable will be retried before eventually being purged when past their expiry. diff --git a/modules/ossm-threescale-cr.adoc b/modules/ossm-threescale-cr.adoc deleted file mode 100644 index 23e75ebdf9fc..000000000000 --- a/modules/ossm-threescale-cr.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-cr_{context}"] -= Generating 3scale custom resources - -The adapter includes a tool that allows you to generate the `handler`, `instance`, and `rule` custom resources. - -.Usage -|=== -|Option |Description |Required | Default value - -|`-h, --help` -|Produces help output for available options -|No -| - -|`--name` -|Unique name for this URL, token pair -|Yes -| - -|`-n, --namespace` -|Namespace to generate templates -|No -|istio-system - -|`-t, --token` -|3scale access token -|Yes -| - -|`-u, --url` -|3scale Admin Portal URL -|Yes -| - -|`--backend-url` -|3scale backend URL. If set, it overrides the value that is read from system configuration -|No -| - -|`-s, --service` -|3scale API/Service ID -|No -| - -|`--auth` -|3scale authentication pattern to specify (1=API Key, 2=App Id/App Key, 3=OIDC) -|No -|Hybrid - -|`-o, --output` -|File to save produced manifests to -|No -|Standard output - -|`--version` -|Outputs the CLI version and exits immediately -|No -| -|=== diff --git a/modules/ossm-threescale-integrate-1x.adoc b/modules/ossm-threescale-integrate-1x.adoc deleted file mode 100644 index d5d6f0b885e0..000000000000 --- a/modules/ossm-threescale-integrate-1x.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-integrate-1x_{context}"] -= Integrate the 3scale adapter with {ProductName} - -You can use these examples to configure requests to your services using the 3scale Istio Adapter. - - -.Prerequisites: - -* {ProductName} version 1.x -* A working 3scale account (link:https://www.3scale.net/signup/[SaaS] or link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.5/html/installing_3scale/onpremises-installation[3scale 2.5 On-Premises]) -* Enabling backend cache requires 3scale 2.9 or greater -* {ProductName} prerequisites - -[NOTE] -==== -To configure the 3scale Istio Adapter, refer to {ProductName} custom resources for instructions on adding adapter parameters to the custom resource file. -==== - - -[NOTE] -==== -Pay particular attention to the `kind: handler` resource. You must update this with your 3scale credentials and the service ID of the API you want to manage. -==== - -. Modify the handler configuration with your 3scale configuration. -+ -.Handler configuration example -[source,yaml] ----- - apiVersion: "config.istio.io/v1alpha2" - kind: handler - metadata: - name: threescale - spec: - adapter: threescale - params: - service_id: "<SERVICE_ID>" - system_url: "https://<organization>-admin.3scale.net/" - access_token: "<ACCESS_TOKEN>" - connection: - address: "threescale-istio-adapter:3333" ----- - -Optionally, you can provide a `backend_url` field within the _params_ section to override the URL provided by the 3scale configuration. This may be useful if the adapter runs on the same cluster as the 3scale on-premise instance, and you wish to leverage the internal cluster DNS. - -. Modify the rule configuration with your 3scale configuration to dispatch the rule to the threescale handler. -+ -.Rule configuration example -[source,yaml] ----- - apiVersion: "config.istio.io/v1alpha2" - kind: rule - metadata: - name: threescale - spec: - match: destination.labels["service-mesh.3scale.net"] == "true" - actions: - - handler: threescale.handler - instances: - - threescale-authorization.instance ----- diff --git a/modules/ossm-threescale-integrate.adoc b/modules/ossm-threescale-integrate.adoc deleted file mode 100644 index 86e109c3d398..000000000000 --- a/modules/ossm-threescale-integrate.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-integrate_{context}"] -= Integrate the 3scale adapter with {ProductName} - -You can use these examples to configure requests to your services using the 3scale Istio Adapter. - - -.Prerequisites: - -* {ProductName} version 2.x -* A working 3scale account (link:https://www.3scale.net/signup/[SaaS] or link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.9/html/installing_3scale/install-threescale-on-openshift-guide[3scale 2.9 On-Premises]) -* Enabling backend cache requires 3scale 2.9 or greater -* {ProductName} prerequisites -* Ensure Mixer policy enforcement is enabled. Update Mixer policy enforcement section provides instructions to check the current Mixer policy enforcement status and enable policy enforcement. -* Mixer policy and telemetry must be enabled if you are using a mixer plug-in. -** You will need to properly configure the Service Mesh Control Plane (SMCP) when upgrading. - -[NOTE] -==== -To configure the 3scale Istio Adapter, refer to {ProductName} custom resources for instructions on adding adapter parameters to the custom resource file. -==== - - -[NOTE] -==== -Pay particular attention to the `kind: handler` resource. You must update this with your 3scale credentials and the service ID of the API you want to manage. -==== - -. Modify the handler configuration with your 3scale configuration. -+ -.Handler configuration example -[source,yaml] ----- - apiVersion: "config.istio.io/v1alpha2" - kind: handler - metadata: - name: threescale - spec: - adapter: threescale - params: - service_id: "<SERVICE_ID>" - system_url: "https://<organization>-admin.3scale.net/" - access_token: "<ACCESS_TOKEN>" - connection: - address: "threescale-istio-adapter:3333" ----- - -Optionally, you can provide a `backend_url` field within the _params_ section to override the URL provided by the 3scale configuration. This may be useful if the adapter runs on the same cluster as the 3scale on-premise instance, and you wish to leverage the internal cluster DNS. - -. Modify the rule configuration with your 3scale configuration to dispatch the rule to the threescale handler. -+ -.Rule configuration example -[source,yaml] ----- - apiVersion: "config.istio.io/v1alpha2" - kind: rule - metadata: - name: threescale - spec: - match: destination.labels["service-mesh.3scale.net"] == "true" - actions: - - handler: threescale.handler - instances: - - threescale-authorization.instance ----- diff --git a/modules/ossm-threescale-integration-settings.adoc b/modules/ossm-threescale-integration-settings.adoc deleted file mode 100644 index c41c33bb254f..000000000000 --- a/modules/ossm-threescale-integration-settings.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-integration-settings_{context}"] -= Configure the integration settings in 3scale - -Follow this procedure to configure the 3scale integration settings. - -[NOTE] -==== -For 3scale SaaS customers, {ProductName} is enabled as part of the Early Access program. -==== - -.Procedure - -. Navigate to *[your_API_name]* -> *Integration* -> *Configuration*. - -. At the top of the *Integration* page click on *edit integration settings* in the top right corner. - -. Under the *Service Mesh* heading, click the *Istio* option. - -. Scroll to the bottom of the page and click *Update Service*. diff --git a/modules/ossm-threescale-manifests.adoc b/modules/ossm-threescale-manifests.adoc deleted file mode 100644 index 07829e464337..000000000000 --- a/modules/ossm-threescale-manifests.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-manifests_{context}"] -= Generating manifests from a deployed adapter - - -. Run this command to generate manifests from a deployed adapter in the `istio-system` namespace: -+ ----- -$ export NS="istio-system" URL="https://replaceme-admin.3scale.net/" NAME="name" TOKEN="token" -oc exec -n ${NS} $(oc get po -n ${NS} -o jsonpath='{.items[?(@.metadata.labels.app=="3scale-istio-adapter")].metadata.name}') \ --it -- ./3scale-config-gen \ ---url ${URL} --name ${NAME} --token ${TOKEN} -n ${NS} ----- - -. This will produce sample output to the terminal. Edit these samples if required and create the objects using the `oc create` command. - -. When the request reaches the adapter, the adapter needs to know how the service maps to an API on 3scale. You can provide this information in two ways: - -.. Label the workload (recommended) -.. Hard code the handler as `service_id` - - -. Update the workload with the required annotations: -+ -[NOTE] -==== -You only need to update the service ID provided in this example if it is not already embedded in the handler. *The setting in the handler takes precedence*. -==== -+ ----- -$ export CREDENTIALS_NAME="replace-me" -export SERVICE_ID="replace-me" -export DEPLOYMENT="replace-me" -patch="$(oc get deployment "${DEPLOYMENT}" -patch="$(oc get deployment "${DEPLOYMENT}" --template='{"spec":{"template":{"metadata":{"labels":{ {{ range $k,$v := .spec.template.metadata.labels }}"{{ $k }}":"{{ $v }}",{{ end }}"service-mesh.3scale.net/service-id":"'"${SERVICE_ID}"'","service-mesh.3scale.net/credentials":"'"${CREDENTIALS_NAME}"'"}}}}}' )" -oc patch deployment "${DEPLOYMENT}" --patch ''"${patch}"'' - ----- diff --git a/modules/ossm-threescale-metrics-1x.adoc b/modules/ossm-threescale-metrics-1x.adoc deleted file mode 100644 index 888d6a900c80..000000000000 --- a/modules/ossm-threescale-metrics-1x.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-metrics-1x_{context}"] -= 3scale Adapter metrics -The adapter, by default reports various Prometheus metrics that are exposed on port `8080` at the `/metrics` endpoint. These metrics provide insight into how the interactions between the adapter and 3scale are performing. The service is labeled to be automatically discovered and scraped by Prometheus. diff --git a/modules/ossm-threescale-metrics.adoc b/modules/ossm-threescale-metrics.adoc deleted file mode 100644 index dbb58e45d60a..000000000000 --- a/modules/ossm-threescale-metrics.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-metrics_{context}"] -= 3scale Adapter metrics -The adapter, by default reports various Prometheus metrics that are exposed on port `8080` at the `/metrics` endpoint. These metrics provide insight into how the interactions between the adapter and 3scale are performing. The service is labeled to be automatically discovered and scraped by Prometheus. - -NOTE: There are incompatible changes in the 3scale Istio Adapter metrics since the previous releases in Service Mesh 1.x. - -In Prometheus, metrics have been renamed with one addition for the backend cache, so that the following metrics exist as of Service Mesh 2.0: - -.Prometheus metrics -|=== -|Metric |Type |Description - -|`threescale_latency` -|Histogram -|Request latency between adapter and 3scale. - -|`threescale_http_total` -|Counter -|HTTP Status response codes for requests to 3scale backend. - -|`threescale_system_cache_hits` -|Counter -|Total number of requests to the 3scale system fetched from the configuration cache. - -|`threescale_backend_cache_hits` -|Counter -|Total number of requests to 3scale backend fetched from the backend cache. -|=== diff --git a/modules/ossm-threescale-routing.adoc b/modules/ossm-threescale-routing.adoc deleted file mode 100644 index 9fd723079b23..000000000000 --- a/modules/ossm-threescale-routing.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-routing_{context}"] -= Routing service traffic through the adapter -Follow these steps to drive traffic for your service through the 3scale adapter. - -.Prerequisites - -* Credentials and service ID from your 3scale administrator. - -.Procedure - -. Match the rule `destination.labels["service-mesh.3scale.net/credentials"] == "threescale"` that you previously created in the configuration, in the `kind: rule` resource. - -. Add the above label to `PodTemplateSpec` on the Deployment of the target workload to integrate a service. the value, `threescale`, refers to the name of the generated handler. This handler stores the access token required to call 3scale. - -. Add the `destination.labels["service-mesh.3scale.net/service-id"] == "replace-me"` label to the workload to pass the service ID to the adapter via the instance at request time. diff --git a/modules/ossm-threescale-templates.adoc b/modules/ossm-threescale-templates.adoc deleted file mode 100644 index cbbae2303a37..000000000000 --- a/modules/ossm-threescale-templates.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="ossm-threescale-templates_{context}"] -= Generate templates from URL examples - -* This example generates templates allowing the token, URL pair to be shared by multiple services as a single handler: -+ ----- -$ 3scale-gen-config --name=admin-credentials --url="https://<organization>-admin.3scale.net:443" --token="[redacted]" ----- - -* This example generates the templates with the service ID embedded in the handler: -+ ----- -$ 3scale-gen-config --url="https://<organization>-admin.3scale.net" --name="my-unique-id" --service="123456789" --token="[redacted]" ----- diff --git a/modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc b/modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc deleted file mode 100644 index b17149817c21..000000000000 --- a/modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc +++ /dev/null @@ -1,29 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -* service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc -//// - -[id="ossm-tutorial-bookinfo-adding-destination-rules_{context}"] -= Adding default destination rules - -Before you can use the Bookinfo application, you have to add default destination rules. There are two preconfigured YAML files, depending on whether or not you enabled mutual transport layer security (TLS) authentication. - -.Procedure - -. To add destination rules, run one of the following commands: -** If you did not enable mutual TLS: -+ - -[source,bash,subs="attributes"] ----- -$ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-{MaistraVersion}/samples/bookinfo/networking/destination-rule-all.yaml ----- - -** If you enabled mutual TLS: -+ - -[source,bash,subs="attributes"] ----- -$ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-{MaistraVersion}/samples/bookinfo/networking/destination-rule-all-mtls.yaml ----- diff --git a/modules/ossm-tutorial-bookinfo-install.adoc b/modules/ossm-tutorial-bookinfo-install.adoc deleted file mode 100644 index 26e190f6ad5b..000000000000 --- a/modules/ossm-tutorial-bookinfo-install.adoc +++ /dev/null @@ -1,119 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -* service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc -//// - -[id="ossm-tutorial-bookinfo-install_{context}"] -= Installing the Bookinfo application - -This tutorial walks you through creating a Bookinfo project, deploying the Bookinfo application, and running Bookinfo on {product-title} with {ProductShortName} {ProductVersion}. - -[WARNING] -==== -The Bookinfo example application allows you to test your {ProductName} {ProductVersion} installation on {product-title}. - -Red Hat does not provide support for the Bookinfo application. -==== - -[NOTE] -==== -The Bookinfo sample application cannot be installed on IBM Z and IBM Power Systems. -==== - -.Prerequisites: - -* {product-title} 4.1 or higher installed. -* {ProductName} {ProductVersion} installed. -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - -[NOTE] -==== -{ProductName} implements auto-injection differently than the upstream Istio project, therefore this procedure uses a version of the `bookinfo.yaml` file annotated to enable automatic injection of the Istio sidecar for {ProductName}. -==== - -.Procedure - -. Log in to the {product-title} web console as a user with cluster-admin rights. - -. Click to *Home* -> *Projects*. - -. Click *Create Project*. - -. Enter `bookinfo` as the *Project Name*, enter a *Display Name*, and enter a *Description*, then click *Create*. -+ -** Alternatively, you can run this command from the CLI to create the `bookinfo` project. -+ -[source,terminal] ----- -$ oc new-project bookinfo ----- -+ -. Click *Operators* -> *Installed Operators*. - -. Click the *Project* menu and use the control plane namespace. In this example, use `istio-system`. - -. Click the *{ProductName}* Operator. - -. Click the *Istio Service Mesh Member Roll* link. - -.. If you have already created a Istio Service Mesh Member Roll, click the name, then click the YAML tab to open the YAML editor. - -.. If you have not created a Istio Service Mesh Member Roll, click *Create Service Mesh Member Roll*. -+ -[NOTE] -==== -You need cluster-admin rights to edit the Istio Service Mesh Member Roll. -==== -+ -. Edit the default Service Mesh Member Roll YAML and add `bookinfo` to the *members* list. -+ -.Bookinfo ServiceMeshMemberRoll example - -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshMemberRoll -metadata: - name: default -spec: - members: - - bookinfo ----- -+ -** Alternatively, you can run this command from the CLI to add the `bookinfo` project to the `ServiceMeshMemberRoll`. Replace `<control_plane_project>` with the name of your control plane project. -+ -[source,terminal] ----- -$ oc -n <control_plane_project> patch --type='json' smmr default -p '[{"op": "add", "path": "/spec/members", "value":["'"bookinfo"'"]}]' ----- -+ -. Click *Create* to save the updated Service Mesh Member Roll. - -. From the CLI, deploy the Bookinfo application in the _`bookinfo`_ project by applying the `bookinfo.yaml` file: -+ - -[source,bash,subs="attributes"] ----- -$ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-{MaistraVersion}/samples/bookinfo/platform/kube/bookinfo.yaml ----- -+ -. Create the ingress gateway by applying the `bookinfo-gateway.yaml` file: -+ - -[source,bash,subs="attributes"] ----- -$ oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-{MaistraVersion}/samples/bookinfo/networking/bookinfo-gateway.yaml ----- -+ -. Set the value for the `GATEWAY_URL` parameter: -+ -[NOTE] -==== -Replace `<control_plane_project>` with the name of your control plane project. In this example, the control plane project is `istio-system`. -==== -+ -[source,terminal] ----- -$ export GATEWAY_URL=$(oc -n <control_plane_project> get route istio-ingressgateway -o jsonpath='{.spec.host}') ----- diff --git a/modules/ossm-tutorial-bookinfo-overview.adoc b/modules/ossm-tutorial-bookinfo-overview.adoc deleted file mode 100644 index b0966bff617f..000000000000 --- a/modules/ossm-tutorial-bookinfo-overview.adoc +++ /dev/null @@ -1,23 +0,0 @@ -//// -This CONCEPT module included in the following assemblies: -* service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc -//// - -[id="ossm-tutorial-bookinfo-overview_{context}"] -= Bookinfo example application - -The upstream Istio project has an example tutorial called https://istio.io/docs/examples/bookinfo[Bookinfo], which is composed of four separate microservices used to demonstrate various Istio features. The Bookinfo application displays information about a book, similar to a single catalog entry of an online book store. Displayed on the page is a description of the book, book details (ISBN, number of pages, and other information), and book reviews. - -The Bookinfo application consists of these microservices: - -* The `productpage` microservice calls the `details` and `reviews` microservices to populate the page. -* The `details` microservice contains book information. -* The `reviews` microservice contains book reviews. It also calls the `ratings` microservice. -* The `ratings` microservice contains book ranking information that accompanies a book review. - -There are three versions of the reviews microservice: - -* Version v1 does not call the `ratings` Service. -* Version v2 calls the `ratings` Service and displays each rating as one to five black stars. -* Version v3 calls the `ratings` Service and displays each rating as one to five red stars. diff --git a/modules/ossm-tutorial-bookinfo-removing.adoc b/modules/ossm-tutorial-bookinfo-removing.adoc deleted file mode 100644 index f145dcae23d3..000000000000 --- a/modules/ossm-tutorial-bookinfo-removing.adoc +++ /dev/null @@ -1,62 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -* service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc -//// - -[id="ossm-tutorial-bookinfo-removing_{context}"] -= Removing the Bookinfo application - -Follow these steps to remove the Bookinfo application. - -.Prerequisites - -* {product-title} 4.1 or higher installed. -* {ProductName} {ProductVersion} installed. -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - -[id="ossm-delete-bookinfo-project_{context}"] -== Delete the Bookinfo project - -.Procedure - -. Log in to the {product-title} web console. - -. Click to *Home* -> *Projects*. - -. Click on the `bookinfo` menu {kebab}, and then click *Delete Project*. - -. Type `bookinfo` in the confirmation dialog box, and then click *Delete*. -+ -** Alternatively, you can run this command from the CLI to create the `bookinfo` project. -+ -[source,terminal] ----- -$ oc delete project bookinfo ----- - -[id="ossm-remove-bookinfo-smmr_{context}"] -== Remove the Bookinfo project from the {ProductShortName} member roll - -.Procedure - -. Log in to the {product-title} web console. - -. Click *Operators* -> *Installed Operators*. - -. Click the *Project* menu and choose `openshift-operators` from the list. - -. Click the *Istio Service Mesh Member Roll* link under *Provided APIS* for the *{ProductName}* Operator. - -. Click the `ServiceMeshMemberRoll` menu {kebab} and select *Edit Service Mesh Member Roll*. - -. Edit the default Service Mesh Member Roll YAML and remove `bookinfo` from the *members* list. -+ -** Alternatively, you can run this command from the CLI to remove the `bookinfo` project from the `ServiceMeshMemberRoll`. Replace `<control_plane_project>` with the name of your control plane project. -+ -[source,terminal] ----- -$ oc -n <control_plane_project> patch --type='json' smmr default -p '[{"op": "remove", "path": "/spec/members", "value":["'"bookinfo"'"]}]' ----- - -. Click *Save* to update Service Mesh Member Roll. diff --git a/modules/ossm-tutorial-bookinfo-verify-install.adoc b/modules/ossm-tutorial-bookinfo-verify-install.adoc deleted file mode 100644 index af7673036740..000000000000 --- a/modules/ossm-tutorial-bookinfo-verify-install.adoc +++ /dev/null @@ -1,34 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -* service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc -//// - -[id="ossm-tutorial-bookinfo-verify-install_{context}"] -= Verifying the Bookinfo installation - -Before configuring your application, verify that it successfully deployed. - -.Prerequisites - -* {product-title} 4.1 or higher installed. -* {ProductName} {ProductVersion} installed. -* Access to the {product-title} Command-line Interface (CLI) also known as `oc`. - -.Procedure - -. Log in to the {product-title} CLI. - -. Run this command to confirm that Bookinfo is deployed: -+ ----- -$ curl -o /dev/null -s -w "%{http_code}\n" http://$GATEWAY_URL/productpage ----- -+ -** Alternatively, you can open `http://$GATEWAY_URL/productpage` in your browser. -** You can also verify that all pods are ready with this command: -+ -[source,terminal] ----- -$ oc get pods -n bookinfo ----- diff --git a/modules/ossm-tutorial-grafana-accessing.adoc b/modules/ossm-tutorial-grafana-accessing.adoc deleted file mode 100644 index c1b0dcafed7f..000000000000 --- a/modules/ossm-tutorial-grafana-accessing.adoc +++ /dev/null @@ -1,54 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- ossm-tutorial-grafana.adoc -//// - -[id="ossm-tutorial-grafana-accessing_{context}"] -= Accessing the Grafana dashboard - -The Grafana dashboard's web-based interface lets you visualize your metrics data. - -.Prerequisites: - -* {product-title} 3.11 or higher installed. -* {ProductName} {ProductVersion} installed. -* `Bookinfo` demonstration application installed. - - - -.Procedure -. A route to access the Grafana dashboard already exists. Query for details of the route: -+ ----- - $ export GRAFANA_URL=$(oc get route -n istio-system grafana -o jsonpath='{.spec.host}') ----- -+ -. Launch a browser and navigate to navigate to `http://<GRAFANA_URL>`. You see Grafana's home screen, as shown in the following figure: -+ -image::ossm-grafana-home-screen.png[] -+ -. From the menu in the upper-left corner, select *Istio Mesh Dashboard* to see Istio mesh metrics. -+ -image::ossm-grafana-mesh-no-traffic.png[] -+ -. Generate some traffic by accessing the Bookinfo application: -+ ----- -$ curl -o /dev/null http://<GATEWAY_URL>/productpage ----- -+ -The dashboard reflects the traffic through the mesh, similar to the following figure: -+ -image::ossm-grafana-mesh-with-traffic.png[] -+ -. To see detailed metrics for a Service, click a Service name in the *Service* column. The Service dashboard resembles the following figure: -+ -image::ossm-grafana-services.png[] -+ -Note that *TCP Bandwidth* metrics are empty, because Bookinfo only uses http-based Services. The dashboard also displays metrics for Workloads that call the *Client Workloads* Service and for Workloads that process requests from the *Service Workloads*. You can switch to a different Service or filter metrics by client and Service Workloads by using the menus at the top of the dashboard. -+ -. To switch to the Workloads dashboard, click *Istio Workload Dashboard* on the menu in the upper-left corner. You will see a screen resembling the following figure: -+ -image::ossm-grafana-workloads.png[] -+ -This dashboard shows Workload metrics and metrics for client (inbound) and Service (outbound) Workloads. You can switch to a different Workload; to filter metrics by inbound or outbound Workloads, use the menus at the top of the dashboard. diff --git a/modules/ossm-tutorial-jaeger-generating-traces.adoc b/modules/ossm-tutorial-jaeger-generating-traces.adoc deleted file mode 100644 index ef031440842a..000000000000 --- a/modules/ossm-tutorial-jaeger-generating-traces.adoc +++ /dev/null @@ -1,53 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -* service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc -* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc -//// - -[id="generating-sample-traces-analyzing-trace-data_{context}"] -= Generating example traces and analyzing trace data - -Jaeger is an open source distributed tracing system. You use Jaeger for monitoring and troubleshooting microservices-based distributed systems. Using Jaeger you can perform a trace, which follows the path of a request through various microservices that make up an application. Jaeger is installed by default as part of the {ProductShortName}. - -This tutorial uses {ProductShortName} and the bookinfo tutorial to demonstrate how you can use Jaeger to perform distributed tracing. - -[NOTE] -==== -The Bookinfo example application allows you to test your {ProductName} {ProductVersion} installation on {product-title}. - -Red Hat does not provide support for the Bookinfo application. -==== - -This tutorial uses {ProductShortName} and the Bookinfo tutorial to demonstrate how you can perform a trace using the Jaeger component of {ProductName}. - -.Prerequisites: - -* {product-title} 4.1 or higher installed. -* {ProductName} {ProductVersion} installed. -* Jaeger enabled during the installation. -* Bookinfo example application installed. - -.Procedure -. After you have deployed the Bookinfo application you will need to generate calls to the Bookinfo application so that you have some trace data to analyze. Access `http://<GATEWAY_URL>/productpage` and refresh the page a few times to generate some trace data. -. The installation process creates a route to access the Jaeger console. -.. In the {product-title} console, navigate to *Networking* -> *Routes* and search for the Jaeger route, which is the URL listed under *Location*. -.. Use the CLI to query for details of the route: -+ ----- -$ export JAEGER_URL=$(oc get route -n bookinfo jaeger-query -o jsonpath='{.spec.host}') ----- -+ -. Launch a browser and navigate to `https://<JAEGER_URL>`. - -. If necessary, log in using the same user name and password as you use to access the {product-title} console. - -. In the left pane of the Jaeger dashboard, from the Service menu, select "productpage" and click the *Find Traces* button at the bottom of the pane. A list of traces is displayed, as shown in the following image: - -+ -image::ossm-jaeger-main-screen.png[] -+ -. Click one of the traces in the list to open a detailed view of that trace. If you click on the top (most recent) trace, you see the details that correspond to the latest refresh of the ``/productpage`. -+ -image::ossm-jaeger-spans.png[] -+ -The trace in the previous figure consists of a few nested spans, each corresponding to a Bookinfo Service call, all performed in response to a ``/productpage` request. Overall processing time was 2.62s, with the *details* Service taking 3.56ms, the *reviews* Service taking 2.6s, and the *ratings* Service taking 5.32ms. Each of the calls to remote Services is represented by a client-side and server-side span. For example, the *details* client-side span is labeled `productpage details.myproject.svc.cluster.local:9080`. The span nested underneath it, labeled `details details.myproject.svc.cluster.local:9080`, corresponds to the server-side processing of the request. The trace also shows calls to *istio-policy*, which reflect authorization checks made by Istio. diff --git a/modules/ossm-tutorial-prometheus-querying-metrics.adoc b/modules/ossm-tutorial-prometheus-querying-metrics.adoc deleted file mode 100644 index abc55e597874..000000000000 --- a/modules/ossm-tutorial-prometheus-querying-metrics.adoc +++ /dev/null @@ -1,66 +0,0 @@ -//// -This PROCEDURE module included in the following assemblies: -- ossm-tutorial-prometheus.adoc -//// - -[id="ossm-tutorial-prometheus-querying-metrics_{context}"] -= Querying Prometheus metrics - -This tutorial uses {ProductShortName} and the `bookinfo` tutorial to demonstrate how you can query for metrics using Prometheus. - -.Prerequisites: - -* {product-title} 3.11 or higher installed. -* {ProductName} {ProductVersion} installed. -* `Bookinfo` demonstration application installed. - -After you have verified the Bookinfo application has deployed, you will need to generate calls to the application before you query for metrics. - -.Procedure - -. Verify that the `prometheus` Service is running in your cluster. In Kubernetes environments, execute the following command: -+ -[source,terminal] ----- -$ oc get svc prometheus -n istio-system ----- -+ -.Example output -[source,terminal] ----- -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -prometheus 10.59.241.54 <none> 9090/TCP 2m ----- -+ -. Generate network traffic by accessing the Bookinfo application: -+ -[source,terminal] ----- -$ curl -o /dev/null http://$GATEWAY_URL/productpage ----- -+ -. A route to access the Prometheus user interface already exists. Query for details of the route: -+ -[source,terminal] ----- -$ export PROMETHEUS_URL=$(oc get route -n istio-system prometheus -o jsonpath='{.spec.host}') ----- -+ -. Launch a browser and navigate to `http://<PROMETHEUS_URL>`. You will see the Prometheus home screen, similar to the following figure: -+ -image::ossm-prometheus-home-screen.png[] -+ -. In the *Expression* field, enter `istio_request_duration_seconds_count`, and click the `Execute` button. You will see a screen similar to the following figure: -+ -image::ossm-prometheus-metrics.png[] -+ -. You can narrow down queries by using selectors. For example `istio_request_duration_seconds_count{destination_workload="reviews-v2"}` shows only counters with the matching *destination_workload* label. For more information about using queries, see the link:https://prometheus.io/docs/prometheus/latest/querying/basics/#instant-vector-selectors[Prometheus documentation]. -+ -. To list all available Prometheus metrics, run the following command: -+ -[source,terminal] ----- -$ oc get prometheus -n istio-system -o jsonpath='{.items[*].spec.metrics[*].name}' requests_total request_duration_seconds request_bytes response_bytes tcp_sent_bytes_total tcp_received_bytes_total ----- -+ -Note that returned metric names must be prepended with `istio_` when used in queries, for example, `requests_total` is `istio_requests_total`. diff --git a/modules/ossm-understanding-service-mesh.adoc b/modules/ossm-understanding-service-mesh.adoc deleted file mode 100644 index ce0bd181b36b..000000000000 --- a/modules/ossm-understanding-service-mesh.adoc +++ /dev/null @@ -1,29 +0,0 @@ -//// -Module included in the following assemblies: --service_mesh/v1x/ossm-architecture.adoc --service_mesh/v2x/ossm-architecture.adoc -//// - -[id="ossm-understanding-service-mesh_{context}"] -= Understanding service mesh - -A _service mesh_ is the network of microservices that make up applications in a distributed microservice architecture and the interactions between those microservices. When a {ProductShortName} grows in size and complexity, it can become harder to understand and manage. - -Based on the open source link:https://istio.io/[Istio] project, {ProductName} adds a transparent layer on existing distributed applications without requiring any changes to the service code. You add {ProductName} support to services by deploying a special sidecar proxy to relevant services in the mesh that intercepts all network communication between microservices. You configure and manage the {ProductShortName} using the control plane features. - -{ProductName} gives you an easy way to create a network of deployed services that provide: - -* Discovery -* Load balancing -* Service-to-service authentication -* Failure recovery -* Metrics -* Monitoring - -{ProductName} also provides more complex operational functions including: - -* A/B testing -* Canary releases -* Rate limiting -* Access control -* End-to-end authentication diff --git a/modules/ossm-update-app-sidecar.adoc b/modules/ossm-update-app-sidecar.adoc deleted file mode 100644 index 1ede6a805078..000000000000 --- a/modules/ossm-update-app-sidecar.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/installing-ossm.adoc -// * service_mesh/v2x/installing-ossm.adoc - -[id="ossm-update-app-sidecar_{context}"] -= Updating your application pods - -If you selected the Automatic Approval Strategy when you were installing your Operators, then the Operators update the control plane automatically, but not your applications. Existing applications continue to be part of the mesh and function accordingly. The application administrator must restart applications to upgrade the sidecar. - -If your deployment uses Automatic sidecar injection, you can update the pod template in the deployment by adding or modifying an annotation. Run the following command to redeploy the pods: - -[source,terminal] ----- -$ oc patch deployment/<deployment> -p '{"spec":{"template":{"metadata":{"annotations":{"kubectl.kubernetes.io/restartedAt": "'`date -Iseconds`'"}}}}}' ----- - -If your deployment does not use automatic sidecar injection, you must manually update the sidecars by modifying the sidecar container image specified in the deployment or pod. diff --git a/modules/ossm-updating-smcp.adoc b/modules/ossm-updating-smcp.adoc deleted file mode 100644 index 7d1134f3881b..000000000000 --- a/modules/ossm-updating-smcp.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/customizing-installation-ossm.adoc -// * service_mesh/v2x/customizing-installation-ossm.adoc - -[id="ossm-updating-smcp_{context}"] -= Updating the ServiceMeshControlPlane - -Configure {ProductName} to work with your app by creating and configuring a `ServiceMeshControlPlane`. The `ServiceMeshControlPlane` resource defines the configuration to be used during installation. You can deploy the default configuration provided by Red Hat or customize the `ServiceMeshControlPlane` resource for your microservices and workflows. - -[id="ossm-control-plane-deploy-operatorhub_{context}"] -== Editing the `ServiceMeshControlPlane` from the web console - -Follow this procedure to edit the `ServiceMeshControlPlane` with the {product-title} web console. - -.Procedure - -. In the {product-title} web console, click *Operators* -> *Installed Operators*. - -. Select the project where you installed the control plane, for example `istio-system`, from the Project menu. - -. Click the {ProductName} Operator. In the *Istio Service Mesh Control Plane* column, click the name of your `ServiceMeshControlPlane`, for example `basic-install`. - -. On the *Create ServiceMeshControlPlane Details* page, click `YAML` to modify your configuration. - -. Click *Save*. - -[id="ossm-control-plane-deploy-cli_{context}"] -== Editing the `ServiceMeshControlPlane` from the CLI - -Follow this procedure to create or edit the `ServiceMeshControlPlane` with the command line. - -.Procedure - -. Log in to the {product-title} CLI as a user with the `cluster-admin` role. Enter the following command. Then, enter your username and password when prompted. -+ -[source,terminal] ----- -$ oc login https://{HOSTNAME}:6443 ----- -+ -. Change to the project where you installed the control plane, for example istio-system. -+ -[source,terminal] ----- -$ oc project istio-system ----- -+ -. Edit the `ServiceMeshControlPlane` file. - -. Run the following command to edit the control plane where `<istio-installation.yaml>` includes a full path to the file you edited: -+ -[source,terminal] ----- -$ oc edit -n istio-system -f <istio-installation.yaml> ----- -+ -. Execute the following command to see the status of the control plane installation. -+ -[source,terminal] ----- -$ oc get smcp -n istio-system ----- -+ -The installation has finished successfully when the READY column is true. -+ ----- -NAME READY STATUS TEMPLATE VERSION AGE -basic-install 9/9 InstallSuccessful default v2.0 4m25s ----- - diff --git a/modules/ossm-vs-istio-1x.adoc b/modules/ossm-vs-istio-1x.adoc deleted file mode 100644 index 90f79d38b4e6..000000000000 --- a/modules/ossm-vs-istio-1x.adoc +++ /dev/null @@ -1,105 +0,0 @@ -//// -Module included in the following assemblies: --service_mesh/v1x/ossm-vs-community.adoc -//// - -[id="ossm-vs-istio_{context}"] -= Differences between Istio and {ProductName} - -An installation of {ProductName} differs from an installation of Istio in multiple ways. The modifications to {ProductName} are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on OpenShift. - -[id="ossm-cli-tool_{context}"] -== Command line tool - -The command line tool for {ProductName} is oc.  {ProductName}  does not support istioctl. - -[id="ossm-automatic-injection_{context}"] -== Automatic injection - -The upstream Istio community installation automatically injects the sidecar into pods within the projects you have labeled. - -{ProductName} does not automatically inject the sidecar to any pods, but requires you to opt in to injection using an annotation without labeling projects. This method requires fewer privileges and does not conflict with other OpenShift capabilities such as builder pods. To enable automatic injection you specify the `sidecar.istio.io/inject` annotation as described in the Automatic sidecar injection section. - -[id="ossm-rbac_{context}"] -== Istio Role Based Access Control features - -Istio Role Based Access Control (RBAC) provides a mechanism you can use to control access to a service. You can identify subjects by user name or by specifying a set of properties and apply access controls accordingly. - -The upstream Istio community installation includes options to perform exact header matches, match wildcards in headers, or check for a header containing a specific prefix or suffix. - -{ProductName} extends the ability to match request headers by using a regular expression. Specify a property key of `request.regex.headers` with a regular expression. - -.Upstream Istio community matching request headers example -[source,yaml] ----- -apiVersion: "rbac.istio.io/v1alpha1" -kind: ServiceRoleBinding -metadata: - name: httpbin-client-binding - namespace: httpbin -spec: - subjects: - - user: "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account" - properties: - request.headers[<header>]: "value" ----- - -.{ProductName} matching request headers by using regular expressions -[source,yaml] ----- -apiVersion: "rbac.istio.io/v1alpha1" -kind: ServiceRoleBinding -metadata: - name: httpbin-client-binding - namespace: httpbin -spec: - subjects: - - user: "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account" - properties: - request.regex.headers[<header>]: "<regular expression>" ----- - - -[id="ossm-openssl_{context}"] -== OpenSSL - -{ProductName} replaces BoringSSL with OpenSSL. OpenSSL is a software library that contains an open source implementation of the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols. The {ProductName} Proxy binary dynamically links the OpenSSL libraries (libssl and libcrypto) from the underlying Red Hat Enterprise Linux operating system. - -[id="ossm-component-modifications_{context}"] -== Component modifications - -* A _maistra-version_ label has been added to all resources. -* All Ingress resources have been converted to OpenShift Route resources. -* Grafana, Tracing (Jaeger), and Kiali are enabled by default and exposed through OpenShift routes. -* Godebug has been removed from all templates -* The `istio-multi` ServiceAccount and ClusterRoleBinding have been removed, as well as the `istio-reader` ClusterRole. - -[id="ossm-envoy-sds-ca_{context}"] -== Envoy, Secret Discovery Service, and certificates - -* {ProductName} does not support QUIC-based services. -* Deployment of TLS certificates using the Secret Discovery Service (SDS) functionality of Istio is not currently supported in {ProductName}. The Istio implementation depends on a nodeagent container that uses hostPath mounts. - -[id="ossm-cni_{context}"] -== Istio Container Network Interface (CNI) plug-in - -{ProductName} includes CNI plug-in, which provides you with an alternate way to configure application pod networking. The CNI plug-in replaces the `init-container` network configuration eliminating the need to grant service accounts and projects access to Security Context Constraints (SCCs) with elevated privileges. - -[id="ossm-routes-gateways_{context}"] -== Routes for Istio Gateways - -OpenShift routes for Istio Gateways are automatically managed in {ProductName}. Every time an Istio Gateway is created, updated or deleted inside the service mesh, an OpenShift route is created, updated or deleted. - -A {ProductName} control plane component called Istio OpenShift Routing (IOR) synchronizes the gateway route. For more information, see Automatic route creation. - -[id="ossm-catch-all-domains_{context}"] -=== Catch-all domains -Catch-all domains ("\*") are not supported. If one is found in the Gateway definition, {ProductName} _will_ create the route, but will rely on OpenShift to create a default hostname. This means that the newly created route will __not__ be a catch all ("*") route, instead it will have a hostname in the form `<route-name>[-<project>].<suffix>`. Refer to the OpenShift documentation for more information about how default hostnames work and how a cluster administrator can customize it. - -[id="ossm-subdomains_{context}"] -=== Subdomains -Subdomains (e.g.: "*.domain.com") are supported. However this ability doesn't come enabled by default in OpenShift. This means that {ProductName} _will_ create the route with the subdomain, but it will only be in effect if OpenShift is configured to enable it. - -[id="ossm-tls_{context}"] -=== Transport layer security -Transport Layer Security (TLS) is supported. This means that, if the Gateway contains a `tls` section, the OpenShift Route will be configured to support TLS. diff --git a/modules/ossm-vs-istio.adoc b/modules/ossm-vs-istio.adoc deleted file mode 100644 index 62880d2d71c6..000000000000 --- a/modules/ossm-vs-istio.adoc +++ /dev/null @@ -1,123 +0,0 @@ -//// -Module included in the following assemblies: --service_mesh/v2x/ossm-vs-community.adoc -//// - -[id="ossm-vs-istio_{context}"] -= Differences between Istio and {ProductName} - -An installation of {ProductName} differs from an installation of Istio in multiple ways. The modifications to {ProductName} are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on OpenShift. - -[id="ossm-cli-tool_{context}"] -== Command line tool - -The command line tool for {ProductName} is `oc`.  {ProductName} does not support `istioctl`. - - -[id="ossm-installation-upgrade_{context}"] -== Installation and upgrades - -{ProductName} does not support Istio installation profiles. - -{ProductName} does not support canary upgrades of the service mesh. - - -[id="ossm-federation-multicluster_{context}"] -== Federation and multicluster - -{ProductName} does not yet support federated or multiclustered service meshes. - -* *Federated*: a set of Service Mesh control planes which interact with each other and are configured independently. - -* *Clustered*: a set of Service Mesh control planes which act as a single control plane and are configured as a single entity. - - -[id="ossm-automatic-injection_{context}"] -== Automatic injection - -The upstream Istio community installation automatically injects the sidecar into pods within the projects you have labeled. - -{ProductName} does not automatically inject the sidecar to any pods, but requires you to opt in to injection using an annotation without labeling projects. This method requires fewer privileges and does not conflict with other OpenShift capabilities such as builder pods. To enable automatic injection you specify the `sidecar.istio.io/inject` annotation as described in the Automatic sidecar injection section. - -[id="ossm-rbac_{context}"] -== Istio Role Based Access Control features - -Istio Role Based Access Control (RBAC) provides a mechanism you can use to control access to a service. You can identify subjects by user name or by specifying a set of properties and apply access controls accordingly. - -The upstream Istio community installation includes options to perform exact header matches, match wildcards in headers, or check for a header containing a specific prefix or suffix. - -{ProductName} extends the ability to match request headers by using a regular expression. Specify a property key of `request.regex.headers` with a regular expression. - -.Upstream Istio community matching request headers example -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: httpbin-usernamepolicy -spec: - action: ALLOW - rules: - - when: - - key: 'request.regex.headers[username]' - values: - - "allowed.*" - selector: - matchLabels: - app: httpbin ----- - -[id="ossm-openssl_{context}"] -== OpenSSL - -{ProductName} replaces BoringSSL with OpenSSL. OpenSSL is a software library that contains an open source implementation of the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols. The {ProductName} Proxy binary dynamically links the OpenSSL libraries (libssl and libcrypto) from the underlying Red Hat Enterprise Linux operating system. - - -[id="ossm-external-workloads_{context}"] -== External workloads - -{ProductName} does not support external workloads (virtual machines). - -[id="ossm-component-modifications_{context}"] -== Component modifications - -* A _maistra-version_ label has been added to all resources. -* All Ingress resources have been converted to OpenShift Route resources. -* Grafana, Tracing (Jaeger), and Kiali are enabled by default and exposed through OpenShift routes. -* Godebug has been removed from all templates -* The `istio-multi` ServiceAccount and ClusterRoleBinding have been removed, as well as the `istio-reader` ClusterRole. - -[id="ossm-envoy-services_{context}"] -== Envoy services - -* {ProductName} does not support QUIC-based services. - -[id="ossm-cni_{context}"] -== Istio Container Network Interface (CNI) plug-in - -{ProductName} includes CNI plug-in, which provides you with an alternate way to configure application pod networking. The CNI plug-in replaces the `init-container` network configuration eliminating the need to grant service accounts and projects access to security context constraints (SCCs) with elevated privileges. - -[id="ossm-routes-gateways_{context}"] -== Routes for Istio Gateways - -OpenShift routes for Istio Gateways are automatically managed in {ProductName}. Every time an Istio Gateway is created, updated or deleted inside the service mesh, an OpenShift route is created, updated or deleted. - -A {ProductName} control plane component called Istio OpenShift Routing (IOR) synchronizes the gateway route. For more information, see Automatic route creation. - -[id="ossm-catch-all-domains_{context}"] -=== Catch-all domains -Catch-all domains ("\*") are not supported. If one is found in the Gateway definition, {ProductName} _will_ create the route, but will rely on OpenShift to create a default hostname. This means that the newly created route will __not__ be a catch all ("*") route, instead it will have a hostname in the form `<route-name>[-<project>].<suffix>`. Refer to the OpenShift documentation for more information about how default hostnames work and how a cluster administrator can customize it. - -[id="ossm-subdomains_{context}"] -=== Subdomains -Subdomains (e.g.: "*.domain.com") are supported. However this ability doesn't come enabled by default in OpenShift. This means that {ProductName} _will_ create the route with the subdomain, but it will only be in effect if OpenShift is configured to enable it. - -[id="ossm-tls_{context}"] -=== Transport layer security -Transport Layer Security (TLS) is supported. This means that, if the Gateway contains a `tls` section, the OpenShift Route will be configured to support TLS. - - -[id="ossm-wasm_{context}"] -=== WebAssembly Extensions - -{ProductName} 2.0 introduces WebAssembly extensions to Envoy Proxy as a link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview]. Note that WASM extensions are not included in the proxy binary and that WASM filters from the upstream Istio community are not supported in {ProductName} 2.0. diff --git a/modules/ovirt-csi-driver-storage-class.adoc b/modules/ovirt-csi-driver-storage-class.adoc deleted file mode 100644 index 1db6d53fa1b8..000000000000 --- a/modules/ovirt-csi-driver-storage-class.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-ovirt.adoc - -[id="ovirt-csi-driver-storage-class_{context}"] -= oVirt CSI driver storage class - -{product-title} creates a default object of type `StorageClass` named `ovirt-csi-sc` which is used for creating dynamically provisioned persistent volumes. - -To create additional storage classes for different configurations, create and save a file with the `StorageClass` object described by the following sample YAML: - -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: <storage-class-name> <1> - annotations: - storageclass.kubernetes.io/is-default-class: "false" <2> -provisioner: csi.ovirt.org -parameters: - storageDomainName: <rhv-storage-domain-name> <3> - thinProvisioning: "true" <4> - csi.storage.k8s.io/fstype: ext4 <5> ----- -<1> Name of the storage class. -<2> Set to `false` if the storage class is the default storage class in the cluster. If set to `true`, the existing default storage class must be edited and set to `false`. -<3> {rh-virtualization} storage domain name to use. -<4> Disk must be thin provisioned. -<5> File system type to be created. diff --git a/modules/pagerduty-configuring-acs.adoc b/modules/pagerduty-configuring-acs.adoc new file mode 100644 index 000000000000..0de4d52f85f3 --- /dev/null +++ b/modules/pagerduty-configuring-acs.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-pagerduty.adoc +:_mod-docs-content-type: PROCEDURE +[id="pagerduty-configuring-acs_{context}"] += Configuring {product-title} + +Create a new integration in {product-title} by using the integration key. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *PagerDuty*. +. Click *New Integration* (*`add`* icon). +. Enter a name for *Integration Name*. +. Enter the integration key in the *PagerDuty integration key* field. +. Click *Test* to validate that the integration with PagerDuty is working. +. Click *Create* to create the configuration. diff --git a/modules/perform-on-demand-backups-amazon-s3.adoc b/modules/perform-on-demand-backups-amazon-s3.adoc new file mode 100644 index 000000000000..b68d26e2b2c5 --- /dev/null +++ b/modules/perform-on-demand-backups-amazon-s3.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-amazon-s3.adoc +:_mod-docs-content-type: PROCEDURE +[id="perform-on-demand-backups-amazon-s3_{context}"] += Performing on-demand backups on Amazon S3 + +Uses the {product-title-short} portal to trigger manual backups of {product-title} on Amazon S3. + +.Prerequisites +* You must have already integrated {product-title} with Amazon S3. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *External backups* section, click *Amazon S3*. +. Select the integration name for the S3 bucket where you want to do a backup. +. Click *Trigger Backup*. + +[NOTE] +==== +Currently, when you select the *Trigger Backup* option, there is no notification. +However, {product-title} begins the backup task in the background. +==== diff --git a/modules/perform-on-demand-backups-google-cloud-storage.adoc b/modules/perform-on-demand-backups-google-cloud-storage.adoc new file mode 100644 index 000000000000..e6051a30e557 --- /dev/null +++ b/modules/perform-on-demand-backups-google-cloud-storage.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * dir/filename.adoc +:_mod-docs-content-type: PROCEDURE +[id="perform-on-demand-backups-google-cloud-storage_{context}"] += Perform on-demand backups on Google Cloud Storage + +[role="_abstract"] +Uses the {product-title-short} portal to trigger manual backups of {product-title} on Google Cloud Storage. + +.Prerequisites +* You must have already integrated {product-title} with Google Cloud Storage. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Under the *External backups* section, click *Google Cloud Storage*. +. Select the integration name for the GCS bucket in which you want to do a backup. +. Click *Trigger Backup*. + +[NOTE] +==== +Currently, when you select the *Trigger Backup* option, there is no notification. +However, {product-title} begins the backup task in the background. +==== diff --git a/modules/perform-on-demand-backups-s3-api-compatible-services.adoc b/modules/perform-on-demand-backups-s3-api-compatible-services.adoc new file mode 100644 index 000000000000..2ae946335ddf --- /dev/null +++ b/modules/perform-on-demand-backups-s3-api-compatible-services.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-s3-api-compatible-services.adoc +:_mod-docs-content-type: PROCEDURE +[id="perform-on-demand-backups-s3-api-compatible-services_{context}"] += Performing on-demand backups on an S3 API compatible bucket + +Use the {product-title} portal to trigger manual backups of {product-title-short} to an S3 API compatible bucket. + +.Prerequisites +* You have integrated {product-title-short} with an S3 API compatible service. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. In the *External backups* section, click *S3 API Compatible*. +. Select the integration name for the S3 bucket where you want to do a backup. +. Click *Trigger backup*. + +[NOTE] +==== +When you select *Trigger backup*, there is no notification. +However, {product-title-short} begins the backup task in the background. +==== diff --git a/modules/periodic-scanning-of-images.adoc b/modules/periodic-scanning-of-images.adoc new file mode 100644 index 000000000000..9e727f03546c --- /dev/null +++ b/modules/periodic-scanning-of-images.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: CONCEPT +[id="periodic-scanning-of-images_{context}"] += Automatic scanning of active images + +[role="_abstract"] +{product-title} periodically scans all active images and updates the image scan results to reflect the latest vulnerability definitions. Active images are the images you have deployed in your environment. + +[NOTE] +==== +From {product-title} 3.0.57, you can enable automatic scanning of inactive images by configuring the *Watch* setting for images. +==== + +Central fetches the image scan results for all active images from Scanner or other integrated image scanners that you use and updates the results every 4 hours. + +You can also use the `roxctl` CLI to check the image scan results on demand. diff --git a/modules/persistent-storage-cinder-creating-pv.adoc b/modules/persistent-storage-cinder-creating-pv.adoc deleted file mode 100644 index a1e4fe15bf1b..000000000000 --- a/modules/persistent-storage-cinder-creating-pv.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent_storage-cinder.adoc - -[id="persistent-storage-cinder-creating-pv_{context}"] -= Creating the persistent volume - -You must define your persistent volume (PV) in an object definition before creating -it in {product-title}: - -.Procedure - -. Save your object definition to a file. -+ -.cinder-persistentvolume.yaml -[source,yaml] ----- -apiVersion: "v1" -kind: "PersistentVolume" -metadata: - name: "pv0001" <1> -spec: - capacity: - storage: "5Gi" <2> - accessModes: - - "ReadWriteOnce" - cinder: <3> - fsType: "ext3" <4> - volumeID: "f37a03aa-6212-4c62-a805-9ce139fab180" <5> ----- -<1> The name of the volume that is used by persistent volume claims or pods. -<2> The amount of storage allocated to this volume. -<3> Indicates `cinder` for {rh-openstack-first} Cinder volumes. -<4> The file system that is created when the volume is mounted for the first time. -<5> The Cinder volume to use. -+ -[IMPORTANT] -==== -Do not change the `fstype` parameter value after the volume is formatted and -provisioned. Changing this value can result in data loss and pod failure. -==== - -. Create the object definition file you saved in the previous step. -+ -[source,terminal] ----- -$ oc create -f cinder-persistentvolume.yaml ----- diff --git a/modules/persistent-storage-cinder-provisioning.adoc b/modules/persistent-storage-cinder-provisioning.adoc deleted file mode 100644 index d77c8ac59f31..000000000000 --- a/modules/persistent-storage-cinder-provisioning.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent_storage-cinder.adoc - -[id="persistent-storage-cinder-provisioning_{context}"] -= Manual provisioning with Cinder - -Storage must exist in the underlying infrastructure before it can be mounted as a volume in {product-title}. - -.Prerequisites - -* {product-title} configured for {rh-openstack-first} -* Cinder volume ID diff --git a/modules/persistent-storage-cinder-pv-format.adoc b/modules/persistent-storage-cinder-pv-format.adoc deleted file mode 100644 index 0d0aae53bb20..000000000000 --- a/modules/persistent-storage-cinder-pv-format.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent_storage-cinder.adoc - -[id="persistent-storage-cinder-pv-format_{context}"] -= Persistent volume formatting - -You can use unformatted Cinder volumes as PVs because -{product-title} formats them before the first use. - -Before {product-title} mounts the volume and passes it to a container, the system checks that it contains a file system as specified by the `fsType` parameter in the -PV definition. If the device is not formatted with the file system, all data from the device is erased and the device is automatically formatted with the given file system. diff --git a/modules/persistent-storage-cinder-volume-security.adoc b/modules/persistent-storage-cinder-volume-security.adoc deleted file mode 100644 index 1242c020c2f3..000000000000 --- a/modules/persistent-storage-cinder-volume-security.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent_storage-cinder.adoc - -[id="persistent-storage-cinder-volume-security_{context}"] -= Cinder volume security - -If you use Cinder PVs in your application, configure security for their -deployment configurations. - -.Prerequisites -- An SCC must be created that uses the appropriate `fsGroup` strategy. - -.Procedure - -. Create a service account and add it to the SCC: -+ -[source,terminal] ----- -$ oc create serviceaccount <service_account> ----- -+ -[source,terminal] ----- -$ oc adm policy add-scc-to-user <new_scc> -z <service_account> -n <project> ----- - -. In your application's deployment configuration, provide the service account -name and `securityContext`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ReplicationController -metadata: - name: frontend-1 -spec: - replicas: 1 <1> - selector: <2> - name: frontend - template: <3> - metadata: - labels: <4> - name: frontend <5> - spec: - containers: - - image: openshift/hello-openshift - name: helloworld - ports: - - containerPort: 8080 - protocol: TCP - restartPolicy: Always - serviceAccountName: <service_account> <6> - securityContext: - fsGroup: 7777 <7> ----- -<1> The number of copies of the pod to run. -<2> The label selector of the pod to run. -<3> A template for the pod that the controller creates. -<4> The labels on the pod. They must include labels from the label selector. -<5> The maximum name length after expanding any parameters is 63 characters. -<6> Specifies the service account you created. -<7> Specifies an `fsGroup` for the pods. diff --git a/modules/persistent-storage-csi-about.adoc b/modules/persistent-storage-csi-about.adoc deleted file mode 100644 index 7959f939fd6b..000000000000 --- a/modules/persistent-storage-csi-about.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-ebs.adoc -// * storage/container_storage_interface/persistent-storage-csi-manila.adoc -// * storage/container_storage_interface/persistent-storage-csi-ovirt.adoc - -[id="csi-about_{context}"] -= About CSI -Storage vendors have traditionally provided storage drivers as part of Kubernetes. With the implementation of the Container Storage Interface (CSI), third-party providers can instead deliver storage plug-ins using a standard interface without ever having to change the core Kubernetes code. - -CSI Operators give {product-title} users storage options, such as volume snapshots, that are not possible with in-tree volume plug-ins. diff --git a/modules/persistent-storage-csi-architecture.adoc b/modules/persistent-storage-csi-architecture.adoc deleted file mode 100644 index c04096b2bcba..000000000000 --- a/modules/persistent-storage-csi-architecture.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent_storage-csi.adoc - -[id="persistent-storage-csi-architecture_{context}"] -= CSI Architecture - -CSI drivers are typically shipped as container images. These containers -are not aware of {product-title} where they run. To use CSI-compatible -storage back end in {product-title}, the cluster administrator must deploy -several components that serve as a bridge between {product-title} and the -storage driver. - -The following diagram provides a high-level overview about the components -running in pods in the {product-title} cluster. - -image::csi-arch.png["Architecture of CSI components"] - -It is possible to run multiple CSI drivers for different storage back ends. -Each driver needs its own external controllers deployment and daemon set -with the driver and CSI registrar. diff --git a/modules/persistent-storage-csi-cinder-storage-class.adoc b/modules/persistent-storage-csi-cinder-storage-class.adoc deleted file mode 100644 index 18cd30908604..000000000000 --- a/modules/persistent-storage-csi-cinder-storage-class.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-cinder.adoc - -[id="persistent-storage-csi-cinder_{context}"] -= Making OpenStack Cinder CSI the default storage class - -In {product-title}, the default storage class references the in-tree Cinder driver. The storage class will default to referencing OpenStack Cinder CSI in a subsequent update of {product-title}. Volumes provisioned using the existing in-tree storage class are planned for migration to the OpenStack Cinder CSI storage class at that time. - -The OpenStack Cinder CSI driver uses the `cinder.csi.openstack.org` parameter key to support dynamic provisioning. - -To enable OpenStack Cinder CSI provisioning in {product-title}, it is recommended that you overwrite the default in-tree storage class with `standard-csi`. Alternatively, you can create the persistent volume claim (PVC) and specify the storage class as "standard-csi". - -.Recommended procedure -Use the following steps to apply the `standard-csi` storage class by overwriting the default in-tree storage class. - -. List the storage class: -+ -[source,terminal] --- -$ oc get storageclass --- -+ -[source,terminal] -.Example output --- -NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE -standard(default) cinder.csi.openstack.org Delete WaitForFirstConsumer true 46h -standard-csi kubernetes.io/cinder Delete WaitForFirstConsumer true 46h --- - -. Change the value of the annotation `storageclass.kubernetes.io/is-default-class` to `false` for the default storage class, as shown in the following example: -+ -[source,terminal] --- -$ oc patch storageclass standard -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "false"}}}' --- - -. Make another storage class the default by adding or modifying the annotation as `storageclass.kubernetes.io/is-default-class=true`. -+ -[source,terminal] --- -$ oc patch storageclass standard-csi -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}' --- - -. Verify that the PVC is now referencing the CSI storage class by default: -+ -[source,terminal] --- -$ oc get storageclass --- -+ -[source,terminal] -.Example output --- -NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE -standard kubernetes.io/cinder Delete WaitForFirstConsumer true 46h -standard-csi(default) cinder.csi.openstack.org Delete WaitForFirstConsumer true 46h --- - -. Optional: You can define a new PVC without having to specify the storage class: -+ -[source,yaml] --- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: cinder-claim -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi --- -+ -A PVC that does not specify a specific storage class is automatically provisioned by using the default storage class. -+ -. Optional: After the new file has been configured, create it in your cluster: -+ -[source,terminal] --- -$ oc create -f cinder-claim.yaml --- diff --git a/modules/persistent-storage-csi-cloning-overview.adoc b/modules/persistent-storage-csi-cloning-overview.adoc deleted file mode 100644 index 354e7854e103..000000000000 --- a/modules/persistent-storage-csi-cloning-overview.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-cloning.adoc - -[id="persistent-storage-csi-cloning-overview_{context}"] -= Overview of CSI volume cloning - -A Container Storage Interface (CSI) volume clone is a duplicate of an existing persistent volume at a particular point in time. - -Volume cloning is similar to volume snapshots, although it is more efficient. For example, a cluster administrator can duplicate a cluster volume by creating another instance of the existing cluster volume. - -Cloning creates an exact duplicate of the specified volume on the back-end device, rather than creating a new empty volume. After dynamic provisioning, you can use a volume clone just as you would use any standard volume. - -No new API objects are required for cloning. The existing `dataSource` field in the `PersistentVolumeClaim` object is expanded so that it can accept the name of an existing PersistentVolumeClaim in the same namespace. - -== Support limitations - -By default, {product-title} supports CSI volume cloning with these limitations: - -* The destination persistent volume claim (PVC) must exist in the same namespace as the source PVC. -* The source and destination storage class must be the same. -* Support is only available for CSI drivers. In-tree and FlexVolumes are not supported. -* {product-title} does not include any CSI drivers. Use the CSI drivers provided by -link:https://kubernetes-csi.github.io/docs/drivers.html[community or storage vendors]. Follow the installation instructions provided by the CSI driver. -* CSI drivers might not have implemented the volume cloning functionality. For details, see the CSI driver documentation. -* {product-title} {product-version} supports version 1.1.0 of the -link:https://github.com/container-storage-interface/spec[CSI specification]. diff --git a/modules/persistent-storage-csi-cloning-provisioning.adoc b/modules/persistent-storage-csi-cloning-provisioning.adoc deleted file mode 100644 index 8bef2e4fcc60..000000000000 --- a/modules/persistent-storage-csi-cloning-provisioning.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-cloning.adoc - -[id="persistent-storage-csi-cloning-provisioning_{context}"] -= Provisioning a CSI volume clone - -When you create a cloned persistent volume claim (PVC) API object, you trigger the provisioning of a CSI volume clone. The clone pre-populates with the contents of another PVC, adhering to the same rules as any other persistent volume. The one exception is that you must add a `dataSource` that references an existing PVC in the same namespace. - -.Prerequisites -* You are logged in to a running {product-title} cluster. -* Your PVC is created using a CSI driver that supports volume cloning. -* Your storage back end is configured for dynamic provisioning. Cloning support is not available for static provisioners. - -.Procedure - -To clone a PVC from an existing PVC: - -. Create and save a file with the `PersistentVolumeClaim` object described by the following YAML: - -+ -.pvc-clone.yaml -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: pvc-1-clone - namespace: mynamespace -spec: - storageClassName: csi-cloning <1> - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 5Gi - dataSource: - kind: PersistentVolumeClaim - name: pvc-1 ----- -+ -<1> The name of the storage class that provisions the storage back end. The default storage class can be used and `storageClassName` can be omitted in the spec. -+ -. Create the object you saved in the previous step by running the following command: -+ -[source,terminal] ----- -$ oc create -f pvc-clone.yaml ----- -+ -A new PVC `pvc-1-clone` is created. - -. Verify that the volume clone was created and is ready by running the following command: -+ -[source,terminal] ----- -$ oc get pvc pvc-1-clone ----- -+ -The `pvc-1-clone` shows that it is `Bound`. -+ -You are now ready to use the newly cloned PVC to configure a pod. - -. Create and save a file with the `Pod` object described by the YAML. For example: -+ - -[source,yaml] ----- -kind: Pod -apiVersion: v1 -metadata: - name: mypod -spec: - containers: - - name: myfrontend - image: dockerfile/nginx - volumeMounts: - - mountPath: "/var/www/html" - name: mypd - volumes: - - name: mypd - persistentVolumeClaim: - claimName: pvc-1-clone <1> ----- -+ -<1> The cloned PVC created during the CSI volume cloning operation. -+ -The created `Pod` object is now ready to consume, clone, snapshot, or delete your cloned PVC independently of its original `dataSource` PVC. diff --git a/modules/persistent-storage-csi-driver-daemonset.adoc b/modules/persistent-storage-csi-driver-daemonset.adoc deleted file mode 100644 index 49c7fd69ef01..000000000000 --- a/modules/persistent-storage-csi-driver-daemonset.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent_storage-csi.adoc - -[id="csi-driver-daemonset_{context}"] -= CSI driver daemon set - -The CSI driver daemon set runs a pod on every node that allows -{product-title} to mount storage provided by the CSI driver to the node -and use it in user workloads (pods) as persistent volumes (PVs). The pod -with the CSI driver installed contains the following containers: - -* A CSI driver registrar, which registers the CSI driver into the -`openshift-node` service running on the node. The `openshift-node` process -running on the node then directly connects with the CSI driver using the -UNIX Domain Socket available on the node. -* A CSI driver. - -The CSI driver deployed on the node should have as few credentials to the -storage back end as possible. {product-title} will only use the node plug-in -set of CSI calls such as `NodePublish`/`NodeUnpublish` and -`NodeStage`/`NodeUnstage`, if these calls are implemented. diff --git a/modules/persistent-storage-csi-drivers-supported.adoc b/modules/persistent-storage-csi-drivers-supported.adoc deleted file mode 100644 index f052190c277b..000000000000 --- a/modules/persistent-storage-csi-drivers-supported.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi.adoc - -[id="csi-drivers-supported_{context}"] -= CSI drivers supported by {product-title} - -{product-title} installs certain CSI drivers by default, giving users storage options that are not possible with in-tree volume plug-ins. - -To create CSI-provisioned persistent volumes that mount to these supported storage assets, {product-title} installs the necessary CSI driver Operator, the CSI driver, and the required storage class by default. For more details about the default namespace of the Operator and driver, see the documentation for the specific CSI Driver Operator. - -The following table describes the CSI drivers that are installed with {product-title} and which CSI features they support, such as volume snapshots, cloning, and resize. - -.Supported CSI drivers and features in {product-title} -[cols=",^v,^v,^v, width="100%",options="header"] -|=== -|CSI driver |CSI volume snapshots |CSI cloning |CSI resize - -|AWS EBS (Tech Preview) | ✅ | - | ✅ -|Google Cloud Platform (GCP) persistent disk (PD) (Tech Preview)| ✅ | - | ✅ -|OpenStack Cinder | ✅ | ✅ | ✅ -|OpenStack Manila | ✅ | ✅ | ✅ -|Red Hat Virtualization (oVirt) | - | - | - -|=== - -[IMPORTANT] -==== -If your CSI driver is not listed in the preceding table, you must follow the installation instructions provided by your CSI storage vendor to use their supported CSI features. -==== diff --git a/modules/persistent-storage-csi-dynamic-provisioning.adoc b/modules/persistent-storage-csi-dynamic-provisioning.adoc deleted file mode 100644 index be6c915b7367..000000000000 --- a/modules/persistent-storage-csi-dynamic-provisioning.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi.adoc - -[id="csi-dynamic-provisioning_{context}"] -= Dynamic provisioning - -Dynamic provisioning of persistent storage depends on the capabilities of -the CSI driver and underlying storage back end. The provider of the CSI -driver should document how to create a storage class in {product-title} and -the parameters available for configuration. - -The created storage class can be configured to enable dynamic provisioning. - -.Procedure - -* Create a default storage class that ensures all PVCs that do not require -any special storage class are provisioned by the installed CSI driver. -+ -[source,shell] ----- -# oc create -f - << EOF -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: <storage-class> <1> - annotations: - storageclass.kubernetes.io/is-default-class: "true" -provisioner: <provisioner-name> <2> -parameters: -EOF ----- -<1> The name of the storage class that will be created. -<2> The name of the CSI driver that has been installed diff --git a/modules/persistent-storage-csi-ebs-operator-install-driver.adoc b/modules/persistent-storage-csi-ebs-operator-install-driver.adoc deleted file mode 100644 index 08f41c35c99d..000000000000 --- a/modules/persistent-storage-csi-ebs-operator-install-driver.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-ebs.adoc - -[id="persistent-storage-csi-ebs-operator-install-driver_{context}"] -= Installing the AWS Elastic Block Store CSI driver - -The AWS Elastic Block Store (EBS) Container Storage Interface (CSI) driver is a custom resource (CR) that enables you to create and mount AWS EBS persistent volumes. - -The driver is not installed in {product-title} by default, and must be installed after the AWS EBS CSI Driver Operator has been installed. - -.Prerequisites - -* The AWS EBS CSI Driver Operator has been installed. -* You have access to the {product-title} web console. - -.Procedure - -To install the AWS EBS CSI driver from the web console, complete the following steps: - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *Installed Operators*. - -. Locate the *AWS EBS CSI Driver Operator* from the list and click on the Operator link. - -. Create the driver: -.. From the *Details* tab, click *Create Instance*. - -.. Optional: Select *YAML view* to make modifications, such as adding notations, to the driver object template. - -.. Click *Create* to finalize. -+ -[IMPORTANT] -==== -Renaming the cluster and specifying a certain namespace are not supported functions. -==== diff --git a/modules/persistent-storage-csi-ebs-operator-install.adoc b/modules/persistent-storage-csi-ebs-operator-install.adoc deleted file mode 100644 index 924bbbe39495..000000000000 --- a/modules/persistent-storage-csi-ebs-operator-install.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-ebs.adoc - -[id="persistent-storage-csi-ebs-operator-install_{context}"] -= Installing the AWS Elastic Block Store CSI Driver Operator - -The AWS Elastic Block Store (EBS) Container Storage Interface (CSI) Driver Operator enables the replacement of the existing AWS EBS in-tree storage plug-in. - -[IMPORTANT] -==== -AWS EBS CSI Driver Operator is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. -==== - -Installing the AWS EBS CSI Driver Operator provides the CSI driver that allows you to use CSI volumes with the `PersistentVolumeClaims`, `PersistentVolumes`, and `StorageClasses` API objects in {product-title}. It also deploys the StorageClass that you can use to create persistent volume claims (PVCs). - -The AWS EBS CSI Driver Operator is not installed in {product-title} by default. Use the following procedure to install and configure this Operator to enable the AWS EBS CSI driver in your cluster. - -.Prerequisites -* Access to the {product-title} web console. - -.Procedure -To install the AWS EBS CSI Driver Operator from the web console: - -. Log in to the web console. - -. Navigate to *Operators* -> *OperatorHub*. - -. To locate the AWS EBS CSI Driver Operator, type *AWS EBS CSI* into the filter box. - -. Click *Install*. - -. On the *Install Operator* page, be sure that *All namespaces on the cluster (default)* is selected. Select *openshift-aws-ebs-csi-driver-operator* from the *Installed Namespace* drop-down menu. - -. Adjust the values for *Update Channel* and *Approval Strategy* to the values that you want. - -. Click *Install*. - -Once finished, the AWS EBS CSI Driver Operator is listed in the *Installed Operators* section of the web console. diff --git a/modules/persistent-storage-csi-external-controllers.adoc b/modules/persistent-storage-csi-external-controllers.adoc deleted file mode 100644 index 5a2c54e0c1f5..000000000000 --- a/modules/persistent-storage-csi-external-controllers.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent_storage-csi.adoc - -[id="external-csi-contollers_{context}"] -= External CSI controllers - -External CSI Controllers is a deployment that deploys one or more pods -with three containers: - -* An external CSI attacher container translates `attach` and `detach` -calls from {product-title} to respective `ControllerPublish` and -`ControllerUnpublish` calls to the CSI driver. -* An external CSI provisioner container that translates `provision` and -`delete` calls from {product-title} to respective `CreateVolume` and -`DeleteVolume` calls to the CSI driver. -* A CSI driver container - -The CSI attacher and CSI provisioner containers communicate with the CSI -driver container using UNIX Domain Sockets, ensuring that no CSI -communication leaves the pod. The CSI driver is not accessible from -outside of the pod. - -[NOTE] -==== -`attach`, `detach`, `provision`, and `delete` operations typically require -the CSI driver to use credentials to the storage backend. Run the CSI -controller pods on infrastructure nodes so the credentials are never leaked -to user processes, even in the event of a catastrophic security breach -on a compute node. -==== - -[NOTE] -==== -The external attacher must also run for CSI drivers that do not support -third-party `attach` or `detach` operations. The external attacher will -not issue any `ControllerPublish` or `ControllerUnpublish` operations to -the CSI driver. However, it still must run to implement the necessary -{product-title} attachment API. -==== diff --git a/modules/persistent-storage-csi-gcp-pd-encrypted-pv.adoc b/modules/persistent-storage-csi-gcp-pd-encrypted-pv.adoc deleted file mode 100644 index 588852fdb87c..000000000000 --- a/modules/persistent-storage-csi-gcp-pd-encrypted-pv.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc - -[id="persistent-storage-csi-gcp-pd-encrypted-pv_{context}"] -= Creating a custom-encrypted persistent volume - -When you create a `PersistentVolumeClaim` object, {product-title} provisions a new persistent volume (PV) and creates a `PersistentVolume` object. You can add a custom encryption key in Google Cloud Platform (GCP) to protect a PV in your cluster by encrypting the newly created PV. - -For encryption, the newly attached PV that you create uses customer-managed encryption keys (CMEK) on a cluster by using a new or existing Google Cloud Key Management Service (KMS) key. - -.Prerequisites -* You are logged in to a running {product-title} cluster. -* You have created a Cloud KMS key ring and key version. - -For more information about CMEK and Cloud KMS resources, see link:https://cloud.google.com/kubernetes-engine/docs/how-to/using-cmek[Using customer-managed encryption keys (CMEK)]. - -.Procedure -To create a custom-encrypted PV, complete the following steps: - -. Create a storage class with the Cloud KMS key. The following example enables dynamic provisioning of encrypted volumes: -+ -[source,yaml] --- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: csi-gce-pd-cmek -provisioner: pd.csi.storage.gke.io -volumeBindingMode: "WaitForFirstConsumer" -allowVolumeExpansion: true -parameters: - type: pd-standard - disk-encryption-kms-key: projects/<key-project-id>/locations/<location>/keyRings/<key-ring>/cryptoKeys/<key> <1> --- -<1> This field must be the resource identifier for the key that will be used to encrypt new disks. Values are case-sensitive. For more information about providing key ID values, see link:https://cloud.google.com/kms/docs/resource-hierarchy#retrieve_resource_id[Retrieving a resource's ID] and link:https://cloud.google.com/kms/docs/getting-resource-ids[Getting a Cloud KMS resource ID]. -+ -[NOTE] -==== -You cannot add the `disk-encryption-kms-key` parameter to an existing storage class. However, you can delete the storage class and recreate it with the same name and a different set of parameters. If you do this, the provisioner of the existing class must be `pd.csi.storage.gke.io`. -==== - -. Deploy the storage class on your {product-title} cluster using the `oc` command: -+ -[source,terminal] --- -$ oc describe storageclass csi-gce-pd-cmek --- -+ -.Example output -[source,terminal] --- -Name: csi-gce-pd-cmek -IsDefaultClass: No -Annotations: None -Provisioner: pd.csi.storage.gke.io -Parameters: disk-encryption-kms-key=projects/key-project-id/locations/location/keyRings/ring-name/cryptoKeys/key-name,type=pd-standard -AllowVolumeExpansion: unset -MountOptions: none -ReclaimPolicy: Delete -VolumeBindingMode: WaitForFirstConsumer -Events: none --- - -. Create a file named `pvc.yaml` that matches the name of your storage class object that you created in the previous step: -+ -[source,yaml] --- -kind: PersistentVolumeClaim -apiVersion: v1 -metadata: - name: podpvc -spec: - accessModes: - - ReadWriteOnce - storageClassName: csi-gce-pd-cmek - resources: - requests: - storage: 6Gi --- -+ -[NOTE] -==== -If you marked the new storage class as default, you can omit the `storageClassName` field. -==== - -. Apply the PVC on your cluster: -+ -[source,terminal] --- -$ oc apply -f pvc.yaml --- - -. Get the status of your PVC and verify that it is created and bound to a newly provisioned PV: -+ -[source,terminal] --- -$ oc get pvc --- -+ -[source,terminal] -.Example output --- -NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE -podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd-cmek 9s --- -+ -[NOTE] -==== -If your storage class has the `volumeBindingMode` field set to `WaitForFirstConsumer`, you must create a pod to use the PVC before you can verify it. -==== - -Your CMEK-protected PV is now ready to use with your {product-title} cluster. diff --git a/modules/persistent-storage-csi-gcp-pd-storage-class-ref.adoc b/modules/persistent-storage-csi-gcp-pd-storage-class-ref.adoc deleted file mode 100644 index 3f7b3ce3bb2b..000000000000 --- a/modules/persistent-storage-csi-gcp-pd-storage-class-ref.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc - -[id="persistent-storage-csi-gcp-pd-storage-class-ref_{context}"] -= GCP PD CSI driver storage class parameters - -The Google Cloud Platform (GCP) persistent disk (PD) Container Storage Interface (CSI) driver uses the CSI `external-provisioner` sidecar as a controller. This is a separate helper container that is deployed with the CSI driver. The sidecar manages persistent volumes (PVs) by triggering the `CreateVolume` operation. - -The GCP PD CSI driver uses the `csi.storage.k8s.io/fstype` parameter key to support dynamic provisioning. The following table describes all the GCP PD CSI storage class parameters that are supported by {product-title}. - -.CreateVolume Parameters -[cols="2,3,2,4",options="header"] -|=== -|Parameter |Values |Default |Description - -|`type` | `pd-ssd` or `pd-standard` | `pd-standard` | Allows you to choose between standard PVs or solid-state-drive PVs. -|`replication-type`| `none` or `regional-pd` | `none` | Allows you to choose between zonal or regional PVs. -|`disk-encryption-kms-key` | Fully qualified resource identifier for the key to use to encrypt new disks. | Empty string | Uses customer-managed encryption keys (CMEK) to encrypt new disks. -|=== diff --git a/modules/persistent-storage-csi-manila-dynamic-provisioning.adoc b/modules/persistent-storage-csi-manila-dynamic-provisioning.adoc deleted file mode 100644 index 559679324ad8..000000000000 --- a/modules/persistent-storage-csi-manila-dynamic-provisioning.adoc +++ /dev/null @@ -1,92 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-manila.adoc - -[id="persistent-storage-csi-manila-dynamic-provisioning_{context}"] -= Dynamically provisioning Manila CSI volumes - -{product-title} installs a storage class for each available Manila share type. - -The YAML files that are created are completely decoupled from Manila and from its Container Storage Interface (CSI) plug-in. As an application developer, you can dynamically provision ReadWriteMany (RWX) storage and deploy pods with applications that safely consume the storage using YAML manifests. - -You can use the same pod and persistent volume claim (PVC) definitions on-premise that you use with {product-title} on AWS, GCP, Azure, and other platforms, with the exception of the storage class reference in the PVC definition. - -[NOTE] -==== -Manila service is optional. If the service is not enabled in {rh-openstack-first}, the Manila CSI driver is not installed and the storage classes for Manila are not created. -==== - -.Prerequisites - -* {rh-openstack} is deployed with appropriate Manila share infrastructure so that it can be used to dynamically provision and mount volumes in {product-title}. - -.Procedure (UI) - -To dynamically create a Manila CSI volume using the web console: - -. In the {product-title} console, click *Storage* → *Persistent Volume Claims*. - -. In the persistent volume claims overview, click *Create Persistent Volume Claim*. - -. Define the required options on the resulting page. - -.. Select the appropriate storage class. - -.. Enter a unique name for the storage claim. - -.. Select the access mode to specify read and write access for the PVC you are creating. -+ -[IMPORTANT] -==== -Use RWX if you want the persistent volume (PV) that fulfills this PVC to be mounted to multiple pods on multiple nodes in the cluster. -==== - -. Define the size of the storage claim. - -. Click *Create* to create the persistent volume claim and generate a persistent volume. - -.Procedure (CLI) - -To dynamically create a Manila CSI volume using the command-line interface (CLI): - -. Create and save a file with the `PersistentVolumeClaim` object described by the following YAML: - -+ -.pvc-manila.yaml -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: pvc-manila -spec: - accessModes: <1> - - ReadWriteMany - resources: - requests: - storage: 10Gi - storageClassName: csi-manila-gold <2> ----- -+ -<1> Use RWX if you want the persistent volume (PV) that fulfills this PVC to be mounted to multiple pods on multiple nodes in the cluster. -<2> The name of the storage class that provisions the storage back end. Manila storage classes are provisioned by the Operator and have the `csi-manila-` prefix. -+ -. Create the object you saved in the previous step by running the following command: -+ -[source,terminal] ----- -$ oc create -f pvc-manila.yaml ----- -+ -A new PVC is created. - -. To verify that the volume was created and is ready, run the following command: -+ -[source,terminal] ----- -$ oc get pvc pvc-manila ----- -+ -The `pvc-manila` shows that it is `Bound`. - -You can now use the new PVC to configure a pod. diff --git a/modules/persistent-storage-csi-manila-install-driver.adoc b/modules/persistent-storage-csi-manila-install-driver.adoc deleted file mode 100644 index 5cb52e16111e..000000000000 --- a/modules/persistent-storage-csi-manila-install-driver.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-manila.adoc - -[id="persistent-storage-csi-manila-install-driver_{context}"] -= Installing the OpenStack Manila CSI driver - -The OpenStack Manila Container Storage Interface (CSI) driver is a custom resource (CR) that enables you to create and mount OpenStack Manila shares. It also supports creating snapshots, and recovering shares from snapshots. - -The driver is not installed in {product-title} by default, and must be installed after the Manila CSI Driver Operator has been installed. - -.Prerequisites - -* The Manila CSI Driver Operator has been installed. -* Access to the {product-title} web console or command-line interface (CLI). - -.UI procedure - -To install the Manila CSI driver from the web console, complete the following steps: - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *Installed Operators*. - -. Locate the *Manila CSI Driver Operator* from the list and click on the Operator link. - -. Create the driver: -.. From the *Details* tab, click *Create Instance*. - -.. Optional: Select *YAML view* to make modifications, such as adding notations, to the ManilaDriver object template. - -.. Click *Create* to finalize. -+ -[IMPORTANT] -==== -Renaming the cluster and specifying a certain namespace are not supported functions. -==== - -.CLI procedure - -To install the Manila CSI driver from the CLI, complete the following steps: - -. Create an object YAML file, such as `maniladriver.yaml`, to define the ManilaDriver: -+ -.Example maniladriver -[source,yaml] ----- - apiVersion: csi.openshift.io/v1alpha1 - kind: ManilaDriver - metadata: - name: cluster <1> ----- -<1> Renaming the cluster and specifying a certain namespace are not supported functions. - -. Create the ManilaDriver CR object in your {product-title} cluster by specifying the file you created in the previous step: -+ ----- -$ oc create -f maniladriver.yaml ----- - -When the Operator installation is finished, the Manila CSI driver is deployed on {product-title} for dynamic provisioning of RWX persistent volumes on {rh-openstack-first}. - -.Verification -. Verify that the ManilaDriver CR was created successfully by entering the following command: -+ -[source,terminal] ----- -$ oc get all -n openshift-manila-csi-driver ----- -+ -.Example output -+ -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -pod/csi-nodeplugin-nfsplugin-lzvpm 1/1 Running 0 18h -pod/csi-nodeplugin-nfsplugin-slvg2 1/1 Running 0 18h -pod/csi-nodeplugin-nfsplugin-xmps9 1/1 Running 0 18h -pod/openstack-manila-csi-controllerplugin-7d4f5d985b-mw4x5 3/3 Running 0 17h -pod/openstack-manila-csi-nodeplugin-6xchs 2/2 Running 0 18h -pod/openstack-manila-csi-nodeplugin-bkcmz 2/2 Running 0 18h -pod/openstack-manila-csi-nodeplugin-rlpps 2/2 Running 0 18h - -NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE -daemonset.apps/csi-nodeplugin-nfsplugin 3 3 3 3 3 18h -daemonset.apps/openstack-manila-csi-nodeplugin 3 3 3 3 3 18h - -NAME READY UP-TO-DATE AVAILABLE AGE -deployment.apps/openstack-manila-csi-controllerplugin 1/1 1 1 18h - -NAME DESIRED CURRENT READY AGE -replicaset.apps/openstack-manila-csi-controllerplugin-7d4f5d985b 1 1 1 17h - ----- - -. Verify that the storage class was created successfully by entering the following command: -+ -[source,terminal] ----- -$ oc get storageclasses | grep -E "NAME|csi-manila-" ----- -+ -.Example output -+ -[source,terminal] ----- -NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE -csi-manila-gold manila.csi.openstack.org Delete Immediate false 18h ----- diff --git a/modules/persistent-storage-csi-manila-install-operator.adoc b/modules/persistent-storage-csi-manila-install-operator.adoc deleted file mode 100644 index 30cefe6f8d4e..000000000000 --- a/modules/persistent-storage-csi-manila-install-operator.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-manila.adoc - -[id="persistent-storage-csi-manila-install-operator_{context}"] -= Installing the Manila CSI Driver Operator - -The Manila Container Storage Interface (CSI) Driver Operator is not installed in {product-title} by default. Use the following procedure to install and configure this Operator to enable the OpenStack Manila CSI driver in your cluster. - -.Prerequisites -* You have access to the {product-title} web console. -* The underlying {rh-openstack-first} infrastructure cloud deploys Manila serving NFS shares. - -.Procedure - -To install the Manila CSI Driver Operator from the web console, follow these steps: - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *OperatorHub*. - -. Type *Manila CSI Driver Operator* into the filter box to locate the Operator. - -. Click *Install*. - -. On the *Install Operator* page, select *openshift-manila-csi-driver-operator* from the *Installed Namespace* drop-down menu. - -. Adjust the values for *Update Channel* and *Approval Strategy* to the values that you want. The only supported *Installation Mode* is *All namespaces on the cluster*. - -. Click *Install*. - -Once finished, the Manila CSI Driver Operator is listed in the *Installed Operators* section of the web console. diff --git a/modules/persistent-storage-csi-manila-uninstall-operator.adoc b/modules/persistent-storage-csi-manila-uninstall-operator.adoc deleted file mode 100644 index 80360c14abec..000000000000 --- a/modules/persistent-storage-csi-manila-uninstall-operator.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-manila.adoc - -[id="persistent-storage-csi-manila-uninstall-operator_{context}"] -= Uninstalling the Manila CSI Driver Operator - -Before you uninstall the Manila Container Storage Interface (CSI) Driver Operator, you must delete all persistent volume claims (PVCs) that are in use by the Operator. - -.Prerequisites -* Access to the {product-title} web console. - -.Procedure -To uninstall the Manila CSI Driver Operator from the web console: - -. Log in to the web console. - -. Navigate to *Storage* -> *Persistent Volume Claims*. - -. Select any PVCs that are in use by the Manila CSI Driver Operator and click *Delete*. - -. From the *Operators* -> *Installed Operators* page, scroll or type *Manila CSI* into the *Filter by name* field to find the Operator. Then, click on it. - -. On the right-hand side of the *Installed Operators* details page, select *Uninstall Operator* from the *Actions* drop-down menu. - -. When prompted by the *Uninstall Operator* window, click the *Uninstall* button to remove the Operator from the namespace. Any applications deployed by the Operator on the cluster will need to be cleaned up manually. - -Once finished, the Manila CSI Driver Operator is no longer listed in the *Installed Operators* section of the web console. diff --git a/modules/persistent-storage-csi-mysql-example.adoc b/modules/persistent-storage-csi-mysql-example.adoc deleted file mode 100644 index 413a94586441..000000000000 --- a/modules/persistent-storage-csi-mysql-example.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies -// -// * storage/container_storage_interface/persistent_storage-csi.adoc - -[id="csi-example-usage_{context}"] -= Example using the CSI driver - -The following example installs a default MySQL template without any -changes to the template. - -.Prerequisites - -* The CSI driver has been deployed. -* A storage class has been created for dynamic provisioning. - -.Procedure - -* Create the MySQL template: -+ -[source,terminal] ----- -# oc new-app mysql-persistent ----- -+ -.Example output -[source,terminal] ----- ---> Deploying template "openshift/mysql-persistent" to project default -... ----- -+ -[source,terminal] ----- -# oc get pvc ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS VOLUME CAPACITY -ACCESS MODES STORAGECLASS AGE -mysql Bound kubernetes-dynamic-pv-3271ffcb4e1811e8 1Gi -RWO cinder 3s ----- diff --git a/modules/persistent-storage-csi-snapshots-controller-sidecar.adoc b/modules/persistent-storage-csi-snapshots-controller-sidecar.adoc deleted file mode 100644 index 14741bcde37e..000000000000 --- a/modules/persistent-storage-csi-snapshots-controller-sidecar.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-snapshots.adoc - -[id="persistent-storage-csi-snapshots-controller-sidecar_{context}"] -= CSI snapshot controller and sidecar - -{product-title} provides a snapshot controller that is deployed into the control plane. In addition, your CSI driver vendor provides the CSI snapshot sidecar as a helper container that is installed during the CSI driver installation. - -The CSI snapshot controller and sidecar provide volume snapshotting through the {product-title} API. These external components run in the cluster. - -The external controller is deployed by the CSI Snapshot Controller Operator. - -== External controller -The CSI snapshot controller binds `VolumeSnapshot` and `VolumeSnapshotContent` objects. The controller manages dynamic provisioning by creating and deleting `VolumeSnapshotContent` objects. - -== External sidecar -Your CSI driver vendor provides the `csi-external-snapshotter` sidecar. This is a separate helper container that is deployed with the CSI driver. The sidecar manages snapshots by triggering `CreateSnapshot` and `DeleteSnapshot` operations. Follow the installation instructions provided by your vendor. diff --git a/modules/persistent-storage-csi-snapshots-create.adoc b/modules/persistent-storage-csi-snapshots-create.adoc deleted file mode 100644 index db8bb78c950c..000000000000 --- a/modules/persistent-storage-csi-snapshots-create.adoc +++ /dev/null @@ -1,145 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-snapshots.adoc - -[id="persistent-storage-csi-snapshots-create_{context}"] -= Creating a volume snapshot - -When you create a `VolumeSnapshot` object, {product-title} creates a volume snapshot. - - -.Prerequisites -* Logged in to a running {product-title} cluster. -* A PVC created using a CSI driver that supports `VolumeSnapshot` objects. -* A storage class to provision the storage back end. -* No pods are using the persistent volume claim (PVC) that you want to take a snapshot of. -+ -[NOTE] -==== -Do not create a volume snapshot of a PVC if a pod is using it. Doing so might cause data corruption because the PVC is not quiesced (paused). Be sure to first tear down a running pod to ensure consistent snapshots. -==== - -.Procedure - -To dynamically create a volume snapshot: - -. Create a file with the `VolumeSnapshotClass` object described by the following YAML: - -+ -.volumesnapshotclass.yaml -[source,yaml] ----- -apiVersion: snapshot.storage.k8s.io/v1 -kind: VolumeSnapshotClass -metadata: - name: csi-hostpath-snap -driver: hostpath.csi.k8s.io <1> -deletionPolicy: Delete ----- -+ -<1> The name of the CSI driver that is used to create snapshots of this `VolumeSnapshotClass` object. The name must be the same as the `Provisioner` field of the storage class that is responsible for the PVC that is being snapshotted. - -. Create the object you saved in the previous step by entering the following command: -+ -[source,terminal] ----- -$ oc create -f volumesnapshotclass.yaml ----- - -. Create a `VolumeSnapshot` object: - -+ -.volumesnapshot-dynamic.yaml -[source,yaml] ----- -apiVersion: snapshot.storage.k8s.io/v1 -kind: VolumeSnapshot -metadata: - name: mysnap -spec: - volumeSnapshotClassName: csi-hostpath-snap <1> - source: - persistentVolumeClaimName: myclaim <2> ----- -+ -<1> The request for a particular class by the volume snapshot. If the `volumeSnapshotClassName` setting is absent and there is a default volume snapshot class, a snapshot is created with the default volume snapshot class name. But if the field is absent and no default volume snapshot class exists, then no snapshot is created. -+ -<2> The name of the `PersistentVolumeClaim` object bound to a persistent volume. This defines what you want to create a snapshot of. Required for dynamically provisioning a snapshot. - -. Create the object you saved in the previous step by entering the following command: -+ -[source,terminal] ----- -$ oc create -f volumesnapshot-dynamic.yaml ----- - - -To manually provision a snapshot: - -. Provide a value for the `volumeSnapshotContentName` parameter as the source for the snapshot, in addition to defining volume snapshot class as shown above. -+ -.volumesnapshot-manual.yaml -[source,yaml] ----- -apiVersion: snapshot.storage.k8s.io/v1 -kind: VolumeSnapshot -metadata: - name: snapshot-demo -spec: - source: - volumeSnapshotContentName: mycontent <1> ----- -<1> The `volumeSnapshotContentName` parameter is required for pre-provisioned snapshots. - -. Create the object you saved in the previous step by entering the following command: -+ -[source,terminal] ----- -$ oc create -f volumesnapshot-manual.yaml ----- - -.Verification -After the snapshot has been created in the cluster, additional details about the snapshot are available. - -. To display details about the volume snapshot that was created, enter the following command: -+ -[source,terminal] ----- -$ oc describe volumesnapshot mysnap ----- -+ -The following example displays details about the `mysnap` volume snapshot: -+ -.volumesnapshot.yaml -[source,yaml] ----- -apiVersion: snapshot.storage.k8s.io/v1 -kind: VolumeSnapshot -metadata: - name: mysnap -spec: - source: - persistentVolumeClaimName: myclaim - volumeSnapshotClassName: csi-hostpath-snap -status: - boundVolumeSnapshotContentName: snapcontent-1af4989e-a365-4286-96f8-d5dcd65d78d6 <1> - creationTime: "2020-01-29T12:24:30Z" <2> - readyToUse: true <3> - restoreSize: 500Mi ----- -<1> The pointer to the actual storage content that was created by the controller. -<2> The time when the snapshot was created. The snapshot contains the volume content that was available at this indicated time. -<3> If the value is set to `true`, the snapshot can be used to restore as a new PVC. - + -If the value is set to `false`, the snapshot was created. However, the storage back end needs to perform additional tasks to make the snapshot usable so that it can be restored as a new volume. For example, Amazon Elastic Block Store data might be moved to a different, less expensive location, which can take several minutes. - -. To verify that the volume snapshot was created, enter the following command: -+ -[source,terminal] ----- -$ oc get volumesnapshotcontent ----- -+ -The pointer to the actual content is displayed. If the `boundVolumeSnapshotContentName` field is populated, a `VolumeSnapshotContent` object exists and the snapshot was created. - -. To verify that the snapshot is ready, confirm that the `VolumeSnapshot` object has `readyToUse: true`. diff --git a/modules/persistent-storage-csi-snapshots-delete.adoc b/modules/persistent-storage-csi-snapshots-delete.adoc deleted file mode 100644 index 8c511ed9d1b6..000000000000 --- a/modules/persistent-storage-csi-snapshots-delete.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-snapshots.adoc - -[id="persistent-storage-csi-snapshots-delete_{context}"] -= Deleting a volume snapshot - -You can configure how {product-title} deletes volume snapshots. - -.Procedure - -. Specify the deletion policy that you require in the `VolumeSnapshotClass` object, as shown in the following example: -+ -.volumesnapshotclass.yaml -[source,yaml] ----- -apiVersion: snapshot.storage.k8s.io/v1 -kind: VolumeSnapshotClass -metadata: - name: csi-hostpath-snap -driver: hostpath.csi.k8s.io -deletionPolicy: Delete <1> ----- -<1> When deleting the volume snapshot, if the `Delete` value is set, the underlying snapshot is deleted along with the `VolumeSnapshotContent` object. If the `Retain` value is set, both the underlying snapshot and `VolumeSnapshotContent` object remain. - + -If the `Retain` value is set and the `VolumeSnapshot` object is deleted without deleting the corresponding `VolumeSnapshotContent` object, the content remains. The snapshot itself is also retained in the storage back end. - -. Delete the volume snapshot by entering the following command: - -+ -[source,terminal] ----- -$ oc delete volumesnapshot <volumesnapshot_name> ----- -+ -.Example output -[source, terminal] ----- -volumesnapshot.snapshot.storage.k8s.io "mysnapshot" deleted ----- -. If the deletion policy is set to `Retain`, delete the volume snapshot content by entering the following command: -+ -[source,terminal] ----- -$ oc delete volumesnapshotcontent <volumesnapshotcontent_name> ----- -+ -. Optional: If the `VolumeSnapshot` object is not successfully deleted, enter the following command to remove any finalizers for the leftover resource so that the delete operation can continue: -+ -[IMPORTANT] -==== -Only remove the finalizers if you are confident that there are no existing references from either persistent volume claims or volume snapshot contents to the `VolumeSnapshot` object. -Even with the `--force` option, the delete operation does not delete snapshot objects until all finalizers are removed. -==== -+ -[source,terminal] ----- -$ oc patch -n $PROJECT volumesnapshot/$NAME --type=merge -p '{"metadata": {"finalizers":null}}' ----- -+ -.Example output -[source, terminal] ----- -volumesnapshotclass.snapshot.storage.k8s.io "csi-ocs-rbd-snapclass" deleted ----- -+ -The finalizers are removed and the volume snapshot is deleted. diff --git a/modules/persistent-storage-csi-snapshots-operator.adoc b/modules/persistent-storage-csi-snapshots-operator.adoc deleted file mode 100644 index 96776538778d..000000000000 --- a/modules/persistent-storage-csi-snapshots-operator.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-snapshots.adoc - -[id="persistent-storage-csi-snapshots-operator_{context}"] -= About the CSI Snapshot Controller Operator - -The CSI Snapshot Controller Operator runs in the `openshift-cluster-storage-operator` namespace. It is installed by the Cluster Version Operator (CVO) in all clusters by default. - -The CSI Snapshot Controller Operator installs the CSI snapshot controller, which runs in the `openshift-cluster-storage-operator` namespace. - -== Volume snapshot CRDs - -During {product-title} installation, the CSI Snapshot Controller Operator creates the following snapshot custom resource definitions (CRDs) in the `snapshot.storage.k8s.io/v1` API group: - -`VolumeSnapshotContent`:: - -A snapshot taken of a volume in the cluster that has been provisioned by a cluster administrator. -+ -Similar to the `PersistentVolume` object, the `VolumeSnapshotContent` CRD is a cluster resource that points to a real snapshot in the storage back end. -+ -For manually pre-provisioned snapshots, a cluster administrator creates a number of `VolumeSnapshotContent` CRDs. These carry the details of the real volume snapshot in the storage system. -+ -The `VolumeSnapshotContent` CRD is not namespaced and is for use by a cluster administrator. - -`VolumeSnapshot`:: - -Similar to the `PersistentVolumeClaim` object, the `VolumeSnapshot` CRD defines a developer request for a snapshot. The CSI Snapshot Controller Operator runs the CSI snapshot controller, which handles the binding of a `VolumeSnapshot` CRD with an appropriate `VolumeSnapshotContent` CRD. The binding is a one-to-one mapping. -+ -The `VolumeSnapshot` CRD is namespaced. A developer uses the CRD as a distinct request for a snapshot. - -`VolumeSnapshotClass`:: - -Allows a cluster administrator to specify different attributes belonging to a `VolumeSnapshot` object. These attributes may differ among snapshots taken of the same volume on the storage system, in which case they would not be expressed by using the same storage class of a persistent volume claim. -+ -The `VolumeSnapshotClass` CRD defines the parameters for the `csi-external-snapshotter` sidecar to use when creating a snapshot. This allows the storage back end to know what kind of snapshot to dynamically create if multiple options are supported. -+ -Dynamically provisioned snapshots use the `VolumeSnapshotClass` CRD to specify storage-provider-specific parameters to use when creating a snapshot. -+ -The `VolumeSnapshotContentClass` CRD is not namespaced and is for use by a cluster administrator to enable global configuration options for their storage back end. diff --git a/modules/persistent-storage-csi-snapshots-overview.adoc b/modules/persistent-storage-csi-snapshots-overview.adoc deleted file mode 100644 index c7984a3b82d6..000000000000 --- a/modules/persistent-storage-csi-snapshots-overview.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-snapshots.adoc - -[id="persistent-storage-csi-snapshots-overview_{context}"] -= Overview of CSI volume snapshots - -A _snapshot_ represents the state of the storage volume in a cluster at a particular point in time. Volume snapshots can be used to provision a new volume. - -{product-title} supports CSI volume snapshots by default. However, a specific CSI driver is required. - -With CSI volume snapshots, a cluster administrator can: - -* Deploy a third-party CSI driver that supports snapshots. -* Create a new persistent volume claim (PVC) from an existing volume snapshot. -* Take a snapshot of an existing PVC. -* Restore a snapshot as a different PVC. -* Delete an existing volume snapshot. - -With CSI volume snapshots, an app developer can: - -* Use volume snapshots as building blocks for developing application- or cluster-level storage backup solutions. -* Rapidly rollback to a previous development version. -* Use storage more efficiently by not having to make a full copy each time. - -Be aware of the following when using volume snapshots: - -* Support is only available for CSI drivers. In-tree and FlexVolumes are not supported. -* {product-title} only ships with select CSI drivers. For CSI drivers that are not provided by an {product-title} Driver Operator, it is recommended to use the CSI drivers provided by -link:https://kubernetes-csi.github.io/docs/drivers.html[community or storage vendors]. Follow the installation instructions provided by the CSI driver. -* CSI drivers may or may not have implemented the volume snapshot functionality. CSI drivers that have provided support for volume snapshots will likely use the `csi-external-snapshotter` sidecar. See documentation provided by the CSI driver for details. -* {product-title} {product-version} supports version 1.1.0 of the link:https://github.com/container-storage-interface/spec[CSI specification]. diff --git a/modules/persistent-storage-csi-snapshots-provision.adoc b/modules/persistent-storage-csi-snapshots-provision.adoc deleted file mode 100644 index 408066cd0655..000000000000 --- a/modules/persistent-storage-csi-snapshots-provision.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-snapshots.adoc - -[id="persistent-storage-csi-snapshots-provision_{context}"] -= Volume snapshot provisioning - -There are two ways to provision snapshots: dynamically and manually. - -[id="snapshots-dynamic-provisioning_{context}"] -== Dynamic provisioning - -Instead of using a preexisting snapshot, you can request that a snapshot be taken dynamically from a persistent volume claim. Parameters are specified using a `VolumeSnapshotClass` CRD. - -[id="snapshots-manual-provisioning_{context}"] -== Manual provisioning - -As a cluster administrator, you can manually pre-provision a number of `VolumeSnapshotContent` objects. These carry the real volume snapshot details available to cluster users. diff --git a/modules/persistent-storage-csi-snapshots-restore.adoc b/modules/persistent-storage-csi-snapshots-restore.adoc deleted file mode 100644 index 5464e0909ec1..000000000000 --- a/modules/persistent-storage-csi-snapshots-restore.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/container_storage_interface/persistent-storage-csi-snapshots.adoc - -[id="persistent-storage-csi-snapshots-restore_{context}"] -= Restoring a volume snapshot - -The `VolumeSnapshot` CRD content can be used to restore the existing volume to a previous state. - -After your `VolumeSnapshot` CRD is bound and the `readyToUse` value is set to `true`, you can use that resource to provision a new volume that is pre-populated with data from the snapshot. -.Prerequisites -* Logged in to a running {product-title} cluster. -* A persistent volume claim (PVC) created using a Container Storage Interface (CSI) driver that supports volume snapshots. -* A storage class to provision the storage back end. -* A volume snapshot has been created and is ready to use. - -.Procedure - -. Specify a `VolumeSnapshot` data source on a PVC as shown in the following: -+ -.pvc-restore.yaml -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: myclaim-restore -spec: - storageClassName: csi-hostpath-sc - dataSource: - name: mysnap <1> - kind: VolumeSnapshot <2> - apiGroup: snapshot.storage.k8s.io <3> - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi ----- -<1> Name of the `VolumeSnapshot` object representing the snapshot to use as source. -<2> Must be set to the `VolumeSnapshot` value. -<3> Must be set to the `snapshot.storage.k8s.io` value. - -. Create a PVC by entering the following command: - -+ -[source,terminal] ----- -$ oc create -f pvc-restore.yaml ----- - -. Verify that the restored PVC has been created by entering the following command: - -+ -[source,terminal] ----- -$ oc get pvc ----- -+ -A new PVC such as `myclaim-restore` is displayed. diff --git a/modules/persistent-storage-fibre-disk-quotas.adoc b/modules/persistent-storage-fibre-disk-quotas.adoc deleted file mode 100644 index f17450c16691..000000000000 --- a/modules/persistent-storage-fibre-disk-quotas.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persitent-storage/persistent_storage-fibre.adoc - -[id="enforcing-disk-quota_{context}"] -= Enforcing disk quotas -Use LUN partitions to enforce disk quotas and size constraints. -Each LUN is mapped to a single persistent volume, and unique -names must be used for persistent volumes. - -Enforcing quotas in this way allows the end user to request persistent storage -by a specific amount, such as 10Gi, and be matched with a corresponding volume -of equal or greater capacity. diff --git a/modules/persistent-storage-fibre-provisioning.adoc b/modules/persistent-storage-fibre-provisioning.adoc deleted file mode 100644 index 23f06cc28dbc..000000000000 --- a/modules/persistent-storage-fibre-provisioning.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-fibre.adoc - -[id="provisioning-fibre_{context}"] -= Provisioning -To provision Fibre Channel volumes using the `PersistentVolume` API -the following must be available: - -* The `targetWWNs` (array of Fibre Channel target's World Wide -Names). -* A valid LUN number. -* The filesystem type. - -A persistent volume and a LUN have a one-to-one mapping between them. - -.Prerequisites - -* Fibre Channel LUNs must exist in the underlying infrastructure. - -.`PersistentVolume` object definition - -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: pv0001 -spec: - capacity: - storage: 1Gi - accessModes: - - ReadWriteOnce - fc: - targetWWNs: ['500a0981891b8dc5', '500a0981991b8dc5'] <1> - lun: 2 - fsType: ext4 ----- -<1> Fibre Channel WWNs are identified as -`/dev/disk/by-path/pci-<IDENTIFIER>-fc-0x<WWN>-lun-<LUN#>`, -but you do not need to provide any part of the path leading up to the `WWN`, -including the `0x`, and anything after, including the `-` (hyphen). - -[IMPORTANT] -==== -Changing the value of the `fstype` parameter after the volume has been -formatted and provisioned can result in data loss and pod failure. -==== diff --git a/modules/persistent-storage-fibre-volume-security.adoc b/modules/persistent-storage-fibre-volume-security.adoc deleted file mode 100644 index 91283f471444..000000000000 --- a/modules/persistent-storage-fibre-volume-security.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-fibre.adoc - -[id="fibre-volume-security_{context}"] -= Fibre Channel volume security -Users request storage with a persistent volume claim. This claim only lives in -the user's namespace, and can only be referenced by a pod within that same -namespace. Any attempt to access a persistent volume across a namespace causes -the pod to fail. - -Each Fibre Channel LUN must be accessible by all nodes in the cluster. diff --git a/modules/persistent-storage-flexvolume-consuming.adoc b/modules/persistent-storage-flexvolume-consuming.adoc deleted file mode 100644 index fdac0bbdfd65..000000000000 --- a/modules/persistent-storage-flexvolume-consuming.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-flexvolume.adoc - -[id="flexvolume-driver-consuming_{context}"] -= Consuming storage using FlexVolume drivers - -Each `PersistentVolume` object in {product-title} represents one storage asset in the storage back-end, such as a volume. - -.Procedure -* Use the `PersistentVolume` object to reference the installed storage. - -.Persistent volume object definition using FlexVolume drivers example -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: pv0001 <1> -spec: - capacity: - storage: 1Gi <2> - accessModes: - - ReadWriteOnce - flexVolume: - driver: openshift.com/foo <3> - fsType: "ext4" <4> - secretRef: foo-secret <5> - readOnly: true <6> - options: <7> - fooServer: 192.168.0.1:1234 - fooVolumeName: bar ----- -<1> The name of the volume. This is how it is identified through persistent volume claims or from pods. This name can be different from the name of the volume on -back-end storage. -<2> The amount of storage allocated to this volume. -<3> The name of the driver. This field is mandatory. -<4> The file system that is present on the volume. This field is optional. -<5> The reference to a secret. Keys and values from this secret are -provided to the FlexVolume driver on invocation. This field is optional. -<6> The read-only flag. This field is optional. -<7> The additional options for the FlexVolume driver. In addition to the flags specified by the user in the `options` field, the following flags are also passed to the executable: - - "fsType":"<FS type>", - "readwrite":"<rw>", - "secret/key1":"<secret1>" - ... - "secret/keyN":"<secretN>" - -[NOTE] -==== -Secrets are passed only to mount or unmount call-outs. -==== diff --git a/modules/persistent-storage-flexvolume-driver-example.adoc b/modules/persistent-storage-flexvolume-driver-example.adoc deleted file mode 100644 index 80e4b0b8526c..000000000000 --- a/modules/persistent-storage-flexvolume-driver-example.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-flexvolume.adoc - -[id="flexvolume-driver-example_{context}"] -= FlexVolume driver example - -The first command-line argument of the FlexVolume driver is always an operation name. Other parameters are specific to each operation. Most of the operations take a JavaScript Object Notation (JSON) string as a parameter. This parameter is a complete JSON string, and not the name of a file with the JSON data. - -The FlexVolume driver contains: - -* All `flexVolume.options`. -* Some options from `flexVolume` prefixed by `kubernetes.io/`, such as `fsType` and `readwrite`. -* The content of the referenced secret, if specified, prefixed by `kubernetes.io/secret/`. - -.FlexVolume driver JSON input example - -[source,json] ----- -{ - "fooServer": "192.168.0.1:1234", <1> - "fooVolumeName": "bar", - "kubernetes.io/fsType": "ext4", <2> - "kubernetes.io/readwrite": "ro", <3> - "kubernetes.io/secret/<key name>": "<key value>", <4> - "kubernetes.io/secret/<another key name>": "<another key value>", -} ----- -<1> All options from `flexVolume.options`. -<2> The value of `flexVolume.fsType`. -<3> `ro`/`rw` based on `flexVolume.readOnly`. -<4> All keys and their values from the secret referenced by `flexVolume.secretRef`. - -{product-title} expects JSON data on standard output of the driver. When not -specified, the output describes the result of the operation. - -.FlexVolume driver default output example - -[source,json] ----- -{ - "status": "<Success/Failure/Not supported>", - "message": "<Reason for success/failure>" -} ----- - -Exit code of the driver should be `0` for success and `1` for error. - -Operations should be idempotent, which means that the mounting of an already mounted volume should result in a successful operation. diff --git a/modules/persistent-storage-flexvolume-drivers.adoc b/modules/persistent-storage-flexvolume-drivers.adoc deleted file mode 100644 index f2edc38668da..000000000000 --- a/modules/persistent-storage-flexvolume-drivers.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-flexvolume.adoc - -[id="flexvolume-drivers_{context}"] -= About FlexVolume drivers - -A FlexVolume driver is an executable file that resides in a well-defined directory on all nodes in the cluster. {product-title} calls the FlexVolume driver whenever it needs to mount or unmount a volume represented by a `PersistentVolume` object with `flexVolume` as the source. - -[IMPORTANT] -==== -Attach and detach operations are not supported in {product-title} for FlexVolume. -==== diff --git a/modules/persistent-storage-flexvolume-installing.adoc b/modules/persistent-storage-flexvolume-installing.adoc deleted file mode 100644 index 0b1baada6178..000000000000 --- a/modules/persistent-storage-flexvolume-installing.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-flexvolume.adoc - -[id="flexvolume-installing_{context}"] - -= Installing FlexVolume drivers - -FlexVolume drivers that are used to extend {product-title} are executed only on the node. To implement FlexVolumes, a list of operations to call and the installation path are all that is required. - -.Prerequisites - -* FlexVolume drivers must implement these operations: - -`init`:: -Initializes the driver. It is called during initialization of all nodes. - -** Arguments: none -** Executed on: node -** Expected output: default JSON - -`mount`:: -Mounts a volume to directory. This can include anything that is necessary to mount the volume, including finding the device and then mounting the device. - -** Arguments: `<mount-dir>` `<json>` -** Executed on: node -** Expected output: default JSON - -`unmount`:: -Unmounts a volume from a directory. This can include anything that is necessary to clean up the volume after unmounting. - -** Arguments: `<mount-dir>` -** Executed on: node -** Expected output: default JSON - -`mountdevice`:: -Mounts a volume's device to a directory where individual pods can then bind mount. - -This call-out does not pass "secrets" specified in the FlexVolume spec. If your driver requires secrets, do not implement this call-out. - -** Arguments: `<mount-dir>` `<json>` -** Executed on: node -** Expected output: default JSON - -`unmountdevice`:: -Unmounts a volume's device from a directory. - -** Arguments: `<mount-dir>` -** Executed on: node -** Expected output: default JSON - -* All other operations should return JSON with `{"status": "Not supported"}` and exit code `1`. - -.Procedure - -To install the FlexVolume driver: - -. Ensure that the executable file exists on all nodes in the cluster. - -. Place the executable file at the volume plug-in path: -`/etc/kubernetes/kubelet-plugins/volume/exec/<vendor>~<driver>/<driver>`. - -For example, to install the FlexVolume driver for the storage `foo`, place the -executable file at: -`/etc/kubernetes/kubelet-plugins/volume/exec/openshift.com~foo/foo`. diff --git a/modules/persistent-storage-hostpath-about.adoc b/modules/persistent-storage-hostpath-about.adoc deleted file mode 100644 index 69aca7bfa541..000000000000 --- a/modules/persistent-storage-hostpath-about.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-hostpath.adoc - -[id="persistent-storage-hostpath-about_{context}"] -= Overview - -{product-title} supports hostPath mounting for development and testing on a single-node cluster. - -In a production cluster, you would not use hostPath. Instead, a cluster administrator would provision a network resource, such as a GCE Persistent Disk volume, an NFS share, or an Amazon EBS volume. Network resources support the use of storage classes to set up dynamic provisioning. - -A hostPath volume must be provisioned statically. diff --git a/modules/persistent-storage-hostpath-pod.adoc b/modules/persistent-storage-hostpath-pod.adoc deleted file mode 100644 index 8dbb93ff5d30..000000000000 --- a/modules/persistent-storage-hostpath-pod.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-hostpath.adoc - -[id="persistent-storage-hostpath-pod_{context}"] -= Mounting the hostPath share in a privileged pod - -After the persistent volume claim has been created, it can be used inside by an application. The following example demonstrates mounting this share inside of a pod. - -.Prerequisites -* A persistent volume claim exists that is mapped to the underlying hostPath share. - -.Procedure - -* Create a privileged pod that mounts the existing persistent volume claim: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: pod-name <1> -spec: - containers: - ... - securityContext: - privileged: true <2> - volumeMounts: - - mountPath: /data <3> - name: hostpath-privileged - ... - securityContext: {} - volumes: - - name: hostpath-privileged - persistentVolumeClaim: - claimName: task-pvc-volume <4> ----- -<1> The name of the pod. -<2> The pod must run as privileged to access the node's storage. -<3> The path to mount the hostPath share inside the privileged pod. -<4> The name of the `PersistentVolumeClaim` object that has been previously created. diff --git a/modules/persistent-storage-hostpath-static-provisioning.adoc b/modules/persistent-storage-hostpath-static-provisioning.adoc deleted file mode 100644 index 20196b41190e..000000000000 --- a/modules/persistent-storage-hostpath-static-provisioning.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-hostpath.adoc - -[id="hostpath-static-provisioning_{context}"] -= Statically provisioning hostPath volumes - -A pod that uses a hostPath volume must be referenced by manual (static) provisioning. - -.Procedure - -. Define the persistent volume (PV). Create a file, `pv.yaml`, with the `PersistentVolume` object definition: -+ -[source,yaml] ----- - apiVersion: v1 - kind: PersistentVolume - metadata: - name: task-pv-volume <1> - labels: - type: local - spec: - storageClassName: manual <2> - capacity: - storage: 5Gi - accessModes: - - ReadWriteOnce <3> - persistentVolumeReclaimPolicy: Retain - hostPath: - path: "/mnt/data" <4> ----- -<1> The name of the volume. This name is how it is identified by persistent volume claims or pods. -<2> Used to bind persistent volume claim requests to this persistent volume. -<3> The volume can be mounted as `read-write` by a single node. -<4> The configuration file specifies that the volume is at `/mnt/data` on the cluster’s node. - -. Create the PV from the file: -+ -[source,terminal] ----- -$ oc create -f pv.yaml ----- - -. Define the persistent volume claim (PVC). Create a file, `pvc.yaml`, with the `PersistentVolumeClaim` object definition: -+ -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: task-pvc-volume -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi - storageClassName: manual ----- - -. Create the PVC from the file: -+ -[source,terminal] ----- -$ oc create -f pvc.yaml ----- diff --git a/modules/persistent-storage-local-create-cr.adoc b/modules/persistent-storage-local-create-cr.adoc deleted file mode 100644 index 87e5b83ff1ea..000000000000 --- a/modules/persistent-storage-local-create-cr.adoc +++ /dev/null @@ -1,154 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-local.adoc - -[id="local-volume-cr_{context}"] -= Provisioning the local volumes - -Local volumes cannot be created by dynamic provisioning. Instead, persistent volumes must be created by the Local Storage Operator. This provisioner looks for any file system or block volume devices at the paths specified in defined resource. - -.Prerequisites - -* The Local Storage Operator is installed. -* Local disks are attached to the {product-title} nodes. - -.Procedure - -. Create the local volume resource. This resource must define the nodes and paths to the local volumes. -+ -[NOTE] -==== -Do not use different storage class names for the same device. Doing so will create multiple persistent volumes (PVs). -==== -+ -.Example: Filesystem -[source,yaml] ----- -apiVersion: "local.storage.openshift.io/v1" -kind: "LocalVolume" -metadata: - name: "local-disks" - namespace: "openshift-local-storage" <1> -spec: - nodeSelector: <2> - nodeSelectorTerms: - - matchExpressions: - - key: kubernetes.io/hostname - operator: In - values: - - ip-10-0-140-183 - - ip-10-0-158-139 - - ip-10-0-164-33 - storageClassDevices: - - storageClassName: "local-sc" <3> - volumeMode: Filesystem <4> - fsType: xfs <5> - devicePaths: <6> - - /path/to/device <7> ----- -<1> The namespace where the Local Storage Operator is installed. -<2> Optional: A node selector containing a list of nodes where the local storage volumes are attached. This example uses the node host names, obtained from `oc get node`. If a value is not defined, then the Local Storage Operator will attempt to find matching disks on all available nodes. -<3> The name of the storage class to use when creating persistent volume objects. The Local Storage Operator automatically creates the storage class if it does not exist. Be sure to use a storage class that uniquely identifies this set of local volumes. -<4> The volume mode, either `Filesystem` or `Block`, that defines the type of local volumes. -<5> The file system that is created when the local volume is mounted for the first time. -<6> The path containing a list of local storage devices to choose from. -<7> Replace this value with your actual local disks filepath to the `LocalVolume` resource, such as `/dev/xvdg`. PVs are created for these local disks when the provisioner is deployed successfully. -+ -[NOTE] -==== -A raw block volume (`volumeMode: block`) is not formatted with a file system. You should use this mode only if any application running on the pod can use raw block devices. -==== -+ -.Example: Block -[source,yaml] ----- -apiVersion: "local.storage.openshift.io/v1" -kind: "LocalVolume" -metadata: - name: "local-disks" - namespace: "openshift-local-storage" <1> -spec: - nodeSelector: <2> - nodeSelectorTerms: - - matchExpressions: - - key: kubernetes.io/hostname - operator: In - values: - - ip-10-0-136-143 - - ip-10-0-140-255 - - ip-10-0-144-180 - storageClassDevices: - - storageClassName: "localblock-sc" <3> - volumeMode: Block <4> - devicePaths: <5> - - /path/to/device <6> ----- -<1> The namespace where the Local Storage Operator is installed. -<2> Optional: A node selector containing a list of nodes where the local storage volumes are attached. This example uses the node host names, obtained from `oc get node`. If a value is not defined, then the Local Storage Operator will attempt to find matching disks on all available nodes. -<3> The name of the storage class to use when creating persistent volume objects. -<4> The volume mode, either `Filesystem` or `Block`, that defines the type of local volumes. -<5> The path containing a list of local storage devices to choose from. -<6> Replace this value with your actual local disks filepath to the `LocalVolume` resource, such as `/dev/xvdg`. PVs are created for these local disks when the provisioner is deployed successfully. - -. Create the local volume resource in your {product-title} cluster. Specify the file you just created: -+ -[source,terminal] ----- -$ oc create -f <local-volume>.yaml ----- - -. Verify that the provisioner was created and that the corresponding daemon sets were created: -+ -[source,terminal] ----- -$ oc get all -n openshift-local-storage ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -pod/local-disks-local-provisioner-h97hj 1/1 Running 0 46m -pod/local-disks-local-provisioner-j4mnn 1/1 Running 0 46m -pod/local-disks-local-provisioner-kbdnx 1/1 Running 0 46m -pod/local-disks-local-diskmaker-ldldw 1/1 Running 0 46m -pod/local-disks-local-diskmaker-lvrv4 1/1 Running 0 46m -pod/local-disks-local-diskmaker-phxdq 1/1 Running 0 46m -pod/local-storage-operator-54564d9988-vxvhx 1/1 Running 0 47m - -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -service/local-storage-operator ClusterIP 172.30.49.90 <none> 60000/TCP 47m - -NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE -daemonset.apps/local-disks-local-provisioner 3 3 3 3 3 <none> 46m -daemonset.apps/local-disks-local-diskmaker 3 3 3 3 3 <none> 46m - -NAME READY UP-TO-DATE AVAILABLE AGE -deployment.apps/local-storage-operator 1/1 1 1 47m - -NAME DESIRED CURRENT READY AGE -replicaset.apps/local-storage-operator-54564d9988 1 1 1 47m ----- -+ -Note the desired and current number of daemon set processes. A desired count of `0` indicates that the label selectors were invalid. - -. Verify that the persistent volumes were created: -+ -[source,terminal] ----- -$ oc get pv ----- -+ -.Example output -[source,terminal] ----- -NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE -local-pv-1cec77cf 100Gi RWO Delete Available local-sc 88m -local-pv-2ef7cd2a 100Gi RWO Delete Available local-sc 82m -local-pv-3fa1c73 100Gi RWO Delete Available local-sc 48m ----- - -[IMPORTANT] -==== -Editing the `LocalVolume` object does not change the `fsType` or `volumeMode` of existing persistent volumes because doing so might result in a destructive operation. -==== diff --git a/modules/persistent-storage-local-discovery.adoc b/modules/persistent-storage-local-discovery.adoc deleted file mode 100644 index ae9b8563bc9a..000000000000 --- a/modules/persistent-storage-local-discovery.adoc +++ /dev/null @@ -1,148 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-local.adoc - -[id="local-storage-discovery_{context}"] -= Automating discovery and provisioning for local storage devices - -The Local Storage Operator automates local storage discovery and provisioning. With this feature, you can simplify installation when dynamic provisioning is not available during deployment, such as with bare metal, VMware, or AWS store instances with attached devices. - -[IMPORTANT] -==== -Automatic discovery and provisioning is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. - -For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/. -==== - -Use the following procedure to automatically discover local devices, and to automatically provision local volumes for selected devices. - -.Prerequisites -* You have cluster administrator permissions. - -* You have installed the Local Storage Operator. - -* You have attached local disks to {product-title} nodes. - -* You have access to the {product-title} web console and the `oc` command-line interface (CLI). - -.Procedure - -. To enable automatic discovery of local devices from the web console: - -.. In the _Administrator_ perspective, navigate to *Operators* -> *Installed Operators* and click on the *Local Volume Discovery* tab. - -.. Click *Create Local Volume Discovery*. - -.. Select either *All nodes* or *Select nodes*, depending on whether you want to discover available disks on all or specific nodes. -+ -[NOTE] -==== -Only worker nodes are available, regardless of whether you filter using *All nodes* or *Select nodes*. -==== -+ -.. Click *Create*. - -A local volume discovery instance named `auto-discover-devices` is displayed. - -. To display a continuous list of available devices on a node: - -.. Log in to the {product-title} web console. - -.. Navigate to *Compute* -> *Nodes*. - -.. Click the node name that you want to open. The "Node Details" page is displayed. - -.. Select the *Disks* tab to display the list of the selected devices. -+ -The device list updates continuously as local disks are added or removed. You can filter the devices by name, status, type, model, capacity, and mode. - -. To automatically provision local volumes for the discovered devices from the web console: - -.. Navigate to *Operators* -> *Installed Operators* and select *Local Storage* from the list of Operators. - -.. Select *Local Volume Set* -> *Create Local Volume Set*. - -.. Enter a volume set name and a storage class name. - -.. Choose *All nodes* or *Select nodes* to apply filters accordingly. -+ -[NOTE] -==== -Only worker nodes are available, regardless of whether you filter using *All nodes* or *Select nodes*. -==== -+ -.. Select the disk type, mode, size, and limit you want to apply to the local volume set, and click *Create*. -+ -A message displays after several minutes, indicating that the "Operator reconciled successfully." - -[start=3] -. Alternatively, to provision local volumes for the discovered devices from the CLI: - -.. Create an object YAML file to define the local volume set, such as `local-volume-set.yaml`, as shown in the following example: -+ -[source,yaml] ----- -apiVersion: local.storage.openshift.io/v1alpha1 -kind: LocalVolumeSet -metadata: - name: example-autodetect -spec: - nodeSelector: - nodeSelectorTerms: - - matchExpressions: - - key: kubernetes.io/hostname - operator: In - values: - - worker-0 - - worker-1 - storageClassName: example-storageclass <1> - volumeMode: Filesystem - fstype: ext4 - maxDeviceCount: 10 - deviceInclusionSpec: - deviceTypes: <2> - - disk - - part - deviceMechanicalProperty: - - NonRotational - minSize: 10G - maxSize: 100G - models: - - SAMSUNG - - Crucial_CT525MX3 - vendors: - - ATA - - ST2000LM ----- -+ -<1> Determines the storage class that is created for persistent volumes that are provisioned from discovered devices. The Local Storage Operator automatically creates the storage class if it does not exist. Be sure to use a storage class that uniquely identifies this set of local volumes. -+ -<2> When using the local volume set feature, the Local Storage Operator does not support the use of logical volume management (LVM) devices. - -.. Create the local volume set object: -+ -[source,terminal] ----- -$ oc apply -f local-volume-set.yaml ----- - -.. Verify that the local persistent volumes were dynamically provisioned based on the storage class: -+ -[source,terminal] ----- -$ oc -n get pv ----- -+ -.Example output -[source,terminal] ----- -NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE -local-pv-1cec77cf 100Gi RWO Delete Available example-storageclass 88m -local-pv-2ef7cd2a 100Gi RWO Delete Available example-storageclass 82m -local-pv-3fa1c73 100Gi RWO Delete Available example-storageclass 48m ----- - -[NOTE] -==== -Results are deleted after they are removed from the node. Symlinks must be manually removed. -==== diff --git a/modules/persistent-storage-local-install.adoc b/modules/persistent-storage-local-install.adoc deleted file mode 100644 index 90baddd227f0..000000000000 --- a/modules/persistent-storage-local-install.adoc +++ /dev/null @@ -1,136 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-local.adoc - -[id="local-storage-install_{context}"] -= Installing the Local Storage Operator - -The Local Storage Operator is not installed in {product-title} by default. Use the following procedure to install and configure this Operator to enable local volumes in your cluster. - -.Prerequisites - -* Access to the {product-title} web console or command-line interface (CLI). - -.Procedure - -. Create the `openshift-local-storage` project: -+ -[source,terminal] ----- -$ oc adm new-project openshift-local-storage ----- - -. Optional: Allow local storage creation on infrastructure nodes. -+ -You might want to use the Local Storage Operator to create volumes on infrastructure nodes in support of components such as logging and monitoring. -+ -You must adjust the default node selector so that the Local Storage Operator includes the infrastructure nodes, and not just worker nodes. -+ -To block the Local Storage Operator from inheriting the cluster-wide default selector, enter the following command: -+ -[source,terminal] ----- -$ oc annotate project openshift-local-storage openshift.io/node-selector='' ----- - -.From the UI - -To install the Local Storage Operator from the web console, follow these steps: - -. Log in to the {product-title} web console. - -. Navigate to *Operators* -> *OperatorHub*. - -. Type *Local Storage* into the filter box to locate the Local Storage Operator. - -. Click *Install*. - -. On the *Install Operator* page, select *A specific namespace on the cluster*. Select *openshift-local-storage* from the drop-down menu. - -. Adjust the values for *Update Channel* and *Approval Strategy* to the values that you want. - -. Click *Install*. - -Once finished, the Local Storage Operator will be listed in the *Installed Operators* section of the web console. - -.From the CLI -. Install the Local Storage Operator from the CLI. - -.. Run the following command to get the {product-title} major and minor version. It is required for the `channel` value in the next -step. -+ -[source,terminal] ----- -$ OC_VERSION=$(oc version -o yaml | grep openshiftVersion | \ - grep -o '[0-9]*[.][0-9]*' | head -1) ----- - -.. Create an object YAML file to define an Operator group and subscription for the Local Storage Operator, -such as `openshift-local-storage.yaml`: -+ -.Example openshift-local-storage.yaml -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha2 -kind: OperatorGroup -metadata: - name: local-operator-group - namespace: openshift-local-storage -spec: - targetNamespaces: - - openshift-local-storage ---- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: local-storage-operator - namespace: openshift-local-storage -spec: - channel: "${OC_VERSION}" - installPlanApproval: Automatic <1> - name: local-storage-operator - source: redhat-operators - sourceNamespace: openshift-marketplace ----- -<1> The user approval policy for an install plan. - -. Create the Local Storage Operator object by entering the following command: -+ -[source,terminal] ----- -$ oc apply -f openshift-local-storage.yaml ----- -+ -At this point, the Operator Lifecycle Manager (OLM) is now aware of the Local Storage Operator. A ClusterServiceVersion (CSV) for the Operator should appear in the target namespace, and APIs provided by the Operator should be available for creation. -+ -. Verify local storage installation by checking that all pods and the Local Storage Operator have been created: - -.. Check that all the required pods have been created: -+ -[source,terminal] ----- -$ oc -n openshift-local-storage get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -local-storage-operator-746bf599c9-vlt5t 1/1 Running 0 19m ----- - -.. Check the ClusterServiceVersion (CSV) YAML manifest to see that the Local Storage Operator is available in the `openshift-local-storage` project: -+ -[source,terminal] ----- -$ oc get csvs -n openshift-local-storage ----- -+ -.Example output -[source,terminal] ----- -NAME DISPLAY VERSION REPLACES PHASE -local-storage-operator.4.2.26-202003230335 Local Storage 4.2.26-202003230335 Succeeded ----- - -After all checks have passed, the Local Storage Operator is installed successfully. diff --git a/modules/persistent-storage-local-pod.adoc b/modules/persistent-storage-local-pod.adoc deleted file mode 100644 index 97e8f0266e47..000000000000 --- a/modules/persistent-storage-local-pod.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-local.adoc - -[id="local-pod_{context}"] -= Attach the local claim - -After a local volume has been mapped to a persistent volume claim -it can be specified inside of a resource. - -.Prerequisites - -* A persistent volume claim exists in the same namespace. - -.Procedure - -. Include the defined claim in the resource spec. The following example -declares the persistent volume claim inside a pod: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -spec: - ... - containers: - volumeMounts: - - name: local-disks <1> - mountPath: /data <2> - volumes: - - name: localpvc - persistentVolumeClaim: - claimName: local-pvc-name <3> ----- -<1> The name of the volume to mount. -<2> The path inside the pod where the volume is mounted. -<3> The name of the existing persistent volume claim to use. - -. Create the resource in the {product-title} cluster, specifying the file -you just created: -+ -[source,terminal] ----- -$ oc create -f <local-pod>.yaml ----- diff --git a/modules/persistent-storage-local-pvc.adoc b/modules/persistent-storage-local-pvc.adoc deleted file mode 100644 index 16a645b2e3e7..000000000000 --- a/modules/persistent-storage-local-pvc.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-local.adoc - -[id="create-local-pvc_{context}"] -= Creating the local volume persistent volume claim - -Local volumes must be statically created as a persistent volume claim (PVC) -to be accessed by the pod. - -.Prerequisites - -* Persistent volumes have been created using the local volume provisioner. - -.Procedure - -. Create the PVC using the corresponding storage class: -+ -[source,yaml] ----- -kind: PersistentVolumeClaim -apiVersion: v1 -metadata: - name: local-pvc-name <1> -spec: - accessModes: - - ReadWriteOnce - volumeMode: Filesystem <2> - resources: - requests: - storage: 100Gi <3> - storageClassName: local-sc <4> ----- -<1> Name of the PVC. -<2> The type of the PVC. Defaults to `Filesystem`. -<3> The amount of storage available to the PVC. -<4> Name of the storage class required by the claim. - -. Create the PVC in the {product-title} cluster, specifying the file -you just created: -+ -[source,terminal] ----- -$ oc create -f <local-pvc>.yaml ----- diff --git a/modules/persistent-storage-local-removing-devices.adoc b/modules/persistent-storage-local-removing-devices.adoc deleted file mode 100644 index 87a3cf0d6f55..000000000000 --- a/modules/persistent-storage-local-removing-devices.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-local.adoc - -[id="local-removing-device_{context}"] -= Removing a local volume or local volume set - -Occasionally, local volumes and local volume sets must be deleted. While removing the entry in the resource and deleting the persistent volume is typically enough, if you want to reuse the same device path or have it managed by a different storage class, then additional steps are needed. - -[NOTE] -==== -The following procedure outlines an example for removing a local volume. The same procedure can also be used to remove symlinks for a local volume set custom resource. -==== - -.Prerequisites - -* The persistent volume must be in a `Released` or `Available` state. -+ -[WARNING] -==== -Deleting a persistent volume that is still in use can result in data loss or corruption. -==== - -.Procedure - -. Edit the previously created local volume to remove any unwanted disks. - -.. Edit the cluster resource: -+ -[source,terminal] ----- -$ oc edit localvolume <name> -n openshift-local-storage ----- - -.. Navigate to the lines under `devicePaths`, and delete any representing unwanted disks. - -. Delete any persistent volumes created. -+ -[source,terminal] ----- -$ oc delete pv <pv-name> ----- - -. Delete any symlinks on the node. -+ -[WARNING] -==== -The following step involves accessing a node as the root user. Modifying the state of the node beyond the steps in this procedure could result in cluster instability. -==== -+ -.. Create a debug pod on the node: -+ -[source,terminal] ----- -$ oc debug node/<node-name> ----- - -.. Change your root directory to the host: -+ -[source,terminal] ----- -$ chroot /host ----- - -.. Navigate to the directory containing the local volume symlinks. -+ -[source,terminal] ----- -$ cd /mnt/openshift-local-storage/<sc-name> <1> ----- -<1> The name of the storage class used to create the local volumes. - -.. Delete the symlink belonging to the removed device. -+ -[source,terminal] ----- -$ rm <symlink> ----- diff --git a/modules/persistent-storage-local-tolerations.adoc b/modules/persistent-storage-local-tolerations.adoc deleted file mode 100644 index 6f05a4eaec59..000000000000 --- a/modules/persistent-storage-local-tolerations.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-local.adoc - -[id="local-tolerations_{context}"] -= Using tolerations with Local Storage Operator pods - -Taints can be applied to nodes to prevent them from running general workloads. To allow the Local Storage Operator to use tainted nodes, you must add tolerations to the `Pod` or `DaemonSet` definition. This allows the created resources to run on these tainted nodes. - -You apply tolerations to the Local Storage Operator pod through the `LocalVolume` resource -and apply taints to a node through the node specification. A taint on a node instructs the node to repel all pods that do not tolerate the taint. Using a specific taint that is not on other pods ensures that the Local Storage Operator pod can also run on that node. - -[IMPORTANT] -==== -Taints and tolerations consist of a key, value, and effect. As an argument, it is expressed as `key=value:effect`. An operator allows you to leave one of these parameters empty. -==== - -.Prerequisites - -* The Local Storage Operator is installed. - -* Local disks are attached to {product-title} nodes with a taint. - -* Tainted nodes are expected to provision local storage. - -.Procedure -To configure local volumes for scheduling on tainted nodes: - -. Modify the YAML file that defines the `Pod` and add the `LocalVolume` spec, as shown in the following example: -+ -[source,yaml] ----- - apiVersion: "local.storage.openshift.io/v1" - kind: "LocalVolume" - metadata: - name: "local-disks" - namespace: "openshift-local-storage" - spec: - tolerations: - - key: localstorage <1> - operator: Equal <2> - value: "localstorage" <3> - storageClassDevices: - - storageClassName: "localblock-sc" - volumeMode: Block <4> - devicePaths: <5> - - /dev/xvdg - ----- -<1> Specify the key that you added to the node. -<2> Specify the `Equal` operator to require the `key`/`value` parameters to match. If operator is `Exists`, the system checks that the key exists and ignores the value. If operator is `Equal`, then the key and value must match. -<3> Specify the value `local` of the tainted node. -<4> The volume mode, either `Filesystem` or `Block`, defining the type of the local volumes. -<5> The path containing a list of local storage devices to choose from. - -The defined tolerations will be passed to the resulting daemon sets, allowing the diskmaker and provisioner pods to be created for nodes that contain the specified taints. diff --git a/modules/persistent-storage-local-uninstall-operator.adoc b/modules/persistent-storage-local-uninstall-operator.adoc deleted file mode 100644 index 154ecf16adf2..000000000000 --- a/modules/persistent-storage-local-uninstall-operator.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-local.adoc - -[id="local-storage-uninstall_{context}"] -= Uninstalling the Local Storage Operator - -To uninstall the Local Storage Operator, you must remove the Operator and all created resources in the `openshift-local-storage` project. - -[WARNING] -==== -Uninstalling the Local Storage Operator while local storage PVs are still in use is not recommended. While the PVs will remain after the Operator's removal, -there might be indeterminate behavior if the Operator is uninstalled and reinstalled without removing the PVs and local storage resources. -==== - -.Prerequisites - -* Access to the {product-title} web console. - -.Procedure - -. Delete any local volume resources in the project: -+ -[source,terminal] ----- -$ oc delete localvolume --all --all-namespaces ----- - -. Uninstall the Local Storage Operator from the web console. - -.. Log in to the {product-title} web console. - -.. Navigate to *Operators* -> *Installed Operators*. - -.. Type *Local Storage* into the filter box to locate the Local Storage Operator. - -.. Click the Options menu {kebab} at the end of the Local Storage Operator. - -.. Click *Uninstall Operator*. - -.. Click *Remove* in the window that appears. - -. The PVs created by the Local Storage Operator will remain in the cluster until deleted. Once these volumes are no longer in use, delete them by running the following command: -+ -[source,terminal] ----- -$ oc delete pv <pv-name> ----- - -. Delete the `openshift-local-storage` project: -+ -[source,terminal] ----- -$ oc delete project openshift-local-storage ----- diff --git a/modules/persistent-storage-manila-install.adoc b/modules/persistent-storage-manila-install.adoc deleted file mode 100644 index cf66efd40863..000000000000 --- a/modules/persistent-storage-manila-install.adoc +++ /dev/null @@ -1,150 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-manila.adoc - -[id="persistent-storage-manila-install_{context}"] -= Installing the external provisioner - -To use {rh-openstack-first} Manila persistent storage you must install -and configure an external provisioner in the {product-title} -cluster. - -The external provisioner is distributed as a container image -and can be run in the {product-title} cluster as usual. - -.Procedure - -. Create a service account: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: manila-provisioner-runner ----- - -. Create a ClusterRole: -+ -[source,yaml] ----- -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: manila-provisioner-role -rules: - - apiGroups: [""] - resources: ["persistentvolumes", "endpoints"] - verbs: ["get", "list", "watch", "create", "delete", "update"] - - apiGroups: [""] - resources: ["persistentvolumeclaims"] - verbs: ["get", "list", "watch", "update"] - - apiGroups: ["storage.k8s.io"] - resources: ["storageclasses"] - verbs: ["get", "list", "watch"] - - apiGroups: [""] - resources: ["events"] - verbs: ["list", "watch", "create", "update", "patch"] - - apiGroups: ["v1"] - resources: ["secrets"] - verbs: ["get", "list"] ----- - -. Bind the rules via ClusterRoleBinding: -+ -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: manila-provisioner -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: manila-provisioner-role -subjects: -- kind: ServiceAccount - name: manila-provisioner-runner - namespace: default ----- - -. Create a new secret: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: manila-secret <1> - namespace: default <2> -data: - os-authURL: <base64 encoded {rh-openstack} Keystone URL> - os-userName: <base64 encoded Manila username> - os-password: <base64 encoded password> - os-projectName: <base64 encoded {rh-openstack} project (tenant) name> - os-domainName: <base64 encoded {rh-openstack} Manila service domain> - os-region: <base64 encoded {rh-openstack} region> ----- -<1> The secret name will be referenced by the Manila volume's -StorageClass. -<2> The secret namespace will be referenced by the Manila -volume's StorageClass. - -. Create a new StorageClass: -+ -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: "manila-share" -provisioner: "externalstorage.k8s.io/manila" -parameters: - type: "default" <1> - zones: "nova" <2> - protocol: "NFS" <3> - backend: "nfs" <4> - osSecretName: "manila-secret" <5> - osSecretNamespace: "default" <6> - nfs-share-client: "0.0.0.0" <7> ----- -<1> The link:https://docs.openstack.org/manila/latest/admin/shared-file-systems-share-types.html[Manila share type] -the provisioner will create for the volume. This field is optional, -and defaults to `default`. -<2> Set of Manila availability zones that the volume might be created -in. This field is optional, and defaults to `nova`. -<3> Protocol used when provisioning a share. Valid options are -`NFS` and `CEPHFS`. This field is required. -<4> Backend share used for granting access and creating the -`PersistentVolumeSource`. Valid options are `nfs` and `cephfs`. -This field is required. -<5> Name of the secret object containing {rh-openstack} credentials. -This field is required. -<6> Namespace of the {rh-openstack} credentials secret object. This field -is optional, and defaults to `default`. -<7> Default NFS client for the share exported. This field is optional, -and is only used for the `NFS` protocol. Defaults to `0.0.0.0`. - -. Start the provisioner itself. The following example uses a Deployment: -+ -[source,yaml] ----- -kind: Deployment -apiVersion: apps/v1 -metadata: - name: manila-provisioner -spec: - replicas: 1 - strategy: - type: Recreate - template: - metadata: - labels: - app: manila-provisioner - spec: - serviceAccountName: manila-provisioner-runner - containers: - - image: "registry.redhat.io/openshift/manila-provisioner:latest" - imagePullPolicy: "IfNotPresent" - name: manila-provisioner ----- diff --git a/modules/persistent-storage-manila-usage.adoc b/modules/persistent-storage-manila-usage.adoc deleted file mode 100644 index 2eda8b122e89..000000000000 --- a/modules/persistent-storage-manila-usage.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-manila.adoc - -[id="persistent-storage-manila-usage_{context}"] -= Provisioning an {rh-openstack} Manila persistent volume - -{rh-openstack-first} Manila shares are dynamically provisioned as needed. When the -PersistentVolumeClaim is deleted the provisioner will automatically -delete and unexport the {rh-openstack} Manila share. - -.Prerequisites - -* The {rh-openstack} Manila external provisioner must be installed. - -.Procedure - -* Create a PersistentVolumeClaim using the corresponding -StorageClass. -+ -[source,yaml] ----- -kind: PersistentVolumeClaim -apiVersion: v1 -metadata: - name: manila-nfs-pvc -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 2G - storageClassName: manila-share ----- diff --git a/modules/persistent-storage-rhv.adoc b/modules/persistent-storage-rhv.adoc deleted file mode 100644 index fcbfe04fd68e..000000000000 --- a/modules/persistent-storage-rhv.adoc +++ /dev/null @@ -1,69 +0,0 @@ -[id="persistent-storage-rhv_{context}"] -= Creating a persistent volume on RHV - -When you create a `PersistentVolumeClaim` (PVC) object, {product-title} provisions a new persistent volume (PV) and creates a `PersistentVolume` object. - -.Prerequisites -* You are logged in to a running {product-title} cluster. -* You provided the correct {rh-virtualization} credentials in `ovirt-credentials` secret. -* You have installed the oVirt CSI driver. -* You have defined at least one storage class. - -.Procedure - -* If you are using the we console to to dynamically create a persistent volume on {rh-virtualization} : -+ -. In the {product-title} console, click *Storage* -> *Persistent Volume Claims*. -. In the persistent volume claims overview, click *Create Persistent Volume Claim*. -. Define the required options on the resulting page. -. Select the appropriate `StorageClass` object, which is `ovirt-csi-sc` by default. -. Enter a unique name for the storage claim. -. Select the access mode. Currently, RWO (ReadWriteOnce) is the only supported access mode. -. Define the size of the storage claim. -. Select the Volume Mode: -+ -`Filesystem`: Mounted into pods as a directory. This mode is the default. -+ -`Block`: Block device, without any file system on it -+ -. Click *Create* to create the `PersistentVolumeClaim` object and generate a `PersistentVolume` object. - -* If you are using the command-line interface (CLI) to dynamically create a {rh-virtualization} CSI volume: -+ -. Create and save a file with the `PersistentVolumeClaim` object described by the following sample YAML: -+ -.pvc-ovirt.yaml -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: pvc-ovirt -spec: - storageClassName: ovirt-csi-sc <1> - accessModes: - - ReadWriteOnce - resources: - requests: - storage: <volume size> <2> - volumeMode: <volume mode> <3> ----- -<1> Name of the required storage class. -<2> Volume size in GiB. -<3> Supported options: - ** `Filesystem`: Mounted into pods as a directory. This mode is the default. - ** `Block`: Block device, without any file system on it. -+ -. Create the object you saved in the previous step by running the following command: -+ ----- -$ oc create -f pvc-ovirt.yaml ----- -+ -. To verify that the volume was created and is ready, run the following command: -+ ----- -$ oc get pvc pvc-ovirt ----- -+ -The `pvc-ovirt` shows that it is Bound. diff --git a/modules/persistent-storage-vsphere-backup.adoc b/modules/persistent-storage-vsphere-backup.adoc deleted file mode 100644 index b880ee550eb3..000000000000 --- a/modules/persistent-storage-vsphere-backup.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-vsphere.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere.adoc - -[id="vsphere-pv-backup_{context}"] -= Backing up VMware vSphere volumes - -{product-title} provisions new volumes as independent persistent disks to freely attach and detach the volume on any node in the cluster. As a consequence, it is not possible to back up volumes that use snapshots, or to restore volumes from snapshots. See link:https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.vm_admin.doc/GUID-53F65726-A23B-4CF0-A7D5-48E584B88613.html[Snapshot Limitations] for more information. - -.Procedure - -To create a backup of persistent volumes: - -. Stop the application that is using the persistent volume. -. Clone the persistent volume. -. Restart the application. -. Create a backup of the cloned volume. -. Delete the cloned volume. diff --git a/modules/persistent-storage-vsphere-dynamic-provisioning-cli.adoc b/modules/persistent-storage-vsphere-dynamic-provisioning-cli.adoc deleted file mode 100644 index 45b4f7c1b859..000000000000 --- a/modules/persistent-storage-vsphere-dynamic-provisioning-cli.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-vsphere.adoc - -[id="vsphere-dynamic-provisioning-cli_{context}"] -= Dynamically provisioning VMware vSphere volumes using the CLI - -{product-title} installs a default StorageClass, named `thin`, that uses the `thin` disk format for provisioning volumes. - -.Prerequisites - -* Storage must exist in the underlying infrastructure before it can be mounted as a volume in {product-title}. - -.Procedure (CLI) - -. You can define a VMware vSphere PersistentVolumeClaim by creating a file, `pvc.yaml`, with the following contents: -+ -[source,yaml] ----- -kind: PersistentVolumeClaim -apiVersion: v1 -metadata: - name: pvc <1> -spec: - accessModes: - - ReadWriteOnce <2> - resources: - requests: - storage: 1Gi <3> ----- -<1> A unique name that represents the persistent volume claim. -<2> The access mode of the persistent volume claim. With `ReadWriteOnce`, the volume can be mounted with read and write permissions by a single node. -<3> The size of the persistent volume claim. - -. Create the `PersistentVolumeClaim` object from the file: -+ -[source,terminal] ----- -$ oc create -f pvc.yaml ----- diff --git a/modules/persistent-storage-vsphere-dynamic-provisioning.adoc b/modules/persistent-storage-vsphere-dynamic-provisioning.adoc deleted file mode 100644 index 7b4e70c9ac46..000000000000 --- a/modules/persistent-storage-vsphere-dynamic-provisioning.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-vsphere.adoc - -[id="vsphere-dynamic-provisioning_{context}"] -= Dynamically provisioning VMware vSphere volumes using the UI - -{product-title} installs a default storage class, named `thin`, that uses the `thin` disk format for provisioning volumes. - -.Prerequisites - -* Storage must exist in the underlying infrastructure before it can be mounted as a volume in {product-title}. - -.Procedure - -. In the {product-title} console, click *Storage* → *Persistent Volume Claims*. - -. In the persistent volume claims overview, click *Create Persistent Volume Claim*. - -. Define the required options on the resulting page. - -.. Select the `thin` storage class. - -.. Enter a unique name for the storage claim. - -.. Select the access mode to determine the read and write access for the created storage claim. - -.. Define the size of the storage claim. - -. Click *Create* to create the persistent volume claim and generate a persistent volume. diff --git a/modules/persistent-storage-vsphere-formatting.adoc b/modules/persistent-storage-vsphere-formatting.adoc deleted file mode 100644 index c8a302e609d6..000000000000 --- a/modules/persistent-storage-vsphere-formatting.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies -// -// * storage/persistent_storage/persistent-storage-vsphere.adoc - -[id="vsphere-formatting-volumes_{context}"] -= Formatting VMware vSphere volumes - -Before {product-title} mounts the volume and passes it to a container, it checks that the volume contains a file system that is specified by the `fsType` parameter value in the `PersistentVolume` (PV) definition. If the device is not formatted with the file system, all data from the device is erased, and the device is automatically formatted with the specified file system. - -Because {product-title} formats them before the first use, you can use unformatted vSphere volumes as PVs. diff --git a/modules/persistent-storage-vsphere-static-provisioning.adoc b/modules/persistent-storage-vsphere-static-provisioning.adoc deleted file mode 100644 index d600aff2015a..000000000000 --- a/modules/persistent-storage-vsphere-static-provisioning.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-vsphere.adoc - -[id="vsphere-static-provisioning_{context}"] -= Statically provisioning VMware vSphere volumes - -To statically provision VMware vSphere volumes you must create the virtual machine disks for reference by the persistent volume framework. - -.Prerequisites - -* Storage must exist in the underlying infrastructure before it can be mounted as a volume in {product-title}. - -.Procedure - -. Create the virtual machine disks. Virtual machine disks (VMDKs) must be created manually before statically provisioning VMware vSphere volumes. Use either of the following methods: - - * Create using `vmkfstools`. Access ESX through Secure Shell (SSH) and then use following command to create a VMDK volume: -+ -[source,terminal] ----- -$ vmkfstools -c <size> /vmfs/volumes/<datastore-name>/volumes/<disk-name>.vmdk ----- - - * Create using `vmware-diskmanager`: -+ -[source,terminal] ----- -$ shell vmware-vdiskmanager -c -t 0 -s <size> -a lsilogic <disk-name>.vmdk ----- - -. Create a persistent volume that references the VMDKs. Create a file, `pv1.yaml`, with the `PersistentVolume` object definition: -+ -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: pv1 <1> -spec: - capacity: - storage: 1Gi <2> - accessModes: - - ReadWriteOnce - persistentVolumeReclaimPolicy: Retain - vsphereVolume: <3> - volumePath: "[datastore1] volumes/myDisk" <4> - fsType: ext4 <5> ----- -<1> The name of the volume. This name is how it is identified by persistent volume claims or pods. -<2> The amount of storage allocated to this volume. -<3> The volume type used, with `vsphereVolume` for vSphere volumes. The label is used to mount a vSphere VMDK volume into pods. The contents of a volume are preserved when it is unmounted. The volume type supports VMFS and VSAN datastore. -<4> The existing VMDK volume to use. If you used `vmkfstools`, you must enclose the datastore name in square brackets, `[]`, in the volume definition, as shown previously. -<5> The file system type to mount. For example, ext4, xfs, or other file systems. -+ -[IMPORTANT] -==== -Changing the value of the fsType parameter after the volume is formatted and provisioned can result in data loss and pod failure. -==== - -. Create the `PersistentVolume` object from the file: -+ -[source,terminal] ----- -$ oc create -f pv1.yaml ----- - -. Create a persistent volume claim that maps to the persistent volume you created in the previous step. Create a file, `pvc1.yaml`, with the `PersistentVolumeClaim` object definition: -+ -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: pvc1 <1> -spec: - accessModes: - - ReadWriteOnce <2> - resources: - requests: - storage: "1Gi" <3> - volumeName: pv1 <4> ----- -<1> A unique name that represents the persistent volume claim. -<2> The access mode of the persistent volume claim. With ReadWriteOnce, the volume can be mounted with read and write permissions by a single node. -<3> The size of the persistent volume claim. -<4> The name of the existing persistent volume. - -. Create the `PersistentVolumeClaim` object from the file: -+ -[source,terminal] ----- -$ oc create -f pvc1.yaml ----- diff --git a/modules/pipelines-document-attributes.adoc b/modules/pipelines-document-attributes.adoc deleted file mode 100644 index 0f2c80b7fdc9..000000000000 --- a/modules/pipelines-document-attributes.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Standard document attributes to be used in the documentation -// -// The following are shared by all documents: -:toc: -:toclevels: 4 -:experimental: -// -// Product content attributes, that is, substitution variables in the files. -// -:pipelines-title: Red Hat OpenShift Pipelines -:pipelines-shortname: Pipelines -:pipelines-ver: pipelines-1.3 diff --git a/modules/pod-interactions-with-topology-manager.adoc b/modules/pod-interactions-with-topology-manager.adoc deleted file mode 100644 index bebe1be59d0a..000000000000 --- a/modules/pod-interactions-with-topology-manager.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * scaling_and_performance/using-topology-manager.adoc - -[id="pod-interactions-with-topology-manager_{context}"] -= Pod interactions with Topology Manager policies - -The example `Pod` specs below help illustrate pod interactions with Topology Manager. - -The following pod runs in the `BestEffort` QoS class because no resource requests or -limits are specified. - -[source,yaml] ----- -spec: - containers: - - name: nginx - image: nginx ----- - -The next pod runs in the `Burstable` QoS class because requests are less than limits. - -[source,yaml] ----- -spec: - containers: - - name: nginx - image: nginx - resources: - limits: - memory: "200Mi" - requests: - memory: "100Mi" ----- - -If the selected policy is anything other than `none`, Topology Manager would -not consider either of these `Pod` specifications. - -The last example pod below runs in the Guaranteed QoS class because requests are equal to limits. - -[source,yaml] ----- -spec: - containers: - - name: nginx - image: nginx - resources: - limits: - memory: "200Mi" - cpu: "2" - example.com/device: "1" - requests: - memory: "200Mi" - cpu: "2" - example.com/device: "1" ----- - -Topology Manager would consider this pod. The Topology Manager consults the -CPU Manager static policy, which returns the topology of available CPUs. Topology -Manager also consults Device Manager to discover the topology of available devices -for example.com/device. - -Topology Manager will use this information to store the best Topology for this -container. In the case of this pod, CPU Manager and Device Manager will use this stored -information at the resource allocation stage. diff --git a/modules/policy-and-violation-management.adoc b/modules/policy-and-violation-management.adoc new file mode 100644 index 000000000000..97e689ae16fc --- /dev/null +++ b/modules/policy-and-violation-management.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="policy-and-violation-management_{context}"] += Policy and violation management + +[role="_abstract"] + +_Policy management_ encompasses the set of activities that security teams undertake to establish the appropriate guardrails. All of these activities happen *before* the policy is evaluated. _Violation management_ is the set of activities that security and developer teams take to assist in addressing security incidents to remediate policy violations. +All of these activities happen after a policy has been violated. + + diff --git a/modules/policy-as-code-about.adoc b/modules/policy-as-code-about.adoc new file mode 100644 index 000000000000..7068df74665d --- /dev/null +++ b/modules/policy-as-code-about.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="policy-as-code-about_{context}"] += Managing polices as code + +[role="_abstract"] + +You can create and manage policies as code by saving policies as Kubernetes custom resources (CRs) and applying them to clusters by using a Kubernetes-native continuous delivery (CD) tool such as Argo CD. + +Policy as code is useful for Kubernetes security architects who want to author policies in YAML or JSON instead of using the {product-title-short} portal. GitOps administrators who already manage Kubernetes configurations by using a GitOps workflow can also find it useful. + +{product-title-short} provides the ability to use default policies or create custom policies for your system. With the policy as code feature, you can create custom policies locally by downloading them and modifying them, or by creating them from empty files. To author policies locally, you create CRs that represent the desired state of the policies. You then use a continuous delivery tool such as Argo CD to track, manage, and apply policies to your clusters that are running {product-title-short}. After you create or update CRs and use the CI/CD tool to apply them, the policies stored in the {product-title-short} database are created or updated. + +With this feature, {product-title-short} installs a new Kubernetes controller in the namespace where Central is installed, typically the `stackrox` namespace. With an Argo CD workflow, you configure Argo CD to apply policy as code resources to the same namespace in which {product-title-short} is installed. After you configure this connection, the controller in {product-title-short} receives information from the Kubernetes API about new, updated, or deleted policies that are managed as individual Kubernetes CR files. {product-title-short} reconciles the policy CR to the policy stored in the {product-title-short} database. + +// future: architecture diagram + +With a GitOps workflow that does not use Argo CD, you configure your GitOps repository to connect to Central in {product-title-short} through the {product-title-short} API. A CR is not used. + + diff --git a/modules/policy-as-code-create-cr.adoc b/modules/policy-as-code-create-cr.adoc new file mode 100644 index 000000000000..defacdf7d3d6 --- /dev/null +++ b/modules/policy-as-code-create-cr.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="policy-as-code-create-cr_{context}"] += Creating policies in code by constructing a CR + +[role="_abstract"] +You can create new policies in code by constructing a CR for the policy. + +. Use an editor to construct a CR for the policy with the following attributes: ++ +[source,yaml] +---- +kind: SecurityPolicy +apiVersion: config.stackrox.io/v1alpha1 +metadata: + name: short-name +spec: + policyName: A longer form name +# ... +---- ++ +[TIP] +==== +Use online documentation, for example, by entering the `kubectl explain securitypolicy.spec` command, to understand the fields available for defining a policy specification. +==== +. Apply the saved CR by doing one of the following: + +* Use the `oc apply` or `kubectl apply` command to apply the CR directly to the Kubernetes namespace where Central is installed. +* Use Argo CD or your GitOps tool to push the CR to the Kubernetes namespace where Central is installed. + + diff --git a/modules/policy-as-code-create-portal.adoc b/modules/policy-as-code-create-portal.adoc new file mode 100644 index 000000000000..87acafe99d81 --- /dev/null +++ b/modules/policy-as-code-create-portal.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="policy-as-code-create-portal_{context}"] += Creating policies in code by using the {product-title-short} portal + +[role="_abstract"] +You can create new policies in code by using the {product-title-short} portal to save existing policies as YAML files. + +.Prerequisites +* You must have {product-title-short} release 4.6 or later installed. +* If you installed {product-title-short} by using the manifest installation method, also called the `roxctl` method, you must manually apply the `config.stackrox.io` CRD that is located in the .zip file at `helm/chart/crds/config.stackrox.io_securitypolicies.yaml` by using the following command: ++ +[source,terminal] +---- +$ kubectl create -f helm/chart/crds/config.stackrox.io_securitypolicies.yaml +---- + +.Procedure + +To create a new policy in code by using the {product-title-short} portal to create the CR: + +. In the *Policy Management* page, create a new policy or clone a default policy. ++ +[NOTE] +==== +You must clone a default policy before you can save it as a CR. +==== +. In the row listing the policy, click the overflow menu, {kebab}, and then select *Save as Custom Resource*. To save multiple policies at one time, you can select them and click *Bulk actions* -> *Save as Custom Resources*. +. After editing your policy, you can apply the saved CR by doing one of the following: + +* Use the `oc apply` or `kubectl apply` command to apply the CR directly to the Kubernetes namespace where Central is installed. +* Use Argo CD or your GitOps tool to push the CR to the Kubernetes namespace where Central is installed. + diff --git a/modules/policy-as-code-disable.adoc b/modules/policy-as-code-disable.adoc new file mode 100644 index 000000000000..2da6e4ef1d36 --- /dev/null +++ b/modules/policy-as-code-disable.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="policy-as-code-disable_{context}"] += Disabling the policy as code feature + +[role="_abstract"] +The policy as code feature is automatically enabled when you install {product-title-short}, but you can disable it. + +.Procedure + +To disable the policy as code feature, complete one of the following tasks, depending on the method you used to install {product-title-short}: + +* If you installed {product-title-short} by using the Operator, set the `spec.configAsCode.configAsCodeComponent` field to `Disabled`. +* If you installed {product-title-short} by using Helm charts, set the `configAsCode.enabled` field in the `values.yaml` file to `false`. +* If you installed {product-title-short} by using the manifest installation method, also known as the `roxctl` method, delete the `config-controller` deployment by running the following command: ++ +[source,terminal] +---- +$ kubectl -n stackrox delete deployment config-controller <1> +---- +<1> For {ocp}, use `oc` instead of `kubectl`. diff --git a/modules/policy-as-code-drift.adoc b/modules/policy-as-code-drift.adoc new file mode 100644 index 000000000000..f52deee86a3d --- /dev/null +++ b/modules/policy-as-code-drift.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="policy-as-code-drift_{context}"] += About policy drift + +[role="_abstract"] +Because policies can be edited, deleted, and created in the {product-title-short} portal and also externally, sometimes _policy drift_ can occur. Drift occurs when the version of a policy in Central in {product-title-short} does not match the version of the policy in Kubernetes. + +Drift can occur when a change is applied to an externally-managed policy by using the {product-title-short} portal or the API instead of by modifying its Kubernetes custom resource. {product-title-short} does not prevent drift, but it is not recommended. Drift is automatically resolved within ten hours after it was introduced. + + diff --git a/modules/policy-as-code-workflow-example.adoc b/modules/policy-as-code-workflow-example.adoc new file mode 100644 index 000000000000..7916abddef5d --- /dev/null +++ b/modules/policy-as-code-workflow-example.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="policy-as-code-workflow-example_{context}"] += Policy as code workflow example + +//This module is a placeholder and content will not be in 4.6. + +[role="_abstract"] +This workflow example for policy as code uses the {product-title-short} Operator installation and Argo CD to manage policies. + +The following example provides a high-level workflow for policy as code. + +. Install {product-title-short} using the {product-title-short} Operator. Beginning with {product-title-short} version 4.6, the configuration controller needed for the feature is automatically installed. + + +**STLL WORKING ON THIS EXAMPLE** + +. Apply the saved CR by doing one of the following: + +* Use the `oc apply` or `kubectl apply` command to apply the CR directly to the Kubernetes namespace where Central is installed. +* Use Argo CD or your GitOps tool to push the CR to the Kubernetes namespace where Central is installed. + + diff --git a/modules/policy-criteria.adoc b/modules/policy-criteria.adoc new file mode 100644 index 000000000000..a7b45270cb3d --- /dev/null +++ b/modules/policy-criteria.adoc @@ -0,0 +1,942 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="policy-criteria_{context}"] += Policy criteria + +[role="_abstract"] +You can set up rules in {product-title-short} and configure the data on which you want to trigger a policy. This data is also referred to as _policy criteria_ or _policy fields_. + +You can configure the policy based on the attributes listed in the following table. + +In this table: + +* The *Regular expressions*, *AND, OR*, and *NOT* columns indicate whether you can use regular expressions and other logical operators along with the specific attribute. +** `!` for *Regex* (Regular expressions) indicates that you can only use regular expressions for the listed fields. +** `!` for *AND*, or *OR* indicates that you can only use the mentioned logical operator for the attribute. +** ✕ in the *Regex* / *NOT* / *AND, OR* column indicates that the attribute does not support any of those (regex, negation, logical operators). +* The *{product-title-short} version* column indicates the version of {product-title} that you must have to use the attribute. +* You cannot use logical combination operators `AND` and `OR` for attributes that have: +** Boolean values `true` and `false` +** Minimum-value semantics, for example: +*** *Minimum RBAC permissions* +*** *Days since image was created* +* You cannot use the `NOT` logical operator for attributes that have: +** Boolean values `true` and `false` +** Numeric values that already use comparison, such as the `<`, `>`, `+<=+`, `>=` operators. +** Compound criteria that can have multiple values, for example: +*** *Dockerfile Line*, which includes both instructions and arguments. +*** *Environment Variable*, which consists of both name and value. +** Other meanings, including *Add Capabilities*, *Drop Capabilities*, *Days since image was created*, and *Days since image was last scanned*. + +[cols="<,<,<,<,^,<"] +|=== +| *Attribute* | *Description* | *JSON Attribute* | *Allowed Values* | *Regex*, *NOT*, *AND, OR* | *Phase* + +6+| *Section: Image registry* + +| Image Registry +| The name of the image registry. +| Image Registry +| String +| Regex, + +NOT, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image Name +| The full name of the image in registry, for example `library/nginx`. +| Image Remote +| String +| Regex, + +NOT, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image Tag +| Identifier for an image. +| Image Tag +| String +| Regex, + +NOT, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image Signature +| The list of signature integrations you can use to verify an image's signature. Create alerts on images that either do not have a signature or their signature is not verifiable by at least one of the provided signature integrations. +| Image Signature Verified By +| A valid ID of an already configured image signature integration +| ! `OR` only +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +6+| *Section: Image contents* + +| The Common Vulnerabilities and Exposures (CVE) is fixable +| This criterion results in a violation only if the image in the deployment you are evaluating has a fixable CVE. +| Fixable +| Boolean +| ✕ +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Days Since CVE Was First Discovered In Image +| This criterion results in a violation only if it has been more than a specified number of days since {product-title-short} discovered the CVE in a specific image. +| Days Since CVE Was First Discovered In Image +| Integer +| ✕ +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Days Since CVE Was First Discovered In System +| This criterion results in a violation only if it has been more than a specified number of days since {product-title-short} discovered the CVE across all deployed images in all clusters that {product-title-short} monitors. +| Days Since CVE Was First Discovered In System +| Integer +| ✕ +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image age +| The minimum number of days from image creation date. +| Image Age +| Integer +| ✕ +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image scan age +| The minimum number of days since the image was last scanned. +| Image Scan Age +| Integer +| ✕ +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image User +| Matches the USER directive in the Dockerfile. See https://docs.docker.com/engine/reference/builder/#user for details +. +| Image User +| String +| Regex, + +NOT, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Dockerfile Line +| A specific line in the Dockerfile, including both instructions and arguments. +| Dockerfile Line +| One of: LABEL, RUN, CMD, EXPOSE, ENV, ADD, COPY, ENTRYPOINT, VOLUME, USER, WORKDIR, ONBUILD +| ! Regex only for values, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image scan status +| Check if an image was scanned. +| Unscanned Image +| Boolean +| ✕ +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Common Vulnerability Scoring System (CVSS) +| CVSS: Use it to match images with vulnerabilities whose scores are greater than `>`, less than `<`, or equal to `=` the specified CVSS. +| CVSS +| <, >, \<=, >= or nothing (which implies equal to) + + +-- and -- + + +a decimal (a number with an optional fractional value). + + +Examples: + +>=5, or + +9.5 +| AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Severity +| The severity of the vulnerability based on the CVSS or the vendor. Can be one of Low, Moderate, Important or Critical. +| Severity +| <, >, <=, >= or nothing (which implies equal to) + + +-- and -- + + +One of: + +UNKNOWN + +LOW + +MODERATE + +IMPORTANT + +CRITICAL + + +Examples: + +>=IMPORTANT, or + +CRITICAL +| AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Fixed By +| The version string of a package that fixes a flagged vulnerability in an image. This criterion may be used in addition to other criteria that identify a vulnerability, for example using the CVE criterion. +| Fixed By +| String +| Regex, + +NOT, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| CVE +| Common Vulnerabilities and Exposures, use it with specific CVE numbers. +| CVE +| String +| Regex, + +NOT, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image Component +| Name and version number of a specific software component present in an image. +| Image Component +| key=value + + +Value is optional. + + +If value is missing, it must be in format "key=". +| Regex, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Image OS +| Name and version number of the base operating system of the image. For example, `alpine:3.17.3` +| Image OS +| String +| Regex, + +NOT, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Require image label +| Ensure the presence of a Docker image label. The policy triggers if any image in the deployment does not have the specified label. You can use regular expressions for both key and value fields to match labels. The `Require Image Label` policy criteria only works when you integrate with a Docker registry. For details about Docker labels see Docker documentation, https://docs.docker.com/config/labels-custom-metadata/. +| Required Image Label +| key=value + + +Value is optional. + + +If value is missing, it must be in format "key=". +| Regex, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Disallow image label +| Ensure that a particular Docker image label is NOT used. The policy triggers if any image in the deployment has the specified label. You can use regular expressions for both key and value fields to match labels. The 'Disallow Image Label policy' criteria only works when you integrate with a Docker registry. For details about Docker labels see Docker documentation, https://docs.docker.com/config/labels-custom-metadata/. +| Disallowed Image Label +| key=value + + +Value is optional. + + +If value is missing, it must be in format "key=". +| Regex, + +AND, OR +| *Build*, + +*Deploy*, + +*Runtime* (when used with a Runtime criterion) + +6+| *Section: Container configuration* + +| Environment Variable +| Check environment variables by name or value. When you create a policy that includes the environment variable attribute, +you can choose which types of environment variables the policy should match. For example, you can specify raw values, which are provided directly in the deployment YAML, or you can specify references to values from config maps, secrets, fields, or resource requests or limits. +For any type other than a raw value specified directly in the deployment YAML, the corresponding `value` attribute of the policy rule is ignored. In this case, the policy match is evaluated on the existence of the specified environment variable type. Additionally, this criteria disallows the creation of policies with a non-empty `value` attribute for types other than raw values. +| Environment Variable +a| RAW=key=value to match an environment variable as directly specified in the deployment YAML with a specific key and value. You can omit the `value` attribute to match on only the key. + + +If the environment variable is not defined in the configuration YAML, then you can use the format `SOURCE=KEY`, where `SOURCE` is one of the following objects: + +* SECRET_KEY (SecretKeyRef) +* CONFIG_MAP_KEY (ConfigMapRef) +* FIELD (FieldRef) +* RESOURCE_FIELD (ResourceFieldRef) + +The preceding list provides the API object label first, and then provides the user interface label in parentheses. + +| ! Regex only for key and value (if using RAW) + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Container CPU Request +| Check for the number of cores reserved for a given resource. +| Container CPU Request +| <, >, <=, >= or nothing (which implies equal to) + + +-- and -- + + +A decimal (a number with an optional fractional value) + + +Examples: + + >=5, or + + 9.5 +| AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Container CPU Limit +| Check for the maximum number of cores a resource is allowed to use. +| Container CPU Limit +| (Same as Container CPU Request) +| AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Container Memory Request +| Number, including fraction, of MB requested. +// Do we convert the K8s resource into MB (including convert MiB to MB) ? If so, the documentation should explain this conversion . +| Container Memory Request +| (Same as Container CPU Request) +| AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Container Memory Limit +| Check for the maximum amount of memory a resource is allowed to use. +| Container Memory Limit +| (Same as Container CPU Request) +| AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Privileged container +| Check if a deployment is configured in privileged mode. This criterion only checks the value of the `privileged` field in the respective link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#securitycontext-v1-core[Pod Security Context]. +| Privileged Container +| Boolean: `true` when the value of the `privileged` field in the respective `PodSecurityContext` is set to `true` +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Root filesystem writeability +| Check if a deployment is configured in the `readOnlyFilesystem` mode. +| Read-Only Root Filesystem +| Boolean: `true` when the value of the `readOnlyRootFilesystem` field in the respective `PodSecurityContext` is set to `true` +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Seccomp Profile Type +| The type of `seccomp` profile defined for the deployment. If `seccomp` options are provided at both the pod and container level, the container options override the pod options. See link:https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context-1[Security Context]. +| Seccomp Profile Type +| One of: + + +UNCONFINED + +RUNTIME_DEFAULT + +LOCALHOST +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Privilege escalation +| Provides alerts when a deployment allows a container process to gain more privileges than its parent process. +| Allow Privilege Escalation +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Drop Capabilities +| Linux capabilities that must be dropped from the container. Provides alerts when the specified capabilities are not dropped. +For example, if configured with `SYS_ADMIN` AND `SYS_BOOT`, and the deployment drops only _one_ or _neither_ of these two capabilities, the alert occurs. +| Drop Capabilities + + +| One of: + + +ALL + +AUDIT_CONTROL + +AUDIT_READ + +AUDIT_WRITE + +BLOCK_SUSPEND + +CHOWN + +DAC_OVERRIDE + +DAC_READ_SEARCH + +FOWNER + +FSETID + +IPC_LOCK + +IPC_OWNER + +KILL + +LEASE + +LINUX_IMMUTABLE + +MAC_ADMIN + +MAC_OVERRIDE + +MKNOD + +NET_ADMIN + +NET_BIND_SERVICE + +NET_BROADCAST + +NET_RAW + +SETGID + +SETFCAP + +SETPCAP + +SETUID + +SYS_ADMIN + +SYS_BOOT + +SYS_CHROOT + +SYS_MODULE + +SYS_NICE + +SYS_PACCT + +SYS_PTRACE + +SYS_RAWIO + +SYS_RESOURCE + +SYS_TIME + +SYS_TTY_CONFIG + +SYSLOG + +WAKE_ALARM + +| AND +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Add Capabilities +| Linux capabilities that must not be added to the container, such as the ability to send raw packets or override file permissions. Provides alerts when the specified capabilities are added. For example, if configured with `NET_ADMIN` or `NET_RAW`, and the deployment manifest YAML file includes at least one of these two capabilities, the alert occurs. +| Add Capabilities +| +AUDIT_CONTROL + +AUDIT_READ + +AUDIT_WRITE + +BLOCK_SUSPEND + +CHOWN + +DAC_OVERRIDE + +DAC_READ_SEARCH + +FOWNER + +FSETID + +IPC_LOCK + +IPC_OWNER + +KILL + +LEASE + +LINUX_IMMUTABLE + +MAC_ADMIN + +MAC_OVERRIDE + +MKNOD + +NET_ADMIN + +NET_BIND_SERVICE + +NET_BROADCAST + +NET_RAW + +SETGID + +SETFCAP + +SETPCAP + +SETUID + +SYS_ADMIN + +SYS_BOOT + +SYS_CHROOT + +SYS_MODULE + +SYS_PACCT + +SYS_PTRACE + +SYS_RAWIO + +SYS_RESOURCE + +SYS_TIME + +SYS_TTY_CONFIG + +SYSLOG + +WAKE_ALARM + +| OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Container Name +| The name of the container. +| Container Name +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| AppArmor Profile +| The Application Armor ("AppArmor") profile used in the container. +| AppArmor Profile +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Liveness Probe +| Whether the container defines a liveness probe. +| Liveness Probe +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +| Readiness Probe +| Whether the container defines a readiness probe. +| Readiness Probe +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + + +6+| *Section: Deployment metadata* + +| Disallowed Annotation +| An annotation which is not allowed to be present on Kubernetes resources in a specified environment. +| Disallowed Annotation +| key=value + + +Value is optional. + + +If value is missing, it must be in format "key=". +| Regex, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Required Label +| Check for the presence of a required label in Kubernetes. +| Required Label +| key=value + + +Value is optional. + + +If value is missing, it must be in format "key=". +| Regex, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Required Annotation +| Check for the presence of a required annotation in Kubernetes. +| Required Annotation +| key=value + + +Value is optional. + + +If value is missing, it must be in format "key=". +| Regex, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Runtime Class +| The `RuntimeClass` of the deployment. +| Runtime Class +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Host Network +| Check if `HostNetwork` is enabled which means that the container is not placed inside a separate network stack (for example, the container's networking is not containerized). This implies that the container has full access to the host's network interfaces. +| Host Network +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Host PID +| Check if the Process ID (PID) namespace is isolated between the containers and the host. This allows for processes in different PID namespaces to have the same PID. +| Host PID +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Host IPC +| Check if the IPC (POSIX/SysV IPC) namespace (which provides separation of named shared memory segments, semaphores and message queues) on the host is shared with containers. +| Host IPC +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Namespace +| The name of the namespace the deployment belongs to. +| Namespace +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Replicas +| The number of deployment replicas. If you use `oc scale` to scale the deployment replicas from 0 to a number, then the admission controller blocks this action if the deployment violates a policy. +| Replicas +| <, >, <=, >= or nothing (which implies equal to) + + +-- and -- + + +a decimal (a number with an optional fractional value). + + +Examples: + +>=5, or + +9.5 +| NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +6+| *Section: Storage* + +| Volume Name +| Name of the storage. +| Volume Name +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Volume Source +| Indicates the form in which the volume is provisioned. For example, `persistentVolumeClaim` or `hostPath`. +| Volume Source +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Volume Destination +| The path where the volume is mounted. +| Volume Destination +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Volume Type +| The type of volume. +| Volume Type +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Mounted volume writability +| Volumes that are mounted as writable. +| Writable Mounted Volume +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Mount Propagation +| Check if container is mounting volumes in `Bidirectional`, `Host to Container`, or `None` modes. +| Mount Propagation +| One of: + + +NONE + +HOSTTOCONTAINER + +BIDIRECTIONAL + +| NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Host mount writability +| Resource has mounted a path on the host with write permissions. +| Writable Host Mount +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +6+| *Section: Networking* + +| Protocol +| Protocol, such as, TCP or UDP, that is used by the exposed port. +| Exposed Port Protocol +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Port +| Port numbers exposed by a deployment. +| Exposed Port +| <, >, <=, >= or nothing (which implies equal to) + + +-- and -- + + +an integer. + + +Examples: + +>=1024, or + +22 +| NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Exposed Node Port +| Port numbers exposed externally by a deployment. +| Exposed Node Port +| (Same as Exposed Port) +| NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Port Exposure +| Exposure method of the service, for example, load balancer or node port. +| Port Exposure Method +| One of: + + +Route + +LoadBalancer + +NodePort + +HostPort + +Exposure type is not set + +| NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Unexpected Network Flow Detected +| Check if the detected network traffic is part of the network baseline for the deployment. +| Unexpected Network Flow Detected +| Boolean +| ✕ +| *Runtime* ONLY - Network + +| Ingress Network Policy +| Check the presence or absence of ingress Kubernetes network policies. +| Has Ingress Network Policy +| Boolean +| Regex, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Egress Network Policy +| Check the presence or absence of egress Kubernetes network policies. +| Has Egress Network Policy +| Boolean +| Regex, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +6+| *Section: Process activity* + +| Process Name +| Name of the process executed in a deployment. +| Process Name +| String +| Regex, + +NOT, + +AND, OR +| *Runtime* ONLY - Process + +| Process Ancestor +| Name of any parent process for a process executed in a deployment. +| Process Ancestor +| String +| Regex, + +NOT, + +AND, OR +| *Runtime* ONLY - Process + +| Process Arguments +| Command arguments for a process executed in a deployment. +| Process Arguments +| String +| Regex, + +NOT, + +AND, OR +| *Runtime* ONLY - Process + +| Process UID +| Unix user ID for a process executed in a deployment. +| Process UID +| Integer +| NOT, + +AND, OR +| *Runtime* ONLY - Process + +| Unexpected Process Executed +| Check deployments for which process executions are not listed in the deployment's locked process baseline. +| Unexpected Process Executed +| Boolean +| ✕ +| *Runtime* ONLY - Process + +6+| *Section: Kubernetes access* + +| Service Account +| The name of the service account. +| Service Account +| String +| Regex, + +NOT, + +AND, OR +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Automount Service Account Token +| Check if the deployment configuration automatically mounts the service account token. +| Automount Service Account Token +| Boolean +| ✕ +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +| Minimum RBAC Permissions +| Match if the deployment's Kubernetes service account has Kubernetes RBAC permission level equal to `=` or greater than `>` the specified level. +| Minimum RBAC Permissions +| One of: + + +DEFAULT + +ELEVATED_IN_NAMESPACE + +ELEVATED_CLUSTER_WIDE + +CLUSTER_ADMIN +| NOT +| *Deploy*, + +*Runtime* (when used with a Runtime criterion) + +6+| *Section: Kubernetes events* + +| Kubernetes Action +| The name of the Kubernetes action, such as `Pod Exec`. +| Kubernetes Resource +| One of: + + +PODS_EXEC + +PODS_PORTFORWARD + +| ! `OR` only +| *Runtime* ONLY - Kubernetes Events + +| Kubernetes User Name +| The name of the user who accessed the resource. +| Kubernetes User Name +| Alphanumeric with hyphens (-) and colon (:) only +| Regex, + +NOT, + +! `OR` only +| *Runtime* ONLY - Kubernetes Events + +| Kubernetes User Group +| The name of the group to which the user who accessed the resource belongs to. +| Kubernetes User Groups +| Alphanumeric with hyphens (-) and colon (:) only +| Regex, + +NOT, + +! `OR` only +| *Runtime* ONLY - Kubernetes Events + +| Kubernetes Resource Type +| Type of the accessed Kubernetes resource. +| Kubernetes Resource +| One of: + + +Config maps + +Secrets + +ClusterRoles + +ClusterRoleBindings + +NetworkPolicies + +SecurityContextConstraints + +EgressFirewalls + +| ! `OR` only +| *Runtime* ONLY - Audit Log + +| Kubernetes API Verb +| The Kubernetes API verb that is used to access the resource, such as `GET` or `POST`. +| Kubernetes API Verb +| One of: + + +CREATE + +DELETE + +GET + +PATCH + +UPDATE + +| ! `OR` only +| *Runtime* ONLY - Audit Log + +| Kubernetes Resource Name +| The name of the accessed Kubernetes resource. +| Kubernetes Resource Name +| Alphanumeric with hyphens (-) and colon (:) only +| Regex, + +NOT, + +! `OR` only +| *Runtime* ONLY - Audit Log + +| User Agent +| The user agent that the user used to access the resource. +For example `oc`, or `kubectl`. +| User Agent +| String +| Regex, + +NOT, + +! `OR` only +| *Runtime* ONLY - Audit Log + +| Source IP Address +| The IP address from which the user accessed the resource. +| Source IP Address +| IPV4 or IPV6 address +| Regex, + +NOT, + +! `OR` only +| *Runtime* ONLY - Audit Log + +| Is Impersonated User +| Check if the request was made by a user that is impersonated by a service account or some other account. +| Is Impersonated User +| Boolean +| ✕ +| *Runtime* ONLY - Audit Log + +|=== diff --git a/modules/policy-enforcement-about.adoc b/modules/policy-enforcement-about.adoc new file mode 100644 index 000000000000..5f4d3a36b3f4 --- /dev/null +++ b/modules/policy-enforcement-about.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="policy-enforcement-about_{context}"] += About policy enforcement + +[role="_abstract"] +When you configure policies in {product-title-short}, you can configure how {product-title-short} responds when it detects a condition that violates a security policy. + +{product-title-short} allows you to enforce security policies during all phases of the development lifecycle: build, deploy, and runtime. diff --git a/modules/policy-enforcement-build-stage.adoc b/modules/policy-enforcement-build-stage.adoc new file mode 100644 index 000000000000..747f45c892f9 --- /dev/null +++ b/modules/policy-enforcement-build-stage.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="build-stage-policies_{context}"] += Build stage enforcement + +[role="_abstract"] + +{product-title-short} uses build stage policies to discover and respond to security violations before code is deployed. Build stage policies are composed entirely of image criteria, such as image registry, image content, and CVE data, including scan results and status. + +{product-title-short} checks the build by using the `roxctl image check` and `roxctl deployment check` commands. You can configure {product-title-short} to fail your continuous integration (CI) builds when images match the criteria of the policy. This means that when there is a condition in the build that violates the policy, for example, if there is a fixable CVE of a severity level and you have configured a policy for that condition, the build fails. + +As an example, you can configure {product-title-short} to check an image or deployment and integrate that check into a continuous integration/continuous development (CI/CD) pipeline. Then, if {product-title-short} detects a condition that means a policy should fail, the {product-title-short} API returns a non-zero exit code. These violations are not collected or acted on by {product-title-short}, but are used with a CI/CD tool. You configure your CI/CD tool to act on those results, for example, to fail the build process if a violation is reported. diff --git a/modules/policy-enforcement-deploy.adoc b/modules/policy-enforcement-deploy.adoc new file mode 100644 index 000000000000..fb6754ece0bf --- /dev/null +++ b/modules/policy-enforcement-deploy.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +// * operating/manage_security_policies/about-security-policies.adoc +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: CONCEPT +[id="policy-enforcement-deploy_{context}"] += Deploy stage enforcement + +{product-title} supports two forms of security policy enforcement for deploy-time policies: hard enforcement through the admission controller and soft enforcement by {product-title-short} Sensor. The admission controller blocks creation or updating of deployments that violate policy. If the admission controller is disabled or unavailable, Sensor can perform enforcement by scaling down replicas for deployments that violate policy to 0. + +[WARNING] +==== +Policy enforcement can impact running applications or development processes. Before you enable enforcement options, inform all stakeholders and plan how to respond to the automated enforcement actions. +==== diff --git a/modules/policy-enforcement-hard.adoc b/modules/policy-enforcement-hard.adoc new file mode 100644 index 000000000000..b4c1c2e41fd6 --- /dev/null +++ b/modules/policy-enforcement-hard.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +// * operating/manage_security_policies/about-security-policies.adoc +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: CONCEPT +[id="policy-enforcement-hard_{context}"] += Hard enforcement + +Hard enforcement is performed by the {product-title-short} admission controller. In clusters with admission controller enforcement, the Kubernetes or {ocp} API server blocks all noncompliant deployments. The admission controller blocks `CREATE` and `UPDATE` operations. Any pod create or update request that satisfies a policy configured with deploy-time enforcement enabled will fail. + +[NOTE] +==== +Kubernetes admission webhooks support only `CREATE`, `UPDATE`, `DELETE`, or `CONNECT` operations. The {product-title-short} admission controller supports only `CREATE` and `UPDATE` operations. Operations such as `kubectl patch`, `kubectl set`, and `kubectl scale` are PATCH operations, not UPDATE operations. Because PATCH operations are not supported in Kubernetes, {product-title-short} cannot perform enforcement on PATCH operations. +==== + +For blocking enforcement, you must enable the following settings for the cluster in {product-title-short}: + +* *Enforce on Object Creates*: This toggle in the *Dynamic Configuration* section controls the behavior of the admission control service. +You must have the *Configure Admission Controller Webhook to listen on Object Creates* toggle in the *Static Configuration* section turned on for this to work. +* *Enforce on Object Updates*: This toggle in the *Dynamic Configuration* section controls the behavior of the admission control service. +You must have the *Configure Admission Controller Webhook to listen on Object Updates* toggle in the *Static Configuration* section turned on for this to work. + +If you make changes to settings in the *Static Configuration* setting, you must redeploy the secured cluster for those changes to take effect. diff --git a/modules/policy-enforcement-runtime.adoc b/modules/policy-enforcement-runtime.adoc new file mode 100644 index 000000000000..17075ad0b7f4 --- /dev/null +++ b/modules/policy-enforcement-runtime.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="policy-enforcement-runtime_{context}"] += Runtime enforcement + +[role="_abstract"] +You can configure policies that are enforced during runtime to terminate a pod that violates the policy or, in the case of audit log inspection, notify you of events that violate the policy but have already occurred and have been logged. + +When enforced, a policy violation results in one or more of the following actions: + +* Shutting down an offending pod, which results in creation of another healthy pod in its place +* {product-title-short} intercepting and preventing certain Kubernetes API calls + +[IMPORTANT] +==== +When a violation is triggered by an image or workload rule, a violation alert is generated, but the pod is _not_ disrupted. +==== +//is the above true? I thought the pod was terminated if enforcement is configured. + + diff --git a/modules/policy-enforcement-soft.adoc b/modules/policy-enforcement-soft.adoc new file mode 100644 index 000000000000..1fa7f57984d9 --- /dev/null +++ b/modules/policy-enforcement-soft.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-ci-systems.adoc +// * operating/manage_security_policies/about-security-policies.adoc +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: CONCEPT +[id="policy-enforcement-soft_{context}"] += Soft enforcement + +Soft enforcement is performed by {product-title-short} Sensor. This enforcement prevents an operation from being initiated. With soft enforcement, Sensor scales the replicas to 0, and prevents pods from being scheduled. In this enforcement, a non-ready deployment is available in the cluster. + +By design, Sensor only performs this soft enforcement once, to prevent trapping of update requests to scale the deployment back down again. + +If soft enforcement is configured, and Sensor is down, then {product-title-short} cannot perform enforcement. \ No newline at end of file diff --git a/modules/policy-evaluation-engine.adoc b/modules/policy-evaluation-engine.adoc new file mode 100644 index 000000000000..636256a0c5b3 --- /dev/null +++ b/modules/policy-evaluation-engine.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="policy-evaluation-engine_{context}"] += Understanding the {product-title-short} policy evaluation engine + +[role="_abstract"] + +The {product-title-short} policy engine evaluates policies that you have created based on policy criteria. It operates differently in each of the build, deploy, and runtime stages. + +Build stage:: + +-- +{product-title-short} can evaluate policy rules upon request by using the `roxctl` CLI. When a policy is violated during the build stage, the violation text and error code let developers know what failed and how to fix it. You can configure the error code to fail the pipeline. During this stage, {product-title-short} can evaluate both standalone images and deployments against applicable policies. Violations from the build stage are not stored or routed using notifiers. +-- + +Deploy stage:: + +-- +{product-title-short} uses deploy stage policies when inspecting workloads during a deployment attempt. These policies are composed of workload criteria, such as the following criteria: + +* Container configuration, including environment variables and privileges +* Deployment metadata, such as required or disallowed annotations and labels +* Storage volume information, such as volume name and mount configuration +* Networking configuration, such as port exposure and ingress or egress policy +* Kubernetes access configuration, which consists of criteria such as service account configuration and Role-based Access Control (RBAC) permissions + +You can also include image criteria, such as image registry, image content, and CVE data, when building deploy stage policies. This is helpful if you want to evaluate the same requirements in both pipeline builds and deployment attempts. This eliminates the need to duplicate policies, because you can create a policy that includes both image and workload criteria and use it for both the build and deploy stages. + +{product-title-short} prevents Kubernetes or {ocp} from creating or updating workloads, for example, deployments, daemon sets or jobs, that match the conditions of the policy. This is useful for shutting down deployments with serious problems even if the build was successful. +-- + +Runtime stage:: +-- +{product-title-short} continuously evaluates deployments against applicable policies after a deployment is running. Runtime policies are used to monitor running pods within a Kubernetes cluster and report or prevent unauthorized workload activity, baseline deviations, or prohibited Kubernetes resource operations. {product-title-short} can monitor unsafe Kubernetes requests and selectively block them by using the API. F example, {product-title-short} can block attempted access to config maps or secrets. + +Runtime policies can inspect the following two event sources: + +* Deployment events: Real-time events such as running pods, process activity inside pods, deviations from networking or process baselines, or user-pod interaction such as port forwarding or port exec actions +* Audit log events: Logs that can be inspected for actions such as access to sensitive Kubernetes resources + +Runtime policies can also include build and deploy stage criteria for the following reasons: + +* These criteria can be used to identify high-risk situations combining runtime and workload/image criteria. +* These criteria can ensure that the build and deploy stage requirements are met during runtime, for example, when a new vulnerability is discovered, or a new requirement has been introduced. + +Audit log policies are used to inspect the Kubernetes audit log for actions related to sensitive Kubernetes resources, such as secrets and `ClusterRoleBinding`. They have the following characteristics: + +* Audit log policies are only composed of the audit log criteria. +* They are not associated with images or deployments. For this reason, audit log policies can only be associated with the runtime lifecycle stage. +* These policies are not enforceable, because the audited action has already occurred. +-- + diff --git a/modules/policy-generation-strategy-ng20.adoc b/modules/policy-generation-strategy-ng20.adoc new file mode 100644 index 000000000000..530f85aaea9c --- /dev/null +++ b/modules/policy-generation-strategy-ng20.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="policy-generation-strategy-ng20_{context}"] += About generating policies from the network graph + +A Kubernetes network policy controls which pods receive incoming network traffic, and which pods can send outgoing traffic. +By using network policies to enable and disable traffic to or from pods, you can limit your network attack surface. + +These network policies are YAML configuration files. +It is often difficult to gain insights into the network flow and manually create these files. You can use {product-title-short} to generate these files. +When you automatically generate network policies, {product-title-short} follows these guidelines: + +* {product-title-short} generates a single network policy for each deployment in the namespace. +The pod selector for the policy is the pod selector of the deployment. +** If a deployment already has a network policy, {product-title-short} does not generate new policies or delete existing policies. ++ +Generated policies only restrict traffic to existing deployments. +** Deployments that you create later will not have any restrictions unless you create or generate new network policies for them. +** If a new deployment needs to contact a deployment with a network policy, you might need to edit the network policy to allow access. +* Each policy has the same name as the deployment name, prefixed with `stackrox-generated-`. +For example, the policy name for the deployment `depABC` in the generated network policy is `stackrox-generated-depABC`. +All generated policies also have an identifying label. +* {product-title-short} generates a single rule allowing traffic from any IP address if one of the following conditions are met: +** The deployment has an incoming connection from outside the cluster within the selected time +** The deployment is exposed through a node port or load balancer service +* {product-title-short} generates one `ingress` rule for every deployment from which there is an incoming connection. +** For deployments in the same namespace, this rule uses the pod selector labels from the other deployment. +** For deployments in different namespaces, this rule uses a namespace selector. +To make this possible, {product-title-short} automatically adds a label, `namespace.metadata.stackrox.io/name`, to each namespace. + +[IMPORTANT] +==== +In rare cases, if a standalone pod does not have any labels, the generated policy allows traffic from or to the pod's entire namespace. +==== diff --git a/modules/policy-rules-setting.adoc b/modules/policy-rules-setting.adoc new file mode 100644 index 000000000000..f17a7401ae49 --- /dev/null +++ b/modules/policy-rules-setting.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="setting-policy-rules_{context}"] += Setting policy rules + +[role="_abstract"] + +With policy as code, {product-title-short} supports both internal and external sources for policies. When using external policies, {product-title-short} defines a Kubernetes native Custom Resource (CR) to streamline policy as code by using tools like {pipelines-shortname} and Argo CD. + +You can use {product-title-short} to perform the following actions: + +* Define policy rules: Whether teams manage their policies as code or by using the {product-title-short} internal database, authoring policies can be technically challenging. {product-title-short} provides an intuitive user interface, or portal, that simplifies this task. You can focus on controls while hiding the specification complexity. You can author policies by using the portal and then exported them as YAML to be stored as code or be stored locally. +* Choose the lifecycle to which the policy applies: For internal policies, {product-title-short} offers Create, Read, Update, Delete (CRUD) actions. For external policies, these actions are handled by users on their own, and the results are presented to {product-title-short} using the CR. For internal policies, {product-title-short} also offers role-based access control and tracks changes to policies in its audit log. +* Configure policy behavior: {product-title-short} provides users with multi-cluster governance in a centralized manner. When configuring policies, you can configure the following: +** Select the scope for inclusion or exclusion for individual clusters, or establish governance to apply to all clusters +** Choose the action (inform/enforce), and enable or disable the policy +** Configure notifiers +* Test policies: +** You can perform a dry run to test the policy in the portal or by using the API, and perform policy CR validation +** Create policy reports: You can configure reporting in the portal or by using the API to detail policy coverage + + + diff --git a/modules/policy-structure.adoc b/modules/policy-structure.adoc new file mode 100644 index 000000000000..0cd44816b75c --- /dev/null +++ b/modules/policy-structure.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="policy-structure_{context}"] += {product-title-short} policy structure + +[role="_abstract"] + +{product-title-short} policies are structured text objects that define security rules and the action {product-title-short} performs when these rules are broken. + +//Graphic needed but currently there is no graphics support for our doc team. + +An {product-title-short} policy contains the following parts: + +* *Policy definition*: Specifies the policy's metadata and its rules, including the following components: +** *Policy details*: Text to assist policy authors in managing policies and end users in the remediation process. +** *Lifecycle*: A fundamental policy attribute that determines when that policy is evaluated. +** *Policy rules*: A set of conditions that are used with an implied `OR`, for example, rule 1 _or_ rule 2. Each rule consists of predefined building blocks called policy criteria that use an `AND` relationship, for example, criterion A _and_ criterion B. {product-title-short} uses intuitive text to describe the conditions that you want, rather than having you specify potentially complex Kubernetes conditions. ++ +Most {product-title-short} criteria configure the condition on which to trigger the policy, and many criteria include a `NOT` form. However, a few criteria are designed to define the positive, expected behavior. Whether a criteria is designed for positive or negative condition depends on the context, because they are designed to make creating policies intuitive for policy users. The following examples show negative and positive forms of policy criteria: +** Negative form: `Container Registry name is <gcr.io>` triggers if the specific `gcr.io` registry is used. Consequently, `Container Registry name is NOT <quay.io>` triggers if any registry is used other than the allowed one registry, quay.io. This is a generalized rule. +** Negative form: `Liveness probe is <Not Defined>` triggers if a liveness probe is missing from the configuration. `Liveness probe is <Defined>` can be used to receive a positive indication by using a notifier for all compliant workloads. +** Positive form: The `Drop capabilities, Capabilities that MUST be dropped: <SYS_ADMIN>` rule defines the expected behavior. If a workload fails to drop the `SYS_ADMIN` property, it violates the policy and triggers a violation alert. +* *Policy behavior*: Specifies the action, inform or enforce, that {product-title-short} takes for a given scope. +** *Scope*: By default, {product-title-short} policies are _global_; they apply across all secured clusters, on all namespaces, for all workloads and images. The policy scope can be modified by explicitly including or excluding a mix of cluster, namespace, and deployment selection criteria. Policy scopes can use regular expression to select a namespace name, namespace label, or a deployment name or deployment label, whihc automatically applies across all clusters, including new ones. +** *Action*: This section determines if a policy is active, for example, enabled or disabled, whether it is enforced, and which notifiers to use for routing alerts. + diff --git a/modules/portal-generate-init-bundle.adoc b/modules/portal-generate-init-bundle.adoc new file mode 100644 index 000000000000..f78cee1d7852 --- /dev/null +++ b/modules/portal-generate-init-bundle.adoc @@ -0,0 +1,83 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +// +// You must declare the `topic-helm` or `topic-operator` attribute when using this module. +:_mod-docs-content-type: PROCEDURE +[id="portal-generate-init-bundle_{context}"] += Generating an init bundle by using the RHACS portal + + +ifeval::["{context}" == "init-bundle-cloud-other"] +:cloud-svc: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp"] +:cloud-svc: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-ocp"] +:openshift: +endif::[] + +ifndef::cloud-svc[] +You can create an init bundle containing secrets by using the {product-title-short} portal. +endif::cloud-svc[] + +ifdef::cloud-svc[] +You can create an init bundle containing secrets by using the {product-title-short} portal, also called the ACS Console. +endif::cloud-svc[] + +[NOTE] +==== +You must have the `Admin` user role to create an init bundle. +==== + +.Procedure + +ifndef::cloud-svc[] +. Find the address of the {product-title-short} portal as described in "Verifying Central installation using the Operator method". +endif::cloud-svc[] +. Log in to the {product-title-short} portal. +. If you do not have secured clusters, the *Platform Configuration* -> *Clusters* page appears. +. Click *Create init bundle*. +. Enter a name for the cluster init bundle. +. Select your platform. +. Select the installation method you will use for your secured clusters: *Operator* or *Helm chart*. +. Click *Download* to generate and download the init bundle, which is created in the form of a YAML file. You can use one init bundle and its corresponding YAML file for all secured clusters if you are using the same installation method. ++ +[IMPORTANT] +==== +Store this bundle securely because it contains secrets. +==== +.Next steps +. Apply the init bundle by using it to create resources on the secured cluster. +. Install secured cluster services on each cluster. + +ifeval::["{context}" == "init-bundle-cloud-other"] +:!cloud-svc: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp"] +:!cloud-svc: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-ocp"] +:!openshift: +endif::[] \ No newline at end of file diff --git a/modules/prepare-operator-upgrades.adoc b/modules/prepare-operator-upgrades.adoc new file mode 100644 index 000000000000..090487ef2a57 --- /dev/null +++ b/modules/prepare-operator-upgrades.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * cloud_service/upgrade-cloudsvc-operator.adoc +// * upgrading/upgrade-operator.adoc +:_mod-docs-content-type: CONCEPT +[id="prepare-operator-upgrades_{context}"] += Preparing to upgrade + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:cloud-svc: +endif::[] + +[role="_abstract"] +Before you upgrade the {rh-rhacs-first} version, complete the following steps: + +ifndef::cloud-svc[] +* If you are upgrading from version 3.74, verify that you are running the latest patch release version of the {product-title-short} Operator 3.74. +* Backup your existing Central database. +endif::cloud-svc[] +* If the cluster you are upgrading contains the `SecuredCluster` custom resource (CR), change the collection method to `CORE_BPF`. For more information, see "Changing the collection method". + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:!cloud-svc: +endif::[] \ No newline at end of file diff --git a/modules/preparing-for-deployments-and-upgrades.adoc b/modules/preparing-for-deployments-and-upgrades.adoc new file mode 100644 index 000000000000..10b507ec648a --- /dev/null +++ b/modules/preparing-for-deployments-and-upgrades.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * configuration/internal-certificate-authority-rotation-for-rhacs.adoc + +:_mod-docs-content-type: REFERENCE +[id="preparing-for-deployments-and-upgrades_{context}"] += Preparing for deployments and upgrades + +The following table lists the actions you must take for each deployment scenario during certificate authority (CA) rotation or upgrades: + +.Required user actions +[cols="2,6",options="header"] +|=== +|Deployment scenario |What you must do + +|Operator-managed secured clusters +|No action is needed if Central is also Operator-managed. The Operator automates rotation. + +|Helm-managed secured clusters +|Re-register with a new init bundle or cluster registration secret before the 5-year CA expires. + +|Upgrading a Central instance older than 4 years to {rh-rhacs-first} 4.9 +a| +[NOTE] +==== +Central switches to certificates signed by the new CA and secured clusters older than version 4.9 cannot trust the certificates. +==== + +You can do any of the following tasks: + +* Upgrade all secured clusters to {product-title-short} 4.9. +* Re-register any secured clusters that you cannot upgrade. + +Secured clusters for {product-title-short} 4.9 and later versions automatically trust the new CA if the old CA is still valid. + +|=== \ No newline at end of file diff --git a/modules/preview-policy-violations.adoc b/modules/preview-policy-violations.adoc new file mode 100644 index 000000000000..671426f6ac74 --- /dev/null +++ b/modules/preview-policy-violations.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="preview-policy-violations_{context}"] += Reviewing the policy and previewing violations + +[role="_abstract"] +When creating a policy, {product-title-short} provides a review window where you can view your policy configuration and preview the violations that will occur if the policy is implemented. + +.Procedure + +. Verify that the policy configuration is configured with the correct options. +. The *Preview violations* panel provides additional information, including whether or not build phase or deploy phase deployments have violations of the policy. ++ +[NOTE] +==== +Runtime violations are not available in this preview because they are generated in response to future events. +==== +Before you save the policy, verify that the violations seem accurate. +. Click *Save*. \ No newline at end of file diff --git a/modules/pricing.adoc b/modules/pricing.adoc new file mode 100644 index 000000000000..37c326da8415 --- /dev/null +++ b/modules/pricing.adoc @@ -0,0 +1,8 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_mod-docs-content-type: CONCEPT +[id="pricing_{context}"] += Pricing + +For information about subscription fees, see link:https://www.redhat.com/licenses/Appendix_4_Red_Hat_Online_Services_20221213.pdf[PRODUCT APPENDIX 4 RED HAT ONLINE SERVICES]. diff --git a/modules/private-clusters-about-aws.adoc b/modules/private-clusters-about-aws.adoc deleted file mode 100644 index ed232c1e08d3..000000000000 --- a/modules/private-clusters-about-aws.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="private-clusters-about-aws_{context}"] -= Private clusters in AWS - -To create a private cluster on Amazon Web Services (AWS), you must provide an existing private VPC and subnets to host the cluster. The installation program must also be able to resolve the DNS records that the cluster requires. The installation program configures the Ingress Operator and API server for access from only the private network. - -The cluster still requires access to Internet to access the AWS APIs. - -The following items are not required or created when you install a private cluster: - -* Public subnets -* Public load balancers, which support public ingress -* A public Route 53 zone that matches the `baseDomain` for the cluster - -The installation program does use the `baseDomain` that you specify to create a private Route 53 zone and the required records for the cluster. The cluster is configured so that the Operators do not create public records for the cluster and all cluster machines are placed in the private subnets that you specify. - -[id="private-clusters-limitations-aws_{context}"] -== Limitations - -The ability to add public functionality to a private cluster is limited. - -* You cannot make the Kubernetes API endpoints public after installation without taking additional actions, including creating public subnets in the VPC for each availability zone in use, creating a public load balancer, and configuring the control plane security groups to allow traffic from Internet on 6443 (Kubernetes API port). -* If you use a public Service type load balancer, you must tag a public subnet in each availability zone with `kubernetes.io/cluster/<cluster-infra-id>: shared` so that AWS can use them to create public load balancers. diff --git a/modules/private-clusters-about-azure.adoc b/modules/private-clusters-about-azure.adoc deleted file mode 100644 index 741b52a50c57..000000000000 --- a/modules/private-clusters-about-azure.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc - -[id="private-clusters-about-azure_{context}"] -= Private clusters in Azure - -To create a private cluster on Microsoft Azure, you must provide an existing private VNet and subnets to host the cluster. The installation program must also be able to resolve the DNS records that the cluster requires. The installation program configures the Ingress Operator and API server for only internal traffic. - -Depending how your network connects to the private VNET, you might need to use a DNS forwarder to resolve the cluster's private DNS records. The cluster's machines use `168.63.129.16` internally for DNS resolution. For more information, see link:https://docs.microsoft.com/en-us/azure/dns/private-dns-overview[What is Azure Private DNS?] and link:https://docs.microsoft.com/en-us/azure/virtual-network/what-is-ip-address-168-63-129-16[What is IP address 168.63.129.16?] in the Azure documentation. - -The cluster still requires access to Internet to access the Azure APIs. - -The following items are not required or created when you install a private cluster: - -* A `BaseDomainResourceGroup`, since the cluster does not create public records -* Public IP addresses -* Public DNS records -* Public endpoints - - The cluster is configured so that the Operators do not create public records for the cluster and all cluster machines are placed in the private subnets that you specify. - -[id="private-clusters-limitations-azure_{context}"] -== Limitations - -Private clusters on Azure are subject to only the limitations that are associated with the use of an existing VNet. - - -//// -Is this also valid in Azure? - -The ability to add public functionality to a private cluster is limited. - -* You cannot make the Kubernetes API endpoints public after installation without taking additional actions, including creating public subnets in the VNet for each availablity zone in use, creating a public load balancer, and configuring the control plane security groups to allow traffic from Internet on 6443 (Kubernetes API port). -//// diff --git a/modules/private-clusters-about-gcp.adoc b/modules/private-clusters-about-gcp.adoc deleted file mode 100644 index f7ef8bd4387c..000000000000 --- a/modules/private-clusters-about-gcp.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_gcp/installing-gcp-private.adoc - -[id="private-clusters-about-gcp_{context}"] -= Private clusters in GCP - -To create a private cluster on Google Cloud Platform (GCP), you must provide an existing private VPC and subnets to host the cluster. The installation program must also be able to resolve the DNS records that the cluster requires. The installation program configures the Ingress Operator and API server for only internal traffic. - -The cluster still requires access to Internet to access the GCP APIs. - -The following items are not required or created when you install a private cluster: - -* Public subnets -* Public network load balancers, which support public ingress -* A public DNS zone that matches the `baseDomain` for the cluster - -The installation program does use the `baseDomain` that you specify to create a private DNS zone and the required records for the cluster. The cluster is configured so that the Operators do not create public records for the cluster and all cluster machines are placed in the private subnets that you specify. - -Because it is not possible to limit access to external load balancers based on source tags, the private cluster uses only internal load balancers to allow access to internal instances. - -The internal load balancer relies on instance groups rather than the target pools that the network load balancers use. The installation program creates instance groups for each zone, even if there is no instance in that group. - -* The cluster IP address is internal only. -* One forwarding rule manages both the Kubernetes API and machine config server ports. -* The backend service is comprised of each zone’s instance group and, while it exists, the bootstrap instance group. -* The firewall uses a single rule that is based on only internal source ranges. - -[id="private-clusters-limitations-gcp_{context}"] -== Limitations - -No health check for the Machine config server, `/healthz`, runs because of a difference in load balancer functionality. Two internal load balancers cannot share a single IP address, but two network load balancers can share a single external IP address. Instead, the health of an instance is determined entirely by the `/readyz` check on port 6443. - -//// -Is this also valid in GCP? - -The ability to add public functionality to a private cluster is limited. - -* You cannot make the Kubernetes API endpoints public after installation without taking additional actions, including creating public subnets in the VPC for each availablity zone in use, creating a public load balancer, and configuring the control plane security groups to allow traffic from Internet on 6443 (Kubernetes API port). -//// diff --git a/modules/private-clusters-about.adoc b/modules/private-clusters-about.adoc deleted file mode 100644 index 31e9ebdee721..000000000000 --- a/modules/private-clusters-about.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/configuring-private-cluster.adoc - -[id="private-clusters-about_{context}"] -= About private clusters - -By default, {product-title} is provisioned using publicly-accessible DNS and endpoints. You can set the DNS, Ingress Controller, and API server to private after you deploy your cluster. - -[discrete] -[id="private-clusters-about-dns_{context}"] -== DNS - -If you install {product-title} on installer-provisioned infrastructure, the installation program creates records in a pre-existing public zone and, where possible, creates a private zone for the cluster’s own DNS resolution. In both the public zone and the private zone, the installation program or cluster creates DNS entries for `*.apps`, for the `Ingress` object, and `api`, for the API server. - -The `*.apps` records in the public and private zone are identical, so when you delete the public zone, the private zone seamlessly provides all DNS resolution for the cluster. - -[discrete] -[id="private-clusters-about-ingress-controller_{context}"] -== Ingress Controller -Because the default `Ingress` object is created as public, the load balancer is internet-facing and in the public subnets. You can replace the default Ingress Controller with an internal one. - -[discrete] -[id="private-clusters-about-api-server_{context}"] -== API server - -By default, the installation program creates appropriate network load balancers for the API server to use for both internal and external traffic. - -On Amazon Web Services (AWS), separate public and private load balancers are created. The load balancers are identical except that an additional port is available on the internal one for use within the cluster. Although the installation program automatically creates or destroys the load balancer based on API server requirements, the cluster does not manage or maintain them. As long as you preserve the cluster's access to the API server, you can manually modify or move the load balancers. For the public load balancer, port 6443 is open and the health check is configured for HTTPS against the `/readyz` path. - -On Google Cloud Platform, a single load balancer is created to manage both internal and external API traffic, so you do not need to modify the load balancer. - -On Microsoft Azure, both public and private load balancers are created. However, because of limitations in current implementation, you just retain both load balancers in a private cluster. diff --git a/modules/private-clusters-default.adoc b/modules/private-clusters-default.adoc deleted file mode 100644 index 18dddda4805e..000000000000 --- a/modules/private-clusters-default.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc - -[id="private-clusters-default_{context}"] -= Private clusters - -ifeval::["{context}" == "installing-aws-government-region"] -:aws-gov: -endif::[] - -You can deploy a private {product-title} cluster that does not expose external endpoints. Private clusters are accessible from only an internal network and are not visible to the Internet. - -ifdef::aws-gov[] -[NOTE] -==== -Public zones are not supported in Route 53 in AWS GovCloud or Secret Regions. Therefore, clusters -must be private if they are deployed to an AWS government or secret region. -==== -endif::aws-gov[] - -By default, {product-title} is provisioned to use publicly-accessible DNS and endpoints. A private cluster sets the DNS, Ingress Controller, and API server to private when you deploy your cluster. This means that the cluster resources are only accessible from your internal network and are not visible to the internet. - -To deploy a private cluster, you must use existing networking that meets your requirements. Your cluster resources might be shared between other clusters on the network. - -Additionally, you must deploy a private cluster from a machine that has access the API services for the cloud you provision to, the hosts on the network that you provision, and to the internet to obtain installation media. You can use any machine that meets these access requirements and follows your company's guidelines. For example, this machine can be a bastion host on your cloud network or a machine that has access to the network through a VPN. - -ifeval::["{context}" == "installing-aws-government-region"] -:!aws-gov: -endif::[] diff --git a/modules/private-clusters-setting-api-private.adoc b/modules/private-clusters-setting-api-private.adoc deleted file mode 100644 index b96a3a3cfe70..000000000000 --- a/modules/private-clusters-setting-api-private.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/configuring-private-cluster.adoc - -[id="private-clusters-setting-api-private_{context}"] -= Restricting the API server to private - -After you deploy a cluster to Amazon Web Services (AWS) or Microsoft Azure, you can reconfigure the API server to use only the private zone. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Have access to the web console as a user with `admin` privileges. - -.Procedure - -. In the web portal or console for AWS or Azure, take the following actions: - -.. Locate and delete appropriate load balancer component. -*** For AWS, delete the external load balancer. The API DNS entry in the private zone already points to the internal load balancer, which uses an identical configuration, so you do not need to modify the internal load balancer. -*** For Azure, delete the `api-internal` rule for the load balancer. - -.. Delete the `api.$clustername.$yourdomain` DNS entry in the public zone. - -. From your terminal, list the cluster machines: -+ -[source,terminal] ----- -$ oc get machine -n openshift-machine-api ----- -+ -.Example output -[source,terminal] ----- -NAME STATE TYPE REGION ZONE AGE -lk4pj-master-0 running m4.xlarge us-east-1 us-east-1a 17m -lk4pj-master-1 running m4.xlarge us-east-1 us-east-1b 17m -lk4pj-master-2 running m4.xlarge us-east-1 us-east-1a 17m -lk4pj-worker-us-east-1a-5fzfj running m4.xlarge us-east-1 us-east-1a 15m -lk4pj-worker-us-east-1a-vbghs running m4.xlarge us-east-1 us-east-1a 15m -lk4pj-worker-us-east-1b-zgpzg running m4.xlarge us-east-1 us-east-1b 15m ----- -+ -You modify the control plane machines, which contain `master` in the name, in the following step. - -. Remove the external load balancer from each control plane machine. -.. Edit a control plane `Machine` object to remove the reference to the external load balancer. -+ -[source,terminal] ----- -$ oc edit machines -n openshift-machine-api <master_name> <1> ----- -<1> Specify the name of the control plane, or master, `Machine` object to modify. - -.. Remove the lines that describe the external load balancer, which are marked in the following example, and save and exit the object specification: -+ -[source,yaml] ----- -... -spec: - providerSpec: - value: - ... - loadBalancers: - - name: lk4pj-ext <1> - type: network <1> - - name: lk4pj-int - type: network ----- -<1> Delete this line. - -.. Repeat this process for each of the machines that contains `master` in the name. diff --git a/modules/private-clusters-setting-dns-private.adoc b/modules/private-clusters-setting-dns-private.adoc deleted file mode 100644 index d2a72aa216d9..000000000000 --- a/modules/private-clusters-setting-dns-private.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/configuring-private-cluster.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="private-clusters-setting-dns-private_{context}"] -= Setting DNS to private - -After you deploy a cluster, you can modify its DNS to use only a private zone. - -.Procedure - -. Review the `DNS` custom resource for your cluster: -+ -[source,terminal] ----- -$ oc get dnses.config.openshift.io/cluster -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: DNS -metadata: - creationTimestamp: "2019-10-25T18:27:09Z" - generation: 2 - name: cluster - resourceVersion: "37966" - selfLink: /apis/config.openshift.io/v1/dnses/cluster - uid: 0e714746-f755-11f9-9cb1-02ff55d8f976 -spec: - baseDomain: <base_domain> - privateZone: - tags: - Name: <infrastructureID>-int - kubernetes.io/cluster/<infrastructureID>: owned - publicZone: - id: Z2XXXXXXXXXXA4 -status: {} ----- -+ -Note that the `spec` section contains both a private and a public zone. - -. Patch the `DNS` custom resource to remove the public zone: -+ -[source,terminal] ----- -$ oc patch dnses.config.openshift.io/cluster --type=merge --patch='{"spec": {"publicZone": null}}' -dns.config.openshift.io/cluster patched ----- -+ -Because the Ingress Controller consults the `DNS` definition when it creates `Ingress` objects, when you create or modify `Ingress` objects, only private records are created. -+ -[IMPORTANT] -==== -DNS records for the existing Ingress objects are not modified when you remove the public zone. -==== - -. Optional: Review the `DNS` custom resource for your cluster and confirm that the public zone was removed: -+ -[source,terminal] ----- -$ oc get dnses.config.openshift.io/cluster -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: DNS -metadata: - creationTimestamp: "2019-10-25T18:27:09Z" - generation: 2 - name: cluster - resourceVersion: "37966" - selfLink: /apis/config.openshift.io/v1/dnses/cluster - uid: 0e714746-f755-11f9-9cb1-02ff55d8f976 -spec: - baseDomain: <base_domain> - privateZone: - tags: - Name: <infrastructureID>-int - kubernetes.io/cluster/<infrastructureID>-wfpg4: owned -status: {} ----- diff --git a/modules/private-clusters-setting-ingress-private.adoc b/modules/private-clusters-setting-ingress-private.adoc deleted file mode 100644 index 5f76bfd06594..000000000000 --- a/modules/private-clusters-setting-ingress-private.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/configuring-private-cluster.adoc - -[id="private-clusters-setting-ingress-private_{context}"] -= Setting the Ingress Controller to private - -After you deploy a cluster, you can modify its Ingress Controller to use only a private zone. - -.Procedure - -. Modify the default Ingress Controller to use only an internal endpoint: -+ -[source,terminal] ----- -$ oc replace --force --wait --filename - <<EOF -apiVersion: operator.openshift.io/v1 -kind: IngressController -metadata: - namespace: openshift-ingress-operator - name: default -spec: - endpointPublishingStrategy: - type: LoadBalancerService - loadBalancer: - scope: Internal -EOF ----- -+ -.Example output -[source,terminal] ----- -ingresscontroller.operator.openshift.io "default" deleted -ingresscontroller.operator.openshift.io/default replaced ----- -+ -The public DNS entry is removed, and the private zone entry is updated. diff --git a/modules/process-discovery-event-timeline.adoc b/modules/process-discovery-event-timeline.adoc new file mode 100644 index 000000000000..05ac082cedb9 --- /dev/null +++ b/modules/process-discovery-event-timeline.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="process-discovery-event-timeline_{context}"] += Event timeline section + +[role="_abstract"] +The *Event Timeline* section in the *Process Discovery* tab provides an overview of events for the selected deployment. +It shows the number of policy violations, process activities, and container termination or restart events. + +You can select *Event Timeline* to view more details. + +The *Event Timeline* modal box shows events for all pods for the selected deployment. + +The events on the timeline are categorized as: + +* Process activities +* Policy violations +* Container restarts +* Container terminations + +The events appear as icons on a timeline. +To see more details about an event, hold your mouse pointer over the event icon. +The details appear in a tooltip. + +* Click *Show Legend* to see which icon corresponds to which type of event. +* Select *Export* -> *Download PDF* or *Export* -> *Download CSV* to download the event timeline information. +* Select the *Show All* drop-down menu to filter which type of events are visible on the timeline. +* Click on the expand icon to see events separately for each container in the selected pod. + +All events in the timeline are also visible in the minimap control at the bottom. +The minimap controls the number of events visible in the event timeline. +You can change the events shown in the timeline by modifying the highlighted area on the minimap. +To do this, decrease the highlighted area from left or right sides (or both), and then drag the highlighted area. + +[NOTE] +==== +* When containers restart, {product-title}: +** Shows information about container termination and restart events for up to 10 inactive container instances for each container in a pod. +For example, for a pod with two containers `app` and `sidecar`, {product-title} keeps activity for up to 10 `app` instances and up to 10 `sidecar` instances. +** Does not track process activities associated with the previous instances of the container. +* {product-title} only shows the most recent execution of each (process name, process arguments, UID) tuple for each pod. +* {product-title} shows events only for the active pods. +* {product-title} adjusts the reported timestamps based on time reported by Kubernetes and the Collector. +Kubernetes timestamps use second-based precision, and it rounds off the time to the nearest second. +However, the Collector uses more precise timestamps. +For example, if Kubernetes reports the container start time as `10:54:48`, and the Collector reports a process in that container started at `10:54:47.5349823`, {product-title} adjusts the container start time to `10:54:47.5349823`. +==== diff --git a/modules/process-discovery-tab.adoc b/modules/process-discovery-tab.adoc new file mode 100644 index 000000000000..384b23c32344 --- /dev/null +++ b/modules/process-discovery-tab.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="process-discovery-tab_{context}"] += Process discovery tab + +[role="_abstract"] +The *Process Discovery* tab provides a comprehensive list of all binaries that have been executed in each container in your environment, summarized by deployment. + +The process discovery tab shows details about the following: + +* *Binary Name*: The name of the binary that was executed. +* *Container*: The container in the deployment in which the process executed. +* *Arguments*: The specific arguments that were passed with the binary. +* *Time*: The date and time of the most recent time the binary was executed in a given container. +* *Pod ID*: The identifier of the pod in which the container resides. +* *UID*: The Linux user identity under which the process executed. + +Use the `Process Name:<name>` query in the filter bar to find specific processes. +//See the link:/docs/search/#use-local-page-filtering[Use local page filtering] topic for more information. diff --git a/modules/prometheus-database-storage-requirements.adoc b/modules/prometheus-database-storage-requirements.adoc deleted file mode 100644 index a41343b184a5..000000000000 --- a/modules/prometheus-database-storage-requirements.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/scaling-cluster-monitoring-operator.adoc -// * installing-byoh/installing-existing-hosts.adoc - -[id="prometheus-database-storage-requirements_{context}"] -= Prometheus database storage requirements - -Red Hat performed various tests for different scale sizes. - -[NOTE] -==== -The Prometheus storage requirements below are not prescriptive. Higher resource consumption might be observed in your cluster depending on workload activity and resource use. -==== - -.Prometheus Database storage requirements based on number of nodes/pods in the cluster -[options="header"] -|=== -|Number of Nodes |Number of pods |Prometheus storage growth per day |Prometheus storage growth per 15 days |RAM Space (per scale size) |Network (per tsdb chunk) - -|50 -|1800 -|6.3 GB -|94 GB -|6 GB -|16 MB - -|100 -|3600 -|13 GB -|195 GB -|10 GB -|26 MB - -|150 -|5400 -|19 GB -|283 GB -|12 GB -|36 MB - -|200 -|7200 -|25 GB -|375 GB -|14 GB -|46 MB -|=== - -Approximately 20 percent of the expected size was added as overhead to ensure that the storage requirements do not exceed the calculated value. - -The above calculation is for the default {product-title} Cluster Monitoring Operator. - -[NOTE] -==== -CPU utilization has minor impact. The ratio is approximately 1 core out of 40 per 50 nodes and 1800 pods. -==== - -*Recommendations for {product-title}* - -* Use at least three infrastructure (infra) nodes. -* Use at least three *openshift-container-storage* nodes with non-volatile memory express (NVMe) drives. diff --git a/modules/prometheus-operator.adoc b/modules/prometheus-operator.adoc deleted file mode 100644 index e4cadf6758bf..000000000000 --- a/modules/prometheus-operator.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="prometheus-operator_{context}"] -= Prometheus Operator - -[discrete] -== Purpose - -The Prometheus Operator for Kubernetes provides easy monitoring definitions for Kubernetes services and deployment and management of Prometheus instances. - -Once installed, the Prometheus Operator provides the following features: - -* Create and Destroy: Easily launch a Prometheus instance for your Kubernetes namespace, a specific application or team easily using the Operator. - -* Simple Configuration: Configure the fundamentals of Prometheus like versions, persistence, retention policies, and replicas from a native Kubernetes resource. - -* Target Services via Labels: Automatically generate monitoring target configurations based on familiar Kubernetes label queries; no need to learn a Prometheus specific configuration language. - -[discrete] -== Project - -link:https://github.com/openshift/prometheus-operator[prometheus-operator] diff --git a/modules/prometheus-service-monitor.adoc b/modules/prometheus-service-monitor.adoc new file mode 100644 index 000000000000..643c7650af01 --- /dev/null +++ b/modules/prometheus-service-monitor.adoc @@ -0,0 +1,51 @@ +// Module included in the following assemblies: +// +// * configuration/monitor-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="prometheus-service-monitor-example_{context}"] += Monitoring Central by using Prometheus service monitor + +[role="_abstract"] +If you are using the Prometheus Operator, you can use a service monitor to scrape the metrics from {rh-rhacs-first}. + +[NOTE] +==== +If you are not using the Prometheus operator, you must edit the Prometheus configuration files to receive the data from {product-title-short}. +==== + +.Procedure +. Create a new `servicemonitor.yaml` file with the following content: ++ +[source,yaml] +---- +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + name: prometheus-stackrox + namespace: stackrox +spec: + endpoints: + - interval: 30s + port: monitoring + scheme: http + selector: + matchLabels: + app.kubernetes.io/name: <stackrox-service> <1> +---- +<1> The labels must match with the `Service` resource that you want to monitor. For example, `central` or `scanner`. +. Apply the YAML to the cluster: ++ +[source,terminal] +---- +$ oc apply -f servicemonitor.yaml <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +.Verification +* Run the following command to check the status of service monitor: ++ +[source,terminal] +---- +$ oc get servicemonitor --namespace stackrox <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. diff --git a/modules/provision-postgresql-database.adoc b/modules/provision-postgresql-database.adoc new file mode 100644 index 000000000000..4888f654dfb0 --- /dev/null +++ b/modules/provision-postgresql-database.adoc @@ -0,0 +1,72 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-ocp.adoc +:_mod-docs-content-type: PROCEDURE +[id="provision-postgresql-database_{context}"] += Provisioning a database in your PostgreSQL instance + +[role="_abstract"] +This step is optional. You can use your existing PostgreSQL infrastructure to provision a database for {product-title-short}. Use the instructions in this section for configuring a PostgreSQL database environment, creating a user, database, schema, role, and granting required permissions. + +.Procedure +. Create a new user: ++ +[source,terminal] +---- +CREATE USER stackrox WITH PASSWORD <password>; +---- +. Create a database: ++ +[source,terminal] +---- +CREATE DATABASE stackrox; +---- +. Connect to the database: ++ +[source,terminal] +---- +\connect stackrox +---- +. Create user schema: ++ +[source,terminal] +---- +CREATE SCHEMA stackrox; +---- +. (Optional) Revoke rights on public: ++ +[source,terminal] +---- +REVOKE CREATE ON SCHEMA public FROM PUBLIC; +REVOKE USAGE ON SCHEMA public FROM PUBLIC; +REVOKE ALL ON DATABASE stackrox FROM PUBLIC; +---- +. Create a role: ++ +[source,terminal] +---- +CREATE ROLE readwrite; +---- +. Grant connection permission to the role: ++ +[source,terminal] +---- +GRANT CONNECT ON DATABASE stackrox TO readwrite; +---- +. Add required permissions to the `readwrite` role: ++ +[source,terminal] +---- +GRANT USAGE ON SCHEMA stackrox TO readwrite; +GRANT USAGE, CREATE ON SCHEMA stackrox TO readwrite; +GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA stackrox TO readwrite; +ALTER DEFAULT PRIVILEGES IN SCHEMA stackrox GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO readwrite; +GRANT USAGE ON ALL SEQUENCES IN SCHEMA stackrox TO readwrite; +ALTER DEFAULT PRIVILEGES IN SCHEMA stackrox GRANT USAGE ON SEQUENCES TO readwrite; +---- +. Assign the `readwrite` role to the `stackrox` user: ++ +[source,terminal] +---- +GRANT readwrite TO stackrox; +---- diff --git a/modules/pruning-basic-operations.adoc b/modules/pruning-basic-operations.adoc deleted file mode 100644 index 51fcca379886..000000000000 --- a/modules/pruning-basic-operations.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/pruning-objects.adoc - -[id="pruning-basic-operations_{context}"] -= Basic pruning operations - -The CLI groups prune operations under a common parent command: - -[source,terminal] ----- -$ oc adm prune <object_type> <options> ----- - -This specifies: - -- The `<object_type>` to perform the action on, such as `groups`, `builds`, -`deployments`, or `images`. -- The `<options>` supported to prune that object type. diff --git a/modules/pruning-builds.adoc b/modules/pruning-builds.adoc deleted file mode 100644 index 90a1de19dcef..000000000000 --- a/modules/pruning-builds.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/pruning-objects.adoc - -[id="pruning-builds_{context}"] -= Pruning builds - -To prune builds that are no longer required by the system due to age and status, administrators can run the following command: - -[source,terminal] ----- -$ oc adm prune builds [<options>] ----- - -.Prune builds CLI configuration options -[cols="4,8",options="header"] -|=== - -|Option |Description - -.^|`--confirm` -|Indicate that pruning should occur, instead of performing a dry-run. - -.^|`--orphans` -|Prune all builds whose build configuration no longer exists, status is complete, failed, error, or canceled. - -.^|`--keep-complete=<N>` -|Per build configuration, keep the last `N` builds whose status is complete (default `5`). - -.^|`--keep-failed=<N>` -|Per build configuration, keep the last `N` builds whose status is failed, error, or canceled (default `1`). - -.^|`--keep-younger-than=<duration>` -|Do not prune any object that is younger than `<duration>` relative to the current time (default `60m`). -|=== - -To see what a pruning operation would delete: - -[source,terminal] ----- -$ oc adm prune builds --orphans --keep-complete=5 --keep-failed=1 \ - --keep-younger-than=60m ----- - -To actually perform the prune operation: - -[source,terminal] ----- -$ oc adm prune builds --orphans --keep-complete=5 --keep-failed=1 \ - --keep-younger-than=60m --confirm ----- - -[NOTE] -==== -Developers can enable automatic build pruning by modifying their build configuration. -==== diff --git a/modules/pruning-cronjobs.adoc b/modules/pruning-cronjobs.adoc deleted file mode 100644 index 9d75606b6c77..000000000000 --- a/modules/pruning-cronjobs.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/pruning-objects.adoc - -[id="pruning-cronjobs_{context}"] -= Pruning cron jobs - -Cron jobs can perform pruning of successful jobs, but might not properly handle -failed jobs. Therefore, the cluster administrator should perform regular cleanup of -jobs manually. They should also restrict the access to cron jobs to a small -group of trusted users and set appropriate quota to prevent the cron job from -creating too many jobs and pods. diff --git a/modules/pruning-deployments.adoc b/modules/pruning-deployments.adoc deleted file mode 100644 index ee43b05f2387..000000000000 --- a/modules/pruning-deployments.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/pruning-objects.adoc - -[id="pruning-deployments_{context}"] -= Pruning `DeploymentConfig` objects - -To prune `DeploymentConfig` objects that are no longer required by the system due to age and status, administrators can run the following command: - -[source,terminal] ----- -$ oc adm prune deployments [<options>] ----- - -.Prune deployments CLI configuration options -[cols="4,8",options="header"] -|=== - -|Option |Description - -.^|`--confirm` -|Indicate that pruning should occur, instead of performing a dry-run. - -.^|`--orphans` -|Prune all deployments that no longer have a `DeploymentConfig` object, has status of `Complete` or `Failed`, and has a replica count of zero. - -.^|`--keep-complete=<N>` -|Per the `DeploymentConfig` object, keep the last `N` deployments that have a status of `Complete` and replica count of zero. (default `5`) - -.^|`--keep-failed=<N>` -|Per the `DeploymentConfig` object, keep the last `N` deployments that have a status of `Failed` and replica count of zero. (default `1`) - -.^|`--keep-younger-than=<duration>` -|Do not prune any object that is younger than `<duration>` relative to the current time. (default `60m`) Valid units of measurement include nanoseconds (`ns`), microseconds (`us`), milliseconds (`ms`), seconds (`s`), minutes (`m`), and hours (`h`). -|=== - -To see what a pruning operation would delete: - -[source,terminal] ----- -$ oc adm prune deployments --orphans --keep-complete=5 --keep-failed=1 \ - --keep-younger-than=60m ----- - -To actually perform the prune operation: - -[source,terminal] ----- -$ oc adm prune deployments --orphans --keep-complete=5 --keep-failed=1 \ - --keep-younger-than=60m --confirm ----- diff --git a/modules/pruning-groups.adoc b/modules/pruning-groups.adoc deleted file mode 100644 index 3cad8c4e88a2..000000000000 --- a/modules/pruning-groups.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/pruning-objects.adoc - -[id="pruning-groups_{context}"] -= Pruning groups - -To prune groups records from an external provider, administrators can run the -following command: - -[source,terminal] ----- -$ oc adm prune groups \ - --sync-config=path/to/sync/config [<options>] ----- - -.Prune groups CLI configuration options -[cols="4,8",options="header"] -|=== - -|Options |Description - -.^|`--confirm` -|Indicate that pruning should occur, instead of performing a dry-run. - -.^|`--blacklist` -|Path to the group blacklist file. - -.^|`--whitelist` -|Path to the group whitelist file. - -.^|`--sync-config` -|Path to the synchronization configuration file. -|=== - -To see the groups that the prune command deletes: - -[source,terminal] ----- -$ oc adm prune groups --sync-config=ldap-sync-config.yaml ----- - -To perform the prune operation: - -[source,terminal] ----- -$ oc adm prune groups --sync-config=ldap-sync-config.yaml --confirm ----- - -//// -Needs "Additional resources" links when converted: - -//Future xref:../install_config/syncing_groups_with_ldap.adoc#configuring-ldap-sync[Configuring LDAP Sync] -//Future xref:../install_config/syncing_groups_with_ldap.adoc#overview[Syncing Groups With LDAP] -//// diff --git a/modules/pruning-hard-pruning-registry.adoc b/modules/pruning-hard-pruning-registry.adoc deleted file mode 100644 index 32ce6f8cc3ae..000000000000 --- a/modules/pruning-hard-pruning-registry.adoc +++ /dev/null @@ -1,158 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/pruning-objects.adoc - -[id="pruning-hard-pruning-registry_{context}"] -= Hard pruning the registry - -The OpenShift Container Registry can accumulate blobs that are not referenced by -the {product-title} cluster's etcd. The basic pruning images procedure, -therefore, is unable to operate on them. These are called _orphaned blobs_. - -Orphaned blobs can occur from the following scenarios: - -- Manually deleting an image with `oc delete image <sha256:image-id>` command, -which only removes the image from etcd, but not from the registry's storage. - -- Pushing to the registry initiated by daemon failures, which causes some blobs to -get uploaded, but the image manifest (which is uploaded as the very last -component) does not. All unique image blobs become orphans. - -- {product-title} refusing an image because of quota restrictions. - -- The standard image pruner deleting an image manifest, but is interrupted before -it deletes the related blobs. - -- A bug in the registry pruner, which fails to remove the intended blobs, causing -the image objects referencing them to be removed and the blobs becoming orphans. -// Find this BZ - -_Hard pruning_ the registry, a separate procedure from basic image pruning, -allows cluster administrators to remove orphaned blobs. You should hard prune if -you are running out of storage space in your OpenShift Container Registry and -believe you have orphaned blobs. - -This should be an infrequent operation and is necessary only when you have -evidence that significant numbers of new orphans have been created. Otherwise, -you can perform standard image pruning at regular intervals, for example, once a -day (depending on the number of images being created). - -.Procedure - -To hard prune orphaned blobs from the registry: - -. *Log in.* -+ -Log in to the cluster with the CLI as `kubeadmin` or another privileged user that -has access to the `openshift-image-registry` namespace. - -. *Run a basic image prune*. -+ -Basic image pruning removes additional images that are no longer needed. The -hard prune does not remove images on its own. It only removes blobs stored in -the registry storage. Therefore, you should run this just before the hard prune. - -. *Switch the registry to read-only mode.* -+ -If the registry is not running in read-only mode, any pushes happening at the -same time as the prune will either: -+ --- -- fail and cause new orphans, or -- succeed although the images cannot be pulled (because some of the -referenced blobs were deleted). --- -+ -Pushes will not succeed until the registry is switched back to read-write mode. -Therefore, the hard prune must be carefully scheduled. -+ -To switch the registry to read-only mode: - -.. In `configs.imageregistry.operator.openshift.io/cluster`, set `spec.readOnly` to `true`: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io/cluster -p '{"spec":{"readOnly":true}}' --type=merge ----- - -. *Add the `system:image-pruner` role.* -+ -The service account used to run the registry instances requires additional -permissions to list some resources. - -.. Get the service account name: -+ -[source,terminal] ----- -$ service_account=$(oc get -n openshift-image-registry \ - -o jsonpath='{.spec.template.spec.serviceAccountName}' deploy/image-registry) ----- - -.. Add the `system:image-pruner` cluster role to the service account: -+ -[source,terminal] ----- -$ oc adm policy add-cluster-role-to-user \ - system:image-pruner -z \ - ${service_account} -n openshift-image-registry ----- - -. *Optional: Run the pruner in dry-run mode.* -+ -To see how many blobs would be removed, run the hard pruner in dry-run mode. No changes are actually made. The following example references an image registry pod called `image-registry-3-vhndw`: -+ -[source,terminal] ----- -$ oc -n openshift-image-registry exec pod/image-registry-3-vhndw -- /bin/sh -c '/usr/bin/dockerregistry -prune=check' ----- -+ -Alternatively, to get the exact paths for the prune candidates, increase the -logging level: -+ -[source,terminal] ----- -$ oc -n openshift-image-registry exec pod/image-registry-3-vhndw -- /bin/sh -c 'REGISTRY_LOG_LEVEL=info /usr/bin/dockerregistry -prune=check' ----- -+ -.Example output -[source,terminal] ----- -time="2017-06-22T11:50:25.066156047Z" level=info msg="start prune (dry-run mode)" distribution_version="v2.4.1+unknown" kubernetes_version=v1.6.1+$Format:%h$ openshift_version=unknown -time="2017-06-22T11:50:25.092257421Z" level=info msg="Would delete blob: sha256:00043a2a5e384f6b59ab17e2c3d3a3d0a7de01b2cabeb606243e468acc663fa5" go.version=go1.7.5 instance.id=b097121c-a864-4e0c-ad6c-cc25f8fdf5a6 -time="2017-06-22T11:50:25.092395621Z" level=info msg="Would delete blob: sha256:0022d49612807cb348cabc562c072ef34d756adfe0100a61952cbcb87ee6578a" go.version=go1.7.5 instance.id=b097121c-a864-4e0c-ad6c-cc25f8fdf5a6 -time="2017-06-22T11:50:25.092492183Z" level=info msg="Would delete blob: sha256:0029dd4228961086707e53b881e25eba0564fa80033fbbb2e27847a28d16a37c" go.version=go1.7.5 instance.id=b097121c-a864-4e0c-ad6c-cc25f8fdf5a6 -time="2017-06-22T11:50:26.673946639Z" level=info msg="Would delete blob: sha256:ff7664dfc213d6cc60fd5c5f5bb00a7bf4a687e18e1df12d349a1d07b2cf7663" go.version=go1.7.5 instance.id=b097121c-a864-4e0c-ad6c-cc25f8fdf5a6 -time="2017-06-22T11:50:26.674024531Z" level=info msg="Would delete blob: sha256:ff7a933178ccd931f4b5f40f9f19a65be5eeeec207e4fad2a5bafd28afbef57e" go.version=go1.7.5 instance.id=b097121c-a864-4e0c-ad6c-cc25f8fdf5a6 -time="2017-06-22T11:50:26.674675469Z" level=info msg="Would delete blob: sha256:ff9b8956794b426cc80bb49a604a0b24a1553aae96b930c6919a6675db3d5e06" go.version=go1.7.5 instance.id=b097121c-a864-4e0c-ad6c-cc25f8fdf5a6 -... -Would delete 13374 blobs -Would free up 2.835 GiB of disk space -Use -prune=delete to actually delete the data ----- - -. *Run the hard prune.* -+ -Execute the following command inside one running instance of a `image-registry` pod to run the hard prune. The following example references an image registry pod called `image-registry-3-vhndw`: -+ -[source,terminal] ----- -$ oc -n openshift-image-registry exec pod/image-registry-3-vhndw -- /bin/sh -c '/usr/bin/dockerregistry -prune=delete' ----- -+ -.Example output -[source,terminal] ----- -Deleted 13374 blobs -Freed up 2.835 GiB of disk space ----- - -. *Switch the registry back to read-write mode.* -+ -After the prune is finished, the registry can be switched back to read-write -mode. In `configs.imageregistry.operator.openshift.io/cluster`, set -`spec.readOnly` to `false`: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io/cluster -p '{"spec":{"readOnly":false}}' --type=merge ----- diff --git a/modules/pruning-images-manual.adoc b/modules/pruning-images-manual.adoc deleted file mode 100644 index d69374f2e728..000000000000 --- a/modules/pruning-images-manual.adoc +++ /dev/null @@ -1,381 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/pruning-objects.adoc - -[id="pruning-images-manual_{context}"] -= Manually pruning images - -The pruning custom resource enables automatic image pruning. However, administrators can manually prune images that are no longer required by the system due to age, status, or exceed limits. There are two methods to manually prune images: - -* Running image pruning as a `Job` or `CronJob` on the cluster. -* Running the `oc adm prune images` command. - -.Prerequisites - -* To prune images, you must first log in to the CLI as a user with an access token. The user must also have the `system:image-pruner` cluster role or greater (for example, `cluster-admin`). -* Expose the image registry. - -.Procedure - -To manually prune images that are no longer required by the system due to age, status, or exceed limits, use one of the following methods: - -* Run image pruning as a `Job` or `CronJob` on the cluster by creating a YAML file for the `pruner` service account, for example: -+ -[source,terminal] ----- -$ oc create -f <filename>.yaml ----- -+ -.Example output -+ -[source,yaml] ----- -kind: List -apiVersion: v1 -items: -- apiVersion: v1 - kind: ServiceAccount - metadata: - name: pruner - namespace: openshift-image-registry -- apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: openshift-image-registry-pruner - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: system:image-pruner - subjects: - - kind: ServiceAccount - name: pruner - namespace: openshift-image-registry -- apiVersion: batch/v1beta1 - kind: CronJob - metadata: - name: image-pruner - namespace: openshift-image-registry - spec: - schedule: "0 0 * * *" - concurrencyPolicy: Forbid - successfulJobsHistoryLimit: 1 - failedJobsHistoryLimit: 3 - jobTemplate: - spec: - template: - spec: - restartPolicy: OnFailure - containers: - - image: "quay.io/openshift/origin-cli:4.1" - resources: - requests: - cpu: 1 - memory: 1Gi - terminationMessagePolicy: FallbackToLogsOnError - command: - - oc - args: - - adm - - prune - - images - - --certificate-authority=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt - - --keep-tag-revisions=5 - - --keep-younger-than=96h - - --confirm=true - name: image-pruner - serviceAccountName: pruner ----- - -* Run the `oc adm prune images [<options>]` command: -+ -[source,terminal] ----- -$ oc adm prune images [<options>] ----- -+ -Pruning images removes data from the integrated registry unless `--prune-registry=false` is used. -+ -Pruning images with the `--namespace` flag does not remove images, only image streams. Images are non-namespaced resources. Therefore, limiting pruning to a particular namespace makes it impossible to calculate its current usage. -+ -By default, the integrated registry caches metadata of blobs to reduce the number of requests to storage, and to increase the request-processing speed. Pruning does not update the integrated registry cache. Images that still contain pruned layers after pruning will be broken because the pruned layers that have metadata in the cache will not be pushed. Therefore, you must redeploy the registry to clear the cache after pruning: -+ -[source,terminal] ----- -$ oc rollout restart deployment/image-registry -n openshift-image-registry ----- -+ -If the integrated registry uses a Redis cache, you must clean the database manually. -+ -If redeploying the registry after pruning is not an option, then you must permanently disable the cache. -+ -`oc adm prune images` operations require a route for your registry. Registry routes are not created by default. -+ -The *Prune images CLI configuration options* table describes the options you can use with the `oc adm prune images <options>` command. -+ -.Prune images CLI configuration options -[cols="4,8",options="header"] -|=== - -|Option |Description - -.^|`--all` -|Include images that were not pushed to the registry, but have been mirrored by -pullthrough. This is on by default. To limit the pruning to images that were -pushed to the integrated registry, pass `--all=false`. - -.^|`--certificate-authority` -|The path to a certificate authority file to use when communicating with the -{product-title}-managed registries. Defaults to the certificate authority data -from the current user's configuration file. If provided, a secure connection is -initiated. - -.^|`--confirm` -|Indicate that pruning should occur, instead of performing a test-run. This -requires a valid route to the integrated container image registry. If this -command is run outside of the cluster network, the route must be provided -using `--registry-url`. - -.^|`--force-insecure` -|Use caution with this option. Allow an insecure connection to the container -registry that is hosted via HTTP or has an invalid HTTPS certificate. - -.^|`--keep-tag-revisions=<N>` -|For each imagestream, keep up to at most `N` image revisions per tag (default -`3`). - -.^|`--keep-younger-than=<duration>` -|Do not prune any image that is younger than `<duration>` relative to the -current time. Alternately, do not prune any image that is referenced by any other object that -is younger than `<duration>` relative to the current time (default `60m`). - -.^|`--prune-over-size-limit` -|Prune each image that exceeds the smallest limit defined in the same project. -This flag cannot be combined with `--keep-tag-revisions` nor -`--keep-younger-than`. - -.^|`--registry-url` -|The address to use when contacting the registry. The command attempts to use a -cluster-internal URL determined from managed images and image streams. In case -it fails (the registry cannot be resolved or reached), an alternative route that -works needs to be provided using this flag. The registry host name can be -prefixed by `https://` or `http://`, which enforces particular connection -protocol. - -.^|`--prune-registry` -|In conjunction with the conditions stipulated by the other options, this option -controls whether the data in the registry corresponding to the {product-title} -image API object is pruned. By default, image pruning processes both the image -API objects and corresponding data in the registry. - -This option is useful when you are only concerned with removing etcd content, to reduce the number of image objects but are not concerned with cleaning up registry storage, or if you intend to do that separately by hard pruning the registry during an appropriate maintenance window for the registry. -|=== - -[id="pruning-images-conditions_{context}"] -== Image prune conditions - -You can apply conditions to your manually pruned images. - -* To remove any image managed by {product-title}, or images with the annotation `openshift.io/image.managed`: -** Created at least `--keep-younger-than` minutes ago and are not currently referenced by any: -*** Pods created less than `--keep-younger-than` minutes ago -*** Image streams created less than `--keep-younger-than` minutes ago -*** Running pods -*** Pending pods -*** Replication controllers -*** Deployments -*** Deployment configs -*** Replica sets -*** Build configurations -*** Builds -*** `--keep-tag-revisions` most recent items in `stream.status.tags[].items` -** That are exceeding the smallest limit defined in the same project and are not currently referenced by any: -*** Running pods -*** Pending pods -*** Replication controllers -*** Deployments -*** Deployment configs -*** Replica sets -*** Build configurations -*** Builds -* There is no support for pruning from external registries. -* When an image is pruned, all references to the image are removed from all -image streams that have a reference to the image in `status.tags`. -* Image layers that are no longer referenced by any images are removed. - -[NOTE] -==== -The `--prune-over-size-limit` flag cannot be combined with the `--keep-tag-revisions` flag nor the `--keep-younger-than` flags. Doing so returns -information that this operation is not allowed. -==== - -Separating the removal of {product-title} image API objects and image data from the registry by using `--prune-registry=false`, followed by hard pruning the registry, can narrow timing windows and is safer when compared to trying to prune both through one command. However, timing windows are not completely removed. - -For example, you can still create a Pod referencing an image as pruning identifies that image for pruning. You should still keep track of an API object created during the pruning operations that might reference images so that you can mitigate any references to deleted content. - -Re-doing the pruning without the `--prune-registry` option or with `--prune-registry=true` does not lead to pruning the associated storage in the image registry for images previously pruned by `--prune-registry=false`. Any images that were pruned with `--prune-registry=false` can only be deleted from registry storage by hard pruning the registry. - -[id="pruning-images-running-operation_{context}"] -== Running the image prune operation - -.Procedure - -. To see what a pruning operation would delete: - -.. Keeping up to three tag revisions, and keeping resources (images, image streams, and pods) younger than 60 minutes: -+ -[source,terminal] ----- -$ oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m ----- - -.. Pruning every image that exceeds defined limits: -+ -[source,terminal] ----- -$ oc adm prune images --prune-over-size-limit ----- - -. To perform the prune operation with the options from the previous step: -+ -[source,terminal] ----- -$ oc adm prune images --keep-tag-revisions=3 --keep-younger-than=60m --confirm ----- -+ -[source,terminal] ----- -$ oc adm prune images --prune-over-size-limit --confirm ----- - -[id="pruning-images-secure-insecure_{context}"] -== Using secure or insecure connections - -The secure connection is the preferred and recommended approach. It is done over -HTTPS protocol with a mandatory certificate verification. The `prune` command -always attempts to use it if possible. If it is not possible, in some cases it -can fall-back to insecure connection, which is dangerous. In this case, either -certificate verification is skipped or plain HTTP protocol is used. - -The fall-back to insecure connection is allowed in the following cases unless -`--certificate-authority` is specified: - -. The `prune` command is run with the `--force-insecure` option. -. The provided `registry-url` is prefixed with the `http://` scheme. -. The provided `registry-url` is a local-link address or `localhost`. -. The configuration of the current user allows for an insecure connection. This -can be caused by the user either logging in using `--insecure-skip-tls-verify` -or choosing the insecure connection when prompted. - -[IMPORTANT] -==== -If the registry is secured by a certificate authority different from the one used by {product-title}, it must be specified using the -`--certificate-authority` flag. Otherwise, the `prune` command fails with an error. -==== - -[id="pruning-images-problems_{context}"] -== Image pruning problems - -[discrete] -[id="pruning-images-not-being-pruned_{context}"] -==== Images not being pruned - -If your images keep accumulating and the `prune` command removes just a small -portion of what you expect, ensure that you understand the image prune -conditions that must apply for an image to be considered a candidate for -pruning. - -Ensure that images you want removed occur at higher positions in each tag -history than your chosen tag revisions threshold. For example, consider an old -and obsolete image named `sha:abz`. By running the following command in -namespace `N`, where the image is tagged, the image is tagged three times in a -single image stream named `myapp`: - -[source,terminal] ----- -$ oc get is -n N -o go-template='{{range $isi, $is := .items}}{{range $ti, $tag := $is.status.tags}}'\ - '{{range $ii, $item := $tag.items}}{{if eq $item.image "'"sha:abz"\ - $'"}}{{$is.metadata.name}}:{{$tag.tag}} at position {{$ii}} out of {{len $tag.items}}\n'\ - '{{end}}{{end}}{{end}}{{end}}' ----- - -.Example output -[source,terminal] ----- -myapp:v2 at position 4 out of 5 -myapp:v2.1 at position 2 out of 2 -myapp:v2.1-may-2016 at position 0 out of 1 ----- - -When default options are used, the image is never pruned because it occurs at -position `0` in a history of `myapp:v2.1-may-2016` tag. For an image to be -considered for pruning, the administrator must either: - -* Specify `--keep-tag-revisions=0` with the `oc adm prune images` command. -+ -[WARNING] -==== -This action removes all the tags from all the namespaces with underlying images, unless they are younger or they are referenced by objects younger than the specified threshold. -==== - -* Delete all the `istags` where the position is below the revision threshold, -which means `myapp:v2.1` and `myapp:v2.1-may-2016`. - -* Move the image further in the history, either by running new builds pushing to -the same `istag`, or by tagging other image. This is not always -desirable for old release tags. - -Tags having a date or time of a particular image's build in their names should -be avoided, unless the image must be preserved for an undefined amount of time. -Such tags tend to have just one image in their history, which prevents -them from ever being pruned. - -[discrete] -[id="pruning-images-secure-against-insecure_{context}"] -==== Using a secure connection against insecure registry - -If you see a message similar to the following in the output of the `oc adm prune images` -command, then your registry is not secured and the `oc adm prune images` -client attempts to use a secure connection: - -[source,terminal] ----- -error: error communicating with registry: Get https://172.30.30.30:5000/healthz: http: server gave HTTP response to HTTPS client ----- - -* The recommended solution is to secure the registry. Otherwise, you can force the -client to use an insecure connection by appending `--force-insecure` to the -command; however, this is not recommended. - -[discrete] -[id="pruning-images-insecure-against-secure_{context}"] -==== Using an insecure connection against a secured registry - -If you see one of the following errors in the output of the `oc adm prune images` -command, it means that your registry is secured using a certificate signed by a -certificate authority other than the one used by `oc adm prune images` client for -connection verification: - -[source,terminal] ----- -error: error communicating with registry: Get http://172.30.30.30:5000/healthz: malformed HTTP response "\x15\x03\x01\x00\x02\x02" -error: error communicating with registry: [Get https://172.30.30.30:5000/healthz: x509: certificate signed by unknown authority, Get http://172.30.30.30:5000/healthz: malformed HTTP response "\x15\x03\x01\x00\x02\x02"] ----- - -By default, the certificate authority data stored in the user's configuration files is used; the same is true for communication with the master API. - -Use the `--certificate-authority` option to provide the right certificate authority for the container image registry server. - -[discrete] -[id="pruning-images-wrong-ca_{context}"] -==== Using the wrong certificate authority - -The following error means that the certificate authority used to sign the certificate of the secured container image registry is different from the authority used by the client: - -[source,terminal] ----- -error: error communicating with registry: Get https://172.30.30.30:5000/: x509: certificate signed by unknown authority ----- - -Make sure to provide the right one with the flag `--certificate-authority`. - -As a workaround, the `--force-insecure` flag can be added instead. However, this is not recommended. diff --git a/modules/pruning-images.adoc b/modules/pruning-images.adoc deleted file mode 100644 index 908e265be5a4..000000000000 --- a/modules/pruning-images.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/pruning-objects.adoc - -[id="pruning-images_{context}"] -= Automatically pruning images - -Images that are no longer required by the system due to age, -status, or exceed limits are automatically pruned. Cluster administrators can configure the Pruning Custom Resource, or suspend it. - -.Prerequisites - -* Cluster administrator permissions. -* Install the `oc` CLI. - -.Procedure - -* Verify that the object named `imagepruners.imageregistry.operator.openshift.io/cluster` contains the following `spec` and `status` fields: - -[source,yaml] ----- -spec: - schedule: 0 0 * * * <1> - suspend: false <2> - keepTagRevisions: 3 <3> - keepYoungerThanDuration: 60m <4> - keepYoungerThan: 3600000000000 <5> - resources: {} <6> - affinity: {} <7> - nodeSelector: {} <8> - tolerations: [] <9> - successfulJobsHistoryLimit: 3 <10> - failedJobsHistoryLimit: 3 <11> -status: - observedGeneration: 2 <12> - conditions: <13> - - type: Available - status: "True" - lastTransitionTime: 2019-10-09T03:13:45 - reason: Ready - message: "Periodic image pruner has been created." - - type: Scheduled - status: "True" - lastTransitionTime: 2019-10-09T03:13:45 - reason: Scheduled - message: "Image pruner job has been scheduled." - - type: Failed - staus: "False" - lastTransitionTime: 2019-10-09T03:13:45 - reason: Succeeded - message: "Most recent image pruning job succeeded." ----- -<1> `schedule`: `CronJob` formatted schedule. This is an optional field, default is daily at midnight. -<2> `suspend`: If set to `true`, the `CronJob` running pruning is suspended. This is an optional field, default is `false`. The initial value on new clusters is `false`. -<3> `keepTagRevisions`: The number of revisions per tag to keep. This is an optional field, default is `3`. The initial value is `3`. -<4> `keepYoungerThanDuration`: Retain images younger than this duration. This is an optional field. If a value is not specified, either `keepYoungerThan` or the default value `60m` (60 minutes) is used. -<5> `keepYoungerThan`: Deprecated. The same as `keepYoungerThanDuration`, but the duration is specified as an integer in nanoseconds. This is an optional field. When `keepYoungerThanDuration` is set, this field is ignored. -<6> `resources`: Standard Pod resource requests and limits. This is an optional field. -<7> `affinity`: Standard Pod affinity. This is an optional field. -<8> `nodeSelector`: Standard Pod node selector. This is an optional field. -<9> `tolerations`: Standard Pod tolerations. This is an optional field. -<10> `successfulJobsHistoryLimit`: The maximum number of successful jobs to retain. Must be `>= 1` to ensure metrics are reported. This is an optional field, default is `3`. The initial value is `3`. -<11> `failedJobsHistoryLimit`: The maximum number of failed jobs to retain. Must be `>= 1` to ensure metrics are reported. This is an optional field, default is `3`. The initial value is `3`. -<12> `observedGeneration`: The generation observed by the Operator. -<13> `conditions`: The standard condition objects with the following types: -* `Available`: Indicates if the pruning job has been created. Reasons can be Ready or Error. -* `Scheduled`: Indicates if the next pruning job has been scheduled. Reasons can be Scheduled, Suspended, or Error. -* `Failed`: Indicates if the most recent pruning job failed. - - -[IMPORTANT] -==== -The Image Registry Operator's behavior for managing the pruner is orthogonal to the `managementState` specified on the Image Registry Operator's `ClusterOperator` object. If the Image Registry Operator is not in the `Managed` state, the image pruner can still be configured and managed by the Pruning Custom Resource. - -However, the `managementState` of the Image Registry Operator alters the behavior of the deployed image pruner job: - -* `Managed`: the `--prune-registry` flag for the image pruner is set to `true`. -* `Removed`: the `--prune-registry` flag for the image pruner is set to `false`, meaning it only prunes image metatdata in etcd. -* `Unmanaged`: the `--prune-registry` flag for the image pruner is set to `false`. -==== diff --git a/modules/quay-keyless-eso.adoc b/modules/quay-keyless-eso.adoc new file mode 100644 index 000000000000..abc0fa83ec15 --- /dev/null +++ b/modules/quay-keyless-eso.adoc @@ -0,0 +1,113 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-image-registries.adoc +:_mod-docs-content-type: PROCEDURE +[id="quay-keyless-eso_{context}"] += Enabling Quay registry keyless authentication using external secret + +For validating images stored in Quay private registries, you can configure {product-title-short} to use keyless authentication with Red{nbsp}Hat Quay registries. This method uses the External Secrets Operator (ESO) and OpenID Connect (OIDC) federation. + +.Prerequisites + +* You have enabled delegated scanning in {product-title-short}. For more information, see "Accessing delegated image scanning" in the "Additional resources" section. +* The Central endpoint configured for the Secured Cluster `centralEndpoint: central.stackrox:443` or similar. +* A robot account created in Red{nbsp}Hat Quay with OIDC federation configured. ++ +-- +* The issuer URL in the Quay robot identity federation configuration must match the service account token issuer of your {ocp} cluster. +* The `sub claim` subject must match the service account name and namespace that you configure in your cluster. +-- ++ +See the link:https://docs.redhat.com/en/documentation/red_hat_quay/latest/html/about_quay_io/allow-robot-access-user-repo[Red Hat Quay Robot Account overview] topic in Quay documentation for more information. + +.Procedure + +. In your Quay instance, navigate to your robot account settings and configure OIDC federation. ++ +Ensure the *Issuer URL* and *Subject* fields are correctly set to match your {ocp} service account that ESO uses. See the link:https://docs.redhat.com/en/documentation/red_hat_quay/latest/html/about_quay_io/allow-robot-access-user-repo#setting-robot-federation[Setting up robot account federation] topic in the Red Hat Quay documentation for more information. + +. If ESO is not already present in your cluster, install it using Helm or another preferred method. ++ +[source,terminal,subs="+attributes"] +---- +$ helm repo add external-secrets https://charts.external-secrets.io +helm install external-secrets \ + external-secrets/external-secrets \ + -n external-secrets \ + --create-namespace +---- + +. Define and apply the following Kubernetes resources. This example creates a `ServiceAccount` resource, a `QuayAccessToken` generator resource provided by the ESO installation, and an `ExternalSecret` resource that uses the generator to create a `kubernetes.io/dockerconfigjson` secret in the specified namespace. ++ +[IMPORTANT] +==== +Update the `robotAccount` field in the `QuayAccessToken` resource to match the name of your Quay robot account. +==== ++ +[source,yaml] +---- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: quay + namespace: quay +--- +apiVersion: generators.external-secrets.io/v1alpha1 +kind: QuayAccessToken +metadata: + name: quay-token + namespace: quay +spec: + url: quay.io + robotAccount: keyless+account # <1> + serviceAccountRef: + name: quay + namespace: quay +--- +apiVersion: external-secrets.io/v1beta1 +kind: ExternalSecret +metadata: + name: quay-credentials + namespace: quay +spec: + dataFrom: + - sourceRef: + generatorRef: + apiVersion: generators.external-secrets.io/v1alpha1 + kind: QuayAccessToken + name: quay-token + refreshInterval: 55m + target: + name: quay-credentials + template: + type: kubernetes.io/dockerconfigjson + data: + .dockerconfigjson: | + { + "auths": { + "{{ .registry }}": { + "auth": "{{ .auth }}" + } + } + } +---- +<1> Replace `keyless+account` with the actual name of your Quay robot account. + +.Verification + +* Confirm that ESO has successfully created a secret named `quay-credentials` of type `kubernetes.io/dockerconfigjson` in the specified namespace. ++ +[source,terminal] +---- +$ kubectl get secret quay-credentials -n quay -o yaml +---- + +The keyless authentication method supports image scanning by using **delegated scanning**. + +* Use delegated image scanning by running the following command: ++ +[source,terminal] +---- +$ roxctl image scan <image_name> --namespace=<namespace_where_secret_exists> <1> +---- +<1> Specify the image name and namespace where you created the secret. diff --git a/modules/querying-bootstrap-node-journal-logs.adoc b/modules/querying-bootstrap-node-journal-logs.adoc deleted file mode 100644 index e634e20fe6c4..000000000000 --- a/modules/querying-bootstrap-node-journal-logs.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/gathering-cluster-data.adoc - -[id="querying-bootstrap-node-journal-logs_{context}"] -= Querying bootstrap node journal logs - -If you experience bootstrap-related issues, you can gather `bootkube.service` `journald` unit logs and container logs from the bootstrap node. - -.Prerequisites - -* You have SSH access to your bootstrap node. -* You have the fully qualified domain name of the bootstrap node. - -.Procedure - -. Query `bootkube.service` `journald` unit logs from a bootstrap node during {product-title} installation. Replace `<bootstrap_fqdn>` with the bootstrap node's fully qualified domain name: -+ -[source,terminal] ----- -$ ssh core@<bootstrap_fqdn> journalctl -b -f -u bootkube.service ----- -+ -[NOTE] -==== -The `bootkube.service` log on the bootstrap node outputs etcd `connection refused` errors, indicating that the bootstrap server is unable to connect to etcd on master nodes. After etcd has started on each master node and the nodes have joined the cluster, the errors should stop. -==== -+ -. Collect logs from the bootstrap node containers using `podman` on the bootstrap node. Replace `<bootstrap_fqdn>` with the bootstrap node's fully qualified domain name: -+ -[source,terminal] ----- -$ ssh core@<bootstrap_fqdn> 'for pod in $(sudo podman ps -a -q); do sudo podman logs $pod; done' ----- diff --git a/modules/querying-cluster-node-journal-logs.adoc b/modules/querying-cluster-node-journal-logs.adoc deleted file mode 100644 index deb58270f765..000000000000 --- a/modules/querying-cluster-node-journal-logs.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc -// * support/troubleshooting/verifying-node-health.adoc - -[id="querying-cluster-node-journal-logs_{context}"] -= Querying cluster node journal logs - -You can gather `journald` unit logs and other logs within `/var/log` on individual cluster nodes. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). -* You have SSH access to your hosts. - -.Procedure - -. Query `kubelet` `journald` unit logs from {product-title} cluster nodes. The following example queries master nodes only: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master -u kubelet <1> ----- -<1> Replace `kubelet` as appropriate to query other unit logs. - -. Collect logs from specific subdirectories under `/var/log/` on cluster nodes. -.. Retrieve a list of logs contained within a `/var/log/` subdirectory. The following example lists files in `/var/log/openshift-apiserver/` on all master nodes: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master --path=openshift-apiserver ----- -+ -.. Inspect a specific log within a `/var/log/` subdirectory. The following example outputs `/var/log/openshift-apiserver/audit.log` contents from all master nodes: -+ -[source,terminal] ----- -$ oc adm node-logs --role=master --path=openshift-apiserver/audit.log ----- -+ -.. If the API is not functional, review the logs on each node using SSH instead. The following example tails `/var/log/openshift-apiserver/audit.log`: -+ -[source,terminal] ----- -$ ssh core@<master-node>.<cluster_name>.<base_domain> sudo tail -f /var/log/openshift-apiserver/audit.log ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. Before attempting to collect diagnostic data over SSH, review whether the data collected by running `oc adm must gather` and other `oc` commands is sufficient instead. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>`. -==== diff --git a/modules/querying-external-entities-using-api.adoc b/modules/querying-external-entities-using-api.adoc new file mode 100644 index 000000000000..74dccabaddad --- /dev/null +++ b/modules/querying-external-entities-using-api.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/visualizing-external-entities.adoc +:_mod-docs-content-type: REFERENCE +[id="querying-external-entities-using-api_{context}"] += Querying external IP addresses by using the API + +[role="_abstract"] +You can get information about the external IP addresses associated with a specific cluster by using the following endpoints: + +* `/v1/networkgraph/cluster/{clusterId}/externalentities`: This endpoint returns a list of external entities for a given cluster ID. Each entity includes the following information: ++ +** *Name*: The name of the external entity. +** *CIDR block*: The CIDR block associated with the entity. +** *Default entity*: Indicates that the entity is a CIDR-block definition provided by the system. +** *Discovered*: If `true`, indicates that the external IP address does not match any specified CIDR block. +* `/v1/networkgraph/cluster/{clusterId}/externalentities/{entityId}/flows`: This endpoint reports the flows to and from an external entity for a given cluster ID and entity ID. Use this endpoint to analyze network traffic patterns and gain insights into the interactions between your cluster and external entities. +* `/v1/networkgraph/cluster/{clusterId}/externalentities/metadata`: This endpoint reports statistics about the external flows for a given cluster ID. It reports details about each entity, as well as the number of flows associated with it. diff --git a/modules/querying-kubelet-status-on-a-node.adoc b/modules/querying-kubelet-status-on-a-node.adoc deleted file mode 100644 index 06ca8c475d42..000000000000 --- a/modules/querying-kubelet-status-on-a-node.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/verifying-node-health.adoc - -[id="querying-kubelet-status-on-a-node_{context}"] -= Querying the kubelet's status on a node - -You can review cluster node health status, resource consumption statistics, and node logs. Additionally, you can query `kubelet` status on individual nodes. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. The kubelet is managed using a systemd service on each node. Review the kubelet's status by querying the `kubelet` systemd service within a debug pod. -.. Start a debug pod for a node: -+ -[source,terminal] ----- -$ oc debug node/my-node ----- -+ -.. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- -+ -[NOTE] -==== -{product-title} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or `kubelet` is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead. -==== -+ -.. Check whether the `kubelet` systemd service is active on the node: -+ -[source,terminal] ----- -# systemctl is-active kubelet ----- -+ -.. Output a more detailed `kubelet.service` status summary: -+ -[source,terminal] ----- -# systemctl status kubelet ----- diff --git a/modules/querying-operator-pod-status.adoc b/modules/querying-operator-pod-status.adoc deleted file mode 100644 index 1088d8486bd5..000000000000 --- a/modules/querying-operator-pod-status.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-operator-issues.adoc - -[id="querying-operator-pod-status_{context}"] -= Querying Operator pod status - -You can list Operator pods within a cluster and their status. You can also collect a detailed Operator pod summary. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. List Operators running in the cluster. The output includes Operator version, availability, and up-time information: -+ -[source,terminal] ----- -$ oc get clusteroperators ----- - -. List Operator pods running in the Operator's namespace, plus pod status, restarts, and age: -+ -[source,terminal] ----- -$ oc get pod -n <operator_namespace> ----- - -. Output a detailed Operator pod summary: -+ -[source,terminal] ----- -$ oc describe pod <operator_pod_name> -n <operator_namespace> ----- - -. If an Operator issue is node-specific, query Operator container status on that node. -.. Start a debug pod for the node: -+ -[source,terminal] ----- -$ oc debug node/my-node ----- -+ -.. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead. -==== -+ -.. List details about the node's containers, including state and associated pod IDs: -+ -[source,terminal] ----- -# crictl ps ----- -+ -.. List information about a specific Operator container on the node. The following example lists information about the `network-operator` container: -+ -[source,terminal] ----- -# crictl ps --name network-operator ----- -+ -.. Exit from the debug shell. diff --git a/modules/querying-operator-status-after-installation.adoc b/modules/querying-operator-status-after-installation.adoc deleted file mode 100644 index 3cccfe9d19eb..000000000000 --- a/modules/querying-operator-status-after-installation.adoc +++ /dev/null @@ -1,115 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="querying-operator-status-after-installation_{context}"] -= Querying Operator status after installation - -You can check Operator status at the end of an installation. Retrieve diagnostic data for Operators that do not become available. Review logs for any Operator pods that are listed as `Pending` or have an error status. Validate base images used by problematic pods. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Check that cluster Operators are all available at the end of an installation. -+ -[source,terminal] ----- -$ oc get clusteroperators ----- - -. Verify that all of the required certificate signing requests (CSRs) are approved. Some nodes might not move to a `Ready` status and some cluster Operators might not become available if there are pending CSRs. -.. Check the status of the CSRs and ensure that you see a client and server request with the `Pending` or `Approved` status for each machine that you added to the cluster: -+ -[source,terminal] ----- -$ oc get csr ----- -+ -.Example output -[source,terminal] ----- -NAME AGE REQUESTOR CONDITION -csr-8b2br 15m system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending <1> -csr-8vnps 15m system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending -csr-bfd72 5m26s system:node:ip-10-0-50-126.us-east-2.compute.internal Pending <2> -csr-c57lv 5m26s system:node:ip-10-0-95-157.us-east-2.compute.internal Pending -... ----- -<1> A client request CSR. -<2> A server request CSR. -+ -In this example, two machines are joining the cluster. You might see more approved CSRs in the list. - -.. If the CSRs were not approved, after all of the pending CSRs for the machines you added are in `Pending` status, approve the CSRs for your cluster machines: -+ -[NOTE] -==== -Because the CSRs rotate automatically, approve your CSRs within an hour of adding the machines to the cluster. If you do not approve them within an hour, the certificates will rotate, and more than two certificates will be present for each node. You must approve all of these certificates. After you approve the initial CSRs, the subsequent node client CSRs are automatically approved by the cluster `kube-controller-manager`. -==== -+ -[NOTE] -==== -For clusters running on platforms that are not machine API enabled, such as bare metal and other user-provisioned infrastructure, you must implement a method of automatically approving the kubelet serving certificate requests (CSRs). If a request is not approved, then the `oc exec`, `oc rsh`, and `oc logs` commands cannot succeed, because a serving certificate is required when the API server connects to the kubelet. Any operation that contacts the Kubelet endpoint requires this certificate approval to be in place. The method must watch for new CSRs, confirm that the CSR was submitted by the `node-bootstrapper` service account in the `system:node` or `system:admin` groups, and confirm the identity of the node. -==== - -** To approve them individually, run the following command for each valid CSR: -+ -[source,terminal] ----- -$ oc adm certificate approve <csr_name> <1> ----- -<1> `<csr_name>` is the name of a CSR from the list of current CSRs. - -** To approve all pending CSRs, run the following command: -+ -[source,terminal] ----- -$ oc get csr -o go-template='{{range .items}}{{if not .status}}{{.metadata.name}}{{"\n"}}{{end}}{{end}}' | xargs oc adm certificate approve ----- - -. View Operator events: -+ -[source,terminal] ----- -$ oc describe clusteroperator <operator_name> ----- - -. Review Operator pod status within the Operator's namespace: -+ -[source,terminal] ----- -$ oc get pods -n <operator_namespace> ----- - -. Obtain a detailed description for pods that do not have `Running` status: -+ -[source,terminal] ----- -$ oc describe pod/<operator_pod_name> -n <operator_namespace> ----- - -. Inspect pod logs: -+ -[source,terminal] ----- -$ oc logs pod/<operator_pod_name> -n <operator_namespace> ----- - -. When experiencing pod base image related issues, review base image status. -.. Obtain details of the base image used by a problematic pod: -+ -[source,terminal] ----- -$ oc get pod -o "jsonpath={range .status.containerStatuses[*]}{.name}{'\t'}{.state}{'\t'}{.image}{'\n'}{end}" <operator_pod_name> -n <operator_namespace> ----- -+ -.. List base image release information: -+ -[source,terminal] ----- -$ oc adm release info <image_path>:<tag> --commits ----- diff --git a/modules/querying-the-status-of-cluster-nodes-using-the-cli.adoc b/modules/querying-the-status-of-cluster-nodes-using-the-cli.adoc deleted file mode 100644 index bffe85ac4358..000000000000 --- a/modules/querying-the-status-of-cluster-nodes-using-the-cli.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc - -[id="querying-the-status-of-cluster-nodes-using-the-cli_{context}"] -= Querying the status of the cluster nodes by using the CLI - -You can verify the status of the cluster nodes after an installation. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. List the status of the cluster nodes. Verify that the output lists all of the expected control plane and compute nodes and that each node has a `Ready` status: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -compute-1.example.com Ready worker 33m v1.19.0+9f84db3 -control-plane-1.example.com Ready master 41m v1.19.0+9f84db3 -control-plane-2.example.com Ready master 45m v1.19.0+9f84db3 -compute-2.example.com Ready worker 38m v1.19.0+9f84db3 -compute-3.example.com Ready worker 33m v1.19.0+9f84db3 -control-plane-3.example.com Ready master 41m v1.19.0+9f84db3 ----- - -. Review CPU and memory resource availability for each cluster node: -+ -[source,terminal] ----- -$ oc adm top nodes ----- -+ -.Example output -[source,terminal] ----- -NAME CPU(cores) CPU% MEMORY(bytes) MEMORY% -compute-1.example.com 128m 8% 1132Mi 16% -control-plane-1.example.com 801m 22% 3471Mi 23% -control-plane-2.example.com 1718m 49% 6085Mi 40% -compute-2.example.com 935m 62% 5178Mi 75% -compute-3.example.com 111m 7% 1131Mi 16% -control-plane-3.example.com 942m 26% 4100Mi 27% ----- diff --git a/modules/quick-start-adding-custom-icon.adoc b/modules/quick-start-adding-custom-icon.adoc deleted file mode 100644 index 5ab50afa3c2d..000000000000 --- a/modules/quick-start-adding-custom-icon.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="adding-custom-icon-to-quick-start_{context}"] -= Adding a custom icon to a quick start - -A default icon is provided for all quick starts. You can provide your own custom icon. - -.Procedure - -. Find the `.svg` file that you want to use as your custom icon. -. Use an link:https://cryptii.com/pipes/text-to-base64[online tool to convert the text to base64]. -. In the YAML file, add `icon: >-`, then on the next line include `data:image/svg+xml;base64` followed by the output from the base64 conversion. For example: -+ -[source,yaml] ----- -icon: >- - data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHJvbGU9ImltZyIgdmlld. ----- diff --git a/modules/quick-start-components.adoc b/modules/quick-start-components.adoc deleted file mode 100644 index 4d34ee2e17cf..000000000000 --- a/modules/quick-start-components.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="quick-start-components_{context}"] -= Quick start components - -A quick start consists of the following sections: - -* *Card*: The catalog tile that provides the basic information of the quick start, including title, description, time commitment, and completion status -* *Introduction*: A brief overview of the goal and tasks of the quick start -* *Task headings*: Hyper-linked titles for each task in the quick start -* *Check your work module*: A module for a user to confirm that they completed a task successfully before advancing to the next task in the quick start -* *Hints*: An animation to help users identify specific areas of the product -* *Buttons* -** *Next and back buttons*: Buttons for navigating the steps and modules within each task of a quick start -** *Final screen buttons*: Buttons for closing the quick start, going back to previous tasks within the quick start, and viewing all quick starts - -The main content area of a quick start includes the following sections: - -* *Card copy* -* *Introduction* -* *Task steps* -* *Modals and in-app messaging* -* *Check your work module* diff --git a/modules/quick-start-content-guidelines.adoc b/modules/quick-start-content-guidelines.adoc deleted file mode 100644 index 20d1bef5edb8..000000000000 --- a/modules/quick-start-content-guidelines.adoc +++ /dev/null @@ -1,160 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="quick-start-content-guidelines_{context}"] -= Quick start content guidelines - -[id="quick-start-content-guidelines-card-copy_{context}"] -== Card copy - -You can customize the title and description on a quick start card, but you cannot customize the status. - -* Keep your description to one to two sentences. -* Start with a verb and communicate the goal of the user. Correct example: -+ ----- -Create a serverless application. ----- - -[id="quick-start-content-guidelines-introduction_{context}"] -== Introduction - -After clicking a quick start card, a side panel slides in that introduces the quick start and lists the tasks within it. - -* Make your introduction content clear, concise, informative, and friendly. -* State the outcome of the quick start. A user should understand the purpose of the quick start before they begin. -* Give action to the user, not the quick start. -** *Correct example*: -+ ----- -In this quick start, you will deploy a sample application to {product-title}. ----- -** *Incorrect example*: -+ ----- -This quick start shows you how to deploy a sample application to {product-title}. ----- -* The introduction should be a maximum of four to five sentences, depending on the complexity of the feature. A long introduction can overwhelm the user. -* List the quick start tasks after the introduction content, and start each task with a verb. Do not specify the number of tasks because the copy would need to be updated every time a task is added or removed. -** *Correct example*: -+ ----- -Tasks to complete: Create a serverless application; Connect an event source; Force a new revision ----- -** *Incorrect example*: -+ ----- -You will complete these 3 tasks: Creating a serverless application; Connecting an event source; Forcing a new revision ----- - -[id="quick-start-content-guidelines-task-steps_{context}"] -== Task steps - -After the user clicks *Start*, a series of steps appears that they must perform to complete the quick start. - -Follow these general guidelines when writing task steps: - -* Use "Click" for buttons and labels. Use "Select" for checkboxes, radio buttons, and drop-down menus. -* Use "Click" instead of "Click on" -** *Correct example*: -+ ----- -Click OK. ----- -** *Incorrect example*: -+ ----- -Click on the OK button. ----- - -* Tell users how to navigate between *Administrator* and *Developer* perspectives. Even if you think a user might already be in the appropriate perspective, give them instructions on how to get there so that they are definitely where they need to be. -+ -Examples: -+ ----- -Enter the Developer perspective: In the main navigation, click the dropdown menu and select Developer. -Enter the Administrator perspective: In the main navigation, click the dropdown menu and select Admin. ----- - -* Use the "Location, action" structure. Tell a user where to go before telling them what to do. -** *Correct example*: -+ ----- -In the node.js deployment, hover over the icon. ----- -** *Incorrect example*: -+ ----- -Hover over the icon in the node.js deployment. ----- - -* Keep your product terminology capitalization consistent. -* If you must specify a menu type or list as a dropdown, write "dropdown” as one word without a hyphen. -* Clearly distinguish between a user action and additional information on product functionality. -** *User action*: -+ ----- -Change the time range of the dashboard by clicking the dropdown menu and selecting time range. ----- -** *Additional information*: -+ ----- -To look at data in a specific time frame, you can change the time range of the dashboard. ----- - -* Avoid directional language, like "In the top-right corner, click the icon". Directional language becomes outdated every time UI layouts change. Also, a direction for desktop users might not be accurate for users with a different screen size. Instead, identify something using its name. -** *Correct example*: -+ ----- -In the navigation menu, click Settings. ----- -** *Incorrect example*: -+ ----- -In the left-hand menu, click Settings. ----- -* Do not identify items by color alone, like "Click the gray circle". Color identifiers are not useful for sight-limited users, especially colorblind users. Instead, identify an item using its name or copy, like button copy. -** *Correct example*: -+ ----- -The success message indicates a connection. ----- -** *Incorrect example*: -+ ----- -The message with a green icon indicates a connection. ----- - -* Use the second-person point of view, you, consistently: -** *Correct example*: -+ ----- -Set up your environment. ----- -** *Incorrect example*: -+ ----- -Let’s set up our environment. ----- - -[id="quick-start-content-guidelines-check-your-work-module_{context}"] -== Check your work module - -* After a user completes a step, a *Check your work* module appears. This module prompts the user to answer a yes or no question about the step results, which gives them the opportunity to review their work. For this module, you only need to write a single yes or no question. -** If the user answers *Yes*, a check mark will appear. -** If the user answers *No*, an error message appears with a link to relevant documentation, if necessary. The user then has the opportunity to go back and try again. - -[id="quick-start-content-guidelines-formatting-UI-elements_{context}"] -== Formatting UI elements - -Format UI elements using these guidelines: - -* Copy for buttons, dropdowns, tabs, fields, and other UI controls: Write the copy as it appears in the UI and bold it. -* All other UI elements—including page, window, and panel names: Write the copy as it appears in the UI and bold it. -* Code or user-entered text: Use monospaced font. -* Hints: If a hint to a navigation or masthead element is included, style the text as you would a link. -* CLI commands: Use monospaced font. -* In running text, use a bold, monospaced font for a command. -* If a parameter or option is a variable value, use an italic monospaced font. -* Use a bold, monospaced font for the parameter and a monospaced font for the option. diff --git a/modules/quick-start-limiting-access.adoc b/modules/quick-start-limiting-access.adoc deleted file mode 100644 index e9e2449e4fcc..000000000000 --- a/modules/quick-start-limiting-access.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="limiting-access-to-quick-starts_{context}"] -= Limiting access to a quick start - -Not all quick starts should be available for everyone. The `accessReviewResources` section of the YAML file provides the ability to limit access to the quick start. - -To only allow the user to access the quick start if they have the ability to create `HelmChartRepository` resources, use the following configuration: - -[source,yaml] ----- -accessReviewResources: - - group: helm.openshift.io - resource: helmchartrepositories - verb: create ----- - -To only allow the user to access the quick start if they have the ability to list Operator groups and package manifests, thus ability to install Operators, use the following configuration: - - -[source,yaml] ----- -accessReviewResources: - - group: operators.coreos.com - resource: operatorgroups - verb: list - - group: packages.operators.coreos.com - resource: packagemanifests - verb: list ----- diff --git a/modules/quick-start-user-workflow.adoc b/modules/quick-start-user-workflow.adoc deleted file mode 100644 index 47c2a19ad13b..000000000000 --- a/modules/quick-start-user-workflow.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="quick-start-user-workflow_{context}"] -= Quick start user workflow - -When you interact with an existing quick start tutorial, this is the expected workflow experience: - -. In the *Administrator* or *Developer* perspective, click the *Help icon* and select *Quick Starts*. - -. Click a quick start card. - -. In the panel that appears, click *Start*. - -. Complete the on-screen instructions, then click *Next*. - -. In the *Check your work* module that appears, answer the question to confirm that you successfully completed the task. -.. If you select *Yes*, click *Next* to continue to the next task. -.. If you select *No*, repeat the task instructions and check your work again. - -. Repeat steps 1 through 6 above to complete the remaining tasks in the quick start. -. After completing the final task, click *Close* to close the quick start. diff --git a/modules/quick-starts-linking-to-others.adoc b/modules/quick-starts-linking-to-others.adoc deleted file mode 100644 index 711c64e683e3..000000000000 --- a/modules/quick-starts-linking-to-others.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="linking-to-other-quick-starts_{context}"] -= Linking to other quick starts - -.Procedure - -* In the `nextQuickStart` section of the YAML file, provide the `name`, not the `displayName`, of the quick start to which you want to link. For example: -+ -[source,yaml] ----- -nextQuickStart: - - add-healthchecks ----- diff --git a/modules/quick-starts-supported-tags.adoc b/modules/quick-starts-supported-tags.adoc deleted file mode 100644 index df4274dfd136..000000000000 --- a/modules/quick-starts-supported-tags.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="supported-tags-for-quick-starts_{context}"] -= Supported tags for quick starts - -Write your quick start content in markdown using these tags. The markdown is converted to HTML. - -[cols="2",options="header"] -|=== -|Tag -|Description - -|`'b',` -|Defines bold text. - -|`'img',` -|Embeds an image. - -|`'i',` -|Defines italic text. - -|`'strike',` -|Defines strike-through text. - -|`'s',` -|Defines smaller text - -|`'del',` -|Defines smaller text. - -|`'em',` -|Defines emphasized text. - -|`'strong',` -|Defines important text. - -|`'a',` -|Defines an anchor tag. - -|`'p',` -|Defines paragraph text. - -|`'h1',` -|Defines a level 1 heading. - -|`'h2',` -|Defines a level 2 heading. - -|`'h3',` -|Defines a level 3 heading. - -|`'h4',` -|Defines a level 4 heading. - -|`'ul',` -|Defines an unordered list. - -|`'ol',` -|Defines an ordered list. - -|`'li',` -|Defines a list item. - -|`'code',` -|Defines a text as code. - -|`'pre',` -|Defines a block of preformatted text. - -|`'button',` -|Defines a button in text. -|=== diff --git a/modules/quotas-creating-a-quota.adoc b/modules/quotas-creating-a-quota.adoc deleted file mode 100644 index 7bdde871d8cb..000000000000 --- a/modules/quotas-creating-a-quota.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -[id="quotas-creating-a-quota_{context}"] -= Creating a quota - -You can create a quota to constrain resource usage in a given project. - -.Procedure - -. Define the quota in a file. - -. Use the file to create the quota and apply it to a project: -+ -[source,terminal] ----- -$ oc create -f <file> [-n <project_name>] ----- -+ -For example: -+ -[source,terminal] ----- -$ oc create -f core-object-counts.yaml -n demoproject ----- diff --git a/modules/quotas-creating-object-count-quotas.adoc b/modules/quotas-creating-object-count-quotas.adoc deleted file mode 100644 index 139ca195eefc..000000000000 --- a/modules/quotas-creating-object-count-quotas.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -[id="quota-creating-object-count-quotas_{context}"] -= Creating object count quotas - -You can create an object count quota for all standard namespaced resource types on {product-title}, such as `BuildConfig` and `DeploymentConfig` objects. An object quota count places a defined quota on all standard namespaced resource types. - -When using a resource quota, an object is charged against the quota upon creation. These types of quotas are useful to protect against exhaustion of resources. The quota can only be created if there are enough spare resources within the project. - -.Procedure - -To configure an object count quota for a resource: - -. Run the following command: -+ -[source,terminal] ----- -$ oc create quota <name> \ - --hard=count/<resource>.<group>=<quota>,count/<resource>.<group>=<quota> <1> ----- -<1> The `<resource>` variable is the name of the resource, and `<group>` is the API group, if applicable. Use the `oc api-resources` command for a list of resources and their associated API groups. -+ -For example: -+ -[source,terminal] ----- -$ oc create quota test \ - --hard=count/deployments.extensions=2,count/replicasets.extensions=4,count/pods=3,count/secrets=4 ----- -+ -.Example output -[source,terminal] ----- -resourcequota "test" created ----- -+ -This example limits the listed resources to the hard limit in each project in the cluster. - -. Verify that the quota was created: -+ -[source,terminal] ----- -$ oc describe quota test ----- -+ -.Example output -[source,terminal] ----- -Name: test -Namespace: quota -Resource Used Hard --------- ---- ---- -count/deployments.extensions 0 2 -count/pods 0 3 -count/replicasets.extensions 0 4 -count/secrets 0 4 ----- diff --git a/modules/quotas-enforcement.adoc b/modules/quotas-enforcement.adoc deleted file mode 100644 index 4606f331c1b0..000000000000 --- a/modules/quotas-enforcement.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -[id="quota-enforcement_{context}"] -= Quota enforcement - -After a resource quota for a project is first created, the project restricts the -ability to create any new resources that may violate a quota constraint until it -has calculated updated usage statistics. - -After a quota is created and usage statistics are updated, the project accepts -the creation of new content. When you create or modify resources, your quota -usage is incremented immediately upon the request to create or modify the -resource. - -When you delete a resource, your quota use is decremented during the next full -recalculation of quota statistics for the project. A configurable amount of time -determines how long it takes to reduce quota usage statistics to their current -observed system value. - -If project modifications exceed a quota usage limit, the server denies the -action, and an appropriate error message is returned to the user explaining the -quota constraint violated, and what their currently observed usage statistics -are in the system. diff --git a/modules/quotas-requests-vs-limits.adoc b/modules/quotas-requests-vs-limits.adoc deleted file mode 100644 index 37d4e606093c..000000000000 --- a/modules/quotas-requests-vs-limits.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -[id="quotas-requests-vs-limits_{context}"] -= Requests versus limits - -When allocating compute resources, each container might specify a request and a -limit value each for CPU, memory, and ephemeral storage. Quotas can restrict any -of these values. - -If the quota has a value specified for `requests.cpu` or `requests.memory`, -then it requires that every incoming container make an explicit request for -those resources. If the quota has a value specified for `limits.cpu` or -`limits.memory`, then it requires that every incoming container specify an -explicit limit for those resources. diff --git a/modules/quotas-requiring-explicit-quota.adoc b/modules/quotas-requiring-explicit-quota.adoc deleted file mode 100644 index 31d5905445ca..000000000000 --- a/modules/quotas-requiring-explicit-quota.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -// NOTE: This is currently not configurable in 4.1, removing from 4.1 docs. - -[id="configuring-explicit-resource-quotas_{context}"] -= Configuring explicit resource quotas - -Configure explicit resource quotas in a project request template to apply specific resource quotas in new projects. - -.Prerequisites - -* Access to the cluster as a user with the cluster-admin role. - -* Install the OpenShift CLI (`oc`). - -.Procedure - -. Add a resource quota definition to a project request template: -+ -** If a project request template does not exist in a cluster: -.. Create a bootstrap project template and output it to a file called `template.yaml`: -+ -[source,terminal] ----- -$ oc adm create-bootstrap-project-template -o yaml > template.yaml ----- -+ -.. Add a resource quota definition to `template.yaml`. The following example defines a resource quota named 'storage-consumption'. The definition must be added before the `parameters:` section in the template: -+ -[source,yaml] ----- -- apiVersion: v1 - kind: ResourceQuota - metadata: - name: storage-consumption - spec: - hard: - persistentvolumeclaims: "10" <1> - requests.storage: "50Gi" <2> - gold.storageclass.storage.k8s.io/requests.storage: "10Gi" <3> - silver.storageclass.storage.k8s.io/requests.storage: "20Gi" <4> - silver.storageclass.storage.k8s.io/persistentvolumeclaims: "5" <5> - bronze.storageclass.storage.k8s.io/requests.storage: "0" <6> - bronze.storageclass.storage.k8s.io/persistentvolumeclaims: "0" <7> ----- -<1> The total number of persistent volume claims in a project. -<2> Across all persistent volume claims in a project, the sum of storage requested cannot exceed this value. -<3> Across all persistent volume claims in a project, the sum of storage requested in the gold storage class cannot exceed this value. -<4> Across all persistent volume claims in a project, the sum of storage requested in the silver storage class cannot exceed this value. -<5> Across all persistent volume claims in a project, the total number of claims in the silver storage class cannot exceed this value. -<6> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this value is set to `0`, the bronze storage class cannot request storage. -<7> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this value is set to `0`, the bronze storage class cannot create claims. -+ -.. Create a project request template from the modified `template.yaml` file in the `openshift-config` namespace: -+ -[source,terminal] ----- -$ oc create -f template.yaml -n openshift-config ----- -+ -[NOTE] -==== -To include the configuration as a `kubectl.kubernetes.io/last-applied-configuration` annotation, add the `--save-config` option to the `oc create` command. -==== -+ -By default, the template is called `project-request`. -+ -** If a project request template already exists within a cluster: -+ -[NOTE] -==== -If you declaratively or imperatively manage objects within your cluster by using configuration files, edit the existing project request template through those files instead. -==== -+ -.. List templates in the `openshift-config` namespace: -+ -[source,terminal] ----- -$ oc get templates -n openshift-config ----- -+ -.. Edit an existing project request template: -+ -[source,terminal] ----- -$ oc edit template <project_request_template> -n openshift-config ----- -+ -.. Add a resource quota definition, such as the preceding `storage-consumption` example, into the existing template. The definition must be added before the `parameters:` section in the template. - -. If you created a project request template, reference it in the cluster's project configuration resource: -.. Access the project configuration resource for editing: -+ -** By using the web console: -... Navigate to the *Administration* -> *Cluster Settings* page. -... Click *Global Configuration* to view all configuration resources. -... Find the entry for *Project* and click *Edit YAML*. -+ -** By using the CLI: -... Edit the `project.config.openshift.io/cluster` resource: -+ -[source,terminal] ----- -$ oc edit project.config.openshift.io/cluster ----- -+ -.. Update the `spec` section of the project configuration resource to include the `projectRequestTemplate` and `name` parameters. The following example references the default project request template name `project-request`: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Project -metadata: - ... -spec: - projectRequestTemplate: - name: project-request ----- - -. Verify that the resource quota is applied when projects are created: -.. Create a project: -+ -[source,terminal] ----- -$ oc new-project <project_name> ----- -+ -.. List the project's resource quotas: -+ -[source,terminal] ----- -$ oc get resourcequotas ----- -+ -.. Describe the resource quota in detail: -+ -[source,terminal] ----- -$ oc describe resourcequotas <resource_quota_name> ----- diff --git a/modules/quotas-resources-managed.adoc b/modules/quotas-resources-managed.adoc deleted file mode 100644 index 9b57e7f4dae8..000000000000 --- a/modules/quotas-resources-managed.adoc +++ /dev/null @@ -1,104 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -[id="quotas-resources-managed_{context}"] -= Resources managed by quotas - -The following describes the set of compute resources and object types that can be managed by a quota. - -[NOTE] -==== -A pod is in a terminal state if `status.phase in (Failed, Succeeded)` is true. -==== - -.Compute resources managed by quota -[cols="3a,8a",options="header"] -|=== - -|Resource Name |Description - -|`cpu` -|The sum of CPU requests across all pods in a non-terminal state cannot exceed this value. `cpu` and `requests.cpu` are the same value and can be used interchangeably. - -|`memory` -|The sum of memory requests across all pods in a non-terminal state cannot exceed this value. `memory` and `requests.memory` are the same value and can be used interchangeably. - -|`ephemeral-storage` -|The sum of local ephemeral storage requests across all pods in a non-terminal state cannot exceed this value. `ephemeral-storage` and `requests.ephemeral-storage` are the same value and can be used interchangeably. - -|`requests.cpu` -|The sum of CPU requests across all pods in a non-terminal state cannot exceed this value. `cpu` and `requests.cpu` are the same value and can be used interchangeably. - -|`requests.memory` -|The sum of memory requests across all pods in a non-terminal state cannot exceed this value. `memory` and `requests.memory` are the same value and can be used interchangeably. - -|`requests.ephemeral-storage` -|The sum of ephemeral storage requests across all pods in a non-terminal state cannot exceed this value. `ephemeral-storage` and `requests.ephemeral-storage` are the same value and can be used interchangeably. - -|`limits.cpu` -|The sum of CPU limits across all pods in a non-terminal state cannot exceed this value. - -|`limits.memory` -|The sum of memory limits across all pods in a non-terminal state cannot exceed this value. - -|`limits.ephemeral-storage` -|The sum of ephemeral storage limits across all pods in a non-terminal state cannot exceed this value. -|=== - -.Storage resources managed by quota -[cols="3a,8a",options="header"] -|=== - -|Resource Name |Description - -|`requests.storage` -|The sum of storage requests across all persistent volume claims in any state cannot exceed this value. - -|`persistentvolumeclaims` -|The total number of persistent volume claims that can exist in the project. - -|`<storage-class-name>.storageclass.storage.k8s.io/requests.storage` -|The sum of storage requests across all persistent volume claims in any state that have a matching storage class, cannot exceed this value. - -|`<storage-class-name>.storageclass.storage.k8s.io/persistentvolumeclaims` -|The total number of persistent volume claims with a matching storage class that can exist in the project. -|=== - -[id="quotas-object-counts-managed_{context}"] -.Object counts managed by quota -[cols="3a,8a",options="header"] -|=== - -|Resource Name |Description - -|`pods` -|The total number of pods in a non-terminal state that can exist in the project. - -|`replicationcontrollers` -|The total number of ReplicationControllers that can exist in the project. - -|`resourcequotas` -|The total number of resource quotas that can exist in the project. - -|`services` -|The total number of services that can exist in the project. - -|`services.loadbalancers` -|The total number of services of type `LoadBalancer` that can exist in the project. - -|`services.nodeports` -|The total number of services of type `NodePort` that can exist in the project. - -|`secrets` -|The total number of secrets that can exist in the project. - -|`configmaps` -|The total number of `ConfigMap` objects that can exist in the project. - -|`persistentvolumeclaims` -|The total number of persistent volume claims that can exist in the project. - -|`openshift.io/imagestreams` -|The total number of imagestreams that can exist in the project. -|=== diff --git a/modules/quotas-sample-resource-quotas-def.adoc b/modules/quotas-sample-resource-quotas-def.adoc deleted file mode 100644 index 4dd7ed271913..000000000000 --- a/modules/quotas-sample-resource-quotas-def.adoc +++ /dev/null @@ -1,153 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -[id="quotas-sample-resource-quota-definitions_{context}"] -= Sample resource quota definitions - -.`core-object-counts.yaml` -[source,yaml] ----- -apiVersion: v1 -kind: ResourceQuota -metadata: - name: core-object-counts -spec: - hard: - configmaps: "10" <1> - persistentvolumeclaims: "4" <2> - replicationcontrollers: "20" <3> - secrets: "10" <4> - services: "10" <5> - services.loadbalancers: "2" <6> ----- -<1> The total number of `ConfigMap` objects that can exist in the project. -<2> The total number of persistent volume claims (PVCs) that can exist in the -project. -<3> The total number of replication controllers that can exist in the project. -<4> The total number of secrets that can exist in the project. -<5> The total number of services that can exist in the project. -<6> The total number of services of type `LoadBalancer` that can exist in the project. - -.`openshift-object-counts.yaml` -[source,yaml] ----- -apiVersion: v1 -kind: ResourceQuota -metadata: - name: openshift-object-counts -spec: - hard: - openshift.io/imagestreams: "10" <1> ----- -<1> The total number of image streams that can exist in the project. - -.`compute-resources.yaml` -[source,yaml] ----- -apiVersion: v1 -kind: ResourceQuota -metadata: - name: compute-resources -spec: - hard: - pods: "4" <1> - requests.cpu: "1" <2> - requests.memory: 1Gi <3> - requests.ephemeral-storage: 2Gi <4> - limits.cpu: "2" <5> - limits.memory: 2Gi <6> - limits.ephemeral-storage: 4Gi <7> ----- -<1> The total number of pods in a non-terminal state that can exist in the project. -<2> Across all pods in a non-terminal state, the sum of CPU requests cannot exceed 1 core. -<3> Across all pods in a non-terminal state, the sum of memory requests cannot exceed 1Gi. -<4> Across all pods in a non-terminal state, the sum of ephemeral storage requests cannot exceed 2Gi. -<5> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed 2 cores. -<6> Across all pods in a non-terminal state, the sum of memory limits cannot exceed 2Gi. -<7> Across all pods in a non-terminal state, the sum of ephemeral storage limits cannot exceed 4Gi. - -.`besteffort.yaml` -[source,yaml] ----- -apiVersion: v1 -kind: ResourceQuota -metadata: - name: besteffort -spec: - hard: - pods: "1" <1> - scopes: - - BestEffort <2> ----- -<1> The total number of pods in a non-terminal state with `BestEffort` quality of service that can exist in the project. -<2> Restricts the quota to only matching pods that have `BestEffort` quality of service for either memory or CPU. - -.`compute-resources-long-running.yaml` -[source,yaml] ----- -apiVersion: v1 -kind: ResourceQuota -metadata: - name: compute-resources-long-running -spec: - hard: - pods: "4" <1> - limits.cpu: "4" <2> - limits.memory: "2Gi" <3> - limits.ephemeral-storage: "4Gi" <4> - scopes: - - NotTerminating <5> ----- -<1> The total number of pods in a non-terminal state. -<2> Across all pods in a non-terminal state, the sum of CPU limits cannot exceed this value. -<3> Across all pods in a non-terminal state, the sum of memory limits cannot exceed this value. -<4> Across all pods in a non-terminal state, the sum of ephemeral storage limits cannot exceed this value. -<5> Restricts the quota to only matching pods where `spec.activeDeadlineSeconds` is set to `nil`. Build pods will fall under `NotTerminating` unless the `RestartNever` policy is applied. - -.`compute-resources-time-bound.yaml` -[source,yaml] ----- -apiVersion: v1 -kind: ResourceQuota -metadata: - name: compute-resources-time-bound -spec: - hard: - pods: "2" <1> - limits.cpu: "1" <2> - limits.memory: "1Gi" <3> - limits.ephemeral-storage: "1Gi" <4> - scopes: - - Terminating <5> ----- -<1> The total number of pods in a terminating state. -<2> Across all pods in a terminating state, the sum of CPU limits cannot exceed this value. -<3> Across all pods in a terminating state, the sum of memory limits cannot exceed this value. -<4> Across all pods in a terminating state, the sum of ephemeral storage limits cannot exceed this value. -<5> Restricts the quota to only matching pods where `spec.activeDeadlineSeconds >=0`. For example, this quota would charge for build or deployer pods, but not long running pods like a web server or database. - -.`storage-consumption.yaml` -[source,yaml] ----- -apiVersion: v1 -kind: ResourceQuota -metadata: - name: storage-consumption -spec: - hard: - persistentvolumeclaims: "10" <1> - requests.storage: "50Gi" <2> - gold.storageclass.storage.k8s.io/requests.storage: "10Gi" <3> - silver.storageclass.storage.k8s.io/requests.storage: "20Gi" <4> - silver.storageclass.storage.k8s.io/persistentvolumeclaims: "5" <5> - bronze.storageclass.storage.k8s.io/requests.storage: "0" <6> - bronze.storageclass.storage.k8s.io/persistentvolumeclaims: "0" <7> ----- -<1> The total number of persistent volume claims in a project -<2> Across all persistent volume claims in a project, the sum of storage requested cannot exceed this value. -<3> Across all persistent volume claims in a project, the sum of storage requested in the gold storage class cannot exceed this value. -<4> Across all persistent volume claims in a project, the sum of storage requested in the silver storage class cannot exceed this value. -<5> Across all persistent volume claims in a project, the total number of claims in the silver storage class cannot exceed this value. -<6> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this is set to `0`, it means bronze storage class cannot request storage. -<7> Across all persistent volume claims in a project, the sum of storage requested in the bronze storage class cannot exceed this value. When this is set to `0`, it means bronze storage class cannot create claims. diff --git a/modules/quotas-scopes.adoc b/modules/quotas-scopes.adoc deleted file mode 100644 index e9559c8a8b21..000000000000 --- a/modules/quotas-scopes.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -[id="quotas-scopes_{context}"] -= Quota scopes - -Each quota can have an associated set of _scopes_. A quota only measures usage -for a resource if it matches the intersection of enumerated scopes. - -Adding a scope to a quota restricts the set of resources to which that quota can -apply. Specifying a resource outside of the allowed set results in a validation -error. - -|=== - -|Scope |Description - -|`Terminating` -|Match pods where `spec.activeDeadlineSeconds >= 0`. - -|`NotTerminating` -|Match pods where `spec.activeDeadlineSeconds` is `nil`. - -|`BestEffort` -|Match pods that have best effort quality of service for either `cpu` or -`memory`. - -|`NotBestEffort` -|Match pods that do not have best effort quality of service for `cpu` and -`memory`. -|=== - -A `BestEffort` scope restricts a quota to limiting the following resources: - -- `pods` - -A `Terminating`, `NotTerminating`, and `NotBestEffort` scope restricts a quota -to tracking the following resources: - -- `pods` -- `memory` -- `requests.memory` -- `limits.memory` -- `cpu` -- `requests.cpu` -- `limits.cpu` -- `ephemeral-storage` -- `requests.ephemeral-storage` -- `limits.ephemeral-storage` diff --git a/modules/quotas-selecting-projects.adoc b/modules/quotas-selecting-projects.adoc deleted file mode 100644 index 785d51950a7b..000000000000 --- a/modules/quotas-selecting-projects.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-across-multiple-projects.adoc - -[id="quotas-setting-projects_{context}"] -= Selecting multiple projects during quota creation - -When creating quotas, you can select multiple projects based on annotation selection, label selection, or both. - -.Procedure - -. To select projects based on annotations, run the following command: -+ -[source,terminal] ----- -$ oc create clusterquota for-user \ - --project-annotation-selector openshift.io/requester=<user_name> \ - --hard pods=10 \ - --hard secrets=20 ----- -+ -This creates the following `ClusterResourceQuota` object: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ClusterResourceQuota -metadata: - name: for-user -spec: - quota: <1> - hard: - pods: "10" - secrets: "20" - selector: - annotations: <2> - openshift.io/requester: <user_name> - labels: null <3> -status: - namespaces: <4> - - namespace: ns-one - status: - hard: - pods: "10" - secrets: "20" - used: - pods: "1" - secrets: "9" - total: <5> - hard: - pods: "10" - secrets: "20" - used: - pods: "1" - secrets: "9" ----- -<1> The `ResourceQuotaSpec` object that will be enforced over the selected projects. -<2> A simple key-value selector for annotations. -<3> A label selector that can be used to select projects. -<4> A per-namespace map that describes current quota usage in each selected project. -<5> The aggregate usage across all selected projects. -+ -This multi-project quota document controls all projects requested by `<user_name>` using the default project request endpoint. You are limited to 10 pods and 20 secrets. - -. Similarly, to select projects based on labels, run this command: -+ -[source,terminal] ----- -$ oc create clusterresourcequota for-name \//<1> - --project-label-selector=name=frontend \//<2> - --hard=pods=10 --hard=secrets=20 ----- -+ -<1> Both `clusterresourcequota` and `clusterquota` are aliases of the same command. `for-name` is the name of the `ClusterResourceQuota` object. -<2> To select projects by label, provide a key-value pair by using the format `--project-label-selector=key=value`. -+ -This creates the following `ClusterResourceQuota` object definition: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ClusterResourceQuota -metadata: - creationTimestamp: null - name: for-name -spec: - quota: - hard: - pods: "10" - secrets: "20" - selector: - annotations: null - labels: - matchLabels: - name: frontend ----- diff --git a/modules/quotas-selection-granularity.adoc b/modules/quotas-selection-granularity.adoc deleted file mode 100644 index 57219a629a74..000000000000 --- a/modules/quotas-selection-granularity.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-across-multiple-projects.adoc - -[id="quotas-selection-granularity_{context}"] -= Selection granularity - -Because of the locking consideration when claiming quota allocations, the number of -active projects selected by a multi-project quota is an important consideration. -Selecting more than 100 projects under a single multi-project quota can have -detrimental effects on API server responsiveness in those projects. diff --git a/modules/quotas-viewing-clusterresourcequotas.adoc b/modules/quotas-viewing-clusterresourcequotas.adoc deleted file mode 100644 index 9ae159e3bd8b..000000000000 --- a/modules/quotas-viewing-clusterresourcequotas.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-across-multiple-projects.adoc - -[id="quotas-viewing-clusterresourcequotas_{context}"] -= Viewing applicable cluster resource quotas - -A project administrator is not allowed to create or modify the multi-project quota that limits his or her project, but the administrator is allowed to view the multi-project quota documents that are applied to his or her project. The project administrator can do this via the `AppliedClusterResourceQuota` resource. - -.Procedure - -. To view quotas applied to a project, run: -+ -[source,terminal] ----- -$ oc describe AppliedClusterResourceQuota ----- -+ -.Example output -[source,terminal] ----- -Name: for-user -Namespace: <none> -Created: 19 hours ago -Labels: <none> -Annotations: <none> -Label Selector: <null> -AnnotationSelector: map[openshift.io/requester:<user-name>] -Resource Used Hard --------- ---- ---- -pods 1 10 -secrets 9 20 ----- diff --git a/modules/quotas-viewing-quotas.adoc b/modules/quotas-viewing-quotas.adoc deleted file mode 100644 index ca5573676bc4..000000000000 --- a/modules/quotas-viewing-quotas.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas/quotas-setting-per-project.adoc - -[id="quota-viewing-quotas_{context}"] -= Viewing a quota - -You can view usage statistics related to any hard limits defined in a project's -quota by navigating in the web console to the project's *Quota* page. - -You can also use the CLI to view quota details. - -.Procedure - -. Get the list of quotas defined in the project. For example, for a project called -`demoproject`: -+ -[source,terminal] ----- -$ oc get quota -n demoproject ----- -+ -.Example output -[source,terminal] ----- -NAME AGE -besteffort 11m -compute-resources 2m -core-object-counts 29m ----- - -. Describe the quota you are interested in, for example the `core-object-counts` -quota: -+ -[source,terminal] ----- -$ oc describe quota core-object-counts -n demoproject ----- -+ -.Example output -[source,terminal] ----- -Name: core-object-counts -Namespace: demoproject -Resource Used Hard --------- ---- ---- -configmaps 3 10 -persistentvolumeclaims 0 4 -replicationcontrollers 3 20 -secrets 9 10 -services 2 10 ----- diff --git a/modules/rbac-access-scopes.adoc b/modules/rbac-access-scopes.adoc new file mode 100644 index 000000000000..142c61b80c1a --- /dev/null +++ b/modules/rbac-access-scopes.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: CONCEPT +[id="rbac-access-scopes_{context}"] += System access scopes + +[role="_abstract"] +{product-title} includes some default system access scopes that you can apply on roles. +You can also create custom access scopes as required. + +[cols="1,3"] +|=== +| Acces scope | Description + +| *Unrestricted* +| Provides access to all clusters and namespaces that {product-title} monitors. + +| *Deny All* +| Provides no access to any Kubernetes and {ocp} resources. +|=== diff --git a/modules/rbac-adding-roles.adoc b/modules/rbac-adding-roles.adoc deleted file mode 100644 index 255caef43546..000000000000 --- a/modules/rbac-adding-roles.adoc +++ /dev/null @@ -1,126 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="adding-roles_{context}"] -= Adding roles to users - -You can use the `oc adm` administrator CLI to manage the roles and bindings. - -ifdef::openshift-dedicated[] -Dedicated administrators cannot manage cluster roles. They can manage -cluster role bindings and local roles and bindings. -endif::[] - -Binding, or adding, a role to users or groups gives the user or group the access -that is granted by the role. You can add and remove roles to and from users and -groups using `oc adm policy` commands. - -You can bind any of the default cluster roles to local users or groups in your -project. - -.Procedure - -. Add a role to a user in a specific project: -+ -[source,terminal] ----- -$ oc adm policy add-role-to-user <role> <user> -n <project> ----- -+ -For example, you can add the `admin` role to the `alice` user in `joe` project -by running: -+ -[source,terminal] ----- -$ oc adm policy add-role-to-user admin alice -n joe ----- - -. View the local role bindings and verify the addition in the output: -+ -[source,terminal] ----- -$ oc describe rolebinding.rbac -n <project> ----- -+ -For example, to view the local role bindings for the `joe` project: -+ -[source,terminal] ----- -$ oc describe rolebinding.rbac -n joe ----- -+ -.Example output -[source,terminal] ----- - -Name: admin -Labels: <none> -Annotations: <none> -Role: - Kind: ClusterRole - Name: admin -Subjects: - Kind Name Namespace - ---- ---- --------- - User kube:admin - - -Name: admin-0 -Labels: <none> -Annotations: <none> -Role: - Kind: ClusterRole - Name: admin -Subjects: - Kind Name Namespace - ---- ---- --------- - User alice <1> - - -Name: system:deployers -Labels: <none> -Annotations: openshift.io/description: - Allows deploymentconfigs in this namespace to rollout pods in - this namespace. It is auto-managed by a controller; remove - subjects to disa... -Role: - Kind: ClusterRole - Name: system:deployer -Subjects: - Kind Name Namespace - ---- ---- --------- - ServiceAccount deployer joe - - -Name: system:image-builders -Labels: <none> -Annotations: openshift.io/description: - Allows builds in this namespace to push images to this - namespace. It is auto-managed by a controller; remove subjects - to disable. -Role: - Kind: ClusterRole - Name: system:image-builder -Subjects: - Kind Name Namespace - ---- ---- --------- - ServiceAccount builder joe - - -Name: system:image-pullers -Labels: <none> -Annotations: openshift.io/description: - Allows all pods in this namespace to pull images from this - namespace. It is auto-managed by a controller; remove subjects - to disable. -Role: - Kind: ClusterRole - Name: system:image-puller -Subjects: - Kind Name Namespace - ---- ---- --------- - Group system:serviceaccounts:joe ----- -<1> The `alice` user has been added to the `admins` `RoleBinding`. diff --git a/modules/rbac-api-authentication.adoc b/modules/rbac-api-authentication.adoc deleted file mode 100644 index f7a1208feec8..000000000000 --- a/modules/rbac-api-authentication.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="rbac-api-authentication_{context}"] -= API authentication -Requests to the {product-title} API are authenticated using the following -methods: - -OAuth access tokens:: -* Obtained from the {product-title} OAuth server using the -`_<namespace_route>_/oauth/authorize` and `_<namespace_route>_/oauth/token` -endpoints. -* Sent as an `Authorization: Bearer...` header. -* Sent as a websocket subprotocol header in the form -`base64url.bearer.authorization.k8s.io.<base64url-encoded-token>` for websocket -requests. - -X.509 client certificates:: -* Requires an HTTPS connection to the API server. -* Verified by the API server against a trusted certificate authority bundle. -* The API server creates and distributes certificates to controllers to authenticate themselves. - -Any request with an invalid access token or an invalid certificate is rejected -by the authentication layer with a `401` error. - -If no access token or certificate is presented, the authentication layer assigns -the `system:anonymous` virtual user and the `system:unauthenticated` virtual -group to the request. This allows the authorization layer to determine which -requests, if any, an anonymous user is allowed to make. diff --git a/modules/rbac-cluster-role-binding-commands.adoc b/modules/rbac-cluster-role-binding-commands.adoc deleted file mode 100644 index 2580d81eb3a5..000000000000 --- a/modules/rbac-cluster-role-binding-commands.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] - -[id="cluster-role-binding-commands_{context}"] -= Cluster role binding commands - -You can also manage cluster role bindings using the following -operations. The `-n` flag is not used for these operations because -cluster role bindings use non-namespaced resources. - -.Cluster role binding operations -[options="header"] -|=== - -|Command |Description - -|`$ oc adm policy add-cluster-role-to-user _<role>_ _<username>_` -|Binds a given role to specified users for all projects in the cluster. - -|`$ oc adm policy remove-cluster-role-from-user _<role>_ _<username>_` -|Removes a given role from specified users for all projects in the cluster. - -|`$ oc adm policy add-cluster-role-to-group _<role>_ _<groupname>_` -|Binds a given role to specified groups for all projects in the cluster. - -|`$ oc adm policy remove-cluster-role-from-group _<role>_ _<groupname>_` -|Removes a given role from specified groups for all projects in the cluster. - -|=== -endif::[] diff --git a/modules/rbac-creating-cluster-admin.adoc b/modules/rbac-creating-cluster-admin.adoc deleted file mode 100644 index c2db72e8557f..000000000000 --- a/modules/rbac-creating-cluster-admin.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="creating-cluster-admin_{context}"] -= Creating a cluster admin - -The `cluster-admin` role is required to perform administrator -level tasks on the {product-title} cluster, such as modifying -cluster resources. - -.Prerequisites - -* You must have created a user to define as the cluster admin. - -.Procedure - -* Define the user as a cluster admin: -+ -[source,terminal] ----- -$ oc adm policy add-cluster-role-to-user cluster-admin <user> ----- diff --git a/modules/rbac-creating-cluster-role.adoc b/modules/rbac-creating-cluster-role.adoc deleted file mode 100644 index 14e36e3399ae..000000000000 --- a/modules/rbac-creating-cluster-role.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[id="creating-cluster-role_{context}"] -= Creating a cluster role - -You can create a cluster role. - -.Procedure - -. To create a cluster role, run the following command: -+ -[source,terminal] ----- -$ oc create clusterrole <name> --verb=<verb> --resource=<resource> ----- -+ -In this command, specify: -+ --- -* `<name>`, the local role's name -* `<verb>`, a comma-separated list of the verbs to apply to the role -* `<resource>`, the resources that the role applies to --- -+ -For example, to create a cluster role that allows a user to view pods, run the -following command: -+ -[source,terminal] ----- -$ oc create clusterrole podviewonly --verb=get --resource=pod ----- -endif::[] diff --git a/modules/rbac-creating-local-role.adoc b/modules/rbac-creating-local-role.adoc deleted file mode 100644 index 5d4c41547071..000000000000 --- a/modules/rbac-creating-local-role.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[id="creating-local-role_{context}"] -= Creating a local role - -You can create a local role for a project and then bind it to a user. - -.Procedure - -. To create a local role for a project, run the following command: -+ -[source,terminal] ----- -$ oc create role <name> --verb=<verb> --resource=<resource> -n <project> ----- -+ -In this command, specify: -+ --- -* `<name>`, the local role's name -* `<verb>`, a comma-separated list of the verbs to apply to the role -* `<resource>`, the resources that the role applies to -* `<project>`, the project name --- -+ -For example, to create a local role that allows a user to view pods in the -`blue` project, run the following command: -+ -[source,terminal] ----- -$ oc create role podview --verb=get --resource=pod -n blue ----- - -. To bind the new role to a user, run the following command: -+ -[source,terminal] ----- -$ oc adm policy add-role-to-user podview user2 --role-namespace=blue -n blue ----- -endif::[] diff --git a/modules/rbac-custom-roles.adoc b/modules/rbac-custom-roles.adoc new file mode 100644 index 000000000000..43f678c4009b --- /dev/null +++ b/modules/rbac-custom-roles.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: CONCEPT +[id="rbac-custom-roles_{context}"] += Custom roles + +{product-title} also allows you to create custom roles. +You can create a custom role with one or more permissions and then grant that custom role to users. +Creating custom roles enables you to enforce the principle of least privilege (PoLP). +You can use these roles to give users or system accounts only those permissions that are essential to performing their intended functions. diff --git a/modules/rbac-default-projects.adoc b/modules/rbac-default-projects.adoc deleted file mode 100644 index d5cdc82a8a3e..000000000000 --- a/modules/rbac-default-projects.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="rbac-default-projects_{context}"] -= Default projects - -{product-title} comes with a number of default projects, and projects -starting with `openshift-` are the most essential to users. -These projects host master components that run as pods and other infrastructure -components. The pods created in these namespaces that have a -link:https://kubernetes.io/docs/tasks/administer-cluster/guaranteed-scheduling-critical-addon-pods/#rescheduler-guaranteed-scheduling-of-critical-add-ons[critical pod annotation] -are considered critical, and the have guaranteed admission by kubelet. -Pods created for master components in these namespaces are already marked as -critical. - -[NOTE] -==== -You cannot assign an SCC to pods created in one of the default namespaces: `default`, `kube-system`, `kube-public`, `openshift-node`, `openshift-infra`, and `openshift`. You cannot use these namespaces for running pods or services. -==== diff --git a/modules/rbac-for-network-graph.adoc b/modules/rbac-for-network-graph.adoc new file mode 100644 index 000000000000..513b2c443229 --- /dev/null +++ b/modules/rbac-for-network-graph.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="rbac-for-network-graph_{context}"] += Access control and permissions + +To view network graphs, the user must have at least the permissions granted to the *Network Graph Viewer* default permission set. + +The following permissions are granted to the *Network Graph Viewer* permission set: + +- Read `Deployment` +- Read `NetworkGraph` +- Read `NetworkPolicy` + +For more information, see "System permission sets" in the "Additional resources" section. diff --git a/modules/rbac-groups.adoc b/modules/rbac-groups.adoc deleted file mode 100644 index 262b0bb65b19..000000000000 --- a/modules/rbac-groups.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-authentication.adoc - -[id="rbac-groups_{context}"] -= Groups - -A user can be assigned to one or more _groups_, each of which represent a -certain set of users. Groups are useful when managing authorization policies -to grant permissions to multiple users at once, for example allowing -access to objects within a project, versus granting -them to users individually. - -In addition to explicitly defined groups, there are also -system groups, or _virtual groups_, that are automatically provisioned by -the cluster. - -The following default virtual groups are most important: - -//WHY? - -[cols="2,5",options="header"] -|=== - -|Virtual group |Description - -|`system:authenticated` |Automatically associated with all authenticated users. -|`system:authenticated:oauth` |Automatically associated with all users authenticated with an OAuth access token. -|`system:unauthenticated` |Automatically associated with all unauthenticated users. - -|=== diff --git a/modules/rbac-local-role-binding-commands.adoc b/modules/rbac-local-role-binding-commands.adoc deleted file mode 100644 index 2801473ee7d9..000000000000 --- a/modules/rbac-local-role-binding-commands.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="local-role-binding-commands_{context}"] -= Local role binding commands - -When you manage a user or group's associated roles for local role bindings using the -following operations, a project may be specified with the `-n` flag. If it is -not specified, then the current project is used. - -You can use the following commands for local RBAC management. - -.Local role binding operations -[options="header"] -|=== - -|Command |Description - -|`$ oc adm policy who-can _<verb>_ _<resource>_` -|Indicates which users can perform an action on a resource. - -|`$ oc adm policy add-role-to-user _<role>_ _<username>_` -|Binds a specified role to specified users in the current project. - -|`$ oc adm policy remove-role-from-user _<role>_ _<username>_` -|Removes a given role from specified users in the current project. - -|`$ oc adm policy remove-user _<username>_` -|Removes specified users and all of their roles in the current project. - -|`$ oc adm policy add-role-to-group _<role>_ _<groupname>_` -|Binds a given role to specified groups in the current project. - -|`$ oc adm policy remove-role-from-group _<role>_ _<groupname>_` -|Removes a given role from specified groups in the current project. - -|`$ oc adm policy remove-group _<groupname>_` -|Removes specified groups and all of their roles in the current project. - -|=== diff --git a/modules/rbac-overview.adoc b/modules/rbac-overview.adoc deleted file mode 100644 index c7250a000b28..000000000000 --- a/modules/rbac-overview.adoc +++ /dev/null @@ -1,217 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="authorization-overview_{context}"] -= RBAC overview - -Role-based access control (RBAC) objects determine whether a user is allowed to -perform a given action within a project. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -Cluster -endif::[] -ifdef::openshift-dedicated[] -Dedicated -endif::[] -administrators can use the cluster roles and -bindings to control who has various access levels to the {product-title} -platform itself and all projects. - -Developers can use local roles and bindings to control who has access -to their projects. Note that authorization is a separate step from -authentication, which is more about determining the identity of who is taking the action. - -Authorization is managed using: - -[cols="1,4",options="header"] -|=== - -|Authorization object |Description - -|Rules |Sets of permitted verbs on a set of objects. For example, -whether a user or service account can `create` pods. - -|Roles |Collections of rules. You can associate, or bind, users and groups -to multiple roles. - -|Bindings |Associations between users and/or groups with a role. -|=== - -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -There are two levels of RBAC roles and bindings that control authorization: - -[cols="1,4",options="header"] -|=== - -|RBAC level |Description - -|Cluster RBAC |Roles and bindings that are applicable across -all projects. _Cluster roles_ exist cluster-wide, and _cluster role bindings_ -can reference only cluster roles. - -|Local RBAC |Roles and bindings that are scoped to a given project. While -_local roles_ exist only in a single project, local role bindings can -reference _both_ cluster and local roles. - -|=== - -A cluster role binding is a binding that exists at the cluster level. -A role binding exists at the project level. The cluster role _view_ must be -bound to a user using a local role binding for that user to view the project. -Create local roles only if a cluster role does not provide the set -of permissions needed for a particular situation. - -This two-level hierarchy allows reuse across multiple projects through the -cluster roles while allowing customization inside of individual projects -through local roles. - -During evaluation, both the cluster role bindings and the local role bindings are used. -For example: - -. Cluster-wide "allow" rules are checked. -. Locally-bound "allow" rules are checked. -. Deny by default. - - -[id="default-roles_{context}"] -== Default cluster roles - -{product-title} includes a set of default cluster roles that you can bind to -users and groups cluster-wide or locally. You can manually modify the default -cluster roles, if required. - -[cols="1,4",options="header"] -|=== - -|Default cluster role |Description - -|`admin` |A project manager. If used in a local binding, an `admin` has -rights to view any resource in the project and modify any resource in the -project except for quota. - -|`basic-user` |A user that can get basic information about projects and users. - -|`cluster-admin` |A super-user that can perform any action in any project. When -bound to a user with a local binding, they have full control over quota and -every action on every resource in the project. - -|`cluster-status` |A user that can get basic cluster status information. - -|`edit` |A user that can modify most objects in a project but does not have the -power to view or modify roles or bindings. - -|`self-provisioner` |A user that can create their own projects. - -|`view` |A user who cannot make any modifications, but can see most objects in a -project. They cannot view or modify roles or bindings. - -ifdef::openshift-dedicated[] -|`dedicated-readers` |A user who cannot make any modifications, but can see most objects in a -project. They cannot view or modify roles or bindings. Similar to the `view` role. All dedicated administrators are also granted these permissions. -endif::[] - -|=== -endif::[] - -Be mindful of the difference between local and cluster bindings. For example, -if you bind the `cluster-admin` role to a user by using a local role binding, -it might appear that this user has the privileges of a cluster administrator. -This is not the case. Binding the `cluster-admin` to a user in a project -grants super administrator privileges for only that -project to the user. That user has the permissions of the cluster role -`admin`, plus a few additional permissions like the ability to edit rate limits, -for that project. -This binding can be confusing via the web console UI, which does not list -cluster role bindings that are bound to true cluster administrators. However, it -does list local role bindings that you can use to locally bind `cluster-admin`. - -//// -If you do, when you upgrade -your cluster, the default roles are updated and -automatically reconciled when the server is started. During reconciliation, any -permissions that are missing from -the default roles are added. If you added more permissions to the role, they are -not removed. - -If you customized the default roles and configured them to prevent automatic -role reconciliation, you must manually update policy definitions -when you upgrade {product-title}. -//// - - -The relationships between cluster roles, local roles, cluster role bindings, -local role bindings, users, groups and service accounts are illustrated below. - -image::rbac.png[{product-title} RBAC] - - -[id="evaluating-authorization_{context}"] -== Evaluating authorization - -{product-title} evaluates authorization by using: - -Identity:: The user name and list of groups that the user belongs to. - -Action:: The action you perform. In most cases, this consists of: -* *Project*: The project you access. A project is a Kubernetes namespace with -additional annotations that allows a community of users to organize and manage -their content in isolation from other communities. -* *Verb* : The action itself: `get`, `list`, `create`, `update`, `delete`, `deletecollection`, or `watch`. -* *Resource name*: The API endpoint that you access. -Bindings:: The full list of bindings, the associations between users or groups -with a role. - -{product-title} evaluates authorization by using the following steps: - -. The identity and the project-scoped action is used to find all bindings that -apply to the user or their groups. -. Bindings are used to locate all the roles that apply. -. Roles are used to find all the rules that apply. -. The action is checked against each rule to find a match. -. If no matching rule is found, the action is then denied by default. - - -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] - -[TIP] -==== -Remember that users and groups can be associated with, or bound to, multiple -roles at the same time. -==== - -Project administrators can use the CLI to -endif::openshift-origin,openshift-enterprise,openshift-dedicated[] -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -view local roles and bindings, -endif::openshift-enterprise,openshift-webscale,openshift-origin[] -ifdef::openshift-dedicated[] -view local bindings, -endif::openshift-dedicated[] -including a matrix of the verbs and resources each are associated with. - -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -[IMPORTANT] -==== -The cluster role bound to the project administrator is limited in a project -through a local binding. -It is not bound cluster-wide like the cluster roles granted to the -*cluster-admin* or *system:admin*. - -Cluster roles are roles defined at the cluster level but can be bound either at -the cluster level or at the project level. -==== -endif::openshift-origin,openshift-enterprise,openshift-dedicated[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[id="cluster-role-aggregations_{context}"] -=== Cluster role aggregation -The default admin, edit, view, and cluster-reader cluster roles support -link:https://kubernetes.io/docs/admin/authorization/rbac/#aggregated-clusterroles[cluster role aggregation], -where the cluster rules for each role are dynamically updated as -new rules are created. This feature is relevant only if you extend the -Kubernetes API by creating custom resources. - -// NEED NEW LINK TO ASSEMBLY ABOUT making custom resources -endif::[] diff --git a/modules/rbac-permission-sets.adoc b/modules/rbac-permission-sets.adoc new file mode 100644 index 000000000000..eac864e12403 --- /dev/null +++ b/modules/rbac-permission-sets.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: CONCEPT +[id="rbac-permission-sets_{context}"] += System permission sets + +[role="_abstract"] +{product-title} includes some default system permission sets that you can apply to roles. +You can also create custom permission sets as required. + +[cols="1,3"] +|=== +| Permission set | Description + +| *Admin* +| Provides read and write access to all resources. + +| *Analyst* +| Provides read-only access for all resources. + +| *Continuous Integration* +| This permission set is targeted for CI (continuous integration) systems and includes the permissions required to enforce deployment policies. + +| *Network Graph Viewer* +| Provides the minimum permissions to view network graphs. + +| *None* +| No read and write permissions are allowed for any resource. + +| *Sensor Creator* +| Provides permissions for resources that are required to create Sensors in secured clusters. +|=== diff --git a/modules/rbac-projects-namespaces.adoc b/modules/rbac-projects-namespaces.adoc deleted file mode 100644 index 0c8ccb0039f8..000000000000 --- a/modules/rbac-projects-namespaces.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="rbac-projects-namespaces_{context}"] -= Projects and namespaces - -A Kubernetes _namespace_ provides a mechanism to scope resources in a cluster. -The -https://kubernetes.io/docs/tasks/administer-cluster/namespaces/[Kubernetes documentation] -has more information on namespaces. - -Namespaces provide a unique scope for: - -* Named resources to avoid basic naming collisions. -* Delegated management authority to trusted users. -* The ability to limit community resource consumption. - -Most objects in the system are scoped by namespace, but some are -excepted and have no namespace, including nodes and users. - -A _project_ is a Kubernetes namespace with additional annotations and is the central vehicle -by which access to resources for regular users is managed. -A project allows a community of users to organize and manage their content in -isolation from other communities. Users must be given access to projects by administrators, -or if allowed to create projects, automatically have access to their own projects. - -Projects can have a separate `name`, `displayName`, and `description`. - -- The mandatory `name` is a unique identifier for the project and is most visible when using the CLI tools or API. The maximum name length is 63 characters. -- The optional `displayName` is how the project is displayed in the web console (defaults to `name`). -- The optional `description` can be a more detailed description of the project and is also visible in the web console. - -Each project scopes its own set of: - -[cols="1,4",options="header"] -|=== - -|Object -|Description - -|`Objects` -|Pods, services, replication controllers, etc. - -|`Policies` -|Rules for which users can or cannot perform actions on objects. - -|`Constraints` -|Quotas for each kind of object that can be limited. - -|`Service accounts` -|Service accounts act automatically with designated access to objects in the project. - -|=== - -Cluster administrators can create projects and delegate administrative rights -for the project to any member of the user community. Cluster administrators can -also allow developers to create their own projects. - -Developers and administrators can interact with projects by using the CLI or the -web console. diff --git a/modules/rbac-resource-definitions.adoc b/modules/rbac-resource-definitions.adoc new file mode 100644 index 000000000000..8466fc796087 --- /dev/null +++ b/modules/rbac-resource-definitions.adoc @@ -0,0 +1,155 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: CONCEPT +[id="resource-definitions_{context}"] += Resource definitions + +[role="_abstract"] +{product-title} includes many resources. +The following table lists the {product-title} resources and describes the actions that users can perform with the `read` or `write` permission. + +include::snippets/note-about-creating-tokens.adoc[] + +[cols="1,2a,2a"] +|=== +| Resource | Read permission | Write permission + +| Access +| View configurations for single sign-on (SSO) and role-based access control (RBAC) rules that match user metadata to {product-title} roles and users that have accessed your {product-title} instance, including the metadata that the authentication providers give about them. +| Create, modify, or delete SSO configurations and configured RBAC rules. + +| Administration +| View the following items: + +* Options for data retention, security notices and other related configurations +* The current logging verbosity level in {product-title} components +* Manifest content for the uploaded probe files +* Existing image scanner integrations +* The status of automatic upgrades +* Metadata about {product-title} service-to-service authentication +* The content of the scanner bundle (download) +| Edit the following items: + +* Data retention, security notices, and related configurations +* The logging level +* Support packages in Central (upload) +* Image scanner integrations (create/modify/delete) +* Automatic upgrades for secured clusters (enable/disable) +* Service-to-service authentication credentials (revoke/re-issue) +//TODO: Add link to security notices and data retention +//TODO: Add link to uploading packages +//TODO: Add link to image scanner integration +//TODO: Add link to automatic upgrades + +| Alert +| View existing policy violations. +| Resolve or edit policy violations. +//TODO: Add link to policy violations + +| CVE +| _Internal use only_ +| _Internal use only_ + +| Cluster +| View existing secured clusters. +| Add new secured clusters and modify or delete existing clusters. + +| Compliance +| View compliance standards and results, recent compliance runs, and the associated completion status. +| Trigger compliance runs. +//TODO: Add link to Compliance + +| Deployment +| View deployments (workloads) in secured clusters. +| N/A + +| DeploymentExtension +| View the following items: + +* Process baselines +* Process activity in deployments +* Risk results +| Modify the following items: + +* Process baselines (add or remove processes) +//TODO: Add link to pprocess baselines +//TODO: Add link to Risks + +| Detection +| Check build-time policies against images or deployment YAML. +| N/A +//TODO: Add link to Integrate with CI systems + +| Image +| View images, their components, and their vulnerabilities. +| N/A +//TODO: Add link to VIew images topic + +| Integration +| View integrations and their configuration, including backup, registry, image signature, notification systems, and API tokens. +| Add, modify, and delete integrations and their configurations, and API tokens. + +| K8sRole +| View roles for Kubernetes RBAC in secured clusters. +| N/A + +| K8sRoleBinding +| View role bindings for Kubernetes RBAC in secured clusters. +| N/A + +| K8sSubject +| View users and groups for Kubernetes RBAC in secured clusters. +| N/A + +| Namespace +| View existing Kubernetes namespaces in secured clusters. +| N/A + +| NetworkGraph +| View active and allowed network connections in secured clusters. +| N/A +//TODO: Add link to manage network policies + +| NetworkPolicy +| View existing network policies in secured clusters and simulate changes. +| Apply network policy changes in secured clusters. +//TODO: Add link to manage network policies + +| Node +| View existing Kubernetes nodes in secured clusters. +| N/A + +| WorkflowAdministration +| View all resource collections. +| Add, modify, or delete resource collections. + +| Role +| View existing {product-title} RBAC roles and their permissions. +| Add, modify, or delete roles and their permissions. + +| Secret +| View metadata about secrets in secured clusters. +| N/A + +| ServiceAccount +| List Kubernetes service accounts in secured clusters. +| N/A + +| VulnerabilityManagementApprovals +| View all pending deferral or false positive requests for vulnerabilities. +| Approve or deny any pending deferral or false positive requests and move any previously approved requests back to observed. + +| VulnerabilityManagementRequests +| View all pending deferral or false positive requests for vulnerabilities. +| Request a deferral on a vulnerability, mark it as a false positive, or move a pending or previously approved request made by the same user back to observed. + +| WatchedImage +| View undeployed and monitored watched images. +| Configure watched images. + +| WorkflowAdministration +| View all resource collections. +| Create, modify, or delete resource collections. + +|=== diff --git a/modules/rbac-system-roles-3630.adoc b/modules/rbac-system-roles-3630.adoc new file mode 100644 index 000000000000..69efcefd246d --- /dev/null +++ b/modules/rbac-system-roles-3630.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: CONCEPT +[id="rbac-system-roles-3630_{context}"] += System roles + +[role="_abstract"] +{rh-rhacs-first} includes some default system roles that you can apply to users when you create rules. +You can also create custom roles as required. + +[cols="1,3"] +|=== +| System role | Description + +| *Admin* +| This role is targeted for administrators. Use it to provide read and write access to all resources. + +| *Analyst* +| This role is targeted for a user who cannot make any changes, but can view everything. Use it to provide read-only access for all resources. + +| *Continuous Integration* +| This role is targeted for CI (continuous integration) systems and includes the permission set required to enforce deployment policies. + +| *Network Graph Viewer* +| This role is targeted for users who need to view the network graph. + +| *None* +| This role has no read and write access to any resource. +You can set this role as the minimum access role for all users. + +| *Sensor Creator* +| {product-title-short} uses this role to automate new cluster setups. It includes the permission set to create Sensors in secured clusters. + +| *Vulnerability Management Approver* +| This role allows you to provide access to approve vulnerability deferrals or false positive requests. + +| *Vulnerability Management Requester* +| This role allows you to provide access to request vulnerability deferrals or false positives. + +| *Vulnerability Report Creator* +| This role allows you to create and manage vulnerability reporting configurations for scheduled vulnerability reports. + +|=== diff --git a/modules/rbac-system-roles.adoc b/modules/rbac-system-roles.adoc new file mode 100644 index 000000000000..ce8bf0ba74a1 --- /dev/null +++ b/modules/rbac-system-roles.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: CONCEPT +[id="rbac-system-roles_{context}"] += System roles + +[role="_abstract"] +{product-title} includes some default system roles that you can apply on users. +You can also create custom roles as required. + +[cols="1,3"] +|=== +| System role | Description + +| *Admin* +| This role is targeted for administrators. +It has `read` and `write` permissions for all resources. + +| *Analyst* +| This role is targeted for a user who cannot make any changes, but can view everything. +It has read-only permissions for all resources. + +| *Continuous Integration* +| This role is targeted for CI (Continuous Integration) systems and has read-only access to check images and deployment YAML against your policies. + +| *None* +| This role has no read and write permissions. +You can set this role as the minimum access role for all users. + +| *Sensor Creator* +| {product-title} uses this role to automate new cluster setups. +You require this role to run the command `roxctl sensor generate` in a new secured cluster. +|=== diff --git a/modules/rbac-users.adoc b/modules/rbac-users.adoc deleted file mode 100644 index 41d1c05bdcb5..000000000000 --- a/modules/rbac-users.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/understanding-authentication.adoc - -[id="rbac-users_{context}"] -= Users - -A _user_ in {product-title} is an entity that can make requests to the -{product-title} API. An {product-title} `User` object represents an actor which -can be granted permissions in the system by adding roles to them or to their -groups. Typically, this represents the account of a developer or -administrator that is interacting with {product-title}. - -Several types of users can exist: - -[cols="1,4",options="header"] -|=== - -|User type -|Description - -|`Regular users` -|This is the way most interactive {product-title} users are -represented. Regular users are created automatically in the system upon -first login or can be created via the API. Regular users are represented -with the `User` object. Examples: `joe` `alice` - -|`System users` -|Many of these are created automatically when the infrastructure - is defined, mainly for the purpose of enabling the infrastructure to - interact with the API securely. They include a cluster administrator - (with access to everything), a per-node user, users for use by routers - and registries, and various others. Finally, there is an `anonymous` - system user that is used by default for unauthenticated requests. Examples: -`system:admin` `system:openshift-registry` `system:node:node1.example.com` - -|`Service accounts` -|These are special system users associated with projects; some are created automatically when -the project is first created, while project administrators can create more -for the purpose of defining access to the contents of each project. -Service accounts are represented with the `ServiceAccount` object. Examples: -`system:serviceaccount:default:deployer` `system:serviceaccount:foo:builder` - -|=== - -Each user must authenticate in -some way to access {product-title}. API requests with no authentication -or invalid authentication are authenticated as requests by the `anonymous` -system user. Once authenticated, policy determines what the user is -authorized to do. diff --git a/modules/rbac-viewing-cluster-roles.adoc b/modules/rbac-viewing-cluster-roles.adoc deleted file mode 100644 index 8d42035709db..000000000000 --- a/modules/rbac-viewing-cluster-roles.adoc +++ /dev/null @@ -1,325 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="viewing-cluster-roles_{context}"] -= Viewing cluster roles and bindings - -You can use the `oc` CLI to view cluster roles and bindings by using the -`oc describe` command. - -.Prerequisites - -* Install the `oc` CLI. -* Obtain permission to view the cluster roles and bindings. -ifdef::openshift-dedicated[] -Users with the `dedicated-admins-cluster` role can view cluster roles and bindings. -endif::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -Users with the `cluster-admin` default cluster role bound cluster-wide can -perform any action on any resource, including viewing cluster roles and bindings. -endif::[] - -.Procedure - -. To view the cluster roles and their associated rule sets: -+ -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[source,terminal] ----- -$ oc describe clusterrole.rbac ----- -+ -.Example output -[source,terminal] ----- -Name: admin -Labels: kubernetes.io/bootstrapping=rbac-defaults -Annotations: rbac.authorization.kubernetes.io/autoupdate: true -PolicyRule: - Resources Non-Resource URLs Resource Names Verbs - --------- ----------------- -------------- ----- - .packages.apps.redhat.com [] [] [* create update patch delete get list watch] - imagestreams [] [] [create delete deletecollection get list patch update watch create get list watch] - imagestreams.image.openshift.io [] [] [create delete deletecollection get list patch update watch create get list watch] - secrets [] [] [create delete deletecollection get list patch update watch get list watch create delete deletecollection patch update] - buildconfigs/webhooks [] [] [create delete deletecollection get list patch update watch get list watch] - buildconfigs [] [] [create delete deletecollection get list patch update watch get list watch] - buildlogs [] [] [create delete deletecollection get list patch update watch get list watch] - deploymentconfigs/scale [] [] [create delete deletecollection get list patch update watch get list watch] - deploymentconfigs [] [] [create delete deletecollection get list patch update watch get list watch] - imagestreamimages [] [] [create delete deletecollection get list patch update watch get list watch] - imagestreammappings [] [] [create delete deletecollection get list patch update watch get list watch] - imagestreamtags [] [] [create delete deletecollection get list patch update watch get list watch] - processedtemplates [] [] [create delete deletecollection get list patch update watch get list watch] - routes [] [] [create delete deletecollection get list patch update watch get list watch] - templateconfigs [] [] [create delete deletecollection get list patch update watch get list watch] - templateinstances [] [] [create delete deletecollection get list patch update watch get list watch] - templates [] [] [create delete deletecollection get list patch update watch get list watch] - deploymentconfigs.apps.openshift.io/scale [] [] [create delete deletecollection get list patch update watch get list watch] - deploymentconfigs.apps.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - buildconfigs.build.openshift.io/webhooks [] [] [create delete deletecollection get list patch update watch get list watch] - buildconfigs.build.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - buildlogs.build.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - imagestreamimages.image.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - imagestreammappings.image.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - imagestreamtags.image.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - routes.route.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - processedtemplates.template.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - templateconfigs.template.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - templateinstances.template.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - templates.template.openshift.io [] [] [create delete deletecollection get list patch update watch get list watch] - serviceaccounts [] [] [create delete deletecollection get list patch update watch impersonate create delete deletecollection patch update get list watch] - imagestreams/secrets [] [] [create delete deletecollection get list patch update watch] - rolebindings [] [] [create delete deletecollection get list patch update watch] - roles [] [] [create delete deletecollection get list patch update watch] - rolebindings.authorization.openshift.io [] [] [create delete deletecollection get list patch update watch] - roles.authorization.openshift.io [] [] [create delete deletecollection get list patch update watch] - imagestreams.image.openshift.io/secrets [] [] [create delete deletecollection get list patch update watch] - rolebindings.rbac.authorization.k8s.io [] [] [create delete deletecollection get list patch update watch] - roles.rbac.authorization.k8s.io [] [] [create delete deletecollection get list patch update watch] - networkpolicies.extensions [] [] [create delete deletecollection patch update create delete deletecollection get list patch update watch get list watch] - networkpolicies.networking.k8s.io [] [] [create delete deletecollection patch update create delete deletecollection get list patch update watch get list watch] - configmaps [] [] [create delete deletecollection patch update get list watch] - endpoints [] [] [create delete deletecollection patch update get list watch] - persistentvolumeclaims [] [] [create delete deletecollection patch update get list watch] - pods [] [] [create delete deletecollection patch update get list watch] - replicationcontrollers/scale [] [] [create delete deletecollection patch update get list watch] - replicationcontrollers [] [] [create delete deletecollection patch update get list watch] - services [] [] [create delete deletecollection patch update get list watch] - daemonsets.apps [] [] [create delete deletecollection patch update get list watch] - deployments.apps/scale [] [] [create delete deletecollection patch update get list watch] - deployments.apps [] [] [create delete deletecollection patch update get list watch] - replicasets.apps/scale [] [] [create delete deletecollection patch update get list watch] - replicasets.apps [] [] [create delete deletecollection patch update get list watch] - statefulsets.apps/scale [] [] [create delete deletecollection patch update get list watch] - statefulsets.apps [] [] [create delete deletecollection patch update get list watch] - horizontalpodautoscalers.autoscaling [] [] [create delete deletecollection patch update get list watch] - cronjobs.batch [] [] [create delete deletecollection patch update get list watch] - jobs.batch [] [] [create delete deletecollection patch update get list watch] - daemonsets.extensions [] [] [create delete deletecollection patch update get list watch] - deployments.extensions/scale [] [] [create delete deletecollection patch update get list watch] - deployments.extensions [] [] [create delete deletecollection patch update get list watch] - ingresses.extensions [] [] [create delete deletecollection patch update get list watch] - replicasets.extensions/scale [] [] [create delete deletecollection patch update get list watch] - replicasets.extensions [] [] [create delete deletecollection patch update get list watch] - replicationcontrollers.extensions/scale [] [] [create delete deletecollection patch update get list watch] - poddisruptionbudgets.policy [] [] [create delete deletecollection patch update get list watch] - deployments.apps/rollback [] [] [create delete deletecollection patch update] - deployments.extensions/rollback [] [] [create delete deletecollection patch update] - catalogsources.operators.coreos.com [] [] [create update patch delete get list watch] - clusterserviceversions.operators.coreos.com [] [] [create update patch delete get list watch] - installplans.operators.coreos.com [] [] [create update patch delete get list watch] - packagemanifests.operators.coreos.com [] [] [create update patch delete get list watch] - subscriptions.operators.coreos.com [] [] [create update patch delete get list watch] - buildconfigs/instantiate [] [] [create] - buildconfigs/instantiatebinary [] [] [create] - builds/clone [] [] [create] - deploymentconfigrollbacks [] [] [create] - deploymentconfigs/instantiate [] [] [create] - deploymentconfigs/rollback [] [] [create] - imagestreamimports [] [] [create] - localresourceaccessreviews [] [] [create] - localsubjectaccessreviews [] [] [create] - podsecuritypolicyreviews [] [] [create] - podsecuritypolicyselfsubjectreviews [] [] [create] - podsecuritypolicysubjectreviews [] [] [create] - resourceaccessreviews [] [] [create] - routes/custom-host [] [] [create] - subjectaccessreviews [] [] [create] - subjectrulesreviews [] [] [create] - deploymentconfigrollbacks.apps.openshift.io [] [] [create] - deploymentconfigs.apps.openshift.io/instantiate [] [] [create] - deploymentconfigs.apps.openshift.io/rollback [] [] [create] - localsubjectaccessreviews.authorization.k8s.io [] [] [create] - localresourceaccessreviews.authorization.openshift.io [] [] [create] - localsubjectaccessreviews.authorization.openshift.io [] [] [create] - resourceaccessreviews.authorization.openshift.io [] [] [create] - subjectaccessreviews.authorization.openshift.io [] [] [create] - subjectrulesreviews.authorization.openshift.io [] [] [create] - buildconfigs.build.openshift.io/instantiate [] [] [create] - buildconfigs.build.openshift.io/instantiatebinary [] [] [create] - builds.build.openshift.io/clone [] [] [create] - imagestreamimports.image.openshift.io [] [] [create] - routes.route.openshift.io/custom-host [] [] [create] - podsecuritypolicyreviews.security.openshift.io [] [] [create] - podsecuritypolicyselfsubjectreviews.security.openshift.io [] [] [create] - podsecuritypolicysubjectreviews.security.openshift.io [] [] [create] - jenkins.build.openshift.io [] [] [edit view view admin edit view] - builds [] [] [get create delete deletecollection get list patch update watch get list watch] - builds.build.openshift.io [] [] [get create delete deletecollection get list patch update watch get list watch] - projects [] [] [get delete get delete get patch update] - projects.project.openshift.io [] [] [get delete get delete get patch update] - namespaces [] [] [get get list watch] - pods/attach [] [] [get list watch create delete deletecollection patch update] - pods/exec [] [] [get list watch create delete deletecollection patch update] - pods/portforward [] [] [get list watch create delete deletecollection patch update] - pods/proxy [] [] [get list watch create delete deletecollection patch update] - services/proxy [] [] [get list watch create delete deletecollection patch update] - routes/status [] [] [get list watch update] - routes.route.openshift.io/status [] [] [get list watch update] - appliedclusterresourcequotas [] [] [get list watch] - bindings [] [] [get list watch] - builds/log [] [] [get list watch] - deploymentconfigs/log [] [] [get list watch] - deploymentconfigs/status [] [] [get list watch] - events [] [] [get list watch] - imagestreams/status [] [] [get list watch] - limitranges [] [] [get list watch] - namespaces/status [] [] [get list watch] - pods/log [] [] [get list watch] - pods/status [] [] [get list watch] - replicationcontrollers/status [] [] [get list watch] - resourcequotas/status [] [] [get list watch] - resourcequotas [] [] [get list watch] - resourcequotausages [] [] [get list watch] - rolebindingrestrictions [] [] [get list watch] - deploymentconfigs.apps.openshift.io/log [] [] [get list watch] - deploymentconfigs.apps.openshift.io/status [] [] [get list watch] - controllerrevisions.apps [] [] [get list watch] - rolebindingrestrictions.authorization.openshift.io [] [] [get list watch] - builds.build.openshift.io/log [] [] [get list watch] - imagestreams.image.openshift.io/status [] [] [get list watch] - appliedclusterresourcequotas.quota.openshift.io [] [] [get list watch] - imagestreams/layers [] [] [get update get] - imagestreams.image.openshift.io/layers [] [] [get update get] - builds/details [] [] [update] - builds.build.openshift.io/details [] [] [update] - - -Name: basic-user -Labels: <none> -Annotations: openshift.io/description: A user that can get basic information about projects. - rbac.authorization.kubernetes.io/autoupdate: true -PolicyRule: - Resources Non-Resource URLs Resource Names Verbs - --------- ----------------- -------------- ----- - selfsubjectrulesreviews [] [] [create] - selfsubjectaccessreviews.authorization.k8s.io [] [] [create] - selfsubjectrulesreviews.authorization.openshift.io [] [] [create] - clusterroles.rbac.authorization.k8s.io [] [] [get list watch] - clusterroles [] [] [get list] - clusterroles.authorization.openshift.io [] [] [get list] - storageclasses.storage.k8s.io [] [] [get list] - users [] [~] [get] - users.user.openshift.io [] [~] [get] - projects [] [] [list watch] - projects.project.openshift.io [] [] [list watch] - projectrequests [] [] [list] - projectrequests.project.openshift.io [] [] [list] - -Name: cluster-admin -Labels: kubernetes.io/bootstrapping=rbac-defaults -Annotations: rbac.authorization.kubernetes.io/autoupdate: true -PolicyRule: -Resources Non-Resource URLs Resource Names Verbs ---------- ----------------- -------------- ----- -*.* [] [] [*] - [*] [] [*] - -... - ----- -endif::[] -ifdef::openshift-dedicated[] -[source,terminal] ----- -$ oc describe clusterrole.rbac ----- -endif::[] - -. To view the current set of cluster role bindings, which shows the users and -groups that are bound to various roles: -+ -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[source,terminal] ----- -$ oc describe clusterrolebinding.rbac ----- -+ -.Example output -[source,terminal] ----- -Name: alertmanager-main -Labels: <none> -Annotations: <none> -Role: - Kind: ClusterRole - Name: alertmanager-main -Subjects: - Kind Name Namespace - ---- ---- --------- - ServiceAccount alertmanager-main openshift-monitoring - - -Name: basic-users -Labels: <none> -Annotations: rbac.authorization.kubernetes.io/autoupdate: true -Role: - Kind: ClusterRole - Name: basic-user -Subjects: - Kind Name Namespace - ---- ---- --------- - Group system:authenticated - - -Name: cloud-credential-operator-rolebinding -Labels: <none> -Annotations: <none> -Role: - Kind: ClusterRole - Name: cloud-credential-operator-role -Subjects: - Kind Name Namespace - ---- ---- --------- - ServiceAccount default openshift-cloud-credential-operator - - -Name: cluster-admin -Labels: kubernetes.io/bootstrapping=rbac-defaults -Annotations: rbac.authorization.kubernetes.io/autoupdate: true -Role: - Kind: ClusterRole - Name: cluster-admin -Subjects: - Kind Name Namespace - ---- ---- --------- - Group system:masters - - -Name: cluster-admins -Labels: <none> -Annotations: rbac.authorization.kubernetes.io/autoupdate: true -Role: - Kind: ClusterRole - Name: cluster-admin -Subjects: - Kind Name Namespace - ---- ---- --------- - Group system:cluster-admins - User system:admin - - -Name: cluster-api-manager-rolebinding -Labels: <none> -Annotations: <none> -Role: - Kind: ClusterRole - Name: cluster-api-manager-role -Subjects: - Kind Name Namespace - ---- ---- --------- - ServiceAccount default openshift-machine-api - -... ----- -endif::[] -ifdef::openshift-dedicated[] -[source,terminal] ----- -$ oc describe clusterrolebinding.rbac ----- -endif::[] diff --git a/modules/rbac-viewing-local-roles.adoc b/modules/rbac-viewing-local-roles.adoc deleted file mode 100644 index a0d9179cbbfe..000000000000 --- a/modules/rbac-viewing-local-roles.adoc +++ /dev/null @@ -1,105 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-rbac.adoc -// * post_installation_configuration/preparing-for-users.adoc - -[id="viewing-local-roles_{context}"] -= Viewing local roles and bindings - -You can use the `oc` CLI to view local roles and bindings by using the -`oc describe` command. - -.Prerequisites - -* Install the `oc` CLI. -* Obtain permission to view the local roles and bindings: - -ifdef::openshift-dedicated[] -** Users with the `dedicated-admins-cluster` role can view and manage local roles and bindings. -endif::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -** Users with the `cluster-admin` default cluster role bound cluster-wide can -perform any action on any resource, including viewing local roles and bindings. -endif::[] - -** Users with the `admin` default cluster role bound locally can view and manage -roles and bindings in that project. - -.Procedure - -. To view the current set of local role bindings, which show the users and groups -that are bound to various roles for the current project: -+ -[source,terminal] ----- -$ oc describe rolebinding.rbac ----- - -. To view the local role bindings for a different project, add the `-n` flag -to the command: -+ -[source,terminal] ----- -$ oc describe rolebinding.rbac -n joe-project ----- -+ -.Example output -[source,terminal] ----- -Name: admin -Labels: <none> -Annotations: <none> -Role: - Kind: ClusterRole - Name: admin -Subjects: - Kind Name Namespace - ---- ---- --------- - User kube:admin - - -Name: system:deployers -Labels: <none> -Annotations: openshift.io/description: - Allows deploymentconfigs in this namespace to rollout pods in - this namespace. It is auto-managed by a controller; remove - subjects to disa... -Role: - Kind: ClusterRole - Name: system:deployer -Subjects: - Kind Name Namespace - ---- ---- --------- - ServiceAccount deployer joe-project - - -Name: system:image-builders -Labels: <none> -Annotations: openshift.io/description: - Allows builds in this namespace to push images to this - namespace. It is auto-managed by a controller; remove subjects - to disable. -Role: - Kind: ClusterRole - Name: system:image-builder -Subjects: - Kind Name Namespace - ---- ---- --------- - ServiceAccount builder joe-project - - -Name: system:image-pullers -Labels: <none> -Annotations: openshift.io/description: - Allows all pods in this namespace to pull images from this - namespace. It is auto-managed by a controller; remove subjects - to disable. -Role: - Kind: ClusterRole - Name: system:image-puller -Subjects: - Kind Name Namespace - ---- ---- --------- - Group system:serviceaccounts:joe-project ----- diff --git a/modules/rebuilding-the-oci-artifact.adoc b/modules/rebuilding-the-oci-artifact.adoc new file mode 100644 index 000000000000..3538086579b7 --- /dev/null +++ b/modules/rebuilding-the-oci-artifact.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * configuration/configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub.adoc + +:_mod-docs-content-type: PROCEDURE +[id="rebuilding-the-oci-artifact_{context}"] += Rebuilding the OCI artifact + +To rebuild the Open Container Initiative (OCI) artifact, update the `repo-ref` field in the `source.json` file to reference the new commit ID of the plugin repository. + +.Procedure + +* To rebuild the OCI artifact, update the `repo-ref` field in the `source.json` file, for example: ++ +[IMPORTANT] +==== +You can find the `source.json` file in the `workspaces/acs` directory of the `rhdh-plugin-export-overlays` repository. +==== ++ +[source,json] +---- +{"repo":"https://github.com/backstage/community-plugins","repo-ref":"19ddb7837c6823a253c87af9524f8aef26a90b35","repo-flat":false} +---- \ No newline at end of file diff --git a/modules/recommended-configurable-storage-technology.adoc b/modules/recommended-configurable-storage-technology.adoc deleted file mode 100644 index 7c9e4ed0c12f..000000000000 --- a/modules/recommended-configurable-storage-technology.adoc +++ /dev/null @@ -1,132 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/optimizing-storage.adoc -// * post_installation_configuration/storage-configuration.adoc - -[id="recommended-configurable-storage-technology_{context}"] -= Recommended configurable storage technology - -The following table summarizes the recommended and configurable storage technologies for the given {product-title} cluster application. - -.Recommended and configurable storage technology -[options="header,footer"] -|=== -|Storage type |ROX^1^|RWX^2^|Registry|Scaled registry|Metrics^3^|Logging|Apps - -| Block -| Yes^4^ -| No -| Configurable -| Not configurable -| Recommended -| Recommended -| Recommended - -| File -| Yes^4^ -| Yes -| Configurable -| Configurable -| Configurable^5^ -| Configurable^6^ -| Recommended - -| Object -| Yes -| Yes -| Recommended -| Recommended -| Not configurable -| Not configurable -| Not configurable^7^ - -8+a| -^1^ `ReadOnlyMany` - -^2^ `ReadWriteMany` - -^3^ Prometheus is the underlying technology used for metrics. - -^4^ This does not apply to physical disk, VM physical disk, VMDK, loopback over NFS, AWS EBS, and Azure Disk. - -^5^ For metrics, using file storage with the `ReadWriteMany` (RWX) access mode is unreliable. If you use file storage, do not configure the RWX access mode on any persistent volume claims (PVCs) that are configured for use with metrics. - -^6^ For logging, using any shared storage would be an anti-pattern. One volume per elasticsearch is required. - -^7^ Object storage is not consumed through {product-title}'s PVs or PVCs. Apps must integrate with the object storage REST API. - -|=== - -[NOTE] -==== -A scaled registry is an {product-title} registry where two or more pod replicas are running. -==== - -== Specific application storage recommendations - -[IMPORTANT] -==== -Testing shows issues with using the NFS server on {op-system-base-full} as storage backend for core services. This includes the OpenShift Container Registry and Quay, Prometheus for monitoring storage, and Elasticsearch for logging storage. Therefore, using {op-system-base} NFS to back PVs used by core services is not recommended. - -Other NFS implementations on the marketplace might not have these issues. Contact the individual NFS implementation vendor for more information on any testing that was possibly completed against these {product-title} core components. -==== - -=== Registry - -In a non-scaled/high-availability (HA) {product-title} registry cluster deployment: - -* The storage technology does not have to support RWX access mode. -* The storage technology must ensure read-after-write consistency. -* The preferred storage technology is object storage followed by block storage. -* File storage is not recommended for {product-title} registry cluster deployment with production workloads. - -=== Scaled registry - -In a scaled/HA {product-title} registry cluster deployment: - -* The storage technology must support RWX access mode and must ensure read-after-write consistency. -* The preferred storage technology is object storage. -* Amazon Simple Storage Service (Amazon S3), Google Cloud Storage (GCS), Microsoft Azure Blob Storage, and OpenStack Swift are supported. -* Object storage should be S3 or Swift compliant.. -* For non-cloud platforms, such as vSphere and bare metal installations, the only configurable technology is file storage. -* Block storage is not configurable. - -=== Metrics - -In an {product-title} hosted metrics cluster deployment: - -* The preferred storage technology is block storage. -* Object storage is not configurable. - -[IMPORTANT] -==== -It is not recommended to use file storage for a hosted metrics cluster deployment with production workloads. -==== - -=== Logging - -In an {product-title} hosted logging cluster deployment: - -* The preferred storage technology is block storage. -* Object storage is not configurable. - -[IMPORTANT] -==== -Testing shows issues with using the NFS server on {op-system-base} as storage backend for core services. This includes Elasticsearch for logging storage. Therefore, using {op-system-base} NFS to back PVs used by core services is not recommended. - -Other NFS implementations on the marketplace might not have these issues. Contact the individual NFS implementation vendor for more information on any testing that was possibly completed against these {product-title} core components. -==== - -=== Applications - -Application use cases vary from application to application, as described in the following examples: - -* Storage technologies that support dynamic PV provisioning have low mount time latencies, and are not tied to nodes to support a healthy cluster. -* Application developers are responsible for knowing and understanding the storage requirements for their application, and how it works with the provided storage to ensure that issues do not occur when an application scales or interacts with the storage layer. - -== Other specific application storage recommendations - -* {product-title} Internal `etcd`: For the best `etcd` reliability, the lowest consistent latency storage technology is preferable. -* It is highly recommended that you use `etcd` with storage that handles serial writes (fsync) quickly, such as NVMe or SSD. Ceph, NFS, and spinning disks are not recommended. -* {rh-openstack-first} Cinder: {rh-openstack} Cinder tends to be adept in ROX access mode use cases. -* Databases: Databases (RDBMSs, NoSQL DBs, etc.) tend to perform best with dedicated block storage. diff --git a/modules/recommended-etcd-practices.adoc b/modules/recommended-etcd-practices.adoc deleted file mode 100644 index 47d00530cfeb..000000000000 --- a/modules/recommended-etcd-practices.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/recommended-host-practices.adoc - -[id="recommended-etcd-practices_{context}"] -= Recommended etcd practices - -For large and dense clusters, etcd can suffer from poor performance -if the keyspace grows excessively large and exceeds the space quota. -Periodic maintenance of etcd, including defragmentation, must be performed -to free up space in the data store. It is highly recommended that you monitor -Prometheus for etcd metrics and defragment it when required before etcd raises -a cluster-wide alarm that puts the cluster into a maintenance mode, which -only accepts key reads and deletes. Some of the key metrics to monitor are -`etcd_server_quota_backend_bytes` which is the current quota limit, -`etcd_mvcc_db_total_size_in_use_in_bytes` which indicates the actual -database usage after a history compaction, and -`etcd_debugging_mvcc_db_total_size_in_bytes` which shows the database size -including free space waiting for defragmentation. Instructions on defragging -etcd can be found in the `Defragmenting etcd data` section. - -Etcd writes data to disk, so its performance strongly depends on disk performance. Etcd -persists proposals on disk. Slow disks and disk activity from other processes might cause long -fsync latencies, causing etcd to miss heartbeats, inability to commit new proposals to the disk -on time, which can cause request timeouts and temporary leader loss. It is highly recommended to -run etcd on machines backed by SSD/NVMe disks with low latency and high throughput. - -Some of the key metrics to monitor on a deployed {product-title} cluster -are p99 of etcd disk write ahead log duration and the number of etcd leader changes. -Use Prometheus to track these metrics. `etcd_disk_wal_fsync_duration_seconds_bucket` -reports the etcd disk fsync duration, `etcd_server_leader_changes_seen_total` reports -the leader changes. To rule out a slow disk and confirm that the disk is reasonably fast, -99th percentile of the `etcd_disk_wal_fsync_duration_seconds_bucket` should be less than 10ms. - -Fio, a I/O benchmarking tool can be used to validate the hardware for etcd before or after -creating the OpenShift cluster. Run fio and analyze the results: - -Assuming container runtimes like podman or docker are installed on the machine under test and -the path etcd writes the data exists - /var/lib/etcd, run: - -.Procedure -Run the following if using podman: -[source,terminal] ----- -$ sudo podman run --volume /var/lib/etcd:/var/lib/etcd:Z quay.io/openshift-scale/etcd-perf ----- - -Alternatively, run the following if using docker: -[source,terminal] ----- -$ sudo docker run --volume /var/lib/etcd:/var/lib/etcd:Z quay.io/openshift-scale/etcd-perf ----- - -The output reports whether the disk is fast enough to host etcd by comparing the 99th percentile -of the fsync metric captured from the run to see if it is less than 10ms. - -Etcd replicates the requests among all the members, so its performance strongly depends on network -input/output (IO) latency. High network latencies result in etcd heartbeats taking longer than the -election timeout, which leads to leader elections that are disruptive to the cluster. A key metric -to monitor on a deployed {product-title} cluster is the 99th percentile of etcd network peer latency -on each etcd cluster member. Use Prometheus to track the metric. `histogram_quantile(0.99, rate(etcd_network_peer_round_trip_time_seconds_bucket[2m]))` -reports the round trip time for etcd to finish replicating the client requests between the members; -it should be less than 50 ms. diff --git a/modules/recommended-install-practices.adoc b/modules/recommended-install-practices.adoc deleted file mode 100644 index e5a2e9492b14..000000000000 --- a/modules/recommended-install-practices.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/recommended-install-practices.adoc - -[id="recommended-install-practices_{context}"] -= Recommended practices for installing large scale clusters - -When installing large clusters or scaling the cluster to larger node counts, -set the cluster network `cidr` accordingly in your `install-config.yaml` -file before you install the cluster: - -[source,yaml] ----- -networking: - clusterNetwork: - - cidr: 10.128.0.0/14 - hostPrefix: 23 - machineCIDR: 10.0.0.0/16 - networkType: OpenShiftSDN - serviceNetwork: - - 172.30.0.0/16 ----- - -The default cluster network `cidr` `10.128.0.0/14` cannot be used if the cluster -size is more than 500 nodes. It must be set to `10.128.0.0/12` or -`10.128.0.0/10` to get to larger node counts beyond 500 nodes. diff --git a/modules/recommended-node-host-practices.adoc b/modules/recommended-node-host-practices.adoc deleted file mode 100644 index 6ec65e426e13..000000000000 --- a/modules/recommended-node-host-practices.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/recommended-host-practices.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="recommended-node-host-practices_{context}"] -= Recommended node host practices - -The {product-title} node configuration file contains important options. For -example, two parameters control the maximum number of pods that can be scheduled -to a node: `podsPerCore` and `maxPods`. - -When both options are in use, the lower of the two values limits the number of -pods on a node. Exceeding these values can result in: - -* Increased CPU utilization. -* Slow pod scheduling. -* Potential out-of-memory scenarios, depending on the amount of memory in the node. -* Exhausting the pool of IP addresses. -* Resource overcommitting, leading to poor user application performance. - -[IMPORTANT] -==== -In Kubernetes, a pod that is holding a single container actually uses two -containers. The second container is used to set up networking prior to the -actual container starting. Therefore, a system running 10 pods will actually -have 20 containers running. -==== - -[NOTE] -==== -Disk IOPS throttling from the cloud provider might have an impact on CRI-O and kubelet. -They might get overloaded when there are large number of I/O intensive pods running on -the nodes. It is recommended that you monitor the disk I/O on the nodes and use volumes -with sufficient throughput for the workload. -==== - -`podsPerCore` sets the number of pods the node can run based on the number of -processor cores on the node. For example, if `podsPerCore` is set to `10` on a -node with 4 processor cores, the maximum number of pods allowed on the node will -be `40`. - -[source,yaml] ----- -kubeletConfig: - podsPerCore: 10 ----- - -Setting `podsPerCore` to `0` disables this limit. The default is `0`. -`podsPerCore` cannot exceed `maxPods`. - -`maxPods` sets the number of pods the node can run to a fixed value, regardless -of the properties of the node. - -[source,yaml] ----- - kubeletConfig: - maxPods: 250 ----- diff --git a/modules/recommended-requirements-central-services.adoc b/modules/recommended-requirements-central-services.adoc new file mode 100644 index 000000000000..1f87eb6f93cf --- /dev/null +++ b/modules/recommended-requirements-central-services.adoc @@ -0,0 +1,156 @@ +// Module included in the following assemblies: +// +// * installing/acs-recommended-requirements.adoc +:_mod-docs-content-type: CONCEPT +[id="recommended-requirements-central-services_{context}"] += Central services (self-managed) + +[NOTE] +==== +If you are using {rh-rhacscs-first}, you do not need to review the requirements for Central services, because they are managed by Red{nbsp}Hat. You only need to look at the requirements for secured cluster services. +==== + +Central services contain the following components: + +* Central +* Central DB +* StackRox Scanner +* Scanner V4 + +[id="recommended-requirements-central-services-central_{context}"] +== Central + +=== Memory and CPU requirements + +The following table lists the minimum memory and CPU values required to run Central. To determine sizing, consider the following data: + +* The total number of monitored deployments across all secured clusters that are connected to a single Central deployment +* The number of concurrent web portal users + +|=== +| Deployments | Concurrent web portal users | CPU | Memory + +| < 25,000 +| 1 user +| 2 cores +| 8 GiB + +| < 25,000 +| < 5 users +| 2 cores +| 8 GiB + +| < 50,000 +| 1 user +| 2 cores +| 12 GiB + +| < 50,000 +| < 5 users +| 6 cores +| 16 GiB +|=== + +[id="recommended-requirements-central-db-services-central_{context}"] +== Central DB + +=== Memory and CPU requirements + +The following table lists the minimum memory and CPU values required to run Central DB. To determine sizing, consider the following data: + +* The total number of monitored deployments across all secured clusters that are connected to a single Central deployment +* The number of concurrent web portal users + +|=== +| Deployments | Concurrent web portal users | CPU | Memory + +| < 25,000 +| 1 user +| 12 cores +| 32 GiB + +| < 25,000 +| < 5 users +| 24 cores +| 32 GiB + +| < 50,000 +| 1 user +| 16 cores +| 32 GiB + +| < 50,000 +| < 5 users +| 32 cores +| 32 GiB +|=== + +[id="recommended-requirements-central-services-scanner-stackrox_{context}"] +== StackRox Scanner + +The following table lists the minimum memory and CPU values required for the StackRox Scanner deployment in the Central cluster. The table includes the number of unique images deployed in all secured clusters. + +|=== +| Number of unique Images | Replicas | CPU | Memory + +| < 100 +| 1 replica +| 1 core +| 1.5 GiB + +| < 500 +| 1 replica +| 2 cores +| 2.5 GiB + +| < 2000 +| 2 replicas +| 2 cores +| 2.5 GiB + +| < 5000 +| 3 replicas +| 2 cores +| 2.5 GiB +|=== + +[id="recommended-requirements-central-services-scanner-scannerv4_{context}"] +== Scanner V4 + +The following table lists the minimum memory and CPU values required for the Scanner V4 deployment in the Central cluster. The table includes the number of unique images deployed in all secured clusters. + +=== Scanner V4 Indexer + +|=== +|Number of unique images|Replicas|CPU|Memory + +|< 100|1|2 cores|0.5 GiB +|< 500|1|2 cores|0.5 GiB +|< 2000|2|3 cores|1 GiB +|< 5000|2|5 cores|1 GiB +|< 10000|3|6 cores|1.5 GiB +|=== + +=== Scanner V4 Matcher + +|=== +|Number of unique images| Replicas | CPU | Memory + +|< 100|1|1 core|1.3 GiB +|< 500|1|1 core|1.4 GiB +|< 2000|2|3 cores|1.5 GiB +|< 5000|2|3 cores|1.6 GiB +|< 10000|3|3 cores|1.7 GiB +|=== + +=== Scanner V4 DB + +|=== +|Number of unique images| Replicas | CPU | Memory + +|< 100|1|1 core|4.5 GiB +|< 500|1|3 cores|5 GiB +|< 2000|1|6 cores|6 GiB +|< 5000|1|6 cores|6 GiB +|< 10000|1|8 cores|6 GiB +|=== diff --git a/modules/recommended-requirements-secured-cluster-services.adoc b/modules/recommended-requirements-secured-cluster-services.adoc new file mode 100644 index 000000000000..8a5f786ba5b2 --- /dev/null +++ b/modules/recommended-requirements-secured-cluster-services.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// * installing/acs-recommended-requirements.adoc +// * cloud_service/acscs-recommended-requirements.adoc +:_mod-docs-content-type: CONCEPT +[id="recommended-requirements-secured-cluster-services_{context}"] += Secured cluster services + +Secured cluster services contain the following components: + +* Sensor +* Admission controller +* Collector ++ +[NOTE] +==== +Collector component is not included on this page. Required resource requirements are listed on the default resource requirements page. +==== + +[id="recommended-requirements-secured-cluster-services-sensor_{context}"] +== Sensor + +Sensor monitors your Kubernetes and OpenShift Container Platform clusters. These services currently deploy in a single deployment, which handles interactions with the Kubernetes API and coordinates with Collector. + + +== Memory and CPU requirements + +The following table lists the minimum memory and CPU values required to run Sensor on a secured cluster. + +|=== +| Deployments | CPU | Memory + +| < 25,000 +| 2 cores +| 10 GiB + +| < 50,000 +| 2 cores +| 20 GiB +|=== + +[id="recommended-requirements-secured-cluster-services-admission-controller_{context}"] +== Admission controller + +The admission controller prevents users from creating workloads that violate policies that you configure. + +== Memory and CPU requirements + +The following table lists the minimum memory and CPU values required to run the admission controller on a secured cluster. + +|=== +| Deployments | CPU | Memory + +| < 25,000 +| 0.5 cores +| 300 MiB + +| < 50,000 +| 0.5 cores +| 600 MiB +|=== diff --git a/modules/recommended-scale-practices.adoc b/modules/recommended-scale-practices.adoc deleted file mode 100644 index ecd05b134c3b..000000000000 --- a/modules/recommended-scale-practices.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/recommended-cluster-scaling-practices.adoc - -[id="recommended-scale-practices_{context}"] -= Recommended practices for scaling the cluster - -When scaling up the cluster to higher node counts: - -* Spread nodes across all of the available zones for higher availability. -* Scale up by no more than 25 to 50 machines at once. -* Consider creating new machine sets in each available zone with alternative instance types of similar size to help mitigate any periodic provider capacity constraints. For example, on AWS, use m5.large and m5d.large. - -[NOTE] -==== -Cloud providers might implement a quota for API services. Therefore, gradually scale the cluster. -==== - -The controller might not be able to create the machines if the replicas in the machine sets are set to higher numbers all at one time. The number of requests the cloud platform, which {product-title} is deployed on top of, is able to handle impacts the process. The controller will start to query more while trying to create, check, and update the machines with the status. The cloud platform on which {product-title} is deployed has API request limits and excessive queries might lead to machine creation failures due to cloud platform limitations. - -Enable machine health checks when scaling to large node counts. In case of failures, -the health checks monitor the condition and automatically repair unhealthy machines. - -[NOTE] -==== -When scaling large and dense clusters to lower node counts, it might take large -amounts of time as the process involves draining or evicting the objects running on -the nodes being terminated in parallel. Also, the client might start to throttle the -requests if there are too many objects to evict. The default client QPS and burst -rates are currently set to `5` and `10` respectively and they cannot be modified -in {product-title}. -==== diff --git a/modules/red-hat-marketplace-features.adoc b/modules/red-hat-marketplace-features.adoc deleted file mode 100644 index 77cf12ef82ea..000000000000 --- a/modules/red-hat-marketplace-features.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/red-hat-marketplace.adoc - -[id="red-hat-marketplace-features_{context}"] -= Red Hat Marketplace features - -Cluster administrators can use link:https://marketplace.redhat.com/en-us/documentation/getting-started[the Red Hat Marketplace] to manage software on {product-title}, give developers self-service access to deploy application instances, and correlate application usage against a quota. - -[id="marketplace-clusters_{context}"] -== Connect {product-title} clusters to the Marketplace - -Cluster administrators can install a common set of applications on {product-title} clusters that connect to the Marketplace. They can also use the Marketplace to track cluster usage against subscriptions or quotas. Users that they add by using the Marketplace have their product usage tracked and billed to their organization. - -During the link:https://marketplace.redhat.com/en-us/documentation/clusters[cluster connection process], -a Marketplace Operator is installed that updates the image registry secret, manages the catalog, and reports application usage. - -[id="marketplace-install-applications_{context}"] -== Install applications - -Cluster administrators can link:https://marketplace.redhat.com/en-us/documentation/operators[install Marketplace applications] from within OperatorHub in {product-title}, or from the link:https://marketplace.redhat.com[Marketplace web application]. - -You can access installed applications from the web console by clicking **Operators > Installed Operators**. - -[id="marketplace-deploy_{context}"] -== Deploy applications from different perspectives - -You can deploy Marketplace applications from the web console's Administrator and Developer perspectives. - -[discrete] -=== The Developer perspective - -Developers can access newly installed capabilities by using the Developer perspective. - -For example, after a database Operator is installed, a developer can create an instance from the catalog within their project. Database usage is aggregated and reported to the cluster administrator. - -This perspective does not include Operator installation and application usage tracking. - -[discrete] -=== The Administrator perspective - -Cluster administrators can access Operator installation and application usage information from the Administrator perspective. - -They can also launch application instances by browsing custom resource definitions (CRDs) in the *Installed Operators* list. \ No newline at end of file diff --git a/modules/redirecting-image-pulls-from-a-source-registry-to-a-mirrored-registry.adoc b/modules/redirecting-image-pulls-from-a-source-registry-to-a-mirrored-registry.adoc new file mode 100644 index 000000000000..7710380a5db6 --- /dev/null +++ b/modules/redirecting-image-pulls-from-a-source-registry-to-a-mirrored-registry.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="redirecting-image-pulls-from-a-source-registry-to-a-mirrored-registry_{context}"] += Redirecting image pulls from a source registry to a mirrored registry + +{rh-rhacs-first} supports scanning images from registry mirrors that you have configured by using one of the following {ocp} custom resources (CRs): + +* `ImageContentSourcePolicy` (ICSP) +* `ImageDigestMirrorSet` (IDMS) +* `ImageTagMirrorSet` (ITMS) + +For more information about how to configure image registry repository mirroring, see "Configuring image registry repository mirroring". + +[IMPORTANT] +==== +To scan images from registry mirrors, you must configure delegated image scanning. +==== + +For more information about how to configure delegated image scanning, see "Accessing delegated image scanning". \ No newline at end of file diff --git a/modules/registry-accessing-directly.adoc b/modules/registry-accessing-directly.adoc deleted file mode 100644 index 2462b4b0a442..000000000000 --- a/modules/registry-accessing-directly.adoc +++ /dev/null @@ -1,162 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/accessing-the-registry.adoc -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc - -[id="registry-accessing-directly_{context}"] -= Accessing registry directly from the cluster - -You can access the registry from inside the cluster. - -.Procedure - -Access the registry from the cluster by using internal routes: - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -. Access the node by getting the node's address: -+ -[source,terminal] ----- -$ oc get nodes ----- -+ -[source,terminal] ----- -$ oc debug nodes/<node_address> ----- - -. To enable access to tools such as `oc` and `podman` on the node, run the following command: -+ -[source,terminal] ----- -sh-4.2# chroot /host ----- -+ -endif::[] - -. Log in to the container image registry by using your access token: -+ -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[source,terminal] ----- -sh-4.2# oc login -u kubeadmin -p <password_from_install_log> https://api-int.<cluster_name>.<base_domain>:6443 ----- -+ -[source,terminal] ----- -sh-4.2# podman login -u kubeadmin -p $(oc whoami -t) image-registry.openshift-image-registry.svc:5000 ----- -endif::[] - -+ -ifdef::openshift-dedicated[] -[source,terminal] ----- -$ podman login -u $(oc whoami) -p $(oc whoami -t) $(oc -n openshift-image-registry get route default-route -o jsonpath='{.spec.host}') ----- -endif::[] - -+ -You should see a message confirming login, such as: -+ -[source,terminal] ----- -Login Succeeded! ----- -+ -[NOTE] -==== -You can pass any value for the user name; the token contains all necessary -information. Passing a user name that contains colons will result in a login -failure. - -Since the Image Registry Operator creates the route, it will likely be similar to -`default-route-openshift-image-registry.<cluster_name>`. -==== -+ -. Perform `podman pull` and `podman push` operations against your registry: -+ -[IMPORTANT] -==== -You can pull arbitrary images, but if you have the *system:registry* role -added, you can only push images to the registry in your project. -==== -+ -In the following examples, use: -+ -|==== -|Component |Value - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -|*<registry_ip>* -|`172.30.124.220` - -|*<port>* -|`5000` -endif::[] - -ifdef::openshift-dedicated[] -|*<registry_url>* -|`oc -n openshift-image-registry get route default-route -o jsonpath='{.spec.host}'` -endif::[] - -|*<project>* -|`openshift` - -|*<image>* -|`image` - -|*<tag>* -| omitted (defaults to `latest`) -|==== - -.. Pull an arbitrary image: -+ -[source,terminal] ----- -$ podman pull name.io/image ----- - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -.. Tag the new image with the form `<registry_ip>:<port>/<project>/<image>`. -The project name must appear in this pull specification for {product-title} to -correctly place and later access the image in the registry: -+ -[source,terminal] ----- -$ podman tag name.io/image image-registry.openshift-image-registry.svc:5000/openshift/image ----- -endif::[] -ifdef::openshift-dedicated[] -.. Tag the new image with the form `<registry_url>:<project>/<image>`. -The project name must appear in this pull specification for {product-title} to -correctly place and later access the image in the registry: -+ -[source,terminal] ----- -$ podman tag name.io/image $(oc -n openshift-image-registry get route default-route -o jsonpath='{.spec.host}')/openshift/image ----- -endif::[] -+ -[NOTE] -==== -You must have the `system:image-builder` role for the specified -project, which allows the user to write or push an image. Otherwise, the -`podman push` in the next step will fail. To test, you can create a new project -to push the image. -==== - -.. Push the newly tagged image to your registry: -+ -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[source,terminal] ----- -$ podman push image-registry.openshift-image-registry.svc:5000/openshift/image ----- -endif::[] -ifdef::openshift-dedicated[] -[source,terminal] ----- -$ podman push $(oc -n openshift-image-registry get route default-route -o jsonpath='{.spec.host}')/openshift/image ----- -endif::[] diff --git a/modules/registry-accessing-metrics.adoc b/modules/registry-accessing-metrics.adoc deleted file mode 100644 index a9c48683a415..000000000000 --- a/modules/registry-accessing-metrics.adoc +++ /dev/null @@ -1,98 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/accessing-the-registry.adoc - -[id="registry-accessing-metrics_{context}"] -= Accessing registry metrics - -The OpenShift Container Registry provides an endpoint for -link:https://prometheus.io/docs/introduction/overview/[Prometheus metrics]. -Prometheus is a stand-alone, open source systems monitoring and alerting -toolkit. - -The metrics are exposed at the *_/extensions/v2/metrics_* path of the registry -endpoint. - -// Recommended link to extended registry configuration assembly. - -.Procedure - -There are two ways in which you can access the metrics, running a metrics query -or using the cluster role. - -*Metrics query* - -. Run a metrics query, for example: -+ -[source,terminal] ----- -$ curl --insecure -s -u <user>:<secret> \ <1> - https://image-registry.openshift-image-registry.svc:5000/extensions/v2/metrics | grep imageregistry | head -n 20 ----- -+ -.Example output -[source,terminal] ----- -# HELP imageregistry_build_info A metric with a constant '1' value labeled by major, minor, git commit & git version from which the image registry was built. -# TYPE imageregistry_build_info gauge -imageregistry_build_info{gitCommit="9f72191",gitVersion="v3.11.0+9f72191-135-dirty",major="3",minor="11+"} 1 -# HELP imageregistry_digest_cache_requests_total Total number of requests without scope to the digest cache. -# TYPE imageregistry_digest_cache_requests_total counter -imageregistry_digest_cache_requests_total{type="Hit"} 5 -imageregistry_digest_cache_requests_total{type="Miss"} 24 -# HELP imageregistry_digest_cache_scoped_requests_total Total number of scoped requests to the digest cache. -# TYPE imageregistry_digest_cache_scoped_requests_total counter -imageregistry_digest_cache_scoped_requests_total{type="Hit"} 33 -imageregistry_digest_cache_scoped_requests_total{type="Miss"} 44 -# HELP imageregistry_http_in_flight_requests A gauge of requests currently being served by the registry. -# TYPE imageregistry_http_in_flight_requests gauge -imageregistry_http_in_flight_requests 1 -# HELP imageregistry_http_request_duration_seconds A histogram of latencies for requests to the registry. -# TYPE imageregistry_http_request_duration_seconds summary -imageregistry_http_request_duration_seconds{method="get",quantile="0.5"} 0.01296087 -imageregistry_http_request_duration_seconds{method="get",quantile="0.9"} 0.014847248 -imageregistry_http_request_duration_seconds{method="get",quantile="0.99"} 0.015981195 -imageregistry_http_request_duration_seconds_sum{method="get"} 12.260727916000022 ----- -<1> `<user>` can be arbitrary, but `<secret>` must match the value specified in the -registry configuration. - -*Cluster role* - -. Create a cluster role if you do not already have one to access the metrics: -+ -[source,terminal] ----- -$ cat <<EOF | oc create -f - -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: prometheus-scraper -rules: -- apiGroups: - - image.openshift.io - resources: - - registry/metrics - verbs: - - get -EOF ----- - -. Add this role to a user, run the following command: -+ -[source,terminal] ----- -$ oc adm policy add-cluster-role-to-user prometheus-scraper <username> ----- - -. Access the metrics using cluster role. The part of -the configuration file responsible for metrics should look like this: -+ -[source,yaml] ----- -openshift: - version: 1.0 - metrics: - enabled: true -... ----- diff --git a/modules/registry-authentication-enabled-registry-overview.adoc b/modules/registry-authentication-enabled-registry-overview.adoc deleted file mode 100644 index e290495c3862..000000000000 --- a/modules/registry-authentication-enabled-registry-overview.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/registry-options.adoc - -[id="registry-authentication-enabled-registry-overview_{context}"] -= Authentication enabled Red Hat registry - -All container images available through the Container images section of the Red Hat Ecosystem Catalog are hosted -on an image registry, `registry.redhat.io`. - -The registry, `registry.redhat.io`, requires authentication for access to -images and hosted content on {product-title}. Following the move to the new -registry, the existing registry will be available for a period of time. - -[NOTE] -==== -{product-title} pulls images from `registry.redhat.io`, so you must configure -your cluster to use it. -==== - -The new registry uses standard OAuth mechanisms for authentication, -with the following methods: - -* *Authentication token.* Tokens, which are generated by administrators, -are service accounts that give systems the ability to authenticate against the -container image registry. -Service accounts are not affected by changes in user accounts, so the token -authentication method is reliable and resilient. This is the only supported -authentication option for production clusters. -* *Web username and password.* This is the standard set of credentials you use -to log in to resources such as `access.redhat.com`. -While it is possible to use this authentication method with {product-title}, it -is not supported for production deployments. Restrict this authentication method -to stand-alone projects outside {product-title}. - -You can use `podman login` with your credentials, either username and password -or authentication token, to access content on the new registry. - -All imagestreams point to the new registry, which uses the installation pull secret to authenticate. - -You must place your credentials in either of the following places: - -* *`openshift` namespace*. Your credentials must exist in the OpenShift -namespace so that the imagestreams in the `openshift` namespace can import. -* *Your host*. Your credentials must exist on your host because Kubernetes -uses the credentials from your host when it goes to pull images. - - -//.Additional resources -//* link:https://access.redhat.com/terms-based-registry[Authentication tokens] diff --git a/modules/registry-change-management-state.adoc b/modules/registry-change-management-state.adoc deleted file mode 100644 index 376be03412c4..000000000000 --- a/modules/registry-change-management-state.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc - -[id="registry-change-management-state_{context}"] -= Changing the image registry's management state - -To start the image registry, you must change the Image Registry Operator configuration's `managementState` from `Removed` to `Managed`. - -.Procedure - -* Change `managementState` Image Registry Operator configuration from `Removed` to `Managed`. For example: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io cluster --type merge --patch '{"spec":{"managementState":"Managed"}}' ----- diff --git a/modules/registry-checking-the-status-of-registry-pods.adoc b/modules/registry-checking-the-status-of-registry-pods.adoc deleted file mode 100644 index 849376c84367..000000000000 --- a/modules/registry-checking-the-status-of-registry-pods.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/accessing-the-registry.adoc - -[id="checking-the-status-of-registry-pods_{context}"] -= Checking the status of the registry pods - -As a cluster administrator, you can list the image registry pods running in the `openshift-image-registry` project and check their status. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. List the pods in the `openshift-image-registry` project and view their status: -+ -[source,terminal] ----- -$ oc get pods -n openshift-image-registry ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -cluster-image-registry-operator-764bd7f846-qqtpb 1/1 Running 0 78m -image-registry-79fb4469f6-llrln 1/1 Running 0 77m -node-ca-hjksc 1/1 Running 0 73m -node-ca-tftj6 1/1 Running 0 77m -node-ca-wb6ht 1/1 Running 0 77m -node-ca-zvt9q 1/1 Running 0 74m ----- diff --git a/modules/registry-configuring-storage-aws-user-infra.adoc b/modules/registry-configuring-storage-aws-user-infra.adoc deleted file mode 100644 index 3b34f1f20af7..000000000000 --- a/modules/registry-configuring-storage-aws-user-infra.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * registry/configuring_registry_storage-aws-user-infrastructure.adoc - -[id="registry-configuring-storage-aws-user-infra_{context}"] -= Configuring registry storage for AWS with user-provisioned infrastructure - -During installation, your cloud credentials are sufficient to create an Amazon S3 bucket -and the Registry Operator will automatically configure storage. - -If the Registry Operator cannot create an S3 bucket and automatically configure -storage, you can create an S3 bucket and configure storage with the following -procedure. - -.Prerequisites - -* You have a cluster on AWS with user-provisioned infrastructure. -* For Amazon S3 storage, the secret is expected to contain two keys: -** `REGISTRY_STORAGE_S3_ACCESSKEY` -** `REGISTRY_STORAGE_S3_SECRETKEY` - -.Procedure - -Use the following procedure if the Registry Operator cannot create an S3 bucket -and automatically configure storage. - -. Set up a link:https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuoverview.html#mpu-abort-incomplete-mpu-lifecycle-config[Bucket Lifecycle Policy] -to abort incomplete multipart uploads that are one day old. - -. Fill in the storage configuration in -`configs.imageregistry.operator.openshift.io/cluster`: -+ -[source,terminal] ----- -$ oc edit configs.imageregistry.operator.openshift.io/cluster ----- -+ -.Example configuration -[source,yaml] ----- -storage: - s3: - bucket: <bucket-name> - region: <region-name> ----- - -[WARNING] -==== -To secure your registry images in AWS, link:https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-publicaccessblockconfiguration.html[block public access] -to the S3 bucket. -==== diff --git a/modules/registry-configuring-storage-azure-gov-cloud.adoc b/modules/registry-configuring-storage-azure-gov-cloud.adoc deleted file mode 100644 index 207bbf3b0c42..000000000000 --- a/modules/registry-configuring-storage-azure-gov-cloud.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -//* registry/configuring_registry_storage-azure.adoc - -[id="registry-configuring-storage-azure-gov-cloud_{context}"] -= Configuring registry storage for Azure Government - -During installation, your cloud credentials are sufficient to create Azure Blob -Storage, and the Registry Operator automatically configures storage. - -.Prerequisites - -* A cluster on Azure with user-provisioned infrastructure in a government region. -* To configure registry storage for Azure, provide Registry Operator -cloud credentials. -* For Azure storage, the secret is expected to contain one key: -** `REGISTRY_STORAGE_AZURE_ACCOUNTKEY` - -.Procedure - -. Create an link:https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal[Azure storage container]. - -. Fill in the storage configuration in `configs.imageregistry.operator.openshift.io/cluster`: -+ -[source,terminal] ----- -$ oc edit configs.imageregistry.operator.openshift.io/cluster ----- -+ -.Example configuration -[source,yaml] ----- -storage: - azure: - accountName: <storage-account-name> - container: <container-name> - cloudName: AzureUSGovernmentCloud <1> ----- -<1> `cloudName` is the name of the Azure cloud environment, which can be used to configure the Azure SDK with the appropriate Azure API endpoints. Defaults to `AzurePublicCloud`. You can also set `cloudName` to `AzureUSGovernmentCloud`, `AzureChinaCloud`, or `AzureGermanCloud` with sufficient credentials. diff --git a/modules/registry-configuring-storage-azure-user-infra.adoc b/modules/registry-configuring-storage-azure-user-infra.adoc deleted file mode 100644 index 6f3e6806054e..000000000000 --- a/modules/registry-configuring-storage-azure-user-infra.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -//* registry/configuring_registry_storage-azure.adoc - -[id="registry-configuring-storage-azure-user-infra_{context}"] -= Configuring registry storage for Azure - -During installation, your cloud credentials are sufficient to create Azure Blob -Storage, and the Registry Operator automatically configures storage. - -.Prerequisites - -* A cluster on Azure with user-provisioned infrastructure. -* To configure registry storage for Azure, provide Registry Operator -cloud credentials. -* For Azure storage the secret is expected to contain one key: -** `REGISTRY_STORAGE_AZURE_ACCOUNTKEY` - -.Procedure - -. Create an link:https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal[Azure storage container]. - -. Fill in the storage configuration in `configs.imageregistry.operator.openshift.io/cluster`: -+ -[source,terminal] ----- -$ oc edit configs.imageregistry.operator.openshift.io/cluster ----- -+ -.Example configuration -[source,yaml] ----- -storage: - azure: - accountName: <storage-account-name> - container: <container-name> ----- diff --git a/modules/registry-configuring-storage-baremetal.adoc b/modules/registry-configuring-storage-baremetal.adoc deleted file mode 100644 index c75976e57d4d..000000000000 --- a/modules/registry-configuring-storage-baremetal.adoc +++ /dev/null @@ -1,136 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-baremetal -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc - -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:ibm-z: -:restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-power"] -:ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:ibm-power: -:restricted: -endif::[] - -[id="registry-configuring-storage-baremetal_{context}"] -ifndef::ibm-z,ibm-power[] -= Configuring registry storage for bare metal and other manual installations -endif::ibm-z,ibm-power[] -ifdef::ibm-z[] -= Configuring registry storage for IBM Z -endif::ibm-z[] -ifdef::ibm-power[] -= Configuring registry storage for IBM Power Systems -endif::ibm-power[] - -As a cluster administrator, following installation you must configure your -registry to use storage. - -.Prerequisites - -* Cluster administrator permissions. -* A cluster -ifndef::ibm-z,ibm-power[that uses manually-provisioned {op-system-first} nodes, such as bare metal.] -ifdef::ibm-z[on IBM Z.] -ifdef::ibm-power[on IBM Power Systems.] -ifndef::ibm-z[* Persistent storage provisioned for your cluster, such as Red Hat OpenShift Container Storage.] -ifdef::ibm-z[* Persistent storage provisioned for your cluster.] -+ -[IMPORTANT] -==== -{product-title} supports `ReadWriteOnce` access for image registry storage when you have only one replica. To deploy an image registry that supports high availability with two or more replicas, `ReadWriteMany` access is required. -==== -+ -* Must have 100Gi capacity. - -.Procedure - -. To configure your registry to use storage, change the `spec.storage.pvc` in -the `configs.imageregistry/cluster` resource. -+ -[NOTE] -==== -When using shared storage, review your security settings to prevent outside access. -==== - -. Verify that you do not have a registry pod: -+ -[source,terminal] ----- -$ oc get pod -n openshift-image-registry ----- -+ -[NOTE] -===== -If the storage type is `emptyDIR`, the replica number cannot be greater than `1`. -===== -+ -. Check the registry configuration: -+ -[source,terminal] ----- -$ oc edit configs.imageregistry.operator.openshift.io ----- -+ -.Example output -[source,yaml] ----- -storage: - pvc: - claim: ----- -+ -Leave the `claim` field blank to allow the automatic creation of an -`image-registry-storage` PVC. -+ -. Check the `clusteroperator` status: -+ -[source,terminal] ----- -$ oc get clusteroperator image-registry ----- -+ -. Ensure that your registry is set to managed to enable building and pushing of images. -+ -* Run: -+ ----- -$ oc edit configs.imageregistry/cluster ----- -+ -Then, change the line -+ ----- -managementState: Removed ----- -+ -to -+ ----- -managementState: Managed ----- - -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:!ibm-z: -:!restricted: -endif::[] -ifeval::["{context}" == "installing-ibm-power"] -:!ibm-power: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-power"] -:!ibm-power: -:!restricted: -endif::[] diff --git a/modules/registry-configuring-storage-gcp-user-infra.adoc b/modules/registry-configuring-storage-gcp-user-infra.adoc deleted file mode 100644 index 3553522333d0..000000000000 --- a/modules/registry-configuring-storage-gcp-user-infra.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring_registry_storage-gcp-user-infrastructure.adoc - -[id="registry-configuring-storage-gcp-user-infra_{context}"] -= Registry storage for GCP with user-provisioned infrastructure - -You must set up the storage medium manually and configure the settings in the -registry custom resource (CR). - -.Prerequisites - -* A cluster on GCP with user-provisioned infrastructure. -* To configure registry storage for GCP, you need to provide Registry Operator -cloud credentials. -* For GCS on GCP storage, the secret is expected to contain one key whose value is the -contents of a credentials file provided by GCP: -** `REGISTRY_STORAGE_GCS_KEYFILE` - - -.Procedure - -//// -Stub for procedure to manually set storage medium. -//// diff --git a/modules/registry-configuring-storage-openstack-user-infra.adoc b/modules/registry-configuring-storage-openstack-user-infra.adoc deleted file mode 100644 index 48a44085f4cc..000000000000 --- a/modules/registry-configuring-storage-openstack-user-infra.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring_registry_storage-openstack-user-infrastructure.adoc - -[id="registry-configuring-storage-openstack-user-infra_{context}"] -= Registry storage for {rh-openstack} with user-provisioned infrastructure - -You must set up the storage medium manually and configure the settings in the -registry custom resource (CR). - -.Prerequisites - -* A cluster on {rh-openstack-first} with user-provisioned infrastructure. -* To configure registry storage for {rh-openstack}, you need to provide Registry Operator -cloud credentials. -* For Swift on {rh-openstack} storage, the secret is expected to contain the following two keys: - -** `REGISTRY_STORAGE_SWIFT_USER` -** `REGISTRY_STORAGE_SWIFT_PASSWORD` diff --git a/modules/registry-configuring-storage-vsphere.adoc b/modules/registry-configuring-storage-vsphere.adoc deleted file mode 100644 index e324896d86b0..000000000000 --- a/modules/registry-configuring-storage-vsphere.adoc +++ /dev/null @@ -1,100 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc - -[id="registry-configuring-storage-vsphere_{context}"] -= Configuring registry storage for VMware vSphere - -As a cluster administrator, following installation you must configure your registry to use storage. - -.Prerequisites - -* Cluster administrator permissions. -* A cluster on VMware vSphere. -* Persistent storage provisioned for your cluster, such as Red Hat OpenShift Container Storage. -+ -[IMPORTANT] -==== -{product-title} supports `ReadWriteOnce` access for image registry storage when you have only one replica. To deploy an image registry that supports high availability with two or more replicas, `ReadWriteMany` access is required. -==== -+ -* Must have "100Gi" capacity. - -[IMPORTANT] -==== -Testing shows issues with using the NFS server on RHEL as storage backend for -core services. This includes the OpenShift Container Registry and Quay, -Prometheus for monitoring storage, and Elasticsearch for logging storage. -Therefore, using RHEL NFS to back PVs used by core services is not recommended. - -Other NFS implementations on the marketplace might not have these issues. -Contact the individual NFS implementation vendor for more information on any -testing that was possibly completed against these {product-title} core -components. -==== - -.Procedure - -. To configure your registry to use storage, change the `spec.storage.pvc` in the `configs.imageregistry/cluster` resource. -+ -[NOTE] -==== -When using shared storage, review your security settings to prevent outside access. -==== - -. Verify that you do not have a registry pod: -+ -[source,terminal] ----- -$ oc get pod -n openshift-image-registry ----- -+ -[NOTE] -===== -If the storage type is `emptyDIR`, the replica number cannot be greater than `1`. -===== -+ -. Check the registry configuration: -+ -[source,terminal] ----- -$ oc edit configs.imageregistry.operator.openshift.io ----- -+ -.Example output -[source,yaml] ----- -storage: - pvc: - claim: <1> ----- -+ -<1> Leave the `claim` field blank to allow the automatic creation of an `image-registry-storage` PVC. - -. Check the `clusteroperator` status: -+ -[source,terminal] ----- -$ oc get clusteroperator image-registry ----- -//+ -//There will be warning similar to: -//+ -//---- -//- lastTransitionTime: 2019-03-26T12:45:46Z -//message: storage backend not configured -//reason: StorageNotConfigured -//status: "True" -//type: Degraded -//---- diff --git a/modules/registry-exposing-secure-registry-manually.adoc b/modules/registry-exposing-secure-registry-manually.adoc deleted file mode 100644 index 0a3954e35a27..000000000000 --- a/modules/registry-exposing-secure-registry-manually.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/securing-exposing-registry.adoc -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc - -[id="registry-exposing-secure-registry-manually_{context}"] -= Exposing a secure registry manually - -Instead of logging in to the {product-title} registry from within the cluster, -you can gain external access to it by exposing it with a route. This allows you -to log in to the registry from outside the cluster using the route address, and -to tag and push images using the route host. - -.Prerequisites: - -* The following prerequisites are automatically performed: -** Deploy the Registry Operator. -** Deploy the Ingress Operator. - -.Procedure - -You can expose the route by using `DefaultRoute` parameter in the -`configs.imageregistry.operator.openshift.io` resource or by using custom routes. - -To expose the registry using `DefaultRoute`: - -. Set `DefaultRoute` to `True`: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io/cluster --patch '{"spec":{"defaultRoute":true}}' --type=merge ----- -+ -. Log in with `podman`: -+ -[source,terminal] ----- -$ HOST=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}') ----- -+ -[source,terminal] ----- -$ podman login -u $(oc whoami) -p $(oc whoami -t) --tls-verify=false $HOST <1> ----- -<1> `--tls-verify=false` is needed if the cluster's default certificate for routes -is untrusted. You can set a custom, trusted certificate as the default -certificate with the Ingress Operator. - - -To expose the registry using custom routes: - -. Create a secret with your route's TLS keys: -+ -[source,terminal] ----- -$ oc create secret tls public-route-tls \ - -n openshift-image-registry \ - --cert=</path/to/tls.crt> \ - --key=</path/to/tls.key> ----- -+ -This step is optional. If you do not create a secret, the route uses the -default TLS configuration from the Ingress Operator. -+ -. On the Registry Operator: -+ -[source,yaml] ----- -spec: - routes: - - name: public-routes - hostname: myregistry.mycorp.organization - secretName: public-route-tls -... ----- -+ -[NOTE] -==== -Only set `secretName` if you are providing a custom TLS configuration for the -registry's route. -==== diff --git a/modules/registry-integrated-openshift-registry.adoc b/modules/registry-integrated-openshift-registry.adoc deleted file mode 100644 index ebd3d6642ede..000000000000 --- a/modules/registry-integrated-openshift-registry.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -//* registry/registry-options -//* registry/architecture-component-imageregistry - -[id="registry-integrated-openshift-registry_{context}"] -= Integrated {product-title} registry -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -{product-title} provides a built-in container image registry that runs as a -standard workload on the cluster. The registry is configured and managed by an -infrastructure Operator. It provides an out-of-the-box solution for users to -manage the images that run their workloads, and runs on top of the existing -cluster infrastructure. This registry can be scaled up or down like any other -cluster workload and does not require specific infrastructure provisioning. In -addition, it is integrated into the cluster user authentication and -authorization system, which means that access to create and retrieve images is -controlled by defining user permissions on the image resources. - -The registry is typically used as a publication target for images built on the -cluster, as well as being a source of images for workloads running on the cluster. -When a new image is pushed to the registry, the cluster is notified of the -new image and other components can react to and consume the updated image. - -Image data is stored in two locations. The actual image data is stored in a -configurable storage location, such as cloud storage or a filesystem volume. The -image metadata, which is exposed by the standard cluster APIs and is used to -perform access control, is stored as standard API resources, specifically images -and imagestreams. -endif::[] - -ifdef::openshift-dedicated[] -{product-title} provides a built-in container image registry that runs as a -standard workload on the cluster. The registry is configured and managed by an -infrastructure Operator. It provides an out-of-the-box solution for users to -manage the images that run their workloads, and runs on top of the existing -cluster infrastructure. In addition, it is integrated into the cluster user -authentication and authorization system, which means that access to create and -retrieve images is controlled by defining user permissions on the image resources. - -The registry is typically used as a publication target for images built on the -cluster, as well as being a source of images for workloads running on the cluster. -When a new image is pushed to the registry, the cluster is notified of the -new image and other components can react to and consume the updated image. - -The actual image data is stored in a Red Hat-managed Amazon S3 bucket. The -image metadata, which is exposed by the standard cluster APIs and is used to -perform access control, is stored as standard API resources, specifically images -and imagestreams. -endif::[] diff --git a/modules/registry-operator-config-resources-secret-aws.adoc b/modules/registry-operator-config-resources-secret-aws.adoc deleted file mode 100644 index 5b6dff575f51..000000000000 --- a/modules/registry-operator-config-resources-secret-aws.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring_registry_storage-aws-user-infrastructure.adoc - -[id="registry-operator-config-resources-secret-aws_{context}"] -= Configuring a secret for the Image Registry Operator - -In addition to the `configs.imageregistry.operator.openshift.io` and ConfigMap -resources, configuration is provided to the Operator by a separate secret -resource located within the `openshift-image-registry` namespace. - -The `image-registry-private-configuration-user` secret provides -credentials needed for storage access and management. It overrides the default -credentials used by the Operator, if default credentials were found. - -For S3 on AWS storage, the secret is expected to contain two keys: - -* `REGISTRY_STORAGE_S3_ACCESSKEY` -* `REGISTRY_STORAGE_S3_SECRETKEY` - -.Procedure - -* Create an {product-title} secret that contains the required keys. -+ -[source,terminal] ----- -$ oc create secret generic image-registry-private-configuration-user --from-literal=REGISTRY_STORAGE_S3_ACCESSKEY=myaccesskey --from-literal=REGISTRY_STORAGE_S3_SECRETKEY=mysecretkey --namespace openshift-image-registry ----- - - -// Undefine the attribute to catch any errors at the end -:!KEY1: diff --git a/modules/registry-operator-config-resources-secret-azure.adoc b/modules/registry-operator-config-resources-secret-azure.adoc deleted file mode 100644 index 4076cbdb3eac..000000000000 --- a/modules/registry-operator-config-resources-secret-azure.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring_registry_storage/configuring-registry-storage-azure-user-infrastructure.adoc - - -[id="registry-operator-config-resources-secret-azure_{context}"] -= Configuring a secret for the Image Registry Operator - -In addition to the `configs.imageregistry.operator.openshift.io` and ConfigMap -resources, configuration is provided to the Operator by a separate secret -resource located within the `openshift-image-registry` namespace. - -The `image-registry-private-configuration-user` secret provides -credentials needed for storage access and management. It overrides the default -credentials used by the Operator, if default credentials were found. - -For Azure registry storage, the secret is expected to contain one key whose value is the -contents of a credentials file provided by Azure: - -* `REGISTRY_STORAGE_AZURE_ACCOUNTKEY` - -.Procedure - - -* Create an {product-title} secret that contains the required key. -+ -[source,terminal] ----- -$ oc create secret generic image-registry-private-configuration-user --from-literal=REGISTRY_STORAGE_AZURE_ACCOUNTKEY=<accountkey> --namespace openshift-image-registry ----- - - -// Undefine the attribute to catch any errors at the end -:!KEY1: diff --git a/modules/registry-operator-config-resources-secret-gcp.adoc b/modules/registry-operator-config-resources-secret-gcp.adoc deleted file mode 100644 index 2ce7d3c595a0..000000000000 --- a/modules/registry-operator-config-resources-secret-gcp.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring_registry_storage-gcp-user-infrastructure.adoc - -[id="registry-operator-config-resources-secret-gcp_{context}"] -= Configuring a secret for the Image Registry Operator - -In addition to the `configs.imageregistry.operator.openshift.io` and ConfigMap -resources, configuration is provided to the Operator by a separate secret -resource located within the `openshift-image-registry` namespace. - -The `image-registry-private-configuration-user` secret provides -credentials needed for storage access and management. It overrides the default -credentials used by the Operator, if default credentials were found. - -For GCS on GCP storage, the secret is expected to contain one key whose value is the -contents of a credentials file provided by GCP: - -* `REGISTRY_STORAGE_GCS_KEYFILE` - -.Procedure - -* Create an {product-title} secret that contains the required keys. -+ -[source,terminal] ----- -$ oc create secret generic image-registry-private-configuration-user --from-file=REGISTRY_STORAGE_GCS_KEYFILE=<path_to_keyfile> --namespace openshift-image-registry ----- - - -// Undefine the attribute to catch any errors at the end -:!KEY1: diff --git a/modules/registry-operator-config-resources-secret-openstack.adoc b/modules/registry-operator-config-resources-secret-openstack.adoc deleted file mode 100644 index 281bddfc7da5..000000000000 --- a/modules/registry-operator-config-resources-secret-openstack.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring-registry-operator.adoc - - -[id="registry-operator-config-resources-secret-openstack_{context}"] -= Configuring a secret for the Image Registry Operator - -In addition to the `configs.imageregistry.operator.openshift.io` and ConfigMap -resources, configuration is provided to the Operator by a separate secret -resource located within the `openshift-image-registry` namespace. - -The `image-registry-private-configuration-user` secret provides -credentials needed for storage access and management. It overrides the default -credentials used by the Operator, if default credentials were found. - -For Swift on {rh-openstack-first} storage, the secret is expected to contain the following two keys: - -* `REGISTRY_STORAGE_SWIFT_USER` -* `REGISTRY_STORAGE_SWIFT_PASSWORD` - -.Procedure - -* Create an {product-title} secret that contains the required keys. -+ -[source,terminal] ----- -$ oc create secret generic image-registry-private-configuration-user --from-literal=REGISTRY_STORAGE_SWIFT_USER=<username> --from-literal=REGISTRY_STORAGE_SWIFT_PASSWORD=<password> -n openshift-image-registry ----- diff --git a/modules/registry-operator-config-resources-storage-credentials.adoc b/modules/registry-operator-config-resources-storage-credentials.adoc deleted file mode 100644 index fcc69e03ada6..000000000000 --- a/modules/registry-operator-config-resources-storage-credentials.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring-registry-operator.adoc - - -[id="registry-operator-config-resources-storage-credentials_{context}"] -= Configuring storage credentials for the Image Registry Operator - -In addition to the `configs.imageregistry.operator.openshift.io` and ConfigMap -resources, storage credential configuration is provided to the Operator by a separate secret -resource located within the `openshift-image-registry` namespace. - -The `image-registry-private-configuration-user` secret provides -credentials needed for storage access and management. It overrides the default -credentials used by the Operator, if default credentials were found. - -.Procedure - -* Create an {product-title} secret that contains the required keys. -+ -[source,terminal] ----- -$ oc create secret generic image-registry-private-configuration-user --from-file=KEY1=value1 --from-literal=KEY2=value2 --namespace openshift-image-registry ----- - - -// Undefine the attribute to catch any errors at the end -:!KEY1: diff --git a/modules/registry-operator-configuration-resource-overview-aws-s3.adoc b/modules/registry-operator-configuration-resource-overview-aws-s3.adoc deleted file mode 100644 index 72c92b4d50f7..000000000000 --- a/modules/registry-operator-configuration-resource-overview-aws-s3.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring-registry-storage-aws-user-infrastructure.adoc - -[id="registry-operator-configuration-resource-overview-aws-s3_{context}"] -= Image Registry Operator configuration parameters for AWS S3 - -The following configuration parameters are available for AWS S3 registry storage. - -`ImageRegistryConfigStorageS3` holds the information to configure the registry to use the AWS S3 service for back-end storage. See the link:https://docs.docker.com/registry/storage-drivers/s3/[S3 storage driver documentation] for more information. - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`bucket` -|Bucket is the bucket name in which you want to store the registry's data. -It is optional and is generated if not provided. - -|`region` -|Region is the AWS region in which your bucket exists. It is optional and is -set based on the installed AWS Region. - -|`regionEndpoint` -|RegionEndpoint is the endpoint for S3 compatible storage services. -It is optional and defaults based on the Region that is provided. - -|`virtualHostedStyle` -|VirtualHostedStyle enables using S3 virtual hosted style bucket paths with a custom RegionEndpoint. It is optional and defaults to false. - -Set this parameter to deploy {product-title} to hidden regions. - -|`encrypt` -|Encrypt specifies whether or not the registry stores the image in encrypted format. -It is optional and defaults to false. - -|`keyID` -|KeyID is the KMS key ID to use for encryption. It is optional. Encrypt must be -true, or this parameter is ignored. - -|`ImageRegistryConfigStorageS3CloudFront` -|CloudFront configures Amazon Cloudfront as the storage middleware in a registry. -It is optional. - -|=== diff --git a/modules/registry-operator-configuration-resource-overview-gcp-gcs.adoc b/modules/registry-operator-configuration-resource-overview-gcp-gcs.adoc deleted file mode 100644 index 2af302b20c8e..000000000000 --- a/modules/registry-operator-configuration-resource-overview-gcp-gcs.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/configuring-registry-operator.adoc - -[id="registry-operator-configuration-resource-overview-gcp-gcs_{context}"] -= Image Registry Operator configuration parameters for GCP GCS - -The following configuration parameters are available for GCP GCS registry storage. - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`bucket` -|Bucket is the bucket name in which you want to store the registry's data. -It is optional and is generated if not provided. - -|`region` -|Region is the GCS location in which your bucket exists. It is optional and is -set based on the installed GCS Region. - -|`projectID` -|ProjectID is the Project ID of the GCP project that this bucket should be -associated with. It is optional. - -|`keyID` -|KeyID is the KMS key ID to use for encryption. It is optional because -buckets are encrypted by default on GCP. This allows for the use of a custom -encryption key. - -|=== diff --git a/modules/registry-operator-configuration-resource-overview-openstack-swift.adoc b/modules/registry-operator-configuration-resource-overview-openstack-swift.adoc deleted file mode 100644 index 7a7f8287f52b..000000000000 --- a/modules/registry-operator-configuration-resource-overview-openstack-swift.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/configuring_registry_storage/configuring-registry-storage-openstack-user-infrastructure.adoc - -[id="registry-operator-configuration-resource-overview-openstack-swift_{context}"] -= Image Registry Operator configuration parameters for {rh-openstack} Swift - -The following configuration parameters are available for {rh-openstack-first} Swift -registry storage. - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`authURL` -|This value is optional. - -|`authVersion` -|This value is optional. - -|`container` -|This value is optional. - -|`domain` -|This value is optional. - -|`domainID` -|This value is optional. - -|`tenant` -|This value is optional. - -|`tenantID` -|This value is optional. - -|`regionName` -|This value is optional. - -|=== diff --git a/modules/registry-operator-configuration-resource-overview.adoc b/modules/registry-operator-configuration-resource-overview.adoc deleted file mode 100644 index 8c771f2bccde..000000000000 --- a/modules/registry-operator-configuration-resource-overview.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/configuring-registry-operator.adoc - - -[id="registry-operator-configuration-resource-overview_{context}"] -= Image Registry Operator configuration parameters - -The `configs.imageregistry.operator.openshift.io` resource offers the following -configuration parameters. - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`managementState` -|`Managed`: The Operator updates the registry as configuration resources -are updated. - -`Unmanaged`: The Operator ignores changes to the configuration resources. - -`Removed`: The Operator removes the registry instance and tear down any -storage that the Operator provisioned. - -|`logLevel` -|Sets `logLevel` of the registry instance. Defaults to `Normal`. - -The supported values for `logLevel` are: - -* `Normal` -* `Debug` -* `Trace` -* `TraceAll` - -|`httpSecret` -|Value needed by the registry to secure uploads, generated by default. - -|`proxy` -|Defines the Proxy to be used when calling master API -and upstream registries. - -|`storage` -|`Storagetype`: Details for configuring registry storage, for example S3 bucket -coordinates. Normally configured by default. - -|`readOnly` -|Indicates whether the registry instance should reject attempts to push new images or delete existing ones. - -|`requests` -|API Request Limit details. Controls how many parallel requests a given registry -instance will handle before queuing additional requests. - -|`defaultRoute` -|Determines whether or not an external route is defined using the default -hostname. If enabled, the route uses re-encrypt encryption. Defaults to false. - -|`routes` -|Array of additional routes to create. You provide the hostname and certificate -for the route. - -|`replicas` -|Replica count for the registry. - -|`spec.storage.managementState` - -|The Image Registry Operator sets the `spec.storage.managementState` parameter to `Managed` on new installations or upgrades of clusters using installer-provisioned infrastructure on AWS or Azure. - -* `Managed`: Determines that the Image Registry Operator manages underlying storage. If the Image Registry Operator's `managementState` is set to `Removed`, then the storage is deleted. -** If the `managementState` is set to `Managed`, the Image Registry Operator attempts to apply some default configuration on the underlying storage unit. For example, if set to `Managed`, the Operator tries to enable encryption on the S3 bucket before making it available to the registry. If you do not want the default settings to be applied on the storage you are providing, make sure the `managementState` is set to `Unmanaged`. -* `Unmanaged`: Determines that the Image Registry Operator ignores the storage settings. If the Image Registry Operator's `managementState` is set to `Removed`, then the storage is not deleted. If you provided an underlying storage unit configuration, such as a bucket or container name, and the `spec.storage.managementState` is not yet set to any value, then the Image Registry Operator configures it to `Unmanaged`. - - - -|=== diff --git a/modules/registry-operator-default-crd.adoc b/modules/registry-operator-default-crd.adoc deleted file mode 100644 index 02eeb0a93021..000000000000 --- a/modules/registry-operator-default-crd.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/configuring-registry-operator.adoc - - -[id="registry-operator-default-crd_{context}"] -= Enable the Image Registry default route with the Custom Resource Definition - -In {product-title}, the `Registry` Operator controls the registry feature. The -Operator is defined by the `configs.imageregistry.operator.openshift.io` Custom -Resource Definition (CRD). - -If you need to automatically enable the Image Registry default route, patch the -Image Registry Operator CRD. - -.Procedure - -* Patch the Image Registry Operator CRD: -+ -[source,terminal] ----- -$ oc patch configs.imageregistry.operator.openshift.io/cluster --type merge -p '{"spec":{"defaultRoute":true}}' ----- diff --git a/modules/registry-quay-overview.adoc b/modules/registry-quay-overview.adoc deleted file mode 100644 index ca0cff7ea566..000000000000 --- a/modules/registry-quay-overview.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/registry-options.adoc - -[id="registry-quay-overview_{context}"] -= Red Hat Quay registries - -If you need an enterprise-quality container image registry, Red Hat Quay is -available both as a hosted service and as software you can install in your own -data center or cloud environment. Advanced registry features in Red Hat Quay -include geo-replication, image scanning, and the ability to roll back images. - -Visit the Quay.io site to set up your own hosted Quay registry account. After -that, follow the Quay Tutorial to log in to the Quay registry and start managing -your images. - -You can access your Red Hat Quay registry from {product-title} like any remote -container image registry. - -//.Additional resources -//* link:https://quay.io[Quay.io] -//* link:https://quay.io/tutorial/[Quay Tutorial] -//* Refer to link:https://access.redhat.com/documentation/en-us/red_hat_quay/2.9/html-single/getting_started_with_red_hat_quay/[Getting Started with Red Hat Quay] -//for information about setting up your own Red Hat Quay registry. -//* To learn how to set up credentials to access -//Red Hat Quay as a secured registry, refer to Allowing Pods to Reference Images from Other Secured Registries. diff --git a/modules/registry-removed.adoc b/modules/registry-removed.adoc deleted file mode 100644 index 1ee060e1ed57..000000000000 --- a/modules/registry-removed.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_bare_metal/installing-bare-metal-network-customizations.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * registry/configuring-registry-operator.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc -// * registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc - -[id="registry-removed_{context}"] -= Image registry removed during installation - -On platforms that do not provide shareable object storage, the OpenShift Image -Registry Operator bootstraps itself as `Removed`. This allows -`openshift-installer` to complete installations on these platform types. - -After installation, you must edit the Image Registry Operator configuration to -switch the `managementState` from `Removed` to `Managed`. - -[NOTE] -==== -The Prometheus console provides an `ImageRegistryRemoved` alert, for example: - -"Image Registry has been removed. `ImageStreamTags`, `BuildConfigs` and -`DeploymentConfigs` which reference `ImageStreamTags` may not work as -expected. Please configure storage and update the config to `Managed` -state by editing configs.imageregistry.operator.openshift.io." -==== diff --git a/modules/registry-third-party-registries.adoc b/modules/registry-third-party-registries.adoc deleted file mode 100644 index a70760a96421..000000000000 --- a/modules/registry-third-party-registries.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/registry-options.adoc - -[id="registry-third-party-registries_{context}"] -= Third-party registries - -{product-title} can create containers using images from third-party registries, -but it is unlikely that these registries offer the same image notification -support as the integrated {product-title} registry. In this situation, -{product-title} will fetch tags from the remote registry upon imagestream -creation. - -Refreshing the fetched tags is as simple as running `oc import-image -<stream>`. When new images are detected, the previously described build and -deployment reactions occur. - -[id="authentication_{context}"] -== Authentication -{product-title} can communicate with registries to access private image -repositories using credentials supplied by the user. This allows {product-title} -to push and pull images to and from private repositories. diff --git a/modules/registry-viewing-logs.adoc b/modules/registry-viewing-logs.adoc deleted file mode 100644 index ebe9adc22069..000000000000 --- a/modules/registry-viewing-logs.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * registry/accessing-the-registry.adoc - -[id="registry-viewing-logs_{context}"] -= Viewing registry logs - -You can view the logs for the registry by using the `oc logs` command. - -.Procedure - -. Use the `oc logs` command with deployments to view the logs for the container -image registry: -+ -[source,terminal] ----- -$ oc logs deployments/image-registry -n openshift-image-registry ----- -+ -.Example output -[source,terminal] ----- -2015-05-01T19:48:36.300593110Z time="2015-05-01T19:48:36Z" level=info msg="version=v2.0.0+unknown" -2015-05-01T19:48:36.303294724Z time="2015-05-01T19:48:36Z" level=info msg="redis not configured" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002 -2015-05-01T19:48:36.303422845Z time="2015-05-01T19:48:36Z" level=info msg="using inmemory layerinfo cache" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002 -2015-05-01T19:48:36.303433991Z time="2015-05-01T19:48:36Z" level=info msg="Using OpenShift Auth handler" -2015-05-01T19:48:36.303439084Z time="2015-05-01T19:48:36Z" level=info msg="listening on :5000" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002 ----- diff --git a/modules/reissue-internal-certificates-central.adoc b/modules/reissue-internal-certificates-central.adoc new file mode 100644 index 000000000000..6a2553c2bfbd --- /dev/null +++ b/modules/reissue-internal-certificates-central.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc +:_mod-docs-content-type: PROCEDURE +[id="reissue-internal-certificates-central_{context}"] += Reissuing internal certificates for Central + +Central uses a built-in server certificate for authentication when communicating with other {product-title} services. +This certificate is unique to your Central installation. +The {product-title-short} portal shows an information banner when the Central certificate is about to expire. + +[NOTE] +==== +The information banner only appears 15 days before the certificate expiration date. +==== + +For Operator-based installations, beginning with {product-title-short} version 4.3.4, the Operator will automatically rotate all Central components' service transport layer security (TLS) certificates 6 months before they expire. The following conditions apply: + +* The rotation of certificates in the secrets does not trigger the components to automatically reload them. However, reloads typically occur when the pod is replaced as part of an {product-title-short} upgrade or as a result of node reboots. If neither of those events happens at least every 6 months, you must restart the pods before the old (in-memory) service certificates expire. For example, you can delete the pods with an `app` label that contains one of the values of `central`, `central-db`, `scanner`, or `scanner-db`. + +* CA certificates are not updated. They are valid for 5 years. + +For non-Operator based installations, you must manually rotate TLS certificates. Instructions for manually rotating certificates are included in the following section. + +.Prerequisites + +* To reissue, or rotate, certificates, you must have `write` permission for the `Administration` resource. + +.Procedure + +. In the {product-title-short} portal, click on the link in the banner that announces the certificate expiration to download a YAML configuration file, which contains a new secret. The secret includes the certificate and key values. +. Apply the new YAML configuration file to the cluster where you have installed Central by running the following command: ++ +[source,terminal] +---- +$ oc apply -f <secret_file.yaml> +---- +. Restart Central to apply the changes. diff --git a/modules/reissue-internal-certificates-scanner.adoc b/modules/reissue-internal-certificates-scanner.adoc new file mode 100644 index 000000000000..85a555887569 --- /dev/null +++ b/modules/reissue-internal-certificates-scanner.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc +:_mod-docs-content-type: PROCEDURE +[id="reissue-internal-certificates-scanner_{context}"] += Reissuing internal certificates for Scanner + +Scanner has a built-in certificate that it uses to communicate with Central. + +The {product-title-short} portal shows an information banner when the Scanner certificate is about to expire. + +[NOTE] +==== +The information banner only appears 15 days before the certificate expiry date. +==== + +.Prerequisites + +* To reissue certificates, you must have `write` permission for the `Administration` resource. + +.Procedure + +. Click on the link in the banner to download a YAML configuration file, which contains a new {ocp} secret, including the certificate and key values. +. Apply the new YAML configuration file to the cluster where you installed Scanner. ++ +[source,terminal] +---- +$ oc apply -f <secret_file.yaml> +---- +. Restart Scanner to apply the changes. diff --git a/modules/reissue-internal-certificates-secured-clusters-automatic-upgrades.adoc b/modules/reissue-internal-certificates-secured-clusters-automatic-upgrades.adoc new file mode 100644 index 000000000000..423ea7eef53f --- /dev/null +++ b/modules/reissue-internal-certificates-secured-clusters-automatic-upgrades.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="reissue-internal-certificates-secured-clusters-automatic-upgrade_{context}"] += Reissuing internal certificates for secured clusters by using automatic upgrades + +Secured clusters contain the Collector, Sensor, Admission Control, and local Scanner components. +You can reissue internal certificates for these components by using automatic upgrades. + +[IMPORTANT] +==== +Automatic upgrades are only applicable to static manifest-based deployments by using the `roxctl` CLI. + +For more information, see "Install Central using the roxctl CLI". +==== + +.Prerequisites + +* You have enabled automatic upgrades for all the clusters. +* You have `write` permission for the `Administration` resource. + +.Procedure + +. In the {product-title-short} portal, click *Platform Configuration* -> *Clusters*. +. Select a cluster to view its details. +. From the cluster details panel, select the link to *Apply credentials by using an automatic upgrade*. ++ +[NOTE] +==== +When you apply an automatic upgrade, {rh-rhacs-first} creates new credentials in the selected cluster. However, you continue to see a notification. The notification disappears when each {product-title-short} service uses the new credentials after the service restarts. +==== \ No newline at end of file diff --git a/modules/reissue-internal-certificates-secured-clusters.adoc b/modules/reissue-internal-certificates-secured-clusters.adoc new file mode 100644 index 000000000000..37d8c3c10d65 --- /dev/null +++ b/modules/reissue-internal-certificates-secured-clusters.adoc @@ -0,0 +1,76 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="reissue-internal-certificates-secured-cluster_{context}"] += Reissuing internal certificates for secured clusters by using init bundles + +Secured clusters contain the Collector, Sensor, Admission Control, and local Scanner components. These components use a built-in server certificate for authentication when communicating with other {rh-rhacs-first} components. + +The {product-title-short} portal shows an information banner when the Central certificate is about to expire. + +[NOTE] +==== +The information banner only appears 15 days before the certificate expiry date. +==== + +.Prerequisites + +* You have `write` permission for the `Administration` resource. +* You have the `Admin` user role to create init bundles. + +[IMPORTANT] +==== +Store the init bundle securely because it contains secrets. +You can use the same bundle on multiple secured clusters. +==== + +.Procedure + +. Choose the appropriate method to generate an init bundle: + +** To generate an init bundle by using the user interface (UI), perform the following steps: +... In the {product-title-short} portal, click *Platform Configuration* -> *Clusters*. +... Click *Init bundles*. +... To create a new init bundle, click *Create bundle*. +... Enter a name for the cluster init bundle. +... Choose the appropriate platform of the secured clusters: ++ +The following values are associated with the platform of the secured clusters: + +**** `OpenShift` +**** `EKS` +**** `AKS` +**** `GKE` + +... Choose the appropriate installation method for the secured cluster services from the drop-down list: ++ +The following values are associated with the installation method for the secured cluster services: + +**** `Operator (recommended)` +**** `Helm chart` + +... Click *Download*. ++ +[IMPORTANT] +==== +You can only download the YAML file once when you create an init bundle. +Store the YAML file securely because it contains secrets. +==== + +** To generate an init bundle by using the `roxctl` CLI, run the following command: ++ +[source,terminal] +---- +$ roxctl -e <endpoint> -p <admin_password> central \ + init-bundles generate --output-secrets <bundle_name> \ + init-bundle.yaml +---- + +. To create the necessary resources on each secured cluster, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox apply -f <init-bundle.yaml> +---- \ No newline at end of file diff --git a/modules/reissuing-internal-certificates-for-secured-clusters-by-using-automatic-certificate-renewal.adoc b/modules/reissuing-internal-certificates-for-secured-clusters-by-using-automatic-certificate-renewal.adoc new file mode 100644 index 000000000000..2b0e245b0afb --- /dev/null +++ b/modules/reissuing-internal-certificates-for-secured-clusters-by-using-automatic-certificate-renewal.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: CONCEPT +[id="reissuing-internal-certificates-for-secured-clusters-by-using-automatic-certificate-renewal_{context}"] += Reissuing internal certificates for secured clusters by using automatic certificate renewal + +Secured clusters contain the Collector, Sensor, Admission Control, and local Scanner components. You can reissue internal certificates for these components by using automatic certificate renewal. + +TLS certificates are automatically renewed several months in advance but are only loaded when {product-title-short} pods restart, for example, during an upgrade. \ No newline at end of file diff --git a/modules/remove-admin-user.adoc b/modules/remove-admin-user.adoc new file mode 100644 index 000000000000..6ec2c995c597 --- /dev/null +++ b/modules/remove-admin-user.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/remove-admin-user.adoc +:_mod-docs-content-type: PROCEDURE +[id="remove_admin-user_{context}"] += Removing the admin user after installation + +After an authentication provider has been successfully created, it is strongly recommended to remove the `admin` user. + +Removing the `admin` user is dependent on the installation method of the {product-title-short} portal. + +.Procedure + +Perform one of the following procedures: + +* For Operator installations, set `central.adminPasswordGenerationDisabled` to `true` in your `Central` custom resource. + +* For Helm installations: +. In your `Central` Helm configuration, set `central.adminPassword.generate` to `false`. +. Follow the steps to change the configuration. See "Changing configuration options after deployment" for more information. + +* For `roxctl` installations: +. When generating the manifest, set `Disable password generation` to `false`. +. Follow the steps to install Central by using `roxctl` to apply the changes. See "Install Central using the roxctl CLI" for more information. diff --git a/modules/remove-process-from-baseline.adoc b/modules/remove-process-from-baseline.adoc new file mode 100644 index 000000000000..cc2407dc20a0 --- /dev/null +++ b/modules/remove-process-from-baseline.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: PROCEDURE +[id="remove-process-from-baseline_{context}"] += Removing a process from the baseline + +You can remove a process from the baseline. + +.Procedure +. In the {product-title-short} portal, select *Risk* from the navigation menu. +. Select a deployment from the list of deployments in the default *Risk* view. +Deployment details open in a panel on the right. +. In the *Deployment* details panel, select the *Process Discovery* tab. +. Under the *Spec Container baselines* section, click the *Remove* icon for the process you want to remove from the process baseline. diff --git a/modules/restart-central-container.adoc b/modules/restart-central-container.adoc new file mode 100644 index 000000000000..eb78d76ddaa0 --- /dev/null +++ b/modules/restart-central-container.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * configuration/add-trusted-ca.adoc +// * configuration/configure-endpoints.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restart-central_{context}"] += Restarting the Central container + +[role="_abstract"] +You can restart the Central container by killing the Central container or by deleting the Central pod. + +.Procedure + +* Run the following command to kill the Central container: ++ +[NOTE] +==== +You must wait for at least 1 minute, until {ocp} propagates your changes and restarts the Central container. +==== ++ +[source,terminal] +---- +$ oc -n stackrox exec deploy/central -c central -- kill 1 +---- +* Or, run the following command to delete the Central pod: ++ +[source,terminal] +---- +$ oc -n stackrox delete pod -lapp=central +---- diff --git a/modules/restart-scanner-and-scannerdb-containers.adoc b/modules/restart-scanner-and-scannerdb-containers.adoc new file mode 100644 index 000000000000..738ca93e62fc --- /dev/null +++ b/modules/restart-scanner-and-scannerdb-containers.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restart-scanner_{context}"] += Restarting the Scanner and Scanner DB containers + +[role="_abstract"] +You can restart the Scanner and Scanner DB container by deleting the pods. + +.Procedure + +* To delete the Scanner and Scanner DB pods, run the following command: +** On {ocp}: ++ +[source,terminal] +---- +$ oc delete pod -n stackrox -l app=scanner; oc -n stackrox delete pod -l app=scanner-db +---- +** On Kubernetes: ++ +[source,terminal] +---- +$ kubectl delete pod -n stackrox -l app=scanner; kubectl -n stackrox delete pod -l app=scanner-db +---- diff --git a/modules/restart-scanner-container.adoc b/modules/restart-scanner-container.adoc new file mode 100644 index 000000000000..85302963457f --- /dev/null +++ b/modules/restart-scanner-container.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * configuration/add-trusted-ca.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restart-scanner_{context}"] += Restarting the Scanner container + +[role="_abstract"] +You can restart the Scanner container by deleting the pod. + +.Procedure + +* Run the following command to delete the Scanner pod: +** On {ocp}: ++ +[source,terminal] +---- +$ oc delete pod -n stackrox -l app=scanner +---- +** On Kubernetes: ++ +[source,terminal] +---- +$ kubectl delete pod -n stackrox -l app=scanner +---- + diff --git a/modules/restart-sensor-container.adoc b/modules/restart-sensor-container.adoc new file mode 100644 index 000000000000..f71ab6b44002 --- /dev/null +++ b/modules/restart-sensor-container.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * configuration/add-custom-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restart-sensor_{context}"] += Restarting the Sensor container + +[role="_abstract"] +You can restart the Sensor container either by killing the container or by deleting the Sensor pod. + +.Procedure + +* Run the following command to kill the Sensor container: ++ +[NOTE] +==== +You must wait for at least 1 minute, until {ocp} or Kubernetes propagates your changes and restarts the Sensor container. +==== +** On {ocp}: ++ +[source,terminal] +---- +$ oc -n stackrox deploy/sensor -c sensor -- kill 1 +---- +** On Kubernetes: ++ +[source,terminal] +---- +$ kubectl -n stackrox deploy/sensor -c sensor -- kill 1 +---- +* Or, run the following command to delete the Sensor pod: +** On {ocp}: ++ +[source,terminal] +---- +$ oc -n stackrox delete pod -lapp=sensor +---- +** On Kubernetes: ++ +[source,terminal] +---- +$ kubectl -n stackrox delete pod -lapp=sensor +---- diff --git a/modules/restarting-sensor-in-the-secured-cluster.adoc b/modules/restarting-sensor-in-the-secured-cluster.adoc new file mode 100644 index 000000000000..34ad78f5e4a7 --- /dev/null +++ b/modules/restarting-sensor-in-the-secured-cluster.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * manage-compliance-operator/compliance-operator-rhacs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restarting-sensor-in-the-secured-cluster_{context}"] += Restarting Sensor in the secured cluster + +If you installed the Compliance Operator after installing {product-title-short}, you need to restart Sensor in the secured cluster either by using the command-line interface (CLI) or the user interface (UI). + +.Procedure + +* To restart Sensor from the CLI, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox delete pod -lapp=sensor +---- + +* To restart Sensor from the UI, perform the following steps: +. Change the active project to `stackrox`. +. Go to *Workloads -> Pods*. +. Locate the pod with the name starting with `sensor-`, and then click *Actions -> Delete Pod*. \ No newline at end of file diff --git a/modules/restore-acs-roxctl-admin-pass.adoc b/modules/restore-acs-roxctl-admin-pass.adoc new file mode 100644 index 000000000000..3ff8775c9433 --- /dev/null +++ b/modules/restore-acs-roxctl-admin-pass.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/restore-acs.adoc +// * troubleshooting_central/restoring-central-database-by-using-the-roxctl-cli.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restore-acs-roxctl-admin-pass_{context}"] += Restoring by using the administrator password + +[role="_abstract"] +You can restore the entire database of {product-title-short} by using your administrator password. + +.Prerequisites + +* You have a {product-title-short} backup file. +* You have the administrator password. +* You have installed the `roxctl` CLI. + +.Procedure +. Set the `ROX_ENDPOINT` environment variable by running the following command: ++ +[source,terminal] +---- +$ export ROX_ENDPOINT=<address>:<port_number> +---- + +. Restore the Central database by running the following command: ++ +[source,terminal] +---- +$ roxctl -p <admin_password> \// <1> + central db restore <backup_file> <2> +---- ++ +<1> For `<admin_password>`, specify the administrator password. +<2> For `<backup_file>`, specify the name of the backup file that you want to restore. \ No newline at end of file diff --git a/modules/restore-acs-roxctl-api.adoc b/modules/restore-acs-roxctl-api.adoc new file mode 100644 index 000000000000..f3488ecc581f --- /dev/null +++ b/modules/restore-acs-roxctl-api.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/restore-acs.adoc +// *troubleshooting_central/restoring-central-database-by-using-the-roxctl-cli.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restore-acs-roxctl-api_{context}"] += Restoring by using an API token + +[role="_abstract"] +You can restore the entire database of {product-title-short} by using an API token. + +.Prerequisites + +* You have a {product-title-short} backup file. +* You have an API token with the administrator role. +* You have installed the `roxctl` CLI. + +.Procedure +. Set the `ROX_API_TOKEN` and the `ROX_ENDPOINT` environment variables by running the following commands: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN=<api_token> +---- ++ +[source,terminal] +---- +$ export ROX_ENDPOINT=<address>:<port_number> +---- + +. Restore the Central database by running the following command: ++ +[source,terminal] +---- +$ roxctl central db restore <backup_file> <1> +---- ++ +<1> For `<backup_file>`, specify the name of the backup file that you want to restore. \ No newline at end of file diff --git a/modules/restore-cert-roxctl.adoc b/modules/restore-cert-roxctl.adoc new file mode 100644 index 000000000000..921ef54adec6 --- /dev/null +++ b/modules/restore-cert-roxctl.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/restore-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="restore-cert-roxctl_{context}"] += Restore certificates using the roxctl CLI + +[role="_abstract"] +Use the `roxctl` CLI to generate Kubernetes manifests to install the {product-title-short} Central component to your cluster. +Doing this allows you to ensure that authentication certificates for Secured clusters and the API tokens remain valid for the restored version. +If you backed up another instance of {product-title-short} Central, you can use the certificate files from that backup. + +[NOTE] +==== +With the `roxctl` CLI, you can not restore the entire Central deployment. Instead, first you use the `roxctl` CLI to generate new manifests using the certificates in your central data backup. Afterwards, you use those manifests to install Central. +==== + +.Prerequisites +* You must have the {product-title} backup file. +* You must have installed the `roxctl` CLI. + +.Procedure +. Run the interactive install command: ++ +[source,terminal] +---- +$ roxctl central generate interactive +---- +. For the following prompt, enter the path of the {product-title} backup file: ++ +[source,terminal] +---- +Enter path to the backup bundle from which to restore keys and certificates (optional): _<backup-file-path>_ +---- +. For other following prompts, press kbd:[Enter] to accept the default value or enter custom values as required. + +On completion, the interactive install command creates a folder named `central-bundle`, which has the necessary YAML manifests and scripts to deploy Central. diff --git a/modules/restore-deployment-config-helm.adoc b/modules/restore-deployment-config-helm.adoc new file mode 100644 index 000000000000..28caeb816c6d --- /dev/null +++ b/modules/restore-deployment-config-helm.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/restore-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="restore-deployment-config-helm_{context}"] += Restore Central deployment using Helm + +[role="_abstract"] +You can restore your Central deployment to its original configuration by using Helm. +To successfully restore, you need the backup of your Central custom resource, the `central-tls` secret, and the administrator password. + +.Prerequisites +* You must have the Helm values backup file. +* You must have a {product-title} backup file. +* You must have installed the `roxctl` CLI. + +.Procedure +. Generate `values-private.yaml` from the {product-title-short} database backup file: ++ +[source,terminal] +---- +$ roxctl central generate k8s pvc --backup-bundle _<path-to-backup-file>_ --output-format "helm-values" +---- +. Run the `helm install` command and specify your backup files: ++ +[source,terminal] +---- +$ helm install -n stackrox --create-namespace stackrox-central-services rhacs/central-services -f central-values-backup.yaml -f central-bundle/values-private.yaml +---- diff --git a/modules/restore-deployment-config-operator.adoc b/modules/restore-deployment-config-operator.adoc new file mode 100644 index 000000000000..bf4083f93dd6 --- /dev/null +++ b/modules/restore-deployment-config-operator.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/restore-acs.adoc +:_mod-docs-content-type: PROCEDURE +[id="restore-deployment-config-operator_{context}"] += Restore Central deployment using the {product-title-short} Operator + +[role="_abstract"] +You can restore your Central deployment to its original configuration by using the {product-title-short} Operator. +To successfully restore, you need the backup of your Central custom resource, `central-tls`, and the administrator password. + +.Prerequisites +* You must have the `central-tls` backup file. +* You must have the Central custom resource backup file. +* You must have the administrator password backup file. + +.Procedure +. Use the `central-tls` backup file to create resources: ++ +[source,terminal] +---- +$ oc apply -f central-tls.json +---- +. Use the `central-htpasswd` backup file to create secrets: ++ +[source,terminal] +---- +$ oc apply -f central-htpasswd.json +---- +. Use the `central-cr.yaml` file to create the Central deployment: ++ +[source,terminal] +---- +$ oc apply -f central-cr.yaml +---- diff --git a/modules/restore-determine-state-etcd-member.adoc b/modules/restore-determine-state-etcd-member.adoc deleted file mode 100644 index fa112342c326..000000000000 --- a/modules/restore-determine-state-etcd-member.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// Module included in the following assemblies: -// -// * backup_and_restore/replacing-unhealthy-etcd-member.adoc - -[id="restore-determine-state-etcd-member_{context}"] -= Determining the state of the unhealthy etcd member - -The steps to replace an unhealthy etcd member depend on which of the following states your etcd member is in: - -* The machine is not running or the node is not ready -* The etcd pod is crashlooping - -This procedure determines which state your etcd member is in. This enables you to know which procedure to follow to replace the unhealthy etcd member. - -[NOTE] -==== -If you are aware that the machine is not running or the node is not ready, but you expect it to return to a healthy state soon, then you do not need to perform a procedure to replace the etcd member. The etcd cluster Operator will automatically sync when the machine or node returns to a healthy state. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have identified an unhealthy etcd member. - -.Procedure - -. Determine if the *machine is not running*: -+ -[source,terminal] ----- -$ oc get machines -A -ojsonpath='{range .items[*]}{@.status.nodeRef.name}{"\t"}{@.status.providerStatus.instanceState}{"\n"}' | grep -v running ----- -+ -.Example output -[source,terminal] ----- -ip-10-0-131-183.ec2.internal stopped <1> ----- -<1> This output lists the node and the status of the node's machine. If the status is anything other than `running`, then the *machine is not running*. -+ -// TODO: xref -If the *machine is not running*, then follow the _Replacing an unhealthy etcd member whose machine is not running or whose node is not ready_ procedure. - - -. Determine if the *node is not ready*. -+ -If either of the following scenarios are true, then the *node is not ready*. - -** If the machine is running, then check whether the node is unreachable: -+ -[source,terminal] ----- -$ oc get nodes -o jsonpath='{range .items[*]}{"\n"}{.metadata.name}{"\t"}{range .spec.taints[*]}{.key}{" "}' | grep unreachable ----- -+ -.Example output -[source,terminal] ----- -ip-10-0-131-183.ec2.internal node-role.kubernetes.io/master node.kubernetes.io/unreachable node.kubernetes.io/unreachable <1> ----- -<1> If the node is listed with an `unreachable` taint, then the *node is not ready*. - -** If the node is still reachable, then check whether the node is listed as `NotReady`: -+ -[source,terminal] ----- -$ oc get nodes -l node-role.kubernetes.io/master | grep "NotReady" ----- -+ -.Example output -[source,terminal] ----- -ip-10-0-131-183.ec2.internal NotReady master 122m v1.20.0 <1> ----- -<1> If the node is listed as `NotReady`, then the *node is not ready*. - -+ -// TODO: xref -If the *node is not ready*, then follow the _Replacing an unhealthy etcd member whose machine is not running or whose node is not ready_ procedure. - - -. Determine if the *etcd pod is crashlooping*. -+ -If the machine is running and the node is ready, then check whether the etcd pod is crashlooping. - -.. Verify that all master nodes are listed as `Ready`: -+ -[source,terminal] ----- -$ oc get nodes -l node-role.kubernetes.io/master ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-131-183.ec2.internal Ready master 6h13m v1.20.0 -ip-10-0-164-97.ec2.internal Ready master 6h13m v1.20.0 -ip-10-0-154-204.ec2.internal Ready master 6h13m v1.20.0 ----- - -.. Check whether the status of an etcd pod is either `Error` or `CrashloopBackoff`: -+ -[source,terminal] ----- -$ oc get pods -n openshift-etcd | grep -v etcd-quorum-guard | grep etcd ----- -+ -.Example output -[source,terminal] ----- -etcd-ip-10-0-131-183.ec2.internal 2/3 Error 7 6h9m <1> -etcd-ip-10-0-164-97.ec2.internal 3/3 Running 0 6h6m -etcd-ip-10-0-154-204.ec2.internal 3/3 Running 0 6h6m ----- -<1> Since this status of this pod is `Error`, then the *etcd pod is crashlooping*. - -+ -// TODO: xref -If the *etcd pod is crashlooping*, then follow the _Replacing an unhealthy etcd member whose etcd pod is crashlooping_ procedure. diff --git a/modules/restore-identify-unhealthy-etcd-member.adoc b/modules/restore-identify-unhealthy-etcd-member.adoc deleted file mode 100644 index ec07b26a3285..000000000000 --- a/modules/restore-identify-unhealthy-etcd-member.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * backup_and_restore/replacing-unhealthy-etcd-member.adoc - -[id="restore-identify-unhealthy-etcd-member_{context}"] -= Identifying an unhealthy etcd member - -You can identify if your cluster has an unhealthy etcd member. - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Check the status of the `EtcdMembersAvailable` status condition using the following command: -+ -[source,terminal] ----- -$ oc get etcd -o=jsonpath='{range .items[0].status.conditions[?(@.type=="EtcdMembersAvailable")]}{.message}{"\n"}' ----- - -. Review the output: -+ -[source,terminal] ----- -2 of 3 members are available, ip-10-0-131-183.ec2.internal is unhealthy ----- -+ -This example output shows that the `ip-10-0-131-183.ec2.internal` etcd member is unhealthy. diff --git a/modules/restore-replace-crashlooping-etcd-member.adoc b/modules/restore-replace-crashlooping-etcd-member.adoc deleted file mode 100644 index b2928ffab387..000000000000 --- a/modules/restore-replace-crashlooping-etcd-member.adoc +++ /dev/null @@ -1,225 +0,0 @@ -// Module included in the following assemblies: -// -// * backup_and_restore/replacing-unhealthy-etcd-member.adoc - -[id="restore-replace-crashlooping-etcd-member_{context}"] -= Replacing an unhealthy etcd member whose etcd pod is crashlooping - -This procedure details the steps to replace an etcd member that is unhealthy because the etcd pod is crashlooping. - -.Prerequisites - -* You have identified the unhealthy etcd member. -* You have verified that the etcd pod is crashlooping. -* You have access to the cluster as a user with the `cluster-admin` role. -* You have taken an etcd backup. -+ -[IMPORTANT] -==== -It is important to take an etcd backup before performing this procedure so that your cluster can be restored if you encounter any issues. -==== - -.Procedure - -. Stop the crashlooping etcd pod. - -.. Debug the node that is crashlooping. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc debug node/ip-10-0-131-183.ec2.internal <1> ----- -<1> Replace this with the name of the unhealthy node. - -.. Change your root directory to the host: -+ -[source,terminal] ----- -sh-4.2# chroot /host ----- - -.. Move the existing etcd pod file out of the kubelet manifest directory: -+ -[source,terminal] ----- -sh-4.2# mkdir /var/lib/etcd-backup ----- -+ -[source,terminal] ----- -sh-4.2# mv /etc/kubernetes/manifests/etcd-pod.yaml /var/lib/etcd-backup/ ----- - -.. Move the etcd data directory to a different location: -+ -[source,terminal] ----- -sh-4.2# mv /var/lib/etcd/ /tmp ----- -+ -You can now exit the node shell. - -. Remove the unhealthy member. - -.. Choose a pod that is _not_ on the affected node. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc get pods -n openshift-etcd | grep -v etcd-quorum-guard | grep etcd ----- -+ -.Example output -[source,terminal] ----- -etcd-ip-10-0-131-183.ec2.internal 2/3 Error 7 6h9m -etcd-ip-10-0-164-97.ec2.internal 3/3 Running 0 6h6m -etcd-ip-10-0-154-204.ec2.internal 3/3 Running 0 6h6m ----- - -.. Connect to the running etcd container, passing in the name of a pod that is not on the affected node. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc rsh -n openshift-etcd etcd-ip-10-0-154-204.ec2.internal ----- - -.. View the member list: -+ -[source,terminal] ----- -sh-4.2# etcdctl member list -w table ----- -+ -.Example output -[source,terminal] ----- -+------------------+---------+------------------------------+---------------------------+---------------------------+ -| ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS | -+------------------+---------+------------------------------+---------------------------+---------------------------+ -| 62bcf33650a7170a | started | ip-10-0-131-183.ec2.internal | https://10.0.131.183:2380 | https://10.0.131.183:2379 | -| b78e2856655bc2eb | started | ip-10-0-164-97.ec2.internal | https://10.0.164.97:2380 | https://10.0.164.97:2379 | -| d022e10b498760d5 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 | -+------------------+---------+------------------------------+---------------------------+---------------------------+ ----- -+ -Take note of the ID and the name of the unhealthy etcd member, because these values are needed later in the procedure. - -.. Remove the unhealthy etcd member by providing the ID to the `etcdctl member remove` command: -+ -[source,terminal] ----- -sh-4.2# etcdctl member remove 62bcf33650a7170a ----- -+ -.Example output -[source,terminal] ----- -Member 62bcf33650a7170a removed from cluster ead669ce1fbfb346 ----- - -.. View the member list again and verify that the member was removed: -+ -[source,terminal] ----- -sh-4.2# etcdctl member list -w table ----- -+ -.Example output -[source,terminal] ----- -+------------------+---------+------------------------------+---------------------------+---------------------------+ -| ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS | -+------------------+---------+------------------------------+---------------------------+---------------------------+ -| b78e2856655bc2eb | started | ip-10-0-164-97.ec2.internal | https://10.0.164.97:2380 | https://10.0.164.97:2379 | -| d022e10b498760d5 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 | -+------------------+---------+------------------------------+---------------------------+---------------------------+ ----- -+ -You can now exit the node shell. - -. Remove the old secrets for the unhealthy etcd member that was removed. - -.. List the secrets for the unhealthy etcd member that was removed. -+ -[source,terminal] ----- -$ oc get secrets -n openshift-etcd | grep ip-10-0-131-183.ec2.internal <1> ----- -<1> Pass in the name of the unhealthy etcd member that you took note of earlier in this procedure. -+ -There is a peer, serving, and metrics secret as shown in the following output: -+ -.Example output -[source,terminal] ----- -etcd-peer-ip-10-0-131-183.ec2.internal kubernetes.io/tls 2 47m -etcd-serving-ip-10-0-131-183.ec2.internal kubernetes.io/tls 2 47m -etcd-serving-metrics-ip-10-0-131-183.ec2.internal kubernetes.io/tls 2 47m ----- - -.. Delete the secrets for the unhealthy etcd member that was removed. - -... Delete the peer secret: -+ -[source,terminal] ----- -$ oc delete secret -n openshift-etcd etcd-peer-ip-10-0-131-183.ec2.internal ----- - -... Delete the serving secret: -+ -[source,terminal] ----- -$ oc delete secret -n openshift-etcd etcd-serving-ip-10-0-131-183.ec2.internal ----- - -... Delete the metrics secret: -+ -[source,terminal] ----- -$ oc delete secret -n openshift-etcd etcd-serving-metrics-ip-10-0-131-183.ec2.internal ----- - -. Force etcd redeployment. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc patch etcd cluster -p='{"spec": {"forceRedeploymentReason": "single-master-recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge <1> ----- -<1> The `forceRedeploymentReason` value must be unique, which is why a timestamp is appended. -+ -When the etcd cluster Operator performs a redeployment, it ensures that all master nodes have a functioning etcd pod. - -. Verify that the new member is available and healthy. - -.. Connect to the running etcd container again. -+ -In a terminal that has access to the cluster as a cluster-admin user, run the following command: -+ -[source,terminal] ----- -$ oc rsh -n openshift-etcd etcd-ip-10-0-154-204.ec2.internal ----- - -.. Verify that all members are healthy: -+ -[source,terminal] ----- -sh-4.2# etcdctl endpoint health --cluster ----- -+ -.Example output -[source,terminal] ----- -https://10.0.131.183:2379 is healthy: successfully committed proposal: took = 16.671434ms -https://10.0.154.204:2379 is healthy: successfully committed proposal: took = 16.698331ms -https://10.0.164.97:2379 is healthy: successfully committed proposal: took = 16.621645ms ----- diff --git a/modules/restore-replace-stopped-etcd-member.adoc b/modules/restore-replace-stopped-etcd-member.adoc deleted file mode 100644 index f923799976e8..000000000000 --- a/modules/restore-replace-stopped-etcd-member.adoc +++ /dev/null @@ -1,353 +0,0 @@ -// Module included in the following assemblies: -// -// * backup_and_restore/replacing-unhealthy-etcd-member.adoc - -[id="restore-replace-stopped-etcd-member_{context}"] -= Replacing an unhealthy etcd member whose machine is not running or whose node is not ready - -This procedure details the steps to replace an etcd member that is unhealthy either because the machine is not running or because the node is not ready. - -.Prerequisites - -* You have identified the unhealthy etcd member. -* You have verified that either the machine is not running or the node is not ready. -* You have access to the cluster as a user with the `cluster-admin` role. -* You have taken an etcd backup. -+ -[IMPORTANT] -==== -It is important to take an etcd backup before performing this procedure so that your cluster can be restored if you encounter any issues. -==== - -.Procedure - -. Remove the unhealthy member. - -.. Choose a pod that is _not_ on the affected node: -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc get pods -n openshift-etcd | grep -v etcd-quorum-guard | grep etcd ----- -+ -.Example output -[source,terminal] ----- -etcd-ip-10-0-131-183.ec2.internal 3/3 Running 0 123m -etcd-ip-10-0-164-97.ec2.internal 3/3 Running 0 123m -etcd-ip-10-0-154-204.ec2.internal 3/3 Running 0 124m ----- - -.. Connect to the running etcd container, passing in the name of a pod that is not on the affected node: -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc rsh -n openshift-etcd etcd-ip-10-0-154-204.ec2.internal ----- - -.. View the member list: -+ -[source,terminal] ----- -sh-4.2# etcdctl member list -w table ----- -+ -.Example output -[source,terminal] ----- -+------------------+---------+------------------------------+---------------------------+---------------------------+ -| ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS | -+------------------+---------+------------------------------+---------------------------+---------------------------+ -| 6fc1e7c9db35841d | started | ip-10-0-131-183.ec2.internal | https://10.0.131.183:2380 | https://10.0.131.183:2379 | -| 757b6793e2408b6c | started | ip-10-0-164-97.ec2.internal | https://10.0.164.97:2380 | https://10.0.164.97:2379 | -| ca8c2990a0aa29d1 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 | -+------------------+---------+------------------------------+---------------------------+---------------------------+ ----- -+ -Take note of the ID and the name of the unhealthy etcd member, because these values are needed later in the procedure. - -.. Remove the unhealthy etcd member by providing the ID to the `etcdctl member remove` command: -+ -[source,terminal] ----- -sh-4.2# etcdctl member remove 6fc1e7c9db35841d ----- -+ -.Example output -[source,terminal] ----- -Member 6fc1e7c9db35841d removed from cluster baa565c8919b060e ----- - -.. View the member list again and verify that the member was removed: -+ -[source,terminal] ----- -sh-4.2# etcdctl member list -w table ----- -+ -.Example output -[source,terminal] ----- -+------------------+---------+------------------------------+---------------------------+---------------------------+ -| ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS | -+------------------+---------+------------------------------+---------------------------+---------------------------+ -| 757b6793e2408b6c | started | ip-10-0-164-97.ec2.internal | https://10.0.164.97:2380 | https://10.0.164.97:2379 | -| ca8c2990a0aa29d1 | started | ip-10-0-154-204.ec2.internal | https://10.0.154.204:2380 | https://10.0.154.204:2379 | -+------------------+---------+------------------------------+---------------------------+---------------------------+ ----- -+ -You can now exit the node shell. - -. Remove the old secrets for the unhealthy etcd member that was removed. - -.. List the secrets for the unhealthy etcd member that was removed. -+ -[source,terminal] ----- -$ oc get secrets -n openshift-etcd | grep ip-10-0-131-183.ec2.internal <1> ----- -<1> Pass in the name of the unhealthy etcd member that you took note of earlier in this procedure. -+ -There is a peer, serving, and metrics secret as shown in the following output: -+ -.Example output -[source,terminal] ----- -etcd-peer-ip-10-0-131-183.ec2.internal kubernetes.io/tls 2 47m -etcd-serving-ip-10-0-131-183.ec2.internal kubernetes.io/tls 2 47m -etcd-serving-metrics-ip-10-0-131-183.ec2.internal kubernetes.io/tls 2 47m ----- - -.. Delete the secrets for the unhealthy etcd member that was removed. - -... Delete the peer secret: -+ -[source,terminal] ----- -$ oc delete secret -n openshift-etcd etcd-peer-ip-10-0-131-183.ec2.internal ----- - -... Delete the serving secret: -+ -[source,terminal] ----- -$ oc delete secret -n openshift-etcd etcd-serving-ip-10-0-131-183.ec2.internal ----- - -... Delete the metrics secret: -+ -[source,terminal] ----- -$ oc delete secret -n openshift-etcd etcd-serving-metrics-ip-10-0-131-183.ec2.internal ----- - -. Delete and recreate the master machine. After this machine is recreated, a new revision is forced and etcd scales up automatically. -+ -If you are running installer-provisioned infrastructure, or you used the Machine API to create your machines, follow these steps. Otherwise, you must create the new master using the same method that was used to originally create it. - -.. Obtain the machine for the unhealthy member. -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc get machines -n openshift-machine-api -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME PHASE TYPE REGION ZONE AGE NODE PROVIDERID STATE -clustername-8qw5l-master-0 Running m4.xlarge us-east-1 us-east-1a 3h37m ip-10-0-131-183.ec2.internal aws:///us-east-1a/i-0ec2782f8287dfb7e stopped <1> -clustername-8qw5l-master-1 Running m4.xlarge us-east-1 us-east-1b 3h37m ip-10-0-154-204.ec2.internal aws:///us-east-1b/i-096c349b700a19631 running -clustername-8qw5l-master-2 Running m4.xlarge us-east-1 us-east-1c 3h37m ip-10-0-164-97.ec2.internal aws:///us-east-1c/i-02626f1dba9ed5bba running -clustername-8qw5l-worker-us-east-1a-wbtgd Running m4.large us-east-1 us-east-1a 3h28m ip-10-0-129-226.ec2.internal aws:///us-east-1a/i-010ef6279b4662ced running -clustername-8qw5l-worker-us-east-1b-lrdxb Running m4.large us-east-1 us-east-1b 3h28m ip-10-0-144-248.ec2.internal aws:///us-east-1b/i-0cb45ac45a166173b running -clustername-8qw5l-worker-us-east-1c-pkg26 Running m4.large us-east-1 us-east-1c 3h28m ip-10-0-170-181.ec2.internal aws:///us-east-1c/i-06861c00007751b0a running ----- -<1> This is the master machine for the unhealthy node, `ip-10-0-131-183.ec2.internal`. - -.. Save the machine configuration to a file on your file system: -+ -[source,terminal] ----- -$ oc get machine clustername-8qw5l-master-0 \ <1> - -n openshift-machine-api \ - -o yaml \ - > new-master-machine.yaml ----- -<1> Specify the name of the master machine for the unhealthy node. - -.. Edit the `new-master-machine.yaml` file that was created in the previous step to assign a new name and remove unnecessary fields. - -... Remove the entire `status` section: -+ -[source,yaml] ----- -status: - addresses: - - address: 10.0.131.183 - type: InternalIP - - address: ip-10-0-131-183.ec2.internal - type: InternalDNS - - address: ip-10-0-131-183.ec2.internal - type: Hostname - lastUpdated: "2020-04-20T17:44:29Z" - nodeRef: - kind: Node - name: ip-10-0-131-183.ec2.internal - uid: acca4411-af0d-4387-b73e-52b2484295ad - phase: Running - providerStatus: - apiVersion: awsproviderconfig.openshift.io/v1beta1 - conditions: - - lastProbeTime: "2020-04-20T16:53:50Z" - lastTransitionTime: "2020-04-20T16:53:50Z" - message: machine successfully created - reason: MachineCreationSucceeded - status: "True" - type: MachineCreation - instanceId: i-0fdb85790d76d0c3f - instanceState: stopped - kind: AWSMachineProviderStatus ----- - -... Change the `metadata.name` field to a new name. -+ -It is recommended to keep the same base name as the old machine and change the ending number to the next available number. In this example, `clustername-8qw5l-master-0` is changed to `clustername-8qw5l-master-3`. -+ -For example: -+ -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: Machine -metadata: - ... - name: clustername-8qw5l-master-3 - ... ----- - -... Update the `metadata.selfLink` field to use the new machine name from the previous step. -+ -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: Machine -metadata: - ... - selfLink: /apis/machine.openshift.io/v1beta1/namespaces/openshift-machine-api/machines/clustername-8qw5l-master-3 - ... ----- - -... Remove the `spec.providerID` field: -+ -[source,yaml] ----- - providerID: aws:///us-east-1a/i-0fdb85790d76d0c3f ----- - -... Remove the `metadata.annotations` and `metadata.generation` fields: -+ -[source,yaml] ----- - annotations: - machine.openshift.io/instance-state: running - ... - generation: 2 ----- - -... Remove the `metadata.resourceVersion` and `metadata.uid` fields: -+ -[source,yaml] ----- - resourceVersion: "13291" - uid: a282eb70-40a2-4e89-8009-d05dd420d31a ----- - -.. Delete the machine of the unhealthy member: -+ -[source,terminal] ----- -$ oc delete machine -n openshift-machine-api clustername-8qw5l-master-0 <1> ----- -<1> Specify the name of the master machine for the unhealthy node. - -.. Verify that the machine was deleted: -+ -[source,terminal] ----- -$ oc get machines -n openshift-machine-api -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME PHASE TYPE REGION ZONE AGE NODE PROVIDERID STATE -clustername-8qw5l-master-1 Running m4.xlarge us-east-1 us-east-1b 3h37m ip-10-0-154-204.ec2.internal aws:///us-east-1b/i-096c349b700a19631 running -clustername-8qw5l-master-2 Running m4.xlarge us-east-1 us-east-1c 3h37m ip-10-0-164-97.ec2.internal aws:///us-east-1c/i-02626f1dba9ed5bba running -clustername-8qw5l-worker-us-east-1a-wbtgd Running m4.large us-east-1 us-east-1a 3h28m ip-10-0-129-226.ec2.internal aws:///us-east-1a/i-010ef6279b4662ced running -clustername-8qw5l-worker-us-east-1b-lrdxb Running m4.large us-east-1 us-east-1b 3h28m ip-10-0-144-248.ec2.internal aws:///us-east-1b/i-0cb45ac45a166173b running -clustername-8qw5l-worker-us-east-1c-pkg26 Running m4.large us-east-1 us-east-1c 3h28m ip-10-0-170-181.ec2.internal aws:///us-east-1c/i-06861c00007751b0a running ----- - -.. Create the new machine using the `new-master-machine.yaml` file: -+ -[source,terminal] ----- -$ oc apply -f new-master-machine.yaml ----- - - -.. Verify that the new machine has been created: -+ -[source,terminal] ----- -$ oc get machines -n openshift-machine-api -o wide ----- -+ -.Example output -[source,terminal] ----- -NAME PHASE TYPE REGION ZONE AGE NODE PROVIDERID STATE -clustername-8qw5l-master-1 Running m4.xlarge us-east-1 us-east-1b 3h37m ip-10-0-154-204.ec2.internal aws:///us-east-1b/i-096c349b700a19631 running -clustername-8qw5l-master-2 Running m4.xlarge us-east-1 us-east-1c 3h37m ip-10-0-164-97.ec2.internal aws:///us-east-1c/i-02626f1dba9ed5bba running -clustername-8qw5l-master-3 Provisioning m4.xlarge us-east-1 us-east-1a 85s ip-10-0-133-53.ec2.internal aws:///us-east-1a/i-015b0888fe17bc2c8 running <1> -clustername-8qw5l-worker-us-east-1a-wbtgd Running m4.large us-east-1 us-east-1a 3h28m ip-10-0-129-226.ec2.internal aws:///us-east-1a/i-010ef6279b4662ced running -clustername-8qw5l-worker-us-east-1b-lrdxb Running m4.large us-east-1 us-east-1b 3h28m ip-10-0-144-248.ec2.internal aws:///us-east-1b/i-0cb45ac45a166173b running -clustername-8qw5l-worker-us-east-1c-pkg26 Running m4.large us-east-1 us-east-1c 3h28m ip-10-0-170-181.ec2.internal aws:///us-east-1c/i-06861c00007751b0a running ----- -<1> The new machine, `clustername-8qw5l-master-3` is being created and is ready once the phase changes from `Provisioning` to `Running`. -+ -It might take a few minutes for the new machine to be created. The etcd cluster Operator will automatically sync when the machine or node returns to a healthy state. - -. Verify that all etcd pods are running properly: -+ -In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc get pods -n openshift-etcd | grep -v etcd-quorum-guard | grep etcd ----- -+ -.Example output -[source,terminal] ----- -etcd-ip-10-0-133-53.ec2.internal 3/3 Running 0 7m49s -etcd-ip-10-0-164-97.ec2.internal 3/3 Running 0 123m -etcd-ip-10-0-154-204.ec2.internal 3/3 Running 0 124m ----- -+ -If the output from the previous command only lists two pods, you can manually force an etcd redeployment. In a terminal that has access to the cluster as a `cluster-admin` user, run the following command: -+ -[source,terminal] ----- -$ oc patch etcd cluster -p='{"spec": {"forceRedeploymentReason": "recovery-'"$( date --rfc-3339=ns )"'"}}' --type=merge <1> ----- -<1> The `forceRedeploymentReason` value must be unique, which is why a timestamp is appended. -+ diff --git a/modules/restoring-an-external-postgresql-database.adoc b/modules/restoring-an-external-postgresql-database.adoc new file mode 100644 index 000000000000..0c7602a67efc --- /dev/null +++ b/modules/restoring-an-external-postgresql-database.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/restore-acs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restoring-an-external-postgresql-database_{context}"] += Restoring an external PostgreSQL database + +By restoring an external PostgreSQL database, you can recover your {rh-rhacs-first} instance from a backup while maintaining your existing database setup. + +This procedure focuses on restoring the database that contains your {product-title-short} system data. You can perform a PostgreSQL database restore by using the vendor-recommended `pg_restore` command. + +.Prerequisites + +* You have scaled down Central to `0`. + +.Procedure + +. To perform a PostgreSQL restore, run the following command: ++ +[source,terminal] +---- +$ pg_restore -U <username> -d <database_name> <path_to_backup_file> +---- ++ +where: + +`<username>`:: Specifies the actual user name. +`<database_name>`:: Specifies the name of the target database. +`<path_to_backup_file>`:: Specifies the location and name of the file you want to restore. You can use `.tar`, `.gz`, or another custom file format. + +After you restore the external PostgreSQL database, you must restore the {product-title-short} Central certificates. \ No newline at end of file diff --git a/modules/restoring-central-certificates-and-redeploying-central.adoc b/modules/restoring-central-certificates-and-redeploying-central.adoc new file mode 100644 index 000000000000..e1fa557199e5 --- /dev/null +++ b/modules/restoring-central-certificates-and-redeploying-central.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/restore-acs.adoc + +:_mod-docs-content-type: PROCEDURE +[id="restoring-central-certificates-and-redeploying-central_{context}"] += Restoring the Central certificates and redeploying Central + +You must restore the Central certificates and redeploy Central to ensure that authentication certificates for secured clusters and API tokens remain valid for the redeployed Central instance. + +.Procedure + +* Run the `roxctl central generate interactive` command and provide the path to your backup file, which creates a central-bundle folder with the necessary manifests and scripts. ++ +You can then use these files to install Central, ensuring that all your authentication certificates and API tokens remain valid. ++ +For more information, see "Restore certificates using the roxctl CLI". \ No newline at end of file diff --git a/modules/resume-acs-restore.adoc b/modules/resume-acs-restore.adoc new file mode 100644 index 000000000000..1ca321a286eb --- /dev/null +++ b/modules/resume-acs-restore.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * backup_and_restore/restore-acs.adoc +// * troubleshooting_central/restoring-central-database-by-using-the-roxctl-cli.adoc + +:_mod-docs-content-type: CONCEPT +[id="resume-acs-restore_{context}"] += Resuming the restore operation + +[role="_abstract"] +If your connection is interrupted during a restore operation or you need to go offline, you can resume the restore operation. + +* If you do not have access to the machine running the resume operation, you can use the `roxctl central db restore status` command to check the status of an ongoing restore operation. +* If the connection is interrupted, the `roxctl` CLI automatically attempts to restore a task as soon as the connection is available again. +The automatic connection retries depend on the duration specified by the `timeout` option. +* Use the `--timeout` option to specify the time in seconds, minutes or hours after which the `roxctl` CLI stops trying to resume a restore operation. +If the option is not specified, the default timeout is 10 minutes. +* If a restore operation gets stuck or you want to cancel it, use the `roxctl central db restore cancel` command to cancel a running restore operation. +* If a restore operation is stuck, you have canceled it, or the time has expired, you can resume the previous restore by running the original command again. + +[IMPORTANT] +==== +* During interruptions, {product-title-short} caches an ongoing restore operation for 24 hours. +You can resume this operation by executing the original restore command again. +* The `--timeout` option only controls the client-side connection retries and has no effect on the server-side restore cache of 24 hours. +* You cannot resume restores across Central pod restarts. +* If a restore operation is interrupted, you must restart it within 24 hours and before restarting Central, otherwise {product-title-short} cancels the restore operation. +==== diff --git a/modules/retag-images.adoc b/modules/retag-images.adoc new file mode 100644 index 000000000000..ac9e91ac736b --- /dev/null +++ b/modules/retag-images.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: PROCEDURE +[id="topic-name_{context}"] += Retagging images + +You can download and retag images using the Docker command-line interface. + +[IMPORTANT] +==== +When you retag an image, you must maintain the name of the image and the tag. For example, use: +[source,terminal,subs=attributes+] +---- +$ docker tag registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} <your_registry>/rhacs-main-rhel8:{rhacs-version} +---- +and do not retag like the following example: +[source,terminal,subs=attributes+] +---- +$ docker tag registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} <your_registry>/other-name:latest +---- +==== + +.Procedure +. Log in to the registry: ++ +[source,terminal] +---- +$ docker login registry.redhat.io +---- +. Pull the image: ++ +[source,terminal] +---- +$ docker pull <image> +---- +. Retag the image: ++ +[source,terminal] +---- +$ docker tag <image> <new_image> +---- +. Push the updated image to your registry: ++ +[source,terminal] +---- +$ docker push <new_image> +---- diff --git a/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc b/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc new file mode 100644 index 000000000000..e36ccbe64fee --- /dev/null +++ b/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: PROCEDURE +[id="retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory_{context}"] += Retrieving connectivity mapping information from a Kubernetes manifest directory + +[role="_abstract"] +Retrieve connectivity mapping information from a Kubernetes manifest directory by using the `roxctl netpol connectivity map` command. + +.Procedure + +* To retrieve the connectivity mapping information, run the following command: ++ +[source,terminal,subs="+quotes"] +---- +roxctl netpol connectivity map <folder_path> [flags] <1> +---- ++ +<1> Specify the path to the folder, which can include sub-folders that contain YAML resources and network policies for analysis, for example, link:https://github.com/np-guard/netpol-analyzer/tree/main/tests/netpol-analysis-example-minimal[`netpol-analysis-example-minimal/`]. The command scans the entire sub-folder tree. Optionally, you can also specify parameters to modify the behavior of the command. ++ +.Example output + +[cols="2,2,1",options="header"] +|=== + +|src |dst |conn + +|0.0.0.0-255.255.255.255 +|default/frontend[Deployment] +|TCP 8080 + +|default/frontend[Deployment] +|0.0.0.0-255.255.255.255 +|UDP 53 + +|default/frontend[Deployment] +|default/backend[Deployment] +|TCP 9090 + +|=== + +The output displays a table listing the allowed connectivity lines. +Each line is composed of the following elements: + +* `src`:: Represents the source endpoint. +* `dst`:: Represents the destination endpoint. +* `conn`:: Represents the permissible connectivity attributes. + +An endpoint follows the format `namespace/name[Kind]`. For example, `default/backend[Deployment]`. + +Opional: To see which policies and rules are responsible for allowing or denying specific connections, you can use the `--explain` option with the `roxctl netpol connectivity map` command. +You can use the output to debug network policy configurations. +For more information about understanding the explanation output, see "Retriving explanations". diff --git a/modules/retrieving-debugging-information.adoc b/modules/retrieving-debugging-information.adoc new file mode 100644 index 000000000000..6b65a0048441 --- /dev/null +++ b/modules/retrieving-debugging-information.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * cli/debugging-issues.adoc +:_mod-docs-content-type: PROCEDURE +[id="retrieving-debugging-information_{context}"] += Retrieving debugging information + +.Procedure + +* Run the following command to gather the debugging information for investigating issues: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl central debug dump +---- + +* To generate a diagnostic bundle with the {product-title-short} administrator password or API token and central address, follow the procedure in xref:../support/getting-support.adoc#generate-diagnostic-bundle-using-roxctl-cli_getting-support[Generating a diagnostic bundle by using the roxctl CLI]. \ No newline at end of file diff --git a/modules/retrieving-explanations.adoc b/modules/retrieving-explanations.adoc new file mode 100644 index 000000000000..73472f492ed0 --- /dev/null +++ b/modules/retrieving-explanations.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: PROCEDURE +[id="retrieving-explanations_{context}"] += Retrieving explanations + +[role="_abstract"] +You can understand why connections are allowed or denied based on your Kubernetes network policy rules by retrieving the explanations. + +.Procedure + +* To generate a connectivity report with explanations, run the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl netpol connectivity map --explain <folder_path> <1> +---- ++ +<1> Specify the path to the folder, which can include sub-folders that contain YAML resources and network policies for analysis. + +When you use the `--explain` flag, the connectivity report includes an *explanation section* that details the specific policies and rules relevant to each allowed or blocked connection. diff --git a/modules/retrieving-the-collector-logs.adoc b/modules/retrieving-the-collector-logs.adoc new file mode 100644 index 000000000000..2d35d0573c2b --- /dev/null +++ b/modules/retrieving-the-collector-logs.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * troubleshooting/retrieving-and-analyzing-the-collector-logs-and-pod-status.adoc +:_mod-docs-content-type: CONCEPT +[id="retrieving-the-collector-logs_{context}"] + += Retrieving the Collector logs + +First, you should examine the logs from failing Collectors. Depending on your environment and access rights, you can obtain these logs in two ways: + + +* xref:../troubleshooting/retrieving-and-analyzing-the-collector-logs-and-pod-status.adoc#retrieving-the-logs-with-the-oc-or-kubectl-command_logs-and-pod-status[Retrieving the logs with the `oc` or `kubectl` command] + +* xref:../troubleshooting/retrieving-and-analyzing-the-collector-logs-and-pod-status.adoc#retrieving-logs-from-a-rhacs-diagnostic-bundle_logs-and-pod-status[Retrieving logs from a {product-title-short} diagnostic bundle] diff --git a/modules/retrieving-the-logs-with-the-oc-or-kubectl-command.adoc b/modules/retrieving-the-logs-with-the-oc-or-kubectl-command.adoc new file mode 100644 index 000000000000..f95d490ae7c4 --- /dev/null +++ b/modules/retrieving-the-logs-with-the-oc-or-kubectl-command.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * troubleshooting/retrieving-and-analyzing-the-collector-logs-and-pod-status.adoc +:_mod-docs-content-type: PROCEDURE +[id="retrieving-the-logs-with-the-oc-or-kubectl-command_{context}"] += Retrieving the logs with the `oc` or `kubectl` command + +You can use either the `oc` or `kubectl` command to obtain logs from your running Collector pod. Optionally, you can even check the logs from a previous Collector pod if your current Collector pod is restarting. + +.Prerequisites + +* Ensure that you have the authority to list the pods and logs: ++ +[source,terminal] +---- +$ oc auth can-i get pods && oc auth can-i get pods --subresource=logs <1> +---- ++ +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +.Procedure + +. List all the pods with label `app=collector`: ++ +[source,terminal] +---- +$ oc get pods -n stackrox -l app=collector <1> +---- ++ +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +.Example output ++ +[source,terminal] +---- +collector-vclg5 1/2 CrashLoopBackOff 2 (25s ago) 2m41s+ +---- + +. Get the logs for the Collector pod: ++ +[source,terminal,subs="+quotes"] +---- +$ oc logs -n stackrox _<collector_pod_name>_ collector <1> +---- ++ +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. For +`_<collector_pod_name>_`, specify the name of your Collector pod, for example, `collector-vclg5`. + +. (Optional) If the current Collector pod is restarting, you can check the logs for the previous Collector pod: ++ +[source,terminal,subs="+quotes"] +---- +$ oc logs -n stackrox _<collector_pod_name>_ collector --previous <1> +---- ++ +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. For +`_<collector_pod_name>_`, specify the name of your Collector pod, for example, `collector-vclg5`. \ No newline at end of file diff --git a/modules/reviewing-cluster-status-from-the-openshift-cluster-manager.adoc b/modules/reviewing-cluster-status-from-the-openshift-cluster-manager.adoc deleted file mode 100644 index c07904a5b91e..000000000000 --- a/modules/reviewing-cluster-status-from-the-openshift-cluster-manager.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc - -[id="reviewing-cluster-status-from-the-openshift-cluster-manager_{context}"] -= Reviewing the cluster status from the {cloud-redhat-com} - -You can review detailed information about the status of your cluster in the {cloud-redhat-com}. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. In the *Administrator* perspective, navigate to *Home* -> *Overview* -> *Details* -> *OpenShift Cluster Manager* to open the *Overview* page for the cluster in the {cloud-redhat-com}. -+ -[NOTE] -==== -Alternatively, you can navigate to the link:https://cloud.redhat.com/openshift/[{cloud-redhat-com}] directly and select your cluster ID from the list of available clusters. -==== - -. In the *Overview* page, review the following information about your cluster: -+ -* vCPU and memory availability and resource usage -+ -* The cluster ID, status, type, location, and the provider name -+ -* Node counts by node type -+ -* Cluster version details, the creation date of the cluster, and the name of the cluster owner -+ -* The life cycle support status of the cluster -+ -* Subscription information, including the service level agreement (SLA) status, the subscription unit type, the production status of the cluster, the subscription obligation, and the service level -+ -* A cluster history - -. Navigate to the *Monitoring* page to review the following information: -* A list of any issues that have been detected -+ -* A list of alerts that are firing -+ -* The cluster Operator status and version -+ -* Cluster resource usage - -. Navigate to the *Insights* page to review the following information provided by Red Hat Insights: -* Potential issues that your cluster might be exposed to, categorized by risk level -+ -* Health-check status by category diff --git a/modules/reviewing-cluster-status-from-the-openshift-web-console.adoc b/modules/reviewing-cluster-status-from-the-openshift-web-console.adoc deleted file mode 100644 index 878ea9d6c569..000000000000 --- a/modules/reviewing-cluster-status-from-the-openshift-web-console.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc - -[id="reviewing-cluster-status-from-the-openshift-web-console_{context}"] -= Reviewing the cluster status from the {product-title} web console - -You can review the following information in the *Overview* page in the {product-title} web console: - -* The general status of your cluster - -* The status of the control plane, cluster Operators, and storage - -* CPU, memory, file system, network transfer, and pod availability - -* The API address of the cluster, the cluster ID, and the name of the provider - -* Cluster version information - -* Cluster update status, including details of the current update channel and available updates - -* A cluster inventory detailing node, pod, storage class, and persistent volume claim (PVC) information - -* A list of ongoing cluster activities and recent events - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -* In the *Administrator* perspective, navigate to *Home* -> *Overview*. - - diff --git a/modules/reviewing-node-status-usage-and-configuration.adoc b/modules/reviewing-node-status-usage-and-configuration.adoc deleted file mode 100644 index bf3f01635ea0..000000000000 --- a/modules/reviewing-node-status-usage-and-configuration.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/verifying-node-health.adoc - -[id="reviewing-node-status-use-and-configuration_{context}"] -= Reviewing node status, resource usage, and configuration - -Review cluster node health status, resource consumption statistics, and node logs. Additionally, query `kubelet` status on individual nodes. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. List the name, status, and role for all nodes in the cluster: -+ -[source,terminal] ----- -$ oc get nodes ----- - -. Summarize CPU and memory usage for each node within the cluster: -+ -[source,terminal] ----- -$ oc adm top nodes ----- - -. Summarize CPU and memory usage for a specific node: -+ -[source,terminal] ----- -$ oc adm top node -l my-node ----- diff --git a/modules/reviewing-pod-status.adoc b/modules/reviewing-pod-status.adoc deleted file mode 100644 index d82d4807a09d..000000000000 --- a/modules/reviewing-pod-status.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/investigating-pod-issues.adoc - -[id="reviewing-pod-status_{context}"] -= Reviewing pod status - -You can query pod status and error states. You can also query a pod's associated deployment configuration and review base image availability. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* `skopeo` is installed. - -.Procedure - -. Switch into a project: -+ -[source,terminal] ----- -$ oc project <project_name> ----- - -. List pods running within the namespace, as well as pod status, error states, restarts, and age: -+ -[source,terminal] ----- -$ oc get pods ----- - -. Determine whether the namespace is managed by a deployment configuration: -+ -[source,terminal] ----- -$ oc status ----- -+ -If the namespace is managed by a deployment configuration, the output includes the deployment configuration name and a base image reference. - -. Inspect the base image referenced in the preceding command's output: -+ -[source,terminal] ----- -$ skopeo inspect docker://<image_reference> ----- - -. If the base image reference is not correct, update the reference in the deployment configuration: -+ -[source,terminal] ----- -$ oc edit deployment/my-deployment ----- - -. When deployment configuration changes on exit, the configuration will automatically redeploy. Watch pod status as the deployment progresses, to determine whether the issue has been resolved: -+ -[source,terminal] ----- -$ oc get pods -w ----- - -. Review events within the namespace for diagnostic information relating to pod failures: -+ -[source,terminal] ----- -$ oc get events ----- diff --git a/modules/reviewing-the-installation-log.adoc b/modules/reviewing-the-installation-log.adoc deleted file mode 100644 index d6a1b4397ac9..000000000000 --- a/modules/reviewing-the-installation-log.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// *installing/validating-an-installation.adoc - -[id="reviewing-the-installation-log_{context}"] -= Reviewing the installation log - -You can review a summary of an installation in the {product-title} installation log. If an installation succeeds, the information required to access the cluster is included in the log. - -.Prerequisites - -* You have access to the installation host. - -.Procedure - -* Review the `.openshift_install.log` log file in the installation directory on your installation host: -+ -[source,terminal] ----- -$ cat <install_dir>/.openshift_install.log ----- -+ -.Example output -+ -Cluster credentials are included at the end of the log if the installation is successful, as outlined in the following example: -+ -[source,terminal] ----- -... -time="2020-12-03T09:50:47Z" level=info msg="Install complete!" -time="2020-12-03T09:50:47Z" level=info msg="To access the cluster as the system:admin user when using 'oc', run 'export KUBECONFIG=/home/myuser/install_dir/auth/kubeconfig'" -time="2020-12-03T09:50:47Z" level=info msg="Access the OpenShift web-console here: https://console-openshift-console.apps.mycluster.example.com" -time="2020-12-03T09:50:47Z" level=info msg="Login to the console with user: \"kubeadmin\", and password: \"6zYIx-ckbW3-4d2Ne-IWvDF\"" -time="2020-12-03T09:50:47Z" level=debug msg="Time elapsed per stage:" -time="2020-12-03T09:50:47Z" level=debug msg=" Infrastructure: 6m45s" -time="2020-12-03T09:50:47Z" level=debug msg="Bootstrap Complete: 11m30s" -time="2020-12-03T09:50:47Z" level=debug msg=" Bootstrap Destroy: 1m5s" -time="2020-12-03T09:50:47Z" level=debug msg=" Cluster Operators: 17m31s" -time="2020-12-03T09:50:47Z" level=info msg="Time elapsed: 37m26s" ----- diff --git a/modules/revoke-the-api-token.adoc b/modules/revoke-the-api-token.adoc new file mode 100644 index 000000000000..9739480c794f --- /dev/null +++ b/modules/revoke-the-api-token.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-44.adoc +:_mod-docs-content-type: PROCEDURE +[id="revoke-the-api-token_{context}"] += Revoking the API token + +[role="_abstract"] +For security reasons, Red{nbsp}Hat recommends that you revoke the API token that you have used to complete Central database backup. + +.Prerequisites +* After the upgrade, you must reload the {product-title-short} portal page and re-accept the certificate to continue using the {product-title-short} portal. + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Authentication Tokens* category, and click *API Token*. +. Select the checkbox in front of the token name that you want to revoke. +. Click *Revoke*. +. On the confirmation dialog box, click *Confirm*. diff --git a/modules/rhcos-about.adoc b/modules/rhcos-about.adoc deleted file mode 100644 index 38d5e9ea2326..000000000000 --- a/modules/rhcos-about.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture_rhcos.adoc - -[id="rhcos-about_{context}"] -= About {op-system} - -{op-system-first} represents the next generation of single-purpose container operating system technology. Created by the same development teams that created Red Hat Enterprise Linux Atomic Host and CoreOS Container Linux, {op-system} combines the quality standards of {op-system-base-full} with the automated, remote upgrade features from Container Linux. - -{op-system} is supported only as a component of {product-title} {product-version} for all {product-title} machines. {op-system} is the only supported operating system for {product-title} control plane, or master, machines. While {op-system} is the default operating system for all cluster machines, you can create compute machines, which are also known as worker machines, that use {op-system-base} as their operating system. There are two general ways {op-system} is deployed in {product-title} {product-version}: - -* If you install your cluster on infrastructure that the cluster provisions, {op-system} images are downloaded to the target platform during installation, and suitable Ignition config files, which control the {op-system} configuration, are used to deploy the machines. - -* If you install your cluster on infrastructure that you manage, you must follow the installation documentation to obtain the {op-system} images, generate Ignition config files, and use the Ignition config files to provision your machines. - -[id="rhcos-key-features_{context}"] -== Key {op-system} features - -The following list describes key features of the {op-system} operating system: - -* **Based on {op-system-base}**: The underlying operating system consists primarily of {op-system-base} components. The same quality, security, and control measures that support {op-system-base} also support {op-system}. For example, {op-system} software is in RPM packages, and each {op-system} system starts up with a {op-system-base} kernel and a set of services that are managed by the systemd init system. - -* **Controlled immutability**: Although it contains {op-system-base} components, {op-system} is designed to be managed more tightly than a default {op-system-base} installation. Management is performed remotely from the {product-title} cluster. When you set up your {op-system} machines, you can modify only a few system settings. This controlled immutability allows {product-title} to store the latest state of {op-system} systems in the cluster so it is always able to create additional machines and perform updates based on the latest {op-system} configurations. - -* **CRI-O container runtime**: Although {op-system} contains features for running the OCI- and libcontainer-formatted containers that Docker requires, it incorporates the CRI-O container engine instead of the Docker container engine. By focusing on features needed by Kubernetes platforms, such as {product-title}, CRI-O can offer specific compatibility with different Kubernetes versions. CRI-O also offers a smaller footprint and reduced attack surface than is possible with container engines that offer a larger feature set. At the moment, CRI-O is only available as a container engine within {product-title} clusters. - -* **Set of container tools**: For tasks such as building, copying, and otherwise managing containers, {op-system} replaces the Docker CLI tool with a compatible set of container tools. The podman CLI tool supports many container runtime features, such as running, starting, stopping, listing, and removing containers and container images. The skopeo CLI tool can copy, authenticate, and sign images. You can use the `crictl` CLI tool to work with containers and pods from the CRI-O container engine. While direct use of these tools in {op-system} is discouraged, you can use them for debugging purposes. - -* **rpm-ostree upgrades**: {op-system} features transactional upgrades using the `rpm-ostree` system. Updates are delivered by means of container images and are part of the {product-title} update process. When deployed, the container image is pulled, extracted, and written to disk, then the bootloader is modified to boot into the new version. The machine will reboot into the update in a rolling manner to ensure cluster capacity is minimally impacted. - -* **bootupd firmware and bootloader updater**: Package managers and hybrid systems such as `rpm-ostree` do not update the firmware or the bootloader. With `bootupd`, {op-system} users have access to a cross-distribution, system-agnostic update tool that manages firmware and boot updates in UEFI and legacy BIOS boot modes that run on modern architectures, such as x86_64, ppc64le, and aarch64. -+ -For information about how to install `bootupd`, see the documentation for _Updating the bootloader using bootupd_ for more information. - -* **Updated through the Machine Config Operator**: In {product-title}, the Machine Config Operator handles operating system upgrades. Instead of upgrading individual packages, as is done with `yum` upgrades, `rpm-ostree` delivers upgrades of the OS as an atomic unit. The new OS deployment is staged during upgrades and goes into effect on the next reboot. If something goes wrong with the upgrade, a single rollback and reboot returns the system to the previous state. {op-system} upgrades in {product-title} are performed during cluster updates. - -For {op-system} systems, the layout of the `rpm-ostree` file system has the following characteristics: - -* `/usr` is where the operating system binaries and libraries are stored and is read-only. We do not support altering this. -* `/etc`, `/boot`, `/var` are writable on the system but only intended to be altered by the Machine Config Operator. -* `/var/lib/containers` is the graph storage location for storing container images. - -[id="rhcos-configured_{context}"] -== Choosing how to configure {op-system} - -{op-system} is designed to deploy on an {product-title} cluster with a minimal amount of user configuration. In its most basic form, this consists of: - -* Starting with a provisioned infrastructure, such as on AWS, or provisioning the infrastructure yourself. - -* Supplying a few pieces of information, such as credentials and cluster name, in an `install-config.yaml` file when running `openshift-install`. - -Because {op-system} systems in {product-title} are designed to be fully managed from the {product-title} cluster after that, directly changing an {op-system} machine is discouraged. Although limited direct access to {op-system} machines cluster can be accomplished for debugging purposes, you should not directly configure {op-system} systems. Instead, if you need to add or change features on your {product-title} nodes, consider making changes in the following ways: - -* **Kubernetes workload objects, such as DaemonSet and Deployment**: If you need to add services or other user-level features to your cluster, consider adding them as Kubernetes workload objects. Keeping those features outside of specific node configurations is the best way to reduce the risk of breaking the cluster on subsequent upgrades. - -* **Day-2 customizations**: If possible, bring up a cluster without making any customizations to cluster nodes and make necessary node changes after the cluster is up. Those changes are easier to track later and less likely to break updates. Creating machine configs or modifying Operator custom resources are ways of making these customizations. - -* **Day-1 customizations**: For customizations that you must implement when the cluster first comes up, there are ways of modifying your cluster so changes are implemented on first boot. -Day-1 customizations can be done through Ignition configs and manifest files during `openshift-install` or by adding boot options during ISO installs provisioned by the user. - -Here are examples of customizations you could do on day 1: - -* **Kernel arguments**: If particular kernel features or tuning is needed on nodes when the cluster first boots. -* **Disk encryption**: If your security needs require that the root file system on the nodes are encrypted, such as with FIPS support. -* **Kernel modules**: If a particular hardware device, such as a network card or video card, does not have a usable module available by default in the Linux kernel. -* **Chronyd**: If you want to provide specific clock settings to your nodes, such as the location of time servers. - -To accomplish these tasks, you can augment the `openshift-install` process to include additional objects such as `MachineConfig` objects. Those procedures that result in creating machine configs can be passed to the Machine Config Operator after the cluster is up. - - -[NOTE] -==== -The Ignition config files that the installation program generates contain certificates that expire after 24 hours, which are then renewed at that time. If the cluster is shut down before renewing the certificates and the cluster is later restarted after the 24 hours have elapsed, the cluster automatically recovers the expired certificates. The exception is that you must manually approve the pending `node-bootstrapper` certificate signing requests (CSRs) to recover kubelet certificates. See the documentation for _Recovering from expired control plane certificates_ for more information. -==== - -[id="rhcos-deployed_{context}"] -== Choosing how to deploy {op-system} - -Differences between {op-system} installations for {product-title} are based on whether you are deploying on an infrastructure provisioned by the installer or by the user: - -* **Installer-provisioned**: Some cloud environments offer pre-configured infrastructures that allow you to bring up an {product-title} cluster with minimal configuration. For these types of installations, you can supply Ignition configs that place content on each node so it is there when the cluster first boots. - -* **User-provisioned**: If you are provisioning your own infrastructure, you have more flexibility in how you add content to a {op-system} node. For example, you could add kernel arguments when you boot the {op-system} ISO installer to install each system. However, in most cases where configuration is required on the operating system itself, it is best to provide that configuration through an Ignition config. - -The Ignition facility runs only when the {op-system} system is first set up. After that, Ignition configs can be supplied later using the machine config. - -[id="rhcos-about-ignition_{context}"] -== About Ignition - -Ignition is the utility that is used by {op-system} to manipulate disks during initial configuration. It completes common disk tasks, including partitioning disks, formatting partitions, writing files, and configuring users. On first boot, Ignition reads its configuration from the installation media or the location that you specify and applies the configuration to the machines. - -Whether you are installing your cluster or adding machines to it, Ignition always performs the initial configuration of the {product-title} cluster machines. Most of the actual system setup happens on each machine itself. For each machine, Ignition takes the {op-system} image and boots the {op-system} kernel. Options on the kernel command line, identify the type of deployment and the location of the Ignition-enabled initial Ram disk (initramfs). - -//// -//// - -[id="about-ignition_{context}"] -=== How Ignition works - -To create machines by using Ignition, you need Ignition config files. The {product-title} installation program creates the Ignition config files that you need to deploy your cluster. These files are based on the information that you provide to the installation program directly or through an `install-config.yaml` file. - -The way that Ignition configures machines is similar to how tools like https://cloud-init.io/[cloud-init] or Linux Anaconda https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/installation_guide/index#chap-kickstart-installations[kickstart] configure systems, but with some important differences: - -//// -The order of information in those files does not matter. For example, if a file needs a directory several levels deep, if another file needs a directory along that path, the later file is created first. Ignition sorts and creates all files, directories, and links by depth. -//// - -* Ignition runs from an initial RAM disk that is separate from the system you are installing to. Because of that, Ignition can repartition disks, set up file systems, and perform other changes to the machine’s permanent file system. In contrast, cloud-init runs as part of a machine’s init system when the system boots, so making foundational changes to things like disk partitions cannot be done as easily. With cloud-init, it is also difficult to reconfigure the boot process while you are in the middle of the node's boot process. - -* Ignition is meant to initialize systems, not change existing systems. After a machine initializes and the kernel is running from the installed system, the Machine Config Operator from the {product-title} cluster completes all future machine configuration. -* Instead of completing a defined set of actions, Ignition implements a declarative configuration. It checks that all partitions, files, services, and other items are in place before the new machine starts. It then makes the changes, like copying files to disk that are necessary for the new machine to meet the specified configuration. - -* After Ignition finishes configuring a machine, the kernel keeps running but discards the initial RAM disk and pivots to the installed system on disk. All of the new system services and other features start without requiring a system reboot. - -* Because Ignition confirms that all new machines meet the declared configuration, you cannot have a partially-configured machine. If a machine’s setup fails, the initialization process does not finish, and Ignition does not start the new machine. Your cluster will never contain partially-configured machines. If Ignition cannot complete, the machine is not added to the cluster. You must add a new machine instead. This behavior prevents the difficult case of debugging a machine when the results of a failed configuration task are not known until something that depended on it fails at a later date. - -* If there is a problem with an Ignition config that causes the setup of a machine to fail, Ignition will not try to use the same config to set up another machine. For example, a failure could result from an Ignition config made up of a parent and child config that both want to create the same file. A failure in such a case would prevent that Ignition config from being used again to set up an other machines, until the problem is resolved. - -* If you have multiple Ignition config files, you get a union of that set of configs. Because Ignition is declarative, conflicts between the configs could cause Ignition to fail to set up the machine. The order of information in those files does not matter. Ignition will sort and implement each setting in ways that make the most sense. For example, if a file needs a directory several levels deep, if another file needs a directory along that path, the later file is created first. Ignition sorts and creates all files, directories, and links by depth. - -* Because Ignition can start with a completely empty hard disk, it can do something cloud-init cannot do: set up systems on bare metal from scratch (using features such as PXE boot). In the bare metal case, the Ignition config is injected into the boot partition so Ignition can find it and configure the system correctly. - - -[id="ignition-sequence_{context}"] -=== The Ignition sequence - -The Ignition process for an {op-system} machine in an {product-title} cluster involves the following steps: - -* The machine gets its Ignition config file. Master machines get their Ignition config files from the bootstrap machine, and worker machines get Ignition config files from a master. -* Ignition creates disk partitions, file systems, directories, and links on the machine. It supports RAID arrays but does not support LVM volumes. -* Ignition mounts the root of the permanent file system to the `/sysroot` directory in the initramfs and starts working in that `/sysroot` directory. -* Ignition configures all defined file systems and sets them up to mount appropriately at runtime. -* Ignition runs `systemd` temporary files to populate required files in the `/var` directory. -* Ignition runs the Ignition config files to set up users, systemd unit files, and other configuration files. -* Ignition unmounts all components in the permanent system that were mounted in the initramfs. -* Ignition starts up new machine’s init process which, in turn, starts up all other services on the machine that run during system boot. - -The machine is then ready to join the cluster and does not require a reboot. - -//// -After Ignition finishes its work on an individual machine, the kernel pivots to the installed system. The initial RAM disk is no longer used and the kernel goes on to run the init service to start up everything on the host from the installed disk. When the last machine under the bootstrap machine’s control is completed, and the services on those machines come up, the work of the bootstrap machine is over. -//// diff --git a/modules/rhcos-add-extensions.adoc b/modules/rhcos-add-extensions.adoc deleted file mode 100644 index 1cce4a4c062f..000000000000 --- a/modules/rhcos-add-extensions.adoc +++ /dev/null @@ -1,111 +0,0 @@ -// Module included in the following assemblies: -// -// * post_installation_configuration/machine-configuration-tasks.adoc - -[id="rhcos-add-extensions_{context}"] - -= Adding extensions to {op-system} -{op-system} is a minimal container-oriented RHEL operating system, designed to provide a common set of capabilities to {product-title} clusters across all platforms. While adding software packages to {op-system} systems is generally discouraged, the MCO provides an `extensions` feature you can use to add a minimal set of features to {op-system} nodes. - -Currently, the following extension is available: - -* **usbguard**: Adding the `usbguard` extension protects {op-system} systems from attacks from intrusive USB devices. See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/security_hardening/index#usbguard_protecting-systems-against-intrusive-usb-devices[USBGuard] for details. - -The following procedure describes how to use a machine config to add one or more extensions to your {op-system} nodes. - -.Prerequisites -* Have a running {product-title} cluster (version 4.6 or later). -* Log in to the cluster as a user with administrative privileges. - -.Procedure - -. Create a machine config for extensions: Create a YAML file (for example, `80-extensions.yaml`) that contains a `MachineConfig` `extensions` object. This example tells the cluster to add the `usbguard` extension. -+ -[source,terminal] ----- -$ cat << EOF > 80-extensions.yaml -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: 80-worker-extensions -spec: - config: - ignition: - version: 3.1.0 - extensions: - - usbguard -EOF ----- - -. Add the machine config to the cluster. Type the following to add the machine config to the cluster: -+ -[source,terminal] ----- -$ oc create -f 80-extensions.yaml ----- -+ -This sets all worker nodes to have rpm packages for `usbguard` installed. - -. Check that the extensions were applied: -+ -[source,terminal] ----- -$ oc get machineconfig 80-worker-extensions ----- -+ -.Example output -+ -[source,terminal] ----- -NAME GENERATEDBYCONTROLLER IGNITIONVERSION AGE -80-worker-extensions 3.1.0 57s ----- - -. Check that the new machine config is now applied and that the nodes are not in a degraded state. It may take a few minutes. The worker pool will show the updates in progress, as each machine successfully has the new machine config applied: -+ -[source,terminal] ----- -$ oc get machineconfigpool ----- -+ -.Example output -+ -[source,terminal] ----- -NAME CONFIG UPDATED UPDATING DEGRADED MACHINECOUNT READYMACHINECOUNT UPDATEDMACHINECOUNT DEGRADEDMACHINECOUNT AGE -master rendered-master-35 True False False 3 3 3 0 34m -worker rendered-worker-d8 False True False 3 1 1 0 34m ----- - -. Check the extensions. To check that the extension was applied, run: -+ -[source,terminal] ----- -$ oc get node | grep worker ----- -+ -.Example output -+ -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -ip-10-0-169-2.us-east-2.compute.internal Ready worker 102m v1.18.3 ----- -+ -[source,terminal] ----- -$ oc debug node/ip-10-0-169-2.us-east-2.compute.internal ----- -+ -.Example output -+ -[source,terminal] ----- -... -To use host binaries, run `chroot /host` -sh-4.4# chroot /host -sh-4.4# rpm -q usbguard -usbguard-0.7.4-4.el8.x86_64.rpm ----- diff --git a/modules/rhcos-analyse-detect.adoc b/modules/rhcos-analyse-detect.adoc new file mode 100644 index 000000000000..aee85f7f9074 --- /dev/null +++ b/modules/rhcos-analyse-detect.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scan-rhcos-node-host.adoc +:_mod-docs-content-type: CONCEPT +[id="rhcos-analyse-detect_{context}"] += Analysis and detection + +[role="_abstract"] +When you use {product-title-short} with {ocp}, {product-title-short} creates two coordinating containers for analysis and detection, the Compliance container and the Node-inventory container. +The Compliance container was already a part of earlier {product-title-short} versions. +However, the Node-inventory container is new with {product-title-short} 4.0 and works only with {ocp} cluster nodes. + +Upon start-up, the Compliance and Node-inventory containers begin the first inventory scan of {op-system-first} software components within five minutes. Next, the Node-inventory container scans the node's file system to identify installed RPM packages and report on {op-system} software components. Afterward, inventory scanning occurs at periodic intervals, typically every four hours. You can customize the default interval by configuring the ROX_NODE_SCANNING_INTERVAL environment variable for the Compliance container. diff --git a/modules/rhcos-enable-node-scan-scannerv4.adoc b/modules/rhcos-enable-node-scan-scannerv4.adoc new file mode 100644 index 000000000000..8c8c403c21d1 --- /dev/null +++ b/modules/rhcos-enable-node-scan-scannerv4.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scan-rhcos-node-host.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="rhcos-enable-node-scan-scannerv4_{context}"] += Enabling {op-system} node scanning with Scanner V4 + +[role="_abstract"] +If you use {ocp}, you can enable scanning of {op-system-first} nodes for vulnerabilities by using {rh-rhacs-first}. + +.Prerequisites +* For scanning {op-system} node hosts of the secured cluster, you must have installed the following software: +** Secured Cluster services on {ocp} {ocp-supported-version} or later +** {product-title-short} version 4.6 or later ++ +For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. For life cycle support information for {product-title-short}, see the link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. + +.Procedure + +[NOTE] +==== +Node scanning with Scanner V4 is enabled by default in a new installation of release 4.8 and later. These steps are only required if you are updating from an earlier version of {product-title-short} and Scanner V4 was not enabled. +==== + +. Ensure that Scanner V4 is deployed in the Central cluster: ++ +[source,terminal] +---- +$ kubectl -n stackrox get deployment scanner-v4-indexer scanner-v4-matcher scanner-v4-db<1> +---- +<1> For {ocp}, use `oc` instead of `kubectl`. +. In the Central pod, on the `central` container, set the `ROX_NODE_INDEX_ENABLED` and the `ROX_SCANNER_V4` variables to `true` by running the following command on the Central cluster: ++ +[source,terminal] +---- +$ kubectl -n stackrox set env deployment/central ROX_NODE_INDEX_ENABLED=true ROX_SCANNER_V4=true<1> +---- +<1> For {ocp}, use `oc` instead of `kubectl`. +. In the Sensor pod, on the `sensor` container, set the `ROX_NODE_INDEX_ENABLED` and the `ROX_SCANNER_V4` variables to `true` by running the following command on all secured clusters where you want to enable node scanning: ++ +[source,terminal] +---- +$ kubectl -n stackrox set env deployment/sensor ROX_NODE_INDEX_ENABLED=true ROX_SCANNER_V4=true<1> +---- +<1> For {ocp}, use `oc` instead of `kubectl`. +. In the Collector Daemonset, in the `compliance` container, set the `ROX_NODE_INDEX_ENABLED` and the `ROX_SCANNER_V4` variables to `true` by running the following command on all secured clusters where you want to enable node scanning: ++ +[source,terminal] +---- +$ kubectl -n stackrox set env daemonset/collector ROX_NODE_INDEX_ENABLED=true ROX_SCANNER_V4=true<1> +---- +<1> For {ocp}, use `oc` instead of `kubectl`. +. To verify that node scanning is working, examine the Central logs for the following message: ++ +[source,text] +---- +Scanned index report and found <number> components for node <node_name>. +---- ++ +where: + +<number>:: Specifies the number of discovered components. +<node_name>:: Specifies the name of the node. diff --git a/modules/rhcos-enable-node-scan.adoc b/modules/rhcos-enable-node-scan.adoc new file mode 100644 index 000000000000..51cdff4f4167 --- /dev/null +++ b/modules/rhcos-enable-node-scan.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scan-rhcos-node-host.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="rhcos-enable-node-scan_{context}"] += Enabling {op-system} node scanning with the StackRox Scanner + +[role="_abstract"] +If you use {ocp}, you can enable scanning of {op-system-first} nodes for vulnerabilities by using {rh-rhacs-first}. +[NOTE] +==== +Use Scanner V4 for full functionality when scanning nodes. For instructions on changing to Scanner V4 if you are using the StackRox scanner, see "Enabling Scanner V4". +==== + +.Prerequisites +* For scanning {op-system} node hosts of the secured cluster, you must have installed Secured Cluster services on {ocp} {ocp-supported-version} or later. For information about supported platforms and architecture, see the link:https://access.redhat.com/articles/7045053[{product-title} Support Matrix]. For life cycle support information for {product-title-short}, see the link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. +* This procedure describes how to enable node scanning for the first time. +If you are reconfiguring {product-title} to use the StackRox Scanner instead of Scanner V4, follow the procedure in "Restoring {op-system} node scanning with the StackRox Scanner". + +.Procedure +. Run one of the following commands to update the compliance container. +** For a default compliance container with metrics disabled, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox patch daemonset/collector -p '{"spec":{"template":{"spec":{"containers":[{"name":"compliance","env":[{"name":"ROX_METRICS_PORT","value":"disabled"},{"name":"ROX_NODE_SCANNING_ENDPOINT","value":"127.0.0.1:8444"},{"name":"ROX_NODE_SCANNING_INTERVAL","value":"4h"},{"name":"ROX_NODE_SCANNING_INTERVAL_DEVIATION","value":"24m"},{"name":"ROX_NODE_SCANNING_MAX_INITIAL_WAIT","value":"5m"},{"name":"ROX_RHCOS_NODE_SCANNING","value":"true"},{"name":"ROX_CALL_NODE_INVENTORY_ENABLED","value":"true"}]}]}}}}' +---- +** For a compliance container with Prometheus metrics enabled, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox patch daemonset/collector -p '{"spec":{"template":{"spec":{"containers":[{"name":"compliance","env":[{"name":"ROX_METRICS_PORT","value":":9091"},{"name":"ROX_NODE_SCANNING_ENDPOINT","value":"127.0.0.1:8444"},{"name":"ROX_NODE_SCANNING_INTERVAL","value":"4h"},{"name":"ROX_NODE_SCANNING_INTERVAL_DEVIATION","value":"24m"},{"name":"ROX_NODE_SCANNING_MAX_INITIAL_WAIT","value":"5m"},{"name":"ROX_RHCOS_NODE_SCANNING","value":"true"},{"name":"ROX_CALL_NODE_INVENTORY_ENABLED","value":"true"}]}]}}}}' +---- +. Update the Collector DaemonSet (DS) by taking the following steps: +.. Add new volume mounts to Collector DS by running the following command: ++ +[source,terminal] +---- +$ oc -n stackrox patch daemonset/collector -p '{"spec":{"template":{"spec":{"volumes":[{"name":"tmp-volume","emptyDir":{}},{"name":"cache-volume","emptyDir":{"sizeLimit":"200Mi"}}]}}}}' +---- +.. Add the new `NodeScanner` container by running the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox patch daemonset/collector -p '{"spec":{"template":{"spec":{"containers":[{"command":["/scanner","--nodeinventory","--config=",""],"env":[{"name":"ROX_NODE_NAME","valueFrom":{"fieldRef":{"apiVersion":"v1","fieldPath":"spec.nodeName"}}},{"name":"ROX_CLAIR_V4_SCANNING","value":"true"},{"name":"ROX_COMPLIANCE_OPERATOR_INTEGRATION","value":"true"},{"name":"ROX_CSV_EXPORT","value":"false"},{"name":"ROX_DECLARATIVE_CONFIGURATION","value":"false"},{"name":"ROX_INTEGRATIONS_AS_CONFIG","value":"false"},{"name":"ROX_NETPOL_FIELDS","value":"true"},{"name":"ROX_NETWORK_DETECTION_BASELINE_SIMULATION","value":"true"},{"name":"ROX_NETWORK_GRAPH_PATTERNFLY","value":"true"},{"name":"ROX_NODE_SCANNING_CACHE_TIME","value":"3h36m"},{"name":"ROX_NODE_SCANNING_INITIAL_BACKOFF","value":"30s"},{"name":"ROX_NODE_SCANNING_MAX_BACKOFF","value":"5m"},{"name":"ROX_PROCESSES_LISTENING_ON_PORT","value":"false"},{"name":"ROX_QUAY_ROBOT_ACCOUNTS","value":"true"},{"name":"ROX_ROXCTL_NETPOL_GENERATE","value":"true"},{"name":"ROX_SOURCED_AUTOGENERATED_INTEGRATIONS","value":"false"},{"name":"ROX_SYSLOG_EXTRA_FIELDS","value":"true"},{"name":"ROX_SYSTEM_HEALTH_PF","value":"false"},{"name":"ROX_VULN_MGMT_WORKLOAD_CVES","value":"false"}],"image":"registry.redhat.io/advanced-cluster-security/rhacs-scanner-slim-rhel8:{rhacs-version}","imagePullPolicy":"IfNotPresent","name":"node-inventory","ports":[{"containerPort":8444,"name":"grpc","protocol":"TCP"}],"volumeMounts":[{"mountPath":"/host","name":"host-root-ro","readOnly":true},{"mountPath":"/tmp/","name":"tmp-volume"},{"mountPath":"/cache","name":"cache-volume"}]}]}}}}' +---- diff --git a/modules/rhcos-environment-variables.adoc b/modules/rhcos-environment-variables.adoc new file mode 100644 index 000000000000..0a6ec25ca812 --- /dev/null +++ b/modules/rhcos-environment-variables.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scan-rhcos-node-host.adoc +:_mod-docs-content-type: REFERENCE +[id="rhcos-environment-variables_{context}"] += Related environment variables + +[role="_abstract"] +You can use the following environment variables to configure {op-system} node scanning on {product-title-short}. + +.Node-inventory configuration +[options="header", cols="1m,2"] +|==== +|Environment Variable|Description + +|ROX_NODE_SCANNING_CACHE_TIME +|The time after which a cached inventory is considered outdated. Defaults to 90% of `ROX_NODE_SCANNING_INTERVAL` that is `3h36m`. + +|ROX_NODE_SCANNING_INITIAL_BACKOFF +|The initial time in seconds a node scan will be delayed if a backoff file is found. The default value is `30s`. + +|ROX_NODE_SCANNING_MAX_BACKOFF +|The upper limit of backoff. The default value is 5m, being 50% of Kubernetes restart policy stability timer. + +|==== + +.Compliance configuration +[options="header", cols="1m,2"] +|==== +|Environment Variable|Description + +|ROX_NODE_INDEX_ENABLED +|Controls whether node indexing is enabled for this cluster. The default value is `true`. +|ROX_NODE_SCANNING_INTERVAL +|The base value of the interval duration between node scans. The default value is `4h`. + +|ROX_NODE_SCANNING_INTERVAL_DEVIATION +|The duration of node scans can differ from the base interval time. However, the maximum value is limited by the `ROX_NODE_SCANNING_INTERVAL`. + +|ROX_NODE_SCANNING_MAX_INITIAL_WAIT +|The maximum wait time before the first node scan, which is randomly generated. You can set this value to `0` to disable the initial node scanning wait time. The default value is `5m`. + +|==== \ No newline at end of file diff --git a/modules/rhcos-match-vulnerability.adoc b/modules/rhcos-match-vulnerability.adoc new file mode 100644 index 000000000000..2133d761e4cc --- /dev/null +++ b/modules/rhcos-match-vulnerability.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scan-rhcos-node-host.adoc +:_mod-docs-content-type: CONCEPT +[id="rhcos-match-vulnerability_{context}"] += Vulnerability matching on RHCOS nodes + +[role="_abstract"] +Central services, which include Central and Scanner, perform vulnerability matching with the results from {product-title-short} Scanner V4. + +When scanning {op-system} nodes, {product-title-short} releases after 4.0 no longer use the Kubernetes node metadata to find the kernel and container runtime versions. Instead, {product-title-short} uses the installed {op-system} RPMs to assess that information. diff --git a/modules/rhel-adding-more-nodes.adoc b/modules/rhel-adding-more-nodes.adoc deleted file mode 100644 index 97eb7472f488..000000000000 --- a/modules/rhel-adding-more-nodes.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_provisioned/more-rhel-compute.adoc - -[id="rhel-adding-more-nodes_{context}"] -= Adding more RHEL compute machines to your cluster - -You can add more compute machines that use Red Hat Enterprise Linux (RHEL) as the operating system to an {product-title} {product-version} cluster. - -.Prerequisites - -* Your {product-title} cluster already contains RHEL compute nodes. -* The `hosts` file that you used to add the first RHEL compute machines to your cluster is on the machine that you use the run the playbook. -* The machine that you run the playbook on must be able to access all of the RHEL hosts. You can use any method that your company allows, including a bastion with an SSH proxy or a VPN. -* The `kubeconfig` file for the cluster and the installation program that you used to install the cluster are on the machine that you use the run the playbook. -* You must prepare the RHEL hosts for installation. -* Configure a user on the machine that you run the playbook on that has SSH access to all of the RHEL hosts. -* If you use SSH key-based authentication, you must manage the key with an SSH agent. -* Install the OpenShift CLI (`oc`) on the machine that you run the playbook on. - - -.Procedure - -. Open the Ansible inventory file at `/<path>/inventory/hosts` that defines your compute machine hosts and required variables. - -. Rename the `[new_workers]` section of the file to `[workers]`. - -. Add a `[new_workers]` section to the file and define the fully-qualified domain names for each new host. The file resembles the following example: -+ ----- -[all:vars] -ansible_user=root -#ansible_become=True - -openshift_kubeconfig_path="~/.kube/config" - -[workers] -mycluster-rhel7-0.example.com -mycluster-rhel7-1.example.com - -[new_workers] -mycluster-rhel7-2.example.com -mycluster-rhel7-3.example.com ----- -+ -In this example, the `mycluster-rhel7-0.example.com` and `mycluster-rhel7-1.example.com` machines are in the cluster and you add the `mycluster-rhel7-2.example.com` and `mycluster-rhel7-3.example.com` machines. - -. Navigate to the Ansible playbook directory: -+ -[source,terminal] ----- -$ cd /usr/share/ansible/openshift-ansible ----- - -. Run the scaleup playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i /<path>/inventory/hosts playbooks/scaleup.yml <1> ----- -<1> For `<path>`, specify the path to the Ansible inventory file that you created. diff --git a/modules/rhel-adding-node.adoc b/modules/rhel-adding-node.adoc deleted file mode 100644 index 38feee2a3a63..000000000000 --- a/modules/rhel-adding-node.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_provisioned/adding-rhel-compute.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="rhel-adding-node_{context}"] -= Adding a RHEL compute machine to your cluster - -You can add compute machines that use Red Hat Enterprise Linux as the operating system to an {product-title} {product-version} cluster. - -.Prerequisites - -* You installed the required packages and performed the necessary configuration on the machine that you run the playbook on. -* You prepared the RHEL hosts for installation. - -.Procedure - -Perform the following steps on the machine that you prepared to run the playbook: - -. Create an Ansible inventory file that is named `/<path>/inventory/hosts` that defines your compute machine hosts and required variables: -+ ----- -[all:vars] -ansible_user=root <1> -#ansible_become=True <2> - -openshift_kubeconfig_path="~/.kube/config" <3> - -[new_workers] <4> -mycluster-rhel7-0.example.com -mycluster-rhel7-1.example.com ----- -<1> Specify the user name that runs the Ansible tasks on the remote compute machines. -<2> If you do not specify `root` for the `ansible_user`, you must set `ansible_become` to `True` and assign the user sudo permissions. -<3> Specify the path and file name of the `kubeconfig` file for your cluster. -<4> List each RHEL machine to add to your cluster. You must provide the fully-qualified domain name for each host. This name is the host name that the cluster uses to access the machine, so set the correct public or private name to access the machine. - -. Navigate to the Ansible playbook directory: -+ -[source,terminal] ----- -$ cd /usr/share/ansible/openshift-ansible ----- - -. Run the playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i /<path>/inventory/hosts playbooks/scaleup.yml <1> ----- -<1> For `<path>`, specify the path to the Ansible inventory file that you created. diff --git a/modules/rhel-ansible-parameters.adoc b/modules/rhel-ansible-parameters.adoc deleted file mode 100644 index c5bb466e0077..000000000000 --- a/modules/rhel-ansible-parameters.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_provisioned/adding-rhel-compute.adoc -// * machine_management/user_provisioned/more-rhel-compute.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="rhel-ansible-parameters_{context}"] -= Required parameters for the Ansible hosts file - -You must define the following parameters in the Ansible hosts file before you add Red Hat Enterprise Linux (RHEL) compute machines to your cluster. - -[cols="1,2,2",options="header"] -|=== -|Paramter |Description |Values - -|`ansible_user` -|The SSH user that allows SSH-based authentication without requiring a password. If you use SSH key-based authentication, then you must manage the key with an SSH agent. -|A user name on the system. The default value is `root`. - -|`ansible_become` -|If the values of `ansible_user` is not root, you must set `ansible_become` to `True`, and the user that you specify as the `ansible_user` must be configured for passwordless sudo access. -|`True`. If the value is not `True`, do not specify and define this parameter. - -|`openshift_kubeconfig_path` -|Specifies a path and file name to a local directory that contains the `kubeconfig` file for your cluster. -|The path and name of the configuration file. - -|=== diff --git a/modules/rhel-compute-about-hooks.adoc b/modules/rhel-compute-about-hooks.adoc deleted file mode 100644 index 6cf01aec693b..000000000000 --- a/modules/rhel-compute-about-hooks.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-cluster-rhel-compute.adoc - -[id="rhel-compute-about-hooks_{context}"] -= About Ansible hooks for upgrades - -When you update {product-title}, you can run custom tasks on your Red Hat -Enterprise Linux (RHEL) nodes during specific operations by using _hooks_. Hooks -allow you to provide files that define tasks to run before or after specific -update tasks. You can use hooks to validate or modify custom -infrastructure when you update the RHEL compute nodes in you {product-title} -cluster. - -Because when a hook fails, the operation fails, you must design hooks that are -idempotent, or can run multiple times and provide the same results. - -Hooks have the following important limitations: -- Hooks do not have a defined or versioned interface. They can use internal -`openshift-ansible` variables, but it is possible that the variables will be -modified or removed in future {product-title} releases. -- Hooks do not have error handling, so an error in a hook halts the update -process. If you get an error, you must address the problem and then start the -upgrade again. \ No newline at end of file diff --git a/modules/rhel-compute-available-hooks.adoc b/modules/rhel-compute-available-hooks.adoc deleted file mode 100644 index 167f31cdc87e..000000000000 --- a/modules/rhel-compute-available-hooks.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-cluster-rhel-compute.adoc - -[id="rhel-compute-available-hooks_{context}"] -= Available hooks for RHEL compute machines - -You can use the following hooks when you update the Red Hat Enterprise Linux (RHEL) -compute machines in your {product-title} cluster. - - -[cols="1,1",options="header"] -|=== -|Hook name |Description - - -|`openshift_node_pre_cordon_hook` -a|- Runs *before* each node is cordoned. -- This hook runs against *each node* in serial. -- If a task must run against a different host, the task must use -link:http://docs.ansible.com/ansible/playbooks_delegation.html#delegation[`delegate_to` or `local_action`]. - -|`openshift_node_pre_upgrade_hook` -a|- Runs *after* each node is cordoned but *before* it is updated. -- This hook runs against *each node* in serial. -- If a task must run against a different host, the task must use -link:http://docs.ansible.com/ansible/playbooks_delegation.html#delegation[`delegate_to` or `local_action`]. - -|`openshift_node_pre_uncordon_hook` -a|- Runs *after* each node is updated but *before* it is uncordoned. -- This hook runs against *each node* in serial. -- If a task must run against a different host, they task must use -link:http://docs.ansible.com/ansible/playbooks_delegation.html#delegation[`delegate_to` or `local_action`]. - -|`openshift_node_post_upgrade_hook` -a|- Runs *after* each node uncordoned. It is the *last* node update action. -- This hook runs against *each node* in serial. -- If a task must run against a different host, the task must use -link:http://docs.ansible.com/ansible/playbooks_delegation.html#delegation[`delegate_to` or `local_action`]. - -|=== - diff --git a/modules/rhel-compute-overview.adoc b/modules/rhel-compute-overview.adoc deleted file mode 100644 index fe8f53294061..000000000000 --- a/modules/rhel-compute-overview.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_provisioned/adding-rhel-compute.adoc -// * machine_management/user_provisioned/more-rhel-compute.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="rhel-compute-overview_{context}"] -= About adding RHEL compute nodes to a cluster - -In {product-title} {product-version}, you have the option of using Red Hat Enterprise Linux (RHEL) machines as compute machines, which are also known as worker machines, in your cluster if you use a user-provisioned infrastructure installation. You must use {op-system-first} machines for the control plane, or master, machines in your cluster. - -As with all installations that use user-provisioned infrastructure, if you choose to use RHEL compute machines in your cluster, you take responsibility for all operating system life cycle management and maintenance, including performing system updates, applying patches, and completing all other required tasks. - -[IMPORTANT] -==== -Because removing {product-title} from a machine in the cluster requires destroying the operating system, you must use dedicated hardware for any RHEL machines that you add to the cluster. -==== - -[IMPORTANT] -==== -Swap memory is disabled on all RHEL machines that you add to your {product-title} cluster. You cannot enable swap memory on these machines. -==== - -You must add any RHEL compute machines to the cluster after you initialize the control plane. diff --git a/modules/rhel-compute-requirements.adoc b/modules/rhel-compute-requirements.adoc deleted file mode 100644 index a928232b65f1..000000000000 --- a/modules/rhel-compute-requirements.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_provisioned/adding-rhel-compute.adoc -// * machine_management/user_provisioned/more-rhel-compute.adoc -// * post_installation_configuration/node-tasks.adoc - - -[id="rhel-compute-requirements_{context}"] -= System requirements for RHEL compute nodes - -The Red Hat Enterprise Linux (RHEL) compute machine hosts, which are also known as worker machine hosts, in your {product-title} environment must meet the following minimum hardware specifications and system-level requirements. - -* You must have an active {product-title} subscription on your Red Hat account. If you do not, contact your sales representative for more information. - -* Production environments must provide compute machines to support your expected workloads. As a cluster administrator, you must calculate the expected workload and add about 10 percent for overhead. For production environments, allocate enough resources so that a node host failure does not affect your maximum capacity. -* Each system must meet the following hardware requirements: -** Physical or virtual system, or an instance running on a public or private IaaS. -ifdef::openshift-origin[] -** Base OS: CentOS 7.4. -endif::[] -ifdef::openshift-enterprise,openshift-webscale[] -** Base OS: link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/installation_guide/index[RHEL 7.8 - 7.9] with "Minimal" installation option. -+ -[IMPORTANT] -==== -Only RHEL 7.8 - 7.9 is supported in {product-title} {product-version}. You must not upgrade your compute machines to RHEL 8. -==== -** If you deployed {product-title} in FIPS mode, you must enable FIPS on the RHEL machine before you boot it. See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/chap-federal_standards_and_regulations#sec-Enabling-FIPS-Mode[Enabling FIPS Mode] in the RHEL 7 documentation. -endif::[] -** NetworkManager 1.0 or later. -** 1 vCPU. -** Minimum 8 GB RAM. -** Minimum 15 GB hard disk space for the file system containing `/var/`. -** Minimum 1 GB hard disk space for the file system containing `/usr/local/bin/`. -** Minimum 1 GB hard disk space for the file system containing the system's temporary directory. The system’s temporary directory is determined according to the rules defined in the tempfile module in Python’s standard library. -* Each system must meet any additional requirements for your system provider. For example, if you installed your cluster on VMware vSphere, your disks must be configured according to its link:https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/index.html[storage guidelines] and the `disk.enableUUID=true` attribute must be set. - -* Each system must be able to access the cluster's API endpoints by using DNS-resolvable host names. Any network security access control that is in place must allow the system access to the cluster's API service endpoints. - -[id="csr-management-rhel_{context}"] -== Certificate signing requests management - -Because your cluster has limited access to automatic machine management when you use infrastructure that you provision, you must provide a mechanism for approving cluster certificate signing requests (CSRs) after installation. The `kube-controller-manager` only approves the kubelet client CSRs. The `machine-approver` cannot guarantee the validity of a serving certificate that is requested by using kubelet credentials because it cannot confirm that the correct machine issued the request. You must determine and implement a method of verifying the validity of the kubelet serving certificate requests and approving them. diff --git a/modules/rhel-compute-updating.adoc b/modules/rhel-compute-updating.adoc deleted file mode 100644 index d23373c408c9..000000000000 --- a/modules/rhel-compute-updating.adoc +++ /dev/null @@ -1,140 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-cluster-rhel-compute.adoc - -[id="rhel-compute-updating_{context}"] -= Updating RHEL compute machines in your cluster - -After you update your cluster, you must update the Red Hat Enterprise Linux (RHEL) -compute machines in your cluster. - -.Prerequisites - -* You updated your cluster. -+ -[IMPORTANT] -==== -Because the RHEL machines require assets that are generated by the cluster to -complete the update process, you must update the cluster before you update -the RHEL compute machines in it. -==== - -* You have access to the machine that you used to add the RHEL compute machines -cluster. You must have access to the `hosts` Ansible inventory file that defines -your RHEL machines and the `upgrade` playbook. - -.Procedure - -. Stop and disable firewalld on the host: -+ -[source,terminal] ----- -# systemctl disable --now firewalld.service ----- -+ -[NOTE] -==== -You must not enable firewalld later. If you do, you cannot access {product-title} logs on the worker. -==== - -. Enable the repositories that are required for {product-title} {product-version}: -.. On the machine that you run the Ansible playbooks, update the required repositories: -+ -[source,terminal] ----- -# subscription-manager repos --disable=rhel-7-server-ose-4.6-rpms \ - --enable=rhel-7-server-ansible-2.9-rpms \ - --enable=rhel-7-server-ose-4.7-rpms ----- - -.. On the machine that you run the Ansible playbooks, update the required packages, including `openshift-ansible`: -+ -[source,terminal] ----- -# yum update openshift-ansible openshift-clients ----- - -.. On each RHEL compute node, update the required repositories: -+ -[source,terminal] ----- -# subscription-manager repos --disable=rhel-7-server-ose-4.6-rpms \ - --enable=rhel-7-server-ose-4.7-rpms \ - --enable=rhel-7-fast-datapath-rpms \ - --enable=rhel-7-server-optional-rpms ----- - -. Update a RHEL worker machine: -.. Review the current node status to determine which RHEL worker to update: -+ -[source,terminal] ----- -# oc get node ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -mycluster-control-plane-0 Ready master 145m v1.20.0 -mycluster-control-plane-1 Ready master 145m v1.20.0 -mycluster-control-plane-2 Ready master 145m v1.20.0 -mycluster-rhel7-0 NotReady,SchedulingDisabled worker 98m v1.14.6+97c81d00e -mycluster-rhel7-1 Ready worker 98m v1.14.6+97c81d00e -mycluster-rhel7-2 Ready worker 98m v1.14.6+97c81d00e -mycluster-rhel7-3 Ready worker 98m v1.14.6+97c81d00e ----- -+ -Note which machine has the `NotReady,SchedulingDisabled` status. - -.. Review your Ansible inventory file at `/<path>/inventory/hosts` -and update its contents so that only the machine with the `NotReady,SchedulingDisabled` status is listed in the `[workers]` section, as shown in the following example: -+ ----- -[all:vars] -ansible_user=root -#ansible_become=True - -openshift_kubeconfig_path="~/.kube/config" - -[workers] -mycluster-rhel7-0.example.com ----- - -.. Change to the `openshift-ansible` directory: -+ -[source,terminal] ----- -$ cd /usr/share/ansible/openshift-ansible ----- - -.. Run the `upgrade` playbook: -+ -[source,terminal] ----- -$ ansible-playbook -i /<path>/inventory/hosts playbooks/upgrade.yml <1> ----- -<1> For `<path>`, specify the path to the Ansible inventory file -that you created. - -. Follow the process in the previous step to update each RHEL worker machine in your cluster. - -. After you update all of the workers, confirm that all of your cluster nodes have updated to the new version: -+ -[source,terminal] ----- -# oc get node ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS ROLES AGE VERSION -mycluster-control-plane-0 Ready master 145m v1.20.0 -mycluster-control-plane-1 Ready master 145m v1.20.0 -mycluster-control-plane-2 Ready master 145m v1.20.0 -mycluster-rhel7-0 NotReady,SchedulingDisabled worker 98m v1.20.0 -mycluster-rhel7-1 Ready worker 98m v1.20.0 -mycluster-rhel7-2 Ready worker 98m v1.20.0 -mycluster-rhel7-3 Ready worker 98m v1.20.0 ----- diff --git a/modules/rhel-compute-using-hooks.adoc b/modules/rhel-compute-using-hooks.adoc deleted file mode 100644 index 6bb183615250..000000000000 --- a/modules/rhel-compute-using-hooks.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-cluster-rhel-compute.adoc - -[id="rhel-compute-using-hooks_{context}"] -= Configuring the Ansible inventory file to use hooks - -You define the hooks to use when you update the Red Hat Enterprise Linux (RHEL) -compute machines, which are also known as worker machines, in the `hosts` inventory file under the `all:vars` -section. - -.Prerequisites - -* You have access to the machine that you used to add the RHEL compute machines -cluster. You must have access to the `hosts` Ansible inventory file that defines -your RHEL machines. - - -.Procedure - -. After you design the hook, create a YAML file that defines the Ansible tasks -for it. This file must be a set of tasks and cannot be a playbook, as shown in -the following example: -+ -[source.yaml] ----- ---- -# Trivial example forcing an operator to acknowledge the start of an upgrade -# file=/home/user/openshift-ansible/hooks/pre_compute.yml - -- name: note the start of a compute machine update - debug: - msg: "Compute machine upgrade of {{ inventory_hostname }} is about to start" - -- name: require the user agree to start an upgrade - pause: - prompt: "Press Enter to start the compute machine update" ----- - -. Modify the `hosts` Ansible inventory file to specify the hook files. The -hook files are specified as parameter values in the `[all:vars]` section, -as shown: -+ -.Example hook definitions in an inventory file -[source] ----- -[all:vars] -openshift_node_pre_upgrade_hook=/home/user/openshift-ansible/hooks/pre_node.yml -openshift_node_post_upgrade_hook=/home/user/openshift-ansible/hooks/post_node.yml ----- -+ -To avoid ambiguity in the paths to the hook, use absolute paths instead of a -relative paths in their definitions. diff --git a/modules/rhel-preparing-node.adoc b/modules/rhel-preparing-node.adoc deleted file mode 100644 index 4269203f6627..000000000000 --- a/modules/rhel-preparing-node.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_provisioned/adding-rhel-compute.adoc -// * machine_management/user_provisioned/more-rhel-compute.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="rhel-preparing-node_{context}"] -= Preparing a RHEL compute node - -Before you add a Red Hat Enterprise Linux (RHEL) machine to your {product-title} cluster, you must register each host with Red Hat Subscription Manager (RHSM), attach an active {product-title} subscription, and enable the required repositories. - -. On each host, register with RHSM: -+ -[source,terminal] ----- -# subscription-manager register --username=<user_name> --password=<password> ----- - -. Pull the latest subscription data from RHSM: -+ -[source,terminal] ----- -# subscription-manager refresh ----- - -. List the available subscriptions: -+ -[source,terminal] ----- -# subscription-manager list --available --matches '*OpenShift*' ----- - -. In the output for the previous command, find the pool ID for an {product-title} subscription and attach it: -+ -[source,terminal] ----- -# subscription-manager attach --pool=<pool_id> ----- - -. Disable all yum repositories: -.. Disable all the enabled RHSM repositories: -+ -[source,terminal] ----- -# subscription-manager repos --disable="*" ----- - -.. List the remaining yum repositories and note their names under `repo id`, if any: -+ -[source,terminal] ----- -# yum repolist ----- - -.. Use `yum-config-manager` to disable the remaining yum repositories: -+ -[source,terminal] ----- -# yum-config-manager --disable <repo_id> ----- -+ -Alternatively, disable all repositories: -+ -[source,terminal] ----- -# yum-config-manager --disable \* ----- -+ -Note that this might take a few minutes if you have a large number of available repositories - -. Enable only the repositories required by {product-title} {product-version}: -+ -[source,terminal] ----- -# subscription-manager repos \ - --enable="rhel-7-server-rpms" \ - --enable="rhel-7-fast-datapath-rpms" \ - --enable="rhel-7-server-extras-rpms" \ - --enable="rhel-7-server-optional-rpms" \ - --enable="rhel-7-server-ose-4.7-rpms" ----- - -. Stop and disable firewalld on the host: -+ -[source,terminal] ----- -# systemctl disable --now firewalld.service ----- -+ -[NOTE] -==== -You must not enable firewalld later. If you do, you cannot access {product-title} logs on the worker. -==== diff --git a/modules/rhel-preparing-playbook-machine.adoc b/modules/rhel-preparing-playbook-machine.adoc deleted file mode 100644 index caaf8db071c7..000000000000 --- a/modules/rhel-preparing-playbook-machine.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_provisioned/adding-rhel-compute.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="rhel-preparing-playbook-machine_{context}"] -= Preparing the machine to run the playbook - -Before you can add compute machines that use Red Hat Enterprise Linux as the operating system to an {product-title} {product-version} cluster, you must prepare a machine to run the playbook from. This machine is not part of the cluster but must be able to access it. - -.Prerequisites - -* Install the OpenShift CLI (`oc`) on the machine that you run the playbook on. -* Log in as a user with `cluster-admin` permission. - -.Procedure - -. Ensure that the `kubeconfig` file for the cluster and the installation program that you used to install the cluster are on the machine. One way to accomplish this is to use the same machine that you used to install the cluster. - -. Configure the machine to access all of the RHEL hosts that you plan to use as compute machines. You can use any method that your company allows, including a bastion with an SSH proxy or a VPN. - -. Configure a user on the machine that you run the playbook on that has SSH access to all of the RHEL hosts. -+ -[IMPORTANT] -==== -If you use SSH key-based authentication, you must manage the key with an SSH agent. -==== - -. If you have not already done so, register the machine with RHSM and attach a pool with an `OpenShift` subscription to it: -.. Register the machine with RHSM: -+ -[source,terminal] ----- -# subscription-manager register --username=<user_name> --password=<password> ----- - -.. Pull the latest subscription data from RHSM: -+ -[source,terminal] ----- -# subscription-manager refresh ----- - -.. List the available subscriptions: -+ -[source,terminal] ----- -# subscription-manager list --available --matches '*OpenShift*' ----- - -.. In the output for the previous command, find the pool ID for an {product-title} subscription and attach it: -+ -[source,terminal] ----- -# subscription-manager attach --pool=<pool_id> ----- - -. Enable the repositories required by {product-title} {product-version}: -+ -[source,terminal] ----- -# subscription-manager repos \ - --enable="rhel-7-server-rpms" \ - --enable="rhel-7-server-extras-rpms" \ - --enable="rhel-7-server-ansible-2.9-rpms" \ - --enable="rhel-7-server-ose-4.7-rpms" ----- - -. Install the required packages, including `openshift-ansible`: -+ -[source,terminal] ----- -# yum install openshift-ansible openshift-clients jq ----- -+ -The `openshift-ansible` package provides installation program utilities and pulls in other packages that you require to add a RHEL compute node to your cluster, such as Ansible, playbooks, and related configuration files. The `openshift-clients` provides the `oc` CLI, and the `jq` package improves the display of JSON output on your command line. diff --git a/modules/rhel-removing-rhcos.adoc b/modules/rhel-removing-rhcos.adoc deleted file mode 100644 index e66577444ea4..000000000000 --- a/modules/rhel-removing-rhcos.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * machine_management/user_provisioned/adding-rhel-compute.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="rhel-removing-rhcos_{context}"] -= Optional: Removing RHCOS compute machines from a cluster - -After you add the Red Hat Enterprise Linux (RHEL) compute machines to your cluster, you can optionally remove the {op-system-first} compute machines to free up resources. - -.Prerequisites - -* You have added RHEL compute machines to your cluster. - -.Procedure - -. View the list of machines and record the node names of the {op-system} compute machines: -+ -[source,terminal] ----- -$ oc get nodes -o wide ----- - -. For each {op-system} compute machine, delete the node: -.. Mark the node as unschedulable by running the `oc adm cordon` command: -+ -[source,terminal] ----- -$ oc adm cordon <node_name> <1> ----- -<1> Specify the node name of one of the {op-system} compute machines. - -.. Drain all the pods from the node: -+ -[source,terminal] ----- -$ oc adm drain <node_name> --force --delete-local-data --ignore-daemonsets <1> ----- -<1> Specify the node name of the {op-system} compute machine that you isolated. - -.. Delete the node: -+ -[source,terminal] ----- -$ oc delete nodes <node_name> <1> ----- -<1> Specify the node name of the {op-system} compute machine that you drained. - -. Review the list of compute machines to ensure that only the RHEL nodes remain: -+ -[source,terminal] ----- -$ oc get nodes -o wide ----- - -. Remove the {op-system} machines from the load balancer for your cluster's compute machines. You can delete the virtual machines or reimage the physical hardware for the {op-system} compute machines. diff --git a/modules/risk-deployment-details-container-configuration.adoc b/modules/risk-deployment-details-container-configuration.adoc new file mode 100644 index 000000000000..4e1193db44e4 --- /dev/null +++ b/modules/risk-deployment-details-container-configuration.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="risk-deployment-details-container-configuration_{context}"] += Container configuration section + +The container configuration section shows details about the following: + +* *Image Name*: The name of the image that is deployed. +* *Resources* + ** *CPU Request (cores)*: The number of CPUs requested by the container. + ** *CPU Limit (cores)*: The maximum number of CPUs the container can use. + ** *Memory Request (MB)*: The memory size requested by the container. + ** *Memory Limit (MB)*: The maximum amount of memory the container can use without being killed. +* *Mounts* + ** *Name*: The name of the mount. + ** *Source*: The path from where the data for the mount comes. + ** *Destination*: The path to which the data for the mount goes. + ** *Type*: The type of the mount. +* *Secrets*: The names of Kubernetes secrets used in the deployment, and basic details for secret values that are X.509 certificates. diff --git a/modules/risk-deployment-details-overview.adoc b/modules/risk-deployment-details-overview.adoc new file mode 100644 index 000000000000..c07521027706 --- /dev/null +++ b/modules/risk-deployment-details-overview.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="risk-deployment-details-overview_{context}"] += Overview section + +The *Overview* section shows details about the following: + +* *Deployment ID*: An alphanumeric identifier for the deployment. +* *Namespace*: The Kubernetes or {ocp} namespace in which the deployment exists. +* *Updated*: A timestamp with date for when the deployment was updated. +* *Deployment Type*: The type of deployment, for example, `Deployment` or `DaemonSet`. +* *Replicas*: The number of pods deployed for this deployment. +* *Labels*: The key-value labels attached to the Kubernetes or {ocp} application. +* *Cluster*: The name of the cluster where the deployment is running. +* *Annotations*: The Kubernetes annotations for the deployment. +* *Service Account*: Represents an identity for processes that run in a pod. +When a process is authenticated through a service account, it can contact the Kubernetes API server and access cluster resources. +If a pod does not have an assigned service account, it gets the default service account. diff --git a/modules/risk-deployment-details-security-context.adoc b/modules/risk-deployment-details-security-context.adoc new file mode 100644 index 000000000000..349bd66bbe67 --- /dev/null +++ b/modules/risk-deployment-details-security-context.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="risk-deployment-details-security-context_{context}"] += Security context section + +The *Security Context* section shows details about the following: + +* *Privileged*: Lists `true` if the container is privileged. diff --git a/modules/risk-indicators-tab.adoc b/modules/risk-indicators-tab.adoc new file mode 100644 index 000000000000..d8a3511ab6ac --- /dev/null +++ b/modules/risk-indicators-tab.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="risk-indicators-tab_{context}"] += Risk Indicators tab + +[role="_abstract"] +The *Risk Indicators* tab of the *Risk Details* panel explains the discovered risks. + +The *Risk Indicators* tab includes the following sections: + +* *Policy Violations*: The names of the policies that are violated for the selected deployment. +* *Suspicious Process Executions*: Suspicious processes, arguments, and container names that the process ran in. +* *Image Vulnerabilities*: Images including total CVEs with their CVSS scores. +* *Service Configurations*: Aspects of the configurations that are often problematic, such as read-write (RW) capability, whether capabilities are dropped, and the presence of privileged containers. +* *Service Reachability*: Container ports exposed inside or outside the cluster. +* *Components Useful for Attackers*: Discovered software tools that are often used by attackers. +* *Number of Components in Image*: The number of packages found in each image. +* *Image Freshness*: Image names and age, for example, `285 days old`. +* *RBAC Configuration*: The level of permissions granted to the deployment in Kubernetes role-based access control (RBAC). + +[NOTE] +==== +Not all sections are visible in the *Risk Indicators* tab. +{product-title} displays only relevant sections that affect the selected deployment. +==== diff --git a/modules/risk-view-details.adoc b/modules/risk-view-details.adoc new file mode 100644 index 000000000000..003cb2b875ec --- /dev/null +++ b/modules/risk-view-details.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="risk-view-details_{context}"] += Risk view + +[role="_abstract"] +The *Risk* view lists all deployments from all clusters, sorted by a multi-factor risk metric based on policy violations, image contents, deployment configuration, and other similar factors. +Deployments at the top of the list present the most risk. + +The *Risk* view shows list of deployments with following attributes for each row: + +* *Name*: The name of the deployment. +* *Created*: The creation time of the deployment. +* *Cluster*: The name of the cluster where the deployment is running. +* *Namespace*: The namespace in which the deployment exists. +* *Priority*: A priority ranking based on severity and risk metrics. + +In the *Risk* view, you can: + +* Select a column heading to sort the violations in ascending or descending order. +* Use the filter bar to filter violations. +//See the link:/docs/search/#use-local-page-filtering[Use local page filtering] topic for more information. +* Create a new policy based on the filtered criteria. + +To view more details about the risks for a deployment, select a deployment in the *Risk* view. diff --git a/modules/rollback-central-forced.adoc b/modules/rollback-central-forced.adoc new file mode 100644 index 000000000000..ec5893c93d7c --- /dev/null +++ b/modules/rollback-central-forced.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-44.adoc +:_mod-docs-content-type: PROCEDURE +[id="rollback-central-forced_{context}"] += Rolling back Central forcefully + +[role="_abstract"] +You can use forced rollback to roll back to an earlier version of Central (after the Central service starts). + +[IMPORTANT] +==== +Using forced rollback to switch back to a previous version might result in loss of data and functionality. +==== + +.Prerequisites + +* **Enough disk space**: Before you can perform a rollback, you must have free disk space available on your persistent storage. {product-title} uses disk space to keep a copy of databases during the upgrade. If the disk space is not enough to store a copy and the upgrade fails, you cannot perform a roll back to an earlier version. +* **Internal database rollback (4.8 or earlier)**: If you are rolling back from {product-title-short} 4.8 to an earlier version and use the internal database (`central-db`), you must first restore the database from a PostgreSQL 13 backup. + +** To restore the database, add the `RESTORE_BACKUP=true` and `FORCE_OLD_BINARIES=true` environment variables to the `central-db` and `init-db` containers of the `central-db` component. +** For details on injecting environment variables, see "Injecting an environment variable into the Central deployment". + +.Procedure + +* Run the following commands to perform a forced rollback: +** To forcefully rollback to the previously installed version: ++ +[source,terminal] +---- +$ oc -n stackrox rollout undo deploy/central <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +** To forcefully rollback to a specific version: +. Edit the `ConfigMap` that belongs to Central: ++ +[source,terminal] +---- +$ oc -n stackrox edit configmap/central-config <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +. Update the value of the `maintenance.forceRollbackVersion` key: ++ +[source,yaml] +---- +data: + central-config.yaml: | + maintenance: + safeMode: false + compaction: + enabled: true + bucketFillFraction: .5 + freeFractionThreshold: 0.75 + forceRollbackVersion: <x.x.x.x> <1> + ... +---- +<1> Specify the version that you want to roll back to. +. Update the Central image version: ++ +[source,terminal] +---- +$ oc -n stackrox \ <1> + set image deploy/central central=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:<x.x.x.x> <2> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +<2> Specify the version that you want to roll back to. It must be the same version that you specified for the `maintenance.forceRollbackVersion` key in the `central-config` config map. diff --git a/modules/rollback-central-normal.adoc b/modules/rollback-central-normal.adoc new file mode 100644 index 000000000000..969957bc3601 --- /dev/null +++ b/modules/rollback-central-normal.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-44.adoc +:_mod-docs-content-type: PROCEDURE +[id="rollback-central-normal_{context}"] += Rolling back Central normally + +[role="_abstract"] +You can roll back to a previous version of Central if upgrading {product-title} fails. + +.Prerequisites + +* **Enough disk space**: Before you can perform a rollback, you must have free disk space available on your persistent storage. {product-title} uses disk space to keep a copy of databases during the upgrade. If the disk space is not enough to store a copy and the upgrade fails, you cannot perform a roll back to an earlier version. +* **Internal database rollback (4.8 or earlier)**: If you are rolling back from {product-title-short} 4.8 to an earlier version and use the internal database (`central-db`), you must first restore the database from a PostgreSQL 13 backup. + +** To restore the database, add the `RESTORE_BACKUP=true` and `FORCE_OLD_BINARIES=true` environment variables to the `central-db` and `init-db` containers of the `central-db` component. +** For details on injecting environment variables, see "Injecting an environment variable into the Central deployment". + +.Procedure + +* Run the following command to roll back to a previous version when an upgrade fails (before the Central service starts): ++ +[source,terminal] +---- +$ oc -n stackrox rollout undo deploy/central <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. diff --git a/modules/rollback-helm-upgrade.adoc b/modules/rollback-helm-upgrade.adoc new file mode 100644 index 000000000000..b829d47672a3 --- /dev/null +++ b/modules/rollback-helm-upgrade.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-helm.adoc +:_mod-docs-content-type: PROCEDURE +[id="rollback-helm-upgrade_{context}"] += Rolling back a Helm upgrade + +[role="_abstract"] +You can roll back to an earlier version of Central if the upgrade to a new version is unsuccessful. + +.Procedure + +. Run the following `helm upgrade` command: ++ +[source,terminal] +---- +$ helm upgrade -n stackrox \ + stackrox-central-services rhacs/central-services \ + --version <previous_rhacs_74_version> \ <1> + --set central.db.enabled=false +---- +<1> Replace `<previous_rhacs_74_version>` with the previously installed {product-title-short} version. +. Delete the `central-db` persistent volume claim (PVC): ++ +[source,terminal] +---- +$ oc -n stackrox delete pvc central-db <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. diff --git a/modules/rollback-operator-upgrades-cli.adoc b/modules/rollback-operator-upgrades-cli.adoc new file mode 100644 index 000000000000..f829221f68ec --- /dev/null +++ b/modules/rollback-operator-upgrades-cli.adoc @@ -0,0 +1,72 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-operator.adoc +// * cloud_service/upgrade-cloudsvc-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="rollback-operator-upgrades_{context}"] += Rolling back an Operator upgrade by using the CLI + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:cloud-svc: +endif::[] + +You can roll back the Operator version by using command-line interface (CLI) commands. + +.Procedure + +. Delete the {olm-first} subscription and cluster service version (CSV): ++ +[IMPORTANT] +==== +If you use Kubernetes, enter `kubectl` instead of `oc`. +==== + +.. To delete the {olm} subscription, run the following command: ++ +[source,terminal] +---- +$ oc -n rhacs-operator delete subscription rhacs-operator +---- ++ +.Example output ++ +[source,terminal] +---- +subscription.operators.coreos.com "rhacs-operator" deleted +---- + +.. To delete the CSV, run the following command: ++ +[source,terminal] +---- +$ oc -n rhacs-operator delete csv -l operators.coreos.com/rhacs-operator.rhacs-operator +---- ++ +.Example output ++ +[source,terminal] +---- +clusterserviceversion.operators.coreos.com "rhacs-operator.v4.8.4" deleted +---- + +ifndef::cloud-svc[] + +. Install the previous version of the {product-title-short} Operator: +.. In the OpenShift web console, click *OperatorHub*. +.. Search for *Advanced Cluster Security for Kubernetes*. +.. Select and install the previous version of the Operator. ++ +[NOTE] +==== +Installing the previous Operator version rolls back {product-title-short} to the same version as the Operator. +==== +endif::cloud-svc[] + +ifdef::cloud-svc[] +. Install the latest version of the Operator on the rolled back channel. +endif::cloud-svc[] + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:!cloud-svc: +endif::[] \ No newline at end of file diff --git a/modules/rollback-operator-upgrades-console.adoc b/modules/rollback-operator-upgrades-console.adoc new file mode 100644 index 000000000000..50a09f3d176d --- /dev/null +++ b/modules/rollback-operator-upgrades-console.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-operator.adoc +// * cloud_service/upgrade-cloudsvc-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="rollback-operator-upgrades-console_{context}"] += Rolling back an Operator upgrade by using the web console + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:cloud-svc: +endif::[] + +You can roll back the Operator version by using the {ocp} web console. + +.Prerequisites + +* You have access to an {ocp} cluster web console using an account with `cluster-admin` permissions. + +.Procedure + +. In the OpenShift web console, click *Operators* -> *Installed Operators*. +. From the list of projects, select *rhacs-operator*. +. Locate the *Advanced Cluster Security for Kubernetes* Operator: +.. Click the overflow menu {kebab} -> *Uninstall Operator*. ++ +The uninstall Operator dialog is displayed. +.. Ensure that the *Delete all operand instances for this operator* checkbox is clear to avoid uninstallation of {rh-rhacs-first}. +.. Click *Uninstall*. + +ifndef::cloud-svc[] +. Install the previous version of {product-title-short} Operator: +.. In the OpenShift web console, click *OperatorHub*. +.. Search for *Advanced Cluster Security for Kubernetes*. +.. Select and install the previous version of the Operator. ++ +[NOTE] +==== +Installing the previous Operator version rolls back {product-title-short} to the same version as the Operator. +==== +endif::cloud-svc[] + +ifdef::cloud-svc[] +. Install the latest version of the Operator on the rolled back channel. +endif::cloud-svc[] + +ifeval::["{context}" == "upgrade-cloudsvc-operator"] +:!cloud-svc: +endif::[] \ No newline at end of file diff --git a/modules/router-performance-optimizations.adoc b/modules/router-performance-optimizations.adoc deleted file mode 100644 index 729561c08a6f..000000000000 --- a/modules/router-performance-optimizations.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// * scalability_and_performance/routing-optimization.adoc -// * post_installation_configuration/network-configuration.adoc - -[id="router-performance-optimizations_{context}"] -= Ingress Controller (router) performance optimizations - -{product-title} no longer supports modifying Ingress Controller deployments by setting environment variables such as `ROUTER_THREADS`, `ROUTER_DEFAULT_TUNNEL_TIMEOUT`, `ROUTER_DEFAULT_CLIENT_TIMEOUT`, `ROUTER_DEFAULT_SERVER_TIMEOUT`, and `RELOAD_INTERVAL`. - -You can modify the Ingress Controller deployment, but if the Ingress Operator is enabled, the configuration is overwritten. diff --git a/modules/roxctl-central-backup.adoc b/modules/roxctl-central-backup.adoc new file mode 100644 index 000000000000..3c3bfd9a2a83 --- /dev/null +++ b/modules/roxctl-central-backup.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-backup_{context}"] += roxctl central backup + +Create a backup of the {product-title-short} database and certificates. + +.Usage +[source,terminal] +---- +$ roxctl central backup [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--certs-only` +|Specify to only back up the certificates. When using an external database, this option is used to generate a backup bundle with certificates. The default value is `false`. + +|`--output string` +a|Specify where you want to save the backup. The behavior depends on the specified path: + +* If the path is a file path, the backup is written to the file and overwrites it if it already exists. The directory must exist. +* If the path is a directory, the backup is saved in this directory under the file name that the server specifies. +* If this argument is omitted, the backup is saved in the current working directory under the file name that the server specifies. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests. It represents the maximum duration of a request. The default value is `1h0m0s`. +|=== diff --git a/modules/roxctl-central-cert.adoc b/modules/roxctl-central-cert.adoc new file mode 100644 index 000000000000..8f2c8b8b9d00 --- /dev/null +++ b/modules/roxctl-central-cert.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-cert_{context}"] += roxctl central cert + +Download the certificate chain for the Central service. + +.Usage +[source,terminal] +---- +$ roxctl central cert [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--output string` +|Specify the file name to which you want to save the PEM certificate. Use `-` to produce output to the standard output stream (`stdout`). The default value is `-`. + +|`--retry-timeout duration` +|Specify the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-crs-generate.adoc b/modules/roxctl-central-crs-generate.adoc new file mode 100644 index 000000000000..2c325d359776 --- /dev/null +++ b/modules/roxctl-central-crs-generate.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-crs-generate_{context}"] += roxctl central crs generate + +Generate a cluster registration secret (CRS) that allows communication between Central and secured clusters for the initial setup. + +.Usage +[source,terminal] +---- +$ roxctl central crs generate <crs name> [flags] +---- + +For available flags, see "roxctl central command options inherited from the parent command". \ No newline at end of file diff --git a/modules/roxctl-central-crs-list.adoc b/modules/roxctl-central-crs-list.adoc new file mode 100644 index 000000000000..993a417b560a --- /dev/null +++ b/modules/roxctl-central-crs-list.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-crs-list_{context}"] += roxctl central crs list + +Generate a list of previously generated cluster registration secrets that allow communication between Central and secured clusters for the initial setup. + +.Usage +[source,terminal] +---- +$ roxctl central crs list [flags] +---- + +For available flags, see "roxctl central command options inherited from the parent command". \ No newline at end of file diff --git a/modules/roxctl-central-crs-revoke.adoc b/modules/roxctl-central-crs-revoke.adoc new file mode 100644 index 000000000000..f2dbb0c35033 --- /dev/null +++ b/modules/roxctl-central-crs-revoke.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-crs-revoke_{context}"] += roxctl central crs revoke + +Revoke a cluster registration secret (CRS) that allows communication between Central and secured clusters for the initial setup. + +.Usage +[source,terminal] +---- +$ roxctl central crs revoke <CRS unique identifier or name> [flags] +---- + +For available flags, see "roxctl central command options inherited from the parent command". \ No newline at end of file diff --git a/modules/roxctl-central-crs.adoc b/modules/roxctl-central-crs.adoc new file mode 100644 index 000000000000..212a76166a21 --- /dev/null +++ b/modules/roxctl-central-crs.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-crs_{context}"] += roxctl central crs + +Manage cluster registration secrets that allow communication between Central and secured clusters for the initial setup. + +:FeatureName: Cluster registration secrets +include::snippets/technology-preview.adoc[] + +.Usage +[source,terminal] +---- +$ roxctl central crs [command] [flags] +---- + +For available flags, see "roxctl central command options inherited from the parent command". \ No newline at end of file diff --git a/modules/roxctl-central-db-generate-k8s-hostpath.adoc b/modules/roxctl-central-db-generate-k8s-hostpath.adoc new file mode 100644 index 000000000000..19a0127df829 --- /dev/null +++ b/modules/roxctl-central-db-generate-k8s-hostpath.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-generate-k8s-hostpath_{context}"] += roxctl central db generate k8s hostpath + +Generate a Kubernetes YAML manifest for a database deployment with a hostpath volume type in Central. + +.Usage +[source,terminal] +---- +$ roxctl central db generate k8s hostpath [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--hostpath string` +|Specify the path on the host. The default value is `/var/lib/stackrox-central-db`. + +|`--node-selector-key string` +|Specify the node selector key. Valid values include `kubernetes.io` and `hostname`. + +|`--node-selector-value string` +|Specify the node selector value. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db-generate-k8s-pvc.adoc b/modules/roxctl-central-db-generate-k8s-pvc.adoc new file mode 100644 index 000000000000..ce1be830f6a9 --- /dev/null +++ b/modules/roxctl-central-db-generate-k8s-pvc.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-generate-k8s-pvc_{context}"] += roxctl central db generate k8s pvc + +Generate Kubernetes YAML files for persistent volume claims (PVCs) in Central. + +.Usage +[source,terminal] +---- +$ roxctl central db generate k8s pvc [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--name string` +|Specify the external volume name for the Central database. The default value is `central-db`. + +|`--size uint32` +|Specify the external volume size in gigabytes for the Central database. The default value is `100`. + +|`--storage-class string` +|Specify the storage class name for the Central database. This is optional if you have a default storage class configured. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db-generate-k8s.adoc b/modules/roxctl-central-db-generate-k8s.adoc new file mode 100644 index 000000000000..c87e0098e717 --- /dev/null +++ b/modules/roxctl-central-db-generate-k8s.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-generate-k8s_{context}"] += roxctl central db generate k8s + +Generate Kubernetes YAML files for deploying Central's database components. + +.Usage +[source,terminal] +---- +$ roxctl central db generate k8s [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--central-db-image string` +|Specify the Central database image that you want to use. If not specified, a default value corresponding to the `--image-defaults` is used. + +|`--image-defaults string` +|Specify the default settings for container images. It controls the repositories from which the images are downloaded, the image names and the format of the tags. The default value is `development_build`. + +|`--output-dir output directory` +|Specify the directory to which you want to save the deployment bundle. The default value is `central-db-bundle`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db-generate-openshift-hostpath.adoc b/modules/roxctl-central-db-generate-openshift-hostpath.adoc new file mode 100644 index 000000000000..d2740ed2b640 --- /dev/null +++ b/modules/roxctl-central-db-generate-openshift-hostpath.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-generate-openshift-hostpath_{context}"] += roxctl central db generate openshift hostpath + +Add a hostpath external volume to the Central database. + +.Usage +[source,terminal] +---- +$ roxctl central db generate openshift hostpath [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--hostpath string` +|Specify the path on the host. The default value is `/var/lib/stackrox-central-db`. + +|`--node-selector-key string` +|Specify the node selector key. Valid values include `kubernetes.io` and `hostname`. + +|`--node-selector-value string` +|Specify the node selector value. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db-generate-openshift-pvc.adoc b/modules/roxctl-central-db-generate-openshift-pvc.adoc new file mode 100644 index 000000000000..541b286ad14f --- /dev/null +++ b/modules/roxctl-central-db-generate-openshift-pvc.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-generate-openshift-pvc_{context}"] += roxctl central db generate openshift pvc + +Generate an OpenShift YAML manifest for a database deployment with a persistent volume claim (PVC) in Central. + +.Usage +[source,terminal] +---- +$ roxctl central db generate openshift pvc [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|--name string +|Specify the external volume name for the Central database. The default value is `central-db`. + +|--size uint32 +|Specify the external volume size in gigabytes for the Central database. The default value is `100`. + +|--storage-class string +|Specify the storage class name for the Central database. This is optional if you have a default storage class configured. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db-generate-openshift.adoc b/modules/roxctl-central-db-generate-openshift.adoc new file mode 100644 index 000000000000..4bfff20494fe --- /dev/null +++ b/modules/roxctl-central-db-generate-openshift.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-generate-openshift_{context}"] += roxctl central db generate openshift + +Generate an OpenShift YAML manifest for deploying a Central database instance on a {osp} cluster. + +.Usage +[source,terminal] +---- +$ roxctl central db generate openshift [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--central-db-image string` +|Specify the Central database image that you want to use. If not specified, a default value corresponding to the `--image-defaults` is used. + +|`--image-defaults string` +|Specify the default settings for container images. It controls the repositories from which the images are downloaded, the image names and the format of the tags. The default value is `development_build`. + +|`--openshift-version int` +|Specify the {osp} major version 3 or 4 for the deployment. The default value is `3`. + +|`--output-dir output-directory` +|Specify the directory to which you want to save the deployment bundle. The default value is `central-db-bundle`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db-generate.adoc b/modules/roxctl-central-db-generate.adoc new file mode 100644 index 000000000000..4081e1f788b1 --- /dev/null +++ b/modules/roxctl-central-db-generate.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-generate_{context}"] += roxctl central db generate + +Generate a Central database bundle. + +.Usage +[source,terminal] +---- +$ roxctl central db generate [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--debug` +|If set to `true`, templates are read from the local file system. The default value is `false`. + +|`--debug-path string` +|Specify the path to the Helm templates in your local file system. For more details, run the `roxctl central db generate` command. + +|`--enable-pod-security-policies` +|If set to `true`, `PodSecurityPolicy` resources are created. The default value is `true`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db-restore-cancel.adoc b/modules/roxctl-central-db-restore-cancel.adoc new file mode 100644 index 000000000000..3d05d922926e --- /dev/null +++ b/modules/roxctl-central-db-restore-cancel.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-restore-cancel_{context}"] += roxctl central db restore cancel + +Cancel the ongoing Central database restore process. + +.Usage +[source,terminal] +---- +$ roxctl central db restore cancel [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`f`, `--force` +|If set to `true`, proceed with the cancellation without confirmation. The default value is `false`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db-restore-status.adoc b/modules/roxctl-central-db-restore-status.adoc new file mode 100644 index 000000000000..4dba3f1eae62 --- /dev/null +++ b/modules/roxctl-central-db-restore-status.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-restore-status_{context}"] += roxctl central db restore status + +Display information about the ongoing database restore process. + +.Usage +[source,terminal] +---- +$ roxctl central db restore status [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-central-db-restore.adoc b/modules/roxctl-central-db-restore.adoc new file mode 100644 index 000000000000..2b6091eecc07 --- /dev/null +++ b/modules/roxctl-central-db-restore.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db-restore_{context}"] += roxctl central db restore + +Restore the {product-title-short} database from a previous backup. + +.Usage +[source,terminal] +---- +$ roxctl central db restore <file> [flags] <1> +---- + +<1> For `<file>`, specify the database backup file that you want to restore. + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-f`, `--force` +|If set to `true`, the restoration is performed without confirmation. The default value is `false`. + +|`--interrupt` +|If set to `true`, it interrupts the running restore process to allow it to continue. The default value is `false`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-db.adoc b/modules/roxctl-central-db.adoc new file mode 100644 index 000000000000..7f3a44511a0c --- /dev/null +++ b/modules/roxctl-central-db.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-db_{context}"] += roxctl central db + +Control the database operations. + +.Usage +[source,terminal] +---- +$ roxctl central db [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `1h0m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-debug-authz-trace.adoc b/modules/roxctl-central-debug-authz-trace.adoc new file mode 100644 index 000000000000..d94bd0b67a22 --- /dev/null +++ b/modules/roxctl-central-debug-authz-trace.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-debug-authz-trace_{context}"] += roxctl central debug authz-trace + +Enable or disable authorization tracing in Central for debugging purposes. + +.Usage +[source,terminal] +---- +$ roxctl central debug authz-trace [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `20m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-debug-db-stats-reset.adoc b/modules/roxctl-central-debug-db-stats-reset.adoc new file mode 100644 index 000000000000..8546245c1f7e --- /dev/null +++ b/modules/roxctl-central-debug-db-stats-reset.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-debug-db-stats-reset_{context}"] += roxctl central debug db stats reset + +Reset the statistics of the Central database. + +.Usage +[source,terminal] +---- +$ roxctl central debug db stats reset [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-central-debug-db-stats.adoc b/modules/roxctl-central-debug-db-stats.adoc new file mode 100644 index 000000000000..6085984cc8ea --- /dev/null +++ b/modules/roxctl-central-debug-db-stats.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-debug-db-stats_{context}"] += roxctl central debug db stats + +Control the statistics of the Central database. + +.Usage +[source,terminal] +---- +$ roxctl central debug db stats [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-central-debug-db.adoc b/modules/roxctl-central-debug-db.adoc new file mode 100644 index 000000000000..2d3399f684c6 --- /dev/null +++ b/modules/roxctl-central-debug-db.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-debug-db_{context}"] += roxctl central debug db + +Control the debugging of the database. + +.Usage +[source,terminal] +---- +$ roxctl central debug db [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-debug-download-diagnostics.adoc b/modules/roxctl-central-debug-download-diagnostics.adoc new file mode 100644 index 000000000000..ccbaaa4af8da --- /dev/null +++ b/modules/roxctl-central-debug-download-diagnostics.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-debug-download-diagnostics_{context}"] += roxctl central debug download-diagnostics + +Download a bundle containing a snapshot of diagnostic information about the platform. + +.Usage +[source,terminal] +---- +$ roxctl central debug download-diagnostics [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--clusters strings` +|Specify a comma-separated list of the Sensor clusters from which you want to collect the logs. + +|`--output-dir string` +|Specify the output directory in which you want to save the diagnostic bundle. + +|`--since string` +|Specify the timestamp from which you want to collect the logs from the Sensor clusters. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests, which specifies the maximum duration of a request. The default value is `5m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-debug-dump.adoc b/modules/roxctl-central-debug-dump.adoc new file mode 100644 index 000000000000..4c3e0318947e --- /dev/null +++ b/modules/roxctl-central-debug-dump.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-debug-dump_{context}"] += roxctl central debug dump + +Download a bundle containing the debug information for Central. + +.Usage +[source,terminal] +---- +$ roxctl central debug dump [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--logs` +|If set to `true`, logs are included in the Central dump. The default value is `false`. + +|`--output-dir string` +|Specify the output directory for the bundle content. The default value is an automatically generated directory name within the current directory. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests, which is the maximum duration of a request. The default value is `5m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-debug-log.adoc b/modules/roxctl-central-debug-log.adoc new file mode 100644 index 000000000000..b746491dfc6d --- /dev/null +++ b/modules/roxctl-central-debug-log.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-debug-log_{context}"] += roxctl central debug log + +Retrieve the current log level. + +.Usage +[source,terminal] +---- +$ roxctl central debug log [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-l`, `--level string` +|Specify the log level to which you want to set the modules. Valid values include `Debug`, `Info`, `Warn`, `Error`, `Panic`, and `Fatal`. + +|`-m`, `--modules strings` +|Specify the modules to which you want to apply the command. + +|`--retry-timeout duration` +|Specify the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests, which is the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-debug.adoc b/modules/roxctl-central-debug.adoc new file mode 100644 index 000000000000..f2b892873281 --- /dev/null +++ b/modules/roxctl-central-debug.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-debug_{context}"] += roxctl central debug + +Debug the Central service. + +.Usage +[source,terminal] +---- +$ roxctl central debug [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-central-generate-interactive.adoc b/modules/roxctl-central-generate-interactive.adoc new file mode 100644 index 000000000000..7b63d7ab1d09 --- /dev/null +++ b/modules/roxctl-central-generate-interactive.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-generate-interactive_{context}"] += roxctl central generate interactive + +Generate interactive resources in Central. + +.Usage +[source,terminal] +---- +$ roxctl central generate interactive [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-central-generate-k8s-hostpath.adoc b/modules/roxctl-central-generate-k8s-hostpath.adoc new file mode 100644 index 000000000000..fa7c0378eec1 --- /dev/null +++ b/modules/roxctl-central-generate-k8s-hostpath.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-generate-k8s-hostpath_{context}"] += roxctl central generate k8s hostpath + +Generate a Kubernetes YAML manifest for deploying a Central instance by using the hostpath volume type. + +.Usage +[source,terminal] +---- +$ roxctl central generate k8s hostpath [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--db-hostpath string` +|Specify the path on the host for the Central database. The default value is `/var/lib/stackrox-central`. + +|`--db-node-selector-key string` +|Specify the node selector key for the Central database. Valid values include `kubernetes.io` and `hostname`. + +|`--db-node-selector-value string` +|Specify the node selector value for the Central database. + +|=== \ No newline at end of file diff --git a/modules/roxctl-central-generate-k8s-pvc.adoc b/modules/roxctl-central-generate-k8s-pvc.adoc new file mode 100644 index 000000000000..599cff33c9c5 --- /dev/null +++ b/modules/roxctl-central-generate-k8s-pvc.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-generate-k8s-pvc_{context}"] += roxctl central generate k8s pvc + +Generate Kubernetes YAML files for persistent volume claims (PVCs) in Central. + +.Usage +[source,terminal] +---- +$ roxctl central generate k8s pvc [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--db-name string` +|Specify the external volume name for the Central database. The default value is `central-db`. + +|`--db-size uint32` +|Specify the external volume size in gigabytes for the Central database. The default value is `100`. + +|`--db-storage-class string` +|Specify the storage class name for the Central database. This is optional if you have a default storage class configured. + +|=== \ No newline at end of file diff --git a/modules/roxctl-central-generate-k8s.adoc b/modules/roxctl-central-generate-k8s.adoc new file mode 100644 index 000000000000..f7229f6e7153 --- /dev/null +++ b/modules/roxctl-central-generate-k8s.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-generate-k8s_{context}"] += roxctl central generate k8s + +Generate the required YAML configuration files to deploy Central into a Kubernetes cluster. + +.Usage +[source,terminal] +---- +$ roxctl central generate k8s [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--central-db-image string` +|Specify the Central database image you want to use. If not specified, a default value corresponding to the `--image-defaults` is used. + +|`--declarative-config-config-maps strings` +|Specify a list of configuration maps that you want to add as declarative configuration mounts in Central. + +|`--declarative-config-secrets strings` +|Specify a list of secrets that you want to add as declarative configuration mounts in Central. + +|`--enable-telemetry` +|Specify whether you want to enable telemetry. The default value is `false`. + +|`--image-defaults string` +|Specify the default settings for container images. The specified settings control the repositories from which the images are downloaded, the image names and the format of the tags. The default value is `development_build`. + +|`--istio-support version` +|Generate deployment files that support the specified Istio version. Valid values include `1.0`, `1.1`, `1.2`, `1.3`, `1.4`, `1.5`, `1.6`, and `1.7`. + +|`--lb-type load balancer type` +|Specify the method in which you want to suspend Central. Valid values include `lb`, `np` and `none`. The default value is `none`. + +|`-i`, `--main-image string` +|Specify the main image that you want to use. If not specified, a default value corresponding to the `--image-defaults` is used. + +|`--offline` +|Specify whether you want to run {product-title-short} in offline mode, avoiding a connection to the Internet. The default value is `false`. + +|`--output-dir output directory` +|Specify the directory to which you want to save the deployment bundle. The default value is `central-bundle`. + +|`--output-format output format` +|Specify the deployment tool that you want to use. Valid values include `kubectl`, `helm`, and `helm-values`. The default value is `kubectl`. + +|`--scanner-db-image string` +|Specify the Scanner database image that you want to use. If not specified, a default value corresponding to the `--image-defaults` is used. + +|`--scanner-image string` +|Specify the Scanner image that you want to use. If not specified, a default value corresponding to the `--image-defaults" is used. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-generate-openshift-hostpath.adoc b/modules/roxctl-central-generate-openshift-hostpath.adoc new file mode 100644 index 000000000000..35370a7fe6b6 --- /dev/null +++ b/modules/roxctl-central-generate-openshift-hostpath.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-generate-openshift-hostpath_{context}"] += roxctl central generate openshift hostpath + +Add a hostpath external volume to the deployment definition in {osp}. + +.Usage +[source,terminal] +---- +$ roxctl central generate openshift hostpath [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--db-hostpath string` +|Specify the path on the host for the Central database. The default value is `/var/lib/stackrox-central`. + +|`--db-node-selector-key string` +|Specify the node selector key. Valid values include `kubernetes.io` and `hostname` for the Central database. + +|`--db-node-selector-value string` +|Specify the node selector value for the Central database. + +|=== \ No newline at end of file diff --git a/modules/roxctl-central-generate-openshift-pvc.adoc b/modules/roxctl-central-generate-openshift-pvc.adoc new file mode 100644 index 000000000000..3b84401e0644 --- /dev/null +++ b/modules/roxctl-central-generate-openshift-pvc.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-generate-openshift-pvc_{context}"] += roxctl central generate openshift pvc + +Generate a OpenShift YAML manifest for deploying a persistent volume claim (PVC) in Central. + +.Usage +[source,terminal] +---- +$ roxctl central generate openshift pvc [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--db-name string` +|Specify the external volume name for the Central database. The default value is `central-db`. + +|`--db-size uint32` +|Specify the external volume size in gigabytes for the Central database. The default value is `100`. + +|`--db-storage-class string` +|Specify the storage class name for the Central database. This is optional if you have a default storage class configured. + +|=== \ No newline at end of file diff --git a/modules/roxctl-central-generate-openshift.adoc b/modules/roxctl-central-generate-openshift.adoc new file mode 100644 index 000000000000..0f666314c202 --- /dev/null +++ b/modules/roxctl-central-generate-openshift.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-generate-openshift_{context}"] += roxctl central generate openshift + +Generate the required YAML configuration files to deploy Central in a {osp} cluster. + +.Usage +[source,terminal] +---- +$ roxctl central generate openshift [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--central-db-image string` +|Specify the Central database image that you want to use. If not specified, a default value is created corresponding to the `--image-defaults`. + +|`--declarative-config-config-maps strings` +|Specify a list of configuration maps that you want to add as declarative configuration mounts in Central. + +|`--declarative-config-secrets strings` +|Specify a list of secrets that you want to add as declarative configuration mounts in Central. + +|`--enable-telemetry` +|Specify whether you want to enable telemetry. The default value is `false`. + +|`--image-defaults string` +|Specify the default settings for container images. It controls the repositories from which the images are downloaded, the image names and the format of the tags. The default value is `development_build`. + +|`--istio-support version` +|Generate deployment files that support the specified Istio version. Valid values include `1.0`, `1.1`, `1.2`, `1.3`, `1.4`, `1.5`, `1.6`, and `1.7`. + +|`--lb-type load balancer type` +|Specify the method of exposing Central. Valid values include `route`, `lb`, `np` and `none`. The default value is `none`. + +|`-i`, `--main-image string` +|Specify the main image that you want to use. If not specified, a default value corresponding to `--image-defaults` is used. + +|`--offline` +|Specify whether you want to run {product-title-short} in offline mode, avoiding a connection to the Internet. The default value is `false`. + +|`--openshift-monitoring false\|true\|auto[=true]` +|Specify integration with {osp} 4 monitoring. The default value is `auto`. + +|`--openshift-version int` +|Specify the {osp} major version 3 or 4 for the deployment. + +|`--output-dir output directory` +|Specify the directory to which you want to save the deployment bundle. The default value is `central-bundle`. + +|`--output-format output format` +|Specify the deployment tool that you want to use. Valid values include `kubectl`, `helm` and `helm-values`. The default value is `kubectl`. + +|`--scanner-db-image string` +|Specify the Scanner database image that you want to use. If not specified, a default value corresponding to the `--image-defaults` is used. + +|`--scanner-image string` +|Specify the Scanner image that you want to use. If not specified, a default value corresponding to `--image-defaults` is used. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-generate.adoc b/modules/roxctl-central-generate.adoc new file mode 100644 index 000000000000..41c3dde10025 --- /dev/null +++ b/modules/roxctl-central-generate.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-generate_{context}"] += roxctl central generate + +Generate the required YAML configuration files that contain the orchestrator objects to deploy Central. + +.Usage +[source,terminal] +---- +$ roxctl central generate [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--backup-bundle string` +|Specify the path to the backup bundle from which you want to restore the keys and certificates. + +|`--debug` +|If set to `true`, templates are read from the local file system. The default value is `false`. + +|`--debug-path string` +|Specify the path to Helm templates on your local file system. For more details, run the `roxctl central generate --help` command. + +|`--default-tls-certfile` +|Specify the PEM certificate bundle file that you want to use as the default. + +|`--default-tls-keyfile` +|Specify the PEM private key file that you want to use as the default. + +|`--enable-pod-security-policies` +|If set to `true`, `PodSecurityPolicy` resources are created. The default value is `true`. + +|`-p`, `--password string` +|Specify the administrator password. The default value is automatically generated. + +|`--plaintext-endpoints string` +|Specify the ports or endpoints you want to use for unencrypted exposure as a comma-separated list. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-init-bundles-fetch-ca.adoc b/modules/roxctl-central-init-bundles-fetch-ca.adoc new file mode 100644 index 000000000000..d52ffed4c0cc --- /dev/null +++ b/modules/roxctl-central-init-bundles-fetch-ca.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-init-bundles-fetch-ca_{context}"] += roxctl central init-bundles fetch-ca + +Fetch the certificate authority (CA) bundle from Central. + +.Usage +[source,terminal] +---- +$ roxctl central init-bundles fetch-ca [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--output string` +|Specify the file that you want to use for storing the CA configuration. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-init-bundles-generate.adoc b/modules/roxctl-central-init-bundles-generate.adoc new file mode 100644 index 000000000000..dca61a3e8388 --- /dev/null +++ b/modules/roxctl-central-init-bundles-generate.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-init-bundles-generate_{context}"] += roxctl central init-bundles generate + +Generate a new cluster initialization bundle. + +.Usage +[source,terminal] +---- +$ roxctl central init-bundles generate <init_bundle_name> [flags] <1> +---- + +<1> For `<init_bundle_name>`, specify the name for the initialization bundle you want to generate. + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--output string` +|Specify the file you want to use for storing the newly generated initialization bundle in the Helm configuration form. Use `-` to produce output to the standard output stream (`stdout`). + +|`--output-secrets string` +|Specify the file that you want to use for storing the newly generated initialization bundle in Kubernetes secret form. Use `-` to produce output to the standard output stream (`stdout`). +|=== \ No newline at end of file diff --git a/modules/roxctl-central-init-bundles-list.adoc b/modules/roxctl-central-init-bundles-list.adoc new file mode 100644 index 000000000000..a0fcfa09a9c8 --- /dev/null +++ b/modules/roxctl-central-init-bundles-list.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-init-bundles-list_{context}"] += roxctl central init-bundles list + +List the available initialization bundles in Central. + +.Usage +[source,terminal] +---- +$ roxctl central init-bundles list [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-central-init-bundles-revoke.adoc b/modules/roxctl-central-init-bundles-revoke.adoc new file mode 100644 index 000000000000..a3fa4170798e --- /dev/null +++ b/modules/roxctl-central-init-bundles-revoke.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-init-bundles-revoke_{context}"] += roxctl central init-bundles revoke + +Revoke one or more cluster initialization bundles in Central. + +.Usage +[source,terminal] +---- +$ roxctl central init-bundles revoke <init_bundle_ID or name> [<init_bundle_ID or name> ...] [flags] <1> +---- + +<1> For `<init_bundle_ID or name>`, specify the ID or the name of the initialization bundle that you want to revoke. You can provide multiple IDs or names separated by using spaces. \ No newline at end of file diff --git a/modules/roxctl-central-init-bundles.adoc b/modules/roxctl-central-init-bundles.adoc new file mode 100644 index 000000000000..83f293fdead5 --- /dev/null +++ b/modules/roxctl-central-init-bundles.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-init-bundles_{context}"] += roxctl central init-bundles + +Initialize bundles in Central. + +.Usage +[source,terminal] +---- +$ roxctl central init-bundles [flag] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--retry-timeout duration` +|Specify the timeout after which API requests are retried. A value of `0s` means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-login.adoc b/modules/roxctl-central-login.adoc new file mode 100644 index 000000000000..b366f0b76f06 --- /dev/null +++ b/modules/roxctl-central-login.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-login_{context}"] += roxctl central login + +Login to the Central instance to obtain a token. + +.Usage +[source,terminal] +---- +$ roxctl central login [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `5m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-userpki-create.adoc b/modules/roxctl-central-userpki-create.adoc new file mode 100644 index 000000000000..58dc41d6afa2 --- /dev/null +++ b/modules/roxctl-central-userpki-create.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-userpki-create_{context}"] += roxctl central userpki create + +Create a new user certificate authentication provider. + +.Usage +[source,terminal] +---- +$ roxctl central userpki create name [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-c`, `--cert strings` +|Specify the PEM files of the root CA certificates. You can specify several certificate files. + +|`--retry-timeout duration` +|Specify the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-r`, `--role string` +|Specify the minimum access role for users of this provider. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-userpki-delete.adoc b/modules/roxctl-central-userpki-delete.adoc new file mode 100644 index 000000000000..afeb7820633e --- /dev/null +++ b/modules/roxctl-central-userpki-delete.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-userpki-delete_{context}"] += roxctl central userpki delete + +Delete a user certificate authentication provider. + +.Usage +[source,terminal] +---- +$ roxctl central userpki delete id|name [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-f`, `--force` +|If set to `true`, proceed with the deletion without confirmation. The default value is `false`. + +|`--retry-timeout duration` +|Specify the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-userpki-list.adoc b/modules/roxctl-central-userpki-list.adoc new file mode 100644 index 000000000000..48c7c7851aa6 --- /dev/null +++ b/modules/roxctl-central-userpki-list.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-userpki-list_{context}"] += roxctl central userpki list + +Display all the user certificate authentication providers. + +.Usage +[source,terminal] +---- +$ roxctl central userpki list [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-j`, `--json` +|Enable the JSON output. The default value is `false`. + +|`--retry-timeout duration` +|Specify the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-central-userpki.adoc b/modules/roxctl-central-userpki.adoc new file mode 100644 index 000000000000..72018583f595 --- /dev/null +++ b/modules/roxctl-central-userpki.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-userpki_{context}"] += roxctl central userpki + +Manage the user certificate authorization providers. + +.Usage +[source,terminal] +---- +$ roxctl central userpki [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-central-whoami.adoc b/modules/roxctl-central-whoami.adoc new file mode 100644 index 000000000000..1c84a1fd1ce2 --- /dev/null +++ b/modules/roxctl-central-whoami.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-central.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-central-whoami_{context}"] += roxctl central whoami + +Display information about the current user and their authentication method. + +.Usage +[source,terminal] +---- +$ roxctl central whoami [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--retry-timeout duration` +|Specify the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Specify the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-cluster-delete.adoc b/modules/roxctl-cluster-delete.adoc new file mode 100644 index 000000000000..7a91076e3f4e --- /dev/null +++ b/modules/roxctl-cluster-delete.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-cluster.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-cluster-delete_{context}"] += roxctl cluster delete + +Remove Sensor from Central. + +.Usage +[source,terminal] +---- +$ roxctl cluster delete [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--name string` +|Specify the cluster name to delete. +|=== \ No newline at end of file diff --git a/modules/roxctl-collector-support-packages-upload.adoc b/modules/roxctl-collector-support-packages-upload.adoc new file mode 100644 index 000000000000..ab8c519ad07d --- /dev/null +++ b/modules/roxctl-collector-support-packages-upload.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-collector.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-collector-support-packages-upload_{context}"] += roxctl collector support-packages upload + +Upload files from a Collector support package to Central. + +.Usage +[source,terminal] +---- +$ roxctl collector support-packages upload [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--overwrite` +|Specify whether you want to overwrite existing but different files. The default value is `false`. + +|`--retry-timeout duration` +|Set the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Set the timeout for API requests. This option represents the maximum duration of a request. The default value is `1m0s`. +|=== diff --git a/modules/roxctl-collector-support-packages.adoc b/modules/roxctl-collector-support-packages.adoc new file mode 100644 index 000000000000..285c83dcb938 --- /dev/null +++ b/modules/roxctl-collector-support-packages.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-collector.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-collector-support-packages_{context}"] += roxctl collector support-packages + +Upload support packages for Collector. + +[NOTE] +==== +Support packages are deprecated and have no effect on secured clusters running version +4.5 or later. Support package uploads only affect secured clusters on version 4.4 and +earlier. +==== + +.Usage +[source,terminal] +---- +$ roxctl collector support-packages [flags] +---- diff --git a/modules/roxctl-command-options.adoc b/modules/roxctl-command-options.adoc new file mode 100644 index 000000000000..c257da38e520 --- /dev/null +++ b/modules/roxctl-command-options.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-command-options_{context}"] += roxctl command options + +The `roxctl` command supports the following options: + +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--ca string` +|Specify a custom CA certificate file path for secure connections. Alternatively, you can specify the file path by using the `ROX_CA_CERT_FILE` environment variable. + +|`--direct-grpc` +|Set `--direct-grpc` for improved connection performance. Alternatively, by setting the `ROX_DIRECT_GRPC_CLIENT` environment variable to `true`, you can enable direct gRPC . The default value is `false`. + +|`-e`, `--endpoint string` +|Set the endpoint for the service to contact. Alternatively, you can set the endpoint by using the `ROX_ENDPOINT` environment variable. The default value is `localhost:8443`. + +|`--force-http1` +|Force the use of HTTP/1 for all connections. Alternatively, by setting the `ROX_CLIENT_FORCE_HTTP1` environment variable to `true`, you can force the use of HTTP/1. The default value is `false`. + +|`--insecure` +|Enable insecure connection options. Alternatively, by setting the `ROX_INSECURE_CLIENT` environment variable to `true`, you can enable insecure connection options. The default value is `false`. + +|`--insecure-skip-tls-verify` +a|Skip the TLS certificate validation. Alternatively, by setting the `ROX_INSECURE_CLIENT_SKIP_TLS_VERIFY` environment variable to `true`, you can skip the TLS certificate validation. The default value is `false`. + +|`--no-color` +|Disable the color output. Alternatively, by setting the `ROX_NO_COLOR environment variable` to `true`, you can disable the color output. The default value is `false`. + +|`-p`, `--password string` +|Specify the password for basic authentication. Alternatively, you can set the password by using the `ROX_ADMIN_PASSWORD` environment variable. + +|`--plaintext` +|Use an unencrypted connection. Alternatively, by setting the `ROX_PLAINTEXT` environment variable to `true`, you can enable an unencrypted connection. The default value is `false`. + +|`-s`, `--server-name string` +|Set the TLS server name to use for SNI. Alternatively, you can set the server name by using the `ROX_SERVER_NAME` environment variable. + +|`--token-file string` +|Use the API token provided in the specified file for authentication. Alternatively, you can set the token by using the `ROX_API_TOKEN` environment variable. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-access-scope.adoc b/modules/roxctl-declarative-config-create-access-scope.adoc new file mode 100644 index 000000000000..668e31121bae --- /dev/null +++ b/modules/roxctl-declarative-config-create-access-scope.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-access-scope_{context}"] += roxctl declarative-config create access-scope + +Create a declarative configuration for an access scope. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create access-scope [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--cluster-label-selector requirement` +|Specify the criteria for creating a label selector based on the cluster's labels. The key-value pairs represent requirements, and you can use this flag multiple times to create a combination of requirements. The default value is `[ [ ] ]`. For more details, run the `roxctl declarative-config create access-scope --help` command. + +|`--description string` +|Set a description for the access scope. + +|`--included included-object` +|Specify a list of clusters and their namespaces that you want to include in the access scope. The default value is `[null]`. + +|`--name string` +|Specify the name of the access scope. + +|`--namespace-label-selector requirement` +|Specify the criteria for creating a label selector based on the namespace's labels. Similar to the cluster-label-selector, you can use this flag multiple times for the combination of requirements. For more details, run the `roxctl declarative-config create access-scope --help` command. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-auth-provider-iap.adoc b/modules/roxctl-declarative-config-create-auth-provider-iap.adoc new file mode 100644 index 000000000000..6f38e7ba073e --- /dev/null +++ b/modules/roxctl-declarative-config-create-auth-provider-iap.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-auth-provider-iap_{context}"] += roxctl declarative-config create auth-provider iap + +Create a declarative configuration for an authentication provider with the identity-aware proxy (IAP) identifier. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create auth-provider iap [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--audience string` +|Specify the target group that you want to validate. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-auth-provider-oidc.adoc b/modules/roxctl-declarative-config-create-auth-provider-oidc.adoc new file mode 100644 index 000000000000..511fba5bc6e5 --- /dev/null +++ b/modules/roxctl-declarative-config-create-auth-provider-oidc.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-auth-provider-oidc_{context}"] += roxctl declarative-config create auth-provider oidc + +Create a declarative configuration for an OpenID Connect (OIDC) authentication provider. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create auth-provider oidc [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--claim-mappings stringToString` +|Specify a list of non-standard claims from the identity provider (IdP) token that you want to include in the authentication provider's rules. The default value is `[]`. + +|`--client-id string` +|Specify the client ID of the OIDC client. + +|`--client-secret string` +|Specify the client secret of the OIDC client. + +|`--disable-offline-access` +|Disable the request for the offline_access from the OIDC IdP. You need to use this option if the OIDC IdP limits the number of sessions with the `offline_access` scope. The default value is `false`. + +|`--issuer string` +|Specify the issuer of the OIDC client. + +|`--mode string` +|Specify the callback mode that you want to use. Valid values include `auto`, `post`, `query` and `fragment`. The default value is `auto`. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-auth-provider-openshift-auth.adoc b/modules/roxctl-declarative-config-create-auth-provider-openshift-auth.adoc new file mode 100644 index 000000000000..41a35653719b --- /dev/null +++ b/modules/roxctl-declarative-config-create-auth-provider-openshift-auth.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-auth-provider-openshift-auth_{context}"] += roxctl declarative-config create auth-provider openshift-auth + +Create a declarative configuration for an {ocp} OAuth authentication provider. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create auth-provider openshift-auth [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-auth-provider-saml.adoc b/modules/roxctl-declarative-config-create-auth-provider-saml.adoc new file mode 100644 index 000000000000..7f0bbf1cb239 --- /dev/null +++ b/modules/roxctl-declarative-config-create-auth-provider-saml.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-auth-provider-saml_{context}"] += roxctl declarative-config create auth-provider saml + +Create a declarative configuration for a SAML authentication provider. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create auth-provider saml [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--idp-cert string` +|Specify the file containing the SAML identity provider (IdP) certificate in PEM format. + +|`--idp-issuer string` +|Specify the issuer of the IdP. + +|`--metadata-url string` +|Specify the metadata URL of the service provider. + +|`--name-id-format string` +|Specify the format of the name ID. + +|`--sp-issuer string` +|Specify the issuer of the service provider. + +|`--sso-url string` +|Specify the URL of the IdP for single sign-on (SSO). +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-auth-provider-userpki.adoc b/modules/roxctl-declarative-config-create-auth-provider-userpki.adoc new file mode 100644 index 000000000000..ae7637d4db91 --- /dev/null +++ b/modules/roxctl-declarative-config-create-auth-provider-userpki.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-auth-provider-userpki_{context}"] += roxctl declarative-config create auth-provider userpki + +Create a declarative configuration for an user PKI authentication provider. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create auth-provider userpki [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--ca-file string` +|Specify the file containing the certification authorities in PEM format. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-auth-provider.adoc b/modules/roxctl-declarative-config-create-auth-provider.adoc new file mode 100644 index 000000000000..4ae1ff0288f4 --- /dev/null +++ b/modules/roxctl-declarative-config-create-auth-provider.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-auth-provider_{context}"] += roxctl declarative-config create auth-provider + +Create a declarative configuration for an authentication provider. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create auth-provider [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--extra-ui-endpoints strings` +|Specify additional user interface (UI) endpoints from which the authentication provider is used. The expected format is `<endpoint>:<port>`. + +|`--groups-key strings` +|Set the keys of the groups that you want to add within the authentication provider. The tuples of key, value and role should have the same length. For more details, run the `roxctl declarative-config create auth-provider --help` command. + +|`--groups-role strings` +|Set the role of the groups that you want to add within the authentication provider. The tuples of key, value and role should have the same length. For more details, run the `roxctl declarative-config create auth-provider --help` command. + +|`--groups-value strings` +|Set the values of the groups that you want to add within the authentication provider. The tuples of key, value and role should have the same length. For more details, run the `roxctl declarative-config create auth-provider --help` command. + +|`--minimum-access-role string` +|Set the minimum access role of the authentication provider. You can leave this field empty if you do not want to configure the minimum access role by using the declarative configuration. + +|`--name string` +|Specify the name of the authentication provider. + +|`--required-attributes stringToString` +|Set a list of attributes that the authentication provider must return during authentication. The default value is `[]`. + +|`--ui-endpoint string` +|Set the UI endpoint from which the authentication provider is used. This is usually the public endpoint where {product-title-short} is available. The expected format is `<endpoint>:<port>`. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-notifier-generic.adoc b/modules/roxctl-declarative-config-create-notifier-generic.adoc new file mode 100644 index 000000000000..97a075b943e8 --- /dev/null +++ b/modules/roxctl-declarative-config-create-notifier-generic.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-notifier-generic_{context}"] += roxctl declarative-config create notifier generic + +Create a declarative configuration for a generic notifier. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create notifier generic [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--audit-logging` +|Enable audit logging. The default value is `false`. + +|`--extra-fields stringToString` +|Specify additional fields as comma-separated `key=value` pairs. The default value is `[]`. + +|`--headers stringToString` +|Specify headers as comma-separated `key=value` pairs. The default value is `[]`. + +|`--webhook-cacert-file string` +|Specify the file name of the endpoint CA certificate in PEM format. + +|`--webhook-endpoint string` +|Specify the URL of the webhook endpoint. + +|`--webhook-password string` +|Specify the password for basic authentication of the webhook endpoint. No authentication if not specified. Requires `--webhook-username`. + +|`--webhook-skip-tls-verify` +|Skip webhook TLS verification. The default value is `false`. + +|`--webhook-username string` +|Specify the username for basic authentication of the webhook endpoint. No authentication occurs if not specified. Requires `--webhook-password`. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-notifier-splunk.adoc b/modules/roxctl-declarative-config-create-notifier-splunk.adoc new file mode 100644 index 000000000000..722ae985f683 --- /dev/null +++ b/modules/roxctl-declarative-config-create-notifier-splunk.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-notifier-splunk_{context}"] += roxctl declarative-config create notifier splunk + +Create a declarative configuration for a splunk notifier. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create notifier splunk [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--audit-logging` +|Enable audit logging. The default value is `false`. + +|`--source-types stringToString` +|Specify Splunk source types as comma-separated `key=value` pairs. The default value is `[]`. + +|`--splunk-endpoint string` +|Specify the Splunk HTTP endpoint. This is a mandatory option. + +|`--splunk-skip-tls-verify` +|Use an insecure connection to Splunk. The default value is `false`. + +|`--splunk-token string` +|Specify the Splunk HTTP token. This is a mandatory option. + +|`--truncate int` +|Specify the Splunk truncate limit. The default value is `10000`. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-notifier.adoc b/modules/roxctl-declarative-config-create-notifier.adoc new file mode 100644 index 000000000000..cabd5399523f --- /dev/null +++ b/modules/roxctl-declarative-config-create-notifier.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-notifier_{context}"] += roxctl declarative-config create notifier + +Create a declarative configuration for a notifier. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create notifier [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--name string` +|Specify the name of the notifier. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-permission-set.adoc b/modules/roxctl-declarative-config-create-permission-set.adoc new file mode 100644 index 000000000000..710e667c848f --- /dev/null +++ b/modules/roxctl-declarative-config-create-permission-set.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-permission-set_{context}"] += roxctl declarative-config create permission-set + +Create a declarative configuration for a permission set. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create permission-set [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--description string` +|Set the description of the permission set. + +|`--name string` +|Specify the name of the permission set. + +|`--resource-with-access stringToString` +|Set a list of resources with their respective access levels. The default value is `[]`. For more details, run the `roxctl declarative-config create permission-set --help` command. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create-role.adoc b/modules/roxctl-declarative-config-create-role.adoc new file mode 100644 index 000000000000..5cb7030905d5 --- /dev/null +++ b/modules/roxctl-declarative-config-create-role.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create-role_{context}"] += roxctl declarative-config create role + +Create a declarative configuration for a role. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create role [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--access-scope string` +|By providing the name, you can specify the referenced access scope. + +|`--description string` +|Set a description for the role. + +|`--name string` +|Specify the name of the role. + +|`--permission-set string` +|By providing the name, you can specify the referenced permission set. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-create.adoc b/modules/roxctl-declarative-config-create.adoc new file mode 100644 index 000000000000..560877bacb0c --- /dev/null +++ b/modules/roxctl-declarative-config-create.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-create_{context}"] += roxctl declarative-config create + +Create declarative configurations. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config create [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--config-map string` +|Write the declarative configuration YAML in the configuration map. If not specified and the `--secret` flag is also not specified, the generated YAML is printed in the standard output format. + +|`--namespace string` +|Required if you want to write the declarative configuration YAML to a configuration map or secret. If not specified, the default namespace in the current Kubernetes configuration is used. + +|`--secret string` +|Write the declarative configuration YAML in the Secret. You must use secrets for sensitive data. If not specified and the `--config-map` flag is also not specified, the generated YAML is printed in the standard output format. +|=== \ No newline at end of file diff --git a/modules/roxctl-declarative-config-lint.adoc b/modules/roxctl-declarative-config-lint.adoc new file mode 100644 index 000000000000..0d413bcd5be9 --- /dev/null +++ b/modules/roxctl-declarative-config-lint.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-declarative-config.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-declarative-config-lint_{context}"] += roxctl declarative-config lint + +Lint an existing declarative configuration YAML file. + +.Usage +[source,terminal] +---- +$ roxctl declarative-config lint [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--config-map string` +|Read the declarative configuration from the `--config-map string`. If not specified, the configuration is read from the YAML file specified by using the `--file` flag. + +|`-f`, `--file string` +|File containing the declarative configuration in YAML format. + +|`--namespace string` +|Read the declarative configuration from the `--namespace string` of the configuration map. If not specified, the namespace specified in the current Kubernetes configuration context is used. + +|`--secret string` +|Read the declarative configuration from the specified `--secret string`. If not specified, the configuration is read from the YAML file specified by using the `--file` flag. +|=== \ No newline at end of file diff --git a/modules/roxctl-deployment-check.adoc b/modules/roxctl-deployment-check.adoc new file mode 100644 index 000000000000..eb6eecf6a043 --- /dev/null +++ b/modules/roxctl-deployment-check.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-deployment.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-deployment-check_{context}"] += roxctl deployment check + +Check deployments for violations of the deployment time policy. + +.Usage +[source,terminal] +---- +$ roxctl deployment check [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`-c`, `--categories strings` +|Define the policy categories that you want to execute. By default, all policy categories are executed. + +|`--cluster string` +|Set the cluster name or ID that you want to use as the context for the evaluation to enable extended deployments with cluster-specific information. + +|`--compact-output` +|Print the JSON output in compact form. The default value is `false`. + +|`-f`, `--file stringArray` +|Specify the YAML files to send to Central for policy evaluation. + +|`--force` +|Bypass the Central cache for images and force a new pull from Scanner. The default value is `false`. + +|`--headers strings` +|Define headers that you want to print in the tabular output. The default values include `POLICY`, `SEVERITY`, `BREAKS DEPLOY`, `DEPLOYMENT`, `DESCRIPTION`, `VIOLATION`, and `REMEDIATION`. + +|`--headers-as-comments` +|Print headers as comments in the CSV tabular output. The default value is `false`. + +|`--junit-suite-name string` +|Set the name of the JUnit test suite. The default value is `deployment-check`. + +|`--merge-output` +|Merge duplicate cells in the tabular output. The default value is `false`. + +|`-n`, `--namespace string` +|Specify a namespace to enhance deployments with context information such as network policies, RBACs and services for deployments that do not have a namespace in their specification. The namespace defined in the specification is not changed. The default value is `default`. + +|`--no-header` +|Do not print headers for a tabular output. The default value is `false`. + +|`-o`, `--output string` +|Choose the output format. Output formats include `json`, `junit`, `sarif`, `table`, and `csv`. The default value is `table`. + +|`-r`, `--retries int` +|Set the number of retries before exiting as an error. The default value is `3`. + +|`-d`, `--retry-delay int` +|Set the time to wait between retries in seconds. The default value is `3`. + +|`--row-jsonpath-expressions string` +|Define the JSON path expressions to create a row from the JSON object. For more details, run the `roxctl deployment check --help` command. +|=== \ No newline at end of file diff --git a/modules/roxctl-generate-init-bundle.adoc b/modules/roxctl-generate-init-bundle.adoc new file mode 100644 index 000000000000..a2c7cb4fa9b3 --- /dev/null +++ b/modules/roxctl-generate-init-bundle.adoc @@ -0,0 +1,99 @@ +// Module included in the following assemblies: +// +// * installing/installing_helm/install-helm-customization.adoc +// * installing/install-ocp-operator.adoc +// +// You must declare the `topic-helm` or `topic-operator` attribute when using this module. +:_mod-docs-content-type: PROCEDURE +[id="roxctl-generate-init-bundle_{context}"] += Generating an init bundle by using the roxctl CLI + +ifeval::["{context}" == "init-bundle-cloud-other"] +:other: +endif::[] + +ifeval::["{context}" == init-bundle-cloud-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-generate"] +:cloud-ocp-generate: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-generate"] +:cloud-other-generate: +endif::[] + +You can create an init bundle with secrets by using the `roxctl` CLI. + +[NOTE] +==== +You must have the `Admin` user role to create init bundles. +==== + +.Prerequisites + +* You have configured the `ROX_API_TOKEN` and the `ROX_CENTRAL_ADDRESS` environment variables: + +.. Set the `ROX_API_TOKEN` by running the following command: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN=<api_token> +---- + +.. Set the `ROX_CENTRAL_ADDRESS` environment variable by running the following command: ++ +[source,terminal] +---- +$ export ROX_CENTRAL_ADDRESS=<address>:<port_number> +---- + +ifdef::cloud-ocp-generate,cloud-other-generate[] +[IMPORTANT] +==== +In {product-title-managed-short}, when using `roxctl` commands that require the Central address, use the *Central instance address* as displayed in the *Instance Details* section of the {cloud-console}. For example, use `acs-ABCD12345.acs.rhcloud.com` instead of `acs-data-ABCD12345.acs.rhcloud.com`. +==== +endif::cloud-ocp-generate,cloud-other-generate[] + +.Procedure + +* To generate a cluster init bundle containing secrets for Helm installations, run the following command: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" \ + central init-bundles generate <cluster_init_bundle_name> --output \ + cluster_init_bundle.yaml +---- + +* To generate a cluster init bundle containing secrets for Operator installations, run the following command: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" \ + central init-bundles generate <cluster_init_bundle_name> --output-secrets \ + cluster_init_bundle.yaml +---- ++ +[IMPORTANT] +==== +Ensure that you store this bundle securely because it contains secrets. +You can use the same bundle to set up multiple secured clusters. +==== + +ifeval::["{context}" == "init-bundle-cloud-other"] +:!other: +endif::[] + +ifeval::["{context}" == init-bundle-cloud-ocp"] +:!openshift: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-ocp-generate"] +:!cloud-ocp-generate: +endif::[] + +ifeval::["{context}" == "init-bundle-cloud-other-generate"] +:!cloud-other-generate: +endif::[] \ No newline at end of file diff --git a/modules/roxctl-generate-netpol.adoc b/modules/roxctl-generate-netpol.adoc new file mode 100644 index 000000000000..1f0fa0c85133 --- /dev/null +++ b/modules/roxctl-generate-netpol.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * /command-reference/roxctl-generate.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-generate-netpol_{context}"] += roxctl generate netpol + +Recommend network policies based on the deployment information. + +.Usage +[source,terminal] +---- +$ roxctl generate netpol <folder_path> [flags] <1> +---- + +<1> For the `<folder_path>`, specify the path to the directory containing your Kubernetes deployment and service configuration files. + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--fail` +|Fail on the first encountered error. The default value is `false`. + +|`-h`, `--help` +|View the help text for the `roxctl generate netpol` command. + +|`-d`, `--output-dir string` +|Save the generated policies into the target folder. + +|`-f`, `--output-file string` +|Save and merge the generated policies into a single YAML file. + +|`--remove` +|Remove the output path if it already exists. The default value is `false`. + +|`--strict` +|Treat warnings as errors. The default value is `false`. +|=== \ No newline at end of file diff --git a/modules/roxctl-helm-derive-local-values.adoc b/modules/roxctl-helm-derive-local-values.adoc new file mode 100644 index 000000000000..2fd0749a1ff1 --- /dev/null +++ b/modules/roxctl-helm-derive-local-values.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-helm.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-helm-derive-local-values_{context}"] += roxctl helm derive-local-values + +Derive local Helm values from the cluster configuration. + +.Usage +[source,terminal] +---- +$ roxctl helm derive-local-values --output <path> \// <1> +<central_services> [flags] <2> +---- + +<1> For the `<path>`, specify the path where you want to save the generated local values file. +<2> For the `<central_services>`, specify the path to the central services configuration file. + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--input string` +|Specify the path to the file or directory containing the YAML input. + +|`--output string` +|Define the path to the output file. + +|`--output-dir string` +|Define the path to the output directory. + +|`--retry-timeout duration` +|Set the timeout after which API requests are retried. The timeout value indicates that the entire request duration is waited for without retrying. The default value is `20s`. + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-helm-output.adoc b/modules/roxctl-helm-output.adoc new file mode 100644 index 000000000000..206fb8fc3bf6 --- /dev/null +++ b/modules/roxctl-helm-output.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-helm.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-helm-output_{context}"] += roxctl helm output + +Output a Helm chart. + +.Usage +[source,terminal] +---- +$ roxctl helm output <central_services or secured_cluster_services> [flags] <1> +---- + +<1> For `<central_services or secured_cluster_services>`, specify the path to either the central services or the secured cluster services to generate a Helm chart output. + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--debug` +|Read templates from the local filesystem. The default value is `false`. + +|`--debug-path string` +|Specify the path to the Helm templates on your local filesystem. For more details, run the `roxctl helm output --help` command. + +|`--image-defaults string` +|Set the default container image settings. Image settings include `development_build`, `stackrox.io`, `rhacs`, and `opensource`. It influences repositories for image downloads, image names, and tag formats. The default value is `development_build`. + +|`--output-dir string` +|Define the path to the output directory for the Helm chart. The default path is `./stackrox-<chart name>-chart`. + +|`--remove` +|Remove the output directory if it already exists. The default value is `false`. +|=== \ No newline at end of file diff --git a/modules/roxctl-image-check.adoc b/modules/roxctl-image-check.adoc new file mode 100644 index 000000000000..69475ba7129c --- /dev/null +++ b/modules/roxctl-image-check.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-check_{context}"] += roxctl image check + +Check images for build time policy violations, and report them. + +.Usage +[source,terminal] +---- +$ roxctl image check [flags] +---- + +.Options +[cols="5,4",options="header"] +|=== +|Option |Description + +|`-c`, `--categories strings` +|List of the policy categories that you want to execute. By default, all the policy categories are used. + +|`--cluster string` +|Define the cluster name or ID that you want to use as the context for evaluation. + +|`--compact-output` +|Print JSON output in a compact format. The default value is `false`. + +|`-f`, `--force` +|Bypass the Central cache for the image and force a new pull from the Scanner. The default value is `false`. + +|`--headers strings` +|Define headers to print in a tabular output. The default values include `POLICY`, `SEVERITY`, `BREAKS BUILD`, `DESCRIPTION`, `VIOLATION`, and `REMEDIATION`. + +|`--headers-as-comments` +|Print headers as comments in a CSV tabular output. The default value is `false`. + +|`-i`, `--image string` +|Specify the image name and reference. For example, `nginx:latest` or `nginx@sha256:...)`. + +|`--junit-suite-name string` +|Set the name of the JUnit test suite. Default value is `image-check`. + +|`--merge-output` +|Merge duplicate cells in a tabular output. The default value is `false`. + +|`--namespace` +|Specify a namespace on the secured cluster from which to read context information, specifically pull secrets to access the image registry, when delegating image scans. + +|`--no-header` +|Do not print headers for a tabular output. The default value is `false`. + +|`-o`, `--output string` +|Choose the output format. Output formats include `junit`, `sarif`, `table`, `csv`, and `json`. The default value is `table`. + +|`-r`, `--retries int` +|Set the number of retries before exiting as an error. The default value is `3`. + +|`-d`, `--retry-delay int` +|Set the time to wait between retries in seconds. The default value is `3`. + +|`--row-jsonpath-expressions string` +|Create a row from the JSON object by using JSON path expression. For more details, run the `roxctl image check --help` command. + +|`--send-notifications` +|Define whether you want to send notifications in the event of violations. The default value is `false`. +|=== diff --git a/modules/roxctl-image-sbom.adoc b/modules/roxctl-image-sbom.adoc new file mode 100644 index 000000000000..7af632536e27 --- /dev/null +++ b/modules/roxctl-image-sbom.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-sbom_{context}"] += roxctl image sbom + +Generate an SPDX 2.3 SBOM from an image scan. You must have write permissions for the `Image` resource. + +.Usage +[source,terminal] +---- +$ roxctl image sbom [flags] +---- + +.Options +[cols="5,4",options="header"] +|=== +|Option |Description + +|`--cluster` string +|Cluster name or ID that you want to delegate the image scan to. + +|`--namespace` string +|Namespace on the secured cluster from which to read context information when delegating image scans, specifically pull secrets for accessing the image registry. + +|`-f, --force` +|Bypass Central's cache for the image and force a new pull from the scanner. The default is `false`. + +|`-d, --retry-delay integer` +|Sets the time to wait between retries in seconds. The default is 3. + +|`-i, --image string` +|Image name and reference, for example, `nginx:latest` or `nginx@sha256:...`. + +|`-r, --retries integer` +|Sets the number of times that Scanner V4 should retry before exiting with an error. The default is 3. +|=== diff --git a/modules/roxctl-image-scan-command-options.adoc b/modules/roxctl-image-scan-command-options.adoc new file mode 100644 index 000000000000..eeee991fdcea --- /dev/null +++ b/modules/roxctl-image-scan-command-options.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * cli/image-scanning-by-using-the-roxctl-cli.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-scan-command-options_{context}"] += roxctl image scan command options + +The `roxctl image scan` command supports the following options: + +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--cluster string` +|Delegate image scanning to a specific cluster. + +|`--compact-output` +|Print the JSON output in a compact format. The default value is `false`. + +|`-f`, `--force` +|Ignore Central's cache for the scan and force a fresh re-pull from Scanner. The default value is `false`. + +|`--headers strings` +|Print the headers in a tabular format. Default values include `COMPONENT`,`VERSION`,`CVE`,`SEVERITY`, and `LINK`. + +|`--headers-as-comments` +|Print the headers as comments in a CSV tabular output. The default value is `false`. + +|`-h`, `--help` +|View the help text for the `roxctl image scan` command. + +|`-i`, `--image string` +|Specify the image name and reference you want to scan. + +|`-a`, `--include-snoozed` +|Return both snoozed and unsnoozed common vulnerabilities and exposures (CVEs). The default value is `false`. + +|`--merge-output` +|Merge duplicate cells in a tabular output. The default value is `true`. + +|`--no-header` +|Do not print headers for tabular format. The default value is `false`. + +|`-o`, `--output string` +|Specify the output format. You can select a format to customize the display of results. Formats include `table`, `CSV`, `JSON`, and `SARIF`. + +|`-r`, `--retries int` +|Set the number of retries before the operation is aborted with an error. The default value is `3`. + +|`-d`, `--retry-delay int` +|Set the time in seconds to wait between retries. The default value is `3`. + +|`--row-jsonpath-expressions string` +|Use the JSON path expressions to create rows from the JSON object. For more details, run the `roxctl image scan --help` command. +|=== \ No newline at end of file diff --git a/modules/roxctl-image-scan.adoc b/modules/roxctl-image-scan.adoc new file mode 100644 index 000000000000..0f4340bed999 --- /dev/null +++ b/modules/roxctl-image-scan.adoc @@ -0,0 +1,70 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-image.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-image-scan_{context}"] += roxctl image scan + +Scan the specified image, and return the scan results. + +.Usage +[source,terminal] +---- +$ roxctl image scan [flags] +---- + +.Options +[cols="5,4",options="header"] +|=== +|Option |Description + +|`--cluster string` +|Specify the cluster name or ID to which you want to delegate the image scan. + +|`--compact-output` +|Print JSON output in a compact format. The default value is `false`. + +|`--fail` +|Fail if vulnerabilities have been found. The default value is `false`. + +|`-f`, `--force` +|Ignore Central's cache and force a fresh re-pull from Scanner. The default value is `false`. + +|`--headers strings` +|Specify the headers to print in a tabular output. The default values include `COMPONENT`, +`VERSION`,`CVE`,`SEVERITY`, and `LINK`. + +|`--headers-as-comments` +|Print headers as comments in a CSV tabular output. The default value is `false`. + +|`-i`, `--image string` +|Specify the image name and reference to scan. For example, `nginx:latest` or `nginx@sha256:...`. + +|`-a`, `--include-snoozed` +|Include snoozed and unsnoozed CVEs in the scan results. The default value is `false`. + +|`--merge-output` +|Merge duplicate cells in a tabular output. The default value is `true`. + +|`--namespace` +|Specify a namespace on the secured cluster from which to read context information, specifically pull secrets to access the image registry, when delegating image scans. + +|`--no-header` +|Do not print headers for a tabular output. The default value is `false`. + +|`-o`, `--output string` +|Specify the output format. Output formats include `table`, `csv`, `json`, and `sarif`. + +|`-r`, `--retries int` +|Specify the number of retries before exiting as an error. The default value is `3`. + +|`-d`, `--retry-delay int` +|Set the time to wait between retries in seconds. The default value is `3`. + +|`--row-jsonpath-expressions string` +|Specify JSON path expressions to create a row from the JSON object. For more details, run the `roxctl image scan --help` command. + +|`--severity strings` +|List of severities to include in the output. Use this to filter for specific severities. The default values include `LOW`, `MODERATE`, `IMPORTANT`, and `CRITICAL`. +|=== diff --git a/modules/roxctl-netpol-connectivity-diff-command-options.adoc b/modules/roxctl-netpol-connectivity-diff-command-options.adoc new file mode 100644 index 000000000000..b0b6ef0b6d41 --- /dev/null +++ b/modules/roxctl-netpol-connectivity-diff-command-options.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-netpol-connectivity-diff-command-options_{context}"] += roxctl netpol connectivity diff command options + +The `roxctl netpol connectivity diff` command supports the following options: + +[%autowidth,options="header"] +|=== + +|Option |Description + +|`--dir1 string` +|First directory path of the input resources. This is a mandatory option. + +|`--dir2 string` +|Second directory path of the input resources to be compared with the first directory path. This is a mandatory option. + +|`--fail` +|Fail on the first encountered error. The default value is `false`. + +|`-h`, `--help` +|View the help text for the `roxctl netpol connectivity diff` command. + +|`-f`, `--output-file string` +|Save the connections difference output into a specific file. + +|`-o`, `--output-format string` +|Configure the output format. The supported formats are `txt`, `md`, `dot`, and `csv`. The default value is `txt`. + +|`--remove` +|Remove the output path if it already exists. The default value is `false`. + +|`--save-to-file` +|Save the connections difference output into default a file. The default value is `false`. + +|`--strict` +|Treat warnings as errors. The default value is `false`. + +|=== \ No newline at end of file diff --git a/modules/roxctl-netpol-connectivity-diff.adoc b/modules/roxctl-netpol-connectivity-diff.adoc new file mode 100644 index 000000000000..5713a2146c2d --- /dev/null +++ b/modules/roxctl-netpol-connectivity-diff.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-netpol.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-netpol-connectivity-diff_{context}"] += roxctl netpol connectivity diff + +Report connectivity differences based on two network policy directories and YAML manifests with workload resources. + +.Usage +[source,terminal] +---- +$ roxctl netpol connectivity diff [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--dir1 string` +|Specify the first directory path of the input resources. This value is mandatory. + +|`--dir2 string` +|Specify the second directory path of the input resources that you want to compare with the first directory path. This value is mandatory. + +|`--fail` +|Fail on the first encounter. The default value is `false`. + +|`-f`, `--output-file string` +|Save the output of the connectivity difference command into a specific file. + +|`-o`, `--output-format string` +|Configure the output of the connectivity difference command in a specific format. Supported formats include `txt`, `md`, `csv`. The default value is `txt`.. + +|`--remove` +|Remove the output path if it already exists. The default value is `false`. + +|`--save-to-file` +|Define whether you want to store the output of the connectivity differences in the default file. The default value is `false`. + +|`--strict` +|Treat warnings as errors. The default value is `false`. +|=== \ No newline at end of file diff --git a/modules/roxctl-netpol-connectivity-map-command-options.adoc b/modules/roxctl-netpol-connectivity-map-command-options.adoc new file mode 100644 index 000000000000..64f8a5899d50 --- /dev/null +++ b/modules/roxctl-netpol-connectivity-map-command-options.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-netpol-connectivity-map-command-options_{context}"] += roxctl netpol connectivity map command options + +The `roxctl netpol connectivity map` command supports the following options: + +[%autowidth,options="header"] +|=== + +|Option |Description + +|`--explain` +|Enhance the analysis of permitted connectivity with explanations per denied/allowed connection; supported only for txt output format. + +|`--fail` +|Fail on the first encountered error. The default value is `false`. + +|`--focus-workload string` +|Focus on connections of a specified workload name in the output. + +|`-h`, `--help` +|View the help text for the `roxctl netpol connectivity map` command. + +|`-f`, `--output-file string` +|Save the connections list output into a specific file. + +|`-o`, `--output-format string` +|Configure the output format. The supported formats are `txt`, `json`, `md`, `dot`, and `csv`. The default value is `txt`. + +|`--remove` +|Remove the output path if it already exists. The default value is `false`. + +|`--save-to-file` +|Save the connections list output into a default file. The default value is `false`. + +|`--strict` +|Treat warnings as errors. The default value is `false`. +|=== \ No newline at end of file diff --git a/modules/roxctl-netpol-connectivity-map.adoc b/modules/roxctl-netpol-connectivity-map.adoc new file mode 100644 index 000000000000..8cae6565bc1a --- /dev/null +++ b/modules/roxctl-netpol-connectivity-map.adoc @@ -0,0 +1,53 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-netpol.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-netpol-connectivity-map_{context}"] += roxctl netpol connectivity map + +Analyze connectivity based on the network policies and other resources. + +.Usage +[source,terminal] +---- +$ roxctl netpol connectivity map <folder_path> [flags] <1> +---- + +<1> For `<folder_path>`, specify the path to the directory containing your Kubernetes deployment and service configuration files. + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--explain` +|Enhance the analysis of permitted connectivity with explanations per denied/allowed connection; supported only for txt output format. + +|`--exposure` +|Enhance the analysis of permitted connectivity by using exposure analysis. The default value is `false`. + +|`--fail` +|Fail on the first encountered error. The default value is `false`. + +|`--focus-workload string` +|Focus on connections of the specified workload name in the output. + +|`-f`, `--output-file string` +|Save the connections list output into a specific file. + +|`-h`, `--help` +|View the help text for the `roxctl netpol connectivity map` command. + +|`-o`, `--output-format string` +|Configure the connections list in a specific format. Supported formats include `txt`, `json`, `md`, `dot`, and `csv`. The default value is `txt`. + +|`--remove` +|Remove the output path if it already exists. The default value is `false`. + +|`--save-to-file` +|Define whether you want to save the output of the connection list in the default file. The default value is `false`. + +|`--strict` +|Treat warnings as errors. The default value is `false`. +|=== \ No newline at end of file diff --git a/modules/roxctl-netpol-connectivity.adoc b/modules/roxctl-netpol-connectivity.adoc new file mode 100644 index 000000000000..dc90e50f1899 --- /dev/null +++ b/modules/roxctl-netpol-connectivity.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-netpol.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-netpol-connectivity_{context}"] += roxctl netpol connectivity + +Commands related to the connectivity analysis of the network policy resources. + +.Usage +[source,terminal] +---- +$ roxctl netpol connectivity [flags] +---- \ No newline at end of file diff --git a/modules/roxctl-netpol-generate-command-options.adoc b/modules/roxctl-netpol-generate-command-options.adoc new file mode 100644 index 000000000000..a85f650a32b5 --- /dev/null +++ b/modules/roxctl-netpol-generate-command-options.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-netpol-generate-command-options_{context}"] += roxctl netpol generate command options + +The `roxctl netpol generate` command supports the following options: + +[cols="1m,2",options="header"] +|=== + +|Option |Description + +| -h, --help +| View the help text for the `netpol` command. + +| -d, --output-dir <dir> +| Save the generated policies into a target folder. One file per policy. + +| -f, --output-file <filename> +| Save and merge the generated policies into a single YAML file. + +| --fail +| Fail on the first encountered error. The default value is `false`. + +| --remove +| Remove the output path if it already exist. + +| --strict +| Treat warnings as errors. The default value is `false`. + +|=== \ No newline at end of file diff --git a/modules/roxctl-netpol-generate.adoc b/modules/roxctl-netpol-generate.adoc new file mode 100644 index 000000000000..e8a5bb9a737d --- /dev/null +++ b/modules/roxctl-netpol-generate.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-netpol.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-netpol-generate_{context}"] += roxctl netpol generate + +Recommend network policies based on the deployment information. + +.Usage +[source,terminal] +---- +$ roxctl netpol generate <folder_path> [flags] <1> +---- + +<1> For `<folder_path>`, specify the path to the directory containing your Kubernetes deployment and service configuration files. + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--dnsport <int_or_string>` +a|Specify the DNS port or a named port that you want to use in the egress rules of synthesized network policies. For example: + +* `roxctl netpol generate --dnsport 5353 <other_options>` +* `roxctl netpol generate --dnsport foo-dns <other_options>`. + +|`--fail` +|Fail on the first encountered error. The default value is `false`. + +|`-d`, `--output-dir string` +|Save generated policies into the target folder. + +|`-f`, `--output-file string` +|Save and merge generated policies into a single YAML file. + +|`--remove` +|Remove the output path if it already exists. The default value is `false`. + +|`--strict` +|Treat warnings as errors. The default value is `false`. +|=== + +[NOTE] +==== +If you do not specify a port, the `roxctl netpol generate` command uses port `53` for DNS connections. + +If you are using {ocp}, you might need to change the port when generating network policies by using the `roxctl` CLI. If you do not change the port, {ocp} uses port `5353` and assigns the name `dns` for this port automatially. You can use the `--dnsport` option to override the default DNS port. For example: + +* `roxctl netpol generate --dnsport 5353 <other_options>` +* `roxctl netpol generate --dnsport dns <other-options>`. +==== + diff --git a/modules/roxctl-scanner-download-db.adoc b/modules/roxctl-scanner-download-db.adoc new file mode 100644 index 000000000000..e0893b81aa28 --- /dev/null +++ b/modules/roxctl-scanner-download-db.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-scanner.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-scanner-download-db_{context}"] += roxctl scanner download-db + +Download the offline vulnerability database for StackRox Scanner or Scanner V4. + +This command downloads version-specific offline vulnerability bundles. The system contacts Central to determine the version if one is not specified. If communication fails, the download defaults to the version embedded within `roxctl`. + +By default, it will attempt to download the database for the determined version and less-specific variants. For example, if version `4.4.1-extra` is specified, downloads will be attempted for the following version variants: + +* 4.4.1-extra +* 4.4.1 +* 4.4 + +.Usage +[source,terminal] +---- +$ roxctl scanner download-db [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--force` +| Force overwriting the output file if it already exists. The default value is `false`. + +|`--scanner-db-file string` +| Output file to save the vulnerability database to. The default value is the name and path of the remote file that is downloaded. + +|`--skip-central` +| Do not contact Central when detecting the version. The default value is `false`. + +|`--skip-variants` +| Do not attempt to process variants of the determined version. The default value is `false`. + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `10m0s`. + +|`--version string` +| Download a specific version or version variant of the vulnerability database. By default, the version is automatically detected. +|=== \ No newline at end of file diff --git a/modules/roxctl-scanner-generate.adoc b/modules/roxctl-scanner-generate.adoc new file mode 100644 index 000000000000..a1c26403fb03 --- /dev/null +++ b/modules/roxctl-scanner-generate.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-scanner.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-scanner-generate_{context}"] += roxctl scanner generate + +Generate the required YAML configuration files to deploy Scanner. + +.Usage +[source,terminal] +---- +$ roxctl scanner generate [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--cluster-type cluster type` +|Specify the type of cluster on which you want to run Scanner. Cluster types include `k8s` and `openshift`. The default value is `k8s`. + +|`--enable-pod-security-policies` +|Create `PodSecurityPolicy` resources. The default value is `true`. + +|`--istio-support string` +|Generate deployment files that support the specified Istio version. Valid versions include `1.0`, `1.1`, `1.2`, `1.3`, `1.4`, `1.5`, `1.6`, and `1.7`. + +|`--output-dir string` +|Specify the output directory for the Scanner bundle. Leave blank to use the default value. + +|`--retry-timeout duration` +|Set the timeout after which API requests are retried. A value of zero means that the entire request duration is waited for without retrying. The default value is `20s`. + +|`--scanner-image string` +|Specify the Scanner image that you want to use. Leave blank to use the server default. + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `1m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-scanner-upload-db.adoc b/modules/roxctl-scanner-upload-db.adoc new file mode 100644 index 000000000000..d19f72d5751d --- /dev/null +++ b/modules/roxctl-scanner-upload-db.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-scanner.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-scanner-upload-db_{context}"] += roxctl scanner upload-db + +Upload a vulnerability database for Scanner. + +.Usage +[source,terminal] +---- +$ roxctl scanner upload-db [flags] +---- + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--scanner-db-file string` +|Specify the file containing the dumped Scanner definitions DB. + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `10m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-sensor-generate-certs.adoc b/modules/roxctl-sensor-generate-certs.adoc new file mode 100644 index 000000000000..465b20073612 --- /dev/null +++ b/modules/roxctl-sensor-generate-certs.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-sensor.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-sensor-generate-certs_{context}"] += roxctl sensor generate-certs + +Download a YAML file with renewed certificates for Sensor, Collector, and Admission controller. + +.Usage +[source,terminal] +---- +$ roxctl sensor generate-certs <cluster_details> [flags] <1> +---- + +<1> For `<cluster_details>`, specify the cluster name or ID. + +.Options +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--output-dir string` +|Specify the output directory for the YAML file. The default value is `.`. +|=== \ No newline at end of file diff --git a/modules/roxctl-sensor-generate-k8s.adoc b/modules/roxctl-sensor-generate-k8s.adoc new file mode 100644 index 000000000000..dd043e6871bb --- /dev/null +++ b/modules/roxctl-sensor-generate-k8s.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-sensor.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-sensor-generate-k8s_{context}"] += roxctl sensor generate k8s + +Generate the required files to deploy {product-title-short} services in a Kubernetes cluster. + +.Usage +[source,terminal] +---- +$ roxctl sensor generate k8s [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--admission-controller-listen-on-events` +|Enable admission controller webhook to listen to Kubernetes events. The default value is `true`. +|=== \ No newline at end of file diff --git a/modules/roxctl-sensor-generate-openshift.adoc b/modules/roxctl-sensor-generate-openshift.adoc new file mode 100644 index 000000000000..cfce7c9e8190 --- /dev/null +++ b/modules/roxctl-sensor-generate-openshift.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-sensor.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-sensor-generate-openshift_{context}"] += roxctl sensor generate openshift + +Generate the required files to deploy {product-title-short} services in a {osp} cluster. + +.Usage +[source,terminal] +---- +$ roxctl sensor generate openshift [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--admission-controller-listen-on-events false|true|auto[=true]` +|`Enable or disable the admission controller webhook to listen to Kubernetes events`. The default value is `auto`. + +|`--disable-audit-logs false|true|auto[=true]` +|Enable or disable audit log collection for runtime detection. The default value is `auto`. + +|`--openshift-version int` +|Specify the {osp} major version for which you want to generate the deployment files. +|=== \ No newline at end of file diff --git a/modules/roxctl-sensor-generate.adoc b/modules/roxctl-sensor-generate.adoc new file mode 100644 index 000000000000..fca4dd945f95 --- /dev/null +++ b/modules/roxctl-sensor-generate.adoc @@ -0,0 +1,81 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-sensor.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-sensor-generate_{context}"] += roxctl sensor generate + +Generate files to deploy {product-title-short} services in secured clusters. + +.Usage +[source,terminal] +---- +$ roxctl sensor generate [flags] +---- + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--admission-controller-disable-bypass` +|Disable the bypass annotations for the admission controller. The default value is `false`. + +|`--admission-controller-enforce-on-creates` +|Dynamic enable for enforcing on object creation in the admission controller. The default value is `false`. + +|`--admission-controller-enforce-on-updates` +|Enable dynamic enforcement of object updates in the admission controller. The default value is `false`. + +|`--admission-controller-listen-on-creates` +|Configure the admission controller webhook to listen to deployment creation. The default value is `false`. + +|`--admission-controller-listen-on-updates` +|Configure the admission controller webhook to listen to deployment updates. The default value is `false`. + +|`--admission-controller-scan-inline` +|Get scans inline when using the admission controller. The default value is `false`. + +|`--admission-controller-timeout int32` +|Set the timeout in seconds for the admission controller. The default value is `3`. + +|`--central string` +|Set the endpoint to which you want to connect Sensor. The default value is `central.stackrox:443`. + +|`--collection-method collection method` +|Specify the collection method that you want to use for runtime support. Collection methods include `none`, `default`, `ebpf` and `core_bpf`. The default value is `default`. + +|`--collector-image-repository string` +|Set the image repository that you want to use to deploy Collector. If not specified, a default value corresponding to the effective `--main-image repository` value is derived. + +|`--continue-if-exists` +|Continue with downloading the sensor bundle even if the cluster already exists. The default value is `false`. + +|`--create-upgrader-sa` +|Decide whether to create the upgrader service account with `cluster-admin` privileges to facilitate automated sensor upgrades. The default value is `true`. + +|`--disable-tolerations` +|Disable tolerations for tainted nodes. The default value is `false`. + +|`--enable-pod-security-policies` +|Create `PodSecurityPolicy` resources. The default value is `true`. + +|`--istio-support string` +|Generate deployment files that support the specified Istio version. Valid versions include `1.0`, `1.1`, `1.2`, `1.3`, `1.4`, `1.5`, `1.6`, `1.7`. + +|`--main-image-repository string` +|Specify the image repository that you want to use to deploy Sensor. If not specified, a default value is used. + +|`--name string` +|Set the cluster name to identify the cluster. + +|`--output-dir string` +|Set the output directory for the bundle contents. The default value is an automatically generated directory name inside the current directory. + +|`--slim-collector string[="true"]` +|Use Collector-slim in the deployment bundle. Valid values include `auto`, `true`, and `false`. The default value is `auto`. + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `5m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-sensor-get-bundle.adoc b/modules/roxctl-sensor-get-bundle.adoc new file mode 100644 index 000000000000..f31f6ea53686 --- /dev/null +++ b/modules/roxctl-sensor-get-bundle.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-sensor.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-sensor-get-bundle_{context}"] += roxctl sensor get-bundle + +Download a bundle with the files to deploy {product-title-short} services into a cluster. + +.Usage +[source,terminal] +---- +$ roxctl sensor get-bundle <cluster_details> [flags] <1> +---- + +<1> For `<cluster_details>`, specify the cluster name or ID. + +.Options +[cols="6,3",options="header"] +|=== +|Option |Description + +|`--create-upgrader-sa` +|Specify whether to create the upgrader service account with `cluster-admin` privileges for automated Sensor upgrades. The default value is `true`. + +|`--istio-support string` +|Generate deployment files that support the specified Istio version. Valid versions include `1.0`, `1.1`, `1.2`, `1.3`, `1.4`, `1.5`, `1.6`, and `1.7`. + +|`--output-dir string` +|Specify the output directory for the bundle contents. The default value is an automatically generated directory name inside the current directory. + +|`--slim-collector string[="true"]` +|Use Collector-slim in the deployment bundle. Valid values include `auto`, `true` and `false`. The default value is `auto`. + +|`-t`, `--timeout duration` +|Set the timeout for API requests representing the maximum duration of a request. The default value is `5m0s`. +|=== \ No newline at end of file diff --git a/modules/roxctl-version-command-options.adoc b/modules/roxctl-version-command-options.adoc new file mode 100644 index 000000000000..bd23cf2d0934 --- /dev/null +++ b/modules/roxctl-version-command-options.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * command-reference/roxctl-version.adoc + +:_mod-docs-content-type: REFERENCE +[id="roxctl-version-command-options_{context}"] += roxctl version command options + +The `roxctl version` command supports the following option: + +[cols="2,2",options="header"] +|=== +|Option |Description + +|`--json` +|Display the extended version information as JSON. The default value is `false`. +|=== \ No newline at end of file diff --git a/modules/run-roxctl-from-container.adoc b/modules/run-roxctl-from-container.adoc new file mode 100644 index 000000000000..7d0b5e0cabd2 --- /dev/null +++ b/modules/run-roxctl-from-container.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * cli/using-roxctl-cli.adoc +:_mod-docs-content-type: PROCEDURE +[id="run-roxctl-from-container_{context}"] += Running the roxctl CLI from a container + +The `roxctl` client is the default entry point in the {product-title-short} `roxctl` image. +To run the `roxctl` client in a container image: + +.Prerequisites +* You must first generate an authentication token from the {product-title-short} portal. + +.Procedure + +. Log in to the `registry.redhat.io` registry. ++ +[source,terminal] +---- +$ docker login registry.redhat.io +---- +. Pull the latest container image for the `roxctl` CLI. ++ +[source,terminal,subs=attributes+] +---- +$ docker pull registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:{rhacs-version} +---- + +After you install the CLI, you can run it by using the following command: +[source,terminal,subs=attributes+] +---- +$ docker run -e ROX_API_TOKEN=$ROX_API_TOKEN \ + -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:{rhacs-version} \ + -e $ROX_CENTRAL_ADDRESS <command> +---- +[NOTE] +==== +In {rh-rhacscs-first}, when using `roxctl` commands that require the Central address, use the *Central instance address* as displayed in the *Instance Details* section of the {cloud-console}. For example, use `acs-ABCD12345.acs.rhcloud.com` instead of `acs-data-ABCD12345.acs.rhcloud.com`. +==== + +.Verification + +* Verify the `roxctl` version you have installed. ++ +[source,terminal,subs=attributes+] +---- +$ docker run -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:{rhacs-version} version +---- \ No newline at end of file diff --git a/modules/running-cluster-loader.adoc b/modules/running-cluster-loader.adoc deleted file mode 100644 index 0c25ff8ae031..000000000000 --- a/modules/running-cluster-loader.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// scalability_and_performance/using-cluster-loader.adoc - -[id="running_cluster_loader_{context}"] -= Running Cluster Loader - -.Prerequisites - -* The repository will prompt you to authenticate. The registry credentials allow -you to access the image, which is not publicly available. Use your existing -authentication credentials from installation. - -.Procedure - -. Execute Cluster Loader using the built-in test configuration, which deploys five -template builds and waits for them to complete: -+ -[source,terminal] ----- -$ sudo podman run -v ${LOCAL_KUBECONFIG}:/root/.kube/config:z -i \ -quay.io/openshift/origin-tests:4.7 /bin/bash -c 'export KUBECONFIG=/root/.kube/config && \ -openshift-tests run-test "[sig-scalability][Feature:Performance] Load cluster \ -should populate the cluster [Slow][Serial] [Suite:openshift]"' ----- -+ -Alternatively, execute Cluster Loader with a user-defined configuration by -setting the environment variable for `VIPERCONFIG`: -+ -[source,terminal] ----- -$ sudo podman run -v ${LOCAL_KUBECONFIG}:/root/.kube/config:z \ --v ${LOCAL_CONFIG_FILE_PATH}:/root/configs/:z \ --i quay.io/openshift/origin-tests:4.7 \ -/bin/bash -c 'KUBECONFIG=/root/.kube/config VIPERCONFIG=/root/configs/test.yaml \ -openshift-tests run-test "[sig-scalability][Feature:Performance] Load cluster \ -should populate the cluster [Slow][Serial] [Suite:openshift]"' ----- -+ -In this example, `${LOCAL_KUBECONFIG}` refers to the path to the `kubeconfig` on -your local file system. Also, there is a directory called -`${LOCAL_CONFIG_FILE_PATH}`, which is mounted into the container that contains a -configuration file called `test.yaml`. Additionally, if the `test.yaml` -references any external template files or podspec files, they should also be -mounted into the container. diff --git a/modules/running-compliance-scans.adoc b/modules/running-compliance-scans.adoc deleted file mode 100644 index 5f2d7a08b819..000000000000 --- a/modules/running-compliance-scans.adoc +++ /dev/null @@ -1,112 +0,0 @@ -// Module included in the following assemblies: -// -// * security/compliance_operator/compliance-scans.adoc - -[id="running-compliance-scans_{context}"] -= Running compliance scans - -You can run a scan using the Center for Internet Security (CIS) profiles. For convenience, the Compliance Operator creates a `ScanSetting` object with reasonable defaults on startup. This `ScanSetting` object is named `default`. - -.Procedure - -. Inspect the `ScanSetting` object by running: -+ -[source,terminal] ----- -$ oc describe scansettings default -n openshift-compliance ----- -+ -.Example output -[source,terminal] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ScanSetting -metadata: - name: default - namespace: openshift-compliance -rawResultStorage: - pvAccessModes: - - ReadWriteOnce <1> - rotation: 3 <2> - size: 1Gi <3> -roles: -- worker <4> -- master <4> -scanTolerations: <5> -- effect: NoSchedule - key: node-role.kubernetes.io/master - operator: Exists -schedule: 0 1 * * * <6> ----- -<1> The Compliance Operator creates a persistent volume (PV) that contains the results of the scans. By default, the PV will use access mode `ReadWriteOnce` because the Compliance Operator cannot make any assumptions about the storage classes configured on the cluster. Additionally, `ReadWriteOnce` access mode is available on most clusters. If you need to fetch the scan results, you can do so by using a helper pod, which also binds the volume. Volumes that use the `ReadWriteOnce` access mode can be mounted by only one pod at time, so it is important to remember to delete the helper pods. Otherwise, the Compliance Operator will not be able to reuse the volume for subsequent scans. -<2> The Compliance Operator keeps results of three subsequent scans in the volume; older scans are rotated. -<3> The Compliance Operator will allocate one GB of storage for the scan results. -<4> If the scan setting uses any profiles that scan cluster nodes, scan these node roles. -<5> The default scan setting object also scans the master nodes. -<6> The default scan setting object runs scans at 01:00 each day. -+ -As an alternative to the default scan setting, you can use `default-auto-apply`, which has the following settings: -+ -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ScanSetting -metadata: - name: default-auto-apply - namespace: openshift-compliance -autoUpdateRemediations: true <1> -autoApplyRemediations: true <1> -rawResultStorage: - pvAccessModes: - - ReadWriteOnce - rotation: 3 - size: 1Gi -schedule: 0 1 * * * -roles: - - worker - - master -scanTolerations: - - effect: NoSchedule - key: node-role.kubernetes.io/master - operator: Exists ----- -<1> Setting `autoUpdateRemediations` and `autoApplyRemediations` flags to `true` allows you to easily create `ScanSetting` objects that auto-remediate without extra steps. - -. Create a `ScanSettingBinding` object that binds to the default `ScanSetting` object and scans the cluster using the `cis` and `cis-node` profiles. For example: -+ -[source,yaml] ----- -apiVersion: compliance.openshift.io/v1alpha1 -kind: ScanSettingBinding -metadata: - name: cis-compliance -profiles: - - name: ocp4-cis-node - kind: Profile - apiGroup: compliance.openshift.io/v1alpha1 - - name: ocp4-cis - kind: Profile - apiGroup: compliance.openshift.io/v1alpha1 -settingsRef: - name: default - kind: ScanSetting - apiGroup: compliance.openshift.io/v1alpha1 ----- - -. Create the `ScanSettingBinding` object by running: -+ -[source, terminal] ----- -$ oc create -f <file-name>.yaml -n openshift-compliance ----- -+ -At this point in the process, the `ScanSettingBinding` object is reconciled and based on the `Binding` and the `Bound` settings. The Compliance Operator creates a `ComplianceSuite` object and the associated `ComplianceScan` objects. - -. Follow the compliance scan progress by running: -+ -[source,terminal] ----- -$ oc get compliancescan -w -n openshift-compliance ----- -+ -The scans progress through the scanning phases and eventually reach the `DONE` phase when complete. In most cases, the result of the scan is `NON-COMPLIANT`. You can review the scan results and start applying remediations to make the cluster compliant. See xref:../../security/compliance_operator/compliance-operator-remediation.adoc#compliance-operator-remediation[Managing Compliance Operator remediation] for more information. diff --git a/modules/s3-api-compatible-services-configuring-acs.adoc b/modules/s3-api-compatible-services-configuring-acs.adoc new file mode 100644 index 000000000000..3dfe0ef3112c --- /dev/null +++ b/modules/s3-api-compatible-services-configuring-acs.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-s3-api-compatible-services.adoc +:_mod-docs-content-type: PROCEDURE +[id="s3-api-compatible-services-configuring-acs_{context}"] += Configuring S3 API compatible integrations in {product-title} + +To configure S3 API compatible backups, create a new integration in {product-title}. + +.Prerequisites +* You have configured an existing S3 bucket. +To create a new bucket with required permissions, see your S3 provider documentation. +* You have `read`, `write`, and `delete` permissions for the S3 bucket, the *Access key ID*, and the *Secret access key*. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *External backups* section and select *S3 API Compatible*. +. Click *New Integration*. +. Enter a name for *Integration Name*. +. Enter the number of backups to retain in the *Backups To Retain* box. +. For *Schedule*, select the backup frequency as daily or weekly, and select the time to run the backup process. +. Enter the *Bucket* name where you want to store the backup. +. Optionally, enter an *Object Prefix* if you want to save the backups in a specific folder structure. +. Enter the *Endpoint* under which the S3 compatible service is reachable. If no scheme is specified, the default, `https`, is used. +. Enter the *Region* for the bucket. Consult your provider's documentation to enter the correct region. +. Select the *URL style*: +* *Virtual hosted* style buckets are addressed as __\https://<bucket>.<endpoint>__. + +* *Path* style buckets are addressed as __\https://<endpoint>/<bucket>__. +. Enter the *Access Key ID* and the *Secret Access Key*. +. Select *Test* to confirm that the integration with the S3 is working. +. Select *Create* to generate the configuration. + +After the integration is configured, {product-title-short} automatically backs up all data according to the specified schedule. diff --git a/modules/sample-audit-log-message.adoc b/modules/sample-audit-log-message.adoc new file mode 100644 index 000000000000..eeb2205328e1 --- /dev/null +++ b/modules/sample-audit-log-message.adoc @@ -0,0 +1,82 @@ +// Module included in the following assemblies: +// +// * configuration/configure-audit-logging.adoc +:_mod-docs-content-type: CONCEPT +[id="sample-audit-log-message_{context}"] += Sample audit log message + +The log message has the following format: + +[source,json] +---- +{ + "headers": { + "Accept-Encoding": [ + "gzip" + ], + "Content-Length": [ + "586" + ], + "Content-Type": [ + "application/json" + ], + "User-Agent": [ + "Go-http-client/1.1" + ] + }, + "data": { + "audit": { + "interaction": "CREATE", + "method": "UI", + "request": { + "endpoint": "/v1/notifiers", + "method": "POST", + "source": { + "requestAddr": "10.131.0.7:58276", + "xForwardedFor": "8.8.8.8", + }, + "sourceIp": "8.8.8.8", + "payload": { + "@type": "storage.Notifier", + "enabled": true, + "generic": { + "auditLoggingEnabled": true, + "endpoint": "http://samplewebhookserver.com:8080/" + }, + "id": "b53232ee-b13e-47e0-b077-1e383c84aa07", + "name": "Webhook", + "type": "generic", + "uiEndpoint": "https://localhost:8000/" + } + }, + "status": "REQUEST_SUCCEEDED", + "time": "2019-05-28T16:07:05.500171300Z", + "user": { + "friendlyName": "John Doe", + "role": { + "globalAccess": "READ_WRITE_ACCESS", + "name": "Admin" + }, + "username": "john.doe@example.com" + } + } + } +} +---- + +The source IP address of the request is displayed in the source parameters, which makes it easier for you to investigate audit log requests and identify their origin. + +To determine the source IP address of a request, {product-title-short} uses the following parameters: + +* `xForwardedFor`: The X-Forwarded-For header. +* `requestAddr`: The remote address header. +* `sourceIp`: The IP address of the HTTP request. + +[IMPORTANT] +==== +The determination of the source IP address depends on how you expose Central externally. You can consider the following options: + +* If you expose Central behind a load balancer, for example, if you are running Central on Google Kubernetes Engine (GKE) or Amazon Elastic Kubernetes Service (Amazon EKS) by using the Kubernetes External Load Balancer service type, see link:https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip[Preserving the client source IP]. +* If you expose Central behind an Ingress Controller that forwards requests by using the link:https://datatracker.ietf.org/doc/html/rfc7239#section-5.2[X-Forwarded-For header], you do not need to make any configuration changes. +* If you expose Central with a TLS passthrough route, you cannot determine the source IP address of the client. A cluster-internal IP address is displayed in the source parameters as the source IP address of the client. +==== \ No newline at end of file diff --git a/modules/sample-windows-workload-deployment.adoc b/modules/sample-windows-workload-deployment.adoc deleted file mode 100644 index c83c32def871..000000000000 --- a/modules/sample-windows-workload-deployment.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/scheduling-windows-workloads.adoc - -[id="sample-windows-workload-deployment_{context}"] -= Sample Windows container workload deployment - -You can deploy Windows container workloads to your cluster once you have a Windows compute node available. - -[NOTE] -==== -This sample deployment is provided for reference only. -==== - -.Example `Service` object -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: win-webserver - labels: - app: win-webserver -spec: - ports: - # the port that this service should serve on - - port: 80 - targetPort: 80 - selector: - app: win-webserver - type: LoadBalancer ----- - -.Example `Deployment` object -[source,yaml] ----- -apiVersion: apps/v1 -kind: Deployment -metadata: - labels: - app: win-webserver - name: win-webserver -spec: - selector: - matchLabels: - app: win-webserver - replicas: 1 - template: - metadata: - labels: - app: win-webserver - name: win-webserver - spec: - tolerations: - - key: "os" - value: "Windows" - Effect: "NoSchedule" - containers: - - name: windowswebserver - image: mcr.microsoft.com/windows/servercore:ltsc2019 - imagePullPolicy: IfNotPresent - command: - - powershell.exe - - -command - - $listener = New-Object System.Net.HttpListener; $listener.Prefixes.Add('http://*/'); $listener.Start();Write-Host('Listening at http://*:80/'); while ($listener.IsListening) { $context = $listener.GetContext(); $response = $context.Response; $content='<html><body><H1>Red Hat OpenShift + Windows Container Workloads</H1></body></html>'; $buffer = [System.Text.Encoding]::UTF8.GetBytes($content); $response.ContentLength64 = $buffer.Length; $response.OutputStream.Write($buffer, 0, $buffer.Length); $response.Close(); }; - securityContext: - windowsOptions: - runAsUserName: "ContainerAdministrator" - nodeSelector: - beta.kubernetes.io/os: windows ----- - -[NOTE] -==== -When using the `mcr.microsoft.com/powershell:<tag>` container image, you must define the command as `pwsh.exe`. If you are using the `mcr.microsoft.com/windows/servercore:<tag>` container image, you must define the command as `powershell.exe`. For more information, see Microsoft's documentation. -==== diff --git a/modules/samples-operator-configuration.adoc b/modules/samples-operator-configuration.adoc deleted file mode 100644 index d63522f18192..000000000000 --- a/modules/samples-operator-configuration.adoc +++ /dev/null @@ -1,118 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/configuring_samples_operator.adoc - - -[id="samples-operator-configuration_{context}"] -= Cluster Samples Operator configuration parameters - -The samples resource offers the following configuration fields: - -[cols="3a,8a",options="header"] -|=== -|Parameter |Description - -|`managementState` -|`Managed`: The Cluster Samples Operator updates the samples as the configuration -dictates. - -`Unmanaged`: The Cluster Samples Operator ignores updates to its configuration -resource object and any imagestreams or templates in the `openshift` namespace. - -`Removed`: The Cluster Samples Operator removes the set of `Managed` imagestreams -and templates in the `openshift` namespace. It ignores new samples created by the -cluster administrator or any samples in the skipped lists. After the removals are -complete, the Cluster Samples Operator works like it is in the `Unmanaged` state and ignores -any watch events on the sample resources, imagestreams, or templates. - -|`samplesRegistry` -|Allows you to specify which registry is accessed by imagestreams for their image content. `samplesRegistry` defaults to `registry.redhat.io` for {product-title}. - -[NOTE] -==== -Creation or update of RHEL content does not commence if the secret for pull -access is not in place when either `Samples Registry` is not explicitly set (i.e., -the empty string), or when it is set to registry.redhat.io. In both cases, image -imports will work off of registry.redhat.io, which requires credentials. - -Creation or update of RHEL content is not gated by the existence of the pull -secret if the `Samples Registry` is overridden to a value other than the empty -string or registry.redhat.io. -==== - -|`architectures` -|Placeholder to choose an architecture type. - -|`skippedImagestreams` -|Imagestreams that are in the Cluster Samples Operator’s inventory but that the cluster -administrator wants the Operator to ignore or not manage. You can add a list of imagestream names to this parameter. For example, `["httpd","perl"]`. - -|`skippedTemplates` -|Templates that are in the Cluster Samples Operator's inventory, but that -the cluster administrator wants the Operator to ignore or not manage. - -|=== - -Secret, imagestream, and template watch events can come in before the initial -samples resource object is created, the Cluster Samples Operator detects and re-queues the -event. - -== Configuration restrictions - -When the Cluster Samples Operator starts supporting multiple architectures, the -architecture list is not allowed to be changed while in the `Managed` state. - -To change the architectures values, a cluster administrator must: - -* Mark the `Management State` as `Removed`, saving the change. -* In a subsequent change, edit the architecture and change the `Management State` -back to `Managed`. - -The Cluster Samples Operator still processes secrets while in `Removed` state. You can -create the secret before switching to `Removed`, while in `Removed` before -switching to `Managed`, or after switching to `Managed` state (though there are -delays in creating the samples until the secret event is processed if you create -the secret after switching to `Managed`). This helps facilitate the -changing of the registry, where you choose to remove all the samples before -switching to insure a clean slate (removing before switching is not required). - -== Conditions - -The samples resource maintains the following conditions in its status: - -[cols="3a,8a",options="header"] -|=== -|Condition |Description - -|`SamplesExists` -|Indicates the samples are created in the `openshift` namespace. - -|`ImageChangesInProgress` -|`True` when imagestreams are created or updated, but -not all of the tag spec generations and tag status generations match. - -`False` when all of the generations match, or unrecoverable errors occurred during -import, the last seen error is in the message field. The list of pending -imagestreams is in the reason field. - -|`ConfigurationValid` -|`True` or `False` based on whether any of the restricted changes noted -previously are submitted. - -|`RemovePending` -|Indicator that there is a `Management State: Removed` setting pending, but the -Cluster Samples Operator is waiting for the deletions to complete. - -|`ImportImageErrorsExist` -|Indicator of which imagestreams had errors during the image import phase for -one of their tags. - -`True` when an error has occurred. The list of imagestreams with an error is -in the reason field. The details of each error reported are in the -message field. - -|`MigrationInProgress` -|`True` when the Cluster Samples Operator detects that the version is different than the -Cluster Samples Operator version with which the current samples set are installed. - -|=== diff --git a/modules/samples-operator-crd.adoc b/modules/samples-operator-crd.adoc deleted file mode 100644 index 32df699dc3f1..000000000000 --- a/modules/samples-operator-crd.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/configuring_samples_operator.adoc - - -[id="samples-operator-crd_{context}"] -= Accessing the Cluster Samples Operator configuration - -You can configure the Cluster Samples Operator by editing the file with the provided -parameters. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). - -.Procedure - -* Access the Cluster Samples Operator configuration: -+ -[source, terminal] ----- -$ oc edit configs.samples.operator.openshift.io/cluster -o yaml ----- -+ -The Cluster Samples Operator configuration resembles the following example: -+ -[source,yaml] ----- -apiVersion: samples.operator.openshift.io/v1 -kind: Config -... ----- diff --git a/modules/samples-operator-overview.adoc b/modules/samples-operator-overview.adoc deleted file mode 100644 index 8267afe0ac6a..000000000000 --- a/modules/samples-operator-overview.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/configuring_samples_operator.adoc - - -[id="samples-operator-overview_{context}"] -= Understanding the Cluster Samples Operator - -During installation, the Operator creates the default configuration object for -itself and then creates the sample image streams and templates, including quickstart templates. - -[NOTE] -==== -To facilitate image stream imports from other registries that require credentials, a cluster administrator can create any additional secrets that contain the content of a Docker `config.json` file in the `openshift` namespace needed for image import. -==== - -The Cluster Samples Operator configuration is a cluster-wide resource, and the deployment is contained within the `openshift-cluster-samples-operator` namespace. - -The image for the Cluster Samples Operator contains image stream and template definitions -for the associated {product-title} release. When each sample is created or updated, -the Cluster Samples Operator includes an annotation that denotes the version of -{product-title}. The Operator uses this annotation to ensure that each sample -matches the release version. Samples outside of its inventory are ignored, as -are skipped samples. Modifications to any samples that are managed by the -Operator, where that version annotation is modified or deleted, are reverted -automatically. - -[NOTE] -==== -The Jenkins images are part of the image payload from -installation and are tagged into the image streams directly. -==== - -The Cluster Samples Operator configuration resource includes a finalizer which cleans up -the following upon deletion: - -* Operator managed image streams. -* Operator managed templates. -* Operator generated configuration resources. -* Cluster status resources. - -Upon deletion of the samples resource, the Cluster Samples Operator recreates the -resource using the default configuration. - -[id="samples-operator-bootstrapped"] -== Cluster Samples Operator's use of management state - -The Cluster Samples Operator is bootstrapped as `Managed` by default or if global proxy is configured. In the `Managed` state, the Cluster Samples Operator is actively managing its resources and keeping the component active in order to pull sample image streams and images from the registry and ensure that the requisite sample templates are installed. - -Certain circumstances result in the Cluster Samples Operator bootstrapping itself as `Removed` including: - -* If the Cluster Samples Operator cannot reach link:https://registry.redhat.io[registry.redhat.io] after three minutes on initial start-up after a clean installation. -* If the Cluster Samples Operator detects it is on an IPv6 network. - -However, if the Cluster Samples Operator also detects an {product-title} global proxy is configured, it bypasses those checks. - -[IMPORTANT] -==== -IPv6 installations are not currently supported by link:https://registry.redhat.io[registry.redhat.io]. The Cluster Samples Operator pulls most of the sample image streams and images from link:https://registry.redhat.io[registry.redhat.io]. -==== - -[id="samples-operator-restricted-network-install"] -=== Restricted network installation - -Boostrapping as `Removed` when unable to access `registry.redhat.io` facilitates restricted network installations when the network restriction is already in place. Bootstrapping as `Removed` when network access is restricted allows the cluster administrator more time to decide if samples are desired, because the Cluster Samples Operator does not submit alerts that sample image stream imports are failing when the management state is set to `Removed`. When the Cluster Samples Operator comes up as `Managed` and attempts to install sample image streams, it starts alerting two hours after initial installation if there are failing imports. - -[id="samples-operator-restricted-network-install-with-access"] -=== Restricted network installation with initial network access - -Conversely, if a cluster that is intended to be a restricted network or disconnected cluster is first installed while network access exists, the Cluster Samples Operator installs the content from `registry.redhat.io` since it can access it. If you want the Cluster Samples Operator to still bootstrap as `Removed` in order to defer samples installation until you have decided which samples are desired, set up image mirrors, and so on, then follow the instructions for using the Samples Operator with an alternate registry and customizing nodes, both linked in the additional resources section, to override the Cluster Samples Operator default configuration and initially come up as `Removed`. - -You must put the following additional YAML file in the `openshift` directory created by `openshift-install create manifest`: - -.Example Cluster Samples Operator YAML file with `managementState: Removed` -[source,yaml] ----- -apiVersion: samples.operator.openshift.io/v1 -kind: Config -metadata: - name: cluster -spec: - architectures: - - x86_64 - managementState: Removed ----- - -[id="samples-operator-retries"] -== Cluster Samples Operator's tracking and error recovery of image stream imports - -After creation or update of a samples image stream, the Cluster Samples Operator monitors the progress of each image stream tag's image import. - -If an import fails, the Cluster Samples Operator retries the import through the image stream image import API, which is the same API used by the `oc import-image` command, approximately every 15 minutes until it sees the import succeed, or if -the Cluster Samples Operator's configuration is changed such that either the image stream is added to the `skippedImagestreams` list, or the management state is changed to `Removed`. diff --git a/modules/sandboxed-containers-about-sandboxing.adoc b/modules/sandboxed-containers-about-sandboxing.adoc deleted file mode 100644 index 534df9cf8a4d..000000000000 --- a/modules/sandboxed-containers-about-sandboxing.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/understanding_sandboxed_containers.adoc - -[id="about-sandboxing_{context}"] - -= About sandboxing diff --git a/modules/sandboxed-containers-building-blocks.adoc b/modules/sandboxed-containers-building-blocks.adoc deleted file mode 100644 index e9e1d674b423..000000000000 --- a/modules/sandboxed-containers-building-blocks.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/understanding_sandboxed_containers.adoc - -[id="sandboxed-containers-building-blocks_{context}"] - -= Sandboxed containers building blocks diff --git a/modules/sandboxed-containers-installing-operator-cli.adoc b/modules/sandboxed-containers-installing-operator-cli.adoc deleted file mode 100644 index dae4346f40b7..000000000000 --- a/modules/sandboxed-containers-installing-operator-cli.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="sandboxed-containers-installing-operator-cli_{context}"] - -= Installing the Sandboxed Containers Operator using the CLI diff --git a/modules/sandboxed-containers-installing-operator-web-console.adoc b/modules/sandboxed-containers-installing-operator-web-console.adoc deleted file mode 100644 index f2c74930c7bd..000000000000 --- a/modules/sandboxed-containers-installing-operator-web-console.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="sandboxed-containers-installing-operator-web-console_{context}"] - -= Installing the Sandboxed Containers Operator using the web console diff --git a/modules/sandboxed-containers-installing-operator.adoc b/modules/sandboxed-containers-installing-operator.adoc deleted file mode 100644 index dcca4a20e13f..000000000000 --- a/modules/sandboxed-containers-installing-operator.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="installing-sandboxed-container-operator_{context}"] - -= Installing the Sandboxed Containers Operator diff --git a/modules/sandboxed-containers-limitations.adoc b/modules/sandboxed-containers-limitations.adoc deleted file mode 100644 index db8243454fb1..000000000000 --- a/modules/sandboxed-containers-limitations.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/understanding_sandboxed_containers.adoc - -[id="sandboxed-containers-limitations_{context}"] - -= Limitations diff --git a/modules/sandboxed-containers-os-extensions.adoc b/modules/sandboxed-containers-os-extensions.adoc deleted file mode 100644 index 709a3bea17e8..000000000000 --- a/modules/sandboxed-containers-os-extensions.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/understanding_sandboxed_containers.adoc - -[id="sandboxed-containers-os-extensions_{context}"] - -= OS extensions diff --git a/modules/sandboxed-containers-preparing-openshift-cluster.adoc b/modules/sandboxed-containers-preparing-openshift-cluster.adoc deleted file mode 100644 index 97650a4876ab..000000000000 --- a/modules/sandboxed-containers-preparing-openshift-cluster.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="sandboxed-containers-preparing-openshift-cluster_{context}"] - -= Preparing your cluster for OpenShift sandboxed containers diff --git a/modules/sandboxed-containers-scheduling-workloads.adoc b/modules/sandboxed-containers-scheduling-workloads.adoc deleted file mode 100644 index a2fa188c63c0..000000000000 --- a/modules/sandboxed-containers-scheduling-workloads.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="sandboxed-containers-scheduling-workloads_{context}"] - -= Scheduling sandboxed containers workloads diff --git a/modules/sandboxed-containers-selecting-nodes.adoc b/modules/sandboxed-containers-selecting-nodes.adoc deleted file mode 100644 index ff180d6cdefc..000000000000 --- a/modules/sandboxed-containers-selecting-nodes.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="sandboxed-containers-selecting-nodes_{context}"] - -= Selecting nodes for OpenShift sandboxed containers diff --git a/modules/sandboxed-containers-triggering-installation-kata-runtime.adoc b/modules/sandboxed-containers-triggering-installation-kata-runtime.adoc deleted file mode 100644 index 10f6c8dcc070..000000000000 --- a/modules/sandboxed-containers-triggering-installation-kata-runtime.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="sandboxed-containers-triggering-installation-kata-runtime_{context}"] - -= Triggering the installation of the Kata runtime diff --git a/modules/sandboxed-containers-uninstalling-kata-runtime.adoc b/modules/sandboxed-containers-uninstalling-kata-runtime.adoc deleted file mode 100644 index bfd0c07155c6..000000000000 --- a/modules/sandboxed-containers-uninstalling-kata-runtime.adoc +++ /dev/null @@ -1,20 +0,0 @@ -//Module included in the following assemblies: -// -// *disabling-sandboxed-container-workloads.adoc - -[id="sandboxed-containers-uninstalling-kata-runtime_{context}"] - -= Uninstalling the Kata runtime - -This section describes how to remove and uninstall the `kata` runtime and all its related resources, such as CRI-O config and `RuntimeClass`, from from your cluster. - -.Procedure - -- Delete the `KataConfig` custom resource: -+ -[source,terminal] ----- -oc delete kataconfig <KataConfig_CR_Name> ----- - -The {sandboxed-containers} removes all resources that were initially created to enable the runtime on your cluster. After you run the command above, your cluster is restored to the state prior to the installation process. diff --git a/modules/sandboxed-containers-viewing-workloads-from-cli.adoc b/modules/sandboxed-containers-viewing-workloads-from-cli.adoc deleted file mode 100644 index 1fed0137a6fa..000000000000 --- a/modules/sandboxed-containers-viewing-workloads-from-cli.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="sandboxed-containers-viewing-workloads-from-cli_{context}"] - -= Viewing sandboxed containers workloads from the CLI diff --git a/modules/sandboxed-containers-viewing-workloads-from-web-console.adoc b/modules/sandboxed-containers-viewing-workloads-from-web-console.adoc deleted file mode 100644 index 88db81b5c433..000000000000 --- a/modules/sandboxed-containers-viewing-workloads-from-web-console.adoc +++ /dev/null @@ -1,7 +0,0 @@ -//Module included in the following assemblies: -// -// * sandboxed_containers/deploying_sandboxed_containers.adoc - -[id="sandboxed-containers-viewing-workloads-from-web-console_{context}"] - -= Viewing sandboxed containers workloads from the web console diff --git a/modules/save-generated-policies-ng20.adoc b/modules/save-generated-policies-ng20.adoc new file mode 100644 index 000000000000..2a0b114b483e --- /dev/null +++ b/modules/save-generated-policies-ng20.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="save-generated-policies-ng20_{context}"] += Saving generated policies in the network graph + +[role="_abstract"] +You can download and save the generated network policies from {product-title-short}. +Use this option to download policies so that you can commit the policies into a version control system such as Git. + +.Procedure +* After generating a network policy, click the *Download YAML* icon in the *Network Policy Simulator* panel. diff --git a/modules/sbom-about.adoc b/modules/sbom-about.adoc new file mode 100644 index 000000000000..f2220cb1be9f --- /dev/null +++ b/modules/sbom-about.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scanner-generate-sbom.adoc +:_mod-docs-content-type: CONCEPT +[id="sbom-about_{context}"] += About SBOMs + +A Software Bill of Materials (SBOM) is a digital record that lists the components of a piece of software and their origins. Organizations can use SBOMs to locate the presence of vulnerable software packages and components and respond more quickly to mitigate the risk. Additionally, being able to generate SBOMs assists organizations in complying with link:https://www.nist.gov/itl/executive-order-14028-improving-nations-cybersecurity[Executive Order 14028: Improving the Nations Cybersecurity]. + +SBOMs can contain different types of information, depending on the methods of data collection and how they are generated. The Cybersecurity & Infrastructure Security Agency (CISA) provides a document, link:https://www.cisa.gov/resources-tools/resources/types-software-bill-materials-sbom[Types of Software Bill of Materials (SBOM)], that summarizes the types of SBOMs. + +The type of SBOM that {product-title-short} generates is "Analyzed." CISA notes that these types of SBOMs are created through an analysis of artifacts such as executables, packages, containers, and virtual machine images. Analyzed SBOMs provide the following benefits, as summarized by CISA: + +* They can provide information about software without an active development environment. +* They can be generated without access to the build process. +* You can use them to discover hidden dependencies that might be missed by other tools. + +The SBOM generated by {product-title-short} is in link:https://spdx.org/rdf/terms/[System Package Data Exchange (SPDX) 2.3] format. diff --git a/modules/sbom-generate.adoc b/modules/sbom-generate.adoc new file mode 100644 index 000000000000..3ab6cad4d05e --- /dev/null +++ b/modules/sbom-generate.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/scanner-generate-sbom.adoc + +:_mod-docs-content-type: CONCEPT +[id="sbom-generate_{context}"] += Generate SBOMs + +You can generate a Software Bill of Materials (SBOM) by using the {rh-rhacs-first} portal, `roxctl` CLI, or API. \ No newline at end of file diff --git a/modules/scan-inactive-images.adoc b/modules/scan-inactive-images.adoc new file mode 100644 index 000000000000..27e5afcb6c2a --- /dev/null +++ b/modules/scan-inactive-images.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="scan-inactive-images_{context}"] += Scanning inactive images + +{rh-rhacs-first} scans all active (deployed) images every 4 hours and updates the image scan results to reflect the latest vulnerability definitions. +//TODO: add link to Re-scanning images. + +You can also configure {product-title-short} to scan inactive (not deployed) images automatically. + +.Procedure + +. In the {product-title-short} portal, click *Vulnerability Management* -> *Results*. +. Click *More Views* -> *Inactive images*. +. Optional: Choose the appropriate method to view the component and advisory data associated with a CVE: +** To view the component and advisory data associated with a CVE from the list of CVEs, complete the following steps: +... Click the *<number> CVEs* tab. +... In the list of CVEs, click a CVE to do any of the following tasks: +**** To view the component and advisory data associated with an image: +..... Click the *<number> Images* tab. +..... Expand the image. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +**** To view the component and advisory data associated with a deployment: +..... Click the *<number> Deployments* tab. +..... Expand the deployment. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +** To view the component and advisory data associated with a CVE from the list of images, complete the following steps: +... Click the *<number> Images* tab. +... In the list of images, click an image. +... To view the component and advisory data associated with a CVE, expand the CVE. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +** To view the component and advisory data associated with a CVE from the list of deployments, complete the following steps: +... Click the *<number> Deployments* tab. +... In the list of deployments, click a deployment. +... To view the component and advisory data associated with a CVE, expand the CVE. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +. Click *Manage watched images*. +. In the *Image name* field, enter the fully-qualified image name that begins with the registry and ends with the image tag, for example, `docker.io/library/nginx:latest`. +. Click *Add image to watch list*. +. Optional: To remove a watched image, locate the image in the *Manage watched images* window, and click *Remove watch*. ++ +[IMPORTANT] +==== +In the {product-title-short} portal, click *Platform Configuration* -> *System Configuration* to view the data retention configuration. + +All the data related to the image removed from the watched image list continues to appear in the {product-title-short} portal for the number of days mentioned on the *System Configuration* page and is only removed after that period is over. +==== +. Click *Close* to return to the *Inactive images* page. \ No newline at end of file diff --git a/modules/scanning-images-by-using-secured-clusters.adoc b/modules/scanning-images-by-using-secured-clusters.adoc new file mode 100644 index 000000000000..25c2bab8b341 --- /dev/null +++ b/modules/scanning-images-by-using-secured-clusters.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="scanning-images-by-using-secured-clusters_{context}"] += Scanning images by using secured clusters + +To scan images by using the secured clusters instead of the Central services, you can use the delegated image scanning feature. + +A new delegated scanning configuration specifies the registries from which you can delegate image scans. For images that Sensor observes, you can use the delegated registry configuration to delegate scans from no registries, all registries, or specific registries. + +To enable delegation of scans by using the `roxctl` CLI, Jenkins plugin, or API, you must also specify a destination cluster and source registry. + +.Prerequisites + +* You have installed Scanner in the secured cluster to scan images. ++ +[NOTE] +==== +Enabling Scanner is supported on {ocp} and Kubernetes secured clusters. +==== + +.Procedure + +. In the {product-title-short} portal, click *Platform Configuration -> Clusters*. +. In the *Clusters* view header, click *Delegated scanning*. +. In the *Delegated Image Scanning* page, provide the following information: + +** *Delegate scanning for*: To choose the scope of the image delegation, select one of the following options: +*** *None*: The default option. This option specifies that the secured clusters do _not_ scan any images, except for images from the integrated OpenShift image registry. +*** *All registries*: This option indicates that the secured clusters scan all the images. +*** *Specified registries*: This option specifies the images that secured clusters should scan based on the registries list. + +** *Select default cluster to delegate to*: From the drop-down list, select the name of the default cluster. The default cluster processes the scan requests coming from the command-line interface (CLI) and API. This is optional and you can select `None` if required. + +** Optional: To specify the source registry and destination cluster details, click *Add registry*. ++ +For example, specify the source registry as `example.com`, and select `remote` from the drop-down list for the destination cluster. You can add more than one source registry and destination cluster if required. ++ +[IMPORTANT] +==== +You can select the destination cluster as `None` if the scan requests are not coming from the CLI and API. +==== + +. Click *Save*. + +Image integrations are now synchronized between Central and Sensor, and Sensor captures pull secrets from each namespace. Sensor then uses these credentials to authenticate to the image registries. \ No newline at end of file diff --git a/modules/scanning-images.adoc b/modules/scanning-images.adoc new file mode 100644 index 000000000000..af174c30c8e2 --- /dev/null +++ b/modules/scanning-images.adoc @@ -0,0 +1,187 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc +:_mod-docs-content-type: CONCEPT +[id="scanning-images_{context}"] += Scanning images + +[role="_abstract"] + +Scanner V4 is the default scanner for {product-title-short}. When scanning, it performs the following actions: + +* Central requests the Scanner V4 Indexer to download and index (analyze) given images. +* Scanner V4 Indexer pulls image metadata from registries to determine the layers of the image, and downloads each previously unindexed layer. +* Scanner V4 Indexer requests mapping files from Central that assist the indexing process. Scanner V4 Indexer produces in an index report. +* Central requests that Scanner V4 Matcher match given images to known vulnerabilities. This process results in the final scan result: a vulnerability report. Scanner V4 Matcher requests the latest vulnerabilities from Central. +* Scanner V4 Matcher requests the results of the image indexing, the index report, from Scanner V4 Indexer. It then uses the report to determine relevant vulnerabilities. This interaction occurs only when the image is indexed in the Central cluster. This interaction does not occur when Scanner V4 is matching vulnerabilities for images indexed in secured clusters. +* The Indexer stores data in the Scanner V4 DB that is related to the indexing results to ensure that image layers are only downloaded and indexed once. This prevents unnecessary network traffic and other resource utilization. +* When secured cluster scanning is enabled, Sensor requests Scanner V4 to index images. Scanner V4 Indexer requests mapping files from Sensor that assist the indexing process unless Central exists in the same namespace. In that case, Central is contacted instead. + +[id="common-scanner-warning-messages_{context}"] +== Understanding and addressing common Scanner warning messages + +When scanning images with {rh-rhacs-first}, you might see the `CVE DATA MAY BE INACCURATE` warning message. +Scanner displays this message when it cannot retrieve complete information about the operating system or other packages in the image. + +The following table shows some common Scanner warning messages: + +.Warning messages +[%autowidth] +|=== +| *Message* | *Description* + +|`Unable to retrieve the OS CVE data, only Language CVE data is available` +|Indicates that Scanner does not officially support the base operating system of the image; therefore, it cannot retrieve CVE data for the operating system-level packages. + +|`Stale OS CVE data` +|Indicates that the base operating system of the image has reached end-of-life, which means the vulnerability data is outdated. For example, Debian 8 and 9. + +For more information about the files needed to identify the components in the images, see xref:../operating/examine-images-for-vulnerabilities.adoc#examine-images-for-vulnerabilities[Examining images for vulnerabilities]. + + +|`Failed to get the base OS information` +|Indicates that Scanner scanned the image, but was unable to determine the base operating system used for the image. + +|`Failed to retrieve metadata from the registry` +|Indicates that the target registry is unreachable on the network. The cause could be a firewall blocking `docker.io`, or an authentication issue preventing access. + +To analyze the root cause, create a special registry integration for private registries or repositories to get the pod logs for {product-title-short} Central. For instructions on how to do this, see xref:../integration/integrate-with-image-registries.adoc[Integrating with image registries]. + +|`Image out of scope for Red{nbsp}Hat Vulnerability Scanner Certification` +a|Indicates that Scanner scanned the image, but the image is old and does not fall within the scope of Red{nbsp}Hat Scanner Certification. For more information, see https://redhat-connect.gitbook.io/partner-guide-red-hat-vulnerability-scanner-cert/[Partner Guide for Red{nbsp}Hat Vulnerability Scanner Certification]. + +IMPORTANT: If you are using a Red{nbsp}Hat link:https://catalog.redhat.com/software/containers/explore[container image], consider using a base image newer than June 2020. + +|=== + +[id="supported-operating-systems_{context}"] +== Supported operating systems + +The supported platforms listed in this section are the distributions in which Scanner identifies vulnerabilities, and it is different from the supported platforms on which you can install {product-title}. + +Scanner identifies vulnerabilities in images that contain the following Linux distributions. For more information about the vulnerability databases used, see "Vulnerability sources" in "{product-title-short} Architecture". + +[cols="1,3",options="header"] +|=== +| Distribution | Version + +| link:https://www.alpinelinux.org/[Alpine Linux] +| `alpine:3.2`^[1]^,`alpine:3.3`, `alpine:3.4`, `alpine:3.5`, `alpine:3.6`, `alpine:3.7`, `alpine:3.8`, `alpine:3.9`, `alpine:3.10`, `alpine:3.11`, `alpine:3.12`, `alpine:3.13`, `alpine:3.14`, `alpine:3.15`, `alpine:3.16`, `alpine:3.17`, `alpine:3.18`, `alpine:3.19`, `alpine:3.20`, `alpine:3.21`^[2]^, `alpine:3.22`^[2]^, `alpine:edge` + +| link:https://aws.amazon.com/amazon-linux-ami[Amazon Linux] +| `amzn:2018.03`, `amzn:2`, `amzn:2023`^[2]^ + +| CentOS +| `centos:6`^[1]^, `centos:7`^[1]^, `centos:8`^[1]^ + +| link:https://www.debian.org/releases/[Debian] +| `debian:11`, `debian:12`, `debian:13`^[2]^, `debian:unstable`^[1]^, link:https://github.com/GoogleContainerTools/distroless[`Distroless`] + +The following vulnerability sources are not updated by the vendor: +`debian:8`^[1]^, `debian:9`^[1]^, `debian:10`^[1]^ + +| link:https://www.oracle.com/linux/[Oracle Linux] +| `ol:5`^[2]^, `ol:6`^[2]^, `ol:7`^[2]^, `ol:8`^[2]^, `ol:9`^[2]^ + +| link:https://vmware.github.io/photon/assets/files/html/3.0/Introduction.html[Photon OS] +| `photon:1.0`^[2]^, `photon:2.0`^[2]^, `photon:3.0`^[2]^ + +| link:https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux[{op-system-base-full}] +| `rhel:6`^[3]^, `rhel:7`^[3]^, `rhel:8`^[3]^, `rhel:9`, `rhel:10`^[2]^ + +| link:https://www.suse.com/[SUSE] +| `sles:11`^[2]^, `sles:12`^[2]^, `sles:15`^[2]^, `opensuse-leap:15.5`^[2]^, `opensuse-leap:15.6`^[2]^ + +| link:http://releases.ubuntu.com/[Ubuntu] +| `ubuntu:14.04`, `ubuntu:16.04`, `ubuntu:18.04`, `ubuntu:20.04`, `ubuntu:22.04`, `ubuntu:24.04`, ubuntu:25.04`^[2]^ + +The following vulnerability sources are not updated by the vendor: +`ubuntu:12.04`^[1]^, `ubuntu:12.10`^[1]^, `ubuntu:13.04`^[1]^, `ubuntu:14.10`^[1]^, `ubuntu:15.04`^[1]^, `ubuntu::15.10`^[1]^, `ubuntu::16.10`^[1]^, `ubuntu:17.04`^[1]^, `ubuntu:17.10`^[1]^, `ubuntu:18.10`^[1]^, `ubuntu:19.04`^[1]^, `ubuntu:19.10`^[1]^, `ubuntu:20.10`^[1]^, `ubuntu:21.04`^[1]^, `ubuntu:21.10`^[1]^, `ubuntu:22.10`^[1]^, `ubuntu:23.04`^[1]^, `ubuntu:23.10`^[1]^, `ubuntu:24.10`^[1]^ +|=== +. Only supported in the StackRox Scanner. +. Only supported in Scanner V4. +. Images older than June 2020 are not supported in Scanner V4. + +[NOTE] +==== +Scanner does not support the Fedora operating system because Fedora does not maintain a vulnerability database. +However, Scanner still detects language-specific vulnerabilities in Fedora-based images. +==== + +[id="supported-package-formats_{context}"] +== Supported package formats + +Scanner can check for vulnerabilities in images that use the following package formats: + +[cols="2",options="header"] +|=== +| Package format | Package managers + +| apk +| apk + +| dpkg +| apt, dpkg + +| rpm +| dnf, microdnf, rpm, yum +|=== + +[id="supported-programming-languages_{context}"] +== Supported programming languages + +Scanner can check for vulnerabilities in dependencies for the following programming languages: + +[cols="1,3",options="header"] +|=== +| Programming language | Package format + +| Go^[1]^ +| Binaries: The standard library version used to build the binary is analyzed. If the binaries are built with module support (go.mod), then the dependencies are also analyzed. + +| Java +| JAR, WAR, EAR, JPI, HPI + +| JavaScript +| package.json + +| Python +| egg, wheel + +| Ruby +| gem +|=== +. Only supported in Scanner V4. + +[id="supported-layer-compression-formats_{context}"] +== Supported layer compression formats + +Container image layers are `.tar` file archives that might be compressed or uncompressed. StackRox Scanner and Scanner V4 support different formats as shown in the following table: + +[cols="1,1,1",options="header"] +|=== +| Format | Stackrox Scanner Support | Scanner V4 Support +| No compression +| Yes +| Yes + +|bzip2 | Yes | Yes + +|gzip | Yes | Yes + +|xz | Yes | No + +|zstd | No | Yes + +|=== + + +[id="supported-runtimes-frameworks_{context}"] +== Supported runtimes and frameworks + +Beginning from {product-title} 3.0.50 (Scanner version 2.5.0), the StackRox Scanner identifies vulnerabilities in the following developer platforms: + +* .NET Core +* ASP.NET Core + +These are not supported by Scanner V4. diff --git a/modules/schedules-page-overview.adoc b/modules/schedules-page-overview.adoc new file mode 100644 index 000000000000..4f223acc5dbc --- /dev/null +++ b/modules/schedules-page-overview.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/scheduling-compliance-scans-and-assessing-profile-compliance.adoc + +:_mod-docs-content-type: REFERENCE +[id="schedules-page-overview_{context}"] += OpenShift Schedules page overview + +The *OpenShift Schedules* page lists all the scan schedules and organizes information into the following groups: + +Name:: The unique identifier or title given to each scan schedule. +Schedule:: Indicates the frequency and timing of the scan. +Last scanned:: Indicates the date and time of the most recent scan for that schedule. +Clusters:: Lists the clusters included in the scan schedule. +Profiles:: Identifies the one or more profiles applied in the compliance scan. +My last job status:: Shows the status of your job. ++ +The following values are associated with the job status: ++ +`Waiting`::: The report job is in the queue. +`Preparing`::: The report job is being processed. +`Report ready for download`::: The report is ready and available for download. +`Partial report ready for download`::: A report is partially complete and ready for download. +`Report successfully sent`::: The report was successfully emailed. +`Partial report successfully sent`::: A report is partially complete and was successfully emailed. +`Report failed to generate`::: There was an issue with the report job. Hover to view the error message. +`None`::: There are no recent jobs available. + +To view the configuration details and report job status associated with a compliance scan, select the compliance scan you created. \ No newline at end of file diff --git a/modules/search-attributes.adoc b/modules/search-attributes.adoc new file mode 100644 index 000000000000..574cb0ff45f6 --- /dev/null +++ b/modules/search-attributes.adoc @@ -0,0 +1,285 @@ +// Module included in the following assemblies: +// +// * operating/search-filter.adoc +:_mod-docs-content-type: CONCEPT +[id="search-attributes_{context}"] += Search attributes + +Following is the list of search attributes that you can use while searching and filtering in {product-title}. + +[cols="1,3"] +|=== +| *Attribute* | *Description* + +| Add Capabilities +| Provides the container with additional Linux capabilities, for instance the ability to modify files or perform network operations. + +| Annotation +| Arbitrary non-identifying metadata attached to an orchestrator object. + +| CPU Cores Limit +| Maximum number of cores that a resource is allowed to use. + +| CPU Cores Request +| Minimum number of cores to be reserved for a given resource. + +| CVE +| Common Vulnerabilities and Exposures, use it with specific CVE numbers. + +| CVSS +| Common Vulnerability Scoring System, use it with the CVSS score and greater than ( > ), less than ( < ), or equal to ( = ) symbols. + +| Category +| Policy categories include DevOps Best Practices, Security Best Practices, Privileges, Vulnerability Management, Multiple, and any custom policy categories that you create. +//TODO: Add link to custom policy categories topic + +| Cert Expiration +| Certificate expiration date. + +| Cluster +| Name of a Kubernetes or {ocp} cluster. + +| Cluster ID +| Unique ID for a Kubernetes or {ocp} cluster. + +| Cluster Role +| Use `true` to search for cluster-wide roles and `false` for namespace-scoped roles. + +| Component +| Software (daemond, docker), objects (images, containers, services), registries (repository for Docker images). + +| Component Count +| Number of components in the image. + +| Component version +| The version of software, objects, or registries. + +| Created Time +| Time and date when the secret object was created. + +| Deployment +| Name of the deployment. + +| Deployment Type +| The type of Kubernetes controller on which the deployment is based. + +| Description +| Description of the deployment. + +| Dockerfile Instruction Keyword +| Keyword in the Dockerfile instructions in an image. + +| Dockerfile Instruction Value +| Value in the Dockerfile instructions in an image. + +| Drop Capabilities +| Linux capabilities that have been dropped from the container. +For example `CAP_SETUID` or `CAP_NET_RAW`. + +| Enforcement +| Type of enforcement assigned to the deployment. +For example, `None`, `Scale to Zero Replicas`, or `Add an Unsatisfiable Node Constraint`. + +| Environment Key +| Key portion of a label key-value string that is metadata for further identifying and organizing the environment of a container. + +| Environment Value +| Value portion of a label key-value string that is metadata for further identifying and organizing the environment of a container. + +| Exposed Node Port +| Port number of the exposed node port. + +| Exposing Service +| Name of the exposed service. + +| Exposing Service Port +| Port number of the exposed service. + +| Exposure Level +| The type of exposure for a deployment port, for example `external` or `node`. + +| External Hostname +| The hostname for an external port exposure for a deployment. + +| External IP +| The IP address for an external port exposure for a deployment. + +| Fixable CVE Count +| Number of fixable CVEs on an image. + +| Fixed By +| The version string of a package that fixes a flagged vulnerability in an image. + +| Image +| The name of the image. + +| Image Command +| The command specified in the image. + +| Image Created Time +| The time and date when the image was created. + +| Image Entrypoint +| The entrypoint command specified in the image. + +| Image Pull Secret +| The name of the secret to use when pulling the image, as specified in the deployment. + +| Image Pull Secret Registry +| The name of the registry for an image pull secret. + +| Image Registry +| The name of the image registry. + +| Image Remote +| Indication of an image that is remotely accessible. + +| Image Scan Time +| The time and date when the image was last scanned. + +| Image Tag +| Identifier for an image. + +| Image Users +| Name of the user or group that a container image is configured to use when it runs. + +| Image Volumes +| Names of the configured volumes in the container image. + +| Inactive Deployment +| Use `true` to search for inactive deployments and `false` for active deployments. + +| Label +| The key portion of a label key-value string that is metadata for further identifying and organizing images, containers, daemons, volumes, networks, and other resources. + +| Lifecycle Stage +| The type of lifecycle stage where this policy is configured or alert was triggered. + +| Max Exposure Level +| For a deployment, the maximum level of network exposure for all given ports/services. + +| Memory Limit (MB) +| Maximum amount of memory that a resource is allowed to use. + +| Memory Request (MB) +| Minimum amount of memory to be reserved for a given resource. + +| Namespace +| The name of the namespace. + +| Namespace ID +| Unique ID for the containing namespace object on a deployment. + +| Node +| Name of a node. + +| Node ID +| Unique ID for a node. + +| Pod Label +| Single piece of identifying metadata attached to an individual pod. + +| Policy +| The name of the security policy. +//TODO: Add link to the security policy topic + +| Port +| Port numbers exposed by a deployment. + +| Port Protocol +| IP protocol such as TCP or UDP used by exposed port. + +| Priority +| Risk priority for a deployment. +(Only available in *Risks* view.) + +| Privileged +| Use `true` to search for privileged running deployments, or `false` otherwise. + +| Process Ancestor +| Name of any parent process for a process indicator in a deployment. + +| Process Arguments +| Command arguments for a process indicator in a deployment. + +| Process Name +| Name of the process for a process indicator in a deployment. + +| Process Path +| Path to the binary in the container for a process indicator in a deployment. + +| Process UID +| Unix user ID for the process indicator in a deployment. + +| Read Only Root Filesystem +| Use `true` to search for containers running with the root file system configured as read only. + +| Role +| Name of a Kubernetes RBAC role. + +| Role Binding +| Name of a Kubernetes RBAC role binding. + +| Role ID +| Role ID to which a Kubernetes RBAC role binding is bound. + +| Secret +| Name of the secret object that holds the sensitive information. + +| Secret Path +| Path to the secret object in the file system. + +| Secret Type +| Type of the secret, for example, certificate or RSA public key. + +| Service Account +| Service account name for a service account or deployment. + +| Severity +| Indication of level of importance of a violation: Critical, High, Medium, Low. + +| Subject +| Name for a subject in Kubernetes RBAC. + +| Subject Kind +| Type of subject in Kubernetes RBAC, such as `SERVICE_ACCOUNT`, `USER` or `GROUP`. + +| Taint Effect +| Type of taint currently applied to a node. + +| Taint Key +| Key for a taint currently applied to a node. + +| Taint Value +| Allowed value for a taint currently applied to a node. + +| Toleration Key +| Key for a toleration applied to a deployment. + +| Toleration Value +| Value for a toleration applied to a deployment. + +| Violation +| A notification displayed in the *Violations* page when the conditions specified by a policy have not been met. + +| Violation State +| Use it to search for resolved violations. + +| Violation Time +| Time and date that a violation first occurred. + +| Volume Destination +| Mount path of the data volume. + +| Volume Name +| Name of the storage. + +| Volume ReadOnly +| Use `true` to search for volumes that are mounted as read only. + +| Volume Source +| Indicates the form in which the volume is provisioned (for example, `persistentVolumeClaim` or `hostPath`). + +| Volume Type +| The type of volume. +|=== diff --git a/modules/search-autocomplete.adoc b/modules/search-autocomplete.adoc new file mode 100644 index 000000000000..31fa3746ffdb --- /dev/null +++ b/modules/search-autocomplete.adoc @@ -0,0 +1,8 @@ +// Module included in the following assemblies: +// +// * operating/search-filter.adoc +:_mod-docs-content-type: CONCEPT +[id="search-autocomplete_{context}"] += Search autocomplete + +As you enter your query, {product-title} automatically displays relevant suggestions for the attributes and the search terms. \ No newline at end of file diff --git a/modules/search-syntax.adoc b/modules/search-syntax.adoc new file mode 100644 index 000000000000..b03e796963a9 --- /dev/null +++ b/modules/search-syntax.adoc @@ -0,0 +1,58 @@ +// Module included in the following assemblies: +// +// * operating/search-filter.adoc +:_mod-docs-content-type: CONCEPT +[id="search-syntax_{context}"] += Search syntax + +A search query is made up of two parts: + +* An attribute that identifies the resource type you want to search for. +* A search term that finds the matching resource. + +For example, to find all violations in the `visa-processor` deployment, the search query is `Deployment:visa-processor`. In this search query, `Deployment` is the attribute and `visa-processor` is the search term. + +[NOTE] +==== +You must select an attribute before you can use search terms. However, in some views, such as the *Risk* view and the *Violations* view, {product-title} automatically applies the relevant attribute based on the search term you enter. +==== + +* You can use multiple attributes in your query. When you use more than one attribute, the results only include the items that match all attributes. ++ +.Example +When you search for `Namespace:frontend CVE:CVE-2018-11776`, it returns only those resources which violate CVE-2018-11776 in the `frontend` namespace. + +* You can use more than one search term with each attribute. When you use more than one search term, the results include all items that match any of the search terms. ++ +.Example +If you use the search query `Namespace: frontend backend`, it returns matching results from the namespace `frontend` or `backend`. + +* You can combine multiple attribute and search term pairs. ++ +.Example +The search query `Cluster:production Namespace:frontend CVE:CVE-2018-11776` returns all resources which violate CVE-2018-11776 in the `frontend` namespace in the `production` cluster. + +* Search terms can be part of a word, in which case {product-title} returns all matching results. ++ +.Example +If you search for `Deployment:def`, the results include all deployments starting with `def`. + +* To explicitly search for a specific term, use the search terms inside quotes. ++ +.Example +When you search for `Deployment:"def"`, the results only include the deployment `def`. + +* You can also use regular expressions by using `r/` before your search term. ++ +.Example +When you search for `Namespace:r/st.*x`, the results include matches from namespace `stackrox` and `stix`. + +* Use `!` to indicate the search terms that you do not want in results. ++ +.Example +If you search for `Namespace:!stackrox`, the results include matches from all namespaces except the `stackrox` namespace. + +* Use the comparison operators `>`, `<`, `=`, `>=`, or `\<=` to match a specific value or range of values. ++ +.Example +If you search for `CVSS:>=6`, the results include all vulnerabilities with Common Vulnerability Scoring System (CVSS) score 6 or higher. diff --git a/modules/secured-cluster-configuration-options-operator.adoc b/modules/secured-cluster-configuration-options-operator.adoc new file mode 100644 index 000000000000..d31532200a52 --- /dev/null +++ b/modules/secured-cluster-configuration-options-operator.adoc @@ -0,0 +1,327 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-secured-cluster-config-options-ocp.adoc +:_mod-docs-content-type: CONCEPT +[id="secured-cluster-configuration-options-operator_{context}"] += Secured Cluster services configuration options + +When you create a Central instance, the Operator lists the following configuration options for the `Central` custom resource. + +[id="required-configuration-settings_{context}"] +== Required Configuration Settings + +[cols="1,3"] +|=== +| Parameter | Description + +| `centralEndpoint` +| The endpoint of Central instance to connect to, including the port number. +If using a non-gRPC capable load balancer, use the WebSocket protocol by prefixing the endpoint address with `wss://`. +If you do not specify a value for this parameter, Sensor attempts to connect to a Central instance running in the same namespace. + +| `clusterName` +| The unique name of this cluster, which shows up in the {product-title-short} portal. +After you set the name by using this parameter, you cannot change it again. +To change the name, you must delete and re-create the object. + +|=== + +[id="admission-controller-settings_{context}"] +== Admission controller settings + +[cols="1,3"] +|=== +| Parameter | Description + +| `admissionControl.listenOnCreates` +| Specify `true` to enable preventive policy enforcement for object creations. +The default value is `true`. + +| `admissionControl.listenOnEvents` +| Specify `true` to enable monitoring and enforcement for Kubernetes events, such as `port-forward` and `exec` events. +It is used to control access to resources through the Kubernetes API. +The default value is `true`. + +| `admissionControl.listenOnUpdates` +| Specify `true` to enable preventive policy enforcement for object updates. +It will not have any effect unless `Listen On Creates` is set to `true` as well. +The default value is `true`. + +| `admissionControl.nodeSelector` +| If you want this component to only run on specific nodes, you can configure a node selector using this parameter. + +| `admissionControl.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Admission Control. This parameter is mainly used for infrastructure nodes. + +| `admissionControl.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `admissionControl.resources.limits` +| Use this parameter to override the default resource limits for the admission controller. + +| `admissionControl.resources.requests` +| Use this parameter to override the default resource requests for the admission controller. + +| `admissionControl.bypass` +a| Use one of the following values to configure the bypassing of admission controller enforcement: + + * `BreakGlassAnnotation` to enable bypassing the admission controller via the `admission.stackrox.io/break-glass` annotation. + * `Disabled` to disable the ability to bypass admission controller enforcement for the secured cluster. + +The default value is `BreakGlassAnnotation`. + +| `admissionControl.contactImageScanners` +a| Use one of the following values to specify if the admission controller must connect to the image scanner: + + * `ScanIfMissing` if the scan results for the image are missing. + * `DoNotScanInline` to skip scanning the image when processing the admission request. + +The default value is `DoNotScanInline`. + +| `admissionControl.timeoutSeconds` +| Use this parameter to specify the maximum number of seconds {product-title-short} must wait for an admission review before marking it as fail open. If the admission webhook does not receive information that it is requesting before the end of the timeout period, it fails, but in fail open status, it still allows the operation to succeed. For example, the admission controller would allow a deployment to be created even if a scan had timed out and {product-title-short} could not determine if the deployment violated a policy. Beginning in release 4.5, Red{nbsp}Hat reduced the default timeout setting for the {product-title-short} admission controller webhooks from 20 seconds to 10 seconds, resulting in an effective timeout of 12 seconds within the `ValidatingWebhookConfiguration`. This change does not negatively affect {ocp} users because {ocp} caps the timeout at 13 seconds. +|=== + +[id="scanner-configuration-settings_{context}"] +== Scanner configuration settings for the Operator + +Use Scanner configuration settings to modify the local cluster scanner for the integrated OpenShift image registry. + +[cols="1,3"] +|=== +| Parameter | Description + +| `scanner.analyzer.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force Scanner to only schedule on nodes with the specified label. + +| `scanner.analyzer.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner. + +| `scanner.analyzer.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `scanner.analyzer.resources.requests.memory` +| The memory request for the Scanner container. Use this parameter to override the default value. + +| `scanner.analyzer.resources.requests.cpu` +| The CPU request for the Scanner container. Use this parameter to override the default value. + +| `scanner.analyzer.resources.limits.memory` +| The memory limit for the Scanner container. Use this parameter to override the default value. + +| `scanner.analyzer.resources.limits.cpu` +| The CPU limit for the Scanner container. Use this parameter to override the default value. + +| `scanner.analyzer.scaling.autoscaling` +| If you set this option to `Disabled`, {product-title} disables autoscaling on the Scanner deployment. The default value is `Enabled`. + +| `scanner.analyzer.scaling.minReplicas` +| The minimum number of replicas for autoscaling. The default value is `2`. + +| `scanner.analyzer.scaling.maxReplicas` +| The maximum number of replicas for autoscaling. The default value is `5`. + +| `scanner.analyzer.scaling.replicas` +| The default number of replicas. The default value is `3`. + +| `scanner.analyzer.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner. + +| `scanner.db.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force Scanner DB to only schedule on nodes with the specified label. + +| `scanner.db.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `scanner.db.resources.requests.memory` +| The memory request for the Scanner DB container. Use this parameter to override the default value. + +| `scanner.db.resources.requests.cpu` +| The CPU request for the Scanner DB container. Use this parameter to override the default value. + +| `scanner.db.resources.limits.memory` +| The memory limit for the Scanner DB container. Use this parameter to override the default value. + +| `scanner.db.resources.limits.cpu` +| The CPU limit for the Scanner DB container. Use this parameter to override the default value. + +| `scanner.db.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner DB. + +| `scanner.scannerComponent` +| If you set this option to `Disabled`, {product-title} does not deploy the Scanner deployment. Do not disable the Scanner on {ocp} clusters. The default value is `AutoSense`. + +| `scannerV4.db.nodeSelector` +| If you want this component to only run on specific nodes, you can use this parameter to configure a node selector. + +| `scannerV4.db.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner V4 DB. This parameter is mainly used for infrastructure nodes. + +| `scannerV4.db.resources.limits` +| Use this parameter to override the default resource limits for Scanner V4 DB. + +| `scannerV4.db.resources.requests` +| Use this parameter to override the default resource requests for Scanner V4 DB. + +| `scannerV4.db.persistence.persistentVolumeClaim.claimName` +| The name of the PVC to manage persistent data for Scanner V4. You can use a PVC, which is the recommended default if a default storage class exists on the cluster. If no default storage class exists and it is not specifically set in the `persistentVolumeClaim.storageClassName` parameter, ephemeral storage is used. + +| `scannerV4.db.persistence.persistentVolumeClaim.size` +| The size of the PVC to manage persistent data for Scanner V4. + +| `scannerV4.db.persistence.persistentVolumeClaim.storageClassName` +| The name of the storage class to use for the PVC. If your cluster is not configured with a default storage class, and no value is provided for this parameter, ephemeral storage is used. + +| `scannerV4.indexer.nodeSelector` +| If you want this component to only run on specific nodes, you can use this parameter to configure a node selector. + +| `scannerV4.indexer.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for the Scanner V4 Indexer. This parameter is mainly used for infrastructure nodes. + +| `scannerV4.indexer.resources.limits` +| Use this parameter to override the default resource limits for the Scanner V4 Indexer. + +| `scannerV4.indexer.resources.requests` +| Use this parameter to override the default resource requests for the Scanner V4 Indexer. + +| `scannerV4.indexer.scaling.autoScaling` +| When enabled, the number of Scanner V4 Indexer replicas is managed dynamically based on the load, within the limits specified. + +| `scannerV4.indexer.scaling.maxReplicas` +| Specifies the maximum replicas to be used in the Scanner V4 Indexer autoscaling configuration. + +| `scannerV4.indexer.scaling.minReplicas` +| Specifies the minimum replicas to be used in the Scanner V4 Indexer autoscaling configuration. + +| `scannerV4.indexer.scaling.replicas` +| When autoscaling is disabled for the Scanner V4 Indexer, the number of replicas is always configured to match this value. + +| `scannerV4.monitoring.exposeEndpoint` +| Configures a monitoring endpoint for Scanner V4. The monitoring endpoint allows other services to collect metrics from Scanner V4, provided in a Prometheus-compatible format. Use `Enabled` to expose the monitoring endpoint. When you enable monitoring, {product-title-short} creates a new service, `monitoring`, with port 9090, and a network policy allowing inbound connections to the port. By default, this is not enabled. + +a| `scannerV4.scannerComponent` +| Enables Scanner V4. Valid values are: + +* `Default`: Scanner V4 is not enabled and not deployed. + +* `AutoSense`: If Central exists in the same namespace, Scanner V4 is not deployed and the existing Scanner V4 that was installed with Central is used. If there is no Central in this namespace, Scanner V4 is deployed. + +* `Disabled`: Do not deploy Scanner V4. + +|=== + +[id="image-configuration-settings_{context}"] +== Image configuration + +Use image configuration settings when you are using a custom registry. + +[cols="1,3"] +|=== +| Parameter | Description + +| `imagePullSecrets.name` +| Additional image pull secrets to be taken into account for pulling images. + +|=== + +[id="per-node-settings_{context}"] +== Per node settings + +Per node settings define the configuration settings for components that run on each node in a cluster to secure the cluster. +These components are Collector and Compliance. + +[cols="1,3a"] +|=== +| Parameter | Description + +| `perNode.collector.collection` +| The method for system-level data collection. +The default value is `CORE_BPF`. +Red{nbsp}Hat recommends using `CORE_BPF` for data collection. +If you select `NoCollection`, Collector does not report any information about the network activity and the process executions. +Available options are `NoCollection` and `CORE_BPF`. The `EBPF` option is available only for version 4.4 and earlier. + +| `perNode.collector.imageFlavor` +| The image type to use for Collector. You can specify it as `Regular` or `Slim`. +This value is deprecated. `Regular` and `Slim` images are identical. + +| `perNode.collector.resources.limits` +| Use this parameter to override the default resource limits for Collector. + +| `perNode.collector.resources.requests` +| Use this parameter to override the default resource requests for Collector. + +| `perNode.compliance.resources.requests` +| Use this parameter to override the default resource requests for Compliance. + +| `perNode.compliance.resources.limits` +| Use this parameter to override the default resource limits for Compliance. + +| `perNode.taintToleration` +| To ensure comprehensive monitoring of your cluster activity, {product-title} runs services on every node in the cluster, including tainted nodes by default. +If you do not want this behavior, specify `AvoidTaints` for this parameter. The default value is `TolerateTaints`. + +|=== + +[id="sensor-configuration-settings_{context}"] +== Sensor configuration + +This configuration defines the settings of the Sensor components, which runs on one node in a cluster. + +[cols="1,3"] +|=== +| Parameter | Description + +| `sensor.nodeSelector` +| If you want Sensor to only run on specific nodes, you can configure a node selector. + +| `sensor.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Sensor. This parameter is mainly used for infrastructure nodes. + +| `sensor.hostAliases` +| Use this parameter to inject hosts and IP addresses into the pod's hosts file. + +| `sensor.resources.limits` +| Use this parameter to override the default resource limits for Sensor. + +| `sensor.resources.requests` +| Use this parameter to override the default resource requests for Sensor. +|=== + +[id="general-and-miscellaneous-settings-secured-cluster_{context}"] +== General and miscellaneous settings + +[cols="1,3"] +|=== +| Parameter | Description + +| `customize.annotations` +| Allows specifying custom annotations for the Central deployment. + +| `customize.envVars` +| Advanced settings to configure environment variables. + +| `egress.connectivityPolicy` +| Configures whether {product-title} should run in online or offline mode. +In offline mode, automatic updates of vulnerability definitions and kernel modules are disabled. + +| `misc.createSCCs` +| Set this to `true` to create SCCs for Central. +It may cause issues in some environments. + +|`network.policies` +a| To provide security at the network level, {product-title-short} creates default `NetworkPolicy` resources in the namespace where secured cluster resources are installed. These network policies allow ingress to specific components on specific ports. If you do not want {product-title-short} to create these policies, set this parameter to `Disabled`. The default value is `Enabled`. + +[WARNING] +==== +Disabling creation of default network policies can break communication between {product-title-short} components. If you disable creation of default policies, you must create your own network policies to allow this communication. +==== + +| `overlays` +| See "Customizing the installation using the Operator with overlays". + +| `tls.additionalCAs` +| Additional trusted CA certificates for the secured cluster. +These certificates are used when integrating with services using a private certificate authority. + +|=== diff --git a/modules/secured-cluster-services-config.adoc b/modules/secured-cluster-services-config.adoc new file mode 100644 index 000000000000..c86c84ca20b9 --- /dev/null +++ b/modules/secured-cluster-services-config.adoc @@ -0,0 +1,339 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-secured-cluster-ocp.adoc +// * installing/installing_other/install-secured-cluster-other.adoc +// * cloud_service/installing_cloud_other/install-secured-cluster-cloud-other.adoc +// * cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc +:_mod-docs-content-type: CONCEPT +[id="secured-cluster-services-config_{context}"] += Configuration parameters + +ifeval::["{context}" == "install-secured-cluster-cloud-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "install-secured-cluster-cloud-other"] +:kube: +endif::[] + +ifeval::["{context}" == "install-secured-cluster-ocp"] +:openshift: +endif::[] + +ifeval::["{context}" == "install-secured-cluster-other"] +:kube: +endif::[] + + +|=== +| Parameter | Description + +| `clusterName` +| Name of your cluster. + +| `centralEndpoint` +| Address of the Central endpoint. If you are using a non-gRPC capable load balancer, use the WebSocket protocol by prefixing the endpoint address with `wss://`. When configuring multiple clusters, use the hostname for the address. For example, `central.example.com`. + +| `env.grpcEnforceALPN` +| Use `true` to force application-level protocol negotiation (ALPN) during the TLS handshake. + +| `sensor.endpoint` +| Address of the Sensor endpoint including port number. + +| `sensor.imagePullPolicy` +| Image pull policy for the Sensor container. + +| `sensor.serviceTLS.cert` +| The internal service-to-service TLS certificate that Sensor uses. + +| `sensor.serviceTLS.key` +| The internal service-to-service TLS certificate key that Sensor uses. + +| `sensor.resources.requests.memory` +| The memory request for the Sensor container. Use this parameter to override the default value. + +| `sensor.resources.requests.cpu` +| The CPU request for the Sensor container. Use this parameter to override the default value. + +| `sensor.resources.limits.memory` +| The memory limit for the Sensor container. Use this parameter to override the default value. + +| `sensor.resources.limits.cpu` +| The CPU limit for the Sensor container. Use this parameter to override the default value. + +| `sensor.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force Sensor to only schedule on nodes with the specified label. + +| `sensor.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Sensor. This parameter is mainly used for infrastructure nodes. + +| `image.main.name` +| The name of the `main` image. + +| `image.collector.name` +| The name of the Collector image. + +| `image.main.registry` +| The address of the registry you are using for the main image. + +| `image.collector.registry` +| The address of the registry you are using for the Collector image. + +| `image.scanner.registry` +| The address of the registry you are using for the Scanner image. + +| `image.scannerDb.registry` +| The address of the registry you are using for the Scanner DB image. + +| `image.scannerV4.registry` +| The address of the registry you are using for the Scanner V4 image. + +| `image.scannerV4DB.registry` +| The address of the registry you are using for the Scanner V4 DB image. + +| `image.main.pullPolicy` +| Image pull policy for `main` images. + +| `image.collector.pullPolicy` +| Image pull policy for the Collector images. + +| `image.main.tag` +| Tag of `main` image to use. + +| `image.collector.tag` +| Tag of `collector` image to use. + +| `collector.collectionMethod` +| Either `CORE_BPF` or `NO_COLLECTION`. + +| `collector.imagePullPolicy` +| Image pull policy for the Collector container. + +| `collector.complianceImagePullPolicy` +| Image pull policy for the Compliance container. + +| `collector.disableTaintTolerations` +| If you specify `false`, tolerations are applied to Collector, and the collector pods can schedule onto all nodes with taints. +If you specify it as `true`, no tolerations are applied, and the collector pods are not scheduled onto nodes with taints. + +| `collector.resources.requests.memory` +| The memory request for the Collector container. Use this parameter to override the default value. + +| `collector.resources.requests.cpu` +| The CPU request for the Collector container. Use this parameter to override the default value. + +| `collector.resources.limits.memory` +| The memory limit for the Collector container. Use this parameter to override the default value. + +| `collector.resources.limits.cpu` +| The CPU limit for the Collector container. Use this parameter to override the default value. + +| `collector.complianceResources.requests.memory` +| The memory request for the Compliance container. Use this parameter to override the default value. + +| `collector.complianceResources.requests.cpu` +| The CPU request for the Compliance container. Use this parameter to override the default value. + +| `collector.complianceResources.limits.memory` +| The memory limit for the Compliance container. Use this parameter to override the default value. + +| `collector.complianceResources.limits.cpu` +| The CPU limit for the Compliance container. Use this parameter to override the default value. + +| `collector.serviceTLS.cert` +| The internal service-to-service TLS certificate that Collector uses. + +| `collector.serviceTLS.key` +| The internal service-to-service TLS certificate key that Collector uses. + +| `admissionControl.listenOnCreates` +| This setting controls whether Kubernetes is configured to contact {product-title} with `AdmissionReview` requests for workload creation events. + +| `admissionControl.listenOnUpdates` +| When you set this parameter as `false`, {product-title} creates the `ValidatingWebhookConfiguration` in a way that causes the Kubernetes API server not to send object update events. +Since the volume of object updates is usually higher than the object creates, leaving this as `false` limits the load on the admission control service and decreases the chances of a malfunctioning admission control service. + +| `admissionControl.listenOnEvents` +| This setting controls whether the cluster is configured to contact {product-title} with `AdmissionReview` requests for Kubernetes `exec` and `portforward` events. +{product-title-short} does not support this feature on {ocp} 3.11. + +| `admissionControl.dynamic.enforceOnCreates` +| This setting controls whether {product-title} evaluates policies; +if it is disabled, all AdmissionReview requests are automatically accepted. + +| `admissionControl.dynamic.enforceOnUpdates` +| This setting controls the behavior of the admission control service. +You must specify `listenOnUpdates` as `true` for this to work. + +| `admissionControl.dynamic.scanInline` +| If you set this option to `true`, the admission control service requests an image scan before making an admission decision. +Since image scans take several seconds, enable this option only if you can ensure that all images used in your cluster are scanned before deployment (for example, by a CI integration during image build). +This option corresponds to the *Contact image scanners* option in the {product-title-short} portal. + +| `admissionControl.dynamic.disableBypass` +| Set it to `true` to disable bypassing the Admission controller. +//TODO: Link to admission controller docs + +| `admissionControl.dynamic.timeout` +| Use this parameter to specify the maximum number of seconds {product-title-short} must wait for an admission review before marking it as fail open. If the admission webhook does not receive information that it is requesting before the end of the timeout period, it fails, but in fail open status, it still allows the operation to succeed. For example, the admission controller would allow a deployment to be created even if a scan had timed out and {product-title-short} could not determine if the deployment violated a policy. Beginning in release 4.5, Red{nbsp}Hat reduced the default timeout setting for the {product-title-short} admission controller webhooks from 20 seconds to 10 seconds, resulting in an effective timeout of 12 seconds within the `ValidatingWebhookConfiguration`. +ifndef::kube[] +This change does not negatively affect {ocp} users because {ocp} caps the timeout at 13 seconds. +endif::kube[] +ifndef::openshift[] +For Kubernetes clusters, image scanning and pulling that are done as part of the webhook execution might require you to configure a longer timeout value. +endif::openshift[] + +| `admissionControl.resources.requests.memory` +| The memory request for the Admission Control container. Use this parameter to override the default value. + +| `admissionControl.resources.requests.cpu` +| The CPU request for the Admission Control container. Use this parameter to override the default value. + +| `admissionControl.resources.limits.memory` +| The memory limit for the Admission Control container. Use this parameter to override the default value. + +| `admissionControl.resources.limits.cpu` +| The CPU limit for the Admission Control container. Use this parameter to override the default value. + +| `admissionControl.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force Admission Control to only schedule on nodes with the specified label. + +| `admissionControl.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Admission Control. This parameter is mainly used for infrastructure nodes. + +| `admissionControl.namespaceSelector` +| If the admission controller webhook needs a specific `namespaceSelector`, you can specify the corresponding selector here. Use this parameter to override the default, which avoids a few system namespaces. + +| `admissionControl.serviceTLS.cert` +| The internal service-to-service TLS certificate that Admission Control uses. + +| `admissionControl.serviceTLS.key` +| The internal service-to-service TLS certificate key that Admission Control uses. + +| `registryOverride` +| Use this parameter to override the default `docker.io` registry. +Specify the name of your registry if you are using some other registry. + +| `collector.disableTaintTolerations` +| If you specify `false`, tolerations are applied to Collector, and the Collector pods can schedule onto all nodes with taints. +If you specify it as `true`, no tolerations are applied, and the Collector pods are not scheduled onto nodes with taints. + +| `createUpgraderServiceAccount` +| Specify `true` to create the `sensor-upgrader` account. +By default, {product-title} creates a service account called `sensor-upgrader` in each secured cluster. +This account is highly privileged but is only used during upgrades. +If you do not create this account, you must complete future upgrades manually if the Sensor does not have enough permissions. +//TODO: Link to Enable automatic upgrades for secured clusters topic. + +| `createSecrets` +| Specify `false` to skip the orchestrator secret creation for the Sensor, Collector, and Admission controller. + +| `collector.slimMode` +| Deprecated. Specify `true` if you want to use a slim Collector image for deploying Collector. + +| `sensor.resources` +| Resource specification for Sensor. + +| `admissionControl.resources` +| Resource specification for Admission controller. + +| `collector.resources` +| Resource specification for Collector. + +| `collector.complianceResources` +| Resource specification for Collector's Compliance container. + +| `exposeMonitoring` +| If you set this option to `true`, {product-title} exposes Prometheus metrics endpoints on port number 9090 for the Sensor, Collector, and the Admission controller. + +| `auditLogs.disableCollection` +| If you set this option to `true`, {product-title} disables the audit log detection features used to detect access and modifications to configuration maps and secrets. + +| `autoLockProcessBaselines.enabled` +| If you set this option to `true`, {product-title} enables automatically locking process baselines. The default is `false`. + +| `scanner.disable` +| If you set this option to `false`, {product-title} deploys a Scanner-slim and Scanner DB in the secured cluster to allow scanning images on the integrated OpenShift image registry. Enabling Scanner-slim is supported on {ocp} and Kubernetes secured clusters. Defaults to `true`. + +| `scanner.dbTolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner DB. + +| `scanner.replicas` +| Resource specification for Collector's Compliance container. + +| `scanner.logLevel` +| Setting this parameter allows you to modify the scanner log level. Use this option only for troubleshooting purposes. + +| `scanner.autoscaling.disable` +| If you set this option to `true`, {product-title} disables autoscaling on the Scanner deployment. + +| `scanner.autoscaling.minReplicas` +| The minimum number of replicas for autoscaling. Defaults to 2. + +| `scanner.autoscaling.maxReplicas` +| The maximum number of replicas for autoscaling. Defaults to 5. + +| `scanner.nodeSelector` +| Specify a node selector label as `label-key: label-value` to force Scanner to only schedule on nodes with the specified label. + +| `scanner.tolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner. + +| `scanner.dbNodeSelector` +| Specify a node selector label as `label-key: label-value` to force Scanner DB to only schedule on nodes with the specified label. + +| `scanner.dbTolerations` +| If the node selector selects tainted nodes, use this parameter to specify a taint toleration key, value, and effect for Scanner DB. + +| `scanner.resources.requests.memory` +| The memory request for the Scanner container. Use this parameter to override the default value. + +| `scanner.resources.requests.cpu` +| The CPU request for the Scanner container. Use this parameter to override the default value. + +| `scanner.resources.limits.memory` +| The memory limit for the Scanner container. Use this parameter to override the default value. + +| `scanner.resources.limits.cpu` +| The CPU limit for the Scanner container. Use this parameter to override the default value. + +| `scanner.dbResources.requests.memory` +| The memory request for the Scanner DB container. Use this parameter to override the default value. + +| `scanner.dbResources.requests.cpu` +| The CPU request for the Scanner DB container. Use this parameter to override the default value. + +| `scanner.dbResources.limits.memory` +| The memory limit for the Scanner DB container. Use this parameter to override the default value. + +| `scanner.dbResources.limits.cpu` +| The CPU limit for the Scanner DB container. Use this parameter to override the default value. + +| `monitoring.openshift.enabled` +| If you set this option to `false`, {product-title} will not set up {osp} monitoring. Defaults to `true` on {osp} 4. + +| `network.enableNetworkPolicies` +a| To provide security at the network level, {product-title-short} creates default `NetworkPolicy` resources in the namespace where secured cluster resources are installed. These network policies allow ingress to specific components on specific ports. If you do not want {product-title-short} to create these policies, set this parameter to `False`. This is a Boolean value. The default value is `True`, which means the default policies are automatically created. + +[WARNING] +==== +Disabling creation of default network policies can break communication between {product-title-short} components. If you disable creation of default policies, you must create your own network policies to allow this communication. +==== +|=== + +[id="secured-cluster-services-environment-variables_{context}"] +== Environment variables + +You can specify environment variables for Sensor and Admission controller in the following format: + +[source,yaml] +---- +customize: + envVars: + ENV_VAR1: "value1" + ENV_VAR2: "value2" +---- + +The `customize` setting allows you to specify custom Kubernetes metadata (labels and annotations) for all objects created by this Helm chart and additional pod labels, pod annotations, and container environment variables for workloads. + +The configuration is hierarchical, in the sense that metadata defined at a more generic scope (for example, for all objects) can be overridden by metadata defined at a narrower scope (for example, only for the Sensor deployment). diff --git a/modules/securing-container-images-by-using-signature-integration.adoc b/modules/securing-container-images-by-using-signature-integration.adoc new file mode 100644 index 000000000000..2d30e51ac45a --- /dev/null +++ b/modules/securing-container-images-by-using-signature-integration.adoc @@ -0,0 +1,110 @@ +// Module included in the following assemblies: +// +// * operating/verify-image-signatures.adoc + +:_mod-docs-content-type: PROCEDURE +[id="securing-container-images-by-using-signature-integration_{context}"] += Securing container images by using signature integration + +By creating a signature integration, you can ensure that a trusted source signs the container image. + +When you create a signature integration, you can use the following verification methods: + +* Cosign public keys +* Cosign certificates + +You can also enhance signature verification by enabling transparency log validation. +The transparency log records the signature in a public log and provides cryptographic proof of its inclusion. +You can strengthen verification by adding traceability and increasing trust when you use public keys or certificates. + +[IMPORTANT] +==== +You must configure at least one trusted signer. To configure a trusted signer, you must specify a Cosign public encryption key or a Cosign certificate chain. You can combine multiple image signers in a single signature integration. +==== + +.Prerequisites + +* You have a Cosign public key which is encoded in Privacy Enhanced Mail (PEM) format. ++ +For more information about Cosign public keys, see link:https://docs.sigstore.dev/cosign/signing/overview/[Overview] (Sigstore documentation). + +* You have the certificate identity and issuer. +* Optional: You have a certificate and chain which is encoded in PEM format. ++ +For more information about Cosign certificates, see link:https://docs.sigstore.dev/cosign/verifying/verify/[Verifying Signatures] (Sigstore documentation). + +.Procedure + +. In the {product-title-short} portal, click *Platform Configuration* -> *Integrations*. +. Scroll down to the *Signature Integrations* section, and then click *Signature*. +. To create a new signature integration, click *New integration*. +. Enter a name for the integration. +. To add a new public key, complete the following steps: ++ +[NOTE] +==== +** If you add a public key, you do not need to create a new certificate verification. +** You can add one or more public keys. +==== +.. Expand *Cosign public Keys*, and then click *Add new public key*. +.. Enter a name for the key. +.. Enter a value for the key which is encoded in PEM format. +. To add a new certificate verification, complete the following steps: ++ +[IMPORTANT] +==== +** When you create a signature integration, you must add a new certificate verification if you want to use keyless verification for the image signature by using {rh-rhtas-first}. +** You can add one or more certificate verifications. +==== +.. Expand *Cosign certificates*, and then click *Add new certificate verification*. +.. Enter the certificate OIDC issuer that Cosign specifies. You must use regular expressions in RE2 syntax for matching. ++ +For more information, go to the GitHub repository at `google/re2`, open the `Wiki` section, and then select the `Syntax` page. +.. Enter the certificate identity that Cosign specifies. You must use regular expressions in RE2 syntax for matching. ++ +For more information, go to the GitHub repository at `google/re2`, open the `Wiki` section, and then select the `Syntax` page. +.. Enter the trusted certificate root which is encoded in PEM format to verify the certificates. If you do not specify the certificate root, the public Fulcio roots are used automatically for verification. ++ +For more information, see link:https://docs.sigstore.dev/certificate_authority/overview/[Fulcio] (Sigstore documentation). +.. Enter the trusted signer intermediate certificate authority to verify the certificates. If you do not specify the certificate authority, the certificate chain is used automatically for verification. +.. Optional: Select the *Enable certificate transparency log validation* checkbox to validate the proof of inclusion into the certificate transparency log. ++ +Enter the public key that you want to use to validate the proof of inclusion into the certificate transparency log. +If you do not specify the public key, the key of the public Sigstore instance is used automatically for validation. +. To configure the transparency log, complete the following steps: ++ +[NOTE] +==== +When you create a signature integration, you can enable the validation of transparency logs in the following situations: + +** When the signatures contain short-lived certificates that Fulcio issues. +** When you want to use keyless verification of the signatures. +** To verify the signatures, when you use a public key. +==== +.. Select the *Enable transparency log validation* checkbox to validate the inclusion of the signature in a transparency log. ++ +Enter the URL where the Rekor transparency log is available. If you do not specify the URL, the public Rekor instance of Sigstore is used automatically for validation. ++ +[NOTE] +==== +The Rekor URL is required for online confirmation of the inclusion into the transparency log. +==== +.. Optional: Select the *Validate in offline mode* checkbox to force the offline validation of the signature proof of inclusion into the transparency log. ++ +[NOTE] +==== +You can force the offline validation of the signature proof of inclusion into the transparency log only if you have enabled the validation of the transparency log. +==== ++ +Enter the public key to validate the signature proof of inclusion into the Rekor transparency log. +If you do not specify the public key, the key of the public Sigstore instance is used automatically for validation. +. Click *Save*. + +.Verification + +. In the {product-title-short} portal, click *Platform Configuration* -> *Integrations*. +. Scroll down to the *Signature Integrations* section, and then click *Signature*. +. Verify that the creation of the signature integration was successful. +. Optional: Choose the appropriate method to manage the signature integration that you have created: +** To delete the signature integration, click the overflow menu {kebab} and then select *Delete Integration*. +** To edit the signature integration, click the overflow menu {kebab} and then select *Edit Integration*. \ No newline at end of file diff --git a/modules/security-audit-log-filtering.adoc b/modules/security-audit-log-filtering.adoc deleted file mode 100644 index 608deec0f5ca..000000000000 --- a/modules/security-audit-log-filtering.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * security/audit-log-view.adoc - -[id="security-audit-log-basic-filtering_{context}"] -= Filtering audit logs - -You can use `jq` or another JSON parsing tool to filter the API server audit logs. - -[NOTE] -==== -The amount of information logged to the API server audit logs is controlled by the audit log policy that is set. -==== - -The following procedure provides examples of using `jq` to filter audit logs on control plane node `node-1.example.com`. See the link:https://stedolan.github.io/jq/manual/[jq Manual] for detailed information on using `jq`. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed `jq`. - -.Procedure - -* Filter OpenShift API server audit logs by user: -+ -[source,terminal] ----- -$ oc adm node-logs node-1.example.com \ - --path=openshift-apiserver/audit.log \ - | jq 'select(.user.username == "myusername")' ----- - -* Filter OpenShift API server audit logs by user agent: -+ -[source,terminal] ----- -$ oc adm node-logs node-1.example.com \ - --path=openshift-apiserver/audit.log \ - | jq 'select(.userAgent == "cluster-version-operator/v0.0.0 (linux/amd64) kubernetes/$Format")' ----- - -* Filter Kubernetes API server audit logs by a certain API version and only output the user agent: -+ -[source,terminal] ----- -$ oc adm node-logs node-1.example.com \ - --path=kube-apiserver/audit.log \ - | jq 'select(.requestURI | startswith("/apis/apiextensions.k8s.io/v1beta1")) | .userAgent' ----- - -* Filter OpenShift OAuth API server audit logs by excluding a verb: -+ -[source,terminal] ----- -$ oc adm node-logs node-1.example.com \ - --path=oauth-apiserver/audit.log \ - | jq 'select(.verb != "get")' ----- diff --git a/modules/security-build-designing.adoc b/modules/security-build-designing.adoc deleted file mode 100644 index c3e64d774e4e..000000000000 --- a/modules/security-build-designing.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-build.adoc - -[id="security-build-designing_{context}"] -= Designing your build process - -You can design your container image management and build process to use container layers so that you can separate control. - -image::build_process2.png["Designing Your Build Process", align="center"] - -For example, an operations team manages base images, while architects manage -middleware, runtimes, databases, and other solutions. Developers can then focus -on application layers and focus on writing code. - -Because new vulnerabilities are identified daily, you need to proactively check -container content over time. To do this, you should integrate automated security -testing into your build or CI process. For example: - -* SAST / DAST – Static and Dynamic security testing tools. -* Scanners for real-time checking against known vulnerabilities. Tools like these -catalog the open source packages in your container, notify you of any known -vulnerabilities, and update you when new vulnerabilities are discovered in -previously scanned packages. - -Your CI process should include policies that flag builds with issues discovered -by security scans so that your team can take appropriate action to address those -issues. You should sign your custom built containers to ensure that nothing is -tampered with between build and deployment. - -Using GitOps methodology, you can use the same CI/CD mechanisms to -manage not only your application configurations, but also your -{product-title} infrastructure. diff --git a/modules/security-build-inputs.adoc b/modules/security-build-inputs.adoc deleted file mode 100644 index 9d554ab5b815..000000000000 --- a/modules/security-build-inputs.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-build.adoc - -[id="security-build-inputs_{context}"] -= Securing inputs during builds - -In some scenarios, build operations require credentials to access dependent -resources, but it is undesirable for those credentials to be available in the -final application image produced by the build. You can define input secrets for -this purpose. - -For example, when building a Node.js application, you can set up your private -mirror for Node.js modules. To download modules from that private -mirror, you must supply a custom `.npmrc` file for the build that contains -a URL, user name, and password. For security reasons, you do not want to expose -your credentials in the application image. - -Using this example scenario, you can add an input secret to a new `BuildConfig` object: - -. Create the secret, if it does not exist: -+ -[source,terminal] ----- -$ oc create secret generic secret-npmrc --from-file=.npmrc=~/.npmrc ----- -+ -This creates a new secret named `secret-npmrc`, which contains the base64 -encoded content of the `~/.npmrc` file. - -. Add the secret to the `source` section in the existing `BuildConfig` object: -+ -[source,yaml] ----- -source: - git: - uri: https://github.com/sclorg/nodejs-ex.git - secrets: - - destinationDir: . - secret: - name: secret-npmrc ----- - -. To include the secret in a new `BuildConfig` object, run the following command: -+ -[source,terminal] ----- -$ oc new-build \ - openshift/nodejs-010-centos7~https://github.com/sclorg/nodejs-ex.git \ - --build-secret secret-npmrc ----- diff --git a/modules/security-build-knative.adoc b/modules/security-build-knative.adoc deleted file mode 100644 index a4d88a446537..000000000000 --- a/modules/security-build-knative.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-build.adoc - -[id="security-build-knative_{context}"] -= Building Knative serverless applications -Relying on Kubernetes and Kourier, you can build, deploy -and manage serverless applications using -link:https://knative.dev/[Knative] in {product-title}. -As with other builds, you can use S2I images to build your containers, -then serve them using Knative services. -View Knative application builds through the -*Topology* view of the {product-title} web console. diff --git a/modules/security-build-management.adoc b/modules/security-build-management.adoc deleted file mode 100644 index 5a78524c37a1..000000000000 --- a/modules/security-build-management.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-build.adoc - -[id="security-build-management_{context}"] -= Managing builds - -You can use Source-to-Image (S2I) to combine source code and base images. -_Builder images_ make use of S2I to enable your development and operations teams -to collaborate on a reproducible build environment. -With Red Hat S2I images available as Universal Base Image (UBI) images, -you can now freely redistribute your software with -base images built from real {op-system-base} RPM packages. -Red Hat has removed subscription restrictions to allow this. - -When developers commit code with Git for an application using build images, -{product-title} can perform the following functions: - -* Trigger, either by using webhooks on the code repository or other automated -continuous integration (CI) process, to automatically assemble a new image from -available artifacts, the S2I builder image, and the newly committed code. -* Automatically deploy the newly built image for testing. -* Promote the tested image to production where it can be automatically deployed -using a CI process. - -image::build_process1.png["Source-to-Image Builds", align="center"] - -You can use the integrated OpenShift Container Registry to manage access to final images. -Both S2I and native build images are automatically pushed to your OpenShift Container -Registry. - -In addition to the included Jenkins for CI, you can also integrate your own -build and CI environment with {product-title} using RESTful APIs, as well as use -any API-compliant image registry. diff --git a/modules/security-build-once.adoc b/modules/security-build-once.adoc deleted file mode 100644 index f074aba36483..000000000000 --- a/modules/security-build-once.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-build.adoc - -[id="security-build-once_{context}"] -= Building once, deploying everywhere - -Using {product-title} as the standard platform for container builds enables you -to guarantee the security of the build environment. Adhering to a "build once, -deploy everywhere" philosophy ensures that the product of the build process is -exactly what is deployed in production. - -It is also important to maintain the immutability of your containers. You should -not patch running containers, but rebuild and redeploy them. - -As your software moves through the stages of building, testing, and production, it is -important that the tools making up your software supply chain be trusted. The -following figure illustrates the process and tools that could be incorporated -into a trusted software supply chain for containerized software: - -image::trustedsupplychain.png["", align="center"] - -{product-title} can be integrated with trusted code repositories (such as GitHub) -and development platforms (such as Che) for creating and managing secure code. -Unit testing could rely on -link:https://cucumber.io/[Cucumber] and link:https://junit.org/[JUnit]. -You could inspect your containers for vulnerabilities and compliance issues -with link:https://anchore.com[Anchore] or Twistlock, -and use image scanning tools such as AtomicScan or Clair. -Tools such as link:https://sysdig.com[Sysdig] could provide ongoing monitoring -of your containerized applications. diff --git a/modules/security-compliance-nist.adoc b/modules/security-compliance-nist.adoc deleted file mode 100644 index 2d5fe27d2a7a..000000000000 --- a/modules/security-compliance-nist.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-compliance.adoc - -[id="security-compliance-nist_{context}"] -= Understanding compliance and risk management - -ifndef::openshift-origin[] -FIPS compliance is one of the most critical components required in -highly secure environments, to ensure that only supported cryptographic -technologies are allowed on nodes. -endif::openshift-origin[] - -To understand Red Hat's view of {product-title} compliance frameworks, refer -to the Risk Management and Regulatory Readiness chapter of the -link:https://access.redhat.com/articles/5059881[OpenShift Security Guide Book]. - diff --git a/modules/security-container-content-external-scanning.adoc b/modules/security-container-content-external-scanning.adoc deleted file mode 100644 index b761c82b1944..000000000000 --- a/modules/security-container-content-external-scanning.adoc +++ /dev/null @@ -1,265 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-container-content.adoc - -[id="security-container-content-external-scanning_{context}"] -= Integrating external scanning - -{product-title} makes use of link:https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/[object annotations] -to extend functionality. External tools, such as vulnerability scanners, can -annotate image objects with metadata to summarize results and control pod -execution. This section describes the recognized format of this annotation so it -can be reliably used in consoles to display useful data to users. - -[id="security-image-metadata_{context}"] -== Image metadata - -There are different types of image quality data, including package -vulnerabilities and open source software (OSS) license compliance. Additionally, -there may be more than one provider of this metadata. To that end, the following -annotation format has been reserved: - ----- -quality.images.openshift.io/<qualityType>.<providerId>: {} ----- - -.Annotation key format -[option="header"] -|=== -|Component |Description |Acceptable values - -|`qualityType` -|Metadata type -|`vulnerability` + -`license` + -`operations` + -`policy` - -|`providerId` -|Provider ID string -|`openscap` + -`redhatcatalog` + -`redhatinsights` + -`blackduck` + -`jfrog` -|=== - -[id="security-example-annotation-keys_{context}"] -=== Example annotation keys - ----- -quality.images.openshift.io/vulnerability.blackduck: {} -quality.images.openshift.io/vulnerability.jfrog: {} -quality.images.openshift.io/license.blackduck: {} -quality.images.openshift.io/vulnerability.openscap: {} ----- - -The value of the image quality annotation is structured data that must adhere to -the following format: - -.Annotation value format -[option="header"] -|=== -|Field |Required? |Description |Type - -|`name` -|Yes -|Provider display name -|String - -|`timestamp` -|Yes -|Scan timestamp -|String - -|`description` -|No -|Short description -|String -|`reference` -|Yes -|URL of information source or more details. Required so user may validate the data. -|String - -|`scannerVersion` -|No -|Scanner version -|String - -|`compliant` -|No -|Compliance pass or fail -|Boolean - -|`summary` -|No -|Summary of issues found -|List (see table below) -|=== - -The `summary` field must adhere to the following format: - -.Summary field value format -[option="header"] -|=== -|Field |Description |Type - -|`label` -|Display label for component (for example, "critical," "important," "moderate," -"low," or "health") -|String - -|`data` -|Data for this component (for example, count of vulnerabilities found or score) -|String - -|`severityIndex` -|Component index allowing for ordering and assigning graphical -representation. The value is range `0..3` where `0` = low. -|Integer - -|`reference` -|URL of information source or more details. Optional. -|String -|=== - -[id="security-example-annotation-values_{context}"] -=== Example annotation values - -This example shows an OpenSCAP annotation for an image with -vulnerability summary data and a compliance boolean: - -.OpenSCAP annotation -[source,json] ----- -{ - "name": "OpenSCAP", - "description": "OpenSCAP vulnerability score", - "timestamp": "2016-09-08T05:04:46Z", - "reference": "https://www.open-scap.org/930492", - "compliant": true, - "scannerVersion": "1.2", - "summary": [ - { "label": "critical", "data": "4", "severityIndex": 3, "reference": null }, - { "label": "important", "data": "12", "severityIndex": 2, "reference": null }, - { "label": "moderate", "data": "8", "severityIndex": 1, "reference": null }, - { "label": "low", "data": "26", "severityIndex": 0, "reference": null } - ] -} ----- - -This example shows the -link:https://catalog.redhat.com/software/containers/explore[Container images section of the Red Hat Ecosystem Catalog] -annotation for an image with health index data -with an external URL for additional details: - -.Red Hat Ecosystem Catalog annotation -[source,json] ----- -{ - "name": "Red Hat Ecosystem Catalog", - "description": "Container health index", - "timestamp": "2016-09-08T05:04:46Z", - "reference": "https://access.redhat.com/errata/RHBA-2016:1566", - "compliant": null, - "scannerVersion": "1.2", - "summary": [ - { "label": "Health index", "data": "B", "severityIndex": 1, "reference": null } - ] -} ----- - -[id="security-annotating-image-objects_{context}"] -== Annotating image objects - -While image stream objects -are what an end user of {product-title} operates against, -image objects are annotated with -security metadata. Image objects are cluster-scoped, pointing to a single image -that may be referenced by many image streams and tags. - -[id="security-example-annotate-CLI_{context}"] -=== Example annotate CLI command - -Replace `<image>` with an image digest, for example -`sha256:401e359e0f45bfdcf004e258b72e253fd07fba8cc5c6f2ed4f4608fb119ecc2`: - -[source,terminal] ----- -$ oc annotate image <image> \ - quality.images.openshift.io/vulnerability.redhatcatalog='{ \ - "name": "Red Hat Ecosystem Catalog", \ - "description": "Container health index", \ - "timestamp": "2020-06-01T05:04:46Z", \ - "compliant": null, \ - "scannerVersion": "1.2", \ - "reference": "https://access.redhat.com/errata/RHBA-2020:2347", \ - "summary": "[ \ - { "label": "Health index", "data": "B", "severityIndex": 1, "reference": null } ]" }' ----- - -[id="controlling-pod-execution_{context}"] -== Controlling pod execution - -Use the `images.openshift.io/deny-execution` image policy -to programmatically control if an image can be run. - -[id="security-controlling-pod-execution-example-annotation_{context}"] -=== Example annotation - -[source,yaml] ----- -annotations: - images.openshift.io/deny-execution: true ----- - -[id="security-integration-reference_{context}"] -== Integration reference - -In most cases, external tools such as vulnerability scanners develop a -script or plug-in that watches for image updates, performs scanning, and -annotates the associated image object with the results. Typically this -automation calls the {product-title} {product-version} REST APIs to write the annotation. See -{product-title} REST APIs for general -information on the REST APIs. - -[id="security-integration-reference-example-api-call_{context}"] -=== Example REST API call - -The following example call using `curl` overrides the value of the -annotation. Be sure to replace the values for `<token>`, `<openshift_server>`, -`<image_id>`, and `<image_annotation>`. - -.Patch API call -[source,terminal] ----- -$ curl -X PATCH \ - -H "Authorization: Bearer <token>" \ - -H "Content-Type: application/merge-patch+json" \ - https://<openshift_server>:8443/oapi/v1/images/<image_id> \ - --data '{ <image_annotation> }' ----- - -The following is an example of `PATCH` payload data: - -.Patch call data -[source,terminal] ----- -{ -"metadata": { - "annotations": { - "quality.images.openshift.io/vulnerability.redhatcatalog": - "{ 'name': 'Red Hat Ecosystem Catalog', 'description': 'Container health index', 'timestamp': '2020-06-01T05:04:46Z', 'compliant': null, 'reference': 'https://access.redhat.com/errata/RHBA-2020:2347', 'summary': [{'label': 'Health index', 'data': '4', 'severityIndex': 1, 'reference': null}] }" - } - } -} ----- - -ifdef::openshift-origin[] -[NOTE] -==== -Due to the complexity of this API call and challenges with escaping characters, -an API developer tool such as link:https://www.getpostman.com/[Postman] may -assist in creating API calls. -==== -endif::[] diff --git a/modules/security-container-content-inside.adoc b/modules/security-container-content-inside.adoc deleted file mode 100644 index c43ea02c4b4d..000000000000 --- a/modules/security-container-content-inside.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-container-content.adoc - -[id="security-container-content-inside_{context}"] -= Securing inside the container - -Applications and infrastructures are composed of readily available components, -many of which are open source packages such as, the Linux operating system, -JBoss Web Server, PostgreSQL, and Node.js. - -Containerized versions of these packages are also available. However, you need -to know where the packages originally came from, what versions are used, who built them, and whether -there is any malicious code inside them. - -Some questions to answer include: - -* Will what is inside the containers compromise your infrastructure? -* Are there known vulnerabilities in the application layer? -* Are the runtime and operating system layers current? - -By building your containers from Red Hat -link:https://access.redhat.com/articles/4238681[Universal Base Images] (UBI) you are -assured of a foundation for your container images that consists of -the same RPM-packaged software that is included in Red Hat Enterprise Linux. -No subscriptions are required to either use or redistribute UBI images. - -To assure ongoing security of the containers themselves, security -scanning features, used directly from {op-system-base} or added to {product-title}, -can alert you when -an image you are using has vulnerabilities. OpenSCAP image scanning is -available in {op-system-base} and the -link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#container-security-operator-setup[Container Security Operator] can be added -to check container images used in {product-title}. diff --git a/modules/security-container-content-scanning.adoc b/modules/security-container-content-scanning.adoc deleted file mode 100644 index 88f1792e4373..000000000000 --- a/modules/security-container-content-scanning.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-container-content.adoc - -[id="security-container-content-scanning_{context}"] -= Security scanning in {op-system-base} - -For {op-system-base-full} systems, OpenSCAP scanning is available -from the `openscap-utils` package. In {op-system-base}, you can use the `openscap-podman` -command to scan images for vulnerabilities. See -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/security_hardening/index#scanning-the-system-for-configuration-compliance-and-vulnerabilities_security-hardening[Scanning containers and container images for vulnerabilities] in the Red Hat Enterprise Linux documentation. - -{product-title} enables you to leverage {op-system-base} scanners with your CI/CD process. -For example, you can integrate static code analysis tools that test for security -flaws in your source code and software composition analysis tools that identify -open source libraries to provide metadata on those libraries such as -known vulnerabilities. - -[id="quay-security-scan_{context}"] -== Scanning OpenShift images - -For the container images that are running in {product-title} -and are pulled from Red Hat Quay registries, you can use an Operator to list the -vulnerabilities of those images. The -link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#container-security-operator-setup[Container Security Operator] -can be added to {product-title} to provide vulnerability reporting -for images added to selected namespaces. - -Container image scanning for Red Hat Quay is performed by the -link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#quay-security-scanner[Clair security scanner]. -In Red Hat Quay, Clair can search for and report vulnerabilities in -images built from {op-system-base}, CentOS, Oracle, Alpine, Debian, and Ubuntu -operating system software. - diff --git a/modules/security-container-content-universal.adoc b/modules/security-container-content-universal.adoc deleted file mode 100644 index bcd0638b79c5..000000000000 --- a/modules/security-container-content-universal.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-container-content.adoc - -[id="security-container-content-universal_{context}"] -= Creating redistributable images with UBI - -To create containerized applications, you typically start with a trusted base -image that offers the components that are usually provided by the operating system. -These include the libraries, utilities, and other features the application -expects to see in the operating system's file system. - -Red Hat Universal Base Images (UBI) were created to encourage anyone building their -own containers to start with one that is made entirely from Red Hat Enterprise -Linux rpm packages and other content. These UBI images are updated regularly -to keep up with security patches and free to use and redistribute with -container images built to include your own software. - -Search the -link:https://catalog.redhat.com/software/containers/explore[Red Hat Ecosystem Catalog] -to both find and check the health of different UBI images. -As someone creating secure container images, you might -be interested in these two general types of UBI images: - -* **UBI**: There are standard UBI images for RHEL 7 and 8 (`ubi7/ubi` and -`ubi8/ubi`), as well as minimal images based on those systems (`ubi7/ubi-minimal` -and `ubi8/ubi-mimimal`). All of these images are preconfigured to point to free -repositories of {op-system-base} software that you can add to the container images you build, -using standard `yum` and `dnf` commands. -Red Hat encourages people to use these images on other distributions, -such as Fedora and Ubuntu. - -* **Red Hat Software Collections**: Search the Red Hat Ecosystem Catalog -for `rhscl/` to find images created to use as base images for specific types -of applications. For example, there are Apache httpd ([x-]`rhscl/httpd-*`), -Python ([x-]`rhscl/python-*`), Ruby ([x-]`rhscl/ruby-*`), Node.js -([x-]`rhscl/nodejs-*`) and Perl ([x-]`rhscl/perl-*`) rhscl images. - -Keep in mind that while UBI images are freely available and redistributable, -Red Hat support for these images is only available through Red Hat -product subscriptions. - -See -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/building_running_and_managing_containers/index#using_red_hat_universal_base_images_standard_minimal_and_runtimes[Using Red Hat Universal Base Images] -in the Red Hat Enterprise Linux documentation for information on how to use and build on -standard, minimal and init UBI images. diff --git a/modules/security-context-constraints-about.adoc b/modules/security-context-constraints-about.adoc deleted file mode 100644 index aaa14e9489fd..000000000000 --- a/modules/security-context-constraints-about.adoc +++ /dev/null @@ -1,297 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-security-context-constraints.adoc - -[id="security-context-constraints-about_{context}"] -= About security context constraints - -Similar to the way that RBAC resources control user access, administrators can -use _security context constraints_ (SCCs) to control permissions for pods. These -permissions include actions that a _pod_, a collection of containers, can -perform and what resources it can access. You can use SCCs to define a set of -conditions that a pod must run with to be accepted into the system. - -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -SCCs allow an administrator to control: - -- Whether a pod can run privileged containers. -- The capabilities that a container can request. -- The use of host directories as volumes. -- The SELinux context of the container. -- The container user ID. -- The use of host namespaces and networking. -- The allocation of an `FSGroup` that owns the pod's volumes. -- The configuration of allowable supplemental groups. -- Whether a container requires the use of a read only root file system. -- The usage of volume types. -- The configuration of allowable `seccomp` profiles. - -//// -If you have `cluster-admin` privileges, you can adjust the default SCC policies to -be more permissive. -//// - -The cluster contains eight default SCCs: - -* `anyuid` -* `hostaccess` -* `hostmount-anyuid` -* `hostnetwork` -+ -[WARNING] -==== -If additional workloads are run on master hosts, use caution when providing -access to `hostnetwork`. A workload that runs `hostnetwork` on a master host is -effectively root on the cluster and must be trusted accordingly. -==== -* `node-exporter` -* `nonroot` -* `privileged` -* `restricted` - - -[IMPORTANT] -==== -Do not modify the default SCCs. Customizing the default SCCs can lead to issues -when {product-title} is upgraded. -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] -Instead, create new SCCs. -endif::[] -==== - -The `privileged` SCC allows: - -* Users to run privileged pods -* Pods to mount host directories as volumes -* Pods to run as any user -* Pods to run with any MCS label -* Pods to use the host's IPC namespace -* Pods to use the host's PID namespace -* Pods to use any FSGroup -* Pods to use any supplemental group -* Pods to use any seccomp profiles -* Pods to request any capabilities - -The `restricted` SCC: - -* Ensures that pods cannot run as privileged. -* Ensures that pods cannot mount host directory volumes. -* Requires that a pod run as a user in a pre-allocated range of UIDs. -* Requires that a pod run with a pre-allocated MCS label. -* Allows pods to use any FSGroup. -* Allows pods to use any supplemental group. - -[NOTE] -==== -For more information about each SCC, see the `kubernetes.io/description` -annotation available on the SCC. -==== - -SCCs are composed of settings and strategies that control the security features -a pod has access to. These settings fall into three categories: - -[cols="1,4",options="header"] -|=== - -|Category -|Description - -|Controlled by a boolean -|Fields of this type default to the most restrictive value. For example, -`AllowPrivilegedContainer` is always set to `false` if unspecified. - -|Controlled by an allowable set -|Fields of this type are checked against the set to ensure their value is -allowed. - -|Controlled by a strategy -a|Items that have a strategy to generate a value provide: - -* A mechanism to generate the value, and -* A mechanism to ensure that a specified value falls into the set of allowable -values. - -|=== - -CRI-O has the following default list of capabilities that are allowed for each container of a pod: - -* `CHOWN` -* `DAC_OVERRIDE` -* `FSETID` -* `FOWNER` -* `SETGID` -* `SETUID` -* `SETPCAP` -* `NET_BIND_SERVICE` -* `KILL` - -The containers use the capabilities from this default list, but pod manifest authors can alter it by requesting additional capabilities or removing some of the default behaviors. Use the `allowedCapabilities`, `defaultAddCapabilities`, and `requiredDropCapabilities` parameters to control such requests from the pods and to dictate which capabilities can be requested, which ones must be added to each container, and which ones must be forbidden. - -[id="authorization-SCC-strategies_{context}"] -== SCC Strategies - -.RunAsUser - -. `MustRunAs` - Requires a `runAsUser` to be configured. Uses the configured -`runAsUser` as the default. Validates against the configured `runAsUser`. -. `MustRunAsRange` - Requires minimum and maximum values to be defined if not -using pre-allocated values. Uses the minimum as the default. Validates against -the entire allowable range. -. `MustRunAsNonRoot` - Requires that the pod be submitted with a non-zero -`runAsUser` or have the `USER` directive defined in the image. No default -provided. -. `RunAsAny` - No default provided. Allows any `runAsUser` to be specified. - -.SELinuxContext - -. `MustRunAs` - Requires `seLinuxOptions` to be configured if not using -pre-allocated values. Uses `seLinuxOptions` as the default. Validates against -`seLinuxOptions`. -. `RunAsAny` - No default provided. Allows any `seLinuxOptions` to be -specified. - -.SupplementalGroups - -. `MustRunAs` - Requires at least one range to be specified if not using -pre-allocated values. Uses the minimum value of the first range as the default. -Validates against all ranges. -. `RunAsAny` - No default provided. Allows any `supplementalGroups` to be -specified. - -.FSGroup - -. `MustRunAs` - Requires at least one range to be specified if not using -pre-allocated values. Uses the minimum value of the first range as the default. -Validates against the first ID in the first range. -. `RunAsAny` - No default provided. Allows any `fsGroup` ID to be specified. - -[id="authorization-controlling-volumes_{context}"] -== Controlling volumes - -The usage of specific volume types can be controlled by setting the `volumes` -field of the SCC. The allowable values of this field correspond to the volume -sources that are defined when creating a volume: - -* link:https://kubernetes.io/docs/concepts/storage/volumes/#azurefilevolume[`azureFile`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#azurediskvolume[`azureDisk`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#flocker[`flocker`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#flexvolume[`flexVolume`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#hostpath[`hostPath`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#emptydir[`emptyDir`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#gcepersistentdisk[`gcePersistentDisk`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#awselasticblockstore[`awsElasticBlockStore`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#gitrepo[`gitRepo`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#secret[`secret`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#nfs[`nfs`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#iscsi[`iscsi`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#glusterfs[`glusterfs`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#persistentvolumeclaim[`persistentVolumeClaim`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#rbd[`rbd`] -* `cinder` -* link:https://kubernetes.io/docs/concepts/storage/volumes/#cephfs[`cephFS`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#downwardapi[`downwardAPI`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#fc-fibre-channel[`fc`] -* `configMap` -* link:https://kubernetes.io/docs/concepts/storage/volumes/#vspherevolume[`vsphereVolume`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#quobyte[`quobyte`] -* `photonPersistentDisk` -* link:https://kubernetes.io/docs/concepts/storage/volumes/#projected[`projected`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#portworxvolume[`portworxVolume`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#scaleio[`scaleIO`] -* link:https://kubernetes.io/docs/concepts/storage/volumes/#storageos[`storageos`] -* *** (a special value to allow the use of all volume types) -* `none` (a special value to disallow the use of all volumes types. Exist only for backwards compatibility) - -The recommended minimum set of allowed volumes for new SCCs are `configMap`, -`downwardAPI`, `emptyDir`, `persistentVolumeClaim`, `secret`, and `projected`. - -[NOTE] -==== -The list of allowable volume types is not exhaustive because new types are -added with each release of {product-title}. -==== - -[NOTE] -==== -For backwards compatibility, the usage of `allowHostDirVolumePlugin` overrides -settings in the `volumes` field. For example, if `allowHostDirVolumePlugin` -is set to false but allowed in the `volumes` field, then the `hostPath` -value will be removed from `volumes`. -==== - - -[id="admission_{context}"] -== Admission -_Admission control_ with SCCs allows for control over the creation of resources -based on the capabilities granted to a user. - -In terms of the SCCs, this means that an admission controller can inspect the -user information made available in the context to retrieve an appropriate set of -SCCs. Doing so ensures the pod is authorized to make requests about its -operating environment or to generate a set of constraints to apply to the pod. - -The set of SCCs that admission uses to authorize a pod are determined by the -user identity and groups that the user belongs to. Additionally, if the pod -specifies a service account, the set of allowable SCCs includes any constraints -accessible to the service account. - -Admission uses the following approach to create the final security context for -the pod: - -. Retrieve all SCCs available for use. -. Generate field values for security context settings that were not specified -on the request. -. Validate the final settings against the available constraints. - -If a matching set of constraints is found, then the pod is accepted. If the -request cannot be matched to an SCC, the pod is rejected. - -A pod must validate every field against the SCC. The following are examples for -just two of the fields that must be validated: - -[NOTE] -==== -These examples are in the context of a strategy using the preallocated values. -==== - -*A FSGroup SCC strategy of `MustRunAs`* - -If the pod defines a `fsGroup` ID, then that ID must equal the default -`fsGroup` ID. Otherwise, the pod is not validated by that SCC and the next SCC -is evaluated. - -If the `SecurityContextConstraints.fsGroup` field has value `RunAsAny` -and the pod specification omits the `Pod.spec.securityContext.fsGroup`, -then this field is considered valid. Note that it is possible that during -validation, other SCC settings will reject other pod fields and thus cause the -pod to fail. - -*A `SupplementalGroups` SCC strategy of `MustRunAs`* - -If the pod specification defines one or more `supplementalGroups` IDs, then -the pod's IDs must equal one of the IDs in the namespace's -`openshift.io/sa.scc.supplemental-groups` annotation. Otherwise, the pod is not -validated by that SCC and the next SCC is evaluated. - -If the `SecurityContextConstraints.supplementalGroups` field has value `RunAsAny` -and the pod specification omits the `Pod.spec.securityContext.supplementalGroups`, -then this field is considered valid. Note that it is possible that during -validation, other SCC settings will reject other pod fields and thus cause the -pod to fail. - -[id="scc-prioritization_{context}"] -== SCC prioritization - -SCCs have a priority field that affects the ordering when attempting to -validate a request by the admission controller. A higher priority -SCC is moved to the front of the set when sorting. When the complete set -of available SCCs are determined they are ordered by: - -. Highest priority first, nil is considered a 0 priority -. If priorities are equal, the SCCs will be sorted from most restrictive to least restrictive -. If both priorities and restrictions are equal the SCCs will be sorted by name - -By default, the `anyuid` SCC granted to cluster administrators is given priority -in their SCC set. This allows cluster administrators to run pods as any -user by without specifying a `RunAsUser` on the pod's `SecurityContext`. The -administrator may still specify a `RunAsUser` if they wish. diff --git a/modules/security-context-constraints-command-reference.adoc b/modules/security-context-constraints-command-reference.adoc deleted file mode 100644 index db94821b4992..000000000000 --- a/modules/security-context-constraints-command-reference.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-security-context-constraints.adoc - -[id="security-context-constraints-command-reference_{context}"] -= Security context constraints reference commands - -You can manage SCCs in your instance as normal API objects using the CLI. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[NOTE] -==== -You must have `cluster-admin` privileges to manage SCCs. -==== - -[IMPORTANT] -==== -Do not modify the default SCCs. Customizing the default SCCs can lead to issues -when upgrading. Instead, create new SCCs. -==== -endif::openshift-enterprise,openshift-webscale,openshift-origin[] - -ifdef::openshift-dedicated[] -As a cluster administrator, you can list and view details for -SCCs, but cannot edit or delete the default SCCs. -endif::openshift-dedicated[] - - -[id="listing-security-context-constraints_{context}"] -== Listing SCCs - -To get a current list of SCCs: - -[source,terminal] ----- -$ oc get scc ----- - -.Example output -[source,terminal] ----- -NAME PRIV CAPS SELINUX RUNASUSER FSGROUP SUPGROUP PRIORITY READONLYROOTFS VOLUMES -anyuid false [] MustRunAs RunAsAny RunAsAny RunAsAny 10 false [configMap downwardAPI emptyDir persistentVolumeClaim projected secret] -hostaccess false [] MustRunAs MustRunAsRange MustRunAs RunAsAny <none> false [configMap downwardAPI emptyDir hostPath persistentVolumeClaim projected secret] -hostmount-anyuid false [] MustRunAs RunAsAny RunAsAny RunAsAny <none> false [configMap downwardAPI emptyDir hostPath nfs persistentVolumeClaim projected secret] -hostnetwork false [] MustRunAs MustRunAsRange MustRunAs MustRunAs <none> false [configMap downwardAPI emptyDir persistentVolumeClaim projected secret] -node-exporter false [] RunAsAny RunAsAny RunAsAny RunAsAny <none> false [*] -nonroot false [] MustRunAs MustRunAsNonRoot RunAsAny RunAsAny <none> false [configMap downwardAPI emptyDir persistentVolumeClaim projected secret] -privileged true [*] RunAsAny RunAsAny RunAsAny RunAsAny <none> false [*] -restricted false [] MustRunAs MustRunAsRange MustRunAs RunAsAny <none> false [configMap downwardAPI emptyDir persistentVolumeClaim projected secret] ----- - -[id="examining-a-security-context-constraints-object_{context}"] -== Examining an SCC - -You can view information about a particular SCC, including which users, service accounts, and groups the SCC is applied to. - -For example, to examine the `restricted` SCC: - -[source,terminal] ----- -$ oc describe scc restricted ----- - -.Example output -[source,terminal] ----- -Name: restricted -Priority: <none> -Access: - Users: <none> <1> - Groups: system:authenticated <2> -Settings: - Allow Privileged: false - Default Add Capabilities: <none> - Required Drop Capabilities: KILL,MKNOD,SYS_CHROOT,SETUID,SETGID - Allowed Capabilities: <none> - Allowed Seccomp Profiles: <none> - Allowed Volume Types: configMap,downwardAPI,emptyDir,persistentVolumeClaim,projected,secret - Allow Host Network: false - Allow Host Ports: false - Allow Host PID: false - Allow Host IPC: false - Read Only Root Filesystem: false - Run As User Strategy: MustRunAsRange - UID: <none> - UID Range Min: <none> - UID Range Max: <none> - SELinux Context Strategy: MustRunAs - User: <none> - Role: <none> - Type: <none> - Level: <none> - FSGroup Strategy: MustRunAs - Ranges: <none> - Supplemental Groups Strategy: RunAsAny - Ranges: <none> ----- -<1> Lists which users and service accounts the SCC is applied to. -<2> Lists which groups the SCC is applied to. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[NOTE] -==== -To preserve customized SCCs during upgrades, do not edit settings on -the default SCCs. -//other than priority, users, groups, labels, and annotations. -==== - -[id="deleting-security-context-constraints_{context}"] -== Deleting an SCC - -To delete an SCC: - -[source,terminal] ----- -$ oc delete scc <scc_name> ----- - -[NOTE] -==== -If you delete a default SCC, it will regenerate when you restart the cluster. -==== - -[id="updating-security-context-constraints_{context}"] - -== Updating an SCC - -To update an existing SCC: - -[source,terminal] ----- -$ oc edit scc <scc_name> ----- - -[NOTE] -==== -To preserve customized SCCs during upgrades, do not edit settings on -the default SCCs. -//other than priority, users, groups, labels, and annotations. -==== -endif::openshift-enterprise,openshift-webscale,openshift-origin[] diff --git a/modules/security-context-constraints-creating.adoc b/modules/security-context-constraints-creating.adoc deleted file mode 100644 index d478479cd8f6..000000000000 --- a/modules/security-context-constraints-creating.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-security-context-constraints.adoc - -[id="security-context-constraints-creating_{context}"] -= Creating security context constraints - -You can create security context constraints (SCCs) by using the OpenShift CLI (`oc`). - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Log in to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Define the SCC in a YAML file named `scc_admin.yaml`: -+ -.`SecurityContextConstraints` object definition -[source,yaml] ----- -kind: SecurityContextConstraints -apiVersion: security.openshift.io/v1 -metadata: - name: scc-admin -allowPrivilegedContainer: true -runAsUser: - type: RunAsAny -seLinuxContext: - type: RunAsAny -fsGroup: - type: RunAsAny -supplementalGroups: - type: RunAsAny -users: -- my-admin-user -groups: -- my-admin-group ----- -+ -Optionally, you can specify drop capabilities for an SCC by setting the -`requiredDropCapabilities` field with the desired values. Any specified -capabilities are dropped from the container. For example, to create an SCC -with the `KILL`, `MKNOD`, and `SYS_CHROOT` required drop capabilities, add -the following to the SCC object: -+ -[source,yaml] ----- -requiredDropCapabilities: -- KILL -- MKNOD -- SYS_CHROOT ----- -+ -CRI-O supports the same list of capability values that are found in the link:https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities[Docker documentation]. - -. Create the SCC by passing in the file: -+ -[source,terminal] ----- -$ oc create -f scc_admin.yaml ----- -+ -.Example output -[source,terminal] ----- -securitycontextconstraints "scc-admin" created ----- - -.Verification - -* Verify that the SCC was created: -+ -[source,terminal] ----- -$ oc get scc scc-admin ----- -+ -.Example output -[source,terminal] ----- -NAME PRIV CAPS SELINUX RUNASUSER FSGROUP SUPGROUP PRIORITY READONLYROOTFS VOLUMES -scc-admin true [] RunAsAny RunAsAny RunAsAny RunAsAny <none> false [awsElasticBlockStore azureDisk azureFile cephFS cinder configMap downwardAPI emptyDir fc flexVolume flocker gcePersistentDisk gitRepo glusterfs iscsi nfs persistentVolumeClaim photonPersistentDisk quobyte rbd secret vsphere] ----- diff --git a/modules/security-context-constraints-example.adoc b/modules/security-context-constraints-example.adoc deleted file mode 100644 index 9efbe1599f6f..000000000000 --- a/modules/security-context-constraints-example.adoc +++ /dev/null @@ -1,124 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-security-context-constraints.adoc - -[id="security-context-constraints-example_{context}"] -= Example security context constraints - -The following examples show the security context constraints (SCC) format and -annotations: - -.Annotated `priviledged` SCC -[source,yaml] ----- -allowHostDirVolumePlugin: true -allowHostIPC: true -allowHostNetwork: true -allowHostPID: true -allowHostPorts: true -allowPrivilegedContainer: true -allowedCapabilities: <1> -- '*' -apiVersion: security.openshift.io/v1 -defaultAddCapabilities: [] <2> -fsGroup: <3> - type: RunAsAny -groups: <4> -- system:cluster-admins -- system:nodes -kind: SecurityContextConstraints -metadata: - annotations: - kubernetes.io/description: 'privileged allows access to all privileged and host - features and the ability to run as any user, any group, any fsGroup, and with - any SELinux context. WARNING: this is the most relaxed SCC and should be used - only for cluster administration. Grant with caution.' - creationTimestamp: null - name: privileged -priority: null -readOnlyRootFilesystem: false -requiredDropCapabilities: [] <5> -runAsUser: <6> - type: RunAsAny -seLinuxContext: <7> - type: RunAsAny -seccompProfiles: -- '*' -supplementalGroups: <8> - type: RunAsAny -users: <9> -- system:serviceaccount:default:registry -- system:serviceaccount:default:router -- system:serviceaccount:openshift-infra:build-controller -volumes: -- '*' ----- - -<1> A list of capabilities that a pod can request. An empty list means -that none of capabilities can be requested while the special symbol `***` -allows any capabilities. -<2> A list of additional capabilities that are added to any pod. -<3> The `FSGroup` strategy, which dictates the allowable values for the -security context. -<4> The groups that can access this SCC. -<5> A list of capabilities that are be dropped from a pod. -<6> The `runAsUser` strategy type, which dictates the allowable values for the -Security Context. -//could use the available strategies -<7> The `seLinuxContext` strategy type, which dictates the allowable values for -the Security Context. -<8> The `supplementalGroups` strategy, which dictates the allowable supplemental -groups for the Security Context. -<9> The users who can access this SCC. - -The `users` and `groups` fields on the SCC control which users can access the -SCC. -By default, cluster administrators, nodes, and the build controller are granted -access to the privileged SCC. All authenticated users are granted access to the -restricted SCC. - -.Without explicit `runAsUser` setting -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: security-context-demo -spec: - securityContext: <1> - containers: - - name: sec-ctx-demo - image: gcr.io/google-samples/node-hello:1.0 ----- -<1> When a container or pod does not request a user ID under which it should be run, -the effective UID depends on the SCC that emits this pod. Because restricted SCC -is granted to all authenticated users by default, it will be available to all -users and service accounts and used in most cases. The restricted SCC uses -`MustRunAsRange` strategy for constraining and defaulting the possible values of -the `securityContext.runAsUser` field. The admission plug-in will look for the -`openshift.io/sa.scc.uid-range` annotation on the current project to populate -range fields, as it does not provide this range. In the end, a container will -have `runAsUser` equal to the first value of the range that is -hard to predict because every project has different ranges. - - -.With explicit `runAsUser` setting -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: security-context-demo -spec: - securityContext: - runAsUser: 1000 <1> - containers: - - name: sec-ctx-demo - image: gcr.io/google-samples/node-hello:1.0 ----- -<1> A container or pod that requests a specific user ID will be accepted by -{product-title} only when a service account or a user is granted access to a SCC -that allows such a user ID. The SCC can allow arbitrary IDs, an ID that falls -into a range, or the exact user ID specific to the request. - -This configuration is valid for SELinux, fsGroup, and Supplemental Groups. diff --git a/modules/security-context-constraints-pre-allocated-values.adoc b/modules/security-context-constraints-pre-allocated-values.adoc deleted file mode 100644 index 1f5f4e1e9000..000000000000 --- a/modules/security-context-constraints-pre-allocated-values.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-security-context-constraints.adoc - -ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[] -[id="security-context-constraints-pre-allocated-values_{context}"] -= About pre-allocated security context constraints values - -The admission controller is aware of certain conditions in the security context -constraints (SCCs) that trigger it to look up pre-allocated values from a namespace and -populate the SCC before processing the pod. Each SCC -strategy is evaluated independently of other strategies, with the pre-allocated -values, where allowed, for each policy aggregated with pod specification values -to make the final values for the various IDs defined in the running pod. - -The following SCCs cause the admission controller to look for pre-allocated -values when no ranges are defined in the pod specification: - -. A `RunAsUser` strategy of `MustRunAsRange` with no minimum or maximum set. -Admission looks for the `openshift.io/sa.scc.uid-range` annotation to populate -range fields. -. An `SELinuxContext` strategy of `MustRunAs` with no level set. Admission -looks for the `openshift.io/sa.scc.mcs` annotation to populate the level. -. A `FSGroup` strategy of `MustRunAs`. Admission looks for the -`openshift.io/sa.scc.supplemental-groups` annotation. -. A `SupplementalGroups` strategy of `MustRunAs`. Admission looks for the -`openshift.io/sa.scc.supplemental-groups` annotation. - -During the generation phase, the security context provider uses default values -for any parameter values that are not specifically set in the pod. Default values -are based on the selected strategy: - -. `RunAsAny` and `MustRunAsNonRoot` strategies do not provide default -values. If the pod needs a parameter value, such as a group ID, you -must define the value in the pod specification. -. `MustRunAs` (single value) strategies provide a default value that is -always used. For example, for group IDs, even if the pod specification defines -its own ID value, the namespace's default parameter value also appears in the pod's -groups. -. `MustRunAsRange` and `MustRunAs` (range-based) strategies provide the -minimum value of the range. As with a single value `MustRunAs` strategy, the -namespace's default parameter value appears in the running pod. If a range-based -strategy is configurable with multiple ranges, it provides the minimum value -of the first configured range. - -[NOTE] -==== -`FSGroup` and `SupplementalGroups` strategies fall back to the -`openshift.io/sa.scc.uid-range` annotation if the -`openshift.io/sa.scc.supplemental-groups` annotation does not exist on the -namespace. If neither exists, the SCC is not created. -==== - -[NOTE] -==== -By default, the annotation-based `FSGroup` strategy configures itself with a -single range based on the minimum value for the annotation. For example, if your -annotation reads `1/3`, the `FSGroup` strategy configures itself with a -minimum and maximum value of `1`. If you want to allow more groups to be accepted for -the `FSGroup` field, you can configure a custom SCC that does not use the -annotation. -==== - -[NOTE] -==== -The `openshift.io/sa.scc.supplemental-groups` annotation accepts a comma-delimited -list of blocks in the format of `<start>/<length` or `<start>-<end>`. -The `openshift.io/sa.scc.uid-range` annotation accepts only a single block. -==== -endif::[] diff --git a/modules/security-context-constraints-rbac.adoc b/modules/security-context-constraints-rbac.adoc deleted file mode 100644 index 47dd28415bdb..000000000000 --- a/modules/security-context-constraints-rbac.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/managing-security-context-constraints.adoc - -[id="role-based-access-to-ssc_{context}"] -= Role-based access to security context constraints - -You can specify SCCs as resources that are handled by RBAC. This allows -you to scope access to your SCCs to a certain project or to the entire -cluster. Assigning users, groups, or service accounts directly to an -SCC retains cluster-wide scope. - -[NOTE] -==== -You cannot assign a SCC to pods created in one of the default namespaces: `default`, `kube-system`, `kube-public`, `openshift-node`, `openshift-infra`, `openshift`. These namespaces should not be used for running pods or services. -==== - -To include access to SCCs for your role, specify the `scc` resource -when creating a role. - -[source,terminal] ----- -$ oc create role <role-name> --verb=use --resource=scc --resource-name=<scc-name> -n <namespace> ----- - -This results in the following role definition: - -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: -... - name: role-name <1> - namespace: namespace <2> -... -rules: -- apiGroups: - - security.openshift.io <3> - resourceNames: - - scc-name <4> - resources: - - securitycontextconstraints <5> - verbs: <6> - - use ----- -<1> The role's name. -<2> Namespace of the defined role. Defaults to `default` if not specified. -<3> The API group that includes the `SecurityContextConstraints` resource. -Automatically defined when `scc` is specified as a resource. -<4> An example name for an SCC you want to have access. -<5> Name of the resource group that allows users to specify SCC names in -the `resourceNames` field. -<6> A list of verbs to apply to the role. - -A local or cluster role with such a rule allows the subjects that are -bound to it with a role binding or a cluster role binding to use the -user-defined SCC called `scc-name`. - -[NOTE] -==== -Because RBAC is designed to prevent escalation, even project administrators -are unable to grant access to an SCC. By default, they are not -allowed to use the verb `use` on SCC resources, including the -`restricted` SCC. -==== diff --git a/modules/security-deploy-continuous.adoc b/modules/security-deploy-continuous.adoc deleted file mode 100644 index 710e8d3f17f9..000000000000 --- a/modules/security-deploy-continuous.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-deploy.adoc - -[id="security-deploy-continuous_{context}"] -= Automating continuous deployment - -You can integrate your own continuous deployment (CD) tooling with -{product-title}. - -By leveraging CI/CD and {product-title}, you can automate the process of -rebuilding the application to incorporate the latest fixes, testing, and -ensuring that it is deployed everywhere within the environment. diff --git a/modules/security-deploy-image-sources.adoc b/modules/security-deploy-image-sources.adoc deleted file mode 100644 index 0429cc47c3f2..000000000000 --- a/modules/security-deploy-image-sources.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-deploy.adoc - -[id="security-deploy-image-sources_{context}"] -= Controlling what image sources can be deployed - -It is important that the intended images are actually being deployed, that the -images including the contained content -are from trusted sources, and they have not been altered. Cryptographic signing -provides this assurance. {product-title} enables cluster administrators to apply -security policy that is broad or narrow, reflecting deployment environment and -security requirements. Two parameters define this policy: - -* one or more registries, with optional project namespace -* trust type, such as accept, reject, or require public key(s) - -You can use these policy parameters to allow, deny, or require a trust -relationship for entire registries, parts of registries, or individual -images. Using trusted public keys, you can ensure that the source is -cryptographically verified. -The policy rules apply to nodes. Policy may be -applied uniformly across all nodes or targeted for different node workloads (for -example, build, zone, or environment). - -.Example image signature policy file -[json] ----- -{ - "default": [{"type": "reject"}], - "transports": { - "docker": { - "access.redhat.com": [ - { - "type": "signedBy", - "keyType": "GPGKeys", - "keyPath": "/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release" - } - ] - }, - "atomic": { - "172.30.1.1:5000/openshift": [ - { - "type": "signedBy", - "keyType": "GPGKeys", - "keyPath": "/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release" - } - ], - "172.30.1.1:5000/production": [ - { - "type": "signedBy", - "keyType": "GPGKeys", - "keyPath": "/etc/pki/example.com/pubkey" - } - ], - "172.30.1.1:5000": [{"type": "reject"}] - } - } -} ----- - -The policy can be saved onto a node as `/etc/containers/policy.json`. -Saving this file to a node is best accomplished using a new -`MachineConfig` object. This -example enforces the following rules: - -* Require images from the Red Hat Registry (`registry.access.redhat.com`) to be -signed by the Red Hat public key. -* Require images from your OpenShift Container Registry in the `openshift` -namespace to be signed by the Red Hat public key. -* Require images from your OpenShift Container Registry in the `production` -namespace to be signed by the public key for `example.com`. -* Reject all other registries not specified by the global `default` definition. diff --git a/modules/security-deploy-secrets.adoc b/modules/security-deploy-secrets.adoc deleted file mode 100644 index e0cf535c731f..000000000000 --- a/modules/security-deploy-secrets.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-deploy.adoc - -[id="security-deploy-secrets_{context}"] -= Creating secrets and config maps - -The `Secret` object type provides a mechanism to hold sensitive information such -as passwords, {product-title} client configuration files, `dockercfg` files, -and private source repository credentials. Secrets decouple sensitive content -from pods. You can mount secrets into containers using a volume plug-in or the -system can use secrets to perform actions on behalf of a pod. - -For example, to add a secret to your deployment configuration -so that it can access a private image repository, do the following: - -.Procedure - -. Log in to the {product-title} web console. - -. Create a new project. - -. Navigate to *Resources* -> *Secrets* and create a new secret. Set `Secret Type` to -`Image Secret` and `Authentication Type` to `Image Registry Credentials` to -enter credentials for accessing a private image repository. - -. When creating a deployment configuration (for example, from the *Add to Project* -> -*Deploy Image* page), set the `Pull Secret` to your new secret. - -Config maps are similar to secrets, but are designed to support working with -strings that do not contain sensitive information. The `ConfigMap` object holds -key-value pairs of configuration data that can be consumed in pods or used to -store configuration data for system components such as controllers. diff --git a/modules/security-deploy-signature.adoc b/modules/security-deploy-signature.adoc deleted file mode 100644 index fb27fe47bb19..000000000000 --- a/modules/security-deploy-signature.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-deploy.adoc - -[id="security-deploy-signature_{context}"] -= Using signature transports - -A signature transport is a way to store and retrieve the binary signature blob. -There are two types of signature transports. - -* `atomic`: Managed by the {product-title} API. -* `docker`: Served as a local file or by a web server. - -The {product-title} API manages signatures that use the `atomic` transport type. -You must store the images that use this signature type in -your OpenShift Container Registry. Because the docker/distribution `extensions` API -auto-discovers the image signature endpoint, no additional -configuration is required. - -Signatures that use the `docker` transport type are served by local file or web -server. These signatures are more flexible; you can serve images from any -container image registry and use an independent server to deliver binary -signatures. - -However, the `docker` transport type requires additional configuration. You must -configure the nodes with the URI of the signature server by placing -arbitrarily-named YAML files into a directory on the host system, -`/etc/containers/registries.d` by default. The YAML configuration files contain a -registry URI and a signature server URI, or _sigstore_: - -.Example registries.d file -[source,yaml] ----- -docker: - access.redhat.com: - sigstore: https://access.redhat.com/webassets/docker/content/sigstore ----- - -In this example, the Red Hat Registry, `access.redhat.com`, is the signature -server that provides signatures for the `docker` transport type. Its URI is -defined in the `sigstore` parameter. You might name this file -`/etc/containers/registries.d/redhat.com.yaml` and use the Machine Config -Operator to -automatically place the file on each node in your cluster. No service -restart is required since policy and `registries.d` files are dynamically -loaded by the container runtime. diff --git a/modules/security-deploy-trigger.adoc b/modules/security-deploy-trigger.adoc deleted file mode 100644 index 47159e5d63ad..000000000000 --- a/modules/security-deploy-trigger.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-deploy.adoc - -[id="security-deploy-trigger_{context}"] -= Controlling container deployments with triggers - -If something happens during the build process, or if a vulnerability is -discovered after an image has been deployed, you can use tooling for automated, -policy-based deployment to remediate. You can use triggers to rebuild and replace images, -ensuring the immutable containers process, -instead of patching running containers, which is not recommended. - -image::secure_deployments.png["Secure Deployments", align="center"] - -For example, you build an application using three container image layers: core, -middleware, and applications. An issue is discovered in the core image and that -image is rebuilt. After the build is complete, the image is pushed to your -OpenShift Container Registry. {product-title} detects that the image has changed -and automatically rebuilds and deploys the application image, based on the -defined triggers. This change incorporates the fixed libraries and ensures that -the production code is identical to the most current image. - -You can use the `oc set triggers` command to set a deployment trigger. -For example, to set a trigger for a deployment called -deployment-example: - -[source,terminal] ----- -$ oc set triggers deploy/deployment-example \ - --from-image=example:latest \ - --containers=web ----- diff --git a/modules/security-hardening-how.adoc b/modules/security-hardening-how.adoc deleted file mode 100644 index 42f063613314..000000000000 --- a/modules/security-hardening-how.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-hardening.adoc - -[id="security-hardening-how_{context}"] - -= Choosing how to harden {op-system} - -Direct modification of {op-system} systems in {product-title} is discouraged. -Instead, you should think of modifying systems in pools of nodes, such -as worker nodes and master nodes. When a new node is needed, in -non-bare metal installs, you can request a new node of the type -you want and it will be created from an {op-system} image plus the -modifications you created earlier. - -There are opportunities for modifying {op-system} before installation, -during installation, and after the cluster is up and running. - -[id="security-harden-before-installation_{context}"] -== Hardening before installation - -For bare metal installations, you can add hardening features to -{op-system} before beginning the {product-title} installation. For example, -you can add kernel options when you boot the {op-system} installer -to turn security features on or off, such as SELinux or various -low-level settings, such as symmetric multithreading. - -Although bare metal {op-system} installations are more difficult, -they offer the opportunity of getting operating system -changes in place before starting the {product-title} installation. This can be important when you need to ensure that certain -features, such as disk encryption or special networking settings, be -set up at the earliest possible moment. - -[id="security-harden-during-installation_{context}"] -== Hardening during installation - -You can interrupt the OpenShift installation process and change -Ignition configs. Through Ignition configs, you can add your own files -and systemd services to the {op-system} nodes. -You can also make some basic security-related changes to the `install-config.yaml` file -used for installation. -Contents added in this way are available at each node's first boot. - -[id="security-harden-after-installation_{context}"] -== Hardening after the cluster is running -After the {product-title} cluster is up and running, there are -several ways to apply hardening features to {op-system}: - -* Daemon set: If you need a service to run on every node, you can add -that service with a -link:https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/[Kubernetes `DaemonSet` object]. -* Machine config: `MachineConfig` objects contain a subset of Ignition configs in the same format. -By applying machine configs to all worker or control plane nodes, -you can ensure that the next node of the same type that is added -to the cluster has the same changes applied. - -All of the features noted here are described in the {product-title} -product documentation. diff --git a/modules/security-hardening-what.adoc b/modules/security-hardening-what.adoc deleted file mode 100644 index dea89e45bff7..000000000000 --- a/modules/security-hardening-what.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-hardening.adoc - -[id="security-hardening-what_{context}"] - -= Choosing what to harden in {op-system} -ifdef::openshift-origin[] -The link:https://docs.fedoraproject.org/en-US/Fedora/19/html/Security_Guide/chap-Security_Guide-Basic_Hardening.html[{op-system-base} Security Hardening] guide describes how you should approach security for any -{op-system-base} system. -endif::[] -ifdef::openshift-enterprise,openshift-webscale,openshift-aro[] -The link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/security_hardening/index#scanning-container-and-container-images-for-vulnerabilities_scanning-the-system-for-security-compliance-and-vulnerabilities[{op-system-base} 8 Security Hardening] guide describes how you should approach security for any -{op-system-base} system. -endif::[] - -Use this guide to learn how to approach cryptography, evaluate -vulnerabilities, and assess threats to various services. -Likewise, you can learn how to scan for compliance standards, check file -integrity, perform auditing, and encrypt storage devices. - -With the knowledge of what features you want to harden, you can then -decide how to harden them in {op-system}. diff --git a/modules/security-hosts-vms-openshift.adoc b/modules/security-hosts-vms-openshift.adoc deleted file mode 100644 index 5b2d585b2bc0..000000000000 --- a/modules/security-hosts-vms-openshift.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-hosts-vms.adoc - -[id="security-hosts-vms-openshift_{context}"] -= Securing {product-title} -When you deploy {product-title}, you have the choice of an -installer-provisioned infrastructure (there are several available platforms) -or your own user-provisioned infrastructure. -ifndef::openshift-origin[] -Some low-level security-related configuration, such as enabling FIPS -compliance or adding kernel modules required at first boot, might -benefit from a user-provisioned infrastructure. -endif::[] -ifdef::openshift-origin[] -Some low-level security-related configuration, such as adding kernel modules required at first boot, might -benefit from a user-provisioned infrastructure. -endif::[] -Likewise, user-provisioned infrastructure is appropriate for disconnected {product-title} deployments. - -Keep in mind that, when it comes to making security enhancements and other -configuration changes to {product-title}, the goals should include: - -* Keeping the underlying nodes as generic as possible. You want to be able to -easily throw away and spin up similar nodes quickly and in prescriptive ways. -* Managing modifications to nodes through {product-title} as much as possible, -rather than making direct, one-off changes to the nodes. - -In pursuit of those goals, most node changes should be done during installation through Ignition -or later using MachineConfigs that are applied to sets of nodes by the Machine Config Operator. -Examples of security-related configuration changes you can do in this way include: - -* Adding kernel arguments - -* Adding kernel modules - -* Enabling support for FIPS cryptography - -* Configuring disk encryption - -* Configuring the chrony time service - -Besides the Machine Config Operator, there are several other Operators available to configure {product-title} infrastructure that are managed by the Cluster Version Operator (CVO). The CVO is able to automate many aspects of -{product-title} cluster updates. diff --git a/modules/security-hosts-vms-rhcos.adoc b/modules/security-hosts-vms-rhcos.adoc deleted file mode 100644 index 2dea4d504594..000000000000 --- a/modules/security-hosts-vms-rhcos.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-hosts-vms.adoc - -[id="security-hosts-vms-rhcos_{context}"] -= Securing containers on {op-system-first} - -Containers simplify the act of deploying many applications to run on the same host, -using the same kernel and container runtime to spin up each container. -The applications can be owned by many users and, because they are kept -separate, can run different, and even incompatible, versions of those applications -at the same time without issue. - -In Linux, containers are just a special type of process, so securing -containers is similar in many ways to securing any other running process. -An environment for running containers starts with an operating system -that can secure the host kernel from -containers and other processes running on the host, as well as -secure containers from each other. - -Because {product-title} {product-version} runs on {op-system} hosts, -with the option of using {op-system-base-full} as worker nodes, -the following concepts apply by default to any deployed {product-title} -cluster. These {op-system-base} security features are at the core of what -makes running containers in OpenShift more secure: - -* _Linux namespaces_ enable creating an abstraction of a particular global system -resource to make it appear as a separate instance to processes within a -namespace. Consequently, several containers can use the same computing resource -simultaneously without creating a conflict. -Container namespaces that are separate from the host by default include mount table, process table, -network interface, user, control group, UTS, and IPC namespaces. -Those containers that need direct access to host namespaces need to have -elevated permissions to request that access. -ifdef::openshift-enterprise,openshift-webscale,openshift-aro[] -See -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html/overview_of_containers_in_red_hat_systems/introduction_to_linux_containers#linux_containers_architecture[Overview of Containers in Red Hat Systems] -from the {op-system-base} 7 container documentation for details on the types of namespaces. -endif::[] - -* _SELinux_ provides an additional layer of security to keep containers isolated -from each other and from the host. SELinux allows administrators to enforce -mandatory access controls (MAC) for every user, application, process, and file. - -* _CGroups_ (control groups) limit, account for, and isolate the resource usage -(CPU, memory, disk I/O, network, etc.) of a collection of processes. CGroups are -used to ensure that containers on the same host are not impacted by each other. - -* _Secure computing mode (seccomp)_ profiles can be associated with a container to -restrict available system calls. See page 94 of the -link:https://access.redhat.com/articles/5059881[OpenShift Security Guide] for details about seccomp. - -* Deploying containers using _{op-system}_ reduces the attack surface by -minimizing the host environment and tuning it for containers. -The link:https://access.redhat.com/documentation/en-us/openshift_container_platform/3.11/html-single/cri-o_runtime/index[CRI-O container engine] further reduces that attack surface by -implementing only those features required by Kubernetes and OpenShift to -run and manage containers, as opposed to other container engines -that implement desktop-oriented standalone features. - -{op-system} is a version of {op-system-base-full} that is specially -configured to work as control plane (master) and worker nodes -on {product-title} clusters. -So {op-system} is tuned to efficiently run container workloads, along with -Kubernetes and OpenShift services. - -To further protect {op-system} systems in {product-title} clusters, -most containers, except those managing or monitoring the host system itself, -should run as a non-root user. Dropping the privilege level or -creating containers with the least amount of privileges possible is recommended -best practice for protecting your own {product-title} clusters. diff --git a/modules/security-hosts-vms-vs-containers.adoc b/modules/security-hosts-vms-vs-containers.adoc deleted file mode 100644 index a1339c49c0bf..000000000000 --- a/modules/security-hosts-vms-vs-containers.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-hosts-vms.adoc - -[id="security-hosts-vms-vs-containers_{context}"] -= Comparing virtualization and containers - -Traditional virtualization provides another way to keep application -environments separate on the same physical host. However, virtual machines -work in a different way than containers. -Virtualization relies on a hypervisor spinning up guest -virtual machines (VMs), each of which has its own operating system (OS), -represented by a running kernel, as well as the running application and its dependencies. - -With VMs, the hypervisor isolates the guests from each other and from the host -kernel. Fewer individuals and processes have access to the hypervisor, reducing -the attack surface on the physical server. That said, security must still be -monitored: one guest VM might be able to use hypervisor bugs to gain access to -another VM or the host kernel. And, when the OS needs to be patched, it must be -patched on all guest VMs using that OS. - -Containers can be run inside guest VMs, and there might be use cases where this is -desirable. For example, you might be deploying a traditional application in a -container, perhaps to lift-and-shift an application to the cloud. - -Container separation on a single host, however, provides a more lightweight, -flexible, and easier-to-scale deployment solution. This deployment model is -particularly appropriate for cloud-native applications. Containers are -generally much smaller than VMs and consume less memory and CPU. - -ifndef::openshift-origin[] -See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html/overview_of_containers_in_red_hat_systems/introduction_to_linux_containers#linux_containers_compared_to_kvm_virtualization[Linux Containers Compared to KVM Virtualization] -in the {op-system-base} 7 container documentation to learn about the differences between container and VMs. -endif::[] - diff --git a/modules/security-monitoring-audit-logging.adoc b/modules/security-monitoring-audit-logging.adoc deleted file mode 100644 index fcb2793678b3..000000000000 --- a/modules/security-monitoring-audit-logging.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-monitoring.adoc - -[id="security-monitoring-audit-logs_{context}"] -= Audit logs - -With _audit logs_, you can follow a sequence of activities associated with how a -user, administrator, or other {product-title} component is behaving. -API audit logging is done on each server. diff --git a/modules/security-monitoring-cluster-logging.adoc b/modules/security-monitoring-cluster-logging.adoc deleted file mode 100644 index 8ce294e5f67d..000000000000 --- a/modules/security-monitoring-cluster-logging.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-monitoring.adoc - -[id="security-monitoring-cluster-logging_{context}"] -= Logging - -Using the `oc log` command, you can view container logs, build configs and -deployments in real time. Different can users have access different -access to logs: - -* Users who have access to a project are able to see the logs for that project by default. -* Users with admin roles can access all container logs. - -To save your logs for further audit and analysis, you can enable the `cluster-logging` add-on -feature to collect, manage, and view system, container, and audit logs. -You can deploy, manage, and upgrade OpenShift Logging through the OpenShift Elasticsearch Operator -and Cluster Logging Operator. diff --git a/modules/security-monitoring-events.adoc b/modules/security-monitoring-events.adoc deleted file mode 100644 index b524acb13aed..000000000000 --- a/modules/security-monitoring-events.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-monitoring.adoc - -[id="security-monitoring-events_{context}"] -= Watching cluster events - -Cluster administrators are encouraged to familiarize themselves with the `Event` resource -type and review the list of system events to -determine which events are of interest. -Events are associated with a namespace, either the namespace of the -resource they are related to or, for cluster events, the `default` -namespace. The default namespace holds relevant events for monitoring or auditing a cluster, -such as node events and resource events related to infrastructure components. - -The master API and `oc` command do not provide parameters to scope a listing of events to only those -related to nodes. A simple approach would be to use `grep`: - -[source,terminal] ----- -$ oc get event -n default | grep Node ----- - -.Example output -[source,terminal] ----- -1h 20h 3 origin-node-1.example.local Node Normal NodeHasDiskPressure ... ----- - -A more flexible approach is to output the events in a form that other -tools can process. For example, the following example uses the `jq` -tool against JSON output to extract only `NodeHasDiskPressure` events: - -[source,terminal] ----- -$ oc get events -n default -o json \ - | jq '.items[] | select(.involvedObject.kind == "Node" and .reason == "NodeHasDiskPressure")' ----- - -.Example output -[source,terminal] ----- -{ - "apiVersion": "v1", - "count": 3, - "involvedObject": { - "kind": "Node", - "name": "origin-node-1.example.local", - "uid": "origin-node-1.example.local" - }, - "kind": "Event", - "reason": "NodeHasDiskPressure", - ... -} ----- - -Events related to resource creation, modification, or deletion can also be -good candidates for detecting misuse of the cluster. The following query, -for example, can be used to look for excessive pulling of images: - -[source,terminal] ----- -$ oc get events --all-namespaces -o json \ - | jq '[.items[] | select(.involvedObject.kind == "Pod" and .reason == "Pulling")] | length' ----- - -.Example output -[source,terminal] ----- -4 ----- - -[NOTE] -==== -When a namespace is deleted, its events are deleted as well. Events can also expire and are deleted to prevent -filling up etcd storage. Events are -not stored as a permanent record and frequent polling is necessary to capture statistics over time. -==== diff --git a/modules/security-network-egress.adoc b/modules/security-network-egress.adoc deleted file mode 100644 index 114545e0d852..000000000000 --- a/modules/security-network-egress.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-network.adoc - -[id="security-network-egress_{context}"] -= Securing egress traffic - -{product-title} provides the ability to control egress traffic using either -a router or firewall method. For example, you can use IP whitelisting to control -database access. -A cluster administrator can assign one or more egress IP addresses to a project -in an {product-title} SDN network provider. -Likewise, a cluster administrator can prevent egress traffic from -going outside of an {product-title} cluster using an egress firewall. - -By assigning a fixed egress IP address, you can have all outgoing traffic -assigned to that IP address for a particular project. -With the egress firewall, you can prevent a pod from connecting to an -external network, prevent a pod from connecting to an internal network, -or limit a pod's access to specific internal subnets. diff --git a/modules/security-network-ingress.adoc b/modules/security-network-ingress.adoc deleted file mode 100644 index 78656d4e4b62..000000000000 --- a/modules/security-network-ingress.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-network.adoc - -[id="security-network-ingress_{context}"] -= Securing ingress traffic - -There are many security implications related to how you configure -access to your Kubernetes services from outside of your {product-title} cluster. -Besides exposing HTTP and HTTPS routes, ingress routing allows you to set up -NodePort or LoadBalancer ingress types. NodePort exposes an application's -service API object from each cluster worker. LoadBalancer lets you assign an -external load balancer to an associated service API object -in your {product-title} cluster. diff --git a/modules/security-network-isolating.adoc b/modules/security-network-isolating.adoc deleted file mode 100644 index ae6f1e28b7a1..000000000000 --- a/modules/security-network-isolating.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-network.adoc - -[id="security-network-isolating_{context}"] -= Isolating applications - -{product-title} enables you to segment network traffic on a single cluster to -make multitenant clusters that isolate users, teams, applications, and -environments from non-global resources. diff --git a/modules/security-network-multiple-pod.adoc b/modules/security-network-multiple-pod.adoc deleted file mode 100644 index 9aac96f39c56..000000000000 --- a/modules/security-network-multiple-pod.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-network.adoc - -[id="security-network-multiple-pod_{context}"] -= Using multiple pod networks - -Each running container has only one network interface by default. -The Multus CNI plug-in lets you create multiple CNI networks, and then -attach any of those networks to your pods. In that way, you can do -things like separate private data onto a more restricted network -and have multiple network interfaces on each node. diff --git a/modules/security-network-namespaces.adoc b/modules/security-network-namespaces.adoc deleted file mode 100644 index 3eaa2a678154..000000000000 --- a/modules/security-network-namespaces.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-network.adoc - -[id="security-network-namespaces_{context}"] -= Using network namespaces - -{product-title} uses software-defined networking (SDN) to provide a unified -cluster network that enables communication between containers across the -cluster. - -Network policy mode, by default, makes all pods in a project accessible from -other pods and network endpoints. -To isolate one or more pods in a project, you can create `NetworkPolicy` objects -in that project to indicate the allowed incoming connections. -Using multitenant mode, you can provide project-level isolation for pods and services. diff --git a/modules/security-network-policies.adoc b/modules/security-network-policies.adoc deleted file mode 100644 index 9f514e2c0b14..000000000000 --- a/modules/security-network-policies.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-network.adoc - -[id="security-network-policies_{context}"] -= Isolating pods with network policies - -Using _network policies_, you can isolate pods from each other in the same project. -Network policies can deny all network access to a pod, -only allow connections for the ingress controller, reject connections from -pods in other projects, or set similar rules for how networks behave. diff --git a/modules/security-platform-admission.adoc b/modules/security-platform-admission.adoc deleted file mode 100644 index 1a1c0fa2a33d..000000000000 --- a/modules/security-platform-admission.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-platform.adoc - -[id="security-platform-admission_{context}"] -= Protecting control plane with admission plug-ins - -While RBAC controls access rules between users and groups and available projects, -_admission plug-ins_ define access to the {product-title} master API. -Admission plug-ins form a chain of rules that consist of: - -* Default admissions plug-ins: These implement a default set of -policies and resources limits that are applied to components of the {product-title} -control plane. - -* Mutating admission plug-ins: These plug-ins dynamically extend the admission chain. -They call out to a webhook server and can both authenticate a request and modify the selected resource. - -* Validating admission plug-ins: These validate requests for a selected resource -and can both validate the request and ensure that the resource does not change again. - -API requests go through admissions plug-ins in a chain, with any failure along -the way causing the request to be rejected. Each admission plug-in is associated with particular resources and only -responds to requests for those resources. - -[id="security-deployment-sccs_{context}"] -== Security context constraints (SCCs) - -You can use _security context constraints_ (SCCs) to define a set of conditions -that a pod must run with to be accepted -into the system. - -Some aspects that can be managed by SCCs include: - -- Running of privileged containers -- Capabilities a container can request to be added -- Use of host directories as volumes -- SELinux context of the container -- Container user ID - -If you have the required permissions, you can adjust the default SCC policies to -be more permissive, if required. - -[id="security-service-account_{context}"] -== Granting roles to service accounts - -You can assign roles to service accounts, in the same way that -users are assigned role-based access. -There are three default service accounts created for each project. -A service account: - -* is limited in scope to a particular project -* derives its name from its project -* is automatically assigned an API token and credentials to access the -OpenShift Container Registry - -Service accounts associated with platform components automatically -have their keys rotated. diff --git a/modules/security-platform-authentication.adoc b/modules/security-platform-authentication.adoc deleted file mode 100644 index d5abae6e86af..000000000000 --- a/modules/security-platform-authentication.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-platform.adoc - -[id="security-platform-authentication_{context}"] -= Authentication and authorization - -[id="security-platform-auth-controlling-access_{context}"] -== Controlling access using OAuth - -You can use API access control via authentication and authorization for securing -your container platform. The {product-title} master includes a built-in OAuth -server. Users can obtain OAuth access tokens to authenticate themselves to the -API. - -As an administrator, you can configure OAuth to authenticate using an _identity -provider_, such as LDAP, GitHub, or Google. The -identity provider is used by default for new {product-title} deployments, but -you can configure this at initial installation time or post-installation. - -[id="security-platform-api-access-control_{context}"] -== API access control and management - -Applications can have multiple, independent API services which have different -endpoints that require management. {product-title} includes a containerized -version of the 3scale API gateway so that you can manage your APIs and control -access. - -3scale gives you a variety of standard options for API authentication and -security, which can be used alone or in combination to issue credentials and -control access: standard API keys, application ID and key pair, and OAuth 2.0. - -You can restrict access to specific endpoints, methods, and services and apply -access policy for groups of users. Application plans allow you to set rate -limits for API usage and control traffic flow for groups of developers. - -For a tutorial on using APIcast v2, the containerized 3scale API Gateway, see -link:https://support.3scale.net/docs/deployment-options/apicast-openshift[Running APIcast on Red Hat OpenShift] -in the 3scale documentation. - -[id="security-platform-red-hat-sso_{context}"] -== Red Hat Single Sign-On - -The Red Hat Single Sign-On server enables you to secure your -applications by providing web single sign-on capabilities based on standards, including -SAML 2.0, OpenID Connect, and OAuth 2.0. The server can act as a SAML or OpenID -Connect–based identity provider (IdP), mediating with your enterprise user -directory or third-party identity provider for identity information and your -applications using standards-based tokens. You can integrate Red Hat Single Sign-On with -LDAP-based directory services including Microsoft Active Directory and Red Hat -Enterprise Linux Identity Management. - -[id="security-platform-auth-secure-self-service-web-console_{context}"] -== Secure self-service web console - -{product-title} provides a self-service web console to ensure that teams do not -access other environments without authorization. {product-title} ensures a -secure multitenant master by providing the following: - -- Access to the master uses Transport Layer Security (TLS) -- Access to the API Server uses X.509 certificates or OAuth access tokens -- Project quota limits the damage that a rogue token could do -- The etcd service is not exposed directly to the cluster diff --git a/modules/security-platform-certificates.adoc b/modules/security-platform-certificates.adoc deleted file mode 100644 index 11ac828afbe3..000000000000 --- a/modules/security-platform-certificates.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-platform.adoc - -[id="security-platform-certificates_{context}"] -= Managing certificates for the platform - -{product-title} has multiple components within its framework that use REST-based -HTTPS communication leveraging encryption via TLS certificates. -{product-title}'s installer configures these certificates during -installation. There are some primary components that generate this traffic: - -* masters (API server and controllers) -* etcd -* nodes -* registry -* router - -[id="security-platform-config-custom-certs_{context}"] -== Configuring custom certificates - -You can configure custom serving certificates for the public host names of the -API server and web console during initial installation or when redeploying -certificates. You can also use a custom CA. diff --git a/modules/security-platform-multi-tenancy.adoc b/modules/security-platform-multi-tenancy.adoc deleted file mode 100644 index a1df1b2d6d5c..000000000000 --- a/modules/security-platform-multi-tenancy.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-platform.adoc - -[id="security-platform-multi-tenancy_{context}"] -= Isolating containers with multitenancy - -Multitenancy allows applications on an {product-title} cluster that are owned -by multiple users, and run across multiple hosts and namespaces, -to remain isolated from each other and from outside attacks. -You obtain multitenancy by applying role-based access control (RBAC) -to Kubernetes namespaces. - -In Kubernetes, _namespaces_ are areas where applications can run -in ways that are separate from other applications. -{product-title} uses and extends namespaces by adding extra -annotations, including MCS labeling in SELinux, and identifying -these extended namespaces as _projects_. Within the scope of -a project, users can maintain their own cluster resources, -including service accounts, policies, constraints, -and various other objects. - -RBAC objects are assigned to projects to authorize selected users -to have access to those projects. That authorization takes the form -of rules, roles, and bindings: - -* Rules define what a user can create or access in a project. -* Roles are collections of rules that you can bind to selected users or groups. -* Bindings define the association between users or groups and roles. - -Local RBAC roles and bindings attach a user or group to a -particular project. Cluster RBAC can attach cluster-wide roles and bindings -to all projects in a cluster. There are default -cluster roles that can be assigned to provide `admin`, `basic-user`, `cluster-admin`, -and `cluster-status` access. diff --git a/modules/security-pod-scan-cso.adoc b/modules/security-pod-scan-cso.adoc deleted file mode 100644 index 4240a8e46442..000000000000 --- a/modules/security-pod-scan-cso.adoc +++ /dev/null @@ -1,71 +0,0 @@ -// Module included in the following assemblies: -// -// * security/pod-vulnerabilities-scan.adoc - -[id="security-pod-scan-cso_{context}"] -= Running the Container Security Operator - -You can start the Container Security Operator from the {product-title} -web console by selecting and installing that Operator from the Operator Hub, -as described here. - -.Prerequisites - -* Have administrator privileges to the {product-title} cluster -* Have containers that come from a Red Hat Quay or Quay.io registry running on your cluster - -.Procedure - -. Navigate to *Operators* -> *OperatorHub* and select *Security*. - -. Select the *Container Security* Operator, then select *Install* -to go to the Create Operator Subscription page. - -. Check the settings. All namespaces and automatic approval strategy are selected, by default. - -. Select *Install*. The *Container Security* Operator appears after a few moments on the *Installed Operators* screen. - -. Optionally, you can add custom certificates to the CSO. In this example, create a certificate -named `quay.crt` in the current directory. Then run the following command to add the cert to the CSO: -+ -[source,terminal] ----- -$ oc create secret generic container-security-operator-extra-certs --from-file=quay.crt -n openshift-operators ----- - -. If you added a custom certificate, restart the Operator pod for the new certs to take effect. - -. Open the OpenShift Dashboard (`Home` -> `Overview`). A link to -*Quay Image Security* appears under the status section, with a listing of the number -of vulnerabilities found so far. Select the link to see a *Quay Image Security breakdown*, as shown in the following figure: -+ -image:image_security.png[Access image scanning data from {product-title} dashboard] - -. You can do one of two things at this point to follow up on any detected vulnerabilities: -+ -* Select the link to the vulnerability. You are taken to the container -registry that the container came -from, where you can see information about the vulnerability. The following -figure shows an example of detected vulnerabilities from a Quay.io registry: -+ -image:cso-registry-vulnerable.png[The CSO points you to a registry containing the vulnerable image] -+ -* Select the namespaces link to go to the *ImageManifestVuln* screen, -where you can see the name of the selected image -and all namespaces where that image is running. -The following figure indicates that a particular vulnerable image -is running in the `quay-enterprise` namespace: -+ -image:cso-namespace-vulnerable.png[View namespaces a vulnerable image is running in] - -At this point, you know what images are vulnerable, what -you need to do to fix those vulnerabilities, -and every namespace that the image was run in. So you can: - -* Alert anyone running the image that -they need to correct the vulnerability -* Stop the images from running by deleting the deployment -or other object that started the pod that the image is in - -Note that if you do delete the pod, it may take several minutes -for the vulnerability to reset on the dashboard. diff --git a/modules/security-pod-scan-query-cli.adoc b/modules/security-pod-scan-query-cli.adoc deleted file mode 100644 index a969d8fc31d9..000000000000 --- a/modules/security-pod-scan-query-cli.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * security/pod-vulnerabilities-scan.adoc - -[id="security-pod-scan-query-cli_{context}"] -= Querying image vulnerabilities from the CLI -Using the `oc` command, you can display information about -vulnerabilities detected by the Container Security Operator. - -.Prerequisites -* Be running the Container Security Operator on your -{product-title} instance - -.Procedure - -* To query for detected container image vulnerabilities, type: -+ -[source,terminal] ----- -$ oc get vuln --all-namespaces ----- -+ -.Example output -[source,terminal] ----- -NAMESPACE NAME AGE -default sha256.ca90... 6m56s -skynet sha256.ca90... 9m37s ----- - -* To display details for a particular vulnerability, provide the -vulnerability name and its namespace to the `oc describe` command. -This example shows an active container whose image includes an RPM package with a vulnerability: -+ -[source,terminal] ----- -$ oc describe vuln --namespace mynamespace sha256.ac50e3752... ----- -+ -.Example output -[source,terminal] ----- -Name: sha256.ac50e3752... -Namespace: quay-enterprise -... -Spec: - Features: - Name: nss-util - Namespace Name: centos:7 - Version: 3.44.0-3.el7 - Versionformat: rpm - Vulnerabilities: - Description: Network Security Services (NSS) is a set of libraries... ----- diff --git a/modules/security-registries-ecosystem.adoc b/modules/security-registries-ecosystem.adoc deleted file mode 100644 index 06d49898f7ad..000000000000 --- a/modules/security-registries-ecosystem.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-registries.adoc - -[id="security-registries-ecosystem_{context}"] -= Getting containers from Red Hat Registry and Ecosystem Catalog - -Red Hat lists certified container images for Red Hat products and partner offerings from the -link:https://catalog.redhat.com/software/containers/explore[Container Images] -section of the Red Hat Ecosystem Catalog. From that catalog, -you can see details of each image, including CVE, software packages listings, and health -scores. - -Red Hat images are actually stored in what is referred to as the _Red Hat Registry_, -which is represented by a public container registry (`registry.access.redhat.com`) -and an authenticated registry (`registry.redhat.io`). -Both include basically the same set of container images, with -`registry.redhat.io` including some additional images that require authentication -with Red Hat subscription credentials. - -Container content is monitored for vulnerabilities by Red Hat and updated -regularly. When Red Hat releases security updates, such as fixes to _glibc_, -link:https://access.redhat.com/security/vulnerabilities/drown[DROWN], or -link:https://access.redhat.com/blogs/766093/posts/2757141[Dirty Cow], -any affected container images are also rebuilt and pushed -to the Red Hat Registry. - -Red Hat uses a `health index` to reflect the security risk for each container provided through -the Red Hat Ecosystem Catalog. Because containers consume software provided by Red -Hat and the errata process, old, stale containers are insecure whereas new, -fresh containers are more secure. - -To illustrate the age of containers, the Red Hat Ecosystem Catalog uses a -grading system. A freshness grade is a measure of the oldest and most severe -security errata available for an image. "A" is more up to date than "F". See -link:https://access.redhat.com/articles/2803031[Container Health Index grades as used inside the Red Hat Ecosystem Catalog] for more details on this grading system. - -Refer to the link:https://access.redhat.com/security/[Red Hat Product Security Center] -for details on security updates and vulnerabilities related to Red Hat software. -Check out link:https://access.redhat.com/security/security-updates/#/security-advisories[Red Hat Security Advisories] -to search for specific advisories and CVEs. diff --git a/modules/security-registries-immutable.adoc b/modules/security-registries-immutable.adoc deleted file mode 100644 index ea70e016a38c..000000000000 --- a/modules/security-registries-immutable.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-registries.adoc - -[id="security-registries-immutable_{context}"] -= Immutable and certified containers - -Consuming security updates is particularly important when managing _immutable -containers_. Immutable containers are containers that will never be changed -while running. When you deploy immutable containers, you do not step into the -running container to replace one or more binaries. From an operational -standpoint, you rebuild and redeploy an updated container image -to replace a container instead of changing it. - -Red Hat certified images are: - -* Free of known vulnerabilities in the platform components or layers -* Compatible across the {op-system-base} platforms, from bare metal to cloud -* Supported by Red Hat - -The list of known vulnerabilities is constantly evolving, so you must track the -contents of your deployed container images, as well as newly downloaded images, -over time. You can use -link:https://access.redhat.com/security/security-updates/#/security-advisories[Red Hat Security Advisories (RHSAs)] -to alert you to any newly discovered issues in -Red Hat certified container images, and direct you to the updated image. -Alternatively, you can go to the Red Hat Ecosystem Catalog -to look up that and other security-related issues for each Red Hat image. diff --git a/modules/security-registries-openshift.adoc b/modules/security-registries-openshift.adoc deleted file mode 100644 index 915c0526eb0e..000000000000 --- a/modules/security-registries-openshift.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-registries.adoc - -[id="security-registries-openshift_{context}"] -= OpenShift Container Registry - -{product-title} includes the _OpenShift Container Registry_, a private registry -running as an integrated component of the platform that you can use to manage your container -images. The OpenShift Container Registry provides role-based access controls -that allow you to manage who can pull and push which container images. - -{product-title} also supports integration with other private registries that you might -already be using, such as Red Hat Quay. diff --git a/modules/security-registries-quay.adoc b/modules/security-registries-quay.adoc deleted file mode 100644 index 097cb94fac9a..000000000000 --- a/modules/security-registries-quay.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-registries.adoc - -[id="security-registries-quay_{context}"] -= Storing containers using Red Hat Quay -link:https://access.redhat.com/products/red-hat-quay[Red Hat Quay] is an -enterprise-quality container registry product from Red Hat. -Development for Red Hat Quay is done through the upstream -link:https://docs.projectquay.io/welcome.html[Project Quay]. -Red Hat Quay is available to deploy on-premise or through the hosted -version of Red Hat Quay at link:https://quay.io[Quay.io]. - -Security-related features of Red Hat Quay include: - -* *Time machine*: Allows images with older tags to expire after a set -period of time or based on a user-selected expiration time. - -* *link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#repo-mirroring-in-red-hat-quay[Repository mirroring]*: Lets you mirror -other registries for security reasons, such hosting a public repository -on Red Hat Quay behind a company firewall, or for performance reasons, to -keep registries closer to where they are used. - -* *Action log storage*: Save Red Hat Quay logging output to link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#proc_manage-log-storage[Elasticsearch storage] -to allow for later search and analysis. - -* *link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#quay-security-scanner[Clair security scanning]*: Scan images against a variety of Linux -vulnerability databases, based on the origins of each container image. - -* *Internal authentication*: Use the default local database to handle RBAC -authentication to Red Hat Quay or choose from LDAP, Keystone (OpenStack), -JWT Custom Authentication, or External Application Token authentication. - -* *External authorization (OAuth)*: Allow authorization to Red Hat Quay -from GitHub, GitHub Enterprise, or Google Authentication. - -* *Access settings*: Generate tokens to allow access to Red Hat Quay -from docker, rkt, anonymous access, user-created accounts, encrypted -client passwords, or prefix username autocompletion. - -Ongoing integration of Red Hat Quay with {product-title} continues, -with several {product-title} Operators of particular interest. -The link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#quay-bridge-operator[Quay Bridge Operator] -lets you replace the internal {product-title} registry with Red Hat Quay. -The link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html-single/manage_red_hat_quay/index#container-security-operator-setup[Quay Container Security Operator] -lets you check vulnerabilities of images running in {product-title} that were -pulled from Red Hat Quay registries. diff --git a/modules/security-registries-where.adoc b/modules/security-registries-where.adoc deleted file mode 100644 index c493e3ad587d..000000000000 --- a/modules/security-registries-where.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-registries.adoc - -[id="security-registries-where_{context}"] -= Knowing where containers come from? - -There are tools you can use to scan and track the contents of your downloaded -and deployed container images. However, there are many public sources of -container images. When using public container registries, you can add a layer of -protection by using trusted sources. diff --git a/modules/security-storage-block.adoc b/modules/security-storage-block.adoc deleted file mode 100644 index cfe322f5a73b..000000000000 --- a/modules/security-storage-block.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-storage.adoc - -[id="security-network-storage-block_{context}"] -= Block storage - -For block storage providers like AWS Elastic Block Store (EBS), GCE Persistent -Disks, and iSCSI, {product-title} uses SELinux capabilities to secure the root -of the mounted volume for non-privileged pods, making the mounted volume owned -by and only visible to the container with which it is associated. diff --git a/modules/security-storage-persistent.adoc b/modules/security-storage-persistent.adoc deleted file mode 100644 index c7b24eccec2f..000000000000 --- a/modules/security-storage-persistent.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-storage.adoc - -[id="security-network-storage-persistent_{context}"] -= Persistent volume plug-ins - -Containers are useful for both stateless and stateful applications. -Protecting attached storage is a key element of securing stateful services. -Using the Container Storage Interface (CSI), {product-title} can -incorporate storage from any storage back end that supports the CSI interface. - -{product-title} provides plug-ins for multiple types of storage, including: - -* Red Hat OpenShift Container Storage * -* AWS Elastic Block Stores (EBS) * -* AWS Elastic File System (EFS) * -* Azure Disk * -* Azure File * -* OpenStack Cinder * -* GCE Persistent Disks * -* VMware vSphere * -* Network File System (NFS) -* FlexVolume -* Fibre Channel -* iSCSI - -Plug-ins for those storage types with dynamic provisioning are marked with -an asterisk (*). Data in transit is encrypted via HTTPS for all -{product-title} components communicating with each other. - -You can mount a persistent volume (PV) on a host in any way supported by your -storage type. Different types of storage have different capabilities and each -PV's access modes are set to the specific modes supported by that particular -volume. - -For example, NFS can support multiple read/write clients, but a specific NFS PV -might be exported on the server as read-only. Each PV has its own set of access -modes describing that specific PV's capabilities, such as `ReadWriteOnce`, -`ReadOnlyMany`, and `ReadWriteMany`. diff --git a/modules/security-storage-shared.adoc b/modules/security-storage-shared.adoc deleted file mode 100644 index f6a654b456b0..000000000000 --- a/modules/security-storage-shared.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-storage.adoc - -[id="security-network-storage-shared_{context}"] -= Shared storage - -For shared storage providers like NFS, the PV registers its -group ID (GID) as an annotation on the PV resource. Then, when the PV is claimed -by the pod, the annotated GID is added to the supplemental groups of the pod, -giving that pod access to the contents of the shared storage. diff --git a/modules/security-understanding-containers.adoc b/modules/security-understanding-containers.adoc deleted file mode 100644 index 3023556038ba..000000000000 --- a/modules/security-understanding-containers.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-understanding.adoc - -[id="security-understanding-containers_{context}"] -= What are containers? - -Containers package an application and all its dependencies into a single image -that can be promoted from development, to test, to production, without change. -A container might be part of a larger application that works closely with other -containers. - -Containers provide consistency across environments and multiple deployment -targets: physical servers, virtual machines (VMs), and private or public cloud. - -Some of the benefits of using containers include: - -// image::whatarecontainers.png["What Are Containers?", align="center"] - -[options="header"] -|=== -|Infrastructure |Applications - -|Sandboxed application processes on a shared Linux operating system kernel -|Package my application and all of its dependencies - -|Simpler, lighter, and denser than virtual machines -|Deploy to any environment in seconds and enable CI/CD - -|Portable across different environments -|Easily access and share containerized components -|=== - -See link:https://www.redhat.com/en/topics/containers[Understanding Linux containers] from the Red Hat Customer Portal -to find out more about Linux containers. To learn about RHEL container tools, see -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/building_running_and_managing_containers/index[Building, running, and managing containers] in the RHEL product documentation. diff --git a/modules/security-understanding-openshift.adoc b/modules/security-understanding-openshift.adoc deleted file mode 100644 index 74573db0b328..000000000000 --- a/modules/security-understanding-openshift.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * security/container_security/security-understanding.adoc - -[id="security-understanding-openshift_{context}"] -= What is {product-title}? - -Automating how containerized applications are deployed, run, and managed is the -job of a platform such as {product-title}. At its core, {product-title} relies -on the Kubernetes project to provide the engine for orchestrating containers -across many nodes in scalable data centers. - -Kubernetes is a project, which can run using different operating systems -and add-on components that offer no guarantees of supportability from the project. -As a result, the security of different Kubernetes platforms can vary. - -{product-title} is designed to lock down Kubernetes security and integrate -the platform with a variety of extended components. To do this, -{product-title} draws on the extensive Red Hat ecosystem of open source -technologies that include the operating systems, authentication, storage, -networking, development tools, base container images, and many other -components. - -{product-title} can leverage Red Hat's experience in uncovering -and rapidly deploying fixes for vulnerabilities in the platform itself -as well as the containerized applications running on the platform. -Red Hat's experience also extends to efficiently integrating new -components with {product-title} as they become available and -adapting technologies to individual customer needs. diff --git a/modules/select-policy-lifecycle.adoc b/modules/select-policy-lifecycle.adoc new file mode 100644 index 000000000000..d29bc2caabc8 --- /dev/null +++ b/modules/select-policy-lifecycle.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="select-policy-lifecycle_{context}"] += Selecting the policy lifecycle stage + +[role="_abstract"] +Select the lifecycle stage when the policy is used. For more information, see "Understanding the {product-title-short} policy evaluation engine". + +.Procedure + +. Select the *Lifecycle stages* when the policy is used: *Build*, *Deploy*, or *Runtime*. +You can select more than one stage from the following choices: +* Build-time policies apply to image fields such as CVEs and Dockerfile instructions. +* Deploy-time policies can include all build-time policy criteria but they can also include user-pod interaction that has been configured in your cluster, such as running in privileged mode or mounting the Docker socket. +* Runtime policies can include all build-time and deploy-time policy criteria but they can also include data about process executions during runtime. You can further configure runtime policies to trigger policy violations based on the deployment events or audit logs. ++ +. If you selected the *Runtime* lifecycle stage, you must select one of the following *Event sources*: +* *Deployment*: {product-title-short} triggers policy violations when events occur during deployment, such as process activity in running pods, network or process deviations from the baseline, and user pod interaction such as using the `exec` command in a pod or pod port forwarding. +* *Audit logs*: {product-title-short} triggers policy violations when event sources match Kubernetes audit log records. +. Click *Next*. \ No newline at end of file diff --git a/modules/selecting-policy-notifiers.adoc b/modules/selecting-policy-notifiers.adoc new file mode 100644 index 000000000000..e51539402c8d --- /dev/null +++ b/modules/selecting-policy-notifiers.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/custom-security-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="selecting-policy-notifiers_{context}"] += Selecting policy notifiers + +[role="_abstract"] +You can attach notifiers to the policy to send policy violations to email recipients or external tooling such as Jira, Splunk, or other applications that use webhooks. + +.Prerequisite + +* You must have previously configured the notification before it is visible and available to select in the list. You configure these integrations in the *Platform Configuration* -> *Integrations* page, in the *Notifier Integrations* section. + +.Procedure + +. Select the notifier that {product-title-short} will use to inform you when a policy is violated. +. Click *Next*. \ No newline at end of file diff --git a/modules/semantic-difference-output.adoc b/modules/semantic-difference-output.adoc new file mode 100644 index 000000000000..973e2f5d875c --- /dev/null +++ b/modules/semantic-difference-output.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: PROCEDURE +[id="semantic-difference-output_{context}"] += Semantic difference output + +.Procedure + +* Run the following command to analyze the connectivity differences between the Kubernetes manifests and network policies in the two specified directories: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl netpol connectivity diff --dir1=roxctl/netpol/connectivity/diff/testdata/netpol-analysis-example-minimal/ --dir2=roxctl/netpol/connectivity/diff/testdata/netpol-diff-example-minimal +---- ++ +.Example output ++ +[source,text,subs="+quotes"] +---- +Connectivity diff: +diff-type: changed, source: default/frontend[Deployment], destination: default/backend[Deployment], dir1: TCP 9090, dir2: TCP 9090,UDP 53 +diff-type: added, source: 0.0.0.0-255.255.255.255, destination: default/backend[Deployment], dir1: No Connections, dir2: TCP 9090 +---- \ No newline at end of file diff --git a/modules/send-alerts-to-different-slack-channels.adoc b/modules/send-alerts-to-different-slack-channels.adoc new file mode 100644 index 000000000000..43173dbd7d0f --- /dev/null +++ b/modules/send-alerts-to-different-slack-channels.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-slack.adoc +:_mod-docs-content-type: PROCEDURE +[id="send-alerts-to-different-slack-channels_{context}"] += Sending alerts to different Slack channels + +[role="_abstract"] +You can configure {product-title} to send notifications to different Slack channels so that they directly go to the right team. + + +.Procedure +. After you configure incoming webhooks, add an annotation similar to the following in your deployment YAML file: ++ +[source,yaml] +---- +example.com/slack-webhook: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX +---- +. Use the annotation key `example.com/slack-webhook` in the *Label/Annotation Key For Slack Webhook* field when you configure {product-title}. + +After the configuration is complete, if a deployment has the annotation that you configured in the YAML file, {product-title} sends the alert to the webhook URL you specified for that annotation. Otherwise, it sends the alert to the default webhook URL. diff --git a/modules/sensor-upgrade-section.adoc b/modules/sensor-upgrade-section.adoc new file mode 100644 index 000000000000..ac89afd4acbe --- /dev/null +++ b/modules/sensor-upgrade-section.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/use-system-health-dashboard.adoc + +:_mod-docs-content-type: REFERENCE +[id="sensor-upgrade-section_{context}"] += Sensor upgrade section + +The *Sensor upgrade* section organizes the information into the following groups: + +Up to date:: Indicates that Sensor is running the latest supported version. +Failed:: Indicates that Sensor has encountered issues during the upgrade process and requires immediate attention. +Out of date:: Indicates that Sensor is running on an older version that you need to update. +Unavailable:: Indicates the components or services that are unreachable or nonfunctional. +Uninitialized:: Indicates the components or services that are not yet set up or are in the process of initialization. +Total:: Indicates the total count of clusters being monitored in the system. \ No newline at end of file diff --git a/modules/serverless-about-collecting-data.adoc b/modules/serverless-about-collecting-data.adoc deleted file mode 100644 index f94a9b8b3ce0..000000000000 --- a/modules/serverless-about-collecting-data.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/serverless-support.adoc - -[id="serverless-about-collecting-data_{context}"] -= About collecting {ServerlessProductName} data - -You can use the `oc adm must-gather` CLI command to collect information about your cluster, including features and objects associated with {ServerlessProductName}. -To collect {ServerlessProductName} data with `must-gather`, you must specify the {ServerlessProductName} image. - -.Procedure - -* Enter the command: -+ - -[source,terminal] ----- -$ oc adm must-gather --image=registry.redhat.io/openshift-serverless-1/svls-must-gather-rhel8 ----- diff --git a/modules/serverless-access-custom-domain.adoc b/modules/serverless-access-custom-domain.adoc deleted file mode 100644 index f1adf08fee31..000000000000 --- a/modules/serverless-access-custom-domain.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-custom-domains.adoc - -[id="serverless-access-custom-domain_{context}"] -= Accessing a service using your custom domain - -.Procedure - -. Access the custom domain by using the `Host` header in a `curl` request. For example: -+ - -[source,terminal] ----- -$ curl -H "Host: custom-ksvc-domain.example.com" http://<ip_address> ----- - -+ -where `<ip_address>` is the IP address that the {product-title} ingress router is exposed to. -+ - -.Example output -[source,terminal] ----- -Hello OpenShift! ----- diff --git a/modules/serverless-apps-intro.adoc b/modules/serverless-apps-intro.adoc deleted file mode 100644 index c39cb77f1e99..000000000000 --- a/modules/serverless-apps-intro.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative_serving/serverless-knative-serving.adoc -// serverless/serving-creating-managing-apps.adoc - -[id="serverless-about-services_{context}"] -= Serverless applications using Knative services - -To deploy a serverless application using {ServerlessProductName}, you must create a _Knative service_. -Knative services are Kubernetes services, defined by a route and a configuration, and contained in a YAML file. - -.Example Knative service YAML - -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: hello <1> - namespace: default <2> -spec: - template: - spec: - containers: - - image: docker.io/openshift/hello-openshift <3> - env: - - name: RESPONSE <4> - value: "Hello Serverless!" ----- - -<1> The name of the application. -<2> The namespace the application will use. -<3> The image of the application. -<4> The environment variable printed out by the sample application. - -You can create a serverless application by using one of the following methods: - -* Create a Knative service from the {product-title} web console. -* Create a Knative service using the `kn` CLI. -* Create and apply a YAML file. diff --git a/modules/serverless-channel-default.adoc b/modules/serverless-channel-default.adoc deleted file mode 100644 index 2b7099820003..000000000000 --- a/modules/serverless-channel-default.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-channel-default_{context}"] -= Configuring the default channel implementation - -The `default-ch-webhook` config map can be used to specify the default channel implementation for the cluster or for one or more namespaces. - -You can make changes to the `knative-eventing` namespace config maps, including the `default-ch-webhook` config map, by using the {ServerlessOperatorName} to propagate changes. -To do this, you must modify the `KnativeEventing` custom resource. - -.Prerequisites - -* You have cluster administrator permissions on {product-title}. -* You have installed the {ServerlessOperatorName} and Knative Eventing on your cluster. - -.Procedure - -* Modify the `KnativeEventing` custom resource to add configuration details for the `default-ch-webhook` config map: -+ -[source,yaml] ----- -apiVersion: operator.knative.dev/v1alpha1 -kind: KnativeEventing -metadata: - name: knative-eventing - namespace: knative-eventing -spec: - config: <1> - default-ch-webhook: <2> - default-ch-config: | - clusterDefault: <3> - apiVersion: messaging.knative.dev/v1 - kind: InMemoryChannel - spec: - delivery: - backoffDelay: PT0.5S - backoffPolicy: exponential - retry: 5 - namespaceDefaults: <4> - my-namespace: - apiVersion: messaging.knative.dev/v1beta1 - kind: KafkaChannel - spec: - numPartitions: 1 - replicationFactor: 1 ----- -<1> In `spec.config`, you can specify the config maps that you want to add modified configurations for. -<2> The `default-ch-webhook` config map can be used to specify the default channel implementation for the cluster or for one or more namespaces. -<3> The cluster-wide default channel type configuration. In this example, the default channel implementation for the cluster is `InMemoryChannel`. -<4> The namespace-scoped default channel type configuration. In this example, the default channel implementation for the `my-namespace` namespace is `KafkaChannel`. -+ -[IMPORTANT] -==== -Configuring a namespace-specific default overrides any cluster-wide settings. -==== diff --git a/modules/serverless-channels-creating-intro.adoc b/modules/serverless-channels-creating-intro.adoc deleted file mode 100644 index 7ddfcb9c41db..000000000000 --- a/modules/serverless-channels-creating-intro.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-channels-creating-intro_{context}"] -= Creating channels - -Developers can create channels by instantiating a supported `Channel` object. - -After you create a `Channel` object, a mutating admission webhook adds a set of `spec.channelTemplate` properties for the `Channel` object based on the default channel implementation. -For example, for an `InMemoryChannel` default implementation, the `Channel` object looks as follows: - -[source,yaml] ----- -apiVersion: messaging.knative.dev/v1 -kind: Channel -metadata: - name: example-channel - namespace: default -spec: - channelTemplate: - apiVersion: messaging.knative.dev/v1 - kind: InMemoryChannel ----- - -[NOTE] -==== -The `spec.channelTemplate` properties cannot be changed after creation, because they are set by the default channel mechanism rather than by the user. -==== - -The channel controller then creates the backing channel instance based on the `spec.channelTemplate` configuration. - -When this mechanism is used with the example above, two objects are created: a generic backing channel and an `InMemoryChannel` channel. -If you are using a different default channel implementation, for example, Apache Kafka, a generic backing channel and `KafkaChannel` channel are created. - -The backing channel acts as a proxy that copies its subscriptions to the user-created channel object, and sets the user-created channel object status to reflect the status of the backing channel. diff --git a/modules/serverless-cluster-sizing-req.adoc b/modules/serverless-cluster-sizing-req.adoc deleted file mode 100644 index 2fef4bc8e7af..000000000000 --- a/modules/serverless-cluster-sizing-req.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/installing_serverless/installing-openshift-serverless.adoc - -[id="serverless-cluster-sizing-req_{context}"] -= Defining cluster size requirements for an {ServerlessProductName} installation - -To install and use {ServerlessProductName}, the {product-title} cluster must be sized correctly. -The minimum requirement for {ServerlessProductName} is a cluster with 10 CPUs and 40GB memory. -The total size requirements to run {ServerlessProductName} are dependent on the applications deployed. By default, each pod requests approximately 400m of CPU, so the minimum requirements are based on this value. -In the size requirement provided, an application can scale up to 10 replicas. Lowering the actual CPU request of applications can increase the number of possible replicas. - -[NOTE] -==== -The requirements provided relate only to the pool of worker machines of the {product-title} cluster. Master nodes are not used for general scheduling and are omitted from the requirements. -==== - -[NOTE] -==== -The following limitations apply to all {ServerlessProductName} deployments: - -* Maximum number of Knative services: 1000 -* Maximum number of Knative revisions: 1000 -==== diff --git a/modules/serverless-config-replicas.adoc b/modules/serverless-config-replicas.adoc deleted file mode 100644 index a00f871da2f0..000000000000 --- a/modules/serverless-config-replicas.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/serverless-HA.adoc - -[id="serverless-config-replicas_{context}"] -= Configuring high availability replicas on {ServerlessProductName} - -High availability (HA) functionality is available by default on {ServerlessProductName} for the `autoscaler-hpa`, `controller`, `activator`, `kourier-control`, and `kourier-gateway` controllers. These components are configured with two replicas by default. - -You modify the number of replicas that are created per controller by changing the configuration of `KnativeServing.spec.highAvailability` in the KnativeServing custom resource definition. -// This field also specifies the minimum number of _activators_ if you are using the horizontal pod autoscaler (HPA). For more information about HPA, see - -.Prerequisites -* An {product-title} account with cluster administrator access. -* Installed the {ServerlessOperatorName} and Knative Serving. - -.Procedure - -. In the {product-title} web console *Administrator* perspective, navigate to *OperatorHub* -> *Installed Operators*. -+ -image::serving-installed-operator.png[Installed Operators page] -+ -. Select the `knative-serving` namespace. -+ -. Click *Knative Serving* in the list of *Provided APIs* for the {ServerlessOperatorName} to go to the *Knative Serving* tab. -+ -image::serving-tab-created.png[Knative Serving tab] -+ -. Click *knative-serving*, then go to the *YAML* tab in the *knative-serving* page. -+ -image::serving-YAML-HA.png[Knative Serving YAML] -+ -. Edit the custom resource definition YAML: -+ -.Example YAML -[source,yaml] ----- -apiVersion: operator.knative.dev/v1alpha1 -kind: KnativeServing -metadata: - name: knative-serving - namespace: knative-serving -spec: - high-availability: - replicas: 3 ----- -+ -[IMPORTANT] -==== -Do not modify any YAML contained inside the `config` field. Some of the configuration values in this field are injected by the {ServerlessOperatorName}, and modifying them will cause your deployment to become unsupported. -==== -+ -* The default `replicas` value is `2`. -* Changing the value to `1` will disable HA, or you can increase the number of replicas as required. The example configuration shown specifies a replica count of `3` for all HA controllers. diff --git a/modules/serverless-connect-channel-source-odc.adoc b/modules/serverless-connect-channel-source-odc.adoc deleted file mode 100644 index ab33dbc884b8..000000000000 --- a/modules/serverless-connect-channel-source-odc.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-connect-channel-source-odc_{context}"] -= Connect an event source to a channel using the Developer perspective - -You can create multiple event source types in {product-title} that can be connected to channels. - -.Prerequisites -To connect an event source to a channel using the *Developer* perspective, ensure that: - -* The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. -* You have logged in to the web console. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. -* You have created a channel by following the documentation on _Creating a channel using {product-title} web console_. - -.Procedure -. Create an event source of any type, by following the documentation on _Getting started with event sources_. -. In the *Developer* perspective, navigate to *Event Sources*. -. In the *Sink* section of the *Event Sources* form view, select *Resource*. Then use the drop-down to select your channel. -+ -image::sink-pingsource-channel.png[Use your channel as the Resource] -. Click *Create*. - -.Verification -You can verify that the event source was created and is connected to the sink by viewing the *Topology* page. - -. In the *Developer* perspective, navigate to *Topology*. -. View the event source and click on the connected channel to see the channel details in the side panel. -+ -image::serverless-verify-source-channel.png[View the source and connected channel] diff --git a/modules/serverless-create-broker-kn.adoc b/modules/serverless-create-broker-kn.adoc deleted file mode 100644 index 2a4f6255740d..000000000000 --- a/modules/serverless-create-broker-kn.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-create-broker-kn_{context}"] -= Creating a broker using the Knative CLI - -.Prerequisites -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. - -.Procedure -* Create the `default` broker: -+ -[source,terminal] ----- -$ kn broker create default ----- - -.Verification - -. Use the `kn` command to list all existing brokers: -+ -[source,terminal] ----- -$ kn broker list ----- -+ -.Example output -[source,terminal] ----- -NAME URL AGE CONDITIONS READY REASON -default http://broker-ingress.knative-eventing.svc.cluster.local/test/default 45s 5 OK / 5 True ----- - -. Optional: If you are using the {product-title} web console, you can navigate to the **Topology** view in the **Developer** perspective, and observe that the broker exists: -+ -image::odc-view-broker.png[View the broker in the web console Topology view] diff --git a/modules/serverless-create-channel-kn.adoc b/modules/serverless-create-channel-kn.adoc deleted file mode 100644 index 24a7a098277e..000000000000 --- a/modules/serverless-create-channel-kn.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-create-channel-kn_{context}"] -= Creating a channel using the Knative CLI - -You can create a channel with the cluster default configuration by using the `kn` CLI. - -.Prerequisites - -To create channels using the `kn` CLI, ensure that: - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. - -.Procedure - -* Create a channel: -+ -[source,terminal] ----- -$ kn channel create <channel_name> --type <channel_type> ----- -+ -The channel type is optional, but where specified, must be given in the format `Group:Version:Kind`. -For example, you can create an `InMemoryChannel` object: -+ -[source,terminal] ----- -$ kn channel create mychannel --type messaging.knative.dev:v1:InMemoryChannel ----- -+ -.Example output -[source,terminal] ----- -Channel 'mychannel' created in namespace 'default'. ----- - -.Verification - -* To confirm that the channel now exists, list the existing channels and inspect the output: -+ -[source,terminal] ----- -$ kn channel list ----- -+ -.Example output -[source,terminal] ----- -kn channel list -NAME TYPE URL AGE READY REASON -mychannel InMemoryChannel http://mychannel-kn-channel.default.svc.cluster.local 93s True ----- diff --git a/modules/serverless-create-channel-odc.adoc b/modules/serverless-create-channel-odc.adoc deleted file mode 100644 index 4294119235d2..000000000000 --- a/modules/serverless-create-channel-odc.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-create-channel-odc_{context}"] -= Creating a channel using the Developer perspective - -You can create a channel with the cluster default configuration by using the {product-title} web console. - -.Prerequisites -To create channels using the *Developer* perspective ensure that: - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have logged in to the web console. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. - -.Procedure - -. In the *Developer* perspective, navigate to *+Add* -> *Channel*. -. Select the type of `Channel` object that you want to create from the *Type* drop-down. -+ -[NOTE] -==== -Currently only InMemoryChannel type `Channel` objects are supported. -==== -. Click *Create*. - -.Verification - -* Confirm that the channel now exists by navigating to the *Topology* page. -+ -image::verify-channel-odc.png[View the channel in the Topology view] diff --git a/modules/serverless-create-default-channel-yaml.adoc b/modules/serverless-create-default-channel-yaml.adoc deleted file mode 100644 index e813b1013889..000000000000 --- a/modules/serverless-create-default-channel-yaml.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-create-default-channel-yaml_{context}"] -= Creating a default implementation channel by using YAML - -You can create a channel by using YAML with the cluster default configuration. - -.Prerequisites - -* {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. - -.Procedure - -To create a `Channel` object: - -. Create a YAML file and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: messaging.knative.dev/v1 -kind: Channel -metadata: - name: example-channel - namespace: default ----- -. Apply the YAML file: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- diff --git a/modules/serverless-create-domain-mapping.adoc b/modules/serverless-create-domain-mapping.adoc deleted file mode 100644 index 16f625bfa8f8..000000000000 --- a/modules/serverless-create-domain-mapping.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-domain-mapping.adoc - -[id="serverless-create-domain-mapping_{context}"] -= Creating custom domain mapping for a service - -To map a custom domain name to a service you must create a `DomainMapping` custom resource (CR). - -.Prerequisites - -* The {ServerlessOperatorName} and Knative Serving are installed on your cluster. -* You have created a Knative service and control a custom domain that you want to map to that service. -+ -[NOTE] -==== -Your custom domain must point to the DNS of the {product-title} cluster. -==== - -.Procedure - -. Create a YAML file containing the `DomainMapping` CR in the same namespace as the Knative service you want to map to: -+ -[source,yaml] ----- -apiVersion: serving.knative.dev/v1alpha1 -kind: DomainMapping -metadata: - name: <domain_name> <1> - namespace: <namespace> <2> -spec: - ref: - name: <service_name> <3> - kind: Service - apiVersion: serving.knative.dev/v1 ----- -<1> The custom domain name that you want to map to the service. -<2> The namespace of both the `DomainMapping` CR and the Knative service. -<3> The name of the service to map to the custom domain. - -. Apply the `DomainMapping` CR as a YAML file: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- diff --git a/modules/serverless-create-kafka-channel-yaml.adoc b/modules/serverless-create-kafka-channel-yaml.adoc deleted file mode 100644 index 7644c0537b82..000000000000 --- a/modules/serverless-create-kafka-channel-yaml.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc -// * serverless/serverless-kafka.adoc - -[id="serverless-create-kafka-channel-yaml_{context}"] -= Creating a Kafka channel by using YAML - -You can create a Kafka channel by using YAML to create the `KafkaChannel` object. - -.Prerequisites - -* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resource are installed on your {product-title} cluster. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. - -.Procedure - -. Create a YAML file and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: messaging.knative.dev/v1beta1 -kind: KafkaChannel -metadata: - name: example-channel - namespace: default -spec: - numPartitions: 3 - replicationFactor: 1 ----- -. Apply the YAML file: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- diff --git a/modules/serverless-create-kn-trigger.adoc b/modules/serverless-create-kn-trigger.adoc deleted file mode 100644 index 6fe99dd6c9e2..000000000000 --- a/modules/serverless-create-kn-trigger.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-create-kn-trigger_{context}"] -= Creating a trigger using `kn` - -You can create a trigger by using the `kn trigger create` command. - -.Procedure - -* Create a trigger: -+ -[source,terminal] ----- -$ kn trigger create <trigger_name> --broker <broker_name> --filter <key=value> --sink <sink_name> ----- -+ -Alternatively, you can create a trigger and simultaneously create the `default` broker using broker injection: -+ -[source,terminal] ----- -$ kn trigger create <trigger_name> --inject-broker --filter <key=value> --sink <sink_name> ----- -+ -By default, triggers forward all events sent to a broker to sinks that are subscribed to that broker. -Using the `--filter` attribute for triggers allows you to filter events from a broker, so that subscribers will only receive a subset of events based on your defined criteria. diff --git a/modules/serverless-create-trigger-odc.adoc b/modules/serverless-create-trigger-odc.adoc deleted file mode 100644 index 1a0989947f27..000000000000 --- a/modules/serverless-create-trigger-odc.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * /serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-create-trigger-odc_{context}"] -= Creating a trigger using the Developer perspective - -After you have created a broker, you can create a trigger in the web console *Developer* perspective. - -.Prerequisites - -* The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. -* You have logged in to the web console. -* You are in the *Developer* perspective. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. -* You have created a broker and a Knative service or other event sink to connect to the trigger. - -.Procedure - -. In the *Developer* perspective, navigate to the *Topology* page. -. Hover over the broker that you want to create a trigger for, and drag the arrow. The *Add Trigger* option is displayed. -+ -image::add-trigger-odc.png[Create a trigger for the broker] -. Click *Add Trigger*. -. Select your sink as a *Subscriber* from the drop-down list. -+ -. Click *Add*. - -.Verification -* After the subscription has been created, it is represented as a line that connects the broker to the service in the *Topology* view: -+ -image::verify-trigger-odc.png[Trigger in the Topology view] diff --git a/modules/serverless-creating-broker-admin-web-console.adoc b/modules/serverless-creating-broker-admin-web-console.adoc deleted file mode 100644 index 43d32a7abb09..000000000000 --- a/modules/serverless-creating-broker-admin-web-console.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/admin_guide/serverless-cluster-admin-eventing.adoc - -[id="serverless-creating-broker-admin-web-console_{context}"] -= Creating a broker by using the Administrator perspective - -If you have cluster administrator permissions, you can create a broker by using the Administrator perspective in the web console. - -.Prerequisites - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have cluster administrator permissions for {product-title}. - -.Procedure - -. In the *Administrator* perspective of the {product-title} web console, navigate to *Serverless* -> *Eventing*. -. In the *Create* list, select *Broker*. You will be directed to the *Create Broker* page. -. Optional: Modify the YAML configuration for the broker. -. Click *Create*. diff --git a/modules/serverless-creating-broker-admin.adoc b/modules/serverless-creating-broker-admin.adoc deleted file mode 100644 index 5c3e75dafa2f..000000000000 --- a/modules/serverless-creating-broker-admin.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-creating-broker-admin_{context}"] -= Creating a broker by labeling a namespace - -If you have cluster administrator permissions, you can create the `default` broker automatically by labeling a namespace. - -[NOTE] -==== -Brokers created using this method will not be removed if you remove the label. You must manually delete them. -==== - -.Prerequisites -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have cluster administrator permissions for {product-title}. - -.Procedure - -* Label a namespace with `eventing.knative.dev/injection=enabled`: -+ -[source,terminal] ----- -$ oc label namespace <namespace> eventing.knative.dev/injection=enabled ----- - -.Verification - -You can verify that the broker has been created successfully by using the `oc` CLI, or by observing it in the *Topology* view in the web console. - -. Use the `oc` command to get the broker: -+ -[source,terminal] ----- -$ oc -n <namespace> get broker <broker_name> ----- -+ -.Example command -[source,terminal] ----- -$ oc -n default get broker default ----- -+ -.Example output -[source,terminal] ----- -NAME READY REASON URL AGE -default True http://broker-ingress.knative-eventing.svc.cluster.local/test/default 3m56s ----- - -. Navigate to the *Topology* view in the web console, and observe that the broker exists: -+ -image::odc-view-broker.png[View the broker in the web console Topology view] diff --git a/modules/serverless-creating-broker-annotation.adoc b/modules/serverless-creating-broker-annotation.adoc deleted file mode 100644 index 5330e60fbbb5..000000000000 --- a/modules/serverless-creating-broker-annotation.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-creating-broker-annotation_{context}"] -= Creating a broker by annotating a trigger - -You can create a broker by adding the `eventing.knative.dev/injection: enabled` annotation to a `Trigger` object. - -[IMPORTANT] -==== -If you create a broker by using the `eventing.knative.dev/injection: enabled` annotation, you cannot delete this broker without cluster administrator permissions. -If you delete the broker without having a cluster administrator remove this annotation first, the broker is created again after deletion. -==== - -.Prerequisites -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. - -.Procedure -. Create a `Trigger` object as a `.yaml` file that has the `eventing.knative.dev/injection: enabled` annotation: -+ -[source,yaml] ----- -apiVersion: eventing.knative.dev/v1 -kind: Trigger -metadata: - annotations: - eventing.knative.dev/injection: enabled - name: <trigger-name> -spec: - broker: default - subscriber: <1> - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: <service-name> ----- -+ -<1> Specify details about the event sink, or _subscriber_, that the trigger sends events to. -. Apply the `.yaml` file: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- - -.Verification - -You can verify that the broker has been created successfully by using the `oc` CLI, or by observing it in the *Topology* view in the web console. - -. Use the `oc` command to get the broker: -+ -[source,terminal] ----- -$ oc -n <namespace> get broker default ----- -+ -.Example output -[source,terminal] ----- -NAME READY REASON URL AGE -default True http://broker-ingress.knative-eventing.svc.cluster.local/test/default 3m56s ----- - -. Navigate to the *Topology* view in the web console, and observe that the broker exists: -+ -image::odc-view-broker.png[View the broker in the web console Topology view] diff --git a/modules/serverless-creating-channel-admin-web-console.adoc b/modules/serverless-creating-channel-admin-web-console.adoc deleted file mode 100644 index 9e2a13c4cf65..000000000000 --- a/modules/serverless-creating-channel-admin-web-console.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/admin_guide/serverless-cluster-admin-eventing.adoc - -[id="serverless-creating-channel-admin-web-console_{context}"] -= Creating a channel by using the Administrator perspective - -If you have cluster administrator permissions, you can create a channel by using the Administrator perspective in the web console. - -.Prerequisites - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have cluster administrator permissions for {product-title}. - -.Procedure - -. In the *Administrator* perspective of the {product-title} web console, navigate to *Serverless* -> *Eventing*. -. In the *Create* list, select *Channel*. You will be directed to the *Channel* page. -. Select the type of `Channel` object that you want to create from the *Type* drop-down. -+ -[NOTE] -==== -Currently only `InMemoryChannel` channel objects are supported by default. Kafka channels are available as a Technology Preview if you have installed Apache Kafka on {ServerlessProductName}. -==== -. Click *Create*. diff --git a/modules/serverless-creating-event-source-admin-web-console.adoc b/modules/serverless-creating-event-source-admin-web-console.adoc deleted file mode 100644 index c91b97cfa218..000000000000 --- a/modules/serverless-creating-event-source-admin-web-console.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/admin_guide/serverless-cluster-admin-eventing.adoc - -[id="serverless-creating-event-source-admin-web-console_{context}"] -= Creating an event source by using the Administrator perspective - -If you have cluster administrator permissions, you can create an event source by using the Administrator perspective in the web console. - -.Prerequisites - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have cluster administrator permissions for {product-title}. - -.Procedure - -. In the *Administrator* perspective of the {product-title} web console, navigate to *Serverless* -> *Eventing*. -. In the *Create* list, select *Event Source*. You will be directed to the *Event Sources* page. -. Select the event source type that you want to create. diff --git a/modules/serverless-creating-subscription-admin-web-console.adoc b/modules/serverless-creating-subscription-admin-web-console.adoc deleted file mode 100644 index e01b8298aeae..000000000000 --- a/modules/serverless-creating-subscription-admin-web-console.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/admin_guide/serverless-cluster-admin-eventing.adoc - -[id="serverless-creating-subscription-admin-web-console_{context}"] -= Creating a subscription by using the Administrator perspective - -If you have cluster administrator permissions and have created a channel, you can create a subscription to connect your broker to a subscriber by using the Administrator perspective in the web console. - -.Prerequisites - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have cluster administrator permissions for {product-title}. -* You have created a channel. -* You have created a Knative service to use as a subscriber. - -.Procedure - -. In the *Administrator* perspective of the {product-title} web console, navigate to *Serverless* -> *Eventing*. -. In the *Channel* tab, select the Options menu {kebab} for the channel that you want to add a subscription to. -. Click *Add Subscription* in the list. -. In the *Add Subscription* dialogue box, select a *Subscriber* for the subscription. The subscriber is the Knative service that will receive events from the channel. -. Click *Add*. diff --git a/modules/serverless-creating-subscriptions-kn.adoc b/modules/serverless-creating-subscriptions-kn.adoc deleted file mode 100644 index c2641522078c..000000000000 --- a/modules/serverless-creating-subscriptions-kn.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-subs.adoc - -[id="serverless-creating-subscriptions-kn_{context}"] -= Creating subscriptions using the Knative CLI - -You can create a subscription to connect a channel to a sink by using the `kn` CLI. - -.Prerequisites - -To create subscriptions using the `kn` CLI, ensure that: - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. - -.Procedure - -* Create a subscription to connect a sink to a channel: -+ -[source,terminal] ----- -$ kn subscription create <subscription_name> \ - --channel <group:version:kind>:<channel_name> \ <1> - --sink <sink_prefix>:<sink_name> \ <2> - --sink-dead-letter <sink_prefix>:<sink_name> <3> ----- -<1> `--channel` specifies the source for cloud events that should be processed. You must provide the channel name. If you are not using the default `InMemoryChannel` channel that is backed by the `Channel` resource, you must prefix the channel name with the `<group:version:kind>` for the specified channel type. For example, this will be `messaging.knative.dev:v1beta1:KafkaChannel` for a Kafka backed channel. -<2> `--sink` specifies the target destination to which the event should be delivered. By default, the `<sink_name>` is interpreted as a Knative service of this name, in the same namespace as the subscription. You can specify the type of the sink by using one of the following prefixes: -`ksvc`:: A Knative service. -`channel`:: A channel that should be used as destination. Only default channel types can be referenced here. -`broker`:: An Eventing broker. -<3> Optional: `--sink-dead-letter` is an optional flag that can be used to specify a sink which events should be sent to in cases where events fail to be delivered. For more information, see the {ServerlessProductName} _Event delivery_ documentation. -+ -.Example command -[source,terminal] ----- -$ kn subscription create mysubscription --channel mychannel --sink ksvc:event-display ----- -+ -.Example output -[source,terminal] ----- -Subscription 'mysubscription' created in namespace 'default'. ----- - -.Verification - -* To confirm that the channel is connected to the event sink, or _subscriber_, by a subscription, list the existing subscriptions and inspect the output: -+ -[source,terminal] ----- -$ kn subscription list ----- -+ -.Example output -[source,terminal] ----- -NAME CHANNEL SUBSCRIBER REPLY DEAD LETTER SINK READY REASON -mysubscription Channel:mychannel ksvc:event-display True ----- diff --git a/modules/serverless-creating-subscriptions-odc.adoc b/modules/serverless-creating-subscriptions-odc.adoc deleted file mode 100644 index 5105cc9d8219..000000000000 --- a/modules/serverless-creating-subscriptions-odc.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-creating-subscriptions-odc_{context}"] -= Creating subscriptions in the Developer perspective - -.Prerequisites -To create subscriptions using the *Developer* perspective, ensure that: - -* The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. -* You have logged in to the web console. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. -* You have created an event sink, such as a Knative service, and a channel. - -.Procedure -. In the *Developer* perspective, navigate to the *Topology* page. -. Create a subscription using one of the following methods: -.. Hover over the channel that you want to create a subscription for, and drag the arrow. The *Add Subscription* option is displayed. -+ -image::create-sub-ODC.png[Create a subscription for the channel] -+ -... Select your sink as a subscriber from the drop-down list. -... Click *Add*. -.. If the service is available in the *Topology* view under the same namespace or project as the channel, click on the channel that you want to create a subscription for, and drag the arrow directly to a service to immediately create a subscription from the channel to that service. - - -.Verification -* After the subscription has been created, you can see it represented as a line that connects the channel to the service in the *Topology* view: -+ -image::verify-subscription-odc.png[Subscription in the Topology view] -+ -You can view the event source, channel, and subscriptions for the sink by clicking on the service. diff --git a/modules/serverless-creating-subscriptions-yaml.adoc b/modules/serverless-creating-subscriptions-yaml.adoc deleted file mode 100644 index 622c85d17a36..000000000000 --- a/modules/serverless-creating-subscriptions-yaml.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// <List assemblies here, each on a new line> -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-creating-subscriptions-yaml_{context}"] -= Creating subscriptions by using YAML - -You can create a subscription to connect a channel to a sink by using YAML. - -.Procedure - -* Create a `Subscription` object. -** Create a YAML file and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: messaging.knative.dev/v1beta1 -kind: Subscription -metadata: - name: my-subscription <1> - namespace: default -spec: - channel: <2> - apiVersion: messaging.knative.dev/v1beta1 - kind: Channel - name: example-channel - delivery: <3> - deadLetterSink: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: error-handler - subscriber: <4> - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display ----- -+ -<1> Name of the subscription. -<2> Configuration settings for the channel that the subscription connects to. -<3> Configuration settings for event delivery. This tells the subscription what happens to events that cannot be delivered to the subscriber. When this is configured, events that failed to be consumed are sent to the `deadLetterSink`. The event is dropped, no re-delivery of the event is attempted, and an error is logged in the system. The `deadLetterSink` value must be a link:https://pkg.go.dev/knative.dev/pkg/apis/duck/v1?tab=doc#Destination[Destination]. -<4> Configuration settings for the subscriber. This is the event sink that events are delivered to from the channel. -** Apply the YAML file: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- diff --git a/modules/serverless-creating-trigger-admin-web-console.adoc b/modules/serverless-creating-trigger-admin-web-console.adoc deleted file mode 100644 index cdd0acc8b152..000000000000 --- a/modules/serverless-creating-trigger-admin-web-console.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/admin_guide/serverless-cluster-admin-eventing.adoc - -[id="serverless-creating-trigger-admin-web-console_{context}"] -= Creating a trigger by using the Administrator perspective - -If you have cluster administrator permissions and have created a broker, you can create a trigger to connect your broker to a subscriber by using the Administrator perspective in the web console. - -.Prerequisites - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have cluster administrator permissions for {product-title}. -* You have created a broker. -* You have created a Knative service to use as a subscriber. - -.Procedure - -. In the *Administrator* perspective of the {product-title} web console, navigate to *Serverless* -> *Eventing*. -. In the *Broker* tab, select the Options menu {kebab} for the broker that you want to add a trigger to. -. Click *Add Trigger* in the list. -. In the *Add Trigger* dialogue box, select a *Subscriber* for the trigger. The subscriber is the Knative service that will receive events from the broker. -. Click *Add*. diff --git a/modules/serverless-delete-channel-kn.adoc b/modules/serverless-delete-channel-kn.adoc deleted file mode 100644 index 3afccfcb04c0..000000000000 --- a/modules/serverless-delete-channel-kn.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-channels.adoc - -[id="serverless-delete-channel-kn_{context}"] -= Deleting a channel using the Knative CLI - -You can delete a channel with the cluster default configuration by using the `kn` CLI. - -.Procedure - -* Delete a channel: -+ -[source,terminal] ----- -$ kn channel delete <channel_name> ----- diff --git a/modules/serverless-delete-trigger-odc.adoc b/modules/serverless-delete-trigger-odc.adoc deleted file mode 100644 index ab396c8be354..000000000000 --- a/modules/serverless-delete-trigger-odc.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * /serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-delete-trigger-odc_{context}"] -= Deleting a trigger using the Developer perspective - -You can delete triggers in the web console *Developer* perspective. - -.Prerequisites -* To delete a trigger using the *Developer* perspective, ensure that you have logged in to the web console. - -.Procedure - -. In the *Developer* perspective, navigate to the *Topology* page. -. Click on the trigger that you want to delete. -. In the *Actions* context menu, select *Delete Trigger*. -+ -image::delete-trigger-odc.png[Delete a trigger] diff --git a/modules/serverless-deleting-broker-admin.adoc b/modules/serverless-deleting-broker-admin.adoc deleted file mode 100644 index 4e3be55fb1c8..000000000000 --- a/modules/serverless-deleting-broker-admin.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-deleting-broker-admin_{context}"] -= Deleting a broker that was created by injection - -Brokers created by injection, by using a namespace label or trigger annotation, are not deleted permanently if a developer removes the label or annotation. -A user with cluster administrator permissions must manually delete these brokers. - -.Procedure - -. Remove the `eventing.knative.dev/injection=enabled` label from the namespace: -+ -[source,terminal] ----- -$ oc label namespace <namespace> eventing.knative.dev/injection- ----- -+ -Removing the annotation prevents Knative from recreating the broker after you delete it. - -. Delete the broker from the selected namespace: -+ -[source,terminal] ----- -$ oc -n <namespace> delete broker <broker_name> ----- - -.Verification - -* Use the `oc` command to get the broker: -+ -[source,terminal] ----- -$ oc -n <namespace> get broker <broker_name> ----- -+ -.Example command -[source,terminal] ----- -$ oc -n default get broker default ----- -+ -.Example output -[source,terminal] ----- -No resources found. -Error from server (NotFound): brokers.eventing.knative.dev "default" not found ----- diff --git a/modules/serverless-deleting-subscriptions-kn.adoc b/modules/serverless-deleting-subscriptions-kn.adoc deleted file mode 100644 index 12a228bb6aaa..000000000000 --- a/modules/serverless-deleting-subscriptions-kn.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-subs.adoc - -[id="serverless-deleting-subscriptions-kn_{context}"] -= Deleting subscriptions using the Knative CLI - -You can delete a subscription by using the `kn` CLI. - -.Procedure - -* Delete a subscription: -+ -[source,terminal] ----- -$ kn subscription delete <subscription_name> ----- diff --git a/modules/serverless-describe-broker-kn.adoc b/modules/serverless-describe-broker-kn.adoc deleted file mode 100644 index 8df6cd419861..000000000000 --- a/modules/serverless-describe-broker-kn.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-describe-broker-kn_{context}"] -= Describing an existing broker using the Knative CLI - -.Prerequisites -* The {ServerlessOperatorName}, Knative Serving and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. - -.Procedure -* Describe an existing broker: -+ -[source,terminal] ----- -$ kn broker describe <broker_name> ----- -+ -.Example command using default broker -[source,terminal] ----- -$ kn broker describe default ----- -+ -.Example output -[source,terminal] ----- -Name: default -Namespace: default -Annotations: eventing.knative.dev/broker.class=MTChannelBasedBroker, eventing.knative.dev/creato ... -Age: 22s - -Address: - URL: http://broker-ingress.knative-eventing.svc.cluster.local/default/default - -Conditions: - OK TYPE AGE REASON - ++ Ready 22s - ++ Addressable 22s - ++ FilterReady 22s - ++ IngressReady 22s - ++ TriggerChannelReady 22s ----- diff --git a/modules/serverless-describe-subs-kn.adoc b/modules/serverless-describe-subs-kn.adoc deleted file mode 100644 index 99266c6b3cc2..000000000000 --- a/modules/serverless-describe-subs-kn.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-subs.adoc - -[id="serverless-describe-subs-kn_{context}"] -= Describing subscriptions using the Knative CLI - -You can print information about a subscription in the terminal by using the `kn` CLI. - -.Prerequisites - -To describe subscriptions using the `kn` CLI, ensure that: - -* You have installed the `kn` CLI. -* You have created a subscription in your cluster. - -.Procedure - -* Describe a subscription: -+ -[source,terminal] ----- -$ kn subscription describe <subscription_name> ----- -+ -.Example output -[source,terminal] ----- -Name: my-subscription -Namespace: default -Annotations: messaging.knative.dev/creator=openshift-user, messaging.knative.dev/lastModifier=min ... -Age: 43s -Channel: Channel:my-channel (messaging.knative.dev/v1) -Subscriber: - URI: http://edisplay.default.example.com -Reply: - Name: default - Resource: Broker (eventing.knative.dev/v1) -DeadLetterSink: - Name: my-sink - Resource: Service (serving.knative.dev/v1) - -Conditions: - OK TYPE AGE REASON - ++ Ready 43s - ++ AddedToChannel 43s - ++ ChannelReady 43s - ++ ReferencesResolved 43s ----- diff --git a/modules/serverless-document-attributes.adoc b/modules/serverless-document-attributes.adoc deleted file mode 100644 index 9a789135b1e7..000000000000 --- a/modules/serverless-document-attributes.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Standard document attributes to be used in the documentation -// -// The following are shared by all documents: -:toc: -:toclevels: 4 -:experimental: -// -// Product content attributes, that is, substitution variables in the files. -// -:ServerlessProductName: OpenShift Serverless -:ServerlessProductShortName: Serverless -:ServerlessOperatorName: OpenShift Serverless Operator -// -// Documentation publishing attributes used in the master-docinfo.xml file -// Note that the DocInfoProductName generates the URL for the product page. -// Changing the value changes the generated URL. -// -:DocInfoProductName: OpenShift Serverless -// -// Book Names: -// Defining the book names in document attributes instead of hard-coding them in -// the master.adoc files and in link references. This makes it easy to change the -// book name if necessary. -// Using the pattern ending in 'BookName' makes it easy to grep for occurrences -// throughout the topics -// diff --git a/modules/serverless-event-delivery-component-behaviors.adoc b/modules/serverless-event-delivery-component-behaviors.adoc deleted file mode 100644 index 08d5ac457609..000000000000 --- a/modules/serverless-event-delivery-component-behaviors.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/event_workflows/serverless-event-delivery.adoc - -[id="serverless-event-delivery-component-behaviors_{context}"] -= Event delivery behavior for Knative Eventing channels - -Different Knative Eventing channel types have their own behavior patterns that are followed for event delivery. Developers can set event delivery parameters in the subscription configuration to ensure that any events that fail to be delivered from channels to an event sink are retried. You must also configure a dead letter sink for subscriptions if you want to provide a sink where events that are not eventually delivered can be stored, otherwise undelivered events are dropped. - -== Event delivery behavior for Apache Kafka channels - -If an event is successfully delivered to a Kafka channel or broker receiver, the receiver responds with a `202` status code, which means that the event has been safely stored inside a Kafka topic and is not lost. If the receiver responds with any other status code, the event is not safely stored, and steps must be taken by the user to resolve this issue. - -== Delivery failure status codes - -The channel or broker receiver can respond with the following status codes if an event fails to be delivered: - -`500`:: This is a generic status code which means that the event was not delivered successfully. -`404`:: This status code means that the channel or broker the event is being delivered to does not exist, or that the `Host` header is incorrect. -`400`:: This status code means that the event being sent to the receiver is invalid. diff --git a/modules/serverless-getting-support.adoc b/modules/serverless-getting-support.adoc deleted file mode 100644 index c75531527a08..000000000000 --- a/modules/serverless-getting-support.adoc +++ /dev/null @@ -1,15 +0,0 @@ -//// -Module included in the following assemblies: -- /serverless/serverless-release-notes.adoc -//// - -[id="serverless-getting-support_{context}"] -= Getting support - -If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can: - -* Search or browse through the Red Hat Knowledgebase of technical support articles about Red Hat products -* Submit a support case to Red Hat Global Support Services (GSS) -* Access other product documentation - -If you have a suggestion for improving this guide or have found an error, please submit a Bugzilla report at http://bugzilla.redhat.com against *Product* for the *Documentation* component. Please provide specific details, such as the section number, guide name, and {ServerlessProductName} version so we can easily locate the content. diff --git a/modules/serverless-install-eventing-web-console.adoc b/modules/serverless-install-eventing-web-console.adoc deleted file mode 100644 index 2db402936a93..000000000000 --- a/modules/serverless-install-eventing-web-console.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/installing_serverless/installing-knative-eventing.adoc - -[id="serverless-install-eventing-web-console_{context}"] -= Installing Knative Eventing using the web console - -.Procedure -. In the *Administrator* perspective of the {product-title} web console, navigate to *Operators* → *Installed Operators*. -. Check that the *Project* dropdown at the top of the page is set to *Project: knative-eventing*. -. Click *Knative Eventing* in the list of *Provided APIs* for the {ServerlessOperatorName} to go to the *Knative Eventing* tab. -+ -image::eventing-installed-operator.png[Installed Operators page] -. Click the *Create Knative Eventing* button. -+ -image::serverless-create-eventing.png[Knative Eventing tab] -. In the *Create Knative Eventing* page, you can choose to configure the `KnativeEventing` object by using either the default form provided, or by editing the YAML. -+ -* Using the form is recommended for simpler configurations that do not require full control of `KnativeEventing` object creation. -+ -Optional. If you are configuring the `KnativeEventing` object using the form, make any changes that you want to implement for your Knative Eventing deployment. -. Click *Create*. -+ -image::eventing-form-view.png[Create Knative Eventing using the form] -+ -* Editing the YAML is recommended for more complex configurations that require full control of `KnativeEventing` object creation. You can access the YAML by clicking the *edit YAML* link in the top right of the *Create Knative Eventing* page. -+ -Optional. If you are configuring the `KnativeEventing` object by editing the YAML, make any changes to the YAML that you want to implement for your Knative Eventing deployment. -. Click *Create*. -+ -image::serverless-create-eventing-yaml.png[Create Knative Eventing using YAML] -. After you have installed Knative Eventing, the `KnativeEventing` object is created, and you will be automically directed to the *Knative Eventing* tab. -+ -image::eventing-tab-created.png[Installed Operators page] -+ -You will see the `knative-eventing` custom resource in the list of resources. - -.Verification -. Click on the `knative-eventing` custom resource in the *Knative Eventing* tab. -. You will be automatically directed to the *Knative Eventing Overview* page. -+ -image::eventing-overview.png[Knative Eventing Overview page] -. Scroll down to look at the list of *Conditions*. -. You should see a list of conditions with a status of *True*, as shown in the example image. -+ -image::eventing-conditions-true.png[Conditions] -+ -[NOTE] -==== -It may take a few seconds for the Knative Eventing resources to be created. You can check their status in the *Resources* tab. -==== -. If the conditions have a status of *Unknown* or *False*, wait a few moments and then check again after you have confirmed that the resources have been created. diff --git a/modules/serverless-install-eventing-yaml.adoc b/modules/serverless-install-eventing-yaml.adoc deleted file mode 100644 index 3bddea625448..000000000000 --- a/modules/serverless-install-eventing-yaml.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/installing_serverless/installing-knative-eventing.adoc - -[id="serverless-install-eventing-yaml_{context}"] -= Installing Knative Eventing using YAML - -.Procedure - -. Create a file named `eventing.yaml`. -. Copy the following sample YAML into `eventing.yaml`: -+ -[source,yaml] ----- -apiVersion: operator.knative.dev/v1alpha1 -kind: KnativeEventing -metadata: - name: knative-eventing - namespace: knative-eventing ----- -. Optional. Make any changes to the YAML that you want to implement for your Knative Eventing deployment. -. Apply the `eventing.yaml` file by entering: -+ -[source,terminal] ----- -$ oc apply -f eventing.yaml ----- - -.Verification - -. Verify the installation is complete by entering the following command and observing the output: -+ -[source,terminal] ----- -$ oc get knativeeventing.operator.knative.dev/knative-eventing \ - -n knative-eventing \ - --template='{{range .status.conditions}}{{printf "%s=%s\n" .type .status}}{{end}}' ----- -+ -.Example output -[source,terminal] ----- -InstallSucceeded=True -Ready=True ----- -+ -[NOTE] -==== -It may take a few seconds for the Knative Eventing resources to be created. -==== -. If the conditions have a status of `Unknown` or `False`, wait a few moments and then check again after you have confirmed that the resources have been created. -. Check that the Knative Eventing resources have been created by entering: -+ -[source,terminal] ----- -$ oc get pods -n knative-eventing ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -broker-controller-58765d9d49-g9zp6 1/1 Running 0 7m21s -eventing-controller-65fdd66b54-jw7bh 1/1 Running 0 7m31s -eventing-webhook-57fd74b5bd-kvhlz 1/1 Running 0 7m31s -imc-controller-5b75d458fc-ptvm2 1/1 Running 0 7m19s -imc-dispatcher-64f6d5fccb-kkc4c 1/1 Running 0 7m18s ----- diff --git a/modules/serverless-install-kafka-odc.adoc b/modules/serverless-install-kafka-odc.adoc deleted file mode 100644 index c5976e024c9c..000000000000 --- a/modules/serverless-install-kafka-odc.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/serverless-kafka.adoc - -[id="serverless-install-kafka-odc_{context}"] -= Installing Apache Kafka components by using the web console - -Cluster administrators can enable the use of Apache Kafka functionality in an {ServerlessProductName} deployment by instantiating the `KnativeKafka` custom resource definition provided by the *Knative Kafka* {ServerlessOperatorName} API. - -.Prerequisites - -* You have installed {ServerlessProductName}, including Knative Eventing, in your {product-title} cluster. -* You have access to a Red Hat AMQ Streams cluster. -* You have cluster administrator permissions on {product-title}. -* You are logged in to the web console. - -.Procedure - -. In the *Administrator* perspective, navigate to *Operators* -> *Installed Operators*. -. Check that the *Project* dropdown at the top of the page is set to *Project: knative-eventing*. -. In the list of *Provided APIs* for the {ServerlessOperatorName}, find the *Knative Kafka* box and click *Create Instance*. -. Configure the *KnativeKafka* object in the *Create Knative Kafka* page. -+ -[IMPORTANT] -==== -To use the Kafka channel or Kafka source on your cluster, you must toggle the *Enable* switch for the options you want to use to *true*. These switches are set to *false* by default. Additionally, to use the Kafka channel, you must specify the Boostrap Servers. -==== -.. Using the form is recommended for simpler configurations that do not require full control of *KnativeKafka* object creation. -.. Editing the YAML is recommended for more complex configurations that require full control of *KnativeKafka* object creation. You can access the YAML by clicking the *Edit YAML* link in the top right of the *Create Knative Kafka* page. -. Click *Create* after you have completed any of the optional configurations for Kafka. You are automatically directed to the *Knative Kafka* tab where *knative-kafka* is in the list of resources. - -.Verification - -. Click on the *knative-kafka* resource in the *Knative Kafka* tab. You are automatically directed to the *Knative Kafka Overview* page. -. View the list of *Conditions* for the resource and confirm that they have a status of *True*. -+ -image::knative-kafka-overview.png[Kafka Knative Overview page showing Conditions] -+ -If the conditions have a status of *Unknown* or *False*, wait a few moments to refresh the page. -. Check that the Knative Kafka resources have been created: -+ -[source,terminal] ----- -$ oc get pods -n knative-eventing ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -kafka-ch-controller-85f879d577-xcbjh 1/1 Running 0 44s -kafka-ch-dispatcher-55d76d7db8-ggqjl 1/1 Running 0 44s -kafka-controller-manager-bc994c465-pt7qd 1/1 Running 0 40s -kafka-webhook-54646f474f-wr7bb 1/1 Running 0 42s ----- diff --git a/modules/serverless-install-serving-web-console.adoc b/modules/serverless-install-serving-web-console.adoc deleted file mode 100644 index bf4292203582..000000000000 --- a/modules/serverless-install-serving-web-console.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/installing_serverless/installing-knative-serving.adoc - -[id="serverless-install-serving-web-console_{context}"] -= Installing Knative Serving using the web console - -.Procedure -. In the *Administrator* perspective of the {product-title} web console, navigate to *Operators* -> *Installed Operators*. -. Check that the *Project* dropdown at the top of the page is set to *Project: knative-serving*. -. Click *Knative Serving* in the list of *Provided APIs* for the {ServerlessOperatorName} to go to the *Knative Serving* tab. -+ -image::serving-installed-operator.png[Installed Operators page] -. Click the *Create Knative Serving* button. -+ -image::serverless-create-serving.png[Knative Serving tab] -. In the *Create Knative Serving* page, you can install Knative Serving using the default settings by clicking *Create*. -+ -You can also modify settings for the Knative Serving installation by editing the `KnativeServing` object using either the form provided, or by editing the YAML. -+ -* Using the form is recommended for simpler configurations that do not require full control of `KnativeServing` object creation. -* Editing the YAML is recommended for more complex configurations that require full control of `KnativeServing` object creation. You can access the YAML by clicking the *edit YAML* link in the top right of the *Create Knative Serving* page. -+ -After you complete the form, or have finished modifying the YAML, click *Create*. -+ -[NOTE] -==== -For more information about configuration options for the KnativeServing custom resource definition, see the documentation on _Advanced installation configuration options_. -==== -+ -image::serving-form-view.png[Create Knative Serving in Form View] -+ -image::serverless-create-serving-yaml.png[Create Knative Serving in YAML view] -. After you have installed Knative Serving, the `KnativeServing` object is created, and you will be automically directed to the *Knative Serving* tab. -+ -image::serving-tab-created.png[Installed Operators page] -+ -You will see the `knative-serving` custom resource in the list of resources. - -.Verification -. Click on `knative-serving` custom resource in the *Knative Serving* tab. -. You will be automatically directed to the *Knative Serving Overview* page. -+ -image::serving-overview.png[Installed Operators page] -. Scroll down to look at the list of *Conditions*. -. You should see a list of conditions with a status of *True*, as shown in the example image. -+ -image::serving-conditions-true.png[Conditions] -+ -[NOTE] -==== -It may take a few seconds for the Knative Serving resources to be created. You can check their status in the *Resources* tab. -==== -. If the conditions have a status of *Unknown* or *False*, wait a few moments and then check again after you have confirmed that the resources have been created. diff --git a/modules/serverless-install-serving-yaml.adoc b/modules/serverless-install-serving-yaml.adoc deleted file mode 100644 index f1cfd6f45cb7..000000000000 --- a/modules/serverless-install-serving-yaml.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/installing_serverless/installing-knative-serving.adoc - -[id="serverless-install-serving-yaml_{context}"] -= Installing Knative Serving using YAML - -.Procedure - -. Create a file named `serving.yaml` and copy the following example YAML into it: -+ -[source,yaml] ----- -apiVersion: operator.knative.dev/v1alpha1 -kind: KnativeServing -metadata: - name: knative-serving - namespace: knative-serving ----- -. Apply the `serving.yaml` file: -+ -[source,terminal] ----- -$ oc apply -f serving.yaml ----- - -.Verification - -. To verify the installation is complete, enter the following command: -+ -[source,terminal] ----- -$ oc get knativeserving.operator.knative.dev/knative-serving -n knative-serving --template='{{range .status.conditions}}{{printf "%s=%s\n" .type .status}}{{end}}' ----- -+ -.Example output -[source,terminal] ----- -DependenciesInstalled=True -DeploymentsAvailable=True -InstallSucceeded=True -Ready=True ----- -+ -[NOTE] -==== -It may take a few seconds for the Knative Serving resources to be created. -==== -. If the conditions have a status of `Unknown` or `False`, wait a few moments and then check again after you have confirmed that the resources have been created. -. Check that the Knative Serving resources have been created by entering: -+ -[source,terminal] ----- -$ oc get pods -n knative-serving ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -activator-5c596cf8d6-5l86c 1/1 Running 0 9m37s -activator-5c596cf8d6-gkn5k 1/1 Running 0 9m22s -autoscaler-5854f586f6-gj597 1/1 Running 0 9m36s -autoscaler-hpa-78665569b8-qmlmn 1/1 Running 0 9m26s -autoscaler-hpa-78665569b8-tqwvw 1/1 Running 0 9m26s -controller-7fd5655f49-9gxz5 1/1 Running 0 9m32s -controller-7fd5655f49-pncv5 1/1 Running 0 9m14s -kn-cli-downloads-8c65d4cbf-mt4t7 1/1 Running 0 9m42s -webhook-5c7d878c7c-n267j 1/1 Running 0 9m35s ----- diff --git a/modules/serverless-install-web-console.adoc b/modules/serverless-install-web-console.adoc deleted file mode 100644 index 733e968aa105..000000000000 --- a/modules/serverless-install-web-console.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * /serverless/installing_serverless/installing-openshift-serverless.adoc - -[id="serverless-install-web-console_{context}"] -= Installing the {ServerlessOperatorName} - -This procedure describes how to install and subscribe to the {ServerlessOperatorName} from the OperatorHub using the {product-title} web console. - -.Procedure - -. In the {product-title} web console, navigate to the *Operators* -> *OperatorHub* page. -. Scroll, or type they keyword *Serverless* into the *Filter by keyword box* to find the {ServerlessOperatorName}. -+ -image::serverless-search.png[{ServerlessOperatorName} in the {product-title} web console] - -. Review the information about the Operator and click *Install*. -. On the *Install Operator* page: -.. The *Installation Mode* is *All namespaces on the cluster (default)*. This mode installs the Operator in the default `openshift-serverless` namespace to watch and be made available to all namespaces in the cluster. -.. The *Installed Namespace* will be `openshift-serverless`. -.. Select the *4.6* channel as the *Update Channel*. The *4.6* channel will enable installation of the latest stable release of the {ServerlessOperatorName}. -.. Select *Automatic* or *Manual* approval strategy. -. Click *Install* to make the Operator available to the selected namespaces on this {product-title} cluster. -. From the *Catalog* -> *Operator Management* page, you can monitor the {ServerlessOperatorName} subscription’s installation and upgrade progress. -.. If you selected a *Manual* approval strategy, the subscription’s upgrade status will remain *Upgrading* until you review and approve its install plan. After approving on the *Install Plan* page, the subscription upgrade status moves to *Up to date*. -.. If you selected an *Automatic* approval strategy, the upgrade status should resolve to *Up to date* without intervention. - -.Verification - -After the Subscription’s upgrade status is *Up to date*, select *Catalog* -> *Installed Operators* to verify that the {ServerlessOperatorName} eventually shows up and its *Status* ultimately resolves to *InstallSucceeded* in the relevant namespace. - -If it does not: - -. Switch to the *Catalog* -> *Operator Management* page and inspect the *Operator Subscriptions* and *Install Plans* tabs for any failure or errors under *Status*. -. Check the logs in any pods in the `openshift-serverless` project on the *Workloads* -> *Pods* page that are reporting issues to troubleshoot further. diff --git a/modules/serverless-installing-cli-linux-rpm.adoc b/modules/serverless-installing-cli-linux-rpm.adoc deleted file mode 100644 index 33e87a88fd4a..000000000000 --- a/modules/serverless-installing-cli-linux-rpm.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative-client.adoc - -[id="installing-cli-linux-rpm_{context}"] -= Installing the `kn` CLI for Linux using an RPM - -For Red Hat Enterprise Linux (RHEL), you can install `kn` as an RPM if you have an active {product-title} subscription on your Red Hat account. - - -.Procedure -. Enter the command: -+ - -[source,terminal] ----- -# subscription-manager register ----- - -. Enter the command: -+ - -[source,terminal] ----- -# subscription-manager refresh ----- - -. Enter the command: -+ - -[source,terminal] ----- -# subscription-manager attach --pool=<pool_id> <1> ----- -+ -<1> Pool ID for an active {product-title} subscription - -. Enter the command: -+ - -[source,terminal] ----- -# subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-x86_64-rpms" ----- - -. Enter the command: -+ - -[source,terminal] ----- -# yum install openshift-serverless-clients ----- diff --git a/modules/serverless-installing-cli-linux.adoc b/modules/serverless-installing-cli-linux.adoc deleted file mode 100644 index 3b5ed859dfa0..000000000000 --- a/modules/serverless-installing-cli-linux.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative-client.adoc - -[id="installing-cli-linux_{context}"] -= Installing the `kn` CLI for Linux - -For Linux distributions, you can download the CLI directly as a `tar.gz` archive. - - -.Procedure - -. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest[CLI]. - -. Unpack the archive: -+ - -[source,terminal] ----- -$ tar -xf <file> ----- - -. Move the `kn` binary to a directory on your PATH. - -. To check your path, run: -+ - -[source,terminal] ----- -$ echo $PATH ----- - -+ -[NOTE] -==== -If you do not use RHEL or Fedora, ensure that *libc* is installed in a directory on your library path. -If *libc* is not available, you might see the following error when you run CLI commands: - -[source,terminal] ----- -$ kn: No such file or directory ----- -==== diff --git a/modules/serverless-installing-cli-macos.adoc b/modules/serverless-installing-cli-macos.adoc deleted file mode 100644 index f297ea64d966..000000000000 --- a/modules/serverless-installing-cli-macos.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative-client.adoc - -[id="installing-cli-macosx_{context}"] -= Installing the `kn` CLI for macOS - -`kn` for macOS is provided as a `tar.gz` archive. - -.Procedure - -. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest[CLI]. - -. Unpack and unzip the archive. - -. Move the `kn` binary to a directory on your PATH. - -. To check your PATH, open a terminal window and run: -+ - -[source,terminal] ----- -$ echo $PATH ----- - - -// For future release: -// Alternatively, Mac OS X users can install the CLI using link:http://brew.sh/[Homebrew] and run the command: -// ---- -// $ brew install TBD -// ---- diff --git a/modules/serverless-installing-cli-web-console.adoc b/modules/serverless-installing-cli-web-console.adoc deleted file mode 100644 index b9a02bb7bf36..000000000000 --- a/modules/serverless-installing-cli-web-console.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative-client.adoc - -[id="installing-cli-web-console_{context}"] -= Installing the `kn` CLI using the {product-title} web console - -Once the {ServerlessOperatorName} is installed, you will see a link to download the `kn` CLI for Linux, macOS and Windows from the *Command Line Tools* page in the {product-title} web console. - -You can access the *Command Line Tools* page by clicking the image:../images/question-circle.png[title="Help"] icon in the top right corner of the web console and selecting *Command Line Tools* in the drop down menu. - -.Procedure - -. Download the `kn` CLI from the *Command Line Tools* page. -. Unpack the archive: -+ - -[source,terminal] ----- -$ tar -xf <file> ----- - -. Move the `kn` binary to a directory on your PATH. - -. To check your path, run: -+ - -[source,terminal] ----- -$ echo $PATH ----- - -+ -[NOTE] -==== -If you do not use RHEL or Fedora, ensure that *libc* is installed in a directory on your library path. -If *libc* is not available, you might see the following error when you run CLI commands: - -[source,terminal] ----- -$ kn: No such file or directory ----- - -==== diff --git a/modules/serverless-installing-cli-windows.adoc b/modules/serverless-installing-cli-windows.adoc deleted file mode 100644 index f05bd80b4664..000000000000 --- a/modules/serverless-installing-cli-windows.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/installing-knative-client.adoc - -[id="installing-cli-windows_{context}"] -= Installing the `kn` CLI for Windows - -The CLI for Windows is provided as a zip archive. - -.Procedure - -. Download the link:https://mirror.openshift.com/pub/openshift-v4/clients/serverless/latest[CLI]. - -. Unzip the archive with a ZIP program. - -. Move the `kn` binary to a directory on your PATH. - -. To check your PATH, open the Command Prompt and run the command: -+ - -[source,terminal] ----- -C:\> path ----- diff --git a/modules/serverless-jaeger-config.adoc b/modules/serverless-jaeger-config.adoc deleted file mode 100644 index cc101d80d4d4..000000000000 --- a/modules/serverless-jaeger-config.adoc +++ /dev/null @@ -1,83 +0,0 @@ -// Module included in the following assemblies: -// -// * /serverless/serverless-tracing.adoc -// */jaeger/jaeger_config/serverless-jaeger-integration.adoc - -[id="serverless-jaeger-config_{context}"] -= Configuring Jaeger for use with {ServerlessProductName} - -.Prerequisites - -To configure Jaeger for use with {ServerlessProductName}, you will need: - -* Cluster administrator permissions on an {product-title} cluster. -* A current installation of {ServerlessOperatorName} and Knative Serving. -* A current installation of the Jaeger Operator. - -.Procedure - -. Create and apply a Jaeger custom resource YAML file that contains the following sample YAML: -+ - -.Jaeger custom resource YAML -+ - -[source,terminal] ----- -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: jaeger - namespace: default ----- - -. Enable tracing for Knative Serving, by editing the `KnativeServing` resource and adding a YAML configuration for tracing. -+ - -.Tracing YAML example -+ - -[source,yaml] ----- -apiVersion: operator.knative.dev/v1alpha1 -kind: KnativeServing -metadata: - name: knative-serving - namespace: knative-serving -spec: - config: - tracing: - sample-rate: "0.1" <1> - backend: zipkin <2> - zipkin-endpoint: http://jaeger-collector.default.svc.cluster.local:9411/api/v2/spans <3> - debug: "false" <4> ----- -+ -<1> The `sample-rate` defines sampling probability. Using `sample-rate: "0.1"` means that 1 in 10 traces will be sampled. -<2> `backend` must be set to `zipkin`. -<3> The `zipkin-endpoint` must point to your `jaeger-collector` service endpoint. To get this endpoint, substitute the namespace where the Jaeger custom resource is applied. -<4> Debugging should be set to `false`. Enabling debug mode by setting `debug: "true"` allows all spans to be sent to the server, bypassing sampling. - -.Verification - -Access the Jaeger web console to see tracing data. You can access the Jaeger web console by using the `jaeger` route. - -. Get the `jaeger` route's hostname by entering the following command: -+ - -[source,terminal] ----- -$ oc get route jaeger ----- - -+ -.Example output -+ - -[source,terminal] ----- -NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD -jaeger jaeger-default.apps.example.com jaeger-query <all> reencrypt None ----- - -. Open the endpoint address in your browser to view the console. diff --git a/modules/serverless-kafka-sasl.adoc b/modules/serverless-kafka-sasl.adoc deleted file mode 100644 index 64b57a2b44ac..000000000000 --- a/modules/serverless-kafka-sasl.adoc +++ /dev/null @@ -1,90 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/serverless-kafka.adoc - -[id="serverless-configuring-sasl-authentication-against-an-apache-kafka_{context}"] -= Configuring SASL authentication - -.Prerequisites - -* A username and password for the Kafka cluster. -* Choose the SASL mechanism to use, for example `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`. -* If TLS is enabled, you also need the `ca.crt` certificate file for the Kafka cluster. - -[NOTE] -==== -Red Hat recommends to enable TLS in addition to SASL. -==== - -.Procedure - -. Create the certificate files as secrets in your chosen namespace: -+ -[source,terminal] ----- -$ kubectl create secret --namespace <namespace> generic <kafka_auth_secret> \ - --from-file=ca.crt=caroot.pem \ - --from-literal=password="SecretPassword" \ - --from-literal=saslType="SCRAM-SHA-512" \ - --from-literal=user="my-sasl-user" ----- -+ -[IMPORTANT] -==== -Use the key names `ca.crt`, `password`, and `saslType`. Do not change them. -==== - -. Start editing the `KnativeKafka` custom resource: -+ -[source,terminal] ----- -$ oc edit knativekafka ----- - -. Reference your secret and the namespace of the secret: -+ -[source,terminal] ----- -apiVersion: operator.serverless.openshift.io/v1alpha1 -kind: KnativeKafka -metadata: - namespace: knative-eventing - name: knative-kafka -spec: - channel: - authSecretName: <kafka_auth_secret> - authSecretNamespace: <kafka_auth_secret_namespace> - bootstrapServers: <bootstrap_server> - enabled: true - source: - enabled: true ----- -+ -[NOTE] -==== -Make sure to specify the matching port in the bootstrap server. -==== -+ -For example: -+ -[source,terminal] ----- -apiVersion: operator.serverless.openshift.io/v1alpha1 -kind: KnativeKafka -metadata: - namespace: knative-eventing - name: knative-kafka -spec: - channel: - authSecretName: scram-user - authSecretNamespace: kafka - bootstrapServers: eventing-kafka-bootstrap.kafka.svc:9093 - enabled: true - source: - enabled: true ----- - -.Additional resources - -* link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html-single/using_amq_streams_on_rhel/index#assembly-kafka-encryption-and-authentication-str[TLS and SASL on Kafka] - diff --git a/modules/serverless-kafka-source-kn.adoc b/modules/serverless-kafka-source-kn.adoc deleted file mode 100644 index f4a07ec1497d..000000000000 --- a/modules/serverless-kafka-source-kn.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-kafka-source.adoc -[id="serverless-kafka-source-kn_{context}"] -= Creating a Kafka event source by using the kn CLI - -This section describes how to create a Kafka event source by using the `kn` command. - -:FeatureName: Creating a Kafka event source by using the `kn` CLI -include::../modules/technology-preview.adoc[leveloffset=+0] - -.Prerequisites - -* The {ServerlessOperatorName}, Knative Eventing, Knative Serving, and the `KnativeKafka` custom resource are installed on your cluster. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. -* You have access to a Red Hat AMQ Streams (Kafka) cluster that produces the Kafka messages you want to import. - -.Procedure - -. To verify that the Kafka event source is working, create a Knative service that dumps incoming events into the service logs: -+ -[source, terminal] ----- -$ kn service create event-display \ - --image quay.io/openshift-knative/knative-eventing-sources-event-display ----- - -. Create a `KafkaSource` resource: -+ -[source,terminal] ----- -$ kn source kafka create mykafkasrc \ - --servers my-cluster-kafka-bootstrap.kafka.svc:9092 \ - --topics my-topic --consumergroup my-consumer-group \ - --sink event-display ----- -+ -The `--servers`, `--topics`, and `--consumergroup` options specify the connection parameters to the Kafka cluster. The `--consumergroup` option is optional. - -. Optional: View details about the `KafkaSource` resource you created: -+ -[source, terminal] ----- -$ kn source kafka describe mykafkasrc ----- -+ -.Example output -[source, terminal] ----- -Name: mykafkasrc -Namespace: kafka -Age: 1h -BootstrapServers: my-cluster-kafka-bootstrap.kafka.svc:9092 -Topics: my-topic -ConsumerGroup: my-consumer-group - -Sink: - Name: event-display - Namespace: default - Resource: Service (serving.knative.dev/v1) - -Conditions: - OK TYPE AGE REASON - ++ Ready 1h - ++ Deployed 1h - ++ SinkProvided 1h ----- - -.Verification steps - -. Trigger the Kafka instance to send a message to the topic: -+ -[source,terminal] ----- -$ oc -n kafka run kafka-producer \ - -ti --image=quay.io/strimzi/kafka:latest-kafka-2.7.0 --rm=true \ - --restart=Never -- bin/kafka-console-producer.sh \ - --broker-list my-cluster-kafka-bootstrap:9092 --topic my-topic ----- -+ -Enter the message in the prompt. This command assumes that: -+ -* The Kafka cluster is installed in the `kafka` namespace. -* The `KafkaSource` object has been configured to use the `my-topic` topic. - -. Verify that the message arrived by viewing the logs: -+ -[source,terminal] ----- -$ oc logs $(oc get pod -o name | grep event-display) -c user-container ----- -+ -.Example output -[source,terminal] ----- -☁️ cloudevents.Event -Validation: valid -Context Attributes, - specversion: 1.0 - type: dev.knative.kafka.event - source: /apis/v1/namespaces/default/kafkasources/mykafkasrc#my-topic - subject: partition:46#0 - id: partition:46/offset:0 - time: 2021-03-10T11:21:49.4Z -Extensions, - traceparent: 00-161ff3815727d8755848ec01c866d1cd-7ff3916c44334678-00 -Data, - Hello! ----- diff --git a/modules/serverless-kafka-source-odc.adoc b/modules/serverless-kafka-source-odc.adoc deleted file mode 100644 index 6615e0f415a4..000000000000 --- a/modules/serverless-kafka-source-odc.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-kafka-source.adoc - -[id="serverless-kafka-source-odc_{context}"] -= Creating a Kafka event source by using the web console - -You can create and verify a Kafka event source from the {product-title} web console. - -.Prerequisites - -* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resource are installed on your cluster. -* You have logged in to the web console. -* You are in the *Developer* perspective. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. - -.Procedure - -. Navigate to the *Add* page and select *Event Source*. -. In the *Event Sources* page, select *Kafka Source* in the *Type* section. -. Configure the *Kafka Source* settings: -.. Add a comma-separated list of *Bootstrap Servers*. -.. Add a comma-separated list of *Topics*. -.. Add a *Consumer Group*. -.. Select the *Service Account Name* for the service account that you created. -.. Select the *Sink* for the event source. A *Sink* can be either a *Resource*, such as a channel, broker, or service, or a *URI*. -.. Enter a *Name* for the Kafka event source. -. Click *Create*. - -.Verification - -You can verify that the Kafka event source was created and is connected to the sink by viewing the *Topology* page. - -. In the *Developer* perspective, navigate to *Topology*. -. View the Kafka event source and sink. -+ -image::verify-kafka-ODC.png[View the Kafka source and service in the Topology view] diff --git a/modules/serverless-kafka-source-yaml.adoc b/modules/serverless-kafka-source-yaml.adoc deleted file mode 100644 index 70a021de1a02..000000000000 --- a/modules/serverless-kafka-source-yaml.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-kafka-source.adoc - -[id="serverless-kafka-source-yaml_{context}"] -= Creating a Kafka event source by using YAML - -You can create a Kafka event source by using YAML. - -.Prerequisites - -* The {ServerlessOperatorName}, Knative Eventing, and the `KnativeKafka` custom resource are installed on your cluster. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. - -.Procedure - -. Create a YAML file containing the following: -+ -[source,yaml] ----- -apiVersion: sources.knative.dev/v1beta1 -kind: KafkaSource -metadata: - name: <source-name> -spec: - consumerGroup: <group-name> <1> - bootstrapServers: - - <list-of-bootstrap-servers> - topics: - - <list-of-topics> <2> - sink: ----- -<1> A consumer group is a group of consumers that use the same group ID, and consume data from a topic. -<2> A topic provides a destination for the storage of data. Each topic is split into one or more partitions. -+ -.Example `KafkaSource` object -[source,yaml] ----- -apiVersion: sources.knative.dev/v1beta1 -kind: KafkaSource -metadata: - name: kafka-source -spec: - consumerGroup: knative-group - bootstrapServers: - - my-cluster-kafka-bootstrap.kafka:9092 - topics: - - knative-demo-topic - sink: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display ----- - -. Apply the YAML file: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- - -.Verification - -* Verify that the Kafka event source was created: -+ -[source, terminal] ----- -$ oc get pods ----- -+ -.Example output -[source, terminal] ---- -NAME READY STATUS RESTARTS AGE -kafkasource-kafka-source-5ca0248f-... 1/1 Running 0 13m ---- diff --git a/modules/serverless-kafka-tls.adoc b/modules/serverless-kafka-tls.adoc deleted file mode 100644 index d2f78ad5bfc0..000000000000 --- a/modules/serverless-kafka-tls.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/serverless-kafka.adoc - -[id="serverless-configuring-tls-authentication-against-an-apache-kafka_{context}"] -= Configuring TLS authentication - -.Prerequisites - -* A Kafka cluster CA certificate as a `.pem` file. -* A Kafka cluster client certificate and key as `.pem` files. - -.Procedure - -. Create the certificate files as secrets in your chosen namespace: -+ ----- -$ kubectl create secret --namespace <namespace> generic <kafka_auth_secret> \ - --from-file=ca.crt=caroot.pem \ - --from-file=user.crt=certificate.pem \ - --from-file=user.key=key.pem ----- -+ -[IMPORTANT] -==== -Use the key names `ca.crt`, `user.crt`, and `user.key`. Do not change them. -==== - -. Start editing the `KnativeKafka` custom resource: -+ -[source,terminal] ----- -$ oc edit knativekafka ----- - -. Reference your secret and the namespace of the secret: -+ -[source,terminal] ----- -apiVersion: operator.serverless.openshift.io/v1alpha1 -kind: KnativeKafka -metadata: - namespace: knative-eventing - name: knative-kafka -spec: - channel: - authSecretName: <kafka_auth_secret> - authSecretNamespace: <kafka_auth_secret_namespace> - bootstrapServers: <bootstrap_server> - enabled: true - source: - enabled: true ----- -+ -[NOTE] -==== -Make sure to specify the matching port in the bootstrap server. -==== -+ -For example: -+ -[source,terminal] ----- -apiVersion: operator.serverless.openshift.io/v1alpha1 -kind: KnativeKafka -metadata: - namespace: knative-eventing - name: knative-kafka -spec: - channel: - authSecretName: tls-user - authSecretNamespace: kafka - bootstrapServers: eventing-kafka-bootstrap.kafka.svc:9094 - enabled: true - source: - enabled: true ----- - -.Additional resources - -* link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.5/html-single/using_amq_streams_on_rhel/index#assembly-kafka-encryption-and-authentication-str[TLS and SASL on Kafka] - diff --git a/modules/serverless-kn-cli-plugins.adoc b/modules/serverless-kn-cli-plugins.adoc deleted file mode 100644 index 384af0d2be48..000000000000 --- a/modules/serverless-kn-cli-plugins.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/installing-kn.adoc - -[id="serverless-kn-plugins_{context}"] -= kn plug-ins - -The Red Hat distribution of the CLI command `kn` contains extensions of `kn` known as plug-ins. The main use of plug-ins is to extend `kn` by providing additional commands on {ServerlessProductName}, such as for the Kafka stack API. The `kn` plug-ins are used in the same way as the main `kn` functionality. - -Currently, Red Hat provides the `kn-source-kafka` plug-in as a Technology Preview feature. diff --git a/modules/serverless-list-broker-kn.adoc b/modules/serverless-list-broker-kn.adoc deleted file mode 100644 index 614a5c56d231..000000000000 --- a/modules/serverless-list-broker-kn.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-using-brokers.adoc - -[id="serverless-list-broker-kn_{context}"] -= Listing existing brokers using the Knative CLI - -.Prerequisites -* The {ServerlessOperatorName}, Knative Serving and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. - -.Procedure -* List all existing brokers: -+ -[source,terminal] ----- -$ kn broker list ----- -+ -.Example output -[source,terminal] ----- -NAME URL AGE CONDITIONS READY REASON -default http://broker-ingress.knative-eventing.svc.cluster.local/test/default 45s 5 OK / 5 True ----- diff --git a/modules/serverless-list-source-types-kn.adoc b/modules/serverless-list-source-types-kn.adoc deleted file mode 100644 index 80c3ae6bcdb8..000000000000 --- a/modules/serverless-list-source-types-kn.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-listing-event-sources.adoc - -[id="serverless-list-source-types-kn_{context}"] -= Listing available event source types by using the Knative CLI - -.Procedure - -. List the available event source types in the terminal: -+ -[source,terminal] ----- -$ kn source list-types ----- -+ -.Example output -[source,terminal] ----- -TYPE NAME DESCRIPTION -ApiServerSource apiserversources.sources.knative.dev Watch and send Kubernetes API events to a sink -PingSource pingsources.sources.knative.dev Periodically send ping events to a sink -SinkBinding sinkbindings.sources.knative.dev Binding for connecting a PodSpecable to a sink ----- - -. Optional: You can also list the available event source types in YAML format: -+ -[source,terminal] ----- -$ kn source list-types -o yaml ----- diff --git a/modules/serverless-list-source-types-odc.adoc b/modules/serverless-list-source-types-odc.adoc deleted file mode 100644 index 4fec642ae886..000000000000 --- a/modules/serverless-list-source-types-odc.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-listing-event-sources.adoc - -[id="serverless-list-source-types-odc_{context}"] -= Viewing available event source types within the Developer perspective - -You can use the web console to view available event source types. - -[NOTE] -==== -Additional event source types can be added by cluster administrators by installing Operators on {product-title}. -==== - -.Procedure -. Access the *Developer* perspective. -. Click *+Add*. -. Click *Event source*. diff --git a/modules/serverless-list-source.adoc b/modules/serverless-list-source.adoc deleted file mode 100644 index f0a6245ac1dd..000000000000 --- a/modules/serverless-list-source.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-listing-event-sources.adoc - -[id="serverless-list-source_{context}"] -= Listing available event sources using the Knative CLI - -* List the available event sources: -+ -[source,terminal] ----- -$ kn source list ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE RESOURCE SINK READY -a1 ApiServerSource apiserversources.sources.knative.dev ksvc:eshow2 True -b1 SinkBinding sinkbindings.sources.knative.dev ksvc:eshow3 False -p1 PingSource pingsources.sources.knative.dev ksvc:eshow1 True ----- - -== Listing event sources of a specific type only - -You can list event sources of a specific type only, by using the `--type` flag. - -* List the available ping sources: -+ -[source,terminal] ----- -$ kn source list --type PingSource ----- -+ -.Example output -[source,terminal] ----- -NAME TYPE RESOURCE SINK READY -p1 PingSource pingsources.sources.knative.dev ksvc:eshow1 True ----- diff --git a/modules/serverless-list-subs-kn.adoc b/modules/serverless-list-subs-kn.adoc deleted file mode 100644 index c8a3fd1e4375..000000000000 --- a/modules/serverless-list-subs-kn.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-subs.adoc - -[id="serverless-list-subs-kn_{context}"] -= Listing subscriptions using the Knative CLI - -You can list existing subscriptions on your cluster by using the `kn` CLI. - -.Prerequisites - -* You have installed the `kn` CLI. - -.Procedure - -* List subscriptions on your cluster: -+ -[source,terminal] ----- -$ kn subscription list ----- -+ -.Example output -[source,terminal] ----- -NAME CHANNEL SUBSCRIBER REPLY DEAD LETTER SINK READY REASON -mysubscription Channel:mychannel ksvc:event-display True ----- -// . Optional: List subscriptions in YAML format: -// + -// [source,terminal] -// ---- -// $ kn subscription list -o yaml -// ---- -// Add this step once I have an example output, optional so non urgent diff --git a/modules/serverless-metering-datasources.adoc b/modules/serverless-metering-datasources.adoc deleted file mode 100644 index b0c7a11c54f3..000000000000 --- a/modules/serverless-metering-datasources.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// serverless-metering.adoc - -[id="datasources-metering-serverless_{context}"] -= Datasources for Knative Serving metering -The following `ReportDataSources` are examples of how Knative Serving can be used with {product-title} metering. - -[id="knative-service-cpu-usage-ds_{context}"] -== Datasource for CPU usage in Knative Serving -This datasource provides the accumulated CPU seconds used per Knative service over the report time period. - -.YAML file -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: ReportDataSource -metadata: - name: knative-service-cpu-usage -spec: - prometheusMetricsImporter: - query: > - sum - by(namespace, - label_serving_knative_dev_service, - label_serving_knative_dev_revision) - ( - label_replace(rate(container_cpu_usage_seconds_total{container!="POD",container!="",pod!=""}[1m]), "pod", "$1", "pod", "(.*)") - * - on(pod, namespace) - group_left(label_serving_knative_dev_service, label_serving_knative_dev_revision) - kube_pod_labels{label_serving_knative_dev_service!=""} - ) ----- - -[id="knative-service-memory-usage-ds_{context}"] -== Datasource for memory usage in Knative Serving -This datasource provides the average memory consumption per Knative service over the report time period. - -.YAML file -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: ReportDataSource -metadata: - name: knative-service-memory-usage -spec: - prometheusMetricsImporter: - query: > - sum - by(namespace, - label_serving_knative_dev_service, - label_serving_knative_dev_revision) - ( - label_replace(container_memory_usage_bytes{container!="POD", container!="",pod!=""}, "pod", "$1", "pod", "(.*)") - * - on(pod, namespace) - group_left(label_serving_knative_dev_service, label_serving_knative_dev_revision) - kube_pod_labels{label_serving_knative_dev_service!=""} - ) ----- - -[id="applying-datasources-knative_{context}"] -== Applying Datasources for Knative Serving metering -You can apply the `ReportDataSources` by using the following command: - -[source,terminal] ----- -$ oc apply -f <datasource_name>.yaml ----- - -.Example - -[source,terminal] ----- -$ oc apply -f knative-service-memory-usage.yaml ----- diff --git a/modules/serverless-metering-queries.adoc b/modules/serverless-metering-queries.adoc deleted file mode 100644 index 7961e7203599..000000000000 --- a/modules/serverless-metering-queries.adoc +++ /dev/null @@ -1,138 +0,0 @@ -// Module included in the following assemblies: -// serverless-metering.adoc - -[id="queries-metering-serverless_{context}"] -= Queries for Knative Serving metering -The following `ReportQuery` resources reference the example `DataSources` provided. - -[id="knative-service-cpu-usage-query_{context}"] -== Query for CPU usage in Knative Serving - -.YAML file - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: ReportQuery -metadata: - name: knative-service-cpu-usage -spec: - inputs: - - name: ReportingStart - type: time - - name: ReportingEnd - type: time - - default: knative-service-cpu-usage - name: KnativeServiceCpuUsageDataSource - type: ReportDataSource - columns: - - name: period_start - type: timestamp - unit: date - - name: period_end - type: timestamp - unit: date - - name: namespace - type: varchar - unit: kubernetes_namespace - - name: service - type: varchar - - name: data_start - type: timestamp - unit: date - - name: data_end - type: timestamp - unit: date - - name: service_cpu_seconds - type: double - unit: cpu_core_seconds - query: | - SELECT - timestamp '{| default .Report.ReportingStart .Report.Inputs.ReportingStart| prestoTimestamp |}' AS period_start, - timestamp '{| default .Report.ReportingEnd .Report.Inputs.ReportingEnd | prestoTimestamp |}' AS period_end, - labels['namespace'] as project, - labels['label_serving_knative_dev_service'] as service, - min("timestamp") as data_start, - max("timestamp") as data_end, - sum(amount * "timeprecision") AS service_cpu_seconds - FROM {| dataSourceTableName .Report.Inputs.KnativeServiceCpuUsageDataSource |} - WHERE "timestamp" >= timestamp '{| default .Report.ReportingStart .Report.Inputs.ReportingStart | prestoTimestamp |}' - AND "timestamp" < timestamp '{| default .Report.ReportingEnd .Report.Inputs.ReportingEnd | prestoTimestamp |}' - GROUP BY labels['namespace'],labels['label_serving_knative_dev_service'] ----- - -[id="knative-service-memory-usage-query_{context}"] -== Query for memory usage in Knative Serving - -.YAML file - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: ReportQuery -metadata: - name: knative-service-memory-usage -spec: - inputs: - - name: ReportingStart - type: time - - name: ReportingEnd - type: time - - default: knative-service-memory-usage - name: KnativeServiceMemoryUsageDataSource - type: ReportDataSource - columns: - - name: period_start - type: timestamp - unit: date - - name: period_end - type: timestamp - unit: date - - name: namespace - type: varchar - unit: kubernetes_namespace - - name: service - type: varchar - - name: data_start - type: timestamp - unit: date - - name: data_end - type: timestamp - unit: date - - name: service_usage_memory_byte_seconds - type: double - unit: byte_seconds - query: | - SELECT - timestamp '{| default .Report.ReportingStart .Report.Inputs.ReportingStart| prestoTimestamp |}' AS period_start, - timestamp '{| default .Report.ReportingEnd .Report.Inputs.ReportingEnd | prestoTimestamp |}' AS period_end, - labels['namespace'] as project, - labels['label_serving_knative_dev_service'] as service, - min("timestamp") as data_start, - max("timestamp") as data_end, - sum(amount * "timeprecision") AS service_usage_memory_byte_seconds - FROM {| dataSourceTableName .Report.Inputs.KnativeServiceMemoryUsageDataSource |} - WHERE "timestamp" >= timestamp '{| default .Report.ReportingStart .Report.Inputs.ReportingStart | prestoTimestamp |}' - AND "timestamp" < timestamp '{| default .Report.ReportingEnd .Report.Inputs.ReportingEnd | prestoTimestamp |}' - GROUP BY labels['namespace'],labels['label_serving_knative_dev_service'] ----- - -[id="applying-queries-knative_{context}"] -== Applying Queries for Knative Serving metering - -. Apply the `ReportQuery` by entering the following command: -+ - -[source,terminal] ----- -$ oc apply -f <query-name>.yaml ----- - -+ -.Example command -+ - -[source,terminal] ----- -$ oc apply -f knative-service-memory-usage.yaml ----- diff --git a/modules/serverless-metering-reports.adoc b/modules/serverless-metering-reports.adoc deleted file mode 100644 index 1fef860171ac..000000000000 --- a/modules/serverless-metering-reports.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// serverless-metering.adoc - -[id="reports-metering-serverless_{context}"] -= Metering reports for Knative Serving - -You can run metering reports against Knative Serving by creating `Report` resources. -Before you run a report, you must modify the input parameter within the `Report` resource to specify the start and end dates of the reporting period. - -.YAML file - -[source,yaml] ----- -apiVersion: metering.openshift.io/v1 -kind: Report -metadata: - name: knative-service-cpu-usage -spec: - reportingStart: '2019-06-01T00:00:00Z' <1> - reportingEnd: '2019-06-30T23:59:59Z' <2> - query: knative-service-cpu-usage <3> -runImmediately: true ----- - -<1> Start date of the report, in ISO 8601 format. -<2> End date of the report, in ISO 8601 format. -<3> Either `knative-service-cpu-usage` for CPU usage report or `knative-service-memory-usage` for a memory usage report. - -[id="reports-metering-serverless-run_{context}"] -== Running a metering report - -. Run the report by entering the following command: -+ - -[source,terminal] ----- -$ oc apply -f <report-name>.yml ----- - -. You can then check the report by entering the following command: -+ - -[source,terminal] ----- -$ oc get report ----- - -+ -.Example output -+ - -[source,terminal] ----- -NAME QUERY SCHEDULE RUNNING FAILED LAST REPORT TIME AGE -knative-service-cpu-usage knative-service-cpu-usage Finished 2019-06-30T23:59:59Z 10h ----- diff --git a/modules/serverless-monitoring-health-status.adoc b/modules/serverless-monitoring-health-status.adoc deleted file mode 100644 index fa3cc5e1a0cb..000000000000 --- a/modules/serverless-monitoring-health-status.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * /serverless/monitoring/serverless-monitoring.adoc - -[id="serverless-monitoring-health-status"] -= Monitoring serverless components overall health status - -You can use the {product-title} monitoring dashboards to view the overall health status of Knative Serving and Eventing. - -.Prerequisites - -* You have installed {ServerlessProductName}. -* The {product-title} monitoring stack is enabled. -* You have cluster administrator permissions, and access to the *Administrator* perspective in the {product-title} web console. - -.Procedure - -. In the *Administrator* perspective, navigate to *Monitoring* -> *Dashboards*. -. Select the *Knative Health Status* dashboard to view the overall health status of Knative Serving and Eventing. -+ -image::knative-health-status-dash.png[Knative Health Status dashboard] diff --git a/modules/serverless-monitoring-serving-cpu-memory.adoc b/modules/serverless-monitoring-serving-cpu-memory.adoc deleted file mode 100644 index 6138ea1c97c5..000000000000 --- a/modules/serverless-monitoring-serving-cpu-memory.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/monitoring/serverless-monitoring.adoc - -[id="serverless-monitoring-serving-cpu-memory"] -= Monitoring Knative Serving revision CPU and memory usage - -You can use the {product-title} monitoring dashboards to view revision CPU and memory usage metrics for Knative Serving components. - -.Prerequisites - -* You have installed {ServerlessProductName}. -* The {product-title} monitoring stack is enabled. -* You have cluster administrator permissions, and access to the *Administrator* perspective in the {product-title} web console. - -.Procedure - -. In the *Administrator* perspective, navigate to *Monitoring* -> *Dashboards*. -. Select the *Knative Serving - Revision CPU and Memory Usage* dashboard to view metrics for Knative service revisions. -. Optional: You can filter this dashboard by *Namespace*, *Configuration*, or *Revision*, by using the drop-down selections. -+ -image::knative-serving-cpu-memory-dash.png[Knative Serving Revision CPU and Memory Usage dashboard] diff --git a/modules/serverless-openshift-routes.adoc b/modules/serverless-openshift-routes.adoc deleted file mode 100644 index b192f615157a..000000000000 --- a/modules/serverless-openshift-routes.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// * serverless/networking/serverless-configuring-routes.adoc - -[id="serverless-openshift-routes_{context}"] -= Configuring {product-title} routes for Knative services - -If you want to configure a Knative service to use your TLS certificate on {product-title}, you must disable the automatic creation of a route for the service by the {ServerlessOperatorName}, and instead manually create a `Route` resource for the service. - -.Prerequisites - -* The {ServerlessOperatorName} and Knative Serving component must be installed on your {product-title} cluster. - -.Procedure - -. Create a Knative service that includes the `serving.knative.openshift.io/disableRoute=true` annotation: -+ -.Example YAML -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: <service_name> - annotations: - serving.knative.openshift.io/disableRoute: true -spec: - template: - spec: - containers: - - image: <image> ----- -+ -.Example `kn` command -[source,terminal] ----- -$ kn service create hello-example \ - --image=gcr.io/knative-samples/helloworld-go \ - --annotation serving.knative.openshift.io/disableRoute=true ----- - -. Verify that no {product-title} route has been created for the service: -+ -.Example command -[source,terminal] ----- -$ oc get routes.route.openshift.io -l serving.knative.openshift.io/ingressName=$KSERVICE_NAME -l serving.knative.openshift.io/ingressNamespace=$KSERVICE_NAMESPACE -n knative-serving-ingress ----- -+ -You should see the following output: -+ -[source,terminal] ----- -No resources found in knative-serving-ingress namespace. ----- - -. Create a `Route` object in the `knative-serving-ingress` namespace by copying the following sample YAML and modifying the replaceable values: -+ -[source,yaml] ----- -apiVersion: route.openshift.io/v1 -kind: Route -metadata: - annotations: - haproxy.router.openshift.io/timeout: 600s <1> - name: <route_name> <2> - namespace: knative-serving-ingress <3> -spec: - host: <service_host> <4> - port: - targetPort: http2 - to: - kind: Service - name: kourier - weight: 100 - tls: - insecureEdgeTerminationPolicy: Allow - termination: edge <5> - key: |- - -----BEGIN PRIVATE KEY----- - [...] - -----END PRIVATE KEY----- - certificate: |- - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE----- - caCertificate: |- - -----BEGIN CERTIFICATE----- - [...] - -----END CERTIFICATE---- - wildcardPolicy: None ----- -<1> The timeout value for the {product-title} route. You must set the same value as the `max-revision-timeout-seconds` setting (`600s` by default). -<2> The name of the {product-title} route. -<3> The namespace for the {product-title} route. This must be `knative-serving-ingress`. -<4> The hostname for external access. You can set this to `<service_name>-<service_namespace>.<domain>`. -<5> The certificates you want to use. Currently, only `edge` termination is supported. diff --git a/modules/serverless-ossm-setup.adoc b/modules/serverless-ossm-setup.adoc deleted file mode 100644 index a85241867f6c..000000000000 --- a/modules/serverless-ossm-setup.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm.adoc - -[id="serverless-ossm-setup_{context}"] -= Using {ProductShortName} with {ServerlessProductName} - -.Procedure - -. Add the namespaces that you would like to integrate with {ProductShortName} to the `ServiceMeshMemberRoll` object as members: -+ -[source,yaml] ----- -apiVersion: maistra.io/v1 -kind: ServiceMeshMemberRoll -metadata: - name: default - namespace: istio-system -spec: - members: - - <namespace> <1> ----- -<1> A list of namespaces to be integrated with {ProductShortName}. -+ -[IMPORTANT] -==== -Adding sidecar injection to Pods in system namespaces such as `knative-serving` and `knative-serving-ingress` is not supported. -==== -. Create a network policy that permits traffic flow from Knative system Pods to Knative services: -.. Add the `serving.knative.openshift.io/system-namespace=true` label to the `knative-serving` namespace: -+ -[source,terminal] ----- -$ oc label namespace knative-serving serving.knative.openshift.io/system-namespace=true ----- -.. Add the `serving.knative.openshift.io/system-namespace=true` label to the `knative-serving-ingress` namespace: -+ -[source,terminal] ----- -$ oc label namespace knative-serving-ingress serving.knative.openshift.io/system-namespace=true ----- -.. For each namespace that you would like to integrate with {ProductShortName}, copy the following `NetworkPolicy` resource into a YAML file: -+ -[source,yaml] ----- -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: allow-from-serving-system-namespace - namespace: <namespace> -spec: - ingress: - - from: - - namespaceSelector: - matchLabels: - serving.knative.openshift.io/system-namespace: "true" - podSelector: {} - policyTypes: - - Ingress ----- -.. Apply the `NetworkPolicy` resource: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- diff --git a/modules/serverless-ossm-v1x-jwt.adoc b/modules/serverless-ossm-v1x-jwt.adoc deleted file mode 100644 index 7a5d06356aa8..000000000000 --- a/modules/serverless-ossm-v1x-jwt.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-jwt.adoc - -[id="serverless-ossm-v1x-jwt_{context}"] -= Using JSON Web Token authentication with {ProductShortName} 1.x and {ServerlessProductName} - -.Procedure - -. Create a policy in a serverless application namespace which is a member in the `ServiceMeshMemberRoll` object, that only allows requests with valid JSON Web Tokens (JWT): -.. Copy the following `Policy` resource into a YAML file: -+ -[IMPORTANT] -==== -The paths `/metrics` and `/healthz` must be included in `excludedPaths` because they are accessed from system Pods in the `knative-serving` namespace. -==== -+ -[source,yaml] ----- -apiVersion: authentication.istio.io/v1alpha1 -kind: Policy -metadata: - name: default - namespace: <namespace> -spec: - origins: - - jwt: - issuer: testing@secure.istio.io - jwksUri: "https://raw.githubusercontent.com/istio/istio/release-1.6/security/tools/jwt/samples/jwks.json" - triggerRules: - - excludedPaths: - - prefix: /metrics <1> - - prefix: /healthz <2> - principalBinding: USE_ORIGIN ----- -<1> The path on your application to collect metrics by system pod. -<2> The path on your application to probe by system pod. -.. Apply the `Policy` resource: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- - -.Verification - -. If you try to use a `curl` request to get the Knative service URL, it is denied. -+ -[source,terminal] ----- -$ curl http://hello-example-default.apps.mycluster.example.com/ ----- -+ -.Example output -[source,terminal] ----- -Origin authentication failed. ----- -. Verify the request with a valid JWT. -.. Get the valid JWT token by entering the following command: -+ -[source,terminal] ----- -$ TOKEN=$(curl https://raw.githubusercontent.com/istio/istio/release-1.6/security/tools/jwt/samples/demo.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode - ----- -.. Access the service by using the valid token in the `curl` request header: -+ -[source,terminal] ----- -$ curl http://hello-example-default.apps.mycluster.example.com/ -H "Authorization: Bearer $TOKEN" ----- -+ -The request is now allowed. -+ -.Example output -[source,terminal] ----- -Hello OpenShift! ----- diff --git a/modules/serverless-ossm-v1x-tls.adoc b/modules/serverless-ossm-v1x-tls.adoc deleted file mode 100644 index 757fcdb0bb3a..000000000000 --- a/modules/serverless-ossm-v1x-tls.adoc +++ /dev/null @@ -1,162 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-tls.adoc - -[id="serverless-ossm-v1x-tls_{context}"] -= Configuring Transport Layer Security for a custom domain using {ProductName} 1.x - -You can create a Transport Layer Security (TLS) key and certificates for a custom domain and subdomain using {ProductName}. - -.Procedure - -. Create a root certificate and private key to sign the certificates for your services: -+ -[source,terminal] ----- -$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \ - -subj '/O=Example Inc./CN=example.com' \ - -keyout example.com.key \ - -out example.com.crt ----- -. Create a certificate signing request for your domain: -+ -[source,terminal] ----- -$ openssl req -out custom.example.com.csr -newkey rsa:2048 -nodes \ - -keyout custom.example.com.key \ - -subj "/CN=custom-ksvc-domain.example.com/O=Example Inc." ----- -. Sign the request with your CA: -+ -[source,terminal] ----- -$ openssl x509 -req -days 365 -set_serial 0 \ - -CA example.com.crt \ - -CAkey example.com.key \ - -in custom.example.com.csr \ - -out custom.example.com.crt ----- -. Check that the certificates appear in your directory: -+ -[source,terminal] ----- -$ ls -1 ----- -+ -.Example output -[source,terminal] ----- -custom.example.com.crt -custom.example.com.csr -custom.example.com.key -example.com.crt -example.com.key ----- -. Create a secret: -+ -[source,terminal] ----- -$ oc create -n istio-system secret tls custom.example.com \ - --key=custom.example.com.key \ - --cert=custom.example.com.crt ----- -. Attach the secret to the Istio ingress gateway by editing the `ServiceMeshControlPlane` resource. -.. Edit the `ServiceMeshControlPlane` resource: -+ -[source,terminal] ----- -$ oc edit -n istio-system ServiceMeshControlPlane <control_plane_name> ----- -.. Check that the following lines exist in the resource, and if they do not, add them: -+ -[source,yaml] ----- -spec: - istio: - gateways: - istio-ingressgateway: - secretVolumes: - - mountPath: /custom.example.com - name: custom-example-com - secretName: custom.example.com ----- -. Update the Istio ingress gateway to use your secret. -.. Edit the `default-gateway` resource: -+ -[source,terminal] ----- -$ oc edit gateway default-gateway ----- -.. Check that the following lines exist in the resource, and if they do not, add them: -+ -[source,yaml] ----- -- hosts: - - custom-ksvc-domain.example.com - port: - name: https - number: 443 - protocol: HTTPS - tls: - mode: SIMPLE - privateKey: /custom.example.com/tls.key - serverCertificate: /custom.example.com/tls.crt ----- -. Update the route to use pass-through TLS and `8443` as the `spec.port.targetPort`. -.. Edit the route: -+ -[source,terminal] ----- -$ oc edit route -n istio-system hello ----- -.. Add the following configuration to the route: -+ -[source,yaml] ----- -spec: - host: custom-ksvc-domain.example.com - port: - targetPort: 8443 - tls: - insecureEdgeTerminationPolicy: None - termination: passthrough - to: - kind: Service - name: istio-ingressgateway - weight: 100 - wildcardPolicy: None ----- - -.Verification - -* Access your serverless application by a secure connection that is now trusted by the CA: -+ -[source,terminal] ----- -$ curl --cacert example.com.crt \ - --header "Host: custom-ksvc-domain.example.com" \ - --resolve "custom-ksvc-domain.example.com:443:<ingress_router_IP>" \ - https://custom-ksvc-domain.example.com:443 ----- -+ -[NOTE] -==== -You must substitute your own value for `<ingress_router_IP>`. -Steps for finding this IP or host name value vary depending on your {product-title} provider platform. - -.Example command to find the ingress IP - -This command is valid for GCP and Azure provider platforms: - -[source,terminal] ----- -$ oc get svc -n openshift-ingress router-default \ - -o jsonpath='{.status.loadBalancer.ingress[0].ip}' ----- -==== -+ -.Example output -[source,terminal] ----- -Hello OpenShift! ----- diff --git a/modules/serverless-ossm-v2x-jwt.adoc b/modules/serverless-ossm-v2x-jwt.adoc deleted file mode 100644 index b59f151ed6cf..000000000000 --- a/modules/serverless-ossm-v2x-jwt.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-jwt.adoc - -[id="serverless-ossm-v2x-jwt_{context}"] -= Using JSON Web Token authentication with {ProductShortName} 2.x and {ServerlessProductName} - -.Procedure - -. Create the `RequestAuthentication` resource in each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, by copying the following code into a YAML file: -+ -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: RequestAuthentication -metadata: - name: jwt-example - namespace: <namespace> -spec: - jwtRules: - - issuer: testing@secure.istio.io - jwksUri: https://raw.githubusercontent.com/istio/istio/release-1.8/security/tools/jwt/samples/jwks.json ----- -. Apply the `RequestAuthentication` resource: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- -. Allow access to the `RequestAuthenticaton` resource from system pods for each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, by copying the following `AuthorizationPolicy` resources into a YAML file: -+ -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: allowlist-by-paths - namespace: <namespace> -spec: - action: ALLOW - rules: - - to: - - operation: - paths: - - /metrics <1> - - /healthz <2> ----- -<1> The path on your application to collect metrics by system pod. -<2> The path on your application to probe by system pod. -. Apply the `AuthorizationPolicy` resource YAML file: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- -. For each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, copy the following `AuthorizationPolicy` resource, into a YAML file: -+ -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: require-jwt - namespace: <namespace> -spec: - action: ALLOW - rules: - - from: - - source: - requestPrincipals: ["testing@secure.istio.io/testing@secure.istio.io"] ----- -. Apply the `AuthorizationPolicy` resource YAML file: -+ -[source,terminal] ----- -$ oc apply -f <filename> ----- - -.Verification - -. If you try to use a `curl` request to get the Knative service URL, it is denied. -+ -[source,terminal] ----- -$ curl http://hello-example-1-default.apps.mycluster.example.com/ ----- -+ -.Example output -[source,terminal] ----- -RBAC: access denied ----- -. Verify the request with a valid JWT. -.. Get the valid JWT token by entering the following command: -+ -[source,terminal] ----- -$ TOKEN=$(curl https://raw.githubusercontent.com/istio/istio/release-1.8/security/tools/jwt/samples/demo.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode - ----- -.. Access the service by using the valid token in the `curl` request header: -+ -[source,terminal] ----- -$ curl -H "Authorization: Bearer $TOKEN" http://hello-example-1-default.apps.example.com ----- -+ -The request is now allowed. -+ -.Example output -[source,terminal] ----- -Hello OpenShift! ----- diff --git a/modules/serverless-ossm-v2x-tls.adoc b/modules/serverless-ossm-v2x-tls.adoc deleted file mode 100644 index b6124bbe8371..000000000000 --- a/modules/serverless-ossm-v2x-tls.adoc +++ /dev/null @@ -1,164 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-tls.adoc - -[id="serverless-ossm-v2x-tls_{context}"] -= Configuring Transport Layer Security for a custom domain using {ProductName} 2.x - -You can create a Transport Layer Security (TLS) key and certificates for a custom domain and subdomain using {ProductName}. - -.Procedure - -. Create a root certificate and private key to sign the certificates for your services: -+ -[source,terminal] ----- -$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \ - -subj '/O=Example Inc./CN=example.com' \ - -keyout example.com.key \ - -out example.com.crt ----- -. Create a certificate signing request for your domain: -+ -[source,terminal] ----- -$ openssl req -out custom.example.com.csr -newkey rsa:2048 -nodes \ - -keyout custom.example.com.key \ - -subj "/CN=custom-ksvc-domain.example.com/O=Example Inc." ----- -. Sign the request with your CA: -+ -[source,terminal] ----- -$ openssl x509 -req -days 365 -set_serial 0 \ - -CA example.com.crt \ - -CAkey example.com.key \ - -in custom.example.com.csr \ - -out custom.example.com.crt ----- -. Check that the certificates appear in your directory: -+ -[source,terminal] ----- -$ ls -1 ----- -+ -.Example output -[source,terminal] ----- -custom.example.com.crt -custom.example.com.csr -custom.example.com.key -example.com.crt -example.com.key ----- -. Create a secret: -+ -[source,terminal] ----- -$ oc create -n istio-system secret tls custom.example.com \ - --key=custom.example.com.key \ - --cert=custom.example.com.crt ----- -. Attach the secret to the Istio ingress gateway by editing the `ServiceMeshControlPlane` resource. -.. Edit the `ServiceMeshControlPlane` resource: -+ -[source,terminal] ----- -$ oc edit -n istio-system ServiceMeshControlPlane <control-plane-name> ----- -.. Check that the following lines exist in the resource, and if they do not, add them: -+ -[source,yaml] ----- -spec: - gateways: - ingress: - volumes: - - volume: - secret: - secretName: custom.example.com - volumeMount: - name: custom-example-com - mountPath: /custom.example.com ----- -. Update the Istio ingress gateway to use your secret. -.. Edit the `default-gateway` resource: -+ -[source,terminal] ----- -$ oc edit gateway default-gateway ----- -.. Check that the following lines exist in the resource, and if they do not, add them: -+ -[source,yaml] ----- -- hosts: - - custom-ksvc-domain.example.com - port: - name: https - number: 443 - protocol: HTTPS - tls: - mode: SIMPLE - privateKey: /custom.example.com/tls.key - serverCertificate: /custom.example.com/tls.crt ----- -. Update the route to use pass-through TLS and `8443` as the `spec.port.targetPort`. -.. Edit the route: -+ -[source,terminal] ----- -$ oc edit route -n istio-system hello ----- -.. Add the following configuration to the route: -+ -[source,yaml] ----- -spec: - host: custom-ksvc-domain.example.com - port: - targetPort: 8443 - tls: - insecureEdgeTerminationPolicy: None - termination: passthrough - to: - kind: Service - name: istio-ingressgateway - weight: 100 - wildcardPolicy: None ----- - -.Verification - -* Access your serverless application by a secure connection that is now trusted by the CA: -+ -[source,terminal] ----- -$ curl --cacert example.com.crt \ - --header "Host: custom-ksvc-domain.example.com" \ - --resolve "custom-ksvc-domain.example.com:443:<ingress_router_IP>" \ - https://custom-ksvc-domain.example.com:443 ----- -+ -[NOTE] -==== -You must substitute your own value for `<ingress_router_IP>`. -Steps for finding this IP or host name value vary depending on your {product-title} provider platform. - -.Example command to find the ingress IP - -This command is valid for GCP and Azure provider platforms: - -[source,terminal] ----- -$ oc get svc -n openshift-ingress router-default \ - -o jsonpath='{.status.loadBalancer.ingress[0].ip}' ----- -==== -+ -.Example output -[source,terminal] ----- -Hello OpenShift! ----- diff --git a/modules/serverless-pingsource-kn.adoc b/modules/serverless-pingsource-kn.adoc deleted file mode 100644 index 10ca58998b00..000000000000 --- a/modules/serverless-pingsource-kn.adoc +++ /dev/null @@ -1,102 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-pingsource.adoc - -[id="serverless-pingsource-kn_{context}"] -= Using a ping source with the Knative CLI - -The following procedure describes how to create a basic ping source by using the `kn` CLI. - -.Prerequisites - -* You have Knative Serving and Eventing installed. -* You have the `kn` CLI installed. - -.Procedure - -. To verify that the ping source is working, create a simple Knative -service that dumps incoming messages to the service logs: -+ -[source,terminal] ----- -$ kn service create event-display \ - --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- -. For each set of ping events that you want to request, create a ping source in the same namespace as the event consumer: -+ -[source,terminal] ----- -$ kn source ping create test-ping-source \ - --schedule "*/2 * * * *" \ - --data '{"message": "Hello world!"}' \ - --sink ksvc:event-display ----- -. Check that the controller is mapped correctly by entering the following command and inspecting the output: -+ -[source,terminal] ----- -$ kn source ping describe test-ping-source ----- -+ -.Example output -[source,terminal] ----- -Name: test-ping-source -Namespace: default -Annotations: sources.knative.dev/creator=developer, sources.knative.dev/lastModifier=developer -Age: 15s -Schedule: */2 * * * * -Data: {"message": "Hello world!"} - -Sink: - Name: event-display - Namespace: default - Resource: Service (serving.knative.dev/v1) - -Conditions: - OK TYPE AGE REASON - ++ Ready 8s - ++ Deployed 8s - ++ SinkProvided 15s - ++ ValidSchedule 15s - ++ EventTypeProvided 15s - ++ ResourcesCorrect 15s ----- - -.Verification - -You can verify that the Kubernetes events were sent to the Knative event sink by looking at the logs of the sink pod. - -By default, Knative services terminate their pods if no traffic is received within a 60 second period. -The example shown in this guide creates a ping source that sends a message every 2 minutes, so each message should be observed in a newly created pod. - -. Watch for new pods created: -+ -[source,terminal] ----- -$ watch oc get pods ----- -. Cancel watching the pods using Ctrl+C, then look at the logs of the created pod: -+ -[source,terminal] ----- -$ oc logs $(oc get pod -o name | grep event-display) -c user-container ----- -+ -.Example output -[source,terminal] ----- -☁️ cloudevents.Event -Validation: valid -Context Attributes, - specversion: 1.0 - type: dev.knative.sources.ping - source: /apis/v1/namespaces/default/pingsources/test-ping-source - id: 99e4f4f6-08ff-4bff-acf1-47f61ded68c9 - time: 2020-04-07T16:16:00.000601161Z - datacontenttype: application/json -Data, - { - "message": "Hello world!" - } ----- diff --git a/modules/serverless-pingsource-odc.adoc b/modules/serverless-pingsource-odc.adoc deleted file mode 100644 index e9cb4c9c79e7..000000000000 --- a/modules/serverless-pingsource-odc.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-pingsource.adoc - -[id="serverless-pingsource-odc_{context}"] -= Creating a ping source using the Developer perspective - -You can create and verify a basic ping source from the {product-title} web console. - -.Prerequisites - -To create a ping source using the *Developer* perspective, ensure that: - -* The {ServerlessOperatorName}, Knative Serving, and Knative Eventing are installed on your {product-title} cluster. -* You have logged in to the web console. -* You are in the *Developer* perspective. -* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. - -.Procedure - -. To verify that the ping source is working, create a simple Knative -service that dumps incoming messages to the logs of the service. -.. In the *Developer* perspective, navigate to *+Add* -> *YAML*. -.. Copy the example YAML: -+ -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: event-display -spec: - template: - spec: - containers: - - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- - -.. Click *Create*. - -. Create a ping source in the same namespace as the service created in the previous step, or any other sink that you want to send events to. -.. In the *Developer* perspective, navigate to *+Add* -> *Event Source*. The *Event Sources* page is displayed. -.. Optional: If you have multiple providers for your event sources, select the required provider from the *Providers* list to filter the available event sources from the provider. -.. Select *Ping Source* and then click *Create Event Source*. The *Create Event Source* page is displayed. -+ -[NOTE] -==== -You can configure the *PingSource* settings by using the *Form view* or *YAML view* and can switch between the views. The data is persisted when switching between the views. -==== -.. Enter a value for *Schedule*. In this example, the value is `*/2 * * * *`, which creates a PingSource that sends a message every two minutes. -.. Optional: You can enter a value for *Data*, which is the message payload. -.. Select a *Sink*. This can be either a *Resource* or a *URI*. In this example, the `event-display` service created in the previous step is used as the *Resource* sink. -.. Click *Create*. - -.Verification - -You can verify that the ping source was created and is connected to the sink by viewing the *Topology* page. - -. In the *Developer* perspective, navigate to *Topology*. -. View the PingSource and sink. -+ -image::verify-pingsource-ODC.png[View the PingSource and service in the Topology view] diff --git a/modules/serverless-pingsource-yaml.adoc b/modules/serverless-pingsource-yaml.adoc deleted file mode 100644 index 7697b9329f7b..000000000000 --- a/modules/serverless-pingsource-yaml.adoc +++ /dev/null @@ -1,144 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-pingsource.adoc - -[id="serverless-pingsource-yaml_{context}"] -= Using a ping source with YAML - -The following sections describe how to create a basic ping source using YAML files. - -.Prerequisites - -* You have Knative Serving and Eventing installed. - -[NOTE] -==== -The following procedure requires you to create YAML files. - -If you change the names of the YAML files from those used in the examples, you must ensure that you also update the corresponding CLI commands. -==== - -.Procedure - -. To verify that the ping source is working, create a simple Knative -service that dumps incoming messages to the service's logs. -.. Copy the example YAML into a file named `service.yaml`: -+ -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: event-display -spec: - template: - spec: - containers: - - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- - -.. Create the service: -+ -[source,terminal] ----- -$ oc apply --filename service.yaml ----- - -. For each set of ping events that you want to request, create a ping source in the same namespace as the event consumer. -.. Copy the example YAML into a file named `ping-source.yaml`: -+ -[source,yaml] ----- -apiVersion: sources.knative.dev/v1alpha2 -kind: PingSource -metadata: - name: test-ping-source -spec: - schedule: "*/2 * * * *" - jsonData: '{"message": "Hello world!"}' - sink: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display ----- - -.. Create the ping source: -+ -[source,terminal] ----- -$ oc apply --filename ping-source.yaml ----- - -. Check that the controller is mapped correctly by entering the following command: -+ -[source,terminal] ----- -$ oc get pingsource.sources.knative.dev test-ping-source -oyaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: sources.knative.dev/v1alpha2 -kind: PingSource -metadata: - annotations: - sources.knative.dev/creator: developer - sources.knative.dev/lastModifier: developer - creationTimestamp: "2020-04-07T16:11:14Z" - generation: 1 - name: test-ping-source - namespace: default - resourceVersion: "55257" - selfLink: /apis/sources.knative.dev/v1alpha2/namespaces/default/pingsources/test-ping-source - uid: 3d80d50b-f8c7-4c1b-99f7-3ec00e0a8164 -spec: - jsonData: '{ value: "hello" }' - schedule: '*/2 * * * *' - sink: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display - namespace: default ----- - -.Verification - -You can verify that the Kubernetes events were sent to the Knative event sink by looking at the sink pod's logs. - -By default, Knative services terminate their pods if no traffic is received within a 60 second period. -The example shown in this guide creates a PingSource that sends a message every 2 minutes, so each message should be observed in a newly created pod. - -. Watch for new pods created: -+ -[source,terminal] ----- -$ watch oc get pods ----- - -. Cancel watching the pods using Ctrl+C, then look at the logs of the created pod: -+ -[source,terminal] ----- -$ oc logs $(oc get pod -o name | grep event-display) -c user-container ----- -+ -.Example output -[source,terminal] ----- -☁️ cloudevents.Event -Validation: valid -Context Attributes, - specversion: 1.0 - type: dev.knative.sources.ping - source: /apis/v1/namespaces/default/pingsources/test-ping-source - id: 042ff529-240e-45ee-b40c-3a908129853e - time: 2020-04-07T16:22:00.000791674Z - datacontenttype: application/json -Data, - { - "message": "Hello world!" - } ----- diff --git a/modules/serverless-rn-1-10-0.adoc b/modules/serverless-rn-1-10-0.adoc deleted file mode 100644 index 298db13a63ad..000000000000 --- a/modules/serverless-rn-1-10-0.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/release-notes.adoc - -[id="serverless-rn-1-10-0_{context}"] -= Release Notes for Red Hat {ServerlessProductName} 1.10.0 - -[id="new-features-1-10-0_{context}"] -== New features -* {ServerlessProductName} now uses Knative Operator 0.16.0. -* {ServerlessProductName} now uses Knative Serving 0.16.0. -* {ServerlessProductName} uses Knative Eventing 0.16.0. -* {ServerlessProductName} now uses Kourier 0.16.0. -* {ServerlessProductName} now uses Knative `kn` CLI 0.16.1. -* The annotation `knative-eventing-injection=enabled` that was previously used to label namespaces for broker creation is now deprecated. The new annotation is `eventing.knative.dev/injection=enabled`. For more information, see the documentation on _Brokers and triggers_. -* Multi-container support is now available on Knative as a Technology Preview feature. You can enable multi-container support in the `config-features` config map. For more information, see the https://knative.dev/docs/serving/feature-flags/#multi-containers[Knative documentation]. - -[id="fixed-issues-1-10-0_{context}"] -== Fixed issues -* In previous releases, Knative Serving had a fixed, minimum CPU request of 25m for `queue-proxy`. If your cluster had any value set that conflicted with this, for example, if you had set a minimum CPU request for `defaultRequest` of more than `25m`, the Knative Service failed to deploy. This issue is fixed in 1.10.0. - -// [id="known-issues-1-10-0_{context}"] -// == Known issues diff --git a/modules/serverless-rn-1-11-0.adoc b/modules/serverless-rn-1-11-0.adoc deleted file mode 100644 index 0e6b1ff1eb6b..000000000000 --- a/modules/serverless-rn-1-11-0.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/release-notes.adoc - -[id="serverless-rn-1-11-0_{context}"] - -= Release Notes for Red Hat {ServerlessProductName} 1.11.0 - -[id="new-features-1-11-0_{context}"] -== New features - -* Knative Eventing on {ServerlessProductName} is now Generally Available (GA). -* Apache Kafka features such as Kafka channel and Kafka event source are now available as a Technology Preview on {ServerlessProductName}. Kafka integration is delivered through the {ServerlessOperatorName} and does not require a separate community Operator installation. For more information, see the documentation on _Using Apache Kafka with OpenShift Serverless_. -* {ServerlessProductName} Functions is now delivered as a Developer Preview through the standard Knative `kn` CLI installation. This feature is not yet supported by Red Hat for production deployments, but can be used for development and testing. For more information about using {ServerlessProductName} Functions through the `kn func` CLI, see the link:https://openshift-knative.github.io/docs/docs/functions/about-functions.html[{ServerlessProductName} Functions Developer Preview documentation]. -* {ServerlessProductName} now uses Knative Serving 0.17.3. -* {ServerlessProductName} uses Knative Eventing 0.17.2. -* {ServerlessProductName} now uses Kourier 0.17.0. -* {ServerlessProductName} now uses Knative `kn` CLI 0.17.3. -* {ServerlessProductName} now uses Knative Kafka 0.17.1. - -// [id="fixed-issues-1-11-0_{context}"] -// == Fixed issues - -[id="known-issues-1-11-0_{context}"] -== Known issues - -* When the horizontal pod autoscaler (HPA) scales up the `broker-ingress` pod, the `imc-dispatcher` pod sometimes fails to forward replies. This is because the new `broker-ingress` pods are *Ready* before accepting connections, because they lack a readiness probe. If you are using HPA autoscaling and do not want to scale the `broker-ingress` pod manually, you must configure retries in the `Broker.Spec.Delivery`. -* Using the `eventing.knative.dev/scope: namespace` annotation with Kafka channels is not supported. diff --git a/modules/serverless-rn-1-12-0.adoc b/modules/serverless-rn-1-12-0.adoc deleted file mode 100644 index dd10274d970e..000000000000 --- a/modules/serverless-rn-1-12-0.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/release-notes.adoc - -[id="serverless-rn-1-12-0_{context}"] - -= Release Notes for Red Hat {ServerlessProductName} 1.12.0 - -[id="new-features-1-12-0_{context}"] -== New features - -* {ServerlessProductName} now uses Knative Serving 0.18.2. -* {ServerlessProductName} uses Knative Eventing 0.18.6. -* {ServerlessProductName} now uses Kourier 0.18.0. -* {ServerlessProductName} now uses Knative `kn` CLI 0.18.4. -* {ServerlessProductName} now uses Knative Kafka 0.18.0. - -[id="fixed-issues-1-12-0_{context}"] -== Fixed issues - -* In previous versions, if you used a ping source with OpenShift Serverless, after you uninstalled and deleted all other Knative Eventing components, the `pingsource-jobrunner` deployment was not deleted. This issue is now fixed, and the `pingsource-jobrunner` deployment has been renamed to `pingsource-mt-adapter`. -* In previous versions, deleting a sink before you delete the `SinkBinding` resource connected to it caused the resource deletion to hang. This issue is now fixed. - -[id="known-issues-1-12-0_{context}"] -== Known issues - -* Using the `eventing.knative.dev/scope: namespace` annotation for the `KafkaChannel` objects is not supported. diff --git a/modules/serverless-rn-1-13-0.adoc b/modules/serverless-rn-1-13-0.adoc deleted file mode 100644 index 39fd961293f0..000000000000 --- a/modules/serverless-rn-1-13-0.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/release-notes.adoc - -[id="serverless-rn-1-13-0_{context}"] -//update the <version> to match the filename - -= Release Notes for Red Hat {ServerlessProductName} 1.13.0 - -[id="new-features-1-13-0_{context}"] -== New features - -* {ServerlessProductName} now uses Knative Serving 0.19.0. -* {ServerlessProductName} uses Knative Eventing 0.19.2. -* {ServerlessProductName} now uses Kourier 0.19.0. -* {ServerlessProductName} now uses Knative `kn` CLI 0.19.1. -* {ServerlessProductName} now uses Knative Kafka 0.19.1. -* A `DomainMapping` custom resource (CR) has been added to {ServerlessProductName} to enable users to map a custom domain name to a Knative Service. See the Knative documentation on https://knative.dev/docs/serving/creating-domain-mappings/[Creating a mapping between a custom domain name and a Knative Service]. -* In Knative Serving 0.19.0, `v1alpha1` and `v1beta1` versions of the `Service`, `Route`, `Configuration`, and `Revision` resources have been removed. The {ServerlessOperatorName} automatically upgrades older resources to `v1`, so no user action is required. -+ -[NOTE] -==== -New resources must not be created as `v1alpha1` or `v1beta1` versions, since this can cause errors and these resources will not be upgraded automatically. -==== - -// [id="fixed-issues-1-13-0_{context}"] -// == Fixed issues - -// [id="known-issues-1-13-0_{context}"] -// == Known issues diff --git a/modules/serverless-service-ac-event-sources.adoc b/modules/serverless-service-ac-event-sources.adoc deleted file mode 100644 index ddad894d6448..000000000000 --- a/modules/serverless-service-ac-event-sources.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/event_workflows/serverless-listing-event-sources.adoc - -[id="serverless-service-ac-event-sources_context"] -= Creating a service account, role, and binding for event sources - -.Procedure - -. Create a service account, role, and role binding for the event source by creating a file named `authentication.yaml` and copying the following sample code into it: -+ - -[source,yaml] ----- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: events-sa - namespace: default <1> - ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: Role -metadata: - name: event-watcher - namespace: default <1> -rules: - - apiGroups: - - "" - resources: - - events - verbs: - - get - - list - - watch - ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: k8s-ra-event-watcher - namespace: default <1> -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: Role - name: event-watcher -subjects: - - kind: ServiceAccount - name: events-sa - namespace: default <1> ----- - -+ -<1> Change this namespace to the namespace that you have selected for installing the event source. -+ -[NOTE] -==== -If you want to re-use an existing service account with the appropriate permissions, you must modify the `authentication.yaml` for that service account. -==== - -. Create the service account, role binding, and cluster binding by entering the following command: -+ - -[source,terminal] ----- -$ oc apply --filename authentication.yaml ----- diff --git a/modules/serverless-service-mesh-enable-sidecar-injection.adoc b/modules/serverless-service-mesh-enable-sidecar-injection.adoc deleted file mode 100644 index 88b60fc9d32a..000000000000 --- a/modules/serverless-service-mesh-enable-sidecar-injection.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// * serverless/networking/serverless-ossm.adoc -// * serverless/networking/serverless-ossm-jwt.adoc - -[id="serverless-enable-sidecar_{context}"] -= Enabling sidecar injection for a Knative service - -You can add an annotation to the Service resource YAML file to enable sidecar injection for a Knative service. - -.Procedure - -. Add the `sidecar.istio.io/inject="true"` annotation to the Service resource: -+ - -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: hello-example-1 -spec: - template: - metadata: - annotations: - sidecar.istio.io/inject: "true" <1> - spec: - containers: - - image: docker.io/openshift/hello-openshift - name: container ----- -<1> Add the `sidecar.istio.io/inject="true"` annotation. - -. Apply the Service resource YAML file: -+ - -[source,terminal] ----- -$ oc apply -f <filename> ----- diff --git a/modules/serverless-service-mesh-resources.adoc b/modules/serverless-service-mesh-resources.adoc deleted file mode 100644 index 9227be0a29d0..000000000000 --- a/modules/serverless-service-mesh-resources.adoc +++ /dev/null @@ -1,136 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-custom-domains.adoc - -[id="serverless-service-mesh-resources_{context}"] -= Creating necessary {ProductShortName} resources - -.Procedure - -. Create an Istio gateway to accept traffic. -.. Create a YAML file, and copy the following YAML into it: -+ - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: Gateway -metadata: - name: default-gateway -spec: - selector: - istio: ingressgateway - servers: - - port: - number: 80 - name: http - protocol: HTTP - hosts: - - "*" ----- - -.. Apply the YAML file: -+ - -[source,terminal] ----- -$ oc apply -f <filename> ----- - -. Create an Istio `VirtualService` object to rewrite the host header. -.. Create a YAML file, and copy the following YAML into it: -+ - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: VirtualService -metadata: - name: hello -spec: - hosts: - - custom-ksvc-domain.example.com - gateways: - - default-gateway - http: - - rewrite: - authority: hello.default.svc <1> - route: - - destination: - host: hello.default.svc <1> - port: - number: 80 ----- -<1> Your Knative service in the format `<service_name>.<namespace>.svc`. - -.. Apply the YAML file: -+ - -[source,terminal] ----- -$ oc apply -f <filename> ----- - -. Create an Istio `ServiceEntry` object. This is required for {ServerlessProductName} because Kourier is outside of the service mesh. -.. Create a YAML file, and copy the following YAML into it: -+ - -[source,yaml] ----- -apiVersion: networking.istio.io/v1alpha3 -kind: ServiceEntry -metadata: - name: hello.default.svc -spec: - hosts: - - hello.default.svc <1> - location: MESH_EXTERNAL - endpoints: - - address: kourier-internal.knative-serving-ingress.svc - ports: - - number: 80 - name: http - protocol: HTTP - resolution: DNS ----- -<1> Your Knative service in the format `<service_name>.<namespace>.svc`. - -.. Apply the YAML file: -+ - -[source,terminal] ----- -$ oc apply -f <filename> ----- - -. Create an {product-title} route that points to the `VirtualService` object. -.. Create a YAML file, and copy the following YAML into it: -+ - -[source,yaml] ----- -apiVersion: route.openshift.io/v1 -kind: Route -metadata: - name: hello - namespace: istio-system <1> -spec: - host: custom-ksvc-domain.example.com - port: - targetPort: 8080 - to: - kind: Service - name: istio-ingressgateway ----- - -<1> The {product-title} route must be created in the same namespace as the -ServiceMeshControlPlane. In this example, the ServiceMeshControlPlane is -deployed in the `istio-system` namespace. - -.. Apply the YAML file: -+ - -[source,terminal] ----- -$ oc apply -f <filename> ----- diff --git a/modules/serverless-sinkbinding-kn.adoc b/modules/serverless-sinkbinding-kn.adoc deleted file mode 100644 index b1fc1ec78083..000000000000 --- a/modules/serverless-sinkbinding-kn.adoc +++ /dev/null @@ -1,177 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-sinkbinding.adoc - -[id="serverless-sinkbinding-kn_{context}"] -= Using sink binding with the Knative CLI - -This guide describes the steps required to create a sink binding instance using `kn` commands. - -.Prerequisites - -* You have Knative Serving and Eventing installed. -* You have the `kn` CLI installed. - -[NOTE] -==== -The following procedure requires you to create YAML files. - -If you change the names of the YAML files from those used in the examples, you must ensure that you also update the corresponding CLI commands. -==== - -[IMPORTANT] -==== -Before developers can use sink binding, cluster administrators must label the namespace that will be configured for sink binding with `bindings.knative.dev/include:"true"`: - -[source,terminal] ----- -$ oc label namespace <namespace> bindings.knative.dev/include=true ----- -==== - -.Procedure - -. To check that sink binding is set up correctly, create a Knative event display service, or event sink, that dumps incoming messages to its log: -+ -[source,terminal] ----- -$ kn service create event-display --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- - -. Create a sink binding instance that directs events to the service: -+ -[source,terminal] ----- -$ kn source binding create bind-heartbeat --subject Job:batch/v1:app=heartbeat-cron --sink ksvc:event-display ----- - -. Create a `CronJob` resource. -.. Create a file named `heartbeats-cronjob.yaml` and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: batch/v1beta1 -kind: CronJob -metadata: - name: heartbeat-cron -spec: -spec: - # Run every minute - schedule: "* * * * *" - jobTemplate: - metadata: - labels: - app: heartbeat-cron - bindings.knative.dev/include: "true" - spec: - template: - spec: - restartPolicy: Never - containers: - - name: single-heartbeat - image: quay.io/openshift-knative/knative-eventing-sources-heartbeats:latest - args: - - --period=1 - env: - - name: ONE_SHOT - value: "true" - - name: POD_NAME - valueFrom: - fieldRef: - fieldPath: metadata.name - - name: POD_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace ----- -+ -[IMPORTANT] -==== -To use sink binding, you must manually add a `bindings.knative.dev/include=true` label to your Knative resources. - -For example, to add this label to a `CronJob` resource, add the following lines to the `Job` resource YAML definition: - -[source,yaml] ----- - jobTemplate: - metadata: - labels: - app: heartbeat-cron - bindings.knative.dev/include: "true" ----- - -==== - -+ -.. After you have created the `heartbeats-cronjob.yaml` file, apply it by entering: -+ -[source,terminal] ----- -$ oc apply -f heartbeats-cronjob.yaml ----- - -. Check that the controller is mapped correctly by entering the following command and inspecting the output: -+ -[source,terminal] ----- -$ kn source binding describe bind-heartbeat ----- -+ -.Example output -[source,terminal] ----- -Name: bind-heartbeat -Namespace: demo-2 -Annotations: sources.knative.dev/creator=minikube-user, sources.knative.dev/lastModifier=minikub ... -Age: 2m -Subject: - Resource: job (batch/v1) - Selector: - app: heartbeat-cron -Sink: - Name: event-display - Resource: Service (serving.knative.dev/v1) - -Conditions: - OK TYPE AGE REASON - ++ Ready 2m ----- - -.Verification - -You can verify that the Kubernetes events were sent to the Knative event sink by looking at the message dumper function logs. - -* View the message dumper function logs by entering the following commands: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -[source,terminal] ----- -$ oc logs $(oc get pod -o name | grep event-display) -c user-container ----- -+ -.Example output -[source,terminal] ----- -☁️ cloudevents.Event -Validation: valid -Context Attributes, - specversion: 1.0 - type: dev.knative.eventing.samples.heartbeat - source: https://knative.dev/eventing-contrib/cmd/heartbeats/#event-test/mypod - id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596 - time: 2019-10-18T15:23:20.809775386Z - contenttype: application/json -Extensions, - beats: true - heart: yes - the: 42 -Data, - { - "id": 1, - "label": "" - } ----- diff --git a/modules/serverless-sinkbinding-yaml.adoc b/modules/serverless-sinkbinding-yaml.adoc deleted file mode 100644 index 70f567d1aac3..000000000000 --- a/modules/serverless-sinkbinding-yaml.adoc +++ /dev/null @@ -1,217 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_sources/serverless-sinkbinding.adoc - -[id="serverless-sinkbinding-yaml_{context}"] -= Using sink binding with the YAML method - -This guide describes the steps required to create a sink binding instance using YAML files. - -.Prerequisites - -* You have Knative Serving and Eventing installed. - -[NOTE] -==== -The following procedure requires you to create YAML files. - -If you change the names of the YAML files from those used in the examples, you must ensure that you also update the corresponding CLI commands. -==== - -[IMPORTANT] -==== -Before developers can use a SinkBinding, cluster administrators must label the namespace that will be configured in the SinkBinding with `bindings.knative.dev/include:"true"`: - -[source,terminal] ----- -$ oc label namespace <namespace> bindings.knative.dev/include=true ----- -==== - -.Procedure - -. To check that sink binding is set up correctly, create a Knative event display service, or event sink, that dumps incoming messages to its log. -.. Copy the following sample YAML into a file named `service.yaml`: -+ -[source,yaml] ----- -apiVersion: serving.knative.dev/v1 -kind: Service -metadata: - name: event-display -spec: - template: - spec: - containers: - - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest ----- - -.. After you have created the `service.yaml` file, apply it by entering: -+ -[source,terminal] ----- -$ oc apply -f service.yaml ----- - -. Create a sink binding instance that directs events to the service. -.. Create a file named `sinkbinding.yaml` and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: sources.knative.dev/v1alpha1 -kind: SinkBinding -metadata: - name: bind-heartbeat -spec: - subject: - apiVersion: batch/v1 - kind: Job <1> - selector: - matchLabels: - app: heartbeat-cron - - sink: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display ----- -<1> In this example, any Job with the label `app: heartbeat-cron` will be bound to the event sink. - -.. After you have created the `sinkbinding.yaml` file, apply it by entering: -+ -[source,terminal] ----- -$ oc apply -f sinkbinding.yaml ----- - -. Create a `CronJob` resource. -.. Create a file named `heartbeats-cronjob.yaml` and copy the following sample code into it: -+ -[source,yaml] ----- -apiVersion: batch/v1beta1 -kind: CronJob -metadata: - name: heartbeat-cron -spec: -spec: - # Run every minute - schedule: "* * * * *" - jobTemplate: - metadata: - labels: - app: heartbeat-cron - bindings.knative.dev/include: "true" - spec: - template: - spec: - restartPolicy: Never - containers: - - name: single-heartbeat - image: quay.io/openshift-knative/knative-eventing-sources-heartbeats:latest - args: - - --period=1 - env: - - name: ONE_SHOT - value: "true" - - name: POD_NAME - valueFrom: - fieldRef: - fieldPath: metadata.name - - name: POD_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace ----- -+ -[IMPORTANT] -==== -To use sink binding, you must manually add a `bindings.knative.dev/include=true` label to your Knative resources. - -For example, to add this label to a `CronJob` resource, add the following lines to the `Job` resource YAML definition: - -[source,yaml] ----- - jobTemplate: - metadata: - labels: - app: heartbeat-cron - bindings.knative.dev/include: "true" ----- - -==== -+ -.. After you have created the `heartbeats-cronjob.yaml` file, apply it by entering: -+ -[source,terminal] ----- -$ oc apply -f heartbeats-cronjob.yaml ----- - -. Check that the controller is mapped correctly by entering the following command and inspecting the output: -+ -[source,terminal] ----- -$ oc get sinkbindings.sources.knative.dev bind-heartbeat -oyaml ----- -+ -.Example output -[source,yaml] ----- -spec: - sink: - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display - namespace: default - subject: - apiVersion: batch/v1 - kind: Job - namespace: default - selector: - matchLabels: - app: heartbeat-cron ----- - -.Verification - -You can verify that the Kubernetes events were sent to the Knative event sink by looking at the message dumper function logs. - -. Enter the command: -+ -[source,terminal] ----- -$ oc get pods ----- - -. Enter the command: -+ -[source,terminal] ----- -$ oc logs $(oc get pod -o name | grep event-display) -c user-container ----- -+ -.Example output -[source,terminal] ----- -☁️ cloudevents.Event -Validation: valid -Context Attributes, - specversion: 1.0 - type: dev.knative.eventing.samples.heartbeat - source: https://knative.dev/eventing-contrib/cmd/heartbeats/#event-test/mypod - id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596 - time: 2019-10-18T15:23:20.809775386Z - contenttype: application/json -Extensions, - beats: true - heart: yes - the: 42 -Data, - { - "id": 1, - "label": "" - } ----- diff --git a/modules/serverless-subscription-event-delivery-config.adoc b/modules/serverless-subscription-event-delivery-config.adoc deleted file mode 100644 index 1b37f1d5de79..000000000000 --- a/modules/serverless-subscription-event-delivery-config.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/event_workflows/serverless-event-delivery.adoc - -[id="serverless-subscription-event-delivery-config_{context}"] -= Configuring event delivery failure parameters using subscriptions - -Developers can configure event delivery parameters for individual subscriptions by modifying the `delivery` settings for a `Subscription` object. - -.Example subscription YAML -[source,yaml] ----- -apiVersion: messaging.knative.dev/v1 -kind: Subscription -metadata: - name: <subscription_name> - namespace: <subscription_namespace> -spec: - delivery: - deadLetterSink: <1> - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: <sink_name> - backoffDelay: <duration> <2> - backoffPolicy: <policy_type> <3> - retry: <integer> <4> ----- -<1> Configuration settings to enable using a dead letter sink. This tells the subscription what happens to events that cannot be delivered to the subscriber. -+ -When this is configured, events that fail to be delivered are sent to the dead letter sink destination. The destination can be a Knative service or a URI. -<2> You can set the `backoffDelay` delivery parameter to specify the time delay before an event delivery retry is attempted after a failure. The duration of the `backoffDelay` parameter is specified using the https://en.wikipedia.org/wiki/ISO_8601#Durations[ISO 8601] format. For example, `PT1S` specifies a 1 second delay. -<3> The `backoffPolicy` delivery parameter can be used to specify the retry back off policy. The policy can be specified as either `linear` or `exponential`. When using the `linear` back off policy, the back off delay is the time interval specified between retries. When using the `exponential` back off policy, the back off delay is equal to `backoffDelay*2^<numberOfRetries>`. -<4> The number of times that event delivery is retried before the event is sent to the dead letter sink. diff --git a/modules/serverless-uninstalling-knative-eventing.adoc b/modules/serverless-uninstalling-knative-eventing.adoc deleted file mode 100644 index c077aea0c819..000000000000 --- a/modules/serverless-uninstalling-knative-eventing.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/installing_serverless/installing-openshift-serverless.adoc - -[id="serverless-uninstalling-knative-eventing_{context}"] -= Uninstalling Knative Eventing - -To uninstall Knative Eventing, you must remove its custom resource and delete the `knative-eventing` namespace. - -.Procedure - -. Delete the `knative-eventing` custom resource: -+ - -[source,terminal] ----- -$ oc delete knativeeventings.operator.knative.dev knative-eventing -n knative-eventing ----- - -. After the command has completed and all pods have been removed from the `knative-eventing` namespace, delete the namespace: -+ - -[source,terminal] ----- -$ oc delete namespace knative-eventing ----- diff --git a/modules/serverless-uninstalling-knative-serving.adoc b/modules/serverless-uninstalling-knative-serving.adoc deleted file mode 100644 index aa792ea94cce..000000000000 --- a/modules/serverless-uninstalling-knative-serving.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/installing_serverless/installing-openshift-serverless.adoc - -[id="serverless-uninstalling-knative-serving_{context}"] -= Uninstalling Knative Serving - -To uninstall Knative Serving, you must remove its custom resource and delete the `knative-serving` namespace. - -.Procedure - -. Delete the `knative-serving` custom resource: -+ - -[source,terminal] ----- -$ oc delete knativeservings.operator.knative.dev knative-serving -n knative-serving ----- - -. After the command has completed and all pods have been removed from the `knative-serving` namespace, delete the namespace: -+ - -[source,terminal] ----- -$ oc delete namespace knative-serving ----- diff --git a/modules/serverless-update-subscriptions-kn.adoc b/modules/serverless-update-subscriptions-kn.adoc deleted file mode 100644 index 4c0bd405d9c0..000000000000 --- a/modules/serverless-update-subscriptions-kn.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/event_workflows/serverless-subs.adoc - -[id="serverless-update-subscriptions-kn_{context}"] -= Updating subscriptions - -You can update a subscription by using the `kn` CLI. - -.Prerequisites - -To update subscriptions using the `kn` CLI, ensure that: - -* The {ServerlessOperatorName} and Knative Eventing are installed on your {product-title} cluster. -* You have installed the `kn` CLI. -* You have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}. -* You have created a subscription. - -.Procedure - -* Update a subscription: -+ -[source,terminal] ----- -$ kn subscription update <subscription_name> \ - --sink <sink_prefix>:<sink_name> \ <1> - --sink-dead-letter <sink_prefix>:<sink_name> <2> ----- -<1> `--sink` specifies the updated target destination to which the event should be delivered. You can specify the type of the sink by using one of the following prefixes: -`ksvc`:: A Knative service. -`channel`:: A channel that should be used as destination. Only default channel types can be referenced here. -`broker`:: An Eventing broker. -<2> Optional: `--sink-dead-letter` is an optional flag that can be used to specify a sink which events should be sent to in cases where events fail to be delivered. For more information, see the {ServerlessProductName} _Event delivery_ documentation. -+ -.Example command -[source,terminal] ----- -$ kn subscription update mysubscription --sink ksvc:event-display ----- diff --git a/modules/serverless-upgrade-sub-channel.adoc b/modules/serverless-upgrade-sub-channel.adoc deleted file mode 100644 index 12c063142e8d..000000000000 --- a/modules/serverless-upgrade-sub-channel.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/installing_serverless/upgrading-serverless.adoc - -[id="serverless-upgrade-sub-channel_{context}"] -= Upgrading the Subscription Channel - -.Prerequisites -* You have installed a previous version of {ServerlessOperatorName}, and have selected Automatic updates during the installation process. -+ -[NOTE] -==== -If you have selected Manual updates, you will need to complete additional steps after updating the channel as described in this guide. The Subscription’s upgrade status will remain *Upgrading* until you review and approve its Install Plan. Information about the Install Plan can be found in the {product-title} Operators documentation. -==== -* You have logged in to the {product-title} web console. - -.Procedure - -. Select the `openshift-operators` namespace in the {product-title} web console. -. Navigate to the *Operators* -> *Installed Operators* page. -. Select the *{ServerlessOperatorName} Operator*. -. Click *Subscription* -> *Channel*. -. In the *Change Subscription Update Channel* window, select *4.6*, and then click *Save*. -. Wait until all pods have been upgraded in the `knative-serving` namespace and the `KnativeServing` custom resource reports the latest Knative Serving version. - -.Verification - -To verify that the upgrade has been successful, you can check the status of pods in the `knative-serving` namespace, and the version of the `KnativeServing` custom resource. - -. Check the status of the pods: -+ -[source,terminal] ----- -$ oc get knativeserving.operator.knative.dev knative-serving -n knative-serving -o=jsonpath='{.status.conditions[?(@.type=="Ready")].status}' ----- -+ -This command should return a status of `True`. - -. Check the version of the `KnativeServing` custom resource: -+ -[source,terminal] ----- -$ oc get knativeserving.operator.knative.dev knative-serving -n knative-serving -o=jsonpath='{.status.version}' ----- -+ -This command should return the latest version of Knative Serving. You can check the latest version in the {ServerlessOperatorName} release notes. diff --git a/modules/serverless-using-cluster-logging-find-logs-knative-serving-components.adoc b/modules/serverless-using-cluster-logging-find-logs-knative-serving-components.adoc deleted file mode 100644 index ddb671b9d515..000000000000 --- a/modules/serverless-using-cluster-logging-find-logs-knative-serving-components.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/cluster-logging-serverless.adoc - -[id="using-cluster-logging-to-find-logs-for-knative-serving-components_{context}"] -= Using OpenShift Logging to find logs for Knative Serving components - -.Procedure - -. Get the Kibana route: -+ -[source,terminal] ----- -$ oc -n openshift-logging get route kibana ----- -. Use the route's URL to navigate to the Kibana dashboard and log in. -. Check that the index is set to *.all*. If the index is not set to *.all*, only the OpenShift system logs will be listed. -. Filter the logs by using the `knative-serving` namespace. Enter `kubernetes.namespace_name:knative-serving` in the search box to filter results. - -[NOTE] -==== -Knative Serving uses structured logging by default. You can enable the parsing of these logs by customizing the OpenShift Logging Fluentd settings. This makes the logs more searchable and enables filtering on the log level to quickly identify issues. -==== diff --git a/modules/serverless-using-cluster-logging-find-logs-services-deployed.adoc b/modules/serverless-using-cluster-logging-find-logs-services-deployed.adoc deleted file mode 100644 index f85a0922d625..000000000000 --- a/modules/serverless-using-cluster-logging-find-logs-services-deployed.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// serverless/cluster-logging-serverless.adoc -[id="using-cluster-logging-to-find-logs-for-services-deployed-with-knative-serving_{context}"] -= Using OpenShift Logging to find logs for services deployed with Knative Serving - -With OpenShift Logging, the logs that your applications write to the console are collected in Elasticsearch. The following procedure outlines how to apply these capabilities to applications deployed by using Knative Serving. - -.Procedure -. Get the Kibana route: -+ -[source,terminal] ----- -$ oc -n openshift-logging get route kibana ----- -. Use the route's URL to navigate to the Kibana dashboard and log in. -. Check that the index is set to *.all*. If the index is not set to *.all*, only the OpenShift system logs will be listed. -. Filter the logs by using the `knative-serving` namespace. Enter a filter for the service in the search box to filter results. -+ -.Example filter -[source,terminal] ----- -kubernetes.namespace_name:default AND kubernetes.labels.serving_knative_dev\/service:{service_name} ----- -+ -You can also filter by using `/configuration` or `/revision`. -. Narrow your search by using `kubernetes.container_name:<user_container>` to only display the logs generated by your application. Otherwise, you will see logs from the queue-proxy. - -[NOTE] -==== -Use JSON-based structured logging in your application to allow for the quick filtering of these logs in production environments. -==== diff --git a/modules/serverless-workflow-autoscaling-kn.adoc b/modules/serverless-workflow-autoscaling-kn.adoc deleted file mode 100644 index f706cce5d5ce..000000000000 --- a/modules/serverless-workflow-autoscaling-kn.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative_serving/configuring-knative-serving-autoscaling.adoc - -[id="autoscaling-workflow-kn_{context}"] -= Autoscaling workflow using the Knative `kn` CLI - -You can edit autoscaling capabilities for your cluster by using `kn` to modify Knative services without editing YAML files directly. - -You can use the `kn service create` and `kn service update` commands with the appropriate flags as described below to configure autoscaling behavior. - -[cols="1,3",options="header"] -|=== -| Flag -| Description - -| `--concurrency-limit int` -| Sets a hard limit of concurrent requests to be processed by a single revision. - -| `--concurrency-target int` -| Provides a recommendation for when to scale up revisions, based on the concurrent number of incoming requests. Defaults to `--concurrency-limit`. - -| `--max-scale int` -| Maximum number of revisions. - -| `--min-scale int` -| Minimum number of revisions. -|=== diff --git a/modules/serverless-workflow-tag-revisions-assign.adoc b/modules/serverless-workflow-tag-revisions-assign.adoc deleted file mode 100644 index 2b82c4cd23ae..000000000000 --- a/modules/serverless-workflow-tag-revisions-assign.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative-client.adoc - -[id="assigning-tag-revisions_{context}"] -= Assigning tag revisions - -A tag in a traffic block of service creates a custom URL, which points to a referenced revision. A user can define a unique tag for an available revision of a service which creates a custom URL by using the format `http(s)://TAG-SERVICE.DOMAIN`. - -A given tag must be unique to its traffic block of the service. `kn` supports assigning and unassigning custom tags for revisions of services as part of the `kn service update` command. - -[NOTE] -==== -If you have assigned a tag to a particular revision, a user can reference the revision by its tag in the `--traffic` flag as `--traffic Tag=Percent`. -==== - - -.Procedure -* Use the following command: -+ - -[source,terminal] ----- -$ kn service update svc --tag @latest=candidate --tag svc-vwxyz=current ----- - -[NOTE] -==== -`--tag RevisionName=Tag` uses the following syntax: - -* `--tag` flag requires two values separated by a `=`. - -* `RevisionName` string refers to name of the `Revision`. - -* `Tag` string denotes the custom tag to be given for this Revision. - -* Use the identifier `@latest` for the RevisionName to refer to the latest ready revision of the service. You can use this identifier only once with the `--tag` flag. - -* If the `service update` command is updating the configuration values for the Service (along with tag flags), `@latest` reference will be pointed to the created Revision after applying the update. - -* `--tag` flag can be specified multiple times. - -* `--tag` flag may assign different tags to the same revision. -==== diff --git a/modules/serverless-workflow-tag-revisions-unassign.adoc b/modules/serverless-workflow-tag-revisions-unassign.adoc deleted file mode 100644 index 172edf821008..000000000000 --- a/modules/serverless-workflow-tag-revisions-unassign.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative-client.adoc - -[id="unassigning-tag-revisions_{context}"] -= Unassigning tag revisions - -Tags assigned to revisions in a traffic block can be unassigned. Unassigning tags removes the custom URLs. - -[NOTE] -==== -If a revision is untagged and it is assigned 0% of the traffic, it is removed from the traffic block entirely. -==== - -.Procedure -* A user can unassign the tags for revisions using the `kn service update` command: -+ - -[source,terminal] ----- -$ kn service update svc --untag candidate ----- - -[NOTE] -==== -`--untag Tag` uses the following syntax: - -* The `--untag` flag requires one value. -* The `tag` string denotes the unique tag in the traffic block of the service which needs to be unassigned. This also removes the respective custom URL. -* The `--untag` flag can be specified multiple times. -==== diff --git a/modules/serverless-workflow-traffic-flag-operation-precedence.adoc b/modules/serverless-workflow-traffic-flag-operation-precedence.adoc deleted file mode 100644 index 5aad068b83d4..000000000000 --- a/modules/serverless-workflow-traffic-flag-operation-precedence.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative-client.adoc - -[id="traffic-flag-operation-precedence_{context}"] -= Traffic flag operation precedence - -All traffic-related flags can be specified using a single `kn service update` command. -`kn` defines the precedence of these flags. The order of the flags specified when using the command is not taken into account. - -The precedence of the flags as they are evaluated by `kn` are: - -. `--untag`: All the referenced revisions with this flag are removed from the traffic block. -. `--tag`: Revisions are tagged as specified in the traffic block. -. `--traffic`: The referenced revisions are assigned a portion of the traffic split. diff --git a/modules/serverless-workflow-traffic-splitting-flags.adoc b/modules/serverless-workflow-traffic-splitting-flags.adoc deleted file mode 100644 index a9ecf271223a..000000000000 --- a/modules/serverless-workflow-traffic-splitting-flags.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module is included in the following assemblies: -// -//serverless/knative-client.adoc - -[id="traffice-splitting-flags_{context}"] -= Traffic splitting flags - -`kn` supports traffic operations on the traffic block of a service as part of the `kn service update` command. - -The following table displays a summary of traffic splitting flags, value formats, and the operation the flag performs. The *Repetition* column denotes whether repeating the particular value of flag is allowed in a `kn service update` command. - -[cols="1,1,2,1",options="header"] -|=== -| Flag -| Value(s) -| Operation -| Repetition - -|`--traffic` -| `RevisionName=Percent` -| Gives `Percent` traffic to `RevisionName` -| Yes - -|`--traffic` -| `Tag=Percent` -| Gives `Percent` traffic to the revision having `Tag` -| Yes - -|`--traffic` -| `@latest=Percent` -| Gives `Percent` traffic to the latest ready revision -| No - -|`--tag` -| `RevisionName=Tag` -| Gives `Tag` to `RevisionName` -| Yes - -|`--tag` -| `@latest=Tag` -| Gives `Tag` to the latest ready revision -| No - -|`--untag` -| `Tag` -| Removes `Tag` from revision -| Yes - -|=== diff --git a/modules/service-accounts-as-oauth-clients.adoc b/modules/service-accounts-as-oauth-clients.adoc deleted file mode 100644 index 5228fa0b1748..000000000000 --- a/modules/service-accounts-as-oauth-clients.adoc +++ /dev/null @@ -1,157 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts-as-oauth-client.adoc - -[id="service-accounts-as-oauth-clients_{context}"] -= Service accounts as OAuth clients - -You can use a service account as a constrained form of OAuth client. -Service accounts can request only a subset of scopes that -allow access to some basic user information -and role-based power inside of the service account's own namespace: - -* `user:info` -* `user:check-access` -* `role:<any_role>:<service_account_namespace>` -* `role:<any_role>:<service_account_namespace>:!` - -When using a service account as an OAuth client: - -* `client_id` is `system:serviceaccount:<service_account_namespace>:<service_account_name>`. -* `client_secret` can be any of the API tokens for that service account. For example: -+ -[source,terminal] ----- -$ oc sa get-token <service_account_name> ----- - -* To get `WWW-Authenticate` challenges, set an -`serviceaccounts.openshift.io/oauth-want-challenges` annotation on the service -account to `true`. - -* `redirect_uri` must match an annotation on the service account. - -[id="redirect-uris-for-service-accounts_{context}"] -== Redirect URIs for service accounts as OAuth clients - -Annotation keys must have the prefix -`serviceaccounts.openshift.io/oauth-redirecturi.` or -`serviceaccounts.openshift.io/oauth-redirectreference.` such as: - ----- -serviceaccounts.openshift.io/oauth-redirecturi.<name> ----- - -In its simplest form, the annotation can be used to directly specify valid -redirect URIs. For example: - ----- -"serviceaccounts.openshift.io/oauth-redirecturi.first": "https://example.com/" -"serviceaccounts.openshift.io/oauth-redirecturi.second": "https://other.com/" ----- - -The `first` and `second` postfixes in the above example are used to separate the -two valid redirect URIs. - -In more complex configurations, static redirect URIs may not be enough. For -example, perhaps you want all Ingresses for a route to be considered valid. This -is where dynamic redirect URIs via the -`serviceaccounts.openshift.io/oauth-redirectreference.` prefix come into play. - -For example: - ----- -"serviceaccounts.openshift.io/oauth-redirectreference.first": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}" ----- - -Since the value for this annotation contains serialized JSON data, it is easier -to see in an expanded format: - ----- - -{ - "kind": "OAuthRedirectReference", - "apiVersion": "v1", - "reference": { - "kind": "Route", - "name": "jenkins" - } -} - ----- - -Now you can see that an `OAuthRedirectReference` allows us to reference the -route named `jenkins`. Thus, all Ingresses for that route will now be considered -valid. The full specification for an `OAuthRedirectReference` is: - ----- - -{ - "kind": "OAuthRedirectReference", - "apiVersion": "v1", - "reference": { - "kind": ..., <1> - "name": ..., <2> - "group": ... <3> - } -} - ----- - -<1> `kind` refers to the type of the object being referenced. Currently, only `route` is supported. -<2> `name` refers to the name of the object. The object must be in the same namespace as the service account. -<3> `group` refers to the group of the object. Leave this blank, as the group for a route is the empty string. - -Both annotation prefixes can be combined to override the data provided by the -reference object. For example: - ----- -"serviceaccounts.openshift.io/oauth-redirecturi.first": "custompath" -"serviceaccounts.openshift.io/oauth-redirectreference.first": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}" ----- - -The `first` postfix is used to tie the annotations together. Assuming that the -`jenkins` route had an Ingress of `\https://example.com`, now -`\https://example.com/custompath` is considered valid, but -`\https://example.com` is not. The format for partially supplying override -data is as follows: - -[cols="4a,8a",options="header"] -|=== -|Type | Syntax -|Scheme| "https://" -|Hostname| "//website.com" -|Port| "//:8000" -|Path| "examplepath" -|=== - -[NOTE] -==== -Specifying a host name override will replace the host name data from the -referenced object, which is not likely to be desired behavior. -==== - -Any combination of the above syntax can be combined using the following format: - -`<scheme:>//<hostname><:port>/<path>` - -The same object can be referenced more than once for more flexibility: - ----- -"serviceaccounts.openshift.io/oauth-redirecturi.first": "custompath" -"serviceaccounts.openshift.io/oauth-redirectreference.first": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}" -"serviceaccounts.openshift.io/oauth-redirecturi.second": "//:8000" -"serviceaccounts.openshift.io/oauth-redirectreference.second": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}" ----- - -Assuming that the route named `jenkins` has an Ingress of -`\https://example.com`, then both `\https://example.com:8000` and -`\https://example.com/custompath` are considered valid. - -Static and dynamic annotations can be used at the same time to achieve the -desired behavior: - ----- -"serviceaccounts.openshift.io/oauth-redirectreference.first": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}" -"serviceaccounts.openshift.io/oauth-redirecturi.second": "https://other.com/" ----- diff --git a/modules/service-accounts-configuration-parameters.adoc b/modules/service-accounts-configuration-parameters.adoc deleted file mode 100644 index bbaad7f9c96a..000000000000 --- a/modules/service-accounts-configuration-parameters.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-configuration-parameters_{context}"] -= Service account configuration parameters - -You can provide values for the following service account parameters in the -*_/etc/origin/master/master-config.yml_* file on the master host. - -.Service account configuration parameters -[cols="3a,3a,6a",options="header"] -|=== - -| Parameter Name | Type | Description - -|`LimitSecretReferences` -|Boolean -|Controls whether or not to allow a service account to reference any secret in a -namespace without explicitly referencing them. - -|`ManagedNames` -|String -|A list of service account names that is automatically created in each namespace. -If no names are specified, the `ServiceAccountsController` service does not -start. - -|`MasterCA` -|String -|The CA that verifies the TLS connection back to the master. The service account -controller automatically injects the contents of this file into pods so they -can verify connections to the master. - -|`PrivateKeyFile` -|String -|A file that contains a PEM-encoded private RSA key, which is used to sign -service account tokens. If no private key is specified, the service account -`TokensController` service does not start. - -|`PublicKeyFiles` -|String -|A list of files, each of which contains a PEM-encoded public RSA key. If any file -contains a private key, the public portion of the key is used. The list of -public keys is used to verify presented service account tokens. Each key is -tried in order until the list is exhausted or verification succeeds. If no keys -are specified, no service account authentication is available. - -|`ServiceAccountConfig` -|List -|The parameter that contains the other listed service account parameters. - -|=== diff --git a/modules/service-accounts-creating.adoc b/modules/service-accounts-creating.adoc deleted file mode 100644 index d1a8bb8ca7eb..000000000000 --- a/modules/service-accounts-creating.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-managing_{context}"] -= Creating service accounts - -You can create a service account in a project and grant it permissions by -binding it to a role. - -.Procedure - -. Optional: To view the service accounts in the current project: -+ -[source,terminal] ----- -$ oc get sa ----- -+ -.Example output -[source,terminal] ----- -NAME SECRETS AGE -builder 2 2d -default 2 2d -deployer 2 2d ----- - -. To create a new service account in the current project: -+ -[source,terminal] ----- -$ oc create sa <service_account_name> <1> ----- -<1> To create a service account in a different project, specify `-n <project_name>`. -+ -.Example output -[source,terminal] ----- -serviceaccount "robot" created ----- - -. Optional: View the secrets for the service account: -+ -[source,terminal] ----- -$ oc describe sa robot ----- -+ -.Example output -[source,terminal] ----- -Name: robot -Namespace: project1 -Labels: <none> -Annotations: <none> - -Image pull secrets: robot-dockercfg-qzbhb - -Mountable secrets: robot-token-f4khf - robot-dockercfg-qzbhb - -Tokens: robot-token-f4khf - robot-token-z8h44 ----- diff --git a/modules/service-accounts-dedicated-admin-role.adoc b/modules/service-accounts-dedicated-admin-role.adoc deleted file mode 100644 index 71d6cb57c1d5..000000000000 --- a/modules/service-accounts-dedicated-admin-role.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - - -[id="service-accounts-dedicated-admin-role_{context}"] -ifdef::openshift-dedicated[] -= Service accounts in {product-title} - -As an administrator, you can use service accounts to perform any -actions that require {product-title} `admin` roles. - -The `dedicated-admin` service creates the `dedicated-admins` group. This group -is granted the roles at the cluster or individual project -level. Users can be assigned to this group, and group membership defines who has -{product-title} administrator access. However, by design, service accounts -cannot be added to regular groups. - -Instead, the `dedicated-admin` service creates a special project for this -purpose named `dedicated-admin`. The service account group for this project is -granted {product-title} `admin` roles, which grants {product-title} administrator -access to all service accounts within the `dedicated-admin` project. You can -then use these service accounts to perform any actions that require -{product-title} administrator access. - -Users that are members of the `dedicated-admins` group are granted the -`dedicated-admin` role permissions and have `edit` access to the `dedicated-admin` -project. These users can manage the service accounts in this project -and create new ones as needed. - -Users with a `dedicated-reader` role are granted edit and view access to the -`dedicated-reader` project and view-only access to the other projects. -endif::[] diff --git a/modules/service-accounts-default.adoc b/modules/service-accounts-default.adoc deleted file mode 100644 index d4ca2b17c47c..000000000000 --- a/modules/service-accounts-default.adoc +++ /dev/null @@ -1,73 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-default_{context}"] -= Default service accounts - -Your {product-title} cluster contains default service accounts for -cluster management and generates more service accounts for each project. - -[id="default-cluster-service-accounts_{context}"] -== Default cluster service accounts - -Several infrastructure controllers run using service account credentials. The -following service accounts are created in the {product-title} infrastructure -project (`openshift-infra`) at server start, and given the following roles -cluster-wide: - -[cols="1,3",options="header"] -|==== -|Service Account |Description - -|`replication-controller` -|Assigned the `system:replication-controller` role - -|`deployment-controller` -|Assigned the `system:deployment-controller` role - -|`build-controller` -|Assigned the `system:build-controller` role. Additionally, the -`build-controller` service account is included in the privileged -security context constraint to create privileged -build pods. -|==== - - -//// -To configure the project where those service accounts are created, set the -`openshiftInfrastructureNamespace` field in the -*_/etc/origin/master/master-config.yml_* file on the master: - ----- -policyConfig: - ... - openshiftInfrastructureNamespace: openshift-infra ----- -//// - -[id="default-service-accounts-and-roles_{context}"] -== Default project service accounts and roles - -Three service accounts are automatically created in each project: - -[options="header",cols="1,3"] -|=== -|Service Account |Usage - -|`builder` -|Used by build pods. It is given the `system:image-builder` role, which allows -pushing images to any imagestream in the project using the internal Docker -registry. - -|`deployer` -|Used by deployment pods and given the `system:deployer` role, which allows -viewing and modifying replication controllers and pods in the project. - -|`default` -|Used to run all other pods unless they specify a different service account. -|=== - -All service accounts in a project are given the `system:image-puller` role, -which allows pulling images from any imagestream in the project using the -internal container image registry. diff --git a/modules/service-accounts-enabling-authentication.adoc b/modules/service-accounts-enabling-authentication.adoc deleted file mode 100644 index 17e3ea76e30f..000000000000 --- a/modules/service-accounts-enabling-authentication.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-enabling-authentication_{context}"] -= Enabling service account authentication - -Service accounts authenticate to the API using tokens signed by a private RSA -key. The authentication layer verifies the signature using a matching public RSA -key. - -.Procedure - -* To enable service account token generation, update the `serviceAccountConfig` -stanza in the *_/etc/origin/master/master-config.yml_* file on the master to -specify a `privateKeyFile` (for signing), and a matching public key file in -the `publicKeyFiles` list: -+ -[source,yaml] ----- -serviceAccountConfig: - ... - masterCA: ca.crt <1> - privateKeyFile: serviceaccounts.private.key <2> - publicKeyFiles: - - serviceaccounts.public.key <3> - - ... ----- -<1> CA file to validate the API server's serving certificate. -<2> Private RSA key file for token signing. -<3> Public RSA key files for token verification. If you provide private key -files, then the public key component is used. You can specify multiple public -key files, and a token is accepted if it can be validated by one of the -public keys. This allows rotation of the signing key while still accepting -tokens generated by the previous signer. diff --git a/modules/service-accounts-granting-roles.adoc b/modules/service-accounts-granting-roles.adoc deleted file mode 100644 index 3ad5890e6f4c..000000000000 --- a/modules/service-accounts-granting-roles.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-granting-roles_{context}"] -= Examples of granting roles to service accounts - -You can grant roles to service accounts in the same way that you grant roles -to a regular user account. - -* You can modify the service accounts for the current project. For example, to add -the `view` role to the `robot` service account in the `top-secret` project: -+ -[source,terminal] ----- -$ oc policy add-role-to-user view system:serviceaccount:top-secret:robot ----- - -* You can also grant access to a specific service account in a project. For -example, from the project to which the service account belongs, use -the `-z` flag and specify the `<service_account_name>` - -+ -[source,terminal] ----- -$ oc policy add-role-to-user <role_name> -z <service_account_name> ----- -+ -[IMPORTANT] -==== -If you want to grant access to a specific service account in a project, use the -`-z` flag. Using this flag helps prevent typos and ensures that access -is granted to only the specified service account. -==== - -* To modify a different namespace, you can use the `-n` option to indicate the -project namespace it applies to, as shown in the following examples. - -** For example, to allow all service accounts in all projects to view resources in -the `top-secret` project: -+ -[source,terminal] ----- -$ oc policy add-role-to-group view system:serviceaccounts -n top-secret ----- - -** To allow all service accounts in the `managers` project to edit resources in the -`top-secret` project: -+ -[source,terminal] ----- -$ oc policy add-role-to-group edit system:serviceaccounts:managers -n top-secret ----- diff --git a/modules/service-accounts-overview.adoc b/modules/service-accounts-overview.adoc deleted file mode 100644 index 6678cb45bc95..000000000000 --- a/modules/service-accounts-overview.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-overview_{context}"] -= Service accounts overview - -A service account is an {product-title} account that allows a component to -directly access the API. Service accounts are API objects that exist within each project. -Service accounts provide a flexible way to control API -access without sharing a regular user's credentials. - -When you use the {product-title} CLI or web console, your API token -authenticates you to the API. You can associate a component with a service account -so that they can access the API without using a regular user's credentials. -ifdef::openshift-online,openshift-origin,openshift-dedicated,openshift-enterprise,openshift-webscale[] -For example, service accounts can allow: - -* Replication controllers to make API calls to create or delete pods. -* Applications inside containers to make API calls for discovery purposes. -* External applications to make API calls for monitoring or integration purposes. -endif::[] - -Each service account's user name is derived from its project and name: - ----- -system:serviceaccount:<project>:<name> ----- - -Every service account is also a member of two groups: - -[cols="1,2",options="header"] -|=== - -|Group -|Description - -|system:serviceaccounts -|Includes all service accounts in the system. - -|system:serviceaccounts:<project> -|Includes all service accounts in the -specified project. - -|=== - -Each service account automatically contains two secrets: - -* An API token -* Credentials for the OpenShift Container Registry - -The generated API token and registry credentials do not expire, but you can -revoke them by deleting the secret. When you delete the secret, a new one is -automatically generated to take its place. diff --git a/modules/service-accounts-permissions.adoc b/modules/service-accounts-permissions.adoc new file mode 100644 index 000000000000..35a1752fe1eb --- /dev/null +++ b/modules/service-accounts-permissions.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/review-cluster-configuration.adoc +:_mod-docs-content-type: PROCEDURE +[id="service-accounts-permissions_{context}"] += Finding service accounts and their permissions + +[role="_abstract"] +Use the *Configuration Management* view to find out where service accounts are in use and their permissions. + +.Procedure +. In the {product-title-short} portal, go to *Configuration Management*. +. Select *RBAC Visibility and Configuration* -> *Service Accounts* from the header in the *Configuration Management* view. +The *Service Accounts* view displays a list of Kubernetes service accounts across your clusters, their assigned roles, whether the `cluster-admin` role is enabled, and which deployments use them. +. Select a row or an underlined link to view more details, including which cluster and namespace permissions are granted to the selected service account. diff --git a/modules/service-accounts-using-credentials-externally.adoc b/modules/service-accounts-using-credentials-externally.adoc deleted file mode 100644 index eea3233e8396..000000000000 --- a/modules/service-accounts-using-credentials-externally.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-using-credentials-externally_{context}"] -= Using a service account's credentials externally - -You can distribute a service account's token to external applications that must -authenticate to the API. - -To pull an image, the authenticated user must have `get` rights on the -requested `imagestreams/layers`. To push an image, the authenticated -user must have `update` rights on the requested `imagestreams/layers`. - -By default, all service accounts in a project have rights to pull any image in -the same project, and the *builder* service account has rights to push any image -in the same project. - -.Procedure - -. View the service account's API token: -+ -[source,terminal] ----- -$ oc describe secret <secret_name> ----- -+ -For example: -+ -[source,terminal] ----- -$ oc describe secret robot-token-uzkbh -n top-secret ----- -+ -.Example output -[source,terminal] ----- -Name: robot-token-uzkbh -Labels: <none> -Annotations: kubernetes.io/service-account.name=robot,kubernetes.io/service-account.uid=49f19e2e-16c6-11e5-afdc-3c970e4b7ffe - -Type: kubernetes.io/service-account-token - -Data - -token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... ----- - -. Log in using the token that you obtained: -+ -[source,terminal] ----- -$ oc login --token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... ----- -+ -.Example output -[source,terminal] ----- -Logged into "https://server:8443/" as "system:serviceaccount:top-secret:robot" using the token provided. - -You don't have any projects. You can try to create a new project, by running - - $ oc new-project <projectname> ----- - -. Confirm that you logged in as the service account: -+ -[source,terminal] ----- -$ oc whoami ----- -+ -.Example output -[source,terminal] ----- -system:serviceaccount:top-secret:robot ----- diff --git a/modules/service-accounts-using-credentials-inside-a-container.adoc b/modules/service-accounts-using-credentials-inside-a-container.adoc deleted file mode 100644 index a586c9691155..000000000000 --- a/modules/service-accounts-using-credentials-inside-a-container.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/using-service-accounts.adoc - -[id="service-accounts-using-credentials-inside-a-container_{context}"] -= Using a service account's credentials inside a container - -When a pod is created, it specifies a service account (or uses the default -service account), and is allowed to use that service account's API credentials -and referenced secrets. - -.Procedure - -. View the API token for the pod's service account in the - *_/var/run/secrets/kubernetes.io/serviceaccount/token_* file. - -. Set the token value to the `Token` variable: -+ ----- -$ TOKEN="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" ----- - -. Use the token to make API calls as the pod's service account. For example, -call the `users/~` API to get information about the user identified -by the token: -+ ----- -$ curl --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt \ - "https://openshift.default.svc.cluster.local/oapi/v1/users/~" \ - -H "Authorization: Bearer $TOKEN" - -kind: "User" -apiVersion: "user.openshift.io/v1" -metadata: - name: "system:serviceaccount:top-secret:robot" - selflink: "/oapi/v1/users/system:serviceaccount:top-secret:robot" - creationTimestamp: null -identities: null -groups: - - "system:serviceaccounts" - - "system:serviceaccounts:top-secret" ----- diff --git a/modules/service-ca-certificates.adoc b/modules/service-ca-certificates.adoc deleted file mode 100644 index 9ccd56e4ea1e..000000000000 --- a/modules/service-ca-certificates.adoc +++ /dev/null @@ -1,81 +0,0 @@ -// Module included in the following assemblies: -// -// * security/certificate-types-descriptions.adoc - -[id="service-ca-certificates_{context}"] -= Service CA certificates - -[discrete] -== Purpose - -`service-ca` is an Operator that creates a self-signed CA when an -{product-title} cluster is deployed. - -[discrete] -== Expiration - -A custom expiration term is not supported. The self-signed CA is stored in a -secret with qualified name `service-ca/signing-key` in fields `tls.crt` -(certificate(s)), `tls.key` (private key), and `ca-bundle.crt` (CA bundle). - -Other services can request a service serving certificate by annotating a -service resource with `service.beta.openshift.io/serving-cert-secret-name: -<secret name>`. In response, the Operator generates a new certificate, as -`tls.crt`, and private key, as `tls.key` to the named secret. The certificate -is valid for two years. - -Other services can request that the CA bundle for the service CA be injected -into APIService or ConfigMap resources by annotating with -`service.beta.openshift.io/inject-cabundle: true` to support validating -certificates generated from the service CA. In response, the Operator writes its -current CA bundle to the `CABundle` field of APIService or as `service-ca.crt` -to a ConfigMap. - -As of {product-title} 4.3.5, automated rotation is supported and is backported -to some 4.2.z and 4.3.z releases. For any release supporting automated rotation, -the service CA is valid for 26 months and is automatically refreshed when there -is less than 13 months validity left. If necessary, you can manually refresh -the service CA. - -The service CA expiration of 26 months is longer than the expected upgrade -interval for a supported {product-title} cluster, such that non-control plane -consumers of service CA certificates will be refreshed after CA rotation and -prior to the expiration of the pre-rotation CA. - -[WARNING] -==== -A manually-rotated service CA does not maintain trust with the previous service -CA. You might experience a temporary service disruption until the pods in the -cluster are restarted, which ensures that pods are using service serving -certificates issued by the new service CA. -==== - -[discrete] -== Management - -These certificates are managed by the system and not the user. - -[discrete] -== Services - -Services that use service CA certificates include: - -* cluster-autoscaler-operator -* cluster-monitoring-operator -* cluster-authentication-operator -* cluster-image-registry-operator -* cluster-ingress-operator -* cluster-kube-apiserver-operator -* cluster-kube-controller-manager-operator -* cluster-kube-scheduler-operator -* cluster-networking-operator -* cluster-openshift-apiserver-operator -* cluster-openshift-controller-manager-operator -* cluster-samples-operator -* machine-config-operator -* console-operator -* insights-operator -* machine-api-operator -* operator-lifecycle-manager - -This is not a comprehensive list. diff --git a/modules/service-level-agreement.adoc b/modules/service-level-agreement.adoc new file mode 100644 index 000000000000..26139e05a122 --- /dev/null +++ b/modules/service-level-agreement.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_mod-docs-content-type: CONCEPT +[id="service-level-agreement_{context}"] += Service Level Agreement + +For more information about the Service Level Agreements (SLAs) offered for {rh-rhacscs-first}, see link:https://www.redhat.com/licenses/Appendix_4_Red_Hat_Online_Services_20221213.pdf[PRODUCT APPENDIX 4 RED HAT ONLINE SERVICES]. + diff --git a/modules/set-rox-scanner-init-db-env-variable.adoc b/modules/set-rox-scanner-init-db-env-variable.adoc new file mode 100644 index 000000000000..d23008349124 --- /dev/null +++ b/modules/set-rox-scanner-init-db-env-variable.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="set-up-rox-scanner-env-variable_{context}"] += Set up the `ROX_SCANNER_DB_INIT` environment variable + +ScannerDB's `initContainer` requires a new environment variable called `ROX_SCANNER_DB_INIT`. You must set its value to `true` before you upgrade. + +.Procedure + +* For {ocp}, run the following command: ++ +[source,terminal] +---- +$ oc -n stackrox set env deploy/scanner-db -c init-db ROX_SCANNER_DB_INIT=true +---- +* For Kubernetes, run the following command: ++ +[source,terminal] +---- +$ kubectl -n stackrox set env deploy/scanner-db -c init-db ROX_SCANNER_DB_INIT=true +---- diff --git a/modules/set-up-oauth-20-credentials-for-your-gcp-project.adoc b/modules/set-up-oauth-20-credentials-for-your-gcp-project.adoc new file mode 100644 index 000000000000..4ec0b6651705 --- /dev/null +++ b/modules/set-up-oauth-20-credentials-for-your-gcp-project.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-google-workspace-identity.adoc +:_mod-docs-content-type: PROCEDURE +[id="set-up-oauth-20-credentials-for-your-gcp-project_{context}"] += Setting up OAuth 2.0 credentials for your GCP project + +To configure Google Workspace as an identity provider for {product-title}, you must first configure OAuth 2.0 credentials for your GCP project. + +.Prerequisites +* You must have administrator-level access to your organization's Google Workspace account to create a new project, or permissions to create and configure OAuth 2.0 credentials for an existing project. Red{nbsp}Hat recommends that you create a new project for managing access to {product-title}. + +.Procedure +. Create a new Google Cloud Platform (GCP) project, see the Google documentation topic link:https://cloud.google.com/resource-manager/docs/creating-managing-projects[creating and managing projects]. +. After you have created the project, open the link:https://console.developers.google.com/apis/credentials[*Credentials*] page in the Google API Console. +. Verify the project name listed in the upper left corner near the logo to make sure that you are using the correct project. +. To create new credentials, go to *Create Credentials* -> *OAuth client ID*. +. Choose *Web application* as the *Application type*. +. In the *Name* box, enter a name for the application, for example, *{product-title-short}*. +. In the *Authorized redirect URIs* box, enter `\https://<stackrox_hostname>:<port_number>/sso/providers/oidc/callback`. +** replace `<stackrox_hostname>` with the hostname on which you expose your Central instance. +** replace `<port_number>` with the port number on which you expose Central. +If you are using the standard HTTPS port `443`, you can omit the port number. +. Click *Create*. +This creates an application and credentials and redirects you back to the credentials page. +. An information box opens, showing details about the newly created application. +Close the information box. +. Copy and save the *Client ID* that ends with `.apps.googleusercontent.com`. +You can check this client ID by using the Google API Console. +. Select *OAuth consent screen* from the navigation menu on the left. ++ +[NOTE] +==== +The OAuth consent screen configuration is valid for the entire GCP project, and not only to the application you created in the previous steps. +If you already have an OAuth consent screen configured in this project and want to apply different settings for {product-title} login, create a new GCP project. +==== +. On the OAuth consent screen page: +.. Choose the *Application type* as *Internal*. +If you select *Public*, anyone with a Google account can sign in. +.. Enter a descriptive *Application name*. +This name is shown to users on the consent screen when they sign in. +For example, use *{product-title-short}* or *<organization_name> SSO for {product-title}*. +.. Verify that the *Scopes for Google APIs* only lists *email*, *profile*, and *openid* scopes. +Only these scopes are required for single sign-on. +If you grant additional scopes it increases the risk of exposing sensitive data. diff --git a/modules/setting-resource-quota-for-extended-resources.adoc b/modules/setting-resource-quota-for-extended-resources.adoc deleted file mode 100644 index d8fbb8c54aa8..000000000000 --- a/modules/setting-resource-quota-for-extended-resources.adoc +++ /dev/null @@ -1,161 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/quotas-setting-per-project.adoc - -[id="setting-resource-quota-for-extended-resources_{context}"] -= Setting resource quota for extended resources - -Overcommitment of resources is not allowed for extended resources, so you must specify `requests` and `limits` for the same extended resource in a quota. Currently, only quota items with the prefix `requests.` is allowed for extended resources. The following is an example scenario of how to set resource quota for the GPU resource `nvidia.com/gpu`. - -.Procedure - -. Determine how many GPUs are available on a node in your cluster. For example: -+ -[source,terminal] ----- -# oc describe node ip-172-31-27-209.us-west-2.compute.internal | egrep 'Capacity|Allocatable|gpu' ----- -+ -.Example output -[source,terminal] ----- - openshift.com/gpu-accelerator=true -Capacity: - nvidia.com/gpu: 2 -Allocatable: - nvidia.com/gpu: 2 - nvidia.com/gpu 0 0 ----- -+ -In this example, 2 GPUs are available. - -. Set a quota in the namespace `nvidia`. In this example, the quota is `1`: -+ -[source,terminal] ----- -# cat gpu-quota.yaml ----- -+ -.Example output -[source,terminal] ----- -apiVersion: v1 -kind: ResourceQuota -metadata: - name: gpu-quota - namespace: nvidia -spec: - hard: - requests.nvidia.com/gpu: 1 ----- - -. Create the quota: -+ -[source,terminal] ----- -# oc create -f gpu-quota.yaml ----- -+ -.Example output -[source,terminal] ----- -resourcequota/gpu-quota created ----- - -. Verify that the namespace has the correct quota set: -+ -[source,terminal] ----- -# oc describe quota gpu-quota -n nvidia ----- -+ -.Example output -[source,terminal] ----- -Name: gpu-quota -Namespace: nvidia -Resource Used Hard --------- ---- ---- -requests.nvidia.com/gpu 0 1 ----- - -. Define a pod that asks for a single GPU. The following example definition file is called `gpu-pod.yaml`: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - generateName: gpu-pod- - namespace: nvidia -spec: - restartPolicy: OnFailure - containers: - - name: rhel7-gpu-pod - image: rhel7 - env: - - name: NVIDIA_VISIBLE_DEVICES - value: all - - name: NVIDIA_DRIVER_CAPABILITIES - value: "compute,utility" - - name: NVIDIA_REQUIRE_CUDA - value: "cuda>=5.0" - command: ["sleep"] - args: ["infinity"] - resources: - limits: - nvidia.com/gpu: 1 ----- - -. Create the pod: -+ -[source,terminal] ----- -# oc create -f gpu-pod.yaml ----- - -. Verify that the pod is running: -+ -[source,terminal] ----- -# oc get pods ----- -+ -.Example output -[source,terminal] ----- -NAME READY STATUS RESTARTS AGE -gpu-pod-s46h7 1/1 Running 0 1m ----- - -. Verify that the quota `Used` counter is correct: -+ -[source,terminal] ----- -# oc describe quota gpu-quota -n nvidia ----- -+ -.Example output -[source,terminal] ----- -Name: gpu-quota -Namespace: nvidia -Resource Used Hard --------- ---- ---- -requests.nvidia.com/gpu 1 1 ----- - -. Attempt to create a second GPU pod in the `nvidia` namespace. This is technically available on the node because it has 2 GPUs: -+ -[source,terminal] ----- -# oc create -f gpu-pod.yaml ----- -+ -.Example output -[source,terminal] ----- -Error from server (Forbidden): error when creating "gpu-pod.yaml": pods "gpu-pod-f7z2w" is forbidden: exceeded quota: gpu-quota, requested: requests.nvidia.com/gpu=1, used: requests.nvidia.com/gpu=1, limited: requests.nvidia.com/gpu=1 ----- -+ -This *Forbidden* error message is expected because you have a quota of 1 GPU and this pod tried to allocate a second GPU, which exceeds its quota. diff --git a/modules/setting-the-expiration-of-the-administration-events.adoc b/modules/setting-the-expiration-of-the-administration-events.adoc new file mode 100644 index 000000000000..4279a73587bb --- /dev/null +++ b/modules/setting-the-expiration-of-the-administration-events.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// *operating/using-the-administration-events-page.adoc + +:_mod-docs-content-type: PROCEDURE +[id="setting-the-expiration-of-the-administration-events_{context}"] += Setting the expiration of the administration events + +By specifying the number of days, you can control when the administration events expire. This is important for managing your events and ensuring that you retain the information for the desired duration. + +[NOTE] +==== +By default, administration events are retained for 4 days. The retention period for these events is determined by the time of the last occurrence and not by the time of creation. This means that an event expires and is deleted only if the time of the last occurrence exceeds the specified retention period. +==== + +.Procedure + +. In the {product-title-short} portal, go to *Platform Configuration -> System Configuration*. You can configure the following setting for administration events: + +* *Administration events retention days*: The number of days to retain your administration events. + +. To change this value, click *Edit*, make your changes, and then click *Save*. \ No newline at end of file diff --git a/modules/setting-up-cpu-manager.adoc b/modules/setting-up-cpu-manager.adoc deleted file mode 100644 index 9ee0a41c4841..000000000000 --- a/modules/setting-up-cpu-manager.adoc +++ /dev/null @@ -1,251 +0,0 @@ -// Module included in the following assemblies: -// -// * scaling_and_performance/using-cpu-manager.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="seting_up_cpu_manager_{context}"] -= Setting up CPU Manager - -.Procedure - -. Optional: Label a node: -+ -[source,terminal] ----- -# oc label node perf-node.example.com cpumanager=true ----- - -. Edit the `MachineConfigPool` of the nodes where CPU Manager should be enabled. In this example, all workers have CPU Manager enabled: -+ -[source,terminal] ----- -# oc edit machineconfigpool worker ----- - -. Add a label to the worker machine config pool: -+ -[source,yaml] ----- -metadata: - creationTimestamp: 2020-xx-xxx - generation: 3 - labels: - custom-kubelet: cpumanager-enabled ----- - -. Create a `KubeletConfig`, `cpumanager-kubeletconfig.yaml`, custom resource (CR). Refer to the label created in the previous step to have the correct nodes updated with the new kubelet config. See the `machineConfigPoolSelector` section: -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: cpumanager-enabled -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: cpumanager-enabled - kubeletConfig: - cpuManagerPolicy: static <1> - cpuManagerReconcilePeriod: 5s <2> ----- -<1> Specify a policy: -* `none`. This policy explicitly enables the existing default CPU affinity scheme, providing no affinity beyond what the scheduler does automatically. -* `static`. This policy allows pods with certain resource characteristics to be granted increased CPU affinity and exclusivity on the node. -<2> Optional. Specify the CPU Manager reconcile frequency. The default is `5s`. - -. Create the dynamic kubelet config: -+ -[source,terminal] ----- -# oc create -f cpumanager-kubeletconfig.yaml ----- -+ -This adds the CPU Manager feature to the kubelet config and, if needed, the Machine Config Operator (MCO) reboots the node. To enable CPU Manager, a reboot is not needed. - -. Check for the merged kubelet config: -+ -[source,terminal] ----- -# oc get machineconfig 99-worker-XXXXXX-XXXXX-XXXX-XXXXX-kubelet -o json | grep ownerReference -A7 ----- -+ -.Example output -[source,json] ----- - "ownerReferences": [ - { - "apiVersion": "machineconfiguration.openshift.io/v1", - "kind": "KubeletConfig", - "name": "cpumanager-enabled", - "uid": "7ed5616d-6b72-11e9-aae1-021e1ce18878" - } - ] ----- - -. Check the worker for the updated `kubelet.conf`: -+ -[source,terminal] ----- -# oc debug node/perf-node.example.com -sh-4.2# cat /host/etc/kubernetes/kubelet.conf | grep cpuManager ----- -+ -.Example output -[source,terminal] ----- -cpuManagerPolicy: static <1> -cpuManagerReconcilePeriod: 5s <1> ----- -<1> These settings were defined when you created the `KubeletConfig` CR. - -. Create a pod that requests a core or multiple cores. Both limits and requests must have their CPU value set to a whole integer. That is the number of cores that will be dedicated to this pod: -+ -[source,terminal] ----- -# cat cpumanager-pod.yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - generateName: cpumanager- -spec: - containers: - - name: cpumanager - image: gcr.io/google_containers/pause-amd64:3.0 - resources: - requests: - cpu: 1 - memory: "1G" - limits: - cpu: 1 - memory: "1G" - nodeSelector: - cpumanager: "true" ----- - -. Create the pod: -+ -[source,terminal] ----- -# oc create -f cpumanager-pod.yaml ----- - -. Verify that the pod is scheduled to the node that you labeled: -+ -[source,terminal] ----- -# oc describe pod cpumanager ----- -+ -.Example output -[source,terminal] ----- -Name: cpumanager-6cqz7 -Namespace: default -Priority: 0 -PriorityClassName: <none> -Node: perf-node.example.com/xxx.xx.xx.xxx -... - Limits: - cpu: 1 - memory: 1G - Requests: - cpu: 1 - memory: 1G -... -QoS Class: Guaranteed -Node-Selectors: cpumanager=true ----- - -. Verify that the `cgroups` are set up correctly. Get the process ID (PID) of the `pause` process: -+ -[source,terminal] ----- -# ├─init.scope -│ └─1 /usr/lib/systemd/systemd --switched-root --system --deserialize 17 -└─kubepods.slice - ├─kubepods-pod69c01f8e_6b74_11e9_ac0f_0a2b62178a22.slice - │ ├─crio-b5437308f1a574c542bdf08563b865c0345c8f8c0b0a655612c.scope - │ └─32706 /pause ----- -+ -Pods of quality of service (QoS) tier `Guaranteed` are placed within the `kubepods.slice`. Pods of other QoS tiers end up in child `cgroups` of `kubepods`: -+ -[source,terminal] ----- -# cd /sys/fs/cgroup/cpuset/kubepods.slice/kubepods-pod69c01f8e_6b74_11e9_ac0f_0a2b62178a22.slice/crio-b5437308f1ad1a7db0574c542bdf08563b865c0345c86e9585f8c0b0a655612c.scope -# for i in `ls cpuset.cpus tasks` ; do echo -n "$i "; cat $i ; done ----- -+ -.Example output -[source,terminal] ----- -cpuset.cpus 1 -tasks 32706 ----- - -. Check the allowed CPU list for the task: -+ -[source,terminal] ----- -# grep ^Cpus_allowed_list /proc/32706/status ----- -+ -.Example output -[source,terminal] ----- - Cpus_allowed_list: 1 ----- - -. Verify that another pod (in this case, the pod in the `burstable` QoS tier) on the system cannot run on the core allocated for the `Guaranteed` pod: -+ -[source,terminal] ----- -# cat /sys/fs/cgroup/cpuset/kubepods.slice/kubepods-besteffort.slice/kubepods-besteffort-podc494a073_6b77_11e9_98c0_06bba5c387ea.slice/crio-c56982f57b75a2420947f0afc6cafe7534c5734efc34157525fa9abbf99e3849.scope/cpuset.cpus -0 -# oc describe node perf-node.example.com ----- -+ -.Example output -[source, terminal] ----- -... -Capacity: - attachable-volumes-aws-ebs: 39 - cpu: 2 - ephemeral-storage: 124768236Ki - hugepages-1Gi: 0 - hugepages-2Mi: 0 - memory: 8162900Ki - pods: 250 -Allocatable: - attachable-volumes-aws-ebs: 39 - cpu: 1500m - ephemeral-storage: 124768236Ki - hugepages-1Gi: 0 - hugepages-2Mi: 0 - memory: 7548500Ki - pods: 250 -------- ---- ------------ ---------- --------------- ------------- --- - default cpumanager-6cqz7 1 (66%) 1 (66%) 1G (12%) 1G (12%) 29m - -Allocated resources: - (Total limits may be over 100 percent, i.e., overcommitted.) - Resource Requests Limits - -------- -------- ------ - cpu 1440m (96%) 1 (66%) ----- -+ -This VM has two CPU cores. The `system-reserved` setting reserves 500 millicores, meaning that half of one core is subtracted from the total capacity of the node to arrive at the `Node Allocatable` amount. You can see that `Allocatable CPU` is 1500 millicores. This means you can run one of the CPU Manager pods since each will take one whole core. A whole core is equivalent to 1000 millicores. If you try to schedule a second pod, the system will accept the pod, but it will never be scheduled: -+ -[source, terminal] ----- -NAME READY STATUS RESTARTS AGE -cpumanager-6cqz7 1/1 Running 0 33m -cpumanager-7qc2t 0/1 Pending 0 11s ----- diff --git a/modules/setting-up-environment-variables.adoc b/modules/setting-up-environment-variables.adoc new file mode 100644 index 000000000000..1fb3bd3a5162 --- /dev/null +++ b/modules/setting-up-environment-variables.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// +:_mod-docs-content-type: PROCEDURE +[id="setting-up-environment-variables_{context}"] += Prerequisites + +* You have configured the `ROX_ENDPOINT` environment variable using the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ export ROX_ENDPOINT=_<host:port>_ <1> +---- ++ +<1> The host and port information that you want to store in the `ROX_ENDPOINT` environment variable. \ No newline at end of file diff --git a/modules/setting-up-topology-manager.adoc b/modules/setting-up-topology-manager.adoc deleted file mode 100644 index a8bf9eae0fff..000000000000 --- a/modules/setting-up-topology-manager.adoc +++ /dev/null @@ -1,89 +0,0 @@ -// Module included in the following assemblies: -// -// * scaling_and_performance/using-topology-manager.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="seting_up_topology_manager_{context}"] -= Setting up Topology Manager - -To use Topology Manager, you must enable the `LatencySensitive` Feature Gate and configure the Topology Manager policy in the `cpumanager-enabled` custom resource (CR). This file might exist if you have set up CPU Manager. If the file does not exist, you can create the file. - -.Prequisites - -* Configure the CPU Manager policy to be `static`. Refer to Using CPU Manager in the Scalability and Performance section. - -.Procedure - -To activate Topololgy Manager: - -. Edit the `FeatureGate` object to add the `LatencySensitive` feature set: -+ -[source,terminal] ----- -$ oc edit featuregate/cluster ----- -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: FeatureGate -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: 2020-06-05T14:41:09Z - generation: 2 - managedFields: - - apiVersion: config.openshift.io/v1 - fieldsType: FieldsV1 - fieldsV1: - f:metadata: - f:annotations: - .: {} - f:release.openshift.io/create-only: {} - f:spec: {} - manager: cluster-version-operator - operation: Update - time: 2020-06-05T14:41:09Z - - apiVersion: config.openshift.io/v1 - fieldsType: FieldsV1 - fieldsV1: - f:spec: - f:featureSet: {} - manager: oc - operation: Update - time: 2020-06-05T15:21:44Z - name: cluster - resourceVersion: "28457" - selfLink: /apis/config.openshift.io/v1/featuregates/cluster - uid: e802e840-89ee-4137-a7e5-ca15fd2806f8 -spec: - featureSet: LatencySensitive <1> -... ----- -<1> Add the `LatencySensitive` feature set in a comma-separated list. - -. Configure the Topology Manager policy in the `cpumanager-enabled` custom resource (CR). -+ -[source,terminal] ----- -$ oc edit KubeletConfig cpumanager-enabled ----- -+ -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: KubeletConfig -metadata: - name: cpumanager-enabled -spec: - machineConfigPoolSelector: - matchLabels: - custom-kubelet: cpumanager-enabled - kubeletConfig: - cpuManagerPolicy: static <1> - cpuManagerReconcilePeriod: 5s - topologyManagerPolicy: single-numa-node <2> ----- -<1> This parameter must be `static`. -<2> Specify your selected Topology Manager policy. Here, the policy is `single-numa-node`. -Acceptable values are: `default`, `best-effort`, `restricted`, `single-numa-node`. diff --git a/modules/setting-up-vmc-for-vsphere.adoc b/modules/setting-up-vmc-for-vsphere.adoc deleted file mode 100644 index 8220c7945843..000000000000 --- a/modules/setting-up-vmc-for-vsphere.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc - -ifeval::["{context}" == "installing-vmc"] -:ipi: -endif::[] -ifeval::["{context}" == "installing-vmc-customizations"] -:ipi: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:ipi: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:restricted: -endif::[] - -[id="setting-up-vmc-for-vsphere_{context}"] -= Setting up VMC for vSphere - -You can install {product-title} on VMware Cloud (VMC) on AWS hosted vSphere clusters to enable applications to be deployed and managed both on-premise and off-premise, across the hybrid cloud. - -image::150_OpenShift_VMware_on_AWS_0321_arch.svg["VMC on AWS Architecture"] - -You must configure several options in your VMC environment prior to installing {product-title} on VMware vSphere. Ensure your VMC environment has the following prerequisites: - -* Create a non-exclusive, DHCP-enabled, NSX-T network segment and subnet. Other virtual machines (VMs) can be hosted on the subnet, but at least eight IP addresses must be available for the {product-title} deployment. - -ifdef::ipi[] -* Allocate two IP addresses, outside the DHCP range, and configure them with reverse DNS records. -** A DNS record for `api.<cluster_name>.<base_domain>` pointing to the allocated IP address. -** A DNS record for `*.apps.<cluster_name>.<base_domain>` pointing to the allocated IP address. -endif::ipi[] - -* Configure the following firewall rules: -ifndef::restricted[] -** An ANY:ANY firewall rule between the {product-title} compute network and the Internet. This is used by nodes and applications to download container images. -endif::restricted[] -** An ANY:ANY firewall rule between the installation host and the software-defined data center (SDDC) management network on port 443. This allows you to upload the {op-system-first} OVA during deployment. -** An HTTPS firewall rule between the {product-title} compute network and vCenter. This connection allows {product-title} to communicate with vCenter for provisioning and managing nodes, persistent volume claims (PVCs), and other resources. - -* You must have the following information to deploy {product-title}: -** The {product-title} cluster name, such as `vmc-prod-1`. -** The base DNS name, such as `companyname.com`. -** If not using the default, the pod network CIDR and services network CIDR must be identified, which are set by default to `10.128.0.0/14` and `172.30.0.0/16`, respectively. These CIDRs are used for pod-to-pod and pod-to-service communication and are not accessible externally; however, they must not overlap with existing subnets in your organization. -** The following vCenter information: -*** vCenter host name, username, and password -*** Datacenter name, such as `SDDC-Datacenter` -*** Cluster name, such as `Cluster-1` -*** Network name -*** Datastore name, such as `WorkloadDatastore` -+ -[NOTE] -==== -It is recommended to move your vSphere cluster to the VMC `Compute-ResourcePool` resource pool after your cluster installation is finished. -==== - -* A Linux-based host deployed to VMC as a bastion. -** The bastion host can be {op-system-base-full} or any another Linux-based host; it must have Internet connectivity and the ability to upload an OVA to the ESXi hosts. -** Download and install the OpenShift CLI tools to the bastion host. -*** The `openshift-install` installation program -*** The OpenShift CLI (`oc`) tool - -[NOTE] -==== -You cannot use the VMware NSX Container Plugin for Kubernetes (NCP), and NSX is not used as the OpenShift SDN. The version of NSX currently available with VMC is incompatible with the version of NCP certified with {product-title}. - -However, the NSX DHCP service is used for virtual machine IP management with the full-stack automated {product-title} deployment and with nodes provisioned, either manually or automatically, by the Machine API integration with vSphere. Additionally, NSX firewall rules are created to enable access with the {product-title} cluster and between the bastion host and the VMC vSphere hosts. -==== - -ifeval::["{context}" == "installing-vmc"] -:!ipi: -endif::[] -ifeval::["{context}" == "installing-vmc-customizations"] -:!ipi: -endif::[] -ifeval::["{context}" == "installing-vmc-network-customizations"] -:!ipi: -endif::[] -ifeval::["{context}" == "installing-restricted-network-vmc-user-infra"] -:!restricted: -endif::[] diff --git a/modules/sharing-security-policies.adoc b/modules/sharing-security-policies.adoc new file mode 100644 index 000000000000..4cbd041b0e1a --- /dev/null +++ b/modules/sharing-security-policies.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="sharing-security-policies_{context}"] += Sharing security policies + +[role="_abstract"] + +You can share your security policies between different Central instances in the {product-title-short} portal by exporting and importing policies. +Sharing policies helps you enforce the same standards for all your clusters. +To share policies, you export them as JSON files, and then import them back into another Central instance. + +[NOTE] +==== +Currently, you cannot export multiple security policies at the same time by using the {product-title-short} portal. +However, you can use the API for exporting multiple security policies. +In the {product-title-short} portal, go to *Help* -> *API reference* to see the API reference. +==== \ No newline at end of file diff --git a/modules/simulate-network-policies-ng20.adoc b/modules/simulate-network-policies-ng20.adoc new file mode 100644 index 000000000000..8a0c001e6721 --- /dev/null +++ b/modules/simulate-network-policies-ng20.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="simulate-network-policies-ng20_{context}"] += Simulating network policies from the network graph + +[role="_abstract"] +Your current network policies might allow unneeded network communications. You can use the network policy generator to create network policies that restrict ingress traffic to the computed baselines for a set of deployments. + +[NOTE] +==== +The Network Graph does not display the generated policies in the visualization. Generated policies are only for ingress traffic and policies that restrict egress traffic are not generated. +==== + +.Procedure +. In the {product-title-short} portal, go to *Network Graph*. +. Select a cluster, and then select one or more namespaces. +. On the network graph header, select *Network policy generator*. +. You can perform the following actions: +** Generate a YAML file with network policies to use in the simulation by clicking *Generate and simulate network policies*. For more information, see "Generating network policies in the network graph". +** Upload a YAML file of a network policy that you want to use in the simulation by performing the following steps: +.. Click *Upload YAML* and then select the file. +.. Click *Open*. The system displays a message to indicate the processing status of the uploaded policy. +. You can view active YAML files that correspond to the current network policies by clicking the *View active YAMLS* tab, and then selecting policies from the drop-down list. You can also perform the following actions: +** Click the appropriate button to copy or download the displayed YAML file. +** Use the *Actions* menu to rebuild rules from active traffic or revert rules to a previously applied YAML. For more information, see "Generating network policies in the network graph". + diff --git a/modules/slack-configuring-acs.adoc b/modules/slack-configuring-acs.adoc new file mode 100644 index 000000000000..a6b7751d6cb6 --- /dev/null +++ b/modules/slack-configuring-acs.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-slack.adoc +:_mod-docs-content-type: PROCEDURE +[id="slack-configuring-acs_{context}"] += Configuring {product-title} + +Create a new integration in {product-title} by using the webhook URL. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *Slack*. +. Click *New Integration* (*`add`* icon). +. Enter a name for *Integration Name*. +. Enter the generated webhook URL in the *Default Slack Webhook* field. +. Select *Test* to test that the integration with Slack is working. +. Select *Create* to generate the configuration. diff --git a/modules/snippets b/modules/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/modules/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/modules/snooze-cves-vm20.adoc b/modules/snooze-cves-vm20.adoc new file mode 100644 index 000000000000..b82505c69839 --- /dev/null +++ b/modules/snooze-cves-vm20.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc +:_mod-docs-content-type: PROCEDURE + +[id="snooze-cves-vm20_{context}"] += Snoozing platform and node CVEs + +[role="_abstract"] +You can snooze platform and node CVEs that do not relate to your infrastructure. You can snooze CVEs for 1 day, 1 week, 2 weeks, 1 month, or indefinitely, until you unsnooze them. Snoozing a CVE takes effect immediately and does not require an additional approval step. + +[NOTE] +==== +The ability to snooze a CVE is not enabled by default in the web portal or in the API. To enable the ability to snooze CVEs, set the runtime environment variable `ROX_VULN_MGMT_LEGACY_SNOOZE` to `true`. +==== + +.Procedure + +. In the {product-title-short} portal, do any of the following tasks: +* To view platform CVEs, click *Vulnerability Management* -> *Platform CVEs*. +* To view node CVEs, click *Vulnerability Management* -> *Node CVEs*. +. Select one or more CVEs. +. Select the appropriate method to snooze the CVE: +* If you selected a single CVE, click the overflow menu, {kebab}, and then select *Snooze CVE*. +* If you selected multiple CVEs, click *Bulk actions* -> *Snooze CVEs*. +. Select the duration of time to snooze. +. Click *Snooze CVEs*. ++ +You receive a confirmation that you have requested to snooze the CVEs. diff --git a/modules/specify-a-client-secret.adoc b/modules/specify-a-client-secret.adoc new file mode 100644 index 000000000000..606b92f9d5cf --- /dev/null +++ b/modules/specify-a-client-secret.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/configure-google-workspace-identity.adoc +:_mod-docs-content-type: CONCEPT +[id="specify-a-client-secret_{context}"] += Specifying a client secret + +{product-title} version 3.0.39 and newer supports the link:https://oauth.net/2/grant-types/authorization-code/[OAuth 2.0 Authorization Code Grant] authentication flow when you specify a client secret. +When you use this authentication flow, {product-title} uses a refresh token to keep users logged in beyond the token expiration time configured in your OIDC identity provider. + +When users log out, {product-title} deletes the refresh token from the client-side. +Additionally, if your identity provider API supports refresh token revocation, {product-title} also sends a request to your identity provider to revoke the refresh token. + +You can specify a client secret when you configure {product-title} to integrate with an OIDC identity provider. + +[NOTE] +==== +* You cannot use a *Client Secret* with the _Fragment_ *Callback mode*. +* You cannot edit configurations for existing authentication providers. +* You must create a new OIDC integration in {product-title} if you want to use a *Client Secret*. +==== + +Red{nbsp}Hat recommends using a client secret when connecting {product-title} with an OIDC identity provider. +If you do not want to use a *Client Secret*, you must select the *Do not use Client Secret (not recommended)* option. diff --git a/modules/specifying-oc-log-levels.adoc b/modules/specifying-oc-log-levels.adoc deleted file mode 100644 index dd89238809b7..000000000000 --- a/modules/specifying-oc-log-levels.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/diagnosing-oc-issues.adoc - -[id="specifying-oc-log-levels_{context}"] -= Specifying OpenShift CLI (`oc`) log levels - -You can investigate OpenShift CLI (`oc`) issues by increasing the command's log level. - -.Prerequisites - -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Specify the `oc` log level when running an `oc` command: -+ -[source,terminal] ----- -$ oc <options> --loglevel <log_level> ----- - -. The {product-title} user's current session token is typically included in logged `curl` requests where required. You can also obtain the current user's session token manually, for use when testing aspects of an `oc` command's underlying process step by step: -+ -[source,terminal] ----- -$ oc whoami -t ----- diff --git a/modules/specifying-openshift-installer-log-levels.adoc b/modules/specifying-openshift-installer-log-levels.adoc deleted file mode 100644 index 126775003d6c..000000000000 --- a/modules/specifying-openshift-installer-log-levels.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="specifying-openshift-installer-log-levels_{context}"] -= Specifying {product-title} installer log levels - -By default, the {product-title} installer log level is set to `info`. If more detailed logging is required when diagnosing a failed {product-title} installation, you can increase the `openshift-install` log level to `debug` when starting the installation again. - -.Prerequisites - -* You have access to the installation host. - -.Procedure - -* Set the installation log level to `debug` when initiating the installation: -+ -[source,terminal] ----- -$ ./openshift-install --dir=<installation_directory> wait-for bootstrap-complete --log-level=debug <1> ----- -<1> Possible log levels include `info`, `warn`, `error,` and `debug`. diff --git a/modules/specifying-the-environment-variables-in-the-securedcluster-cr.adoc b/modules/specifying-the-environment-variables-in-the-securedcluster-cr.adoc new file mode 100644 index 000000000000..bde732be20c3 --- /dev/null +++ b/modules/specifying-the-environment-variables-in-the-securedcluster-cr.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * cloud_service/installing_cloud_ocp/configuring-the-proxy-for-collector-in-rhacs-cloud-service.adoc +:_mod-docs-content-type: PROCEDURE +[id="specifying-the-environment-variables-in-the-securedcluster-cr_{context}"] += Specifying the environment variables in the SecuredCluster CR + +[role="_abstract"] +To configure an egress proxy, you can either use the cluster-wide {osp} proxy or specify the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables within the SecuredCluster Custom Resource (CR) configuration file to ensure proper use of the proxy and bypass for internal requests within the specified domain. + +The proxy configuration applies to all running services: Sensor, Collector, Admission Controller and Scanner. + + +.Procedure + +* Specify the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables under the customize specification in the SecuredCluster CR configuration file: ++ +For example: ++ +[source,yaml] +---- +# proxy collector +customize: + envVars: + - name: HTTP_PROXY + value: http://egress-proxy.stackrox.svc:xxxx <1> + - name: HTTPS_PROXY + value: http://egress-proxy.stackrox.svc:xxxx <2> + - name: NO_PROXY + value: .stackrox.svc <3> +---- +<1> The variable `HTTP_PROXY` is set to the value `\http://egress-proxy.stackrox.svc:xxxx`. This is the proxy server used for HTTP connections. +<2> The variable `HTTPS_PROXY` is set to the value `\http://egress-proxy.stackrox.svc:xxxx`. This is the proxy server used for HTTPS connections. +<3> The variable `NO _PROXY` is set to `.stackrox.svc`. This variable is used to define the hostname or IP address that should not be accessed through the proxy server. + diff --git a/modules/splunk-configuring-acs.adoc b/modules/splunk-configuring-acs.adoc new file mode 100644 index 000000000000..6f4408fa0b94 --- /dev/null +++ b/modules/splunk-configuring-acs.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-splunk.adoc +:_mod-docs-content-type: PROCEDURE +[id="splunk-configuring-acs_{context}"] += Configuring Splunk integration in {product-title} + +[role="_abstract"] +Create a new Splunk integration in {product-title} by using the token value. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *Splunk*. +. Click *New Integration* (*`add`* icon). +. Enter a name for *Integration Name*. +. Enter your Splunk URL in the *HTTP Event Collector URL* field. +You must specify the port number if it is not `443` for HTTPS or `80` for HTTP. +You must also add the URL path `/services/collector/event` at the end of the URL. +For example, `\https://<splunk-server-path>:8088/services/collector/event`. +. Enter your token in the *HTTP Event Collector Token* field. ++ +[NOTE] +==== +If you are using {product-title} version 3.0.57 or newer, you can specify custom *Source Type for Alert* events and *Source Type for Audit* events. +==== +. Select *Test* to send a test message to verify that the integration with Splunk is working. +. Select *Create* to generate the configuration. diff --git a/modules/ssh-agent-using.adoc b/modules/ssh-agent-using.adoc deleted file mode 100644 index 8e74ebd64606..000000000000 --- a/modules/ssh-agent-using.adoc +++ /dev/null @@ -1,243 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_aws/installing-aws-user-infra.adoc -// * installing/installing_aws/installing-aws-customizations.adoc -// * installing/installing_aws/installing-aws-default.adoc -// * installing/installing_aws/installing-aws-government-region.adoc -// * installing/installing_aws/installing-aws-network-customizations.adoc -// * installing/installing_aws/installing-aws-private.adoc -// * installing/installing_aws/installing-aws-vpc.adoc -// * installing/installing_azure/installing-azure-customizations.adoc -// * installing/installing_azure/installing-azure-default.adoc -// * installing/installing_azure/installing-azure-government-region.adoc -// * installing/installing_azure/installing-azure-private.adoc -// * installing/installing_azure/installing-azure-vnet.adoc -// * installing/installing_azure/installing-azure-user-infra.adoc -// * installing/installing_bare_metal/installing-bare-metal.adoc -// * installing/installing_gcp/installing-gcp-customizations.adoc -// * installing/installing_gcp/installing-gcp-private.adoc -// * installing/installing_gcp/installing-gcp-default.adoc -// * installing/installing_gcp/installing-gcp-vpc.adoc -// * installing/installing_openstack/installing-openstack-installer-custom.adoc -// * installing/installing_openstack/installing-openstack-installer-kuryr.adoc -// * installing/installing_openstack/installing-openstack-installer.adoc -// * installing/installing_aws/installing-restricted-networks-aws.adoc -// * installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc -// * installing/installing_platform_agnostic/installing-platform-agnostic.adoc -// * installing/installing_vmc/installing-restricted-networks-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere.adoc -// * installing/installing_vsphere/installing-vsphere-network-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-customizations.adoc -// * installing/installing_vsphere/installing-vsphere-installer-provisioned-network-customizations.adoc -// * installing/installing_vsphere/installing-restricted-networks-installer-provisioned-vsphere.adoc -// * installing/installing_ibm_z/installing-ibm-z.adoc -// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc -// * installing/installing_ibm_z/installing-ibm-power.adoc -// * installing/installing-rhv-restricted-network.adoc - - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-aws"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-bare-metal"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-vmc-user-infra"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-aws-user-infra"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:user-infra: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-custom"] -:osp: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:osp: -endif::[] -ifeval::["{context}" == "installing-openstack-installer"] -:osp: -endif::[] -ifeval::["{context}" == "installing-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:ibm-z-kvm: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:ibm-z: -endif::[] -ifeval::["{context}" == "installing-rhv-default"] -:rhv: -endif::[] -ifeval::["{context}" == "installing-rhv-customizations"] -:rhv: -endif::[] -ifeval::["{context}" == "installing-platform-agnostic"] -:user-infra: -endif::[] - -[id="ssh-agent-using_{context}"] -= Generating an SSH private key and adding it to the agent - -If you want to perform installation debugging or disaster recovery on your cluster, you must provide an SSH key to both your `ssh-agent` and the installation program. You can use this key to access the bootstrap machine in a public cluster to troubleshoot installation issues. -[NOTE] -==== -In a production environment, you require disaster recovery and debugging. -==== - -ifdef::ibm-z,ibm-z-kvm[] -[IMPORTANT] -==== -Do not skip this procedure in production environments where disaster recovery and debugging is required. -==== -endif::[] - -You can use this key to SSH into the master nodes as the user `core`. When you -deploy the cluster, the key is added to the `core` user's -`~/.ssh/authorized_keys` list. - -ifndef::osp,ibm-z,ibm-z-kvm,rhv[] -[NOTE] -==== -You must use a local key, not one that you configured with platform-specific -approaches such as -link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[AWS key pairs]. -==== -endif::[] - -ifdef::openshift-origin[] -[NOTE] -==== -On clusters running {op-system-first}, the SSH keys specified in the Ignition config files are written to the `/home/core/.ssh/authorized_keys.d/core` file. However, the Machine Config Operator manages SSH keys in the `/home/core/.ssh/authorized_keys` file and configures *sshd* to ignore the `/home/core/.ssh/authorized_keys.d/core` file. -As a result, newly provisioned {product-title} nodes are not accessible using SSH until the Machine Config Operator reconciles the machine configs with the `authorized_keys` file. After you can access the nodes using SSH, you can delete the `/home/core/.ssh/authorized_keys.d/core` file. -==== -endif::openshift-origin[] - -.Procedure - -. If you do not have an SSH key that is configured for password-less authentication -on your computer, create one. -For example, on a computer that uses a Linux operating system, run the -following command: -+ -[source,terminal] ----- -$ ssh-keygen -t ed25519 -N '' \ - -f <path>/<file_name> <1> ----- -<1> Specify the path and file name, such as `~/.ssh/id_rsa`, of the new SSH key. -+ -Running this command generates an SSH key that does not require a password in -the location that you specified. - -. Start the `ssh-agent` process as a background task: -+ -[source,terminal] ----- -$ eval "$(ssh-agent -s)" ----- -+ -.Example output -[source,terminal] ----- -Agent pid 31874 ----- - -. Add your SSH private key to the `ssh-agent`: -+ -[source,terminal] ----- -$ ssh-add <path>/<file_name> <1> ----- -+ -.Example output -[source,terminal] ----- -Identity added: /home/<you>/<path>/<file_name> (<computer_name>) ----- -<1> Specify the path and file name for your SSH private key, such as `~/.ssh/id_rsa` - - -.Next steps - -* When you install {product-title}, provide the SSH public key to the installation program. -ifdef::user-infra[] -If you install a cluster on infrastructure that you provision, you must provide this key to your cluster's machines. -endif::user-infra[] - -ifeval::["{context}" == "installing-restricted-networks-vsphere"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-vmc-user-infra"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-bare-metal"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-aws"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-bare-metal"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-vsphere"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-vmc-user-infra"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-aws-user-infra"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-azure-user-infra"] -:!user-infra: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-custom"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-openstack-installer-kuryr"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-openstack-installer"] -:!osp: -endif::[] -ifeval::["{context}" == "installing-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-ibm-z-kvm"] -:!ibm-z-kvm: -endif::[] -ifeval::["{context}" == "installing-rhv-default"] -:!rhv: -endif::[] -ifeval::["{context}" == "installing-restricted-networks-ibm-z"] -:!ibm-z: -endif::[] -ifeval::["{context}" == "installing-rhv-customizations"] -:!rhv: -endif::[] -ifeval::["{context}" == "installing-platform-agnostic"] -:!user-infra: -endif::[] diff --git a/modules/starting-debug-pods-with-root-access.adoc b/modules/starting-debug-pods-with-root-access.adoc deleted file mode 100644 index 0b4ea42bd6ac..000000000000 --- a/modules/starting-debug-pods-with-root-access.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/investigating-pod-issues.adoc - -[id="starting-debug-pods-with-root-access_{context}"] -= Starting debug pods with root access - -You can start a debug pod with root access, based on a problematic pod's deployment or deployment configuration. Pod users typically run with non-root privileges, but running troubleshooting pods with temporary root privileges can be useful during issue investigation. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* Your API service is still functional. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Start a debug pod with root access, based on a deployment. -.. Obtain a project's deployment name: -+ -[source,terminal] ----- -$ oc get deployment -n <project_name> ----- - -.. Start a debug pod with root privileges, based on the deployment: -+ -[source,terminal] ----- -$ oc debug deployment/my-deployment --as-root -n <project_name> ----- - -. Start a debug pod with root access, based on a deployment configuration. -.. Obtain a project's deployment configuration name: -+ -[source,terminal] ----- -$ oc get deploymentconfigs -n <project_name> ----- - -.. Start a debug pod with root privileges, based on the deployment configuration: -+ -[source,terminal] ----- -$ oc debug deploymentconfig/my-deployment-configuration --as-root -n <project_name> ----- - -[NOTE] -==== -You can append `-- <command>` to the preceding `oc debug` commands to run individual commands within a debug pod, instead of running an interactive shell. -==== diff --git a/modules/storage-azure-create-storage-class.adoc b/modules/storage-azure-create-storage-class.adoc deleted file mode 100644 index 8c5d0af89b21..000000000000 --- a/modules/storage-azure-create-storage-class.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage-azure.adoc - - - -[id="storage-create-azure-storage-class_{context}"] -= Creating the Azure storage class - -Storage classes are used to differentiate and delineate storage levels and -usages. By defining a storage class, users can obtain dynamically provisioned -persistent volumes. - -.Procedure - -. In the {product-title} console, click *Storage* -> *Storage Classes*. - -. In the storage class overview, click *Create Storage Class*. - -. Define the desired options on the page that appears. - -.. Enter a name to reference the storage class. - -.. Enter an optional description. - -.. Select the reclaim policy. - -.. Select `kubernetes.io/azure-disk` from the drop down list. - -... Enter the storage account type. This corresponds to your Azure -storage account SKU tier. Valid options are `Premium_LRS`, `Standard_LRS`, -`StandardSSD_LRS`, and `UltraSSD_LRS`. - -... Enter the kind of account. Valid options are `shared`, `dedicated,` -and `managed`. -+ -[IMPORTANT] -==== -Red Hat only supports the use of `kind: Managed` in the storage class. - -With `Shared` and `Dedicated`, Azure creates unmanaged disks, while {product-title} creates a managed disk for machine OS (root) disks. But because Azure Disk does not allow the use of both managed and unmanaged disks on a node, unmanaged disks created with `Shared` or `Dedicated` cannot be attached to {product-title} nodes. -==== - -.. Enter additional parameters for the storage class as desired. - -. Click *Create* to create the storage class. - -.Additional resources - -* https://kubernetes.io/docs/concepts/storage/storage-classes/#new-azure-disk-storage-class-starting-from-v1-7-2[Azure Disk Storage Class] diff --git a/modules/storage-create-storage-class.adoc b/modules/storage-create-storage-class.adoc deleted file mode 100644 index 0eb3396d3dd2..000000000000 --- a/modules/storage-create-storage-class.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Be sure to set the :StorageClass: and :Provisioner: value in each assembly -// on the line before the include statement for this module. For example, to -// set the StorageClass value to "AWS EBS", add the following line to the -// assembly: -// :StorageClass: AWS EBS -// Module included in the following assemblies: -// -// * storage/persistent_storage-aws.adoc - - - -[id="storage-create-{StorageClass}-storage-class_{context}"] -= Creating the {StorageClass} storage class - -Storage classes are used to differentiate and delineate storage levels and -usages. By defining a storage class, users can obtain dynamically provisioned -persistent volumes. - -.Procedure - -. In the {product-title} console, click *Storage* -> *Storage Classes*. - -. In the storage class overview, click *Create Storage Class*. - -. Define the desired options on the page that appears. - -.. Enter a name to reference the storage class. - -.. Enter an optional description. - -.. Select the reclaim policy. - -.. Select `{Provisioner}` from the drop down list. - -.. Enter additional parameters for the storage class as desired. - -. Click *Create* to create the storage class. - -// Undefine {StorageClass} attribute, so that any mistakes are easily spotted -:!StorageClass: diff --git a/modules/storage-ephemeral-storage-manage.adoc b/modules/storage-ephemeral-storage-manage.adoc deleted file mode 100644 index ff1f1c50e2dd..000000000000 --- a/modules/storage-ephemeral-storage-manage.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// Module included in the following assemblies: -// -// storage/understanding-persistent-storage.adoc[leveloffset=+1] - -[id=storage-ephemeral-storage-manage_{context}] -= Ephemeral storage management - -Cluster administrators can manage ephemeral storage within a project by setting quotas that define the limit ranges and number of requests for ephemeral storage across all pods in a non-terminal state. Developers can also set requests and limits on this compute resource at the pod and container level. diff --git a/modules/storage-ephemeral-storage-monitoring.adoc b/modules/storage-ephemeral-storage-monitoring.adoc deleted file mode 100644 index 9036740ea4ef..000000000000 --- a/modules/storage-ephemeral-storage-monitoring.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// storage/understanding-persistent-storage.adoc[leveloffset=+1] - -[id=storage-ephemeral-storage-monitoring_{context}] -= Monitoring ephemeral storage - -You can use `/bin/df` as a tool to monitor ephemeral storage usage on the volume where ephemeral container data is located, which is `/var/lib/kubelet` and `/var/lib/containers`. The available space for only `/var/lib/kubelet` is shown when you use the `df` command if `/var/lib/containers` is placed on a separate disk by the cluster administrator. - -To show the human-readable values of used and available space in `/var/lib`, enter the following command: - -[source,terminal] ----- -$ df -h /var/lib ----- - -The output shows the ephemeral storage usage in `/var/lib`: - -.Example output -[source,terminal] ----- -Filesystem Size Used Avail Use% Mounted on -/dev/sda1 69G 32G 34G 49% / ----- diff --git a/modules/storage-ephemeral-storage-overview.adoc b/modules/storage-ephemeral-storage-overview.adoc deleted file mode 100644 index c894496390dc..000000000000 --- a/modules/storage-ephemeral-storage-overview.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// storage/understanding-persistent-storage.adoc[leveloffset=+1] - -[id=storage-ephemeral-storage-overview_{context}] -= Overview - -In addition to persistent storage, pods and containers can require -ephemeral or transient local storage for their operation. The lifetime -of this ephemeral storage does not extend beyond the life of the -individual pod, and this ephemeral storage cannot be shared across -pods. - -Pods use ephemeral local storage for scratch space, caching, and logs. Issues related to -the lack of local storage accounting and isolation include the following: - -* Pods do not know how much local storage is available to them. -* Pods cannot request guaranteed local storage. -* Local storage is a best effort resource. -* Pods can be evicted due to other pods filling the local storage, -after which new pods are not admitted until sufficient storage -has been reclaimed. - -Unlike persistent volumes, ephemeral storage is unstructured and -the space is shared between all pods running on a -node, in addition to other uses by the system, the container runtime, -and {product-title}. The ephemeral storage framework allows pods to -specify their transient local storage needs. It also allows {product-title} to -schedule pods where appropriate, and to protect the node against excessive -use of local storage. - -While the ephemeral storage framework allows administrators and -developers to better manage this local storage, it does not provide -any promises related to I/O throughput and latency. diff --git a/modules/storage-ephemeral-storage-types.adoc b/modules/storage-ephemeral-storage-types.adoc deleted file mode 100644 index 1ac96ef1c6c9..000000000000 --- a/modules/storage-ephemeral-storage-types.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// storage/understanding-persistent-storage.adoc[leveloffset=+1] - -[id=storage-ephemeral-storage-types_{context}] -= Types of ephemeral storage - -Ephemeral local storage is always made available in the primary -partition. There are two basic ways of creating the primary -partition: root and runtime. - -[discrete] -== Root - -This partition holds the kubelet root directory, `/var/lib/kubelet/` by -default, and `/var/log/` directory. This partition can be shared between user -pods, the OS, and Kubernetes system daemons. This partition can be consumed by pods -through `EmptyDir` volumes, container logs, image layers, and container-writable -layers. Kubelet manages shared access and isolation of this partition. This -partition is ephemeral, and applications cannot expect any performance SLAs, -such as disk IOPS, from this partition. - -[discrete] -== Runtime - -This is an optional partition that runtimes can use for overlay -file systems. {product-title} attempts to identify and provide -shared access along with isolation to this partition. Container image -layers and writable layers are stored here. If the runtime partition -exists, the `root` partition does not hold any image layer or other writable storage. diff --git a/modules/storage-expanding-add-volume-expansion.adoc b/modules/storage-expanding-add-volume-expansion.adoc deleted file mode 100644 index c6622053e6ee..000000000000 --- a/modules/storage-expanding-add-volume-expansion.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies -// -// * storage/expanding-persistent-volumes.adoc - -[id="add-volume-expansion_{context}"] -= Enabling volume expansion support - -Before you can expand persistent volumes, the `StorageClass` object must -have the `allowVolumeExpansion` field set to `true`. - -.Procedure - -* Edit the `StorageClass` object and add the `allowVolumeExpansion` attribute. -The following example demonstrates adding this line at the bottom -of the storage class configuration. -+ -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -... -parameters: - type: gp2 -reclaimPolicy: Delete -allowVolumeExpansion: true <1> ----- -<1> Setting this attribute to `true` allows PVCs to be -expanded after creation. diff --git a/modules/storage-expanding-csi-volumes.adoc b/modules/storage-expanding-csi-volumes.adoc deleted file mode 100644 index 3251f996bd41..000000000000 --- a/modules/storage-expanding-csi-volumes.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies -// -// * storage/expanding-persistent-volumes.adoc - -[id="expanding-csi-volumes_{context}"] -= Expanding CSI volumes - -You can use the Container Storage Interface (CSI) to expand storage volumes after they have already been created. - -{product-title} supports CSI volume expansion by default. However, a specific CSI driver is required. - -{product-title} does not ship with any CSI drivers. It is recommended to use the CSI drivers provided by -link:https://kubernetes-csi.github.io/docs/drivers.html[community or storage vendors]. Follow the installation instructions provided by the CSI driver. - -{product-title} {product-version} supports version 1.1.0 of the -link:https://github.com/container-storage-interface/spec[CSI specification]. diff --git a/modules/storage-expanding-filesystem-pvc.adoc b/modules/storage-expanding-filesystem-pvc.adoc deleted file mode 100644 index 00a74280ba1a..000000000000 --- a/modules/storage-expanding-filesystem-pvc.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/expanding-persistent-volume.adoc - -[id="expanding-pvc-filesystem_{context}"] -= Expanding persistent volume claims (PVCs) with a file system - -Expanding PVCs based on volume types that need file system resizing, -such as GCE PD, EBS, and Cinder, is a two-step process. -This process involves expanding volume objects in the cloud provider, and -then expanding the file system on the actual node. - -Expanding the file system on the node only happens when a new pod is started -with the volume. - -.Prerequisites - -* The controlling `StorageClass` object must have `allowVolumeExpansion` set -to `true`. - -.Procedure - -. Edit the PVC and request a new size by editing `spec.resources.requests`. -For example, the following expands the `ebs` PVC to 8 Gi. -+ -[source,yaml] ----- -kind: PersistentVolumeClaim -apiVersion: v1 -metadata: - name: ebs -spec: - storageClass: "storageClassWithFlagSet" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 8Gi <1> ----- -<1> Updating `spec.resources.requests` to a larger amount will expand -the PVC. - -. After the cloud provider object has finished resizing, the PVC is set to -`FileSystemResizePending`. Check the condition by entering the following command: -+ -[source,terminal] ----- -$ oc describe pvc <pvc_name> ----- - -. When the cloud provider object has finished resizing, the -`PersistentVolume` object reflects the newly requested size in -`PersistentVolume.Spec.Capacity`. At this point, you can create or -recreate a new pod from the PVC to finish the file system resizing. -Once the pod is running, the newly requested size is available and the -`FileSystemResizePending` condition is removed from the PVC. diff --git a/modules/storage-expanding-flexvolume.adoc b/modules/storage-expanding-flexvolume.adoc deleted file mode 100644 index d58807ba6236..000000000000 --- a/modules/storage-expanding-flexvolume.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies -// -// * storage/expanding-persistent-volumes.adoc - -[id="expanding-flexvolume_{context}"] -= Expanding FlexVolume with a supported driver - -When using FlexVolume to connect to your back-end storage system, you can expand persistent storage volumes after they have already been created. This is done by manually updating the persistent volume claim (PVC) in {product-title}. - -FlexVolume allows expansion if the driver is set with `RequiresFSResize` to `true`. The FlexVolume can be expanded on pod restart. - -Similar to other volume types, FlexVolume volumes can also be expanded when in use by a pod. - -.Prerequisites - -* The underlying volume driver supports resize. -* The driver is set with the `RequiresFSResize` capability to `true`. -* Dynamic provisioning is used. -* The controlling `StorageClass` object has `allowVolumeExpansion` set to `true`. - -.Procedure - -* To use resizing in the FlexVolume plugin, you must implement the `ExpandableVolumePlugin` interface using these methods: - -`RequiresFSResize`:: -If `true`, updates the capacity directly. If `false`, calls the `ExpandFS` method to finish the filesystem resize. - -`ExpandFS`:: -If `true`, calls `ExpandFS` to resize filesystem after physical volume expansion is done. The volume driver can also perform physical volume resize together with filesystem resize. - -[IMPORTANT] -==== -Because {product-title} does not support installation of FlexVolume plugins on master nodes, it does not support control-plane expansion of FlexVolume. -==== diff --git a/modules/storage-expanding-recovering-failure.adoc b/modules/storage-expanding-recovering-failure.adoc deleted file mode 100644 index fb6860c411c1..000000000000 --- a/modules/storage-expanding-recovering-failure.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies -// -// * storage/expanding-persistent-volumes.adoc - -[id="expanding-recovering-from-failure_{context}"] -= Recovering from failure when expanding volumes - -If expanding underlying storage fails, the {product-title} administrator -can manually recover the persistent volume claim (PVC) state and cancel -the resize requests. Otherwise, the resize requests are continuously -retried by the controller without administrator intervention. - -.Procedure - -. Mark the persistent volume (PV) that is bound to the PVC with the -`Retain` reclaim policy. This can be done by editing the PV and changing -`persistentVolumeReclaimPolicy` to `Retain`. -. Delete the PVC. This will be recreated later. -. To ensure that the newly created PVC can bind to the PV marked `Retain`, -manually edit the PV and delete the `claimRef` entry from the PV specs. -This marks the PV as `Available`. -. Re-create the PVC in a smaller size, or a size that can be allocated by -the underlying storage provider. -. Set the `volumeName` field of the PVC to the name of the PV. This binds -the PVC to the provisioned PV only. -. Restore the reclaim policy on the PV. diff --git a/modules/storage-multi-attach-error.adoc b/modules/storage-multi-attach-error.adoc deleted file mode 100644 index 20bd289bd422..000000000000 --- a/modules/storage-multi-attach-error.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-storage-issues.adoc - -[id="storage-multi-attach-error_{context}"] -= Resolving multi-attach errors - -When a node crashes or shuts down abruptly, the attached ReadWriteOnce (RWO) volume is expected to be unmounted from the node so that it can be used by a pod scheduled on another node. - -However, mounting on a new node is not possible because the failed node is unable to unmount the attached volume. - -A multi-attach error is reported: - -[source,terminal] -.Example output --- -Unable to attach or mount volumes: unmounted volumes=[sso-mysql-pvol], unattached volumes=[sso-mysql-pvol default-token-x4rzc]: timed out waiting for the condition -Multi-Attach error for volume "pvc-8837384d-69d7-40b2-b2e6-5df86943eef9" Volume is already used by pod(s) sso-mysql-1-ns6b4 --- - -.Procedure - -To resolve the multi-attach issue, use one of the following solutions: - -* Enable multiple attachments by using RWX volumes. -+ -For most storage solutions, you can use ReadWriteMany (RWX) volumes to prevent multi-attach errors. -+ -* Recover or delete the failed node when using an RWO volume. -+ -For storage that does not support RWX, such as VMware vSphere, RWO volumes must be used instead. However, RWO volumes cannot be mounted on multiple nodes. -+ -If you encounter a multi-attach error message with an RWO volume, force delete the pod on a shutdown or crashed node to avoid data loss in critical workloads, such as when dynamic persistent volumes are attached. -+ -[source,terminal] ----- -$ oc delete pod <old_pod> --force=true --grace-period=0s ----- -+ -This command deletes the volumes stuck on shutdown or crashed nodes after six minutes. diff --git a/modules/storage-persistent-storage-aws-maximum-volumes.adoc b/modules/storage-persistent-storage-aws-maximum-volumes.adoc deleted file mode 100644 index bb00e44ab6e9..000000000000 --- a/modules/storage-persistent-storage-aws-maximum-volumes.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage-aws.adoc - -[id="maximum-number-of-ebs-volumes-on-a-node_{context}"] -= Maximum number of EBS volumes on a node - -By default, {product-title} supports a maximum of 39 EBS volumes attached to one -node. This limit is consistent with the -link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/volume_limits.html#linux-specific-volume-limits[AWS volume limits]. The volume limit depends on the instance type. - -[IMPORTANT] -==== -As a cluster administrator, you must use either in-tree or Container Storage Interface (CSI) volumes and their respective storage classes, but never both volume types at the same time. The maximum attached EBS volume number is counted separately for in-tree and CSI volumes. -==== diff --git a/modules/storage-persistent-storage-azure-file-pod.adoc b/modules/storage-persistent-storage-azure-file-pod.adoc deleted file mode 100644 index eb0ce158b15f..000000000000 --- a/modules/storage-persistent-storage-azure-file-pod.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-azure-file.adoc - -[id="create-azure-file-pod_{context}"] -= Mount the Azure File share in a pod - -After the persistent volume claim has been created, it can be used inside by an application. The following example demonstrates mounting this share inside of a pod. - -.Prerequisites - -* A persistent volume claim exists that is mapped to the underlying Azure File share. - -.Procedure - -* Create a pod that mounts the existing persistent volume claim: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: pod-name <1> -spec: - containers: - ... - volumeMounts: - - mountPath: "/data" <2> - name: azure-file-share - volumes: - - name: azure-file-share - persistentVolumeClaim: - claimName: claim1 <3> ----- -<1> The name of the pod. -<2> The path to mount the Azure File share inside the pod. -<3> The name of the `PersistentVolumeClaim` object that has been previously created. diff --git a/modules/storage-persistent-storage-azure-file.adoc b/modules/storage-persistent-storage-azure-file.adoc deleted file mode 100644 index d825421008ed..000000000000 --- a/modules/storage-persistent-storage-azure-file.adoc +++ /dev/null @@ -1,74 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-azure-file.adoc - -[id="create-azure-file-secret_{context}"] -= Create the Azure File share persistent volume claim - -To create the persistent volume claim, you must first define a `Secret` object that contains the Azure account and key. This secret is used in the `PersistentVolume` definition, and will be referenced by the persistent volume claim for use in applications. - -.Prerequisites - -* An Azure File share exists. -* The credentials to access this share, specifically the storage account and -key, are available. - -.Procedure - -. Create a `Secret` object that contains the Azure File credentials: -+ -[source,terminal] ----- -$ oc create secret generic <secret-name> --from-literal=azurestorageaccountname=<storage-account> \ <1> - --from-literal=azurestorageaccountkey=<storage-account-key> <2> ----- -<1> The Azure File storage account name. -<2> The Azure File storage account key. - -. Create a `PersistentVolume` object that references the `Secret` object you created: -+ -[source,yaml] ----- -apiVersion: "v1" -kind: "PersistentVolume" -metadata: - name: "pv0001" <1> -spec: - capacity: - storage: "5Gi" <2> - accessModes: - - "ReadWriteOnce" - storageClassName: azure-file-sc - azureFile: - secretName: <secret-name> <3> - shareName: share-1 <4> - readOnly: false ----- -<1> The name of the persistent volume. -<2> The size of this persistent volume. -<3> The name of the secret that contains the Azure File share credentials. -<4> The name of the Azure File share. - -. Create a `PersistentVolumeClaim` object that maps to the persistent volume you created: -+ -[source,yaml] ----- -apiVersion: "v1" -kind: "PersistentVolumeClaim" -metadata: - name: "claim1" <1> -spec: - accessModes: - - "ReadWriteOnce" - resources: - requests: - storage: "5Gi" <2> - storageClassName: azure-file-sc <3> - volumeName: "pv0001" <4> ----- -<1> The name of the persistent volume claim. -<2> The size of this persistent volume claim. -<3> The name of the storage class that is used to provision the persistent volume. -Specify the storage class used in the `PersistentVolume` definition. -<4> The name of the existing `PersistentVolume` object that references the -Azure File share. diff --git a/modules/storage-persistent-storage-azure-volume-format.adoc b/modules/storage-persistent-storage-azure-volume-format.adoc deleted file mode 100644 index 3cf0bbd2ac90..000000000000 --- a/modules/storage-persistent-storage-azure-volume-format.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage-azure.adoc - -[id="volume-format-azure_{context}"] -= Volume format -Before {product-title} mounts the volume and passes it to a container, it checks -that it contains a file system as specified by the `fsType` parameter in the -persistent volume definition. If the device is not formatted with the file -system, all data from the device is erased and the device is automatically -formatted with the given file system. - -This allows using unformatted Azure volumes as persistent volumes, because -{product-title} formats them before the first use. diff --git a/modules/storage-persistent-storage-block-volume-examples.adoc b/modules/storage-persistent-storage-block-volume-examples.adoc deleted file mode 100644 index 7fe0cd694694..000000000000 --- a/modules/storage-persistent-storage-block-volume-examples.adoc +++ /dev/null @@ -1,142 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/understanding-persistent-storage.adoc -// -// This module should only be present in openshift-enterprise and -// openshift-origin distributions. - -[id="block-volume-examples_{context}"] -= Block volume examples - -.PV example -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: block-pv -spec: - capacity: - storage: 10Gi - accessModes: - - ReadWriteOnce - volumeMode: Block <1> - persistentVolumeReclaimPolicy: Retain - fc: - targetWWNs: ["50060e801049cfd1"] - lun: 0 - readOnly: false ----- -<1> `volumeMode` must be set to `Block` to indicate that this PV is a raw -block volume. - -.PVC example -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: block-pvc -spec: - accessModes: - - ReadWriteOnce - volumeMode: Block <1> - resources: - requests: - storage: 10Gi ----- -<1> `volumeMode` must be set to `Block` to indicate that a raw block PVC -is requested. - -.`Pod` specification example -[source,yaml] ----- -apiVersion: v1 -kind: Pod -metadata: - name: pod-with-block-volume -spec: - containers: - - name: fc-container - image: fedora:26 - command: ["/bin/sh", "-c"] - args: [ "tail -f /dev/null" ] - volumeDevices: <1> - - name: data - devicePath: /dev/xvda <2> - volumes: - - name: data - persistentVolumeClaim: - claimName: block-pvc <3> ----- -<1> `volumeDevices`, instead of `volumeMounts`, is used for block -devices. Only `PersistentVolumeClaim` sources can be used with -raw block volumes. -<2> `devicePath`, instead of `mountPath`, represents the path to the -physical device where the raw block is mapped to the system. -<3> The volume source must be of type `persistentVolumeClaim` and must -match the name of the PVC as expected. - -.Accepted values for `volumeMode` -[cols="1,2",options="header"] -|=== - -|Value -|Default - -|Filesystem -|Yes - -|Block -|No -|=== - -.Binding scenarios for block volumes -[cols="1,2,3",options="header"] -|=== - -|PV `volumeMode` -|PVC `volumeMode` -|Binding result - -|Filesystem -|Filesystem -|Bind - -|Unspecified -|Unspecified -|Bind - -|Filesystem -|Unspecified -|Bind - -|Unspecified -|Filesystem -|Bind - -|Block -|Block -|Bind - -|Unspecified -|Block -|No Bind - -|Block -|Unspecified -|No Bind - -|Filesystem -|Block -|No Bind - -|Block -|Filesystem -|No Bind -|=== - -[IMPORTANT] -==== -Unspecified values result in the default value of `Filesystem`. -==== diff --git a/modules/storage-persistent-storage-block-volume.adoc b/modules/storage-persistent-storage-block-volume.adoc deleted file mode 100644 index 6518ea4b3406..000000000000 --- a/modules/storage-persistent-storage-block-volume.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/understanding-persistent-storage.adoc -// -// This module should only be present in openshift-enterprise and -// openshift-origin distributions. - -[id="block-volume-support_{context}"] -= Block volume support - -{product-title} can statically provision raw block volumes. These volumes -do not have a file system, and can provide performance benefits for -applications that either write to the disk directly or implement their own -storage service. - -Raw block volumes are provisioned by specifying `volumeMode: Block` in the -PV and PVC specification. - -[IMPORTANT] -==== -Pods using raw block volumes must be configured to allow privileged containers. -==== - -The following table displays which volume plug-ins support block volumes. - -.Block volume support -[cols="1,1,1,1", width="100%",options="header"] -|=== -|Volume Plug-in |Manually provisioned |Dynamically provisioned |Fully supported -|AWS EBS | ✅ | ✅ | ✅ -|Azure Disk | ✅ | ✅ | ✅ -|Azure File | | | -|Cinder | ✅ | ✅ | -|Fibre Channel | ✅ | | -|GCP | ✅ | ✅ | ✅ -|HostPath | | | -|iSCSI | ✅ | | ✅ -|Local volume | ✅ || ✅ -|NFS | | | -|Red Hat OpenShift Container Storage | ✅ | ✅ | ✅ -|VMware vSphere | ✅ | ✅ | ✅ -|=== - -[NOTE] -==== -Any of the block volumes that can be provisioned manually, but are not provided -as fully supported, are included as a Technology Preview feature only. Technology -Preview features are not supported with Red Hat production service level -agreements (SLAs) and might not be functionally complete. Red Hat does not -recommend using them in production. These features provide early access to -upcoming product features, enabling customers to test functionality and provide -feedback during the development process. For more information about the -support scope of Red Hat Technology Preview -features, see https://access.redhat.com/support/offerings/techpreview/. -==== diff --git a/modules/storage-persistent-storage-creating-volume-claim.adoc b/modules/storage-persistent-storage-creating-volume-claim.adoc deleted file mode 100644 index b38b3b5a1ce8..000000000000 --- a/modules/storage-persistent-storage-creating-volume-claim.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage-aws.adoc - -= Creating the persistent volume claim - -.Prerequisites - -Storage must exist in the underlying infrastructure before it can be mounted as -a volume in {product-title}. - -.Procedure - -. In the {product-title} console, click *Storage* -> *Persistent Volume Claims*. - -. In the persistent volume claims overview, click *Create Persistent Volume -Claim*. - -. Define the desired options on the page that appears. - -.. Select the storage class created previously from the drop-down menu. - -.. Enter a unique name for the storage claim. - -.. Select the access mode. This determines the read and write access for the -created storage claim. - -.. Define the size of the storage claim. - -. Click *Create* to create the persistent volume claim and generate a persistent -volume. diff --git a/modules/storage-persistent-storage-efs-authorization.adoc b/modules/storage-persistent-storage-efs-authorization.adoc deleted file mode 100644 index aa3713410c47..000000000000 --- a/modules/storage-persistent-storage-efs-authorization.adoc +++ /dev/null @@ -1,113 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-efs.adoc - -[id="efs-authorization_{context}"] -= Configuring authorization for EFS volumes - -The EFS provisioner must be authorized to communicate to the AWS endpoints, -along with observing and updating {product-title} storage resources. The -following instructions create the necessary permissions for the EFS -provisioner. - -.Procedure - -. Create an `efs-provisioner` service account: -+ -[source,terminal] ----- -$ oc create serviceaccount efs-provisioner ----- - -. Create a file, `clusterrole.yaml`, that defines the necessary permissions: -+ -[source,yaml] ----- -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: efs-provisioner-runner -rules: - - apiGroups: [""] - resources: ["persistentvolumes"] - verbs: ["get", "list", "watch", "create", "delete"] - - apiGroups: [""] - resources: ["persistentvolumeclaims"] - verbs: ["get", "list", "watch", "update"] - - apiGroups: ["storage.k8s.io"] - resources: ["storageclasses"] - verbs: ["get", "list", "watch"] - - apiGroups: [""] - resources: ["events"] - verbs: ["create", "update", "patch"] - - apiGroups: ["security.openshift.io"] - resources: ["securitycontextconstraints"] - verbs: ["use"] - resourceNames: ["hostmount-anyuid"] ----- - -. Create a file, `clusterrolebinding.yaml`, that defines a cluster role -binding that assigns the defined role to the service account: -+ -[source,yaml] ----- -kind: ClusterRoleBinding -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: run-efs-provisioner -subjects: - - kind: ServiceAccount - name: efs-provisioner - namespace: default <1> -roleRef: - kind: ClusterRole - name: efs-provisioner-runner - apiGroup: rbac.authorization.k8s.io ----- -<1> The namespace where the EFS provisioner Pod will run. If the EFS -provisioner is running in a namespace other than `default`, this value must -be updated. - -. Create a file, `role.yaml`, that defines a role with the necessary -permissions: -+ -[source,yaml] ----- -kind: Role -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: leader-locking-efs-provisioner -rules: - - apiGroups: [""] - resources: ["endpoints"] - verbs: ["get", "list", "watch", "create", "update", "patch"] ----- - -. Create a file, `rolebinding.yaml`, that defines a role binding that -assigns this role to the service account: -+ -[source,yaml] ----- -kind: RoleBinding -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: leader-locking-efs-provisioner -subjects: - - kind: ServiceAccount - name: efs-provisioner - namespace: default <1> -roleRef: - kind: Role - name: leader-locking-efs-provisioner - apiGroup: rbac.authorization.k8s.io ----- -<1> The namespace where the EFS provisioner Pod will run. If the EFS -provisioner is running in a namespace other than `default`, this value must -be updated. - -. Create the resources inside the {product-title} cluster: -+ -[source,terminal] ----- -$ oc create -f clusterrole.yaml,clusterrolebinding.yaml,role.yaml,rolebinding.yaml ----- diff --git a/modules/storage-persistent-storage-efs-configmap.adoc b/modules/storage-persistent-storage-efs-configmap.adoc deleted file mode 100644 index 5da835cbf53f..000000000000 --- a/modules/storage-persistent-storage-efs-configmap.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-efs.adoc - -[id="efs-creating-configmap_{context}"] -= Store the EFS variables in a config map - -It is recommended to use a config map to contain all the environment -variables that are required for the EFS provisioner. - -.Procedure - -. Define an {product-title} `ConfigMap` object that contains the environment -variables by creating a `configmap.yaml` file that contains following contents: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: efs-provisioner -data: - file.system.id: <file-system-id> <1> - aws.region: <aws-region> <2> - provisioner.name: openshift.org/aws-efs <3> - dns.name: "" <4> ----- -<1> Defines the Amazon Web Services (AWS) EFS file system ID. -<2> The AWS region of the EFS file system, such as `us-east-1`. -<3> The name of the provisioner for the associated storage class. -<4> An optional argument that specifies the new DNS name where the EFS volume -is located. If no DNS name is provided, the provisioner will search for the -EFS volume at `<file-system-id>.efs.<aws-region>.amazonaws.com`. - -. After the file has been configured, create it in your cluster -by running the following command: -+ -[source,terminal] ----- -$ oc create -f configmap.yaml -n <namespace> ----- diff --git a/modules/storage-persistent-storage-efs-provisioner.adoc b/modules/storage-persistent-storage-efs-provisioner.adoc deleted file mode 100644 index 438a17c2eb5b..000000000000 --- a/modules/storage-persistent-storage-efs-provisioner.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-efs.adoc - -[id="efs-provisioner_{context}"] -= Create the EFS provisioner - -The EFS provisioner is an {product-title} pod that mounts the EFS volume -as an NFS share. - -.Prerequisites - -* Create a config map that defines the EFS environment variables. -* Create a service account that contains the necessary cluster -and role permissions. -* Create a storage class for provisioning volumes. -* Configure the Amazon Web Services (AWS) security groups to allow incoming -NFS traffic on all {product-title} nodes. -* Configure the AWS EFS volume security groups to allow incoming -SSH traffic from all sources. - -.Procedure - -. Define the EFS provisioner by creating a `provisioner.yaml` file with the -following contents: -+ -[source,yaml] ----- -kind: Pod -apiVersion: v1 -metadata: - name: efs-provisioner -spec: - serviceAccount: efs-provisioner - containers: - - name: efs-provisioner - image: quay.io/external_storage/efs-provisioner:latest - env: - - name: PROVISIONER_NAME - valueFrom: - configMapKeyRef: - name: efs-provisioner - key: provisioner.name - - name: FILE_SYSTEM_ID - valueFrom: - configMapKeyRef: - name: efs-provisioner - key: file.system.id - - name: AWS_REGION - valueFrom: - configMapKeyRef: - name: efs-provisioner - key: aws.region - - name: DNS_NAME - valueFrom: - configMapKeyRef: - name: efs-provisioner - key: dns.name - optional: true - volumeMounts: - - name: pv-volume - mountPath: /persistentvolumes - volumes: - - name: pv-volume - nfs: - server: <file-system-id>.efs.<region>.amazonaws.com <1> - path: / <2> ----- -<1> Contains the DNS name of the EFS volume. This field must be updated -for the pod to discover the EFS volume. -<2> The mount path of the EFS volume. Each persistent volume is created -as a separate subdirectory on the EFS volume. If this EFS volume is used -for other projects outside of {product-title}, then it is recommended to -create a unique subdirectory {product-title} manually on EFS for the -cluster to prevent projects from accessing another project's data. Specifying a -directory that does not exist results in an error. - -. After the file has been configured, create it in your cluster -by running the following command: -+ -[source,terminal] ----- -$ oc create -f provisioner.yaml ----- diff --git a/modules/storage-persistent-storage-efs-pvc.adoc b/modules/storage-persistent-storage-efs-pvc.adoc deleted file mode 100644 index 60382e7462c6..000000000000 --- a/modules/storage-persistent-storage-efs-pvc.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-efs.adoc - -[id="efs-pvc_{context}"] -= Create the EFS persistent volume claim - -EFS persistent volume claims are created to allow pods -to mount the underlying EFS storage. - -.Prerequisites - -* Create the EFS provisioner pod. - -.Procedure (UI) - -. In the {product-title} console, click *Storage* -> *Persistent Volume Claims*. - -. In the persistent volume claims overview, click *Create Persistent Volume -Claim*. - -. Define the required options on the resulting page. - -.. Select the storage class that you created from the list. - -.. Enter a unique name for the storage claim. - -.. Select the access mode to determine the read and write access for the -created storage claim. - -.. Define the size of the storage claim. -+ -[NOTE] -==== -Although you must enter a size, every pod that access the EFS volume has -unlimited storage. Define a value, such as `1Mi`, that will remind you that -the storage size is unlimited. -==== - -. Click *Create* to create the persistent volume claim and generate a -persistent volume. - -.Procedure (CLI) - -. Alternately, you can define EFS persistent volume claims by creating a file, `pvc.yaml`, with the following contents: -+ -[source,yaml] ----- -kind: PersistentVolumeClaim -apiVersion: v1 -metadata: - name: efs-claim <1> - namespace: test-efs - annotations: - volume.beta.kubernetes.io/storage-provisioner: openshift.org/aws-efs - finalizers: - - kubernetes.io/pvc-protection -spec: - accessModes: - - ReadWriteOnce <2> - resources: - requests: - storage: 5Gi <3> - storageClassName: aws-efs <4> - volumeMode: Filesystem ----- -<1> A unique name for the PVC. -<2> The access mode to determine the read and write access for the created PVC. -<3> Defines the size of the PVC. -<4> Name of the storage class for the EFS provisioner. - -. After the file has been configured, create it in your cluster by running the following command: -+ -[source,terminal] ----- -$ oc create -f pvc.yaml ----- diff --git a/modules/storage-persistent-storage-efs-storage-class.adoc b/modules/storage-persistent-storage-efs-storage-class.adoc deleted file mode 100644 index 7d677bd79daf..000000000000 --- a/modules/storage-persistent-storage-efs-storage-class.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// storage/persistent_storage/persistent-storage-efs.adoc - -[id="efs-storage-class_{context}"] -= Create the EFS storage class - -Before persistent volume claims can be created, a storage class -must exist in the {product-title} cluster. The following instructions -create the storage class for the EFS provisioner. - -.Procedure - -. Define an {product-title} config map that contains the environment -variables by creating a `storageclass.yaml` with the following contents: -+ -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: aws-efs -provisioner: openshift.org/aws-efs -parameters: - gidMin: "2048" <1> - gidMax: "2147483647" <2> - gidAllocate: "true" <3> ----- -<1> An optional argument that defines the minimum group ID (GID) for volume -assignments. The default value is `2048`. -<2> An optional argument that defines the maximum GID for volume -assignments. The default value is `2147483647`. -<3> An optional argument that determines if GIDs are assigned to -volumes. If `false`, dynamically provisioned volumes are not -allocated GIDs, allowing all users to read and write to the -created volumes. The default value is `true`. - -. After the file has been configured, create it in your cluster -by running the following command: -+ -[source,terminal] ----- -$ oc create -f storageclass.yaml ----- diff --git a/modules/storage-persistent-storage-iscsi-custom-initiator.adoc b/modules/storage-persistent-storage-iscsi-custom-initiator.adoc deleted file mode 100644 index 535b0b2657bc..000000000000 --- a/modules/storage-persistent-storage-iscsi-custom-initiator.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage-iscsi.adoc - -[id="iscsi-custom-iqn_{context}"] -= iSCSI custom initiator IQN -Configure the custom initiator iSCSI Qualified Name (IQN) if the iSCSI -targets are restricted to certain IQNs, but the nodes that the iSCSI PVs -are attached to are not guaranteed to have these IQNs. - -To specify a custom initiator IQN, use `initiatorName` field. - -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: iscsi-pv -spec: - capacity: - storage: 1Gi - accessModes: - - ReadWriteOnce - iscsi: - targetPortal: 10.0.0.1:3260 - portals: ['10.0.2.16:3260', '10.0.2.17:3260', '10.0.2.18:3260'] - iqn: iqn.2016-04.test.com:storage.target00 - lun: 0 - initiatorName: iqn.2016-04.test.com:custom.iqn <1> - fsType: ext4 - readOnly: false ----- -<1> Specify the name of the initiator. diff --git a/modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc b/modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc deleted file mode 100644 index 219cb02652fb..000000000000 --- a/modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage-iscsi.adoc - -[id="enforcing-disk-quotas-iscsi_{context}"] -= Enforcing disk quotas -Use LUN partitions to enforce disk quotas and size constraints. Each LUN -is one persistent volume. Kubernetes enforces unique names for persistent -volumes. - -Enforcing quotas in this way allows the end user to request persistent -storage by a specific amount (e.g, 10Gi) and be matched with a -corresponding volume of equal or greater capacity. diff --git a/modules/storage-persistent-storage-iscsi-multipath.adoc b/modules/storage-persistent-storage-iscsi-multipath.adoc deleted file mode 100644 index a67e4dfef4e7..000000000000 --- a/modules/storage-persistent-storage-iscsi-multipath.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage-iscsi.adoc - -[id="iscsi-multipath_{context}"] -= iSCSI multipathing -For iSCSI-based storage, you can configure multiple paths by using the -same IQN for more than one target portal IP address. Multipathing ensures -access to the persistent volume when one or more of the components in a -path fail. - -To specify multi-paths in the pod specification use the `portals` field. -For example: - -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: iscsi-pv -spec: - capacity: - storage: 1Gi - accessModes: - - ReadWriteOnce - iscsi: - targetPortal: 10.0.0.1:3260 - portals: ['10.0.2.16:3260', '10.0.2.17:3260', '10.0.2.18:3260'] <1> - iqn: iqn.2016-04.test.com:storage.target00 - lun: 0 - fsType: ext4 - readOnly: false ----- -<1> Add additional target portals using the `portals` field. diff --git a/modules/storage-persistent-storage-iscsi-provisioning.adoc b/modules/storage-persistent-storage-iscsi-provisioning.adoc deleted file mode 100644 index c17a264b11d0..000000000000 --- a/modules/storage-persistent-storage-iscsi-provisioning.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies -// -// * storage/persistent_storage-iscsi.adoc - -[id="persistent-storage-iscsi-provisioning_{context}"] -= Provisioning -Verify that the storage exists in the underlying infrastructure before -mounting it as a volume in {product-title}. All that is required for the -iSCSI is the iSCSI target portal, a valid iSCSI Qualified Name (IQN), -a valid LUN number, the filesystem type, and the `PersistentVolume` API. - -.`PersistentVolume` object definition -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: iscsi-pv -spec: - capacity: - storage: 1Gi - accessModes: - - ReadWriteOnce - iscsi: - targetPortal: 10.16.154.81:3260 - iqn: iqn.2014-12.example.server:storage.target00 - lun: 0 - fsType: 'ext4' ----- diff --git a/modules/storage-persistent-storage-iscsi-volume-security.adoc b/modules/storage-persistent-storage-iscsi-volume-security.adoc deleted file mode 100644 index 74092419f5f2..000000000000 --- a/modules/storage-persistent-storage-iscsi-volume-security.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage-iscsi.adoc - -[id="volume-security-iscsi_{context}"] -= iSCSI volume security -Users request storage with a `PersistentVolumeClaim` object. This claim only -lives in the user's namespace and can only be referenced by a pod within -that same namespace. Any attempt to access a persistent volume claim across a -namespace causes the pod to fail. - -Each iSCSI LUN must be accessible by all nodes in the cluster. - -== Challenge Handshake Authentication Protocol (CHAP) configuration - -Optionally, OpenShift can use CHAP to authenticate itself to iSCSI targets: - -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: iscsi-pv -spec: - capacity: - storage: 1Gi - accessModes: - - ReadWriteOnce - iscsi: - targetPortal: 10.0.0.1:3260 - iqn: iqn.2016-04.test.com:storage.target00 - lun: 0 - fsType: ext4 - chapAuthDiscovery: true <1> - chapAuthSession: true <2> - secretRef: - name: chap-secret <3> - ----- -<1> Enable CHAP authentication of iSCSI discovery. -<2> Enable CHAP authentication of iSCSI session. -<3> Specify name of Secrets object with user name + password. This `Secret` -object must be available in all namespaces that can use the referenced volume. diff --git a/modules/storage-persistent-storage-lifecycle.adoc b/modules/storage-persistent-storage-lifecycle.adoc deleted file mode 100644 index 0ebe8d5df97a..000000000000 --- a/modules/storage-persistent-storage-lifecycle.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/understanding-persistent-storage.adoc - -[id=lifecycle-volume-claim_{context}] -= Lifecycle of a volume and claim - -PVs are resources in the cluster. PVCs are requests for those resources -and also act as claim checks to the resource. The interaction between PVs -and PVCs have the following lifecycle. - -[id="provisioning_{context}"] -== Provision storage - -In response to requests from a developer defined in a PVC, a cluster -administrator configures one or more dynamic provisioners that provision -storage and a matching PV. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -Alternatively, a cluster administrator can create a number of PVs in advance -that carry the details of the real storage that is available for use. PVs -exist in the API and are available for use. -endif::[] - -[id="binding_{context}"] -== Bind claims - -When you create a PVC, you request a specific amount of storage, specify the -required access mode, and create a storage class to describe and classify -the storage. The control loop in the master watches for new PVCs and binds -the new PVC to an appropriate PV. If an appropriate PV does not exist, a -provisioner for the storage class creates one. - -The size of all PVs might exceed your PVC size. This is especially true -with manually provisioned PVs. To minimize the excess, {product-title} -binds to the smallest PV that matches all other criteria. - -Claims remain unbound indefinitely if a matching volume does not exist or -can not be created with any available provisioner servicing a storage -class. Claims are bound as matching volumes become available. For example, -a cluster with many manually provisioned 50Gi volumes would not match a -PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the -cluster. - -[id="using-pods_{context}"] -== Use pods and claimed PVs - -Pods use claims as volumes. The cluster inspects the claim to find the bound -volume and mounts that volume for a pod. For those volumes that support -multiple access modes, you must specify which mode applies when you use -the claim as a volume in a pod. - -Once you have a claim and that claim is bound, the bound PV belongs to you -for as long as you need it. You can schedule pods and access claimed -PVs by including `persistentVolumeClaim` in the pod's volumes block. - -ifdef::openshift-origin,openshift-enterprise,openshift-webscale[] - -[id="pvcprotection_{context}"] -== Storage Object in Use Protection - -The Storage Object in Use Protection feature ensures that PVCs in active use by a pod and PVs that are bound to PVCs are not removed from the system, as this can result in data loss. - -Storage Object in Use Protection is enabled by default. - -[NOTE] -==== -A PVC is in active use by a pod when a `Pod` object exists that uses the PVC. -==== - -If a user deletes a PVC that is in active use by a pod, the PVC is not removed immediately. PVC removal is postponed until the PVC is no longer actively used by any pods. Also, if a cluster admin deletes a PV that is bound to a PVC, the PV is not removed immediately. PV removal is postponed until the PV is no longer bound to a PVC. - -endif::openshift-origin,openshift-enterprise,openshift-webscale[] - -[id="releasing_{context}"] -== Release a persistent volume - -When you are finished with a volume, you can delete the PVC object from -the API, which allows reclamation of the resource. The volume is -considered released when the claim is deleted, but it is not yet available -for another claim. The previous claimant's data remains on the volume and -must be handled according to policy. - -[id="reclaiming_{context}"] -== Reclaim policy for persistent volumes - -The reclaim policy of a persistent volume tells the cluster what to do with the volume after it is released. A volume's reclaim policy can be -`Retain`, `Recycle`, or `Delete`. - -* `Retain` reclaim policy allows manual reclamation of the resource for -those volume plug-ins that support it. - -* `Recycle` reclaim policy recycles the volume back into the pool of -unbound persistent volumes once it is released from its claim. - -[IMPORTANT] -==== -The `Recycle` reclaim policy is deprecated in {product-title} 4. Dynamic provisioning is recommended for equivalent and better -functionality. -==== - -* `Delete` reclaim policy deletes both the `PersistentVolume` object -from {product-title} and the associated storage asset in external -infrastructure, such as AWS EBS or VMware vSphere. - -[NOTE] -==== -Dynamically provisioned volumes are always deleted. -==== diff --git a/modules/storage-persistent-storage-nfs-additional-configuration.adoc b/modules/storage-persistent-storage-nfs-additional-configuration.adoc deleted file mode 100644 index aeddb37448b3..000000000000 --- a/modules/storage-persistent-storage-nfs-additional-configuration.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.adoc - -= Additional configuration and troubleshooting - -Depending on what version of NFS is being used and how it is configured, -there may be additional configuration steps needed for proper export and -security mapping. The following are some that may apply: - -[cols="1,2"] -|=== - -|NFSv4 mount incorrectly shows all files with ownership of `nobody:nobody` -a|- Could be attributed to the ID mapping settings, found in `/etc/idmapd.conf` on your NFS. -- See https://access.redhat.com/solutions/33455[this Red Hat Solution]. - -|Disabling ID mapping on NFSv4 -a|- On both the NFS client and server, run: -+ -[source,terminal] ----- -# echo 'Y' > /sys/module/nfsd/parameters/nfs4_disable_idmapping ----- -|=== diff --git a/modules/storage-persistent-storage-nfs-enforcing-disk-quota.adoc b/modules/storage-persistent-storage-nfs-enforcing-disk-quota.adoc deleted file mode 100644 index ab39560abc6c..000000000000 --- a/modules/storage-persistent-storage-nfs-enforcing-disk-quota.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.adoc - -[id="nfs-enforcing-disk-quota_{context}"] -= Enforcing disk quotas - -You can use disk partitions to enforce disk quotas and size constraints. -Each partition can be its own export. Each export is one PV. -{product-title} enforces unique names for PVs, but the uniqueness of the -NFS volume's server and path is up to the administrator. - -Enforcing quotas in this way allows the developer to request persistent -storage by a specific amount, such as 10Gi, and be matched with a -corresponding volume of equal or greater capacity. diff --git a/modules/storage-persistent-storage-nfs-export-settings.adoc b/modules/storage-persistent-storage-nfs-export-settings.adoc deleted file mode 100644 index 9ab1019c6dba..000000000000 --- a/modules/storage-persistent-storage-nfs-export-settings.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.adoc - -= Export settings - -To enable arbitrary container users to read and write the volume, -each exported volume on the NFS server should conform to the following -conditions: - -* Every export must be exported using the following format: -+ -[source,terminal] ----- -/<example_fs> *(rw,root_squash) ----- - -* The firewall must be configured to allow traffic to the mount point. -** For NFSv4, configure the default port `2049` (*nfs*). -+ -.NFSv4 -[source,terminal] ----- -# iptables -I INPUT 1 -p tcp --dport 2049 -j ACCEPT ----- - -** For NFSv3, there are three ports to configure: -`2049` (*nfs*), `20048` (*mountd*), and `111` (*portmapper*). -+ -.NFSv3 -[source,terminal] ----- -# iptables -I INPUT 1 -p tcp --dport 2049 -j ACCEPT ----- -+ -[source,terminal] ----- -# iptables -I INPUT 1 -p tcp --dport 20048 -j ACCEPT ----- -+ -[source,terminal] ----- -# iptables -I INPUT 1 -p tcp --dport 111 -j ACCEPT ----- - -* The NFS export and directory must be set up so that they are accessible -by the target pods. Either set the export to be owned by the container's -primary UID, or supply the pod group access using `supplementalGroups`, -as shown in the group IDs above. diff --git a/modules/storage-persistent-storage-nfs-group-ids.adoc b/modules/storage-persistent-storage-nfs-group-ids.adoc deleted file mode 100644 index 986006680212..000000000000 --- a/modules/storage-persistent-storage-nfs-group-ids.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.adoc -// * storage/registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc - -[id=storage-persistent-storage-nfs-group-ids_{context}] -= Group IDs - -The recommended way to handle NFS access, assuming it is not an option to -change permissions on the NFS export, is to use supplemental groups. -Supplemental groups in {product-title} are used for shared storage, of -which NFS is an example. In contrast, block storage such as -iSCSI uses the `fsGroup` SCC strategy and the `fsGroup` value in the `securityContext` of the pod. - -[NOTE] -==== -To gain access to persistent storage, it is generally preferable to use supplemental group IDs versus user IDs. -==== - -Because the group ID on the example target NFS directory -is `5555`, the Pod can define that group ID using `supplementalGroups` -under the `securityContext` definition of the pod. For example: - -[source,yaml] ----- -spec: - containers: - - name: - ... - securityContext: <1> - supplementalGroups: [5555] <2> ----- -<1> `securityContext` must be defined at the pod level, not under a -specific container. -<2> An array of GIDs defined for the pod. In this case, there is -one element in the array. Additional GIDs would be comma-separated. - -Assuming there are no custom SCCs that might satisfy the pod -requirements, the pod likely matches the `restricted` SCC. This SCC has -the `supplementalGroups` strategy set to `RunAsAny`, meaning that any -supplied group ID is accepted without range checking. - -As a result, the above pod passes admissions and is launched. However, -if group ID range checking is desired, a custom SCC is the preferred -solution. A custom SCC can be created such that minimum -and maximum group IDs are defined, group ID range checking is enforced, -and a group ID of `5555` is allowed. - -[NOTE] -==== -To use a custom SCC, you must first add it to the appropriate service -account. For example, use the `default` service account in the given project -unless another has been specified on the `Pod` specification. -==== diff --git a/modules/storage-persistent-storage-nfs-provisioning.adoc b/modules/storage-persistent-storage-nfs-provisioning.adoc deleted file mode 100644 index 9f5069844f3d..000000000000 --- a/modules/storage-persistent-storage-nfs-provisioning.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.adoc - -[id="persistent-storage-nfs-provisioning_{context}"] -= Provisioning - -Storage must exist in the underlying infrastructure before it can be -mounted as a volume in {product-title}. To provision NFS volumes, -a list of NFS servers and export paths are all that is required. - -.Procedure - -. Create an object definition for the PV: -+ -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: pv0001 <1> -spec: - capacity: - storage: 5Gi <2> - accessModes: - - ReadWriteOnce <3> - nfs: <4> - path: /tmp <5> - server: 172.17.0.2 <6> - persistentVolumeReclaimPolicy: Retain <7> ----- -<1> The name of the volume. This is the PV identity in various `oc <command> -pod` commands. -<2> The amount of storage allocated to this volume. -<3> Though this appears to be related to controlling access to the volume, -it is actually used similarly to labels and used to match a PVC to a PV. -Currently, no access rules are enforced based on the `accessModes`. -<4> The volume type being used, in this case the `nfs` plug-in. -<5> The path that is exported by the NFS server. -<6> The host name or IP address of the NFS server. -<7> The reclaim policy for the PV. This defines what happens to a volume -when released. -+ -[NOTE] -==== -Each NFS volume must be mountable by all schedulable nodes in the cluster. -==== - -. Verify that the PV was created: -+ -[source,terminal] ----- -$ oc get pv ----- -+ -.Example output -[source,terminal] ----- -NAME LABELS CAPACITY ACCESSMODES STATUS CLAIM REASON AGE -pv0001 <none> 5Gi RWO Available 31s ----- - -. Create a persistent volume claim that binds to the new PV: -+ -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: nfs-claim1 -spec: - accessModes: - - ReadWriteOnce <1> - resources: - requests: - storage: 5Gi <2> ----- -<1> As mentioned above for PVs, the `accessModes` do not enforce security, but -rather act as labels to match a PV to a PVC. -<2> This claim looks for PVs offering *5Gi* or greater capacity. - -. Verify that the persistent volume claim was created: -+ ----- -$ oc get pvc -NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE -nfs-claim1 Bound pv0001 5Gi RWO gp2 2m ----- diff --git a/modules/storage-persistent-storage-nfs-reclaiming-resources.adoc b/modules/storage-persistent-storage-nfs-reclaiming-resources.adoc deleted file mode 100644 index f113f6054054..000000000000 --- a/modules/storage-persistent-storage-nfs-reclaiming-resources.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.adoc - -[id="nfs-reclaiming-resources_{context}"] -= Reclaiming resources -NFS implements the {product-title} `Recyclable` plug-in interface. Automatic -processes handle reclamation tasks based on policies set on each persistent -volume. - -By default, PVs are set to `Retain`. - -Once claim to a PVC is deleted, and the PV is released, the PV object -should not be reused. Instead, a new PV should be created with the same -basic volume details as the original. - -For example, the administrator creates a PV named `nfs1`: - -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: nfs1 -spec: - capacity: - storage: 1Mi - accessModes: - - ReadWriteMany - nfs: - server: 192.168.1.1 - path: "/" ----- - -The user creates `PVC1`, which binds to `nfs1`. The user then deletes -`PVC1`, releasing claim to `nfs1`. This results in `nfs1` being `Released`. -If the administrator wants to make the same NFS share available, -they should create a new PV with the same NFS server details, but a -different PV name: - -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: nfs2 -spec: - capacity: - storage: 1Mi - accessModes: - - ReadWriteMany - nfs: - server: 192.168.1.1 - path: "/" ----- - -Deleting the original PV and re-creating it with the same name is -discouraged. Attempting to manually change the status of a PV -from `Released` to `Available` causes errors and potential data loss. diff --git a/modules/storage-persistent-storage-nfs-selinux.adoc b/modules/storage-persistent-storage-nfs-selinux.adoc deleted file mode 100644 index ae1b7fa03683..000000000000 --- a/modules/storage-persistent-storage-nfs-selinux.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.adoc - -[id="nfs-selinux_{context}"] -= SELinux - -{op-system-base-full} and {op-system-first} systems are configured to use SELinux on remote NFS servers by default. - -For non-{op-system-base} and non-{op-system} systems, SELinux does not allow writing from a pod to a remote NFS server. The NFS volume mounts correctly but it is read-only. You will need to enable the correct SELinux permissions by using the following procedure. - -.Prerequisites - -* The `container-selinux` package must be installed. This package provides the `virt_use_nfs` SELinux boolean. - -.Procedure - -* Enable the `virt_use_nfs` boolean using the following command. The `-P` option makes this boolean persistent across reboots. -+ -[source,terminal] ----- -# setsebool -P virt_use_nfs 1 ----- diff --git a/modules/storage-persistent-storage-nfs-user-ids.adoc b/modules/storage-persistent-storage-nfs-user-ids.adoc deleted file mode 100644 index 1a4b373ec34e..000000000000 --- a/modules/storage-persistent-storage-nfs-user-ids.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.aodc - -[id="nfs-user-id_{context}"] -= User IDs - -User IDs can be defined in the container image or in the `Pod` definition. - -[NOTE] -==== -It is generally preferable to use supplemental group IDs to gain access to -persistent storage versus using user IDs. -==== - -In the example target NFS directory shown above, the container -needs its UID set to `65534`, ignoring group IDs for the moment, so the -following can be added to the `Pod` definition: - -[source,yaml] ----- -spec: - containers: <1> - - name: - ... - securityContext: - runAsUser: 65534 <2> ----- -<1> Pods contain a `securityContext` definition specific to each container and -a pod's `securityContext` which applies to all containers defined in -the pod. -<2> `65534` is the `nfsnobody` user. - -Assuming that the project is `default` and the SCC is `restricted`, the user ID of `65534` as requested by the pod is not allowed. Therefore, the pod fails for the following reasons: - -* It requests `65534` as its user ID. -* All SCCs available to the Pod are examined to see which SCC allows a -user ID of `65534`. While all policies of the SCCs are checked, the focus -here is on user ID. -* Because all available SCCs use `MustRunAsRange` for their `runAsUser` -strategy, UID range checking is required. -* `65534` is not included in the SCC or project's user ID range. - -It is generally considered a good practice not to modify the predefined -SCCs. The preferred way to fix this situation is to create a custom SCC -A custom SCC can be created such that minimum and maximum user IDs -are defined, UID range checking is still enforced, and the UID of `65534` - is allowed. - -[NOTE] -==== -To use a custom SCC, you must first add it to the appropriate service -account. For example, use the `default` service account in the given project -unless another has been specified on the `Pod` specification. -==== diff --git a/modules/storage-persistent-storage-nfs-volume-security.adoc b/modules/storage-persistent-storage-nfs-volume-security.adoc deleted file mode 100644 index 2a3209e2918a..000000000000 --- a/modules/storage-persistent-storage-nfs-volume-security.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/persistent_storage/persistent-storage-nfs.adoc - -[id="nfs-volume-security_{context}"] -= NFS volume security - -This section covers NFS volume security, including matching permissions and -SELinux considerations. The user is expected to understand the basics of -POSIX permissions, process UIDs, supplemental groups, and SELinux. - -Developers request NFS storage by referencing either a PVC by name or the -NFS volume plug-in directly in the `volumes` section of their `Pod` -definition. - -The `/etc/exports` file on the NFS server contains the accessible NFS -directories. The target NFS directory has POSIX owner and group IDs. The -{product-title} NFS plug-in mounts the container's NFS directory with the -same POSIX ownership and permissions found on the exported NFS directory. -However, the container is not run with its effective UID equal to the -owner of the NFS mount, which is the desired behavior. - -As an example, if the target NFS directory appears on the NFS server as: - -[[nfs-export]] -[source,terminal] ----- -$ ls -lZ /opt/nfs -d ----- - -.Example output -[source,terminal] ----- -drwxrws---. nfsnobody 5555 unconfined_u:object_r:usr_t:s0 /opt/nfs ----- -[source,terminal] ----- -$ id nfsnobody ----- -.Example output -[source,terminal] ----- -uid=65534(nfsnobody) gid=65534(nfsnobody) groups=65534(nfsnobody) ----- - -Then the container must match SELinux labels, and either run with a UID of -`65534`, the `nfsnobody` owner, or with `5555` in its supplemental groups to access the directory. - -[NOTE] -==== -The owner ID of `65534` is used as an example. Even though NFS's -`root_squash` maps `root`, uid `0`, to `nfsnobody`, uid `65534`, NFS -exports can have arbitrary owner IDs. Owner `65534` is not required -for NFS exports. -==== diff --git a/modules/storage-persistent-storage-overview.adoc b/modules/storage-persistent-storage-overview.adoc deleted file mode 100644 index 27f1041b0e69..000000000000 --- a/modules/storage-persistent-storage-overview.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// storage/understanding-persistent-storage.adoc[leveloffset=+1] - -[id=persistent-storage-overview_{context}] -= Persistent storage overview - -Managing storage is a distinct problem from managing compute resources. -{product-title} uses the Kubernetes persistent volume (PV) framework to -allow cluster administrators to provision persistent storage for a cluster. -Developers can use persistent volume claims (PVCs) to request PV resources -without having specific knowledge of the underlying storage infrastructure. - -PVCs are specific to a project, and are created and used by developers as -a means to use a PV. PV resources on their own are not scoped to any -single project; they can be shared across the entire {product-title} -cluster and claimed from any project. After a PV is bound to a PVC, -that PV can not then be bound to additional PVCs. This has the effect of -scoping a bound PV to a single namespace, that of the binding project. - -PVs are defined by a `PersistentVolume` API object, which represents a -piece of existing storage in the cluster that was either statically provisioned -by the cluster administrator or dynamically provisioned using a `StorageClass` object. It is a resource in the cluster just like a -node is a cluster resource. - -PVs are volume plug-ins like `Volumes` but -have a lifecycle that is independent of any individual pod that uses the -PV. PV objects capture the details of the implementation of the storage, -be that NFS, iSCSI, or a cloud-provider-specific storage system. - -[IMPORTANT] -==== -High availability of storage in the infrastructure is left to the underlying -storage provider. -==== - -PVCs are defined by a `PersistentVolumeClaim` API object, which represents a -request for storage by a developer. It is similar to a pod in that pods -consume node resources and PVCs consume PV resources. For example, pods -can request specific levels of resources, such as CPU and memory, while -PVCs can request specific storage capacity and access modes. For example, -they can be mounted once read-write or many times read-only. diff --git a/modules/storage-persistent-storage-pv.adoc b/modules/storage-persistent-storage-pv.adoc deleted file mode 100644 index 41d32fafb74c..000000000000 --- a/modules/storage-persistent-storage-pv.adoc +++ /dev/null @@ -1,289 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/understanding-persistent-storage.adoc - -[id="persistent-volumes_{context}"] -= Persistent volumes - -Each PV contains a `spec` and `status`, which is the specification and -status of the volume, for example: - -.`PersistentVolume` object definition example -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: pv0001 <1> -spec: - capacity: - storage: 5Gi <2> - accessModes: - - ReadWriteOnce <3> - persistentVolumeReclaimPolicy: Retain <4> - ... -status: - ... ----- -<1> Name of the persistent volume. -<2> The amount of storage available to the volume. -<3> The access mode, defining the read-write and mount permissions. -<4> The reclaim policy, indicating how the resource should be handled -once it is released. - -[id="types-of-persistent-volumes_{context}"] -== Types of PVs - -{product-title} supports the following persistent volume plug-ins: - -// - GlusterFS -// - Ceph RBD -// - OpenStack Cinder -- AWS Elastic Block Store (EBS) -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-aro[] -- Azure Disk -- Azure File -endif::openshift-enterprise,openshift-webscale,openshift-origin,openshift-aro[] -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -- Cinder -- Fibre Channel -endif::openshift-enterprise,openshift-webscale,openshift-origin[] -- GCE Persistent Disk -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-aro[] -- HostPath -- iSCSI -- Local volume -- NFS -- OpenStack Manila -- Red Hat OpenShift Container Storage -endif::openshift-enterprise,openshift-webscale,openshift-origin,openshift-aro[] -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -- VMware vSphere -// - Local -endif::openshift-enterprise,openshift-webscale,openshift-origin[] - -[id="pv-capacity_{context}"] -== Capacity - -Generally, a persistent volume (PV) has a specific storage capacity. This is set by using the `capacity` attribute of the PV. - -Currently, storage capacity is the only resource that can be set or -requested. Future attributes may include IOPS, throughput, and so on. - -[id="pv-access-modes_{context}"] -== Access modes - -A persistent volume can be mounted on a host in any way supported by the -resource provider. Providers have different capabilities and each PV's -access modes are set to the specific modes supported by that particular -volume. For example, NFS can support multiple read-write clients, but a -specific NFS PV might be exported on the server as read-only. Each PV gets -its own set of access modes describing that specific PV's capabilities. - -Claims are matched to volumes with similar access modes. The only two -matching criteria are access modes and size. A claim's access modes -represent a request. Therefore, you might be granted more, but never less. -For example, if a claim requests RWO, but the only volume available is an -NFS PV (RWO+ROX+RWX), the claim would then match NFS because it supports -RWO. - -Direct matches are always attempted first. The volume's modes must match or -contain more modes than you requested. The size must be greater than or -equal to what is expected. If two types of volumes, such as NFS and iSCSI, -have the same set of access modes, either of them can match a claim with -those modes. There is no ordering between types of volumes and no way to -choose one type over another. - -All volumes with the same modes are grouped, and then sorted by size, -smallest to largest. The binder gets the group with matching modes and -iterates over each, in size order, until one size matches. - -The following table lists the access modes: - -.Access modes -[cols="1,1,3",options="header"] -|=== -|Access Mode |CLI abbreviation |Description -|ReadWriteOnce -|`RWO` -|The volume can be mounted as read-write by a single node. -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -|ReadOnlyMany -|`ROX` -|The volume can be mounted as read-only by many nodes. -|ReadWriteMany -|`RWX` -|The volume can be mounted as read-write by many nodes. -endif::[] -|=== - -[IMPORTANT] -==== -Volume access modes are descriptors of volume capabilities. They -are not enforced constraints. The storage provider is responsible for -runtime errors resulting from invalid use of the resource. - -For example, NFS offers `ReadWriteOnce` access mode. You must -mark the claims as `read-only` if you want to use the volume's -ROX capability. Errors in the provider show up at runtime as mount errors. - -iSCSI and Fibre Channel volumes do not currently have any fencing -mechanisms. You must ensure the volumes are only used by one node at a -time. In certain situations, such as draining a node, the volumes can be -used simultaneously by two nodes. Before draining the node, first ensure -the pods that use these volumes are deleted. -==== - -.Supported access modes for PVs -[cols=",^v,^v,^v", width="100%",options="header"] -|=== -|Volume plug-in |ReadWriteOnce ^[1]^ |ReadOnlyMany |ReadWriteMany -|AWS EBS ^[2]^ | ✅ | - | - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -|Azure File | ✅ | ✅ | ✅ -|Azure Disk | ✅ | - | - -//|Ceph RBD | ✅ | ✅ | - -//|CephFS | ✅ | ✅ | ✅ -|Cinder | ✅ | - | - -|Fibre Channel | ✅ | ✅ | - -|GCE Persistent Disk | ✅ | - | - -//|GlusterFS | ✅ | ✅ | ✅ -|HostPath | ✅ | - | - -|iSCSI | ✅ | ✅ | - -|Local volume | ✅ | - | - -|NFS | ✅ | ✅ | ✅ -|OpenStack Manila | - | - | ✅ -|Red Hat OpenShift Container Storage | ✅ | - | ✅ -|VMware vSphere | ✅ | - | - -endif::[] - -|=== -[.small] --- -1. ReadWriteOnce (RWO) volumes cannot be mounted on multiple nodes. If a node fails, the system does not allow the attached RWO volume to be mounted on a new node because it is already assigned to the failed node. If you encounter a multi-attach error message as a result, force delete the pod on a shutdown or crashed node to avoid data loss in critical workloads, such as when dynamic persistent volumes are attached. -2. Use a recreate deployment strategy for pods that rely on AWS EBS. -// GCE Persistent Disks, or Openstack Cinder PVs. --- - -ifdef::openshift-dedicated,openshift-online[] -[id="pv-restrictions_{context}"] -== Restrictions - -The following restrictions apply when using PVs with {product-title}: -endif::[] - -ifdef::openshift-dedicated[] - * PVs are provisioned with either EBS volumes (AWS) or GCP storage (GCP), -depending on where the cluster is provisioned. - * Only RWO access mode is applicable, as EBS volumes and GCE Persistent -Disks cannot be mounted to multiple nodes. - * *emptyDir* has the same lifecycle as the pod: - ** *emptyDir* volumes survive container crashes/restarts. - ** *emptyDir* volumes are deleted when the pod is deleted. -endif::[] - -ifdef::openshift-online[] - * PVs are provisioned with EBS volumes (AWS). - * Only RWO access mode is applicable, as EBS volumes and GCE Persistent -Disks cannot be mounted to multiple nodes. - * Docker volumes are disabled. - ** VOLUME directive without a mapped external volume fails to be -instantiated -. - * *emptyDir* is restricted to 512 Mi per project (group) per node. - ** A single pod for a project on a particular node can use up to 512 Mi -of *emptyDir* storage. - ** Multiple pods for a project on a particular node share the 512 Mi of -*emptyDir* storage. - * *emptyDir* has the same lifecycle as the pod: - ** *emptyDir* volumes survive container crashes/restarts. - ** *emptyDir* volumes are deleted when the pod is deleted. -endif::[] - -[id="pv-phase_{context}"] -== Phase - -Volumes can be found in one of the following phases: - -.Volume phases -[cols="1,2",options="header"] -|=== - -|Phase -|Description - -|Available -|A free resource not yet bound to a claim. - -|Bound -|The volume is bound to a claim. - -|Released -|The claim was deleted, but the resource is not yet reclaimed by the -cluster. - -|Failed -|The volume has failed its automatic reclamation. - -|=== - -You can view the name of the PVC bound to the PV by running: - -[source,terminal] ----- -$ oc get pv <pv-claim> ----- - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[id="pv-mount-options_{context}"] -=== Mount options - -You can specify mount options while mounting a PV by using the annotation -`volume.beta.kubernetes.io/mount-options`. - -For example: - -.Mount options example -[source,yaml] ----- -apiVersion: v1 -kind: PersistentVolume -metadata: - name: pv0001 - annotations: - volume.beta.kubernetes.io/mount-options: rw,nfsvers=4,noexec <1> -spec: - capacity: - storage: 1Gi - accessModes: - - ReadWriteOnce - nfs: - path: /tmp - server: 172.17.0.2 - persistentVolumeReclaimPolicy: Retain - claimRef: - name: claim1 - namespace: default ----- -<1> Specified mount options are used while mounting the PV to the disk. - -The following PV types support mount options: - -// - GlusterFS -// - Ceph RBD -- AWS Elastic Block Store (EBS) -- Azure Disk -- Azure File -- Cinder -- GCE Persistent Disk -- iSCSI -- Local volume -- NFS -- Red Hat OpenShift Container Storage (Ceph RBD only) -- VMware vSphere - -[NOTE] -==== -Fibre Channel and HostPath PVs do not support mount options. -==== -endif::openshift-enterprise,openshift-webscale,openshift-origin[] diff --git a/modules/storage-persistent-storage-pvc.adoc b/modules/storage-persistent-storage-pvc.adoc deleted file mode 100644 index 822eb5068c38..000000000000 --- a/modules/storage-persistent-storage-pvc.adoc +++ /dev/null @@ -1,106 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/understanding-persistent-storage.adoc - -[id="persistent-volume-claims_{context}"] -= Persistent volume claims - -Each `PersistentVolumeClaim` object contains a `spec` and `status`, which -is the specification and status of the persistent volume claim (PVC), for example: - -.`PersistentVolumeClaim` object definition example -[source,yaml] ----- -kind: PersistentVolumeClaim -apiVersion: v1 -metadata: - name: myclaim <1> -spec: - accessModes: - - ReadWriteOnce <2> - resources: - requests: - storage: 8Gi <3> - storageClassName: gold <4> -status: - ... ----- -<1> Name of the PVC -<2> The access mode, defining the read-write and mount permissions -<3> The amount of storage available to the PVC -<4> Name of the `StorageClass` required by the claim - -[id="pvc-storage-class_{context}"] -== Storage classes - -Claims can optionally request a specific storage class by specifying the -storage class's name in the `storageClassName` attribute. Only PVs of the -requested class, ones with the same `storageClassName` as the PVC, can be -bound to the PVC. The cluster administrator can configure dynamic -provisioners to service one or more storage classes. The cluster -administrator can create a PV on demand that matches the specifications -in the PVC. - - -[IMPORTANT] -==== -The Cluster Storage Operator might install a default storage class depending -on the platform in use. This storage class is owned and controlled by the -operator. It cannot be deleted or modified beyond defining annotations -and labels. If different behavior is desired, you must define a custom -storage class. -==== - -The cluster administrator can also set a default storage class for all PVCs. -When a default storage class is configured, the PVC must explicitly ask for -`StorageClass` or `storageClassName` annotations set to `""` to be bound -to a PV without a storage class. - -[NOTE] -==== -If more than one storage class is marked as default, a PVC can only be created if the `storageClassName` is explicitly specified. Therefore, only one storage class should be set as the default. -==== - -[id="pvc-access-modes_{context}"] -== Access modes - -Claims use the same conventions as volumes when requesting storage with -specific access modes. - -[id="pvc-resources_{context}"] -== Resources - -Claims, such as pods, can request specific quantities of a resource. In -this case, the request is for storage. The same resource model applies to -volumes and claims. - -[id="pvc-claims-as-volumes_{context}"] -== Claims as volumes - -Pods access storage by using the claim as a volume. Claims must exist in the -same namespace as the pod by using the claim. The cluster finds the claim -in the pod's namespace and uses it to get the `PersistentVolume` backing -the claim. The volume is mounted to the host and into the pod, for example: - -.Mount volume to the host and into the pod example -[source,yaml] ----- -kind: Pod -apiVersion: v1 -metadata: - name: mypod -spec: - containers: - - name: myfrontend - image: dockerfile/nginx - volumeMounts: - - mountPath: "/var/www/html" <1> - name: mypd <2> - volumes: - - name: mypd - persistentVolumeClaim: - claimName: myclaim <3> ----- -<1> Path to mount the volume inside the pod -<2> Name of the volume to mount -<3> Name of the PVC, that exists in the same namespace, to use diff --git a/modules/storage-persistent-storage-reclaim-manual.adoc b/modules/storage-persistent-storage-reclaim-manual.adoc deleted file mode 100644 index 3a34c3765837..000000000000 --- a/modules/storage-persistent-storage-reclaim-manual.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/understanding-persistent-storage.adoc - -[id="reclaim-manual_{context}"] -= Reclaiming a persistent volume manually - -When a persistent volume claim (PVC) is deleted, the persistent volume (PV) still exists and is considered "released". However, the PV is not yet available for another claim because the data of the previous claimant remains on the volume. - -.Procedure -To manually reclaim the PV as a cluster administrator: - -. Delete the PV. -+ -[source,terminal] ----- -$ oc delete <pv-name> ----- -+ -The associated storage asset in the external infrastructure, such as an AWS EBS, GCE PD, Azure Disk, or Cinder volume, still exists after the PV is deleted. - -. Clean up the data on the associated storage asset. - -. Delete the associated storage asset. Alternately, to reuse the same storage asset, create a new PV with the storage asset definition. - -The reclaimed PV is now available for use by another PVC. diff --git a/modules/storage-persistent-storage-reclaim.adoc b/modules/storage-persistent-storage-reclaim.adoc deleted file mode 100644 index a8d95563f3ac..000000000000 --- a/modules/storage-persistent-storage-reclaim.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * storage/understanding-persistent-storage.adoc - -[id="reclaim-policy_{context}"] -= Changing the reclaim policy of a persistent volume - -To change the reclaim policy of a persistent volume: - -. List the persistent volumes in your cluster: -+ -[source,terminal] ----- -$ oc get pv ----- -+ -.Example output -[source-terminal] ----- -NAME CAPACITY ACCESSMODES RECLAIMPOLICY STATUS CLAIM STORAGECLASS REASON AGE - pvc-b6efd8da-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim1 manual 10s - pvc-b95650f8-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim2 manual 6s - pvc-bb3ca71d-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim3 manual 3s ----- - -. Choose one of your persistent volumes and change its reclaim policy: -+ -[source,terminal] ----- -$ oc patch pv <your-pv-name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' ----- - -+ -. Verify that your chosen persistent volume has the right policy: -+ -[source,terminal] ----- -$ oc get pv ----- -+ -.Example output -[source-terminal] ----- -NAME CAPACITY ACCESSMODES RECLAIMPOLICY STATUS CLAIM STORAGECLASS REASON AGE - pvc-b6efd8da-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim1 manual 10s - pvc-b95650f8-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Delete Bound default/claim2 manual 6s - pvc-bb3ca71d-b7b5-11e6-9d58-0ed433a7dd94 4Gi RWO Retain Bound default/claim3 manual 3s ----- -+ -In the preceding output, the volume bound to claim `default/claim3` now has a `Retain` reclaim policy. The volume will not be automatically deleted when a user deletes claim `default/claim3`. diff --git a/modules/storage-persistent-storage-volume-format.adoc b/modules/storage-persistent-storage-volume-format.adoc deleted file mode 100644 index 737b2d487df4..000000000000 --- a/modules/storage-persistent-storage-volume-format.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Be sure to set the :provider: value in each assembly -// on the line before the include statement for this module. -// For example: -// :provider: AWS -// -// Module included in the following assemblies: -// -// * storage/persistent_storage-aws.adoc -// * storage/persistent_storage-gce.adoc - -[id="volume-format-{provider}_{context}"] -= Volume format -Before {product-title} mounts the volume and passes it to a container, it -checks that it contains a file system as specified by the `fsType` -parameter in the persistent volume definition. If the device is not -formatted with the file system, all data from the device is erased and the -device is automatically formatted with the given file system. - -This allows using unformatted {provider} volumes as persistent volumes, -because {product-title} formats them before the first use. - -// Undefined {provider} attribute, so that any mistakes are easily spotted -:!provider: diff --git a/modules/strategies-for-s2i-troubleshooting.adoc b/modules/strategies-for-s2i-troubleshooting.adoc deleted file mode 100644 index c98a4da41abe..000000000000 --- a/modules/strategies-for-s2i-troubleshooting.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-s2i.adoc - -[id="strategies-for-s2i-troubleshooting_{context}"] -= Strategies for Source-to-Image troubleshooting - -Use Source-to-Image (S2I) to build reproducible, Docker-formatted container images. You can create ready-to-run images by injecting application source code into a container image and assembling a new image. The new image incorporates the base image (the builder) and built source. - -To determine where in the S2I process a failure occurs, you can observe the state of the pods relating to each of the following S2I stages: - -. *During the build configuration stage*, a build pod is used to create an application container image from a base image and application source code. - -. *During the deployment configuration stage*, a deployment pod is used to deploy application pods from the application container image that was built in the build configuration stage. The deployment pod also deploys other resources such as services and routes. The deployment configuration begins after the build configuration succeeds. - -. *After the deployment pod has started the application pods*, application failures can occur within the running application pods. For instance, an application might not behave as expected even though the application pods are in a `Running` state. In this scenario, you can access running application pods to investigate application failures within a pod. - -When troubleshooting S2I issues, follow this strategy: - -. Monitor build, deployment, and application pod status -. Determine the stage of the S2I process where the problem occurred -. Review logs corresponding to the failed stage diff --git a/modules/summarizing-cluster-specifications-through-clusterversion.adoc b/modules/summarizing-cluster-specifications-through-clusterversion.adoc deleted file mode 100644 index 94f24014aead..000000000000 --- a/modules/summarizing-cluster-specifications-through-clusterversion.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * support/summarizing-cluster-specifications.adoc - -[id="summarizing-cluster-specifications-through-clusterversion_{context}"] -= Summarizing cluster specifications through `clusterversion` - -You can obtain a summary of {product-title} cluster specifications by querying the `clusterversion` resource. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Query cluster version, availability, uptime, and general status: -+ -[source,terminal] ----- -$ oc get clusterversion ----- - -. Obtain a detailed summary of cluster specifications, update availability, and update history: -+ -[source,terminal] ----- -$ oc describe clusterversion ----- diff --git a/modules/sumologic-configuring-acs.adoc b/modules/sumologic-configuring-acs.adoc new file mode 100644 index 000000000000..3a17c7e4bec1 --- /dev/null +++ b/modules/sumologic-configuring-acs.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-sumologic.adoc +:_mod-docs-content-type: PROCEDURE +[id="sumologic-configuring-acs_{context}"] += Configuring {product-title} + +Create a new integration in {product-title} by using the HTTP URL. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *Sumo Logic*. +. Click *New Integration* (`*add*` icon). +. Enter a name for *Integration Name*. +. Enter the generated HTTP URL in the *HTTP Collector Source Address* field. +. Click *Test* (`*checkmark*` icon) to test that the integration with Sumo Logic is working. +. Click *Create* (`*save*` icon) to create the configuration. diff --git a/modules/support-collecting-network-trace.adoc b/modules/support-collecting-network-trace.adoc deleted file mode 100644 index 9323309f380e..000000000000 --- a/modules/support-collecting-network-trace.adoc +++ /dev/null @@ -1,126 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="support-collecting-network-trace_{context}"] -= Collecting a network trace from an {product-title} node or container - -When investigating potential network-related {product-title} issues, Red Hat Support might request a network packet trace from a specific {product-title} cluster node or from a specific container. The recommended method to capture a network trace in {product-title} is through a debug pod. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have a Red Hat standard or premium Subscription. -* You have a Red Hat Customer Portal account. -* You have an existing Red Hat Support case ID. -* You have SSH access to your hosts. - -.Procedure - -. Obtain a list of cluster nodes: -+ -[source,terminal] ----- -$ oc get nodes ----- - -. Enter into a debug session on the target node. This step instantiates a debug pod called `<node_name>-debug`: -+ -[source,terminal] ----- -$ oc debug node/my-cluster-node ----- - -. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead. -==== -+ -. From within the `chroot` environment console, obtain the node's interface names: -+ -[source,terminal] ----- -# ip ad ----- - -. Start a `toolbox` container, which includes the required binaries and plug-ins to run `sosreport`: -+ -[source,terminal] ----- -# toolbox ----- -+ -[NOTE] -==== -If an existing `toolbox` pod is already running, the `toolbox` command outputs `'toolbox-' already exists. Trying to start...`. To avoid `tcpdump` issues, remove the running toolbox container with `podman rm toolbox-` and spawn a new toolbox container. -==== -+ -. Initiate a `tcpdump` session on the cluster node and redirect output to a capture file. This example uses `ens5` as the interface name: -+ -[source,terminal] ----- -$ tcpdump -nn -s 0 -i ens5 -w /host/var/tmp/my-cluster-node_$(date +%d_%m_%Y-%H_%M_%S-%Z).pcap <1> ----- -<1> The `tcpdump` capture file's path is outside of the `chroot` environment because the toolbox container mounts the host’s root directory at `/host`. - -. If a `tcpdump` capture is required for a specific container on the node, follow these steps. -.. Determine the target container ID. The `chroot host` command precedes the `crictl` command in this step because the toolbox container mounts the host's root directory at `/host`: -+ -[source,terminal] ----- -# chroot /host crictl ps ----- -+ -.. Determine the container's process ID. In this example, the container ID is `a7fe32346b120`: -+ -[source,terminal] ----- -# chroot /host crictl inspect --output yaml a7fe32346b120 | grep 'pid' | awk '{print $2}' ----- -+ -.. Initiate a `tcpdump` session on the container and redirect output to a capture file. This example uses `49628` as the container's process ID and `ens5` as the interface name. The `nsenter` command enters the namespace of a target process and runs a command in its namespace. because the target process in this example is a container's process ID, the `tcpdump` command is run in the container's namespace from the host: -+ -[source,terminal] ----- -# nsenter -n -t 49628 -- tcpdump -nn -i ens5 -w /host/var/tmp/my-cluster-node-my-container_$(date +%d_%m_%Y-%H_%M_%S-%Z).pcap.pcap <1> ----- -<1> The `tcpdump` capture file's path is outside of the `chroot` environment because the toolbox container mounts the host’s root directory at `/host`. - -. Provide the `tcpdump` capture file to Red Hat Support for analysis, using one of the following methods. -+ -* Upload the file to an existing Red Hat support case directly from an {product-title} cluster. -.. From within the toolbox container, run `redhat-support-tool` to attach the file directly to an existing Red Hat Support case. This example uses support case ID `01234567`: -+ -[source,terminal] ----- -# redhat-support-tool addattachment -c 01234567 /host/var/tmp/my-tcpdump-capture-file.pcap <1> ----- -<1> The toolbox container mounts the host’s root directory at `/host`. Reference the absolute path from the toolbox container's root directory, including `/host/`, when specifying files to upload through the `redhat-support-tool` command. -+ -* Upload the file to an existing Red Hat support case. -.. Concatenate the `sosreport` archive by running the `oc debug node/<node_name>` command and redirect the output to a file. This command assumes you have exited the previous `oc debug` session: -+ -[source,terminal] ----- -$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/my-tcpdump-capture-file.pcap' > /tmp/my-tcpdump-capture-file.pcap <1> ----- -<1> The debug container mounts the host’s root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Transferring a `tcpdump` capture file from a cluster node by using `scp` is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to copy a `tcpdump` capture file from a node by running `scp core@<node>.<cluster_name>.<base_domain>:<file_path> <local_path>`. -==== -+ -.. Navigate to an existing support case within link:https://access.redhat.com/support/cases/[https://access.redhat.com/support/cases/]. -+ -.. Select *Attach files* and follow the prompts to upload the file. - -// TODO - Add details relating to https://github.com/openshift/must-gather/pull/156 within the procedure. diff --git a/modules/support-gather-data.adoc b/modules/support-gather-data.adoc deleted file mode 100644 index 55b65b7f8cc8..000000000000 --- a/modules/support-gather-data.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="support_gathering_data_{context}"] -= Gathering data about your cluster for Red Hat Support - -You can gather debugging information about your cluster by using the `oc adm must-gather` CLI command. - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. -* The {product-title} CLI (`oc`) installed. - -.Procedure - -. Navigate to the directory where you want to store the `must-gather` data. - -. Run the `oc adm must-gather` command: -+ -[source,terminal] ----- -$ oc adm must-gather ----- -+ -[NOTE] -==== -If this command fails, for example if you cannot schedule a pod on your cluster, then use the `oc adm inspect` command to gather information for particular resources. Contact Red Hat Support for the recommended resources to gather. -==== -+ -[NOTE] -==== -If your cluster is using a restricted network, you must take additional steps. If your mirror registry has a trusted CA, you must first add the trusted CA to the cluster. For all clusters on restricted networks, you must import the default `must-gather` image as an image stream before you use the `oc adm must-gather` command. - -[source,terminal] ----- -$ oc import-image is/must-gather -n openshift ----- -==== - -. Create a compressed file from the `must-gather` directory that was just created in your working directory. For example, on a computer that uses a Linux -operating system, run the following command: -+ -[source,terminal] ----- -$ tar cvaf must-gather.tar.gz must-gather.local.5421342344627712289/ <1> ----- -<1> Make sure to replace `must-gather-local.5421342344627712289/` with the actual directory name. - -ifndef::openshift-origin[] -. Attach the compressed file to your support case on the link:https://access.redhat.com[Red Hat Customer Portal]. -endif::[] - -ifdef::openshift-origin[] -. Attach the compressed file to the bugreport -endif::[] diff --git a/modules/support-generating-a-sosreport-archive.adoc b/modules/support-generating-a-sosreport-archive.adoc deleted file mode 100644 index 90d4f21314e3..000000000000 --- a/modules/support-generating-a-sosreport-archive.adoc +++ /dev/null @@ -1,110 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="support-generating-a-sosreport-archive_{context}"] -= Generating a `sosreport` archive for an {product-title} cluster node - -The recommended way to generate a `sosreport` for an {product-title} {product-version} cluster node is through a debug pod. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have SSH access to your hosts. -* You have installed the OpenShift CLI (`oc`). -* You have a Red Hat standard or premium Subscription. -* You have a Red Hat Customer Portal account. -* You have an existing Red Hat Support case ID. - -.Procedure - -. Obtain a list of cluster nodes: -+ -[source,terminal] ----- -$ oc get nodes ----- - -. Enter into a debug session on the target node. This step instantiates a debug pod called `<node_name>-debug`: -+ -[source,terminal] ----- -$ oc debug node/my-cluster-node ----- - -. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead. -==== - -. Start a `toolbox` container, which includes the required binaries and plug-ins to run `sosreport`: -+ -[source,terminal] ----- -# toolbox ----- -+ -[NOTE] -==== -If an existing `toolbox` pod is already running, the `toolbox` command outputs `'toolbox-' already exists. Trying to start...`. Remove the running toolbox container with `podman rm toolbox-` and spawn a new toolbox container, to avoid issues with `sosreport` plug-ins. -==== -+ -. Collect a `sosreport` archive. -.. Run the `sosreport` command and enable the `crio.all` and `crio.logs` CRI-O container engine `sosreport` plug-ins: -+ -[source,terminal] ----- -# sosreport -k crio.all=on -k crio.logs=on <1> ----- -<1> `-k` enables you to define `sosreport` plug-in parameters outside of the defaults. -+ -.. Press *Enter* when prompted, to continue. -+ -.. Provide the Red Hat Support case ID. `sosreport` adds the ID to the archive's file name. -+ -.. The `sosreport` output provides the archive's location and checksum. The following sample output references support case ID `01234567`: -+ -[source,terminal] ----- -Your sosreport has been generated and saved in: - /host/var/tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz <1> - -The checksum is: 382ffc167510fd71b4f12a4f40b97a4e ----- -<1> The `sosreport` archive's file path is outside of the `chroot` environment because the toolbox container mounts the host’s root directory at `/host`. - -. Provide the `sosreport` archive to Red Hat Support for analysis, using one of the following methods. -+ -* Upload the file to an existing Red Hat support case directly from an {product-title} cluster. -.. From within the toolbox container, run `redhat-support-tool` to attach the archive directly to an existing Red Hat support case. This example uses support case ID `01234567`: -+ -[source,terminal] ----- -# redhat-support-tool addattachment -c 01234567 /host/var/tmp/my-sosreport.tar.xz <1> ----- -<1> The toolbox container mounts the host’s root directory at `/host`. Reference the absolute path from the toolbox container's root directory, including `/host/`, when specifying files to upload through the `redhat-support-tool` command. -+ -* Upload the file to an existing Red Hat support case. -.. Concatenate the `sosreport` archive by running the `oc debug node/<node_name>` command and redirect the output to a file. This command assumes you have exited the previous `oc debug` session: -+ -[source,terminal] ----- -$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz' > /tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz <1> ----- -<1> The debug container mounts the host’s root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Transferring a `sosreport` archive from a cluster node by using `scp` is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to copy a `sosreport` archive from a node by running `scp core@<node>.<cluster_name>.<base_domain>:<file_path> <local_path>`. -==== -+ -.. Navigate to an existing support case within link:https://access.redhat.com/support/cases/[https://access.redhat.com/support/cases/]. -+ -.. Select *Attach files* and follow the prompts to upload the file. diff --git a/modules/support-get-cluster-id.adoc b/modules/support-get-cluster-id.adoc deleted file mode 100644 index 292f7e16764d..000000000000 --- a/modules/support-get-cluster-id.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="support-get-cluster-id_{context}"] -= Obtaining your cluster ID - -When providing information to Red Hat Support, it is helpful to provide the unique identifier for your cluster. You can have your cluster ID autofilled by using the {product-title} web console. You can also manually obtain your cluster ID by using the web console or the OpenShift CLI (`oc`). - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. -* Access to the web console or the OpenShift CLI (`oc`) installed. - -.Procedure -ifdef::openshift-enterprise,openshift-webscale,openshift-dedicated[] -* To open a support case and have your cluster ID autofilled using the web console: -.. From the toolbar, navigate to *(?) Help* -> *Open Support Case*. -.. The *Cluster ID* value is autofilled. -endif::[] -ifdef::openshift-origin[] -* To open a bug and have your cluster ID autofilled using the web console: -.. From the toolbar, navigate to *(?) Help* -> *Report Bug*. -.. The *Cluster ID* value is autofilled after you click `Submit Bug`. -endif::[] - -* To manually obtain your cluster ID using the web console: -.. Navigate to *Home* -> *Dashboards* -> *Overview*. -.. The value is available in the *Cluster ID* field of the *Details* section. - -* To obtain your cluster ID using the OpenShift CLI (`oc`), run the following command: -+ -[source,terminal] ----- -$ oc get clusterversion -o jsonpath='{.items[].spec.clusterID}{"\n"}' ----- diff --git a/modules/support-installing-packages-to-a-toolbox-container.adoc b/modules/support-installing-packages-to-a-toolbox-container.adoc deleted file mode 100644 index 8efbee55a810..000000000000 --- a/modules/support-installing-packages-to-a-toolbox-container.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="installing-packages-to-a-toolbox-container_{context}"] -= Installing packages to a `toolbox` container - -By default, running the `toolbox` command starts a container with the `registry.redhat.io/rhel8/support-tools:latest` image. This image contains the most frequently used support tools. If you need to collect node-specific data that requires a support tool that is not part of the image, you can install additional packages. - -.Prerequisites - -* You have accessed a node with the `oc debug node/<node_name>` command. - -.Procedure - -. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- - -. Start the toolbox container: -+ -[source,terminal] ----- -# toolbox ----- - -. Install the additional package, such as `wget`: -+ -[source,terminal] ----- -# dnf install -y <package_name> ----- diff --git a/modules/support-knowledgebase-about.adoc b/modules/support-knowledgebase-about.adoc index 0379c2529924..2957cdbbd19d 100644 --- a/modules/support-knowledgebase-about.adoc +++ b/modules/support-knowledgebase-about.adoc @@ -1,8 +1,8 @@ // Module included in the following assemblies: // -// * support/support-redhat-knowledgebase.adoc +// * support/getting-support.adoc [id="support-knowledgebase-about_{context}"] = About the Red Hat Knowledgebase -The link:https://access.redhat.com/knowledgebase[Red Hat Knowledgebase] provides rich content aimed at helping you make the most of Red Hat's products and technologies. The Red Hat Knowledgebase consists of articles, product documentation, and videos outlining best practices on installing, configuring, and using Red Hat products. In addition, you can search for solutions to known issues, each providing concise root cause descriptions and remedial steps. +The link:https://access.redhat.com/knowledgebase[Red{nbsp}Hat Knowledgebase] provides rich content aimed at helping you make the most of Red{nbsp}Hat products and technologies. The Red{nbsp}Hat Knowledgebase consists of articles, product documentation, and videos outlining best practices on installing, configuring, and using Red{nbsp}Hat products. In addition, you can search for solutions to known issues, each providing concise root cause descriptions and remedial steps. diff --git a/modules/support-knowledgebase-search.adoc b/modules/support-knowledgebase-search.adoc index f2b54e53ffd8..acf23a6773c6 100644 --- a/modules/support-knowledgebase-search.adoc +++ b/modules/support-knowledgebase-search.adoc @@ -1,28 +1,22 @@ // Module included in the following assemblies: // -// * support/support-redhat-knowledgebase.adoc +// * support/getting-support.adoc [id="support-knowledgebase-search_{context}"] = Searching the Red Hat Knowledgebase -In the event of an {product-title} issue, you can perform an initial search to determine if a solution already exists within the Red Hat Knowledgebase. +In the event of an {product-title} issue, you can perform an initial search to determine if a solution already exists within the Red{nbsp}Hat Knowledgebase. .Prerequisites - -* You have a Red Hat Customer Portal account. +* You have a Red{nbsp}Hat Customer Portal account. .Procedure -. Log in to the link:http://access.redhat.com[Red Hat Customer Portal]. - -. In the main Red Hat Customer Portal search field, input keywords and strings relating to the problem, including: -+ -* {product-title} components (such as *etcd*) -* Related procedure (such as *installation*) -* Warnings, error messages, and other outputs related to explicit failures - +. Log in to the link:http://access.redhat.com[Red{nbsp}Hat Customer Portal]. +. In the main Red{nbsp}Hat Customer Portal search field, input keywords and strings relating to the problem, including: +** {product-title} components (such as *etcd*) +** Related procedure (such as *installation*) +** Warnings, error messages, and other outputs related to explicit failures . Click *Search*. - . Select the *{product-title}* product filter. - . Select the *Knowledgebase* content type filter. diff --git a/modules/support-providing-diagnostic-data-to-red-hat.adoc b/modules/support-providing-diagnostic-data-to-red-hat.adoc deleted file mode 100644 index 9f203cebd523..000000000000 --- a/modules/support-providing-diagnostic-data-to-red-hat.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="support-providing-diagnostic-data-to-red-hat_{context}"] -= Providing diagnostic data to Red Hat Support - -When investigating {product-title} issues, Red Hat Support might ask you to upload diagnostic data to a support case. Files can be uploaded to a support case through the Red Hat Customer Portal, or from an {product-title} cluster directly by using the `redhat-support-tool` command. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have SSH access to your hosts. -* You have installed the OpenShift CLI (`oc`). -* You have a Red Hat standard or premium Subscription. -* You have a Red Hat Customer Portal account. -* You have an existing Red Hat Support case ID. - -.Procedure - -* Upload diagnostic data to an existing Red Hat support case through the Red Hat Customer Portal. -. Concatenate a diagnostic file contained on an {product-title} node by using the `oc debug node/<node_name>` command and redirect the output to a file. The following example copies `/host/var/tmp/my-diagnostic-data.tar.gz` from a debug container to `/var/tmp/my-diagnostic-data.tar.gz`: -+ -[source,terminal] ----- -$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/my-diagnostic-data.tar.gz' > /var/tmp/my-diagnostic-data.tar.gz <1> ----- -<1> The debug container mounts the host’s root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Transferring files from a cluster node by using `scp` is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to copy diagnostic files from a node by running `scp core@<node>.<cluster_name>.<base_domain>:<file_path> <local_path>`. -==== -+ -. Navigate to an existing support case within link:https://access.redhat.com/support/cases/[https://access.redhat.com/support/cases/]. -+ -. Select *Attach files* and follow the prompts to upload the file. - -* Upload diagnostic data to an existing Red Hat support case directly from an {product-title} cluster. -. Obtain a list of cluster nodes: -+ -[source,terminal] ----- -$ oc get nodes ----- - -. Enter into a debug session on the target node. This step instantiates a debug pod called `<node_name>-debug`: -+ -[source,terminal] ----- -$ oc debug node/my-cluster-node ----- -+ -. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead. -==== -+ -. Start a `toolbox` container, which includes the required binaries to run `redhat-support-tool`: -+ -[source,terminal] ----- -# toolbox ----- -+ -[NOTE] -==== -If an existing `toolbox` pod is already running, the `toolbox` command outputs `'toolbox-' already exists. Trying to start...`. Remove the running toolbox container with `podman rm toolbox-` and spawn a new toolbox container, to avoid issues. -==== -+ -.. Run `redhat-support-tool` to attach a file from the debug pod directly to an existing Red Hat Support case. This example uses support case ID '01234567' and example file path `/host/var/tmp/my-diagnostic-data.tar.gz`: -+ -[source,terminal] ----- -# redhat-support-tool addattachment -c 01234567 /host/var/tmp/my-diagnostic-data.tar.gz <1> ----- -<1> The toolbox container mounts the host’s root directory at `/host`. Reference the absolute path from the toolbox container's root directory, including `/host/`, when specifying files to upload through the `redhat-support-tool` command. diff --git a/modules/support-starting-an-alternative-image-with-toolbox.adoc b/modules/support-starting-an-alternative-image-with-toolbox.adoc deleted file mode 100644 index e9e5f8c657d3..000000000000 --- a/modules/support-starting-an-alternative-image-with-toolbox.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * support/gathering-cluster-data.adoc - -[id="starting-an-alternative-image-with-toolbox_{context}"] -= Starting an alternative image with `toolbox` - -By default, running the `toolbox` command starts a container with the `registry.redhat.io/rhel8/support-tools:latest` image. You can start an alternative image by creating a `.toolboxrc` file and specifying the image to run. - -.Prerequisites - -* You have accessed a node with the `oc debug node/<node_name>` command. - -.Procedure - -. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- - -. Create a `.toolboxrc` file in the home directory for the root user ID: -+ -[source,terminal] ----- -# vi ~/.toolboxrc ----- -+ -[source,text] ----- -REGISTRY=quay.io <.> -IMAGE=fedora/fedora:33-x86_64 <.> -TOOLBOX_NAME=toolbox-fedora-33 <.> ----- -<.> Optional: Specify an alternative container registry. -<.> Specify an alternative image to start. -<.> Optional: Specify an alternative name for the toolbox container. - -. Start a toolbox container with the alternative image: -+ -[source,terminal] ----- -# toolbox ----- -+ -[NOTE] -==== -If an existing `toolbox` pod is already running, the `toolbox` command outputs `'toolbox-' already exists. Trying to start...`. Remove the running toolbox container with `podman rm toolbox-` and spawn a new toolbox container, to avoid issues with `sosreport` plug-ins. -==== diff --git a/modules/support-submitting-a-case.adoc b/modules/support-submitting-a-case.adoc index de36c2025ec2..8d4ad0905ad7 100644 --- a/modules/support-submitting-a-case.adoc +++ b/modules/support-submitting-a-case.adoc @@ -6,51 +6,17 @@ = Submitting a support case .Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). -* You have a Red Hat Customer Portal account. -* You have a Red Hat standard or premium Subscription. +* You have access to the cluster. +* You have a Red{nbsp}Hat Customer Portal account. +* You have a link:https://www.redhat.com/en/technologies/cloud-computing/openshift/platform-plus[Red{nbsp}Hat OpenShift Platform Plus] subscription. .Procedure - -. Log in to the link:http://access.redhat.com[Red Hat Customer Portal] and select *SUPPORT CASES* -> *Open a case*. - +. Log in to the link:http://access.redhat.com[Red{nbsp}Hat Customer Portal] and select *SUPPORT CASES* -> *Open a case*. . Select the appropriate category for your issue (such as *Defect / Bug*), product (*{product-title}*), and product version (*{product-version}*, if this is not already autofilled). - -. Review the list of suggested Red Hat Knowledgebase solutions for a potential match against the problem that is being reported. If the suggested articles do not address the issue, click *Continue*. - +. Review the list of suggested Red{nbsp}Hat Knowledgebase solutions for a potential match against the problem that is being reported. If the suggested articles do not address the issue, click *Continue*. . Enter a concise but descriptive problem summary and further details about the symptoms being experienced, as well as your expectations. - -. Review the updated list of suggested Red Hat Knowledgebase solutions for a potential match against the problem that is being reported. The list is refined as you provide more information during the case creation process. If the suggested articles do not address the issue, click *Continue*. - +. Review the updated list of suggested Red{nbsp}Hat Knowledgebase solutions for a potential match against the problem that is being reported. The list is refined as you provide more information during the case creation process. If the suggested articles do not address the issue, click *Continue*. . Ensure that the account information presented is as expected, and if not, amend accordingly. - -. Check that the autofilled {product-title} Cluster ID is correct. If it is not, manually obtain your cluster ID. -+ -* To manually obtain your cluster ID using the {product-title} web console: -.. Navigate to *Home* -> *Dashboards* -> *Overview*. -.. Find the value in the *Cluster ID* field of the *Details* section. -+ -* Alternatively, it is possible to open a new support case through the {product-title} web console and have your cluster ID autofilled. -.. From the toolbar, navigate to *(?) Help* -> *Open Support Case*. -.. The *Cluster ID* value is autofilled. -+ -* To obtain your cluster ID using the OpenShift CLI (`oc`), run the following command: -+ -[source,terminal] ----- -$ oc get clusterversion -o jsonpath='{.items[].spec.clusterID}{"\n"}' ----- - -. Complete the following questions where prompted and then click *Continue*: -+ -* Where are you experiencing the behavior? What environment? -* When does the behavior occur? Frequency? Repeatedly? At certain times? -* What information can you provide around time-frames and the business impact? - -. Upload relevant diagnostic data files and click *Continue*. It is recommended to include data gathered using the `oc adm must-gather` command as a starting point, plus any issue specific data that is not collected by that command. - +. Upload the generated diagnostic bundle and click *Continue*. . Input relevant case management details and click *Continue*. - . Preview the case details and click *Submit*. diff --git a/modules/support.adoc b/modules/support.adoc deleted file mode 100644 index a197a24d1ab9..000000000000 --- a/modules/support.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * support/getting-support.adoc -// * service_mesh/v1x/servicemesh-release-notes.adoc -// * service_mesh/v2x/servicemesh-release-notes.adoc - -[id="support_{context}"] -= Getting support - -If you experience difficulty with a procedure described in this documentation, or with {product-title} in general, visit the link:http://access.redhat.com[Red Hat Customer Portal]. From the Customer Portal, you can: - -* Search or browse through the Red Hat Knowledgebase of articles and solutions relating to Red Hat products. -* Submit a support case to Red Hat Support. -// TODO: xref -* Access other product documentation. - -To identify issues with your cluster, you can use Insights in {cloud-redhat-com}. Insights provides details about issues and, if available, information on how to solve a problem. - -// TODO: verify that these settings apply for Service Mesh and OpenShift virtualization, etc. -If you have a suggestion for improving this documentation or have found an -error, please submit a link:http://bugzilla.redhat.com[Bugzilla report] against the -*OpenShift Container Platform* product for the *Documentation* component. Please -provide specific details, such as the section name and {product-title} version. diff --git a/modules/supported-benchmark-versions.adoc b/modules/supported-benchmark-versions.adoc new file mode 100644 index 000000000000..f0f2a6090643 --- /dev/null +++ b/modules/supported-benchmark-versions.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: REFERENCE +[id="supported-benchmark-versions_{context}"] += Supported benchmark versions + +{rh-rhacs-first} supports compliance checks against the following industry standards and regulatory frameworks: + +[cols="2,2",options="header"] +|=== +|Benchmark |Supported version + +|CIS Benchmark (Center for Internet Security) for Kubernetes +|CIS Kubernetes v1.5.0 + +|HIPAA (Health Insurance Portability and Accountability Act) +|HIPAA 164 + +|NIST (National Institute of Standards and Technology) +|NIST Special Publication 800-190 and 800-53 Rev. 4 + +|PCI DSS (Payment Card Industry Data Security Standard) +|PCI DSS 3.2.1 +|=== \ No newline at end of file diff --git a/modules/supported-platforms-for-openshift-clusters.adoc b/modules/supported-platforms-for-openshift-clusters.adoc deleted file mode 100644 index 45ab38579583..000000000000 --- a/modules/supported-platforms-for-openshift-clusters.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture-installation.adoc -// * installing/index.adoc - -[id="supported-platforms-for-openshift-clusters_{context}"] -= Supported platforms for OpenShift clusters - -In {product-title} {product-version}, you can install a cluster that uses installer-provisioned infrastructure on the following platforms: - -* Amazon Web Services (AWS) -* Google Cloud Platform (GCP) -* Microsoft Azure -* {rh-openstack-first} version 13 and 16 -** The latest {product-title} release supports both the latest {rh-openstack} long-life release and intermediate release. For complete {rh-openstack} release compatibility, see the link:https://access.redhat.com/articles/4679401[{product-title} on {rh-openstack} support matrix]. -* {rh-virtualization-first} -* VMware vSphere -* VMware Cloud (VMC) on AWS - -For these clusters, all machines, including the computer that you run the installation process on, must have direct internet access to pull images for platform containers and provide telemetry data to Red Hat. - -[IMPORTANT] -==== -After installation, the following changes are not supported: - -* Mixing cloud provider platforms -* Mixing cloud provider components, such as using a persistent storage framework from a differing platform than what the cluster is installed on -==== - -In {product-title} {product-version}, you can install a cluster that uses user-provisioned infrastructure on the following platforms: - -* AWS -* Azure -* GCP -* {rh-openstack} -* {rh-virtualization} -* VMware vSphere -* VMware Cloud on AWS -* Bare metal -* IBM Z or LinuxONE -* IBM Power Systems - -With installations on user-provisioned infrastructure, each machine can have full internet access, you can place your cluster behind a proxy, or you can perform a _restricted network installation_. In a restricted network installation, you can download the images that are required to install a cluster, place them in a mirror registry, and use that data to install your cluster. While you require internet access to pull images for platform containers, with a restricted network installation on vSphere or bare metal infrastructure, your cluster machines do not require direct internet access. - -The link:https://access.redhat.com/articles/4128421[OpenShift Container Platform 4.x Tested Integrations] page contains details about integration testing for different platforms. diff --git a/modules/syntactic-difference-output.adoc b/modules/syntactic-difference-output.adoc new file mode 100644 index 000000000000..643e179dc83f --- /dev/null +++ b/modules/syntactic-difference-output.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: PROCEDURE +[id="syntactic-difference-output_{context}"] += Syntactic difference output + +.Procedure + +* Run the following command to compare the contents of the `netpols.yaml` files in the two specified directories: ++ +---- +$ diff netpol-diff-example-minimal/netpols.yaml netpol-analysis-example-minimal/netpols.yaml +---- ++ +.Example output ++ +[source,text,subs="+quotes"] +---- +12c12 +< - ports: +--- +> ports: +---- \ No newline at end of file diff --git a/modules/syslog-configuring-acs.adoc b/modules/syslog-configuring-acs.adoc new file mode 100644 index 000000000000..3dbfe45fe71b --- /dev/null +++ b/modules/syslog-configuring-acs.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-syslog-protocol.adoc +:_mod-docs-content-type: PROCEDURE +[id="syslog-configuring-acs_{context}"] += Configuring syslog integration with {product-title} + +Create a new syslog integration in {rh-rhacs-first}. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *Syslog*. +. Click *New Integration* (add icon). +. Enter a name for *Integration Name*. +. Select the *Logging Facility* value from `local0` through `local7`. +. Enter your *Receiver Host* address and *Receiver Port* number. +. If you are using TLS, turn on the *Use TLS* toggle. +. If your syslog receiver uses a certificate that is not trusted, turn on the *Disable TLS Certificate Validation (Insecure)* toggle. +Otherwise, leave this toggle off. +. Click *Add new extra field* to add extra fields. For example, if your syslog receiver accepts objects from multiple sources, type `source` and `rhacs` in the *Key* and *Value* fields. ++ +You can filter using the custom values in your syslog receiver to identify all alerts from {product-title-short}. +. Select *Test* (`checkmark` icon) to send a test message to verify that the integration with your generic webhook is working. +. Select *Create* (`save` icon) to create the configuration. \ No newline at end of file diff --git a/modules/system-health-dashboard-page-overview.adoc b/modules/system-health-dashboard-page-overview.adoc new file mode 100644 index 000000000000..033796a0cf3a --- /dev/null +++ b/modules/system-health-dashboard-page-overview.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/use-system-health-dashboard.adoc + +:_mod-docs-content-type: REFERENCE +[id="system-health-dashboard-page-overview_{context}"] += System health dashboard page overview + +The *System Health* dashboard page organizes information into the following groups: + +Cluster status:: Indicates the overall status of the cluster, and the status of essential {rh-rhacs-first} components such as Sensor, Collector and Admission Controller. +Sensor upgrade:: Indicates the status of any pending or in-progress upgrades for Sensor. +Credential expiration:: Indicates the expiration date of the critical credentials. +StackRox Scanner Vulnerability Definitions:: Indicates the status of the vulnerability definitions database that StackRox Scanner uses. +Scanner V4 Vulnerabilities:: Indicates the status of the vulnerability definitions database that Scanner V4 uses. +Image Integrations:: Indicates the status of integrated image registries and scanners. +Notifier Integrations:: Indicates the status of any notifiers that you have integrated. +Backup Integrations:: Indicates the status of any backup providers that you have integrated. +Declarative configuration:: Indicates the status and consistency of the declarative configurations. +Central certificate:: Indicates the expiration date of the Central certificate. +StackRox Scanner certificate:: Indicates the expiration date of the StackRox Scanner certificate. +Scanner V4 certificate:: Indicates the expiration date of the Scanner V4 certificate. \ No newline at end of file diff --git a/modules/technology-preview.adoc b/modules/technology-preview.adoc deleted file mode 100644 index d9da088146db..000000000000 --- a/modules/technology-preview.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// When including this file, ensure that {FeatureName} is set immediately before -// the include. Otherwise it will result in an incorrect replacement. - -[IMPORTANT] -==== -{FeatureName} is a Technology Preview feature only. Technology Preview features -are not supported with Red Hat production service level agreements (SLAs) and -might not be functionally complete. Red Hat does not recommend using them -in production. These features provide early access to upcoming product -features, enabling customers to test functionality and provide feedback during -the development process. - -For more information about the support scope of Red Hat Technology Preview -features, see https://access.redhat.com/support/offerings/techpreview/. -==== -// Undefine {FeatureName} attribute, so that any mistakes are easily spotted -:!FeatureName: diff --git a/modules/telemetry-about-telemetry.adoc b/modules/telemetry-about-telemetry.adoc deleted file mode 100644 index 71228ca02ea2..000000000000 --- a/modules/telemetry-about-telemetry.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc -// * support/remote_health_monitoring/about-remote-health-monitoring.adoc - -[id="telemetry-about-telemetry_{context}"] -= About Telemetry - -Telemetry sends a carefully chosen subset of the cluster monitoring metrics to Red Hat. The Telemeter Client fetches the metrics values every four minutes and thirty seconds and uploads the data to Red Hat. These metrics are described in this document. - -This stream of data is used by Red Hat to monitor the clusters in real-time and to react as necessary to problems that impact our customers. It also allows Red Hat to roll out {product-title} upgrades to customers to minimize service impact and continuously improve the upgrade experience. - -This debugging information is available to Red Hat Support and Engineering teams with the same restrictions as accessing data reported through support cases. All connected cluster information is used by Red Hat to help make {product-title} better and more intuitive to use. diff --git a/modules/telemetry-consequences-of-disabling-telemetry.adoc b/modules/telemetry-consequences-of-disabling-telemetry.adoc deleted file mode 100644 index 44ca200ca164..000000000000 --- a/modules/telemetry-consequences-of-disabling-telemetry.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// support/remote_health_monitoring/opting-out-of-telemetry.adoc - -[id="telemetry-consequences-of-disabling-telemetry_{context}"] -= Consequences of disabling remote health reporting - -In {product-title}, customers can opt out of reporting usage information. However, connected clusters allow Red Hat to react more quickly to problems and better support our customers, as well as better understand how product upgrades impact clusters. Connected clusters also help to simplify the subscription and entitlement process and enable the {cloud-redhat-com} service to provide an overview of your clusters and their subscription status. - -Red Hat strongly recommends leaving health and usage reporting enabled for pre-production and test clusters even if it is necessary to opt out for production clusters. This allows Red Hat to be a participant in qualifying {product-title} in your environments and react more rapidly to product issues. - -Some of the consequences of opting out of having a connected cluster are: - -* Red Hat will not be able to monitor the success of product upgrades or the health of your clusters without a support case being opened. -* Red Hat will not be able to use configuration data to better triage customer support cases and identify which configurations our customers find important. -* The {cloud-redhat-com} will not show data about your clusters including health and usage information. -ifndef::openshift-origin[] -* Your subscription entitlement information must be manually entered via cloud.redhat.com without the benefit of automatic usage reporting. -endif::[] - -In restricted networks, Telemetry and Insights data can still be reported through appropriate configuration of your proxy. diff --git a/modules/telemetry-showing-data-collected-from-the-cluster.adoc b/modules/telemetry-showing-data-collected-from-the-cluster.adoc deleted file mode 100644 index 70e4bf8a790d..000000000000 --- a/modules/telemetry-showing-data-collected-from-the-cluster.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * support/remote_health_monitoring/showing-data-collected-by-remote-health-reporting.adoc - -[id="showing-data-collected-from-the-cluster_{context}"] -= Showing data collected by Telemetry - -You can see the cluster and components time series data captured by Telemetry. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster with a user that has either the `cluster-admin` role or the `cluster-monitoring-view` role. - -.Procedure - -. Find the URL for the Prometheus service that runs in the {product-title} cluster: -+ -[source,terminal] ----- -$ oc get route prometheus-k8s -n openshift-monitoring -o jsonpath="{.spec.host}" ----- - -. Navigate to the URL. - -. Enter this query in the *Expression* input box and press *Execute*: -+ ----- -{__name__=~"cluster:usage:.*|count:up0|count:up1|cluster_version|cluster_version_available_updates|cluster_operator_up|cluster_operator_conditions|cluster_version_payload|cluster_installer|cluster_infrastructure_provider|cluster_feature_set|instance:etcd_object_counts:sum|ALERTS|code:apiserver_request_total:rate:sum|cluster:capacity_cpu_cores:sum|cluster:capacity_memory_bytes:sum|cluster:cpu_usage_cores:sum|cluster:memory_usage_bytes:sum|openshift:cpu_usage_cores:sum|openshift:memory_usage_bytes:sum|workload:cpu_usage_cores:sum|workload:memory_usage_bytes:sum|cluster:virt_platform_nodes:sum|cluster:node_instance_type_count:sum|cnv:vmi_status_running:count|node_role_os_version_machine:cpu_capacity_cores:sum|node_role_os_version_machine:cpu_capacity_sockets:sum|subscription_sync_total|csv_succeeded|csv_abnormal|ceph_cluster_total_bytes|ceph_cluster_total_used_raw_bytes|ceph_health_status|job:ceph_osd_metadata:count|job:kube_pv:count|job:ceph_pools_iops:total|job:ceph_pools_iops_bytes:total|job:ceph_versions_running:count|job:noobaa_total_unhealthy_buckets:sum|job:noobaa_bucket_count:sum|job:noobaa_total_object_count:sum|noobaa_accounts_num|noobaa_total_usage|console_url|cluster:network_attachment_definition_instances:max|cluster:network_attachment_definition_enabled_instance_up:max|insightsclient_request_send_total|cam_app_workload_migrations|cluster:apiserver_current_inflight_requests:sum:max_over_time:2m|cluster:telemetry_selected_series:count",alertstate=~"firing|"} ----- -+ -This query replicates the request that Telemetry makes against a running {product-title} cluster's Prometheus service and returns the full set of time series captured by Telemetry. diff --git a/modules/telemetry-what-information-is-collected.adoc b/modules/telemetry-what-information-is-collected.adoc deleted file mode 100644 index f96018c3cd24..000000000000 --- a/modules/telemetry-what-information-is-collected.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc -// * support/remote_health_monitoring/about-remote-health-monitoring.adoc - -ifeval::["{context}" == "virt-openshift-cluster-monitoring"] -:virt-cluster: -endif::[] - -[id="what-information-is-collected_{context}"] -= Information collected by Telemetry - -The following information is collected by Telemetry: - -* The unique random identifier that is generated during an installation -* Version information, including the {product-title} cluster version and installed update details that are used to determine update version availability -* Update information, including the number of updates available per cluster, the channel and image repository used for an update, update progress information, and the number of errors that occur in an update -* The name of the provider platform that {product-title} is deployed on and the data center location -* Sizing information about clusters, machine types, and machines, including the number of CPU cores and the amount of RAM used for each -ifdef::virt-cluster[] -* The number of running virtual machine instances in a cluster -endif::virt-cluster[] -* The number of etcd members and the number of objects stored in the etcd cluster -* The {product-title} framework components installed in a cluster and their condition and status -* Usage information about components, features, and extensions -* Usage details about Technology Previews and unsupported configurations -* Information about degraded software -* Information about nodes that are marked as `NotReady` -* Events for all namespaces listed as "related objects" for a degraded Operator -* Configuration details that help Red Hat Support to provide beneficial support for customers. This includes node configuration at the cloud infrastructure level, host names, IP addresses, Kubernetes pod names, namespaces, and services. -* Information about the validity of certificates - -Telemetry does not collect identifying information such as user names, or passwords. Red Hat does not intend to collect personal information. If Red Hat discovers that personal information has been inadvertently received, Red Hat will delete such information. To the extent that any telemetry data constitutes personal data, please refer to the link:https://www.redhat.com/en/about/privacy-policy[Red Hat Privacy Statement] for more information about Red Hat’s privacy practices. - -ifeval::["{context}" == "virt-openshift-cluster-monitoring"] -:!virt-cluster: -endif::[] diff --git a/modules/templates-cli-generating-list-of-objects.adoc b/modules/templates-cli-generating-list-of-objects.adoc deleted file mode 100644 index 376a8fb61079..000000000000 --- a/modules/templates-cli-generating-list-of-objects.adoc +++ /dev/null @@ -1,93 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-cli-generating-list-of-objects_{context}"] -= Generating a list of objects - -Using the CLI, you can process a file defining a template to return the list of -objects to standard output. - -.Procedure - -. Process a file defining a template to return the list of objects to standard -output: -+ -[source,terminal] ----- -$ oc process -f <filename> ----- -+ -Alternatively, if the template has already been uploaded to the current project: -+ -[source,terminal] ----- -$ oc process <template_name> ----- -+ -. Create objects from a template by processing the template and piping the -output to `oc create`: -+ -[source,terminal] ----- -$ oc process -f <filename> | oc create -f - ----- -+ -Alternatively, if the template has already been uploaded to the current project: -+ -[source,terminal] ----- -$ oc process <template> | oc create -f - ----- -+ -. You can override any parameter values defined in the file by adding the `-p` -option for each `<name>=<value>` pair you want to override. A parameter -reference may appear in any text field inside the template items. -+ -For example, in the following the *`POSTGRESQL_USER`* and *`POSTGRESQL_DATABASE`* -parameters of a template are overridden to output a configuration with -customized environment variables: -+ -.. Creating a List of Objects from a Template -+ -[source,terminal] ----- -$ oc process -f my-rails-postgresql \ - -p POSTGRESQL_USER=bob \ - -p POSTGRESQL_DATABASE=mydatabase ----- -+ -.. The JSON file can either be redirected to a file or applied directly without -uploading the template by piping the processed output to the `oc create` -command: -+ -[source,terminal] ----- -$ oc process -f my-rails-postgresql \ - -p POSTGRESQL_USER=bob \ - -p POSTGRESQL_DATABASE=mydatabase \ - | oc create -f - ----- -+ -.. If you have large number of parameters, you can store them in a file and then -pass this file to `oc process`: -+ -[source,terminal] ----- -$ cat postgres.env -POSTGRESQL_USER=bob -POSTGRESQL_DATABASE=mydatabase ----- -+ -[source,terminal] ----- -$ oc process -f my-rails-postgresql --param-file=postgres.env ----- -+ -.. You can also read the environment from standard input by using `"-"` as the -argument to `--param-file`: -+ -[source,terminal] ----- -$ sed s/bob/alice/ postgres.env | oc process -f my-rails-postgresql --param-file=- ----- diff --git a/modules/templates-cli-labels.adoc b/modules/templates-cli-labels.adoc deleted file mode 100644 index a2adf03a765a..000000000000 --- a/modules/templates-cli-labels.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-cli-labels_{context}"] -= Adding labels - -Labels are used to manage and organize generated objects, such as pods. The -labels specified in the template are applied to every object that is generated -from the template. - -.Procedure - -* Add labels in the template from the command line: -+ -[source,terminal] ----- -$ oc process -f <filename> -l name=otherLabel ----- diff --git a/modules/templates-cli-parameters.adoc b/modules/templates-cli-parameters.adoc deleted file mode 100644 index ee952af47dc8..000000000000 --- a/modules/templates-cli-parameters.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-cli-parameters_{context}"] -= Listing parameters - -The list of parameters that you can override are listed in the `parameters` -section of the template. - -.Procedure - -. You can list parameters with the CLI by using the following command and -specifying the file to be used: -+ -[source,terminal] ----- -$ oc process --parameters -f <filename> ----- -+ -Alternatively, if the template is already uploaded: -+ -[source,terminal] ----- -$ oc process --parameters -n <project> <template_name> ----- -+ -For example, the following shows the output when listing the parameters for one -of the Quickstart templates in the default \*openshift* project: -+ -[source,terminal] ----- -$ oc process --parameters -n openshift rails-postgresql-example ----- -+ -.Example output -[source,terminal] ----- -NAME DESCRIPTION GENERATOR VALUE -SOURCE_REPOSITORY_URL The URL of the repository with your application source code https://github.com/sclorg/rails-ex.git -SOURCE_REPOSITORY_REF Set this to a branch name, tag or other ref of your repository if you are not using the default branch -CONTEXT_DIR Set this to the relative path to your project if it is not in the root of your repository -APPLICATION_DOMAIN The exposed hostname that will route to the Rails service rails-postgresql-example.openshiftapps.com -GITHUB_WEBHOOK_SECRET A secret string used to configure the GitHub webhook expression [a-zA-Z0-9]{40} -SECRET_KEY_BASE Your secret key for verifying the integrity of signed cookies expression [a-z0-9]{127} -APPLICATION_USER The application user that is used within the sample application to authorize access on pages openshift -APPLICATION_PASSWORD The application password that is used within the sample application to authorize access on pages secret -DATABASE_SERVICE_NAME Database service name postgresql -POSTGRESQL_USER database username expression user[A-Z0-9]{3} -POSTGRESQL_PASSWORD database password expression [a-zA-Z0-9]{8} -POSTGRESQL_DATABASE database name root -POSTGRESQL_MAX_CONNECTIONS database max connections 10 -POSTGRESQL_SHARED_BUFFERS database shared buffers 12MB ----- -+ -The output identifies several parameters that are generated with a regular -expression-like generator when the template is processed. diff --git a/modules/templates-create-from-existing-object.adoc b/modules/templates-create-from-existing-object.adoc deleted file mode 100644 index 7f79081815e7..000000000000 --- a/modules/templates-create-from-existing-object.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-create-from-existing-object_{context}"] -= Creating a template from existing objects - -Rather than writing an entire template from scratch, you can export existing -objects from your project in YAML form, and then modify the YAML from there by -adding parameters and other customizations as template form. - -.Procedure - -* Export objects in a project in YAML form: -+ -[source,terminal] ----- -$ oc get -o yaml all > <yaml_filename> ----- -+ -You can also substitute a particular resource type or multiple resources instead of `all`. -Run `oc get -h` for more examples. -+ -The object types included in `oc get -o yaml all` are: -+ -** `BuildConfig` -** `Build` -** `DeploymentConfig` -** `ImageStream` -** `Pod` -** `ReplicationController` -** `Route` -** `Service` - -[NOTE] -==== -Using the `all` alias is not recommended because the contents might vary across different clusters and versions. Instead, specify all required resources. -==== diff --git a/modules/templates-creating-from-console.adoc b/modules/templates-creating-from-console.adoc deleted file mode 100644 index 7edbba0a1a63..000000000000 --- a/modules/templates-creating-from-console.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-creating-from-console_{context}"] -= Creating an application by using the web console - -You can use the web console to create an application from a template. - -.Procedure - -. While in the desired project, click *Add to Project*. - -. Select either a builder image from the list of images in your project, or -from the service catalog. -+ -[NOTE] -==== -Only imagestreamtags that have the *builder* tag listed in their annotations -appear in this list, as demonstrated here: -==== -+ -[source,yaml] ----- -kind: "ImageStream" -apiVersion: "v1" -metadata: - name: "ruby" - creationTimestamp: null -spec: - dockerImageRepository: "registry.redhat.io/rhscl/ruby-26-rhel7" - tags: - - - name: "2.6" - annotations: - description: "Build and run Ruby 2.6 applications" - iconClass: "icon-ruby" - tags: "builder,ruby" <1> - supports: "ruby:2.6,ruby" - version: "2.6" ----- -<1> Including *builder* here ensures this `ImageStreamTag` appears in the -web console as a builder. - -. Modify the settings in the new application screen to configure the objects -to support your application. diff --git a/modules/templates-exposing-object-fields.adoc b/modules/templates-exposing-object-fields.adoc deleted file mode 100644 index 0faf3471abd7..000000000000 --- a/modules/templates-exposing-object-fields.adoc +++ /dev/null @@ -1,110 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-exposing-object-fields_{context}"] -= Exposing template object fields - -Template authors can indicate that fields of particular objects in a template -should be exposed. The {tsb-name} recognizes exposed fields on -`ConfigMap`, `Secret`, `Service`, and `Route` objects, and returns the values of the -exposed fields when a user binds a service backed by the broker. - -To expose one or more fields of an object, add annotations prefixed by -`template.openshift.io/expose-` or `template.openshift.io/base64-expose-` to -the object in the template. - -Each annotation key, with its prefix removed, is passed through to become a key -in a `bind` response. - -Each annotation value is a Kubernetes JSONPath expression, which is resolved at -bind time to indicate the object field whose value should be returned in the -`bind` response. - -[NOTE] -==== -`Bind` response key-value pairs can be used in other parts of the system as -environment variables. Therefore, it is recommended that every annotation key -with its prefix removed should be a valid environment variable name -- -beginning with a character `A-Z`, `a-z`, or `pass:[_]`, and being followed by zero or -more characters `A-Z`, `a-z`, `0-9`, or `pass:[_]`. -==== - -[NOTE] -==== -Unless escaped with a backslash, Kubernetes' JSONPath implementation interprets -characters such as `.`, `@`, and others as metacharacters, regardless of their -position in the expression. Therefore, for example, to refer to a `ConfigMap` -datum named `my.key`, the required JSONPath expression would be -`{.data['my\.key']}`. Depending on how the JSONPath expression is then written in YAML, -an additional backslash might be required, for example `"{.data['my\\.key']}"`. -==== - -The following is an example of different objects' fields being exposed: - -[source,yaml] ----- -kind: Template -apiVersion: v1 -metadata: - name: my-template -objects: -- kind: ConfigMap - apiVersion: v1 - metadata: - name: my-template-config - annotations: - template.openshift.io/expose-username: "{.data['my\\.username']}" - data: - my.username: foo -- kind: Secret - apiVersion: v1 - metadata: - name: my-template-config-secret - annotations: - template.openshift.io/base64-expose-password: "{.data['password']}" - stringData: - password: bar -- kind: Service - apiVersion: v1 - metadata: - name: my-template-service - annotations: - template.openshift.io/expose-service_ip_port: "{.spec.clusterIP}:{.spec.ports[?(.name==\"web\")].port}" - spec: - ports: - - name: "web" - port: 8080 -- kind: Route - apiVersion: v1 - metadata: - name: my-template-route - annotations: - template.openshift.io/expose-uri: "http://{.spec.host}{.spec.path}/" - spec: - path: mypath ----- - -An example response to a `bind` operation given the above partial template -follows: - -[source,json] ----- -{ - "credentials": { - "username": "foo", - "password": "YmFy", - "service_ip_port": "172.30.12.34:8080", - "uri": "http://route-test.router.default.svc.cluster.local/mypath" - } -} ----- - -.Procedure - -* Use the `template.openshift.io/expose-` annotation to return the field value as -a string. This is convenient, although it does not handle arbitrary binary data. - -* If you want to return binary data, use the -`template.openshift.io/base64-expose-` annotation instead to base64 encode the -data before it is returned. diff --git a/modules/templates-marking-as-bindable.adoc b/modules/templates-marking-as-bindable.adoc deleted file mode 100644 index bfda79ac4ae0..000000000000 --- a/modules/templates-marking-as-bindable.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-marking-as-bindable_{context}"] -= Marking a template as bindable - -The {tsb-name} advertises one service in its catalog for each -Template object of which it is aware. By default, each of these services is -advertised as being "bindable", meaning an end user is permitted to bind against -the provisioned service. - -.Procedure - -Template authors can prevent end users from binding against services provisioned -from a given Template. - - * Prevent end user from binding against services provisioned from a given - template by adding the annotation `template.openshift.io/bindable: "false"` - to the Template. diff --git a/modules/templates-modifying-uploaded-template.adoc b/modules/templates-modifying-uploaded-template.adoc deleted file mode 100644 index 921241cf8b05..000000000000 --- a/modules/templates-modifying-uploaded-template.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-modifying-uploaded-templates_{context}"] -= Modifying uploaded templates - -You can edit a template that has already been uploaded to your project. - -.Procedure - -* Modify a template that has already been uploaded: -+ -[source,terminal] ----- -$ oc edit template <template> ----- diff --git a/modules/templates-overview.adoc b/modules/templates-overview.adoc deleted file mode 100644 index e84872182cc9..000000000000 --- a/modules/templates-overview.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-overview_{context}"] -= Understanding templates - -A template describes a set of objects that can be parameterized and processed to -produce a list of objects for creation by {product-title}. A template can be -processed to create anything you have permission to create within a project, for -example services, build configurations, and DeploymentConfigs. A -template may also define a set of labels to apply to every object defined in the -template. - -You can create a list of objects from a template using the CLI or, if a -template has been uploaded to your project or the -global template library, using the web console. - -//.Additional resources -//For a curated set of templates, see the -//link:https://github.com/openshift/library[OpenShift ImageStreams and Templates -//library]. diff --git a/modules/templates-quickstart.adoc b/modules/templates-quickstart.adoc deleted file mode 100644 index 4737e781e7f9..000000000000 --- a/modules/templates-quickstart.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-quickstart_{context}"] -= Quickstart templates - -A Quickstart is a basic example of an application running on {product-title}. -Quickstarts come in a variety of languages and frameworks, and are defined in a -template, which is constructed from a set of services, build configurations, and -DeploymentConfigs. This template references the necessary images and -source repositories to build and deploy the application. - -To explore a Quickstart, create an application from a template. Your -administrator may have already installed these templates in your {product-title} -cluster, in which case you can simply select it from the web console. - -Quickstarts refer to a source repository that contains the application source -code. To customize the Quickstart, fork the repository and, when creating an -application from the template, substitute the default source repository name -with your forked repository. This results in builds that are performed using -your source code instead of the provided example source. You can then update the -code in your source repository and launch a new build to see the changes -reflected in the deployed application. - -[id="templates-quickstart-web-framework_{context}"] -== Web framework Quickstart templates - -These Quickstart templates provide a basic application of the indicated -framework and language: - -* CakePHP: a PHP web framework (includes a MySQL database) -* Dancer: a Perl web framework (includes a MySQL database) -* Django: a Python web framework (includes a PostgreSQL database) -* NodeJS: a NodeJS web application (includes a MongoDB database) -* Rails: a Ruby web framework (includes a PostgreSQL database) - - - -//* CakePHP: a PHP web framework (includes a MySQL database) -//** link:https://github.com/openshift/origin/tree/master/examples/quickstarts/cakephp-mysql.json[Template definition] -//** link:https://github.com/sclorg/cakephp-ex[Source repository] -//* Dancer: a Perl web framework (includes a MySQL database) -//** link:https://github.com/openshift/origin/tree/master/examples/quickstarts/dancer-mysql.json[Template definition] -//** link:https://github.com/sclorg/dancer-ex[Source repository] -//* Django: a Python web framework (includes a PostgreSQL database) -//** link:https://github.com/openshift/origin/tree/master/examples/quickstarts/django-postgresql.json[Template definition] -//** link:https://github.com/sclorg/django-ex[Source repository] -//* NodeJS: a NodeJS web application (includes a MongoDB database) -//** link:https://github.com/openshift/origin/tree/master/examples/quickstarts/nodejs-mongodb.json[Template definition] -//** link:https://github.com/sclorg/nodejs-ex[Source repository] -//* Rails: a Ruby web framework (includes a PostgreSQL database) -//** link:https://github.com/openshift/origin/tree/master/examples/quickstarts/rails-postgresql.json[Template definition] -//** link:https://github.com/sclorg/rails-ex[Source repository] diff --git a/modules/templates-rails-configuring-application.adoc b/modules/templates-rails-configuring-application.adoc deleted file mode 100644 index 541337024b72..000000000000 --- a/modules/templates-rails-configuring-application.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - -[id="templates-rails-configuring-application_{context}"] -= Configuring application for {product-title} - -To have your application communicate with the PostgreSQL database -service running in {product-title} you must edit the -`default` section in your `config/database.yml` to use environment -variables, which you will define later, upon the database service creation. - -.Procedure - -* Edit the `default` section in your `config/database.yml` with -pre-defined variables as follows: -+ -[source,yaml] ----- -<% user = ENV.key?("POSTGRESQL_ADMIN_PASSWORD") ? "root" : ENV["POSTGRESQL_USER"] %> -<% password = ENV.key?("POSTGRESQL_ADMIN_PASSWORD") ? ENV["POSTGRESQL_ADMIN_PASSWORD"] : ENV["POSTGRESQL_PASSWORD"] %> -<% db_service = ENV.fetch("https://github.com/DATABASE_SERVICE_NAME","").upcase %> - -default: &default - adapter: postgresql - encoding: unicode - # For details on connection pooling, see rails configuration guide - # http://guides.rubyonrails.org/configuring.html#database-pooling - pool: <%= ENV["POSTGRESQL_MAX_CONNECTIONS"] || 5 %> - username: <%= user %> - password: <%= password %> - host: <%= ENV["#{db_service}_SERVICE_HOST"] %> - port: <%= ENV["#{db_service}_SERVICE_PORT"] %> - database: <%= ENV["POSTGRESQL_DATABASE"] %> ----- diff --git a/modules/templates-rails-creating-database-service.adoc b/modules/templates-rails-creating-database-service.adoc deleted file mode 100644 index 54826aa5bc6f..000000000000 --- a/modules/templates-rails-creating-database-service.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - -[id="templates-rails-creating-database-service_{context}"] -= Creating the database service - -Your Rails application expects a running database service. For this service use -PostgeSQL database image. - -To create the database service you will use the `oc new-app` command. To this -command you must pass some necessary environment variables which will be -used inside the database container. These environment variables are required to -set the username, password, and name of the database. You can change the values -of these environment variables to anything you would like. The variables are as -follows: - -* POSTGRESQL_DATABASE -* POSTGRESQL_USER -* POSTGRESQL_PASSWORD - -Setting these variables ensures: - -* A database exists with the specified name. -* A user exists with the specified name. -* The user can access the specified database with the specified password. - -.Procedure - -. Create the database service: -+ -[source,terminal] ----- -$ oc new-app postgresql -e POSTGRESQL_DATABASE=db_name -e POSTGRESQL_USER=username -e POSTGRESQL_PASSWORD=password ----- -+ -To also set the password for the database administrator, append to the previous -command with: -+ -[source,terminal] ----- --e POSTGRESQL_ADMIN_PASSWORD=admin_pw ----- - -. Watch the progress: -+ -[source,terminal] ----- -$ oc get pods --watch ----- diff --git a/modules/templates-rails-creating-frontend-service.adoc b/modules/templates-rails-creating-frontend-service.adoc deleted file mode 100644 index ffd2debe4f72..000000000000 --- a/modules/templates-rails-creating-frontend-service.adoc +++ /dev/null @@ -1,96 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - -[id="templates-rails-creating-frontend-service_{context}"] -= Creating the frontend service - -To bring your application to {product-title}, you must specify a repository -in which your application lives. - -.Procedure - -. Create the frontend service and specify database related -environment variables that were setup when creating the database service: -+ -[source,terminal] ----- -$ oc new-app path/to/source/code --name=rails-app -e POSTGRESQL_USER=username -e POSTGRESQL_PASSWORD=password -e POSTGRESQL_DATABASE=db_name -e DATABASE_SERVICE_NAME=postgresql ----- -+ -With this command, {product-title} fetches the source code, sets up the builder -builds your application image, and deploys the newly created image together with -the specified environment variables. The application is named `rails-app`. - -. Verify the environment variables have been added by viewing the JSON document of -the `rails-app` DeploymentConfig: -+ -[source,terminal] ----- -$ oc get dc rails-app -o json ----- -+ -You should see the following section: -+ -[source,json] ----- -env": [ - { - "name": "POSTGRESQL_USER", - "value": "username" - }, - { - "name": "POSTGRESQL_PASSWORD", - "value": "password" - }, - { - "name": "POSTGRESQL_DATABASE", - "value": "db_name" - }, - { - "name": "DATABASE_SERVICE_NAME", - "value": "postgresql" - } - -], ----- - -. Check the build process: -+ -[source,terminal] ----- -$ oc logs -f build/rails-app-1 ----- - -. Once the build is complete, look at the running pods in {product-title}: -+ -[source,terminal] ----- -$ oc get pods ----- -+ -You should see a line starting with `myapp-<number>-<hash>`, and that is your -application running in {product-title}. - -. Before your application will be functional, you must initialize the database -by running the database migration script. There are two ways you can do this: -+ -* Manually from the running frontend container: -+ -** Exec into frontend container with `rsh` command: -+ -[source,terminal] ----- -$ oc rsh <frontend_pod_id> ----- -+ -** Run the migration from inside the container: -+ -[source,terminal] ----- -$ RAILS_ENV=production bundle exec rake db:migrate ----- -+ -If you are running your Rails application in a `development` or `test` -environment you do not have to specify the `RAILS_ENV` environment variable. -+ -* By adding pre-deployment lifecycle hooks in your template. diff --git a/modules/templates-rails-creating-route-for-application.adoc b/modules/templates-rails-creating-route-for-application.adoc deleted file mode 100644 index 1d89a67ac25e..000000000000 --- a/modules/templates-rails-creating-route-for-application.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - -[id="templates-rails-creating-route-for-application_{context}"] -= Creating a route for your application - -You can expose a service to create a route for your application. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -.Procedure - -* To expose a service by giving it an externally-reachable hostname like -`www.example.com` use {product-title} route. In your case you need -to expose the frontend service by typing: -+ -[source,terminal] ----- -$ oc expose service rails-app --hostname=www.example.com ----- - - -ifdef::openshift-online[] -.Procedure - -* Expose the frontend service by typing: -+ -[source,terminal] ----- -$ oc expose service rails-app ----- -endif::[] - -[WARNING] -==== -Ensure the hostname you specify resolves into the IP address of the router. -==== diff --git a/modules/templates-rails-creating-welcome-page.adoc b/modules/templates-rails-creating-welcome-page.adoc deleted file mode 100644 index 11c788c43cf1..000000000000 --- a/modules/templates-rails-creating-welcome-page.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - -[id="templates-rails-creating-welcome-page_{context}"] -= Creating a welcome page - -Since Rails 4 no longer serves a static `public/index.html` page in production, -you must create a new root page. - -To have a custom welcome page must do following steps: - -* Create a *controller* with an index action -* Create a *view* page for the `welcome` controller `index` action -* Create a *route* that will serve applications root page with the created -*controller* and *view* - -Rails offers a generator that will do all necessary steps for you. - -.Procedure - -. Run Rails generator: -+ -[source,terminal] ----- -$ rails generate controller welcome index ----- -+ -All the necessary files are created. - -. edit line 2 in `config/routes.rb` file as follows: -+ ----- -root 'welcome#index' ----- - -. Run the rails server to verify the page is available: -+ -[source,terminal] ----- -$ rails server ----- -+ -You should see your page by visiting *http://localhost:3000* in your browser. -If you do not see the page, check the logs that are output to your server to debug. diff --git a/modules/templates-rails-deploying-application.adoc b/modules/templates-rails-deploying-application.adoc deleted file mode 100644 index e245f3e171c7..000000000000 --- a/modules/templates-rails-deploying-application.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - -[id="templates-rails-deploying-application_{context}"] -= Deploying your application to {product-title} - -You can deploy you application to {product-title}. - -After creating the `rails-app` project, you will be automatically switched to -the new project namespace. - -Deploying your application in {product-title} involves three steps: - -* Creating a database service from {product-title}'s PostgreSQL image. -* Creating a frontend service from {product-title}'s Ruby 2.0 builder image and -your Ruby on Rails source code, which are wired with the database service. -* Creating a route for your application. - -.Procedure - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated[] -* To deploy your Ruby on Rails application, create a new Project for the -application: -+ -[source,terminal] ----- -$ oc new-project rails-app --description="My Rails application" --display-name="Rails Application" ----- -endif::[] diff --git a/modules/templates-rails-setting-up-database.adoc b/modules/templates-rails-setting-up-database.adoc deleted file mode 100644 index 3a45b75e1c40..000000000000 --- a/modules/templates-rails-setting-up-database.adoc +++ /dev/null @@ -1,43 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - -[id="templates-rails-setting-up-database_{context}"] -= Setting up the database - -Rails applications are almost always used with a database. For the local -development use the PostgreSQL database. - -.Procedure - -. Install the database: -+ -[source,terminal] ----- -$ sudo yum install -y postgresql postgresql-server postgresql-devel ----- - -. Initialize the database: -+ -[source,terminal] ----- -$ sudo postgresql-setup initdb ----- -+ -This command will create the `/var/lib/pgsql/data` directory, in which the data -will be stored. - -. Start the database: -+ -[source,terminal] ----- -$ sudo systemctl start postgresql.service ----- - -. When the database is running, create your `rails` user: -+ -[source,terminal] ----- -$ sudo -u postgres createuser -s rails ----- -+ -Note that the user created has no password. diff --git a/modules/templates-rails-storing-application-in-git.adoc b/modules/templates-rails-storing-application-in-git.adoc deleted file mode 100644 index 067a109dc44f..000000000000 --- a/modules/templates-rails-storing-application-in-git.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - - -[id="templates-rails-storing-application-in-git_{context}"] -= Storing your application in Git - -Building an application in {product-title} usually requires that the source code -be stored in a git repository, so you must -install `git` if you do not already have it. - -.Prerequisites - -* Install git. - -.Procedure - -. Make sure you are in your Rails application directory by running the `ls -1` -command. The output of the command should look like: -+ -[source,terminal] ----- -$ ls -1 ----- -+ -.Example output -[source,terminal] ----- -app -bin -config -config.ru -db -Gemfile -Gemfile.lock -lib -log -public -Rakefile -README.rdoc -test -tmp -vendor ----- - -. Run the following commands in your Rails app directory to initialize and commit -your code to git: -+ -[source,terminal] ----- -$ git init ----- -+ -[source,terminal] ----- -$ git add . ----- -+ -[source,terminal] ----- -$ git commit -m "initial commit" ----- -+ -After your application is committed you must push it to a remote repository. -GitHub account, in which you create a new repository. - -. Set the remote that points to your `git` repository: -+ -[source,terminal] ----- -$ git remote add origin git@github.com:<namespace/repository-name>.git ----- - -. Push your application to your remote git repository. -+ -[source,terminal] ----- -$ git push ----- diff --git a/modules/templates-rails-writing-application.adoc b/modules/templates-rails-writing-application.adoc deleted file mode 100644 index f53b47e21635..000000000000 --- a/modules/templates-rails-writing-application.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// * openshift_images/templates-ruby-on-rails.adoc - -[id="templates-rails-writing-application_{context}"] -= Writing your application - -If you are starting your Rails application from scratch, you must install the -Rails gem first. Then you can proceed with writing your application. - -.Procedure - -. Install the Rails gem: -+ -[source,terminal] ----- -$ gem install rails ----- -+ -.Example output -[source,terminal] ----- -Successfully installed rails-4.3.0 -1 gem installed ----- - -. After you install the Rails gem, create a new application with PostgreSQL as -your database: -+ -[source,terminal] ----- -$ rails new rails-app --database=postgresql ----- - -. Change into your new application directory: -+ -[source,terminal] ----- -$ cd rails-app ----- - -. If you already have an application, make sure the `pg` (postgresql) gem is -present in your `Gemfile`. If not, edit your `Gemfile` by adding the gem: -+ -[source,terminal] ----- -gem 'pg' ----- - -. Generate a new `Gemfile.lock` with all your dependencies: -+ -[source,terminal] ----- -$ bundle install ----- - -. In addition to using the `postgresql` database with the `pg` gem, you also -must ensure that the `config/database.yml` is using the `postgresql` adapter. -+ -Make sure you updated `default` section in the `config/database.yml` file, so it -looks like this: -+ -[source,yaml] ----- -default: &default - adapter: postgresql - encoding: unicode - pool: 5 - host: localhost - username: rails - password: ----- - -. Create your application's development and test databases: -+ -[source,terminal] ----- -$ rake db:create ----- -+ -This will create `development` and `test` database in your PostgreSQL server. diff --git a/modules/templates-uploading.adoc b/modules/templates-uploading.adoc deleted file mode 100644 index 8df202617a41..000000000000 --- a/modules/templates-uploading.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-uploading_{context}"] -= Uploading a template - -If you have a JSON or YAML file that defines a template, for example as seen in -this example, you can upload the template to projects using the CLI. This saves -the template to the project for repeated use by any user with appropriate access -to that project. Instructions on writing your own templates are provided later -in this topic. - -.Procedure - -* Upload a template to your current project's template library, pass the JSON -or YAML file with the following command: -+ -[source,terminal] ----- -$ oc create -f <filename> ----- - -* Upload a template to a different project using the `-n` option with the -name of the project: -+ -[source,terminal] ----- -$ oc create -f <filename> -n <project> ----- - -The template is now available for selection using the web console or the CLI. diff --git a/modules/templates-using-instant-app-quickstart.adoc b/modules/templates-using-instant-app-quickstart.adoc deleted file mode 100644 index 0cb29b9165f4..000000000000 --- a/modules/templates-using-instant-app-quickstart.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-using-instant-app-quickstart_{context}"] -= Using Instant App and Quickstart templates - -{product-title} provides a number of default Instant App and Quickstart -templates to make it easy to quickly get started creating a new application for -different languages. Templates are provided for Rails (Ruby), Django (Python), -Node.js, CakePHP (PHP), and Dancer (Perl). Your cluster administrator should -have created these templates in the default, global *openshift* project so you -have access to them. - -By default, the templates build using a public source repository on -GitHub that contains the necessary application code. - -.Procedure - -. You can list the available default Instant App and Quickstart templates with: -+ -[source,terminal] ----- -$ oc get templates -n openshift ----- - -. To modify the source and build your own version of the application: -+ -.. Fork the repository referenced by the template's default -`SOURCE_REPOSITORY_URL` parameter. -+ -.. Override the value of the `SOURCE_REPOSITORY_URL` parameter when creating -from the template, specifying your fork instead of the default value. -+ -By doing this, the build configuration created by the template will now point to -your fork of the application code, and you can modify the code and rebuild the -application at will. - - -[NOTE] -==== -Some of the Instant App and Quickstart templates define a database deployment -configuration. The configuration they define uses ephemeral storage for the -database content. These templates should be used for demonstration purposes only -as all database data will be lost if the database pod restarts for any reason. -==== diff --git a/modules/templates-using-the-cli.adoc b/modules/templates-using-the-cli.adoc deleted file mode 100644 index b13136d6988c..000000000000 --- a/modules/templates-using-the-cli.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-using-the-cli_{context}"] -= Creating objects from templates by using the CLI - -You can use the CLI to process templates and use the configuration that is -generated to create objects. diff --git a/modules/templates-waiting-for-readiness.adoc b/modules/templates-waiting-for-readiness.adoc deleted file mode 100644 index 598dbcdf682b..000000000000 --- a/modules/templates-waiting-for-readiness.adoc +++ /dev/null @@ -1,110 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-waiting-for-readiness_{context}"] -= Waiting for template readiness - -Template authors can indicate that certain objects within a template -should be waited for before a template instantiation by the service catalog, -{tsb-name}, or TemplateInstance API is considered complete. - -To use this feature, mark one or more objects of kind -`Build`, `BuildConfig`, `Deployment`, `DeploymentConfig`, `Job`, or `StatefulSet` -in a template with the following annotation: - ----- -"template.alpha.openshift.io/wait-for-ready": "true" ----- - -Template instantiation will not complete until all objects marked with the -annotation report ready. Similarly, if any of the annotated objects report -failed, or if the template fails to become ready within a fixed timeout of one -hour, the template instantiation will fail. - -For the purposes of instantiation, readiness and failure of each object kind are -defined as follows: - -[cols="1a,2a,2a", options="header"] -|=== - -| Kind -| Readiness -| Failure - -| `Build` -| Object reports phase Complete -| Object reports phase Canceled, Error, or Failed - -| `BuildConfig` -| Latest associated Build object reports phase Complete -| Latest associated Build object reports phase Canceled, Error, or Failed - -| `Deployment` -| Object reports new ReplicaSet and deployment available (this honors readiness -probes defined on the object) -| Object reports Progressing condition as false - -|`DeploymentConfig` -| Object reports new ReplicationController and deployment available (this -honors readiness probes defined on the object) -| Object reports Progressing condition as false - -| `Job` -| Object reports completion -| Object reports that one or more failures have occurred - -| `StatefulSet` -| Object reports all replicas ready (this honors readiness probes defined on -the object) -| Not applicable -|=== - -The following is an example template extract, which uses the `wait-for-ready` -annotation. Further examples can be found in the OpenShift quickstart templates. - -[source,yaml] ----- -kind: Template -apiVersion: v1 -metadata: - name: my-template -objects: -- kind: BuildConfig - apiVersion: v1 - metadata: - name: ... - annotations: - # wait-for-ready used on BuildConfig ensures that template instantiation - # will fail immediately if build fails - template.alpha.openshift.io/wait-for-ready: "true" - spec: - ... -- kind: DeploymentConfig - apiVersion: v1 - metadata: - name: ... - annotations: - template.alpha.openshift.io/wait-for-ready: "true" - spec: - ... -- kind: Service - apiVersion: v1 - metadata: - name: ... - spec: - ... ----- - -.Additional recommendations - -* Set memory, CPU, and storage -default sizes to make sure your application is given enough resources to run -smoothly. - -* Avoid referencing the `latest` tag from images if that tag is used across major -versions. This may cause running applications to break when new images are -pushed to that tag. - -* A good template builds and deploys cleanly without requiring modifications -after the template is deployed. diff --git a/modules/templates-writing-description.adoc b/modules/templates-writing-description.adoc deleted file mode 100644 index 0c6d6912fc58..000000000000 --- a/modules/templates-writing-description.adoc +++ /dev/null @@ -1,169 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-writing-description_{context}"] -= Writing the template description - -The template description informs users what the template does and helps them -find it when searching in the web console. Additional metadata beyond the -template name is optional, but useful to have. In addition to general -descriptive information, the metadata also includes a set of tags. Useful tags -include the name of the language the template is related to (for example, -*java*, *php*, *ruby*, and so on). - -The following is an example of template description metadata: - -[source,yaml] ----- -kind: Template -apiVersion: v1 -metadata: - name: cakephp-mysql-example <1> - annotations: - openshift.io/display-name: "CakePHP MySQL Example (Ephemeral)" <2> - description: >- - An example CakePHP application with a MySQL database. For more information - about using this template, including OpenShift considerations, see - https://github.com/sclorg/cakephp-ex/blob/master/README.md. - - - WARNING: Any data stored will be lost upon pod destruction. Only use this - template for testing." <3> - openshift.io/long-description: >- - This template defines resources needed to develop a CakePHP application, - including a build configuration, application DeploymentConfig, and - database DeploymentConfig. The database is stored in - non-persistent storage, so this configuration should be used for - experimental purposes only. <4> - tags: "quickstart,php,cakephp" <5> - iconClass: icon-php <6> - openshift.io/provider-display-name: "Red Hat, Inc." <7> - openshift.io/documentation-url: "https://github.com/sclorg/cakephp-ex" <8> - openshift.io/support-url: "https://access.redhat.com/" <9> -message: "Your admin credentials are ${ADMIN_USERNAME}:${ADMIN_PASSWORD}" <10> ----- -<1> The unique name of the template. -<2> A brief, user-friendly name, which can be employed by user interfaces. -<3> A description of the template. Include enough detail that the user will -understand what is being deployed and any caveats they must know before -deploying. It should also provide links to additional information, such as a -*_README_* file. Newlines can be included to create paragraphs. -<4> Additional template description. This may be displayed by the service -catalog, for example. -<5> Tags to be associated with the template for searching and grouping. Add tags -that will include it into one of the provided catalog categories. Refer to the -`id` and `categoryAliases` in `CATALOG_CATEGORIES` in the console's -constants file. -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -The categories can also be customized for the whole cluster. -endif::[] -<6> An icon to be displayed with your template in the web console. -+ -.Available icons -[%collapsible] -==== -* `icon-3scale` -* `icon-aerogear` -* `icon-amq` -* `icon-angularjs` -* `icon-ansible` -* `icon-apache` -* `icon-beaker` -* `icon-camel` -* `icon-capedwarf` -* `icon-cassandra` -* `icon-catalog-icon` -* `icon-clojure` -* `icon-codeigniter` -* `icon-cordova` -* `icon-datagrid` -* `icon-datavirt` -* `icon-debian` -* `icon-decisionserver` -* `icon-django` -* `icon-dotnet` -* `icon-drupal` -* `icon-eap` -* `icon-elastic` -* `icon-erlang` -* `icon-fedora` -* `icon-freebsd` -* `icon-git` -* `icon-github` -* `icon-gitlab` -* `icon-glassfish` -* `icon-go-gopher` -* `icon-golang` -* `icon-grails` -* `icon-hadoop` -* `icon-haproxy` -* `icon-helm` -* `icon-infinispan` -* `icon-jboss` -* `icon-jenkins` -* `icon-jetty` -* `icon-joomla` -* `icon-jruby` -* `icon-js` -* `icon-knative` -* `icon-kubevirt` -* `icon-laravel` -* `icon-load-balancer` -* `icon-mariadb` -* `icon-mediawiki` -* `icon-memcached` -* `icon-mongodb` -* `icon-mssql` -* `icon-mysql-database` -* `icon-nginx` -* `icon-nodejs` -* `icon-openjdk` -* `icon-openliberty` -* `icon-openshift` -* `icon-openstack` -* `icon-other-linux` -* `icon-other-unknown` -* `icon-perl` -* `icon-phalcon` -* `icon-php` -* `icon-play` -* `iconpostgresql` -* `icon-processserver` -* `icon-python` -* `icon-quarkus` -* `icon-rabbitmq` -* `icon-rails` -* `icon-redhat` -* `icon-redis` -* `icon-rh-integration` -* `icon-rh-spring-boot` -* `icon-rh-tomcat` -* `icon-ruby` -* `icon-scala` -* `icon-serverlessfx` -* `icon-shadowman` -* `icon-spring-boot` -* `icon-spring` -* `icon-sso` -* `icon-stackoverflow` -* `icon-suse` -* `icon-symfony` -* `icon-tomcat` -* `icon-ubuntu` -* `icon-vertx` -* `icon-wildfly` -* `icon-windows` -* `icon-wordpress` -* `icon-xamarin` -* `icon-zend` -==== -<7> The name of the person or organization providing the template. -<8> A URL referencing further documentation for the template. -<9> A URL where support can be obtained for the template. -<10> An instructional message that is displayed when this template is -instantiated. This field should inform the user how to use the newly created -resources. Parameter substitution is performed on the message before being -displayed so that generated credentials and other parameters can be included in -the output. Include links to any next-steps documentation that users should -follow. diff --git a/modules/templates-writing-labels.adoc b/modules/templates-writing-labels.adoc deleted file mode 100644 index 1ff9f91715d8..000000000000 --- a/modules/templates-writing-labels.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-writing-label_{context}"] -= Writing template labels - -Templates can include a set of labels. These labels will be added to each object -created when the template is instantiated. Defining a label in this way makes it -easy for users to find and manage all the objects created from a particular -template. - -The following is an example of template object labels: - -[source,yaml] ----- -kind: "Template" -apiVersion: "v1" -... -labels: - template: "cakephp-mysql-example" <1> - app: "${NAME}" <2> ----- -<1> A label that will be applied to all objects created from this template. -<2> A parameterized label that will also be applied to all objects created from -this template. Parameter expansion is carried out on both label keys and -values. diff --git a/modules/templates-writing-object-list.adoc b/modules/templates-writing-object-list.adoc deleted file mode 100644 index d7f88c9cef3f..000000000000 --- a/modules/templates-writing-object-list.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-writing-object-list_{context}"] -= Writing the template object list - -The main portion of the template is the list of objects which will be created -when the template is instantiated. This can be any valid API object, such as a -`BuildConfig`, `DeploymentConfig`, `Service`, etc. The object will be -created exactly as defined here, with any parameter values substituted in prior -to creation. The definition of these objects can reference parameters defined -earlier. - -The following is an example of an object list: - -[source,yaml] ----- -kind: "Template" -apiVersion: "v1" -metadata: - name: my-template -objects: - - kind: "Service" <1> - apiVersion: "v1" - metadata: - name: "cakephp-mysql-example" - annotations: - description: "Exposes and load balances the application pods" - spec: - ports: - - name: "web" - port: 8080 - targetPort: 8080 - selector: - name: "cakephp-mysql-example" ----- -<1> The definition of a `Service` which will be created by this template. - - -[NOTE] -==== -If an object definition's metadata includes a fixed `namespace` field value, the -field will be stripped out of the definition during template instantiation. If -the `namespace` field contains a parameter reference, normal parameter -substitution will be performed and the object will be created in whatever -namespace the parameter substitution resolved the value to, assuming the user -has permission to create objects in that namespace. -==== diff --git a/modules/templates-writing-parameters.adoc b/modules/templates-writing-parameters.adoc deleted file mode 100644 index bdd05733b188..000000000000 --- a/modules/templates-writing-parameters.adoc +++ /dev/null @@ -1,170 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-writing-parameters_{context}"] -= Writing template parameters - -Parameters allow a value to be supplied by the user or generated when the -template is instantiated. Then, that value is substituted wherever the parameter -is referenced. References can be defined in any field in the objects list field. -This is useful for generating random passwords or allowing the user to supply a -host name or other user-specific value that is required to customize the -template. Parameters can be referenced in two ways: - -* As a string value by placing values in the form *${PARAMETER_NAME}* in any -string field in the template. - -* As a json/yaml value by placing values in the form *${{PARAMETER_NAME}}* in -place of any field in the template. - -When using the *${PARAMETER_NAME}* syntax, multiple parameter references can be -combined in a single field and the reference can be embedded within fixed data, -such as *"http://${parameter_1}${parameter_2}/"*. Both parameter values will be -substituted and the resulting value will be a quoted string. - -When using the *${{PARAMETER_NAME}}* syntax only a single parameter reference is -allowed and leading/trailing characters are not permitted. The resulting value -will be unquoted unless, after substitution is performed, the result is not a -valid json object. If the result is not a valid json value, the resulting value -will be quoted and treated as a standard string. - -A single parameter can be referenced multiple times within a template and it can -be referenced using both substitution syntaxes within a single template. - -A default value can be provided, which is used if the user does not supply a -different value: - -The following is an example of setting an explicit value as the default value: - -[source,yaml] ----- -parameters: - - name: USERNAME - description: "The user name for Joe" - value: joe ----- - -Parameter values can also be generated based on rules specified in the parameter -definition, for example generating a parameter value: - -[source,yaml] ----- -parameters: - - name: PASSWORD - description: "The random user password" - generate: expression - from: "[a-zA-Z0-9]{12}" ----- - - -In the previous example, processing will generate a random password 12 -characters long consisting of all upper and lowercase alphabet letters -and numbers. - -The syntax available is not a full regular expression syntax. However, you can -use `\w`, `\d`, `\a`, and `\A` modifiers: - -- `[\w]{10}` produces 10 alphabet characters, numbers, and underscores. This -follows the PCRE standard and is equal to `[a-zA-Z0-9_]{10}`. -- `[\d]{10}` produces 10 numbers. This is equal to `[0-9]{10}`. -- `[\a]{10}` produces 10 alphabetical characters. This is equal to -`[a-zA-Z]{10}`. -- `[\A]{10}` produces 10 punctuation or symbol characters. This is equal to ``[~!@#$%^&*()-_+={}[]\|<,>.?/"';:`]{10}``. - -[NOTE] -==== -Depending on if the template is written in YAML or JSON, and the type of string that the modifier is embedded within, you might need to escape the backslash with a second backslash. The following examples are equivalent: - -.Example YAML template with a modifier -[source,yaml] ----- - parameters: - - name: singlequoted_example - generate: expression - from: '[\A]{10}' - - name: doublequoted_example - generate: expression - from: "[\\A]{10}" ----- - -.Example JSON template with a modifier -[source,json] ----- -{ - "parameters": [ - {"name": "json_example", - "generate": "expression", - "from": "[\\A]{10}" - } - ] -} ----- -==== - -Here is an example of a full template with parameter definitions and references: - -[source,yaml] ----- -kind: Template -apiVersion: v1 -metadata: - name: my-template -objects: - - kind: BuildConfig - apiVersion: v1 - metadata: - name: cakephp-mysql-example - annotations: - description: Defines how to build the application - spec: - source: - type: Git - git: - uri: "${SOURCE_REPOSITORY_URL}" <1> - ref: "${SOURCE_REPOSITORY_REF}" - contextDir: "${CONTEXT_DIR}" - - kind: DeploymentConfig - apiVersion: v1 - metadata: - name: frontend - spec: - replicas: "${{REPLICA_COUNT}}" <2> -parameters: - - name: SOURCE_REPOSITORY_URL <3> - displayName: Source Repository URL <4> - description: The URL of the repository with your application source code <5> - value: https://github.com/sclorg/cakephp-ex.git <6> - required: true <7> - - name: GITHUB_WEBHOOK_SECRET - description: A secret string used to configure the GitHub webhook - generate: expression <8> - from: "[a-zA-Z0-9]{40}" <9> - - name: REPLICA_COUNT - description: Number of replicas to run - value: "2" - required: true -message: "... The GitHub webhook secret is ${GITHUB_WEBHOOK_SECRET} ..." <10> ----- -<1> This value will be replaced with the value of the `SOURCE_REPOSITORY_URL` -parameter when the template is instantiated. -<2> This value will be replaced with the unquoted value of the `REPLICA_COUNT` -parameter when the template is instantiated. -<3> The name of the parameter. This value is used to -reference the parameter within the template. -<4> The user-friendly name for the parameter. This will be displayed to users. -<5> A description of the parameter. Provide more detailed information for the purpose -of the parameter, including any constraints on the expected value. Descriptions should -use complete sentences to follow the console's text standards. -Do not make this a duplicate of the display name. -<6> A default value for the parameter which will be used if the user does not -override the value when instantiating the template. Avoid using default values for things like passwords, instead -use generated parameters in combination with Secrets. -<7> Indicates this parameter is required, meaning the user cannot override it -with an empty value. If the parameter does not provide a default or generated -value, the user must supply a value. -<8> A parameter which has its value generated. -<9> The input to the generator. In this case, the generator will produce a 40 -character alphanumeric value including upper and lowercase characters. -<10> Parameters can be included in the template message. This informs the -user about generated values. diff --git a/modules/templates-writing.adoc b/modules/templates-writing.adoc deleted file mode 100644 index e62983ee4baf..000000000000 --- a/modules/templates-writing.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * openshift_images/using-templates.adoc - -[id="templates-writing_{context}"] -= Writing templates - -You can define new templates to make it easy to recreate all the objects of your -application. The template will define the objects it creates along with some -metadata to guide the creation of those objects. - -The following is an example of a simple template object definition (YAML): - -[source,yaml] ----- -apiVersion: v1 -kind: Template -metadata: - name: redis-template - annotations: - description: "Description" - iconClass: "icon-redis" - tags: "database,nosql" -objects: -- apiVersion: v1 - kind: Pod - metadata: - name: redis-master - spec: - containers: - - env: - - name: REDIS_PASSWORD - value: ${REDIS_PASSWORD} - image: dockerfile/redis - name: master - ports: - - containerPort: 6379 - protocol: TCP -parameters: -- description: Password used for Redis authentication - from: '[A-Z0-9]{8}' - generate: expression - name: REDIS_PASSWORD -labels: - redis: master ----- diff --git a/modules/test-generated-policies-ng20.adoc b/modules/test-generated-policies-ng20.adoc new file mode 100644 index 000000000000..7b3634665edb --- /dev/null +++ b/modules/test-generated-policies-ng20.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="test-generated-policies-ng20_{context}"] += Testing generated policies in the network graph + +After you download the network policies that {product-title-short} generates, you can test them by applying them to your cluster by using the CLI or your automated deployment procedures. You cannot apply generated network policies directly in the network graph. + +.Procedure +. To create policies using the saved YAML file, run the following command: ++ +[source,terminal] +---- +$ oc create -f "<generated_file>.yml" <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +. If the generated policies cause problems, you can remove them by running the following command: ++ +[source,terminal] +---- +$ oc delete -f "<generated_file>.yml" <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +[WARNING] +==== +Directly applying network policies might cause problems for running applications. +Always download and test the network policies in a development environment or test clusters before applying them to production workloads. +==== \ No newline at end of file diff --git a/modules/threescale-backend-cache.adoc b/modules/threescale-backend-cache.adoc deleted file mode 100644 index 3ca71e957426..000000000000 --- a/modules/threescale-backend-cache.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="threescale-backend-cache_{context}"] -= 3scale backend cache - -The 3scale backend cache provides an authorization and reporting cache for clients of the 3scale Service Management API. This cache is embedded in the adapter to enable lower latencies in responses in certain situations assuming the administrator is willing to accept the trade-offs. - -NOTE: 3scale backend cache is disabled by default. 3scale backend cache functionality trades inaccuracy in rate limiting and potential loss of hits since the last flush was performed for low latency and higher consumption of resources in the processor and memory. - -== Advantages of enabling backend cache - -The following are advantages to enabling the backend cache: - -* Enable the backend cache when you find latencies are high while accessing services managed by the 3scale Istio Adapter. -* Enabling the backend cache will stop the adapter from continually checking with the 3scale API manager for request authorizations, which will lower the latency. -** This creates an in-memory cache of 3scale authorizations for the 3scale Istio Adapter to store and reuse before attempting to contact the 3scale API manager for authorizations. Authorizations will then take much less time to be granted or denied. -* Backend caching is useful in cases when you are hosting the 3scale API manager in another geographical location from the service mesh running the 3scale Istio Adapter. -** This is generally the case with the 3scale Hosted (SaaS) platform, but also if a user hosts their 3scale API manager in another cluster located in a different geographical location, in a different availability zone, or in any case where the network overhead to reach the 3scale API manager is noticeable. - - -== Trade-offs for having lower latencies - -The following are trade-offs for having lower latencies: - -* Each 3scale adapter's authorization state updates every time a flush happens. -** This means two or more instances of the adapter will introduce more inaccuracy between flushing periods. -** There is a greater chance of too many requests being granted that exceed limits and introduce erratic behavior, which leads to some requests going through and some not, depending on which adapter processes each request. -* An adapter cache that cannot flush its data and update its authorization information risks shut down or crashing without reporting its information to the API manager. -* A fail open or fail closed policy will be applied when an adapter cache cannot determine whether a request must be granted or denied, possibly due to network connectivity issues in contacting the API manager. -* When cache misses occur, typically right after booting the adapter or after a long period of no connectivity, latencies will grow in order to query the API manager. -* An adapter cache must do much more work on computing authorizations than it would without an enabled cache, which will tax processor resources. -* Memory requirements will grow proportionally to the combination of the amount of limits, applications, and services managed by the cache. - -== Backend cache configuration settings - -The following points explain the backend cache configuration settings: - -* Find the settings to configure the backend cache in the 3scale configuration options. -* The last 3 settings control enabling of backend cache: -** `PARAM_USE_CACHE_BACKEND` - set to true to enable backend cache. -** `PARAM_BACKEND_CACHE_FLUSH_INTERVAL_SECONDS` - sets time in seconds between consecutive attempts to flush cache data to the API manager. -** `PARAM_BACKEND_CACHE_POLICY_FAIL_CLOSED` - set whether or not to allow/open or deny/close requests to the services when there is not enough cached data and the 3scale API manager cannot be reached. diff --git a/modules/threescale-istio-adapter-apicast.adoc b/modules/threescale-istio-adapter-apicast.adoc deleted file mode 100644 index 75852d1a912a..000000000000 --- a/modules/threescale-istio-adapter-apicast.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * service_mesh/v1x/threescale_adapter/threescale-adapter.adoc -// * service_mesh/v2x/threescale_adapter/threescale-adapter.adoc - -[id="threescale-istio-adapter-apicast_{context}"] -= 3scale Istio Adapter APIcast emulation - -The 3scale Istio Adapter performs as APIcast would when the following conditions occur: - -* When a request cannot match any mapping rule defined, the returned HTTP code is 404 Not Found. This was previously 403 Forbidden. -* When a request is denied because it goes over limits, the returned HTTP code is 429 Too Many Requests. This was previously 403 Forbidden. -* When generating default templates via the CLI, it will use underscores rather than dashes for the headers, for example: `user_key` rather than `user-key`. diff --git a/modules/tokens-scoping-about.adoc b/modules/tokens-scoping-about.adoc deleted file mode 100644 index d13286376a6a..000000000000 --- a/modules/tokens-scoping-about.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/tokens-scoping.adoc - -[id="tokens-scoping-about_{context}"] -= About scoping tokens - -You can created scoped tokens to delegate some of your permissions to another -user or service account. -For example, a project administrator might want to delegate the -power to create pods. - -A scoped token is a token that identifies as a given user but is limited to -certain actions by its scope. Only a user with the `cluster-admin` role can create -scoped tokens. - -Scopes are evaluated by converting the set of scopes for a token into a set of -`PolicyRules`. Then, the request is matched against those rules. The request -attributes must match at least one of the scope rules to be passed to the -"normal" authorizer for further authorization checks. - -[id="scoping-tokens-user-scopes_{context}"] -== User scopes - -User scopes are focused on getting information about a given user. They are -intent-based, so the rules are automatically created for you: - -* `user:full` - Allows full read/write access to the API with all of the user's permissions. -* `user:info` - Allows read-only access to information about the user, such as name and groups. -* `user:check-access` - Allows access to `self-localsubjectaccessreviews` and `self-subjectaccessreviews`. - These are the variables where you pass an empty user and groups in your request object. -* `user:list-projects` - Allows read-only access to list the projects the user has access to. - - -[id="scoping-tokens-role-scope_{context}"] -== Role scope -The role scope allows you to have the same level of access as a given role -filtered by namespace. - -* `role:<cluster-role name>:<namespace or * for all>` - Limits the scope to the -rules specified by the cluster-role, but only in the specified namespace . -+ -[NOTE] -==== -Caveat: This prevents escalating access. Even if the role allows access to -resources like secrets, rolebindings, and roles, this scope will deny access -to those resources. This helps prevent unexpected escalations. Many people do -not think of a role like `edit` as being an escalating role, but with access to -a secret it is. -==== - -* `role:<cluster-role name>:<namespace or * for all>:!` - This is similar to the -example above, except that including the bang causes this scope to allow -escalating access. diff --git a/modules/top-risky-images-components.adoc b/modules/top-risky-images-components.adoc new file mode 100644 index 000000000000..5730d1415ffb --- /dev/null +++ b/modules/top-risky-images-components.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="top-risky-images-components_{context}"] += Identifying top riskiest images and components by using the dashboard + +Similar to the *Top Risky*, the *Top Riskiest* widget lists the names of the top riskiest images and components. +This widget also includes the total number of CVEs and the number of fixable CVEs in the listed images. + +.Procedure + +. Go to the {product-title-short} portal and click *Vulnerability Management* from the navigation menu. +. Select the *Top Riskiest Images* widget header to choose between the riskiest images and components. +If you are viewing *Top Riskiest Images*: +** When you hover over an image in the list, you see an overview of the image, which includes image name, scan time, and the number of CVEs along with severity (critical, high, medium, and low). +** When you select an image, the *Image* view opens for the selected image. +The *Image* view shows in-depth details of the image and includes information about CVEs by CVSS score, top riskiest components, fixable CVEs, and Dockerfile for the image. +. Select *View All* on the widget header to view all objects of the chosen type. +For example, if you chose *Top Riskiest Components*, you can select *View All* to view detailed information about all components in your infrastructure. diff --git a/modules/topology-manager-policies.adoc b/modules/topology-manager-policies.adoc deleted file mode 100644 index 0da806f481bf..000000000000 --- a/modules/topology-manager-policies.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * scaling_and_performance/using-topology-manager.adoc -// * post_installation_configuration/node-tasks.adoc - -[id="topology_manager_policies_{context}"] -= Topology Manager policies - -Topology Manager aligns `Pod` resources of all Quality of Service (QoS) classes by collecting topology hints from Hint Providers, such as CPU Manager and Device Manager, and using the collected hints to align the `Pod` resources. - -[NOTE] -==== -To align CPU resources with other requested resources in a `Pod` spec, the CPU Manager must be enabled with the `static` CPU Manager policy. -==== - -Topology Manager supports four allocation policies, which you assign in the `cpumanager-enabled` custom resource (CR): - -`none` policy:: - -This is the default policy and does not perform any topology alignment. - -`best-effort` policy:: - -For each container in a pod with the `best-effort` topology management policy, kubelet calls each Hint Provider to discover their resource -availability. Using this information, the Topology Manager stores the preferred NUMA Node affinity for that container. If the affinity is not preferred, Topology Manager stores this and admits the pod to the node. - -`restricted` policy:: - -For each container in a pod with the `restricted` topology management policy, kubelet calls each Hint Provider to discover their resource -availability. Using this information, the Topology Manager stores the preferred NUMA Node affinity for that container. If the affinity is not -preferred, Topology Manager rejects this pod from the node, resulting in a pod in a `Terminated` state with a pod admission failure. - -`single-numa-node` policy:: - -For each container in a pod with the `single-numa-node` topology management policy, kubelet calls each Hint Provider to discover their resource availability. Using this information, the Topology Manager determines if a single NUMA Node affinity is possible. If it is, the pod is admitted to the node. If a single NUMA Node affinity is not possible, the Topology Manager rejects the pod from the node. This results in a pod in a Terminated state with a pod admission failure. diff --git a/modules/topology.png b/modules/topology.png deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/modules/tracking-the-compliance-status-of-your-environment.adoc b/modules/tracking-the-compliance-status-of-your-environment.adoc new file mode 100644 index 000000000000..20c095a289e3 --- /dev/null +++ b/modules/tracking-the-compliance-status-of-your-environment.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="tracking-the-compliance-status-of-your-environment_{context}"] += Tracking the compliance status of your environment + +By generating compliance reports, you can keep a track of the compliance status of your environment. You can use these reports to convey compliance status across various industry mandates to other stakeholders. + +You can generate the following reports: + +Executive reports:: Focuses on the business aspect and include charts and a summary of the compliance status in PDF format. +Evidence reports:: Focuses on the technical aspect and contain detailed information in CSV format. + +.Procedure + +. In the {product-title-short} portal, click *Compliance -> Dashboard*. +. Click the *Export* tab to do any of the following tasks: +** To generate an executive report, select *Download Page as PDF*. +** To generate an evidence report, select *Download Evidence as CSV*. ++ +[TIP] +==== +The *Export* option appears on all compliance pages and filtered views. +==== \ No newline at end of file diff --git a/modules/traffic-splitting-kn.adoc b/modules/traffic-splitting-kn.adoc deleted file mode 100644 index 09d7971c5fe5..000000000000 --- a/modules/traffic-splitting-kn.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/knative_serving/splitting-traffic-between-revisions-knative.adoc - -[id="traffic-splitting-kn_{context}"] -= Traffic mapping and splitting using `kn` - -`kn` provides commands that help you to control traffic mapping and how traffic is split between revisions. - -You can use the `kn service update` command with the `--traffic` flag to update the traffic. This flag uses the following syntax: - -[source,terminal] ----- ---traffic RevisionName=Percent ----- - -where -* The `--traffic` flag requires two values separated by separated by an equals sign (`=`). -* The `RevisionName` string refers to the name of the revision. -* `Percent` integer denotes the traffic portion assigned to the revision. - -[IMPORTANT] -==== -The `--traffic` flag can be specified multiple times in one command, and is valid only if the sum of the `Percent` values in all flags totals 100. -==== - -.Procedure - -* Update the percentage of traffic to be routed to a revision: -+ -[source,terminal] ----- -$ kn service update --traffic <@revision_name>=<percent_integer> ----- -+ -[NOTE] -==== -You can use the identifier `@latest` for the revision name, to refer to the latest ready revision of the service. You can use this identifier only once per command with the `--traffic` flag. -==== diff --git a/modules/troubleshoot-jira-integration.adoc b/modules/troubleshoot-jira-integration.adoc new file mode 100644 index 000000000000..4eb7068a70b5 --- /dev/null +++ b/modules/troubleshoot-jira-integration.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-jira.adoc +:_mod-docs-content-type: PROCEDURE +[id="troubleshoot-jira-integration_{context}"] += Troubleshooting Jira integration + +[role="_abstract"] +If you are using custom priorities or mandatory custom fields in your Jira project, you may get an error when you try to integrate {product-title} with Jira Software. +This error might be because of the mismatch between the severity and the priority field values. + +If you do not know the custom priority values in your JIRA project, use the `roxctl` CLI to enable debug logging for JIRA integration. + +.Procedure +. To get the custom priority values from your JIRA project, run the following command to turn on debug logging for JIRA integration: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level Debug --modules notifiers/jira +---- +. Follow the instructions to configure {product-title} for Jira integration. When you test the integration, even if the integration test fails, the generated log includes your JIRA project schema and the custom priorities. +. To save the debugging information as a compressed `.zip` file, run the following command: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump +---- +. Unzip the `.zip` file to retrieve the custom priority values in use in your JIRA project. +. To turn off debug logging, run the following command: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level Info +---- +. Configure {product-title} for Jira integration again and use the priority values to configure custom priorities. diff --git a/modules/troubleshoot-the-splunk-add-on.adoc b/modules/troubleshoot-the-splunk-add-on.adoc new file mode 100644 index 000000000000..323d69005fe7 --- /dev/null +++ b/modules/troubleshoot-the-splunk-add-on.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-splunk.adoc +:_mod-docs-content-type: CONCEPT +[id="troubleshoot-the-splunk-add-on_{context}"] += Troubleshoot the Splunk add-on + +[role="_abstract"] +If you stop receiving events from the {product-title} add-on, check the Splunk add-on debug logs for errors. + +Splunk creates a debug log file for every configured input in the `/opt/splunk/var/log/splunk` directory. Find the file named `stackrox_<input>_<uid>.log`, for example, `stackrox_compliance_29a3e14798aa2363d.log` and look for issues. diff --git a/modules/troubleshooting-cluster-upgrader.adoc b/modules/troubleshooting-cluster-upgrader.adoc new file mode 100644 index 000000000000..4fc59075fdf3 --- /dev/null +++ b/modules/troubleshooting-cluster-upgrader.adoc @@ -0,0 +1,76 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="troubleshooting-upgrader_{context}"] += Troubleshooting the cluster upgrader + +[role="_abstract"] +If you encounter problems when using the legacy installation method for the secured cluster and enabling the automated updates, you can try troubleshooting the problem. +The following errors can be found in the clusters view when the upgrader fails. + +[id="upgrader-missing-permissions_{context}"] +== Upgrader is missing permissions + +.Symptom + +The following error is displayed in the cluster page: + +[source,text] +---- +Upgrader failed to execute PreflightStage of the roll-forward workflow: executing stage "Run preflight checks": preflight check "Kubernetes authorization" reported errors. This usually means that access is denied. Have you configured this Secured Cluster for automatically receiving upgrades?" +---- + +.Procedure + +. Ensure that the bundle for the secured cluster was generated with future upgrades enabled before clicking *Download YAML file and keys*. +. If possible, remove that secured cluster and generate a new bundle making sure that future upgrades are enabled. +. If you cannot re-create the cluster, you can take these actions: +.. Ensure that the service account `sensor-upgrader` exists in the same namespace as Sensor. +.. Ensure that a ClusterRoleBinding exists (default name: `<namespace>:upgrade-sensors`) that grants the `cluster-admin` ClusterRole to the `sensor-upgrader` service account. + +[id="upgrader-cannot-start-missing-image_{context}"] +== Upgrader cannot start due to missing image + +.Symptom + +The following error is displayed in the cluster page: + +[source,text] +---- +"Upgrade initialization error: The upgrader pods have trouble pulling the new image: Error pulling image: (...) (<image_reference:tag>: not found)" +---- + +.Procedure + +. Ensure that the Secured Cluster can access the registry and pull the image `<image_reference:tag>`. +. Ensure that the image pull secrets are configured correctly in the secured cluster. + +[id="upgrader-cannot-start-unknown-reason_{context}"] +== Upgrader cannot start due to an unknown reason + +.Symptom + +The following error is displayed in the cluster page: + +[source,text] +---- +"Upgrade initialization error: Pod terminated: (Error)" +---- + +.Procedure + +. Ensure that the upgrader has enough permissions for accessing the cluster objects. For more information, see "Upgrader is missing permissions". +. Check the upgrader logs for more insights. + +[id="obtainig-upgrader-logs_{context}"] +=== Obtaining upgrader logs + +The logs can be accessed by running the following command: +[source,terminal,subs="+quotes"] +---- +$ kubectl -n <namespace> logs deploy/sensor-upgrader <1> +---- +<1> For `_<namespace>_`, specify the namespace in which Sensor is running. + +Usually, the upgrader deployment is only running in the cluster for a short time while doing the upgrades. It is removed later, so accessing its logs using the orchestrator CLI can require proper timing. diff --git a/modules/troubleshooting-disabling-autoreboot-mco-cli.adoc b/modules/troubleshooting-disabling-autoreboot-mco-cli.adoc deleted file mode 100644 index f83d3f68c51b..000000000000 --- a/modules/troubleshooting-disabling-autoreboot-mco-cli.adoc +++ /dev/null @@ -1,141 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-operator-issues.adoc - -[id="troubleshooting-disabling-autoreboot-mco-cli_{context}"] -= Disabling the Machine Config Operator from automatically rebooting by using the CLI - -To avoid unwanted disruptions from changes made by the Machine Config Operator (MCO), you can modify the machine config pool (MCP) using the OpenShift CLI (oc) to prevent the MCO from making any changes to nodes in that pool. This prevents any reboots that would normally be part of the MCO update process. - -[NOTE] -==== -Pausing an MCP stops all updates to your {op-system} nodes, including updates to the operating system, security, certificate, as well as any other updates related to the machine config. Pausing should be done for short periods of time only. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -To pause or unpause automatic MCO update rebooting: - -* Pause the autoreboot process: - -. Update the `MachineConfigPool` custom resource to set the `spec.paused` field to `true`. -+ -.Control plane (master) nodes -[source,terminal] ----- -$ oc patch --type=merge --patch='{"spec":{"paused":true}}' machineconfigpool/master ----- -+ -.Worker nodes -[source,terminal] ----- -$ oc patch --type=merge --patch='{"spec":{"paused":true}}' machineconfigpool/worker ----- - -. Verify that the MCP is paused: -+ -.Control plane (master) nodes -[source,terminal] ----- -$ oc get machineconfigpool/master --template='{{.spec.paused}}' ----- -+ -.Worker nodes -[source,terminal] ----- -$ oc get machineconfigpool/worker --template='{{.spec.paused}}' ----- -+ -.Example output -[source,terminal] ----- -true ----- -+ -The `spec.paused` field is `true` and the MCP is paused. - -. Determine if the MCP has pending changes: -+ -[source,terminal] ----- -# oc get machineconfigpool ----- -+ -.Example output ----- -NAME CONFIG UPDATED UPDATING -master rendered-master-33cf0a1254318755d7b48002c597bf91 True False -worker rendered-worker-e405a5bdb0db1295acea08bcca33fa60 False False ----- -+ -If the *UPDATED* column is *False* and *UPDATING* is *False*, there are pending changes. When *UPDATED* is *True* and *UPDATING* is *False*, there are no pending changes. In the previous example, the worker node has pending changes. The master node does not have any pending changes. -+ -[IMPORTANT] -==== -If there are pending changes (where both the *Updated* and *Updating* columns are *False*), it is recommended to schedule a maintenance window for a reboot as early as possible. Use the following steps for unpausing the autoreboot process to apply the changes that were queued since the last reboot. -==== - -* Unpause the autoreboot process: - -. Update the `MachineConfigPool` custom resource to set the `spec.paused` field to `false`. -+ -.Control plane (master) nodes -[source,terminal] ----- -$ oc patch --type=merge --patch='{"spec":{"paused":false}}' machineconfigpool/master ----- -+ -.Worker nodes -[source,terminal] ----- -$ oc patch --type=merge --patch='{"spec":{"paused":false}}' machineconfigpool/worker ----- -+ -[NOTE] -==== -By unpausing an MCP, the MCO applies all paused changes and reboots {op-system-first} as needed. -==== -+ -. Verify that the MCP is unpaused: -+ -.Control plane (master) nodes -[source,terminal] ----- -$ oc get machineconfigpool/master --template='{{.spec.paused}}' ----- -+ -.Worker nodes -[source,terminal] ----- -$ oc get machineconfigpool/worker --template='{{.spec.paused}}' ----- -+ -.Example output -[source,terminal] ----- -false ----- -+ -The `spec.paused` field is `false` and the MCP is unpaused. - -. Determine if the MCP has pending changes: -+ -[source,terminal] ----- -$ oc get machineconfigpool ----- -+ -.Example output ----- -NAME CONFIG UPDATED UPDATING -master rendered-master-546383f80705bd5aeaba93 True False -worker rendered-worker-b4c51bb33ccaae6fc4a6a5 False True ----- -+ -If the MCP is applying any pending changes, the *UPDATED* column is *False* and the *UPDATING* column is *True*. When *UPDATED* is *True* and *UPDATING* is *False*, there are no further changes being made. In the previous example, the MCO is updating the worker node. - diff --git a/modules/troubleshooting-disabling-autoreboot-mco-console.adoc b/modules/troubleshooting-disabling-autoreboot-mco-console.adoc deleted file mode 100644 index ad6ded29ca48..000000000000 --- a/modules/troubleshooting-disabling-autoreboot-mco-console.adoc +++ /dev/null @@ -1,92 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-operator-issues.adoc - -[id="troubleshooting-disabling-autoreboot-mco-console_{context}"] -= Disabling the Machine Config Operator from automatically rebooting by using the console - -To avoid unwanted disruptions from changes made by the Machine Config Operator (MCO), you can use the {product-title} web console to modify the machine config pool (MCP) to prevent the MCO from making any changes to nodes in that pool. This prevents any reboots that would normally be part of the MCO update process. - -[NOTE] -==== -Pausing an MCP stops all updates to your {op-system} nodes, including updates to the operating system, security, certificate, and any other updates related to the machine config. Pausing should be done for short periods of time only. -==== - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -To pause or unpause automatic MCO update rebooting: - -* Pause the autoreboot process: - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Click *Compute* -> *Machine Config Pools*. - -. On the *Machine Config Pools* page, click either *master* or *worker*, depending upon which nodes you want to pause rebooting for. - -. On the *master* or *worker* page, click *YAML*. - -. In the YAML, update the `spec.paused` field to `true`. -+ -.Sample MachineConfigPool object -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool - ... -spec: - ... - paused: true <1> ----- -<1> Update the `spec.paused` field to `true` to pause rebooting. - -. To verify that the MCP is paused, return to the *Machine Config Pools* page. -+ -On the *Machine Config Pools* page, the *Paused* column reports *True* for the MCP you modified. -+ -If the MCP has pending changes while paused, the *Updated* column is *False* and *Updating* is *False*. When *Updated* is *True* and *Updating* is *False*, there are no pending changes. -+ -[IMPORTANT] -==== -If there are pending changes (where both the *Updated* and *Updating* columns are *False*), it is recommended to schedule a maintenance window for a reboot as early as possible. Use the following steps for unpausing the autoreboot process to apply the changes that were queued since the last reboot. -==== - -* Unpause the autoreboot process: - -. Log in to the {product-title} web console as a user with the `cluster-admin` role. - -. Click *Compute* -> *Machine Config Pools*. - -. On the *Machine Config Pools* page, click either *master* or *worker*, depending upon which nodes you want to pause rebooting for. - -. On the *master* or *worker* page, click *YAML*. - -. In the YAML, update the `spec.paused` field to `false`. -+ -.Sample MachineConfigPool object -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfigPool - ... -spec: - ... - paused: false <1> ----- -<1> Update the `spec.paused` field to `false` to allow rebooting. -+ -[NOTE] -==== -By unpausing an MCP, the MCO applies all paused changes reboots {op-system-first} as needed. -==== - -. To verify that the MCP is paused, return to the *Machine Config Pools* page. -+ -On the *Machine Config Pools* page, the *Paused* column reports *False* for the MCP you modified. -+ -If the MCP is applying any pending changes, the *Updated* column is *False* and the *Updating* column is *True*. When *Updated* is *True* and *Updating* is *False*, there are no further changes being made. - diff --git a/modules/troubleshooting-disabling-autoreboot-mco.adoc b/modules/troubleshooting-disabling-autoreboot-mco.adoc deleted file mode 100644 index ba02165639db..000000000000 --- a/modules/troubleshooting-disabling-autoreboot-mco.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-operator-issues.adoc - -[id="troubleshooting-disabling-autoreboot-mco_{context}"] -= Disabling the Machine Config Operator from automatically rebooting - -When configuration changes are made by the Machine Config Operator (MCO), {op-system-first} must reboot for the changes to take effect. Whether the configuration change is automatic, such as when a `kube-apiserver-to-kubelet-signer` certificate authority (CA) is rotated, or manual, an {op-system} node reboots automatically unless it is paused. - -[NOTE] -==== -The following modifications do not trigger a node reboot: - -* changes to the SSH key in the `spec.config.ignition.passwd.users.sshAuthorizedKeys` parameter of a machine config -* changes to the global pull secret or pull secret in the `openshift-config` namespace -* changes to the `/etc/containers/registries.conf` file, such as adding or editing an `ImageContentSourcePolicy` object - -When the MCO detects any of these changes, it drains the corresponding nodes, applies the changes, and uncordons the nodes. -==== - -To avoid unwanted disruptions, you can modify the machine config pool (MCP) to prevent automatic rebooting after the Operator makes changes to the machine config. - -[NOTE] -==== -Pausing a machine config pool stops all system reboot processes and all configuration changes from being applied. -==== - diff --git a/modules/troubleshooting-openshift-install-command-issues.adoc b/modules/troubleshooting-openshift-install-command-issues.adoc deleted file mode 100644 index 27ac72f1d42e..000000000000 --- a/modules/troubleshooting-openshift-install-command-issues.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="troubleshooting-openshift-install-command-issues_{context}"] -= Troubleshooting `openshift-install` command issues - -If you experience issues running the `openshift-install` command, check the following: - -* The installation has been initiated within 24 hours of Ignition configuration file creation. The Ignition files are created when the following command is run: -+ -[source,terminal] ----- -$ ./openshift-install create ignition-configs --dir=./install_dir ----- - -* The `install-config.yaml` file is in the same directory as the installer. If an alternative installation path is declared by using the `./openshift-install --dir` option, verify that the `install-config.yaml` file exists within that directory. diff --git a/modules/trust-cert-existing-sensor.adoc b/modules/trust-cert-existing-sensor.adoc new file mode 100644 index 000000000000..bcbac25e81e1 --- /dev/null +++ b/modules/trust-cert-existing-sensor.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * configuration/add-custom-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="trust-cert-existing-sensor_{context}"] += Configuring an existing Sensor to trust custom certificates + +.Prerequisites + +* You have downloaded the Sensor bundle. + +.Procedure + +. Unzip the Sensor bundle: ++ +[source,terminal] +---- +$ unzip -d sensor sensor-<cluster_name>.zip +---- +. Run the following command to create the secret: ++ +[source,terminal] +---- +$ ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ <1> +---- +<1> Use the `-d` option to specify a directory containing custom certificates. ++ +[NOTE] +==== +If you get the "secret already exists" error message, re-run the script with the `-u` option: + +[source,terminal] +---- +$ ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u +---- +==== +. Continue Sensor deployment by using the YAML files. diff --git a/modules/trust-cert-new-sensor.adoc b/modules/trust-cert-new-sensor.adoc new file mode 100644 index 000000000000..91f887d50b19 --- /dev/null +++ b/modules/trust-cert-new-sensor.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * configuration/add-custom-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="trust-cert-new-sensor_{context}"] += Configuring Sensor to trust custom certificates when deploying a new Sensor + +.Prerequisites + +* You have downloaded the Sensor bundle. + +.Procedure + +* If you are using the `sensor.sh` script: ++ +. Unzip the Sensor bundle: ++ +[source,terminal] +---- +$ unzip -d sensor sensor-<cluster_name>.zip +---- +. Run the `sensor.sh` script: ++ +[source,terminal] +---- +$ ./sensor/sensor.sh +---- ++ +The certificates are automatically applied when you run the sensor (`./sensor/sensor.sh`) script. +You can also place additional custom certificates in the `sensor/additional-cas/` directory before you run the `sensor.sh` script. +* If you are not using the `sensor.sh` script: ++ +. Unzip the Sensor bundle: ++ +[source,terminal] +---- +$ unzip -d sensor sensor-<cluster_name>.zip +---- +. Run the following command to create the secret: ++ +[source,terminal] +---- +$ ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ <1> +---- +<1> Use the `-d` option to specify a directory containing custom certificates. ++ +[NOTE] +==== +If you get the "secret already exists" error message, re-run the script with the `-u` option: + +[source,terminal] +---- +$ ./sensor/ca-setup-sensor.sh -d sensor/additional-cas/ -u +---- +==== +. Continue Sensor deployment by using the YAML files. diff --git a/modules/unable-to-connect-to-the-sensor.adoc b/modules/unable-to-connect-to-the-sensor.adoc new file mode 100644 index 000000000000..4d8cc718831a --- /dev/null +++ b/modules/unable-to-connect-to-the-sensor.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * troubleshooting/commonly-occurring-error-conditions.adoc +:_mod-docs-content-type: PROCEDURE +[id="unable-to-connect-to-the-sensor_{context}"] += Unable to connect to the Sensor + +When starting, first check if you can connect to Sensor. Sensor is responsible for downloading kernel drivers and CIDR blocks for processing network events, making it an essential part of the startup process. The following logs indicate you are unable to connect to the Sensor: + +[source,terminal] +---- +Collector Version: 3.15.0 +OS: Ubuntu 20.04.4 LTS +Kernel Version: 5.4.0-126-generic +[...] +[INFO 2023/05/13 12:20:43] Sensor configured at address: sensor.stackrox.svc:9998 +[INFO 2023/05/13 12:20:43] Attempting to connect to Sensor +[INFO 2023/05/13 12:21:13] +[INFO 2023/05/13 12:21:13] == Collector Startup Diagnostics: == +[INFO 2023/05/13 12:21:13] Connected to Sensor? false +[INFO 2023/05/13 12:21:13] Kernel driver candidates: +[INFO 2023/05/13 12:21:13] ==================================== +[INFO 2023/05/13 12:21:13] +[FATAL 2023/05/13 12:21:13] Unable to connect to Sensor at 'sensor.stackrox.svc:9998'. +---- + +This error could mean that Sensor has not started correctly or that Collector configuration is incorrect. To fix this issue, you must verify Collector configuration to ensure that Sensor address is correct and that the Sensor pod is running correctly. + + +View the Collector logs to specifically check the configured Sensor address. Alternatively, you can run the following command: + +[source,terminal,subs="+quotes"] +---- +$ kubectl -n stackrox get pod _<collector_pod_name>_ -o jsonpath='{.spec.containers[0].env[?(@.name=="GRPC_SERVER")].value}' <1> +---- + +<1> For `_<collector_pod_name>_`, specify the name of your Collector pod, for example, `collector-vclg5`. \ No newline at end of file diff --git a/modules/unavailability-of-the-kernel-driver.adoc b/modules/unavailability-of-the-kernel-driver.adoc new file mode 100644 index 000000000000..c96201884fc1 --- /dev/null +++ b/modules/unavailability-of-the-kernel-driver.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * troubleshooting/commonly-occurring-error-conditions.adoc +:_mod-docs-content-type: CONCEPT +[id="unavailability-of-the-kernel-driver_{context}"] += Unavailability of the kernel driver + +Collector determines if it has a kernel driver for the node's kernel version. Collector first searches the local storage for a driver with the correct version and type, and then attempts to download the driver from Sensor. The following logs indicate that neither a local kernel driver nor a driver from Sensor is present: + +[source,terminal] +---- +Collector Version: 3.15.0 +OS: Alpine Linux v3.16 +Kernel Version: 5.15.82-0-virt +Starting StackRox Collector... +[INFO 2023/05/30 12:00:33] Hostname: 'alpine' +[INFO 2023/05/30 12:00:33] User configured collection-method=ebpf +[INFO 2023/05/30 12:00:33] Afterglow is enabled +[INFO 2023/05/30 12:00:33] Sensor configured at address: sensor.stackrox.svc:443 +[INFO 2023/05/30 12:00:33] Attempting to connect to Sensor +[INFO 2023/05/30 12:00:33] Successfully connected to Sensor. +[INFO 2023/05/30 12:00:33] Module version: 2.5.0-rc1 +[INFO 2023/05/30 12:00:33] Config: collection_method:0, useChiselCache:1, scrape_interval:30, turn_off_scrape:0, hostname:alpine, processesListeningOnPorts:1, logLevel:INFO +[INFO 2023/05/30 12:00:33] Attempting to find eBPF probe - Candidate versions: +[INFO 2023/05/30 12:00:33] collector-ebpf-5.15.82-0-virt.o +[INFO 2023/05/30 12:00:33] Attempting to download collector-ebpf-5.15.82-0-virt.o +[INFO 2023/05/30 12:00:33] Attempting to download kernel object from https://sensor.stackrox.svc:443/kernel-objects/2.5.0/collector-ebpf-5.15.82-0-virt.o.gz <1> +[INFO 2023/05/30 12:00:33] HTTP Request failed with error code 404 <2> +[WARNING 2023/05/30 12:02:03] Attempted to download collector-ebpf-5.15.82-0-virt.o.gz 90 time(s) +[WARNING 2023/05/30 12:02:03] Failed to download from collector-ebpf-5.15.82-0-virt.o.gz +[WARNING 2023/05/30 12:02:03] Unable to download kernel object collector-ebpf-5.15.82-0-virt.o to /module/collector-ebpf.o.gz +[WARNING 2023/05/30 12:02:03] No suitable kernel object downloaded for collector-ebpf-5.15.82-0-virt.o +[ERROR 2023/05/30 12:02:03] Failed to initialize collector kernel components. +[INFO 2023/05/30 12:02:03] +[INFO 2023/05/30 12:02:03] == Collector Startup Diagnostics: == +[INFO 2023/05/30 12:02:03] Connected to Sensor? true +[INFO 2023/05/30 12:02:03] Kernel driver candidates: +[INFO 2023/05/30 12:02:03] collector-ebpf-5.15.82-0-virt.o (unavailable) +[INFO 2023/05/30 12:02:03] ==================================== +[INFO 2023/05/30 12:02:03] +[FATAL 2023/05/30 12:02:03] Failed to initialize collector kernel components. <3> +---- + +<1> The logs display attempts to locate the module first, followed by any efforts to download the driver from Sensor. +<2> The 404 errors indicate that the node's kernel does not have a kernel driver. +<3> As a result of missing a driver, Collector enters the `CrashLoopBackOff` state. + +The link:https://github.com/stackrox/collector/blob/master/kernel-modules/KERNEL_VERSIONS[Kernel versions] file contains a list of all supported kernel versions. diff --git a/modules/understand-admission-controller-enforcement.adoc b/modules/understand-admission-controller-enforcement.adoc new file mode 100644 index 000000000000..f0d7705c6f9b --- /dev/null +++ b/modules/understand-admission-controller-enforcement.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="understand-admission-controller-enforcement_{context}"] += Understanding admission controller enforcement + +If you intend to use admission controller enforcement, consider the following: + +* *API latency*: Using admission controller enforcement increases Kubernetes or {ocp} API latency because it involves additional API validation requests. +Many standard Kubernetes libraries, such as fabric8, have short Kubernetes or {ocp} API timeouts by default. +Also, consider API timeouts in any custom automation you might be using. If a request does time out due to latency issues, the admission controller will _fail open_, or allow the request to reach the API server. +* *Image scanning*: You can choose whether the admission controller scans images while reviewing requests by setting the *Contact Image Scanners* option in the cluster configuration panel. +** If you enable this setting, {product-title} contacts the image scanners if the scan or image signature verification results are not already available, which adds considerable latency. +** If you disable this setting, the enforcement decision only considers image scan criteria if cached scan and signature verification results are available. +* You can use admission controller enforcement for: +** Options in the pod `securityContext` +** Deployment configurations +** Image components and vulnerabilities +* You cannot use admission controller enforcement for the following items: +** Any runtime behavior, such as processes +** Any policies based on port exposure +* The admission controller might fail if there are connectivity issues between the Kubernetes or {ocp} API server and {product-title-short} Sensor. +To resolve this issue, delete the `ValidatingWebhookConfiguration` object as described in "Disabling admission controller enforcement". +//link to Disable admission controller enforcement +* If you have deploy stage enforcement enabled for a policy and you enable the admission controller, {product-title-short} attempts to block deployments that violate the policy. +If a noncompliant deployment is not rejected by the admission controller, for example, in case of a timeout, {product-title-short} still applies other deploy stage enforcement mechanisms, such as scaling to zero replicas. diff --git a/modules/understanding-connectivity-explanations.adoc b/modules/understanding-connectivity-explanations.adoc new file mode 100644 index 000000000000..eea8826be6df --- /dev/null +++ b/modules/understanding-connectivity-explanations.adoc @@ -0,0 +1,71 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: CONCEPT +[id="understanding-connectivity-explanations_{context}"] += Understanding Connectivity Explanations + +[role="_abstract"] +To understand precisely which parts of your Kubernetes network policy YAML files are responsible for allowing or denying connections, you can use the `roxctl netpol connectivity map` command which includes an explainability mode. +You can debug and refine your network policies by using the explainability mode which provides additional details beyond the standard connectivity report. + +As a developer or DevOps professional, you might encounter situations where a connection you expect to be open is denied, or you need to confirm which specific rules allow the connection. + +The following are examples of some common issues: + +* Mismatched ingress and egress rules, where one side of a connection allows traffic but the other denies it. +* Typographical errors that cause policies to open different ports or protocols than intended. + +The explainability mode provides insights into how each side of a connection is affected by your policy rules. You can quickly identify the configuration mistakes by using the explainability mode. + +== Example allowed connections + +Consider that you have a Kubernetes cluster with the following components: + +* A *Monitoring service* called `monitoring-service` that collects data from various applications. +* A core *Internal application A* called `internal-app-a` that actively exposes monitoring endpoints and needs monitoring. +* A network policy configuration that defines Admin Network Policy (ANP) to `pass` connections from monitoring into namespaces with label `security: internal`, and a specific Network Policy (NP) that explicitly allows connections from `monitoring-service` into `internal-app-a`. + +You can see the YAML manifest for this example at link:https://github.com/np-guard/netpol-analyzer/tree/0ac857e19bfab4b281ca9bdfb2bbc5ea319b5065/tests/anp_banp_explain_demo[`netpol-analyzer/tests/anp_banp_explain_demo/`]. + +To analyze the network policies and provides an explanation for each connection, you can run the `roxctl netpol connectivity map --explain` command on this setup. + +The explainability output for allowed connections from the `monitoring-service` deployment for such configuration shows: + +[source,terminal] +---- +Connections between monitoring/monitoring-service[Pod] => internal-apps/internal-app-a[Pod]: +Allowed connections: + Allowed TCP, UDP, SCTP due to the following policies and rules: + Egress (Allowed) due to the system default (Allow all) + Ingress (Allowed) + AdminNetworkPolicy 'pass-monitoring' passes connections by Ingress rule pass-ingress-from-monitoring + NetworkPolicy 'internal-apps/allow-monitoring' allows connections by Ingress rule #1 +---- + +In this example, the connection from `monitoring/monitoring-service` to `internal-apps/internal-app-a` is allowed by the combination of ANP `pass-monitoring` that applies broadly on all namespaces with the label `security: internal` and a more specific NP `internal-apps/allow-monitoring` tailored for `internal-app-a`. The output shows that multiple policies can contribute to allowing a connection. + +== Example blocked connections + +Consider an isolated data service `isolated-data-service` which denies all external access by default for security reasons. + +You can see the YAML manifest for this example at link:https://github.com/np-guard/netpol-analyzer/tree/7ab6bbd421d3d80cbfff7cd1529ff8caf0137fbc/tests/anp_banp_explain_demo_2[`netpol-analyzer/tests/anp_banp_explain_demo_2/`]. + +To analyze the network policies and provides an explanation for each connection, you can run the `roxctl netpol connectivity map --explain` command on this setup. + +The explainability output for blocked connections from the `monitoring-service` deployment to this workload shows: + +[source,terminal] +---- +Connections between monitoring/monitoring-service[Pod] => isolated-apps/isolated-data-service[Pod]: + +Denied connections: + Denied TCP, UDP, SCTP due to the following policies and rules: + Egress (Allowed) due to the system default (Allow all) + Ingress (Denied) + AdminNetworkPolicy 'pass-monitoring' passes connections by Ingress rule pass-ingress-from-monitoring + BaselineAdminNetworkPolicy 'default' denies connections by Ingress rule deny-ingress-from-monitoring +---- + +In this example, the connection to `data/isolated-data-service` is blocked by a combination of ANP with Pass action, and of BANP that denies all connections from `monitoring` by default. diff --git a/modules/understanding-control-plane.adoc b/modules/understanding-control-plane.adoc deleted file mode 100644 index ae9e3be3a2bd..000000000000 --- a/modules/understanding-control-plane.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture.adoc - -[id="understanding-control-plane_{context}"] -= Understanding the {product-title} control plane - -The control plane, which is composed of master machines, manages the -{product-title} cluster. The control plane machines manage workloads on the -compute machines, which are also known as worker machines. The cluster itself manages all upgrades to the -machines by the actions of the Cluster Version Operator, the -Machine Config Operator, and a set of individual Operators. diff --git a/modules/understanding-filtering-to-policy-mapping.adoc b/modules/understanding-filtering-to-policy-mapping.adoc new file mode 100644 index 000000000000..4234cb5603ee --- /dev/null +++ b/modules/understanding-filtering-to-policy-mapping.adoc @@ -0,0 +1,229 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="understanding-filtering-to-policy-mapping_{context}"] += Understanding how {product-title} transforms the filtering criteria into policy criteria + +When you create new security policies from the *Risk* view, based on the filtering criteria you use, not all criteria are directly applied to the new policy. + +* {product-title} converts the *Cluster*, *Namespace*, and *Deployment* filters to equivalent policy scopes. +** Local page filtering on the *Risk* view combines the search terms by using the following methods: + +*** Combines the search terms within the same category with an `OR` operator. +For example, if the search query is `Cluster:A,B`, the filter matches deployments in `cluster A` or `cluster B`. +*** Combines the search terms from different categories with an `AND` operator. +For example, if the search query is `Cluster:A+Namespace:Z`, the filter matches deployments in `cluster A` and in `namespace Z`. +** When you add multiple scopes to a policy, the policy matches violations from any of the scopes. +*** For example, if you search for `(Cluster A OR Cluster B) AND (Namespace Z)` it results in two policy scopes, `(Cluster=A AND Namespace=Z)` OR `(Cluster=B AND Namespace=Z)`. +* {product-title} drops or modifies filters that do not directly map to policy criteria and reports the dropped filters. + +The following table lists how the filtering search attributes map to the policy criteria: + +|=== +| Search attribute | Policy criteria + +| Add Capabilities +| Add Capabilities + +| Annotation +| Disallowed Annotation + +| CPU Cores Limit +| Container CPU Limit + +| CPU Cores Request +| Container CPU Request + +| CVE +| CVE + +| CVE Published On +| ✕ Dropped + +| CVE Snoozed +| ✕ Dropped + +| CVSS +| CVSS + +| Cluster +| ⟳ Converted to scope + +| Component +| Image Component (name) + +| Component Version +| Image Component (version) + +| Deployment +| ⟳ Converted to scope + +| Deployment Type +| ✕ Dropped + +| Dockerfile Instruction Keyword +| Dockerfile Line (key) + +| Dockerfile Instruction Value +| Dockerfile Line (value) + +| Drop Capabilities +| ✕ Dropped + +| Environment Key +| Environment Variable (key) + +| Environment Value +| Environment Variable (value) + +| Environment Variable Source +| Environment Variable (source) + +| Exposed Node Port +| ✕ Dropped + +| Exposing Service +| ✕ Dropped + +| Exposing Service Port +| ✕ Dropped + +| Exposure Level +| Port Exposure + +| External Hostname +| ✕ Dropped + +| External IP +| ✕ Dropped + +| Image +| ✕ Dropped + +| Image Command +| ✕ Dropped + +| Image Created Time +| Days since image was created + +| Image Entrypoint +| ✕ Dropped + +| Image Label +| Disallowed Image Label + +| Image OS +| Image OS + +| Image Pull Secret +| ✕ Dropped + +| Image Registry +| Image Registry + +| Image Remote +| Image Remote + +| Image Scan Time +| Days since image was last scanned + +| Image Tag +| Image Tag + +| Image Top CVSS +| ✕ Dropped + +| Image User +| ✕ Dropped + +| Image Volumes +| ✕ Dropped + +| Label +| ⟳ Converted to scope + +| Max Exposure Level +| ✕ Dropped + +| Memory Limit (MB) +| Container Memory Limit + +| Memory Request (MB) +| Container Memory Request + +| Namespace +| ⟳ Converted to scope + +| Namespace ID +| ✕ Dropped + +| Pod Label +| ✕ Dropped + +| Port +| Port + +| Port Protocol +| Protocol + +| Priority +| ✕ Dropped + +| Privileged +| Privileged + +| Process Ancestor +| Process Ancestor + +| Process Arguments +| Process Arguments + +| Process Name +| Process Name + +| Process Path +| ✕ Dropped + +| Process Tag +| ✕ Dropped + +| Process UID +| Process UID + +| Read Only Root Filesystem +| Read-Only Root Filesystem + +| Secret +| ✕ Dropped + +| Secret Path +| ✕ Dropped + +| Service Account +| ✕ Dropped + +| Service Account Permission Level +| Minimum RBAC Permission Level + +| Toleration Key +| ✕ Dropped + +| Toleration Value +| ✕ Dropped + +| Volume Destination +| Volume Destination + +| Volume Name +| Volume Name + +| Volume ReadOnly +| Writable Volume + +| Volume Source +| Volume Source + +| Volume Type +| Volume Type +|=== diff --git a/modules/understanding-machine-config-operator.adoc b/modules/understanding-machine-config-operator.adoc deleted file mode 100644 index 60b9e84dbbdd..000000000000 --- a/modules/understanding-machine-config-operator.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/control-plane.adoc -[id="understanding-machine-config-operator_{context}"] -= Understanding the Machine Config Operator - -{product-title} {product-version} integrates both -operating system and cluster management. Because the cluster manages its own -updates, including updates to {op-system-first} on cluster nodes, -{product-title} provides an opinionated lifecycle management -experience that simplifies the orchestration of node upgrades. - -{product-title} employs three daemon sets and controllers to -simplify node management. These daemon sets orchestrate operating system updates -and configuration changes to the hosts by using standard Kubernetes-style -constructs. They include: - -* The `machine-config-controller`, which coordinates machine upgrades from the control -plane. It monitors all of the cluster nodes and orchestrates their configuration -updates. -* The `machine-config-daemon` daemon set, which runs on -each node in the cluster and updates a machine to configuration as defined by -machine config and as instructed by the MachineConfigController. When the node detects -a change, it drains off its pods, applies the update, and reboots. These changes -come in the form of Ignition configuration files that apply the specified -machine configuration and control kubelet configuration. The update itself is -delivered in a container. This process is key to the success of managing -{product-title} and {op-system} updates together. -* The `machine-config-server` daemon set, which provides the Ignition config files -to control plane nodes as they join the cluster. - -The machine configuration is a subset of the Ignition configuration. The -`machine-config-daemon` reads the machine configuration to see if it needs to do -an OSTree update or if it must apply a series of systemd kubelet file changes, -configuration changes, or other changes to the operating system or {product-title} -configuration. - -When you perform node management operations, you create or modify a -`KubeletConfig` custom resource (CR). -//See https://github.com/openshift/machine-config-operator/blob/master/docs/KubeletConfigDesign.md[KubeletConfigDesign] for details. - -[IMPORTANT] -==== -When changes are made to a machine configuration, the Machine Config Operator (MCO) automatically reboots all corresponding nodes in order for the changes to take effect. - -To prevent the nodes from automatically rebooting after machine configuration changes, before making the changes, you must pause the autoreboot process by setting the `spec.paused` field to `true` in the corresponding machine config pool. When paused, machine configuration changes are not applied until you set the `spec.paused` field to `false` and the nodes have rebooted into the new configuration. - -The following modifications do not trigger a node reboot: - -* changes to the SSH key in the `spec.config.ignition.passwd.users.sshAuthorizedKeys` parameter of a machine config -* changes to the global pull secret or pull secret in the `openshift-config` namespace -* changes to the `/etc/containers/registries.conf` file, such as adding or editing an `ImageContentSourcePolicy` object - -When the MCO detects any of these changes, it drains the corresponding nodes, applies the changes, and uncordons the nodes. -==== - diff --git a/modules/understanding-node-cves-scanner-v4.adoc b/modules/understanding-node-cves-scanner-v4.adoc new file mode 100644 index 000000000000..ff0c4de9453b --- /dev/null +++ b/modules/understanding-node-cves-scanner-v4.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: CONCEPT +// DO NOT RENAME THE ID - there are UI links using it in ACS +[id="understanding-node-cves-scanner-v4_{context}"] += Understanding differences in scanning results between the Stackrox Scanner and Scanner V4 + +Scanning {op-system} node hosts with Scanner V4 reports significantly more CVEs for the same operating system version. For example, Scanner V4 reports about 390 CVEs, compared to about 50 CVEs that are reported by StackRox Scanner. A manual review of selected vulnerabilities revealed the following causes: + +* The Vulnerability Exploitability eXchange (VEX) data used in Scanner V4 is more accurate. +* The VEX data includes granular statuses, such as "no fix planned" and "fix deferred". +* Some vulnerabilities reported by StackRox Scanner were false positives. + +As a result, Scanner V4 provides a more accurate and realistic vulnerability assessment. + +Users might find discrepancies in reported vulnerabilities surprising, especially if some secured clusters still use older {product-title-short} versions with StackRox Scanner while others use Scanner V4. To help you understand this difference, the following example provides an explanation and guidance on how to manually verify reported vulnerabilities. + +== Example of discrepancies in reported vulnerabilities + +In this example, we analyzed the differences in reported CVEs for three arbitrarily selected {op-system} versions. This example presents findings for {op-system} version `417.94.202501071621-0`. +For this version, {product-title-short} provided the following scan results: + +* StackRox Scanner reported 49 CVEs. +* Scanner V4 reported 389 CVEs. + +The breakdown is as follows: + +* 1 CVE is reported only by the StackRox Scanner. +* 48 CVEs are reported by both scanners. +* 341 CVEs are reported only by Scanner V4. + +=== CVEs reported only by the StackRox Scanner + +The single CVE reported exclusively by StackRox Scanner was a false positive. CVE-2022-4122 was flagged for the `podman` package in version `5:5.2.2-1.rhaos4.17.el9.x86_64`. However, a manual review of VEX data from link:https://access.redhat.com/errata/RHSA-2024:9102[RHSA-2024:9102] indicated that this vulnerability was fixed in version `5:5.2.2-1.el9`. Therefore, the package version scanned was the first to contain the fix and was no longer affected. + +=== CVEs reported only by Scanner V4 + +We randomly selected 10 CVEs from the 341 unique to Scanner V4 and conducted a detailed analysis using VEX data. The vulnerabilities fell into two categories: + +* Affected packages with a fine-grained status indicating that no fix is planned +* Affected packages with no additional status details regarding a fix + +For example, the following results were analyzed: + +* The `git-core` package (version `2.43.5-1.el9_4`) was flagged for CVE-2024-50349 (link:https://access.redhat.com/security/cve/cve-2024-50349[VEX data]) and marked as "Affected" with a fine-grained status of "Fix deferred." This means a fix is not guaranteed due to higher-priority development work. The package is affected by three CVEs in total. + +* The `vim-minimal` package (version `2:8.2.2637-20.el9_1`) was flagged for 109 CVEs, 108 of which have low CVSS scores. Most are marked as "Affected" with a fine-grained status of "Will not fix." + +* The `krb5-libs` package (version `1.21.1-2.el9_4.1`) was flagged for CVE-2025-24528 (link:https://access.redhat.com/security/cve/cve-2025-24528[VEX data]), but no fine-grained status was available. Given that this CVE was recently discovered at the time of this analysis, its status might be updated soon. + +=== CVEs reported by both scanners + +We manually verified three randomly selected packages, finding that the OVAL v2 data used in the StackRox Scanner and the VEX data used in Scanner V4 provided consistent explanations for the detected CVEs. In some cases, CVSS scores differed slightly, which is expected due to variations in VEX publisher data. + +== Verifying the status of vulnerabilities + +As a best practice, verify the fine-grained statuses of vulnerabilities in node host components that are critical to your environment using publicly available VEX data. VEX data is accessible in both human-readable and machine-readable formats. For more information about interpreting VEX data, visit link:https://www.redhat.com/en/blog/recent-improvements-red-hat-enterprise-linux-coreos-security-data[Recent improvements in Red Hat Enterprise Linux CoreOS security data]. \ No newline at end of file diff --git a/modules/understanding-oc-log-levels.adoc b/modules/understanding-oc-log-levels.adoc deleted file mode 100644 index 04b1a9f695c3..000000000000 --- a/modules/understanding-oc-log-levels.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/diagnosing-oc-issues.adoc - -[id="understanding-oc-log-levels_{context}"] -= Understanding OpenShift CLI (`oc`) log levels - -With the OpenShift CLI (`oc`), you can create applications and manage {product-title} projects from a terminal. - -If `oc` command-specific issues arise, increase the `oc` log level to output API request, API response, and `curl` request details generated by the command. This provides a granular view of a particular `oc` command's underlying operation, which in turn might provide insight into the nature of a failure. - -`oc` log levels range from 1 to 10. The following table provides a list of `oc` log levels, along with their descriptions. - -.OpenShift CLI (`oc`) log levels -[cols="1,4",options="header"] -|=== -| Log level | Description - -| 1 to 5 -| No additional logging to stderr. - -| 6 -| Log API requests to stderr. - -| 7 -| Log API requests and headers to stderr. - -| 8 -| Log API requests, headers, and body, plus API response headers and body to stderr. - -| 9 -| Log API requests, headers, and body, API response headers and body, plus `curl` requests to stderr. - -| 10 -| Log API requests, headers, and body, API response headers and body, plus `curl` requests to stderr, in verbose detail. -|=== diff --git a/modules/understanding-platform-components.adoc b/modules/understanding-platform-components.adoc new file mode 100644 index 000000000000..2e793cca1a23 --- /dev/null +++ b/modules/understanding-platform-components.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * configuration/customizing-platform-components.adoc +:_mod-docs-content-type: CONCEPT +[id="understanding-platform-components_{context}"] += Understanding platform components + +{product-title-short} automatically identify platform components by built-in definitions. However, with {product-title-short} 4.8 and newer, you can view and customize these definitions, providing more granular control over how {product-title-short} categorizes security findings. + +When viewing violations and vulnerabilities in RHACS, they are categorized as either **User workloads** or **Platform**. This distinction helps you understand the scope and responsibility for addressing security findings. + +**User workloads** include violations and vulnerabilities that affect the applications and images you deploy and manage in your system. + +**Platform** includes violations and vulnerabilities related to the platform itself, such as those in workloads and images deployed by {ocp} and layered services. Platform components are currently defined using entire namespaces, and RHACS uses regular expression patterns to specify such namespaces. + +You can view the platform components definition in the {product-title-short} portal by going to **Platform Configuration** > **System Configuration**. + +The **Platform components configuration** section lists platform components in the following categories: + +* **Core system components**: These components are part of the core {ocp} and Kubernetes namespaces. {product-title-short} includes them in the platform definition by default. You cannot customize these definitions. These definitions might change when you upgrade the system. +* **Red{nbsp}Hat layered products**: Components found in Red{nbsp}Hat layered and partner product namespaces are included in the platform definition by default. Ensure that you update the definition if you install Red{nbsp}Hat products, including {product-title-short}, into a non-default namespace. +* **Custom components**: You can extend the platform definition by defining namespaces for additional applications and products. You can use it to classify other namespaces as **Platform**, such as third-party applications, to exclude them from the focused **User workloads** views. diff --git a/modules/understanding-pod-error-states.adoc b/modules/understanding-pod-error-states.adoc deleted file mode 100644 index adad1a9e0c13..000000000000 --- a/modules/understanding-pod-error-states.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/investigating-pod-issues.adoc - -[id="understanding-pod-error-states_{context}"] -= Understanding pod error states - -Pod failures return explicit error states that can be observed in the `status` field in the output of `oc get pods`. Pod error states cover image, container, and container network related failures. - -The following table provides a list of pod error states along with their descriptions. - -.Pod error states -[cols="1,4",options="header"] -|=== -| Pod error state | Description - -| `ErrImagePull` -| Generic image retrieval error. - -| `ErrImagePullBackOff` -| Image retrieval failed and is backed off. - -| `ErrInvalidImageName` -| The specified image name was invalid. - -| `ErrImageInspect` -| Image inspection did not succeed. - -| `ErrImageNeverPull` -| `PullPolicy` is set to `NeverPullImage` and the target image is not present locally on the host. - -| `ErrRegistryUnavailable` -| When attempting to retrieve an image from a registry, an HTTP error was encountered. - -| `ErrContainerNotFound` -| The specified container is either not present or not managed by the kubelet, within the declared pod. - -| `ErrRunInitContainer` -| Container initialization failed. - -| `ErrRunContainer` -| None of the pod's containers started successfully. - -| `ErrKillContainer` -| None of the pod's containers were killed successfully. - -| `ErrCrashLoopBackOff` -| A container has terminated. The kubelet will not attempt to restart it. - -| `ErrVerifyNonRoot` -| A container or image attempted to run with root privileges. - -| `ErrCreatePodSandbox` -| Pod sandbox creation did not succeed. - -| `ErrConfigPodSandbox` -| Pod sandbox configuration was not obtained. - -| `ErrKillPodSandbox` -| A pod sandbox did not stop successfully. - -| `ErrSetupNetwork` -| Network initialization failed. - -| `ErrTeardownNetwork` -| Network termination failed. -|=== diff --git a/modules/understanding-quick-start-elements.adoc b/modules/understanding-quick-start-elements.adoc deleted file mode 100644 index d8348169bbd7..000000000000 --- a/modules/understanding-quick-start-elements.adoc +++ /dev/null @@ -1,163 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="understanding-quick-start-elements_{context}"] -= Mapping the elements in the quick start to the quick start CR - -This section helps you visually map parts of the quick start custom resource (CR) with where they appear in the quick start within the web console. - -[id="conclusion-quick-start-element_{context}"] -== conclusion element - -.Viewing the conclusion element in the YAML file -[source,yaml] ----- -... -summary: - failed: Try the steps again. - success: Your Spring application is running. -title: Run the Spring application -conclusion: >- -Your Spring application is deployed and ready. <1> ----- -<1> conclusion text - -.Viewing the conclusion element in the web console - -The conclusion appears in the last section of the quick start. - -image::quick-start-conclusion.png[quick start conclusion in the web console] - -[id="description-quick-start-element_{context}"] -== description element - -.Viewing the description element in the YAML file -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleQuickStart -metadata: - name: spring-with-s2i -spec: - description: 'Import a Spring Application from git, build, and deploy it onto OpenShift.' <1> -... ----- -<1> description text - -.Viewing the description element in the web console - -The description appears on the introductory tile of the quick start on the *Quick Starts* page. - -image::quick-start-description.png[quick start description in the web console] - - -[id="displayName-quick-start-element_{context}"] -== displayName element - -.Viewing the displayName element in the YAML file - -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleQuickStart -metadata: - name: spring-with-s2i -spec: - description: 'Import a Spring Application from git, build, and deploy it onto OpenShift.' - displayName: Get started with Spring <1> - durationMinutes: 10 ----- -<1> `displayName` text. - -.Viewing the displayName element in the web console - -The display name appears on the introductory tile of the quick start on the *Quick Starts* page. - -image::quick-start-display-name.png[quick start display name in the web console] - -[id="duration-minutes-quick-start-element_{context}"] -== durationMinutes element - -.Viewing the durationMinutes element in the YAML file - -[source,yaml] ----- -apiVersion: console.openshift.io/v1 -kind: ConsoleQuickStart -metadata: - name: spring-with-s2i -spec: - description: 'Import a Spring Application from git, build, and deploy it onto OpenShift.' - displayName: Get started with Spring - durationMinutes: 10 <1> ----- -<1> `durationMinutes` value, in minutes. This value defines how long the quick start should take to complete. - -.Viewing the durationMinutes element in the web console - -The duration minutes element appears on the introductory tile of the quick start on the *Quick Starts* page. - -image::quick-start-duration.png[quick start durationMinutes element in the web console] - -[id="icon-quick-start-element_{context}"] -== icon element - -.Viewing the icon element in the YAML file - -[source,yaml] ----- -... -spec: - description: 'Import a Spring Application from git, build, and deploy it onto OpenShift.' - displayName: Get started with Spring - durationMinutes: 10 - icon: >- <1> - data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGlkPSJMYXllcl8xIiBkYXRhLW5hbWU9IkxheWVyIDEiIHZpZXdCb3g9IjAgMCAxMDI0IDEwMjQiPjxkZWZzPjxzdHlsZT4uY2xzLTF7ZmlsbDojMTUzZDNjO30uY2xzLTJ7ZmlsbDojZDhkYTlkO30uY2xzLTN7ZmlsbDojNThjMGE4O30uY2xzLTR7ZmlsbDojZmZmO30uY2xzLTV7ZmlsbDojM2Q5MTkxO308L3N0eWxlPjwvZGVmcz48dGl0bGU+c25vd2Ryb3BfaWNvbl9yZ2JfZGVmYXVsdDwvdGl0bGU+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMTAxMi42OSw1OTNjLTExLjEyLTM4LjA3LTMxLTczLTU5LjIxLTEwMy44LTkuNS0xMS4zLTIzLjIxLTI4LjI5LTM5LjA2LTQ3Ljk0QzgzMy41MywzNDEsNzQ1LjM3LDIzNC4xOCw2NzQsMTY4Ljk0Yy01LTUuMjYtMTAuMjYtMTAuMzEtMTUuNjUtMTUuMDdhMjQ2LjQ5LDI0Ni40OSwwLDAsMC0zNi41NS0yNi44LDE4Mi41LDE4Mi41LDAsMCwwLTIwLjMtMTEuNzcsMjAxLjUzLDIwMS41MywwLDAsMC00My4xOS0xNUExNTUuMjQsMTU1LjI0LDAsMCwwLDUyOCw5NS4yYy02Ljc2LS42OC0xMS43NC0uODEtMTQuMzktLjgxaDBsLTEuNjIsMC0xLjYyLDBhMTc3LjMsMTc3LjMsMCwwLDAtMzEuNzcsMy4zNSwyMDguMjMsMjA4LjIzLDAsMCwwLTU2LjEyLDE3LjU2LDE4MSwxODEsMCwwLDAtMjAuMjcsMTEuNzUsMjQ3LjQzLDI0Ny40MywwLDAsMC0zNi41NywyNi44MUMzNjAuMjUsMTU4LjYyLDM1NSwxNjMuNjgsMzUwLDE2OWMtNzEuMzUsNjUuMjUtMTU5LjUsMTcyLTI0MC4zOSwyNzIuMjhDOTMuNzMsNDYwLjg4LDgwLDQ3Ny44Nyw3MC41Miw0ODkuMTcsNDIuMzUsNTIwLDIyLjQzLDU1NC45LDExLjMxLDU5MywuNzIsNjI5LjIyLTEuNzMsNjY3LjY5LDQsNzA3LjMxLDE1LDc4Mi40OSw1NS43OCw4NTkuMTIsMTE4LjkzLDkyMy4wOWEyMiwyMiwwLDAsMCwxNS41OSw2LjUyaDEuODNsMS44Ny0uMzJjODEuMDYtMTMuOTEsMTEwLTc5LjU3LDE0My40OC0xNTUuNiwzLjkxLTguODgsNy45NS0xOC4wNSwxMi4yLTI3LjQzcTUuNDIsOC41NCwxMS4zOSwxNi4yM2MzMS44NSw0MC45MSw3NS4xMiw2NC42NywxMzIuMzIsNzIuNjNsMTguOCwyLjYyLDQuOTUtMTguMzNjMTMuMjYtNDkuMDcsMzUuMy05MC44NSw1MC42NC0xMTYuMTksMTUuMzQsMjUuMzQsMzcuMzgsNjcuMTIsNTAuNjQsMTE2LjE5bDUsMTguMzMsMTguOC0yLjYyYzU3LjItOCwxMDAuNDctMzEuNzIsMTMyLjMyLTcyLjYzcTYtNy42OCwxMS4zOS0xNi4yM2M0LjI1LDkuMzgsOC4yOSwxOC41NSwxMi4yLDI3LjQzLDMzLjQ5LDc2LDYyLjQyLDE0MS42OSwxNDMuNDgsMTU1LjZsMS44MS4zMWgxLjg5YTIyLDIyLDAsMCwwLDE1LjU5LTYuNTJjNjMuMTUtNjQsMTAzLjk1LTE0MC42LDExNC44OS0yMTUuNzhDMTAyNS43Myw2NjcuNjksMTAyMy4yOCw2MjkuMjIsMTAxMi42OSw1OTNaIi8+PHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMzY0LjE1LDE4NS4yM2MxNy44OS0xNi40LDM0LjctMzAuMTUsNDkuNzctNDAuMTFhMjEyLDIxMiwwLDAsMSw2NS45My0yNS43M0ExOTgsMTk4LDAsMCwxLDUxMiwxMTYuMjdhMTk2LjExLDE5Ni4xMSwwLDAsMSwzMiwzLjFjNC41LjkxLDkuMzYsMi4wNiwxNC41MywzLjUyLDYwLjQxLDIwLjQ4LDg0LjkyLDkxLjA1LTQ3LjQ0LDI0OC4wNi0yOC43NSwzNC4xMi0xNDAuNywxOTQuODQtMTg0LjY2LDI2OC40MmE2MzAuODYsNjMwLjg2LDAsMCwwLTMzLjIyLDU4LjMyQzI3Niw2NTUuMzQsMjY1LjQsNTk4LDI2NS40LDUyMC4yOSwyNjUuNCwzNDAuNjEsMzExLjY5LDI0MC43NCwzNjQuMTUsMTg1LjIzWiIvPjxwYXRoIGNsYXNzPSJjbHMtMyIgZD0iTTUyNy41NCwzODQuODNjODQuMDYtOTkuNywxMTYuMDYtMTc3LjI4LDk1LjIyLTIzMC43NCwxMS42Miw4LjY5LDI0LDE5LjIsMzcuMDYsMzEuMTMsNTIuNDgsNTUuNSw5OC43OCwxNTUuMzgsOTguNzgsMzM1LjA3LDAsNzcuNzEtMTAuNiwxMzUuMDUtMjcuNzcsMTc3LjRhNjI4LjczLDYyOC43MywwLDAsMC0zMy4yMy01OC4zMmMtMzktNjUuMjYtMTMxLjQ1LTE5OS0xNzEuOTMtMjUyLjI3QzUyNi4zMywzODYuMjksNTI3LDM4NS41Miw1MjcuNTQsMzg0LjgzWiIvPjxwYXRoIGNsYXNzPSJjbHMtNCIgZD0iTTEzNC41OCw5MDguMDdoLS4wNmEuMzkuMzksMCwwLDEtLjI3LS4xMWMtMTE5LjUyLTEyMS4wNy0xNTUtMjg3LjQtNDcuNTQtNDA0LjU4LDM0LjYzLTQxLjE0LDEyMC0xNTEuNiwyMDIuNzUtMjQyLjE5LTMuMTMsNy02LjEyLDE0LjI1LTguOTIsMjEuNjktMjQuMzQsNjQuNDUtMzYuNjcsMTQ0LjMyLTM2LjY3LDIzNy40MSwwLDU2LjUzLDUuNTgsMTA2LDE2LjU5LDE0Ny4xNEEzMDcuNDksMzA3LjQ5LDAsMCwwLDI4MC45MSw3MjNDMjM3LDgxNi44OCwyMTYuOTMsODkzLjkzLDEzNC41OCw5MDguMDdaIi8+PHBhdGggY2xhc3M9ImNscy01IiBkPSJNNTgzLjQzLDgxMy43OUM1NjAuMTgsNzI3LjcyLDUxMiw2NjQuMTUsNTEyLDY2NC4xNXMtNDguMTcsNjMuNTctNzEuNDMsMTQ5LjY0Yy00OC40NS02Ljc0LTEwMC45MS0yNy41Mi0xMzUuNjYtOTEuMThhNjQ1LjY4LDY0NS42OCwwLDAsMSwzOS41Ny03MS41NGwuMjEtLjMyLjE5LS4zM2MzOC02My42MywxMjYuNC0xOTEuMzcsMTY3LjEyLTI0NS42Niw0MC43MSw1NC4yOCwxMjkuMSwxODIsMTY3LjEyLDI0NS42NmwuMTkuMzMuMjEuMzJhNjQ1LjY4LDY0NS42OCwwLDAsMSwzOS41Nyw3MS41NEM2ODQuMzQsNzg2LjI3LDYzMS44OCw4MDcuMDUsNTgzLjQzLDgxMy43OVoiLz48cGF0aCBjbGFzcz0iY2xzLTQiIGQ9Ik04ODkuNzUsOTA4YS4zOS4zOSwwLDAsMS0uMjcuMTFoLS4wNkM4MDcuMDcsODkzLjkzLDc4Nyw4MTYuODgsNzQzLjA5LDcyM2EzMDcuNDksMzA3LjQ5LDAsMCwwLDIwLjQ1LTU1LjU0YzExLTQxLjExLDE2LjU5LTkwLjYxLDE2LjU5LTE0Ny4xNCwwLTkzLjA4LTEyLjMzLTE3My0zNi42Ni0yMzcuNHEtNC4yMi0xMS4xNi04LjkzLTIxLjdjODIuNzUsOTAuNTksMTY4LjEyLDIwMS4wNSwyMDIuNzUsMjQyLjE5QzEwNDQuNzksNjIwLjU2LDEwMDkuMjcsNzg2Ljg5LDg4OS43NSw5MDhaIi8+PC9zdmc+Cg== -... ----- -<1> The icon defined as a base64 value. - -.Viewing the icon element in the web console - -The icon appears on the introductory tile of the quick start on the *Quick Starts* page. - -image::quick-start-icon.png[quick start icon element in the web console] - -[id="introduction-quick-start-element_{context}"] -== introduction element - -.Viewing the introduction element in the YAML file - -[source,yaml] ----- -... - introduction: >- <1> - **Spring** is a Java framework for building applications based on a distributed microservices architecture. - - - Spring enables easy packaging and configuration of Spring applications into a self-contained executable application which can be easily deployed as a container to OpenShift. - - - Spring applications can integrate OpenShift capabilities to provide a natural "Spring on OpenShift" developer experience for both existing and net-new Spring applications. For example: - - - Externalized configuration using Kubernetes ConfigMaps and integration with Spring Cloud Kubernetes - - - Service discovery using Kubernetes Services - - - Load balancing with Replication Controllers - - - Kubernetes health probes and integration with Spring Actuator - - - Metrics: Prometheus, Grafana, and integration with Spring Cloud Sleuth - - - Distributed tracing with Istio & Jaeger tracing - - - Developer tooling through Red Hat OpenShift and Red Hat CodeReady developer tooling to quickly scaffold new Spring projects, gain access to familiar Spring APIs in your favorite IDE, and deploy to Red Hat OpenShift -... ----- -<1> The introduction introduces the quick start and lists the tasks within it. - -.Viewing the introduction element in the web console - -After clicking a quick start card, a side panel slides in that introduces the quick start and lists the tasks within it. - -image::quick-start-introduction.png[quick start introduction element in the web console] diff --git a/modules/understanding-quick-starts.adoc b/modules/understanding-quick-starts.adoc deleted file mode 100644 index 588f41fc9512..000000000000 --- a/modules/understanding-quick-starts.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/creating-quick-start-tutorials.adoc - -[id="understanding-quick-starts_{context}"] -= Understanding quick starts - -A quick start is a guided tutorial with user tasks. In the web console, you can access quick starts under the *Help* menu. They are especially useful for getting oriented with an application, Operator, or other product offering. - -A quick start primarily consists of tasks and steps. Each task has multiple steps, and each quick start has multiple tasks. For example: - -* Task 1 -** Step 1 -** Step 2 -** Step 3 -* Task 2 -** Step 1 -** Step 2 -** Step 3 -* Task 3 -** Step 1 -** Step 2 -** Step 3 diff --git a/modules/understanding-static-network-policy-connectivity-diff.adoc b/modules/understanding-static-network-policy-connectivity-diff.adoc new file mode 100644 index 000000000000..ce03a8ed71a1 --- /dev/null +++ b/modules/understanding-static-network-policy-connectivity-diff.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="analyzing-the-differences-in-network-policies_{context}"] += Analyzing the differences in network policies + +You can use the static network policy connectivity diff command to analyze two sets of Kubernetes manifests, including network policies. Specify two folders that contain deployment YAMLs and network policies. +The command then analyzes the allowed cluster connectivity for each input folder and generates a list of differences in the allowed connections. This is done based on the defined workloads and network policies. +This helps you create a file that visualizes the connectivity differences between two versions of workloads and network policy manifests. \ No newline at end of file diff --git a/modules/understanding-telemetry-and-insights-operator-data-flow.adoc b/modules/understanding-telemetry-and-insights-operator-data-flow.adoc deleted file mode 100644 index 0a7be2f24a27..000000000000 --- a/modules/understanding-telemetry-and-insights-operator-data-flow.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * support/remote_health_monitoring/about-remote-health-monitoring.adoc - -[id="understanding-telemetry-and-insights-operator-data-flow_{context}"] -= Understanding Telemetry and Insights Operator data flow - -The Telemeter Client collects selected time series data from the Prometheus API. The time series data is uploaded to api.openshift.com every four minutes and thirty seconds for processing. - -The Insights Operator gathers selected data from the Kubernetes API and the Prometheus API into an archive. The archive is uploaded to link:https://cloud.redhat.com[cloud.redhat.com] every two hours for processing. The Insights Operator also downloads the latest Insights analysis from link:https://cloud.redhat.com[cloud.redhat.com]. This is used to populate the *Insights status* pop-up that is included in the *Overview* page in the {product-title} web console. - -All of the communication with Red Hat occurs over encrypted channels by using Transport Layer Security (TLS) and mutual certificate authentication. All of the data is encrypted in transit and at rest. - -Access to the systems that handle customer data is controlled through multi-factor authentication and strict authorization controls. Access is granted on a need-to-know basis and is limited to required operations. - -.Telemetry and Insights Operator data flow -image:telmetry-and-insights-operator-data-flow.svg[Telemetry and Insights Operator data flow] \ No newline at end of file diff --git a/modules/understanding-upgrade-channels.adoc b/modules/understanding-upgrade-channels.adoc deleted file mode 100644 index 054afb80af98..000000000000 --- a/modules/understanding-upgrade-channels.adoc +++ /dev/null @@ -1,222 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-cluster.adoc -// * updating/updating-cluster-between-minor.adoc -// * updating/updating-cluster-cli.adoc -// * updating/updating-cluster-rhel-compute.adoc -// * updating/updating-disconnected-cluster.adoc - -[id="understanding-upgrade-channels_{context}"] -= {product-title} upgrade channels and releases - -In {product-title} 4.1, Red Hat introduced the concept of channels for -recommending the appropriate release versions for cluster upgrade. By controlling -the pace of upgrades, these upgrade channels allow you to choose an upgrade -strategy. Upgrade channels are tied to a minor version of -{product-title}. For instance, {product-title} 4.7 -upgrade channels will never include an upgrade to a 4.8 release. This strategy ensures that -administrators explicitly decide to upgrade to the next minor version of -{product-title}. Upgrade channels control only release selection and do not impact the version of the cluster that you install; the `openshift-install` -binary file for a specific version of {product-title} always installs that version. - -ifndef::openshift-origin[] -{product-title} {product-version} offers the following upgrade channels: - -* `candidate-{product-version}` -* `fast-{product-version}` -* `stable-{product-version}` -* `eus-4.6` (only available when running 4.6) - -endif::openshift-origin[] -ifdef::openshift-origin[] -{product-title} {product-version} offers the following upgrade channel: - -* `stable-4` - -endif::openshift-origin[] - -ifndef::openshift-origin[] -[discrete] -== candidate-{product-version} channel - -The `candidate-{product-version}` channel contains candidate builds for a z-stream -({product-version}.z) release. -Release candidates contain all the features of the product but are not supported. Use release candidate versions to test feature acceptance and assist in qualifying the next version -of {product-title}. -A release candidate is any build that is available in the candidate channel, including ones that do not contain link:https://semver.org/spec/v2.0.0.html#spec-item-9[a pre-release version] such as `-rc` in their names. -After a version is available in the candidate channel, it goes through more quality checks. If -it meets the quality standard, it is promoted to the `fast-{product-version}` or `stable-{product-version}` channels. -Because of this strategy, if a specific release is available in both the `candidate-{product-version}` channel and in the `fast-{product-version}` -or `stable-{product-version}` channels, it is a Red Hat supported version. -The `candidate-{product-version}` channel can include release versions from which there are no recommended updates in any channel. - -You can use the `candidate-{product-version}` channel to upgrade from a previous minor version of -{product-title}. - -[NOTE] -==== -Release candidates differ from the nightly builds. Nightly -builds are available for early access to features, but updating to or from nightly -builds is neither recommended nor supported. Nightly builds are not available in -any upgrade channel. You can reference the {product-title} -ifdef::openshift-origin[] -link:https://origin-release.apps.ci.l2s4.p1.openshiftapps.com/[release statuses] -endif::[] -ifndef::openshift-origin[] -link:https://openshift-release.apps.ci.l2s4.p1.openshiftapps.com/[release statuses] -endif::[] -for more build information. -==== - -[discrete] -== fast-{product-version} channel - -The `fast-{product-version}` channel is updated with new {product-version} -versions as soon as Red Hat declares the given version as a general availability -release. As such, these releases are fully supported, are production quality, and have -performed well while available as a release candidate in the `candidate-{product-version}` -channel from where they were promoted. Some time after a release appears in the -`fast-{product-version}` channel, it is added to the `stable-{product-version}` channel. Releases -never appear in the `stable-{product-version}` channel before they appear in the `fast-{product-version}` channel. - -You can use the `fast-{product-version}` channel to upgrade from a previous minor version of -{product-title}. -endif::openshift-origin[] - -ifndef::openshift-origin[] -[discrete] -== stable-{product-version} channel -While the `fast-{product-version}` channel contains releases as soon -as their errata are published, releases are added to the `stable-{product-version}` channel -after a delay. During this delay, data is collected from Red Hat SRE teams, Red Hat support services, -and pre-production and production environments that participate in connected customer program about the stability of the release. - -You can use the `stable-{product-version}` channel to upgrade from a previous minor version of -{product-title}. -endif::openshift-origin[] -ifdef::openshift-origin[] -[discrete] -== stable-4 channel -Releases are added to the `stable-4` channel -after passing all tests. - -You can use the `stable-4` channel to upgrade from a previous minor version of -{product-title}. -endif::openshift-origin[] - -ifndef::openshift-origin[] -[discrete] -== eus-4.6 channel - -In addition to the stable channel, certain minor versions of {product-title} offer an -link:https://access.redhat.com/support/policy/updates/openshift#ocp4_phases[Extended Update Support] (EUS). -These EUS versions extend the maintenance phase for customers with Premium Subscriptions -to 14 months. {product-title} 4.6 is currently the only minor version with EUS. - -Although there is no difference between stable-4.6 and eus-4.6 -channels until {product-title} 4.6 transitions to EUS the phase, you can switch -to the EUS channel as soon as it becomes available. When {product-title} 4.6 -transitions to the EUS phase of its lifecycle the stable-4.6 channel will -no longer receive subsequent z-stream updates. After you upgrade to a version that -is exclusive to the EUS channel, that cluster will no longer be eligible for minor -version upgrades until upgrades to the next EUS version become available. The next -planned EUS version is to be 4.10 and the upgrade to that version will require a -serial set of version upgrades, such as from 4.6 to 4.7 to 4.8 to 4.9 to 4.10. - -Additionally, you may only switch to the EUS channel when your cluster is running -a supported version of {product-title} 4.6. - -Finally, if you install of a 4.6 version that is exclusive to EUS, you will -similarly not be able to upgrade to a later minor version until upgrades are provided to 4.10. -endif::openshift-origin[] - -[discrete] -== Upgrade version paths - -{product-title} maintains an upgrade recommendation service that understands the -version of {product-title} you have installed as well as the path to take within -the channel you choose to get you to the next release. - -ifndef::openshift-origin[] -You can imagine seeing the following in the `fast-{product-version}` channel: -endif::openshift-origin[] -ifdef::openshift-origin[] -You can imagine seeing the following in the `stable-4` channel: -endif::openshift-origin[] - -* {product-version}.0 -* {product-version}.1 -* {product-version}.3 -* {product-version}.4 - -The service recommends only upgrades that have been tested and have no serious issues. -If your cluster is on {product-version}.1 and {product-title} suggests -{product-version}.4, then it is safe for you to update from {product-version}.1 to {product-version}.4. Do not rely on consecutive patch numbers. In this example, {product-version}.2 is not, and never was, available in the channel. The update service will not suggest updating to a version of {product-title} that contains known vulnerabilities. - -ifndef::openshift-origin[] -Update stability depends on your channel. The presence of an update recommendation in -the `candidate-{product-version}` channel does not imply that the update is supported. -It means that no serious issues have been found with the update yet, but there might -not be significant traffic through the update to suggest stability. The presence of -an update recommendation in the `fast-{product-version}` or `stable-{product-version}` -channels is a declaration that the update is fully supported while it is in the -channel. While releases will never be removed from a channel, update recommendations -that exhibit serious issues will be removed from all channels. Updates initiated -after the update recommendation has been removed might not be supported. - -Red Hat will eventually provide supported update paths from any supported release in the `fast-{product-version}` -or `stable-{product-version}` channels to the latest release in {product-version}.z, -although there can be delays while safe paths away from troubled releases are -constructed and verified. -endif::openshift-origin[] - -ifdef::openshift-origin[] -The presence of an update recommendation in the `stable-4` -channel is a declaration that the update is fully supported while it is in the -channel. While releases will never be removed from the channel, update recommendations -that exhibit serious issues will be removed from the channel. Updates initiated -after the update recommendation has been removed might not be supported. -endif::openshift-origin[] - -ifndef::openshift-origin[] -[discrete] -== Fast and stable channel use and strategies - -The `fast-{product-version}` and `stable-{product-version}` channels present a choice between receiving -general availability releases as soon as they are available or allowing Red Hat to -control the rollout of those updates. If issues are detected during rollout or at a -later time, upgrades to that version might be blocked in both the `fast-{product-version}` and -`stable-{product-version}` channels, and a new version might be introduced that becomes the new -preferred upgrade target. - -Customers can improve this process by configuring pre-production systems on the -`fast-{product-version}` channel, configuring production systems on the `stable-{product-version}` channel, -and participating in Red Hat’s connected customer program. Red -Hat uses this program to observe the impact of updates on your specific hardware and software -configurations. Future releases might improve or alter the pace at which updates move -from the `fast-{product-version}` to the `stable-{product-version}` channel. -endif::openshift-origin[] - -[discrete] -== Restricted network clusters - -If you manage the container images for your {product-title} clusters yourself, you must consult the Red Hat errata that is associated with product releases and note any comments that impact upgrades. -During upgrade, the user interface might warn you about switching between these versions, -so you must ensure that you selected an appropriate version before you bypass those warnings. - -ifndef::openshift-origin[] -[discrete] -== Switching between channels - -Your cluster is still supported if you change from the `stable-{product-version}` channel to -the `fast-{product-version}` channel. Although you can switch to the -`candidate-{product-version}` channel at any time, some releases in that channel might be unsupported release candidates. -You can switch from the `candidate-{product-version}` channel to the `fast-{product-version}` channel -if your current release is a general availability release. You can always -switch from the `fast-{product-version}` channel to the `stable-{product-version}` channel, although if the current release was recently promoted to -`fast-{product-version}` there can -be a delay of up to a day for the release to be promoted to -`stable-{product-version}`. If you change to a channel that does not include your -current release, an alert displays and no updates can be recommended, but you can -safely change back to your original channel at any point. -endif::openshift-origin[] diff --git a/modules/understanding-vulnerability-scores.adoc b/modules/understanding-vulnerability-scores.adoc new file mode 100644 index 000000000000..8613bcf58871 --- /dev/null +++ b/modules/understanding-vulnerability-scores.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/examine-images-for-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="understanding-understanding-vulnerability-scores_{context}"] += Understanding vulnerability scores in the dashboard + +[role="_abstract"] +The vulnerability management dashboard in the {product-title} portal shows a single Common Vulnerability Scoring System (CVSS) base score for each vulnerability. +{product-title-short} shows the CVSS score based on the following criteria: + +* If a CVSS v3 score is available, {product-title-short} shows the score and lists `v3` along with it. +For example, `6.5 (v3)`. ++ +[NOTE] +==== +CVSS v3 scores are only available if you are using the StackRox Scanner version 1.3.5 and later or Scanner V4. +==== + +* If a CVSS v3 score is not available, {product-title-short} might show only the CVSS v2 score. +For example, `6.5`. + +You can use the API to get the CVSS scores. +If CVSS v3 information is available for a vulnerability, the response might include both CVSS v3 and CVSS v2 information. \ No newline at end of file diff --git a/modules/uninstall-roxctl-cli.adoc b/modules/uninstall-roxctl-cli.adoc new file mode 100644 index 000000000000..9600835079f0 --- /dev/null +++ b/modules/uninstall-roxctl-cli.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-roxctl.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="uninstalling-cli-on-linux_{context}"] += Uninstalling the roxctl CLI + +You can uninstall the `roxctl` CLI binary on Linux by using the following procedure. + +.Procedure + +* Find and delete the `roxctl` binary: ++ +[source,terminal] +---- +$ ROXPATH=$(which roxctl) && rm -f $ROXPATH <1> +---- +<1> Depending on your environment, you might need administrator rights to delete the `roxctl` binary. diff --git a/modules/uninstalling-wmco.adoc b/modules/uninstalling-wmco.adoc deleted file mode 100644 index b2bf9bfbec5a..000000000000 --- a/modules/uninstalling-wmco.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/disabling-windows-container-workloads.adoc - -[id="uninstalling-wmco_{context}"] -= Uninstalling the Windows Machine Config Operator - -You can uninstall the Windows Machine Config Operator (WMCO) from your cluster. - -.Prerequisites - -* Delete the Windows `Machine` objects hosting your Windows workloads. - -.Procedure - -. From the *Operators -> OperatorHub* page, use the *Filter by keyword* box to search for `Red Hat Windows Machine Config Operator`. - -. Click the *Red Hat Windows Machine Config Operator* tile. The Operator tile indicates it is installed. - -. In the *Windows Machine Config Operator* descriptor page, click *Uninstall*. diff --git a/modules/unmanaged-operators.adoc b/modules/unmanaged-operators.adoc deleted file mode 100644 index 95def22db4d0..000000000000 --- a/modules/unmanaged-operators.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture-installation.adoc -// * updating/updating-cluster-between-minor.adoc - -[id="unmanaged-operators_{context}"] -= Support policy for unmanaged Operators - -The _management state_ of an Operator determines whether an Operator is actively -managing the resources for its related component in the cluster as designed. If -an Operator is set to an _unmanaged_ state, it does not respond to changes in -configuration nor does it receive updates. - -While this can be helpful in non-production clusters or during debugging, -Operators in an unmanaged state are unsupported and the cluster administrator -assumes full control of the individual component configurations and upgrades. - -An Operator can be set to an unmanaged state using the following methods: - -* **Individual Operator configuration** -+ -Individual Operators have a `managementState` parameter in their configuration. -This can be accessed in different ways, depending on the Operator. For example, -the Cluster Logging Operator accomplishes this by modifying a custom resource -(CR) that it manages, while the Cluster Samples Operator uses a cluster-wide -configuration resource. -+ -Changing the `managementState` parameter to `Unmanaged` means that the Operator -is not actively managing its resources and will take no action related to the -related component. Some Operators might not support this management state as it -might damage the cluster and require manual recovery. -+ -[WARNING] -==== -Changing individual Operators to the `Unmanaged` state renders that particular -component and functionality unsupported. Reported issues must be reproduced in -`Managed` state for support to proceed. -==== - -* **Cluster Version Operator (CVO) overrides** -+ -The `spec.overrides` parameter can be added to the CVO's configuration to allow -administrators to provide a list of overrides to the CVO's behavior for a -component. Setting the `spec.overrides[].unmanaged` parameter to `true` for a -component blocks cluster upgrades and alerts the administrator after a CVO -override has been set: -+ -[source,terminal] ----- -Disabling ownership via cluster version overrides prevents upgrades. Please remove overrides before continuing. ----- -+ -[WARNING] -==== -Setting a CVO override puts the entire cluster in an unsupported state. Reported -issues must be reproduced after removing any overrides for support to proceed. -==== diff --git a/modules/unsnooze-cves-vm20.adoc b/modules/unsnooze-cves-vm20.adoc new file mode 100644 index 000000000000..d00bba95038a --- /dev/null +++ b/modules/unsnooze-cves-vm20.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="unsnooze-cves-vm20_{context}"] += Unsnoozing platform and node CVEs + +[role="_abstract"] +You can unsnooze platform and node CVEs that you have previously snoozed. + +[NOTE] +==== +The ability to snooze a CVE is not enabled by default in the web portal or in the API. To enable the ability to snooze CVEs, set the runtime environment variable `ROX_VULN_MGMT_LEGACY_SNOOZE` to `true`. +==== + +.Procedure + +. In the {product-title-short} portal, do any of the following tasks: +* To view the list of platform CVEs, click *Vulnerability Management* -> *Platform CVEs*. +* To view the list of node CVEs, click *Vulnerability Management* -> *Node CVEs*. +. To view the list of snoozed CVEs, click *Show snoozed CVEs* in the header view. +. Select one or more CVEs from the list of snoozed CVEs. +. Select the appropriate method to unsnooze the CVE: +* If you selected a single CVE, click the overflow menu, {kebab}, and then select *Unsnooze CVE*. +* If you selected multiple CVEs, click *Bulk actions* -> *Unsnooze CVEs*. +. Click *Unsnooze CVEs* again. ++ +You receive a confirmation that you have requested to unsnooze the CVEs. diff --git a/modules/unused-kubernetes-roles.adoc b/modules/unused-kubernetes-roles.adoc new file mode 100644 index 000000000000..9ed69447e2a7 --- /dev/null +++ b/modules/unused-kubernetes-roles.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/review-cluster-configuration.adoc +:experimental: +:_mod-docs-content-type: PROCEDURE +[id="unused-kubernetes-roles_{context}"] += Finding unused Kubernetes roles + +[role="_abstract"] +Use the *Configuration Management* view to get more information about your Kubernetes roles and find unused roles. + +.Procedure +. In the {product-title-short} portal, go to *Configuration Management*. +. Select *RBAC Visibility and Configuration* -> *Roles* from the header in the *Configuration Management* view. +The *Roles* view displays a list of Kubernetes roles across your clusters, the permissions they grant, and where they are used. +. Select a row or an underlined link to view more details about the role. +. To find roles not granted to any users, groups, or service accounts, select the *Users & Groups* column header. +Then select the *Service Account* column header while holding the kbd:[Shift] key. +The list shows the roles that are not granted to any users, groups, or service accounts. diff --git a/modules/update-admission-controller.adoc b/modules/update-admission-controller.adoc new file mode 100644 index 000000000000..45e2602e6614 --- /dev/null +++ b/modules/update-admission-controller.adoc @@ -0,0 +1,90 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-44.adoc +:_mod-docs-content-type: PROCEDURE +[id="update-admission-controller_{context}"] += Updating Admission controller + +[role="_abstract"] +{product-title} 3.0.55 includes changes that affect admission controller integration. Therefore, if you are using an admission controller or want to take advantage of the admission controller integration’s new features, you must run some additional commands to upgrade the secured cluster. + +[IMPORTANT] +==== +If you are upgrading from a {product-title} version between 3.0.44 and 3.0.54, and you are not using an Admission controller and automatic upgrades, then you must manually redeploy Sensor on all clusters. +==== + +.Prerequisites + +* You must be using the {product-title} Admission controller. To check if you are using the Admission controller, run the following command: ++ +[source,terminal] +---- +$ oc get validatingwebhookconfiguration stackrox <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +If you get an error, it means that you are not using an admission controller. + +.Procedure + +. Delete the existing validating webhook configuration: ++ +[source,terminal] +---- +$ oc delete validatingwebhookconfiguration stackrox <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +[TIP] +==== +If you want to allow any additional admission controller features moving forward, go to the *Clusters* configuration view in the {product-title-short} portal, select the cluster you are updating, and enable the appropriate options. +==== +. Obtain a new Sensor bundle for the secured cluster: ++ +[source,terminal] +---- +$ roxctl sensor get-bundle <cluster_name> +---- +. Unzip the Sensor bundle and open the extracted directory. +. Create the `admission-control` deployment and related objects: ++ +[source,terminal] +---- +$ oc -n stackrox apply -f admission-controller-scc.yaml <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +[source,terminal] +---- +$ oc -n stackrox apply -f admission-controller-secret.yaml <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +[source,terminal] +---- +$ oc -n stackrox apply -f admission-controller-rbac.yaml <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +[source,terminal] +---- +$ oc -n stackrox apply -f admission-controller-netpol.yaml <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +[source,terminal] +---- +$ oc -n stackrox apply -f admission-controller-pod-security.yaml <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. ++ +[source,terminal] +---- +$ oc -n stackrox apply -f admission-controller.yaml <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +[WARNING] +==== +By default, the `--listenOnEvents` option is set to `false` during the upgrade. It controls the deployment of the admission controller webhook, which listens for `exec` and `portforward` events. If you are using {ocp} version 3.11, do not set the `--listenOnEvents` option to `true`. Since these events are not available for {ocp} 3.11, enabling them causes errors. For more information, see link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. +==== diff --git a/modules/update-authentication-keys-and-certificates.adoc b/modules/update-authentication-keys-and-certificates.adoc new file mode 100644 index 000000000000..7c86394da6be --- /dev/null +++ b/modules/update-authentication-keys-and-certificates.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * operating/manage-user-access/enable-pki-authentication.adoc +:_mod-docs-content-type: PROCEDURE +[id="update-authentication-keys-and-certificates_{context}"] += Updating authentication keys and certificates + +You can update your authentication keys and certificates by using the {product-title-short} portal. + +.Procedure +. Create a new authentication provider. +. Copy the role mappings from your old authentication provider to the new authentication provider. +. Rename or delete the old authentication provider with the old root CA key. diff --git a/modules/update-configuring-image-signature.adoc b/modules/update-configuring-image-signature.adoc deleted file mode 100644 index 159f23134ac6..000000000000 --- a/modules/update-configuring-image-signature.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-restricted-network-cluster.adoc - -[id="update-configuring-image-signature"] -= Creating an image signature config map manually - -Create and apply the image signature config map to the cluster that you want to update. - -[NOTE] -==== -You must perform following steps each time that you update a cluster. -==== - -.Procedure - -. Review the link:https://access.redhat.com/solutions/4583231[{product-title} upgrade paths] knowledge base article to determine a valid upgrade path for your cluster. - -. Add the version to the `OCP_RELEASE_NUMBER` environment variable: -+ -[source,terminal] ----- -$ OCP_RELEASE_NUMBER=<release_version> <1> ----- -<1> For `<release_version>`, specify the tag that corresponds to the version of {product-title} you want -to update the cluster, such as `4.4.0`. - -. Add the system architecture for your cluster to `ARCHITECTURE` environment variable: -+ -[source,terminal] ----- -$ ARCHITECTURE=<server_architecture> <1> ----- -<1> For `server_architecture`, specify the architecture of the server, such as `x86_64`. - -. Get the release image digest from link:https://quay.io/[Quay]: -+ -[source,terminal] ----- -$ DIGEST="$(oc adm release info quay.io/openshift-release-dev/ocp-release:${OCP_RELEASE_NUMBER}-${ARCHITECTURE} | sed -n 's/Pull From: .*@//p')" ----- - -. Set the digest algorithm: -+ -[source,terminal] ----- -$ DIGEST_ALGO="${DIGEST%%:*}" ----- - -. Set the digest signature: -+ -[source,terminal] ----- -$ DIGEST_ENCODED="${DIGEST#*:}" ----- - -. Get the image signature from link:https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release[mirror.openshift.com] website. -+ -[source,terminal] ----- -$ SIGNATURE_BASE64=$(curl -s "https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release/$%7BDIGEST_ALGO%7D=$%7BDIGEST_ENCODED%7D/signature-1" | base64 -w0 && echo) ----- - -. Create the config map: -+ -[source,terminal] ----- -$ cat >checksum-${OCP_RELEASE_NUMBER}.yaml <<EOF -apiVersion: v1 -kind: ConfigMap -metadata: - name: release-image-${OCP_RELEASE_NUMBER} - namespace: openshift-config-managed - labels: - release.openshift.io/verification-signatures: "" -binaryData: - ${DIGEST_ALGO}-${DIGEST_ENCODED}: ${SIGNATURE_BASE64} -EOF ----- - -. Apply the config map to the cluster to update: -+ -[source,terminal] ----- -$ oc apply -f checksum-${OCP_RELEASE_NUMBER}.yaml ----- diff --git a/modules/update-custom-certificate-central.adoc b/modules/update-custom-certificate-central.adoc new file mode 100644 index 000000000000..fb741ab6d3aa --- /dev/null +++ b/modules/update-custom-certificate-central.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * configuration/add-custom-certificates.adoc +:_mod-docs-content-type: PROCEDURE +[id="update-custom-certificate-central_{context}"] += Updating the custom certificate for an existing instance + +[role="_abstract"] +If you use a custom certificate for Central, you can update the certificate by performing the following procedure. + +.Procedure +. Delete the existing custom certificate's secret: ++ +[source,terminal] +---- +$ oc delete secret central-default-tls-cert +---- + +. Create a new secret: ++ +[source,terminal] +---- +$ oc -n stackrox create secret tls central-default-tls-cert \ + --cert <server_cert.pem> \ + --key <server_key.pem> \ + --dry-run -o yaml | oc apply -f - +---- + +. Restart the Central container. diff --git a/modules/update-kernel-support-packages.adoc b/modules/update-kernel-support-packages.adoc new file mode 100644 index 000000000000..8de89b4e5f35 --- /dev/null +++ b/modules/update-kernel-support-packages.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: CONCEPT +[id="update-kernel-support-packages_{context}"] += Updating kernel support packages in offline mode + +[NOTE] +==== +Support packages are deprecated and have no effect on secured clusters running version +4.5 or later. Support package uploads only affect secured clusters on version 4.4 and +earlier. +==== + +Collector monitors the runtime activity for each node in your secured clusters. +To monitor the activities, Collector requires probes in the form of eBPF programs. + +With the `CORE_BPF` collection method, the probe is not specific to any kernel version, and can still be used after the underlying kernel +has been updated. This collection method does not require you to provide or update a support package. + +Instead, when you use the collection method `EBPF`, the probes are specific to the Linux kernel version installed on the host. +The Collector image contains a set of built-in probes for the kernels supported at release time. However, later kernels will require newer probes. + +When {product-title} runs in normal mode (connected to the internet), Collector automatically downloads a new probe if the required probe is not built in. + +In offline mode, you can manually download packages containing probes for all recent and supported Linux kernel versions and upload them to Central. +Collectors then download these probes from Central. + +Collector checks for the new probes in the following order. It checks: + +. The existing Collector image. +. The kernel support package (if you have uploaded one to Central). +. A Red{nbsp}Hat-operated server available on the internet. +Collector uses Central's network connection to check and download the probes. + +If Collector does not get new probes after checking, it reports a `CrashLoopBackoff` event. + +If your network configuration restricts outbound traffic, you can manually download packages containing probes for all recent and supported Linux kernel versions and upload them to Central. Collectors then download these probes from Central, thus avoiding any outbound internet access. diff --git a/modules/update-mirror-repository.adoc b/modules/update-mirror-repository.adoc deleted file mode 100644 index 54a83683fa1e..000000000000 --- a/modules/update-mirror-repository.adoc +++ /dev/null @@ -1,122 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-restricted-network-cluster.adoc - -[id="update-mirror-repository_{context}"] -= Mirroring the {product-title} image repository - -Before you upgrade a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. You can also use this procedure in unrestricted networks to ensure your clusters only use container images that have satisfied your organizational controls on external content. - -.Procedure - -. Use the link:https://access.redhat.com/labs/ocpupgradegraph/update_channel[Red Hat {product-title} Upgrade Graph visualizer and update planner] to plan an upgrade from one version to another. The OpenShift Upgrade Graph provides channel graphs and a way to confirm that there is an update path between your current and intended cluster versions. - -. Set the required environment variables: -.. Export the release version: -+ -[source,terminal] ----- -$ export OCP_RELEASE=<release_version> ----- -+ -For `<release_version>`, specify the tag that corresponds to the version of {product-title} to which you want to upgrade, such as `4.5.4`. - -.. Export the local registry name and host port: -+ -[source,terminal] ----- -$ LOCAL_REGISTRY='<local_registry_host_name>:<local_registry_host_port>' ----- -+ -For `<local_registry_host_name>`, specify the registry domain name for your mirror -repository, and for `<local_registry_host_port>`, specify the port that it -serves content on. - -.. Export the local repository name: -+ -[source,terminal] ----- -$ LOCAL_REPOSITORY='<local_repository_name>' ----- -+ -For `<local_repository_name>`, specify the name of the repository to create in your -registry, such as `ocp4/openshift4`. - -.. Export the name of the repository to mirror: -+ -[source,terminal] ----- -$ PRODUCT_REPO='openshift-release-dev' ----- -+ -For a production release, you must specify `openshift-release-dev`. - -.. Export the path to your registry pull secret: -+ -[source,terminal] ----- -$ LOCAL_SECRET_JSON='<path_to_pull_secret>' ----- -+ -For `<path_to_pull_secret>`, specify the absolute path to and file name of the pull secret for your mirror registry that you created. - -.. Export the release mirror: -+ -[source,terminal] ----- -$ RELEASE_NAME="ocp-release" ----- -+ -For a production release, you must specify `ocp-release`. - -.. Export the type of architecture for your server, such as `x86_64`.: -+ -[source,terminal] ----- -$ ARCHITECTURE=<server_architecture> ----- - -.. Export the path to the directory to host the mirrored images: -+ -[source,terminal] ----- -$ REMOVABLE_MEDIA_PATH=<path> <1> ----- -<1> Specify the full path, including the initial forward slash (/) character. - -. Review the images and configuration manifests to mirror: -+ -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} --dry-run ----- -. Mirror the version images to the internal container registry. -** If your mirror host does not have internet access, take the following actions: -... Connect the removable media to a system that is connected to the internet. -... Mirror the images and configuration manifests to a directory on the removable media: -+ -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --to-dir=${REMOVABLE_MEDIA_PATH}/mirror quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} ----- -... Take the media to the restricted network environment and upload the images to the local container registry. -+ -[source,terminal] ----- -$ oc image mirror -a ${LOCAL_SECRET_JSON} --from-dir=${REMOVABLE_MEDIA_PATH}/mirror "file://openshift/release:${OCP_RELEASE}*" ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} <1> ----- -+ -<1> For `REMOVABLE_MEDIA_PATH`, you must use the same path that you specified when you mirrored the images. - -** If the local container registry and the cluster are connected to the mirror host, directly push the release images to the local registry and apply the config map to the cluster by using following command: -+ -[source,terminal] ----- -$ oc adm release mirror -a ${LOCAL_SECRET_JSON} --from=quay.io/${PRODUCT_REPO}/${RELEASE_NAME}:${OCP_RELEASE}-${ARCHITECTURE} \ - --to=${LOCAL_REGISTRY}/${LOCAL_REPOSITORY} --apply-release-image-signature ----- -+ -[NOTE] -==== -If you include the `--apply-release-image-signature` option, do not create the config map for image signature verification. -==== diff --git a/modules/update-oc-configmap-signature-verification.adoc b/modules/update-oc-configmap-signature-verification.adoc deleted file mode 100644 index a1f597e7e7d7..000000000000 --- a/modules/update-oc-configmap-signature-verification.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-restricted-network-cluster.adoc - -[id="update-oc-configmap-signature-verification_{context}"] -= Creating the config map for image signature verification by using the `oc` CLI - -Before you update your cluster, you must manually create a config map that contains the signatures of the release images that you use. This signature allows the Cluster Version Operator (CVO) to verify that the release images have not been modified by comparing the expected and actual image signatures. - -[NOTE] -==== -If you are upgrading from a release prior to version 4.4.8, you must use the manual method for creating the config map instead of this procedure. The commands that this procedure uses are not in earlier versions of the `oc` command-line interface (CLI). -==== - -.Prerequisites - -* Install the OpenShift CLI (`oc`), version 4.4.8 or later. - -.Procedure - -. Obtain the image signature for the version that you are upgrading to from either link:https://mirror.openshift.com/pub/openshift-v4/signatures/openshift/release[mirror.openshift.com] or link:https://storage.googleapis.com/openshift-release/official/signatures[Google Cloud Storage (GCS)]. - -. Use `oc` command-line interface (CLI) to log into the cluster that you are upgrading. - -. Apply the mirrored release image signature config map to the connected cluster: -+ -[source,terminal] ----- -$ oc apply -f <image_signature_file> <1> ----- -<1> For `<image_signature_file>`, specify the path and name of the file, for example, `mirror/config/signature-sha256-81154f5c03294534.yaml`. diff --git a/modules/update-other-images-40.adoc b/modules/update-other-images-40.adoc new file mode 100644 index 000000000000..667218f02279 --- /dev/null +++ b/modules/update-other-images-40.adoc @@ -0,0 +1,156 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-40-43.adoc +:_mod-docs-content-type: PROCEDURE +[id="update-other-images-40_{context}"] += Updating other images + +[role="_abstract"] +If you are upgrading {product-title} version, you must update the Sensor and Collector images. + +.Prerequisites + +* You must be using {product-title} version between 3.0.44 and 3.0.54. + +[NOTE] +==== +If you are using Kubernetes, use `kubectl` instead of `oc` for the commands listed in this procedure. +==== + +.Procedure + +. Update OpenShift security context constraints, if you are using {ocp}: ++ +[source,terminal] +---- +$ oc -n stackrox patch scc sensor -p '{"priority": 0}' +---- ++ +[source,terminal] +---- +$ oc -n stackrox patch scc collector -p '{"priority": 0}' +---- +. Apply the patch for Collector: ++ +[source,terminal] +---- +$ oc -n stackrox patch psp/stackrox-collector -p '{"spec":{"allowedHostPaths":[{"pathPrefix":"/","readOnly":true}]}}' +---- ++ +[source,terminal] +---- +$ oc -n stackrox patch ds/collector -p '{"spec":{"template":{"spec":{"containers":[{"name":"collector","volumeMounts":[{"mountPath":"/host/var/run/docker.sock","readOnly":true}]},{"name":"compliance","volumeMounts":[{"mountPath":"/host/var/lib","$patch":"delete"},{"mountPath":"/host/var/log/audit","$patch":"delete"},{"mountPath":"/host/usr/sbin","$patch":"delete"},{"mountPath":"/host/run","$patch":"delete"},{"mountPath":"/host/lib","$patch":"delete"},{"mountPath":"/host/usr/lib","$patch":"delete"},{"mountPath":"/host/etc","$patch":"delete"},{"mountPath":"/host/usr/bin","$patch":"delete"},{"mountPath":"/host/proc","$patch":"delete"},{"mountPath":"/host/var/run/docker.sock","$patch":"delete"},{"mountPath":"/host","name":"host-root-ro","readOnly":true}]}],"volumes":[{"name":"var-lib","$patch":"delete"},{"name":"var-log-audit","$patch":"delete"},{"name":"usr-sbin","$patch":"delete"},{"name":"run","$patch":"delete"},{"name":"lib","$patch":"delete"},{"name":"usr-lib","$patch":"delete"},{"hostPath":{"path":"/"},"name":"host-root-ro"}]}}}}' +---- +. Apply the patch for Sensor: ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy/sensor -p '{"spec":{"template":{"metadata":{"annotations":{"traffic.sidecar.istio.io/excludeInboundPorts":"8443,9443"}}}}}' +---- ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy/sensor -p '{"spec":{"template":{"spec":{"containers":[{"name":"sensor","resources":{"limits":{"cpu":"2","memory":"4Gi"},"requests":{"cpu":"1","memory":"1Gi"}}}]}}}}' +---- ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy/sensor -p '{"spec":{"template":{"spec":{"containers":[{"name":"sensor","env":[{"name":"POD_NAMESPACE","valueFrom":{"fieldRef":{"fieldPath":"metadata.namespace"}}}],"volumeMounts":[{"name":"cache","mountPath":"/var/cache/stackrox"}]}],"volumes":[{"name":"cache","emptyDir":{}}]}}}}' +---- +. Update the Sensor image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/sensor sensor=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} +---- +. Update the Compliance image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image ds/collector compliance=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} +---- +. Update the Collector image: +** If you are using the `collector` image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image ds/collector collector=registry.redhat.io/advanced-cluster-security/rhacs-collector-rhel8:{rhacs-version} +---- +** If you are using the `collector-slim` image: ++ +[source,terminal] +---- +$ oc -n stackrox set image ds/collector collector=registry.redhat.io/advanced-cluster-security/rhacs-collector-slim-rhel8:{rhacs-version} +---- +. Update the admission control image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/admission-control admission-control=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} +---- +. Apply the following cluster role and cluster role binding: ++ +[source,terminal] +---- +$ oc -n stackrox apply -f - <<EOF +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: +name: stackrox:review-tokens +labels: +app.kubernetes.io/name: stackrox +auto-upgrade.stackrox.io/component: "sensor" +annotations: +owner: stackrox +email: "support@stackrox.com" +rules: +- resources: +- tokenreviews +apiGroups: ["authentication.k8s.io"] +verbs: +- create +--- +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: +name: stackrox:review-tokens-binding +labels: +app.kubernetes.io/name: stackrox +auto-upgrade.stackrox.io/component: "sensor" +annotations: +owner: stackrox +email: "support@stackrox.com" +subjects: +- kind: ServiceAccount +name: sensor +namespace: stackrox +roleRef: +kind: ClusterRole +name: stackrox:review-tokens +apiGroup: rbac.authorization.k8s.io +EOF +---- +. Optional: If you have installed Istio in your cluster, run the following additional command: ++ +[source,terminal] +---- +$ oc create -f - <<EOF +apiVersion: networking.istio.io/v1alpha3 +kind: DestinationRule +metadata: + name: sensor-internal-no-istio-mtls + namespace: stackrox + labels: + app.kubernetes.io/name: stackrox + annotations: + stackrox.io/description: "Disable Istio mTLS for port 443, since StackRox services use built-in mTLS." +spec: + host: sensor.stackrox.svc.cluster.local + trafficPolicy: + portLevelSettings: + - port: + number: 443 + tls: + mode: DISABLE +EOF +---- diff --git a/modules/update-other-images.adoc b/modules/update-other-images.adoc new file mode 100644 index 000000000000..a6c077f7967c --- /dev/null +++ b/modules/update-other-images.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-44.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="update-other-images_{context}"] += Updating other images + +[role="_abstract"] +You must update the sensor, collector and compliance images on each secured cluster when not using automatic upgrades. + +[NOTE] +==== +If you are using Kubernetes, use `kubectl` instead of `oc` for the commands listed in this procedure. +==== + +.Procedure + +. Update the Sensor image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/sensor sensor=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +. Update the Compliance image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image ds/collector compliance=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +. Update the Collector image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image ds/collector collector=registry.redhat.io/advanced-cluster-security/rhacs-collector-rhel8:{rhacs-version} <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +. Update the admission control image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/admission-control admission-control=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} +---- + +[IMPORTANT] +==== +If you have installed {product-title-short} on {osp} by using the `roxctl` CLI, you need to migrate the security context constraints (SCCs). + +For more information, see "Migrating SCCs during the manual upgrade" in the "Additional resources" section. +==== \ No newline at end of file diff --git a/modules/update-restricted.adoc b/modules/update-restricted.adoc deleted file mode 100644 index a266fb2bdda1..000000000000 --- a/modules/update-restricted.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-restricted-network-cluster.adoc - -[id="update-restricted_{context}"] -= Upgrading the restricted network cluster - -Update the restricted network cluster to the {product-title} version that you downloaded the release images for. - -.Prerequisites - -* You mirrored the images for the new release to your registry. -* You applied the release image signature ConfigMap for the new release to your cluster. -* You obtained the sha256 sum value for the release from the image signature ConfigMap. -* Install the OpenShift CLI (`oc`), version 4.4.8 or later. - -.Procedure - -* Update the cluster: -+ -[source,terminal] ----- -$ oc adm upgrade --allow-explicit-upgrade --to-image ${LOCAL_REGISTRY}/${LOCAL_REPOSITORY}<sha256_sum_value> <1> ----- -<1> The `<sha256_sum_value>` value is the sha256 sum value for the release from the image signature ConfigMap, for example, `@sha256:81154f5c03294534e1eaf0319bef7a601134f891689ccede5d705ef659aa8c92` -+ -If you use an `ImageContentSourcePolicy` for the mirror registry, you can use the canonical registry name instead of `LOCAL_REGISTRY`. diff --git a/modules/update-service-overview.adoc b/modules/update-service-overview.adoc deleted file mode 100644 index b57e0e2965c2..000000000000 --- a/modules/update-service-overview.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// Module included in the following assemblies: -// -// * architecture/architecture-installation.adoc -// * architecture/control-plane.adoc -// * updating/updating-cluster-between-minor.adoc -// * updating/updating-cluster-cli.adoc -// * updating/updating-cluster-rhel-compute.adoc -// * updating/updating-cluster.adoc -// * updating/updating-disconnected-cluster.adoc - -[id="update-service-overview_{context}"] -= About the {product-title} update service - -The {product-title} update service is the hosted service that provides over-the-air -updates to both {product-title} and {op-system-first}. It provides a graph, -or diagram that contain _vertices_ and the _edges_ that connect them, of -component Operators. The edges in the graph show which versions you can safely -update to, and the vertices are update payloads that specify the intended state -of the managed cluster components. - -The Cluster Version Operator (CVO) in your cluster checks with the -{product-title} update service to see the valid updates and update paths based -on current component versions and information in the graph. When you request an -update, the {product-title} CVO uses the release image for that update to -upgrade your cluster. The release artifacts are hosted in Quay as container -images. -//// -By accepting automatic updates, you can automatically -keep your cluster up to date with the most recent compatible components. -//// - -To allow the {product-title} update service to provide only compatible updates, -a release verification pipeline exists to drive automation. Each release -artifact is verified for compatibility with supported cloud platforms and system -architectures as well as other component packages. After the pipeline confirms -the suitability of a release, the {product-title} update service notifies you -that it is available. - -[IMPORTANT] -==== -Because the update service displays all valid updates, you must not force an update to a version that the update service does not display. -==== - -//// -The interaction between the registry and the {product-title} update service is different during -bootstrap and continuous update modes. When you bootstrap the initial -infrastructure, the Cluster Version Operator finds -the fully qualified image name for the shortname of the images that it needs to -apply to the server during installation. It looks at the imagestream that it needs -to apply and renders it to disk. It calls bootkube and waits for a temporary minimal control -plane to come up and load the Cluster Version Operator. -//// - -During continuous update mode, two controllers run. One continuously updates -the payload manifests, applies them to the cluster, and outputs the status of -the controlled rollout of the Operators, whether they are available, upgrading, -or failed. The second controller polls the {product-title} update service to -determine if updates are available. - -[IMPORTANT] -==== -Reverting your cluster to a previous version, or a rollback, is not supported. -Only upgrading to a newer version is supported. -==== - -During the upgrade process, the Machine Config Operator (MCO) applies the new configuration to your cluster machines. It cordons the number of nodes that is specified by the `maxUnavailable` field on the machine configuration pool and marks them as unavailable. By default, this value is set to `1`. It then applies the new configuration and reboots the machine. If you use Red Hat Enterprise Linux (RHEL) machines as workers, the MCO does not update the kubelet on these machines because you must update the OpenShift API on them first. Because the specification for the new version is applied to the old kubelet, the RHEL machine cannot return to the `Ready` state. You cannot complete the update until the machines are available. However, the maximum number of nodes that are unavailable is set to ensure that normal cluster operations are likely to continue with that number of machines out of service. diff --git a/modules/update-the-splunk-add-on.adoc b/modules/update-the-splunk-add-on.adoc new file mode 100644 index 000000000000..dbba00078c4a --- /dev/null +++ b/modules/update-the-splunk-add-on.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-splunk.adoc +:_mod-docs-content-type: PROCEDURE +[id="update-the-splunk-add-on_{context}"] += Update the StackRox Kubernetes Security Platform add-on + +[role="_abstract"] +If you are using the StackRox Kubernetes Security Platform add-on, you must upgrade to the new {product-title} add-on. + +You can see the update notification on the Splunk homepage under the list of apps on the left. Alternatively, you can also go to the *Apps* -> *Manage apps* page to see the update notification. + +.Prerequisites +* You must have an API token with `read` permission for all resources of {product-title}. You can assign the *Analyst* system role to grant this level of access. The *Analyst* role has read permissions for all the resources. + +.Procedure +. Click *Update* on the update notification. +. Select the checkbox for accepting the terms and conditions, and then click *Accept and Continue* to install the update. +. After the installation, select *{product-title}* from the *Apps* menu. +. Go to *Configuration* and then click *Add-on Settings*. +.. Enter the *API token* you have generated for the add-on. +.. Click *Save*. diff --git a/modules/update-upgrading-cli.adoc b/modules/update-upgrading-cli.adoc deleted file mode 100644 index 104aa8bc4fb4..000000000000 --- a/modules/update-upgrading-cli.adoc +++ /dev/null @@ -1,178 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-cluster-cli.adoc -// * updating/updating-cluster-rhel-compute.adoc - -[id="update-upgrading-cli_{context}"] -= Updating a cluster by using the CLI - -If updates are available, you can update your cluster by using the -OpenShift CLI (`oc`). - -You can find information about available {product-title} advisories and updates -link:https://access.redhat.com/downloads/content/290/ver=4.1/rhel---7/4.1.0/x86_64/product-errata[in the errata section] -of the Customer Portal. - -.Prerequisites - -* Install the OpenShift CLI (`oc`) that matches the version for your updated version. -* Log in to the cluster as user with `cluster-admin` privileges. -* Install the `jq` package. - -.Procedure - -. Ensure that your cluster is available: -+ -[source,terminal] ----- -$ oc get clusterversion ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING SINCE STATUS -version 4.6.9 True False 158m Cluster version is 4.6.9 ----- - -. Review the current update channel information and confirm that your channel -is set to `stable-4.7`: -+ -[source,terminal] ----- -$ oc get clusterversion -o json|jq ".items[0].spec" ----- -+ -.Example output -[source,terminal] ----- -{ - "channel": "stable-4.7", - "clusterID": "990f7ab8-109b-4c95-8480-2bd1deec55ff", - "upstream": "https://api.openshift.com/api/upgrades_info/v1/graph" -} ----- -+ -[IMPORTANT] -==== -For production clusters, you must subscribe to a `stable-\*` or `fast-*` channel. -==== - -. View the available updates and note the version number of the update that -you want to apply: -+ -[source,terminal] ----- -$ oc adm upgrade ----- -+ -.Example output -[source,terminal] ----- -Cluster version is 4.1.0 - -Updates: - -VERSION IMAGE -4.1.2 quay.io/openshift-release-dev/ocp-release@sha256:9c5f0df8b192a0d7b46cd5f6a4da2289c155fd5302dec7954f8f06c878160b8b ----- - -. Apply an update: -** To update to the latest version: -+ -[source,terminal] ----- -$ oc adm upgrade --to-latest=true <1> ----- - -** To update to a specific version: -+ -[source,terminal] ----- -$ oc adm upgrade --to=<version> <1> ----- -<1> `<version>` is the update version that you obtained from the output of the -previous command. - -. Review the status of the Cluster Version Operator: -+ -[source,terminal] ----- -$ oc get clusterversion -o json|jq ".items[0].spec" ----- -+ -.Example output -[source,terminal] ----- -{ - "channel": "stable-4.7", - "clusterID": "990f7ab8-109b-4c95-8480-2bd1deec55ff", - "desiredUpdate": { - "force": false, - "image": "quay.io/openshift-release-dev/ocp-release@sha256:9c5f0df8b192a0d7b46cd5f6a4da2289c155fd5302dec7954f8f06c878160b8b", - "version": "4.7.0" <1> - }, - "upstream": "https://api.openshift.com/api/upgrades_info/v1/graph" -} ----- -<1> If the `version` number in the `desiredUpdate` stanza matches the value that -you specified, the update is in progress. - -. Review the cluster version status history to monitor the status of the update. -It might take some time for all the objects to finish updating. -+ -[source,terminal] ----- -$ oc get clusterversion -o json|jq ".items[0].status.history" ----- -+ -.Example output -[source,terminal] ----- -[ - { - "completionTime": null, - "image": "quay.io/openshift-release-dev/ocp-release@sha256:b8fa13e09d869089fc5957c32b02b7d3792a0b6f36693432acc0409615ab23b7", - "startedTime": "2021-01-28T20:30:50Z", - "state": "Partial", - "verified": true, - "version": "4.7.0" - }, - { - "completionTime": "2021-01-28T20:30:50Z", - "image": "quay.io/openshift-release-dev/ocp-release@sha256:b8fa13e09d869089fc5957c32b02b7d3792a0b6f36693432acc0409615ab23b7", - "startedTime": "2021-01-28T17:38:10Z", - "state": "Completed", - "verified": false, - "version": "4.7.0" - } -] ----- -+ -The history contains a list of the most recent versions applied to the cluster. -This value is updated when the CVO applies an update. The list is ordered by -date, where the newest update is first in the list. Updates in the history have -state `Completed` if the rollout completed and `Partial` if the update failed -or did not complete. -+ -[IMPORTANT] -==== -If an upgrade fails, the Operator stops and reports the status of the failing -component. Rolling your cluster back to a previous version is not supported. -If your upgrade fails, contact Red Hat support. -==== - -. After the update completes, you can confirm that the cluster version has -updated to the new version: -+ -[source,terminal] ----- -$ oc get clusterversion ----- -+ -.Example output -[source,terminal] ----- -NAME VERSION AVAILABLE PROGRESSING SINCE STATUS -version 4.7.0 True False 2m Cluster version is 4.7.0 ----- diff --git a/modules/update-upgrading-web.adoc b/modules/update-upgrading-web.adoc deleted file mode 100644 index ae96a93c98e7..000000000000 --- a/modules/update-upgrading-web.adoc +++ /dev/null @@ -1,85 +0,0 @@ -// Module included in the following assemblies: -// -// * updating/updating-cluster.adoc -// * updating/updating-cluster-between-minor.adoc - -ifeval::["{context}" == "updating-cluster"] -:within: -endif::[] -ifeval::["{context}" == "updating-cluster-between-minor"] -:between: -endif::[] -ifeval::["{context}" == "updating-cluster-rhel-compute"] -:rhel: -:between: -endif::[] - -[id="update-upgrading-web_{context}"] -= Updating a cluster by using the web console - -If updates are available, you can update your cluster from the web console. - -You can find information about available {product-title} advisories and updates -link:https://access.redhat.com/downloads/content/290/ver=4.7/rhel---8/4.7.0/x86_64/product-errata[in the errata section] of the Customer Portal. - -.Prerequisites - -* Have access to the web console as a user with `admin` privileges. - -.Procedure - -. From the web console, click *Administration* > *Cluster Settings* and review the contents of the *Details* tab. - -. For production clusters, ensure that the *Channel* is set to the correct channel for -ifdef::within[] -the version that you want to update to, -endif::within[] -ifdef::between[] -your current minor version, -endif::between[] -ifndef::openshift-origin[] -such as `stable-{product-version}`. -+ -[IMPORTANT] -==== -For production clusters, you must subscribe to a stable-* or fast-* channel. -==== -endif::openshift-origin[] -ifdef::openshift-origin[] -such as `stable-4`. -endif::openshift-origin[] -** If the *Update Status* is not *Updates Available*, you cannot upgrade your cluster. -** *Select Channel* indicates the cluster version that your cluster is running or is updating to. - -. Select -ifdef::within[] -a version to update to, -endif::within[] -ifdef::between[] -the highest available version -endif::between[] -and click *Update*. -The *Update Status* changes to `Update to <product-version> in progress`, and you can review the progress of the cluster update by watching the progress bars for the Operators and nodes. - -ifdef::between[] -. After the update completes and the Cluster Version Operator refreshes the available updates, check if more updates are available in your current channel. -+ --- -** If updates are available, continue to perform updates in the current channel until you can no longer update. -ifndef::openshift-origin[] -** If no updates are available, change the *Channel* to the stable-* or fast-* channel for the next minor version, and update to the version that you want in that channel. -endif::openshift-origin[] -ifdef::openshift-origin[] -** If no updates are available, change the *Channel* to the stable-* channel for the next minor version, and update to the version that you want in that channel. -endif::openshift-origin[] --- -+ -You might need to perform several intermediate updates until you reach the version that you want. -ifdef::rhel[] -+ -[NOTE] -==== -When you update a cluster that contains Red Hat Enterprise Linux (RHEL) worker machines, those workers temporarily become unavailable during the update process. You must run the upgrade playbook against each RHEL machine as it enters the `NotReady` state for the cluster to finish updating. -==== - -endif::rhel[] diff --git a/modules/update-validating-webhook-configuration.adoc b/modules/update-validating-webhook-configuration.adoc new file mode 100644 index 000000000000..6c0dd12c20c6 --- /dev/null +++ b/modules/update-validating-webhook-configuration.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="update-validating-webhook-configuration_{context}"] += Update ValidatingWebhookConfiguration + +[role="_abstract"] +Earlier {product-title-short} versions included a wrong entry in the ValidatingWebhookConfiguration. To fix it, you must update the ValidatingWebhookConfiguration. + +.Procedure + +* If you have enabled `listenOnEvents` in your Admission controller, you must run the following command: ++ +[source,terminal] +---- +$ oc patch validatingwebhookconfiguration stackrox -p '{"webhooks":[{"name": "k8sevents.stackrox.io", "rules": [{"apiGroups": ["*"], "apiVersions": ["*"], "operations": ["CONNECT"], "resources": ["pods", "pods/exec", "pods/portforward"]}]}]}' <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. diff --git a/modules/updates-and-upgrades.adoc b/modules/updates-and-upgrades.adoc new file mode 100644 index 000000000000..ded597b7e253 --- /dev/null +++ b/modules/updates-and-upgrades.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * service_description/rhacs-cloud-service-service-description.adoc +:_mod-docs-content-type: CONCEPT +[id="updates-and-upgrades_{context}"] += Updates and Upgrades + +Red{nbsp}Hat makes a commercially reasonable effort to notify customers prior to updates and upgrades that impact service. +The decision regarding the need for a Service update to the Central instance and its timing is the sole responsibility of Red{nbsp}Hat. + +Customers have no control over when a Central service update occurs. For more information, see link:https://www.redhat.com/licenses/Appendix_4_Red_Hat_Online_Services_20221213.pdf[PRODUCT APPENDIX 4 RED HAT ONLINE SERVICES]. +Upgrades to the version of {rh-rhacscs-first} are considered part of the service update. Upgrades are transparent to the customer and no connection to any update site is required. + +Customers are responsible for timely {product-title-short} Secured Cluster services upgrades that are required to maintain compatibility with {product-title-managed-short}. + +Red{nbsp}Hat recommends enabling automatic upgrades for Secured Clusters that are connected to {product-title-managed-short}. + +See the link:https://access.redhat.com/articles/7045053[Red Hat Advanced Cluster Security for Kubernetes Support Matrix] for more information about upgrade versions. diff --git a/modules/updating-clear.adoc b/modules/updating-clear.adoc deleted file mode 100644 index 34d7a080c6f4..000000000000 --- a/modules/updating-clear.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * upgrading/upgrading-cluster-cli.adoc - -[id="updating-clear_{context}"] -= Recovering when an update fails before it is applied - -If an update fails before it is applied, such as when the version that you -specify cannot be found, you can cancel the upgrade: - ----- -$ oc adm upgrade clear ----- \ No newline at end of file diff --git a/modules/updating-helm-repository.adoc b/modules/updating-helm-repository.adoc new file mode 100644 index 000000000000..c45d77d0871b --- /dev/null +++ b/modules/updating-helm-repository.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-helm.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-helm.adoc +:_mod-docs-content-type: PROCEDURE +[id="updating-helm-repository_{context}"] += Updating the Helm chart repository + +You must always update Helm charts before upgrading to a new version of {product-title}. + +.Prerequisites + +* You must have already added the {product-title} Helm chart repository. +* You must be using Helm version 3.8.3 or newer. + +.Procedure + +* Update {product-title} charts repository. ++ +[source,terminal] +---- +$ helm repo update +---- + +.Verification + +* Run the following command to verify the added chart repository: ++ +[source,terminal] +---- +$ helm search repo -l rhacs/ +---- diff --git a/modules/upgrade-central-cluster-central.adoc b/modules/upgrade-central-cluster-central.adoc new file mode 100644 index 000000000000..a413ddca241e --- /dev/null +++ b/modules/upgrade-central-cluster-central.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc + +:_mod-docs-content-type: PROCEDURE +[id="upgrade-central-cluster-central_{context}"] += Upgrading Central + +[role="_abstract"] +You can update Central to the latest version by downloading and deploying the updated images. + +[IMPORTANT] +==== +If you use Kubernetes, enter `kubectl` instead of `oc`. +==== + +.Procedure + +. To update the Central image, run the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/central \ +central=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} +---- + +. To update the Central-db image, run the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/central-db \ +central-db=registry.redhat.io/advanced-cluster-security/rhacs-central-db-rhel8:{rhacs-version} \ +init-db=registry.redhat.io/advanced-cluster-security/rhacs-central-db-rhel8:{rhacs-version} +---- + +. To update the config controller image, run the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/config-controller \ +manager=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} +---- + +.Verification + +* Verify that the new pods have deployed: ++ +[source,terminal] +---- +$ oc get deploy -n stackrox -o wide +---- ++ +[source,terminal] +---- +$ oc get pod -n stackrox --watch +---- \ No newline at end of file diff --git a/modules/upgrade-central-cluster-crds.adoc b/modules/upgrade-central-cluster-crds.adoc new file mode 100644 index 000000000000..87ccc4e92b2f --- /dev/null +++ b/modules/upgrade-central-cluster-crds.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="upgrade-central-cluster-crds_{context}"] += Upgrading the SecurityPolicy custom resource definition + +[role="_abstract"] +You can update the `SecurityPolicy` custom resource definition (CRD) to the latest version by generating the new CRD and applying it to the cluster. + +.Procedure + +. Use `roxctl` to generate a new set of resources by entering the following command: ++ +[source,terminal,subs=attributes+] +---- +$ roxctl central generate k8s pvc > bundle.zip +---- + +. Extract the CRD from the archive by entering the following command: ++ +[source,terminal,subs=attributes+] +---- +$ unzip bundle.zip central/00-securitypolicy-crd.yaml +---- + +. Apply the extracted CRD to your cluster by entering the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc apply -f central/00-securitypolicy-crd.yaml <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. diff --git a/modules/upgrade-central-cluster-scanner.adoc b/modules/upgrade-central-cluster-scanner.adoc new file mode 100644 index 000000000000..88c0d0c2ca16 --- /dev/null +++ b/modules/upgrade-central-cluster-scanner.adoc @@ -0,0 +1,71 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc + +:_mod-docs-content-type: PROCEDURE +[id="upgrade-central-cluster-scanner_{context}"] += Upgrading Scanner + +[role="_abstract"] +You can update Scanner to the latest version by downloading and deploying the updated images. + +[IMPORTANT] +==== +If you are using Kubernetes, enter the `kubectl` command instead of the `oc` command. +==== + +.Procedure + +. If you have created custom Scanner configurations, you must apply these changes before updating the Scanner configuration file: + +.. To generate Scanner, run the following command: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" scanner generate +---- + +.. To apply the TLS secrets YAML file, run the following command: ++ +[source,terminal] +---- +$ oc apply -f scanner-bundle/scanner/02-scanner-03-tls-secret.yaml +---- + +.. To apply the Scanner configuration YAML file, run the following command: ++ +[source,terminal] +---- +$ oc apply -f scanner-bundle/scanner/02-scanner-04-scanner-config.yaml +---- + +. To update the Scanner image, run the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/scanner \ +scanner=registry.redhat.io/advanced-cluster-security/rhacs-scanner-rhel8:{rhacs-version} +---- + +. To update the Scanner database image, run the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/scanner-db \ +db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version} \ +init-db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version} +---- + +.Verification + +* To verify that the new pods have been deployed, run the following commands: ++ +[source,terminal] +---- +$ oc get deploy -n stackrox -o wide +---- ++ +[source,terminal] +---- +$ oc get pod -n stackrox --watch +---- \ No newline at end of file diff --git a/modules/upgrade-central-kubernetes.adoc b/modules/upgrade-central-kubernetes.adoc new file mode 100644 index 000000000000..58fb8ee57e82 --- /dev/null +++ b/modules/upgrade-central-kubernetes.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="upgrade-central-kubernetes_{context}"] += Upgrading Central on Kubernetes + +If you installed {product-title} on Kubernetes, use the following procedure to upgrade. + +.Prerequisites + +* If you deploy images from a private image registry, first push the new image into your private registry, and then replace your image registry in the following commands. + +.Procedure + +. Patch the local role: ++ +[source,terminal] +---- +$ kubectl -n stackrox patch role edit -p '{"rules":[{"apiGroups":["*"],"resources":["*"],"verbs":["create","get", "list", "watch", "update", "patch", "delete","deletecollection"]}]}' +---- +. Run the following commands to upgrade Central: ++ +[source,terminal] +---- +$ kubectl -n stackrox patch deploy/central -p '{"spec":{"template":{"spec":{"containers":[{"name":"central","env":[{"name":"ROX_NAMESPACE","valueFrom":{"fieldRef":{"fieldPath":"metadata.namespace"}}}]}]}}}}' +---- ++ +[source,terminal] +---- +$ kubectl -n stackrox patch deployment/scanner -p '{"spec":{"template":{"spec":{"containers":[{"name":"scanner","securityContext":{"runAsUser":65534}}]}}}}' +---- ++ +[source,terminal,subs=attributes+] +---- +$ kubectl -n stackrox set image deploy/central central=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} <1> +---- +<1> If you deploy images from a private image registry, push the new image into your private registry, and replace the image registry address here. + +.Verification + +* Verify that the new pods have deployed: ++ +[source,terminal] +---- +$ kubectl get deploy -n stackrox -o wide +---- ++ +[source,terminal] +---- +$ kubectl get pod -n stackrox --watch +---- diff --git a/modules/upgrade-central-openshift.adoc b/modules/upgrade-central-openshift.adoc new file mode 100644 index 000000000000..fda9e9d5c34e --- /dev/null +++ b/modules/upgrade-central-openshift.adoc @@ -0,0 +1,97 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="upgrade-central-openshift_{context}"] += Upgrading Central on {ocp} + +If you installed {product-title} on {ocp}, use the following procedure to upgrade. + +.Procedure + +. Patch the local role: ++ +[source,terminal] +---- +$ oc -n stackrox patch role edit -p '{"rules":[{"apiGroups":["*"],"resources":["*"],"verbs":["create","get", "list", "watch", "update", "patch", "delete","deletecollection"]}]}' +---- +. Cleanup existing roles and role bindings: ++ +[source,terminal] +---- +$ oc -n stackrox delete RoleBinding admission-control-use-scc || true +---- ++ +[source,terminal] +---- +$ oc -n stackrox delete RoleBinding sensor-use-scc || true +---- ++ +[source,terminal] +---- +$ oc -n stackrox delete Role use-anyuid-scc || true +---- +. Set `sensor` and `admission-control` to `restricted[-v2]` security context constraints by removing the hard-coded security context: ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy sensor -p '{"spec":{"template":{"spec":{"securityContext":null}}}}' <1> +---- +<1> {product-title} recreates the pods automatically, however, `sensor` can take some time to restart. ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy admission-control -p '{"spec":{"template":{"spec":{"securityContext":null}}}}' +---- +. Run the following commands to upgrade Central: ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy/central -p '{"spec":{"template":{"spec":{"containers":[{"name":"central","env":[{"name":"ROX_NAMESPACE","valueFrom":{"fieldRef":{"fieldPath":"metadata.namespace"}}}]}]}}}}' +---- ++ +[source,terminal] +---- +$ oc -n stackrox patch deployment/scanner -p '{"spec":{"template":{"spec":{"containers":[{"name":"scanner","securityContext":{"runAsUser":65534}}]}}}}' +---- ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/central central=registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:{rhacs-version} <1> +---- +<1> If you deploy images from a private image registry, push the new image into your private registry, and replace the image registry address here. ++ +[IMPORTANT] +==== +If you have not installed {product-title} by using Helm or Operator, and you want to enable authentication using the OpenShift OAuth server, you must run the following additional commands: +[source,terminal] +---- +$ oc -n stackrox set env deploy/central ROX_ENABLE_OPENSHIFT_AUTH=true +---- +[source,terminal] +---- +$ oc -n stackrox patch serviceaccount/central -p ' +{ +"metadata": { +"annotations": { +"serviceaccounts.openshift.io/oauth-redirecturi.main": "sso/providers/openshift/callback", +"serviceaccounts.openshift.io/oauth-redirectreference.main": "{"kind":"OAuthRedirectReference","apiVersion":"v1","reference":{"kind":"Route","name":"central"}}" +} +} +}' +---- +==== + +.Verification + +* Verify that the new pods have deployed: ++ +[source,terminal] +---- +$ oc get deploy -n stackrox -o wide +---- ++ +[source,terminal] +---- +$ oc get pod -n stackrox --watch +---- diff --git a/modules/upgrade-crd-helm.adoc b/modules/upgrade-crd-helm.adoc new file mode 100644 index 000000000000..077e223d486d --- /dev/null +++ b/modules/upgrade-crd-helm.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-helm.adoc +:_mod-docs-content-type: PROCEDURE +[id="upgrade-crd-helm_{context}"] += Preparing the custom resource definition for upgrade + +[role="_abstract"] +If upgrading from version 4.6 or 4.7, you must prepare the `SecurityPolicy` custom resource definition (CRD) to avoid upgrade errors. + +.Procedure +* Apply Helm-specific labels and annotations to the CRD by running the following commands: + +[source,terminal] +---- +$ oc annotate crd/securitypolicies.config.stackrox.io meta.helm.sh/release-name=stackrox-central-services <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. Adjust the value of the `release-name` from the above default of `stackrox-central-services` as needed. + +[source,terminal] +---- +$ oc annotate crd/securitypolicies.config.stackrox.io meta.helm.sh/release-namespace=stackrox <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. Adjust the value of the `release-namespace` from the above default of `stackrox` as needed. + +[source,terminal] +---- +$ oc label crd/securitypolicies.config.stackrox.io app.kubernetes.io/managed-by=Helm <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. diff --git a/modules/upgrade-helm-chart.adoc b/modules/upgrade-helm-chart.adoc new file mode 100644 index 000000000000..237a4669d0fc --- /dev/null +++ b/modules/upgrade-helm-chart.adoc @@ -0,0 +1,66 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-helm.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-helm.adoc +:_mod-docs-content-type: PROCEDURE +[id="upgrade-helm-chart_{context}"] += Running the Helm upgrade command + +ifeval::["{context}" == "upgrade-cloudsvc-helm"] +:cloud-svc: +endif::[] + +[role="_abstract"] +You can use the `helm upgrade` command to update {rh-rhacs-first}. + +.Prerequisites +* You must have access to the `values-private.yaml` configuration file that you have used to install {rh-rhacs-first}. Otherwise, you must generate the `values-private.yaml` configuration file containing root certificates before proceeding with these commands. + +.Procedure +* Run the helm upgrade command and specify the configuration files by using the `-f` option: + +ifndef::cloud-svc[] ++ +[source,terminal] +---- +$ helm upgrade -n stackrox stackrox-central-services \ + rhacs/central-services --version <current-rhacs-version> \// <1> + -f values-private.yaml \ + --set central.db.password.generate=true \ + --set central.db.serviceTLS.generate=true \ + --set central.db.persistence.persistentVolumeClaim.createClaim=true +---- +<1> Use the `-f` option to specify the paths for your YAML configuration files. +endif::cloud-svc[] + ++ +[source,terminal] +---- +$ helm upgrade -n stackrox stackrox-secured-cluster-services \ + rhacs/secured-cluster-services --version <current-rhacs-version> \// <1> + -f values-private.yaml +---- +<1> Use the `-f` option to specify the paths for your YAML configuration files. + +ifndef::cloud-svc[] +[NOTE] +==== +You might use the `--reuse-values` option to preserve the previously configured Helm values during the upgrade. If you do that, you must turn off `central-db` creation before you upgrade to the next version. + +See the following command example: + +[source,terminal] +---- +$ helm upgrade -n stackrox stackrox-central-services \ + rhacs/central-services --version <current-rhacs-version> --reuse-values \ + -f values-private.yaml \ + --set central.db.password.generate=false \ + --set central.db.serviceTLS.generate=false \ + --set central.db.persistence.persistentVolumeClaim.createClaim=false +---- +==== +endif::cloud-svc[] + +ifeval::["{context}" == "upgrade-cloudsvc-helm"] +:!cloud-svc: +endif::[] \ No newline at end of file diff --git a/modules/upgrade-scanner-40.adoc b/modules/upgrade-scanner-40.adoc new file mode 100644 index 000000000000..9a398987985b --- /dev/null +++ b/modules/upgrade-scanner-40.adoc @@ -0,0 +1,126 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-40-43.adoc +:_mod-docs-content-type: PROCEDURE +[id="upgrade-scanner-40_{context}"] += Upgrading Scanner + +You can update Scanner to the latest version by using the `roxctl` CLI. + +.Prerequisites + +* If you deploy images from a private image registry, first push the new image into your private registry, and then replace your image registry for the commands in this section. +* If you used Red{nbsp}Hat UBI-based images when you installed {product-title}, replace the image names for the commands in this section with the following UBI-based image names: +** For Central, Sensor, and Compliance, use `\registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8` +** For Scanner, use `\registry.redhat.io/advanced-cluster-security/rhacs-scanner-rhel8` and `\registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8` +** For Collector, use `\registry.redhat.io/advanced-cluster-security/rhacs-collector-rhel8` + +.Procedure + +. Apply the patch for Scanner: ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy/scanner -p '{"spec":{"template":{"spec":{"containers":[{"name":"scanner","command":["/entrypoint.sh"],"volumeMounts":[{"mountPath":"/etc/ssl","name":"central-etc-ssl-volume"},{"mountPath":"/usr/local/share/ca-certificates/","name":"additional-ca-volume","readOnly":true}]}],"volumes":[{"name":"additional-ca-volume","secret":{"defaultMode":420,"optional":true,"secretName":"additional-ca"}},{"emptyDir":{},"name":"central-etc-ssl-volume"}]}}}}' +---- ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy/scanner -p '{"spec":{"template":{"metadata":{"annotations":{"traffic.sidecar.istio.io/excludeInboundPorts":"8080,8443"}}}}}' +---- +. Apply the patch for the Scanner database: ++ +[source,terminal] +---- +$ oc -n stackrox patch deploy/scanner-db -p '{"spec":{"template":{"metadata":{"annotations":{"traffic.sidecar.istio.io/excludeInboundPorts":"5432"}}}}}' +---- +. Apply the patch for the Scanner service: ++ +[source,terminal] +---- +$ oc -n stackrox patch svc/scanner -p '{"spec":{"ports":[{"port":8443,"name":"grpcs-scanner"}]}}' +---- +. Apply the patch for the Scanner database service: ++ +[source,terminal] +---- +$ oc -n stackrox patch svc/scanner-db -p '{"spec":{"ports":[{"port":5432,"name":"db"}]}}' +---- +. Apply the patch for the Scanner Horizontal Pod Autoscaler. ++ +[source,terminal] +---- +$ oc -n stackrox patch hpa/scanner -p '{"spec":{"minReplicas":2}}' +---- +. Update the Scanner image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/scanner scanner=registry.redhat.io/advanced-cluster-security/rhacs-scanner-rhel8:{rhacs-version} +---- +. Update the Scanner database image: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/scanner-db db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version} init-db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version} +---- +. Optional: If you have installed Istio in your cluster, run the following additional command: ++ +[source,terminal] +---- +$ oc -n stackrox create -f - <<EOF +apiVersion: networking.istio.io/v1alpha3 +kind: DestinationRule +metadata: + name: scanner-internal-no-istio-mtls + namespace: stackrox + labels: + app.kubernetes.io/name: stackrox + annotations: + stackrox.io/description: "Disable Istio mTLS for ports 8080 and 8443, since StackRox services use built-in mTLS." +spec: + host: scanner.stackrox.svc.cluster.local + trafficPolicy: + portLevelSettings: + - port: + number: 8080 + tls: + mode: DISABLE + - port: + number: 8443 + tls: + mode: DISABLE +--- +apiVersion: networking.istio.io/v1alpha3 +kind: DestinationRule +metadata: + name: scanner-db-internal-no-istio-mtls + namespace: stackrox + labels: + app.kubernetes.io/name: stackrox + annotations: + stackrox.io/description: "Disable Istio mTLS for port 5432, since StackRox services use built-in mTLS." +spec: + host: scanner-db.stackrox.svc.cluster.local + trafficPolicy: + portLevelSettings: + - port: + number: 5432 + tls: + mode: DISABLE +EOF +---- + +.Verification + +* Check that the new pods have deployed: ++ +[source,terminal] +---- +$ oc get deploy -n stackrox -o wide +---- ++ +[source,terminal] +---- +$ oc get pod -n stackrox --watch +---- diff --git a/modules/upgrade-scanner-roxctl-371.adoc b/modules/upgrade-scanner-roxctl-371.adoc new file mode 100644 index 000000000000..5d606e6f6529 --- /dev/null +++ b/modules/upgrade-scanner-roxctl-371.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// */upgrading/upgrade-scanner.adoc +:_mod-docs-content-type: PROCEDURE +[id="upgrade-scanner-roxctl-371_{context}"] += Upgrading to RHACS version 3.71 + +If you are upgrading to {product-title-short} 3.71 using the `roxctl` CLI and YAML files, you need to perform some additional steps. The Scanner DB image no longer mounts the `scanner-db-password` Kubernetes Secret into the `db` Scanner DB container. Instead, `scanner-db-password` is only used in the init container, `init-db`. Therefore, you must add the `POSTGRES_PASSWORD_FILE` environment variable to the init container configuration. The init container must also mount the `scanner-db-tls-volume` and `scanner-db-password` volumes. The following section provides the upgrade steps for {product-title-short} if you are using {ocp} or Kubernetes. For more information about init containers, see the link:https://kubernetes.io/docs/concepts/workloads/pods/init-containers/[Kubernetes documentation]. + +.Prerequisites + +* This procedure assumes the `db` container in the Scanner DB configuration is at `index 0`, which is the first entry in the `containers` list; and the `scanner-db-password` volume mount is at `index 2`, which is the third entry. + +While this scenario applies to most deployments, check the configuration for Scanner DB before entering these commands. If your values differ, you must adjust the `.../containers/x/volumeMounts/y` value in the following commands. + +.Procedure + +. Apply the patch: +* If you use {ocp}, enter the following command: ++ +[source,terminal] +---- +$ oc -n stackrox patch deployment.apps/scanner-db --patch '{"spec":{"template":{"spec":{"initContainers":[{"name":"init-db","env":[{"name":"POSTGRES_PASSWORD_FILE","value":"/run/secrets/stackrox.io/secrets/password"}],"command":["/usr/local/bin/docker-entrypoint.sh","postgres","-c","config_file=/etc/postgresql.conf"],"volumeMounts":[{"name":"db-data","mountPath":"/var/lib/postgresql/data"},{"name":"scanner-db-tls-volume","mountPath":"/run/secrets/stackrox.io/certs","readOnly":true},{"name":"scanner-db-password","mountPath":"/run/secrets/stackrox.io/secrets","readOnly":true}],"securityContext":{"runAsGroup":70,"runAsNonRoot":true,"runAsUser":70}}]}}}}' +---- +* If you use Kubernetes, enter the following command: ++ +[source,terminal] +---- +$ kubectl -n stackrox patch deployment.apps/scanner-db --patch '{"spec":{"template":{"spec":{"initContainers":[{"name":"init-db","env":[{"name":"POSTGRES_PASSWORD_FILE","value":"/run/secrets/stackrox.io/secrets/password"}],"command":["/usr/local/bin/docker-entrypoint.sh","postgres","-c","config_file=/etc/postgresql.conf"],"volumeMounts":[{"name":"db-data","mountPath":"/var/lib/postgresql/data"},{"name":"scanner-db-tls-volume","mountPath":"/run/secrets/stackrox.io/certs","readOnly":true},{"name":"scanner-db-password","mountPath":"/run/secrets/stackrox.io/secrets","readOnly":true}],"securityContext":{"runAsGroup":70,"runAsNonRoot":true,"runAsUser":70}}]}}}}' +---- +. Remove the path: +* If you use {ocp}, enter the following command: ++ +[source,terminal] +---- +$ oc -n stackrox patch deployment.apps/scanner-db --type json --patch '[{"op":"remove","path":"/spec/template/spec/containers/0/volumeMounts/2"}]' +---- +* If you use Kubernetes, enter the following command: ++ +[source,terminal] +---- +$ kubectl -n stackrox patch deployment.apps/scanner-db --type json --patch '[{"op":"remove","path":"/spec/template/spec/containers/0/volumeMounts/2"}]' +---- diff --git a/modules/upgrade-scanner.adoc b/modules/upgrade-scanner.adoc new file mode 100644 index 000000000000..e8ec3db2c81d --- /dev/null +++ b/modules/upgrade-scanner.adoc @@ -0,0 +1,91 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-44.adoc +:_mod-docs-content-type: PROCEDURE +[id="upgrade-scanner_{context}"] += Upgrading Scanner + +You can update Scanner to the latest version by using the `roxctl` CLI. + +.Prerequisites +* If you deploy images from a private image registry, you must first push the new image into your private registry, then edit the commands in the following section to use the name of your private image registry. + +.Procedure +. If you have created custom scanner configurations, you must apply those changes before updating the scanner configuration file. +.. Generate Scanner using the following `roxctl` command: ++ +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" scanner generate +---- +.. Apply the TLS secrets YAML file: +* If you use {ocp}, enter the following command: ++ +[source,terminal] +---- +$ oc apply -f scanner-bundle/scanner/02-scanner-03-tls-secret.yaml +---- +* If you use Kubernetes, enter the following command: ++ +[source,terminal] +---- +$ kubectl apply -f scanner-bundle/scanner/02-scanner-03-tls-secret.yaml +---- +.. Apply the Scanner configuration YAML file: +* If you use {ocp}, enter the following command: ++ +[source,terminal] +---- +$ oc apply -f scanner-bundle/scanner/02-scanner-04-scanner-config.yaml +---- +* If you use Kubernetes, enter the following command: ++ +[source,terminal] +---- +$ kubectl apply -f scanner-bundle/scanner/02-scanner-04-scanner-config.yaml +---- +. Update the Scanner image: +* If you use {ocp}, enter the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/scanner scanner=registry.redhat.io/advanced-cluster-security/rhacs-scanner-rhel8:{rhacs-version} +---- +* If you use Kubernetes, enter the following command: ++ +[source,terminal,subs=attributes+] +---- +$ kubectl -n stackrox set image deploy/scanner scanner=registry.redhat.io/advanced-cluster-security/rhacs-scanner-rhel8:{rhacs-version} +---- + +. Update the Scanner database image: +* If you use {ocp}, enter the following command: ++ +[source,terminal,subs=attributes+] +---- +$ oc -n stackrox set image deploy/scanner-db db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version} init-db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version} +---- +* If you use Kubernetes, enter the following command: ++ +[source,terminal,subs=attributes+] +---- +$ kubectl -n stackrox set image deploy/scanner-db db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version} init-db=registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:{rhacs-version} +---- + +.Verification + +* Check that the new pods have deployed successfully: + +** If you use {ocp}, enter the following command: ++ +[source,terminal] +---- +$ oc get pod -n stackrox --watch +---- + +** If you use Kubernetes, enter the following command: ++ +[source,terminal] +---- +$ kubectl get pod -n stackrox --watch +---- diff --git a/modules/upi-installation-considerations.adoc b/modules/upi-installation-considerations.adoc deleted file mode 100644 index 3696bf6071f4..000000000000 --- a/modules/upi-installation-considerations.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-installations.adoc - -[id="upi-installation-considerations_{context}"] -= User-provisioned infrastructure installation considerations - -The default installation method uses installer-provisioned infrastructure. With installer-provisioned infrastructure clusters, {product-title} manages all aspects of the cluster, including the operating system itself. If possible, use this feature to avoid having to provision and maintain the cluster infrastructure. - -You can alternatively install {product-title} {product-version} on infrastructure that you provide. If you use this installation method, follow user-provisioned infrastructure installation documentation carefully. Additionally, review the following considerations before the installation: - -* Check the link:https://access.redhat.com/ecosystem/search/#/ecosystem/Red%20Hat%20Enterprise%20Linux[{op-system-base-full} Ecosystem] to determine the level of {op-system-first} support provided for your chosen server hardware or virtualization technology. - -* Many virtualization and cloud environments require agents to be installed on guest operating systems. Ensure that these agents are installed as a containerized workload deployed through a daemon set. - -* Install cloud provider integration if you want to enable features such as dynamic storage, on-demand service routing, node host name to Kubernetes host name resolution, and cluster autoscaling. -+ -[NOTE] -==== -It is not possible to enable cloud provider integration in {product-title} environments that mix resources from different cloud providers, or that span multiple physical or virtual platforms. The node life cycle controller will not allow nodes that are external to the existing provider to be added to a cluster, and it is not possible to specify more than one cloud provider integration. -==== - -* A provider-specific Machine API implementation is required if you want to use machine sets or autoscaling to automatically provision {product-title} cluster nodes. - -* Check whether your chosen cloud provider offers a method to inject Ignition configuration files into hosts as part of their initial deployment. If they do not, you will need to host Ignition configuration files by using an HTTP server. The steps taken to troubleshoot Ignition configuration file issues will differ depending on which of these two methods is deployed. - -* Storage needs to be manually provisioned if you want to leverage optional framework components such as the embedded container registry, ElasticSearch, or Prometheus. Default storage classes are not defined in user-provisioned infrastructure installations unless explicitly configured. - -* A load balancer is required to distribute API requests across all master nodes in highly available {product-title} environments. You can use any TCP-based load balancing solution that meets {product-title} DNS routing and port requirements. diff --git a/modules/upload-definitions-to-central-admin-pass.adoc b/modules/upload-definitions-to-central-admin-pass.adoc new file mode 100644 index 000000000000..4bff1a0be350 --- /dev/null +++ b/modules/upload-definitions-to-central-admin-pass.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: PROCEDURE +[id="upload-definitions-to-central-admin-pass_{context}"] += Uploading definitions to Central by using the administrator password + +You can upload the vulnerability definitions database that Scanner uses to Central by using your {product-title} administrator password. + +.Prerequisites + +* You must have the administrator password. +* You must have installed the `roxctl` command-line interface (CLI). + +.Procedure + +. Set the `ROX_CENTRAL_ADDRESS` environment variable: ++ +[source,terminal] +---- +$ export ROX_CENTRAL_ADDRESS=<address>:<port_number> +---- +. Run the following command to upload the definitions file: ++ +[source,terminal] +---- +$ roxctl scanner upload-db \ + -p <your_administrator_password> \ + -e "$ROX_CENTRAL_ADDRESS" \ + --scanner-db-file=<compressed_scanner_definitions.zip> +---- diff --git a/modules/upload-definitions-to-central-api-token.adoc b/modules/upload-definitions-to-central-api-token.adoc new file mode 100644 index 000000000000..224e2b2f2b1d --- /dev/null +++ b/modules/upload-definitions-to-central-api-token.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: PROCEDURE +[id="upload-definitions-to-central-api-token_{context}"] += Uploading definitions to Central by using an API token + +You can upload the vulnerability definitions database that Scanner uses to Central by using an API token. + +.Prerequisites + +* You must have an API token with the administrator role. +* You must have installed the `roxctl` command-line interface (CLI). + +.Procedure + +. Set the `ROX_API_TOKEN` and the `ROX_CENTRAL_ADDRESS` environment variables: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN=<api_token> +---- ++ +[source,terminal] +---- +$ export ROX_CENTRAL_ADDRESS=<address>:<port_number> +---- +. Run the following command to upload the definitions file: ++ +[source,terminal] +---- +$ roxctl scanner upload-db \ + -e "$ROX_CENTRAL_ADDRESS" \ + --scanner-db-file=<compressed_scanner_definitions.zip> +---- + diff --git a/modules/upload-kernel-support-package-to-central.adoc b/modules/upload-kernel-support-package-to-central.adoc new file mode 100644 index 000000000000..ccd49b4f870f --- /dev/null +++ b/modules/upload-kernel-support-package-to-central.adoc @@ -0,0 +1,42 @@ +// Module included in the following assemblies: +// +// * configuration/enable-offline-mode.adoc +:_mod-docs-content-type: PROCEDURE +[id="upload-kernel-support-package-to-central_{context}"] += Uploading kernel support packages to Central + +You can upload the kernel support packages containing probes for all recent and supported Linux kernel versions to Central. + +.Prerequisites + +* You must have an API token with the administrator role. +* You must have installed the `roxctl` command-line interface (CLI). + +.Procedure + +. Set the `ROX_API_TOKEN` and the `ROX_CENTRAL_ADDRESS` environment variables: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN=<api_token> +---- ++ +[source,terminal] +---- +$ export ROX_CENTRAL_ADDRESS=<address>:<port_number> +---- +. Run the following command to upload the kernel support packages: ++ +[source,terminal] +---- +$ roxctl collector support-packages upload <package_file> \ + -e "$ROX_CENTRAL_ADDRESS" +---- + +[NOTE] +==== +* When you upload a new support package that includes content uploaded to Central previously, only new files are uploaded. +* When you upload a new support package that includes files with the same name but different contents than those present on the Central, `roxctl` shows a warning message and does not overwrite files. +** You can use the `--overwrite` option with the upload command to overwrite the files. +* When you upload a support package that contains a required probe, Central does not make any outbound requests (to the internet) for downloading this probe. Central uses the probe from the support package. +==== diff --git a/modules/use-global-search.adoc b/modules/use-global-search.adoc new file mode 100644 index 000000000000..3498381a633e --- /dev/null +++ b/modules/use-global-search.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * operating/search-filter.adoc +:_mod-docs-content-type: CONCEPT +[id="use-global-search_{context}"] += Using global search + +By using global search you can search across all resources in your environment. Based on the resource type you use in your search query, the results are grouped in the following categories: + +* All results (Lists matching results across all categories) +* Clusters +* Deployments +* Images +* Namespaces +* Nodes +* Policies +* Policy categories ^[1]^ +* Roles +* Role bindings +* Secrets +* Service accounts +* Users and groups +* Violations + +[.small] +-- +1. The *Policy categories* option is only available if you use the following: +* PostgreSQL as a backend database in {rh-rhacs-first}. +* {rh-rhacscs-first}. +-- + +These categories are listed as a table on the {product-title-short} portal global search page and you can click on the category name to identify results belonging to the selected category. + +To do a global search, in the {product-title-short} portal, select *Search*. \ No newline at end of file diff --git a/modules/use-local-page-filtering.adoc b/modules/use-local-page-filtering.adoc new file mode 100644 index 000000000000..54198f825614 --- /dev/null +++ b/modules/use-local-page-filtering.adoc @@ -0,0 +1,8 @@ +// Module included in the following assemblies: +// +// * operating/search-filter.adoc +:_mod-docs-content-type: CONCEPT +[id="use-local-page-filtering_{context}"] += Using local page filtering + +You can use local page filtering from within all views in the {product-title-short} portal. Local page filtering works similar to the global search, but only relevant attributes are available. You can select the search bar to show all available attributes for a specific view. diff --git a/modules/use-network-baselining-ng20.adoc b/modules/use-network-baselining-ng20.adoc new file mode 100644 index 000000000000..c8fc9b45abdc --- /dev/null +++ b/modules/use-network-baselining-ng20.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="use-network-baselining-ng20_{context}"] += About network baselining in the network graph + +[role="_abstract"] +In {product-title-short}, you can minimize your risks by using network baselining. +It is a proactive approach to keep your infrastructure secure. +{product-title-short} first discovers existing network flows and creates a baseline, and then it treats network flows outside of this baseline as anomalous. + +When you install {product-title-short}, there is no default network baseline. +As {product-title-short} discovers network flows, it creates a baseline and then it adds all discovered network flows to it, following these guidelines: + +* When {product-title-short} discovers new network activity, it adds that network flow to the network baseline. +* Network flows do not show up as anomalous flows and do not trigger any violations. + +After the discovery phase, the following actions occur: + +* {product-title-short} stops adding network flows to the network baselines. +* New network flows that are not in the network baseline show up as anomalous flows but they do not trigger any violations. diff --git a/modules/use-process-baselines.adoc b/modules/use-process-baselines.adoc new file mode 100644 index 000000000000..95e703be4379 --- /dev/null +++ b/modules/use-process-baselines.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: CONCEPT +[id="use-process-baselines_{context}"] += Using process baselines + +[role="_abstract"] +You can minimize risk by using process baselining for infrastructure security. With this approach, {product-title} first discovers existing processes and creates a baseline. +Then it operates in the default deny-all mode and only allows processes listed in the baseline to run. + +== Process baselines + +When you install {product-title}, there is no default process baseline. +As {product-title} discovers deployments, it creates a process baseline for every container type in a deployment. +Then it adds all discovered processes to their own process baselines. + +== Process baseline states + +During the process discovery phase, all baselines are in an unlocked state. + +In an *unlocked* state: + +* When {product-title} discovers a new process, it adds that process to the process baseline. +* Processes do not show up as risks and do not trigger any violations. + +After an hour from when {product-title} receives the first process indicator from a container in a deployment, it finishes the process discovery phase. +At this point: + +* {product-title} stops adding processes to the process baselines. +* New processes that are not in the process baseline show up as risks, but they do not by default trigger any violations. + +To generate violations, you must either manually lock the process baseline, or enable process baseline auto-lock feature. +//See <<lock-and-unlock-process-baselines,Manually Lock and unlock process baselines>> for more details about manually locking and unlocking process baselines. +//See <<auto-lock-process-baselines,Auto-lock process baselines>> for more details about enabling the process baselines auto-lock feature. +//See <<auto-lock-process-baselines-known-limitations,Auto-lock process baselines known limitations>> for information how enabling the process baselines auto-lock feature may degrade performance. +//See <<bulk-locking-and-unlocking-process-baselines,Bulk locking and unlocking process baselines>> for information on how to manually lock or unlock process baselines in bulk. + +In a *locked* state: + +* {product-title} stops adding processes to the process baselines. +* New processes that are not in the process baseline trigger violations. + +Independent of the locked or unlocked baseline state, you can always add or remove processes from the baseline. + +[NOTE] +==== +For a deployment, if each pod has multiple containers in it, {product-title} creates a process baseline for each container type. +For such a deployment, if some baselines are locked and some are unlocked, the baseline status for that deployment shows up as *Mixed*. +==== diff --git a/modules/use-signature-verification.adoc b/modules/use-signature-verification.adoc new file mode 100644 index 000000000000..e7af26f6fc9b --- /dev/null +++ b/modules/use-signature-verification.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/verify-image-signatures.adoc +:_mod-docs-content-type: PROCEDURE +[id="use-signature-verification_{context}"] += Using signature verification in a policy + +When creating custom security policies, you can use the *Trusted image signers* policy criteria to verify image signatures. + +.Prerequisites + +* You must have already configured a signature integration with at least 1 Cosign public key. + +.Procedure + +. When creating or editing a policy, drag the *Not verified by trusted image signers* policy criteria in the policy field drop area for the *Policy criteria* section. +. Click *Select*. +. Select the trusted image signers from the list and click *Save*. diff --git a/modules/user-agent-configuring.adoc b/modules/user-agent-configuring.adoc deleted file mode 100644 index 7d2d8a11ba8a..000000000000 --- a/modules/user-agent-configuring.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring_user_agent.adoc - -[id="user-agent-configuring_{context}"] -= Configuring the user agent - -As an administrator, you can prevent clients from accessing the -API with the `userAgentMatching` configuration setting of a master -configuration. - - -.Procedure - -* Modify the master configuration file to include the user agent configuration. -For example, the following user agent denies the Kubernetes 1.2 client binary, -OKD 1.1.3 binary, and the POST and PUT `httpVerbs`: -+ -[source,yaml] ----- -policyConfig: - userAgentMatchingConfig: - defaultRejectionMessage: "Your client is too old. Go to https://example.org to update it." - deniedClients: - - regex: '\w+/v(?:(?:1\.1\.1)|(?:1\.0\.1)) \(.+/.+\) openshift/\w{7}' - - regex: '\w+/v(?:1\.1\.3) \(.+/.+\) openshift/\w{7}' - httpVerbs: - - POST - - PUT - - regex: '\w+/v1\.2\.0 \(.+/.+\) kubernetes/\w{7}' - httpVerbs: - - POST - - PUT - requiredClients: null ----- -+ -The following example denies clients that do not exactly match an expected -client: -+ -[source,yaml] ----- -policyConfig: - userAgentMatchingConfig: - defaultRejectionMessage: "Your client is too old. Go to https://example.org to update it." - deniedClients: [] - requiredClients: - - regex: '\w+/v1\.1\.3 \(.+/.+\) openshift/\w{7}' - - regex: '\w+/v1\.2\.0 \(.+/.+\) kubernetes/\w{7}' - httpVerbs: - - POST - - PUT ----- diff --git a/modules/user-agent-overview.adoc b/modules/user-agent-overview.adoc deleted file mode 100644 index 413a57300453..000000000000 --- a/modules/user-agent-overview.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * authentication/configuring_user_agent.adoc - - -[id="user-agent-overview_{context}"] -= About the user agent - -{product-title} implements a user agent that can be used to prevent an -application developer's CLI accessing the {product-title} API. If a client uses -a particular library or binary file, they cannot access the {product-title} API. - -You construct user agents for the {product-title} CLI from a set of values -within {product-title}: - -[source,terminal] ----- -<command>/<version> (<platform>/<architecture>) <client>/<git_commit> ----- - -For example, when: - -* `<command>` = `oc` -* `<version>` = The client version. For example, `v4.3.0`. Requests made against the Kubernetes -API at `/api` receive the Kubernetes version, while requests made against the -{product-title} API at `/oapi` receive the {product-title} version (as specified -by `oc version`) -* `<platform>` = `linux` -* `<architecture>` = `amd64` -* `<client>` = `openshift`, or `kubernetes` depending on if the request is made against the Kubernetes API at `/api`, or the {product-title} API at `/oapi` -* `<git_commit>` = The Git commit of the client version (for example, `f034127`) - -the user agent is: - -[source,terminal] ----- -oc/v3.3.0 (linux/amd64) openshift/f034127 ----- diff --git a/modules/using-an-authentication-provider-to-authenticate-with-roxctl.adoc b/modules/using-an-authentication-provider-to-authenticate-with-roxctl.adoc new file mode 100644 index 000000000000..652bad42652c --- /dev/null +++ b/modules/using-an-authentication-provider-to-authenticate-with-roxctl.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// * cli/getting-started-cli.adoc +:_mod-docs-content-type: PROCEDURE +[id="using-an-authentication-provider-to-authenticate-with-roxctl_{context}"] += Using an authentication provider to authenticate with roxctl + +[role="_abstract"] +You can configure an authentication provider in Central and initiate the login process with the `roxctl` CLI. +Set the `ROX_ENDPOINT` variable, initiate the login process with the `roxctl central login` command, select the authentication provider in a browser window, and retrieve the token information from the `roxctl` CLI as described in the following procedure. + + +.Prerequisite + +* You selected an authentication provider of your choice, such as OpenID Connect (OIDC) with fragment or query mode. + +.Procedure + +. Run the following command to set the `ROX_ENDPOINT` variable to Central hostname and port: ++ +[source,terminal,subs="+quotes"] +---- +export ROX_ENDPOINT=_<central_hostname:port>_ +---- + +. Run the following command to initiate the login process to Central: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl central login +---- + +. Within the `roxctl` CLI, a URL is printed as output and you are redirected to a browser window where you can select the authentication provider you want to use. + +. Log in with your authentication provider. ++ +After you have successfully logged in, the browser window indicates that authentication was successful and you can close the browser window. + +. The `roxctl` CLI displays your token information including details such as the access token, the expiration time of the access token, the refresh token if one has been issued, and notification that these values are stored locally. ++ +.Example output ++ +[source,terminal] +---- +Please complete the authorization flow in the browser with an auth provider of your choice. +If no browser window opens, please click on the following URL: + http://127.0.0.1:xxxxx/login + +INFO: Received the following after the authorization flow from Central: +INFO: Access token: <redacted> <1> +INFO: Access token expiration: 2023-04-19 13:58:43 +0000 UTC <2> +INFO: Refresh token: <redacted> <3> +INFO: Storing these values under $HOME/.roxctl/login… <4> +---- +<1> The access token. +<2> The expiration time of the access token. +<3> The refresh token. +<4> The directory where values of the access token, the access token expiration time, and the refresh token are stored locally. ++ +[IMPORTANT] +==== +Ensure that you set the environment to determine the directory where the configuration is stored. By default, the configuration is stored in the `$HOME/.roxctl/roxctl-config` directory. + +* If you set the `$ROX_CONFIG_DIR` environment variable, the configuration is stored in the `$ROX_CONFIG_DIR/roxctl-config` directory. This option has the highest priority. + +* If you set the `$XDG_RUNTIME_DIR` environment variable and the `$ROX_CONFIG_DIR` variable is not set, the configuration is stored in the `$XDG_RUNTIME_DIR /roxctl-config` directory. + +* If you do not set the `$ROX_CONFIG_DIR` or `$XDG_RUNTIME_DIR` environment variable, the configuration is stored in the `$HOME/.roxctl/roxctl-config` directory. +==== \ No newline at end of file diff --git a/modules/using-cli.adoc b/modules/using-cli.adoc new file mode 100644 index 000000000000..8a39ec1777d0 --- /dev/null +++ b/modules/using-cli.adoc @@ -0,0 +1,293 @@ +// Module included in the following assemblies: +// +// * cli/using-roxctl-cli.adoc +:_mod-docs-content-type: CONCEPT +[id="using-cli_{context}"] += Using the roxctl CLI + +Review the following sections to learn how to complete common tasks using the CLI. + +[NOTE] +==== + +* Export the following variables before using these commands: ++ +[source,terminal] +---- +$ export ROX_API_TOKEN=<api_token> +---- ++ +[source,terminal] +---- +$ export ROX_CENTRAL_ADDRESS=<address>:<port_number> +---- + +* You can use the `--help` option to get more information about the commands. + +* In {product-title-managed}, when using `roxctl` commands that require the Central address, use the *Central instance address* as displayed in the *Instance Details* section of the {cloud-console}. For example, use `acs-ABCD12345.acs.rhcloud.com` instead of `acs-data-ABCD12345.acs.rhcloud.com`. +==== + +[id="manage-central-db_{context}"] +== Managing Central's database +Central stores information about: + +* Activity observed in your clusters, +* Information retrieved from integrated image registries or scanners, and +* {product-title} configuration. +//TODO Add links to registries and scanners + +You can back up and restore Central's database by using the `roxctl` CLI. + +=== Backing up Central database + +Run the following command to back up Central's database: +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central backup +---- + +=== Restoring Central database + +Run the following command to restore Central's database: +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central db restore <backup_filename> +---- + +[id="manage-secure-clusters_{context}"] +== Managing secured clusters + +To secure a Kubernetes or an {ocp} cluster, you must deploy {product-title} services into the cluster. +You can generate deployment files in the {product-title-short} portal by selecting *Platform Configuration* -> *Clusters*, or you can use the `roxctl` CLI. + +=== Generating Sensor deployment files + +.Kubernetes + +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate k8s --name <cluster_name> --central "$ROX_CENTRAL_ADDRESS" +---- + +.{ocp} + +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" sensor generate openshift --openshift-version <ocp-version> --name <cluster_name> --central "$ROX_CENTRAL_ADDRESS" <1> +---- +<1> For the `--openshift-version` option specify the major {ocp} version number for your cluster. For example, specify `3` for {ocp} version `3.x` and specify `4` for {ocp} version `4.x`. + +Read the `--help` output to see other options that you might need to use depending on your system architecture. + +Verify that the endpoint you provide for `--central` can be reached from the cluster where you are deploying {product-title} services. + +[NOTE] +==== +If you are using a non-gRPC capable load balancer, such as HAProxy, AWS Application Load Balancer (ALB), or AWS Elastic Load Balancing (ELB): + +* Use the WebSocket Secure (`wss`) protocol. +To use `wss`, prefix the address with *`wss://`*, and +* Add the port number after the address, for example: ++ +[source,terminal] +---- +$ roxctl sensor generate k8s --central wss://stackrox-central.example.com:443 +---- +==== + +=== Installing Sensor by using the generate YAML files +When you generate the Sensor deployment files, `roxctl` creates a directory called `sensor-<cluster_name>` in your working directory. The script to install Sensor is present in this directory. Run the sensor installation script to install Sensor. + +[source,terminal] +---- +$ ./sensor-<cluster_name>/sensor.sh +---- + +If you get a warning that you do not have the required permissions to install Sensor, follow the on-screen instructions, or contact your cluster administrator for help. + +=== Downloading Sensor bundle for existing clusters + +Use the following command to download Sensor bundles for existing clusters by specifying a cluster name or ID. + +[source,terminal] +---- +$ roxctl sensor get-bundle <cluster_name_or_id> +---- + +=== Deleting cluster integration + +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" cluster delete --name=<cluster_name> +---- + +[IMPORTANT] +==== +Deleting cluster integration will not remove {product-title} services running in the cluster. +You can remove them by running the `delete-sensor.sh` script from the Sensor installation bundle. +==== + +[id="check-policy-compliance_{context}"] +== Checking policy compliance + +You can use the `roxctl` CLI to check deployment YAML files and images for policy compliance. + +=== Configuring output format +When you check policy compliance by using the `deployment check`, `image check`, or `image scan` commands, you can specify the output format by using the `-o` option. This option determines how the output of a command is displayed in the terminal. + +You can change the output format by adding the `-o` option to the command and specifying the format as `json`, `table`, `csv`, or `junit`. + +For example, the following command checks a deployment and then displays the result in `csv` format: +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" \ + deployment check --file =<yaml_filename> \ + -o csv +---- + +[NOTE] +==== +When you do not specify the `-o` option for the output format, the following default behavior is used: + +* The format for the `deployment check` and the `image check` commands is `table`. +* The default output format for the `image scan` command is `json`. This is the old JSON format output for compatibility with older versions of the CLI. To get the output in the new JSON format, specify the option with format, as `-o json`. +==== + +Different options are available to configure the output. The following table lists the options and the format in which they are available. + +[%header,cols="1,2,1"] +|=== +|Option +|Description +|Formats + +|`--compact-output` +|Use this option to display the JSON output in a compact format. +|`json` + +|`--headers` +|Use this option to specify custom headers. +|`table` and `csv` + +|`--no-header` +|Use this option to omit the header row from the output. +|`table` and `csv` + +|`--row-jsonpath-expressions` +a|Use this option to specify link:https://github.com/tidwall/gjson[GJSON paths] to select specific items from the output. For example, to get the *Policy name* and *Severity* for a deployment check, use the following command: +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" \ + deployment check --file=<yaml_filename> \ + -o table --headers POLICY-NAME,SEVERITY \ + --row-jsonpath-expressions="{results.#.violatedPolicies.#.name,results.#.violatedPolicies.#.severity}" +---- +|`table` and `csv` + +|`--merge-output` +|Use this options to merge table cells that have the same value. +|`table` + +|`headers-as-comment` +|Use this option to include the header row as a comment in the output. +|`csv` + +|`--junit-suite-name` +|Use this option to specify the name of the JUnit test suite. +|`junit` + +|=== + +=== Checking deployment YAML files + +The following command checks build-time and deploy-time violations of your security policies in YAML deployment files. +//TODO: Add link to security policies section +Use this command to validate: + +* Configuration options in a YAML file, such as resource limits or privilege options; +or +* Aspects of the images used in a YAML file, such as components or vulnerabilities. + +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" deployment check --file=<yaml_filename> +---- + +=== Checking images + +The following command checks build-time violations of your security policies in images. +//TODO: Add link to security policy section +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" image check --image=<image_name> +---- + +=== Checking image scan results + +You can also check the scan results for specific images. + +The following command returns the components and vulnerabilities found in the image in JSON format. +The format is defined in the API reference. +//TODO: Add link to the API reference. + +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" image scan --image <image_name> +---- + +To cause {product-title} to re-pull image metadata and image scan results from the associated registry and scanner, add the `--force` option. + +[NOTE] +==== +To check specific image scan results, you must have a token with both `read` and `write` permissions for the `Image` resource. +The default *Continuous Integration* system role already has the required permissions. +//TODO: Add link to the system role topic. +==== + +[id="debug-issues_{context}"] +== Debugging issues + +=== Managing Central log level + +Central saves information to its container logs. + +==== Viewing the logs +You can see the container logs for Central by running: + +.Kubernetes +[source,terminal] +---- +$ kubectl logs -n stackrox <central_pod> +---- + +.{ocp} +[source,terminal] +---- +$ oc logs -n stackrox <central_pod> +---- + +==== Viewing current log level +You can change the log level to see more or less information in Central logs. +Run the following command to view the current log level: +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log +---- + +==== Changing the log level +Run the following command to change the log level: + +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level=<log_level> <1> +---- +<1> The acceptable values for `<log_level>` are `Panic`, `Fatal`, `Error`, `Warn`, `Info`, and `Debug`. + +=== Retrieving debugging information + +To gather debugging information for investigating issues, run the following command: + +[source,terminal] +---- +$ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump +---- diff --git a/modules/using-must-gather.adoc b/modules/using-must-gather.adoc deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/modules/using-regular-expression.adoc b/modules/using-regular-expression.adoc new file mode 100644 index 000000000000..415f5e0f592f --- /dev/null +++ b/modules/using-regular-expression.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// * operating/create-use-collections.adoc +:_mod-docs-content-type: CONCEPT +[id="using-regular-expression_{context}"] += Using regular expressions + +{product-title-short} uses regular expressions in some areas of the portal, including when you configure collections to include or exclude deployments. + +For example, when configuring a collection, you can use regular expressions to search for a deployment. This option is useful if you do not know the exact name of the deployment. A regular expression is a string of letters, numbers, and symbols that defines a pattern. {product-title-short} uses this pattern to match characters or groups of characters and return results. For regular expressions, note the following guidelines: + +* link:https://github.com/google/re2/wiki/Syntax[RE2 syntax] is supported. +* Perl syntax is not supported. +* Testing your regular expressions syntax is helpful, for example, by using a site such as link:https://regex101.com/[https://regex101.com/]. Select *Golang* as the flavor. + +[NOTE] +==== +The following examples assume naming conventions are followed where production clusters contain the word `prod` in the name. +==== + +.Regular expressions example to create a collection of production clusters + +. In *Collection rules*, select *Clusters with names matching*. +. From the drop-down list, select *A regex value of* and enter the following text: ++ +---- +^prod.* +---- + +.Regular expressions example to create a collection of non-production clusters + +With RE2 syntax, you cannot match by using negative lookahead, meaning that you cannot direct regular expressions to match if an element is *not* present. As a workaround, you can use regular expressions to match when the word `prod` does not appear in the cluster name; that is, to match if the letters `p`, `r`, `o`, and `d` do not appear in sequence. + +. In *Collection rules*, select *Clusters with names matching*. +. From the drop-down list, select *A regex value of* and enter the following text: ++ +---- +^[^p]*(p([^r]|$|r([^o]|$|o([^d]|$))))*[^p]*$ +---- + +.Regular expressions example to create a collection that matches all entities in the cluster, namespace, and deployments hierarchy + +. In *Collection rules*, select *Deployments with names matching*. +.. From the drop-down list, select *A regex value of* and enter `.*`. +. Select *Namespaces with names matching*. +.. From the drop-down list, select *A regex value of* and enter `.*`. +. Select *Clusters with names matching*. +.. From the drop-down list, select *A regex value of* and enter `.*`. + +.Regular expressions example to create a collection that includes a named deployment and database and specific labels + +The following example provides the steps for configuring a collection for a medical application. In this example, you want your collection to include the `reporting` deployment, a database called `patient-db`, and you want to select namespaces with labels where `key = kubernetes.io/metadata.name` and `value = medical`. For this example, perform the following steps: + +. In *Collection rules*, select *Deployments with names matching*. +. Click *An exact value of* and enter *reporting*. +. Click *OR*. +. Click *A regex value of* and enter `.*-db` to select all deployments with a name ending in `db` in your environment. The `regex value` option uses regular expressions for pattern matching. For regular expressions, link:https://github.com/google/re2/wiki/Syntax[RE2 syntax] is supported. Perl syntax is not supported. The panel on the right might display databases that you do not want to include. You can exclude those databases by using additional filters. For example: +.. Filter by namespace labels by clicking *Namespaces with labels matching exactly* and entering `kubernetes.io/metadata.name=medical` to include only deployments in the namespace that is labeled `medical`. +.. If you know the name of the namespace, click *Namespaces with names matching* and enter the name. \ No newline at end of file diff --git a/modules/using-the-build-time-network-policy-generator.adoc b/modules/using-the-build-time-network-policy-generator.adoc new file mode 100644 index 000000000000..9ddedda871fb --- /dev/null +++ b/modules/using-the-build-time-network-policy-generator.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * cli/generating-build-time-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="using-the-build-time-network-policy-generator_{context}"] += Using the build-time network policy generator + +[role="_abstract"] +The build-time network policy generator is included in the `roxctl` CLI. +For the build-time network policy generation feature, `roxctl` CLI does not need to communicate with {product-title-short} Central so you can use it in any development environment. + +.Prerequisites +. The build-time network policy generator recursively scans the directory you specify when you run the command. +Therefore, before you run the command, you must already have service manifests, config maps, and workload manifests such as `Pod`, `Deployment`, `ReplicaSet`, `Job`, `DaemonSet`, and `StatefulSet` as YAML files in the specified directory. +. Verify that you can apply these YAML files by using the `kubectl apply -f` command. The build-time network policy generator does not work with files that use Helm style templating. +. Verify that the service network addresses are not hard-coded. Every workload that needs to connect to a service must specify the service network address as a variable. You can specify this variable by using the workload's resource environment variable or in a config map. + +** link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/k8s_guestbook/frontend-deployment.yaml#L25:L28[Example 1: Using an environment variable] +** link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/onlineboutique/kubernetes-manifests.yaml#L105:L109[Example 2: Using a config map] +** link:https://github.com/np-guard/cluster-topology-analyzer/blob/main/tests/onlineboutique/kubernetes-manifests.yaml#L269:L271[Example 3: Using a config map] +. Service network addresses must match the following official regular expression pattern: ++ +---- +(http(s)?://)?<svc>(.<ns>(.svc.cluster.local)?)?(:<portNum>)? <1> +---- ++ +<1> In this pattern, +* <svc> is the service name. +* <ns> is the namespace where you defined the service. +* <portNum> is the exposed service port number. + ++ +Following are some examples that match the pattern: + +* `wordpress-mysql:3306` +* `redis-follower.redis.svc.cluster.local:6379` +* `redis-leader.redis` +* `+http://rating-service.+` + + +.Procedure +. Verify that the build-time network policy generation feature is available by running the help command: ++ +[source,terminal] +---- +$ roxctl netpol generate -h +---- +. Generate the policies by using the `netpol generate` command: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl netpol generate <folder_path> [flags] <1> +---- ++ +<1> Specify the path to the folder, which can include sub-folders that contain YAML resources for analysis. The command scans the entire sub-folder tree. Optionally, you can also specify parameters to change the behavior of the command. diff --git a/modules/using-the-configuration-management-view.adoc b/modules/using-the-configuration-management-view.adoc new file mode 100644 index 000000000000..c043ba9b6eb5 --- /dev/null +++ b/modules/using-the-configuration-management-view.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * operating/review-cluster-configuration.adoc +:_mod-docs-content-type: CONCEPT +[id="using-the-configuration-management-view_{context}"] += Using the Configuration Management view + +[role="_abstract"] +To open the *Configuration Management* view, select *Configuration Management* from the navigation menu. +Similar to the *Dashboard*, it displays some useful widgets. + +These widgets are interactive and show the following information: + +* Security policy violations by severity +* The state of CIS (Center for Information Security) for Kubernetes benchmark controls +* Users with administrator rights in the most clusters +* Secrets used most widely in your clusters + +The header in the *Configuration Management* view shows you the number of policies and CIS controls in your cluster. +[NOTE] +==== +Only policies in the Deploy lifecycle phase are included in the policy count and policy list view. +==== + +The header includes drop-down menus that allow you to switch between entities. +For example, you can: + +* Click *Policies* to view all policies and their severity, or select *CIS Controls* to view detailed information about all controls. +* Click *Application and Infrastructure* and select clusters, namespaces, nodes, deployments, images, and secrets to view detailed information. +* Click *RBAC Visibility and Configuration* and select users and groups, service accounts, and roles to view detailed information. diff --git a/modules/using-the-interactive-installer.adoc b/modules/using-the-interactive-installer.adoc new file mode 100644 index 000000000000..8cf93fa94059 --- /dev/null +++ b/modules/using-the-interactive-installer.adoc @@ -0,0 +1,72 @@ +// Module included in the following assemblies: +// +// * installing/installing_ocp/install-central-ocp.adoc +// * installing/installing_other/install-central-other.adoc +:_mod-docs-content-type: PROCEDURE +[id="using-the-interactive-installer_{context}"] += Using the interactive installer + +[role="_abstract"] +Use the interactive installer to generate the required secrets, deployment configurations, and deployment scripts for your environment. + +.Procedure +. Run the interactive install command: ++ +[source,terminal] +---- +$ roxctl central generate interactive +---- ++ +[IMPORTANT] +==== +Installing {product-title-short} using the `roxctl` CLI creates PodSecurityPolicy (PSP) objects by default for backward compatibility. If you install {product-title-short} on Kubernetes versions 1.25 and newer or {ocp} version 4.12 and newer, you must disable the PSP object creation. To do this, specify `--enable-pod-security-policies` option as `false` for the `roxctl central generate` and `roxctl sensor generate` commands. +==== +. Press *Enter* to accept the default value for a prompt or enter custom values as required. The following example shows the interactive installer prompts: ++ +[source,terminal] +---- +Path to the backup bundle from which to restore keys and certificates (optional): +PEM cert bundle file (optional): <1> +Disable the administrator password (only use this if you have already configured an IdP for your instance) (default: "false"): +Create PodSecurityPolicy resources (for pre-v1.25 Kubernetes) (default: "false"): <2> +Administrator password (default: autogenerated): +Orchestrator (k8s, openshift): +Default container images settings (rhacs, opensource); it controls repositories from where to download the images, image names and tags format (default: "rhacs"): +The directory to output the deployment bundle to (default: "central-bundle"): +Whether to enable telemetry (default: "true"): +The central-db image to use (if unset, a default will be used according to --image-defaults) (default: "registry.redhat.io/advanced-cluster-security/rhacs-central-db-rhel8:4.6.0"): +List of secrets to add as declarative configuration mounts in central (default: "[]"): <3> +The method of exposing Central (lb, np, none) (default: "none"): <4> +The main image to use (if unset, a default will be used according to --image-defaults) (default: "registry.redhat.io/advanced-cluster-security/rhacs-main-rhel8:4.6.0"): +Whether to run StackRox in offline mode, which avoids reaching out to the Internet (default: "false"): +List of config maps to add as declarative configuration mounts in central (default: "[]"): <5> +The deployment tool to use (kubectl, helm, helm-values) (default: "kubectl"): +Istio version when deploying into an Istio-enabled cluster (leave empty when not running Istio) (optional): +The scanner-db image to use (if unset, a default will be used according to --image-defaults) (default: "registry.redhat.io/advanced-cluster-security/rhacs-scanner-db-rhel8:4.6.0"): +The scanner image to use (if unset, a default will be used according to --image-defaults) (default: "registry.redhat.io/advanced-cluster-security/rhacs-scanner-rhel8:4.6.0"): +The scanner-v4-db image to use (if unset, a default will be used according to --image-defaults) (default: "registry.redhat.io/advanced-cluster-security/rhacs-scanner-v4-db-rhel8:4.6.0"): +The scanner-v4 image to use (if unset, a default will be used according to --image-defaults) (default: "registry.redhat.io/advanced-cluster-security/rhacs-scanner-v4-rhel8:4.6.0"): +External volume type (hostpath, pvc): hostpath +Path on the host (default: "/var/lib/stackrox-central"): +Node selector key (e.g. kubernetes.io/hostname): +Node selector value: +---- +<1> If you want to add a custom TLS certificate, provide the file path for the PEM-encoded certificate. When you specify a custom certificate the interactive installer also prompts you to provide a PEM private key for the custom certificate you are using. +<2> If you are running Kubernetes version 1.25 or later, set this value to `false`. +<3> For more information on using declarative configurations for authentication and authorization, see "Declarative configuration for authentication and authorization resources" in "Managing RBAC in Red{nbsp}Hat Advanced Cluster Security for Kubernetes". +<4> To use the {product-title-short} portal, you must expose Central by using a route, a load balancer or a node port. +<5> For more information on using declarative configurations for authentication and authorization, see "Declarative configuration for authentication and authorization resources" in "Managing RBAC in Red{nbsp}Hat Advanced Cluster Security for Kubernetes". ++ +[WARNING] +==== +On {ocp}, for using a hostPath volume, you must modify the SELinux policy to allow access to the directory, which the host and the container share. It is because SELinux blocks directory sharing by default. To modify the SELinux policy, run the following command: +[source,terminal] +---- +$ sudo chcon -Rt svirt_sandbox_file_t <full_volume_path> +---- + +However, Red{nbsp}Hat does not recommend modifying the SELinux policy, instead use PVC when installing on {ocp}. +==== + +On completion, the installer creates a folder named central-bundle, which contains the necessary YAML manifests and scripts to deploy Central. +In addition, it shows on-screen instructions for the scripts you need to run to deploy additional trusted certificate authorities, Central and Scanner, and the authentication instructions for logging into the {product-title-short} portal along with the autogenerated password if you did not provide one when answering the prompts. diff --git a/modules/using-wildcard-routes.adoc b/modules/using-wildcard-routes.adoc deleted file mode 100644 index c122cb465d2d..000000000000 --- a/modules/using-wildcard-routes.adoc +++ /dev/null @@ -1,288 +0,0 @@ -// Module included in the following assemblies: -// -// * networking/configuring-ingress-controller - -[id="using-wildcard-routes_{context}"] -= Using wildcard routes - -The HAProxy Ingress Controller has support for wildcard routes. The Ingress Operator uses `wildcardPolicy` to configure the `ROUTER_ALLOW_WILDCARD_ROUTES` environment variable of the Ingress Controller. - -The default behavior of the Ingress Controller is to admit routes with a wildcard policy of `None`, which is backwards compatible with existing `IngressController` resources. - -.Procedure - -. Configure the wildcard policy. -.. Use the following command to edit the `IngressController` resource: -+ -[source,terminal] ----- -$ oc edit IngressController ----- -+ -.. Under `spec`, set the `wildcardPolicy` field to `WildcardsDisallowed` or `WildcardsAllowed`: -+ -[source,yaml] ----- -spec: - routeAdmission: - wildcardPolicy: WildcardsDisallowed # or WildcardsAllowed ----- - -//// -.Samples for using a secure wildcard edge terminated route - -This example reflects TLS termination occurring on the Ingress Controller before traffic is proxied to the destination. Traffic sent to any hosts in the subdomain -`example.test` (`*.example.test`) is proxied to the exposed service. - -The secure edge terminated route specifies the TLS certificate and key -information. The TLS certificate is served by the Ingress Controller front end for all hosts that match the subdomain (`*.example.test`). - -. Configure the wildcard policy. - -. Create a private key, certificate signing request (CSR), and certificate for the -edge secured route. -+ -The instructions on how to do this are specific to your certificate authority and provider. The following example is a simple self-signed certificate for a domain named `*.example.test`: -+ ----- -# sudo openssl genrsa -out example-test.key 2048 -# -# sudo openssl req -new -key example-test.key -out example-test.csr \ - -subj "/C=US/ST=CA/L=Mountain View/O=OS3/OU=Eng/CN=*.example.test" -# -# sudo openssl x509 -req -days 366 -in example-test.csr \ - -signkey example-test.key -out example-test.crt ----- - -. Generate a wildcard route using the certificate and key: -+ ----- -$ cat > route.yaml <<REOF -apiVersion: v1 -kind: Route -metadata: - name: my-service -spec: - host: www.example.test - wildcardPolicy: Subdomain - to: - kind: Service - name: my-service - tls: - termination: edge - key: "$(perl -pe 's/\n/\\n/' example-test.key)" - certificate: "$(perl -pe 's/\n/\\n/' example-test.cert)" -REOF -$ oc create -f route.yaml ----- -+ -Ensure your DNS entry for `*.example.test` points to your Ingress Controller instances and the route to your domain is available. -+ -This example uses `curl` with a local resolver to simulate the DNS lookup: -+ ----- -# routerip="4.1.1.1" # replace with IP address of one of your router instances. -# curl -k --resolve www.example.test:443:$routerip https://www.example.test/ -# curl -k --resolve abc.example.test:443:$routerip https://abc.example.test/ -# curl -k --resolve anyname.example.test:443:$routerip https://anyname.example.test/ ----- - -For Ingress Controllers that allow wildcard routes, configure the wildcard policy, there are some caveats to the ownership of a subdomain associated with a wildcard route. - -Prior to wildcard routes, ownership was based on the claims made for a host name with the namespace with the oldest route winning against any other claimants. -For example, route `r1` in namespace `ns1` with a claim for `one.example.test` -would win over another route `r2` in namespace `ns2` for the same host name -`one.example.test` if route `r1` was older than route `r2`. - -In addition, routes in other namespaces were allowed to claim non-overlapping -hostnames. For example, route `rone` in namespace `ns1` could claim -`www.example.test` and another route `rtwo` in namespace `d2` could claim -`c3po.example.test`. - -This is still the case if there are _no_ wildcard routes claiming that same -subdomain, such as `example.test` in the previous example. - -However, a wildcard route needs to claim all of the host names within a -subdomain, host names of the form `\*.example.test`. A wildcard route's claim -is allowed or denied based on whether or not the oldest route for that subdomain -(`example.test`) is in the same namespace as the wildcard route. The oldest -route can be either a regular route or a wildcard route. - -For example, if there is already a route `eldest` that exists in the `ns1` -namespace that claimed a host named `owner.example.test` and, if at a later -point in time, a new wildcard route `wildthing` requesting for routes in that -subdomain (`example.test`) is added, the claim by the wildcard route will only -be allowed if it is the same namespace (`ns1`) as the owning route. - -The following examples illustrate various scenarios in which claims for wildcard -routes will succeed or fail. - -In the following example, a Ingress Controller that allows wildcard routes will allow non-overlapping claims for hosts in the subdomain `example.test` as long as a -wildcard route has not claimed a subdomain. - ----- -$ oc project ns1 -$ oc expose service myservice --hostname=owner.example.test -$ oc expose service myservice --hostname=aname.example.test -$ oc expose service myservice --hostname=bname.example.test - -$ oc project ns2 -$ oc expose service anotherservice --hostname=second.example.test -$ oc expose service anotherservice --hostname=cname.example.test - -$ oc project otherns -$ oc expose service thirdservice --hostname=emmy.example.test -$ oc expose service thirdservice --hostname=webby.example.test ----- - -In the following example, a Ingress Controller that allows wildcard routes will not allow the claim for `owner.example.test` or `aname.example.test` to succeed since the owning namespace is `ns1`. - ----- -$ oc project ns1 -$ oc expose service myservice --hostname=owner.example.test -$ oc expose service myservice --hostname=aname.example.test - -$ oc project ns2 -$ oc expose service secondservice --hostname=bname.example.test -$ oc expose service secondservice --hostname=cname.example.test - -$ # Router will not allow this claim with a different path name `/p1` as -$ # namespace `ns1` has an older route claiming host `aname.example.test`. -$ oc expose service secondservice --hostname=aname.example.test --path="/p1" - -$ # Router will not allow this claim as namespace `ns1` has an older route -$ # claiming host name `owner.example.test`. -$ oc expose service secondservice --hostname=owner.example.test - -$ oc project otherns - -$ # Router will not allow this claim as namespace `ns1` has an older route -$ # claiming host name `aname.example.test`. -$ oc expose service thirdservice --hostname=aname.example.test ----- - -In the following example, a Ingress Controller that allows wildcard routes will allow the claim for `\*.example.test` to succeed since the owning namespace is `ns1` and the wildcard route belongs to that same namespace. - ----- -$ oc project ns1 -$ oc expose service myservice --hostname=owner.example.test - -$ # Reusing the route.yaml from the previous example. -$ # spec: -$ # host: www.example.test -$ # wildcardPolicy: Subdomain - -$ oc create -f route.yaml # router will allow this claim. ----- - -In the following example, a Ingress Controller that allows wildcard routes will not allow the claim for \*.example.test` to succeed since the owning namespace is `ns1` and the wildcard route belongs to another namespace `cyclone`. - ----- -$ oc project ns1 -$ oc expose service myservice --hostname=owner.example.test - -$ # Switch to a different namespace/project. -$ oc project cyclone - -$ # Reusing the route.yaml from a prior example. -$ # spec: -$ # host: www.example.test -$ # wildcardPolicy: Subdomain - -$ oc create -f route.yaml # router will deny (_NOT_ allow) this claim. ----- - -Similarly, once a namespace with a wildcard route claims a subdomain, only -routes within that namespace can claim any hosts in that same subdomain. - -In the following example, once a route in namespace `ns1` with a wildcard route -claims subdomain `example.test`, only routes in the namespace `ns1` are allowed -to claim any hosts in that same subdomain. - ----- -$ oc project ns1 -$ oc expose service myservice --hostname=owner.example.test - -$ oc project otherns - -$ # namespace `otherns` is allowed to claim for other.example.test -$ oc expose service otherservice --hostname=other.example.test - -$ oc project ns1 - -$ # Reusing the route.yaml from the previous example. -$ # spec: -$ # host: www.example.test -$ # wildcardPolicy: Subdomain - -$ oc create -f route.yaml # Router will allow this claim. - -$ # In addition, route in namespace otherns will lose its claim to host -$ # `other.example.test` due to the wildcard route claiming the subdomain. - -$ # namespace `ns1` is allowed to claim for deux.example.test -$ oc expose service mysecondservice --hostname=deux.example.test - -$ # namespace `ns1` is allowed to claim for deux.example.test with path /p1 -$ oc expose service mythirdservice --hostname=deux.example.test --path="/p1" - -$ oc project otherns - -$ # namespace `otherns` is not allowed to claim for deux.example.test -$ # with a different path '/otherpath' -$ oc expose service otherservice --hostname=deux.example.test --path="/otherpath" - -$ # namespace `otherns` is not allowed to claim for owner.example.test -$ oc expose service yetanotherservice --hostname=owner.example.test - -$ # namespace `otherns` is not allowed to claim for unclaimed.example.test -$ oc expose service yetanotherservice --hostname=unclaimed.example.test ----- - -In the following example, different scenarios are shown in which the owner routes -are deleted and ownership is passed within and across namespaces. While a route -claiming host `eldest.example.test` in the namespace `ns1` exists, wildcard -routes in that namespace can claim subdomain `example.test`. When the route for -host `eldest.example.test` is deleted, the next oldest route -`senior.example.test` would become the oldest route and would not affect any -other routes. Once the route for host `senior.example.test` is deleted, the next -oldest route `junior.example.test` becomes the oldest route and block the -wildcard route claimant. - ----- -$ oc project ns1 -$ oc expose service myservice --hostname=eldest.example.test -$ oc expose service seniorservice --hostname=senior.example.test - -$ oc project otherns - -$ # namespace `otherns` is allowed to claim for other.example.test -$ oc expose service juniorservice --hostname=junior.example.test - -$ oc project ns1 - -$ # Reusing the route.yaml from the previous example. -$ # spec: -$ # host: www.example.test -$ # wildcardPolicy: Subdomain - -$ oc create -f route.yaml # Router will allow this claim. - -$ # In addition, route in namespace otherns will lose its claim to host -$ # `junior.example.test` due to the wildcard route claiming the subdomain. - -$ # namespace `ns1` is allowed to claim for dos.example.test -$ oc expose service mysecondservice --hostname=dos.example.test - -$ # Delete route for host `eldest.example.test`, the next oldest route is -$ # the one claiming `senior.example.test`, so route claims are unaffacted. -$ oc delete route myservice - -$ # Delete route for host `senior.example.test`, the next oldest route is -$ # the one claiming `junior.example.test` in another namespace, so claims -$ # for a wildcard route would be affected. The route for the host -$ # `dos.example.test` would be unaffected as there are no other wildcard -$ # claimants blocking it. -$ oc delete route seniorservice ----- -//// diff --git a/modules/validatingwebhookconfiguration-yaml-changes.adoc b/modules/validatingwebhookconfiguration-yaml-changes.adoc new file mode 100644 index 000000000000..c15e7d143c79 --- /dev/null +++ b/modules/validatingwebhookconfiguration-yaml-changes.adoc @@ -0,0 +1,65 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc +:_mod-docs-content-type: CONCEPT +[id="validatingwebhookconfiguration-yaml-changes_{context}"] += ValidatingWebhookConfiguration YAML file changes + +With {product-title} you can enforce security policies on: + +* Object creation +* Object update +* Pod execution +* Pod port forward + +== If Central or Sensor is unavailable +The admission controller requires an initial configuration from Sensor to work. +Kubernetes or {ocp} saves this configuration, and it remains accessible even if all admission control service replicas are rescheduled onto other nodes. +If this initial configuration exists, the admission controller enforces all configured deploy-time policies. + +If Sensor or Central becomes unavailable later: + +* you will not be able to run image scans, or query information about cached image scans. +However, admission controller enforcement still functions based on the available information gathered before the timeout expires, even if the gathered information is incomplete. +* you will not be able to disable the admission controller from the {product-title-short} portal or modify enforcement for an existing policy as the changes will not get propagated to the admission control service. + +[NOTE] +==== +If you need to disable admission control enforcement, you can delete the validating webhook configuration by running the following command: + +* On {ocp}: ++ +[source,terminal] +---- +$ oc delete ValidatingWebhookConfiguration/stackrox +---- +* On Kubernetes: ++ +[source,terminal] +---- +$ kubectl delete ValidatingWebhookConfiguration/stackrox +---- +==== + +== Make the admission controller more reliable + +Red{nbsp}Hat recommends that you schedule the admission control service on the control plane and not on worker nodes. +The deployment YAML file includes a soft preference for running on the control plane, however it is not enforced. + +By default, the admission control service runs 3 replicas. +To increase reliability, you can increase the replicas by running the following command: + +[source,terminal] +---- +$ oc -n stackrox scale deploy/admission-control --replicas=<number_of_replicas> <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +== Using with the roxctl CLI + +You can use the following options when you generate a Sensor deployment YAML file: + +* `--admission-controller-listen-on-updates`: If you use this option, {product-title} generates a Sensor bundle with a `ValidatingWebhookConfiguration` pre-configured to receive update events from the Kubernetes or {ocp} API server. +* `--admission-controller-enforce-on-updates`: If you use this option, {product-title} configures Central such that the admission controller also enforces security policies object updates. + +Both these options are optional, and are `false` by default. diff --git a/modules/verify-acs-installation-kube.adoc b/modules/verify-acs-installation-kube.adoc new file mode 100644 index 000000000000..3f102d179981 --- /dev/null +++ b/modules/verify-acs-installation-kube.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * installing/verify-installation-rhacs-other.adoc +:_mod-docs-content-type: PROCEDURE +[id="verify-acs-installation_{context}"] += Verifying installation + +After you complete the installation, run a few vulnerable applications and go to the {product-title-short} portal to evaluate the results of security assessments and policy violations. + +[NOTE] +==== +The sample applications listed in the following section contain critical vulnerabilities and they are specifically designed to verify the build and deploy-time assessment features of {product-title}. +==== +To verify installation: + +. Find the address of the {product-title-short} portal based on your exposure method: +.. For a load balancer: ++ +[source,terminal] +---- +$ kubectl get service central-loadbalancer -n stackrox +---- +.. For port forward: +... Run the following command: ++ +[source,terminal] +---- +$ kubectl port-forward svc/central 18443:443 -n stackrox +---- +... Go to `\https://localhost:18443/`. +. Create a new namespace: ++ +[source,terminal] +---- +$ kubectl create namespace test +---- +. Start some applications with critical vulnerabilities: ++ +[source,terminal] +---- +$ kubectl run shell --labels=app=shellshock,team=test-team \ + --image=quay.io/stackrox-io/docs:example-vulnerables-cve-2014-6271 -n test +$ kubectl run samba --labels=app=rce \ + --image=quay.io/stackrox-io/docs:example-vulnerables-cve-2017-7494 -n test +---- + +{product-title} automatically scans these deployments for security risks and policy violations as soon as they are submitted to the cluster. Go to the {product-title-short} portal to view the violations. You can log in to the {product-title-short} portal by using the default username *admin* and the generated password. diff --git a/modules/verify-acs-installation-ocp.adoc b/modules/verify-acs-installation-ocp.adoc new file mode 100644 index 000000000000..a24a05d6a43b --- /dev/null +++ b/modules/verify-acs-installation-ocp.adoc @@ -0,0 +1,53 @@ +// Module included in the following assemblies: +// +// * installing/verify-installation-rhacs-ocp.adoc +:_mod-docs-content-type: PROCEDURE +[id="verify-acs-installation_{context}"] += Verifying installation + +After you complete the installation, run a few vulnerable applications and go to the {product-title-short} portal to evaluate the results of security assessments and policy violations. + +[NOTE] +==== +The sample applications listed in the following section contain critical vulnerabilities and they are specifically designed to verify the build and deploy-time assessment features of {product-title}. +==== +To verify installation: + +. Find the address of the {product-title-short} portal based on your exposure method: +.. For a route: ++ +[source,terminal] +---- +$ oc get route central -n stackrox +---- +.. For a load balancer: ++ +[source,terminal] +---- +$ oc get service central-loadbalancer -n stackrox +---- +.. For port forward: +... Run the following command: ++ +[source,terminal] +---- +$ oc port-forward svc/central 18443:443 -n stackrox +---- +... Go to `\https://localhost:18443/`. +. Using the {osp} CLI, create a new project: ++ +[source,terminal] +---- +$ oc new-project test +---- +. Start some applications with critical vulnerabilities: ++ +[source,terminal] +---- +$ oc run shell --labels=app=shellshock,team=test-team \ + --image=quay.io/stackrox-io/docs:example-vulnerables-cve-2014-6271 -n test +$ oc run samba --labels=app=rce \ + --image=quay.io/stackrox-io/docs:example-vulnerables-cve-2017-7494 -n test +---- + +{product-title} automatically scans these deployments for security risks and policy violations as soon as they are submitted to the cluster. Go to the {product-title-short} portal to view the violations. You can log in to the {product-title-short} portal by using the default username *admin* and the generated password. diff --git a/modules/verify-central-cluster-upgrade.adoc b/modules/verify-central-cluster-upgrade.adoc new file mode 100644 index 000000000000..dbd81006365b --- /dev/null +++ b/modules/verify-central-cluster-upgrade.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="verify-central-cluster-upgrade_{context}"] += Verifying the Central cluster upgrade + +[role="_abstract"] +After you have upgraded both Central and Scanner, verify that the Central cluster upgrade is complete. + +.Procedure + +* Check the Central logs by running the following command: ++ +[source,terminal] +---- +$ oc logs -n stackrox deploy/central -c central <1> +---- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. + +.Sample output of a successful upgrade +[source,terminal] +---- +No database restore directory found (this is not an error). +Migrator: 2023/04/19 17:58:54: starting DB compaction +Migrator: 2023/04/19 17:58:54: Free fraction of 0.0391 (40960/1048576) is < 0.7500. Will not compact +badger 2023/04/19 17:58:54 INFO: All 1 tables opened in 2ms +badger 2023/04/19 17:58:55 INFO: Replaying file id: 0 at offset: 846357 +badger 2023/04/19 17:58:55 INFO: Replay took: 50.324µs +badger 2023/04/19 17:58:55 DEBUG: Value log discard stats empty +Migrator: 2023/04/19 17:58:55: DB is up to date. Nothing to do here. +badger 2023/04/19 17:58:55 INFO: Got compaction priority: {level:0 score:1.73 dropPrefix:[]} +version: 2023/04/19 17:58:55.189866 ensure.go:49: Info: Version found in the DB was current. We’re good to go! +---- diff --git a/modules/verify-central-install-operator.adoc b/modules/verify-central-install-operator.adoc new file mode 100644 index 000000000000..29cec1c52058 --- /dev/null +++ b/modules/verify-central-install-operator.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * installing/install-ocp-operator.adoc +:_mod-docs-content-type: PROCEDURE +[id="verify-central-install-operator_{context}"] += Verifying Central installation using the Operator method + +After Central finishes installing, log in to the {product-title-short} portal to verify the successful installation of Central. + +.Procedure +. On the {ocp} web console, go to the *Operators* -> *Installed Operators* page. +. Select the {product-title} Operator from the list of installed Operators. +. Select the *Central* tab. +. From the *Centrals* list, select `stackrox-central-services` to view its details. +. To get the password for the `admin` user, you can either: +* Click the link under **Admin Password Secret Reference**. +* Use the {osp} CLI to enter the command listed under **Admin Credentials Info**: ++ +[source,terminal] +---- +$ oc -n stackrox get secret central-htpasswd -o go-template='{{index .data "password" | base64decode}}' +---- +. Find the link to the {product-title-short} portal by using the {osp} CLI command: ++ +[source,terminal] +---- +$ oc -n stackrox get route central -o jsonpath="{.status.ingress[0].host}" +---- +Alternatively, you can use the {product-title} web console to find the link to the {product-title-short} portal by performing the following commands: +.. Go to *Networking* -> *Routes*. +.. Find the *central* Route and click on the {product-title-short} portal link under the *Location* column. +. Log in to the {product-title-short} portal using the username *admin* and the password that you retrieved in a previous step. Until {product-title-short} is completely configured (for example, you have the `Central` resource and at least one `SecuredCluster` resource installed and configured), no data is available in the dashboard. The `SecuredCluster` resource can be installed and configured on the same cluster as the `Central` resource. Clusters with the `SecuredCluster` resource are similar to managed clusters in {rh-rhacm-first}. + +.Next Steps +. Optional: Configure central settings. +. Generate an init bundle or CRS containing the cluster secrets that allows communication between the `Central` and `SecuredCluster` resources. You need to download this file, use it to generate resources on the clusters you want to secure, and securely store it. +. Install secured cluster services on each cluster you want to monitor. diff --git a/modules/verify-secured-cluster-upgrade.adoc b/modules/verify-secured-cluster-upgrade.adoc new file mode 100644 index 000000000000..9bed1da917b2 --- /dev/null +++ b/modules/verify-secured-cluster-upgrade.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-44.adoc +// * cloud_service/upgrading-cloud/upgrade-cloudsvc-roxctl.adoc +:_mod-docs-content-type: PROCEDURE +[id="verify-secured-cluster-upgrade_{context}"] += Verifying secured cluster upgrade + +[role="_abstract"] +After you have upgraded secured clusters, verify that the updated pods are working. + +.Procedure + +* Check that the new pods have deployed: ++ +[source,terminal] +---- +$ oc get deploy,ds -n stackrox -o wide <1> +---- ++ +-- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +-- ++ +[source,terminal] +---- +$ oc get pod -n stackrox --watch <1> +---- ++ +-- +<1> If you use Kubernetes, enter `kubectl` instead of `oc`. +-- \ No newline at end of file diff --git a/modules/verify-upgrades.adoc b/modules/verify-upgrades.adoc new file mode 100644 index 000000000000..7922b42ebec1 --- /dev/null +++ b/modules/verify-upgrades.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * upgrade/upgrade-from-44.adoc +:_mod-docs-content-type: PROCEDURE +[id="verify-upgrades_{context}"] += Verifying upgrades + +[role="_abstract"] +The updated Sensors and Collectors continue to report the latest data from each secured cluster. + +The last time Sensor contacted Central is visible in the {product-title-short} portal. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *System Health*. +. Check to ensure that Sensor Upgrade shows clusters up to date with Central. diff --git a/modules/verifying-crio-status.adoc b/modules/verifying-crio-status.adoc deleted file mode 100644 index 5416b52c7586..000000000000 --- a/modules/verifying-crio-status.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-crio-issues.adoc - -[id="verifying-crio-status_{context}"] -= Verifying CRI-O runtime engine status - -You can verify CRI-O container runtime engine status on each cluster node. - -.Prerequisites - -* You have access to the cluster as a user with the `cluster-admin` role. -* You have installed the OpenShift CLI (`oc`). - -.Procedure - -. Review CRI-O status by querying the `crio` systemd service on a node, within a debug pod. -.. Start a debug pod for a node: -+ -[source,terminal] ----- -$ oc debug node/my-node ----- -+ -.. Set `/host` as the root directory within the debug shell. The debug pod mounts the host's root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host's executable paths: -+ -[source,terminal] ----- -# chroot /host ----- -+ -[NOTE] -==== -{product-title} {product-version} cluster nodes running {op-system-first} are immutable and rely on Operators to apply cluster changes. Accessing cluster nodes using SSH is not recommended and nodes will be tainted as _accessed_. However, if the {product-title} API is not available, or the kubelet is not properly functioning on the target node, `oc` operations will be impacted. In such situations, it is possible to access nodes using `ssh core@<node>.<cluster_name>.<base_domain>` instead. -==== -+ -.. Check whether the `crio` systemd service is active on the node: -+ -[source,terminal] ----- -# systemctl is-active crio ----- -+ -.. Output a more detailed `kubelet.service` status summary: -+ -[source,terminal] ----- -# systemctl status crio ----- diff --git a/modules/verifying-image-signatures-to-ensure-image-integrity.adoc b/modules/verifying-image-signatures-to-ensure-image-integrity.adoc new file mode 100644 index 000000000000..90403b899b7c --- /dev/null +++ b/modules/verifying-image-signatures-to-ensure-image-integrity.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * operating/verify-image-signatures.adoc + +:_mod-docs-content-type: PROCEDURE +[id="verifying-image-signatures-to-ensure-image-integrity_{context}"] += Verifying image signatures to ensure image integrity + +To verify image integrity, you must check that a trusted source signed the image. +If you have enabled transparency log validation for your signature integration, you must also confirm that the scan includes a valid transparency log bundle. + +For multi-architecture images, you must sign both the index and architecture-specific digests to avoid runtime resolution issues. + +.Prerequisites + +* You have created a signature integration. ++ +For more information about how to create a signature integration, see "Securing container Images by using signature integration". + +.Procedure + +* To scan an image signature by using the `roxctl` CLI, run the following command: ++ +[source,terminal] +---- +$ roxctl image scan \ +--image=<registry>/<repository>/<image>@<digest> \ +--force-insecure-skip-tls-verify +---- ++ +where: ++ +-- +`<registry>`:: Specifies the container image registry. For example, `quay.io`. +`<repository>`:: Specifies the repository of the container image. For example, `quay`. +`<image>`:: Specifies the name of the container image that you want to scan. For example, `busybox`. +`<digest>`:: Specifies the digest of the container image. For example, `sha256:92f3298bf80a1ba949140d77987f5de081f010337880cd771f7e7fc928f8c74d`. +-- ++ +Verify that the output includes the signature. +If transparency log validation is enabled for your signature integration, verify that the output includes the Rekor bundle with the proof of inclusion into the transparency log. ++ +If certificate verification is enabled for your signature integration, verify that the output includes the certificate verification data. \ No newline at end of file diff --git a/modules/verifying-serverless-app-deployment.adoc b/modules/verifying-serverless-app-deployment.adoc deleted file mode 100644 index e93550dba537..000000000000 --- a/modules/verifying-serverless-app-deployment.adoc +++ /dev/null @@ -1,78 +0,0 @@ -// Module included in the following assemblies: -// -// * serverless/serving-creating-managing-apps.adoc - -[id="verifying-serverless-app-deployment_{context}"] -= Verifying your serverless application deployment - -To verify that your serverless application has been deployed successfully, you must get the application URL created by Knative, and then send a request to that URL and observe the output. - -[NOTE] -==== -{ServerlessProductName} supports the use of both HTTP and HTTPS URLs, however the output from `oc get ksvc` will always print URLs using the `http://` format. -==== - -.Procedure - -. Find the application URL: -+ -[source,terminal] ----- -$ oc get ksvc <service_name> ----- -+ -.Example output -[source,terminal] ----- -NAME URL LATESTCREATED LATESTREADY READY REASON -event-delivery http://event-delivery-default.example.com event-delivery-4wsd2 event-delivery-4wsd2 True ----- -. Make a request to your cluster and observe the output. -+ -.Example HTTP request -[source,terminal] ----- -$ curl http://event-delivery-default.example.com ----- -+ -.Example HTTPS request -[source,terminal] ----- -$ curl https://event-delivery-default.example.com ----- -+ -.Example output -[source,terminal] ----- -Hello Serverless! ----- -. Optional. If you receive an error relating to a self-signed certificate in the certificate chain, you can add the `--insecure` flag to the curl command to ignore the error: -+ -[source,terminal] ----- -$ curl https://event-delivery-default.example.com --insecure ----- -+ -.Example output -[source,terminal] ----- -Hello Serverless! ----- -+ -[IMPORTANT] -==== -Self-signed certificates must not be used in a production deployment. This method is only for testing purposes. -==== -. Optional. If your {product-title} cluster is configured with a certificate that is signed by a certificate authority (CA) but not yet globally configured for your system, you can specify this with the `curl` command. -The path to the certificate can be passed to the curl command by using the `--cacert` flag: -+ -[source,terminal] ----- -$ curl https://event-delivery-default.example.com --cacert <file> ----- -+ -.Example output -[source,terminal] ----- -Hello Serverless! ----- diff --git a/modules/verifying-the-status-of-automatic-certificate-renewal.adoc b/modules/verifying-the-status-of-automatic-certificate-renewal.adoc new file mode 100644 index 000000000000..d5af4c667da5 --- /dev/null +++ b/modules/verifying-the-status-of-automatic-certificate-renewal.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * configuration/reissue-internal-certificates.adoc + +:_mod-docs-content-type: PROCEDURE +[id="verifying-the-status-of-automatic-certificate-renewal_{context}"] += Verifying the status of automatic certificate renewal + +By viewing the *Clusters* page, you can verify that the automatic certificate renewal is active. + +.Procedure + +. In the {product-title-short} portal, click *Platform Configuration* -> *Clusters*. +. Verify that *Auto-refresh enabled* appears in the *Credential Expiration* column. + +[IMPORTANT] +==== +If a secured cluster displays a warning about soon-to-expire credentials even though auto-refresh is enabled, you must manually restart the pods of the affected cluster to apply the latest certificates and prevent downtime. + +For more information, see "Applying the latest internal certificates". +==== diff --git a/modules/view-alerts-in-sumo-logic.adoc b/modules/view-alerts-in-sumo-logic.adoc new file mode 100644 index 000000000000..d242c5625a0f --- /dev/null +++ b/modules/view-alerts-in-sumo-logic.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * integration/integrate-with-sumologic.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-alerts-in-sumo-logic_{context}"] += Viewing alerts in Sumo Logic + +You can view alerts from {product-title} in Sumo Logic. + +. Log in to your Sumo Logic Home page and click *Log Search*. +. In the search box, enter `_sourceCategory=rhacs`. +Make sure to use the same *Source Category* name that you entered while configuring Sumo Logic. +. Select the time and then click *Start*. diff --git a/modules/view-deployment-info.adoc b/modules/view-deployment-info.adoc new file mode 100644 index 000000000000..7193dcfe1d1d --- /dev/null +++ b/modules/view-deployment-info.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-deployment-info_{context}"] += Viewing deployment information + +[role="_abstract"] +The network graph provides a visual map of deployments, namespaces, and connections that {product-title-short} has discovered. By clicking on a deployment in the graph, you can view information about the deployment, including the following details: + +- Network security, such as the number of flows, existing or missing network policy rules, and listening ports +- Labels and annotations +- Port configurations +- Container information +- Anomalous and baseline flows for ingress and egress connections, including protocols and port numbers +- Network policies + +.Procedure +To view details for deployments in a namespace: + +. In the {product-title-short} portal, go to *Network Graph* and select your cluster from the drop-down list. +. Click the *Namespaces* list and use the search field to locate a namespace, or select individual namespaces. +. Click the *Deployments* list and use the search field to locate a deployment, or select individual deployments to display in the network graph. +. In the network graph, click on a deployment to view the information panel. +. Click the *Details*, *Flows*, *Baseline*, or *Network policies* tab to view the corresponding information. + diff --git a/modules/view-details-only-for-fixable-cves.adoc b/modules/view-details-only-for-fixable-cves.adoc new file mode 100644 index 000000000000..09f58590c48d --- /dev/null +++ b/modules/view-details-only-for-fixable-cves.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="view-details-only-for-fixable-cves_{context}"] += Viewing details only for fixable CVEs by using the dashboard + +[role="_abstract"] +Use the *Vulnerability Management* view to filter and show only the fixable CVEs. + +.Procedure + +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Dashboard*. +. From the *Vulnerability Management* view header, under *Filter CVEs*, click *Fixable*. \ No newline at end of file diff --git a/modules/view-dockerfile-for-image.adoc b/modules/view-dockerfile-for-image.adoc new file mode 100644 index 000000000000..5f9fa3ffa7c4 --- /dev/null +++ b/modules/view-dockerfile-for-image.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-dockerfile-for-image_{context}"] += Viewing the Dockerfile for an image by using the dashboard + +Use the *Vulnerability Management* view to find the root cause of vulnerabilities in an image. +You can view the Dockerfile and find exactly which command in the Dockerfile introduced the vulnerabilities and all components that are associated with that single command. + +The Dockerfile section shows information about: + +* All the layers in the Dockerfile +* The instructions and their value for each layer +* The components included in each layer +* The number of CVEs in components for each layer + +When there are components introduced by a specific layer, you can select the expand icon to see a summary of its components. +If there are any CVEs in those components, you can select the expand icon for an individual component to get more details about the CVEs affecting that component. + +.Procedure + +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Dashboard*. +. Select an image from either the *Top Riskiest Images* widget or click the *Images* button at the top of the dashboard and select an image. +. In the *Image* details view, next to *Dockerfile*, select the expand icon to see a summary of instructions, values, creation date, and components. +. Select the expand icon for an individual component to view more information. \ No newline at end of file diff --git a/modules/view-kubernetes-secrets.adoc b/modules/view-kubernetes-secrets.adoc new file mode 100644 index 000000000000..ab588a63e169 --- /dev/null +++ b/modules/view-kubernetes-secrets.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/review-cluster-configuration.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-kubernetes-secrets_{context}"] += Viewing Kubernetes secrets + +[role="_abstract"] +View Kubernetes secrets in use in your environment and identify deployments using those secrets. + +.Procedure +. In the {product-title-short} portal, go to *Configuration Management*. +. On the *Secrets Most Used Across Deployments* widget, select *View All*. +The *Secrets* view displays a list of Kubernetes secrets. +. Select a row to view more details. + +Use the available information to identify if the secrets are in use in deployments where they are not needed. diff --git a/modules/view-most-common-vulnerabilities.adoc b/modules/view-most-common-vulnerabilities.adoc new file mode 100644 index 000000000000..e8ec0b529e8f --- /dev/null +++ b/modules/view-most-common-vulnerabilities.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="view-most-common-vulnerabilities_{context}"] += Viewing the most common vulnerabilities by using the dashboard + +The *Most Common Vulnerabilities* widget on the *Vulnerability Management* -> *Dashboard* view shows a list of vulnerabilities that affect the largest number of deployments and images arranged by their CVSS score. + +* When you hover over a CVE in the list, you see an overview of the CVE which includes, scan time, CVSS score, description, impact, and whether it is scored by using CVSS v2 or v3. +* When you select a CVE, the *CVE* details view opens for the selected CVE. +The *CVE* details view shows in-depth details of the CVE and the components, images, and deployments and deployments in which it appears. +* Select *View All* on the *Most Common Vulnerabilities* widget header to view a list of all the CVEs in your infrastructure. +You can also filter the list of CVEs. +//TODO: Add link to local page filtering +To export the CVEs as a CSV file, select *Export* -> *Download CVES as CSV*. diff --git a/modules/view-network-baselines-ng20.adoc b/modules/view-network-baselines-ng20.adoc new file mode 100644 index 000000000000..a92d40d1259a --- /dev/null +++ b/modules/view-network-baselines-ng20.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-network-baselines-ng20_{context}"] += Viewing network baselines from the network graph + +You can view network baselines from the network graph view. + +.Procedure +. Click the *Namespaces* list and use the search field to locate a namespace, or select individual namespaces. +. Click the *Deployments* list and use the search field to locate a deployment, or select individual deployments to display in the network graph. +. In the network graph, click on a deployment to view the information panel. +. Select the *Baseline* tab. Use the *filter by entity name* field to further restrict the flows that are displayed. +. Optional: You can mark baseline flows as anomalous by performing one of the following actions: +* Select an individual entity. Click the overflow menu, {kebab}, and then select *Mark as anomalous*. +* Select multiple entities, and then click *Bulk actions* and select *Mark as anomalous*. +. Optional: Check the box to exclude ports and protocols. +. Optional: To save the baseline as a network policy YAML file, click *Download baseline as network policy*. diff --git a/modules/view-network-policies-ng20.adoc b/modules/view-network-policies-ng20.adoc new file mode 100644 index 000000000000..5c71ac2a9127 --- /dev/null +++ b/modules/view-network-policies-ng20.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-network-policies.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-network-policies-ng20_{context}"] += Viewing network policies in the network graph + +[role="_abstract"] +Network policies specify how groups of pods are allowed to communicate with each other and with other network endpoints. +Kubernetes `NetworkPolicy` resources use labels to select pods and define rules that specify what traffic is allowed to or from the selected pods. +{product-title-short} discovers and displays network policy information for all your Kubernetes clusters, namespaces, deployments, and pods, in the network graph. + +.Procedure +. In the {product-title-short} portal, go to *Network Graph* and select your cluster from the drop-down list. +. Click the *Namespaces* list and select individual namespaces, or use the search field to locate a namespace. +. Click the *Deployments* list and select individual deployments, or use the search field to locate a deployment. +. In the network graph, click on a deployment to view the information panel. +. In the *Details* tab, in the *Network security* section, you can view summary messages about network policy rules that give the following information: +* If policies exist in the network that regulate ingress or egress traffic +* If your network is missing policies and is therefore allowing all ingress or egress traffic +. To view the YAML file for the network policies, you can click on the policy rule, or click the *Network policies* tab. + diff --git a/modules/view-nonactive-clusters.adoc b/modules/view-nonactive-clusters.adoc new file mode 100644 index 000000000000..2788c778bd22 --- /dev/null +++ b/modules/view-nonactive-clusters.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * configuration/cluster-decommissioning.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-nonactive-clusters_{context}"] += Viewing nonactive clusters + +[role="_abstract"] +Nonactive clusters are clusters that were installed and performed a handshake with Central at least once but have been unreachable by Sensor for a specified period of time. Use this procedure to view a list of these clusters. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *System Configuration*. +. In the *Cluster deletion* section, click *Clusters which have Sensor Status: Unhealthy* to go to the *Clusters* list page. This page is filtered to show nonactive clusters that are subject to removal from {product-title-short} and a timeframe for the removal. ++ +[NOTE] +==== +If this feature is enabled after a cluster is considered nonactive, the counting of days towards removal starts from the time the cluster became nonactive, not from the time that the feature was enabled. If there are any nonactive clusters that you do not want removed, you can configure a label as described in the "Configuring cluster decommissioning" section. Clusters with those labels are ignored when the system removes nonactive clusters. +==== + diff --git a/modules/view-process-baselines.adoc b/modules/view-process-baselines.adoc new file mode 100644 index 000000000000..1fb7e57acd19 --- /dev/null +++ b/modules/view-process-baselines.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/evaluate-security-risks.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-process-baselines_{context}"] += Viewing the process baselines + +You can view process baselines from the *Risk* view. + +.Procedure +. In the {product-title-short} portal, select *Risk* from the navigation menu. +. Select a deployment from the list of deployments in the default *Risk* view. +Deployment details open in a panel on the right. +. In the *Deployment* details panel, select the *Process Discovery* tab. +. The process baselines are visible under the *Spec Container Baselines* section. diff --git a/modules/view-recently-detected-vulnerabilities.adoc b/modules/view-recently-detected-vulnerabilities.adoc new file mode 100644 index 000000000000..eb1f5e2d7f84 --- /dev/null +++ b/modules/view-recently-detected-vulnerabilities.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: CONCEPT +[id="view-recently-detected-vulnerabilities_{context}"] += Viewing recently detected vulnerabilities by using the dashboard + +The *Recently Detected Vulnerabilities* widget on the *Vulnerability Management* -> *Dashboard* view shows a list of recently discovered vulnerabilities in your scanned images, based on the scan time and CVSS score. +It also includes information about the number of images affected by the CVE and its impact (percentage) on your environment. + +* When you hover over a CVE in the list, you see an overview of the CVE, which includes scan time, CVSS score, description, impact, and whether it's scored by using CVSS v2 or v3. +* When you select a CVE, the *CVE* details view opens for the selected CVE. +The *CVE* details view shows in-depth details of the CVE and the components, images, and deployments and deployments in which it appears. +* Select *View All* on the *Recently Detected Vulnerabilities* widget header to view a list of all the CVEs in your infrastructure. +You can also filter the list of CVEs. +//TODO: Add link to local page filtering diff --git a/modules/view-system-access-scopes.adoc b/modules/view-system-access-scopes.adoc new file mode 100644 index 000000000000..9b04db867ea8 --- /dev/null +++ b/modules/view-system-access-scopes.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-system-access-scopes_{context}"] += Viewing the details for a system access scope + +You can view the Kubernetes and {ocp} resources that are allowed and not allowed for an access scope in the {product-title-short} portal. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Select *Access scopes*. +. Click on one of the access scopes to view its details. The details page shows a list of clusters and namespaces, and which ones are allowed for the selected access scope. + +[NOTE] +==== +You cannot modify allowed resources for a system access scope. +==== diff --git a/modules/view-system-permission-set.adoc b/modules/view-system-permission-set.adoc new file mode 100644 index 000000000000..131149579f51 --- /dev/null +++ b/modules/view-system-permission-set.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-system-permission-set_{context}"] += Viewing the permissions for a system permission set + +You can view the permissions for a system permission set in the {product-title-short} portal. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Select *Permission sets*. +. Click on one of the permission sets to view its details. The details page shows a list of resources and their permissions for the selected permission set. + +[NOTE] +==== +You cannot modify permissions for a system permission set. +==== diff --git a/modules/view-system-roles-permission-scope.adoc b/modules/view-system-roles-permission-scope.adoc new file mode 100644 index 000000000000..cac128a1368d --- /dev/null +++ b/modules/view-system-roles-permission-scope.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-system-roles-permission-scope_{context}"] += Viewing the permission set and access scope for a system role + +You can view the permission set and access scope for the default system roles. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Select *Roles*. +. Click on one of the roles to view its details. The details page shows the permission set and access scope for the slected role. + +[NOTE] +==== +You cannot modify permission set and access scope for the default system roles. +==== diff --git a/modules/view-system-roles.adoc b/modules/view-system-roles.adoc new file mode 100644 index 000000000000..9f7e9a537264 --- /dev/null +++ b/modules/view-system-roles.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * operating/manage-role-based-access-control.adoc +:_mod-docs-content-type: PROCEDURE +[id="view-system-roles_{context}"] += Viewing system roles permissions + +You can view the permissions for the default system roles. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Access control*. +. Click on the *Roles and Permissions* tab. +. Click on one of the roles to view its associated permissions for each resource. + +[NOTE] +==== +You cannot modify `read` and `write` permissions for the default system roles. +==== diff --git a/modules/viewing-a-project-using-the-CLI.adoc b/modules/viewing-a-project-using-the-CLI.adoc deleted file mode 100644 index 72e66f1f1fa2..000000000000 --- a/modules/viewing-a-project-using-the-CLI.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="viewing-a-project-using-the-CLI_{context}"] -= Viewing a project using the CLI - -When viewing projects, you are restricted to seeing only the projects you have -access to view based on the authorization policy. - -.Procedure - -. To view a list of projects, run: -+ -[source,terminal] ----- -$ oc get projects ----- - -. You can change from the current project to a different project for CLI -operations. The specified project is then used in all subsequent operations that -manipulate project-scoped content: -+ -[source,terminal] ----- -$ oc project <project_name> ----- diff --git a/modules/viewing-a-project-using-the-web-console.adoc b/modules/viewing-a-project-using-the-web-console.adoc deleted file mode 100644 index 2860caef3034..000000000000 --- a/modules/viewing-a-project-using-the-web-console.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// applications/projects/working-with-projects.adoc - -[id="viewing-a-project-using-the-web-console_{context}"] -= Viewing a project using the web console - -.Procedure - -. Navigate to *Home* -> *Projects*. - -. Select a project to view. -+ -On this page, click the *Workloads* button to see workloads in the project. diff --git a/modules/viewing-current-log-level.adoc b/modules/viewing-current-log-level.adoc new file mode 100644 index 000000000000..4b21410a3e4b --- /dev/null +++ b/modules/viewing-current-log-level.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * cli/debugging-issues.adoc +:_mod-docs-content-type: PROCEDURE +[id="viewing-the-current-log-level_{context}"] += Viewing the current log level + +You can change the log level to see more or less information in Central logs. + +.Procedure + +* Run the following command to view the current log level: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl central debug log +---- \ No newline at end of file diff --git a/modules/viewing-default-security-policies.adoc b/modules/viewing-default-security-policies.adoc new file mode 100644 index 000000000000..4e791602ff46 --- /dev/null +++ b/modules/viewing-default-security-policies.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/about-security-policies.adoc + +:_mod-docs-content-type: CONCEPT +[id="viewing-default-security-policies_{context}"] += Viewing default security policies + +[role="_abstract"] +{product-title} You can use the {product-title-short} portal to view default policies, clone them, and edit the cloned default policies. Default policies are not supported with the policies as code feature. + +.Procedure + +* In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. Default policies are indicated by the *System* label in the *Origin* column. ++ +[NOTE] +==== +You cannot delete default policies or edit policy criteria for default policies. +==== diff --git a/modules/viewing-node-cves.adoc b/modules/viewing-node-cves.adoc new file mode 100644 index 000000000000..bf8bf6cfc500 --- /dev/null +++ b/modules/viewing-node-cves.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-node-cves_{context}"] += Viewing vulnerabilities in nodes + +You can identify vulnerabilities in your nodes by using {product-title-short}. The vulnerabilities that are identified include the following: + +* Vulnerabilities in core Kubernetes components +* Vulnerabilities in container runtimes such as Docker, CRI-O, runC, and containerd + +For more information about operating systems that {product-title-short} can scan, see "Supported operating systems". + +{product-title-short} currently supports scanning nodes with the StackRox scanner and Scanner V4. Depending on which scanner is configured, different results might appear in the list of vulnerabilities. For more information, see "Understanding differences in scanning results between the StackRox Scanner and Scanner V4". + +.Procedure + +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Results*. +. Select the *Nodes* tab. +. Optional: The page defaults to a list of observed CVEs. Click *Show snoozed CVEs* to view them. +. Optional: To filter CVEs according to entity, select the appropriate filters and attributes. To add more filtering criteria, follow these steps: +.. Select the entity or attribute from the list. +.. Depending on your choices, enter the appropriate information such as text, or select a date or object. +.. Click the right arrow icon. +.. Optional: Select additional entities and attributes, and then click the right arrow icon to add them. +The filter entities and attributes are listed in the following table. ++ +.Filter options +[cols="2",options="header"] +|=== +|Entity|Attributes + +|Node +a| +* *Name*: The name of the node. +* *Operating system*: The operating system of the node, for example, {op-system-base-full}. +* *Label*: The label of the node. +* *Annotation*: The annotation for the node. +* *Scan time*: The scan date of the node. +|CVE +a| +* *Name*: The name of the CVE. +* *Discovered time*: The date when {product-title-short} discovered the CVE. +* *CVSS*: The severity level for the CVE. ++ +The following values are associated with the severity level for the CVE: ++ +** *is greater than* +** *is greater than or equal to* +** *is equal to* +** *is less than or equal to* +** *is less than* +|Node Component +a| +* *Name*: The name of the component. +* *Version*: The version of the component, for example, `4.15.0-2024`. You can use this to search for a specific version of a component, for example, in conjunction with a component name. +|Cluster +a| +* *ID*: The alphanumeric ID for the cluster. This is an internal identifier that {product-title-short} assigns for tracking purposes. +* *Name*: The name of the cluster. +* *Label*: The label for the cluster. +* *Type*: The type of cluster, for example, OCP. +* *Platform type*: The type of platform, for example, OpenShift 4 cluster. +|=== +. Optional: To refine the list of results, do any of the following tasks: +* Click *CVE severity*, and then select one or more levels. +* Click *CVE status*, and then select *Fixable* or *Not fixable*. +. To view the data, click one of the following tabs: +* *<number> CVEs*: Displays a list of all the CVEs affecting all of your nodes. +* *<number> Nodes*: Displays a list of nodes that contain CVEs. +. To view the details of the node and information about the CVEs according to the CVSS score and fixable CVEs for that node, click a node name in the list of nodes. \ No newline at end of file diff --git a/modules/viewing-resource-logs-cli-console.adoc b/modules/viewing-resource-logs-cli-console.adoc deleted file mode 100644 index 3c876dfeffc1..000000000000 --- a/modules/viewing-resource-logs-cli-console.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// * logging/viewing-resource-logs.adoc -// * nodes/pods/nodes-pods-viewing.adoc - -[id="viewing-resource-logs-cli-console_{context}"] -= Viewing resource logs - -You can view the log for various resources in the OpenShift CLI (oc) and web console. Logs read from the tail, or end, of the log. - -.Prerequisites - -* Access to the OpenShift CLI (oc). - -.Procedure (UI) - -. In the {product-title} console, navigate to *Workloads* -> *Pods* or navigate to the pod through the resource you want to investigate. -+ -[NOTE] -==== -Some resources, such as builds, do not have pods to query directly. In such instances, you can locate the *Logs* link on the *Details* page for the resource. -==== - -. Select a project from the drop-down menu. - -. Click the name of the pod you want to investigate. - -. Click *Logs*. - -.Procedure (CLI) - -** View the log for a specific pod: -+ -[source,terminal] ----- -$ oc logs -f <pod_name> -c <container_name> ----- -+ --- -where: - -`-f`:: Optional: Specifies that the output follows what is being written into the logs. -`<pod_name>`:: Specifies the name of the pod. -`<container_name>`:: Optional: Specifies the name of a container. When a pod has more than one container, you must specify the container name. --- -+ -For example: -+ -[source,terminal] ----- -$ oc logs ruby-58cd97df55-mww7r ----- -+ -[source,terminal] ----- -$ oc logs -f ruby-57f7f4855b-znl92 -c ruby ----- -+ -The contents of log files are printed out. - -** View the log for a specific resource: -+ -[source,terminal] ----- -$ oc logs <object_type>/<resource_name> <1> ----- -<1> Specifies the resource type and name. -+ -For example: -+ -[source,terminal] ----- -$ oc logs deployment/ruby ----- -+ -The contents of log files are printed out. - diff --git a/modules/viewing-security-information-in-red-hat-developer-hub.adoc b/modules/viewing-security-information-in-red-hat-developer-hub.adoc new file mode 100644 index 000000000000..13c73849b2ba --- /dev/null +++ b/modules/viewing-security-information-in-red-hat-developer-hub.adoc @@ -0,0 +1,104 @@ +// Module included in the following assemblies: +// +// * configuration/configuring-and-integrating-the-rhacs-plugin-with-red-hat-developer-hub.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-security-information-in-red-hat-developer-hub_{context}"] += Viewing security information in Red Hat Developer Hub + +By configuring and integrating the {rh-rhacs-first} plugin with {rh-rhdh-first}, you can access vulnerability data, assess risks, and take proactive security actions without leaving the {rh-rhdh} environment. + +Review the upstream plugin progress and details by visiting link:https://github.com/backstage/community-plugins[Community plugins for Backstage]. + +.Prerequisites + +* You have enabled the {product-title-short} plugin installation in {rh-rhdh}. ++ +For more information, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{rhdh-latest-version}/html/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about#con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[Installing dynamic plugins using the Helm chart] ({rh-rhdh} documentation). + +.Procedure + +. In the `app-config.yaml` file, add the `proxy` and `acs` stanzas by using the following content: ++ +[source,yaml] +---- +# ... +proxy: + endpoints: + /acs: + target: ${ACS_API_URL} + headers: + authorization: Bearer ${ACS_API_KEY} +acs: + acsUrl: ${ACS_API_URL} +# ... +---- + +. To enable the {product-title-short} plugin, perform the following steps: +.. Navigate to the dynamic plugins configuration file in your {rh-rhdh} setup. +.. To include the {product-title-short} plugin, add the following content to the configuration file, for example: ++ +[source,yaml,subs="attributes+"] +---- +# ... +- package: "oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-acs:pr_986__{plugin-acs-latest-version}!backstage-community-plugin-acs" + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + backstage-community.plugin-acs: + entityTabs: + - path: /acs + title: Security + mountPoint: entity.page.acs + mountPoints: + - mountPoint: entity.page.acs/cards + importName: EntityACSContent + config: + layout: + gridColumnEnd: + lg: span 12 + md: span 12 + xs: span 12 +# ... +---- + +. To add annotations for entities in the {rh-rhdh} catalog, perform the following steps: ++ +[NOTE] +==== +To display the vulnerability data, each component entity in the {rh-rhdh} catalog must reference the {product-title-short} deployments. + +The following values are associated with the entities in the {rh-rhdh} catalog: + +** `API` +** `Component` +** `Domain` +** `Group` +** `Location` +** `Resource` +** `System` +** `Template` +** `User` +==== +.. Navigate to the entity configuration file for your service in your {rh-rhdh} setup. +.. Add the following annotation to the configuration file, for example: ++ +[source,yaml] +---- +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: test-service + annotations: + acs/deployment-name: test-deployment-1,test-deployment-2,test-deployment-3 +# ... +---- + +.Verification + +. In the {rh-rhdh} portal, click *Catalog*. +. Click an entity and verify that the *{product-title-short}* tab appears. +. To view the violations and vulnerability data, click the *{product-title-short}* tab. + +After you configure and integrate the {product-title-short} plugin with {rh-rhdh}, you need to rebuild the Open Container Initiative (OCI) artifact. See "Rebuilding the OCI artifact" for instructions. \ No newline at end of file diff --git a/modules/viewing-snoozed-cves.adoc b/modules/viewing-snoozed-cves.adoc new file mode 100644 index 000000000000..2d33bb859305 --- /dev/null +++ b/modules/viewing-snoozed-cves.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc +:_mod-docs-content-type: PROCEDURE +[id="viewing-snoozed-cves_{context}"] += Viewing snoozed CVEs + +[role="_abstract"] +You can view a list of platform and node CVEs that have been snoozed. + +[NOTE] +==== +The ability to snooze a CVE is not enabled by default in the web portal or in the API. To enable the ability to snooze CVEs, set the runtime environment variable `ROX_VULN_MGMT_LEGACY_SNOOZE` to `true`. +==== + +.Procedure + +. In the {product-title-short} portal, do any of the following tasks: +* To view the list of platform CVEs, click *Vulnerability Management* -> *Platform CVEs*. +* To view the list of node CVEs, click *Vulnerability Management* -> *Node CVEs*. +. Click *Show snoozed CVEs* to view the list. + diff --git a/modules/viewing-the-compliance-standards-across-your-environment.adoc b/modules/viewing-the-compliance-standards-across-your-environment.adoc new file mode 100644 index 000000000000..920dd9d19cfc --- /dev/null +++ b/modules/viewing-the-compliance-standards-across-your-environment.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-the-compliance-standards-across-your-environment_{context}"] += Viewing the compliance standards across your environment + +The compliance dashboard gives you an overview of the compliance standards in all clusters, namespaces, and nodes in your environment, including charts and options to investigate potential compliance issues. + +You can view the compliance scan results for an individual cluster, namespace, or node. You can also generate reports on the compliance status of your containerized environment. + +.Procedure + +* In the {product-title-short} portal, click *Compliance -> Dashboard.* ++ +[NOTE] +==== +When you open the compliance dashboard for the first time, you see the dashboard is empty. Perform a compliance scan to fill the dashboard with data. +==== \ No newline at end of file diff --git a/modules/viewing-the-compliance-status-for-a-specific-control.adoc b/modules/viewing-the-compliance-status-for-a-specific-control.adoc new file mode 100644 index 000000000000..c439170419cc --- /dev/null +++ b/modules/viewing-the-compliance-status-for-a-specific-control.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-the-compliance-status-for-a-specific-control_{context}"] += Viewing the compliance status for a specific control + +By viewing the compliance status for a specific control, you can ensure that your environment meets detailed compliance requirements. + +You can view the compliance status for a specific control for a selected standard. + +.Procedure + +. In the {product-title-short} portal, click *Compliance -> Dashboard*. +. Look for the *Passing standards by cluster* widget. +. Click a standard to view information about all the controls associated with that standard. +. In the *Controls* table, click a control. A side panel opens, which is located on the right side. +. In the side panel, click the name of the control to view its details. \ No newline at end of file diff --git a/modules/viewing-the-compliance-status-for-a-specific-standard.adoc b/modules/viewing-the-compliance-status-for-a-specific-standard.adoc new file mode 100644 index 000000000000..aadd94d7bf40 --- /dev/null +++ b/modules/viewing-the-compliance-status-for-a-specific-standard.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-the-compliance-status-for-a-specific-standard_{context}"] += Viewing the compliance status for a specific standard + +By viewing the compliance status for a specific standard, you can ensure that your environment adheres to industry and regulatory compliance requirements. + +{rh-rhacs-first} supports NIST, PCI DSS, NIST, HIPAA, and CIS for Kubernetes compliance standards. You can view all the compliance controls for a single compliance standard. + +.Procedure + +. In the {product-title-short} portal, click *Compliance -> Dashboard*. +. Look for the *Passing standards across clusters* widget. +. Click a standard to view information about all the controls associated with that standard. \ No newline at end of file diff --git a/modules/viewing-the-compliance-status-for-clusters.adoc b/modules/viewing-the-compliance-status-for-clusters.adoc new file mode 100644 index 000000000000..348a9909db8f --- /dev/null +++ b/modules/viewing-the-compliance-status-for-clusters.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-the-compliance-status-for-clusters_{context}"] += Viewing the compliance status for clusters + +By viewing the compliance status for clusters, you can monitor and ensure that your clusters adhere to the required compliance standards. + +You can view the compliance status for all clusters or an individual cluster in the compliance dashboard. + +.Procedure + +* To view the compliance status for all clusters in your environment: + +** In the {product-title-short} portal, click *Compliance -> Dashboard* -> *clusters* tab. + +* To view the compliance status for a specific cluster in your environment, perform the following steps: + +** In the {product-title-short} portal, click *Compliance -> Dashboard*. +** Look for the *Passing standards by cluster* widget. +** In this widget, click a cluster name to view its compliance status. \ No newline at end of file diff --git a/modules/viewing-the-compliance-status-for-namespaces.adoc b/modules/viewing-the-compliance-status-for-namespaces.adoc new file mode 100644 index 000000000000..a520a73c35bb --- /dev/null +++ b/modules/viewing-the-compliance-status-for-namespaces.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * operating/manage-compliance/monitoring-workload-and-cluster-compliance.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-the-compliance-status-for-namespaces_{context}"] += Viewing the compliance status for namespaces + +By viewing the compliance status for namespaces, you can monitor and ensure that each namespace adheres to the required compliance standards. + +You can view the compliance status for all namespaces or a single namespace in the compliance dashboard. + +.Procedure + +* To view the compliance status for all namespaces in your environment: +** In the {product-title-short} portal, click *Compliance -> Dashboard -> namespaces* tab. + +* To view the compliance status for a specific namespace in your environment, perform the following steps: +** In the {product-title-short} portal, click *Compliance -> Dashboard -> namespaces* tab. +** In the *Namespaces* table, click a namespace. A side panel opens, which is located on the right side. +** In the side panel, click the name of the namespace to view its compliance status. \ No newline at end of file diff --git a/modules/viewing-the-log-analytics-to-detect-threats.adoc b/modules/viewing-the-log-analytics-to-detect-threats.adoc new file mode 100644 index 000000000000..b173e6ebe2b7 --- /dev/null +++ b/modules/viewing-the-log-analytics-to-detect-threats.adoc @@ -0,0 +1,82 @@ +// Module included in the following assemblies: +// +// * integration/integrating-with-microsoft-sentinel-notifier.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-the-log-analytics-to-detect-threats_{context}"] += Viewing the log analytics to detect threats + +By creating a Microsoft Sentinel integration, you can view the log analytics to detect threats. + +.Prerequisites + +* You have created a data collection rule and a log analytics workspace on Microsoft Azure. +* You have configured a service principal with a client secret, client certificate, or managed identity. The service principal or managed identity requires the `Monitoring Metrics Publisher` over a scope that includes all Sentinel resources. +* You have created a log analytics schema by using the `TimeGenerated` and `msg` fields in JSON format. ++ +[IMPORTANT] +==== +You need to create separate log analytics tables for audit logs and alerts, and both data sources use the same schema. +==== + +** To create a schema, upload the following content to Microsoft Sentinel: ++ +.Example JSON +[source,json] +---- +{ + "TimeGenerated": "2024-09-03T10:56:58.5010069Z", # <1> + "msg": { # <2> + "id": "1abe30d1-fa3a-xxxx-xxxx-781f0a12228a", # <3> + "policy" : {} + } +} +---- ++ +-- +<1> The timestamp for the alert. +<2> Contains the message details. +<3> The payload of the message, either alert or audit log. +-- + +.Procedure + +. In the {product-title-short} portal, click *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section, and then click *Microsoft Sentinel*. +. To create a new integration, click *New integration*. +. In the *Create integration* page, provide the following information: +** *Integration name*: Specify a name for the integration. +** *Log ingestion endpoint*: Enter the data collection endpoint. You can find the endpoint in the Microsoft Azure portal. ++ +For more information, see link:https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/data-collection-rule-overview[Data collection rules (DCRs) in Azure Monitor] (Microsoft Azure documentation). +** *Directory tenant ID*: Enter your unique tenant ID within the Microsoft Azure cloud infrastructure. You can find the tenant ID in the Microsoft Azure portal. ++ +For more information, see link:https://learn.microsoft.com/en-us/azure/active-directory-b2c/tenant-management-read-tenant-name[Find tenant name and tenant ID in Azure Active Directory B2C] (Microsoft Azure documentation). +** *Application client ID*: Enter the client ID which uniquely identifies the specific application registered within your AAD that needs access to resources. You can find the client ID in the Microsoft Entra portal for the service principal you have created. ++ +For more information, see link:https://learn.microsoft.com/en-us/security/zero-trust/develop/app-registration[Register applications] (Microsoft Azure documentation). +** Choose the appropriate authentication method: +*** If you want to use a secret, enter the secret value. You can find the secret in the Microsoft Azure portal. +*** If you want to use a client certificate, enter the client certificate and private key. You can find the certificate ID and private key in the Microsoft Azure portal. +*** If you want to use an Azure managed identity, select the *Use workload identity* checkbox. ++ +For more information, see link:https://learn.microsoft.com/en-us/azure/active-directory-b2c/app-registrations-training-guide[The new App registrations experience for Azure Active Directory B2C] (Microsoft Azure documentation). +** Optional: Choose the appropriate method to configure the data collection rule configuration: +*** Select the *Enable alert DCR* checkbox, if you want to enable the alert data collection rule configuration. ++ +To create an alert data collection rule, enter the alert data collection rule stream name and ID. You can find the stream name and ID in the Microsoft Azure portal. +*** Select the *Enable audit log DCR* checkbox, if you want to enable audit data collection rule configuration. ++ +To create an audit data collection rule, enter the stream name and ID. You can find the stream name and ID in the Microsoft Azure portal. ++ +For more information, see link:https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/data-collection-rule-overview[Data collection rules (DCRs) in Azure Monitor] (Microsoft Azure documentation). + +. Optional: To test the new integration, click *Test*. +. To save the new integration, click *Save*. + +.Verification + +. In the {product-title-short} portal, click *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section, and then click *Microsoft Sentinel*. +. In the *Integrations Microsoft Sentinel* page, verify that the new integration has been created. +. Verify that the messages receive the correct log tables in your log analytics workspace. diff --git a/modules/viewing-the-logs.adoc b/modules/viewing-the-logs.adoc new file mode 100644 index 000000000000..2b82835cf789 --- /dev/null +++ b/modules/viewing-the-logs.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * cli/debugging-issues.adoc + +:_mod-docs-content-type: PROCEDURE +[id="viewing-the-logs_{context}"] += Viewing the logs + +You can use either the `oc` or `kubectl` command to view the logs for the Central pod. + +.Procedure + +* To view the logs for the Central pod by using `kubectl`, run the following command : ++ +[source,terminal,subs="+quotes"] +---- +$ kubectl logs -n stackrox _<central_pod>_ +---- + +* To view the logs for the Central pod by using `oc`, run the following command : ++ +[source,terminal,subs="+quotes"] +---- +$ oc logs -n stackrox _<central_pod>_ +---- \ No newline at end of file diff --git a/modules/violation-view-enforcement-tab.adoc b/modules/violation-view-enforcement-tab.adoc new file mode 100644 index 000000000000..c7a878f8cc20 --- /dev/null +++ b/modules/violation-view-enforcement-tab.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * operating/respond-to-violations.adoc +:_mod-docs-content-type: CONCEPT +[id="violation-view-enforcement-tab_{context}"] += Enforcement tab + +[role="_abstract"] +The *Enforcement* tab of the *Details* panel displays an explanation of the type of enforcement action that was taken in response to the selected policy violation diff --git a/modules/violation-view-policy-tab.adoc b/modules/violation-view-policy-tab.adoc new file mode 100644 index 000000000000..635a2ef37057 --- /dev/null +++ b/modules/violation-view-policy-tab.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * operating/respond-to-violations.adoc +:_mod-docs-content-type: REFERENCE +[id="violation-view-policy-tab_{context}"] += Policy tab + +[role="_abstract"] +The *Policy* tab of the *Details* panel displays details of the policy that caused the violation. + +== Policy overview section + +The *Policy overview* section lists the following information: + +* *Severity*: A ranking of the policy (critical, high, medium, or low) for the amount of attention required. +* *Categories*: The policy category of the policy. Policy categories are listed in *Platform Configuration* -> *Policy Management* in the *Policy categories* tab. +* *Type*: Whether the policy is user generated (policies created by a user) or a system policy (policies built into {product-title-short} by default). +* *Description*: A detailed explanation of what the policy alert is about. +* *Rationale*: Information about the reasoning behind the establishment of the policy and why it matters. +* *Guidance*: Suggestions on how to address the violation. +* *MITRE ATT&CK*: Indicates if there are MITRE link:https://attack.mitre.org/matrices/enterprise/containers/[tactics and techniques] that apply to this policy. + +== Policy behavior + +The *Policy behavior* section provides the following information: + +* *Lifecycle Stage*: Lifecycle stages that the policy belongs to, `Build`, `Deploy`, or `Runtime`. +* *Event source*: This field is only applicable if the lifecycle stage is `Runtime`. It can be one of the following: +** *Deployment*: {product-title-short} triggers policy violations when event sources include process and network activity, pod execution, and pod port forwarding. +** *Audit logs*: {product-title-short} triggers policy violations when event sources match Kubernetes audit log records. +* *Response*: The response can be one of the following: +** *Inform*: Policy violations generate a violation in the violations list. +** *Inform and enforce*: The violation is enforced. +* *Enforcement*: If the response is set to *Inform and enforce*, lists the type of enforcement that is set for the following stages: +** *Build*: {product-title-short} fails your continuous integration (CI) builds when images match the criteria of the policy. +** *Deploy*: For the *Deploy* stage, {product-title-short} blocks the creation and update of deployments that match the conditions of the policy if the {product-title-short} admission controller is configured and running. +*** In clusters with admission controller enforcement, the Kubernetes or {ocp} API server blocks all noncompliant deployments. In other clusters, {product-title-short} edits noncompliant deployments to prevent pods from being scheduled. +*** For existing deployments, policy changes only result in enforcement at the next detection of the criteria, when a Kubernetes event occurs. For more information about enforcement, see "Security policy enforcement for the deploy stage". +** *Runtime*: {product-title-short} deletes all pods when an event in the pods matches the criteria of the policy. + +== Policy criteria section + +The *Policy criteria* section lists the policy criteria for the policy. diff --git a/modules/violation-view-violation-tab.adoc b/modules/violation-view-violation-tab.adoc new file mode 100644 index 000000000000..c6bcc7b60dcc --- /dev/null +++ b/modules/violation-view-violation-tab.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * operating/respond-to-violations.adoc +:_mod-docs-content-type: CONCEPT +[id="violation-view-violation-tab_{context}"] += Violation tab + +[role="_abstract"] +The *Violation* tab of the *Violation Details* panel explains how the policy was violated. +If the policy targets deploy-phase attributes, you can view the specific values that violated the policies, such as violation names. +If the policy targets runtime activity, you can view detailed information about the process that violated the policy, including its arguments and the ancestor processes that created it. diff --git a/modules/violations-page-overview.adoc b/modules/violations-page-overview.adoc new file mode 100644 index 000000000000..134efdade58a --- /dev/null +++ b/modules/violations-page-overview.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * operating/respond-to-violations.adoc + +:_mod-docs-content-type: CONCEPT +[id="violations-page-overview_{context}"] += Violations page overview + +The *Violations* page shows a list of violations and organizes information into the following groups: + +* *Policy*: The name of the violated policy. +* *Entity*: The entity where the violation occurred. +* *Type*: The type of entity. ++ +For workload violations, the type indicates the workload type, for example, `Deployment`, `Pod`, `DaemonSet`, and so on. ++ +For other resource violations, the type indicates the resource type, for example, `Secrets`, `ConfigMaps`, `ClusterRoles`, and so on. +* *Enforced*: Indicates if the policy was enforced when the violation occurred. +* *Severity*: The severity of the violation. ++ +The following values are associated with the severity of the violation: ++ +** `Low` +** `Medium` +** `High` +** `Critical` +* *Categories*: The category of the violated policy. ++ +To view the policy categories: ++ +** In the {product-title-short} portal, click the *Platform Configuration* -> *Policy Management* -> *Policy categories* tab. +* *Lifecycle*: The lifecycle stages to which the policy applies. ++ +The following values are associated with the lifecycle stages: ++ +** `Build` +** `Deploy` +** `Runtime` +* *Time*: The date and time when the violation occurred. \ No newline at end of file diff --git a/modules/violations-view-deployment-tab.adoc b/modules/violations-view-deployment-tab.adoc new file mode 100644 index 000000000000..ec0a71bbd027 --- /dev/null +++ b/modules/violations-view-deployment-tab.adoc @@ -0,0 +1,74 @@ +// Module included in the following assemblies: +// +// * operating/respond-to-violations.adoc +:_mod-docs-content-type: REFERENCE +[id="violations-view-deployment-tab_{context}"] += Deployment tab + +[role="_abstract"] +The *Deployment* tab of the *Details* panel displays details of the deployment to which the violation applies. + +== Overview section + +The *Deployment overview* section lists the following information: + +* *Deployment ID*: The alphanumeric identifier for the deployment. +* *Deployment name*: The name of the deployment. +* *Deployment type*: The type of the deployment. +* *Cluster*: The name of the cluster where the container is deployed. +* *Namespace*: The unique identifier for the deployed cluster. +* *Replicas*: The number of the replicated deployments. +* *Created*: The time and date when the deployment was created. +* *Updated*: The time and date when the deployment was updated. +* *Labels*: The labels that apply to the selected deployment. +* *Annotations*: The annotations that apply to the selected deployment. +* *Service Account*: The name of the service account for the selected deployment. + +== Container configuration section + +The *Container configuration* section lists the following information: + +* *containers*: For each container, provides the following information: +** *Image name*: The name of the image for the selected deployment. Click the name to view more information about the image. +** *Resources*: This section provides information for the following fields: +*** *CPU request (cores)*: The number of cores requested by the container. +*** *CPU limit (cores)*: The maximum number of cores that can be requested by the container. +*** *Memory request (MB)*: The memory size requested by the container. +*** *Memory limit (MB)*: The maximum memory that can be requested by the container. +** *volumes*: Volumes mounted in the container, if any. +** *secrets*: Secrets associated with the selected deployment. For each secret, provides information for the following fields: +*** *Name*: Name of the secret. +*** *Container path*: Location where the secret is stored. +** *Name*: The name of the location where the service will be mounted. +** *Source*: The data source path. +** *Destination*: The path where the data is stored. +** *Type*: The type of the volume. + +== Port configuration section + +The *Port configuration* section provides information about the ports in the deployment, including the following fields: + +* *ports*: All ports exposed by the deployment and any Kubernetes services associated with this deployment and port if they exist. For each port, the following fields are listed: +** *containerPort*: The port number exposed by the deployment. +** *protocol*: Protocol, such as, TCP or UDP, that is used by the port. +** *exposure*: Exposure method of the service, for example, load balancer or node port. +** *exposureInfo*: This section provides information for the following fields: +*** *level*: Indicates if the service exposing the port internally or externally. +*** *serviceName*: Name of the Kubernetes service. +*** *serviceID*: ID of the Kubernetes service as stored in {product-title-short}. +*** *serviceClusterIp*: The IP address that another deployment or service _within the cluster_ can use to reach the service. This is not the external IP address. +*** *servicePort*: The port used by the service. +*** *nodePort*: The port on the node where external traffic comes into the node. +*** *externalIps*: The IP addresses that can be used to access the service externally, from outside the cluster, if any exist. This field is not available for an internal service. + +== Security context section + +The *Security context* section lists whether the container is running as a privileged container. + +* *Privileged*: +** `true` if it is *privileged*. +** `false` if it is *not privileged*. + +== Network policy section + +The *Network policy* section lists the namespace and all network policies in the namespace containing the violation. Click on a network policy name to view the full YAML file of the network policy. \ No newline at end of file diff --git a/modules/virt-about-block-pvs.adoc b/modules/virt-about-block-pvs.adoc deleted file mode 100644 index 0a64cb845622..000000000000 --- a/modules/virt-about-block-pvs.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc - -[id="virt-about-block-pvs_{context}"] -= About block persistent volumes - -A block persistent volume (PV) is a PV that is backed by a raw block device. These volumes -do not have a file system and can provide performance benefits for -virtual machines by reducing overhead. - -Raw block volumes are provisioned by specifying `volumeMode: Block` in the -PV and persistent volume claim (PVC) specification. diff --git a/modules/virt-about-collecting-virt-data.adoc b/modules/virt-about-collecting-virt-data.adoc deleted file mode 100644 index 1f0e61a29754..000000000000 --- a/modules/virt-about-collecting-virt-data.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-collecting-virt-data.adoc - -//This file contains UI elements and/or package names that need to be updated. - -[id="virt-about-collecting-virt-data_{context}"] -= About collecting {VirtProductName} data - -You can use the `oc adm must-gather` CLI command to collect information about your -cluster, including features and objects associated with {VirtProductName}: - -* The Hyperconverged Cluster Operator namespaces (and child objects) -* All namespaces (and their child objects) that belong to any {VirtProductName} -resources -* All {VirtProductName} custom resource definitions (CRDs) -* All namespaces that contain virtual machines -* All virtual machine definitions - -To collect {VirtProductName} data with `must-gather`, you must specify the -{VirtProductName} image: -`--image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel8:v{HCOVersion}`. diff --git a/modules/virt-about-conditions-and-events.adoc b/modules/virt-about-conditions-and-events.adoc deleted file mode 100644 index f5cf3cf1b299..000000000000 --- a/modules/virt-about-conditions-and-events.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-diagnosing-datavolumes-using-events-and-conditions.adoc - -[id="virt-about-conditions-and-events.adoc_{context}"] -= About conditions and events - -Diagnose data volume issues by examining the output of the `Conditions` and `Events` sections -generated by the command: - -[source,terminal] ----- -$ oc describe dv <DataVolume> ----- - -There are three `Types` in the `Conditions` section that display: - -* `Bound` -* `Running` -* `Ready` - -The `Events` section provides the following additional information: - -* `Type` of event -* `Reason` for logging -* `Source` of the event -* `Message` containing additional diagnostic information. - -The output from `oc describe` does not always contains `Events`. - -An event is generated when either `Status`, `Reason`, or `Message` changes. -Both conditions and events react to changes in the state of the data volume. - -For example, if you misspell the URL during an import operation, the import -generates a 404 message. That message change generates an event with a reason. -The output in the `Conditions` section is updated as well. diff --git a/modules/virt-about-container-disks.adoc b/modules/virt-about-container-disks.adoc deleted file mode 100644 index 07f8fb78208a..000000000000 --- a/modules/virt-about-container-disks.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc -// * virt/virtual_machines/importing_vms/virt-importing-container-disk-with-datavolumes.adoc - -[id="virt-about-container-disks_{context}"] -= About container disks - -A container disk is a virtual machine image that is stored as a container image in a container image registry. You can use container disks to deliver the same disk images to multiple virtual machines and to create large numbers of virtual machine clones. - -A container disk can either be imported into a persistent volume claim (PVC) by using a data volume that is attached to a virtual machine, or attached directly to a virtual machine as an ephemeral `containerDisk` volume. - -== Importing a container disk into a PVC by using a data volume - -Use the Containerized Data Importer (CDI) to import the container disk into a PVC by using a data volume. You can then attach the data volume to a virtual machine for persistent storage. - -== Attaching a container disk to a virtual machine as a `containerDisk` volume - -A `containerDisk` volume is ephemeral. It is discarded when the virtual machine is stopped, restarted, or deleted. When a virtual machine with a `containerDisk` volume starts, the container image is pulled from the registry and hosted on the node that is hosting the virtual machine. - -Use `containerDisk` volumes for read-only file systems such as CD-ROMs or for disposable virtual machines. - -[IMPORTANT] -==== -Using `containerDisk` volumes for read-write file systems is not recommended because the data is temporarily written to local storage on the hosting node. This slows live migration of the virtual machine, such as in the case of node maintenance, because the data must be migrated to the destination node. Additionally, all data is lost if the node loses power or otherwise shuts down unexpectedly. -==== - diff --git a/modules/virt-about-cpu-and-memory-quota-namespace.adoc b/modules/virt-about-cpu-and-memory-quota-namespace.adoc deleted file mode 100644 index 16adfb25a50c..000000000000 --- a/modules/virt-about-cpu-and-memory-quota-namespace.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-configuring-cdi-for-namespace-resourcequota.adoc - -[id="virt-about-cpu-and-memory-quota-namespace_{context}"] -= About CPU and memory quotas in a namespace - -A _resource quota_, defined by the `ResourceQuota` object, imposes restrictions on a namespace that limit the total amount of compute resources that can be consumed by resources within that namespace. - -The `CDI` object defines the user configuration for the Containerized Data Importer (CDI). The CPU and memory request and limit values for the `CDI` object are set to a default value of 0. -This ensures that pods created by CDI that do not specify compute resource requirements are given the default values and are allowed to run in a namespace that is restricted with a quota. diff --git a/modules/virt-about-datavolumes.adoc b/modules/virt-about-datavolumes.adoc deleted file mode 100644 index 01b8cc17b6fc..000000000000 --- a/modules/virt-about-datavolumes.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-expanding-virtual-storage-with-blank-disk-images.adoc -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc -// * virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-using-datavolumetemplate.adoc -// * virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc - -[id="virt-about-datavolumes_{context}"] -= About data volumes - -`DataVolume` objects are custom resources that are provided by the Containerized -Data Importer (CDI) project. Data volumes orchestrate import, clone, and upload -operations that are associated with an underlying persistent volume claim (PVC). -Data volumes are integrated with {VirtProductName}, and they prevent a virtual machine -from being started before the PVC has been prepared. diff --git a/modules/virt-about-dedicated-resources.adoc b/modules/virt-about-dedicated-resources.adoc deleted file mode 100644 index d92ef60ef6f4..000000000000 --- a/modules/virt-about-dedicated-resources.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-dedicated-resources-vm.adoc -// * virt/vm_templates/virt-dedicated-resources-vm-template.adoc - -[id="virt-about-dedicated-resources_{context}"] - -= About dedicated resources - -When you enable dedicated resources for your virtual machine, your virtual -machine's workload is scheduled on CPUs that will not be used by other -processes. By using dedicated resources, you can improve the performance of the -virtual machine and the accuracy of latency predictions. diff --git a/modules/virt-about-efi-mode-for-vms.adoc b/modules/virt-about-efi-mode-for-vms.adoc deleted file mode 100644 index b0e8139220d4..000000000000 --- a/modules/virt-about-efi-mode-for-vms.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-efi-mode-for-vms.adoc - -[id="virt-about-efi-mode-for-vms_{context}"] -= About EFI mode for virtual machines - -Extensible Firmware Interface (EFI), like legacy BIOS, initializes hardware components and operating system image files when a computer starts. EFI supports more modern features and customization options than BIOS, enabling faster boot times. - -It stores all the information about initialization and startup in a file with a `.efi` extension, which is stored on a special partition called EFI System Partition (ESP). The ESP also contains the boot loader programs for the operating system that is installed on the computer. - - -[NOTE] -==== -{VirtProductName} only supports a virtual machine (VM) with Secure Boot when using EFI mode. If Secure Boot is not enabled, the VM crashes repeatedly. However, the VM might not support Secure Boot. Before you boot a VM, verify that it supports Secure Boot by checking the VM settings. -==== diff --git a/modules/virt-about-hostpath-provisioner.adoc b/modules/virt-about-hostpath-provisioner.adoc deleted file mode 100644 index 119db362fec4..000000000000 --- a/modules/virt-about-hostpath-provisioner.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc - -[id="virt-about-hostpath-provisioner_{context}"] -= About the hostpath provisioner - -The hostpath provisioner is a local storage provisioner designed for -{VirtProductName}. If you want to configure local storage for -virtual machines, you must enable the hostpath provisioner first. - -When you install the {VirtProductName} Operator, the hostpath provisioner Operator -is automatically installed. To use it, you must: - -* Configure SELinux: -** If you use Red Hat Enterprise Linux CoreOS 8 workers, you must create a `MachineConfig` -object on each node. -** Otherwise, apply the SELinux label `container_file_t` to the persistent volume (PV) backing -directory on each node. -* Create a `HostPathProvisioner` custom resource. -* Create a `StorageClass` object for the hostpath provisioner. - -The hostpath provisioner Operator deploys the provisioner as a _DaemonSet_ on each -node when you create its custom resource. In the custom resource file, you specify -the backing directory for the persistent volumes that the hostpath provisioner -creates. diff --git a/modules/virt-about-kubemacpool.adoc b/modules/virt-about-kubemacpool.adoc deleted file mode 100644 index 87b7d2955450..000000000000 --- a/modules/virt-about-kubemacpool.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc - -[id="virt-about-kubemacpool_{context}"] -= About KubeMacPool - -If you enable the KubeMacPool component for a namespace, virtual machine NICs in that namespace are allocated MAC addresses from a MAC address pool. -This ensures that the NIC is assigned a unique MAC address that does not conflict with the MAC address of another virtual machine. - -Virtual machine instances created from that virtual machine retain the assigned MAC address across reboots. - -[NOTE] -==== -KubeMacPool does not handle virtual machine instances created independently from a virtual machine. -==== - -KubeMacPool is disabled by default. -Enable a MAC address pool for a namespace by applying the KubeMacPool label to the namespace. - diff --git a/modules/virt-about-liveness-readiness-probes.adoc b/modules/virt-about-liveness-readiness-probes.adoc deleted file mode 100644 index 472673054e5c..000000000000 --- a/modules/virt-about-liveness-readiness-probes.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-monitoring-vm-health.adoc - -[id="virt-about-liveness-readiness-probes_{context}"] - -= About liveness and readiness probes - -_Liveness probes_ determine if a virtual machine instance (VMI) is still responding. If the probe fails, the VMI is stopped. A replacement VMI is then created to restore virtual machine responsiveness. - -_Readiness probes_ tell services and endpoints that the virtual machine instance -is ready to receive traffic from services. If readiness probes fail, the virtual machine instance is removed from applicable endpoints until the probe recovers. diff --git a/modules/virt-about-nmstate.adoc b/modules/virt-about-nmstate.adoc deleted file mode 100644 index bc4dc39bfdff..000000000000 --- a/modules/virt-about-nmstate.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-observing-node-network-state.adoc -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-observing-node-network-state.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-about-nmstate_{context}"] -= About nmstate - -{VirtProductName} uses link:https://nmstate.github.io/[`nmstate`] to report on and configure the state of the node network. This makes it possible to modify network policy configuration, such as by creating a Linux bridge on all nodes, by applying a single configuration manifest to the cluster. - -Node networking is monitored and updated by the following objects: - -`NodeNetworkState`:: Reports the state of the network on that node. -`NodeNetworkConfigurationPolicy`:: Describes the requested network configuration on nodes. You update the node network configuration, including adding and removing interfaces, by applying a `NodeNetworkConfigurationPolicy` manifest to the cluster. -`NodeNetworkConfigurationEnactment`:: Reports the network policies enacted upon each node. - -{VirtProductName} supports the use of the following nmstate interface types: - -* Linux Bridge - -* VLAN - -* Bond - -* Ethernet - -[NOTE] -==== -If your {product-title} cluster uses OVN-Kubernetes as the default Container Network Interface (CNI) provider, you cannot attach a Linux bridge or bonding to the default interface of a host because of a change in the host network topology of OVN-Kubernetes. As a workaround, you can use a secondary network interface connected to your host, or switch to the OpenShift SDN default CNI provider. -==== diff --git a/modules/virt-about-node-placement-virtualization-components.adoc b/modules/virt-about-node-placement-virtualization-components.adoc deleted file mode 100644 index abeabb8cd758..000000000000 --- a/modules/virt-about-node-placement-virtualization-components.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/virt-specifying-nodes-for-virtualization-components.adoc - -[id="virt-about-node-placement-virtualization-components_{context}"] -= About node placement for virtualization components - -You might want to customize where {VirtProductName} deploys its components to ensure that: - -* Virtual machines only deploy on nodes that are intended for virtualization workloads. -* Operators only deploy on infrastructure nodes. -* Certain nodes are unaffected by {VirtProductName}. For example, you have workloads unrelated to virtualization running on your cluster, and you want those workloads to be isolated from {VirtProductName}. - -[id="how-to-apply-node-placement-rules-virt-components"] -== How to apply node placement rules to virtualization components - -You can specify node placement rules for a component by editing the corresponding object directly or by using the web console. - -* For the {VirtProductName} Operators that Operator Lifecycle Manager (OLM) deploys, edit the OLM `Subscription` object directly. Currently, you cannot configure node placement rules for the `Subscription` object by using the web console. -* For components that the {VirtProductName} Operators deploy, edit the `HyperConverged` object directly or configure it by using the web console during {VirtProductName} installation. -* For the hostpath provisioner, edit the `HostPathProvisioner` object directly or configure it by using the web console. -+ -[WARNING] -==== -You must schedule the hostpath provisioner and the virtualization components on the same nodes. Otherwise, virtualization pods that use the hostpath provisioner cannot run. -==== - -Depending on the object, you can use one or more of the following rule types: - -`nodeSelector`:: Allows pods to be scheduled on nodes that are labeled with the key-value pair or pairs that you specify in this field. The node must have labels that exactly match all listed pairs. -`affinity`:: Enables you to use more expressive syntax to set rules that match nodes with pods. Affinity also allows for more nuance in how the rules are applied. For example, you can specify that a rule is a preference, rather than a hard requirement, so that pods are still scheduled if the rule is not satisfied. -`tolerations`:: Allows pods to be scheduled on nodes that have matching taints. If a taint is applied to a node, that node only accepts pods that tolerate the taint. - -[id="node-placement-olm-subscription_{context}"] -== Node placement in the OLM Subscription object - -To specify the nodes where OLM deploys the {VirtProductName} Operators, edit the `Subscription` object during {VirtProductName} installation. You can include node placement rules in the `spec.config` field, as shown in the following example: - -[source,yaml,subs="attributes+"] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: hco-operatorhub - namespace: openshift-cnv -spec: - source: redhat-operators - sourceNamespace: openshift-marketplace - name: kubevirt-hyperconverged - startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} - channel: "stable" - config: <1> ----- -<1> The `config` field supports `nodeSelector` and `tolerations`, but it does not support `affinity`. - -[id="node-placement-hco_{context}"] -== Node placement in the HyperConverged object - -To specify the nodes where {VirtProductName} deploys its components, you can include the `nodePlacement` object in the HyperConverged Cluster custom resource (CR) file that you create during {VirtProductName} installation. You can include `nodePlacement` under the `spec.infra` and `spec.workloads` fields, as shown in the following example: - -[source,yaml] ----- -apiVersion: hco.kubevirt.io/v1beta1 -kind: HyperConverged -metadata: - name: kubevirt-hyperconverged - namespace: openshift-cnv -spec: - infra: - nodePlacement: <1> - workloads: - nodePlacement: ----- -<1> The `nodePlacement` field supports `nodeSelector`, `affinity`, and `tolerations` fields. - -[id="node-placement-hpp_{context}"] -== Node placement in the HostPathProvisioner object - -You can configure node placement rules in the `spec.workload` field of the `HostPathProvisioner` object that you create when you install the hostpath provisioner. - -[source,yaml] ----- -apiVersion: hostpathprovisioner.kubevirt.io/v1beta1 -kind: HostPathProvisioner -metadata: - name: hostpath-provisioner -spec: - imagePullPolicy: IfNotPresent - pathConfig: - path: "</path/to/backing/directory>" - useNamingPrefix: false - workload: <1> ----- -<1> The `workload` field supports `nodeSelector`, `affinity`, and `tolerations` fields. \ No newline at end of file diff --git a/modules/virt-about-preallocation.adoc b/modules/virt-about-preallocation.adoc deleted file mode 100644 index 26d09fc0dbca..000000000000 --- a/modules/virt-about-preallocation.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc - -[id="virt-about-preallocation_{context}"] -= About preallocation - -The Containerized Data Importer (CDI) can use the QEMU preallocate mode for data volumes to improve write performance. You can use preallocation mode for importing and uploading operations and when creating blank data volumes. - -If preallocation is enabled, CDI uses the better preallocation method depending on the underlying file system and device type: - -`fallocate`:: -If the file system supports it, CDI uses the operating system's `fallocate` call to preallocate space by using the `posix_fallocate` function, which allocates blocks and marks them as uninitialized. - -`full`:: -If `fallocate` mode cannot be used, `full` mode allocates space for the image by writing data to the underlying storage. Depending on the storage location, all the empty allocated space might be zeroed. diff --git a/modules/virt-about-qemu-guest-agent-web.adoc b/modules/virt-about-qemu-guest-agent-web.adoc deleted file mode 100644 index b28da559851b..000000000000 --- a/modules/virt-about-qemu-guest-agent-web.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-viewing-qemu-guest-agent-information.adoc - -[id="About-the-qemu-guest-agent-web_{context}"] -= About the QEMU guest agent information in the web console - -When the QEMU guest agent is installed, the *Details* pane within the *Virtual Machine Overview* tab and the *Details* tab display information about the host name, operating system, time zone, and logged in users. - -The *Virtual Machine Overview* shows information about the guest operating system installed on the virtual machine. The *Details* tab displays a table with information for logged in users. The *Disks* tab displays a table with information for file systems. - -[NOTE] -==== -If the QEMU guest agent is not installed, the *Virtual Machine Overview* tab and the *Details* tab display information about the operating system that was specified when the virtual machine was created. -==== diff --git a/modules/virt-about-reclaiming-statically-provisioned-persistent-volumes.adoc b/modules/virt-about-reclaiming-statically-provisioned-persistent-volumes.adoc deleted file mode 100644 index df92bec9e2c2..000000000000 --- a/modules/virt-about-reclaiming-statically-provisioned-persistent-volumes.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// virt/virtual_machines/virtual_disks/virt-reusing-statically-provisioned-persistent-volumes.adoc - -[id="virt-about-reclaiming-statically-provisioned-persistent-volumes_{context}"] - -= About reclaiming statically provisioned persistent volumes - -When you reclaim a persistent volume (PV), you unbind the PV from a persistent volume claim (PVC) and delete the PV. Depending on the underlying storage, you might need to manually delete the shared storage. - -You can then re-use the PV configuration to create a PV with a different name. - -Statically provisioned PVs must have a reclaim policy of `Retain` to be reclaimed. -If they do not, the PV enters a failed state when the PVC is unbound from the PV. - -[IMPORTANT] -==== -The `Recycle` reclaim policy is deprecated in {product-title} 4. -==== diff --git a/modules/virt-about-red-hat-ansible-automation.adoc b/modules/virt-about-red-hat-ansible-automation.adoc deleted file mode 100644 index 8620a460a474..000000000000 --- a/modules/virt-about-red-hat-ansible-automation.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-automating-management-tasks.adoc - -[id="virt-about-red-hat-ansible-automation_{context}"] -= About Red Hat Ansible Automation - -link:https://docs.ansible.com/ansible/latest/index.html[Ansible] is an automation -tool used to configure systems, deploy software, and perform rolling updates. -Ansible includes support for {VirtProductName}, and Ansible modules enable you to -automate cluster management tasks such as template, persistent volume claim, and -virtual machine operations. - -Ansible provides a way to automate {VirtProductName} management, which you can also -accomplish by using the `oc` CLI tool or APIs. Ansible is unique because it -allows you to integrate -link:https://docs.ansible.com/ansible/latest/modules/list_of_cloud_modules.html#kubevirt[KubeVirt modules] with other Ansible modules. diff --git a/modules/virt-about-runstrategies-vms.adoc b/modules/virt-about-runstrategies-vms.adoc deleted file mode 100644 index 5dda7bbd1606..000000000000 --- a/modules/virt-about-runstrategies-vms.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc - -[id="virt-about-runstrategies-vms_{context}"] -= About RunStrategies for virtual machines - -A `RunStrategy` for virtual machines determines a virtual machine instance's (VMI) behavior, depending on a series of conditions. The `spec.runStrategy` setting exists in the virtual machine configuration process as an alternative to the `spec.running` setting. -The `spec.runStrategy` setting allows greater flexibility for how VMIs are created and managed, in contrast to the `spec.running` setting with only `true` or `false` responses. However, the two settings are mutually exclusive. Only either `spec.running` or `spec.runStrategy` can be used. An error occurs if both are used. - -There are four defined RunStrategies. - -`Always`:: -A VMI is always present when a virtual machine is created. A new VMI is created if the original stops for any reason, which is the same behavior as `spec.running: true`. -`RerunOnFailure`:: -A VMI is re-created if the previous instance fails due to an error. The instance is not re-created if the virtual machine stops successfully, such as when it shuts down. -`Manual`:: -The `start`, `stop`, and `restart` virtctl client commands can be used to control the VMI's state and existence. -`Halted`:: -No VMI is present when a virtual machine is created, which is the same behavior as `spec.running: false`. - -Different combinations of the `start`, `stop` and `restart` virtctl commands affect which `RunStrategy` is used. - -The following table follows a VM’s transition from different states. The first column shows the VM's initial `RunStrategy`. Each additional column shows a virtctl command and the new `RunStrategy` after that command is run. - -|=== -|Initial RunStrategy |start |stop |restart - -|Always -|- -|Halted -|Always - -|RerunOnFailure -|- -|Halted -|RerunOnFailure - -|Manual -|Manual -|Manual -|Manual - -|Halted -|Always -|- -|- -|=== - -[NOTE] -==== -In {VirtProductName} clusters installed using installer-provisioned infrastructure, when a node fails the MachineHealthCheck and becomes unavailable to the cluster, VMs with a RunStrategy of `Always` or `RerunOnFailure` are rescheduled on a new node. -==== - -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachine -spec: - RunStrategy: Always <1> - template: -... ----- -<1> The VMI's current `RunStrategy` setting. diff --git a/modules/virt-about-storage-setting-for-datavolumes.adoc b/modules/virt-about-storage-setting-for-datavolumes.adoc deleted file mode 100644 index a12e1237b90d..000000000000 --- a/modules/virt-about-storage-setting-for-datavolumes.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc - -[id="virt-about-kubevirtstorageclassdefaults_{context}"] -= About storage settings for data volumes - -Data volumes require a defined _access mode_ and _volume mode_ to be created in the web console. -These storage settings are configured by default with a `ReadWriteOnce` access mode and `Filesystem` volume mode. - -You can modify these settings by editing the `kubevirt-storage-class-defaults` config map in the `openshift-cnv` namespace. -You can also add settings for other storage classes to create data volumes in the web console for different storage types. - -[NOTE] -==== -You must configure storage settings that are supported by the underlying storage. -==== - -All data volumes that you create in the web console use the default storage settings unless you specify a storage class that is also defined in the config map. - -[id="virt-datavolumes-access-modes_{context}"] -== Access modes - -Data volumes support the following access modes: - -* `ReadWriteOnce`: The volume can be mounted as read-write by a single node. `ReadWriteOnce` has greater versatility and is the default setting. -* `ReadWriteMany`: The volume can be mounted as read-write by many nodes. `ReadWriteMany` is required for some features, such as live migration of virtual machines between nodes. - -`ReadWriteMany` is recommended if the underlying storage supports it. - -[id="virt-datavolumes-volume-modes_{context}"] -== Volume modes - -The volume mode defines if a volume is intended to be used with a formatted file system or to remain in raw block state. Data volumes support the following volume modes: - -* `Filesystem`: Creates a file system on the data volume. This is the default setting. -* `Block`: Creates a block data volume. Only use `Block` if the underlying storage supports it. diff --git a/modules/virt-about-the-overview-dashboard.adoc b/modules/virt-about-the-overview-dashboard.adoc deleted file mode 100644 index 36aa662f0fa4..000000000000 --- a/modules/virt-about-the-overview-dashboard.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-using-dashboard-to-get-cluster-info.adoc -// * web_console/using-dashboard-to-get-cluster-information.adoc - -ifeval::["{context}" == "virt-using-dashboard-to-get-cluster-info"] -:virt-cluster: -endif::[] - -[id="virt-about-the-overview-dashboard_{context}"] -= About the {product-title} dashboards page - -The {product-title} dashboard consists of the following cards: - -* *Details* provides a brief overview of informational cluster details. -+ -Status include *ok*, *error*, *warning*, *in progress*, and *unknown*. Resources can add custom status names. -+ -** Cluster ID -** Provider -** Version -* *Cluster Inventory* details number of resources and associated statuses. It is helpful when intervention is required to resolve problems, including information about: -** Number of nodes -** Number of pods -** Persistent storage volume claims -ifdef::virt-cluster[] -** Virtual machines (available if {VirtProductName} is installed) -endif::virt-cluster[] -** Bare metal hosts in the cluster, listed according to their state (only available in *metal3* environment). -ifdef::virt-cluster[] -* *Cluster Health* summarizes the current health of the cluster as a whole, including relevant alerts and descriptions. If {VirtProductName} is installed, the overall health of {VirtProductName} is diagnosed as well. If more than one subsystem is present, click *See All* to view the status of each subsystem. -endif::virt-cluster[] -* *Cluster Capacity* charts help administrators understand when additional resources are required in the cluster. The charts contain an inner ring that displays current consumption, while an outer ring displays thresholds configured for the resource, including information about: -** CPU time -** Memory allocation -** Storage consumed -** Network resources consumed -* *Cluster Utilization* shows the capacity of various resources over a specified period of time, to help administrators understand the scale and frequency of high resource consumption. -* *Events* lists messages related to recent activity in the cluster, such as pod creation or virtual machine migration to another host. -* *Top Consumers* helps administrators understand how cluster resources are consumed. Click on a resource to jump to a detailed page listing pods and nodes that consume the largest amount of the specified cluster resource (CPU, memory, or storage). - -ifeval::["{context}" == "virt-using-dashboard-to-get-cluster-info"] -:!virt-cluster: -endif::[] diff --git a/modules/virt-about-the-vm-dashboard.adoc b/modules/virt-about-the-vm-dashboard.adoc deleted file mode 100644 index 37b2a6026fc4..000000000000 --- a/modules/virt-about-the-vm-dashboard.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-viewing-information-about-vm-workloads.adoc - -[id="virt-about-the-vm-dashboard_{context}"] -= About the Virtual Machines dashboard - -Access virtual machines from the {product-title} web console by navigating -to the *Workloads* -> *Virtualization* page. The *Workloads* -> *Virtualization* page contains two tabs: -* *Virtual Machines* -* *Virtual Machine Templates* - -The following cards describe each virtual machine: - -* *Details* provides identifying information about the virtual machine, including: -** Name -** Namespace -** Date of creation -** Node name -** IP address - -* *Inventory* lists the virtual machine's resources, including: -** Network interface controllers (NICs) -** Disks - -* *Status* includes: -** The current status of the virtual machine -** A note indicating whether or not the QEMU guest agent is installed on the virtual machine - -* *Utilization* includes charts that display usage data for: -** CPU -** Memory -** Filesystem -** Network transfer - -[NOTE] -==== -Use the drop-down list to choose a duration for the utilization data. The available options are *1 Hour*, *6 Hours*, and *24 Hours*. -==== - -* *Events* lists messages about virtual machine activity over the past hour. To view additional events, click *View all*. diff --git a/modules/virt-about-upgrading-virt.adoc b/modules/virt-about-upgrading-virt.adoc deleted file mode 100644 index 55473211ea05..000000000000 --- a/modules/virt-about-upgrading-virt.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/upgrading-virt.adoc - -[id="virt-about-upgrading-virt_{context}"] -= About upgrading {VirtProductName} - -== How {VirtProductName} upgrades work - -* You can upgrade to the next minor version of {VirtProductName} by using the -{product-title} web console to change the channel of your Operator subscription. - -* You can enable automatic _z-stream_ updates during {VirtProductName} installation. - -* Updates are delivered via the _Marketplace Operator_, which is deployed -during {product-title} installation. The Marketplace Operator makes -external Operators available to your cluster. - -* The amount of time an update takes to complete depends on your network -connection. Most automatic updates complete within fifteen minutes. - -== How {VirtProductName} upgrades affect your cluster - -* Upgrading does not interrupt virtual machine workloads. -** Virtual machine pods are not restarted or migrated during an upgrade. If you -need to update the `virt-launcher` pod, you must restart or live migrate the -virtual machine. -+ -[NOTE] -==== -Each virtual machine has a `virt-launcher` pod that runs the virtual machine -instance. The `virt-launcher` pod runs an instance of `libvirt`, which is -used to manage the virtual machine process. -==== - -* Upgrading does not interrupt network connections. - -* Data volumes and their associated persistent volume claims are preserved during -upgrade. -+ -[IMPORTANT] -==== -If you have virtual machines running that cannot be live migrated, they might block an {product-title} cluster upgrade. -This includes virtual machines that use hostpath provisioner storage or SR-IOV network interfaces. - -As a workaround, you can reconfigure the virtual machines so that they can be powered off automatically during a cluster upgrade. Remove the `evictionStrategy: LiveMigrate` field and -set the `runStrategy` field to `Always`. -==== diff --git a/modules/virt-about-vm-console-sessions.adoc b/modules/virt-about-vm-console-sessions.adoc deleted file mode 100644 index c5e868715fa0..000000000000 --- a/modules/virt-about-vm-console-sessions.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-about-vm-console-sessions_{context}"] -= About virtual machine console sessions - -You can connect to the VNC and serial consoles of a running virtual machine from -the *Console* tab on the *Virtual Machine Details* page of the web console. - -The *VNC Console* opens by default when you navigate to -the *Console* tab. You can open a connection to the serial console by clicking -the *VNC Console* drop-down list and selecting *Serial Console*. - -Console sessions remain active in the background unless they are disconnected. To ensure that only one console session is open at a time, click the *Disconnect before switching* check box before switching consoles. - -You can open the active console session in a detached window by clicking the *Open Console in New Window* button or by clicking *Actions* -> *Open Console*. - -.Options for the *VNC Console* -* Send key combinations to the virtual machine by clicking *Send Key*. - -.Options for the *Serial Console* -* Manually disconnect the *Serial Console* session from the virtual machine by clicking *Disconnect*. -* Manually open a *Serial Console* session to the virtual machine by clicking *Reconnect*. diff --git a/modules/virt-about-vm-snapshots.adoc b/modules/virt-about-vm-snapshots.adoc deleted file mode 100644 index c642649a2c3b..000000000000 --- a/modules/virt-about-vm-snapshots.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc - -[id="virt-about-vm-snapshots_{context}"] -= About virtual machine snapshots - -A _snapshot_ represents the state and data of a virtual machine (VM) at a specific point in time. You can use a snapshot to restore an existing VM to a previous state (represented by -the snapshot) for backup and disaster recovery or to rapidly roll back to a previous development version. - -An offline VM snapshot is created from a VM that is powered off (Stopped state). The snapshot stores a copy of each Container Storage Interface (CSI) volume attached to the VM and a copy of the VM -specification and metadata. Snapshots cannot be changed after creation. - -With the offline VM snapshots feature, cluster administrators and application developers can: - -* Create a new snapshot -* List all snapshots attached to a specific VM -* Restore a VM from a snapshot -* Delete an existing VM snapshot - -== Virtual machine snapshot controller and custom resource definitions (CRDs) - -The VM snapshot feature introduces three new API objects defined as CRDs for managing snapshots: - -* `VirtualMachineSnapshot`: Represents a user request to create a snapshot. It contains information about the current state of the VM. -* `VirtualMachineSnapshotContent`: Represents a provisioned resource on the cluster (a snapshot). It is created by the VM snapshot controller and contains references to all resources required to restore the VM. -* `VirtualMachineRestore`: Represents a user request to restore a VM from a snapshot. - -The VM snapshot controller binds a `VirtualMachineSnapshotContent` object with the `VirtualMachineSnapshot` object for which it was created, with a one-to-one mapping. diff --git a/modules/virt-about-vm-templates.adoc b/modules/virt-about-vm-templates.adoc deleted file mode 100644 index aa54d6104d14..000000000000 --- a/modules/virt-about-vm-templates.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-understanding-vm-templates-web_{context}"] -= About virtual machine templates - -Preconfigured Red Hat virtual machine templates are listed in the *Templates* tab within the *Virtualization* page. These templates are available for different versions of Red Hat Enterprise Linux, Fedora, Microsoft Windows 10, and Microsoft Windows Servers. Each Red Hat virtual machine template is preconfigured with the operating system image, default settings for the operating system, flavor (CPU and memory), and workload type (server). - -The *Templates* tab displays four types of virtual machine templates: - -* *Red Hat Supported* templates are fully supported by Red Hat. -* *User Supported* templates are *Red Hat Supported* templates that were cloned and created by users. -* *Red Hat Provided* templates have limited support from Red Hat. -* *User Provided* templates are *Red Hat Provided* templates that were cloned and created by users. - -[NOTE] -==== -In the Templates tab, you cannot edit or delete Red Hat Supported or Red Hat Provided templates. You can only edit or delete custom virtual machine templates that were created by users. -==== - -Using a Red Hat template is convenient because the template is already preconfigured. When you select a Red Hat template to create your own custom template, the *Create Virtual Machine Template* wizard prompts you to add a boot source if a boot source was not added previously. Then, you can either save your custom template or continue to customize it and save it. - -You can also select the *Create Virtual Machine Template* wizard directly and create a custom virtual machine template. The wizard prompts you to provide configuration details for the operating system, flavor, workload type, and other settings. You can add a boot source and continue to customize your template and save it. diff --git a/modules/virt-about-vmis.adoc b/modules/virt-about-vmis.adoc deleted file mode 100644 index 1313b9e7c001..000000000000 --- a/modules/virt-about-vmis.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assembly: -// -// * virt/virtual_machines/virt-manage-vmis.adoc -// - -[id="virt-about-vmis_{context}"] -= About virtual machine instances - -A virtual machine instance (VMI) is a representation of a running virtual machine (VM). When a VMI is owned by a VM or by another object, you manage it through its owner in the web console or by using the `oc` command-line interface (CLI). - -A standalone VMI is created and started independently with a script, through automation, or by using other methods in the CLI. In your environment, you might have standalone VMIs that were developed and started outside of the {VirtProductName} environment. You can continue to manage those standalone VMIs by using the CLI. You can also use the web console for specific tasks associated with standalone VMIs: - -* List standalone VMIs and their details. - -* Edit labels and annotations for a standalone VMI. - -* Delete a standalone VMI. - -When you delete a VM, the associated VMI is automatically deleted. You delete a standalone VMI directly because it is not owned by VMs or other objects. - -[NOTE] -==== -Before you uninstall {VirtProductName}, list and view the standalone VMIs by using the CLI or the web console. Then, delete any outstanding VMIs. -==== diff --git a/modules/virt-accessing-rdp-console.adoc b/modules/virt-accessing-rdp-console.adoc deleted file mode 100644 index 0cfd40aaaa1d..000000000000 --- a/modules/virt-accessing-rdp-console.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-accessing-rdp-console_{context}"] -= Connecting to a Windows virtual machine with an RDP console - -The Remote Desktop Protocol (RDP) provides a better console experience for -connecting to Windows virtual machines. - -To connect to a Windows virtual machine with RDP, specify the IP address of the -attached L2 NIC to your RDP client. - -.Prerequisites - -* A running Windows virtual machine with the QEMU guest agent installed. The -`qemu-guest-agent` is included in the VirtIO drivers. -* A layer 2 NIC attached to the virtual machine. -* An RDP client installed on a machine on the same network as the -Windows virtual machine. - -.Procedure - -. Log in to the {VirtProductName} cluster through the `oc` CLI tool as a user with -an access token. -+ -[source,terminal] ----- -$ oc login -u <user> https://<cluster.example.com>:8443 ----- - -. Use `oc describe vmi` to display the configuration of the running -Windows virtual machine. -+ -[source,terminal] ----- -$ oc describe vmi <windows-vmi-name> ----- -+ -.Example output -[source,yaml] ----- -... -spec: - networks: - - name: default - pod: {} - - multus: - networkName: cnv-bridge - name: bridge-net -... -status: - interfaces: - - interfaceName: eth0 - ipAddress: 198.51.100.0/24 - ipAddresses: - 198.51.100.0/24 - mac: a0:36:9f:0f:b1:70 - name: default - - interfaceName: eth1 - ipAddress: 192.0.2.0/24 - ipAddresses: - 192.0.2.0/24 - 2001:db8::/32 - mac: 00:17:a4:77:77:25 - name: bridge-net -... ----- - -. Identify and copy the IP address of the layer 2 network interface. This is -`192.0.2.0` in the above example, or `2001:db8::` if you prefer IPv6. -. Open an RDP client and use the IP address copied in the previous step for the -connection. -. Enter the *Administrator* user name and password to connect to the -Windows virtual machine. diff --git a/modules/virt-accessing-serial-console.adoc b/modules/virt-accessing-serial-console.adoc deleted file mode 100644 index fa7714d53f02..000000000000 --- a/modules/virt-accessing-serial-console.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-accessing-serial-console_{context}"] -= Accessing the serial console of a virtual machine instance - -The `virtctl console` command opens a serial console to the specified virtual -machine instance. - -.Prerequisites -* The `virt-viewer` package must be installed. -* The virtual machine instance you want to access must be running. - -.Procedure - -* Connect to the serial console with `virtctl`: -+ - -[source,terminal] ----- -$ virtctl console <VMI> ----- diff --git a/modules/virt-accessing-vmi-ssh.adoc b/modules/virt-accessing-vmi-ssh.adoc deleted file mode 100644 index 712f215811d6..000000000000 --- a/modules/virt-accessing-vmi-ssh.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-accessing-vmi-ssh_{context}"] -= Accessing a virtual machine instance via SSH - -You can use SSH to access a virtual machine (VM) after you expose port 22 on it. - -The `virtctl expose` command forwards a virtual machine instance (VMI) port to a node -port and creates a service for enabled access. The following example creates -the `fedora-vm-ssh` service that forwards traffic from a specific port of cluster nodes to port 22 of the `<fedora-vm>` virtual -machine. - -.Prerequisites -* You must be in the same project as the VMI. -* The VMI you want to access must be connected -to the default pod network by using the `masquerade` binding method. -* The VMI you want to access must be running. -* Install the OpenShift CLI (`oc`). - -.Procedure -. Run the following command to create the `fedora-vm-ssh` service: -+ ----- -$ virtctl expose vm <fedora-vm> --port=22 --name=fedora-vm-ssh --type=NodePort <1> ----- -<1> `<fedora-vm>` is the name of the VM that you run the -`fedora-vm-ssh` service on. - -. Check the service to find out which port the service acquired: -+ -[source,terminal] ----- -$ oc get svc ----- - -.Example output -[source,terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -fedora-vm-ssh NodePort 127.0.0.1 <none> 22:32551/TCP 6s ----- -+ -In this example, the service acquired the `32551` port. - -. Log in to the VMI via SSH. Use the `ipAddress` of any of the cluster -nodes and the port that you found in the previous step: -+ -[source,terminal] ----- -$ ssh username@<node_IP_address> -p 32551 ----- diff --git a/modules/virt-accessing-vnc-console.adoc b/modules/virt-accessing-vnc-console.adoc deleted file mode 100644 index 98f1ae4462a2..000000000000 --- a/modules/virt-accessing-vnc-console.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-accessing-vnc-console_{context}"] -= Accessing the graphical console of a virtual machine instances with VNC - -The `virtctl` client utility can use the `remote-viewer` function to open a -graphical console to a running virtual machine instance. This capability is -included in the `virt-viewer` package. - -.Prerequisites - -* The `virt-viewer` package must be installed. -* The virtual machine instance you want to access must be running. - -[NOTE] -==== -If you use `virtctl` via SSH on a remote machine, you must -forward the X session to your machine. -==== - -.Procedure - -. Connect to the graphical interface with the `virtctl` utility: -+ - -[source,terminal] ----- -$ virtctl vnc <VMI> ----- - -. If the command failed, try using the `-v` flag to collect -troubleshooting information: - -+ -[source,terminal] ----- -$ virtctl vnc <VMI> -v 4 ----- diff --git a/modules/virt-add-boot-order-web.adoc b/modules/virt-add-boot-order-web.adoc deleted file mode 100644 index 676eb01fa1c6..000000000000 --- a/modules/virt-add-boot-order-web.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assembly: -// -// * virt/virt_users_guide/virt-edit-boot-order.adoc -// - -[id="virt-add-boot-order-web_{context}"] -= Adding items to a boot order list in the web console - -Add items to a boot order list by using the web console. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine to open the *Virtual Machine Overview* screen. - -. Click the *Details* tab. - -. Click the pencil icon that is located on the right side of *Boot Order*. If a YAML configuration does not exist, or if this is the first time that you are creating a boot order list, the following message displays: *No resource selected. VM will attempt to boot from disks by order of appearance in YAML file.* - -. Click *Add Source* and select a bootable disk or network interface card (NIC) for the virtual machine. - -. Add any additional disks or NICs to the boot order list. - -. Click *Save*. - -[NOTE] -==== -If the virtual machine is running, changes to *Boot Order* will not take effect until you restart the virtual machine. - -You can view pending changes by clicking *View Pending Changes* on the right side of the *Boot Order* field. The *Pending Changes* banner at the -top of the page displays a list of all changes that will be applied when the virtual machine restarts. -==== diff --git a/modules/virt-add-disk-to-vm.adoc b/modules/virt-add-disk-to-vm.adoc deleted file mode 100644 index d76b8c3c166f..000000000000 --- a/modules/virt-add-disk-to-vm.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-edit-vms.adoc -// * virt/vm_templates/virt-editing-vm-template.adoc - -// Establishing conditionals so content can be re-used for editing VMs -// and VM templates. - -ifeval::["{context}" == "virt-edit-vms"] -:virt-vm: -:object: virtual machine -:object-gui: Virtual Machines -:object-vm-overview: Virtual Machine Overview -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:virt-vm-template: -:object: virtual machine template -:object-gui: Templates -:object-vm-overview: VM Template Details -endif::[] - -[id="virt-vm-add-disk_{context}"] - -= Adding a virtual disk to a {object} - -Use this procedure to add a virtual disk to a {object}. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *{object-gui}* tab. - -. Select a {object} to open the *{object-vm-overview}* screen. - -. Click the *Disks* tab. - -. In the *Add Disk* window, specify the *Source*, *Name*, *Size*, *Type*, *Interface*, and *Storage Class*. - -.. Optional: In the *Advanced* list, specify the *Volume Mode* and *Access Mode* for the virtual disk. If you do not specify these parameters, the system uses the default values from the `kubevirt-storage-class-defaults` config map. - -. Click *Add*. - -ifdef::virt-vm[] -[NOTE] -==== -If the {object} is running, the new disk is in the *pending restart* state and will not be attached until you restart the {object}. - -The *Pending Changes* banner at the top of the page displays a list of all changes that will be applied when the {object} restarts. -==== -endif::virt-vm[] - -// Unsetting all conditionals used in module - -ifeval::["{context}" == "virt-edit-vms"] -:virt-vm!: -:object!: -:object-gui!: -:object-vm-overview!: -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:virt-vm-template!: -:object!: -:object-gui!: -:object-vm-overview!: -endif::[] diff --git a/modules/virt-add-nic-to-vm.adoc b/modules/virt-add-nic-to-vm.adoc deleted file mode 100644 index 836fd90b6879..000000000000 --- a/modules/virt-add-nic-to-vm.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-edit-vms.adoc -// * virt/vm_templates/virt-editing-vm-template.adoc - -ifeval::["{context}" == "virt-edit-vms"] -:virt-vm: -:object: virtual machine -:object-gui: Virtual Machines -:object-vm-overview: Virtual Machine Overview -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:virt-vm-template: -:object: virtual machine template -:object-gui: Templates -:object-vm-overview: VM Template Details -endif::[] - -[id="virt-vm-add-nic_{context}"] - -= Adding a network interface to a {object} - -Use this procedure to add a network interface to a {object}. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *{object-gui}* tab. - -. Select a {object} to open the *{object-vm-overview}* screen. - -. Click the *Network Interfaces* tab. - -. Click *Add Network Interface*. - -. In the *Add Network Interface* window, specify the *Name*, *Model*, *Network*, *Type*, and *MAC Address* of the network interface. - -. Click *Add*. - -ifdef::virt-vm[] -[NOTE] -==== -If the {object} is running, the new network interface is in the *pending restart* state and changes will not take effect until you restart the {object}. - -The *Pending Changes* banner at the top of the page displays a list of all changes that will be applied when the {object} restarts. -==== -endif::virt-vm[] - -// Scrubbing all conditionals used in module - -ifeval::["{context}" == "virt-edit-vms"] -:virt-vm!: -:object!: -:object-gui!: -:object-vm-overview!: -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:virt-vm-template!: -:object!: -:object-gui!: -:object-vm-overview!: -endif::[] diff --git a/modules/virt-adding-a-boot-source-web.adoc b/modules/virt-adding-a-boot-source-web.adoc deleted file mode 100644 index 8db14e55d99c..000000000000 --- a/modules/virt-adding-a-boot-source-web.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-adding-a-boot-source-web_{context}"] -= Adding a boot source for a virtual machine template - -A boot source can be configured for any virtual machine template that you want to use for creating virtual machines or custom templates. When virtual machine templates are configured with a boot source, they are labeled *Available* in the *Templates* tab. After you add a boot source to a template, you can create a new virtual machine from the template. - -There are four methods for selecting and adding a boot source in the web console: - -* *Upload local file (creates PVC)* -* *Import via URL (creates PVC)* -* *Clone existing PVC (creates PVC)* -* *Import via Registry (creates PVC)* - -.Prerequisites -* To add a boot source, you must be logged in as a user with the `os-images.kubevirt.io:edit` RBAC role or as an administrator. You do not need special privileges to create a virtual machine from a template with a boot source added. - -* To upload a local file, the operating system image file must exist on your local machine. - -* To import via URL, access to the web server with the operating system image is required. For example: the Red Hat Enterprise Linux web page with images. - -* To clone an existing PVC, access to the project with a PVC is required. - -* To import via registry, access to the container registry is required. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Templates* tab. - -. Identify the virtual machine template for which you want to configure a boot source and click *Add source*. - -. In the *Add boot source to template* window, click *Select boot source*, select a method for creating a persistent volume claim (PVC): *Upload local file*, *Import via URL*, *Clone existing PVC*, or *Import via Registry*. - -.. Optional: Click *Mount this as a CD-ROM boot source* to add an additional disk and mount the disk as a CD-ROM. - -. Enter a value for *Persistent Volume Claim size* to specify the PVC size that is adequate for the uncompressed image and any additional space that is required. - -.. Optional: Enter a name for *Source provider* to associate the name with this template. - -.. Advanced: Click *Storage class* and select the storage class that is used to create the disk. - -.. Advanced: Click *Access mode* and select an access mode for the persistent volume. Supported access modes are: *Single User (RWO)*, *Shared Access (RWX)*, and *Read Only (ROX)*. - -.. Advanced: Click *Volume mode* if you want to select *Block* instead of the default value *Filesystem*. - -. Select the appropriate method to save your boot source: - -.. Click *Save and upload* if you uploaded a local file. - -.. Click *Save and import* if you imported content from a URL or the registry. - -.. Click *Save and clone* if you cloned an existing PVC. - -Your custom virtual machine template with a boot source is listed in the *Templates* tab, and you can create virtual machines by using this template. diff --git a/modules/virt-adding-secret-configmap-service-account-to-vm.adoc b/modules/virt-adding-secret-configmap-service-account-to-vm.adoc deleted file mode 100644 index 63f9e983d6a9..000000000000 --- a/modules/virt-adding-secret-configmap-service-account-to-vm.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-managing-configmaps-secrets-service-accounts.adoc - -[id="virt-adding-secret-configmap-service-account-to-vm_{context}"] - -= Adding a secret, config map, or service account to a virtual machine - -Add a secret, config map, or service account to a virtual machine by using the {product-title} web console. - -.Prerequisites - -* The secret, config map, or service account that you want to add must exist in the same namespace as the target virtual machine. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine to open the *Virtual Machine Overview* screen. - -. Click the *Environment* tab. - -. Click *Select a resource* and select a secret, config map, or service account from the list. A six character serial number is automatically -generated for the selected resource. - -. Click *Save*. - -. Optional. Add another object by clicking *Add Config Map, Secret or Service Account*. - -[NOTE] -==== -.. You can reset the form to the last saved state by clicking *Reload*. - -.. The *Environment* resources are added to the virtual machine as disks. You can mount the secret, config map, or service account as you would mount any other disk. - -.. If the virtual machine is running, changes will not take effect until you restart the virtual machine. The newly added resources are marked as pending changes -for both the *Environment* and *Disks* tab in the *Pending Changes* banner at the top of the page. - -==== - -.Verification - -. From the *Virtual Machine Overview* page, click the *Disks* tab. - -. Check to ensure that the secret, config map, or service account is included in the list of disks. - -. Optional. Choose the appropriate method to apply your changes: - -.. If the virtual machine is running, restart the virtual machine by clicking *Actions* -> *Restart Virtual Machine*. - -.. If the virtual machine is stopped, start the virtual machine by clicking *Actions* -> *Start Virtual Machine*. - -You can now mount the secret, config map, or service account as you would mount any other disk. diff --git a/modules/virt-adding-tls-certificates-for-authenticating-dv-imports.adoc b/modules/virt-adding-tls-certificates-for-authenticating-dv-imports.adoc deleted file mode 100644 index 6d5bb89e166b..000000000000 --- a/modules/virt-adding-tls-certificates-for-authenticating-dv-imports.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-tls-certificates-for-dv-imports.adoc - -[id="virt-adding-tls-certificates-for-authenticating-dv-imports_{context}"] -= Adding TLS certificates for authenticating data volume imports - -TLS certificates for registry or HTTPS endpoints must be added to a config map -to import data from these sources. This config map must be present -in the namespace of the destination data volume. - -Create the config map by referencing the relative file path for the TLS certificate. - -.Procedure - -. Ensure you are in the correct namespace. The config map can only be referenced by data volumes if it is in the same namespace. -+ - -[source,terminal] ----- -$ oc get ns ----- - -. Create the config map: -+ - -[source,terminal] ----- -$ oc create configmap <configmap-name> --from-file=</path/to/file/ca.pem> ----- diff --git a/modules/virt-adding-virtio-drivers-vm-yaml.adoc b/modules/virt-adding-virtio-drivers-vm-yaml.adoc deleted file mode 100644 index 7506130e7206..000000000000 --- a/modules/virt-adding-virtio-drivers-vm-yaml.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc -// * virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc - -//This file contains UI elements and/or package names that need to be updated. - -[id="virt-adding-virtio-drivers-vm-yaml_{context}"] -= Adding VirtIO drivers container disk to a virtual machine - -{VirtProductName} distributes VirtIO drivers for Microsoft Windows as a -container disk, which is available from the -link:https://access.redhat.com/containers/#/registry.access.redhat.com/container-native-virtualization/virtio-win[Red Hat Ecosystem Catalog]. -To install these drivers to a Windows virtual machine, attach the -`container-native-virtualization/virtio-win` container disk to the virtual machine as a SATA CD drive -in the virtual machine configuration file. - -.Prerequisites - -* Download the `container-native-virtualization/virtio-win` container disk from the -link:https://access.redhat.com/containers/#/registry.access.redhat.com/container-native-virtualization/virtio-win[Red Hat Ecosystem Catalog]. -This is not mandatory, because the container disk will be downloaded from the Red Hat registry -if it not already present in the cluster, but it can reduce installation time. - -.Procedure - -. Add the `container-native-virtualization/virtio-win` container disk as a `cdrom` disk in the -Windows virtual machine configuration file. The container disk will be -downloaded from the registry if it is not already present in the cluster. -+ -[source,yaml] ----- -spec: - domain: - devices: - disks: - - name: virtiocontainerdisk - bootOrder: 2 <1> - cdrom: - bus: sata -volumes: - - containerDisk: - image: container-native-virtualization/virtio-win - name: virtiocontainerdisk ----- -<1> {VirtProductName} boots virtual machine disks in the order defined in the -`VirtualMachine` configuration file. You can either define other disks for the -virtual machine before the `container-native-virtualization/virtio-win` container disk or use the optional -`bootOrder` parameter to ensure the virtual machine boots from the correct disk. - If you specify the `bootOrder` for a disk, it must be specified for all disks -in the configuration. - -. The disk is available once the virtual machine has started: -** If you add the container disk to a running virtual machine, use -`oc apply -f <vm.yaml>` in the CLI or reboot the virtual machine for the changes -to take effect. -** If the virtual machine is not running, use `virtctl start <vm>`. - -After the virtual machine has started, the VirtIO drivers can be installed from -the attached SATA CD drive. diff --git a/modules/virt-additional-scc-for-kubevirt-controller.adoc b/modules/virt-additional-scc-for-kubevirt-controller.adoc deleted file mode 100644 index cf874fa85435..000000000000 --- a/modules/virt-additional-scc-for-kubevirt-controller.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virt-additional-security-privileges-controller-and-launcher.adoc - -[id="virt-additional-scc-for-kubevirt-controller_{context}"] -= Additional {product-title} security context constraints and Linux capabilities for the `kubevirt-controller` service account - -Security context constraints (SCCs) control permissions for pods. These permissions include actions that a pod, a collection of containers, can perform and what resources it can access. You can use SCCs to define a set of conditions that a pod must run with to be accepted into the system. - -The `kubevirt-controller` is a cluster controller that creates the virt-launcher pods for virtual machines in the cluster. These virt-launcher pods are granted permissions by the `kubevirt-controller` service account. - -== Additional SCCs granted to the `kubevirt-controller` service account - -The `kubevirt-controller` service account is granted additional SCCs and Linux capabilities so that it can create virt-launcher pods with the appropriate permissions. These extended permissions allow virtual machines to take advantage of {VirtProductName} features that are beyond the scope of typical pods. - -The `kubevirt-controller` service account is granted the following SCCs: - -* `scc.AllowHostDirVolumePlugin = true` + -This allows virtual machines to use the hostpath volume plug-in. - -* `scc.AllowPrivilegedContainer = false` + -This ensures the virt-launcher pod is not run as a privileged container. - -* `scc.AllowedCapabilities = []corev1.Capability{"NET_ADMIN", "NET_RAW", "SYS_NICE"}` + -This provides the following additional Linux capabilities -`NET_ADMIN`, -`NET_RAW`, and -`SYS_NICE`. - -== Viewing the SCC and RBAC definitions for the `kubevirt-controller` - -You can view the `SecurityContextConstraints` definition for the `kubevirt-controller` by using the `oc` tool: - -[source,terminal] ----- -$ oc get scc kubevirt-controller -o yaml ----- - -You can view the RBAC definition for the `kubevirt-controller` clusterrole by using the `oc` tool: - -[source,terminal] ----- -$ oc get clusterrole kubevirt-controller -o yaml ----- diff --git a/modules/virt-analyzing-datavolume-conditions-and-events.adoc b/modules/virt-analyzing-datavolume-conditions-and-events.adoc deleted file mode 100644 index 52cba9e95ef4..000000000000 --- a/modules/virt-analyzing-datavolume-conditions-and-events.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-analyzing-datavolumes-using-events-and-conditions.adoc - -[id="virt-analyzing-datavolume-conditions-and-events_{context}"] -= Analyzing data volumes using conditions and events - -By inspecting the `Conditions` and `Events` sections generated by the `describe` -command, you determine the state of the data volume -in relation to persistent volume claims (PVCs), and whether or -not an operation is actively running or completed. You might also receive messages -that offer specific details about the status of the data volume, and how -it came to be in its current state. - -There are many different combinations of conditions. Each must be evaluated in its unique context. - -Examples of various combinations follow. - -* `Bound` – A successfully bound PVC displays in this example. -+ -Note that the `Type` is `Bound`, so the `Status` is `True`. -If the PVC is not bound, the `Status` is `False`. -+ -When the PVC is bound, an event is generated stating that the PVC is bound. -In this case, the `Reason` is `Bound` and `Status` is `True`. -The `Message` indicates which PVC owns the data volume. -+ -`Message`, in the `Events` section, provides further details including how -long the PVC has been bound (`Age`) and by what resource (`From`), -in this case `datavolume-controller`: -+ -.Example output -[source,terminal] ----- -Status: - Conditions: - Last Heart Beat Time: 2020-07-15T03:58:24Z - Last Transition Time: 2020-07-15T03:58:24Z - Message: PVC win10-rootdisk Bound - Reason: Bound - Status: True - Type: Bound - - Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Bound 24s datavolume-controller PVC example-dv Bound ----- - -* `Running` – In this case, note that `Type` is `Running` and `Status` is `False`, -indicating that an event has occurred that caused an attempted -operation to fail, changing the Status from `True` to `False`. -+ -However, note that `Reason` is `Completed` and the `Message` field indicates -`Import Complete`. -+ -In the `Events` section, the `Reason` and `Message` contain additional -troubleshooting information about the failed operation. In this example, -the `Message` displays an inability to connect due to a `404`, listed in the -`Events` section’s first `Warning`. -+ -From this information, you conclude that an import operation was running, -creating contention for other operations that are -attempting to access the data volume: -+ -.Example output -[source,terminal] ----- -Status: - Conditions: - Last Heart Beat Time: 2020-07-15T04:31:39Z - Last Transition Time: 2020-07-15T04:31:39Z - Message: Import Complete - Reason: Completed - Status: False - Type: Running - - Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Warning Error 12s (x2 over 14s) datavolume-controller Unable to connect - to http data source: expected status code 200, got 404. Status: 404 Not Found - ----- - -* `Ready` – If `Type` is `Ready` and `Status` is `True`, then the data volume is ready -to be used, as in the following example. If the data volume is not ready to be -used, the `Status` is `False`: -+ -.Example output -[source,terminal] ----- -Status: - Conditions: - Last Heart Beat Time: 2020-07-15T04:31:39Z - Last Transition Time: 2020-07-15T04:31:39Z - Status: True - Type: Ready ----- diff --git a/modules/virt-attaching-vm-to-sriov-network.adoc b/modules/virt-attaching-vm-to-sriov-network.adoc deleted file mode 100644 index 8e0d1cbebaa4..000000000000 --- a/modules/virt-attaching-vm-to-sriov-network.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-attaching-vm-to-sriov-network.adoc - -[id="virt-attaching-vm-to-sriov-network_{context}"] -= Attaching a virtual machine to an SR-IOV network - -You can attach the virtual machine to the SR-IOV network by including the network details in the virtual machine configuration. - -.Procedure - -. Include the SR-IOV network details in the `spec.domain.devices.interfaces` and `spec.networks` of the virtual machine configuration: -+ -[source,yaml] ----- -kind: VirtualMachine -... -spec: - domain: - devices: - interfaces: - - name: <default> <1> - masquerade: {} <2> - - name: <nic1> <3> - sriov: {} - networks: - - name: <default> <4> - pod: {} - - name: <nic1> <5> - multus: - networkName: <sriov-network> <6> -... ----- -<1> A unique name for the interface that is connected to the pod network. -<2> The `masquerade` binding to the default pod network. -<3> A unique name for the SR-IOV interface. -<4> The name of the pod network interface. This must be the same as the `interfaces.name` that you defined earlier. -<5> The name of the SR-IOV interface. This must be the same as the `interfaces.name` that you defined earlier. -<6> The name of the SR-IOV network attachment definition. - -. Apply the virtual machine configuration: -+ -[source,terminal] ----- -$ oc apply -f <vm-sriov.yaml> <1> ----- -<1> The name of the virtual machine YAML file. diff --git a/modules/virt-automatic-certificates-renewal.adoc b/modules/virt-automatic-certificates-renewal.adoc deleted file mode 100644 index bebd8aa2623b..000000000000 --- a/modules/virt-automatic-certificates-renewal.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_maintenance/virt-automatic-certificates.adoc - -[id="virt-automatic-certificates-renewal_{context}"] -= Automatic renewal of TLS certificates - -TLS certificates are automatically deleted and replaced according to the following schedule: - -* KubeVirt certificates are renewed daily. - -* Containerized Data Importer controller (CDI) - certificates are renewed every 15 days. - -* MAC pool certificates are renewed every year. - -Automatic TLS certificate rotation does not disrupt any operations. For example, the following operations continue to function without any disruption: - -* Migrations - -* Image uploads - -* VNC and console connections diff --git a/modules/virt-automating-virtual-machine-creation-with-ansible.adoc b/modules/virt-automating-virtual-machine-creation-with-ansible.adoc deleted file mode 100644 index b2eb3c9c5337..000000000000 --- a/modules/virt-automating-virtual-machine-creation-with-ansible.adoc +++ /dev/null @@ -1,103 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-automating-management-tasks.adoc - -[id="virt-automating-virtual-machine-creation-with-ansible_{context}"] -= Automating virtual machine creation - -You can use the `kubevirt_vm` Ansible Playbook to create virtual machines in -your {product-title} cluster using Red Hat Ansible Automation Platform. - -.Prerequisites - -* link:https://access.redhat.com/products/red-hat-ansible-engine[Red Hat Ansible Engine] -version 2.8 or newer - -.Procedure - -. Edit an Ansible Playbook YAML file so that it includes the `kubevirt_vm` task: -+ -[source,yaml] ----- - kubevirt_vm: - namespace: - name: - cpu_cores: - memory: - disks: - - name: - volume: - containerDisk: - image: - disk: - bus: ----- -+ -[NOTE] -==== -This snippet only includes the `kubevirt_vm` portion of the playbook. -==== - -. Edit the values to reflect the virtual machine you want to create, including the -`namespace`, the number of `cpu_cores`, the `memory`, and the `disks`. For -example: -+ -[source,yaml] ----- - kubevirt_vm: - namespace: default - name: vm1 - cpu_cores: 1 - memory: 64Mi - disks: - - name: containerdisk - volume: - containerDisk: - image: kubevirt/cirros-container-disk-demo:latest - disk: - bus: virtio ----- - -. If you want the virtual machine to boot immediately after creation, add -`state: running` to the YAML file. For example: -+ -[source,yaml] ----- - kubevirt_vm: - namespace: default - name: vm1 - state: running <1> - cpu_cores: 1 ----- -<1> Changing this value to `state: absent` deletes the virtual machine, if it -already exists. - -. Run the `ansible-playbook` command, using your playbook's file name as the -only argument: -+ -[source,terminal] ----- -$ ansible-playbook create-vm.yaml ----- - -. Review the output to determine if the play was successful: -+ -.Example output -[source,terminal] ----- -(...) -TASK [Create my first VM] ************************************************************************ -changed: [localhost] - -PLAY RECAP ******************************************************************************************************** -localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 ----- - -. If you did not include `state: running` in your playbook file and you want to -boot the VM now, edit the file so that it includes `state: running` and run the -playbook again: -+ -[source,terminal] ----- -$ ansible-playbook create-vm.yaml ----- diff --git a/modules/virt-booting-efi-mode.adoc b/modules/virt-booting-efi-mode.adoc deleted file mode 100644 index 1f7d758582a2..000000000000 --- a/modules/virt-booting-efi-mode.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-efi-mode-for-vms.adoc - -[id="virt-booting-vms-efi-mode_{context}"] -= Booting virtual machines in EFI mode - -You can configure a virtual machine to boot in EFI mode by editing the VM or VMI manifest. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). - -.Procedure - -. Create a YAML file that defines a VM object or a Virtual Machine Instance (VMI) object. Use the firmware stanza of the example YAML file: -+ -.Booting in EFI mode with secure boot active -[source,yaml] ----- - apiversion: kubevirt.io/v1 - kind: VirtualMachineInstance - metadata: - labels: - special: vmi-secureboot - name: vmi-secureboot - spec: - domain: - devices: - disks: - - disk: - bus: virtio - name: containerdisk - features: - acpi: {} - smm: - enabled: true <1> - firmware: - bootloader: - efi: - secureBoot: true <2> -... ----- -<1> {VirtProductName} requires System Management Mode (`SMM`) to be enabled for Secure Boot in EFI mode to occur. -<2> {VirtProductName} only supports a virtual machine (VM) with Secure Boot when using EFI mode. If Secure Boot is not enabled, the VM crashes repeatedly. However, the VM might not support Secure Boot. Before you boot a VM, verify that it supports Secure Boot by checking the VM settings. - -. Apply the manifest to your cluster by running the following command: -+ -[source,terminal] ----- -$ oc create -f <file_name>.yaml ----- diff --git a/modules/virt-canceling-vm-import.adoc b/modules/virt-canceling-vm-import.adoc deleted file mode 100644 index bf55cfb87a8d..000000000000 --- a/modules/virt-canceling-vm-import.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc -[id='virt-canceling-vm-import_{context}'] -= Canceling a virtual machine import - -You can cancel a virtual machine import in progress by using the web console. - -.Procedure - -. Click *Workloads* -> *Virtual Machines*. - -. Click the Options menu {kebab} of the virtual machine you are importing and select *Delete Virtual Machine*. - -. In the *Delete Virtual Machine* window, click *Delete*. -+ -The virtual machine is removed from the list of virtual machines. diff --git a/modules/virt-cancelling-vm-migration-cli.adoc b/modules/virt-cancelling-vm-migration-cli.adoc deleted file mode 100644 index 051abd570eeb..000000000000 --- a/modules/virt-cancelling-vm-migration-cli.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-cancel-vmi-migration.adoc - -[id="virt-cancelling-vm-migration-cli_{context}"] -= Cancelling live migration of a virtual machine instance in the CLI - -Cancel the live migration of a virtual machine instance by deleting the -`VirtualMachineInstanceMigration` object associated with the migration. - -.Procedure - -* Delete the `VirtualMachineInstanceMigration` object that triggered the live -migration, `migration-job` in this example: -+ - -[source,terminal] ----- -$ oc delete vmim migration-job ----- diff --git a/modules/virt-cancelling-vm-migration-web.adoc b/modules/virt-cancelling-vm-migration-web.adoc deleted file mode 100644 index 6bd816618e9f..000000000000 --- a/modules/virt-cancelling-vm-migration-web.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-cancel-vmi-migration.adoc - -[id="virt-cancelling-vm-migration-web_{context}"] -= Cancelling live migration of a virtual machine instance in the web console - -You can cancel a live migration of the virtual machine instance using the -Options menu {kebab} found on each virtual machine in the -*Virtualization* -> *Virtual Machines* tab, or from the *Actions* menu -available on all tabs in the *Virtual Machine Overview* screen. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. You can cancel the migration from this screen, which makes it easier to -perform actions on multiple virtual machines, or from the -*Virtual Machine Overview* screen where you can view comprehensive details -of the selected virtual machine: -** Click the Options menu {kebab} at the end of virtual machine and select -*Cancel Virtual Machine Migration*. -** Select a virtual machine name to open the *Virtual Machine Overview* -screen and click *Actions* -> *Cancel Virtual Machine Migration*. -. Click *Cancel Migration* to cancel the virtual machine live migration. diff --git a/modules/virt-cdi-supported-operations-matrix.adoc b/modules/virt-cdi-supported-operations-matrix.adoc deleted file mode 100644 index 9123cb78f770..000000000000 --- a/modules/virt-cdi-supported-operations-matrix.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-virtctl.adoc -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc -// * virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-using-datavolumetemplate.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-web.adoc - -[id="virt-cdi-supported-operations-matrix_{context}"] -= CDI supported operations matrix - -This matrix shows the supported CDI operations for content types against endpoints, and which of these operations requires scratch space. - -|=== -|Content types | HTTP | HTTPS | HTTP basic auth | Registry | Upload - -| KubeVirt (QCOW2) -|&#10003; QCOW2 + -&#10003; GZ* + -&#10003; XZ* - -|&#10003; QCOW2** + -&#10003; GZ* + -&#10003; XZ* - -|&#10003; QCOW2 + -&#10003; GZ* + -&#10003; XZ* - -| &#10003; QCOW2* + -&#9633; GZ + -&#9633; XZ - -| &#10003; QCOW2* + -&#10003; GZ* + -&#10003; XZ* - -| KubeVirt (RAW) -|&#10003; RAW + -&#10003; GZ + -&#10003; XZ - -|&#10003; RAW + -&#10003; GZ + -&#10003; XZ - -| &#10003; RAW + -&#10003; GZ + -&#10003; XZ - -| &#10003; RAW* + -&#9633; GZ + -&#9633; XZ - -| &#10003; RAW* + -&#10003; GZ* + -&#10003; XZ* -|=== - -&#10003; Supported operation - -&#9633; Unsupported operation - -$$*$$ Requires scratch space - -$$**$$ Requires scratch space if a custom certificate authority is required diff --git a/modules/virt-cdrom-wizard-fields-web.adoc b/modules/virt-cdrom-wizard-fields-web.adoc deleted file mode 100644 index ee91dd3509fc..000000000000 --- a/modules/virt-cdrom-wizard-fields-web.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -//Removed this module from the -//assemblies noted below for the -//CNV 2.6 Release. Prior to the -//CNV 2.6 Release, this module -//is being used. -// * virt/virtual_machines/virt-create-vms.adoc -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-cdrom-wizard-fields-web_{context}"] -= CD-ROM fields - -|=== -|Source | Description - -|Container -|Specify the container path. For example: `kubevirt/fedora-registry-disk: latest`. - -|URL -|Specify the URL path and size in GiB. Then, select the storage class for this URL from the drop-down list. - -|Attach Disk -|Select the virtual machine disk that you want to attach. - -|=== diff --git a/modules/virt-checking-storage-class.adoc b/modules/virt-checking-storage-class.adoc deleted file mode 100644 index bf0d6c95b39a..000000000000 --- a/modules/virt-checking-storage-class.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc - -[id="virt-checking-storage-class_{context}"] -= Checking the default storage class - -You must check the default storage class to ensure that it is NFS. - -Cinder, the default storage class, does not support VM import. See link:https://bugzilla.redhat.com/show_bug.cgi?id=1856439[(*BZ#1856439*)] for details. - -== Checking the default storage class in the {product-title} console - -You can check the default storage class in the {product-title} console. If the default storage class is not NFS, you can change the default storage class so that it is no longer the default and change the NFS storage class so that it is the default. - -If more than one default storage class is defined, the `VirtualMachineImport` CR uses the default storage class that is first in alphabetical order. - -.Procedure - -. Navigate to *Storage* -> *Storage Classes*. -. Check the default storage class in the *Storage Classes* list. -. If the default storage class is not NFS, edit the default storage class so that it is no longer the default: - -.. Click the Options menu {kebab} of the default storage class and select *Edit Storage Class*. -.. In the *Details* tab, click the Edit button beside *Annotations*. -.. Click the Delete button {delete} on the right side of the `storageclass.kubernetes.io/is-default-class` annotation and then click *Save*. - -. Change an existing NFS storage class to be the default: - -.. Click the Options menu {kebab} of an existing NFS storage class and select *Edit Storage Class*. -.. In the *Details* tab, click the Edit button beside *Annotations*. -.. Enter `storageclass.kubernetes.io/is-default-class` in the *Key* field and `true` in the *Value* field and then click *Save*. - -. Navigate to *Storage* -> *Storage Classes* to verify that the NFS storage class is the only default storage class. - -== Checking the default storage class from the CLI - -You can check the default storage class from the CLI. - -If the default storage class is not NFS, you must change the default storage class to NFS and change the existing default storage class so that it is not the default. If more than one default storage class is defined, the `VirtualMachineImport` CR uses the default storage class that is first in alphabetical order. - -.Procedure - -* Get the storage classes by entering the following command: -+ -[source,terminal] ----- -$ oc get sc ----- - -The `default` storage class is displayed in the output: - -.Example output -[source,terminal,options="nowrap"] ----- -NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANS -... -standard (default) kubernetes.io/cinder Delete WaitForFirstConsumer true ----- diff --git a/modules/virt-cli-reference-controlling-vms.adoc b/modules/virt-cli-reference-controlling-vms.adoc deleted file mode 100644 index f655713f4cf6..000000000000 --- a/modules/virt-cli-reference-controlling-vms.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-controlling-vm-states.adoc - -[id="virt-cli-reference-controlling-vms_{context}"] -= CLI reference for controlling virtual machines - -Use the following `virtctl` client utility and `oc` commands to change the state of the virtual -machines and display lists of the virtual machines and the virtual machine instances -that represent them. - -[NOTE] -==== -When you run `virtctl` commands, you modify the virtual machines themselves, -not the virtual machine instances that represent them in the web console. -==== - -== start - -Start a virtual machine. - -.Example: Start a virtual machine in the current project ----- -$ virtctl start <example-vm> ----- - -.Example: Start a virtual machine in a specific project ----- -$ virtctl start <example-vm> -n <project_name> ----- - -== restart - -Restart a running virtual machine. - -.Example: Restart a virtual machine in the current project ----- -$ virtctl restart <example-vm> ----- - -.Example: Restart a virtual machine in a specific project ----- -$ virtctl restart <example-vm> -n <project_name> ----- - -== stop - -Stop a running virtual machine. - -.Example: Stop a virtual machine in the current project ----- -$ virtctl stop <example-vm> ----- - -.Example: Stop a virtual machine in a specific project ----- -$ virtctl stop <example-vm> -n <project_name> ----- - -== list - -List the virtual machines or virtual machine instances in a project. The -virtual machine instances are abstractions that represent the virtual machines -themselves. - -.Example: List the virtual machines in the current project ----- -$ oc get vm ----- - -.Example: List the virtual machines in a specific project ----- -$ oc get vm -n <project_name> ----- - -.Example: List the running virtual machine instances in the current project ----- -$ oc get vmi ----- - -.Example: List the running virtual machine instances in a specific project ----- -$ oc get vmi -n <project_name> ----- diff --git a/modules/virt-cloning-a-datavolume.adoc b/modules/virt-cloning-a-datavolume.adoc deleted file mode 100644 index ddf0f75388ee..000000000000 --- a/modules/virt-cloning-a-datavolume.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-cloning-a-datavolume-using-smart-cloning.adoc - -[id="virt-cloning-a-datavolume_{context}"] -= Cloning a data volume - -.Prerequisites - -For smart-cloning to occur, the following conditions are required. - -* Your storage provider must support snapshots. -* The source and target PVCs must be defined to the same namespace. -* The source and target PVCs must be defined to the same storage class. -* The `VolumeSnapshotClass` object must reference the storage class defined to both the source and target PVCs. - -If any of these prerequisites are not met, host-assisted cloning automatically occurs when you create a data volume with a PVC source. - -.Procedure - -To initiate cloning of a data volume: - -. Create a YAML file for a `DataVolume` object that specifies the name of the -new data volume, the name and namespace of the source PVC, and the size of the new data volume. This example clones a source PVC in block mode, so `volumeMode: Block` is used: -+ -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: <cloner-datavolume> <1> -spec: - source: - pvc: - namespace: "<source-namespace>" <2> - name: "<my-favorite-vm-disk>" <3> - pvc: - accessModes: - - ReadWriteMany - resources: - requests: - storage: <2Gi> <4> - volumeMode: Block <5> ----- -<1> The name of the new data volume. -<2> The namespace where the source PVC exists. -<3> The name of the source PVC. -<4> The size of the new data volume. You must allocate enough space, or the -cloning operation fails. The size must be the same as or larger than the source PVC. -<5> Specifies that the destination is a block PV. - -. Start cloning the PVC by creating the data volume: -+ -[source,terminal] ----- -$ oc create -f <cloner-datavolume>.yaml ----- -+ -[NOTE] -==== -Data volumes prevent a virtual machine from starting before the PVC is prepared, -so you can create a virtual machine that references the new data volume while the -PVC clones. -==== diff --git a/modules/virt-cloning-local-volume-to-another-node.adoc b/modules/virt-cloning-local-volume-to-another-node.adoc deleted file mode 100644 index dee5e7c91cf7..000000000000 --- a/modules/virt-cloning-local-volume-to-another-node.adoc +++ /dev/null @@ -1,134 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-moving-local-vm-disk-to-different-node.adoc - -[id="virt-cloning-local-volume-to-another-node_{context}"] -= Cloning a local volume to another node - -You can move a virtual machine disk so that it runs on a specific node by cloning the underlying persistent volume claim (PVC). - -To ensure the virtual machine disk is cloned to the correct node, you must either create a new persistent volume (PV) or identify one on the correct node. -Apply a unique label to the PV so that it can be referenced by the data volume. - -[NOTE] -==== -The destination PV must be the same size or larger than the source PVC. -If the destination PV is smaller than the source PVC, the cloning operation fails. -==== - -.Prerequisites - -* The virtual machine must not be running. Power down the virtual machine before cloning the virtual machine disk. - -.Procedure - -. Either create a new local PV on the node, or identify a local PV already on the node: - -* Create a local PV that includes the `nodeAffinity.nodeSelectorTerms` parameters. The following manifest creates a `10Gi` local PV on `node01`. -+ -[source,yaml] ----- -kind: PersistentVolume -apiVersion: v1 -metadata: - name: <destination-pv> <1> - annotations: -spec: - accessModes: - - ReadWriteOnce - capacity: - storage: 10Gi <2> - local: - path: /mnt/local-storage/local/disk1 <3> - nodeAffinity: - required: - nodeSelectorTerms: - - matchExpressions: - - key: kubernetes.io/hostname - operator: In - values: - - node01 <4> - persistentVolumeReclaimPolicy: Delete - storageClassName: local - volumeMode: Filesystem ----- -<1> The name of the PV. -<2> The size of the PV. You must allocate enough space, or the cloning operation fails. The size must be the same as or larger than the source PVC. -<3> The mount path on the node. -<4> The name of the node where you want to create the PV. - -* Identify a PV that already exists on the target node. You can identify the node where a PV is provisioned by viewing the `nodeAffinity` field in its configuration: -+ -[source,terminal] ----- -$ oc get pv <destination-pv> -o yaml ----- -+ -The following snippet shows that the PV is on `node01`: -+ -.Example output -[source,yaml] ----- -... -spec: - nodeAffinity: - required: - nodeSelectorTerms: - - matchExpressions: - - key: kubernetes.io/hostname <1> - operator: In - values: - - node01 <2> -... ----- -<1> The `kubernetes.io/hostname` key uses the node host name to select a node. -<2> The host name of the node. - -. Add a unique label to the PV: -+ -[source,terminal] ----- -$ oc label pv <destination-pv> node=node01 ----- - -. Create a data volume manifest that references the following: - -* The PVC name and namespace of the virtual machine. -* The label you applied to the PV in the previous step. -* The size of the destination PV. -+ -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: <clone-datavolume> <1> -spec: - source: - pvc: - name: "<source-vm-disk>" <2> - namespace: "<source-namespace>" <3> - pvc: - accessModes: - - ReadWriteOnce - selector: - matchLabels: - node: node01 <4> - resources: - requests: - storage: <10Gi> <5> ----- -<1> The name of the new data volume. -<2> The name of the source PVC. If you do not know the PVC name, you can find it in the virtual machine configuration: `spec.volumes.persistentVolumeClaim.claimName`. -<3> The namespace where the source PVC exists. -<4> The label that you applied to the PV in the previous step. -<5> The size of the destination PV. - -. Start the cloning operation by applying the data volume manifest to your cluster: -+ -[source,terminal] ----- -$ oc apply -f <clone-datavolume.yaml> ----- - -The data volume clones the PVC of the virtual machine into the PV on the specific node. diff --git a/modules/virt-cloning-pvc-of-vm-disk-into-new-datavolume.adoc b/modules/virt-cloning-pvc-of-vm-disk-into-new-datavolume.adoc deleted file mode 100644 index 042ac0af3e39..000000000000 --- a/modules/virt-cloning-pvc-of-vm-disk-into-new-datavolume.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc - -// `blockstorage` conditionals are used (declared in the "*-block" assembly) to separate content - -[id="virt-cloning-pvc-of-vm-disk-into-new-datavolume_{context}"] -= Cloning the persistent volume claim of a virtual machine disk into a new data volume - -You can clone a persistent volume claim (PVC) of an existing virtual machine disk -into a new data volume. The new data volume can then be used for a new virtual -machine. - -[NOTE] -==== -When a data volume is created independently of a virtual machine, the lifecycle -of the data volume is independent of the virtual machine. If the virtual machine -is deleted, neither the data volume nor its associated PVC is deleted. -==== - -.Prerequisites - -* Determine the PVC of an existing virtual machine disk to use. You must power -down the virtual machine that is associated with the PVC before you can clone it. -* Install the OpenShift CLI (`oc`). -ifdef::blockstorage[] -* At least one available block persistent volume (PV) that is the same size as or larger than the source PVC. -endif::[] - -.Procedure - -. Examine the virtual machine disk you want to clone to identify the name and -namespace of the associated PVC. - -. Create a YAML file for a data volume that specifies the name of the -new data volume, the name and namespace of the source PVC, -ifdef::blockstorage[] -`volumeMode: Block` so that an available block PV is used, -endif::[] -and the size of the new data volume. -+ -For example: -+ -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: <cloner-datavolume> <1> -spec: - source: - pvc: - namespace: "<source-namespace>" <2> - name: "<my-favorite-vm-disk>" <3> - pvc: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: <2Gi> <4> -ifdef::blockstorage[] - volumeMode: Block <5> -endif::[] ----- -<1> The name of the new data volume. -<2> The namespace where the source PVC exists. -<3> The name of the source PVC. -<4> The size of the new data volume. You must allocate enough space, or the -cloning operation fails. The size must be the same as or larger than the source PVC. -ifdef::blockstorage[] -<5> Specifies that the destination is a block PV -endif::[] - -. Start cloning the PVC by creating the data volume: -+ -[source,terminal] ----- -$ oc create -f <cloner-datavolume>.yaml ----- -+ -[NOTE] -==== -Data volumes prevent a virtual machine from starting before the PVC is prepared, -so you can create a virtual machine that references the new data volume while the -PVC clones. -==== diff --git a/modules/virt-cloud-init-fields-web.adoc b/modules/virt-cloud-init-fields-web.adoc deleted file mode 100644 index 49e4cf1d3f2f..000000000000 --- a/modules/virt-cloud-init-fields-web.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-cloud-init-fields-web_{context}"] -= Cloud-init fields - -|=== -|Name | Description - -|Hostname -|Sets a specific host name for the virtual machine. - -|Authorized SSH Keys -|The user's public key that is copied to *_~/.ssh/authorized_keys_* on the virtual machine. - -|Custom script -|Replaces other options with a field in which you paste a custom cloud-init script. -|=== diff --git a/modules/virt-cluster-resource-requirements.adoc b/modules/virt-cluster-resource-requirements.adoc deleted file mode 100644 index 3cb3ed4a9c23..000000000000 --- a/modules/virt-cluster-resource-requirements.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/preparing-cluster-for-virt.adoc - -[id="virt-cluster-resource-requirements_{context}"] -= Additional hardware requirements for {VirtProductName} - - -{VirtProductName} is an add-on to {product-title} and imposes additional overhead that you must account for when planning a cluster. Each cluster machine must accommodate the following overhead requirements in addition to the {product-title} requirements. Oversubscribing the physical resources in a cluster can affect performance. - -[IMPORTANT] -==== -The numbers noted in this documentation are based on Red Hat’s test methodology and setup. These numbers can vary based on your own individual setup and environments. -==== - -[id="memory-overhead_{context}"] -== Memory overhead - -Calculate the memory overhead values for {VirtProductName} by using the equations below. - -.Cluster memory overhead - ----- -Memory overhead per infrastructure node ≈ 150 MiB ----- - ----- -Memory overhead per worker node ≈ 360 MiB ----- - -Additionally, {VirtProductName} environment resources require a total of 2179 MiB of RAM that is spread across all infrastructure nodes. - - -.Virtual machine memory overhead - ----- -Memory overhead per virtual machine ≈ (1.002 * requested memory) + 146 MiB \ - + 8 * (number of vCPUs) \ <1> - + 16 MiB * (number of graphics devices) <2> ----- - -<1> Number of virtual CPUs requested by the virtual machine -<2> Number of virtual graphics cards requested by the virtual machine - -If your environment includes a Single Root I/O Virtualization (SR-IOV) network device or a Graphics Processing Unit (GPU), allocate 1 GiB additional memory overhead for each device. - - -[id="CPU-overhead_{context}"] -== CPU overhead - -Calculate the cluster processor overhead requirements for {VirtProductName} by using the equation below. The CPU overhead per virtual machine depends on your individual setup. - -.Cluster CPU overhead - ----- -CPU overhead for infrastructure nodes ≈ 4 cores ----- - -{VirtProductName} increases the overall utilization of cluster level services such as logging, routing, and monitoring. To account for this workload, ensure that nodes that host infrastructure components have capacity allocated for 4 additional cores (4000 millicores) distributed across those nodes. - ----- -CPU overhead for worker nodes ≈ 2 cores + CPU overhead per virtual machine ----- - -Each worker node that hosts virtual machines must have capacity for 2 additional cores (2000 millicores) for {VirtProductName} management workloads in addition to the CPUs required for virtual machine workloads. - - -.Virtual machine CPU overhead - -If dedicated CPUs are requested, there is a 1:1 impact on the cluster CPU overhead requirement. Otherwise, there are no specific rules about how many CPUs a virtual machine requires. - - -[id="storage-overhead_{context}"] -== Storage overhead - -Use the guidelines below to estimate storage overhead requirements for your {VirtProductName} environment. - -.Cluster storage overhead - ----- -Aggregated storage overhead per node ≈ 10 GiB ----- - -10 GiB is the estimated on-disk storage impact for each node in the cluster when you install {VirtProductName}. - -.Virtual machine storage overhead - -Storage overhead per virtual machine depends on specific requests for resource allocation within the virtual machine. The request could be for ephemeral storage on the node or storage resources hosted elsewhere in the cluster. {VirtProductName} does not currently allocate any additional ephemeral storage for the running container itself. - - -[id="example-scenario_{context}"] -== Example - -As a cluster administrator, if you plan to host 10 virtual machines in the cluster, each with 1 GiB of RAM and 2 vCPUs, the memory impact across the cluster is 11.68 GiB. The estimated on-disk storage impact for each node in the cluster is 10 GiB and the CPU impact for worker nodes that host virtual machine workloads is a minimum of 2 cores. diff --git a/modules/virt-configuring-configmap-for-obsolete-cpu-models.adoc b/modules/virt-configuring-configmap-for-obsolete-cpu-models.adoc deleted file mode 100644 index 561cdfa9f2c4..000000000000 --- a/modules/virt-configuring-configmap-for-obsolete-cpu-models.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_maintenance/virt-managing-node-labeling-obsolete-cpu-models.adoc - -[id="virt-configuring-configmap-for-obsolete-cpu-models_{context}"] -= Configuring a config map for obsolete CPU models - -Use this procedure to configure a config map for obsolete CPU models. - -.Procedure - -* Create a `ConfigMap` object, specifying the obsolete CPU models in the `obsoleteCPUs` array. For example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: cpu-plugin-configmap <1> -data: <2> - cpu-plugin-configmap: - obsoleteCPUs: <3> - - "486" - - "pentium" - - "pentium2" - - "pentium3" - - "pentiumpro" - minCPU: "Penryn" <4> ----- -<1> Name of the config map. -<2> Configuration data. -<3> List of obsolete CPU models. -<4> Minimum CPU model that is used for basic CPU features. diff --git a/modules/virt-configuring-guest-memory-overcommitment.adoc b/modules/virt-configuring-guest-memory-overcommitment.adoc deleted file mode 100644 index 1fbdc58ce51b..000000000000 --- a/modules/virt-configuring-guest-memory-overcommitment.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-managing-guest-memory.adoc - -[id="virt-configuring-guest-memory-overcommitment_{context}"] -= Configuring guest memory overcommitment - -If your virtual workload requires more memory than available, you can use memory overcommitment to allocate all or most of the host’s memory to your virtual machine instances (VMIs). Enabling memory overcommitment means that you can maximize resources that are normally reserved for the host. - -For example, if the host has 32 GB RAM, you can use memory overcommitment to fit 8 virtual machines (VMs) with 4 GB RAM each. This allocation works under the assumption that the virtual machines will not use all of their memory at the same time. - -[IMPORTANT] -==== -Memory overcommitment increases the potential for virtual machine processes to be killed due to memory pressure (OOM killed). - -The potential for a VM to be OOM killed varies based on your specific configuration, node memory, available swap space, virtual machine memory consumption, the use of kernel same-page merging (KSM), and other factors. -==== - -.Procedure - -. To explicitly tell the virtual machine instance that it has more memory available than was requested from the cluster, edit the virtual machine configuration file and set `spec.domain.memory.guest` to a higher value than `spec.domain.resources.requests.memory`. This process is called memory overcommitment. -+ -In this example, `1024M` is requested from the cluster, but the virtual machine instance is told that it has `2048M` available. As long as there is enough free memory available on the node, the virtual machine instance will consume up to 2048M. -+ - -[source,yaml] ----- -kind: VirtualMachine -spec: - template: - domain: - resources: - requests: - memory: 1024M - memory: - guest: 2048M ----- -+ -[NOTE] -==== -The same eviction rules as those for pods apply to the virtual machine instance if the node is under memory pressure. -==== - -. Create the virtual machine: -+ - -[source,terminal] ----- -$ oc create -f <file_name>.yaml ----- \ No newline at end of file diff --git a/modules/virt-configuring-huge-pages-for-vms.adoc b/modules/virt-configuring-huge-pages-for-vms.adoc deleted file mode 100644 index 201d8d3913ee..000000000000 --- a/modules/virt-configuring-huge-pages-for-vms.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-using-huge-pages-with-vms.adoc - -[id="virt-configuring-huge-pages-for-vms_{context}"] -= Configuring huge pages for virtual machines - -You can configure virtual machines to use pre-allocated huge pages by including the -`memory.hugepages.pageSize` and `resources.requests.memory` parameters in your virtual machine configuration. - -The memory request must be divisible by the page size. For example, you cannot request `500Mi` memory with a page size of `1Gi`. - -[NOTE] -==== -The memory layouts of the host and the guest OS are unrelated. -Huge pages requested in the virtual machine manifest apply to QEMU. -Huge pages inside the guest can only be configured based on the amount of available memory of the virtual machine instance. -==== - -If you edit a running virtual machine, the virtual machine must be rebooted for the changes to take effect. - -.Prerequisites - -* Nodes must have pre-allocated huge pages configured. - -.Procedure - -. In your virtual machine configuration, add the `resources.requests.memory` and -`memory.hugepages.pageSize` parameters to the `spec.domain`. The following configuration snippet is -for a virtual machine that requests a total of `4Gi` memory with a page size of `1Gi`: -+ - -[source,yaml] ----- -kind: VirtualMachine -... -spec: - domain: - resources: - requests: - memory: "4Gi" <1> - memory: - hugepages: - pageSize: "1Gi" <2> -... ----- -<1> The total amount of memory requested for the virtual machine. This value must be divisible by the page size. -<2> The size of each huge page. Valid values for x86_64 architecture are `1Gi` and `2Mi`. The page size must be smaller than the requested memory. - -. Apply the virtual machine configuration: -+ - -[source,terminal] ----- -$ oc apply -f <virtual_machine>.yaml ----- diff --git a/modules/virt-configuring-ip-for-new-vm-cloud-init.adoc b/modules/virt-configuring-ip-for-new-vm-cloud-init.adoc deleted file mode 100644 index fca62d44aee6..000000000000 --- a/modules/virt-configuring-ip-for-new-vm-cloud-init.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-configuring-ip-for-vms.adoc - -[id="virt-configuring-ip-for-new-vm-cloud-init_{context}"] -= Configuring an IP address for a new virtual machine using cloud-init - -You can use cloud-init to configure an IP address when you create a virtual machine. The IP address can be dynamically or statically provisioned. - -.Procedure - -* Create a virtual machine configuration and include the cloud-init network details in the `spec.volumes.cloudInitNoCloud.networkData` field of the virtual machine configuration: - -.. To configure a dynamic IP, specify the interface name and the `dhcp4` boolean: -+ -[source,yaml] ----- -kind: VirtualMachine -spec: -... - volumes: - - cloudInitNoCloud: - networkData: | - version: 2 - ethernets: - eth1: <1> - dhcp4: true <2> ----- -<1> The interface name. -<2> Uses DHCP to provision an IPv4 address. - -.. To configure a static IP, specify the interface name and the IP address: -+ -[source,yaml] ----- -kind: VirtualMachine -spec: -... - volumes: - - cloudInitNoCloud: - networkData: | - version: 2 - ethernets: - eth1: <1> - addresses: - - 10.10.10.14/24 <2> ----- -<1> The interface name. -<2> The static IP address for the virtual machine. diff --git a/modules/virt-configuring-live-migration-limits.adoc b/modules/virt-configuring-live-migration-limits.adoc deleted file mode 100644 index 87adbe5d98a8..000000000000 --- a/modules/virt-configuring-live-migration-limits.adoc +++ /dev/null @@ -1,42 +0,0 @@ - -// Module included in the following assemblies: -// -// * virt/live_migration/virt-live-migration-limits.adoc - -[id="virt-configuring-live-migration-limits_{context}"] -= Configuring live migration limits and timeouts - -Configure live migration limits and timeouts for the cluster by adding updated -key:value fields to the `kubevirt-config` configuration file, which is located in the -`openshift-cnv` namespace. - -.Procedure - -* Edit the `kubevirt-config` configuration file and add the necessary -live migration parameters. The following example shows the default values: -+ - -[source,terminal] ----- -$ oc edit configmap kubevirt-config -n openshift-cnv ----- -+ - -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: kubevirt-config - namespace: kubevirt - labels: - kubevirt.io: "" -data: - feature-gates: "LiveMigration" - migrations: |- - parallelMigrationsPerCluster: "5" - parallelOutboundMigrationsPerNode: "2" - bandwidthPerMigration: "64Mi" - completionTimeoutPerGiB: "800" - progressTimeout: "150" ----- diff --git a/modules/virt-configuring-masquerade-mode-cli.adoc b/modules/virt-configuring-masquerade-mode-cli.adoc deleted file mode 100644 index 9077733d015d..000000000000 --- a/modules/virt-configuring-masquerade-mode-cli.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc - -[id="virt-configuring-masquerade-mode-cli_{context}"] -= Configuring masquerade mode from the command line - -You can use masquerade mode to hide a virtual machine's outgoing traffic behind -the pod IP address. Masquerade mode uses Network Address Translation (NAT) to -connect virtual machines to the pod network backend through a Linux bridge. - -Enable masquerade mode and allow traffic to enter the virtual machine by -editing your virtual machine configuration file. - -.Prerequisites - -* The virtual machine must be configured to use DHCP to acquire IPv4 addresses. -The examples below are configured to use DHCP. - -.Procedure - -. Edit the `interfaces` spec of your virtual machine configuration file: -+ - -[source,yaml] ----- -kind: VirtualMachine -spec: - domain: - devices: - interfaces: - - name: red - masquerade: {} <1> - ports: - - port: 80 <2> - networks: - - name: red - pod: {} ----- -<1> Connect using masquerade mode -<2> Allow incoming traffic on port 80 - -. Create the virtual machine: -+ - -[source,terminal] ----- -$ oc create -f <vm-name>.yaml ----- diff --git a/modules/virt-configuring-selinux-hpp-on-rhcos8.adoc b/modules/virt-configuring-selinux-hpp-on-rhcos8.adoc deleted file mode 100644 index c80fc7039b01..000000000000 --- a/modules/virt-configuring-selinux-hpp-on-rhcos8.adoc +++ /dev/null @@ -1,67 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc - -[id="virt-configuring-selinux-hpp-on-rhcos8_{context}"] -= Configuring SELinux for the hostpath provisioner on Red Hat Enterprise Linux CoreOS 8 - -You must configure SELinux before you create the `HostPathProvisioner` custom -resource. To configure SELinux on Red Hat Enterprise Linux CoreOS 8 workers, you -must create a `MachineConfig` object on each node. - -.Prerequisites - -* Create a backing directory on each node for the persistent volumes (PVs) -that the hostpath provisioner creates. - - -.Procedure - -. Create the `MachineConfig` file. For example: -+ - -[source,terminal] ----- -$ touch machineconfig.yaml ----- - -. Edit the file, ensuring that you include the directory where you want the -hostpath provisioner to create PVs. For example: -+ - -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - name: 50-set-selinux-for-hostpath-provisioner - labels: - machineconfiguration.openshift.io/role: worker -spec: - config: - ignition: - version: 3.1.0 - systemd: - units: - - contents: | - [Unit] - Description=Set SELinux chcon for hostpath provisioner - Before=kubelet.service - - [Service] - ExecStart=/usr/bin/chcon -Rt container_file_t <path/to/backing/directory> <1> - - [Install] - WantedBy=multi-user.target - enabled: true - name: hostpath-provisioner.service ----- -<1> Specify the backing directory where you want the provisioner to create PVs. - -. Create the `MachineConfig` object: -+ - -[source,terminal] ----- -$ oc create -f machineconfig.yaml -n <namespace> ----- diff --git a/modules/virt-configuring-vm-live-migration-cli.adoc b/modules/virt-configuring-vm-live-migration-cli.adoc deleted file mode 100644 index 5c3caee4e585..000000000000 --- a/modules/virt-configuring-vm-live-migration-cli.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc - -[id="virt-configuring-vm-live-migration-cli_{context}"] -= Configuring custom virtual machines with the `LiveMigration` eviction strategy - -You only need to configure the `LiveMigration` eviction strategy on custom -virtual machines. Common templates have this eviction strategy -configured by default. - -.Procedure - -. Add the `evictionStrategy: LiveMigrate` option to the `spec` section in the -virtual machine configuration file. This example uses `oc edit` to update -the relevant snippet of the `VirtualMachine` configuration file: -+ - -[source,terminal] ----- -$ oc edit vm <custom-vm> -n <my-namespace> ----- -+ - -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachine -metadata: - name: custom-vm -spec: - terminationGracePeriodSeconds: 30 - evictionStrategy: LiveMigrate - domain: - resources: - requests: -... ----- - -. Restart the virtual machine for the update to take effect: -+ - -[source,terminal] ----- -$ virtctl restart <custom-vm> -n <my-namespace> ----- diff --git a/modules/virt-confirming-policy-updates-on-nodes.adoc b/modules/virt-confirming-policy-updates-on-nodes.adoc deleted file mode 100644 index 7b010efc6b12..000000000000 --- a/modules/virt-confirming-policy-updates-on-nodes.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-configuring-node-network-policy -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-confirming-policy-updates-on-nodes_{context}"] -= Confirming node network policy updates on nodes - -A `NodeNetworkConfigurationPolicy` manifest describes your requested network configuration for nodes in the cluster. -The node network policy includes your requested network configuration and the status of execution of the policy on the cluster as a whole. - - -When you apply a node network policy, a `NodeNetworkConfigurationEnactment` object is created for every node in the cluster. The node network configuration enactment is a read-only object that represents the status of execution of the policy on that node. -If the policy fails to be applied on the node, the enactment for that node includes a traceback for troubleshooting. - -.Procedure - -. To confirm that a policy has been applied to the cluster, list the policies and their status: -+ -[source,terminal] ----- -$ oc get nncp ----- - -. Optional: If a policy is taking longer than expected to successfully configure, you can inspect the requested state and status conditions of a particular policy: -+ -[source,terminal] ----- -$ oc get nncp <policy> -o yaml ----- - -. Optional: If a policy is taking longer than expected to successfully configure on all nodes, you can list the status of the enactments on the cluster: -+ -[source,terminal] ----- -$ oc get nnce ----- - -. Optional: To view the configuration of a particular enactment, including any error reporting for a failed configuration: -+ -[source,terminal] ----- -$ oc get nnce <node>.<policy> -o yaml ----- diff --git a/modules/virt-connecting-to-the-terminal.adoc b/modules/virt-connecting-to-the-terminal.adoc deleted file mode 100644 index cc3964fc3592..000000000000 --- a/modules/virt-connecting-to-the-terminal.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-connecting-to-the-terminal_{context}"] - -= Connecting to the terminal -You can connect to a virtual machine by using the web console. - -.Procedure - -. Ensure you are in the correct project. If not, click the *Project* -list and select the appropriate project. -. Click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a virtual machine to open the *Virtual Machine Overview* screen. -. In the *Details* tab, click the `virt-launcher-<vm-name>` pod. -. Click the *Terminal* tab. If the terminal is blank, select the -terminal and press any key to initiate connection. diff --git a/modules/virt-connecting-vnc-console.adoc b/modules/virt-connecting-vnc-console.adoc deleted file mode 100644 index e612038b75f9..000000000000 --- a/modules/virt-connecting-vnc-console.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-connecting-vnc-console_{context}"] -= Connecting to the VNC console - -Connect to the VNC console of a running virtual machine from the *Console* tab -in the *Virtual Machine Overview* screen of the web console. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a virtual machine to open the *Virtual Machine Overview* page. -. Click the *Console* tab. The VNC console opens by default. -. Optional: Open the VNC console in a separate window by clicking *Open Console in New Window*. diff --git a/modules/virt-creating-a-service-from-a-virtual-machine.adoc b/modules/virt-creating-a-service-from-a-virtual-machine.adoc deleted file mode 100644 index 204e2f830a3e..000000000000 --- a/modules/virt-creating-a-service-from-a-virtual-machine.adoc +++ /dev/null @@ -1,232 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc - -[id="virt-creating-a-service-from-a-virtual-machine_{context}"] - -= Creating a service from a virtual machine - -Create a service from a running virtual machine by first creating a `Service` object to expose the virtual machine. - -The `ClusterIP` service type exposes the virtual machine internally, within the cluster. The `NodePort` or `LoadBalancer` service types expose the virtual machine externally, outside of the cluster. - -This procedure presents an example of how to create, connect to, and expose a `Service` object of `type: ClusterIP` as a virtual machine-backed service. - -[NOTE] -==== -`ClusterIP` is the default service `type`, if the service `type` is not specified. -==== - -.Procedure - -. Edit the virtual machine YAML as follows: -+ - -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachine -metadata: - name: vm-ephemeral - namespace: example-namespace -spec: - running: false - template: - metadata: - labels: - special: key <1> - spec: - domain: - devices: - disks: - - name: containerdisk - disk: - bus: virtio - - name: cloudinitdisk - disk: - bus: virtio - interfaces: - - masquerade: {} - name: default - resources: - requests: - memory: 1024M - networks: - - name: default - pod: {} - volumes: - - name: containerdisk - containerDisk: - image: kubevirt/fedora-cloud-container-disk-demo - - name: cloudinitdisk - cloudInitNoCloud: - userData: | - #!/bin/bash - echo "fedora" | passwd fedora --stdin ----- -<1> Add the label `special: key` in the `spec.template.metadata.labels` section. -+ - -[NOTE] -==== -Labels on a virtual machine are passed through to the pod. The labels on -the `VirtualMachine` configuration, for example `special: key`, must match the labels in -the `Service` YAML `selector` attribute, which you create later -in this procedure. -==== - -. Save the virtual machine YAML to apply your changes. - -. Edit the `Service` YAML to configure the settings necessary to create and expose the `Service` object: -+ - -[source,yaml] ----- -apiVersion: v1 -kind: Service -metadata: - name: vmservice <1> - namespace: example-namespace <2> -spec: - ports: - - port: 27017 - protocol: TCP - targetPort: 22 <3> - selector: - special: key <4> - type: ClusterIP <5> ----- -<1> Specify the `name` of the service you are creating and exposing. -<2> Specify `namespace` in the `metadata` section of the `Service` YAML that corresponds to the `namespace` you specify in the virtual machine YAML. -<3> Add `targetPort: 22`, exposing the service on SSH port `22`. -<4> In the `spec` section of the `Service` YAML, add `special: key` to the `selector` attribute, which corresponds to the `labels` you added in the virtual machine YAML configuration file. -<5> In the `spec` section of the `Service` YAML, add `type: ClusterIP` for a -ClusterIP service. To create and expose other types of services externally, outside of the cluster, such as `NodePort` and `LoadBalancer`, replace -`type: ClusterIP` with `type: NodePort` or `type: LoadBalancer`, as appropriate. -+ - -. Save the `Service` YAML to store the service configuration. -. Create the `ClusterIP` service: -+ - -[source,terminal] ----- -$ oc create -f <service_name>.yaml ----- - -+ -. Start the virtual machine. If the virtual machine is already running, restart it. -+ - -+ -. Query the `Service` object to verify it is available and is configured with type `ClusterIP`. -+ - -.Verification -* Run the `oc get service` command, specifying the `namespace` that you reference in the virtual machine and `Service` YAML files. -+ - -[source, terminal] ----- -$ oc get service -n example-namespace ----- -+ - -.Example output -[source, terminal] ----- -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -vmservice ClusterIP 172.30.3.149 <none> 27017/TCP 2m ----- -+ - -** As shown from the output, `vmservice` is running. -** The `TYPE` displays as `ClusterIP`, as you specified in the `Service` YAML. - -. Establish a connection to the virtual machine that you want to use to back your service. Connect from an object inside the cluster, such as another virtual machine. -+ - -.. Edit the virtual machine YAML as follows: -+ - -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachine -metadata: - name: vm-connect - namespace: example-namespace -spec: - running: false - template: - spec: - domain: - devices: - disks: - - name: containerdisk - disk: - bus: virtio - - name: cloudinitdisk - disk: - bus: virtio - interfaces: - - masquerade: {} - name: default - resources: - requests: - memory: 1024M - networks: - - name: default - pod: {} - volumes: - - name: containerdisk - containerDisk: - image: kubevirt/fedora-cloud-container-disk-demo - - name: cloudinitdisk - cloudInitNoCloud: - userData: | - #!/bin/bash - echo "fedora" | passwd fedora --stdin ----- -+ - -.. Run the `oc create` command to create a second virtual machine, where `file.yaml` is the name of the virtual machine YAML: -+ - -[source,terminal] ----- -$ oc create -f <file.yaml> ----- -+ - -.. Start the virtual machine. - -.. Connect to the virtual machine by running the following `virtctl` command: -+ - -[source,terminal] ----- -$ virtctl -n example-namespace console <new-vm-name> ----- -+ - -[NOTE] -==== -For service type `LoadBalancer`, use the `vinagre` client to connect your -virtual machine by using the public IP and port. -External ports are dynamically allocated when using service type -`LoadBalancer`. -==== -+ - -.. Run the `ssh` command to authenticate the connection, where `172.30.3.149` is the ClusterIP of the service and `fedora` is the user name of the virtual machine: -+ - -[source,terminal] ----- -$ ssh fedora@172.30.3.149 -p 27017 ----- -+ - -.Verification -* You receive the command prompt of the virtual machine backing the service you want to expose. You now have a service backed by a running virtual machine. diff --git a/modules/virt-creating-a-vm-from-a-template-with-an-attached-boot-source.adoc b/modules/virt-creating-a-vm-from-a-template-with-an-attached-boot-source.adoc deleted file mode 100644 index ca9035244dbb..000000000000 --- a/modules/virt-creating-a-vm-from-a-template-with-an-attached-boot-source.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-creating-and-using-boot-sources.adoc - -[id="virt-creating-a-vm-from-a-template-with-an-attached-boot-source_{context}"] -= Creating a virtual machine from a template with an attached boot source - -After you add a boot source to a template, you can create a new virtual machine from the template. - -.Procedure - -. In the {product-title} web console, click *Workloads > Virtualization* in the side menu. -. From the *Virtual Machines* tab or the *Templates* tab, click *Create* and select *Virtual Machine with Wizard*. -. In the *General* step, select an OS from the Operating System list that has the *(Source available)* label next to the OS and version name. The *(Source available)* label indicates that a boot source is available for this OS. -. Ensure that the *Clone available operating system source* checkbox is selected. -. Click *Review and Confirm*. -. Review your virtual machine settings and edit them, if required. -. Click *Create Virtual Machine* to create your virtual machine. The *Successfully created virtual machine* page is displayed. diff --git a/modules/virt-creating-an-upload-dv.adoc b/modules/virt-creating-an-upload-dv.adoc deleted file mode 100644 index a4eb59f2f00e..000000000000 --- a/modules/virt-creating-an-upload-dv.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc - -[id="virt-creating-an-upload-dv_{context}"] -= Creating an upload data volume - -You can manually create a data volume with an `upload` data source to use for uploading -local disk images. - -.Procedure - -. Create a data volume configuration that specifies `spec: source: upload{}`: -+ - -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: <upload-datavolume> <1> -spec: - source: - upload: {} - pvc: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: <2Gi> <2> ----- -<1> The name of the data volume. -<2> The size of the data volume. Ensure that this value is greater than or equal -to the size of the disk that you upload. - -. Create the data volume by running the following command: -+ - -[source,terminal] ----- -$ oc create -f <upload-datavolume>.yaml ----- diff --git a/modules/virt-creating-blank-disk-datavolumes.adoc b/modules/virt-creating-blank-disk-datavolumes.adoc deleted file mode 100644 index befec4f9858c..000000000000 --- a/modules/virt-creating-blank-disk-datavolumes.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-expanding-virtual-storage-with-blank-disk-images.adoc - -[id="virt-creating-blank-disk-datavolumes_{context}"] -= Creating a blank disk image with data volumes - -You can create a new blank disk image in a persistent volume claim by -customizing and deploying a data volume configuration file. - -.Prerequisites - -* At least one available persistent volume. -* Install the OpenShift CLI (`oc`). - -.Procedure - -. Edit the data volume configuration file: -+ - -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: blank-image-datavolume -spec: - source: - blank: {} - pvc: - # Optional: Set the storage class or omit to accept the default - # storageClassName: "hostpath" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 500Mi ----- - -. Create the blank disk image by running the following command: -+ - -[source,terminal] ----- -$ oc create -f <blank-image-datavolume>.yaml ----- diff --git a/modules/virt-creating-bridge-nad-cli.adoc b/modules/virt-creating-bridge-nad-cli.adoc deleted file mode 100644 index 588e222e51e0..000000000000 --- a/modules/virt-creating-bridge-nad-cli.adoc +++ /dev/null @@ -1,102 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc - -[id="virt-creating-bridge-nad-cli_{context}"] -= Creating a Linux bridge network attachment definition in the CLI - -As a network administrator, you can configure a network attachment definition -of type `cnv-bridge` to provide Layer-2 networking to pods and virtual machines. - -[NOTE] -==== -The network attachment definition must be in the same namespace as the pod or virtual machine. -==== - -.Procedure - -. Create a new file for the network attachment definition in any local directory. -The file must have the following contents, modified to match your -configuration: -+ -[source,yaml] ----- -apiVersion: "k8s.cni.cncf.io/v1" -kind: NetworkAttachmentDefinition -metadata: - name: a-bridge-network - annotations: - k8s.v1.cni.cncf.io/resourceName: bridge.network.kubevirt.io/br0 <1> -spec: - config: '{ - "cniVersion": "0.3.1", - "name": "a-bridge-network", <2> - "plugins": [ - { - "type": "cnv-bridge", <3> - "bridge": "br0", <4> - "vlan": 1 <5> - }, - { - "type": "cnv-tuning" <6> - } - ] - }' ----- -<1> If you add this annotation to your network attachment definition, your virtual machine instances -will only run on nodes that have the `br0` bridge connected. -<2> Required. A name for the configuration. It is recommended to match the configuration name to the `name` value of the network attachment definition. -<3> The actual name of the Container Network Interface (CNI) plug-in that provides -the network for this network attachment definition. Do not change this field unless -you want to use a different CNI. -<4> You must substitute the actual name of the bridge, if it is not `br0`. -<5> Optional: The VLAN tag. -<6> Required. This allows the MAC pool manager to assign a unique MAC address to the connection. - -+ -[source,terminal] ----- -$ oc create -f <resource_spec.yaml> ----- - -. Edit the configuration file of a virtual machine or virtual machine instance that you want to connect to the bridge network, for example: -+ -[source,yaml] ----- -apiVersion: v1 -kind: VirtualMachine -metadata: - name: example-vm -spec: - domain: - devices: - interfaces: - - masquerade: {} - name: default - - bridge: {} - name: bridge-net <1> - ... - - networks: - - name: default - pod: {} - - name: bridge-net <1> - multus: - networkName: a-bridge-network <2> -... ----- -<1> The `name` value for the bridge interface and network must be the same. -<2> You must substitute the actual `name` value from the network attachment definition. -+ -[NOTE] -==== -The virtual machine instance will be connected to both the `default` pod network and `bridge-net`, which is -defined by a network attachment definition named `a-bridge-network`. -==== - -. Apply the configuration file to the resource: -+ -[source,terminal] ----- -$ oc create -f <local/path/to/network-attachment-definition.yaml> ----- diff --git a/modules/virt-creating-bridge-nad-web.adoc b/modules/virt-creating-bridge-nad-web.adoc deleted file mode 100644 index 213805b6703d..000000000000 --- a/modules/virt-creating-bridge-nad-web.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc - -//This file contains UI elements and/or package names that need to be updated. - -[id="virt-creating-bridge-nad-web_{context}"] -= Creating a Linux bridge network attachment definition in the web console - -The network attachment definition is a custom resource that exposes layer-2 devices -to a specific namespace in your {VirtProductName} cluster. - -Network administrators can create network attachment definitions -to provide existing layer-2 networking to pods and virtual machines. - -.Procedure - -. In the web console, click *Networking* -> *Network Attachment Definitions*. -. Click *Create Network Attachment Definition* . -. Enter a unique *Name* and optional *Description*. -. Click the *Network Type* list and select *CNV Linux bridge*. -. Enter the name of the bridge in the *Bridge Name* field. -. Optional: If the resource has VLAN IDs configured, enter the ID numbers in the *VLAN Tag Number* field. -. Click *Create*. diff --git a/modules/virt-creating-configmap.adoc b/modules/virt-creating-configmap.adoc deleted file mode 100644 index ca6d28432cbf..000000000000 --- a/modules/virt-creating-configmap.adoc +++ /dev/null @@ -1,178 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc - -[id="virt-creating-configmap_{context}"] -= Creating a config map for importing a VM - -You can create a config map to map the Red Hat Virtualization (RHV) virtual machine operating system to an {VirtProductName} template if you want to override the default `vm-import-controller` mapping or to add additional mappings. - -The default `vm-import-controller` config map contains the following RHV operating systems and their corresponding common {VirtProductName} templates. - -[cols="1,1", options="header"] -.Operating system and template mapping -|=== -|RHV VM operating system |{VirtProductName} template -|`rhel_6_9_plus_ppc64` |`rhel6.9` -|`rhel_6_ppc64` |`rhel6.9` -|`rhel_6` |`rhel6.9` -|`rhel_6x64` |`rhel6.9` -|`rhel_7_ppc64` |`rhel7.7` -|`rhel_7_s390x` |`rhel7.7` -|`rhel_7x64` |`rhel7.7` -|`rhel_8x64` |`rhel8.1` -|`sles_11_ppc64` |`opensuse15.0` -|`sles_11` |`opensuse15.0` -|`sles_12_s390x` |`opensuse15.0` -|`ubuntu_12_04` |`ubuntu18.04` -|`ubuntu_12_10` |`ubuntu18.04` -|`ubuntu_13_04` |`ubuntu18.04` -|`ubuntu_13_10` |`ubuntu18.04` -|`ubuntu_14_04_ppc64` |`ubuntu18.04` -|`ubuntu_14_04` |`ubuntu18.04` -|`ubuntu_16_04_s390x` |`ubuntu18.04` -|`windows_10` |`win10` -|`windows_10x64` |`win10` -|`windows_2003` |`win10` -|`windows_2003x64` |`win10` -|`windows_2008R2x64` |`win2k8` -|`windows_2008` |`win2k8` -|`windows_2008x64` |`win2k8` -|`windows_2012R2x64` |`win2k12r2` -|`windows_2012x64` |`win2k12r2` -|`windows_2016x64` |`win2k16` -|`windows_2019x64` |`win2k19` -|`windows_7` |`win10` -|`windows_7x64` |`win10` -|`windows_8` |`win10` -|`windows_8x64` |`win10` -|`windows_xp` |`win10` -|=== - -.Procedure - -. In a web browser, identify the REST API name of the RHV VM operating system by navigating to `\http://<RHV_Manager_FQDN>/ovirt-engine/api/vms/<VM_ID>`. The operating system name appears in the `<os>` section of the XML output, as shown in the following example: -+ -[source,xml] ----- -... -<os> -... -<type>rhel_8x64</type> -</os> ----- - -. View a list of the available {VirtProductName} templates: -+ -[source,terminal] ----- -$ oc get templates -n openshift --show-labels | tr ',' '\n' | grep os.template.kubevirt.io | sed -r 's#os.template.kubevirt.io/(.*)=.*#\1#g' | sort -u ----- -+ -.Example output -[source,terminal] ----- -fedora31 -fedora32 -... -rhel8.1 -rhel8.2 -... ----- - -. If an {VirtProductName} template that matches the RHV VM operating system does not appear in the list of available templates, create a template with the {VirtProductName} web console. - -. Create a config map to map the RHV VM operating system to the {VirtProductName} template: -+ -[source,yaml] ----- -$ cat <<EOF | oc create -f - -apiVersion: v1 -kind: ConfigMap -metadata: - name: os-configmap - namespace: default <1> -data: - guestos2common: | - "Red Hat Enterprise Linux Server": "rhel" - "CentOS Linux": "centos" - "Fedora": "fedora" - "Ubuntu": "ubuntu" - "openSUSE": "opensuse" - osinfo2common: | - "<rhv-operating-system>": "<vm-template>" <2> -EOF ----- -<1> Optional: You can change the value of the `namespace` parameter. -<2> Specify the REST API name of the RHV operating system and its corresponding VM template as shown in the following example. -+ -.Config map example -[source,yaml] ----- -$ cat <<EOF | oc apply -f - -apiVersion: v1 -kind: ConfigMap -metadata: - name: os-configmap - namespace: default -data: - osinfo2common: | - "other_linux": "fedora31" -EOF ----- - -. Verify that the custom config map was created: -+ -[source,terminal] ----- -$ oc get cm -n default os-configmap -o yaml ----- - -ifeval::["{VirtVersion}" < "2.5"] -. Edit the `kubevirt-hyperconverged-operator.v{HCOVersion}.yaml` file: -+ -[source,terminal,subs="attributes+"] ----- -$ oc edit clusterserviceversion -n openshift-cnv kubevirt-hyperconverged-operator.v{HCOVersion} ----- - -. Update the following parameters of the `vm-import-operator` deployment manifest: -+ -[source,yaml] ----- -... -spec: - containers: - - env: - ... - - name: OS_CONFIGMAP_NAME - value: os-configmap <1> - - name: OS_CONFIGMAP_NAMESPACE - value: default <2> ----- -<1> Add `value: os-configmap` to the `name: OS_CONFIGMAP_NAME` parameter. -<2> Optional: You can add this value if you changed the namespace in the config map. - -. Save the `kubevirt-hyperconverged-operator.v{HCOVersion}.yaml` file. -+ -Updating the `vm-import-operator` deployment updates the `vm-import-controller` config map. -endif::[] -ifeval::["{VirtVersion}" >= "2.5"] -. Patch the `vm-import-controller-config` config map to apply the new config map: -+ -[source,terminal] ----- -$ oc patch configmap vm-import-controller-config -n openshift-cnv --patch '{ - "data": { - "osConfigMap.name": "os-configmap", - "osConfigMap.namespace": "default" <1> - } -}' ----- -<1> Update the namespace if you changed it in the config map. -endif::[] - -. Verify that the template appears in the {VirtProductName} web console: - -.. Click *Workloads* -> *Virtualization* from the side menu. -.. Click the *Virtual Machine Templates* tab and find the template in the list. diff --git a/modules/virt-creating-interface-on-nodes.adoc b/modules/virt-creating-interface-on-nodes.adoc deleted file mode 100644 index 52bfb507804b..000000000000 --- a/modules/virt-creating-interface-on-nodes.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-creating-interface-on-nodes_{context}"] -= Creating an interface on nodes - -Create an interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest to the cluster. The manifest details the requested configuration for the interface. - -By default, the manifest applies to all nodes in the cluster. To add the interface to specific nodes, add the `spec: nodeSelector` parameter and the appropriate `<key>:<value>` for your node selector. - -.Procedure - -. Create the `NodeNetworkConfigurationPolicy` manifest. The following example configures a Linux bridge on all worker nodes: -+ -[source,yaml] ----- -apiVersion: nmstate.io/v1beta1 -kind: NodeNetworkConfigurationPolicy -metadata: - name: <br1-eth1-policy> <1> -spec: - nodeSelector: <2> - node-role.kubernetes.io/worker: "" <3> - desiredState: - interfaces: - - name: br1 - description: Linux bridge with eth1 as a port <4> - type: linux-bridge - state: up - ipv4: - dhcp: true - enabled: true - bridge: - options: - stp: - enabled: false - port: - - name: eth1 ----- -<1> Name of the policy. -<2> Optional: If you do not include the `nodeSelector` parameter, the policy applies to all nodes in the cluster. -<3> This example uses the `node-role.kubernetes.io/worker: ""` node selector to select all worker nodes in the cluster. -<4> Optional: Human-readable description for the interface. - -. Create the node network policy: -+ -[source,terminal] ----- -$ oc apply -f <br1-eth1-policy.yaml> <1> ----- -<1> File name of the node network configuration policy manifest. diff --git a/modules/virt-creating-local-block-pv.adoc b/modules/virt-creating-local-block-pv.adoc deleted file mode 100644 index 93f8b92f35f8..000000000000 --- a/modules/virt-creating-local-block-pv.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc - -[id="virt-creating-local-block-pv_{context}"] -= Creating a local block persistent volume - -Create a local block persistent volume (PV) on a node by populating a file and -mounting it as a loop device. You can then reference this loop device in a -PV manifest as a `Block` volume and use it as a block device for a -virtual machine image. - -.Procedure - -. Log in as `root` to the node on which to create the local PV. This procedure -uses `node01` for its examples. - -. Create a file and populate it with null characters so that it can be used as a block device. -The following example creates a file `loop10` with a size of 2Gb (20 100Mb blocks): -+ -[source,terminal] ----- -$ dd if=/dev/zero of=<loop10> bs=100M count=20 ----- - -. Mount the `loop10` file as a loop device. -+ -[source,terminal] ----- -$ losetup </dev/loop10>d3 <loop10> <1> <2> ----- -<1> File path where the loop device is mounted. -<2> The file created in the previous step to be mounted as the loop device. - -. Create a `PersistentVolume` manifest that references the mounted loop device. -+ -[source,yaml] ----- -kind: PersistentVolume -apiVersion: v1 -metadata: - name: <local-block-pv10> - annotations: -spec: - local: - path: </dev/loop10> <1> - capacity: - storage: <2Gi> - volumeMode: Block <2> - storageClassName: local <3> - accessModes: - - ReadWriteOnce - persistentVolumeReclaimPolicy: Delete - nodeAffinity: - required: - nodeSelectorTerms: - - matchExpressions: - - key: kubernetes.io/hostname - operator: In - values: - - <node01> <4> ----- -<1> The path of the loop device on the node. -<2> Specifies it is a block PV. -<3> Optional: Set a storage class for the PV. If you omit it, the cluster default is used. -<4> The node on which the block device was mounted. - -. Create the block PV. -+ -[source,terminal] ----- -# oc create -f <local-block-pv10.yaml><1> ----- -<1> The file name of the persistent volume created in the previous step. diff --git a/modules/virt-creating-new-vm-from-cloned-pvc-using-datavolumetemplate.adoc b/modules/virt-creating-new-vm-from-cloned-pvc-using-datavolumetemplate.adoc deleted file mode 100644 index 1d468e3f7ca6..000000000000 --- a/modules/virt-creating-new-vm-from-cloned-pvc-using-datavolumetemplate.adoc +++ /dev/null @@ -1,90 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-using-datavolumetemplate.adoc - -[id="virt-creating-new-vm-from-cloned-pvc-using-datavolumetemplate_{context}"] -= Creating a new virtual machine from a cloned persistent volume claim by using a data volume template - -You can create a virtual machine that clones the persistent volume claim (PVC) of -an existing virtual machine into a data volume. Reference a -`dataVolumeTemplate` in the virtual machine manifest and the `source` PVC is cloned to -a data volume, which is then automatically used for the creation of the virtual -machine. - -[NOTE] -==== -When a data volume is created as part of the data volume template of a virtual -machine, the lifecycle of the data volume is then dependent on the virtual -machine. If the virtual machine is deleted, the data volume and associated -PVC are also deleted. -==== - -.Prerequisites - -* Determine the PVC of an existing virtual machine disk to use. You must power -down the virtual machine that is associated with the PVC before you can clone it. -* Install the OpenShift CLI (`oc`). - -.Procedure - -. Examine the virtual machine you want to clone to identify the name and -namespace of the associated PVC. - -. Create a YAML file for a `VirtualMachine` object. The following virtual -machine example clones `my-favorite-vm-disk`, which is located in the -`source-namespace` namespace. The `2Gi` data volume called `favorite-clone` -is created from `my-favorite-vm-disk`. -+ -For example: -+ -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachine -metadata: - labels: - kubevirt.io/vm: vm-dv-clone - name: vm-dv-clone <1> -spec: - running: false - template: - metadata: - labels: - kubevirt.io/vm: vm-dv-clone - spec: - domain: - devices: - disks: - - disk: - bus: virtio - name: root-disk - resources: - requests: - memory: 64M - volumes: - - dataVolume: - name: favorite-clone - name: root-disk - dataVolumeTemplates: - - metadata: - name: favorite-clone - spec: - pvc: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 2Gi - source: - pvc: - namespace: "source-namespace" - name: "my-favorite-vm-disk" ----- -<1> The virtual machine to create. - -. Create the virtual machine with the PVC-cloned data volume: -+ -[source,terminal] ----- -$ oc create -f <vm-clone-datavolumetemplate>.yaml ----- diff --git a/modules/virt-creating-offline-vm-snapshot-cli.adoc b/modules/virt-creating-offline-vm-snapshot-cli.adoc deleted file mode 100644 index 3eb487f6f95a..000000000000 --- a/modules/virt-creating-offline-vm-snapshot-cli.adoc +++ /dev/null @@ -1,99 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc - -[id="virt-creating-offline-vm-snapshot-cli_{context}"] -= Creating an offline virtual machine snapshot in the CLI - -You can create a virtual machine (VM) snapshot for an offline VM by creating a `VirtualMachineSnapshot` object. - -.Prerequisites - -* Ensure that the persistent volume claims (PVCs) are in a storage class that supports Container Storage Interface (CSI) volume snapshots. -* Install the OpenShift CLI (`oc`). -* Power down the VM for which you want to create a snapshot. - -.Procedure - -. Create a YAML file to define a `VirtualMachineSnapshot` object that specifies the name of the new `VirtualMachineSnapshot` and the name of the source VM. -+ -For example: -+ -[source,yaml] - ----- -apiVersion: snapshot.kubevirt.io/v1alpha1 -kind: VirtualMachineSnapshot -metadata: - name: my-vmsnapshot <1> -spec: - source: - apiGroup: kubevirt.io - kind: VirtualMachine - name: my-vm <2> ----- -<1> The name of the new `VirtualMachineSnapshot` object. -<2> The name of the source VM. - -. Create the `VirtualMachineSnapshot` resource. The snapshot controller creates a `VirtualMachineSnapshotContent` object, binds it to the `VirtualMachineSnapshot` and updates the `status` and `readyToUse` fields -of the `VirtualMachineSnapshot` object. -+ -[source,terminal] ----- -$ oc create -f <my-vmsnapshot>.yaml ----- - -.Verification - -. Verify that the `VirtualMachineSnapshot` object is created and bound with `VirtualMachineSnapshotContent`. The `readyToUse` flag must be set to `true`. -+ -[source,terminal] ----- -$ oc describe vmsnapshot <my-vmsnapshot> ----- -+ -.Example output - -[source, yaml] - ----- -apiVersion: snapshot.kubevirt.io/v1alpha1 -kind: VirtualMachineSnapshot -metadata: -creationTimestamp: "2020-09-30T14:41:51Z" -finalizers: -- snapshot.kubevirt.io/vmsnapshot-protection -generation: 5 -name: mysnap -namespace: default -resourceVersion: "3897" -selfLink: /apis/snapshot.kubevirt.io/v1alpha1/namespaces/default/virtualmachinesnapshots/my-vmsnapshot -uid: 28eedf08-5d6a-42c1-969c-2eda58e2a78d -spec: -source: -apiGroup: kubevirt.io -kind: VirtualMachine -name: my-vm -status: -conditions: - - lastProbeTime: null - lastTransitionTime: "2020-09-30T14:42:03Z" - reason: Operation complete - status: "False" <1> - type: Progressing - - lastProbeTime: null - lastTransitionTime: "2020-09-30T14:42:03Z" - reason: Operation complete - status: "True" <2> - type: Ready -creationTime: "2020-09-30T14:42:03Z" -readyToUse: true <3> -sourceUID: 355897f3-73a0-4ec4-83d3-3c2df9486f4f -virtualMachineSnapshotContentName: vmsnapshot-content-28eedf08-5d6a-42c1-969c-2eda58e2a78d <4> ----- -<1> The `status` field of the `Progressing` condition specifies if the snapshot is still being created. -<2> The `status` field of the `Ready` condition specifies if the snapshot creation process is complete. -<3> Specifies if the snapshot is ready to be used. -<4> Specifies that the snapshot is bound to a `VirtualMachineSnapshotContent` object created by the snapshot controller. - -. Check the `spec:volumeBackups` property of the `VirtualMachineSnapshotContent` resource to verify that the expected PVCs are included in the snapshot. diff --git a/modules/virt-creating-offline-vm-snapshot-web.adoc b/modules/virt-creating-offline-vm-snapshot-web.adoc deleted file mode 100644 index 95cb0f76dcd0..000000000000 --- a/modules/virt-creating-offline-vm-snapshot-web.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc - -[id="virt-creating-offline-vm-snapshot-web_{context}"] -= Creating an offline virtual machine snapshot in the web console - -You can create a virtual machine (VM) snapshot by using the web console. - -[NOTE] -==== -The VM snapshot only includes disks that meet the following requirements: - -* Must be either a data volume or persistent volume claim -* Belong to a storage class that supports Container Storage Interface (CSI) volume snapshots - -If your VM storage includes disks that do not support snapshots, you can either edit them or contact your cluster administrator. -==== - -.Procedure - -. Click *Workloads* → *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine to open the *Virtual Machine Overview* screen. - -. If the virtual machine is running, click *Actions* → *Stop Virtual Machine* to power it down. - -. Click the *Snapshots* tab and then click *Take Snapshot*. - -. Fill in the *Snapshot Name* and optional *Description* fields. - -. Expand *Disks included in this Snapshot* to see the storage volumes to be included in the snapshot. - -. If your VM has disks that cannot be included in the snapshot and you still wish to proceed, select the *I am aware of this warning and wish to proceed* checkbox. - -. Click *Save*. diff --git a/modules/virt-creating-rbac-cloning-dvs.adoc b/modules/virt-creating-rbac-cloning-dvs.adoc deleted file mode 100644 index 351523519778..000000000000 --- a/modules/virt-creating-rbac-cloning-dvs.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc - -[id="virt-creating-rbac-cloning-dvs_{context}"] -= Creating RBAC resources for cloning data volumes - -Create a new cluster role that enables permissions for all actions for the `datavolumes` resource. - -.Procedure - -. Create a `ClusterRole` manifest: -+ -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: <datavolume-cloner> <1> -rules: -- apiGroups: ["cdi.kubevirt.io"] - resources: ["datavolumes/source"] - verbs: ["*"] ----- -<1> Unique name for the cluster role. - -. Create the cluster role in the cluster: -+ -[source,terminal] ----- -$ oc create -f <datavolume-cloner.yaml> <1> ----- -<1> The file name of the `ClusterRole` manifest created in the previous step. - -. Create a `RoleBinding` manifest that applies to both the source and destination namespaces and references -the cluster role created in the previous step. -+ -[source,yaml] ----- -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: <allow-clone-to-user> <1> - namespace: <Source namespace> <2> -subjects: -- kind: ServiceAccount - name: default - namespace: <Destination namespace> <3> -roleRef: - kind: ClusterRole - name: datavolume-cloner <4> - apiGroup: rbac.authorization.k8s.io ----- -<1> Unique name for the role binding. -<2> The namespace for the source data volume. -<3> The namespace to which the data volume is cloned. -<4> The name of the cluster role created in the previous step. - -. Create the role binding in the cluster: -+ -[source,terminal] ----- -$ oc create -f <datavolume-cloner.yaml> <1> ----- -<1> The file name of the `RoleBinding` manifest created in the previous step. diff --git a/modules/virt-creating-storage-class.adoc b/modules/virt-creating-storage-class.adoc deleted file mode 100644 index ae1396aafe66..000000000000 --- a/modules/virt-creating-storage-class.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc - -[id="virt-creating-storage-class_{context}"] -= Creating a storage class - -When you create a storage class, you set parameters that affect the -dynamic provisioning of persistent volumes (PVs) that belong to that storage class. + -[NOTE] -==== -You cannot update a `StorageClass` object's parameters after you create it. -==== - -.Procedure - -. Create a YAML file for defining the storage class. For example: -+ -[source,terminal] ----- -$ touch storageclass.yaml ----- - -. Edit the file. For example: -+ -[source,yaml] ----- -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: hostpath-provisioner <1> -provisioner: kubevirt.io/hostpath-provisioner -reclaimPolicy: Delete <2> -volumeBindingMode: WaitForFirstConsumer <3> ----- -<1> You can optionally rename the storage class by changing this value. -<2> The two possible `reclaimPolicy` values are `Delete` and `Retain`. If you -do not specify a value, the storage class defaults to `Delete`. -<3> The `volumeBindingMode` value determines when dynamic provisioning and volume -binding occur. Specify `WaitForFirstConsumer` to delay the binding and provisioning -of a PV until after a pod that uses the persistent volume claim (PVC) -is created. This ensures that the PV meets the pod's scheduling requirements. - -[NOTE] -==== -Virtual machines use data volumes that are based on local PVs. Local PVs are bound to specific nodes. While the disk image is prepared for consumption by the virtual machine, it is possible that the virtual machine cannot be scheduled to the node where the local storage PV was previously pinned. - -To solve this problem, use the Kubernetes pod scheduler to bind the PVC to a PV on the correct node. By using `StorageClass` with `volumeBindingMode` set to `WaitForFirstConsumer`, the binding and provisioning of the PV is delayed until a `Pod` is created using the PVC. -==== - -. Create the `StorageClass` object: -+ -[source,terminal] ----- -$ oc create -f storageclass.yaml ----- - -.Additional information - -* link:https://kubernetes.io/docs/concepts/storage/storage-classes/[Storage Classes] diff --git a/modules/virt-creating-template-wizard-web.adoc b/modules/virt-creating-template-wizard-web.adoc deleted file mode 100644 index eeb3dbe6de45..000000000000 --- a/modules/virt-creating-template-wizard-web.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-creating-template-wizard-web_{context}"] -= Creating a virtual machine template with the wizard in the web console - -The web console features the *Create Virtual Machine Template* wizard that guides you through the *General*, *Networking*, *Storage*, *Advanced*, and *Review* steps to simplify the process of creating virtual machine templates. All required fields are marked with a ++*++. The *Create Virtual Machine Template* wizard prevents you from moving to the next step until you provide values in the required fields. - -[NOTE] -==== -The wizard guides you to create a custom virtual machine template where you specify the operating system, boot source, flavor, and other settings. -==== - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Templates* tab. - -. Click *Create* and select *Template with Wizard*. - -. Fill in all required fields in the *General* step. - -. Click *Next* to progress to the *Networking* step. A NIC that is named `nic0` is attached by default. - -.. Optional: Click *Add Network Interface* to create additional NICs. - -.. Optional: You can remove any or all NICs by clicking the Options menu {kebab} and selecting *Delete*. Virtual machines created from a template do not need a NIC attached. NICs can be created after a virtual machine has been created. - -. Click *Next* to progress to the *Storage* step. - -. Click *Add Disk* to add a disk, and complete your selections for the fields in the *Add Disk* screen. -+ -[NOTE] -==== -If *Import via URL (creates PVC)*, *Import via Registry (creates PVC)*, or *Container (ephemeral)* is selected as *Source*, a `rootdisk` disk is created and attached to the virtual machine as the *Bootable Disk*. - -A *Bootable Disk* is not required for virtual machines provisioned from a *PXE* source if there are no disks attached to the virtual machine. If one or more disks are attached to the virtual machine, you must select one as the *Bootable Disk*. - -Blank disks, PVC disks without a valid boot source, and the cloudinitdisk cannot be used as a boot source. -==== - -. Optional: Click *Advanced* to configure Cloud-init. - -. Click *Review* to review and confirm your settings. - -. Click *Create Virtual Machine template*. - -. Click *See virtual machine template details* to view details about the virtual machine template. - -The template is also listed in the *Templates* tab. diff --git a/modules/virt-creating-vddk-image.adoc b/modules/virt-creating-vddk-image.adoc deleted file mode 100644 index 84e2a6684aef..000000000000 --- a/modules/virt-creating-vddk-image.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc - -[id="virt-creating-vddk-image_{context}"] -= Creating and using a VDDK image - -You can download the VMware Virtual Disk Development Kit (VDDK), build a VDDK image, and push the VDDK image to your image registry. You then add the VDDK image to the `v2v-vmware` config map. - -.Prerequisites - -* You must have access to an {product-title} internal image registry or a secure external registry. - -.Procedure - -. Create and navigate to a temporary directory: -+ -[source,terminal] ----- -$ mkdir /tmp/<dir_name> && cd /tmp/<dir_name> ----- - -. In a browser, navigate to link:https://code.vmware.com/home[VMware code] and click *SDKs*. -. Under *Compute Virtualization*, click *Virtual Disk Development Kit (VDDK)*. -. Select the VDDK version that corresponds to your VMware vSphere version, for example, VDDK 7.0 for vSphere 7.0, click *Download*, and then save the VDDK archive in the temporary directory. - -. Extract the VDDK archive: -+ -[source,terminal] ----- -$ tar -xzf VMware-vix-disklib-<version>.x86_64.tar.gz ----- - -. Create a `Dockerfile`: -+ -[source,terminal] ----- -$ cat > Dockerfile <<EOF -FROM busybox:latest -COPY vmware-vix-disklib-distrib /vmware-vix-disklib-distrib -RUN mkdir -p /opt -ENTRYPOINT ["cp", "-r", "/vmware-vix-disklib-distrib", "/opt"] -EOF ----- - -. Build the image: -+ -[source,terminal] ----- -$ podman build . -t <registry_route_or_server_path>/vddk:<tag> <1> ----- -<1> Specify your image registry: -+ -* For an internal {product-title} registry, use the internal registry route, for example, `image-registry.openshift-image-registry.svc:5000/openshift/vddk:<tag>`. -* For an external registry, specify the server name, path, and tag, for example, `server.example.com:5000/vddk:<tag>`. - -. Push the image to the registry: -+ -[source,terminal] ----- -$ podman push <registry_route_or_server_path>/vddk:<tag> ----- - -. Ensure that the image is accessible to your {VirtProductName} environment. -. Edit the `v2v-vmware` config map in the *openshift-cnv* project: -+ -[source,terminal] ----- -$ oc edit configmap v2v-vmware -n openshift-cnv ----- - -. Add the `vddk-init-image` parameter to the `data` stanza: -+ -[source,yaml] ----- -... -data: - vddk-init-image: <registry_route_or_server_path>/vddk:<tag> ----- diff --git a/modules/virt-creating-vm-quick-start-web.adoc b/modules/virt-creating-vm-quick-start-web.adoc deleted file mode 100644 index d305372e838c..000000000000 --- a/modules/virt-creating-vm-quick-start-web.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc - -[id="virt-creating-vm-quick-start-web_{context}"] -= Using a Quick Start to create a virtual machine - -The web console provides Quick Starts with instructional guided tours for creating virtual machines. You can access the Quick Starts catalog by selecting the Help menu in the *Administrator* perspective to view the Quick Starts catalog. When you click on a Quick Start tile and begin the tour, the system guides you through the process. - -Tasks in a Quick Start begin with selecting a Red Hat template. Then, you can add a boot source and import the operating system image. Finally, you can save the custom template and use it to create a virtual machine. - -Quick Start tours for creating virtual machines include the following: - -* Creating a Red Hat Enterprise Linux virtual machine -* Creating a Windows 10 virtual machine -* Importing a VMWare virtual machine - -.Prerequisites -* Access to the website where you can download the URL link for the operating system image. - -.Procedure - -. In the web console, select *Quick Starts* from the Help menu. - -. Click on a tile in the Quick Starts catalog. For example: *Creating a Red Hat Linux Enterprise Linux virtual machine*. - -. Follow the instructions in the guided tour and complete the tasks for importing an operating system image and creating a virtual machine. The *Virtual Machines* tab displays the virtual machine. diff --git a/modules/virt-creating-vm-wizard-web.adoc b/modules/virt-creating-vm-wizard-web.adoc deleted file mode 100644 index 4eab20413a4e..000000000000 --- a/modules/virt-creating-vm-wizard-web.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc - -[id="virt-creating-vm-wizard-web_{context}"] -= Running the virtual machine wizard to create a virtual machine - -The web console features a wizard that guides you through the process of selecting a virtual machine template and creating a virtual machine. Red Hat virtual machine templates are preconfigured with an operating system image, default settings for the operating system, flavor (CPU and memory), and workload type (server). When templates are configured with a boot source, they are labeled with a customized label text or the default label text *Available boot source*. These templates are then ready to be used for creating virtual machines. - -You can select a template from the list of preconfigured templates, review the settings, and create a virtual machine in the *Create virtual machine from template* wizard. If you choose to customize your virtual machine, the wizard guides you through the *General*, *Networking*, *Storage*, *Advanced*, and *Review* steps. All required fields displayed by the wizard are marked by a ++*++. - -Create Network interface cards (NICs) and storage disks later and attach them to virtual machines. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. From the *Virtual Machines* tab or the *Templates* tab, click *Create* and select *Virtual Machine with Wizard*. - -. Select a template that is configured with a boot source. - -. Click *Next* to go to the *Review and create* step. - -. Clear the *Start this virtual machine after creation* checkbox if you do not want to start the virtual machine now. - -. Click *Create virtual machine* and exit the wizard or continue with the wizard to customize the virtual machine. - -. Click *Customize virtual machine* to go to the *General* step. - -.. Optional: Edit the *Name* field to specify a custom name for the virtual machine. - -.. Optional: In the *Description* field, add a description. - -. Click *Next* to go to the *Networking* step. A `nic0` NIC is attached by default. - -.. Optional: Click *Add Network Interface* to create additional NICs. - -.. Optional: You can remove any or all NICs by clicking the Options menu {kebab} and selecting *Delete*. A virtual machine does not need a NIC attached to be created. You can create NICs after the virtual machine has been created. - -. Click *Next* to go to the *Storage* step. - -.. Optional: Click *Add Disk* to create additional disks. These disks can be removed by clicking the Options menu {kebab} and selecting *Delete*. - -.. Optional: Click the Options menu {kebab} to edit the disk and save your changes. - -. Click *Next* to go to the *Advanced* step and review the details for *Cloud-init*. - -. Click *Next* to go to the *Review* step and review the settings for the virtual machine. - -. Click *Create Virtual Machine*. - -. Click *See virtual machine details* to view the *Overview* for this virtual machine. -+ -The virtual machine is listed in the *Virtual Machines* tab. diff --git a/modules/virt-creating-vm-yaml-web.adoc b/modules/virt-creating-vm-yaml-web.adoc deleted file mode 100644 index 178ca5c13a9e..000000000000 --- a/modules/virt-creating-vm-yaml-web.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc - -[id="virt-creating-vm-yaml-web_{context}"] -= Pasting in a pre-configured YAML file to create a virtual machine - -Create a virtual machine by writing or pasting a YAML configuration file. A valid `example` virtual machine configuration is provided by default whenever you open the YAML edit screen. - -If your YAML configuration is invalid when you click *Create*, an error message indicates the parameter in which the error occurs. Only one error is shown at a time. - -[NOTE] -==== -Navigating away from the YAML screen while editing cancels any changes to the configuration you have made. -==== - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Click *Create* and select *Virtual Machine With YAML*. -. Write or paste your virtual machine configuration in the editable window. -.. Alternatively, use the `example` virtual machine provided by default in the YAML screen. -. Optional: Click *Download* to download the YAML configuration file in its present state. -. Click *Create* to create the virtual machine. - -The virtual machine is listed in the *Virtual Machines* tab. diff --git a/modules/virt-creating-vm.adoc b/modules/virt-creating-vm.adoc deleted file mode 100644 index 9d6a36e53d5a..000000000000 --- a/modules/virt-creating-vm.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc - -[id="virt-creating-vm_{context}"] -= Using the CLI to create a virtual machine - -.Procedure - -The `spec` object of the virtual machine configuration file references -the virtual machine settings, such as the number of cores and the amount -of memory, the disk type, and the volumes to use. - -. Attach the virtual machine disk to the virtual machine by referencing -the relevant PVC `claimName` as a volume. - -. To create a virtual machine with the {product-title} client, run this command: -+ -[source,terminal] ----- -$ oc create -f <vm.yaml> ----- - -. Since virtual machines are created in a *Stopped* state, run a virtual machine -instance by starting it. - -[NOTE] -==== -A https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/[ReplicaSet]’s purpose is often used to guarantee the availability of a specified number of identical pods. -ReplicaSet is not currently supported in {VirtProductName}. -==== - - - -[caption=] -.Domain settings -|=== -|Setting | Description - -|Cores -|The number of cores inside the virtual machine. Must be a value greater than or equal to 1. - -|Memory -|The amount of RAM that is allocated to the virtual machine by the node. Specify a value in *M* for Megabyte or *Gi* for Gigabyte. - -|Disks -|The name of the volume that is referenced. Must match the name of a volume. -|=== - -[caption=] -.Volume settings -|=== -|Setting | Description - -|Name -|The name of the volume, which must be a DNS label and unique within the virtual machine. - -|PersistentVolumeClaim -|The PVC to attach to the virtual machine. The `claimName` of the PVC must be in the same project as the virtual machine. -|=== diff --git a/modules/virt-define-http-liveness-probe.adoc b/modules/virt-define-http-liveness-probe.adoc deleted file mode 100644 index bb82cf4ca6a7..000000000000 --- a/modules/virt-define-http-liveness-probe.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-monitoring-vm-health.adoc - -[id="virt-define-http-liveness-probe_{context}"] - -= Define an HTTP liveness probe - -This procedure provides an example configuration file for defining HTTP -liveness probes. - -.Procedure - -. Customize a YAML configuration file to create an HTTP liveness probe, using -the following code block as an example. In this example: -* You configure a probe using `spec.livenessProbe.httpGet`, which queries port `1500` of the virtual machine instance, after an initial delay of `120` seconds. -* The virtual machine instance installs and runs a minimal HTTP server -on port `1500` using `cloud-init`. -+ -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachineInstance -metadata: - labels: - special: vmi-fedora - name: vmi-fedora -spec: - domain: - devices: - disks: - - disk: - bus: virtio - name: containerdisk - - disk: - bus: virtio - name: cloudinitdisk - resources: - requests: - memory: 1024M - livenessProbe: - initialDelaySeconds: 120 - periodSeconds: 20 - httpGet: - port: 1500 - timeoutSeconds: 10 - terminationGracePeriodSeconds: 0 - volumes: - - name: containerdisk - registryDisk: - image: kubevirt/fedora-cloud-registry-disk-demo - - cloudInitNoCloud: - userData: |- - #cloud-config - password: fedora - chpasswd: { expire: False } - bootcmd: - - setenforce 0 - - dnf install -y nmap-ncat - - systemd-run --unit=httpserver nc -klp 1500 -e '/usr/bin/echo -e HTTP/1.1 200 OK\\n\\nHello World!' - name: cloudinitdisk ----- -+ -. Create the virtual machine instance by running the following command: -+ -[source,terminal] ----- -$ oc create -f <file name>.yaml ----- diff --git a/modules/virt-define-readiness-probe.adoc b/modules/virt-define-readiness-probe.adoc deleted file mode 100644 index 1d32cbb4ca56..000000000000 --- a/modules/virt-define-readiness-probe.adoc +++ /dev/null @@ -1,75 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-monitoring-vm-health.adoc - -[id="virt-define-readiness-probe_{context}"] - -= Define a readiness probe - -This procedure provides an example configuration file for defining -readiness probes. - -.Procedure - -. Customize a YAML configuration file to create a readiness probe. Readiness -probes are configured in a similar manner to liveness probes. However, note the -following differences in this example: -* Readiness probes are saved using a different spec name. For example, you -create a readiness probe as `spec.readinessProbe` instead of as -`spec.livenessProbe.<type-of-probe>`. -* When creating a readiness probe, you optionally set a `failureThreshold` and a -`successThreshold` to switch between `ready` and `non-ready` states, should the probe -succeed or fail multiple times. -+ -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachineInstance -metadata: - labels: - special: vmi-fedora - name: vmi-fedora -spec: - domain: - devices: - disks: - - disk: - bus: virtio - name: containerdisk - - disk: - bus: virtio - name: cloudinitdisk - resources: - requests: - memory: 1024M - readinessProbe: - httpGet: - port: 1500 - initialDelaySeconds: 120 - periodSeconds: 20 - timeoutSeconds: 10 - failureThreshold: 3 - successThreshold: 3 - terminationGracePeriodSeconds: 0 - volumes: - - name: containerdisk - registryDisk: - image: kubevirt/fedora-cloud-registry-disk-demo - - cloudInitNoCloud: - userData: |- - #cloud-config - password: fedora - chpasswd: { expire: False } - bootcmd: - - setenforce 0 - - dnf install -y nmap-ncat - - systemd-run --unit=httpserver nc -klp 1500 -e '/usr/bin/echo -e HTTP/1.1 200 OK\\n\\nHello World!' - name: cloudinitdisk ----- -+ -. Create the virtual machine instance by running the following command: -+ -[source,terminal] ----- -$ oc create -f <file name>.yaml ----- diff --git a/modules/virt-define-tcp-liveness-probe.adoc b/modules/virt-define-tcp-liveness-probe.adoc deleted file mode 100644 index fd848d78688a..000000000000 --- a/modules/virt-define-tcp-liveness-probe.adoc +++ /dev/null @@ -1,69 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-monitoring-vm-health.adoc - -[id="virt-define-tcp-liveness-probe_{context}"] - -= Define a TCP liveness probe - -This procedure provides an example configuration file for defining -TCP liveness probes. - -.Procedure - -. Customize a YAML configuration file to create an TCP liveness probe, using -this code block as an example. In this example: -* You configure a probe using `spec.livenessProbe.tcpSocket`, which queries port `1500` of the virtual machine instance, after an initial delay of `120` seconds. -* The virtual machine instance installs and runs a minimal HTTP server -on port `1500` using `cloud-init`. -+ -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachineInstance -metadata: - labels: - special: vmi-fedora - name: vmi-fedora -spec: - domain: - devices: - disks: - - disk: - bus: virtio - name: containerdisk - - disk: - bus: virtio - name: cloudinitdisk - resources: - requests: - memory: 1024M - livenessProbe: - initialDelaySeconds: 120 - periodSeconds: 20 - tcpSocket: - port: 1500 - timeoutSeconds: 10 - terminationGracePeriodSeconds: 0 - volumes: - - name: containerdisk - registryDisk: - image: kubevirt/fedora-cloud-registry-disk-demo - - cloudInitNoCloud: - userData: |- - #cloud-config - password: fedora - chpasswd: { expire: False } - bootcmd: - - setenforce 0 - - dnf install -y nmap-ncat - - systemd-run --unit=httpserver nc -klp 1500 -e '/usr/bin/echo -e HTTP/1.1 200 OK\\n\\nHello World!' - name: cloudinitdisk ----- -+ -. Create the virtual machine instance by running the following command: -+ -[source,terminal] ----- -$ oc create -f <file name>.yaml ----- diff --git a/modules/virt-defining-storageclass-in-cdi.adoc b/modules/virt-defining-storageclass-in-cdi.adoc deleted file mode 100644 index 29923ab0cc70..000000000000 --- a/modules/virt-defining-storageclass-in-cdi.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc - -[id="virt-defining-storageclass-in-cdi_{context}"] -= Defining a storage class in the CDI object - -Dynamically provision scratch space for CDI operations by defining a storage class in the `CDI` object. - - -.Prerequisites - -* Install the OpenShift client (`oc`). - -.Procedure - -. Use the `oc` client to edit the `CDI` object: -+ -[source,terminal] ----- -$ oc edit cdi ----- - -. Edit the `spec.config.scratchSpaceStorageClass` field to match a storage class in the cluster. -+ -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: CDI -... -spec: - config: - scratchSpaceStorageClass: "<storage_class>" <1> -... ----- -<1> Replace `<storage_class>` with the storage class that you want to use to provision scratch space for CDI operations in your cluster. - -. Save and exit your default editor to update the `CDI` object. diff --git a/modules/virt-delete-vm-web.adoc b/modules/virt-delete-vm-web.adoc deleted file mode 100644 index 5523fd666d7a..000000000000 --- a/modules/virt-delete-vm-web.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-delete-vms.adoc - -[id="virt-delete-vm-web_{context}"] - -= Deleting a virtual machine using the web console - -Deleting a virtual machine permanently removes it from the cluster. + -[NOTE] -==== -When you delete a virtual machine, the data volume it uses is automatically deleted. -==== - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Click the Options menu {kebab} of the virtual machine that you want to delete and select *Delete Virtual Machine*. - -** Alternatively, click the virtual machine name to open the *Virtual Machine Overview* screen and click *Actions* -> *Delete Virtual Machine*. - -. In the confirmation pop-up window, click *Delete* to permanently delete the virtual machine. diff --git a/modules/virt-deleting-catalog-subscription.adoc b/modules/virt-deleting-catalog-subscription.adoc deleted file mode 100644 index 251021a7bfbf..000000000000 --- a/modules/virt-deleting-catalog-subscription.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/uninstalling-virt.adoc - -[id="virt-deleting-catalog-subscription_{context}"] -= Deleting the {VirtProductName} catalog subscription - -To finish uninstalling {VirtProductName}, delete the -*{VirtProductName}* catalog subscription. - -.Prerequisites - -* An active subscription to the *{VirtProductName}* catalog - -.Procedure - -. Navigate to the *Operators* -> *OperatorHub* page. - -. Search for *{VirtProductName}* and then select it. - -. Click *Uninstall*. diff --git a/modules/virt-deleting-deployment-custom-resource.adoc b/modules/virt-deleting-deployment-custom-resource.adoc deleted file mode 100644 index cefb387ce710..000000000000 --- a/modules/virt-deleting-deployment-custom-resource.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/uninstalling-virt-web.adoc - -//This file contains UI elements and/or package names that need to be updated. - -[id="virt-deleting-deployment-custom-resource_{context}"] -= Deleting the {VirtProductName} Operator Deployment custom resource - -To uninstall {VirtProductName}, you must first delete the *{VirtProductName} Operator Deployment* custom resource. - -.Prerequisites - -* Create the *{VirtProductName} Operator Deployment* custom resource. - -.Procedure - -. From the {product-title} web console, select `openshift-cnv` from the *Projects* list. - -. Navigate to the *Operators* -> *Installed Operators* page. - -. Click *{VirtProductName}*. - -. Click the *{VirtProductName} Operator Deployment* tab. - -. Click the Options menu {kebab} in the row containing the *kubevirt-hyperconverged* custom resource. In the expanded menu, click *Delete HyperConverged Cluster*. - -. Click *Delete* in the confirmation window. - -. Navigate to the *Workloads* -> *Pods* page to verify that only the Operator pods are running. - -. Open a terminal window and clean up the remaining resources by running the following command: -+ -[source,terminal] ----- -$ oc delete apiservices v1alpha3.subresources.kubevirt.io -n openshift-cnv ----- diff --git a/modules/virt-deleting-dvs.adoc b/modules/virt-deleting-dvs.adoc deleted file mode 100644 index b6597425ba4c..000000000000 --- a/modules/virt-deleting-dvs.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-deleting-datavolumes.adoc - -[id="virt-deleting-dvs_{context}"] - -= Deleting a data volume - -You can delete a data volume by using the `oc` command-line interface (CLI). - -.Prerequisites - -* Identify the name of the data volume that you want to delete. - -.Procedure - -* Delete the data volume by running the following command: -+ -[source,terminal] ----- -$ oc delete dv <datavolume_name> ----- -+ -[NOTE] -==== -This command only deletes objects that exist in the current project. Specify the -`-n <project_name>` option if the object you want to delete is in -a different project or namespace. -==== diff --git a/modules/virt-deleting-template-web.adoc b/modules/virt-deleting-template-web.adoc deleted file mode 100644 index 05c52586b4c5..000000000000 --- a/modules/virt-deleting-template-web.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/vm_templates/virt-deleting-vm-template.adoc - -[id="virt-deleting-template-wizard-web_{context}"] -= Deleting a virtual machine template in the web console - -Deleting a virtual machine template permanently removes it from the cluster. - -[NOTE] -==== -You can delete virtual machine templates that were created by using a Red Hat template or the *Create Virtual Machine Template* wizard. Preconfigured virtual machine templates that are provided by Red Hat cannot be deleted. -==== - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Templates* tab. Select the appropriate method to delete a virtual machine template: - -** Click the Options menu {kebab} of the template to delete and select *Delete Template*. - -** Click the template name to open the *Virtual Machine Template Details* screen and click *Actions* -> *Delete Template*. - -. In the confirmation pop-up window, click *Delete* to permanently delete the template. diff --git a/modules/virt-deleting-virt-cli.adoc b/modules/virt-deleting-virt-cli.adoc deleted file mode 100644 index 45a996db503f..000000000000 --- a/modules/virt-deleting-virt-cli.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/uninstalling-virt.adoc - -[id="virt-deleting-virt-cli_{context}"] -= Deleting {VirtProductName} - -You can delete {VirtProductName} by using the CLI. - -.Prerequisites - -- Install the OpenShift CLI (`oc`). - -- Access to a {VirtProductName} cluster using an account with -`cluster-admin` permissions. - -[NOTE] -==== -When you delete the subscription of the {VirtProductName} operator in the OLM by using the CLI, the `ClusterServiceVersion` (CSV) object is not deleted from the cluster. To completely uninstall {VirtProductName}, you must explicitly delete the CSV. -==== - -.Procedure - -. Delete the `HyperConverged` custom resource: -+ -[source,terminal] ----- -$ oc delete HyperConverged kubevirt-hyperconverged -n openshift-cnv ----- - -. Delete the subscription of the {VirtProductName} operator in the Operator Lifecycle Manager (OLM): -+ -[source,terminal] ----- -$ oc delete subscription kubevirt-hyperconverged -n openshift-cnv ----- - -. Set the cluster service version (CSV) name for {VirtProductName} as an environment variable: -+ -[source,terminal] ----- -$ CSV_NAME=$(oc get csv -n openshift-cnv -o=custom-columns=:metadata.name) ----- -. Delete the CSV from the {VirtProductName} cluster by specifying the CSV name from the previous step: -+ -[source,terminal] ----- -$ oc delete csv ${CSV_NAME} -n openshift-cnv ----- -+ -{VirtProductName} is uninstalled when a confirmation message indicates that the CSV was deleted successfully: -+ -.Example output -[source,terminal,subs="attributes+"] ----- -clusterserviceversion.operators.coreos.com "kubevirt-hyperconverged-operator.v{HCOVersion}" deleted ----- diff --git a/modules/virt-deleting-vm-snapshot-cli.adoc b/modules/virt-deleting-vm-snapshot-cli.adoc deleted file mode 100644 index 531c5c8aa24f..000000000000 --- a/modules/virt-deleting-vm-snapshot-cli.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc - -[id="virt-deleting-vm-snapshot-cli_{context}"] -= Deleting a virtual machine snapshot in the CLI - -You can delete an existing virtual machine (VM) snapshot by deleting the appropriate `VirtualMachineSnapshot` object. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). - -.Procedure - -* Delete the `VirtualMachineSnapshot` object. The snapshot controller deletes the `VirtualMachineSnapshot` along with the associated `VirtualMachineSnapshotContent` object. -+ -[source,terminal] ----- -$ oc delete vmsnapshot <my-vmsnapshot> ----- - -.Verification - -* Verify that the snapshot is deleted and no longer attached to this VM: -+ -[source,terminal] ----- -$ oc get vmsnapshot ----- diff --git a/modules/virt-deleting-vm-snapshot-web.adoc b/modules/virt-deleting-vm-snapshot-web.adoc deleted file mode 100644 index 5b2465bd50b5..000000000000 --- a/modules/virt-deleting-vm-snapshot-web.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc - -[id="virt-deleting-vm-snapshot-web_{context}"] -= Deleting a virtual machine snapshot in the web console - -You can delete an existing virtual machine snapshot by using the web console. - -.Procedure - -. Click *Workloads* → *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine to open the *Virtual Machine Overview* screen. - -. Click the *Snapshots* tab. The page displays a list of snapshots associated with the virtual machine. - -. Choose one of the following methods to delete a virtual machine snapshot: - -.. Click the Options menu {kebab} of the virtual machine snapshot that you want to delete and select *Delete Virtual Machine Snapshot*. - -.. Select a snapshot to open the *Snapshot Details* screen and click *Actions* → *Delete Virtual Machine Snapshot*. - -. In the confirmation pop-up window, click *Delete* to delete the snapshot. diff --git a/modules/virt-deleting-vmis-cli.adoc b/modules/virt-deleting-vmis-cli.adoc deleted file mode 100644 index f42a758c2ebe..000000000000 --- a/modules/virt-deleting-vmis-cli.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-deleting-vmis-cli.adoc - -[id="virt-deleting-vmis-cli_{context}"] - -= Deleting a standalone virtual machine instance using the CLI - -You can delete a standalone virtual machine instance (VMI) by using the `oc` command-line interface (CLI). - -.Prerequisites - -* Identify the name of the VMI that you want to delete. - -.Procedure - -* Delete the VMI by running the following command: -+ -[source,terminal] ----- -$ oc delete vmi <vmi_name> ----- \ No newline at end of file diff --git a/modules/virt-deleting-vmis-web.adoc b/modules/virt-deleting-vmis-web.adoc deleted file mode 100644 index 09bdcb4960d4..000000000000 --- a/modules/virt-deleting-vmis-web.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-manage-vmis.adoc - -[id="virt-deleting-vmis-web_{context}"] -= Deleting a standalone virtual machine instance using the web console - -Delete a standalone virtual machine instance (VMI) from the web console. - -.Procedure - -. In the {product-title} web console, click *Workloads* -> *Virtualization* from the side menu. - -. Click the &#8942; button of the standalone virtual machine instance (VMI) that you want to delete and select *Delete Virtual Machine Instance*. - -** Alternatively, click the name of the standalone VMI. The *Virtual Machine Instance Overview* page displays. - -. Select *Actions* -> *Delete Virtual Machine Instance*. - -. In the confirmation pop-up window, click *Delete* to permanently delete the standalone VMI. diff --git a/modules/virt-deleting-vms.adoc b/modules/virt-deleting-vms.adoc deleted file mode 100644 index 25e31abaaa1c..000000000000 --- a/modules/virt-deleting-vms.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-delete-vms.adoc - -[id="virt-deleting-vms_{context}"] - -= Deleting a virtual machine by using the CLI - -You can delete a virtual machine by using the `oc` command line interface (CLI). -The `oc` client enables you to perform actions on multiple virtual machines. + -[NOTE] -==== -When you delete a virtual machine, the data volume it uses is automatically deleted. -==== - -.Prerequisites - -* Identify the name of the virtual machine that you want to delete. - -.Procedure - -* Delete the virtual machine by running the following command: -+ -[source,terminal] ----- -$ oc delete vm <vm_name> ----- -+ -[NOTE] -==== -This command only deletes objects that exist in the current project. Specify the -`-n <project_name>` option if the object you want to delete is in -a different project or namespace. -==== diff --git a/modules/virt-deploying-operator-cli.adoc b/modules/virt-deploying-operator-cli.adoc deleted file mode 100644 index 3bce3e0b52f6..000000000000 --- a/modules/virt-deploying-operator-cli.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/installing-virt-cli.adoc - -[id="virt-deploying-operator-cli_{context}"] -= Deploying the {VirtProductName} Operator by using the CLI - -You can deploy the {VirtProductName} Operator by using the `oc` CLI. - -.Prerequisites - -* An active subscription to the {VirtProductName} catalog in the `openshift-cnv` namespace. - -.Procedure - -. Create a YAML file that contains the following manifest: -+ -[source,yaml] ----- -apiVersion: hco.kubevirt.io/v1beta1 -kind: HyperConverged -metadata: - name: kubevirt-hyperconverged - namespace: openshift-cnv -spec: ----- - -. Deploy the {VirtProductName} Operator by running the following command: -+ -[source,terminal] ----- -$ oc apply -f <file_name>.yaml ----- - -.Verification - -* Ensure that {VirtProductName} deployed successfully by watching the `PHASE` of the cluster service version (CSV) in the `openshift-cnv` namespace. Run the following command: -+ -[source,terminal] ----- -$ watch oc get csv -n openshift-cnv ----- -+ -The following output displays if deployment was successful: -+ -.Example output -[source,terminal,subs="attributes+"] ----- -NAME DISPLAY VERSION REPLACES PHASE -kubevirt-hyperconverged-operator.v{HCOVersion} {VirtProductName} {HCOVersion} Succeeded ----- diff --git a/modules/virt-disabling-guest-memory-overhead-accounting.adoc b/modules/virt-disabling-guest-memory-overhead-accounting.adoc deleted file mode 100644 index 99566c7830ed..000000000000 --- a/modules/virt-disabling-guest-memory-overhead-accounting.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-managing-guest-memory.adoc - -[id="virt-disabling-guest-memory-overhead-accounting_{context}"] -= Disabling guest memory overhead accounting - -A small amount of memory is requested by each virtual machine instance in addition to the amount that you request. This additional memory is used for the infrastructure that wraps each `VirtualMachineInstance` process. - -Though it is not usually advisable, it is possible to increase the virtual machine instance density on the node by disabling guest memory overhead accounting. - -[IMPORTANT] -==== -Disabling guest memory overhead accounting increases the potential for virtual machine processes to be killed due to memory pressure (OOM killed). - -The potential for a VM to be OOM killed varies based on your specific configuration, node memory, available swap space, virtual machine memory consumption, the use of kernel same-page merging (KSM), and other factors. -==== - -.Procedure - -. To disable guest memory overhead accounting, edit the YAML configuration file and set the `overcommitGuestOverhead` value to `true`. This parameter is disabled by default. -+ -[source,yaml] ----- -kind: VirtualMachine -spec: - template: - domain: - resources: - overcommitGuestOverhead: true - requests: - memory: 1024M ----- -+ -[NOTE] -==== -If `overcommitGuestOverhead` is enabled, it adds the guest overhead to memory limits, if present. -==== - -. Create the virtual machine: -+ -[source,terminal] ----- -$ oc create -f <file_name>.yaml ----- diff --git a/modules/virt-disabling-mac-address-pool-for-namespace-cli.adoc b/modules/virt-disabling-mac-address-pool-for-namespace-cli.adoc deleted file mode 100644 index 63e7b40c7319..000000000000 --- a/modules/virt-disabling-mac-address-pool-for-namespace-cli.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc - -[id="virt-disabling-mac-address-pool-for-namespace-cli_{context}"] -= Disabling a MAC address pool for a namespace in the CLI - -Disable a MAC address pool for virtual machines in a namespace by removing the `mutatevirtualmachines.kubemacpool.io` label. - -.Procedure - -* Remove the KubeMacPool label from the namespace. -The following example removes the KubeMacPool label from two namespaces, `<namespace1>` and `<namespace2>`: -+ -[source,terminal] ----- -$ oc label namespace <namespace1> <namespace2> mutatevirtualmachines.kubemacpool.io- ----- - diff --git a/modules/virt-disabling-tls-for-registry.adoc b/modules/virt-disabling-tls-for-registry.adoc deleted file mode 100644 index d1e8bef1e602..000000000000 --- a/modules/virt-disabling-tls-for-registry.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc - -[id="virt-disabling-tls-for-registry_{context}"] -= Disabling TLS for a container registry to use as insecure registry - -You can disable TLS (transport layer security) for a container registry by adding the registry to the `cdi-insecure-registries` config map. - -.Prerequisites - -* Log in to the cluster as a user with the `cluster-admin` role. - -.Procedure - -* Add the registry to the `cdi-insecure-registries` config map in the `cdi` namespace. -+ -[source,terminal] ----- -$ oc patch configmap cdi-insecure-registries -n cdi \ - --type merge -p '{"data":{"mykey": "<insecure-registry-host>:5000"}}' <1> ----- -<1> Replace `<insecure-registry-host>` with the registry hostname. diff --git a/modules/virt-document-attributes.adoc b/modules/virt-document-attributes.adoc deleted file mode 100644 index 9cd6da96f768..000000000000 --- a/modules/virt-document-attributes.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Standard document attributes to be used in the documentation -// -// The following are shared by all documents: -:toc: -:toc-title: -:toclevels: 4 -:experimental: -// -// Product content attributes, that is, substitution variables in the files. -// -:product-title: OpenShift Container Platform -:VirtProductName: OpenShift Virtualization -:ProductRelease: -:ProductVersion: -:VirtVersion: 2.6 -:KubeVirtVersion: v0.36.2 -:HCOVersion: 2.6.0 -// :LastHCOVersion: -:product-build: -:DownloadURL: registry.access.redhat.com -:kebab: image:kebab.png[title="Options menu"] -:delete: image:delete.png[title="Delete"] -// -// Book Names: -// Defining the book names in document attributes instead of hard-coding them in -// the master.adoc files and in link references. This makes it easy to change the -// book name if necessary. -// Using the pattern ending in 'BookName' makes it easy to grep for occurrences -// throughout the topics -// -:Install_BookName: Installing OpenShift Virtualization -:Using_BookName: Using OpenShift Virtualization -:RN_BookName: OpenShift Virtualization release notes diff --git a/modules/virt-edit-boot-order-web.adoc b/modules/virt-edit-boot-order-web.adoc deleted file mode 100644 index aedb7eb6eb2e..000000000000 --- a/modules/virt-edit-boot-order-web.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virt_users_guide/virt-edit-boot-order.adoc - -[id="virt-edit-boot-order-web_{context}"] -= Editing a boot order list in the web console - -Edit the boot order list in the web console. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine to open the *Virtual Machine Overview* screen. - -. Click the *Details* tab. - -. Click the pencil icon that is located on the right side of *Boot Order*. - -. Choose the appropriate method to move the item in the boot order list: - -* If you do not use a screen reader, hover over the arrow icon next to the item that you want to move, drag the item up or down, and drop it in a location of your choice. - -* If you use a screen reader, press the Up Arrow key or Down Arrow key to move the item in the boot order list. Then, press the *Tab* key to drop the item in a location of your choice. - -. Click *Save*. - -[NOTE] -==== -If the virtual machine is running, changes to the boot order list will not take effect until you restart the virtual machine. - -You can view pending changes by clicking *View Pending Changes* on the right side of the *Boot Order* field. The *Pending Changes* banner -at the top of the page displays a list of all changes that will be applied when the virtual machine restarts. -==== diff --git a/modules/virt-edit-boot-order-yaml-web.adoc b/modules/virt-edit-boot-order-yaml-web.adoc deleted file mode 100644 index 0fbe57ae7aa4..000000000000 --- a/modules/virt-edit-boot-order-yaml-web.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virt_users_guide/virt-edit-boot-order.adoc -// - -[id="virt-edit-boot-order-yaml-web_{context}"] -= Editing a boot order list in the YAML configuration file - -Edit the boot order list in a YAML configuration file by using the CLI. - -.Procedure - -. Open the YAML configuration file for the virtual machine by running the following command: -+ -[source,terminal] ----- -$ oc edit vm example ----- - -. Edit the YAML file and modify the values for the boot order associated with a disk or network interface card (NIC). For example: - -+ -[source,yaml] ----- -disks: - - bootOrder: 1 <1> - disk: - bus: virtio - name: containerdisk - - disk: - bus: virtio - name: cloudinitdisk - - cdrom: - bus: virtio - name: cd-drive-1 -interfaces: - - boot Order: 2 <2> - macAddress: '02:96:c4:00:00' - masquerade: {} - name: default ----- -<1> The boot order value specified for the disk. -<2> The boot order value specified for the network interface card. - -. Save the YAML file. - - -. Click *reload the content* to apply the updated boot order values from the YAML file to the boot order list in the web console. diff --git a/modules/virt-edit-cdrom-vm.adoc b/modules/virt-edit-cdrom-vm.adoc deleted file mode 100644 index 21c167d99b4e..000000000000 --- a/modules/virt-edit-cdrom-vm.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-edit-vms.adoc -// * virt/vm_templates/virt-editing-vm-template.adoc - -// Establishing conditionals so content can be re-used for editing VMs -// and VM templates. - -ifeval::["{context}" == "virt-edit-vms"] -:object: virtual machine -:object-gui: Virtual Machines -:object-overview: Virtual Machine Overview -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:object: virtual machine template -:object-gui: Templates -:object-overview: VM Template Details -endif::[] - -[id="virt-vm-edit-cdrom_{context}"] - -= Editing CD-ROMs for {object-gui} -Use the following procedure to edit CD-ROMs for {object}s. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *{object-gui}* tab. - -. Select a {object} to open the *{object-overview}* screen. - -. Click the *Disks* tab. - -. Click the Options menu {kebab} for the CD-ROM that you want to edit and select *Edit*. - -. In the *Edit CD-ROM* window, edit the fields: *Source*, *Persistent Volume Claim*, *Name*, *Type*, and *Interface*. - -. Click *Save*. - -// Scrubbing all conditionals used in module - -ifeval::["{context}" == "virt-edit-vms"] -:object!: -:object-gui!: -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:object!: -:object-gui!: -endif::[] diff --git a/modules/virt-editing-cdi-cpu-and-memory-defaults.adoc b/modules/virt-editing-cdi-cpu-and-memory-defaults.adoc deleted file mode 100644 index 6f3fffca451f..000000000000 --- a/modules/virt-editing-cdi-cpu-and-memory-defaults.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-configuring-cdi-for-namespace-resourcequota.adoc - -[id="virt-editing-cdi-cpu-and-memory-defaults_{context}"] -= Editing the CDI object to override CPU and memory defaults - -Modify the default settings for CPU and memory requests and limits for your -use case by editing the `spec.config.podResourceRequirements` fields of the `CDI` object. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). - -.Procedure - -. Edit the `CDI` object by running the following command: -+ -[source,terminal] ----- -$ oc edit cdi ----- - -. Change the default CPU and memory requests and limits by editing the `spec.config.podResourceRequirements` fields of the `CDI` object: -+ -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: CDI -... -spec: - config: - podResourceRequirements: - limits: - cpu: "4" - memory: "1Gi" - requests: - cpu: "1" - memory: "250Mi" -... ----- - -. Save and exit the editor to update the `CDI` object. - -.Verification - -* View the `status` field of the `CDI` object to verify your changes: -+ -[source,terminal] ----- -$ oc get cdi -o yaml ----- diff --git a/modules/virt-editing-kubevirtstorageclassdefaults-cli.adoc b/modules/virt-editing-kubevirtstorageclassdefaults-cli.adoc deleted file mode 100644 index 3d6387186d2a..000000000000 --- a/modules/virt-editing-kubevirtstorageclassdefaults-cli.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc - -[id="virt-editing-kubevirtstorageclassdefaults-cli_{context}"] -= Editing the `kubevirt-storage-class-defaults` config map in the CLI - -Modify the storage settings for data volumes by editing the `kubevirt-storage-class-defaults` config map in the `openshift-cnv` namespace. -You can also add settings for other storage classes to create data volumes in the web console for different storage types. - -[NOTE] -==== -You must configure storage settings that are supported by the underlying storage. -==== - -.Procedure - -. Edit the config map by running the following command: -+ -[source,terminal] ----- -$ oc edit configmap kubevirt-storage-class-defaults -n openshift-cnv ----- - -. Update the `data` values of the config map: -+ -[source,yaml] ----- -... -data: - accessMode: ReadWriteOnce <1> - volumeMode: Filesystem <2> - <new>.accessMode: ReadWriteMany <3> - <new>.volumeMode: Block <4> ----- -<1> The default accessMode is `ReadWriteOnce`. -<2> The default volumeMode is `Filesystem`. -<3> If you add an access mode for a storage class, replace the `<new>` part of the parameter with the storage class name. -<4> If you add a volume mode for a storage class, replace the `<new>` part of the parameter with the storage class name. - -. Save and exit the editor to update the config map. - diff --git a/modules/virt-editing-kubevirtstorageclassdefaults-web.adoc b/modules/virt-editing-kubevirtstorageclassdefaults-web.adoc deleted file mode 100644 index b0a4bc39b0ba..000000000000 --- a/modules/virt-editing-kubevirtstorageclassdefaults-web.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc - -[id="virt-editing-kubevirtstorageclassdefaults-web_{context}"] -= Editing the `kubevirt-storage-class-defaults` config map in the web console - -Modify the storage settings for data volumes by editing the `kubevirt-storage-class-defaults` config map in the `openshift-cnv` namespace. -You can also add settings for other storage classes to create data volumes in the web console for different storage types. - -[NOTE] -==== -You must configure storage settings that are supported by the underlying storage. -==== - -.Procedure - -. Click *Workloads* -> *Config Maps* from the side menu. -. In the *Project* list, select *openshift-cnv*. -. Click *kubevirt-storage-class-defaults* to open the *Config Map Overview*. -. Click the *YAML* tab to display the editable configuration. -. Update the `data` values with the storage configuration that is appropriate for your underlying storage: -+ -[source,yaml] ----- -... -data: - accessMode: ReadWriteOnce <1> - volumeMode: Filesystem <2> - <new>.accessMode: ReadWriteMany <3> - <new>.volumeMode: Block <4> ----- -<1> The default accessMode is `ReadWriteOnce`. -<2> The default volumeMode is `Filesystem`. -<3> If you add an access mode for a storage class, replace the `<new>` part of the parameter with the storage class name. -<4> If you add a volume mode for a storage class, replace the `<new>` part of the parameter with the storage class name. - -. Click *Save* to update the config map. - - - diff --git a/modules/virt-editing-template-yaml-web.adoc b/modules/virt-editing-template-yaml-web.adoc deleted file mode 100644 index 92e558388879..000000000000 --- a/modules/virt-editing-template-yaml-web.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/vm_templates/virt-editing-vm-template.adoc - -[id="virt-editing-template-yaml-web_{context}"] -= Editing virtual machine template YAML configuration in the web console - -You can edit the YAML configuration of a virtual machine template from the web console. - -Some parameters cannot be modified. If you click *Save* with an invalid configuration, an error message indicates the parameter that cannot be modified. - -[NOTE] -==== -Navigating away from the YAML screen while editing cancels any changes to the configuration that you made. -==== - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Templates* tab. - -. Select a template to open the *VM Template Details* screen. - -. Click the *YAML* tab to display the editable configuration. - -. Edit the file and click *Save*. - -A confirmation message, which includes the updated version number for the object, shows that the YAML configuration was successfully edited. diff --git a/modules/virt-editing-vm-cli.adoc b/modules/virt-editing-vm-cli.adoc deleted file mode 100644 index 76b426db4add..000000000000 --- a/modules/virt-editing-vm-cli.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-edit-vms.adoc - -[id="virt-editing-vm-cli_{context}"] -= Editing a virtual machine YAML configuration using the CLI - -Use this procedure to edit a virtual machine YAML configuration using the CLI. - -.Prerequisites - -* You configured a virtual machine with a YAML object configuration file. -* You installed the `oc` CLI. - -.Procedure - -. Run the following command to update the virtual machine configuration: -+ -[source,terminal] ----- -$ oc edit <object_type> <object_ID> ----- - -. Open the object configuration. -. Edit the YAML. -. If you edit a running virtual machine, you need to do one of the following: -* Restart the virtual machine. -* Run the following command for the new configuration to take effect: -+ -[source,terminal] ----- -$ oc apply <object_type> <object_ID> ----- diff --git a/modules/virt-editing-vm-web.adoc b/modules/virt-editing-vm-web.adoc deleted file mode 100644 index 13a3a079ac4f..000000000000 --- a/modules/virt-editing-vm-web.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-edit-vms.adoc -// * virt/vm_templates/virt-editing-vm-template.adoc - -// Establishing conditionals so content can be re-used for editing VMs -// and VM templates. - -// The ifeval statements use the context of the assembly in which the module -// is included to declare 1) an attribute, and 2) the content of the {object} -// and {object-gui} variables used throughout. We need two variables because -// the object is lower case, but the gui elements are capitalized. - -ifeval::["{context}" == "virt-editing-vm-template"] -:virt-vm-template: -:object: virtual machine template -:object-gui: Templates -:object-vm-details: VM Template Details -endif::[] - -ifeval::["{context}" == "virt-edit-vms"] -:virt-vm: -:object: virtual machine -:object-gui: Virtual Machines -:object-vm-details: Details -endif::[] - -[id="virt-editing-vm-web_{context}"] - -= Editing a {object} in the web console - -Edit select values of a {object} in the web console by clicking the pencil icon next to the relevant field. Other values can be edited using the CLI. - -Labels and annotations are editable for both preconfigured Red Hat templates and your custom virtual machine templates. All other values are editable only for custom virtual machine templates that users have created using the Red Hat templates or the *Create Virtual Machine Template* wizard. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *{object-gui}* tab. - -. Select a {object}. - -. Click the *{object-vm-details}* tab. - -. Click the pencil icon to make a field editable. - -. Make the relevant changes and click *Save*. - -// Using the attributes we declared earlier, we can have different lines after -// the procedure that will be included in the different assemblies. - -ifdef::virt-vm-template[] -Editing a virtual machine template will not affect virtual machines already created from that template. -endif::virt-vm-template[] -ifdef::virt-vm[] -[NOTE] -==== -If the {object} is running, changes to *Boot Order* or *Flavor* will not take effect until you restart the {object}. - -You can view pending changes by clicking *View Pending Changes* on the right side of the relevant field. The *Pending Changes* banner at the -top of the page displays a list of all changes that will be applied when the {object} restarts. -==== -endif::virt-vm[] - -// Unsetting the attributes/variables used in the module or else they will stay active -// subsequent modules in the assembly and topic_map. -// Attributes set with an ifeval statement need to be unset with an ifeval statement. - -ifeval::["{context}" == "virt-edit-vms"] -:virt-vm!: -:object!: -:object-gui!: -:object-vm-details!: -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:virt-vm-template!: -:object!: -:object-gui!: -:object-vm-details!: -endif::[] diff --git a/modules/virt-editing-vm-yaml-web.adoc b/modules/virt-editing-vm-yaml-web.adoc deleted file mode 100644 index ad50c9de6251..000000000000 --- a/modules/virt-editing-vm-yaml-web.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-edit-vms.adoc -//Establishing conditional expressions -// -ifeval::["{context}" == "virt-edit-vms"] -:object: virtual machine -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:object: virtual machine template -endif::[] - -[id="virt-editing-vm-yaml-web_{context}"] - -= Editing a virtual machine YAML configuration using the web console - -You can edit the YAML configuration of a virtual machine in the web console. Some parameters cannot be modified. If you click *Save* with an invalid configuration, an error message indicates the parameter that cannot be changed. - -If you edit the YAML configuration while the virtual machine is running, changes will not take effect until you restart the virtual machine. - -[NOTE] -==== -Navigating away from the YAML screen while editing cancels any changes to the configuration you have made. -==== - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Select a {object}. - -. Click the *YAML* tab to display the editable configuration. - -. Optional: You can click *Download* to download the YAML file locally in its current state. - -. Edit the file and click *Save*. - -A confirmation message shows that the modification has been successful and includes the updated version number for the object. - -//Ending conditional expressions -ifeval::["{context}" == "virt-edit-vms"] -:object!: -endif::[] - -ifeval::["{context}" == "virt-editing-vm-template"] -:object!: -endif::[] diff --git a/modules/virt-editing-vmis-web.adoc b/modules/virt-editing-vmis-web.adoc deleted file mode 100644 index ed5554a4db53..000000000000 --- a/modules/virt-editing-vmis-web.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-manage-vmis.adoc - -[id="virt-editing-vmis-web_{context}"] -= Editing a standalone virtual machine instance using the web console - -You can edit annotations and labels for a standalone virtual machine instance (VMI) using the web console. Other items displayed in the *Details* page for a standalone VMI are not editable. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. A list of virtual machines (VMs) and standalone VMIs displays. - -. Click the name of a standalone VMI to open the *Virtual Machine Instance Overview* screen. - -. Click the *Details* tab. - -. Click the pencil icon that is located on the right side of *Annotations*. - -. Make the relevant changes and click *Save*. - -[NOTE] -==== -To edit labels for a standalone VMI, click *Actions* and select *Edit Labels.* Make the relevant changes and click *Save*. -==== diff --git a/modules/virt-enabling-dedicated-resources.adoc b/modules/virt-enabling-dedicated-resources.adoc deleted file mode 100644 index 133b9ffce5de..000000000000 --- a/modules/virt-enabling-dedicated-resources.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-dedicated-resources-vm.adoc -// * virt/vm_templates/virt-dedicated-resources-vm-template.adoc - -// Establishing conditionals so content can be re-used for editing VMs -// and VM templates. - -ifeval::["{context}" == "virt-dedicated-resources-vm-template"] -:virt-vm-template: -:object: virtual machine template -:object-gui: Virtual Machine Template -endif::[] - -ifeval::["{context}" == "virt-dedicated-resources-vm"] -:virt-vm: -:object: virtual machine -:object-gui: Virtual Machine -endif::[] - -[id="virt-enabling-dedicated-resources_{context}"] -= Enabling dedicated resources for a {object} - -You can enable dedicated resources for a {object} in the *Details* tab. Virtual machines that were created by using a Red Hat template or the wizard can be enabled with dedicated resources. - -.Procedure - -. Click *Workloads* -> *{object-gui}s* from the side menu. -. Select a {object} to open the *{object-gui}* tab. -. Click the *Details* tab. -. Click the pencil icon to the right of the *Dedicated Resources* field to open the *Dedicated Resources* window. -. Select *Schedule this workload with dedicated resources (guaranteed policy)*. -. Click *Save*. - -// Unsetting all conditionals used in module - -ifeval::["{context}" == "virt-dedicated-resources-vm"] -:virt-vm!: -:object!: -:object-gui!: -endif::[] - -ifeval::["{context}" == "virt-dedicated-resources-vm-template"] -:virt-vm-template!: -:object!: -:object-gui!: -endif::[] diff --git a/modules/virt-enabling-mac-address-pool-for-namespace-cli.adoc b/modules/virt-enabling-mac-address-pool-for-namespace-cli.adoc deleted file mode 100644 index ec1f2f782065..000000000000 --- a/modules/virt-enabling-mac-address-pool-for-namespace-cli.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc - -[id="virt-enabling-mac-address-pool-for-namespace-cli_{context}"] -= Enabling a MAC address pool for a namespace in the CLI - -Enable a MAC address pool for virtual machines in a namespace by applying the `mutatevirtualmachines.kubemacpool.io=allocate` label to the namespace. - -.Procedure - -* Add the KubeMacPool label to the namespace. -The following example adds the KubeMacPool label to two namespaces, `<namespace1>` and `<namespace2>`: -+ -[source,terminal] ----- -$ oc label namespace <namespace1> <namespace2> mutatevirtualmachines.kubemacpool.io=allocate ----- - diff --git a/modules/virt-enabling-preallocation-for-dv.adoc b/modules/virt-enabling-preallocation-for-dv.adoc deleted file mode 100644 index 3cd9adc07ef9..000000000000 --- a/modules/virt-enabling-preallocation-for-dv.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc - -[id="virt-enabling-preallocation-for-dv_{context}"] -= Enabling preallocation for a data volume - -If preallocation is not globally enabled for the cluster, you can enable it for specific data volumes by including the `spec.preallocation` field in the data volume manifest. You can enable preallocation mode in either the web console or by using the OpenShift client (`oc`). - -Preallocation mode is supported for all CDI source types. - -.Procedure - -* Specify the `spec.preallocation` field in the data volume manifest: -+ -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: preallocated-datavolume -spec: - source: <1> - ... - pvc: - ... - preallocation: true <2> ----- -<1> All CDI source types support preallocation, however preallocation is ignored for cloning operations. -<2> The `preallocation` field is a boolean that defaults to false. - diff --git a/modules/virt-enabling-preallocation-globally.adoc b/modules/virt-enabling-preallocation-globally.adoc deleted file mode 100644 index 99b514852304..000000000000 --- a/modules/virt-enabling-preallocation-globally.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc - -[id="virt-enabling-preallocation-globally_{context}"] -= Enabling preallocation globally - -You can enable cluster-wide preallocation mode for the Containerized Data Importer (CDI) by adding the `preallocation` field to the `CDI` object. - -.Prerequisites - -* Install the OpenShift client (`oc`). - -.Procedure - -. Use the `oc` client to edit the `CDI` object: -+ -[source,terminal] ----- -$ oc edit cdi ----- - -. Set the `spec.config.preallocation` field with a value of `true`: -+ -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: CDI -metadata: -... -spec: - config: - preallocation: true <1> ----- -<1> The `preallocation` field is a boolean that defaults to false. - -. Save and exit your editor to update the `CDI` object and enable preallocation mode. - - diff --git a/modules/virt-enabling-virt-repos.adoc b/modules/virt-enabling-virt-repos.adoc deleted file mode 100644 index fd8fa631dc0a..000000000000 --- a/modules/virt-enabling-virt-repos.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// virt/install/virt-installing-virtctl.adoc - -[id="virt-enabling-virt-repos_{context}"] -= Enabling {VirtProductName} repositories - -Red Hat offers {VirtProductName} repositories for both Red Hat Enterprise Linux 8 -and Red Hat Enterprise Linux 7: - -* Red Hat Enterprise Linux 8 repository: `cnv-2.5-for-rhel-8-x86_64-rpms` - -* Red Hat Enterprise Linux 7 repository: `rhel-7-server-cnv-2.5-rpms` - -The process for enabling the repository in `subscription-manager` is the same -in both platforms. - -.Procedure - -* Enable the appropriate {VirtProductName} repository for your system by running the following command: -+ -[source,terminal] ----- -# subscription-manager repos --enable <repository> ----- diff --git a/modules/virt-example-ansible-playbook-creating-vms.adoc b/modules/virt-example-ansible-playbook-creating-vms.adoc deleted file mode 100644 index 0dc8b26b127f..000000000000 --- a/modules/virt-example-ansible-playbook-creating-vms.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-automating-management-tasks.adoc - -[id="virt-example-ansible-playbook-creating-vms_{context}"] -= Example: Ansible Playbook for creating virtual machines - -You can use the `kubevirt_vm` Ansible Playbook to automate virtual machine -creation. - -The following YAML file is an example of the `kubevirt_vm` playbook. It includes -sample values that you must replace with your own information if you run the -playbook. - -[source,yaml] ----- ---- -- name: Ansible Playbook 1 - hosts: localhost - connection: local - tasks: - - name: Create my first VM - kubevirt_vm: - namespace: default - name: vm1 - cpu_cores: 1 - memory: 64Mi - disks: - - name: containerdisk - volume: - containerDisk: - image: kubevirt/cirros-container-disk-demo:latest - disk: - bus: virtio ----- - -.Additional information - -* link:https://docs.ansible.com/ansible/latest/user_guide/playbooks.html[Intro to Playbooks] -* link:https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html#validate-playbook-tools[Tools for Validating Playbooks] diff --git a/modules/virt-example-bond-nncp.adoc b/modules/virt-example-bond-nncp.adoc deleted file mode 100644 index 5a836f965466..000000000000 --- a/modules/virt-example-bond-nncp.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-example-bond-nncp_{context}"] -= Example: Bond interface node network configuration policy - -Create a bond interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest -to the cluster. - -[NOTE] -==== -{VirtProductName} only supports the following bond modes: - -* mode=1 active-backup + -* mode=2 balance-xor + -* mode=4 802.3ad + -* mode=5 balance-tlb + -* mode=6 balance-alb -==== - -The following YAML file is an example of a manifest for a bond interface. -It includes samples values that you must replace with your own information. - -[source,yaml] ----- -apiVersion: nmstate.io/v1beta1 -kind: NodeNetworkConfigurationPolicy -metadata: - name: bond0-eth1-eth2-policy <1> -spec: - nodeSelector: <2> - kubernetes.io/hostname: <node01> <3> - desiredState: - interfaces: - - name: bond0 <4> - description: Bond enslaving eth1 and eth2 <5> - type: bond <6> - state: up <7> - ipv4: - dhcp: true <8> - enabled: true <9> - link-aggregation: - mode: active-backup <10> - options: - miimon: '140' <11> - slaves: <12> - - eth1 - - eth2 - mtu: 1450 <13> ----- -<1> Name of the policy. -<2> Optional: If you do not include the `nodeSelector` parameter, the policy applies to all nodes in the cluster. -<3> This example uses a `hostname` node selector. -<4> Name of the interface. -<5> Optional: Human-readable description of the interface. -<6> The type of interface. This example creates a bond. -<7> The requested state for the interface after creation. -<8> Optional: If you do not use `dhcp`, you can either set a static IP or leave the interface without an IP address. -<9> Enables `ipv4` in this example. -<10> The driver mode for the bond. This example uses an active backup mode. -<11> Optional: This example uses miimon to inspect the bond link every 140ms. -<12> The subordinate node NICs in the bond. -<13> Optional: The maximum transmission unit (MTU) for the bond. If not specified, this value is set to `1500` by default. diff --git a/modules/virt-example-bridge-nncp.adoc b/modules/virt-example-bridge-nncp.adoc deleted file mode 100644 index a5439eecbde4..000000000000 --- a/modules/virt-example-bridge-nncp.adoc +++ /dev/null @@ -1,50 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-example-bridge-nncp_{context}"] -= Example: Linux bridge interface node network configuration policy - -Create a Linux bridge interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest -to the cluster. - -The following YAML file is an example of a manifest for a Linux bridge interface. -It includes samples values that you must replace with your own information. - -[source,yaml] ----- -apiVersion: nmstate.io/v1beta1 -kind: NodeNetworkConfigurationPolicy -metadata: - name: br1-eth1-policy <1> -spec: - nodeSelector: <2> - kubernetes.io/hostname: <node01> <3> - desiredState: - interfaces: - - name: br1 <4> - description: Linux bridge with eth1 as a port <5> - type: linux-bridge <6> - state: up <7> - ipv4: - dhcp: true <8> - enabled: true <9> - bridge: - options: - stp: - enabled: false <10> - port: - - name: eth1 <11> ----- -<1> Name of the policy. -<2> Optional: If you do not include the `nodeSelector` parameter, the policy applies to all nodes in the cluster. -<3> This example uses a `hostname` node selector. -<4> Name of the interface. -<5> Optional: Human-readable description of the interface. -<6> The type of interface. This example creates a bridge. -<7> The requested state for the interface after creation. -<8> Optional: If you do not use `dhcp`, you can either set a static IP or leave the interface without an IP address. -<9> Enables `ipv4` in this example. -<10> Disables `stp` in this example. -<11> The node NIC to which the bridge attaches. diff --git a/modules/virt-example-configmap-tls-certificate.adoc b/modules/virt-example-configmap-tls-certificate.adoc deleted file mode 100644 index 67e93b4124af..000000000000 --- a/modules/virt-example-configmap-tls-certificate.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-tls-certificates-for-dv-imports.adoc - -[id="virt-example-configmap-tls-certificate_{context}"] -= Example: Config map created from a TLS certificate - -The following example is of a config map created from `ca.pem` TLS certificate. - -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: tls-certs -data: - ca.pem: | - -----BEGIN CERTIFICATE----- - ... <base64 encoded cert> ... - -----END CERTIFICATE----- ----- diff --git a/modules/virt-example-ethernet-nncp.adoc b/modules/virt-example-ethernet-nncp.adoc deleted file mode 100644 index 3ed5b2028472..000000000000 --- a/modules/virt-example-ethernet-nncp.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-example-ethernet-nncp_{context}"] -= Example: Ethernet interface node network configuration policy - -Configure an Ethernet interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest to the cluster. - -The following YAML file is an example of a manifest for an Ethernet interface. -It includes sample values that you must replace with your own information. - -[source,yaml] ----- -apiVersion: nmstate.io/v1beta1 -kind: NodeNetworkConfigurationPolicy -metadata: - name: eth1-policy <1> -spec: - nodeSelector: <2> - kubernetes.io/hostname: <node01> <3> - desiredState: - interfaces: - - name: eth1 <4> - description: Configuring eth1 on node01 <5> - type: ethernet <6> - state: up <7> - ipv4: - dhcp: true <8> - enabled: true <9> ----- -<1> Name of the policy. -<2> Optional: If you do not include the `nodeSelector` parameter, the policy applies to all nodes in the cluster. -<3> This example uses a `hostname` node selector. -<4> Name of the interface. -<5> Optional: Human-readable description of the interface. -<6> The type of interface. This example creates an Ethernet networking interface. -<7> The requested state for the interface after creation. -<8> Optional: If you do not use `dhcp`, you can either set a static IP or leave the interface without an IP address. -<9> Enables `ipv4` in this example. diff --git a/modules/virt-example-kubevirtstorageclassdefaults.adoc b/modules/virt-example-kubevirtstorageclassdefaults.adoc deleted file mode 100644 index 93401d2f3deb..000000000000 --- a/modules/virt-example-kubevirtstorageclassdefaults.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc - -[id="virt-example-kubevirtstorageclassdefaults_{context}"] -= Example of multiple storage class defaults - -The following YAML file is an example of a `kubevirt-storage-class-defaults` config map that has storage settings configured for two storage classes, `migration` and `block`. - -Ensure that all settings are supported by your underlying storage before you update the config map. - -[source,yaml] ----- -kind: ConfigMap -apiVersion: v1 -metadata: - name: kubevirt-storage-class-defaults - namespace: openshift-cnv -... -data: - accessMode: ReadWriteOnce - volumeMode: Filesystem - nfs-sc.accessMode: ReadWriteMany - nfs-sc.volumeMode: Filesystem - block-sc.accessMode: ReadWriteMany - block-sc.volumeMode: Block ----- diff --git a/modules/virt-example-nmstate-IP-management.adoc b/modules/virt-example-nmstate-IP-management.adoc deleted file mode 100644 index 6bf684455985..000000000000 --- a/modules/virt-example-nmstate-IP-management.adoc +++ /dev/null @@ -1,138 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-example-nmstate-IP-management_{context}"] -= Examples: IP management - -The following example configuration snippets demonstrate different methods of IP management. - -These examples use the `ethernet` interface type to simplify the example while showing the related context in the policy configuration. These IP management examples can be used with the other interface types. - -[id="virt-example-nmstate-IP-management-static_{context}"] -== Static - -The following snippet statically configures an IP address on the Ethernet interface: - -[source,yaml] ----- -... - interfaces: - - name: eth1 - description: static IP on eth1 - type: ethernet - state: up - ipv4: - address: - - ip: 192.168.122.250 <1> - prefix-length: 24 - enabled: true -... ----- -<1> Replace this value with the static IP address for the interface. - -[id="virt-example-nmstate-IP-management-no-ip_{context}"] -== No IP address - -The following snippet ensures that the interface has no IP address: - -[source,yaml] ----- -... - interfaces: - - name: eth1 - description: No IP on eth1 - type: ethernet - state: up - ipv4: - enabled: false -... ----- - -[id="virt-example-nmstate-IP-management-dhcp_{context}"] -== Dynamic host configuration - -The following snippet configures an Ethernet interface that uses a dynamic IP address, gateway address, and DNS: - -[source,yaml] ----- -... - interfaces: - - name: eth1 - description: DHCP on eth1 - type: ethernet - state: up - ipv4: - dhcp: true - enabled: true -... ----- - -The following snippet configures an Ethernet interface that uses a dynamic IP address but does not use a dynamic gateway address or DNS: - -[source,yaml] ----- -... - interfaces: - - name: eth1 - description: DHCP without gateway or DNS on eth1 - type: ethernet - state: up - ipv4: - dhcp: true - auto-gateway: false - auto-dns: false - enabled: true -... ----- - -[id="virt-example-nmstate-IP-management-dns_{context}"] -== DNS - -The following snippet sets DNS configuration on the host. - -[source,yaml] ----- -... - interfaces: - ... - dns-resolver: - config: - search: - - example.com - - example.org - server: - - 8.8.8.8 -... ----- - -[id="virt-example-nmstate-IP-management-static-routing_{context}"] -== Static routing - -The following snippet configures a static route and a static IP on interface `eth1`. - -[source,yaml] ----- -... - interfaces: - - name: eth1 - description: Static routing on eth1 - type: ethernet - state: up - ipv4: - address: - - ip: 192.0.2.251 <1> - prefix-length: 24 - enabled: true - routes: - config: - - destination: 198.51.100.0/24 - metric: 150 - next-hop-address: 192.0.2.1 <2> - next-hop-interface: eth1 - table-id: 254 -... ----- -<1> The static IP address for the Ethernet interface. -<2> Next hop address for the node traffic. This must be in the same subnet as the IP address set for the Ethernet interface. diff --git a/modules/virt-example-nmstate-multiple-interfaces.adoc b/modules/virt-example-nmstate-multiple-interfaces.adoc deleted file mode 100644 index eefcfc4401ab..000000000000 --- a/modules/virt-example-nmstate-multiple-interfaces.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-example-nmstate-multiple-interfaces_{context}"] -= Example: Multiple interfaces in the same node network configuration policy - -You can create multiple interfaces in the same node network configuration policy. These interfaces can reference each other, allowing you to build and deploy a network configuration by using a single policy manifest. - -The following example snippet creates a bond that is named `bond10` across two NICs and a Linux bridge that is named `br1` that connects to the bond. - -[source,yaml] ----- -... - interfaces: - - name: bond10 - description: Bonding eth2 and eth3 for Linux bridge - type: bond - state: up - link-aggregation: - slaves: - - eth2 - - eth3 - - name: br1 - description: Linux bridge on bond - type: linux-bridge - state: up - bridge: - port: - - name: bond10 -... ----- diff --git a/modules/virt-example-node-placement-affinity-hyperconverged-cr.adoc b/modules/virt-example-node-placement-affinity-hyperconverged-cr.adoc deleted file mode 100644 index 6f23d637758c..000000000000 --- a/modules/virt-example-node-placement-affinity-hyperconverged-cr.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/virt-specifying-nodes-for-virtualization-components.adoc - -[id="virt-example-node-placement-affinity-hyperconverged-cr_{context}"] -= Example: Node placement with affinity in the HyperConverged Cluster CR - -In this example, `affinity` is configured so that infrastructure resources are placed on nodes that are labeled with `example.io/example-infra-key = example-value` and workloads are placed on nodes labeled with `example.io/example-workloads-key = example-workloads-value`. Nodes that have more than eight CPUs are preferred for workloads, but if they are not available, pods are still scheduled. - -[source,yaml] ----- -apiVersion: hco.kubevirt.io/v1beta1 -kind: HyperConverged -metadata: - name: kubevirt-hyperconverged - namespace: openshift-cnv -spec: - infra: - nodePlacement: - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: example.io/example-infra-key - operator: In - values: - - example-infra-value - workloads: - nodePlacement: - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: example.io/example-workloads-key - operator: In - values: - - example-workloads-value - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 1 - preference: - matchExpressions: - - key: example.io/num-cpus - operator: gt - values: - - 8 ----- \ No newline at end of file diff --git a/modules/virt-example-node-placement-node-selector-hpp.adoc b/modules/virt-example-node-placement-node-selector-hpp.adoc deleted file mode 100644 index e6ad87aea359..000000000000 --- a/modules/virt-example-node-placement-node-selector-hpp.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/virt-specifying-nodes-for-virtualization-components.adoc - -[id="virt-example-node-placement-node-selector-hpp_{context}"] -= Example: Node placement with nodeSelector in the HostPathProvisioner object - -In this example, `nodeSelector` is configured so that workloads are placed on nodes labeled with `example.io/example-workloads-key = example-workloads-value`. - -[source,yaml] ----- -apiVersion: hostpathprovisioner.kubevirt.io/v1beta1 -kind: HostPathProvisioner -metadata: - name: hostpath-provisioner -spec: - imagePullPolicy: IfNotPresent - pathConfig: - path: "</path/to/backing/directory>" - useNamingPrefix: false - workload: - nodeSelector: - example.io/example-workloads-key: example-workloads-value ----- \ No newline at end of file diff --git a/modules/virt-example-node-placement-node-selector-hyperconverged-cr.adoc b/modules/virt-example-node-placement-node-selector-hyperconverged-cr.adoc deleted file mode 100644 index aa654facbd92..000000000000 --- a/modules/virt-example-node-placement-node-selector-hyperconverged-cr.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/virt-specifying-nodes-for-virtualization-components.adoc - -[id="virt-example-node-placement-node-selector-hyperconverged-cr_{context}"] -= Example: Node placement with nodeSelector in the HyperConverged Cluster CR - -In this example, `nodeSelector` is configured so that infrastructure resources are placed on nodes that are labeled with `example.io/example-infra-key = example-infra-value` and workloads are placed on nodes labeled with `example.io/example-workloads-key = example-workloads-value`. - -[source,yaml] ----- -apiVersion: hco.kubevirt.io/v1beta1 -kind: HyperConverged -metadata: - name: kubevirt-hyperconverged - namespace: openshift-cnv -spec: - infra: - nodePlacement: - nodeSelector: - example.io/example-infra-key: example-infra-value - workloads: - nodePlacement: - nodeSelector: - example.io/example-workloads-key: example-workloads-value ----- \ No newline at end of file diff --git a/modules/virt-example-node-placement-node-selector-olm-subscription.adoc b/modules/virt-example-node-placement-node-selector-olm-subscription.adoc deleted file mode 100644 index 58c8900ba4e0..000000000000 --- a/modules/virt-example-node-placement-node-selector-olm-subscription.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/virt-specifying-nodes-for-virtualization-components.adoc - -[id="virt-example-node-placement-node-selector-olm-subscription_{context}"] -= Example: Node placement with nodeSelector in the OLM Subscription object - -In this example, `nodeSelector` is configured so that OLM places the {VirtProductName} Operators on nodes that are labeled with `example.io/example-infra-key = example-infra-value`. - -[source,yaml,subs="attributes+"] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: hco-operatorhub - namespace: openshift-cnv -spec: - source: redhat-operators - sourceNamespace: openshift-marketplace - name: kubevirt-hyperconverged - startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} - channel: "stable" - config: - nodeSelector: - example.io/example-infra-key: example-infra-value ----- \ No newline at end of file diff --git a/modules/virt-example-node-placement-tolerations-hyperconverged-cr.adoc b/modules/virt-example-node-placement-tolerations-hyperconverged-cr.adoc deleted file mode 100644 index 73fa06b5db26..000000000000 --- a/modules/virt-example-node-placement-tolerations-hyperconverged-cr.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/virt-specifying-nodes-for-virtualization-components.adoc - -[id="virt-example-node-placement-tolerations-hyperconverged-cr_{context}"] -= Example: Node placement with tolerations in the HyperConverged Cluster CR - -In this example, nodes that are reserved for {VirtProductName} components are labeled with the `key=virtualization:NoSchedule` taint. Only pods with the matching tolerations are scheduled to these nodes. - -[source,yaml] ----- -apiVersion: hco.kubevirt.io/v1beta1 -kind: HyperConverged -metadata: - name: kubevirt-hyperconverged - namespace: openshift-cnv -spec: - workloads: - nodePlacement: - tolerations: - - key: "key" - operator: "Equal" - value: "virtualization" - effect: "NoSchedule" ----- \ No newline at end of file diff --git a/modules/virt-example-node-placement-tolerations-olm-subscription.adoc b/modules/virt-example-node-placement-tolerations-olm-subscription.adoc deleted file mode 100644 index eca2baf25083..000000000000 --- a/modules/virt-example-node-placement-tolerations-olm-subscription.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/virt-specifying-nodes-for-virtualization-components.adoc - -[id="virt-example-node-placement-tolerations-olm-subscription_{context}"] -= Example: Node placement with tolerations in the OLM Subscription object - -In this example, nodes that are reserved for OLM to deploy {VirtProductName} Operators are labeled with the `key=virtualization:NoSchedule` taint. Only pods with the matching tolerations are scheduled to these nodes. - -[source,yaml,subs="attributes+"] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: hco-operatorhub - namespace: openshift-cnv -spec: - source: redhat-operators - sourceNamespace: openshift-marketplace - name: kubevirt-hyperconverged - startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} - channel: "stable" - config: - tolerations: - - key: "key" - operator: "Equal" - value: "virtualization" - effect: "NoSchedule" ----- \ No newline at end of file diff --git a/modules/virt-example-vlan-nncp.adoc b/modules/virt-example-vlan-nncp.adoc deleted file mode 100644 index d87e0fadd1f7..000000000000 --- a/modules/virt-example-vlan-nncp.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-example-vlan-nncp_{context}"] -= Example: VLAN interface node network configuration policy - -Create a VLAN interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest -to the cluster. - -The following YAML file is an example of a manifest for a VLAN interface. -It includes samples values that you must replace with your own information. - -[source,yaml] ----- -apiVersion: nmstate.io/v1beta1 -kind: NodeNetworkConfigurationPolicy -metadata: - name: vlan-eth1-policy <1> -spec: - nodeSelector: <2> - kubernetes.io/hostname: <node01> <3> - desiredState: - interfaces: - - name: eth1.102 <4> - description: VLAN using eth1 <5> - type: vlan <6> - state: up <7> - vlan: - base-iface: eth1 <8> - id: 102 <9> ----- -<1> Name of the policy. -<2> Optional: If you do not include the `nodeSelector` parameter, the policy applies to all nodes in the cluster. -<3> This example uses a `hostname` node selector. -<4> Name of the interface. -<5> Optional: Human-readable description of the interface. -<6> The type of interface. This example creates a VLAN. -<7> The requested state for the interface after creation. -<8> The node NIC to which the VLAN is attached. -<9> The VLAN tag. diff --git a/modules/virt-extended-selinux-policies-for-virt-launcher.adoc b/modules/virt-extended-selinux-policies-for-virt-launcher.adoc deleted file mode 100644 index 48e30817fa37..000000000000 --- a/modules/virt-extended-selinux-policies-for-virt-launcher.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virt-additional-security-privileges-controller-and-launcher.adoc - -[id="virt-extended-selinux-policies-for-virt-launcher_{context}"] -= Extended SELinux policies for virt-launcher pods - -The `container_t` SELinux policy for virt-launcher pods is extended with the following rules: - -* `allow process self (tun_socket (relabelfrom relabelto attach_queue))` -* `allow process sysfs_t (file (write))` -* `allow process hugetlbfs_t (dir (add_name create write remove_name rmdir setattr))` -* `allow process hugetlbfs_t (file (create unlink))` - -These rules enable the following virtualization features: - -* Relabel and attach queues to its own TUN sockets, which is required to support network multi-queue. Multi-queue enables network performance to scale as the number of available vCPUs increases. - -* Allows virt-launcher pods to write information to sysfs (`/sys`) files, which is required to enable Single Root I/O Virtualization (SR-IOV). - -* Read/write `hugetlbfs` entries, which is required to support huge pages. Huge pages are a method of managing large amounts of memory by increasing the memory page size. - diff --git a/modules/virt-features-for-storage-matrix.adoc b/modules/virt-features-for-storage-matrix.adoc deleted file mode 100644 index 369449d5d12b..000000000000 --- a/modules/virt-features-for-storage-matrix.adoc +++ /dev/null @@ -1,109 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-features-for-storage.adoc -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc - -[id="virt-features-for-storage-matrix_{context}"] -= {VirtProductName} storage feature matrix - -ifdef::virt-importing-rhv-vm,virt-importing-vmware-vm[] -The following table describes the {VirtProductName} storage types that support VM import. -endif::[] - -[caption=] -.{VirtProductName} storage feature matrix -ifdef::virt-features-for-storage[] -[cols="40%,15%,15%,15%,15%",options="header"] -|=== -| -|Virtual machine live migration -|Host-assisted virtual machine disk cloning -|Storage-assisted virtual machine disk cloning -|Virtual machine snapshots -endif::[] -ifdef::virt-importing-rhv-vm[] -[cols="50%,50%",options="header",caption] -|=== -| -|RHV VM import -endif::[] -ifdef::virt-importing-vmware-vm[] -[cols="50%,50%",options="header",caption] -|=== -| -|VMware VM import -endif::[] - -|OpenShift Container Storage: RBD block-mode volumes -ifdef::virt-features-for-storage[] -|Yes -|Yes -|Yes -|Yes -endif::[] -ifdef::virt-importing-rhv-vm,virt-importing-vmware-vm[] -|Yes -endif::[] - -|{VirtProductName} hostpath provisioner -ifdef::virt-features-for-storage[] -|No -|Yes -|No -|No -endif::[] -ifdef::virt-importing-rhv-vm[] -|No -endif::[] -ifdef::virt-importing-vmware-vm[] -|Yes -endif::[] - -|Other multi-node writable storage -ifdef::virt-features-for-storage[] -|Yes ^[1]^ -|Yes -|Yes ^[2]^ -|Yes ^[2]^ -endif::[] -ifdef::virt-importing-rhv-vm,virt-importing-vmware-vm[] -|Yes ^[1]^ -endif::[] - -|Other single-node writable storage -ifdef::virt-features-for-storage[] -|No -|Yes -|Yes ^[2]^ -|Yes ^[2]^ -endif::[] -ifdef::virt-importing-rhv-vm,virt-importing-vmware-vm[] -|Yes ^[2]^ -endif::[] -|=== -[.small] -ifdef::virt-importing-rhv-vm,virt-importing-vmware-vm[] --- -1. PVCs must request a ReadWriteMany access mode. -2. PVCs must request a ReadWriteOnce access mode. --- -endif::[] -ifdef::virt-features-for-storage[] --- -1. PVCs must request a ReadWriteMany access mode. -2. Storage provider must support both Kubernetes and CSI snapshot APIs --- -endif::[] - -ifdef::virt-features-for-storage[] -[NOTE] -==== -You cannot live migrate virtual machines that use: - -* A storage class with ReadWriteOnce (RWO) access mode -* Passthrough features such as SR-IOV and GPU - -Do not set the `evictionStrategy` field to `LiveMigrate` for these virtual machines. -==== -endif::[] diff --git a/modules/virt-filtering-vm-templates.adoc b/modules/virt-filtering-vm-templates.adoc deleted file mode 100644 index 30ed8ca3ebd6..000000000000 --- a/modules/virt-filtering-vm-templates.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-filtering-vm-templates_{context}"] -= Filtering the list of virtual machine templates by providers - -In the *Templates* tab, you can use the *Search by name* field to search for virtual machine templates by specifying either the name of the template or a label that identfies the template. You can also filter templates by the provider, and display only those templates that meet your filtering criteria. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Templates* tab. -. To filter templates, click *Filter*. -. Select the appropriate checkbox from the list to filter the templates: *Red Hat Supported*, *User Supported*, *Red Hat Provided*, and *User Provided*. diff --git a/modules/virt-how-fs-overhead-affects-space-vm-disks.adoc b/modules/virt-how-fs-overhead-affects-space-vm-disks.adoc deleted file mode 100644 index 1e85abfb8e9b..000000000000 --- a/modules/virt-how-fs-overhead-affects-space-vm-disks.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-reserving-pvc-space-fs-overhead.adoc - -[id="virt-how-fs-overhead-affects-space-vm-disks_{context}"] -= How file system overhead affects space for virtual machine disks - -When you add a virtual machine disk to a persistent volume claim (PVC) that uses the `Filesystem` volume mode, you must ensure that there is enough space on the PVC for: - -* The virtual machine disk. -* The space that the Containerized Data Importer (CDI) reserves for file system overhead, such as metadata. - -By default, CDI reserves 5.5% of the PVC space for overhead, reducing the space available for virtual machine disks by that amount. - -If a different value works better for your use case, you can configure the overhead value by editing the `CDI` object. You can change the value globally and you can specify values for specific storage classes. \ No newline at end of file diff --git a/modules/virt-importing-vm-cli.adoc b/modules/virt-importing-vm-cli.adoc deleted file mode 100644 index 632735cd757e..000000000000 --- a/modules/virt-importing-vm-cli.adoc +++ /dev/null @@ -1,191 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc - -[id="virt-importing-vm-cli_{context}"] -= Importing a virtual machine with the CLI - -You can import a virtual machine with the CLI by creating the `Secret` and `VirtualMachineImport` custom resources (CRs). The `Secret` CR stores the RHV Manager credentials and CA certificate. The `VirtualMachineImport` CR defines the parameters of the VM import process. - -Optional: You can create a `ResourceMapping` CR that is separate from the `VirtualMachineImport` CR. A `ResourceMapping` CR provides greater flexibility, for example, if you import additional RHV VMs. - -[IMPORTANT] -==== -The default target storage class must be NFS. Cinder does not support RHV VM import. -==== - -.Procedure - -. Create the `Secret` CR by running the following command: -+ -[source,yaml] ----- -$ cat <<EOF | oc create -f - -apiVersion: v1 -kind: Secret -metadata: - name: rhv-credentials - namespace: default <1> -type: Opaque -stringData: - ovirt: | - apiUrl: <api_endpoint> <2> - username: admin@internal - password: <3> - caCert: | - -----BEGIN CERTIFICATE----- - <4> - -----END CERTIFICATE----- -EOF ----- -<1> Optional. You can specify a different namespace in all the CRs. -<2> Specify the API endpoint of the RHV Manager, for example, `\"https://www.example.com:8443/ovirt-engine/api"` -<3> Specify the password for `admin@internal`. -<4> Specify the RHV Manager CA certificate. You can obtain the CA certificate by running the following command: -+ -[source,terminal] ----- -$ openssl s_client -connect :443 -showcerts < /dev/null ----- - -. Optional: Create a `ResourceMapping` CR if you want to separate the resource mapping from the `VirtualMachineImport` CR by running the following command: -+ -[source,yaml] ----- -$ cat <<EOF | kubectl create -f - -apiVersion: v2v.kubevirt.io/v1alpha1 -kind: ResourceMapping -metadata: - name: resourcemapping_example - namespace: default -spec: - ovirt: - networkMappings: - - source: - name: <rhv_logical_network>/<vnic_profile> <1> - target: - name: <target_network> <2> - type: pod - storageMappings: <3> - - source: - name: <rhv_storage_domain> <4> - target: - name: <target_storage_class> <5> - volumeMode: <volume_mode> <6> -EOF ----- -<1> Specify the RHV logical network and vNIC profile. -<2> Specify the {VirtProductName} network. -<3> If storage mappings are specified in both the `ResourceMapping` and the `VirtualMachineImport` CRs, the `VirtualMachineImport` CR takes precedence. -<4> Specify the RHV storage domain. -<5> Specify `nfs` or `ocs-storagecluster-ceph-rbd`. -<6> If you specified the `ocs-storagecluster-ceph-rbd` storage class, you must specify `Block` as the volume mode. -// For CNV 2.6.1 only. Will be fixed in CNV 2.6.2. -. If you specified NFS as the target storage class, you must run the following command because of a known issue (link:https://bugzilla.redhat.com/show_bug.cgi?id=1946177[*BZ#1946177*]): -+ -[source,terminal] ----- -$ oc patch cdi cdi-kubevirt-hyperconverged --type merge -p '{"spec": {"config": {"filesystemOverhead": {"global": "0"}}}}' ----- - -. Create the `VirtualMachineImport` CR by running the following command: -+ -[source,yaml] ----- -$ cat <<EOF | oc create -f - -apiVersion: v2v.kubevirt.io/v1beta1 -kind: VirtualMachineImport -metadata: - name: vm-import - namespace: default -spec: - providerCredentialsSecret: - name: rhv-credentials - namespace: default -# resourceMapping: <1> -# name: resourcemapping-example -# namespace: default - targetVmName: vm_example <2> - startVm: true - source: - ovirt: - vm: - id: <source_vm_id> <3> - name: <source_vm_name> <4> - cluster: - name: <source_cluster_name> <5> - mappings: <6> - networkMappings: - - source: - name: <source_logical_network>/<vnic_profile> <7> - target: - name: <target_network> <8> - type: pod - storageMappings: <9> - - source: - name: <source_storage_domain> <10> - target: - name: <target_storage_class> <11> - accessMode: <volume_access_mode> <12> - diskMappings: - - source: - id: <source_vm_disk_id> <13> - target: - name: <target_storage_class> <14> -EOF ----- -<1> If you create a `ResourceMapping` CR, uncomment the `resourceMapping` section. -<2> Specify the target VM name. -<3> Specify the source VM ID, for example, `80554327-0569-496b-bdeb-fcbbf52b827b`. You can obtain the VM ID by entering `\https://www.example.com/ovirt-engine/api/vms/` in a web browser on the Manager machine to list all VMs. Locate the VM you want to import and its corresponding VM ID. You do not need to specify a VM name or cluster name. -<4> If you specify the source VM name, you must also specify the source cluster. Do not specify the source VM ID. -<5> If you specify the source cluster, you must also specify the source VM name. Do not specify the source VM ID. -<6> If you create a `ResourceMapping` CR, comment out the `mappings` section. -<7> Specify the logical network and vNIC profile of the source VM. -<8> Specify the {VirtProductName} network. -<9> If storage mappings are specified in both the `ResourceMapping` and the `VirtualMachineImport` CRs, the `VirtualMachineImport` CR takes precedence. -<10> Specify the source storage domain. -<11> Specify the target storage class. -<12> Specify `ReadWriteOnce`, `ReadWriteMany`, or `ReadOnlyMany`. If no access mode is specified, {virt} determines the correct volume access mode based on the *Host* -> *Migration mode* setting of the RHV VM or on the virtual disk access mode: -* If the RHV VM migration mode is `Allow manual and automatic migration`, the default access mode is `ReadWriteMany`. -* If the RHV virtual disk access mode is `ReadOnly`, the default access mode is `ReadOnlyMany`. -* For all other settings, the default access mode is `ReadWriteOnce`. -<13> Specify the source VM disk ID, for example, `8181ecc1-5db8-4193-9c92-3ddab3be7b05`. You can obtain the disk ID by entering `\https://www.example.com/ovirt-engine/api/vms/vm23` in a web browser on the Manager machine and reviewing the VM details. -<14> Specify the target storage class. - -. Follow the progress of the virtual machine import to verify that the import was successful: -+ -[source,terminal] ----- -$ oc get vmimports vm-import -n default ----- -+ -The output indicating a successful import resembles the following example: -+ -.Example output -[source,yaml] ----- -... -status: - conditions: - - lastHeartbeatTime: "2020-07-22T08:58:52Z" - lastTransitionTime: "2020-07-22T08:58:52Z" - message: Validation completed successfully - reason: ValidationCompleted - status: "True" - type: Valid - - lastHeartbeatTime: "2020-07-22T08:58:52Z" - lastTransitionTime: "2020-07-22T08:58:52Z" - message: 'VM specifies IO Threads: 1, VM has NUMA tune mode specified: interleave' - reason: MappingRulesVerificationReportedWarnings - status: "True" - type: MappingRulesVerified - - lastHeartbeatTime: "2020-07-22T08:58:56Z" - lastTransitionTime: "2020-07-22T08:58:52Z" - message: Copying virtual machine disks - reason: CopyingDisks - status: "True" - type: Processing - dataVolumes: - - name: fedora32-b870c429-11e0-4630-b3df-21da551a48c0 - targetVmName: fedora32 ----- diff --git a/modules/virt-importing-vm-datavolume.adoc b/modules/virt-importing-vm-datavolume.adoc deleted file mode 100644 index bb1b707c661f..000000000000 --- a/modules/virt-importing-vm-datavolume.adoc +++ /dev/null @@ -1,150 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc - -[id="virt-importing-vm-datavolume_{context}"] -= Importing a virtual machine image into a persistent volume claim by using a data volume - -You can import a virtual machine image into a persistent volume claim (PVC) by using a data volume. - -The virtual machine image can be hosted at an HTTP or HTTPS endpoint, or the image can be built into a container disk and stored in a container registry. - -To create a virtual machine from an imported virtual machine image, specify the image or container disk endpoint in the `VirtualMachine` configuration file before you create the virtual machine. - -.Prerequisites - -* You have installed the OpenShift CLI (`oc`). -* Your cluster has at least one available persistent volume. -* To import a virtual machine image you must have the following: -** A virtual machine disk image in RAW, ISO, or QCOW2 format, optionally -compressed by using `xz` or `gz`. -** An HTTP endpoint where the image is hosted, along with any authentication -credentials needed to access the data source. For example: `http://www.example.com/path/to/data` -* To import a container disk you must have the following: -** A container disk built from a virtual machine image stored in your container image registry, along with any authentication credentials needed to access the data source. For example: `docker://registry.example.com/container-image` - -.Procedure - -. Optional: If your data source requires authentication credentials, edit the -`endpoint-secret.yaml` file, and apply the updated configuration to the cluster: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: <endpoint-secret> - labels: - app: containerized-data-importer -type: Opaque -data: - accessKeyId: "" <1> - secretKey: "" <2> ----- -<1> Optional: your key or user name, base64 encoded -<2> Optional: your secret or password, base64 encoded -+ -[source,terminal] ----- -$ oc apply -f endpoint-secret.yaml ----- - -. Edit the virtual machine configuration file, specifying the data source for -the virtual machine image you want to import. In this example, a Fedora image is imported from an `http` source: -+ -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachine -metadata: - creationTimestamp: null - labels: - kubevirt.io/vm: vm-fedora-datavolume - name: vm-fedora-datavolume -spec: - dataVolumeTemplates: - - metadata: - creationTimestamp: null - name: fedora-dv - spec: - pvc: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 10Gi - storageClassName: local - source: - http: <1> - url: "https://download.fedoraproject.org/pub/fedora/linux/releases/33/Cloud/x86_64/images/Fedora-Cloud-Base-33-1.2.x86_64.qcow2" <2> - secretRef: "" <3> - certConfigMap: "" <4> - status: {} - running: true - template: - metadata: - creationTimestamp: null - labels: - kubevirt.io/vm: vm-fedora-datavolume - spec: - domain: - devices: - disks: - - disk: - bus: virtio - name: datavolumedisk1 - machine: - type: "" <5> - resources: - requests: - memory: 1.5Gi - terminationGracePeriodSeconds: 60 - volumes: - - dataVolume: - name: fedora-dv - name: datavolumedisk1 -status: {} ----- -<1> The source type to import the image from. This example uses an HTTP endpoint. To import a container disk from a registry, replace `http` with `registry`. -<2> The source of the virtual machine image you want to import. This example references a virtual machine image at an HTTP endpoint. An example of a container registry endpoint is `url: "docker://kubevirt/fedora-cloud-container-disk-demo:latest"`. -<3> The `secretRef` parameter is optional. -<4> The `certConfigMap` is required for communicating with servers that use self-signed certificates or certificates not signed by the system CA bundle. The referenced config map must be in the same namespace as the data volume. -<5> Specify `type: dataVolume` or `type: ""`. If you specify any other value for `type`, such as `persistentVolumeClaim`, a warning is displayed, and the virtual machine does not start. - -. Create the virtual machine: -+ -[source,terminal] ----- -$ oc create -f vm-<name>-datavolume.yaml ----- -+ -[NOTE] -==== -The `oc create` command creates the data volume and the virtual machine. The CDI controller creates an underlying PVC with the correct annotation, and the import process begins. When the import completes, the data volume status changes to `Succeeded`, and the virtual machine is allowed to start. - -Data volume provisioning happens in the background, so there is no need to monitor it. You can start the virtual machine, and it will not run until the import is complete. -==== - -.Verification -. The importer pod downloads the virtual machine image or container disk from the specified URL and stores it on the provisioned PV. View the status of the importer pod by running the following command: -+ -[source,terminal] ----- -$ oc get pods ----- - -. Monitor the data volume status until it shows `Succeeded` by running the following command: -+ -[source,terminal] ----- -$ oc describe dv <datavolume-name> <1> ----- -<1> The name of the data volume as specified under `dataVolumeTemplates.metadata.name` in the virtual machine -configuration file. In the example configuration above, this is `fedora-dv`. - -. To verify that provisioning is complete and that the VMI has started, try accessing its serial console by running the following command: -+ -[source,terminal] ----- -$ virtctl console <vm-fedora-datavolume> ----- diff --git a/modules/virt-importing-vm-prerequisites.adoc b/modules/virt-importing-vm-prerequisites.adoc deleted file mode 100644 index 56d74b76bbb9..000000000000 --- a/modules/virt-importing-vm-prerequisites.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc - -[id="virt-importing-vm-prerequisites_{context}"] -= Prerequisites for importing a virtual machine - -Importing a virtual machine from Red Hat Virtualization (RHV) into {VirtProductName} has the following prerequisites: - -* You must have admin user privileges. -* Storage: -** The {VirtProductName} local and shared persistent storage classes must support VM import. -** If you are using Ceph RBD block-mode volumes, the storage must be large enough to accommodate the virtual disk. If the disk is too large for the available storage, the import process fails and the PV that is used to copy the virtual disk is not released. -** If you are using NFS storage, you must run the following command because of a known issue (link:https://bugzilla.redhat.com/show_bug.cgi?id=1946177[*BZ#1946177*]): -+ -[source,terminal] ----- -$ oc patch cdi cdi-kubevirt-hyperconverged --type merge -p '{"spec": {"config": {"filesystemOverhead": {"global": "0"}}}}' ----- -// remove for CNV 2.6.2 - -* Networks: -** The RHV and {VirtProductName} networks must either have the same name or be mapped to each other. -** The RHV VM network interface must be `e1000`, `rtl8139`, or `virtio`. - -* VM disks: -** The disk interface must be `sata`, `virtio_scsi`, or `virtio`. -** The disk must not be configured as a direct LUN. -** The disk status must not be `illegal` or `locked`. -** The storage type must be `image`. -** SCSI reservation must be disabled. -** `ScsiGenericIO` must be disabled. - -* VM configuration: -** If the VM uses GPU resources, the nodes providing the GPUs must be configured. -** The VM must not be configured for vGPU resources. -** The VM must not have snapshots with disks in an `illegal` state. -** The VM must not have been created with {product-title} and subsequently added to RHV. -** The VM must not be configured for USB devices. -** The watchdog model must not be `diag288`. diff --git a/modules/virt-importing-vm-to-block-pv.adoc b/modules/virt-importing-vm-to-block-pv.adoc deleted file mode 100644 index acb3b41bb704..000000000000 --- a/modules/virt-importing-vm-to-block-pv.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc - -[id="virt-importing-vm-to-block-pv_{context}"] -= Importing a virtual machine image to a block persistent volume using data volumes - -You can import an existing virtual machine image into your {product-title} cluster. {VirtProductName} uses data volumes to automate the importing data and the creation of an underlying persistent volume claim (PVC). You can then reference the data volume in a virtual machine manifest. - -.Prerequisites - -* A virtual machine disk image, in RAW, ISO, or QCOW2 format, optionally compressed by using `xz` or `gz`. -* An `HTTP` or `s3` endpoint where the image is hosted, along with any authentication credentials needed to access the data source -* At least one available block PV. - -.Procedure - -. If your data source requires authentication credentials, edit the `endpoint-secret.yaml` file, and apply the updated configuration to the cluster. - -.. Edit the `endpoint-secret.yaml` file with your preferred text editor: -+ -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: <endpoint-secret> - labels: - app: containerized-data-importer -type: Opaque -data: - accessKeyId: "" <1> - secretKey: "" <2> ----- -<1> Optional: your key or user name, base64 encoded -<2> Optional: your secret or password, base64 encoded - -.. Update the secret by running the following command: -+ -[source,terminal] ----- -$ oc apply -f endpoint-secret.yaml ----- - -. Create a `DataVolume` manifest that specifies the data source for the image you want to import and `volumeMode: Block` so that an available block PV is used. -+ -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: <import-pv-datavolume> <1> -spec: - storageClassName: local <2> - source: - http: - url: <http://download.fedoraproject.org/pub/fedora/linux/releases/28/Cloud/x86_64/images/Fedora-Cloud-Base-28-1.1.x86_64.qcow2> <3> - secretRef: <endpoint-secret> <4> - pvc: - volumeMode: Block <5> - accessModes: - - ReadWriteOnce - resources: - requests: - storage: <2Gi> ----- -<1> The name of the data volume. -<2> Optional: Set the storage class or omit it to accept the cluster default. -<3> The `HTTP` source of the image to import. -<4> Only required if the data source requires authentication. -<5> Required for importing to a block PV. - -. Create the data volume to import the virtual machine image by running the following command: -+ -[source,terminal] ----- -$ oc create -f <import-pv-datavolume.yaml><1> ----- -<1> The file name of the data volume that you created in the previous step. - diff --git a/modules/virt-importing-vm-wizard.adoc b/modules/virt-importing-vm-wizard.adoc deleted file mode 100644 index bd62a1b8bcce..000000000000 --- a/modules/virt-importing-vm-wizard.adoc +++ /dev/null @@ -1,158 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc - -[id="virt-importing-vm-wizard_{context}"] -= Importing a virtual machine with the VM Import wizard - -You can import a single virtual machine with the VM Import wizard. - -ifdef::virt-importing-vmware-vm[] -You can also import a VM template. If you import a VM template, {VirtProductName} creates a virtual machine based on the template. - -.Prerequisites - -* You must have admin user privileges. -* The VMware Virtual Disk Development Kit (VDDK) image must be in an image registry that is accessible to your {VirtProductName} environment. -* The VDDK image must be added to the `v2v-vmware` config map. -* The VM must be powered off. -* Virtual disks must be connected to IDE or SCSI controllers. If virtual disks are connected to a SATA controller, you can change them to IDE controllers and then migrate the VM. -* The {VirtProductName} local and shared persistent storage classes must support VM import. -* The {VirtProductName} storage must be large enough to accommodate the virtual disk. -+ -[WARNING] -==== -If you are using Ceph RBD block-mode volumes, the storage must be large enough to accommodate the virtual disk. If the disk is too large for the available storage, the import process fails and the PV that is used to copy the virtual disk is not released. You will not be able to import another virtual machine or to clean up the storage because there are insufficient resources to support object deletion. To resolve this situation, you must add more object storage devices to the storage back end. -==== - -* The {VirtProductName} egress network policy must allow the following traffic: -+ -[cols="1,1,1" options="header"] -|=== -|Destination |Protocol |Port -|VMware ESXi hosts |TCP |443 -|VMware ESXi hosts |TCP |902 -|VMware vCenter |TCP |5840 -|=== -endif::[] - -.Procedure - -. In the web console, click *Workloads* -> *Virtual Machines*. -. Click *Create Virtual Machine* and select *Import with Wizard*. -ifdef::virt-importing-vmware-vm[] -. Select *VMware* from the *Provider* list. -. Select *Connect to New Instance* or a saved vCenter instance. - -* If you select *Connect to New Instance*, enter the *vCenter hostname*, *Username*, and *Password*. -* If you select a saved vCenter instance, the wizard connects to the vCenter instance using the saved credentials. - -. Click *Check and Save* and wait for the connection to complete. -+ -[NOTE] -==== -The connection details are stored in a secret. If you add a provider with an incorrect host name, user name, or password, click *Workloads* -> *Secrets* and delete the provider secret. -==== - -. Select a virtual machine or a template. -endif::[] -ifdef::virt-importing-rhv-vm[] -. Select *Red Hat Virtualization (RHV)* from the *Provider* list. -. Select *Connect to New Instance* or a saved RHV instance. - -* If you select *Connect to New Instance*, fill in the following fields: - -** *API URL*: For example, `\https://<RHV_Manager_FQDN>/ovirt-engine/api` -** *CA certificate*: Click *Browse* to upload the RHV Manager CA certificate or paste the CA certificate into the field. -+ -View the CA certificate by running the following command: -+ -[source,terminal] ----- -$ openssl s_client -connect <RHV_Manager_FQDN>:443 -showcerts < /dev/null ----- -+ -The CA certificate is the second certificate in the output. - -** *Username*: RHV Manager user name, for example, `admin@internal` -** *Password*: RHV Manager password - -* If you select a saved RHV instance, the wizard connects to the RHV instance using the saved credentials. - -. Click *Check and Save* and wait for the connection to complete. -+ -[NOTE] -==== -The connection details are stored in a secret. If you add a provider with an incorrect URL, user name, or password, click *Workloads* -> *Secrets* and delete the provider secret. -==== - -. Select a cluster and a virtual machine. -endif::[] -. Click *Next*. -. In the *Review* screen, review your settings. -// RHV import options -ifdef::virt-importing-rhv-vm[] -. Optional: You can select *Start virtual machine on creation*. -endif::[] - -. Click *Edit* to update the following settings: - -ifdef::virt-importing-rhv-vm[] -* *General* -> *Name*: The VM name is limited to 63 characters. -* *General* -> *Description*: Optional description of the VM. -** *Storage Class*: Select *NFS* or *ocs-storagecluster-ceph-rbd*. -+ -If you select *ocs-storagecluster-ceph-rbd*, you must set the *Volume Mode* of the disk to *Block*. -+ -If you select *NFS*, you must run the following command on the CLI because of a known issue (link:https://bugzilla.redhat.com/show_bug.cgi?id=1946177[*BZ#1946177*]): -+ -[source,terminal] ----- -$ oc patch cdi cdi-kubevirt-hyperconverged --type merge -p '{"spec": {"config": {"filesystemOverhead": {"global": "0"}}}}' ----- -// remove this step for CNV 2.6.2 - -** *Advanced* -> *Volume Mode*: Select *Block*. -* *Advanced* -> *Volume Mode*: Select *Block*. -* *Networking* -> *Network*: You can select a network from a list of available network attachment definition objects. -endif::[] -ifdef::virt-importing-vmware-vm[] -* *General*: -** *Description* -** *Operating System* -** *Flavor* -** *Memory* -** *CPUs* -** *Workload Profile* - -* *Networking*: -** *Name* -** *Model* -** *Network* -** *Type*: You must select the `masquerade` binding method. -** *MAC Address* - -* *Storage*: Click the Options menu {kebab} of the VM disk and select *Edit* to update the following fields: -** *Name* -** *Source*: For example, *Import Disk*. -** *Size* -** *Interface* -** *Storage Class*: Select *NFS* or *ocs-storagecluster-ceph-rbd (ceph-rbd)*. -+ -If you select *ocs-storagecluster-ceph-rbd*, you must set the *Volume Mode* of the disk to *Block*. -+ -Other storage classes might work, but they are not officially supported. - -** *Advanced* -> *Volume Mode*: Select *Block*. -** *Advanced* -> *Access Mode* - -* *Advanced* -> *Cloud-init*: -** *Form*: Enter the *Hostname* and *Authenticated SSH Keys*. -** *Custom script*: Enter the `cloud-init` script in the text field. - -* *Advanced* -> *Virtual Hardware*: You can attach a virtual CD-ROM to the imported virtual machine. -endif::[] -. Click *Import* or *Review and Import*, if you have edited the import settings. -+ -A *Successfully created virtual machine* message and a list of resources created for the virtual machine are displayed. The virtual machine appears in *Workloads* -> *Virtual Machines*. diff --git a/modules/virt-initiating-vm-migration-cli.adoc b/modules/virt-initiating-vm-migration-cli.adoc deleted file mode 100644 index d329ec6c2a0b..000000000000 --- a/modules/virt-initiating-vm-migration-cli.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-migrate-vmi.adoc - -[id="virt-initiating-vm-migration-cli_{context}"] -= Initiating live migration of a virtual machine instance in the CLI - -Initiate a live migration of a running virtual machine instance by creating a `VirtualMachineInstanceMigration` object in the cluster and referencing the name of the virtual machine instance. - -.Procedure - -. Create a `VirtualMachineInstanceMigration` configuration file for the virtual machine instance to migrate. For example, `vmi-migrate.yaml`: -+ -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachineInstanceMigration -metadata: - name: migration-job -spec: - vmiName: vmi-fedora ----- - -. Create the object in the cluster by running the following command: -+ -[source,terminal] ----- -$ oc create -f vmi-migrate.yaml ----- - -The `VirtualMachineInstanceMigration` object triggers a live migration of the virtual machine instance. -This object exists in the cluster for as long as the virtual machine instance is running, unless manually deleted. diff --git a/modules/virt-initiating-vm-migration-web.adoc b/modules/virt-initiating-vm-migration-web.adoc deleted file mode 100644 index 3bcba0460531..000000000000 --- a/modules/virt-initiating-vm-migration-web.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-migrate-vmi.adoc - -[id="virt-initiating-vm-migration-web_{context}"] -= Initiating live migration of a virtual machine instance in the web console - -Migrate a running virtual machine instance to a different node in the cluster. - -[NOTE] -==== -The *Migrate Virtual Machine* action is visible to all users but only admin users -can initiate a virtual machine migration. -==== - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. You can initiate the migration from this screen, which makes it easier to -perform actions on multiple virtual machines in the one screen, or from the -*Virtual Machine Overview* screen where you can view comprehensive details of the -selected virtual machine: -** Click the Options menu {kebab} at the end of virtual machine and select -*Migrate Virtual Machine*. -** Click the virtual machine name to open the *Virtual Machine Overview* -screen and click *Actions* -> *Migrate Virtual Machine*. -. Click *Migrate* to migrate the virtual machine to another node. diff --git a/modules/virt-installing-qemu-guest-agent-on-linux-vm.adoc b/modules/virt-installing-qemu-guest-agent-on-linux-vm.adoc deleted file mode 100644 index cd3a3af08682..000000000000 --- a/modules/virt-installing-qemu-guest-agent-on-linux-vm.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-installing-qemu-guest-agent.adoc - -[id="virt-installing-qemu-guest-agent-on-linux-vm_{context}"] -= Installing QEMU guest agent on a Linux virtual machine - -The `qemu-guest-agent` is widely available and available by default in Red Hat -virtual machines. Install the agent and start the service - -.Procedure - -. Access the virtual machine command line through one of the consoles or by SSH. - -. Install the QEMU guest agent on the virtual machine: -+ -[source,terminal] ----- -$ yum install -y qemu-guest-agent ----- - -. Ensure the service is persistent and start it: -+ -[source,terminal] ----- -$ systemctl enable --now qemu-guest-agent ----- diff --git a/modules/virt-installing-qemu-guest-agent-on-windows-vm.adoc b/modules/virt-installing-qemu-guest-agent-on-windows-vm.adoc deleted file mode 100644 index e4676f273d15..000000000000 --- a/modules/virt-installing-qemu-guest-agent-on-windows-vm.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-installing-qemu-guest-agent.adoc - -[id="installing-qemu-guest-agent-on-a-windows-virtual-machine"] -= Installing QEMU guest agent on a Windows virtual machine - -For Windows virtual machines, the QEMU guest agent is included in the -VirtIO drivers, which can be installed using one of the following procedures: diff --git a/modules/virt-installing-virt-operator.adoc b/modules/virt-installing-virt-operator.adoc deleted file mode 100644 index 7a2c9a444c75..000000000000 --- a/modules/virt-installing-virt-operator.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/installing-virt-web.adoc - -[id="virt-installing-virt-operator_{context}"] -= Installing the {VirtProductName} Operator - -You can install the {VirtProductName} Operator from the {product-title} web console. - -.Prerequisites - -* Install {product-title} {product-version} on your cluster. -* Log in to the {product-title} web console as a user with `cluster-admin` permissions. - -.Procedure - -. Open a browser window and log in to the {product-title} web console. - -. From the *Administrator* perspective, click *Operators* -> *OperatorHub*. - -. In the *Filter by keyword* field, type *{VirtProductName}*. - -. Select the *{VirtProductName}* tile. - -. Read the information about the Operator and click *Install*. - -. On the *Install Operator* page: - -.. Select *stable* from the list of available *Update Channel* options. This ensures that: -* You install the version of {VirtProductName} that is compatible with your {product-title} version. -* When you update {product-title}, {VirtProductName} automatically updates to the next minor version. - -.. For *Installed Namespace*, ensure that the *Operator recommended namespace* option is selected. This installs the Operator in the mandatory `openshift-cnv` namespace, which is automatically created if it does not exist. -+ -[WARNING] -==== -Attempting to install the {VirtProductName} Operator in a namespace other than `openshift-cnv` causes the installation to fail. -==== - -.. For *Approval Strategy*, ensure that *Automatic*, which is the default value, is selected. {VirtProductName} automatically updates when a new z-stream release is available. - -. Click *Install* to make the Operator available to the `openshift-cnv` namespace. - -. When the Operator installs successfully, click *Create HyperConverged*. - -. Optional: Configure *Infra* and *Workloads* node placement options for {VirtProductName} components. - -. Click *Create* to launch {VirtProductName}. - -.Verification - -* Navigate to the *Workloads* -> *Pods* page and monitor the {VirtProductName} pods until they are all *Running*. After all the pods display the *Running* state, you can use {VirtProductName}. \ No newline at end of file diff --git a/modules/virt-installing-virtctl-client-web.adoc b/modules/virt-installing-virtctl-client-web.adoc deleted file mode 100644 index 2bd6daf13100..000000000000 --- a/modules/virt-installing-virtctl-client-web.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// virt/install/virt-installing-virtctl.adoc - -[id="virt-installing-virtctl-client-web_{context}"] -= Installing the `virtctl` client from the web console - -You can download the `virtctl` client from the Red Hat Customer Portal, which is linked to in your {VirtProductName} web console in the *Command Line Tools* page. - -.Prerequisites - -* You must have an activated {product-title} subscription to access the download page on the Customer Portal. - -.Procedure - -. Access the Customer Portal by clicking the image:question-circle.png[title="Help"] icon, which is in the upper-right corner of the web console, and selecting *Command Line Tools*. - -. Ensure you have the appropriate version for your cluster selected from the *Version:* list. - -. Download the `virtctl` client for your distribution. All downloads are in `tar.gz` format. - -. Extract the tarball. The following CLI command extracts it into the same directory as the tarball and is applicable for all distributions: -+ -[source,terminal] ----- -$ tar -xvf <virtctl-version-distribution.arch>.tar.gz ----- - -. For Linux and macOS: - -.. Navigate the extracted folder hierachy and make the `virtctl` binary executable: -+ -[source,terminal] ----- -$ chmod +x <virtctl-file-name> ----- - -.. Move the `virtctl` binary to a directory on your PATH. - -... To check your path, run: -+ -[source,terminal] ----- -$ echo $PATH ----- - -. For Windows users: - -.. Navigate the extracted folder hierarchy and double-click the `virtctl` executable file to install the client. diff --git a/modules/virt-installing-virtctl-client.adoc b/modules/virt-installing-virtctl-client.adoc deleted file mode 100644 index 87fc3769c247..000000000000 --- a/modules/virt-installing-virtctl-client.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// virt/install/virt-installing-virtctl.adoc - -[id="virt-installing-virtctl-client_{context}"] -= Installing the `virtctl` client - -Install the `virtctl` client from the `kubevirt-virtctl` package. - -.Procedure - -* Install the `kubevirt-virtctl` package: -+ -[source,terminal] ----- -# yum install kubevirt-virtctl ----- diff --git a/modules/virt-installing-virtio-drivers-existing-windows.adoc b/modules/virt-installing-virtio-drivers-existing-windows.adoc deleted file mode 100644 index 0ba9fc06d06a..000000000000 --- a/modules/virt-installing-virtio-drivers-existing-windows.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-installing-qemu-guest-agent.adoc -// * virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc - -[id="virt-installing-virtio-drivers-existing-windows_{context}"] -= Installing VirtIO drivers on an existing Windows virtual machine - -Install the VirtIO drivers from the attached SATA CD drive to an -existing Windows virtual machine. - -[NOTE] -==== -This procedure uses a generic approach to adding drivers to Windows. -The process might differ slightly between versions of Windows. -Refer to the installation documentation for your version of Windows -for specific installation steps. -==== - -.Procedure - -. Start the virtual machine and connect to a graphical console. -. Log in to a Windows user session. -. Open *Device Manager* and expand *Other devices* to list any *Unknown device*. -.. Open the `Device Properties` to identify the unknown device. -Right-click the device and select *Properties*. -.. Click the *Details* tab and select *Hardware Ids* in the *Property* list. -.. Compare the *Value* for the *Hardware Ids* with the supported VirtIO drivers. -. Right-click the device and select *Update Driver Software*. -. Click *Browse my computer for driver software* and browse to the attached -SATA CD drive, where the VirtIO drivers are located. The drivers are arranged -hierarchically according to their driver type, operating system, -and CPU architecture. -. Click *Next* to install the driver. -. Repeat this process for all the necessary VirtIO drivers. -. After the driver installs, click *Close* to close the window. -. Reboot the virtual machine to complete the driver installation. diff --git a/modules/virt-installing-virtio-drivers-installing-windows.adoc b/modules/virt-installing-virtio-drivers-installing-windows.adoc deleted file mode 100644 index ed5989cccc43..000000000000 --- a/modules/virt-installing-virtio-drivers-installing-windows.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-installing-qemu-guest-agent.adoc -// * virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc - -[id="virt-installing-virtio-drivers-installing-windows_{context}"] -= Installing VirtIO drivers during Windows installation - -Install the VirtIO drivers from the attached SATA CD driver during Windows installation. - -[NOTE] -==== -This procedure uses a generic approach to the Windows installation and the -installation method might differ between versions of Windows. Refer to the -documentation for the version of Windows that you are installing. -==== - -.Procedure - -. Start the virtual machine and connect to a graphical console. -. Begin the Windows installation process. -. Select the *Advanced* installation. -. The storage destination will not be recognized until the driver is loaded. -Click `Load driver`. -. The drivers are attached as a SATA CD drive. Click *OK* and browse the CD drive - for the storage driver to load. The drivers are arranged hierarchically -according to their driver type, operating system, and CPU architecture. -. Repeat the previous two steps for all required drivers. -. Complete the Windows installation. diff --git a/modules/virt-listing-dvs.adoc b/modules/virt-listing-dvs.adoc deleted file mode 100644 index 44e59778156d..000000000000 --- a/modules/virt-listing-dvs.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-deleting-datavolumes.adoc - -[id="virt-listing-dvs_{context}"] - -= Listing all data volumes - -You can list the data volumes in your cluster by using the `oc` command-line interface. - -.Procedure - -* List all data volumes by running the following command: -+ -[source,terminal] ----- -$ oc get dvs ----- diff --git a/modules/virt-listing-vmis-cli.adoc b/modules/virt-listing-vmis-cli.adoc deleted file mode 100644 index 4b8c4af06a7e..000000000000 --- a/modules/virt-listing-vmis-cli.adoc +++ /dev/null @@ -1,19 +0,0 @@ - -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-manage-vmis.adoc -// * virt/virtual_machines/virt-triggering-vm-failover-resolving-failed-node.adoc - -[id="virt-listing-vmis-cli_{context}"] -= Listing all virtual machine instances using the CLI - -You can list all virtual machine instances (VMIs) in your cluster, including standalone VMIs and those owned by virtual machines, by using the `oc` command-line interface (CLI). - -.Procedure - -* List all VMIs by running the following command: -+ -[source,terminal] ----- -$ oc get vmis ----- diff --git a/modules/virt-listing-vmis-web.adoc b/modules/virt-listing-vmis-web.adoc deleted file mode 100644 index 4dfde2d8b74d..000000000000 --- a/modules/virt-listing-vmis-web.adoc +++ /dev/null @@ -1,19 +0,0 @@ - -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-manage-vmis-web.adoc - -[id="virt-listing-vmis-web_{context}"] -= Listing standalone virtual machine instances using the web console - -Using the web console, you can list and view standalone virtual machine instances (VMIs) in your cluster that are not owned by virtual machines (VMs). - -[NOTE] -==== -VMIs that are owned by VMs or other objects are not displayed in the web console. The web console displays only standalone VMIs. If you want to list all VMIs in your cluster, you must use the CLI. -==== - - -.Procedure - -* Click *Workloads -> Virtualization* from the side menu. A list of VMs and standalone VMIs displays. You can identify standalone VMIs by the dark colored badges that display next to the virtual machine instance names. diff --git a/modules/virt-live-migration-limits-reftable.adoc b/modules/virt-live-migration-limits-reftable.adoc deleted file mode 100644 index df3caef1632b..000000000000 --- a/modules/virt-live-migration-limits-reftable.adoc +++ /dev/null @@ -1,38 +0,0 @@ - -// Module included in the following assemblies: -// -// * virt/live_migration/virt-live-migration-limits.adoc - -[id="virt-live-migration-limits-ref_{context}"] -= Cluster-wide live migration limits and timeouts - -[caption=] -.Migration parameters -[cols="2,3,1"] -|=== -|Parameter |Description |Default - -|`parallelMigrationsPerCluster` -|Number of migrations running in parallel in the cluster. -|5 - -|`parallelOutboundMigrationsPerNode` -|Maximum number of outbound migrations per node. -|2 - -|`bandwidthPerMigration` -|Bandwidth limit of each migration, in MiB/s. -|64Mi - -|`completionTimeoutPerGiB` -|The migration is canceled if it has not completed in this time, in seconds -per GiB of memory. For example, a virtual machine instance with 6GiB memory times out if it has -not completed migration in 4800 seconds. If the `Migration Method` is -`BlockMigration`, the size of the migrating disks is included in the calculation. -|800 - -|`progressTimeout` -|The migration is canceled if memory copy fails to make progress in this -time, in seconds. -|150 -|=== diff --git a/modules/virt-marking-vm-templates-favorites.adoc b/modules/virt-marking-vm-templates-favorites.adoc deleted file mode 100644 index 82d39616de93..000000000000 --- a/modules/virt-marking-vm-templates-favorites.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-marking-vm-templates-favorites_{context}"] -= Marking virtual machine templates as favorites - -For easier access to virtual machine templates that are used frequently, you can mark those templates as favorites. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Templates* tab. -. Identify the Red Hat template that you want to mark as a favorite. -. Click the Options menu {kebab} and select *Favorite template*. The template moves up higher in the list of displayed templates. diff --git a/modules/virt-monitoring-upgrade-status.adoc b/modules/virt-monitoring-upgrade-status.adoc deleted file mode 100644 index be9095adbb09..000000000000 --- a/modules/virt-monitoring-upgrade-status.adoc +++ /dev/null @@ -1,61 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/upgrading-virt.adoc - -[id="virt-monitoring-upgrade-status_{context}"] -= Monitoring upgrade status - -The best way to monitor {VirtProductName} upgrade status is to watch the -cluster service version (CSV) `PHASE`. You can also monitor the CSV conditions -in the web console or by running the command provided here. - -[NOTE] -==== -The `PHASE` and conditions values are approximations that are based on -available information. -==== - -.Prerequisites - -* Log in to the cluster as a user with the `cluster-admin` role. -* Install the OpenShift CLI (`oc`). - -.Procedure - -. Run the following command: -+ -[source,terminal] ----- -$ oc get csv ----- - -. Review the output, checking the `PHASE` field. For example: -+ -.Example output -[source,terminal,subs="attributes+"] ----- -VERSION REPLACES PHASE -2.5.0 kubevirt-hyperconverged-operator.v2.4.3 Installing -2.4.3 Replacing ----- - -. Optional: Monitor the aggregated status of all {VirtProductName} component -conditions by running the following command: -+ -[source,terminal] ----- -$ oc get hco -n openshift-cnv kubevirt-hyperconverged \ --o=jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.message}{"\n"}{end}' ----- -+ -A successful upgrade results in the following output: -+ -.Example output -[source,terminal] ----- -ReconcileComplete True Reconcile completed successfully -Available True Reconcile completed successfully -Progressing False Reconcile completed successfully -Degraded False Reconcile completed successfully -Upgradeable True Reconcile completed successfully ----- diff --git a/modules/virt-monitoring-vm-migration-cli.adoc b/modules/virt-monitoring-vm-migration-cli.adoc deleted file mode 100644 index d3f567f73c8b..000000000000 --- a/modules/virt-monitoring-vm-migration-cli.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-monitor-vmi-migration.adoc - -[id="virt-monitoring-vm-migration-cli_{context}"] -= Monitoring live migration of a virtual machine instance in the CLI - -The status of the virtual machine migration is stored in the `Status` component of the `VirtualMachineInstance` configuration. - -.Procedure - -* Use the `oc describe` command on the migrating virtual machine instance: -+ -[source,terminal] ----- -$ oc describe vmi vmi-fedora ----- -+ -.Example output -[source,yaml] ----- -... -Status: - Conditions: - Last Probe Time: <nil> - Last Transition Time: <nil> - Status: True - Type: LiveMigratable - Migration Method: LiveMigration - Migration State: - Completed: true - End Timestamp: 2018-12-24T06:19:42Z - Migration UID: d78c8962-0743-11e9-a540-fa163e0c69f1 - Source Node: node2.example.com - Start Timestamp: 2018-12-24T06:19:35Z - Target Node: node1.example.com - Target Node Address: 10.9.0.18:43891 - Target Node Domain Detected: true ----- diff --git a/modules/virt-monitoring-vm-migration-web.adoc b/modules/virt-monitoring-vm-migration-web.adoc deleted file mode 100644 index f10038582172..000000000000 --- a/modules/virt-monitoring-vm-migration-web.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-monitor-vmi-migration.adoc - -[id="virt-monitoring-vm-migration-web_{context}"] -= Monitoring live migration of a virtual machine instance in the web console - -For the duration of the migration, the virtual machine has a status of -*Migrating*. This status is displayed in the *Virtual Machines* tab or in the -*Virtual Machine Overview* screen for the migrating virtual machine. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a virtual machine to open the *Virtual Machine Overview* screen. diff --git a/modules/virt-networking-glossary.adoc b/modules/virt-networking-glossary.adoc deleted file mode 100644 index 9bdc3d9f9c7b..000000000000 --- a/modules/virt-networking-glossary.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-configuring-pxe-booting.adoc -// * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc - -[id="virt-networking-glossary_{context}"] -= {VirtProductName} networking glossary - -{VirtProductName} provides advanced networking functionality by using custom resources and plug-ins. - -The following terms are used throughout {VirtProductName} documentation: - -Container Network Interface (CNI):: a link:https://www.cncf.io/[Cloud Native Computing Foundation] -project, focused on container network connectivity. -{VirtProductName} uses CNI plug-ins to build upon the basic Kubernetes networking functionality. - -Multus:: a "meta" CNI plug-in that allows multiple CNIs to exist so that a pod or virtual machine can use the interfaces it needs. - -Custom resource definition (CRD):: a link:https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[Kubernetes] -API resource that allows you to define custom resources, or an object defined by using the CRD API resource. - -Network attachment definition:: a CRD introduced by the Multus project that allows you to attach pods, virtual machines, and virtual machine instances to one or more networks. - -Preboot eXecution Environment (PXE):: an interface that enables an administrator to boot a client machine from a server over the network. -Network booting allows you to remotely load operating systems and other software onto the client. diff --git a/modules/virt-networking-wizard-fields-web.adoc b/modules/virt-networking-wizard-fields-web.adoc deleted file mode 100644 index 58e41fd21cbc..000000000000 --- a/modules/virt-networking-wizard-fields-web.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc -// * virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc -// * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-networking-wizard-fields-web_{context}"] -= Networking fields - -|=== -|Name | Description - -|Name -|Name for the network interface card. - -|Model -|Indicates the model of the network interface card. Supported values are *e1000e* and *virtio*. - -|Network -|List of available network attachment definitions. - -|Type -|List of available binding methods. For the default pod network, `masquerade` is the only recommended binding method. For secondary networks, use the `bridge` binding method. The `masquerade` method is not supported for non-default networks. Select `SR-IOV` if you configured an SR-IOV network device and defined that network in the namespace. - -|MAC Address -|MAC address for the network interface card. If a MAC address is not specified, an ephemeral address is generated for the session. -|=== diff --git a/modules/virt-openshift-client-commands.adoc b/modules/virt-openshift-client-commands.adoc deleted file mode 100644 index c5f5215d9129..000000000000 --- a/modules/virt-openshift-client-commands.adoc +++ /dev/null @@ -1,38 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virt-using-the-cli-tools.adoc - -[id="virt-openshift-client-commands_{context}"] -= {product-title} client commands - -The {product-title} `oc` client is a command-line utility for managing -{product-title} resources, including the `VirtualMachine` (`vm`) and `VirtualMachineInstance` (`vmi`) object types. + -[NOTE] -==== -You can use the `-n <namespace>` flag to specify a different project. -==== - -.`oc` commands - -[width="100%",cols="42%,58%",options="header",] -|=== -|Command |Description - -|`oc login -u <user_name>` -|Log in to the {product-title} cluster as `<user_name>`. - -|`oc get <object_type>` -|Display a list of objects for the specified object type in the current project. - -|`oc describe <object_type> <resource_name>` -|Display details of the specific resource in the current project. - -|`oc create -f <object_config>` -|Create a resource in the current project from a file name or from stdin. - -|`oc edit <object_type> <resource_name>` -|Edit a resource in the current project. - -|`oc delete <object_type> <resource_name>` -|Delete a resource in the current project. -|=== diff --git a/modules/virt-operations-requiring-scratch-space.adoc b/modules/virt-operations-requiring-scratch-space.adoc deleted file mode 100644 index c5354e788ebb..000000000000 --- a/modules/virt-operations-requiring-scratch-space.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc - -[id="virt-operations-requiring-scratch-space_{context}"] -= CDI operations that require scratch space - -[options="header"] -|=== -| Type | Reason - -| Registry imports -| CDI must download the image to a scratch space and extract the layers to find the image file. The image file is then passed to QEMU-IMG for conversion to a raw disk. - -| Upload image -| QEMU-IMG does not accept input from STDIN. Instead, the image to upload is saved in scratch space before it can be passed to QEMU-IMG for conversion. - -| HTTP imports of archived images -| QEMU-IMG does not know how to handle the archive formats CDI supports. Instead, the image is unarchived and saved into scratch space before it is passed to QEMU-IMG. - -| HTTP imports of authenticated images -| QEMU-IMG inadequately handles authentication. Instead, the image is saved to scratch space and authenticated before it is passed to QEMU-IMG. - -| HTTP imports of custom certificates -| QEMU-IMG inadequately handles custom certificates of HTTPS endpoints. Instead, CDI downloads the image to scratch space before passing the file to QEMU-IMG. -|=== diff --git a/modules/virt-overriding-default-fs-overhead-value.adoc b/modules/virt-overriding-default-fs-overhead-value.adoc deleted file mode 100644 index 91e166ad4d71..000000000000 --- a/modules/virt-overriding-default-fs-overhead-value.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-reserving-pvc-space-fs-overhead.adoc - -[id="virt-overriding-default-fs-overhead-value_{context}"] -= Overriding the default file system overhead value - -Change the amount of persistent volume claim (PVC) space that the Containerized Data Importer (CDI) reserves for file system overhead by editing the `spec.config.filesystemOverhead` attribute of the `CDI` object. - -.Prerequisites - -* Install the OpenShift CLI (`oc`). - -.Procedure - -. Open the `CDI` object for editing by running the following command: -+ -[source,terminal] ----- -$ oc edit cdi ----- - -. Edit the `spec.config.filesystemOverhead` fields, populating them with your chosen values: -+ -[source,yaml] ----- -... -spec: - config: - filesystemOverhead: - global: "<new_global_value>" <1> - storageClass: - <storage_class_name>: "<new_value_for_this_storage_class>" <2> ----- -<1> The file system overhead percentage that CDI uses across the cluster. For example, `global: "0.07"` reserves 7% of the PVC for file system overhead. -<2> The file system overhead percentage for the specified storage class. For example, `mystorageclass: "0.04"` changes the default overhead value for PVCs in the `mystorageclass` storage class to 4%. - -. Save and exit the editor to update the `CDI` object. - -.Verification - -* View the `CDI` status and verify your changes by running the following command: -+ -[source,terminal] ----- -$ oc get cdi -o yaml ----- diff --git a/modules/virt-preparing-container-disk-for-vms.adoc b/modules/virt-preparing-container-disk-for-vms.adoc deleted file mode 100644 index e060dedc699a..000000000000 --- a/modules/virt-preparing-container-disk-for-vms.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc - -[id="virt-preparing-container-disk-for-vms_{context}"] -= Preparing a container disk for virtual machines - -You must build a container disk with a virtual machine image and push it to a container registry before it can used with a virtual machine. You can then either import the container disk into a PVC using a data volume and attach it to a virtual machine, or you can attach the container disk directly to a virtual machine as an ephemeral `containerDisk` volume. - -.Prerequisites - -* Install `podman` if it is not already installed. - -* The virtual machine image must be either QCOW2 or RAW format. - -.Procedure - -. Create a Dockerfile to build the virtual machine image into a container image. The virtual machine image must be owned by QEMU, which has a UID of `107`, and placed in the `/disk/` directory inside the container. Permissions for the `/disk/` directory must then be set to `0440`. -+ -The following example uses the Red Hat Universal Base Image (UBI) to handle these configuration changes in the first stage, and uses the minimal `scratch` image in the second stage to store the result: -+ -[source,terminal] ----- -$ cat > Dockerfile << EOF -FROM registry.access.redhat.com/ubi8/ubi:latest AS builder -ADD --chown=107:107 <vm_image>.qcow2 /disk/ <1> -RUN chmod 0440 /disk/* - -FROM scratch -COPY --from=builder /disk/* /disk/ -EOF ----- -<1> Where <vm_image> is the virtual machine image in either QCOW2 or RAW format. + -To use a remote virtual machine image, replace `<vm_image>.qcow2` with the complete url for the remote image. - -. Build and tag the container: -+ -[source,terminal] ----- -$ podman build -t <registry>/<container_disk_name>:latest . ----- - -. Push the container image to the registry: -+ -[source,terminal] ----- -$ podman push <registry>/<container_disk_name>:latest ----- diff --git a/modules/virt-pxe-booting-with-mac-address.adoc b/modules/virt-pxe-booting-with-mac-address.adoc deleted file mode 100644 index 981a15f18221..000000000000 --- a/modules/virt-pxe-booting-with-mac-address.adoc +++ /dev/null @@ -1,163 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-configuring-pxe-booting.adoc - -[id="virt-pxe-booting-with-mac-address_{context}"] -= PXE booting with a specified MAC address - -As an administrator, you can boot a client over the network by first creating a `NetworkAttachmentDefinition` object for your PXE network. -Then, reference the network attachment definition in your virtual machine instance configuration file before you start the virtual machine instance. -You can also specify a MAC address in the virtual machine instance configuration file, if required by the PXE server. - -.Prerequisites - -* A Linux bridge must be connected. -* The PXE server must be connected to the same VLAN as the bridge. - -.Procedure - -. Configure a PXE network on the cluster: - -.. Create the network attachment definition file for PXE network `pxe-net-conf`: -+ -[source,yaml] ----- -apiVersion: "k8s.cni.cncf.io/v1" -kind: NetworkAttachmentDefinition -metadata: - name: pxe-net-conf -spec: - config: '{ - "cniVersion": "0.3.1", - "name": "pxe-net-conf", - "plugins": [ - { - "type": "cnv-bridge", - "bridge": "br1", - "vlan": 1 <1> - }, - { - "type": "cnv-tuning" <2> - } - ] - }' ----- -<1> Optional: The VLAN tag. -<2> The `cnv-tuning` plug-in provides support for custom MAC addresses. -+ -[NOTE] -==== -The virtual machine instance will be attached to the bridge `br1` through an access port with the requested VLAN. -==== - -. Create the network attachment definition by using the file you created in the previous step: -+ -[source,terminal] ----- -$ oc create -f pxe-net-conf.yaml ----- - -. Edit the virtual machine instance configuration file to include the details of the interface and network. - -.. Specify the network and MAC address, if required by the PXE server. -If the MAC address is not specified, a value is assigned automatically. -However, note that at this time, MAC addresses assigned automatically are not persistent. -+ -Ensure that `bootOrder` is set to `1` so that the interface boots first. -In this example, the interface is connected to a network called -`<pxe-net>`: -+ -[source,yaml] ----- -interfaces: -- masquerade: {} - name: default -- bridge: {} - name: pxe-net - macAddress: de:00:00:00:00:de - bootOrder: 1 ----- -+ -[NOTE] -==== -Boot order is global for interfaces and disks. -==== - -.. Assign a boot device number to the disk to ensure proper booting after operating system provisioning. -+ -Set the disk `bootOrder` value to `2`: -+ -[source,yaml] ----- -devices: - disks: - - disk: - bus: virtio - name: containerdisk - bootOrder: 2 ----- - -.. Specify that the network is connected to the previously created network attachment definition. In this scenario, `<pxe-net>` is connected to the network attachment definition called `<pxe-net-conf>`: -+ -[source,yaml] ----- -networks: -- name: default - pod: {} -- name: pxe-net - multus: - networkName: pxe-net-conf ----- - -. Create the virtual machine instance: -+ -[source,terminal] ----- -$ oc create -f vmi-pxe-boot.yaml ----- - -.Example output -[source,terminal] ----- - virtualmachineinstance.kubevirt.io "vmi-pxe-boot" created ----- - -. Wait for the virtual machine instance to run: -+ -[source,terminal] ----- -$ oc get vmi vmi-pxe-boot -o yaml | grep -i phase - phase: Running ----- - -. View the virtual machine instance using VNC: -+ -[source,terminal] ----- -$ virtctl vnc vmi-pxe-boot ----- - -. Watch the boot screen to verify that the PXE boot is successful. - -. Log in to the virtual machine instance: -+ -[source,terminal] ----- -$ virtctl console vmi-pxe-boot ----- - -. Verify the interfaces and MAC address on the virtual machine and that the interface connected to the bridge has the specified MAC address. -In this case, we used `eth1` for the PXE boot, without an IP address. The other interface, `eth0`, got an IP address from {product-title}. -+ -[source,terminal] ----- -$ ip addr ----- - -.Example output -[source,terminal] ----- -... -3. eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000 - link/ether de:00:00:00:00:de brd ff:ff:ff:ff:ff:ff ----- diff --git a/modules/virt-reclaiming-statically-provisioned-persistent-volumes.adoc b/modules/virt-reclaiming-statically-provisioned-persistent-volumes.adoc deleted file mode 100644 index 1f9bef79062e..000000000000 --- a/modules/virt-reclaiming-statically-provisioned-persistent-volumes.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// virt/virtual_machines/virtual_disks/virt-reusing-statically-provisioned-persistent-volumes.adoc - -[id="virt-reclaiming-statically-provisioned-persistent-volumes_{context}"] -= Reclaiming statically provisioned persistent volumes - -Reclaim a statically provisioned persistent volume (PV) by unbinding the persistent volume claim (PVC) and deleting the PV. You might also need to manually delete the shared storage. - -Reclaiming a statically provisioned PV is dependent on the underlying storage. -This procedure provides a general approach that might need to be customized depending on your storage. - -.Procedure - -. Ensure that the reclaim policy of the PV is set to `Retain`: - -.. Check the reclaim policy of the PV: -+ -[source,terminal] ----- -$ oc get pv <pv_name> -o yaml | grep 'persistentVolumeReclaimPolicy' ----- - -.. If the `persistentVolumeReclaimPolicy` is not set to `Retain`, edit the reclaim policy with the following command: -+ -[source,terminal] ----- -$ oc patch pv <pv_name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' ----- - -. Ensure that no resources are using the PV: -+ -[source,terminal] ----- -$ oc describe pvc <pvc_name> | grep 'Mounted By:' ----- -+ -Remove any resources that use the PVC before continuing. - -. Delete the PVC to release the PV: -+ -[source,terminal] ----- -$ oc delete pvc <pvc_name> ----- - -. Optional: Export the PV configuration to a YAML file. If you manually remove the shared storage later in this procedure, you can refer to this configuration. -You can also use `spec` parameters in this file as the basis to create a new PV with the same storage configuration after you reclaim the PV: -+ -[source,terminal] ----- -$ oc get pv <pv_name> -o yaml > <file_name>.yaml ----- - -. Delete the PV: -+ -[source,terminal] ----- -$ oc delete pv <pv_name> ----- - -. Optional: Depending on the storage type, you might need to remove the contents of the shared storage folder: -+ -[source,terminal] ----- -$ rm -rf <path_to_share_storage> ----- - -. Optional: Create a PV that uses the same storage configuration as the deleted PV. If you exported the reclaimed PV configuration earlier, you can use the `spec` parameters of that file as the basis for a new PV manifest: -+ -[NOTE] -==== -To avoid possible conflict, it is good practice to give the new PV object a different name than the one that you deleted. -==== -+ -[source,terminal] ----- -$ oc create -f <new_pv_name>.yaml ----- diff --git a/modules/virt-refreshing-certificates.adoc b/modules/virt-refreshing-certificates.adoc deleted file mode 100644 index 543a9373a1f3..000000000000 --- a/modules/virt-refreshing-certificates.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_maintenance/virt-refresh-certificates.adoc - -[id="virt-refreshing-certificates_{context}"] -= Refreshing TLS certificates - -To refresh the TLS certificates for {VirtProductName}, download and run the `rotate-certs` script. This script is available from the `kubevirt/hyperconverged-cluster-operator` repository on GitHub. - -[IMPORTANT] -==== -When refreshing the certificates, the following operations are impacted: - -* Migrations are canceled -* Image uploads are canceled -* VNC and console connections are closed -==== - -.Prerequisites - -* Ensure that you are logged in to the cluster as a user with `cluster-admin` privileges. -The script uses your active session to the cluster to refresh certificates in the `openshift-cnv` namespace. - -.Procedure - -. Download the `rotate-certs.sh` script from GitHub: -+ -[source,terminal] ----- -$ curl -O https://raw.githubusercontent.com/kubevirt/hyperconverged-cluster-operator/master/tools/rotate-certs.sh ----- - -. Ensure the script is executable: -+ -[source,terminal] ----- -$ chmod +x rotate-certs.sh ----- - -. Run the script: -+ -[source,terminal] ----- -$ ./rotate-certs.sh -n openshift-cnv ----- - -The TLS certificates are refreshed and valid for one year. diff --git a/modules/virt-remove-boot-order-item-web.adoc b/modules/virt-remove-boot-order-item-web.adoc deleted file mode 100644 index edb6feaf736f..000000000000 --- a/modules/virt-remove-boot-order-item-web.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assembly: -// -// * virt/virt_users_guide/virt-edit-boot-order.adoc -// - -[id="virt-remove-boot-order-item-web_{context}"] - -= Removing items from a boot order list in the web console - -Remove items from a boot order list by using the web console. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine to open the *Virtual Machine Overview* screen. - -. Click the *Details* tab. - -. Click the pencil icon that is located on the right side of *Boot Order*. - -. Click the *Remove* icon {delete} next to the item. The item is removed from the boot order list and saved in the list of available boot sources. If you remove all items from the boot order list, the following message displays: *No resource selected. VM will attempt to boot from disks by order of appearance in YAML file.* - -[NOTE] -==== -If the virtual machine is running, changes to *Boot Order* will not take effect until you restart the virtual machine. - -You can view pending changes by clicking *View Pending Changes* on the right side of the *Boot Order* field. The *Pending Changes* banner at the -top of the page displays a list of all changes that will be applied when the virtual machine restarts. -==== diff --git a/modules/virt-removing-interface-from-nodes.adoc b/modules/virt-removing-interface-from-nodes.adoc deleted file mode 100644 index 00a779b4b836..000000000000 --- a/modules/virt-removing-interface-from-nodes.adoc +++ /dev/null @@ -1,63 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-updating-node-network-config.adoc -// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc - -[id="virt-removing-interface-from-nodes_{context}"] -= Removing an interface from nodes - -You can remove an interface from one or more nodes in the cluster by editing the `NodeNetworkConfigurationPolicy` object and setting the `state` of the interface to `absent`. - -Removing an interface from a node does not automatically restore the node network configuration to a previous state. If you want to restore the previous state, you will need to define that node network configuration in the policy. - -If you remove a bridge or bonding interface, any node NICs in the cluster that were previously attached or subordinate to that bridge or bonding interface are placed in a `down` state and become unreachable. To avoid losing connectivity, configure the node NIC in the same policy so that it has a status of `up` and either DHCP or a static IP address. - -[NOTE] -==== -Deleting the node network policy that added an interface does not change the configuration of the policy on the node. -Although a `NodeNetworkConfigurationPolicy` is an object in the cluster, it only represents the requested configuration. + -Similarly, removing an interface does not delete the policy. -==== - -.Procedure - -. Update the `NodeNetworkConfigurationPolicy` manifest used to create the interface. The following example removes a Linux bridge and configures the `eth1` NIC with DHCP to avoid losing connectivity: -+ -[source,yaml] ----- -apiVersion: nmstate.io/v1beta1 -kind: NodeNetworkConfigurationPolicy -metadata: - name: <br1-eth1-policy> <1> -spec: - nodeSelector: <2> - node-role.kubernetes.io/worker: "" <3> - desiredState: - interfaces: - - name: br1 - type: linux-bridge - state: absent <4> - - name: eth1 <5> - type: ethernet <6> - state: up <7> - ipv4: - dhcp: true <8> - enabled: true <9> ----- -<1> Name of the policy. -<2> Optional: If you do not include the `nodeSelector` parameter, the policy applies to all nodes in the cluster. -<3> This example uses the `node-role.kubernetes.io/worker: ""` node selector to select all worker nodes in the cluster. -<4> Changing the state to `absent` removes the interface. -<5> The name of the interface that is to be unattached from the bridge interface. -<6> The type of interface. This example creates an Ethernet networking interface. -<7> The requested state for the interface. -<8> Optional: If you do not use `dhcp`, you can either set a static IP or leave the interface without an IP address. -<9> Enables `ipv4` in this example. - -. Update the policy on the node and remove the interface: -+ -[source,terminal] ----- -$ oc apply -f <br1-eth1-policy.yaml> <1> ----- -<1> File name of the policy manifest. diff --git a/modules/virt-removing-secret-configmap-service-account-vm.adoc b/modules/virt-removing-secret-configmap-service-account-vm.adoc deleted file mode 100644 index 9568b6d3d748..000000000000 --- a/modules/virt-removing-secret-configmap-service-account-vm.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-managing-configmaps-secrets-service-accounts.adoc - -[id="virt-removing-secret-configmap-service-account-vm_{context}"] - -= Removing a secret, config map, or service account from a virtual machine - -Remove a secret, config map, or service account from a virtual machine by using the {product-title} web console. - -.Prerequisites - -* You must have at least one secret, config map, or service account -that is attached to a virtual machine. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine to open the *Virtual Machine Overview* screen. - -. Click the *Environment* tab. - -. Find the item that you want to delete in the list, and click the *Remove* button {delete} on the right side of the item. - -. Click *Save*. - -[NOTE] -==== -You can reset the form to the last saved state by clicking *Reload*. -==== - - -.Verification - -. From the *Virtual Machine Overview* page, click the *Disks* tab. - -. Check to ensure that the secret, config map, or service account that you removed is no longer included in the list of disks. diff --git a/modules/virt-removing-virtio-disk-from-vm.adoc b/modules/virt-removing-virtio-disk-from-vm.adoc deleted file mode 100644 index 179070d7dac6..000000000000 --- a/modules/virt-removing-virtio-disk-from-vm.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc -// * virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc - -//This file contains UI elements and/or package names that need to be updated. - -[id="virt-removing-virtio-disk-from-vm_{context}"] -= Removing the VirtIO container disk from a virtual machine - -After installing all required VirtIO drivers to the virtual machine, the - `container-native-virtualization/virtio-win` container disk no longer needs to be attached to the virtual machine. -Remove the `container-native-virtualization/virtio-win` container disk from the virtual machine configuration file. - -.Procedure -. Edit the configuration file and remove the `disk` and the `volume`. -+ -[source,terminal] ----- -$ oc edit vm <vm-name> ----- -+ - -[source,yaml] ----- -spec: - domain: - devices: - disks: - - name: virtiocontainerdisk - bootOrder: 2 - cdrom: - bus: sata -volumes: - - containerDisk: - image: container-native-virtualization/virtio-win - name: virtiocontainerdisk ----- - -. Reboot the virtual machine for the changes to take effect. diff --git a/modules/virt-restarting-vm-web.adoc b/modules/virt-restarting-vm-web.adoc deleted file mode 100644 index c67fb4ebdbb4..000000000000 --- a/modules/virt-restarting-vm-web.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-controlling-vm-states.adoc - -[id="virt-restarting-vm-web_{context}"] -= Restarting a virtual machine - -You can restart a running virtual machine from the web console. - -[IMPORTANT] -==== -To avoid errors, do not restart a virtual machine while it has a status of *Importing*. -==== - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Find the row that contains the virtual machine that you want to restart. - -. Navigate to the appropriate menu for your use case: - -* To stay on this page, where you can perform actions on multiple virtual machines: - -.. Click the Options menu {kebab} located at the far right end of the row. - -* To view comprehensive information about the selected virtual machine before -you restart it: - -.. Access the *Virtual Machine Overview* screen by clicking the name of the virtual -machine. - -.. Click *Actions*. - -. Select *Restart Virtual Machine*. - -. In the confirmation window, click *Restart* to restart the virtual machine. diff --git a/modules/virt-restoring-vm-from-snapshot-cli.adoc b/modules/virt-restoring-vm-from-snapshot-cli.adoc deleted file mode 100644 index 6036cc885fa7..000000000000 --- a/modules/virt-restoring-vm-from-snapshot-cli.adoc +++ /dev/null @@ -1,107 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc - -[id="virt-restoring-vm-from-snapshot-cli_{context}"] -= Restoring a virtual machine from a snapshot in the CLI - -You can restore an existing virtual machine (VM) to a previous configuration by using a VM snapshot . - -.Prerequisites - -* Install the OpenShift CLI (`oc`). -* Power down the VM you want to restore to a previous state. - -.Procedure - -. Create a YAML file to define a `VirtualMachineRestore` object that specifies the name of the VM you want to restore and the name of the snapshot to be used as the source. -+ -For example: -+ -[source,yaml] - ----- -apiVersion: snapshot.kubevirt.io/v1alpha1 -kind: VirtualMachineRestore -metadata: - name: my-vmrestore <1> -spec: - target: - apiGroup: kubevirt.io - kind: VirtualMachine - name: my-vm <2> - virtualMachineSnapshotName: my-vmsnapshot <3> ----- -<1> The name of the new `VirtualMachineRestore` object. -<2> The name of the target VM you want to restore. -<3> The name of the `VirtualMachineSnapshot` object to be used as the source. - -. Create the `VirtualMachineRestore` resource. The snapshot controller updates the status fields of the `VirtualMachineRestore` object and replaces the existing VM configuration with the snapshot content. -+ -[source,terminal] ----- -$ oc create -f <my-vmrestore>.yaml ----- - -.Verification - -* Verify that the VM is restored to the previous state represented by the snapshot. The `complete` flag must be set to `true`. -+ -[source,terminal] ----- -$ oc get vmrestore <my-vmrestore> ----- -+ -.Example output -+ -[source, yaml] - ----- -apiVersion: snapshot.kubevirt.io/v1alpha1 -kind: VirtualMachineRestore -metadata: -creationTimestamp: "2020-09-30T14:46:27Z" -generation: 5 -name: my-vmrestore -namespace: default -ownerReferences: -- apiVersion: kubevirt.io/v1alpha3 -blockOwnerDeletion: true -controller: true -kind: VirtualMachine -name: my-vm -uid: 355897f3-73a0-4ec4-83d3-3c2df9486f4f -resourceVersion: "5512" -selfLink: /apis/snapshot.kubevirt.io/v1alpha1/namespaces/default/virtualmachinerestores/my-vmrestore -uid: 71c679a8-136e-46b0-b9b5-f57175a6a041 -spec: -target: -apiGroup: kubevirt.io -kind: VirtualMachine -name: my-vm -virtualMachineSnapshotName: my-vmsnapshot -status: -complete: true <1> -conditions: -- lastProbeTime: null -lastTransitionTime: "2020-09-30T14:46:28Z" -reason: Operation complete -status: "False" <2> -type: Progressing -- lastProbeTime: null -lastTransitionTime: "2020-09-30T14:46:28Z" -reason: Operation complete -status: "True" <3> -type: Ready -deletedDataVolumes: -- test-dv1 -restoreTime: "2020-09-30T14:46:28Z" -restores: -- dataVolumeName: restore-71c679a8-136e-46b0-b9b5-f57175a6a041-datavolumedisk1 -persistentVolumeClaim: restore-71c679a8-136e-46b0-b9b5-f57175a6a041-datavolumedisk1 -volumeName: datavolumedisk1 -volumeSnapshotName: vmsnapshot-28eedf08-5d6a-42c1-969c-2eda58e2a78d-volume-datavolumedisk1 ----- -<1> Specifies if the process of restoring the VM to the state represented by the snapshot is complete. -<2> The `status` field of the `Progressing` condition specifies if the VM is still being restored. -<3> The `status` field of the `Ready` condition specifies if the VM restoration process is complete. diff --git a/modules/virt-restoring-vm-from-snapshot-web.adoc b/modules/virt-restoring-vm-from-snapshot-web.adoc deleted file mode 100644 index dd96d4bc2e93..000000000000 --- a/modules/virt-restoring-vm-from-snapshot-web.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc - -[id="virt-restoring-vm-from-snapshot-web_{context}"] -= Restoring a virtual machine from a snapshot in the web console - -You can restore a virtual machine (VM) to a previous configuration represented by a snapshot in the web console. - -.Procedure - -. Click *Workloads* → *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine to open the *Virtual Machine Overview* screen. - -. If the virtual machine is running, click *Actions* → *Stop Virtual Machine* to power it down. - -. Click the *Snapshots* tab. The page displays a list of snapshots associated with the virtual machine. - -. Choose one of the following methods to restore a VM snapshot: - -.. For the snapshot that you want to use as the source to restore the VM, click *Restore*. - -.. Select a snapshot to open the *Snapshot Details* screen and click *Actions* → *Restore Virtual Machine Snapshot*. - -. In the confirmation pop-up window, click *Restore* to restore the VM to its previous configuration represented by the snapshot. diff --git a/modules/virt-resuming-node-maintenance-cli.adoc b/modules/virt-resuming-node-maintenance-cli.adoc deleted file mode 100644 index 06e294f49e5b..000000000000 --- a/modules/virt-resuming-node-maintenance-cli.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_maintenance/virt-resuming-node.adoc - -[id="virt-resuming-node-maintenance-cli_{context}"] -= Resuming a node from maintenance mode in the CLI - -Resume a node from maintenance mode by making it schedulable again. - -.Procedure - -* Mark the node as schedulable. You can then resume scheduling new workloads on the node. -+ -[source,terminal] ----- -$ oc adm uncordon <node1> ----- diff --git a/modules/virt-resuming-node-maintenance-web.adoc b/modules/virt-resuming-node-maintenance-web.adoc deleted file mode 100644 index 721522d0513b..000000000000 --- a/modules/virt-resuming-node-maintenance-web.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_maintenance/virt-resuming-node.adoc - -[id="virt-resuming-node-maintenance-web_{context}"] -= Resuming a node from maintenance mode in the web console - -Resume a node from maintenance mode using the Options menu {kebab} found -on each node in the *Compute* -> *Nodes* list, or using the *Actions* control -of the *Node Details* screen. - -.Procedure - -. In the {VirtProductName} console, click *Compute* -> *Nodes*. -. You can resume the node from this screen, which makes it easier to perform -actions on multiple nodes in the one screen, or from the *Node Details* screen -where you can view comprehensive details of the selected node: -** Click the Options menu {kebab} at the end of the node and select -*Stop Maintenance*. -** Click the node name to open the *Node Details* screen and click -*Actions* -> *Stop Maintenance*. -. Click *Stop Maintenance* in the confirmation window. - -The node becomes schedulable, but virtual machine instances that were running on -the node prior to maintenance will not automatically migrate back to this node. diff --git a/modules/virt-schedule-cpu-host-model-vms.adoc b/modules/virt-schedule-cpu-host-model-vms.adoc deleted file mode 100644 index 9113cb4f44fa..000000000000 --- a/modules/virt-schedule-cpu-host-model-vms.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-schedule-vms.adoc - -[id="virt-schedule-cpu-host-model-vms_{context}"] -= Scheduling virtual machines with the host model - -When the CPU model for a virtual machine (VM) is set to `host-model`, the VM inherits the CPU model of the node where it is scheduled. - -.Procedure - -* Edit the `domain` spec of your VM configuration file. The following example shows `host-model` being specified for the virtual machine instance (VMI): -+ -[source,yaml] ----- -apiVersion: kubevirt/v1alpha3 -kind: VirtualMachineInstance -metadata: - name: myvmi -spec: - domain: - cpu: - model: host-model <1> ----- -<1> The VM or VMI that inherits the CPU model of the node where it is scheduled. diff --git a/modules/virt-schedule-supported-cpu-model-vms.adoc b/modules/virt-schedule-supported-cpu-model-vms.adoc deleted file mode 100644 index 48893e88dd30..000000000000 --- a/modules/virt-schedule-supported-cpu-model-vms.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-schedule-vms.adoc - -[id="virt-schedule-supported-cpu-model-vms_{context}"] -= Scheduling virtual machines with the supported CPU model - -You can configure a CPU model for a virtual machine (VM) or a virtual machine instance (VMI) to schedule it on a node where its CPU model is supported. - -.Procedure - -* Edit the `domain` spec of your virtual machine configuration file. The following example shows a specific CPU model defined for a VMI: -+ -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachineInstance -metadata: - name: myvmi -spec: - domain: - cpu: - model: Conroe <1> ----- -<1> CPU model for the VMI. diff --git a/modules/virt-setting-node-maintenance-cli.adoc b/modules/virt-setting-node-maintenance-cli.adoc deleted file mode 100644 index 06bfdc8d101a..000000000000 --- a/modules/virt-setting-node-maintenance-cli.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_maintenance/virt-setting-node-maintenance.adoc - -[id="virt-setting-node-maintenance-cli_{context}"] -= Setting a node to maintenance mode in the CLI - -Set a node to maintenance mode by marking it as unschedulable and using the `oc adm drain` command to evict or delete pods from the node. - -.Procedure - -. Mark the node as unschedulable. The node status changes to `NotReady,SchedulingDisabled`. -+ -[source,terminal] ----- -$ oc adm cordon <node1> ----- - -. Drain the node in preparation for maintenance. The node live migrates virtual machine instances that have the `LiveMigratable` condition set to `True` and the `spec:evictionStrategy` field set to `LiveMigrate`. All other pods and virtual machines on the node are deleted and recreated on another node. -+ -[source,terminal] ----- -$ oc adm drain <node1> --delete-local-data --ignore-daemonsets=true --force ----- - -* The `--delete-local-data` flag removes any virtual machine instances on the node that use `emptyDir` volumes. Data in these volumes is ephemeral and is safe to be deleted after termination. - -* The `--ignore-daemonsets=true` flag ensures that daemon sets are ignored and pod eviction can continue successfully. - -* The `--force` flag is required to delete pods that are not managed by a replica set or daemon set controller. diff --git a/modules/virt-setting-node-maintenance-web.adoc b/modules/virt-setting-node-maintenance-web.adoc deleted file mode 100644 index f1342d002f5e..000000000000 --- a/modules/virt-setting-node-maintenance-web.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_maintenance/virt-setting-node-maintenance.adoc - -[id="virt-setting-node-maintenance-web_{context}"] -= Setting a node to maintenance mode in the web console - -Set a node to maintenance mode using the Options menu {kebab} found on each node in the -*Compute* -> *Nodes* list, or using the *Actions* control of the *Node Details* -screen. - -.Procedure - -. In the {VirtProductName} console, click *Compute* -> *Nodes*. -. You can set the node to maintenance from this screen, which makes it easier to perform -actions on multiple nodes in the one screen or from the *Node Details* screen -where you can view comprehensive details of the selected node: -** Click the Options menu {kebab} at the end of the node and select *Start Maintenance*. -** Click the node name to open the *Node Details* screen and click -*Actions* -> *Start Maintenance*. -. Click *Start Maintenance* in the confirmation window. - -The node will live migrate virtual machine instances that have the -`LiveMigration` eviction strategy, and the node is no longer schedulable. All -other pods and virtual machines on the node are deleted and recreated on another node. diff --git a/modules/virt-setting-policy-attributes.adoc b/modules/virt-setting-policy-attributes.adoc deleted file mode 100644 index 4291120bccc8..000000000000 --- a/modules/virt-setting-policy-attributes.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-schedule-vms.adoc - -[id="virt-setting-policy-attributes_{context}"] -= Setting a policy attribute and CPU feature - -You can set a policy attribute and CPU feature for each virtual machine (VM) to ensure that it is scheduled on a node according to policy and feature. The CPU feature that you set is verified to ensure that it is supported by the host CPU or emulated by the hypervisor. - -.Procedure - -* Edit the `domain` spec of your VM configuration file. The following example sets the CPU feature and the `require` policy for a virtual machine instance (VMI): -+ -[source,yaml] ----- -apiVersion: v1 -kind: VirtualMachine -metadata: - name: myvmi -spec: - domain: - cpu: - features: - - name: apic <1> - policy: require <2> ----- -<1> Name of the CPU feature for the VM or VMI. -<2> Policy attribute for the VM or VMI. diff --git a/modules/virt-starting-vm-web.adoc b/modules/virt-starting-vm-web.adoc deleted file mode 100644 index 22f2b89d6657..000000000000 --- a/modules/virt-starting-vm-web.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-controlling-vm-states.adoc - -[id="virt-starting-vm-web_{context}"] -= Starting a virtual machine - -You can start a virtual machine from the web console. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Find the row that contains the virtual machine that you want to start. - -. Navigate to the appropriate menu for your use case: - -* To stay on this page, where you can perform actions on multiple virtual machines: - -.. Click the Options menu {kebab} located at the far right end of the row. - -* To view comprehensive information about the selected virtual machine before -you start it: - -.. Access the *Virtual Machine Overview* screen by clicking the name of the virtual -machine. - -.. Click *Actions*. - -. Select *Start Virtual Machine*. - -. In the confirmation window, click *Start* to start the virtual machine. - -[NOTE] -==== -When you start virtual machine that is provisioned from a `URL` source for the -first time, the virtual machine has a status of *Importing* while {VirtProductName} -imports the container from the URL endpoint. Depending on the size of the image, -this process might take several minutes. -==== diff --git a/modules/virt-stopping-vm-web.adoc b/modules/virt-stopping-vm-web.adoc deleted file mode 100644 index 5c4a8c737842..000000000000 --- a/modules/virt-stopping-vm-web.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-controlling-vm-states.adoc - -[id="virt-stopping-vm-web_{context}"] -= Stopping a virtual machine - -You can stop a virtual machine from the web console. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Find the row that contains the virtual machine that you want to stop. - -. Navigate to the appropriate menu for your use case: - -* To stay on this page, where you can perform actions on multiple virtual machines: - -.. Click the Options menu {kebab} located at the far right end of the row. - -* To view comprehensive information about the selected virtual machine before -you stop it: - -.. Access the *Virtual Machine Overview* screen by clicking the name of the virtual -machine. - -.. Click *Actions*. - -. Select *Stop Virtual Machine*. - -. In the confirmation window, click *Stop* to stop the virtual machine. diff --git a/modules/virt-storage-wizard-fields-web.adoc b/modules/virt-storage-wizard-fields-web.adoc deleted file mode 100644 index 3e0e684a12ef..000000000000 --- a/modules/virt-storage-wizard-fields-web.adoc +++ /dev/null @@ -1,106 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-storage-wizard-fields-web_{context}"] -= Storage fields - -|=== -|Name |Selection |Description - -.6+|Source -|Blank (creates PVC) -|Create an empty disk. - -|Import via URL (creates PVC) -|Import content via URL (HTTP or S3 endpoint). - -|Use an existing PVC -|Use a PVC that is already available in the cluster. - -|Clone existing PVC (creates PVC) -|Select an existing PVC available in the cluster and clone it. - -|Import via Registry (creates PVC) -|Import content via container registry. - -|Container (ephemeral) -|Upload content from a container located in a registry accessible from the cluster. The container disk should be used only for read-only filesystems such as CD-ROMs or temporary virtual machines. - -|Name -| -|Name of the disk. The name can contain lowercase letters (`a-z`), numbers (`0-9`), hyphens (`-`), and periods (`.`), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, or special characters. - -|Size -| -|Size of the disk in GiB. - -|Type -| -|Type of disk. Example: Disk or CD-ROM - -|Interface -| -|Type of disk device. Supported interfaces are *virtIO*, *SATA*, and *SCSI*. - -|Storage Class -| -|The storage class that is used to create the disk. - -|Advanced -> Volume Mode -| -|Defines whether the persistent volume uses a formatted file system or raw block state. Default is *Filesystem*. -ifeval::["{context}" != "virt-importing-rhv-vm"] -|Advanced -> Access Mode -| -|Access mode of the persistent volume. Supported access modes are *Single User (RWO)*, *Shared Access (RWX)*, and *Read Only (ROX)*. -endif::[] -|=== - -[id="virt-storage-wizard-fields-advanced-web_{context}"] -[discrete] -== Advanced storage settings - -ifeval::["{context}" != "virt-importing-rhv-vm"] -The following advanced storage settings are available for *Blank*, *Import via URL*, and *Clone existing PVC* disks. These parameters are optional. If you do not specify these parameters, the system uses the default values from the `kubevirt-storage-class-defaults` config map. -endif::[] - -[cols="2a,3a,5a"] -|=== -|Name | Parameter | Description - -.2+|Volume Mode -|Filesystem -|Stores the virtual disk on a file system-based volume. - -|Block -|Stores the virtual disk directly on the block volume. Only use `Block` if the underlying storage supports it. - -ifeval::["{context}" == "virt-importing-rhv-vm"] -.3+|Access Mode ^[1]^ -endif::[] -ifeval::["{context}" != "virt-importing-rhv-vm"] -.3+|Access Mode -endif::[] -|Single User (RWO) -|The disk can be mounted as read/write by a single node. - -|Shared Access (RWX) -|The disk can be mounted as read/write by many nodes. -ifeval::["{context}" != "virt-importing-rhv-vm"] -[NOTE] -==== -This is required for some features, such as live migration of virtual machines between nodes. -==== -endif::[] - -|Read Only (ROX) -|The disk can be mounted as read-only by many nodes. -|=== -ifeval::["{context}" == "virt-importing-rhv-vm"] --- -1. You can change the access mode by using the command line interface. --- -endif::[] diff --git a/modules/virt-subscribing-cli.adoc b/modules/virt-subscribing-cli.adoc deleted file mode 100644 index 495aa4942feb..000000000000 --- a/modules/virt-subscribing-cli.adoc +++ /dev/null @@ -1,53 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/install/installing-virt-cli.adoc - -[id="virt-subscribing-cli_{context}"] -= Subscribing to the {VirtProductName} catalog by using the CLI - -Before you install {VirtProductName}, you must subscribe to the {VirtProductName} catalog. Subscribing gives the `openshift-cnv` namespace access to the {VirtProductName} Operators. - -To subscribe, configure `Namespace`, `OperatorGroup`, and `Subscription` objects by applying a single manifest to your cluster. - -.Procedure - -. Create a YAML file that contains the following manifest: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: v1 -kind: Namespace -metadata: - name: openshift-cnv ---- -apiVersion: operators.coreos.com/v1 -kind: OperatorGroup -metadata: - name: kubevirt-hyperconverged-group - namespace: openshift-cnv -spec: - targetNamespaces: - - openshift-cnv ---- -apiVersion: operators.coreos.com/v1alpha1 -kind: Subscription -metadata: - name: hco-operatorhub - namespace: openshift-cnv -spec: - source: redhat-operators - sourceNamespace: openshift-marketplace - name: kubevirt-hyperconverged - startingCSV: kubevirt-hyperconverged-operator.v{HCOVersion} - channel: "stable" <1> ----- -<1> Using the `stable` channel ensures that you install the version of -{VirtProductName} that is compatible with your {product-title} version. - -. Create the required `Namespace`, `OperatorGroup`, and `Subscription` objects -for {VirtProductName} by running the following command: -+ -[source,terminal] ----- -$ oc apply -f <file name>.yaml ----- diff --git a/modules/virt-supported-cluster-version.adoc b/modules/virt-supported-cluster-version.adoc deleted file mode 100644 index 8075c668bde2..000000000000 --- a/modules/virt-supported-cluster-version.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/about-virt.adoc -// * virt/virt_release_notes/virt-2-4-release-notes.adoc - -[id="virt-supported-cluster-version_{context}"] -= {VirtProductName} supported cluster version - -{VirtProductName} {VirtVersion} is supported for use on {product-title} {product-version} clusters. - diff --git a/modules/virt-supported-virtio-drivers.adoc b/modules/virt-supported-virtio-drivers.adoc deleted file mode 100644 index 9e5285bd2a0a..000000000000 --- a/modules/virt-supported-virtio-drivers.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc -// * virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc - -[id="virt-supported-virtio-drivers_{context}"] -= Supported VirtIO drivers for Microsoft Windows virtual machines - -[caption=] -.Supported drivers -|=== -|Driver name | Hardware ID | Description - -|*viostor* -|VEN_1AF4&DEV_1001 + -VEN_1AF4&DEV_1042 -|The block driver. Sometimes displays as an *SCSI Controller* in the *Other devices* -group. - -|*viorng* -|VEN_1AF4&DEV_1005 + -VEN_1AF4&DEV_1044 -|The entropy source driver. Sometimes displays as a *PCI Device* in the -*Other devices* group. - -|*NetKVM* -|VEN_1AF4&DEV_1000 + -VEN_1AF4&DEV_1041 -|The network driver. Sometimes displays as an *Ethernet Controller* in the -*Other devices* group. Available only if a VirtIO NIC is configured. -|=== diff --git a/modules/virt-template-blank-disk-datavolume.adoc b/modules/virt-template-blank-disk-datavolume.adoc deleted file mode 100644 index 76d643f328f1..000000000000 --- a/modules/virt-template-blank-disk-datavolume.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-expanding-virtual-storage-with-blank-disk-images.adoc - -[id="virt-template-blank-disk-datavolume_{context}"] -= Template: Data volume configuration file for blank disk images - -*blank-image-datavolume.yaml* -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: blank-image-datavolume -spec: - source: - blank: {} - pvc: - # Optional: Set the storage class or omit to accept the default - # storageClassName: "hostpath" - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 500Mi ----- diff --git a/modules/virt-template-datavolume-clone.adoc b/modules/virt-template-datavolume-clone.adoc deleted file mode 100644 index 0eddcbf661ca..000000000000 --- a/modules/virt-template-datavolume-clone.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc - -[id="virt-template-datavolume-clone_{context}"] -= Template: Data volume clone configuration file - -*example-clone-dv.yaml* -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: "example-clone-dv" -spec: - source: - pvc: - name: source-pvc - namespace: example-ns - pvc: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: "1G" ----- diff --git a/modules/virt-template-datavolume-import.adoc b/modules/virt-template-datavolume-import.adoc deleted file mode 100644 index 85e32e5ae065..000000000000 --- a/modules/virt-template-datavolume-import.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc - -[id="virt-template-datavolume-import_{context}"] -= Template: Data volume import configuration file - -*example-import-dv.yaml* -[source,yaml] ----- -apiVersion: cdi.kubevirt.io/v1beta1 -kind: DataVolume -metadata: - name: "example-import-dv" -spec: - source: - http: - url: "" <1> - secretRef: "" <2> - pvc: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: "1G" ----- -<1> The `HTTP` source of the image you want to import. -<2> The `secretRef` parameter is optional. diff --git a/modules/virt-template-datavolume-vm.adoc b/modules/virt-template-datavolume-vm.adoc deleted file mode 100644 index 02e2f5233411..000000000000 --- a/modules/virt-template-datavolume-vm.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/cloning_vms/virt-cloning-vm-using-datavolumetemplate.adoc -// * virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc - -[id="virt-template-datavolume-vm_{context}"] -= Template: Data volume virtual machine configuration file - -*example-dv-vm.yaml* -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachine -metadata: - labels: - kubevirt.io/vm: example-vm - name: example-vm -spec: - dataVolumeTemplates: - - metadata: - name: example-dv - spec: - pvc: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1G - source: - http: - url: "" <1> - running: false - template: - metadata: - labels: - kubevirt.io/vm: example-vm - spec: - domain: - cpu: - cores: 1 - devices: - disks: - - disk: - bus: virtio - name: example-dv-disk - machine: - type: q35 - resources: - requests: - memory: 1G - terminationGracePeriodSeconds: 0 - volumes: - - dataVolume: - name: example-dv - name: example-dv-disk ----- -<1> The `HTTP` source of the image you want to import, if applicable. diff --git a/modules/virt-template-fields-for-boot-source.adoc b/modules/virt-template-fields-for-boot-source.adoc deleted file mode 100644 index d6ac5c7f7b91..000000000000 --- a/modules/virt-template-fields-for-boot-source.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/vm_templates/virt-creating-vm-template.adoc - -[id="virt-template-fields-for-boot-source_{context}"] -= Virtual machine template fields for adding a boot source - -The following table describes the fields for *Add boot source to template* window. This window displays when you click *Add Source* for a virtual machine template in the *Templates* tab. -[cols="2a,3a,5a"] -|=== -|Name | Parameter | Description - -.4+|Boot source type -|Upload local file (creates PVC) -|Upload a file from your local device. Supported file types include gz, xz, tar, and qcow2. - -|Import via URL (creates PVC) -|Import content from an image available from an HTTP or S3 endpoint. Obtain the download link URL from the web page where the image download is available and enter that URL link in the *Import via URL (creates PVC)* field. Example: For a Red Hat Enterprise Linux image, log on to the Red Hat Customer Portal, access the image download page, and copy the download link URL for the KVM guest image. - -|Clone existing PVC (creates PVC) -|Use a PVC that is already available in the cluster and clone it. - -|Import via Registry (creates PVC) -|Specify the bootable operating system container that is located in a registry and accessible from the cluster. Example: kubevirt/cirros-registry-dis-demo. - -|Source provider -| -|Optional field. Add descriptive text about the source for the template or the name of the user who created the template. Example: Red Hat. - -.3+|Advanced -|Storage class -|The storage class that is used to create the disk. - -|Access mode -|Access mode of the persistent volume. Supported access modes are *Single User (RWO)*, *Shared Access (RWX)*, *Read Only (ROX)*. If *Single User (RWO)* is selected, the disk can be mounted as read/write by a single node. If *Shared Access (RWX)* is selected, the disk can be mounted as read-write by many nodes. The `kubevirt-storage-class-defaults` config map provides access mode defaults for data volumes. The default value is set according to the best option for each storage class in the cluster. -+ -[NOTE] -==== -Shared Access (RWX) is required for some features, such as live migration of virtual machines between nodes. -==== - -|Volume mode -|Defines whether the persistent volume uses a formatted file system or raw block state. Supported modes are *Block* and *Filesystem*. The `kubevirt-storage-class-defaults` config map provides volume mode defaults for data volumes. The default value is set according to the best option for each storage class in the cluster. -|=== diff --git a/modules/virt-template-vm-config.adoc b/modules/virt-template-vm-config.adoc deleted file mode 100644 index cdf45fd3032b..000000000000 --- a/modules/virt-template-vm-config.adoc +++ /dev/null @@ -1,46 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc - -[id="virt-template-vm-config_{context}"] -= Template: Virtual machine configuration file - -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachine -metadata: - name: example-vm - namespace: default -spec: - running: false - template: - spec: - domain: - devices: - disks: - - name: containerdisk - disk: - bus: virtio - - name: cloudinitdisk - disk: - bus: virtio - interfaces: - - masquerade: {} - name: default - resources: - requests: - memory: 1024M - networks: - - name: default - pod: {} - volumes: - - name: containerdisk - containerDisk: - image: kubevirt/fedora-cloud-container-disk-demo - - name: cloudinitdisk - cloudInitNoCloud: - userData: | - #!/bin/bash - echo "fedora" | passwd fedora --stdin ----- diff --git a/modules/virt-template-vmi-pxe-config.adoc b/modules/virt-template-vmi-pxe-config.adoc deleted file mode 100644 index adff4effd75a..000000000000 --- a/modules/virt-template-vmi-pxe-config.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/advanced_vm_management/virt-configuring-pxe-booting.adoc - -[id="virt-pxe-vmi-template_{context}"] -= Template: Virtual machine instance configuration file for PXE booting - -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachineInstance -metadata: - creationTimestamp: null - labels: - special: vmi-pxe-boot - name: vmi-pxe-boot -spec: - domain: - devices: - disks: - - disk: - bus: virtio - name: containerdisk - bootOrder: 2 - - disk: - bus: virtio - name: cloudinitdisk - interfaces: - - masquerade: {} - name: default - - bridge: {} - name: pxe-net - macAddress: de:00:00:00:00:de - bootOrder: 1 - machine: - type: "" - resources: - requests: - memory: 1024M - networks: - - name: default - pod: {} - - multus: - networkName: pxe-net-conf - name: pxe-net - terminationGracePeriodSeconds: 0 - volumes: - - name: containerdisk - containerDisk: - image: kubevirt/fedora-cloud-container-disk-demo - - cloudInitNoCloud: - userData: | - #!/bin/bash - echo "fedora" | passwd fedora --stdin - name: cloudinitdisk -status: {} ----- diff --git a/modules/virt-template-windows-vmi.adoc b/modules/virt-template-windows-vmi.adoc deleted file mode 100644 index adfca3e73276..000000000000 --- a/modules/virt-template-windows-vmi.adoc +++ /dev/null @@ -1,62 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc - -[id="virt-template-windows-vmi_{context}"] -= Template: Windows virtual machine instance configuration file - -[source,yaml] ----- -apiVersion: kubevirt.io/v1alpha3 -kind: VirtualMachineInstance -metadata: - labels: - special: vmi-windows - name: vmi-windows -spec: - domain: - clock: - timer: - hpet: - present: false - hyperv: {} - pit: - tickPolicy: delay - rtc: - tickPolicy: catchup - utc: {} - cpu: - cores: 2 - devices: - disks: - - disk: - bus: sata - name: pvcdisk - interfaces: - - masquerade: {} - model: e1000 - name: default - features: - acpi: {} - apic: {} - hyperv: - relaxed: {} - spinlocks: - spinlocks: 8191 - vapic: {} - firmware: - uuid: 5d307ca9-b3ef-428c-8861-06e72d69f223 - machine: - type: q35 - resources: - requests: - memory: 2Gi - networks: - - name: default - pod: {} - terminationGracePeriodSeconds: 0 - volumes: - - name: pvcdisk - persistentVolumeClaim: - claimName: disk-windows ----- diff --git a/modules/virt-troubleshooting-incorrect-policy-config.adoc b/modules/virt-troubleshooting-incorrect-policy-config.adoc deleted file mode 100644 index 279a227956f5..000000000000 --- a/modules/virt-troubleshooting-incorrect-policy-config.adoc +++ /dev/null @@ -1,239 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-troubleshooting-node-network.adoc -// * networking/k8s_nmstate/k8s-nmstate-troubleshooting-node-network.adoc - -[id="virt-troubleshooting-incorrect-policy-config_{context}"] -= Troubleshooting an incorrect node network configuration policy configuration - -You can apply changes to the node network configuration across your entire cluster by applying a node network configuration policy. -If you apply an incorrect configuration, you can use the following example to troubleshoot and correct the failed node network policy. - -In this example, a Linux bridge policy is applied to an example cluster that has three control plane nodes (master) and three compute (worker) nodes. -The policy fails to be applied because it references an incorrect interface. -To find the error, investigate the available NMState resources. You can then update the policy with the correct configuration. - -.Procedure - -. Create a policy and apply it to your cluster. The following example creates a simple bridge on the `ens01` interface: -+ -[source,yaml] ----- -apiVersion: nmstate.io/v1beta1 -kind: NodeNetworkConfigurationPolicy -metadata: - name: ens01-bridge-testfail -spec: - desiredState: - interfaces: - - name: br1 - description: Linux bridge with the wrong port - type: linux-bridge - state: up - ipv4: - dhcp: true - enabled: true - bridge: - options: - stp: - enabled: false - port: - - name: ens01 ----- -+ -[source,terminal] ----- -$ oc apply -f ens01-bridge-testfail.yaml ----- -+ -.Example output -[source,terminal] ----- -nodenetworkconfigurationpolicy.nmstate.io/ens01-bridge-testfail created ----- - -. Verify the status of the policy by running the following command: -+ -[source,terminal] ----- -$ oc get nncp ----- -+ -The output shows that the policy failed: -+ -.Example output -[source,terminal] ----- -NAME STATUS -ens01-bridge-testfail FailedToConfigure ----- -+ -However, the policy status alone does not indicate if it failed on all nodes or a subset of nodes. - -. List the node network configuration enactments to see if the policy was successful on any of the nodes. If the policy failed for only a subset of nodes, it suggests that the problem is with a specific node configuration. If the policy failed on all nodes, it suggests that the problem is with the policy. -+ -[source,terminal] ----- -$ oc get nnce ----- -+ -The output shows that the policy failed on all nodes: -+ -.Example output -[source,terminal] ----- -NAME STATUS -control-plane-1.ens01-bridge-testfail FailedToConfigure -control-plane-2.ens01-bridge-testfail FailedToConfigure -control-plane-3.ens01-bridge-testfail FailedToConfigure -compute-1.ens01-bridge-testfail FailedToConfigure -compute-2.ens01-bridge-testfail FailedToConfigure -compute-3.ens01-bridge-testfail FailedToConfigure ----- - -. View one of the failed enactments and look at the traceback. The following command uses the output tool `jsonpath` to filter the output: -+ -[source,terminal] ----- -$ oc get nnce compute-1.ens01-bridge-testfail -o jsonpath='{.status.conditions[?(@.type=="Failing")].message}' ----- -+ -This command returns a large traceback that has been edited for brevity: -+ -.Example output -[source,terminal] ----- -error reconciling NodeNetworkConfigurationPolicy at desired state apply: , failed to execute nmstatectl set --no-commit --timeout 480: 'exit status 1' '' -... -libnmstate.error.NmstateVerificationError: -desired -======= ---- -name: br1 -type: linux-bridge -state: up -bridge: - options: - group-forward-mask: 0 - mac-ageing-time: 300 - multicast-snooping: true - stp: - enabled: false - forward-delay: 15 - hello-time: 2 - max-age: 20 - priority: 32768 - port: - - name: ens01 -description: Linux bridge with the wrong port -ipv4: - address: [] - auto-dns: true - auto-gateway: true - auto-routes: true - dhcp: true - enabled: true -ipv6: - enabled: false -mac-address: 01-23-45-67-89-AB -mtu: 1500 - -current -======= ---- -name: br1 -type: linux-bridge -state: up -bridge: - options: - group-forward-mask: 0 - mac-ageing-time: 300 - multicast-snooping: true - stp: - enabled: false - forward-delay: 15 - hello-time: 2 - max-age: 20 - priority: 32768 - port: [] -description: Linux bridge with the wrong port -ipv4: - address: [] - auto-dns: true - auto-gateway: true - auto-routes: true - dhcp: true - enabled: true -ipv6: - enabled: false -mac-address: 01-23-45-67-89-AB -mtu: 1500 - -difference -========== ---- desired -+++ current -@@ -13,8 +13,7 @@ - hello-time: 2 - max-age: 20 - priority: 32768 -- port: -- - name: ens01 -+ port: [] - description: Linux bridge with the wrong port - ipv4: - address: [] - line 651, in _assert_interfaces_equal\n current_state.interfaces[ifname],\nlibnmstate.error.NmstateVerificationError: ----- -+ -The `NmstateVerificationError` lists the `desired` policy configuration, the `current` configuration of the policy on the node, and the `difference` highlighting the parameters that do not match. In this example, the `port` is included in the `difference`, which suggests that the problem is the port configuration in the policy. - -. To ensure that the policy is configured properly, view the network configuration for one or all of the nodes by requesting the `NodeNetworkState` object. The following command returns the network configuration for the `control-plane-1` node: -+ ----- -$ oc get nns control-plane-1 -o yaml ----- -+ -The output shows that the interface name on the nodes is `ens1` but the failed policy incorrectly uses `ens01`: -+ -.Example output -[source,yaml] ----- - - ipv4: - ... - name: ens1 - state: up - type: ethernet ----- - -. Correct the error by editing the existing policy: -+ -[source,terminal] ----- -$ oc edit nncp ens01-bridge-testfail ----- -+ -[source,yaml] ----- -... - port: - - name: ens1 ----- -+ -Save the policy to apply the correction. - -. Check the status of the policy to ensure it updated successfully: -+ -[source,terminal] ----- -$ oc get nncp ----- -+ -.Example output -[source,terminal] ----- -NAME STATUS -ens01-bridge-testfail SuccessfullyConfigured ----- - -The updated policy is successfully configured on all nodes in the cluster. diff --git a/modules/virt-troubleshooting-vm-import.adoc b/modules/virt-troubleshooting-vm-import.adoc deleted file mode 100644 index c14fbd09616e..000000000000 --- a/modules/virt-troubleshooting-vm-import.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// Module included in the following assemblies: -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc -[id='virt-troubleshooting-vm-import_{context}'] -= Troubleshooting a virtual machine import - -[id='logs_{context}'] -== Logs - -ifdef::virt-importing-vmware-vm[] -You can check the V2V Conversion pod log for errors. - -.Procedure - -. View the V2V Conversion pod name by running the following command: -+ -[source,terminal] ----- -$ oc get pods -n <namespace> | grep v2v <1> ----- -<1> Specify the namespace of your imported virtual machine. -+ -.Example output -[source,terminal] ----- -kubevirt-v2v-conversion-f66f7d-zqkz7 1/1 Running 0 4h49m ----- - -. View the V2V Conversion pod log by running the following command: -+ -[source,terminal] ----- -$ oc logs <kubevirt-v2v-conversion-f66f7d-zqkz7> -f -n <namespace> <1> ----- -<1> Specify the VM Conversion pod name and the namespace. -endif::[] -ifdef::virt-importing-rhv-vm[] -You can check the VM Import Controller pod log for errors. - -.Procedure - -. View the VM Import Controller pod name by running the following command: -+ -[source,terminal] ----- -$ oc get pods -n <namespace> | grep import <1> ----- -<1> Specify the namespace of your imported virtual machine. -+ -.Example output -[source,terminal] ----- -vm-import-controller-f66f7d-zqkz7 1/1 Running 0 4h49m ----- - -. View the VM Import Controller pod log by running the following command: -+ -[source,terminal] ----- -$ oc logs <vm-import-controller-f66f7d-zqkz7> -f -n <namespace> <1> ----- -<1> Specify the VM Import Controller pod name and the namespace. -endif::[] - -[id='error-messages_{context}'] -== Error messages - -ifdef::virt-importing-rhv-vm[] -The following error message might appear: - -* The following error message is displayed in the VM Import Controller pod log and the progress bar stops at 10% if the {VirtProductName} storage PV is not suitable: -+ -[source,terminal] ----- -Failed to bind volumes: provisioning failed for PVC ----- -+ -You must use a compatible storage class. The Cinder storage class is not supported. - -endif::[] - -ifdef::virt-importing-vmware-vm[] -The following error messages might appear: - -* If the VMware VM is not shut down before import, the imported virtual machine displays the error message, `Readiness probe failed` in the {product-title} console and the V2V Conversion pod log displays the following error message: -+ -[source,terminal] ----- -INFO - have error: ('virt-v2v error: internal error: invalid argument: libvirt domain ‘v2v_migration_vm_1’ is running or paused. It must be shut down in order to perform virt-v2v conversion',)" ----- - -* The following error message is displayed in the {product-title} console if a non-admin user tries to import a VM: -+ -[source,terminal] ----- -Could not load config map vmware-to-kubevirt-os in kube-public namespace -Restricted Access: configmaps "vmware-to-kubevirt-os" is forbidden: User cannot get resource "configmaps" in API group "" in the namespace "kube-public" ----- -+ -Only an admin user can import a VM. -endif::[] diff --git a/modules/virt-understanding-events.adoc b/modules/virt-understanding-events.adoc deleted file mode 100644 index 3e870e1bedb2..000000000000 --- a/modules/virt-understanding-events.adoc +++ /dev/null @@ -1,13 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-events.adoc - -[id="virt-understanding-events_{context}"] -= Understanding virtual machine events - -{product-title} events are records of important life-cycle information in a -namespace and are useful for monitoring and troubleshooting resource -scheduling, creation, and deletion issues. - -{VirtProductName} adds events for virtual machines and virtual machine instances. These -can be viewed from either the web console or the CLI. diff --git a/modules/virt-understanding-live-migration.adoc b/modules/virt-understanding-live-migration.adoc deleted file mode 100644 index ab90ebf7adbd..000000000000 --- a/modules/virt-understanding-live-migration.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-live-migration.adoc - -[id="virt-understanding-live-migration_{context}"] -= Understanding live migration - -Live migration is the process of moving a running virtual machine instance (VMI) to -another node in the cluster without interrupting the virtual workload or access. -If a VMI uses the `LiveMigrate` eviction strategy, it automatically migrates -when the node that the VMI runs on is placed into maintenance mode. You can also -manually start live migration by selecting a VMI to migrate. - -Virtual machines must have a persistent volume claim (PVC) with a shared -ReadWriteMany (RWX) access mode to be live migrated. - -[NOTE] -==== -Live migration is not supported for virtual machines that are -attached to an SR-IOV network interface. -==== diff --git a/modules/virt-understanding-logs.adoc b/modules/virt-understanding-logs.adoc deleted file mode 100644 index 41c87335149e..000000000000 --- a/modules/virt-understanding-logs.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-logs.adoc - -[id="virt-understanding-logs_{context}"] -= Understanding virtual machine logs - -Logs are collected for {product-title} builds, deployments, and pods. -In {VirtProductName}, virtual machine logs can be retrieved from the -virtual machine launcher pod in either the web console or the CLI. - -The `-f` option follows the log output in real time, which is useful for -monitoring progress and error checking. - -If the launcher pod is failing to start, use the -`--previous` option to see the logs of the last attempt. - -[WARNING] -==== -`ErrImagePull` and `ImagePullBackOff` errors can be caused by -an incorrect deployment configuration or problems with the images that are -referenced. -==== diff --git a/modules/virt-understanding-node-labeling-obsolete-cpu-models.adoc b/modules/virt-understanding-node-labeling-obsolete-cpu-models.adoc deleted file mode 100644 index 51f285d47595..000000000000 --- a/modules/virt-understanding-node-labeling-obsolete-cpu-models.adoc +++ /dev/null @@ -1,133 +0,0 @@ -// Module included in the following assemblies: -// * virt/node_maintenance/virt-managing-node-labeling-obsolete-cpu-models.adoc - -[id="virt-understanding-node-labeling-obsolete-cpu-models_{context}"] -= Understanding node labeling for obsolete CPU models - -To ensure that a node supports only valid CPU models for scheduled VMs, create a config map with a list of obsolete CPU models. When the `node-labeller` obtains the list of obsolete CPU models, it eliminates those CPU models and creates labels for valid CPU models. - -[NOTE] -==== -If you do not configure a config map with a list of obsolete CPU models, all CPU models are evaluated for labels, including obsolete CPU models that are not present in your environment. -==== - -Through the process of iteration, the list of base CPU features in the minimum CPU model are eliminated from the list of labels generated for the node. For example, an environment might have two supported CPU models: `Penryn` and `Haswell`. - -If `Penryn` is specified as the CPU model for `minCPU`, the `node-labeller` evaluates each base CPU feature for `Penryn` and compares it with each CPU feature supported by `Haswell`. If the CPU feature is supported by both `Penryn` and `Haswell`, the `node-labeller` eliminates that feature from the list of CPU features for creating labels. If a CPU feature is supported only by `Haswell` and not by `Penryn`, that CPU feature is included in the list of generated labels. The `node-labeller` follows this iterative process to eliminate base CPU features that are present in the minimum CPU model and create labels. - -The following example shows the complete list of CPU features for `Penryn` which is specified as the CPU model for `minCPU`: - -.Example of CPU features for Penryn ----- -apic -clflush -cmov -cx16 -cx8 -de -fpu -fxsr -lahf_lm -lm -mca -mce -mmx -msr -mtrr -nx -pae -pat -pge -pni -pse -pse36 -sep -sse -sse2 -sse4.1 -ssse3 -syscall -tsc ----- - -The following example shows the complete list of CPU features for `Haswell`: - -.Example of CPU features for Haswell ----- -aes -apic -avx -avx2 -bmi1 -bmi2 -clflush -cmov -cx16 -cx8 -de -erms -fma -fpu -fsgsbase -fxsr -hle -invpcid -lahf_lm -lm -mca -mce -mmx -movbe -msr -mtrr -nx -pae -pat -pcid -pclmuldq -pge -pni -popcnt -pse -pse36 -rdtscp -rtm -sep -smep -sse -sse2 -sse4.1 -sse4.2 -ssse3 -syscall -tsc -tsc-deadline -x2apic -xsave ----- - -The following example shows the list of node labels generated by the `node-labeller` after iterating and comparing the CPU features for `Penryn` with the CPU features for `Haswell`: - -.Example of node labels after iteration ----- -aes -avx -avx2 -bmi1 -bmi2 -erms -fma -fsgsbase -hle -invpcid -movbe -pcid -pclmuldq -popcnt -rdtscp -rtm -sse4.2 -tsc-deadline -x2apic -xsave ----- diff --git a/modules/virt-understanding-node-maintenance.adoc b/modules/virt-understanding-node-maintenance.adoc deleted file mode 100644 index 848c79597715..000000000000 --- a/modules/virt-understanding-node-maintenance.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_maintenance/virt-node-maintenance.adoc -// * virt/node_maintenance/virt-setting-node-maintenance.adoc - -[id="virt-understanding-node-maintenance_{context}"] -= Understanding node maintenance mode - -Placing a node into maintenance marks the node as unschedulable and drains all -the virtual machines and pods from it. Virtual machine instances that have a -`LiveMigrate` eviction strategy are live migrated to another node without loss -of service. This eviction strategy is configured by default in virtual machine -created from common templates but must be configured manually for custom -virtual machines. - -Virtual machine instances without an eviction strategy will be deleted on the -node and recreated on another node. - -[IMPORTANT] -==== -Virtual machines must have a persistent volume claim (PVC) with a shared -ReadWriteMany (RWX) access mode to be live migrated. -==== - - diff --git a/modules/virt-understanding-policy-attributes.adoc b/modules/virt-understanding-policy-attributes.adoc deleted file mode 100644 index 2d86a75c3c96..000000000000 --- a/modules/virt-understanding-policy-attributes.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assembly: -// -// * virt/virtual_machines/advanced_vm_management/virt-schedule-vms.adoc -// - -[id="understanding-policy-attributes_{context}"] -= Understanding policy attributes - -You can schedule a virtual machine (VM) by specifying a policy attribute and a CPU feature that is matched for compatibility when the VM is scheduled on a node. A policy attribute specified for a VM determines how that VM is scheduled on a node. - -[cols="30,70"] -|=== -|Policy attribute | Description - -|force -|The VM is forced to be scheduled on a node. This is true even if the host CPU does not support the VM's CPU. - -|require -|Default policy that applies to a VM if the VM is not configured with a specific CPU model and feature specification. If a node is not configured to support CPU node discovery with this default policy attribute or any one of the other policy attributes, VMs are not scheduled on that node. Either the host CPU must support the VM's CPU or the hypervisor must be able to emulate the supported CPU model. - -|optional -|The VM is added to a node if that VM is supported by the host's physical machine CPU. - -|disable -|The VM cannot be scheduled with CPU node discovery. - -|forbid -|The VM is not scheduled even if the feature is supported by the host CPU and CPU node discovery is enabled. -|=== diff --git a/modules/virt-understanding-scratch-space.adoc b/modules/virt-understanding-scratch-space.adoc deleted file mode 100644 index 24ef8bb839ef..000000000000 --- a/modules/virt-understanding-scratch-space.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc - -[id="virt-understanding-scratch-space_{context}"] -= Understanding scratch space - -The Containerized Data Importer (CDI) requires scratch space (temporary storage) to complete some operations, such as importing and uploading virtual machine images. -During this process, CDI provisions a scratch space PVC equal to the size of the PVC backing the destination data volume (DV). -The scratch space PVC is deleted after the operation completes or aborts. - -You can define the storage class that is used to bind the scratch space PVC in the `spec.config.scratchSpaceStorageClass` field of the `CDI` object. - -If the defined storage class does not match a storage class in the cluster, then the default storage class defined for the cluster is used. -If there is no default storage class defined in the cluster, the storage class used to provision the original DV or PVC is used. - -[NOTE] -==== -CDI requires requesting scratch space with a `file` volume mode, regardless of the PVC backing the origin data volume. -If the origin PVC is backed by `block` volume mode, you must define a storage class capable of provisioning `file` volume mode PVCs. -==== - -[discrete] -== Manual provisioning - -If there are no storage classes, CDI uses any PVCs in the project that match the size requirements for the image. -If there are no PVCs that match these requirements, the CDI import pod remains in a *Pending* state until an appropriate PVC is made available or until a timeout function kills the pod. diff --git a/modules/virt-understanding-smart-cloning.adoc b/modules/virt-understanding-smart-cloning.adoc deleted file mode 100644 index c2109687b3be..000000000000 --- a/modules/virt-understanding-smart-cloning.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-cloning-a-datavolume-using-smart-cloning.adoc - -[id="virt-understanding-smart-cloning_{context}"] -= Understanding smart-cloning - -When a data volume is smart-cloned, the following occurs: - -. A snapshot of the source persistent volume claim (PVC) is created. -. A PVC is created from the snapshot. -. The snapshot is deleted. diff --git a/modules/virt-understanding-virtio-drivers.adoc b/modules/virt-understanding-virtio-drivers.adoc deleted file mode 100644 index 840978143972..000000000000 --- a/modules/virt-understanding-virtio-drivers.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc -// * virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc - -//This file contains UI elements and/or package names that need to be updated. - -[id="virt-understanding-virtio-drivers_{context}"] -= Understanding VirtIO drivers - -VirtIO drivers are paravirtualized device drivers required for Microsoft Windows - virtual machines to run in {VirtProductName}. The supported drivers are -available in the `container-native-virtualization/virtio-win` container disk of the -link:https://access.redhat.com/containers/#/registry.access.redhat.com/container-native-virtualization/virtio-win[Red Hat Ecosystem Catalog]. - -The `container-native-virtualization/virtio-win` container disk must be attached to the virtual machine as a -SATA CD drive to enable driver installation. You can install VirtIO drivers during -Windows installation on the virtual machine or added to an -existing Windows installation. - -After the drivers are installed, the `container-native-virtualization/virtio-win` container disk can be removed -from the virtual machine. diff --git a/modules/virt-unpausing-vm-web.adoc b/modules/virt-unpausing-vm-web.adoc deleted file mode 100644 index 53863f88b8c5..000000000000 --- a/modules/virt-unpausing-vm-web.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-controlling-vm-states.adoc - -[id="virt-unpausing-vm-web_{context}"] -= Unpausing a virtual machine - -You can unpause a paused virtual machine from the web console. - -.Prerequisites - -* At least one of your virtual machines must have a status of *Paused*. -+ -[NOTE] -==== -You can pause virtual machines by using the `virtctl` client. -==== - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. - -. Click the *Virtual Machines* tab. - -. Find the row that contains the virtual machine that you want to unpause. - -. Navigate to the appropriate menu for your use case: - -* To stay on this page, where you can perform actions on multiple virtual machines: - -.. In the *Status* column, click *Paused*. - -* To view comprehensive information about the selected virtual machine before -you unpause it: - -.. Access the *Virtual Machine Overview* screen by clicking the name of the virtual -machine. - -.. Click the pencil icon that is located on the right side of *Status*. - -. In the confirmation window, click *Unpause* to unpause the virtual machine. diff --git a/modules/virt-updating-access-mode-for-live-migration.adoc b/modules/virt-updating-access-mode-for-live-migration.adoc deleted file mode 100644 index 1fa36dcdb4b1..000000000000 --- a/modules/virt-updating-access-mode-for-live-migration.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/live_migration/virt-live-migration.adoc - -[id="virt-updating-access-mode-for-live-migration_{context}"] -= Updating access mode for live migration - -For live migration to function properly, you must use the -ReadWriteMany (RWX) access mode. Use this -procedure to update the access mode, if needed. - -.Procedure -* To set the RWX access mode, run the following `oc patch` command: -+ -[source,terminal] ----- -$ oc patch -n openshift-cnv \ - cm kubevirt-storage-class-defaults \ - -p '{"data":{"'$<STORAGE_CLASS>'.accessMode":"ReadWriteMany"}}' ----- diff --git a/modules/virt-updating-imported-vm-network-name.adoc b/modules/virt-updating-imported-vm-network-name.adoc deleted file mode 100644 index 7bd612b74105..000000000000 --- a/modules/virt-updating-imported-vm-network-name.adoc +++ /dev/null @@ -1,35 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc - -[id="virt-updating-imported-vmware-vm-network-name_{context}"] -= Updating the NIC name of an imported virtual machine - -You must update the NIC name of a virtual machine that you imported from VMware to conform to {VirtProductName} naming conventions. - -.Procedure - -. Log in to the virtual machine. -. Navigate to the `/etc/sysconfig/network-scripts` directory. -. Rename the network configuration file: -+ -[source,terminal] ----- -$ mv vmnic0 ifcfg-eth0 <1> ----- -<1> The first network configuration file is named `ifcfg-eth0`. Additional network configuration files are numbered sequentially, for example, `ifcfg-eth1`, `ifcfg-eth2`. - -. Update the `NAME` and `DEVICE` parameters in the network configuration file: -+ -[source,terminal] ----- -NAME=eth0 -DEVICE=eth0 ----- - -. Restart the network: -+ -[source,terminal] ----- -$ systemctl restart network ----- diff --git a/modules/virt-upgrade-pathways.adoc b/modules/virt-upgrade-pathways.adoc deleted file mode 100644 index bd89d0002dd8..000000000000 --- a/modules/virt-upgrade-pathways.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/upgrading-virt.adoc - -[id="virt-upgrade-pathways_{context}"] -= Upgrade pathways for minor releases - -The upgrade pathway is different depending on the 2.4.z version of {VirtProductName} that you have installed. - -[IMPORTANT] -==== -You must upgrade your {product-title} to 4.7 before upgrading the minor release of {VirtProductName}. -==== - -[id="virt-upgrade-pathways-2.4.3_{context}"] -== Upgrading from 2.4.3 to {HCOVersion} - -You must first upgrade to 2.5.0 before you can upgrade the z-stream. You can then upgrade from 2.5.0 to 2.5.1 and then to 2.5.2 and so on. - -If your *Approval Strategy* is *Automatic*, which is the default, {VirtProductName} upgrades the z-stream automatically after you have upgraded to 2.5.0. - -[id="virt-upgrade-pathways-2.4.4_{context}"] -== Upgrading from 2.4.4 or 2.4.5 to {HCOVersion} - -You can upgrade from 2.4.4 or 2.4.5 directly to 2.5.2. You can then upgrade from 2.5.2 to 2.5.3 and so on. - -If your *Approval Strategy* is *Automatic*, which is the default, {VirtProductName} upgrades the z-stream automatically after you have upgraded to 2.5.2. diff --git a/modules/virt-upgrading-virt.adoc b/modules/virt-upgrading-virt.adoc deleted file mode 100644 index 70f139070514..000000000000 --- a/modules/virt-upgrading-virt.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/upgrading-virt.adoc - -[id="virt-upgrading-virt_{context}"] -= Upgrading {VirtProductName} to the next minor version - -You can manually upgrade {VirtProductName} to the next minor version by using the -{product-title} web console to change the channel of your Operator subscription. - -.Prerequisites - -* Log in to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Access the {product-title} web console and navigate to *Operators* -> *Installed Operators*. - -. Click *{VirtProductName}* to open the *Operator Details* page. - -. Click the *Subscription* tab to open the *Subscription Overview* page. - -. In the *Channel* pane, click the pencil icon on the right side of the -version number to open the *Change Subscription Update Channel* window. - -. Select *stable*. This ensures that you install the version of {VirtProductName} -that is compatible with your {product-title} version. - -. Click *Save*. - -. Check the status of the upgrade by navigating to *Operators* -> *Installed Operators*. -You can also check the status by running the following `oc` command: -+ -[source,terminal] ----- -$ oc get csv -n openshift-cnv ----- diff --git a/modules/virt-uploading-image-web.adoc b/modules/virt-uploading-image-web.adoc deleted file mode 100644 index 00d07e128884..000000000000 --- a/modules/virt-uploading-image-web.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-web.adoc - -[id="virt-uploading-image-web_{context}"] -= Uploading an image file using the web console - -Use the web console to upload an image file to a new persistent volume claim (PVC). -You can later use this PVC to attach the image to new virtual machines. - -.Prerequisites - -* You must have one of the following: -** A raw virtual machine image file in either ISO or IMG format. -** A virtual machine image file in QCOW2 format. -* For best results, compress your image file according to the following guidelines before you upload it: -** Compress a raw image file by using `xz` or `gzip`. -+ -[NOTE] -==== -Using a compressed raw image file results in the most efficient upload. -==== -** Compress a QCOW2 image file by using the method that is recommended for your client: -*** If you use a Linux client, _sparsify_ the QCOW2 file by using the -link:https://libguestfs.org/virt-sparsify.1.html[virt-sparsify] tool. -*** If you use a Windows client, compress the QCOW2 file by using `xz` or `gzip`. - -.Procedure - -. From the side menu of the web console, click *Storage* -> *Persistent Volume Claims*. - -. Click the *Create Persistent Volume Claim* drop-down list to expand it. - -. Click *With Data Upload Form* to open the *Upload Data to Persistent Volume Claim* page. - -. Click *Browse* to open the file manager and select the image that you want to upload, or drag the file into the *Drag a file here or browse to upload* field. - -. Optional: Set this image as the default image for a specific operating system. - -.. Select the *Attach this data to a virtual machine operating system* check box. - -.. Select an operating system from the list. - -. The *Persistent Volume Claim Name* field is automatically filled with a unique name and cannot be edited. Take note of the name assigned to the PVC so that you can identify it later, if necessary. - -. Select a storage class from the *Storage Class* list. - -. In the *Size* field, enter the size value for the PVC. Select the corresponding unit of measurement from the drop-down list. -+ -[WARNING] -==== -The PVC size must be larger than the size of the image file. -==== - -. Select an *Access Mode* that matches the storage class that you selected. - -. Click *Upload*. diff --git a/modules/virt-uploading-local-disk-image-dv.adoc b/modules/virt-uploading-local-disk-image-dv.adoc deleted file mode 100644 index a44e44d03db4..000000000000 --- a/modules/virt-uploading-local-disk-image-dv.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc - -[id="virt-uploading-local-disk-image-dv_{context}"] -= Uploading a local disk image to a data volume - -You can use the `virtctl` CLI utility to upload a local disk image from -a client machine to a data volume (DV) in your cluster. You can use a DV that -already exists in your cluster or create a new DV during this procedure. - -[NOTE] -==== -After you upload a local disk image, you can add it to a virtual machine. -==== - -.Prerequisites - -* You must have one of the following: -** A raw virtual machine image file in either ISO or IMG format. -** A virtual machine image file in QCOW2 format. - -* For best results, compress your image file according to the following guidelines before you upload it: -** Compress a raw image file by using `xz` or `gzip`. -+ -[NOTE] -==== -Using a compressed raw image file results in the most efficient upload. -==== -** Compress a QCOW2 image file by using the method that is recommended for your client: -*** If you use a Linux client, _sparsify_ the QCOW2 file by using the -link:https://libguestfs.org/virt-sparsify.1.html[virt-sparsify] tool. -*** If you use a Windows client, compress the QCOW2 file by using `xz` or `gzip`. - -* The `kubevirt-virtctl` package must be installed on the client machine. - -* The client machine must be configured to trust the {product-title} router's -certificate. - -.Procedure - -. Identify the following items: -* The name of the upload data volume that you want to use. If this data volume -does not exist, it is created automatically. -* The size of the data volume, if you want it to be created during the upload -procedure. The size must be greater than or equal to the size of the disk image. -* The file location of the virtual machine disk image that you want to upload. - -. Upload the disk image by running the `virtctl image-upload` command. -Specify the parameters that you identified in the previous step. -For example: -+ -[source,terminal] ----- -$ virtctl image-upload dv <datavolume_name> \ <1> ---size=<datavolume_size> \ <2> ---image-path=</path/to/image> \ <3> ----- -<1> The name of the data volume. -<2> The size of the data volume. For example: `--size=500Mi`, `--size=1G` -<3> The file path of the virtual machine disk image. -+ -[NOTE] -==== -* If you do not want to create a new data volume, omit the `--size` parameter and -include the `--no-create` flag. - -* To allow insecure server connections when using HTTPS, use the `--insecure` -parameter. Be aware that when you use the `--insecure` flag, the authenticity of -the upload endpoint is *not* verified. -==== - -. Optional. To verify that a data volume was created, view all data volumes -by running the following command: -+ -[source,terminal] ----- -$ oc get dvs ----- diff --git a/modules/virt-uploading-local-disk-image-pvc.adoc b/modules/virt-uploading-local-disk-image-pvc.adoc deleted file mode 100644 index fb87c6fad0f2..000000000000 --- a/modules/virt-uploading-local-disk-image-pvc.adoc +++ /dev/null @@ -1,55 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-virtctl.adoc - -[id="virt-uploading-local-disk-image-pvc_{context}"] -= Uploading a local disk image to a new persistent volume claim - -You can use the `virtctl` CLI utility to upload a virtual machine disk image from a client machine to your cluster. Uploading the disk image creates a persistent volume claim (PVC) that you can associate with a virtual machine. - -.Prerequisites - -* You must have one of the following: -** A raw virtual machine image file in either ISO or IMG format. -** A virtual machine image file in QCOW2 format. - -* For best results, compress your image file according to the following guidelines before you upload it: -** Compress a raw image file by using `xz` or `gzip`. -+ -[NOTE] -==== -Using a compressed raw image file results in the most efficient upload. -==== -** Compress a QCOW2 image file by using the method that is recommended for your client: -*** If you use a Linux client, _sparsify_ the QCOW2 file by using the -link:https://libguestfs.org/virt-sparsify.1.html[virt-sparsify] tool. -*** If you use a Windows client, compress the QCOW2 file by using `xz` or `gzip`. - -* The `kubevirt-virtctl` package must be installed on the client machine. - -* The client machine must be configured to trust the {product-title} router's certificate. - -.Procedure - -. Identify the following items: -* File location of the VM disk image you want to upload. -* Name and size required for the resulting PVC. - -. Run the `virtctl image-upload` command to upload your VM image. You must specify the PVC name, PVC size, and file location. For example: -+ -[source,terminal] ----- -$ virtctl image-upload --pvc-name=<upload-fedora-pvc> --pvc-size=<2Gi> --image-path=</images/fedora.qcow2> ----- -+ -[WARNING] -==== -To allow insecure server connections when using HTTPS, use the `--insecure` parameter. Be aware that when you use the `--insecure` flag, the authenticity of the upload endpoint is *not* verified. -==== - -. To verify that the PVC was created, view all PVC objects: -+ -[source,terminal] ----- -$ oc get pvc ----- diff --git a/modules/virt-using-hostpath-provisioner.adoc b/modules/virt-using-hostpath-provisioner.adoc deleted file mode 100644 index 78478ce393b0..000000000000 --- a/modules/virt-using-hostpath-provisioner.adoc +++ /dev/null @@ -1,72 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc - -[id="virt-using-hostpath-provisioner_{context}"] -= Using the hostpath provisioner to enable local storage - -To deploy the hostpath provisioner and enable your virtual machines to use local -storage, first create a `HostPathProvisioner` custom resource. - -.Prerequisites - -* Create a backing directory on each node for the persistent volumes (PVs) -that the hostpath provisioner creates. - -* Apply the SELinux context `container_file_t` to the PV -backing directory on each node. For example: -+ -[source,terminal] ----- -$ sudo chcon -t container_file_t -R </path/to/backing/directory> ----- -+ -[NOTE] -==== -If you use Red Hat Enterprise Linux CoreOS 8 workers, you must configure SELinux -by using a `MachineConfig` manifest instead. -==== - -.Procedure - -. Create the `HostPathProvisioner` custom resource file. For example: -+ -[source,terminal] ----- -$ touch hostpathprovisioner_cr.yaml ----- - -. Edit the file, ensuring that the `spec.pathConfig.path` value is the directory -where you want the hostpath provisioner to create PVs. For example: -+ -[source,yaml] ----- -apiVersion: hostpathprovisioner.kubevirt.io/v1beta1 -kind: HostPathProvisioner -metadata: - name: hostpath-provisioner -spec: - imagePullPolicy: IfNotPresent - pathConfig: - path: "</path/to/backing/directory>" <1> - useNamingPrefix: false <2> - workload: <3> ----- -<1> Specify the backing directory where you want the provisioner to create PVs. -<2> Change this value to `true` if you want to use the name of the persistent volume claim (PVC) -that is bound to the created PV as the prefix of the directory name. -<3> Optional: You can use the `spec.workload` field to configure node placement rules for the hostpath provisioner. -+ -[NOTE] -==== -If you did not create the backing directory, the provisioner attempts to create -it for you. If you did not apply the `container_file_t` SELinux context, this can cause -`Permission denied` errors. -==== - -. Create the custom resource in the `openshift-cnv` namespace: -+ -[source,terminal] ----- -$ oc create -f hostpathprovisioner_cr.yaml -n openshift-cnv ----- diff --git a/modules/virt-using-supported-boot-source-names.adoc b/modules/virt-using-supported-boot-source-names.adoc deleted file mode 100644 index 0500cc0a19ba..000000000000 --- a/modules/virt-using-supported-boot-source-names.adoc +++ /dev/null @@ -1,52 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virtual_disks/virt-creating-and-using-boot-sources.adoc - -[id="virt-using-supported-boot-source-names_{context}"] -= Supported boot source names - -When you add boot sources, you associate them with templates for specific operating systems. - -It is important that the boot source volume name matches the predefined name of the template. If the volume name does not match the name defined by the template, you will be unable to add the boot source and use it to create virtual machines. - -If you add a boot source by using the web console, you do not need to supply the boot source name because it is already associated with the appropriate template. When using the CLI, you must specify the supported boot source name in your YAML code when creating a volume. - -Use the following table to determine the supported name of a boot source for various operating systems. - -[cols="2",options="header"] -.Supported boot source names for operating systems -|=== -|To create a boot source for this OS: -|Name the volume: - -|Fedora -|fedora - -|Centos 7 -|centos7 - -|Centos 8 -|centos8 - -|Red Hat Enterprise Linux 6 -|rhel6 - -|Red Hat Enterprise Linux 7 -|rhel7 - -|Red Hat Enterprise Linux 8 -|rhel8 - -|Windows 10 -|win10 - -|Windows 2012 Server Release 2 -|win2k12r2 - -|Windows 2016 Server -|win2k16 - -|Windows 2019 Server -|win2k19 - -|=== diff --git a/modules/virt-viewing-namespace-events-cli.adoc b/modules/virt-viewing-namespace-events-cli.adoc deleted file mode 100644 index 4a525bc096f0..000000000000 --- a/modules/virt-viewing-namespace-events-cli.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-events.adoc - -[id="virt-viewing-namespace-events-cli_{context}"] -= Viewing namespace events in the CLI - -Use the {product-title} client to get the events for a namespace. - -.Procedure - -* In the namespace, use the `oc get` command: -+ -[source,terminal] ----- -$ oc get events ----- - diff --git a/modules/virt-viewing-network-state-of-node.adoc b/modules/virt-viewing-network-state-of-node.adoc deleted file mode 100644 index dd42b98826d4..000000000000 --- a/modules/virt-viewing-network-state-of-node.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/node_network/virt-observing-node-network-state.adoc -// * networking/k8s_nmstate/k8s-observing-node-network-state.adoc - -[id="virt-viewing-network-state-of-node_{context}"] -= Viewing the network state of a node - -A `NodeNetworkState` object exists on every node in the cluster. This object is periodically updated and captures the state of the network for that node. - -.Procedure - -. List all the `NodeNetworkState` objects in the cluster: -+ -[source,terminal] ----- -$ oc get nns ----- - -. Inspect a `NodeNetworkState` object to view the network on that node. The output in this example has been redacted for clarity: -+ -[source,terminal] ----- -$ oc get nns node01 -o yaml ----- -+ -.Example output -[source,yaml] ----- -apiVersion: nmstate.io/v1beta1 -kind: NodeNetworkState -metadata: - name: node01 <1> -status: - currentState: <2> - dns-resolver: -... - interfaces: -... - route-rules: -... - routes: -... - lastSuccessfulUpdateTime: "2020-01-31T12:14:00Z" <3> ----- -<1> The name of the `NodeNetworkState` object is taken from the node. -<2> The `currentState` contains the complete network configuration for the node, including DNS, interfaces, and routes. -<3> Timestamp of the last successful update. This is updated periodically as long as the node is reachable and can be used to evalute the freshness of the report. diff --git a/modules/virt-viewing-qemu-guest-agent-information-web.adoc b/modules/virt-viewing-qemu-guest-agent-information-web.adoc deleted file mode 100644 index e00db5e701f3..000000000000 --- a/modules/virt-viewing-qemu-guest-agent-information-web.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-viewing-qemu-guest-agent-information.adoc - -[id="virt-viewing-qemu-guest-agent-information-web_{context}"] -= Viewing the QEMU guest agent information in the web console - -You can use the web console to view information for virtual machines that is passed by the QEMU guest agent to the host. - -.Procedure - -. Click *Workloads* -> *Virtual Machines* from the side menu. - -. Click the *Virtual Machines* tab. - -. Select a virtual machine name to open the *Virtual Machine Overview* screen and view the *Details* pane. - -. Click *Logged in users* to view the *Details* tab that shows information for users. - -. Click the *Disks* tab to view information about the file systems. diff --git a/modules/virt-viewing-resource-events-cli.adoc b/modules/virt-viewing-resource-events-cli.adoc deleted file mode 100644 index c615ae18cde5..000000000000 --- a/modules/virt-viewing-resource-events-cli.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-events.adoc - -[id="virt-viewing-resource-events-cli_{context}"] -= Viewing resource events in the CLI - -Events are included in the resource description, which you can get using the -{product-title} client. - -.Procedure - -* In the namespace, use the `oc describe` command. The following example shows -how to get the events for a virtual machine, a virtual machine instance, and the -virt-launcher pod for a virtual machine: -+ -[source,terminal] ----- -$ oc describe vm <vm> ----- -+ -[source,terminal] ----- -$ oc describe vmi <vmi> ----- -+ -[source,terminal] ----- -$ oc describe pod virt-launcher-<name> ----- - diff --git a/modules/virt-viewing-virtual-machine-logs-cli.adoc b/modules/virt-viewing-virtual-machine-logs-cli.adoc deleted file mode 100644 index a4a83028dd19..000000000000 --- a/modules/virt-viewing-virtual-machine-logs-cli.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-logs.adoc - -[id="virt-viewing-virtual-machine-logs-cli_{context}"] -= Viewing virtual machine logs in the CLI - -Get virtual machine logs from the virtual machine launcher pod. - -.Procedure - -* Use the following command: -+ -[source,terminal] ----- -$ oc logs <virt-launcher-name> ----- diff --git a/modules/virt-viewing-virtual-machine-logs-web.adoc b/modules/virt-viewing-virtual-machine-logs-web.adoc deleted file mode 100644 index 10423351f655..000000000000 --- a/modules/virt-viewing-virtual-machine-logs-web.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-logs.adoc - -[id="virt-viewing-virtual-machine-logs-web_{context}"] -= Viewing virtual machine logs in the web console - -Get virtual machine logs from the associated virtual machine launcher pod. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a virtual machine to open the *Virtual Machine Overview* screen. -. In the *Details* tab, click the `virt-launcher-<name>` pod in the *Pod* -section. -. Click *Logs*. diff --git a/modules/virt-viewing-vm-events-web.adoc b/modules/virt-viewing-vm-events-web.adoc deleted file mode 100644 index fdce4d9fdc96..000000000000 --- a/modules/virt-viewing-vm-events-web.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/logging_events_monitoring/virt-events.adoc - -[id="virt-viewing-vm-events-web_{context}"] -= Viewing the events for a virtual machine in the web console - -You can view the stream events for a running a virtual machine from the -*Virtual Machine Overview* panel of the web console. - -The &#9646;&#9646; button pauses the events stream. + -The &#9654; button continues a paused events stream. - -.Procedure - -. Click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a virtual machine to open the *Virtual Machine Overview* screen. -. Click *Events* to view all events for the virtual machine. diff --git a/modules/virt-viewing-vmi-ip-cli.adoc b/modules/virt-viewing-vmi-ip-cli.adoc deleted file mode 100644 index 8e0befeaac83..000000000000 --- a/modules/virt-viewing-vmi-ip-cli.adoc +++ /dev/null @@ -1,51 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-viewing-ip-of-vm-vnic.adoc - -[id="virt-viewing-vmi-ip-cli_{context}"] -= Viewing the IP address of a virtual machine interface in the CLI - -The network interface configuration is included in the `oc describe vmi <vmi_name>` command. - -You can also view the IP address information by running `ip addr` on the virtual -machine, or by running `oc get vmi <vmi_name> -o yaml`. - -.Procedure - -* Use the `oc describe` command to display the virtual machine interface configuration: -+ -[source,terminal] ----- -$ oc describe vmi <vmi_name> ----- -+ -.Example output -[source,yaml] ----- -... -Interfaces: - Interface Name: eth0 - Ip Address: 10.244.0.37/24 - Ip Addresses: - 10.244.0.37/24 - fe80::858:aff:fef4:25/64 - Mac: 0a:58:0a:f4:00:25 - Name: default - Interface Name: v2 - Ip Address: 1.1.1.7/24 - Ip Addresses: - 1.1.1.7/24 - fe80::f4d9:70ff:fe13:9089/64 - Mac: f6:d9:70:13:90:89 - Interface Name: v1 - Ip Address: 1.1.1.1/24 - Ip Addresses: - 1.1.1.1/24 - 1.1.1.2/24 - 1.1.1.4/24 - 2001:de7:0:f101::1/64 - 2001:db8:0:f101::1/64 - fe80::1420:84ff:fe10:17aa/64 - Mac: 16:20:84:10:17:aa ----- - diff --git a/modules/virt-viewing-vmi-ip-web.adoc b/modules/virt-viewing-vmi-ip-web.adoc deleted file mode 100644 index 99ecd0401320..000000000000 --- a/modules/virt-viewing-vmi-ip-web.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-viewing-ip-of-vm-nic.adoc - -[id="virt-viewing-vmi-ip-web_{context}"] -= Viewing the IP address of a virtual machine interface in the web console - -The IP information displays in the *Virtual Machine Overview* screen for the virtual machine. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a virtual machine name to open the *Virtual Machine Overview* screen. - -The information for each attached NIC is displayed under *IP Address*. diff --git a/modules/virt-virtctl-commands.adoc b/modules/virt-virtctl-commands.adoc deleted file mode 100644 index 2d6ad72774b4..000000000000 --- a/modules/virt-virtctl-commands.adoc +++ /dev/null @@ -1,84 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virt-using-the-cli-tools.adoc - -[id="virt-virtctl-commands_{context}"] -= Virtctl client commands - -The `virtctl` client is a command-line utility for managing {VirtProductName} -resources. The following table contains the `virtctl` commands used throughout -the {VirtProductName} documentation. - -To view a list of options that you can use with a command, run it with the `-h` or `--help` flag. For example: - -[source,terminal] ----- -$ virtctl image-upload -h ----- - -.`virtctl` client commands - -[width="100%",cols="42%,58%",options="header",] -|=== -|Command |Description - -|`virtctl start <vm_name>` -|Start a virtual machine. - -|`virtctl stop <vm_name>` -|Stop a virtual machine. - -|`virtctl pause vm\|vmi <object_name>` -|Pause a virtual machine or virtual machine instance. The machine state is kept -in memory. - -|`virtctl unpause vm\|vmi <object_name>` -|Unpause a virtual machine or virtual machine instance. - -|`virtctl migrate <vm_name>` -|Migrate a virtual machine. - -|`virtctl rename <vm_name> <new_vm_name>` -|Rename a stopped virtual machine. - -|`virtctl restart <vm_name>` -|Restart a virtual machine. - -|`virtctl expose <vm_name>` -|Create a service that forwards a designated port -of a virtual machine or virtual machine instance and expose the service on -the specified port of the node. - -|`virtctl console <vmi_name>` -|Connect to a serial console of a virtual machine instance. - -|`virtctl vnc --kubeconfig=$KUBECONFIG <vmi_name>` -|Open a VNC (Virtual Network Client) connection to a virtual machine instance. Access the graphical console of a virtual machine instance through a VNC which requires a remote viewer on your local machine. - -|`virtctl vnc --kubeconfig=$KUBECONFIG --proxy-only=true <vmi-name>` -|Display the port number and connect manually to the virtual machine instance by using any viewer through the VNC connection. - -|`virtctl vnc --kubeconfig=$KUBECONFIG --port=<port-number> <vmi-name>` -|Specify a port number to run the proxy on the specified port, if that port is available. If a port number is not specified, the proxy runs on a random port. - -|`virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create` -|Upload a virtual machine image to a data volume that already exists. - -|`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>` -|Upload a virtual machine image to a new data volume. - -|`virtctl version` -|Display the client and server version information. - -|`virtctl help` -|Display a descriptive list of `virtctl` commands. - -|`virtctl fslist <vmi_name>` -|Return a full list of file systems available on the guest machine. - -|`virtctl guestosinfo <vmi_name>` -|Return guest agent information about the operating system. - -|`virtctl userlist <vmi_name>` -|Return a full list of logged-in users on the guest machine. -|=== diff --git a/modules/virt-vm-create-nic-web.adoc b/modules/virt-vm-create-nic-web.adoc deleted file mode 100644 index 6f17abf2a061..000000000000 --- a/modules/virt-vm-create-nic-web.adoc +++ /dev/null @@ -1,18 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc - -[id="virt-vm-create-nic-web_{context}"] -= Creating a NIC for a virtual machine - -Create and attach additional NICs to a virtual machine from the web console. - -.Procedure - -. In the correct project in the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a virtual machine to open the *Virtual Machine Overview* screen. -. Click *Network Interfaces* to display the NICs already attached to the virtual machine. -. Click *Add Network Interface* to create a new slot in the list. -. Fill in the *Name*, *Model*, *Network*, *Type*, and *MAC Address* for the new NIC. -. Click the *Add* button to save and attach the NIC to the virtual machine. diff --git a/modules/virt-vm-rdp-console-web.adoc b/modules/virt-vm-rdp-console-web.adoc deleted file mode 100644 index db3b9c7e3f41..000000000000 --- a/modules/virt-vm-rdp-console-web.adoc +++ /dev/null @@ -1,42 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-vm-rdp-console-web_{context}"] -= Connecting to the RDP console - -The desktop viewer console, which utilizes the Remote Desktop Protocol (RDP), -provides a better console experience for connecting to Windows virtual machines. - -To connect to a Windows virtual machine with RDP, download the `console.rdp` -file for the virtual machine from the *Consoles* tab in the -*Virtual Machine Details* screen of the web console and supply it to your -preferred RDP client. - -.Prerequisites - -* A running Windows virtual machine with the QEMU guest agent installed. The -`qemu-guest-agent` is included in the VirtIO drivers. -* A layer-2 NIC attached to the virtual machine. -* An RDP client installed on a machine on the same network as the -Windows virtual machine. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a Windows virtual machine to open the *Virtual Machine Overview* screen. -. Click the *Console* tab. -. In the *Console* list, select *Desktop Viewer*. -. In the *Network Interface* list, select the layer-2 NIC. -. Click *Launch Remote Desktop* to download the `console.rdp` file. -. Open an RDP client and reference the `console.rdp` file. For example, using -*remmina*: -+ -[source,terminal] ----- -$ remmina --connect /path/to/console.rdp ----- - -. Enter the *Administrator* user name and password to connect to the -Windows virtual machine. diff --git a/modules/virt-vm-serial-console-web.adoc b/modules/virt-vm-serial-console-web.adoc deleted file mode 100644 index d1bcad5a8d6d..000000000000 --- a/modules/virt-vm-serial-console-web.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-accessing-vm-consoles.adoc - -[id="virt-vm-serial-console-web_{context}"] -= Connecting to the serial console - -Connect to the *Serial Console* of a running virtual machine from the *Console* -tab in the *Virtual Machine Overview* screen of the web console. - -.Procedure - -. In the {VirtProductName} console, click *Workloads* -> *Virtualization* from the side menu. -. Click the *Virtual Machines* tab. -. Select a virtual machine to open the *Virtual Machine Overview* page. -. Click *Console*. The VNC console opens by default. -. Click the *VNC Console* drop-down list and select *Serial Console*. -. Optional: Open the serial console in a separate window by clicking *Open Console in New Window*. - diff --git a/modules/virt-vm-storage-volume-types.adoc b/modules/virt-vm-storage-volume-types.adoc deleted file mode 100644 index 54d3fc0f74ef..000000000000 --- a/modules/virt-vm-storage-volume-types.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc - -[id="virt-vm-storage-volume-types_{context}"] -= Virtual machine storage volume types - -[cols="1a,1a"] -|=== -|Storage volume type |Description - -|ephemeral -|A local copy-on-write (COW) image that uses a network volume as a read-only backing store. The backing volume must be a *PersistentVolumeClaim*. The ephemeral image is created when the virtual machine starts and stores all writes locally. The ephemeral image is discarded when the virtual machine is stopped, restarted, or deleted. The backing volume (PVC) is not mutated in any way. - -|persistentVolumeClaim -|Attaches an available PV to a virtual machine. Attaching a PV allows for the virtual machine data to persist between sessions. - -Importing an existing virtual machine disk into a PVC by using CDI and attaching the PVC to a virtual machine instance is the recommended method for importing existing virtual machines into {product-title}. There are some requirements for the disk to be used within a PVC. - -|dataVolume -|Data volumes build on the `persistentVolumeClaim` disk type by managing the process of preparing the virtual machine disk via an import, clone, or upload operation. VMs that use this volume type are guaranteed not to start until the volume is ready. - -Specify `type: dataVolume` or `type: ""`. If you specify any other value for `type`, such as `persistentVolumeClaim`, a warning is displayed, and the virtual machine does not start. - -|cloudInitNoCloud -|Attaches a disk that contains the referenced cloud-init NoCloud data source, providing user data and metadata to the virtual machine. A cloud-init installation is required inside the virtual machine disk. - -|containerDisk -|References an image, such as a virtual machine disk, that is stored in the container image registry. The image is pulled from the registry and attached to the virtual machine as a disk when the virtual machine is launched. - -A `containerDisk` volume is not limited to a single virtual machine and is useful for creating large numbers of virtual machine clones that do not require persistent storage. - -Only RAW and QCOW2 formats are supported disk types for the container image registry. QCOW2 is recommended for reduced image size. - -[NOTE] -==== -A `containerDisk` volume is ephemeral. It is discarded when the virtual machine is stopped, restarted, or deleted. A `containerDisk` volume is useful for read-only file systems such as CD-ROMs or for disposable virtual machines. -==== - -|emptyDisk -|Creates an additional sparse QCOW2 disk that is tied to the life-cycle of the virtual machine interface. The data survives guest-initiated reboots in the virtual machine but is discarded when the virtual machine stops or is restarted from the web console. The empty disk is used to store application dependencies and data that otherwise exceeds the limited temporary file system of an ephemeral disk. - -The disk *capacity* size must also be provided. - -|=== diff --git a/modules/virt-vm-wizard-fields-web.adoc b/modules/virt-vm-wizard-fields-web.adoc deleted file mode 100644 index 8453618d98fd..000000000000 --- a/modules/virt-vm-wizard-fields-web.adoc +++ /dev/null @@ -1,105 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/virtual_machines/virt-create-vms.adoc -// * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc -// * virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc -// * virt/vm_templates/virt-creating-vm-template.adoc - -// VM wizard includes additional options to VM template wizard -// Call appropriate attribute in the assembly - -[id="virt-vm-wizard-fields-web_{context}"] -ifdef::virtualmachine[] -= Virtual machine wizard fields -endif::[] -ifdef::vmtemplate[] -= Virtual machine template wizard fields -endif::[] - -|=== -|Name |Parameter |Description - -ifdef::vmtemplate[] -|Template -| -|Template from which to create the virtual machine. Selecting a template will automatically complete other fields. -endif::[] - -|Name -| -|The name can contain lowercase letters (`a-z`), numbers (`0-9`), and hyphens (`-`), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, periods (`.`), or special characters. - -ifdef::vmtemplate[] -|Template provider -| -|The name of the user who is creating the template for the cluster or any meaningful name that identifies this template. -endif::[] - -ifdef::vmtemplate[] -.2+|Template support -|No additional support -|This template does not have additional support in the cluster. - -|Support by template provider -|This template is supported by the template provider. -endif::[] - -|Description -| -|Optional description field. - -|Operating System -| -ifdef::virtualmachine[] -|The operating system that is selected for the virtual machine in the template. You cannot edit this field when creating a virtual machine from a template. -endif::[] -ifdef::vmtemplate[] -|The operating system that is selected for the virtual machine. Selecting an operating system automatically selects the default *Flavor* and *Workload Type* for that operating system. -endif::[] - -.4+|Boot Source -|Import via URL (creates PVC) -|Import content from an image available from an *HTTP* or *S3* endpoint. Example: Obtaining a URL link from the web page with the operating system image. - -|Clone existing PVC (creates PVC) -|Select an existent persistent volume claim available on the cluster and clone it. - -|Import via Registry (creates PVC) -|Provision virtual machine from a bootable operating system container located in a registry accessible from the cluster. Example: `_kubevirt/cirros-registry-disk-demo_`. - -|PXE (network boot - adds network interface) -|Boot an operating system from a server on the network. Requires a PXE bootable network attachment definition. - -|Persistent Volume Claim project -| -|Project name that you want to use for cloning the PVC. - -|Persistent Volume Claim name -| -|PVC name that should apply to this virtual machine template if you are cloning an existing PVC. - -|Mount this as a CD-ROM boot source -| -|A CD-ROM requires an additional disk for installing the operating system. Select the checkbox to add a disk and customize it later. - -|Flavor -|Tiny, Small, Medium, Large, Custom -|Presets that determine the amount of CPU and memory allocated to the virtual machine. The presets displayed for *Flavor* are determined by the operating system. - -.3+|Workload Type - -|Desktop -|A virtual machine configuration for use on a desktop. Ideal for consumption on a small scale. Recommended for use with the web console. - -|Server -|Balances performance and it is compatible with a wide range of server workloads. - -|High-Performance -|A virtual machine configuration that is optimized for high-performance workloads. - -ifdef::virtualmachine[] -|Start this virtual machine after creation. -| -|This checkbox is selected by default and the virtual machine starts running after creation. Clear the checkbox if you do not want the virtual machine to start when it is created. -endif::[] -|=== diff --git a/modules/virt-what-you-can-do-with-virt.adoc b/modules/virt-what-you-can-do-with-virt.adoc deleted file mode 100644 index 8d3d0408dbdd..000000000000 --- a/modules/virt-what-you-can-do-with-virt.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * virt/about-virt.adoc -// * virt/virt_release_notes/virt-2-4-release-notes.adoc - -[id="virt-what-you-can-do-with-virt_{context}"] -= What you can do with {VirtProductName} - -{VirtProductName} is an add-on to {product-title} that allows you to run and manage - virtual machine workloads alongside container workloads. - -{VirtProductName} adds new objects into your {product-title} cluster via Kubernetes -custom resources to enable virtualization tasks. These tasks include: - -* Creating and managing Linux and Windows virtual machines -* Connecting to virtual machines through a variety of consoles and CLI tools -* Importing and cloning existing virtual machines -* Managing network interface controllers and storage disks attached to virtual machines -* Live migrating virtual machines between nodes - -An enhanced web console provides a graphical portal to manage these virtualized -resources alongside the {product-title} cluster containers and infrastructure. - -{VirtProductName} is tested with OpenShift Container Storage (OCS) and designed to use with -OCS features for the best experience. - -// A line about support for OVN and OpenShiftSDN network providers has been moved to the `about-virt` assembly due to xrefs. -// If you are re-using this module, you might also want to include that line in your assembly. diff --git a/modules/visualizing-external-entities-known-limitations.adoc b/modules/visualizing-external-entities-known-limitations.adoc new file mode 100644 index 000000000000..6a1379f51881 --- /dev/null +++ b/modules/visualizing-external-entities-known-limitations.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/visualizing-external-entities.adoc +:_mod-docs-content-type: CONCEPT +[id="visualizing-external-entities-known-limitations_{context}"] += Known limitations + +[role="_abstract"] +The following are some known limitations of the Visualizing external entities feature: + +* You cannot see external IP addresses if they are part of CIDR blocks. +* When you enable external IP collection for a cluster, the Collector in those clusters reports more information to Sensor and Central. Enabling external IP collection might create scalability issues if the workload in the cluster communicates with a large number of distinct external peers. Red{nbsp}Hat recommends that you turn off this feature on clusters with communication patterns involving more than 10,000 distinct external entities. However, if the pattern is mostly ingress or egress, you can overcome the scaling issue by enabling external IPs only in the opposite direction. For more information, see "Using Collector runtime configuration" in the Additional resources section. ++ +[NOTE] +==== +During a test, Red{nbsp}Hat generated 20 flows per second with external entities, leading to a daily increase of 450 MB in Central memory usage. This memory persisted even after deleting the deployments. Turning off external IPs at the Collector level stops further memory growth in Central caused by external IPs. To clear most of the memory used by external IPs, turn off external IPs at the Central level by setting the `ROX_EXTERNAL_IPS` environment variable to `false` and the `ROX_EXTERNAL_IPS_PRUNING` environment variable to `true`. +==== diff --git a/modules/vmc-sizer-tool.adoc b/modules/vmc-sizer-tool.adoc deleted file mode 100644 index cada0f4bacad..000000000000 --- a/modules/vmc-sizer-tool.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vmc/installing-restricted-network-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations.adoc -// * installing/installing_vmc/installing-vmc-network-customizations-user-infra.adoc -// * installing/installing_vmc/installing-vmc-user-infra.adoc -// * installing/installing_vmc/installing-vmc.adoc - -[id="vmc-sizer-tool_{context}"] -= VMC Sizer tool - -VMware Cloud on AWS is built on top of AWS bare metal infrastructure; this is the same bare metal infrastructure which runs AWS native services. When a VMware cloud on AWS software-defined data center (SDDC) is deployed, you consume these physical server nodes and run the VMware ESXi hypervisor in a single tenant fashion. This means the physical infrastructure is not accessible to anyone else using VMC. It is important to consider how many physical hosts you will need to host your virtual infrastructure. - -To determine this, VMware provides the link:https://vmc.vmware.com/sizer/quick-sizing[VMC on AWS Sizer]. With this tool, you can define the resources you intend to host on VMC: - -* Types of workloads -* Total number of virtual machines -* Specification information such as: -** Storage requirements -** vCPUs -** vRAM -** Overcommit ratios - -With these details, the sizer tool can generate a report, based on VMware best practices, and recommend your cluster configuration and the number of hosts you will need. diff --git a/modules/vsphere-problem-detector-about.adoc b/modules/vsphere-problem-detector-about.adoc deleted file mode 100644 index a1d6c8d8a352..000000000000 --- a/modules/vsphere-problem-detector-about.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc - -:operator-name: vSphere Problem Detector Operator - -[id="vsphere-problem-detector-about_{context}"] -= About the {operator-name} - -The {operator-name} checks clusters that are deployed on vSphere for common installation and misconfiguration issues that are related to storage. - -The Operator runs in the `openshift-cluster-storage-operator` namespace and is started by the Cluster Storage Operator when the Cluster Storage Operator detects that the cluster is deployed on vSphere. The {operator-name} communicates with the vSphere vCenter Server to determine the virtual machines in the cluster, the default datastore, and other information about the vSphere vCenter Server configuration. The Operator uses the credentials from the Cloud Credential Operator to connect to vSphere. - -The Operator runs the checks according to the following schedule: - -* The checks run every 8 hours. - -* If any check fails, the Operator runs the checks again in intervals of 1 minute, 2 minutes, 4, 8, and so on. The Operator doubles the interval up to a maximum interval of 8 hours. - -* When all checks pass, the schedule returns to an 8 hour interval. - -The Operator increases the frequency of the checks after a failure so that the Operator can report success quickly after the failure condition is remedied. You can run the Operator manually for immediate troubleshooting information. - -// Clear temporary attributes -:!operator-name: diff --git a/modules/vsphere-problem-detector-config-checks.adoc b/modules/vsphere-problem-detector-config-checks.adoc deleted file mode 100644 index ee82b68820f2..000000000000 --- a/modules/vsphere-problem-detector-config-checks.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc - -:operator-name: vSphere Problem Detector Operator - -[id="vsphere-problem-detector-config-checks_{context}"] -= Configuration checks run by the {operator-name} - -The following tables identify the configuration checks that the {operator-name} runs. Some checks verify the configuration of the cluster. Other checks verify the configuration of each node in the cluster. - -.Cluster configuration checks -[options="header",cols="20,80a"] -|=== -|Name -|Description - -|`CheckDefaultDatastore` -|Verifies that the default datastore name in the vSphere configuration is short enough for use with dynamic provisioning. - -If this check fails, you can expect the following: - -* `systemd` logs errors to the journal such as `Failed to set up mount unit: Invalid argument`. - -* `systemd` does not unmount volumes if the virtual machine is shut down or rebooted without draining all the pods from the node. - -If this check fails, reconfigure vSphere with a shorter name for the default datastore. - -|`CheckFolderPermissions` -|Verifies the permission to list volumes in the default datastore. This permission is required to create volumes. The Operator verifies the permission by listing the `/` and `/kubevols` directories. The root directory must exist. It is acceptable if the `/kubevols` directory does not exist when the check runs. The `/kubevols` directory is created when the datastore is used with dynamic provisioning if the directory does not already exist. - -If this check fails, review the required permissions for the vCenter account that was specified during the {product-title} installation. - -|`CheckPVs` -|Verifies that the fully qualified path to each persistent volume is less than 255 characters. - -If this check fails, rename the VDMK file to use a shorter name. - -|`CheckStorageClasses` -|Verifies the following: - -* The fully qualified path to each persistent volume that is provisioned by this storage class is less than 255 characters. - -* If a storage class uses a storage policy, the storage class must use one policy only and that policy must be defined. - -|`CheckTaskPermissions` -|Verifies the permission to list recent tasks and datastores. - -|`ClusterInfo` -|Collects the cluster version and UUID from vSphere vCenter. -|=== - -.Node configuration checks -[options="header",cols="20,80a"] -|=== -|Name -|Description - -|`CheckNodeDiskUUID` -|Verifies that all the vSphere virtual machines are configured with `disk.enableUUID=TRUE`. - -If this check fails, see the link:https://access.redhat.com/solutions/4606201[How to check 'disk.EnableUUID' parameter from VM in vSphere] Red Hat Knowledgebase solution. - -|`CheckNodeProviderID` -|Verifies that all nodes are configured with the `ProviderID` from vSphere vCenter. This check fails when the output from the following command does not include a provider ID for each node. - -[source,terminal] ----- -$ oc get nodes -o custom-columns=NAME:.metadata.name,PROVIDER_ID:.spec.providerID,UUID:.status.nodeInfo.systemUUID ----- - -If this check fails, refer to the vSphere product documentation for information about setting the provider ID for each node in the cluster. - -|`CollectNodeESXiVersion` -|Reports the version of the ESXi hosts that run nodes. - -|`CollectNodeHWVersion` -|Reports the virtual machine hardware version for a node. -|=== - -// Clear temporary attributes -:!operator-name: diff --git a/modules/vsphere-problem-detector-metrics.adoc b/modules/vsphere-problem-detector-metrics.adoc deleted file mode 100644 index 01561d3698ae..000000000000 --- a/modules/vsphere-problem-detector-metrics.adoc +++ /dev/null @@ -1,40 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc - -:operator-name: vSphere Problem Detector Operator - -[id="vsphere-problem-detector-operator-metrics_{context}"] -= Metrics for the {operator-name} - -The {operator-name} exposes the following metrics for use by the {product-title} monitoring stack. - -.Metrics exposed by the {operator-name} -[cols="2a,8a",options="header"] -|=== -|Name |Description - -|`vsphere_cluster_check_total` -|Cumulative number of cluster-level checks that the {operator-name} performed. This count includes both successes and failures. - -|`vsphere_cluster_check_errors` -|Number of failed cluster-level checks that the {operator-name} performed. For example, a value of `1` indicates that one cluster-level check failed. - -|`vsphere_esxi_version_total` -|Number of ESXi hosts with a specific version. Be aware that if a host runs more than one node, the host is counted only once. - -|`vsphere_node_check_total` -|Cumulative number of node-level checks that the {operator-name} performed. This count includes both successes and failures. - -|`vsphere_node_check_errors` -|Number of failed node-level checks that the {operator-name} performed. For example, a value of `1` indicates that one node-level check failed. - -|`vsphere_node_hw_version_total` -|Number of vSphere nodes with a specific hardware version. - -|`vsphere_vcenter_info` -|Information about the vSphere vCenter Server. -|=== - -// Clear temporary attributes -:!operator-name: diff --git a/modules/vsphere-problem-detector-operator.adoc b/modules/vsphere-problem-detector-operator.adoc deleted file mode 100644 index 6f622e7efcc5..000000000000 --- a/modules/vsphere-problem-detector-operator.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -:operator-name: vSphere Problem Detector Operator - -[id="vsphere-problem-detector-operator_{context}"] -= {operator-name} - -[discrete] -== Purpose - -The {operator-name} checks the cluster for common installation and misconfiguration issues. - -[discrete] -== Configuration - -No configuration is required. - -[discrete] -== Notes - -* The Operator supports {product-title} installations on vSphere. -* The Operator uses the `vsphere-cloud-credentials` to communicate with vSphere. -* The Operator performs checks that are related to storage. - -// Clear temporary attributes -:!operator-name: diff --git a/modules/vsphere-problem-detector-running.adoc b/modules/vsphere-problem-detector-running.adoc deleted file mode 100644 index deb0a6217b4c..000000000000 --- a/modules/vsphere-problem-detector-running.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc - -:operator-name: vSphere Problem Detector Operator - -[id="vsphere-problem-detector-running_{context}"] -= Running the {operator-name} checks - -You can override the schedule for running the {operator-name} checks and run the checks immediately. - -The {operator-name} automatically runs the checks every 8 hours. However, when the Operator starts, it runs the checks immediately. The Operator is started by the Cluster Storage Operator when the Cluster Storage Operator starts and determines that the cluster is running on vSphere. To run the checks immediately, you can scale the {operator-name} to `0` and back to `1` so that it restarts the {operator-name}. - -.Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -.Procedure - -. Scale the Operator to `0`: -+ -[source,terminal] ----- -$ oc scale deployment/vsphere-problem-detector-operator --replicas=0 \ - -n openshift-cluster-storage-operator ----- -+ -If the deployment does not scale to zero immediately, you can run the following command to wait for the pods to exit: -+ -[source,terminal] ----- -$ oc wait pods -l name=vsphere-problem-detector-operator \ - --for=delete --timeout=5m -n openshift-cluster-storage-operator ----- - -. Scale the Operator back to `1`: -+ -[source,terminal] ----- -$ oc scale deployment/vsphere-problem-detector-operator --replicas=1 \ - -n openshift-cluster-storage-operator ----- - -. Delete the old leader lock to speed up the new leader election for the Cluster Storage Operator: -+ -[source,terminal] ----- -$ oc delete -n openshift-cluster-storage-operator \ - cm vsphere-problem-detector-lock ----- - -.Verification - -* View the events or logs that are generated by the {operator-name}. Confirm that the events or logs have recent timestamps. - -// Clear temporary attributes -:!operator-name: diff --git a/modules/vsphere-problem-detector-storage-class-config-check.adoc b/modules/vsphere-problem-detector-storage-class-config-check.adoc deleted file mode 100644 index 7e64c1dd6204..000000000000 --- a/modules/vsphere-problem-detector-storage-class-config-check.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc - -:operator-name: vSphere Problem Detector Operator - -[id="vsphere-problem-detector-storage-class-config-check_{context}"] -= About the storage class configuration check - -The names for persistent volumes that use vSphere storage are related to the datastore name and cluster ID. - -When a persistent volume is created, `systemd` creates a mount unit for the persistent volume. The `systemd` process has a 255 character limit for the length of the fully qualified path to the VDMK file that is used for the persistent volume. - -The fully qualified path is based on the naming conventions for `systemd` and vSphere. The naming conventions use the following pattern: - -[source,text] ----- -/var/lib/kubelet/plugins/kubernetes.io/vsphere-volume/mounts/[<datastore>] 00000000-0000-0000-0000-000000000000/<cluster_id>-dynamic-pvc-00000000-0000-0000-0000-000000000000.vmdk ----- - -* The naming conventions require 205 characters of the 255 character limit. - -* The datastore name and the cluster ID are determined from the deployment. - -* The datastore name and cluster ID are substituted into the preceding pattern. Then the path is processed with the `systemd-escape` command to escape special characters. For example, a hyphen character uses four characters after it is escaped. The escaped value is `\x2d`. - -* After processing with `systemd-escape` to ensure that `systemd` can access the fully qualified path to the VDMK file, the length of the path must be less than 255 characters. - -// Clear temporary attributes -:!operator-name: diff --git a/modules/vsphere-problem-detector-viewing-events.adoc b/modules/vsphere-problem-detector-viewing-events.adoc deleted file mode 100644 index 414d4fa6eec7..000000000000 --- a/modules/vsphere-problem-detector-viewing-events.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies -// -// * installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc - -:operator-name: vSphere Problem Detector Operator - -[id="vsphere-problem-detector-viewing-events_{context}"] -= Viewing the events from the {operator-name} - -After the {operator-name} runs and performs the configuration checks, it creates events that can be viewed from the command line or from the {product-title} web console. - -.Procedure - -* To view the events by using the command line, run the following command: -+ -[source,terminal] ----- -$ oc get event -n openshift-cluster-storage-operator \ - --sort-by={.metadata.creationTimestamp} ----- -+ -.Example output -[source,terminal] ----- -16m Normal Started pod/vsphere-problem-detector-operator-xxxxx Started container vsphere-problem-detector -16m Normal Created pod/vsphere-problem-detector-operator-xxxxx Created container vsphere-problem-detector -16m Normal LeaderElection configmap/vsphere-problem-detector-lock vsphere-problem-detector-operator-xxxxx became leader ----- - -* To view the events by using the {product-title} web console, navigate to *Home* -> *Events* and select `openshift-cluster-storage-operator` from the *Project* menu. - -// Clear temporary attributes -:!operator-name: diff --git a/modules/vsphere-problem-detector-viewing-logs.adoc b/modules/vsphere-problem-detector-viewing-logs.adoc deleted file mode 100644 index fa76c29f9e02..000000000000 --- a/modules/vsphere-problem-detector-viewing-logs.adoc +++ /dev/null @@ -1,44 +0,0 @@ -// Module included in the following assemblies: -// -// * installing/installing_vsphere/using-vsphere-problem-detector-operator.adoc - -:operator-name: vSphere Problem Detector Operator - -[id="vsphere-problem-detector-viewing-logs_{context}"] -= Viewing the logs from the {operator-name} - -After the {operator-name} runs and performs the configuration checks, it creates log records that can be viewed from the command line or from the {product-title} web console. - -.Procedure - -* To view the logs by using the command line, run the following command: -+ -[source,terminal] ----- -$ oc logs deployment/vsphere-problem-detector-operator \ - -n openshift-cluster-storage-operator ----- -+ -.Example output -[source,terminal] ----- -I0108 08:32:28.445696 1 operator.go:209] ClusterInfo passed -I0108 08:32:28.451029 1 datastore.go:57] CheckStorageClasses checked 1 storage classes, 0 problems found -I0108 08:32:28.451047 1 operator.go:209] CheckStorageClasses passed -I0108 08:32:28.452160 1 operator.go:209] CheckDefaultDatastore passed -I0108 08:32:28.480648 1 operator.go:271] CheckNodeDiskUUID:<host_name> passed -I0108 08:32:28.480685 1 operator.go:271] CheckNodeProviderID:<host_name> passed ----- - -* To view the Operator logs with the {product-title} web console, perform the following steps: - -.. Navigate to *Workloads* -> *Pods*. - -.. Select `openshift-cluster-storage-operator` from the *Projects* menu. - -.. Click the link for the `vsphere-problem-detector-operator` pod. - -.. Click the *Logs* tab on the *Pod details* page to view the logs. - -// Clear temporary attributes -:!operator-name: diff --git a/modules/vulnerability-management-accept-deferrals-false-positives.adoc b/modules/vulnerability-management-accept-deferrals-false-positives.adoc new file mode 100644 index 000000000000..342e3222ec38 --- /dev/null +++ b/modules/vulnerability-management-accept-deferrals-false-positives.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-review-accept-deferrals-false-positives_{context}"] += Reviewing and managing an exception request to defer or mark a CVE as false positive + +[role="_abstract"] +You can review, update, approve, or deny an exception requests for deferring and marking CVEs as false positives. + +.Prerequisites +* You have the `write` permission for the `VulnerabilityManagementRequests` resource. + +.Procedure +. To view the list of pending requests, do any of the following tasks: +* Paste the approval link into your browser. +* Click *Vulnerability Management* -> *Exception Management*, and then click the request name in the *Pending requests* tab. +. Review the scope of the vulnerability and decide whether or not to approve it. +. Choose the appropriate option to manage a pending request: +* If you want to deny the request and return the CVE to observed status, click *Deny request*. ++ +Enter a rationale for the denial, and click *Deny*. +* If you want to approve the request, click *Approve request*. ++ +Enter a rationale for the approval, and click *Approve*. +. To cancel a request that you have created and return the CVE to observed status, click *Cancel request*. You can only cancel requests that you have created. +. To update the deferral time period or rationale for a request that you have created, click *Update request*. You can only update requests that you have created. ++ +After you make changes, click *Submit request*. ++ +You receive a confirmation that you have submitted a request. diff --git a/modules/vulnerability-management-accept-risks.adoc b/modules/vulnerability-management-accept-risks.adoc new file mode 100644 index 000000000000..3f0cbe261c20 --- /dev/null +++ b/modules/vulnerability-management-accept-risks.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-accept-risks_{context}"] += Deferring CVEs + +[role="_abstract"] +You can accept risk with or without mitigation and defer CVEs. You must get deferral requests approved in the exception management workflow. + +.Prerequisites +* You have `write` permission for the `VulnerabilityManagementRequests` resource. + +.Procedure +. In the {product-title-short} portal, click *Vulnerability Management* -> *Results*. +. Click the *User Workloads* tab. +. Choose the appropriate method to defer a CVE: +* If you want to defer a single CVE, perform the following steps: +.. Find the row which contains the CVE that you want to mark as a false positive. +.. Click the overflow menu, {kebab}, for the CVE that you identified, and then click *Defer CVE*. +* If you want to defer multiple CVEs, perform the following steps: +.. Select each CVE. +.. Click *Bulk actions* -> *Defer CVEs*. +. Select the time period for the deferral. +. Enter a rationale for requesting the exception. +. Optional: To review the CVEs that are included in the exception menu, click *CVE selections*. +. Click *Submit request*. ++ +You receive a confirmation that you have requested a deferral. +. Optional: To copy the approval link to share it with your organization's exception approver, click the copy icon. +. Click *Close*. + diff --git a/modules/vulnerability-management-accessing-additional-views.adoc b/modules/vulnerability-management-accessing-additional-views.adoc new file mode 100644 index 000000000000..a3c92191baea --- /dev/null +++ b/modules/vulnerability-management-accessing-additional-views.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-accessing-additional-views_{context}"] += Accessing additional views in vulnerability management + +The *More views* tab provides additional ways to view vulnerabilities in your system, including the following views: + +* All vulnerable images: Displays vulnerabilities for user workloads, platform vulnerabilities, and vulnerabilities for inactive images in the same page. +* Inactive images: Displays vulnerabilities for watched images and images that are not currently deployed as workloads. Vulnerabilities are reported for images based on your image retention settings. +* Images without CVEs: Shows images and workloads without observed CVEs. See "Analyze images and deployments without observed CVEs". +* Kubernetes components: Displays vulnerabilities affecting the underlying Kubernetes structure. \ No newline at end of file diff --git a/modules/vulnerability-management-assess-exposure.adoc b/modules/vulnerability-management-assess-exposure.adoc new file mode 100644 index 000000000000..5f63cb4eb321 --- /dev/null +++ b/modules/vulnerability-management-assess-exposure.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-assess-exposure_{context}"] += Assessing the exposure + +[role="_abstract"] +To assess your exposure to a vulnerability, answer the following questions: + +* Is your application impacted by a vulnerability? +* Is the vulnerability mitigated by some other factor? +* Are there any known threats that could lead to the exploitation of this vulnerability? +* Are you using the software package which has the vulnerability? +* Is spending time on a specific vulnerability and the software package worth it? + +Take some of the following actions based on your assessment: + +* Consider marking the vulnerability as a false positive if you determine that there is no exposure or that the vulnerability does not apply in your environment. +* Consider if you would prefer to remediate, mitigate or accept the risk if you are exposed. +* Consider if you want to remove or change the software package to reduce your attack surface. diff --git a/modules/vulnerability-management-asset-assessment.adoc b/modules/vulnerability-management-asset-assessment.adoc new file mode 100644 index 000000000000..8afda33f16f5 --- /dev/null +++ b/modules/vulnerability-management-asset-assessment.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-asset-assessment_{context}"] += Performing asset assessment + +[role="_abstract"] +Performing an assessment of an organization's assets involve the following actions: + +* Identifying the assets in your environment +* Scanning these assets to identify known vulnerabilities +* Reporting on the vulnerabilities in your environment to impacted stakeholders + +When you install {product-title} on your Kubernetes or {ocp} cluster, it first aggregates the assets running inside of your cluster to help you identify those assets. {product-title-short} allows organizations to perform continuous assessments on their {ocp} and Kubernetes clusters. {product-title-short} provides organizations with the contextual information to prioritize and act on vulnerabilities in their environment more effectively. + +Important assets that should be monitored by the organization's vulnerability management process using {product-title-short} include: + +* *Components*: Components are software packages that may be used as part of an image or run on a node. Components are the lowest level where vulnerabilities are present. Therefore, organizations must upgrade, modify or remove software components in some way to remediate vulnerabilities. +* *Images*: A collection of software components and code that create an environment to run an executable portion of code. Images are where you upgrade components to fix vulnerabilities. +* *Nodes*: A server used to manage and run applications using OpenShift or Kubernetes and the components that make up the {ocp} or Kubernetes service. + +{product-title-short} groups these assets into the following structures: + +* *Deployment*: A definition of an application in Kubernetes that may run pods with containers based on one or many images. +* *Namespace*: A grouping of resources such as Deployments that support and isolate an application. +* *Cluster*: A group of nodes used to run applications using OpenShift or Kubernetes. + +{product-title-short} scans the assets for known vulnerabilities and uses the Common Vulnerabilities and Exposures (CVE) data to assess the impact of a known vulnerability. diff --git a/modules/vulnerability-management-components-portal.adoc b/modules/vulnerability-management-components-portal.adoc new file mode 100644 index 000000000000..23e680bdc748 --- /dev/null +++ b/modules/vulnerability-management-components-portal.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vuln-management-components-portal_{context}"] += Viewing vulnerability management data in the RHACS portal + +[role="_abstract"] + +Beginning with release 4.7, {product-title-short} has reorganized data for vulnerabilities it discovers and separated vulnerability data by category, such as vulnerabilities in user workloads and nodes, and platform vulnerabilities. + +In the *Vulnerability Management* menu, the *Results* page provides vulnerability data. You can view vulnerability data by category by clicking the tabs at the top of the page. The tabs include the following categories: + +User workloads:: This tab provides information about vulnerabilities that affect workloads and images in your system that you have deployed. Because these workloads are deployed and managed by you, they are called _user workloads_. + +Platform:: This tab provides information about vulnerabilities that {product-title-short} identifies as related to the _platform_, for example, vulnerabilities in workloads and images that the OpenShift platform and layered services deploy. {product-title-short} uses a regular expression pattern to examine the namespaces of workloads and identify workloads that belong to platform components. For example, currently, {product-title-short} identifies vulnerabilities in the following namespaces as belonging to the platform: +* {ocp}: Namespace starts with `openshift-` or `kube-` +* Layered products: +** Namespace starts with rhacs-operator +** Namespace starts with open-cluster-management +** Namespace is `stackrox`, `multicluster-engine`, `aap`, or `hive` +* Third-party partners: Namespace is `nvidia-gpu-operator` + +Nodes:: This tab provides a view of vulnerabilities across nodes, including user-managed and platform workloads and images. + +More views:: This menu provides access to additional ways to view vulnerability information, including the following views: + +* All vulnerable images +* Inactive images +* Images without CVEs +* Kubernetes components diff --git a/modules/vulnerability-management-exception-time-config.adoc b/modules/vulnerability-management-exception-time-config.adoc new file mode 100644 index 000000000000..0e15f2d21819 --- /dev/null +++ b/modules/vulnerability-management-exception-time-config.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-exception-time-config_{context}"] += Configuring vulnerability exception expiration periods + +[role="_abstract"] +You can configure the time periods available for vulnerability management exceptions. These options are available when users request to defer a CVE. + +.Prerequisites +* You have `write` permission for the `VulnerabilityManagementRequests` resource. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Exception Configuration*. +. You can configure expiration times that users can select when they request to defer a CVE. Enabling a time period makes it available to users and disabling it removes it from the user interface. diff --git a/modules/vulnerability-management-export-workloads.adoc b/modules/vulnerability-management-export-workloads.adoc new file mode 100644 index 000000000000..a1cff975f92c --- /dev/null +++ b/modules/vulnerability-management-export-workloads.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-export-workloads_{context}"] += Exporting workload vulnerabilities by using the API + +[role="_abstract"] +You can export workload vulnerabilities in {product-title} by using the API. + +For these examples, workloads are composed of deployments and their associated images. The export uses the `/v1/export/vuln-mgmt/workloads` streaming API. It allows the combined export of deployments and images. The `images` payload contains the full vulnerability information. The output is streamed and has the following schema: + +[source,json] +---- +{"result": {"deployment": {...}, "images": [...]}} +... +{"result": {"deployment": {...}, "images": [...]}} +---- + +The following examples assume that these environment variables have been set: + +* `ROX_API_TOKEN`: API token with `view` permissions for the `Deployment` and `Image` resources +* `ROX_ENDPOINT`: Endpoint under which Central's API is available + +* To export all workloads, enter the following command: ++ +[source,terminal] +---- +$ curl -H "Authorization: Bearer $ROX_API_TOKEN" $ROX_ENDPOINT/v1/export/vuln-mgmt/workloads +---- +* To export all workloads with a query timeout of 60 seconds, enter the following command: ++ +[source,terminal] +---- +$ curl -H "Authorization: Bearer $ROX_API_TOKEN" $ROX_ENDPOINT/v1/export/vuln-mgmt/workloads?timeout=60 +---- +* To export all workloads matching the query `Deployment:app Namespace:default`, enter the following command: ++ +[source,terminal] +---- +$ curl -H "Authorization: Bearer $ROX_API_TOKEN" $ROX_ENDPOINT/v1/export/vuln-mgmt/workloads?query=Deployment%3Aapp%2BNamespace%3Adefault +---- + diff --git a/modules/vulnerability-management-mark-false-positive-image.adoc b/modules/vulnerability-management-mark-false-positive-image.adoc new file mode 100644 index 000000000000..b6a04b44d0b1 --- /dev/null +++ b/modules/vulnerability-management-mark-false-positive-image.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-mark-false-positive-image_{context}"] += Marking a vulnerability as a false positive for an image or image tag + +[role="_abstract"] +To create an exception for a vulnerability, you can mark it as a false positive for a single image, or across all tags associated with an image. You must get requests to mark a vulnerability as a false positive approved in the exception management workflow. + +.Prerequisites +* You have the `write` permission for the `VulnerabilityManagementRequests` resource. + +.Procedure +. In the {product-title-short} portal, click *Vulnerability Management* -> *Results*. +. Click the *User Workloads* tab. +. To view the list of images, click *<number> Images*. +. Find the row that lists the image that you want to mark as a false positive, and click the image name. +. Choose the appropriate method to mark the CVEs: +* If you want to mark a single CVE, perform the following steps: +.. Find the row which contains the CVE that you want to take action on. +.. Click the overflow menu, {kebab}, for the CVE that you identified, and then select *Mark as false positive*. +* If you want to mark multiple CVEs, perform the following steps: +.. Select each CVE. +.. From the *Bulk actions* drop-down list, select *Mark as false positives*. +. Select the scope. You can select either all tags associated with the image or only the image. +. Enter a rationale for requesting the exception. +. Optional: To review the CVEs that are included in the exception request, click *CVE selections*. +. Click *Submit request*. ++ +You receive a confirmation that you have requested an exception. +. Optional: To copy the approval link and share it with your organization's exception approver, click the copy icon. +. Click *Close*. \ No newline at end of file diff --git a/modules/vulnerability-management-mark-false-positive.adoc b/modules/vulnerability-management-mark-false-positive.adoc new file mode 100644 index 000000000000..af32e2a22e3b --- /dev/null +++ b/modules/vulnerability-management-mark-false-positive.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-mark-false-positive_{context}"] += Marking a vulnerability as a false positive globally + +[role="_abstract"] +You can create an exception for a vulnerability by marking it as a false positive globally, or across all images. You must get requests to mark a vulnerability as a false positive approved in the exception management workflow. + +.Prerequisites +* You have the `write` permission for the `VulnerabilityManagementRequests` resource. + +.Procedure +. In the {product-title-short} portal, click *Vulnerability Management* -> *Results*. +. Click *User Workloads*. +. Choose the appropriate method to mark the CVEs: +* If you want to mark a single CVE, perform the following steps: +.. Find the row which contains the CVE that you want to take action on. +.. Click the overflow menu, {kebab}, for the CVE that you identified, and then select *Mark as false positive*. +* If you want to mark multiple CVEs, perform the following steps: +.. Select each CVE. +.. From the *Bulk actions* drop-down list, select *Mark as false positives*. +. Enter a rationale for requesting the exception. +. Optional: To review the CVEs that are included in the exception request, click *CVE selections*. +. Click *Submit request*. ++ +You receive a confirmation that you have requested an exception. +. Optional: To copy the approval link and share it with your organization's exception approver, click the copy icon. +. Click *Close*. \ No newline at end of file diff --git a/modules/vulnerability-management-more-views-all-vuln-images.adoc b/modules/vulnerability-management-more-views-all-vuln-images.adoc new file mode 100644 index 000000000000..d9f61a7e9de6 --- /dev/null +++ b/modules/vulnerability-management-more-views-all-vuln-images.adoc @@ -0,0 +1,145 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-more-views-all-vuln-images_{context}"] += Viewing all vulnerable images + +You can view a list of vulnerabilities for user workloads, platform vulnerabilities, and inactive images on the same page. + +.Procedure + +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Results*. +. Click *More Views* and select *All vulnerable images*. +. Optional: You can choose to view observed vulnerabilities or those that have been deferred or marked as false positives. Click one of the following tabs: +* *Observed*: Lists vulnerabilities that {product-title-short} observed across all images and workloads. +* *Deferred*: Lists vulnerabilities that have been observed but had a deferral request submitted and approved in the exception management workflow. +* *False positives*: Lists vulnerabilities that have been observed but were identified as false positives in the exception management workflow. +. Optional: You can select the following options to refine the list of results: +* *Prioritize by namespace view*: Displays a list of namespaces sorted according to the risk priority. You can use this view to quickly identify and address the most critical areas. In this view, click *<number> deployments* in a table row to return to the all vulnerable images view, with filters applied to show only deployments for the selected namespace. +* *Default filters*: You can select filters for CVE severity and CVE status that are automatically applied across all views on this page. These filters are applied when you visit the page from another section of the {product-title-short} web portal or from a bookmarked URL. They are saved in the local storage of your browser. +. Click one of the following tabs to view the data that you want: +* *<number> CVEs*: Displays vulnerabilities organized by CVE +* *<number> Images*: Displays images that contain discovered vulnerabilities. +* *<number> Deployments*: Displays deployments that contain discovered vulnerabilities. +. Optional: Choose the appropriate method to view the component and advisory data associated with a CVE: +** To view the component and advisory data associated with a CVE from the list of CVEs, complete the following steps: +... Click the *<number> CVEs* tab. +... In the list of CVEs, click a CVE to do any of the following tasks: +**** To view the component and advisory data associated with an image: +..... Click the *<number> Images* tab. +..... Expand the image. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +**** To view the component and advisory data associated with a deployment: +..... Click the *<number> Deployments* tab. +..... Expand the deployment. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +** To view the component and advisory data associated with a CVE from the list of images, complete the following steps: +... Click the *<number> Images* tab. +... In the list of images, click an image. +... To view the component and advisory data associated with a CVE, expand the CVE. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +** To view the component and advisory data associated with a CVE from the list of deployments, complete the following steps: +... Click the *<number> Deployments* tab. +... In the list of deployments, click a deployment. +... To view the component and advisory data associated with a CVE, expand the CVE. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +. Optional: Choose the appropriate method to re-organize the information in the *User Workloads* tab: +** To sort the table in ascending or descending order, select a column heading. +** To filter the table, use the filter bar. +** To select the categories that you want to display in the table, perform the following steps: +... Click *Columns*. +... Choose the appropriate method to manage the columns: +**** To view all the categories, click *Select all*. +**** To reset to the default categories, click *Reset to default*. +**** To view only the selected categories, select the one or more categories that you want to view, and then click *Save*. +. To filter the list of results by entity, for example, to search for a specific named CVE, select the appropriate filters and attributes. ++ +To select multiple entities and attributes, click the right arrow icon to add another criteria. Depending on your choices, enter the appropriate information such as text, or select a date or object. ++ +The filter entities and attributes are listed in the following table. ++ +.CVE filtering +[cols="2",options="header"] +|=== +|Entity|Attributes + +|Image +a| +* *Name*: The name of the image. +* *Operating system*: The operating system of the image. +* *Tag*: The tag for the image. +* *Label*: The label for the image. +* *Registry*: The registry where the image is located. +|CVE +a| +* *Name*: The name of the CVE. +* *Discovered time*: The date when {product-title-short} discovered the CVE. +* *CVSS*: The severity level for the CVE. ++ +The following values are associated with the severity level for the CVE: ++ +** *is greater than* +** *is greater than or equal to* +** *is equal to* +** *is less than or equal to* +** *is less than* +* *EPSS probability*: The likelihood that the vulnerability could be exploited according to the link:https://www.first.org/epss/[Exploit Prediction Scoring System (EPSS)]. This EPSS data provides a percentage estimate of the probability that exploitation of this vulnerability will be observed in the next 30 days. The EPSS collects data of observed exploitation activity from partners, and exploitation activity does not mean that an attempted exploitation was successful. The EPSS score should be used as a single data point _along with other information_, such as the age of the CVE, to help you prioritize the vulnerabilities to address. For more information, see link:https://access.redhat.com/articles/7106599[{product-title-short} and EPSS]. +|Image Component +a| + +* *Name*: The name of the image component, for example, `activerecord-sql-server-adapter` +* *Source*: +** OS +** Python +** Java +** Ruby +** Node.js +** Go +** Dotnet Core Runtime +** Infrastructure + +* *Version*: Version of the image component; for example, `3.4.21`. You can use this to search for a specific version of a component, for example, in conjunction with a component name. +|Deployment +a| +* *Name*: Name of the deployment. +* *Label*: Label for the deployment. +* *Annotation*: The annotation for the deployment. +* *Status*: Whether the deployment is inactive or active. +|Namespace +a| +* *ID*: The `metadata.uid` of the namespace that is created by Kubernetes. +* *Name*: The name of the namespace. +* *Label*: The label for the namespace. +* *Annotation*: The annotation for the namespace. +|Cluster +a| +* *ID*: The alphanumeric ID for the cluster. This is an internal identifier that {product-title-short} assigns for tracking purposes. +* *Name*: The name of the cluster. +* *Label*: The label for the cluster. +* *Type*: The cluster type, for example, OCP. +* *Platform type*: The platform type, for example, OpenShift 4 cluster. +|=== +* *CVE severity*: You can select one or more levels. +* *CVE status*: You can select *Fixable* or *Not fixable*. + +[NOTE] +==== +The *Filtered view* icon indicates that the displayed results were filtered based on the criteria that you selected. You can click *Clear filters* to remove all filters, or remove individual filters by clicking on them. +==== + +In the list of results, click a CVE, image name, or deployment name to view more information about the item. For example, depending on the item type, you can view the following information: + +* Whether a CVE is fixable +* Whether an image is active +* The Dockerfile line in the image that contains the CVE +* External links to information about the CVE in Red{nbsp}Hat and other CVE databases \ No newline at end of file diff --git a/modules/vulnerability-management-other-views.adoc b/modules/vulnerability-management-other-views.adoc new file mode 100644 index 000000000000..4ab0bb775021 --- /dev/null +++ b/modules/vulnerability-management-other-views.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-other-views_{context}"] += Other views + +The *Vulnerability Management* view also includes multiple other views that all provide information in the context of vulnerabilities. + +The available views are: + +* Clusters +* Namespaces +* Deployments +* Images +* Components +* CVEs +* Policies + +All these views show a list of items for the selected entity type. +You can select the column heading to sort the items and also use local page filtering. + +//TODO: Add link to local page filtering + +You can easily switch between different views. For example: + +* To switch to the *Clusters* view, from the *Vulnerability Management* view: +** Go to *Application & Infrastructure* -> *Clusters*. +* To switch to the *Clusters* view, from a different view: +** Go to *All Entities* -> *Clusters*. diff --git a/modules/vulnerability-management-prioritizing.adoc b/modules/vulnerability-management-prioritizing.adoc new file mode 100644 index 000000000000..bd9bbf1f44ed --- /dev/null +++ b/modules/vulnerability-management-prioritizing.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-prioritizing_{context}"] += Prioritizing the vulnerabilities + +[role="_abstract"] + +Answer the following questions to prioritize the vulnerabilities in your environment for action and investigation: + +* How important is an affected asset for your organization? +* How severe does a vulnerability need to be for investigation? +* Can the vulnerability be fixed by a patch for the affected software component? +* Does the existence of the vulnerability violate any of your organization's security policies? + +The answers to these questions help security and development teams decide if they want to gauge the exposure of a vulnerability. + +{product-title} provides you the means to facilitate the prioritization of the vulnerabilities in your applications and components. You can use data reported by {product-title-short} to decide which vulnerabilities are critical to address. For example, when viewing vulnerability findings by CVE, you might want to consider the following data that {product-title-short} provides and that you can use to sort and prioritize vulnerabilities: + +* CVE severity: {product-title-short} reports the number of images that are affected by the CVE and its severity rating (for example, low, moderate, important, or critical) from Red{nbsp} Hat Product Security. +* Top CVSS: The highest Common Vulnerability Scoring System (CVSS) score, from data gathered from Red{nbsp}Hat and vendor sources, of this CVE across images. +* Top NVD CVSS: The highest CVSS score, from the National Vulnerability Database, of this CVE across images. You must have Scanner V4 enabled to view this data. +* EPSS probability: The likelihood that the vulnerability could be exploited according to the link:https://www.first.org/epss/[Exploit Prediction Scoring System (EPSS)]. This EPSS data provides a percentage estimate of the probability that exploitation of this vulnerability will be observed in the next 30 days. The EPSS collects data of observed exploitation activity from partners, and exploitation activity does not mean that an attempted exploitation was successful. The EPSS score should be used as a single data point _along with other information_, such as the age of the CVE, to help you prioritize the vulnerabilities to address. For more information, see link:https://access.redhat.com/articles/7106599[{product-title-short} and EPSS]. diff --git a/modules/vulnerability-management-process.adoc b/modules/vulnerability-management-process.adoc new file mode 100644 index 000000000000..7827d4f0e596 --- /dev/null +++ b/modules/vulnerability-management-process.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-process_{context}"] += Vulnerability management process + +[role="_abstract"] +Vulnerability management is a continuous process to identify and remediate vulnerabilities. {product-title} helps you to facilitate a vulnerability management process. + +A successful vulnerability management program often includes the following critical tasks: + +* Performing asset assessment +* Prioritizing the vulnerabilities +* Assessing the exposure +* Taking action +* Continuously reassessing assets + +{product-title} helps organizations to perform continuous assessments on their {ocp} and Kubernetes clusters. It provides organizations with the contextual information they need to prioritize and act on vulnerabilities in their environment more effectively. diff --git a/modules/vulnerability-management-reporting.adoc b/modules/vulnerability-management-reporting.adoc new file mode 100644 index 000000000000..384126152dec --- /dev/null +++ b/modules/vulnerability-management-reporting.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-reporting_{context}"] += Reporting vulnerabilities to teams + +[role="_abstract"] + +As organizations must constantly reassess and report on their vulnerabilities, some organizations find it helpful to have scheduled communications to key stakeholders to help in the vulnerability management process. + +You can use {product-title} to schedule these reoccurring communications through e-mail. These communications should be scoped to the most relevant information that the key stakeholders need. + +For sending these communications, you must consider the following questions: + +* What schedule would have the most impact when communicating with the stakeholders? +* Who is the audience? +* Should you only send specific severity vulnerabilities in your report? +* Should you only send fixable vulnerabilities in your report? diff --git a/modules/vulnerability-management-review-deferred.adoc b/modules/vulnerability-management-review-deferred.adoc new file mode 100644 index 000000000000..4b6d0f3b8347 --- /dev/null +++ b/modules/vulnerability-management-review-deferred.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-review-deferred_{context}"] += Viewing deferred and false positive CVEs + +[role="_abstract"] +You can view the CVEs that have been deferred or marked as false positives by using the *User Workloads* page. + +.Procedure +. To see CVEs that have been deferred or marked as false positives, with the exceptions approved by an approver, click *Vulnerability Management* -> *Results*. +. Click the *User Workloads* tab. +. Complete any of the following actions: +* To see CVEs that have been deferred, click the *Deferred* tab. +* To see CVEs that have been marked as false positives, click the *False positives* tab. ++ +[NOTE] +==== +To approve, deny, or change deferred or false positive CVEs, click *Vulnerability Management* -> *Exception Management*. +==== +. Optional: To view additional information about the deferral or false positive, click *View* in the *Request details* column. The *Exception Management* page is displayed. diff --git a/modules/vulnerability-management-take-action.adoc b/modules/vulnerability-management-take-action.adoc new file mode 100644 index 000000000000..0641e454931a --- /dev/null +++ b/modules/vulnerability-management-take-action.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-take-action_{context}"] += Taking action + +[role="_abstract"] +Once you have decided to take action on a vulnerability, you can take one of the following actions: + +* Remediate the vulnerability +* Mitigate and accept the risk +* Accept the risk +* Mark the vulnerability as a false positive + +You can remediate vulnerabilities by performing one of the following actions: + +* Remove a software package +* Update a software package to a non-vulnerable version diff --git a/modules/vulnerability-management-upgrade-component.adoc b/modules/vulnerability-management-upgrade-component.adoc new file mode 100644 index 000000000000..030414799022 --- /dev/null +++ b/modules/vulnerability-management-upgrade-component.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-upgrade-component_{context}"] += Finding a new component version + +[role="_abstract"] +The following procedure finds a new component version to upgrade to. + +.Procedure + +. In the {product-title-short} portal, click *Vulnerability Management* -> *Results*. +. Click the *User Workloads* tab. +. Click *<number> Images* and select an image. +. To view additional information, locate the CVE and click the expand icon. ++ +The additional information includes the component that the CVE is in and the version in which the CVE is fixed, if it is fixable. +. Update your image to a later version. diff --git a/modules/vulnerability-management-view-applications-vulnerability.adoc b/modules/vulnerability-management-view-applications-vulnerability.adoc new file mode 100644 index 000000000000..f122d426f070 --- /dev/null +++ b/modules/vulnerability-management-view-applications-vulnerability.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-view-applications-vulnerability_{context}"] += Viewing application vulnerabilities by using the dashboard + +[role="_abstract"] +You can view application vulnerabilities in {product-title} by using the dashboard. + +.Procedure + +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Dashboard*. +. On the *Dashboard* view header, select *Application & Infrastructure* -> *Namespaces* or *Deployments*. +. From the list, search for and select the *Namespace* or *Deployment* you want to review. +. To get more information about the application, select an entity from *Related entities* on the right. diff --git a/modules/vulnerability-management-view-image-vulnerability-dashboard.adoc b/modules/vulnerability-management-view-image-vulnerability-dashboard.adoc new file mode 100644 index 000000000000..df7e034ba80e --- /dev/null +++ b/modules/vulnerability-management-view-image-vulnerability-dashboard.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-view-image-vulnerability-dashboard_{context}"] += Viewing image vulnerabilities by using the dashboard + +[role="_abstract"] +You can view image vulnerabilities in {product-title} by using the dashboard. + +.Procedure +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Dashboard*. +. On the *Dashboard* view header, select *<number> Images*. +. From the list of images, select the image you want to investigate. You can also filter the list by performing one of the following steps: +.. Enter *Image* in the search bar and then select the *Image* attribute. +.. Enter the image name in the search bar. +. In the image details view, review the listed CVEs and prioritize taking action to address the impacted components. +. Select *Components* from *Related entities* on the right to get more information about all the components that are impacted by the selected image. Or select *Components* from the *Affected components* column under the *Image findings* section for a list of components affected by specific CVEs. diff --git a/modules/vulnerability-management-view-infrastructure-vulnerability.adoc b/modules/vulnerability-management-view-infrastructure-vulnerability.adoc new file mode 100644 index 000000000000..8030947d9aab --- /dev/null +++ b/modules/vulnerability-management-view-infrastructure-vulnerability.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-view-infrastructure-vulnerability_{context}"] += Viewing cluster vulnerabilities by using the dashboard + +[role="_abstract"] +You can view vulnerabilities in clusters by using {product-title}. + +.Procedure +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Dashboard*. +. On the *Dashboard* view header, select *Application & Infrastructure* -> *Clusters*. +. From the list of clusters, select the cluster you want to investigate. +. Review the cluster's vulnerabilities and prioritize taking action on the impacted nodes on the cluster. diff --git a/modules/vulnerability-management-view-node-vulnerability.adoc b/modules/vulnerability-management-view-node-vulnerability.adoc new file mode 100644 index 000000000000..be2f467732a7 --- /dev/null +++ b/modules/vulnerability-management-view-node-vulnerability.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-view-node-vulnerability_{context}"] += Viewing node vulnerabilities by using the dashboard + +You can view vulnerabilities in specific nodes by using {product-title}. + +.Procedure +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Dashboard*. +. On the *Dashboard* view header, select *Nodes*. +. From the list of nodes, select the node you want to investigate. +. Review vulnerabilities for the selected node and prioritize taking action. +. To get more information about the affected components in a node, select *Components* from *Related entities* on the right. diff --git a/modules/vulnerability-management-view.adoc b/modules/vulnerability-management-view.adoc new file mode 100644 index 000000000000..d89e326443ee --- /dev/null +++ b/modules/vulnerability-management-view.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management-view_{context}"] += Vulnerability Management view + +[role="_abstract"] +The *Vulnerability Management* view displays information you can act on in multiple widgets. +For example, you can identify the riskiest deployments in your infrastructure from the *Top Risky Deployments* widget. + +To open the *Vulnerability Management* view: + +* In the {product-title-short} portal, go to *Vulnerability Management* -> *Dashboard*. + +The *Vulnerability Management* view presents information in multiple interactive widgets. + +Using all these components gives you a complete view of the vulnerabilities in your environment ranging from deployments and images, to the software components from which they are built. diff --git a/modules/vulnerability-management-viewing-kubernetes-vulnerabilities.adoc b/modules/vulnerability-management-viewing-kubernetes-vulnerabilities.adoc new file mode 100644 index 000000000000..f2de4d6dc114 --- /dev/null +++ b/modules/vulnerability-management-viewing-kubernetes-vulnerabilities.adoc @@ -0,0 +1,69 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/common-vuln-management-tasks.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management-viewing-kubernetes-vulnerabilities_{context}"] += Viewing Kubernetes vulnerabilities + +You can view vulnerabilities in your clusters that affect the underlying Kubernetes structure. + +.Procedure + +. Go to *Vulnerability Management* -> *Results*. +. Click *More Views* and select *Kubernetes components*. +. Click the *<number> CVEs* or *<number> Clusters* to display by CVE or cluster. +. Optional: Within the results list, you can filter results by cluster and CVE. To filter vulnerabilities based on an entity, select the appropriate filters and attributes. ++ +To select multiple entities and attributes, click the right arrow icon to add another criteria. Depending on your choices, enter the appropriate information such as text, or select a date or object. ++ +The filter entities and attributes are listed in the following table. ++ +.Filter options +[cols="2",options="header"] +|=== +|Entity|Attributes + +|Cluster +a| +* *ID*: The alphanumeric ID for the cluster. This is an internal identifier that {product-title-short} assigns for tracking purposes. +* *Name*: The name of the cluster. +* *Label*: The label for the cluster. +* *Type*: The cluster type, for example, OCP. +* *Platform type*: The platform type, for example, OpenShift 4 cluster. + +|CVE +a| +* *Name*: The name of the CVE. +* *Discovered time*: The date when {product-title-short} discovered the CVE. +* *CVSS*: The severity level for the CVE. ++ +The following values are associated with the severity level for the CVE: ++ +** *is greater than* +** *is greater than or equal to* +** *is equal to* +** *is less than or equal to* +** *is less than* +* *Type*: The type of CVE: +** Kubernetes +** Istio +** OpenShift +|=== +. Optional: To filter the table based on the status of a CVE, from the *CVE status* drop-down list, select one or more statuses. ++ +The following values are associated with the status of a CVE: ++ +*** `Fixable` +*** `Not fixable` + +[NOTE] +==== +The *Filtered view* icon indicates that the displayed results were filtered based on the criteria that you selected. You can click *Clear filters* to remove all filters, or remove individual filters by clicking on them. +==== + +In the list of results, click a CVE or cluster name to view more information about the item. For example, depending on the item type, you can view the following information: + +* First discovered date +* Whether a CVE is fixable +* External links to information about the CVE in Red{nbsp}Hat and other CVE databases \ No newline at end of file diff --git a/modules/vulnerability-management20-clone-reports.adoc b/modules/vulnerability-management20-clone-reports.adoc new file mode 100644 index 000000000000..250d60da0ad8 --- /dev/null +++ b/modules/vulnerability-management20-clone-reports.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-clone-reports_{context}"] += Cloning vulnerability report configurations + +[role="_abstract"] +You can make copies of vulnerability report configurations by cloning them. This is useful when you want to reuse report configurations with minor changes, such as reporting vulnerabilities in different deployments or namespaces. + +.Procedure +. In the {product-title-short} web portal, click *Vulnerability Management* -> *Vulnerability Reporting*. +. Locate the report configuration that you want to clone in the list of report configurations. +. Click *Clone report*. +. Make any changes that you want to the report parameters and delivery destinations. +. Click *Create*. \ No newline at end of file diff --git a/modules/vulnerability-management20-configure-report-delivery-destinations-schedule.adoc b/modules/vulnerability-management20-configure-report-delivery-destinations-schedule.adoc new file mode 100644 index 000000000000..5ab5ad1bdec5 --- /dev/null +++ b/modules/vulnerability-management20-configure-report-delivery-destinations-schedule.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-configure-report-delivery-destinations-schedule_{context}"] += Configuring delivery destinations and scheduling + +[role="_abstract"] +Configuring destinations and delivery schedules for vulnerability reports is optional, unless on the previous page, you selected the option to include CVEs that were discovered since the last scheduled report. If you selected that option, configuring destinations and delivery schedules for vulnerability reports is required. + +.Procedure +. To configure destinations for delivery, in the *Configure delivery destinations* section, you can add a delivery destination and set up a schedule for reporting. +. To email reports, you must configure at least one email notifier. Select an existing notifier or create a new email notifier to send your report by email. For more information about creating an email notifier, see "Configuring the email plugin" in the "Additional resources" section. ++ +When you select a notifier, the email addresses configured in the notifier as *Default recipients* appear in the *Distribution list* field. You can add additional email addresses that are separated by a comma. +. A default email template is automatically applied. To edit this default template, perform the following steps: +.. Click the edit icon and enter a customized subject and email body in the *Edit* tab. +.. Click the *Preview* tab to see your proposed template. +.. Click *Apply* to save your changes to the template. ++ +[NOTE] +==== +When reviewing the report jobs for a specific report, you can see whether the default template or a customized template was used when creating the report. +==== +. In the *Configure schedule* section, select the frequency and day of the week for the report. +. Click *Next* to review your vulnerability report configuration and finish creating it. \ No newline at end of file diff --git a/modules/vulnerability-management20-creating-report.adoc b/modules/vulnerability-management20-creating-report.adoc new file mode 100644 index 000000000000..623d01f08f5b --- /dev/null +++ b/modules/vulnerability-management20-creating-report.adoc @@ -0,0 +1,54 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-creating-report_{context}"] += Creating vulnerability management report configurations + +[role="_abstract"] +{product-title-short} guides you through the process of creating a vulnerability management report configuration. This configuration determines the information that will be included in a report job that runs at a scheduled time or that you run on demand. + +.Procedure +. In the {product-title-short} portal, click *Vulnerability Management* -> *Vulnerability Reporting*. +. Click *Create report*. +. In the *Configure report parameters* page, provide the following information: +** *Report name*: Enter a name for your report configuration. +** *Report description*: Enter a text describing the report configuration. This is optional. +** *CVE severity*: Select the severity of common vulnerabilities and exposures (CVEs) that you want to include in the report configuration. +** *CVE status*: Select one or more CVE statuses. ++ +The following values are associated with the CVE status: ++ +*** *Fixable* +*** *Unfixable* +** *Image type*: Select one or more image types. ++ +The following values are associated with image types: ++ +*** *Deployed images* +*** *Watched images* +** *CVEs discovered since*: Select the time period for which you want to include the CVEs in the report configuration. +** Optional: Choose the appropriate column that you want to include in the vulnerability report: ++ +[NOTE] +==== +You can select one or more columns to include in the report configuration. +==== ++ +*** Select the *Include NVD CVSS* checkbox, if you want to include the NVD CVSS column in the report configuration. +*** Select the *Include EPSS probability* checkbox, if you want to include the EPSS probability column in the report configuration. +*** Select the *Include advisory name and link* checkbox, if you want to include the advisory name and link column in the report configuration. +** *Configure collection included*: To configure at least one collection, do any of the following tasks: +*** Select an existing collection that you want to include. ++ +To view the collection information, edit the collection, and get a preview of collection results, click *View*. ++ +When viewing the collection, entering text in the field searches for collections matching that text string. +*** To create a new collection, click *Create collection*. ++ +[NOTE] +==== +For more information about collections, see "Creating and using deployment collections". +==== +. To configure the delivery destinations and optionally set up a schedule for delivery, click *Next*. \ No newline at end of file diff --git a/modules/vulnerability-management20-delete-reports.adoc b/modules/vulnerability-management20-delete-reports.adoc new file mode 100644 index 000000000000..88c094683f87 --- /dev/null +++ b/modules/vulnerability-management20-delete-reports.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-delete-reports_{context}"] += Deleting vulnerability report configurations + +[role="_abstract"] +Deleting a report configuration deletes the configuration and any reports that were previously run using this configuration. + +.Procedure +. In the {product-title-short} web portal, click *Vulnerability Management* -> *Vulnerability Reporting*. +. Locate the report configuration that you want to delete in the list of reports. +. Click the overflow menu, {kebab}, and then select *Delete report*. diff --git a/modules/vulnerability-management20-download-reports.adoc b/modules/vulnerability-management20-download-reports.adoc new file mode 100644 index 000000000000..a2fedfa9c5cd --- /dev/null +++ b/modules/vulnerability-management20-download-reports.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-download-reports_{context}"] += Downloading vulnerability reports + +[role="_abstract"] +You can generate an on-demand vulnerability report and then download it. + +[NOTE] +==== +You can only download reports that you have generated; you cannot download reports generated by other users. +==== + +.Procedure +. In the {product-title-short} web portal, click *Vulnerability Management* -> *Vulnerability Reporting*. +. In the list of report configurations, locate the report configuration that you want to use to create the downloadable report. +. Generate the vulnerability report by using one of the following methods: +* To generate the report from the list: +.. Click the overflow menu, {kebab}, and then select *Generate download*. The *My active job status* column displays the status of your report creation. After the *Processing* status goes away, you can download the report. +* To generate the report from the report window: +.. Click the report configuration name to open the configuration detail window. +.. Click *Actions* and select *Generate download*. +. To download the report, if you are viewing the list of report configurations, click the report configuration name to open it. +. Click *All report jobs* from the menu on the header. +. If the report is completed, click the *Ready for download* link in the *Status* column. The report is in `.csv` format and is compressed into a `.zip` file for download. \ No newline at end of file diff --git a/modules/vulnerability-management20-edit-reports.adoc b/modules/vulnerability-management20-edit-reports.adoc new file mode 100644 index 000000000000..8b888af5f5ec --- /dev/null +++ b/modules/vulnerability-management20-edit-reports.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-edit-reports_{context}"] += Editing vulnerability report configurations + +[role="_abstract"] +You can edit existing vulnerability report configurations from the list of report configurations, or by selecting an individual report configuration first. + +.Procedure +. In the {product-title-short} web portal, click *Vulnerability Management* -> *Vulnerability Reporting*. +. To edit an existing vulnerability report configuration, complete any of the following actions: +* Locate the report configuration that you want to edit in the list of report configurations. Click the overflow menu, {kebab}, and then select *Edit report*. +* Click the report configuration name in the list of report configurations. Then, click *Actions* and select *Edit report*. +. Make changes to the report configuration and save. \ No newline at end of file diff --git a/modules/vulnerability-management20-permissions.adoc b/modules/vulnerability-management20-permissions.adoc new file mode 100644 index 000000000000..3c0c27da79f1 --- /dev/null +++ b/modules/vulnerability-management20-permissions.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: CONCEPT +[id="vulnerability-management20-permissions_{context}"] += Vulnerability report permissions + +[role="_abstract"] +The ability to create, view, and download reports depends on the access control settings, or roles and permission sets, for your user account. + +For example, you can only view, create, and download reports for data that your user account has permission to access. In addition, the following restrictions apply: + +* You can only download reports that you have generated; you cannot download reports generated by other users. +* Report permissions are restricted depending on the access settings for user accounts. If the access settings for your account change, old reports do not reflect the change. For example, if you are given new permissions and want to view vulnerability data that is now allowed by those permissions, you must create a new vulnerability report. \ No newline at end of file diff --git a/modules/vulnerability-management20-report-review-create.adoc b/modules/vulnerability-management20-report-review-create.adoc new file mode 100644 index 000000000000..158cda1968ab --- /dev/null +++ b/modules/vulnerability-management20-report-review-create.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-report-review-create_{context}"] += Reviewing and creating the report configuration + +[role="_abstract"] +You can review the details of your vulnerability report configuration before creating it. + +.Procedure +. In the *Review and create* section, you can review the report configuration parameters, delivery destination, email template that is used if you selected email delivery, delivery schedule, and report format. To make any changes, click *Back* to go to the previous section and edit the fields that you want to change. +. Click *Create* to create the report configuration and save it. \ No newline at end of file diff --git a/modules/vulnerability-management20-retention-settings.adoc b/modules/vulnerability-management20-retention-settings.adoc new file mode 100644 index 000000000000..abaf39880473 --- /dev/null +++ b/modules/vulnerability-management20-retention-settings.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-retention-settings_{context}"] += Configuring vulnerability management report job retention settings + +[role="_abstract"] +You can configure settings that determine when vulnerability report job requests expire and other retention settings for report jobs. + +[NOTE] +==== +These settings do not affect the following vulnerability report jobs: + +* Jobs in the `WAITING` or `PREPARING` state (unfinished jobs) +* The last successful scheduled report job +* The last successful on-demand emailed report job +* The last successful downloadable report job +* Downloadable report jobs for which the report file has not been deleted by either manual deletion or by configuring the downloadable report pruning settings +==== + +.Procedure +. In the {product-title-short} web portal, go to *Platform Configuration* -> *System Configuration*. You can configure the following settings for vulnerability report jobs: +* *Vulnerability report run history retention*: The number of days that a record is kept of vulnerability report jobs that have been run. This setting controls how many days that report jobs are listed in the *All report jobs* tab under *Vulnerability Management* -> *Vulnerability Reporting* when a report configuration is selected. The entire report history after the exclusion date is deleted, with the exception of the following jobs: +** Unfinished jobs. +** Jobs for which prepared downloadable reports still exist in the system. +** The last successful report job for each job type (scheduled email, on-demand email, or download). This ensures users have information about the last run job for each type. +* *Prepared downloadable vulnerability reports retention days*: The number of days that prepared, on-demand downloadable vulnerability report jobs are available for download on the *All report jobs* tab under *Vulnerability Management* -> *Vulnerability Reporting* when a report configuration is selected. +* *Prepared downloadable vulnerability reports limit*: The limit, in MB, of space allocated to prepared downloadable vulnerability report jobs. After the limit is reached, the oldest report job in the download queue is removed. +. To change these values, click *Edit*, make your changes, and then click *Save*. + diff --git a/modules/vulnerability-management20-send-reports.adoc b/modules/vulnerability-management20-send-reports.adoc new file mode 100644 index 000000000000..126f0eead6f3 --- /dev/null +++ b/modules/vulnerability-management20-send-reports.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-send-reports_{context}"] += Sending vulnerability reports on-demand + +[role="_abstract"] +You can send vulnerability reports immediately, rather than waiting for the scheduled send time. + +.Procedure +. In the {product-title-short} web portal, click *Vulnerability Management* -> *Vulnerability Reporting*. +. In the list of report configurations, locate the report configuration for the report that you want to send. +. Click the overflow menu, {kebab}, and then select *Send report now*. diff --git a/modules/vulnerability-management20-view-platform-cve.adoc b/modules/vulnerability-management20-view-platform-cve.adoc new file mode 100644 index 000000000000..87c8c2d21018 --- /dev/null +++ b/modules/vulnerability-management20-view-platform-cve.adoc @@ -0,0 +1,146 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-view-platform-cve_{context}"] += Viewing platform vulnerabilities + +[role="_abstract"] + +The *Platform vulnerabilities* page provides information about vulnerabilities that {product-title-short} identifies as related to the _platform_, for example, vulnerabilities in workloads and images that are used by the OpenShift Platform and layered services. + +.Procedure + +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Results*. +. Select the *Platform* tab. By default, the *Observed* tab is selected. +. Optional: You can choose to view observed vulnerabilities or those that have been deferred or marked as false positives. Click one of the following tabs: +* *Observed*: Lists vulnerabilities that {product-title-short} observed in platform workloads and images. +* *Deferred*: Lists vulnerabilities that have been observed but had a deferral request submitted and approved in the exception management workflow. +* *False positives*: Lists vulnerabilities that have been observed but were identified as false positives in the exception management workflow. +. Optional: You can select the following options to refine the list of results: +* *Prioritize by namespace view*: Displays a list of namespaces sorted according to the risk priority. You can use this view to quickly identify and address the most critical areas. In this view, click *<number> deployments* in a table row to return to the platform vulnerabilities view, with filters applied to show only deployments for the selected namespace. +* *Default filters*: You can select filters for CVE severity and CVE status that are automatically applied across all views on this page. These filters are applied when you visit the page from another section of the {product-title-short} web portal or from a bookmarked URL. They are saved in the local storage of your browser. +. To filter the list of results by entity, for example, to search for a specific named CVE, select the appropriate filters and attributes. ++ +To select multiple entities and attributes, click the right arrow icon to add another criteria. Depending on your choices, enter the appropriate information such as text, or select a date or object. ++ +The filter entities and attributes are listed in the following table. ++ +[NOTE] +==== +The *Filtered view* icon indicates that the displayed results were filtered based on the criteria that you selected. You can click *Clear filters* to remove all filters, or remove individual filters by clicking on them. +==== ++ +.Filter options +[cols="2",options="header"] +|=== +|Entity|Attributes + +|Image +a| +* *Name*: The name of the image. +* *Operating system*: The operating system of the image. +* *Tag*: The tag for the image. +* *Label*: The label for the image. +* *Registry*: The registry where the image is located. +|CVE +a| +* *Name*: The name of the CVE. +* *Discovered time*: The date when {product-title-short} discovered the CVE. +* *CVSS*: The severity level for the CVE. ++ +The following values are associated with the severity level for the CVE: ++ +** *is greater than* +** *is greater than or equal to* +** *is equal to* +** *is less than or equal to* +** *is less than* +* *EPSS probability*: The likelihood that the vulnerability could be exploited according to the link:https://www.first.org/epss/[Exploit Prediction Scoring System (EPSS)]. This EPSS data provides a percentage estimate of the probability that exploitation of this vulnerability will be observed in the next 30 days. The EPSS collects data of observed exploitation activity from partners, and exploitation activity does not mean that an attempted exploitation was successful. The EPSS score should be used as a single data point _along with other information_, such as the age of the CVE, to help you prioritize the vulnerabilities to address. For more information, see link:https://access.redhat.com/articles/7106599[{product-title-short} and EPSS]. +|Image Component +a| + +* *Name*: The name of the image component, for example, `activerecord-sql-server-adapter` +* *Source*: +** OS +** Python +** Java +** Ruby +** Node.js +** Go +** Dotnet Core Runtime +** Infrastructure + +* *Version*: Version of the image component; for example, `3.4.21`. You can use this to search for a specific version of a component, for example, in conjunction with a component name. +|Deployment +a| +* *Name*: Name of the deployment. +* *Label*: Label for the deployment. +* *Annotation*: The annotation for the deployment. +* *Status*: Whether the deployment is inactive or active. +|Namespace +a| +* *ID*: The `metadata.uid` of the namespace that is created by Kubernetes. +* *Name*: The name of the namespace. +* *Label*: The label for the namespace. +* *Annotation*: The annotation for the namespace. +|Cluster +a| +* *ID*: The alphanumeric ID for the cluster. This is an internal identifier that {product-title-short} assigns for tracking purposes. +* *Name*: The name of the cluster. +* *Label*: The label for the cluster. +* *Type*: The cluster type, for example, OCP. +* *Platform type*: The platform type, for example, OpenShift 4 cluster. +|=== +* *CVE severity*: You can select one or more levels. +* *CVE status*: You can select *Fixable* or *Not fixable*. +. Click one of the following tabs to view the data that you want: +* *<number> CVEs*: Displays vulnerabilities organized by CVE +* *<number> Images*: Displays images that contain discovered vulnerabilities. +* *<number> Deployments*: Displays deployments that contain discovered vulnerabilities. +. Optional: Choose the appropriate method to view the component and advisory data associated with a CVE: +** To view the component and advisory data associated with a CVE from the list of CVEs, complete the following steps: +... Click the *<number> CVEs* tab. +... In the list of CVEs, click a CVE to do any of the following tasks: +**** To view the component and advisory data associated with an image: +..... Click the *<number> Images* tab. +..... Expand the image. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +**** To view the component and advisory data associated with a deployment: +..... Click the *<number> Deployments* tab. +..... Expand the deployment. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +** To view the component and advisory data associated with a CVE from the list of images, complete the following steps: +... Click the *<number> Images* tab. +... In the list of images, click an image. +... To view the component and advisory data associated with a CVE, expand the CVE. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +** To view the component and advisory data associated with a CVE from the list of deployments, complete the following steps: +... Click the *<number> Deployments* tab. +... In the list of deployments, click a deployment. +... To view the component and advisory data associated with a CVE, expand the CVE. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +. Optional: Choose the appropriate method to re-organize the information in the *User Workloads* tab: +** To sort the table in ascending or descending order, select a column heading. +** To select the categories that you want to display in the table, perform the following steps: +... Click *Columns*. +... Choose the appropriate method to manage the columns: +**** To view all the categories, click *Select all*. +**** To reset to the default categories, click *Reset to default*. +**** To view only the selected categories, select the one or more categories that you want to view, and then click *Save*. +. In the list of results, click a CVE, image name, or deployment name to view more information about the item. For example, depending on the item type, you can view the following information: + +* Whether a CVE is fixable +* Whether an image is active +* The Dockerfile line in the image that contains the CVE +* External links to information about the CVE in Red{nbsp}Hat and other CVE databases + diff --git a/modules/vulnerability-management20-view-workload-cve.adoc b/modules/vulnerability-management20-view-workload-cve.adoc new file mode 100644 index 000000000000..c2fdf6cd733a --- /dev/null +++ b/modules/vulnerability-management20-view-workload-cve.adoc @@ -0,0 +1,147 @@ +// Module included in the following assemblies: +// +// * operating/manage-vulnerabilities/vulnerability-management.adoc + +:_mod-docs-content-type: PROCEDURE +[id="vulnerability-management20-view-workload-cve_{context}"] += Viewing user workload vulnerabilities + +[role="_abstract"] + +In the *Vulnerability Management* -> *Results* page, you can get information about the vulnerabilities in applications running on clusters in your system. With this information, you can prioritize and manage vulnerabilities across images and deployments. + +In the *User workload vulnerabilities* page, you can view images and deployments with vulnerabilities and filter by image, deployment, namespace, cluster, CVE, component, and component source. + +.Procedure + +. In the {product-title-short} portal, go to *Vulnerability Management* -> *Results*. +. Select the *User Workloads* tab. By default, the *Observed* tab is selected. +. Optional: You can choose to view observed vulnerabilities or those that have been deferred or marked as false positives. Click one of the following tabs: +* *Observed*: Lists vulnerabilities that {product-title-short} observed in your user workloads. +* *Deferred*: Lists vulnerabilities that have been observed but had a deferral request submitted and approved in the exception management workflow. +* *False positives*: Lists vulnerabilities that have been observed but were identified as false positives in the exception management workflow. +. Optional: You can select the following options to refine the list of results: +* *Prioritize by namespace view*: Displays a list of namespaces sorted according to the risk priority. You can use this view to quickly identify and address the most critical areas. In this view, click *<number> deployments* in a table row to return to the vulnerability findings view, with filters applied to show only deployments for the selected namespace. +* *Default filters*: You can select filters for CVE severity and CVE status that are automatically applied across all views on this page. These filters are applied when you visit the page from another section of the {product-title-short} web portal or from a bookmarked URL. They are saved in the local storage of your browser. +. To filter the list of results by entity, for example, to search for a specific named CVE, select the appropriate filters and attributes. ++ +To select multiple entities and attributes, click the right arrow icon to add another criteria. Depending on your choices, enter the appropriate information such as text, or select a date or object. ++ +The filter entities and attributes are listed in the following table. ++ +[NOTE] +==== +The *Filtered view* icon indicates that the displayed results were filtered based on the criteria that you selected. You can click *Clear filters* to remove all filters, or remove individual filters by clicking on them. +==== ++ +.Filter options +[cols="2",options="header"] +|=== +|Entity|Attributes + +|Image +a| +* *Name*: The name of the image. +* *Operating system*: The operating system of the image. +* *Tag*: The tag for the image. +* *Label*: The label for the image. +* *Registry*: The registry where the image is located. +|CVE +a| +* *Name*: The name of the CVE. +* *Discovered time*: The date when {product-title-short} discovered the CVE. +* *CVSS*: The severity level for the CVE. ++ +The following values are associated with the severity level for the CVE: ++ +** *is greater than* +** *is greater than or equal to* +** *is equal to* +** *is less than or equal to* +** *is less than* +* *EPSS probability*: The likelihood that the vulnerability could be exploited according to the link:https://www.first.org/epss/[Exploit Prediction Scoring System (EPSS)]. This EPSS data provides a percentage estimate of the probability that exploitation of this vulnerability will be observed in the next 30 days. The EPSS collects data of observed exploitation activity from partners, and exploitation activity does not mean that an attempted exploitation was successful. The EPSS score should be used as a single data point _along with other information_, such as the age of the CVE, to help you prioritize the vulnerabilities to address. For more information, see link:https://access.redhat.com/articles/7106599[{product-title-short} and EPSS]. +|Image Component +a| + +* *Name*: The name of the image component, for example, `activerecord-sql-server-adapter` +* *Source*: +** OS +** Python +** Java +** Ruby +** Node.js +** Go +** Dotnet Core Runtime +** Infrastructure + +* *Version*: Version of the image component; for example, `3.4.21`. You can use this to search for a specific version of a component, for example, in conjunction with a component name. +|Deployment +a| +* *Name*: Name of the deployment. +* *Label*: Label for the deployment. +* *Annotation*: The annotation for the deployment. +* *Status*: Whether the deployment is inactive or active. +|Namespace +a| +* *ID*: The `metadata.uid` of the namespace that is created by Kubernetes. +* *Name*: The name of the namespace. +* *Label*: The label for the namespace. +* *Annotation*: The annotation for the namespace. +|Cluster +a| +* *ID*: The alphanumeric ID for the cluster. This is an internal identifier that {product-title-short} assigns for tracking purposes. +* *Name*: The name of the cluster. +* *Label*: The label for the cluster. +* *Type*: The cluster type, for example, OCP. +* *Platform type*: The platform type, for example, OpenShift 4 cluster. +|=== +* *CVE severity*: You can select one or more levels. +* *CVE status*: You can select *Fixable* or *Not fixable*. +. Click one of the following tabs to view the data that you want: +* *<number> CVEs*: Displays vulnerabilities organized by CVE +* *<number> Images*: Displays images that contain discovered vulnerabilities. +* *<number> Deployments*: Displays deployments that contain discovered vulnerabilities. +. Optional: Choose the appropriate method to view the component and advisory data associated with a CVE: +** To view the component and advisory data associated with a CVE from the list of CVEs, complete the following steps: +... Click the *<number> CVEs* tab. +... In the list of CVEs, click a CVE to do any of the following tasks: +**** To view the component and advisory data associated with an image: +..... Click the *<number> Images* tab. +..... Expand the image. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +**** To view the component and advisory data associated with a deployment: +..... Click the *<number> Deployments* tab. +..... Expand the deployment. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +** To view the component and advisory data associated with a CVE from the list of images, complete the following steps: +... Click the *<number> Images* tab. +... In the list of images, click an image. +... To view the component and advisory data associated with a CVE, expand the CVE. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +** To view the component and advisory data associated with a CVE from the list of deployments, complete the following steps: +... Click the *<number> Deployments* tab. +... In the list of deployments, click a deployment. +... To view the component and advisory data associated with a CVE, expand the CVE. ++ +You can find the component data in the *Component* column, and +you can find the advisory data in the *Advisory* column. +. Optional: Choose the appropriate method to re-organize the information in the *User Workloads* tab: +** To sort the table in ascending or descending order, select a column heading. +** To select the categories that you want to display in the table, perform the following steps: +... Click *Columns*. +... Choose the appropriate method to manage the columns: +**** To view all the categories, click *Select all*. +**** To reset to the default categories, click *Reset to default*. +**** To view only the selected categories, select the one or more categories that you want to view, and then click *Save*. +. In the list of results, click a CVE, image name, or deployment name to view more information about the item. For example, depending on the item type, you can view the following information: + +* Whether a CVE is fixable +* Whether an image is active +* The Dockerfile line in the image that contains the CVE +* External links to information about the CVE in Red{nbsp}Hat and other CVE databases diff --git a/modules/web-console-configuration.adoc b/modules/web-console-configuration.adoc deleted file mode 100644 index dde908f024db..000000000000 --- a/modules/web-console-configuration.adoc +++ /dev/null @@ -1,32 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/configuring-web-console.adoc - -[id="web-console-configuration_{context}"] -= Configuring the web console - -You can configure the web console settings by editing the `console.config.openshift.io` resource. - -* Edit the `console.config.openshift.io` resource: -+ -[source,terminal] ----- -$ oc edit console.config.openshift.io cluster ----- -+ -The following example displays the sample resource definition for the console: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Console -metadata: - name: cluster -spec: - authentication: - logoutRedirect: "" <1> -status: - consoleURL: "" <2> ----- -<1> Specify the URL of the page to load when a user logs out of the web console. If you do not specify a value, the user returns to the login page for the web console. Specifying a `logoutRedirect` URL allows your users to perform single logout (SLO) through the identity provider to destroy their single sign-on session. -<2> The web console URL. To update this to a custom value, see *Customizing the web console URL*. diff --git a/modules/web-console-disable.adoc b/modules/web-console-disable.adoc deleted file mode 100644 index 7dedfacf976d..000000000000 --- a/modules/web-console-disable.adoc +++ /dev/null @@ -1,33 +0,0 @@ -// Module included in the following assemblies: -// -// * web_console/disabling-web-console.adoc - -[id="web-console-disable_{context}"] -= Disabling the web console - -You can disable the web console by editing the -`consoles.operator.openshift.io` resource. - -* Edit the `consoles.operator.openshift.io` resource: -+ -[source,terminal] ----- -$ oc edit consoles.operator.openshift.io cluster ----- -+ -The following example displays the parameters from this resource that you can -modify: -+ -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Console -metadata: - name: cluster -spec: - managementState: Removed <1> ----- -<1> Set the `managementState` parameter value to `Removed` to disable the web -console. The other valid values for this parameter are `Managed`, which enables -the console under the cluster's control, and `Unmanaged`, which means that you -are taking control of web console management. diff --git a/modules/web-console-overview.adoc b/modules/web-console-overview.adoc deleted file mode 100644 index b6bd9ef85316..000000000000 --- a/modules/web-console-overview.adoc +++ /dev/null @@ -1,22 +0,0 @@ -// Module included in the following assemblies: -// * web_console/web-console.adoc - -[id="web-console-overview_{context}"] -= Understanding and accessing the web console - -The web console runs as a pod on the master. The static assets required to run -the web console are served by the pod. Once {product-title} is successfully -installed, find the URL for the web console and login credentials for your -installed cluster in the CLI output of the installation program. For example: - -[source,terminal] -.Example output ----- -INFO Install complete! -INFO Run 'export KUBECONFIG=<your working directory>/auth/kubeconfig' to manage the cluster with 'oc', the OpenShift CLI. -INFO The cluster is ready when 'oc login -u kubeadmin -p <provided>' succeeds (wait a few minutes). -INFO Access the OpenShift web-console here: https://console-openshift-console.apps.demo1.openshift4-beta-abcorp.com -INFO Login to the console with user: kubeadmin, password: <provided> ----- - -Use those details to log in and access the web console. diff --git a/modules/webhook-configuring-acs.adoc b/modules/webhook-configuring-acs.adoc new file mode 100644 index 000000000000..b507d4b45214 --- /dev/null +++ b/modules/webhook-configuring-acs.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * integration/integrate-using-generic-webhooks.adoc +:_mod-docs-content-type: PROCEDURE +[id="webhook-configuring-acs_{context}"] += Configuring integrations by using webhooks + +[role="_abstract"] +Create a new integration in {product-title} by using the webhook URL. + +.Procedure +. In the {product-title-short} portal, go to *Platform Configuration* -> *Integrations*. +. Scroll down to the *Notifier Integrations* section and select *Generic Webhook*. +. Click *New integration*. +. Enter a name for *Integration name*. +. Enter the webhook URL in the *Endpoint* field. +. If your webhook receiver uses an untrusted certificate, enter a CA certificate in the *CA certificate* field. Otherwise, leave it blank. ++ +[NOTE] +==== +The server certificate used by the webhook receiver must be valid for the endpoint DNS name. +You can click *Skip TLS verification* to ignore this validation. +Red{nbsp}Hat does not suggest turning off TLS verification. Without TLS verification, data could be intercepted by an unintended recipient. +==== +. Optional: Click *Enable audit logging* to receive alerts about all the changes made in {product-title}. +//See link:/docs/integrate-with-other-tools/enable-audit-logging/[Audit Logging] for more information. ++ +[NOTE] +==== +Red{nbsp}Hat suggests using separate webhooks for alerts and audit logs to handle these messages differently. +==== +. To authenticate with the webhook receiver, enter details for one of the following: +** *Username* and *Password* for basic HTTP authentication +** Custom *Header*, for example: `Authorization: Bearer <access_token>` +. Use *Extra fields* to include additional key-value pairs in the JSON object that {product-title} sends. +For example, if your webhook receiver accepts objects from multiple sources, you can add `"source": "rhacs"` as an extra field and filter on this value to identify all alerts from {product-title}. +. Select *Test* to send a test message to verify that the integration with your generic webhook is working. +. Select *Save* to create the configuration. diff --git a/modules/what-huge-pages-do.adoc b/modules/what-huge-pages-do.adoc deleted file mode 100644 index 856b7eef0494..000000000000 --- a/modules/what-huge-pages-do.adoc +++ /dev/null @@ -1,57 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc -// * virt/virtual_machines/advanced_vm_management/virt-using-huge-pages-with-vms.adoc -// * post_installation_configuration/node-tasks.adoc - -ifeval::["{context}" == "huge-pages"] -:ocp-hugepages: -endif::[] - -ifeval::["{context}" == "virt-using-huge-pages-with-vms"] -:virt-hugepages: -endif::[] - -[id="what-huge-pages-do_{context}"] -= What huge pages do - -Memory is managed in blocks known as pages. On most systems, a page is 4Ki. 1Mi -of memory is equal to 256 pages; 1Gi of memory is 256,000 pages, and so on. CPUs -have a built-in memory management unit that manages a list of these pages in -hardware. The Translation Lookaside Buffer (TLB) is a small hardware cache of -virtual-to-physical page mappings. If the virtual address passed in a hardware -instruction can be found in the TLB, the mapping can be determined quickly. If -not, a TLB miss occurs, and the system falls back to slower, software-based -address translation, resulting in performance issues. Since the size of the TLB -is fixed, the only way to reduce the chance of a TLB miss is to increase the -page size. - -A huge page is a memory page that is larger than 4Ki. On x86_64 architectures, -there are two common huge page sizes: 2Mi and 1Gi. Sizes vary on other -architectures. To use huge pages, code must be written so that -applications are aware of them. Transparent Huge Pages (THP) attempt to automate -the management of huge pages without application knowledge, but they have -limitations. In particular, they are limited to 2Mi page sizes. THP can lead to -performance degradation on nodes with high memory utilization or fragmentation -due to defragmenting efforts of THP, which can lock memory pages. For this -reason, some applications may be designed to (or recommend) usage of -pre-allocated huge pages instead of THP. - -ifdef::ocp-hugepages[] -In {product-title}, applications in a pod can allocate and consume pre-allocated -huge pages. -endif::ocp-hugepages[] - -ifdef::virt-hugepages[] -In {VirtProductName}, virtual machines can be configured to consume pre-allocated -huge pages. -endif::virt-hugepages[] - - -ifeval::["{context}" == "huge-pages"] -:ocp-hugepages!: -endif::[] - -ifeval::["{context}" == "virt-using-huge-pages-with-vms"] -:virt-hugepages!: -endif::[] diff --git a/modules/windows-machine-config-operator.adoc b/modules/windows-machine-config-operator.adoc deleted file mode 100644 index 82de9ce6ca60..000000000000 --- a/modules/windows-machine-config-operator.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// Module included in the following assemblies: -// -// * operators/operator-reference.adoc - -[id="windows-machine-config-operator_{context}"] -= Windows Machine Config Operator - -[discrete] -== Purpose - -The Windows Machine Config Operator (WMCO) orchestrates the process of deploying and managing Windows workloads on a cluster. The WMCO configures Windows machines into compute nodes, enabling Windows container workloads to run in {product-title} clusters. This is done by creating a machine set that uses a Windows image with the Docker-formatted container runtime installed. The WMCO completes all necessary steps to configure the underlying Windows VM so that it can join the cluster as a compute node. - -[discrete] -== Project - -link:https://github.com/openshift/windows-machine-config-operator[windows-machine-config-operator] diff --git a/modules/windows-machineset-aws.adoc b/modules/windows-machineset-aws.adoc deleted file mode 100644 index ce45b2ca2ef1..000000000000 --- a/modules/windows-machineset-aws.adoc +++ /dev/null @@ -1,86 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.adoc - -[id="windows-machineset-aws_{context}"] -= Sample YAML for a Windows `MachineSet` object on AWS - -This sample YAML defines a Windows `MachineSet` object running on Amazon Web Services (AWS) that the Windows Machine Config Operator (WMCO) can react upon. - -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - name: <infrastructure_id>-windows-worker-<zone> <2> - namespace: openshift-machine-api -spec: - replicas: 1 - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machineset: <infrastructure_id>-windows-worker-<zone> <2> - template: - metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machine-role: worker - machine.openshift.io/cluster-api-machine-type: worker - machine.openshift.io/cluster-api-machineset: <infrastructure_id>-windows-worker-<zone> <2> - machine.openshift.io/os-id: Windows <3> - spec: - metadata: - labels: - node-role.kubernetes.io/worker: "" <4> - providerSpec: - value: - ami: - id: <windows_container_ami> <5> - apiVersion: awsproviderconfig.openshift.io/v1beta1 - blockDevices: - - ebs: - iops: 0 - volumeSize: 120 - volumeType: gp2 - credentialsSecret: - name: aws-cloud-credentials - deviceIndex: 0 - iamInstanceProfile: - id: <infrastructure_id>-worker-profile <1> - instanceType: m5a.large - kind: AWSMachineProviderConfig - placement: - availabilityZone: <zone> <6> - region: <region> <7> - securityGroups: - - filters: - - name: tag:Name - values: - - <infrastructure_id>-worker-sg <1> - subnet: - filters: - - name: tag:Name - values: - - <infrastructure_id>-private-<zone> <1> - tags: - - name: kubernetes.io/cluster/<infrastructure_id> <1> - value: owned - userDataSecret: - name: windows-user-data <8> - namespace: openshift-machine-api ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. You can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- -<2> Specify the infrastructure ID, worker label, and zone. -<3> Configure the machine set as a Windows machine. -<4> Configure the Windows node as a compute machine. -<5> Specify the AMI ID of a Windows image with a container runtime installed. You must use Windows Server 2019. -<6> Specify the AWS zone, like `us-east-1a`. -<7> Specify the AWS region, like `us-east-1`. -<8> Created by the WMCO when it is configuring the first Windows machine. After that, the `windows-user-data` is available for all subsequent machine sets to consume. diff --git a/modules/windows-machineset-azure.adoc b/modules/windows-machineset-azure.adoc deleted file mode 100644 index 3fda45e1d221..000000000000 --- a/modules/windows-machineset-azure.adoc +++ /dev/null @@ -1,80 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-azure.adoc - -[id="windows-machineset-azure_{context}"] -= Sample YAML for a Windows `MachineSet` object on Azure - -This sample YAML defines a Windows `MachineSet` object running on Microsoft Azure that the Windows Machine Config Operator (WMCO) can react upon. - -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - name: <windows_machine_set_name> <2> - namespace: openshift-machine-api -spec: - replicas: 1 - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machineset: <windows_machine_set_name> <2> - template: - metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machine-role: worker - machine.openshift.io/cluster-api-machine-type: worker - machine.openshift.io/cluster-api-machineset: <windows_machine_set_name> <2> - machine.openshift.io/os-id: Windows <3> - spec: - metadata: - labels: - node-role.kubernetes.io/worker: "" <4> - providerSpec: - value: - apiVersion: azureproviderconfig.openshift.io/v1beta1 - credentialsSecret: - name: azure-cloud-credentials - namespace: openshift-machine-api - image: <5> - offer: WindowsServer - publisher: MicrosoftWindowsServer - resourceID: "" - sku: 2019-Datacenter-with-Containers - version: latest - kind: AzureMachineProviderSpec - location: <location> <6> - managedIdentity: <infrastructure_id>-identity <1> - networkResourceGroup: <infrastructure_id>-rg <1> - osDisk: - diskSizeGB: 128 - managedDisk: - storageAccountType: Premium_LRS - osType: Windows - publicIP: false - resourceGroup: <infrastructure_id>-rg <1> - subnet: <infrastructure_id>-worker-subnet - userDataSecret: - name: windows-user-data <7> - namespace: openshift-machine-api - vmSize: Standard_D2s_v3 - vnet: <infrastructure_id>-vnet <1> - zone: "<zone>" <8> ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. You can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- -<2> Specify the Windows machine set name. Windows machine names on Azure cannot be more than 15 characters long. Therefore, the machine set name cannot be more than 9 characters long, due to the way machine names are generated from it. -<3> Configure the machine set as a Windows machine. -<4> Configure the Windows node as a compute machine. -<5> Specify a `WindowsServer` image offering that defines the `2019-Datacenter-with-Containers` SKU. -<6> Specify the Azure region, like `centralus`. -<7> Created by the WMCO when it is configuring the first Windows machine. After that, the `windows-user-data` is available for all subsequent machine sets to consume. -<8> Specify the zone within your region to place machines on. Be sure that your region supports the zone that you specify. diff --git a/modules/windows-machineset-vsphere.adoc b/modules/windows-machineset-vsphere.adoc deleted file mode 100644 index e4bb5e2447ca..000000000000 --- a/modules/windows-machineset-vsphere.adoc +++ /dev/null @@ -1,77 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc - -[id="windows-machineset-vsphere_{context}"] -= Sample YAML for a Windows MachineSet object on vSphere - -This sample YAML defines a Windows `MachineSet` object running on VMware vSphere that the Windows Machine Config Operator (WMCO) can react upon. - -[source,yaml] ----- -apiVersion: machine.openshift.io/v1beta1 -kind: MachineSet -metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - name: <windows_machine_set_name> <2> - namespace: openshift-machine-api -spec: - replicas: 1 - selector: - matchLabels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machineset: <windows_machine_set_name> <2> - template: - metadata: - labels: - machine.openshift.io/cluster-api-cluster: <infrastructure_id> <1> - machine.openshift.io/cluster-api-machine-role: worker - machine.openshift.io/cluster-api-machine-type: worker - machine.openshift.io/cluster-api-machineset: <windows_machine_set_name> <2> - machine.openshift.io/os-id: Windows <3> - spec: - metadata: - labels: - node-role.kubernetes.io/worker: "" <4> - providerSpec: - value: - apiVersion: vsphereprovider.openshift.io/v1beta1 - credentialsSecret: - name: vsphere-cloud-credentials - diskGiB: 128 - kind: VSphereMachineProviderSpec - memoryMiB: 16384 - network: - devices: - - networkName: "<vm_network_name>" <5> - numCPUs: 4 - numCoresPerSocket: 1 - snapshot: "" - template: <windows_vm_template_name> <6> - userDataSecret: - name: windows-user-data <7> - workspace: - datacenter: <vcenter_datacenter_name> <8> - datastore: <vcenter_datastore_name> <9> - folder: <vcenter_vm_folder_path> <10> - resourcePool: <vsphere_resource_pool> <11> - server: <vcenter_server_ip> <12> ----- -<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. You can obtain the infrastructure ID by running the following command: -+ -[source,terminal] ----- -$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster ----- -<2> Specify the Windows machine set name. The machine set name cannot be more than 9 characters long, due to the way machine names are generated in vSphere. -<3> Configure the machine set as a Windows machine. -<4> Configure the Windows node as a compute machine. -<5> Specify the vSphere VM network to deploy the machine set to. -<6> Specify the full path of the Windows vSphere VM template to use, such as `/Datacenter/vm/ocp4-llplx/windows-golden-image`. The name must be unique. -<7> The `windows-user-data` is created by the WMCO when the first Windows machine is configured. After that, the `windows-user-data` is available for all subsequent machine sets to consume. -<8> Specify the vCenter Datacenter to deploy the machine set on. -<9> Specify the vCenter Datastore to deploy the machine set on. -<10> Specify the path to the vSphere VM folder in vCenter, such as `/dc1/vm/user-inst-5ddjd`. -<11> Optional: Specify the vSphere resource pool for your Windows VMs. -<12> Specify the vCenter server IP or fully qualified domain name. diff --git a/modules/windows-node-services.adoc b/modules/windows-node-services.adoc deleted file mode 100644 index bce763fd1a2d..000000000000 --- a/modules/windows-node-services.adoc +++ /dev/null @@ -1,31 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/understanding-windows-container-workloads.adoc - -[id="windows-node-services_{context}"] -= Windows node services - -The following Windows-specific services are installed on each Windows node: - -[cols="1,2",options="header"] -|=== - -|Service -|Description - -|kubelet -|Registers the Windows node and manages its status. - -|Container Network Interface (CNI) plug-ins -|Exposes link:https://kubernetes.io/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#networking[networking] for Windows nodes. - -|Windows Machine Config Bootstrapper (WMCB) -|Configures the kubelet and CNI plug-ins. - -|hybrid-overlay -|Creates the {product-title} link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/container-networking/architecture#container-network-management-with-host-network-service[Host Network Service (HNS)]. - -|kube-proxy -|Maintains network rules on nodes allowing outside communication. - -|=== diff --git a/modules/windows-pod-placement.adoc b/modules/windows-pod-placement.adoc deleted file mode 100644 index a12e2aa7b2ed..000000000000 --- a/modules/windows-pod-placement.adoc +++ /dev/null @@ -1,12 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/scheduling-windows-workloads.adoc - -[id="windows-pod-placement_{context}"] -= Windows pod placement - -Before deploying your Windows workloads to the cluster, you must configure your Windows node scheduling so pods are assigned correctly. Since you have a machine hosting your Windows node, it is managed the same as a Linux-based node. Likewise, scheduling a Windows pod to the appropriate Windows node is completed similarly, using mechanisms like taints, tolerations, and node selectors. - -With multiple operating systems, and the ability to run multiple Windows OS variants, in the same cluster, you must map your Windows pods to a base Windows OS variant by using a `RuntimeClass`. For example, if you have multiple Windows nodes running on different Windows Server container versions, the cluster could schedule your Windows pods to an incompatible Windows OS variant. You must have `RuntimeClass` objects configured for each Windows OS variant on your cluster. Using a `RuntimeClass` object is also recommended if you have only one Windows OS variant available in your cluster. - -For more information, see Microsoft's documentation on link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/update-containers#host-and-container-version-compatibility[Host and container version compatibility]. diff --git a/modules/windows-workload-management.adoc b/modules/windows-workload-management.adoc deleted file mode 100644 index 911833310da5..000000000000 --- a/modules/windows-workload-management.adoc +++ /dev/null @@ -1,34 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/understanding-windows-container-workloads.adoc - -[id="windows-workload-management_{context}"] -= Windows workload management - -To run Windows workloads in your cluster, you must first install the Windows Machine Config Operator (WMCO). The WMCO is a Linux-based Operator that runs on Linux-based control plane and compute nodes. The WMCO orchestrates the process of deploying and managing Windows workloads on a cluster. - -.WMCO design -image::wmco-design.png[WMCO workflow] - -Before deploying Windows workloads, you must create a Windows compute node and have it join the cluster. The Windows node hosts the Windows workloads in a cluster, and can run alongside other Linux-based compute nodes. You can create a Windows compute node by creating a Windows machine set to host Windows Server compute machines. You must apply a Windows-specific label to the machine set that specifies a Windows OS image that has the Docker-formatted container runtime add-on enabled. - -[IMPORTANT] -==== -Currently, the Docker-formatted container runtime is used in Windows nodes. Kubernetes is deprecating Docker as a container runtime; you can reference the Kubernetes documentation for more information in link:https://kubernetes.io/blog/2020/12/02/dont-panic-kubernetes-and-docker/[Docker deprecation]. Containerd will be the new supported container runtime for Windows nodes in a future release of Kubernetes. -==== - -The WMCO watches for machines with the Windows label. After a Windows machine set is detected and its respective machines are provisioned, the WMCO configures the underlying Windows virtual machine (VM) so that it can join the cluster as a compute node. - -.Mixed Windows and Linux workloads -image::mixed-windows-linux-workloads.png[Mixed Windows and Linux workloads] - -The WMCO expects a predetermined secret in its namespace containing a private key that is used to interact with the Windows instance. WMCO checks for this secret during boot up time and creates a user data secret which you must reference in the Windows `MachineSet` object that you created. Then the WMCO populates the user data secret with a public key that corresponds to the private key. With this data in place, the cluster can connect to the Windows VM using an SSH connection. - -After the cluster establishes a connection with the Windows VM, you can manage the Windows node using similar practices as you would a Linux-based node. - -[NOTE] -==== -The {product-title} web console provides most of the same monitoring capabilities for Windows nodes that are available for Linux nodes. However, the ability to monitor workload graphs for pods running on Windows nodes is not available at this time. -==== - -Scheduling Windows workloads to a Windows node can be done with typical pod scheduling practices like taints, tolerations, and node selectors; alternatively, you can differentiate your Windows workloads from Linux workloads and other Windows-versioned workloads by using a `RuntimeClass` object. diff --git a/modules/wmco-does-not-install.adoc b/modules/wmco-does-not-install.adoc deleted file mode 100644 index a1a4c01efe08..000000000000 --- a/modules/wmco-does-not-install.adoc +++ /dev/null @@ -1,10 +0,0 @@ -// Module included in the following assemblies: -// -// * support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc - -[id="wmco-does-not-install_{context}"] -= Windows Machine Config Operator does not install - -If you have completed the process of installing the Windows Machine Config Operator (WMCO), but the Operator is stuck in the `InstallWaiting` phase, your issue is likely caused by a networking issue. - -The WMCO requires your {product-title} cluster to be configured with hybrid networking using OVN-Kubernetes; the WMCO cannot complete the installation process without hybrid networking available. This is necessary to manage nodes on multiple operating systems (OS) and OS variants. This must be completed during the installation of your cluster. diff --git a/modules/wmco-upgrades.adoc b/modules/wmco-upgrades.adoc deleted file mode 100644 index 9ed552e2565b..000000000000 --- a/modules/wmco-upgrades.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * windows_containers/windows-node-upgrades.adoc - -[id="wmco-upgrades_{context}"] -= Windows Machine Config Operator upgrades - -When a new version of the Windows Machine Config Operator (WMCO) is released that is compatible with the current cluster version, the Operator is upgraded based on the upgrade channel and subscription approval strategy it was installed with when using the Operator Lifecycle Manager (OLM). The WMCO upgrade results in the Kubernetes components in the Windows machine being upgraded. - -[NOTE] -==== -If you are upgrading to a new version of the WMCO and want to use cluster monitoring, you must have the `openshift.io/cluster-monitoring=true` label present in the WMCO namespace. If you add the label to a pre-existing WMCO namespace, and there are already Windows nodes configured, restart the WMCO pod to allow monitoring graphs to display. -==== - -For a non-disruptive upgrade, the WMCO terminates the Windows machines configured by the previous version of the WMCO and recreates them using the current version. This is done by deleting the `Machine` object, which results in the drain and deletion of the Windows node. To facilitate an upgrade, the WMCO adds a version annotation to all the configured nodes. During an upgrade, a mismatch in version annotation results in the deletion and recreation of a Windows machine. To have minimal service disruptions during an upgrade, the WMCO only updates one Windows machine at a time. - -[IMPORTANT] -==== -The WMCO is only responsible for updating Kubernetes components, not for Windows operating system updates. You provide the Windows image when creating the VMs; therefore, you are responsible for providing an updated image. You can provide an updated Windows image by changing the image configuration in the `MachineSet` spec. -==== diff --git a/monitoring/accessing-third-party-uis.adoc b/monitoring/accessing-third-party-uis.adoc deleted file mode 100644 index 6f029e57a841..000000000000 --- a/monitoring/accessing-third-party-uis.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[id="accessing-third-party-uis"] -= Accessing third-party UIs -include::modules/common-attributes.adoc[] -:context: accessing-third-party-uis - -toc::[] - -Integrated Metrics, Alerting, and Dashboard UIs are provided in the {product-title} web console. See the following for details on using these integrated UIs: - -* xref:../monitoring/managing-metrics.adoc#managing-metrics[Managing metrics] -* xref:../monitoring/managing-alerts.adoc#managing-alerts[Managing alerts] -* xref:../monitoring/reviewing-monitoring-dashboards.adoc#reviewing-monitoring-dashboards[ -Reviewing monitoring dashboards] - -{product-title} also provides access to the Prometheus, Alertmanager, and Grafana third-party interfaces. - -[NOTE] -==== -Default access to the third-party monitoring interfaces might be removed in future {product-title} releases. Following this, you will need to use port-forwarding to access them. -==== - -[NOTE] -==== -The Grafana instance that is provided with the {product-title} monitoring stack, along with its dashboards, is read-only. -==== - -[NOTE] -==== -The Grafana dashboard includes Kubernetes and `cluster-monitoring` metrics only. Additional platform components are included in *Monitoring* → *Dashboards* in the {product-title} web console. -==== - -// Accessing third-party monitoring UIs by using the web console -include::modules/monitoring-accessing-third-party-uis-using-the-web-console.adoc[leveloffset=+1] - -// Accessing third-party monitoring UIs by using the CLI -include::modules/monitoring-accessing-third-party-uis-using-the-cli.adoc[leveloffset=+1] - -[IMPORTANT] -==== -The monitoring routes are managed by the Cluster Monitoring Operator and they cannot be modified by the user. -==== - -== Next steps - -* xref:../monitoring/exposing-custom-application-metrics-for-autoscaling.adoc#exposing-custom-application-metrics-for-horizontal-pod-autoscaling_exposing-custom-application-metrics-for-autoscaling[ -Exposing custom application metrics for autoscaling] diff --git a/monitoring/application-monitoring.adoc b/monitoring/application-monitoring.adoc deleted file mode 100644 index 4c6c28e119d9..000000000000 --- a/monitoring/application-monitoring.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="application-monitoring"] -= Application monitoring -include::modules/common-attributes.adoc[] -:context: application-monitoring - -toc::[] - -You can configure custom metrics scraping for your applications. For that, you deploy the Prometheus Operator and a custom Prometheus instance and Alertmanager instance in the namespace where your application is. - -:FeatureName: Application monitoring -include::modules/technology-preview.adoc[leveloffset=+0] - -include::modules/monitoring-configuring-cluster-for-application-monitoring.adoc[leveloffset=+1] -include::modules/monitoring-configuring-monitoring-for-an-application.adoc[leveloffset=+1] -include::modules/monitoring-exposing-custom-application-metrics-for-horizontal-pod-autoscaling.adoc[leveloffset=+1] - -== Next steps - -* To automatically adjust the number of pods in which the application runs, xref:../monitoring/application-monitoring.adoc#application-monitoring[configure Horizontal Pod Autoscaling for the application.] diff --git a/monitoring/configuring-hpa-for-an-application.adoc b/monitoring/configuring-hpa-for-an-application.adoc deleted file mode 100644 index 1886680a23ed..000000000000 --- a/monitoring/configuring-hpa-for-an-application.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="configuring-hpa-for-an-application"] -= Configuring HPA for an application -include::modules/common-attributes.adoc[] -:context: configuring-hpa-for-an-application - -toc::[] - -You can configure Horizontal Pod Autoscaling (HPA) for an application that exports metrics. - -:FeatureName: Horizontal Pod Autoscaling for an application -include::modules/technology-preview.adoc[leveloffset=+0] - -== Prerequisites - -* Install the OpenShift CLI (`oc`). -* You must log in to the cluster with a user that has the `cluster-admin` role. -* Make sure you configured the cluster for application monitoring. In the following example, it is presumed that Prometheus and Alertmanager instances were installed in the `default` project. See xref:../monitoring/application-monitoring.adoc#configuring-cluster-for-application-monitoring_application-monitoring[Application monitoring]. -* Make sure you configured monitoring for your application. In the following example, it is presumed that the application and the service monitor for it were installed in the `default` project. See xref:../monitoring/application-monitoring.adoc#configuring-monitoring-for-an-application_application-monitoring[Application monitoring]. -* Make sure your application exposes metrics using the `prometheus-adapter`. In the following example, it is presumed that `prometheus-adapater` was installed in the `default` project. See xref:../monitoring/application-monitoring.adoc#exposing-custom-application-metrics-for-horizontal-pod-autoscaling_application-monitoring[Application monitoring]. - -include::modules/configuring-hpa-based-on-application-metrics.adoc[leveloffset=+1] - -.Additional resources - -See the xref:../nodes/pods/nodes-pods-autoscaling.adoc#nodes-pods-autoscaling[horizontal pod autoscaling documentation]. diff --git a/monitoring/configuring-the-monitoring-stack.adoc b/monitoring/configuring-the-monitoring-stack.adoc deleted file mode 100644 index 1ffe94ef99e9..000000000000 --- a/monitoring/configuring-the-monitoring-stack.adoc +++ /dev/null @@ -1,139 +0,0 @@ -[id="configuring-the-monitoring-stack"] -= Configuring the monitoring stack -include::modules/common-attributes.adoc[] -:context: configuring-the-monitoring-stack - -toc::[] - -The {product-title} 4 installation program provides only a low number of configuration options before installation. Configuring most {product-title} framework components, including the cluster monitoring stack, happens post-installation. - -This section explains what configuration is supported, shows how to configure the monitoring stack, and demonstrates several common configuration scenarios. - -== Prerequisites - -* The monitoring stack imposes additional resource requirements. Consult the computing resources recommendations in xref:../scalability_and_performance/scaling-cluster-monitoring-operator.adoc#scaling-cluster-monitoring-operator[Scaling the Cluster Monitoring Operator] and verify that you have sufficient resources. - -// Maintenance and support for monitoring -include::modules/monitoring-maintenance-and-support.adoc[leveloffset=+1] -include::modules/monitoring-support-considerations.adoc[leveloffset=+2] -include::modules/monitoring-unmanaged-monitoring-operators.adoc[leveloffset=+2] - -// Preparing to configure the monitoring stack -[id="preparing-to-configure-the-monitoring-stack"] -== Preparing to configure the monitoring stack - -You can configure the monitoring stack by creating and updating monitoring config maps. - -include::modules/monitoring-creating-cluster-monitoring-configmap.adoc[leveloffset=+2] -include::modules/monitoring-creating-user-defined-workload-monitoring-configmap.adoc[leveloffset=+2] - -.Additional resources - -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] - -// Configuring the monitoring stack -include::modules/monitoring-configuring-the-monitoring-stack.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#preparing-to-configure-the-monitoring-stack[Preparing to configure the monitoring stack] for steps to create monitoring config maps -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] - -// Configurable monitoring components -include::modules/monitoring-configurable-monitoring-components.adoc[leveloffset=+1] - -// Moving monitoring components to different nodes -include::modules/monitoring-moving-monitoring-components-to-different-nodes.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#preparing-to-configure-the-monitoring-stack[Preparing to configure the monitoring stack] for steps to create monitoring config maps -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] -* xref:../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-working-updating_nodes-nodes-working[Understanding how to update labels on nodes] -* xref:../nodes/scheduling/nodes-scheduler-node-selectors.adoc#nodes-scheduler-node-selectors[Placing pods on specific nodes using node selectors] -* See the link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector[Kubernetes documentation] for details on the `nodeSelector` constraint - -// Assigning tolerations to monitoring components -include::modules/monitoring-assigning-tolerations-to-monitoring-components.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#preparing-to-configure-the-monitoring-stack[Preparing to configure the monitoring stack] for steps to create monitoring config maps -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] -* See the xref:../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations[{product-title} documentation] on taints and tolerations -* See the link:https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/[Kubernetes documentation] on taints and tolerations - -// Configuring persistent storage -[id="configuring-persistent-storage"] -== Configuring persistent storage - -Running cluster monitoring with persistent storage means that your metrics are stored to a persistent volume (PV) and can survive a pod being restarted or recreated. This is ideal if you require your metrics or alerting data to be guarded from data loss. For production environments, it is highly recommended to configure persistent storage. Because of the high IO demands, it is advantageous to use local storage. - -[IMPORTANT] -==== -If you are running cluster monitoring with an attached PVC for Prometheus, you might experience OOM kills during cluster upgrade. When persistent storage is in use for Prometheus, Prometheus memory usage doubles during cluster upgrade and for several hours after upgrade is complete. To avoid the OOM kill issue, allow worker nodes with double the size of memory that was available prior to the upgrade. For example, if you are running monitoring on the minimum recommended nodes, which is 2 cores with 8 GB of RAM, increase memory to 16 GB. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1925061[BZ#1925061]. -==== - -[NOTE] -==== -See xref:../scalability_and_performance/optimizing-storage.adoc#recommended-configurable-storage-technology_persistent-storage[Recommended configurable storage technology]. -==== - -[id="persistent-storage-prerequisites"] -=== Persistent storage prerequisites - -* Dedicate sufficient local persistent storage to ensure that the disk does not become full. How much storage you need depends on the number of pods. For information on system requirements for persistent storage, see xref:../scalability_and_performance/scaling-cluster-monitoring-operator.adoc#prometheus-database-storage-requirements[Prometheus database storage requirements]. - -* Make sure you have a persistent volume (PV) ready to be claimed by the persistent volume claim (PVC), one PV for each replica. Because Prometheus has two replicas and Alertmanager has three replicas, you need five PVs to support the entire monitoring stack. The PVs should be available from the Local Storage Operator. This does not apply if you enable dynamically provisioned storage. - -* Use the block type of storage. - -* xref:../storage/persistent_storage/persistent-storage-local.adoc#persistent-storage-using-local-volume[Configure local persistent storage.] -+ -[NOTE] -==== -If you use a local volume for persistent storage, do not use a raw block volume, which is described with `volumeMode: block` in the `LocalVolume` object. Elasticsearch cannot use raw block volumes. -==== - -include::modules/monitoring-configuring-a-local-persistent-volume-claim.adoc[leveloffset=+2] -include::modules/monitoring-modifying-retention-time-for-prometheus-metrics-data.adoc[leveloffset=+2] - -.Additional resources - -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#preparing-to-configure-the-monitoring-stack[Preparing to configure the monitoring stack] for steps to create monitoring config maps -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] -* xref:../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage] -* xref:../scalability_and_performance/optimizing-storage.adoc#optimizing-storage[Optimizing storage] - -// Managing scrape sample limits for user-defined projects -include::modules/monitoring-limiting-scrape-samples-in-user-defined-projects.adoc[leveloffset=+1] -include::modules/monitoring-setting-a-scrape-sample-limit-for-user-defined-projects.adoc[leveloffset=+2] -include::modules/monitoring-creating-scrape-sample-alerts.adoc[leveloffset=+2] - -.Additional resources - -* xref:../monitoring/configuring-the-monitoring-stack.adoc#creating-user-defined-workload-monitoring-configmap_configuring-the-monitoring-stack[Creating a user-defined workload monitoring config map] -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] -* See xref:../monitoring/troubleshooting-monitoring-issues.html#determining-why-prometheus-is-consuming-disk-space_troubleshooting-monitoring-issues[Determining why Prometheus is consuming a lot of disk space] for steps to query which metrics have the highest number of scrape samples - -//Attaching additional labels to your time series and alerts -include::modules/monitoring-attaching-additional-labels-to-your-time-series-and-alerts.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#preparing-to-configure-the-monitoring-stack[Preparing to configure the monitoring stack] for steps to create monitoring config maps -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#preparing-to-configure-the-monitoring-stack[Preparing to configure the monitoring stack] for steps to create monitoring config maps - -// Setting log levels for monitoring components -include::modules/monitoring-setting-log-levels-for-monitoring-components.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#preparing-to-configure-the-monitoring-stack[Preparing to configure the monitoring stack] for steps to create monitoring config maps -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] - -== Next steps - -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] -* Learn about xref:../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting_opting-out-remote-health-reporting[remote health reporting] and, if necessary, opt out of it diff --git a/monitoring/enabling-monitoring-for-user-defined-projects.adoc b/monitoring/enabling-monitoring-for-user-defined-projects.adoc deleted file mode 100644 index 5fdf0fd63a0d..000000000000 --- a/monitoring/enabling-monitoring-for-user-defined-projects.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="enabling-monitoring-for-user-defined-projects"] -= Enabling monitoring for user-defined projects -include::modules/common-attributes.adoc[] -:context: enabling-monitoring-for-user-defined-projects - -toc::[] - -In {product-title} {product-version}, you can enable monitoring for user-defined projects in addition to the default platform monitoring. You can now monitor your own projects in {product-title} without the need for an additional monitoring solution. Using this new feature centralizes monitoring for core platform components and user-defined projects. - -[NOTE] -==== -Custom Prometheus instances and the Prometheus Operator installed through Operator Lifecycle Manager (OLM) can cause issues with user-defined workload monitoring if it is enabled. Custom Prometheus instances are not supported in {product-title}. -==== - -// Enabling monitoring for user-defined projects -include::modules/monitoring-enabling-monitoring-for-user-defined-projects.adoc[leveloffset=+1] - -.Additional resources - -* xref:../monitoring/configuring-the-monitoring-stack.adoc#creating-cluster-monitoring-configmap_configuring-the-monitoring-stack[Creating a cluster monitoring config map] -* xref:../monitoring/configuring-the-monitoring-stack.adoc#configuring-the-monitoring-stack[Configuring the monitoring stack] -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.html#granting-users-permission-to-configure-monitoring-for-user-defined-projects_enabling-monitoring-for-user-defined-projects[Granting users permission to configure monitoring for user-defined projects] - -// Granting users permission to monitor user-defined projects -include::modules/monitoring-granting-users-permission-to-monitor-user-defined-projects.adoc[leveloffset=+1] -include::modules/monitoring-granting-user-permissions-using-the-web-console.adoc[leveloffset=+2] -include::modules/monitoring-granting-user-permissions-using-the-cli.adoc[leveloffset=+2] - -// Granting users permission to configure monitoring for user-defined projects -include::modules/monitoring-granting-users-permission-to-configure-monitoring-for-user-defined-projects.adoc[leveloffset=+1] - -// Disabling monitoring for user-defined projects -include::modules/monitoring-disabling-monitoring-for-user-defined-projects.adoc[leveloffset=+1] - -== Next steps - -* xref:../monitoring/managing-metrics.adoc#managing-metrics[Managing metrics] diff --git a/monitoring/exposing-custom-application-metrics-for-autoscaling.adoc b/monitoring/exposing-custom-application-metrics-for-autoscaling.adoc deleted file mode 100644 index 6434579d9346..000000000000 --- a/monitoring/exposing-custom-application-metrics-for-autoscaling.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="exposing-custom-application-metrics-for-autoscaling"] -= Exposing custom application metrics for autoscaling -include::modules/common-attributes.adoc[] -:context: exposing-custom-application-metrics-for-autoscaling - -toc::[] - -You can export custom application metrics for the horizontal pod autoscaler. - -:FeatureName: Prometheus Adapter -include::modules/technology-preview.adoc[leveloffset=+0] - -// Exposing custom application metrics for horizontal pod autoscaling -include::modules/monitoring-exposing-custom-application-metrics-for-horizontal-pod-autoscaling.adoc[leveloffset=+1] - -.Additional resources - -* See the xref:../nodes/pods/nodes-pods-autoscaling.adoc#nodes-pods-autoscaling[horizontal pod autoscaling documentation] -* See the link:https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale[Kubernetes documentation on horizontal pod autoscaler] - -== Next steps - -* xref:../monitoring/troubleshooting-monitoring-issues.adoc#troubleshooting-monitoring-issues[Troubleshooting monitoring issues] diff --git a/monitoring/managing-alerts.adoc b/monitoring/managing-alerts.adoc deleted file mode 100644 index 5005510ae017..000000000000 --- a/monitoring/managing-alerts.adoc +++ /dev/null @@ -1,65 +0,0 @@ -[id="managing-alerts"] -= Managing alerts -include::modules/common-attributes.adoc[] -:context: managing-alerts - -toc::[] - -In {product-title} {product-version}, the Alerting UI enables you to manage alerts, silences, and alerting rules. - -* *Alerting rules*. Alerting rules contain a set of conditions that outline a particular state within a cluster. Alerts are triggered when those conditions are true. An alerting rule can be assigned a severity that defines how the alerts are routed. -* *Alerts*. An alert is fired when the conditions defined in an alerting rule are true. Alerts provide a notification that a set of circumstances are apparent within an {product-title} cluster. -* *Silences*. A silence can be applied to an alert to prevent notifications from being sent when the conditions for an alert are true. You can mute an alert after the initial notification, while you work on resolving the underlying issue. - -[NOTE] -==== -The alerts, silences, and alerting rules that are available in the Alerting UI relate to the projects that you have access to. For example, if you are logged in with `cluster-administrator` privileges, all alerts, silences, and alerting rules are accessible. -==== - -// Accessing the Alerting UI in the Administrator and Developer perspectives -include::modules/monitoring-accessing-the-alerting-ui.adoc[leveloffset=+1] - -// Searching and filtering alerts, silences, and alerting rules -include::modules/monitoring-searching-alerts-silences-and-alerting-rules.adoc[leveloffset=+1] - -// Getting information about alerts, silences and alerting rules -include::modules/monitoring-getting-information-about-alerts-silences-and-alerting-rules.adoc[leveloffset=+1] - -// Managing alerting rules -include::modules/monitoring-managing-alerting-rules.adoc[leveloffset=+1] -include::modules/monitoring-optimizing-alerting-for-user-defined-projects.adoc[leveloffset=+2] - -.Additional resources - -* See the link:https://prometheus.io/docs/practices/alerting/[Prometheus alerting documentation] for further guidelines on optimizing alerts -* See xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Understanding the monitoring stack] for details about {product-title} {product-version} monitoring architecture - -include::modules/monitoring-creating-alerting-rules-for-user-defined-projects.adoc[leveloffset=+2] -include::modules/monitoring-reducing-latency-for-alerting-rules-that-do-not-query-platform-metrics.adoc[leveloffset=+2] - -* See xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Understanding the monitoring stack] for details about {product-title} {product-version} monitoring architecture. - -include::modules/monitoring-accessing-alerting-rules-for-your-project.adoc[leveloffset=+2] -include::modules/monitoring-listing-alerting-rules-for-all-projects-in-a-single-view.adoc[leveloffset=+2] -include::modules/monitoring-removing-alerting-rules-for-user-defined-projects.adoc[leveloffset=+2] - -.Additional resources - -* See the link:https://prometheus.io/docs/alerting/alertmanager/[Alertmanager documentation] - -// Managing silences -include::modules/monitoring-managing-silences.adoc[leveloffset=+1] -include::modules/monitoring-silencing-alerts.adoc[leveloffset=+2] -include::modules/monitoring-editing-silences.adoc[leveloffset=+2] -include::modules/monitoring-expiring-silences.adoc[leveloffset=+2] - -// Sending notifications to external systems -include::modules/monitoring-sending-notifications-to-external-systems.adoc[leveloffset=+1] -include::modules/monitoring-configuring-alert-receivers.adoc[leveloffset=+2] - -// Applying a custom Alertmanager configuration -include::modules/monitoring-applying-custom-alertmanager-configuration.adoc[leveloffset=+1] - -== Next steps - -* xref:../monitoring/reviewing-monitoring-dashboards.adoc#reviewing-monitoring-dashboards[Reviewing monitoring dashboards] diff --git a/monitoring/managing-metrics.adoc b/monitoring/managing-metrics.adoc deleted file mode 100644 index 7a18bfcef300..000000000000 --- a/monitoring/managing-metrics.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="managing-metrics"] -= Managing metrics -include::modules/common-attributes.adoc[] -:context: managing-metrics - -toc::[] - -// Understanding metrics -include::modules/monitoring-understanding-metrics.adoc[leveloffset=+1] - -// Setting up metrics collection for user-defined projects -include::modules/monitoring-setting-up-metrics-collection-for-user-defined-projects.adoc[leveloffset=+1] -include::modules/monitoring-deploying-a-sample-service.adoc[leveloffset=+2] -include::modules/monitoring-specifying-how-a-service-is-monitored.adoc[leveloffset=+2] - -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects] - -// Querying metrics -include::modules/monitoring-querying-metrics.adoc[leveloffset=+1] -//include::modules/monitoring-contents-of-the-metrics-ui.adoc[leveloffset=+2] -include::modules/monitoring-querying-metrics-for-all-projects-as-an-administrator.adoc[leveloffset=+2] -include::modules/monitoring-querying-metrics-for-user-defined-projects-as-a-developer.adoc[leveloffset=+2] - -.Additional resources - -* See the xref:../monitoring/managing-metrics.adoc#querying-metrics-for-user-defined-projects-as-a-developer_managing-metrics[Querying metrics for user-defined projects as a developer] for details on accessing non-cluster metrics as a developer or a privileged user - -include::modules/monitoring-exploring-the-visualized-metrics.adoc[leveloffset=+2] - -.Additional resources - -* See the xref:../monitoring/managing-metrics.adoc#querying-metrics_managing-metrics[Querying metrics] section on using the PromQL interface - -== Next steps - -* xref:../monitoring/managing-alerts.adoc#managing-alerts[Managing alerts] diff --git a/monitoring/reviewing-monitoring-dashboards.adoc b/monitoring/reviewing-monitoring-dashboards.adoc deleted file mode 100644 index a44ed34e7df7..000000000000 --- a/monitoring/reviewing-monitoring-dashboards.adoc +++ /dev/null @@ -1,49 +0,0 @@ -[id="reviewing-monitoring-dashboards"] -= Reviewing monitoring dashboards -include::modules/common-attributes.adoc[] -:context: reviewing-monitoring-dashboards - -toc::[] - -{product-title} {product-version} provides a comprehensive set of monitoring dashboards that help you understand the state of cluster components and user-defined workloads. - -In the *Administrator* perspective you can access dashboards for core {product-title} components, including: - -* API performance -* etcd -* Kubernetes compute resources -* Kubernetes network resources -* Prometheus -* USE method dashboards relating to cluster and node performance - -.Example dashboard in the Administrator perspective -image::monitoring-dashboard-administrator.png[] - -In the *Developer* perspective you can access dashboards that provide the following statistics for a selected project: - -* CPU usage -* Memory usage -* Bandwidth information -* Packet rate information - -.Example dashboard in the Developer perspective -image::monitoring-dashboard-developer.png[] - -[NOTE] -==== -In the *Developer* perspective, you can view dashboards for only one project at a time. -==== - -// Reviewing monitoring dashboards as a cluster administrator -include::modules/monitoring-reviewing-monitoring-dashboards-admin.adoc[leveloffset=+1] - -// Reviewing monitoring dashboards as a developer -include::modules/monitoring-reviewing-monitoring-dashboards-developer.adoc[leveloffset=+1] - -.Additional resources - -* xref:../applications/odc-monitoring-project-and-application-metrics-using-developer-perspective.adoc#monitoring-project-and-application-metrics-using-developer-perspective[Monitoring project and application metrics using the Developer perspective] - -== Next steps - -* xref:../monitoring/accessing-third-party-uis.adoc#accessing-third-party-uis[Accessing third-party UIs] diff --git a/monitoring/troubleshooting-monitoring-issues.adoc b/monitoring/troubleshooting-monitoring-issues.adoc deleted file mode 100644 index a4cc7b6766d7..000000000000 --- a/monitoring/troubleshooting-monitoring-issues.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="troubleshooting-monitoring-issues"] -= Troubleshooting monitoring issues -include::modules/common-attributes.adoc[] -:context: troubleshooting-monitoring-issues - -toc::[] - -// Investigating why user-defined metrics are unavailable -include::modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc[leveloffset=+1] - -.Additional resources - -* xref:../monitoring/configuring-the-monitoring-stack.adoc#creating-user-defined-workload-monitoring-configmap_configuring-the-monitoring-stack[Creating a user-defined workload monitoring config map] -* See xref:../monitoring/managing-metrics.adoc#specifying-how-a-service-is-monitored_managing-metrics[Specifying how a service is monitored] for details on how to create a `ServiceMonitor` or `PodMonitor` resource - -// Determining why Prometheus is consuming a lot of disk space -include::modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../monitoring/configuring-the-monitoring-stack.adoc#setting-a-scrape-sample-limit-for-user-defined-projects_configuring-the-monitoring-stack[Setting a scrape sample limit for user-defined projects] for details on how to set a scrape sample limit and create related alerting rules -* xref:../support/getting-support.html#support-submitting-a-case_getting-support[Submitting a support case] diff --git a/monitoring/understanding-the-monitoring-stack.adoc b/monitoring/understanding-the-monitoring-stack.adoc deleted file mode 100644 index 4e094ccab465..000000000000 --- a/monitoring/understanding-the-monitoring-stack.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="understanding-the-monitoring-stack"] -= Understanding the monitoring stack -include::modules/common-attributes.adoc[] -:context: understanding-the-monitoring-stack - -toc::[] - -// About cluster monitoring (the title is only shown in virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc) -include::modules/monitoring-about-cluster-monitoring.adoc[leveloffset=+1] - -// Understanding the monitoring stack -include::modules/monitoring-understanding-the-monitoring-stack.adoc[leveloffset=+1] -include::modules/monitoring-default-monitoring-components.adoc[leveloffset=+2] -include::modules/monitoring-default-monitoring-targets.adoc[leveloffset=+2] -include::modules/monitoring-components-for-monitoring-user-defined-projects.adoc[leveloffset=+2] -include::modules/monitoring-targets-for-user-defined-projects.adoc[leveloffset=+2] - -== Additional resources - -* xref:../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring[About remote health monitoring] -* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#granting-users-permission-to-monitor-user-defined-projects_enabling-monitoring-for-user-defined-projects[Granting users permission to monitor user-defined projects] - -== Next steps - -* xref:../monitoring/configuring-the-monitoring-stack.adoc#configuring-the-monitoring-stack[Configuring the monitoring stack] diff --git a/networking/accessing-hosts.adoc b/networking/accessing-hosts.adoc deleted file mode 100644 index e61998c6c8c5..000000000000 --- a/networking/accessing-hosts.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="accessing-hosts"] -= Accessing hosts -include::modules/common-attributes.adoc[] -:context: accessing-hosts - -toc::[] - -Learn how to create a bastion host to access {product-title} instances and -access the master nodes with secure shell (SSH) access. - -include::modules/accessing-hosts-on-aws.adoc[leveloffset=+1] diff --git a/networking/associating-secondary-interfaces-metrics-to-network-attachments.adoc b/networking/associating-secondary-interfaces-metrics-to-network-attachments.adoc deleted file mode 100644 index f9cfa9c86502..000000000000 --- a/networking/associating-secondary-interfaces-metrics-to-network-attachments.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="associating-secondary-interfaces-metrics-to-network-attachments"] -= Associating secondary interfaces metrics to network attachments -include::modules/common-attributes.adoc[] -:context: secondary-interfaces-metrics - -toc::[] - -include::modules/cnf-associating-secondary-interfaces-metrics-to-network-attachments.adoc[leveloffset=+1] diff --git a/networking/cluster-network-operator.adoc b/networking/cluster-network-operator.adoc deleted file mode 100644 index 0fedd6cc05cc..000000000000 --- a/networking/cluster-network-operator.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="cluster-network-operator"] -= Cluster Network Operator in {product-title} -include::modules/common-attributes.adoc[] -:context: cluster-network-operator - -toc::[] - -The Cluster Network Operator (CNO) deploys and manages the cluster network components on an {product-title} cluster, including the Container Network Interface (CNI) default network provider plug-in selected for the cluster during installation. - -include::modules/nw-cluster-network-operator.adoc[leveloffset=+1] - -include::modules/nw-cno-view.adoc[leveloffset=+1] - -include::modules/nw-cno-status.adoc[leveloffset=+1] - -include::modules/nw-cno-logs.adoc[leveloffset=+1] - -include::modules/nw-operator-cr.adoc[leveloffset=+1] diff --git a/networking/configuring-a-custom-pki.adoc b/networking/configuring-a-custom-pki.adoc deleted file mode 100644 index 3c07d2bbee78..000000000000 --- a/networking/configuring-a-custom-pki.adoc +++ /dev/null @@ -1,47 +0,0 @@ -[id="configuring-a-custom-pki"] -= Configuring a custom PKI -include::modules/common-attributes.adoc[] -:context: configuring-a-custom-pki - -toc::[] - -Some platform components, such as the web console, use Routes for communication and -must trust other components' certificates to interact with them. If -you are using a custom public key infrastructure (PKI), you must configure it so -its privately signed CA certificates are recognized across the cluster. - -You can leverage the Proxy API to add cluster-wide trusted CA certificates. You -must do this either during installation or at runtime. - -* During _installation_, xref:installation-configure-proxy_{context}[configure the cluster-wide proxy]. You must define your -privately signed CA certificates in the `install-config.yaml` file's -`additionalTrustBundle` setting. -+ -The installation program generates a ConfigMap that is named `user-ca-bundle` -that contains the additional CA certificates you defined. The Cluster Network -Operator then creates a `trusted-ca-bundle` ConfigMap that merges these CA -certificates with the {op-system-first} trust bundle; this ConfigMap is -referenced in the Proxy object's `trustedCA` field. - -* At _runtime_, xref:nw-proxy-configure-object_{context}[modify the default Proxy object to include your privately signed -CA certificates] (part of cluster's proxy enablement workflow). This involves -creating a ConfigMap that contains the privately signed CA certificates that -should be trusted by the cluster, and then modifying the proxy resource with the -`trustedCA` referencing the privately signed certificates' ConfigMap. - -[NOTE] -==== -The installer configuration's `additionalTrustBundle` field and the proxy -resource's `trustedCA` field are used to manage the cluster-wide trust bundle; -`additionalTrustBundle` is used at install time and the proxy's `trustedCA` is -used at runtime. - -The `trustedCA` field is a reference to a `ConfigMap` containing the custom -certificate and key pair used by the cluster component. -==== - -include::modules/installation-configure-proxy.adoc[leveloffset=+1] - -include::modules/nw-proxy-configure-object.adoc[leveloffset=+1] - -include::modules/certificate-injection-using-operators.adoc[leveloffset=+1] diff --git a/networking/configuring-node-port-service-range.adoc b/networking/configuring-node-port-service-range.adoc deleted file mode 100644 index a252015a8bed..000000000000 --- a/networking/configuring-node-port-service-range.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="configuring-node-port-service-range"] -= Configuring the node port service range -include::modules/common-attributes.adoc[] -:context: configuring-node-port-service-range - -toc::[] - -As a cluster administrator, you can expand the available node port range. If your cluster uses of a large number of node ports, you might need to increase the number of available ports. - -The default port range is `30000-32767`. You can never reduce the port range, even if you first expand it beyond the default range. - -[id="configuring-node-port-service-range-prerequisites"] -== Prerequisites - -- Your cluster infrastructure must allow access to the ports that you specify within the expanded range. For example, if you expand the node port range to `30000-32900`, the inclusive port range of `32768-32900` must be allowed by your firewall or packet filtering configuration. - -include::modules/nw-nodeport-service-range-edit.adoc[leveloffset=+1] - -[id="configuring-node-port-service-range-additional-resources"] -== Additional resources - -* xref:../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc#configuring-ingress-cluster-traffic-nodeport[Configuring ingress cluster traffic using a NodePort] -* xref:../rest_api/config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[Network [config.openshift.io/v1]] -* xref:../rest_api/network_apis/service-core-v1.adoc#service-core-v1[Service [core/v1]] diff --git a/networking/configuring-ptp.adoc b/networking/configuring-ptp.adoc deleted file mode 100644 index bef2caaa1b49..000000000000 --- a/networking/configuring-ptp.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="configuring-ptp"] -= Configuring PTP hardware -include::modules/common-attributes.adoc[] -:context: configuring-ptp - -toc::[] - -:FeatureName: Precision Time Protocol (PTP) hardware -include::modules/technology-preview.adoc[leveloffset=+1] - -[id="about-using-ptp-hardware"] -== About PTP hardware - -{product-title} includes the capability to use Precision Time Protocol (PTP)hardware on your nodes. -You can configure linuxptp services on nodes in your cluster that have PTP-capable hardware. - -[NOTE] -==== -The PTP Operator works with PTP-capable devices on clusters provisioned only on bare metal infrastructure. -==== - -You can use the {product-title} console to install PTP by deploying the PTP Operator. The PTP Operator creates and manages the linuxptp services. The Operator provides the following features: - -* Discovery of the PTP-capable devices in a cluster. -* Management of the configuration of linuxptp services. - -include::modules/nw-ptp-device-discovery.adoc[leveloffset=+1] -include::modules/nw-ptp-installing-operator.adoc[leveloffset=+1] -include::modules/nw-ptp-configuring-linuxptp.adoc[leveloffset=+1] diff --git a/networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc b/networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc deleted file mode 100644 index 6abfc20da1dd..000000000000 --- a/networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="configuring-externalip"] -= Configuring ExternalIPs for services -include::modules/common-attributes.adoc[] -:context: configuring-externalip - -toc::[] - -As a cluster administrator, you can designate an IP address block that is external to the cluster that can send traffic to services in the cluster. - -This functionality is generally most useful for clusters installed on bare-metal hardware. - -== Prerequisites - -* Your network infrastructure must route traffic for the external IP addresses to your cluster. - -include::modules/nw-externalip-about.adoc[leveloffset=+1] - -include::modules/nw-externalip-object.adoc[leveloffset=+1] - -include::modules/nw-externalip-configuring.adoc[leveloffset=+1] - -[id="configuring-externalip-next-steps"] -== Next steps - -* xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc#configuring-ingress-cluster-traffic-service-external-ip[Configuring ingress cluster traffic for a service external IP] diff --git a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws-network-load-balancer.adoc b/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws-network-load-balancer.adoc deleted file mode 100644 index d01579f6c6a6..000000000000 --- a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-aws-network-load-balancer.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="configuring-ingress-cluster-traffic-aws-network-load-balancer"] -= Configuring ingress cluster traffic on AWS using a Network Load Balancer -include::modules/common-attributes.adoc[] -:context: configuring-ingress-cluster-traffic-aws-network-load-balancer - -toc::[] - -{product-title} provides methods for communicating from outside the cluster with services running in the cluster. This method uses a Network Load Balancer (NLB), which forwards the client's IP address to the node. You can configure an NLB on a new or existing AWS cluster. - -include::modules/nw-aws-nlb-existing-cluster.adoc[leveloffset=+1] - -[IMPORTANT] -==== -Before you can configure an Ingress Controller NLB on a new AWS cluster, you must complete the xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#installation-initializing_installing-aws-network-customizations[Creating the installation configuration file] procedure. -==== - -include::modules/nw-aws-nlb-new-cluster.adoc[leveloffset=+1] - -[id="configuring-ingress-cluster-traffic-aws-network-load-balancer-addtl-resources"] -== Additional resources - -* xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[Installing a cluster on AWS with network customizations]. -* For more information, see link:https://kubernetes.io/docs/concepts/services-networking/service/#aws-nlb-support[Network Load Balancer support on AWS]. diff --git a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc b/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc deleted file mode 100644 index 24fc79601d82..000000000000 --- a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc +++ /dev/null @@ -1,59 +0,0 @@ -[id="configuring-ingress-cluster-traffic-ingress-controller"] -= Configuring ingress cluster traffic using an Ingress Controller -include::modules/common-attributes.adoc[] -:context: configuring-ingress-cluster-traffic-ingress-controller - -toc::[] - - -{product-title} provides methods for communicating from outside the cluster with -services running in the cluster. This method uses an Ingress Controller. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/nw-using-ingress-and-routes.adoc[leveloffset=+1] - -[NOTE] -==== -The procedures in this section require prerequisites performed by the cluster -administrator. -==== - -== Prerequisites - -Before starting the following procedures, the administrator must: - -* Set up the external port to the cluster networking environment so that requests -can reach the cluster. - -* Make sure there is at least one user with cluster admin role. To add this role -to a user, run the following command: -+ ----- -$ oc adm policy add-cluster-role-to-user cluster-admin username ----- - -* Have an {product-title} cluster with at least one master and at least one node -and a system outside the cluster that has network access to the cluster. This -procedure assumes that the external system is on the same subnet as the cluster. -The additional networking required for external systems on a different subnet is -out-of-scope for this topic. -endif::[] - -include::modules/nw-creating-project-and-service.adoc[leveloffset=+1] - -include::modules/nw-exposing-service.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/nw-ingress-sharding-route-labels.adoc[leveloffset=+1] - -include::modules/nw-ingress-sharding-namespace-labels.adoc[leveloffset=+1] - -== Additional resources - -* The Ingress Operator manages wildcard DNS. For more information, see -xref:../../networking/ingress-operator.adoc#configuring-ingress[Ingress Operator -in {product-title}], -xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Installing -a cluster on bare metal], and -xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Installing a cluster on vSphere]. -endif::[] diff --git a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-load-balancer.adoc b/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-load-balancer.adoc deleted file mode 100644 index e92a81618ae4..000000000000 --- a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-load-balancer.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id="configuring-ingress-cluster-traffic-load-balancer"] -= Configuring ingress cluster traffic using a load balancer -include::modules/common-attributes.adoc[] -:context: configuring-ingress-cluster-traffic-load-balancer - -toc::[] - -{product-title} provides methods for communicating from -outside the cluster with services running in the cluster. This method uses a -load balancer. - -include::modules/nw-using-load-balancer-getting-traffic.adoc[leveloffset=+1] - -[NOTE] -==== -The procedures in this section require prerequisites performed by the cluster -administrator. -==== - -== Prerequisites - -Before starting the following procedures, the administrator must: - -* Set up the external port to the cluster networking environment so that requests -can reach the cluster. - -* Make sure there is at least one user with cluster admin role. To add this role -to a user, run the following command: -+ ----- -$ oc adm policy add-cluster-role-to-user cluster-admin username ----- - -* Have an {product-title} cluster with at least one master and at least one node -and a system outside the cluster that has network access to the cluster. This -procedure assumes that the external system is on the same subnet as the cluster. -The additional networking required for external systems on a different subnet is -out-of-scope for this topic. - -include::modules/nw-creating-project-and-service.adoc[leveloffset=+1] - -include::modules/nw-exposing-service.adoc[leveloffset=+1] - -include::modules/nw-create-load-balancer-service.adoc[leveloffset=+1] diff --git a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc b/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc deleted file mode 100644 index 6df7c7c8b527..000000000000 --- a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc +++ /dev/null @@ -1,48 +0,0 @@ -[id="configuring-ingress-cluster-traffic-nodeport"] -= Configuring ingress cluster traffic using a NodePort -include::modules/common-attributes.adoc[] -:context: configuring-ingress-cluster-traffic-nodeport - -toc::[] - -{product-title} provides methods for communicating from -outside the cluster with services running in the cluster. This method uses a -`NodePort`. - -include::modules/nw-using-nodeport.adoc[leveloffset=+1] - -[NOTE] -==== -The procedures in this section require prerequisites performed by the cluster -administrator. -==== - -== Prerequisites - -Before starting the following procedures, the administrator must: - -* Set up the external port to the cluster networking environment so that requests -can reach the cluster. - -* Make sure there is at least one user with cluster admin role. To add this role -to a user, run the following command: -+ ----- -$ oc adm policy add-cluster-role-to-user cluster-admin <user_name> ----- - -* Have an {product-title} cluster with at least one master and at least one node -and a system outside the cluster that has network access to the cluster. This -procedure assumes that the external system is on the same subnet as the cluster. -The additional networking required for external systems on a different subnet is -out-of-scope for this topic. - -include::modules/nw-creating-project-and-service.adoc[leveloffset=+1] - -include::modules/nw-exposing-service.adoc[leveloffset=+1] - - -[id="configuring-ingress-cluster-traffic-nodeport-additional-resources"] -== Additional resources - -* xref:../../networking/configuring-node-port-service-range.adoc#configuring-node-port-service-range[Configuring the node port service range] diff --git a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc b/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc deleted file mode 100644 index dc5ebadb6db5..000000000000 --- a/networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="configuring-ingress-cluster-traffic-service-external-ip"] -= Configuring ingress cluster traffic for a service external IP -include::modules/common-attributes.adoc[] -:context: configuring-ingress-cluster-traffic-service-external-ip - -toc::[] - -You can attach an external IP address to a service so that it is available to traffic outside the cluster. -This is generally useful only for a cluster installed on bare metal hardware. -The external network infrastructure must be configured correctly to route traffic to the service. - -[id="configuring-ingress-cluster-traffic-service-external-ip-prerequisites"] -== Prerequisites - -* Your cluster is configured with ExternalIPs enabled. For more information, read xref:../../networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc#configuring-externalip[Configuring ExternalIPs for services]. - -include::modules/nw-service-externalip-create.adoc[leveloffset=+1] - -[id="configuring-ingress-cluster-traffic-service-external-ip-additional-resources"] -== Additional resources - -* xref:../../networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc#configuring-externalip[Configuring ExternalIPs for services] diff --git a/networking/configuring_ingress_cluster_traffic/overview-traffic.adoc b/networking/configuring_ingress_cluster_traffic/overview-traffic.adoc deleted file mode 100644 index a332ed28eb04..000000000000 --- a/networking/configuring_ingress_cluster_traffic/overview-traffic.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="overview-traffic"] -= Configuring ingress cluster traffic overview -include::modules/common-attributes.adoc[] -:context: overview-traffic - -toc::[] - -{product-title} provides the following methods for communicating from -outside the cluster with services running in the cluster. - -The methods are recommended, in order or preference: - -* If you have HTTP/HTTPS, use an Ingress Controller. -* If you have a TLS-encrypted protocol other than HTTPS. For example, for TLS -with the SNI header, use an Ingress Controller. -* Otherwise, use a Load Balancer, an External IP, or a `NodePort`. - -[[external-access-options-table]] -[options="header"] -|=== - -|Method |Purpose - -|xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc#configuring-ingress-cluster-traffic-ingress-controller[Use an Ingress Controller] -|Allows access to HTTP/HTTPS traffic and TLS-encrypted protocols other than HTTPS (for example, TLS with the SNI header). - -|xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-load-balancer.adoc#configuring-ingress-cluster-traffic-load-balancer[Automatically assign an external IP using a load balancer service] -|Allows traffic to non-standard ports through an IP address assigned from a pool. - -|xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc#configuring-ingress-cluster-traffic-service-external-ip[Manually assign an external IP to a service] -|Allows traffic to non-standard ports through a specific IP address. - -|xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc#configuring-ingress-cluster-traffic-nodeport[Configure a `NodePort`] -|Expose a service on all nodes in the cluster. -|=== diff --git a/networking/dns-operator.adoc b/networking/dns-operator.adoc deleted file mode 100644 index f95e78594d68..000000000000 --- a/networking/dns-operator.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="dns-operator"] -= DNS Operator in {product-title} -include::modules/common-attributes.adoc[] -:context: dns-operator - -toc::[] - -The DNS Operator deploys and manages CoreDNS to provide a name resolution -service to pods, enabling DNS-based Kubernetes Service discovery in -OpenShift. - -include::modules/nw-dns-operator.adoc[leveloffset=+1] - -include::modules/nw-dns-view.adoc[leveloffset=+1] - -include::modules/nw-dns-forward.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/nw-dns-operator-status.adoc[leveloffset=+1] - -include::modules/nw-dns-operator-logs.adoc[leveloffset=+1] -endif::[] diff --git a/networking/enable-cluster-wide-proxy.adoc b/networking/enable-cluster-wide-proxy.adoc deleted file mode 100644 index 117e4077330c..000000000000 --- a/networking/enable-cluster-wide-proxy.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="enable-cluster-wide-proxy"] -= Configuring the cluster-wide proxy -include::modules/common-attributes.adoc[] -:context: config-cluster-wide-proxy - -toc::[] - -Production environments can deny direct access to the Internet and instead have an HTTP or HTTPS proxy available. You can configure {product-title} to use a proxy by xref:../networking/enable-cluster-wide-proxy.adoc#nw-proxy-configure-object_config-cluster-wide-proxy[modifying the Proxy object for existing clusters] or by configuring the proxy settings in the `install-config.yaml` file for new clusters. - -[IMPORTANT] -==== -The cluster-wide proxy is only supported if you used a user-provisioned infrastructure installation or provide your own networking, such as a virtual private cloud or virual network, for a supported provider. -==== - -== Prerequisites - -* Review the xref:../installing/install_config/configuring-firewall.adoc#configuring-firewall[sites that your cluster requires access to] and determine whether any of them must bypass the proxy. By default, all cluster system egress traffic is proxied, including calls to the cloud provider API for the cloud that hosts your cluster. System-wide proxy affects system components only, not user workloads. Add sites to the Proxy object's `spec.noProxy` field to bypass the proxy if necessary. -+ -[NOTE] -==== -The Proxy object `status.noProxy` field is populated with the values of the `networking.machineNetwork[].cidr`, `networking.clusterNetwork[].cidr`, and `networking.serviceNetwork[]` fields from your installation configuration. - -For installations on Amazon Web Services (AWS), Google Cloud Platform (GCP), Microsoft Azure, and {rh-openstack-first}, the `Proxy` object `status.noProxy` field is also populated with the instance metadata endpoint (`169.254.169.254`). -==== - -include::modules/nw-proxy-configure-object.adoc[leveloffset=+1] - -include::modules/nw-proxy-remove.adoc[leveloffset=+1] diff --git a/networking/hardware_networks/about-sriov.adoc b/networking/hardware_networks/about-sriov.adoc deleted file mode 100644 index fcb17d493bb1..000000000000 --- a/networking/hardware_networks/about-sriov.adoc +++ /dev/null @@ -1,69 +0,0 @@ -[id="about-sriov"] -= About Single Root I/O Virtualization (SR-IOV) hardware networks -include::modules/common-attributes.adoc[] -:context: about-sriov - -toc::[] - -The Single Root I/O Virtualization (SR-IOV) specification is a standard for a type of PCI device assignment that can share a single device with multiple pods. - -SR-IOV enables you to segment a compliant network device, recognized on the host node as a physical function (PF), into multiple virtual functions (VFs). -The VF is used like any other network device. -The SR-IOV device driver for the device determines how the VF is exposed in the container: - -* `netdevice` driver: A regular kernel network device in the `netns` of the container -* `vfio-pci` driver: A character device mounted in the container - -You can use SR-IOV network devices with additional networks on your {product-title} cluster for application that require high bandwidth or low latency. - -[id="components-sr-iov-network-devices"] -== Components that manage SR-IOV network devices - -The SR-IOV Network Operator creates and manages the components of the SR-IOV stack. -It performs the following functions: - -- Orchestrates discovery and management of SR-IOV network devices -- Generates `NetworkAttachmentDefinition` custom resources for the SR-IOV Container Network Interface (CNI) -- Creates and updates the configuration of the SR-IOV network device plug-in -- Creates node specific `SriovNetworkNodeState` custom resources -- Updates the `spec.interfaces` field in each `SriovNetworkNodeState` custom resource - -The Operator provisions the following components: - -SR-IOV network configuration daemon:: -A DaemonSet that is deployed on worker nodes when the SR-IOV Operator starts. The daemon is responsible for discovering and initializing SR-IOV network devices in the cluster. - -SR-IOV Operator webhook:: -A dynamic admission controller webhook that validates the Operator custom resource and sets appropriate default values for unset fields. - -SR-IOV Network resources injector:: -A dynamic admission controller webhook that provides functionality for patching Kubernetes pod specifications with requests and limits for custom network resources such as SR-IOV VFs. - -SR-IOV network device plug-in:: -A device plug-in that discovers, advertises, and allocates SR-IOV network virtual function (VF) resources. Device plug-ins are used in Kubernetes to enable the use of limited resources, typically in physical devices. Device plug-ins give the Kubernetes scheduler awareness of resource availability, so that the scheduler can schedule pods on nodes with sufficient resources. - -SR-IOV CNI plug-in:: -A CNI plug-in that attaches VF interfaces allocated from the SR-IOV device plug-in directly into a pod. - -SR-IOV InfiniBand CNI plug-in:: -A CNI plug-in that attaches InfiniBand (IB) VF interfaces allocated from the SR-IOV device plug-in directly into a pod. - -[NOTE] -==== -The SR-IOV Network resources injector and SR-IOV Network Operator webhook are enabled by default and can be disabled by editing the `default` `SriovOperatorConfig` CR. -==== - -include::modules/nw-sriov-supported-devices.adoc[leveloffset=+2] -include::modules/nw-sriov-device-discovery.adoc[leveloffset=+2] -include::modules/nw-sriov-example-vf-function-in-pod.adoc[leveloffset=+2] -include::modules/nw-sriov-app-netutil.adoc[leveloffset=+2] - -[id="about-sriov-next-steps"] -== Next steps - -* xref:../../networking/hardware_networks/installing-sriov-operator.adoc#installing-sriov-operator[Installing the SR-IOV Network Operator] -* Optional: xref:../../networking/hardware_networks/configuring-sriov-operator.adoc#configuring-sriov-operator[Configuring the SR-IOV Network Operator] -* xref:../../networking/hardware_networks/configuring-sriov-device.adoc#configuring-sriov-device[Configuring an SR-IOV network device] -* If you use OpenShift Virtualization: xref:../../virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc#virt-configuring-sriov-device-for-vms[Configuring an SR-IOV network device for virtual machines] -* xref:../../networking/hardware_networks/configuring-sriov-net-attach.adoc#configuring-sriov-net-attach[Configuring an SR-IOV network attachment] -* xref:../../networking/hardware_networks/add-pod.adoc#add-pod[Adding a pod to an SR-IOV additional network] diff --git a/networking/hardware_networks/add-pod.adoc b/networking/hardware_networks/add-pod.adoc deleted file mode 100644 index 6907f149b423..000000000000 --- a/networking/hardware_networks/add-pod.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="add-pod"] -= Adding a pod to an SR-IOV additional network -include::modules/common-attributes.adoc[] -:context: configuring-sr-iov - -toc::[] - -You can add a pod to an existing Single Root I/O Virtualization (SR-IOV) network. - -include::modules/nw-sriov-runtime-config.adoc[leveloffset=+1] - -include::modules/nw-multus-add-pod.adoc[leveloffset=+1] - -include::modules/nw-sriov-topology-manager.adoc[leveloffset=+1] - -[id="add-pod-additional-resources"] -== Additional resources - -- xref:../../networking/hardware_networks/configuring-sriov-device.adoc#configuring-sriov-device[Configuring an SR-IOV Ethernet network attachment] -- xref:../../networking/hardware_networks/configuring-sriov-ib-attach.adoc#configuring-sriov-ib-attach[Configuring an SR-IOV InfiniBand network attachment] diff --git a/networking/hardware_networks/configuring-sriov-device.adoc b/networking/hardware_networks/configuring-sriov-device.adoc deleted file mode 100644 index ecb94a7d4748..000000000000 --- a/networking/hardware_networks/configuring-sriov-device.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="configuring-sriov-device"] -= Configuring an SR-IOV network device -include::modules/common-attributes.adoc[] -:context: configuring-sriov-device - -toc::[] - -You can configure a Single Root I/O Virtualization (SR-IOV) device in your cluster. - -include::modules/nw-sriov-networknodepolicy-object.adoc[leveloffset=+1] -// A direct companion to nw-sriov-networknodepolicy-object -include::modules/nw-sriov-nic-partitioning.adoc[leveloffset=+2] -include::modules/nw-sriov-configuring-device.adoc[leveloffset=+1] -:FeatureName: CNI VRF plug-in -include::modules/technology-preview.adoc[leveloffset=+1] -include::modules/cnf-assigning-a-sriov-network-to-a-vrf.adoc[leveloffset=+1] - -[id="configuring-sriov-device-next-steps"] -== Next steps - -* xref:../../networking/hardware_networks/configuring-sriov-net-attach.adoc#configuring-sriov-net-attach[Configuring an SR-IOV network attachment] diff --git a/networking/hardware_networks/configuring-sriov-ib-attach.adoc b/networking/hardware_networks/configuring-sriov-ib-attach.adoc deleted file mode 100644 index 376b07d0ed09..000000000000 --- a/networking/hardware_networks/configuring-sriov-ib-attach.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="configuring-sriov-ib-attach"] -= Configuring an SR-IOV InfiniBand network attachment -include::modules/common-attributes.adoc[] -:context: configuring-sriov-ib-attach - -toc::[] - -You can configure an InfiniBand (IB) network attachment for an Single Root I/O Virtualization (SR-IOV) device in the cluster. - -include::modules/nw-sriov-ibnetwork-object.adoc[leveloffset=+1] -include::modules/nw-multus-ipam-object.adoc[leveloffset=+2] -include::modules/nw-sriov-network-attachment.adoc[leveloffset=+1] - -[id="configuring-sriov-ib-attach-next-steps"] -== Next steps - -* xref:../../networking/hardware_networks/add-pod.adoc#add-pod[Adding a pod to an SR-IOV additional network] - -[id="configuring-sriov-ib-attach-additional-resources"] -== Additional resources - - * xref:../../networking/hardware_networks/configuring-sriov-device.adoc#configuring-sriov-device[Configuring an SR-IOV network device] diff --git a/networking/hardware_networks/configuring-sriov-net-attach.adoc b/networking/hardware_networks/configuring-sriov-net-attach.adoc deleted file mode 100644 index 29122fcc405a..000000000000 --- a/networking/hardware_networks/configuring-sriov-net-attach.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="configuring-sriov-net-attach"] -= Configuring an SR-IOV Ethernet network attachment -include::modules/common-attributes.adoc[] -:context: configuring-sriov-net-attach - -toc::[] - -You can configure an Ethernet network attachment for an Single Root I/O Virtualization (SR-IOV) device in the cluster. - -include::modules/nw-sriov-network-object.adoc[leveloffset=+1] -include::modules/nw-multus-ipam-object.adoc[leveloffset=+2] -include::modules/nw-sriov-network-attachment.adoc[leveloffset=+1] - -[id="configuring-sriov-net-attach-next-steps"] -== Next steps - -* xref:../../networking/hardware_networks/add-pod.adoc#add-pod[Adding a pod to an SR-IOV additional network] - -[id="configuring-sriov-net-attach-additional-resources"] -== Additional resources - - * xref:../../networking/hardware_networks/configuring-sriov-device.adoc#configuring-sriov-device[Configuring an SR-IOV network device] diff --git a/networking/hardware_networks/configuring-sriov-operator.adoc b/networking/hardware_networks/configuring-sriov-operator.adoc deleted file mode 100644 index ff5dd82aaa0a..000000000000 --- a/networking/hardware_networks/configuring-sriov-operator.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="configuring-sriov-operator"] -= Configuring the SR-IOV Network Operator -include::modules/common-attributes.adoc[] -:context: configuring-sriov-operator - -toc::[] - -The Single Root I/O Virtualization (SR-IOV) Network Operator manages the SR-IOV network devices and network attachments in your cluster. - -include::modules/nw-sriov-configuring-operator.adoc[leveloffset=+1] - -[id="configuring-sriov-operator-next-steps"] -== Next steps - -* xref:../../networking/hardware_networks/configuring-sriov-device.adoc#configuring-sriov-device[Configuring an SR-IOV network device] diff --git a/networking/hardware_networks/installing-sriov-operator.adoc b/networking/hardware_networks/installing-sriov-operator.adoc deleted file mode 100644 index 0523b5baec8f..000000000000 --- a/networking/hardware_networks/installing-sriov-operator.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="installing-sriov-operator"] -= Installing the SR-IOV Network Operator -include::modules/common-attributes.adoc[] -:context: installing-sriov-operator - -toc::[] - -You can install the Single Root I/O Virtualization (SR-IOV) Network Operator on your cluster to manage SR-IOV network devices and network attachments. - -include::modules/nw-sriov-installing-operator.adoc[leveloffset=+1] - -[id="installing-sriov-operator-next-steps"] -== Next steps - -* Optional: xref:../../networking/hardware_networks/configuring-sriov-operator.adoc#configuring-sriov-operator[Configuring the SR-IOV Network Operator] diff --git a/networking/hardware_networks/using-dpdk-and-rdma.adoc b/networking/hardware_networks/using-dpdk-and-rdma.adoc deleted file mode 100644 index 159c5f969ff8..000000000000 --- a/networking/hardware_networks/using-dpdk-and-rdma.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="using-dpdk-and-rdma"] -= Using virtual functions (VFs) with DPDK and RDMA modes -include::modules/common-attributes.adoc[] -:context: using-dpdk-and-rdma - -toc::[] - -You can use Single Root I/O Virtualization (SR-IOV) network hardware with the Data Plane Development Kit (DPDK) and with remote direct memory access (RDMA). - -:FeatureName: The Data Plane Development Kit (DPDK) -include::modules/technology-preview.adoc[leveloffset=+0] - -include::modules/nw-sriov-dpdk-example-intel.adoc[leveloffset=+1] - -include::modules/nw-sriov-dpdk-example-mellanox.adoc[leveloffset=+1] - -include::modules/nw-sriov-rdma-example-mellanox.adoc[leveloffset=+1] - -:!FeatureName: diff --git a/networking/hardware_networks/using-sriov-multicast.adoc b/networking/hardware_networks/using-sriov-multicast.adoc deleted file mode 100644 index ca1336dfdfcc..000000000000 --- a/networking/hardware_networks/using-sriov-multicast.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="using-sriov-multicast"] -= Using high performance multicast -include::modules/common-attributes.adoc[] -:context: using-sriov-multicast - -toc::[] - -You can use multicast on your Single Root I/O Virtualization (SR-IOV) hardware network. - -include::modules/nw-configuring-high-performance-multicast-with-sriov.adoc[leveloffset=+1] diff --git a/networking/images b/networking/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/networking/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/networking/ingress-operator.adoc b/networking/ingress-operator.adoc deleted file mode 100644 index 1377ccb88467..000000000000 --- a/networking/ingress-operator.adoc +++ /dev/null @@ -1,65 +0,0 @@ -[id="configuring-ingress"] -= Ingress Operator in {product-title} -include::modules/common-attributes.adoc[] -:context: configuring-ingress - -toc::[] - -The Ingress Operator implements the `ingresscontroller` API and is the -component responsible for enabling external access to {product-title} -cluster services. The Operator makes this possible by deploying and -managing one or more HAProxy-based -link:https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/[Ingress Controllers] -to handle routing. You can use the Ingress Operator to route traffic by -specifying {product-title} `Route` and Kubernetes `Ingress` resources. - -include::modules/nw-installation-ingress-config-asset.adoc[leveloffset=+1] - -include::modules/nw-ingress-controller-configuration-parameters.adoc[leveloffset=+1] - -include::modules/nw-ingress-controller-tls-profiles.adoc[leveloffset=+2] - -include::modules/nw-ingress-controller-endpoint-publishing-strategies.adoc[leveloffset=+2] - -include::modules/nw-ingress-view.adoc[leveloffset=+1] - -include::modules/nw-ingress-operator-status.adoc[leveloffset=+1] - -include::modules/nw-ingress-operator-logs.adoc[leveloffset=+1] - -include::modules/nw-ingress-controller-status.adoc[leveloffset=+1] - -[id="configuring-ingress-controller"] -== Configuring the Ingress Controller - -include::modules/nw-ingress-setting-a-custom-default-certificate.adoc[leveloffset=+2] - -include::modules/nw-scaling-ingress-controller.adoc[leveloffset=+2] - -include::modules/nw-configure-ingress-access-logging.adoc[leveloffset=+2] - -include::modules/nw-ingress-sharding.adoc[leveloffset=+2] - -include::modules/nw-ingress-sharding-route-labels.adoc[leveloffset=+3] - -include::modules/nw-ingress-sharding-namespace-labels.adoc[leveloffset=+3] - -include::modules/nw-ingress-setting-internal-lb.adoc[leveloffset=+2] - -include::modules/nw-ingress-default-internal.adoc[leveloffset=+2] - -include::modules/nw-route-admission-policy.adoc[leveloffset=+2] - -include::modules/using-wildcard-routes.adoc[leveloffset=+2] - -include::modules/nw-using-ingress-forwarded.adoc[leveloffset=+2] - -include::modules/nw-http2-haproxy.adoc[leveloffset=+2] - -include::modules/nw-ingress-configuring-application-domain.adoc[leveloffset=+2] - -//include::modules/nw-ingress-select-route.adoc[leveloffset=+2] - -== Additional resources - -* xref:../networking/configuring-a-custom-pki.adoc#configuring-a-custom-pki[Configuring a custom PKI] diff --git a/networking/k8s_nmstate/k8s-nmstate-about-the-k8s-nmstate-operator.adoc b/networking/k8s_nmstate/k8s-nmstate-about-the-k8s-nmstate-operator.adoc deleted file mode 100644 index 4b325fcdcc6d..000000000000 --- a/networking/k8s_nmstate/k8s-nmstate-about-the-k8s-nmstate-operator.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="k8s-nmstate-about-the-k8s-nmstate-operator"] -= About the Kubernetes NMState Operator -:FeatureName: Kubernetes NMState Operator -:context: k8s-nmstate-operator - -toc::[] - -The Kubernetes NMState Operator provides a Kubernetes API for performing state-driven network configuration across the {product-title} cluster's nodes with NMState. The Kubernetes NMState Operator provides users with functionality to configure various network interface types, DNS, and routing on cluster nodes. Additionally, the daemons on the cluster nodes periodically report on the state of each node's network interfaces to the API server. - -include::modules/technology-preview.adoc[] - -Before you can use NMState with {product-title}, you must install the Kubernetes NMState Operator. - -include::modules/k8s-nmstate-installing-the-kubernetes-nmstate-operator.adoc[leveloffset=+1] diff --git a/networking/k8s_nmstate/k8s-nmstate-observing-node-network-state.adoc b/networking/k8s_nmstate/k8s-nmstate-observing-node-network-state.adoc deleted file mode 100644 index cd30a45beb23..000000000000 --- a/networking/k8s_nmstate/k8s-nmstate-observing-node-network-state.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="k8s-nmstate-observing-node-network-state"] -= Observing node network state -include::modules/virt-document-attributes.adoc[] -:VirtProductName: OpenShift Container Platform -:context: k8s-nmstate-observing-node-network-state - -toc::[] - -Node network state is the network configuration for all nodes in the cluster. - -include::modules/virt-about-nmstate.adoc[leveloffset=+1] - -include::modules/virt-viewing-network-state-of-node.adoc[leveloffset=+1] diff --git a/networking/k8s_nmstate/k8s-nmstate-troubleshooting-node-network.adoc b/networking/k8s_nmstate/k8s-nmstate-troubleshooting-node-network.adoc deleted file mode 100644 index 6a1987d89dac..000000000000 --- a/networking/k8s_nmstate/k8s-nmstate-troubleshooting-node-network.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="k8s-nmstate-troubleshooting-node-network"] -= Troubleshooting node network configuration -include::modules/virt-document-attributes.adoc[] -:VirtProductName: OpenShift Container Platform -:context: k8s-nmstate-troubleshooting-node-network - -toc::[] - -If the node network configuration encounters an issue, the policy is automatically rolled back and the enactments report failure. -This includes issues such as: - -* The configuration fails to be applied on the host. -* The host loses connection to the default gateway. -* The host loses connection to the API server. - -include::modules/virt-troubleshooting-incorrect-policy-config.adoc[leveloffset=+1] diff --git a/networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc b/networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc deleted file mode 100644 index aaeecf7183e3..000000000000 --- a/networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc +++ /dev/null @@ -1,38 +0,0 @@ -[id="k8s-nmstate-updating-node-network-config"] -= Updating node network configuration -include::modules/virt-document-attributes.adoc[] -:VirtProductName: OpenShift Container Platform -:context: k8s_nmstate-updating-node-network-config - -toc::[] - -You can update the node network configuration, such as adding or removing interfaces from nodes, by applying `NodeNetworkConfigurationPolicy` manifests to the cluster. - -include::modules/virt-about-nmstate.adoc[leveloffset=+1] - -include::modules/virt-creating-interface-on-nodes.adoc[leveloffset=+1] - -[discrete] -== Additional resources -* xref:virt-example-nmstate-multiple-interfaces_{context}[Example for creating multiple interfaces in the same policy] -* xref:virt-example-nmstate-IP-management_{context}[Examples of different IP management methods in policies] - -include::modules/virt-confirming-policy-updates-on-nodes.adoc[leveloffset=+1] - -include::modules/virt-removing-interface-from-nodes.adoc[leveloffset=+1] - -[id="virt-nmstate-example-policy-configurations"] -== Example policy configurations for different interfaces - -include::modules/virt-example-bridge-nncp.adoc[leveloffset=+2] - -include::modules/virt-example-vlan-nncp.adoc[leveloffset=+2] - -include::modules/virt-example-bond-nncp.adoc[leveloffset=+2] - -include::modules/virt-example-ethernet-nncp.adoc[leveloffset=+2] - -include::modules/virt-example-nmstate-multiple-interfaces.adoc[leveloffset=+2] - -// Dropping offset by one again -include::modules/virt-example-nmstate-IP-management.adoc[leveloffset=+1] diff --git a/networking/k8s_nmstate/modules b/networking/k8s_nmstate/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/networking/k8s_nmstate/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/networking/load-balancing-openstack.adoc b/networking/load-balancing-openstack.adoc deleted file mode 100644 index 0ba81865ea9a..000000000000 --- a/networking/load-balancing-openstack.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="load-balancing-openstack"] -= Load balancing on {rh-openstack} -include::modules/common-attributes.adoc[] -:context: load-balancing-openstack - -toc::[] - -include::modules/installation-osp-kuryr-octavia-upgrade.adoc[leveloffset=+1] -include::modules/installation-osp-api-octavia.adoc[leveloffset=+1] -include::modules/installation-osp-api-scaling.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-api-scaling.adoc[leveloffset=+2] -include::modules/installation-osp-kuryr-ingress-scaling.adoc[leveloffset=+1] -include::modules/nw-osp-configuring-external-load-balancer.adoc[leveloffset=+1] diff --git a/networking/modules b/networking/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/networking/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/networking/multiple_networks/about-virtual-routing-and-forwarding.adoc b/networking/multiple_networks/about-virtual-routing-and-forwarding.adoc deleted file mode 100644 index 5f3f8b1a40b7..000000000000 --- a/networking/multiple_networks/about-virtual-routing-and-forwarding.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="about-virtual-routing-and-forwarding"] -= About virtual routing and forwarding -include::modules/common-attributes.adoc[] -:context: about-virtual-routing-and-forwarding - -toc::[] - -include::modules/cnf-about-virtual-routing-and-forwarding.adoc[leveloffset=+1] diff --git a/networking/multiple_networks/assigning-a-secondary-network-to-a-vrf.adoc b/networking/multiple_networks/assigning-a-secondary-network-to-a-vrf.adoc deleted file mode 100644 index 6343076e533c..000000000000 --- a/networking/multiple_networks/assigning-a-secondary-network-to-a-vrf.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="assigning-a-secondary-network-to-a-vrf"] -= Assigning a secondary network to a VRF -include::modules/common-attributes.adoc[] -:context: assigning-a-secondary-network-to-a-vrf - -toc::[] - -:FeatureName: CNI VRF plug-in -include::modules/technology-preview.adoc[leveloffset=+1] - -include::modules/cnf-assigning-a-secondary-network-to-a-vrf.adoc[leveloffset=+1] diff --git a/networking/multiple_networks/attaching-pod.adoc b/networking/multiple_networks/attaching-pod.adoc deleted file mode 100644 index 2e7d0c108a8c..000000000000 --- a/networking/multiple_networks/attaching-pod.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="attaching-pod"] -= Attaching a pod to an additional network -include::modules/common-attributes.adoc[] -:context: attaching-pod - -toc::[] - -As a cluster user you can attach a pod to an additional network. - -include::modules/nw-multus-add-pod.adoc[leveloffset=+1] -include::modules/nw-multus-advanced-annotations.adoc[leveloffset=+2] diff --git a/networking/multiple_networks/configuring-bridge.adoc b/networking/multiple_networks/configuring-bridge.adoc deleted file mode 100644 index c08b8831ee28..000000000000 --- a/networking/multiple_networks/configuring-bridge.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="configuring-bridge"] -= Configuring a bridge network -include::modules/common-attributes.adoc[] -:context: configuring-bridge - -toc::[] - -As a cluster administrator, you can configure an additional network for your -cluster using the bridge Container Network Interface (CNI) plug-in. When -configured, all Pods on a node are connected to a virtual switch. Each pod is -assigned an IP address on the additional network. - -// TODO - include specifics of virtual bridge - -include::modules/nw-multus-create-network.adoc[leveloffset=+1] -include::modules/nw-multus-bridge-object.adoc[leveloffset=+2] -include::modules/nw-multus-ipam-object.adoc[leveloffset=+2] - -== Next steps - -* xref:../../networking/multiple_networks/attaching-pod.adoc#attaching-pod[Attach a pod to an additional network]. diff --git a/networking/multiple_networks/configuring-host-device.adoc b/networking/multiple_networks/configuring-host-device.adoc deleted file mode 100644 index 917ba486f2c1..000000000000 --- a/networking/multiple_networks/configuring-host-device.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="configuring-host-device"] -= Configuring a host-device network -include::modules/common-attributes.adoc[] -:context: configuring-host-device - -toc::[] - -As a cluster administrator, you can configure an additional network for your cluster by using the host-device Container Network Interface (CNI) plug-in. The plug-in moves the specified network device from the network namespace of the host into the network namespace of the pod. - -include::modules/nw-multus-create-network.adoc[leveloffset=+1] -include::modules/nw-multus-host-device-object.adoc[leveloffset=+2] -include::modules/nw-multus-ipam-object.adoc[leveloffset=+2] - -== Next steps - -* xref:../../networking/multiple_networks/attaching-pod.adoc#attaching-pod[Attach a pod to an additional network]. diff --git a/networking/multiple_networks/configuring-ipvlan.adoc b/networking/multiple_networks/configuring-ipvlan.adoc deleted file mode 100644 index 6b04214698e4..000000000000 --- a/networking/multiple_networks/configuring-ipvlan.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="configuring-ipvlan"] -= Configuring an ipvlan network -include::modules/common-attributes.adoc[] -:context: configuring-ipvlan - -toc::[] - -As a cluster administrator, you can configure an additional network for your -cluster by using the ipvlan Container Network Interface (CNI) plug-in. The virtual -network created by this plug-in is associated with a physical interface that you -specify. - -// Each virtual interface shares the same MAC address as the physical interface. - -// TODO - Discuss layer 2, layer 3, and layer 3s. - -include::modules/nw-multus-create-network.adoc[leveloffset=+1] -include::modules/nw-multus-ipvlan-object.adoc[leveloffset=+2] -include::modules/nw-multus-ipam-object.adoc[leveloffset=+2] - -== Next steps - -* xref:../../networking/multiple_networks/attaching-pod.adoc#attaching-pod[Attach a pod to an additional network]. diff --git a/networking/multiple_networks/configuring-macvlan-basic.adoc b/networking/multiple_networks/configuring-macvlan-basic.adoc deleted file mode 100644 index 26acd54485e0..000000000000 --- a/networking/multiple_networks/configuring-macvlan-basic.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="configuring-macvlan-basic"] -= Configuring a macvlan network with basic customizations -include::modules/common-attributes.adoc[] -:context: configuring-macvlan-basic - -toc::[] - -As a cluster administrator, you can configure an additional network for your cluster using the macvlan Container Network Interface (CNI) plug-in. -When a pod is attached to the network, the plug-in creates a sub-interface from the parent interface on the host. -A unique hardware mac address is generated for each sub-device. - -[IMPORTANT] -==== -The unique MAC addresses this plug-in generates for sub-interfaces might not be -compatible with the security polices of your cloud provider. -==== - -You specify a basic configuration directly in YAML. This approach offers fewer configuration options than by specifying a macvlan configuration by using a CNI object directly in JSON. - -include::modules/nw-multus-create-network.adoc[leveloffset=+1] -include::modules/nw-multus-macvlan-object.adoc[leveloffset=+2] -include::modules/nw-multus-ipam-object.adoc[leveloffset=+2] - -== Next steps - -* xref:../../networking/multiple_networks/attaching-pod.adoc#attaching-pod[Attach a pod to an additional network]. diff --git a/networking/multiple_networks/configuring-macvlan.adoc b/networking/multiple_networks/configuring-macvlan.adoc deleted file mode 100644 index 1c761ab4a231..000000000000 --- a/networking/multiple_networks/configuring-macvlan.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="configuring-macvlan"] -= Configuring a macvlan network -include::modules/common-attributes.adoc[] -:context: configuring-macvlan - -toc::[] - -As a cluster administrator, you can configure an additional network for your cluster using the macvlan Container Network Interface (CNI) plug-in with advanced customization. -When a pod is attached to the network, the plug-in creates a sub-interface from the parent interface on the host. -A unique hardware mac address is generated for each sub-device. - -[IMPORTANT] -==== -The unique MAC addresses this plug-in generates for sub-interfaces might not be -compatible with the security polices of your cloud provider. -==== - -You specify a configuration with a CNI object. This approach allows you to specify additional configuration options that are not available when using a YAML configuration. - -include::modules/nw-multus-create-network.adoc[leveloffset=+1] -include::modules/nw-multus-macvlan-object.adoc[leveloffset=+2] -include::modules/nw-multus-ipam-object.adoc[leveloffset=+2] - -== Next steps - -* xref:../../networking/multiple_networks/attaching-pod.adoc#attaching-pod[Attach a pod to an additional network]. diff --git a/networking/multiple_networks/edit-additional-network.adoc b/networking/multiple_networks/edit-additional-network.adoc deleted file mode 100644 index e5d7a5009f9a..000000000000 --- a/networking/multiple_networks/edit-additional-network.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="edit-additional-network"] -= Editing an additional network -include::modules/common-attributes.adoc[] -:context: edit-additional-network - -toc::[] - -As a cluster administrator you can modify the configuration for an existing -additional network. - -include::modules/nw-multus-edit-network.adoc[leveloffset=+1] diff --git a/networking/multiple_networks/remove-additional-network.adoc b/networking/multiple_networks/remove-additional-network.adoc deleted file mode 100644 index 683ceaa21f7d..000000000000 --- a/networking/multiple_networks/remove-additional-network.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="remove-additional-network"] -= Removing an additional network -include::modules/common-attributes.adoc[] -:context: remove-additional-network - -toc::[] - -As a cluster administrator you can remove an additional network attachment. - -include::modules/nw-multus-delete-network.adoc[leveloffset=+1] diff --git a/networking/multiple_networks/removing-pod.adoc b/networking/multiple_networks/removing-pod.adoc deleted file mode 100644 index f38082549476..000000000000 --- a/networking/multiple_networks/removing-pod.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="removing-pod"] -= Removing a pod from an additional network -include::modules/common-attributes.adoc[] -:context: removing-pod - -toc::[] - -As a cluster user you can remove a pod from an additional network. - -include::modules/nw-multus-remove-pod.adoc[leveloffset=+1] diff --git a/networking/multiple_networks/understanding-multiple-networks.adoc b/networking/multiple_networks/understanding-multiple-networks.adoc deleted file mode 100644 index 1103867057dc..000000000000 --- a/networking/multiple_networks/understanding-multiple-networks.adoc +++ /dev/null @@ -1,68 +0,0 @@ -[id="understanding-multiple-networks"] -= Understanding multiple networks -include::modules/common-attributes.adoc[] -:context: understanding-multiple-networks - -toc::[] - -In Kubernetes, container networking is delegated to networking plug-ins that -implement the Container Network Interface (CNI). - -{product-title} uses the Multus CNI plug-in to allow chaining of CNI plug-ins. -During cluster installation, you configure your _default_ pod network. The -default network handles all ordinary network traffic for the cluster. You can -define an _additional network_ based on the available CNI plug-ins and attach -one or more of these networks to your pods. You can define more than one -additional network for your cluster, depending on your needs. This gives you -flexibility when you configure pods that deliver network functionality, such as -switching or routing. - -[id="additional-network-considerations"] -== Usage scenarios for an additional network - -You can use an additional network in situations where network isolation is -needed, including data plane and control plane separation. Isolating network -traffic is useful for the following performance and security reasons: - -Performance:: You can send traffic on two different planes to manage -how much traffic is along each plane. -Security:: You can send sensitive traffic onto a network plane that is managed -specifically for security considerations, and you can separate private data that -must not be shared between tenants or customers. - -All of the pods in the cluster still use the cluster-wide default network -to maintain connectivity across the cluster. Every pod has an `eth0` interface -that is attached to the cluster-wide pod network. You can view the interfaces -for a pod by using the `oc exec -it <pod_name> \-- ip a` command. If you -add additional network interfaces that use Multus CNI, they are named `net1`, -`net2`, ..., `netN`. - -To attach additional network interfaces to a pod, you must create configurations that define how the interfaces are attached. You specify each interface by using a `NetworkAttachmentDefinition` custom resource (CR). A CNI configuration inside each of these CRs defines how that interface is created. - -[id="additional-networks-provided"] -== Additional networks in {product-title} - -{product-title} provides the following CNI plug-ins for creating additional -networks in your cluster: - - * *bridge*: xref:../../networking/multiple_networks/configuring-bridge.adoc#configuring-bridge[Creating a bridge-based additional network] - allows pods on the same host to communicate with each other and the host. - -* *host-device*: xref:../../networking/multiple_networks/configuring-host-device.adoc#configuring-host-device[Configuring a host-device additional network] allows pods access to a physical Ethernet network device on the host system. - - * *ipvlan*: xref:../../networking/multiple_networks/configuring-ipvlan.adoc#configuring-ipvlan[Configuring an ipvlan-based additional network] - allows pods on a host to communicate with other hosts and pods on those hosts, - similar to a macvlan-based additional network. Unlike a macvlan-based - additional network, each pod shares the same MAC address as the parent physical - network interface. - - * *macvlan*: Creating a macvlan-based additional network allows pods on a host to communicate with other hosts and pods on those hosts by using a physical network interface. Each pod that is attached to a macvlan-based additional network is provided a unique MAC address. -+ -A macvlan additional network can be configured in two ways: - - - xref:../../networking/multiple_networks/configuring-macvlan-basic.adoc#configuring-macvlan-basic[Configuring a macvlan-based additional network with basic customizations] - - xref:../../networking/multiple_networks/configuring-macvlan.adoc#configuring-macvlan[Configuring a macvlan-based additional network] - - * *SR-IOV*: xref:../../networking/hardware_networks/about-sriov.adoc#about-sriov[Configuring an SR-IOV based additional network] allows pods to attach to a virtual function (VF) interface on SR-IOV capable hardware on the host system. - -include::modules/nw-multus-remove-pod.adoc[leveloffset=+1] diff --git a/networking/network_policy/about-network-policy.adoc b/networking/network_policy/about-network-policy.adoc deleted file mode 100644 index e1b2c33a84c0..000000000000 --- a/networking/network_policy/about-network-policy.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="about-network-policy"] -= About network policy -include::modules/common-attributes.adoc[] -:context: about-network-policy - -toc::[] - -As a cluster administrator, you can define network policies that restrict traffic to pods in your cluster. - -include::modules/nw-networkpolicy-about.adoc[leveloffset=+1] - -include::modules/nw-networkpolicy-optimize.adoc[leveloffset=+1] - -[id="about-network-policy-next-steps"] -== Next steps - -* xref:../../networking/network_policy/creating-network-policy.adoc#creating-network-policy[Creating a network policy] -* Optional: xref:../../networking/network_policy/default-network-policy.adoc#default-network-policy[Defining a default network policy] - -[id="about-network-policy-additional-resources"] -== Additional resources - -* xref:../../networking/network_policy/multitenant-network-policy.adoc#multitenant-network-policy[Configuring multitenant network policy] -* xref:../../rest_api/network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[NetworkPolicy API] diff --git a/networking/network_policy/creating-network-policy.adoc b/networking/network_policy/creating-network-policy.adoc deleted file mode 100644 index cc06cc080c8e..000000000000 --- a/networking/network_policy/creating-network-policy.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="creating-network-policy"] -= Creating a network policy -include::modules/common-attributes.adoc[] -:context: creating-network-policy - -toc::[] - -As a cluster administrator, you can create a network policy for a namespace. - -include::modules/nw-networkpolicy-create.adoc[leveloffset=+1] - -include::modules/nw-networkpolicy-object.adoc[leveloffset=+1] diff --git a/networking/network_policy/default-network-policy.adoc b/networking/network_policy/default-network-policy.adoc deleted file mode 100644 index 4253f9695dc3..000000000000 --- a/networking/network_policy/default-network-policy.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="default-network-policy"] -= Creating default network policies for a new project -include::modules/common-attributes.adoc[] -:context: default-network-policy - -toc::[] - -As a cluster administrator, you can modify the new project template to -automatically include network policies when you create a new project. -If you do not yet have a customized template for new projects, you must first create one. - -include::modules/modifying-template-for-new-projects.adoc[leveloffset=+1] - -include::modules/nw-networkpolicy-project-defaults.adoc[leveloffset=+1] diff --git a/networking/network_policy/deleting-network-policy.adoc b/networking/network_policy/deleting-network-policy.adoc deleted file mode 100644 index 715a53b4552c..000000000000 --- a/networking/network_policy/deleting-network-policy.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="deleting-network-policy"] -= Deleting a network policy -include::modules/common-attributes.adoc[] -:context: deleting-network-policy - -toc::[] - -As a cluster administrator, you can delete a network policy from a namespace. - -include::modules/nw-networkpolicy-delete.adoc[leveloffset=+1] diff --git a/networking/network_policy/editing-network-policy.adoc b/networking/network_policy/editing-network-policy.adoc deleted file mode 100644 index 8702984d40ad..000000000000 --- a/networking/network_policy/editing-network-policy.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="editing-network-policy"] -= Editing a network policy -include::modules/common-attributes.adoc[] -:context: editing-network-policy - -toc::[] - -As a cluster administrator, you can edit an existing network policy for a namespace. - -include::modules/nw-networkpolicy-edit.adoc[leveloffset=+1] - -include::modules/nw-networkpolicy-object.adoc[leveloffset=+1] - -[id="editing-network-policy-additional-resources"] -== Additional resources -- xref:../../networking/network_policy/creating-network-policy.adoc#creating-network-policy[Creating a network policy] diff --git a/networking/network_policy/multitenant-network-policy.adoc b/networking/network_policy/multitenant-network-policy.adoc deleted file mode 100644 index bc51e6fa105c..000000000000 --- a/networking/network_policy/multitenant-network-policy.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="multitenant-network-policy"] -= Configuring multitenant isolation with network policy -include::modules/common-attributes.adoc[] -:context: multitenant-network-policy - -toc::[] - -As a cluster administrator, you can configure your network policies to provide multitenant network isolation. - -[NOTE] -==== -If you are using the OpenShift SDN cluster network provider, configuring network policies as described in this section provides network isolation similar to multitenant mode but with network policy mode set. -==== - -include::modules/nw-networkpolicy-multitenant-isolation.adoc[leveloffset=+1] - -[id="multitenant-network-policy-next-steps"] -== Next steps - -* xref:../../networking/network_policy/default-network-policy.adoc#default-network-policy[Defining a default network policy] - -[id="multitenant-network-policy-additional-resources"] -== Additional resources - -* xref:../../networking/openshift_sdn/about-openshift-sdn.adoc#nw-openshift-sdn-modes_about-openshift-sdn[OpenShift SDN network isolation modes] diff --git a/networking/network_policy/viewing-network-policy.adoc b/networking/network_policy/viewing-network-policy.adoc deleted file mode 100644 index 35dbca1d7373..000000000000 --- a/networking/network_policy/viewing-network-policy.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="viewing-network-policy"] -= Viewing a network policy -include::modules/common-attributes.adoc[] -:context: viewing-network-policy - -toc::[] - -As a cluster administrator, you can view a network policy for a namespace. - -include::modules/nw-networkpolicy-view.adoc[leveloffset=+1] - -include::modules/nw-networkpolicy-object.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/about-openshift-sdn.adoc b/networking/openshift_sdn/about-openshift-sdn.adoc deleted file mode 100644 index 1e0cae2b5d3f..000000000000 --- a/networking/openshift_sdn/about-openshift-sdn.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="about-openshift-sdn"] -= About the OpenShift SDN default CNI network provider -include::modules/common-attributes.adoc[] -:context: about-openshift-sdn - -toc::[] - -{product-title} uses a software-defined networking (SDN) approach to provide a -unified cluster network that enables communication between pods across the -{product-title} cluster. This pod network is established and maintained by the -OpenShift SDN, which configures an overlay network using Open vSwitch (OVS). - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/nw-openshift-sdn-modes.adoc[leveloffset=+1] - -ifdef::openshift-origin[] -[NOTE] -==== -{product-title} uses the xref:../../networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc#about-ovn-kubernetes[OVN-Kubernetes Container Network Interface (CNI) plug-in] by default. -==== -endif::openshift-origin[] -endif::[] - -ifdef::openshift-dedicated[] -OpenShift SDN supports only the _network policy_ mode, which allows project -administrators to configure their own isolation policies by using -xref:../../networking/network_policy/about-network-policy.adoc#about-network-policy[NetworkPolicy objects]. -endif::[] - -// flipped table for OpenShift SDN -include::modules/nw-ovn-kubernetes-matrix.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/assigning-egress-ips.adoc b/networking/openshift_sdn/assigning-egress-ips.adoc deleted file mode 100644 index 99d33ed1080a..000000000000 --- a/networking/openshift_sdn/assigning-egress-ips.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="assigning-egress-ips"] -= Configuring egress IPs for a project -include::modules/common-attributes.adoc[] -:context: egress-ips - -toc::[] - -As a cluster administrator, you can configure the OpenShift SDN default Container Network Interface (CNI) network provider to assign one or more egress IP addresses to a project. - -include::modules/nw-egress-ips-about.adoc[leveloffset=+1] - -include::modules/nw-egress-ips-automatic.adoc[leveloffset=+1] - -include::modules/nw-egress-ips-static.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/configuring-egress-firewall.adoc b/networking/openshift_sdn/configuring-egress-firewall.adoc deleted file mode 100644 index 35bd040426db..000000000000 --- a/networking/openshift_sdn/configuring-egress-firewall.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="configuring-egress-firewall"] -= Configuring an egress firewall for a project -include::modules/common-attributes.adoc[] -:context: openshift-sdn-egress-firewall - -toc::[] - -As a cluster administrator, you can create an egress firewall for a project that restricts egress traffic leaving your {product-title} cluster. - -include::modules/nw-egressnetworkpolicy-about.adoc[leveloffset=+1] -include::modules/nw-egressnetworkpolicy-object.adoc[leveloffset=+1] -include::modules/nw-egressnetworkpolicy-create.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/configuring-egress-router-configmap.adoc b/networking/openshift_sdn/configuring-egress-router-configmap.adoc deleted file mode 100644 index d9e279e76753..000000000000 --- a/networking/openshift_sdn/configuring-egress-router-configmap.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="configuring-egress-router-configmap"] -= Configuring an egress router pod destination list from a config map -include::modules/common-attributes.adoc[] -:context: configuring-egress-router-configmap - -toc::[] - -As a cluster administrator, you can define a `ConfigMap` object that specifies destination mappings for an egress router pod. The specific format of the configuration depends on the type of egress router pod. For details on the format, refer to the documentation for the specific egress router pod. - -include::modules/nw-egress-router-configmap.adoc[leveloffset=+1] - -[id="configuring-egress-router-configmap-additional-resources"] -== Additional resources - -- xref:../../networking/openshift_sdn/deploying-egress-router-layer3-redirection.adoc#nw-egress-router-dest-var_deploying-egress-router-layer3-redirection[Redirect mode] -- xref:../../networking/openshift_sdn/deploying-egress-router-http-redirection.adoc#nw-egress-router-dest-var_deploying-egress-router-http-redirection[HTTP proxy mode] -- xref:../../networking/openshift_sdn/deploying-egress-router-dns-redirection.adoc#nw-egress-router-dest-var_deploying-egress-router-dns-redirection[DNS proxy mode] diff --git a/networking/openshift_sdn/configuring-kube-proxy.adoc b/networking/openshift_sdn/configuring-kube-proxy.adoc deleted file mode 100644 index b8d2e4a4d88d..000000000000 --- a/networking/openshift_sdn/configuring-kube-proxy.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="configuring-kube-proxy"] -= Configuring kube-proxy -include::modules/common-attributes.adoc[] -:context: configuring-kube-proxy - -toc::[] - -The Kubernetes network proxy (kube-proxy) runs on each node and is managed by -the Cluster Network Operator (CNO). kube-proxy maintains network rules for -forwarding connections for endpoints associated with services. - -include::modules/nw-kube-proxy-sync.adoc[leveloffset=+1] -include::modules/nw-kube-proxy-config.adoc[leveloffset=+1] -include::modules/nw-kube-proxy-configuring.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/deploying-egress-router-dns-redirection.adoc b/networking/openshift_sdn/deploying-egress-router-dns-redirection.adoc deleted file mode 100644 index 11e6e3418e9e..000000000000 --- a/networking/openshift_sdn/deploying-egress-router-dns-redirection.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="deploying-egress-router-dns-redirection"] -= Deploying an egress router pod in DNS proxy mode -include::modules/common-attributes.adoc[] -:context: deploying-egress-router-dns-redirection - -toc::[] - -As a cluster administrator, you can deploy an egress router pod configured to proxy traffic to specified DNS names and IP addresses. - -include::modules/nw-egress-router-pod.adoc[leveloffset=+1] - -include::modules/nw-egress-router-dest-var.adoc[leveloffset=+1] - -include::modules/nw-egress-router-dns-mode.adoc[leveloffset=+1] - -[id="deploying-egress-router-dns-redirection-additional-resources"] -== Additional resources - -* xref:../../networking/openshift_sdn/configuring-egress-router-configmap.adoc#configuring-egress-router-configmap[Configuring an egress router destination mappings with a ConfigMap] diff --git a/networking/openshift_sdn/deploying-egress-router-http-redirection.adoc b/networking/openshift_sdn/deploying-egress-router-http-redirection.adoc deleted file mode 100644 index 38668c1221f5..000000000000 --- a/networking/openshift_sdn/deploying-egress-router-http-redirection.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="deploying-egress-router-http-redirection"] -= Deploying an egress router pod in HTTP proxy mode -include::modules/common-attributes.adoc[] -:context: deploying-egress-router-http-redirection - -toc::[] - -As a cluster administrator, you can deploy an egress router pod configured to proxy traffic to specified HTTP and HTTPS-based services. - -include::modules/nw-egress-router-pod.adoc[leveloffset=+1] - -include::modules/nw-egress-router-dest-var.adoc[leveloffset=+1] - -include::modules/nw-egress-router-http-proxy-mode.adoc[leveloffset=+1] - -[id="deploying-egress-router-http-redirection-additional-resources"] -== Additional resources - -* xref:../../networking/openshift_sdn/configuring-egress-router-configmap.adoc#configuring-egress-router-configmap[Configuring an egress router destination mappings with a ConfigMap] diff --git a/networking/openshift_sdn/deploying-egress-router-layer3-redirection.adoc b/networking/openshift_sdn/deploying-egress-router-layer3-redirection.adoc deleted file mode 100644 index 5d64ace4a03a..000000000000 --- a/networking/openshift_sdn/deploying-egress-router-layer3-redirection.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="deploying-egress-router-layer3-redirection"] -= Deploying an egress router pod in redirect mode -include::modules/common-attributes.adoc[] -:context: deploying-egress-router-layer3-redirection - -toc::[] - -As a cluster administrator, you can deploy an egress router pod that is configured to redirect traffic to specified destination IP addresses. - -include::modules/nw-egress-router-pod.adoc[leveloffset=+1] - -include::modules/nw-egress-router-dest-var.adoc[leveloffset=+1] - -include::modules/nw-egress-router-redirect-mode.adoc[leveloffset=+1] - -[id="deploying-egress-router-layer3-redirection-additional-resources"] -== Additional resources - -* xref:../../networking/openshift_sdn/configuring-egress-router-configmap.adoc#configuring-egress-router-configmap[Configuring an egress router destination mappings with a ConfigMap] diff --git a/networking/openshift_sdn/disabling-multicast.adoc b/networking/openshift_sdn/disabling-multicast.adoc deleted file mode 100644 index a4801e184dca..000000000000 --- a/networking/openshift_sdn/disabling-multicast.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="disabling-multicast"] -= Disabling multicast for a project -include::modules/common-attributes.adoc[] -:context: openshift-sdn-disabling-multicast - -toc::[] - -include::modules/nw-disabling-multicast.adoc[leveloffset=+1] - diff --git a/networking/openshift_sdn/editing-egress-firewall.adoc b/networking/openshift_sdn/editing-egress-firewall.adoc deleted file mode 100644 index b848f2668ba0..000000000000 --- a/networking/openshift_sdn/editing-egress-firewall.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="editing-egress-firewall"] -= Editing an egress firewall for a project -include::modules/common-attributes.adoc[] -:context: openshift-sdn-egress-firewall - -toc::[] - -As a cluster administrator, you can modify network traffic rules for an existing egress firewall. - -include::modules/nw-egressnetworkpolicy-edit.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/enabling-multicast.adoc b/networking/openshift_sdn/enabling-multicast.adoc deleted file mode 100644 index a2e54b8fa740..000000000000 --- a/networking/openshift_sdn/enabling-multicast.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="enabling-multicast"] -= Enabling multicast for a project -include::modules/common-attributes.adoc[] -:context: openshift-sdn-enabling-multicast - -toc::[] - -include::modules/nw-about-multicast.adoc[leveloffset=+1] -include::modules/nw-enabling-multicast.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/multitenant-isolation.adoc b/networking/openshift_sdn/multitenant-isolation.adoc deleted file mode 100644 index 068ed875092e..000000000000 --- a/networking/openshift_sdn/multitenant-isolation.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="configuring-multitenant-isolation"] -= Configuring network isolation using OpenShift SDN -include::modules/common-attributes.adoc[] -:context: multitenant-isolation - -toc::[] - -When your cluster is configured to use the multitenant isolation mode for the -OpenShift SDN CNI plug-in, each project is isolated by default. Network traffic -is not allowed between pods or services in different projects in multitenant -isolation mode. - -You can change the behavior of multitenant isolation for a project in two ways: - -* You can join one or more projects, allowing network traffic between pods and -services in different projects. - -* You can disable network isolation for a project. It will be globally -accessible, accepting network traffic from pods and services in all other -projects. A globally accessible project can access pods and services in all -other projects. - -== Prerequisites - -* You must have a cluster configured to use the OpenShift SDN Container Network -Interface (CNI) plug-in in multitenant isolation mode. - -include::modules/nw-multitenant-joining.adoc[leveloffset=+1] -include::modules/nw-multitenant-isolation.adoc[leveloffset=+1] -include::modules/nw-multitenant-global.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/removing-egress-firewall.adoc b/networking/openshift_sdn/removing-egress-firewall.adoc deleted file mode 100644 index 61c12d9e1a9e..000000000000 --- a/networking/openshift_sdn/removing-egress-firewall.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="removing-egress-firewall"] -= Removing an egress firewall from a project -include::modules/common-attributes.adoc[] -:context: openshift-sdn-egress-firewall - -toc::[] - -As a cluster administrator, you can remove an egress firewall from a project to remove all restrictions on network traffic from the project that leaves the {product-title} cluster. - -include::modules/nw-egressnetworkpolicy-delete.adoc[leveloffset=+1] diff --git a/networking/openshift_sdn/using-an-egress-router.adoc b/networking/openshift_sdn/using-an-egress-router.adoc deleted file mode 100644 index aa2f9bfd7c4f..000000000000 --- a/networking/openshift_sdn/using-an-egress-router.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="using-an-egress-router"] -= Considerations for the use of an egress router pod -include::modules/common-attributes.adoc[] -:context: using-an-egress-router - -toc::[] - -include::modules/nw-egress-router-about.adoc[leveloffset=+1] - -[id="using-an-egress-router-additional-resources"] -== Additional resources - -- xref:../../networking/openshift_sdn/deploying-egress-router-layer3-redirection.adoc#deploying-egress-router-layer3-redirection[Deploying an egress router in redirection mode] -- xref:../../networking/openshift_sdn/deploying-egress-router-http-redirection.adoc#deploying-egress-router-http-redirection[Deploying an egress router in HTTP proxy mode] -- xref:../../networking/openshift_sdn/deploying-egress-router-dns-redirection.adoc#deploying-egress-router-dns-redirection[Deploying an egress router in DNS proxy mode] diff --git a/networking/openshift_sdn/viewing-egress-firewall.adoc b/networking/openshift_sdn/viewing-egress-firewall.adoc deleted file mode 100644 index ba8e9a388535..000000000000 --- a/networking/openshift_sdn/viewing-egress-firewall.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="openshift-sdn-viewing-egress-firewall"] -= Editing an egress firewall for a project -include::modules/common-attributes.adoc[] -:context: openshift-sdn-viewing-egress-firewall - -toc::[] - -As a cluster administrator, you can modify network traffic rules for an existing egress firewall. - -include::modules/nw-egressnetworkpolicy-view.adoc[leveloffset=+1] diff --git a/networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc b/networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc deleted file mode 100644 index 2e7f8d4277fb..000000000000 --- a/networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="about-ipsec-ovn"] -= IPsec encryption configuration -include::modules/common-attributes.adoc[] -:context: about-ipsec-ovn - -toc::[] - -With IPsec enabled, all network traffic between nodes on the OVN-Kubernetes Container Network Interface (CNI) cluster network travels through an encrypted tunnel. - -IPsec is disabled by default. - -[NOTE] -==== -IPsec encryption can be enabled only during cluster installation and cannot be disabled after it is enabled. -For installation documentation, refer to xref:../../installing/installing-preparing.adoc#installing-preparing[Selecting a cluster installation method and preparing it for users]. -==== - -include::modules/nw-ovn-ipsec-traffic.adoc[leveloffset=+1] -include::modules/nw-ovn-ipsec-encryption.adoc[leveloffset=+1] -include::modules/nw-ovn-ipsec-certificates.adoc[leveloffset=+1] diff --git a/networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc b/networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc deleted file mode 100644 index d6ed276d3ade..000000000000 --- a/networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="about-ovn-kubernetes"] -= About the OVN-Kubernetes default Container Network Interface (CNI) network provider -include::modules/common-attributes.adoc[] -:context: about-ovn-kubernetes - -toc::[] - -The {product-title} cluster uses a virtualized network for pod and service networks. -The OVN-Kubernetes Container Network Interface (CNI) plug-in is a network provider for the default cluster network. -OVN-Kubernetes is based on Open Virtual Network (OVN) and provides an overlay-based networking implementation. -A cluster that uses the OVN-Kubernetes network provider also runs Open vSwitch (OVS) on each node. -OVN configures OVS on each node to implement the declared network configuration. - -include::modules/nw-ovn-kubernetes-features.adoc[leveloffset=+1] - -include::modules/nw-ovn-kubernetes-matrix.adoc[leveloffset=+1] -// This is a moving target; what is included isn't valid for 4.6 -//include::modules/nw-ovn-kubernetes-metrics.adoc[leveloffset=+1] - -.Additional resources - -* xref:../../networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc#configuring-egress-firewall-ovn[Configuring an egress firewall for a project] -* xref:../../networking/network_policy/about-network-policy.adoc#about-network-policy[About network policy] -* xref:../../networking/ovn_kubernetes_network_provider/enabling-multicast.adoc#nw-ovn-kubernetes-enabling-multicast[Enabling multicast for a project] -* xref:../../networking/ovn_kubernetes_network_provider/about-ipsec-ovn.adoc#about-ipsec-ovn[IPsec encryption configuration] -* xref:../../rest_api/operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[Network [operator.openshift.io/v1]] diff --git a/networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc b/networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc deleted file mode 100644 index f3c730567e05..000000000000 --- a/networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="assigning-egress-ips-ovn"] -= Assigning an egress IP address -include::modules/common-attributes.adoc[] -:context: assigning-egress-ips-ovn - -toc::[] - -As a cluster administrator, you can assign an egress IP address for traffic leaving the cluster from a namespace or from specific pods in a namespace. - -include::modules/nw-egress-ips-assign.adoc[leveloffset=+1] - -[id="assigning-egress-ips-additional-resources"] -== Additional resources - -* xref:../../networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc#configuring-egress-ips-ovn[Configuring egress IP addresses] diff --git a/networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc b/networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc deleted file mode 100644 index 3d6a936e99f3..000000000000 --- a/networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="configuring-egress-firewall-ovn"] -= Configuring an egress firewall for a project -include::modules/common-attributes.adoc[] -:context: configuring-egress-firewall-ovn - -toc::[] - -As a cluster administrator, you can create an egress firewall for a project that restricts egress traffic leaving your {product-title} cluster. - -include::modules/nw-egressnetworkpolicy-about.adoc[leveloffset=+1] -include::modules/nw-egressnetworkpolicy-object.adoc[leveloffset=+1] -include::modules/nw-egressnetworkpolicy-create.adoc[leveloffset=+1] diff --git a/networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc b/networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc deleted file mode 100644 index 806f5370118f..000000000000 --- a/networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="configuring-egress-ips-ovn"] -= Configuring an egress IP address -include::modules/common-attributes.adoc[] -:context: configuring-egress-ips-ovn - -toc::[] - -As a cluster administrator, you can configure the OVN-Kubernetes default Container Network Interface (CNI) network provider to assign one or more egress IP addresses to a namespace, or to specific pods in a namespace. - -include::modules/nw-egress-ips-about.adoc[leveloffset=+1] - -include::modules/nw-egress-ips-object.adoc[leveloffset=+1] - -include::modules/nw-egress-ips-node.adoc[leveloffset=+1] - -[id="configuring-egress-ips-next-steps"] -== Next steps - -* xref:../../networking/ovn_kubernetes_network_provider/assigning-egress-ips-ovn.adoc#assigning-egress-ips-ovn[Assigning egress IPs] - -[id="configuring-egress-ips-additional-resources"] -== Additional resources - -* xref:../../rest_api/objects/index.adoc#labelselector-meta-v1[LabelSelector meta/v1] -* xref:../../rest_api/objects/index.adoc#labelselectorrequirement-meta-v1[LabelSelectorRequirement meta/v1] diff --git a/networking/ovn_kubernetes_network_provider/configuring-hybrid-networking.adoc b/networking/ovn_kubernetes_network_provider/configuring-hybrid-networking.adoc deleted file mode 100644 index 51e2f3c3125a..000000000000 --- a/networking/ovn_kubernetes_network_provider/configuring-hybrid-networking.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="configuring-hybrid-networking"] -= Configuring hybrid networking -include::modules/common-attributes.adoc[] -:context: configuring-hybrid-networking - -toc::[] - -As a cluster administrator, you can configure the OVN-Kubernetes Container Network Interface (CNI) cluster network provider to allow Linux and Windows nodes to host Linux and Windows workloads, respectively. - -include::modules/configuring-hybrid-ovnkubernetes.adoc[leveloffset=+1] - -Complete any further installation configurations, and then create your cluster. Hybrid networking is enabled when the installation process is finished. - -[id="configuring-hybrid-networking-additional-resources"] -== Additional resources - -* xref:../../windows_containers/understanding-windows-container-workloads.adoc#understanding-windows-container-workloads[Understanding Windows container workloads] -* xref:../../windows_containers/enabling-windows-container-workloads.adoc#enabling-windows-container-workloads[Enabling Windows container workloads] -* xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[Installing a cluster on AWS with network customizations] -* xref:../../installing/installing_azure/installing-azure-network-customizations.adoc#installing-azure-network-customizations[Installing a cluster on Azure with network customizations] diff --git a/networking/ovn_kubernetes_network_provider/deploying-egress-router-ovn-redirection.adoc b/networking/ovn_kubernetes_network_provider/deploying-egress-router-ovn-redirection.adoc deleted file mode 100644 index a8b807c732fe..000000000000 --- a/networking/ovn_kubernetes_network_provider/deploying-egress-router-ovn-redirection.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="deploying-egress-router-ovn-redirection"] -= Deploying an egress router pod in redirect mode -include::modules/common-attributes.adoc[] -:context: deploying-egress-router-ovn-redirection - -toc::[] - -As a cluster administrator, you can deploy an egress router pod to redirect traffic to specified destination IP addresses from a reserved source IP address. - -The egress router implementation uses the egress router Container Network Interface (CNI) plug-in. - -:FeatureName: The egress router CNI plug-in -include::modules/technology-preview.adoc[leveloffset=+1] -:!FeatureName: - -// Network attachment definition for egress router in {router-type} mode -include::modules/nw-egress-router-network-attachment.adoc[leveloffset=+1] - -// Egress router pod specification for {router-type} mode -include::modules/nw-egress-router-pod-ovn.adoc[leveloffset=+1] - -// Deploying an egress router pod in {router-type} mode -include::modules/nw-egress-router-redirect-mode-ovn.adoc[leveloffset=+1] diff --git a/networking/ovn_kubernetes_network_provider/disabling-multicast.adoc b/networking/ovn_kubernetes_network_provider/disabling-multicast.adoc deleted file mode 100644 index dbb70680f6c5..000000000000 --- a/networking/ovn_kubernetes_network_provider/disabling-multicast.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="nw-ovn-kubernetes-disabling-multicast"] -= Disabling multicast for a project -include::modules/common-attributes.adoc[] -:context: ovn-kubernetes-disabling-multicast - -toc::[] - -include::modules/nw-disabling-multicast.adoc[leveloffset=+1] - diff --git a/networking/ovn_kubernetes_network_provider/editing-egress-firewall-ovn.adoc b/networking/ovn_kubernetes_network_provider/editing-egress-firewall-ovn.adoc deleted file mode 100644 index 604a8244b951..000000000000 --- a/networking/ovn_kubernetes_network_provider/editing-egress-firewall-ovn.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="editing-egress-firewall-ovn"] -= Editing an egress firewall for a project -include::modules/common-attributes.adoc[] -:context: editing-egress-firewall-ovn - -toc::[] - -As a cluster administrator, you can modify network traffic rules for an existing egress firewall. - -include::modules/nw-egressnetworkpolicy-edit.adoc[leveloffset=+1] diff --git a/networking/ovn_kubernetes_network_provider/enabling-multicast.adoc b/networking/ovn_kubernetes_network_provider/enabling-multicast.adoc deleted file mode 100644 index adb1bf8e25cf..000000000000 --- a/networking/ovn_kubernetes_network_provider/enabling-multicast.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="nw-ovn-kubernetes-enabling-multicast"] -= Enabling multicast for a project -include::modules/common-attributes.adoc[] -:context: ovn-kubernetes-enabling-multicast - -ifeval::["{product-version}" == "4.3"] -:bz: -endif::[] -ifeval::["{product-version}" == "4.4"] -:bz: -endif::[] -ifeval::["{product-version}" == "4.5"] -:bz: -endif::[] - -toc::[] - -ifdef::bz[] -[NOTE] -==== -In {product-title} {product-version}, a bug prevents pods in the same namespace, but assigned to different nodes, from communicating over multicast. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1843695[BZ#1843695]. -==== -endif::bz[] - -include::modules/nw-about-multicast.adoc[leveloffset=+1] -include::modules/nw-enabling-multicast.adoc[leveloffset=+1] - -ifdef::bz[] -:!bz: -endif::bz[] diff --git a/networking/ovn_kubernetes_network_provider/images b/networking/ovn_kubernetes_network_provider/images deleted file mode 120000 index 847b03ed0541..000000000000 --- a/networking/ovn_kubernetes_network_provider/images +++ /dev/null @@ -1 +0,0 @@ -../../images/ \ No newline at end of file diff --git a/networking/ovn_kubernetes_network_provider/migrate-from-openshift-sdn.adoc b/networking/ovn_kubernetes_network_provider/migrate-from-openshift-sdn.adoc deleted file mode 100644 index a33a3a1961d4..000000000000 --- a/networking/ovn_kubernetes_network_provider/migrate-from-openshift-sdn.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="migrate-from-openshift-sdn"] -= Migrate from the OpenShift SDN cluster network provider -include::modules/common-attributes.adoc[] -:context: migrate-from-openshift-sdn - -toc::[] - -As a cluster administrator, you can migrate to the OVN-Kubernetes default Container Network Interface (CNI) network provider from the OpenShift SDN default CNI network provider. - -To learn more about OVN-Kubernetes, read xref:../../networking/ovn_kubernetes_network_provider/about-ovn-kubernetes#about-ovn-kubernetes[About the OVN-Kubernetes network provider]. - -include::modules/nw-ovn-kubernetes-migration-about.adoc[leveloffset=+1] - -include::modules/nw-ovn-kubernetes-migration.adoc[leveloffset=+1] - -[id="migrate-from-openshift-sdn-additional-resources"] -== Additional resources - -* xref:../../networking/cluster-network-operator.adoc#nw-operator-configuration-parameters-for-ovn-sdn_cluster-network-operator[Configuration parameters for the OVN-Kubernetes default CNI network provider] -* xref:../../backup_and_restore/backing-up-etcd.adoc#backup-etcd[Backing up etcd] -* xref:../../networking/network_policy/about-network-policy.adoc#about-network-policy[About network policy] -* OVN-Kubernetes capabilities -- xref:../../networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc#configuring-egress-ips-ovn[Configuring an egress IP address] -- xref:../../networking/ovn_kubernetes_network_provider/configuring-egress-firewall-ovn.adoc#configuring-egress-firewall-ovn[Configuring an egress firewall for a project] -- xref:../../networking/ovn_kubernetes_network_provider/enabling-multicast.adoc#nw-ovn-kubernetes-enabling-multicast[Enabling multicast for a project] -* OpenShift SDN capabilities -- xref:../../networking/openshift_sdn/assigning-egress-ips.adoc#assigning-egress-ips[Configuring egress IPs for a project] -- xref:../../networking/openshift_sdn/configuring-egress-firewall.adoc#configuring-egress-firewall[Configuring an egress firewall for a project] -- xref:../../networking/openshift_sdn/enabling-multicast.adoc#enabling-multicast[Enabling multicast for a project] -* xref:../../rest_api/operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[Network [operator.openshift.io/v1]] diff --git a/networking/ovn_kubernetes_network_provider/removing-egress-firewall-ovn.adoc b/networking/ovn_kubernetes_network_provider/removing-egress-firewall-ovn.adoc deleted file mode 100644 index 4278f5bce458..000000000000 --- a/networking/ovn_kubernetes_network_provider/removing-egress-firewall-ovn.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="removing-egress-firewall-ovn"] -= Removing an egress firewall from a project -include::modules/common-attributes.adoc[] -:context: removing-egress-firewall-ovn - -toc::[] - -As a cluster administrator, you can remove an egress firewall from a project to remove all restrictions on network traffic from the project that leaves the {product-title} cluster. - -include::modules/nw-egressnetworkpolicy-delete.adoc[leveloffset=+1] diff --git a/networking/ovn_kubernetes_network_provider/rollback-to-openshift-sdn.adoc b/networking/ovn_kubernetes_network_provider/rollback-to-openshift-sdn.adoc deleted file mode 100644 index d082fc1dcd55..000000000000 --- a/networking/ovn_kubernetes_network_provider/rollback-to-openshift-sdn.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="rollback-to-openshift-sdn"] -= Rollback to the OpenShift SDN network provider -include::modules/common-attributes.adoc[] -:context: rollback-to-openshift-sdn - -toc::[] - -As a cluster administrator, you can rollback to the OpenShift SDN cluster default Container Network Interface (CNI) provider from the OVN-Kubernetes default CNI network provider if the migration to OVN-Kubernetes unsuccessful. - -include::modules/nw-ovn-kubernetes-rollback.adoc[leveloffset=+1] diff --git a/networking/ovn_kubernetes_network_provider/using-an-egress-router-ovn.adoc b/networking/ovn_kubernetes_network_provider/using-an-egress-router-ovn.adoc deleted file mode 100644 index 39035d9a69e3..000000000000 --- a/networking/ovn_kubernetes_network_provider/using-an-egress-router-ovn.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="using-an-egress-router-ovn"] -= Considerations for the use of an egress router pod -include::modules/common-attributes.adoc[] -:context: using-an-egress-router-ovn - -toc::[] - -// About an egress router pod -include::modules/nw-egress-router-about.adoc[leveloffset=+1] - -[id="using-an-egress-router-ovn-additional-resources"] -== Additional resources - -- xref:../../networking/ovn_kubernetes_network_provider/deploying-egress-router-ovn-redirection.adoc#deploying-egress-router-ovn-redirection[Deploying an egress router in redirection mode] diff --git a/networking/ovn_kubernetes_network_provider/viewing-egress-firewall-ovn.adoc b/networking/ovn_kubernetes_network_provider/viewing-egress-firewall-ovn.adoc deleted file mode 100644 index 0d4cf54cd4a3..000000000000 --- a/networking/ovn_kubernetes_network_provider/viewing-egress-firewall-ovn.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="viewing-egress-firewall-ovn"] -= Viewing an egress firewall for a project -include::modules/common-attributes.adoc[] -:context: viewing-egress-firewall-ovn - -toc::[] - -As a cluster administrator, you can list the names of any existing egress firewalls and view the traffic rules for a specific egress firewall. - -include::modules/nw-egressnetworkpolicy-view.adoc[leveloffset=+1] diff --git a/networking/routes/route-configuration.adoc b/networking/routes/route-configuration.adoc deleted file mode 100644 index 0c7aac089a89..000000000000 --- a/networking/routes/route-configuration.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Assembly filename:route-configuration.adoc -// Explains route configuration. -[id="route-configuration"] -= Route configuration -include::modules/common-attributes.adoc[] -:context: route-configuration - -toc::[] - -//Creating route timeouts -include::modules/nw-configuring-route-timeouts.adoc[leveloffset=+1] -// -//Enabling HTTP Strict Transport Security -include::modules/nw-enabling-hsts.adoc[leveloffset=+1] -// -//Troubleshooting Throughput Issues -include::modules/nw-throughput-troubleshoot.adoc[leveloffset=+1] -// -//Using cookies to keep route statefulness -include::modules/nw-using-cookies-keep-route-statefulness.adoc[leveloffset=+1] -include::modules/nw-annotating-a-route-with-a-cookie-name.adoc[leveloffset=+2] - -include::modules/nw-path-based-routes.adoc[leveloffset=+1] - -include::modules/nw-route-specific-annotations.adoc[leveloffset=+1] - -include::modules/nw-route-admission-policy.adoc[leveloffset=+1] - -include::modules/nw-ingress-creating-a-route-via-an-ingress.adoc[leveloffset=+1] diff --git a/networking/routes/secured-routes.adoc b/networking/routes/secured-routes.adoc deleted file mode 100644 index 520704cd6763..000000000000 --- a/networking/routes/secured-routes.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="configuring-default-certificate"] -= Secured routes -include::modules/common-attributes.adoc[] -:context: secured-routes - -toc::[] - -Secure routes provide the ability to use several types of TLS termination to serve certificates to the client. The following sections describe how to create re-encrypt, edge, and passthrough routes with custom certificates. - -[IMPORTANT] -==== -If you create routes in Microsoft Azure through public endpoints, the resource -names are subject to restriction. You cannot create resources that use certain -terms. For a list of terms that Azure restricts, see -link:https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-reserved-resource-name[Resolve reserved resource name errors] -in the Azure documentation. -==== - -include::modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc[leveloffset=+1] - -include::modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc[leveloffset=+1] - -include::modules/nw-ingress-creating-a-passthrough-route.adoc[leveloffset=+1] diff --git a/networking/understanding-networking.adoc b/networking/understanding-networking.adoc deleted file mode 100644 index 9ae5f569b39f..000000000000 --- a/networking/understanding-networking.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="understanding-networking"] -= Understanding networking -include::modules/common-attributes.adoc[] -:context: understanding-networking - -toc::[] - -Kubernetes ensures that pods are able to network with each other, and allocates -each pod an IP address from an internal network. This ensures all containers -within the pod behave as if they were on the same host. Giving each pod its own -IP address means that pods can be treated like physical hosts or virtual -machines in terms of port allocation, networking, naming, service discovery, -load balancing, application configuration, and migration. - -[NOTE] -==== -Some cloud platforms offer metadata APIs that listen on the 169.254.169.254 IP address, a link-local IP address in the IPv4 `169.254.0.0/16` CIDR block. - -This CIDR block is not reachable from the pod network. Pods that need access to these IP addresses must be given host network access by setting the `spec.hostNetwork` field in the pod spec to `true`. - -If you allow a pod host network access, you grant the pod privileged access to the underlying network infrastructure. -==== - -include::modules/nw-ne-openshift-dns.adoc[leveloffset=+1] diff --git a/networking/using-cookies-to-keep-route-statefulness.adoc b/networking/using-cookies-to-keep-route-statefulness.adoc deleted file mode 100644 index e7030ff2e4a8..000000000000 --- a/networking/using-cookies-to-keep-route-statefulness.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="using-cookies-to-keep-route-statefulness"] -= Using cookies to keep route statefulness -{product-author} -{product-version} -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title: -:prewrap!: -:context: using-cookies-to-keep-route-statefulness - -toc::[] - -{product-title} provides sticky sessions, which enables stateful application -traffic by ensuring all traffic hits the same endpoint. However, if the endpoint -pod terminates, whether through restart, scaling, or a change in configuration, -this statefulness can disappear. - -{product-title} can use cookies to configure session persistence. The router -selects an endpoint to handle any user requests, and creates a cookie for the -session. The cookie is passed back in the response to the request and the user -sends the cookie back with the next request in the session. The cookie tells the -router which endpoint is handling the session, ensuring that client requests use -the cookie so that they are routed to the same pod. - -include::modules/annotating-a-route-with-a-cookie-name.adoc[leveloffset=+1] diff --git a/networking/using-sctp.adoc b/networking/using-sctp.adoc deleted file mode 100644 index 8449e6e1d686..000000000000 --- a/networking/using-sctp.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="using-sctp"] -= Using the Stream Control Transmission Protocol (SCTP) on a bare metal cluster -include::modules/common-attributes.adoc[] -:context: using-sctp - -toc::[] - -As a cluster administrator, you can use the Stream Control Transmission Protocol (SCTP) on a cluster. - -include::modules/nw-sctp-about.adoc[leveloffset=+1] - -include::modules/nw-sctp-enabling.adoc[leveloffset=+1] - -include::modules/nw-sctp-verifying.adoc[leveloffset=+1] diff --git a/networking/verifying-connectivity-endpoint.adoc b/networking/verifying-connectivity-endpoint.adoc deleted file mode 100644 index 73a1f2688429..000000000000 --- a/networking/verifying-connectivity-endpoint.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="verifying-connectivity-endpoint"] -= Verifying connectivity to an endpoint -include::modules/common-attributes.adoc[] -:context: verifying-connectivity-endpoint - -toc::[] - -The Cluster Network Operator (CNO) runs a controller, the connectivity check controller, that performs a connection health check between resources within your cluster. -By reviewing the results of the health checks, you can diagnose connection problems or eliminate network connectivity as the cause of an issue that you are investigating. - -include::modules/nw-pod-network-connectivity-checks.adoc[leveloffset=+1] -include::modules/nw-pod-network-connectivity-implementation.adoc[leveloffset=+1] -include::modules/nw-pod-network-connectivity-check-object.adoc[leveloffset=+1] -include::modules/nw-pod-network-connectivity-verify.adoc[leveloffset=+1] diff --git a/nodes/clusters/nodes-cluster-enabling-features.adoc b/nodes/clusters/nodes-cluster-enabling-features.adoc deleted file mode 100644 index 6a29a997b352..000000000000 --- a/nodes/clusters/nodes-cluster-enabling-features.adoc +++ /dev/null @@ -1,15 +0,0 @@ -:context: nodes-cluster-enabling -[id="nodes-cluster-enabling"] -= Enabling features using feature gates -include::modules/common-attributes.adoc[] - -toc::[] - -As an administrator, you can turn on features that are in Technology Preview -status. - -include::modules/nodes-cluster-features-about.adoc[leveloffset=+1] - -include::modules/feature-gate-features.adoc[leveloffset=+1] - -include::modules/nodes-cluster-enabling-features-cluster.adoc[leveloffset=+1] diff --git a/nodes/clusters/nodes-cluster-limit-ranges.adoc b/nodes/clusters/nodes-cluster-limit-ranges.adoc deleted file mode 100644 index ddef054a5363..000000000000 --- a/nodes/clusters/nodes-cluster-limit-ranges.adoc +++ /dev/null @@ -1,39 +0,0 @@ -:context: nodes-cluster-limit-ranges -[id="nodes-cluster-limit-ranges"] -= Restrict resource consumption with limit ranges -include::modules/common-attributes.adoc[] - -toc::[] - - -By default, containers run with unbounded compute resources on an {product-title} -cluster. With limit ranges, you can restrict resource consumption for specific -objects in a project: - -* pods and containers: You can set minimum and maximum requirements for CPU and -memory for pods and their containers. -* Image streams: You can set limits on the number of images and tags in an -`ImageStream` object. -* Images: You can limit the size of images that can be pushed to an internal -registry. -* Persistent volume claims (PVC): You can restrict the size of the PVCs that can -be requested. - -If a pod does not meet the constraints imposed by the limit -range, the pod cannot be created in the namespace. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/nodes-cluster-limit-ranges-about.adoc[leveloffset=+1] - -include::modules/nodes-cluster-limit-ranges-limits.adoc[leveloffset=+2] - -include::modules/nodes-cluster-limit-ranges-creating.adoc[leveloffset=+1] - -include::modules/nodes-cluster-limit-ranges-viewing.adoc[leveloffset=+1] - -include::modules/nodes-cluster-limit-ranges-deleting.adoc[leveloffset=+1] diff --git a/nodes/clusters/nodes-cluster-overcommit.adoc b/nodes/clusters/nodes-cluster-overcommit.adoc deleted file mode 100644 index 6dad54743c5f..000000000000 --- a/nodes/clusters/nodes-cluster-overcommit.adoc +++ /dev/null @@ -1,80 +0,0 @@ -:context: nodes-cluster-overcommit -[id="nodes-cluster-overcommit"] -= Configuring your cluster to place pods on overcommitted nodes -include::modules/common-attributes.adoc[] - -toc::[] - - - - - - -In an _overcommitted_ state, the sum of the container compute resource requests -and limits exceeds the resources available on the system. For example, you might -want to use overcommitment in development environments where a trade-off of -guaranteed performance for capacity is acceptable. - -Containers can specify compute resource requests and limits. Requests are used -for scheduling your container and provide a minimum service guarantee. Limits -constrain the amount of compute resource that can be consumed on your node. - -The scheduler attempts to optimize the compute resource use across all nodes -in your cluster. It places pods onto specific nodes, taking the pods' compute -resource requests and nodes' available capacity into consideration. - -{product-title} administrators can control the level of overcommit and manage -container density on nodes. You can configure cluster-level overcommit using -the xref:#nodes-cluster-resource-override_nodes-cluster-overcommit[ClusterResourceOverride Operator] -to override the ratio between requests and limits set on developer containers. -In conjunction with xref:#nodes-cluster-node-overcommit_nodes-cluster-overcommit[node overcommit] and -xref:../../applications/deployments/managing-deployment-processes.adoc#deployments-setting-resources_deployment-operations[project memory and CPU limits and defaults], you can adjust the resource limit and request to achieve the desired level of overcommit. - -[NOTE] -==== -In {product-title}, you must enable cluster-level overcommit. Node overcommitment is enabled by default. -See xref:#nodes-cluster-overcommit-node-disable_nodes-cluster-overcommit[Disabling overcommitment for a node]. -==== - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/nodes-cluster-overcommit-resource-requests.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-override.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-override-deploy-console.adoc[leveloffset=+2] - -include::modules/nodes-cluster-resource-override-deploy-cli.adoc[leveloffset=+2] - -include::modules/nodes-cluster-resource-configure.adoc[leveloffset=+2] - -include::modules/nodes-cluster-node-overcommit.adoc[leveloffset=+1] - -include::modules/nodes-cluster-overcommit-resources-containers.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-qos-about.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-configure-nodes.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-node-enforcing.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-node-resources.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-node-disable.adoc[leveloffset=+2] - -include::modules/nodes-cluster-project-overcommit.adoc[leveloffset=+1] - -include::modules/nodes-cluster-overcommit-project-disable.adoc[leveloffset=+2] - -[id="nodes-cluster-overcommit-addtl-resources"] -== Additional resources - -For information setting per-project resource limits, see -xref:../../applications/deployments/managing-deployment-processes.adoc#deployments-triggers_deployment-operations[Setting deployment resources]. - - - diff --git a/nodes/clusters/nodes-cluster-pods-configuring.adoc b/nodes/clusters/nodes-cluster-pods-configuring.adoc deleted file mode 100644 index ea40f25e8fef..000000000000 --- a/nodes/clusters/nodes-cluster-pods-configuring.adoc +++ /dev/null @@ -1,31 +0,0 @@ -:context: nodes-cluster-pods -[id="nodes-cluster-pods-configuring"] -= Configuring an {product-title} cluster for pods -include::modules/common-attributes.adoc[] - -toc::[] - -As an administrator, you can create and maintain an efficient cluster for pods. - -By keeping your cluster efficient, you can provide a better environment for your developers using -such tools as what a pod does when it exits, ensuring that the required number of pods is always running, -when to restart pods designed to run only once, limit the bandwidth available to pods, and how to keep -pods running during disruptions. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-configuring-restart.adoc[leveloffset=+1] - -include::modules/nodes-pods-configuring-bandwidth.adoc[leveloffset=+1] - -include::modules/nodes-pods-pod-disruption-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-pod-disruption-configuring.adoc[leveloffset=+2] - -include::modules/nodes-pods-configuring-pod-critical.adoc[leveloffset=+1] - -// modules/nodes-pods-configuring-run-once.adoc[leveloffset=+1] - diff --git a/nodes/clusters/nodes-cluster-resource-configure.adoc b/nodes/clusters/nodes-cluster-resource-configure.adoc deleted file mode 100644 index 9b1306f85271..000000000000 --- a/nodes/clusters/nodes-cluster-resource-configure.adoc +++ /dev/null @@ -1,38 +0,0 @@ -:context: nodes-cluster-resource-configure -[id="nodes-cluster-resource-configure"] -= Configuring cluster memory to meet container memory and risk requirements -include::modules/common-attributes.adoc[] - -toc::[] - - - -As a cluster administrator, you can help your clusters operate efficiently through -managing application memory by: - -* Determining the memory and risk requirements of a containerized application - component and configuring the container memory parameters to suit those - requirements. - -* Configuring containerized application runtimes (for example, OpenJDK) to adhere - optimally to the configured container memory parameters. - -* Diagnosing and resolving memory-related error conditions associated with - running in a container. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-cluster-resource-configure-about.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-configure-jdk.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-configure-request-limit.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-configure-oom.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-configure-evicted.adoc[leveloffset=+1] - - diff --git a/nodes/clusters/nodes-cluster-resource-levels.adoc b/nodes/clusters/nodes-cluster-resource-levels.adoc deleted file mode 100644 index 1ca020764b98..000000000000 --- a/nodes/clusters/nodes-cluster-resource-levels.adoc +++ /dev/null @@ -1,27 +0,0 @@ -:context: nodes-cluster-resource-levels -[id="nodes-cluster-resource-levels"] -= Estimating the number of pods your {product-title} nodes can hold -include::modules/common-attributes.adoc[] - -toc::[] - - - -As a cluster administrator, you can use the cluster capacity tool to view the -number of pods that can be scheduled to increase the current resources before -they become exhausted, and to ensure any future pods can be scheduled. This -capacity comes from an individual node host in a cluster, and includes CPU, -memory, disk space, and others. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-cluster-resource-levels-about.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-levels-command.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-levels-job.adoc[leveloffset=+1] - - diff --git a/nodes/clusters/nodes-containers-events.adoc b/nodes/clusters/nodes-containers-events.adoc deleted file mode 100644 index 7e8a967e9f82..000000000000 --- a/nodes/clusters/nodes-containers-events.adoc +++ /dev/null @@ -1,25 +0,0 @@ -:context: nodes-containers-events -[id="nodes-containers-events"] -= Viewing system event information in an {product-title} cluster -include::modules/common-attributes.adoc[] - -toc::[] - - - - - -Events in {product-title} are modeled based on events that happen to API objects -in an {product-title} cluster. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-events-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-events-viewing.adoc[leveloffset=+1] - -include::modules/nodes-containers-events-list.adoc[leveloffset=+1] diff --git a/nodes/containers/nodes-containers-copying-files.adoc b/nodes/containers/nodes-containers-copying-files.adoc deleted file mode 100644 index cc311f5db963..000000000000 --- a/nodes/containers/nodes-containers-copying-files.adoc +++ /dev/null @@ -1,26 +0,0 @@ -:context: nodes-containers-copying-files -[id="nodes-containers-copying-files"] -= Copying files to or from an {product-title} container -include::modules/common-attributes.adoc[] - -toc::[] - - - - - - -You can use the CLI to copy local files to or from a remote directory in a container -using the `rsync` command. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-copying-files-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-copying-files-procedure.adoc[leveloffset=+1] - -include::modules/nodes-containers-copying-files-rsync.adoc[leveloffset=+1] - diff --git a/nodes/containers/nodes-containers-downward-api.adoc b/nodes/containers/nodes-containers-downward-api.adoc deleted file mode 100644 index f411cddab73e..000000000000 --- a/nodes/containers/nodes-containers-downward-api.adoc +++ /dev/null @@ -1,45 +0,0 @@ -:context: nodes-containers-downward-api -[id="nodes-containers-downward-api"] -= Allowing containers to consume API objects -include::modules/common-attributes.adoc[] - -toc::[] - - - - - -The _Downward API_ is a mechanism that allows containers to consume information -about API objects without coupling to {product-title}. -Such information includes the pod’s name, namespace, and resource values. -Containers can consume information from the downward API using environment -variables or a volume plug-in. - - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-downward-api-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-downward-api-container-values.adoc[leveloffset=+1] - -include::modules/nodes-containers-downward-api-container-values-envars.adoc[leveloffset=+2] - -include::modules/nodes-containers-downward-api-container-values-plugin.adoc[leveloffset=+2] - -include::modules/nodes-containers-downward-api-container-resources.adoc[leveloffset=+1] - -include::modules/nodes-containers-downward-api-container-resources-envars.adoc[leveloffset=+2] - -include::modules/nodes-containers-downward-api-container-resources-plugin.adoc[leveloffset=+2] - -include::modules/nodes-containers-downward-api-container-secrets.adoc[leveloffset=+1] - -include::modules/nodes-containers-downward-api-container-configmaps.adoc[leveloffset=+1] - -include::modules/nodes-containers-downward-api-container-envars.adoc[leveloffset=+1] - -include::modules/nodes-containers-downward-api-container-escaping.adoc[leveloffset=+1] diff --git a/nodes/containers/nodes-containers-init.adoc b/nodes/containers/nodes-containers-init.adoc deleted file mode 100644 index 39f9be81836a..000000000000 --- a/nodes/containers/nodes-containers-init.adoc +++ /dev/null @@ -1,23 +0,0 @@ -:context: nodes-containers-init -[id="nodes-containers-init"] -= Using Init Containers to perform tasks before a pod is deployed -include::modules/common-attributes.adoc[] - -toc::[] - - - - -{product-title} provides _init containers_, which are specialized containers -that run before application containers and can contain utilities or setup scripts not present in an app image. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-init-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-init-creating.adoc[leveloffset=+1] - - diff --git a/nodes/containers/nodes-containers-port-forwarding.adoc b/nodes/containers/nodes-containers-port-forwarding.adoc deleted file mode 100644 index fbbc410a39fc..000000000000 --- a/nodes/containers/nodes-containers-port-forwarding.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:context: nodes-containers-port-forwarding -[id="nodes-containers-port-forwarding"] -= Using port forwarding to access applications in a container -include::modules/common-attributes.adoc[] - -toc::[] - - - - - -{product-title} supports port forwarding to pods. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-port-forwarding-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-port-forwarding-using.adoc[leveloffset=+1] - -include::modules/nodes-containers-port-forwarding-protocol.adoc[leveloffset=+1] diff --git a/nodes/containers/nodes-containers-projected-volumes.adoc b/nodes/containers/nodes-containers-projected-volumes.adoc deleted file mode 100644 index 6433b6c05a57..000000000000 --- a/nodes/containers/nodes-containers-projected-volumes.adoc +++ /dev/null @@ -1,37 +0,0 @@ -:context: nodes-containers-projected-volumes -[id="nodes-containers-projected-volumes"] -= Mapping volumes using projected volumes -include::modules/common-attributes.adoc[] - -toc::[] - - - - - - -A _projected volume_ maps several existing volume sources into the same directory. - -The following types of volume sources can be projected: - -* Secrets - -* Config Maps - -* Downward API - -[NOTE] -==== -All sources are required to be in the same namespace as the pod. -==== - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-projected-volumes-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-projected-volumes-creating.adoc[leveloffset=+1] - - diff --git a/nodes/containers/nodes-containers-remote-commands.adoc b/nodes/containers/nodes-containers-remote-commands.adoc deleted file mode 100644 index 22480e967e64..000000000000 --- a/nodes/containers/nodes-containers-remote-commands.adoc +++ /dev/null @@ -1,22 +0,0 @@ -:context: nodes-containers-remote-commands -[id="nodes-containers-remote-commands"] -= Executing remote commands in an {product-title} container -include::modules/common-attributes.adoc[] - -toc::[] - - - - - -You can use the CLI to execute remote commands in an {product-title} container. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-remote-commands-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-remote-commands-protocol.adoc[leveloffset=+1] - diff --git a/nodes/containers/nodes-containers-sysctls.adoc b/nodes/containers/nodes-containers-sysctls.adoc deleted file mode 100644 index 2cbb69d921ae..000000000000 --- a/nodes/containers/nodes-containers-sysctls.adoc +++ /dev/null @@ -1,29 +0,0 @@ -:context: nodes-containers-using -[id="nodes-containers-sysctls"] -= Using sysctls in containers -include::modules/common-attributes.adoc[] - -toc::[] - - - - -Sysctl settings are exposed via Kubernetes, allowing users to modify certain -kernel parameters at runtime for namespaces within a container. Only sysctls -that are namespaced can be set independently on pods. If a sysctl is not -namespaced, called _node-level_, it cannot be set within {product-title}. -Moreover, only those sysctls considered _safe_ are whitelisted by default; you -can manually enable other _unsafe_ sysctls on the node to be available to the -user. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-sysctls-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-sysctls-setting.adoc[leveloffset=+1] - -include::modules/nodes-containers-sysctls-unsafe.adoc[leveloffset=+1] diff --git a/nodes/containers/nodes-containers-using.adoc b/nodes/containers/nodes-containers-using.adoc deleted file mode 100644 index 22f9b0abd063..000000000000 --- a/nodes/containers/nodes-containers-using.adoc +++ /dev/null @@ -1,48 +0,0 @@ -:context: nodes-containers-using -[id="nodes-containers-using"] -= Understanding Containers -include::modules/common-attributes.adoc[] - -toc::[] - - - - -The basic units of {product-title} applications are called _containers_. -link:https://access.redhat.com/articles/1353593[Linux container technologies] -are lightweight mechanisms for isolating running processes so that they are -limited to interacting with only their designated resources. - -Many application instances can be running in containers on a single host without -visibility into each others' processes, files, network, and so on. Typically, -each container provides a single service (often called a "micro-service"), such -as a web server or a database, though containers can be used for arbitrary -workloads. - -The Linux kernel has been incorporating capabilities for container technologies -for years. {product-title} and -Kubernetes add the ability to orchestrate containers across -multi-host installations. - -[discrete] -[id="nodes-containers-memory"] -== About containers and RHEL kernel memory - -Due to Red Hat Enterprise Linux (RHEL) behavior, a container on a node with high CPU usage might seem to consume more memory than expected. The higher memory consumption could be caused by the `kmem_cache` in the RHEL kernel. The RHEL kernel creates a `kmem_cache` for each cgroup. For added performance, the `kmem_cache` contains a `cpu_cache`, and a node cache for any NUMA nodes. These caches all consume kernel memory. - -The amount of memory stored in those caches is proportional to the number of CPUs that the system uses. As a result, a higher number of CPUs results in a greater amount of kernel memory being held in these caches. Higher amounts of kernel memory in these caches can cause {product-title} containers to exceed the configured memory limits, resulting in the container being killed. - -To avoid losing containers due to kernel memory issues, ensure that the containers request sufficient memory. You can use the following formula to estimate the amount of memory consumed by the `kmem_cache`, where `nproc` is the number of process reported by the `nproc` command. The lower limit of container requests should be this value plus the container memory requirements: - -[source,terminal] ----- -$(nproc) X 1/2 MiB ----- - - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - diff --git a/nodes/containers/nodes-containers-volumes.adoc b/nodes/containers/nodes-containers-volumes.adoc deleted file mode 100644 index 505f6133954b..000000000000 --- a/nodes/containers/nodes-containers-volumes.adoc +++ /dev/null @@ -1,33 +0,0 @@ -:context: nodes-containers-volumes -[id="nodes-containers-volumes"] -= Using volumes to persist container data -include::modules/common-attributes.adoc[] - -toc::[] - - - - -Files in a container are ephemeral. As such, when a container crashes or stops, the data is lost. -You can use _volumes_ to persist the data used by the containers in a pod. A volume is directory, accessible to the Containers in a pod, where data is stored for the life of the pod. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-containers-volumes-about.adoc[leveloffset=+1] - -include::modules/nodes-containers-volumes-cli.adoc[leveloffset=+1] - -include::modules/nodes-containers-volumes-listing.adoc[leveloffset=+1] - -include::modules/nodes-containers-volumes-adding.adoc[leveloffset=+1] - -include::modules/nodes-containers-volumes-updating.adoc[leveloffset=+1] - -include::modules/nodes-containers-volumes-removing.adoc[leveloffset=+1] - -include::modules/nodes-containers-volumes-subpath.adoc[leveloffset=+1] - - diff --git a/nodes/edge/nodes-edge-remote-workers.adoc b/nodes/edge/nodes-edge-remote-workers.adoc deleted file mode 100644 index 1034ff20e6da..000000000000 --- a/nodes/edge/nodes-edge-remote-workers.adoc +++ /dev/null @@ -1,57 +0,0 @@ -:context: nodes-edge-remote-workers -[id="nodes-edge-remote-workers"] -= Using remote worker nodes at the network edge -include::modules/common-attributes.adoc[] - -toc::[] - - -You can configure {product-title} clusters with nodes located at your network edge. In this topic, they are called _remote worker nodes_. A typical cluster with remote worker nodes combines on-premise master and worker nodes with worker nodes in other locations that connect to the cluster. This topic is intended to provide guidance on best practices for using remote worker nodes and does not contain specific configuration details. - -There are multiple use cases across different industries, such as telecommunications, retail, manufacturing, and government, for using a deployment pattern with remote worker nodes. For example, you can separate and isolate your projects and workloads by combining the remote worker nodes into xref:../../nodes/edge/nodes-edge-remote-workers.adoc#nodes-edge-remote-workers-strategies-zones_nodes-edge-remote-workers[Kubernetes zones]. - -However, having remote worker nodes can introduce higher latency, intermittent loss of network connectivity, and other issues. Among the challenges in a cluster with remote worker node are: - -* *Network separation*: The {product-title} control plane and the remote worker nodes must be able communicate with each other. Because of the distance between the control plane and the remote worker nodes, network issues could prevent this communication. See xref:../../nodes/edge/nodes-edge-remote-workers.adoc#nodes-edge-remote-workers-network_nodes-edge-remote-workers[Network separation with remote worker nodes] for information on how {product-title} responds to network separation and for methods to diminish the impact to your cluster. - -* *Power outage*: Because the control plane and remote worker nodes are in separate locations, a power outage at the remote location or at any point between the two can negatively impact your cluster. See xref:../../nodes/edge/nodes-edge-remote-workers.adoc#nodes-edge-remote-workers-power_nodes-edge-remote-workers[Power loss on remote worker nodes] for information on how {product-title} responds to a node losing power and for methods to diminish the impact to your cluster. - -* *Latency spikes or temporary reduction in throughput*: As with any network, any changes in network conditions between your cluster and the remote worker nodes can negatively impact your cluster. These types of situations are beyond the scope of this documentation. - -Note the following limitations when planning a cluster with remote worker nodes: - -* Remote worker nodes are supported on only bare metal clusters with user-provisioned infrastructure. - -* {product-title} does not support remote worker nodes that use a different cloud provider than the on-premise cluster uses. - -* Moving workloads from one Kubernetes zone to a different Kubernetes zone can be problematic due to system and environment issues, such as a specific type of memory not being available in a different zone. - -* Proxies and firewalls can present additional limitations that are beyond the scope of this document. Refer to the relevant {product-title} documentation for how to address such limitations, such as xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[Configuring your firewall]. - -* You are responsible for configuring and maintaining L2/L3-level network connectivity between the control plane and the network-edge nodes. - -include::modules/nodes-edge-remote-workers-network.adoc[leveloffset=+1] - -For more information on using these objects in a cluster with remote worker nodes, see xref:../../nodes/edge/nodes-edge-remote-workers.html#nodes-edge-remote-workers-strategies_nodes-edge-remote-workers[About remote worker node strategies]. - -include::modules/nodes-edge-remote-workers-power.adoc[leveloffset=+1] - -For more information on using these objects in a cluster with remote worker nodes, see xref:../../nodes/edge/nodes-edge-remote-workers.html#nodes-edge-remote-workers-strategies_nodes-edge-remote-workers[About remote worker node strategies]. - -include::modules/nodes-edge-remote-workers-strategies.adoc[leveloffset=+1] - -.Additional resources - -* For more information on Daemonesets, see xref:../../nodes/jobs/nodes-pods-daemonsets.adoc#nodes-pods-daemonsets[DaemonSets]. - -* For more information on taints and tolerations, see xref:../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations-about_nodes-scheduler-taints-tolerations[Controlling pod placement using node taints]. - -* For more information on configuring `KubeletConfig` objects, see xref:../../post_installation_configuration/node-tasks.adoc#create-a-kubeletconfig-crd-to-edit-kubelet-parameters_post-install-node-tasks[Creating a KubeletConfig CRD]. - -* For more information on replica sets, see xref:../../applications/deployments/what-deployments-are.html#deployments-repliasets_what-deployments-are[ReplicaSets]. - -* For more information on deployments, see xref:../../applications/deployments/what-deployments-are.html#deployments-kube-deployments_what-deployments-are[Deployments]. - -* For more information on replication controllers, see xref:../../applications/deployments/what-deployments-are.html#deployments-replicationcontrollers_what-deployments-are[Replication controllers]. - -* For more information on the controller manager, see xref:../../operators/operator-reference.html#kube-controller-manager-operator_red-hat-operators[Kubernetes Controller Manager Operator]. diff --git a/nodes/images b/nodes/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/nodes/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/nodes/jobs/nodes-nodes-jobs.adoc b/nodes/jobs/nodes-nodes-jobs.adoc deleted file mode 100644 index def2a9af3564..000000000000 --- a/nodes/jobs/nodes-nodes-jobs.adoc +++ /dev/null @@ -1,60 +0,0 @@ - -:context: nodes-nodes-jobs -[id="nodes-nodes-jobs"] -= Running tasks in pods using jobs -include::modules/common-attributes.adoc[] - -toc::[] - - -A _job_ executes a task in your {product-title} cluster. - -A job tracks the overall progress of a task and updates its status with information -about active, succeeded, and failed pods. Deleting a job will clean up any pod -replicas it created. Jobs are part of the Kubernetes API, which can be managed -with `oc` commands like other object types. - -.Sample Job specification - -[source,yaml] ----- -apiVersion: batch/v1 -kind: Job -metadata: - name: pi -spec: - parallelism: 1 <1> - completions: 1 <2> - activeDeadlineSeconds: 1800 <3> - backoffLimit: 6 <4> - template: <5> - metadata: - name: pi - spec: - containers: - - name: pi - image: perl - command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"] - restartPolicy: OnFailure <6> ----- -1. The pod replicas a job should run in parallel. -2. Successful pod completions are needed to mark a job completed. -3. The maximum duration the job can run. -4. The number of retries for a job. -5. The template for the pod the controller creates. -6. The restart policy of the pod. - -See the http://kubernetes.io/docs/user-guide/jobs/[Kubernetes documentation] for -more information about jobs. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-jobs-about.adoc[leveloffset=+1] - -include::modules/nodes-nodes-jobs-creating.adoc[leveloffset=+1] - -include::modules/nodes-nodes-jobs-creating-cron.adoc[leveloffset=+1] - diff --git a/nodes/jobs/nodes-pods-daemonsets.adoc b/nodes/jobs/nodes-pods-daemonsets.adoc deleted file mode 100644 index c7abd2df206c..000000000000 --- a/nodes/jobs/nodes-pods-daemonsets.adoc +++ /dev/null @@ -1,58 +0,0 @@ -:context: nodes-pods-daemonsets -[id="nodes-pods-daemonsets"] -= Running background tasks on nodes automatically with daemon sets -include::modules/common-attributes.adoc[] - -toc::[] - -As an administrator, you can create and use daemon sets to run replicas of a pod on specific or all nodes in an {product-title} cluster. - -A daemon set ensures that all (or some) nodes run a copy of a pod. As nodes are added to the cluster, pods are added to the cluster. -As nodes are removed from the cluster, those pods are removed through garbage collection. Deleting a daemon set will clean up the pods it created. - -You can use daemon sets to create shared storage, run a logging pod on every node in -your cluster, or deploy a monitoring agent on every node. - -For security reasons, only cluster administrators can create daemon sets. - -For more information on daemon sets, see the link:http://kubernetes.io/docs/admin/daemons/[Kubernetes documentation]. - -[IMPORTANT] -==== -Daemon set scheduling is incompatible with project's default node selector. -If you fail to disable it, the daemon set gets restricted by merging with the -default node selector. This results in frequent pod recreates on the nodes that -got unselected by the merged node selector, which in turn puts unwanted load on -the cluster. -==== - -== Scheduled by default scheduler - -A daemon set ensures that all eligible nodes run a copy of a pod. Normally, the node that a pod runs on is selected by the Kubernetes scheduler. However, previously daemon set pods are created and scheduled by the daemon set controller. That introduces the following issues: - -* Inconsistent pod behavior: Normal pods waiting to be scheduled are created and in Pending state, but daemon set pods are not created in `Pending` state. This is confusing to the user. -* Pod preemption is handled by default scheduler. When preemption is enabled, the daemon set controller will make scheduling decisions without considering pod priority and preemption. - -The *ScheduleDaemonSetPods* feature, enabled by default in {product-title}, lets you to schedule daemon sets using the default scheduler instead of the daemon set controller, by adding the `NodeAffinity` term to the daemon set pods, instead of the `spec.nodeName` term. The default scheduler is then used to bind the pod to the target host. If node affinity of the daemon set pod already exists, it is replaced. The daemon set controller only performs these operations when creating or modifying daemon set pods, and no changes are made to the `spec.template` of the daemon set. - -[source,yaml] ----- -nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchFields: - - key: metadata.name - operator: In - values: - - target-host-name ----- - -In addition, a `node.kubernetes.io/unschedulable:NoSchedule` toleration is added automatically to daemon set pods. The default scheduler ignores unschedulable Nodes when scheduling daemon set pods. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-daemonsets-creating.adoc[leveloffset=+1] diff --git a/nodes/modules b/nodes/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/nodes/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/nodes/nodes/images b/nodes/nodes/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/nodes/nodes/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/nodes/nodes/modules b/nodes/nodes/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/nodes/nodes/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/nodes/nodes/nodes-node-tuning-operator.adoc b/nodes/nodes/nodes-node-tuning-operator.adoc deleted file mode 100644 index 8b4cb8f11ab9..000000000000 --- a/nodes/nodes/nodes-node-tuning-operator.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="nodes-node-tuning-operator"] -= Using the Node Tuning Operator -include::modules/common-attributes.adoc[] -:context: nodes-node-tuning-operator - -toc::[] - -Learn about the Node Tuning Operator and how you can use it to manage node-level -tuning by orchestrating the tuned daemon. - -include::modules/node-tuning-operator.adoc[leveloffset=+1] - -include::modules/accessing-an-example-cluster-node-tuning-operator-specification.adoc[leveloffset=+1] - -include::modules/custom-tuning-specification.adoc[leveloffset=+1] - -include::modules/cluster-node-tuning-operator-default-profiles-set.adoc[leveloffset=+1] - -include::modules/node-tuning-operator-supported-tuned-daemon-plug-ins.adoc[leveloffset=+1] - - - - - - diff --git a/nodes/nodes/nodes-nodes-garbage-collection.adoc b/nodes/nodes/nodes-nodes-garbage-collection.adoc deleted file mode 100644 index 3726d86c83e4..000000000000 --- a/nodes/nodes/nodes-nodes-garbage-collection.adoc +++ /dev/null @@ -1,32 +0,0 @@ - -:context: nodes-nodes-configuring -[id="nodes-nodes-garbage-collection"] -= Freeing node resources using garbage collection -include::modules/common-attributes.adoc[] - -toc::[] - - - - -As an administrator, you can use {product-title} to ensure that your nodes are running efficiently -by freeing up resources through garbage collection. - -The {product-title} node performs two types of garbage collection: - -* Container garbage collection: Removes terminated containers. -* Image garbage collection: Removes images not referenced by any running pods. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-garbage-collection-containers.adoc[leveloffset=+1] - -include::modules/nodes-nodes-garbage-collection-images.adoc[leveloffset=+1] - -include::modules/nodes-nodes-garbage-collection-configuring.adoc[leveloffset=+1] - - diff --git a/nodes/nodes/nodes-nodes-machine-config-daemon-metrics.adoc b/nodes/nodes/nodes-nodes-machine-config-daemon-metrics.adoc deleted file mode 100644 index 01b1e7409c22..000000000000 --- a/nodes/nodes/nodes-nodes-machine-config-daemon-metrics.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="machine-config-daemon-metrics"] -= Machine Config Daemon metrics -include::modules/common-attributes.adoc[] -:context: machine-config-operator - -The Machine Config Daemon is a part of the Machine Config Operator. It runs on every node in the cluster. The Machine Config Daemon manages configuration changes and updates on each of the nodes. - -include::modules/machine-config-daemon-metrics.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[the documentation on the {product-title} monitoring stack]. -* See xref:../../support/gathering-cluster-data.adoc[the documentation on gathering data about your cluster]. diff --git a/nodes/nodes/nodes-nodes-managing-max-pods.adoc b/nodes/nodes/nodes-nodes-managing-max-pods.adoc deleted file mode 100644 index 543adc49bed4..000000000000 --- a/nodes/nodes/nodes-nodes-managing-max-pods.adoc +++ /dev/null @@ -1,42 +0,0 @@ -:context: nodes-nodes-jobs -[id="nodes-nodes-managing-max-pods"] -= Managing the maximum number of pods per node -include::modules/common-attributes.adoc[] - -toc::[] - - -In {product-title}, you can configure the number of pods that can run on a node based on the number of -processor cores on the node, a hard limit or both. If you use both options, -the lower of the two limits the number of pods on a node. - -Exceeding these values can result in: - -* Increased CPU utilization by {product-title}. -* Slow pod scheduling. -* Potential out-of-memory scenarios, depending on the amount of memory in the node. -* Exhausting the IP address pool. -* Resource overcommitting, leading to poor user application performance. - -[NOTE] -==== -A pod that is holding a single container actually uses two -containers. The second container sets up networking prior to the -actual container starting. As a result, a node running 10 pods actually -has 20 containers running. -==== - -The `podsPerCore` parameter limits the number of pods the node can run based on the number of -processor cores on the node. For example, if `podsPerCore` is set to `10` on -a node with 4 processor cores, the maximum number of pods allowed on the node is 40. - -The `maxPods` parameter limits the number of pods the node can run to a fixed value, regardless -of the properties of the node. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-managing-max-pods-proc.adoc[leveloffset=+1] - diff --git a/nodes/nodes/nodes-nodes-managing.adoc b/nodes/nodes/nodes-nodes-managing.adoc deleted file mode 100644 index d7ef9c9645eb..000000000000 --- a/nodes/nodes/nodes-nodes-managing.adoc +++ /dev/null @@ -1,24 +0,0 @@ - -:context: nodes-nodes-jobs -[id="nodes-nodes-managing"] -= Managing nodes -include::modules/common-attributes.adoc[] - -toc::[] - - -{product-title} uses a KubeletConfig custom resource (CR) to manage the -configuration of nodes. By creating an instance of a `KubeletConfig` object, a managed machine config is created to override setting on the node. - -[NOTE] -==== -*Logging in to remote machines for the purpose of changing their configuration is not supported.* -==== - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-managing-about.adoc[leveloffset=+1] - diff --git a/nodes/nodes/nodes-nodes-modifying.adoc b/nodes/nodes/nodes-nodes-modifying.adoc deleted file mode 100644 index d9539b19b3c4..000000000000 --- a/nodes/nodes/nodes-nodes-modifying.adoc +++ /dev/null @@ -1,18 +0,0 @@ - -:context: nodes-nodes-modifying -[id="nodes-nodes-modifying"] -= Modifying existing nodes in your {product-title} cluster -include::modules/common-attributes.adoc[] - -toc::[] - - -As an administrator, you can use the node group configuration map or through the use of labels on the nodes. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-working-marking.adoc[leveloffset=+1] - diff --git a/nodes/nodes/nodes-nodes-rebooting.adoc b/nodes/nodes/nodes-nodes-rebooting.adoc deleted file mode 100644 index 27f1f3fc3153..000000000000 --- a/nodes/nodes/nodes-nodes-rebooting.adoc +++ /dev/null @@ -1,39 +0,0 @@ - -:context: nodes-nodes-rebooting -[id="nodes-nodes-rebooting"] -= Understanding node rebooting -include::modules/common-attributes.adoc[] - -toc::[] - - - -To reboot a node without causing an outage for applications running on the -platform, it is important to first evacuate the pods. For pods that are -made highly available by the routing tier, nothing -else needs to be done. For other pods needing storage, typically databases, it -is critical to ensure that they can remain in operation with one pod -temporarily going offline. While implementing resiliency for stateful pods -is different for each application, in all cases it is important to configure -the scheduler to use node anti-affinity to -ensure that the pods are properly spread across available nodes. - -Another challenge is how to handle nodes that are running critical -infrastructure such as the router or the registry. The same node evacuation -process applies, though it is important to understand certain edge cases. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-rebooting-infrastructure.adoc[leveloffset=+1] - -.Additional information - -* For more information on pod anti-affinity, see xref:../../nodes/scheduling/nodes-scheduler-pod-affinity.adoc#nodes-scheduler-pod-affinity[Placing pods relative to other pods using affinity and anti-affinity rules]. - -include::modules/nodes-nodes-rebooting-affinity.adoc[leveloffset=+1] - -include::modules/nodes-nodes-rebooting-router.adoc[leveloffset=+1] - diff --git a/nodes/nodes/nodes-nodes-resources-configuring.adoc b/nodes/nodes/nodes-nodes-resources-configuring.adoc deleted file mode 100644 index 72b950a65974..000000000000 --- a/nodes/nodes/nodes-nodes-resources-configuring.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[id="nodes-nodes-resources-configuring"] -= Allocating resources for nodes in an {product-title} cluster -include::modules/common-attributes.adoc[] -:context: nodes-nodes-resources-configuring - -toc::[] - -To provide more reliable scheduling and minimize node resource overcommitment, reserve a portion of the CPU and memory resources for use by the underlying node components, such as `kubelet` and `kube-proxy`, and the remaining system components, such as `sshd` and `NetworkManager`. By specifying the resources to reserve, you provide the scheduler with more information about the remaining CPU and memory resources that a node has available for use by pods. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-resources-configuring-about.adoc[leveloffset=+1] - -include::modules/nodes-nodes-resources-configuring-setting.adoc[leveloffset=+1] - -//// -== Additional resources - -The ephemeral storage management feature is disabled by default. To enable this -feature, - -See /install_config/configuring_ephemeral.adoc#install-config-configuring-ephemeral-storage[configuring for -ephemeral storage]. - -See /dev_guide/compute_resources.adoc#dev-guide-compute-resources[Compute Resources] for more -details. - -#update these links when the links become available# - -//// diff --git a/nodes/nodes/nodes-nodes-resources-cpus.adoc b/nodes/nodes/nodes-nodes-resources-cpus.adoc deleted file mode 100644 index dced9dce06d4..000000000000 --- a/nodes/nodes/nodes-nodes-resources-cpus.adoc +++ /dev/null @@ -1,20 +0,0 @@ -:context: nodes-nodes-resources-cpus -[id="nodes-nodes-resources-cpus"] -= Allocating specific CPUs for nodes in a cluster -include::modules/common-attributes.adoc[] - -toc::[] - - -When using the xref:../../scalability_and_performance/using-cpu-manager.adoc[static CPU Manager policy], you can reserve specific CPUs for use by specific nodes in your cluster. For example, on a system with 24 CPUs, you could reserve CPUs numbered 0 - 3 for the control plane allowing the compute nodes to use CPUs 4 - 23. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-resources-cpus-reserve.adoc[leveloffset=+1] - -.Additional resources - -* For more information on the `systemReserved` and `kubeReserved` parameters, see xref:../../nodes/nodes/nodes-nodes-resources-configuring.html#nodes-nodes-resources-configuring-about_nodes-nodes-resources-configuring[Allocating resources for nodes in an {product-title} cluster]. diff --git a/nodes/nodes/nodes-nodes-viewing.adoc b/nodes/nodes/nodes-nodes-viewing.adoc deleted file mode 100644 index cd2f9e628471..000000000000 --- a/nodes/nodes/nodes-nodes-viewing.adoc +++ /dev/null @@ -1,25 +0,0 @@ - -:context: nodes-nodes-viewing -[id="nodes-nodes-viewing"] -= Viewing and listing the nodes in your {product-title} cluster -include::modules/common-attributes.adoc[] - -toc::[] - - -You can list all the nodes in your cluster to obtain information such as status, age, memory usage, and details about the nodes. - -When you perform node management operations, the CLI interacts with node objects that are representations of actual node hosts. -The master uses the information from node objects to validate nodes with health checks. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-nodes-viewing-listing.adoc[leveloffset=+1] - -include::modules/nodes-nodes-viewing-listing-pods.adoc[leveloffset=+1] - -include::modules/nodes-nodes-viewing-memory.adoc[leveloffset=+1] - diff --git a/nodes/nodes/nodes-nodes-working.adoc b/nodes/nodes/nodes-nodes-working.adoc deleted file mode 100644 index 2f5ef367db7e..000000000000 --- a/nodes/nodes/nodes-nodes-working.adoc +++ /dev/null @@ -1,38 +0,0 @@ - -:context: nodes-nodes-working -[id="nodes-nodes-working"] -= Working with nodes -include::modules/common-attributes.adoc[] - -toc::[] - - -As an administrator, you can perform a number of tasks to make your clusters more efficient. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/nodes-nodes-working-evacuating.adoc[leveloffset=+1] - -include::modules/nodes-nodes-working-updating.adoc[leveloffset=+1] - -include::modules/nodes-nodes-working-marking.adoc[leveloffset=+1] - -include::modules/nodes-nodes-working-master-schedulable.adoc[leveloffset=+1] - -== Deleting nodes - -include::modules/nodes-nodes-working-deleting.adoc[leveloffset=+2] -include::modules/nodes-nodes-working-deleting-bare-metal.adoc[leveloffset=+2] - -include::modules/nodes-nodes-kernel-arguments.adoc[leveloffset=+1] -ifdef::openshift-webscale[] -include::modules/nodes-nodes-rtkernel-arguments.adoc[leveloffset=+1] -endif::openshift-webscale[] -== Additional resources - -For more information on scaling your cluster using a MachineSet, -see xref:../../machine_management/manually-scaling-machineset.adoc#machineset-manually-scaling-manually-scaling-machineset[Manually scaling a MachineSet]. diff --git a/nodes/pods/nodes-pods-autoscaling.adoc b/nodes/pods/nodes-pods-autoscaling.adoc deleted file mode 100644 index aedbf826c639..000000000000 --- a/nodes/pods/nodes-pods-autoscaling.adoc +++ /dev/null @@ -1,36 +0,0 @@ -:context: nodes-pods-autoscaling -[id='nodes-pods-autoscaling'] -= Automatically scaling pods with the horizontal pod autoscaler -include::modules/common-attributes.adoc[] - -toc::[] - -As a developer, you can use a horizontal pod autoscaler (HPA) to -specify how {product-title} should automatically increase or decrease the scale of -a replication controller or deployment configuration, based on metrics collected -from the pods that belong to that replication controller or deployment -configuration. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-autoscaling-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-autoscaling-policies.adoc[leveloffset=+2] - -include::modules/nodes-pods-autoscaling-creating-cpu.adoc[leveloffset=+1] - -include::modules/nodes-pods-autoscaling-creating-memory.adoc[leveloffset=+1] - -include::modules/nodes-pods-autoscaling-status-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-autoscaling-status-viewing.adoc[leveloffset=+2] - -== Additional resources - -For more information on replication controllers and deployment controllers, -see xref:../../applications/deployments/what-deployments-are.adoc#what-deployments-are[Understanding deployments and deployment configs]. - diff --git a/nodes/pods/nodes-pods-configuring.adoc b/nodes/pods/nodes-pods-configuring.adoc deleted file mode 100644 index 66d38ee5a960..000000000000 --- a/nodes/pods/nodes-pods-configuring.adoc +++ /dev/null @@ -1,32 +0,0 @@ -:context: nodes-pods-configuring -[id="nodes-pods-configuring"] -= Configuring an {product-title} cluster for pods -include::modules/common-attributes.adoc[] - -toc::[] - -As an administrator, you can create and maintain an efficient cluster for pods. - -By keeping your cluster efficient, you can provide a better environment for your developers using -such tools as what a pod does when it exits, ensuring that the required number of pods is always running, -when to restart pods designed to run only once, limit the bandwidth available to pods, and how to keep -pods running during disruptions. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-configuring-restart.adoc[leveloffset=+1] - -include::modules/nodes-pods-configuring-bandwidth.adoc[leveloffset=+1] - -include::modules/nodes-pods-pod-disruption-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-pod-disruption-configuring.adoc[leveloffset=+2] - -include::modules/nodes-pods-configuring-pod-critical.adoc[leveloffset=+1] - -// modules/nodes-pods-configuring-run-once.adoc[leveloffset=+1] - - diff --git a/nodes/pods/nodes-pods-node-selectors.adoc b/nodes/pods/nodes-pods-node-selectors.adoc deleted file mode 100644 index c70ef35b388b..000000000000 --- a/nodes/pods/nodes-pods-node-selectors.adoc +++ /dev/null @@ -1,22 +0,0 @@ -:context: nodes-pods-node-selectors -[id="nodes-pods-node-selectors"] -= Placing pods on specific nodes using node selectors -include::modules/common-attributes.adoc[] - -toc::[] - - - -A _node selector_ specifies a map of key-value pairs. The rules are defined using custom labels on nodes and selectors specified in pods. - -For the pod to be eligible to run on a node, the pod must have the indicated key-value pairs as the label on the node. - -If you are using node affinity and node selectors in the same pod configuration, see the important considerations below. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-scheduler-node-selectors-pod.adoc[leveloffset=+1] - diff --git a/nodes/pods/nodes-pods-plugins.adoc b/nodes/pods/nodes-pods-plugins.adoc deleted file mode 100644 index 09bdbfba0f10..000000000000 --- a/nodes/pods/nodes-pods-plugins.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:context: nodes-pods-device -[id="nodes-pods-device"] -= Using device plug-ins to access external resources with pods -include::modules/common-attributes.adoc[] - -toc::[] - - -Device plug-ins allow you to use a particular device type (GPU, InfiniBand, -or other similar computing resources that require vendor-specific initialization -and setup) in your {product-title} pod without needing to write custom code. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-plugins-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-plugins-device-mgr.adoc[leveloffset=+1] - -include::modules/nodes-pods-plugins-install.adoc[leveloffset=+1] - diff --git a/nodes/pods/nodes-pods-priority.adoc b/nodes/pods/nodes-pods-priority.adoc deleted file mode 100644 index c20634c72264..000000000000 --- a/nodes/pods/nodes-pods-priority.adoc +++ /dev/null @@ -1,27 +0,0 @@ -:context: nodes-pods-priority -[id="nodes-pods-priority"] -= Including pod priority in pod scheduling decisions -include::modules/common-attributes.adoc[] - -toc::[] - - -You can enable pod priority and preemption in your cluster. pod priority indicates the importance of a pod relative to other pods and queues the pods based on that priority. pod preemption allows the cluster to evict, or preempt, lower-priority pods so that higher-priority pods can be scheduled if there is no available space on a suitable node -pod priority also affects the scheduling order of pods and out-of-resource eviction ordering on the node. - -To use priority and preemption, you create priority classes that define the relative weight of your pods. Then, reference a priority class in the pod specification to apply that weight for scheduling. - - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-priority-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-priority-preempt-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-priority-configuring.adoc[leveloffset=+1] - - diff --git a/nodes/pods/nodes-pods-secrets.adoc b/nodes/pods/nodes-pods-secrets.adoc deleted file mode 100644 index 7caa26f21483..000000000000 --- a/nodes/pods/nodes-pods-secrets.adoc +++ /dev/null @@ -1,30 +0,0 @@ -:context: nodes-pods-secrets -[id="nodes-pods-secrets"] -= Providing sensitive data to pods -include::modules/common-attributes.adoc[] - -toc::[] - -Some applications need sensitive information, such as passwords and user names, that you do not want developers to have. - -As an administrator, you can use `Secret` objects to provide this information without exposing that information in clear text. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-secrets-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-secrets-creating.adoc[leveloffset=+1] - -include::modules/nodes-pods-secrets-creating-opaque.adoc[leveloffset=+2] - -include::modules/nodes-pods-secrets-updating.adoc[leveloffset=+1] - -include::modules/nodes-pods-secrets-certificates-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-secrets-certificates-creating.adoc[leveloffset=+2] - -include::modules/nodes-pods-secrets-troubleshooting.adoc[leveloffset=+1] - diff --git a/nodes/pods/nodes-pods-using.adoc b/nodes/pods/nodes-pods-using.adoc deleted file mode 100644 index 85ed346d017f..000000000000 --- a/nodes/pods/nodes-pods-using.adoc +++ /dev/null @@ -1,19 +0,0 @@ -:context: nodes-pods-using-ssy -[id="nodes-pods-using-pp"] -= Using pods -include::modules/common-attributes.adoc[] - -toc::[] - -A _pod_ is one or more containers deployed together on one host, and the smallest compute unit that can be defined, -deployed, and managed. - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-using-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-using-example.adoc[leveloffset=+1] diff --git a/nodes/pods/nodes-pods-vertical-autoscaler.adoc b/nodes/pods/nodes-pods-vertical-autoscaler.adoc deleted file mode 100644 index 16a08af13136..000000000000 --- a/nodes/pods/nodes-pods-vertical-autoscaler.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="nodes-pods-vpa"] -:context: nodes-pods-vertical-autoscaler -= Automatically adjust pod resource levels with the vertical pod autoscaler -include::modules/common-attributes.adoc[] - -toc::[] - - - -The {product-title} Vertical Pod Autoscaler Operator (VPA) automatically reviews the historic and current CPU and memory resources for containers in pods and can update the resource limits and requests based on the usage values it learns. The VPA uses individual custom resources (CR) to update all of the pods associated with a workload object, such as a `Deployment`, `Deployment Config`, `StatefulSet`, `Job`, `DaemonSet`, `ReplicaSet`, or `ReplicationController`. - -The VPA helps you to understand the optimal CPU and memory usage for your pods and can automatically maintain pod resources through the pod lifecycle. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/nodes-pods-vertical-autoscaler-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-vertical-autoscaler-install.adoc[leveloffset=+1] - -include::modules/nodes-pods-vertical-autoscaler-using-about.adoc[leveloffset=+1] - -include::modules/nodes-pods-vertical-autoscaler-configuring.adoc[leveloffset=+1] - -include::modules/nodes-pods-vertical-autoscaler-uninstall.adoc[leveloffset=+1] - - diff --git a/nodes/pods/nodes-pods-viewing.adoc b/nodes/pods/nodes-pods-viewing.adoc deleted file mode 100644 index 476913199daa..000000000000 --- a/nodes/pods/nodes-pods-viewing.adoc +++ /dev/null @@ -1,23 +0,0 @@ -:context: nodes-pods-viewing -[id="nodes-pods-viewing"] -= Viewing pods -include::modules/common-attributes.adoc[] - -toc::[] - -As an administrator, you can view the pods in your cluster and to determine the health of those pods and the cluster as a whole. - -include::modules/nodes-pods-about.adoc[leveloffset=+1] - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-pods-viewing-project.adoc[leveloffset=+1] - -include::modules/nodes-pods-viewing-usage.adoc[leveloffset=+1] - -include::modules/viewing-resource-logs-cli-console.adoc[leveloffset=+1] - - diff --git a/nodes/scheduling/images b/nodes/scheduling/images deleted file mode 120000 index 847b03ed0541..000000000000 --- a/nodes/scheduling/images +++ /dev/null @@ -1 +0,0 @@ -../../images/ \ No newline at end of file diff --git a/nodes/scheduling/modules b/nodes/scheduling/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/nodes/scheduling/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/nodes/scheduling/nodes-descheduler.adoc b/nodes/scheduling/nodes-descheduler.adoc deleted file mode 100644 index 558f9cfe1dc9..000000000000 --- a/nodes/scheduling/nodes-descheduler.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="nodes-descheduler"] -= Evicting pods using the descheduler -include::modules/common-attributes.adoc[] -:context: nodes-descheduler - -toc::[] - -While the xref:../../nodes/scheduling/nodes-scheduler-about.adoc#nodes-scheduler-about[scheduler] is used to determine the most suitable node to host a new pod, the descheduler can be used to evict a running pod so that the pod can be rescheduled onto a more suitable node. - -// About the descheduler -include::modules/nodes-descheduler-about.adoc[leveloffset=+1] - -// Descheduler profiles -include::modules/nodes-descheduler-profiles.adoc[leveloffset=+1] - -// Installing the descheduler -include::modules/nodes-descheduler-installing.adoc[leveloffset=+1] - -// Configuring the descheduler profiles -include::modules/nodes-descheduler-configuring-profiles.adoc[leveloffset=+1] - -// Configuring the descheduler interval -include::modules/nodes-descheduler-configuring-interval.adoc[leveloffset=+1] - -// Uninstalling the descheduler -include::modules/nodes-descheduler-uninstalling.adoc[leveloffset=+1] diff --git a/nodes/scheduling/nodes-scheduler-about.adoc b/nodes/scheduling/nodes-scheduler-about.adoc deleted file mode 100644 index c2909a80b69f..000000000000 --- a/nodes/scheduling/nodes-scheduler-about.adoc +++ /dev/null @@ -1,89 +0,0 @@ -:context: nodes-scheduler-about -[id="nodes-scheduler-about"] -= Controlling pod placement using the scheduler -include::modules/common-attributes.adoc[] - -toc::[] - - - -Pod scheduling is an internal process that determines placement of new -pods onto nodes within the cluster. - -The scheduler code has a clean separation that watches new pods -as they get created and identifies the most suitable node to host them. It then -creates bindings (pod to node bindings) for the pods using the master API. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -Default pod scheduling:: -{product-title} comes with a xref:../../nodes/scheduling/nodes-scheduler-default.adoc#nodes-scheduler-default[default scheduler] that serves the needs of most users. The default scheduler uses both inherent and customization tools to determine the best fit for a pod. - -Advanced pod scheduling:: -In situations where you might want more control over where new pods are placed, the {product-title} advanced scheduling features allow you to configure a pod so that the pod is required or has a preference to run on a particular node or alongside a specific pod by. - -* Using xref:../../nodes/scheduling/nodes-scheduler-pod-affinity.adoc#nodes-scheduler-pod-affinity[pod affinity and anti-affinity rules]. -* Controlling pod placement with xref:../../nodes/scheduling/nodes-scheduler-pod-affinity.adoc#nodes-scheduler-pod-affinity-about_nodes-scheduler-pod-affinity[pod affinity]. -* Controlling pod placement with xref:../../nodes/scheduling/nodes-scheduler-node-affinity.adoc#nodes-scheduler-node-affinity-about_nodes-scheduler-node-affinity[node affinity]. -* Placing pods on xref:../../nodes/scheduling/nodes-scheduler-overcommit.adoc#nodes-scheduler-overcommit[overcomitted nodes]. -* Controlling pod placement with xref:../../nodes/scheduling/nodes-scheduler-node-selectors.adoc#nodes-scheduler-node-selectors[node selectors]. -* Controlling pod placement with xref:../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations[taints and tolerations]. - -[id="nodes-scheduler-about-use-cases_{context}"] -== Scheduler Use Cases - -One of the important use cases for scheduling within {product-title} is to -support flexible affinity and anti-affinity policies. -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] - -[id="infrastructure-topological-levels_{context}"] -=== Infrastructure Topological Levels - -Administrators can define multiple topological levels for their infrastructure -(nodes) by specifying labels on nodes. For example: `region=r1`, `zone=z1`, `rack=s1`. - -These label names have no particular meaning and -administrators are free to name their infrastructure levels anything, such as -city/building/room. Also, administrators can define any number of levels -for their infrastructure topology, with three levels usually being adequate -(such as: `regions` -> `zones` -> `racks`). Administrators can specify affinity -and anti-affinity rules at each of these levels in any combination. -endif::openshift-enterprise,openshift-webscale,openshift-origin[] - -[id="affinity_{context}"] -=== Affinity - -Administrators should be able to configure the scheduler to specify affinity at -any topological level, or even at multiple levels. Affinity at a particular -level indicates that all pods that belong to the same service are scheduled -onto nodes that belong to the same level. This handles any latency requirements -of applications by allowing administrators to ensure that peer pods do not end -up being too geographically separated. If no node is available within the same -affinity group to host the pod, then the pod is not scheduled. - -If you need greater control over where the pods are scheduled, see xref:../../nodes/scheduling/nodes-scheduler-node-affinity.adoc#nodes-scheduler-node-affinity[Controlling pod placement on nodes using node affinity rules] and -xref:../../nodes/scheduling/nodes-scheduler-pod-affinity.adoc#nodes-scheduler-pod-affinity[Placing pods relative to other pods using affinity and anti-affinity rules]. - -These advanced scheduling features allow administrators -to specify which node a pod can be scheduled on and to force or reject scheduling relative to other pods. - - -[id="anti-affinity_{context}"] -=== Anti-Affinity - -Administrators should be able to configure the scheduler to specify -anti-affinity at any topological level, or even at multiple levels. -Anti-affinity (or 'spread') at a particular level indicates that all pods that -belong to the same service are spread across nodes that belong to that -level. This ensures that the application is well spread for high availability -purposes. The scheduler tries to balance the service pods across all -applicable nodes as evenly as possible. - -If you need greater control over where the pods are scheduled, see xref:../../nodes/scheduling/nodes-scheduler-node-affinity.adoc#nodes-scheduler-node-affinity[Controlling pod placement on nodes using node affinity rules] and -xref:../../nodes/scheduling/nodes-scheduler-pod-affinity.adoc#nodes-scheduler-pod-affinity[Placing pods relative to other pods using affinity and anti-affinity rules]. - -These advanced scheduling features allow administrators -to specify which node a pod can be scheduled on and to force or reject scheduling relative to other pods. diff --git a/nodes/scheduling/nodes-scheduler-default.adoc b/nodes/scheduling/nodes-scheduler-default.adoc deleted file mode 100644 index 24edbf06e788..000000000000 --- a/nodes/scheduling/nodes-scheduler-default.adoc +++ /dev/null @@ -1,61 +0,0 @@ -:context: nodes-scheduler-default -[id="nodes-scheduler-default"] -= Configuring the default scheduler to control pod placement -include::modules/common-attributes.adoc[] - -toc::[] - - - -The default {product-title} pod scheduler is responsible for determining placement of new -pods onto nodes within the cluster. It reads data from the pod and tries to find -a node that is a good fit based on configured policies. It is completely -independent and exists as a standalone/pluggable solution. It does not modify -the pod and just creates a binding for the pod that ties the pod to the -particular node. - -[IMPORTANT] -==== -Configuring a scheduler policy is deprecated and is planned for removal in a future release. For more information on the Technology Preview alternative, see xref:../../nodes/scheduling/nodes-scheduler-profiles.adoc#nodes-scheduler-profiles[Scheduling pods using a scheduler profile]. -==== - -A selection of predicates and priorities defines the policy for the scheduler. See xref:../../nodes/scheduling/nodes-scheduler-default.adoc#nodes-scheduler-default-modifying_nodes-scheduler-default[Modifying scheduler policy] for a list of predicates and priorities. - -.Sample default scheduler object -[source,yaml] ----- -apiVersion: config.openshift.io/v1 -kind: Scheduler -metadata: - annotations: - release.openshift.io/create-only: "true" - creationTimestamp: 2019-05-20T15:39:01Z - generation: 1 - name: cluster - resourceVersion: "1491" - selfLink: /apis/config.openshift.io/v1/schedulers/cluster - uid: 6435dd99-7b15-11e9-bd48-0aec821b8e34 -spec: - policy: <1> - name: scheduler-policy - defaultNodeSelector: type=user-node,region=east <2> ----- -<1> You can specify the name of a custom scheduler policy file. -<2> Optional: Specify a default node selector to restrict pod placement to specific nodes. The default node selector is applied to the pods created in all namespaces. Pods can be scheduled on nodes with labels that match the default node selector and any existing pod node selectors. Namespaces having project-wide node selectors are not impacted even if this field is set. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-scheduler-default-about.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-default-creating.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-default-modifying.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-default-predicates.adoc[leveloffset=+2] - -include::modules/nodes-scheduler-default-priorities.adoc[leveloffset=+2] - -include::modules/nodes-scheduler-default-sample.adoc[leveloffset=+1] diff --git a/nodes/scheduling/nodes-scheduler-node-affinity.adoc b/nodes/scheduling/nodes-scheduler-node-affinity.adoc deleted file mode 100644 index bfee2f4cba4f..000000000000 --- a/nodes/scheduling/nodes-scheduler-node-affinity.adoc +++ /dev/null @@ -1,32 +0,0 @@ -:context: nodes-scheduler-node-affinity -[id="nodes-scheduler-node-affinity"] -= Controlling pod placement on nodes using node affinity rules -include::modules/common-attributes.adoc[] - -toc::[] - - - -Affinity is a property of pods that controls the nodes on which they prefer to be scheduled. - -In {product-title} node affinity is a set of rules used by the scheduler to determine where a pod can be placed. -The rules are defined using custom labels on the nodes and label selectors specified in pods. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-scheduler-node-affinity-about.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-node-affinity-configuring-required.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-node-affinity-configuring-preferred.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-node-affinity-example.adoc[leveloffset=+1] - -[id="nodes-scheduler-node-affinity-addtl-resources_{context}"] -== Additional resources - -For information about changing node labels, see -xref:../../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-working-updating_nodes-nodes-working[Understanding how to update labels on nodes]. diff --git a/nodes/scheduling/nodes-scheduler-node-names.adoc b/nodes/scheduling/nodes-scheduler-node-names.adoc deleted file mode 100644 index c697240e1d9d..000000000000 --- a/nodes/scheduling/nodes-scheduler-node-names.adoc +++ /dev/null @@ -1,30 +0,0 @@ -:context: nodes-scheduler-node-names -[id="nodes-scheduler-node-names"] -= Placing a pod on a specific node by name -include::modules/common-attributes.adoc[] - -toc::[] - - - -Use the Pod Node Constraints admission controller to ensure a pod -is deployed onto only a specified node host by assigning it a label -and specifying this in the `nodeName` setting in a pod configuration. - -The Pod Node Constraints admission controller ensures that pods -are deployed onto only specified node hosts using labels -and prevents users without a specific role from using the -`nodeSelector` field to schedule pods. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-scheduler-node-names-configuring.adoc[leveloffset=+1] - -[id="nodes-scheduler-node-names-addtl-resources_{context}"] -== Additional resources - -For information about changing node labels, see xref:../../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-working-updating_nodes-nodes-working[Understanding how to update labels on nodes]. - diff --git a/nodes/scheduling/nodes-scheduler-node-projects.adoc b/nodes/scheduling/nodes-scheduler-node-projects.adoc deleted file mode 100644 index 259778648cd5..000000000000 --- a/nodes/scheduling/nodes-scheduler-node-projects.adoc +++ /dev/null @@ -1,20 +0,0 @@ -:context: nodes-scheduler-node-project -[id="nodes-scheduler-node-project"] -= Placing a pod in a specific project -include::modules/common-attributes.adoc[] - -toc::[] - - - -The pod Node Selector admission controller allows you to force pods onto nodes associated with a specific project and prevent pods from being scheduled in those nodes. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-scheduler-node-projects-about.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-node-projects-configuring.adoc[leveloffset=+2] - diff --git a/nodes/scheduling/nodes-scheduler-node-selectors.adoc b/nodes/scheduling/nodes-scheduler-node-selectors.adoc deleted file mode 100644 index 74e4f9edd684..000000000000 --- a/nodes/scheduling/nodes-scheduler-node-selectors.adoc +++ /dev/null @@ -1,29 +0,0 @@ -:context: nodes-scheduler-node-selectors -[id="nodes-scheduler-node-selectors"] -= Placing pods on specific nodes using node selectors -include::modules/common-attributes.adoc[] - -toc::[] - - - -A _node selector_ specifies a map of key/value pairs that are defined using custom labels on nodes and selectors specified in pods. - -For the pod to be eligible to run on a node, the pod must have the same key/value node selector as the label on the node. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/nodes-scheduler-node-selectors-about.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-node-selectors-pod.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-node-selectors-cluster.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-node-selectors-project.adoc[leveloffset=+1] - -// include::modules/nodes-scheduler-node-selectors-configuring.adoc[leveloffset=+1] - diff --git a/nodes/scheduling/nodes-scheduler-overcommit.adoc b/nodes/scheduling/nodes-scheduler-overcommit.adoc deleted file mode 100644 index 1bbb6fd8e5ec..000000000000 --- a/nodes/scheduling/nodes-scheduler-overcommit.adoc +++ /dev/null @@ -1,28 +0,0 @@ -:context: nodes-scheduler-overcommit -[id="nodes-scheduler-overcommit"] -= Placing pods onto overcommited nodes -include::modules/common-attributes.adoc[] - -toc::[] - - - - - - -In an _overcommited_ state, the sum of the container compute resource requests and limits exceeds the resources available on the system. -Overcommitment might be desirable in development environments where a trade-off of guaranteed performance for capacity is acceptable. - -Requests and limits enable administrators to allow and manage the overcommitment of resources on a node. -The scheduler uses requests for scheduling your container and providing a minimum service guarantee. -Limits constrain the amount of compute resource that may be consumed on your node. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - - -include::modules/nodes-cluster-overcommit-about.adoc[leveloffset=+1] - -include::modules/nodes-cluster-overcommit-configure-nodes.adoc[leveloffset=+1] diff --git a/nodes/scheduling/nodes-scheduler-pod-affinity.adoc b/nodes/scheduling/nodes-scheduler-pod-affinity.adoc deleted file mode 100644 index 23f1cec65339..000000000000 --- a/nodes/scheduling/nodes-scheduler-pod-affinity.adoc +++ /dev/null @@ -1,28 +0,0 @@ -:context: nodes-scheduler-pod-affinity -[id="nodes-scheduler-pod-affinity"] -= Placing pods relative to other pods using affinity and anti-affinity rules -include::modules/common-attributes.adoc[] - -toc::[] - - - -Affinity is a property of pods that controls the nodes on which they prefer to be scheduled. Anti-affinity is a property of pods -that prevents a pod from being scheduled on a node. - -In {product-title} _pod affinity_ and _pod anti-affinity_ allow you to constrain which nodes your pod is eligible to be scheduled on based on the key/value labels on other pods. - - - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-scheduler-pod-affinity-about.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-pod-affinity-configuring.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-pod-anti-affinity-configuring.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-pod-affinity-example.adoc[leveloffset=+1] diff --git a/nodes/scheduling/nodes-scheduler-pod-topology-spread-constraints.adoc b/nodes/scheduling/nodes-scheduler-pod-topology-spread-constraints.adoc deleted file mode 100644 index 76aa6385ac53..000000000000 --- a/nodes/scheduling/nodes-scheduler-pod-topology-spread-constraints.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="nodes-scheduler-pod-topology-spread-constraints"] -= Controlling pod placement by using pod topology spread constraints -include::modules/common-attributes.adoc[] -:context: nodes-scheduler-pod-topology-spread-constraints - -toc::[] - -You can use pod topology spread constraints to control the placement of your pods across nodes, zones, regions, or other user-defined topology domains. - -// About pod topology spread constraints -include::modules/nodes-scheduler-pod-topology-spread-constraints-about.adoc[leveloffset=+1] - -// Configuring pod topology spread constraints -include::modules/nodes-scheduler-pod-topology-spread-constraints-configuring.adoc[leveloffset=+1] - -// Sample pod topology spread constraints -include::modules/nodes-scheduler-pod-topology-spread-constraints-examples.adoc[leveloffset=+1] - -== Additional resources - -* xref:../../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-working-updating_nodes-nodes-working[Understanding how to update labels on nodes] diff --git a/nodes/scheduling/nodes-scheduler-profiles.adoc b/nodes/scheduling/nodes-scheduler-profiles.adoc deleted file mode 100644 index 0148ba2ee80d..000000000000 --- a/nodes/scheduling/nodes-scheduler-profiles.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="nodes-scheduler-profiles"] -= Scheduling pods using a scheduler profile -include::modules/common-attributes.adoc[] -:context: nodes-scheduler-profiles - -toc::[] - -You can configure {product-title} to use a scheduling profile to schedule pods onto nodes within the cluster. - -:FeatureName: Enabling a scheduler profile -include::modules/technology-preview.adoc[leveloffset=+0] - -// About scheduler profiles -include::modules/nodes-scheduler-profiles-about.adoc[leveloffset=+1] - -// Configuring a scheduler profile -include::modules/nodes-scheduler-profiles-configuring.adoc[leveloffset=+1] diff --git a/nodes/scheduling/nodes-scheduler-taints-tolerations.adoc b/nodes/scheduling/nodes-scheduler-taints-tolerations.adoc deleted file mode 100644 index 7cba42cd34f5..000000000000 --- a/nodes/scheduling/nodes-scheduler-taints-tolerations.adoc +++ /dev/null @@ -1,31 +0,0 @@ -:context: nodes-scheduler-taints-tolerations -[id="nodes-scheduler-taints-tolerations"] -= Controlling pod placement using node taints -include::modules/common-attributes.adoc[] - -toc::[] - - - -Taints and tolerations allow the node to control which pods should (or should not) be scheduled on them. - -// The following include statements pull in the module files that comprise -// the assembly. Include any combination of concept, procedure, or reference -// modules required to cover the user story. You can also include other -// assemblies. - -include::modules/nodes-scheduler-taints-tolerations-about.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-taints-tolerations-adding.adoc[leveloffset=+1] - -include::modules/nodes-scheduler-taints-tolerations-adding-machineset.adoc[leveloffset=+2] - -include::modules/nodes-scheduler-taints-tolerations-binding.adoc[leveloffset=+2] - -include::modules/nodes-scheduler-taints-tolerations-special.adoc[leveloffset=+2] - -include::modules/nodes-scheduler-taints-tolerations-removing.adoc[leveloffset=+1] - -//Removed per upstream docs modules/nodes-scheduler-taints-tolerations-evictions.adoc[leveloffset=+1] - - diff --git a/openshift_images/cnf-building-and-deploying-a-dpdk-payload.adoc b/openshift_images/cnf-building-and-deploying-a-dpdk-payload.adoc deleted file mode 100644 index cad584785c4f..000000000000 --- a/openshift_images/cnf-building-and-deploying-a-dpdk-payload.adoc +++ /dev/null @@ -1,304 +0,0 @@ -// Epic CNF-40 -[id="cnf-building-and-deploying-a-dpdk-application"] -= Building and deploying a DPDK application using the S2I image -include::modules/common-attributes.adoc[] -:context: building-deploying-DPDK-using-s2i-image - -toc::[] - -The Data Plane Development Kit (DPDK) base image is a base image for DPDK -applications. It uses the Source-to-Image (S2I) build tool to automate the -building of application images. - -Source-to-Image (S2I) is a tool for building reproducible and formatted -container images. It produces ready-to-run images by injecting application -source into a container image and assembling a new image. The new image -incorporates the base image (the builder) and built source. For more -information, see -xref:../cicd/builds/build-strategies.adoc#build-strategy-s2i_build-strategies[Source-to-Image -(S2I) build]. - -The DPDK base image comes preinstalled with DPDK, and with a build tool that can be used to -create a target image containing the DPDK libraries and the application provided by the user. - -== Prerequisites - -Before using the S2I tool, ensure that you have the following components installed and configured: - -* OCP Image Registry Operator: -See xref:../registry/configuring-registry-operator.adoc#configuring-registry-operator[Image Registry Operator in OpenShift Container Platform]. - -* SR-IOV Operator: -See xref:../networking/hardware_networks/about-sriov.adoc#about-sriov[About SR-IOV hardware on {product-title}]. - -* Performance AddOn Operator: -See xref:../scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc#performance-addon-operator-for-low-latency-nodes[About CNF Performance Addon Operator]. - -This example application is the `test-pmd` application provided by dpdk.org. -For more information, see link:https://doc.dpdk.org/guides/testpmd_app_ug/[Testpmd Application User Guide]. - -.Building procedure - -To build a target image, create a repository containing an application and the following two scripts: - -* `build.sh` - for building the application -* `run.sh` - for running the application - -This is an example of `build.sh`: - ----- -#!/usr/bin/env bash - -make -C test-pmd - -cp test-pmd/testpmd ./customtestpmd - -echo "build done" ----- - -This is an example of `run.sh`: - ----- -#!/bin/bash -eux - -export CPU=$(cat /sys/fs/cgroup/cpuset/cpuset.cpus) -echo ${CPU} -echo ${PCIDEVICE_OPENSHIFT_IO_DPDKNIC} # This is the resource name configured via -the SR-IOV operator. - -if [ "$RUN_TYPE" == "testpmd" ]; then -envsubst < test-template.sh > test.sh -chmod +x test.sh -expect -f test.sh -fi - -while true; do sleep inf; done; ----- - -The example `run.sh` will run the commands inside the `test-template.sh`. - ----- -spawn ./customtestpmd -l ${CPU} -w ${PCIDEVICE_OPENSHIFT_IO_DPDKNIC} ---iova-mode=va -- -i --portmask=0x1 --nb-cores=2 --forward-mode=mac --port-topology=loop ---no-mlockall -set timeout 10000 -expect "testpmd>" -send -- "start\r" -sleep 20 -expect "testpmd>" -send -- "stop\r" -expect "testpmd>" -send -- "quit\r" -expect eof ----- - -This file will run the `testpmd` compiled application from the build stage. -This spawns the `testpmd` interactive terminal then start a test workload and close it after 20 seconds. - -The DPDK base image and the application repository are both used to build a target application image. -S2I copies the application from the repository to the DPDK base image, which then builds a target image using -DPDK base image resources and the copied application. - -You can use the {product-title} BuildConfig to build a target image in a production environment. -The `build-config.yaml` file is the file you use to create your automated build. -It creates a new `dpdk` namespace and configures an `ImageStream` for the image -and starts a build. -The internal registry must be configured in the cluster. - ----- ---- -apiVersion: image.openshift.io/v1 -kind: ImageStream <1> -metadata: - name: s2i-dpdk-app - namespace: dpdk -spec: {} ---- -apiVersion: build.openshift.io/v1 -kind: BuildConfig -metadata: - labels: - app: s2i-dpdk - app.kubernetes.io/component: s2i-dpdk - app.kubernetes.io/instance: s2i-dpdk - name: s2i-dpdk - namespace: dpdk -spec: - failedBuildsHistoryLimit: 5 - nodeSelector: null - output: <2> - to: - kind: ImageStreamTag - name: s2i-dpdk-app:latest - postCommit: {} - resources: {} - runPolicy: Serial - source: <3> - contextDir: tools/s2i-dpdk/test/test-app - git: - uri: <repo-uri> <4> - type: Git - strategy: <5> - sourceStrategy: - from: - kind: DockerImage - name: registry.access.redhat.com/openshift4/dpdk-base-rhel8:v4.4 - type: Source - successfulBuildsHistoryLimit: 5 - triggers: - - type: ConfigChange ----- - -<1> The `kind` type specifies the defined image stream. - -<2> The `output` type publishes the result of the image stream object. - -<3> The `source` type contains the git repository and a context directory within the repository. - -<4> The repository uri that contains the application and both the `build.sh` and the `run.sh` files. - -<5> The `strategy` type contains a DPDK base image. - -It is the `source` type and `strategy` type that build the image. - -A complete guide to using BuildConfigs is available in -xref:../builds/understanding-buildconfigs.adoc#understanding-buildconfigs[Understanding -build configurations]. - -After the base DPDK image build is ready, you should configure the environment to be able to run the DPDK workload on it. - -.Deployment procedure - -. Create a performance profile to allocate Hugepages and isolated CPUs. For more -information, see -xref:../scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc#cnf-understanding-low-latency_{context}[Tuning -nodes for low latency via PerformanceProfile]. - -. Create the SR-IOV network policy and the SR-IOV network attachment based on your network card type. For more information, -see xref:../networking/hardware_networks/using-dpdk-and-rdma.adoc#using-dpdk-and-rdma[Using Virtual Functions (VFs) with DPDK and RDMA modes]. - -. Using a deployment config resource instead of a regular deployment allows automatic redeploy of the workload whenever a new image is built. -You must create a special `SecurityContextConstraints` resource that will allow the `deployer` service account to create the -dpdk workload deployment and the deployment config resource pointing to the `ImageStream`. -+ -`SecurityContextConstraints` example: -+ ----- -apiVersion: security.openshift.io/v1 -kind: SecurityContextConstraints -metadata: - name: dpdk -allowHostDirVolumePlugin: true -allowHostIPC: false -allowHostNetwork: false -allowHostPID: false -allowHostPorts: false -allowPrivilegeEscalation: false -allowPrivilegedContainer: false -allowedCapabilities: - - "*" -allowedUnsafeSysctls: - - "*" -defaultAddCapabilities: null -fsGroup: - type: RunAsAny -readOnlyRootFilesystem: false -runAsUser: - type: RunAsAny -seLinuxContext: - type: RunAsAny -seccompProfiles: - - "*" -users: <1> - - system:serviceaccount:dpdk:deployer -volumes: - - "*" ----- -+ -<1> This is a list of all the service accounts that will be part of the SCC. -You should add here all the namespaces that will deploy the dpdk workload in the following format `system:serviceaccount:<namespace>:deployer`. - -. Apply the deployment config resource. -+ -`DeploymentConfig` resource example: -+ ----- -apiVersion: apps.openshift.io/v1 -kind: DeploymentConfig -metadata: - labels: - app: s2i-dpdk-app - app.kubernetes.io/component: s2i-dpdk-app - app.kubernetes.io/instance: s2i-dpdk-app - name: s2i-dpdk-app - namespace: dpdk -spec: - replicas: 1 - revisionHistoryLimit: 10 - selector: - deploymentconfig: s2i-dpdk-app - strategy: - rollingParams: - intervalSeconds: 1 - maxSurge: 25% - maxUnavailable: 25% - timeoutSeconds: 600 - updatePeriodSeconds: 1 - type: Rolling - template: - metadata: - labels: - deploymentconfig: s2i-dpdk-app - annotations: - k8s.v1.cni.cncf.io/networks: dpdk/dpdk-network <1> - spec: - serviceAccount: deployer - serviceAccountName: deployer - securityContext: - runAsUser: 0 - containers: - - image: “<internal-registry-url>/<namespace>/<image-stream>:<tag>” <2> - securityContext: - runAsUser: 0 - capabilities: - add: ["IPC_LOCK","SYS_RESOURCE"] - imagePullPolicy: Always - name: s2i-dpdk-app - terminationMessagePath: /dev/termination-log - terminationMessagePolicy: File - resources: <3> - limits: - cpu: "4" - hugepages-1Gi: 4Gi - memory: 1000Mi - requests: - cpu: "4" - hugepages-1Gi: 4Gi - memory: 1000Mi - volumeMounts: - - mountPath: /mnt/huge - name: hugepage - dnsPolicy: ClusterFirst - volumes: - - name: hugepage - emptyDir: - medium: HugePages - restartPolicy: Always - test: false - triggers: - - type: ConfigChange - - imageChangeParams: - automatic: true - containerNames: - - s2i-dpdk-app - from: <4> - kind: ImageStreamTag - name: <image-stream>:<tag> - namespace: <namespace> - type: ImageChange ----- -+ -<1> The network attachment definition name. -<2> The image stream URL. -<3> The requested resource. The limit and request should be the same so the quality of service (QOS) will be guaranteed and the CPUs will be pinned. -<4> The image stream created to start a redeployment when a newly built image is pushed to the registry. diff --git a/openshift_images/configuring-samples-operator.adoc b/openshift_images/configuring-samples-operator.adoc deleted file mode 100644 index d8654a2b7c8e..000000000000 --- a/openshift_images/configuring-samples-operator.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="configuring-samples-operator"] -= Configuring the Cluster Samples Operator -include::modules/common-attributes.adoc[] -:context: configuring-samples-operator - -toc::[] - -The Cluster Samples Operator, which operates in the `openshift` namespace, installs and updates the {op-system-base-full}-based {product-title} image streams and {product-title} templates. - -include::modules/samples-operator-overview.adoc[leveloffset=+1] - -[discrete] -== Additional resources - -* If the Cluster Samples Operator is removed during installation, you can xref:../openshift_images/samples-operator-alt-registry.adoc#samples-operator-alt-registry[use the Cluster Samples Operator with an alternate registry] so content can be imported, and then set the Cluster Samples Operator to `Managed` to get the samples. -* To ensure the Cluster Samples Operator bootstraps as `Removed` in a restricted network installation with initial network access to defer samples installation until you have decided which samples are desired, follow the instructions for xref:../installing/install_config/installing-customizing.adoc#installing-customizing[customizing nodes] to override the Cluster Samples Operator default configuration and initially come up as `Removed`. -** To host samples in your disconnected environment, follow the instructions for xref:../openshift_images/samples-operator-alt-registry.adoc#samples-operator-alt-registry[using the Cluster Samples Operator with an alternate registry]. - -include::modules/installation-images-samples-disconnected-mirroring-assist.adoc[leveloffset=+2] - -See xref:../openshift_images/samples-operator-alt-registry.adoc#installation-restricted-network-samples_samples-operator-alt-registry[Using Cluster Samples Operator image streams with alternate or mirrored registries] for a detailed procedure. - -include::modules/samples-operator-configuration.adoc[leveloffset=+1] - -include::modules/samples-operator-crd.adoc[leveloffset=+1] - -include::modules/images-samples-operator-deprecated-image-stream.adoc[leveloffset=+1] - -[discrete] -== Additional resources - -For more information about configuring credentials, see xref:../openshift_images/managing_images/using-image-pull-secrets.adoc#using-image-pull-secrets[Using image pull secrets]. diff --git a/openshift_images/create-images.adoc b/openshift_images/create-images.adoc deleted file mode 100644 index fd9906db0494..000000000000 --- a/openshift_images/create-images.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="creating-images"] -= Creating images -include::modules/common-attributes.adoc[] -:context: create-images - -toc::[] - -Learn how to create your own container images, based on pre-built images that are ready to help you. -The process includes learning best practices for writing images, defining metadata for images, testing images, and using a custom builder workflow to create images to use with {product-title}. -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -After you create an image, you can push it to the internal registry. -endif::[] - - -// include::modules/builds-define-build-inputs.adoc[leveloffset=+1] - -include::modules/images-create-guidelines.adoc[leveloffset=+1] -include::modules/images-create-guide-general.adoc[leveloffset=+2] -include::modules/images-create-guide-openshift.adoc[leveloffset=+2] -include::modules/images-create-metadata.adoc[leveloffset=+1] - - - -//Testing may have to move -include::modules/images-test-s2i.adoc[leveloffset=+1] - - -//Section - use openshift to build images - link to build strategies diff --git a/openshift_images/image-configuration.adoc b/openshift_images/image-configuration.adoc deleted file mode 100644 index 395490714550..000000000000 --- a/openshift_images/image-configuration.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="image-configuration"] -= Image configuration resources -include::modules/common-attributes.adoc[] -:context: image-configuration - -toc::[] - -Use the following procedure to configure image registries. - -include::modules/images-configuration-parameters.adoc[leveloffset=+1] - -include::modules/images-configuration-file.adoc[leveloffset=+1] - -include::modules/images-configuration-allowed.adoc[leveloffset=+2] - -include::modules/images-configuration-blocked.adoc[leveloffset=+2] - -include::modules/images-configuration-insecure.adoc[leveloffset=+2] - -include::modules/images-configuration-shortname.adoc[leveloffset=+2] - -include::modules/images-configuration-cas.adoc[leveloffset=+2] - -include::modules/images-configuration-registry-mirror.adoc[leveloffset=+2] diff --git a/openshift_images/image-streams-manage.adoc b/openshift_images/image-streams-manage.adoc deleted file mode 100644 index 5089ea4e3929..000000000000 --- a/openshift_images/image-streams-manage.adoc +++ /dev/null @@ -1,39 +0,0 @@ -:context: image-streams-managing -[id="managing-image-streams"] -= Managing imagestreams -include::modules/common-attributes.adoc[] - -:toc: macro -:toc-title: -:prewrap!: - -toc::[] - -Imagestreams provide a means of creating and updating container images in an -on-going way. As improvements are made to an image, tags can be used to assign -new version numbers and keep track of changes. This document describes how image -streams are managed. - -include::modules/images-imagestream-use.adoc[leveloffset=+1] -include::modules/images-imagestream-configure.adoc[leveloffset=+1] -include::modules/images-using-imagestream-images.adoc[leveloffset=+1] -include::modules/images-using-imagestream-tags.adoc[leveloffset=+1] -include::modules/images-using-imagestream-change-triggers.adoc[leveloffset=+1] -include::modules/images-imagestream-mapping.adoc[leveloffset=+1] - -== Working with imagestreams - -The following sections describe how to use imagestreams and imagestreamtags. - -include::modules/images-getting-info-about-imagestreams.adoc[leveloffset=+2] -include::modules/images-imagestream-adding-tags.adoc[leveloffset=+2] -include::modules/images-imagestream-external-image-tags.adoc[leveloffset=+2] -include::modules/images-imagestream-update-tag.adoc[leveloffset=+2] -include::modules/images-imagestream-remove-tag.adoc[leveloffset=+2] - -See xref:../openshift_images/configuring-samples-operator.adoc#images-samples-operator-deprecated-image-stream_configuring-samples-operator[Removing deprecated image stream tags from the Cluster Samples Operator] for more information on how the Cluster Samples Operator handles deprecated image stream tags. - -include::modules/images-imagestream-import.adoc[leveloffset=+2] - -include::modules/images-imagestream-import-images-private-registry.adoc[leveloffset=+1] -include::modules/images-allow-pods-to-reference-images-from-secure-registries.adoc[leveloffset=+2] diff --git a/openshift_images/images-understand.adoc b/openshift_images/images-understand.adoc deleted file mode 100644 index 67949ce174e2..000000000000 --- a/openshift_images/images-understand.adoc +++ /dev/null @@ -1,38 +0,0 @@ -:context: images-understand -[id="understanding-images"] -= Understanding containers, images, and imagestreams -include::modules/common-attributes.adoc[] - -:toc: macro -:toc-title: -:prewrap!: - -toc::[] - - -Containers, images, and imagestreams are important concepts -to understand when you set out to create and manage containerized software. -An image holds a set of software that is ready to run, -while a container is a running instance of a container image. -An imagestream provides a way of storing different versions of the -same basic image. Those different versions are represented by different -tags on the same image name. - -include::modules/images-about.adoc[leveloffset=+1] -include::modules/containers-about.adoc[leveloffset=+1] -include::modules/images-image-registry-about.adoc[leveloffset=+1] -include::modules/images-container-repository-about.adoc[leveloffset=+1] -include::modules/images-tag.adoc[leveloffset=+1] -include::modules/images-id.adoc[leveloffset=+1] -include::modules/images-imagestream-use.adoc[leveloffset=+1] -include::modules/images-imagestream-tag.adoc[leveloffset=+1] -include::modules/images-imagestream-image.adoc[leveloffset=+1] -include::modules/images-imagestream-trigger.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -== Additional resources - -* For more information on using imagestreams, see -xref:../openshift_images/image-streams-manage.adoc#managing-image-streams[Managing image -streams]. -endif::[] diff --git a/openshift_images/managing_images/image-pull-policy.adoc b/openshift_images/managing_images/image-pull-policy.adoc deleted file mode 100644 index 9c16f7a380af..000000000000 --- a/openshift_images/managing_images/image-pull-policy.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="image-pull-policy"] -= Image pull policy -include::modules/common-attributes.adoc[] -:context: image-pull-policy - -toc::[] - -Each container in a Pod has a container image. Once you have created an image -and pushed it to a registry, you can then refer to it in the Pod. - -include::modules/images-image-pull-policy-overview.adoc[leveloffset=+1] diff --git a/openshift_images/managing_images/managing-images-overview.adoc b/openshift_images/managing_images/managing-images-overview.adoc deleted file mode 100644 index fafaf9a0f37e..000000000000 --- a/openshift_images/managing_images/managing-images-overview.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="managing-images-overview"] -= Managing images overview -include::modules/common-attributes.adoc[] -:context: managing-images-overview - -toc::[] - -With {product-title} you can interact with images and set up imagestreams, -depending on where the images' registries are located, any authentication -requirements around those registries, and how you want your builds and -deployments to behave. - -include::modules/images-managing-overview.adoc[leveloffset=+1] diff --git a/openshift_images/managing_images/tagging-images.adoc b/openshift_images/managing_images/tagging-images.adoc deleted file mode 100644 index 40c8b433dd51..000000000000 --- a/openshift_images/managing_images/tagging-images.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="tagging-images"] -= Tagging images -include::modules/common-attributes.adoc[] -:context: tagging-images - -toc::[] - -The following sections provide an overview and instructions for using image tags -in the context of container images for working with {product-title} imagestreams -and their tags. - -include::modules/images-tag.adoc[leveloffset=+1] - -include::modules/images-tagging-conventions.adoc[leveloffset=+1] - -include::modules/images-add-tags-to-imagestreams.adoc[leveloffset=+1] - -include::modules/images-remove-tag-imagestream.adoc[leveloffset=+1] - -include::modules/images-referencing-images-imagestreams.adoc[leveloffset=+1] - - -== Additional information - -* Example imagestream definitions for https://github.com/openshift/origin/blob/master/examples/image-streams/image-streams-centos7.json[CentOS imagestreams]. diff --git a/openshift_images/managing_images/using-image-pull-secrets.adoc b/openshift_images/managing_images/using-image-pull-secrets.adoc deleted file mode 100644 index 21ed745b5d8a..000000000000 --- a/openshift_images/managing_images/using-image-pull-secrets.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id="using-image-pull-secrets"] -= Using image pull secrets -include::modules/common-attributes.adoc[] -:context: using-image-pull-secrets - -toc::[] - -If you are using {product-title}'s internal registry and are pulling from -image streams located in the same project, then your pod's service account should -already have the correct permissions and no additional action should be -required. - -However, for other scenarios, such as referencing images across {product-title} -projects or from secured registries, then additional configuration steps are -required. - -You can obtain the image pull secret, `pullSecret`, from the link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site. - -You use this pull secret to authenticate with the services that are provided by the included authorities, including link:quay.io[Quay.io] and link:registry.redhat.io[registry.redhat.io], which serve the container images for {product-title} components. - -.Example `config.json` file -[source,json] ----- -{ - "auths":{ - "cloud.openshift.com":{ - "auth":"b3Blb=", - "email":"you@example.com" - }, - "quay.io":{ - "auth":"b3Blb=", - "email":"you@example.com" - } - } -} ----- - -include::modules/images-allow-pods-to-reference-images-across-projects.adoc[leveloffset=+1] - -include::modules/images-allow-pods-to-reference-images-from-secure-registries.adoc[leveloffset=+1] - -include::modules/images-pulling-from-private-registries.adoc[leveloffset=+2] - -include::modules/images-update-global-pull-secret.adoc[leveloffset=+1] diff --git a/openshift_images/modules b/openshift_images/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/openshift_images/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/openshift_images/samples-operator-alt-registry.adoc b/openshift_images/samples-operator-alt-registry.adoc deleted file mode 100644 index 1454cfee02ba..000000000000 --- a/openshift_images/samples-operator-alt-registry.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="samples-operator-alt-registry"] -= Using the Cluster Samples Operator with an alternate registry -include::modules/common-attributes.adoc[] -:context: samples-operator-alt-registry - -toc::[] - -You can use the Cluster Samples Operator with an alternate registry by first creating a mirror registry. - -[IMPORTANT] -==== -You must have access to the internet to obtain the necessary container images. In this procedure, you place the mirror registry on a mirror host that has access to both your network and the internet. -==== - -include::modules/installation-about-mirror-registry.adoc[leveloffset=+1] - -[id="samples-preparing-bastion"] -=== Preparing the mirror host - -Before you create the mirror registry, you must prepare the mirror host. - -include::modules/cli-installing-cli.adoc[leveloffset=+2] - -include::modules/installation-creating-mirror-registry.adoc[leveloffset=+1] - -//include::modules/installation-local-registry-pull-secret.adoc[leveloffset=+1] - -include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1] - -include::modules/installation-mirror-repository.adoc[leveloffset=+1] - -include::modules/installation-restricted-network-samples.adoc[leveloffset=+1] - -include::modules/installation-images-samples-disconnected-mirroring-assist.adoc[leveloffset=+2] - -See xref:../openshift_images/samples-operator-alt-registry.adoc#installation-restricted-network-samples_samples-operator-alt-registry[Using Cluster Samples Operator image streams with alternate or mirrored registries] for a detailed procedure. diff --git a/openshift_images/templates-using-ruby-on-rails.adoc b/openshift_images/templates-using-ruby-on-rails.adoc deleted file mode 100644 index 22f896674a7c..000000000000 --- a/openshift_images/templates-using-ruby-on-rails.adoc +++ /dev/null @@ -1,56 +0,0 @@ -:context: templates-ruby-on-rails -[id="templates-using-ruby-on-rails"] -= Using Ruby on Rails -include::modules/common-attributes.adoc[] - -:toc: macro -:toc-title: -:prewrap!: - -toc::[] - -Ruby on Rails is a web framework written in Ruby. This guide covers -using Rails 4 on {product-title}. - -[WARNING] -==== -Go through the whole tutorial to have an overview of all -the steps necessary to run your application on the {product-title}. If you -experience a problem try reading through the entire tutorial and then going back -to your issue. It can also be useful to review your previous steps to ensure -that all the steps were executed correctly. -==== - -== Prerequisites - -* Basic Ruby and Rails knowledge. -* Locally installed version of Ruby 2.0.0+, Rubygems, Bundler. -* Basic Git knowledge. -ifndef::openshift-online[] -* Running instance of {product-title} 4. -endif::[] -ifdef::openshift-online[] -* Provisioned account in OpenShift Online. -endif::[] -* Make sure that an instance of {product-title} is running and is available. Also -make sure that your `oc` CLI client is installed and the command is accessible -from your command shell, so you can use it to log in using your email address -and password. - -include::modules/templates-rails-setting-up-database.adoc[leveloffset=+1] - -include::modules/templates-rails-writing-application.adoc[leveloffset=+1] - -include::modules/templates-rails-creating-welcome-page.adoc[leveloffset=+2] - -include::modules/templates-rails-configuring-application.adoc[leveloffset=+2] - -include::modules/templates-rails-storing-application-in-git.adoc[leveloffset=+2] - -include::modules/templates-rails-deploying-application.adoc[leveloffset=+1] - -include::modules/templates-rails-creating-database-service.adoc[leveloffset=+2] - -include::modules/templates-rails-creating-frontend-service.adoc[leveloffset=+2] - -include::modules/templates-rails-creating-route-for-application.adoc[leveloffset=+2] diff --git a/openshift_images/triggering-updates-on-imagestream-changes.adoc b/openshift_images/triggering-updates-on-imagestream-changes.adoc deleted file mode 100644 index 353113bf6eff..000000000000 --- a/openshift_images/triggering-updates-on-imagestream-changes.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="triggering-updates-on-imagestream-changes"] -= Triggering updates on image stream changes -include::modules/common-attributes.adoc[] -:context: triggering-updates-on-imagestream-changes - -toc::[] - - -When an image stream tag is updated to point to a new image, {product-title} can automatically take action to roll the new image out to resources that were using the old image. You configure this behavior in different ways depending on the type of resource that references the image stream tag. - -[id="openshift-resources"] -== {product-title} resources -{product-title} Deployment configurations and Build configurations can be automatically triggered by changes to image stream tags. The triggered action can be run using the new value of the image referenced by the updated image stream tag. - -include::modules/images-triggering-updates-imagestream-changes-kubernetes-about.adoc[leveloffset=+1] - -include::modules/images-triggering-updates-imagestream-changes-kubernetes.adoc[leveloffset=+1] - -include::modules/images-triggering-updates-imagestream-changes-kubernetes-cli.adoc[leveloffset=+1] diff --git a/openshift_images/using-imagestreams-with-kube-resources.adoc b/openshift_images/using-imagestreams-with-kube-resources.adoc deleted file mode 100644 index c5f550f41c37..000000000000 --- a/openshift_images/using-imagestreams-with-kube-resources.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="using-imagestreams-with-kube-resources"] -= Using imagestreams with Kubernetes resources -include::modules/common-attributes.adoc[] -:context: using-imagestreams-with-kube-resources - -toc::[] - - -Imagestreams, being {product-title} native resources, work out of the box with -all the rest of native resources available in {product-title}, such as builds or -deployments. It is also possible to make them work with native -Kubernetes resources, such as jobs, replication controllers, replica sets or -Kubernetes deployments. - -include::modules/images-managing-images-enabling-imagestreams-kube.adoc[leveloffset=+1] diff --git a/openshift_images/using-templates.adoc b/openshift_images/using-templates.adoc deleted file mode 100644 index 3397218d72d8..000000000000 --- a/openshift_images/using-templates.adoc +++ /dev/null @@ -1,54 +0,0 @@ -:context: using-templates -[id="using-templates"] -= Using templates -include::modules/common-attributes.adoc[] - -:toc: macro -:toc-title: -:prewrap!: - -toc::[] - -The following sections provide an overview of templates, as well as how to use -and create them. - -include::modules/templates-overview.adoc[leveloffset=+1] - -include::modules/templates-uploading.adoc[leveloffset=+1] - -include::modules/templates-creating-from-console.adoc[leveloffset=+1] - -include::modules/templates-using-the-cli.adoc[leveloffset=+1] - -include::modules/templates-cli-labels.adoc[leveloffset=+2] - -include::modules/templates-cli-parameters.adoc[leveloffset=+2] - -include::modules/templates-cli-generating-list-of-objects.adoc[leveloffset=+2] - -include::modules/templates-modifying-uploaded-template.adoc[leveloffset=+1] - -include::modules/templates-using-instant-app-quickstart.adoc[leveloffset=+1] - -include::modules/templates-quickstart.adoc[leveloffset=+2] - -include::modules/templates-writing.adoc[leveloffset=+1] - -include::modules/templates-writing-description.adoc[leveloffset=+2] - -include::modules/templates-writing-labels.adoc[leveloffset=+2] - -include::modules/templates-writing-parameters.adoc[leveloffset=+2] - -include::modules/templates-writing-object-list.adoc[leveloffset=+2] - -include::modules/templates-marking-as-bindable.adoc[leveloffset=+2] - -include::modules/templates-exposing-object-fields.adoc[leveloffset=+2] - -include::modules/templates-waiting-for-readiness.adoc[leveloffset=+2] - -include::modules/templates-create-from-existing-object.adoc[leveloffset=+2] - - -//Add Quickstart and other relevant tutorials here. diff --git a/openshift_images/using_images/images-other-jenkins-agent.adoc b/openshift_images/using_images/images-other-jenkins-agent.adoc deleted file mode 100644 index caf2bce2b6a2..000000000000 --- a/openshift_images/using_images/images-other-jenkins-agent.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[id="images-other-jenkins-agent"] -= Jenkins agent -include::modules/common-attributes.adoc[] -:context: images-other-jenkins-agent - -toc::[] - -{product-title} provides three images that are suitable for use as Jenkins agents: -the *_Base_*, *_Maven_*, and *_Node.js_* images. - -The first is a base image for Jenkins agents: - -* It pulls in both the required tools, headless Java, the Jenkins JNLP client, - and the useful ones including `git`, `tar`, `zip`, and `nss` among others. -* It establishes the JNLP agent as the entrypoint. -* It includes the `oc` client tooling for invoking command line operations from - within Jenkins jobs. -* It provides Dockerfiles for both Red Hat Enterprise Linux (RHEL) and `localdev` images. - -Two more images that extend the base image are also provided: - -* Maven v3.5 image -* Node.js v10 image and Node.js v12 image - -The Maven and Node.js Jenkins agent images provide Dockerfiles for the Universal -Base Image (UBI) that you can reference when building new agent images. Also -note the `contrib` and `contrib/bin` subdirectories. They allow for the -insertion of configuration files and executable scripts for your image. - -[IMPORTANT] -==== -Use and extend an appropriate agent image version for the your -of {product-title}. If the `oc` client version that is embedded in -the agent image is not compatible with the {product-title} version, unexpected -behavior can result. -==== - -include::modules/images-other-jenkins-agent-images.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-agent-env-var.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-agent-memory.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-agent-gradle.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-agent-pod-retention.adoc[leveloffset=+1] diff --git a/openshift_images/using_images/images-other-jenkins.adoc b/openshift_images/using_images/images-other-jenkins.adoc deleted file mode 100644 index b6885e72d1a1..000000000000 --- a/openshift_images/using_images/images-other-jenkins.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id="images-other-jenkins"] -= Configuring Jenkins images -include::modules/common-attributes.adoc[] -:context: images-other-jenkins - -toc::[] - -{product-title} provides a container image for running Jenkins. This image -provides a Jenkins server instance, which can be used to set up a basic flow for -continuous testing, integration, and delivery. - -The image is based on the -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/getting_started_with_containers/index#using_red_hat_base_container_images_standard_and_minimal[Red -Hat Universal Base Images] (UBI). - -{product-title} follows the link:https://jenkins.io/changelog-stable/[LTS] -release of Jenkins. {product-title} provides an image that contains Jenkins 2.x. - -The {product-title} Jenkins images are available on `quay.io` or -`registry.redhat.io`. - -For example: - ----- -$ docker pull registry.redhat.io/openshift4/ose-jenkins:<v4.3.0> ----- - -To use these images, you can either access them directly from these registries -or push them into your {product-title} container image registry. Additionally, -you can create an ImageStream that points to the image, either in your container -image registry or at the external location. Your {product-title} resources can -then reference the ImageStream. - -But for convenience, {product-title} provides ImageStreams in the `openshift` namespace -for the core Jenkins image as well as the example Agent images provided for {product-title} -integration with Jenkins. - -== Configuration and customization - -You can manage Jenkins authentication in two ways: - -* {product-title} OAuth authentication provided by the OpenShift Login -plug-in. -* Standard authentication provided by Jenkins. - -include::modules/images-other-jenkins-oauth-auth.adoc[leveloffset=+2] - -include::modules/images-other-jenkins-auth.adoc[leveloffset=+2] - -include::modules/images-other-jenkins-env-var.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-cross-project.adoc[leveloffset=+1] - -== Jenkins cross volume mount points - -The Jenkins image can be run with mounted volumes to enable persistent storage -for the configuration: - -* `/var/lib/jenkins` - This is the data directory where Jenkins stores -configuration files, including job definitions. - -include::modules/images-other-jenkins-customize-s2i.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-config-kubernetes.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-permissions.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-create-service.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-kubernetes-plugin.adoc[leveloffset=+1] - -include::modules/images-other-jenkins-memory.adoc[leveloffset=+1] - -== Additional Resources - -* See xref:../../architecture/understanding-development.adoc#base-image-options[Base -image options] for more information on the -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/getting_started_with_containers/index#using_red_hat_base_container_images_standard_and_minimal[Red -Hat Universal Base Images] (UBI). diff --git a/openshift_images/using_images/using-images-overview.adoc b/openshift_images/using_images/using-images-overview.adoc deleted file mode 100644 index e050ca4af7b8..000000000000 --- a/openshift_images/using_images/using-images-overview.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="using-images-overview"] -= Using images overview -include::modules/common-attributes.adoc[] -:context: using-images-overview - -toc::[] - -Use the following topics to discover the different Source-to-Image (S2I), -database, and other container images that are available for {product-title} -users. - -Red Hat’s official container images are provided in the Red Hat Registry at -link:https://registry.redhat.io[registry.redhat.io]. {product-title}’s supported S2I, -database, and Jenkins images are provided in the `openshift4` repository in the -Red Hat Quay Registry. For example, -`quay.io/openshift-release-dev/ocp-v4.0-<address>` is the name of the OpenShift -Application Platform image. - -The xPaaS middleware images are provided in their respective product -repositories on the Red Hat Registry but suffixed with a `-openshift`. For -example, `registry.redhat.io/jboss-eap-6/eap64-openshift` is the name of the -JBoss EAP image. - -All Red Hat supported images covered in this section are described in the link:https://catalog.redhat.com/software/containers/explore[Container images section of the Red Hat Ecosystem Catalog]. For every version of each image, you can find details on its contents and usage. Browse or search for the image that interests you. - -[IMPORTANT] -==== -The newer versions of container images are not compatible with earlier versions -of {product-title}. Verify and use the correct version of container images, -based on your version of {product-title}. -==== diff --git a/operating/audit-listening-endpoints.adoc b/operating/audit-listening-endpoints.adoc new file mode 100644 index 000000000000..3d5c5f42c092 --- /dev/null +++ b/operating/audit-listening-endpoints.adoc @@ -0,0 +1,36 @@ +[id="audit-listening-endpoints"] += Auditing listening endpoints +include::modules/common-attributes.adoc[] +:context: audit-listening-endpoints + +toc::[] + +[role="_abstract"] + +{rh-rhacs-first} provides the ability to audit the processes that are listening on ports in your secured clusters and filter this data by deployment, namespace, or cluster. + +You can view information about processes and ports that they are listening on by using the following methods: + +* In the {product-title-short} web portal, go to *Network* -> *Listening Endpoints*. +* Connect to the `ListeningEndpointsService` object in the API. For more information on the API, go to *Help* -> *API reference* in the {product-title-short} web portal. + +The page provides a list of processes by deployment, with the following information displayed for each process on the list: + +* Deployment name +* Cluster +* Namespace +* Count, or the number of processes listening on the ports in the deployment + +You can further filter the information displayed on the page by using the filter field and entering individual deployments, namespaces, and clusters. + +//"expand icon" is used elsewhere in docs +Click the expand icon at the top of the list to expand all sections for all deployments listed, or click the expand icon on a single deployment line to view additional information about that deployment. The following information is provided: + +* Exec file path: Location of the process +* PID: System ID of the process +* Port: Port on which the process is listening +* Protocol: Protocol in use by the process +* Pod ID: Name of the pod where the process is contained +* Container name: Name of the container in which the process that is listening is located + +Clicking on a deployment name brings you to the *Risk* page in the {product-title-short} web portal, where you can view information about the deployment, including risk indicators such as policy violations and additional deployment details. \ No newline at end of file diff --git a/operating/build-time-network-policy-tools.adoc b/operating/build-time-network-policy-tools.adoc new file mode 100644 index 000000000000..84f66450ee74 --- /dev/null +++ b/operating/build-time-network-policy-tools.adoc @@ -0,0 +1,94 @@ +:_mod-docs-content-type: ASSEMBLY +[id="build-time-network-policy-tools"] += Build-time network policy tools +include::modules/common-attributes.adoc[] +:context: network-policy-tools + +toc::[] + +[role="_abstract"] +Build-time network policy tools let you automate the creation and validation of network policies, including Kubernetes network policies, and the cluster-wide Admin Network Policy (ANP) and Baseline Admin Network Policy (BANP), in your development and operations workflows by using the `roxctl` CLI. These tools work with a specified file directory containing your project's workload and network policy manifests and do not require {product-title-short} authentication. + +.Network policy tools +[%autowidth,options="header"] +|=== +|Command |Description + +|`roxctl netpol generate` +|Generates Kubernetes network policies by analyzing your project's YAML manifests in a specified directory. For more information, see xref:../operating/build-time-network-policy-tools.adoc#using-the-build-time-network-policy-generator_network-policy-tools[Using the build-time network policy generator]. + +|`roxctl netpol connectivity map` +|Lists the allowed connections between workloads in your project directory by examining the workload, Kubernetes network policy, ANP, and BANP manifests. You can generate the output in various text formats or in a graphical `.dot` format. For more information, see xref:../operating/build-time-network-policy-tools.adoc#connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command_network-policy-tools[Connectivity mapping using the roxctl netpol connectivity map command]. + +|`roxctl netpol connectivity diff` +|Creates a list of variations in the allowed connections between two project versions. This is determined by the workload and Kubernetes network policy, ANP, and BANP manifests in each version's directory. This feature shows the semantic differences which are not obvious when performing a source code (syntactic) `diff`. For more information, see xref:../operating/build-time-network-policy-tools.adoc#identifying-the-differences-in-allowed-connections-between-project-versions_network-policy-tools[Identifying the differences in allowed connections between project versions]. + +|=== + +//Network policy generator +[id="build-time-network-policy-generator_{context}"] +== Build-time network policy generator + +The build-time network policy generator can automatically generate Kubernetes network policies based on application YAML manifests. You can use it to develop network policies as part of the continuous integration/continuous deployment (CI/CD) pipeline before deploying applications on your cluster. + +Red{nbsp}Hat developed this feature in partnership with the developers of the link:https://np-guard.github.io/[NP-Guard project]. +First, the build-time network policy generator analyzes Kubernetes manifests in a local folder, including service manifests, config maps, and workload manifests such as `Pod`, `Deployment`, `ReplicaSet`, `Job`, `DaemonSet`, and `StatefulSet`. +Then, it discovers the required connectivity and creates the Kubernetes network policies to achieve pod isolation. +These policies allow no more and no less than the needed ingress and egress traffic. + +include::modules/using-the-build-time-network-policy-generator.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-generate_roxctl-netpol[roxctl netpol generate command options]. + +.Next steps + +* After generating the policies, you must inspect them for completeness and accuracy, in case any relevant network address was not specified as expected in the YAML files. + +* Most importantly, verify that required connections are not blocked by the isolating policies. To help with this inspection you can use the `roxctl netpol connectivity map` tool. + +[NOTE] +==== +Applying network policies to the cluster as part of the workload deployment using automation saves time and ensures accuracy. +You can follow a GitOps approach by submitting the generated policies using pull requests, providing the team an opportunity to review the policies before deploying them as part of the pipeline. +==== + +//Connectivity mapping +include::modules/connectivity-mapping-using-the-roxctl-netpol-connectivity-map-command.adoc[leveloffset=+1] + +include::modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-connectivity-map_roxctl-netpol[roxctl netpol connectivity map command options]. + +include::modules/retrieving-explanations.adoc[leveloffset=+2] + +include::modules/understanding-connectivity-explanations.adoc[leveloffset=+3] + +include::modules/connectivity-map-output-formats-and-visualizations.adoc[leveloffset=+2] + +include::modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc[leveloffset=+2] + +//Connectivity diff +include::modules/identifying-the-differences-in-allowed-connections-between-project-versions.adoc[leveloffset=+1] + +include::modules/generating-connectivity-difference-reports.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-connectivity-diff_roxctl-netpol[roxctl netpol connectivity diff command options]. +* link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/diff/diff_between_netpol-diff-example-minimal_and_netpol-analysis-example-minimal.txt[Output generated by the `roxctl netpol connectivity diff` command. Example 1: text format] +* link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/diff/diff_between_netpol-diff-example-minimal_and_netpol-analysis-example-minimal.md[Output generated by the `roxctl netpol connectivity diff` command. Example 2: md format] +* link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/diff/diff_between_netpol-diff-example-minimal_and_netpol-analysis-example-minimal.dot.svg[Output generated by the `roxctl netpol connectivity diff` command. Example 3: svg graph generated from dot format] +* link:https://github.com/np-guard/netpol-analyzer/blob/main/test_outputs/diff/diff_between_netpol-diff-example-minimal_and_netpol-analysis-example-minimal.csv[Output generated by the `roxctl netpol connectivity diff` command. Example 4: csv format] + +include::modules/distinguishing-between-syntactic-and-semantic-difference-outputs.adoc[leveloffset=+2] + +include::modules/syntactic-difference-output.adoc[leveloffset=+3] + +include::modules/semantic-difference-output.adoc[leveloffset=+3] \ No newline at end of file diff --git a/operating/compliance-operator-rhacs.adoc b/operating/compliance-operator-rhacs.adoc new file mode 100644 index 000000000000..8e7f7dfa6eff --- /dev/null +++ b/operating/compliance-operator-rhacs.adoc @@ -0,0 +1,52 @@ +:_mod-docs-content-type: ASSEMBLY +[id="compliance-operator-rhacs"] += Using the Compliance Operator with {product-title} +include::modules/common-attributes.adoc[] +:context: compliance-operator-rhacs + +toc::[] + +[role="_abstract"] +You can configure {product-title-short} to use the Compliance Operator for compliance reporting and remediation with {ocp} clusters. Results from the Compliance Operator are reported in the {product-title-short} Compliance Dashboard. + +The default compliance profiles in {product-title-short} only scan the user workloads. The Compliance Operator adds compliance profiles suitable for the rest of the {ocp} infrastructure. Therefore, installing the Compliance Operator provides a complete environment scanning solution. + +[NOTE] +==== +You must install the Compliance Operator on the cluster where Central is installed and on each secured cluster that you want reviewed for compliance. +==== + +The Compliance Operator automates the review of numerous technical implementations and compares them with certain aspects of industry standards, benchmarks, and baselines. + +The Compliance Operator is not an auditor. To comply or certify to these various standards, you must engage an authorized auditor such as a Qualified Security Assessor (QSA), Joint Authorization Board (JAB), or other industry-recognized regulatory authority to assess your environment. + +The Compliance Operator makes recommendations based on generally available information and practices that relate to such standards and can assist with remediation, but actual compliance is your responsibility. You are required to work with an authorized auditor to achieve compliance with a standard. + +For the latest updates, see the link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-latest-version}/html/security_and_compliance/compliance-operator#compliance-operator-release-notes[Compliance Operator release notes]. + + +//Installing the Compliance Operator +include::modules/compliance-operator-install.adoc[leveloffset=+1] + +.Next steps + +* xref:../operating/compliance-operator-rhacs.adoc#compliance-operator-configure-scanning_compliance-operator-rhacs[Configuring the ScanSettingBinding object] + + +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage-compliance/using-openshift-compliance.adoc#customizing-and-automating-your-compliance-scans_using-openshift-compliance[Customizing and automating your compliance scans] + +//Configuring the ScanSettingBinding object +include::modules/compliance-operator-configure-scanning.adoc[leveloffset=+1] + +// See https://docs.openshift.com/container-platform/4.12/security/compliance_operator/compliance-scans.html#running-compliance-scans_compliance-operator-scans. + +[role="_additional-resources"] +.Additional resources + +* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-latest-version}/html/security_and_compliance/compliance-operator#understanding-compliance-operator[Understanding the Compliance Operator] +* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-latest-version}/html/security_and_compliance/compliance-operator#compliance-operator-scans[Compliance Operator scans] +* xref:../operating/manage-compliance/using-the-compliance-dashboard.adoc#checking-the-compliance-status-of-your-infrastructure_using-the-compliance-dashboard[Checking the compliance status of your infrastructure] +* xref:../operating/manage-compliance/using-the-compliance-dashboard.adoc#viewing-the-compliance-standards-across-your-environment_using-the-compliance-dashboard[Viewing the compliance standards across your environment] +* xref:../operating/manage-compliance/using-openshift-compliance.adoc#assessing-the-profile-compliance-across-clusters_using-openshift-compliance[Assessing the profile compliance across clusters] \ No newline at end of file diff --git a/operating/create-use-collections.adoc b/operating/create-use-collections.adoc new file mode 100644 index 000000000000..971148e0cd98 --- /dev/null +++ b/operating/create-use-collections.adoc @@ -0,0 +1,58 @@ +:_mod-docs-content-type: ASSEMBLY +[id="create-use-collections"] += Creating and using deployment collections +include::modules/common-attributes.adoc[] +:context: create-use-collections + +toc::[] + +[role="_abstract"] + +You can use collections in {product-title-short} to define and name a group of resources by using matching patterns. You can then configure system processes to use these collections. + +Currently, collections are available only under the following conditions: + +* Collections are available only for deployments. +* You can only use collections with vulnerability reporting. See "Vulnerability reporting" in the Additional resources section for more information. +* Deployment collections are only available to {product-title-short} customers if they are using the PostgreSQL database. ++ +[NOTE] +==== +By default, {product-title-managed-short} uses the PostgreSQL database, and it is also used by default when installing {product-title-short} release 4.0 and later. {product-title-short} customers using an earlier release than 3.74 can migrate to the PostgreSQL database with help from Red{nbsp}Hat. +==== + +[id="prerequisites_collections"] +== Prerequisites + +A user account must have the following permissions to use the Collections feature: + +* `WorkflowAdministration`: You must have *Read* access to view collections and *Write* access to add, change, or delete collections. +* `Deployment`: You need *Read Access* or *Read and Write Access* to understand how configured rules will match with deployments. + +These permissions are included in the `Admin` system role. For more information about roles and permissions, see "Managing RBAC in {product-title-short}" in "Additional resources". + +include::modules/object-collections.adoc[leveloffset=+1] + +include::modules/access-object-collections.adoc[leveloffset=+1] + +include::modules/create-object-collections.adoc[leveloffset=+1] + +include::modules/create-collection-rules.adoc[leveloffset=+2] + +include::modules/using-regular-expression.adoc[leveloffset=+3] + +include::modules/adding-attached-collections.adoc[leveloffset=+2] + +include::modules/migrate-scope-collections.adoc[leveloffset=+1] + +[id="API_support_collections"] +== Managing collections by using the API + +You can configure collections by using the `CollectionService` API object. For example, you can use `CollectionService_DryRunCollection` to return a list of results equivalent to the live preview panel in the {product-title-short} portal. For more information, go to *Help* -> *API reference* in the {product-title-short} portal. + +[role="_additional-resources"] +.Additional resources + +* xref:../operating/manage-user-access/manage-role-based-access-control-3630.adoc#manage-role-based-access-control[Managing RBAC in {product-title-short}] +* xref:../operating/manage-vulnerabilities/vulnerability-reporting.adoc#vulnerability-reporting[Vulnerability reporting] +* link:https://github.com/google/re2/wiki/Syntax[RE2 regular expression syntax] diff --git a/operating/evaluate-security-risks.adoc b/operating/evaluate-security-risks.adoc new file mode 100644 index 000000000000..eb77b7058f02 --- /dev/null +++ b/operating/evaluate-security-risks.adoc @@ -0,0 +1,57 @@ +[id="evaluate-security-risks"] += Evaluating security risks +include::modules/common-attributes.adoc[] +:context: evaluate-security-risks + +toc::[] + +[role="_abstract"] +{product-title} assesses risk across your entire environment and ranks your running deployments according to their security risk. +It also provides details about vulnerabilities, configurations, and runtime activities that require immediate attention. + +include::modules/risk-view-details.adoc[leveloffset=+1] + +include::modules/open-risk-view.adoc[leveloffset=+2] + +include::modules/create-policy-from-risk-view.adoc[leveloffset=+1] + +include::modules/understanding-filtering-to-policy-mapping.adoc[leveloffset=+2] + +[id="view-risk-details"] +== Viewing risk details + +When you select a deployment in the *Risk* view, the *Risk Details* open in a panel on the right. +The *Risk Details* panel shows detailed information grouped by multiple tabs. + +include::modules/risk-indicators-tab.adoc[leveloffset=+2] + +[id="risk-deployment-details-tab"] +== Deployment Details tab + +The sections in the *Deployment Details* tab of the *Deployment Risk* panel provide more information so you can make appropriate decisions on how to address the discovered risk. + +include::modules/risk-deployment-details-overview.adoc[leveloffset=+2] + +include::modules/risk-deployment-details-container-configuration.adoc[leveloffset=+2] + +include::modules/risk-deployment-details-security-context.adoc[leveloffset=+2] + +include::modules/process-discovery-tab.adoc[leveloffset=+1] + +include::modules/process-discovery-event-timeline.adoc[leveloffset=+2] + +include::modules/use-process-baselines.adoc[leveloffset=+1] + +include::modules/view-process-baselines.adoc[leveloffset=+2] + +include::modules/add-process-to-baseline.adoc[leveloffset=+2] + +include::modules/remove-process-from-baseline.adoc[leveloffset=+2] + +include::modules/lock-and-unlock-process-baselines.adoc[leveloffset=+2] + +include::modules/auto-lock-process-baselines.adoc[leveloffset=+2] + +include::modules/auto-lock-process-baselines-known-limitations.adoc[leveloffset=+3] + +include::modules/bulk-locking-and-unlocking-process-baselines.adoc[leveloffset=+3] diff --git a/operating/examine-images-for-vulnerabilities.adoc b/operating/examine-images-for-vulnerabilities.adoc new file mode 100644 index 000000000000..10eb9620f43c --- /dev/null +++ b/operating/examine-images-for-vulnerabilities.adoc @@ -0,0 +1,204 @@ +:_mod-docs-content-type: ASSEMBLY +[id="examine-images-for-vulnerabilities"] += Examining images for vulnerabilities +include::modules/common-attributes.adoc[] +:context: examine-images-for-vulnerabilities + +toc::[] + +[role="_abstract"] +With {product-title}, you can analyze images for vulnerabilities using the {product-title-short} Scanner V4, or you can xref:../integration/integrate-with-image-vulnerability-scanners.adoc#integrate-with-image-vulnerability-scanners[configure an integration] to use another supported scanner. + +{product-title-short} scanners analyze each image layer to find packages and match them against known vulnerabilities by comparing them with a vulnerability database populated from different sources. These sources include Red{nbsp}Hat Vulnerability Exchange (VEX), the National Vulnerability Database (NVD), the Open Source Vulnerabilities (OSV) database, and operating system vulnerability feeds. + +[NOTE] +==== +{product-title-short} uses the OSV database available at link:https://osv.dev/[OSV.dev] under link:https://github.com/google/osv.dev/blob/master/LICENSE[Apache License 2.0]. +==== + +{product-title-short} contains two scanners: Scanner V4 and the StackRox Scanner. + +Scanner V4, built on Claircore, is the default scanner as of release 4.8. The StackRox Scanner, which originates from a fork of the Clair v2 open source scanner, is deprecated. + +[NOTE] +==== +When this documentation uses the term "{product-title-short} scanner" or "Scanner", it refers to Scanner V4. +==== + +When the {product-title-short} scanner finds any vulnerabilities, it performs the following actions: + +* Shows them in the xref:../operating/manage-vulnerabilities/common-vuln-management-tasks.adoc#common-vuln-management-tasks[*Vulnerability Management*] view for detailed analysis +* Ranks vulnerabilities according to risk and highlights them in the {product-title-short} portal for risk assessment +* Checks them against enabled xref:../operating/manage_security_policies/about-security-policies.adoc#about-security-policies[security policies] + +The {product-title-short} scanner inspects the images and identifies the installed components based on the files in the images. +It might fail to identify installed components or vulnerabilities if the final images are modified to remove the following files: + +[cols=",a"options="header"] +|=== +|Components |Files + +|Package managers +| +* `/etc/alpine-release` +* `/etc/lsb-release` +* `/etc/os-release` or `/usr/lib/os-release` +* `/etc/oracle-release`, `/etc/centos-release`, `/etc/redhat-release`, or `/etc/system-release` +* Other similar system files. + +|Language-level dependencies +| +* `package.json` for JavaScript. +* `dist-info` or `egg-info` for Python. +* `MANIFEST.MF` in Java Archive (JAR) for Java. + +|Application-level dependencies +| +* `dotnet/shared/Microsoft.AspNetCore.App/` +* `dotnet/shared/Microsoft.NETCore.App/` + +|=== + +//About Scanner V4 +include::modules/consolidated-scanner.adoc[leveloffset=+1] + +[id="enabling_scanner_v4_{context}"] +== Enabling Scanner V4 + +Scanner V4 is enabled by default when {product-title-short} is newly installed. However, if you have not previously enabled Scanner V4 and are upgrading from version 4.7 or earlier, you must enable it explicitly during the upgrade to use it. For more information, see the following sections. + +[id="enabling-scanner-v4-after-installation-operator_{context}"] +=== Enabling Scanner V4 after installing by using the Operator + +To use Scanner V4, you can enable it after installation on the cluster where Central is installed and on secured clusters. + +include::modules/enabling-scanner-v4-after-operator-installation-central.adoc[leveloffset=+3] + +include::modules/enabling-scanner-v4-after-operator-installation-secured-cluster.adoc[leveloffset=+3] + +[id="enabling-scanner-v4-after-installation-helm_{context}"] +=== Enabling Scanner V4 after installing by using Helm + +To use Scanner V4, you can enable it after installation on the cluster where Central is installed and on secured clusters. + +include::modules/enabling-scanner-v4-after-helm-installation-central.adoc[leveloffset=+3] + +include::modules/enabling-scanner-v4-after-helm-installation-secured-cluster.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources + +* xref:../installing/installing_ocp/install-central-ocp.adoc#change-config-options-after-deployment-central-services_install-central-ocp[Changing configuration options after deploying the central-services Helm chart] +* xref:../installing/installing_ocp/install-central-ocp.adoc#automatically-generated-ca_install-central-ocp[Retrieving the automatically generated certificate authority] +* xref:../upgrading/upgrade-helm.adoc#upgrade-helm[Upgrading using Helm charts] + + +include::modules/scanning-images.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../architecture/acs-architecture.adoc#vulnerability-sources_acs-architecture[Vulnerability sources] + +* xref:../integration/integrate-with-image-vulnerability-scanners.adoc#integrate-with-image-vulnerability-scanners[Integrating with image vulnerability scanners] + +include::modules/redirecting-image-pulls-from-a-source-registry-to-a-mirrored-registry.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-latest-version}/html/images/image-configuration#images-configuration-registry-mirror-configuring_image-configuration[Configuring image registry repository mirroring] + +* xref:../operating/examine-images-for-vulnerabilities.adoc#accessing-delegated-image-scanning_examine-images-for-vulnerabilities[Accessing delegated image scanning] + +* xref:../operating/examine-images-for-vulnerabilities.adoc#scanning-images-by-using-secured-clusters_examine-images-for-vulnerabilities[Scanning images by using secured clusters] + +include::modules/accessing-delegated-image-scanning.adoc[leveloffset=+1] + +include::modules/enhancing-image-scanning-by-accessing-delegated-image-scanning.adoc[leveloffset=+2] + +include::modules/scanning-images-by-using-secured-clusters.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../operating/examine-images-for-vulnerabilities.adoc#redirecting-image-pulls-from-a-source-registry-to-a-mirrored-registry_examine-images-for-vulnerabilities[Redirecting image pulls from a source registry to a mirrored registry] + +[id="installing-and-configuring-scanning-on-secured-clusters_{context}"] +=== Installing and configuring Scanner-slim on secured clusters + +[id="using-the-operator_{context}"] +==== Using the Operator + +{product-title-short} Operator installs a Scanner-slim version on each secured cluster to scan images in the {ocp} integrated registry and optionally other registries. + +For more information, see xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#installing-sc-operator[Installing {product-title-short} on secured clusters by using the Operator]. + + +[id="using-helm_{context}"] +==== Using Helm + +Secured Cluster Services Helm chart (`secured-cluster-services`) installs a Scanner-slim version on each secured cluster. +In Kubernetes, the secured cluster services include Scanner-slim. +On {ocp}, however, {product-title-short} installs a Scanner-slim version on each secured cluster to scan images in the {ocp} integrated registry and optionally other registries. + +* For {ocp} installations, see xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#installing-secured-cluster-services-quickly_install-secured-cluster-ocp[Installing the secured-cluster-services Helm chart without customization]. + +* For non-{ocp} installations, such as Amazon Elastic Kubernetes Service (Amazon EKS), Google Kubernetes Engine (Google GKE), and Microsoft Azure Kubernetes Service (Microsoft AKS), see xref:../installing/installing_other/install-secured-cluster-other.adoc#installing-secured-cluster-services-quickly_install-secured-cluster-other[Installing the secured-cluster-services Helm chart without customization]. + +[id="verifying-after-installation_{context}"] +==== Verifying after installation + +.Procedure + +* Verify that the status of the secured cluster indicates that Scanner is present and healthy: +.. In the {product-title-short} portal, go to *Platform Configuration -> Clusters*. +.. In the *Clusters* view, select a cluster to view its details. +.. In the *Health Status* card, ensure that *Scanner* is present and is marked as *Healthy.* + +[id="using-image-scanning_{context}"] +==== Using image scanning + +You can scan images stored in a cluster specific {ocp} integrated image registry by using `roxctl` CLI, Jenkins, and API. You can specify the appropriate cluster in the delegated scanning configuration or use the cluster parameter available in `roxctl` CLI, Jenkins, and API. + +For more information about how to scan images by using the `roxctl` CLI, see xref:../cli/image-scanning-by-using-the-roxctl-cli.adoc#image-scanning-by-using-the-roxctl-cli[Image scanning by using the roxctl CLI]. + +[id="setting-up-scanning_{context}"] +== Setting up scanning + +You can configure settings for scanning, such as automatic scanning of active and inactive images. + +include::modules/periodic-scanning-of-images.adoc[leveloffset=+2] + +include::modules/scan-inactive-images.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../operating/examine-images-for-vulnerabilities.adoc#scan-inactive-images_examine-images-for-vulnerabilities[Scanning inactive images] +* xref:../cli/installing-the-roxctl-cli.adoc#installing-the-roxctl-cli[Installing the roxctl CLI] + +[id="about-vulnerabilities_{context}"] +== About vulnerabilities + +//Removed a lot of "additional resources" and added link below to the vulnerability management chapter, common vulnerability management tasks + +{product-title-short} fetches vulnerability definitions and updates from multiple vulnerability feeds. These feeds are both general in nature, such as NVD, or distribution-specific, such as Alpine, Debian, and Ubuntu. For more information on viewing and addressing vulnerabilities that are found, see xref:../operating/manage-vulnerabilities/vulnerability-management.adoc#vulnerability-management[Vulnerability management]. + +include::modules/fetching-vulnerability-definitions.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../architecture/acs-architecture.adoc#vulnerability-sources_acs-architecture[Vulnerability sources] + +include::modules/understanding-vulnerability-scores.adoc[leveloffset=+2] + +//moved identify-dockerfile-line-component-cve.adoc to common vulnerability management chapter + +include::modules/disable-language-specific-vulnerability-scanning.adoc[leveloffset=+1] + +[id="additional-resources_examine-images-for-vulnerabilities"] +== Additional resources + +* link:https://access.redhat.com/security/cve[Red{nbsp}Hat CVE Database] \ No newline at end of file diff --git a/applications/deployments/images b/operating/images similarity index 100% rename from applications/deployments/images rename to operating/images diff --git a/operating/manage-compliance/compliance-feature-overview.adoc b/operating/manage-compliance/compliance-feature-overview.adoc new file mode 100644 index 000000000000..d9532901f9a3 --- /dev/null +++ b/operating/manage-compliance/compliance-feature-overview.adoc @@ -0,0 +1,50 @@ +:_mod-docs-content-type: ASSEMBLY +[id="compliance-feature-overview"] += Compliance feature overview +include::modules/common-attributes.adoc[] +:context: compliance-feature-overview + +toc::[] + +The compliance feature ensures that your Kubernetes clusters adhere to industry standards and regulatory requirements. It provides automated compliance checks that enable you to continuously monitor your clusters against predefined benchmarks such as CIS, PCI-DSS, HIPAA, and so on. + +The feature includes detailed reports and remediation guidance to help administrators quickly identify and resolve compliance issues. You can view the compliance results associated with your cluster by using the compliance feature in the {rh-rhacs-first} portal. + +The compliance feature summarizes information into the following sections: + +* OpenShift infrastructure compliance +* Dashboard (deprecated) + +[id="openshift-infrastructure-compliance_{context}"] +== OpenShift infrastructure compliance + +Formerly known as _Compliance 2.0_, summarizes the compliance information in a single interface after the scheduled scans by using the Compliance Operator. + +[IMPORTANT] +==== +* If you have {osp} clusters with the Compliance Operator installed, you can create and manage compliance scan schedules directly in {product-title-short} on the schedules page. The coverage page shows you the scan results associated with a benchmark and profile in a single interface. + +* You can now use the new OpenShift infrastructure compliance feature to assess compliance across your entire OpenShift cluster fleet and ensure consistent adherence to the security policies of your organization. {product-title-short} now generates reports even if some clusters in a scheduled scan fail, so that you can maintain visibility into the compliance status of successfully scanned clusters without data gaps. ++ +For more information, see xref:../../operating/manage-compliance/using-openshift-compliance.adoc#using-openshift-compliance[Using OpenShift compliance]. +==== + +[NOTE] +==== +To access the Compliance menu and API, a user must have at least read permissions for the `Compliance` resource and read permissions for the `Cluster` resource. Additionally, to use email notifiers in the scan schedule configuration, the user requires read permissions for the `Integration` resource. +==== + +[id="dashboard_{context}"] +== Dashboard (deprecated) + +Formerly known as _Compliance 1.0_, summarizes the compliance information collected from all your clusters. It covers workload and infrastructure compliance. The dashboard is deprecated in {product-title-short} 4.8 and will be removed in a future release. + +[IMPORTANT] +==== +By running a compliance scan in {product-title-short}, you can monitor the entire Kubernetes infrastructure and workloads and ensure that they meet the required standards. You can use the compliance dashboard for filtering and detailed reporting. + +For more information, see xref:../../operating/manage-compliance/using-the-compliance-dashboard.adoc#using-the-compliance-dashboard[Using the compliance dashboard (deprecated)]. +==== + +//Compliance assessment and reporting by using {product-title-short} +include::modules/compliance-assessment-and-reporting-by-using-rhacs.adoc[leveloffset=+2] diff --git a/installing/installing_ibm_z/images b/operating/manage-compliance/images similarity index 100% rename from installing/installing_ibm_z/images rename to operating/manage-compliance/images diff --git a/installing/installing_ibm_power/modules b/operating/manage-compliance/modules similarity index 100% rename from installing/installing_ibm_power/modules rename to operating/manage-compliance/modules diff --git a/operating/manage-compliance/snippets b/operating/manage-compliance/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/operating/manage-compliance/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/operating/manage-compliance/using-openshift-compliance.adoc b/operating/manage-compliance/using-openshift-compliance.adoc new file mode 100644 index 000000000000..3404d12a5d5d --- /dev/null +++ b/operating/manage-compliance/using-openshift-compliance.adoc @@ -0,0 +1,54 @@ +:_mod-docs-content-type: ASSEMBLY +[id="using-openshift-compliance"] += Using OpenShift compliance +include::modules/common-attributes.adoc[] +:context: using-openshift-compliance + +toc::[] + +You can create and manage compliance scan schedules on the schedules page that meet your operational needs. You can only have one schedule that scans the same profile on the same cluster. + +By viewing and filtering the scan results on the coverage page, you can monitor the compliance status across all clusters. + +//Customizing and automating your compliance scans +include::modules/customizing-and-automating-your-compliance-scans.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../operating/compliance-operator-rhacs.adoc#compliance-operator-rhacs[Using the Compliance Operator with {product-title}] + +//Analyzing compliance scan schedules +include::modules/analyzing-compliance-scan-schedules.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../../operating/manage-compliance/using-openshift-compliance.adoc#customizing-and-automating-your-compliance-scans_using-openshift-compliance[Customizing and automating your compliance scans] + +//OpenShift Schedules page overview +include::modules/schedules-page-overview.adoc[leveloffset=+2] + +//Configuration details tab +include::modules/configuration-details-tab.adoc[leveloffset=+3] + +//All report jobs tab +include::modules/all-report-jobs-tab.adoc[leveloffset=+3] + +//Assessing the profile compliance across clusters +include::modules/assessing-the-profile-compliance-across-clusters.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../operating/compliance-operator-rhacs.adoc#compliance-operator-rhacs[Using the Compliance Operator with {product-title}] +* xref:../../operating/manage-compliance/using-openshift-compliance.adoc#customizing-and-automating-your-compliance-scans_using-openshift-compliance[Customizing and automating your compliance scans] + +//OpenShift Coverage page overview +include::modules/coverage-page-overview.adoc[leveloffset=+2] + +//Monitoring and analyzing the health of your clusters +include::modules/monitoring-and-analyzing-the-health-of-your-clusters.adoc[leveloffset=+2] + +//Compliance scan status overview +include::modules/compliance-scan-status-overview.adoc[leveloffset=+2] \ No newline at end of file diff --git a/operating/manage-compliance/using-the-compliance-dashboard.adoc b/operating/manage-compliance/using-the-compliance-dashboard.adoc new file mode 100644 index 000000000000..6b41ce1d3ed3 --- /dev/null +++ b/operating/manage-compliance/using-the-compliance-dashboard.adoc @@ -0,0 +1,49 @@ +:_mod-docs-content-type: ASSEMBLY +[id="using-the-compliance-dashboard"] += Using the compliance dashboard (deprecated) +include::modules/common-attributes.adoc[] +:context: using-the-compliance-dashboard + +toc::[] + +By performing compliance scans, you can check the compliance status of your entire infrastructure in {product-title-short}. You can view the results in the compliance dashboard, where you can filter data and monitor compliance status across clusters, namespaces and nodes. + +By generating detailed compliance reports and focusing on specific standards, controls and industry benchmarks, you can track and share the compliance status of your environment, and ensure that your infrastructure meets the required compliance standards. + +// Checking the compliance status of your infrastructure +include::modules/checking-the-compliance-status-of-your-infrastructure.adoc[leveloffset=+1] + +// Viewing the compliance standards across your environment +include::modules/viewing-the-compliance-standards-across-your-environment.adoc[leveloffset=+1] + +// Compliance dashboard overview +include::modules/compliance-dashboard-overview.adoc[leveloffset=+1] + +// Viewing the compliance status for clusters +include::modules/viewing-the-compliance-status-for-clusters.adoc[leveloffset=+2] + +// Viewing the compliance status for namespaces +include::modules/viewing-the-compliance-status-for-namespaces.adoc[leveloffset=+2] + +// Viewing the compliance status for a specific standard +include::modules/viewing-the-compliance-status-for-a-specific-standard.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../../operating/manage_security_policies/about-security-policies.adoc#about-security-policies[About security policies] + +// Viewing the compliance status for a specific control +include::modules/viewing-the-compliance-status-for-a-specific-control.adoc[leveloffset=+2] + +// Limiting the amount of data visible in the compliance dashboard +include::modules/limiting-the-amount-of-data-visible-in-the-compliance-dashboard.adoc[leveloffset=+1] + +// Tracking the compliance status of your environment +include::modules/tracking-the-compliance-status-of-your-environment.adoc[leveloffset=+1] + +// Evidence reports +include::modules/evidence-reports.adoc[leveloffset=+2] + +// Supported benchmark versions +include::modules/supported-benchmark-versions.adoc[leveloffset=+1] \ No newline at end of file diff --git a/operating/manage-network-policies.adoc b/operating/manage-network-policies.adoc new file mode 100644 index 000000000000..9ea42d37ce03 --- /dev/null +++ b/operating/manage-network-policies.adoc @@ -0,0 +1,70 @@ +:_mod-docs-content-type: ASSEMBLY +[id="manage-network-policies"] += Managing network policies +include::modules/common-attributes.adoc[] +:context: manage-network-policies + +toc::[] + +[role="_abstract"] +A https://kubernetes.io/docs/concepts/services-networking/network-policies/[Kubernetes network policy] is a specification of how groups of pods are allowed to communicate with each other and other network endpoints. +These network policies are configured as YAML files. +By looking at these files alone, it is often hard to identify whether the applied network policies achieve the desired network topology. + +{rh-rhacs-first} gathers all defined network policies from your orchestrator and provides tools to make these policies easier to use. + +To support network policy enforcement, {product-title-short} provides the following tools: + +* Network graph +* Network policy generator +* Network policy simulator +* Build-time network policy generator + +[id="network-graph-20-docs"] +== Network graph + +include::modules/network-graph-20-view.adoc[leveloffset=+2] + +include::modules/rbac-for-network-graph.adoc[leveloffset=+2] + +.Additional resources +* xref:../operating/manage-user-access/manage-role-based-access-control-3630.adoc#rbac-permission-sets_manage-role-based-access-control[System permission sets] + +include::modules/view-deployment-info.adoc[leveloffset=+2] + +include::modules/view-network-policies-ng20.adoc[leveloffset=+2] + +include::modules/configure-cidr-blocks-ng20.adoc[leveloffset=+2] + +[id="network-graph-simulate-generate"] +== Using the network graph to generate and simulate network policies + +include::modules/policy-generation-strategy-ng20.adoc[leveloffset=+2] + +include::modules/generate-network-policies-ng20.adoc[leveloffset=+2] + +include::modules/save-generated-policies-ng20.adoc[leveloffset=+2] + +include::modules/test-generated-policies-ng20.adoc[leveloffset=+2] + +include::modules/delete-generated-policies-ng20.adoc[leveloffset=+2] + +include::modules/delete-all-autogenerated-policies-ng20.adoc[leveloffset=+2] + +include::modules/simulate-network-policies-ng20.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../configuration/enable-offline-mode.adoc#update-kernel-support-packages_enable-offline-mode[Updating kernel support packages in offline mode] +* xref:../integration/integrate-using-generic-webhooks.adoc#integrate-using-generic-webhooks[Integrating using generic webhooks] + +//About network baselining in the network graph +include::modules/use-network-baselining-ng20.adoc[leveloffset=+1] + +include::modules/view-network-baselines-ng20.adoc[leveloffset=+2] + +include::modules/download-network-baselines.adoc[leveloffset=+2] + +include::modules/configuring-network-baselining-timeframe.adoc[leveloffset=+2] + +include::modules/enable-alert-on-baseline-violations-ng20.adoc[leveloffset=+2] diff --git a/operating/manage-user-access/configure-short-lived-access.adoc b/operating/manage-user-access/configure-short-lived-access.adoc new file mode 100644 index 000000000000..302ef2fbc8ba --- /dev/null +++ b/operating/manage-user-access/configure-short-lived-access.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: ASSEMBLY +[id="configure-short-lived-access"] += Configuring short-lived access +include::modules/common-attributes.adoc[] +:context: configure-short-lived-access + +toc::[] + +[role="_abstract"] + +{rh-rhacs-first} provides the ability to configure short-lived access to the user interface and API calls. + +You can configure this by exchanging OpenID Connect (OIDC) identity tokens for a {product-title-short}-issued token. +This is sometimes called machine to machine authentication. + +We recommend this especially for Continuous Integration (CI) usage, where short-lived access is preferable over long-lived API tokens. + +The following steps outline the high-level workflow on how to configure short-lived access to the user interface and API calls: + +. Configuring {product-title-short} to trust OIDC identity token issuers for exchanging short-lived {product-title-short}-issued tokens. +. Exchanging an OIDC identity token for a short-lived {product-title-short}-issued token by calling the API. + +include::snippets/note-about-creating-tokens.adoc[] + +[role="_additional-resources"] +.Additional resources + +* link:https://github.com/stackrox/contributions/blob/main/guides/cloud-provider-integrations/azure-service-principal-m2m-auth.md[Using Azure Entra ID service principals for machine to machine auth with RHACS] +* xref:../../cli/using-the-roxctl-cli.adoc#using-an-authentication-provider-to-authenticate-with-roxctl_using-roxctl-cli[Using an authentication provider to authenticate with roxctl] +* xref:../../configuration/configure-api-token.adoc#configure-api-token[Configuring API tokens] + +include::modules/configure-short-lived-access.adoc[leveloffset=+1] + +include::modules/exchanging-identity-token.adoc[leveloffset=+1] diff --git a/operating/manage-user-access/configuring-identity-providers/configure-google-workspace-identity.adoc b/operating/manage-user-access/configuring-identity-providers/configure-google-workspace-identity.adoc new file mode 100644 index 000000000000..6e7e36eb185d --- /dev/null +++ b/operating/manage-user-access/configuring-identity-providers/configure-google-workspace-identity.adoc @@ -0,0 +1,15 @@ +[id="configure-google-workspace-identity"] += Configuring Google Workspace as an OIDC identity provider +include::modules/common-attributes.adoc[] +:context: configure-google-workspace-identity + +toc::[] + +[role="_abstract"] +You can use link:https://workspace.google.com/[Google Workspace] as a single sign-on (SSO) provider for {product-title}. + +include::modules/set-up-oauth-20-credentials-for-your-gcp-project.adoc[leveloffset=+1] + +include::modules/specify-a-client-secret.adoc[leveloffset=+1] + +include::modules/configure-oidc-identity-provider.adoc[leveloffset=+1] diff --git a/operating/manage-user-access/configuring-identity-providers/configure-ocp-oauth.adoc b/operating/manage-user-access/configuring-identity-providers/configure-ocp-oauth.adoc new file mode 100644 index 000000000000..ee59287b660d --- /dev/null +++ b/operating/manage-user-access/configuring-identity-providers/configure-ocp-oauth.adoc @@ -0,0 +1,36 @@ +:_mod-docs-content-type: ASSEMBLY +[id="configure-ocp-oauth"] += Configuring {ocp} OAuth server as an identity provider +include::modules/common-attributes.adoc[] +:context: configure-ocp-oauth + +toc::[] + +[role="_abstract"] +{ocp} includes a built-in OAuth server that you can use as an authentication provider for {product-title} ({product-title-short}). + +include::modules/configure-ocp-oauth-identity-provider.adoc[leveloffset=+1] + +[IMPORTANT] +==== +* If you use a custom TLS certificate for {ocp} OAuth server, you must add the root certificate of the CA to {product-title} as a trusted root CA. Otherwise, Central cannot connect to the {ocp} OAuth server. +* To enable the {ocp} OAuth server integration when installing {product-title} using the `roxctl` CLI, set the `ROX_ENABLE_OPENSHIFT_AUTH` environment variable to `true` in Central: ++ +[source,terminal] +---- +$ oc -n stackrox set env deploy/central ROX_ENABLE_OPENSHIFT_AUTH=true +---- +* For access rules, the {ocp} OAuth server does not return the key `Email`. +==== + +[role="_additional-resources"] +.Additional resources +* link:https://docs.openshift.com/container-platform/4.12/authentication/identity_providers/configuring-ldap-identity-provider.html[Configuring an LDAP identity provider] +* xref:../../../configuration/add-trusted-ca.adoc#add-trusted-ca[Adding trusted certificate authorities] + +include::modules/create-additional-routes-ocp-oauth.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* link:https://docs.openshift.com/container-platform/4.12/authentication/using-service-accounts-as-oauth-client.html#service-accounts-as-oauth-clients_using-service-accounts-as-oauth-client[Service accounts as OAuth clients] +* link:https://docs.openshift.com/container-platform/4.12/authentication/using-service-accounts-as-oauth-client.html#redirect-uris-for-service-accounts_using-service-accounts-as-oauth-client[Redirect URIs for service accounts as OAuth clients] diff --git a/operating/manage-user-access/configuring-identity-providers/configure-okta-identity-cloud.adoc b/operating/manage-user-access/configuring-identity-providers/configure-okta-identity-cloud.adoc new file mode 100644 index 000000000000..22bb53b15c29 --- /dev/null +++ b/operating/manage-user-access/configuring-identity-providers/configure-okta-identity-cloud.adoc @@ -0,0 +1,13 @@ +[id="configure-okta-identity-cloud"] += Configuring Okta Identity Cloud as a SAML 2.0 identity provider +include::modules/common-attributes.adoc[] +:context: configure-okta-identity-cloud + +toc::[] + +[role="_abstract"] +You can use Okta as a single sign-on (SSO) provider for {product-title} ({product-title-short}). + +include::modules/create-an-okta-app.adoc[leveloffset=+1] + +include::modules/configure-saml-identity-provider.adoc[leveloffset=+1] diff --git a/operating/manage-user-access/configuring-identity-providers/connecting-azure-ad-to-rhacs-using-sso-configuration.adoc b/operating/manage-user-access/configuring-identity-providers/connecting-azure-ad-to-rhacs-using-sso-configuration.adoc new file mode 100644 index 000000000000..7c764ad93889 --- /dev/null +++ b/operating/manage-user-access/configuring-identity-providers/connecting-azure-ad-to-rhacs-using-sso-configuration.adoc @@ -0,0 +1,22 @@ +:_mod-docs-content-type: ASSEMBLY +[id="connecting-azure-ad-to-rhacs-using-sso-configuration"] += Connecting Azure AD to RHACS using SSO configuration +include::modules/common-attributes.adoc[] +:context: user-authentication + +toc::[] + +[role="_abstract"] + +To connect an Azure Active Directory (AD) to {product-title-short} using Sign-On (SSO) configuration, you need to add specific claims (for example, `group` claim to tokens) and assign users, groups, or both to the enterprise application. + +[id="adding-group-claims-to-tokens-for-saml-applications-using-SSO-configuration_{context}"] +== Adding group claims to tokens for SAML applications using SSO configuration + +Configure the application registration in Azure AD to include `group` claims in tokens. For instructions, see link:https://learn.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims#add-group-claims-to-tokens-for-saml-applications-using-sso-configuration[Add group claims to tokens for SAML applications using SSO configuration]. + +[IMPORTANT] +==== +Verify that you are using the latest version of Azure AD. +For more information on how to upgrade Azure AD to the latest version, see link:https://learn.microsoft.com/en-us/azure/active-directory/hybrid/how-to-upgrade-previous-version[Azure AD Connect: Upgrade from a previous version to the latest]. +==== diff --git a/metering/images b/operating/manage-user-access/configuring-identity-providers/images similarity index 100% rename from metering/images rename to operating/manage-user-access/configuring-identity-providers/images diff --git a/jaeger/modules b/operating/manage-user-access/configuring-identity-providers/modules similarity index 100% rename from jaeger/modules rename to operating/manage-user-access/configuring-identity-providers/modules diff --git a/operating/manage-user-access/enable-pki-authentication.adoc b/operating/manage-user-access/enable-pki-authentication.adoc new file mode 100644 index 000000000000..c204223f12a0 --- /dev/null +++ b/operating/manage-user-access/enable-pki-authentication.adoc @@ -0,0 +1,23 @@ +[id="enable-pki-authentication"] += Enabling PKI authentication +include::modules/common-attributes.adoc[] +:context: enable-pki-authentication + +toc::[] + +[role="_abstract"] +If you use an enterprise certificate authority (CA) for authentication, you can configure {product-title} ({product-title-short}) to authenticate users by using their personal certificates. + +After you configure PKI authentication, users and API clients can log in using their personal certificates. +Users without certificates can still use other authentication options, including API tokens, the local administrator password, or other authentication providers. +PKI authentication is available on the same port number as the Web UI, gRPC, and REST APIs. + +When you configure PKI authentication, by default, {product-title} uses the same port for PKI, web UI, gRPC, other single sign-on (SSO) providers, and REST APIs. You can also configure a separate port for PKI authentication by using a YAML configuration file to configure and expose endpoints. + +include::modules/configure-pki-authentication-portal.adoc[leveloffset=+1] + +include::modules/configure-pki-authentication-roxctl.adoc[leveloffset=+1] + +include::modules/update-authentication-keys-and-certificates.adoc[leveloffset=+1] + +include::modules/log-in-using-client-certificate.adoc[leveloffset=+1] diff --git a/monitoring/images b/operating/manage-user-access/images similarity index 100% rename from monitoring/images rename to operating/manage-user-access/images diff --git a/operating/manage-user-access/manage-role-based-access-control-3630.adoc b/operating/manage-user-access/manage-role-based-access-control-3630.adoc new file mode 100644 index 000000000000..b1a2788c7d92 --- /dev/null +++ b/operating/manage-user-access/manage-role-based-access-control-3630.adoc @@ -0,0 +1,64 @@ +:_mod-docs-content-type: ASSEMBLY +[id="manage-role-based-access-control"] += Managing RBAC in Red Hat Advanced Cluster Security for Kubernetes +include::modules/common-attributes.adoc[] +:context: manage-role-based-access-control + +toc::[] + +[role="_abstract"] +{rh-rhacs-first} comes with role-based access control (RBAC) that you can use to configure roles and grant various levels of access to {product-title} for different users. + +Beginning with version 3.63, {product-title-short} includes a scoped access control feature that enables you to configure fine-grained and specific sets of permissions that define how a given {product-title-short} user or a group of users can interact with {product-title-short}, which resources they can access, and which actions they can perform. + +* _Roles_ are a collection of permission sets and access scopes. You can assign roles to users and groups by specifying rules. You can configure these rules when you configure an authentication provider. +There are two types of roles in {product-title}: +** System roles that are created by Red{nbsp}Hat and cannot be changed. +** Custom roles, which {product-title} administrators can create and change at any time. ++ +[NOTE] +==== +* If you assign multiple roles for a user, they get access to the combined permissions of the assigned roles. +* If you have users assigned to a custom role, and you delete that role, all associated users transfer to the minimum access role that you have configured. +==== + +* _Permission sets_ are a set of permissions that define what actions a role can perform on a given resource. _Resources_ are the functionalities of {product-title} for which you can set view (`read`) and modify (`write`) permissions. There are two types of permission sets in {product-title}: +** System permission sets, which are created by Red{nbsp}Hat and cannot be changed. +** Custom permission sets, which {product-title} administrators can create and change at any time. + +* _Access scopes_ are a set of Kubernetes and {ocp} resources that users can access. For example, you can define an access scope that only allows users to access information about pods in a given project. There are two types of access scopes in {product-title}: +** System access scopes, which are created by Red{nbsp}Hat and cannot be changed. +** Custom access scopes, which {product-title} administrators can create and change at any time. + +include::modules/rbac-system-roles-3630.adoc[leveloffset=+1] + +include::modules/view-system-roles-permission-scope.adoc[leveloffset=+2] + +include::modules/create-a-custom-role-3630.adoc[leveloffset=+2] + +[role="additional-resources"] +.Additional resources +* xref:../../operating/manage-user-access/manage-role-based-access-control-3630.adoc#create-a-custom-permission-set_manage-role-based-access-control[Creating a custom permission set] +* xref:../../operating/manage-user-access/manage-role-based-access-control-3630.adoc#create-a-custom-access-scope_manage-role-based-access-control[Creating a custom access scope] + +include::modules/assign-role-to-user-or-group.adoc[leveloffset=+2] + +include::modules/rbac-permission-sets.adoc[leveloffset=+1] + +include::modules/view-system-permission-set.adoc[leveloffset=+2] + +include::modules/create-a-custom-permission-set.adoc[leveloffset=+2] + +include::modules/rbac-access-scopes.adoc[leveloffset=+1] + +include::modules/view-system-access-scopes.adoc[leveloffset=+2] + +include::modules/create-a-custom-access-scope.adoc[leveloffset=+2] + +include::modules/rbac-resource-definitions.adoc[leveloffset=+1] + +include::modules/declarative-configuration-auth-resources.adoc[leveloffset=+1] + +.Additional resources + +* xref:../../configuration/declarative-configuration-using.adoc#declarative-configuration-using[Using declarative configuration] diff --git a/masters/modules b/operating/manage-user-access/modules similarity index 100% rename from masters/modules rename to operating/manage-user-access/modules diff --git a/operating/manage-user-access/remove-admin-user.adoc b/operating/manage-user-access/remove-admin-user.adoc new file mode 100644 index 000000000000..1072f41fc2fa --- /dev/null +++ b/operating/manage-user-access/remove-admin-user.adoc @@ -0,0 +1,31 @@ +:_mod-docs-content-type: ASSEMBLY +[id="remove-admin-user"] += Removing the admin user +include::modules/common-attributes.adoc[] +:context: remove-admin-user + +toc::[] + +[role="_abstract"] + +{rh-rhacs-first} creates an administrator account, `admin`, during the installation process that can be used to log in with a user name and password. +The password is dynamically generated unless specifically overridden and is unique to your {product-title-short} instance. + +In production environments, it is highly recommended to create an authentication provider and remove the `admin` user. + +include::modules/remove-admin-user.adoc[leveloffset=+1] + +.Additional resources + +* xref:../../installing/installing_ocp/install-central-ocp.adoc#change-config-options-after-deployment-central-services_install-central-ocp[Changing configuration options after deploying the central-services Helm chart ({ocp})] + +* xref:../../installing/installing_other/install-central-other.adoc#change-config-options-after-deployment-central-services_install-central-other[Changing configuration options after deploying the central-services Helm chart (Kubernetes)] + +* xref:../../installing/installing_ocp/install-central-ocp.adoc#install-using-roxctl-ocp[Install Central using the roxctl CLI] + +After applying the configuration changes, you cannot log in as an `admin` user. + +[NOTE] +==== +You can add the `admin` user again as a fallback by reverting the configuration changes. When enabling the `admin` user again, a new password is generated. +==== diff --git a/operating/manage-user-access/snippets b/operating/manage-user-access/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/operating/manage-user-access/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/operating/manage-user-access/understanding-authentication-providers.adoc b/operating/manage-user-access/understanding-authentication-providers.adoc new file mode 100644 index 000000000000..47cb67edb34c --- /dev/null +++ b/operating/manage-user-access/understanding-authentication-providers.adoc @@ -0,0 +1,108 @@ +:_mod-docs-content-type: ASSEMBLY +[id="understanding-authentication-providers"] += Understanding authentication providers +include::modules/common-attributes.adoc[] +:context: authentication-provider-structure + +toc::[] + +[role="_abstract"] + +An authentication provider connects to a third-party source of user identity (for example, an identity provider or IDP), gets the user identity, issues a token based on that identity, and returns the token to {rh-rhacs-first}. +This token allows {product-title-short} to authorize the user. +{product-title-short} uses the token within the user interface and API calls. + +After installing {product-title-short}, you must set up your IDP to authorize users. + +[NOTE] +==== +If you are using OpenID Connect (OIDC) as your IDP, {product-title-short} relies on mapping rules that examine the values of specific claims like `groups`, `email`, `userid` and `name` from either the user ID token or the `UserInfo` endpoint response to authorize the users. +If these details are absent, the mapping cannot succeed and the user does not get access to the required resources. +Therefore, you need to ensure that the claims required to authorize users from your IDP, for example, `groups`, are included in the authentication response of your IDP to enable successful mapping. +==== + +[role="_additional-resources"] +.Additional resources +* xref:../../operating/manage-user-access/configuring-identity-providers/configure-okta-identity-cloud.adoc#configure-okta-identity-cloud[Configuring Okta Identity Cloud as a SAML 2.0 identity provider] +* xref:../../operating/manage-user-access/configuring-identity-providers/configure-google-workspace-identity.adoc#configure-google-workspace-identity[Configuring Google Workspace as an OIDC identity provider] +* xref:../../operating/manage-user-access/configuring-identity-providers/configure-ocp-oauth.adoc#configure-ocp-oauth[Configuring OpenShift Container Platform OAuth server as an identity provider] +* xref:../../operating/manage-user-access/configuring-identity-providers/connecting-azure-ad-to-rhacs-using-sso-configuration.adoc#connecting-azure-ad-to-rhacs-using-sso-configuration[Connecting Azure AD to {product-title-short} using SSO configuration] + +[id="auth-provider-claim-mappings"] +== Claim mappings +A claim is the data an identity provider includes about a user inside the token they issue. + +Using claim mappings, you can specify if {product-title-short} should customize the claim attribute it receives from an IDP to another attribute in the {product-title-short}-issued token. If you do not use the claim mapping, {product-title-short} does not include the claim attribute in the {product-title-short}-issued token. + +For example, you can map from `roles` in the user identity to `groups` in the {product-title-short}-issued token using claim mapping. + +{product-title-short} uses different default claim mappings for every authentication provider. + +[id="auth-provider-oidc-default-claim-mappings"] +=== OIDC default claim mappings +The following list provides the default OIDC claim mappings: + +* `sub` to `userid` +* `name` to `name` +* `email` to `email` +* `groups` to `groups` + +[id="auth-provider-auth0-default-claim-mappings"] +=== Auth0 default claim mappings +The `Auth0` default claim mappings are the same as the OIDC default claim mappings. + +[id="auth-provider-saml20-default-claim-mappings"] +=== SAML 2.0 default claim mappings +The following list applies to SAML 2.0 default claim mappings: + +* `Subject.NameID` is mapped to `userid` +* every SAML `AttributeStatement.Attribute` from the response gets mapped to its name + +[id="auth-provider-google-iap-default-claim-mappings"] +=== Google IAP default claim mappings +The following list provides the Google IAP default claim mappings: + +* `sub` to `userid` +* `email` to `email` +* `hd` to `hd` +* `google.access_levels` to `access_levels` + +[id="auth-provider-userpki-default-claim-mappings"] +=== User certificates default claim mappings +User certificates differ from all other authentication providers because instead of communicating with a third-party IDP, they get user information from certificates used by the user. + +The default claim mappings for user certificates include: + +* `CertFingerprint` to `userid` +* `Subject -> Common Name` to `name` +* `EmailAddresses` to `email` +* `Subject -> Organizational Unit` to `groups` + +[id="auth-provider-openshift-auth-default-claim-mappings"] +=== OpenShift Auth default claim mappings +The following list provides the OpenShift Auth default claim mappings: + +* `groups` to `groups` +* `uid` to `userid` +* `name` to `name` + +[id="auth-provider-rules"] +== Rules +To authorize users, {product-title-short} relies on mapping rules that examine the values of specific claims such as `groups`, `email`, `userid`, and `name` from the user identity. +Rules allow mapping of users who have attributes with a specific value to a specific role. As an example, a rule could include the following:`key` is `email`, `value` is `john@redhat.com`, `role` is `Admin`. + +If the claim is missing, the mapping cannot succeed, and the user does not get access to the required resources. +Therefore, to enable successful mapping, you must ensure that the authentication response from your IDP includes the required claims to authorize users, for example, `groups`. + +[id="auth-provider-minimum-access-role"] +== Minimum access role +{product-title-short} assigns a minimum access role to every caller with a {product-title-short} token issued by a particular authentication provider. The minimum access role is set to `None` by default. + +For example, suppose there is an authentication provider with the minimum access role of `Analyst`. In that case, all users who log in using this provider will have the `Analyst` role assigned to them. + +[id="auth-provider-required-attributes"] +== Required attributes +Required attributes can restrict issuing of the {product-title-short} token based on whether a user identity has an attribute with a specific value. + +For example, you can configure {product-title-short} only to issue a token when the attribute with key `is_internal` has the attribute value `true`. +Users with the attribute `is_internal` set to `false` or not set do not get a token. diff --git a/operating/manage-user-access/understanding-multi-tenancy.adoc b/operating/manage-user-access/understanding-multi-tenancy.adoc new file mode 100644 index 000000000000..bc3d3e831080 --- /dev/null +++ b/operating/manage-user-access/understanding-multi-tenancy.adoc @@ -0,0 +1,96 @@ +:_mod-docs-content-type: ASSEMBLY +[id="understanding-multi-tenancy"] += Understanding multi-tenancy +include::modules/common-attributes.adoc[] +:context: understanding-multi-tenancy + +toc::[] + +[role="_abstract"] + +{product-title} provides ways to implement multi-tenancy within a Central instance. + +You can implement multi-tenancy by using role-based access control (RBAC) and access scopes within {product-title-short}. + +[id="understanding-resource-scoping"] +== Understanding resource scoping + +{product-title-short} includes resources which are used within RBAC. +In addition to associating permissions for a resource, each resource is also scoped. + +In {product-title-short}, resources are scoped as the following types: + +* Global scope, where a resource is not assigned to any cluster or namespace +* Cluster scope, where a resource is assigned to particular clusters +* Namespace scope, where a resource is assigned to particular namespaces + +The scope of resources is important when creating custom access scopes. +Custom access scopes are used to create multi-tenancy within {product-title-short}. + +Only resources which are cluster or namespace scoped are applicable for scoping in access scopes. Globally scoped resources are not scoped by access scopes. +Therefore, multi-tenancy within {product-title-short} can only be achieved for resources that are scoped either by cluster or namespace. + +[id="multi-tenancy-per-namespace-config-example"] +== Multi-tenancy per namespace configuration example + +A common example for multi-tenancy within {product-title-short} is associating users with a specific namespace and only allowing them access to their specific namespace. + +The following example combines a custom permission set, access scope, and role. The user or group assigned with this role can only see CVE information, violations, and information about deployments in the particular namespace or cluster scoped to them. + +.Procedure + +. In the {product-title-short} portal, select *Platform Configuration* -> *Access Control*. +. Select *Permission Sets*. +. Click *Create permission set*. +. Enter a *Name* and *Description* for the permission set. +. Select the following resources and access level and click *Save*: +** `READ` Alert +** `READ` Deployment +** `READ` DeploymentExtension +** `READ` Image +** `READ` K8sRole +** `READ` K8sRoleBinding +** `READ` K8sSubject +** `READ` NetworkGraph +** `READ` NetworkPolicy +** `READ` Secret +** `READ` ServiceAccount +. Select *Access Scopes*. +. Click *Create access scope*. +. Enter a *Name* and *Description* for the access scope. +. In the *Allowed resources* section, select the namespace you want to use for scoping and click *Save*. +. Select *Roles*. +. Click *Create role*. +. Enter a *Name* and *Description* for the role. +. Select the previously created *Permission Set* and *Access scope* for the role and click *Save*. +. Assign the role to your required user or group. See xref:../../operating/manage-user-access/manage-role-based-access-control-3630.adoc#assign-role-to-user-or-group_manage-role-based-access-control[Assigning a role to a user or a group]. + +[NOTE] +==== +The {product-title-short} dashboard options for users with the sample role are minimal compared to options available to an administrator. +Only relevant pages are visible for the user. +==== + +[id="mutli-tenancy-limitations"] +== Limitations + +Achieving multi-tenancy within {product-title-short} is not possible for resources with a *global scope*. + +The following resources have a global scope: + +* Access +* Administration +* Detection +* Integration +* VulnerabilityManagementApprovals +* VulnerabilityManagementRequests +* WatchedImage +* WorkflowAdministration + +These resources are shared across all users within a {product-title-short} Central instance and cannot be scoped. + +[role="_additional-resources"] +.Additional resources +* xref:../../operating/manage-user-access/manage-role-based-access-control-3630.adoc#create-a-custom-permission-set_manage-role-based-access-control[Creating a custom permission set] +* xref:../../operating/manage-user-access/manage-role-based-access-control-3630.adoc#create-a-custom-access-scope_manage-role-based-access-control[Create a custom access scope] +* xref:../../operating/manage-user-access/manage-role-based-access-control-3630.adoc#create-a-custom-role-3630_manage-role-based-access-control[Create a custom role] diff --git a/operating/manage-vulnerabilities/common-vuln-management-tasks.adoc b/operating/manage-vulnerabilities/common-vuln-management-tasks.adoc new file mode 100644 index 000000000000..680d47e8a2a8 --- /dev/null +++ b/operating/manage-vulnerabilities/common-vuln-management-tasks.adoc @@ -0,0 +1,137 @@ +:_mod-docs-content-type: ASSEMBLY +[id="common-vuln-management-tasks"] += Viewing and addressing vulnerabilities +include::modules/common-attributes.adoc[] +:context: common-vuln-management-tasks + +toc::[] + +[role="_abstract"] +The *Vulnerability Management* functions provide methods to view and manage vulnerabilities discovered by {product-title-short}. Common vulnerability management tasks involve identifying and prioritizing vulnerabilities, remedying them, and monitoring for new threats. + +For information about the sources used for identifying vulnerabilities, see xref:../../architecture/acs-architecture.adoc#con-vuln-sources_acs-architecture[Vulnerability data sources]. + +//Keep older dashboard info until removed + +Historically, {product-title-short} provided a view of vulnerabilities discovered in your system in the vulnerability management dashboard. The dashboard is deprecated in {product-title-short} 4.5 and will be removed in a future release. + +For more information about the dashboard, see xref:../../operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc#vulnerability-management-dashboard[Using the vulnerability management dashboard]. + +Currently, vulnerability information is provided in pages that are accessed by selecting *Vulnerability Management* -> *Results*. You can select different views based on whether you want to view vulnerabilities discovered in your workloads, vulnerabilities discovered in platform components, such as OpenShift, or node vulnerabilities. Depending on the view, you can filter results based on specific criteria: for example, you can display vulnerabilities of different severity, vulnerabilities in deployments with specific annotations, or vulnerabilities in images that are based on a specific operating system. + +//user workload, platform, and node cve explanation +include::modules/vulnerability-management-components-portal.adoc[leveloffset=+1] + +//viewing vulns in user workloads +include::modules/vulnerability-management20-view-workload-cve.adoc[leveloffset=+1] + +:context: vulns-platforms +//viewing vulns in platforms +include::modules/vulnerability-management20-view-platform-cve.adoc[leveloffset=+1] +:!context: + +:context: vulns-nodes +//Viewing vulns in nodes +include::modules/viewing-node-cves.adoc[leveloffset=+1] + +include::modules/disable-identify-vulnerabilities-in-nodes.adoc[leveloffset=+2] + +.Additional resources +* xref:../../operating/manage-vulnerabilities/scan-rhcos-node-host.adoc#understanding-node-cves-scanner-v4_scan-rhcos-node-host[Understanding differences in scanning results between the StackRox Scanner and Scanner V4] +* xref:../../operating/examine-images-for-vulnerabilities.adoc#supported-operating-systems_examine-images-for-vulnerabilities[Supported operating systems] + +:!context: + +:context: more-views +//more views + +include::modules/vulnerability-management-accessing-additional-views.adoc[leveloffset=+1] + +//all vulnerable images +include::modules/vulnerability-management-more-views-all-vuln-images.adoc[leveloffset=+2] + +//inactive images +include::modules/scan-inactive-images.adoc[leveloffset=+2] + +//Analyze images and deployments without observed CVEs +include::modules/analyze-images-and-deployments-without-observed-cves.adoc[leveloffset=+2] + +//kubernetes components + +include::modules/vulnerability-management-viewing-kubernetes-vulnerabilities.adoc[leveloffset=+2] + +:!context: + +:context: excluding-cves +[id="excluding-CVEs_{context}"] +== Excluding CVEs + +You can exclude or ignore CVEs in {product-title-short} by snoozing node and platform CVEs and deferring or marking node, platform, and image CVEs as false positives. You might want to exclude CVEs if you know that the CVE is a false positive or you have already taken steps to mitigate the CVE. Snoozed CVEs do not appear in vulnerability reports or trigger policy violations. + +You can snooze a CVE to ignore it globally for a specified period of time. Snoozing a CVE does not require approval. + +[NOTE] +==== +Snoozing node and platform CVEs requires that the `ROX_VULN_MGMT_LEGACY_SNOOZE` environment variable is set to `true`. +==== + +Deferring or marking a CVE as a false positive is done through the exception management workflow. This workflow provides the ability to view pending, approved, and denied deferral and false positive requests. You can scope the CVE exception to a single image, all tags for a single image, or globally for all images. + +When approving or denying a request, you must add a comment. A CVE remains in the observed status until the exception request is approved. A pending request for deferral that is denied by another user is still visible in reports, policy violations, and other places in the system, but is indicated by a *Pending exception* label next to the CVE when visiting the following pages after going to *Vulnerability Management* -> *Results*: + +* User workloads +* Platform +* All vulnerable images +* Inactive images + +An approved exception for a deferral or false positive has the following effects: + +* Removes the CVE from the *Observed* tab in the *User Workloads* tab to either the *Deferred* or *False positive* tab +* Prevents the CVE from triggering policy violations that are related to the CVE +* Prevents the CVE from showing up in automatically generated vulnerability reports + +:!context: + +:context: snoozing-cves +//snoozing CVEs +include::modules/snooze-cves-vm20.adoc[leveloffset=+2] + +include::modules/unsnooze-cves-vm20.adoc[leveloffset=+2] + +include::modules/viewing-snoozed-cves.adoc[leveloffset=+2] +:!context: + +:context: marking +//marking as false positives +include::modules/vulnerability-management-mark-false-positive.adoc[leveloffset=+2] + +include::modules/vulnerability-management-mark-false-positive-image.adoc[leveloffset=+2] +:!context: + +:context: deferring +//deferring +include::modules/vulnerability-management-review-deferred.adoc[leveloffset=+2] + +include::modules/vulnerability-management-accept-risks.adoc[leveloffset=+2] + +include::modules/vulnerability-management-exception-time-config.adoc[leveloffset=+3] +:!context: + +:context: approving +//approving +include::modules/vulnerability-management-accept-deferrals-false-positives.adoc[leveloffset=+2] +:!context: + +:context: other +//other +include::modules/identify-dockerfile-line-component-cve.adoc[leveloffset=+1] + +include::modules/vulnerability-management-upgrade-component.adoc[leveloffset=+1] + +include::modules/vulnerability-management-export-workloads.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../../operating/search-filter.adoc#search-filter[Searching and filtering] + +:!context: diff --git a/operating/manage-vulnerabilities/field-trial.adoc b/operating/manage-vulnerabilities/field-trial.adoc new file mode 100644 index 000000000000..f47d066cd08f --- /dev/null +++ b/operating/manage-vulnerabilities/field-trial.adoc @@ -0,0 +1,11 @@ +// When including this file, ensure that {FeatureName} is set immediately before +// the include. Otherwise it will result in an incorrect replacement. + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} is available as a Field Trial release. A Field Trial provides approved customers access to {product-title-managed} for trial purposes. For more information, contact link:https://www.redhat.com/en/contact[Red{nbsp}Hat Sales]. + +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: \ No newline at end of file diff --git a/installing/installing_rhv/images b/operating/manage-vulnerabilities/images similarity index 100% rename from installing/installing_rhv/images rename to operating/manage-vulnerabilities/images diff --git a/applications/deployments/modules b/operating/manage-vulnerabilities/modules similarity index 100% rename from applications/deployments/modules rename to operating/manage-vulnerabilities/modules diff --git a/operating/manage-vulnerabilities/scan-rhcos-node-host.adoc b/operating/manage-vulnerabilities/scan-rhcos-node-host.adoc new file mode 100644 index 000000000000..50c952f40275 --- /dev/null +++ b/operating/manage-vulnerabilities/scan-rhcos-node-host.adoc @@ -0,0 +1,51 @@ +:_mod-docs-content-type: ASSEMBLY +[id="scan-rhcos-node-host"] += Scanning {op-system} node hosts +include::modules/common-attributes.adoc[] +:context: scan-rhcos-node-host + +toc::[] + +[role="_abstract"] +For {ocp}, {op-system-first} is the only supported operating system for control plane. For node hosts, {ocp} supports both {op-system} and {op-system-base-full}. +With {rh-rhacs-first}, you can scan {op-system} nodes for vulnerabilities and detect potential security threats. + +{product-title-short} scans {op-system} RPMs installed on the node host, as part of the {op-system} installation, for any known vulnerabilities. + +First, {product-title-short} analyzes and detects {op-system} components. Then it matches vulnerabilities for identified components by using {op-system-base} and the following data streams: + +* OpenShift 4.X Open Vulnerability and Assessment Language (OVAL) v2 security data streams is used if StackRox Scanner is used for node scanning. +* Red{nbsp}Hat Common Security Advisory Framework (CSAF) Vulnerability Exploitability eXchange (VEX) is used if Scanner V4 is used for node scanning. + +[NOTE] +==== +* If you installed {product-title-short} by using the `roxctl` CLI, you must manually enable the {op-system} node scanning features. When you use Helm or Operator installation methods on {ocp}, this feature is enabled by default. +==== + +[role="_additional-resources"] +.Additional resources +* link:https://access.redhat.com/articles/6907891[RHEL Versions Utilized by RHEL CoreOS and OCP] + +include::modules/rhcos-enable-node-scan.adoc[leveloffset=+1] + +include::modules/rhcos-enable-node-scan-scannerv4.adoc[leveloffset=+1] + +include::modules/rhcos-analyse-detect.adoc[leveloffset=+1] + +include::modules/rhcos-match-vulnerability.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../operating/examine-images-for-vulnerabilities.adoc#enabling_scanner_v4_examine-images-for-vulnerabilities[Enabling Scanner V4] +* xref:../../installing/installing_ocp/install-central-config-options-ocp.adoc#scannerv4-settings_install-central-config-options-ocp[Scanner V4 settings for installing {product-title-short} for {ocp} by using the Operator] +* xref:../../installing/installing_ocp/install-central-ocp.adoc#central-services-public-configuration-file-scannerv4_install-central-ocp[Scanner V4 settings for installing {product-title-short} for {ocp} by using Helm] +* xref:../../installing/installing_other/install-central-other.adoc#central-services-public-configuration-file-scannerv4_install-central-other[Scanner V4 settings for installing {product-title-short} for Kubernetes by using Helm] + +include::modules/rhcos-environment-variables.adoc[leveloffset=+1] + +include::modules/identify-vulnerabilities-in-nodes.adoc[leveloffset=+1] + +include::modules/viewing-node-cves.adoc[leveloffset=+1] + +include::modules/understanding-node-cves-scanner-v4.adoc[leveloffset=+1] diff --git a/operating/manage-vulnerabilities/scanner-generate-sbom.adoc b/operating/manage-vulnerabilities/scanner-generate-sbom.adoc new file mode 100644 index 000000000000..3f17f278f662 --- /dev/null +++ b/operating/manage-vulnerabilities/scanner-generate-sbom.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: ASSEMBLY +[id="scanner-generate-sbom"] += Generating SBOMs from scanned images +include::modules/common-attributes.adoc[] +:context: scanner-generate-sbom + +toc::[] + +[role="_abstract"] + +You can use {product-title-short} to generate a Software Bill of Materials (SBOM) from scanned container images. + +SBOMs give you a detailed overview of software components, dependencies, and libraries within your application. {product-title-short} uses the results of scans performed by {product-title-short} to generate an SBOM. You can generate an SBOM by using the {product-title-short} portal, the `roxctl` CLI, or the {product-title-short} API. + +include::modules/sbom-about.adoc[leveloffset=+1] + +include::modules/sbom-generate.adoc[leveloffset=+1] + +//Generating SBOMs by using the RHACS portal +include::modules/generating-sboms-by-using-the-rhacs-portal.adoc[leveloffset=+2] + +//Generating SBOMs by using the roxctl CLI +include::modules/generating-sboms-by-using-the-roxctl-cli.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../../cli/command-reference/roxctl-image.adoc#roxctl-image-sbom_roxctl-image[roxctl image sbom] + +//Generating SBOMs by using the API +include::modules/generating-sboms-by-using-the-api.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../../rest_api/ImageService/ImageService.adoc#GenerateSBOM_ImageService[GenerateSBOM] \ No newline at end of file diff --git a/operating/manage-vulnerabilities/snippets b/operating/manage-vulnerabilities/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/operating/manage-vulnerabilities/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/operating/manage-vulnerabilities/technology-preview.adoc b/operating/manage-vulnerabilities/technology-preview.adoc new file mode 100644 index 000000000000..dcf0471dda81 --- /dev/null +++ b/operating/manage-vulnerabilities/technology-preview.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: SNIPPET + +// When including this file, ensure that {FeatureName} is set immediately before +// the include. Otherwise it will result in an incorrect replacement. + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} is a Technology Preview feature only. Technology Preview features +are not supported with Red{nbsp}Hat production service level agreements (SLAs) and +might not be functionally complete. Red{nbsp}Hat does not recommend using them +in production. These features provide early access to upcoming product +features, enabling customers to test functionality and provide feedback during +the development process. + +For more information about the support scope of Red{nbsp}Hat Technology Preview +features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: \ No newline at end of file diff --git a/operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc b/operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc new file mode 100644 index 000000000000..6b5bf7d944d1 --- /dev/null +++ b/operating/manage-vulnerabilities/vulnerability-management-dashboard.adoc @@ -0,0 +1,37 @@ +:_mod-docs-content-type: ASSEMBLY +[id="vulnerability-management-dashboard"] += Using the vulnerability management dashboard (deprecated) +include::modules/common-attributes.adoc[] +:context: vulnerability-management-dashboard + +toc::[] + +[role="_abstract"] + +Historically, {product-title-short} has provided a view of vulnerabilities discovered in your system in the vulnerability management dashboard. With the dashboard, you can view vulnerabilities by image, node, or platform. You can also view vulnerabilities by clusters, namespaces, deployments, node components, and image components. The dashboard is deprecated in {product-title-short} 4.5 and will be removed in a future release. + +[IMPORTANT] +==== +To perform actions on vulnerabilities, such as view additional information about a vulnerability, defer a vulnerability, or mark a vulnerability as a false positive, go to *Vulnerability Management* -> *Results* and click the *User Workloads* tab. To review requests for deferring and marking CVEs as false positives, click *Vulnerability Management* -> *Exception Management*. +==== + +include::modules/vulnerability-management-view-applications-vulnerability.adoc[leveloffset=+1] +include::modules/vulnerability-management-view-image-vulnerability-dashboard.adoc[leveloffset=+1] +include::modules/vulnerability-management-view-infrastructure-vulnerability.adoc[leveloffset=+1] +include::modules/vulnerability-management-view-node-vulnerability.adoc[leveloffset=+1] +include::modules/find-the-most-vulnerable-image-components.adoc[leveloffset=+1] +include::modules/view-details-only-for-fixable-cves.adoc[leveloffset=+1] +include::modules/identify-operating-system-of-the-base-image.adoc[leveloffset=+1] +include::modules/identify-top-risky-objects.adoc[leveloffset=+1] +include::modules/top-risky-images-components.adoc[leveloffset=+1] +include::modules/view-dockerfile-for-image.adoc[leveloffset=+1] +include::modules/identify-container-image-layer-that-introduces-vulnerabilities.adoc[leveloffset=+1] +include::modules/view-recently-detected-vulnerabilities.adoc[leveloffset=+1] +include::modules/view-most-common-vulnerabilities.adoc[leveloffset=+1] +include::modules/find-clusters-with-most-kubernetes-and-istio-vulnerabilities.adoc[leveloffset=+1] +include::modules/identify-vulnerabilities-in-nodes.adoc[leveloffset=+1] + +.Additional resources +* xref:../../operating/examine-images-for-vulnerabilities.adoc#supported-operating-systems_examine-images-for-vulnerabilities[Supported operating systems] + +include::modules/create-policies-to-block-specific-cves.adoc[leveloffset=+1] \ No newline at end of file diff --git a/operating/manage-vulnerabilities/vulnerability-management.adoc b/operating/manage-vulnerabilities/vulnerability-management.adoc new file mode 100644 index 000000000000..e65203e50aac --- /dev/null +++ b/operating/manage-vulnerabilities/vulnerability-management.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: ASSEMBLY +[id="vulnerability-management"] += Vulnerability management overview +include::modules/common-attributes.adoc[] +:context: acs-operating-manage-vulnerabilities + +toc::[] + +[role="_abstract"] +Security vulnerabilities in your environment might be exploited by an attacker to perform unauthorized actions such as carrying out a denial of service attack, executing remote code, or gaining unauthorized access to sensitive data. Therefore, the management of vulnerabilities is a foundational step towards a successful Kubernetes security program. + +include::modules/vulnerability-management-process.adoc[leveloffset=+1] +include::modules/vulnerability-management-asset-assessment.adoc[leveloffset=+2] +include::modules/vulnerability-management-prioritizing.adoc[leveloffset=+2] +include::modules/vulnerability-management-assess-exposure.adoc[leveloffset=+2] +include::modules/vulnerability-management-take-action.adoc[leveloffset=+2] \ No newline at end of file diff --git a/operating/manage-vulnerabilities/vulnerability-reporting.adoc b/operating/manage-vulnerabilities/vulnerability-reporting.adoc new file mode 100644 index 000000000000..ba2d060e0c83 --- /dev/null +++ b/operating/manage-vulnerabilities/vulnerability-reporting.adoc @@ -0,0 +1,52 @@ +:_mod-docs-content-type: ASSEMBLY +[id="vulnerability-reporting"] += Vulnerability reporting +include::modules/common-attributes.adoc[] +:context: vulnerability-reporting + +toc::[] + +[role="_abstract"] + +You can create and download an on-demand image vulnerability report from the *Vulnerability Management* -> *Vulnerability Reporting* menu in the {product-title-short} web portal. This report contains a comprehensive list of common vulnerabilities and exposures in images and deployments, referred to as workload CVEs or user workloads in {product-title-short}. + +To share this report with auditors or internal stakeholders, you can schedule emails in {product-title-short} or download the report and share it by using other methods. + +include::modules/vulnerability-management-reporting.adoc[leveloffset=+1] + +//creating the report +include::modules/vulnerability-management20-creating-report.adoc[leveloffset=+1] + +//configuring destinations and scheduling +include::modules/vulnerability-management20-configure-report-delivery-destinations-schedule.adoc[leveloffset=+2] + +include::modules/vulnerability-management20-report-review-create.adoc[leveloffset=+2] + +//report permissions +include::modules/vulnerability-management20-permissions.adoc[leveloffset=+1] + +//editing reports +include::modules/vulnerability-management20-edit-reports.adoc[leveloffset=+1] + +//downloading reports +include::modules/vulnerability-management20-download-reports.adoc[leveloffset=+1] + +//sending reports +include::modules/vulnerability-management20-send-reports.adoc[leveloffset=+1] + +//cloning reports +include::modules/vulnerability-management20-clone-reports.adoc[leveloffset=+1] + +//deleting reports +include::modules/vulnerability-management20-delete-reports.adoc[leveloffset=+1] + +//report settings +include::modules/vulnerability-management20-retention-settings.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_vuln-reporting"] +== Additional resources + +* xref:../../operating/create-use-collections.adoc#create-use-collections[Creating and using deployment collections] +* xref:../../operating/create-use-collections.adoc#migrate-scope-collections_create-use-collections[Migration of access scopes to collections] +* xref:../../integration/integrate-with-email.adoc#configure-acs-email_integrate-with-email[Configuring the email plugin] diff --git a/operating/manage_security_policies/about-security-policies.adoc b/operating/manage_security_policies/about-security-policies.adoc new file mode 100644 index 000000000000..0c44de12cd99 --- /dev/null +++ b/operating/manage_security_policies/about-security-policies.adoc @@ -0,0 +1,64 @@ +:_mod-docs-content-type: ASSEMBLY +[id="about-security-policies"] += About policies in {product-title-short} +include::modules/common-attributes.adoc[] +:context: about-security-policies + +toc::[] + +[role="_abstract"] + +{product-title} ({product-title-short}) helps you secure your container infrastructure by using a robust policy engine and an admission controller. With {product-title-short}, you can establish appropriate security guardrails, inform about policy violations, and selectively enforce policies to prevent insecure situations. + +Specifically, {product-title-short} can help you fail the CI pipeline in the build stage, reject deployments from being deployed in the deployment stage, and shut down running deployments that violate runtime policies. {product-title-short} also provides policy management and violation management tools described in the following sections. + +//Want to provide a graphic here but we currently have no graphics support for our doc team to create one. + +include::modules/policy-evaluation-engine.adoc[leveloffset=+1] + +//Policy enforcement + +include::modules/policy-enforcement-about.adoc[leveloffset=+1] + +include::modules/policy-enforcement-build-stage.adoc[leveloffset=+2] + +include::modules/policy-enforcement-deploy.adoc[leveloffset=+2] + +include::modules/policy-enforcement-hard.adoc[leveloffset=+3] + +include::modules/namespace-exclusions.adoc[leveloffset=+3] + +include::modules/enforcement-existing-deployments.adoc[leveloffset=+3] + +include::modules/policy-enforcement-soft.adoc[leveloffset=+3] + +include::modules/policy-enforcement-runtime.adoc[leveloffset=+2] + + +//RHACS Policy Structure + +include::modules/policy-structure.adoc[leveloffset=+1] + +//Policy and violation management + +include::modules/policy-and-violation-management.adoc[leveloffset=+1] + +include::modules/policy-rules-setting.adoc[leveloffset=+2] + +//Boaz to provide info about violation management + +//Violations management +// Different than https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_security_for_kubernetes/4.8/html/operating/respond-to-violations ? + +include::modules/default-security-policies-about.adoc[leveloffset=+1] + +include::modules/viewing-default-security-policies.adoc[leveloffset=+2] + +include::modules/custom-security-policies-about.adoc[leveloffset=+1] + +include::modules/sharing-security-policies.adoc[leveloffset=+1] + +include::modules/export-security-policy.adoc[leveloffset=+2] + +include::modules/import-security-policy.adoc[leveloffset=+2] + diff --git a/operating/manage_security_policies/custom-security-policies.adoc b/operating/manage_security_policies/custom-security-policies.adoc new file mode 100644 index 000000000000..3325e96ed830 --- /dev/null +++ b/operating/manage_security_policies/custom-security-policies.adoc @@ -0,0 +1,25 @@ +:_mod-docs-content-type: ASSEMBLY +[id="custom-security-policies"] += Creating and modifying security policies +include::modules/common-attributes.adoc[] +:context: custom-security-policies + +toc::[] + +[role="_abstract"] +In {product-title} ({product-title-short}), you can use the {product-title-short} portal to create policies, or create and manage policies as code by saving policies as Kubernetes custom resources (CRs) and by applying them to clusters by using a continuous delivery tool such as Argo CD. + +include::modules/create-policy-from-system-policies-view.adoc[leveloffset=+1] +include::modules/enter-policy-details.adoc[leveloffset=+2] +include::modules/select-policy-lifecycle.adoc[leveloffset=+2] +include::modules/configure-policy-rules.adoc[leveloffset=+2] +include::modules/configure-policy-scope.adoc[leveloffset=+2] +include::modules/configure-policy-enforcement-creating-policies.adoc[leveloffset=+2] +include::modules/selecting-policy-notifiers.adoc[leveloffset=+2] +include::modules/preview-policy-violations.adoc[leveloffset=+2] + +include::modules/create-policy-from-risk-view.adoc[leveloffset=+1] + +//Modifying existing security policies +include::modules/modify-existing-security-policies.adoc[leveloffset=+1] + diff --git a/installing/installing_vmc/images b/operating/manage_security_policies/images similarity index 100% rename from installing/installing_vmc/images rename to operating/manage_security_policies/images diff --git a/operating/manage_security_policies/managing-policies-as-code.adoc b/operating/manage_security_policies/managing-policies-as-code.adoc new file mode 100644 index 000000000000..4b12d7e58c8f --- /dev/null +++ b/operating/manage_security_policies/managing-policies-as-code.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: ASSEMBLY +[id="managing-policies-as-code"] += Managing policies as code +include::modules/common-attributes.adoc[] +:context: managing-policies-as-code + +toc::[] + +[role="_abstract"] +You can create and manage policies as code by saving policies as Kubernetes custom resources (CRs) and applying them to clusters by using a Kubernetes-native continuous delivery (CD) tool such as Argo CD. + +include::modules/policy-as-code-about.adoc[leveloffset=+1] +include::modules/policy-as-code-drift.adoc[leveloffset=+2] +include::modules/policy-as-code-create-portal.adoc[leveloffset=+2] +include::modules/policy-as-code-create-cr.adoc[leveloffset=+2] +include::modules/policy-as-code-disable.adoc[leveloffset=+2] + +//in progress: modules/policy-as-code-workflow-example.adoc + diff --git a/installing/installing_ibm_z/modules b/operating/manage_security_policies/modules similarity index 100% rename from installing/installing_ibm_z/modules rename to operating/manage_security_policies/modules diff --git a/operating/manage_security_policies/security-policy-reference.adoc b/operating/manage_security_policies/security-policy-reference.adoc new file mode 100644 index 000000000000..4bafacfc0bf9 --- /dev/null +++ b/operating/manage_security_policies/security-policy-reference.adoc @@ -0,0 +1,30 @@ +:_mod-docs-content-type: ASSEMBLY +[id="security-policy-reference"] += Security policy reference +include::modules/common-attributes.adoc[] +:context: security-policy-reference + +toc::[] + +[role="_abstract"] +You can use policy categories to manage your policies, and security criteria are available to use in building custom policies. Different criteria are available depending on the policy lifecycle stage. + +include::modules/default-security-policies.adoc[leveloffset=+1] + +include::modules/con-policy-categories.adoc[leveloffset=+1] + +include::modules/policy-criteria.adoc[leveloffset=+1] + +[id="default-security-policies-list"] +== Default security policies + +{product-title-short} provides included security policies that you can use to prevent high-risk service deployments in your environment and respond to runtime security incidents. The listed policies are organized by severity level: critical, high, medium, and low. + +include::modules/critical-sev-security-policies.adoc[leveloffset=+1] + +include::modules/high-sev-security-policies.adoc[leveloffset=+1] + +include::modules/medium-sev-security-policies.adoc[leveloffset=+1] + +include::modules/low-sev-security-policies.adoc[leveloffset=+1] + diff --git a/operating/manage_security_policies/snippets b/operating/manage_security_policies/snippets new file mode 120000 index 000000000000..7bf6da9a51d0 --- /dev/null +++ b/operating/manage_security_policies/snippets @@ -0,0 +1 @@ +../../snippets \ No newline at end of file diff --git a/operating/manage_security_policies/use-admission-controller-enforcement.adoc b/operating/manage_security_policies/use-admission-controller-enforcement.adoc new file mode 100644 index 000000000000..0948b04fcb9f --- /dev/null +++ b/operating/manage_security_policies/use-admission-controller-enforcement.adoc @@ -0,0 +1,29 @@ +[id="use-admission-controller-enforcement"] += Using admission controller enforcement +include::modules/common-attributes.adoc[] +:context: use-admission-controller-enforcement + +toc::[] + +[role="_abstract"] +{product-title-short} works with link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/[Kubernetes admission controllers] and link:https://docs.openshift.com/container-platform/4.19/architecture/admission-plug-ins.html[{ocp} admission plugins] to allow you to enforce security policies before Kubernetes or {ocp} creates workloads, for example, deployments, daemon sets or jobs. The {product-title-short} admission controller prevents users from creating or updating workloads that violate policies that you configure in {product-title-short}. + +{product-title-short} uses the `ValidatingAdmissionWebhook` controller to verify that the resource being provisioned complies with the specified security policies. +To handle this, {product-title-short} creates a `ValidatingWebhookConfiguration` which contains multiple webhook rules. + +When the Kubernetes or {ocp} API server receives a request that matches one of the webhook rules, the API server sends an `AdmissionReview` request to {product-title-short}. {product-title-short} then accepts or rejects the request based on the configured security policies. + +//There will be additional changes to these modules as part of 4.9 +include::modules/understand-admission-controller-enforcement.adoc[leveloffset=+1] + +include::modules/enable-admission-controller-enforcement.adoc[leveloffset=+1] + +include::modules/bypass-admission-controller-enforcement.adoc[leveloffset=+1] + +include::modules/disable-admission-controller-enforcement.adoc[leveloffset=+1] + +include::modules/disable-associated-policies.adoc[leveloffset=+2] + +include::modules/disable-the-webhook.adoc[leveloffset=+2] + +include::modules/validatingwebhookconfiguration-yaml-changes.adoc[leveloffset=+1] \ No newline at end of file diff --git a/applications/modules b/operating/modules similarity index 100% rename from applications/modules rename to operating/modules diff --git a/operating/respond-to-violations.adoc b/operating/respond-to-violations.adoc new file mode 100644 index 000000000000..98c459a87095 --- /dev/null +++ b/operating/respond-to-violations.adoc @@ -0,0 +1,41 @@ +:_mod-docs-content-type: ASSEMBLY +[id="respond-to-violations"] += Responding to violations +include::modules/common-attributes.adoc[] +:context: respond-to-violations + +toc::[] + +[role="_abstract"] +Using {rh-rhacs-first} you can view policy violations, navigate to the actual cause of the violation, and take corrective actions. + +{product-title-short}'s built-in policies identify a variety of security findings, including vulnerabilities (CVEs), violations of DevOps best practices, high-risk build and deployment practices, and suspicious runtime behaviors. +Whether you use the default out-of-box security policies or use your own custom policies, {product-title-short} reports a violation when an enabled policy fails. + +include::modules/namespace-conditions-for-platform-components.adoc[leveloffset=+1] + +include::modules/analyzing-all-violations.adoc[leveloffset=+1] + +include::modules/violations-page-overview.adoc[leveloffset=+1] + +[id="view-violation-details"] +== Viewing violation details +When you select a violation in the *Violations* view, a window opens with more information about the violation. It provides detailed information grouped by multiple tabs. + +include::modules/violation-view-violation-tab.adoc[leveloffset=+2] + +//we don't seem to have an enforcement tab any longer? +//include::modules/violation-view-enforcement-tab.adoc[leveloffset=+2] + +include::modules/violations-view-deployment-tab.adoc[leveloffset=+2] + +include::modules/violation-view-policy-tab.adoc[leveloffset=+2] + +include::modules/policy-enforcement-deploy.adoc[leveloffset=+3] + +[role="_additional-resources"] +.Additional resources + +* xref:../operating/manage_security_policies/use-admission-controller-enforcement.adoc#use-admission-controller-enforcement[Using admission controller enforcement] + +include::modules/network-policies-tab.adoc[leveloffset=+2] \ No newline at end of file diff --git a/operating/review-cluster-configuration.adoc b/operating/review-cluster-configuration.adoc new file mode 100644 index 000000000000..7f7816dcf28d --- /dev/null +++ b/operating/review-cluster-configuration.adoc @@ -0,0 +1,33 @@ +[id="review-cluster-configuration"] += Reviewing cluster configuration +include::modules/common-attributes.adoc[] +:context: review-cluster-configuration + +toc::[] + +[role="_abstract"] +Learn how to use the *Configuration Management* view and understand the correlation between various entities in your cluster to manage your cluster configuration efficiently. + +Every {ocp} cluster includes many different entities distributed throughout the cluster, which makes it more challenging to understand and act on the available information. + +{product-title} ({product-title-short}) provides efficient configuration management that combines all these distributed entities on a single page. +It brings together information about all your clusters, namespaces, nodes, deployments, images, secrets, users, groups, service accounts, and roles in a single *Configuration Management* view, helping you visualize different entities and the connections between them. + +include::modules/using-the-configuration-management-view.adoc[leveloffset=+1] + +[id="misconfigurations-kubernetes-rbac"] +== Identifying misconfigurations in Kubernetes roles + +You can use the *Configuration Management* view to identify potential misconfigurations, such as users, groups, or service accounts granted the `cluster-admin` role, or roles that are not granted to anyone. + +include::modules/kubernetes-role-assignment.adoc[leveloffset=+2] + +include::modules/service-accounts-permissions.adoc[leveloffset=+2] + +include::modules/unused-kubernetes-roles.adoc[leveloffset=+2] + +include::modules/view-kubernetes-secrets.adoc[leveloffset=+1] + +include::modules/find-policy-violations.adoc[leveloffset=+1] + +include::modules/find-failing-cis-controls.adoc[leveloffset=+1] diff --git a/operating/search-filter.adoc b/operating/search-filter.adoc new file mode 100644 index 000000000000..50b391cd0c0e --- /dev/null +++ b/operating/search-filter.adoc @@ -0,0 +1,21 @@ +[id="search-filter"] += Searching and filtering +include::modules/common-attributes.adoc[] +:context: search-filter + +toc::[] + +[role="_abstract"] +The ability to instantly find resources is important to safeguard your cluster. Use {product-title} search feature to find relevant resources faster. For example, you can use it to find deployments that are exposed to a newly published CVE or find all deployments that have external network exposure. + +include::modules/search-syntax.adoc[leveloffset=+1] + +include::modules/search-autocomplete.adoc[leveloffset=+1] + +include::modules/use-global-search.adoc[leveloffset=+1] + +include::modules/use-local-page-filtering.adoc[leveloffset=+1] + +include::modules/common-search-queries.adoc[leveloffset=+1] + +include::modules/search-attributes.adoc[leveloffset=+1] diff --git a/operating/snippets b/operating/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/operating/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/operating/use-system-health-dashboard.adoc b/operating/use-system-health-dashboard.adoc new file mode 100644 index 000000000000..b223b7cfee37 --- /dev/null +++ b/operating/use-system-health-dashboard.adoc @@ -0,0 +1,32 @@ +:_mod-docs-content-type: ASSEMBLY +[id="use-system-health-dashboard"] += Using the system health dashboard +include::modules/common-attributes.adoc[] +:context: use-system-health-dashboard + +toc::[] + +[role="_abstract"] +The {rh-rhacs-first} system health dashboard provides a single interface for viewing health-related information about the {product-title-short} components. + +//Analyzing and managing the system health information +include::modules/analyzing-and-managing-the-system-health-information.adoc[leveloffset=+1] + +//System health dashboard page overview +include::modules/system-health-dashboard-page-overview.adoc[leveloffset=+1] + + +//not applicable for 4.7 +//// +//Cluster status section +include::modules/cluster-status-section.adoc[leveloffset=+2] + +//Sensor upgrade section +include::modules/sensor-upgrade-section.adoc[leveloffset=+2] +//// + +//Image Integrations section +include::modules/image-integrations-section.adoc[leveloffset=+2] + +//Administration usage page overview +include::modules/administration-usage-page-overview.adoc[leveloffset=+1] \ No newline at end of file diff --git a/operating/using-collector-runtime-configuration.adoc b/operating/using-collector-runtime-configuration.adoc new file mode 100644 index 000000000000..c254d978c955 --- /dev/null +++ b/operating/using-collector-runtime-configuration.adoc @@ -0,0 +1,40 @@ +:_mod-docs-content-type: ASSEMBLY +[id="using-collector-runtime-configuration"] += Using Collector runtime configuration +include::modules/common-attributes.adoc[] + +:FeatureName: Using Collector runtime configuration +:!FeatureName: + +toc::[] + +[role="_abstract"] +You can use the Collector runtime configuration to modify some collector behaviors without restarting Collector. Set the Collector runtime configuration by using a `ConfigMap` object called `collector-config`. When you create or update the `ConfigMap` object, Collector refreshes the runtime configuration. When you delete the `ConfigMap` object, the settings revert to the default runtime configuration values. + +You can control the following settings using the Collector runtime configuration: + +* `networking.externalIps.enabled` controls if the visualizing external entities feature is enabled or disabled. The default is `DISABLED`. In release 4.6, this setting was `networking.externalIps.enable` and was a boolean. For more information, see xref:../operating/visualizing-external-entities.adoc#visualizing-external-entities[Visualizing external entities]. + +* `networking.externalIps.direction` specifies the direction for collecting external IPs. The values are `INGRESS`, `EGRESS`, or `BOTH` (default). For example, when you select `EGRESS` it provides details for all outgoing connections while aggregating the incoming ones. + +* `networking.maxConnectionsPerMinute` is the maximum number of open networking connections reported by Collector per container per minute. The default value is 2048. + +The following example enables the visualizing external entities for outgoing connections only and sets `maxConnectionsPerMinute` to 2048. + +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: collector-config + namespace: stackrox +data: + runtime_config.yaml: | <1> + networking: + externalIps: + enabled: ENABLED + direction: EGRESS <2> + maxConnectionsPerMinute: 2048 +---- +<1> {product-title-short} mounts this file at `/etc/stackrox/runtime_config.yaml`. +<2> The `direction` setting is optional. If you do not specify it, the default value is `BOTH`, which collects both ingress and egress connections. diff --git a/operating/using-the-administration-events-page.adoc b/operating/using-the-administration-events-page.adoc new file mode 100644 index 000000000000..a5df2bae1723 --- /dev/null +++ b/operating/using-the-administration-events-page.adoc @@ -0,0 +1,25 @@ +:_mod-docs-content-type: ASSEMBLY +[id="using-the-administration-events-page"] += Using the administration events page +include::modules/common-attributes.adoc[] +:context: using-the-administration-events-page + +toc::[] + +[role="_abstract"] +You can view administration event information in a single interface with {rh-rhacs-first}. You can use this interface to help you understand and interpret important event details. + +//Accessing the event logs in different domains +include::modules/accessing-the-event-logs-in-different-domains.adoc[leveloffset=+1] + +//Administration events page overview +include::modules/administration-events-page-overview.adoc[leveloffset=+1] + +//Getting information about the events in a particular domain +include::modules/getting-information-about-the-events-in-a-particular-domain.adoc[leveloffset=+1] + +//Administration event details overview +include::modules/administration-event-details-overview.adoc[leveloffset=+1] + +//Setting the expiration of the administration events +include::modules/setting-the-expiration-of-the-administration-events.adoc[leveloffset=+1] \ No newline at end of file diff --git a/operating/verify-image-signatures.adoc b/operating/verify-image-signatures.adoc new file mode 100644 index 000000000000..f15fc5e1eb31 --- /dev/null +++ b/operating/verify-image-signatures.adoc @@ -0,0 +1,57 @@ +[id="verify-image-signatures"] += Verifying image signatures +include::modules/common-attributes.adoc[] +:context: verify-image-signatures + +toc::[] + +[role="_abstract"] +You can use {product-title} ({product-title-short}) to ensure the integrity of the container images in your clusters by verifying image signatures against pre-configured keys. + +You can create policies to block unsigned images and images that do not have a verified signature. +You can also enforce the policy by using the {product-title-short} admission controller to stop unauthorized deployment creation. + +[NOTE] +==== +* {product-title-short} supports Cosign signature verification by using Cosign public keys, Cosign certificates, or both. ++ +For more information about Cosign, see link:https://docs.sigstore.dev/cosign/signing/overview/[Overview] (Sigstore documentation). +* For Cosign signature verification, {product-title-short} supports communication with the transparency log. ++ +For more information, see link:https://docs.sigstore.dev/logging/overview/[Rekor] (Sigstore documentation). +* For Cosign signature verification, you can use keyless verification with {product-title-short}. If you want to host the key infrastructure yourself, you can do this by using {rh-rhtas-first}. +* You must configure signature integration with at least 1 Cosign verification method for signature verification. +* For all deployed and watched images: +** {product-title-short} fetches and verifies the signatures every 4 hours. +** {product-title-short} verifies the signatures whenever you change or update your signature integration verification data. +==== + +//Securing container images by using signature integration +include::modules/securing-container-images-by-using-signature-integration.adoc[leveloffset=+1] + +//Verifying image signatures to ensure image integrity +include::modules/verifying-image-signatures-to-ensure-image-integrity.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../operating/verify-image-signatures.adoc#securing-container-images-by-using-signature-integration_verify-image-signatures[Securing container images by using signature integration] + +//Using signature verification in a policy +include::modules/use-signature-verification.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage_security_policies/custom-security-policies.adoc#create-policy-from-system-policies-view_custom-security-policies[Creating a security policy from the system policies view] + +* xref:../operating/manage_security_policies/security-policy-reference.adoc#policy-criteria_security-policy-reference[Understanding rules and policy criteria] + +== Enforcing signature verification +To prevent the users from using unsigned images, you can enforce signature verification by using the {product-title-short} admission controller. +You must first enable the *Contact Image Scanners* feature in your cluster configuration settings. +Then, while creating a security policy to enforce signature verification, you can use the *Inform and enforce* option. + +For more information, see xref:../operating/manage_security_policies/use-admission-controller-enforcement.adoc#enable-admission-controller-enforcement_use-admission-controller-enforcement[Enabling admission controller enforcement]. + +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage_security_policies/custom-security-policies.adoc#create-policy-from-system-policies-view_custom-security-policies[Creating a security policy from the system policies view] diff --git a/operating/view-dashboard.adoc b/operating/view-dashboard.adoc new file mode 100644 index 000000000000..b2531b8f5b1c --- /dev/null +++ b/operating/view-dashboard.adoc @@ -0,0 +1,117 @@ +:_mod-docs-content-type: ASSEMBLY +[id="view-dashboard"] += Viewing the dashboard +include::modules/common-attributes.adoc[] +:context: view-dashboard + +toc::[] + +[role="_abstract"] +The {product-title} ({product-title-short}) Dashboard provides quick access to the data you need. It contains additional navigation shortcuts and actionable widgets that are easy to filter and customize so that you can focus on the data that matters most to you. You can view information about levels of risk in your environment, compliance status, policy violations, and common vulnerabilities and exposures (CVEs) in images. + +[NOTE] +==== +When you open the {product-title-short} portal for the first time, the Dashboard might be empty. After you deploy Sensor in at least one cluster, the Dashboard reflects the status of your environment. +==== + +The following sections describe the Dashboard components. + +[id="status-bar-links"] +== Status bar + +The *Status Bar* provides at-a-glance numerical counters for key resources. The counters reflect what is visible with your current access scope that is defined by the roles associated with your user profile. These counters are clickable, providing fast access to desired list view pages as follows: + +[cols="1,1"] +|=== +| Counter | Destination + +| Clusters +| Platform Configuration -> Clusters + +| Nodes +| Configuration Management -> Application & Infrastructure → Nodes + +| Violations +| Violations main menu + +| Deployments +| Configuration Management -> Application & Infrastructure → Deployments + +| Images +| Vulnerability Management -> Dashboard -> Images + +| Secrets +| Configuration Management -> Application & Infrastructure -> Secrets +|=== + +[id="dashboard-filter"] +== Dashboard filter + +The Dashboard includes a top-level filter that applies simultaneously to all widgets. You can select one or more clusters, and one or more namespaces within selected clusters. When no clusters or namespaces are selected, the view automatically switches to *All*. Any change to the filter is immediately reflected by all widgets, limiting the data they present to the selected scope. The Dashboard filter does not affect the *Status Bar*. + +[id="widget-options"] +== Widget options + +Some widgets are customizable to help you focus on specific data. Widgets offer different controls that you can use to change how the data is sorted, filter the data, and customize the output of the widget. + +Widgets offer two ways to customize different aspects: + +* An *Options* menu, when present, provides specific options applicable to that widget. +* A *dynamic axis legend*, when present, provides a method to filter data by hiding one or more of the axis categories. For example, in the *Policy violations by category* widget, you can click on a severity to include or exclude violations of a selected severity from the data. + +[NOTE] +==== +Individual widget customization settings are short-lived and are reset to the system default upon leaving the Dashboard. +==== + +[id="new-widgets"] +== Actionable widgets + +The following sections describe the actionable widgets available in the Dashboard. + +[id="policy-violations-severity"] +=== Policy violations by severity + +This widget shows the distribution of violations across severity levels for the Dashboard-filtered scope. Clicking a *severity level* in the chart takes you to the *Violations* page, filtered for that severity and scope. It also lists the three most recent violations of a *Critical* level policy within the scope you defined in the Dashboard filter. Clicking a specific violation takes you directly to the *Violations* detail page for that violation. + +[id="images-most-risk"] +=== Images at most risk + +This widget lists the top six vulnerable images within the Dashboard-filtered scope, sorted by their computed risk priority, along with the number of critical and important CVEs they contain. Click on an image name to go directly to the *Image Findings* page under *Vulnerability Management*. Use the *Options* menu to focus on fixable CVEs, or further focus on active images. + +[NOTE] +==== +When clusters or namespaces have been selected in the Dashboard filter, the data displayed is already filtered to active images, or images that are used by deployments within the filtered scope. +==== + +[id="deployments-most-risk"] +=== Deployments at most risk + +This widget provides information about the top deployments at risk in your environment. It displays additional information such as the resource location (cluster and namespace) and the risk priority score. Additionally, you can click on a deployment to view risk information about the deployment; for example, its policy violations and vulnerabilities. + +[id="aging-images"] +=== Aging images + +Older images present a higher security risk because they can contain vulnerabilities that have already been addressed. If older images are active, they can expose deployments to exploits. You can use this widget to quickly assess your security posture and identify offending images. You can use the default ranges or customize the age intervals with your own values. You can view both inactive and active images or use the Dashboard filter to focus on a particular area for active images. You can then click on an age group in this widget to view only those images in the *Vulnerability Management* -> *Images* page. + +[id="policy-violations-category"] +=== Policy violations by category + +This widget can help you gain insights about the challenges your organization is facing in complying with security policies, by analyzing which types of policies are violated more than others. The widget shows the five policy categories of highest interest. Explore the *Options* menu for different ways to slice the data. You can filter the data to focus exclusively on deploy or runtime violations. + +You can also change the sorting mode. By default, the data is sorted by the number of violations within the highest severity first. Therefore, all categories with critical policies will appear before categories without critical policies. The other sorting mode considers the total number of violations regardless of severity. Because some categories contain no critical policies (for example, “Docker CIS”), the two sorting modes can provide significantly different views, offering additional insight. + +Click on a severity level at the bottom of the graph to include or exclude that level from the data. Selecting different severity levels can result in a different top five selection or ranking order. Data is filtered to the scope selected by the Dashboard filter. + +[id="compliance-standard"] +=== Compliance by standard + +You can use the *Compliance by standard* widget with the Dashboard filter to focus on areas that matter to you the most. The widget lists the top or bottom six compliance benchmarks, depending on sort order. Select *Options* to sort by the coverage percentage. Click on one of the benchmark labels or graphs to go directly to the *Compliance Controls* page, filtered by the Dashboard scope and the selected benchmark. + +[NOTE] +==== +The *Compliance* widget shows details only after you run a compliance scan. + +For more information, see xref:../operating/manage-compliance/using-the-compliance-dashboard.adoc#checking-the-compliance-status-of-your-infrastructure_using-the-compliance-dashboard[Checking the compliance status of your infrastructure]. +==== +//TODO: Add link to compliance scan \ No newline at end of file diff --git a/operating/visualizing-external-entities.adoc b/operating/visualizing-external-entities.adoc new file mode 100644 index 000000000000..3f0ee42fa087 --- /dev/null +++ b/operating/visualizing-external-entities.adoc @@ -0,0 +1,35 @@ +:_mod-docs-content-type: ASSEMBLY +[id="visualizing-external-entities"] += Visualizing external entities +include::modules/common-attributes.adoc[] +:context: visualizing-external-entities + +toc::[] + +:FeatureName: Visualizing external entities +:!FeatureName: + +[role="_abstract"] + +Understanding the interactions between your cluster and external entities is essential for incident response and network policy management. With the Visualizing external entities feature, you can view the external IP addresses that interact with your cluster. + +You can view external entities in the Network Graph by selecting the External Entities graph node or by checking the deployment flows tab. + +You can also query external entities using the API. + +[NOTE] +==== +Visualizing external entities is an opt-in feature that is disabled by default. To enable this feature, you must enable external IP collection in secured clusters, as described in the following section. +==== + +include::modules/enabling-external-ip-collection-secured-clusters.adoc[leveloffset=+1] + +include::modules/querying-external-entities-using-api.adoc[leveloffset=+1] + +include::modules/visualizing-external-entities-known-limitations.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources + +* xref:../operating/using-collector-runtime-configuration.adoc#using-collector-runtime-configuration[Using collector runtime configuration] diff --git a/operators/admin/images b/operators/admin/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/operators/admin/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/operators/admin/modules b/operators/admin/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/operators/admin/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/operators/admin/olm-adding-operators-to-cluster.adoc b/operators/admin/olm-adding-operators-to-cluster.adoc deleted file mode 100644 index c8fbeaebdad3..000000000000 --- a/operators/admin/olm-adding-operators-to-cluster.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="olm-adding-operators-to-a-cluster"] -= Adding Operators to a cluster -include::modules/common-attributes.adoc[] -:context: olm-adding-operators-to-a-cluster - -// Assembly and included modules watched for changes by Ecosystem Catalog team: -// https://projects.engineering.redhat.com/projects/RHEC/summary - -toc::[] - -Cluster administrators can install Operators to an {product-title} cluster by subscribing Operators to namespaces with OperatorHub. - -ifdef::openshift-origin[] -[id="olm-adding-operators-to-a-cluster-prereqs"] -== Prerequisites - -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in _Obtaining the installation program_ in the installation documentation for your platform. -+ -If you have the pull secret, add the `redhat-operators` catalog to the `OperatorHub` custom resource (CR) as shown in _Configuring {product-title} to use Red Hat Operators_. -endif::[] - -include::modules/olm-installing-operators-from-operatorhub.adoc[leveloffset=+1] -* xref:../../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub] - -include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+1] -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/olm-installing-from-operatorhub-using-cli.adoc[leveloffset=+1] -.Additional resources - -* xref:../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-operatorgroups-about_olm-understanding-operatorgroups[About Operator groups] - -include::modules/olm-installing-specific-version-cli.adoc[leveloffset=+1] -.Additional resources - -* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator upgrade] -endif::[] diff --git a/operators/admin/olm-configuring-proxy-support.adoc b/operators/admin/olm-configuring-proxy-support.adoc deleted file mode 100644 index 8b78481b151b..000000000000 --- a/operators/admin/olm-configuring-proxy-support.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="olm-configuring-proxy-support"] -= Configuring proxy support in Operator Lifecycle Manager -include::modules/common-attributes.adoc[] -:context: olm-configuring-proxy-support - -toc::[] - -If a global proxy is configured on the {product-title} cluster, Operator Lifecycle Manager (OLM) automatically configures Operators that it manages with the cluster-wide proxy. However, you can also configure installed Operators to override the global proxy or inject a custom CA certificate. - -.Additional resources - -* xref:../../networking/enable-cluster-wide-proxy.adoc#enable-cluster-wide-proxy[Configuring the cluster-wide proxy] -* xref:../../networking/configuring-a-custom-pki.adoc#configuring-a-custom-pki[Configuring a custom PKI] (custom CA certificate) - -include::modules/olm-overriding-proxy-settings.adoc[leveloffset=+1] -include::modules/olm-injecting-custom-ca.adoc[leveloffset=+1] diff --git a/operators/admin/olm-creating-policy.adoc b/operators/admin/olm-creating-policy.adoc deleted file mode 100644 index 6997e3b23361..000000000000 --- a/operators/admin/olm-creating-policy.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="olm-creating-policy"] -= Allowing non-cluster administrators to install Operators -include::modules/common-attributes.adoc[] -:context: olm-creating-policy - -toc::[] - -Operators can require wide privileges to run, and the required privileges can change between versions. Operator Lifecycle Manager (OLM) runs with `cluster-admin` privileges. By default, Operator authors can specify any set of permissions in the cluster service version (CSV) and OLM will consequently grant it to the Operator. - -Cluster administrators should take measures to ensure that an Operator cannot achieve cluster-scoped privileges and that users cannot escalate privileges using OLM. One method for locking this down requires cluster administrators auditing Operators before they are added to the cluster. Cluster administrators are also provided tools for determining and constraining which actions are allowed during an Operator installation or upgrade using service accounts. - -By associating an _Operator group_ with a service account that has a set of privileges granted to it, cluster administrators can set policy on Operators to ensure they operate only within predetermined boundaries using RBAC rules. The Operator is unable to do anything that is not explicitly permitted by those rules. - -This self-sufficient, limited scope installation of Operators by non-cluster administrators means that more of the Operator Framework tools can safely be made available to more users, providing a richer experience for building applications with Operators. - -include::modules/olm-policy-understanding.adoc[leveloffset=+1] -include::modules/olm-policy-scenarios.adoc[leveloffset=+2] -include::modules/olm-policy-workflow.adoc[leveloffset=+2] - -include::modules/olm-policy-scoping-operator-install.adoc[leveloffset=+1] -include::modules/olm-policy-fine-grained-permissions.adoc[leveloffset=+2] - -include::modules/olm-policy-troubleshooting.adoc[leveloffset=+1] diff --git a/operators/admin/olm-deleting-operators-from-cluster.adoc b/operators/admin/olm-deleting-operators-from-cluster.adoc deleted file mode 100644 index a43d2a15bf5f..000000000000 --- a/operators/admin/olm-deleting-operators-from-cluster.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id='olm-deleting-operators-from-a-cluster'] -= Deleting Operators from a cluster -include::modules/common-attributes.adoc[] -:context: olm-deleting-operators-from-a-cluster - -toc::[] - -The following describes how to delete Operators that were previously installed using Operator Lifecycle Manager (OLM) on your {product-title} cluster. - -include::modules/olm-deleting-operators-from-a-cluster-using-web-console.adoc[leveloffset=+1] -include::modules/olm-deleting-operators-from-a-cluster-using-cli.adoc[leveloffset=+1] -include::modules/olm-refresh-subs.adoc[leveloffset=+1] diff --git a/operators/admin/olm-managing-custom-catalogs.adoc b/operators/admin/olm-managing-custom-catalogs.adoc deleted file mode 100644 index 690da16e5627..000000000000 --- a/operators/admin/olm-managing-custom-catalogs.adoc +++ /dev/null @@ -1,58 +0,0 @@ -[id="olm-managing-custom-catalogs"] -= Managing custom catalogs -include::modules/common-attributes.adoc[] -:context: olm-managing-custom-catalogs - -toc::[] - -This guide describes how to work with custom catalogs for Operators packaged using either the xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Bundle Format] or the legacy xref:../../operators/understanding/olm-packaging-format.adoc#olm-package-manifest-format_olm-packaging-format[Package Manifest Format] on Operator Lifecycle Manager (OLM) in {product-title}. - -include::modules/olm-understanding-operator-catalog-images.adoc[leveloffset=+1] - -[id="olm-managing-custom-catalogs-bundle-format"] -== Custom catalogs using the Bundle Format - -[id="olm-managing-custom-catalogs-bundle-format-prereqs"] -=== Prerequisites - -* Install the xref:../../cli_reference/opm-cli.adoc#opm-cli[`opm` CLI]. - -include::modules/olm-creating-index-image.adoc[leveloffset=+2] -include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+2] -.Additional resources - -* If your index image is hosted on a private registry and requires authentication, see xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries]. - -include::modules/olm-updating-index-image.adoc[leveloffset=+2] -include::modules/olm-pruning-index-image.adoc[leveloffset=+2] - -[id="olm-managing-custom-catalogs-package-manifest-format"] -== Custom catalogs using the Package Manifest Format - -include::modules/olm-building-operator-catalog-image.adoc[leveloffset=+2] -.Additional resources - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Creating a mirror registry for installation in a restricted network] - -include::modules/olm-mirroring-package-manifest-catalog.adoc[leveloffset=+2] -.Additional resources - -* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-arch-os-support_osdk-generating-csvs[Architecture and operating system support for Operators] -* If your catalog image is hosted on a private registry and requires authentication, see xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries]. - -include::modules/olm-updating-operator-catalog-image.adoc[leveloffset=+2] -.Additional resources - -* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-arch-os-support_osdk-generating-csvs[Architecture and operating system support for Operators] - -include::modules/olm-testing-operator-catalog-image.adoc[leveloffset=+2] - -include::modules/olm-accessing-images-private-registries.adoc[leveloffset=+1] -.Additional resources - -* See xref:../../cicd/builds/creating-build-inputs.adoc#builds-secrets-overview_creating-build-inputs[What is a secret?] for more information on the types of secrets, including those used for registry credentials. -* See xref:../../openshift_images/managing_images/using-image-pull-secrets.adoc#images-update-global-pull-secret_using-image-pull-secrets[Updating the global cluster pull secret] for more details on the impact of changing this secret. -* See xref:../../openshift_images/managing_images/using-image-pull-secrets.adoc#images-allow-pods-to-reference-images-from-secure-registries_using-image-pull-secrets[Allowing pods to reference images from other secured registries] for more details on linking pull secrets to service accounts per namespace. - -include::modules/olm-restricted-networks-configuring-operatorhub.adoc[leveloffset=+1] -include::modules/olm-removing-catalogs.adoc[leveloffset=+1] diff --git a/operators/admin/olm-managing-operatorconditions.adoc b/operators/admin/olm-managing-operatorconditions.adoc deleted file mode 100644 index 0f86952f6f7c..000000000000 --- a/operators/admin/olm-managing-operatorconditions.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="olm-managing-operatorconditions"] -= Managing Operator conditions -include::modules/common-attributes.adoc[] -:context: olm-managing-operatorconditions - -toc::[] - -As a cluster administrator, you can manage Operator conditions by using Operator Lifecycle Manager (OLM). - -include::modules/olm-overriding-operatorconditions.adoc[leveloffset=+1] -include::modules/olm-updating-use-operatorconditions.adoc[leveloffset=+1] - -[id="olm-managing-operatorconditions-addtl-resources"] -== Additional resources - -* xref:../../operators/understanding/olm/olm-operatorconditions.adoc#olm-operatorconditions[Operator conditions] diff --git a/operators/admin/olm-restricted-networks.adoc b/operators/admin/olm-restricted-networks.adoc deleted file mode 100644 index 3fe1676c2708..000000000000 --- a/operators/admin/olm-restricted-networks.adoc +++ /dev/null @@ -1,66 +0,0 @@ -[id="olm-restricted-networks"] -= Using Operator Lifecycle Manager on restricted networks -include::modules/common-attributes.adoc[] -:context: olm-restricted-networks - -toc::[] - -For {product-title} clusters that are installed on restricted networks, also known as _disconnected clusters_, Operator Lifecycle Manager (OLM) by default cannot access the Red Hat-provided OperatorHub sources hosted on remote registries because those remote sources require full Internet connectivity. - -However, as a cluster administrator you can still enable your cluster to use OLM in a restricted network if you have a workstation that has full Internet access. The workstation, which requires full Internet access to pull the remote OperatorHub content, is used to prepare local mirrors of the remote sources, and push the content to a mirror registry. - -The mirror registry can be located on a bastion host, which requires connectivity to both your workstation and the disconnected cluster, or a completely disconnected, or _airgapped_, host, which requires removable media to physically move the mirrored content to the disconnected environment. - -This guide describes the following process that is required to enable OLM in restricted networks: - -* Disable the default remote OperatorHub sources for OLM. -* Use a workstation with full Internet access to create and push local mirrors of the OperatorHub content to a mirror registry. -* Configure OLM to install and manage Operators from local sources on the mirror registry instead of the default remote sources. - -After enabling OLM in a restricted network, you can continue to use your unrestricted workstation to keep your local OperatorHub sources updated as newer versions of Operators are released. - -[IMPORTANT] -==== -While OLM can manage Operators from local sources, the ability for a given Operator to run successfully in a restricted network still depends on the Operator itself. The Operator must: - -* List any related images, or other container images that the Operator might require to perform their functions, in the `relatedImages` parameter of its `ClusterServiceVersion` (CSV) object. -* Reference all specified images by a digest (SHA) and not by a tag. - -See the following Red Hat Knowledgebase Article for a list of Red Hat Operators that support running in disconnected mode: - -link:https://access.redhat.com/articles/4740011[] -==== - -.Additional resources - -* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-enabling-operator-for-restricted-network_osdk-generating-csvs[Enabling your Operator for restricted network environments] - -include::modules/olm-understanding-operator-catalog-images.adoc[leveloffset=+1] - -[id="olm-restricted-network-prereqs"] -== Prerequisites - -* Log in to your {product-title} cluster as a user with `cluster-admin` privileges. -* If you want to prune the default catalog and selectively mirror only a subset of Operators, install the xref:../../cli_reference/opm-cli.adoc#opm-cli[`opm` CLI]. - -[NOTE] -==== -If you are using OLM in a restricted network on IBM Z, you must have at least 12 GB allocated to the directory where you place your registry. -==== - -include::modules/olm-restricted-networks-configuring-operatorhub.adoc[leveloffset=+1] -include::modules/olm-pruning-index-image.adoc[leveloffset=+1] -include::modules/olm-mirroring-catalog.adoc[leveloffset=+1] -.Additional resources - -* xref:../../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[Creating a mirror registry for installation in a restricted network] -* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-arch-os-support_osdk-generating-csvs[Architecture and operating system support for Operators] -* xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-mirroring-package-manifest-catalog_olm-managing-custom-catalogs[Mirroring a Package Manifest Format catalog image] - -include::modules/olm-creating-catalog-from-index.adoc[leveloffset=+1] -* If your index image is hosted on a private registry and requires authentication, see xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-accessing-images-private-registries_olm-managing-custom-catalogs[Accessing images for Operators from private registries]. - -include::modules/olm-updating-index-image.adoc[leveloffset=+1] -.Additional resources - -* xref:../../operators/admin/olm-restricted-networks.adoc#olm-mirror-catalog_olm-restricted-networks[Mirroring an Operator catalog] diff --git a/operators/admin/olm-status.adoc b/operators/admin/olm-status.adoc deleted file mode 100644 index a1fcbb331b9a..000000000000 --- a/operators/admin/olm-status.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="olm-status"] -= Viewing Operator status -include::modules/common-attributes.adoc[] -:context: olm-status - -toc::[] - -Understanding the state of the system in Operator Lifecycle Manager (OLM) is important for making decisions about and debugging problems with installed Operators. OLM provides insight into subscriptions and related catalog sources regarding their state and actions performed. This helps users better understand the healthiness of their Operators. - -include::modules/olm-status-conditions.adoc[leveloffset=+1] -include::modules/olm-status-viewing-cli.adoc[leveloffset=+1] diff --git a/operators/admin/olm-upgrading-operators.adoc b/operators/admin/olm-upgrading-operators.adoc deleted file mode 100644 index 30e8c2fc11d9..000000000000 --- a/operators/admin/olm-upgrading-operators.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="olm-upgrading-operators"] -= Upgrading installed Operators -include::modules/common-attributes.adoc[] -:context: olm-upgrading-operators - -toc::[] - -As a cluster administrator, you can upgrade Operators that have been previously installed using Operator Lifecycle Manager (OLM) on your {product-title} cluster. - -include::modules/olm-changing-update-channel.adoc[leveloffset=+1] -include::modules/olm-approving-pending-upgrade.adoc[leveloffset=+1] diff --git a/operators/images b/operators/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/operators/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/operators/modules b/operators/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/operators/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/operators/operator-reference.adoc b/operators/operator-reference.adoc deleted file mode 100644 index 40c2ad123ac5..000000000000 --- a/operators/operator-reference.adoc +++ /dev/null @@ -1,58 +0,0 @@ -[id="red-hat-operators"] -= Red Hat Operators -include::modules/common-attributes.adoc[] -:context: red-hat-operators - -toc::[] - -include::modules/cloud-credential-operator.adoc[leveloffset=+1] -[discrete] -[id="red-hat-operators-cco-addtl-resources"] -=== Additional resources - -* xref:../rest_api/security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[CredentialsRequest custom resource] -* xref:../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc[About the Cloud Credential Operator] - -include::modules/cluster-authentication-operator.adoc[leveloffset=+1] -include::modules/cluster-autoscaler-operator.adoc[leveloffset=+1] -include::modules/cluster-image-registry-operator.adoc[leveloffset=+1] -include::modules/cluster-monitoring-operator.adoc[leveloffset=+1] -include::modules/cluster-network-operator.adoc[leveloffset=+1] -include::modules/cluster-openshift-controller-manager-operators.adoc[leveloffset=+1] -include::modules/cluster-samples-operator.adoc[leveloffset=+1] -include::modules/cluster-storage-operator.adoc[leveloffset=+1] -include::modules/cluster-version-operator.adoc[leveloffset=+1] -include::modules/console-operator.adoc[leveloffset=+1] -include::modules/cluster-dns-operator.adoc[leveloffset=+1] -include::modules/etcd-operator.adoc[leveloffset=+1] -include::modules/ingress-operator.adoc[leveloffset=+1] -include::modules/kube-apiserver-operator.adoc[leveloffset=+1] -include::modules/kube-controller-manager-operator.adoc[leveloffset=+1] -include::modules/cluster-kube-scheduler-operator.adoc[leveloffset=+1] -include::modules/machine-api-operator.adoc[leveloffset=+1] -include::modules/machine-config-operator.adoc[leveloffset=+1] -include::modules/operator-marketplace.adoc[leveloffset=+1] -include::modules/node-tuning-operator.adoc[leveloffset=+1] - -[id="red-hat-operators-olm"] -== Operator Lifecycle Manager Operators -[discrete] -include::modules/olm-overview.adoc[leveloffset=+2] -[discrete] -include::modules/olm-architecture.adoc[leveloffset=+2] -[discrete] -include::modules/olm-arch-olm-operator.adoc[leveloffset=+2] -[discrete] -include::modules/olm-arch-catalog-operator.adoc[leveloffset=+2] -[discrete] -include::modules/olm-arch-catalog-registry.adoc[leveloffset=+2] -[discrete] -[id="red-hat-operators-olm-addtl-resources"] -=== Additional resources - -For more information, see the sections on xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[understanding Operator Lifecycle Manager (OLM)]. - -include::modules/openshift-apiserver-operator.adoc[leveloffset=+1] -include::modules/prometheus-operator.adoc[leveloffset=+1] -include::modules/vsphere-problem-detector-operator.adoc[leveloffset=+1] -include::modules/windows-machine-config-operator.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/ansible/images b/operators/operator_sdk/ansible/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/operators/operator_sdk/ansible/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/operators/operator_sdk/ansible/modules b/operators/operator_sdk/ansible/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/operators/operator_sdk/ansible/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc b/operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc deleted file mode 100644 index d99175f64697..000000000000 --- a/operators/operator_sdk/ansible/osdk-ansible-cr-status.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="osdk-ansible-cr-status"] -= Custom resource status management -include::modules/common-attributes.adoc[] -:context: osdk-ansible-cr-mgmt - -toc::[] - -include::modules/osdk-ansible-cr-status-about.adoc[leveloffset=+1] -include::modules/osdk-ansible-cr-status-manual.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc b/operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc deleted file mode 100644 index 2d978f6f0fcb..000000000000 --- a/operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="osdk-ansible-inside-operator"] -= Using Ansible inside an Operator -include::modules/common-attributes.adoc[] -:context: osdk-ansible-inside-operator - -toc::[] - -After you are familiar with xref:../../../operators/operator_sdk/ansible/osdk-ansible-k8s-collection.adoc#osdk-ansible-k8s-collection[using the Kubernetes Collection for Ansible locally], you can trigger the same Ansible logic inside of an Operator when a custom resource (CR) changes. This example maps an Ansible role to a specific Kubernetes resource that the Operator watches. This mapping is done in the `watches.yaml` file. - -include::modules/osdk-ansible-custom-resource-files.adoc[leveloffset=+1] -include::modules/osdk-ansible-inside-operator-local.adoc[leveloffset=+1] -include::modules/osdk-run-deployment.adoc[leveloffset=+1] -include::modules/osdk-ansible-inside-operator-logs.adoc[leveloffset=+1] -include::modules/osdk-ansible-inside-operator-logs-view.adoc[leveloffset=+2] -include::modules/osdk-ansible-inside-operator-logs-full-result.adoc[leveloffset=+2] -include::modules/osdk-ansible-inside-operator-logs-verbose.adoc[leveloffset=+2] diff --git a/operators/operator_sdk/ansible/osdk-ansible-k8s-collection.adoc b/operators/operator_sdk/ansible/osdk-ansible-k8s-collection.adoc deleted file mode 100644 index 8f14b8ffdc94..000000000000 --- a/operators/operator_sdk/ansible/osdk-ansible-k8s-collection.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="osdk-ansible-k8s-collection"] -= Kubernetes Collection for Ansible -include::modules/common-attributes.adoc[] -:context: osdk-ansible-k8s-collection - -toc::[] - -To manage the lifecycle of your application on Kubernetes using Ansible, you can use the link:https://galaxy.ansible.com/community/kubernetes[Kubernetes Collection for Ansible]. This collection of Ansible modules allows a developer to either leverage their existing Kubernetes resource files written in YAML or express the lifecycle management in native Ansible. - -One of the biggest benefits of using Ansible in conjunction with existing Kubernetes resource files is the ability to use Jinja templating so that you can customize resources with the simplicity of a few variables in Ansible. - -This section goes into detail on usage of the Kubernetes Collection. To get started, install the collection on your local workstation and test it using a playbook before moving on to using it within an Operator. - -include::modules/osdk-ansible-k8s-install.adoc[leveloffset=+1] -include::modules/osdk-ansible-k8s-local.adoc[leveloffset=+1] - -[id="osdk-ansible-k8s-collection-next-steps"] -== Next steps - -* See xref:../../../operators/operator_sdk/ansible/osdk-ansible-inside-operator.adoc#osdk-ansible-inside-operator[Using Ansible inside an Operator] for details on triggering your custom Ansible logic inside of an Operator when a custom resource (CR) changes. diff --git a/operators/operator_sdk/ansible/osdk-ansible-project-layout.adoc b/operators/operator_sdk/ansible/osdk-ansible-project-layout.adoc deleted file mode 100644 index b78db0dd7c2d..000000000000 --- a/operators/operator_sdk/ansible/osdk-ansible-project-layout.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="osdk-ansible-project-layout"] -= Project layout for Ansible-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-ansible-project-layout - -toc::[] - -The `operator-sdk` CLI can generate, or _scaffold_, a number of packages and files for each Operator project. - -include::modules/osdk-ansible-project-layout.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc b/operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc deleted file mode 100644 index 0d47687de777..000000000000 --- a/operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="osdk-ansible-quickstart"] -= Getting started with Operator SDK for Ansible-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-ansible-quickstart - -toc::[] - -The Operator SDK includes options for generating an Operator project that leverages existing Ansible playbooks and modules to deploy Kubernetes resources as a unified application, without having to write any Go code. - -To demonstrate the basics of setting up and running an link:https://docs.ansible.com/ansible/latest/index.html[Ansible]-based Operator using tools and libraries provided by the Operator SDK, Operator developers can build an example Ansible-based Operator for Memcached, a distributed key-value store, and deploy it to a cluster. - -include::modules/osdk-common-prereqs.adoc[leveloffset=+1] -include::modules/osdk-quickstart.adoc[leveloffset=+1] - -[id="osdk-ansible-quickstart-next-steps"] -== Next steps - -* See xref:../../../operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc#osdk-ansible-tutorial[Operator SDK tutorial for Ansible-based Operators] for a more in-depth walkthrough on building an Ansible-based Operator. diff --git a/operators/operator_sdk/ansible/osdk-ansible-support.adoc b/operators/operator_sdk/ansible/osdk-ansible-support.adoc deleted file mode 100644 index 67304f29d946..000000000000 --- a/operators/operator_sdk/ansible/osdk-ansible-support.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="osdk-ansible-support"] -= Ansible support in Operator SDK -include::modules/common-attributes.adoc[] -:context: osdk-ansible-support - -toc::[] - -include::modules/osdk-ansible-custom-resource-files.adoc[leveloffset=+1] -include::modules/osdk-ansible-watches-file.adoc[leveloffset=+1] -include::modules/osdk-ansible-extra-variables.adoc[leveloffset=+1] -include::modules/osdk-ansible-runner-directory.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc b/operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc deleted file mode 100644 index 12e08c585797..000000000000 --- a/operators/operator_sdk/ansible/osdk-ansible-tutorial.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id="osdk-ansible-tutorial"] -= Operator SDK tutorial for Ansible-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-ansible-tutorial - -toc::[] - -Operator developers can take advantage of link:https://docs.ansible.com/ansible/latest/index.html[Ansible] support in the Operator SDK to build an example Ansible-based Operator for Memcached, a distributed key-value store, and manage its lifecycle. This tutorial walks through the following process: - -* Create a Memcached deployment -* Ensure that the deployment size is the same as specified by the `Memcached` custom resource (CR) spec -* Update the `Memcached` CR status using the status writer with the names of the `memcached` pods - -This process is accomplished by using two centerpieces of the Operator Framework: - -Operator SDK:: The `operator-sdk` CLI tool and `controller-runtime` library API - -Operator Lifecycle Manager (OLM):: Installation, upgrade, and role-based access control (RBAC) of Operators on a cluster - -[NOTE] -==== -This tutorial goes into greater detail than xref:../../../operators/operator_sdk/ansible/osdk-ansible-quickstart.adoc#osdk-ansible-quickstart[Getting started with Operator SDK for Ansible-based Operators]. -==== - -include::modules/osdk-common-prereqs.adoc[leveloffset=+1] - -include::modules/osdk-create-project.adoc[leveloffset=+1] -include::modules/osdk-project-file.adoc[leveloffset=+2] - -include::modules/osdk-ansible-create-api.adoc[leveloffset=+1] -include::modules/osdk-ansible-modify-manager.adoc[leveloffset=+1] - -include::modules/osdk-run-operator.adoc[leveloffset=+1] -include::modules/osdk-run-locally.adoc[leveloffset=+2] -include::modules/osdk-prepare-supported-images.adoc[leveloffset=+2] -include::modules/osdk-run-deployment.adoc[leveloffset=+2] -include::modules/osdk-bundle-deploy-olm.adoc[leveloffset=+2] - -include::modules/osdk-create-cr.adoc[leveloffset=+1] - -[id="osdk-ansible-tutorial-addtl-resources"] -== Additional resources - -- See xref:../../../operators/operator_sdk/ansible/osdk-ansible-project-layout.adoc#osdk-ansible-project-layout[Project layout for Ansible-based Operators] to learn about the directory structures created by the Operator SDK. diff --git a/operators/operator_sdk/golang/images b/operators/operator_sdk/golang/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/operators/operator_sdk/golang/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/operators/operator_sdk/golang/modules b/operators/operator_sdk/golang/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/operators/operator_sdk/golang/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/operators/operator_sdk/golang/osdk-golang-project-layout.adoc b/operators/operator_sdk/golang/osdk-golang-project-layout.adoc deleted file mode 100644 index e9c89c135260..000000000000 --- a/operators/operator_sdk/golang/osdk-golang-project-layout.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="osdk-golang-project-layout"] -= Project layout for Go-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-golang-project-layout - -toc::[] - -The `operator-sdk` CLI can generate, or _scaffold_, a number of packages and files for each Operator project. - -include::modules/osdk-golang-project-layout.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/golang/osdk-golang-quickstart.adoc b/operators/operator_sdk/golang/osdk-golang-quickstart.adoc deleted file mode 100644 index fe41ebb29b8c..000000000000 --- a/operators/operator_sdk/golang/osdk-golang-quickstart.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="osdk-golang-quickstart"] -= Getting started with Operator SDK for Go-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-golang-quickstart - -toc::[] - -To demonstrate the basics of setting up and running a Go-based Operator using tools and libraries provided by the Operator SDK, Operator developers can build an example Go-based Operator for Memcached, a distributed key-value store, and deploy it to a cluster. - -include::modules/osdk-common-prereqs.adoc[leveloffset=+1] -include::modules/osdk-quickstart.adoc[leveloffset=+1] - -[id="osdk-golang-quickstart-next-steps"] -== Next steps - -* See xref:../../../operators/operator_sdk/golang/osdk-golang-tutorial.adoc#osdk-golang-tutorial[Operator SDK tutorial for Go-based Operators] for a more in-depth walkthrough on building a Go-based Operator. diff --git a/operators/operator_sdk/golang/osdk-golang-tutorial.adoc b/operators/operator_sdk/golang/osdk-golang-tutorial.adoc deleted file mode 100644 index 2dba6e2435b8..000000000000 --- a/operators/operator_sdk/golang/osdk-golang-tutorial.adoc +++ /dev/null @@ -1,53 +0,0 @@ -[id="osdk-golang-tutorial"] -= Operator SDK tutorial for Go-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-golang-tutorial - -toc::[] - -Operator developers can take advantage of Go programming language support in the Operator SDK to build an example Go-based Operator for Memcached, a distributed key-value store, and manage its lifecycle. - -This process is accomplished using two centerpieces of the Operator Framework: - -Operator SDK:: The `operator-sdk` CLI tool and `controller-runtime` library API - -Operator Lifecycle Manager (OLM):: Installation, upgrade, and role-based access control (RBAC) of Operators on a cluster - -[NOTE] -==== -This tutorial goes into greater detail than xref:../../../operators/operator_sdk/golang/osdk-golang-quickstart.adoc#osdk-golang-quickstart[Getting started with Operator SDK for Go-based Operators]. -==== - -include::modules/osdk-common-prereqs.adoc[leveloffset=+1] - -include::modules/osdk-create-project.adoc[leveloffset=+1] -include::modules/osdk-project-file.adoc[leveloffset=+2] -include::modules/osdk-golang-manager.adoc[leveloffset=+2] -include::modules/osdk-golang-multi-group-apis.adoc[leveloffset=+2] - -include::modules/osdk-golang-create-api-controller.adoc[leveloffset=+1] -include::modules/osdk-golang-define-api.adoc[leveloffset=+2] -include::modules/osdk-golang-generate-crd.adoc[leveloffset=+2] -include::modules/osdk-about-openapi-validation.adoc[leveloffset=+3] - -include::modules/osdk-golang-implement-controller.adoc[leveloffset=+1] - -The next subsections explain how the controller in the example implementation watches resources and how the reconcile loop is triggered. You can skip these subsections to go directly to xref:../../../operators/operator_sdk/golang/osdk-golang-tutorial.adoc#osdk-run-operator_osdk-golang-tutorial[Running the Operator]. - -include::modules/osdk-golang-controller-resources.adoc[leveloffset=+2] -include::modules/osdk-golang-controller-configs.adoc[leveloffset=+2] -include::modules/osdk-golang-controller-reconcile-loop.adoc[leveloffset=+2] -include::modules/osdk-golang-controller-rbac-markers.adoc[leveloffset=+2] - -include::modules/osdk-run-operator.adoc[leveloffset=+1] -include::modules/osdk-run-locally.adoc[leveloffset=+2] -include::modules/osdk-prepare-supported-images.adoc[leveloffset=+2] -include::modules/osdk-run-deployment.adoc[leveloffset=+2] -include::modules/osdk-bundle-deploy-olm.adoc[leveloffset=+2] - -include::modules/osdk-create-cr.adoc[leveloffset=+1] - -[id="osdk-golang-tutorial-addtl-resources"] -== Additional resources - -- See xref:../../../operators/operator_sdk/golang/osdk-golang-project-layout.adoc#osdk-golang-project-layout[Project layout for Go-based Operators] to learn about the directory structures created by the Operator SDK. diff --git a/operators/operator_sdk/helm/images b/operators/operator_sdk/helm/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/operators/operator_sdk/helm/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/operators/operator_sdk/helm/modules b/operators/operator_sdk/helm/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/operators/operator_sdk/helm/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/operators/operator_sdk/helm/osdk-helm-project-layout.adoc b/operators/operator_sdk/helm/osdk-helm-project-layout.adoc deleted file mode 100644 index eac580b93e2a..000000000000 --- a/operators/operator_sdk/helm/osdk-helm-project-layout.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="osdk-helm-project-layout"] -= Project layout for Helm-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-helm-project-layout - -toc::[] - -The `operator-sdk` CLI can generate, or _scaffold_, a number of packages and files for each Operator project. - -include::modules/osdk-helm-project-layout.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/helm/osdk-helm-quickstart.adoc b/operators/operator_sdk/helm/osdk-helm-quickstart.adoc deleted file mode 100644 index e3fd83a7fc41..000000000000 --- a/operators/operator_sdk/helm/osdk-helm-quickstart.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="osdk-helm-quickstart"] -= Getting started with Operator SDK for Helm-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-helm-quickstart - -toc::[] - -The Operator SDK includes options for generating an Operator project that leverages existing link:https://helm.sh/docs/[Helm] charts to deploy Kubernetes resources as a unified application, without having to write any Go code. - -To demonstrate the basics of setting up and running an link:https://helm.sh/docs/[Helm]-based Operator using tools and libraries provided by the Operator SDK, Operator developers can build an example Helm-based Operator for Nginx and deploy it to a cluster. - -include::modules/osdk-common-prereqs.adoc[leveloffset=+1] -include::modules/osdk-quickstart.adoc[leveloffset=+1] - -[id="osdk-helm-quickstart-next-steps"] -== Next steps - -* See xref:../../../operators/operator_sdk/helm/osdk-helm-tutorial.adoc#osdk-helm-tutorial[Operator SDK tutorial for Helm-based Operators] for a more in-depth walkthrough on building a Helm-based Operator. diff --git a/operators/operator_sdk/helm/osdk-helm-support.adoc b/operators/operator_sdk/helm/osdk-helm-support.adoc deleted file mode 100644 index 00ce0a5e63eb..000000000000 --- a/operators/operator_sdk/helm/osdk-helm-support.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="osdk-helm-support"] -= Helm support in Operator SDK -include::modules/common-attributes.adoc[] -:context: osdk-helm-support - -toc::[] - -include::modules/osdk-helm-charts.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/helm/osdk-helm-tutorial.adoc b/operators/operator_sdk/helm/osdk-helm-tutorial.adoc deleted file mode 100644 index a9d48816a27e..000000000000 --- a/operators/operator_sdk/helm/osdk-helm-tutorial.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[id="osdk-helm-tutorial"] -= Operator SDK tutorial for Helm-based Operators -include::modules/common-attributes.adoc[] -:context: osdk-helm-tutorial - -toc::[] - -Operator developers can take advantage of link:https://helm.sh/docs/[Helm] support in the Operator SDK to build an example Helm-based Operator for Nginx and manage its lifecycle. This tutorial walks through the following process: - -* Create a Nginx deployment -* Ensure that the deployment size is the same as specified by the `Nginx` custom resource (CR) spec -* Update the `Nginx` CR status using the status writer with the names of the `nginx` pods - -This process is accomplished using two centerpieces of the Operator Framework: - -Operator SDK:: The `operator-sdk` CLI tool and `controller-runtime` library API - -Operator Lifecycle Manager (OLM):: Installation, upgrade, and role-based access control (RBAC) of Operators on a cluster - -[NOTE] -==== -This tutorial goes into greater detail than xref:../../../operators/operator_sdk/helm/osdk-helm-quickstart.adoc#osdk-helm-quickstart[Getting started with Operator SDK for Helm-based Operators]. -==== - -include::modules/osdk-common-prereqs.adoc[leveloffset=+1] - -include::modules/osdk-create-project.adoc[leveloffset=+1] -include::modules/osdk-helm-existing-chart.adoc[leveloffset=+2] -include::modules/osdk-project-file.adoc[leveloffset=+2] - -include::modules/osdk-helm-logic.adoc[leveloffset=+1] -include::modules/osdk-helm-sample-chart.adoc[leveloffset=+2] -include::modules/osdk-helm-modify-cr.adoc[leveloffset=+2] - -include::modules/osdk-run-operator.adoc[leveloffset=+1] -include::modules/osdk-run-locally.adoc[leveloffset=+2] -include::modules/osdk-prepare-supported-images.adoc[leveloffset=+2] -include::modules/osdk-run-deployment.adoc[leveloffset=+2] -include::modules/osdk-bundle-deploy-olm.adoc[leveloffset=+2] - -include::modules/osdk-create-cr.adoc[leveloffset=+1] - -[id="osdk-helm-tutorial-addtl-resources"] -== Additional resources - -- See xref:../../../operators/operator_sdk/helm/osdk-helm-project-layout.adoc#osdk-helm-project-layout[Project layout for Helm-based Operators] to learn about the directory structures created by the Operator SDK. diff --git a/operators/operator_sdk/images b/operators/operator_sdk/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/operators/operator_sdk/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/operators/operator_sdk/modules b/operators/operator_sdk/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/operators/operator_sdk/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/operators/operator_sdk/osdk-about.adoc b/operators/operator_sdk/osdk-about.adoc deleted file mode 100644 index fcdd2395f134..000000000000 --- a/operators/operator_sdk/osdk-about.adoc +++ /dev/null @@ -1,54 +0,0 @@ -[id="osdk-about"] -= About the Operator SDK -include::modules/common-attributes.adoc[] -:context: osdk-about - -toc::[] - -The link:https://operatorframework.io/[Operator Framework] is an open source toolkit to manage Kubernetes native applications, called _Operators_, in an effective, automated, and scalable way. Operators take advantage of Kubernetes extensibility to deliver the automation advantages of cloud services, like provisioning, scaling, and backup and restore, while being able to run anywhere that Kubernetes can run. - -Operators make it easy to manage complex, stateful applications on top of Kubernetes. However, writing an Operator today can be difficult because of challenges such as using low-level APIs, writing boilerplate, and a lack of modularity, which leads to duplication. - -The Operator SDK, a component of the Operator Framework, provides a command-line interface (CLI) tool that Operator developers can use to build, test, and deploy an Operator. - -**Why use the Operator SDK?** - -The Operator SDK simplifies this process of building Kubernetes-native applications, which can require deep, application-specific operational knowledge. The Operator SDK not only lowers that barrier, but it also helps reduce the amount of boilerplate code required for many common management capabilities, such as metering or monitoring. - -The Operator SDK is a framework that uses the link:https://github.com/kubernetes-sigs/controller-runtime[controller-runtime] library to make writing Operators easier by providing the following features: - -- High-level APIs and abstractions to write the operational logic more intuitively -- Tools for scaffolding and code generation to quickly bootstrap a new project -- Integration with Operator Lifecycle Manager (OLM) to streamline packaging, installing, and running Operators on a cluster -- Extensions to cover common Operator use cases -- Metrics set up automatically in any generated Go-based Operator for use on clusters where the Prometheus Operator is deployed - -Operator authors with cluster administrator access to a Kubernetes-based cluster (such as {product-title}) can use the Operator SDK CLI to develop their own Operators based on Go, Ansible, or Helm. link:https://kubebuilder.io/[Kubebuilder] is embedded into the Operator SDK as the scaffolding solution for Go-based Operators, which means existing Kubebuilder projects can be used as is with the Operator SDK and continue to work. - -[NOTE] -==== -{product-title} 4.7 supports Operator SDK v1.3.0 or later. -==== - -[id="osdk-about-what-are-operators"] -== What are Operators? - -For an overview about basic Operator concepts and terminology, see xref:../../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Understanding Operators]. - -include::modules/osdk-workflow.adoc[leveloffset=+1] - -[id="osdk-about-addtl-resources"] -== Additional resources - -- link:https://redhat-connect.gitbook.io/certified-operator-guide/[Certified Operator Build Guide] - -ifdef::openshift-origin[] -[id="osdk-about-getting-involved"] -== Getting involved - -This guide provides an effective demonstration of the value of the Operator Framework for building and managing Operators, but it is limited in scope. The Operator Framework and its components are open source, so visit each project individually and learn what else you can do: - -link:https://github.com/operator-framework[*github.com/operator-framework*] - -If you want to discuss your experience, have questions, or want to get involved, join the link:https://groups.google.com/forum/#!forum/operator-framework[Operator Framework mailing list]. -endif::[] diff --git a/operators/operator_sdk/osdk-cli-ref.adoc b/operators/operator_sdk/osdk-cli-ref.adoc deleted file mode 100644 index 42388ac786cf..000000000000 --- a/operators/operator_sdk/osdk-cli-ref.adoc +++ /dev/null @@ -1,41 +0,0 @@ -[id="osdk-cli-ref"] -= Operator SDK CLI reference -include::modules/common-attributes.adoc[] -:context: osdk-cli-ref - -toc::[] - -The Operator SDK command-line interface (CLI) is a development kit designed to make writing Operators easier. - -.Operator SDK CLI syntax -[source,terminal] ----- -$ operator-sdk <command> [<subcommand>] [<argument>] [<flags>] ----- - -Operator authors with cluster administrator access to a Kubernetes-based cluster (such as {product-title}) can use the Operator SDK CLI to develop their own Operators based on Go, Ansible, or Helm. link:https://kubebuilder.io/[Kubebuilder] is embedded into the Operator SDK as the scaffolding solution for Go-based Operators, which means existing Kubebuilder projects can be used as is with the Operator SDK and continue to work. - -include::modules/osdk-cli-ref-bundle.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-cleanup.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-completion.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-create.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-generate.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-generate-bundle.adoc[leveloffset=+2] -.Additional resources - -* See xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-bundle-deploy-olm_osdk-working-bundle-images[Bundling an Operator and deploying with Operator Lifecycle Manager] for a full procedure that includes using the `make bundle` command to call the `generate bundle` subcommand. - -include::modules/osdk-cli-ref-generate-kustomize.adoc[leveloffset=+2] - -include::modules/osdk-cli-ref-init.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-run.adoc[leveloffset=+1] -include::modules/osdk-cli-ref-run-bundle.adoc[leveloffset=+2] -.Additional resources - -* See xref:../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-operatorgroups-membership_olm-understanding-operatorgroups[Operator group membership] for details on possible install modes. - -include::modules/osdk-cli-ref-run-bundle-upgrade.adoc[leveloffset=+2] -include::modules/osdk-cli-ref-scorecard.adoc[leveloffset=+1] -.Additional resources - -* See xref:../../operators/operator_sdk/osdk-scorecard.adoc#osdk-scorecard[Validating Operators using the scorecard tool] for details about running the scorecard tool. diff --git a/operators/operator_sdk/osdk-generating-csvs.adoc b/operators/operator_sdk/osdk-generating-csvs.adoc deleted file mode 100644 index 87982f3c8209..000000000000 --- a/operators/operator_sdk/osdk-generating-csvs.adoc +++ /dev/null @@ -1,73 +0,0 @@ -[id="osdk-generating-csvs"] -= Defining cluster service versions (CSVs) -include::modules/common-attributes.adoc[] -:context: osdk-generating-csvs - -toc::[] - -A _cluster service version_ (CSV), defined by a `ClusterServiceVersion` object, is a YAML manifest created from Operator metadata that assists Operator Lifecycle Manager (OLM) in running the Operator in a cluster. It is the metadata that accompanies an Operator container image, used to populate user interfaces with information such as its logo, description, and version. It is also a source of technical information that is required to run the Operator, like the RBAC rules it requires and which custom resources (CRs) it manages or depends on. - -The Operator SDK includes the CSV generator to generate a CSV for the current Operator project, customized using information contained in YAML manifests and Operator source files. - -A CSV-generating command removes the responsibility of Operator authors having in-depth OLM knowledge in order for their Operator to interact with OLM or publish metadata to the Catalog Registry. Further, because the CSV spec will likely change over time as new Kubernetes and OLM features are implemented, the Operator SDK is equipped to easily extend its update system to handle new CSV features going forward. - -include::modules/osdk-how-csv-gen-works.adoc[leveloffset=+1] -.Additional resources - -* See xref:../../operators/operator_sdk/osdk-working-bundle-images.adoc#osdk-bundle-deploy-olm_osdk-working-bundle-images[Bundling an Operator and deploying with Operator Lifecycle Manager] for a full procedure that includes generating a bundle and CSV. - -include::modules/osdk-csv-bundle-files.adoc[leveloffset=+2] -include::modules/osdk-csv-ver.adoc[leveloffset=+2] - - -include::modules/osdk-manually-defined-csv-fields.adoc[leveloffset=+1] -.Additional resources - -- xref:../../operators/understanding/olm-what-operators-are.adoc#olm-maturity-model_olm-what-operators-are[Operator maturity model] - -include::modules/osdk-csv-manual-annotations.adoc[leveloffset=+2] -.Additional resources -- xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-crds-templates_osdk-generating-csvs[CRD templates] -- xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-init-resource_osdk-generating-csvs[Initializing required custom resources -] -- xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-suggested-namespace_osdk-generating-csvs[Setting a suggested namespace] -- xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-enabling-operator-for-restricted-network_osdk-generating-csvs[Enabling your Operator for restricted network environments] (disconnected mode) -- xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-hiding-internal-objects_osdk-generating-csvs[Hiding internal objects] -- xref:../../installing/installing-fips.adoc#installing-fips[Support for FIPS crytography] - -include::modules/olm-enabling-operator-restricted-network.adoc[leveloffset=+1] -include::modules/olm-enabling-operator-for-multi-arch.adoc[leveloffset=+1] -.Additional resources - -- See the link:https://docs.docker.com/registry/spec/manifest-v2-2/#manifest-list[Image Manifest V 2, Schema 2] specification for more information on manifest lists. - -include::modules/olm-arch-os-support.adoc[leveloffset=+2] - -include::modules/osdk-suggested-namespace.adoc[leveloffset=+1] -include::modules/osdk-operatorconditions.adoc[leveloffset=+1] -.Additional resources - -* xref:../../operators/understanding/olm/olm-operatorconditions.adoc#olm-operatorconditions[Operator conditions] - -include::modules/olm-defining-csv-webhooks.adoc[leveloffset=+1] -.Additional resources - -* xref:../../architecture/admission-plug-ins.adoc#admission-webhook-types_admission-plug-ins[Types of webhook admission plug-ins] -* Kubernetes documentation: -** link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook[Validating admission webhooks] -** link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook[Mutating admission webhooks] -** link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#webhook-conversion[Conversion webhooks] - -include::modules/olm-webhook-considerations.adoc[leveloffset=+2] - -include::modules/osdk-crds.adoc[leveloffset=+1] -include::modules/osdk-owned-crds.adoc[leveloffset=+2] -include::modules/osdk-required-crds.adoc[leveloffset=+2] -include::modules/olm-dependency-resolution-crd-upgrades.adoc[leveloffset=+2] -include::modules/olm-adding-new-crd-version.adoc[leveloffset=+3] -include::modules/olm-removing-crd-version.adoc[leveloffset=+3] -include::modules/osdk-crd-templates.adoc[leveloffset=+2] -include::modules/osdk-hiding-internal-objects.adoc[leveloffset=+2] -include::modules/osdk-init-resource.adoc[leveloffset=+2] - -include::modules/osdk-apiservices.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/osdk-installing-cli.adoc b/operators/operator_sdk/osdk-installing-cli.adoc deleted file mode 100644 index 8f042515b301..000000000000 --- a/operators/operator_sdk/osdk-installing-cli.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="osdk-installing-cli"] -= Installing the Operator SDK CLI -include::modules/common-attributes.adoc[] -:context: osdk-installing-cli - -toc::[] - -The Operator SDK provides a command-line interface (CLI) tool that Operator developers can use to build, test, and deploy an Operator. You can install the Operator SDK CLI on your workstation so that you are prepared to start authoring your own Operators. - -[NOTE] -==== -{product-title} 4.7 supports Operator SDK v1.3.0. -==== - -include::modules/osdk-installing-cli-linux-macos.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/osdk-leader-election.adoc b/operators/operator_sdk/osdk-leader-election.adoc deleted file mode 100644 index 81096abcd420..000000000000 --- a/operators/operator_sdk/osdk-leader-election.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="osdk-leader-election"] -= Configuring leader election -include::modules/common-attributes.adoc[] -:context: osdk-leader-election - -toc::[] - -During the lifecycle of an Operator, it is possible that there may be more than one instance running at any given time, for example when rolling out an upgrade for the Operator. In such a scenario, it is necessary to avoid contention between multiple Operator instances using leader election. This ensures only one leader instance handles the reconciliation while the other instances are inactive but ready to take over when the leader steps down. - -There are two different leader election implementations to choose from, each with its own trade-off: - -Leader-for-life:: The leader pod only gives up leadership, using garbage collection, when it is deleted. This implementation precludes the possibility of two instances mistakenly running as leaders, a state also known as split brain. However, this method can be subject to a delay in electing a new leader. For example, when the leader pod is on an unresponsive or partitioned node, the link:https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/#options[`pod-eviction-timeout`] dictates long how it takes for the leader pod to be deleted from the node and step down, with a default of `5m`. See the link:https://godoc.org/github.com/operator-framework/operator-sdk/pkg/leader[Leader-for-life] Go documentation for more. - -Leader-with-lease:: The leader pod periodically renews the leader lease and gives up leadership when it cannot renew the lease. This implementation allows for a faster transition to a new leader when the existing leader is isolated, but there is a possibility of split brain in link:https://github.com/kubernetes/client-go/blob/30b06a83d67458700a5378239df6b96948cb9160/tools/leaderelection/leaderelection.go#L21-L24[certain situations]. See the link:https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/leaderelection[Leader-with-lease] Go documentation for more. - -By default, the Operator SDK enables the Leader-for-life implementation. Consult the related Go documentation for both approaches to consider the trade-offs that make sense for your use case. - -The following examples illustrate how to use the two options. - -include::modules/osdk-leader-election-types.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc b/operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc deleted file mode 100644 index 1a55890cf4d9..000000000000 --- a/operators/operator_sdk/osdk-migrating-to-v0-1-0.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="osdk-migrating-to-v0-1-0"] -= Migrating to Operator SDK v0.1.0 -include::modules/common-attributes.adoc[] -:context: osdk-migrating-to-v0-1-0 - -toc::[] - -This guide describes how to migrate an Operator project built using Operator SDK v0.0.x to the project structure required by link:https://github.com/operator-framework/operator-sdk/releases[Operator SDK v0.1.0]. - -The recommended method for migrating your project is to: - -. Initialize a new v0.1.0 project. -. Copy your code into the new project. -. Modify the new project as described for v0.1.0. - -This guide uses the `memcached-operator`, the example project from xref:../../operators/operator_sdk/osdk-about.adoc#osdk-about[the Operator SDK], to illustrate the migration steps. See the link:https://github.com/operator-framework/operator-sdk-samples/tree/aa15bd278eec0959595e0a0a7282a26055d7f9d6/memcached-operator[v0.0.7 memcached-operator] and link:https://github.com/operator-framework/operator-sdk-samples/tree/4c6934448684a6953ece4d3d9f3f77494b1c125e/memcached-operator[v0.1.0 memcached-operator] project structures for pre- and post-migration examples, respectively. - -include::modules/creating-new-osdk-v0-1-0-project.adoc[leveloffset=+1] -include::modules/migrating-custom-types-pkg-apis.adoc[leveloffset=+1] -include::modules/migrating-reconcile-code.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/osdk-monitoring-prometheus.adoc b/operators/operator_sdk/osdk-monitoring-prometheus.adoc deleted file mode 100644 index 4015778322b5..000000000000 --- a/operators/operator_sdk/osdk-monitoring-prometheus.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="osdk-monitoring-prometheus"] -= Configuring built-in monitoring with Prometheus -include::modules/common-attributes.adoc[] -:context: osdk-monitoring-prometheus - -toc::[] - -This guide describes the built-in monitoring support provided by the Operator SDK using the Prometheus Operator and details usage for Operator authors. - -include::modules/osdk-monitoring-prometheus-operator-support.adoc[leveloffset=+1] - -include::modules/osdk-monitoring-prometheus-metrics-helper.adoc[leveloffset=+1] -include::modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc[leveloffset=+2] - -include::modules/osdk-monitoring-prometheus-servicemonitor.adoc[leveloffset=+1] -include::modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc[leveloffset=+2] diff --git a/operators/operator_sdk/osdk-scorecard.adoc b/operators/operator_sdk/osdk-scorecard.adoc deleted file mode 100644 index d1752a0d33fb..000000000000 --- a/operators/operator_sdk/osdk-scorecard.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="osdk-scorecard"] -= Validating Operators using the scorecard tool -include::modules/common-attributes.adoc[] -:context: osdk-scorecard - -toc::[] - -As an Operator author, you can use the scorecard tool in the Operator SDK to do the following tasks: - -* Validate that your Operator project is free of syntax errors and packaged correctly -* Review suggestions about ways you can improve your Operator - -include::modules/osdk-scorecard-about.adoc[leveloffset=+1] -include::modules/osdk-scorecard-config.adoc[leveloffset=+1] -include::modules/osdk-scorecard-tests.adoc[leveloffset=+1] -include::modules/osdk-scorecard-run.adoc[leveloffset=+1] -include::modules/osdk-scorecard-output.adoc[leveloffset=+1] -include::modules/osdk-scorecard-select-tests.adoc[leveloffset=+1] -include::modules/osdk-scorecard-parallel.adoc[leveloffset=+1] -include::modules/osdk-scorecard-custom-tests.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/osdk-working-bundle-images.adoc b/operators/operator_sdk/osdk-working-bundle-images.adoc deleted file mode 100644 index f2568dc8cac4..000000000000 --- a/operators/operator_sdk/osdk-working-bundle-images.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="osdk-working-bundle-images"] -= Working with bundle images -include::modules/common-attributes.adoc[] -:context: osdk-working-bundle-images - -toc::[] - -You can use the Operator SDK to package, deploy, and upgrade Operators in the Bundle Format on Operator Lifecycle Manager (OLM). - -include::modules/osdk-bundle-deploy-olm.adoc[leveloffset=+1] -include::modules/osdk-bundle-upgrade-olm.adoc[leveloffset=+1] - -[id="osdk-working-bundle-images-additional-resources"] -== Additional resources - -* See xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Operator Framework packaging formats] for details on the Bundle Format. -* See xref:../../operators/admin/olm-managing-custom-catalogs.adoc#olm-managing-custom-catalogs[Managing custom catalogs] for details on adding bundle images to index images by using the `opm` command. -* See xref:../../operators/understanding/olm/olm-workflow.adoc#olm-workflow[Operator Lifecycle Manager workflow] for details on how upgrades work for installed Operators. diff --git a/operators/understanding/crds/crd-extending-api-with-crds.adoc b/operators/understanding/crds/crd-extending-api-with-crds.adoc deleted file mode 100644 index 3000f0482ae2..000000000000 --- a/operators/understanding/crds/crd-extending-api-with-crds.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="crd-extending-api-with-crds"] -= Extending the Kubernetes API with custom resource definitions -include::modules/common-attributes.adoc[] -:context: crd-extending-api-with-crds - -toc::[] - -Operators use the Kubernetes extension mechanism, custom resource definitions (CRDs), so that custom objects managed by the Operator look and act just like the built-in, native Kubernetes objects. This guide describes how cluster administrators can extend their {product-title} cluster by creating and managing CRDs. - -include::modules/crd-custom-resource-definitions.adoc[leveloffset=+1] -include::modules/crd-creating-crds.adoc[leveloffset=+1] -include::modules/crd-creating-aggregated-cluster-roles.adoc[leveloffset=+1] -include::modules/crd-creating-custom-resources-from-file.adoc[leveloffset=+1] -include::modules/crd-inspecting-custom-resources.adoc[leveloffset=+1] diff --git a/operators/understanding/crds/crd-managing-resources-from-crds.adoc b/operators/understanding/crds/crd-managing-resources-from-crds.adoc deleted file mode 100644 index e28dd27805c4..000000000000 --- a/operators/understanding/crds/crd-managing-resources-from-crds.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="crd-managing-resources-from-crds"] -= Managing resources from custom resource definitions -include::modules/common-attributes.adoc[] -:context: crd-managing-resources-from-crds - -toc::[] - -This guide describes how developers can manage custom resources (CRs) that come from custom resource definitions (CRDs). - -include::modules/crd-custom-resource-definitions.adoc[leveloffset=+1] -include::modules/crd-creating-custom-resources-from-file.adoc[leveloffset=+1] -include::modules/crd-inspecting-custom-resources.adoc[leveloffset=+1] diff --git a/operators/understanding/crds/images b/operators/understanding/crds/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/operators/understanding/crds/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/operators/understanding/crds/modules b/operators/understanding/crds/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/operators/understanding/crds/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/operators/understanding/images b/operators/understanding/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/operators/understanding/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/operators/understanding/modules b/operators/understanding/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/operators/understanding/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/operators/understanding/olm-common-terms.adoc b/operators/understanding/olm-common-terms.adoc deleted file mode 100644 index 1a38f25ab93b..000000000000 --- a/operators/understanding/olm-common-terms.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="olm-common-terms"] -= Operator Framework glossary of common terms -include::modules/common-attributes.adoc[] -:context: olm-common-terms - -toc::[] - -This topic provides a glossary of common terms related to the Operator Framework, including Operator Lifecycle Manager (OLM) and the Operator SDK, for both packaging formats: Package Manifest Format and Bundle Format. - -include::modules/olm-terms.adoc[leveloffset=+1] diff --git a/operators/understanding/olm-packaging-format.adoc b/operators/understanding/olm-packaging-format.adoc deleted file mode 100644 index 6462757d2dd6..000000000000 --- a/operators/understanding/olm-packaging-format.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[id="olm-packaging-format"] -= Operator Framework packaging formats -include::modules/common-attributes.adoc[] -:context: olm-packaging-format - -toc::[] - -This guide outlines the packaging formats for Operators supported by Operator Lifecycle Manager (OLM) in {product-title}. - -include::modules/olm-bundle-format.adoc[leveloffset=+1] -include::modules/olm-bundle-format-dependencies-file.adoc[leveloffset=+2] -.Additional resources - -* xref:../../operators/understanding/olm/olm-understanding-dependency-resolution.adoc#olm-understanding-dependency-resolution[Operator Lifecycle Manager dependency resolution] - -include::modules/olm-about-opm.adoc[leveloffset=+2] -* See xref:../../cli_reference/opm-cli.adoc#opm-cli[CLI tools] for steps on installing the `opm` CLI. - -include::modules/olm-package-manifest-format.adoc[leveloffset=+1] - -ifdef::openshift-origin[] -[id="olm-packaging-format-addtl-resources"] -== Additional resources - -See the upstream `operator-framework/operator-registry` project repository for more information on the Operator Bundle Format: - -- link:https://github.com/operator-framework/operator-registry/blob/master/docs/design/operator-bundle.md[Operator Bundle Overview] -- link:https://github.com/operator-framework/operator-registry/blob/master/README.md[Operator Registry README] - -See the project *Releases* page for `opm` CLI downloads: - -- link:https://github.com/operator-framework/operator-registry/releases[Releases] -endif::[] diff --git a/operators/understanding/olm-understanding-operatorhub.adoc b/operators/understanding/olm-understanding-operatorhub.adoc deleted file mode 100644 index 852d0e9137cf..000000000000 --- a/operators/understanding/olm-understanding-operatorhub.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="olm-understanding-operatorhub"] -= Understanding OperatorHub -include::modules/common-attributes.adoc[] -:context: olm-understanding-operatorhub - -toc::[] - -include::modules/olm-operatorhub-overview.adoc[leveloffset=+1] -include::modules/olm-operatorhub-architecture.adoc[leveloffset=+1] - -[id="olm-understanding-operatorhub-resources"] -== Additional resources - -* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-catalogsource_olm-understanding-olm[Catalog source] -* xref:../../operators/operator_sdk/osdk-about.adoc#osdk-about[About the Operator SDK] -* xref:../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-generating-csvs[Defining cluster service versions (CSVs)] -* xref:../../operators/understanding/olm/olm-workflow.adoc#olm-upgrades_olm-workflow[Operator installation and upgrade workflow in OLM] -* link:https://connect.redhat.com[Red Hat Partner Connect] -* link:https://marketplace.redhat.com[Red Hat Marketplace] diff --git a/operators/understanding/olm-what-operators-are.adoc b/operators/understanding/olm-what-operators-are.adoc deleted file mode 100644 index 8281c2ae4131..000000000000 --- a/operators/understanding/olm-what-operators-are.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="olm-what-operators-are"] -= What are Operators? -include::modules/common-attributes.adoc[] -:context: olm-what-operators-are - -toc::[] - -Conceptually, _Operators_ take human operational knowledge and encode it into software that is more easily shared with consumers. - -Operators are pieces of software that ease the operational complexity of running another piece of software. They act like an extension of the software vendor's engineering team, watching over a Kubernetes environment (such as {product-title}) and using its current state to make decisions in real time. Advanced Operators are designed to handle upgrades seamlessly, react to failures automatically, and not take shortcuts, like skipping a software backup process to save time. - -More technically, Operators are a method of packaging, deploying, and managing a Kubernetes application. - -A Kubernetes application is an app that is both deployed on Kubernetes and managed using the Kubernetes APIs and `kubectl` or `oc` tooling. To be able to make the most of Kubernetes, you require a set of cohesive APIs to extend in order to service and manage your apps that run on Kubernetes. Think of Operators as the runtime that manages this type of app on Kubernetes. - -include::modules/olm-why-use-operators.adoc[leveloffset=+1] -include::modules/olm-operator-framework.adoc[leveloffset=+1] -include::modules/olm-operator-maturity-model.adoc[leveloffset=+1] diff --git a/operators/understanding/olm/images b/operators/understanding/olm/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/operators/understanding/olm/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/operators/understanding/olm/modules b/operators/understanding/olm/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/operators/understanding/olm/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/operators/understanding/olm/olm-arch.adoc b/operators/understanding/olm/olm-arch.adoc deleted file mode 100644 index dd808e927caf..000000000000 --- a/operators/understanding/olm/olm-arch.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="olm-arch"] -= Operator Lifecycle Manager architecture -include::modules/common-attributes.adoc[] -:context: olm-arch - -toc::[] - -This guide outlines the component architecture of Operator Lifecycle Manager (OLM) in {product-title}. - -include::modules/olm-architecture.adoc[leveloffset=+1] -include::modules/olm-arch-olm-operator.adoc[leveloffset=+1] -include::modules/olm-arch-catalog-operator.adoc[leveloffset=+1] -include::modules/olm-arch-catalog-registry.adoc[leveloffset=+1] diff --git a/operators/understanding/olm/olm-operatorconditions.adoc b/operators/understanding/olm/olm-operatorconditions.adoc deleted file mode 100644 index e36a22d5f340..000000000000 --- a/operators/understanding/olm/olm-operatorconditions.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="olm-operatorconditions"] -= Operator conditions -include::modules/common-attributes.adoc[] -:context: olm-operatorconditions - -toc::[] - -This guide outlines how Operator Lifecycle Manager (OLM) uses Operator conditions. - -include::modules/olm-operatorconditions-about.adoc[leveloffset=+1] -include::modules/olm-supported-operatorconditions.adoc[leveloffset=+1] - -[id="olm-operatorconditions-addtl-resources"] -== Additional resources - -* xref:../../../operators/admin/olm-managing-operatorconditions.adoc#olm-operatorconditions[Managing Operator conditions] -* xref:../../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-operatorconditions_osdk-generating-csvs[Enabling Operator conditions] diff --git a/operators/understanding/olm/olm-understanding-dependency-resolution.adoc b/operators/understanding/olm/olm-understanding-dependency-resolution.adoc deleted file mode 100644 index 7efae1e4f9b8..000000000000 --- a/operators/understanding/olm/olm-understanding-dependency-resolution.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="olm-understanding-dependency-resolution"] -= Operator Lifecycle Manager dependency resolution -include::modules/common-attributes.adoc[] -:context: olm-understanding-dependency-resolution - -toc::[] - -This guide outlines dependency resolution and custom resource definition (CRD) upgrade lifecycles with Operator Lifecycle Manager (OLM) in {product-title}. - -include::modules/olm-dependency-resolution-about.adoc[leveloffset=+1] -include::modules/olm-bundle-format-dependencies-file.adoc[leveloffset=+1] -include::modules/olm-dependency-resolution-preferences.adoc[leveloffset=+1] -include::modules/olm-dependency-resolution-crd-upgrades.adoc[leveloffset=+1] -.Additional resources - -* xref:../../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-dependency-resolution-adding-new-crd-version_osdk-generating-csvs[Adding a new CRD version] -* xref:../../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-dependency-resolution-removing-crd-version_osdk-generating-csvs[Deprecating or removing a CRD version] - -include::modules/olm-dependencies-best-practices.adoc[leveloffset=+1] -.Additional resources - -* Kubernetes documentation: link:https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md#readme[Changing the API] - -include::modules/olm-dependencies-caveats.adoc[leveloffset=+1] -include::modules/olm-dependency-resolution-examples.adoc[leveloffset=+1] diff --git a/operators/understanding/olm/olm-understanding-metrics.adoc b/operators/understanding/olm/olm-understanding-metrics.adoc deleted file mode 100644 index 5d35914ba088..000000000000 --- a/operators/understanding/olm/olm-understanding-metrics.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="olm-understanding-metrics"] -= Operator Lifecycle Manager metrics -include::modules/common-attributes.adoc[] -:context: olm-understanding-metrics - -toc::[] - -include::modules/olm-metrics.adoc[leveloffset=+1] diff --git a/operators/understanding/olm/olm-understanding-olm.adoc b/operators/understanding/olm/olm-understanding-olm.adoc deleted file mode 100644 index e31beb05b5eb..000000000000 --- a/operators/understanding/olm/olm-understanding-olm.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="olm-understanding-olm"] -= Operator Lifecycle Manager concepts -include::modules/common-attributes.adoc[] -:context: olm-understanding-olm - -toc::[] - -This guide provides an overview of the concepts that drive Operator Lifecycle Manager (OLM) in {product-title}. - -include::modules/olm-overview.adoc[leveloffset=+1] -include::modules/olm-crds.adoc[leveloffset=+1] -include::modules/olm-csv.adoc[leveloffset=+2] -include::modules/olm-catalogsource.adoc[leveloffset=+2] -include::modules/olm-subscription.adoc[leveloffset=+2] -include::modules/olm-installplan.adoc[leveloffset=+2] -include::modules/olm-operatorgroups-about.adoc[leveloffset=+2] - -For more information, see xref:../../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-understanding-operatorgroups[Operator groups]. - -include::modules/olm-operatorconditions-about.adoc[leveloffset=+2] - -For more information, see xref:../../../operators/understanding/olm/olm-operatorconditions.adoc#olm-operatorconditions[Operator conditions]. diff --git a/operators/understanding/olm/olm-understanding-operatorgroups.adoc b/operators/understanding/olm/olm-understanding-operatorgroups.adoc deleted file mode 100644 index 710aab5e888b..000000000000 --- a/operators/understanding/olm/olm-understanding-operatorgroups.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="olm-understanding-operatorgroups"] -= Operator groups -include::modules/common-attributes.adoc[] -:context: olm-understanding-operatorgroups - -toc::[] - -This guide outlines the use of Operator groups with Operator Lifecycle Manager (OLM) in {product-title}. - -include::modules/olm-operatorgroups-about.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-membership.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-target-namespace.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-csv-annotations.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-provided-apis-annotations.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-rbac.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-copied-csvs.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-static.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-intersections.adoc[leveloffset=+1] -include::modules/olm-operatorgroups-troubleshooting.adoc[leveloffset=+1] diff --git a/operators/understanding/olm/olm-webhooks.adoc b/operators/understanding/olm/olm-webhooks.adoc deleted file mode 100644 index 84884c3bf320..000000000000 --- a/operators/understanding/olm/olm-webhooks.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="olm-webhooks"] -= Webhook management in Operator Lifecycle Manager -include::modules/common-attributes.adoc[] -:context: olm-webhooks - -toc::[] - -Webhooks allow Operator authors to intercept, modify, and accept or reject resources before they are saved to the object store and handled by the Operator controller. Operator Lifecycle Manager (OLM) can manage the lifecycle of these webhooks when they are shipped alongside your Operator. - -See xref:../../../operators/operator_sdk/osdk-generating-csvs.adoc#olm-defining-csv-webhook_osdk-generating-csvs[Defining cluster service versions (CSVs)] for details on how an Operator developer can define webhooks for their Operator, as well as considerations when running on OLM. - -[id="olm-webhooks-additional-resources"] -== Additional resources - -* xref:../../../architecture/admission-plug-ins.adoc#admission-webhook-types_admission-plug-ins[Types of webhook admission plug-ins] -* Kubernetes documentation: -** link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook[Validating admission webhooks] -** link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook[Mutating admission webhooks] -** link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#webhook-conversion[Conversion webhooks] diff --git a/operators/understanding/olm/olm-workflow.adoc b/operators/understanding/olm/olm-workflow.adoc deleted file mode 100644 index 1e91d5d4be17..000000000000 --- a/operators/understanding/olm/olm-workflow.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="olm-workflow"] -= Operator Lifecycle Manager workflow -include::modules/common-attributes.adoc[] -:context: olm-workflow - -toc::[] - -This guide outlines the workflow of Operator Lifecycle Manager (OLM) in {product-title}. - -include::modules/olm-upgrades.adoc[leveloffset=+1] diff --git a/operators/user/images b/operators/user/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/operators/user/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/operators/user/modules b/operators/user/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/operators/user/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/operators/user/olm-creating-apps-from-installed-operators.adoc b/operators/user/olm-creating-apps-from-installed-operators.adoc deleted file mode 100644 index 94589e4305c1..000000000000 --- a/operators/user/olm-creating-apps-from-installed-operators.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="olm-creating-apps-from-installed-operators"] -= Creating applications from installed Operators -include::modules/common-attributes.adoc[] -:context: olm-creating-apps-from-installed-operators - -toc::[] - -This guide walks developers through an example of creating applications from an installed Operator using the {product-title} web console. - -include::modules/olm-creating-etcd-cluster-from-operator.adoc[leveloffset=+1] diff --git a/operators/user/olm-installing-operators-in-namespace.adoc b/operators/user/olm-installing-operators-in-namespace.adoc deleted file mode 100644 index f875da6c26b8..000000000000 --- a/operators/user/olm-installing-operators-in-namespace.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="olm-installing-operators-in-namespace"] -= Installing Operators in your namespace -include::modules/common-attributes.adoc[] -:context: olm-installing-operators-in-namespace - -toc::[] - -If a cluster administrator has delegated Operator installation permissions to your account, you can install and subscribe an Operator to your namespace in a self-service manner. - -[id="olm-installing-operators-in-namespace-prereqs"] -== Prerequisites - -* A cluster administrator must add certain permissions to your {product-title} user account to allow self-service Operator installation to a namespace. See xref:../../operators/admin/olm-creating-policy.adoc#olm-creating-policy[Allowing non-cluster administrators to install Operators] for details. - -ifdef::openshift-origin[] -* Ensure that you have downloaded the link:https://cloud.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager site] as shown in _Obtaining the installation program_ in the installation documentation for your platform. -+ -If you have the pull secret, add the `redhat-operators` catalog to the `OperatorHub` custom resource (CR) as shown in _Configuring {product-title} to use Red Hat Operators_. -endif::[] - -include::modules/olm-installing-operators-from-operatorhub.adoc[leveloffset=+1] -* xref:../../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding OperatorHub] - -include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+1] -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/olm-installing-from-operatorhub-using-cli.adoc[leveloffset=+1] -.Additional resources - -* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-operatorgroups-about_olm-understanding-olm[Operator groups] -* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-subscription_olm-understanding-olm[Channel names] - -include::modules/olm-installing-specific-version-cli.adoc[leveloffset=+1] -.Additional resources - -* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator upgrade] -endif::[] diff --git a/output.txt b/output.txt new file mode 100644 index 000000000000..07a23e0c952e --- /dev/null +++ b/output.txt @@ -0,0 +1,576 @@ + ____ _ _ _ ____ ____ + | _ \| | | | / \ / ___/ ___| + | |_) | |_| | / _ \| | \___ \ + | _ <| _ |/ ___ | |___ ___) | + |_| \_|_| |_/_/ \_\____|____/ + + _ ____ ___ ____ ___ ____ ____ ____ _____ _ _ + / \ | _ |_ _| | _ \ / _ \ / ___/ ___| / ___| ____| \ | | + / _ \ | |_) | | | | | | | | | | \___ \ | | _| _| | \| | + / ___ \| __/| | | |_| | |_| | |___ ___) | | |_| | |___| |\ | +/_/ \_|_| |___| |____/ \___/ \____|____/ \____|_____|_| \_| + +Enter the version number of the RHACS release (e.g., 4.6.0): 4.8.0 +📥 Downloading OpenAPI specification v1 from https://mirror.openshift.com/pub/rhacs/openapi-spec/4.8.0/v1.swagger.json... +✅ Downloaded OpenAPI specification v1. +📥 Downloading OpenAPI specification v2 from https://mirror.openshift.com/pub/rhacs/openapi-spec/4.8.0/v2.swagger.json... +✅ Downloaded OpenAPI specification v2. +✂️ Processing OpenAPI specification v1.swagger.json with ./splitspec.js... +Processing OpenAPI spec: v1.swagger.json +Made 1399 changes to $ref values (standardizing to uppercase). +Processed definitions into /rhacs-api-docs-gen/specs/common_object_reference.json. +Created 62 tag-specific spec files in /rhacs-api-docs-gen/specs. +Successfully processed OpenAPI specification: v1.swagger.json +✂️ Processing OpenAPI specification v2.swagger.json with ./splitspec.js... +Processing OpenAPI spec: v2.swagger.json +Made 223 changes to $ref values (standardizing to uppercase). +Processed definitions into /rhacs-api-docs-gen/specs/common_object_reference.json. +Created 8 tag-specific spec files in /rhacs-api-docs-gen/specs. +Successfully processed OpenAPI specification: v2.swagger.json +📄 Generating AsciiDoc files... + +🔧 Generating AsciiDoc for common_object_reference.json... +🔧 Generating AsciiDoc for AdministrationEventService.json... +🔧 Generating AsciiDoc for AdministrationUsageService.json... +🔧 Generating AsciiDoc for AlertService.json... +🔧 Generating AsciiDoc for APITokenService.json... +🔧 Generating AsciiDoc for AuthProviderService.json... +🔧 Generating AsciiDoc for AuthService.json... +🔧 Generating AsciiDoc for CentralHealthService.json... +🔧 Generating AsciiDoc for CloudSourcesService.json... +🔧 Generating AsciiDoc for ClusterCVEService.json... +🔧 Generating AsciiDoc for ClusterInitService.json... +🔧 Generating AsciiDoc for ClustersService.json... +🔧 Generating AsciiDoc for CollectionService.json... +🔧 Generating AsciiDoc for ComplianceIntegrationService.json... +🔧 Generating AsciiDoc for ComplianceManagementService.json... +🔧 Generating AsciiDoc for ComplianceProfileService.json... +🔧 Generating AsciiDoc for ComplianceResultsService.json... +🔧 Generating AsciiDoc for ComplianceResultsStatsService.json... +🔧 Generating AsciiDoc for ComplianceRuleService.json... +🔧 Generating AsciiDoc for ComplianceScanConfigurationService.json... +🔧 Generating AsciiDoc for ComplianceService.json... +🔧 Generating AsciiDoc for ConfigService.json... +🔧 Generating AsciiDoc for CredentialExpiryService.json... +🔧 Generating AsciiDoc for DBService.json... +🔧 Generating AsciiDoc for DebugService.json... +🔧 Generating AsciiDoc for DeclarativeConfigHealthService.json... +🔧 Generating AsciiDoc for DelegatedRegistryConfigService.json... +🔧 Generating AsciiDoc for DeploymentService.json... +🔧 Generating AsciiDoc for DetectionService.json... +🔧 Generating AsciiDoc for DiscoveredClustersService.json... +🔧 Generating AsciiDoc for ExternalBackupService.json... +🔧 Generating AsciiDoc for FeatureFlagService.json... +🔧 Generating AsciiDoc for GroupService.json... +🔧 Generating AsciiDoc for GRPCPreferencesService.json... +🔧 Generating AsciiDoc for ImageCVEService.json... +🔧 Generating AsciiDoc for ImageIntegrationService.json... +🔧 Generating AsciiDoc for ImageService.json... +🔧 Generating AsciiDoc for IntegrationHealthService.json... +🔧 Generating AsciiDoc for ListeningEndpointsService.json... +🔧 Generating AsciiDoc for MetadataService.json... +🔧 Generating AsciiDoc for MitreAttackService.json... +🔧 Generating AsciiDoc for NamespaceService.json... +🔧 Generating AsciiDoc for NetworkBaselineService.json... +🔧 Generating AsciiDoc for NetworkGraphService.json... +🔧 Generating AsciiDoc for NetworkPolicyService.json... +🔧 Generating AsciiDoc for NodeCVEService.json... +🔧 Generating AsciiDoc for NodeService.json... +🔧 Generating AsciiDoc for NotifierService.json... +🔧 Generating AsciiDoc for PingService.json... +🔧 Generating AsciiDoc for PodService.json... +🔧 Generating AsciiDoc for PolicyCategoryService.json... +🔧 Generating AsciiDoc for PolicyService.json... +🔧 Generating AsciiDoc for ProbeUploadService.json... +🔧 Generating AsciiDoc for ProcessBaselineService.json... +🔧 Generating AsciiDoc for ProcessService.json... +🔧 Generating AsciiDoc for RbacService.json... +🔧 Generating AsciiDoc for ReportConfigurationService.json... +🔧 Generating AsciiDoc for ReportService.json... +🔧 Generating AsciiDoc for RoleService.json... +🔧 Generating AsciiDoc for SearchService.json... +🔧 Generating AsciiDoc for SecretService.json... +🔧 Generating AsciiDoc for SensorUpgradeService.json... +🔧 Generating AsciiDoc for ServiceAccountService.json... +🔧 Generating AsciiDoc for ServiceIdentityService.json... +🔧 Generating AsciiDoc for SignatureIntegrationService.json... +🔧 Generating AsciiDoc for TelemetryService.json... +🔧 Generating AsciiDoc for UserService.json... +🔧 Generating AsciiDoc for VulnerabilityExceptionService.json... +🔧 Generating AsciiDoc for VulnerabilityRequestService.json... +🔧 Generating AsciiDoc for VulnMgmtService.json...🏁 Finished AsciiDoc generation attempts. +🛠️ Updating all AsciiDoc files using ./updateasciidoc.js... + +🛠️ Updating rest_api/CommonObjectReference/CommonObjectReference.adoc... +🛠️ Updating rest_api/AdministrationEventService/AdministrationEventService.adoc... +🛠️ Updating rest_api/AdministrationUsageService/AdministrationUsageService.adoc... +🛠️ Updating rest_api/AlertService/AlertService.adoc... +🛠️ Updating rest_api/APITokenService/APITokenService.adoc... +🛠️ Updating rest_api/AuthProviderService/AuthProviderService.adoc... +🛠️ Updating rest_api/AuthService/AuthService.adoc... +🛠️ Updating rest_api/CentralHealthService/CentralHealthService.adoc... +🛠️ Updating rest_api/CloudSourcesService/CloudSourcesService.adoc... +🛠️ Updating rest_api/ClusterCVEService/ClusterCVEService.adoc... +🛠️ Updating rest_api/ClusterInitService/ClusterInitService.adoc... +🛠️ Updating rest_api/ClustersService/ClustersService.adoc... +🛠️ Updating rest_api/CollectionService/CollectionService.adoc... +🛠️ Updating rest_api/ComplianceIntegrationService/ComplianceIntegrationService.adoc... +🛠️ Updating rest_api/ComplianceManagementService/ComplianceManagementService.adoc... +🛠️ Updating rest_api/ComplianceProfileService/ComplianceProfileService.adoc... +🛠️ Updating rest_api/ComplianceResultsService/ComplianceResultsService.adoc... +🛠️ Updating rest_api/ComplianceResultsStatsService/ComplianceResultsStatsService.adoc... +🛠️ Updating rest_api/ComplianceRuleService/ComplianceRuleService.adoc... +🛠️ Updating rest_api/ComplianceScanConfigurationService/ComplianceScanConfigurationService.adoc... +🛠️ Updating rest_api/ComplianceService/ComplianceService.adoc... +🛠️ Updating rest_api/ConfigService/ConfigService.adoc... +🛠️ Updating rest_api/CredentialExpiryService/CredentialExpiryService.adoc... +🛠️ Updating rest_api/DBService/DBService.adoc... +🛠️ Updating rest_api/DebugService/DebugService.adoc... +🛠️ Updating rest_api/DeclarativeConfigHealthService/DeclarativeConfigHealthService.adoc... +🛠️ Updating rest_api/DelegatedRegistryConfigService/DelegatedRegistryConfigService.adoc... +🛠️ Updating rest_api/DeploymentService/DeploymentService.adoc... +🛠️ Updating rest_api/DetectionService/DetectionService.adoc... +🛠️ Updating rest_api/DiscoveredClustersService/DiscoveredClustersService.adoc... +🛠️ Updating rest_api/ExternalBackupService/ExternalBackupService.adoc... +🛠️ Updating rest_api/FeatureFlagService/FeatureFlagService.adoc... +🛠️ Updating rest_api/GroupService/GroupService.adoc... +🛠️ Updating rest_api/GRPCPreferencesService/GRPCPreferencesService.adoc... +🛠️ Updating rest_api/ImageCVEService/ImageCVEService.adoc... +🛠️ Updating rest_api/ImageIntegrationService/ImageIntegrationService.adoc... +🛠️ Updating rest_api/ImageService/ImageService.adoc... +🛠️ Updating rest_api/IntegrationHealthService/IntegrationHealthService.adoc... +🛠️ Updating rest_api/ListeningEndpointsService/ListeningEndpointsService.adoc... +🛠️ Updating rest_api/MetadataService/MetadataService.adoc... +🛠️ Updating rest_api/MitreAttackService/MitreAttackService.adoc... +🛠️ Updating rest_api/NamespaceService/NamespaceService.adoc... +🛠️ Updating rest_api/NetworkBaselineService/NetworkBaselineService.adoc... +🛠️ Updating rest_api/NetworkGraphService/NetworkGraphService.adoc... +🛠️ Updating rest_api/NetworkPolicyService/NetworkPolicyService.adoc... +🛠️ Updating rest_api/NodeCVEService/NodeCVEService.adoc... +🛠️ Updating rest_api/NodeService/NodeService.adoc... +🛠️ Updating rest_api/NotifierService/NotifierService.adoc... +🛠️ Updating rest_api/PingService/PingService.adoc... +🛠️ Updating rest_api/PodService/PodService.adoc... +🛠️ Updating rest_api/PolicyCategoryService/PolicyCategoryService.adoc... +🛠️ Updating rest_api/PolicyService/PolicyService.adoc... +🛠️ Updating rest_api/ProbeUploadService/ProbeUploadService.adoc... +🛠️ Updating rest_api/ProcessBaselineService/ProcessBaselineService.adoc... +🛠️ Updating rest_api/ProcessService/ProcessService.adoc... +🛠️ Updating rest_api/RbacService/RbacService.adoc... +🛠️ Updating rest_api/ReportConfigurationService/ReportConfigurationService.adoc... +🛠️ Updating rest_api/ReportService/ReportService.adoc... +🛠️ Updating rest_api/RoleService/RoleService.adoc... +🛠️ Updating rest_api/SearchService/SearchService.adoc... +🛠️ Updating rest_api/SecretService/SecretService.adoc... +🛠️ Updating rest_api/SensorUpgradeService/SensorUpgradeService.adoc... +🛠️ Updating rest_api/ServiceAccountService/ServiceAccountService.adoc... +🛠️ Updating rest_api/ServiceIdentityService/ServiceIdentityService.adoc... +🛠️ Updating rest_api/SignatureIntegrationService/SignatureIntegrationService.adoc... +🛠️ Updating rest_api/TelemetryService/TelemetryService.adoc... +🛠️ Updating rest_api/UserService/UserService.adoc... +🛠️ Updating rest_api/VulnerabilityExceptionService/VulnerabilityExceptionService.adoc... +🛠️ Updating rest_api/VulnerabilityRequestService/VulnerabilityRequestService.adoc... +🛠️ Updating rest_api/VulnMgmtService/VulnMgmtService.adoc... +✅ Updated AsciiDoc files. +🧹 Removing interim generated spec files (specs/ directory and swagger JSONs)... +✅ Removed interim spec files. +🗂️ Creating topic map (api_reference.yml)... +rm: cannot remove '/openshift-docs/rest_api': Permission denied +cp: cannot stat '/openshift-docs/rest_api': Permission denied +fs.js:114 + throw err; + ^ + +Error: EACCES: permission denied, open '/openshift-docs/_topic_maps/_topic_map.yml' + at Object.openSync (fs.js:443:3) + at Object.readFileSync (fs.js:343:35) + at Object.<anonymous> (/rhacs-api-docs-gen/updatetopicmap.js:16:18) + at Module._compile (internal/modules/cjs/loader.js:778:30) + at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10) + at Module.load (internal/modules/cjs/loader.js:653:32) + at tryModuleLoad (internal/modules/cjs/loader.js:593:12) + at Function.Module._load (internal/modules/cjs/loader.js:585:3) + at Function.Module.runMain (internal/modules/cjs/loader.js:831:12) + at startup (internal/bootstrap/node.js:283:19) +✅ Generated topic map and copied rest_api to /openshift-docs/rest_api. +🎉 All tasks completed successfully! +CONTAINER_ENGINE=podman 🐳 +CONTAINER_IMAGE=quay.io/redhat-docs/openshift-docs-asciidoc:latest + +🚧 Validating the docs... +Validating release_notes/48-release-notes.adoc ... +No errors found for release_notes/48-release-notes.adoc! ✅ +/ocpd-src/tmpko_eca_i.swp +Cleaning the drupal-build directory +Building the drupal files +Processing welcome +Processing release_notes +Processing cloud_service +Processing architecture +Processing installing +Processing configuration +Processing operating +Processing integration +Processing backup_and_restore +Processing upgrading +Processing cli +Processing troubleshooting +Processing troubleshooting_central +Processing telemetry +Processing support +Processing rest_api +--------------------------------------- +BUILDING openshift-acs BOOKS +--------------------------------------- +>>> Working on welcome book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with welcome book in openshift-acs <<< +--------------------------------------- +>>> Working on release_notes book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with release_notes book in openshift-acs <<< +--------------------------------------- +>>> Working on cloud_service book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with cloud_service book in openshift-acs <<< +--------------------------------------- +>>> Working on architecture book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with architecture book in openshift-acs <<< +--------------------------------------- +>>> Working on installing book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with installing book in openshift-acs <<< +--------------------------------------- +>>> Working on configuration book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with configuration book in openshift-acs <<< +--------------------------------------- +>>> Working on operating book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with operating book in openshift-acs <<< +--------------------------------------- +>>> Working on integration book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with integration book in openshift-acs <<< +--------------------------------------- +>>> Working on backup_and_restore book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with backup_and_restore book in openshift-acs <<< +--------------------------------------- +>>> Working on upgrading book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with upgrading book in openshift-acs <<< +--------------------------------------- +>>> Working on cli book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +asciidoctor: WARNING: tables must have at least one body row +>>> Finished with cli book in openshift-acs <<< +--------------------------------------- +>>> Working on troubleshooting book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with troubleshooting book in openshift-acs <<< +--------------------------------------- +>>> Working on troubleshooting_central book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with troubleshooting_central book in openshift-acs <<< +--------------------------------------- +>>> Working on telemetry book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with telemetry book in openshift-acs <<< +--------------------------------------- +>>> Working on support book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with support book in openshift-acs <<< +--------------------------------------- +>>> Working on rest_api book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with rest_api book in openshift-acs <<< +--------------------------------------- +All Successful +On branch ROX30086-rhacs-docs-main-new-1 +Your branch is up to date with 'upstream/rhacs-docs-main'. + +Untracked files: + (use "git add <file>..." to include in what will be committed) + output.txt + +nothing added to commit but untracked files present (use "git add" to track) + ____ _ _ _ ____ ____ + | _ \| | | | / \ / ___/ ___| + | |_) | |_| | / _ \| | \___ \ + | _ <| _ |/ ___ | |___ ___) | + |_| \_|_| |_/_/ \_\____|____/ + + _ ____ ___ ____ ___ ____ ____ ____ _____ _ _ + / \ | _ |_ _| | _ \ / _ \ / ___/ ___| / ___| ____| \ | | + / _ \ | |_) | | | | | | | | | | \___ \ | | _| _| | \| | + / ___ \| __/| | | |_| | |_| | |___ ___) | | |_| | |___| |\ | +/_/ \_|_| |___| |____/ \___/ \____|____/ \____|_____|_| \_| + +Enter the version number of the RHACS release (e.g., 4.6.0): 4.8.0 +📥 Downloading OpenAPI specification v1 from https://mirror.openshift.com/pub/rhacs/openapi-spec/4.8.0/v1.swagger.json... +✅ Downloaded OpenAPI specification v1. +📥 Downloading OpenAPI specification v2 from https://mirror.openshift.com/pub/rhacs/openapi-spec/4.8.0/v2.swagger.json... +✅ Downloaded OpenAPI specification v2. +✂️ Processing OpenAPI specification v1.swagger.json with ./splitspec.js... +Processing OpenAPI spec: v1.swagger.json +Made 1399 changes to $ref values (standardizing to uppercase). +Processed definitions into /rhacs-api-docs-gen/specs/common_object_reference.json. +Created 62 tag-specific spec files in /rhacs-api-docs-gen/specs. +Successfully processed OpenAPI specification: v1.swagger.json +✂️ Processing OpenAPI specification v2.swagger.json with ./splitspec.js... +Processing OpenAPI spec: v2.swagger.json +Made 223 changes to $ref values (standardizing to uppercase). +Processed definitions into /rhacs-api-docs-gen/specs/common_object_reference.json. +Created 8 tag-specific spec files in /rhacs-api-docs-gen/specs. +Successfully processed OpenAPI specification: v2.swagger.json +📄 Generating AsciiDoc files... + +🔧 Generating AsciiDoc for common_object_reference.json... +🔧 Generating AsciiDoc for AdministrationEventService.json... +🔧 Generating AsciiDoc for AdministrationUsageService.json... +🔧 Generating AsciiDoc for AlertService.json... +🔧 Generating AsciiDoc for APITokenService.json... +🔧 Generating AsciiDoc for AuthProviderService.json... +🔧 Generating AsciiDoc for AuthService.json... +🔧 Generating AsciiDoc for CentralHealthService.json... +🔧 Generating AsciiDoc for CloudSourcesService.json... +🔧 Generating AsciiDoc for ClusterCVEService.json... +🔧 Generating AsciiDoc for ClusterInitService.json... +🔧 Generating AsciiDoc for ClustersService.json... +🔧 Generating AsciiDoc for CollectionService.json... +🔧 Generating AsciiDoc for ComplianceIntegrationService.json... +🔧 Generating AsciiDoc for ComplianceManagementService.json... +🔧 Generating AsciiDoc for ComplianceProfileService.json... +🔧 Generating AsciiDoc for ComplianceResultsService.json... +🔧 Generating AsciiDoc for ComplianceResultsStatsService.json... +🔧 Generating AsciiDoc for ComplianceRuleService.json... +🔧 Generating AsciiDoc for ComplianceScanConfigurationService.json... +🔧 Generating AsciiDoc for ComplianceService.json... +🔧 Generating AsciiDoc for ConfigService.json... +🔧 Generating AsciiDoc for CredentialExpiryService.json... +🔧 Generating AsciiDoc for DBService.json... +🔧 Generating AsciiDoc for DebugService.json... +🔧 Generating AsciiDoc for DeclarativeConfigHealthService.json... +🔧 Generating AsciiDoc for DelegatedRegistryConfigService.json... +🔧 Generating AsciiDoc for DeploymentService.json... +🔧 Generating AsciiDoc for DetectionService.json... +🔧 Generating AsciiDoc for DiscoveredClustersService.json... +🔧 Generating AsciiDoc for ExternalBackupService.json... +🔧 Generating AsciiDoc for FeatureFlagService.json... +🔧 Generating AsciiDoc for GroupService.json... +🔧 Generating AsciiDoc for GRPCPreferencesService.json... +🔧 Generating AsciiDoc for ImageCVEService.json... +🔧 Generating AsciiDoc for ImageIntegrationService.json... +🔧 Generating AsciiDoc for ImageService.json... +🔧 Generating AsciiDoc for IntegrationHealthService.json... +🔧 Generating AsciiDoc for ListeningEndpointsService.json... +🔧 Generating AsciiDoc for MetadataService.json... +🔧 Generating AsciiDoc for MitreAttackService.json... +🔧 Generating AsciiDoc for NamespaceService.json... +🔧 Generating AsciiDoc for NetworkBaselineService.json... +🔧 Generating AsciiDoc for NetworkGraphService.json... +🔧 Generating AsciiDoc for NetworkPolicyService.json... +🔧 Generating AsciiDoc for NodeCVEService.json... +🔧 Generating AsciiDoc for NodeService.json... +🔧 Generating AsciiDoc for NotifierService.json... +🔧 Generating AsciiDoc for PingService.json... +🔧 Generating AsciiDoc for PodService.json... +🔧 Generating AsciiDoc for PolicyCategoryService.json... +🔧 Generating AsciiDoc for PolicyService.json... +🔧 Generating AsciiDoc for ProbeUploadService.json... +🔧 Generating AsciiDoc for ProcessBaselineService.json... +🔧 Generating AsciiDoc for ProcessService.json... +🔧 Generating AsciiDoc for RbacService.json... +🔧 Generating AsciiDoc for ReportConfigurationService.json... +🔧 Generating AsciiDoc for ReportService.json... +🔧 Generating AsciiDoc for RoleService.json... +🔧 Generating AsciiDoc for SearchService.json... +🔧 Generating AsciiDoc for SecretService.json... +🔧 Generating AsciiDoc for SensorUpgradeService.json... +🔧 Generating AsciiDoc for ServiceAccountService.json... +🔧 Generating AsciiDoc for ServiceIdentityService.json... +🔧 Generating AsciiDoc for SignatureIntegrationService.json... +🔧 Generating AsciiDoc for TelemetryService.json... +🔧 Generating AsciiDoc for UserService.json... +🔧 Generating AsciiDoc for VulnerabilityExceptionService.json... +🔧 Generating AsciiDoc for VulnerabilityRequestService.json... +🔧 Generating AsciiDoc for VulnMgmtService.json...🏁 Finished AsciiDoc generation attempts. +🛠️ Updating all AsciiDoc files using ./updateasciidoc.js... + +🛠️ Updating rest_api/CommonObjectReference/CommonObjectReference.adoc... +🛠️ Updating rest_api/AdministrationEventService/AdministrationEventService.adoc... +🛠️ Updating rest_api/AdministrationUsageService/AdministrationUsageService.adoc... +🛠️ Updating rest_api/AlertService/AlertService.adoc... +🛠️ Updating rest_api/APITokenService/APITokenService.adoc... +🛠️ Updating rest_api/AuthProviderService/AuthProviderService.adoc... +🛠️ Updating rest_api/AuthService/AuthService.adoc... +🛠️ Updating rest_api/CentralHealthService/CentralHealthService.adoc... +🛠️ Updating rest_api/CloudSourcesService/CloudSourcesService.adoc... +🛠️ Updating rest_api/ClusterCVEService/ClusterCVEService.adoc... +🛠️ Updating rest_api/ClusterInitService/ClusterInitService.adoc... +🛠️ Updating rest_api/ClustersService/ClustersService.adoc... +🛠️ Updating rest_api/CollectionService/CollectionService.adoc... +🛠️ Updating rest_api/ComplianceIntegrationService/ComplianceIntegrationService.adoc... +🛠️ Updating rest_api/ComplianceManagementService/ComplianceManagementService.adoc... +🛠️ Updating rest_api/ComplianceProfileService/ComplianceProfileService.adoc... +🛠️ Updating rest_api/ComplianceResultsService/ComplianceResultsService.adoc... +🛠️ Updating rest_api/ComplianceResultsStatsService/ComplianceResultsStatsService.adoc... +🛠️ Updating rest_api/ComplianceRuleService/ComplianceRuleService.adoc... +🛠️ Updating rest_api/ComplianceScanConfigurationService/ComplianceScanConfigurationService.adoc... +🛠️ Updating rest_api/ComplianceService/ComplianceService.adoc... +🛠️ Updating rest_api/ConfigService/ConfigService.adoc... +🛠️ Updating rest_api/CredentialExpiryService/CredentialExpiryService.adoc... +🛠️ Updating rest_api/DBService/DBService.adoc... +🛠️ Updating rest_api/DebugService/DebugService.adoc... +🛠️ Updating rest_api/DeclarativeConfigHealthService/DeclarativeConfigHealthService.adoc... +🛠️ Updating rest_api/DelegatedRegistryConfigService/DelegatedRegistryConfigService.adoc... +🛠️ Updating rest_api/DeploymentService/DeploymentService.adoc... +🛠️ Updating rest_api/DetectionService/DetectionService.adoc... +🛠️ Updating rest_api/DiscoveredClustersService/DiscoveredClustersService.adoc... +🛠️ Updating rest_api/ExternalBackupService/ExternalBackupService.adoc... +🛠️ Updating rest_api/FeatureFlagService/FeatureFlagService.adoc... +🛠️ Updating rest_api/GroupService/GroupService.adoc... +🛠️ Updating rest_api/GRPCPreferencesService/GRPCPreferencesService.adoc... +🛠️ Updating rest_api/ImageCVEService/ImageCVEService.adoc... +🛠️ Updating rest_api/ImageIntegrationService/ImageIntegrationService.adoc... +🛠️ Updating rest_api/ImageService/ImageService.adoc... +🛠️ Updating rest_api/IntegrationHealthService/IntegrationHealthService.adoc... +🛠️ Updating rest_api/ListeningEndpointsService/ListeningEndpointsService.adoc... +🛠️ Updating rest_api/MetadataService/MetadataService.adoc... +🛠️ Updating rest_api/MitreAttackService/MitreAttackService.adoc... +🛠️ Updating rest_api/NamespaceService/NamespaceService.adoc... +🛠️ Updating rest_api/NetworkBaselineService/NetworkBaselineService.adoc... +🛠️ Updating rest_api/NetworkGraphService/NetworkGraphService.adoc... +🛠️ Updating rest_api/NetworkPolicyService/NetworkPolicyService.adoc... +🛠️ Updating rest_api/NodeCVEService/NodeCVEService.adoc... +🛠️ Updating rest_api/NodeService/NodeService.adoc... +🛠️ Updating rest_api/NotifierService/NotifierService.adoc... +🛠️ Updating rest_api/PingService/PingService.adoc... +🛠️ Updating rest_api/PodService/PodService.adoc... +🛠️ Updating rest_api/PolicyCategoryService/PolicyCategoryService.adoc... +🛠️ Updating rest_api/PolicyService/PolicyService.adoc... +🛠️ Updating rest_api/ProbeUploadService/ProbeUploadService.adoc... +🛠️ Updating rest_api/ProcessBaselineService/ProcessBaselineService.adoc... +🛠️ Updating rest_api/ProcessService/ProcessService.adoc... +🛠️ Updating rest_api/RbacService/RbacService.adoc... +🛠️ Updating rest_api/ReportConfigurationService/ReportConfigurationService.adoc... +🛠️ Updating rest_api/ReportService/ReportService.adoc... +🛠️ Updating rest_api/RoleService/RoleService.adoc... +🛠️ Updating rest_api/SearchService/SearchService.adoc... +🛠️ Updating rest_api/SecretService/SecretService.adoc... +🛠️ Updating rest_api/SensorUpgradeService/SensorUpgradeService.adoc... +🛠️ Updating rest_api/ServiceAccountService/ServiceAccountService.adoc... +🛠️ Updating rest_api/ServiceIdentityService/ServiceIdentityService.adoc... +🛠️ Updating rest_api/SignatureIntegrationService/SignatureIntegrationService.adoc... +🛠️ Updating rest_api/TelemetryService/TelemetryService.adoc... +🛠️ Updating rest_api/UserService/UserService.adoc... +🛠️ Updating rest_api/VulnerabilityExceptionService/VulnerabilityExceptionService.adoc... +🛠️ Updating rest_api/VulnerabilityRequestService/VulnerabilityRequestService.adoc... +🛠️ Updating rest_api/VulnMgmtService/VulnMgmtService.adoc... +✅ Updated AsciiDoc files. +🧹 Removing interim generated spec files (specs/ directory and swagger JSONs)... +✅ Removed interim spec files. +🗂️ Creating topic map (api_reference.yml)... +✅ Generated topic map and copied rest_api to /openshift-docs/rest_api. +🎉 All tasks completed successfully! +CONTAINER_ENGINE=podman 🐳 +CONTAINER_IMAGE=quay.io/redhat-docs/openshift-docs-asciidoc:latest + +🚧 Validating the docs... +Validating release_notes/48-release-notes.adoc ... +No errors found for release_notes/48-release-notes.adoc! ✅ +/ocpd-src/tmpsddix6da.swp +Cleaning the drupal-build directory +Building the drupal files +Processing welcome +Processing release_notes +Processing cloud_service +Processing architecture +Processing installing +Processing configuration +Processing operating +Processing integration +Processing backup_and_restore +Processing upgrading +Processing cli +Processing troubleshooting +Processing troubleshooting_central +Processing telemetry +Processing support +Processing rest_api +--------------------------------------- +BUILDING openshift-acs BOOKS +--------------------------------------- +>>> Working on welcome book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with welcome book in openshift-acs <<< +--------------------------------------- +>>> Working on release_notes book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with release_notes book in openshift-acs <<< +--------------------------------------- +>>> Working on cloud_service book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with cloud_service book in openshift-acs <<< +--------------------------------------- +>>> Working on architecture book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with architecture book in openshift-acs <<< +--------------------------------------- +>>> Working on installing book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with installing book in openshift-acs <<< +--------------------------------------- +>>> Working on configuration book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with configuration book in openshift-acs <<< +--------------------------------------- +>>> Working on operating book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with operating book in openshift-acs <<< +--------------------------------------- +>>> Working on integration book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with integration book in openshift-acs <<< +--------------------------------------- +>>> Working on backup_and_restore book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with backup_and_restore book in openshift-acs <<< +--------------------------------------- +>>> Working on upgrading book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with upgrading book in openshift-acs <<< +--------------------------------------- +>>> Working on cli book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +asciidoctor: WARNING: tables must have at least one body row +>>> Finished with cli book in openshift-acs <<< +--------------------------------------- +>>> Working on troubleshooting book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with troubleshooting book in openshift-acs <<< +--------------------------------------- +>>> Working on troubleshooting_central book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with troubleshooting_central book in openshift-acs <<< +--------------------------------------- +>>> Working on telemetry book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with telemetry book in openshift-acs <<< +--------------------------------------- +>>> Working on support book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +>>> Finished with support book in openshift-acs <<< +--------------------------------------- +>>> Working on rest_api book in openshift-acs <<< +Transforming the AsciiDoc content to DocBook XML... +Unknown ID or title "SBOM-SPDX23-Document_ImageService", used as an internal cross reference +Unknown ID or title "SBOM-SPDX23-Document_ImageService", used as an internal cross reference +Unknown ID or title "SBOM_SPDX23_Document_CommonObjectReference", used as an internal cross reference +Unknown ID or title "SBOM_SPDX23_Document_packages_CommonObjectReference", used as an internal cross reference +Unknown ID or title "SBOM_SPDX23_Document_relationships_CommonObjectReference", used as an internal cross reference +>>> Validation of book rest_api in openshift-acs failed <<< +>>> Finished with rest_api book in openshift-acs <<< +--------------------------------------- diff --git a/pantheon2.yml b/pantheon2.yml new file mode 100644 index 000000000000..4a0041f330cc --- /dev/null +++ b/pantheon2.yml @@ -0,0 +1,23 @@ +server: https://pantheon.corp.redhat.com +repository: openshift-acs +variants: + - name: acs-365 + path: modules/common-attributes.adoc + canonical: true +assemblies: + - architecture/*.adoc + - backup_and_restore/*.adoc + - cli/*.adoc + - configuration/*.adoc + - installing/*.adoc + - integration/*.adoc + - operating/*.adoc + - release_notes/*.adoc + - support/*.adoc + - upgrading/*.adoc + - welcome/*.adoc +modules: + - modules/*.adoc +resources: + - images/*.png + - images/*.svg diff --git a/planning/PLACEHOLDER b/planning/PLACEHOLDER deleted file mode 100644 index 4020393e57eb..000000000000 --- a/planning/PLACEHOLDER +++ /dev/null @@ -1,2 +0,0 @@ -Please delete this file once you have assemblies here. - diff --git a/planning/images b/planning/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/planning/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/planning/modules b/planning/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/planning/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/post_installation_configuration/cluster-tasks.adoc b/post_installation_configuration/cluster-tasks.adoc deleted file mode 100644 index 58f580c80c2e..000000000000 --- a/post_installation_configuration/cluster-tasks.adoc +++ /dev/null @@ -1,601 +0,0 @@ -:context: post-install-cluster-tasks -[id="post-install-cluster-tasks"] -= Post-installation cluster tasks -include::modules/common-attributes.adoc[] - -toc::[] - -After installing {product-title}, you can further expand and customize your cluster to your requirements. - -[id="available_cluster_customizations"] -== Available cluster customizations - -You complete most of the cluster configuration and customization after you deploy your {product-title} cluster. A number of _configuration resources_ are available. - -[NOTE] -==== -If you install your cluster on IBM Z, not all features and functions are available. -==== - -You modify the configuration resources to configure the major features of the -cluster, such as the image registry, networking configuration, image build -behavior, and the identity provider. - -For current documentation of the settings that you control by using these resources, use -the `oc explain` command, for example `oc explain builds --api-version=config.openshift.io/v1` - -[id="configuration-resources_{context}"] -=== Cluster configuration resources - -All cluster configuration resources are globally scoped (not namespaced) and named `cluster`. -//// -Config changes should not require coordinated changes between config resources, if you find -yourself struggling to update these docs to explain coordinated changes, please reach out -to @api-approvers (github) or #forum-api-review (slack). -//// - -[cols="2a,8a",options="header"] -|=== -|Resource name -|Description - -|`apiserver.config.openshift.io` -|Provides API server configuration such as xref:../security/certificates/api-server.adoc#api-server-certificates[certificates and certificate authorities]. - -|`authentication.config.openshift.io` -|Controls the xref:../authentication/understanding-identity-provider.adoc#understanding-identity-provider[identity provider] and authentication configuration for the cluster. - -|`build.config.openshift.io` -|Controls default and enforced xref:../cicd/builds/build-configuration.adoc#build-configuration[configuration] for all builds on the cluster. - -|`console.config.openshift.io` -|Configures the behavior of the web console interface, including the xref:../web_console/configuring-web-console.adoc#configuring-web-console[logout behavior]. - -|`featuregate.config.openshift.io` -|Enables xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[FeatureGates] -so that you can use Tech Preview features. - -|`image.config.openshift.io` -|Configures how specific xref:../openshift_images/image-configuration.adoc#image-configuration[image registries] should be treated (allowed, disallowed, insecure, CA details). - -|`ingress.config.openshift.io` -|Configuration details related to xref:../networking/ingress-operator.adoc#nw-installation-ingress-config-asset_configuring-ingress[routing] such as the default domain for routes. - -|`oauth.config.openshift.io` -|Configures identity providers and other behavior related to xref:../authentication/configuring-internal-oauth.adoc#configuring-internal-oauth[internal OAuth server] flows. - -|`project.config.openshift.io` -|Configures xref:../applications/projects/configuring-project-creation.adoc#configuring-project-creation[how projects are created] including the project template. - -|`proxy.config.openshift.io` -|Defines proxies to be used by components needing external network access. Note: not all components currently consume this value. - -|`scheduler.config.openshift.io` -|Configures xref:../nodes/scheduling/nodes-scheduler-default.adoc#nodes-scheduler-default[scheduler] behavior such as policies and default node selectors. - -|=== - -[id="operator-configuration-resources_{context}"] -=== Operator configuration resources - -These configuration resources are cluster-scoped instances, named `cluster`, which control the behavior of a specific component as -owned by a particular Operator. - -[cols="2a,8a",options="header"] -|=== -|Resource name -|Description - -|`consoles.operator.openshift.io` -|Controls console appearance such as branding customizations - -|`config.imageregistry.operator.openshift.io` -|Configures xref:../registry/configuring-registry-operator.adoc#registry-operator-configuration-resource-overview_configuring-registry-operator[internal image registry settings] such as public routing, log levels, proxy settings, resource constraints, replica counts, and storage type. - -|`config.samples.operator.openshift.io` -|Configures the -xref:../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Samples Operator] -to control which example image streams and templates are installed on the cluster. - -|=== - - -[id="additional-configuration-resources_{context}"] -=== Additional configuration resources - -These configuration resources represent a single instance of a particular component. In some cases, you can request multiple -instances by creating multiple instances of the resource. In other cases, the Operator can use only a specific -resource instance name in a specific namespace. Reference the component-specific -documentation for details on how and when you can create additional resource instances. - -[cols="2a,2a,2a,8a",options="header"] -|=== -|Resource name -|Instance name -|Namespace -|Description - -|`alertmanager.monitoring.coreos.com` -|`main` -|`openshift-monitoring` -|Controls the xref:../monitoring/managing-alerts.adoc#managing-alerts[Alertmanager] deployment parameters. - -|`ingresscontroller.operator.openshift.io` -|`default` -|`openshift-ingress-operator` -|Configures xref:../networking/ingress-operator.adoc#configuring-ingress[Ingress Operator] behavior such as domain, number of replicas, certificates, and controller placement. - -|=== - - -[id="informational-resources_{context}"] -=== Informational Resources - -You use these resources to retrieve information about the cluster. Do not edit these resources directly. - -[cols="2a,2a,8a",options="header"] -|=== -|Resource name|Instance name|Description - -|`clusterversion.config.openshift.io` -|`version` -|In {product-title} {product-version}, you must not customize the `ClusterVersion` -resource for production clusters. Instead, follow the process to -xref:../updating/updating-cluster.adoc#updating-cluster[update a cluster]. - -|`dns.config.openshift.io` -|`cluster` -|You cannot modify the DNS settings for your cluster. You can -xref:../networking/dns-operator.adoc#dns-operator[view the DNS Operator status]. - -|`infrastructure.config.openshift.io` -|`cluster` -|Configuration details allowing the cluster to interact with its cloud provider. - -|`network.config.openshift.io` -|`cluster` -|You cannot modify your cluster networking after installation. To customize your network, follow the process to -xref:../installing/installing_aws/installing-aws-network-customizations.adoc#installing-aws-network-customizations[customize networking during installation]. - -|=== - -include::modules/images-update-global-pull-secret.adoc[leveloffset=+1] - -//// -[id="default-crds_{context}"] -== Custom resources - -A number of Custom Resource Definitions (CRDs) are available for you to use to -further tune your {product-title} deployment. You can deploy Custom Resources -that are based on many of these CRDs to add more functionality to your -{product-title} cluster. - -.Default CRDs -[cols="2a,2a,8a,2a,2a",options="header"] -|=== -|Name -|Group -|Description -|Namespaced -|Can deploy CR - - -|Alertmanager -|monitoring.coreos.com -| -|Namespaced -| - -|Authentication -|config.openshift.io -| -|Global -| - -|Build -|config.openshift.io -| -|Global -| - -|CatalogSourceConfig -|operators.coreos.com -| -|Namespaced -| - -|CatalogSource -|operators.coreos.com -| -|Namespaced -| - -|ClusterAutoscaler -|autoscaling.openshift.io -| -|Global -|Yes - -|ClusterDNS -|dns.openshift.io -| -|Global -| - -|IngressController -|operator.openshift.io -| -|Namespaced -| - -|ClusterNetwork -|network.openshift.io -| -|Global -| - -|ClusterOperator -|config.openshift.io -| -|Global -| - -|ClusterOperator -|operatorstatus.openshift.io -| -|Namespaced -| - -|Cluster -|machine.openshift.io -| -|Namespaced -| - -|ClusterServiceVersion -|operators.coreos.com -| -|Namespaced -| - -|ClusterVersion -|config.openshift.io -| -|Global -| - -|Config -|imageregistry.operator.openshift.io -| -|Global -| - -|Config -|samples.operator.openshift.io -| -|Global -| - -|Console -|console.config.openshift.io -|The top-level configuration for the web console. -|Namespaced -|The console CR is created by default with more or less empty values. It honors -new values. If it is deleted, it recreates automatically. - -|ControllerConfig -|machineconfiguration.openshift.io -| -|Global -| - -|CredentialsRequest -|cloudcredential.openshift.io -| -|Namespaced -| - -|DNS -|config.openshift.io -| -|Global -| - -|EgressNetworkPolicy -|network.openshift.io -| -|Namespaced -| - -|HostSubnet -|network.openshift.io -| -|Global -| - -|Image -|config.openshift.io -| -|Global -| - -|Infrastructure -|config.openshift.io -| -|Global -| - -|Ingress -|config.openshift.io -| -|Global -| - -|InstallPlan -|operators.coreos.com -| -|Namespaced -| - -|KubeControllerManager -|operator.openshift.io -| -|Global -| - -|KubeletConfig -|machineconfiguration.openshift.io -| -|Global -| - -|MachineAutoscaler -|autoscaling.openshift.io -| -|Namespaced -|Yes - -|MachineClass -|machine.openshift.io -| -|Namespaced -| - -|MachineConfigPool -|machineconfiguration.openshift.io -| -|Global -| - -|MachineConfig -|machineconfiguration.openshift.io -| -|Global -| - -|MachineDeployment -|machine.openshift.io -| -|Namespaced -| - -|MachineHealthCheck -|healthchecking.openshift.io -| -|Namespaced -| - -|Machine -|machine.openshift.io -| -|Namespaced -| - -|MachineSet -|machine.openshift.io -| -|Namespaced -| - -|MCOConfig -|machineconfiguration.openshift.io -| -|Global -| - -|NetNamespace -|network.openshift.io -| -|Global -| - -|NetworkAttachmentDefinition -|k8s.cni.cncf.io -| -|Namespaced -| - -|NetworkConfig -|networkoperator.openshift.io -| -|Global -| - -|Network -|config.openshift.io -| -|Global -| - -|OAuth -|config.openshift.io -| -|Global -| - -|OpenShiftAPIServer -|operator.openshift.io -| -|Global -| - -|OpenShiftControllerManagerOperatorConfig -|openshiftcontrollermanager.operator.openshift.io -| -|Global -| - -|OperatorGroup -|operators.coreos.com -| -|Namespaced -| - -|Project -|config.openshift.io -| -|Global -| - -|Prometheus -|monitoring.coreos.com -| -|Namespaced -| - -|PrometheusRule -|monitoring.coreos.com -| -|Namespaced -| - -|ServiceCertSignerOperatorConfig -|servicecertsigner.config.openshift.io -| -|Global -| - -|ServiceMonitor -|monitoring.coreos.com -| -|Namespaced -| - -|Subscription -|operators.coreos.com -| -|Namespaced -| - -|=== -//// - -[id="post-install-adjust-worker-nodes"] -== Adjust worker nodes -If you incorrectly sized the worker nodes during deployment, adjust them by creating one or more new machine sets, scale them up, then scale the original machine set down before removing them. - -include::modules/differences-between-machinesets-and-machineconfigpool.adoc[leveloffset=+2] - -include::modules/machineset-manually-scaling.adoc[leveloffset=+2] - -include::modules/machineset-delete-policy.adoc[leveloffset=+2] - -[id="post-install-creating-infrastructure-machinesets"] -== Creating infrastructure machine sets - -You can create a `MachineSet` object to host only infrastructure components. You apply specific Kubernetes labels to these machines and then update the infrastructure components to run on only those machines. These infrastructure nodes are not counted toward the total number of subscriptions that are required to run the environment. - -include::modules/infrastructure-components.adoc[leveloffset=+2] -include::modules/nodes-scheduler-node-selectors-cluster.adoc[leveloffset=+2] - -[id="moving-resources-to-infrastructure-machinesets"] -== Moving resources to infrastructure machine sets - -Some of the infrastructure resources are deployed in your cluster by default. You can move them to the infrastructure machine sets that you created. - -include::modules/infrastructure-moving-router.adoc[leveloffset=+2] - -include::modules/infrastructure-moving-registry.adoc[leveloffset=+2] - -[id="post-install-creating-infrastructure-machinesets-production"] -=== Creating infrastructure machine sets for production environments - -In a production deployment, deploy at least three machine sets to hold infrastructure components. Both the logging aggregation solution and the service mesh deploy Elasticsearch, and Elasticsearch requires three instances that are installed on different nodes. For high availability, install deploy these nodes to different availability zones. Since you need different machine sets for each availability zone, create at least three machine sets. - -include::modules/machineset-creating.adoc[leveloffset=+3] - -[id="post-install-creating-infrastructure-machinesets-clouds"] -=== Creating machine sets for different clouds - -Use the sample machine set for your cloud. - -include::modules/machineset-yaml-aws.adoc[leveloffset=+3] - -Machine sets running on AWS support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#machineset-non-guaranteed-instance_creating-machineset-aws[Spot Instances]. You can save on costs by using Spot Instances at a lower price compared to -On-Demand Instances on AWS. xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#machineset-creating-non-guaranteed-instance_creating-machineset-aws[Configure Spot Instances] by adding `spotMarketOptions` to the `MachineSet` YAML file. - -include::modules/machineset-yaml-azure.adoc[leveloffset=+3] - -Machine sets running on Azure support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#machineset-non-guaranteed-instance_creating-machineset-azure[Spot VMs]. You can save on costs by using Spot VMs at a lower price compared to standard VMs on Azure. You can xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#machineset-creating-non-guaranteed-instance_creating-machineset-azure[configure Spot VMs] by adding `spotVMOptions` to the `MachineSet` YAML file. - -include::modules/machineset-yaml-gcp.adoc[leveloffset=+3] - -Machine sets running on GCP support non-guaranteed xref:../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-non-guaranteed-instance_creating-machineset-gcp[preemptible VM instances]. You can save on costs by using preemptible VM instances at a lower price -compared to normal instances on GCP. You can xref:../machine_management/creating_machinesets/creating-machineset-gcp.adoc#machineset-creating-non-guaranteed-instance_creating-machineset-gcp[configure preemptible VM instances] by adding `preemptible` to the `MachineSet` YAML file. - -include::modules/machineset-yaml-vsphere.adoc[leveloffset=+3] - -include::modules/creating-an-infra-node.adoc[leveloffset=+1] -include::modules/creating-infra-machines.adoc[leveloffset=+1] - -include::modules/cluster-autoscaler-about.adoc[leveloffset=+1] -include::modules/cluster-autoscaler-cr.adoc[leveloffset=+2] -:FeatureName: cluster autoscaler -:FeatureResourceName: ClusterAutoscaler -include::modules/deploying-resource.adoc[leveloffset=+2] - -include::modules/machine-autoscaler-about.adoc[leveloffset=+1] -include::modules/machine-autoscaler-cr.adoc[leveloffset=+2] -:FeatureName: machine autoscaler -:FeatureResourceName: MachineAutoscaler -include::modules/deploying-resource.adoc[leveloffset=+2] - -include::modules/nodes-cluster-enabling-features-cluster.adoc[leveloffset=+1] - -[id="post-install-etcd-tasks"] -== etcd tasks -Back up etcd, enable or disable etcd encryption, or defragment etcd data. - -include::modules/about-etcd-encryption.adoc[leveloffset=+2] -include::modules/enabling-etcd-encryption.adoc[leveloffset=+2] -include::modules/disabling-etcd-encryption.adoc[leveloffset=+2] -include::modules/backup-etcd.adoc[leveloffset=+2] -include::modules/etcd-defrag.adoc[leveloffset=+2] -include::modules/dr-restoring-cluster-state.adoc[leveloffset=+2] - -[id="post-install-pod-disruption-budgets"] -== Pod disruption budgets - -Understand and configure pod disruption budgets. - -include::modules/nodes-pods-pod-disruption-about.adoc[leveloffset=+2] -include::modules/nodes-pods-pod-disruption-configuring.adoc[leveloffset=+2] - -[id="post-install-rotate-remove-cloud-creds"] -== Rotating or removing cloud provider credentials -After installing {product-title}, some organizations require the rotation or removal of the cloud provider credentials that were used during the initial installation. - -To allow the cluster to use the new credentials, you must update the secrets that the xref:../operators/operator-reference.adoc#cloud-credential-operator_red-hat-operators[Cloud Credential Operator (CCO)] uses to manage cloud provider credentials. - -include::modules/manually-rotating-cloud-creds.adoc[leveloffset=+2] - -include::modules/manually-removing-cloud-creds.adoc[leveloffset=+2] - -[discrete] -[id="manually-rotating-cloud-creds-addtl-resources"] -=== Additional resources - -* xref:../authentication/managing_cloud_provider_credentials/about-cloud-credential-operator.adoc[About the Cloud Credential Operator] -* xref:../installing/installing_aws/manually-creating-iam.adoc#admin-credentials-root-secret-formats_manually-creating-iam-aws[Amazon Web Services (AWS) secret format] -* xref:../installing/installing_azure/manually-creating-iam-azure.adoc#admin-credentials-root-secret-formats_manually-creating-iam-azure[Microsoft Azure secret format] -* xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#admin-credentials-root-secret-formats_manually-creating-iam-gcp[Google Cloud Platform (GCP) secret format] diff --git a/post_installation_configuration/configuring-alert-notifications.adoc b/post_installation_configuration/configuring-alert-notifications.adoc deleted file mode 100644 index 41370a39e8ab..000000000000 --- a/post_installation_configuration/configuring-alert-notifications.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="configuring-alert-notifications"] -= Configuring alert notifications -include::modules/common-attributes.adoc[] -:context: configuring-alert-notifications - -toc::[] - -In {product-title}, an alert is fired when the conditions defined in an alerting rule are true. An alert provides a notification that a set of circumstances are apparent within a cluster. Firing alerts can be viewed in the Alerting UI in the {product-title} web console by default. After an installation, you can configure {product-title} to send alert notifications to external systems. - -include::modules/monitoring-sending-notifications-to-external-systems.adoc[leveloffset=+1] -include::modules/monitoring-configuring-alert-receivers.adoc[leveloffset=+2] - -[id="configuring-alert-notifications-additional-resources"] -== Additional resources - -* xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Understanding the monitoring stack] -* xref:../monitoring/managing-alerts.adoc#managing-alerts[Managing alerts] diff --git a/post_installation_configuration/configuring-private-cluster.adoc b/post_installation_configuration/configuring-private-cluster.adoc deleted file mode 100644 index ff1611af43c7..000000000000 --- a/post_installation_configuration/configuring-private-cluster.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="configuring-private-cluster"] -= Configuring a private cluster -include::modules/common-attributes.adoc[] -:context: configuring-private-cluster - -toc::[] - -After you install an {product-title} version {product-version} cluster, you can set some of its core components to be private. - -[IMPORTANT] -==== -You can configure this change for only clusters that use infrastructure that you provision to a cloud provider. -==== - -include::modules/private-clusters-about.adoc[leveloffset=+1] - -include::modules/private-clusters-setting-dns-private.adoc[leveloffset=+1] - -include::modules/private-clusters-setting-ingress-private.adoc[leveloffset=+1] - -include::modules/private-clusters-setting-api-private.adoc[leveloffset=+1] diff --git a/post_installation_configuration/machine-configuration-tasks.adoc b/post_installation_configuration/machine-configuration-tasks.adoc deleted file mode 100644 index 4bdb10752953..000000000000 --- a/post_installation_configuration/machine-configuration-tasks.adoc +++ /dev/null @@ -1,43 +0,0 @@ -:context: post-install-machine-configuration-tasks -[id="post-install-machine-configuration-tasks"] -= Post-installation machine configuration tasks -include::modules/common-attributes.adoc[] - -toc::[] - -There are times when you need to make changes to the operating systems running on {product-title} nodes. This can include changing settings for network time service, adding kernel arguments, or configuring journaling in a specific way. - -Aside from a few specialized features, most changes to operating systems on {product-title} nodes can be done by creating what are referred to as `MachineConfig` objects that are managed by the Machine Config Operator. - -Tasks in this section describe how to use features of the Machine Config Operator to configure operating system features on {product-title} nodes. - -[id="understanding-the-machine-config-operator"] -== Understanding the Machine Config Operator - -include::modules/machine-config-operator.adoc[leveloffset=+2] -include::modules/machine-config-overview.adoc[leveloffset=+2] -include::modules/checking-mco-status.adoc[leveloffset=+2] - -[id="using-machineconfigs-to-change-machines"] -== Using MachineConfig objects to configure nodes - -You can use the tasks in this section to create `MachineConfig` objects that modify files, systemd unit files, and other operating system features running on {product-title} nodes. For more ideas on working with machine configs, see content related to link:https://access.redhat.com/solutions/5096731[adding] or -link:https://access.redhat.com/solutions/4510281[updating] SSH authorized keys, link:https://access.redhat.com/verify-images-ocp4[verifying image signatures], link:https://access.redhat.com/solutions/4727321[enabling SCTP], and link:https://access.redhat.com/solutions/5170251[configuring iSCSI initiatornames] for {product-title}. - -{product-title} version 4.7 supports link:https://coreos.github.io/ignition/configuration-v3_2/[Ignition specification version 3.2]. All new machine configs you create going forward should be based on Ignition specification version 3.2. If you are upgrading your {product-title} cluster, any existing Ignition specification version 2.x machine configs will be translated automatically to specification version 3.2. - -include::modules/installation-special-config-crony.adoc[leveloffset=+2] -include::modules/nodes-nodes-kernel-arguments.adoc[leveloffset=+2] -include::modules/nodes-nodes-rtkernel-arguments.adoc[leveloffset=+2] -include::modules/machineconfig-modify-journald.adoc[leveloffset=+2] -include::modules/rhcos-add-extensions.adoc[leveloffset=+2] - -Use the "Configuring crony time service" section as a model for how to go about adding other configuration files to {product-title} nodes. - -[id="configuring-machines-with-custom-resources"] -== Configuring MCO-related custom resources - -Besides managing `MachineConfig` objects, the MCO manages two custom resources (CRs): `KubeletConfig` and `ContainerRuntimeConfig`. Those CRs let you change node-level settings impacting how the Kubelet and CRI-O container runtime services behave. - -include::modules/create-a-kubeletconfig-crd-to-edit-kubelet-parameters.adoc[leveloffset=+2] -include::modules/create-a-containerruntimeconfig-crd.adoc[leveloffset=+2] diff --git a/post_installation_configuration/network-configuration.adoc b/post_installation_configuration/network-configuration.adoc deleted file mode 100644 index 69010f9074d7..000000000000 --- a/post_installation_configuration/network-configuration.adoc +++ /dev/null @@ -1,105 +0,0 @@ -:context: post-install-network-configuration -[id="post-install-network-configuration"] -= Post-installation network configuration -include::modules/common-attributes.adoc[] -include::modules/ossm-document-attributes.adoc[] - -toc::[] - -After installing {product-title}, you can further expand and customize your -network to your requirements. - -include::modules/nw-operator-cr.adoc[leveloffset=+1] - -include::modules/nw-proxy-configure-object.adoc[leveloffset=+1] - -include::modules/private-clusters-setting-dns-private.adoc[leveloffset=+1] - -[id="post-install-configuring_ingress_cluster_traffic"] -== Configuring ingress cluster traffic - -// This section is sourced from networking/configuring_ingress_cluster_traffic/overview-traffic.adoc - -{product-title} provides the following methods for communicating from outside the cluster with services running in the cluster: - -* If you have HTTP/HTTPS, use an Ingress Controller. -* If you have a TLS-encrypted protocol other than HTTPS, such as TLS with the SNI header, use an Ingress Controller. -* Otherwise, use a load balancer, an external IP, or a node port. - -[options="header"] -|=== - -|Method |Purpose - -|xref:../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc#configuring-ingress-cluster-traffic-ingress-controller[Use an Ingress Controller] -|Allows access to HTTP/HTTPS traffic and TLS-encrypted protocols other than HTTPS, such as TLS with the SNI header. - -|xref:../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-load-balancer.adoc#configuring-ingress-cluster-traffic-load-balancer[Automatically assign an external IP by using a load balancer service] -|Allows traffic to non-standard ports through an IP address assigned from a pool. - -|xref:../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-service-external-ip.adoc#configuring-ingress-cluster-traffic-service-external-ip[Manually assign an external IP to a service] -|Allows traffic to non-standard ports through a specific IP address. - -|xref:../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-nodeport.adoc#configuring-ingress-cluster-traffic-nodeport[Configure a `NodePort`] -|Expose a service on all nodes in the cluster. -|=== - -[id="post-install-configuring-node-port-service-range"] -== Configuring the node port service range - -As a cluster administrator, you can expand the available node port range. If your cluster uses of a large number of node ports, you might need to increase the number of available ports. - -The default port range is `30000-32767`. You can never reduce the port range, even if you first expand it beyond the default range. - -[id="post-install-configuring-node-port-service-range-prerequisites"] -=== Prerequisites - -- Your cluster infrastructure must allow access to the ports that you specify within the expanded range. For example, if you expand the node port range to `30000-32900`, the inclusive port range of `32768-32900` must be allowed by your firewall or packet filtering configuration. - -include::modules/nw-nodeport-service-range-edit.adoc[leveloffset=+3] - -[id="post-install-configuring-network-policy"] -== Configuring network policy - -As a cluster administrator or project administrator, you can configure network policies for a project. - -include::modules/nw-networkpolicy-about.adoc[leveloffset=+2] -include::modules/nw-networkpolicy-object.adoc[leveloffset=+2] -include::modules/nw-networkpolicy-create.adoc[leveloffset=+2] -include::modules/nw-networkpolicy-multitenant-isolation.adoc[leveloffset=+2] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -[id="post-install-nw-networkpolicy-creating-default-networkpolicy-objects-for-a-new-project"] -=== Creating default network policies for a new project - -As a cluster administrator, you can modify the new project template to -automatically include `NetworkPolicy` objects when you create a new project. - -include::modules/modifying-template-for-new-projects.adoc[leveloffset=+2] - -include::modules/nw-networkpolicy-project-defaults.adoc[leveloffset=+3] -endif::[] - -include::modules/ossm-supported-configurations.adoc[leveloffset=+1] - -include::modules/ossm-installation-activities.adoc[leveloffset=+2] - -.Next steps - -* xref:../service_mesh/v2x/installing-ossm.adoc#installing-ossm[Install {ProductName}] in your {product-title} environment. - -[id="post-installationrouting-optimization"] -== Optimizing routing - -The {product-title} HAProxy router scales to optimize performance. - -include::modules/baseline-router-performance.adoc[leveloffset=+2] - -include::modules/router-performance-optimizations.adoc[leveloffset=+2] - -[id="post-installation-osp-fips"] -== Post-installation {rh-openstack} network configuration - -You can configure some aspects of a {product-title} on {rh-openstack-first} cluster after installation. - -include::modules/installation-osp-configuring-api-floating-ip.adoc[leveloffset=+1] diff --git a/post_installation_configuration/node-tasks.adoc b/post_installation_configuration/node-tasks.adoc deleted file mode 100644 index 5f2c404fd5bd..000000000000 --- a/post_installation_configuration/node-tasks.adoc +++ /dev/null @@ -1,140 +0,0 @@ -:context: post-install-node-tasks -[id="post-install-node-tasks"] -= Post-installation node tasks -include::modules/common-attributes.adoc[] - -toc::[] - -After installing {product-title}, you can further expand and customize your -cluster to your requirements through certain node tasks. - -ifndef::openshift-origin[] -[id="post-install-config-adding-rhel-compute"] -== Adding RHEL compute machines to an {product-title} cluster -Understand and work with RHEL compute nodes. - -include::modules/rhel-compute-overview.adoc[leveloffset=+2] -include::modules/rhel-compute-requirements.adoc[leveloffset=+2] -include::modules/rhel-preparing-playbook-machine.adoc[leveloffset=+2] -include::modules/rhel-preparing-node.adoc[leveloffset=+2] -include::modules/rhel-adding-node.adoc[leveloffset=+2] -include::modules/rhel-ansible-parameters.adoc[leveloffset=+2] -include::modules/rhel-removing-rhcos.adoc[leveloffset=+2] -endif::[] - -[id="post-install-config-adding-fcos-compute"] -== Adding {op-system} compute machines to an {product-title} cluster - -You can add more {op-system-first} compute machines to your {product-title} cluster on bare metal. - -Before you add more compute machines to a cluster that you installed on bare metal infrastructure, you must create {op-system} machines for it to use. You can either use an ISO image or network PXE booting to create the machines. - -//Prerequisites also in adding-bare-metal-compute-user-infra.adoc -=== Prerequisites - -* You installed a cluster on bare metal. -* You have installation media and {op-system-first} images that you used to create your cluster. If you do not have these files, you must obtain them by following the instructions in the xref:../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[installation procedure]. - -include::modules/machine-user-infra-machines-iso.adoc[leveloffset=+2] - -include::modules/machine-user-infra-machines-pxe.adoc[leveloffset=+2] - -include::modules/installation-approve-csrs.adoc[leveloffset=+2] - -[id="post-installation-config-deploying-machine-health-checks"] -== Deploying machine health checks - -Understand and deploy machine health checks. - -include::modules/machine-user-provisioned-limitations.adoc[leveloffset=+2] -include::modules/machine-health-checks-about.adoc[leveloffset=+2] -include::modules/machine-health-checks-resource.adoc[leveloffset=+2] -include::modules/machine-health-checks-creating.adoc[leveloffset=+2] -include::modules/machineset-manually-scaling.adoc[leveloffset=+2] -include::modules/differences-between-machinesets-and-machineconfigpool.adoc[leveloffset=+2] - -include::modules/recommended-node-host-practices.adoc[leveloffset=+1] -include::modules/create-a-kubeletconfig-crd-to-edit-kubelet-parameters.adoc[leveloffset=+2] -include::modules/modify-unavailable-workers.adoc[leveloffset=+2] -include::modules/master-node-sizing.adoc[leveloffset=+2] -include::modules/setting-up-cpu-manager.adoc[leveloffset=+2] - -[id="post-install-huge-pages"] -== Huge pages -Understand and configure huge pages. - -include::modules/what-huge-pages-do.adoc[leveloffset=+2] -include::modules/how-huge-pages-are-consumed-by-apps.adoc[leveloffset=+2] -include::modules/configuring-huge-pages.adoc[leveloffset=+2] - -include::modules/nodes-pods-plugins-about.adoc[leveloffset=+1] -include::modules/nodes-pods-plugins-device-mgr.adoc[leveloffset=+2] -include::modules/nodes-pods-plugins-install.adoc[leveloffset=+2] - -[id="post-install-taints-tolerations"] -== Taints and tolerations -Understand and work with taints and tolerations. - -include::modules/nodes-scheduler-taints-tolerations-about.adoc[leveloffset=+2] -include::modules/nodes-scheduler-taints-tolerations-adding.adoc[leveloffset=+2] -include::modules/nodes-scheduler-taints-tolerations-adding-machineset.adoc[leveloffset=+2] -include::modules/nodes-scheduler-taints-tolerations-binding.adoc[leveloffset=+2] -include::modules/nodes-scheduler-taints-tolerations-special.adoc[leveloffset=+2] -include::modules/nodes-scheduler-taints-tolerations-removing.adoc[leveloffset=+2] - -[id="post-install-topology-manager"] -== Topology Manager -Understand and work with Topology Manager. - -include::modules/topology-manager-policies.adoc[leveloffset=+2] -include::modules/setting-up-topology-manager.adoc[leveloffset=+2] -include::modules/pod-interactions-with-topology-manager.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-resource-requests.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-override.adoc[leveloffset=+1] - -include::modules/nodes-cluster-resource-override-deploy-console.adoc[leveloffset=+2] - -include::modules/nodes-cluster-resource-override-deploy-cli.adoc[leveloffset=+2] - -include::modules/nodes-cluster-resource-configure.adoc[leveloffset=+2] - -include::modules/nodes-cluster-node-overcommit.adoc[leveloffset=+1] - -include::modules/nodes-cluster-overcommit-resources-containers.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-qos-about.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-configure-nodes.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-node-enforcing.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-node-resources.adoc[leveloffset=+2] - -include::modules/nodes-cluster-overcommit-node-disable.adoc[leveloffset=+2] - -include::modules/nodes-cluster-project-overcommit.adoc[leveloffset=+1] - -include::modules/nodes-cluster-overcommit-project-disable.adoc[leveloffset=+2] - - -[id="post-install-garbage-collection"] -== Freeing node resources using garbage collection -Understand and use garbage collection. - -include::modules/nodes-nodes-garbage-collection-containers.adoc[leveloffset=+2] -include::modules/nodes-nodes-garbage-collection-images.adoc[leveloffset=+2] -include::modules/nodes-nodes-garbage-collection-configuring.adoc[leveloffset=+2] - -[id="post-using-node-tuning-operator"] -== Using the Node Tuning Operator -Understand and use the Node Tuning Operator. - -include::modules/node-tuning-operator.adoc[leveloffset=+2] -include::modules/accessing-an-example-cluster-node-tuning-operator-specification.adoc[leveloffset=+2] -include::modules/custom-tuning-specification.adoc[leveloffset=+2] -include::modules/cluster-node-tuning-operator-default-profiles-set.adoc[leveloffset=+2] -include::modules/node-tuning-operator-supported-tuned-daemon-plug-ins.adoc[leveloffset=+2] - -include::modules/nodes-nodes-managing-max-pods-proc.adoc[leveloffset=+1] diff --git a/post_installation_configuration/preparing-for-users.adoc b/post_installation_configuration/preparing-for-users.adoc deleted file mode 100644 index e10e98fa40fb..000000000000 --- a/post_installation_configuration/preparing-for-users.adoc +++ /dev/null @@ -1,146 +0,0 @@ -:context: post-install-preparing-for-users -[id="post-install-preparing-for-users"] -= Preparing for users -include::modules/common-attributes.adoc[] - -toc::[] - -After installing {product-title}, you can further expand and customize your -cluster to your requirements, including taking steps to prepare for users. - -[id="post-install-understanding-identity-provider"] -== Understanding identity provider configuration - -The {product-title} control plane includes a built-in OAuth server. Developers and -administrators obtain OAuth access tokens to authenticate themselves to the API. - -As an administrator, you can configure OAuth to specify an identity provider -after you install your cluster. - -include::modules/identity-provider-overview.adoc[leveloffset=+2] - -[id="post-install-supported-identity-providers"] -=== Supported identity providers -// This section is sourced from authentication/understanding-identity-provider.adoc -You can configure the following types of identity providers: - -[cols="2a,8a",options="header"] -|=== - -|Identity provider -|Description - -|xref:../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#configuring-htpasswd-identity-provider[HTPasswd] -|Configure the `htpasswd` identity provider to validate user names and passwords -against a flat file generated using -link:http://httpd.apache.org/docs/2.4/programs/htpasswd.html[`htpasswd`]. - -|xref:../authentication/identity_providers/configuring-keystone-identity-provider.adoc#configuring-keystone-identity-provider[Keystone] -|Configure the `keystone` identity provider to integrate -your {product-title} cluster with Keystone to enable shared authentication with -an OpenStack Keystone v3 server configured to store users in an internal -database. - -|xref:../authentication/identity_providers/configuring-ldap-identity-provider.adoc#configuring-ldap-identity-provider[LDAP] -|Configure the `ldap` identity provider to validate user names and passwords -against an LDAPv3 server, using simple bind authentication. - -|xref:../authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc#configuring-basic-authentication-identity-provider[Basic authentication] -|Configure a `basic-authentication` identity provider for users to log in to -{product-title} with credentials validated against a remote identity provider. -Basic authentication is a generic backend integration mechanism. - -|xref:../authentication/identity_providers/configuring-request-header-identity-provider.adoc#configuring-request-header-identity-provider[Request header] -|Configure a `request-header` identity provider to identify users from request -header values, such as `X-Remote-User`. It is typically used in combination with -an authenticating proxy, which sets the request header value. - -|xref:../authentication/identity_providers/configuring-github-identity-provider.adoc#configuring-github-identity-provider[GitHub or GitHub Enterprise] -|Configure a `github` identity provider to validate user names and passwords -against GitHub or GitHub Enterprise's OAuth authentication server. - -|xref:../authentication/identity_providers/configuring-gitlab-identity-provider.adoc#configuring-gitlab-identity-provider[GitLab] -|Configure a `gitlab` identity provider to use -link:https://gitlab.com/[GitLab.com] or any other GitLab instance as an identity -provider. - -|xref:../authentication/identity_providers/configuring-google-identity-provider.adoc#configuring-google-identity-provider[Google] -|Configure a `google` identity provider using -link:https://developers.google.com/identity/protocols/OpenIDConnect[Google's OpenID Connect integration]. - -|xref:../authentication/identity_providers/configuring-oidc-identity-provider.adoc#configuring-oidc-identity-provider[OpenID Connect] -|Configure an `oidc` identity provider to integrate with an OpenID Connect -identity provider using an -link:http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[Authorization Code Flow]. - -|=== - -After you define an identity provider, you can -xref:../authentication/using-rbac.adoc#authorization-overview_using-rbac[use -RBAC to define and apply permissions]. - -include::modules/identity-provider-parameters.adoc[leveloffset=+2] - -include::modules/identity-provider-default-CR.adoc[leveloffset=+2] - -[id="post-install-using-rbac-to-define-and-apply-permissions"] -== Using RBAC to define and apply permissions -Understand and apply role-based access control. - -include::modules/rbac-overview.adoc[leveloffset=+2] - -include::modules/rbac-projects-namespaces.adoc[leveloffset=+2] - -include::modules/rbac-default-projects.adoc[leveloffset=+2] - -include::modules/rbac-viewing-cluster-roles.adoc[leveloffset=+2] - -include::modules/rbac-viewing-local-roles.adoc[leveloffset=+2] - -include::modules/rbac-adding-roles.adoc[leveloffset=+2] - -include::modules/rbac-creating-local-role.adoc[leveloffset=+2] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/rbac-creating-cluster-role.adoc[leveloffset=+2] -endif::[] - -include::modules/rbac-local-role-binding-commands.adoc[leveloffset=+2] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/rbac-cluster-role-binding-commands.adoc[leveloffset=+2] - -include::modules/rbac-creating-cluster-admin.adoc[leveloffset=+2] -endif::[] - -include::modules/authentication-kubeadmin.adoc[leveloffset=+1] - -include::modules/authentication-remove-kubeadmin.adoc[leveloffset=+2] - -[id="post-install-image-configuration-resources"] -== Image configuration resources -Understand and configure image registry settings. - -include::modules/images-configuration-parameters.adoc[leveloffset=+2] - -include::modules/images-configuration-file.adoc[leveloffset=+2] - -include::modules/images-configuration-cas.adoc[leveloffset=+3] - -include::modules/images-configuration-insecure.adoc[leveloffset=+3] - -include::modules/images-configuration-shortname.adoc[leveloffset=+3] - -include::modules/images-configuration-registry-mirror.adoc[leveloffset=+3] - -include::modules/olm-installing-operators-from-operatorhub.adoc[leveloffset=+1] -ifdef::openshift-origin[] -include::modules/olm-installing-operators-from-operatorhub-configure.adoc[leveloffset=+2] -endif::[] -include::modules/olm-installing-from-operatorhub-using-web-console.adoc[leveloffset=+2] -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/olm-installing-from-operatorhub-using-cli.adoc[leveloffset=+2] -.Additional resources - -* xref:../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-operatorgroups-about_olm-understanding-operatorgroups[About OperatorGroups] -endif::[] diff --git a/post_installation_configuration/storage-configuration.adoc b/post_installation_configuration/storage-configuration.adoc deleted file mode 100644 index 0cf7429cce6c..000000000000 --- a/post_installation_configuration/storage-configuration.adoc +++ /dev/null @@ -1,74 +0,0 @@ -:context: post-install-storage-configuration -[id="post-install-storage-configuration"] -= Post-installation storage configuration -include::modules/common-attributes.adoc[] -:gluster: GlusterFS -:gluster-native: Containerized GlusterFS -:gluster-external: External GlusterFS -:gluster-install-link: https://docs.gluster.org/en/latest/Install-Guide/Overview/ -:gluster-admin-link: https://docs.gluster.org/en/latest/Administrator%20Guide/overview/ -:gluster-role-link: https://github.com/openshift/openshift-ansible/tree/master/roles/openshift_storage_glusterfs -ifdef::openshift-enterprise,openshift-webscale[] -:gluster: Red Hat Gluster Storage -:gluster-native: converged mode -:gluster-external: independent mode -:gluster-install-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/installation_guide/ -:gluster-admin-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/administration_guide/ -:cns-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/container-native_storage_for_openshift_container_platform/ -endif::[] - -toc::[] - -After installing {product-title}, you can further expand and customize your -cluster to your requirements, including storage configuration. - -[id="post-install-dynamic-provisioning"] -== Dynamic provisioning - -include::modules/dynamic-provisioning-about.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-available-plugins.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-defining-storage-class.adoc[leveloffset=+1] - -include::modules/dynamic-provisioning-storage-class-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-annotations.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-cinder-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-aws-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-azure-disk-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-azure-file-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-azure-file-considerations.adoc[leveloffset=+3] - -include::modules/dynamic-provisioning-gce-definition.adoc[leveloffset=+2] - -// include::modules/dynamic-provisioning-gluster-definition.adoc[leveloffset=+2] - -// include::modules/dynamic-provisioning-ceph-rbd-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-vsphere-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-change-default-class.adoc[leveloffset=+1] - -[id="post-install-optimizing-storage"] -== Optimizing storage - -Optimizing storage helps to minimize storage use across all resources. By -optimizing storage, administrators help ensure that existing storage resources -are working in an efficient manner. - -include::modules/available-persistent-storage-options.adoc[leveloffset=+1] - -include::modules/recommended-configurable-storage-technology.adoc[leveloffset=+1] - -[id="post-install-deploy-OCS"] -== Deploy Red Hat OpenShift Container Storage -// This section is sourced from storage/persistent_storage/persistent-storage-ocs.adoc -Red Hat OpenShift Container Storage is a provider of agnostic persistent storage for {product-title} supporting file, block, and object storage, either in-house or in hybrid clouds. As a Red Hat storage solution, Red Hat OpenShift Container Storage is completely integrated with {product-title} for deployment, management, and monitoring. - -include::modules/deploy-red-hat-openshift-container-storage.adoc[leveloffset=+1] diff --git a/registry/accessing-the-registry.adoc b/registry/accessing-the-registry.adoc deleted file mode 100644 index 9a3e9a0b71f3..000000000000 --- a/registry/accessing-the-registry.adoc +++ /dev/null @@ -1,62 +0,0 @@ -:context: accessing-the-registry -[id="accessing-the-registry"] -= Accessing the registry -include::modules/common-attributes.adoc[] - -toc::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -Use the following sections for instructions on accessing the registry, including -viewing logs and metrics, as well as securing and exposing the registry. -endif::[] - -ifdef::openshift-dedicated[] -Use the following section for instructions on accessing the registry. -endif::[] - -You can access the registry directly to invoke `podman` commands. This allows -you to push images to or pull them from the integrated registry directly using -operations like `podman push` or `podman pull`. To do so, you must be logged in -to the registry using the `oc login` command. The operations you can perform -depend on your user permissions, as described in the following sections. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -== Prerequisites - -* You must have configured an identity provider (IDP). -* For pulling images, for example when using the `podman pull` command, -the user must have the `registry-viewer` role. To add this role: -+ -[source,terminal] ----- -$ oc policy add-role-to-user registry-viewer <user_name> ----- - -* For writing or pushing images, for example when using the `podman push` command, -the user must have the `registry-editor` role. To add this role: -+ -[source,terminal] ----- -$ oc policy add-role-to-user registry-editor <user_name> ----- -endif::[] - -include::modules/registry-accessing-directly.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/registry-checking-the-status-of-registry-pods.adoc[leveloffset=+1] - -include::modules/registry-viewing-logs.adoc[leveloffset=+1] - -include::modules/registry-accessing-metrics.adoc[leveloffset=+1] - -[id="accessing-the-registry-additional-resources"] -== Additional resources - -* For more information on allowing pods in a project to reference images in another project, see xref:../openshift_images/managing_images/using-image-pull-secrets.adoc#images-allow-pods-to-reference-images-across-projects_using-image-pull-secrets[Allowing pods to reference images across projects]. -* A `kubeadmin` can access the registry until deleted. See -xref:../authentication/remove-kubeadmin.adoc[Removing the kubeadmin user] for -more information. -* For more information on configuring an identity provider, see -xref:../authentication/understanding-identity-provider.adoc[Understanding identity provider configuration]. -endif::[] diff --git a/registry/architecture-component-imageregistry.adoc b/registry/architecture-component-imageregistry.adoc deleted file mode 100644 index 44aa90543a9f..000000000000 --- a/registry/architecture-component-imageregistry.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="architecture-component-imageregistry"] -= Image Registry -include::modules/common-attributes.adoc[] -:context: architecture-component-imageregistry - -toc::[] - -include::modules/registry-integrated-openshift-registry.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -.Additional resources - -* xref:../registry/configuring-registry-operator.adoc#configuring-registry-operator[Image Registry Operator in {product-title}] -endif::[] - -//* Link: Triggering updates on imagestream changes -//* LINK TO API DOCS diff --git a/registry/configuring-registry-operator.adoc b/registry/configuring-registry-operator.adoc deleted file mode 100644 index 56e18fba41d7..000000000000 --- a/registry/configuring-registry-operator.adoc +++ /dev/null @@ -1,67 +0,0 @@ -[id="configuring-registry-operator"] -= Image Registry Operator in {product-title} -include::modules/common-attributes.adoc[] -:context: configuring-registry-operator - -toc::[] - -[id="image-registry-on-cloud"] -== Image Registry on cloud platforms and OpenStack - -The Image Registry Operator installs a single instance of the {product-title} -registry, and manages all registry configuration, including setting up -registry storage. - -[NOTE] -==== -Storage is only automatically configured when you install an -installer-provisioned infrastructure cluster on AWS, GCP, Azure, or OpenStack. - -When you install or upgrade an installer-provisioned infrastructure cluster on AWS or Azure, the Image Registry Operator sets the `spec.storage.managementState` parameter to `Managed`. If the `spec.storage.managementState` parameter is set to `Unmanaged`, the Image Registry Operator takes no action related to storage. -==== - -After the control plane deploys, the Operator will create a default -`configs.imageregistry.operator.openshift.io` resource instance based on -configuration detected in the cluster. - -If insufficient information is available to define a complete -`configs.imageregistry.operator.openshift.io` resource, the incomplete resource -will be defined and the Operator will update the resource status with -information about what is missing. - -The Image Registry Operator runs in the `openshift-image-registry` namespace, -and manages the registry instance in that location as well. All configuration -and workload resources for the registry reside in that namespace. - - -[IMPORTANT] -==== -The Image Registry Operator's behavior for managing the pruner is orthogonal to the `managementState` specified on the `ClusterOperator` object for the Image Registry Operator. If the Image Registry Operator is not in the `Managed` state, the image pruner can still be configured and managed by the `Pruning` custom resource. - -However, the `managementState` of the Image Registry Operator alters the behavior of the deployed image pruner job: - -* `Managed`: the `--prune-registry` flag for the image pruner is set to `true`. -* `Removed`: the `--prune-registry` flag for the image pruner is set to `false`, meaning it only prunes image metatdata in etcd. -* `Unmanaged`: the `--prune-registry` flag for the image pruner is set to `false`. -==== - -[id="image-registry-on-bare-metal-vsphere"] -== Image Registry on bare metal and vSphere - -include::modules/registry-removed.adoc[leveloffset=+2] - -include::modules/registry-operator-configuration-resource-overview.adoc[leveloffset=+1] - -include::modules/registry-operator-default-crd.adoc[leveloffset=+1] - -include::modules/images-configuration-cas.adoc[leveloffset=+1] - -include::modules/registry-operator-config-resources-storage-credentials.adoc[leveloffset=+1] - -== Additional resources - -* xref:../registry/configuring_registry_storage/configuring-registry-storage-aws-user-infrastructure.adoc#configuring-registry-storage-aws-user-infrastructure[Configuring the registry for AWS user-provisioned infrastructure] -* xref:../registry/configuring_registry_storage/configuring-registry-storage-gcp-user-infrastructure.adoc#configuring-registry-storage-gcp-user-infrastructure[Configuring the registry for GCP user-provisioned infrastructure] -* xref:../registry/configuring_registry_storage/configuring-registry-storage-azure-user-infrastructure.adoc#configuring-registry-storage-azure-user-infrastructure[Configuring the registry for Azure user-provisioned infrastructure] -* xref:../registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc#configuring-registry-storage-baremetal[Configuring the registry for bare metal] -* xref:../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#configuring-registry-storage-vsphere[Configuring the registry for vSphere] diff --git a/registry/configuring_registry_storage/configuring-registry-storage-aws-user-infrastructure.adoc b/registry/configuring_registry_storage/configuring-registry-storage-aws-user-infrastructure.adoc deleted file mode 100644 index c54cc1a06338..000000000000 --- a/registry/configuring_registry_storage/configuring-registry-storage-aws-user-infrastructure.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="configuring-registry-storage-aws-user-infrastructure"] -= Configuring the registry for AWS user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: configuring-registry-storage-aws-user-infrastructure - -toc::[] - -:FILE: REGISTRY_STORAGE_S3_ACCESSKEY= - -include::modules/registry-operator-config-resources-secret-aws.adoc[leveloffset=+1] - -include::modules/registry-configuring-storage-aws-user-infra.adoc[leveloffset=+1] - -include::modules/registry-operator-configuration-resource-overview-aws-s3.adoc[leveloffset=+1] diff --git a/registry/configuring_registry_storage/configuring-registry-storage-azure-user-infrastructure.adoc b/registry/configuring_registry_storage/configuring-registry-storage-azure-user-infrastructure.adoc deleted file mode 100644 index 828c16b786a0..000000000000 --- a/registry/configuring_registry_storage/configuring-registry-storage-azure-user-infrastructure.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="configuring-registry-storage-azure-user-infrastructure"] -= Configuring the registry for Azure user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: configuring-registry-storage-azure-user-infrastructure - -toc::[] - - -include::modules/registry-operator-config-resources-secret-azure.adoc[leveloffset=+1] - -include::modules/registry-configuring-storage-azure-user-infra.adoc[leveloffset=+1] - -include::modules/registry-configuring-storage-azure-gov-cloud.adoc[leveloffset=+1] diff --git a/registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc b/registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc deleted file mode 100644 index 6d81e43c8b93..000000000000 --- a/registry/configuring_registry_storage/configuring-registry-storage-baremetal.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="configuring-registry-storage-baremetal"] -= Configuring the registry for bare metal -include::modules/common-attributes.adoc[] -:context: configuring-registry-storage-baremetal - -toc::[] - -include::modules/registry-removed.adoc[leveloffset=+1] - -include::modules/registry-change-management-state.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+1] - -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-block-recreate-rollout-bare-metal.adoc[leveloffset=+1] - - -[id="configuring-registry-storage-baremetal-addtl-resources"] -== Additional resources - -For more details about configuring registry storage for bare metal, see xref:../../scalability_and_performance/optimizing-storage.adoc#recommended-configurable-storage-technology_persistent-storage[Recommended configurable storage technology]. diff --git a/registry/configuring_registry_storage/configuring-registry-storage-gcp-user-infrastructure.adoc b/registry/configuring_registry_storage/configuring-registry-storage-gcp-user-infrastructure.adoc deleted file mode 100644 index 787814b7abc2..000000000000 --- a/registry/configuring_registry_storage/configuring-registry-storage-gcp-user-infrastructure.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="configuring-registry-storage-gcp-user-infrastructure"] -= Configuring the registry for GCP user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: configuring-registry-storage-gcp-user-infrastructure - -toc::[] - -:FILE: gcp= - -include::modules/registry-operator-config-resources-secret-gcp.adoc[leveloffset=+1] - -include::modules/registry-configuring-storage-gcp-user-infra.adoc[leveloffset=+1] - -include::modules/registry-operator-configuration-resource-overview-gcp-gcs.adoc[leveloffset=+1] diff --git a/registry/configuring_registry_storage/configuring-registry-storage-openstack-user-infrastructure.adoc b/registry/configuring_registry_storage/configuring-registry-storage-openstack-user-infrastructure.adoc deleted file mode 100644 index 12dc242c1c8a..000000000000 --- a/registry/configuring_registry_storage/configuring-registry-storage-openstack-user-infrastructure.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="configuring-registry-storage-openstack-user-infrastructure"] -= Configuring the registry for OpenStack user-provisioned infrastructure -include::modules/common-attributes.adoc[] -:context: configuring-registry-storage-openstack-user-infrastructure - -toc::[] - - -include::modules/registry-operator-config-resources-secret-openstack.adoc[leveloffset=+1] - -include::modules/registry-configuring-storage-openstack-user-infra.adoc[leveloffset=+1] - -include::modules/registry-operator-configuration-resource-overview-openstack-swift.adoc[leveloffset=+1] - - -//// -This assembly is commented out for 4.2. When OpenStack UPI GAs, we can updated the associated modules and allow this assembly to build. -//// diff --git a/registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc b/registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc deleted file mode 100644 index 853243704093..000000000000 --- a/registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="configuring-registry-storage-vsphere"] -= Configuring the registry for vSphere -include::modules/common-attributes.adoc[] -:context: configuring-registry-storage-vsphere - -toc::[] - -include::modules/registry-removed.adoc[leveloffset=+1] - -include::modules/registry-change-management-state.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-config.adoc[leveloffset=+2] - -include::modules/registry-configuring-storage-vsphere.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-non-production.adoc[leveloffset=+1] - -include::modules/installation-registry-storage-block-recreate-rollout.adoc[leveloffset=+1] - -For instructions about configuring registry storage so that it references the correct PVC, see xref:../../registry/configuring_registry_storage/configuring-registry-storage-vsphere.adoc#registry-configuring-storage-vsphere_configuring-registry-storage-vsphere[Configuring the registry for vSphere]. - -[id="configuring-registry-storage-vsphere-addtl-resources"] -== Additional resources - -For more details about configuring registry storage for vSphere, see xref:../../scalability_and_performance/optimizing-storage.adoc#recommended-configurable-storage-technology_persistent-storage[Recommended configurable storage technology]. diff --git a/registry/images b/registry/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/registry/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/registry/modules b/registry/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/registry/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/registry/registry-options.adoc b/registry/registry-options.adoc deleted file mode 100644 index 8ed178cfd257..000000000000 --- a/registry/registry-options.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="registry-options"] -= Registry options -include::modules/common-attributes.adoc[] -:context: registry-options - -toc::[] - -{product-title} can build images from your source code, deploy them, and manage -their lifecycle. To enable this, {product-title} provides an internal, -integrated container image registry that can be deployed in your {product-title} -environment to locally manage images. - -include::modules/registry-integrated-openshift-registry.adoc[leveloffset=+1] - -include::modules/registry-third-party-registries.adoc[leveloffset=+1] - -include::modules/registry-quay-overview.adoc[leveloffset=+1] - -include::modules/registry-authentication-enabled-registry-overview.adoc[leveloffset=+1] diff --git a/registry/securing-exposing-registry.adoc b/registry/securing-exposing-registry.adoc deleted file mode 100644 index 08a24a5c4aaa..000000000000 --- a/registry/securing-exposing-registry.adoc +++ /dev/null @@ -1,13 +0,0 @@ -:context: securing-exposing-registry -[id="securing-exposing-registry"] -= Exposing the registry -include::modules/common-attributes.adoc[] - -toc::[] - -By default, the {product-title} registry is secured during cluster installation -so that it serves traffic through TLS. Unlike previous versions of -{product-title}, the registry is not exposed outside of the cluster at the time -of installation. - -include::modules/registry-exposing-secure-registry-manually.adoc[leveloffset=+1] diff --git a/release_notes/48-release-notes.adoc b/release_notes/48-release-notes.adoc new file mode 100644 index 000000000000..32c740f46828 --- /dev/null +++ b/release_notes/48-release-notes.adoc @@ -0,0 +1,378 @@ +:_mod-docs-content-type: ASSEMBLY +[id="release-notes-48"] += Red{nbsp}Hat Advanced Cluster Security for Kubernetes 4.8 +include::modules/common-attributes.adoc[] +:context: release-notes-48 + +toc::[] + +{rh-rhacs-first} is an enterprise-ready, Kubernetes-native container security solution that protects your vital applications across the build, deploy, and runtime stages of the application lifecycle. +{product-title} deploys into your infrastructure and integrates with your DevOps tools and workflows. This integration provides better security and compliance, enabling DevOps and InfoSec teams to operationalize security. + +.Release dates +[options="header"] +|==== + +|{product-title-short} version |Released on + +|`4.8.0` | 9 July 2025 + +|==== + +[id="about-this-release-480_{context}"] +== About release 4.8.0 + +{product-title-short} 4.8 includes the following new features, improvements, and updates: + +Platform:: +* xref:../release_notes/48-release-notes.adoc#central-db-postgresql_15_release-notes-48[Central DB uses PostgreSQL 15] +* xref:../release_notes/48-release-notes.adoc#quay-registry-keyless-authentication_release-notes-48[Quay registry keyless authentication] +* xref:../release_notes/48-release-notes.adoc#arm-architecture-support-ga_release-notes-48[ARM architecture support is now generally available] +* xref:../release_notes/48-release-notes.adoc#view-and-customize-platform-components_release-notes-48[View and customize platform components] +* xref:../release_notes/48-release-notes.adoc#support-for-keyless-signing-verification_release-notes-48[Support for keyless signing verification] + +Compliance:: +* xref:../release_notes/48-release-notes.adoc#openshift-infrastructure-compliance-ga_release-notes-48[OpenShift Infrastructure Compliance is now generally available] + +Policy:: +* xref:../release_notes/48-release-notes.adoc#policy-as-code-ga_release-notes-48[Policy as code is now generally available] + +Vulnerability Management:: +* xref:../release_notes/48-release-notes.adoc#cve-and-rhsa-separation_release-notes-48[{product-title-short} now reports CVEs and RHSAs as separate entities] + +External integrations:: +* xref:../release_notes/48-release-notes.adoc#define-project-scope-for-google-registries_release-notes-48[Optionally define project scope when integrating with Google Registries] + +Network:: +* xref:../release_notes/48-release-notes.adoc#external-ip-visibility-ga_release-notes-48[External IP visibility is now generally available] +* xref:../release_notes/48-release-notes.adoc#build-time-network-policy-tools-enhancements_release-notes-48[Build-time network policy tool enhancements] + +[id="new-features_{context}"] +== New features + +This release adds improvements related to the following components and concepts: + +//ROX-20769 +[id="central-db-postgresql_15_{context}"] +=== Central DB uses PostgreSQL 15 + +The Central DB component now uses PostgreSQL 15, and {product-title-short} 4.8 supports this version for external databases. +A new installation with an internal database now uses this version by default. When upgrading an existing cluster to {product-title-short} 4.8, Central DB performs an upgrade of the data it has collected. + +[IMPORTANT] +==== +When preparing the upgrade to {product-title-short} 4.8, follow these +suggestions: + +* Back up the database before upgrading to {product-title-short} 4.8. +* If you are not upgrading by using the Operator, check the disk space available for the database by viewing the `rox_central_postgres_available_size_bytes` metric. +For the purposes of the upgrade, the value should be double the amount of the already-consumed disk space, as shown in the `rox_central_postgres_total_size_bytes` metric. +If the value is not correct, extend the database PVC. +* Do not interrupt the upgrade procedure. If you interrupt the upgrade, you might need to intervene manually to continue. +Depending on the amount of data, the upgrade can take extra time to finish. +==== + +For more information, see link:https://access.redhat.com/articles/7045053[{product-title-short} Support Matrix]. + +//ROX-29279 +[id="quay-registry-keyless-authentication_{context}"] +=== Quay registry keyless authentication + +You can now use keyless authentication to access the Quay registry when {product-title-short} has delegated scanning enabled for the Secured cluster. +For keyless authentication, {product-title-short} uses a Quay access token that is stored in a secret managed by the External Secrets Operator (ESO). +The ESO on the Secured cluster manages the rotation of the credential in secret, and {product-title-short} APIs can use this credential to authenticate to the Quay Image registry during image scans and check-ins in a particular namespace. + +For more information, see xref:../integration/integrate-with-image-registries.adoc#quay-keyless-eso_integrate-with-image-registries[Enabling Quay registry keyless authentication by using an external secret]. + +//ROX-28348 +[id="openshift-infrastructure-compliance-ga_{context}"] +=== {ocp} Infrastructure Compliance is now generally available + +With this release, {ocp} Infrastructure Compliance is now generally available. Use it to: + +* Easily assess compliance across your entire {ocp} Cluster Fleet. +* Ensure your {ocp} infrastructure consistently adheres to your organizational security policies. + +Additionally, this release also includes enhancement in Compliance Reporting. {product-title-short} now generates compliance reports even when some clusters encounter failures during a scheduled scan. It prevents data gaps and provides continuous visibility, ensuring that you always receive a report reflecting the compliance status of all successfully scanned clusters. + +//ROX-27659 +[id="arm-architecture-support-ga_{context}"] +=== ARM architecture support is now generally available +With this release, {product-title-short} now supports ARM architecture in Secured clusters. This update enables you to use ARM's efficient power consumption and high performance-per-watt benefits, making it ideal for resource-intensive tasks and cost-effective scaling while enhancing flexibility and performance. + +For more details, see link:https://access.redhat.com/articles/7045053[{product-title-short} Support Matrix] + +//ROX-27876 +[id="build-time-network-policy-tools-enhancements_{context}"] +=== Build-time network policy tool enhancements + +This release introduces two key enhancements to the Build-time network policy tools `roxctl netpol`: + +* **Expanded network policy visualization** - The `roxctl netpol connectivity map` command now supports visualizing Admin Network Policies (ANP) and Baseline Admin Network Policies (BANP). It gives you a more comprehensive view of your network's security posture. +* **Enhanced connectivity explainability** - A new `roxctl` explainability feature helps you pinpoint the exact resources, including network policies, ANP, and BANP, that allow or deny connectivity between any two workloads. You can use the report to verify expected connectivity outcomes and guide you in modifying resources to achieve your desired network configuration. + +For more information, see xref:../operating/build-time-network-policy-tools.adoc#build-time-network-policy-tools[Build-time network policy tools]. + +//ROX-26858 +[id="view-and-customize-platform-components_{context}"] +=== View and customize platform components + +{product-title-short} now allows you to view and modify the definition of platform components using the system menu in the user interface or through the API. Red Hat recommends updating the platform components definition if you install {ocp} Operators into non-default namespaces or if you want {product-title-short} to consider any third-party software as a "Platform component". You can focus on actionable data in the **User Workloads** tabs by customizing this definition. + +For more information, see xref:../configuration/customizing-platform-components.adoc#customizing-platform-components[Viewing and customizing platform components]. + +//ROX-27858 +[id="policy-as-code-ga_{context}"] +=== Policy as code is now generally available + +Policy as code, which enables you to manage {product-title-short} policies as Kubernetes custom resources, is now generally available. This feature supports GitOps workflows with tools like {ocp} GitOps (Argo CD). + +Key enhancements include: + +* Clusters and notifiers are addressed by name instead of by UUID. +* The system provides additional error handling. + +For more information, see xref:../operating/manage_security_policies/custom-security-policies.adoc#policy-as-code-about_custom-security-policies[Managing policies as code]. + +//ROX-23580 +[id="support-for-keyless-signing-verification_{context}"] +=== Support for keyless signing verification + +{product-title-short} 4.8 includes enhanced Sigstore integration with support for validating images signed using short-lived credentials. This enhancement uses an integration with Rekor transparency log, which records the public key or certificate used to sign the image. {product-title-short} retrieves this record to validate the signature. + +Additionally, Fulcio integrates with OIDC Identity Providers to exchange a user's identity token for a short-lived credential to sign images, which facilitates a keyless signing workflow. + +//ROX-29006 +[id="define-project-scope-for-google-registries_{context}"] +=== Optionally define project scope when integrating with Google Registries + +{product-title-short} now allows you to include multiple {ocp} projects or Kubernetes namespaces in a single Google Artifact Registry integration. For more details, see xref:../integration/integrate-with-image-registries.adoc#integrate-with-image-registries[Integrating with image registries]. + +//ROX-27696 +[id="external-ip-visibility-ga_{context}"] +=== External IP visibility is now generally available + +The external IP visibility feature is now generally available. This enhancement provides crucial insight into your cluster's external communications. You can now visualize the exact external IP addresses your deployments communicate with. This improves your ability to understand external connections, identify potential threats, and validate network policies. + +By default, this feature is disabled. However, when enabled, you see external IPs in the Network Graph. Additionally, Unauthorized Network Flow violations automatically include detailed external IP information, which streamlines your investigation process. + +For more information, see xref:../operating/visualizing-external-entities.adoc#visualizing-external-entities[Visualizing external entities]. + +//ROX-26476 +[id="cve-and-rhsa-separation_{context}"] +=== {product-title-short} now reports CVEs and RHSAs as separate entities + +Starting with {product-title-short} 4.8, the system now reports both the CVE ID (Common Vulnerabilities and Exposures) and the RHSA (Red Hat Security Advisory) when available. RHSAs might include one or more security fixes, and might also contain bug or enhancement updates. In previous versions up to {product-title-short} 4.7, {product-title-short} replaced the CVE ID with the corresponding RHSA ID once Red Hat released a fix for the associated vulnerability. + + +[id="notable-technical-changes_{context}"] +== Notable technical changes + +This release contains the following changes: + +//ROX-26577 +* Starting with {product-title-short} 4.8, Scanner V4 is the default scanner for reporting vulnerabilities in User Workloads, Platforms, and Nodes for all new installations of {product-title-short} Central and Secured Clusters. + +* {product-title-short} 4.8 preserves the current scanner configuration for existing deployments that you upgrade. If you are using the StackRox Scanner, it remains in use after the upgrade. For switching to Scanner V4, see xref:../operating/examine-images-for-vulnerabilities.adoc#enabling_scanner_v4_examine-images-for-vulnerabilities[Enabling Scanner V4]. + +* Scanner V4 runs in Central and you do not have to deploy it to secured clusters unless you have specific requirements, for example: +** Accessing image registries that are not reachable from Central. +** Using the {ocp} image registry. +** Running on {product-title-short} Cloud Service with firewall restrictions that limit registry access to internal traffic. +** Using registry mirroring. ++ +For more details, see xref:../operating/examine-images-for-vulnerabilities.adoc#accessing-delegated-image-scanning_examine-images-for-vulnerabilities[Accessing delegated image scanning]. + +* In `roxctl` CLI, certificate validation failures are now marked as errors. + +* {product-title-short} 4.8 includes the updated `roxctl` help command output making it more readable. The output is now more consistent with other command-line tools. + +* Red Hat has moved the `SecurityPolicy`` Custom Resource Definition (CRD) to the template directory within the Helm chart. This change simplifies CRD maintenance if you are using Helm, as it now automatically upgrades. ++ +[IMPORTANT] +==== +If you are using Helm to manage your {product-title-short} installation, you must apply the following changes to the `SecurityPolicy` CRD before upgrading to avoid upgrade failures: +[source,terminal] +---- +$ kubectl annotate crd/securitypolicies.config.stackrox.io meta.helm.sh/release-name=stackrox-central-services <1> +$ kubectl annotate crd/securitypolicies.config.stackrox.io meta.helm.sh/release-namespace=stackrox <2> +$ kubectl label crd/securitypolicies.config.stackrox.io app.kubernetes.io/managed-by=Helm +---- +<1> If you used a different name during your initial installation, update the `release-name` annotation to match that name. The default value is `stackrox-central-services`. +<2> If you used a different namespace during your initial installation, update the `release-namespace` annotation to match that namespace. The default value is `stackrox`. +==== + +* Sensor now ignores entries that contain invalid UTF-8 characters when reading Docker configuration pull secrets from Kubernetes. + +* The S3 integration type no longer supports Google Cloud Storage (GCS) buckets. Red Hat announced this change in RHACS 4.5.0. If you use GCS buckets for backups, you must now use the dedicated GCS integration. + +* Scoping Google image integrations by project is now optional. + +* The default output of the `roxctl image scan` command now includes three new fields when you use the `--output` option: **CVSS**, **Advisory**, and **Advisory Link**. The exact names of these fields depend on the specific output format you select. +** **CVSS** represents the CVSS score of the vulnerability. +** **Advisory** and **Advisory Link** represent the advisory related to the vulnerability, if {product-title-short} tracks it. For example, a CVE's associated Red Hat Security Advisory (RHSA), if the CVE relates to a Red Hat product. + +[id="deprecated-and-removed-features_{context}"] +== Deprecated and removed features + +Some features available in earlier releases have been deprecated or removed. + +Deprecated functionality is still included in {product-title-short} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments. +For the most recent list of major functionality deprecated and removed, see the following table. +Additional removed or deprecated functionality is available after the table. + +In the table, features are marked with the following statuses: + +* GA: General Availability +* TP: Technology Preview +* DEP: Deprecated +* REM: Removed +* NA: Not applicable + +.Deprecated and removed features tracker +[cols="4,1,1,1",options="header"] +|=== +|Feature |{product-title-short} 4.6 |{product-title-short} 4.7 |{product-title-short} 4.8 + +|API token authentication for {cloud-redhat-com}^[1]^ +|DEP +|DEP +|DEP + +|Compliance dashboard +|NA +|NA +|DEP + +|`definitions.stackrox.io` +|DEP +|DEP +|DEP + +|Google Container Registry integration^[2]^ +|DEP +|DEP +|DEP + +|Kernel support packages and driver download functionality ^[3]^ +|DEP +|DEP +|DEP + +|Reporting of Istio vulnerabilities +|DEP +|DEP +|DEP + +|StackRox Scanner +|DEP +|DEP +|DEP + +|S3 backup on GCS buckets +|DEP +|DEP +|REM + +|`/v1/clustercves/suppress` APIs^[5,6]^ +|DEP +|DEP +|DEP + +|`/v1/clustercves/unsuppress` APIs^[5,6]^ +|DEP +|DEP +|DEP + +|`/v1/nodecves/suppress` APIs^[5,6]^ +|DEP +|DEP +|DEP + +|`/v1/nodecves/unsuppress` APIs^[5,6]^ +|DEP +|DEP +|DEP + +|`/v1/summary/counts` endpoint +|DEP +|DEP +|DEP + +|Vulnerability Management (1.0) menu item^[7]^ +|DEP +|DEP +|DEP + +|Vulnerability Report Creator permission +|DEP +|DEP +|DEP + +|=== + +[.small] +-- +1. API token authentication is deprecated. The corresponding cloud source integration now uses service accounts for authentication. + +2. The Google Container Registry integration is deprecated in response to the deprecation of Container Registry. You can use the Artifact Registry as a registry replacement and Scanner V4 as a scanner replacement. ++ +For more information, see link:https://cloud.google.com/artifact-registry/docs/transition/transition-from-gcr[Transition from Container Registry] (Google Cloud documentation). + +3. Kernel support packages and driver download functionality are deprecated. + +4. The `{product-title-short}-collector-slim*` image is deprecated and has been removed in {product-title-short} 4.7.0. `{product-title-short}-collector*` image used to contain kernel modules and eBPF probes, but {product-title-short} no longer needs those items. +The `{product-title-short}-collector*` and the `{product-title-short}-collector-slim*` images are now functionally the same. + +5. A feature flag controls this API object, and you can enable or disable this API object by using the `ROX_VULN_MGMT_LEGACY_SNOOZE` environment variable. + +6. The format for specifying duration in JSON requests to `v1/nodecves/suppress`, `v1/clustercves/suppress`, and `v1/imagecves/suppress` has been changed to the ProtoJSON format. +Only a numeric value representing seconds with optional fractional seconds for nanosecond precision and followed by the `s` suffix is supported. ++ +For example, `0.300s`, `-5400s`, or `9900s`. The previously valid time units of `ns`, `us`, `µs`, `ms`, `m`, and `h` are no longer supported. + +7. The *Vulnerability Management* -> *Dashboard* view is deprecated and is planned to be removed in a future release. You can use the *User workload vulnerabilities*, *Exception management*, *Platform vulnerabilities*, and *Node CVEs* views as alternatives. + +-- + +[id="bug-fixes_{context}"] +== Bug fixes in version 4.8.0 + +*Release date*: 9 July 2025 + +* Previously, if messages contained non-UTF-8 characters, the Secured Cluster sensor would remain uninitialized and offline. +It prevented proper monitoring of affected clusters. With this release, the Sensor now handles non-UTF-8 characters in user-provided data. +As a result, the Secured Cluster sensor no longer fails to initialize due to these characters and correctly monitors all clusters. + +* Previously, warning messages in sensor pod logs incorrectly indicated that images were *Not Pullable* because the system attempted to determine pullability even when the image ID was empty. +As a consequence, images were skipped from workload CVE scans. +RHACS 4.8 correctly scans the images for vulnerabilities. + +* Fixed an issue where signing images multiple times with different keys led to failed image signature verification. + +* Previously, sometimes RHACS did not correctly initialize the Scanner V4 integration with default indexer and matcher endpoints, which caused scanner pods to fail and prevented images from being scanned. +With this update, RHACS correctly initializes the Scanner V4 integration, scans the images, and creates vulnerability reports as expected. + +* Previously, creating a security policy with a cluster scope using the cluster's name would cause the UI to crash upon viewing the policy. +It was due to the system's inability to resolve the cluster name to its corresponding ID correctly. +This update enables proper resolution of cluster names to IDs in security policies. +As a result, you can now view policies with cluster scope in the UI without encountering errors. + +* Previously, the Scanner V4 failed to identify some critical CVEs in Java workloads because an `unidentified jar` error caused the scanner to skip valid JAR files during the scanning process. +As a consequence, RHACS did not detect these vulnerabilities in the scan results. +This update eliminates the `unidentified jar" error, enabling the scanner to process JAR files properly. +As a result, the Scanner V4 now accurately identifies critical CVEs in Java workloads, providing comprehensive vulnerability scanning. + +* Previously, the **Cancel** button on the delegated scanning page provided no visual feedback if you made no changes, leading to confusion about its functionality. +This lack of feedback occurred because the button only reset the form for unpersisted changes. +This update introduces an **Edit** button to initiate editing, making the **Save** and **Cancel** buttons visible and enabled only when you make changes. + +[id="upcoming-changes_49"] +== Upcoming admission controller enforcement changes in version 4.9.0 + +{product-title-short} 4.9 streamlines the admission controller configuration by consolidating the existing `listen` and `enforce` settings into a single **Enforcement** option. You can select the following settings for the **Enforcement** option for create, update, and scale events: + +* `Yes` to enable enforcement for events. +* `No` to disable enforcement for events. + +include::modules/image-versions.adoc[leveloffset=+1] diff --git a/release_notes/README.adoc b/release_notes/README.adoc deleted file mode 100644 index 6d0c17ac9836..000000000000 --- a/release_notes/README.adoc +++ /dev/null @@ -1,4 +0,0 @@ -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release notes should be added/edited in their own PR. diff --git a/release_notes/images b/release_notes/images index e4c5bd02a10a..5e67573196d8 120000 --- a/release_notes/images +++ b/release_notes/images @@ -1 +1 @@ -../images/ \ No newline at end of file +../images \ No newline at end of file diff --git a/release_notes/modules b/release_notes/modules index 43aab75b53c9..464b823aca16 120000 --- a/release_notes/modules +++ b/release_notes/modules @@ -1 +1 @@ -../modules/ \ No newline at end of file +../modules \ No newline at end of file diff --git a/release_notes/ocp-4-1-release-notes.adoc b/release_notes/ocp-4-1-release-notes.adoc deleted file mode 100644 index 555519871ebb..000000000000 --- a/release_notes/ocp-4-1-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-1-release-notes"] -= {product-title} 4.1 release notes -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. diff --git a/release_notes/ocp-4-2-release-notes.adoc b/release_notes/ocp-4-2-release-notes.adoc deleted file mode 100644 index 130dd968d9fc..000000000000 --- a/release_notes/ocp-4-2-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-2-release-notes"] -= {product-title} {product-version} release notes -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. diff --git a/release_notes/ocp-4-3-release-notes.adoc b/release_notes/ocp-4-3-release-notes.adoc deleted file mode 100644 index 4c1fdda4da19..000000000000 --- a/release_notes/ocp-4-3-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-3-release-notes"] -= {product-title} {product-version} release notes -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. diff --git a/release_notes/ocp-4-4-release-notes.adoc b/release_notes/ocp-4-4-release-notes.adoc deleted file mode 100644 index 0c21e7c0c5a2..000000000000 --- a/release_notes/ocp-4-4-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-4-release-notes"] -= {product-title} {product-version} release notes -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. diff --git a/release_notes/ocp-4-5-release-notes.adoc b/release_notes/ocp-4-5-release-notes.adoc deleted file mode 100644 index c0da805190f5..000000000000 --- a/release_notes/ocp-4-5-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-5-release-notes"] -= {product-title} {product-version} release notes -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. diff --git a/release_notes/ocp-4-6-release-notes.adoc b/release_notes/ocp-4-6-release-notes.adoc deleted file mode 100644 index a74d29511953..000000000000 --- a/release_notes/ocp-4-6-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-6-release-notes"] -= {product-title} {product-version} release notes -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. diff --git a/release_notes/ocp-4-7-release-notes.adoc b/release_notes/ocp-4-7-release-notes.adoc deleted file mode 100644 index b42e396ef021..000000000000 --- a/release_notes/ocp-4-7-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-7-release-notes"] -= {product-title} {product-version} release notes -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. \ No newline at end of file diff --git a/release_notes/ocp-4-8-release-notes.adoc b/release_notes/ocp-4-8-release-notes.adoc deleted file mode 100644 index c9bb402adbdb..000000000000 --- a/release_notes/ocp-4-8-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-8-release-notes"] -= {product-title} {product-version} release notes -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. diff --git a/release_notes/snippets b/release_notes/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/release_notes/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/release_notes/versioning-policy.adoc b/release_notes/versioning-policy.adoc deleted file mode 100644 index c247c288f931..000000000000 --- a/release_notes/versioning-policy.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="ocp-4-2-versioning-policy"] -= {product-title} Versioning Policy -include::modules/common-attributes.adoc[] -:context: release-notes - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -Release note changes should be added/edited in their own PR. - -This file is here to allow builds to work. diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000000..c6b8442d7b76 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +./aura.tar.gz +lxml~=4.9.1 +pyyaml~=6.0 +requests~=2.27.1 diff --git a/rest_api/APITokenService/APITokenService.adoc b/rest_api/APITokenService/APITokenService.adoc new file mode 100644 index 000000000000..0320af3e2cce --- /dev/null +++ b/rest_api/APITokenService/APITokenService.adoc @@ -0,0 +1,256 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="APITokenService"] += A P I Token Service +:toc: macro +:toc-title: + +toc::[] + +:context: APITokenService + +[id="GenerateToken_APITokenService"] +== GenerateToken + +`POST /v1/apitokens/generate` + +GenerateToken generates API token for a given user and role. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GenerateTokenRequest_CommonObjectReference[V1GenerateTokenRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GenerateTokenResponse_CommonObjectReference[V1GenerateTokenResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GenerateTokenResponse_CommonObjectReference[V1GenerateTokenResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAPIToken_APITokenService"] +== GetAPIToken + +`GET /v1/apitokens/{id}` + +GetAPIToken returns API token metadata for a given id. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageTokenMetadata_CommonObjectReference[StorageTokenMetadata] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageTokenMetadata_CommonObjectReference[StorageTokenMetadata] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAPITokens_APITokenService"] +== GetAPITokens + +`GET /v1/apitokens` + +GetAPITokens returns all the API tokens. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| revoked +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAPITokensResponse_CommonObjectReference[V1GetAPITokensResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAPITokensResponse_CommonObjectReference[V1GetAPITokensResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListAllowedTokenRoles_APITokenService"] +== ListAllowedTokenRoles + +`GET /v1/apitokens/generate/allowed-roles` + +GetAllowedTokenRoles return roles that user is allowed to request for API token. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListAllowedTokenRolesResponse_CommonObjectReference[V1ListAllowedTokenRolesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListAllowedTokenRolesResponse_CommonObjectReference[V1ListAllowedTokenRolesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="RevokeToken_APITokenService"] +== RevokeToken + +`PATCH /v1/apitokens/revoke/{id}` + +RevokeToken removes the API token for a given id. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/AdministrationEventService/AdministrationEventService.adoc b/rest_api/AdministrationEventService/AdministrationEventService.adoc new file mode 100644 index 000000000000..9bd24736b4b4 --- /dev/null +++ b/rest_api/AdministrationEventService/AdministrationEventService.adoc @@ -0,0 +1,262 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="AdministrationEventService"] += Administration Event Service +:toc: macro +:toc-title: + +toc::[] + +:context: AdministrationEventService + +[id="CountAdministrationEvents_AdministrationEventService"] +== CountAdministrationEvents + +`GET /v1/count/administration/events` + +CountAdministrationEvents returns the number of events after filtering by requested fields. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| filter.from +| Matches events with last_occurred_at after a specific timestamp, i.e. the lower boundary. +| - +| null +| + +| filter.until +| Matches events with last_occurred_at before a specific timestamp, i.e. the upper boundary. +| - +| null +| + +| filter.domain +| Matches events from a specific domain. `String` +| - +| null +| + +| filter.resourceType +| Matches events associated with a specific resource type. `String` +| - +| null +| + +| filter.type +| Matches events based on their type. `String` +| - +| null +| + +| filter.level +| Matches events based on their level. `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountAdministrationEventsResponse_CommonObjectReference[V1CountAdministrationEventsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountAdministrationEventsResponse_CommonObjectReference[V1CountAdministrationEventsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAdministrationEvent_AdministrationEventService"] +== GetAdministrationEvent + +`GET /v1/administration/events/{id}` + +GetAdministrationEvent retrieves an event by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAdministrationEventResponse_CommonObjectReference[V1GetAdministrationEventResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAdministrationEventResponse_CommonObjectReference[V1GetAdministrationEventResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListAdministrationEvents_AdministrationEventService"] +== ListAdministrationEvents + +`GET /v1/administration/events` + +ListAdministrationEvents returns the list of events after filtered by requested fields. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +| filter.from +| Matches events with last_occurred_at after a specific timestamp, i.e. the lower boundary. +| - +| null +| + +| filter.until +| Matches events with last_occurred_at before a specific timestamp, i.e. the upper boundary. +| - +| null +| + +| filter.domain +| Matches events from a specific domain. `String` +| - +| null +| + +| filter.resourceType +| Matches events associated with a specific resource type. `String` +| - +| null +| + +| filter.type +| Matches events based on their type. `String` +| - +| null +| + +| filter.level +| Matches events based on their level. `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListAdministrationEventsResponse_CommonObjectReference[V1ListAdministrationEventsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListAdministrationEventsResponse_CommonObjectReference[V1ListAdministrationEventsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/AdministrationUsageService/AdministrationUsageService.adoc b/rest_api/AdministrationUsageService/AdministrationUsageService.adoc new file mode 100644 index 000000000000..92963e4d862f --- /dev/null +++ b/rest_api/AdministrationUsageService/AdministrationUsageService.adoc @@ -0,0 +1,110 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="AdministrationUsageService"] += Administration Usage Service +:toc: macro +:toc-title: + +toc::[] + +:context: AdministrationUsageService + +[id="GetCurrentSecuredUnitsUsage_AdministrationUsageService"] +== GetCurrentSecuredUnitsUsage + +`GET /v1/administration/usage/secured-units/current` + +GetCurrentSecuredUnitsUsage returns the current secured units usage metrics values. + +=== Description + +The secured units metrics are collected from all connected clusters every 5 minutes, so the returned result includes data for the connected clusters accurate to about these 5 minutes, and potentially some outdated data for the disconnected clusters. + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1SecuredUnitsUsageResponse_CommonObjectReference[V1SecuredUnitsUsageResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1SecuredUnitsUsageResponse_CommonObjectReference[V1SecuredUnitsUsageResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetMaxSecuredUnitsUsage_AdministrationUsageService"] +== GetMaxSecuredUnitsUsage + +`GET /v1/administration/usage/secured-units/max` + +GetMaxSecuredUnitsUsage returns the maximum, i.e. peak, secured units usage observed during a given time range, together with the time when this maximum was aggregated and stored. + +=== Description + +The usage metrics are continuously collected from all the connected clusters. The maximum values are kept for some period of time in memory, and then, periodically, are stored to the database. The last data from disconnected clusters are taken into account. + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| from +| +| - +| null +| + +| to +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1MaxSecuredUnitsUsageResponse_CommonObjectReference[V1MaxSecuredUnitsUsageResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1MaxSecuredUnitsUsageResponse_CommonObjectReference[V1MaxSecuredUnitsUsageResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/AlertService/AlertService.adoc b/rest_api/AlertService/AlertService.adoc new file mode 100644 index 000000000000..f5f7cf7a2de9 --- /dev/null +++ b/rest_api/AlertService/AlertService.adoc @@ -0,0 +1,718 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="AlertService"] += Alert Service +:toc: macro +:toc-title: + +toc::[] + +:context: AlertService + +[id="CountAlerts_AlertService"] +== CountAlerts + +`GET /v1/alertscount` + +CountAlerts counts how many alerts match the get request. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountAlertsResponse_CommonObjectReference[V1CountAlertsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountAlertsResponse_CommonObjectReference[V1CountAlertsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteAlerts_AlertService"] +== DeleteAlerts + +`DELETE /v1/alerts` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +| confirm +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeleteAlertsResponse_CommonObjectReference[V1DeleteAlertsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeleteAlertsResponse_CommonObjectReference[V1DeleteAlertsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAlert_AlertService"] +== GetAlert + +`GET /v1/alerts/{id}` + +GetAlert returns the alert given its id. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAlert_CommonObjectReference[StorageAlert] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAlert_CommonObjectReference[StorageAlert] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAlertTimeseries_AlertService"] +== GetAlertTimeseries + +`GET /v1/alerts/summary/timeseries` + +GetAlertTimeseries returns the alerts sorted by time. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAlertTimeseriesResponse_CommonObjectReference[V1GetAlertTimeseriesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAlertTimeseriesResponse_CommonObjectReference[V1GetAlertTimeseriesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAlertsCounts_AlertService"] +== GetAlertsCounts + +`GET /v1/alerts/summary/counts` + +GetAlertsCounts returns the number of alerts in the requested cluster or category. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| request.query +| +| - +| null +| + +| request.pagination.limit +| +| - +| null +| + +| request.pagination.offset +| +| - +| null +| + +| request.pagination.sortOption.field +| +| - +| null +| + +| request.pagination.sortOption.reversed +| +| - +| null +| + +| request.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| request.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +| groupBy +| +| - +| UNSET +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAlertsCountsResponse_CommonObjectReference[V1GetAlertsCountsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAlertsCountsResponse_CommonObjectReference[V1GetAlertsCountsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAlertsGroup_AlertService"] +== GetAlertsGroup + +`GET /v1/alerts/summary/groups` + +GetAlertsGroup returns alerts grouped by policy. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAlertsGroupResponse_CommonObjectReference[V1GetAlertsGroupResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAlertsGroupResponse_CommonObjectReference[V1GetAlertsGroupResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListAlerts_AlertService"] +== ListAlerts + +`GET /v1/alerts` + +List returns the slim list version of the alerts. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListAlertsResponse_CommonObjectReference[V1ListAlertsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListAlertsResponse_CommonObjectReference[V1ListAlertsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ResolveAlert_AlertService"] +== ResolveAlert + +`PATCH /v1/alerts/{id}/resolve` + +ResolveAlert marks the given alert (by ID) as resolved. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#AlertServiceResolveAlertBody_CommonObjectReference[AlertServiceResolveAlertBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ResolveAlerts_AlertService"] +== ResolveAlerts + +`PATCH /v1/alerts/resolve` + +ResolveAlertsByQuery marks alerts matching search query as resolved. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ResolveAlertsRequest_CommonObjectReference[V1ResolveAlertsRequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/AuthProviderService/AuthProviderService.adoc b/rest_api/AuthProviderService/AuthProviderService.adoc new file mode 100644 index 000000000000..b4f3576e33d7 --- /dev/null +++ b/rest_api/AuthProviderService/AuthProviderService.adoc @@ -0,0 +1,480 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="AuthProviderService"] += Auth Provider Service +:toc: macro +:toc-title: + +toc::[] + +:context: AuthProviderService + +[id="DeleteAuthProvider_AuthProviderService"] +== DeleteAuthProvider + +`DELETE /v1/authProviders/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| force +| +| - +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ExchangeToken_AuthProviderService"] +== ExchangeToken + +`POST /v1/authProviders/exchangeToken` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ExchangeTokenRequest_CommonObjectReference[V1ExchangeTokenRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ExchangeTokenResponse_CommonObjectReference[V1ExchangeTokenResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ExchangeTokenResponse_CommonObjectReference[V1ExchangeTokenResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAuthProvider_AuthProviderService"] +== GetAuthProvider + +`GET /v1/authProviders/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAuthProviders_AuthProviderService"] +== GetAuthProviders + +`GET /v1/authProviders` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| name +| +| - +| null +| + +| type +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAuthProvidersResponse_CommonObjectReference[V1GetAuthProvidersResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAuthProvidersResponse_CommonObjectReference[V1GetAuthProvidersResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetLoginAuthProviders_AuthProviderService"] +== GetLoginAuthProviders + +`GET /v1/login/authproviders` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetLoginAuthProvidersResponse_CommonObjectReference[V1GetLoginAuthProvidersResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetLoginAuthProvidersResponse_CommonObjectReference[V1GetLoginAuthProvidersResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListAvailableProviderTypes_AuthProviderService"] +== ListAvailableProviderTypes + +`GET /v1/availableAuthProviders` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1AvailableProviderTypesResponse_CommonObjectReference[V1AvailableProviderTypesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1AvailableProviderTypesResponse_CommonObjectReference[V1AvailableProviderTypesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostAuthProvider_AuthProviderService"] +== PostAuthProvider + +`POST /v1/authProviders` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| provider +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutAuthProvider_AuthProviderService"] +== PutAuthProvider + +`PUT /v1/authProviders/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#AuthProviderServicePutAuthProviderBody_CommonObjectReference[AuthProviderServicePutAuthProviderBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateAuthProvider_AuthProviderService"] +== UpdateAuthProvider + +`PATCH /v1/authProviders/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#AuthProviderServiceUpdateAuthProviderBody_CommonObjectReference[AuthProviderServiceUpdateAuthProviderBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageAuthProvider_CommonObjectReference[StorageAuthProvider] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/AuthService/AuthService.adoc b/rest_api/AuthService/AuthService.adoc new file mode 100644 index 000000000000..a8d0dab39cc2 --- /dev/null +++ b/rest_api/AuthService/AuthService.adoc @@ -0,0 +1,360 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="AuthService"] += Auth Service +:toc: macro +:toc-title: + +toc::[] + +:context: AuthService + +[id="AddAuthMachineToMachineConfig_AuthService"] +== AddAuthMachineToMachineConfig + +`POST /v1/auth/m2m` + +AddAuthMachineToMachineConfig creates a new auth machine to machine config. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1AddAuthMachineToMachineConfigRequest_CommonObjectReference[V1AddAuthMachineToMachineConfigRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1AddAuthMachineToMachineConfigResponse_CommonObjectReference[V1AddAuthMachineToMachineConfigResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1AddAuthMachineToMachineConfigResponse_CommonObjectReference[V1AddAuthMachineToMachineConfigResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteAuthMachineToMachineConfig_AuthService"] +== DeleteAuthMachineToMachineConfig + +`DELETE /v1/auth/m2m/{id}` + +DeleteAuthMachineToMachineConfig deletes the specific auth machine to machine config. In case a specified auth machine to machine config does not exist is deleted, no error will be returned. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ExchangeAuthMachineToMachineToken_AuthService"] +== ExchangeAuthMachineToMachineToken + +`POST /v1/auth/m2m/exchange` + +ExchangeAuthMachineToMachineToken exchanges a given identity token for a Central access token based on configured auth machine to machine configs. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ExchangeAuthMachineToMachineTokenRequest_CommonObjectReference[V1ExchangeAuthMachineToMachineTokenRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ExchangeAuthMachineToMachineTokenResponse_CommonObjectReference[V1ExchangeAuthMachineToMachineTokenResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ExchangeAuthMachineToMachineTokenResponse_CommonObjectReference[V1ExchangeAuthMachineToMachineTokenResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAuthMachineToMachineConfig_AuthService"] +== GetAuthMachineToMachineConfig + +`GET /v1/auth/m2m/{id}` + +GetAuthMachineToMachineConfig retrieves the specific auth machine to machine config. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAuthMachineToMachineConfigResponse_CommonObjectReference[V1GetAuthMachineToMachineConfigResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAuthMachineToMachineConfigResponse_CommonObjectReference[V1GetAuthMachineToMachineConfigResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAuthStatus_AuthService"] +== GetAuthStatus + +`GET /v1/auth/status` + +GetAuthStatus returns the status for the current client. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1AuthStatus_CommonObjectReference[V1AuthStatus] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1AuthStatus_CommonObjectReference[V1AuthStatus] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListAuthMachineToMachineConfigs_AuthService"] +== ListAuthMachineToMachineConfigs + +`GET /v1/auth/m2m` + +ListAuthMachineToMachineConfigs lists the available auth machine to machine configs. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListAuthMachineToMachineConfigResponse_CommonObjectReference[V1ListAuthMachineToMachineConfigResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListAuthMachineToMachineConfigResponse_CommonObjectReference[V1ListAuthMachineToMachineConfigResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateAuthMachineToMachineConfig_AuthService"] +== UpdateAuthMachineToMachineConfig + +`PUT /v1/auth/m2m/{config.id}` + +UpdateAuthMachineToMachineConfig updates an existing auth machine to machine config. In case the auth machine to machine config does not exist, a new one will be created. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| config.id +| UUID of the config. Note that when adding a machine to machine config, this field should not be set. +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#AuthServiceUpdateAuthMachineToMachineConfigBody_CommonObjectReference[AuthServiceUpdateAuthMachineToMachineConfigBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/CentralHealthService/CentralHealthService.adoc b/rest_api/CentralHealthService/CentralHealthService.adoc new file mode 100644 index 000000000000..154eb7579bb8 --- /dev/null +++ b/rest_api/CentralHealthService/CentralHealthService.adoc @@ -0,0 +1,46 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="CentralHealthService"] += Central Health Service +:toc: macro +:toc-title: + +toc::[] + +:context: CentralHealthService + +[id="GetUpgradeStatus_CentralHealthService"] +== GetUpgradeStatus + +`GET /v1/centralhealth/upgradestatus` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUpgradeStatusResponse_CommonObjectReference[V1GetUpgradeStatusResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUpgradeStatusResponse_CommonObjectReference[V1GetUpgradeStatusResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/CloudSourcesService/CloudSourcesService.adoc b/rest_api/CloudSourcesService/CloudSourcesService.adoc new file mode 100644 index 000000000000..d7bed7561935 --- /dev/null +++ b/rest_api/CloudSourcesService/CloudSourcesService.adoc @@ -0,0 +1,436 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="CloudSourcesService"] += Cloud Sources Service +:toc: macro +:toc-title: + +toc::[] + +:context: CloudSourcesService + +[id="CountCloudSources_CloudSourcesService"] +== CountCloudSources + +`GET /v1/count/cloud-sources` + +CountCloudSources returns the number of cloud sources after filtering by requested fields. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| filter.names +| Matches cloud sources based on their name. `String` +| - +| null +| + +| filter.types +| Matches cloud sources based on their type. `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountCloudSourcesResponse_CommonObjectReference[V1CountCloudSourcesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountCloudSourcesResponse_CommonObjectReference[V1CountCloudSourcesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="CreateCloudSource_CloudSourcesService"] +== CreateCloudSource + +`POST /v1/cloud-sources` + +CreateCloudSource creates a cloud source. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateCloudSourceRequest_CommonObjectReference[V1CreateCloudSourceRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateCloudSourceResponse_CommonObjectReference[V1CreateCloudSourceResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateCloudSourceResponse_CommonObjectReference[V1CreateCloudSourceResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteCloudSource_CloudSourcesService"] +== DeleteCloudSource + +`DELETE /v1/cloud-sources/{id}` + +DeleteCloudSource removes a cloud source. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetCloudSource_CloudSourcesService"] +== GetCloudSource + +`GET /v1/cloud-sources/{id}` + +GetCloudSource retrieves a cloud source by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCloudSourceResponse_CommonObjectReference[V1GetCloudSourceResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCloudSourceResponse_CommonObjectReference[V1GetCloudSourceResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListCloudSources_CloudSourcesService"] +== ListCloudSources + +`GET /v1/cloud-sources` + +ListCloudSources returns the list of cloud sources after filtered by requested fields. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +| filter.names +| Matches cloud sources based on their name. `String` +| - +| null +| + +| filter.types +| Matches cloud sources based on their type. `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListCloudSourcesResponse_CommonObjectReference[V1ListCloudSourcesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListCloudSourcesResponse_CommonObjectReference[V1ListCloudSourcesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TestCloudSource_CloudSourcesService"] +== TestCloudSource + +`POST /v1/cloud-sources/test` + +TestCloudSource tests a cloud source. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1TestCloudSourceRequest_CommonObjectReference[V1TestCloudSourceRequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateCloudSource_CloudSourcesService"] +== UpdateCloudSource + +`PUT /v1/cloud-sources/{cloudSource.id}` + +UpdateCloudSource creates or replaces a cloud source. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| cloudSource.id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#CloudSourcesServiceUpdateCloudSourceBody_CommonObjectReference[CloudSourcesServiceUpdateCloudSourceBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ClusterCVEService/ClusterCVEService.adoc b/rest_api/ClusterCVEService/ClusterCVEService.adoc new file mode 100644 index 000000000000..320c8d468ede --- /dev/null +++ b/rest_api/ClusterCVEService/ClusterCVEService.adoc @@ -0,0 +1,114 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ClusterCVEService"] += Cluster C V E Service +:toc: macro +:toc-title: + +toc::[] + +:context: ClusterCVEService + +[id="SuppressCVEs_ClusterCVEService"] +== SuppressCVEs + +`PATCH /v1/clustercves/suppress` + +SuppressCVE suppresses cluster cves. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1SuppressCVERequest_CommonObjectReference[V1SuppressCVERequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UnsuppressCVEs_ClusterCVEService"] +== UnsuppressCVEs + +`PATCH /v1/clustercves/unsuppress` + +UnsuppressCVE unsuppresses cluster cves. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UnsuppressCVERequest_CommonObjectReference[V1UnsuppressCVERequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ClusterInitService/ClusterInitService.adoc b/rest_api/ClusterInitService/ClusterInitService.adoc new file mode 100644 index 000000000000..9175cb5c5c35 --- /dev/null +++ b/rest_api/ClusterInitService/ClusterInitService.adoc @@ -0,0 +1,322 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ClusterInitService"] += Cluster Init Service +:toc: macro +:toc-title: + +toc::[] + +:context: ClusterInitService + +[id="GenerateCRS_ClusterInitService"] +== GenerateCRS + +`POST /v1/cluster-init/crs` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CRSGenRequest_CommonObjectReference[V1CRSGenRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CRSGenResponse_CommonObjectReference[V1CRSGenResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CRSGenResponse_CommonObjectReference[V1CRSGenResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GenerateInitBundle_ClusterInitService"] +== GenerateInitBundle + +`POST /v1/cluster-init/init-bundles` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1InitBundleGenRequest_CommonObjectReference[V1InitBundleGenRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1InitBundleGenResponse_CommonObjectReference[V1InitBundleGenResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1InitBundleGenResponse_CommonObjectReference[V1InitBundleGenResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetCAConfig_ClusterInitService"] +== GetCAConfig + +`GET /v1/cluster-init/ca-config` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCAConfigResponse_CommonObjectReference[V1GetCAConfigResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCAConfigResponse_CommonObjectReference[V1GetCAConfigResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetCRSs_ClusterInitService"] +== GetCRSs + +`GET /v1/cluster-init/crs` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CRSMetasResponse_CommonObjectReference[V1CRSMetasResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CRSMetasResponse_CommonObjectReference[V1CRSMetasResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetInitBundles_ClusterInitService"] +== GetInitBundles + +`GET /v1/cluster-init/init-bundles` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1InitBundleMetasResponse_CommonObjectReference[V1InitBundleMetasResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1InitBundleMetasResponse_CommonObjectReference[V1InitBundleMetasResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="RevokeCRS_ClusterInitService"] +== RevokeCRS + +`PATCH /v1/cluster-init/crs/revoke` + +RevokeCRSBundle deletes cluster registration secrets. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CRSRevokeRequest_CommonObjectReference[V1CRSRevokeRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CRSRevokeResponse_CommonObjectReference[V1CRSRevokeResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CRSRevokeResponse_CommonObjectReference[V1CRSRevokeResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="RevokeInitBundle_ClusterInitService"] +== RevokeInitBundle + +`PATCH /v1/cluster-init/init-bundles/revoke` + +RevokeInitBundle deletes cluster init bundle. If this operation impacts any cluster then its ID should be included in request. If confirm_impacted_clusters_ids does not match with current impacted clusters then request will fail with error that includes all impacted clusters. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1InitBundleRevokeRequest_CommonObjectReference[V1InitBundleRevokeRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1InitBundleRevokeResponse_CommonObjectReference[V1InitBundleRevokeResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1InitBundleRevokeResponse_CommonObjectReference[V1InitBundleRevokeResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ClustersService/ClustersService.adoc b/rest_api/ClustersService/ClustersService.adoc new file mode 100644 index 000000000000..ff6aa20037b9 --- /dev/null +++ b/rest_api/ClustersService/ClustersService.adoc @@ -0,0 +1,348 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ClustersService"] += Clusters Service +:toc: macro +:toc-title: + +toc::[] + +:context: ClustersService + +[id="DeleteCluster_ClustersService"] +== DeleteCluster + +`DELETE /v1/clusters/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetCluster_ClustersService"] +== GetCluster + +`GET /v1/clusters/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClusterResponse_CommonObjectReference[V1ClusterResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClusterResponse_CommonObjectReference[V1ClusterResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetClusterDefaultValues_ClustersService"] +== GetClusterDefaultValues + +`GET /v1/cluster-defaults` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClusterDefaultsResponse_CommonObjectReference[V1ClusterDefaultsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClusterDefaultsResponse_CommonObjectReference[V1ClusterDefaultsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetClusters_ClustersService"] +== GetClusters + +`GET /v1/clusters` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClustersList_CommonObjectReference[V1ClustersList] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClustersList_CommonObjectReference[V1ClustersList] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetKernelSupportAvailable_ClustersService"] +== GetKernelSupportAvailable + +`GET /v1/clusters-env/kernel-support-available` + +GetKernelSupportAvailable is deprecated in favor of GetClusterDefaultValues. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1KernelSupportAvailableResponse_CommonObjectReference[V1KernelSupportAvailableResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1KernelSupportAvailableResponse_CommonObjectReference[V1KernelSupportAvailableResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostCluster_ClustersService"] +== PostCluster + +`POST /v1/clusters` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageCluster_CommonObjectReference[StorageCluster] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClusterResponse_CommonObjectReference[V1ClusterResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClusterResponse_CommonObjectReference[V1ClusterResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutCluster_ClustersService"] +== PutCluster + +`PUT /v1/clusters/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ClustersServicePutClusterBody_CommonObjectReference[ClustersServicePutClusterBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClusterResponse_CommonObjectReference[V1ClusterResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ClusterResponse_CommonObjectReference[V1ClusterResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/CollectionService/CollectionService.adoc b/rest_api/CollectionService/CollectionService.adoc new file mode 100644 index 000000000000..35fa2f9c0fc0 --- /dev/null +++ b/rest_api/CollectionService/CollectionService.adoc @@ -0,0 +1,538 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="CollectionService"] += Collection Service +:toc: macro +:toc-title: + +toc::[] + +:context: CollectionService + +[id="CreateCollection_CollectionService"] +== CreateCollection + +`POST /v1/collections` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateCollectionRequest_CommonObjectReference[V1CreateCollectionRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateCollectionResponse_CommonObjectReference[V1CreateCollectionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateCollectionResponse_CommonObjectReference[V1CreateCollectionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteCollection_CollectionService"] +== DeleteCollection + +`DELETE /v1/collections/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DryRunCollection_CollectionService"] +== DryRunCollection + +`POST /v1/collections/dryrun` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DryRunCollectionRequest_CommonObjectReference[V1DryRunCollectionRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DryRunCollectionResponse_CommonObjectReference[V1DryRunCollectionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DryRunCollectionResponse_CommonObjectReference[V1DryRunCollectionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetCollection_CollectionService"] +== GetCollection + +`GET /v1/collections/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| options.withMatches +| +| - +| null +| + +| options.filterQuery.query +| +| - +| null +| + +| options.filterQuery.pagination.limit +| +| - +| null +| + +| options.filterQuery.pagination.offset +| +| - +| null +| + +| options.filterQuery.pagination.sortOption.field +| +| - +| null +| + +| options.filterQuery.pagination.sortOption.reversed +| +| - +| null +| + +| options.filterQuery.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| options.filterQuery.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCollectionResponse_CommonObjectReference[V1GetCollectionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCollectionResponse_CommonObjectReference[V1GetCollectionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetCollectionCount_CollectionService"] +== GetCollectionCount + +`GET /v1/collectionscount` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCollectionCountResponse_CommonObjectReference[V1GetCollectionCountResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCollectionCountResponse_CommonObjectReference[V1GetCollectionCountResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListCollectionSelectors_CollectionService"] +== ListCollectionSelectors + +`GET /v1/collections/selectors` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListCollectionSelectorsResponse_CommonObjectReference[V1ListCollectionSelectorsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListCollectionSelectorsResponse_CommonObjectReference[V1ListCollectionSelectorsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListCollections_CollectionService"] +== ListCollections + +`GET /v1/collections` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListCollectionsResponse_CommonObjectReference[V1ListCollectionsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListCollectionsResponse_CommonObjectReference[V1ListCollectionsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateCollection_CollectionService"] +== UpdateCollection + +`PATCH /v1/collections/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#CollectionServiceUpdateCollectionBody_CommonObjectReference[CollectionServiceUpdateCollectionBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateCollectionResponse_CommonObjectReference[V1UpdateCollectionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateCollectionResponse_CommonObjectReference[V1UpdateCollectionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/CommonObjectReference/CommonObjectReference.adoc b/rest_api/CommonObjectReference/CommonObjectReference.adoc new file mode 100644 index 000000000000..ddbb9358353b --- /dev/null +++ b/rest_api/CommonObjectReference/CommonObjectReference.adoc @@ -0,0 +1,29262 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="CommonObjectReference"] += Common Object Reference +:toc: macro +:toc-title: + +toc::[] + +:context: CommonObjectReference + +[id="models_CommonObjectReference"] +== Common object reference + +== Models + +[id="AlertDeploymentContainer_CommonObjectReference"] +=== AlertDeploymentContainer + +[id="Fields-AlertDeploymentContainer_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| image +| +| +| <<StorageContainerImage_CommonObjectReference,StorageContainerImage>> +| +| + +| name +| +| +| String +| +| + +|=== + +[id="AlertEnforcement_CommonObjectReference"] +=== AlertEnforcement + +[id="Fields-AlertEnforcement_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| action +| +| +| <<StorageEnforcementAction_CommonObjectReference,StorageEnforcementAction>> +| +| UNSET_ENFORCEMENT, SCALE_TO_ZERO_ENFORCEMENT, UNSATISFIABLE_NODE_CONSTRAINT_ENFORCEMENT, KILL_POD_ENFORCEMENT, FAIL_BUILD_ENFORCEMENT, FAIL_KUBE_REQUEST_ENFORCEMENT, FAIL_DEPLOYMENT_CREATE_ENFORCEMENT, FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT, + +| message +| +| +| String +| +| + +|=== + +[id="AlertEntityType_CommonObjectReference"] +=== AlertEntityType + +[id="Fields-AlertEntityType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| DEPLOYMENT +| CONTAINER_IMAGE +| RESOURCE + +|=== + +[id="AlertGroupAlertCounts_CommonObjectReference"] +=== AlertGroupAlertCounts + +[id="Fields-AlertGroupAlertCounts_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| severity +| +| +| <<StorageSeverity_CommonObjectReference,StorageSeverity>> +| +| UNSET_SEVERITY, LOW_SEVERITY, MEDIUM_SEVERITY, HIGH_SEVERITY, CRITICAL_SEVERITY, + +| count +| +| +| String +| +| int64 + +|=== + +[id="AlertProcessViolation_CommonObjectReference"] +=== AlertProcessViolation + +[id="Fields-AlertProcessViolation_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| message +| +| +| String +| +| + +| processes +| +| +| List of <<StorageProcessIndicator_CommonObjectReference,StorageProcessIndicator>> +| +| + +|=== + +[id="AlertResourceResourceType_CommonObjectReference"] +=== AlertResourceResourceType + +[id="Fields-AlertResourceResourceType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| SECRETS +| CONFIGMAPS +| CLUSTER_ROLES +| CLUSTER_ROLE_BINDINGS +| NETWORK_POLICIES +| SECURITY_CONTEXT_CONSTRAINTS +| EGRESS_FIREWALLS + +|=== + +[id="AlertServiceResolveAlertBody_CommonObjectReference"] +=== AlertServiceResolveAlertBody + +[id="Fields-AlertServiceResolveAlertBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| whitelist +| +| +| Boolean +| +| + +| addToBaseline +| +| +| Boolean +| +| + +|=== + +[id="AlertViolation_CommonObjectReference"] +=== AlertViolation + +[id="Fields-AlertViolation_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| message +| +| +| String +| +| + +| keyValueAttrs +| +| +| <<ViolationKeyValueAttrs_CommonObjectReference,ViolationKeyValueAttrs>> +| +| + +| networkFlowInfo +| +| +| <<ViolationNetworkFlowInfo_CommonObjectReference,ViolationNetworkFlowInfo>> +| +| + +| type +| +| +| <<AlertViolationType_CommonObjectReference,AlertViolationType>> +| +| GENERIC, K8S_EVENT, NETWORK_FLOW, NETWORK_POLICY, + +| time +| +| +| Date +| Indicates violation time. This field differs from top-level field 'time' which represents last time the alert occurred in case of multiple occurrences of the policy alert. As of 55.0, this field is set only for kubernetes event violations, but may not be limited to it in future. +| date-time + +|=== + +[id="AlertViolationType_CommonObjectReference"] +=== AlertViolationType + +[id="Fields-AlertViolationType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| GENERIC +| K8S_EVENT +| NETWORK_FLOW +| NETWORK_POLICY + +|=== + +[id="AuthMachineToMachineConfigMapping_CommonObjectReference"] +=== AuthMachineToMachineConfigMapping + +Mappings map an identity token's claim values to a specific role within Central. + +[id="Fields-AuthMachineToMachineConfigMapping_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| A key within the identity token's claim value to use. +| + +| valueExpression +| +| +| String +| A regular expression that will be evaluated against values of the identity token claim identified by the specified key. This regular expressions is in RE2 format, see more here: https://github.com/google/re2/wiki/Syntax. +| + +| role +| +| +| String +| The role which should be issued when the key and value match for a particular identity token. +| + +|=== + +[id="AuthProviderRequiredAttribute_CommonObjectReference"] +=== AuthProviderRequiredAttribute + +RequiredAttribute allows to specify a set of attributes which ALL are required to be returned +by the auth provider. +If any attribute is missing within the external claims of the token issued by Central, the +authentication request to this IdP is considered failed. + +[id="Fields-AuthProviderRequiredAttribute_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| attributeKey +| +| +| String +| +| + +| attributeValue +| +| +| String +| +| + +|=== + +[id="AuthProviderServicePutAuthProviderBody_CommonObjectReference"] +=== AuthProviderServicePutAuthProviderBody + +Next Tag: 15. + +[id="Fields-AuthProviderServicePutAuthProviderBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| uiEndpoint +| +| +| String +| +| + +| enabled +| +| +| Boolean +| +| + +| config +| +| +| Map of `string` +| Config holds auth provider specific configuration. Each configuration options are different based on the given auth provider type. OIDC: - "issuer": the OIDC issuer according to https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier. - "client_id": the client ID according to https://www.rfc-editor.org/rfc/rfc6749.html#section-2.2. - "client_secret": the client secret according to https://www.rfc-editor.org/rfc/rfc6749.html#section-2.3.1. - "do_not_use_client_secret": set to "true" if you want to create a configuration with only a client ID and no client secret. - "mode": the OIDC callback mode, choosing from "fragment", "post", or "query". - "disable_offline_access_scope": set to "true" if no offline tokens shall be issued. - "extra_scopes": a space-delimited string of additional scopes to request in addition to "openid profile email" according to https://www.rfc-editor.org/rfc/rfc6749.html#section-3.3. OpenShift Auth: supports no extra configuration options. User PKI: - "keys": the trusted certificates PEM encoded. SAML: - "sp_issuer": the service provider issuer according to https://datatracker.ietf.org/doc/html/rfc7522#section-3. - "idp_metadata_url": the metadata URL according to https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf. - "idp_issuer": the IdP issuer. - "idp_cert_pem": the cert PEM encoded for the IdP endpoint. - "idp_sso_url": the IdP SSO URL. - "idp_nameid_format": the IdP name ID format. IAP: - "audience": the audience to use. +| + +| loginUrl +| +| +| String +| The login URL will be provided by the backend, and may not be specified in a request. +| + +| validated +| +| +| Boolean +| +| + +| extraUiEndpoints +| +| +| List of `string` +| UI endpoints which to allow in addition to `ui_endpoint`. I.e., if a login request is coming from any of these, the auth request will use these for the callback URL, not ui_endpoint. +| + +| active +| +| +| Boolean +| +| + +| requiredAttributes +| +| +| List of <<AuthProviderRequiredAttribute_CommonObjectReference,AuthProviderRequiredAttribute>> +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +| claimMappings +| +| +| Map of `string` +| Specifies claims from IdP token that will be copied to Rox token attributes. Each key in this map contains a path in IdP token we want to map. Path is separated by "." symbol. For example, if IdP token payload looks like: { "a": { "b" : "c", "d": true, "e": [ "val1", "val2", "val3" ], "f": [ true, false, false ], "g": 123.0, "h": [ 1, 2, 3] } } then "a.b" would be a valid key and "a.z" is not. We support the following types of claims: * string(path "a.b") * bool(path "a.d") * string array(path "a.e") * bool array (path "a.f.") We do NOT support the following types of claims: * complex claims(path "a") * float/integer claims(path "a.g") * float/integer array claims(path "a.h") Each value in this map contains a Rox token attribute name we want to add claim to. If, for example, value is "groups", claim would be found in "external_user.Attributes.groups" in token. Note: we only support this feature for OIDC auth provider. +| + +| lastUpdated +| +| +| Date +| Last updated indicates the last time the auth provider has been updated. In case there have been tokens issued by an auth provider _before_ this timestamp, they will be considered invalid. Subsequently, all clients will have to re-issue their tokens (either by refreshing or by an additional login attempt). +| date-time + +|=== + +[id="AuthProviderServiceUpdateAuthProviderBody_CommonObjectReference"] +=== AuthProviderServiceUpdateAuthProviderBody + +[id="Fields-AuthProviderServiceUpdateAuthProviderBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| enabled +| +| +| Boolean +| +| + +|=== + +[id="AuthServiceUpdateAuthMachineToMachineConfigBody_CommonObjectReference"] +=== AuthServiceUpdateAuthMachineToMachineConfigBody + +[id="Fields-AuthServiceUpdateAuthMachineToMachineConfigBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<AuthServiceUpdateAuthMachineToMachineConfigBody_CommonObjectReference,AuthServiceUpdateAuthMachineToMachineConfigBody>> +| +| + +|=== + +[id="AuthServiceUpdateAuthMachineToMachineConfigBodyConfig_CommonObjectReference"] +=== AuthServiceUpdateAuthMachineToMachineConfigBodyConfig + +AuthMachineToMachineConfig determines rules for exchanging an identity token from a third party with +a Central access token. The M2M stands for machine to machine, as this is the intended use-case +for the config. + +[id="Fields-AuthServiceUpdateAuthMachineToMachineConfigBodyConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| <<V1AuthMachineToMachineConfigType_CommonObjectReference,V1AuthMachineToMachineConfigType>> +| +| GENERIC, GITHUB_ACTIONS, KUBE_SERVICE_ACCOUNT, + +| tokenExpirationDuration +| +| +| String +| Sets the expiration of the token returned from the ExchangeAuthMachineToMachineToken API call. Possible valid time units are: s, m, h. The maximum allowed expiration duration is 24h. As an example: 2h45m. For additional information on the validation of the duration, see: https://pkg.go.dev/time#ParseDuration. +| + +| mappings +| +| +| List of <<AuthMachineToMachineConfigMapping_CommonObjectReference,AuthMachineToMachineConfigMapping>> +| At least one mapping is required to resolve to a valid role for the access token to be successfully generated. +| + +| issuer +| +| +| String +| The issuer of the related OIDC provider issuing the ID tokens to exchange. Must be non-empty string containing URL when type is GENERIC. In case of GitHub actions, this must be empty or set to https://token.actions.githubusercontent.com. Issuer is a unique key, therefore there may be at most one GITHUB_ACTIONS config, and each GENERIC config must have a distinct issuer. +| + +|=== + +[id="AuthorizationTraceResponseResponseStatus_CommonObjectReference"] +=== AuthorizationTraceResponseResponseStatus + +[id="Fields-AuthorizationTraceResponseResponseStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN_STATUS +| SUCCESS +| FAILURE + +|=== + +[id="AuthorizationTraceResponseTrace_CommonObjectReference"] +=== AuthorizationTraceResponseTrace + +[id="Fields-AuthorizationTraceResponseTrace_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scopeCheckerType +| +| +| String +| +| + +| builtIn +| +| +| <<TraceBuiltInAuthorizer_CommonObjectReference,TraceBuiltInAuthorizer>> +| +| + +|=== + +[id="AuthorizationTraceResponseUserRole_CommonObjectReference"] +=== AuthorizationTraceResponseUserRole + +[id="Fields-AuthorizationTraceResponseUserRole_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| permissions +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| + +| accessScopeName +| +| +| String +| +| + +| accessScope +| +| +| <<SimpleAccessScopeRules_CommonObjectReference,SimpleAccessScopeRules>> +| +| + +|=== + +[id="AvailableProviderTypesResponseAuthProviderType_CommonObjectReference"] +=== AvailableProviderTypesResponseAuthProviderType + +[id="Fields-AvailableProviderTypesResponseAuthProviderType_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| String +| +| + +| suggestedAttributes +| +| +| List of `string` +| +| + +|=== + +[id="BannerConfigSize_CommonObjectReference"] +=== BannerConfigSize + +[id="Fields-BannerConfigSize_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| SMALL +| MEDIUM +| LARGE + +|=== + +[id="CRSRevokeResponseCRSRevocationError_CommonObjectReference"] +=== CRSRevokeResponseCRSRevocationError + +[id="Fields-CRSRevokeResponseCRSRevocationError_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| error +| +| +| String +| +| + +|=== + +[id="CVSSV2AccessComplexity_CommonObjectReference"] +=== CVSSV2AccessComplexity + +[id="Fields-CVSSV2AccessComplexity_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ACCESS_HIGH +| ACCESS_MEDIUM +| ACCESS_LOW + +|=== + +[id="CVSSV2Authentication_CommonObjectReference"] +=== CVSSV2Authentication + +[id="Fields-CVSSV2Authentication_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| AUTH_MULTIPLE +| AUTH_SINGLE +| AUTH_NONE + +|=== + +[id="CVSSV3Complexity_CommonObjectReference"] +=== CVSSV3Complexity + +[id="Fields-CVSSV3Complexity_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| COMPLEXITY_LOW +| COMPLEXITY_HIGH + +|=== + +[id="CVSSV3Privileges_CommonObjectReference"] +=== CVSSV3Privileges + +[id="Fields-CVSSV3Privileges_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| PRIVILEGE_NONE +| PRIVILEGE_LOW +| PRIVILEGE_HIGH + +|=== + +[id="CVSSV3UserInteraction_CommonObjectReference"] +=== CVSSV3UserInteraction + +[id="Fields-CVSSV3UserInteraction_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UI_NONE +| UI_REQUIRED + +|=== + +[id="CentralServicesCapabilitiesCapabilityStatus_CommonObjectReference"] +=== CentralServicesCapabilitiesCapabilityStatus + + - CapabilityAvailable: CapabilityAvailable means that UI and APIs should be available for users to use. +This does not automatically mean that the functionality is 100% available and any calls to APIs will result +in successful execution. Rather it means that users should be allowed to leverage the functionality as +opposed to CapabilityDisabled when functionality should be blocked. + - CapabilityDisabled: CapabilityDisabled means the corresponding UI should be disabled and attempts to use related APIs +should lead to errors. + +[id="Fields-CentralServicesCapabilitiesCapabilityStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| CapabilityAvailable +| CapabilityDisabled + +|=== + +[id="CentralTelemetryConfig_CommonObjectReference"] +=== CentralTelemetryConfig + +[id="Fields-CentralTelemetryConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| userId +| +| +| String +| +| + +| endpoint +| +| +| String +| +| + +| storageKeyV1 +| +| +| String +| +| + +|=== + +[id="CloudSourcesServiceUpdateCloudSourceBody_CommonObjectReference"] +=== CloudSourcesServiceUpdateCloudSourceBody + +[id="Fields-CloudSourcesServiceUpdateCloudSourceBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cloudSource +| +| +| <<CloudSourcesServiceUpdateCloudSourceBody_CommonObjectReference,CloudSourcesServiceUpdateCloudSourceBody>> +| +| + +| updateCredentials +| +| +| Boolean +| If true, cloud_source must include valid credentials. If false, the resource must already exist and credentials in cloud_source are ignored. +| + +|=== + +[id="CloudSourcesServiceUpdateCloudSourceBodyCloudSource_CommonObjectReference"] +=== CloudSourcesServiceUpdateCloudSourceBodyCloudSource + +CloudSource is an integration which provides a source for discovered +clusters. + +[id="Fields-CloudSourcesServiceUpdateCloudSourceBodyCloudSource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| <<V1CloudSourceType_CommonObjectReference,V1CloudSourceType>> +| +| TYPE_UNSPECIFIED, TYPE_PALADIN_CLOUD, TYPE_OCM, + +| credentials +| +| +| <<V1CloudSourceCredentials_CommonObjectReference,V1CloudSourceCredentials>> +| +| + +| skipTestIntegration +| +| +| Boolean +| +| + +| paladinCloud +| +| +| <<V1PaladinCloudConfig_CommonObjectReference,V1PaladinCloudConfig>> +| +| + +| ocm +| +| +| <<V1OCMConfig_CommonObjectReference,V1OCMConfig>> +| +| + +|=== + +[id="ClusterAlertsAlertEvents_CommonObjectReference"] +=== ClusterAlertsAlertEvents + +[id="Fields-ClusterAlertsAlertEvents_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| severity +| +| +| <<StorageSeverity_CommonObjectReference,StorageSeverity>> +| +| UNSET_SEVERITY, LOW_SEVERITY, MEDIUM_SEVERITY, HIGH_SEVERITY, CRITICAL_SEVERITY, + +| events +| +| +| List of <<V1AlertEvent_CommonObjectReference,V1AlertEvent>> +| +| + +|=== + +[id="ClusterHealthStatusHealthStatusLabel_CommonObjectReference"] +=== ClusterHealthStatusHealthStatusLabel + +- UNAVAILABLE: Only collector can have unavailable status + +[id="Fields-ClusterHealthStatusHealthStatusLabel_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNINITIALIZED +| UNAVAILABLE +| UNHEALTHY +| DEGRADED +| HEALTHY + +|=== + +[id="ClusterScanStatusSuiteStatus_CommonObjectReference"] +=== ClusterScanStatusSuiteStatus + +Additional scan status gathered from ComplianceSuite + +[id="Fields-ClusterScanStatusSuiteStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| phase +| +| +| String +| +| + +| result +| +| +| String +| +| + +| errorMessage +| +| +| String +| +| + +| lastTransitionTime +| +| +| Date +| +| date-time + +|=== + +[id="ClusterUpgradeStatusUpgradability_CommonObjectReference"] +=== ClusterUpgradeStatusUpgradability + + - SENSOR_VERSION_HIGHER: SENSOR_VERSION_HIGHER occurs when we detect that the sensor +is running a newer version than this Central. This is unexpected, +but can occur depending on the patches a customer does. +In this case, we will NOT automatically "upgrade" the sensor, +since that would be a downgrade, even if the autoupgrade setting is +on. The user will be allowed to manually trigger the upgrade, but they are +strongly discouraged from doing so without upgrading Central first, since this +is an unsupported configuration. + +[id="Fields-ClusterUpgradeStatusUpgradability_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| UP_TO_DATE +| MANUAL_UPGRADE_REQUIRED +| AUTO_UPGRADE_POSSIBLE +| SENSOR_VERSION_HIGHER + +|=== + +[id="ClusterUpgradeStatusUpgradeProcessStatus_CommonObjectReference"] +=== ClusterUpgradeStatusUpgradeProcessStatus + +[id="Fields-ClusterUpgradeStatusUpgradeProcessStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| active +| +| +| Boolean +| +| + +| id +| +| +| String +| +| + +| targetVersion +| +| +| String +| +| + +| upgraderImage +| +| +| String +| +| + +| initiatedAt +| +| +| Date +| +| date-time + +| progress +| +| +| <<StorageUpgradeProgress_CommonObjectReference,StorageUpgradeProgress>> +| +| + +| type +| +| +| <<UpgradeProcessStatusUpgradeProcessType_CommonObjectReference,UpgradeProcessStatusUpgradeProcessType>> +| +| UPGRADE, CERT_ROTATION, + +|=== + +[id="ClustersServicePutClusterBody_CommonObjectReference"] +=== ClustersServicePutClusterBody + +[id="Fields-ClustersServicePutClusterBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| <<StorageClusterType_CommonObjectReference,StorageClusterType>> +| +| GENERIC_CLUSTER, KUBERNETES_CLUSTER, OPENSHIFT_CLUSTER, OPENSHIFT4_CLUSTER, + +| labels +| +| +| Map of `string` +| +| + +| mainImage +| +| +| String +| +| + +| collectorImage +| +| +| String +| +| + +| centralApiEndpoint +| +| +| String +| +| + +| runtimeSupport +| +| +| Boolean +| +| + +| collectionMethod +| +| +| <<StorageCollectionMethod_CommonObjectReference,StorageCollectionMethod>> +| +| UNSET_COLLECTION, NO_COLLECTION, KERNEL_MODULE, EBPF, CORE_BPF, + +| admissionController +| +| +| Boolean +| +| + +| admissionControllerUpdates +| +| +| Boolean +| +| + +| admissionControllerEvents +| +| +| Boolean +| +| + +| status +| +| +| <<StorageClusterStatus_CommonObjectReference,StorageClusterStatus>> +| +| + +| dynamicConfig +| +| +| <<StorageDynamicClusterConfig_CommonObjectReference,StorageDynamicClusterConfig>> +| +| + +| tolerationsConfig +| +| +| <<StorageTolerationsConfig_CommonObjectReference,StorageTolerationsConfig>> +| +| + +| priority +| +| +| String +| +| int64 + +| healthStatus +| +| +| <<StorageClusterHealthStatus_CommonObjectReference,StorageClusterHealthStatus>> +| +| + +| slimCollector +| +| +| Boolean +| +| + +| helmConfig +| +| +| <<StorageCompleteClusterConfig_CommonObjectReference,StorageCompleteClusterConfig>> +| +| + +| mostRecentSensorId +| +| +| <<StorageSensorDeploymentIdentification_CommonObjectReference,StorageSensorDeploymentIdentification>> +| +| + +| auditLogState +| +| +| Map of <<StorageAuditLogFileState_CommonObjectReference,StorageAuditLogFileState>> +| For internal use only. +| + +| initBundleId +| +| +| String +| +| + +| managedBy +| +| +| <<StorageManagerType_CommonObjectReference,StorageManagerType>> +| +| MANAGER_TYPE_UNKNOWN, MANAGER_TYPE_MANUAL, MANAGER_TYPE_HELM_CHART, MANAGER_TYPE_KUBERNETES_OPERATOR, + +| sensorCapabilities +| +| +| List of `string` +| +| + +|=== + +[id="CollectionServiceUpdateCollectionBody_CommonObjectReference"] +=== CollectionServiceUpdateCollectionBody + +[id="Fields-CollectionServiceUpdateCollectionBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| resourceSelectors +| +| +| List of <<StorageResourceSelector_CommonObjectReference,StorageResourceSelector>> +| +| + +| embeddedCollectionIds +| +| +| List of `string` +| +| + +|=== + +[id="ComplianceAggregationAggregationKey_CommonObjectReference"] +=== ComplianceAggregationAggregationKey + +Next available tag: 3 + +[id="Fields-ComplianceAggregationAggregationKey_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scope +| +| +| <<StorageComplianceAggregationScope_CommonObjectReference,StorageComplianceAggregationScope>> +| +| UNKNOWN, STANDARD, CLUSTER, CATEGORY, CONTROL, NAMESPACE, NODE, DEPLOYMENT, CHECK, + +| id +| +| +| String +| +| + +|=== + +[id="ComplianceResultValueEvidence_CommonObjectReference"] +=== ComplianceResultValueEvidence + +[id="Fields-ComplianceResultValueEvidence_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| state +| +| +| <<StorageComplianceState_CommonObjectReference,StorageComplianceState>> +| +| COMPLIANCE_STATE_UNKNOWN, COMPLIANCE_STATE_SKIP, COMPLIANCE_STATE_NOTE, COMPLIANCE_STATE_SUCCESS, COMPLIANCE_STATE_FAILURE, COMPLIANCE_STATE_ERROR, + +| message +| +| +| String +| +| + +| messageId +| +| +| Integer +| +| int32 + +|=== + +[id="ComplianceRuleFix_CommonObjectReference"] +=== ComplianceRuleFix + +[id="Fields-ComplianceRuleFix_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| platform +| +| +| String +| +| + +| disruption +| +| +| String +| +| + +|=== + +[id="ComplianceRunResultsEntityResults_CommonObjectReference"] +=== ComplianceRunResultsEntityResults + +[id="Fields-ComplianceRunResultsEntityResults_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| controlResults +| +| +| Map of <<StorageComplianceResultValue_CommonObjectReference,StorageComplianceResultValue>> +| +| + +|=== + +[id="ComplianceScanConfigurationServiceUpdateComplianceScanConfigurationBody_CommonObjectReference"] +=== ComplianceScanConfigurationServiceUpdateComplianceScanConfigurationBody + +Next available tag: 5 + +[id="Fields-ComplianceScanConfigurationServiceUpdateComplianceScanConfigurationBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanName +| +| +| String +| +| + +| scanConfig +| +| +| <<V2BaseComplianceScanConfigurationSettings_CommonObjectReference,V2BaseComplianceScanConfigurationSettings>> +| +| + +| clusters +| +| +| List of `string` +| +| + +|=== + +[id="ComplianceServiceUpdateComplianceStandardConfigBody_CommonObjectReference"] +=== ComplianceServiceUpdateComplianceStandardConfigBody + +[id="Fields-ComplianceServiceUpdateComplianceStandardConfigBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| hideScanResults +| +| +| Boolean +| +| + +|=== + +[id="ComputeEffectiveAccessScopeRequestDetail_CommonObjectReference"] +=== ComputeEffectiveAccessScopeRequestDetail + +[id="Fields-ComputeEffectiveAccessScopeRequestDetail_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| STANDARD +| MINIMAL +| HIGH + +|=== + +[id="ComputeEffectiveAccessScopeRequestPayload_CommonObjectReference"] +=== ComputeEffectiveAccessScopeRequestPayload + +[id="Fields-ComputeEffectiveAccessScopeRequestPayload_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| simpleRules +| +| +| <<SimpleAccessScopeRules_CommonObjectReference,SimpleAccessScopeRules>> +| +| + +|=== + +[id="ContainerConfigEnvironmentConfig_CommonObjectReference"] +=== ContainerConfigEnvironmentConfig + +[id="Fields-ContainerConfigEnvironmentConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| value +| +| +| String +| +| + +| envVarSource +| +| +| <<EnvironmentConfigEnvVarSource_CommonObjectReference,EnvironmentConfigEnvVarSource>> +| +| UNSET, RAW, SECRET_KEY, CONFIG_MAP_KEY, FIELD, RESOURCE_FIELD, UNKNOWN, + +|=== + +[id="ContainerNameAndBaselineStatusBaselineStatus_CommonObjectReference"] +=== ContainerNameAndBaselineStatusBaselineStatus + + - NOT_GENERATED: In current implementation, this is a temporary condition. + +[id="Fields-ContainerNameAndBaselineStatusBaselineStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| INVALID +| NOT_GENERATED +| UNLOCKED +| LOCKED + +|=== + +[id="CosignPublicKeyVerificationPublicKey_CommonObjectReference"] +=== CosignPublicKeyVerificationPublicKey + +[id="Fields-CosignPublicKeyVerificationPublicKey_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| publicKeyPemEnc +| +| +| String +| +| + +|=== + +[id="DBExportManifestEncodingType_CommonObjectReference"] +=== DBExportManifestEncodingType + +The encoding of the file data in the restore body, usually for compression purposes. + +[id="Fields-DBExportManifestEncodingType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| UNCOMPREESSED +| DEFLATED + +|=== + +[id="DBRestoreProcessStatusResumeInfo_CommonObjectReference"] +=== DBRestoreProcessStatusResumeInfo + +[id="Fields-DBRestoreProcessStatusResumeInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| pos +| +| +| String +| +| int64 + +|=== + +[id="DBRestoreRequestHeaderLocalFileInfo_CommonObjectReference"] +=== DBRestoreRequestHeaderLocalFileInfo + +LocalFileInfo provides information about the file on the local machine of the user initiating the restore +process, in order to provide information to other users about ongoing restore processes. + +[id="Fields-DBRestoreRequestHeaderLocalFileInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| path +| +| +| String +| The full path of the file. +| + +| bytesSize +| +| +| String +| The size of the file, in bytes. 0 if unknown. +| int64 + +|=== + +[id="DatabaseStatusDatabaseType_CommonObjectReference"] +=== DatabaseStatusDatabaseType + +[id="Fields-DatabaseStatusDatabaseType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| Hidden +| RocksDB +| PostgresDB + +|=== + +[id="DelegatedRegistryConfigDelegatedRegistry_CommonObjectReference"] +=== DelegatedRegistryConfigDelegatedRegistry + +[id="Fields-DelegatedRegistryConfigDelegatedRegistry_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| path +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +|=== + +[id="DelegatedRegistryConfigEnabledFor_CommonObjectReference"] +=== DelegatedRegistryConfigEnabledFor + +- NONE: Scan all images via central services except for images from the OCP integrated registry - ALL: Scan all images via the secured clusters - SPECIFIC: Scan images that match `registries` or are from the OCP integrated registry via the secured clusters otherwise scan via central services + +[id="Fields-DelegatedRegistryConfigEnabledFor_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| NONE +| ALL +| SPECIFIC + +|=== + +[id="DeployDetectionResponseRun_CommonObjectReference"] +=== DeployDetectionResponseRun + +[id="Fields-DeployDetectionResponseRun_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| alerts +| +| +| List of <<StorageAlert_CommonObjectReference,StorageAlert>> +| +| + +|=== + +[id="DeploymentLabelsResponseLabelValues_CommonObjectReference"] +=== DeploymentLabelsResponseLabelValues + +[id="Fields-DeploymentLabelsResponseLabelValues_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| values +| +| +| List of `string` +| +| + +|=== + +[id="DeploymentListenPort_CommonObjectReference"] +=== DeploymentListenPort + +[id="Fields-DeploymentListenPort_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| port +| +| +| Long +| +| int64 + +| l4protocol +| +| +| <<StorageL4Protocol_CommonObjectReference,StorageL4Protocol>> +| +| L4_PROTOCOL_UNKNOWN, L4_PROTOCOL_TCP, L4_PROTOCOL_UDP, L4_PROTOCOL_ICMP, L4_PROTOCOL_RAW, L4_PROTOCOL_SCTP, L4_PROTOCOL_ANY, + +|=== + +[id="DiscoveredClusterMetadataType_CommonObjectReference"] +=== DiscoveredClusterMetadataType + +[id="Fields-DiscoveredClusterMetadataType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSPECIFIED +| AKS +| ARO +| EKS +| GKE +| OCP +| OSD +| ROSA + +|=== + +[id="ECRConfigAuthorizationData_CommonObjectReference"] +=== ECRConfigAuthorizationData + +An authorization data represents the IAM authentication credentials and +can be used to access any Amazon ECR registry that the IAM principal has +access to. + +[id="Fields-ECRConfigAuthorizationData_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| username +| +| +| String +| +| + +| password +| +| +| String +| +| + +| expiresAt +| +| +| Date +| +| date-time + +|=== + +[id="EmailAuthMethod_CommonObjectReference"] +=== EmailAuthMethod + +[id="Fields-EmailAuthMethod_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| DISABLED +| PLAIN +| LOGIN + +|=== + +[id="EmbeddedVulnerabilityVulnerabilityType_CommonObjectReference"] +=== EmbeddedVulnerabilityVulnerabilityType + +[id="Fields-EmbeddedVulnerabilityVulnerabilityType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN_VULNERABILITY +| IMAGE_VULNERABILITY +| K8S_VULNERABILITY +| ISTIO_VULNERABILITY +| NODE_VULNERABILITY +| OPENSHIFT_VULNERABILITY + +|=== + +[id="EnvironmentConfigEnvVarSource_CommonObjectReference"] +=== EnvironmentConfigEnvVarSource + +For any update to EnvVarSource, please also update 'ui/src/messages/common.js' + +[id="Fields-EnvironmentConfigEnvVarSource_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| RAW +| SECRET_KEY +| CONFIG_MAP_KEY +| FIELD +| RESOURCE_FIELD +| UNKNOWN + +|=== + +[id="EnvironmentList_CommonObjectReference"] +=== EnvironmentList + +[id="Fields-EnvironmentList_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| environments +| +| +| List of <<V4Environment_CommonObjectReference,V4Environment>> +| +| + +|=== + +[id="ExceptionExpiryExpiryType_CommonObjectReference"] +=== ExceptionExpiryExpiryType + +[id="Fields-ExceptionExpiryExpiryType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| TIME +| ALL_CVE_FIXABLE +| ANY_CVE_FIXABLE + +|=== + +[id="ExternalBackupServicePutExternalBackupBody_CommonObjectReference"] +=== ExternalBackupServicePutExternalBackupBody + +Next available tag: 10 + +[id="Fields-ExternalBackupServicePutExternalBackupBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| schedule +| +| +| <<StorageSchedule_CommonObjectReference,StorageSchedule>> +| +| + +| backupsToKeep +| +| +| Integer +| +| int32 + +| s3 +| +| +| <<StorageS3Config_CommonObjectReference,StorageS3Config>> +| +| + +| gcs +| +| +| <<StorageGCSConfig_CommonObjectReference,StorageGCSConfig>> +| +| + +| s3compatible +| +| +| <<StorageS3Compatible_CommonObjectReference,StorageS3Compatible>> +| +| + +| includeCertificates +| +| +| Boolean +| +| + +|=== + +[id="ExternalBackupServiceUpdateExternalBackupBody_CommonObjectReference"] +=== ExternalBackupServiceUpdateExternalBackupBody + +[id="Fields-ExternalBackupServiceUpdateExternalBackupBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| externalBackup +| +| +| <<NextAvailableTag10_CommonObjectReference,NextAvailableTag10>> +| +| + +| updatePassword +| +| +| Boolean +| When false, use the stored credentials of an existing external backup configuration given its ID. +| + +|=== + +[id="GenerateNetworkPoliciesRequestDeleteExistingPoliciesMode_CommonObjectReference"] +=== GenerateNetworkPoliciesRequestDeleteExistingPoliciesMode + + - NONE: Do not delete any existing network policies. + - GENERATED_ONLY: Delete any existing *auto-generated* network policies. + - ALL: Delete all existing network policies in the respective namespace. + +[id="Fields-GenerateNetworkPoliciesRequestDeleteExistingPoliciesMode_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| NONE +| GENERATED_ONLY +| ALL + +|=== + +[id="GetAlertTimeseriesResponseClusterAlerts_CommonObjectReference"] +=== GetAlertTimeseriesResponseClusterAlerts + +[id="Fields-GetAlertTimeseriesResponseClusterAlerts_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cluster +| +| +| String +| +| + +| severities +| +| +| List of <<ClusterAlertsAlertEvents_CommonObjectReference,ClusterAlertsAlertEvents>> +| +| + +|=== + +[id="GetAlertsCountsRequestRequestGroup_CommonObjectReference"] +=== GetAlertsCountsRequestRequestGroup + +[id="Fields-GetAlertsCountsRequestRequestGroup_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| CATEGORY +| CLUSTER + +|=== + +[id="GetAlertsCountsResponseAlertGroup_CommonObjectReference"] +=== GetAlertsCountsResponseAlertGroup + +[id="Fields-GetAlertsCountsResponseAlertGroup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| group +| +| +| String +| +| + +| counts +| +| +| List of <<AlertGroupAlertCounts_CommonObjectReference,AlertGroupAlertCounts>> +| +| + +|=== + +[id="GetLoginAuthProvidersResponseLoginAuthProvider_CommonObjectReference"] +=== GetLoginAuthProvidersResponseLoginAuthProvider + +[id="Fields-GetLoginAuthProvidersResponseLoginAuthProvider_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| loginUrl +| +| +| String +| +| + +|=== + +[id="GetSensorUpgradeConfigResponseSensorAutoUpgradeFeatureStatus_CommonObjectReference"] +=== GetSensorUpgradeConfigResponseSensorAutoUpgradeFeatureStatus + +[id="Fields-GetSensorUpgradeConfigResponseSensorAutoUpgradeFeatureStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| NOT_SUPPORTED +| SUPPORTED + +|=== + +[id="GetSensorUpgradeConfigResponseUpgradeConfig_CommonObjectReference"] +=== GetSensorUpgradeConfigResponseUpgradeConfig + +[id="Fields-GetSensorUpgradeConfigResponseUpgradeConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enableAutoUpgrade +| +| +| Boolean +| +| + +| autoUpgradeFeature +| +| +| <<GetSensorUpgradeConfigResponseSensorAutoUpgradeFeatureStatus_CommonObjectReference,GetSensorUpgradeConfigResponseSensorAutoUpgradeFeatureStatus>> +| +| NOT_SUPPORTED, SUPPORTED, + +|=== + +[id="GooglerpcStatus_CommonObjectReference"] +=== GooglerpcStatus + +[id="Fields-GooglerpcStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| code +| +| +| Integer +| +| int32 + +| message +| +| +| String +| +| + +| details +| +| +| List of <<ProtobufAny_CommonObjectReference,ProtobufAny>> +| +| + +|=== + +[id="ImageIntegrationServicePutImageIntegrationBody_CommonObjectReference"] +=== ImageIntegrationServicePutImageIntegrationBody + +Next Tag: 25 + +[id="Fields-ImageIntegrationServicePutImageIntegrationBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| categories +| +| +| List of <<StorageImageIntegrationCategory_CommonObjectReference,StorageImageIntegrationCategory>> +| +| + +| clairify +| +| +| <<StorageClairifyConfig_CommonObjectReference,StorageClairifyConfig>> +| +| + +| scannerV4 +| +| +| <<StorageScannerV4Config_CommonObjectReference,StorageScannerV4Config>> +| +| + +| docker +| +| +| <<StorageDockerConfig_CommonObjectReference,StorageDockerConfig>> +| +| + +| quay +| +| +| <<StorageQuayConfig_CommonObjectReference,StorageQuayConfig>> +| +| + +| ecr +| +| +| <<StorageECRConfig_CommonObjectReference,StorageECRConfig>> +| +| + +| google +| +| +| <<StorageGoogleConfig_CommonObjectReference,StorageGoogleConfig>> +| +| + +| clair +| +| +| <<StorageClairConfig_CommonObjectReference,StorageClairConfig>> +| +| + +| clairV4 +| +| +| <<StorageClairV4Config_CommonObjectReference,StorageClairV4Config>> +| +| + +| ibm +| +| +| <<StorageIBMRegistryConfig_CommonObjectReference,StorageIBMRegistryConfig>> +| +| + +| azure +| +| +| <<StorageAzureConfig_CommonObjectReference,StorageAzureConfig>> +| +| + +| autogenerated +| +| +| Boolean +| +| + +| clusterId +| +| +| String +| +| + +| skipTestIntegration +| +| +| Boolean +| +| + +| source +| +| +| <<StorageImageIntegrationSource_CommonObjectReference,StorageImageIntegrationSource>> +| +| + +|=== + +[id="ImageIntegrationServiceUpdateImageIntegrationBody_CommonObjectReference"] +=== ImageIntegrationServiceUpdateImageIntegrationBody + +[id="Fields-ImageIntegrationServiceUpdateImageIntegrationBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<NextTag25_CommonObjectReference,NextTag25>> +| +| + +| updatePassword +| +| +| Boolean +| When false, use the stored credentials of an existing image integration given its ID. +| + +|=== + +[id="ImagePullSecretRegistry_CommonObjectReference"] +=== ImagePullSecretRegistry + +[id="Fields-ImagePullSecretRegistry_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| username +| +| +| String +| +| + +|=== + +[id="ImageSBOMRequest_CommonObjectReference"] +=== ImageSBOMRequest + +[id="Fields-ImageSBOMRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| imageName +| X +| +| String +| Image name and reference. (e.g. nginx:latest or nginx@sha256:...) +| + +| force +| +| +| Boolean +| Bypass Central's cache for the image and force a new pull from the Scanner +| + +|=== + +[id="InitBundleMetaImpactedCluster_CommonObjectReference"] +=== InitBundleMetaImpactedCluster + +[id="Fields-InitBundleMetaImpactedCluster_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| id +| +| +| String +| +| + +|=== + +[id="InitBundleRevokeResponseInitBundleRevocationError_CommonObjectReference"] +=== InitBundleRevokeResponseInitBundleRevocationError + +[id="Fields-InitBundleRevokeResponseInitBundleRevocationError_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| error +| +| +| String +| +| + +| impactedClusters +| +| +| List of <<InitBundleMetaImpactedCluster_CommonObjectReference,InitBundleMetaImpactedCluster>> +| +| + +|=== + +[id="JiraPriorityMapping_CommonObjectReference"] +=== JiraPriorityMapping + +[id="Fields-JiraPriorityMapping_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| severity +| +| +| <<StorageSeverity_CommonObjectReference,StorageSeverity>> +| +| UNSET_SEVERITY, LOW_SEVERITY, MEDIUM_SEVERITY, HIGH_SEVERITY, CRITICAL_SEVERITY, + +| priorityName +| +| +| String +| +| + +|=== + +[id="KeyValueAttrsKeyValueAttr_CommonObjectReference"] +=== KeyValueAttrsKeyValueAttr + +[id="Fields-KeyValueAttrsKeyValueAttr_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| value +| +| +| String +| +| + +|=== + +[id="ListAlertCommonEntityInfo_CommonObjectReference"] +=== ListAlertCommonEntityInfo + +Fields common to all entities that an alert might belong to. + +[id="Fields-ListAlertCommonEntityInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterName +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| namespaceId +| +| +| String +| +| + +| resourceType +| +| +| <<StorageListAlertResourceType_CommonObjectReference,StorageListAlertResourceType>> +| +| DEPLOYMENT, SECRETS, CONFIGMAPS, CLUSTER_ROLES, CLUSTER_ROLE_BINDINGS, NETWORK_POLICIES, SECURITY_CONTEXT_CONSTRAINTS, EGRESS_FIREWALLS, + +|=== + +[id="ListAlertPolicyDevFields_CommonObjectReference"] +=== ListAlertPolicyDevFields + +[id="Fields-ListAlertPolicyDevFields_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| SORTName +| +| +| String +| +| + +|=== + +[id="ListAlertResourceEntity_CommonObjectReference"] +=== ListAlertResourceEntity + +[id="Fields-ListAlertResourceEntity_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +|=== + +[id="ListDeploymentsWithProcessInfoResponseDeploymentWithProcessInfo_CommonObjectReference"] +=== ListDeploymentsWithProcessInfoResponseDeploymentWithProcessInfo + +[id="Fields-ListDeploymentsWithProcessInfoResponseDeploymentWithProcessInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployment +| +| +| <<StorageListDeployment_CommonObjectReference,StorageListDeployment>> +| +| + +| baselineStatuses +| +| +| List of <<StorageContainerNameAndBaselineStatus_CommonObjectReference,StorageContainerNameAndBaselineStatus>> +| +| + +|=== + +[id="MetadataLicenseStatus_CommonObjectReference"] +=== MetadataLicenseStatus + +[id="Fields-MetadataLicenseStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| NONE +| INVALID +| EXPIRED +| RESTARTING +| VALID + +|=== + +[id="MetadataProviderType_CommonObjectReference"] +=== MetadataProviderType + +[id="Fields-MetadataProviderType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| PROVIDER_TYPE_UNSPECIFIED +| PROVIDER_TYPE_AWS +| PROVIDER_TYPE_GCP +| PROVIDER_TYPE_AZURE + +|=== + +[id="MicrosoftSentinelClientCertAuthConfig_CommonObjectReference"] +=== MicrosoftSentinelClientCertAuthConfig + +client certificate which is used for authentication + +[id="Fields-MicrosoftSentinelClientCertAuthConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clientCert +| +| +| String +| PEM encoded ASN.1 DER format. +| + +| privateKey +| +| +| String +| PEM encoded PKCS #8, ASN.1 DER format. +| + +|=== + +[id="MicrosoftSentinelDataCollectionRuleConfig_CommonObjectReference"] +=== MicrosoftSentinelDataCollectionRuleConfig + +DataCollectionRuleConfig contains information about the data collection rule which is a config per notifier type. + +[id="Fields-MicrosoftSentinelDataCollectionRuleConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| streamName +| +| +| String +| +| + +| dataCollectionRuleId +| +| +| String +| +| + +| enabled +| +| +| Boolean +| +| + +|=== + +[id="NetworkBaselineServiceGetNetworkBaselineStatusForFlowsBody_CommonObjectReference"] +=== NetworkBaselineServiceGetNetworkBaselineStatusForFlowsBody + +[id="Fields-NetworkBaselineServiceGetNetworkBaselineStatusForFlowsBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| peers +| +| +| List of <<V1NetworkBaselineStatusPeer_CommonObjectReference,V1NetworkBaselineStatusPeer>> +| +| + +|=== + +[id="NetworkBaselineServiceModifyBaselineStatusForPeersBody_CommonObjectReference"] +=== NetworkBaselineServiceModifyBaselineStatusForPeersBody + +[id="Fields-NetworkBaselineServiceModifyBaselineStatusForPeersBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| peers +| +| +| List of <<V1NetworkBaselinePeerStatus_CommonObjectReference,V1NetworkBaselinePeerStatus>> +| +| + +|=== + +[id="NetworkEntityInfoExternalSource_CommonObjectReference"] +=== NetworkEntityInfoExternalSource + +Update normalizeDupNameExtSrcs(...) in `central/networkgraph/aggregator/aggregator.go` whenever this message is updated. + +[id="Fields-NetworkEntityInfoExternalSource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| cidr +| +| +| String +| +| + +| default +| +| +| Boolean +| `default` indicates whether the external source is user-generated or system-generated. +| + +| discovered +| +| +| Boolean +| `discovered` indicates whether the external source is harvested from monitored traffic. +| + +|=== + +[id="NetworkFlowInfoEntity_CommonObjectReference"] +=== NetworkFlowInfoEntity + +[id="Fields-NetworkFlowInfoEntity_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| entityType +| +| +| <<StorageNetworkEntityInfoType_CommonObjectReference,StorageNetworkEntityInfoType>> +| +| UNKNOWN_TYPE, DEPLOYMENT, INTERNET, LISTEN_ENDPOINT, EXTERNAL_SOURCE, INTERNAL_ENTITIES, + +| deploymentNamespace +| +| +| String +| +| + +| deploymentType +| +| +| String +| +| + +| port +| +| +| Integer +| +| int32 + +|=== + +[id="NetworkGraphServiceCreateExternalNetworkEntityBody_CommonObjectReference"] +=== NetworkGraphServiceCreateExternalNetworkEntityBody + +[id="Fields-NetworkGraphServiceCreateExternalNetworkEntityBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entity +| +| +| <<NetworkEntityInfoExternalSource_CommonObjectReference,NetworkEntityInfoExternalSource>> +| +| + +|=== + +[id="NetworkGraphServicePatchExternalNetworkEntityBody_CommonObjectReference"] +=== NetworkGraphServicePatchExternalNetworkEntityBody + +[id="Fields-NetworkGraphServicePatchExternalNetworkEntityBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +|=== + +[id="NetworkPolicyServiceApplyNetworkPolicyYamlForDeploymentBody_CommonObjectReference"] +=== NetworkPolicyServiceApplyNetworkPolicyYamlForDeploymentBody + +[id="Fields-NetworkPolicyServiceApplyNetworkPolicyYamlForDeploymentBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| modification +| +| +| <<StorageNetworkPolicyModification_CommonObjectReference,StorageNetworkPolicyModification>> +| +| + +|=== + +[id="NetworkPolicyServiceGetBaselineGeneratedNetworkPolicyForDeploymentBody_CommonObjectReference"] +=== NetworkPolicyServiceGetBaselineGeneratedNetworkPolicyForDeploymentBody + +[id="Fields-NetworkPolicyServiceGetBaselineGeneratedNetworkPolicyForDeploymentBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deleteExisting +| +| +| <<GenerateNetworkPoliciesRequestDeleteExistingPoliciesMode_CommonObjectReference,GenerateNetworkPoliciesRequestDeleteExistingPoliciesMode>> +| +| UNKNOWN, NONE, GENERATED_ONLY, ALL, + +| includePorts +| +| +| Boolean +| +| + +|=== + +[id="NextAvailableTag10_CommonObjectReference"] +=== NextAvailableTag10 + +Next available tag: 10 + +[id="Fields-NextAvailableTag10_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| schedule +| +| +| <<StorageSchedule_CommonObjectReference,StorageSchedule>> +| +| + +| backupsToKeep +| +| +| Integer +| +| int32 + +| s3 +| +| +| <<StorageS3Config_CommonObjectReference,StorageS3Config>> +| +| + +| gcs +| +| +| <<StorageGCSConfig_CommonObjectReference,StorageGCSConfig>> +| +| + +| s3compatible +| +| +| <<StorageS3Compatible_CommonObjectReference,StorageS3Compatible>> +| +| + +| includeCertificates +| +| +| Boolean +| +| + +|=== + +[id="NextTag21_CommonObjectReference"] +=== NextTag21 + +Next Tag: 21 + +[id="Fields-NextTag21_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| uiEndpoint +| +| +| String +| +| + +| labelKey +| +| +| String +| +| + +| labelDefault +| +| +| String +| +| + +| jira +| +| +| <<StorageJira_CommonObjectReference,StorageJira>> +| +| + +| email +| +| +| <<StorageEmail_CommonObjectReference,StorageEmail>> +| +| + +| cscc +| +| +| <<StorageCSCC_CommonObjectReference,StorageCSCC>> +| +| + +| splunk +| +| +| <<StorageSplunk_CommonObjectReference,StorageSplunk>> +| +| + +| pagerduty +| +| +| <<StoragePagerDuty_CommonObjectReference,StoragePagerDuty>> +| +| + +| generic +| +| +| <<StorageGeneric_CommonObjectReference,StorageGeneric>> +| +| + +| sumologic +| +| +| <<StorageSumoLogic_CommonObjectReference,StorageSumoLogic>> +| +| + +| awsSecurityHub +| +| +| <<StorageAWSSecurityHub_CommonObjectReference,StorageAWSSecurityHub>> +| +| + +| syslog +| +| +| <<StorageSyslog_CommonObjectReference,StorageSyslog>> +| +| + +| microsoftSentinel +| +| +| <<StorageMicrosoftSentinel_CommonObjectReference,StorageMicrosoftSentinel>> +| +| + +| notifierSecret +| +| +| String +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="NextTag25_CommonObjectReference"] +=== NextTag25 + +Next Tag: 25 + +[id="Fields-NextTag25_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| categories +| +| +| List of <<StorageImageIntegrationCategory_CommonObjectReference,StorageImageIntegrationCategory>> +| +| + +| clairify +| +| +| <<StorageClairifyConfig_CommonObjectReference,StorageClairifyConfig>> +| +| + +| scannerV4 +| +| +| <<StorageScannerV4Config_CommonObjectReference,StorageScannerV4Config>> +| +| + +| docker +| +| +| <<StorageDockerConfig_CommonObjectReference,StorageDockerConfig>> +| +| + +| quay +| +| +| <<StorageQuayConfig_CommonObjectReference,StorageQuayConfig>> +| +| + +| ecr +| +| +| <<StorageECRConfig_CommonObjectReference,StorageECRConfig>> +| +| + +| google +| +| +| <<StorageGoogleConfig_CommonObjectReference,StorageGoogleConfig>> +| +| + +| clair +| +| +| <<StorageClairConfig_CommonObjectReference,StorageClairConfig>> +| +| + +| clairV4 +| +| +| <<StorageClairV4Config_CommonObjectReference,StorageClairV4Config>> +| +| + +| ibm +| +| +| <<StorageIBMRegistryConfig_CommonObjectReference,StorageIBMRegistryConfig>> +| +| + +| azure +| +| +| <<StorageAzureConfig_CommonObjectReference,StorageAzureConfig>> +| +| + +| autogenerated +| +| +| Boolean +| +| + +| clusterId +| +| +| String +| +| + +| skipTestIntegration +| +| +| Boolean +| +| + +| source +| +| +| <<StorageImageIntegrationSource_CommonObjectReference,StorageImageIntegrationSource>> +| +| + +|=== + +[id="NodeScanScanner_CommonObjectReference"] +=== NodeScanScanner + +[id="Fields-NodeScanScanner_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| SCANNER +| SCANNER_V4 + +|=== + +[id="NotifierServicePutNotifierBody_CommonObjectReference"] +=== NotifierServicePutNotifierBody + +Next Tag: 21 + +[id="Fields-NotifierServicePutNotifierBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| uiEndpoint +| +| +| String +| +| + +| labelKey +| +| +| String +| +| + +| labelDefault +| +| +| String +| +| + +| jira +| +| +| <<StorageJira_CommonObjectReference,StorageJira>> +| +| + +| email +| +| +| <<StorageEmail_CommonObjectReference,StorageEmail>> +| +| + +| cscc +| +| +| <<StorageCSCC_CommonObjectReference,StorageCSCC>> +| +| + +| splunk +| +| +| <<StorageSplunk_CommonObjectReference,StorageSplunk>> +| +| + +| pagerduty +| +| +| <<StoragePagerDuty_CommonObjectReference,StoragePagerDuty>> +| +| + +| generic +| +| +| <<StorageGeneric_CommonObjectReference,StorageGeneric>> +| +| + +| sumologic +| +| +| <<StorageSumoLogic_CommonObjectReference,StorageSumoLogic>> +| +| + +| awsSecurityHub +| +| +| <<StorageAWSSecurityHub_CommonObjectReference,StorageAWSSecurityHub>> +| +| + +| syslog +| +| +| <<StorageSyslog_CommonObjectReference,StorageSyslog>> +| +| + +| microsoftSentinel +| +| +| <<StorageMicrosoftSentinel_CommonObjectReference,StorageMicrosoftSentinel>> +| +| + +| notifierSecret +| +| +| String +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="NotifierServiceUpdateNotifierBody_CommonObjectReference"] +=== NotifierServiceUpdateNotifierBody + +[id="Fields-NotifierServiceUpdateNotifierBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| notifier +| +| +| <<NextTag21_CommonObjectReference,NextTag21>> +| +| + +| updatePassword +| +| +| Boolean +| When false, use the stored credentials of an existing notifier configuration given its ID. +| + +|=== + +[id="PlatformComponentConfigRule_CommonObjectReference"] +=== PlatformComponentConfigRule + +[id="Fields-PlatformComponentConfigRule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| namespaceRule +| +| +| <<RuleNamespaceRule_CommonObjectReference,RuleNamespaceRule>> +| +| + +|=== + +[id="PodContainerInstanceList_CommonObjectReference"] +=== PodContainerInstanceList + +[id="Fields-PodContainerInstanceList_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| instances +| +| +| List of <<StorageContainerInstance_CommonObjectReference,StorageContainerInstance>> +| +| + +|=== + +[id="PolicyMitreAttackVectors_CommonObjectReference"] +=== PolicyMitreAttackVectors + +[id="Fields-PolicyMitreAttackVectors_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| tactic +| +| +| String +| +| + +| techniques +| +| +| List of `string` +| +| + +|=== + +[id="PolicyServiceEnableDisablePolicyNotificationBody_CommonObjectReference"] +=== PolicyServiceEnableDisablePolicyNotificationBody + +[id="Fields-PolicyServiceEnableDisablePolicyNotificationBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| notifierIds +| +| +| List of `string` +| +| + +| disable +| +| +| Boolean +| +| + +|=== + +[id="PolicyServicePatchPolicyBody_CommonObjectReference"] +=== PolicyServicePatchPolicyBody + +[id="Fields-PolicyServicePatchPolicyBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| disabled +| +| +| Boolean +| +| + +|=== + +[id="PolicyServicePutPolicyBody_CommonObjectReference"] +=== PolicyServicePutPolicyBody + +Next tag: 28 + +[id="Fields-PolicyServicePutPolicyBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| Name of the policy. Must be unique. +| + +| description +| +| +| String +| Free-form text description of this policy. +| + +| rationale +| +| +| String +| +| + +| remediation +| +| +| String +| Describes how to remediate a violation of this policy. +| + +| disabled +| +| +| Boolean +| Toggles whether or not this policy will be executing and actively firing alerts. +| + +| categories +| +| +| List of `string` +| List of categories that this policy falls under. Category names must already exist in Central. +| + +| lifecycleStages +| +| +| List of <<StorageLifecycleStage_CommonObjectReference,StorageLifecycleStage>> +| Describes which policy lifecylce stages this policy applies to. Choices are DEPLOY, BUILD, and RUNTIME. +| + +| eventSource +| +| +| <<StorageEventSource_CommonObjectReference,StorageEventSource>> +| +| NOT_APPLICABLE, DEPLOYMENT_EVENT, AUDIT_LOG_EVENT, + +| exclusions +| +| +| List of <<StorageExclusion_CommonObjectReference,StorageExclusion>> +| Define deployments or images that should be excluded from this policy. +| + +| scope +| +| +| List of <<StorageScope_CommonObjectReference,StorageScope>> +| Defines clusters, namespaces, and deployments that should be included in this policy. No scopes defined includes everything. +| + +| severity +| +| +| <<StorageSeverity_CommonObjectReference,StorageSeverity>> +| +| UNSET_SEVERITY, LOW_SEVERITY, MEDIUM_SEVERITY, HIGH_SEVERITY, CRITICAL_SEVERITY, + +| enforcementActions +| +| +| List of <<StorageEnforcementAction_CommonObjectReference,StorageEnforcementAction>> +| FAIL_DEPLOYMENT_CREATE_ENFORCEMENT takes effect only if admission control webhook is configured to enforce on object creates/updates. FAIL_KUBE_REQUEST_ENFORCEMENT takes effect only if admission control webhook is enabled to listen on exec and port-forward events. FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT takes effect only if admission control webhook is configured to enforce on object updates. Lists the enforcement actions to take when a violation from this policy is identified. Possible value are UNSET_ENFORCEMENT, SCALE_TO_ZERO_ENFORCEMENT, UNSATISFIABLE_NODE_CONSTRAINT_ENFORCEMENT, KILL_POD_ENFORCEMENT, FAIL_BUILD_ENFORCEMENT, FAIL_KUBE_REQUEST_ENFORCEMENT, FAIL_DEPLOYMENT_CREATE_ENFORCEMENT, and. FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT. +| + +| notifiers +| +| +| List of `string` +| List of IDs of the notifiers that should be triggered when a violation from this policy is identified. IDs should be in the form of a UUID and are found through the Central API. +| + +| lastUpdated +| +| +| Date +| +| date-time + +| SORTName +| +| +| String +| For internal use only. +| + +| SORTLifecycleStage +| +| +| String +| For internal use only. +| + +| SORTEnforcement +| +| +| Boolean +| For internal use only. +| + +| policyVersion +| +| +| String +| +| + +| policySections +| +| +| List of <<StoragePolicySection_CommonObjectReference,StoragePolicySection>> +| PolicySections define the violation criteria for this policy. +| + +| mitreAttackVectors +| +| +| List of <<PolicyMitreAttackVectors_CommonObjectReference,PolicyMitreAttackVectors>> +| +| + +| criteriaLocked +| +| +| Boolean +| Read-only field. If true, the policy's criteria fields are rendered read-only. +| + +| mitreVectorsLocked +| +| +| Boolean +| Read-only field. If true, the policy's MITRE ATT&CK fields are rendered read-only. +| + +| isDefault +| +| +| Boolean +| Read-only field. Indicates the policy is a default policy if true and a custom policy if false. +| + +| source +| +| +| <<StoragePolicySource_CommonObjectReference,StoragePolicySource>> +| +| IMPERATIVE, DECLARATIVE, + +|=== + +[id="PortConfigExposureInfo_CommonObjectReference"] +=== PortConfigExposureInfo + +[id="Fields-PortConfigExposureInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| level +| +| +| <<PortConfigExposureLevel_CommonObjectReference,PortConfigExposureLevel>> +| +| UNSET, EXTERNAL, NODE, INTERNAL, HOST, ROUTE, + +| serviceName +| +| +| String +| +| + +| serviceId +| +| +| String +| +| + +| serviceClusterIp +| +| +| String +| +| + +| servicePort +| +| +| Integer +| +| int32 + +| nodePort +| +| +| Integer +| +| int32 + +| externalIps +| +| +| List of `string` +| +| + +| externalHostnames +| +| +| List of `string` +| +| + +|=== + +[id="PortConfigExposureLevel_CommonObjectReference"] +=== PortConfigExposureLevel + +[id="Fields-PortConfigExposureLevel_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| EXTERNAL +| NODE +| INTERNAL +| HOST +| ROUTE + +|=== + +[id="ProcessListeningOnPortEndpoint_CommonObjectReference"] +=== ProcessListeningOnPortEndpoint + +[id="Fields-ProcessListeningOnPortEndpoint_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| port +| +| +| Long +| +| int64 + +| protocol +| +| +| <<StorageL4Protocol_CommonObjectReference,StorageL4Protocol>> +| +| L4_PROTOCOL_UNKNOWN, L4_PROTOCOL_TCP, L4_PROTOCOL_UDP, L4_PROTOCOL_ICMP, L4_PROTOCOL_RAW, L4_PROTOCOL_SCTP, L4_PROTOCOL_ANY, + +|=== + +[id="ProcessSignalLineageInfo_CommonObjectReference"] +=== ProcessSignalLineageInfo + +[id="Fields-ProcessSignalLineageInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| parentUid +| +| +| Long +| +| int64 + +| parentExecFilePath +| +| +| String +| +| + +|=== + +[id="ProtobufAny_CommonObjectReference"] +=== ProtobufAny + +[id="Fields-ProtobufAny_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| @type +| +| +| String +| +| + +|=== + +[id="QuayConfigRobotAccount_CommonObjectReference"] +=== QuayConfigRobotAccount + +Robot account is Quay's named tokens that can be granted permissions on multiple repositories under an organization. It's Quay's recommended authentication model when possible (i.e. registry integration) + +[id="Fields-QuayConfigRobotAccount_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| username +| +| +| String +| +| + +| password +| +| +| String +| The server will mask the value of this password in responses and logs. +| + +|=== + +[id="ReportConfigurationReportType_CommonObjectReference"] +=== ReportConfigurationReportType + +[id="Fields-ReportConfigurationReportType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| VULNERABILITY + +|=== + +[id="ReportConfigurationServiceUpdateReportConfigurationBody_CommonObjectReference"] +=== ReportConfigurationServiceUpdateReportConfigurationBody + +[id="Fields-ReportConfigurationServiceUpdateReportConfigurationBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfig +| +| +| <<StorageReportConfiguration_CommonObjectReference,StorageReportConfiguration>> +| +| + +|=== + +[id="ReportLastRunStatusRunStatus_CommonObjectReference"] +=== ReportLastRunStatusRunStatus + +[id="Fields-ReportLastRunStatusRunStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| SUCCESS +| FAILURE + +|=== + +[id="ReportServiceUpdateReportConfigurationBody_CommonObjectReference"] +=== ReportServiceUpdateReportConfigurationBody + +[id="Fields-ReportServiceUpdateReportConfigurationBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| type +| +| +| <<ReportConfigurationReportType_CommonObjectReference,ReportConfigurationReportType>> +| +| VULNERABILITY, + +| vulnReportFilters +| +| +| <<V2VulnerabilityReportFilters_CommonObjectReference,V2VulnerabilityReportFilters>> +| +| + +| schedule +| +| +| <<V2ReportSchedule_CommonObjectReference,V2ReportSchedule>> +| +| + +| resourceScope +| +| +| <<V2ResourceScope_CommonObjectReference,V2ResourceScope>> +| +| + +| notifiers +| +| +| List of <<V2NotifierConfiguration_CommonObjectReference,V2NotifierConfiguration>> +| +| + +|=== + +[id="RequestExpiryExpiryType_CommonObjectReference"] +=== RequestExpiryExpiryType + +[id="Fields-RequestExpiryExpiryType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| TIME +| ALL_CVE_FIXABLE +| ANY_CVE_FIXABLE + +|=== + +[id="ResourceCollectionEmbeddedResourceCollection_CommonObjectReference"] +=== ResourceCollectionEmbeddedResourceCollection + +[id="Fields-ResourceCollectionEmbeddedResourceCollection_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +|=== + +[id="ResultFactor_CommonObjectReference"] +=== ResultFactor + +[id="Fields-ResultFactor_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| message +| +| +| String +| +| + +| url +| +| +| String +| +| + +|=== + +[id="RoleServicePutPermissionSetBody_CommonObjectReference"] +=== RoleServicePutPermissionSetBody + +This encodes a set of permissions for StackRox resources. + +[id="Fields-RoleServicePutPermissionSetBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| `name` and `description` are provided by the user and can be changed. +| + +| description +| +| +| String +| +| + +| resourceToAccess +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="RoleServicePutSimpleAccessScopeBody_CommonObjectReference"] +=== RoleServicePutSimpleAccessScopeBody + +Simple access scope is a (simple) selection criteria for scoped resources. +It does *not* allow multi-component AND-rules nor set operations on names. + +[id="Fields-RoleServicePutSimpleAccessScopeBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| `name` and `description` are provided by the user and can be changed. +| + +| description +| +| +| String +| +| + +| rules +| +| +| <<SimpleAccessScopeRules_CommonObjectReference,SimpleAccessScopeRules>> +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="RoleServiceUpdateRoleBody_CommonObjectReference"] +=== RoleServiceUpdateRoleBody + +A role specifies which actions are allowed for which subset of cluster +objects. Permissions be can either specified directly via setting +resource_to_access together with global_access or by referencing a +permission set by its id in permission_set_name. + +[id="Fields-RoleServiceUpdateRoleBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| description +| +| +| String +| +| + +| permissionSetId +| +| +| String +| The associated PermissionSet and AccessScope for this Role. +| + +| accessScopeId +| +| +| String +| +| + +| globalAccess +| +| +| <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| NO_ACCESS, READ_ACCESS, READ_WRITE_ACCESS, + +| resourceToAccess +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| Deprecated 2021-04-20 in favor of `permission_set_id`. +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="RpcStatus_CommonObjectReference"] +=== RpcStatus + +[id="Fields-RpcStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| code +| +| +| Integer +| +| int32 + +| message +| +| +| String +| +| + +| details +| +| +| List of <<ProtobufAny_CommonObjectReference,ProtobufAny>> +| +| + +|=== + +[id="RuleNamespaceRule_CommonObjectReference"] +=== RuleNamespaceRule + +[id="Fields-RuleNamespaceRule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| regex +| +| +| String +| +| + +|=== + +[id="SBOMSPDX23Document_CommonObjectReference"] +=== SBOMSPDX23Document + +SPDX 2.3 document, refer to https://spdx.github.io/spdx-spec/v2.3/ for more details. + +[id="Fields-SBOMSPDX23Document_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| spdxVersion +| +| +| String +| +| + +| dataLicense +| +| +| String +| +| + +| SPDXID +| +| +| String +| +| + +| name +| +| +| String +| +| + +| documentNamespace +| +| +| String +| +| + +| creationInfo +| +| +| <<SBOMSPDX23Document_CommonObjectReference,SBOM_SPDX23_Document>> +| +| + +| packages +| +| +| List of <<SBOMSPDX23DocumentPackagesInner_CommonObjectReference,SBOM_SPDX23_Document_packages>> +| +| + +| relationships +| +| +| List of <<SBOMSPDX23DocumentRelationshipsInner_CommonObjectReference,SBOM_SPDX23_Document_relationships>> +| +| + +|=== + +[id="SBOMSPDX23DocumentCreationInfo_CommonObjectReference"] +=== SBOMSPDX23DocumentCreationInfo + +[id="Fields-SBOMSPDX23DocumentCreationInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| created +| +| +| String +| +| + +| creators +| +| +| List of `string` +| +| + +|=== + +[id="SBOMSPDX23DocumentPackagesInner_CommonObjectReference"] +=== SBOMSPDX23DocumentPackagesInner + +[id="Fields-SBOMSPDX23DocumentPackagesInner_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| SPDXID +| +| +| Object +| +| + +| name +| +| +| String +| +| + +| versionInfo +| +| +| String +| +| + +| packageFileName +| +| +| String +| +| + +| downloadLocation +| +| +| String +| +| + +| filesAnalyzed +| +| +| Boolean +| +| + +| primaryPackagePurpose +| +| +| String +| +| + +|=== + +[id="SBOMSPDX23DocumentRelationshipsInner_CommonObjectReference"] +=== SBOMSPDX23DocumentRelationshipsInner + +[id="Fields-SBOMSPDX23DocumentRelationshipsInner_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| spdxElementId +| +| +| String +| +| + +| relatedSpdxElement +| +| +| String +| +| + +| relationshipType +| +| +| String +| +| + +|=== + +[id="ScannerV1Components_CommonObjectReference"] +=== ScannerV1Components + +[id="Fields-ScannerV1Components_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| namespace +| +| +| String +| +| + +| osComponents +| +| +| List of <<ScannerV1OSComponent_CommonObjectReference,ScannerV1OSComponent>> +| +| + +| rhelComponents +| +| +| List of <<ScannerV1RHELComponent_CommonObjectReference,ScannerV1RHELComponent>> +| +| + +| languageComponents +| +| +| List of <<ScannerV1LanguageComponent_CommonObjectReference,ScannerV1LanguageComponent>> +| +| + +| rhelContentSets +| +| +| List of `string` +| +| + +|=== + +[id="ScannerV1Executable_CommonObjectReference"] +=== ScannerV1Executable + +[id="Fields-ScannerV1Executable_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| path +| +| +| String +| +| + +| requiredFeatures +| +| +| List of <<ScannerV1FeatureNameVersion_CommonObjectReference,ScannerV1FeatureNameVersion>> +| +| + +|=== + +[id="ScannerV1FeatureNameVersion_CommonObjectReference"] +=== ScannerV1FeatureNameVersion + +[id="Fields-ScannerV1FeatureNameVersion_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| version +| +| +| String +| +| + +|=== + +[id="ScannerV1JavaComponent_CommonObjectReference"] +=== ScannerV1JavaComponent + +[id="Fields-ScannerV1JavaComponent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| implementationVersion +| +| +| String +| +| + +| mavenVersion +| +| +| String +| +| + +| origins +| +| +| List of `string` +| +| + +| specificationVersion +| +| +| String +| +| + +| bundleName +| +| +| String +| +| + +|=== + +[id="ScannerV1LanguageComponent_CommonObjectReference"] +=== ScannerV1LanguageComponent + +[id="Fields-ScannerV1LanguageComponent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| <<ScannerV1SourceType_CommonObjectReference,ScannerV1SourceType>> +| +| UNSET_SOURCE_TYPE, JAVA, PYTHON, NPM, GEM, DOTNETCORERUNTIME, + +| name +| +| +| String +| +| + +| version +| +| +| String +| +| + +| location +| +| +| String +| +| + +| java +| +| +| <<ScannerV1JavaComponent_CommonObjectReference,ScannerV1JavaComponent>> +| +| + +| python +| +| +| <<ScannerV1PythonComponent_CommonObjectReference,ScannerV1PythonComponent>> +| +| + +| addedBy +| +| +| String +| +| + +|=== + +[id="ScannerV1Note_CommonObjectReference"] +=== ScannerV1Note + +[id="Fields-ScannerV1Note_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| OS_CVES_UNAVAILABLE +| OS_CVES_STALE +| LANGUAGE_CVES_UNAVAILABLE +| CERTIFIED_RHEL_SCAN_UNAVAILABLE + +|=== + +[id="ScannerV1OSComponent_CommonObjectReference"] +=== ScannerV1OSComponent + +[id="Fields-ScannerV1OSComponent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| version +| +| +| String +| +| + +| addedBy +| +| +| String +| +| + +| executables +| +| +| List of <<ScannerV1Executable_CommonObjectReference,ScannerV1Executable>> +| +| + +|=== + +[id="ScannerV1PythonComponent_CommonObjectReference"] +=== ScannerV1PythonComponent + +[id="Fields-ScannerV1PythonComponent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| homepage +| +| +| String +| +| + +| authorEmail +| +| +| String +| +| + +| downloadUrl +| +| +| String +| +| + +| summary +| +| +| String +| +| + +| description +| +| +| String +| +| + +|=== + +[id="ScannerV1RHELComponent_CommonObjectReference"] +=== ScannerV1RHELComponent + +[id="Fields-ScannerV1RHELComponent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| int64 + +| name +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| version +| +| +| String +| +| + +| arch +| +| +| String +| +| + +| module +| +| +| String +| +| + +| cpes +| +| +| List of `string` +| +| + +| addedBy +| +| +| String +| +| + +| executables +| +| +| List of <<ScannerV1Executable_CommonObjectReference,ScannerV1Executable>> +| +| + +|=== + +[id="ScannerV1SourceType_CommonObjectReference"] +=== ScannerV1SourceType + +[id="Fields-ScannerV1SourceType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET_SOURCE_TYPE +| JAVA +| PYTHON +| NPM +| GEM +| DOTNETCORERUNTIME + +|=== + +[id="ScheduleDaysOfMonth_CommonObjectReference"] +=== ScheduleDaysOfMonth + +1 for 1st, 2 for 2nd .... 31 for 31st + +[id="Fields-ScheduleDaysOfMonth_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| days +| +| +| List of `integer` +| +| int32 + +|=== + +[id="ScheduleDaysOfWeek_CommonObjectReference"] +=== ScheduleDaysOfWeek + +Sunday = 0, Monday = 1, .... Saturday = 6 + +[id="Fields-ScheduleDaysOfWeek_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| days +| +| +| List of `integer` +| +| int32 + +|=== + +[id="ScheduleIntervalType_CommonObjectReference"] +=== ScheduleIntervalType + +[id="Fields-ScheduleIntervalType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| DAILY +| WEEKLY +| MONTHLY + +|=== + +[id="ScheduleWeeklyInterval_CommonObjectReference"] +=== ScheduleWeeklyInterval + +[id="Fields-ScheduleWeeklyInterval_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| day +| +| +| Integer +| +| int32 + +|=== + +[id="ScopeImage_CommonObjectReference"] +=== ScopeImage + +[id="Fields-ScopeImage_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| registry +| +| +| String +| +| + +| remote +| +| +| String +| +| + +| tag +| +| +| String +| +| + +|=== + +[id="SearchResponseCount_CommonObjectReference"] +=== SearchResponseCount + +[id="Fields-SearchResponseCount_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| category +| +| +| <<V1SearchCategory_CommonObjectReference,V1SearchCategory>> +| +| SEARCH_UNSET, ALERTS, IMAGES, IMAGE_COMPONENTS, IMAGE_VULN_EDGE, IMAGE_COMPONENT_EDGE, POLICIES, DEPLOYMENTS, ACTIVE_COMPONENT, PODS, SECRETS, PROCESS_INDICATORS, COMPLIANCE, CLUSTERS, NAMESPACES, NODES, NODE_COMPONENTS, NODE_VULN_EDGE, NODE_COMPONENT_EDGE, NODE_COMPONENT_CVE_EDGE, COMPLIANCE_STANDARD, COMPLIANCE_CONTROL_GROUP, COMPLIANCE_CONTROL, SERVICE_ACCOUNTS, ROLES, ROLEBINDINGS, REPORT_CONFIGURATIONS, PROCESS_BASELINES, SUBJECTS, RISKS, VULNERABILITIES, CLUSTER_VULNERABILITIES, IMAGE_VULNERABILITIES, NODE_VULNERABILITIES, COMPONENT_VULN_EDGE, CLUSTER_VULN_EDGE, NETWORK_ENTITY, VULN_REQUEST, NETWORK_BASELINE, NETWORK_POLICIES, PROCESS_BASELINE_RESULTS, COMPLIANCE_METADATA, COMPLIANCE_RESULTS, COMPLIANCE_DOMAIN, CLUSTER_HEALTH, POLICY_CATEGORIES, IMAGE_INTEGRATIONS, COLLECTIONS, POLICY_CATEGORY_EDGE, PROCESS_LISTENING_ON_PORT, API_TOKEN, REPORT_METADATA, REPORT_SNAPSHOT, COMPLIANCE_INTEGRATIONS, COMPLIANCE_SCAN_CONFIG, COMPLIANCE_SCAN, COMPLIANCE_CHECK_RESULTS, BLOB, ADMINISTRATION_EVENTS, COMPLIANCE_SCAN_CONFIG_STATUS, ADMINISTRATION_USAGE, COMPLIANCE_PROFILES, COMPLIANCE_RULES, COMPLIANCE_SCAN_SETTING_BINDINGS, COMPLIANCE_SUITES, CLOUD_SOURCES, DISCOVERED_CLUSTERS, COMPLIANCE_REMEDIATIONS, COMPLIANCE_BENCHMARKS, AUTH_PROVIDERS, COMPLIANCE_REPORT_SNAPSHOT, IMAGE_COMPONENTS_V2, IMAGE_VULNERABILITIES_V2, + +| count +| +| +| String +| +| int64 + +|=== + +[id="SearchResultMatches_CommonObjectReference"] +=== SearchResultMatches + +[id="Fields-SearchResultMatches_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| values +| +| +| List of `string` +| +| + +|=== + +[id="SeccompProfileProfileType_CommonObjectReference"] +=== SeccompProfileProfileType + +[id="Fields-SeccompProfileProfileType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNCONFINED +| RUNTIME_DEFAULT +| LOCALHOST + +|=== + +[id="SecurityContextSELinux_CommonObjectReference"] +=== SecurityContextSELinux + +[id="Fields-SecurityContextSELinux_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| user +| +| +| String +| +| + +| role +| +| +| String +| +| + +| type +| +| +| String +| +| + +| level +| +| +| String +| +| + +|=== + +[id="SecurityContextSeccompProfile_CommonObjectReference"] +=== SecurityContextSeccompProfile + +[id="Fields-SecurityContextSeccompProfile_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| <<SeccompProfileProfileType_CommonObjectReference,SeccompProfileProfileType>> +| +| UNCONFINED, RUNTIME_DEFAULT, LOCALHOST, + +| localhostProfile +| +| +| String +| +| + +|=== + +[id="SignatureIntegrationServicePutSignatureIntegrationBody_CommonObjectReference"] +=== SignatureIntegrationServicePutSignatureIntegrationBody + +[id="Fields-SignatureIntegrationServicePutSignatureIntegrationBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| cosign +| +| +| <<StorageCosignPublicKeyVerification_CommonObjectReference,StorageCosignPublicKeyVerification>> +| +| + +| cosignCertificates +| +| +| List of <<StorageCosignCertificateVerification_CommonObjectReference,StorageCosignCertificateVerification>> +| +| + +| transparencyLog +| +| +| <<StorageTransparencyLogVerification_CommonObjectReference,StorageTransparencyLogVerification>> +| +| + +|=== + +[id="SimpleAccessScopeRules_CommonObjectReference"] +=== SimpleAccessScopeRules + +Each element of any repeated field is an individual rule. Rules are +joined by logical OR: if there exists a rule allowing resource `x`, +`x` is in the access scope. + +[id="Fields-SimpleAccessScopeRules_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| includedClusters +| +| +| List of `string` +| +| + +| includedNamespaces +| +| +| List of <<SimpleAccessScopeRulesNamespace_CommonObjectReference,SimpleAccessScopeRulesNamespace>> +| +| + +| clusterLabelSelectors +| +| +| List of <<StorageSetBasedLabelSelector_CommonObjectReference,StorageSetBasedLabelSelector>> +| +| + +| namespaceLabelSelectors +| +| +| List of <<StorageSetBasedLabelSelector_CommonObjectReference,StorageSetBasedLabelSelector>> +| +| + +|=== + +[id="SimpleAccessScopeRulesNamespace_CommonObjectReference"] +=== SimpleAccessScopeRulesNamespace + +[id="Fields-SimpleAccessScopeRulesNamespace_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterName +| +| +| String +| Both fields must be set. +| + +| namespaceName +| +| +| String +| +| + +|=== + +[id="StorageAWSProviderMetadata_CommonObjectReference"] +=== StorageAWSProviderMetadata + +[id="Fields-StorageAWSProviderMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| accountId +| +| +| String +| +| + +|=== + +[id="StorageAWSSecurityHub_CommonObjectReference"] +=== StorageAWSSecurityHub + +[id="Fields-StorageAWSSecurityHub_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| region +| +| +| String +| +| + +| credentials +| +| +| <<StorageAWSSecurityHubCredentials_CommonObjectReference,StorageAWSSecurityHubCredentials>> +| +| + +| accountId +| +| +| String +| +| + +|=== + +[id="StorageAWSSecurityHubCredentials_CommonObjectReference"] +=== StorageAWSSecurityHubCredentials + +[id="Fields-StorageAWSSecurityHubCredentials_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| accessKeyId +| +| +| String +| +| + +| secretAccessKey +| +| +| String +| +| + +| stsEnabled +| +| +| Boolean +| +| + +|=== + +[id="StorageAccess_CommonObjectReference"] +=== StorageAccess + +[id="Fields-StorageAccess_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| NO_ACCESS +| READ_ACCESS +| READ_WRITE_ACCESS + +|=== + +[id="StorageAdministrationEventsConfig_CommonObjectReference"] +=== StorageAdministrationEventsConfig + +[id="Fields-StorageAdministrationEventsConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| retentionDurationDays +| +| +| Long +| +| int64 + +|=== + +[id="StorageAdmissionControlHealthInfo_CommonObjectReference"] +=== StorageAdmissionControlHealthInfo + +AdmissionControlHealthInfo carries data about admission control deployment but does not include admission control health status +derived from this data. +Aggregated admission control health status is not included because it is derived in central and not in the component that +first reports AdmissionControlHealthInfo (sensor). + +The following fields are made optional/nullable because there can be errors when trying to obtain them and + the default value of 0 might be confusing with the actual value 0. In case an error happens when trying to obtain + a certain field, it will be absent (instead of having the default value). + +[id="Fields-StorageAdmissionControlHealthInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| totalDesiredPods +| +| +| Integer +| +| int32 + +| totalReadyPods +| +| +| Integer +| +| int32 + +| statusErrors +| +| +| List of `string` +| Collection of errors that occurred while trying to obtain admission control health info. +| + +|=== + +[id="StorageAdmissionControllerConfig_CommonObjectReference"] +=== StorageAdmissionControllerConfig + +[id="Fields-StorageAdmissionControllerConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enabled +| +| +| Boolean +| +| + +| timeoutSeconds +| +| +| Integer +| +| int32 + +| scanInline +| +| +| Boolean +| +| + +| disableBypass +| +| +| Boolean +| +| + +| enforceOnUpdates +| +| +| Boolean +| +| + +|=== + +[id="StorageAdvisory_CommonObjectReference"] +=== StorageAdvisory + +[id="Fields-StorageAdvisory_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| link +| +| +| String +| +| + +|=== + +[id="StorageAlert_CommonObjectReference"] +=== StorageAlert + +Next available tag: 24 + +[id="Fields-StorageAlert_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| policy +| +| +| <<StoragePolicy_CommonObjectReference,StoragePolicy>> +| +| + +| lifecycleStage +| +| +| <<StorageLifecycleStage_CommonObjectReference,StorageLifecycleStage>> +| +| DEPLOY, BUILD, RUNTIME, + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| namespaceId +| +| +| String +| +| + +| deployment +| +| +| <<StorageAlertDeployment_CommonObjectReference,StorageAlertDeployment>> +| +| + +| image +| +| +| <<StorageContainerImage_CommonObjectReference,StorageContainerImage>> +| +| + +| resource +| +| +| <<StorageAlertResource_CommonObjectReference,StorageAlertResource>> +| +| + +| violations +| +| +| List of <<AlertViolation_CommonObjectReference,AlertViolation>> +| For run-time phase alert, a maximum of 40 violations are retained. +| + +| processViolation +| +| +| <<AlertProcessViolation_CommonObjectReference,AlertProcessViolation>> +| +| + +| enforcement +| +| +| <<AlertEnforcement_CommonObjectReference,AlertEnforcement>> +| +| + +| time +| +| +| Date +| +| date-time + +| firstOccurred +| +| +| Date +| +| date-time + +| resolvedAt +| +| +| Date +| The time at which the alert was resolved. Only set if ViolationState is RESOLVED. +| date-time + +| state +| +| +| <<StorageViolationState_CommonObjectReference,StorageViolationState>> +| +| ACTIVE, RESOLVED, ATTEMPTED, + +| platformComponent +| +| +| Boolean +| +| + +| entityType +| +| +| <<AlertEntityType_CommonObjectReference,AlertEntityType>> +| +| UNSET, DEPLOYMENT, CONTAINER_IMAGE, RESOURCE, + +|=== + +[id="StorageAlertDeployment_CommonObjectReference"] +=== StorageAlertDeployment + +[id="Fields-StorageAlertDeployment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| namespace +| +| +| String +| This field has to be duplicated in Alert for scope management and search. +| + +| namespaceId +| +| +| String +| This field has to be duplicated in Alert for scope management and search. +| + +| labels +| +| +| Map of `string` +| +| + +| clusterId +| +| +| String +| This field has to be duplicated in Alert for scope management and search. +| + +| clusterName +| +| +| String +| This field has to be duplicated in Alert for scope management and search. +| + +| containers +| +| +| List of <<AlertDeploymentContainer_CommonObjectReference,AlertDeploymentContainer>> +| +| + +| annotations +| +| +| Map of `string` +| +| + +| inactive +| +| +| Boolean +| +| + +|=== + +[id="StorageAlertResource_CommonObjectReference"] +=== StorageAlertResource + +Represents an alert on a kubernetes resource other than a deployment (configmaps, secrets, etc.) + +[id="Fields-StorageAlertResource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| resourceType +| +| +| <<AlertResourceResourceType_CommonObjectReference,AlertResourceResourceType>> +| +| UNKNOWN, SECRETS, CONFIGMAPS, CLUSTER_ROLES, CLUSTER_ROLE_BINDINGS, NETWORK_POLICIES, SECURITY_CONTEXT_CONSTRAINTS, EGRESS_FIREWALLS, + +| name +| +| +| String +| +| + +| clusterId +| +| +| String +| This field has to be duplicated in Alert for scope management and search. +| + +| clusterName +| +| +| String +| This field has to be duplicated in Alert for scope management and search. +| + +| namespace +| +| +| String +| This field has to be duplicated in Alert for scope management and search. +| + +| namespaceId +| +| +| String +| This field has to be duplicated in Alert for scope management and search. +| + +|=== + +[id="StorageAlertRetentionConfig_CommonObjectReference"] +=== StorageAlertRetentionConfig + +[id="Fields-StorageAlertRetentionConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| resolvedDeployRetentionDurationDays +| +| +| Integer +| +| int32 + +| deletedRuntimeRetentionDurationDays +| +| +| Integer +| This runtime alert retention configuration takes precedence after `allRuntimeRetentionDurationDays`. +| int32 + +| allRuntimeRetentionDurationDays +| +| +| Integer +| This runtime alert retention configuration has highest precedence. All runtime alerts, including attempted alerts and deleted deployment alerts, are deleted even if respective retention is longer. +| int32 + +| attemptedDeployRetentionDurationDays +| +| +| Integer +| +| int32 + +| attemptedRuntimeRetentionDurationDays +| +| +| Integer +| This runtime alert retention configuration has lowest precedence. +| int32 + +|=== + +[id="StorageApprover_CommonObjectReference"] +=== StorageApprover + +[id="Fields-StorageApprover_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +|=== + +[id="StorageAuditLogFileState_CommonObjectReference"] +=== StorageAuditLogFileState + +AuditLogFileState tracks the last audit log event timestamp and ID that was collected by Compliance For internal use only + +[id="Fields-StorageAuditLogFileState_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| collectLogsSince +| +| +| Date +| +| date-time + +| lastAuditId +| +| +| String +| +| + +|=== + +[id="StorageAuthProvider_CommonObjectReference"] +=== StorageAuthProvider + +Next Tag: 15. + +[id="Fields-StorageAuthProvider_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| uiEndpoint +| +| +| String +| +| + +| enabled +| +| +| Boolean +| +| + +| config +| +| +| Map of `string` +| Config holds auth provider specific configuration. Each configuration options are different based on the given auth provider type. OIDC: - "issuer": the OIDC issuer according to https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier. - "client_id": the client ID according to https://www.rfc-editor.org/rfc/rfc6749.html#section-2.2. - "client_secret": the client secret according to https://www.rfc-editor.org/rfc/rfc6749.html#section-2.3.1. - "do_not_use_client_secret": set to "true" if you want to create a configuration with only a client ID and no client secret. - "mode": the OIDC callback mode, choosing from "fragment", "post", or "query". - "disable_offline_access_scope": set to "true" if no offline tokens shall be issued. - "extra_scopes": a space-delimited string of additional scopes to request in addition to "openid profile email" according to https://www.rfc-editor.org/rfc/rfc6749.html#section-3.3. OpenShift Auth: supports no extra configuration options. User PKI: - "keys": the trusted certificates PEM encoded. SAML: - "sp_issuer": the service provider issuer according to https://datatracker.ietf.org/doc/html/rfc7522#section-3. - "idp_metadata_url": the metadata URL according to https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf. - "idp_issuer": the IdP issuer. - "idp_cert_pem": the cert PEM encoded for the IdP endpoint. - "idp_sso_url": the IdP SSO URL. - "idp_nameid_format": the IdP name ID format. IAP: - "audience": the audience to use. +| + +| loginUrl +| +| +| String +| The login URL will be provided by the backend, and may not be specified in a request. +| + +| validated +| +| +| Boolean +| +| + +| extraUiEndpoints +| +| +| List of `string` +| UI endpoints which to allow in addition to `ui_endpoint`. I.e., if a login request is coming from any of these, the auth request will use these for the callback URL, not ui_endpoint. +| + +| active +| +| +| Boolean +| +| + +| requiredAttributes +| +| +| List of <<AuthProviderRequiredAttribute_CommonObjectReference,AuthProviderRequiredAttribute>> +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +| claimMappings +| +| +| Map of `string` +| Specifies claims from IdP token that will be copied to Rox token attributes. Each key in this map contains a path in IdP token we want to map. Path is separated by "." symbol. For example, if IdP token payload looks like: { "a": { "b" : "c", "d": true, "e": [ "val1", "val2", "val3" ], "f": [ true, false, false ], "g": 123.0, "h": [ 1, 2, 3] } } then "a.b" would be a valid key and "a.z" is not. We support the following types of claims: * string(path "a.b") * bool(path "a.d") * string array(path "a.e") * bool array (path "a.f.") We do NOT support the following types of claims: * complex claims(path "a") * float/integer claims(path "a.g") * float/integer array claims(path "a.h") Each value in this map contains a Rox token attribute name we want to add claim to. If, for example, value is "groups", claim would be found in "external_user.Attributes.groups" in token. Note: we only support this feature for OIDC auth provider. +| + +| lastUpdated +| +| +| Date +| Last updated indicates the last time the auth provider has been updated. In case there have been tokens issued by an auth provider _before_ this timestamp, they will be considered invalid. Subsequently, all clients will have to re-issue their tokens (either by refreshing or by an additional login attempt). +| date-time + +|=== + +[id="StorageAzureConfig_CommonObjectReference"] +=== StorageAzureConfig + +Azure container registry configuration. Used by integrations of type "azure". + +[id="Fields-StorageAzureConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| username +| +| +| String +| +| + +| password +| +| +| String +| The password for the integration. The server will mask the value of this credential in responses and logs. +| + +| wifEnabled +| +| +| Boolean +| Enables authentication with short-lived tokens using Azure managed identities or Azure workload identities. +| + +|=== + +[id="StorageAzureProviderMetadata_CommonObjectReference"] +=== StorageAzureProviderMetadata + +[id="Fields-StorageAzureProviderMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| subscriptionId +| +| +| String +| +| + +|=== + +[id="StorageBackupInfo_CommonObjectReference"] +=== StorageBackupInfo + +[id="Fields-StorageBackupInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| backupLastRunAt +| +| +| Date +| +| date-time + +| status +| +| +| <<StorageOperationStatus_CommonObjectReference,StorageOperationStatus>> +| +| FAIL, PASS, + +| requestor +| +| +| <<StorageSlimUser_CommonObjectReference,StorageSlimUser>> +| +| + +|=== + +[id="StorageBannerConfig_CommonObjectReference"] +=== StorageBannerConfig + +[id="Fields-StorageBannerConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enabled +| +| +| Boolean +| +| + +| text +| +| +| String +| +| + +| size +| +| +| <<BannerConfigSize_CommonObjectReference,BannerConfigSize>> +| +| UNSET, SMALL, MEDIUM, LARGE, + +| color +| +| +| String +| +| + +| backgroundColor +| +| +| String +| +| + +|=== + +[id="StorageBaselineElement_CommonObjectReference"] +=== StorageBaselineElement + +[id="Fields-StorageBaselineElement_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| element +| +| +| <<StorageBaselineItem_CommonObjectReference,StorageBaselineItem>> +| +| + +| auto +| +| +| Boolean +| +| + +|=== + +[id="StorageBaselineItem_CommonObjectReference"] +=== StorageBaselineItem + +[id="Fields-StorageBaselineItem_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| processName +| +| +| String +| +| + +|=== + +[id="StorageBooleanOperator_CommonObjectReference"] +=== StorageBooleanOperator + +[id="Fields-StorageBooleanOperator_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| OR +| AND + +|=== + +[id="StorageCSCC_CommonObjectReference"] +=== StorageCSCC + +[id="Fields-StorageCSCC_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| serviceAccount +| +| +| String +| The service account for the integration. The server will mask the value of this credential in responses and logs. +| + +| sourceId +| +| +| String +| +| + +| wifEnabled +| +| +| Boolean +| +| + +|=== + +[id="StorageCVEInfo_CommonObjectReference"] +=== StorageCVEInfo + +[id="Fields-StorageCVEInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cve +| +| +| String +| +| + +| summary +| +| +| String +| +| + +| link +| +| +| String +| +| + +| publishedOn +| +| +| Date +| This indicates the timestamp when the cve was first published in the cve feeds. +| date-time + +| createdAt +| +| +| Date +| Time when the CVE was first seen in the system. +| date-time + +| lastModified +| +| +| Date +| +| date-time + +| scoreVersion +| +| +| <<StorageCVEInfoScoreVersion_CommonObjectReference,StorageCVEInfoScoreVersion>> +| +| V2, V3, UNKNOWN, + +| cvssV2 +| +| +| <<StorageCVSSV2_CommonObjectReference,StorageCVSSV2>> +| +| + +| cvssV3 +| +| +| <<StorageCVSSV3_CommonObjectReference,StorageCVSSV3>> +| +| + +| references +| +| +| List of <<StorageCVEInfoReference_CommonObjectReference,StorageCVEInfoReference>> +| +| + +| cvssMetrics +| +| +| List of <<StorageCVSSScore_CommonObjectReference,StorageCVSSScore>> +| +| + +| epss +| +| +| <<StorageEPSS_CommonObjectReference,StorageEPSS>> +| +| + +|=== + +[id="StorageCVEInfoReference_CommonObjectReference"] +=== StorageCVEInfoReference + +[id="Fields-StorageCVEInfoReference_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| URI +| +| +| String +| +| + +| tags +| +| +| List of `string` +| +| + +|=== + +[id="StorageCVEInfoScoreVersion_CommonObjectReference"] +=== StorageCVEInfoScoreVersion + +ScoreVersion can be deprecated ROX-26066 + +- V2: No unset for automatic backwards compatibility + +[id="Fields-StorageCVEInfoScoreVersion_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| V2 +| V3 +| UNKNOWN + +|=== + +[id="StorageCVSSScore_CommonObjectReference"] +=== StorageCVSSScore + +[id="Fields-StorageCVSSScore_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| source +| +| +| <<StorageSource_CommonObjectReference,StorageSource>> +| +| SOURCE_UNKNOWN, SOURCE_RED_HAT, SOURCE_OSV, SOURCE_NVD, + +| url +| +| +| String +| +| + +| cvssv2 +| +| +| <<StorageCVSSV2_CommonObjectReference,StorageCVSSV2>> +| +| + +| cvssv3 +| +| +| <<StorageCVSSV3_CommonObjectReference,StorageCVSSV3>> +| +| + +|=== + +[id="StorageCVSSV2_CommonObjectReference"] +=== StorageCVSSV2 + +[id="Fields-StorageCVSSV2_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| vector +| +| +| String +| +| + +| attackVector +| +| +| <<StorageCVSSV2AttackVector_CommonObjectReference,StorageCVSSV2AttackVector>> +| +| ATTACK_LOCAL, ATTACK_ADJACENT, ATTACK_NETWORK, + +| accessComplexity +| +| +| <<CVSSV2AccessComplexity_CommonObjectReference,CVSSV2AccessComplexity>> +| +| ACCESS_HIGH, ACCESS_MEDIUM, ACCESS_LOW, + +| authentication +| +| +| <<CVSSV2Authentication_CommonObjectReference,CVSSV2Authentication>> +| +| AUTH_MULTIPLE, AUTH_SINGLE, AUTH_NONE, + +| confidentiality +| +| +| <<StorageCVSSV2Impact_CommonObjectReference,StorageCVSSV2Impact>> +| +| IMPACT_NONE, IMPACT_PARTIAL, IMPACT_COMPLETE, + +| integrity +| +| +| <<StorageCVSSV2Impact_CommonObjectReference,StorageCVSSV2Impact>> +| +| IMPACT_NONE, IMPACT_PARTIAL, IMPACT_COMPLETE, + +| availability +| +| +| <<StorageCVSSV2Impact_CommonObjectReference,StorageCVSSV2Impact>> +| +| IMPACT_NONE, IMPACT_PARTIAL, IMPACT_COMPLETE, + +| exploitabilityScore +| +| +| Float +| +| float + +| impactScore +| +| +| Float +| +| float + +| score +| +| +| Float +| +| float + +| severity +| +| +| <<StorageCVSSV2Severity_CommonObjectReference,StorageCVSSV2Severity>> +| +| UNKNOWN, LOW, MEDIUM, HIGH, + +|=== + +[id="StorageCVSSV2AttackVector_CommonObjectReference"] +=== StorageCVSSV2AttackVector + +[id="Fields-StorageCVSSV2AttackVector_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ATTACK_LOCAL +| ATTACK_ADJACENT +| ATTACK_NETWORK + +|=== + +[id="StorageCVSSV2Impact_CommonObjectReference"] +=== StorageCVSSV2Impact + +[id="Fields-StorageCVSSV2Impact_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| IMPACT_NONE +| IMPACT_PARTIAL +| IMPACT_COMPLETE + +|=== + +[id="StorageCVSSV2Severity_CommonObjectReference"] +=== StorageCVSSV2Severity + +[id="Fields-StorageCVSSV2Severity_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| LOW +| MEDIUM +| HIGH + +|=== + +[id="StorageCVSSV3_CommonObjectReference"] +=== StorageCVSSV3 + +[id="Fields-StorageCVSSV3_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| vector +| +| +| String +| +| + +| exploitabilityScore +| +| +| Float +| +| float + +| impactScore +| +| +| Float +| +| float + +| attackVector +| +| +| <<StorageCVSSV3AttackVector_CommonObjectReference,StorageCVSSV3AttackVector>> +| +| ATTACK_LOCAL, ATTACK_ADJACENT, ATTACK_NETWORK, ATTACK_PHYSICAL, + +| attackComplexity +| +| +| <<CVSSV3Complexity_CommonObjectReference,CVSSV3Complexity>> +| +| COMPLEXITY_LOW, COMPLEXITY_HIGH, + +| privilegesRequired +| +| +| <<CVSSV3Privileges_CommonObjectReference,CVSSV3Privileges>> +| +| PRIVILEGE_NONE, PRIVILEGE_LOW, PRIVILEGE_HIGH, + +| userInteraction +| +| +| <<CVSSV3UserInteraction_CommonObjectReference,CVSSV3UserInteraction>> +| +| UI_NONE, UI_REQUIRED, + +| scope +| +| +| <<StorageCVSSV3Scope_CommonObjectReference,StorageCVSSV3Scope>> +| +| UNCHANGED, CHANGED, + +| confidentiality +| +| +| <<StorageCVSSV3Impact_CommonObjectReference,StorageCVSSV3Impact>> +| +| IMPACT_NONE, IMPACT_LOW, IMPACT_HIGH, + +| integrity +| +| +| <<StorageCVSSV3Impact_CommonObjectReference,StorageCVSSV3Impact>> +| +| IMPACT_NONE, IMPACT_LOW, IMPACT_HIGH, + +| availability +| +| +| <<StorageCVSSV3Impact_CommonObjectReference,StorageCVSSV3Impact>> +| +| IMPACT_NONE, IMPACT_LOW, IMPACT_HIGH, + +| score +| +| +| Float +| +| float + +| severity +| +| +| <<StorageCVSSV3Severity_CommonObjectReference,StorageCVSSV3Severity>> +| +| UNKNOWN, NONE, LOW, MEDIUM, HIGH, CRITICAL, + +|=== + +[id="StorageCVSSV3AttackVector_CommonObjectReference"] +=== StorageCVSSV3AttackVector + +[id="Fields-StorageCVSSV3AttackVector_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ATTACK_LOCAL +| ATTACK_ADJACENT +| ATTACK_NETWORK +| ATTACK_PHYSICAL + +|=== + +[id="StorageCVSSV3Impact_CommonObjectReference"] +=== StorageCVSSV3Impact + +[id="Fields-StorageCVSSV3Impact_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| IMPACT_NONE +| IMPACT_LOW +| IMPACT_HIGH + +|=== + +[id="StorageCVSSV3Scope_CommonObjectReference"] +=== StorageCVSSV3Scope + +[id="Fields-StorageCVSSV3Scope_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNCHANGED +| CHANGED + +|=== + +[id="StorageCVSSV3Severity_CommonObjectReference"] +=== StorageCVSSV3Severity + +[id="Fields-StorageCVSSV3Severity_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| NONE +| LOW +| MEDIUM +| HIGH +| CRITICAL + +|=== + +[id="StorageCert_CommonObjectReference"] +=== StorageCert + +[id="Fields-StorageCert_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| subject +| +| +| <<StorageCertName_CommonObjectReference,StorageCertName>> +| +| + +| issuer +| +| +| <<StorageCertName_CommonObjectReference,StorageCertName>> +| +| + +| sans +| +| +| List of `string` +| +| + +| startDate +| +| +| Date +| +| date-time + +| endDate +| +| +| Date +| +| date-time + +| algorithm +| +| +| String +| +| + +|=== + +[id="StorageCertName_CommonObjectReference"] +=== StorageCertName + +[id="Fields-StorageCertName_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| commonName +| +| +| String +| +| + +| country +| +| +| String +| +| + +| organization +| +| +| String +| +| + +| organizationUnit +| +| +| String +| +| + +| locality +| +| +| String +| +| + +| province +| +| +| String +| +| + +| streetAddress +| +| +| String +| +| + +| postalCode +| +| +| String +| +| + +| names +| +| +| List of `string` +| +| + +|=== + +[id="StorageCertificateTransparencyLogVerification_CommonObjectReference"] +=== StorageCertificateTransparencyLogVerification + +Validate that the signature certificate contains a signed +certificate timestamp as proof of inclusion into the certificate +transparency log. + +[id="Fields-StorageCertificateTransparencyLogVerification_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enabled +| +| +| Boolean +| Validate the inclusion of certificates into a certificate transparency log. Disables validation if not enabled. +| + +| publicKeyPemEnc +| +| +| String +| PEM encoded public key used to validate the proof of inclusion into the certificate transparency log. Defaults to the key of the public Sigstore instance if left empty. +| + +|=== + +[id="StorageClairConfig_CommonObjectReference"] +=== StorageClairConfig + +[id="Fields-StorageClairConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| insecure +| +| +| Boolean +| +| + +|=== + +[id="StorageClairV4Config_CommonObjectReference"] +=== StorageClairV4Config + +[id="Fields-StorageClairV4Config_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| insecure +| +| +| Boolean +| +| + +|=== + +[id="StorageClairifyConfig_CommonObjectReference"] +=== StorageClairifyConfig + +[id="Fields-StorageClairifyConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| grpcEndpoint +| +| +| String +| +| + +| numConcurrentScans +| +| +| Integer +| +| int32 + +|=== + +[id="StorageCluster_CommonObjectReference"] +=== StorageCluster + +[id="Fields-StorageCluster_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| <<StorageClusterType_CommonObjectReference,StorageClusterType>> +| +| GENERIC_CLUSTER, KUBERNETES_CLUSTER, OPENSHIFT_CLUSTER, OPENSHIFT4_CLUSTER, + +| labels +| +| +| Map of `string` +| +| + +| mainImage +| +| +| String +| +| + +| collectorImage +| +| +| String +| +| + +| centralApiEndpoint +| +| +| String +| +| + +| runtimeSupport +| +| +| Boolean +| +| + +| collectionMethod +| +| +| <<StorageCollectionMethod_CommonObjectReference,StorageCollectionMethod>> +| +| UNSET_COLLECTION, NO_COLLECTION, KERNEL_MODULE, EBPF, CORE_BPF, + +| admissionController +| +| +| Boolean +| +| + +| admissionControllerUpdates +| +| +| Boolean +| +| + +| admissionControllerEvents +| +| +| Boolean +| +| + +| status +| +| +| <<StorageClusterStatus_CommonObjectReference,StorageClusterStatus>> +| +| + +| dynamicConfig +| +| +| <<StorageDynamicClusterConfig_CommonObjectReference,StorageDynamicClusterConfig>> +| +| + +| tolerationsConfig +| +| +| <<StorageTolerationsConfig_CommonObjectReference,StorageTolerationsConfig>> +| +| + +| priority +| +| +| String +| +| int64 + +| healthStatus +| +| +| <<StorageClusterHealthStatus_CommonObjectReference,StorageClusterHealthStatus>> +| +| + +| slimCollector +| +| +| Boolean +| +| + +| helmConfig +| +| +| <<StorageCompleteClusterConfig_CommonObjectReference,StorageCompleteClusterConfig>> +| +| + +| mostRecentSensorId +| +| +| <<StorageSensorDeploymentIdentification_CommonObjectReference,StorageSensorDeploymentIdentification>> +| +| + +| auditLogState +| +| +| Map of <<StorageAuditLogFileState_CommonObjectReference,StorageAuditLogFileState>> +| For internal use only. +| + +| initBundleId +| +| +| String +| +| + +| managedBy +| +| +| <<StorageManagerType_CommonObjectReference,StorageManagerType>> +| +| MANAGER_TYPE_UNKNOWN, MANAGER_TYPE_MANUAL, MANAGER_TYPE_HELM_CHART, MANAGER_TYPE_KUBERNETES_OPERATOR, + +| sensorCapabilities +| +| +| List of `string` +| +| + +|=== + +[id="StorageClusterCertExpiryStatus_CommonObjectReference"] +=== StorageClusterCertExpiryStatus + +[id="Fields-StorageClusterCertExpiryStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| sensorCertExpiry +| +| +| Date +| +| date-time + +| sensorCertNotBefore +| +| +| Date +| +| date-time + +|=== + +[id="StorageClusterHealthStatus_CommonObjectReference"] +=== StorageClusterHealthStatus + +[id="Fields-StorageClusterHealthStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| collectorHealthInfo +| +| +| <<StorageCollectorHealthInfo_CommonObjectReference,StorageCollectorHealthInfo>> +| +| + +| admissionControlHealthInfo +| +| +| <<StorageAdmissionControlHealthInfo_CommonObjectReference,StorageAdmissionControlHealthInfo>> +| +| + +| scannerHealthInfo +| +| +| <<StorageScannerHealthInfo_CommonObjectReference,StorageScannerHealthInfo>> +| +| + +| sensorHealthStatus +| +| +| <<ClusterHealthStatusHealthStatusLabel_CommonObjectReference,ClusterHealthStatusHealthStatusLabel>> +| +| UNINITIALIZED, UNAVAILABLE, UNHEALTHY, DEGRADED, HEALTHY, + +| collectorHealthStatus +| +| +| <<ClusterHealthStatusHealthStatusLabel_CommonObjectReference,ClusterHealthStatusHealthStatusLabel>> +| +| UNINITIALIZED, UNAVAILABLE, UNHEALTHY, DEGRADED, HEALTHY, + +| overallHealthStatus +| +| +| <<ClusterHealthStatusHealthStatusLabel_CommonObjectReference,ClusterHealthStatusHealthStatusLabel>> +| +| UNINITIALIZED, UNAVAILABLE, UNHEALTHY, DEGRADED, HEALTHY, + +| admissionControlHealthStatus +| +| +| <<ClusterHealthStatusHealthStatusLabel_CommonObjectReference,ClusterHealthStatusHealthStatusLabel>> +| +| UNINITIALIZED, UNAVAILABLE, UNHEALTHY, DEGRADED, HEALTHY, + +| scannerHealthStatus +| +| +| <<ClusterHealthStatusHealthStatusLabel_CommonObjectReference,ClusterHealthStatusHealthStatusLabel>> +| +| UNINITIALIZED, UNAVAILABLE, UNHEALTHY, DEGRADED, HEALTHY, + +| lastContact +| +| +| Date +| For sensors not having health capability, this will be filled with gRPC connection poll. Otherwise, this timestamp will be updated by central pipeline when message is processed. Note: we use this setting to guard against a specific attack vector during CRS-based cluster registration. Assuming that a CRS was used to register a cluster A and the CRS is leaked, an attacker shall not be able to re-run the CRS-flow which would then equip the attacker with a certificate & key issued to the cluster A. As countermeasure we only allow re-running the CRS-flow only as long as the last_contact field is empty, indicating that the legit cluster A's sensor has not yet connected with the CRS-issued service certificates. +| date-time + +| healthInfoComplete +| +| +| Boolean +| +| + +|=== + +[id="StorageClusterMetadata_CommonObjectReference"] +=== StorageClusterMetadata + +ClusterMetadata contains metadata information about the cluster infrastructure. + +[id="Fields-StorageClusterMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| <<StorageClusterMetadataType_CommonObjectReference,StorageClusterMetadataType>> +| +| UNSPECIFIED, AKS, ARO, EKS, GKE, OCP, OSD, ROSA, + +| name +| +| +| String +| Name represents the name under which the cluster is registered with the cloud provider. In case of self managed OpenShift it is the name chosen by the OpenShift installer. +| + +| id +| +| +| String +| Id represents a unique ID under which the cluster is registered with the cloud provider. Not all cluster types have an id. For all OpenShift clusters, this is the Red Hat `cluster_id` registered with OCM. +| + +|=== + +[id="StorageClusterMetadataType_CommonObjectReference"] +=== StorageClusterMetadataType + +[id="Fields-StorageClusterMetadataType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSPECIFIED +| AKS +| ARO +| EKS +| GKE +| OCP +| OSD +| ROSA + +|=== + +[id="StorageClusterStatus_CommonObjectReference"] +=== StorageClusterStatus + +[id="Fields-StorageClusterStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| sensorVersion +| +| +| String +| +| + +| DEPRECATEDLastContact +| +| +| Date +| This field has been deprecated starting release 49.0. Use healthStatus.lastContact instead. +| date-time + +| providerMetadata +| +| +| <<StorageProviderMetadata_CommonObjectReference,StorageProviderMetadata>> +| +| + +| orchestratorMetadata +| +| +| <<StorageOrchestratorMetadata_CommonObjectReference,StorageOrchestratorMetadata>> +| +| + +| upgradeStatus +| +| +| <<StorageClusterUpgradeStatus_CommonObjectReference,StorageClusterUpgradeStatus>> +| +| + +| certExpiryStatus +| +| +| <<StorageClusterCertExpiryStatus_CommonObjectReference,StorageClusterCertExpiryStatus>> +| +| + +|=== + +[id="StorageClusterType_CommonObjectReference"] +=== StorageClusterType + +[id="Fields-StorageClusterType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| GENERIC_CLUSTER +| KUBERNETES_CLUSTER +| OPENSHIFT_CLUSTER +| OPENSHIFT4_CLUSTER + +|=== + +[id="StorageClusterUpgradeStatus_CommonObjectReference"] +=== StorageClusterUpgradeStatus + +[id="Fields-StorageClusterUpgradeStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| upgradability +| +| +| <<ClusterUpgradeStatusUpgradability_CommonObjectReference,ClusterUpgradeStatusUpgradability>> +| +| UNSET, UP_TO_DATE, MANUAL_UPGRADE_REQUIRED, AUTO_UPGRADE_POSSIBLE, SENSOR_VERSION_HIGHER, + +| upgradabilityStatusReason +| +| +| String +| +| + +| mostRecentProcess +| +| +| <<ClusterUpgradeStatusUpgradeProcessStatus_CommonObjectReference,ClusterUpgradeStatusUpgradeProcessStatus>> +| +| + +|=== + +[id="StorageCollectionMethod_CommonObjectReference"] +=== StorageCollectionMethod + +[id="Fields-StorageCollectionMethod_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET_COLLECTION +| NO_COLLECTION +| KERNEL_MODULE +| EBPF +| CORE_BPF + +|=== + +[id="StorageCollectorHealthInfo_CommonObjectReference"] +=== StorageCollectorHealthInfo + +CollectorHealthInfo carries data about collector deployment but does not include collector health status derived from this data. +Aggregated collector health status is not included because it is derived in central and not in the component that +first reports CollectorHealthInfo (sensor). + +[id="Fields-StorageCollectorHealthInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| version +| +| +| String +| +| + +| totalDesiredPods +| +| +| Integer +| +| int32 + +| totalReadyPods +| +| +| Integer +| +| int32 + +| totalRegisteredNodes +| +| +| Integer +| +| int32 + +| statusErrors +| +| +| List of `string` +| Collection of errors that occurred while trying to obtain collector health info. +| + +|=== + +[id="StorageCompleteClusterConfig_CommonObjectReference"] +=== StorageCompleteClusterConfig + +Encodes a complete cluster configuration minus ID/Name identifiers +including static and dynamic settings. + +[id="Fields-StorageCompleteClusterConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| dynamicConfig +| +| +| <<StorageDynamicClusterConfig_CommonObjectReference,StorageDynamicClusterConfig>> +| +| + +| staticConfig +| +| +| <<StorageStaticClusterConfig_CommonObjectReference,StorageStaticClusterConfig>> +| +| + +| configFingerprint +| +| +| String +| +| + +| clusterLabels +| +| +| Map of `string` +| +| + +|=== + +[id="StorageComplianceAggregationResponse_CommonObjectReference"] +=== StorageComplianceAggregationResponse + +Next available tag: 3 + +[id="Fields-StorageComplianceAggregationResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| results +| +| +| List of <<StorageComplianceAggregationResult_CommonObjectReference,StorageComplianceAggregationResult>> +| +| + +| sources +| +| +| List of <<StorageComplianceAggregationSource_CommonObjectReference,StorageComplianceAggregationSource>> +| +| + +| errorMessage +| +| +| String +| +| + +|=== + +[id="StorageComplianceAggregationResult_CommonObjectReference"] +=== StorageComplianceAggregationResult + +Next available tag: 5 + +[id="Fields-StorageComplianceAggregationResult_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| aggregationKeys +| +| +| List of <<ComplianceAggregationAggregationKey_CommonObjectReference,ComplianceAggregationAggregationKey>> +| +| + +| unit +| +| +| <<StorageComplianceAggregationScope_CommonObjectReference,StorageComplianceAggregationScope>> +| +| UNKNOWN, STANDARD, CLUSTER, CATEGORY, CONTROL, NAMESPACE, NODE, DEPLOYMENT, CHECK, + +| numPassing +| +| +| Integer +| +| int32 + +| numFailing +| +| +| Integer +| +| int32 + +| numSkipped +| +| +| Integer +| +| int32 + +|=== + +[id="StorageComplianceAggregationScope_CommonObjectReference"] +=== StorageComplianceAggregationScope + +[id="Fields-StorageComplianceAggregationScope_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| STANDARD +| CLUSTER +| CATEGORY +| CONTROL +| NAMESPACE +| NODE +| DEPLOYMENT +| CHECK + +|=== + +[id="StorageComplianceAggregationSource_CommonObjectReference"] +=== StorageComplianceAggregationSource + +Next available tag: 5 + +[id="Fields-StorageComplianceAggregationSource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| standardId +| +| +| String +| +| + +| successfulRun +| +| +| <<StorageComplianceRunMetadata_CommonObjectReference,StorageComplianceRunMetadata>> +| +| + +| failedRuns +| +| +| List of <<StorageComplianceRunMetadata_CommonObjectReference,StorageComplianceRunMetadata>> +| +| + +|=== + +[id="StorageComplianceDomain_CommonObjectReference"] +=== StorageComplianceDomain + +Next available tag: 5 + +[id="Fields-StorageComplianceDomain_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| cluster +| +| +| <<StorageComplianceDomainCluster_CommonObjectReference,StorageComplianceDomainCluster>> +| +| + +| nodes +| +| +| Map of <<StorageComplianceDomainNode_CommonObjectReference,StorageComplianceDomainNode>> +| +| + +| deployments +| +| +| Map of <<StorageComplianceDomainDeployment_CommonObjectReference,StorageComplianceDomainDeployment>> +| +| + +|=== + +[id="StorageComplianceDomainCluster_CommonObjectReference"] +=== StorageComplianceDomainCluster + +These must mirror the tags _exactly_ in cluster.proto for backwards compatibility + +[id="Fields-StorageComplianceDomainCluster_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +|=== + +[id="StorageComplianceDomainDeployment_CommonObjectReference"] +=== StorageComplianceDomainDeployment + +This must mirror the tags _exactly_ in deployment.proto for backwards compatibility + +[id="Fields-StorageComplianceDomainDeployment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| namespaceId +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +|=== + +[id="StorageComplianceDomainNode_CommonObjectReference"] +=== StorageComplianceDomainNode + +These must mirror the tags _exactly_ in node.proto for backwards compatibility + +[id="Fields-StorageComplianceDomainNode_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +|=== + +[id="StorageComplianceResultValue_CommonObjectReference"] +=== StorageComplianceResultValue + +[id="Fields-StorageComplianceResultValue_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| evidence +| +| +| List of <<ComplianceResultValueEvidence_CommonObjectReference,ComplianceResultValueEvidence>> +| +| + +| overallState +| +| +| <<StorageComplianceState_CommonObjectReference,StorageComplianceState>> +| +| COMPLIANCE_STATE_UNKNOWN, COMPLIANCE_STATE_SKIP, COMPLIANCE_STATE_NOTE, COMPLIANCE_STATE_SUCCESS, COMPLIANCE_STATE_FAILURE, COMPLIANCE_STATE_ERROR, + +|=== + +[id="StorageComplianceRunMetadata_CommonObjectReference"] +=== StorageComplianceRunMetadata + +Next available tag: 5 + +[id="Fields-StorageComplianceRunMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| runId +| +| +| String +| +| + +| standardId +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| startTimestamp +| +| +| Date +| +| date-time + +| finishTimestamp +| +| +| Date +| +| date-time + +| success +| +| +| Boolean +| +| + +| errorMessage +| +| +| String +| +| + +| domainId +| +| +| String +| +| + +|=== + +[id="StorageComplianceRunResults_CommonObjectReference"] +=== StorageComplianceRunResults + +Next available tag: 6 + +[id="Fields-StorageComplianceRunResults_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| domain +| +| +| <<StorageComplianceDomain_CommonObjectReference,StorageComplianceDomain>> +| +| + +| runMetadata +| +| +| <<StorageComplianceRunMetadata_CommonObjectReference,StorageComplianceRunMetadata>> +| +| + +| clusterResults +| +| +| <<ComplianceRunResultsEntityResults_CommonObjectReference,ComplianceRunResultsEntityResults>> +| +| + +| nodeResults +| +| +| Map of <<ComplianceRunResultsEntityResults_CommonObjectReference,ComplianceRunResultsEntityResults>> +| +| + +| deploymentResults +| +| +| Map of <<ComplianceRunResultsEntityResults_CommonObjectReference,ComplianceRunResultsEntityResults>> +| +| + +| machineConfigResults +| +| +| Map of <<ComplianceRunResultsEntityResults_CommonObjectReference,ComplianceRunResultsEntityResults>> +| +| + +|=== + +[id="StorageComplianceState_CommonObjectReference"] +=== StorageComplianceState + +[id="Fields-StorageComplianceState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| COMPLIANCE_STATE_UNKNOWN +| COMPLIANCE_STATE_SKIP +| COMPLIANCE_STATE_NOTE +| COMPLIANCE_STATE_SUCCESS +| COMPLIANCE_STATE_FAILURE +| COMPLIANCE_STATE_ERROR + +|=== + +[id="StorageConfig_CommonObjectReference"] +=== StorageConfig + +[id="Fields-StorageConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| publicConfig +| +| +| <<StoragePublicConfig_CommonObjectReference,StoragePublicConfig>> +| +| + +| privateConfig +| +| +| <<StoragePrivateConfig_CommonObjectReference,StoragePrivateConfig>> +| +| + +| platformComponentConfig +| +| +| <<StoragePlatformComponentConfig_CommonObjectReference,StoragePlatformComponentConfig>> +| +| + +|=== + +[id="StorageContainer_CommonObjectReference"] +=== StorageContainer + +[id="Fields-StorageContainer_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| config +| +| +| <<StorageContainerConfig_CommonObjectReference,StorageContainerConfig>> +| +| + +| image +| +| +| <<StorageContainerImage_CommonObjectReference,StorageContainerImage>> +| +| + +| securityContext +| +| +| <<StorageSecurityContext_CommonObjectReference,StorageSecurityContext>> +| +| + +| volumes +| +| +| List of <<StorageVolume_CommonObjectReference,StorageVolume>> +| +| + +| ports +| +| +| List of <<StoragePortConfig_CommonObjectReference,StoragePortConfig>> +| +| + +| secrets +| +| +| List of <<StorageEmbeddedSecret_CommonObjectReference,StorageEmbeddedSecret>> +| +| + +| resources +| +| +| <<StorageResources_CommonObjectReference,StorageResources>> +| +| + +| name +| +| +| String +| +| + +| livenessProbe +| +| +| <<StorageLivenessProbe_CommonObjectReference,StorageLivenessProbe>> +| +| + +| readinessProbe +| +| +| <<StorageReadinessProbe_CommonObjectReference,StorageReadinessProbe>> +| +| + +|=== + +[id="StorageContainerConfig_CommonObjectReference"] +=== StorageContainerConfig + +[id="Fields-StorageContainerConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| env +| +| +| List of <<ContainerConfigEnvironmentConfig_CommonObjectReference,ContainerConfigEnvironmentConfig>> +| +| + +| command +| +| +| List of `string` +| +| + +| args +| +| +| List of `string` +| +| + +| directory +| +| +| String +| +| + +| user +| +| +| String +| +| + +| uid +| +| +| String +| +| int64 + +| appArmorProfile +| +| +| String +| +| + +|=== + +[id="StorageContainerImage_CommonObjectReference"] +=== StorageContainerImage + +Next tag: 12 + +[id="Fields-StorageContainerImage_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| <<StorageImageName_CommonObjectReference,StorageImageName>> +| +| + +| notPullable +| +| +| Boolean +| +| + +| isClusterLocal +| +| +| Boolean +| +| + +|=== + +[id="StorageContainerInstance_CommonObjectReference"] +=== StorageContainerInstance + +ContainerInstanceID allows to uniquely identify a container within a cluster. + +[id="Fields-StorageContainerInstance_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| instanceId +| +| +| <<StorageContainerInstanceID_CommonObjectReference,StorageContainerInstanceID>> +| +| + +| containingPodId +| +| +| String +| The pod containing this container instance (kubernetes only). +| + +| containerName +| +| +| String +| Container name. +| + +| containerIps +| +| +| List of `string` +| The IP addresses of this container. +| + +| started +| +| +| Date +| +| date-time + +| imageDigest +| +| +| String +| +| + +| finished +| +| +| Date +| The finish time of the container, if it finished. +| date-time + +| exitCode +| +| +| Integer +| The exit code of the container. Only valid when finished is populated. +| int32 + +| terminationReason +| +| +| String +| The reason for the container's termination, if it finished. +| + +|=== + +[id="StorageContainerInstanceID_CommonObjectReference"] +=== StorageContainerInstanceID + +[id="Fields-StorageContainerInstanceID_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| containerRuntime +| +| +| <<StorageContainerRuntime_CommonObjectReference,StorageContainerRuntime>> +| +| UNKNOWN_CONTAINER_RUNTIME, DOCKER_CONTAINER_RUNTIME, CRIO_CONTAINER_RUNTIME, + +| id +| +| +| String +| The ID of the container, specific to the given runtime. +| + +| node +| +| +| String +| The node on which this container runs. +| + +|=== + +[id="StorageContainerNameAndBaselineStatus_CommonObjectReference"] +=== StorageContainerNameAndBaselineStatus + +`ContainerNameAndBaselineStatus` represents a cached result +of process evaluation on a specific container name. + +[id="Fields-StorageContainerNameAndBaselineStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| containerName +| +| +| String +| +| + +| baselineStatus +| +| +| <<ContainerNameAndBaselineStatusBaselineStatus_CommonObjectReference,ContainerNameAndBaselineStatusBaselineStatus>> +| +| INVALID, NOT_GENERATED, UNLOCKED, LOCKED, + +| anomalousProcessesExecuted +| +| +| Boolean +| +| + +|=== + +[id="StorageContainerRuntime_CommonObjectReference"] +=== StorageContainerRuntime + +[id="Fields-StorageContainerRuntime_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN_CONTAINER_RUNTIME +| DOCKER_CONTAINER_RUNTIME +| CRIO_CONTAINER_RUNTIME + +|=== + +[id="StorageContainerRuntimeInfo_CommonObjectReference"] +=== StorageContainerRuntimeInfo + +[id="Fields-StorageContainerRuntimeInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| <<StorageContainerRuntime_CommonObjectReference,StorageContainerRuntime>> +| +| UNKNOWN_CONTAINER_RUNTIME, DOCKER_CONTAINER_RUNTIME, CRIO_CONTAINER_RUNTIME, + +| version +| +| +| String +| +| + +|=== + +[id="StorageCosignCertificateVerification_CommonObjectReference"] +=== StorageCosignCertificateVerification + +Holds all verification data for verifying certificates attached to cosign signatures. +If only the certificate is given, the Fulcio trusted root chain will be assumed and verified against. +If only the chain is given, this will be used over the Fulcio trusted root chain for verification. +If no certificate or chain is given, the Fulcio trusted root chain will be assumed and verified against. + +[id="Fields-StorageCosignCertificateVerification_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| certificatePemEnc +| +| +| String +| PEM encoded certificate to use for verification. Leave empty when using short-lived certificates as issued by Fulcio. +| + +| certificateChainPemEnc +| +| +| String +| PEM encoded certificate chain to use for verification. Defaults to the root certificate authority of the public Sigstore instance if left empty. +| + +| certificateOidcIssuer +| +| +| String +| Certificate OIDC issuer to verify against. This supports regular expressions following the RE2 syntax: https://github.com/google/re2/wiki/Syntax. In case the certificate does not specify an OIDC issuer, you may use '.*' as the OIDC issuer. However, it is recommended to use Fulcio compatible certificates according to the specification: https://github.com/sigstore/fulcio/blob/main/docs/certificate-specification.md. +| + +| certificateIdentity +| +| +| String +| Certificate identity to verify against. This supports regular expressions following the RE2 syntax: https://github.com/google/re2/wiki/Syntax. In case the certificate does not specify an identity, you may use '.*' as the identity. However, it is recommended to use Fulcio compatible certificates according to the specification: https://github.com/sigstore/fulcio/blob/main/docs/certificate-specification.md. +| + +| certificateTransparencyLog +| +| +| <<StorageCertificateTransparencyLogVerification_CommonObjectReference,StorageCertificateTransparencyLogVerification>> +| +| + +|=== + +[id="StorageCosignPublicKeyVerification_CommonObjectReference"] +=== StorageCosignPublicKeyVerification + +[id="Fields-StorageCosignPublicKeyVerification_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| publicKeys +| +| +| List of <<CosignPublicKeyVerificationPublicKey_CommonObjectReference,CosignPublicKeyVerificationPublicKey>> +| +| + +|=== + +[id="StorageCosignSignature_CommonObjectReference"] +=== StorageCosignSignature + +[id="Fields-StorageCosignSignature_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| rawSignature +| +| +| byte[] +| +| byte + +| signaturePayload +| +| +| byte[] +| +| byte + +| certPem +| +| +| byte[] +| +| byte + +| certChainPem +| +| +| byte[] +| +| byte + +| rekorBundle +| +| +| byte[] +| +| byte + +|=== + +[id="StorageDataSource_CommonObjectReference"] +=== StorageDataSource + +[id="Fields-StorageDataSource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| mirror +| +| +| String +| +| + +|=== + +[id="StorageDayOption_CommonObjectReference"] +=== StorageDayOption + +[id="Fields-StorageDayOption_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| numDays +| +| +| Long +| +| int64 + +| enabled +| +| +| Boolean +| +| + +|=== + +[id="StorageDeclarativeConfigHealth_CommonObjectReference"] +=== StorageDeclarativeConfigHealth + +[id="Fields-StorageDeclarativeConfigHealth_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| status +| +| +| <<StorageDeclarativeConfigHealthStatus_CommonObjectReference,StorageDeclarativeConfigHealthStatus>> +| +| UNHEALTHY, HEALTHY, + +| errorMessage +| +| +| String +| +| + +| resourceName +| +| +| String +| +| + +| resourceType +| +| +| <<StorageDeclarativeConfigHealthResourceType_CommonObjectReference,StorageDeclarativeConfigHealthResourceType>> +| +| CONFIG_MAP, ACCESS_SCOPE, PERMISSION_SET, ROLE, AUTH_PROVIDER, GROUP, NOTIFIER, + +| lastTimestamp +| +| +| Date +| Timestamp when the current status was set. +| date-time + +|=== + +[id="StorageDeclarativeConfigHealthResourceType_CommonObjectReference"] +=== StorageDeclarativeConfigHealthResourceType + +[id="Fields-StorageDeclarativeConfigHealthResourceType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| CONFIG_MAP +| ACCESS_SCOPE +| PERMISSION_SET +| ROLE +| AUTH_PROVIDER +| GROUP +| NOTIFIER + +|=== + +[id="StorageDeclarativeConfigHealthStatus_CommonObjectReference"] +=== StorageDeclarativeConfigHealthStatus + +[id="Fields-StorageDeclarativeConfigHealthStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNHEALTHY +| HEALTHY + +|=== + +[id="StorageDecommissionedClusterRetentionConfig_CommonObjectReference"] +=== StorageDecommissionedClusterRetentionConfig + +next available tag: 5 + +[id="Fields-StorageDecommissionedClusterRetentionConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| retentionDurationDays +| +| +| Integer +| +| int32 + +| ignoreClusterLabels +| +| +| Map of `string` +| +| + +| lastUpdated +| +| +| Date +| +| date-time + +| createdAt +| +| +| Date +| +| date-time + +|=== + +[id="StorageDeferralRequest_CommonObjectReference"] +=== StorageDeferralRequest + +[id="Fields-StorageDeferralRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| expiry +| +| +| <<StorageRequestExpiry_CommonObjectReference,StorageRequestExpiry>> +| +| + +|=== + +[id="StorageDeferralUpdate_CommonObjectReference"] +=== StorageDeferralUpdate + +[id="Fields-StorageDeferralUpdate_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| CVEs +| +| +| List of `string` +| +| + +| expiry +| +| +| <<StorageRequestExpiry_CommonObjectReference,StorageRequestExpiry>> +| +| + +|=== + +[id="StorageDeployment_CommonObjectReference"] +=== StorageDeployment + +Next available tag: 36 + +[id="Fields-StorageDeployment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| hash +| +| +| String +| +| uint64 + +| type +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| namespaceId +| +| +| String +| +| + +| orchestratorComponent +| +| +| Boolean +| +| + +| replicas +| +| +| String +| +| int64 + +| labels +| +| +| Map of `string` +| +| + +| podLabels +| +| +| Map of `string` +| +| + +| labelSelector +| +| +| <<StorageLabelSelector_CommonObjectReference,StorageLabelSelector>> +| +| + +| created +| +| +| Date +| +| date-time + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| containers +| +| +| List of <<StorageContainer_CommonObjectReference,StorageContainer>> +| +| + +| annotations +| +| +| Map of `string` +| +| + +| priority +| +| +| String +| +| int64 + +| inactive +| +| +| Boolean +| +| + +| imagePullSecrets +| +| +| List of `string` +| +| + +| serviceAccount +| +| +| String +| +| + +| serviceAccountPermissionLevel +| +| +| <<StoragePermissionLevel_CommonObjectReference,StoragePermissionLevel>> +| +| UNSET, NONE, DEFAULT, ELEVATED_IN_NAMESPACE, ELEVATED_CLUSTER_WIDE, CLUSTER_ADMIN, + +| automountServiceAccountToken +| +| +| Boolean +| +| + +| hostNetwork +| +| +| Boolean +| +| + +| hostPid +| +| +| Boolean +| +| + +| hostIpc +| +| +| Boolean +| +| + +| runtimeClass +| +| +| String +| +| + +| tolerations +| +| +| List of <<StorageToleration_CommonObjectReference,StorageToleration>> +| +| + +| ports +| +| +| List of <<StoragePortConfig_CommonObjectReference,StoragePortConfig>> +| +| + +| stateTimestamp +| +| +| String +| +| int64 + +| riskScore +| +| +| Float +| +| float + +| platformComponent +| +| +| Boolean +| +| + +|=== + +[id="StorageDockerConfig_CommonObjectReference"] +=== StorageDockerConfig + +Docker registry configuration. Used by integrations of type "docker" and other docker compliant registries without dedicated configuration type. + +Use of type "azure" with `DockerConfig` has been deprecated in 4.7. Use `AzureConfig` instead. + +[id="Fields-StorageDockerConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| username +| +| +| String +| +| + +| password +| +| +| String +| The password for the integration. The server will mask the value of this credential in responses and logs. +| + +| insecure +| +| +| Boolean +| +| + +|=== + +[id="StorageDynamicClusterConfig_CommonObjectReference"] +=== StorageDynamicClusterConfig + +The difference between Static and Dynamic cluster config is that Dynamic values are sent over the Central to Sensor gRPC connection. This has the benefit of allowing for "hot reloading" of values without restarting Secured cluster components. + +[id="Fields-StorageDynamicClusterConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| admissionControllerConfig +| +| +| <<StorageAdmissionControllerConfig_CommonObjectReference,StorageAdmissionControllerConfig>> +| +| + +| registryOverride +| +| +| String +| +| + +| disableAuditLogs +| +| +| Boolean +| +| + +|=== + +[id="StorageECRConfig_CommonObjectReference"] +=== StorageECRConfig + +[id="Fields-StorageECRConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| registryId +| +| +| String +| +| + +| accessKeyId +| +| +| String +| The access key ID for the integration. The server will mask the value of this credential in responses and logs. +| + +| secretAccessKey +| +| +| String +| The secret access key for the integration. The server will mask the value of this credential in responses and logs. +| + +| region +| +| +| String +| +| + +| useIam +| +| +| Boolean +| +| + +| endpoint +| +| +| String +| +| + +| useAssumeRole +| +| +| Boolean +| +| + +| assumeRoleId +| +| +| String +| +| + +| assumeRoleExternalId +| +| +| String +| +| + +| authorizationData +| +| +| <<ECRConfigAuthorizationData_CommonObjectReference,ECRConfigAuthorizationData>> +| +| + +|=== + +[id="StorageEPSS_CommonObjectReference"] +=== StorageEPSS + +EPSS Score stores two epss metrics returned by scanner - epss probability and epss percentile + +[id="Fields-StorageEPSS_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| epssProbability +| +| +| Float +| +| float + +| epssPercentile +| +| +| Float +| +| float + +|=== + +[id="StorageEffectiveAccessScope_CommonObjectReference"] +=== StorageEffectiveAccessScope + +EffectiveAccessScope describes which clusters and namespaces are "in scope" +given current state. Basically, if AccessScope is applied to the currently +known clusters and namespaces, the result is EffectiveAccessScope. + +EffectiveAccessScope represents a tree with nodes marked as included and +excluded. If a node is included, all its child nodes are included. + +[id="Fields-StorageEffectiveAccessScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusters +| +| +| List of <<StorageEffectiveAccessScopeCluster_CommonObjectReference,StorageEffectiveAccessScopeCluster>> +| +| + +|=== + +[id="StorageEffectiveAccessScopeCluster_CommonObjectReference"] +=== StorageEffectiveAccessScopeCluster + +[id="Fields-StorageEffectiveAccessScopeCluster_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| state +| +| +| <<StorageEffectiveAccessScopeState_CommonObjectReference,StorageEffectiveAccessScopeState>> +| +| UNKNOWN, INCLUDED, EXCLUDED, PARTIAL, + +| labels +| +| +| Map of `string` +| +| + +| namespaces +| +| +| List of <<StorageEffectiveAccessScopeNamespace_CommonObjectReference,StorageEffectiveAccessScopeNamespace>> +| +| + +|=== + +[id="StorageEffectiveAccessScopeNamespace_CommonObjectReference"] +=== StorageEffectiveAccessScopeNamespace + +[id="Fields-StorageEffectiveAccessScopeNamespace_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| state +| +| +| <<StorageEffectiveAccessScopeState_CommonObjectReference,StorageEffectiveAccessScopeState>> +| +| UNKNOWN, INCLUDED, EXCLUDED, PARTIAL, + +| labels +| +| +| Map of `string` +| +| + +|=== + +[id="StorageEffectiveAccessScopeState_CommonObjectReference"] +=== StorageEffectiveAccessScopeState + +[id="Fields-StorageEffectiveAccessScopeState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| INCLUDED +| EXCLUDED +| PARTIAL + +|=== + +[id="StorageEmail_CommonObjectReference"] +=== StorageEmail + +[id="Fields-StorageEmail_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| server +| +| +| String +| +| + +| sender +| +| +| String +| +| + +| username +| +| +| String +| +| + +| password +| +| +| String +| The password for the integration. The server will mask the value of this credential in responses and logs. +| + +| disableTLS +| +| +| Boolean +| +| + +| DEPRECATEDUseStartTLS +| +| +| Boolean +| +| + +| from +| +| +| String +| +| + +| startTLSAuthMethod +| +| +| <<EmailAuthMethod_CommonObjectReference,EmailAuthMethod>> +| +| DISABLED, PLAIN, LOGIN, + +| allowUnauthenticatedSmtp +| +| +| Boolean +| +| + +| skipTLSVerify +| +| +| Boolean +| +| + +|=== + +[id="StorageEmailNotifierConfiguration_CommonObjectReference"] +=== StorageEmailNotifierConfiguration + +[id="Fields-StorageEmailNotifierConfiguration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| notifierId +| +| +| String +| +| + +| mailingLists +| +| +| List of `string` +| +| + +| customSubject +| +| +| String +| +| + +| customBody +| +| +| String +| +| + +|=== + +[id="StorageEmbeddedImageScanComponent_CommonObjectReference"] +=== StorageEmbeddedImageScanComponent + +Next Tag: 14 + +[id="Fields-StorageEmbeddedImageScanComponent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| version +| +| +| String +| +| + +| license +| +| +| <<StorageLicense_CommonObjectReference,StorageLicense>> +| +| + +| vulns +| +| +| List of <<StorageEmbeddedVulnerability_CommonObjectReference,StorageEmbeddedVulnerability>> +| +| + +| layerIndex +| +| +| Integer +| +| int32 + +| priority +| +| +| String +| +| int64 + +| source +| +| +| <<StorageSourceType_CommonObjectReference,StorageSourceType>> +| +| OS, PYTHON, JAVA, RUBY, NODEJS, GO, DOTNETCORERUNTIME, INFRASTRUCTURE, + +| location +| +| +| String +| +| + +| topCvss +| +| +| Float +| +| float + +| riskScore +| +| +| Float +| +| float + +| fixedBy +| +| +| String +| Component version that fixes all the fixable vulnerabilities in this component. +| + +| executables +| +| +| List of <<StorageEmbeddedImageScanComponentExecutable_CommonObjectReference,StorageEmbeddedImageScanComponentExecutable>> +| +| + +| architecture +| +| +| String +| +| + +|=== + +[id="StorageEmbeddedImageScanComponentExecutable_CommonObjectReference"] +=== StorageEmbeddedImageScanComponentExecutable + +[id="Fields-StorageEmbeddedImageScanComponentExecutable_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| path +| +| +| String +| +| + +| dependencies +| +| +| List of `string` +| +| + +|=== + +[id="StorageEmbeddedNodeScanComponent_CommonObjectReference"] +=== StorageEmbeddedNodeScanComponent + +[id="Fields-StorageEmbeddedNodeScanComponent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| version +| +| +| String +| +| + +| vulns +| +| +| List of <<StorageEmbeddedVulnerability_CommonObjectReference,StorageEmbeddedVulnerability>> +| +| + +| vulnerabilities +| +| +| List of <<StorageNodeVulnerability_CommonObjectReference,StorageNodeVulnerability>> +| +| + +| priority +| +| +| String +| +| int64 + +| topCvss +| +| +| Float +| +| float + +| riskScore +| +| +| Float +| +| float + +|=== + +[id="StorageEmbeddedSecret_CommonObjectReference"] +=== StorageEmbeddedSecret + +[id="Fields-StorageEmbeddedSecret_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| path +| +| +| String +| +| + +|=== + +[id="StorageEmbeddedVulnerability_CommonObjectReference"] +=== StorageEmbeddedVulnerability + +Next Tag: 25 + +[id="Fields-StorageEmbeddedVulnerability_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cve +| +| +| String +| +| + +| advisory +| +| +| <<StorageAdvisory_CommonObjectReference,StorageAdvisory>> +| +| + +| cvss +| +| +| Float +| +| float + +| summary +| +| +| String +| +| + +| link +| +| +| String +| +| + +| fixedBy +| +| +| String +| +| + +| scoreVersion +| +| +| <<StorageEmbeddedVulnerabilityScoreVersion_CommonObjectReference,StorageEmbeddedVulnerabilityScoreVersion>> +| +| V2, V3, + +| cvssV2 +| +| +| <<StorageCVSSV2_CommonObjectReference,StorageCVSSV2>> +| +| + +| cvssV3 +| +| +| <<StorageCVSSV3_CommonObjectReference,StorageCVSSV3>> +| +| + +| publishedOn +| +| +| Date +| +| date-time + +| lastModified +| +| +| Date +| +| date-time + +| vulnerabilityType +| +| +| <<EmbeddedVulnerabilityVulnerabilityType_CommonObjectReference,EmbeddedVulnerabilityVulnerabilityType>> +| +| UNKNOWN_VULNERABILITY, IMAGE_VULNERABILITY, K8S_VULNERABILITY, ISTIO_VULNERABILITY, NODE_VULNERABILITY, OPENSHIFT_VULNERABILITY, + +| vulnerabilityTypes +| +| +| List of <<EmbeddedVulnerabilityVulnerabilityType_CommonObjectReference,EmbeddedVulnerabilityVulnerabilityType>> +| +| + +| suppressed +| +| +| Boolean +| +| + +| suppressActivation +| +| +| Date +| +| date-time + +| suppressExpiry +| +| +| Date +| +| date-time + +| firstSystemOccurrence +| +| +| Date +| Time when the CVE was first seen, for this specific distro, in the system. +| date-time + +| firstImageOccurrence +| +| +| Date +| Time when the CVE was first seen in this image. +| date-time + +| severity +| +| +| <<StorageVulnerabilitySeverity_CommonObjectReference,StorageVulnerabilitySeverity>> +| +| UNKNOWN_VULNERABILITY_SEVERITY, LOW_VULNERABILITY_SEVERITY, MODERATE_VULNERABILITY_SEVERITY, IMPORTANT_VULNERABILITY_SEVERITY, CRITICAL_VULNERABILITY_SEVERITY, + +| state +| +| +| <<StorageVulnerabilityState_CommonObjectReference,StorageVulnerabilityState>> +| +| OBSERVED, DEFERRED, FALSE_POSITIVE, + +| cvssMetrics +| +| +| List of <<StorageCVSSScore_CommonObjectReference,StorageCVSSScore>> +| +| + +| nvdCvss +| +| +| Float +| +| float + +| epss +| +| +| <<StorageEPSS_CommonObjectReference,StorageEPSS>> +| +| + +|=== + +[id="StorageEmbeddedVulnerabilityScoreVersion_CommonObjectReference"] +=== StorageEmbeddedVulnerabilityScoreVersion + +ScoreVersion can be deprecated ROX-26066 + +- V2: No unset for automatic backwards compatibility + +[id="Fields-StorageEmbeddedVulnerabilityScoreVersion_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| V2 +| V3 + +|=== + +[id="StorageEnforcementAction_CommonObjectReference"] +=== StorageEnforcementAction + + - FAIL_KUBE_REQUEST_ENFORCEMENT: FAIL_KUBE_REQUEST_ENFORCEMENT takes effect only if admission control webhook is enabled to listen on exec and port-forward events. + - FAIL_DEPLOYMENT_CREATE_ENFORCEMENT: FAIL_DEPLOYMENT_CREATE_ENFORCEMENT takes effect only if admission control webhook is configured to enforce on object creates. + - FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT: FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT takes effect only if admission control webhook is configured to enforce on object updates. + +[id="Fields-StorageEnforcementAction_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET_ENFORCEMENT +| SCALE_TO_ZERO_ENFORCEMENT +| UNSATISFIABLE_NODE_CONSTRAINT_ENFORCEMENT +| KILL_POD_ENFORCEMENT +| FAIL_BUILD_ENFORCEMENT +| FAIL_KUBE_REQUEST_ENFORCEMENT +| FAIL_DEPLOYMENT_CREATE_ENFORCEMENT +| FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT + +|=== + +[id="StorageEventSource_CommonObjectReference"] +=== StorageEventSource + +[id="Fields-StorageEventSource_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| NOT_APPLICABLE +| DEPLOYMENT_EVENT +| AUDIT_LOG_EVENT + +|=== + +[id="StorageExclusion_CommonObjectReference"] +=== StorageExclusion + +[id="Fields-StorageExclusion_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| deployment +| +| +| <<StorageExclusionDeployment_CommonObjectReference,StorageExclusionDeployment>> +| +| + +| image +| +| +| <<StorageExclusionImage_CommonObjectReference,StorageExclusionImage>> +| +| + +| expiration +| +| +| Date +| +| date-time + +|=== + +[id="StorageExclusionDeployment_CommonObjectReference"] +=== StorageExclusionDeployment + +[id="Fields-StorageExclusionDeployment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| scope +| +| +| <<StorageScope_CommonObjectReference,StorageScope>> +| +| + +|=== + +[id="StorageExclusionImage_CommonObjectReference"] +=== StorageExclusionImage + +[id="Fields-StorageExclusionImage_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +|=== + +[id="StorageExportPoliciesResponse_CommonObjectReference"] +=== StorageExportPoliciesResponse + +ExportPoliciesResponse is used by the API but it is defined in storage because we expect customers to store them. We do backwards-compatibility checks on objects in the storge folder and those checks should be applied to this object + +[id="Fields-StorageExportPoliciesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| policies +| +| +| List of <<StoragePolicy_CommonObjectReference,StoragePolicy>> +| +| + +|=== + +[id="StorageExternalBackup_CommonObjectReference"] +=== StorageExternalBackup + +Next available tag: 10 + +[id="Fields-StorageExternalBackup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| schedule +| +| +| <<StorageSchedule_CommonObjectReference,StorageSchedule>> +| +| + +| backupsToKeep +| +| +| Integer +| +| int32 + +| s3 +| +| +| <<StorageS3Config_CommonObjectReference,StorageS3Config>> +| +| + +| gcs +| +| +| <<StorageGCSConfig_CommonObjectReference,StorageGCSConfig>> +| +| + +| s3compatible +| +| +| <<StorageS3Compatible_CommonObjectReference,StorageS3Compatible>> +| +| + +| includeCertificates +| +| +| Boolean +| +| + +|=== + +[id="StorageFalsePositiveUpdate_CommonObjectReference"] +=== StorageFalsePositiveUpdate + +[id="Fields-StorageFalsePositiveUpdate_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| CVEs +| +| +| List of `string` +| +| + +|=== + +[id="StorageGCSConfig_CommonObjectReference"] +=== StorageGCSConfig + +[id="Fields-StorageGCSConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| bucket +| +| +| String +| +| + +| serviceAccount +| +| +| String +| The service account for the storage integration. The server will mask the value of this credential in responses and logs. +| + +| objectPrefix +| +| +| String +| +| + +| useWorkloadId +| +| +| Boolean +| +| + +|=== + +[id="StorageGeneric_CommonObjectReference"] +=== StorageGeneric + +[id="Fields-StorageGeneric_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| skipTLSVerify +| +| +| Boolean +| +| + +| caCert +| +| +| String +| +| + +| username +| +| +| String +| +| + +| password +| +| +| String +| The password for the integration. The server will mask the value of this credential in responses and logs. +| + +| headers +| +| +| List of <<StorageKeyValuePair_CommonObjectReference,StorageKeyValuePair>> +| +| + +| extraFields +| +| +| List of <<StorageKeyValuePair_CommonObjectReference,StorageKeyValuePair>> +| +| + +| auditLoggingEnabled +| +| +| Boolean +| +| + +|=== + +[id="StorageGoogleConfig_CommonObjectReference"] +=== StorageGoogleConfig + +[id="Fields-StorageGoogleConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| serviceAccount +| +| +| String +| The service account for the integration. The server will mask the value of this credential in responses and logs. +| + +| project +| +| +| String +| +| + +| wifEnabled +| +| +| Boolean +| +| + +|=== + +[id="StorageGoogleProviderMetadata_CommonObjectReference"] +=== StorageGoogleProviderMetadata + +[id="Fields-StorageGoogleProviderMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| project +| +| +| String +| +| + +| clusterName +| +| +| String +| Deprecated in favor of providerMetadata.cluster.name. +| + +|=== + +[id="StorageGroup_CommonObjectReference"] +=== StorageGroup + +Group is a GroupProperties : Role mapping. + +[id="Fields-StorageGroup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| props +| +| +| <<StorageGroupProperties_CommonObjectReference,StorageGroupProperties>> +| +| + +| roleName +| +| +| String +| This is the name of the role that will apply to users in this group. +| + +|=== + +[id="StorageGroupProperties_CommonObjectReference"] +=== StorageGroupProperties + +GroupProperties defines the properties of a group. Groups apply to users when +their properties match. For instance: + - If GroupProperties has only an auth_provider_id, then that group applies + to all users logged in with that auth provider. + - If GroupProperties in addition has a claim key, then it applies to all + users with that auth provider and the claim key, etc. +Note: Changes to GroupProperties may require changes to v1.DeleteGroupRequest. + +[id="Fields-StorageGroupProperties_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| Unique identifier for group properties and respectively the group. +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +| authProviderId +| +| +| String +| +| + +| key +| +| +| String +| +| + +| value +| +| +| String +| +| + +|=== + +[id="StorageIBMRegistryConfig_CommonObjectReference"] +=== StorageIBMRegistryConfig + +[id="Fields-StorageIBMRegistryConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| apiKey +| +| +| String +| The API key for the integration. The server will mask the value of this credential in responses and logs. +| + +|=== + +[id="StorageIPBlock_CommonObjectReference"] +=== StorageIPBlock + +[id="Fields-StorageIPBlock_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cidr +| +| +| String +| +| + +| except +| +| +| List of `string` +| +| + +|=== + +[id="StorageImage_CommonObjectReference"] +=== StorageImage + +Next Tag: 19 + +[id="Fields-StorageImage_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| <<StorageImageName_CommonObjectReference,StorageImageName>> +| +| + +| names +| +| +| List of <<StorageImageName_CommonObjectReference,StorageImageName>> +| This should deprecate the ImageName field long-term, allowing images with the same digest to be associated with different locations. TODO(dhaus): For now, this message will be without search tags due to duplicated search tags otherwise. +| + +| metadata +| +| +| <<StorageImageMetadata_CommonObjectReference,StorageImageMetadata>> +| +| + +| scan +| +| +| <<StorageImageScan_CommonObjectReference,StorageImageScan>> +| +| + +| signatureVerificationData +| +| +| <<StorageImageSignatureVerificationData_CommonObjectReference,StorageImageSignatureVerificationData>> +| +| + +| signature +| +| +| <<StorageImageSignature_CommonObjectReference,StorageImageSignature>> +| +| + +| components +| +| +| Integer +| +| int32 + +| cves +| +| +| Integer +| +| int32 + +| fixableCves +| +| +| Integer +| +| int32 + +| lastUpdated +| +| +| Date +| +| date-time + +| notPullable +| +| +| Boolean +| +| + +| isClusterLocal +| +| +| Boolean +| +| + +| priority +| +| +| String +| +| int64 + +| riskScore +| +| +| Float +| +| float + +| topCvss +| +| +| Float +| +| float + +| notes +| +| +| List of <<StorageImageNote_CommonObjectReference,StorageImageNote>> +| +| + +|=== + +[id="StorageImageIntegration_CommonObjectReference"] +=== StorageImageIntegration + +Next Tag: 25 + +[id="Fields-StorageImageIntegration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| categories +| +| +| List of <<StorageImageIntegrationCategory_CommonObjectReference,StorageImageIntegrationCategory>> +| +| + +| clairify +| +| +| <<StorageClairifyConfig_CommonObjectReference,StorageClairifyConfig>> +| +| + +| scannerV4 +| +| +| <<StorageScannerV4Config_CommonObjectReference,StorageScannerV4Config>> +| +| + +| docker +| +| +| <<StorageDockerConfig_CommonObjectReference,StorageDockerConfig>> +| +| + +| quay +| +| +| <<StorageQuayConfig_CommonObjectReference,StorageQuayConfig>> +| +| + +| ecr +| +| +| <<StorageECRConfig_CommonObjectReference,StorageECRConfig>> +| +| + +| google +| +| +| <<StorageGoogleConfig_CommonObjectReference,StorageGoogleConfig>> +| +| + +| clair +| +| +| <<StorageClairConfig_CommonObjectReference,StorageClairConfig>> +| +| + +| clairV4 +| +| +| <<StorageClairV4Config_CommonObjectReference,StorageClairV4Config>> +| +| + +| ibm +| +| +| <<StorageIBMRegistryConfig_CommonObjectReference,StorageIBMRegistryConfig>> +| +| + +| azure +| +| +| <<StorageAzureConfig_CommonObjectReference,StorageAzureConfig>> +| +| + +| autogenerated +| +| +| Boolean +| +| + +| clusterId +| +| +| String +| +| + +| skipTestIntegration +| +| +| Boolean +| +| + +| source +| +| +| <<StorageImageIntegrationSource_CommonObjectReference,StorageImageIntegrationSource>> +| +| + +|=== + +[id="StorageImageIntegrationCategory_CommonObjectReference"] +=== StorageImageIntegrationCategory + + - NODE_SCANNER: Image and Node integrations are currently done on the same form in the UI +so the image integration is also currently used for node integrations. +This decision was made because we currently only support one node scanner (our scanner). + +[id="Fields-StorageImageIntegrationCategory_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| REGISTRY +| SCANNER +| NODE_SCANNER + +|=== + +[id="StorageImageIntegrationSource_CommonObjectReference"] +=== StorageImageIntegrationSource + +[id="Fields-StorageImageIntegrationSource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| imagePullSecretName +| +| +| String +| +| + +|=== + +[id="StorageImageLayer_CommonObjectReference"] +=== StorageImageLayer + +[id="Fields-StorageImageLayer_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| instruction +| +| +| String +| +| + +| value +| +| +| String +| +| + +| created +| +| +| Date +| +| date-time + +| author +| +| +| String +| +| + +| empty +| +| +| Boolean +| +| + +|=== + +[id="StorageImageMetadata_CommonObjectReference"] +=== StorageImageMetadata + +If any fields of ImageMetadata are modified including subfields, please check pkg/images/enricher/metadata.go to ensure that those changes will be automatically picked up Next Tag: 6 + +[id="Fields-StorageImageMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| v1 +| +| +| <<StorageV1Metadata_CommonObjectReference,StorageV1Metadata>> +| +| + +| v2 +| +| +| <<StorageV2Metadata_CommonObjectReference,StorageV2Metadata>> +| +| + +| layerShas +| +| +| List of `string` +| +| + +| dataSource +| +| +| <<StorageDataSource_CommonObjectReference,StorageDataSource>> +| +| + +| version +| +| +| String +| +| uint64 + +|=== + +[id="StorageImageName_CommonObjectReference"] +=== StorageImageName + +[id="Fields-StorageImageName_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| registry +| +| +| String +| +| + +| remote +| +| +| String +| +| + +| tag +| +| +| String +| +| + +| fullName +| +| +| String +| +| + +|=== + +[id="StorageImageNote_CommonObjectReference"] +=== StorageImageNote + +[id="Fields-StorageImageNote_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| MISSING_METADATA +| MISSING_SCAN_DATA +| MISSING_SIGNATURE +| MISSING_SIGNATURE_VERIFICATION_DATA + +|=== + +[id="StorageImagePullSecret_CommonObjectReference"] +=== StorageImagePullSecret + +[id="Fields-StorageImagePullSecret_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| registries +| +| +| List of <<ImagePullSecretRegistry_CommonObjectReference,ImagePullSecretRegistry>> +| +| + +|=== + +[id="StorageImageScan_CommonObjectReference"] +=== StorageImageScan + +Next tag: 8 + +[id="Fields-StorageImageScan_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scannerVersion +| +| +| String +| +| + +| scanTime +| +| +| Date +| +| date-time + +| components +| +| +| List of <<StorageEmbeddedImageScanComponent_CommonObjectReference,StorageEmbeddedImageScanComponent>> +| +| + +| operatingSystem +| +| +| String +| +| + +| dataSource +| +| +| <<StorageDataSource_CommonObjectReference,StorageDataSource>> +| +| + +| notes +| +| +| List of <<StorageImageScanNote_CommonObjectReference,StorageImageScanNote>> +| +| + +| hash +| +| +| String +| +| uint64 + +|=== + +[id="StorageImageScanNote_CommonObjectReference"] +=== StorageImageScanNote + +[id="Fields-StorageImageScanNote_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| OS_UNAVAILABLE +| PARTIAL_SCAN_DATA +| OS_CVES_UNAVAILABLE +| OS_CVES_STALE +| LANGUAGE_CVES_UNAVAILABLE +| CERTIFIED_RHEL_SCAN_UNAVAILABLE + +|=== + +[id="StorageImageSignature_CommonObjectReference"] +=== StorageImageSignature + +[id="Fields-StorageImageSignature_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| signatures +| +| +| List of <<StorageSignature_CommonObjectReference,StorageSignature>> +| +| + +| fetched +| +| +| Date +| +| date-time + +|=== + +[id="StorageImageSignatureVerificationData_CommonObjectReference"] +=== StorageImageSignatureVerificationData + +[id="Fields-StorageImageSignatureVerificationData_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| results +| +| +| List of <<StorageImageSignatureVerificationResult_CommonObjectReference,StorageImageSignatureVerificationResult>> +| +| + +|=== + +[id="StorageImageSignatureVerificationResult_CommonObjectReference"] +=== StorageImageSignatureVerificationResult + +Next Tag: 6 + +[id="Fields-StorageImageSignatureVerificationResult_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| verificationTime +| +| +| Date +| +| date-time + +| verifierId +| +| +| String +| verifier_id correlates to the ID of the signature integration used to verify the signature. +| + +| status +| +| +| <<StorageImageSignatureVerificationResultStatus_CommonObjectReference,StorageImageSignatureVerificationResultStatus>> +| +| UNSET, VERIFIED, FAILED_VERIFICATION, INVALID_SIGNATURE_ALGO, CORRUPTED_SIGNATURE, GENERIC_ERROR, + +| description +| +| +| String +| description is set in the case of an error with the specific error's message. Otherwise, this will not be set. +| + +| verifiedImageReferences +| +| +| List of `string` +| The full image names that are verified by this specific signature integration ID. +| + +|=== + +[id="StorageImageSignatureVerificationResultStatus_CommonObjectReference"] +=== StorageImageSignatureVerificationResultStatus + +Status represents the status of the result. + + - VERIFIED: VERIFIED is set when the signature's verification was successful. + - FAILED_VERIFICATION: FAILED_VERIFICATION is set when the signature's verification failed. + - INVALID_SIGNATURE_ALGO: INVALID_SIGNATURE_ALGO is set when the signature's algorithm is invalid and unsupported. + - CORRUPTED_SIGNATURE: CORRUPTED_SIGNATURE is set when the raw signature is corrupted, i.e. wrong base64 encoding. + - GENERIC_ERROR: GENERIC_ERROR is set when an error occurred during verification that cannot be associated with a specific +status. + +[id="Fields-StorageImageSignatureVerificationResultStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| VERIFIED +| FAILED_VERIFICATION +| INVALID_SIGNATURE_ALGO +| CORRUPTED_SIGNATURE +| GENERIC_ERROR + +|=== + +[id="StorageIntegrationHealth_CommonObjectReference"] +=== StorageIntegrationHealth + +[id="Fields-StorageIntegrationHealth_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| <<StorageIntegrationHealthType_CommonObjectReference,StorageIntegrationHealthType>> +| +| UNKNOWN, IMAGE_INTEGRATION, NOTIFIER, BACKUP, DECLARATIVE_CONFIG, + +| status +| +| +| <<StorageIntegrationHealthStatus_CommonObjectReference,StorageIntegrationHealthStatus>> +| +| UNINITIALIZED, UNHEALTHY, HEALTHY, + +| errorMessage +| +| +| String +| +| + +| lastTimestamp +| +| +| Date +| +| date-time + +|=== + +[id="StorageIntegrationHealthStatus_CommonObjectReference"] +=== StorageIntegrationHealthStatus + +[id="Fields-StorageIntegrationHealthStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNINITIALIZED +| UNHEALTHY +| HEALTHY + +|=== + +[id="StorageIntegrationHealthType_CommonObjectReference"] +=== StorageIntegrationHealthType + +[id="Fields-StorageIntegrationHealthType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| IMAGE_INTEGRATION +| NOTIFIER +| BACKUP +| DECLARATIVE_CONFIG + +|=== + +[id="StorageJira_CommonObjectReference"] +=== StorageJira + +[id="Fields-StorageJira_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| url +| +| +| String +| +| + +| username +| +| +| String +| +| + +| password +| +| +| String +| The password for the integration. The server will mask the value of this credential in responses and logs. +| + +| issueType +| +| +| String +| +| + +| priorityMappings +| +| +| List of <<JiraPriorityMapping_CommonObjectReference,JiraPriorityMapping>> +| +| + +| defaultFieldsJson +| +| +| String +| +| + +| disablePriority +| +| +| Boolean +| +| + +|=== + +[id="StorageK8sRole_CommonObjectReference"] +=== StorageK8sRole + +Properties of an individual k8s Role or ClusterRole. //////////////////////////////////////// + +[id="Fields-StorageK8sRole_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| clusterRole +| +| +| Boolean +| +| + +| labels +| +| +| Map of `string` +| +| + +| annotations +| +| +| Map of `string` +| +| + +| createdAt +| +| +| Date +| +| date-time + +| rules +| +| +| List of <<StoragePolicyRule_CommonObjectReference,StoragePolicyRule>> +| +| + +|=== + +[id="StorageK8sRoleBinding_CommonObjectReference"] +=== StorageK8sRoleBinding + +Properties of an individual k8s RoleBinding or ClusterRoleBinding. //////////////////////////////////////// + +[id="Fields-StorageK8sRoleBinding_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| clusterRole +| +| +| Boolean +| ClusterRole specifies whether the binding binds a cluster role. However, it cannot be used to determine whether the binding is a cluster role binding. This can be done in conjunction with the namespace. If the namespace is empty and cluster role is true, the binding is a cluster role binding. +| + +| labels +| +| +| Map of `string` +| +| + +| annotations +| +| +| Map of `string` +| +| + +| createdAt +| +| +| Date +| +| date-time + +| subjects +| +| +| List of <<StorageSubject_CommonObjectReference,StorageSubject>> +| +| + +| roleId +| +| +| String +| +| + +|=== + +[id="StorageKeyValuePair_CommonObjectReference"] +=== StorageKeyValuePair + +[id="Fields-StorageKeyValuePair_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| value +| +| +| String +| +| + +|=== + +[id="StorageL4Protocol_CommonObjectReference"] +=== StorageL4Protocol + +[id="Fields-StorageL4Protocol_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| L4_PROTOCOL_UNKNOWN +| L4_PROTOCOL_TCP +| L4_PROTOCOL_UDP +| L4_PROTOCOL_ICMP +| L4_PROTOCOL_RAW +| L4_PROTOCOL_SCTP +| L4_PROTOCOL_ANY + +|=== + +[id="StorageLabelSelector_CommonObjectReference"] +=== StorageLabelSelector + +Label selector components are joined with logical AND, see https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ + +Next available tag: 3 + +[id="Fields-StorageLabelSelector_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| matchLabels +| +| +| Map of `string` +| This is actually a oneof, but we can't make it one due to backwards compatibility constraints. +| + +| requirements +| +| +| List of <<StorageLabelSelectorRequirement_CommonObjectReference,StorageLabelSelectorRequirement>> +| +| + +|=== + +[id="StorageLabelSelectorOperator_CommonObjectReference"] +=== StorageLabelSelectorOperator + +[id="Fields-StorageLabelSelectorOperator_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| IN +| NOT_IN +| EXISTS +| NOT_EXISTS + +|=== + +[id="StorageLabelSelectorRequirement_CommonObjectReference"] +=== StorageLabelSelectorRequirement + +Next available tag: 4 + +[id="Fields-StorageLabelSelectorRequirement_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| op +| +| +| <<StorageLabelSelectorOperator_CommonObjectReference,StorageLabelSelectorOperator>> +| +| UNKNOWN, IN, NOT_IN, EXISTS, NOT_EXISTS, + +| values +| +| +| List of `string` +| +| + +|=== + +[id="StorageLicense_CommonObjectReference"] +=== StorageLicense + +[id="Fields-StorageLicense_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| url +| +| +| String +| +| + +|=== + +[id="StorageLifecycleStage_CommonObjectReference"] +=== StorageLifecycleStage + +[id="Fields-StorageLifecycleStage_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| DEPLOY +| BUILD +| RUNTIME + +|=== + +[id="StorageListAlert_CommonObjectReference"] +=== StorageListAlert + +[id="Fields-StorageListAlert_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| lifecycleStage +| +| +| <<StorageLifecycleStage_CommonObjectReference,StorageLifecycleStage>> +| +| DEPLOY, BUILD, RUNTIME, + +| time +| +| +| Date +| +| date-time + +| policy +| +| +| <<StorageListAlertPolicy_CommonObjectReference,StorageListAlertPolicy>> +| +| + +| state +| +| +| <<StorageViolationState_CommonObjectReference,StorageViolationState>> +| +| ACTIVE, RESOLVED, ATTEMPTED, + +| enforcementCount +| +| +| Integer +| +| int32 + +| enforcementAction +| +| +| <<StorageEnforcementAction_CommonObjectReference,StorageEnforcementAction>> +| +| UNSET_ENFORCEMENT, SCALE_TO_ZERO_ENFORCEMENT, UNSATISFIABLE_NODE_CONSTRAINT_ENFORCEMENT, KILL_POD_ENFORCEMENT, FAIL_BUILD_ENFORCEMENT, FAIL_KUBE_REQUEST_ENFORCEMENT, FAIL_DEPLOYMENT_CREATE_ENFORCEMENT, FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT, + +| commonEntityInfo +| +| +| <<ListAlertCommonEntityInfo_CommonObjectReference,ListAlertCommonEntityInfo>> +| +| + +| deployment +| +| +| <<StorageListAlertDeployment_CommonObjectReference,StorageListAlertDeployment>> +| +| + +| resource +| +| +| <<ListAlertResourceEntity_CommonObjectReference,ListAlertResourceEntity>> +| +| + +|=== + +[id="StorageListAlertDeployment_CommonObjectReference"] +=== StorageListAlertDeployment + +[id="Fields-StorageListAlertDeployment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| clusterName +| +| +| String +| This field is deprecated and can be found in CommonEntityInfo. It will be removed from here in a future release. This field has moved to CommonEntityInfo +| + +| namespace +| +| +| String +| This field is deprecated and can be found in CommonEntityInfo. It will be removed from here in a future release. This field has moved to CommonEntityInfo +| + +| clusterId +| +| +| String +| This field is deprecated and can be found in CommonEntityInfo. It will be removed from here in a future release. This field has moved to CommonEntityInfo +| + +| inactive +| +| +| Boolean +| +| + +| namespaceId +| +| +| String +| This field is deprecated and can be found in CommonEntityInfo. It will be removed from here in a future release. This field has moved to CommonEntityInfo +| + +| deploymentType +| +| +| String +| +| + +|=== + +[id="StorageListAlertPolicy_CommonObjectReference"] +=== StorageListAlertPolicy + +[id="Fields-StorageListAlertPolicy_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| severity +| +| +| <<StorageSeverity_CommonObjectReference,StorageSeverity>> +| +| UNSET_SEVERITY, LOW_SEVERITY, MEDIUM_SEVERITY, HIGH_SEVERITY, CRITICAL_SEVERITY, + +| description +| +| +| String +| +| + +| categories +| +| +| List of `string` +| +| + +| developerInternalFields +| +| +| <<ListAlertPolicyDevFields_CommonObjectReference,ListAlertPolicyDevFields>> +| +| + +|=== + +[id="StorageListAlertResourceType_CommonObjectReference"] +=== StorageListAlertResourceType + +A special ListAlert-only enumeration of all resource types. Unlike Alert.Resource.ResourceType this also includes deployment as a type This must be kept in sync with Alert.Resource.ResourceType (excluding the deployment value) + +[id="Fields-StorageListAlertResourceType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| DEPLOYMENT +| SECRETS +| CONFIGMAPS +| CLUSTER_ROLES +| CLUSTER_ROLE_BINDINGS +| NETWORK_POLICIES +| SECURITY_CONTEXT_CONSTRAINTS +| EGRESS_FIREWALLS + +|=== + +[id="StorageListDeployment_CommonObjectReference"] +=== StorageListDeployment + +Next available tag: 9 + +[id="Fields-StorageListDeployment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| hash +| +| +| String +| +| uint64 + +| name +| +| +| String +| +| + +| cluster +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| created +| +| +| Date +| +| date-time + +| priority +| +| +| String +| +| int64 + +|=== + +[id="StorageListImage_CommonObjectReference"] +=== StorageListImage + +[id="Fields-StorageListImage_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| components +| +| +| Integer +| +| int32 + +| cves +| +| +| Integer +| +| int32 + +| fixableCves +| +| +| Integer +| +| int32 + +| created +| +| +| Date +| +| date-time + +| lastUpdated +| +| +| Date +| +| date-time + +| priority +| +| +| String +| +| int64 + +|=== + +[id="StorageListPolicy_CommonObjectReference"] +=== StorageListPolicy + +[id="Fields-StorageListPolicy_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| severity +| +| +| <<StorageSeverity_CommonObjectReference,StorageSeverity>> +| +| UNSET_SEVERITY, LOW_SEVERITY, MEDIUM_SEVERITY, HIGH_SEVERITY, CRITICAL_SEVERITY, + +| disabled +| +| +| Boolean +| +| + +| lifecycleStages +| +| +| List of <<StorageLifecycleStage_CommonObjectReference,StorageLifecycleStage>> +| +| + +| notifiers +| +| +| List of `string` +| +| + +| lastUpdated +| +| +| Date +| +| date-time + +| eventSource +| +| +| <<StorageEventSource_CommonObjectReference,StorageEventSource>> +| +| NOT_APPLICABLE, DEPLOYMENT_EVENT, AUDIT_LOG_EVENT, + +| isDefault +| +| +| Boolean +| +| + +| source +| +| +| <<StoragePolicySource_CommonObjectReference,StoragePolicySource>> +| +| IMPERATIVE, DECLARATIVE, + +|=== + +[id="StorageListSecret_CommonObjectReference"] +=== StorageListSecret + +[id="Fields-StorageListSecret_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| types +| +| +| List of <<StorageSecretType_CommonObjectReference,StorageSecretType>> +| +| + +| createdAt +| +| +| Date +| +| date-time + +|=== + +[id="StorageLivenessProbe_CommonObjectReference"] +=== StorageLivenessProbe + +[id="Fields-StorageLivenessProbe_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| defined +| +| +| Boolean +| +| + +|=== + +[id="StorageLoginNotice_CommonObjectReference"] +=== StorageLoginNotice + +[id="Fields-StorageLoginNotice_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enabled +| +| +| Boolean +| +| + +| text +| +| +| String +| +| + +|=== + +[id="StorageManagerType_CommonObjectReference"] +=== StorageManagerType + +[id="Fields-StorageManagerType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| MANAGER_TYPE_UNKNOWN +| MANAGER_TYPE_MANUAL +| MANAGER_TYPE_HELM_CHART +| MANAGER_TYPE_KUBERNETES_OPERATOR + +|=== + +[id="StorageMatchType_CommonObjectReference"] +=== StorageMatchType + +[id="Fields-StorageMatchType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| EXACT +| REGEX + +|=== + +[id="StorageMicrosoftSentinel_CommonObjectReference"] +=== StorageMicrosoftSentinel + +[id="Fields-StorageMicrosoftSentinel_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| logIngestionEndpoint +| +| +| String +| log_ingestion_endpoint is the log ingestion endpoint. +| + +| directoryTenantId +| +| +| String +| directory_tenant_id contains the ID of the Microsoft Directory ID of the selected tenant. +| + +| applicationClientId +| +| +| String +| application_client_id contains the ID of the application ID of the service principal. +| + +| secret +| +| +| String +| secret contains the client secret. +| + +| alertDcrConfig +| +| +| <<MicrosoftSentinelDataCollectionRuleConfig_CommonObjectReference,MicrosoftSentinelDataCollectionRuleConfig>> +| +| + +| auditLogDcrConfig +| +| +| <<MicrosoftSentinelDataCollectionRuleConfig_CommonObjectReference,MicrosoftSentinelDataCollectionRuleConfig>> +| +| + +| clientCertAuthConfig +| +| +| <<MicrosoftSentinelClientCertAuthConfig_CommonObjectReference,MicrosoftSentinelClientCertAuthConfig>> +| +| + +| wifEnabled +| +| +| Boolean +| Enables authentication with short-lived tokens using Azure managed identities or Azure workload identities. The toggle exists to make the use of Azure default credentials explicit rather than always using them as a fallback. The explicit behavior is more consistent with other integrations. +| + +|=== + +[id="StorageMitreAttackVector_CommonObjectReference"] +=== StorageMitreAttackVector + +[id="Fields-StorageMitreAttackVector_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| tactic +| +| +| <<StorageMitreTactic_CommonObjectReference,StorageMitreTactic>> +| +| + +| techniques +| +| +| List of <<StorageMitreTechnique_CommonObjectReference,StorageMitreTechnique>> +| +| + +|=== + +[id="StorageMitreTactic_CommonObjectReference"] +=== StorageMitreTactic + +[id="Fields-StorageMitreTactic_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +|=== + +[id="StorageMitreTechnique_CommonObjectReference"] +=== StorageMitreTechnique + +[id="Fields-StorageMitreTechnique_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +|=== + +[id="StorageNamespaceMetadata_CommonObjectReference"] +=== StorageNamespaceMetadata + +[id="Fields-StorageNamespaceMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| labels +| +| +| Map of `string` +| +| + +| creationTime +| +| +| Date +| +| date-time + +| priority +| +| +| String +| +| int64 + +| annotations +| +| +| Map of `string` +| +| + +|=== + +[id="StorageNetworkBaseline_CommonObjectReference"] +=== StorageNetworkBaseline + +NetworkBaseline represents a network baseline of a deployment. It contains all the baseline peers and their respective connections. next available tag: 8 + +[id="Fields-StorageNetworkBaseline_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deploymentId +| +| +| String +| This is the ID of the baseline. +| + +| clusterId +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| peers +| +| +| List of <<StorageNetworkBaselinePeer_CommonObjectReference,StorageNetworkBaselinePeer>> +| +| + +| forbiddenPeers +| +| +| List of <<StorageNetworkBaselinePeer_CommonObjectReference,StorageNetworkBaselinePeer>> +| A list of peers that will never be added to the baseline. For now, this contains peers that the user has manually removed. This is used to ensure we don't add it back in the event we see the flow again. +| + +| observationPeriodEnd +| +| +| Date +| +| date-time + +| locked +| +| +| Boolean +| +| + +| deploymentName +| +| +| String +| +| + +|=== + +[id="StorageNetworkBaselineConnectionProperties_CommonObjectReference"] +=== StorageNetworkBaselineConnectionProperties + +NetworkBaselineConnectionProperties represents information about a baseline connection next available tag: 4 + +[id="Fields-StorageNetworkBaselineConnectionProperties_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| ingress +| +| +| Boolean +| +| + +| port +| +| +| Long +| +| int64 + +| protocol +| +| +| <<StorageL4Protocol_CommonObjectReference,StorageL4Protocol>> +| +| L4_PROTOCOL_UNKNOWN, L4_PROTOCOL_TCP, L4_PROTOCOL_UDP, L4_PROTOCOL_ICMP, L4_PROTOCOL_RAW, L4_PROTOCOL_SCTP, L4_PROTOCOL_ANY, + +|=== + +[id="StorageNetworkBaselinePeer_CommonObjectReference"] +=== StorageNetworkBaselinePeer + +NetworkBaselinePeer represents a baseline peer. next available tag: 3 + +[id="Fields-StorageNetworkBaselinePeer_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entity +| +| +| <<StorageNetworkEntity_CommonObjectReference,StorageNetworkEntity>> +| +| + +| properties +| +| +| List of <<StorageNetworkBaselineConnectionProperties_CommonObjectReference,StorageNetworkBaselineConnectionProperties>> +| +| + +|=== + +[id="StorageNetworkEntity_CommonObjectReference"] +=== StorageNetworkEntity + +[id="Fields-StorageNetworkEntity_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| info +| +| +| <<StorageNetworkEntityInfo_CommonObjectReference,StorageNetworkEntityInfo>> +| +| + +| scope +| +| +| <<StorageNetworkEntityScope_CommonObjectReference,StorageNetworkEntityScope>> +| +| + +|=== + +[id="StorageNetworkEntityInfo_CommonObjectReference"] +=== StorageNetworkEntityInfo + +[id="Fields-StorageNetworkEntityInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| <<StorageNetworkEntityInfoType_CommonObjectReference,StorageNetworkEntityInfoType>> +| +| UNKNOWN_TYPE, DEPLOYMENT, INTERNET, LISTEN_ENDPOINT, EXTERNAL_SOURCE, INTERNAL_ENTITIES, + +| id +| +| +| String +| +| + +| deployment +| +| +| <<StorageNetworkEntityInfoDeployment_CommonObjectReference,StorageNetworkEntityInfoDeployment>> +| +| + +| externalSource +| +| +| <<NetworkEntityInfoExternalSource_CommonObjectReference,NetworkEntityInfoExternalSource>> +| +| + +|=== + +[id="StorageNetworkEntityInfoDeployment_CommonObjectReference"] +=== StorageNetworkEntityInfoDeployment + +[id="Fields-StorageNetworkEntityInfoDeployment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| cluster +| +| +| String +| +| + +| listenPorts +| +| +| List of <<DeploymentListenPort_CommonObjectReference,DeploymentListenPort>> +| +| + +|=== + +[id="StorageNetworkEntityInfoType_CommonObjectReference"] +=== StorageNetworkEntityInfoType + +- INTERNAL_ENTITIES: INTERNAL_ENTITIES is for grouping all internal entities under a single network graph node + +[id="Fields-StorageNetworkEntityInfoType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN_TYPE +| DEPLOYMENT +| INTERNET +| LISTEN_ENDPOINT +| EXTERNAL_SOURCE +| INTERNAL_ENTITIES + +|=== + +[id="StorageNetworkEntityScope_CommonObjectReference"] +=== StorageNetworkEntityScope + +[id="Fields-StorageNetworkEntityScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +|=== + +[id="StorageNetworkFlow_CommonObjectReference"] +=== StorageNetworkFlow + +[id="Fields-StorageNetworkFlow_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| props +| +| +| <<StorageNetworkFlowProperties_CommonObjectReference,StorageNetworkFlowProperties>> +| +| + +| lastSeenTimestamp +| +| +| Date +| +| date-time + +| clusterId +| +| +| String +| +| + +| updatedAt +| +| +| Date +| +| date-time + +|=== + +[id="StorageNetworkFlowProperties_CommonObjectReference"] +=== StorageNetworkFlowProperties + +[id="Fields-StorageNetworkFlowProperties_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| srcEntity +| +| +| <<StorageNetworkEntityInfo_CommonObjectReference,StorageNetworkEntityInfo>> +| +| + +| dstEntity +| +| +| <<StorageNetworkEntityInfo_CommonObjectReference,StorageNetworkEntityInfo>> +| +| + +| dstPort +| +| +| Long +| may be 0 if not applicable (e.g., icmp). +| int64 + +| l4protocol +| +| +| <<StorageL4Protocol_CommonObjectReference,StorageL4Protocol>> +| +| L4_PROTOCOL_UNKNOWN, L4_PROTOCOL_TCP, L4_PROTOCOL_UDP, L4_PROTOCOL_ICMP, L4_PROTOCOL_RAW, L4_PROTOCOL_SCTP, L4_PROTOCOL_ANY, + +|=== + +[id="StorageNetworkGraphConfig_CommonObjectReference"] +=== StorageNetworkGraphConfig + +[id="Fields-StorageNetworkGraphConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| hideDefaultExternalSrcs +| +| +| Boolean +| +| + +|=== + +[id="StorageNetworkPolicy_CommonObjectReference"] +=== StorageNetworkPolicy + +[id="Fields-StorageNetworkPolicy_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| labels +| +| +| Map of `string` +| +| + +| annotations +| +| +| Map of `string` +| +| + +| spec +| +| +| <<StorageNetworkPolicySpec_CommonObjectReference,StorageNetworkPolicySpec>> +| +| + +| yaml +| +| +| String +| +| + +| apiVersion +| +| +| String +| +| + +| created +| +| +| Date +| +| date-time + +|=== + +[id="StorageNetworkPolicyApplicationUndoRecord_CommonObjectReference"] +=== StorageNetworkPolicyApplicationUndoRecord + +[id="Fields-StorageNetworkPolicyApplicationUndoRecord_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| user +| +| +| String +| +| + +| applyTimestamp +| +| +| Date +| +| date-time + +| originalModification +| +| +| <<StorageNetworkPolicyModification_CommonObjectReference,StorageNetworkPolicyModification>> +| +| + +| undoModification +| +| +| <<StorageNetworkPolicyModification_CommonObjectReference,StorageNetworkPolicyModification>> +| +| + +|=== + +[id="StorageNetworkPolicyEgressRule_CommonObjectReference"] +=== StorageNetworkPolicyEgressRule + +[id="Fields-StorageNetworkPolicyEgressRule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| ports +| +| +| List of <<StorageNetworkPolicyPort_CommonObjectReference,StorageNetworkPolicyPort>> +| +| + +| to +| +| +| List of <<StorageNetworkPolicyPeer_CommonObjectReference,StorageNetworkPolicyPeer>> +| +| + +|=== + +[id="StorageNetworkPolicyIngressRule_CommonObjectReference"] +=== StorageNetworkPolicyIngressRule + +[id="Fields-StorageNetworkPolicyIngressRule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| ports +| +| +| List of <<StorageNetworkPolicyPort_CommonObjectReference,StorageNetworkPolicyPort>> +| +| + +| from +| +| +| List of <<StorageNetworkPolicyPeer_CommonObjectReference,StorageNetworkPolicyPeer>> +| +| + +|=== + +[id="StorageNetworkPolicyModification_CommonObjectReference"] +=== StorageNetworkPolicyModification + +Next available tag: 3 + +[id="Fields-StorageNetworkPolicyModification_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| applyYaml +| +| +| String +| +| + +| toDelete +| +| +| List of <<StorageNetworkPolicyReference_CommonObjectReference,StorageNetworkPolicyReference>> +| +| + +|=== + +[id="StorageNetworkPolicyPeer_CommonObjectReference"] +=== StorageNetworkPolicyPeer + +[id="Fields-StorageNetworkPolicyPeer_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| podSelector +| +| +| <<StorageLabelSelector_CommonObjectReference,StorageLabelSelector>> +| +| + +| namespaceSelector +| +| +| <<StorageLabelSelector_CommonObjectReference,StorageLabelSelector>> +| +| + +| ipBlock +| +| +| <<StorageIPBlock_CommonObjectReference,StorageIPBlock>> +| +| + +|=== + +[id="StorageNetworkPolicyPort_CommonObjectReference"] +=== StorageNetworkPolicyPort + +[id="Fields-StorageNetworkPolicyPort_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| protocol +| +| +| <<StorageProtocol_CommonObjectReference,StorageProtocol>> +| +| UNSET_PROTOCOL, TCP_PROTOCOL, UDP_PROTOCOL, SCTP_PROTOCOL, + +| port +| +| +| Integer +| +| int32 + +| portName +| +| +| String +| +| + +|=== + +[id="StorageNetworkPolicyReference_CommonObjectReference"] +=== StorageNetworkPolicyReference + +Next available tag: 3 + +[id="Fields-StorageNetworkPolicyReference_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| namespace +| +| +| String +| +| + +| name +| +| +| String +| +| + +|=== + +[id="StorageNetworkPolicySpec_CommonObjectReference"] +=== StorageNetworkPolicySpec + +[id="Fields-StorageNetworkPolicySpec_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| podSelector +| +| +| <<StorageLabelSelector_CommonObjectReference,StorageLabelSelector>> +| +| + +| ingress +| +| +| List of <<StorageNetworkPolicyIngressRule_CommonObjectReference,StorageNetworkPolicyIngressRule>> +| +| + +| egress +| +| +| List of <<StorageNetworkPolicyEgressRule_CommonObjectReference,StorageNetworkPolicyEgressRule>> +| +| + +| policyTypes +| +| +| List of <<StorageNetworkPolicyType_CommonObjectReference,StorageNetworkPolicyType>> +| +| + +|=== + +[id="StorageNetworkPolicyType_CommonObjectReference"] +=== StorageNetworkPolicyType + +[id="Fields-StorageNetworkPolicyType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET_NETWORK_POLICY_TYPE +| INGRESS_NETWORK_POLICY_TYPE +| EGRESS_NETWORK_POLICY_TYPE + +|=== + +[id="StorageNode_CommonObjectReference"] +=== StorageNode + +Node represents information about a node in the cluster. next available tag: 28 + +[id="Fields-StorageNode_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| A unique ID identifying this node. +| + +| name +| +| +| String +| The (host)name of the node. Might or might not be the same as ID. +| + +| taints +| +| +| List of <<StorageTaint_CommonObjectReference,StorageTaint>> +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| labels +| +| +| Map of `string` +| +| + +| annotations +| +| +| Map of `string` +| +| + +| joinedAt +| +| +| Date +| +| date-time + +| internalIpAddresses +| +| +| List of `string` +| +| + +| externalIpAddresses +| +| +| List of `string` +| +| + +| containerRuntimeVersion +| +| +| String +| Use container_runtime.version +| + +| containerRuntime +| +| +| <<StorageContainerRuntimeInfo_CommonObjectReference,StorageContainerRuntimeInfo>> +| +| + +| kernelVersion +| +| +| String +| +| + +| operatingSystem +| +| +| String +| From NodeInfo. Operating system reported by the node (ex: linux). +| + +| osImage +| +| +| String +| From NodeInfo. OS image reported by the node from /etc/os-release. +| + +| kubeletVersion +| +| +| String +| +| + +| kubeProxyVersion +| +| +| String +| +| + +| lastUpdated +| +| +| Date +| +| date-time + +| k8sUpdated +| +| +| Date +| Time we received an update from Kubernetes. +| date-time + +| scan +| +| +| <<StorageNodeScan_CommonObjectReference,StorageNodeScan>> +| +| + +| components +| +| +| Integer +| +| int32 + +| cves +| +| +| Integer +| +| int32 + +| fixableCves +| +| +| Integer +| +| int32 + +| priority +| +| +| String +| +| int64 + +| riskScore +| +| +| Float +| +| float + +| topCvss +| +| +| Float +| +| float + +| notes +| +| +| List of <<StorageNodeNote_CommonObjectReference,StorageNodeNote>> +| +| + +|=== + +[id="StorageNodeNote_CommonObjectReference"] +=== StorageNodeNote + +[id="Fields-StorageNodeNote_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| MISSING_SCAN_DATA + +|=== + +[id="StorageNodeScan_CommonObjectReference"] +=== StorageNodeScan + +Next tag: 5 + +[id="Fields-StorageNodeScan_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanTime +| +| +| Date +| +| date-time + +| operatingSystem +| +| +| String +| +| + +| components +| +| +| List of <<StorageEmbeddedNodeScanComponent_CommonObjectReference,StorageEmbeddedNodeScanComponent>> +| +| + +| notes +| +| +| List of <<StorageNodeScanNote_CommonObjectReference,StorageNodeScanNote>> +| +| + +| scannerVersion +| +| +| <<NodeScanScanner_CommonObjectReference,NodeScanScanner>> +| +| SCANNER, SCANNER_V4, + +|=== + +[id="StorageNodeScanNote_CommonObjectReference"] +=== StorageNodeScanNote + +[id="Fields-StorageNodeScanNote_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| UNSUPPORTED +| KERNEL_UNSUPPORTED +| CERTIFIED_RHEL_CVES_UNAVAILABLE + +|=== + +[id="StorageNodeVulnerability_CommonObjectReference"] +=== StorageNodeVulnerability + +[id="Fields-StorageNodeVulnerability_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cveBaseInfo +| +| +| <<StorageCVEInfo_CommonObjectReference,StorageCVEInfo>> +| +| + +| cvss +| +| +| Float +| +| float + +| severity +| +| +| <<StorageVulnerabilitySeverity_CommonObjectReference,StorageVulnerabilitySeverity>> +| +| UNKNOWN_VULNERABILITY_SEVERITY, LOW_VULNERABILITY_SEVERITY, MODERATE_VULNERABILITY_SEVERITY, IMPORTANT_VULNERABILITY_SEVERITY, CRITICAL_VULNERABILITY_SEVERITY, + +| fixedBy +| +| +| String +| +| + +| snoozed +| +| +| Boolean +| +| + +| snoozeStart +| +| +| Date +| +| date-time + +| snoozeExpiry +| +| +| Date +| +| date-time + +|=== + +[id="StorageNotifier_CommonObjectReference"] +=== StorageNotifier + +Next Tag: 21 + +[id="Fields-StorageNotifier_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| String +| +| + +| uiEndpoint +| +| +| String +| +| + +| labelKey +| +| +| String +| +| + +| labelDefault +| +| +| String +| +| + +| jira +| +| +| <<StorageJira_CommonObjectReference,StorageJira>> +| +| + +| email +| +| +| <<StorageEmail_CommonObjectReference,StorageEmail>> +| +| + +| cscc +| +| +| <<StorageCSCC_CommonObjectReference,StorageCSCC>> +| +| + +| splunk +| +| +| <<StorageSplunk_CommonObjectReference,StorageSplunk>> +| +| + +| pagerduty +| +| +| <<StoragePagerDuty_CommonObjectReference,StoragePagerDuty>> +| +| + +| generic +| +| +| <<StorageGeneric_CommonObjectReference,StorageGeneric>> +| +| + +| sumologic +| +| +| <<StorageSumoLogic_CommonObjectReference,StorageSumoLogic>> +| +| + +| awsSecurityHub +| +| +| <<StorageAWSSecurityHub_CommonObjectReference,StorageAWSSecurityHub>> +| +| + +| syslog +| +| +| <<StorageSyslog_CommonObjectReference,StorageSyslog>> +| +| + +| microsoftSentinel +| +| +| <<StorageMicrosoftSentinel_CommonObjectReference,StorageMicrosoftSentinel>> +| +| + +| notifierSecret +| +| +| String +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="StorageNotifierConfiguration_CommonObjectReference"] +=== StorageNotifierConfiguration + +[id="Fields-StorageNotifierConfiguration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| emailConfig +| +| +| <<StorageEmailNotifierConfiguration_CommonObjectReference,StorageEmailNotifierConfiguration>> +| +| + +| id +| +| +| String +| +| + +|=== + +[id="StorageOperationStatus_CommonObjectReference"] +=== StorageOperationStatus + +[id="Fields-StorageOperationStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| FAIL +| PASS + +|=== + +[id="StorageOrchestratorMetadata_CommonObjectReference"] +=== StorageOrchestratorMetadata + +[id="Fields-StorageOrchestratorMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| version +| +| +| String +| +| + +| openshiftVersion +| +| +| String +| +| + +| buildDate +| +| +| Date +| +| date-time + +| apiVersions +| +| +| List of `string` +| +| + +|=== + +[id="StoragePagerDuty_CommonObjectReference"] +=== StoragePagerDuty + +[id="Fields-StoragePagerDuty_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| apiKey +| +| +| String +| The API key for the integration. The server will mask the value of this credential in responses and logs. +| + +|=== + +[id="StoragePermissionLevel_CommonObjectReference"] +=== StoragePermissionLevel + +For any update to PermissionLevel, also update: - pkg/searchbasedpolicies/builders/k8s_rbac.go - ui/src/messages/common.js + +[id="Fields-StoragePermissionLevel_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| NONE +| DEFAULT +| ELEVATED_IN_NAMESPACE +| ELEVATED_CLUSTER_WIDE +| CLUSTER_ADMIN + +|=== + +[id="StoragePermissionSet_CommonObjectReference"] +=== StoragePermissionSet + +This encodes a set of permissions for StackRox resources. + +[id="Fields-StoragePermissionSet_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| id is generated and cannot be changed. +| + +| name +| +| +| String +| `name` and `description` are provided by the user and can be changed. +| + +| description +| +| +| String +| +| + +| resourceToAccess +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="StoragePlatformComponentConfig_CommonObjectReference"] +=== StoragePlatformComponentConfig + +[id="Fields-StoragePlatformComponentConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| rules +| +| +| List of <<PlatformComponentConfigRule_CommonObjectReference,PlatformComponentConfigRule>> +| +| + +| needsReevaluation +| +| +| Boolean +| +| + +|=== + +[id="StoragePod_CommonObjectReference"] +=== StoragePod + +Pod represents information for a currently running pod or deleted pod in an active deployment. + +[id="Fields-StoragePod_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| deploymentId +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| liveInstances +| +| +| List of <<StorageContainerInstance_CommonObjectReference,StorageContainerInstance>> +| +| + +| terminatedInstances +| +| +| List of <<PodContainerInstanceList_CommonObjectReference,PodContainerInstanceList>> +| Must be a list of lists, so we can perform search queries (does not work for maps that aren't <string, string>) There is one bucket (list) per container name. +| + +| started +| +| +| Date +| Time Kubernetes reports the pod was created. +| date-time + +|=== + +[id="StoragePolicy_CommonObjectReference"] +=== StoragePolicy + +Next tag: 28 + +[id="Fields-StoragePolicy_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| Name of the policy. Must be unique. +| + +| description +| +| +| String +| Free-form text description of this policy. +| + +| rationale +| +| +| String +| +| + +| remediation +| +| +| String +| Describes how to remediate a violation of this policy. +| + +| disabled +| +| +| Boolean +| Toggles whether or not this policy will be executing and actively firing alerts. +| + +| categories +| +| +| List of `string` +| List of categories that this policy falls under. Category names must already exist in Central. +| + +| lifecycleStages +| +| +| List of <<StorageLifecycleStage_CommonObjectReference,StorageLifecycleStage>> +| Describes which policy lifecylce stages this policy applies to. Choices are DEPLOY, BUILD, and RUNTIME. +| + +| eventSource +| +| +| <<StorageEventSource_CommonObjectReference,StorageEventSource>> +| +| NOT_APPLICABLE, DEPLOYMENT_EVENT, AUDIT_LOG_EVENT, + +| exclusions +| +| +| List of <<StorageExclusion_CommonObjectReference,StorageExclusion>> +| Define deployments or images that should be excluded from this policy. +| + +| scope +| +| +| List of <<StorageScope_CommonObjectReference,StorageScope>> +| Defines clusters, namespaces, and deployments that should be included in this policy. No scopes defined includes everything. +| + +| severity +| +| +| <<StorageSeverity_CommonObjectReference,StorageSeverity>> +| +| UNSET_SEVERITY, LOW_SEVERITY, MEDIUM_SEVERITY, HIGH_SEVERITY, CRITICAL_SEVERITY, + +| enforcementActions +| +| +| List of <<StorageEnforcementAction_CommonObjectReference,StorageEnforcementAction>> +| FAIL_DEPLOYMENT_CREATE_ENFORCEMENT takes effect only if admission control webhook is configured to enforce on object creates/updates. FAIL_KUBE_REQUEST_ENFORCEMENT takes effect only if admission control webhook is enabled to listen on exec and port-forward events. FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT takes effect only if admission control webhook is configured to enforce on object updates. Lists the enforcement actions to take when a violation from this policy is identified. Possible value are UNSET_ENFORCEMENT, SCALE_TO_ZERO_ENFORCEMENT, UNSATISFIABLE_NODE_CONSTRAINT_ENFORCEMENT, KILL_POD_ENFORCEMENT, FAIL_BUILD_ENFORCEMENT, FAIL_KUBE_REQUEST_ENFORCEMENT, FAIL_DEPLOYMENT_CREATE_ENFORCEMENT, and. FAIL_DEPLOYMENT_UPDATE_ENFORCEMENT. +| + +| notifiers +| +| +| List of `string` +| List of IDs of the notifiers that should be triggered when a violation from this policy is identified. IDs should be in the form of a UUID and are found through the Central API. +| + +| lastUpdated +| +| +| Date +| +| date-time + +| SORTName +| +| +| String +| For internal use only. +| + +| SORTLifecycleStage +| +| +| String +| For internal use only. +| + +| SORTEnforcement +| +| +| Boolean +| For internal use only. +| + +| policyVersion +| +| +| String +| +| + +| policySections +| +| +| List of <<StoragePolicySection_CommonObjectReference,StoragePolicySection>> +| PolicySections define the violation criteria for this policy. +| + +| mitreAttackVectors +| +| +| List of <<PolicyMitreAttackVectors_CommonObjectReference,PolicyMitreAttackVectors>> +| +| + +| criteriaLocked +| +| +| Boolean +| Read-only field. If true, the policy's criteria fields are rendered read-only. +| + +| mitreVectorsLocked +| +| +| Boolean +| Read-only field. If true, the policy's MITRE ATT&CK fields are rendered read-only. +| + +| isDefault +| +| +| Boolean +| Read-only field. Indicates the policy is a default policy if true and a custom policy if false. +| + +| source +| +| +| <<StoragePolicySource_CommonObjectReference,StoragePolicySource>> +| +| IMPERATIVE, DECLARATIVE, + +|=== + +[id="StoragePolicyGroup_CommonObjectReference"] +=== StoragePolicyGroup + +[id="Fields-StoragePolicyGroup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| fieldName +| +| +| String +| Defines which field on a deployment or image this PolicyGroup evaluates. See https://docs.openshift.com/acs/operating/manage-security-policies.html#policy-criteria_manage-security-policies for a complete list of possible values. +| + +| booleanOperator +| +| +| <<StorageBooleanOperator_CommonObjectReference,StorageBooleanOperator>> +| +| OR, AND, + +| negate +| +| +| Boolean +| Determines if the evaluation of this PolicyGroup is negated. Default to false. +| + +| values +| +| +| List of <<StoragePolicyValue_CommonObjectReference,StoragePolicyValue>> +| +| + +|=== + +[id="StoragePolicyRule_CommonObjectReference"] +=== StoragePolicyRule + +Properties of an individual rules that grant permissions to resources. //////////////////////////////////////// + +[id="Fields-StoragePolicyRule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| verbs +| +| +| List of `string` +| +| + +| apiGroups +| +| +| List of `string` +| +| + +| resources +| +| +| List of `string` +| +| + +| nonResourceUrls +| +| +| List of `string` +| +| + +| resourceNames +| +| +| List of `string` +| +| + +|=== + +[id="StoragePolicySection_CommonObjectReference"] +=== StoragePolicySection + +[id="Fields-StoragePolicySection_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| sectionName +| +| +| String +| +| + +| policyGroups +| +| +| List of <<StoragePolicyGroup_CommonObjectReference,StoragePolicyGroup>> +| The set of policies groups that make up this section. Each group can be considered an individual criterion. +| + +|=== + +[id="StoragePolicySource_CommonObjectReference"] +=== StoragePolicySource + +[id="Fields-StoragePolicySource_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| IMPERATIVE +| DECLARATIVE + +|=== + +[id="StoragePolicyValue_CommonObjectReference"] +=== StoragePolicyValue + +[id="Fields-StoragePolicyValue_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| value +| +| +| String +| +| + +|=== + +[id="StoragePortConfig_CommonObjectReference"] +=== StoragePortConfig + +Next Available Tag: 6 + +[id="Fields-StoragePortConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| containerPort +| +| +| Integer +| +| int32 + +| protocol +| +| +| String +| +| + +| exposure +| +| +| <<PortConfigExposureLevel_CommonObjectReference,PortConfigExposureLevel>> +| +| UNSET, EXTERNAL, NODE, INTERNAL, HOST, ROUTE, + +| exposedPort +| +| +| Integer +| +| int32 + +| exposureInfos +| +| +| List of <<PortConfigExposureInfo_CommonObjectReference,PortConfigExposureInfo>> +| +| + +|=== + +[id="StoragePrivateConfig_CommonObjectReference"] +=== StoragePrivateConfig + +next available tag:9 + +[id="Fields-StoragePrivateConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| DEPRECATEDAlertRetentionDurationDays +| +| +| Integer +| +| int32 + +| alertConfig +| +| +| <<StorageAlertRetentionConfig_CommonObjectReference,StorageAlertRetentionConfig>> +| +| + +| imageRetentionDurationDays +| +| +| Integer +| +| int32 + +| expiredVulnReqRetentionDurationDays +| +| +| Integer +| +| int32 + +| decommissionedClusterRetention +| +| +| <<StorageDecommissionedClusterRetentionConfig_CommonObjectReference,StorageDecommissionedClusterRetentionConfig>> +| +| + +| reportRetentionConfig +| +| +| <<StorageReportRetentionConfig_CommonObjectReference,StorageReportRetentionConfig>> +| +| + +| vulnerabilityExceptionConfig +| +| +| <<StorageVulnerabilityExceptionConfig_CommonObjectReference,StorageVulnerabilityExceptionConfig>> +| +| + +| administrationEventsConfig +| +| +| <<StorageAdministrationEventsConfig_CommonObjectReference,StorageAdministrationEventsConfig>> +| +| + +|=== + +[id="StorageProcessBaseline_CommonObjectReference"] +=== StorageProcessBaseline + +[id="Fields-StorageProcessBaseline_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| key +| +| +| <<StorageProcessBaselineKey_CommonObjectReference,StorageProcessBaselineKey>> +| +| + +| elements +| +| +| List of <<StorageBaselineElement_CommonObjectReference,StorageBaselineElement>> +| +| + +| elementGraveyard +| +| +| List of <<StorageBaselineElement_CommonObjectReference,StorageBaselineElement>> +| +| + +| created +| +| +| Date +| +| date-time + +| userLockedTimestamp +| +| +| Date +| +| date-time + +| stackRoxLockedTimestamp +| +| +| Date +| +| date-time + +| lastUpdate +| +| +| Date +| +| date-time + +|=== + +[id="StorageProcessBaselineKey_CommonObjectReference"] +=== StorageProcessBaselineKey + +[id="Fields-StorageProcessBaselineKey_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deploymentId +| +| +| String +| The idea is for the keys to be flexible. Only certain combinations of these will be supported. +| + +| containerName +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +|=== + +[id="StorageProcessIndicator_CommonObjectReference"] +=== StorageProcessIndicator + +Next available tag: 13 + +[id="Fields-StorageProcessIndicator_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| deploymentId +| +| +| String +| +| + +| containerName +| +| +| String +| +| + +| podId +| +| +| String +| +| + +| podUid +| +| +| String +| +| + +| signal +| +| +| <<StorageProcessSignal_CommonObjectReference,StorageProcessSignal>> +| +| + +| clusterId +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| containerStartTime +| +| +| Date +| +| date-time + +| imageId +| +| +| String +| +| + +|=== + +[id="StorageProcessListeningOnPort_CommonObjectReference"] +=== StorageProcessListeningOnPort + +The API returns an array of these + +[id="Fields-StorageProcessListeningOnPort_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| <<ProcessListeningOnPortEndpoint_CommonObjectReference,ProcessListeningOnPortEndpoint>> +| +| + +| deploymentId +| +| +| String +| +| + +| containerName +| +| +| String +| +| + +| podId +| +| +| String +| +| + +| podUid +| +| +| String +| +| + +| signal +| +| +| <<StorageProcessSignal_CommonObjectReference,StorageProcessSignal>> +| +| + +| clusterId +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| containerStartTime +| +| +| Date +| +| date-time + +| imageId +| +| +| String +| +| + +|=== + +[id="StorageProcessSignal_CommonObjectReference"] +=== StorageProcessSignal + +[id="Fields-StorageProcessSignal_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| A unique UUID for identifying the message We have this here instead of at the top level because we want to have each message to be self contained. +| + +| containerId +| +| +| String +| +| + +| time +| +| +| Date +| +| date-time + +| name +| +| +| String +| +| + +| args +| +| +| String +| +| + +| execFilePath +| +| +| String +| +| + +| pid +| +| +| Long +| +| int64 + +| uid +| +| +| Long +| +| int64 + +| gid +| +| +| Long +| +| int64 + +| lineage +| +| +| List of `string` +| +| + +| scraped +| +| +| Boolean +| +| + +| lineageInfo +| +| +| List of <<ProcessSignalLineageInfo_CommonObjectReference,ProcessSignalLineageInfo>> +| +| + +|=== + +[id="StorageProtocol_CommonObjectReference"] +=== StorageProtocol + +[id="Fields-StorageProtocol_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET_PROTOCOL +| TCP_PROTOCOL +| UDP_PROTOCOL +| SCTP_PROTOCOL + +|=== + +[id="StorageProviderMetadata_CommonObjectReference"] +=== StorageProviderMetadata + +[id="Fields-StorageProviderMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| region +| +| +| String +| +| + +| zone +| +| +| String +| +| + +| google +| +| +| <<StorageGoogleProviderMetadata_CommonObjectReference,StorageGoogleProviderMetadata>> +| +| + +| aws +| +| +| <<StorageAWSProviderMetadata_CommonObjectReference,StorageAWSProviderMetadata>> +| +| + +| azure +| +| +| <<StorageAzureProviderMetadata_CommonObjectReference,StorageAzureProviderMetadata>> +| +| + +| verified +| +| +| Boolean +| +| + +| cluster +| +| +| <<StorageClusterMetadata_CommonObjectReference,StorageClusterMetadata>> +| +| + +|=== + +[id="StoragePublicConfig_CommonObjectReference"] +=== StoragePublicConfig + +[id="Fields-StoragePublicConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| loginNotice +| +| +| <<StorageLoginNotice_CommonObjectReference,StorageLoginNotice>> +| +| + +| header +| +| +| <<StorageBannerConfig_CommonObjectReference,StorageBannerConfig>> +| +| + +| footer +| +| +| <<StorageBannerConfig_CommonObjectReference,StorageBannerConfig>> +| +| + +| telemetry +| +| +| <<StorageTelemetryConfiguration_CommonObjectReference,StorageTelemetryConfiguration>> +| +| + +|=== + +[id="StorageQuayConfig_CommonObjectReference"] +=== StorageQuayConfig + +[id="Fields-StorageQuayConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| oauthToken +| +| +| String +| The OAuth token for the integration. Required if this is a scanner integration. The server will mask the value of this credential in responses and logs. +| + +| insecure +| +| +| Boolean +| +| + +| registryRobotCredentials +| +| +| <<QuayConfigRobotAccount_CommonObjectReference,QuayConfigRobotAccount>> +| +| + +|=== + +[id="StorageReadinessProbe_CommonObjectReference"] +=== StorageReadinessProbe + +[id="Fields-StorageReadinessProbe_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| defined +| +| +| Boolean +| +| + +|=== + +[id="StorageReportConfiguration_CommonObjectReference"] +=== StorageReportConfiguration + +[id="Fields-StorageReportConfiguration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| type +| +| +| <<ReportConfigurationReportType_CommonObjectReference,ReportConfigurationReportType>> +| +| VULNERABILITY, + +| vulnReportFilters +| +| +| <<StorageVulnerabilityReportFilters_CommonObjectReference,StorageVulnerabilityReportFilters>> +| +| + +| scopeId +| +| +| String +| +| + +| emailConfig +| +| +| <<StorageEmailNotifierConfiguration_CommonObjectReference,StorageEmailNotifierConfiguration>> +| +| + +| schedule +| +| +| <<StorageSchedule_CommonObjectReference,StorageSchedule>> +| +| + +| lastRunStatus +| +| +| <<StorageReportLastRunStatus_CommonObjectReference,StorageReportLastRunStatus>> +| +| + +| lastSuccessfulRunTime +| +| +| Date +| +| date-time + +| resourceScope +| +| +| <<StorageResourceScope_CommonObjectReference,StorageResourceScope>> +| +| + +| notifiers +| +| +| List of <<StorageNotifierConfiguration_CommonObjectReference,StorageNotifierConfiguration>> +| +| + +| creator +| +| +| <<StorageSlimUser_CommonObjectReference,StorageSlimUser>> +| +| + +| version +| +| +| Integer +| +| int32 + +|=== + +[id="StorageReportLastRunStatus_CommonObjectReference"] +=== StorageReportLastRunStatus + +[id="Fields-StorageReportLastRunStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportStatus +| +| +| <<ReportLastRunStatusRunStatus_CommonObjectReference,ReportLastRunStatusRunStatus>> +| +| SUCCESS, FAILURE, + +| lastRunTime +| +| +| Date +| +| date-time + +| errorMsg +| +| +| String +| +| + +|=== + +[id="StorageReportRetentionConfig_CommonObjectReference"] +=== StorageReportRetentionConfig + +next available tag: 4 + +[id="Fields-StorageReportRetentionConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| historyRetentionDurationDays +| +| +| Long +| +| int64 + +| downloadableReportRetentionDays +| +| +| Long +| +| int64 + +| downloadableReportGlobalRetentionBytes +| +| +| Long +| +| int64 + +|=== + +[id="StorageRequestComment_CommonObjectReference"] +=== StorageRequestComment + +[id="Fields-StorageRequestComment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| message +| +| +| String +| +| + +| user +| +| +| <<StorageSlimUser_CommonObjectReference,StorageSlimUser>> +| +| + +| createdAt +| +| +| Date +| +| date-time + +|=== + +[id="StorageRequestExpiry_CommonObjectReference"] +=== StorageRequestExpiry + +[id="Fields-StorageRequestExpiry_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| expiresWhenFixed +| +| +| Boolean +| Indicates that this request expires when the associated vulnerability is fixed. +| + +| expiresOn +| +| +| Date +| Indicates the timestamp when this request expires. +| date-time + +| expiryType +| +| +| <<RequestExpiryExpiryType_CommonObjectReference,RequestExpiryExpiryType>> +| +| TIME, ALL_CVE_FIXABLE, ANY_CVE_FIXABLE, + +|=== + +[id="StorageRequestStatus_CommonObjectReference"] +=== StorageRequestStatus + +Indicates the status of a request. Requests canceled by the user before they are acted upon by the approver +are not tracked/persisted (with the exception of audit logs if it is turned on). + + - PENDING: Default request state. It indicates that the request has not been fulfilled and that an action (approve/deny) is required. + - APPROVED: Indicates that the request has been approved by the approver. + - DENIED: Indicates that the request has been denied by the approver. + - APPROVED_PENDING_UPDATE: Indicates that the original request was approved, but an update is still pending an approval or denial. + +[id="Fields-StorageRequestStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| PENDING +| APPROVED +| DENIED +| APPROVED_PENDING_UPDATE + +|=== + +[id="StorageRequester_CommonObjectReference"] +=== StorageRequester + +[id="Fields-StorageRequester_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +|=== + +[id="StorageResourceCollection_CommonObjectReference"] +=== StorageResourceCollection + +[id="Fields-StorageResourceCollection_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| createdAt +| +| +| Date +| +| date-time + +| lastUpdated +| +| +| Date +| +| date-time + +| createdBy +| +| +| <<StorageSlimUser_CommonObjectReference,StorageSlimUser>> +| +| + +| updatedBy +| +| +| <<StorageSlimUser_CommonObjectReference,StorageSlimUser>> +| +| + +| resourceSelectors +| +| +| List of <<StorageResourceSelector_CommonObjectReference,StorageResourceSelector>> +| `resource_selectors` resolve as disjunction (OR) with each-other and with selectors from `embedded_collections`. For MVP, the size of resource_selectors will at most be 1 from UX standpoint. +| + +| embeddedCollections +| +| +| List of <<ResourceCollectionEmbeddedResourceCollection_CommonObjectReference,ResourceCollectionEmbeddedResourceCollection>> +| +| + +|=== + +[id="StorageResourceScope_CommonObjectReference"] +=== StorageResourceScope + +[id="Fields-StorageResourceScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| collectionId +| +| +| String +| +| + +|=== + +[id="StorageResourceSelector_CommonObjectReference"] +=== StorageResourceSelector + +[id="Fields-StorageResourceSelector_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| rules +| +| +| List of <<StorageSelectorRule_CommonObjectReference,StorageSelectorRule>> +| `rules` resolve as a conjunction (AND). +| + +|=== + +[id="StorageResources_CommonObjectReference"] +=== StorageResources + +[id="Fields-StorageResources_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cpuCoresRequest +| +| +| Float +| +| float + +| cpuCoresLimit +| +| +| Float +| +| float + +| memoryMbRequest +| +| +| Float +| +| float + +| memoryMbLimit +| +| +| Float +| +| float + +|=== + +[id="StorageRisk_CommonObjectReference"] +=== StorageRisk + +[id="Fields-StorageRisk_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| subject +| +| +| <<StorageRiskSubject_CommonObjectReference,StorageRiskSubject>> +| +| + +| score +| +| +| Float +| +| float + +| results +| +| +| List of <<StorageRiskResult_CommonObjectReference,StorageRiskResult>> +| +| + +|=== + +[id="StorageRiskResult_CommonObjectReference"] +=== StorageRiskResult + +[id="Fields-StorageRiskResult_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| factors +| +| +| List of <<ResultFactor_CommonObjectReference,ResultFactor>> +| +| + +| score +| +| +| Float +| +| float + +|=== + +[id="StorageRiskSubject_CommonObjectReference"] +=== StorageRiskSubject + +[id="Fields-StorageRiskSubject_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| type +| +| +| <<StorageRiskSubjectType_CommonObjectReference,StorageRiskSubjectType>> +| +| UNKNOWN, DEPLOYMENT, NAMESPACE, CLUSTER, NODE, NODE_COMPONENT, IMAGE, IMAGE_COMPONENT, SERVICEACCOUNT, + +|=== + +[id="StorageRiskSubjectType_CommonObjectReference"] +=== StorageRiskSubjectType + +Next tag: 9 + +[id="Fields-StorageRiskSubjectType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| DEPLOYMENT +| NAMESPACE +| CLUSTER +| NODE +| NODE_COMPONENT +| IMAGE +| IMAGE_COMPONENT +| SERVICEACCOUNT + +|=== + +[id="StorageRole_CommonObjectReference"] +=== StorageRole + +A role specifies which actions are allowed for which subset of cluster +objects. Permissions be can either specified directly via setting +resource_to_access together with global_access or by referencing a +permission set by its id in permission_set_name. + +[id="Fields-StorageRole_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| `name` and `description` are provided by the user and can be changed. +| + +| description +| +| +| String +| +| + +| permissionSetId +| +| +| String +| The associated PermissionSet and AccessScope for this Role. +| + +| accessScopeId +| +| +| String +| +| + +| globalAccess +| +| +| <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| NO_ACCESS, READ_ACCESS, READ_WRITE_ACCESS, + +| resourceToAccess +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| Deprecated 2021-04-20 in favor of `permission_set_id`. +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="StorageRuleValue_CommonObjectReference"] +=== StorageRuleValue + +[id="Fields-StorageRuleValue_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| value +| +| +| String +| +| + +| matchType +| +| +| <<StorageMatchType_CommonObjectReference,StorageMatchType>> +| +| EXACT, REGEX, + +|=== + +[id="StorageS3Compatible_CommonObjectReference"] +=== StorageS3Compatible + +S3Compatible configures the backup integration with an S3 compatible storage provider. +S3 compatible is intended for non-AWS providers. For AWS S3 use S3Config. + +[id="Fields-StorageS3Compatible_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| bucket +| +| +| String +| +| + +| accessKeyId +| +| +| String +| The access key ID to use. The server will mask the value of this credential in responses and logs. +| + +| secretAccessKey +| +| +| String +| The secret access key to use. The server will mask the value of this credential in responses and logs. +| + +| region +| +| +| String +| +| + +| objectPrefix +| +| +| String +| +| + +| endpoint +| +| +| String +| +| + +| urlStyle +| +| +| <<StorageS3URLStyle_CommonObjectReference,StorageS3URLStyle>> +| +| S3_URL_STYLE_UNSPECIFIED, S3_URL_STYLE_VIRTUAL_HOSTED, S3_URL_STYLE_PATH, + +|=== + +[id="StorageS3Config_CommonObjectReference"] +=== StorageS3Config + +S3Config configures the backup integration with AWS S3. + +[id="Fields-StorageS3Config_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| bucket +| +| +| String +| +| + +| useIam +| +| +| Boolean +| +| + +| accessKeyId +| +| +| String +| The access key ID for the storage integration. The server will mask the value of this credential in responses and logs. +| + +| secretAccessKey +| +| +| String +| The secret access key for the storage integration. The server will mask the value of this credential in responses and logs. +| + +| region +| +| +| String +| +| + +| objectPrefix +| +| +| String +| +| + +| endpoint +| +| +| String +| +| + +|=== + +[id="StorageS3URLStyle_CommonObjectReference"] +=== StorageS3URLStyle + +[id="Fields-StorageS3URLStyle_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| S3_URL_STYLE_UNSPECIFIED +| S3_URL_STYLE_VIRTUAL_HOSTED +| S3_URL_STYLE_PATH + +|=== + +[id="StorageScannerHealthInfo_CommonObjectReference"] +=== StorageScannerHealthInfo + +ScannerHealthInfo represents health info of a scanner instance that is deployed on a secured cluster (so called "local scanner"). +When the scanner is deployed on a central cluster, the following message is NOT used. +ScannerHealthInfo carries data about scanner deployment but does not include scanner health status +derived from this data. +Aggregated scanner health status is not included because it is derived in central and not in the component that +first reports ScannerHealthInfo (sensor). + +The following fields are made optional/nullable because there can be errors when trying to obtain them and + the default value of 0 might be confusing with the actual value 0. In case an error happens when trying to obtain + a certain field, it will be absent (instead of having the default value). + +[id="Fields-StorageScannerHealthInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| totalDesiredAnalyzerPods +| +| +| Integer +| +| int32 + +| totalReadyAnalyzerPods +| +| +| Integer +| +| int32 + +| totalDesiredDbPods +| +| +| Integer +| +| int32 + +| totalReadyDbPods +| +| +| Integer +| +| int32 + +| statusErrors +| +| +| List of `string` +| Collection of errors that occurred while trying to obtain scanner health info. +| + +|=== + +[id="StorageScannerV4Config_CommonObjectReference"] +=== StorageScannerV4Config + +[id="Fields-StorageScannerV4Config_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| numConcurrentScans +| +| +| Integer +| +| int32 + +| indexerEndpoint +| +| +| String +| +| + +| matcherEndpoint +| +| +| String +| +| + +|=== + +[id="StorageSchedule_CommonObjectReference"] +=== StorageSchedule + +[id="Fields-StorageSchedule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| intervalType +| +| +| <<ScheduleIntervalType_CommonObjectReference,ScheduleIntervalType>> +| +| UNSET, DAILY, WEEKLY, MONTHLY, + +| hour +| +| +| Integer +| +| int32 + +| minute +| +| +| Integer +| +| int32 + +| weekly +| +| +| <<ScheduleWeeklyInterval_CommonObjectReference,ScheduleWeeklyInterval>> +| +| + +| daysOfWeek +| +| +| <<ScheduleDaysOfWeek_CommonObjectReference,ScheduleDaysOfWeek>> +| +| + +| daysOfMonth +| +| +| <<ScheduleDaysOfMonth_CommonObjectReference,ScheduleDaysOfMonth>> +| +| + +|=== + +[id="StorageScope_CommonObjectReference"] +=== StorageScope + +[id="Fields-StorageScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cluster +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| label +| +| +| <<StorageScopeLabel_CommonObjectReference,StorageScopeLabel>> +| +| + +|=== + +[id="StorageScopeLabel_CommonObjectReference"] +=== StorageScopeLabel + +[id="Fields-StorageScopeLabel_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| value +| +| +| String +| +| + +|=== + +[id="StorageSecret_CommonObjectReference"] +=== StorageSecret + +Flat secret object. Any properties of an individual secret. (regardless of time, scope, or context) //////////////////////////////////////// + +[id="Fields-StorageSecret_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| type +| +| +| String +| +| + +| labels +| +| +| Map of `string` +| +| + +| annotations +| +| +| Map of `string` +| +| + +| createdAt +| +| +| Date +| +| date-time + +| files +| +| +| List of <<StorageSecretDataFile_CommonObjectReference,StorageSecretDataFile>> +| Metadata about the secrets. The secret need not be a file, but rather may be an arbitrary value. +| + +| relationship +| +| +| <<StorageSecretRelationship_CommonObjectReference,StorageSecretRelationship>> +| +| + +|=== + +[id="StorageSecretContainerRelationship_CommonObjectReference"] +=== StorageSecretContainerRelationship + +Secrets can be mounted in a path in a container. Next Tag: 3 + +[id="Fields-StorageSecretContainerRelationship_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| Id of the container the secret is mounted in. +| + +| path +| +| +| String +| Path is a container specific mounting directory. +| + +|=== + +[id="StorageSecretDataFile_CommonObjectReference"] +=== StorageSecretDataFile + +Metadata about secret. Additional information is presented for a certificate file and +imagePullSecret, but the "file" may also represent some arbitrary value. + +[id="Fields-StorageSecretDataFile_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| type +| +| +| <<StorageSecretType_CommonObjectReference,StorageSecretType>> +| +| UNDETERMINED, PUBLIC_CERTIFICATE, CERTIFICATE_REQUEST, PRIVACY_ENHANCED_MESSAGE, OPENSSH_PRIVATE_KEY, PGP_PRIVATE_KEY, EC_PRIVATE_KEY, RSA_PRIVATE_KEY, DSA_PRIVATE_KEY, CERT_PRIVATE_KEY, ENCRYPTED_PRIVATE_KEY, IMAGE_PULL_SECRET, + +| cert +| +| +| <<StorageCert_CommonObjectReference,StorageCert>> +| +| + +| imagePullSecret +| +| +| <<StorageImagePullSecret_CommonObjectReference,StorageImagePullSecret>> +| +| + +|=== + +[id="StorageSecretDeploymentRelationship_CommonObjectReference"] +=== StorageSecretDeploymentRelationship + +Secrets can be used by a deployment. Next Tag: 3 + +[id="Fields-StorageSecretDeploymentRelationship_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| Id of the deployment using the secret within a container. +| + +| name +| +| +| String +| Name of the deployment. +| + +|=== + +[id="StorageSecretRelationship_CommonObjectReference"] +=== StorageSecretRelationship + +The combined relationships that belong to the secret. Next Tag: 6 + +[id="Fields-StorageSecretRelationship_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| containerRelationships +| +| +| List of <<StorageSecretContainerRelationship_CommonObjectReference,StorageSecretContainerRelationship>> +| +| + +| deploymentRelationships +| +| +| List of <<StorageSecretDeploymentRelationship_CommonObjectReference,StorageSecretDeploymentRelationship>> +| Deployment id to relationship. +| + +|=== + +[id="StorageSecretType_CommonObjectReference"] +=== StorageSecretType + +[id="Fields-StorageSecretType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNDETERMINED +| PUBLIC_CERTIFICATE +| CERTIFICATE_REQUEST +| PRIVACY_ENHANCED_MESSAGE +| OPENSSH_PRIVATE_KEY +| PGP_PRIVATE_KEY +| EC_PRIVATE_KEY +| RSA_PRIVATE_KEY +| DSA_PRIVATE_KEY +| CERT_PRIVATE_KEY +| ENCRYPTED_PRIVATE_KEY +| IMAGE_PULL_SECRET + +|=== + +[id="StorageSecurityContext_CommonObjectReference"] +=== StorageSecurityContext + +[id="Fields-StorageSecurityContext_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| privileged +| +| +| Boolean +| +| + +| selinux +| +| +| <<SecurityContextSELinux_CommonObjectReference,SecurityContextSELinux>> +| +| + +| dropCapabilities +| +| +| List of `string` +| +| + +| addCapabilities +| +| +| List of `string` +| +| + +| readOnlyRootFilesystem +| +| +| Boolean +| +| + +| seccompProfile +| +| +| <<SecurityContextSeccompProfile_CommonObjectReference,SecurityContextSeccompProfile>> +| +| + +| allowPrivilegeEscalation +| +| +| Boolean +| +| + +|=== + +[id="StorageSelectorRule_CommonObjectReference"] +=== StorageSelectorRule + +[id="Fields-StorageSelectorRule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| fieldName +| +| +| String +| +| + +| operator +| +| +| <<StorageBooleanOperator_CommonObjectReference,StorageBooleanOperator>> +| +| OR, AND, + +| values +| +| +| List of <<StorageRuleValue_CommonObjectReference,StorageRuleValue>> +| `values` resolve as a conjunction (AND) or disjunction (OR) depending on operator. For MVP, only OR is supported from UX standpoint. +| + +|=== + +[id="StorageSensorDeploymentIdentification_CommonObjectReference"] +=== StorageSensorDeploymentIdentification + +StackRoxDeploymentIdentification aims at uniquely identifying a StackRox Sensor deployment. It is used to determine +whether a sensor connection comes from a sensor pod that has restarted or was recreated (possibly after a network +partition), or from a deployment in a different namespace or cluster. + +[id="Fields-StorageSensorDeploymentIdentification_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| systemNamespaceId +| +| +| String +| +| + +| defaultNamespaceId +| +| +| String +| +| + +| appNamespace +| +| +| String +| +| + +| appNamespaceId +| +| +| String +| +| + +| appServiceaccountId +| +| +| String +| +| + +| k8sNodeName +| +| +| String +| +| + +|=== + +[id="StorageSensorUpgradeConfig_CommonObjectReference"] +=== StorageSensorUpgradeConfig + +SensorUpgradeConfig encapsulates configuration relevant to sensor auto-upgrades. + +[id="Fields-StorageSensorUpgradeConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enableAutoUpgrade +| +| +| Boolean +| Whether to automatically trigger upgrades for out-of-date sensors. +| + +|=== + +[id="StorageServiceAccount_CommonObjectReference"] +=== StorageServiceAccount + +Any properties of an individual service account. (regardless of time, scope, or context) //////////////////////////////////////// + +[id="Fields-StorageServiceAccount_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| labels +| +| +| Map of `string` +| +| + +| annotations +| +| +| Map of `string` +| +| + +| createdAt +| +| +| Date +| +| date-time + +| automountToken +| +| +| Boolean +| +| + +| secrets +| +| +| List of `string` +| +| + +| imagePullSecrets +| +| +| List of `string` +| +| + +|=== + +[id="StorageServiceIdentity_CommonObjectReference"] +=== StorageServiceIdentity + +[id="Fields-StorageServiceIdentity_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| serialStr +| +| +| String +| +| + +| serial +| +| +| String +| +| int64 + +| id +| +| +| String +| +| + +| type +| +| +| <<StorageServiceType_CommonObjectReference,StorageServiceType>> +| +| UNKNOWN_SERVICE, SENSOR_SERVICE, CENTRAL_SERVICE, CENTRAL_DB_SERVICE, REMOTE_SERVICE, COLLECTOR_SERVICE, MONITORING_UI_SERVICE, MONITORING_DB_SERVICE, MONITORING_CLIENT_SERVICE, BENCHMARK_SERVICE, SCANNER_SERVICE, SCANNER_DB_SERVICE, ADMISSION_CONTROL_SERVICE, SCANNER_V4_INDEXER_SERVICE, SCANNER_V4_MATCHER_SERVICE, SCANNER_V4_DB_SERVICE, SCANNER_V4_SERVICE, REGISTRANT_SERVICE, + +| initBundleId +| +| +| String +| +| + +|=== + +[id="StorageServiceType_CommonObjectReference"] +=== StorageServiceType + +Next available tag: 18 + +- SCANNER_V4_SERVICE: This is used when Scanner V4 is run in combo-mode. + +[id="Fields-StorageServiceType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN_SERVICE +| SENSOR_SERVICE +| CENTRAL_SERVICE +| CENTRAL_DB_SERVICE +| REMOTE_SERVICE +| COLLECTOR_SERVICE +| MONITORING_UI_SERVICE +| MONITORING_DB_SERVICE +| MONITORING_CLIENT_SERVICE +| BENCHMARK_SERVICE +| SCANNER_SERVICE +| SCANNER_DB_SERVICE +| ADMISSION_CONTROL_SERVICE +| SCANNER_V4_INDEXER_SERVICE +| SCANNER_V4_MATCHER_SERVICE +| SCANNER_V4_DB_SERVICE +| SCANNER_V4_SERVICE +| REGISTRANT_SERVICE + +|=== + +[id="StorageSetBasedLabelSelector_CommonObjectReference"] +=== StorageSetBasedLabelSelector + +SetBasedLabelSelector only allows set-based label requirements. + +Next available tag: 3 + +[id="Fields-StorageSetBasedLabelSelector_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requirements +| +| +| List of <<StorageSetBasedLabelSelectorRequirement_CommonObjectReference,StorageSetBasedLabelSelectorRequirement>> +| +| + +|=== + +[id="StorageSetBasedLabelSelectorOperator_CommonObjectReference"] +=== StorageSetBasedLabelSelectorOperator + +[id="Fields-StorageSetBasedLabelSelectorOperator_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| IN +| NOT_IN +| EXISTS +| NOT_EXISTS + +|=== + +[id="StorageSetBasedLabelSelectorRequirement_CommonObjectReference"] +=== StorageSetBasedLabelSelectorRequirement + +Next available tag: 4 + +[id="Fields-StorageSetBasedLabelSelectorRequirement_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| op +| +| +| <<StorageSetBasedLabelSelectorOperator_CommonObjectReference,StorageSetBasedLabelSelectorOperator>> +| +| UNKNOWN, IN, NOT_IN, EXISTS, NOT_EXISTS, + +| values +| +| +| List of `string` +| +| + +|=== + +[id="StorageSeverity_CommonObjectReference"] +=== StorageSeverity + +[id="Fields-StorageSeverity_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET_SEVERITY +| LOW_SEVERITY +| MEDIUM_SEVERITY +| HIGH_SEVERITY +| CRITICAL_SEVERITY + +|=== + +[id="StorageSignature_CommonObjectReference"] +=== StorageSignature + +[id="Fields-StorageSignature_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cosign +| +| +| <<StorageCosignSignature_CommonObjectReference,StorageCosignSignature>> +| +| + +|=== + +[id="StorageSignatureIntegration_CommonObjectReference"] +=== StorageSignatureIntegration + +[id="Fields-StorageSignatureIntegration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| cosign +| +| +| <<StorageCosignPublicKeyVerification_CommonObjectReference,StorageCosignPublicKeyVerification>> +| +| + +| cosignCertificates +| +| +| List of <<StorageCosignCertificateVerification_CommonObjectReference,StorageCosignCertificateVerification>> +| +| + +| transparencyLog +| +| +| <<StorageTransparencyLogVerification_CommonObjectReference,StorageTransparencyLogVerification>> +| +| + +|=== + +[id="StorageSimpleAccessScope_CommonObjectReference"] +=== StorageSimpleAccessScope + +Simple access scope is a (simple) selection criteria for scoped resources. +It does *not* allow multi-component AND-rules nor set operations on names. + +[id="Fields-StorageSimpleAccessScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| `id` is generated and cannot be changed. +| + +| name +| +| +| String +| `name` and `description` are provided by the user and can be changed. +| + +| description +| +| +| String +| +| + +| rules +| +| +| <<SimpleAccessScopeRules_CommonObjectReference,SimpleAccessScopeRules>> +| +| + +| traits +| +| +| <<StorageTraits_CommonObjectReference,StorageTraits>> +| +| + +|=== + +[id="StorageSlimUser_CommonObjectReference"] +=== StorageSlimUser + +[id="Fields-StorageSlimUser_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +|=== + +[id="StorageSource_CommonObjectReference"] +=== StorageSource + +[id="Fields-StorageSource_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| SOURCE_UNKNOWN +| SOURCE_RED_HAT +| SOURCE_OSV +| SOURCE_NVD + +|=== + +[id="StorageSourceType_CommonObjectReference"] +=== StorageSourceType + +[id="Fields-StorageSourceType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| OS +| PYTHON +| JAVA +| RUBY +| NODEJS +| GO +| DOTNETCORERUNTIME +| INFRASTRUCTURE + +|=== + +[id="StorageSplunk_CommonObjectReference"] +=== StorageSplunk + +[id="Fields-StorageSplunk_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| httpToken +| +| +| String +| The HTTP token for the integration. The server will mask the value of this credential in responses and logs. +| + +| httpEndpoint +| +| +| String +| +| + +| insecure +| +| +| Boolean +| +| + +| truncate +| +| +| String +| +| int64 + +| auditLoggingEnabled +| +| +| Boolean +| +| + +| derivedSourceType +| +| +| Boolean +| +| + +| sourceTypes +| +| +| Map of `string` +| +| + +|=== + +[id="StorageStaticClusterConfig_CommonObjectReference"] +=== StorageStaticClusterConfig + +The difference between Static and Dynamic cluster config is that Static values are not sent over the Central to Sensor gRPC connection. They are used, for example, to generate manifests that can be used to set up the Secured Cluster's k8s components. They are *not* dynamically reloaded. + +[id="Fields-StorageStaticClusterConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| <<StorageClusterType_CommonObjectReference,StorageClusterType>> +| +| GENERIC_CLUSTER, KUBERNETES_CLUSTER, OPENSHIFT_CLUSTER, OPENSHIFT4_CLUSTER, + +| mainImage +| +| +| String +| +| + +| centralApiEndpoint +| +| +| String +| +| + +| collectionMethod +| +| +| <<StorageCollectionMethod_CommonObjectReference,StorageCollectionMethod>> +| +| UNSET_COLLECTION, NO_COLLECTION, KERNEL_MODULE, EBPF, CORE_BPF, + +| collectorImage +| +| +| String +| +| + +| admissionController +| +| +| Boolean +| +| + +| admissionControllerUpdates +| +| +| Boolean +| +| + +| tolerationsConfig +| +| +| <<StorageTolerationsConfig_CommonObjectReference,StorageTolerationsConfig>> +| +| + +| slimCollector +| +| +| Boolean +| +| + +| admissionControllerEvents +| +| +| Boolean +| +| + +|=== + +[id="StorageSubject_CommonObjectReference"] +=== StorageSubject + +Properties of an individual subjects who are granted roles via role bindings. //////////////////////////////////////// + +[id="Fields-StorageSubject_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| kind +| +| +| <<StorageSubjectKind_CommonObjectReference,StorageSubjectKind>> +| +| UNSET_KIND, SERVICE_ACCOUNT, USER, GROUP, + +| name +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +|=== + +[id="StorageSubjectKind_CommonObjectReference"] +=== StorageSubjectKind + +[id="Fields-StorageSubjectKind_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET_KIND +| SERVICE_ACCOUNT +| USER +| GROUP + +|=== + +[id="StorageSumoLogic_CommonObjectReference"] +=== StorageSumoLogic + +[id="Fields-StorageSumoLogic_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| httpSourceAddress +| +| +| String +| +| + +| skipTLSVerify +| +| +| Boolean +| +| + +|=== + +[id="StorageSyslog_CommonObjectReference"] +=== StorageSyslog + +[id="Fields-StorageSyslog_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| localFacility +| +| +| <<SyslogLocalFacility_CommonObjectReference,SyslogLocalFacility>> +| +| LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7, + +| tcpConfig +| +| +| <<SyslogTCPConfig_CommonObjectReference,SyslogTCPConfig>> +| +| + +| extraFields +| +| +| List of <<StorageKeyValuePair_CommonObjectReference,StorageKeyValuePair>> +| +| + +| messageFormat +| +| +| <<SyslogMessageFormat_CommonObjectReference,SyslogMessageFormat>> +| +| LEGACY, CEF, + +| maxMessageSize +| +| +| Integer +| +| int32 + +|=== + +[id="StorageTaint_CommonObjectReference"] +=== StorageTaint + +[id="Fields-StorageTaint_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| value +| +| +| String +| +| + +| taintEffect +| +| +| <<StorageTaintEffect_CommonObjectReference,StorageTaintEffect>> +| +| UNKNOWN_TAINT_EFFECT, NO_SCHEDULE_TAINT_EFFECT, PREFER_NO_SCHEDULE_TAINT_EFFECT, NO_EXECUTE_TAINT_EFFECT, + +|=== + +[id="StorageTaintEffect_CommonObjectReference"] +=== StorageTaintEffect + +[id="Fields-StorageTaintEffect_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN_TAINT_EFFECT +| NO_SCHEDULE_TAINT_EFFECT +| PREFER_NO_SCHEDULE_TAINT_EFFECT +| NO_EXECUTE_TAINT_EFFECT + +|=== + +[id="StorageTelemetryConfiguration_CommonObjectReference"] +=== StorageTelemetryConfiguration + +[id="Fields-StorageTelemetryConfiguration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enabled +| +| +| Boolean +| +| + +| lastSetTime +| +| +| Date +| +| date-time + +|=== + +[id="StorageTokenMetadata_CommonObjectReference"] +=== StorageTokenMetadata + +Next available tag: 8 + +[id="Fields-StorageTokenMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| roles +| +| +| List of `string` +| +| + +| issuedAt +| +| +| Date +| +| date-time + +| expiration +| +| +| Date +| +| date-time + +| revoked +| +| +| Boolean +| +| + +| role +| +| +| String +| +| + +|=== + +[id="StorageToleration_CommonObjectReference"] +=== StorageToleration + +[id="Fields-StorageToleration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| operator +| +| +| <<StorageTolerationOperator_CommonObjectReference,StorageTolerationOperator>> +| +| TOLERATION_OPERATION_UNKNOWN, TOLERATION_OPERATOR_EXISTS, TOLERATION_OPERATOR_EQUAL, + +| value +| +| +| String +| +| + +| taintEffect +| +| +| <<StorageTaintEffect_CommonObjectReference,StorageTaintEffect>> +| +| UNKNOWN_TAINT_EFFECT, NO_SCHEDULE_TAINT_EFFECT, PREFER_NO_SCHEDULE_TAINT_EFFECT, NO_EXECUTE_TAINT_EFFECT, + +|=== + +[id="StorageTolerationOperator_CommonObjectReference"] +=== StorageTolerationOperator + +[id="Fields-StorageTolerationOperator_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| TOLERATION_OPERATION_UNKNOWN +| TOLERATION_OPERATOR_EXISTS +| TOLERATION_OPERATOR_EQUAL + +|=== + +[id="StorageTolerationsConfig_CommonObjectReference"] +=== StorageTolerationsConfig + +[id="Fields-StorageTolerationsConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| disabled +| +| +| Boolean +| +| + +|=== + +[id="StorageTraits_CommonObjectReference"] +=== StorageTraits + +[id="Fields-StorageTraits_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| mutabilityMode +| +| +| <<TraitsMutabilityMode_CommonObjectReference,TraitsMutabilityMode>> +| +| ALLOW_MUTATE, ALLOW_MUTATE_FORCED, + +| visibility +| +| +| <<TraitsVisibility_CommonObjectReference,TraitsVisibility>> +| +| VISIBLE, HIDDEN, + +| origin +| +| +| <<TraitsOrigin_CommonObjectReference,TraitsOrigin>> +| +| IMPERATIVE, DEFAULT, DECLARATIVE, DECLARATIVE_ORPHANED, + +|=== + +[id="StorageTransparencyLogVerification_CommonObjectReference"] +=== StorageTransparencyLogVerification + +Validate the inclusion of signature signing events into a transparency log. + +[id="Fields-StorageTransparencyLogVerification_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enabled +| +| +| Boolean +| Validate the inclusion of signatures into a transparency log. Disables validation if not enabled. +| + +| url +| +| +| String +| The URL of the transparency log. Required for online confirmation of inclusion into the transparency log. Defaults to the Sigstore instance `rekor.sigstore.dev`. +| + +| validateOffline +| +| +| Boolean +| Force offline validation of the signature proof of inclusion into the transparency log. Do not fall back to request confirmation from the transparency log over network. +| + +| publicKeyPemEnc +| +| +| String +| PEM encoded public key used to validate the proof of inclusion into the transparency log. Defaults to the key of the public Sigstore instance if left empty. +| + +|=== + +[id="StorageUpgradeProgress_CommonObjectReference"] +=== StorageUpgradeProgress + +[id="Fields-StorageUpgradeProgress_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| upgradeState +| +| +| <<UpgradeProgressUpgradeState_CommonObjectReference,UpgradeProgressUpgradeState>> +| +| UPGRADE_INITIALIZING, UPGRADER_LAUNCHING, UPGRADER_LAUNCHED, PRE_FLIGHT_CHECKS_COMPLETE, UPGRADE_OPERATIONS_DONE, UPGRADE_COMPLETE, UPGRADE_INITIALIZATION_ERROR, PRE_FLIGHT_CHECKS_FAILED, UPGRADE_ERROR_ROLLING_BACK, UPGRADE_ERROR_ROLLED_BACK, UPGRADE_ERROR_ROLLBACK_FAILED, UPGRADE_ERROR_UNKNOWN, UPGRADE_TIMED_OUT, + +| upgradeStatusDetail +| +| +| String +| +| + +| since +| +| +| Date +| +| date-time + +|=== + +[id="StorageUser_CommonObjectReference"] +=== StorageUser + +User is an object that allows us to track the roles a user is tied to, and how they logged in. + +[id="Fields-StorageUser_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| authProviderId +| +| +| String +| +| + +| attributes +| +| +| List of <<StorageUserAttribute_CommonObjectReference,StorageUserAttribute>> +| +| + +| idpToken +| +| +| String +| +| + +|=== + +[id="StorageUserAttribute_CommonObjectReference"] +=== StorageUserAttribute + +[id="Fields-StorageUserAttribute_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| value +| +| +| String +| +| + +|=== + +[id="StorageUserInfo_CommonObjectReference"] +=== StorageUserInfo + +[id="Fields-StorageUserInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| username +| +| +| String +| +| + +| friendlyName +| +| +| String +| +| + +| permissions +| +| +| <<UserInfoResourceToAccess_CommonObjectReference,UserInfoResourceToAccess>> +| +| + +| roles +| +| +| List of <<StorageUserInfoRole_CommonObjectReference,StorageUserInfoRole>> +| +| + +|=== + +[id="StorageUserInfoRole_CommonObjectReference"] +=== StorageUserInfoRole + +Role is wire compatible with the old format of storage.Role and +hence only includes role name and associated permissions. + +[id="Fields-StorageUserInfoRole_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| resourceToAccess +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| + +|=== + +[id="StorageV1Metadata_CommonObjectReference"] +=== StorageV1Metadata + +[id="Fields-StorageV1Metadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| digest +| +| +| String +| +| + +| created +| +| +| Date +| +| date-time + +| author +| +| +| String +| +| + +| layers +| +| +| List of <<StorageImageLayer_CommonObjectReference,StorageImageLayer>> +| +| + +| user +| +| +| String +| +| + +| command +| +| +| List of `string` +| +| + +| entrypoint +| +| +| List of `string` +| +| + +| volumes +| +| +| List of `string` +| +| + +| labels +| +| +| Map of `string` +| +| + +|=== + +[id="StorageV2Metadata_CommonObjectReference"] +=== StorageV2Metadata + +[id="Fields-StorageV2Metadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| digest +| +| +| String +| +| + +|=== + +[id="StorageViolationState_CommonObjectReference"] +=== StorageViolationState + +[id="Fields-StorageViolationState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ACTIVE +| RESOLVED +| ATTEMPTED + +|=== + +[id="StorageVolume_CommonObjectReference"] +=== StorageVolume + +[id="Fields-StorageVolume_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| source +| +| +| String +| +| + +| destination +| +| +| String +| +| + +| readOnly +| +| +| Boolean +| +| + +| type +| +| +| String +| +| + +| mountPropagation +| +| +| <<VolumeMountPropagation_CommonObjectReference,VolumeMountPropagation>> +| +| NONE, HOST_TO_CONTAINER, BIDIRECTIONAL, + +|=== + +[id="StorageVulnerabilityExceptionConfig_CommonObjectReference"] +=== StorageVulnerabilityExceptionConfig + +[id="Fields-StorageVulnerabilityExceptionConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| expiryOptions +| +| +| <<StorageVulnerabilityExceptionConfigExpiryOptions_CommonObjectReference,StorageVulnerabilityExceptionConfigExpiryOptions>> +| +| + +|=== + +[id="StorageVulnerabilityExceptionConfigExpiryOptions_CommonObjectReference"] +=== StorageVulnerabilityExceptionConfigExpiryOptions + +[id="Fields-StorageVulnerabilityExceptionConfigExpiryOptions_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| dayOptions +| +| +| List of <<StorageDayOption_CommonObjectReference,StorageDayOption>> +| +| + +| fixableCveOptions +| +| +| <<StorageVulnerabilityExceptionConfigFixableCVEOptions_CommonObjectReference,StorageVulnerabilityExceptionConfigFixableCVEOptions>> +| +| + +| customDate +| +| +| Boolean +| +| + +| indefinite +| +| +| Boolean +| +| + +|=== + +[id="StorageVulnerabilityExceptionConfigFixableCVEOptions_CommonObjectReference"] +=== StorageVulnerabilityExceptionConfigFixableCVEOptions + +[id="Fields-StorageVulnerabilityExceptionConfigFixableCVEOptions_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| allFixable +| +| +| Boolean +| +| + +| anyFixable +| +| +| Boolean +| +| + +|=== + +[id="StorageVulnerabilityReportFilters_CommonObjectReference"] +=== StorageVulnerabilityReportFilters + +[id="Fields-StorageVulnerabilityReportFilters_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| fixability +| +| +| <<VulnerabilityReportFiltersFixability_CommonObjectReference,VulnerabilityReportFiltersFixability>> +| +| BOTH, FIXABLE, NOT_FIXABLE, + +| sinceLastReport +| +| +| Boolean +| +| + +| severities +| +| +| List of <<StorageVulnerabilitySeverity_CommonObjectReference,StorageVulnerabilitySeverity>> +| +| + +| imageTypes +| +| +| List of <<VulnerabilityReportFiltersImageType_CommonObjectReference,VulnerabilityReportFiltersImageType>> +| +| + +| allVuln +| +| +| Boolean +| +| + +| sinceLastSentScheduledReport +| +| +| Boolean +| +| + +| sinceStartDate +| +| +| Date +| +| date-time + +| accessScopeRules +| +| +| List of <<SimpleAccessScopeRules_CommonObjectReference,SimpleAccessScopeRules>> +| +| + +| includeNvdCvss +| +| +| Boolean +| +| + +| includeEpssProbability +| +| +| Boolean +| +| + +| includeAdvisory +| +| +| Boolean +| +| + +|=== + +[id="StorageVulnerabilityRequest_CommonObjectReference"] +=== StorageVulnerabilityRequest + +Next available tag: 30 +VulnerabilityRequest encapsulates a request such as deferral request and false-positive request. + +[id="Fields-StorageVulnerabilityRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| targetState +| +| +| <<StorageVulnerabilityState_CommonObjectReference,StorageVulnerabilityState>> +| +| OBSERVED, DEFERRED, FALSE_POSITIVE, + +| status +| +| +| <<StorageRequestStatus_CommonObjectReference,StorageRequestStatus>> +| +| PENDING, APPROVED, DENIED, APPROVED_PENDING_UPDATE, + +| expired +| +| +| Boolean +| Indicates if this request is a historical request that is no longer in effect due to deferral expiry, cancellation, or restarting cve observation. +| + +| requestor +| +| +| <<StorageSlimUser_CommonObjectReference,StorageSlimUser>> +| +| + +| approvers +| +| +| List of <<StorageSlimUser_CommonObjectReference,StorageSlimUser>> +| +| + +| createdAt +| +| +| Date +| +| date-time + +| lastUpdated +| +| +| Date +| +| date-time + +| comments +| +| +| List of <<StorageRequestComment_CommonObjectReference,StorageRequestComment>> +| +| + +| scope +| +| +| <<StorageVulnerabilityRequestScope_CommonObjectReference,StorageVulnerabilityRequestScope>> +| +| + +| requesterV2 +| +| +| <<StorageRequester_CommonObjectReference,StorageRequester>> +| +| + +| approversV2 +| +| +| List of <<StorageApprover_CommonObjectReference,StorageApprover>> +| +| + +| deferralReq +| +| +| <<StorageDeferralRequest_CommonObjectReference,StorageDeferralRequest>> +| +| + +| fpRequest +| +| +| Object +| +| + +| cves +| +| +| <<VulnerabilityRequestCVEs_CommonObjectReference,VulnerabilityRequestCVEs>> +| +| + +| updatedDeferralReq +| +| +| <<StorageDeferralRequest_CommonObjectReference,StorageDeferralRequest>> +| +| + +| deferralUpdate +| +| +| <<StorageDeferralUpdate_CommonObjectReference,StorageDeferralUpdate>> +| +| + +| falsePositiveUpdate +| +| +| <<StorageFalsePositiveUpdate_CommonObjectReference,StorageFalsePositiveUpdate>> +| +| + +|=== + +[id="StorageVulnerabilityRequestScope_CommonObjectReference"] +=== StorageVulnerabilityRequestScope + +[id="Fields-StorageVulnerabilityRequestScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| imageScope +| +| +| <<VulnerabilityRequestScopeImage_CommonObjectReference,VulnerabilityRequestScopeImage>> +| +| + +| globalScope +| +| +| Object +| +| + +|=== + +[id="StorageVulnerabilitySeverity_CommonObjectReference"] +=== StorageVulnerabilitySeverity + +[id="Fields-StorageVulnerabilitySeverity_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN_VULNERABILITY_SEVERITY +| LOW_VULNERABILITY_SEVERITY +| MODERATE_VULNERABILITY_SEVERITY +| IMPORTANT_VULNERABILITY_SEVERITY +| CRITICAL_VULNERABILITY_SEVERITY + +|=== + +[id="StorageVulnerabilityState_CommonObjectReference"] +=== StorageVulnerabilityState + +VulnerabilityState indicates if vulnerability is being observed or deferred(/suppressed). By default, it vulnerabilities are observed. + + - OBSERVED: [Default state] + +[id="Fields-StorageVulnerabilityState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| OBSERVED +| DEFERRED +| FALSE_POSITIVE + +|=== + +[id="StorageWatchedImage_CommonObjectReference"] +=== StorageWatchedImage + +[id="Fields-StorageWatchedImage_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +|=== + +[id="SyslogLocalFacility_CommonObjectReference"] +=== SyslogLocalFacility + +[id="Fields-SyslogLocalFacility_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| LOCAL0 +| LOCAL1 +| LOCAL2 +| LOCAL3 +| LOCAL4 +| LOCAL5 +| LOCAL6 +| LOCAL7 + +|=== + +[id="SyslogMessageFormat_CommonObjectReference"] +=== SyslogMessageFormat + +[id="Fields-SyslogMessageFormat_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| LEGACY +| CEF + +|=== + +[id="SyslogTCPConfig_CommonObjectReference"] +=== SyslogTCPConfig + +[id="Fields-SyslogTCPConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| hostname +| +| +| String +| +| + +| port +| +| +| Integer +| +| int32 + +| skipTlsVerify +| +| +| Boolean +| +| + +| useTls +| +| +| Boolean +| +| + +|=== + +[id="TraceBuiltInAuthorizer_CommonObjectReference"] +=== TraceBuiltInAuthorizer + +[id="Fields-TraceBuiltInAuthorizer_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clustersTotalNum +| +| +| Integer +| +| int32 + +| namespacesTotalNum +| +| +| Integer +| +| int32 + +| deniedAuthzDecisions +| +| +| Map of `integer` +| +| int32 + +| allowedAuthzDecisions +| +| +| Map of `integer` +| +| int32 + +| effectiveAccessScopes +| +| +| Map of `string` +| +| + +|=== + +[id="TraitsMutabilityMode_CommonObjectReference"] +=== TraitsMutabilityMode + +EXPERIMENTAL. +NOTE: Please refer from using MutabilityMode for the time being. It will be replaced in the future (ROX-14276). +MutabilityMode specifies whether and how an object can be modified. Default +is ALLOW_MUTATE and means there are no modification restrictions; this is equivalent +to the absence of MutabilityMode specification. ALLOW_MUTATE_FORCED forbids all +modifying operations except object removal with force bit on. + +Be careful when changing the state of this field. For example, modifying an +object from ALLOW_MUTATE to ALLOW_MUTATE_FORCED is allowed but will prohibit any further +changes to it, including modifying it back to ALLOW_MUTATE. + +[id="Fields-TraitsMutabilityMode_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ALLOW_MUTATE +| ALLOW_MUTATE_FORCED + +|=== + +[id="TraitsOrigin_CommonObjectReference"] +=== TraitsOrigin + +Origin specifies the origin of an object. +Objects can have four different origins: +- IMPERATIVE: the object was created via the API. This is assumed by default. +- DEFAULT: the object is a default object, such as default roles, access scopes etc. +- DECLARATIVE: the object is created via declarative configuration. +- DECLARATIVE_ORPHANED: the object is created via declarative configuration and then unsuccessfully deleted(for example, because it is referenced by another object) +Based on the origin, different rules apply to the objects. +Objects with the DECLARATIVE origin are not allowed to be modified via API, only via declarative configuration. +Additionally, they may not reference objects with the IMPERATIVE origin. +Objects with the DEFAULT origin are not allowed to be modified via either API or declarative configuration. +They may be referenced by all other objects. +Objects with the IMPERATIVE origin are allowed to be modified via API, not via declarative configuration. +They may reference all other objects. +Objects with the DECLARATIVE_ORPHANED origin are not allowed to be modified via either API or declarative configuration. +DECLARATIVE_ORPHANED resource can become DECLARATIVE again if it is redefined in declarative configuration. +Objects with this origin will be cleaned up from the system immediately after they are not referenced by other resources anymore. +They may be referenced by all other objects. + +[id="Fields-TraitsOrigin_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| IMPERATIVE +| DEFAULT +| DECLARATIVE +| DECLARATIVE_ORPHANED + +|=== + +[id="TraitsVisibility_CommonObjectReference"] +=== TraitsVisibility + +EXPERIMENTAL. +visibility allows to specify whether the object should be visible for certain APIs. + +[id="Fields-TraitsVisibility_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| VISIBLE +| HIDDEN + +|=== + +[id="UpgradeProcessStatusUpgradeProcessType_CommonObjectReference"] +=== UpgradeProcessStatusUpgradeProcessType + + - UPGRADE: UPGRADE represents a sensor version upgrade. + - CERT_ROTATION: CERT_ROTATION represents an upgrade process that only rotates the TLS certs +used by the cluster, without changing anything else. + +[id="Fields-UpgradeProcessStatusUpgradeProcessType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UPGRADE +| CERT_ROTATION + +|=== + +[id="UpgradeProgressUpgradeState_CommonObjectReference"] +=== UpgradeProgressUpgradeState + + - UPGRADER_LAUNCHING: In-progress states. + - UPGRADE_COMPLETE: The success state. +PLEASE NUMBER ALL IN-PROGRESS STATES ABOVE THIS +AND ALL ERROR STATES BELOW THIS. + - UPGRADE_INITIALIZATION_ERROR: Error states. + +[id="Fields-UpgradeProgressUpgradeState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UPGRADE_INITIALIZING +| UPGRADER_LAUNCHING +| UPGRADER_LAUNCHED +| PRE_FLIGHT_CHECKS_COMPLETE +| UPGRADE_OPERATIONS_DONE +| UPGRADE_COMPLETE +| UPGRADE_INITIALIZATION_ERROR +| PRE_FLIGHT_CHECKS_FAILED +| UPGRADE_ERROR_ROLLING_BACK +| UPGRADE_ERROR_ROLLED_BACK +| UPGRADE_ERROR_ROLLBACK_FAILED +| UPGRADE_ERROR_UNKNOWN +| UPGRADE_TIMED_OUT + +|=== + +[id="UserInfoResourceToAccess_CommonObjectReference"] +=== UserInfoResourceToAccess + +ResourceToAccess represents a collection of permissions. It is wire +compatible with the old format of storage.Role and replaces it in +places where only aggregated permissions are required. + +[id="Fields-UserInfoResourceToAccess_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| resourceToAccess +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| + +|=== + +[id="V1AddAuthMachineToMachineConfigRequest_CommonObjectReference"] +=== V1AddAuthMachineToMachineConfigRequest + +[id="Fields-V1AddAuthMachineToMachineConfigRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<V1AuthMachineToMachineConfig_CommonObjectReference,V1AuthMachineToMachineConfig>> +| +| + +|=== + +[id="V1AddAuthMachineToMachineConfigResponse_CommonObjectReference"] +=== V1AddAuthMachineToMachineConfigResponse + +[id="Fields-V1AddAuthMachineToMachineConfigResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<V1AuthMachineToMachineConfig_CommonObjectReference,V1AuthMachineToMachineConfig>> +| +| + +|=== + +[id="V1AdministrationEvent_CommonObjectReference"] +=== V1AdministrationEvent + +AdministrationEvents are administrative events emitted by Central. They are used to create +transparency for users for asynchronous, background tasks. Events are part of Central's +system health view. + +[id="Fields-V1AdministrationEvent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| UUID of the event. +| + +| type +| +| +| <<V1AdministrationEventType_CommonObjectReference,V1AdministrationEventType>> +| +| ADMINISTRATION_EVENT_TYPE_UNKNOWN, ADMINISTRATION_EVENT_TYPE_GENERIC, ADMINISTRATION_EVENT_TYPE_LOG_MESSAGE, + +| level +| +| +| <<V1AdministrationEventLevel_CommonObjectReference,V1AdministrationEventLevel>> +| +| ADMINISTRATION_EVENT_LEVEL_UNKNOWN, ADMINISTRATION_EVENT_LEVEL_INFO, ADMINISTRATION_EVENT_LEVEL_SUCCESS, ADMINISTRATION_EVENT_LEVEL_WARNING, ADMINISTRATION_EVENT_LEVEL_ERROR, + +| message +| +| +| String +| Message associated with the event. The message may include detailed information for this particular event. +| + +| hint +| +| +| String +| Hint associated with the event. The hint may include different information based on the type of event. It can include instructions to resolve an event, or informational hints. +| + +| domain +| +| +| String +| Domain associated with the event. An event's domain outlines the feature domain where the event was created from. As an example, this might be "Image Scanning". In case of events that cannot be tied to a specific domain, this will be "General". +| + +| resource +| +| +| <<V1AdministrationEventResource_CommonObjectReference,V1AdministrationEventResource>> +| +| + +| numOccurrences +| +| +| String +| Occurrences associated with the event. When events may occur multiple times, the occurrences track the amount. +| int64 + +| lastOccurredAt +| +| +| Date +| Specifies the time when the event has last occurred. +| date-time + +| createdAt +| +| +| Date +| Specifies the time when the event has been created. +| date-time + +|=== + +[id="V1AdministrationEventLevel_CommonObjectReference"] +=== V1AdministrationEventLevel + +AdministrationEventLevel exposes the different levels of events. + +[id="Fields-V1AdministrationEventLevel_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ADMINISTRATION_EVENT_LEVEL_UNKNOWN +| ADMINISTRATION_EVENT_LEVEL_INFO +| ADMINISTRATION_EVENT_LEVEL_SUCCESS +| ADMINISTRATION_EVENT_LEVEL_WARNING +| ADMINISTRATION_EVENT_LEVEL_ERROR + +|=== + +[id="V1AdministrationEventResource_CommonObjectReference"] +=== V1AdministrationEventResource + +Resource holds all information about the resource associated with the event. + +[id="Fields-V1AdministrationEventResource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| type +| +| +| String +| Resource type associated with the event. An event may refer to an underlying resource such as a particular image. In that case, the resource type will be filled here. +| + +| id +| +| +| String +| Resource ID associated with the event. If an event refers to an underlying resource, the resource ID identifies the underlying resource. The resource ID is not guaranteed to be set, depending on the context of the administration event. +| + +| name +| +| +| String +| Resource name associated with the event. If an event refers to an underlying resource, the resource name identifies the underlying resource. The resource name is not guaranteed to be set, depending on the context of the administration event. +| + +|=== + +[id="V1AdministrationEventType_CommonObjectReference"] +=== V1AdministrationEventType + +AdministrationEventType exposes the different types of events. + +[id="Fields-V1AdministrationEventType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ADMINISTRATION_EVENT_TYPE_UNKNOWN +| ADMINISTRATION_EVENT_TYPE_GENERIC +| ADMINISTRATION_EVENT_TYPE_LOG_MESSAGE + +|=== + +[id="V1AdministrationEventsFilter_CommonObjectReference"] +=== V1AdministrationEventsFilter + +[id="Fields-V1AdministrationEventsFilter_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| from +| +| +| Date +| Matches events with last_occurred_at after a specific timestamp, i.e. the lower boundary. +| date-time + +| until +| +| +| Date +| Matches events with last_occurred_at before a specific timestamp, i.e. the upper boundary. +| date-time + +| domain +| +| +| List of `string` +| Matches events from a specific domain. +| + +| resourceType +| +| +| List of `string` +| Matches events associated with a specific resource type. +| + +| type +| +| +| List of <<V1AdministrationEventType_CommonObjectReference,V1AdministrationEventType>> +| Matches events based on their type. +| + +| level +| +| +| List of <<V1AdministrationEventLevel_CommonObjectReference,V1AdministrationEventLevel>> +| Matches events based on their level. +| + +|=== + +[id="V1AggregateBy_CommonObjectReference"] +=== V1AggregateBy + +[id="Fields-V1AggregateBy_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| aggrFunc +| +| +| <<V1Aggregation_CommonObjectReference,V1Aggregation>> +| +| UNSET, COUNT, MIN, MAX, + +| distinct +| +| +| Boolean +| +| + +|=== + +[id="V1Aggregation_CommonObjectReference"] +=== V1Aggregation + +[id="Fields-V1Aggregation_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| COUNT +| MIN +| MAX + +|=== + +[id="V1AlertEvent_CommonObjectReference"] +=== V1AlertEvent + +[id="Fields-V1AlertEvent_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| time +| +| +| String +| +| int64 + +| type +| +| +| <<V1Type_CommonObjectReference,V1Type>> +| +| CREATED, REMOVED, + +| id +| +| +| String +| +| + +|=== + +[id="V1ApproveVulnRequestResponse_CommonObjectReference"] +=== V1ApproveVulnRequestResponse + +[id="Fields-V1ApproveVulnRequestResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requestInfo +| +| +| <<StorageVulnerabilityRequest_CommonObjectReference,StorageVulnerabilityRequest>> +| +| + +|=== + +[id="V1AuthMachineToMachineConfig_CommonObjectReference"] +=== V1AuthMachineToMachineConfig + +AuthMachineToMachineConfig determines rules for exchanging an identity token from a third party with +a Central access token. The M2M stands for machine to machine, as this is the intended use-case +for the config. + +[id="Fields-V1AuthMachineToMachineConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| UUID of the config. Note that when adding a machine to machine config, this field should not be set. +| + +| type +| +| +| <<V1AuthMachineToMachineConfigType_CommonObjectReference,V1AuthMachineToMachineConfigType>> +| +| GENERIC, GITHUB_ACTIONS, KUBE_SERVICE_ACCOUNT, + +| tokenExpirationDuration +| +| +| String +| Sets the expiration of the token returned from the ExchangeAuthMachineToMachineToken API call. Possible valid time units are: s, m, h. The maximum allowed expiration duration is 24h. As an example: 2h45m. For additional information on the validation of the duration, see: https://pkg.go.dev/time#ParseDuration. +| + +| mappings +| +| +| List of <<AuthMachineToMachineConfigMapping_CommonObjectReference,AuthMachineToMachineConfigMapping>> +| At least one mapping is required to resolve to a valid role for the access token to be successfully generated. +| + +| issuer +| +| +| String +| The issuer of the related OIDC provider issuing the ID tokens to exchange. Must be non-empty string containing URL when type is GENERIC. In case of GitHub actions, this must be empty or set to https://token.actions.githubusercontent.com. Issuer is a unique key, therefore there may be at most one GITHUB_ACTIONS config, and each GENERIC config must have a distinct issuer. +| + +|=== + +[id="V1AuthMachineToMachineConfigType_CommonObjectReference"] +=== V1AuthMachineToMachineConfigType + +The type of the auth machine to machine config. +Currently supports GitHub actions or any other generic OIDC provider to use for verifying and +exchanging the token. + +[id="Fields-V1AuthMachineToMachineConfigType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| GENERIC +| GITHUB_ACTIONS +| KUBE_SERVICE_ACCOUNT + +|=== + +[id="V1AuthStatus_CommonObjectReference"] +=== V1AuthStatus + +[id="Fields-V1AuthStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| userId +| +| +| String +| +| + +| serviceId +| +| +| <<StorageServiceIdentity_CommonObjectReference,StorageServiceIdentity>> +| +| + +| expires +| +| +| Date +| +| date-time + +| refreshUrl +| +| +| String +| +| + +| authProvider +| +| +| <<StorageAuthProvider_CommonObjectReference,StorageAuthProvider>> +| +| + +| userInfo +| +| +| <<StorageUserInfo_CommonObjectReference,StorageUserInfo>> +| +| + +| userAttributes +| +| +| List of <<V1UserAttribute_CommonObjectReference,V1UserAttribute>> +| +| + +| idpToken +| +| +| String +| Token returned to ACS by the underlying identity provider. This field is set only in a few, specific contexts. Do not rely on this field being present in the response. +| + +|=== + +[id="V1Authorities_CommonObjectReference"] +=== V1Authorities + +[id="Fields-V1Authorities_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| authorities +| +| +| List of <<V1Authority_CommonObjectReference,V1Authority>> +| +| + +|=== + +[id="V1Authority_CommonObjectReference"] +=== V1Authority + +[id="Fields-V1Authority_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| certificatePem +| +| +| byte[] +| +| byte + +|=== + +[id="V1AuthorizationTraceResponse_CommonObjectReference"] +=== V1AuthorizationTraceResponse + +[id="Fields-V1AuthorizationTraceResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| arrivedAt +| +| +| Date +| +| date-time + +| processedAt +| +| +| Date +| +| date-time + +| request +| +| +| <<V1AuthorizationTraceResponseRequest_CommonObjectReference,V1AuthorizationTraceResponseRequest>> +| +| + +| response +| +| +| <<V1AuthorizationTraceResponseResponse_CommonObjectReference,V1AuthorizationTraceResponseResponse>> +| +| + +| user +| +| +| <<V1AuthorizationTraceResponseUser_CommonObjectReference,V1AuthorizationTraceResponseUser>> +| +| + +| trace +| +| +| <<AuthorizationTraceResponseTrace_CommonObjectReference,AuthorizationTraceResponseTrace>> +| +| + +|=== + +[id="V1AuthorizationTraceResponseRequest_CommonObjectReference"] +=== V1AuthorizationTraceResponseRequest + +[id="Fields-V1AuthorizationTraceResponseRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +| method +| +| +| String +| +| + +|=== + +[id="V1AuthorizationTraceResponseResponse_CommonObjectReference"] +=== V1AuthorizationTraceResponseResponse + +[id="Fields-V1AuthorizationTraceResponseResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| status +| +| +| <<AuthorizationTraceResponseResponseStatus_CommonObjectReference,AuthorizationTraceResponseResponseStatus>> +| +| UNKNOWN_STATUS, SUCCESS, FAILURE, + +| error +| +| +| String +| +| + +|=== + +[id="V1AuthorizationTraceResponseUser_CommonObjectReference"] +=== V1AuthorizationTraceResponseUser + +[id="Fields-V1AuthorizationTraceResponseUser_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| username +| +| +| String +| +| + +| friendlyName +| +| +| String +| +| + +| aggregatedPermissions +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| + +| roles +| +| +| List of <<AuthorizationTraceResponseUserRole_CommonObjectReference,AuthorizationTraceResponseUserRole>> +| +| + +|=== + +[id="V1AutocompleteResponse_CommonObjectReference"] +=== V1AutocompleteResponse + +[id="Fields-V1AutocompleteResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| values +| +| +| List of `string` +| +| + +|=== + +[id="V1AvailableProviderTypesResponse_CommonObjectReference"] +=== V1AvailableProviderTypesResponse + +[id="Fields-V1AvailableProviderTypesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| authProviderTypes +| +| +| List of <<AvailableProviderTypesResponseAuthProviderType_CommonObjectReference,AvailableProviderTypesResponseAuthProviderType>> +| +| + +|=== + +[id="V1BuildDetectionRequest_CommonObjectReference"] +=== V1BuildDetectionRequest + +[id="Fields-V1BuildDetectionRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| image +| +| +| <<StorageContainerImage_CommonObjectReference,StorageContainerImage>> +| +| + +| imageName +| +| +| String +| +| + +| noExternalMetadata +| +| +| Boolean +| +| + +| sendNotifications +| +| +| Boolean +| +| + +| force +| +| +| Boolean +| +| + +| policyCategories +| +| +| List of `string` +| +| + +| cluster +| +| +| String +| Cluster to delegate scan to, may be the cluster's name or ID. +| + +| namespace +| +| +| String +| Namespace on the secured cluster from which to read context information when delegating image scans, specifically pull secrets to access the image registry. +| + +|=== + +[id="V1BuildDetectionResponse_CommonObjectReference"] +=== V1BuildDetectionResponse + +[id="Fields-V1BuildDetectionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| alerts +| +| +| List of <<StorageAlert_CommonObjectReference,StorageAlert>> +| +| + +|=== + +[id="V1CRSGenRequest_CommonObjectReference"] +=== V1CRSGenRequest + +[id="Fields-V1CRSGenRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +|=== + +[id="V1CRSGenResponse_CommonObjectReference"] +=== V1CRSGenResponse + +[id="Fields-V1CRSGenResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| meta +| +| +| <<V1CRSMeta_CommonObjectReference,V1CRSMeta>> +| +| + +| crs +| +| +| byte[] +| +| byte + +|=== + +[id="V1CRSMeta_CommonObjectReference"] +=== V1CRSMeta + +[id="Fields-V1CRSMeta_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| createdAt +| +| +| Date +| +| date-time + +| createdBy +| +| +| <<StorageUser_CommonObjectReference,StorageUser>> +| +| + +| expiresAt +| +| +| Date +| +| date-time + +|=== + +[id="V1CRSMetasResponse_CommonObjectReference"] +=== V1CRSMetasResponse + +[id="Fields-V1CRSMetasResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| items +| +| +| List of <<V1CRSMeta_CommonObjectReference,V1CRSMeta>> +| +| + +|=== + +[id="V1CRSRevokeRequest_CommonObjectReference"] +=== V1CRSRevokeRequest + +[id="Fields-V1CRSRevokeRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| ids +| +| +| List of `string` +| +| + +|=== + +[id="V1CRSRevokeResponse_CommonObjectReference"] +=== V1CRSRevokeResponse + +[id="Fields-V1CRSRevokeResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| crsRevocationErrors +| +| +| List of <<CRSRevokeResponseCRSRevocationError_CommonObjectReference,CRSRevokeResponseCRSRevocationError>> +| +| + +| revokedIds +| +| +| List of `string` +| +| + +|=== + +[id="V1CentralServicesCapabilities_CommonObjectReference"] +=== V1CentralServicesCapabilities + +Provides availability of certain functionality of Central Services in the current configuration. +The initial intended use is to disable certain functionality that does not make sense in the Cloud Service context. + +[id="Fields-V1CentralServicesCapabilities_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| centralScanningCanUseContainerIamRoleForEcr +| +| +| <<CentralServicesCapabilitiesCapabilityStatus_CommonObjectReference,CentralServicesCapabilitiesCapabilityStatus>> +| +| CapabilityAvailable, CapabilityDisabled, + +| centralCanUseCloudBackupIntegrations +| +| +| <<CentralServicesCapabilitiesCapabilityStatus_CommonObjectReference,CentralServicesCapabilitiesCapabilityStatus>> +| +| CapabilityAvailable, CapabilityDisabled, + +| centralCanDisplayDeclarativeConfigHealth +| +| +| <<CentralServicesCapabilitiesCapabilityStatus_CommonObjectReference,CentralServicesCapabilitiesCapabilityStatus>> +| +| CapabilityAvailable, CapabilityDisabled, + +| centralCanUpdateCert +| +| +| <<CentralServicesCapabilitiesCapabilityStatus_CommonObjectReference,CentralServicesCapabilitiesCapabilityStatus>> +| +| CapabilityAvailable, CapabilityDisabled, + +| centralCanUseAcscsEmailIntegration +| +| +| <<CentralServicesCapabilitiesCapabilityStatus_CommonObjectReference,CentralServicesCapabilitiesCapabilityStatus>> +| +| CapabilityAvailable, CapabilityDisabled, + +|=== + +[id="V1CentralUpgradeStatus_CommonObjectReference"] +=== V1CentralUpgradeStatus + +[id="Fields-V1CentralUpgradeStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| version +| +| +| String +| +| + +| forceRollbackTo +| +| +| String +| The version of previous clone in Central. This is the version we can force rollback to. +| + +| canRollbackAfterUpgrade +| +| +| Boolean +| If true, we can rollback to the current version if an upgrade failed. +| + +| spaceRequiredForRollbackAfterUpgrade +| +| +| String +| +| int64 + +| spaceAvailableForRollbackAfterUpgrade +| +| +| String +| +| int64 + +|=== + +[id="V1CloudSource_CommonObjectReference"] +=== V1CloudSource + +CloudSource is an integration which provides a source for discovered +clusters. + +[id="Fields-V1CloudSource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| type +| +| +| <<V1CloudSourceType_CommonObjectReference,V1CloudSourceType>> +| +| TYPE_UNSPECIFIED, TYPE_PALADIN_CLOUD, TYPE_OCM, + +| credentials +| +| +| <<V1CloudSourceCredentials_CommonObjectReference,V1CloudSourceCredentials>> +| +| + +| skipTestIntegration +| +| +| Boolean +| +| + +| paladinCloud +| +| +| <<V1PaladinCloudConfig_CommonObjectReference,V1PaladinCloudConfig>> +| +| + +| ocm +| +| +| <<V1OCMConfig_CommonObjectReference,V1OCMConfig>> +| +| + +|=== + +[id="V1CloudSourceCredentials_CommonObjectReference"] +=== V1CloudSourceCredentials + +[id="Fields-V1CloudSourceCredentials_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| secret +| +| +| String +| Used for single-valued authentication via long-lived tokens. +| + +| clientId +| +| +| String +| Used for client authentication in combination with client_secret. +| + +| clientSecret +| +| +| String +| Used for client authentication in combination with client_id. +| + +|=== + +[id="V1CloudSourceType_CommonObjectReference"] +=== V1CloudSourceType + +[id="Fields-V1CloudSourceType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| TYPE_UNSPECIFIED +| TYPE_PALADIN_CLOUD +| TYPE_OCM + +|=== + +[id="V1CloudSourcesFilter_CommonObjectReference"] +=== V1CloudSourcesFilter + +[id="Fields-V1CloudSourcesFilter_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| names +| +| +| List of `string` +| Matches cloud sources based on their name. +| + +| types +| +| +| List of <<V1CloudSourceType_CommonObjectReference,V1CloudSourceType>> +| Matches cloud sources based on their type. +| + +|=== + +[id="V1ClusterDefaultsResponse_CommonObjectReference"] +=== V1ClusterDefaultsResponse + +[id="Fields-V1ClusterDefaultsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| mainImageRepository +| +| +| String +| +| + +| collectorImageRepository +| +| +| String +| +| + +| kernelSupportAvailable +| +| +| Boolean +| +| + +|=== + +[id="V1ClusterResponse_CommonObjectReference"] +=== V1ClusterResponse + +[id="Fields-V1ClusterResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cluster +| +| +| <<StorageCluster_CommonObjectReference,StorageCluster>> +| +| + +| clusterRetentionInfo +| +| +| <<V1DecommissionedClusterRetentionInfo_CommonObjectReference,V1DecommissionedClusterRetentionInfo>> +| +| + +|=== + +[id="V1ClustersList_CommonObjectReference"] +=== V1ClustersList + +[id="Fields-V1ClustersList_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusters +| +| +| List of <<StorageCluster_CommonObjectReference,StorageCluster>> +| +| + +| clusterIdToRetentionInfo +| +| +| Map of <<V1DecommissionedClusterRetentionInfo_CommonObjectReference,V1DecommissionedClusterRetentionInfo>> +| +| + +|=== + +[id="V1CollectionDeploymentMatchOptions_CommonObjectReference"] +=== V1CollectionDeploymentMatchOptions + +[id="Fields-V1CollectionDeploymentMatchOptions_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| withMatches +| +| +| Boolean +| +| + +| filterQuery +| +| +| <<V1RawQuery_CommonObjectReference,V1RawQuery>> +| +| + +|=== + +[id="V1ComplianceControl_CommonObjectReference"] +=== V1ComplianceControl + +[id="Fields-V1ComplianceControl_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| standardId +| +| +| String +| +| + +| groupId +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| implemented +| +| +| Boolean +| +| + +| interpretationText +| +| +| String +| +| + +|=== + +[id="V1ComplianceControlGroup_CommonObjectReference"] +=== V1ComplianceControlGroup + +[id="Fields-V1ComplianceControlGroup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| standardId +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| numImplementedChecks +| +| +| Integer +| +| int32 + +|=== + +[id="V1ComplianceRun_CommonObjectReference"] +=== V1ComplianceRun + +[id="Fields-V1ComplianceRun_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| standardId +| +| +| String +| +| + +| startTime +| +| +| Date +| +| date-time + +| finishTime +| +| +| Date +| +| date-time + +| state +| +| +| <<V1ComplianceRunState_CommonObjectReference,V1ComplianceRunState>> +| +| INVALID, READY, STARTED, WAIT_FOR_DATA, EVALUTING_CHECKS, FINISHED, + +| errorMessage +| +| +| String +| +| + +|=== + +[id="V1ComplianceRunSelection_CommonObjectReference"] +=== V1ComplianceRunSelection + +[id="Fields-V1ComplianceRunSelection_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| The ID of the cluster. "*" means "all clusters". +| + +| standardId +| +| +| String +| The ID of the compliance standard. "*" means "all standards". +| + +|=== + +[id="V1ComplianceRunState_CommonObjectReference"] +=== V1ComplianceRunState + +[id="Fields-V1ComplianceRunState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| INVALID +| READY +| STARTED +| WAIT_FOR_DATA +| EVALUTING_CHECKS +| FINISHED + +|=== + +[id="V1ComplianceStandard_CommonObjectReference"] +=== V1ComplianceStandard + +[id="Fields-V1ComplianceStandard_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| metadata +| +| +| <<V1ComplianceStandardMetadata_CommonObjectReference,V1ComplianceStandardMetadata>> +| +| + +| groups +| +| +| List of <<V1ComplianceControlGroup_CommonObjectReference,V1ComplianceControlGroup>> +| +| + +| controls +| +| +| List of <<V1ComplianceControl_CommonObjectReference,V1ComplianceControl>> +| +| + +|=== + +[id="V1ComplianceStandardMetadata_CommonObjectReference"] +=== V1ComplianceStandardMetadata + +[id="Fields-V1ComplianceStandardMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| numImplementedChecks +| +| +| Integer +| +| int32 + +| scopes +| +| +| List of <<V1ComplianceStandardMetadataScope_CommonObjectReference,V1ComplianceStandardMetadataScope>> +| +| + +| dynamic +| +| +| Boolean +| +| + +| hideScanResults +| +| +| Boolean +| +| + +|=== + +[id="V1ComplianceStandardMetadataScope_CommonObjectReference"] +=== V1ComplianceStandardMetadataScope + +[id="Fields-V1ComplianceStandardMetadataScope_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| CLUSTER +| NAMESPACE +| DEPLOYMENT +| NODE + +|=== + +[id="V1ConfigureTelemetryRequest_CommonObjectReference"] +=== V1ConfigureTelemetryRequest + +[id="Fields-V1ConfigureTelemetryRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enabled +| +| +| Boolean +| +| + +|=== + +[id="V1CountAdministrationEventsResponse_CommonObjectReference"] +=== V1CountAdministrationEventsResponse + +[id="Fields-V1CountAdministrationEventsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| The total number of events after filtering and deduplication. +| int32 + +|=== + +[id="V1CountAlertsResponse_CommonObjectReference"] +=== V1CountAlertsResponse + +[id="Fields-V1CountAlertsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1CountCloudSourcesResponse_CommonObjectReference"] +=== V1CountCloudSourcesResponse + +[id="Fields-V1CountCloudSourcesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1CountDeploymentsResponse_CommonObjectReference"] +=== V1CountDeploymentsResponse + +[id="Fields-V1CountDeploymentsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1CountDiscoveredClustersResponse_CommonObjectReference"] +=== V1CountDiscoveredClustersResponse + +[id="Fields-V1CountDiscoveredClustersResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1CountImagesResponse_CommonObjectReference"] +=== V1CountImagesResponse + +[id="Fields-V1CountImagesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1CountProcessesResponse_CommonObjectReference"] +=== V1CountProcessesResponse + +[id="Fields-V1CountProcessesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1CountReportConfigurationsResponse_CommonObjectReference"] +=== V1CountReportConfigurationsResponse + +[id="Fields-V1CountReportConfigurationsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1CountSecretsResponse_CommonObjectReference"] +=== V1CountSecretsResponse + +[id="Fields-V1CountSecretsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1CreateCloudSourceRequest_CommonObjectReference"] +=== V1CreateCloudSourceRequest + +[id="Fields-V1CreateCloudSourceRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cloudSource +| +| +| <<V1CloudSource_CommonObjectReference,V1CloudSource>> +| +| + +|=== + +[id="V1CreateCloudSourceResponse_CommonObjectReference"] +=== V1CreateCloudSourceResponse + +[id="Fields-V1CreateCloudSourceResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cloudSource +| +| +| <<V1CloudSource_CommonObjectReference,V1CloudSource>> +| +| + +|=== + +[id="V1CreateCollectionRequest_CommonObjectReference"] +=== V1CreateCollectionRequest + +[id="Fields-V1CreateCollectionRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| resourceSelectors +| +| +| List of <<StorageResourceSelector_CommonObjectReference,StorageResourceSelector>> +| +| + +| embeddedCollectionIds +| +| +| List of `string` +| +| + +|=== + +[id="V1CreateCollectionResponse_CommonObjectReference"] +=== V1CreateCollectionResponse + +[id="Fields-V1CreateCollectionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| collection +| +| +| <<StorageResourceCollection_CommonObjectReference,StorageResourceCollection>> +| +| + +|=== + +[id="V1CreateServiceIdentityRequest_CommonObjectReference"] +=== V1CreateServiceIdentityRequest + +[id="Fields-V1CreateServiceIdentityRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| type +| +| +| <<StorageServiceType_CommonObjectReference,StorageServiceType>> +| +| UNKNOWN_SERVICE, SENSOR_SERVICE, CENTRAL_SERVICE, CENTRAL_DB_SERVICE, REMOTE_SERVICE, COLLECTOR_SERVICE, MONITORING_UI_SERVICE, MONITORING_DB_SERVICE, MONITORING_CLIENT_SERVICE, BENCHMARK_SERVICE, SCANNER_SERVICE, SCANNER_DB_SERVICE, ADMISSION_CONTROL_SERVICE, SCANNER_V4_INDEXER_SERVICE, SCANNER_V4_MATCHER_SERVICE, SCANNER_V4_DB_SERVICE, SCANNER_V4_SERVICE, REGISTRANT_SERVICE, + +|=== + +[id="V1CreateServiceIdentityResponse_CommonObjectReference"] +=== V1CreateServiceIdentityResponse + +[id="Fields-V1CreateServiceIdentityResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| identity +| +| +| <<StorageServiceIdentity_CommonObjectReference,StorageServiceIdentity>> +| +| + +| certificatePem +| +| +| byte[] +| +| byte + +| privateKeyPem +| +| +| byte[] +| +| byte + +|=== + +[id="V1DBExportFormat_CommonObjectReference"] +=== V1DBExportFormat + +DBExportFormat describes a format (= a collection of files) for the database export. + +[id="Fields-V1DBExportFormat_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| formatName +| +| +| String +| +| + +| files +| +| +| List of <<V1DBExportFormatFile_CommonObjectReference,V1DBExportFormatFile>> +| +| + +|=== + +[id="V1DBExportFormatFile_CommonObjectReference"] +=== V1DBExportFormatFile + +[id="Fields-V1DBExportFormatFile_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| optional +| +| +| Boolean +| +| + +|=== + +[id="V1DBExportManifest_CommonObjectReference"] +=== V1DBExportManifest + +A DB export manifest describes the file contents of a restore request. To prevent data loss, a manifest is always +interpreted as binding, i.e., the server must ensure that it will read and make use of every file listed in the +manifest, otherwise it must reject the request. + +[id="Fields-V1DBExportManifest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| files +| +| +| List of <<V1DBExportManifestFile_CommonObjectReference,V1DBExportManifestFile>> +| +| + +|=== + +[id="V1DBExportManifestFile_CommonObjectReference"] +=== V1DBExportManifestFile + +A single file in the restore body. + +[id="Fields-V1DBExportManifestFile_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| The name of the file. This may or may not be a (relative) file path and up to the server to interpret. For databases exported as ZIP files, this is the path relative to the root of the archive. +| + +| encoding +| +| +| <<DBExportManifestEncodingType_CommonObjectReference,DBExportManifestEncodingType>> +| +| UNKNOWN, UNCOMPREESSED, DEFLATED, + +| encodedSize +| +| +| String +| +| int64 + +| decodedSize +| +| +| String +| +| int64 + +| decodedCrc32 +| +| +| Long +| The CRC32 (IEEE) checksum of the decoded(!) data. +| int64 + +|=== + +[id="V1DBRestoreProcessMetadata_CommonObjectReference"] +=== V1DBRestoreProcessMetadata + +The metadata of an ongoing or completed restore process. This is the *static* metadata, which will not change +(i.e., it is not a status). + +[id="Fields-V1DBRestoreProcessMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| An ID identifying the restore process. Auto-assigned. +| + +| header +| +| +| <<V1DBRestoreRequestHeader_CommonObjectReference,V1DBRestoreRequestHeader>> +| +| + +| startTime +| +| +| Date +| The time at which the restore process was started. +| date-time + +| initiatingUserName +| +| +| String +| The user who initiated the database restore process. +| + +|=== + +[id="V1DBRestoreProcessStatus_CommonObjectReference"] +=== V1DBRestoreProcessStatus + +[id="Fields-V1DBRestoreProcessStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| metadata +| +| +| <<V1DBRestoreProcessMetadata_CommonObjectReference,V1DBRestoreProcessMetadata>> +| +| + +| attemptId +| +| +| String +| +| + +| state +| +| +| <<V1DBRestoreProcessStatusState_CommonObjectReference,V1DBRestoreProcessStatusState>> +| +| UNKNOWN, NOT_STARTED, IN_PROGRESS, PAUSED, COMPLETED, + +| resumeInfo +| +| +| <<DBRestoreProcessStatusResumeInfo_CommonObjectReference,DBRestoreProcessStatusResumeInfo>> +| +| + +| error +| +| +| String +| +| + +| bytesRead +| +| +| String +| +| int64 + +| filesProcessed +| +| +| String +| +| int64 + +|=== + +[id="V1DBRestoreProcessStatusState_CommonObjectReference"] +=== V1DBRestoreProcessStatusState + +- COMPLETED: successful if error is empty, unsuccessful otherwise + +[id="Fields-V1DBRestoreProcessStatusState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| NOT_STARTED +| IN_PROGRESS +| PAUSED +| COMPLETED + +|=== + +[id="V1DBRestoreRequestHeader_CommonObjectReference"] +=== V1DBRestoreRequestHeader + +[id="Fields-V1DBRestoreRequestHeader_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| formatName +| +| +| String +| The name of the database export format. Mandatory. +| + +| manifest +| +| +| <<V1DBExportManifest_CommonObjectReference,V1DBExportManifest>> +| +| + +| localFile +| +| +| <<DBRestoreRequestHeaderLocalFileInfo_CommonObjectReference,DBRestoreRequestHeaderLocalFileInfo>> +| +| + +|=== + +[id="V1DatabaseBackupStatus_CommonObjectReference"] +=== V1DatabaseBackupStatus + +[id="Fields-V1DatabaseBackupStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| backupInfo +| +| +| <<StorageBackupInfo_CommonObjectReference,StorageBackupInfo>> +| +| + +|=== + +[id="V1DatabaseStatus_CommonObjectReference"] +=== V1DatabaseStatus + +[id="Fields-V1DatabaseStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| databaseAvailable +| +| +| Boolean +| +| + +| databaseType +| +| +| <<DatabaseStatusDatabaseType_CommonObjectReference,DatabaseStatusDatabaseType>> +| +| Hidden, RocksDB, PostgresDB, + +| databaseVersion +| +| +| String +| +| + +| databaseIsExternal +| +| +| Boolean +| +| + +|=== + +[id="V1DayOption_CommonObjectReference"] +=== V1DayOption + +[id="Fields-V1DayOption_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| numDays +| +| +| Long +| +| int64 + +| enabled +| +| +| Boolean +| +| + +|=== + +[id="V1DecommissionedClusterRetentionInfo_CommonObjectReference"] +=== V1DecommissionedClusterRetentionInfo + +next available tag: 3 + +[id="Fields-V1DecommissionedClusterRetentionInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| isExcluded +| +| +| Boolean +| +| + +| daysUntilDeletion +| +| +| Integer +| +| int32 + +|=== + +[id="V1DeferVulnRequest_CommonObjectReference"] +=== V1DeferVulnRequest + +next available tag: 6 + +[id="Fields-V1DeferVulnRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cve +| +| +| String +| This field indicates the CVEs requested to be deferred. +| + +| comment +| +| +| String +| +| + +| scope +| +| +| <<StorageVulnerabilityRequestScope_CommonObjectReference,StorageVulnerabilityRequestScope>> +| +| + +| expiresWhenFixed +| +| +| Boolean +| +| + +| expiresOn +| +| +| Date +| +| date-time + +|=== + +[id="V1DeferVulnResponse_CommonObjectReference"] +=== V1DeferVulnResponse + +[id="Fields-V1DeferVulnResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requestInfo +| +| +| <<StorageVulnerabilityRequest_CommonObjectReference,StorageVulnerabilityRequest>> +| +| + +|=== + +[id="V1DelegatedRegistryCluster_CommonObjectReference"] +=== V1DelegatedRegistryCluster + +[id="Fields-V1DelegatedRegistryCluster_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| isValid +| +| +| Boolean +| +| + +|=== + +[id="V1DelegatedRegistryClustersResponse_CommonObjectReference"] +=== V1DelegatedRegistryClustersResponse + +[id="Fields-V1DelegatedRegistryClustersResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusters +| +| +| List of <<V1DelegatedRegistryCluster_CommonObjectReference,V1DelegatedRegistryCluster>> +| +| + +|=== + +[id="V1DelegatedRegistryConfig_CommonObjectReference"] +=== V1DelegatedRegistryConfig + +DelegatedRegistryConfig determines if and where scan requests are delegated to, such as kept in +central services or sent to particular secured clusters. + +[id="Fields-V1DelegatedRegistryConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| enabledFor +| +| +| <<DelegatedRegistryConfigEnabledFor_CommonObjectReference,DelegatedRegistryConfigEnabledFor>> +| +| NONE, ALL, SPECIFIC, + +| defaultClusterId +| +| +| String +| +| + +| registries +| +| +| List of <<DelegatedRegistryConfigDelegatedRegistry_CommonObjectReference,DelegatedRegistryConfigDelegatedRegistry>> +| If `enabled for` is NONE registries has no effect. If `ALL` registries directs ad-hoc requests to the specified secured clusters if the path matches. If `SPECIFIC` registries directs ad-hoc requests to the specified secured clusters just like with `ALL`, but in addition images that match the specified paths will be scanned locally by the secured clusters (images from the OCP integrated registry are always scanned locally). Images that do not match a path will be scanned via central services +| + +|=== + +[id="V1DeleteAlertsResponse_CommonObjectReference"] +=== V1DeleteAlertsResponse + +[id="Fields-V1DeleteAlertsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| numDeleted +| +| +| Long +| +| int64 + +| dryRun +| +| +| Boolean +| +| + +|=== + +[id="V1DeleteImagesResponse_CommonObjectReference"] +=== V1DeleteImagesResponse + +[id="Fields-V1DeleteImagesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| numDeleted +| +| +| Long +| +| int64 + +| dryRun +| +| +| Boolean +| +| + +|=== + +[id="V1DeleteProcessBaselinesResponse_CommonObjectReference"] +=== V1DeleteProcessBaselinesResponse + +[id="Fields-V1DeleteProcessBaselinesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| numDeleted +| +| +| Integer +| +| int32 + +| dryRun +| +| +| Boolean +| +| + +|=== + +[id="V1DenyVulnRequestResponse_CommonObjectReference"] +=== V1DenyVulnRequestResponse + +[id="Fields-V1DenyVulnRequestResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requestInfo +| +| +| <<StorageVulnerabilityRequest_CommonObjectReference,StorageVulnerabilityRequest>> +| +| + +|=== + +[id="V1DeployDetectionRemark_CommonObjectReference"] +=== V1DeployDetectionRemark + +[id="Fields-V1DeployDetectionRemark_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| permissionLevel +| +| +| String +| +| + +| appliedNetworkPolicies +| +| +| List of `string` +| +| + +|=== + +[id="V1DeployDetectionRequest_CommonObjectReference"] +=== V1DeployDetectionRequest + +[id="Fields-V1DeployDetectionRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployment +| +| +| <<StorageDeployment_CommonObjectReference,StorageDeployment>> +| +| + +| noExternalMetadata +| +| +| Boolean +| +| + +| enforcementOnly +| +| +| Boolean +| +| + +| clusterId +| +| +| String +| +| + +|=== + +[id="V1DeployDetectionResponse_CommonObjectReference"] +=== V1DeployDetectionResponse + +[id="Fields-V1DeployDetectionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| runs +| +| +| List of <<DeployDetectionResponseRun_CommonObjectReference,DeployDetectionResponseRun>> +| +| + +| ignoredObjectRefs +| +| +| List of `string` +| The reference will be in the format: namespace/name[<group>/<version>, Kind=<kind>]. +| + +| remarks +| +| +| List of <<V1DeployDetectionRemark_CommonObjectReference,V1DeployDetectionRemark>> +| +| + +|=== + +[id="V1DeployYAMLDetectionRequest_CommonObjectReference"] +=== V1DeployYAMLDetectionRequest + +[id="Fields-V1DeployYAMLDetectionRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| yaml +| +| +| String +| +| + +| noExternalMetadata +| +| +| Boolean +| +| + +| enforcementOnly +| +| +| Boolean +| +| + +| force +| +| +| Boolean +| +| + +| policyCategories +| +| +| List of `string` +| +| + +| cluster +| +| +| String +| Cluster to delegate scan to, may be the cluster's name or ID. +| + +| namespace +| +| +| String +| +| + +|=== + +[id="V1DeploymentLabelsResponse_CommonObjectReference"] +=== V1DeploymentLabelsResponse + +[id="Fields-V1DeploymentLabelsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| labels +| +| +| Map of <<DeploymentLabelsResponseLabelValues_CommonObjectReference,DeploymentLabelsResponseLabelValues>> +| +| + +| values +| +| +| List of `string` +| +| + +|=== + +[id="V1DiscoveredCluster_CommonObjectReference"] +=== V1DiscoveredCluster + +DiscoveredCluster represents a cluster discovered from a cloud source. + +[id="Fields-V1DiscoveredCluster_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| UUIDv5 generated deterministically from the tuple (metadata.id, metadata.type, source.id). +| + +| metadata +| +| +| <<V1DiscoveredClusterMetadata_CommonObjectReference,V1DiscoveredClusterMetadata>> +| +| + +| status +| +| +| <<V1DiscoveredClusterStatus_CommonObjectReference,V1DiscoveredClusterStatus>> +| +| STATUS_UNSPECIFIED, STATUS_SECURED, STATUS_UNSECURED, + +| source +| +| +| <<V1DiscoveredClusterCloudSource_CommonObjectReference,V1DiscoveredClusterCloudSource>> +| +| + +|=== + +[id="V1DiscoveredClusterCloudSource_CommonObjectReference"] +=== V1DiscoveredClusterCloudSource + +[id="Fields-V1DiscoveredClusterCloudSource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +|=== + +[id="V1DiscoveredClusterMetadata_CommonObjectReference"] +=== V1DiscoveredClusterMetadata + +[id="Fields-V1DiscoveredClusterMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| Represents a unique ID under which the cluster is registered with the cloud provider. Matches storage.ClusterMetadata.id for secured clusters. +| + +| name +| +| +| String +| Represents the name under which the cluster is registered with the cloud provider. Matches storage.ClusterMetadata.name for secured clusters. +| + +| type +| +| +| <<DiscoveredClusterMetadataType_CommonObjectReference,DiscoveredClusterMetadataType>> +| +| UNSPECIFIED, AKS, ARO, EKS, GKE, OCP, OSD, ROSA, + +| providerType +| +| +| <<MetadataProviderType_CommonObjectReference,MetadataProviderType>> +| +| PROVIDER_TYPE_UNSPECIFIED, PROVIDER_TYPE_AWS, PROVIDER_TYPE_GCP, PROVIDER_TYPE_AZURE, + +| region +| +| +| String +| The region as reported by the cloud provider. +| + +| firstDiscoveredAt +| +| +| Date +| Timestamp at which the cluster was first discovered by the cloud source. +| date-time + +|=== + +[id="V1DiscoveredClusterStatus_CommonObjectReference"] +=== V1DiscoveredClusterStatus + + - STATUS_UNSPECIFIED: The status of the cluster is unknown. May occur if a secured cluster +is missing the metadata for a possible match. + - STATUS_SECURED: The discovered cluster was matched with a secured cluster. + - STATUS_UNSECURED: The discovered cluster was not matched with a secured cluster. + +[id="Fields-V1DiscoveredClusterStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| STATUS_UNSPECIFIED +| STATUS_SECURED +| STATUS_UNSECURED + +|=== + +[id="V1DiscoveredClustersFilter_CommonObjectReference"] +=== V1DiscoveredClustersFilter + +[id="Fields-V1DiscoveredClustersFilter_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| names +| +| +| List of `string` +| Matches discovered clusters of specific names. +| + +| types +| +| +| List of <<DiscoveredClusterMetadataType_CommonObjectReference,DiscoveredClusterMetadataType>> +| Matches discovered clusters of specific types. +| + +| statuses +| +| +| List of <<V1DiscoveredClusterStatus_CommonObjectReference,V1DiscoveredClusterStatus>> +| Matches discovered clusters of specific statuses. +| + +| sourceIds +| +| +| List of `string` +| Matches discovered clusters of specific cloud source IDs. +| + +|=== + +[id="V1DryRunCollectionRequest_CommonObjectReference"] +=== V1DryRunCollectionRequest + +[id="Fields-V1DryRunCollectionRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| id +| +| +| String +| +| + +| description +| +| +| String +| +| + +| resourceSelectors +| +| +| List of <<StorageResourceSelector_CommonObjectReference,StorageResourceSelector>> +| +| + +| embeddedCollectionIds +| +| +| List of `string` +| +| + +| options +| +| +| <<V1CollectionDeploymentMatchOptions_CommonObjectReference,V1CollectionDeploymentMatchOptions>> +| +| + +|=== + +[id="V1DryRunCollectionResponse_CommonObjectReference"] +=== V1DryRunCollectionResponse + +[id="Fields-V1DryRunCollectionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployments +| +| +| List of <<StorageListDeployment_CommonObjectReference,StorageListDeployment>> +| +| + +|=== + +[id="V1DryRunJobStatusResponse_CommonObjectReference"] +=== V1DryRunJobStatusResponse + +[id="Fields-V1DryRunJobStatusResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| pending +| +| +| Boolean +| +| + +| result +| +| +| <<V1DryRunResponse_CommonObjectReference,V1DryRunResponse>> +| +| + +|=== + +[id="V1DryRunResponse_CommonObjectReference"] +=== V1DryRunResponse + +[id="Fields-V1DryRunResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| alerts +| +| +| List of <<V1DryRunResponseAlert_CommonObjectReference,V1DryRunResponseAlert>> +| +| + +|=== + +[id="V1DryRunResponseAlert_CommonObjectReference"] +=== V1DryRunResponseAlert + +[id="Fields-V1DryRunResponseAlert_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployment +| +| +| String +| +| + +| violations +| +| +| List of `string` +| +| + +|=== + +[id="V1ExchangeAuthMachineToMachineTokenRequest_CommonObjectReference"] +=== V1ExchangeAuthMachineToMachineTokenRequest + +[id="Fields-V1ExchangeAuthMachineToMachineTokenRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| idToken +| +| +| String +| Identity token that is supposed to be exchanged. +| + +|=== + +[id="V1ExchangeAuthMachineToMachineTokenResponse_CommonObjectReference"] +=== V1ExchangeAuthMachineToMachineTokenResponse + +[id="Fields-V1ExchangeAuthMachineToMachineTokenResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| accessToken +| +| +| String +| The exchanged access token. +| + +|=== + +[id="V1ExchangeTokenRequest_CommonObjectReference"] +=== V1ExchangeTokenRequest + +[id="Fields-V1ExchangeTokenRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| externalToken +| +| +| String +| The external authentication token. The server will mask the value of this credential in responses and logs. +| + +| type +| +| +| String +| +| + +| state +| +| +| String +| +| + +|=== + +[id="V1ExchangeTokenResponse_CommonObjectReference"] +=== V1ExchangeTokenResponse + +[id="Fields-V1ExchangeTokenResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| token +| +| +| String +| +| + +| clientState +| +| +| String +| +| + +| test +| +| +| Boolean +| +| + +| user +| +| +| <<V1AuthStatus_CommonObjectReference,V1AuthStatus>> +| +| + +|=== + +[id="V1ExportDeploymentResponse_CommonObjectReference"] +=== V1ExportDeploymentResponse + +[id="Fields-V1ExportDeploymentResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployment +| +| +| <<StorageDeployment_CommonObjectReference,StorageDeployment>> +| +| + +|=== + +[id="V1ExportImageResponse_CommonObjectReference"] +=== V1ExportImageResponse + +[id="Fields-V1ExportImageResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| image +| +| +| <<StorageImage_CommonObjectReference,StorageImage>> +| +| + +|=== + +[id="V1ExportNodeResponse_CommonObjectReference"] +=== V1ExportNodeResponse + +[id="Fields-V1ExportNodeResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| node +| +| +| <<StorageNode_CommonObjectReference,StorageNode>> +| +| + +|=== + +[id="V1ExportPodResponse_CommonObjectReference"] +=== V1ExportPodResponse + +[id="Fields-V1ExportPodResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| pod +| +| +| <<StoragePod_CommonObjectReference,StoragePod>> +| +| + +|=== + +[id="V1ExportPoliciesRequest_CommonObjectReference"] +=== V1ExportPoliciesRequest + +[id="Fields-V1ExportPoliciesRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| policyIds +| +| +| List of `string` +| +| + +|=== + +[id="V1ExternalNetworkFlowMetadata_CommonObjectReference"] +=== V1ExternalNetworkFlowMetadata + +[id="Fields-V1ExternalNetworkFlowMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entity +| +| +| <<StorageNetworkEntityInfo_CommonObjectReference,StorageNetworkEntityInfo>> +| +| + +| flowsCount +| +| +| Integer +| +| int32 + +|=== + +[id="V1FalsePositiveVulnRequest_CommonObjectReference"] +=== V1FalsePositiveVulnRequest + +[id="Fields-V1FalsePositiveVulnRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cve +| +| +| String +| This field indicates the CVE requested to be marked as false-positive. +| + +| scope +| +| +| <<StorageVulnerabilityRequestScope_CommonObjectReference,StorageVulnerabilityRequestScope>> +| +| + +| comment +| +| +| String +| +| + +|=== + +[id="V1FalsePositiveVulnResponse_CommonObjectReference"] +=== V1FalsePositiveVulnResponse + +[id="Fields-V1FalsePositiveVulnResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requestInfo +| +| +| <<StorageVulnerabilityRequest_CommonObjectReference,StorageVulnerabilityRequest>> +| +| + +|=== + +[id="V1FeatureFlag_CommonObjectReference"] +=== V1FeatureFlag + +[id="Fields-V1FeatureFlag_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| envVar +| +| +| String +| +| + +| enabled +| +| +| Boolean +| +| + +|=== + +[id="V1GenerateNetworkPoliciesResponse_CommonObjectReference"] +=== V1GenerateNetworkPoliciesResponse + +Next available tag: 2 + +[id="Fields-V1GenerateNetworkPoliciesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| modification +| +| +| <<StorageNetworkPolicyModification_CommonObjectReference,StorageNetworkPolicyModification>> +| +| + +|=== + +[id="V1GenerateTokenRequest_CommonObjectReference"] +=== V1GenerateTokenRequest + +[id="Fields-V1GenerateTokenRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| role +| +| +| String +| +| + +| roles +| +| +| List of `string` +| +| + +| expiration +| +| +| Date +| +| date-time + +|=== + +[id="V1GenerateTokenResponse_CommonObjectReference"] +=== V1GenerateTokenResponse + +[id="Fields-V1GenerateTokenResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| token +| +| +| String +| +| + +| metadata +| +| +| <<StorageTokenMetadata_CommonObjectReference,StorageTokenMetadata>> +| +| + +|=== + +[id="V1GetAPITokensResponse_CommonObjectReference"] +=== V1GetAPITokensResponse + +[id="Fields-V1GetAPITokensResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| tokens +| +| +| List of <<StorageTokenMetadata_CommonObjectReference,StorageTokenMetadata>> +| +| + +|=== + +[id="V1GetActiveDBRestoreProcessResponse_CommonObjectReference"] +=== V1GetActiveDBRestoreProcessResponse + +[id="Fields-V1GetActiveDBRestoreProcessResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| activeStatus +| +| +| <<V1DBRestoreProcessStatus_CommonObjectReference,V1DBRestoreProcessStatus>> +| +| + +|=== + +[id="V1GetAdministrationEventResponse_CommonObjectReference"] +=== V1GetAdministrationEventResponse + +[id="Fields-V1GetAdministrationEventResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| event +| +| +| <<V1AdministrationEvent_CommonObjectReference,V1AdministrationEvent>> +| +| + +|=== + +[id="V1GetAlertTimeseriesResponse_CommonObjectReference"] +=== V1GetAlertTimeseriesResponse + +[id="Fields-V1GetAlertTimeseriesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusters +| +| +| List of <<GetAlertTimeseriesResponseClusterAlerts_CommonObjectReference,GetAlertTimeseriesResponseClusterAlerts>> +| +| + +|=== + +[id="V1GetAlertsCountsResponse_CommonObjectReference"] +=== V1GetAlertsCountsResponse + +[id="Fields-V1GetAlertsCountsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| groups +| +| +| List of <<GetAlertsCountsResponseAlertGroup_CommonObjectReference,GetAlertsCountsResponseAlertGroup>> +| +| + +|=== + +[id="V1GetAlertsGroupResponse_CommonObjectReference"] +=== V1GetAlertsGroupResponse + +[id="Fields-V1GetAlertsGroupResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| alertsByPolicies +| +| +| List of <<V1GetAlertsGroupResponsePolicyGroup_CommonObjectReference,V1GetAlertsGroupResponsePolicyGroup>> +| +| + +|=== + +[id="V1GetAlertsGroupResponsePolicyGroup_CommonObjectReference"] +=== V1GetAlertsGroupResponsePolicyGroup + +[id="Fields-V1GetAlertsGroupResponsePolicyGroup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| policy +| +| +| <<StorageListAlertPolicy_CommonObjectReference,StorageListAlertPolicy>> +| +| + +| numAlerts +| +| +| String +| +| int64 + +|=== + +[id="V1GetAllowedPeersFromCurrentPolicyForDeploymentResponse_CommonObjectReference"] +=== V1GetAllowedPeersFromCurrentPolicyForDeploymentResponse + +[id="Fields-V1GetAllowedPeersFromCurrentPolicyForDeploymentResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| allowedPeers +| +| +| List of <<V1NetworkBaselineStatusPeer_CommonObjectReference,V1NetworkBaselineStatusPeer>> +| +| + +|=== + +[id="V1GetAuthMachineToMachineConfigResponse_CommonObjectReference"] +=== V1GetAuthMachineToMachineConfigResponse + +[id="Fields-V1GetAuthMachineToMachineConfigResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<V1AuthMachineToMachineConfig_CommonObjectReference,V1AuthMachineToMachineConfig>> +| +| + +|=== + +[id="V1GetAuthProvidersResponse_CommonObjectReference"] +=== V1GetAuthProvidersResponse + +[id="Fields-V1GetAuthProvidersResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| authProviders +| +| +| List of <<StorageAuthProvider_CommonObjectReference,StorageAuthProvider>> +| +| + +|=== + +[id="V1GetBaselineGeneratedPolicyForDeploymentResponse_CommonObjectReference"] +=== V1GetBaselineGeneratedPolicyForDeploymentResponse + +[id="Fields-V1GetBaselineGeneratedPolicyForDeploymentResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| modification +| +| +| <<StorageNetworkPolicyModification_CommonObjectReference,StorageNetworkPolicyModification>> +| +| + +|=== + +[id="V1GetCAConfigResponse_CommonObjectReference"] +=== V1GetCAConfigResponse + +[id="Fields-V1GetCAConfigResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| helmValuesBundle +| +| +| byte[] +| +| byte + +|=== + +[id="V1GetCertExpiryComponent_CommonObjectReference"] +=== V1GetCertExpiryComponent + +[id="Fields-V1GetCertExpiryComponent_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN +| CENTRAL +| SCANNER +| SCANNER_V4 +| CENTRAL_DB + +|=== + +[id="V1GetCertExpiryResponse_CommonObjectReference"] +=== V1GetCertExpiryResponse + +[id="Fields-V1GetCertExpiryResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| expiry +| +| +| Date +| +| date-time + +|=== + +[id="V1GetCloudSourceResponse_CommonObjectReference"] +=== V1GetCloudSourceResponse + +[id="Fields-V1GetCloudSourceResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cloudSource +| +| +| <<V1CloudSource_CommonObjectReference,V1CloudSource>> +| +| + +|=== + +[id="V1GetClustersForPermissionsResponse_CommonObjectReference"] +=== V1GetClustersForPermissionsResponse + +[id="Fields-V1GetClustersForPermissionsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusters +| +| +| List of <<V1ScopeObject_CommonObjectReference,V1ScopeObject>> +| +| + +|=== + +[id="V1GetCollectionCountResponse_CommonObjectReference"] +=== V1GetCollectionCountResponse + +[id="Fields-V1GetCollectionCountResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V1GetCollectionResponse_CommonObjectReference"] +=== V1GetCollectionResponse + +[id="Fields-V1GetCollectionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| collection +| +| +| <<StorageResourceCollection_CommonObjectReference,StorageResourceCollection>> +| +| + +| deployments +| +| +| List of <<StorageListDeployment_CommonObjectReference,StorageListDeployment>> +| +| + +|=== + +[id="V1GetComplianceRunResultsResponse_CommonObjectReference"] +=== V1GetComplianceRunResultsResponse + +[id="Fields-V1GetComplianceRunResultsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| results +| +| +| <<StorageComplianceRunResults_CommonObjectReference,StorageComplianceRunResults>> +| +| + +| failedRuns +| +| +| List of <<StorageComplianceRunMetadata_CommonObjectReference,StorageComplianceRunMetadata>> +| +| + +|=== + +[id="V1GetComplianceRunStatusesResponse_CommonObjectReference"] +=== V1GetComplianceRunStatusesResponse + +[id="Fields-V1GetComplianceRunStatusesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| invalidRunIds +| +| +| List of `string` +| +| + +| runs +| +| +| List of <<V1ComplianceRun_CommonObjectReference,V1ComplianceRun>> +| +| + +|=== + +[id="V1GetComplianceStandardResponse_CommonObjectReference"] +=== V1GetComplianceStandardResponse + +[id="Fields-V1GetComplianceStandardResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| standard +| +| +| <<V1ComplianceStandard_CommonObjectReference,V1ComplianceStandard>> +| +| + +|=== + +[id="V1GetComplianceStandardsResponse_CommonObjectReference"] +=== V1GetComplianceStandardsResponse + +[id="Fields-V1GetComplianceStandardsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| standards +| +| +| List of <<V1ComplianceStandardMetadata_CommonObjectReference,V1ComplianceStandardMetadata>> +| +| + +|=== + +[id="V1GetDBExportCapabilitiesResponse_CommonObjectReference"] +=== V1GetDBExportCapabilitiesResponse + +[id="Fields-V1GetDBExportCapabilitiesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| formats +| +| +| List of <<V1DBExportFormat_CommonObjectReference,V1DBExportFormat>> +| +| + +| supportedEncodings +| +| +| List of <<DBExportManifestEncodingType_CommonObjectReference,DBExportManifestEncodingType>> +| +| + +|=== + +[id="V1GetDeclarativeConfigHealthsResponse_CommonObjectReference"] +=== V1GetDeclarativeConfigHealthsResponse + +[id="Fields-V1GetDeclarativeConfigHealthsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| healths +| +| +| List of <<StorageDeclarativeConfigHealth_CommonObjectReference,StorageDeclarativeConfigHealth>> +| +| + +|=== + +[id="V1GetDefaultRedHatLayeredProductsRegexResponse_CommonObjectReference"] +=== V1GetDefaultRedHatLayeredProductsRegexResponse + +[id="Fields-V1GetDefaultRedHatLayeredProductsRegexResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| regex +| +| +| String +| +| + +|=== + +[id="V1GetDeploymentWithRiskResponse_CommonObjectReference"] +=== V1GetDeploymentWithRiskResponse + +[id="Fields-V1GetDeploymentWithRiskResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployment +| +| +| <<StorageDeployment_CommonObjectReference,StorageDeployment>> +| +| + +| risk +| +| +| <<StorageRisk_CommonObjectReference,StorageRisk>> +| +| + +|=== + +[id="V1GetDiffFlowsGroupedFlow_CommonObjectReference"] +=== V1GetDiffFlowsGroupedFlow + +[id="Fields-V1GetDiffFlowsGroupedFlow_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entity +| +| +| <<StorageNetworkEntityInfo_CommonObjectReference,StorageNetworkEntityInfo>> +| +| + +| properties +| +| +| List of <<StorageNetworkBaselineConnectionProperties_CommonObjectReference,StorageNetworkBaselineConnectionProperties>> +| +| + +|=== + +[id="V1GetDiffFlowsReconciledFlow_CommonObjectReference"] +=== V1GetDiffFlowsReconciledFlow + +[id="Fields-V1GetDiffFlowsReconciledFlow_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entity +| +| +| <<StorageNetworkEntityInfo_CommonObjectReference,StorageNetworkEntityInfo>> +| +| + +| added +| +| +| List of <<StorageNetworkBaselineConnectionProperties_CommonObjectReference,StorageNetworkBaselineConnectionProperties>> +| +| + +| removed +| +| +| List of <<StorageNetworkBaselineConnectionProperties_CommonObjectReference,StorageNetworkBaselineConnectionProperties>> +| +| + +| unchanged +| +| +| List of <<StorageNetworkBaselineConnectionProperties_CommonObjectReference,StorageNetworkBaselineConnectionProperties>> +| +| + +|=== + +[id="V1GetDiffFlowsResponse_CommonObjectReference"] +=== V1GetDiffFlowsResponse + +[id="Fields-V1GetDiffFlowsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| added +| +| +| List of <<V1GetDiffFlowsGroupedFlow_CommonObjectReference,V1GetDiffFlowsGroupedFlow>> +| +| + +| removed +| +| +| List of <<V1GetDiffFlowsGroupedFlow_CommonObjectReference,V1GetDiffFlowsGroupedFlow>> +| +| + +| reconciled +| +| +| List of <<V1GetDiffFlowsReconciledFlow_CommonObjectReference,V1GetDiffFlowsReconciledFlow>> +| +| + +|=== + +[id="V1GetDiscoveredClusterResponse_CommonObjectReference"] +=== V1GetDiscoveredClusterResponse + +[id="Fields-V1GetDiscoveredClusterResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cluster +| +| +| <<V1DiscoveredCluster_CommonObjectReference,V1DiscoveredCluster>> +| +| + +|=== + +[id="V1GetExistingProbesResponse_CommonObjectReference"] +=== V1GetExistingProbesResponse + +[id="Fields-V1GetExistingProbesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| existingFiles +| +| +| List of <<V1ProbeUploadManifestFile_CommonObjectReference,V1ProbeUploadManifestFile>> +| +| + +|=== + +[id="V1GetExternalBackupsResponse_CommonObjectReference"] +=== V1GetExternalBackupsResponse + +[id="Fields-V1GetExternalBackupsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| externalBackups +| +| +| List of <<StorageExternalBackup_CommonObjectReference,StorageExternalBackup>> +| +| + +|=== + +[id="V1GetExternalNetworkEntitiesResponse_CommonObjectReference"] +=== V1GetExternalNetworkEntitiesResponse + +[id="Fields-V1GetExternalNetworkEntitiesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entities +| +| +| List of <<StorageNetworkEntity_CommonObjectReference,StorageNetworkEntity>> +| +| + +|=== + +[id="V1GetExternalNetworkFlowsMetadataResponse_CommonObjectReference"] +=== V1GetExternalNetworkFlowsMetadataResponse + +[id="Fields-V1GetExternalNetworkFlowsMetadataResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entities +| +| +| List of <<V1ExternalNetworkFlowMetadata_CommonObjectReference,V1ExternalNetworkFlowMetadata>> +| +| + +| totalEntities +| +| +| Integer +| +| int32 + +|=== + +[id="V1GetExternalNetworkFlowsResponse_CommonObjectReference"] +=== V1GetExternalNetworkFlowsResponse + +[id="Fields-V1GetExternalNetworkFlowsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entity +| +| +| <<StorageNetworkEntityInfo_CommonObjectReference,StorageNetworkEntityInfo>> +| +| + +| totalFlows +| +| +| Integer +| +| int32 + +| flows +| +| +| List of <<StorageNetworkFlow_CommonObjectReference,StorageNetworkFlow>> +| +| + +|=== + +[id="V1GetFeatureFlagsResponse_CommonObjectReference"] +=== V1GetFeatureFlagsResponse + +[id="Fields-V1GetFeatureFlagsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| featureFlags +| +| +| List of <<V1FeatureFlag_CommonObjectReference,V1FeatureFlag>> +| +| + +|=== + +[id="V1GetGroupedProcessesResponse_CommonObjectReference"] +=== V1GetGroupedProcessesResponse + +[id="Fields-V1GetGroupedProcessesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| groups +| +| +| List of <<V1ProcessNameGroup_CommonObjectReference,V1ProcessNameGroup>> +| +| + +|=== + +[id="V1GetGroupedProcessesWithContainerResponse_CommonObjectReference"] +=== V1GetGroupedProcessesWithContainerResponse + +[id="Fields-V1GetGroupedProcessesWithContainerResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| groups +| +| +| List of <<V1ProcessNameAndContainerNameGroup_CommonObjectReference,V1ProcessNameAndContainerNameGroup>> +| +| + +|=== + +[id="V1GetGroupsResponse_CommonObjectReference"] +=== V1GetGroupsResponse + +API for updating Groups and getting users. Next Available Tag: 2 + +[id="Fields-V1GetGroupsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| groups +| +| +| List of <<StorageGroup_CommonObjectReference,StorageGroup>> +| +| + +|=== + +[id="V1GetImageIntegrationsResponse_CommonObjectReference"] +=== V1GetImageIntegrationsResponse + +[id="Fields-V1GetImageIntegrationsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| integrations +| +| +| List of <<StorageImageIntegration_CommonObjectReference,StorageImageIntegration>> +| +| + +|=== + +[id="V1GetIntegrationHealthResponse_CommonObjectReference"] +=== V1GetIntegrationHealthResponse + +[id="Fields-V1GetIntegrationHealthResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| integrationHealth +| +| +| List of <<StorageIntegrationHealth_CommonObjectReference,StorageIntegrationHealth>> +| +| + +|=== + +[id="V1GetLoginAuthProvidersResponse_CommonObjectReference"] +=== V1GetLoginAuthProvidersResponse + +[id="Fields-V1GetLoginAuthProvidersResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| authProviders +| +| +| List of <<GetLoginAuthProvidersResponseLoginAuthProvider_CommonObjectReference,GetLoginAuthProvidersResponseLoginAuthProvider>> +| +| + +|=== + +[id="V1GetMitreVectorResponse_CommonObjectReference"] +=== V1GetMitreVectorResponse + +[id="Fields-V1GetMitreVectorResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| mitreAttackVector +| +| +| <<StorageMitreAttackVector_CommonObjectReference,StorageMitreAttackVector>> +| +| + +|=== + +[id="V1GetNamespacesForClusterAndPermissionsResponse_CommonObjectReference"] +=== V1GetNamespacesForClusterAndPermissionsResponse + +[id="Fields-V1GetNamespacesForClusterAndPermissionsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| namespaces +| +| +| List of <<V1ScopeObject_CommonObjectReference,V1ScopeObject>> +| +| + +|=== + +[id="V1GetNamespacesResponse_CommonObjectReference"] +=== V1GetNamespacesResponse + +[id="Fields-V1GetNamespacesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| namespaces +| +| +| List of <<V1Namespace_CommonObjectReference,V1Namespace>> +| +| + +|=== + +[id="V1GetNotifiersResponse_CommonObjectReference"] +=== V1GetNotifiersResponse + +[id="Fields-V1GetNotifiersResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| notifiers +| +| +| List of <<StorageNotifier_CommonObjectReference,StorageNotifier>> +| +| + +|=== + +[id="V1GetPermissionsResponse_CommonObjectReference"] +=== V1GetPermissionsResponse + +GetPermissionsResponse is wire-compatible with the old format of the Role +message and represents a collection of aggregated permissions. + +[id="Fields-V1GetPermissionsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| resourceToAccess +| +| +| Map of <<StorageAccess_CommonObjectReference,StorageAccess>> +| +| + +|=== + +[id="V1GetPolicyCategoriesResponse_CommonObjectReference"] +=== V1GetPolicyCategoriesResponse + +[id="Fields-V1GetPolicyCategoriesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| categories +| +| +| List of <<V1PolicyCategory_CommonObjectReference,V1PolicyCategory>> +| +| + +|=== + +[id="V1GetPolicyMitreVectorsRequestOptions_CommonObjectReference"] +=== V1GetPolicyMitreVectorsRequestOptions + +[id="Fields-V1GetPolicyMitreVectorsRequestOptions_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| excludePolicy +| +| +| Boolean +| If set to true, policy is excluded from the response. +| + +|=== + +[id="V1GetPolicyMitreVectorsResponse_CommonObjectReference"] +=== V1GetPolicyMitreVectorsResponse + +[id="Fields-V1GetPolicyMitreVectorsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| policy +| +| +| <<StoragePolicy_CommonObjectReference,StoragePolicy>> +| +| + +| vectors +| +| +| List of <<StorageMitreAttackVector_CommonObjectReference,StorageMitreAttackVector>> +| +| + +|=== + +[id="V1GetProcessesListeningOnPortsResponse_CommonObjectReference"] +=== V1GetProcessesListeningOnPortsResponse + +[id="Fields-V1GetProcessesListeningOnPortsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| listeningEndpoints +| +| +| List of <<StorageProcessListeningOnPort_CommonObjectReference,StorageProcessListeningOnPort>> +| +| + +| totalListeningEndpoints +| +| +| Integer +| +| int32 + +|=== + +[id="V1GetProcessesResponse_CommonObjectReference"] +=== V1GetProcessesResponse + +[id="Fields-V1GetProcessesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| processes +| +| +| List of <<StorageProcessIndicator_CommonObjectReference,StorageProcessIndicator>> +| +| + +|=== + +[id="V1GetRecentComplianceRunsResponse_CommonObjectReference"] +=== V1GetRecentComplianceRunsResponse + +[id="Fields-V1GetRecentComplianceRunsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| complianceRuns +| +| +| List of <<V1ComplianceRun_CommonObjectReference,V1ComplianceRun>> +| +| + +|=== + +[id="V1GetReportConfigurationResponse_CommonObjectReference"] +=== V1GetReportConfigurationResponse + +[id="Fields-V1GetReportConfigurationResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfig +| +| +| <<StorageReportConfiguration_CommonObjectReference,StorageReportConfiguration>> +| +| + +|=== + +[id="V1GetReportConfigurationsResponse_CommonObjectReference"] +=== V1GetReportConfigurationsResponse + +[id="Fields-V1GetReportConfigurationsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfigs +| +| +| List of <<StorageReportConfiguration_CommonObjectReference,StorageReportConfiguration>> +| +| + +|=== + +[id="V1GetResourcesResponse_CommonObjectReference"] +=== V1GetResourcesResponse + +[id="Fields-V1GetResourcesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| resources +| +| +| List of `string` +| +| + +|=== + +[id="V1GetRoleBindingResponse_CommonObjectReference"] +=== V1GetRoleBindingResponse + +[id="Fields-V1GetRoleBindingResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| binding +| +| +| <<StorageK8sRoleBinding_CommonObjectReference,StorageK8sRoleBinding>> +| +| + +|=== + +[id="V1GetRoleResponse_CommonObjectReference"] +=== V1GetRoleResponse + +[id="Fields-V1GetRoleResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| role +| +| +| <<StorageK8sRole_CommonObjectReference,StorageK8sRole>> +| +| + +|=== + +[id="V1GetRolesResponse_CommonObjectReference"] +=== V1GetRolesResponse + +[id="Fields-V1GetRolesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| roles +| +| +| List of <<StorageRole_CommonObjectReference,StorageRole>> +| +| + +|=== + +[id="V1GetSensorUpgradeConfigResponse_CommonObjectReference"] +=== V1GetSensorUpgradeConfigResponse + +[id="Fields-V1GetSensorUpgradeConfigResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<GetSensorUpgradeConfigResponseUpgradeConfig_CommonObjectReference,GetSensorUpgradeConfigResponseUpgradeConfig>> +| +| + +|=== + +[id="V1GetServiceAccountResponse_CommonObjectReference"] +=== V1GetServiceAccountResponse + +One service account Next Tag: 2 + +[id="Fields-V1GetServiceAccountResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| saAndRole +| +| +| <<V1ServiceAccountAndRoles_CommonObjectReference,V1ServiceAccountAndRoles>> +| +| + +|=== + +[id="V1GetSubjectResponse_CommonObjectReference"] +=== V1GetSubjectResponse + +[id="Fields-V1GetSubjectResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| subject +| +| +| <<StorageSubject_CommonObjectReference,StorageSubject>> +| +| + +| clusterRoles +| +| +| List of <<StorageK8sRole_CommonObjectReference,StorageK8sRole>> +| +| + +| scopedRoles +| +| +| List of <<V1ScopedRoles_CommonObjectReference,V1ScopedRoles>> +| +| + +|=== + +[id="V1GetUndoModificationForDeploymentResponse_CommonObjectReference"] +=== V1GetUndoModificationForDeploymentResponse + +[id="Fields-V1GetUndoModificationForDeploymentResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| undoRecord +| +| +| <<StorageNetworkPolicyApplicationUndoRecord_CommonObjectReference,StorageNetworkPolicyApplicationUndoRecord>> +| +| + +|=== + +[id="V1GetUndoModificationResponse_CommonObjectReference"] +=== V1GetUndoModificationResponse + +[id="Fields-V1GetUndoModificationResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| undoRecord +| +| +| <<StorageNetworkPolicyApplicationUndoRecord_CommonObjectReference,StorageNetworkPolicyApplicationUndoRecord>> +| +| + +|=== + +[id="V1GetUpgradeStatusResponse_CommonObjectReference"] +=== V1GetUpgradeStatusResponse + +[id="Fields-V1GetUpgradeStatusResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| upgradeStatus +| +| +| <<V1CentralUpgradeStatus_CommonObjectReference,V1CentralUpgradeStatus>> +| +| + +|=== + +[id="V1GetUsersAttributesResponse_CommonObjectReference"] +=== V1GetUsersAttributesResponse + +Next Tag: 2 + +[id="Fields-V1GetUsersAttributesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| usersAttributes +| +| +| List of <<V1UserAttributeTuple_CommonObjectReference,V1UserAttributeTuple>> +| +| + +|=== + +[id="V1GetUsersResponse_CommonObjectReference"] +=== V1GetUsersResponse + +Next Tag: 2 + +[id="Fields-V1GetUsersResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| users +| +| +| List of <<StorageUser_CommonObjectReference,StorageUser>> +| +| + +|=== + +[id="V1GetVulnerabilityExceptionConfigResponse_CommonObjectReference"] +=== V1GetVulnerabilityExceptionConfigResponse + +[id="Fields-V1GetVulnerabilityExceptionConfigResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<V1VulnerabilityExceptionConfig_CommonObjectReference,V1VulnerabilityExceptionConfig>> +| +| + +|=== + +[id="V1GetVulnerabilityRequestResponse_CommonObjectReference"] +=== V1GetVulnerabilityRequestResponse + +[id="Fields-V1GetVulnerabilityRequestResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requestInfo +| +| +| <<StorageVulnerabilityRequest_CommonObjectReference,StorageVulnerabilityRequest>> +| +| + +|=== + +[id="V1GetWatchedImagesResponse_CommonObjectReference"] +=== V1GetWatchedImagesResponse + +[id="Fields-V1GetWatchedImagesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| watchedImages +| +| +| List of <<StorageWatchedImage_CommonObjectReference,StorageWatchedImage>> +| +| + +|=== + +[id="V1GroupBatchUpdateRequest_CommonObjectReference"] +=== V1GroupBatchUpdateRequest + +GroupBatchUpdateRequest is an in transaction batch update to the groups present. Next Available Tag: 3 + +[id="Fields-V1GroupBatchUpdateRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| previousGroups +| +| +| List of <<StorageGroup_CommonObjectReference,StorageGroup>> +| Previous groups are the groups expected to be present in the store. Performs a diff on the GroupProperties present in previous_groups and required_groups: 1) if in previous_groups but not required_groups, it gets deleted. 2) if in previous_groups and required_groups, it gets updated. 3) if not in previous_groups but in required_groups, it gets added. +| + +| requiredGroups +| +| +| List of <<StorageGroup_CommonObjectReference,StorageGroup>> +| Required groups are the groups we want to mutate the previous groups into. +| + +| force +| +| +| Boolean +| +| + +|=== + +[id="V1ImportPoliciesMetadata_CommonObjectReference"] +=== V1ImportPoliciesMetadata + +[id="Fields-V1ImportPoliciesMetadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| overwrite +| +| +| Boolean +| +| + +|=== + +[id="V1ImportPoliciesRequest_CommonObjectReference"] +=== V1ImportPoliciesRequest + +[id="Fields-V1ImportPoliciesRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| metadata +| +| +| <<V1ImportPoliciesMetadata_CommonObjectReference,V1ImportPoliciesMetadata>> +| +| + +| policies +| +| +| List of <<StoragePolicy_CommonObjectReference,StoragePolicy>> +| +| + +|=== + +[id="V1ImportPoliciesResponse_CommonObjectReference"] +=== V1ImportPoliciesResponse + +[id="Fields-V1ImportPoliciesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| responses +| +| +| List of <<V1ImportPolicyResponse_CommonObjectReference,V1ImportPolicyResponse>> +| +| + +| allSucceeded +| +| +| Boolean +| +| + +|=== + +[id="V1ImportPolicyError_CommonObjectReference"] +=== V1ImportPolicyError + +[id="Fields-V1ImportPolicyError_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| message +| +| +| String +| +| + +| type +| +| +| String +| +| + +| duplicateName +| +| +| String +| +| + +| validationError +| +| +| String +| +| + +|=== + +[id="V1ImportPolicyResponse_CommonObjectReference"] +=== V1ImportPolicyResponse + +[id="Fields-V1ImportPolicyResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| succeeded +| +| +| Boolean +| +| + +| policy +| +| +| <<StoragePolicy_CommonObjectReference,StoragePolicy>> +| +| + +| errors +| +| +| List of <<V1ImportPolicyError_CommonObjectReference,V1ImportPolicyError>> +| +| + +|=== + +[id="V1InitBundleGenRequest_CommonObjectReference"] +=== V1InitBundleGenRequest + +[id="Fields-V1InitBundleGenRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +|=== + +[id="V1InitBundleGenResponse_CommonObjectReference"] +=== V1InitBundleGenResponse + +[id="Fields-V1InitBundleGenResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| meta +| +| +| <<V1InitBundleMeta_CommonObjectReference,V1InitBundleMeta>> +| +| + +| helmValuesBundle +| +| +| byte[] +| +| byte + +| kubectlBundle +| +| +| byte[] +| +| byte + +|=== + +[id="V1InitBundleMeta_CommonObjectReference"] +=== V1InitBundleMeta + +[id="Fields-V1InitBundleMeta_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| impactedClusters +| +| +| List of <<InitBundleMetaImpactedCluster_CommonObjectReference,InitBundleMetaImpactedCluster>> +| +| + +| createdAt +| +| +| Date +| +| date-time + +| createdBy +| +| +| <<StorageUser_CommonObjectReference,StorageUser>> +| +| + +| expiresAt +| +| +| Date +| +| date-time + +|=== + +[id="V1InitBundleMetasResponse_CommonObjectReference"] +=== V1InitBundleMetasResponse + +[id="Fields-V1InitBundleMetasResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| items +| +| +| List of <<V1InitBundleMeta_CommonObjectReference,V1InitBundleMeta>> +| +| + +|=== + +[id="V1InitBundleRevokeRequest_CommonObjectReference"] +=== V1InitBundleRevokeRequest + +[id="Fields-V1InitBundleRevokeRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| ids +| +| +| List of `string` +| +| + +| confirmImpactedClustersIds +| +| +| List of `string` +| +| + +|=== + +[id="V1InitBundleRevokeResponse_CommonObjectReference"] +=== V1InitBundleRevokeResponse + +[id="Fields-V1InitBundleRevokeResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| initBundleRevocationErrors +| +| +| List of <<InitBundleRevokeResponseInitBundleRevocationError_CommonObjectReference,InitBundleRevokeResponseInitBundleRevocationError>> +| +| + +| initBundleRevokedIds +| +| +| List of `string` +| +| + +|=== + +[id="V1InterruptDBRestoreProcessResponse_CommonObjectReference"] +=== V1InterruptDBRestoreProcessResponse + +[id="Fields-V1InterruptDBRestoreProcessResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| resumeInfo +| +| +| <<DBRestoreProcessStatusResumeInfo_CommonObjectReference,DBRestoreProcessStatusResumeInfo>> +| +| + +|=== + +[id="V1JobId_CommonObjectReference"] +=== V1JobId + +[id="Fields-V1JobId_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| jobId +| +| +| String +| +| + +|=== + +[id="V1KernelSupportAvailableResponse_CommonObjectReference"] +=== V1KernelSupportAvailableResponse + +[id="Fields-V1KernelSupportAvailableResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| kernelSupportAvailable +| +| +| Boolean +| +| + +|=== + +[id="V1ListAdministrationEventsResponse_CommonObjectReference"] +=== V1ListAdministrationEventsResponse + +[id="Fields-V1ListAdministrationEventsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| events +| +| +| List of <<V1AdministrationEvent_CommonObjectReference,V1AdministrationEvent>> +| +| + +|=== + +[id="V1ListAlertsRequest_CommonObjectReference"] +=== V1ListAlertsRequest + +[id="Fields-V1ListAlertsRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| query +| +| +| String +| +| + +| pagination +| +| +| <<V1Pagination_CommonObjectReference,V1Pagination>> +| +| + +|=== + +[id="V1ListAlertsResponse_CommonObjectReference"] +=== V1ListAlertsResponse + +[id="Fields-V1ListAlertsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| alerts +| +| +| List of <<StorageListAlert_CommonObjectReference,StorageListAlert>> +| +| + +|=== + +[id="V1ListAllowedTokenRolesResponse_CommonObjectReference"] +=== V1ListAllowedTokenRolesResponse + +[id="Fields-V1ListAllowedTokenRolesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| roleNames +| +| +| List of `string` +| +| + +|=== + +[id="V1ListAuthMachineToMachineConfigResponse_CommonObjectReference"] +=== V1ListAuthMachineToMachineConfigResponse + +[id="Fields-V1ListAuthMachineToMachineConfigResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| configs +| +| +| List of <<V1AuthMachineToMachineConfig_CommonObjectReference,V1AuthMachineToMachineConfig>> +| +| + +|=== + +[id="V1ListCloudSourcesResponse_CommonObjectReference"] +=== V1ListCloudSourcesResponse + +[id="Fields-V1ListCloudSourcesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cloudSources +| +| +| List of <<V1CloudSource_CommonObjectReference,V1CloudSource>> +| +| + +|=== + +[id="V1ListCollectionSelectorsResponse_CommonObjectReference"] +=== V1ListCollectionSelectorsResponse + +[id="Fields-V1ListCollectionSelectorsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| selectors +| +| +| List of `string` +| +| + +|=== + +[id="V1ListCollectionsResponse_CommonObjectReference"] +=== V1ListCollectionsResponse + +[id="Fields-V1ListCollectionsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| collections +| +| +| List of <<StorageResourceCollection_CommonObjectReference,StorageResourceCollection>> +| +| + +|=== + +[id="V1ListDeploymentsResponse_CommonObjectReference"] +=== V1ListDeploymentsResponse + +[id="Fields-V1ListDeploymentsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployments +| +| +| List of <<StorageListDeployment_CommonObjectReference,StorageListDeployment>> +| +| + +|=== + +[id="V1ListDeploymentsWithProcessInfoResponse_CommonObjectReference"] +=== V1ListDeploymentsWithProcessInfoResponse + +[id="Fields-V1ListDeploymentsWithProcessInfoResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployments +| +| +| List of <<ListDeploymentsWithProcessInfoResponseDeploymentWithProcessInfo_CommonObjectReference,ListDeploymentsWithProcessInfoResponseDeploymentWithProcessInfo>> +| +| + +|=== + +[id="V1ListDiscoveredClustersResponse_CommonObjectReference"] +=== V1ListDiscoveredClustersResponse + +[id="Fields-V1ListDiscoveredClustersResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusters +| +| +| List of <<V1DiscoveredCluster_CommonObjectReference,V1DiscoveredCluster>> +| +| + +|=== + +[id="V1ListImagesResponse_CommonObjectReference"] +=== V1ListImagesResponse + +[id="Fields-V1ListImagesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| images +| +| +| List of <<StorageListImage_CommonObjectReference,StorageListImage>> +| +| + +|=== + +[id="V1ListMitreAttackVectorsResponse_CommonObjectReference"] +=== V1ListMitreAttackVectorsResponse + +[id="Fields-V1ListMitreAttackVectorsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| mitreAttackVectors +| +| +| List of <<StorageMitreAttackVector_CommonObjectReference,StorageMitreAttackVector>> +| +| + +|=== + +[id="V1ListNodesResponse_CommonObjectReference"] +=== V1ListNodesResponse + +[id="Fields-V1ListNodesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| nodes +| +| +| List of <<StorageNode_CommonObjectReference,StorageNode>> +| +| + +|=== + +[id="V1ListPermissionSetsResponse_CommonObjectReference"] +=== V1ListPermissionSetsResponse + +[id="Fields-V1ListPermissionSetsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| permissionSets +| +| +| List of <<StoragePermissionSet_CommonObjectReference,StoragePermissionSet>> +| +| + +|=== + +[id="V1ListPoliciesResponse_CommonObjectReference"] +=== V1ListPoliciesResponse + +[id="Fields-V1ListPoliciesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| policies +| +| +| List of <<StorageListPolicy_CommonObjectReference,StorageListPolicy>> +| +| + +|=== + +[id="V1ListRoleBindingsResponse_CommonObjectReference"] +=== V1ListRoleBindingsResponse + +A list of k8s role bindings (free of scoped information) Next Tag: 2 + +[id="Fields-V1ListRoleBindingsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| bindings +| +| +| List of <<StorageK8sRoleBinding_CommonObjectReference,StorageK8sRoleBinding>> +| +| + +|=== + +[id="V1ListRolesResponse_CommonObjectReference"] +=== V1ListRolesResponse + +A list of k8s roles (free of scoped information) Next Tag: 2 + +[id="Fields-V1ListRolesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| roles +| +| +| List of <<StorageK8sRole_CommonObjectReference,StorageK8sRole>> +| +| + +|=== + +[id="V1ListSecretsResponse_CommonObjectReference"] +=== V1ListSecretsResponse + +A list of secrets with their relationships. Next Tag: 2 + +[id="Fields-V1ListSecretsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| secrets +| +| +| List of <<StorageListSecret_CommonObjectReference,StorageListSecret>> +| +| + +|=== + +[id="V1ListServiceAccountResponse_CommonObjectReference"] +=== V1ListServiceAccountResponse + +A list of service accounts (free of scoped information) Next Tag: 2 + +[id="Fields-V1ListServiceAccountResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| saAndRoles +| +| +| List of <<V1ServiceAccountAndRoles_CommonObjectReference,V1ServiceAccountAndRoles>> +| +| + +|=== + +[id="V1ListSignatureIntegrationsResponse_CommonObjectReference"] +=== V1ListSignatureIntegrationsResponse + +[id="Fields-V1ListSignatureIntegrationsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| integrations +| +| +| List of <<StorageSignatureIntegration_CommonObjectReference,StorageSignatureIntegration>> +| +| + +|=== + +[id="V1ListSimpleAccessScopesResponse_CommonObjectReference"] +=== V1ListSimpleAccessScopesResponse + +[id="Fields-V1ListSimpleAccessScopesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| accessScopes +| +| +| List of <<StorageSimpleAccessScope_CommonObjectReference,StorageSimpleAccessScope>> +| +| + +|=== + +[id="V1ListSubjectsResponse_CommonObjectReference"] +=== V1ListSubjectsResponse + +A list of k8s subjects (users and groups only, for service accounts, try the service account service) Next Tag: 2 + +[id="Fields-V1ListSubjectsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| subjectAndRoles +| +| +| List of <<V1SubjectAndRoles_CommonObjectReference,V1SubjectAndRoles>> +| +| + +|=== + +[id="V1ListVulnerabilityRequestsResponse_CommonObjectReference"] +=== V1ListVulnerabilityRequestsResponse + +[id="Fields-V1ListVulnerabilityRequestsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requestInfos +| +| +| List of <<StorageVulnerabilityRequest_CommonObjectReference,StorageVulnerabilityRequest>> +| +| + +|=== + +[id="V1LockProcessBaselinesRequest_CommonObjectReference"] +=== V1LockProcessBaselinesRequest + +[id="Fields-V1LockProcessBaselinesRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| keys +| +| +| List of <<StorageProcessBaselineKey_CommonObjectReference,StorageProcessBaselineKey>> +| +| + +| locked +| +| +| Boolean +| +| + +|=== + +[id="V1LogLevelRequest_CommonObjectReference"] +=== V1LogLevelRequest + +[id="Fields-V1LogLevelRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| level +| +| +| String +| +| + +| modules +| +| +| List of `string` +| +| + +|=== + +[id="V1LogLevelResponse_CommonObjectReference"] +=== V1LogLevelResponse + +[id="Fields-V1LogLevelResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| level +| +| +| String +| +| + +| moduleLevels +| +| +| List of <<V1ModuleLevel_CommonObjectReference,V1ModuleLevel>> +| +| + +|=== + +[id="V1MaxSecuredUnitsUsageResponse_CommonObjectReference"] +=== V1MaxSecuredUnitsUsageResponse + +MaxSecuredUnitsUsageResponse holds the maximum values of the secured nodes +and CPU Units (as reported by Kubernetes) with the time at which these +values were aggregated, with the aggregation period accuracy (1h). + +[id="Fields-V1MaxSecuredUnitsUsageResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| maxNodesAt +| +| +| Date +| +| date-time + +| maxNodes +| +| +| String +| +| int64 + +| maxCpuUnitsAt +| +| +| Date +| +| date-time + +| maxCpuUnits +| +| +| String +| +| int64 + +|=== + +[id="V1Metadata_CommonObjectReference"] +=== V1Metadata + +[id="Fields-V1Metadata_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| version +| +| +| String +| +| + +| buildFlavor +| +| +| String +| +| + +| releaseBuild +| +| +| Boolean +| +| + +| licenseStatus +| +| +| <<MetadataLicenseStatus_CommonObjectReference,MetadataLicenseStatus>> +| +| NONE, INVALID, EXPIRED, RESTARTING, VALID, + +|=== + +[id="V1ModuleLevel_CommonObjectReference"] +=== V1ModuleLevel + +[id="Fields-V1ModuleLevel_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| module +| +| +| String +| +| + +| level +| +| +| String +| +| + +|=== + +[id="V1Namespace_CommonObjectReference"] +=== V1Namespace + +[id="Fields-V1Namespace_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| metadata +| +| +| <<StorageNamespaceMetadata_CommonObjectReference,StorageNamespaceMetadata>> +| +| + +| numDeployments +| +| +| Integer +| +| int32 + +| numSecrets +| +| +| Integer +| +| int32 + +| numNetworkPolicies +| +| +| Integer +| +| int32 + +|=== + +[id="V1NetworkBaselineExternalStatusResponse_CommonObjectReference"] +=== V1NetworkBaselineExternalStatusResponse + +[id="Fields-V1NetworkBaselineExternalStatusResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| anomalous +| +| +| List of <<V1NetworkBaselinePeerStatus_CommonObjectReference,V1NetworkBaselinePeerStatus>> +| +| + +| totalAnomalous +| +| +| Integer +| +| int32 + +| baseline +| +| +| List of <<V1NetworkBaselinePeerStatus_CommonObjectReference,V1NetworkBaselinePeerStatus>> +| +| + +| totalBaseline +| +| +| Integer +| +| int32 + +|=== + +[id="V1NetworkBaselinePeerEntity_CommonObjectReference"] +=== V1NetworkBaselinePeerEntity + +[id="Fields-V1NetworkBaselinePeerEntity_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| type +| +| +| <<StorageNetworkEntityInfoType_CommonObjectReference,StorageNetworkEntityInfoType>> +| +| UNKNOWN_TYPE, DEPLOYMENT, INTERNET, LISTEN_ENDPOINT, EXTERNAL_SOURCE, INTERNAL_ENTITIES, + +| name +| +| +| String +| +| + +| discovered +| +| +| Boolean +| +| + +|=== + +[id="V1NetworkBaselinePeerStatus_CommonObjectReference"] +=== V1NetworkBaselinePeerStatus + +[id="Fields-V1NetworkBaselinePeerStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| peer +| +| +| <<V1NetworkBaselineStatusPeer_CommonObjectReference,V1NetworkBaselineStatusPeer>> +| +| + +| status +| +| +| <<V1NetworkBaselinePeerStatusStatus_CommonObjectReference,V1NetworkBaselinePeerStatusStatus>> +| +| BASELINE, ANOMALOUS, + +|=== + +[id="V1NetworkBaselinePeerStatusStatus_CommonObjectReference"] +=== V1NetworkBaselinePeerStatusStatus + +Status of this peer connection. As of now we only have two statuses: - BASELINE: the connection is in the current deployment baseline - ANOMALOUS: the connection is not recognized by the current deployment baseline + +[id="Fields-V1NetworkBaselinePeerStatusStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| BASELINE +| ANOMALOUS + +|=== + +[id="V1NetworkBaselineStatusPeer_CommonObjectReference"] +=== V1NetworkBaselineStatusPeer + +[id="Fields-V1NetworkBaselineStatusPeer_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entity +| +| +| <<V1NetworkBaselinePeerEntity_CommonObjectReference,V1NetworkBaselinePeerEntity>> +| +| + +| port +| +| +| Long +| The port and protocol of the destination of the given connection. +| int64 + +| protocol +| +| +| <<StorageL4Protocol_CommonObjectReference,StorageL4Protocol>> +| +| L4_PROTOCOL_UNKNOWN, L4_PROTOCOL_TCP, L4_PROTOCOL_UDP, L4_PROTOCOL_ICMP, L4_PROTOCOL_RAW, L4_PROTOCOL_SCTP, L4_PROTOCOL_ANY, + +| ingress +| +| +| Boolean +| A boolean representing whether the query is for an ingress or egress connection. This is defined with respect to the current deployment. Thus: - If the connection in question is in the outEdges of the current deployment, this should be false. - If it is in the outEdges of the peer deployment, this should be true. +| + +|=== + +[id="V1NetworkBaselineStatusResponse_CommonObjectReference"] +=== V1NetworkBaselineStatusResponse + +[id="Fields-V1NetworkBaselineStatusResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| statuses +| +| +| List of <<V1NetworkBaselinePeerStatus_CommonObjectReference,V1NetworkBaselinePeerStatus>> +| +| + +|=== + +[id="V1NetworkEdgeProperties_CommonObjectReference"] +=== V1NetworkEdgeProperties + +[id="Fields-V1NetworkEdgeProperties_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| port +| +| +| Long +| +| int64 + +| protocol +| +| +| <<StorageL4Protocol_CommonObjectReference,StorageL4Protocol>> +| +| L4_PROTOCOL_UNKNOWN, L4_PROTOCOL_TCP, L4_PROTOCOL_UDP, L4_PROTOCOL_ICMP, L4_PROTOCOL_RAW, L4_PROTOCOL_SCTP, L4_PROTOCOL_ANY, + +| lastActiveTimestamp +| +| +| Date +| +| date-time + +|=== + +[id="V1NetworkEdgePropertiesBundle_CommonObjectReference"] +=== V1NetworkEdgePropertiesBundle + +[id="Fields-V1NetworkEdgePropertiesBundle_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| properties +| +| +| List of <<V1NetworkEdgeProperties_CommonObjectReference,V1NetworkEdgeProperties>> +| +| + +|=== + +[id="V1NetworkGraph_CommonObjectReference"] +=== V1NetworkGraph + +[id="Fields-V1NetworkGraph_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| epoch +| +| +| Long +| +| int64 + +| nodes +| +| +| List of <<V1NetworkNode_CommonObjectReference,V1NetworkNode>> +| +| + +|=== + +[id="V1NetworkGraphDiff_CommonObjectReference"] +=== V1NetworkGraphDiff + +[id="Fields-V1NetworkGraphDiff_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| DEPRECATEDNodeDiffs +| +| +| Map of <<V1NetworkNodeDiff_CommonObjectReference,V1NetworkNodeDiff>> +| +| + +| nodeDiffs +| +| +| Map of <<V1NetworkNodeDiff_CommonObjectReference,V1NetworkNodeDiff>> +| +| + +|=== + +[id="V1NetworkGraphEpoch_CommonObjectReference"] +=== V1NetworkGraphEpoch + +[id="Fields-V1NetworkGraphEpoch_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| epoch +| +| +| Long +| +| int64 + +|=== + +[id="V1NetworkGraphScope_CommonObjectReference"] +=== V1NetworkGraphScope + +[id="Fields-V1NetworkGraphScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| query +| +| +| String +| +| + +|=== + +[id="V1NetworkNode_CommonObjectReference"] +=== V1NetworkNode + +[id="Fields-V1NetworkNode_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| entity +| +| +| <<StorageNetworkEntityInfo_CommonObjectReference,StorageNetworkEntityInfo>> +| +| + +| internetAccess +| +| +| Boolean +| +| + +| policyIds +| +| +| List of `string` +| +| + +| nonIsolatedIngress +| +| +| Boolean +| +| + +| nonIsolatedEgress +| +| +| Boolean +| +| + +| queryMatch +| +| +| Boolean +| +| + +| outEdges +| +| +| Map of <<V1NetworkEdgePropertiesBundle_CommonObjectReference,V1NetworkEdgePropertiesBundle>> +| +| + +|=== + +[id="V1NetworkNodeDiff_CommonObjectReference"] +=== V1NetworkNodeDiff + +[id="Fields-V1NetworkNodeDiff_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| policyIds +| +| +| List of `string` +| +| + +| DEPRECATEDOutEdges +| +| +| Map of <<V1NetworkEdgePropertiesBundle_CommonObjectReference,V1NetworkEdgePropertiesBundle>> +| +| + +| outEdges +| +| +| Map of <<V1NetworkEdgePropertiesBundle_CommonObjectReference,V1NetworkEdgePropertiesBundle>> +| +| + +| nonIsolatedIngress +| +| +| Boolean +| +| + +| nonIsolatedEgress +| +| +| Boolean +| +| + +|=== + +[id="V1NetworkPoliciesResponse_CommonObjectReference"] +=== V1NetworkPoliciesResponse + +[id="Fields-V1NetworkPoliciesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| networkPolicies +| +| +| List of <<StorageNetworkPolicy_CommonObjectReference,StorageNetworkPolicy>> +| +| + +|=== + +[id="V1NetworkPolicyInSimulation_CommonObjectReference"] +=== V1NetworkPolicyInSimulation + +[id="Fields-V1NetworkPolicyInSimulation_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| policy +| +| +| <<StorageNetworkPolicy_CommonObjectReference,StorageNetworkPolicy>> +| +| + +| status +| +| +| <<V1NetworkPolicyInSimulationStatus_CommonObjectReference,V1NetworkPolicyInSimulationStatus>> +| +| INVALID, UNCHANGED, MODIFIED, ADDED, DELETED, + +| oldPolicy +| +| +| <<StorageNetworkPolicy_CommonObjectReference,StorageNetworkPolicy>> +| +| + +|=== + +[id="V1NetworkPolicyInSimulationStatus_CommonObjectReference"] +=== V1NetworkPolicyInSimulationStatus + +[id="Fields-V1NetworkPolicyInSimulationStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| INVALID +| UNCHANGED +| MODIFIED +| ADDED +| DELETED + +|=== + +[id="V1OCMConfig_CommonObjectReference"] +=== V1OCMConfig + +OCMConfig provides information required to fetch discovered clusters from +the OpenShift cluster manager. + +[id="Fields-V1OCMConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +|=== + +[id="V1Pagination_CommonObjectReference"] +=== V1Pagination + +[id="Fields-V1Pagination_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| limit +| +| +| Integer +| +| int32 + +| offset +| +| +| Integer +| +| int32 + +| sortOption +| +| +| <<V1SortOption_CommonObjectReference,V1SortOption>> +| +| + +| sortOptions +| +| +| List of <<V1SortOption_CommonObjectReference,V1SortOption>> +| This field is under development. It is not supported on any REST APIs. +| + +|=== + +[id="V1PaladinCloudConfig_CommonObjectReference"] +=== V1PaladinCloudConfig + +PaladinCloudConfig provides information required to fetch discovered +clusters from Paladin Cloud. + +[id="Fields-V1PaladinCloudConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| endpoint +| +| +| String +| +| + +|=== + +[id="V1PodsResponse_CommonObjectReference"] +=== V1PodsResponse + +[id="Fields-V1PodsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| pods +| +| +| List of <<StoragePod_CommonObjectReference,StoragePod>> +| +| + +|=== + +[id="V1PolicyCategoriesResponse_CommonObjectReference"] +=== V1PolicyCategoriesResponse + +[id="Fields-V1PolicyCategoriesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| categories +| +| +| List of `string` +| +| + +|=== + +[id="V1PolicyCategory_CommonObjectReference"] +=== V1PolicyCategory + +[id="Fields-V1PolicyCategory_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| isDefault +| +| +| Boolean +| +| + +|=== + +[id="V1PolicyFromSearchRequest_CommonObjectReference"] +=== V1PolicyFromSearchRequest + +[id="Fields-V1PolicyFromSearchRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| searchParams +| +| +| String +| +| + +|=== + +[id="V1PolicyFromSearchResponse_CommonObjectReference"] +=== V1PolicyFromSearchResponse + +[id="Fields-V1PolicyFromSearchResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| policy +| +| +| <<StoragePolicy_CommonObjectReference,StoragePolicy>> +| +| + +| alteredSearchTerms +| +| +| List of `string` +| +| + +| hasNestedFields +| +| +| Boolean +| +| + +|=== + +[id="V1PongMessage_CommonObjectReference"] +=== V1PongMessage + +[id="Fields-V1PongMessage_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| status +| +| +| String +| +| + +|=== + +[id="V1PostReportConfigurationRequest_CommonObjectReference"] +=== V1PostReportConfigurationRequest + +[id="Fields-V1PostReportConfigurationRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfig +| +| +| <<StorageReportConfiguration_CommonObjectReference,StorageReportConfiguration>> +| +| + +|=== + +[id="V1PostReportConfigurationResponse_CommonObjectReference"] +=== V1PostReportConfigurationResponse + +[id="Fields-V1PostReportConfigurationResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfig +| +| +| <<StorageReportConfiguration_CommonObjectReference,StorageReportConfiguration>> +| +| + +|=== + +[id="V1Preferences_CommonObjectReference"] +=== V1Preferences + +[id="Fields-V1Preferences_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| maxGrpcReceiveSizeBytes +| +| +| String +| +| uint64 + +|=== + +[id="V1ProbeUploadManifestFile_CommonObjectReference"] +=== V1ProbeUploadManifestFile + +[id="Fields-V1ProbeUploadManifestFile_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| size +| +| +| String +| +| int64 + +| crc32 +| +| +| Long +| +| int64 + +|=== + +[id="V1ProcessBaselineUpdateError_CommonObjectReference"] +=== V1ProcessBaselineUpdateError + +[id="Fields-V1ProcessBaselineUpdateError_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| error +| +| +| String +| +| + +| key +| +| +| <<StorageProcessBaselineKey_CommonObjectReference,StorageProcessBaselineKey>> +| +| + +|=== + +[id="V1ProcessGroup_CommonObjectReference"] +=== V1ProcessGroup + +[id="Fields-V1ProcessGroup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| args +| +| +| String +| +| + +| signals +| +| +| List of <<StorageProcessIndicator_CommonObjectReference,StorageProcessIndicator>> +| +| + +|=== + +[id="V1ProcessNameAndContainerNameGroup_CommonObjectReference"] +=== V1ProcessNameAndContainerNameGroup + +[id="Fields-V1ProcessNameAndContainerNameGroup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| containerName +| +| +| String +| +| + +| timesExecuted +| +| +| Long +| +| int64 + +| groups +| +| +| List of <<V1ProcessGroup_CommonObjectReference,V1ProcessGroup>> +| +| + +| suspicious +| +| +| Boolean +| +| + +|=== + +[id="V1ProcessNameGroup_CommonObjectReference"] +=== V1ProcessNameGroup + +[id="Fields-V1ProcessNameGroup_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| timesExecuted +| +| +| Long +| +| int64 + +| groups +| +| +| List of <<V1ProcessGroup_CommonObjectReference,V1ProcessGroup>> +| +| + +|=== + +[id="V1PutConfigRequest_CommonObjectReference"] +=== V1PutConfigRequest + +[id="Fields-V1PutConfigRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<StorageConfig_CommonObjectReference,StorageConfig>> +| +| + +|=== + +[id="V1PutNetworkGraphConfigRequest_CommonObjectReference"] +=== V1PutNetworkGraphConfigRequest + +[id="Fields-V1PutNetworkGraphConfigRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<StorageNetworkGraphConfig_CommonObjectReference,StorageNetworkGraphConfig>> +| +| + +|=== + +[id="V1PutPlatformComponentConfigRequest_CommonObjectReference"] +=== V1PutPlatformComponentConfigRequest + +[id="Fields-V1PutPlatformComponentConfigRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| rules +| +| +| List of <<PlatformComponentConfigRule_CommonObjectReference,PlatformComponentConfigRule>> +| +| + +|=== + +[id="V1RawQuery_CommonObjectReference"] +=== V1RawQuery + +RawQuery represents the search query string. +The format of the query string is "<field name>:<value,value,...>+<field name>:<value, value,...>+..." +For example: +To search for deployments named "central" and "sensor" in the namespace "stackrox", the query string would be +"Deployment:central,sensor+Namespace:stackrox" +RawQuery is used in ListAPIs to search for a particular object. + +[id="Fields-V1RawQuery_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| query +| +| +| String +| +| + +| pagination +| +| +| <<V1Pagination_CommonObjectReference,V1Pagination>> +| +| + +|=== + +[id="V1RenamePolicyCategoryRequest_CommonObjectReference"] +=== V1RenamePolicyCategoryRequest + +[id="Fields-V1RenamePolicyCategoryRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| newCategoryName +| +| +| String +| +| + +|=== + +[id="V1ResolveAlertsRequest_CommonObjectReference"] +=== V1ResolveAlertsRequest + +[id="Fields-V1ResolveAlertsRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| query +| +| +| String +| +| + +|=== + +[id="V1SADeploymentRelationship_CommonObjectReference"] +=== V1SADeploymentRelationship + +Service accounts can be used by a deployment. Next Tag: 3 + +[id="Fields-V1SADeploymentRelationship_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| Name of the deployment. +| + +|=== + +[id="V1ScanImageInternalRequestSource_CommonObjectReference"] +=== V1ScanImageInternalRequestSource + +[id="Fields-V1ScanImageInternalRequestSource_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| imagePullSecrets +| +| +| List of `string` +| +| + +|=== + +[id="V1ScanImageInternalResponse_CommonObjectReference"] +=== V1ScanImageInternalResponse + +[id="Fields-V1ScanImageInternalResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| image +| +| +| <<StorageImage_CommonObjectReference,StorageImage>> +| +| + +|=== + +[id="V1ScanImageRequest_CommonObjectReference"] +=== V1ScanImageRequest + +[id="Fields-V1ScanImageRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| imageName +| +| +| String +| +| + +| force +| +| +| Boolean +| +| + +| includeSnoozed +| +| +| Boolean +| +| + +| cluster +| +| +| String +| Cluster to delegate scan to, may be the cluster's name or ID. +| + +| namespace +| +| +| String +| Namespace on the secured cluster from which to read context information when delegating image scans, specifically pull secrets to access the image registry. +| + +|=== + +[id="V1ScopeObject_CommonObjectReference"] +=== V1ScopeObject + +ScopeObject represents an ID, name pair, which can apply to any +entity that takes part in an access scope (so far Cluster and Namespace). + +[id="Fields-V1ScopeObject_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +|=== + +[id="V1ScopedRoles_CommonObjectReference"] +=== V1ScopedRoles + +[id="Fields-V1ScopedRoles_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| namespace +| +| +| String +| +| + +| roles +| +| +| List of <<StorageK8sRole_CommonObjectReference,StorageK8sRole>> +| +| + +|=== + +[id="V1SearchCategory_CommonObjectReference"] +=== V1SearchCategory + +Next available tag: 74 + +[id="Fields-V1SearchCategory_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| SEARCH_UNSET +| ALERTS +| IMAGES +| IMAGE_COMPONENTS +| IMAGE_VULN_EDGE +| IMAGE_COMPONENT_EDGE +| POLICIES +| DEPLOYMENTS +| ACTIVE_COMPONENT +| PODS +| SECRETS +| PROCESS_INDICATORS +| COMPLIANCE +| CLUSTERS +| NAMESPACES +| NODES +| NODE_COMPONENTS +| NODE_VULN_EDGE +| NODE_COMPONENT_EDGE +| NODE_COMPONENT_CVE_EDGE +| COMPLIANCE_STANDARD +| COMPLIANCE_CONTROL_GROUP +| COMPLIANCE_CONTROL +| SERVICE_ACCOUNTS +| ROLES +| ROLEBINDINGS +| REPORT_CONFIGURATIONS +| PROCESS_BASELINES +| SUBJECTS +| RISKS +| VULNERABILITIES +| CLUSTER_VULNERABILITIES +| IMAGE_VULNERABILITIES +| NODE_VULNERABILITIES +| COMPONENT_VULN_EDGE +| CLUSTER_VULN_EDGE +| NETWORK_ENTITY +| VULN_REQUEST +| NETWORK_BASELINE +| NETWORK_POLICIES +| PROCESS_BASELINE_RESULTS +| COMPLIANCE_METADATA +| COMPLIANCE_RESULTS +| COMPLIANCE_DOMAIN +| CLUSTER_HEALTH +| POLICY_CATEGORIES +| IMAGE_INTEGRATIONS +| COLLECTIONS +| POLICY_CATEGORY_EDGE +| PROCESS_LISTENING_ON_PORT +| API_TOKEN +| REPORT_METADATA +| REPORT_SNAPSHOT +| COMPLIANCE_INTEGRATIONS +| COMPLIANCE_SCAN_CONFIG +| COMPLIANCE_SCAN +| COMPLIANCE_CHECK_RESULTS +| BLOB +| ADMINISTRATION_EVENTS +| COMPLIANCE_SCAN_CONFIG_STATUS +| ADMINISTRATION_USAGE +| COMPLIANCE_PROFILES +| COMPLIANCE_RULES +| COMPLIANCE_SCAN_SETTING_BINDINGS +| COMPLIANCE_SUITES +| CLOUD_SOURCES +| DISCOVERED_CLUSTERS +| COMPLIANCE_REMEDIATIONS +| COMPLIANCE_BENCHMARKS +| AUTH_PROVIDERS +| COMPLIANCE_REPORT_SNAPSHOT +| IMAGE_COMPONENTS_V2 +| IMAGE_VULNERABILITIES_V2 + +|=== + +[id="V1SearchOptionsResponse_CommonObjectReference"] +=== V1SearchOptionsResponse + +[id="Fields-V1SearchOptionsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| options +| +| +| List of `string` +| +| + +|=== + +[id="V1SearchResponse_CommonObjectReference"] +=== V1SearchResponse + +[id="Fields-V1SearchResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| results +| +| +| List of <<V1SearchResult_CommonObjectReference,V1SearchResult>> +| +| + +| counts +| +| +| List of <<SearchResponseCount_CommonObjectReference,SearchResponseCount>> +| +| + +|=== + +[id="V1SearchResult_CommonObjectReference"] +=== V1SearchResult + +[id="Fields-V1SearchResult_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| category +| +| +| <<V1SearchCategory_CommonObjectReference,V1SearchCategory>> +| +| SEARCH_UNSET, ALERTS, IMAGES, IMAGE_COMPONENTS, IMAGE_VULN_EDGE, IMAGE_COMPONENT_EDGE, POLICIES, DEPLOYMENTS, ACTIVE_COMPONENT, PODS, SECRETS, PROCESS_INDICATORS, COMPLIANCE, CLUSTERS, NAMESPACES, NODES, NODE_COMPONENTS, NODE_VULN_EDGE, NODE_COMPONENT_EDGE, NODE_COMPONENT_CVE_EDGE, COMPLIANCE_STANDARD, COMPLIANCE_CONTROL_GROUP, COMPLIANCE_CONTROL, SERVICE_ACCOUNTS, ROLES, ROLEBINDINGS, REPORT_CONFIGURATIONS, PROCESS_BASELINES, SUBJECTS, RISKS, VULNERABILITIES, CLUSTER_VULNERABILITIES, IMAGE_VULNERABILITIES, NODE_VULNERABILITIES, COMPONENT_VULN_EDGE, CLUSTER_VULN_EDGE, NETWORK_ENTITY, VULN_REQUEST, NETWORK_BASELINE, NETWORK_POLICIES, PROCESS_BASELINE_RESULTS, COMPLIANCE_METADATA, COMPLIANCE_RESULTS, COMPLIANCE_DOMAIN, CLUSTER_HEALTH, POLICY_CATEGORIES, IMAGE_INTEGRATIONS, COLLECTIONS, POLICY_CATEGORY_EDGE, PROCESS_LISTENING_ON_PORT, API_TOKEN, REPORT_METADATA, REPORT_SNAPSHOT, COMPLIANCE_INTEGRATIONS, COMPLIANCE_SCAN_CONFIG, COMPLIANCE_SCAN, COMPLIANCE_CHECK_RESULTS, BLOB, ADMINISTRATION_EVENTS, COMPLIANCE_SCAN_CONFIG_STATUS, ADMINISTRATION_USAGE, COMPLIANCE_PROFILES, COMPLIANCE_RULES, COMPLIANCE_SCAN_SETTING_BINDINGS, COMPLIANCE_SUITES, CLOUD_SOURCES, DISCOVERED_CLUSTERS, COMPLIANCE_REMEDIATIONS, COMPLIANCE_BENCHMARKS, AUTH_PROVIDERS, COMPLIANCE_REPORT_SNAPSHOT, IMAGE_COMPONENTS_V2, IMAGE_VULNERABILITIES_V2, + +| fieldToMatches +| +| +| Map of <<SearchResultMatches_CommonObjectReference,SearchResultMatches>> +| +| + +| score +| +| +| Double +| +| double + +| location +| +| +| String +| Location is intended to be a unique, yet human readable, identifier for the result. For example, for a deployment, the location will be "$cluster_name/$namespace/$deployment_name. It is displayed in the UI in the global search results, underneath the name for each result. +| + +|=== + +[id="V1SecuredUnitsUsageResponse_CommonObjectReference"] +=== V1SecuredUnitsUsageResponse + +SecuredUnitsUsageResponse holds the values of the currently observable +administration usage metrics. + +[id="Fields-V1SecuredUnitsUsageResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| numNodes +| +| +| String +| +| int64 + +| numCpuUnits +| +| +| String +| +| int64 + +|=== + +[id="V1ServiceAccountAndRoles_CommonObjectReference"] +=== V1ServiceAccountAndRoles + +A service account and the roles that reference it Next Tag: 5 + +[id="Fields-V1ServiceAccountAndRoles_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| serviceAccount +| +| +| <<StorageServiceAccount_CommonObjectReference,StorageServiceAccount>> +| +| + +| clusterRoles +| +| +| List of <<StorageK8sRole_CommonObjectReference,StorageK8sRole>> +| +| + +| scopedRoles +| +| +| List of <<V1ScopedRoles_CommonObjectReference,V1ScopedRoles>> +| +| + +| deploymentRelationships +| +| +| List of <<V1SADeploymentRelationship_CommonObjectReference,V1SADeploymentRelationship>> +| +| + +|=== + +[id="V1ServiceIdentityResponse_CommonObjectReference"] +=== V1ServiceIdentityResponse + +[id="Fields-V1ServiceIdentityResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| identities +| +| +| List of <<StorageServiceIdentity_CommonObjectReference,StorageServiceIdentity>> +| +| + +|=== + +[id="V1SimulateNetworkGraphResponse_CommonObjectReference"] +=== V1SimulateNetworkGraphResponse + +[id="Fields-V1SimulateNetworkGraphResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| simulatedGraph +| +| +| <<V1NetworkGraph_CommonObjectReference,V1NetworkGraph>> +| +| + +| policies +| +| +| List of <<V1NetworkPolicyInSimulation_CommonObjectReference,V1NetworkPolicyInSimulation>> +| +| + +| added +| +| +| <<V1NetworkGraphDiff_CommonObjectReference,V1NetworkGraphDiff>> +| +| + +| removed +| +| +| <<V1NetworkGraphDiff_CommonObjectReference,V1NetworkGraphDiff>> +| +| + +|=== + +[id="V1SortOption_CommonObjectReference"] +=== V1SortOption + +[id="Fields-V1SortOption_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| field +| +| +| String +| +| + +| reversed +| +| +| Boolean +| +| + +| aggregateBy +| +| +| <<V1AggregateBy_CommonObjectReference,V1AggregateBy>> +| +| + +|=== + +[id="V1SubjectAndRoles_CommonObjectReference"] +=== V1SubjectAndRoles + +[id="Fields-V1SubjectAndRoles_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| subject +| +| +| <<StorageSubject_CommonObjectReference,StorageSubject>> +| +| + +| roles +| +| +| List of <<StorageK8sRole_CommonObjectReference,StorageK8sRole>> +| +| + +|=== + +[id="V1SuppressCVERequest_CommonObjectReference"] +=== V1SuppressCVERequest + +[id="Fields-V1SuppressCVERequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cves +| +| +| List of `string` +| These are (NVD) vulnerability identifiers, `cve` field of `storage.CVE`, and *not* the `id` field. For example, CVE-2021-44832. +| + +| duration +| +| +| String +| In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s". +| + +|=== + +[id="V1TLSChallengeResponse_CommonObjectReference"] +=== V1TLSChallengeResponse + +[id="Fields-V1TLSChallengeResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| trustInfoSerialized +| +| +| byte[] +| +| byte + +| signature +| +| +| byte[] +| +| byte + +|=== + +[id="V1TestCloudSourceRequest_CommonObjectReference"] +=== V1TestCloudSourceRequest + +[id="Fields-V1TestCloudSourceRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cloudSource +| +| +| <<V1CloudSource_CommonObjectReference,V1CloudSource>> +| +| + +| updateCredentials +| +| +| Boolean +| If true, cloud_source must include valid credentials. If false, the resource must already exist and credentials in cloud_source are ignored. +| + +|=== + +[id="V1TriggerComplianceRunsRequest_CommonObjectReference"] +=== V1TriggerComplianceRunsRequest + +[id="Fields-V1TriggerComplianceRunsRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| selection +| +| +| <<V1ComplianceRunSelection_CommonObjectReference,V1ComplianceRunSelection>> +| +| + +|=== + +[id="V1TriggerComplianceRunsResponse_CommonObjectReference"] +=== V1TriggerComplianceRunsResponse + +[id="Fields-V1TriggerComplianceRunsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| startedRuns +| +| +| List of <<V1ComplianceRun_CommonObjectReference,V1ComplianceRun>> +| +| + +|=== + +[id="V1Type_CommonObjectReference"] +=== V1Type + +[id="Fields-V1Type_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| CREATED +| REMOVED + +|=== + +[id="V1UndoVulnRequestResponse_CommonObjectReference"] +=== V1UndoVulnRequestResponse + +[id="Fields-V1UndoVulnRequestResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requestInfo +| +| +| <<StorageVulnerabilityRequest_CommonObjectReference,StorageVulnerabilityRequest>> +| +| + +|=== + +[id="V1UnsuppressCVERequest_CommonObjectReference"] +=== V1UnsuppressCVERequest + +[id="Fields-V1UnsuppressCVERequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cves +| +| +| List of `string` +| These are (NVD) vulnerability identifiers, `cve` field of `storage.CVE`, and *not* the `id` field. For example, CVE-2021-44832. +| + +|=== + +[id="V1UpdateCollectionResponse_CommonObjectReference"] +=== V1UpdateCollectionResponse + +[id="Fields-V1UpdateCollectionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| collection +| +| +| <<StorageResourceCollection_CommonObjectReference,StorageResourceCollection>> +| +| + +|=== + +[id="V1UpdateExternalBackupRequest_CommonObjectReference"] +=== V1UpdateExternalBackupRequest + +[id="Fields-V1UpdateExternalBackupRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| externalBackup +| +| +| <<StorageExternalBackup_CommonObjectReference,StorageExternalBackup>> +| +| + +| updatePassword +| +| +| Boolean +| When false, use the stored credentials of an existing external backup configuration given its ID. +| + +|=== + +[id="V1UpdateImageIntegrationRequest_CommonObjectReference"] +=== V1UpdateImageIntegrationRequest + +[id="Fields-V1UpdateImageIntegrationRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<StorageImageIntegration_CommonObjectReference,StorageImageIntegration>> +| +| + +| updatePassword +| +| +| Boolean +| When false, use the stored credentials of an existing image integration given its ID. +| + +|=== + +[id="V1UpdateNotifierRequest_CommonObjectReference"] +=== V1UpdateNotifierRequest + +[id="Fields-V1UpdateNotifierRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| notifier +| +| +| <<StorageNotifier_CommonObjectReference,StorageNotifier>> +| +| + +| updatePassword +| +| +| Boolean +| When false, use the stored credentials of an existing notifier configuration given its ID. +| + +|=== + +[id="V1UpdateProcessBaselinesRequest_CommonObjectReference"] +=== V1UpdateProcessBaselinesRequest + +[id="Fields-V1UpdateProcessBaselinesRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| keys +| +| +| List of <<StorageProcessBaselineKey_CommonObjectReference,StorageProcessBaselineKey>> +| +| + +| addElements +| +| +| List of <<StorageBaselineItem_CommonObjectReference,StorageBaselineItem>> +| +| + +| removeElements +| +| +| List of <<StorageBaselineItem_CommonObjectReference,StorageBaselineItem>> +| +| + +|=== + +[id="V1UpdateProcessBaselinesResponse_CommonObjectReference"] +=== V1UpdateProcessBaselinesResponse + +[id="Fields-V1UpdateProcessBaselinesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| baselines +| +| +| List of <<StorageProcessBaseline_CommonObjectReference,StorageProcessBaseline>> +| +| + +| errors +| +| +| List of <<V1ProcessBaselineUpdateError_CommonObjectReference,V1ProcessBaselineUpdateError>> +| +| + +|=== + +[id="V1UpdateSensorUpgradeConfigRequest_CommonObjectReference"] +=== V1UpdateSensorUpgradeConfigRequest + +[id="Fields-V1UpdateSensorUpgradeConfigRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<StorageSensorUpgradeConfig_CommonObjectReference,StorageSensorUpgradeConfig>> +| +| + +|=== + +[id="V1UpdateVulnRequestResponse_CommonObjectReference"] +=== V1UpdateVulnRequestResponse + +[id="Fields-V1UpdateVulnRequestResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| requestInfo +| +| +| <<StorageVulnerabilityRequest_CommonObjectReference,StorageVulnerabilityRequest>> +| +| + +|=== + +[id="V1UpdateVulnerabilityExceptionConfigRequest_CommonObjectReference"] +=== V1UpdateVulnerabilityExceptionConfigRequest + +[id="Fields-V1UpdateVulnerabilityExceptionConfigRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<V1VulnerabilityExceptionConfig_CommonObjectReference,V1VulnerabilityExceptionConfig>> +| +| + +|=== + +[id="V1UpdateVulnerabilityExceptionConfigResponse_CommonObjectReference"] +=== V1UpdateVulnerabilityExceptionConfigResponse + +[id="Fields-V1UpdateVulnerabilityExceptionConfigResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| config +| +| +| <<V1VulnerabilityExceptionConfig_CommonObjectReference,V1VulnerabilityExceptionConfig>> +| +| + +|=== + +[id="V1UserAttribute_CommonObjectReference"] +=== V1UserAttribute + +[id="Fields-V1UserAttribute_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| key +| +| +| String +| +| + +| values +| +| +| List of `string` +| +| + +|=== + +[id="V1UserAttributeTuple_CommonObjectReference"] +=== V1UserAttributeTuple + +UserAttributeTuple descript the auth:key:value tuple that decides group membership. Next Tag: 4 + +[id="Fields-V1UserAttributeTuple_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| authProviderId +| +| +| String +| +| + +| key +| +| +| String +| +| + +| value +| +| +| String +| +| + +|=== + +[id="V1VulnDefinitionsInfo_CommonObjectReference"] +=== V1VulnDefinitionsInfo + +[id="Fields-V1VulnDefinitionsInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| lastUpdatedTimestamp +| +| +| Date +| +| date-time + +|=== + +[id="V1VulnDefinitionsInfoRequestComponent_CommonObjectReference"] +=== V1VulnDefinitionsInfoRequestComponent + +[id="Fields-V1VulnDefinitionsInfoRequestComponent_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| SCANNER +| SCANNER_V4 + +|=== + +[id="V1VulnMgmtExportWorkloadsResponse_CommonObjectReference"] +=== V1VulnMgmtExportWorkloadsResponse + +The workloads response contains the full image details including the +vulnerability data. + +[id="Fields-V1VulnMgmtExportWorkloadsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| deployment +| +| +| <<StorageDeployment_CommonObjectReference,StorageDeployment>> +| +| + +| images +| +| +| List of <<StorageImage_CommonObjectReference,StorageImage>> +| +| + +| livePods +| +| +| Integer +| +| int32 + +|=== + +[id="V1VulnerabilityExceptionConfig_CommonObjectReference"] +=== V1VulnerabilityExceptionConfig + +[id="Fields-V1VulnerabilityExceptionConfig_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| expiryOptions +| +| +| <<V1VulnerabilityExceptionConfigExpiryOptions_CommonObjectReference,V1VulnerabilityExceptionConfigExpiryOptions>> +| +| + +|=== + +[id="V1VulnerabilityExceptionConfigExpiryOptions_CommonObjectReference"] +=== V1VulnerabilityExceptionConfigExpiryOptions + +[id="Fields-V1VulnerabilityExceptionConfigExpiryOptions_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| dayOptions +| +| +| List of <<V1DayOption_CommonObjectReference,V1DayOption>> +| This allows users to set expiry interval based on number of days. +| + +| fixableCveOptions +| +| +| <<V1VulnerabilityExceptionConfigFixableCVEOptions_CommonObjectReference,V1VulnerabilityExceptionConfigFixableCVEOptions>> +| +| + +| customDate +| +| +| Boolean +| This option, if true, allows UI to show a custom date picker for setting expiry date. +| + +| indefinite +| +| +| Boolean +| +| + +|=== + +[id="V1VulnerabilityExceptionConfigFixableCVEOptions_CommonObjectReference"] +=== V1VulnerabilityExceptionConfigFixableCVEOptions + +[id="Fields-V1VulnerabilityExceptionConfigFixableCVEOptions_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| allFixable +| +| +| Boolean +| This options allows users to expire the vulnerability deferral request if and only if **all** vulnerabilities in the requests become fixable. +| + +| anyFixable +| +| +| Boolean +| This options allows users to expire the vulnerability deferral request if **any** vulnerability in the requests become fixable. +| + +|=== + +[id="V1WatchImageRequest_CommonObjectReference"] +=== V1WatchImageRequest + +[id="Fields-V1WatchImageRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| The name of the image. This must be fully qualified, including a tag, but must NOT include a SHA. +| + +|=== + +[id="V1WatchImageResponse_CommonObjectReference"] +=== V1WatchImageResponse + +[id="Fields-V1WatchImageResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| normalizedName +| +| +| String +| +| + +| errorType +| +| +| <<WatchImageResponseErrorType_CommonObjectReference,WatchImageResponseErrorType>> +| +| NO_ERROR, INVALID_IMAGE_NAME, NO_VALID_INTEGRATION, SCAN_FAILED, + +| errorMessage +| +| +| String +| Only set if error_type is NOT equal to "NO_ERROR". +| + +|=== + +[id="V2AggregateBy_CommonObjectReference"] +=== V2AggregateBy + +[id="Fields-V2AggregateBy_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| aggrFunc +| +| +| <<V2Aggregation_CommonObjectReference,V2Aggregation>> +| +| UNSET, COUNT, MIN, MAX, + +| distinct +| +| +| Boolean +| +| + +|=== + +[id="V2Aggregation_CommonObjectReference"] +=== V2Aggregation + +[id="Fields-V2Aggregation_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| COUNT +| MIN +| MAX + +|=== + +[id="V2ApproveVulnerabilityExceptionResponse_CommonObjectReference"] +=== V2ApproveVulnerabilityExceptionResponse + +[id="Fields-V2ApproveVulnerabilityExceptionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| exception +| +| +| <<V2VulnerabilityException_CommonObjectReference,V2VulnerabilityException>> +| +| + +|=== + +[id="V2BaseComplianceScanConfigurationSettings_CommonObjectReference"] +=== V2BaseComplianceScanConfigurationSettings + +Next available tag: 5 + +[id="Fields-V2BaseComplianceScanConfigurationSettings_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| oneTimeScan +| +| +| Boolean +| +| + +| profiles +| +| +| List of `string` +| +| + +| scanSchedule +| +| +| <<V2Schedule_CommonObjectReference,V2Schedule>> +| +| + +| description +| +| +| String +| +| + +| notifiers +| +| +| List of <<V2NotifierConfiguration_CommonObjectReference,V2NotifierConfiguration>> +| +| + +|=== + +[id="V2COStatus_CommonObjectReference"] +=== V2COStatus + +Represents the status of compliance operator + +[id="Fields-V2COStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| HEALTHY +| UNHEALTHY + +|=== + +[id="V2CancelVulnerabilityExceptionResponse_CommonObjectReference"] +=== V2CancelVulnerabilityExceptionResponse + +[id="Fields-V2CancelVulnerabilityExceptionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| exception +| +| +| <<V2VulnerabilityException_CommonObjectReference,V2VulnerabilityException>> +| +| + +|=== + +[id="V2ClusterCheckStatus_CommonObjectReference"] +=== V2ClusterCheckStatus + +ClusterCheckStatus groups the result of the check by cluster + +[id="Fields-V2ClusterCheckStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cluster +| +| +| <<V2ComplianceScanCluster_CommonObjectReference,V2ComplianceScanCluster>> +| +| + +| status +| +| +| <<V2ComplianceCheckStatus_CommonObjectReference,V2ComplianceCheckStatus>> +| +| UNSET_CHECK_STATUS, PASS, FAIL, ERROR, INFO, MANUAL, NOT_APPLICABLE, INCONSISTENT, + +| createdTime +| +| +| Date +| +| date-time + +| checkUid +| +| +| String +| +| + +| lastScanTime +| +| +| Date +| +| date-time + +|=== + +[id="V2ClusterPlatformType_CommonObjectReference"] +=== V2ClusterPlatformType + +[id="Fields-V2ClusterPlatformType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| GENERIC_CLUSTER +| KUBERNETES_CLUSTER +| OPENSHIFT_CLUSTER +| OPENSHIFT4_CLUSTER + +|=== + +[id="V2ClusterProviderType_CommonObjectReference"] +=== V2ClusterProviderType + +[id="Fields-V2ClusterProviderType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSPECIFIED +| AKS +| ARO +| EKS +| GKE +| OCP +| OSD +| ROSA + +|=== + +[id="V2ClusterScanStatus_CommonObjectReference"] +=== V2ClusterScanStatus + +ClusterScanStatus holds status based on cluster in the event that a scan configuration was successfully applied to some clusters but not others. Next available tag: 5 + +[id="Fields-V2ClusterScanStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| errors +| +| +| List of `string` +| +| + +| clusterName +| +| +| String +| +| + +| suiteStatus +| +| +| <<ClusterScanStatusSuiteStatus_CommonObjectReference,ClusterScanStatusSuiteStatus>> +| +| + +|=== + +[id="V2CollectionReference_CommonObjectReference"] +=== V2CollectionReference + +[id="Fields-V2CollectionReference_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| collectionId +| +| +| String +| +| + +| collectionName +| +| +| String +| +| + +|=== + +[id="V2CollectionSnapshot_CommonObjectReference"] +=== V2CollectionSnapshot + +[id="Fields-V2CollectionSnapshot_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +|=== + +[id="V2Comment_CommonObjectReference"] +=== V2Comment + +[id="Fields-V2Comment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| message +| +| +| String +| +| + +| user +| +| +| <<V2SlimUser_CommonObjectReference,V2SlimUser>> +| +| + +| createdAt +| +| +| Date +| +| date-time + +|=== + +[id="V2ComplianceBenchmark_CommonObjectReference"] +=== V2ComplianceBenchmark + +[id="Fields-V2ComplianceBenchmark_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| version +| +| +| String +| +| + +| description +| +| +| String +| +| + +| provider +| +| +| String +| +| + +| shortName +| +| +| String +| +| + +|=== + +[id="V2ComplianceCheckData_CommonObjectReference"] +=== V2ComplianceCheckData + +[id="Fields-V2ComplianceCheckData_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| scanName +| +| +| String +| +| + +| result +| +| +| <<V2ComplianceCheckResult_CommonObjectReference,V2ComplianceCheckResult>> +| +| + +|=== + +[id="V2ComplianceCheckResult_CommonObjectReference"] +=== V2ComplianceCheckResult + +ComplianceCheckResult details of an instance of a compliance check result + +[id="Fields-V2ComplianceCheckResult_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| checkId +| +| +| String +| +| + +| checkName +| +| +| String +| +| + +| checkUid +| +| +| String +| +| + +| description +| +| +| String +| +| + +| instructions +| +| +| String +| +| + +| rationale +| +| +| String +| +| + +| valuesUsed +| +| +| List of `string` +| +| + +| warnings +| +| +| List of `string` +| +| + +| status +| +| +| <<V2ComplianceCheckStatus_CommonObjectReference,V2ComplianceCheckStatus>> +| +| UNSET_CHECK_STATUS, PASS, FAIL, ERROR, INFO, MANUAL, NOT_APPLICABLE, INCONSISTENT, + +| ruleName +| +| +| String +| +| + +| labels +| +| +| Map of `string` +| +| + +| annotations +| +| +| Map of `string` +| +| + +| controls +| +| +| List of <<V2ComplianceControl_CommonObjectReference,V2ComplianceControl>> +| +| + +|=== + +[id="V2ComplianceCheckResultStatusCount_CommonObjectReference"] +=== V2ComplianceCheckResultStatusCount + +Group the number of occurrences by status + +[id="Fields-V2ComplianceCheckResultStatusCount_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| checkName +| +| +| String +| +| + +| rationale +| +| +| String +| +| + +| ruleName +| +| +| String +| +| + +| checkStats +| +| +| List of <<V2ComplianceCheckStatusCount_CommonObjectReference,V2ComplianceCheckStatusCount>> +| +| + +| controls +| +| +| List of <<V2ComplianceControl_CommonObjectReference,V2ComplianceControl>> +| +| + +|=== + +[id="V2ComplianceCheckStatus_CommonObjectReference"] +=== V2ComplianceCheckStatus + +[id="Fields-V2ComplianceCheckStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET_CHECK_STATUS +| PASS +| FAIL +| ERROR +| INFO +| MANUAL +| NOT_APPLICABLE +| INCONSISTENT + +|=== + +[id="V2ComplianceCheckStatusCount_CommonObjectReference"] +=== V2ComplianceCheckStatusCount + +Group the number of occurrences by status + +[id="Fields-V2ComplianceCheckStatusCount_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +| status +| +| +| <<V2ComplianceCheckStatus_CommonObjectReference,V2ComplianceCheckStatus>> +| +| UNSET_CHECK_STATUS, PASS, FAIL, ERROR, INFO, MANUAL, NOT_APPLICABLE, INCONSISTENT, + +|=== + +[id="V2ComplianceClusterCheckStatus_CommonObjectReference"] +=== V2ComplianceClusterCheckStatus + +ComplianceClusterCheckStatus provides the status of a compliance check result across clusters + +[id="Fields-V2ComplianceClusterCheckStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| checkId +| +| +| String +| +| + +| checkName +| +| +| String +| +| + +| clusters +| +| +| List of <<V2ClusterCheckStatus_CommonObjectReference,V2ClusterCheckStatus>> +| +| + +| description +| +| +| String +| +| + +| instructions +| +| +| String +| +| + +| rationale +| +| +| String +| +| + +| valuesUsed +| +| +| List of `string` +| +| + +| warnings +| +| +| List of `string` +| +| + +| labels +| +| +| Map of `string` +| +| + +| annotations +| +| +| Map of `string` +| +| + +| controls +| +| +| List of <<V2ComplianceControl_CommonObjectReference,V2ComplianceControl>> +| +| + +|=== + +[id="V2ComplianceClusterOverallStats_CommonObjectReference"] +=== V2ComplianceClusterOverallStats + +ComplianceClusterOverallStats provides overall stats for cluster + +[id="Fields-V2ComplianceClusterOverallStats_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cluster +| +| +| <<V2ComplianceScanCluster_CommonObjectReference,V2ComplianceScanCluster>> +| +| + +| checkStats +| +| +| List of <<V2ComplianceCheckStatusCount_CommonObjectReference,V2ComplianceCheckStatusCount>> +| +| + +| clusterErrors +| +| +| List of `string` +| +| + +| lastScanTime +| +| +| Date +| +| date-time + +|=== + +[id="V2ComplianceClusterScanStats_CommonObjectReference"] +=== V2ComplianceClusterScanStats + +ComplianceClusterScanStats provides scan stats overview based on cluster + +[id="Fields-V2ComplianceClusterScanStats_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanStats +| +| +| <<V2ComplianceScanStatsShim_CommonObjectReference,V2ComplianceScanStatsShim>> +| +| + +| cluster +| +| +| <<V2ComplianceScanCluster_CommonObjectReference,V2ComplianceScanCluster>> +| +| + +|=== + +[id="V2ComplianceControl_CommonObjectReference"] +=== V2ComplianceControl + +[id="Fields-V2ComplianceControl_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| standard +| +| +| String +| +| + +| control +| +| +| String +| +| + +|=== + +[id="V2ComplianceIntegration_CommonObjectReference"] +=== V2ComplianceIntegration + +Next Tag: 11 + +[id="Fields-V2ComplianceIntegration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| version +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| namespace +| +| +| String +| +| + +| statusErrors +| +| +| List of `string` +| Collection of errors that occurred while trying to obtain compliance operator health info. +| + +| operatorInstalled +| +| +| Boolean +| +| + +| status +| +| +| <<V2COStatus_CommonObjectReference,V2COStatus>> +| +| HEALTHY, UNHEALTHY, + +| clusterPlatformType +| +| +| <<V2ClusterPlatformType_CommonObjectReference,V2ClusterPlatformType>> +| +| GENERIC_CLUSTER, KUBERNETES_CLUSTER, OPENSHIFT_CLUSTER, OPENSHIFT4_CLUSTER, + +| clusterProviderType +| +| +| <<V2ClusterProviderType_CommonObjectReference,V2ClusterProviderType>> +| +| UNSPECIFIED, AKS, ARO, EKS, GKE, OCP, OSD, ROSA, + +|=== + +[id="V2ComplianceProfile_CommonObjectReference"] +=== V2ComplianceProfile + +Next Tag: 12 + +[id="Fields-V2ComplianceProfile_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| profileVersion +| +| +| String +| +| + +| productType +| +| +| String +| +| + +| description +| +| +| String +| +| + +| rules +| +| +| List of <<V2ComplianceRule_CommonObjectReference,V2ComplianceRule>> +| +| + +| product +| +| +| String +| +| + +| title +| +| +| String +| +| + +| values +| +| +| List of `string` +| +| + +| standards +| +| +| List of <<V2ComplianceBenchmark_CommonObjectReference,V2ComplianceBenchmark>> +| +| + +|=== + +[id="V2ComplianceProfileScanStats_CommonObjectReference"] +=== V2ComplianceProfileScanStats + +ComplianceProfileScanStats provides scan stats overview based on profile + +[id="Fields-V2ComplianceProfileScanStats_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| checkStats +| +| +| List of <<V2ComplianceCheckStatusCount_CommonObjectReference,V2ComplianceCheckStatusCount>> +| +| + +| profileName +| +| +| String +| +| + +| title +| +| +| String +| +| + +| version +| +| +| String +| +| + +| benchmarks +| +| +| List of <<V2ComplianceBenchmark_CommonObjectReference,V2ComplianceBenchmark>> +| +| + +|=== + +[id="V2ComplianceProfileSummary_CommonObjectReference"] +=== V2ComplianceProfileSummary + +Next Tag: 8 + +[id="Fields-V2ComplianceProfileSummary_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| productType +| +| +| String +| +| + +| description +| +| +| String +| +| + +| title +| +| +| String +| +| + +| ruleCount +| +| +| Integer +| +| int32 + +| profileVersion +| +| +| String +| +| + +| standards +| +| +| List of <<V2ComplianceBenchmark_CommonObjectReference,V2ComplianceBenchmark>> +| +| + +|=== + +[id="V2ComplianceReportHistoryResponse_CommonObjectReference"] +=== V2ComplianceReportHistoryResponse + +[id="Fields-V2ComplianceReportHistoryResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| complianceReportSnapshots +| +| +| List of <<V2ComplianceReportSnapshot_CommonObjectReference,V2ComplianceReportSnapshot>> +| +| + +|=== + +[id="V2ComplianceReportSnapshot_CommonObjectReference"] +=== V2ComplianceReportSnapshot + +[id="Fields-V2ComplianceReportSnapshot_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportJobId +| +| +| String +| +| + +| scanConfigId +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| reportStatus +| +| +| <<V2ComplianceReportStatus_CommonObjectReference,V2ComplianceReportStatus>> +| +| + +| reportData +| +| +| <<V2ComplianceScanConfigurationStatus_CommonObjectReference,V2ComplianceScanConfigurationStatus>> +| +| + +| user +| +| +| <<V2SlimUser_CommonObjectReference,V2SlimUser>> +| +| + +| isDownloadAvailable +| +| +| Boolean +| +| + +|=== + +[id="V2ComplianceReportStatus_CommonObjectReference"] +=== V2ComplianceReportStatus + +[id="Fields-V2ComplianceReportStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| runState +| +| +| <<V2ComplianceReportStatusRunState_CommonObjectReference,V2ComplianceReportStatusRunState>> +| +| WAITING, PREPARING, GENERATED, DELIVERED, FAILURE, PARTIAL_ERROR, PARTIAL_SCAN_ERROR_DOWNLOAD, PARTIAL_SCAN_ERROR_EMAIL, + +| startedAt +| +| +| Date +| +| date-time + +| completedAt +| +| +| Date +| +| date-time + +| errorMsg +| +| +| String +| +| + +| reportRequestType +| +| +| <<V2ComplianceReportStatusReportMethod_CommonObjectReference,V2ComplianceReportStatusReportMethod>> +| +| ON_DEMAND, SCHEDULED, + +| reportNotificationMethod +| +| +| <<V2NotificationMethod_CommonObjectReference,V2NotificationMethod>> +| +| EMAIL, DOWNLOAD, + +| failedClusters +| +| +| List of <<V2FailedCluster_CommonObjectReference,V2FailedCluster>> +| +| + +|=== + +[id="V2ComplianceReportStatusReportMethod_CommonObjectReference"] +=== V2ComplianceReportStatusReportMethod + +[id="Fields-V2ComplianceReportStatusReportMethod_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ON_DEMAND +| SCHEDULED + +|=== + +[id="V2ComplianceReportStatusRunState_CommonObjectReference"] +=== V2ComplianceReportStatusRunState + +[id="Fields-V2ComplianceReportStatusRunState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| WAITING +| PREPARING +| GENERATED +| DELIVERED +| FAILURE +| PARTIAL_ERROR +| PARTIAL_SCAN_ERROR_DOWNLOAD +| PARTIAL_SCAN_ERROR_EMAIL + +|=== + +[id="V2ComplianceRule_CommonObjectReference"] +=== V2ComplianceRule + +[id="Fields-V2ComplianceRule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| name +| +| +| String +| +| + +| ruleType +| +| +| String +| +| + +| severity +| +| +| String +| +| + +| standard +| +| +| String +| +| + +| control +| +| +| String +| +| + +| title +| +| +| String +| +| + +| description +| +| +| String +| +| + +| rationale +| +| +| String +| +| + +| fixes +| +| +| List of <<ComplianceRuleFix_CommonObjectReference,ComplianceRuleFix>> +| +| + +| id +| +| +| String +| +| + +| ruleId +| +| +| String +| +| + +| parentRule +| +| +| String +| +| + +| instructions +| +| +| String +| +| + +| warning +| +| +| String +| +| + +|=== + +[id="V2ComplianceRunReportRequest_CommonObjectReference"] +=== V2ComplianceRunReportRequest + +[id="Fields-V2ComplianceRunReportRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanConfigId +| +| +| String +| +| + +| reportNotificationMethod +| +| +| <<V2NotificationMethod_CommonObjectReference,V2NotificationMethod>> +| +| EMAIL, DOWNLOAD, + +|=== + +[id="V2ComplianceRunReportResponse_CommonObjectReference"] +=== V2ComplianceRunReportResponse + +[id="Fields-V2ComplianceRunReportResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| runState +| +| +| <<V2ComplianceRunReportResponseRunState_CommonObjectReference,V2ComplianceRunReportResponseRunState>> +| +| SUBMITTED, ERROR, + +| submittedAt +| +| +| Date +| +| date-time + +| errorMsg +| +| +| String +| +| + +|=== + +[id="V2ComplianceRunReportResponseRunState_CommonObjectReference"] +=== V2ComplianceRunReportResponseRunState + +[id="Fields-V2ComplianceRunReportResponseRunState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| SUBMITTED +| ERROR + +|=== + +[id="V2ComplianceScanCluster_CommonObjectReference"] +=== V2ComplianceScanCluster + +[id="Fields-V2ComplianceScanCluster_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +|=== + +[id="V2ComplianceScanConfiguration_CommonObjectReference"] +=== V2ComplianceScanConfiguration + +Next available tag: 5 + +[id="Fields-V2ComplianceScanConfiguration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| scanName +| +| +| String +| +| + +| scanConfig +| +| +| <<V2BaseComplianceScanConfigurationSettings_CommonObjectReference,V2BaseComplianceScanConfigurationSettings>> +| +| + +| clusters +| +| +| List of `string` +| +| + +|=== + +[id="V2ComplianceScanConfigurationStatus_CommonObjectReference"] +=== V2ComplianceScanConfigurationStatus + +Next available tag: 9 + +[id="Fields-V2ComplianceScanConfigurationStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| scanName +| +| +| String +| +| + +| scanConfig +| +| +| <<V2BaseComplianceScanConfigurationSettings_CommonObjectReference,V2BaseComplianceScanConfigurationSettings>> +| +| + +| clusterStatus +| +| +| List of <<V2ClusterScanStatus_CommonObjectReference,V2ClusterScanStatus>> +| +| + +| createdTime +| +| +| Date +| +| date-time + +| lastUpdatedTime +| +| +| Date +| +| date-time + +| modifiedBy +| +| +| <<V2SlimUser_CommonObjectReference,V2SlimUser>> +| +| + +| lastExecutedTime +| +| +| Date +| +| date-time + +|=== + +[id="V2ComplianceScanStatsShim_CommonObjectReference"] +=== V2ComplianceScanStatsShim + +ComplianceScanStatsShim models statistics of checks for a given scan configuration + +[id="Fields-V2ComplianceScanStatsShim_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanName +| +| +| String +| +| + +| checkStats +| +| +| List of <<V2ComplianceCheckStatusCount_CommonObjectReference,V2ComplianceCheckStatusCount>> +| +| + +| lastScan +| +| +| Date +| +| date-time + +| scanConfigId +| +| +| String +| +| + +|=== + +[id="V2CountReportConfigurationsResponse_CommonObjectReference"] +=== V2CountReportConfigurationsResponse + +[id="Fields-V2CountReportConfigurationsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| count +| +| +| Integer +| +| int32 + +|=== + +[id="V2CreateDeferVulnerabilityExceptionRequest_CommonObjectReference"] +=== V2CreateDeferVulnerabilityExceptionRequest + +next available tag: 6 + +[id="Fields-V2CreateDeferVulnerabilityExceptionRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cves +| +| +| List of `string` +| REQUIRED. The CVEs to which the exception should be applied. +| + +| comment +| +| +| String +| REQUIRED. The rationale for creating the exception. +| + +| scope +| +| +| <<VulnerabilityExceptionScope_CommonObjectReference,VulnerabilityExceptionScope>> +| +| + +| exceptionExpiry +| +| +| <<V2ExceptionExpiry_CommonObjectReference,V2ExceptionExpiry>> +| +| + +|=== + +[id="V2CreateDeferVulnerabilityExceptionResponse_CommonObjectReference"] +=== V2CreateDeferVulnerabilityExceptionResponse + +[id="Fields-V2CreateDeferVulnerabilityExceptionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| exception +| +| +| <<V2VulnerabilityException_CommonObjectReference,V2VulnerabilityException>> +| +| + +|=== + +[id="V2CreateFalsePositiveVulnerabilityExceptionRequest_CommonObjectReference"] +=== V2CreateFalsePositiveVulnerabilityExceptionRequest + +[id="Fields-V2CreateFalsePositiveVulnerabilityExceptionRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cves +| +| +| List of `string` +| REQUIRED. The CVEs to which the exception should be applied. +| + +| scope +| +| +| <<VulnerabilityExceptionScope_CommonObjectReference,VulnerabilityExceptionScope>> +| +| + +| comment +| +| +| String +| REQUIRED. The rationale for creating the exception. +| + +|=== + +[id="V2CreateFalsePositiveVulnerabilityExceptionResponse_CommonObjectReference"] +=== V2CreateFalsePositiveVulnerabilityExceptionResponse + +[id="Fields-V2CreateFalsePositiveVulnerabilityExceptionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| exception +| +| +| <<V2VulnerabilityException_CommonObjectReference,V2VulnerabilityException>> +| +| + +|=== + +[id="V2DeferralRequest_CommonObjectReference"] +=== V2DeferralRequest + +[id="Fields-V2DeferralRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| expiry +| +| +| <<V2ExceptionExpiry_CommonObjectReference,V2ExceptionExpiry>> +| +| + +|=== + +[id="V2DeferralUpdate_CommonObjectReference"] +=== V2DeferralUpdate + +[id="Fields-V2DeferralUpdate_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cves +| +| +| List of `string` +| Use this field to update the CVEs of a deferral exception. +| + +| expiry +| +| +| <<V2ExceptionExpiry_CommonObjectReference,V2ExceptionExpiry>> +| +| + +|=== + +[id="V2DenyVulnerabilityExceptionResponse_CommonObjectReference"] +=== V2DenyVulnerabilityExceptionResponse + +[id="Fields-V2DenyVulnerabilityExceptionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| exception +| +| +| <<V2VulnerabilityException_CommonObjectReference,V2VulnerabilityException>> +| +| + +|=== + +[id="V2EmailNotifierConfiguration_CommonObjectReference"] +=== V2EmailNotifierConfiguration + +[id="Fields-V2EmailNotifierConfiguration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| notifierId +| +| +| String +| +| + +| mailingLists +| +| +| List of `string` +| +| + +| customSubject +| +| +| String +| +| + +| customBody +| +| +| String +| +| + +|=== + +[id="V2ExceptionExpiry_CommonObjectReference"] +=== V2ExceptionExpiry + +[id="Fields-V2ExceptionExpiry_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| expiryType +| +| +| <<ExceptionExpiryExpiryType_CommonObjectReference,ExceptionExpiryExpiryType>> +| +| TIME, ALL_CVE_FIXABLE, ANY_CVE_FIXABLE, + +| expiresOn +| +| +| Date +| Indicates the timestamp when the exception expires. This field is REQUIRED only if the expiry type is set to TIME. +| date-time + +|=== + +[id="V2ExceptionStatus_CommonObjectReference"] +=== V2ExceptionStatus + +Indicates the status of a request. + + - PENDING: Default request state. It indicates that the request has not been fulfilled and that an action (approve/deny) is required. + - APPROVED: Indicates that the request has been approved by the approver. + - DENIED: Indicates that the request has been denied by the approver. + - APPROVED_PENDING_UPDATE: Indicates that the original request was approved, but an update is still pending an approval or denial. + +[id="Fields-V2ExceptionStatus_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| PENDING +| APPROVED +| DENIED +| APPROVED_PENDING_UPDATE + +|=== + +[id="V2FailedCluster_CommonObjectReference"] +=== V2FailedCluster + +[id="Fields-V2FailedCluster_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| reason +| +| +| String +| +| + +| operatorVersion +| +| +| String +| +| + +|=== + +[id="V2FalsePositiveUpdate_CommonObjectReference"] +=== V2FalsePositiveUpdate + +[id="Fields-V2FalsePositiveUpdate_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cves +| +| +| List of `string` +| Use this field to update the CVEs of a false-positive exception. +| + +|=== + +[id="V2GetVulnerabilityExceptionResponse_CommonObjectReference"] +=== V2GetVulnerabilityExceptionResponse + +[id="Fields-V2GetVulnerabilityExceptionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| exception +| +| +| <<V2VulnerabilityException_CommonObjectReference,V2VulnerabilityException>> +| +| + +|=== + +[id="V2ListComplianceCheckClusterResponse_CommonObjectReference"] +=== V2ListComplianceCheckClusterResponse + +ListComplianceCheckClusterResponse provides stats per cluster + +[id="Fields-V2ListComplianceCheckClusterResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| checkResults +| +| +| List of <<V2ClusterCheckStatus_CommonObjectReference,V2ClusterCheckStatus>> +| +| + +| profileName +| +| +| String +| +| + +| checkName +| +| +| String +| +| + +| totalCount +| +| +| Integer +| +| int32 + +| controls +| +| +| List of <<V2ComplianceControl_CommonObjectReference,V2ComplianceControl>> +| +| + +|=== + +[id="V2ListComplianceCheckResultResponse_CommonObjectReference"] +=== V2ListComplianceCheckResultResponse + +[id="Fields-V2ListComplianceCheckResultResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| checkResults +| +| +| List of <<V2ComplianceCheckResult_CommonObjectReference,V2ComplianceCheckResult>> +| +| + +| profileName +| +| +| String +| +| + +| clusterId +| +| +| String +| +| + +| totalCount +| +| +| Integer +| +| int32 + +| lastScanTime +| +| +| Date +| +| date-time + +|=== + +[id="V2ListComplianceClusterOverallStatsResponse_CommonObjectReference"] +=== V2ListComplianceClusterOverallStatsResponse + +ListComplianceCheckScanStatsResponse provides stats per cluster + +[id="Fields-V2ListComplianceClusterOverallStatsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanStats +| +| +| List of <<V2ComplianceClusterOverallStats_CommonObjectReference,V2ComplianceClusterOverallStats>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceClusterProfileStatsResponse_CommonObjectReference"] +=== V2ListComplianceClusterProfileStatsResponse + +ListComplianceClusterProfileStatsResponse provides stats for the profiles within the scans + +[id="Fields-V2ListComplianceClusterProfileStatsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanStats +| +| +| List of <<V2ComplianceProfileScanStats_CommonObjectReference,V2ComplianceProfileScanStats>> +| +| + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceClusterScanStatsResponse_CommonObjectReference"] +=== V2ListComplianceClusterScanStatsResponse + +ListComplianceClusterScanStatsResponse provides stats for the clusters within the scans + +[id="Fields-V2ListComplianceClusterScanStatsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanStats +| +| +| List of <<V2ComplianceClusterScanStats_CommonObjectReference,V2ComplianceClusterScanStats>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceIntegrationsResponse_CommonObjectReference"] +=== V2ListComplianceIntegrationsResponse + +[id="Fields-V2ListComplianceIntegrationsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| integrations +| +| +| List of <<V2ComplianceIntegration_CommonObjectReference,V2ComplianceIntegration>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceProfileResults_CommonObjectReference"] +=== V2ListComplianceProfileResults + +ListComplianceProfileResults provides scan stats overview based on profile + +[id="Fields-V2ListComplianceProfileResults_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| profileResults +| +| +| List of <<V2ComplianceCheckResultStatusCount_CommonObjectReference,V2ComplianceCheckResultStatusCount>> +| +| + +| profileName +| +| +| String +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceProfileScanStatsResponse_CommonObjectReference"] +=== V2ListComplianceProfileScanStatsResponse + +ListComplianceProfileScanStatsResponse provides stats for the profiles within the scans + +[id="Fields-V2ListComplianceProfileScanStatsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanStats +| +| +| List of <<V2ComplianceProfileScanStats_CommonObjectReference,V2ComplianceProfileScanStats>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceProfileSummaryResponse_CommonObjectReference"] +=== V2ListComplianceProfileSummaryResponse + +ListComplianceProfileSummaryResponse provides a list of profiles summaries + +[id="Fields-V2ListComplianceProfileSummaryResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| profiles +| +| +| List of <<V2ComplianceProfileSummary_CommonObjectReference,V2ComplianceProfileSummary>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceProfilesResponse_CommonObjectReference"] +=== V2ListComplianceProfilesResponse + +ListComplianceProfilesResponse provides a list of profiles + +[id="Fields-V2ListComplianceProfilesResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| profiles +| +| +| List of <<V2ComplianceProfile_CommonObjectReference,V2ComplianceProfile>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceResultsResponse_CommonObjectReference"] +=== V2ListComplianceResultsResponse + +ListComplianceResultsResponse provides the complete scan results + +[id="Fields-V2ListComplianceResultsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| scanResults +| +| +| List of <<V2ComplianceCheckData_CommonObjectReference,V2ComplianceCheckData>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceScanConfigsClusterProfileResponse_CommonObjectReference"] +=== V2ListComplianceScanConfigsClusterProfileResponse + +[id="Fields-V2ListComplianceScanConfigsClusterProfileResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| clusterId +| +| +| String +| +| + +| clusterName +| +| +| String +| +| + +| profiles +| +| +| List of <<V2ComplianceProfileSummary_CommonObjectReference,V2ComplianceProfileSummary>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceScanConfigsProfileResponse_CommonObjectReference"] +=== V2ListComplianceScanConfigsProfileResponse + +[id="Fields-V2ListComplianceScanConfigsProfileResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| profiles +| +| +| List of <<V2ComplianceProfileSummary_CommonObjectReference,V2ComplianceProfileSummary>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListComplianceScanConfigurationsResponse_CommonObjectReference"] +=== V2ListComplianceScanConfigurationsResponse + +[id="Fields-V2ListComplianceScanConfigurationsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| configurations +| +| +| List of <<V2ComplianceScanConfigurationStatus_CommonObjectReference,V2ComplianceScanConfigurationStatus>> +| +| + +| totalCount +| +| +| Integer +| +| int32 + +|=== + +[id="V2ListReportConfigurationsResponse_CommonObjectReference"] +=== V2ListReportConfigurationsResponse + +[id="Fields-V2ListReportConfigurationsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfigs +| +| +| List of <<V2ReportConfiguration_CommonObjectReference,V2ReportConfiguration>> +| +| + +|=== + +[id="V2ListVulnerabilityExceptionsResponse_CommonObjectReference"] +=== V2ListVulnerabilityExceptionsResponse + +[id="Fields-V2ListVulnerabilityExceptionsResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| exceptions +| +| +| List of <<V2VulnerabilityException_CommonObjectReference,V2VulnerabilityException>> +| +| + +|=== + +[id="V2NotificationMethod_CommonObjectReference"] +=== V2NotificationMethod + +[id="Fields-V2NotificationMethod_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| EMAIL +| DOWNLOAD + +|=== + +[id="V2NotifierConfiguration_CommonObjectReference"] +=== V2NotifierConfiguration + +[id="Fields-V2NotifierConfiguration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| emailConfig +| +| +| <<V2EmailNotifierConfiguration_CommonObjectReference,V2EmailNotifierConfiguration>> +| +| + +| notifierName +| +| +| String +| +| + +|=== + +[id="V2Pagination_CommonObjectReference"] +=== V2Pagination + +[id="Fields-V2Pagination_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| limit +| +| +| Integer +| +| int32 + +| offset +| +| +| Integer +| +| int32 + +| sortOption +| +| +| <<V2SortOption_CommonObjectReference,V2SortOption>> +| +| + +| sortOptions +| +| +| List of <<V2SortOption_CommonObjectReference,V2SortOption>> +| This field is under development. It is not supported on any REST APIs. +| + +|=== + +[id="V2RawQuery_CommonObjectReference"] +=== V2RawQuery + +RawQuery represents the search query string. +The format of the query string is "<field name>:<value,value,...>+<field name>:<value, value,...>+..." +For example: +To search for deployments named "central" and "sensor" in the namespace "stackrox", the query string would be +"Deployment:central,sensor+Namespace:stackrox" +RawQuery is used in ListAPIs to search for a particular object. + +[id="Fields-V2RawQuery_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| query +| +| +| String +| +| + +| pagination +| +| +| <<V2Pagination_CommonObjectReference,V2Pagination>> +| +| + +|=== + +[id="V2ReportConfiguration_CommonObjectReference"] +=== V2ReportConfiguration + +[id="Fields-V2ReportConfiguration_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| type +| +| +| <<ReportConfigurationReportType_CommonObjectReference,ReportConfigurationReportType>> +| +| VULNERABILITY, + +| vulnReportFilters +| +| +| <<V2VulnerabilityReportFilters_CommonObjectReference,V2VulnerabilityReportFilters>> +| +| + +| schedule +| +| +| <<V2ReportSchedule_CommonObjectReference,V2ReportSchedule>> +| +| + +| resourceScope +| +| +| <<V2ResourceScope_CommonObjectReference,V2ResourceScope>> +| +| + +| notifiers +| +| +| List of <<V2NotifierConfiguration_CommonObjectReference,V2NotifierConfiguration>> +| +| + +|=== + +[id="V2ReportHistoryResponse_CommonObjectReference"] +=== V2ReportHistoryResponse + +[id="Fields-V2ReportHistoryResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportSnapshots +| +| +| List of <<V2ReportSnapshot_CommonObjectReference,V2ReportSnapshot>> +| +| + +|=== + +[id="V2ReportSchedule_CommonObjectReference"] +=== V2ReportSchedule + +[id="Fields-V2ReportSchedule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| intervalType +| +| +| <<V2ReportScheduleIntervalType_CommonObjectReference,V2ReportScheduleIntervalType>> +| +| UNSET, WEEKLY, MONTHLY, + +| hour +| +| +| Integer +| +| int32 + +| minute +| +| +| Integer +| +| int32 + +| daysOfWeek +| +| +| <<V2ReportScheduleDaysOfWeek_CommonObjectReference,V2ReportScheduleDaysOfWeek>> +| +| + +| daysOfMonth +| +| +| <<V2ReportScheduleDaysOfMonth_CommonObjectReference,V2ReportScheduleDaysOfMonth>> +| +| + +|=== + +[id="V2ReportScheduleDaysOfMonth_CommonObjectReference"] +=== V2ReportScheduleDaysOfMonth + +1 for 1st, 2 for 2nd .... 31 for 31st + +[id="Fields-V2ReportScheduleDaysOfMonth_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| days +| +| +| List of `integer` +| +| int32 + +|=== + +[id="V2ReportScheduleDaysOfWeek_CommonObjectReference"] +=== V2ReportScheduleDaysOfWeek + +Sunday = 0, Monday = 1, .... Saturday = 6 + +[id="Fields-V2ReportScheduleDaysOfWeek_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| days +| +| +| List of `integer` +| +| int32 + +|=== + +[id="V2ReportScheduleIntervalType_CommonObjectReference"] +=== V2ReportScheduleIntervalType + +[id="Fields-V2ReportScheduleIntervalType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| WEEKLY +| MONTHLY + +|=== + +[id="V2ReportSnapshot_CommonObjectReference"] +=== V2ReportSnapshot + +[id="Fields-V2ReportSnapshot_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfigId +| +| +| String +| +| + +| reportJobId +| +| +| String +| +| + +| name +| +| +| String +| +| + +| description +| +| +| String +| +| + +| vulnReportFilters +| +| +| <<V2VulnerabilityReportFilters_CommonObjectReference,V2VulnerabilityReportFilters>> +| +| + +| collectionSnapshot +| +| +| <<V2CollectionSnapshot_CommonObjectReference,V2CollectionSnapshot>> +| +| + +| schedule +| +| +| <<V2ReportSchedule_CommonObjectReference,V2ReportSchedule>> +| +| + +| reportStatus +| +| +| <<V2ReportStatus_CommonObjectReference,V2ReportStatus>> +| +| + +| notifiers +| +| +| List of <<V2NotifierConfiguration_CommonObjectReference,V2NotifierConfiguration>> +| +| + +| user +| +| +| <<V2SlimUser_CommonObjectReference,V2SlimUser>> +| +| + +| isDownloadAvailable +| +| +| Boolean +| +| + +|=== + +[id="V2ReportStatus_CommonObjectReference"] +=== V2ReportStatus + +[id="Fields-V2ReportStatus_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| runState +| +| +| <<V2ReportStatusRunState_CommonObjectReference,V2ReportStatusRunState>> +| +| WAITING, PREPARING, GENERATED, DELIVERED, FAILURE, + +| completedAt +| +| +| Date +| +| date-time + +| errorMsg +| +| +| String +| +| + +| reportRequestType +| +| +| <<V2ReportStatusReportMethod_CommonObjectReference,V2ReportStatusReportMethod>> +| +| ON_DEMAND, SCHEDULED, + +| reportNotificationMethod +| +| +| <<V2NotificationMethod_CommonObjectReference,V2NotificationMethod>> +| +| EMAIL, DOWNLOAD, + +|=== + +[id="V2ReportStatusReportMethod_CommonObjectReference"] +=== V2ReportStatusReportMethod + +[id="Fields-V2ReportStatusReportMethod_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| ON_DEMAND +| SCHEDULED + +|=== + +[id="V2ReportStatusResponse_CommonObjectReference"] +=== V2ReportStatusResponse + +[id="Fields-V2ReportStatusResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| status +| +| +| <<V2ReportStatus_CommonObjectReference,V2ReportStatus>> +| +| + +|=== + +[id="V2ReportStatusRunState_CommonObjectReference"] +=== V2ReportStatusRunState + +[id="Fields-V2ReportStatusRunState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| WAITING +| PREPARING +| GENERATED +| DELIVERED +| FAILURE + +|=== + +[id="V2ResourceScope_CommonObjectReference"] +=== V2ResourceScope + +[id="Fields-V2ResourceScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| collectionScope +| +| +| <<V2CollectionReference_CommonObjectReference,V2CollectionReference>> +| +| + +|=== + +[id="V2RunReportRequest_CommonObjectReference"] +=== V2RunReportRequest + +[id="Fields-V2RunReportRequest_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfigId +| +| +| String +| +| + +| reportNotificationMethod +| +| +| <<V2NotificationMethod_CommonObjectReference,V2NotificationMethod>> +| +| EMAIL, DOWNLOAD, + +|=== + +[id="V2RunReportResponse_CommonObjectReference"] +=== V2RunReportResponse + +[id="Fields-V2RunReportResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| reportConfigId +| +| +| String +| +| + +| reportId +| +| +| String +| +| + +|=== + +[id="V2Schedule_CommonObjectReference"] +=== V2Schedule + +[id="Fields-V2Schedule_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| intervalType +| +| +| <<V2ScheduleIntervalType_CommonObjectReference,V2ScheduleIntervalType>> +| +| UNSET, WEEKLY, MONTHLY, DAILY, + +| hour +| +| +| Integer +| +| int32 + +| minute +| +| +| Integer +| +| int32 + +| daysOfWeek +| +| +| <<V2ScheduleDaysOfWeek_CommonObjectReference,V2ScheduleDaysOfWeek>> +| +| + +| daysOfMonth +| +| +| <<V2ScheduleDaysOfMonth_CommonObjectReference,V2ScheduleDaysOfMonth>> +| +| + +|=== + +[id="V2ScheduleDaysOfMonth_CommonObjectReference"] +=== V2ScheduleDaysOfMonth + +1 for 1st, 2 for 2nd .... 31 for 31st + +[id="Fields-V2ScheduleDaysOfMonth_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| days +| +| +| List of `integer` +| +| int32 + +|=== + +[id="V2ScheduleDaysOfWeek_CommonObjectReference"] +=== V2ScheduleDaysOfWeek + +Sunday = 0, Monday = 1, .... Saturday = 6 + +[id="Fields-V2ScheduleDaysOfWeek_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| days +| +| +| List of `integer` +| +| int32 + +|=== + +[id="V2ScheduleIntervalType_CommonObjectReference"] +=== V2ScheduleIntervalType + +[id="Fields-V2ScheduleIntervalType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNSET +| WEEKLY +| MONTHLY +| DAILY + +|=== + +[id="V2SlimUser_CommonObjectReference"] +=== V2SlimUser + +[id="Fields-V2SlimUser_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +|=== + +[id="V2SortOption_CommonObjectReference"] +=== V2SortOption + +[id="Fields-V2SortOption_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| field +| +| +| String +| +| + +| reversed +| +| +| Boolean +| +| + +| aggregateBy +| +| +| <<V2AggregateBy_CommonObjectReference,V2AggregateBy>> +| +| + +|=== + +[id="V2UpdateVulnerabilityExceptionResponse_CommonObjectReference"] +=== V2UpdateVulnerabilityExceptionResponse + +[id="Fields-V2UpdateVulnerabilityExceptionResponse_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| exception +| +| +| <<V2VulnerabilityException_CommonObjectReference,V2VulnerabilityException>> +| +| + +|=== + +[id="V2VulnerabilityException_CommonObjectReference"] +=== V2VulnerabilityException + +Next available tag: 16 +VulnerabilityException represents a vulnerability exception such as deferral and false-positive. + +[id="Fields-V2VulnerabilityException_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| Auto-generated display name of the exception. +| + +| targetState +| +| +| <<V2VulnerabilityState_CommonObjectReference,V2VulnerabilityState>> +| +| OBSERVED, DEFERRED, FALSE_POSITIVE, + +| status +| +| +| <<V2ExceptionStatus_CommonObjectReference,V2ExceptionStatus>> +| +| PENDING, APPROVED, DENIED, APPROVED_PENDING_UPDATE, + +| expired +| +| +| Boolean +| If set to `true`, this field indicates that the exception is no longer enforced. +| + +| requester +| +| +| <<V2SlimUser_CommonObjectReference,V2SlimUser>> +| +| + +| approvers +| +| +| List of <<V2SlimUser_CommonObjectReference,V2SlimUser>> +| +| + +| createdAt +| +| +| Date +| +| date-time + +| lastUpdated +| +| +| Date +| +| date-time + +| comments +| +| +| List of <<V2Comment_CommonObjectReference,V2Comment>> +| +| + +| scope +| +| +| <<VulnerabilityExceptionScope_CommonObjectReference,VulnerabilityExceptionScope>> +| +| + +| deferralRequest +| +| +| <<V2DeferralRequest_CommonObjectReference,V2DeferralRequest>> +| +| + +| falsePositiveRequest +| +| +| Object +| +| + +| cves +| +| +| List of `string` +| Indicates the CVEs to which the exception applies. +| + +| deferralUpdate +| +| +| <<V2DeferralUpdate_CommonObjectReference,V2DeferralUpdate>> +| +| + +| falsePositiveUpdate +| +| +| <<V2FalsePositiveUpdate_CommonObjectReference,V2FalsePositiveUpdate>> +| +| + +|=== + +[id="V2VulnerabilityReportFilters_CommonObjectReference"] +=== V2VulnerabilityReportFilters + +[id="Fields-V2VulnerabilityReportFilters_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| fixability +| +| +| <<VulnerabilityReportFiltersFixability_CommonObjectReference,VulnerabilityReportFiltersFixability>> +| +| BOTH, FIXABLE, NOT_FIXABLE, + +| severities +| +| +| List of <<VulnerabilityReportFiltersVulnerabilitySeverity_CommonObjectReference,VulnerabilityReportFiltersVulnerabilitySeverity>> +| +| + +| imageTypes +| +| +| List of <<VulnerabilityReportFiltersImageType_CommonObjectReference,VulnerabilityReportFiltersImageType>> +| +| + +| allVuln +| +| +| Boolean +| +| + +| sinceLastSentScheduledReport +| +| +| Boolean +| +| + +| sinceStartDate +| +| +| Date +| +| date-time + +| includeNvdCvss +| +| +| Boolean +| +| + +| includeEpssProbability +| +| +| Boolean +| +| + +| includeAdvisory +| +| +| Boolean +| +| + +|=== + +[id="V2VulnerabilityState_CommonObjectReference"] +=== V2VulnerabilityState + +VulnerabilityState are the possible applicable to CVE. By default all vulnerabilities are in observed state. + + - OBSERVED: This is the default state and indicates that the CVE is not excluded from policy evaluation and risk evaluation. + +[Default state] + - DEFERRED: Indicates that the vulnerability is deferred. A deferred CVE is excluded from policy evaluation and risk evaluation. + - FALSE_POSITIVE: Indicates that the vulnerability is a false-positive. A false-positive CVE is excluded from policy evaluation and risk evaluation. + +[id="Fields-V2VulnerabilityState_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| OBSERVED +| DEFERRED +| FALSE_POSITIVE + +|=== + +[id="V4Contents_CommonObjectReference"] +=== V4Contents + +[id="Fields-V4Contents_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| packages +| +| +| List of <<V4Package_CommonObjectReference,V4Package>> +| +| + +| distributions +| +| +| List of <<V4Distribution_CommonObjectReference,V4Distribution>> +| +| + +| repositories +| +| +| List of <<V4Repository_CommonObjectReference,V4Repository>> +| +| + +| environments +| +| +| Map of <<EnvironmentList_CommonObjectReference,EnvironmentList>> +| +| + +|=== + +[id="V4Distribution_CommonObjectReference"] +=== V4Distribution + +[id="Fields-V4Distribution_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| did +| +| +| String +| +| + +| name +| +| +| String +| +| + +| version +| +| +| String +| +| + +| versionCodeName +| +| +| String +| +| + +| versionId +| +| +| String +| +| + +| arch +| +| +| String +| +| + +| cpe +| +| +| String +| +| + +| prettyName +| +| +| String +| +| + +|=== + +[id="V4Environment_CommonObjectReference"] +=== V4Environment + +Environment describes the surrounding environment a package was +discovered in. + +[id="Fields-V4Environment_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| packageDb +| +| +| String +| +| + +| introducedIn +| +| +| String +| +| + +| distributionId +| +| +| String +| +| + +| repositoryIds +| +| +| List of `string` +| +| + +|=== + +[id="V4NormalizedVersion_CommonObjectReference"] +=== V4NormalizedVersion + +[id="Fields-V4NormalizedVersion_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| kind +| +| +| String +| +| + +| v +| +| +| List of `integer` +| +| int32 + +|=== + +[id="V4Package_CommonObjectReference"] +=== V4Package + +[id="Fields-V4Package_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| version +| +| +| String +| +| + +| normalizedVersion +| +| +| <<V4NormalizedVersion_CommonObjectReference,V4NormalizedVersion>> +| +| + +| fixedInVersion +| +| +| String +| +| + +| kind +| +| +| String +| +| + +| source +| +| +| <<V4Package_CommonObjectReference,V4Package>> +| +| + +| packageDb +| +| +| String +| +| + +| repositoryHint +| +| +| String +| +| + +| module +| +| +| String +| +| + +| arch +| +| +| String +| +| + +| cpe +| +| +| String +| +| + +|=== + +[id="V4Repository_CommonObjectReference"] +=== V4Repository + +[id="Fields-V4Repository_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| id +| +| +| String +| +| + +| name +| +| +| String +| +| + +| key +| +| +| String +| +| + +| uri +| +| +| String +| +| + +| cpe +| +| +| String +| +| + +|=== + +[id="ViolationKeyValueAttrs_CommonObjectReference"] +=== ViolationKeyValueAttrs + +[id="Fields-ViolationKeyValueAttrs_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| attrs +| +| +| List of <<KeyValueAttrsKeyValueAttr_CommonObjectReference,KeyValueAttrsKeyValueAttr>> +| +| + +|=== + +[id="ViolationNetworkFlowInfo_CommonObjectReference"] +=== ViolationNetworkFlowInfo + +[id="Fields-ViolationNetworkFlowInfo_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| protocol +| +| +| <<StorageL4Protocol_CommonObjectReference,StorageL4Protocol>> +| +| L4_PROTOCOL_UNKNOWN, L4_PROTOCOL_TCP, L4_PROTOCOL_UDP, L4_PROTOCOL_ICMP, L4_PROTOCOL_RAW, L4_PROTOCOL_SCTP, L4_PROTOCOL_ANY, + +| source +| +| +| <<NetworkFlowInfoEntity_CommonObjectReference,NetworkFlowInfoEntity>> +| +| + +| destination +| +| +| <<NetworkFlowInfoEntity_CommonObjectReference,NetworkFlowInfoEntity>> +| +| + +|=== + +[id="VolumeMountPropagation_CommonObjectReference"] +=== VolumeMountPropagation + +[id="Fields-VolumeMountPropagation_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| NONE +| HOST_TO_CONTAINER +| BIDIRECTIONAL + +|=== + +[id="VulnerabilityExceptionScope_CommonObjectReference"] +=== VulnerabilityExceptionScope + +[id="Fields-VulnerabilityExceptionScope_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| imageScope +| +| +| <<ScopeImage_CommonObjectReference,ScopeImage>> +| +| + +|=== + +[id="VulnerabilityExceptionServiceApproveVulnerabilityExceptionBody_CommonObjectReference"] +=== VulnerabilityExceptionServiceApproveVulnerabilityExceptionBody + +[id="Fields-VulnerabilityExceptionServiceApproveVulnerabilityExceptionBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| comment +| +| +| String +| REQUIRED. The rationale for approving the exception. +| + +|=== + +[id="VulnerabilityExceptionServiceDenyVulnerabilityExceptionBody_CommonObjectReference"] +=== VulnerabilityExceptionServiceDenyVulnerabilityExceptionBody + +[id="Fields-VulnerabilityExceptionServiceDenyVulnerabilityExceptionBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| comment +| +| +| String +| REQUIRED. The rationale for denying the exception. +| + +|=== + +[id="VulnerabilityExceptionServiceUpdateVulnerabilityExceptionBody_CommonObjectReference"] +=== VulnerabilityExceptionServiceUpdateVulnerabilityExceptionBody + +[id="Fields-VulnerabilityExceptionServiceUpdateVulnerabilityExceptionBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| comment +| +| +| String +| REQUIRED. The rationale for updating the exception. +| + +| deferralUpdate +| +| +| <<V2DeferralUpdate_CommonObjectReference,V2DeferralUpdate>> +| +| + +| falsePositiveUpdate +| +| +| <<V2FalsePositiveUpdate_CommonObjectReference,V2FalsePositiveUpdate>> +| +| + +|=== + +[id="VulnerabilityReportFiltersFixability_CommonObjectReference"] +=== VulnerabilityReportFiltersFixability + +[id="Fields-VulnerabilityReportFiltersFixability_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| BOTH +| FIXABLE +| NOT_FIXABLE + +|=== + +[id="VulnerabilityReportFiltersImageType_CommonObjectReference"] +=== VulnerabilityReportFiltersImageType + +[id="Fields-VulnerabilityReportFiltersImageType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| DEPLOYED +| WATCHED + +|=== + +[id="VulnerabilityReportFiltersVulnerabilitySeverity_CommonObjectReference"] +=== VulnerabilityReportFiltersVulnerabilitySeverity + +[id="Fields-VulnerabilityReportFiltersVulnerabilitySeverity_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| UNKNOWN_VULNERABILITY_SEVERITY +| LOW_VULNERABILITY_SEVERITY +| MODERATE_VULNERABILITY_SEVERITY +| IMPORTANT_VULNERABILITY_SEVERITY +| CRITICAL_VULNERABILITY_SEVERITY + +|=== + +[id="VulnerabilityRequestCVEs_CommonObjectReference"] +=== VulnerabilityRequestCVEs + +[id="Fields-VulnerabilityRequestCVEs_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| cves +| +| +| List of `string` +| These are (NVD) vulnerability identifiers, `cve` field of `storage.CVE`, and *not* the `id` field. For example, CVE-2021-44832. +| + +|=== + +[id="VulnerabilityRequestScopeImage_CommonObjectReference"] +=== VulnerabilityRequestScopeImage + +[id="Fields-VulnerabilityRequestScopeImage_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| registry +| +| +| String +| +| + +| remote +| +| +| String +| +| + +| tag +| +| +| String +| +| + +|=== + +[id="VulnerabilityRequestServiceApproveVulnerabilityRequestBody_CommonObjectReference"] +=== VulnerabilityRequestServiceApproveVulnerabilityRequestBody + +[id="Fields-VulnerabilityRequestServiceApproveVulnerabilityRequestBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| comment +| +| +| String +| +| + +|=== + +[id="VulnerabilityRequestServiceDenyVulnerabilityRequestBody_CommonObjectReference"] +=== VulnerabilityRequestServiceDenyVulnerabilityRequestBody + +[id="Fields-VulnerabilityRequestServiceDenyVulnerabilityRequestBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| comment +| +| +| String +| +| + +|=== + +[id="VulnerabilityRequestServiceUpdateVulnerabilityRequestBody_CommonObjectReference"] +=== VulnerabilityRequestServiceUpdateVulnerabilityRequestBody + +[id="Fields-VulnerabilityRequestServiceUpdateVulnerabilityRequestBody_CommonObjectReference"] +[cols="2,1,1,2,4,1"] +|=== +| Field Name| Required| Nullable | Type| Description | Format + +| comment +| +| +| String +| +| + +| expiry +| +| +| <<StorageRequestExpiry_CommonObjectReference,StorageRequestExpiry>> +| +| + +|=== + +[id="WatchImageResponseErrorType_CommonObjectReference"] +=== WatchImageResponseErrorType + +[id="Fields-WatchImageResponseErrorType_CommonObjectReference"] +[cols="1"] +|=== +| Enum Values + +| NO_ERROR +| INVALID_IMAGE_NAME +| NO_VALID_INTEGRATION +| SCAN_FAILED + +|=== diff --git a/rest_api/ComplianceIntegrationService/ComplianceIntegrationService.adoc b/rest_api/ComplianceIntegrationService/ComplianceIntegrationService.adoc new file mode 100644 index 000000000000..26108e70e46d --- /dev/null +++ b/rest_api/ComplianceIntegrationService/ComplianceIntegrationService.adoc @@ -0,0 +1,98 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ComplianceIntegrationService"] += Compliance Integration Service +:toc: macro +:toc-title: + +toc::[] + +:context: ComplianceIntegrationService + +[id="ListComplianceIntegrations_ComplianceIntegrationService"] +== ListComplianceIntegrations + +`GET /v2/compliance/integrations` + +ListComplianceIntegrations lists all the compliance operator metadata for the secured clusters + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceIntegrationsResponse_CommonObjectReference[V2ListComplianceIntegrationsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceIntegrationsResponse_CommonObjectReference[V2ListComplianceIntegrationsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ComplianceManagementService/ComplianceManagementService.adoc b/rest_api/ComplianceManagementService/ComplianceManagementService.adoc new file mode 100644 index 000000000000..21dbb718afbd --- /dev/null +++ b/rest_api/ComplianceManagementService/ComplianceManagementService.adoc @@ -0,0 +1,178 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ComplianceManagementService"] += Compliance Management Service +:toc: macro +:toc-title: + +toc::[] + +:context: ComplianceManagementService + +[id="GetRecentRuns_ComplianceManagementService"] +== GetRecentRuns + +`GET /v1/complianceManagement/runs` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| - +| null +| + +| standardId +| +| - +| null +| + +| since +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetRecentComplianceRunsResponse_CommonObjectReference[V1GetRecentComplianceRunsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetRecentComplianceRunsResponse_CommonObjectReference[V1GetRecentComplianceRunsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetRunStatuses_ComplianceManagementService"] +== GetRunStatuses + +`GET /v1/compliancemanagement/runstatuses` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| runIds +| `String` +| - +| null +| + +| latest +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetComplianceRunStatusesResponse_CommonObjectReference[V1GetComplianceRunStatusesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetComplianceRunStatusesResponse_CommonObjectReference[V1GetComplianceRunStatusesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TriggerRuns_ComplianceManagementService"] +== TriggerRuns + +`POST /v1/compliancemanagement/runs` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1TriggerComplianceRunsRequest_CommonObjectReference[V1TriggerComplianceRunsRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1TriggerComplianceRunsResponse_CommonObjectReference[V1TriggerComplianceRunsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1TriggerComplianceRunsResponse_CommonObjectReference[V1TriggerComplianceRunsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ComplianceProfileService/ComplianceProfileService.adoc b/rest_api/ComplianceProfileService/ComplianceProfileService.adoc new file mode 100644 index 000000000000..b7e51e7a05f5 --- /dev/null +++ b/rest_api/ComplianceProfileService/ComplianceProfileService.adoc @@ -0,0 +1,250 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ComplianceProfileService"] += Compliance Profile Service +:toc: macro +:toc-title: + +toc::[] + +:context: ComplianceProfileService + +[id="GetComplianceProfile_ComplianceProfileService"] +== GetComplianceProfile + +`GET /v2/compliance/profile/{id}` + +GetComplianceProfile retrieves the specified compliance profile + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceProfile_CommonObjectReference[V2ComplianceProfile] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceProfile_CommonObjectReference[V2ComplianceProfile] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="ListComplianceProfiles_ComplianceProfileService"] +== ListComplianceProfiles + +`GET /v2/compliance/profiles/cluster` + +ListComplianceProfiles returns profiles matching given request + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| - +| null +| + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfilesResponse_CommonObjectReference[V2ListComplianceProfilesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfilesResponse_CommonObjectReference[V2ListComplianceProfilesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="ListProfileSummaries_ComplianceProfileService"] +== ListProfileSummaries + +`GET /v2/compliance/profiles/summary` + +ListProfileSummaries returns profiles matching each cluster and the given query + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterIds +| `String` +| - +| null +| + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileSummaryResponse_CommonObjectReference[V2ListComplianceProfileSummaryResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileSummaryResponse_CommonObjectReference[V2ListComplianceProfileSummaryResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ComplianceResultsService/ComplianceResultsService.adoc b/rest_api/ComplianceResultsService/ComplianceResultsService.adoc new file mode 100644 index 000000000000..545673a436de --- /dev/null +++ b/rest_api/ComplianceResultsService/ComplianceResultsService.adoc @@ -0,0 +1,678 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ComplianceResultsService"] += Compliance Results Service +:toc: macro +:toc-title: + +toc::[] + +:context: ComplianceResultsService + +[id="GetComplianceProfileCheckDetails_ComplianceResultsService"] +== GetComplianceProfileCheckDetails + +`GET /v2/compliance/scan/results/profiles/{profileName}/checks/{checkName}/details` + +GetComplianceProfileCheckDetails + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| profileName +| +| X +| null +| + +| checkName +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceClusterCheckStatus_CommonObjectReference[V2ComplianceClusterCheckStatus] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceClusterCheckStatus_CommonObjectReference[V2ComplianceClusterCheckStatus] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceProfileCheckResult_ComplianceResultsService"] +== GetComplianceProfileCheckResult + +`GET /v2/compliance/scan/results/profiles/{profileName}/checks/{checkName}` + +GetComplianceProfileCheckResult lists status of a check per cluster + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| profileName +| +| X +| null +| + +| checkName +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceCheckClusterResponse_CommonObjectReference[V2ListComplianceCheckClusterResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceCheckClusterResponse_CommonObjectReference[V2ListComplianceCheckClusterResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceProfileClusterResults_ComplianceResultsService"] +== GetComplianceProfileClusterResults + +`GET /v2/compliance/scan/results/profiles/{profileName}/clusters/{clusterId}` + +GetComplianceProfileClusterResults lists check results for a specific profile on a specific cluster + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| profileName +| +| X +| null +| + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceCheckResultResponse_CommonObjectReference[V2ListComplianceCheckResultResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceCheckResultResponse_CommonObjectReference[V2ListComplianceCheckResultResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceProfileResults_ComplianceResultsService"] +== GetComplianceProfileResults + +`GET /v2/compliance/scan/results/profiles/{profileName}/checks` + +GetComplianceProfileResults retrieves the most recent compliance operator scan results for the specified query Optional RawQuery query fields can be combined. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| profileName +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileResults_CommonObjectReference[V2ListComplianceProfileResults] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileResults_CommonObjectReference[V2ListComplianceProfileResults] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceScanCheckResult_ComplianceResultsService"] +== GetComplianceScanCheckResult + +`GET /v2/compliance/scan/result/{id}` + +GetComplianceScanCheckResult returns the specific result by ID + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceClusterCheckStatus_CommonObjectReference[V2ComplianceClusterCheckStatus] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceClusterCheckStatus_CommonObjectReference[V2ComplianceClusterCheckStatus] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceScanConfigurationResults_ComplianceResultsService"] +== GetComplianceScanConfigurationResults + +`GET /v2/compliance/scan/results/{scanConfigName}` + +GetComplianceScanConfigurationResults retrieves the most recent compliance operator scan results for the specified query Optional RawQuery query fields can be combined. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| scanConfigName +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceResultsResponse_CommonObjectReference[V2ListComplianceResultsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceResultsResponse_CommonObjectReference[V2ListComplianceResultsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceScanResults_ComplianceResultsService"] +== GetComplianceScanResults + +`GET /v2/compliance/scan/results` + +GetComplianceScanResults retrieves the most recent compliance operator scan results for the specified query Optional RawQuery query fields can be combined. Commonly used ones include but are not limited to - scan: id(s) of the compliance scan - cluster: id(s) of the cluster - profile: id(s) of the profile + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceResultsResponse_CommonObjectReference[V2ListComplianceResultsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceResultsResponse_CommonObjectReference[V2ListComplianceResultsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ComplianceResultsStatsService/ComplianceResultsStatsService.adoc b/rest_api/ComplianceResultsStatsService/ComplianceResultsStatsService.adoc new file mode 100644 index 000000000000..634996a71000 --- /dev/null +++ b/rest_api/ComplianceResultsStatsService/ComplianceResultsStatsService.adoc @@ -0,0 +1,700 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ComplianceResultsStatsService"] += Compliance Results Stats Service +:toc: macro +:toc-title: + +toc::[] + +:context: ComplianceResultsStatsService + +[id="GetComplianceClusterScanStats_ComplianceResultsStatsService"] +== GetComplianceClusterScanStats + +`GET /v2/compliance/stats/configurations/clusters/{clusterId}` + +GetComplianceClusterScanStats lists the current scan stats for a cluster for each scan configuration + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceClusterScanStatsResponse_CommonObjectReference[V2ListComplianceClusterScanStatsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceClusterScanStatsResponse_CommonObjectReference[V2ListComplianceClusterScanStatsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceClusterStats_ComplianceResultsStatsService"] +== GetComplianceClusterStats + +`GET /v2/compliance/scan/stats/profiles/{profileName}/clusters` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| profileName +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceClusterOverallStatsResponse_CommonObjectReference[V2ListComplianceClusterOverallStatsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceClusterOverallStatsResponse_CommonObjectReference[V2ListComplianceClusterOverallStatsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceOverallClusterStats_ComplianceResultsStatsService"] +== GetComplianceOverallClusterStats + +`GET /v2/compliance/scan/stats/overall/cluster` + +Deprecated in favor of GetComplianceClusterStats + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceClusterOverallStatsResponse_CommonObjectReference[V2ListComplianceClusterOverallStatsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceClusterOverallStatsResponse_CommonObjectReference[V2ListComplianceClusterOverallStatsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceProfileCheckStats_ComplianceResultsStatsService"] +== GetComplianceProfileCheckStats + +`GET /v2/compliance/scan/stats/profiles/{profileName}/checks/{checkName}` + +GetComplianceProfileCheckStats lists current stats for a specific cluster check + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| profileName +| +| X +| null +| + +| checkName +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileResults_CommonObjectReference[V2ListComplianceProfileResults] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileResults_CommonObjectReference[V2ListComplianceProfileResults] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceProfileStats_ComplianceResultsStatsService"] +== GetComplianceProfileStats + +`GET /v2/compliance/scan/stats/profiles/{profileName}` + +GetComplianceProfileStats lists current scan stats grouped by profile Optional RawQuery query fields can be combined. Commonly used ones include but are not limited to - scan: id(s) of the compliance scan - cluster: id(s) of the cluster - profile: id(s) of the profile + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| profileName +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileScanStatsResponse_CommonObjectReference[V2ListComplianceProfileScanStatsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileScanStatsResponse_CommonObjectReference[V2ListComplianceProfileScanStatsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceProfilesClusterStats_ComplianceResultsStatsService"] +== GetComplianceProfilesClusterStats + +`GET /v2/compliance/scan/stats/profiles/clusters/{clusterId}` + +GetComplianceProfilesClusterStats lists cluster stats grouped by profile + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceClusterProfileStatsResponse_CommonObjectReference[V2ListComplianceClusterProfileStatsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceClusterProfileStatsResponse_CommonObjectReference[V2ListComplianceClusterProfileStatsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceProfilesStats_ComplianceResultsStatsService"] +== GetComplianceProfilesStats + +`GET /v2/compliance/scan/stats/profiles` + +GetComplianceProfileScanStats lists current scan stats grouped by profile Optional RawQuery query fields can be combined. Commonly used ones include but are not limited to - scan: id(s) of the compliance scan - cluster: id(s) of the cluster - profile: id(s) of the profile + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileScanStatsResponse_CommonObjectReference[V2ListComplianceProfileScanStatsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceProfileScanStatsResponse_CommonObjectReference[V2ListComplianceProfileScanStatsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ComplianceRuleService/ComplianceRuleService.adoc b/rest_api/ComplianceRuleService/ComplianceRuleService.adoc new file mode 100644 index 000000000000..4b537e47271d --- /dev/null +++ b/rest_api/ComplianceRuleService/ComplianceRuleService.adoc @@ -0,0 +1,112 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ComplianceRuleService"] += Compliance Rule Service +:toc: macro +:toc-title: + +toc::[] + +:context: ComplianceRuleService + +[id="GetComplianceRule_ComplianceRuleService"] +== GetComplianceRule + +`GET /v2/compliance/rule/summary/{ruleName}` + +GetComplianceRule returns rule matching given request + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| ruleName +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceRule_CommonObjectReference[V2ComplianceRule] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceRule_CommonObjectReference[V2ComplianceRule] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ComplianceScanConfigurationService/ComplianceScanConfigurationService.adoc b/rest_api/ComplianceScanConfigurationService/ComplianceScanConfigurationService.adoc new file mode 100644 index 000000000000..060a924f5cf0 --- /dev/null +++ b/rest_api/ComplianceScanConfigurationService/ComplianceScanConfigurationService.adoc @@ -0,0 +1,870 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ComplianceScanConfigurationService"] += Compliance Scan Configuration Service +:toc: macro +:toc-title: + +toc::[] + +:context: ComplianceScanConfigurationService + +[id="CreateComplianceScanConfiguration_ComplianceScanConfigurationService"] +== CreateComplianceScanConfiguration + +`POST /v2/compliance/scan/configurations` + +CreateComplianceScanConfiguration creates a compliance scan configuration + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceScanConfiguration_CommonObjectReference[V2ComplianceScanConfiguration] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceScanConfiguration_CommonObjectReference[V2ComplianceScanConfiguration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceScanConfiguration_CommonObjectReference[V2ComplianceScanConfiguration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="DeleteComplianceScanConfiguration_ComplianceScanConfigurationService"] +== DeleteComplianceScanConfiguration + +`DELETE /v2/compliance/scan/configurations/{id}` + +DeleteComplianceScanConfiguration removes the compliance scan configuration with given Name + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="DeleteReport_ComplianceScanConfigurationService"] +== DeleteReport + +`DELETE /v2/compliance/scan/configurations/reports/{id}` + +DeleteReport deletes a given snapshot (scan execution). + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetComplianceScanConfiguration_ComplianceScanConfigurationService"] +== GetComplianceScanConfiguration + +`GET /v2/compliance/scan/configurations/{id}` + +GetComplianceScanConfiguration retrieves the specified compliance scan configurations + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceScanConfigurationStatus_CommonObjectReference[V2ComplianceScanConfigurationStatus] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceScanConfigurationStatus_CommonObjectReference[V2ComplianceScanConfigurationStatus] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetMyReportHistory_ComplianceScanConfigurationService"] +== GetMyReportHistory + +`GET /v2/compliance/scan/configurations/{id}/reports/my-history` + +GetMyReportHistory returns a list of snapshots (scan executions) executed by the current user from a given scan configuration. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| reportParamQuery.query +| +| - +| null +| + +| reportParamQuery.pagination.limit +| +| - +| null +| + +| reportParamQuery.pagination.offset +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.field +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.reversed +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| reportParamQuery.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceReportHistoryResponse_CommonObjectReference[V2ComplianceReportHistoryResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceReportHistoryResponse_CommonObjectReference[V2ComplianceReportHistoryResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetReportHistory_ComplianceScanConfigurationService"] +== GetReportHistory + +`GET /v2/compliance/scan/configurations/{id}/reports/history` + +GetReportHistory returns a list of snapshots (scan executions) from a given scan configuration. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| reportParamQuery.query +| +| - +| null +| + +| reportParamQuery.pagination.limit +| +| - +| null +| + +| reportParamQuery.pagination.offset +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.field +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.reversed +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| reportParamQuery.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceReportHistoryResponse_CommonObjectReference[V2ComplianceReportHistoryResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceReportHistoryResponse_CommonObjectReference[V2ComplianceReportHistoryResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="ListComplianceScanConfigClusterProfiles_ComplianceScanConfigurationService"] +== ListComplianceScanConfigClusterProfiles + +`GET /v2/compliance/scan/configurations/clusters/{clusterId}/profiles/collection` + +GetComplianceScanConfiguration retrieves the specified compliance scan configurations + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceScanConfigsClusterProfileResponse_CommonObjectReference[V2ListComplianceScanConfigsClusterProfileResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceScanConfigsClusterProfileResponse_CommonObjectReference[V2ListComplianceScanConfigsClusterProfileResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="ListComplianceScanConfigProfiles_ComplianceScanConfigurationService"] +== ListComplianceScanConfigProfiles + +`GET /v2/compliance/scan/configurations/profiles/collection` + +ListComplianceScanConfigurations lists all the compliance operator scan configurations for the secured clusters + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceScanConfigsProfileResponse_CommonObjectReference[V2ListComplianceScanConfigsProfileResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceScanConfigsProfileResponse_CommonObjectReference[V2ListComplianceScanConfigsProfileResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="ListComplianceScanConfigurations_ComplianceScanConfigurationService"] +== ListComplianceScanConfigurations + +`GET /v2/compliance/scan/configurations` + +ListComplianceScanConfigurations lists all the compliance operator scan configurations for the secured clusters + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceScanConfigurationsResponse_CommonObjectReference[V2ListComplianceScanConfigurationsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListComplianceScanConfigurationsResponse_CommonObjectReference[V2ListComplianceScanConfigurationsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="RunComplianceScanConfiguration_ComplianceScanConfigurationService"] +== RunComplianceScanConfiguration + +`POST /v2/compliance/scan/configurations/{id}/run` + +RunComplianceScanConfiguration launches scan for the specified scan configuration, which will invoke scans to run for the applicable profiles across the configured clusters. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="RunReport_ComplianceScanConfigurationService"] +== RunReport + +`POST /v2/compliance/scan/configurations/reports/run` + +RunReport runs an on demand compliance report for the scan configuration + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceRunReportRequest_CommonObjectReference[V2ComplianceRunReportRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceRunReportResponse_CommonObjectReference[V2ComplianceRunReportResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ComplianceRunReportResponse_CommonObjectReference[V2ComplianceRunReportResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="UpdateComplianceScanConfiguration_ComplianceScanConfigurationService"] +== UpdateComplianceScanConfiguration + +`PUT /v2/compliance/scan/configurations/{id}` + +UpdateComplianceScanConfiguration updates a compliance scan configuration + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ComplianceScanConfigurationServiceUpdateComplianceScanConfigurationBody_CommonObjectReference[ComplianceScanConfigurationServiceUpdateComplianceScanConfigurationBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ComplianceService/ComplianceService.adoc b/rest_api/ComplianceService/ComplianceService.adoc new file mode 100644 index 000000000000..2c6a9b27e9e5 --- /dev/null +++ b/rest_api/ComplianceService/ComplianceService.adoc @@ -0,0 +1,320 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ComplianceService"] += Compliance Service +:toc: macro +:toc-title: + +toc::[] + +:context: ComplianceService + +[id="GetAggregatedResults_ComplianceService"] +== GetAggregatedResults + +`GET /v1/compliance/aggregatedresults` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| groupBy +| `String` +| - +| null +| + +| unit +| +| - +| UNKNOWN +| + +| where.query +| +| - +| null +| + +| where.pagination.limit +| +| - +| null +| + +| where.pagination.offset +| +| - +| null +| + +| where.pagination.sortOption.field +| +| - +| null +| + +| where.pagination.sortOption.reversed +| +| - +| null +| + +| where.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| where.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageComplianceAggregationResponse_CommonObjectReference[StorageComplianceAggregationResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageComplianceAggregationResponse_CommonObjectReference[StorageComplianceAggregationResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetRunResults_ComplianceService"] +== GetRunResults + +`GET /v1/compliance/runresults` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| - +| null +| + +| standardId +| +| - +| null +| + +| runId +| Specifies the run ID for which to return results. If empty, the most recent run is returned. CAVEAT: Setting this field circumvents the results cache on the server-side, which may lead to significantly increased memory pressure and decreased performance. +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetComplianceRunResultsResponse_CommonObjectReference[V1GetComplianceRunResultsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetComplianceRunResultsResponse_CommonObjectReference[V1GetComplianceRunResultsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetStandard_ComplianceService"] +== GetStandard + +`GET /v1/compliance/standards/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetComplianceStandardResponse_CommonObjectReference[V1GetComplianceStandardResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetComplianceStandardResponse_CommonObjectReference[V1GetComplianceStandardResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetStandards_ComplianceService"] +== GetStandards + +`GET /v1/compliance/standards` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetComplianceStandardsResponse_CommonObjectReference[V1GetComplianceStandardsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetComplianceStandardsResponse_CommonObjectReference[V1GetComplianceStandardsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateComplianceStandardConfig_ComplianceService"] +== UpdateComplianceStandardConfig + +`PATCH /v1/compliance/standards/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ComplianceServiceUpdateComplianceStandardConfigBody_CommonObjectReference[ComplianceServiceUpdateComplianceStandardConfigBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ConfigService/ConfigService.adoc b/rest_api/ConfigService/ConfigService.adoc new file mode 100644 index 000000000000..d383a2c873a8 --- /dev/null +++ b/rest_api/ConfigService/ConfigService.adoc @@ -0,0 +1,378 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ConfigService"] += Config Service +:toc: macro +:toc-title: + +toc::[] + +:context: ConfigService + +[id="GetConfig_ConfigService"] +== GetConfig + +`GET /v1/config` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageConfig_CommonObjectReference[StorageConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageConfig_CommonObjectReference[StorageConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDefaultRedHatLayeredProductsRegex_ConfigService"] +== GetDefaultRedHatLayeredProductsRegex + +`GET /v1/config/platformcomponent/rhlp/default` + +GetDefaultRedHatLayeredProductsRegex returns a static string containing the default Red Hat Layered Products regex. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDefaultRedHatLayeredProductsRegexResponse_CommonObjectReference[V1GetDefaultRedHatLayeredProductsRegexResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDefaultRedHatLayeredProductsRegexResponse_CommonObjectReference[V1GetDefaultRedHatLayeredProductsRegexResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPlatformComponentConfig_ConfigService"] +== GetPlatformComponentConfig + +`GET /v1/config/platformcomponent` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePlatformComponentConfig_CommonObjectReference[StoragePlatformComponentConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePlatformComponentConfig_CommonObjectReference[StoragePlatformComponentConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPrivateConfig_ConfigService"] +== GetPrivateConfig + +`GET /v1/config/private` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePrivateConfig_CommonObjectReference[StoragePrivateConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePrivateConfig_CommonObjectReference[StoragePrivateConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPublicConfig_ConfigService"] +== GetPublicConfig + +`GET /v1/config/public` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePublicConfig_CommonObjectReference[StoragePublicConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePublicConfig_CommonObjectReference[StoragePublicConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetVulnerabilityExceptionConfig_ConfigService"] +== GetVulnerabilityExceptionConfig + +`GET /v1/config/private/exception/vulnerabilities` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetVulnerabilityExceptionConfigResponse_CommonObjectReference[V1GetVulnerabilityExceptionConfigResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetVulnerabilityExceptionConfigResponse_CommonObjectReference[V1GetVulnerabilityExceptionConfigResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutConfig_ConfigService"] +== PutConfig + +`PUT /v1/config` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PutConfigRequest_CommonObjectReference[V1PutConfigRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageConfig_CommonObjectReference[StorageConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageConfig_CommonObjectReference[StorageConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdatePlatformComponentConfig_ConfigService"] +== UpdatePlatformComponentConfig + +`PUT /v1/config/platformcomponent` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PutPlatformComponentConfigRequest_CommonObjectReference[V1PutPlatformComponentConfigRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePlatformComponentConfig_CommonObjectReference[StoragePlatformComponentConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePlatformComponentConfig_CommonObjectReference[StoragePlatformComponentConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateVulnerabilityExceptionConfig_ConfigService"] +== UpdateVulnerabilityExceptionConfig + +`PUT /v1/config/private/exception/vulnerabilities` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateVulnerabilityExceptionConfigRequest_CommonObjectReference[V1UpdateVulnerabilityExceptionConfigRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateVulnerabilityExceptionConfigResponse_CommonObjectReference[V1UpdateVulnerabilityExceptionConfigResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateVulnerabilityExceptionConfigResponse_CommonObjectReference[V1UpdateVulnerabilityExceptionConfigResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/CredentialExpiryService/CredentialExpiryService.adoc b/rest_api/CredentialExpiryService/CredentialExpiryService.adoc new file mode 100644 index 000000000000..60dd8fc4f584 --- /dev/null +++ b/rest_api/CredentialExpiryService/CredentialExpiryService.adoc @@ -0,0 +1,62 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="CredentialExpiryService"] += Credential Expiry Service +:toc: macro +:toc-title: + +toc::[] + +:context: CredentialExpiryService + +[id="GetCertExpiry_CredentialExpiryService"] +== GetCertExpiry + +`GET /v1/credentialexpiry` + +GetCertExpiry returns information related to the expiry component mTLS certificate. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| component +| +| - +| UNKNOWN +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCertExpiryResponse_CommonObjectReference[V1GetCertExpiryResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetCertExpiryResponse_CommonObjectReference[V1GetCertExpiryResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/DBService/DBService.adoc b/rest_api/DBService/DBService.adoc new file mode 100644 index 000000000000..f3b8c8e09d04 --- /dev/null +++ b/rest_api/DBService/DBService.adoc @@ -0,0 +1,188 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="DBService"] += D B Service +:toc: macro +:toc-title: + +toc::[] + +:context: DBService + +[id="CancelRestoreProcess_DBService"] +== CancelRestoreProcess + +`DELETE /v1/db/restore/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetActiveRestoreProcess_DBService"] +== GetActiveRestoreProcess + +`GET /v1/db/restore` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetActiveDBRestoreProcessResponse_CommonObjectReference[V1GetActiveDBRestoreProcessResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetActiveDBRestoreProcessResponse_CommonObjectReference[V1GetActiveDBRestoreProcessResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetExportCapabilities_DBService"] +== GetExportCapabilities + +`GET /v1/db/exportcaps` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDBExportCapabilitiesResponse_CommonObjectReference[V1GetDBExportCapabilitiesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDBExportCapabilitiesResponse_CommonObjectReference[V1GetDBExportCapabilitiesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="InterruptRestoreProcess_DBService"] +== InterruptRestoreProcess + +`POST /v1/db/interruptrestore/{processId}/{attemptId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| processId +| +| X +| null +| + +| attemptId +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1InterruptDBRestoreProcessResponse_CommonObjectReference[V1InterruptDBRestoreProcessResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1InterruptDBRestoreProcessResponse_CommonObjectReference[V1InterruptDBRestoreProcessResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/DebugService/DebugService.adoc b/rest_api/DebugService/DebugService.adoc new file mode 100644 index 000000000000..246191088b2b --- /dev/null +++ b/rest_api/DebugService/DebugService.adoc @@ -0,0 +1,190 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="DebugService"] += Debug Service +:toc: macro +:toc-title: + +toc::[] + +:context: DebugService + +[id="GetLogLevel_DebugService"] +== GetLogLevel + +`GET /v1/debug/loglevel` + +Get the current logging level for StackRox services. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| modules +| `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1LogLevelResponse_CommonObjectReference[V1LogLevelResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1LogLevelResponse_CommonObjectReference[V1LogLevelResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ResetDBStats_DebugService"] +== ResetDBStats + +`POST /v1/debug/db/stats/reset` + +Reset database debugging statistics. + +=== Description + +=== Parameters + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="SetLogLevel_DebugService"] +== SetLogLevel + +`PATCH /v1/debug/loglevel` + +Set logging level for StackRox services. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1LogLevelRequest_CommonObjectReference[V1LogLevelRequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="StreamAuthzTraces_DebugService"] +== StreamAuthzTraces + +`GET /v1/debug/authz/trace` + +Stream authorization traces for all incoming requests. + +=== Description + +=== Parameters + +=== Return Type + +Stream result of v1AuthorizationTraceResponse. + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response.(streaming responses) +| Stream result of v1AuthorizationTraceResponse. + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/DeclarativeConfigHealthService/DeclarativeConfigHealthService.adoc b/rest_api/DeclarativeConfigHealthService/DeclarativeConfigHealthService.adoc new file mode 100644 index 000000000000..5decbbd0eb82 --- /dev/null +++ b/rest_api/DeclarativeConfigHealthService/DeclarativeConfigHealthService.adoc @@ -0,0 +1,46 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="DeclarativeConfigHealthService"] += Declarative Config Health Service +:toc: macro +:toc-title: + +toc::[] + +:context: DeclarativeConfigHealthService + +[id="GetDeclarativeConfigHealths_DeclarativeConfigHealthService"] +== GetDeclarativeConfigHealths + +`GET /v1/declarative-config/health` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDeclarativeConfigHealthsResponse_CommonObjectReference[V1GetDeclarativeConfigHealthsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDeclarativeConfigHealthsResponse_CommonObjectReference[V1GetDeclarativeConfigHealthsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/DelegatedRegistryConfigService/DelegatedRegistryConfigService.adoc b/rest_api/DelegatedRegistryConfigService/DelegatedRegistryConfigService.adoc new file mode 100644 index 000000000000..3119afe4821e --- /dev/null +++ b/rest_api/DelegatedRegistryConfigService/DelegatedRegistryConfigService.adoc @@ -0,0 +1,138 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="DelegatedRegistryConfigService"] += Delegated Registry Config Service +:toc: macro +:toc-title: + +toc::[] + +:context: DelegatedRegistryConfigService + +[id="GetClusters_DelegatedRegistryConfigService"] +== GetClusters + +`GET /v1/delegatedregistryconfig/clusters` + +GetClusters returns the list of clusters (id + name) and a flag indicating whether or not the cluster is valid for use in the delegated registry config + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DelegatedRegistryClustersResponse_CommonObjectReference[V1DelegatedRegistryClustersResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DelegatedRegistryClustersResponse_CommonObjectReference[V1DelegatedRegistryClustersResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetConfig_DelegatedRegistryConfigService"] +== GetConfig + +`GET /v1/delegatedregistryconfig` + +GetConfig returns the current delegated registry configuration + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DelegatedRegistryConfig_CommonObjectReference[V1DelegatedRegistryConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DelegatedRegistryConfig_CommonObjectReference[V1DelegatedRegistryConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateConfig_DelegatedRegistryConfigService"] +== UpdateConfig + +`PUT /v1/delegatedregistryconfig` + +UpdateConfig updates the stored delegated registry configuration + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| DelegatedRegistryConfig determines if and where scan requests are delegated to, such as kept in central services or sent to particular secured clusters. xref:../CommonObjectReference/CommonObjectReference.adoc#V1DelegatedRegistryConfig_CommonObjectReference[V1DelegatedRegistryConfig] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DelegatedRegistryConfig_CommonObjectReference[V1DelegatedRegistryConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DelegatedRegistryConfig_CommonObjectReference[V1DelegatedRegistryConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/DeploymentService/DeploymentService.adoc b/rest_api/DeploymentService/DeploymentService.adoc new file mode 100644 index 000000000000..f352fbab9020 --- /dev/null +++ b/rest_api/DeploymentService/DeploymentService.adoc @@ -0,0 +1,472 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="DeploymentService"] += Deployment Service +:toc: macro +:toc-title: + +toc::[] + +:context: DeploymentService + +[id="CountDeployments_DeploymentService"] +== CountDeployments + +`GET /v1/deploymentscount` + +CountDeployments returns the number of deployments. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountDeploymentsResponse_CommonObjectReference[V1CountDeploymentsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountDeploymentsResponse_CommonObjectReference[V1CountDeploymentsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ExportDeployments_DeploymentService"] +== ExportDeployments + +`GET /v1/export/deployments` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| timeout +| +| - +| null +| + +| query +| +| - +| null +| + +|=== + +=== Return Type + +Stream result of v1ExportDeploymentResponse. + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response.(streaming responses) +| Stream result of v1ExportDeploymentResponse. + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDeployment_DeploymentService"] +== GetDeployment + +`GET /v1/deployments/{id}` + +GetDeployment returns a deployment given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageDeployment_CommonObjectReference[StorageDeployment] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageDeployment_CommonObjectReference[StorageDeployment] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDeploymentWithRisk_DeploymentService"] +== GetDeploymentWithRisk + +`GET /v1/deploymentswithrisk/{id}` + +GetDeploymentWithRisk returns a deployment and its risk given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDeploymentWithRiskResponse_CommonObjectReference[V1GetDeploymentWithRiskResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDeploymentWithRiskResponse_CommonObjectReference[V1GetDeploymentWithRiskResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetLabels_DeploymentService"] +== GetLabels + +`GET /v1/deployments/metadata/labels` + +GetLabels returns the labels used by deployments. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeploymentLabelsResponse_CommonObjectReference[V1DeploymentLabelsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeploymentLabelsResponse_CommonObjectReference[V1DeploymentLabelsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListDeployments_DeploymentService"] +== ListDeployments + +`GET /v1/deployments` + +ListDeployments returns the list of deployments. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListDeploymentsResponse_CommonObjectReference[V1ListDeploymentsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListDeploymentsResponse_CommonObjectReference[V1ListDeploymentsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListDeploymentsWithProcessInfo_DeploymentService"] +== ListDeploymentsWithProcessInfo + +`GET /v1/deploymentswithprocessinfo` + +ListDeploymentsWithProcessInfo returns the list of deployments with process information. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListDeploymentsWithProcessInfoResponse_CommonObjectReference[V1ListDeploymentsWithProcessInfoResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListDeploymentsWithProcessInfoResponse_CommonObjectReference[V1ListDeploymentsWithProcessInfoResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/DetectionService/DetectionService.adoc b/rest_api/DetectionService/DetectionService.adoc new file mode 100644 index 000000000000..744895efb720 --- /dev/null +++ b/rest_api/DetectionService/DetectionService.adoc @@ -0,0 +1,166 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="DetectionService"] += Detection Service +:toc: macro +:toc-title: + +toc::[] + +:context: DetectionService + +[id="DetectBuildTime_DetectionService"] +== DetectBuildTime + +`POST /v1/detect/build` + +DetectBuildTime checks if any images violate build time policies. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1BuildDetectionRequest_CommonObjectReference[V1BuildDetectionRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1BuildDetectionResponse_CommonObjectReference[V1BuildDetectionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1BuildDetectionResponse_CommonObjectReference[V1BuildDetectionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DetectDeployTime_DetectionService"] +== DetectDeployTime + +`POST /v1/detect/deploy` + +DetectDeployTime checks if any deployments violate deploy time policies. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeployDetectionRequest_CommonObjectReference[V1DeployDetectionRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeployDetectionResponse_CommonObjectReference[V1DeployDetectionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeployDetectionResponse_CommonObjectReference[V1DeployDetectionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DetectDeployTimeFromYAML_DetectionService"] +== DetectDeployTimeFromYAML + +`POST /v1/detect/deploy/yaml` + +DetectDeployTimeFromYAML checks if the given deployment yaml violates any deploy time policies. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeployYAMLDetectionRequest_CommonObjectReference[V1DeployYAMLDetectionRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeployDetectionResponse_CommonObjectReference[V1DeployDetectionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeployDetectionResponse_CommonObjectReference[V1DeployDetectionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/DiscoveredClustersService/DiscoveredClustersService.adoc b/rest_api/DiscoveredClustersService/DiscoveredClustersService.adoc new file mode 100644 index 000000000000..aa282bcd896d --- /dev/null +++ b/rest_api/DiscoveredClustersService/DiscoveredClustersService.adoc @@ -0,0 +1,238 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="DiscoveredClustersService"] += Discovered Clusters Service +:toc: macro +:toc-title: + +toc::[] + +:context: DiscoveredClustersService + +[id="CountDiscoveredClusters_DiscoveredClustersService"] +== CountDiscoveredClusters + +`GET /v1/count/discovered-clusters` + +CountDiscoveredClusters returns the number of discovered clusters after filtering by requested fields. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| filter.names +| Matches discovered clusters of specific names. `String` +| - +| null +| + +| filter.types +| Matches discovered clusters of specific types. `String` +| - +| null +| + +| filter.statuses +| Matches discovered clusters of specific statuses. - STATUS_UNSPECIFIED: The status of the cluster is unknown. May occur if a secured cluster is missing the metadata for a possible match. - STATUS_SECURED: The discovered cluster was matched with a secured cluster. - STATUS_UNSECURED: The discovered cluster was not matched with a secured cluster. `String` +| - +| null +| + +| filter.sourceIds +| Matches discovered clusters of specific cloud source IDs. `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountDiscoveredClustersResponse_CommonObjectReference[V1CountDiscoveredClustersResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountDiscoveredClustersResponse_CommonObjectReference[V1CountDiscoveredClustersResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDiscoveredCluster_DiscoveredClustersService"] +== GetDiscoveredCluster + +`GET /v1/discovered-clusters/{id}` + +GetDiscoveredCluster retrieves a discovered cluster by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDiscoveredClusterResponse_CommonObjectReference[V1GetDiscoveredClusterResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDiscoveredClusterResponse_CommonObjectReference[V1GetDiscoveredClusterResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListDiscoveredClusters_DiscoveredClustersService"] +== ListDiscoveredClusters + +`GET /v1/discovered-clusters` + +ListDiscoveredClusters returns the list of discovered clusters after filtered by requested fields. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +| filter.names +| Matches discovered clusters of specific names. `String` +| - +| null +| + +| filter.types +| Matches discovered clusters of specific types. `String` +| - +| null +| + +| filter.statuses +| Matches discovered clusters of specific statuses. - STATUS_UNSPECIFIED: The status of the cluster is unknown. May occur if a secured cluster is missing the metadata for a possible match. - STATUS_SECURED: The discovered cluster was matched with a secured cluster. - STATUS_UNSECURED: The discovered cluster was not matched with a secured cluster. `String` +| - +| null +| + +| filter.sourceIds +| Matches discovered clusters of specific cloud source IDs. `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListDiscoveredClustersResponse_CommonObjectReference[V1ListDiscoveredClustersResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListDiscoveredClustersResponse_CommonObjectReference[V1ListDiscoveredClustersResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ExternalBackupService/ExternalBackupService.adoc b/rest_api/ExternalBackupService/ExternalBackupService.adoc new file mode 100644 index 000000000000..cd34239dba07 --- /dev/null +++ b/rest_api/ExternalBackupService/ExternalBackupService.adoc @@ -0,0 +1,492 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ExternalBackupService"] += External Backup Service +:toc: macro +:toc-title: + +toc::[] + +:context: ExternalBackupService + +[id="DeleteExternalBackup_ExternalBackupService"] +== DeleteExternalBackup + +`DELETE /v1/externalbackups/{id}` + +DeleteExternalBackup removes an external backup configuration given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetExternalBackup_ExternalBackupService"] +== GetExternalBackup + +`GET /v1/externalbackups/{id}` + +GetExternalBackup returns the external backup configuration given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetExternalBackups_ExternalBackupService"] +== GetExternalBackups + +`GET /v1/externalbackups` + +GetExternalBackups returns all external backup configurations. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExternalBackupsResponse_CommonObjectReference[V1GetExternalBackupsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExternalBackupsResponse_CommonObjectReference[V1GetExternalBackupsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostExternalBackup_ExternalBackupService"] +== PostExternalBackup + +`POST /v1/externalbackups` + +PostExternalBackup creates an external backup configuration. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutExternalBackup_ExternalBackupService"] +== PutExternalBackup + +`PUT /v1/externalbackups/{id}` + +PutExternalBackup modifies a given external backup, without using stored credential reconciliation. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ExternalBackupServicePutExternalBackupBody_CommonObjectReference[ExternalBackupServicePutExternalBackupBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TestExternalBackup_ExternalBackupService"] +== TestExternalBackup + +`POST /v1/externalbackups/test` + +TestExternalBackup tests an external backup configuration. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TestUpdatedExternalBackup_ExternalBackupService"] +== TestUpdatedExternalBackup + +`POST /v1/externalbackups/test/updated` + +TestUpdatedExternalBackup checks if the given external backup is correctly configured, with optional stored credential reconciliation. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateExternalBackupRequest_CommonObjectReference[V1UpdateExternalBackupRequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TriggerExternalBackup_ExternalBackupService"] +== TriggerExternalBackup + +`POST /v1/externalbackups/{id}` + +TriggerExternalBackup initiates an external backup for the given configuration. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateExternalBackup_ExternalBackupService"] +== UpdateExternalBackup + +`PATCH /v1/externalbackups/{externalBackup.id}` + +UpdateExternalBackup modifies a given external backup, with optional stored credential reconciliation. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| externalBackup.id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ExternalBackupServiceUpdateExternalBackupBody_CommonObjectReference[ExternalBackupServiceUpdateExternalBackupBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExternalBackup_CommonObjectReference[StorageExternalBackup] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/FeatureFlagService/FeatureFlagService.adoc b/rest_api/FeatureFlagService/FeatureFlagService.adoc new file mode 100644 index 000000000000..b73b6366c83b --- /dev/null +++ b/rest_api/FeatureFlagService/FeatureFlagService.adoc @@ -0,0 +1,46 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="FeatureFlagService"] += Feature Flag Service +:toc: macro +:toc-title: + +toc::[] + +:context: FeatureFlagService + +[id="GetFeatureFlags_FeatureFlagService"] +== GetFeatureFlags + +`GET /v1/featureflags` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetFeatureFlagsResponse_CommonObjectReference[V1GetFeatureFlagsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetFeatureFlagsResponse_CommonObjectReference[V1GetFeatureFlagsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/GRPCPreferencesService/GRPCPreferencesService.adoc b/rest_api/GRPCPreferencesService/GRPCPreferencesService.adoc new file mode 100644 index 000000000000..6f351e880cf8 --- /dev/null +++ b/rest_api/GRPCPreferencesService/GRPCPreferencesService.adoc @@ -0,0 +1,46 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="GRPCPreferencesService"] += G R P C Preferences Service +:toc: macro +:toc-title: + +toc::[] + +:context: GRPCPreferencesService + +[id="Get_GRPCPreferencesService"] +== Get + +`GET /v1/grpc-preferences` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1Preferences_CommonObjectReference[V1Preferences] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1Preferences_CommonObjectReference[V1Preferences] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/GroupService/GroupService.adoc b/rest_api/GroupService/GroupService.adoc new file mode 100644 index 000000000000..65c50ae05477 --- /dev/null +++ b/rest_api/GroupService/GroupService.adoc @@ -0,0 +1,402 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="GroupService"] += Group Service +:toc: macro +:toc-title: + +toc::[] + +:context: GroupService + +[id="BatchUpdate_GroupService"] +== BatchUpdate + +`POST /v1/groupsbatch` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GroupBatchUpdateRequest_CommonObjectReference[V1GroupBatchUpdateRequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="CreateGroup_GroupService"] +== CreateGroup + +`POST /v1/groups` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| Group is a GroupProperties : Role mapping. xref:../CommonObjectReference/CommonObjectReference.adoc#StorageGroup_CommonObjectReference[StorageGroup] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteGroup_GroupService"] +== DeleteGroup + +`DELETE /v1/groups` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| authProviderId +| We copy over parameters from storage.GroupProperties for seamless HTTP API migration. +| - +| null +| + +| key +| +| - +| null +| + +| value +| +| - +| null +| + +| id +| +| - +| null +| + +| force +| +| - +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetGroup_GroupService"] +== GetGroup + +`GET /v1/group` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| Unique identifier for group properties and respectively the group. +| - +| null +| + +| traits.mutabilityMode +| +| - +| ALLOW_MUTATE +| + +| traits.visibility +| +| - +| VISIBLE +| + +| traits.origin +| +| - +| IMPERATIVE +| + +| authProviderId +| +| - +| null +| + +| key +| +| - +| null +| + +| value +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageGroup_CommonObjectReference[StorageGroup] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageGroup_CommonObjectReference[StorageGroup] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetGroups_GroupService"] +== GetGroups + +`GET /v1/groups` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| authProviderId +| +| - +| null +| + +| key +| +| - +| null +| + +| value +| +| - +| null +| + +| id +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetGroupsResponse_CommonObjectReference[V1GetGroupsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetGroupsResponse_CommonObjectReference[V1GetGroupsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateGroup_GroupService"] +== UpdateGroup + +`PUT /v1/groups` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| group +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageGroup_CommonObjectReference[StorageGroup] +| X +| +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| force +| +| - +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ImageCVEService/ImageCVEService.adoc b/rest_api/ImageCVEService/ImageCVEService.adoc new file mode 100644 index 000000000000..2a4e2358d8cf --- /dev/null +++ b/rest_api/ImageCVEService/ImageCVEService.adoc @@ -0,0 +1,114 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ImageCVEService"] += Image C V E Service +:toc: macro +:toc-title: + +toc::[] + +:context: ImageCVEService + +[id="SuppressCVEs_ImageCVEService"] +== SuppressCVEs + +`PATCH /v1/imagecves/suppress` + +SuppressCVE suppresses image cves. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1SuppressCVERequest_CommonObjectReference[V1SuppressCVERequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UnsuppressCVEs_ImageCVEService"] +== UnsuppressCVEs + +`PATCH /v1/imagecves/unsuppress` + +UnsuppressCVE unsuppresses image cves. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UnsuppressCVERequest_CommonObjectReference[V1UnsuppressCVERequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ImageIntegrationService/ImageIntegrationService.adoc b/rest_api/ImageIntegrationService/ImageIntegrationService.adoc new file mode 100644 index 000000000000..45d443631920 --- /dev/null +++ b/rest_api/ImageIntegrationService/ImageIntegrationService.adoc @@ -0,0 +1,460 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ImageIntegrationService"] += Image Integration Service +:toc: macro +:toc-title: + +toc::[] + +:context: ImageIntegrationService + +[id="DeleteImageIntegration_ImageIntegrationService"] +== DeleteImageIntegration + +`DELETE /v1/imageintegrations/{id}` + +DeleteImageIntegration removes a image integration given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetImageIntegration_ImageIntegrationService"] +== GetImageIntegration + +`GET /v1/imageintegrations/{id}` + +GetImageIntegration returns the image integration given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImageIntegration_CommonObjectReference[StorageImageIntegration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImageIntegration_CommonObjectReference[StorageImageIntegration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetImageIntegrations_ImageIntegrationService"] +== GetImageIntegrations + +`GET /v1/imageintegrations` + +GetImageIntegrations returns all image integrations that match the request filters. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| name +| +| - +| null +| + +| cluster +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetImageIntegrationsResponse_CommonObjectReference[V1GetImageIntegrationsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetImageIntegrationsResponse_CommonObjectReference[V1GetImageIntegrationsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostImageIntegration_ImageIntegrationService"] +== PostImageIntegration + +`POST /v1/imageintegrations` + +PostImageIntegration creates a image integration. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImageIntegration_CommonObjectReference[StorageImageIntegration] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImageIntegration_CommonObjectReference[StorageImageIntegration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImageIntegration_CommonObjectReference[StorageImageIntegration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutImageIntegration_ImageIntegrationService"] +== PutImageIntegration + +`PUT /v1/imageintegrations/{id}` + +PutImageIntegration modifies a given image integration, without using stored credential reconciliation. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ImageIntegrationServicePutImageIntegrationBody_CommonObjectReference[ImageIntegrationServicePutImageIntegrationBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TestImageIntegration_ImageIntegrationService"] +== TestImageIntegration + +`POST /v1/imageintegrations/test` + +TestImageIntegration checks if the given image integration is correctly configured, without using stored credential reconciliation. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImageIntegration_CommonObjectReference[StorageImageIntegration] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TestUpdatedImageIntegration_ImageIntegrationService"] +== TestUpdatedImageIntegration + +`POST /v1/imageintegrations/test/updated` + +TestUpdatedImageIntegration checks if the given image integration is correctly configured, with optional stored credential reconciliation. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateImageIntegrationRequest_CommonObjectReference[V1UpdateImageIntegrationRequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateImageIntegration_ImageIntegrationService"] +== UpdateImageIntegration + +`PATCH /v1/imageintegrations/{config.id}` + +UpdateImageIntegration modifies a given image integration, with optional stored credential reconciliation. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| config.id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ImageIntegrationServiceUpdateImageIntegrationBody_CommonObjectReference[ImageIntegrationServiceUpdateImageIntegrationBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ImageService/ImageService.adoc b/rest_api/ImageService/ImageService.adoc new file mode 100644 index 000000000000..15d23c467c84 --- /dev/null +++ b/rest_api/ImageService/ImageService.adoc @@ -0,0 +1,692 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ImageService"] += Image Service +:toc: macro +:toc-title: + +toc::[] + +:context: ImageService + +[id="GenerateSBOM_ImageService"] +== GenerateSBOM + +`POST /api/v1/images/sbom` + +Generate an SPDX 2.3 SBOM from an image scan. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ImageSBOMRequest_CommonObjectReference[ImageSBOMRequest] +| X +| +| + +|=== + +=== Return Type + +<<GenerateSBOM_ImageService,SBOM-SPDX23-Document>> + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| <<GenerateSBOM_ImageService,SBOM-SPDX23-Document>> + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="CountImages_ImageService"] +== CountImages + +`GET /v1/imagescount` + +CountImages returns a count of images that match the input query. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountImagesResponse_CommonObjectReference[V1CountImagesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountImagesResponse_CommonObjectReference[V1CountImagesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteImages_ImageService"] +== DeleteImages + +`DELETE /v1/images` + +DeleteImage removes the images based on a query + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +| confirm +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeleteImagesResponse_CommonObjectReference[V1DeleteImagesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeleteImagesResponse_CommonObjectReference[V1DeleteImagesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ExportImages_ImageService"] +== ExportImages + +`GET /v1/export/images` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| timeout +| +| - +| null +| + +| query +| +| - +| null +| + +|=== + +=== Return Type + +Stream result of v1ExportImageResponse. + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response.(streaming responses) +| Stream result of v1ExportImageResponse. + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetImage_ImageService"] +== GetImage + +`GET /v1/images/{id}` + +GetImage returns the image given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| includeSnoozed +| +| - +| null +| + +| stripDescription +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImage_CommonObjectReference[StorageImage] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImage_CommonObjectReference[StorageImage] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetWatchedImages_ImageService"] +== GetWatchedImages + +`GET /v1/watchedimages` + +GetWatchedImages returns the list of image names that are currently being watched. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetWatchedImagesResponse_CommonObjectReference[V1GetWatchedImagesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetWatchedImagesResponse_CommonObjectReference[V1GetWatchedImagesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="InvalidateScanAndRegistryCaches_ImageService"] +== InvalidateScanAndRegistryCaches + +`GET /v1/images/cache/invalidate` + +InvalidateScanAndRegistryCaches removes the image metadata cache. + +=== Description + +=== Parameters + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListImages_ImageService"] +== ListImages + +`GET /v1/images` + +ListImages returns all the images that match the input query. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListImagesResponse_CommonObjectReference[V1ListImagesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListImagesResponse_CommonObjectReference[V1ListImagesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ScanImage_ImageService"] +== ScanImage + +`POST /v1/images/scan` + +ScanImage scans a single image and returns the result + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ScanImageRequest_CommonObjectReference[V1ScanImageRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImage_CommonObjectReference[StorageImage] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageImage_CommonObjectReference[StorageImage] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UnwatchImage_ImageService"] +== UnwatchImage + +`DELETE /v1/watchedimages` + +UnwatchImage marks an image name to no longer be watched. It returns successfully if the image is no longer being watched after the call, irrespective of whether the image was already being watched. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| name +| The name of the image to unwatch. Should match the name of a previously watched image. +| - +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="WatchImage_ImageService"] +== WatchImage + +`POST /v1/watchedimages` + +WatchImage marks an image name as to be watched. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1WatchImageRequest_CommonObjectReference[V1WatchImageRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1WatchImageResponse_CommonObjectReference[V1WatchImageResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1WatchImageResponse_CommonObjectReference[V1WatchImageResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/IntegrationHealthService/IntegrationHealthService.adoc b/rest_api/IntegrationHealthService/IntegrationHealthService.adoc new file mode 100644 index 000000000000..720e38234446 --- /dev/null +++ b/rest_api/IntegrationHealthService/IntegrationHealthService.adoc @@ -0,0 +1,204 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="IntegrationHealthService"] += Integration Health Service +:toc: macro +:toc-title: + +toc::[] + +:context: IntegrationHealthService + +[id="GetBackupPlugins_IntegrationHealthService"] +== GetBackupPlugins + +`GET /v1/integrationhealth/externalbackups` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetIntegrationHealthResponse_CommonObjectReference[V1GetIntegrationHealthResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetIntegrationHealthResponse_CommonObjectReference[V1GetIntegrationHealthResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDeclarativeConfigs_IntegrationHealthService"] +== GetDeclarativeConfigs + +`GET /v1/integrationhealth/declarativeconfigs` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetIntegrationHealthResponse_CommonObjectReference[V1GetIntegrationHealthResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetIntegrationHealthResponse_CommonObjectReference[V1GetIntegrationHealthResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetImageIntegrations_IntegrationHealthService"] +== GetImageIntegrations + +`GET /v1/integrationhealth/imageintegrations` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetIntegrationHealthResponse_CommonObjectReference[V1GetIntegrationHealthResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetIntegrationHealthResponse_CommonObjectReference[V1GetIntegrationHealthResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNotifiers_IntegrationHealthService"] +== GetNotifiers + +`GET /v1/integrationhealth/notifiers` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetIntegrationHealthResponse_CommonObjectReference[V1GetIntegrationHealthResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetIntegrationHealthResponse_CommonObjectReference[V1GetIntegrationHealthResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetVulnDefinitionsInfo_IntegrationHealthService"] +== GetVulnDefinitionsInfo + +`GET /v1/integrationhealth/vulndefinitions` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| component +| +| - +| SCANNER +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1VulnDefinitionsInfo_CommonObjectReference[V1VulnDefinitionsInfo] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1VulnDefinitionsInfo_CommonObjectReference[V1VulnDefinitionsInfo] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ListeningEndpointsService/ListeningEndpointsService.adoc b/rest_api/ListeningEndpointsService/ListeningEndpointsService.adoc new file mode 100644 index 000000000000..e6cf25d76789 --- /dev/null +++ b/rest_api/ListeningEndpointsService/ListeningEndpointsService.adoc @@ -0,0 +1,106 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ListeningEndpointsService"] += Listening Endpoints Service +:toc: macro +:toc-title: + +toc::[] + +:context: ListeningEndpointsService + +[id="GetListeningEndpoints_ListeningEndpointsService"] +== GetListeningEndpoints + +`GET /v1/listening_endpoints/deployment/{deploymentId}` + +GetListeningEndpoints returns the listening endpoints and the processes that opened them for a given deployment + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetProcessesListeningOnPortsResponse_CommonObjectReference[V1GetProcessesListeningOnPortsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetProcessesListeningOnPortsResponse_CommonObjectReference[V1GetProcessesListeningOnPortsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/MetadataService/MetadataService.adoc b/rest_api/MetadataService/MetadataService.adoc new file mode 100644 index 000000000000..5551c61125da --- /dev/null +++ b/rest_api/MetadataService/MetadataService.adoc @@ -0,0 +1,208 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="MetadataService"] += Metadata Service +:toc: macro +:toc-title: + +toc::[] + +:context: MetadataService + +[id="GetCentralCapabilities_MetadataService"] +== GetCentralCapabilities + +`GET /v1/central-capabilities` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CentralServicesCapabilities_CommonObjectReference[V1CentralServicesCapabilities] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CentralServicesCapabilities_CommonObjectReference[V1CentralServicesCapabilities] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDatabaseBackupStatus_MetadataService"] +== GetDatabaseBackupStatus + +`GET /v1/backup/status` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DatabaseBackupStatus_CommonObjectReference[V1DatabaseBackupStatus] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DatabaseBackupStatus_CommonObjectReference[V1DatabaseBackupStatus] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDatabaseStatus_MetadataService"] +== GetDatabaseStatus + +`GET /v1/database/status` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DatabaseStatus_CommonObjectReference[V1DatabaseStatus] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DatabaseStatus_CommonObjectReference[V1DatabaseStatus] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetMetadata_MetadataService"] +== GetMetadata + +`GET /v1/metadata` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1Metadata_CommonObjectReference[V1Metadata] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1Metadata_CommonObjectReference[V1Metadata] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TLSChallenge_MetadataService"] +== TLSChallenge + +`GET /v1/tls-challenge` + +TLSChallenge + +=== Description + +Returns all trusted CAs, i.e., secret/additional-ca and Central's cert chain. This is necessary if Central is running behind a load balancer with self-signed certificates. Does not require authentication. + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| challengeToken +| generated challenge token by the service asking for TLS certs +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1TLSChallengeResponse_CommonObjectReference[V1TLSChallengeResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1TLSChallengeResponse_CommonObjectReference[V1TLSChallengeResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/MitreAttackService/MitreAttackService.adoc b/rest_api/MitreAttackService/MitreAttackService.adoc new file mode 100644 index 000000000000..e57a3f908afe --- /dev/null +++ b/rest_api/MitreAttackService/MitreAttackService.adoc @@ -0,0 +1,100 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="MitreAttackService"] += Mitre Attack Service +:toc: macro +:toc-title: + +toc::[] + +:context: MitreAttackService + +[id="GetMitreAttackVector_MitreAttackService"] +== GetMitreAttackVector + +`GET /v1/mitreattackvectors/{id}` + +GetMitreAttackVector returns the full MITRE ATT&CK vector for a tactic with all its techniques. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetMitreVectorResponse_CommonObjectReference[V1GetMitreVectorResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetMitreVectorResponse_CommonObjectReference[V1GetMitreVectorResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListMitreAttackVectors_MitreAttackService"] +== ListMitreAttackVectors + +`GET /v1/mitreattackvectors` + +ListMitreAttackVectors returns all MITRE ATT&CK vectors. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListMitreAttackVectorsResponse_CommonObjectReference[V1ListMitreAttackVectorsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListMitreAttackVectorsResponse_CommonObjectReference[V1ListMitreAttackVectorsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/NamespaceService/NamespaceService.adoc b/rest_api/NamespaceService/NamespaceService.adoc new file mode 100644 index 000000000000..ce763c956bd1 --- /dev/null +++ b/rest_api/NamespaceService/NamespaceService.adoc @@ -0,0 +1,146 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="NamespaceService"] += Namespace Service +:toc: macro +:toc-title: + +toc::[] + +:context: NamespaceService + +[id="GetNamespace_NamespaceService"] +== GetNamespace + +`GET /v1/namespaces/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1Namespace_CommonObjectReference[V1Namespace] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1Namespace_CommonObjectReference[V1Namespace] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNamespaces_NamespaceService"] +== GetNamespaces + +`GET /v1/namespaces` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query.query +| +| - +| null +| + +| query.pagination.limit +| +| - +| null +| + +| query.pagination.offset +| +| - +| null +| + +| query.pagination.sortOption.field +| +| - +| null +| + +| query.pagination.sortOption.reversed +| +| - +| null +| + +| query.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| query.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetNamespacesResponse_CommonObjectReference[V1GetNamespacesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetNamespacesResponse_CommonObjectReference[V1GetNamespacesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/NetworkBaselineService/NetworkBaselineService.adoc b/rest_api/NetworkBaselineService/NetworkBaselineService.adoc new file mode 100644 index 000000000000..b33e1fbebbff --- /dev/null +++ b/rest_api/NetworkBaselineService/NetworkBaselineService.adoc @@ -0,0 +1,422 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="NetworkBaselineService"] += Network Baseline Service +:toc: macro +:toc-title: + +toc::[] + +:context: NetworkBaselineService + +[id="GetNetworkBaseline_NetworkBaselineService"] +== GetNetworkBaseline + +`GET /v1/networkbaseline/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkBaseline_CommonObjectReference[StorageNetworkBaseline] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkBaseline_CommonObjectReference[StorageNetworkBaseline] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNetworkBaselineStatusForExternalFlows_NetworkBaselineService"] +== GetNetworkBaselineStatusForExternalFlows + +`GET /v1/networkbaseline/{deploymentId}/status/external` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| since +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkBaselineExternalStatusResponse_CommonObjectReference[V1NetworkBaselineExternalStatusResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkBaselineExternalStatusResponse_CommonObjectReference[V1NetworkBaselineExternalStatusResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNetworkBaselineStatusForFlows_NetworkBaselineService"] +== GetNetworkBaselineStatusForFlows + +`POST /v1/networkbaseline/{deploymentId}/status` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#NetworkBaselineServiceGetNetworkBaselineStatusForFlowsBody_CommonObjectReference[NetworkBaselineServiceGetNetworkBaselineStatusForFlowsBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkBaselineStatusResponse_CommonObjectReference[V1NetworkBaselineStatusResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkBaselineStatusResponse_CommonObjectReference[V1NetworkBaselineStatusResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="LockNetworkBaseline_NetworkBaselineService"] +== LockNetworkBaseline + +`PATCH /v1/networkbaseline/{id}/lock` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| `object` +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ModifyBaselineStatusForPeers_NetworkBaselineService"] +== ModifyBaselineStatusForPeers + +`PATCH /v1/networkbaseline/{deploymentId}/peers` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#NetworkBaselineServiceModifyBaselineStatusForPeersBody_CommonObjectReference[NetworkBaselineServiceModifyBaselineStatusForPeersBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UnlockNetworkBaseline_NetworkBaselineService"] +== UnlockNetworkBaseline + +`PATCH /v1/networkbaseline/{id}/unlock` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| `object` +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/NetworkGraphService/NetworkGraphService.adoc b/rest_api/NetworkGraphService/NetworkGraphService.adoc new file mode 100644 index 000000000000..d14c6a75ab28 --- /dev/null +++ b/rest_api/NetworkGraphService/NetworkGraphService.adoc @@ -0,0 +1,644 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="NetworkGraphService"] += Network Graph Service +:toc: macro +:toc-title: + +toc::[] + +:context: NetworkGraphService + +[id="CreateExternalNetworkEntity_NetworkGraphService"] +== CreateExternalNetworkEntity + +`POST /v1/networkgraph/cluster/{clusterId}/externalentities` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#NetworkGraphServiceCreateExternalNetworkEntityBody_CommonObjectReference[NetworkGraphServiceCreateExternalNetworkEntityBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkEntity_CommonObjectReference[StorageNetworkEntity] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkEntity_CommonObjectReference[StorageNetworkEntity] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteExternalNetworkEntity_NetworkGraphService"] +== DeleteExternalNetworkEntity + +`DELETE /v1/networkgraph/externalentities/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetExternalNetworkEntities_NetworkGraphService"] +== GetExternalNetworkEntities + +`GET /v1/networkgraph/cluster/{clusterId}/externalentities` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExternalNetworkEntitiesResponse_CommonObjectReference[V1GetExternalNetworkEntitiesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExternalNetworkEntitiesResponse_CommonObjectReference[V1GetExternalNetworkEntitiesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetExternalNetworkFlows_NetworkGraphService"] +== GetExternalNetworkFlows + +`GET /v1/networkgraph/cluster/{clusterId}/externalentities/{entityId}/flows` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +| entityId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| since +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExternalNetworkFlowsResponse_CommonObjectReference[V1GetExternalNetworkFlowsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExternalNetworkFlowsResponse_CommonObjectReference[V1GetExternalNetworkFlowsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetExternalNetworkFlowsMetadata_NetworkGraphService"] +== GetExternalNetworkFlowsMetadata + +`GET /v1/networkgraph/cluster/{clusterId}/externalentities/metadata` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| since +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExternalNetworkFlowsMetadataResponse_CommonObjectReference[V1GetExternalNetworkFlowsMetadataResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExternalNetworkFlowsMetadataResponse_CommonObjectReference[V1GetExternalNetworkFlowsMetadataResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNetworkGraph_NetworkGraphService"] +== GetNetworkGraph + +`GET /v1/networkgraph/cluster/{clusterId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| since +| +| - +| null +| + +| includePorts +| +| - +| null +| + +| scope.query +| +| - +| null +| + +| includePolicies +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkGraph_CommonObjectReference[V1NetworkGraph] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkGraph_CommonObjectReference[V1NetworkGraph] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNetworkGraphConfig_NetworkGraphService"] +== GetNetworkGraphConfig + +`GET /v1/networkgraph/config` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkGraphConfig_CommonObjectReference[StorageNetworkGraphConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkGraphConfig_CommonObjectReference[StorageNetworkGraphConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PatchExternalNetworkEntity_NetworkGraphService"] +== PatchExternalNetworkEntity + +`PATCH /v1/networkgraph/externalentities/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#NetworkGraphServicePatchExternalNetworkEntityBody_CommonObjectReference[NetworkGraphServicePatchExternalNetworkEntityBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkEntity_CommonObjectReference[StorageNetworkEntity] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkEntity_CommonObjectReference[StorageNetworkEntity] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutNetworkGraphConfig_NetworkGraphService"] +== PutNetworkGraphConfig + +`PUT /v1/networkgraph/config` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PutNetworkGraphConfigRequest_CommonObjectReference[V1PutNetworkGraphConfigRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkGraphConfig_CommonObjectReference[StorageNetworkGraphConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkGraphConfig_CommonObjectReference[StorageNetworkGraphConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/NetworkPolicyService/NetworkPolicyService.adoc b/rest_api/NetworkPolicyService/NetworkPolicyService.adoc new file mode 100644 index 000000000000..e6f1eb81d6dd --- /dev/null +++ b/rest_api/NetworkPolicyService/NetworkPolicyService.adoc @@ -0,0 +1,946 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="NetworkPolicyService"] += Network Policy Service +:toc: macro +:toc-title: + +toc::[] + +:context: NetworkPolicyService + +[id="ApplyNetworkPolicy_NetworkPolicyService"] +== ApplyNetworkPolicy + +`POST /v1/networkpolicies/apply/{clusterId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| modification +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkPolicyModification_CommonObjectReference[StorageNetworkPolicyModification] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ApplyNetworkPolicyYamlForDeployment_NetworkPolicyService"] +== ApplyNetworkPolicyYamlForDeployment + +`POST /v1/networkpolicies/apply/deployment/{deploymentId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#NetworkPolicyServiceApplyNetworkPolicyYamlForDeploymentBody_CommonObjectReference[NetworkPolicyServiceApplyNetworkPolicyYamlForDeploymentBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GenerateNetworkPolicies_NetworkPolicyService"] +== GenerateNetworkPolicies + +`GET /v1/networkpolicies/generate/{clusterId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| deleteExisting +| - NONE: Do not delete any existing network policies. - GENERATED_ONLY: Delete any existing *auto-generated* network policies. - ALL: Delete all existing network policies in the respective namespace. +| - +| UNKNOWN +| + +| networkDataSince +| +| - +| null +| + +| includePorts +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GenerateNetworkPoliciesResponse_CommonObjectReference[V1GenerateNetworkPoliciesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GenerateNetworkPoliciesResponse_CommonObjectReference[V1GenerateNetworkPoliciesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAllowedPeersFromCurrentPolicyForDeployment_NetworkPolicyService"] +== GetAllowedPeersFromCurrentPolicyForDeployment + +`GET /v1/networkpolicies/allowedpeers/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAllowedPeersFromCurrentPolicyForDeploymentResponse_CommonObjectReference[V1GetAllowedPeersFromCurrentPolicyForDeploymentResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetAllowedPeersFromCurrentPolicyForDeploymentResponse_CommonObjectReference[V1GetAllowedPeersFromCurrentPolicyForDeploymentResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetBaselineGeneratedNetworkPolicyForDeployment_NetworkPolicyService"] +== GetBaselineGeneratedNetworkPolicyForDeployment + +`POST /v1/networkpolicies/generate/baseline/{deploymentId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#NetworkPolicyServiceGetBaselineGeneratedNetworkPolicyForDeploymentBody_CommonObjectReference[NetworkPolicyServiceGetBaselineGeneratedNetworkPolicyForDeploymentBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetBaselineGeneratedPolicyForDeploymentResponse_CommonObjectReference[V1GetBaselineGeneratedPolicyForDeploymentResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetBaselineGeneratedPolicyForDeploymentResponse_CommonObjectReference[V1GetBaselineGeneratedPolicyForDeploymentResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDiffFlowsBetweenPolicyAndBaselineForDeployment_NetworkPolicyService"] +== GetDiffFlowsBetweenPolicyAndBaselineForDeployment + +`GET /v1/networkpolicies/baselinecomparison/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDiffFlowsResponse_CommonObjectReference[V1GetDiffFlowsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDiffFlowsResponse_CommonObjectReference[V1GetDiffFlowsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetDiffFlowsFromUndoModificationForDeployment_NetworkPolicyService"] +== GetDiffFlowsFromUndoModificationForDeployment + +`GET /v1/networkpolicies/undobaselinecomparison/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDiffFlowsResponse_CommonObjectReference[V1GetDiffFlowsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetDiffFlowsResponse_CommonObjectReference[V1GetDiffFlowsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNetworkGraph_NetworkPolicyService"] +== GetNetworkGraph + +`GET /v1/networkpolicies/cluster/{clusterId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| includePorts +| If set to true, include port-level information in the network policy graph. +| - +| null +| + +| scope.query +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkGraph_CommonObjectReference[V1NetworkGraph] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkGraph_CommonObjectReference[V1NetworkGraph] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNetworkGraphEpoch_NetworkPolicyService"] +== GetNetworkGraphEpoch + +`GET /v1/networkpolicies/graph/epoch` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkGraphEpoch_CommonObjectReference[V1NetworkGraphEpoch] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkGraphEpoch_CommonObjectReference[V1NetworkGraphEpoch] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNetworkPolicies_NetworkPolicyService"] +== GetNetworkPolicies + +`GET /v1/networkpolicies` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| - +| null +| + +| deploymentQuery +| +| - +| null +| + +| namespace +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkPoliciesResponse_CommonObjectReference[V1NetworkPoliciesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1NetworkPoliciesResponse_CommonObjectReference[V1NetworkPoliciesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNetworkPolicy_NetworkPolicyService"] +== GetNetworkPolicy + +`GET /v1/networkpolicies/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkPolicy_CommonObjectReference[StorageNetworkPolicy] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkPolicy_CommonObjectReference[StorageNetworkPolicy] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetUndoModification_NetworkPolicyService"] +== GetUndoModification + +`GET /v1/networkpolicies/undo/{clusterId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUndoModificationResponse_CommonObjectReference[V1GetUndoModificationResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUndoModificationResponse_CommonObjectReference[V1GetUndoModificationResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetUndoModificationForDeployment_NetworkPolicyService"] +== GetUndoModificationForDeployment + +`GET /v1/networkpolicies/undo/deployment/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUndoModificationForDeploymentResponse_CommonObjectReference[V1GetUndoModificationForDeploymentResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUndoModificationForDeploymentResponse_CommonObjectReference[V1GetUndoModificationForDeploymentResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="SendNetworkPolicyYAML_NetworkPolicyService"] +== SendNetworkPolicyYAML + +`POST /v1/networkpolicies/simulate/{clusterId}/notify` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| modification +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkPolicyModification_CommonObjectReference[StorageNetworkPolicyModification] +| X +| +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| notifierIds +| `String` +| - +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="SimulateNetworkGraph_NetworkPolicyService"] +== SimulateNetworkGraph + +`POST /v1/networkpolicies/simulate/{clusterId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| modification +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNetworkPolicyModification_CommonObjectReference[StorageNetworkPolicyModification] +| X +| +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| includePorts +| If set to true, include port-level information in the network policy graph. +| - +| null +| + +| includeNodeDiff +| +| - +| null +| + +| scope.query +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1SimulateNetworkGraphResponse_CommonObjectReference[V1SimulateNetworkGraphResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1SimulateNetworkGraphResponse_CommonObjectReference[V1SimulateNetworkGraphResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/NodeCVEService/NodeCVEService.adoc b/rest_api/NodeCVEService/NodeCVEService.adoc new file mode 100644 index 000000000000..d7b6a34bc027 --- /dev/null +++ b/rest_api/NodeCVEService/NodeCVEService.adoc @@ -0,0 +1,114 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="NodeCVEService"] += Node C V E Service +:toc: macro +:toc-title: + +toc::[] + +:context: NodeCVEService + +[id="SuppressCVEs_NodeCVEService"] +== SuppressCVEs + +`PATCH /v1/nodecves/suppress` + +SuppressCVE suppresses node cves. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1SuppressCVERequest_CommonObjectReference[V1SuppressCVERequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UnsuppressCVEs_NodeCVEService"] +== UnsuppressCVEs + +`PATCH /v1/nodecves/unsuppress` + +UnsuppressCVE unsuppresses node cves. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UnsuppressCVERequest_CommonObjectReference[V1UnsuppressCVERequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/NodeService/NodeService.adoc b/rest_api/NodeService/NodeService.adoc new file mode 100644 index 000000000000..1f27d4ffe5d8 --- /dev/null +++ b/rest_api/NodeService/NodeService.adoc @@ -0,0 +1,172 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="NodeService"] += Node Service +:toc: macro +:toc-title: + +toc::[] + +:context: NodeService + +[id="ExportNodes_NodeService"] +== ExportNodes + +`GET /v1/export/nodes` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| timeout +| +| - +| null +| + +| query +| +| - +| null +| + +|=== + +=== Return Type + +Stream result of v1ExportNodeResponse. + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response.(streaming responses) +| Stream result of v1ExportNodeResponse. + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNode_NodeService"] +== GetNode + +`GET /v1/nodes/{clusterId}/{nodeId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +| nodeId +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNode_CommonObjectReference[StorageNode] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNode_CommonObjectReference[StorageNode] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListNodes_NodeService"] +== ListNodes + +`GET /v1/nodes/{clusterId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListNodesResponse_CommonObjectReference[V1ListNodesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListNodesResponse_CommonObjectReference[V1ListNodesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/NotifierService/NotifierService.adoc b/rest_api/NotifierService/NotifierService.adoc new file mode 100644 index 000000000000..a04e49eb8355 --- /dev/null +++ b/rest_api/NotifierService/NotifierService.adoc @@ -0,0 +1,454 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="NotifierService"] += Notifier Service +:toc: macro +:toc-title: + +toc::[] + +:context: NotifierService + +[id="DeleteNotifier_NotifierService"] +== DeleteNotifier + +`DELETE /v1/notifiers/{id}` + +DeleteNotifier removes a notifier configuration given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| force +| +| - +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNotifier_NotifierService"] +== GetNotifier + +`GET /v1/notifiers/{id}` + +GetNotifier returns the notifier configuration given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNotifier_CommonObjectReference[StorageNotifier] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNotifier_CommonObjectReference[StorageNotifier] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNotifiers_NotifierService"] +== GetNotifiers + +`GET /v1/notifiers` + +GetNotifiers returns all notifier configurations. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetNotifiersResponse_CommonObjectReference[V1GetNotifiersResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetNotifiersResponse_CommonObjectReference[V1GetNotifiersResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostNotifier_NotifierService"] +== PostNotifier + +`POST /v1/notifiers` + +PostNotifier creates a notifier configuration. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNotifier_CommonObjectReference[StorageNotifier] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNotifier_CommonObjectReference[StorageNotifier] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNotifier_CommonObjectReference[StorageNotifier] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutNotifier_NotifierService"] +== PutNotifier + +`PUT /v1/notifiers/{id}` + +PutNotifier modifies a given notifier, without using stored credential reconciliation. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#NotifierServicePutNotifierBody_CommonObjectReference[NotifierServicePutNotifierBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TestNotifier_NotifierService"] +== TestNotifier + +`POST /v1/notifiers/test` + +TestNotifier checks if a notifier is correctly configured. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageNotifier_CommonObjectReference[StorageNotifier] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TestUpdatedNotifier_NotifierService"] +== TestUpdatedNotifier + +`POST /v1/notifiers/test/updated` + +TestUpdatedNotifier checks if the given notifier is correctly configured, with optional stored credential reconciliation. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateNotifierRequest_CommonObjectReference[V1UpdateNotifierRequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateNotifier_NotifierService"] +== UpdateNotifier + +`PATCH /v1/notifiers/{notifier.id}` + +UpdateNotifier modifies a given notifier, with optional stored credential reconciliation. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| notifier.id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#NotifierServiceUpdateNotifierBody_CommonObjectReference[NotifierServiceUpdateNotifierBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/PingService/PingService.adoc b/rest_api/PingService/PingService.adoc new file mode 100644 index 000000000000..b21a1106cc42 --- /dev/null +++ b/rest_api/PingService/PingService.adoc @@ -0,0 +1,46 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="PingService"] += Ping Service +:toc: macro +:toc-title: + +toc::[] + +:context: PingService + +[id="Ping_PingService"] +== Ping + +`GET /v1/ping` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1PongMessage_CommonObjectReference[V1PongMessage] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PongMessage_CommonObjectReference[V1PongMessage] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/PodService/PodService.adoc b/rest_api/PodService/PodService.adoc new file mode 100644 index 000000000000..b69d042dca65 --- /dev/null +++ b/rest_api/PodService/PodService.adoc @@ -0,0 +1,154 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="PodService"] += Pod Service +:toc: macro +:toc-title: + +toc::[] + +:context: PodService + +[id="ExportPods_PodService"] +== ExportPods + +`GET /v1/export/pods` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| timeout +| +| - +| null +| + +| query +| +| - +| null +| + +|=== + +=== Return Type + +Stream result of v1ExportPodResponse. + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response.(streaming responses) +| Stream result of v1ExportPodResponse. + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPods_PodService"] +== GetPods + +`GET /v1/pods` + +GetPods returns the pods. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1PodsResponse_CommonObjectReference[V1PodsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PodsResponse_CommonObjectReference[V1PodsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/PolicyCategoryService/PolicyCategoryService.adoc b/rest_api/PolicyCategoryService/PolicyCategoryService.adoc new file mode 100644 index 000000000000..113d974d0104 --- /dev/null +++ b/rest_api/PolicyCategoryService/PolicyCategoryService.adoc @@ -0,0 +1,306 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="PolicyCategoryService"] += Policy Category Service +:toc: macro +:toc-title: + +toc::[] + +:context: PolicyCategoryService + +[id="DeletePolicyCategory_PolicyCategoryService"] +== DeletePolicyCategory + +`DELETE /v1/policycategories/{id}` + +DeletePolicyCategory removes the given policy category. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPolicyCategories_PolicyCategoryService"] +== GetPolicyCategories + +`GET /v1/policycategories` + +GetPolicyCategories returns the list of policy categories + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetPolicyCategoriesResponse_CommonObjectReference[V1GetPolicyCategoriesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetPolicyCategoriesResponse_CommonObjectReference[V1GetPolicyCategoriesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPolicyCategory_PolicyCategoryService"] +== GetPolicyCategory + +`GET /v1/policycategories/{id}` + +GetPolicyCategory returns the requested policy category by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategory_CommonObjectReference[V1PolicyCategory] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategory_CommonObjectReference[V1PolicyCategory] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostPolicyCategory_PolicyCategoryService"] +== PostPolicyCategory + +`POST /v1/policycategories` + +PostPolicyCategory creates a new policy category + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| policyCategory +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategory_CommonObjectReference[V1PolicyCategory] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategory_CommonObjectReference[V1PolicyCategory] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategory_CommonObjectReference[V1PolicyCategory] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="RenamePolicyCategory_PolicyCategoryService"] +== RenamePolicyCategory + +`PUT /v1/policycategories` + +RenamePolicyCategory renames the given policy category. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1RenamePolicyCategoryRequest_CommonObjectReference[V1RenamePolicyCategoryRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategory_CommonObjectReference[V1PolicyCategory] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategory_CommonObjectReference[V1PolicyCategory] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/PolicyService/PolicyService.adoc b/rest_api/PolicyService/PolicyService.adoc new file mode 100644 index 000000000000..af6fb036a085 --- /dev/null +++ b/rest_api/PolicyService/PolicyService.adoc @@ -0,0 +1,964 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="PolicyService"] += Policy Service +:toc: macro +:toc-title: + +toc::[] + +:context: PolicyService + +[id="CancelDryRunJob_PolicyService"] +== CancelDryRunJob + +`DELETE /v1/policies/dryrunjob/{jobId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| jobId +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeletePolicy_PolicyService"] +== DeletePolicy + +`DELETE /v1/policies/{id}` + +DeletePolicy removes a policy by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DryRunPolicy_PolicyService"] +== DryRunPolicy + +`POST /v1/policies/dryrun` + +DryRunPolicy evaluates the given policy and returns any alerts without creating the policy. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePolicy_CommonObjectReference[StoragePolicy] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DryRunResponse_CommonObjectReference[V1DryRunResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DryRunResponse_CommonObjectReference[V1DryRunResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="EnableDisablePolicyNotification_PolicyService"] +== EnableDisablePolicyNotification + +`PATCH /v1/policies/{policyId}/notifiers` + +EnableDisablePolicyNotification enables or disables notifications for a policy by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| policyId +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#PolicyServiceEnableDisablePolicyNotificationBody_CommonObjectReference[PolicyServiceEnableDisablePolicyNotificationBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ExportPolicies_PolicyService"] +== ExportPolicies + +`POST /v1/policies/export` + +ExportPolicies takes a list of policy IDs and returns either the entire list of policies or an error message + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ExportPoliciesRequest_CommonObjectReference[V1ExportPoliciesRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExportPoliciesResponse_CommonObjectReference[StorageExportPoliciesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageExportPoliciesResponse_CommonObjectReference[StorageExportPoliciesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPolicy_PolicyService"] +== GetPolicy + +`GET /v1/policies/{id}` + +GetPolicy returns the requested policy by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePolicy_CommonObjectReference[StoragePolicy] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePolicy_CommonObjectReference[StoragePolicy] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPolicyCategories_PolicyService"] +== GetPolicyCategories + +`GET /v1/policyCategories` + +GetPolicyCategories returns the policy categories. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategoriesResponse_CommonObjectReference[V1PolicyCategoriesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyCategoriesResponse_CommonObjectReference[V1PolicyCategoriesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPolicyMitreVectors_PolicyService"] +== GetPolicyMitreVectors + +`GET /v1/policies/{id}/mitrevectors` + +GetMitreVectorsForPolicy returns the requested policy by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| options.excludePolicy +| If set to true, policy is excluded from the response. +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetPolicyMitreVectorsResponse_CommonObjectReference[V1GetPolicyMitreVectorsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetPolicyMitreVectorsResponse_CommonObjectReference[V1GetPolicyMitreVectorsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ImportPolicies_PolicyService"] +== ImportPolicies + +`POST /v1/policies/import` + +ImportPolicies accepts a list of Policies and returns a list of the policies which could not be imported + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ImportPoliciesRequest_CommonObjectReference[V1ImportPoliciesRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ImportPoliciesResponse_CommonObjectReference[V1ImportPoliciesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ImportPoliciesResponse_CommonObjectReference[V1ImportPoliciesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListPolicies_PolicyService"] +== ListPolicies + +`GET /v1/policies` + +ListPolicies returns the list of policies. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListPoliciesResponse_CommonObjectReference[V1ListPoliciesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListPoliciesResponse_CommonObjectReference[V1ListPoliciesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PatchPolicy_PolicyService"] +== PatchPolicy + +`PATCH /v1/policies/{id}` + +PatchPolicy edits an existing policy. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#PolicyServicePatchPolicyBody_CommonObjectReference[PolicyServicePatchPolicyBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PolicyFromSearch_PolicyService"] +== PolicyFromSearch + +`POST /v1/policies/from-search` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyFromSearchRequest_CommonObjectReference[V1PolicyFromSearchRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyFromSearchResponse_CommonObjectReference[V1PolicyFromSearchResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PolicyFromSearchResponse_CommonObjectReference[V1PolicyFromSearchResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostPolicy_PolicyService"] +== PostPolicy + +`POST /v1/policies` + +PostPolicy creates a new policy. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| policy +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePolicy_CommonObjectReference[StoragePolicy] +| X +| +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| enableStrictValidation +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePolicy_CommonObjectReference[StoragePolicy] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePolicy_CommonObjectReference[StoragePolicy] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutPolicy_PolicyService"] +== PutPolicy + +`PUT /v1/policies/{id}` + +PutPolicy modifies an existing policy. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#PolicyServicePutPolicyBody_CommonObjectReference[PolicyServicePutPolicyBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="QueryDryRunJobStatus_PolicyService"] +== QueryDryRunJobStatus + +`GET /v1/policies/dryrunjob/{jobId}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| jobId +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DryRunJobStatusResponse_CommonObjectReference[V1DryRunJobStatusResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DryRunJobStatusResponse_CommonObjectReference[V1DryRunJobStatusResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ReassessPolicies_PolicyService"] +== ReassessPolicies + +`POST /v1/policies/reassess` + +ReassessPolicies reevaluates all the policies. + +=== Description + +=== Parameters + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="SubmitDryRunPolicyJob_PolicyService"] +== SubmitDryRunPolicyJob + +`POST /v1/policies/dryrunjob` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePolicy_CommonObjectReference[StoragePolicy] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1JobId_CommonObjectReference[V1JobId] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1JobId_CommonObjectReference[V1JobId] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ProbeUploadService/ProbeUploadService.adoc b/rest_api/ProbeUploadService/ProbeUploadService.adoc new file mode 100644 index 000000000000..a9305ba1dfed --- /dev/null +++ b/rest_api/ProbeUploadService/ProbeUploadService.adoc @@ -0,0 +1,60 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ProbeUploadService"] += Probe Upload Service +:toc: macro +:toc-title: + +toc::[] + +:context: ProbeUploadService + +[id="GetExistingProbes_ProbeUploadService"] +== GetExistingProbes + +`POST /v1/probeupload/getexisting` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| filesToCheck +| `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExistingProbesResponse_CommonObjectReference[V1GetExistingProbesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetExistingProbesResponse_CommonObjectReference[V1GetExistingProbesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ProcessBaselineService/ProcessBaselineService.adoc b/rest_api/ProcessBaselineService/ProcessBaselineService.adoc new file mode 100644 index 000000000000..e8d35a499a47 --- /dev/null +++ b/rest_api/ProcessBaselineService/ProcessBaselineService.adoc @@ -0,0 +1,242 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ProcessBaselineService"] += Process Baseline Service +:toc: macro +:toc-title: + +toc::[] + +:context: ProcessBaselineService + +[id="DeleteProcessBaselines_ProcessBaselineService"] +== DeleteProcessBaselines + +`DELETE /v1/processbaselines` + +`DeleteProcessBaselines` deletes baselines. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| confirm +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeleteProcessBaselinesResponse_CommonObjectReference[V1DeleteProcessBaselinesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeleteProcessBaselinesResponse_CommonObjectReference[V1DeleteProcessBaselinesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetProcessBaseline_ProcessBaselineService"] +== GetProcessBaseline + +`GET /v1/processbaselines/key` + +`GetProcessBaselineById` returns the single process baseline referenced by the given ID. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| key.deploymentId +| The idea is for the keys to be flexible. Only certain combinations of these will be supported. +| - +| null +| + +| key.containerName +| +| - +| null +| + +| key.clusterId +| +| - +| null +| + +| key.namespace +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageProcessBaseline_CommonObjectReference[StorageProcessBaseline] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageProcessBaseline_CommonObjectReference[StorageProcessBaseline] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="LockProcessBaselines_ProcessBaselineService"] +== LockProcessBaselines + +`PUT /v1/processbaselines/lock` + +`LockProcessBaselines` accepts a list of baseline IDs, locks those baselines, and returns the updated baseline objects. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1LockProcessBaselinesRequest_CommonObjectReference[V1LockProcessBaselinesRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateProcessBaselinesResponse_CommonObjectReference[V1UpdateProcessBaselinesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateProcessBaselinesResponse_CommonObjectReference[V1UpdateProcessBaselinesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateProcessBaselines_ProcessBaselineService"] +== UpdateProcessBaselines + +`PUT /v1/processbaselines` + +`AddToProcessBaselines` adds a list of process names to each of a list of process baselines. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateProcessBaselinesRequest_CommonObjectReference[V1UpdateProcessBaselinesRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateProcessBaselinesResponse_CommonObjectReference[V1UpdateProcessBaselinesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateProcessBaselinesResponse_CommonObjectReference[V1UpdateProcessBaselinesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ProcessService/ProcessService.adoc b/rest_api/ProcessService/ProcessService.adoc new file mode 100644 index 000000000000..64cff03984a8 --- /dev/null +++ b/rest_api/ProcessService/ProcessService.adoc @@ -0,0 +1,254 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ProcessService"] += Process Service +:toc: macro +:toc-title: + +toc::[] + +:context: ProcessService + +[id="CountProcesses_ProcessService"] +== CountProcesses + +`GET /v1/processcount` + +CountProcesses returns the count of processes. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountProcessesResponse_CommonObjectReference[V1CountProcessesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountProcessesResponse_CommonObjectReference[V1CountProcessesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetGroupedProcessByDeployment_ProcessService"] +== GetGroupedProcessByDeployment + +`GET /v1/processes/deployment/{deploymentId}/grouped` + +GetGroupedProcessByDeployment returns all the processes executed grouped by deployment. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetGroupedProcessesResponse_CommonObjectReference[V1GetGroupedProcessesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetGroupedProcessesResponse_CommonObjectReference[V1GetGroupedProcessesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetGroupedProcessByDeploymentAndContainer_ProcessService"] +== GetGroupedProcessByDeploymentAndContainer + +`GET /v1/processes/deployment/{deploymentId}/grouped/container` + +GetGroupedProcessByDeploymentAndContainer returns all the processes executed grouped by deployment and container. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetGroupedProcessesWithContainerResponse_CommonObjectReference[V1GetGroupedProcessesWithContainerResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetGroupedProcessesWithContainerResponse_CommonObjectReference[V1GetGroupedProcessesWithContainerResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetProcessesByDeployment_ProcessService"] +== GetProcessesByDeployment + +`GET /v1/processes/deployment/{deploymentId}` + +GetProcessesByDeployment returns the processes executed in the given deployment. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| deploymentId +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetProcessesResponse_CommonObjectReference[V1GetProcessesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetProcessesResponse_CommonObjectReference[V1GetProcessesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/RbacService/RbacService.adoc b/rest_api/RbacService/RbacService.adoc new file mode 100644 index 000000000000..3aeac6a6b14c --- /dev/null +++ b/rest_api/RbacService/RbacService.adoc @@ -0,0 +1,420 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="RbacService"] += Rbac Service +:toc: macro +:toc-title: + +toc::[] + +:context: RbacService + +[id="GetRole_RbacService"] +== GetRole + +`GET /v1/rbac/roles/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetRoleResponse_CommonObjectReference[V1GetRoleResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetRoleResponse_CommonObjectReference[V1GetRoleResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetRoleBinding_RbacService"] +== GetRoleBinding + +`GET /v1/rbac/bindings/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetRoleBindingResponse_CommonObjectReference[V1GetRoleBindingResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetRoleBindingResponse_CommonObjectReference[V1GetRoleBindingResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetSubject_RbacService"] +== GetSubject + +`GET /v1/rbac/subject/{id}` + +Subjects served from this API are Groups and Users only. Id in this case is the Name field, since for users and groups, that is unique, and subjects do not have IDs. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetSubjectResponse_CommonObjectReference[V1GetSubjectResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetSubjectResponse_CommonObjectReference[V1GetSubjectResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListRoleBindings_RbacService"] +== ListRoleBindings + +`GET /v1/rbac/bindings` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListRoleBindingsResponse_CommonObjectReference[V1ListRoleBindingsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListRoleBindingsResponse_CommonObjectReference[V1ListRoleBindingsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListRoles_RbacService"] +== ListRoles + +`GET /v1/rbac/roles` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListRolesResponse_CommonObjectReference[V1ListRolesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListRolesResponse_CommonObjectReference[V1ListRolesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListSubjects_RbacService"] +== ListSubjects + +`GET /v1/rbac/subjects` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListSubjectsResponse_CommonObjectReference[V1ListSubjectsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListSubjectsResponse_CommonObjectReference[V1ListSubjectsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ReportConfigurationService/ReportConfigurationService.adoc b/rest_api/ReportConfigurationService/ReportConfigurationService.adoc new file mode 100644 index 000000000000..cab4818e9300 --- /dev/null +++ b/rest_api/ReportConfigurationService/ReportConfigurationService.adoc @@ -0,0 +1,404 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ReportConfigurationService"] += Report Configuration Service +:toc: macro +:toc-title: + +toc::[] + +:context: ReportConfigurationService + +[id="CountReportConfigurations_ReportConfigurationService"] +== CountReportConfigurations + +`GET /v1/report-configurations-count` + +CountReportConfigurations returns the number of report configurations. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountReportConfigurationsResponse_CommonObjectReference[V1CountReportConfigurationsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountReportConfigurationsResponse_CommonObjectReference[V1CountReportConfigurationsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteReportConfiguration_ReportConfigurationService"] +== DeleteReportConfiguration + +`DELETE /v1/report/configurations/{id}` + +DeleteReportConfiguration removes a report configuration given its id + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetReportConfiguration_ReportConfigurationService"] +== GetReportConfiguration + +`GET /v1/report/configurations/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetReportConfigurationResponse_CommonObjectReference[V1GetReportConfigurationResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetReportConfigurationResponse_CommonObjectReference[V1GetReportConfigurationResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetReportConfigurations_ReportConfigurationService"] +== GetReportConfigurations + +`GET /v1/report/configurations` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetReportConfigurationsResponse_CommonObjectReference[V1GetReportConfigurationsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetReportConfigurationsResponse_CommonObjectReference[V1GetReportConfigurationsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostReportConfiguration_ReportConfigurationService"] +== PostReportConfiguration + +`POST /v1/report/configurations` + +PostReportConfiguration creates a report configuration + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PostReportConfigurationRequest_CommonObjectReference[V1PostReportConfigurationRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1PostReportConfigurationResponse_CommonObjectReference[V1PostReportConfigurationResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1PostReportConfigurationResponse_CommonObjectReference[V1PostReportConfigurationResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateReportConfiguration_ReportConfigurationService"] +== UpdateReportConfiguration + +`PUT /v1/report/configurations/{id}` + +UpdateReportConfiguration updates a report configuration + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ReportConfigurationServiceUpdateReportConfigurationBody_CommonObjectReference[ReportConfigurationServiceUpdateReportConfigurationBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ReportService/ReportService.adoc b/rest_api/ReportService/ReportService.adoc new file mode 100644 index 000000000000..2d09ca6d876d --- /dev/null +++ b/rest_api/ReportService/ReportService.adoc @@ -0,0 +1,820 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ReportService"] += Report Service +:toc: macro +:toc-title: + +toc::[] + +:context: ReportService + +[id="CancelReport_ReportService"] +== CancelReport + +`DELETE /v2/reports/jobs/{id}/cancel` + +Cancels a queued report job for the given report id. If the job is not active, it is a noop. If a report is already being prepared, it won't be cancelled. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="CountReportConfigurations_ReportService"] +== CountReportConfigurations + +`GET /v2/reports/configuration-count` + +CountReportConfigurations returns the number of report configurations. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2CountReportConfigurationsResponse_CommonObjectReference[V2CountReportConfigurationsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2CountReportConfigurationsResponse_CommonObjectReference[V2CountReportConfigurationsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="DeleteReport_ReportService"] +== DeleteReport + +`DELETE /v2/reports/jobs/{id}/delete` + +Deletes a generated report for the given report id + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="DeleteReportConfiguration_ReportService"] +== DeleteReportConfiguration + +`DELETE /v2/reports/configurations/{id}` + +DeleteReportConfiguration removes the report configuration with given ID + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetMyReportHistory_ReportService"] +== GetMyReportHistory + +`GET /v2/reports/configurations/{id}/my-history` + +GetMyReportHistory returns the requester's report job history for a report configuration with the specified ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| reportParamQuery.query +| +| - +| null +| + +| reportParamQuery.pagination.limit +| +| - +| null +| + +| reportParamQuery.pagination.offset +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.field +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.reversed +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| reportParamQuery.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportHistoryResponse_CommonObjectReference[V2ReportHistoryResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportHistoryResponse_CommonObjectReference[V2ReportHistoryResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetReportConfiguration_ReportService"] +== GetReportConfiguration + +`GET /v2/reports/configurations/{id}` + +GetReportConfiguration returns the report configuration with given ID + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportConfiguration_CommonObjectReference[V2ReportConfiguration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportConfiguration_CommonObjectReference[V2ReportConfiguration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetReportHistory_ReportService"] +== GetReportHistory + +`GET /v2/reports/configurations/{id}/history` + +GetReportHistory returns the full report job history for a report configuration with the specified ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| reportParamQuery.query +| +| - +| null +| + +| reportParamQuery.pagination.limit +| +| - +| null +| + +| reportParamQuery.pagination.offset +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.field +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.reversed +| +| - +| null +| + +| reportParamQuery.pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| reportParamQuery.pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportHistoryResponse_CommonObjectReference[V2ReportHistoryResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportHistoryResponse_CommonObjectReference[V2ReportHistoryResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetReportStatus_ReportService"] +== GetReportStatus + +`GET /v2/reports/jobs/{id}/status` + +GetReportStatus returns report status for the given report id + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportStatusResponse_CommonObjectReference[V2ReportStatusResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportStatusResponse_CommonObjectReference[V2ReportStatusResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="ListReportConfigurations_ReportService"] +== ListReportConfigurations + +`GET /v2/reports/configurations` + +ListReportConfigurations returns report configurations matching given query + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListReportConfigurationsResponse_CommonObjectReference[V2ListReportConfigurationsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListReportConfigurationsResponse_CommonObjectReference[V2ListReportConfigurationsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="PostReportConfiguration_ReportService"] +== PostReportConfiguration + +`POST /v2/reports/configurations` + +PostReportConfiguration creates a report configuration + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportConfiguration_CommonObjectReference[V2ReportConfiguration] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportConfiguration_CommonObjectReference[V2ReportConfiguration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ReportConfiguration_CommonObjectReference[V2ReportConfiguration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="RunReport_ReportService"] +== RunReport + +`POST /v2/reports/run` + +Submits a new report generation request if the user requesting this report does not have another waiting or preparing report for the same report configuration. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2RunReportRequest_CommonObjectReference[V2RunReportRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2RunReportResponse_CommonObjectReference[V2RunReportResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2RunReportResponse_CommonObjectReference[V2RunReportResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="UpdateReportConfiguration_ReportService"] +== UpdateReportConfiguration + +`PUT /v2/reports/configurations/{id}` + +UpdateReportConfiguration updates a report configuration + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#ReportServiceUpdateReportConfigurationBody_CommonObjectReference[ReportServiceUpdateReportConfigurationBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples diff --git a/rest_api/RoleService/RoleService.adoc b/rest_api/RoleService/RoleService.adoc new file mode 100644 index 000000000000..429d995850aa --- /dev/null +++ b/rest_api/RoleService/RoleService.adoc @@ -0,0 +1,1080 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="RoleService"] += Role Service +:toc: macro +:toc-title: + +toc::[] + +:context: RoleService + +[id="ComputeEffectiveAccessScope_RoleService"] +== ComputeEffectiveAccessScope + +`POST /v1/computeeffectiveaccessscope` + +ComputeEffectiveAccessScope + +=== Description + +Returns effective access scope based on the rules in the request. Does not persist anything; not idempotent due to possible changes to clusters and namespaces. POST is chosen due to potentially large payload. There are advantages in both keeping the response slim and detailed. If only IDs of selected clusters and namespaces are included, response latency and processing time are lower but the caller shall overlay the response with its view of the world which is susceptible to consistency issues. Listing all clusters and namespaces with related metadata is convenient for the caller but bloat the message with secondary data. We let the caller decide what level of detail they would like to have: - Minimal, when only roots of included subtrees are listed by their IDs. Clusters can be either INCLUDED (its namespaces are included but are not listed) or PARTIAL (at least one namespace is explicitly included). Namespaces can only be INCLUDED. - Standard [default], when all known clusters and namespaces are listed with their IDs and names. Clusters can be INCLUDED (all its namespaces are explicitly listed as INCLUDED), PARTIAL (all its namespaces are explicitly listed, some as INCLUDED and some as EXCLUDED), and EXCLUDED (all its namespaces are explicitly listed as EXCLUDED). Namespaces can be either INCLUDED or EXCLUDED. - High, when every cluster and namespace is augmented with metadata. + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| accessScope +| xref:../CommonObjectReference/CommonObjectReference.adoc#ComputeEffectiveAccessScopeRequestPayload_CommonObjectReference[ComputeEffectiveAccessScopeRequestPayload] +| X +| +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| detail +| +| - +| STANDARD +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageEffectiveAccessScope_CommonObjectReference[StorageEffectiveAccessScope] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageEffectiveAccessScope_CommonObjectReference[StorageEffectiveAccessScope] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="CreateRole_RoleService"] +== CreateRole + +`POST /v1/roles/{name}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| name +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| role +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageRole_CommonObjectReference[StorageRole] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeletePermissionSet_RoleService"] +== DeletePermissionSet + +`DELETE /v1/permissionsets/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteRole_RoleService"] +== DeleteRole + +`DELETE /v1/roles/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteSimpleAccessScope_RoleService"] +== DeleteSimpleAccessScope + +`DELETE /v1/simpleaccessscopes/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetClustersForPermissions_RoleService"] +== GetClustersForPermissions + +`GET /v1/sac/clusters` + +GetClustersForPermissions + +=== Description + +Returns the list of cluster ID and cluster name pairs that have at least read allowed by the scope of the requesting user for the list of requested permissions. Effective access scopes are only considered for input permissions that have cluster scope or narrower (i.e. global permissions from the input are ignored). If the input only contains permissions at global level, the output will be an empty list. If no permission is given in input, all clusters allowed by the requester scope for any permission with cluster scope or narrower will be part of the response. + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +| permissions +| `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetClustersForPermissionsResponse_CommonObjectReference[V1GetClustersForPermissionsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetClustersForPermissionsResponse_CommonObjectReference[V1GetClustersForPermissionsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetMyPermissions_RoleService"] +== GetMyPermissions + +`GET /v1/mypermissions` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetPermissionsResponse_CommonObjectReference[V1GetPermissionsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetPermissionsResponse_CommonObjectReference[V1GetPermissionsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetNamespacesForClusterAndPermissions_RoleService"] +== GetNamespacesForClusterAndPermissions + +`GET /v1/sac/clusters/{clusterId}/namespaces` + +GetNamespacesForClusterAndPermissions + +=== Description + +Returns the list of namespace ID and namespace name pairs that belong to the requested cluster and for which the user has at least read access granted for the list of requested permissions that have namespace scope or narrower (i.e. global and cluster permissions from the input are ignored). If the input only contains permissions at global or cluster level, the output will be an empty list. If no permission is given in input, all namespaces allowed by the requester scope for any permission with namespace scope or narrower will be part of the response. + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| clusterId +| +| X +| null +| + +|=== + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| permissions +| `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetNamespacesForClusterAndPermissionsResponse_CommonObjectReference[V1GetNamespacesForClusterAndPermissionsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetNamespacesForClusterAndPermissionsResponse_CommonObjectReference[V1GetNamespacesForClusterAndPermissionsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetPermissionSet_RoleService"] +== GetPermissionSet + +`GET /v1/permissionsets/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePermissionSet_CommonObjectReference[StoragePermissionSet] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePermissionSet_CommonObjectReference[StoragePermissionSet] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetResources_RoleService"] +== GetResources + +`GET /v1/resources` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetResourcesResponse_CommonObjectReference[V1GetResourcesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetResourcesResponse_CommonObjectReference[V1GetResourcesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetRole_RoleService"] +== GetRole + +`GET /v1/roles/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageRole_CommonObjectReference[StorageRole] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageRole_CommonObjectReference[StorageRole] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetRoles_RoleService"] +== GetRoles + +`GET /v1/roles` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetRolesResponse_CommonObjectReference[V1GetRolesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetRolesResponse_CommonObjectReference[V1GetRolesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetSimpleAccessScope_RoleService"] +== GetSimpleAccessScope + +`GET /v1/simpleaccessscopes/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSimpleAccessScope_CommonObjectReference[StorageSimpleAccessScope] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSimpleAccessScope_CommonObjectReference[StorageSimpleAccessScope] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListPermissionSets_RoleService"] +== ListPermissionSets + +`GET /v1/permissionsets` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListPermissionSetsResponse_CommonObjectReference[V1ListPermissionSetsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListPermissionSetsResponse_CommonObjectReference[V1ListPermissionSetsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListSimpleAccessScopes_RoleService"] +== ListSimpleAccessScopes + +`GET /v1/simpleaccessscopes` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListSimpleAccessScopesResponse_CommonObjectReference[V1ListSimpleAccessScopesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListSimpleAccessScopesResponse_CommonObjectReference[V1ListSimpleAccessScopesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostPermissionSet_RoleService"] +== PostPermissionSet + +`POST /v1/permissionsets` + +PostPermissionSet + +=== Description + +PermissionSet.id is disallowed in request and set in response. + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| This encodes a set of permissions for StackRox resources. xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePermissionSet_CommonObjectReference[StoragePermissionSet] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePermissionSet_CommonObjectReference[StoragePermissionSet] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StoragePermissionSet_CommonObjectReference[StoragePermissionSet] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostSimpleAccessScope_RoleService"] +== PostSimpleAccessScope + +`POST /v1/simpleaccessscopes` + +PostSimpleAccessScope + +=== Description + +SimpleAccessScope.id is disallowed in request and set in response. + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| Simple access scope is a (simple) selection criteria for scoped resources. It does *not* allow multi-component AND-rules nor set operations on names. xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSimpleAccessScope_CommonObjectReference[StorageSimpleAccessScope] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSimpleAccessScope_CommonObjectReference[StorageSimpleAccessScope] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSimpleAccessScope_CommonObjectReference[StorageSimpleAccessScope] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutPermissionSet_RoleService"] +== PutPermissionSet + +`PUT /v1/permissionsets/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| id is generated and cannot be changed. +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#RoleServicePutPermissionSetBody_CommonObjectReference[RoleServicePutPermissionSetBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutSimpleAccessScope_RoleService"] +== PutSimpleAccessScope + +`PUT /v1/simpleaccessscopes/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| `id` is generated and cannot be changed. +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#RoleServicePutSimpleAccessScopeBody_CommonObjectReference[RoleServicePutSimpleAccessScopeBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateRole_RoleService"] +== UpdateRole + +`PUT /v1/roles/{name}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| name +| `name` and `description` are provided by the user and can be changed. +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#RoleServiceUpdateRoleBody_CommonObjectReference[RoleServiceUpdateRoleBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/SearchService/SearchService.adoc b/rest_api/SearchService/SearchService.adoc new file mode 100644 index 000000000000..e2aacbaad925 --- /dev/null +++ b/rest_api/SearchService/SearchService.adoc @@ -0,0 +1,172 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="SearchService"] += Search Service +:toc: macro +:toc-title: + +toc::[] + +:context: SearchService + +[id="Autocomplete_SearchService"] +== Autocomplete + +`GET /v1/search/autocomplete` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| categories +| `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1AutocompleteResponse_CommonObjectReference[V1AutocompleteResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1AutocompleteResponse_CommonObjectReference[V1AutocompleteResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="Options_SearchService"] +== Options + +`GET /v1/search/metadata/options` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| categories +| `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1SearchOptionsResponse_CommonObjectReference[V1SearchOptionsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1SearchOptionsResponse_CommonObjectReference[V1SearchOptionsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="Search_SearchService"] +== Search + +`GET /v1/search` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| categories +| `String` +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1SearchResponse_CommonObjectReference[V1SearchResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1SearchResponse_CommonObjectReference[V1SearchResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/SecretService/SecretService.adoc b/rest_api/SecretService/SecretService.adoc new file mode 100644 index 000000000000..38d63b45b731 --- /dev/null +++ b/rest_api/SecretService/SecretService.adoc @@ -0,0 +1,238 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="SecretService"] += Secret Service +:toc: macro +:toc-title: + +toc::[] + +:context: SecretService + +[id="CountSecrets_SecretService"] +== CountSecrets + +`GET /v1/secretscount` + +CountSecrets returns the number of secrets. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountSecretsResponse_CommonObjectReference[V1CountSecretsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CountSecretsResponse_CommonObjectReference[V1CountSecretsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetSecret_SecretService"] +== GetSecret + +`GET /v1/secrets/{id}` + +GetSecret returns a secret given its ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSecret_CommonObjectReference[StorageSecret] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSecret_CommonObjectReference[StorageSecret] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListSecrets_SecretService"] +== ListSecrets + +`GET /v1/secrets` + +ListSecrets returns the list of secrets. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListSecretsResponse_CommonObjectReference[V1ListSecretsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListSecretsResponse_CommonObjectReference[V1ListSecretsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/SensorUpgradeService/SensorUpgradeService.adoc b/rest_api/SensorUpgradeService/SensorUpgradeService.adoc new file mode 100644 index 000000000000..c62f7a4a836b --- /dev/null +++ b/rest_api/SensorUpgradeService/SensorUpgradeService.adoc @@ -0,0 +1,196 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="SensorUpgradeService"] += Sensor Upgrade Service +:toc: macro +:toc-title: + +toc::[] + +:context: SensorUpgradeService + +[id="GetSensorUpgradeConfig_SensorUpgradeService"] +== GetSensorUpgradeConfig + +`GET /v1/sensorupgrades/config` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetSensorUpgradeConfigResponse_CommonObjectReference[V1GetSensorUpgradeConfigResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetSensorUpgradeConfigResponse_CommonObjectReference[V1GetSensorUpgradeConfigResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TriggerSensorCertRotation_SensorUpgradeService"] +== TriggerSensorCertRotation + +`POST /v1/sensorupgrades/rotateclustercerts/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="TriggerSensorUpgrade_SensorUpgradeService"] +== TriggerSensorUpgrade + +`POST /v1/sensorupgrades/cluster/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateSensorUpgradeConfig_SensorUpgradeService"] +== UpdateSensorUpgradeConfig + +`POST /v1/sensorupgrades/config` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateSensorUpgradeConfigRequest_CommonObjectReference[V1UpdateSensorUpgradeConfigRequest] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ServiceAccountService/ServiceAccountService.adoc b/rest_api/ServiceAccountService/ServiceAccountService.adoc new file mode 100644 index 000000000000..2d17f684bc03 --- /dev/null +++ b/rest_api/ServiceAccountService/ServiceAccountService.adoc @@ -0,0 +1,146 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ServiceAccountService"] += Service Account Service +:toc: macro +:toc-title: + +toc::[] + +:context: ServiceAccountService + +[id="GetServiceAccount_ServiceAccountService"] +== GetServiceAccount + +`GET /v1/serviceaccounts/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetServiceAccountResponse_CommonObjectReference[V1GetServiceAccountResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetServiceAccountResponse_CommonObjectReference[V1GetServiceAccountResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListServiceAccounts_ServiceAccountService"] +== ListServiceAccounts + +`GET /v1/serviceaccounts` + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListServiceAccountResponse_CommonObjectReference[V1ListServiceAccountResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListServiceAccountResponse_CommonObjectReference[V1ListServiceAccountResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/ServiceIdentityService/ServiceIdentityService.adoc b/rest_api/ServiceIdentityService/ServiceIdentityService.adoc new file mode 100644 index 000000000000..b9ac845d4085 --- /dev/null +++ b/rest_api/ServiceIdentityService/ServiceIdentityService.adoc @@ -0,0 +1,136 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="ServiceIdentityService"] += Service Identity Service +:toc: macro +:toc-title: + +toc::[] + +:context: ServiceIdentityService + +[id="CreateServiceIdentity_ServiceIdentityService"] +== CreateServiceIdentity + +`POST /v1/serviceIdentities` + +CreateServiceIdentity creates a new key pair and certificate. The key and certificate are not retained and can never be retrieved again. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateServiceIdentityRequest_CommonObjectReference[V1CreateServiceIdentityRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateServiceIdentityResponse_CommonObjectReference[V1CreateServiceIdentityResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1CreateServiceIdentityResponse_CommonObjectReference[V1CreateServiceIdentityResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetAuthorities_ServiceIdentityService"] +== GetAuthorities + +`GET /v1/authorities` + +GetAuthorities returns the authorities currently in use. + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1Authorities_CommonObjectReference[V1Authorities] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1Authorities_CommonObjectReference[V1Authorities] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetServiceIdentities_ServiceIdentityService"] +== GetServiceIdentities + +`GET /v1/serviceIdentities` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ServiceIdentityResponse_CommonObjectReference[V1ServiceIdentityResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ServiceIdentityResponse_CommonObjectReference[V1ServiceIdentityResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/SignatureIntegrationService/SignatureIntegrationService.adoc b/rest_api/SignatureIntegrationService/SignatureIntegrationService.adoc new file mode 100644 index 000000000000..b64bbfce17d5 --- /dev/null +++ b/rest_api/SignatureIntegrationService/SignatureIntegrationService.adoc @@ -0,0 +1,262 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="SignatureIntegrationService"] += Signature Integration Service +:toc: macro +:toc-title: + +toc::[] + +:context: SignatureIntegrationService + +[id="DeleteSignatureIntegration_SignatureIntegrationService"] +== DeleteSignatureIntegration + +`DELETE /v1/signatureintegrations/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetSignatureIntegration_SignatureIntegrationService"] +== GetSignatureIntegration + +`GET /v1/signatureintegrations/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSignatureIntegration_CommonObjectReference[StorageSignatureIntegration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSignatureIntegration_CommonObjectReference[StorageSignatureIntegration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListSignatureIntegrations_SignatureIntegrationService"] +== ListSignatureIntegrations + +`GET /v1/signatureintegrations` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListSignatureIntegrationsResponse_CommonObjectReference[V1ListSignatureIntegrationsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListSignatureIntegrationsResponse_CommonObjectReference[V1ListSignatureIntegrationsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostSignatureIntegration_SignatureIntegrationService"] +== PostSignatureIntegration + +`POST /v1/signatureintegrations` + +Integration id should not be set. Returns signature integration with id filled. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSignatureIntegration_CommonObjectReference[StorageSignatureIntegration] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSignatureIntegration_CommonObjectReference[StorageSignatureIntegration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageSignatureIntegration_CommonObjectReference[StorageSignatureIntegration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PutSignatureIntegration_SignatureIntegrationService"] +== PutSignatureIntegration + +`PUT /v1/signatureintegrations/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#SignatureIntegrationServicePutSignatureIntegrationBody_CommonObjectReference[SignatureIntegrationServicePutSignatureIntegrationBody] +| X +| +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/TelemetryService/TelemetryService.adoc b/rest_api/TelemetryService/TelemetryService.adoc new file mode 100644 index 000000000000..9bffc2b9f40b --- /dev/null +++ b/rest_api/TelemetryService/TelemetryService.adoc @@ -0,0 +1,168 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="TelemetryService"] += Telemetry Service +:toc: macro +:toc-title: + +toc::[] + +:context: TelemetryService + +[id="ConfigureTelemetry_TelemetryService"] +== ConfigureTelemetry + +`PUT /v1/telemetry/configure` + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ConfigureTelemetryRequest_CommonObjectReference[V1ConfigureTelemetryRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageTelemetryConfiguration_CommonObjectReference[StorageTelemetryConfiguration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageTelemetryConfiguration_CommonObjectReference[StorageTelemetryConfiguration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetConfig_TelemetryService"] +== GetConfig + +`GET /v1/telemetry/config` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#CentralTelemetryConfig_CommonObjectReference[CentralTelemetryConfig] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#CentralTelemetryConfig_CommonObjectReference[CentralTelemetryConfig] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetTelemetryConfiguration_TelemetryService"] +== GetTelemetryConfiguration + +`GET /v1/telemetry/configure` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageTelemetryConfiguration_CommonObjectReference[StorageTelemetryConfiguration] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageTelemetryConfiguration_CommonObjectReference[StorageTelemetryConfiguration] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="PostConfigReload_TelemetryService"] +== PostConfigReload + +`POST /v1/telemetry/config/reload` + +=== Description + +=== Parameters + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/UserService/UserService.adoc b/rest_api/UserService/UserService.adoc new file mode 100644 index 000000000000..d916f4a72c84 --- /dev/null +++ b/rest_api/UserService/UserService.adoc @@ -0,0 +1,132 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="UserService"] += User Service +:toc: macro +:toc-title: + +toc::[] + +:context: UserService + +[id="GetUser_UserService"] +== GetUser + +`GET /v1/users/{id}` + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#StorageUser_CommonObjectReference[StorageUser] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#StorageUser_CommonObjectReference[StorageUser] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetUsers_UserService"] +== GetUsers + +`GET /v1/users` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUsersResponse_CommonObjectReference[V1GetUsersResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUsersResponse_CommonObjectReference[V1GetUsersResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetUsersAttributes_UserService"] +== GetUsersAttributes + +`GET /v1/usersattributes` + +=== Description + +=== Parameters + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUsersAttributesResponse_CommonObjectReference[V1GetUsersAttributesResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetUsersAttributesResponse_CommonObjectReference[V1GetUsersAttributesResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/VulnMgmtService/VulnMgmtService.adoc b/rest_api/VulnMgmtService/VulnMgmtService.adoc new file mode 100644 index 000000000000..e36ea456ac61 --- /dev/null +++ b/rest_api/VulnMgmtService/VulnMgmtService.adoc @@ -0,0 +1,70 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="VulnMgmtService"] += Vuln Mgmt Service +:toc: macro +:toc-title: + +toc::[] + +:context: VulnMgmtService + +[id="VulnMgmtExportWorkloads_VulnMgmtService"] +== VulnMgmtExportWorkloads + +`GET /v1/export/vuln-mgmt/workloads` + +Streams vulnerability data upon request. Each entry consists of a deployment and the associated container images. + +=== Description + +The response is structured as: {"result": {"deployment": {...}, "images": [...]}} ... {"result": {"deployment": {...}, "images": [...]}} + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| timeout +| Request timeout in seconds. +| - +| null +| + +| query +| Query to constrain the deployments for which vulnerability data is returned. The queries contain pairs of `Search Option:Value` separated by `+` signs. For HTTP requests the query should be quoted. For example > curl "$ROX_ENDPOINT/v1/export/vuln-mgmt/workloads?query=Deployment%3Ascanner%2BNamespace%3Astackrox" queries vulnerability data for all scanner deployments in the stackrox namespace. See https://docs.openshift.com/acs/operating/search-filter.html for more information. +| - +| null +| + +|=== + +=== Return Type + +Stream result of v1VulnMgmtExportWorkloadsResponse. + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response.(streaming responses) +| Stream result of v1VulnMgmtExportWorkloadsResponse. + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/VulnerabilityExceptionService/VulnerabilityExceptionService.adoc b/rest_api/VulnerabilityExceptionService/VulnerabilityExceptionService.adoc new file mode 100644 index 000000000000..3915110dd157 --- /dev/null +++ b/rest_api/VulnerabilityExceptionService/VulnerabilityExceptionService.adoc @@ -0,0 +1,556 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="VulnerabilityExceptionService"] += Vulnerability Exception Service +:toc: macro +:toc-title: + +toc::[] + +:context: VulnerabilityExceptionService + +[id="ApproveVulnerabilityException_VulnerabilityExceptionService"] +== ApproveVulnerabilityException + +`POST /v2/vulnerability-exceptions/{id}/approve` + +ApproveVulnerabilityException approves a vulnerability exception. Once approved, the exception is enforced. The associated vulnerabilities are excluded from policy evaluation and risk evaluation, and the vulnerabilities may not appear in certain APIs responses by default. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| REQUIRED. The ID of vulnerability exception to be approved. +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#VulnerabilityExceptionServiceApproveVulnerabilityExceptionBody_CommonObjectReference[VulnerabilityExceptionServiceApproveVulnerabilityExceptionBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ApproveVulnerabilityExceptionResponse_CommonObjectReference[V2ApproveVulnerabilityExceptionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ApproveVulnerabilityExceptionResponse_CommonObjectReference[V2ApproveVulnerabilityExceptionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="CancelVulnerabilityException_VulnerabilityExceptionService"] +== CancelVulnerabilityException + +`POST /v2/vulnerability-exceptions/{id}/cancel` + +CancelVulnerabilityException cancels a vulnerability exception. Once cancelled, an approved exception is no longer enforced. Cancelled exceptions are garbage collected as per the retention configuration `.expiredVulnReqRetentionDurationDays` (GET `/v1/config/`). + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2CancelVulnerabilityExceptionResponse_CommonObjectReference[V2CancelVulnerabilityExceptionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2CancelVulnerabilityExceptionResponse_CommonObjectReference[V2CancelVulnerabilityExceptionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="CreateDeferVulnerabilityException_VulnerabilityExceptionService"] +== CreateDeferVulnerabilityException + +`POST /v2/vulnerability-exceptions/deferral` + +CreateDeferVulnerabilityException creates an exception request to defer specified vulnerabilities. Once an exception is created, it remains in the PENDING state until the approval. The exception is enforced only after it is approved. Once the exception expires, it is garbage collected as per the retention configuration `.expiredVulnReqRetentionDurationDays` (GET`/v1/config/`) + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2CreateDeferVulnerabilityExceptionRequest_CommonObjectReference[V2CreateDeferVulnerabilityExceptionRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2CreateDeferVulnerabilityExceptionResponse_CommonObjectReference[V2CreateDeferVulnerabilityExceptionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2CreateDeferVulnerabilityExceptionResponse_CommonObjectReference[V2CreateDeferVulnerabilityExceptionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="CreateFalsePositiveVulnerabilityException_VulnerabilityExceptionService"] +== CreateFalsePositiveVulnerabilityException + +`POST /v2/vulnerability-exceptions/false-positive` + +CreateFalsePositiveVulnerabilityException creates an exception request to mark specified vulnerabilities as false positive. Once an exception is created, it remains in the PENDING state until the approval. The exception is enforced only after it is approved. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2CreateFalsePositiveVulnerabilityExceptionRequest_CommonObjectReference[V2CreateFalsePositiveVulnerabilityExceptionRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2CreateFalsePositiveVulnerabilityExceptionResponse_CommonObjectReference[V2CreateFalsePositiveVulnerabilityExceptionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2CreateFalsePositiveVulnerabilityExceptionResponse_CommonObjectReference[V2CreateFalsePositiveVulnerabilityExceptionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="DeleteVulnerabilityException_VulnerabilityExceptionService"] +== DeleteVulnerabilityException + +`DELETE /v2/vulnerability-exceptions/{id}` + +DeleteVulnerabilityException deletes a vulnerability exception. Only pending exceptions and pending updates to an enforced exception can be deleted. To revert an exception use cancel API. All exceptions are retained in the system according to the retention configuration. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="DenyVulnerabilityException_VulnerabilityExceptionService"] +== DenyVulnerabilityException + +`POST /v2/vulnerability-exceptions/{id}/deny` + +DenyVulnerabilityException denies a vulnerability exception. Denied exceptions are inactive and are garbage collected as per the retention configuration `.expiredVulnReqRetentionDurationDays` (GET`/v1/config/`) + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| REQUIRED. The ID of vulnerability exception to be denied. +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#VulnerabilityExceptionServiceDenyVulnerabilityExceptionBody_CommonObjectReference[VulnerabilityExceptionServiceDenyVulnerabilityExceptionBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2DenyVulnerabilityExceptionResponse_CommonObjectReference[V2DenyVulnerabilityExceptionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2DenyVulnerabilityExceptionResponse_CommonObjectReference[V2DenyVulnerabilityExceptionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="GetVulnerabilityException_VulnerabilityExceptionService"] +== GetVulnerabilityException + +`GET /v2/vulnerability-exceptions/{id}` + +GetVulnerabilityException returns the vulnerability exception with specified ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2GetVulnerabilityExceptionResponse_CommonObjectReference[V2GetVulnerabilityExceptionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2GetVulnerabilityExceptionResponse_CommonObjectReference[V2GetVulnerabilityExceptionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="ListVulnerabilityExceptions_VulnerabilityExceptionService"] +== ListVulnerabilityExceptions + +`GET /v2/vulnerability-exceptions` + +ListVulnerabilityExceptions returns a list of vulnerability exceptions. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListVulnerabilityExceptionsResponse_CommonObjectReference[V2ListVulnerabilityExceptionsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2ListVulnerabilityExceptionsResponse_CommonObjectReference[V2ListVulnerabilityExceptionsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples + +[id="UpdateVulnerabilityException_VulnerabilityExceptionService"] +== UpdateVulnerabilityException + +`PATCH /v2/vulnerability-exceptions/{id}` + +UpdateVulnerabilityException updates an existing vulnerability exception. The update is enforced only once it is approved. Currently only the following can be updated: - CVEs and expiry of the deferral exceptions - CVEs of the false positive exception + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| REQUIRED. The ID of vulnerability exception to be updated. +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#VulnerabilityExceptionServiceUpdateVulnerabilityExceptionBody_CommonObjectReference[VulnerabilityExceptionServiceUpdateVulnerabilityExceptionBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V2UpdateVulnerabilityExceptionResponse_CommonObjectReference[V2UpdateVulnerabilityExceptionResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V2UpdateVulnerabilityExceptionResponse_CommonObjectReference[V2UpdateVulnerabilityExceptionResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#RpcStatus_CommonObjectReference[RpcStatus] + +|=== + +=== Samples diff --git a/rest_api/VulnerabilityRequestService/VulnerabilityRequestService.adoc b/rest_api/VulnerabilityRequestService/VulnerabilityRequestService.adoc new file mode 100644 index 000000000000..0310ee8651f4 --- /dev/null +++ b/rest_api/VulnerabilityRequestService/VulnerabilityRequestService.adoc @@ -0,0 +1,556 @@ +// Auto-generated by scripts. Do not edit. +:_mod-docs-content-type: ASSEMBLY +[id="VulnerabilityRequestService"] += Vulnerability Request Service +:toc: macro +:toc-title: + +toc::[] + +:context: VulnerabilityRequestService + +[id="ApproveVulnerabilityRequest_VulnerabilityRequestService"] +== ApproveVulnerabilityRequest + +`POST /v1/cve/requests/{id}/approve` + +ApproveVulnRequest approve a vulnerability request. If it is an unwatch vulnerability request then the associated vulnerabilities are not watched in workflows such as policy detection, risk, etc. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#VulnerabilityRequestServiceApproveVulnerabilityRequestBody_CommonObjectReference[VulnerabilityRequestServiceApproveVulnerabilityRequestBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ApproveVulnRequestResponse_CommonObjectReference[V1ApproveVulnRequestResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ApproveVulnRequestResponse_CommonObjectReference[V1ApproveVulnRequestResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeferVulnerability_VulnerabilityRequestService"] +== DeferVulnerability + +`POST /v1/cve/requests/defer` + +DeferVulnerability starts the deferral process for the specified vulnerability. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeferVulnRequest_CommonObjectReference[V1DeferVulnRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeferVulnResponse_CommonObjectReference[V1DeferVulnResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DeferVulnResponse_CommonObjectReference[V1DeferVulnResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DeleteVulnerabilityRequest_VulnerabilityRequestService"] +== DeleteVulnerabilityRequest + +`DELETE /v1/cve/requests/{id}` + +DeleteVulnerabilityRequest deletes a vulnerability request. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +`Object` + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| `Object` + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="DenyVulnerabilityRequest_VulnerabilityRequestService"] +== DenyVulnerabilityRequest + +`POST /v1/cve/requests/{id}/deny` + +DenyVulnRequest denies a vulnerability request. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#VulnerabilityRequestServiceDenyVulnerabilityRequestBody_CommonObjectReference[VulnerabilityRequestServiceDenyVulnerabilityRequestBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1DenyVulnRequestResponse_CommonObjectReference[V1DenyVulnRequestResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1DenyVulnRequestResponse_CommonObjectReference[V1DenyVulnRequestResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="FalsePositiveVulnerability_VulnerabilityRequestService"] +== FalsePositiveVulnerability + +`POST /v1/cve/requests/false-positive` + +FalsePositiveVulnerability starts the process to mark the specified vulnerability as false-positive. + +=== Description + +=== Parameters + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1FalsePositiveVulnRequest_CommonObjectReference[V1FalsePositiveVulnRequest] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1FalsePositiveVulnResponse_CommonObjectReference[V1FalsePositiveVulnResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1FalsePositiveVulnResponse_CommonObjectReference[V1FalsePositiveVulnResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="GetVulnerabilityRequest_VulnerabilityRequestService"] +== GetVulnerabilityRequest + +`GET /v1/cve/requests/{id}` + +GetVulnerabilityRequest returns the requested vulnerability request by ID. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetVulnerabilityRequestResponse_CommonObjectReference[V1GetVulnerabilityRequestResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1GetVulnerabilityRequestResponse_CommonObjectReference[V1GetVulnerabilityRequestResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="ListVulnerabilityRequests_VulnerabilityRequestService"] +== ListVulnerabilityRequests + +`GET /v1/cve/requests` + +ListVulnerabilityRequests returns the list of vulnerability requests. + +=== Description + +=== Parameters + +==== Query Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| query +| +| - +| null +| + +| pagination.limit +| +| - +| null +| + +| pagination.offset +| +| - +| null +| + +| pagination.sortOption.field +| +| - +| null +| + +| pagination.sortOption.reversed +| +| - +| null +| + +| pagination.sortOption.aggregateBy.aggrFunc +| +| - +| UNSET +| + +| pagination.sortOption.aggregateBy.distinct +| +| - +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListVulnerabilityRequestsResponse_CommonObjectReference[V1ListVulnerabilityRequestsResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1ListVulnerabilityRequestsResponse_CommonObjectReference[V1ListVulnerabilityRequestsResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UndoVulnerabilityRequest_VulnerabilityRequestService"] +== UndoVulnerabilityRequest + +`POST /v1/cve/requests/{id}/undo` + +UndoVulnerabilityRequest undoes a vulnerability request. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1UndoVulnRequestResponse_CommonObjectReference[V1UndoVulnRequestResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UndoVulnRequestResponse_CommonObjectReference[V1UndoVulnRequestResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples + +[id="UpdateVulnerabilityRequest_VulnerabilityRequestService"] +== UpdateVulnerabilityRequest + +`POST /v1/cve/requests/{id}/update` + +UpdateVulnerabilityRequest updates an existing vulnerability request. Currently only deferral expiration time can be updated. + +=== Description + +=== Parameters + +==== Path Parameters + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| id +| +| X +| null +| + +|=== + +==== Body Parameter + +[cols="2,3,1,1,1"] +|=== +|Name| Description| Required| Default| Pattern + +| body +| xref:../CommonObjectReference/CommonObjectReference.adoc#VulnerabilityRequestServiceUpdateVulnerabilityRequestBody_CommonObjectReference[VulnerabilityRequestServiceUpdateVulnerabilityRequestBody] +| X +| +| + +|=== + +=== Return Type + +xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateVulnRequestResponse_CommonObjectReference[V1UpdateVulnRequestResponse] + +=== Content Type + +* application/json + +=== Responses + +.HTTP Response Codes +[cols="2,3,1"] +|=== +| Code | Message | Datatype + +| 200 +| A successful response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#V1UpdateVulnRequestResponse_CommonObjectReference[V1UpdateVulnRequestResponse] + +| 0 +| An unexpected error response. +| xref:../CommonObjectReference/CommonObjectReference.adoc#GooglerpcStatus_CommonObjectReference[GooglerpcStatus] + +|=== + +=== Samples diff --git a/rest_api/authorization_apis/authorization-apis-index.adoc b/rest_api/authorization_apis/authorization-apis-index.adoc deleted file mode 100644 index 9ec95a440766..000000000000 --- a/rest_api/authorization_apis/authorization-apis-index.adoc +++ /dev/null @@ -1,96 +0,0 @@ -[id="authorization-apis"] -= Authorization APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== LocalResourceAccessReview [authorization.openshift.io/v1] - -Description:: - LocalResourceAccessReview is a means to request a list of which users and groups are authorized to perform the action specified by spec in a particular namespace - -Type:: - `object` - -== LocalSubjectAccessReview [authorization.openshift.io/v1] - -Description:: - LocalSubjectAccessReview is an object for requesting information about whether a user or group can perform an action in a particular namespace - -Type:: - `object` - -== ResourceAccessReview [authorization.openshift.io/v1] - -Description:: - ResourceAccessReview is a means to request a list of which users and groups are authorized to perform the action specified by spec - -Type:: - `object` - -== SelfSubjectRulesReview [authorization.openshift.io/v1] - -Description:: - SelfSubjectRulesReview is a resource you can create to determine which actions you can perform in a namespace - -Type:: - `object` - -== SubjectAccessReview [authorization.openshift.io/v1] - -Description:: - SubjectAccessReview is an object for requesting information about whether a user or group can perform an action - -Type:: - `object` - -== SubjectRulesReview [authorization.openshift.io/v1] - -Description:: - SubjectRulesReview is a resource you can create to determine which actions another user can perform in a namespace - -Type:: - `object` - -== TokenReview [authentication.k8s.io/v1] - -Description:: - TokenReview attempts to authenticate a token to a known user. Note: TokenReview requests may be cached by the webhook token authenticator plugin in the kube-apiserver. - -Type:: - `object` - -== LocalSubjectAccessReview [authorization.k8s.io/v1] - -Description:: - LocalSubjectAccessReview checks whether or not a user or group can perform an action in a given namespace. Having a namespace scoped resource makes it much easier to grant namespace scoped policy that includes permissions checking. - -Type:: - `object` - -== SelfSubjectAccessReview [authorization.k8s.io/v1] - -Description:: - SelfSubjectAccessReview checks whether or the current user can perform an action. Not filling in a spec.namespace means "in all namespaces". Self is a special case, because users should always be able to check whether they can perform an action - -Type:: - `object` - -== SelfSubjectRulesReview [authorization.k8s.io/v1] - -Description:: - SelfSubjectRulesReview enumerates the set of actions the current user can perform within a namespace. The returned list of actions may be incomplete depending on the server's authorization mode, and any errors experienced during the evaluation. SelfSubjectRulesReview should be used by UIs to show/hide actions, or to quickly let an end user reason about their permissions. It should NOT Be used by external systems to drive authorization decisions as this raises confused deputy, cache lifetime/revocation, and correctness concerns. SubjectAccessReview, and LocalAccessReview are the correct way to defer authorization decisions to the API server. - -Type:: - `object` - -== SubjectAccessReview [authorization.k8s.io/v1] - -Description:: - SubjectAccessReview checks whether or not a user or group can perform an action. - -Type:: - `object` - diff --git a/rest_api/authorization_apis/localresourceaccessreview-authorization-openshift-io-v1.adoc b/rest_api/authorization_apis/localresourceaccessreview-authorization-openshift-io-v1.adoc deleted file mode 100644 index bca7664800f4..000000000000 --- a/rest_api/authorization_apis/localresourceaccessreview-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,144 +0,0 @@ -[id="localresourceaccessreview-authorization-openshift-io-v1"] -= LocalResourceAccessReview [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - LocalResourceAccessReview is a means to request a list of which users and groups are authorized to perform the action specified by spec in a particular namespace - -Type:: - `object` - -Required:: - - `namespace` - - `verb` - - `resourceAPIGroup` - - `resourceAPIVersion` - - `resource` - - `resourceName` - - `path` - - `isNonResourceURL` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `content` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| Content is the actual content of the request for create and update - -| `isNonResourceURL` -| `boolean` -| IsNonResourceURL is true if this is a request for a non-resource URL (outside of the resource hierarchy) - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `namespace` -| `string` -| Namespace is the namespace of the action being requested. Currently, there is no distinction between no namespace and all namespaces - -| `path` -| `string` -| Path is the path of a non resource URL - -| `resource` -| `string` -| Resource is one of the existing resource types - -| `resourceAPIGroup` -| `string` -| Group is the API group of the resource Serialized as resourceAPIGroup to avoid confusion with the 'groups' field when inlined - -| `resourceAPIVersion` -| `string` -| Version is the API version of the resource Serialized as resourceAPIVersion to avoid confusion with TypeMeta.apiVersion and ObjectMeta.resourceVersion when inlined - -| `resourceName` -| `string` -| ResourceName is the name of the resource being requested for a "get" or deleted for a "delete" - -| `verb` -| `string` -| Verb is one of: get, list, watch, create, update, delete - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/localresourceaccessreviews` -- `POST`: create a LocalResourceAccessReview - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/localresourceaccessreviews - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a LocalResourceAccessReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/localresourceaccessreview-authorization-openshift-io-v1.adoc#localresourceaccessreview-authorization-openshift-io-v1[`LocalResourceAccessReview authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/localresourceaccessreview-authorization-openshift-io-v1.adoc#localresourceaccessreview-authorization-openshift-io-v1[`LocalResourceAccessReview authorization.openshift.io/v1`] -| 201 - Created -| xref:../authorization_apis/localresourceaccessreview-authorization-openshift-io-v1.adoc#localresourceaccessreview-authorization-openshift-io-v1[`LocalResourceAccessReview authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/localresourceaccessreview-authorization-openshift-io-v1.adoc#localresourceaccessreview-authorization-openshift-io-v1[`LocalResourceAccessReview authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/localsubjectaccessreview-authorization-k8s-io-v1.adoc b/rest_api/authorization_apis/localsubjectaccessreview-authorization-k8s-io-v1.adoc deleted file mode 100644 index 17b56d7e4d28..000000000000 --- a/rest_api/authorization_apis/localsubjectaccessreview-authorization-k8s-io-v1.adoc +++ /dev/null @@ -1,265 +0,0 @@ -[id="localsubjectaccessreview-authorization-k8s-io-v1"] -= LocalSubjectAccessReview [authorization.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - LocalSubjectAccessReview checks whether or not a user or group can perform an action in a given namespace. Having a namespace scoped resource makes it much easier to grant namespace scoped policy that includes permissions checking. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| SubjectAccessReviewSpec is a description of the access request. Exactly one of ResourceAuthorizationAttributes and NonResourceAuthorizationAttributes must be set - -| `status` -| `object` -| SubjectAccessReviewStatus - -|=== -..spec -Description:: - SubjectAccessReviewSpec is a description of the access request. Exactly one of ResourceAuthorizationAttributes and NonResourceAuthorizationAttributes must be set - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `extra` -| `object` -| Extra corresponds to the user.Info.GetExtra() method from the authenticator. Since that is input to the authorizer it needs a reflection here. - -| `extra{}` -| `array (string)` -| - -| `groups` -| `array (string)` -| Groups is the groups you're testing for. - -| `nonResourceAttributes` -| `object` -| NonResourceAttributes includes the authorization attributes available for non-resource requests to the Authorizer interface - -| `resourceAttributes` -| `object` -| ResourceAttributes includes the authorization attributes available for resource requests to the Authorizer interface - -| `uid` -| `string` -| UID information about the requesting user. - -| `user` -| `string` -| User is the user you're testing for. If you specify "User" but not "Groups", then is it interpreted as "What if User were not a member of any groups - -|=== -..spec.extra -Description:: - Extra corresponds to the user.Info.GetExtra() method from the authenticator. Since that is input to the authorizer it needs a reflection here. - -Type:: - `object` - - - - -..spec.nonResourceAttributes -Description:: - NonResourceAttributes includes the authorization attributes available for non-resource requests to the Authorizer interface - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path is the URL path of the request - -| `verb` -| `string` -| Verb is the standard HTTP verb - -|=== -..spec.resourceAttributes -Description:: - ResourceAttributes includes the authorization attributes available for resource requests to the Authorizer interface - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group is the API Group of the Resource. "*" means all. - -| `name` -| `string` -| Name is the name of the resource being requested for a "get" or deleted for a "delete". "" (empty) means all. - -| `namespace` -| `string` -| Namespace is the namespace of the action being requested. Currently, there is no distinction between no namespace and all namespaces "" (empty) is defaulted for LocalSubjectAccessReviews "" (empty) is empty for cluster-scoped resources "" (empty) means "all" for namespace scoped resources from a SubjectAccessReview or SelfSubjectAccessReview - -| `resource` -| `string` -| Resource is one of the existing resource types. "*" means all. - -| `subresource` -| `string` -| Subresource is one of the existing resource types. "" means none. - -| `verb` -| `string` -| Verb is a kubernetes resource API verb, like: get, list, watch, create, update, delete, proxy. "*" means all. - -| `version` -| `string` -| Version is the API Version of the Resource. "*" means all. - -|=== -..status -Description:: - SubjectAccessReviewStatus - -Type:: - `object` - -Required:: - - `allowed` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowed` -| `boolean` -| Allowed is required. True if the action would be allowed, false otherwise. - -| `denied` -| `boolean` -| Denied is optional. True if the action would be denied, otherwise false. If both allowed is false and denied is false, then the authorizer has no opinion on whether to authorize the action. Denied may not be true if Allowed is true. - -| `evaluationError` -| `string` -| EvaluationError is an indication that some error occurred during the authorization check. It is entirely possible to get an error and be able to continue determine authorization status in spite of it. For instance, RBAC can be missing a role, but enough roles are still present and bound to reason about the request. - -| `reason` -| `string` -| Reason is optional. It indicates why a request was allowed or denied. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.k8s.io/v1/namespaces/{namespace}/localsubjectaccessreviews` -- `POST`: create a LocalSubjectAccessReview - - -=== /apis/authorization.k8s.io/v1/namespaces/{namespace}/localsubjectaccessreviews - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a LocalSubjectAccessReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/localsubjectaccessreview-authorization-k8s-io-v1.adoc#localsubjectaccessreview-authorization-k8s-io-v1[`LocalSubjectAccessReview authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/localsubjectaccessreview-authorization-k8s-io-v1.adoc#localsubjectaccessreview-authorization-k8s-io-v1[`LocalSubjectAccessReview authorization.k8s.io/v1`] -| 201 - Created -| xref:../authorization_apis/localsubjectaccessreview-authorization-k8s-io-v1.adoc#localsubjectaccessreview-authorization-k8s-io-v1[`LocalSubjectAccessReview authorization.k8s.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/localsubjectaccessreview-authorization-k8s-io-v1.adoc#localsubjectaccessreview-authorization-k8s-io-v1[`LocalSubjectAccessReview authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/localsubjectaccessreview-authorization-openshift-io-v1.adoc b/rest_api/authorization_apis/localsubjectaccessreview-authorization-openshift-io-v1.adoc deleted file mode 100644 index 33f8328c71e7..000000000000 --- a/rest_api/authorization_apis/localsubjectaccessreview-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,159 +0,0 @@ -[id="localsubjectaccessreview-authorization-openshift-io-v1"] -= LocalSubjectAccessReview [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - LocalSubjectAccessReview is an object for requesting information about whether a user or group can perform an action in a particular namespace - -Type:: - `object` - -Required:: - - `namespace` - - `verb` - - `resourceAPIGroup` - - `resourceAPIVersion` - - `resource` - - `resourceName` - - `path` - - `isNonResourceURL` - - `user` - - `groups` - - `scopes` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `content` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| Content is the actual content of the request for create and update - -| `groups` -| `array (string)` -| Groups is optional. Groups is the list of groups to which the User belongs. - -| `isNonResourceURL` -| `boolean` -| IsNonResourceURL is true if this is a request for a non-resource URL (outside of the resource hierarchy) - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `namespace` -| `string` -| Namespace is the namespace of the action being requested. Currently, there is no distinction between no namespace and all namespaces - -| `path` -| `string` -| Path is the path of a non resource URL - -| `resource` -| `string` -| Resource is one of the existing resource types - -| `resourceAPIGroup` -| `string` -| Group is the API group of the resource Serialized as resourceAPIGroup to avoid confusion with the 'groups' field when inlined - -| `resourceAPIVersion` -| `string` -| Version is the API version of the resource Serialized as resourceAPIVersion to avoid confusion with TypeMeta.apiVersion and ObjectMeta.resourceVersion when inlined - -| `resourceName` -| `string` -| ResourceName is the name of the resource being requested for a "get" or deleted for a "delete" - -| `scopes` -| `array (string)` -| Scopes to use for the evaluation. Empty means "use the unscoped (full) permissions of the user/groups". Nil for a self-SAR, means "use the scopes on this request". Nil for a regular SAR, means the same as empty. - -| `user` -| `string` -| User is optional. If both User and Groups are empty, the current authenticated user is used. - -| `verb` -| `string` -| Verb is one of: get, list, watch, create, update, delete - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/localsubjectaccessreviews` -- `POST`: create a LocalSubjectAccessReview - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/localsubjectaccessreviews - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a LocalSubjectAccessReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/localsubjectaccessreview-authorization-openshift-io-v1.adoc#localsubjectaccessreview-authorization-openshift-io-v1[`LocalSubjectAccessReview authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/localsubjectaccessreview-authorization-openshift-io-v1.adoc#localsubjectaccessreview-authorization-openshift-io-v1[`LocalSubjectAccessReview authorization.openshift.io/v1`] -| 201 - Created -| xref:../authorization_apis/localsubjectaccessreview-authorization-openshift-io-v1.adoc#localsubjectaccessreview-authorization-openshift-io-v1[`LocalSubjectAccessReview authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/localsubjectaccessreview-authorization-openshift-io-v1.adoc#localsubjectaccessreview-authorization-openshift-io-v1[`LocalSubjectAccessReview authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/resourceaccessreview-authorization-openshift-io-v1.adoc b/rest_api/authorization_apis/resourceaccessreview-authorization-openshift-io-v1.adoc deleted file mode 100644 index aa1d50adb7c1..000000000000 --- a/rest_api/authorization_apis/resourceaccessreview-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,136 +0,0 @@ -[id="resourceaccessreview-authorization-openshift-io-v1"] -= ResourceAccessReview [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ResourceAccessReview is a means to request a list of which users and groups are authorized to perform the action specified by spec - -Type:: - `object` - -Required:: - - `namespace` - - `verb` - - `resourceAPIGroup` - - `resourceAPIVersion` - - `resource` - - `resourceName` - - `path` - - `isNonResourceURL` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `content` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| Content is the actual content of the request for create and update - -| `isNonResourceURL` -| `boolean` -| IsNonResourceURL is true if this is a request for a non-resource URL (outside of the resource hierarchy) - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `namespace` -| `string` -| Namespace is the namespace of the action being requested. Currently, there is no distinction between no namespace and all namespaces - -| `path` -| `string` -| Path is the path of a non resource URL - -| `resource` -| `string` -| Resource is one of the existing resource types - -| `resourceAPIGroup` -| `string` -| Group is the API group of the resource Serialized as resourceAPIGroup to avoid confusion with the 'groups' field when inlined - -| `resourceAPIVersion` -| `string` -| Version is the API version of the resource Serialized as resourceAPIVersion to avoid confusion with TypeMeta.apiVersion and ObjectMeta.resourceVersion when inlined - -| `resourceName` -| `string` -| ResourceName is the name of the resource being requested for a "get" or deleted for a "delete" - -| `verb` -| `string` -| Verb is one of: get, list, watch, create, update, delete - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/resourceaccessreviews` -- `POST`: create a ResourceAccessReview - - -=== /apis/authorization.openshift.io/v1/resourceaccessreviews - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a ResourceAccessReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/resourceaccessreview-authorization-openshift-io-v1.adoc#resourceaccessreview-authorization-openshift-io-v1[`ResourceAccessReview authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/resourceaccessreview-authorization-openshift-io-v1.adoc#resourceaccessreview-authorization-openshift-io-v1[`ResourceAccessReview authorization.openshift.io/v1`] -| 201 - Created -| xref:../authorization_apis/resourceaccessreview-authorization-openshift-io-v1.adoc#resourceaccessreview-authorization-openshift-io-v1[`ResourceAccessReview authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/resourceaccessreview-authorization-openshift-io-v1.adoc#resourceaccessreview-authorization-openshift-io-v1[`ResourceAccessReview authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/selfsubjectaccessreview-authorization-k8s-io-v1.adoc b/rest_api/authorization_apis/selfsubjectaccessreview-authorization-k8s-io-v1.adoc deleted file mode 100644 index 90ee1454832d..000000000000 --- a/rest_api/authorization_apis/selfsubjectaccessreview-authorization-k8s-io-v1.adoc +++ /dev/null @@ -1,227 +0,0 @@ -[id="selfsubjectaccessreview-authorization-k8s-io-v1"] -= SelfSubjectAccessReview [authorization.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - SelfSubjectAccessReview checks whether or the current user can perform an action. Not filling in a spec.namespace means "in all namespaces". Self is a special case, because users should always be able to check whether they can perform an action - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| SelfSubjectAccessReviewSpec is a description of the access request. Exactly one of ResourceAuthorizationAttributes and NonResourceAuthorizationAttributes must be set - -| `status` -| `object` -| SubjectAccessReviewStatus - -|=== -..spec -Description:: - SelfSubjectAccessReviewSpec is a description of the access request. Exactly one of ResourceAuthorizationAttributes and NonResourceAuthorizationAttributes must be set - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nonResourceAttributes` -| `object` -| NonResourceAttributes includes the authorization attributes available for non-resource requests to the Authorizer interface - -| `resourceAttributes` -| `object` -| ResourceAttributes includes the authorization attributes available for resource requests to the Authorizer interface - -|=== -..spec.nonResourceAttributes -Description:: - NonResourceAttributes includes the authorization attributes available for non-resource requests to the Authorizer interface - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path is the URL path of the request - -| `verb` -| `string` -| Verb is the standard HTTP verb - -|=== -..spec.resourceAttributes -Description:: - ResourceAttributes includes the authorization attributes available for resource requests to the Authorizer interface - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group is the API Group of the Resource. "*" means all. - -| `name` -| `string` -| Name is the name of the resource being requested for a "get" or deleted for a "delete". "" (empty) means all. - -| `namespace` -| `string` -| Namespace is the namespace of the action being requested. Currently, there is no distinction between no namespace and all namespaces "" (empty) is defaulted for LocalSubjectAccessReviews "" (empty) is empty for cluster-scoped resources "" (empty) means "all" for namespace scoped resources from a SubjectAccessReview or SelfSubjectAccessReview - -| `resource` -| `string` -| Resource is one of the existing resource types. "*" means all. - -| `subresource` -| `string` -| Subresource is one of the existing resource types. "" means none. - -| `verb` -| `string` -| Verb is a kubernetes resource API verb, like: get, list, watch, create, update, delete, proxy. "*" means all. - -| `version` -| `string` -| Version is the API Version of the Resource. "*" means all. - -|=== -..status -Description:: - SubjectAccessReviewStatus - -Type:: - `object` - -Required:: - - `allowed` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowed` -| `boolean` -| Allowed is required. True if the action would be allowed, false otherwise. - -| `denied` -| `boolean` -| Denied is optional. True if the action would be denied, otherwise false. If both allowed is false and denied is false, then the authorizer has no opinion on whether to authorize the action. Denied may not be true if Allowed is true. - -| `evaluationError` -| `string` -| EvaluationError is an indication that some error occurred during the authorization check. It is entirely possible to get an error and be able to continue determine authorization status in spite of it. For instance, RBAC can be missing a role, but enough roles are still present and bound to reason about the request. - -| `reason` -| `string` -| Reason is optional. It indicates why a request was allowed or denied. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.k8s.io/v1/selfsubjectaccessreviews` -- `POST`: create a SelfSubjectAccessReview - - -=== /apis/authorization.k8s.io/v1/selfsubjectaccessreviews - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a SelfSubjectAccessReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/selfsubjectaccessreview-authorization-k8s-io-v1.adoc#selfsubjectaccessreview-authorization-k8s-io-v1[`SelfSubjectAccessReview authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/selfsubjectaccessreview-authorization-k8s-io-v1.adoc#selfsubjectaccessreview-authorization-k8s-io-v1[`SelfSubjectAccessReview authorization.k8s.io/v1`] -| 201 - Created -| xref:../authorization_apis/selfsubjectaccessreview-authorization-k8s-io-v1.adoc#selfsubjectaccessreview-authorization-k8s-io-v1[`SelfSubjectAccessReview authorization.k8s.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/selfsubjectaccessreview-authorization-k8s-io-v1.adoc#selfsubjectaccessreview-authorization-k8s-io-v1[`SelfSubjectAccessReview authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/selfsubjectrulesreview-authorization-k8s-io-v1.adoc b/rest_api/authorization_apis/selfsubjectrulesreview-authorization-k8s-io-v1.adoc deleted file mode 100644 index 4022f419611d..000000000000 --- a/rest_api/authorization_apis/selfsubjectrulesreview-authorization-k8s-io-v1.adoc +++ /dev/null @@ -1,246 +0,0 @@ -[id="selfsubjectrulesreview-authorization-k8s-io-v1"] -= SelfSubjectRulesReview [authorization.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - SelfSubjectRulesReview enumerates the set of actions the current user can perform within a namespace. The returned list of actions may be incomplete depending on the server's authorization mode, and any errors experienced during the evaluation. SelfSubjectRulesReview should be used by UIs to show/hide actions, or to quickly let an end user reason about their permissions. It should NOT Be used by external systems to drive authorization decisions as this raises confused deputy, cache lifetime/revocation, and correctness concerns. SubjectAccessReview, and LocalAccessReview are the correct way to defer authorization decisions to the API server. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| Spec holds information about the request being evaluated. - -| `status` -| `object` -| SubjectRulesReviewStatus contains the result of a rules check. This check can be incomplete depending on the set of authorizers the server is configured with and any errors experienced during evaluation. Because authorization rules are additive, if a rule appears in a list it's safe to assume the subject has that permission, even if that list is incomplete. - -|=== -..spec -Description:: - Spec holds information about the request being evaluated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namespace` -| `string` -| Namespace to evaluate rules for. Required. - -|=== -..status -Description:: - SubjectRulesReviewStatus contains the result of a rules check. This check can be incomplete depending on the set of authorizers the server is configured with and any errors experienced during evaluation. Because authorization rules are additive, if a rule appears in a list it's safe to assume the subject has that permission, even if that list is incomplete. - -Type:: - `object` - -Required:: - - `resourceRules` - - `nonResourceRules` - - `incomplete` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `evaluationError` -| `string` -| EvaluationError can appear in combination with Rules. It indicates an error occurred during rule evaluation, such as an authorizer that doesn't support rule evaluation, and that ResourceRules and/or NonResourceRules may be incomplete. - -| `incomplete` -| `boolean` -| Incomplete is true when the rules returned by this call are incomplete. This is most commonly encountered when an authorizer, such as an external authorizer, doesn't support rules evaluation. - -| `nonResourceRules` -| `array` -| NonResourceRules is the list of actions the subject is allowed to perform on non-resources. The list ordering isn't significant, may contain duplicates, and possibly be incomplete. - -| `nonResourceRules[]` -| `object` -| NonResourceRule holds information that describes a rule for the non-resource - -| `resourceRules` -| `array` -| ResourceRules is the list of actions the subject is allowed to perform on resources. The list ordering isn't significant, may contain duplicates, and possibly be incomplete. - -| `resourceRules[]` -| `object` -| ResourceRule is the list of actions the subject is allowed to perform on resources. The list ordering isn't significant, may contain duplicates, and possibly be incomplete. - -|=== -..status.nonResourceRules -Description:: - NonResourceRules is the list of actions the subject is allowed to perform on non-resources. The list ordering isn't significant, may contain duplicates, and possibly be incomplete. - -Type:: - `array` - - - - -..status.nonResourceRules[] -Description:: - NonResourceRule holds information that describes a rule for the non-resource - -Type:: - `object` - -Required:: - - `verbs` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path. "*" means all. - -| `verbs` -| `array (string)` -| Verb is a list of kubernetes non-resource API verbs, like: get, post, put, delete, patch, head, options. "*" means all. - -|=== -..status.resourceRules -Description:: - ResourceRules is the list of actions the subject is allowed to perform on resources. The list ordering isn't significant, may contain duplicates, and possibly be incomplete. - -Type:: - `array` - - - - -..status.resourceRules[] -Description:: - ResourceRule is the list of actions the subject is allowed to perform on resources. The list ordering isn't significant, may contain duplicates, and possibly be incomplete. - -Type:: - `object` - -Required:: - - `verbs` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against one of the enumerated resources in any API group will be allowed. "*" means all. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. "*" means all. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. "*" means all in the specified apiGroups. - "*/foo" represents the subresource 'foo' for all resources in the specified apiGroups. - -| `verbs` -| `array (string)` -| Verb is a list of kubernetes resource API verbs, like: get, list, watch, create, update, delete, proxy. "*" means all. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.k8s.io/v1/selfsubjectrulesreviews` -- `POST`: create a SelfSubjectRulesReview - - -=== /apis/authorization.k8s.io/v1/selfsubjectrulesreviews - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a SelfSubjectRulesReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/selfsubjectrulesreview-authorization-k8s-io-v1.adoc#selfsubjectrulesreview-authorization-k8s-io-v1[`SelfSubjectRulesReview authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/selfsubjectrulesreview-authorization-k8s-io-v1.adoc#selfsubjectrulesreview-authorization-k8s-io-v1[`SelfSubjectRulesReview authorization.k8s.io/v1`] -| 201 - Created -| xref:../authorization_apis/selfsubjectrulesreview-authorization-k8s-io-v1.adoc#selfsubjectrulesreview-authorization-k8s-io-v1[`SelfSubjectRulesReview authorization.k8s.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/selfsubjectrulesreview-authorization-k8s-io-v1.adoc#selfsubjectrulesreview-authorization-k8s-io-v1[`SelfSubjectRulesReview authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/selfsubjectrulesreview-authorization-openshift-io-v1.adoc b/rest_api/authorization_apis/selfsubjectrulesreview-authorization-openshift-io-v1.adoc deleted file mode 100644 index 426a387acdd4..000000000000 --- a/rest_api/authorization_apis/selfsubjectrulesreview-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,211 +0,0 @@ -[id="selfsubjectrulesreview-authorization-openshift-io-v1"] -= SelfSubjectRulesReview [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - SelfSubjectRulesReview is a resource you can create to determine which actions you can perform in a namespace - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `spec` -| `object` -| SelfSubjectRulesReviewSpec adds information about how to conduct the check - -| `status` -| `object` -| SubjectRulesReviewStatus is contains the result of a rules check - -|=== -..spec -Description:: - SelfSubjectRulesReviewSpec adds information about how to conduct the check - -Type:: - `object` - -Required:: - - `scopes` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `scopes` -| `array (string)` -| Scopes to use for the evaluation. Empty means "use the unscoped (full) permissions of the user/groups". Nil means "use the scopes on this request". - -|=== -..status -Description:: - SubjectRulesReviewStatus is contains the result of a rules check - -Type:: - `object` - -Required:: - - `rules` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `evaluationError` -| `string` -| EvaluationError can appear in combination with Rules. It means some error happened during evaluation that may have prevented additional rules from being populated. - -| `rules` -| `array` -| Rules is the list of rules (no particular sort) that are allowed for the subject - -| `rules[]` -| `object` -| PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -|=== -..status.rules -Description:: - Rules is the list of rules (no particular sort) that are allowed for the subject - -Type:: - `array` - - - - -..status.rules[] -Description:: - PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -Type:: - `object` - -Required:: - - `verbs` - - `resources` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If this field is empty, then both kubernetes and origin API groups are assumed. That means that if an action is requested against one of the enumerated resources in either the kubernetes or the origin API group, the request will be allowed - -| `attributeRestrictions` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| AttributeRestrictions will vary depending on what the Authorizer/AuthorizationAttributeBuilder pair supports. If the Authorizer does not recognize how to handle the AttributeRestrictions, the Authorizer should report an error. - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLsSlice is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path This name is intentionally different than the internal type so that the DefaultConvert works nicely and because the ordering may be different. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. ResourceAll represents all resources. - -| `verbs` -| `array (string)` -| Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule. VerbAll represents all kinds. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/selfsubjectrulesreviews` -- `POST`: create a SelfSubjectRulesReview - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/selfsubjectrulesreviews - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a SelfSubjectRulesReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/selfsubjectrulesreview-authorization-openshift-io-v1.adoc#selfsubjectrulesreview-authorization-openshift-io-v1[`SelfSubjectRulesReview authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/selfsubjectrulesreview-authorization-openshift-io-v1.adoc#selfsubjectrulesreview-authorization-openshift-io-v1[`SelfSubjectRulesReview authorization.openshift.io/v1`] -| 201 - Created -| xref:../authorization_apis/selfsubjectrulesreview-authorization-openshift-io-v1.adoc#selfsubjectrulesreview-authorization-openshift-io-v1[`SelfSubjectRulesReview authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/selfsubjectrulesreview-authorization-openshift-io-v1.adoc#selfsubjectrulesreview-authorization-openshift-io-v1[`SelfSubjectRulesReview authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/subjectaccessreview-authorization-k8s-io-v1.adoc b/rest_api/authorization_apis/subjectaccessreview-authorization-k8s-io-v1.adoc deleted file mode 100644 index 74d054fbe1cf..000000000000 --- a/rest_api/authorization_apis/subjectaccessreview-authorization-k8s-io-v1.adoc +++ /dev/null @@ -1,257 +0,0 @@ -[id="subjectaccessreview-authorization-k8s-io-v1"] -= SubjectAccessReview [authorization.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - SubjectAccessReview checks whether or not a user or group can perform an action. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| SubjectAccessReviewSpec is a description of the access request. Exactly one of ResourceAuthorizationAttributes and NonResourceAuthorizationAttributes must be set - -| `status` -| `object` -| SubjectAccessReviewStatus - -|=== -..spec -Description:: - SubjectAccessReviewSpec is a description of the access request. Exactly one of ResourceAuthorizationAttributes and NonResourceAuthorizationAttributes must be set - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `extra` -| `object` -| Extra corresponds to the user.Info.GetExtra() method from the authenticator. Since that is input to the authorizer it needs a reflection here. - -| `extra{}` -| `array (string)` -| - -| `groups` -| `array (string)` -| Groups is the groups you're testing for. - -| `nonResourceAttributes` -| `object` -| NonResourceAttributes includes the authorization attributes available for non-resource requests to the Authorizer interface - -| `resourceAttributes` -| `object` -| ResourceAttributes includes the authorization attributes available for resource requests to the Authorizer interface - -| `uid` -| `string` -| UID information about the requesting user. - -| `user` -| `string` -| User is the user you're testing for. If you specify "User" but not "Groups", then is it interpreted as "What if User were not a member of any groups - -|=== -..spec.extra -Description:: - Extra corresponds to the user.Info.GetExtra() method from the authenticator. Since that is input to the authorizer it needs a reflection here. - -Type:: - `object` - - - - -..spec.nonResourceAttributes -Description:: - NonResourceAttributes includes the authorization attributes available for non-resource requests to the Authorizer interface - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path is the URL path of the request - -| `verb` -| `string` -| Verb is the standard HTTP verb - -|=== -..spec.resourceAttributes -Description:: - ResourceAttributes includes the authorization attributes available for resource requests to the Authorizer interface - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group is the API Group of the Resource. "*" means all. - -| `name` -| `string` -| Name is the name of the resource being requested for a "get" or deleted for a "delete". "" (empty) means all. - -| `namespace` -| `string` -| Namespace is the namespace of the action being requested. Currently, there is no distinction between no namespace and all namespaces "" (empty) is defaulted for LocalSubjectAccessReviews "" (empty) is empty for cluster-scoped resources "" (empty) means "all" for namespace scoped resources from a SubjectAccessReview or SelfSubjectAccessReview - -| `resource` -| `string` -| Resource is one of the existing resource types. "*" means all. - -| `subresource` -| `string` -| Subresource is one of the existing resource types. "" means none. - -| `verb` -| `string` -| Verb is a kubernetes resource API verb, like: get, list, watch, create, update, delete, proxy. "*" means all. - -| `version` -| `string` -| Version is the API Version of the Resource. "*" means all. - -|=== -..status -Description:: - SubjectAccessReviewStatus - -Type:: - `object` - -Required:: - - `allowed` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowed` -| `boolean` -| Allowed is required. True if the action would be allowed, false otherwise. - -| `denied` -| `boolean` -| Denied is optional. True if the action would be denied, otherwise false. If both allowed is false and denied is false, then the authorizer has no opinion on whether to authorize the action. Denied may not be true if Allowed is true. - -| `evaluationError` -| `string` -| EvaluationError is an indication that some error occurred during the authorization check. It is entirely possible to get an error and be able to continue determine authorization status in spite of it. For instance, RBAC can be missing a role, but enough roles are still present and bound to reason about the request. - -| `reason` -| `string` -| Reason is optional. It indicates why a request was allowed or denied. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.k8s.io/v1/subjectaccessreviews` -- `POST`: create a SubjectAccessReview - - -=== /apis/authorization.k8s.io/v1/subjectaccessreviews - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a SubjectAccessReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/subjectaccessreview-authorization-k8s-io-v1.adoc#subjectaccessreview-authorization-k8s-io-v1[`SubjectAccessReview authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/subjectaccessreview-authorization-k8s-io-v1.adoc#subjectaccessreview-authorization-k8s-io-v1[`SubjectAccessReview authorization.k8s.io/v1`] -| 201 - Created -| xref:../authorization_apis/subjectaccessreview-authorization-k8s-io-v1.adoc#subjectaccessreview-authorization-k8s-io-v1[`SubjectAccessReview authorization.k8s.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/subjectaccessreview-authorization-k8s-io-v1.adoc#subjectaccessreview-authorization-k8s-io-v1[`SubjectAccessReview authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/subjectaccessreview-authorization-openshift-io-v1.adoc b/rest_api/authorization_apis/subjectaccessreview-authorization-openshift-io-v1.adoc deleted file mode 100644 index bb7a4552492b..000000000000 --- a/rest_api/authorization_apis/subjectaccessreview-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,151 +0,0 @@ -[id="subjectaccessreview-authorization-openshift-io-v1"] -= SubjectAccessReview [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - SubjectAccessReview is an object for requesting information about whether a user or group can perform an action - -Type:: - `object` - -Required:: - - `namespace` - - `verb` - - `resourceAPIGroup` - - `resourceAPIVersion` - - `resource` - - `resourceName` - - `path` - - `isNonResourceURL` - - `user` - - `groups` - - `scopes` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `content` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| Content is the actual content of the request for create and update - -| `groups` -| `array (string)` -| GroupsSlice is optional. Groups is the list of groups to which the User belongs. - -| `isNonResourceURL` -| `boolean` -| IsNonResourceURL is true if this is a request for a non-resource URL (outside of the resource hierarchy) - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `namespace` -| `string` -| Namespace is the namespace of the action being requested. Currently, there is no distinction between no namespace and all namespaces - -| `path` -| `string` -| Path is the path of a non resource URL - -| `resource` -| `string` -| Resource is one of the existing resource types - -| `resourceAPIGroup` -| `string` -| Group is the API group of the resource Serialized as resourceAPIGroup to avoid confusion with the 'groups' field when inlined - -| `resourceAPIVersion` -| `string` -| Version is the API version of the resource Serialized as resourceAPIVersion to avoid confusion with TypeMeta.apiVersion and ObjectMeta.resourceVersion when inlined - -| `resourceName` -| `string` -| ResourceName is the name of the resource being requested for a "get" or deleted for a "delete" - -| `scopes` -| `array (string)` -| Scopes to use for the evaluation. Empty means "use the unscoped (full) permissions of the user/groups". Nil for a self-SAR, means "use the scopes on this request". Nil for a regular SAR, means the same as empty. - -| `user` -| `string` -| User is optional. If both User and Groups are empty, the current authenticated user is used. - -| `verb` -| `string` -| Verb is one of: get, list, watch, create, update, delete - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/subjectaccessreviews` -- `POST`: create a SubjectAccessReview - - -=== /apis/authorization.openshift.io/v1/subjectaccessreviews - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a SubjectAccessReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/subjectaccessreview-authorization-openshift-io-v1.adoc#subjectaccessreview-authorization-openshift-io-v1[`SubjectAccessReview authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/subjectaccessreview-authorization-openshift-io-v1.adoc#subjectaccessreview-authorization-openshift-io-v1[`SubjectAccessReview authorization.openshift.io/v1`] -| 201 - Created -| xref:../authorization_apis/subjectaccessreview-authorization-openshift-io-v1.adoc#subjectaccessreview-authorization-openshift-io-v1[`SubjectAccessReview authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/subjectaccessreview-authorization-openshift-io-v1.adoc#subjectaccessreview-authorization-openshift-io-v1[`SubjectAccessReview authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/subjectrulesreview-authorization-openshift-io-v1.adoc b/rest_api/authorization_apis/subjectrulesreview-authorization-openshift-io-v1.adoc deleted file mode 100644 index 1ad179f115cf..000000000000 --- a/rest_api/authorization_apis/subjectrulesreview-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,221 +0,0 @@ -[id="subjectrulesreview-authorization-openshift-io-v1"] -= SubjectRulesReview [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - SubjectRulesReview is a resource you can create to determine which actions another user can perform in a namespace - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `spec` -| `object` -| SubjectRulesReviewSpec adds information about how to conduct the check - -| `status` -| `object` -| SubjectRulesReviewStatus is contains the result of a rules check - -|=== -..spec -Description:: - SubjectRulesReviewSpec adds information about how to conduct the check - -Type:: - `object` - -Required:: - - `user` - - `groups` - - `scopes` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `groups` -| `array (string)` -| Groups is optional. Groups is the list of groups to which the User belongs. At least one of User and Groups must be specified. - -| `scopes` -| `array (string)` -| Scopes to use for the evaluation. Empty means "use the unscoped (full) permissions of the user/groups". - -| `user` -| `string` -| User is optional. At least one of User and Groups must be specified. - -|=== -..status -Description:: - SubjectRulesReviewStatus is contains the result of a rules check - -Type:: - `object` - -Required:: - - `rules` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `evaluationError` -| `string` -| EvaluationError can appear in combination with Rules. It means some error happened during evaluation that may have prevented additional rules from being populated. - -| `rules` -| `array` -| Rules is the list of rules (no particular sort) that are allowed for the subject - -| `rules[]` -| `object` -| PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -|=== -..status.rules -Description:: - Rules is the list of rules (no particular sort) that are allowed for the subject - -Type:: - `array` - - - - -..status.rules[] -Description:: - PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -Type:: - `object` - -Required:: - - `verbs` - - `resources` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If this field is empty, then both kubernetes and origin API groups are assumed. That means that if an action is requested against one of the enumerated resources in either the kubernetes or the origin API group, the request will be allowed - -| `attributeRestrictions` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| AttributeRestrictions will vary depending on what the Authorizer/AuthorizationAttributeBuilder pair supports. If the Authorizer does not recognize how to handle the AttributeRestrictions, the Authorizer should report an error. - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLsSlice is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path This name is intentionally different than the internal type so that the DefaultConvert works nicely and because the ordering may be different. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. ResourceAll represents all resources. - -| `verbs` -| `array (string)` -| Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule. VerbAll represents all kinds. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/subjectrulesreviews` -- `POST`: create a SubjectRulesReview - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/subjectrulesreviews - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a SubjectRulesReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/subjectrulesreview-authorization-openshift-io-v1.adoc#subjectrulesreview-authorization-openshift-io-v1[`SubjectRulesReview authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/subjectrulesreview-authorization-openshift-io-v1.adoc#subjectrulesreview-authorization-openshift-io-v1[`SubjectRulesReview authorization.openshift.io/v1`] -| 201 - Created -| xref:../authorization_apis/subjectrulesreview-authorization-openshift-io-v1.adoc#subjectrulesreview-authorization-openshift-io-v1[`SubjectRulesReview authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/subjectrulesreview-authorization-openshift-io-v1.adoc#subjectrulesreview-authorization-openshift-io-v1[`SubjectRulesReview authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/authorization_apis/tokenreview-authentication-k8s-io-v1.adoc b/rest_api/authorization_apis/tokenreview-authentication-k8s-io-v1.adoc deleted file mode 100644 index d1d2dd56def5..000000000000 --- a/rest_api/authorization_apis/tokenreview-authentication-k8s-io-v1.adoc +++ /dev/null @@ -1,204 +0,0 @@ -[id="tokenreview-authentication-k8s-io-v1"] -= TokenReview [authentication.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - TokenReview attempts to authenticate a token to a known user. Note: TokenReview requests may be cached by the webhook token authenticator plugin in the kube-apiserver. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| TokenReviewSpec is a description of the token authentication request. - -| `status` -| `object` -| TokenReviewStatus is the result of the token authentication request. - -|=== -..spec -Description:: - TokenReviewSpec is a description of the token authentication request. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audiences` -| `array (string)` -| Audiences is a list of the identifiers that the resource server presented with the token identifies as. Audience-aware token authenticators will verify that the token was intended for at least one of the audiences in this list. If no audiences are provided, the audience will default to the audience of the Kubernetes apiserver. - -| `token` -| `string` -| Token is the opaque bearer token. - -|=== -..status -Description:: - TokenReviewStatus is the result of the token authentication request. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audiences` -| `array (string)` -| Audiences are audience identifiers chosen by the authenticator that are compatible with both the TokenReview and token. An identifier is any identifier in the intersection of the TokenReviewSpec audiences and the token's audiences. A client of the TokenReview API that sets the spec.audiences field should validate that a compatible audience identifier is returned in the status.audiences field to ensure that the TokenReview server is audience aware. If a TokenReview returns an empty status.audience field where status.authenticated is "true", the token is valid against the audience of the Kubernetes API server. - -| `authenticated` -| `boolean` -| Authenticated indicates that the token was associated with a known user. - -| `error` -| `string` -| Error indicates that the token couldn't be checked - -| `user` -| `object` -| UserInfo holds the information about the user needed to implement the user.Info interface. - -|=== -..status.user -Description:: - UserInfo holds the information about the user needed to implement the user.Info interface. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `extra` -| `object` -| Any additional information provided by the authenticator. - -| `extra{}` -| `array (string)` -| - -| `groups` -| `array (string)` -| The names of groups this user is a part of. - -| `uid` -| `string` -| A unique value that identifies this user across time. If this user is deleted and another user by the same name is added, they will have different UIDs. - -| `username` -| `string` -| The name that uniquely identifies this user among all active users. - -|=== -..status.user.extra -Description:: - Any additional information provided by the authenticator. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/authentication.k8s.io/v1/tokenreviews` -- `POST`: create a TokenReview - - -=== /apis/authentication.k8s.io/v1/tokenreviews - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a TokenReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../authorization_apis/tokenreview-authentication-k8s-io-v1.adoc#tokenreview-authentication-k8s-io-v1[`TokenReview authentication.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../authorization_apis/tokenreview-authentication-k8s-io-v1.adoc#tokenreview-authentication-k8s-io-v1[`TokenReview authentication.k8s.io/v1`] -| 201 - Created -| xref:../authorization_apis/tokenreview-authentication-k8s-io-v1.adoc#tokenreview-authentication-k8s-io-v1[`TokenReview authentication.k8s.io/v1`] -| 202 - Accepted -| xref:../authorization_apis/tokenreview-authentication-k8s-io-v1.adoc#tokenreview-authentication-k8s-io-v1[`TokenReview authentication.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/autoscale_apis/autoscale-apis-index.adoc b/rest_api/autoscale_apis/autoscale-apis-index.adoc deleted file mode 100644 index 56eab8109623..000000000000 --- a/rest_api/autoscale_apis/autoscale-apis-index.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="autoscale-apis"] -= Autoscale APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== ClusterAutoscaler [autoscaling.openshift.io/v1] - -Description:: - ClusterAutoscaler is the Schema for the clusterautoscalers API - -Type:: - `object` - -== MachineAutoscaler [autoscaling.openshift.io/v1beta1] - -Description:: - MachineAutoscaler is the Schema for the machineautoscalers API - -Type:: - `object` - -== HorizontalPodAutoscaler [autoscaling/v1] - -Description:: - configuration of a horizontal pod autoscaler. - -Type:: - `object` - diff --git a/rest_api/autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc b/rest_api/autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc deleted file mode 100644 index 33630553180f..000000000000 --- a/rest_api/autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc +++ /dev/null @@ -1,761 +0,0 @@ -[id="clusterautoscaler-autoscaling-openshift-io-v1"] -= ClusterAutoscaler [autoscaling.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterAutoscaler is the Schema for the clusterautoscalers API - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Desired state of ClusterAutoscaler resource - -| `status` -| `object` -| Most recently observed status of ClusterAutoscaler resource - -|=== -..spec -Description:: - Desired state of ClusterAutoscaler resource - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `balanceSimilarNodeGroups` -| `boolean` -| BalanceSimilarNodeGroups enables/disables the `--balance-similar-node-groups` cluster-autocaler feature. This feature will automatically identify node groups with the same instance type and the same set of labels and try to keep the respective sizes of those node groups balanced. - -| `ignoreDaemonsetsUtilization` -| `boolean` -| Enables/Disables `--ignore-daemonsets-utilization` CA feature flag. Should CA ignore DaemonSet pods when calculating resource utilization for scaling down. false by default - -| `maxNodeProvisionTime` -| `string` -| Maximum time CA waits for node to be provisioned - -| `maxPodGracePeriod` -| `integer` -| Gives pods graceful termination time before scaling down - -| `podPriorityThreshold` -| `integer` -| To allow users to schedule "best-effort" pods, which shouldn't trigger Cluster Autoscaler actions, but only run when there are spare resources available, More info: https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/FAQ.md#how-does-cluster-autoscaler-work-with-pod-priority-and-preemption - -| `resourceLimits` -| `object` -| Constraints of autoscaling resources - -| `scaleDown` -| `object` -| Configuration of scale down operation - -| `skipNodesWithLocalStorage` -| `boolean` -| Enables/Disables `--skip-nodes-with-local-storage` CA feature flag. If true cluster autoscaler will never delete nodes with pods with local storage, e.g. EmptyDir or HostPath. true by default at autoscaler - -|=== -..spec.resourceLimits -Description:: - Constraints of autoscaling resources - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cores` -| `object` -| Minimum and maximum number of cores in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers. - -| `gpus` -| `array` -| Minimum and maximum number of different GPUs in cluster, in the format <gpu_type>:<min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers. Can be passed multiple times. - -| `gpus[]` -| `object` -| - -| `maxNodesTotal` -| `integer` -| Maximum number of nodes in all node groups. Cluster autoscaler will not grow the cluster beyond this number. - -| `memory` -| `object` -| Minimum and maximum number of gigabytes of memory in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers. - -|=== -..spec.resourceLimits.cores -Description:: - Minimum and maximum number of cores in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers. - -Type:: - `object` - -Required:: - - `max` - - `min` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `max` -| `integer` -| - -| `min` -| `integer` -| - -|=== -..spec.resourceLimits.gpus -Description:: - Minimum and maximum number of different GPUs in cluster, in the format <gpu_type>:<min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers. Can be passed multiple times. - -Type:: - `array` - - - - -..spec.resourceLimits.gpus[] -Description:: - - -Type:: - `object` - -Required:: - - `max` - - `min` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `max` -| `integer` -| - -| `min` -| `integer` -| - -| `type` -| `string` -| - -|=== -..spec.resourceLimits.memory -Description:: - Minimum and maximum number of gigabytes of memory in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers. - -Type:: - `object` - -Required:: - - `max` - - `min` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `max` -| `integer` -| - -| `min` -| `integer` -| - -|=== -..spec.scaleDown -Description:: - Configuration of scale down operation - -Type:: - `object` - -Required:: - - `enabled` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `delayAfterAdd` -| `string` -| How long after scale up that scale down evaluation resumes - -| `delayAfterDelete` -| `string` -| How long after node deletion that scale down evaluation resumes, defaults to scan-interval - -| `delayAfterFailure` -| `string` -| How long after scale down failure that scale down evaluation resumes - -| `enabled` -| `boolean` -| Should CA scale down the cluster - -| `unneededTime` -| `string` -| How long a node should be unneeded before it is eligible for scale down - -|=== -..status -Description:: - Most recently observed status of ClusterAutoscaler resource - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/autoscaling.openshift.io/v1/clusterautoscalers` -- `DELETE`: delete collection of ClusterAutoscaler -- `GET`: list objects of kind ClusterAutoscaler -- `POST`: create a ClusterAutoscaler -* `/apis/autoscaling.openshift.io/v1/clusterautoscalers/{name}` -- `DELETE`: delete a ClusterAutoscaler -- `GET`: read the specified ClusterAutoscaler -- `PATCH`: partially update the specified ClusterAutoscaler -- `PUT`: replace the specified ClusterAutoscaler -* `/apis/autoscaling.openshift.io/v1/clusterautoscalers/{name}/status` -- `GET`: read status of the specified ClusterAutoscaler -- `PATCH`: partially update status of the specified ClusterAutoscaler -- `PUT`: replace status of the specified ClusterAutoscaler - - -=== /apis/autoscaling.openshift.io/v1/clusterautoscalers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterautoscalerlist-autoscaling-openshift-io-v1[`ClusterAutoscalerList autoscaling.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 201 - Created -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 202 - Accepted -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/autoscaling.openshift.io/v1/clusterautoscalers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterAutoscaler -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 201 - Created -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/autoscaling.openshift.io/v1/clusterautoscalers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterAutoscaler -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ClusterAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 201 - Created -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`ClusterAutoscaler autoscaling.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc b/rest_api/autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc deleted file mode 100644 index d8d200204de6..000000000000 --- a/rest_api/autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc +++ /dev/null @@ -1,731 +0,0 @@ -[id="horizontalpodautoscaler-autoscaling-v1"] -= HorizontalPodAutoscaler [autoscaling/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - configuration of a horizontal pod autoscaler. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| specification of a horizontal pod autoscaler. - -| `status` -| `object` -| current status of a horizontal pod autoscaler - -|=== -..spec -Description:: - specification of a horizontal pod autoscaler. - -Type:: - `object` - -Required:: - - `scaleTargetRef` - - `maxReplicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxReplicas` -| `integer` -| upper limit for the number of pods that can be set by the autoscaler; cannot be smaller than MinReplicas. - -| `minReplicas` -| `integer` -| minReplicas is the lower limit for the number of replicas to which the autoscaler can scale down. It defaults to 1 pod. minReplicas is allowed to be 0 if the alpha feature gate HPAScaleToZero is enabled and at least one Object or External metric is configured. Scaling is active as long as at least one metric value is available. - -| `scaleTargetRef` -| `object` -| CrossVersionObjectReference contains enough information to let you identify the referred resource. - -| `targetCPUUtilizationPercentage` -| `integer` -| target average CPU utilization (represented as a percentage of requested CPU) over all the pods; if not specified the default autoscaling policy will be used. - -|=== -..spec.scaleTargetRef -Description:: - CrossVersionObjectReference contains enough information to let you identify the referred resource. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent - -| `kind` -| `string` -| Kind of the referent; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds" - -| `name` -| `string` -| Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names - -|=== -..status -Description:: - current status of a horizontal pod autoscaler - -Type:: - `object` - -Required:: - - `currentReplicas` - - `desiredReplicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `currentCPUUtilizationPercentage` -| `integer` -| current average CPU utilization over all pods, represented as a percentage of requested CPU, e.g. 70 means that an average pod is using now 70% of its requested CPU. - -| `currentReplicas` -| `integer` -| current number of replicas of pods managed by this autoscaler. - -| `desiredReplicas` -| `integer` -| desired number of replicas of pods managed by this autoscaler. - -| `lastScaleTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| last time the HorizontalPodAutoscaler scaled the number of pods; used by the autoscaler to control how often the number of pods is changed. - -| `observedGeneration` -| `integer` -| most recent generation observed by this autoscaler. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/autoscaling/v1/horizontalpodautoscalers` -- `GET`: list or watch objects of kind HorizontalPodAutoscaler -* `/apis/autoscaling/v1/namespaces/{namespace}/horizontalpodautoscalers` -- `DELETE`: delete collection of HorizontalPodAutoscaler -- `GET`: list or watch objects of kind HorizontalPodAutoscaler -- `POST`: create a HorizontalPodAutoscaler -* `/apis/autoscaling/v1/namespaces/{namespace}/horizontalpodautoscalers/{name}` -- `DELETE`: delete a HorizontalPodAutoscaler -- `GET`: read the specified HorizontalPodAutoscaler -- `PATCH`: partially update the specified HorizontalPodAutoscaler -- `PUT`: replace the specified HorizontalPodAutoscaler -* `/apis/autoscaling/v1/namespaces/{namespace}/horizontalpodautoscalers/{name}/status` -- `GET`: read status of the specified HorizontalPodAutoscaler -- `PATCH`: partially update status of the specified HorizontalPodAutoscaler -- `PUT`: replace status of the specified HorizontalPodAutoscaler - - -=== /apis/autoscaling/v1/horizontalpodautoscalers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind HorizontalPodAutoscaler - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#horizontalpodautoscalerlist-autoscaling-v1[`HorizontalPodAutoscalerList autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/autoscaling/v1/namespaces/{namespace}/horizontalpodautoscalers - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#horizontalpodautoscalerlist-autoscaling-v1[`HorizontalPodAutoscalerList autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 201 - Created -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 202 - Accepted -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/autoscaling/v1/namespaces/{namespace}/horizontalpodautoscalers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the HorizontalPodAutoscaler -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 201 - Created -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/autoscaling/v1/namespaces/{namespace}/horizontalpodautoscalers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the HorizontalPodAutoscaler -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified HorizontalPodAutoscaler - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified HorizontalPodAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 201 - Created -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`HorizontalPodAutoscaler autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc b/rest_api/autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc deleted file mode 100644 index f6723a383014..000000000000 --- a/rest_api/autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc +++ /dev/null @@ -1,730 +0,0 @@ -[id="machineautoscaler-autoscaling-openshift-io-v1beta1"] -= MachineAutoscaler [autoscaling.openshift.io/v1beta1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - MachineAutoscaler is the Schema for the machineautoscalers API - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of constraints of a scalable resource - -| `status` -| `object` -| Most recently observed status of a scalable resource - -|=== -..spec -Description:: - Specification of constraints of a scalable resource - -Type:: - `object` - -Required:: - - `maxReplicas` - - `minReplicas` - - `scaleTargetRef` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxReplicas` -| `integer` -| MaxReplicas constrains the maximal number of replicas of a scalable resource - -| `minReplicas` -| `integer` -| MinReplicas constrains the minimal number of replicas of a scalable resource - -| `scaleTargetRef` -| `object` -| ScaleTargetRef holds reference to a scalable resource - -|=== -..spec.scaleTargetRef -Description:: - ScaleTargetRef holds reference to a scalable resource - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name specifies a name of an object, e.g. worker-us-east-1a. Scalable resources are expected to exist under a single namespace. - -|=== -..status -Description:: - Most recently observed status of a scalable resource - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTargetRef` -| `object` -| LastTargetRef holds reference to the recently observed scalable resource - -|=== -..status.lastTargetRef -Description:: - LastTargetRef holds reference to the recently observed scalable resource - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name specifies a name of an object, e.g. worker-us-east-1a. Scalable resources are expected to exist under a single namespace. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/autoscaling.openshift.io/v1beta1/machineautoscalers` -- `GET`: list objects of kind MachineAutoscaler -* `/apis/autoscaling.openshift.io/v1beta1/namespaces/{namespace}/machineautoscalers` -- `DELETE`: delete collection of MachineAutoscaler -- `GET`: list objects of kind MachineAutoscaler -- `POST`: create a MachineAutoscaler -* `/apis/autoscaling.openshift.io/v1beta1/namespaces/{namespace}/machineautoscalers/{name}` -- `DELETE`: delete a MachineAutoscaler -- `GET`: read the specified MachineAutoscaler -- `PATCH`: partially update the specified MachineAutoscaler -- `PUT`: replace the specified MachineAutoscaler -* `/apis/autoscaling.openshift.io/v1beta1/namespaces/{namespace}/machineautoscalers/{name}/status` -- `GET`: read status of the specified MachineAutoscaler -- `PATCH`: partially update status of the specified MachineAutoscaler -- `PUT`: replace status of the specified MachineAutoscaler - - -=== /apis/autoscaling.openshift.io/v1beta1/machineautoscalers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind MachineAutoscaler - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machineautoscalerlist-autoscaling-openshift-io-v1beta1[`MachineAutoscalerList autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/autoscaling.openshift.io/v1beta1/namespaces/{namespace}/machineautoscalers - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machineautoscalerlist-autoscaling-openshift-io-v1beta1[`MachineAutoscalerList autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 201 - Created -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 202 - Accepted -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/autoscaling.openshift.io/v1beta1/namespaces/{namespace}/machineautoscalers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineAutoscaler -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 201 - Created -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/autoscaling.openshift.io/v1beta1/namespaces/{namespace}/machineautoscalers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineAutoscaler -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified MachineAutoscaler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 201 - Created -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`MachineAutoscaler autoscaling.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/apiserver-config-openshift-io-v1.adoc b/rest_api/config_apis/apiserver-config-openshift-io-v1.adoc deleted file mode 100644 index ed3bd30e292b..000000000000 --- a/rest_api/config_apis/apiserver-config-openshift-io-v1.adoc +++ /dev/null @@ -1,781 +0,0 @@ -[id="apiserver-config-openshift-io-v1"] -= APIServer [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - APIServer holds configuration (like serving certificates, client CA and CORS domains) shared by all API servers in the system, among them especially kube-apiserver and openshift-apiserver. The canonical name of an instance is 'cluster'. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalCORSAllowedOrigins` -| `array (string)` -| additionalCORSAllowedOrigins lists additional, user-defined regular expressions describing hosts for which the API server allows access using the CORS headers. This may be needed to access the API and the integrated OAuth server from JavaScript applications. The values are regular expressions that correspond to the Golang regular expression language. - -| `audit` -| `object` -| audit specifies the settings for audit configuration to be applied to all OpenShift-provided API servers in the cluster. - -| `clientCA` -| `object` -| clientCA references a ConfigMap containing a certificate bundle for the signers that will be recognized for incoming client certificates in addition to the operator managed signers. If this is empty, then only operator managed signers are valid. You usually only have to set this if you have your own PKI you wish to honor client certificates from. The ConfigMap must exist in the openshift-config namespace and contain the following required fields: - ConfigMap.Data["ca-bundle.crt"] - CA bundle. - -| `encryption` -| `object` -| encryption allows the configuration of encryption of resources at the datastore layer. - -| `servingCerts` -| `object` -| servingCert is the TLS cert info for serving secure traffic. If not specified, operator managed certificates will be used for serving secure traffic. - -| `tlsSecurityProfile` -| `object` -| tlsSecurityProfile specifies settings for TLS connections for externally exposed servers. - If unset, a default (which may change between releases) is chosen. Note that only Old and Intermediate profiles are currently supported, and the maximum available MinTLSVersions is VersionTLS12. - -|=== -..spec.audit -Description:: - audit specifies the settings for audit configuration to be applied to all OpenShift-provided API servers in the cluster. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `profile` -| `string` -| profile specifies the name of the desired audit policy configuration to be deployed to all OpenShift-provided API servers in the cluster. - The following profiles are provided: - Default: the existing default policy. - WriteRequestBodies: like 'Default', but logs request and response HTTP payloads for write requests (create, update, patch). - AllRequestBodies: like 'WriteRequestBodies', but also logs request and response HTTP payloads for read requests (get, list). - If unset, the 'Default' profile is used as the default. - -|=== -..spec.clientCA -Description:: - clientCA references a ConfigMap containing a certificate bundle for the signers that will be recognized for incoming client certificates in addition to the operator managed signers. If this is empty, then only operator managed signers are valid. You usually only have to set this if you have your own PKI you wish to honor client certificates from. The ConfigMap must exist in the openshift-config namespace and contain the following required fields: - ConfigMap.Data["ca-bundle.crt"] - CA bundle. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.encryption -Description:: - encryption allows the configuration of encryption of resources at the datastore layer. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `type` -| `string` -| type defines what encryption type should be used to encrypt resources at the datastore layer. When this field is unset (i.e. when it is set to the empty string), identity is implied. The behavior of unset can and will change over time. Even if encryption is enabled by default, the meaning of unset may change to a different encryption type based on changes in best practices. - When encryption is enabled, all sensitive resources shipped with the platform are encrypted. This list of sensitive resources can and will change over time. The current authoritative list is: - 1. secrets 2. configmaps 3. routes.route.openshift.io 4. oauthaccesstokens.oauth.openshift.io 5. oauthauthorizetokens.oauth.openshift.io - -|=== -..spec.servingCerts -Description:: - servingCert is the TLS cert info for serving secure traffic. If not specified, operator managed certificates will be used for serving secure traffic. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namedCertificates` -| `array` -| namedCertificates references secrets containing the TLS cert info for serving secure traffic to specific hostnames. If no named certificates are provided, or no named certificates match the server name as understood by a client, the defaultServingCertificate will be used. - -| `namedCertificates[]` -| `object` -| APIServerNamedServingCert maps a server DNS name, as understood by a client, to a certificate. - -|=== -..spec.servingCerts.namedCertificates -Description:: - namedCertificates references secrets containing the TLS cert info for serving secure traffic to specific hostnames. If no named certificates are provided, or no named certificates match the server name as understood by a client, the defaultServingCertificate will be used. - -Type:: - `array` - - - - -..spec.servingCerts.namedCertificates[] -Description:: - APIServerNamedServingCert maps a server DNS name, as understood by a client, to a certificate. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `names` -| `array (string)` -| names is a optional list of explicit DNS names (leading wildcards allowed) that should use this certificate to serve secure traffic. If no names are provided, the implicit names will be extracted from the certificates. Exact names trump over wildcard names. Explicit names defined here trump over extracted implicit names. - -| `servingCertificate` -| `object` -| servingCertificate references a kubernetes.io/tls type secret containing the TLS cert info for serving secure traffic. The secret must exist in the openshift-config namespace and contain the following required fields: - Secret.Data["tls.key"] - TLS private key. - Secret.Data["tls.crt"] - TLS certificate. - -|=== -..spec.servingCerts.namedCertificates[].servingCertificate -Description:: - servingCertificate references a kubernetes.io/tls type secret containing the TLS cert info for serving secure traffic. The secret must exist in the openshift-config namespace and contain the following required fields: - Secret.Data["tls.key"] - TLS private key. - Secret.Data["tls.crt"] - TLS certificate. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.tlsSecurityProfile -Description:: - tlsSecurityProfile specifies settings for TLS connections for externally exposed servers. - If unset, a default (which may change between releases) is chosen. Note that only Old and Intermediate profiles are currently supported, and the maximum available MinTLSVersions is VersionTLS12. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `custom` -| `` -| custom is a user-defined TLS security profile. Be extremely careful using a custom profile as invalid configurations can be catastrophic. An example custom profile looks like this: - ciphers: - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 minTLSVersion: TLSv1.1 - -| `intermediate` -| `` -| intermediate is a TLS security profile based on: - https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29 - and looks like this (yaml): - ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - DHE-RSA-AES128-GCM-SHA256 - DHE-RSA-AES256-GCM-SHA384 minTLSVersion: TLSv1.2 - -| `modern` -| `` -| modern is a TLS security profile based on: - https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility - and looks like this (yaml): - ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 minTLSVersion: TLSv1.3 - NOTE: Currently unsupported. - -| `old` -| `` -| old is a TLS security profile based on: - https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility - and looks like this (yaml): - ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - DHE-RSA-AES128-GCM-SHA256 - DHE-RSA-AES256-GCM-SHA384 - DHE-RSA-CHACHA20-POLY1305 - ECDHE-ECDSA-AES128-SHA256 - ECDHE-RSA-AES128-SHA256 - ECDHE-ECDSA-AES128-SHA - ECDHE-RSA-AES128-SHA - ECDHE-ECDSA-AES256-SHA384 - ECDHE-RSA-AES256-SHA384 - ECDHE-ECDSA-AES256-SHA - ECDHE-RSA-AES256-SHA - DHE-RSA-AES128-SHA256 - DHE-RSA-AES256-SHA256 - AES128-GCM-SHA256 - AES256-GCM-SHA384 - AES128-SHA256 - AES256-SHA256 - AES128-SHA - AES256-SHA - DES-CBC3-SHA minTLSVersion: TLSv1.0 - -| `type` -| `string` -| type is one of Old, Intermediate, Modern or Custom. Custom provides the ability to specify individual TLS security profile parameters. Old, Intermediate and Modern are TLS security profiles based on: - https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations - The profiles are intent based, so they may change over time as new ciphers are developed and existing ciphers are found to be insecure. Depending on precisely which ciphers are available to a process, the list may be reduced. - Note that the Modern profile is currently not supported because it is not yet well adopted by common software libraries. - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/apiservers` -- `DELETE`: delete collection of APIServer -- `GET`: list objects of kind APIServer -- `POST`: create an APIServer -* `/apis/config.openshift.io/v1/apiservers/{name}` -- `DELETE`: delete an APIServer -- `GET`: read the specified APIServer -- `PATCH`: partially update the specified APIServer -- `PUT`: replace the specified APIServer -* `/apis/config.openshift.io/v1/apiservers/{name}/status` -- `GET`: read status of the specified APIServer -- `PATCH`: partially update status of the specified APIServer -- `PUT`: replace status of the specified APIServer - - -=== /apis/config.openshift.io/v1/apiservers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#apiserverlist-config-openshift-io-v1[`APIServerList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/apiservers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the APIServer -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/apiservers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the APIServer -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified APIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`APIServer config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/authentication-config-openshift-io-v1.adoc b/rest_api/config_apis/authentication-config-openshift-io-v1.adoc deleted file mode 100644 index 05ad6e2bcce8..000000000000 --- a/rest_api/config_apis/authentication-config-openshift-io-v1.adoc +++ /dev/null @@ -1,739 +0,0 @@ -[id="authentication-config-openshift-io-v1"] -= Authentication [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Authentication specifies cluster-wide settings for authentication (like OAuth and webhook token authenticators). The canonical name of an instance is `cluster`. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `oauthMetadata` -| `object` -| oauthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for an external OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 If oauthMetadata.name is non-empty, this value has precedence over any metadata reference stored in status. The key "oauthMetadata" is used to locate the data. If specified and the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config. - -| `serviceAccountIssuer` -| `string` -| serviceAccountIssuer is the identifier of the bound service account token issuer. The default is https://kubernetes.default.svc WARNING: Updating this field will result in the invalidation of all bound tokens with the previous issuer value. Unless the holder of a bound token has explicit support for a change in issuer, they will not request a new bound token until pod restart or until their existing token exceeds 80% of its duration. - -| `type` -| `string` -| type identifies the cluster managed, user facing authentication mode in use. Specifically, it manages the component that responds to login attempts. The default is IntegratedOAuth. - -| `webhookTokenAuthenticator` -| `object` -| webhookTokenAuthenticator configures a remote token reviewer. These remote authentication webhooks can be used to verify bearer tokens via the tokenreviews.authentication.k8s.io REST API. This is required to honor bearer tokens that are provisioned by an external authentication service. - -| `webhookTokenAuthenticators` -| `array` -| webhookTokenAuthenticators is DEPRECATED, setting it has no effect. - -| `webhookTokenAuthenticators[]` -| `object` -| deprecatedWebhookTokenAuthenticator holds the necessary configuration options for a remote token authenticator. It's the same as WebhookTokenAuthenticator but it's missing the 'required' validation on KubeConfig field. - -|=== -..spec.oauthMetadata -Description:: - oauthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for an external OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 If oauthMetadata.name is non-empty, this value has precedence over any metadata reference stored in status. The key "oauthMetadata" is used to locate the data. If specified and the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.webhookTokenAuthenticator -Description:: - webhookTokenAuthenticator configures a remote token reviewer. These remote authentication webhooks can be used to verify bearer tokens via the tokenreviews.authentication.k8s.io REST API. This is required to honor bearer tokens that are provisioned by an external authentication service. - -Type:: - `object` - -Required:: - - `kubeConfig` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kubeConfig` -| `object` -| kubeConfig references a secret that contains kube config file data which describes how to access the remote webhook service. The namespace for the referenced secret is openshift-config. - For further details, see: - https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication - The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored. - -|=== -..spec.webhookTokenAuthenticator.kubeConfig -Description:: - kubeConfig references a secret that contains kube config file data which describes how to access the remote webhook service. The namespace for the referenced secret is openshift-config. - For further details, see: - https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication - The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.webhookTokenAuthenticators -Description:: - webhookTokenAuthenticators is DEPRECATED, setting it has no effect. - -Type:: - `array` - - - - -..spec.webhookTokenAuthenticators[] -Description:: - deprecatedWebhookTokenAuthenticator holds the necessary configuration options for a remote token authenticator. It's the same as WebhookTokenAuthenticator but it's missing the 'required' validation on KubeConfig field. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kubeConfig` -| `object` -| kubeConfig contains kube config file data which describes how to access the remote webhook service. For further details, see: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored. The namespace for this secret is determined by the point of use. - -|=== -..spec.webhookTokenAuthenticators[].kubeConfig -Description:: - kubeConfig contains kube config file data which describes how to access the remote webhook service. For further details, see: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication The key "kubeConfig" is used to locate the data. If the secret or expected key is not found, the webhook is not honored. If the specified kube config data is not valid, the webhook is not honored. The namespace for this secret is determined by the point of use. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `integratedOAuthMetadata` -| `object` -| integratedOAuthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for the in-cluster integrated OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 This contains the observed value based on cluster state. An explicitly set value in spec.oauthMetadata has precedence over this field. This field has no meaning if authentication spec.type is not set to IntegratedOAuth. The key "oauthMetadata" is used to locate the data. If the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config-managed. - -|=== -..status.integratedOAuthMetadata -Description:: - integratedOAuthMetadata contains the discovery endpoint data for OAuth 2.0 Authorization Server Metadata for the in-cluster integrated OAuth server. This discovery document can be viewed from its served location: oc get --raw '/.well-known/oauth-authorization-server' For further details, see the IETF Draft: https://tools.ietf.org/html/draft-ietf-oauth-discovery-04#section-2 This contains the observed value based on cluster state. An explicitly set value in spec.oauthMetadata has precedence over this field. This field has no meaning if authentication spec.type is not set to IntegratedOAuth. The key "oauthMetadata" is used to locate the data. If the config map or expected key is not found, no metadata is served. If the specified metadata is not valid, no metadata is served. The namespace for this config map is openshift-config-managed. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/authentications` -- `DELETE`: delete collection of Authentication -- `GET`: list objects of kind Authentication -- `POST`: create an Authentication -* `/apis/config.openshift.io/v1/authentications/{name}` -- `DELETE`: delete an Authentication -- `GET`: read the specified Authentication -- `PATCH`: partially update the specified Authentication -- `PUT`: replace the specified Authentication -* `/apis/config.openshift.io/v1/authentications/{name}/status` -- `GET`: read status of the specified Authentication -- `PATCH`: partially update status of the specified Authentication -- `PUT`: replace status of the specified Authentication - - -=== /apis/config.openshift.io/v1/authentications - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#authenticationlist-config-openshift-io-v1[`AuthenticationList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/authentications/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Authentication -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/authentications/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Authentication -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`Authentication config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/build-config-openshift-io-v1.adoc b/rest_api/config_apis/build-config-openshift-io-v1.adoc deleted file mode 100644 index 206bc76b19bc..000000000000 --- a/rest_api/config_apis/build-config-openshift-io-v1.adoc +++ /dev/null @@ -1,1110 +0,0 @@ -[id="build-config-openshift-io-v1"] -= Build [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Build configures the behavior of OpenShift builds for the entire cluster. This includes default settings that can be overridden in BuildConfig objects, and overrides which are applied to all builds. - The canonical name is "cluster" - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Spec holds user-settable values for the build controller configuration - -|=== -..spec -Description:: - Spec holds user-settable values for the build controller configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalTrustedCA` -| `object` -| AdditionalTrustedCA is a reference to a ConfigMap containing additional CAs that should be trusted for image pushes and pulls during builds. The namespace for this config map is openshift-config. - DEPRECATED: Additional CAs for image pull and push should be set on image.config.openshift.io/cluster instead. - -| `buildDefaults` -| `object` -| BuildDefaults controls the default information for Builds - -| `buildOverrides` -| `object` -| BuildOverrides controls override settings for builds - -|=== -..spec.additionalTrustedCA -Description:: - AdditionalTrustedCA is a reference to a ConfigMap containing additional CAs that should be trusted for image pushes and pulls during builds. The namespace for this config map is openshift-config. - DEPRECATED: Additional CAs for image pull and push should be set on image.config.openshift.io/cluster instead. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.buildDefaults -Description:: - BuildDefaults controls the default information for Builds - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultProxy` -| `object` -| DefaultProxy contains the default proxy settings for all build operations, including image pull/push and source download. - Values can be overrode by setting the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables in the build config's strategy. - -| `env` -| `array` -| Env is a set of default environment variables that will be applied to the build if the specified variables do not exist on the build - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `gitProxy` -| `object` -| GitProxy contains the proxy settings for git operations only. If set, this will override any Proxy settings for all git commands, such as git clone. - Values that are not set here will be inherited from DefaultProxy. - -| `imageLabels` -| `array` -| ImageLabels is a list of docker labels that are applied to the resulting image. User can override a default label by providing a label with the same name in their Build/BuildConfig. - -| `imageLabels[]` -| `object` -| - -| `resources` -| `object` -| Resources defines resource requirements to execute the build. - -|=== -..spec.buildDefaults.defaultProxy -Description:: - DefaultProxy contains the default proxy settings for all build operations, including image pull/push and source download. - Values can be overrode by setting the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables in the build config's strategy. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `httpProxy` -| `string` -| httpProxy is the URL of the proxy for HTTP requests. Empty means unset and will not result in an env var. - -| `httpsProxy` -| `string` -| httpsProxy is the URL of the proxy for HTTPS requests. Empty means unset and will not result in an env var. - -| `noProxy` -| `string` -| noProxy is a comma-separated list of hostnames and/or CIDRs for which the proxy should not be used. Empty means unset and will not result in an env var. - -| `readinessEndpoints` -| `array (string)` -| readinessEndpoints is a list of endpoints used to verify readiness of the proxy. - -| `trustedCA` -| `object` -| trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. - The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): - apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: \| -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE----- - -|=== -..spec.buildDefaults.defaultProxy.trustedCA -Description:: - trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. - The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): - apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: | -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE----- - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.buildDefaults.env -Description:: - Env is a set of default environment variables that will be applied to the build if the specified variables do not exist on the build - -Type:: - `array` - - - - -..spec.buildDefaults.env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.buildDefaults.env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.buildDefaults.env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.buildDefaults.env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.buildDefaults.env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.buildDefaults.env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.buildDefaults.gitProxy -Description:: - GitProxy contains the proxy settings for git operations only. If set, this will override any Proxy settings for all git commands, such as git clone. - Values that are not set here will be inherited from DefaultProxy. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `httpProxy` -| `string` -| httpProxy is the URL of the proxy for HTTP requests. Empty means unset and will not result in an env var. - -| `httpsProxy` -| `string` -| httpsProxy is the URL of the proxy for HTTPS requests. Empty means unset and will not result in an env var. - -| `noProxy` -| `string` -| noProxy is a comma-separated list of hostnames and/or CIDRs for which the proxy should not be used. Empty means unset and will not result in an env var. - -| `readinessEndpoints` -| `array (string)` -| readinessEndpoints is a list of endpoints used to verify readiness of the proxy. - -| `trustedCA` -| `object` -| trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. - The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): - apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: \| -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE----- - -|=== -..spec.buildDefaults.gitProxy.trustedCA -Description:: - trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. - The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): - apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: | -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE----- - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.buildDefaults.imageLabels -Description:: - ImageLabels is a list of docker labels that are applied to the resulting image. User can override a default label by providing a label with the same name in their Build/BuildConfig. - -Type:: - `array` - - - - -..spec.buildDefaults.imageLabels[] -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name defines the name of the label. It must have non-zero length. - -| `value` -| `string` -| Value defines the literal value of the label. - -|=== -..spec.buildDefaults.resources -Description:: - Resources defines resource requirements to execute the build. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.buildOverrides -Description:: - BuildOverrides controls override settings for builds - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `forcePull` -| `boolean` -| ForcePull overrides, if set, the equivalent value in the builds, i.e. false disables force pull for all builds, true enables force pull for all builds, independently of what each build specifies itself - -| `imageLabels` -| `array` -| ImageLabels is a list of docker labels that are applied to the resulting image. If user provided a label in their Build/BuildConfig with the same name as one in this list, the user's label will be overwritten. - -| `imageLabels[]` -| `object` -| - -| `nodeSelector` -| `object (string)` -| NodeSelector is a selector which must be true for the build pod to fit on a node - -| `tolerations` -| `array` -| Tolerations is a list of Tolerations that will override any existing tolerations set on a build pod. - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -|=== -..spec.buildOverrides.imageLabels -Description:: - ImageLabels is a list of docker labels that are applied to the resulting image. If user provided a label in their Build/BuildConfig with the same name as one in this list, the user's label will be overwritten. - -Type:: - `array` - - - - -..spec.buildOverrides.imageLabels[] -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name defines the name of the label. It must have non-zero length. - -| `value` -| `string` -| Value defines the literal value of the label. - -|=== -..spec.buildOverrides.tolerations -Description:: - Tolerations is a list of Tolerations that will override any existing tolerations set on a build pod. - -Type:: - `array` - - - - -..spec.buildOverrides.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/builds` -- `DELETE`: delete collection of Build -- `GET`: list objects of kind Build -- `POST`: create a Build -* `/apis/config.openshift.io/v1/builds/{name}` -- `DELETE`: delete a Build -- `GET`: read the specified Build -- `PATCH`: partially update the specified Build -- `PUT`: replace the specified Build -* `/apis/config.openshift.io/v1/builds/{name}/status` -- `GET`: read status of the specified Build -- `PATCH`: partially update status of the specified Build -- `PUT`: replace status of the specified Build - - -=== /apis/config.openshift.io/v1/builds - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#buildlist-config-openshift-io-v1[`BuildList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/builds/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Build -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/builds/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Build -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`Build config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/clusteroperator-config-openshift-io-v1.adoc b/rest_api/config_apis/clusteroperator-config-openshift-io-v1.adoc deleted file mode 100644 index 43ad0bc67d3f..000000000000 --- a/rest_api/config_apis/clusteroperator-config-openshift-io-v1.adoc +++ /dev/null @@ -1,724 +0,0 @@ -[id="clusteroperator-config-openshift-io-v1"] -= ClusterOperator [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterOperator is the Custom Resource object which holds the current state of an operator. This object is used by operators to convey their state to the rest of the cluster. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds configuration that could apply to any operator. - -| `status` -| `object` -| status holds the information about the state of an operator. It is consistent with status information across the Kubernetes ecosystem. - -|=== -..spec -Description:: - spec holds configuration that could apply to any operator. - -Type:: - `object` - - - - -..status -Description:: - status holds the information about the state of an operator. It is consistent with status information across the Kubernetes ecosystem. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions describes the state of the operator's managed and monitored components. - -| `conditions[]` -| `object` -| ClusterOperatorStatusCondition represents the state of the operator's managed and monitored components. - -| `extension` -| `` -| extension contains any additional status information specific to the operator which owns this status object. - -| `relatedObjects` -| `array` -| relatedObjects is a list of objects that are "interesting" or related to this operator. Common uses are: 1. the detailed resource driving the operator 2. operator namespaces 3. operand namespaces - -| `relatedObjects[]` -| `object` -| ObjectReference contains enough information to let you inspect or modify the referred object. - -| `versions` -| `array` -| versions is a slice of operator and operand version tuples. Operators which manage multiple operands will have multiple operand entries in the array. Available operators must report the version of the operator itself with the name "operator". An operator reports a new "operator" version when it has rolled out the new version to all of its operands. - -| `versions[]` -| `object` -| - -|=== -..status.conditions -Description:: - conditions describes the state of the operator's managed and monitored components. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - ClusterOperatorStatusCondition represents the state of the operator's managed and monitored components. - -Type:: - `object` - -Required:: - - `lastTransitionTime` - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| lastTransitionTime is the time of the last update to the current status property. - -| `message` -| `string` -| message provides additional information about the current condition. This is only to be consumed by humans. - -| `reason` -| `string` -| reason is the CamelCase reason for the condition's current status. - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type specifies the aspect reported by this condition. - -|=== -..status.relatedObjects -Description:: - relatedObjects is a list of objects that are "interesting" or related to this operator. Common uses are: 1. the detailed resource driving the operator 2. operator namespaces 3. operand namespaces - -Type:: - `array` - - - - -..status.relatedObjects[] -Description:: - ObjectReference contains enough information to let you inspect or modify the referred object. - -Type:: - `object` - -Required:: - - `group` - - `name` - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group of the referent. - -| `name` -| `string` -| name of the referent. - -| `namespace` -| `string` -| namespace of the referent. - -| `resource` -| `string` -| resource of the referent. - -|=== -..status.versions -Description:: - versions is a slice of operator and operand version tuples. Operators which manage multiple operands will have multiple operand entries in the array. Available operators must report the version of the operator itself with the name "operator". An operator reports a new "operator" version when it has rolled out the new version to all of its operands. - -Type:: - `array` - - - - -..status.versions[] -Description:: - - -Type:: - `object` - -Required:: - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the name of the particular operand this version is for. It usually matches container images, not operators. - -| `version` -| `string` -| version indicates which version of a particular operand is currently being managed. It must always match the Available operand. If 1.0.0 is Available, then this must indicate 1.0.0 even if the operator is trying to rollout 1.1.0 - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/clusteroperators` -- `DELETE`: delete collection of ClusterOperator -- `GET`: list objects of kind ClusterOperator -- `POST`: create a ClusterOperator -* `/apis/config.openshift.io/v1/clusteroperators/{name}` -- `DELETE`: delete a ClusterOperator -- `GET`: read the specified ClusterOperator -- `PATCH`: partially update the specified ClusterOperator -- `PUT`: replace the specified ClusterOperator -* `/apis/config.openshift.io/v1/clusteroperators/{name}/status` -- `GET`: read status of the specified ClusterOperator -- `PATCH`: partially update status of the specified ClusterOperator -- `PUT`: replace status of the specified ClusterOperator - - -=== /apis/config.openshift.io/v1/clusteroperators - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusteroperatorlist-config-openshift-io-v1[`ClusterOperatorList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/clusteroperators/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterOperator -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/clusteroperators/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterOperator -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ClusterOperator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`ClusterOperator config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc b/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc deleted file mode 100644 index 2f850832f36e..000000000000 --- a/rest_api/config_apis/clusterversion-config-openshift-io-v1.adoc +++ /dev/null @@ -1,848 +0,0 @@ -[id="clusterversion-config-openshift-io-v1"] -= ClusterVersion [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterVersion is the configuration for the ClusterVersionOperator. This is where parameters related to automatic updates can be set. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the desired state of the cluster version - the operator will work to ensure that the desired version is applied to the cluster. - -| `status` -| `object` -| status contains information about the available updates and any in-progress updates. - -|=== -..spec -Description:: - spec is the desired state of the cluster version - the operator will work to ensure that the desired version is applied to the cluster. - -Type:: - `object` - -Required:: - - `clusterID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `channel` -| `string` -| channel is an identifier for explicitly requesting that a non-default set of updates be applied to this cluster. The default channel will be contain stable updates that are appropriate for production clusters. - -| `clusterID` -| `string` -| clusterID uniquely identifies this cluster. This is expected to be an RFC4122 UUID value (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx in hexadecimal values). This is a required field. - -| `desiredUpdate` -| `object` -| desiredUpdate is an optional field that indicates the desired value of the cluster version. Setting this value will trigger an upgrade (if the current version does not match the desired version). The set of recommended update values is listed as part of available updates in status, and setting values outside that range may cause the upgrade to fail. You may specify the version field without setting image if an update exists with that version in the availableUpdates or history. - If an upgrade fails the operator will halt and report status about the failing component. Setting the desired update value back to the previous version will cause a rollback to be attempted. Not all rollbacks will succeed. - -| `overrides` -| `array` -| overrides is list of overides for components that are managed by cluster version operator. Marking a component unmanaged will prevent the operator from creating or updating the object. - -| `overrides[]` -| `object` -| ComponentOverride allows overriding cluster version operator's behavior for a component. - -| `upstream` -| `string` -| upstream may be used to specify the preferred update server. By default it will use the appropriate update server for the cluster and region. - -|=== -..spec.desiredUpdate -Description:: - desiredUpdate is an optional field that indicates the desired value of the cluster version. Setting this value will trigger an upgrade (if the current version does not match the desired version). The set of recommended update values is listed as part of available updates in status, and setting values outside that range may cause the upgrade to fail. You may specify the version field without setting image if an update exists with that version in the availableUpdates or history. - If an upgrade fails the operator will halt and report status about the failing component. Setting the desired update value back to the previous version will cause a rollback to be attempted. Not all rollbacks will succeed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `force` -| `boolean` -| force allows an administrator to update to an image that has failed verification, does not appear in the availableUpdates list, or otherwise would be blocked by normal protections on update. This option should only be used when the authenticity of the provided image has been verified out of band because the provided image will run with full administrative access to the cluster. Do not use this flag with images that comes from unknown or potentially malicious sources. - This flag does not override other forms of consistency checking that are required before a new update is deployed. - -| `image` -| `string` -| image is a container image location that contains the update. When this field is part of spec, image is optional if version is specified and the availableUpdates field contains a matching version. - -| `version` -| `string` -| version is a semantic versioning identifying the update version. When this field is part of spec, version is optional if image is specified. - -|=== -..spec.overrides -Description:: - overrides is list of overides for components that are managed by cluster version operator. Marking a component unmanaged will prevent the operator from creating or updating the object. - -Type:: - `array` - - - - -..spec.overrides[] -Description:: - ComponentOverride allows overriding cluster version operator's behavior for a component. - -Type:: - `object` - -Required:: - - `group` - - `kind` - - `name` - - `namespace` - - `unmanaged` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group identifies the API group that the kind is in. - -| `kind` -| `string` -| kind indentifies which object to override. - -| `name` -| `string` -| name is the component's name. - -| `namespace` -| `string` -| namespace is the component's namespace. If the resource is cluster scoped, the namespace should be empty. - -| `unmanaged` -| `boolean` -| unmanaged controls if cluster version operator should stop managing the resources in this cluster. Default: false - -|=== -..status -Description:: - status contains information about the available updates and any in-progress updates. - -Type:: - `object` - -Required:: - - `desired` - - `observedGeneration` - - `versionHash` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableUpdates` -| `` -| availableUpdates contains the list of updates that are appropriate for this cluster. This list may be empty if no updates are recommended, if the update service is unavailable, or if an invalid channel has been specified. - -| `conditions` -| `array` -| conditions provides information about the cluster version. The condition "Available" is set to true if the desiredUpdate has been reached. The condition "Progressing" is set to true if an update is being applied. The condition "Degraded" is set to true if an update is currently blocked by a temporary or permanent error. Conditions are only valid for the current desiredUpdate when metadata.generation is equal to status.generation. - -| `conditions[]` -| `object` -| ClusterOperatorStatusCondition represents the state of the operator's managed and monitored components. - -| `desired` -| `object` -| desired is the version that the cluster is reconciling towards. If the cluster is not yet fully initialized desired will be set with the information available, which may be an image or a tag. - -| `history` -| `array` -| history contains a list of the most recent versions applied to the cluster. This value may be empty during cluster startup, and then will be updated when a new update is being applied. The newest update is first in the list and it is ordered by recency. Updates in the history have state Completed if the rollout completed - if an update was failing or halfway applied the state will be Partial. Only a limited amount of update history is preserved. - -| `history[]` -| `object` -| UpdateHistory is a single attempted update to the cluster. - -| `observedGeneration` -| `integer` -| observedGeneration reports which version of the spec is being synced. If this value is not equal to metadata.generation, then the desired and conditions fields may represent a previous version. - -| `versionHash` -| `string` -| versionHash is a fingerprint of the content that the cluster will be updated with. It is used by the operator to avoid unnecessary work and is for internal use only. - -|=== -..status.conditions -Description:: - conditions provides information about the cluster version. The condition "Available" is set to true if the desiredUpdate has been reached. The condition "Progressing" is set to true if an update is being applied. The condition "Degraded" is set to true if an update is currently blocked by a temporary or permanent error. Conditions are only valid for the current desiredUpdate when metadata.generation is equal to status.generation. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - ClusterOperatorStatusCondition represents the state of the operator's managed and monitored components. - -Type:: - `object` - -Required:: - - `lastTransitionTime` - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| lastTransitionTime is the time of the last update to the current status property. - -| `message` -| `string` -| message provides additional information about the current condition. This is only to be consumed by humans. - -| `reason` -| `string` -| reason is the CamelCase reason for the condition's current status. - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type specifies the aspect reported by this condition. - -|=== -..status.desired -Description:: - desired is the version that the cluster is reconciling towards. If the cluster is not yet fully initialized desired will be set with the information available, which may be an image or a tag. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `channels` -| `array (string)` -| channels is the set of Cincinnati channels to which the release currently belongs. - -| `image` -| `string` -| image is a container image location that contains the update. When this field is part of spec, image is optional if version is specified and the availableUpdates field contains a matching version. - -| `url` -| `string` -| url contains information about this release. This URL is set by the 'url' metadata property on a release or the metadata returned by the update API and should be displayed as a link in user interfaces. The URL field may not be set for test or nightly releases. - -| `version` -| `string` -| version is a semantic versioning identifying the update version. When this field is part of spec, version is optional if image is specified. - -|=== -..status.history -Description:: - history contains a list of the most recent versions applied to the cluster. This value may be empty during cluster startup, and then will be updated when a new update is being applied. The newest update is first in the list and it is ordered by recency. Updates in the history have state Completed if the rollout completed - if an update was failing or halfway applied the state will be Partial. Only a limited amount of update history is preserved. - -Type:: - `array` - - - - -..status.history[] -Description:: - UpdateHistory is a single attempted update to the cluster. - -Type:: - `object` - -Required:: - - `image` - - `startedTime` - - `state` - - `verified` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `completionTime` -| `` -| completionTime, if set, is when the update was fully applied. The update that is currently being applied will have a null completion time. Completion time will always be set for entries that are not the current update (usually to the started time of the next update). - -| `image` -| `string` -| image is a container image location that contains the update. This value is always populated. - -| `startedTime` -| `string` -| startedTime is the time at which the update was started. - -| `state` -| `string` -| state reflects whether the update was fully applied. The Partial state indicates the update is not fully applied, while the Completed state indicates the update was successfully rolled out at least once (all parts of the update successfully applied). - -| `verified` -| `boolean` -| verified indicates whether the provided update was properly verified before it was installed. If this is false the cluster may not be trusted. - -| `version` -| `string` -| version is a semantic versioning identifying the update version. If the requested image does not define a version, or if a failure occurs retrieving the image, this value may be empty. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/clusterversions` -- `DELETE`: delete collection of ClusterVersion -- `GET`: list objects of kind ClusterVersion -- `POST`: create a ClusterVersion -* `/apis/config.openshift.io/v1/clusterversions/{name}` -- `DELETE`: delete a ClusterVersion -- `GET`: read the specified ClusterVersion -- `PATCH`: partially update the specified ClusterVersion -- `PUT`: replace the specified ClusterVersion -* `/apis/config.openshift.io/v1/clusterversions/{name}/status` -- `GET`: read status of the specified ClusterVersion -- `PATCH`: partially update status of the specified ClusterVersion -- `PUT`: replace status of the specified ClusterVersion - - -=== /apis/config.openshift.io/v1/clusterversions - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterversionlist-config-openshift-io-v1[`ClusterVersionList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/clusterversions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterVersion -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/clusterversions/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterVersion -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ClusterVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`ClusterVersion config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/config-apis-index.adoc b/rest_api/config_apis/config-apis-index.adoc deleted file mode 100644 index 2a44b18f7432..000000000000 --- a/rest_api/config_apis/config-apis-index.adoc +++ /dev/null @@ -1,153 +0,0 @@ -[id="config-apis"] -= Config APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== APIServer [config.openshift.io/v1] - -Description:: - APIServer holds configuration (like serving certificates, client CA and CORS domains) shared by all API servers in the system, among them especially kube-apiserver and openshift-apiserver. The canonical name of an instance is 'cluster'. - -Type:: - `object` - -== Authentication [config.openshift.io/v1] - -Description:: - Authentication specifies cluster-wide settings for authentication (like OAuth and webhook token authenticators). The canonical name of an instance is `cluster`. - -Type:: - `object` - -== Build [config.openshift.io/v1] - -Description:: - Build configures the behavior of OpenShift builds for the entire cluster. This includes default settings that can be overridden in BuildConfig objects, and overrides which are applied to all builds. - The canonical name is "cluster" - -Type:: - `object` - -== ClusterOperator [config.openshift.io/v1] - -Description:: - ClusterOperator is the Custom Resource object which holds the current state of an operator. This object is used by operators to convey their state to the rest of the cluster. - -Type:: - `object` - -== ClusterVersion [config.openshift.io/v1] - -Description:: - ClusterVersion is the configuration for the ClusterVersionOperator. This is where parameters related to automatic updates can be set. - -Type:: - `object` - -== Console [config.openshift.io/v1] - -Description:: - Console holds cluster-wide configuration for the web console, including the logout URL, and reports the public URL of the console. The canonical name is `cluster`. - -Type:: - `object` - -== DNS [config.openshift.io/v1] - -Description:: - DNS holds cluster-wide information about DNS. The canonical name is `cluster` - -Type:: - `object` - -== FeatureGate [config.openshift.io/v1] - -Description:: - Feature holds cluster-wide information about feature gates. The canonical name is `cluster` - -Type:: - `object` - -== HelmChartRepository [helm.openshift.io/v1beta1] - -Description:: - HelmChartRepository holds cluster-wide configuration for proxied Helm chart repository - -Type:: - `object` - -== Image [config.openshift.io/v1] - -Description:: - Image governs policies related to imagestream imports and runtime configuration for external registries. It allows cluster admins to configure which registries OpenShift is allowed to import images from, extra CA trust bundles for external registries, and policies to block or allow registry hostnames. When exposing OpenShift's image registry to the public, this also lets cluster admins specify the external hostname. - -Type:: - `object` - -== Infrastructure [config.openshift.io/v1] - -Description:: - Infrastructure holds cluster-wide information about Infrastructure. The canonical name is `cluster` - -Type:: - `object` - -== Ingress [config.openshift.io/v1] - -Description:: - Ingress holds cluster-wide information about ingress, including the default ingress domain used for routes. The canonical name is `cluster`. - -Type:: - `object` - -== Network [config.openshift.io/v1] - -Description:: - Network holds cluster-wide information about Network. The canonical name is `cluster`. It is used to configure the desired network configuration, such as: IP address pools for services/pod IPs, network plugin, etc. Please view network.spec for an explanation on what applies when configuring this resource. - -Type:: - `object` - -== OAuth [config.openshift.io/v1] - -Description:: - OAuth holds cluster-wide information about OAuth. The canonical name is `cluster`. It is used to configure the integrated OAuth server. This configuration is only honored when the top level Authentication config has type set to IntegratedOAuth. - -Type:: - `object` - -== OperatorHub [config.openshift.io/v1] - -Description:: - OperatorHub is the Schema for the operatorhubs API. It can be used to change the state of the default hub sources for OperatorHub on the cluster from enabled to disabled and vice versa. - -Type:: - `object` - -== Project [config.openshift.io/v1] - -Description:: - Project holds cluster-wide information about Project. The canonical name is `cluster` - -Type:: - `object` - -== Proxy [config.openshift.io/v1] - -Description:: - Proxy holds cluster-wide information on how to configure default proxies for the cluster. The canonical name is `cluster` - -Type:: - `object` - -== Scheduler [config.openshift.io/v1] - -Description:: - Scheduler holds cluster-wide config information to run the Kubernetes Scheduler and influence its placement decisions. The canonical name for this config is `cluster`. - -Type:: - `object` - diff --git a/rest_api/config_apis/console-config-openshift-io-v1.adoc b/rest_api/config_apis/console-config-openshift-io-v1.adoc deleted file mode 100644 index 2c3f5a5a9888..000000000000 --- a/rest_api/config_apis/console-config-openshift-io-v1.adoc +++ /dev/null @@ -1,598 +0,0 @@ -[id="console-config-openshift-io-v1"] -= Console [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Console holds cluster-wide configuration for the web console, including the logout URL, and reports the public URL of the console. The canonical name is `cluster`. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `authentication` -| `object` -| ConsoleAuthentication defines a list of optional configuration for console authentication. - -|=== -..spec.authentication -Description:: - ConsoleAuthentication defines a list of optional configuration for console authentication. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logoutRedirect` -| `string` -| An optional, absolute URL to redirect web browsers to after logging out of the console. If not specified, it will redirect to the default login page. This is required when using an identity provider that supports single sign-on (SSO) such as: - OpenID (Keycloak, Azure) - RequestHeader (GSSAPI, SSPI, SAML) - OAuth (GitHub, GitLab, Google) Logging out of the console will destroy the user's token. The logoutRedirect provides the user the option to perform single logout (SLO) through the identity provider to destroy their single sign-on session. - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `consoleURL` -| `string` -| The URL for the console. This will be derived from the host for the route that is created for the console. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/consoles` -- `DELETE`: delete collection of Console -- `GET`: list objects of kind Console -- `POST`: create a Console -* `/apis/config.openshift.io/v1/consoles/{name}` -- `DELETE`: delete a Console -- `GET`: read the specified Console -- `PATCH`: partially update the specified Console -- `PUT`: replace the specified Console -* `/apis/config.openshift.io/v1/consoles/{name}/status` -- `GET`: read status of the specified Console -- `PATCH`: partially update status of the specified Console -- `PUT`: replace status of the specified Console - - -=== /apis/config.openshift.io/v1/consoles - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#consolelist-config-openshift-io-v1[`ConsoleList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/consoles/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Console -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/consoles/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Console -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`Console config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/dns-config-openshift-io-v1.adoc b/rest_api/config_apis/dns-config-openshift-io-v1.adoc deleted file mode 100644 index 21f3cd6a76a0..000000000000 --- a/rest_api/config_apis/dns-config-openshift-io-v1.adoc +++ /dev/null @@ -1,642 +0,0 @@ -[id="dns-config-openshift-io-v1"] -= DNS [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - DNS holds cluster-wide information about DNS. The canonical name is `cluster` - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `baseDomain` -| `string` -| baseDomain is the base domain of the cluster. All managed DNS records will be sub-domains of this base. - For example, given the base domain `openshift.example.com`, an API server DNS record may be created for `cluster-api.openshift.example.com`. - Once set, this field cannot be changed. - -| `privateZone` -| `object` -| privateZone is the location where all the DNS records that are only available internally to the cluster exist. - If this field is nil, no private records should be created. - Once set, this field cannot be changed. - -| `publicZone` -| `object` -| publicZone is the location where all the DNS records that are publicly accessible to the internet exist. - If this field is nil, no public records should be created. - Once set, this field cannot be changed. - -|=== -..spec.privateZone -Description:: - privateZone is the location where all the DNS records that are only available internally to the cluster exist. - If this field is nil, no private records should be created. - Once set, this field cannot be changed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `id` -| `string` -| id is the identifier that can be used to find the DNS hosted zone. - on AWS zone can be fetched using `ID` as id in [1] on Azure zone can be fetched using `ID` as a pre-determined name in [2], on GCP zone can be fetched using `ID` as a pre-determined name in [3]. - [1]: https://docs.aws.amazon.com/cli/latest/reference/route53/get-hosted-zone.html#options [2]: https://docs.microsoft.com/en-us/cli/azure/network/dns/zone?view=azure-cli-latest#az-network-dns-zone-show [3]: https://cloud.google.com/dns/docs/reference/v1/managedZones/get - -| `tags` -| `object (string)` -| tags can be used to query the DNS hosted zone. - on AWS, resourcegroupstaggingapi [1] can be used to fetch a zone using `Tags` as tag-filters, - [1]: https://docs.aws.amazon.com/cli/latest/reference/resourcegroupstaggingapi/get-resources.html#options - -|=== -..spec.publicZone -Description:: - publicZone is the location where all the DNS records that are publicly accessible to the internet exist. - If this field is nil, no public records should be created. - Once set, this field cannot be changed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `id` -| `string` -| id is the identifier that can be used to find the DNS hosted zone. - on AWS zone can be fetched using `ID` as id in [1] on Azure zone can be fetched using `ID` as a pre-determined name in [2], on GCP zone can be fetched using `ID` as a pre-determined name in [3]. - [1]: https://docs.aws.amazon.com/cli/latest/reference/route53/get-hosted-zone.html#options [2]: https://docs.microsoft.com/en-us/cli/azure/network/dns/zone?view=azure-cli-latest#az-network-dns-zone-show [3]: https://cloud.google.com/dns/docs/reference/v1/managedZones/get - -| `tags` -| `object (string)` -| tags can be used to query the DNS hosted zone. - on AWS, resourcegroupstaggingapi [1] can be used to fetch a zone using `Tags` as tag-filters, - [1]: https://docs.aws.amazon.com/cli/latest/reference/resourcegroupstaggingapi/get-resources.html#options - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/dnses` -- `DELETE`: delete collection of DNS -- `GET`: list objects of kind DNS -- `POST`: create a DNS -* `/apis/config.openshift.io/v1/dnses/{name}` -- `DELETE`: delete a DNS -- `GET`: read the specified DNS -- `PATCH`: partially update the specified DNS -- `PUT`: replace the specified DNS -* `/apis/config.openshift.io/v1/dnses/{name}/status` -- `GET`: read status of the specified DNS -- `PATCH`: partially update status of the specified DNS -- `PUT`: replace status of the specified DNS - - -=== /apis/config.openshift.io/v1/dnses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#dnslist-config-openshift-io-v1[`DNSList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/dnses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DNS -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/dnses/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DNS -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`DNS config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/featuregate-config-openshift-io-v1.adoc b/rest_api/config_apis/featuregate-config-openshift-io-v1.adoc deleted file mode 100644 index f31bfab9d90a..000000000000 --- a/rest_api/config_apis/featuregate-config-openshift-io-v1.adoc +++ /dev/null @@ -1,574 +0,0 @@ -[id="featuregate-config-openshift-io-v1"] -= FeatureGate [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Feature holds cluster-wide information about feature gates. The canonical name is `cluster` - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `customNoUpgrade` -| `` -| customNoUpgrade allows the enabling or disabling of any feature. Turning this feature set on IS NOT SUPPORTED, CANNOT BE UNDONE, and PREVENTS UPGRADES. Because of its nature, this setting cannot be validated. If you have any typos or accidentally apply invalid combinations your cluster may fail in an unrecoverable way. featureSet must equal "CustomNoUpgrade" must be set to use this field. - -| `featureSet` -| `string` -| featureSet changes the list of features in the cluster. The default is empty. Be very careful adjusting this setting. Turning on or off features may cause irreversible changes in your cluster which cannot be undone. - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/featuregates` -- `DELETE`: delete collection of FeatureGate -- `GET`: list objects of kind FeatureGate -- `POST`: create a FeatureGate -* `/apis/config.openshift.io/v1/featuregates/{name}` -- `DELETE`: delete a FeatureGate -- `GET`: read the specified FeatureGate -- `PATCH`: partially update the specified FeatureGate -- `PUT`: replace the specified FeatureGate -* `/apis/config.openshift.io/v1/featuregates/{name}/status` -- `GET`: read status of the specified FeatureGate -- `PATCH`: partially update status of the specified FeatureGate -- `PUT`: replace status of the specified FeatureGate - - -=== /apis/config.openshift.io/v1/featuregates - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#featuregatelist-config-openshift-io-v1[`FeatureGateList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/featuregates/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the FeatureGate -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/featuregates/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the FeatureGate -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified FeatureGate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`FeatureGate config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc b/rest_api/config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc deleted file mode 100644 index cda6174727c6..000000000000 --- a/rest_api/config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc +++ /dev/null @@ -1,721 +0,0 @@ -[id="helmchartrepository-helm-openshift-io-v1beta1"] -= HelmChartRepository [helm.openshift.io/v1beta1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - HelmChartRepository holds cluster-wide configuration for proxied Helm chart repository - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| Observed status of the repository within the cluster.. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `connectionConfig` -| `object` -| Required configuration for connecting to the chart repo - -| `description` -| `string` -| Optional human readable repository description, it can be used by UI for displaying purposes - -| `disabled` -| `boolean` -| If set to true, disable the repo usage in the cluster - -| `name` -| `string` -| Optional associated human readable repository name, it can be used by UI for displaying purposes - -|=== -..spec.connectionConfig -Description:: - Required configuration for connecting to the chart repo - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca-bundle.crt" is used to locate the data. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -| `tlsClientConfig` -| `object` -| tlsClientConfig is an optional reference to a secret by name that contains the PEM-encoded TLS client certificate and private key to present when connecting to the server. The key "tls.crt" is used to locate the client certificate. The key "tls.key" is used to locate the private key. The namespace for this secret is openshift-config. - -| `url` -| `string` -| Chart repository URL - -|=== -..spec.connectionConfig.ca -Description:: - ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca-bundle.crt" is used to locate the data. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.connectionConfig.tlsClientConfig -Description:: - tlsClientConfig is an optional reference to a secret by name that contains the PEM-encoded TLS client certificate and private key to present when connecting to the server. The key "tls.crt" is used to locate the client certificate. The key "tls.key" is used to locate the private key. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..status -Description:: - Observed status of the repository within the cluster.. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their statuses - -| `conditions[]` -| `object` -| Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo's current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` - // other fields } - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their statuses - -Type:: - `array` - - - - -..status.conditions[] -Description:: - Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo's current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` - // other fields } - -Type:: - `object` - -Required:: - - `lastTransitionTime` - - `message` - - `reason` - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. - -| `message` -| `string` -| message is a human readable message indicating details about the transition. This may be an empty string. - -| `observedGeneration` -| `integer` -| observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. - -| `reason` -| `string` -| reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt) - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/helm.openshift.io/v1beta1/helmchartrepositories` -- `DELETE`: delete collection of HelmChartRepository -- `GET`: list objects of kind HelmChartRepository -- `POST`: create a HelmChartRepository -* `/apis/helm.openshift.io/v1beta1/helmchartrepositories/{name}` -- `DELETE`: delete a HelmChartRepository -- `GET`: read the specified HelmChartRepository -- `PATCH`: partially update the specified HelmChartRepository -- `PUT`: replace the specified HelmChartRepository -* `/apis/helm.openshift.io/v1beta1/helmchartrepositories/{name}/status` -- `GET`: read status of the specified HelmChartRepository -- `PATCH`: partially update status of the specified HelmChartRepository -- `PUT`: replace status of the specified HelmChartRepository - - -=== /apis/helm.openshift.io/v1beta1/helmchartrepositories - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#helmchartrepositorylist-helm-openshift-io-v1beta1[`HelmChartRepositoryList helm.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 201 - Created -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 202 - Accepted -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/helm.openshift.io/v1beta1/helmchartrepositories/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the HelmChartRepository -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 201 - Created -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/helm.openshift.io/v1beta1/helmchartrepositories/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the HelmChartRepository -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified HelmChartRepository - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 201 - Created -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`HelmChartRepository helm.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/image-config-openshift-io-v1.adoc b/rest_api/config_apis/image-config-openshift-io-v1.adoc deleted file mode 100644 index dbcb2146fa0b..000000000000 --- a/rest_api/config_apis/image-config-openshift-io-v1.adoc +++ /dev/null @@ -1,686 +0,0 @@ -[id="image-config-openshift-io-v1"] -= Image [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Image governs policies related to imagestream imports and runtime configuration for external registries. It allows cluster admins to configure which registries OpenShift is allowed to import images from, extra CA trust bundles for external registries, and policies to block or allow registry hostnames. When exposing OpenShift's image registry to the public, this also lets cluster admins specify the external hostname. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalTrustedCA` -| `object` -| additionalTrustedCA is a reference to a ConfigMap containing additional CAs that should be trusted during imagestream import, pod image pull, build image pull, and imageregistry pullthrough. The namespace for this config map is openshift-config. - -| `allowedRegistriesForImport` -| `array` -| allowedRegistriesForImport limits the container image registries that normal users may import images from. Set this list to the registries that you trust to contain valid Docker images and that you want applications to be able to import from. Users with permission to create Images or ImageStreamMappings via the API are not affected by this policy - typically only administrators or system integrations will have those permissions. - -| `allowedRegistriesForImport[]` -| `object` -| RegistryLocation contains a location of the registry specified by the registry domain name. The domain name might include wildcards, like '*' or '??'. - -| `externalRegistryHostnames` -| `array (string)` -| externalRegistryHostnames provides the hostnames for the default external image registry. The external hostname should be set only when the image registry is exposed externally. The first value is used in 'publicDockerImageRepository' field in ImageStreams. The value must be in "hostname[:port]" format. - -| `registrySources` -| `object` -| registrySources contains configuration that determines how the container runtime should treat individual registries when accessing images for builds+pods. (e.g. whether or not to allow insecure access). It does not contain configuration for the internal cluster registry. - -|=== -..spec.additionalTrustedCA -Description:: - additionalTrustedCA is a reference to a ConfigMap containing additional CAs that should be trusted during imagestream import, pod image pull, build image pull, and imageregistry pullthrough. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.allowedRegistriesForImport -Description:: - allowedRegistriesForImport limits the container image registries that normal users may import images from. Set this list to the registries that you trust to contain valid Docker images and that you want applications to be able to import from. Users with permission to create Images or ImageStreamMappings via the API are not affected by this policy - typically only administrators or system integrations will have those permissions. - -Type:: - `array` - - - - -..spec.allowedRegistriesForImport[] -Description:: - RegistryLocation contains a location of the registry specified by the registry domain name. The domain name might include wildcards, like '*' or '??'. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `domainName` -| `string` -| domainName specifies a domain name for the registry In case the registry use non-standard (80 or 443) port, the port should be included in the domain name as well. - -| `insecure` -| `boolean` -| insecure indicates whether the registry is secure (https) or insecure (http) By default (if not specified) the registry is assumed as secure. - -|=== -..spec.registrySources -Description:: - registrySources contains configuration that determines how the container runtime should treat individual registries when accessing images for builds+pods. (e.g. whether or not to allow insecure access). It does not contain configuration for the internal cluster registry. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowedRegistries` -| `array (string)` -| allowedRegistries are the only registries permitted for image pull and push actions. All other registries are denied. - Only one of BlockedRegistries or AllowedRegistries may be set. - -| `blockedRegistries` -| `array (string)` -| blockedRegistries cannot be used for image pull and push actions. All other registries are permitted. - Only one of BlockedRegistries or AllowedRegistries may be set. - -| `containerRuntimeSearchRegistries` -| `array (string)` -| containerRuntimeSearchRegistries are registries that will be searched when pulling images that do not have fully qualified domains in their pull specs. Registries will be searched in the order provided in the list. Note: this search list only works with the container runtime, i.e CRI-O. Will NOT work with builds or imagestream imports. - -| `insecureRegistries` -| `array (string)` -| insecureRegistries are registries which do not have a valid TLS certificates or only support HTTP connections. - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `externalRegistryHostnames` -| `array (string)` -| externalRegistryHostnames provides the hostnames for the default external image registry. The external hostname should be set only when the image registry is exposed externally. The first value is used in 'publicDockerImageRepository' field in ImageStreams. The value must be in "hostname[:port]" format. - -| `internalRegistryHostname` -| `string` -| internalRegistryHostname sets the hostname for the default internal image registry. The value must be in "hostname[:port]" format. This value is set by the image registry operator which controls the internal registry hostname. For backward compatibility, users can still use OPENSHIFT_DEFAULT_REGISTRY environment variable but this setting overrides the environment variable. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/images` -- `DELETE`: delete collection of Image -- `GET`: list objects of kind Image -- `POST`: create an Image -* `/apis/config.openshift.io/v1/images/{name}` -- `DELETE`: delete an Image -- `GET`: read the specified Image -- `PATCH`: partially update the specified Image -- `PUT`: replace the specified Image -* `/apis/config.openshift.io/v1/images/{name}/status` -- `GET`: read status of the specified Image -- `PATCH`: partially update status of the specified Image -- `PUT`: replace status of the specified Image - - -=== /apis/config.openshift.io/v1/images - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagelist-config-openshift-io-v1[`ImageList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/images/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Image -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/images/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Image -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`Image config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc b/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc deleted file mode 100644 index 988276cdbb43..000000000000 --- a/rest_api/config_apis/infrastructure-config-openshift-io-v1.adoc +++ /dev/null @@ -1,1148 +0,0 @@ -[id="infrastructure-config-openshift-io-v1"] -= Infrastructure [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Infrastructure holds cluster-wide information about Infrastructure. The canonical name is `cluster` - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cloudConfig` -| `object` -| cloudConfig is a reference to a ConfigMap containing the cloud provider configuration file. This configuration file is used to configure the Kubernetes cloud provider integration when using the built-in cloud provider integration or the external cloud controller manager. The namespace for this config map is openshift-config. - cloudConfig should only be consumed by the kube_cloud_config controller. The controller is responsible for using the user configuration in the spec for various platforms and combining that with the user provided ConfigMap in this field to create a stitched kube cloud config. The controller generates a ConfigMap `kube-cloud-config` in `openshift-config-managed` namespace with the kube cloud config is stored in `cloud.conf` key. All the clients are expected to use the generated ConfigMap only. - -| `platformSpec` -| `object` -| platformSpec holds desired information specific to the underlying infrastructure provider. - -|=== -..spec.cloudConfig -Description:: - cloudConfig is a reference to a ConfigMap containing the cloud provider configuration file. This configuration file is used to configure the Kubernetes cloud provider integration when using the built-in cloud provider integration or the external cloud controller manager. The namespace for this config map is openshift-config. - cloudConfig should only be consumed by the kube_cloud_config controller. The controller is responsible for using the user configuration in the spec for various platforms and combining that with the user provided ConfigMap in this field to create a stitched kube cloud config. The controller generates a ConfigMap `kube-cloud-config` in `openshift-config-managed` namespace with the kube cloud config is stored in `cloud.conf` key. All the clients are expected to use the generated ConfigMap only. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| Key allows pointing to a specific key/value inside of the configmap. This is useful for logical file references. - -| `name` -| `string` -| - -|=== -..spec.platformSpec -Description:: - platformSpec holds desired information specific to the underlying infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `aws` -| `object` -| AWS contains settings specific to the Amazon Web Services infrastructure provider. - -| `azure` -| `object` -| Azure contains settings specific to the Azure infrastructure provider. - -| `baremetal` -| `object` -| BareMetal contains settings specific to the BareMetal platform. - -| `gcp` -| `object` -| GCP contains settings specific to the Google Cloud Platform infrastructure provider. - -| `ibmcloud` -| `object` -| IBMCloud contains settings specific to the IBMCloud infrastructure provider. - -| `kubevirt` -| `object` -| Kubevirt contains settings specific to the kubevirt infrastructure provider. - -| `openstack` -| `object` -| OpenStack contains settings specific to the OpenStack infrastructure provider. - -| `ovirt` -| `object` -| Ovirt contains settings specific to the oVirt infrastructure provider. - -| `type` -| `string` -| type is the underlying infrastructure provider for the cluster. This value controls whether infrastructure automation such as service load balancers, dynamic volume provisioning, machine creation and deletion, and other integrations are enabled. If None, no infrastructure automation is enabled. Allowed values are "AWS", "Azure", "BareMetal", "GCP", "Libvirt", "OpenStack", "VSphere", "oVirt", "KubeVirt" and "None". Individual components may not support all platforms, and must handle unrecognized platforms as None if they do not support that platform. - -| `vsphere` -| `object` -| VSphere contains settings specific to the VSphere infrastructure provider. - -|=== -..spec.platformSpec.aws -Description:: - AWS contains settings specific to the Amazon Web Services infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `serviceEndpoints` -| `array` -| serviceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service. - -| `serviceEndpoints[]` -| `object` -| AWSServiceEndpoint store the configuration of a custom url to override existing defaults of AWS Services. - -|=== -..spec.platformSpec.aws.serviceEndpoints -Description:: - serviceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service. - -Type:: - `array` - - - - -..spec.platformSpec.aws.serviceEndpoints[] -Description:: - AWSServiceEndpoint store the configuration of a custom url to override existing defaults of AWS Services. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the name of the AWS service. The list of all the service names can be found at https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html This must be provided and cannot be empty. - -| `url` -| `string` -| url is fully qualified URI with scheme https, that overrides the default generated endpoint for a client. This must be provided and cannot be empty. - -|=== -..spec.platformSpec.azure -Description:: - Azure contains settings specific to the Azure infrastructure provider. - -Type:: - `object` - - - - -..spec.platformSpec.baremetal -Description:: - BareMetal contains settings specific to the BareMetal platform. - -Type:: - `object` - - - - -..spec.platformSpec.gcp -Description:: - GCP contains settings specific to the Google Cloud Platform infrastructure provider. - -Type:: - `object` - - - - -..spec.platformSpec.ibmcloud -Description:: - IBMCloud contains settings specific to the IBMCloud infrastructure provider. - -Type:: - `object` - - - - -..spec.platformSpec.kubevirt -Description:: - Kubevirt contains settings specific to the kubevirt infrastructure provider. - -Type:: - `object` - - - - -..spec.platformSpec.openstack -Description:: - OpenStack contains settings specific to the OpenStack infrastructure provider. - -Type:: - `object` - - - - -..spec.platformSpec.ovirt -Description:: - Ovirt contains settings specific to the oVirt infrastructure provider. - -Type:: - `object` - - - - -..spec.platformSpec.vsphere -Description:: - VSphere contains settings specific to the VSphere infrastructure provider. - -Type:: - `object` - - - - -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiServerInternalURI` -| `string` -| apiServerInternalURL is a valid URI with scheme 'https', address and optionally a port (defaulting to 443). apiServerInternalURL can be used by components like kubelets, to contact the Kubernetes API server using the infrastructure provider rather than Kubernetes networking. - -| `apiServerURL` -| `string` -| apiServerURL is a valid URI with scheme 'https', address and optionally a port (defaulting to 443). apiServerURL can be used by components like the web console to tell users where to find the Kubernetes API. - -| `etcdDiscoveryDomain` -| `string` -| etcdDiscoveryDomain is the domain used to fetch the SRV records for discovering etcd servers and clients. For more info: https://github.com/etcd-io/etcd/blob/329be66e8b3f9e2e6af83c123ff89297e49ebd15/Documentation/op-guide/clustering.md#dns-discovery deprecated: as of 4.7, this field is no longer set or honored. It will be removed in a future release. - -| `infrastructureName` -| `string` -| infrastructureName uniquely identifies a cluster with a human friendly name. Once set it should not be changed. Must be of max length 27 and must have only alphanumeric or hyphen characters. - -| `platform` -| `string` -| platform is the underlying infrastructure provider for the cluster. - Deprecated: Use platformStatus.type instead. - -| `platformStatus` -| `object` -| platformStatus holds status information specific to the underlying infrastructure provider. - -|=== -..status.platformStatus -Description:: - platformStatus holds status information specific to the underlying infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `aws` -| `object` -| AWS contains settings specific to the Amazon Web Services infrastructure provider. - -| `azure` -| `object` -| Azure contains settings specific to the Azure infrastructure provider. - -| `baremetal` -| `object` -| BareMetal contains settings specific to the BareMetal platform. - -| `gcp` -| `object` -| GCP contains settings specific to the Google Cloud Platform infrastructure provider. - -| `ibmcloud` -| `object` -| IBMCloud contains settings specific to the IBMCloud infrastructure provider. - -| `kubevirt` -| `object` -| Kubevirt contains settings specific to the kubevirt infrastructure provider. - -| `openstack` -| `object` -| OpenStack contains settings specific to the OpenStack infrastructure provider. - -| `ovirt` -| `object` -| Ovirt contains settings specific to the oVirt infrastructure provider. - -| `type` -| `string` -| type is the underlying infrastructure provider for the cluster. This value controls whether infrastructure automation such as service load balancers, dynamic volume provisioning, machine creation and deletion, and other integrations are enabled. If None, no infrastructure automation is enabled. Allowed values are "AWS", "Azure", "BareMetal", "GCP", "Libvirt", "OpenStack", "VSphere", "oVirt", and "None". Individual components may not support all platforms, and must handle unrecognized platforms as None if they do not support that platform. - This value will be synced with to the `status.platform` and `status.platformStatus.type`. Currently this value cannot be changed once set. - -| `vsphere` -| `object` -| VSphere contains settings specific to the VSphere infrastructure provider. - -|=== -..status.platformStatus.aws -Description:: - AWS contains settings specific to the Amazon Web Services infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `region` -| `string` -| region holds the default AWS region for new AWS resources created by the cluster. - -| `serviceEndpoints` -| `array` -| ServiceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service. - -| `serviceEndpoints[]` -| `object` -| AWSServiceEndpoint store the configuration of a custom url to override existing defaults of AWS Services. - -|=== -..status.platformStatus.aws.serviceEndpoints -Description:: - ServiceEndpoints list contains custom endpoints which will override default service endpoint of AWS Services. There must be only one ServiceEndpoint for a service. - -Type:: - `array` - - - - -..status.platformStatus.aws.serviceEndpoints[] -Description:: - AWSServiceEndpoint store the configuration of a custom url to override existing defaults of AWS Services. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the name of the AWS service. The list of all the service names can be found at https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html This must be provided and cannot be empty. - -| `url` -| `string` -| url is fully qualified URI with scheme https, that overrides the default generated endpoint for a client. This must be provided and cannot be empty. - -|=== -..status.platformStatus.azure -Description:: - Azure contains settings specific to the Azure infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cloudName` -| `string` -| cloudName is the name of the Azure cloud environment which can be used to configure the Azure SDK with the appropriate Azure API endpoints. If empty, the value is equal to `AzurePublicCloud`. - -| `networkResourceGroupName` -| `string` -| networkResourceGroupName is the Resource Group for network resources like the Virtual Network and Subnets used by the cluster. If empty, the value is same as ResourceGroupName. - -| `resourceGroupName` -| `string` -| resourceGroupName is the Resource Group for new Azure resources created for the cluster. - -|=== -..status.platformStatus.baremetal -Description:: - BareMetal contains settings specific to the BareMetal platform. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiServerInternalIP` -| `string` -| apiServerInternalIP is an IP address to contact the Kubernetes API server that can be used by components inside the cluster, like kubelets using the infrastructure rather than Kubernetes networking. It is the IP that the Infrastructure.status.apiServerInternalURI points to. It is the IP for a self-hosted load balancer in front of the API servers. - -| `ingressIP` -| `string` -| ingressIP is an external IP which routes to the default ingress controller. The IP is a suitable target of a wildcard DNS record used to resolve default route host names. - -| `nodeDNSIP` -| `string` -| nodeDNSIP is the IP address for the internal DNS used by the nodes. Unlike the one managed by the DNS operator, `NodeDNSIP` provides name resolution for the nodes themselves. There is no DNS-as-a-service for BareMetal deployments. In order to minimize necessary changes to the datacenter DNS, a DNS service is hosted as a static pod to serve those hostnames to the nodes in the cluster. - -|=== -..status.platformStatus.gcp -Description:: - GCP contains settings specific to the Google Cloud Platform infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `projectID` -| `string` -| resourceGroupName is the Project ID for new GCP resources created for the cluster. - -| `region` -| `string` -| region holds the region for new GCP resources created for the cluster. - -|=== -..status.platformStatus.ibmcloud -Description:: - IBMCloud contains settings specific to the IBMCloud infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `location` -| `string` -| Location is where the cluster has been deployed - -| `providerType` -| `string` -| ProviderType indicates the type of cluster that was created - -| `resourceGroupName` -| `string` -| ResourceGroupName is the Resource Group for new IBMCloud resources created for the cluster. - -|=== -..status.platformStatus.kubevirt -Description:: - Kubevirt contains settings specific to the kubevirt infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiServerInternalIP` -| `string` -| apiServerInternalIP is an IP address to contact the Kubernetes API server that can be used by components inside the cluster, like kubelets using the infrastructure rather than Kubernetes networking. It is the IP that the Infrastructure.status.apiServerInternalURI points to. It is the IP for a self-hosted load balancer in front of the API servers. - -| `ingressIP` -| `string` -| ingressIP is an external IP which routes to the default ingress controller. The IP is a suitable target of a wildcard DNS record used to resolve default route host names. - -|=== -..status.platformStatus.openstack -Description:: - OpenStack contains settings specific to the OpenStack infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiServerInternalIP` -| `string` -| apiServerInternalIP is an IP address to contact the Kubernetes API server that can be used by components inside the cluster, like kubelets using the infrastructure rather than Kubernetes networking. It is the IP that the Infrastructure.status.apiServerInternalURI points to. It is the IP for a self-hosted load balancer in front of the API servers. - -| `cloudName` -| `string` -| cloudName is the name of the desired OpenStack cloud in the client configuration file (`clouds.yaml`). - -| `ingressIP` -| `string` -| ingressIP is an external IP which routes to the default ingress controller. The IP is a suitable target of a wildcard DNS record used to resolve default route host names. - -| `nodeDNSIP` -| `string` -| nodeDNSIP is the IP address for the internal DNS used by the nodes. Unlike the one managed by the DNS operator, `NodeDNSIP` provides name resolution for the nodes themselves. There is no DNS-as-a-service for OpenStack deployments. In order to minimize necessary changes to the datacenter DNS, a DNS service is hosted as a static pod to serve those hostnames to the nodes in the cluster. - -|=== -..status.platformStatus.ovirt -Description:: - Ovirt contains settings specific to the oVirt infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiServerInternalIP` -| `string` -| apiServerInternalIP is an IP address to contact the Kubernetes API server that can be used by components inside the cluster, like kubelets using the infrastructure rather than Kubernetes networking. It is the IP that the Infrastructure.status.apiServerInternalURI points to. It is the IP for a self-hosted load balancer in front of the API servers. - -| `ingressIP` -| `string` -| ingressIP is an external IP which routes to the default ingress controller. The IP is a suitable target of a wildcard DNS record used to resolve default route host names. - -| `nodeDNSIP` -| `string` -| deprecated: as of 4.6, this field is no longer set or honored. It will be removed in a future release. - -|=== -..status.platformStatus.vsphere -Description:: - VSphere contains settings specific to the VSphere infrastructure provider. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiServerInternalIP` -| `string` -| apiServerInternalIP is an IP address to contact the Kubernetes API server that can be used by components inside the cluster, like kubelets using the infrastructure rather than Kubernetes networking. It is the IP that the Infrastructure.status.apiServerInternalURI points to. It is the IP for a self-hosted load balancer in front of the API servers. - -| `ingressIP` -| `string` -| ingressIP is an external IP which routes to the default ingress controller. The IP is a suitable target of a wildcard DNS record used to resolve default route host names. - -| `nodeDNSIP` -| `string` -| nodeDNSIP is the IP address for the internal DNS used by the nodes. Unlike the one managed by the DNS operator, `NodeDNSIP` provides name resolution for the nodes themselves. There is no DNS-as-a-service for vSphere deployments. In order to minimize necessary changes to the datacenter DNS, a DNS service is hosted as a static pod to serve those hostnames to the nodes in the cluster. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/infrastructures` -- `DELETE`: delete collection of Infrastructure -- `GET`: list objects of kind Infrastructure -- `POST`: create an Infrastructure -* `/apis/config.openshift.io/v1/infrastructures/{name}` -- `DELETE`: delete an Infrastructure -- `GET`: read the specified Infrastructure -- `PATCH`: partially update the specified Infrastructure -- `PUT`: replace the specified Infrastructure -* `/apis/config.openshift.io/v1/infrastructures/{name}/status` -- `GET`: read status of the specified Infrastructure -- `PATCH`: partially update status of the specified Infrastructure -- `PUT`: replace status of the specified Infrastructure - - -=== /apis/config.openshift.io/v1/infrastructures - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#infrastructurelist-config-openshift-io-v1[`InfrastructureList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/infrastructures/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Infrastructure -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/infrastructures/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Infrastructure -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Infrastructure - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`Infrastructure config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/ingress-config-openshift-io-v1.adoc b/rest_api/config_apis/ingress-config-openshift-io-v1.adoc deleted file mode 100644 index a400517b01b9..000000000000 --- a/rest_api/config_apis/ingress-config-openshift-io-v1.adoc +++ /dev/null @@ -1,576 +0,0 @@ -[id="ingress-config-openshift-io-v1"] -= Ingress [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Ingress holds cluster-wide information about ingress, including the default ingress domain used for routes. The canonical name is `cluster`. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `appsDomain` -| `string` -| appsDomain is an optional domain to use instead of the one specified in the domain field when a Route is created without specifying an explicit host. If appsDomain is nonempty, this value is used to generate default host values for Route. Unlike domain, appsDomain may be modified after installation. This assumes a new ingresscontroller has been setup with a wildcard certificate. - -| `domain` -| `string` -| domain is used to generate a default host name for a route when the route's host name is empty. The generated host name will follow this pattern: "<route-name>.<route-namespace>.<domain>". - It is also used as the default wildcard domain suffix for ingress. The default ingresscontroller domain will follow this pattern: "*.<domain>". - Once set, changing domain is not currently supported. - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/ingresses` -- `DELETE`: delete collection of Ingress -- `GET`: list objects of kind Ingress -- `POST`: create an Ingress -* `/apis/config.openshift.io/v1/ingresses/{name}` -- `DELETE`: delete an Ingress -- `GET`: read the specified Ingress -- `PATCH`: partially update the specified Ingress -- `PUT`: replace the specified Ingress -* `/apis/config.openshift.io/v1/ingresses/{name}/status` -- `GET`: read status of the specified Ingress -- `PATCH`: partially update status of the specified Ingress -- `PUT`: replace status of the specified Ingress - - -=== /apis/config.openshift.io/v1/ingresses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#ingresslist-config-openshift-io-v1[`IngressList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/ingresses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Ingress -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/ingresses/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Ingress -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`Ingress config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/network-config-openshift-io-v1.adoc b/rest_api/config_apis/network-config-openshift-io-v1.adoc deleted file mode 100644 index 265439c96190..000000000000 --- a/rest_api/config_apis/network-config-openshift-io-v1.adoc +++ /dev/null @@ -1,595 +0,0 @@ -[id="network-config-openshift-io-v1"] -= Network [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Network holds cluster-wide information about Network. The canonical name is `cluster`. It is used to configure the desired network configuration, such as: IP address pools for services/pod IPs, network plugin, etc. Please view network.spec for an explanation on what applies when configuring this resource. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration. As a general rule, this SHOULD NOT be read directly. Instead, you should consume the NetworkStatus, as it indicates the currently deployed configuration. Currently, most spec fields are immutable after installation. Please view the individual ones for further details on each. - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration. As a general rule, this SHOULD NOT be read directly. Instead, you should consume the NetworkStatus, as it indicates the currently deployed configuration. Currently, most spec fields are immutable after installation. Please view the individual ones for further details on each. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clusterNetwork` -| `array` -| IP address pool to use for pod IPs. This field is immutable after installation. - -| `clusterNetwork[]` -| `object` -| ClusterNetworkEntry is a contiguous block of IP addresses from which pod IPs are allocated. - -| `externalIP` -| `object` -| externalIP defines configuration for controllers that affect Service.ExternalIP. If nil, then ExternalIP is not allowed to be set. - -| `networkType` -| `string` -| NetworkType is the plugin that is to be deployed (e.g. OpenShiftSDN). This should match a value that the cluster-network-operator understands, or else no networking will be installed. Currently supported values are: - OpenShiftSDN This field is immutable after installation. - -| `serviceNetwork` -| `array (string)` -| IP address pool for services. Currently, we only support a single entry here. This field is immutable after installation. - -| `serviceNodePortRange` -| `string` -| The port range allowed for Services of type NodePort. If not specified, the default of 30000-32767 will be used. Such Services without a NodePort specified will have one automatically allocated from this range. This parameter can be updated after the cluster is installed. - -|=== -..spec.clusterNetwork -Description:: - IP address pool to use for pod IPs. This field is immutable after installation. - -Type:: - `array` - - - - -..spec.clusterNetwork[] -Description:: - ClusterNetworkEntry is a contiguous block of IP addresses from which pod IPs are allocated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cidr` -| `string` -| The complete block for pod IPs. - -| `hostPrefix` -| `integer` -| The size (prefix) of block to allocate to each node. If this field is not used by the plugin, it can be left unset. - -|=== -..spec.externalIP -Description:: - externalIP defines configuration for controllers that affect Service.ExternalIP. If nil, then ExternalIP is not allowed to be set. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `autoAssignCIDRs` -| `array (string)` -| autoAssignCIDRs is a list of CIDRs from which to automatically assign Service.ExternalIP. These are assigned when the service is of type LoadBalancer. In general, this is only useful for bare-metal clusters. In Openshift 3.x, this was misleadingly called "IngressIPs". Automatically assigned External IPs are not affected by any ExternalIPPolicy rules. Currently, only one entry may be provided. - -| `policy` -| `object` -| policy is a set of restrictions applied to the ExternalIP field. If nil or empty, then ExternalIP is not allowed to be set. - -|=== -..spec.externalIP.policy -Description:: - policy is a set of restrictions applied to the ExternalIP field. If nil or empty, then ExternalIP is not allowed to be set. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowedCIDRs` -| `array (string)` -| allowedCIDRs is the list of allowed CIDRs. - -| `rejectedCIDRs` -| `array (string)` -| rejectedCIDRs is the list of disallowed CIDRs. These take precedence over allowedCIDRs. - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clusterNetwork` -| `array` -| IP address pool to use for pod IPs. - -| `clusterNetwork[]` -| `object` -| ClusterNetworkEntry is a contiguous block of IP addresses from which pod IPs are allocated. - -| `clusterNetworkMTU` -| `integer` -| ClusterNetworkMTU is the MTU for inter-pod networking. - -| `networkType` -| `string` -| NetworkType is the plugin that is deployed (e.g. OpenShiftSDN). - -| `serviceNetwork` -| `array (string)` -| IP address pool for services. Currently, we only support a single entry here. - -|=== -..status.clusterNetwork -Description:: - IP address pool to use for pod IPs. - -Type:: - `array` - - - - -..status.clusterNetwork[] -Description:: - ClusterNetworkEntry is a contiguous block of IP addresses from which pod IPs are allocated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cidr` -| `string` -| The complete block for pod IPs. - -| `hostPrefix` -| `integer` -| The size (prefix) of block to allocate to each node. If this field is not used by the plugin, it can be left unset. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/networks` -- `DELETE`: delete collection of Network -- `GET`: list objects of kind Network -- `POST`: create a Network -* `/apis/config.openshift.io/v1/networks/{name}` -- `DELETE`: delete a Network -- `GET`: read the specified Network -- `PATCH`: partially update the specified Network -- `PUT`: replace the specified Network - - -=== /apis/config.openshift.io/v1/networks - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#networklist-config-openshift-io-v1[`NetworkList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/networks/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Network -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`Network config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/oauth-config-openshift-io-v1.adoc b/rest_api/config_apis/oauth-config-openshift-io-v1.adoc deleted file mode 100644 index 2963a650bf50..000000000000 --- a/rest_api/config_apis/oauth-config-openshift-io-v1.adoc +++ /dev/null @@ -1,1498 +0,0 @@ -[id="oauth-config-openshift-io-v1"] -= OAuth [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OAuth holds cluster-wide information about OAuth. The canonical name is `cluster`. It is used to configure the integrated OAuth server. This configuration is only honored when the top level Authentication config has type set to IntegratedOAuth. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `identityProviders` -| `array` -| identityProviders is an ordered list of ways for a user to identify themselves. When this list is empty, no identities are provisioned for users. - -| `identityProviders[]` -| `object` -| IdentityProvider provides identities for users authenticating using credentials - -| `templates` -| `object` -| templates allow you to customize pages like the login page. - -| `tokenConfig` -| `object` -| tokenConfig contains options for authorization and access tokens - -|=== -..spec.identityProviders -Description:: - identityProviders is an ordered list of ways for a user to identify themselves. When this list is empty, no identities are provisioned for users. - -Type:: - `array` - - - - -..spec.identityProviders[] -Description:: - IdentityProvider provides identities for users authenticating using credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| basicAuth contains configuration options for the BasicAuth IdP - -| `github` -| `object` -| github enables user authentication using GitHub credentials - -| `gitlab` -| `object` -| gitlab enables user authentication using GitLab credentials - -| `google` -| `object` -| google enables user authentication using Google credentials - -| `htpasswd` -| `object` -| htpasswd enables user authentication using an HTPasswd file to validate credentials - -| `keystone` -| `object` -| keystone enables user authentication using keystone password credentials - -| `ldap` -| `object` -| ldap enables user authentication using LDAP credentials - -| `mappingMethod` -| `string` -| mappingMethod determines how identities from this provider are mapped to users Defaults to "claim" - -| `name` -| `string` -| name is used to qualify the identities returned by this provider. - It MUST be unique and not shared by any other identity provider used - It MUST be a valid path segment: name cannot equal "." or ".." or contain "/" or "%" or ":" Ref: https://godoc.org/github.com/openshift/origin/pkg/user/apis/user/validation#ValidateIdentityProviderName - -| `openID` -| `object` -| openID enables user authentication using OpenID credentials - -| `requestHeader` -| `object` -| requestHeader enables user authentication using request header credentials - -| `type` -| `string` -| type identifies the identity provider type for this entry. - -|=== -..spec.identityProviders[].basicAuth -Description:: - basicAuth contains configuration options for the BasicAuth IdP - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -| `tlsClientCert` -| `object` -| tlsClientCert is an optional reference to a secret by name that contains the PEM-encoded TLS client certificate to present when connecting to the server. The key "tls.crt" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. If the specified certificate data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `tlsClientKey` -| `object` -| tlsClientKey is an optional reference to a secret by name that contains the PEM-encoded TLS private key for the client certificate referenced in tlsClientCert. The key "tls.key" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. If the specified certificate data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `url` -| `string` -| url is the remote URL to connect to - -|=== -..spec.identityProviders[].basicAuth.ca -Description:: - ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.identityProviders[].basicAuth.tlsClientCert -Description:: - tlsClientCert is an optional reference to a secret by name that contains the PEM-encoded TLS client certificate to present when connecting to the server. The key "tls.crt" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. If the specified certificate data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].basicAuth.tlsClientKey -Description:: - tlsClientKey is an optional reference to a secret by name that contains the PEM-encoded TLS private key for the client certificate referenced in tlsClientCert. The key "tls.key" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. If the specified certificate data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].github -Description:: - github enables user authentication using GitHub credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. This can only be configured when hostname is set to a non-empty value. The namespace for this config map is openshift-config. - -| `clientID` -| `string` -| clientID is the oauth client ID - -| `clientSecret` -| `object` -| clientSecret is a required reference to the secret by name containing the oauth client secret. The key "clientSecret" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `hostname` -| `string` -| hostname is the optional domain (e.g. "mycompany.com") for use with a hosted instance of GitHub Enterprise. It must match the GitHub Enterprise settings value configured at /setup/settings#hostname. - -| `organizations` -| `array (string)` -| organizations optionally restricts which organizations are allowed to log in - -| `teams` -| `array (string)` -| teams optionally restricts which teams are allowed to log in. Format is <org>/<team>. - -|=== -..spec.identityProviders[].github.ca -Description:: - ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. This can only be configured when hostname is set to a non-empty value. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.identityProviders[].github.clientSecret -Description:: - clientSecret is a required reference to the secret by name containing the oauth client secret. The key "clientSecret" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].gitlab -Description:: - gitlab enables user authentication using GitLab credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -| `clientID` -| `string` -| clientID is the oauth client ID - -| `clientSecret` -| `object` -| clientSecret is a required reference to the secret by name containing the oauth client secret. The key "clientSecret" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `url` -| `string` -| url is the oauth server base URL - -|=== -..spec.identityProviders[].gitlab.ca -Description:: - ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.identityProviders[].gitlab.clientSecret -Description:: - clientSecret is a required reference to the secret by name containing the oauth client secret. The key "clientSecret" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].google -Description:: - google enables user authentication using Google credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clientID` -| `string` -| clientID is the oauth client ID - -| `clientSecret` -| `object` -| clientSecret is a required reference to the secret by name containing the oauth client secret. The key "clientSecret" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `hostedDomain` -| `string` -| hostedDomain is the optional Google App domain (e.g. "mycompany.com") to restrict logins to - -|=== -..spec.identityProviders[].google.clientSecret -Description:: - clientSecret is a required reference to the secret by name containing the oauth client secret. The key "clientSecret" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].htpasswd -Description:: - htpasswd enables user authentication using an HTPasswd file to validate credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fileData` -| `object` -| fileData is a required reference to a secret by name containing the data to use as the htpasswd file. The key "htpasswd" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. If the specified htpasswd data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -|=== -..spec.identityProviders[].htpasswd.fileData -Description:: - fileData is a required reference to a secret by name containing the data to use as the htpasswd file. The key "htpasswd" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. If the specified htpasswd data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].keystone -Description:: - keystone enables user authentication using keystone password credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -| `domainName` -| `string` -| domainName is required for keystone v3 - -| `tlsClientCert` -| `object` -| tlsClientCert is an optional reference to a secret by name that contains the PEM-encoded TLS client certificate to present when connecting to the server. The key "tls.crt" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. If the specified certificate data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `tlsClientKey` -| `object` -| tlsClientKey is an optional reference to a secret by name that contains the PEM-encoded TLS private key for the client certificate referenced in tlsClientCert. The key "tls.key" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. If the specified certificate data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `url` -| `string` -| url is the remote URL to connect to - -|=== -..spec.identityProviders[].keystone.ca -Description:: - ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.identityProviders[].keystone.tlsClientCert -Description:: - tlsClientCert is an optional reference to a secret by name that contains the PEM-encoded TLS client certificate to present when connecting to the server. The key "tls.crt" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. If the specified certificate data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].keystone.tlsClientKey -Description:: - tlsClientKey is an optional reference to a secret by name that contains the PEM-encoded TLS private key for the client certificate referenced in tlsClientCert. The key "tls.key" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. If the specified certificate data is not valid, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].ldap -Description:: - ldap enables user authentication using LDAP credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `attributes` -| `object` -| attributes maps LDAP attributes to identities - -| `bindDN` -| `string` -| bindDN is an optional DN to bind with during the search phase. - -| `bindPassword` -| `object` -| bindPassword is an optional reference to a secret by name containing a password to bind with during the search phase. The key "bindPassword" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `ca` -| `object` -| ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -| `insecure` -| `boolean` -| insecure, if true, indicates the connection should not use TLS WARNING: Should not be set to `true` with the URL scheme "ldaps://" as "ldaps://" URLs always attempt to connect using TLS, even when `insecure` is set to `true` When `true`, "ldap://" URLS connect insecurely. When `false`, "ldap://" URLs are upgraded to a TLS connection using StartTLS as specified in https://tools.ietf.org/html/rfc2830. - -| `url` -| `string` -| url is an RFC 2255 URL which specifies the LDAP search parameters to use. The syntax of the URL is: ldap://host:port/basedn?attribute?scope?filter - -|=== -..spec.identityProviders[].ldap.attributes -Description:: - attributes maps LDAP attributes to identities - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `array (string)` -| email is the list of attributes whose values should be used as the email address. Optional. If unspecified, no email is set for the identity - -| `id` -| `array (string)` -| id is the list of attributes whose values should be used as the user ID. Required. First non-empty attribute is used. At least one attribute is required. If none of the listed attribute have a value, authentication fails. LDAP standard identity attribute is "dn" - -| `name` -| `array (string)` -| name is the list of attributes whose values should be used as the display name. Optional. If unspecified, no display name is set for the identity LDAP standard display name attribute is "cn" - -| `preferredUsername` -| `array (string)` -| preferredUsername is the list of attributes whose values should be used as the preferred username. LDAP standard login attribute is "uid" - -|=== -..spec.identityProviders[].ldap.bindPassword -Description:: - bindPassword is an optional reference to a secret by name containing a password to bind with during the search phase. The key "bindPassword" is used to locate the data. If specified and the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].ldap.ca -Description:: - ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.identityProviders[].openID -Description:: - openID enables user authentication using OpenID credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -| `claims` -| `object` -| claims mappings - -| `clientID` -| `string` -| clientID is the oauth client ID - -| `clientSecret` -| `object` -| clientSecret is a required reference to the secret by name containing the oauth client secret. The key "clientSecret" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -| `extraAuthorizeParameters` -| `object (string)` -| extraAuthorizeParameters are any custom parameters to add to the authorize request. - -| `extraScopes` -| `array (string)` -| extraScopes are any scopes to request in addition to the standard "openid" scope. - -| `issuer` -| `string` -| issuer is the URL that the OpenID Provider asserts as its Issuer Identifier. It must use the https scheme with no query or fragment component. - -|=== -..spec.identityProviders[].openID.ca -Description:: - ca is an optional reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. The key "ca.crt" is used to locate the data. If specified and the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. If empty, the default system roots are used. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.identityProviders[].openID.claims -Description:: - claims mappings - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `array (string)` -| email is the list of claims whose values should be used as the email address. Optional. If unspecified, no email is set for the identity - -| `name` -| `array (string)` -| name is the list of claims whose values should be used as the display name. Optional. If unspecified, no display name is set for the identity - -| `preferredUsername` -| `array (string)` -| preferredUsername is the list of claims whose values should be used as the preferred username. If unspecified, the preferred username is determined from the value of the sub claim - -|=== -..spec.identityProviders[].openID.clientSecret -Description:: - clientSecret is a required reference to the secret by name containing the oauth client secret. The key "clientSecret" is used to locate the data. If the secret or expected key is not found, the identity provider is not honored. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.identityProviders[].requestHeader -Description:: - requestHeader enables user authentication using request header credentials - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| ca is a required reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. Specifically, it allows verification of incoming requests to prevent header spoofing. The key "ca.crt" is used to locate the data. If the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. The namespace for this config map is openshift-config. - -| `challengeURL` -| `string` -| challengeURL is a URL to redirect unauthenticated /authorize requests to Unauthenticated requests from OAuth clients which expect WWW-Authenticate challenges will be redirected here. ${url} is replaced with the current URL, escaped to be safe in a query parameter https://www.example.com/sso-login?then=${url} ${query} is replaced with the current query string https://www.example.com/auth-proxy/oauth/authorize?${query} Required when challenge is set to true. - -| `clientCommonNames` -| `array (string)` -| clientCommonNames is an optional list of common names to require a match from. If empty, any client certificate validated against the clientCA bundle is considered authoritative. - -| `emailHeaders` -| `array (string)` -| emailHeaders is the set of headers to check for the email address - -| `headers` -| `array (string)` -| headers is the set of headers to check for identity information - -| `loginURL` -| `string` -| loginURL is a URL to redirect unauthenticated /authorize requests to Unauthenticated requests from OAuth clients which expect interactive logins will be redirected here ${url} is replaced with the current URL, escaped to be safe in a query parameter https://www.example.com/sso-login?then=${url} ${query} is replaced with the current query string https://www.example.com/auth-proxy/oauth/authorize?${query} Required when login is set to true. - -| `nameHeaders` -| `array (string)` -| nameHeaders is the set of headers to check for the display name - -| `preferredUsernameHeaders` -| `array (string)` -| preferredUsernameHeaders is the set of headers to check for the preferred username - -|=== -..spec.identityProviders[].requestHeader.ca -Description:: - ca is a required reference to a config map by name containing the PEM-encoded CA bundle. It is used as a trust anchor to validate the TLS certificate presented by the remote server. Specifically, it allows verification of incoming requests to prevent header spoofing. The key "ca.crt" is used to locate the data. If the config map or expected key is not found, the identity provider is not honored. If the specified ca data is not valid, the identity provider is not honored. The namespace for this config map is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..spec.templates -Description:: - templates allow you to customize pages like the login page. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `error` -| `object` -| error is the name of a secret that specifies a go template to use to render error pages during the authentication or grant flow. The key "errors.html" is used to locate the template data. If specified and the secret or expected key is not found, the default error page is used. If the specified template is not valid, the default error page is used. If unspecified, the default error page is used. The namespace for this secret is openshift-config. - -| `login` -| `object` -| login is the name of a secret that specifies a go template to use to render the login page. The key "login.html" is used to locate the template data. If specified and the secret or expected key is not found, the default login page is used. If the specified template is not valid, the default login page is used. If unspecified, the default login page is used. The namespace for this secret is openshift-config. - -| `providerSelection` -| `object` -| providerSelection is the name of a secret that specifies a go template to use to render the provider selection page. The key "providers.html" is used to locate the template data. If specified and the secret or expected key is not found, the default provider selection page is used. If the specified template is not valid, the default provider selection page is used. If unspecified, the default provider selection page is used. The namespace for this secret is openshift-config. - -|=== -..spec.templates.error -Description:: - error is the name of a secret that specifies a go template to use to render error pages during the authentication or grant flow. The key "errors.html" is used to locate the template data. If specified and the secret or expected key is not found, the default error page is used. If the specified template is not valid, the default error page is used. If unspecified, the default error page is used. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.templates.login -Description:: - login is the name of a secret that specifies a go template to use to render the login page. The key "login.html" is used to locate the template data. If specified and the secret or expected key is not found, the default login page is used. If the specified template is not valid, the default login page is used. If unspecified, the default login page is used. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.templates.providerSelection -Description:: - providerSelection is the name of a secret that specifies a go template to use to render the provider selection page. The key "providers.html" is used to locate the template data. If specified and the secret or expected key is not found, the default provider selection page is used. If the specified template is not valid, the default provider selection page is used. If unspecified, the default provider selection page is used. The namespace for this secret is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..spec.tokenConfig -Description:: - tokenConfig contains options for authorization and access tokens - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessTokenInactivityTimeout` -| `string` -| accessTokenInactivityTimeout defines the token inactivity timeout for tokens granted by any client. The value represents the maximum amount of time that can occur between consecutive uses of the token. Tokens become invalid if they are not used within this temporal window. The user will need to acquire a new token to regain access once a token times out. Takes valid time duration string such as "5m", "1.5h" or "2h45m". The minimum allowed value for duration is 300s (5 minutes). If the timeout is configured per client, then that value takes precedence. If the timeout value is not specified and the client does not override the value, then tokens are valid until their lifetime. - -| `accessTokenInactivityTimeoutSeconds` -| `integer` -| accessTokenInactivityTimeoutSeconds - DEPRECATED: setting this field has no effect. - -| `accessTokenMaxAgeSeconds` -| `integer` -| accessTokenMaxAgeSeconds defines the maximum age of access tokens - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/oauths` -- `DELETE`: delete collection of OAuth -- `GET`: list objects of kind OAuth -- `POST`: create an OAuth -* `/apis/config.openshift.io/v1/oauths/{name}` -- `DELETE`: delete an OAuth -- `GET`: read the specified OAuth -- `PATCH`: partially update the specified OAuth -- `PUT`: replace the specified OAuth -* `/apis/config.openshift.io/v1/oauths/{name}/status` -- `GET`: read status of the specified OAuth -- `PATCH`: partially update status of the specified OAuth -- `PUT`: replace status of the specified OAuth - - -=== /apis/config.openshift.io/v1/oauths - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#oauthlist-config-openshift-io-v1[`OAuthList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/oauths/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OAuth -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/oauths/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OAuth -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified OAuth - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`OAuth config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/operatorhub-config-openshift-io-v1.adoc b/rest_api/config_apis/operatorhub-config-openshift-io-v1.adoc deleted file mode 100644 index 24a6876fdd80..000000000000 --- a/rest_api/config_apis/operatorhub-config-openshift-io-v1.adoc +++ /dev/null @@ -1,663 +0,0 @@ -[id="operatorhub-config-openshift-io-v1"] -= OperatorHub [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OperatorHub is the Schema for the operatorhubs API. It can be used to change the state of the default hub sources for OperatorHub on the cluster from enabled to disabled and vice versa. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| OperatorHubSpec defines the desired state of OperatorHub - -| `status` -| `object` -| OperatorHubStatus defines the observed state of OperatorHub. The current state of the default hub sources will always be reflected here. - -|=== -..spec -Description:: - OperatorHubSpec defines the desired state of OperatorHub - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `disableAllDefaultSources` -| `boolean` -| disableAllDefaultSources allows you to disable all the default hub sources. If this is true, a specific entry in sources can be used to enable a default source. If this is false, a specific entry in sources can be used to disable or enable a default source. - -| `sources` -| `array` -| sources is the list of default hub sources and their configuration. If the list is empty, it implies that the default hub sources are enabled on the cluster unless disableAllDefaultSources is true. If disableAllDefaultSources is true and sources is not empty, the configuration present in sources will take precedence. The list of default hub sources and their current state will always be reflected in the status block. - -| `sources[]` -| `object` -| HubSource is used to specify the hub source and its configuration - -|=== -..spec.sources -Description:: - sources is the list of default hub sources and their configuration. If the list is empty, it implies that the default hub sources are enabled on the cluster unless disableAllDefaultSources is true. If disableAllDefaultSources is true and sources is not empty, the configuration present in sources will take precedence. The list of default hub sources and their current state will always be reflected in the status block. - -Type:: - `array` - - - - -..spec.sources[] -Description:: - HubSource is used to specify the hub source and its configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `disabled` -| `boolean` -| disabled is used to disable a default hub source on cluster - -| `name` -| `string` -| name is the name of one of the default hub sources - -|=== -..status -Description:: - OperatorHubStatus defines the observed state of OperatorHub. The current state of the default hub sources will always be reflected here. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `sources` -| `array` -| sources encapsulates the result of applying the configuration for each hub source - -| `sources[]` -| `object` -| HubSourceStatus is used to reflect the current state of applying the configuration to a default source - -|=== -..status.sources -Description:: - sources encapsulates the result of applying the configuration for each hub source - -Type:: - `array` - - - - -..status.sources[] -Description:: - HubSourceStatus is used to reflect the current state of applying the configuration to a default source - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `disabled` -| `boolean` -| disabled is used to disable a default hub source on cluster - -| `message` -| `string` -| message provides more information regarding failures - -| `name` -| `string` -| name is the name of one of the default hub sources - -| `status` -| `string` -| status indicates success or failure in applying the configuration - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/operatorhubs` -- `DELETE`: delete collection of OperatorHub -- `GET`: list objects of kind OperatorHub -- `POST`: create an OperatorHub -* `/apis/config.openshift.io/v1/operatorhubs/{name}` -- `DELETE`: delete an OperatorHub -- `GET`: read the specified OperatorHub -- `PATCH`: partially update the specified OperatorHub -- `PUT`: replace the specified OperatorHub -* `/apis/config.openshift.io/v1/operatorhubs/{name}/status` -- `GET`: read status of the specified OperatorHub -- `PATCH`: partially update status of the specified OperatorHub -- `PUT`: replace status of the specified OperatorHub - - -=== /apis/config.openshift.io/v1/operatorhubs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#operatorhublist-config-openshift-io-v1[`OperatorHubList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/operatorhubs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OperatorHub -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/operatorhubs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OperatorHub -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified OperatorHub - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`OperatorHub config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/project-config-openshift-io-v1.adoc b/rest_api/config_apis/project-config-openshift-io-v1.adoc deleted file mode 100644 index a5c4e5cd6c86..000000000000 --- a/rest_api/config_apis/project-config-openshift-io-v1.adoc +++ /dev/null @@ -1,593 +0,0 @@ -[id="project-config-openshift-io-v1"] -= Project [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Project holds cluster-wide information about Project. The canonical name is `cluster` - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `projectRequestMessage` -| `string` -| projectRequestMessage is the string presented to a user if they are unable to request a project via the projectrequest api endpoint - -| `projectRequestTemplate` -| `object` -| projectRequestTemplate is the template to use for creating projects in response to projectrequest. This must point to a template in 'openshift-config' namespace. It is optional. If it is not specified, a default template is used. - -|=== -..spec.projectRequestTemplate -Description:: - projectRequestTemplate is the template to use for creating projects in response to projectrequest. This must point to a template in 'openshift-config' namespace. It is optional. If it is not specified, a default template is used. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced project request template - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/projects` -- `DELETE`: delete collection of Project -- `GET`: list objects of kind Project -- `POST`: create a Project -* `/apis/config.openshift.io/v1/projects/{name}` -- `DELETE`: delete a Project -- `GET`: read the specified Project -- `PATCH`: partially update the specified Project -- `PUT`: replace the specified Project -* `/apis/config.openshift.io/v1/projects/{name}/status` -- `GET`: read status of the specified Project -- `PATCH`: partially update status of the specified Project -- `PUT`: replace status of the specified Project - - -=== /apis/config.openshift.io/v1/projects - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#projectlist-config-openshift-io-v1[`ProjectList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/projects/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Project -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/projects/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Project -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`Project config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/proxy-config-openshift-io-v1.adoc b/rest_api/config_apis/proxy-config-openshift-io-v1.adoc deleted file mode 100644 index 30608b804953..000000000000 --- a/rest_api/config_apis/proxy-config-openshift-io-v1.adoc +++ /dev/null @@ -1,628 +0,0 @@ -[id="proxy-config-openshift-io-v1"] -= Proxy [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Proxy holds cluster-wide information on how to configure default proxies for the cluster. The canonical name is `cluster` - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Spec holds user-settable values for the proxy configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - Spec holds user-settable values for the proxy configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `httpProxy` -| `string` -| httpProxy is the URL of the proxy for HTTP requests. Empty means unset and will not result in an env var. - -| `httpsProxy` -| `string` -| httpsProxy is the URL of the proxy for HTTPS requests. Empty means unset and will not result in an env var. - -| `noProxy` -| `string` -| noProxy is a comma-separated list of hostnames and/or CIDRs for which the proxy should not be used. Empty means unset and will not result in an env var. - -| `readinessEndpoints` -| `array (string)` -| readinessEndpoints is a list of endpoints used to verify readiness of the proxy. - -| `trustedCA` -| `object` -| trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. - The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): - apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: \| -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE----- - -|=== -..spec.trustedCA -Description:: - trustedCA is a reference to a ConfigMap containing a CA certificate bundle. The trustedCA field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from the required key "ca-bundle.crt", merging it with the system default trust bundle, and writing the merged trust bundle to a ConfigMap named "trusted-ca-bundle" in the "openshift-config-managed" namespace. Clients that expect to make proxy connections must use the trusted-ca-bundle for all HTTPS requests to the proxy, and may use the trusted-ca-bundle for non-proxy HTTPS requests as well. - The namespace for the ConfigMap referenced by trustedCA is "openshift-config". Here is an example ConfigMap (in yaml): - apiVersion: v1 kind: ConfigMap metadata: name: user-ca-bundle namespace: openshift-config data: ca-bundle.crt: | -----BEGIN CERTIFICATE----- Custom CA certificate bundle. -----END CERTIFICATE----- - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `httpProxy` -| `string` -| httpProxy is the URL of the proxy for HTTP requests. - -| `httpsProxy` -| `string` -| httpsProxy is the URL of the proxy for HTTPS requests. - -| `noProxy` -| `string` -| noProxy is a comma-separated list of hostnames and/or CIDRs for which the proxy should not be used. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/proxies` -- `DELETE`: delete collection of Proxy -- `GET`: list objects of kind Proxy -- `POST`: create a Proxy -* `/apis/config.openshift.io/v1/proxies/{name}` -- `DELETE`: delete a Proxy -- `GET`: read the specified Proxy -- `PATCH`: partially update the specified Proxy -- `PUT`: replace the specified Proxy -* `/apis/config.openshift.io/v1/proxies/{name}/status` -- `GET`: read status of the specified Proxy -- `PATCH`: partially update status of the specified Proxy -- `PUT`: replace status of the specified Proxy - - -=== /apis/config.openshift.io/v1/proxies - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#proxylist-config-openshift-io-v1[`ProxyList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/proxies/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Proxy -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/proxies/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Proxy -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Proxy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`Proxy config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/config_apis/scheduler-config-openshift-io-v1.adoc b/rest_api/config_apis/scheduler-config-openshift-io-v1.adoc deleted file mode 100644 index ba6565dd1c1c..000000000000 --- a/rest_api/config_apis/scheduler-config-openshift-io-v1.adoc +++ /dev/null @@ -1,604 +0,0 @@ -[id="scheduler-config-openshift-io-v1"] -= Scheduler [config.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Scheduler holds cluster-wide config information to run the Kubernetes Scheduler and influence its placement decisions. The canonical name for this config is `cluster`. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultNodeSelector` -| `string` -| defaultNodeSelector helps set the cluster-wide default node selector to restrict pod placement to specific nodes. This is applied to the pods created in all namespaces and creates an intersection with any existing nodeSelectors already set on a pod, additionally constraining that pod's selector. For example, defaultNodeSelector: "type=user-node,region=east" would set nodeSelector field in pod spec to "type=user-node,region=east" to all pods created in all namespaces. Namespaces having project-wide node selectors won't be impacted even if this field is set. This adds an annotation section to the namespace. For example, if a new namespace is created with node-selector='type=user-node,region=east', the annotation openshift.io/node-selector: type=user-node,region=east gets added to the project. When the openshift.io/node-selector annotation is set on the project the value is used in preference to the value we are setting for defaultNodeSelector field. For instance, openshift.io/node-selector: "type=user-node,region=west" means that the default of "type=user-node,region=east" set in defaultNodeSelector would not be applied. - -| `mastersSchedulable` -| `boolean` -| MastersSchedulable allows masters nodes to be schedulable. When this flag is turned on, all the master nodes in the cluster will be made schedulable, so that workload pods can run on them. The default value for this field is false, meaning none of the master nodes are schedulable. Important Note: Once the workload pods start running on the master nodes, extreme care must be taken to ensure that cluster-critical control plane components are not impacted. Please turn on this field after doing due diligence. - -| `policy` -| `object` -| DEPRECATED: the scheduler Policy API has been deprecated and will be removed in a future release. policy is a reference to a ConfigMap containing scheduler policy which has user specified predicates and priorities. If this ConfigMap is not available scheduler will default to use DefaultAlgorithmProvider. The namespace for this configmap is openshift-config. - -| `profile` -| `string` -| profile sets which scheduling profile should be set in order to configure scheduling decisions for new pods. - Valid values are "LowNodeUtilization", "HighNodeUtilization", "NoScoring" Defaults to "LowNodeUtilization" - -|=== -..spec.policy -Description:: - DEPRECATED: the scheduler Policy API has been deprecated and will be removed in a future release. policy is a reference to a ConfigMap containing scheduler policy which has user specified predicates and priorities. If this ConfigMap is not available scheduler will default to use DefaultAlgorithmProvider. The namespace for this configmap is openshift-config. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced config map - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/config.openshift.io/v1/schedulers` -- `DELETE`: delete collection of Scheduler -- `GET`: list objects of kind Scheduler -- `POST`: create a Scheduler -* `/apis/config.openshift.io/v1/schedulers/{name}` -- `DELETE`: delete a Scheduler -- `GET`: read the specified Scheduler -- `PATCH`: partially update the specified Scheduler -- `PUT`: replace the specified Scheduler -* `/apis/config.openshift.io/v1/schedulers/{name}/status` -- `GET`: read status of the specified Scheduler -- `PATCH`: partially update status of the specified Scheduler -- `PUT`: replace status of the specified Scheduler - - -=== /apis/config.openshift.io/v1/schedulers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#schedulerlist-config-openshift-io-v1[`SchedulerList config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 202 - Accepted -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/schedulers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Scheduler -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/config.openshift.io/v1/schedulers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Scheduler -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Scheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 201 - Created -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`Scheduler config.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/console_apis/console-apis-index.adoc b/rest_api/console_apis/console-apis-index.adoc deleted file mode 100644 index 6e79b5125cf9..000000000000 --- a/rest_api/console_apis/console-apis-index.adoc +++ /dev/null @@ -1,56 +0,0 @@ -[id="console-apis"] -= Console APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== ConsoleCLIDownload [console.openshift.io/v1] - -Description:: - ConsoleCLIDownload is an extension for configuring openshift web console command line interface (CLI) downloads. - -Type:: - `object` - -== ConsoleExternalLogLink [console.openshift.io/v1] - -Description:: - ConsoleExternalLogLink is an extension for customizing OpenShift web console log links. - -Type:: - `object` - -== ConsoleLink [console.openshift.io/v1] - -Description:: - ConsoleLink is an extension for customizing OpenShift web console links. - -Type:: - `object` - -== ConsoleNotification [console.openshift.io/v1] - -Description:: - ConsoleNotification is the extension for configuring openshift web console notifications. - -Type:: - `object` - -== ConsoleQuickStart [console.openshift.io/v1] - -Description:: - ConsoleQuickStart is an extension for guiding user through various workflows in the OpenShift web console. - -Type:: - `object` - -== ConsoleYAMLSample [console.openshift.io/v1] - -Description:: - ConsoleYAMLSample is an extension for customizing OpenShift web console YAML samples. - -Type:: - `object` - diff --git a/rest_api/console_apis/consoleclidownload-console-openshift-io-v1.adoc b/rest_api/console_apis/consoleclidownload-console-openshift-io-v1.adoc deleted file mode 100644 index 20dafd079fbf..000000000000 --- a/rest_api/console_apis/consoleclidownload-console-openshift-io-v1.adoc +++ /dev/null @@ -1,607 +0,0 @@ -[id="consoleclidownload-console-openshift-io-v1"] -= ConsoleCLIDownload [console.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ConsoleCLIDownload is an extension for configuring openshift web console command line interface (CLI) downloads. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ConsoleCLIDownloadSpec is the desired cli download configuration. - -|=== -..spec -Description:: - ConsoleCLIDownloadSpec is the desired cli download configuration. - -Type:: - `object` - -Required:: - - `description` - - `displayName` - - `links` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| description is the description of the CLI download (can include markdown). - -| `displayName` -| `string` -| displayName is the display name of the CLI download. - -| `links` -| `array` -| links is a list of objects that provide CLI download link details. - -| `links[]` -| `object` -| - -|=== -..spec.links -Description:: - links is a list of objects that provide CLI download link details. - -Type:: - `array` - - - - -..spec.links[] -Description:: - - -Type:: - `object` - -Required:: - - `href` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `href` -| `string` -| href is the absolute secure URL for the link (must use https) - -| `text` -| `string` -| text is the display text for the link - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/console.openshift.io/v1/consoleclidownloads` -- `DELETE`: delete collection of ConsoleCLIDownload -- `GET`: list objects of kind ConsoleCLIDownload -- `POST`: create a ConsoleCLIDownload -* `/apis/console.openshift.io/v1/consoleclidownloads/{name}` -- `DELETE`: delete a ConsoleCLIDownload -- `GET`: read the specified ConsoleCLIDownload -- `PATCH`: partially update the specified ConsoleCLIDownload -- `PUT`: replace the specified ConsoleCLIDownload -* `/apis/console.openshift.io/v1/consoleclidownloads/{name}/status` -- `GET`: read status of the specified ConsoleCLIDownload -- `PATCH`: partially update status of the specified ConsoleCLIDownload -- `PUT`: replace status of the specified ConsoleCLIDownload - - -=== /apis/console.openshift.io/v1/consoleclidownloads - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#consoleclidownloadlist-console-openshift-io-v1[`ConsoleCLIDownloadList console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 202 - Accepted -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consoleclidownloads/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleCLIDownload -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consoleclidownloads/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleCLIDownload -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ConsoleCLIDownload - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`ConsoleCLIDownload console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/console_apis/consoleexternalloglink-console-openshift-io-v1.adoc b/rest_api/console_apis/consoleexternalloglink-console-openshift-io-v1.adoc deleted file mode 100644 index 19d4aa4c7cf0..000000000000 --- a/rest_api/console_apis/consoleexternalloglink-console-openshift-io-v1.adoc +++ /dev/null @@ -1,568 +0,0 @@ -[id="consoleexternalloglink-console-openshift-io-v1"] -= ConsoleExternalLogLink [console.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ConsoleExternalLogLink is an extension for customizing OpenShift web console log links. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ConsoleExternalLogLinkSpec is the desired log link configuration. The log link will appear on the logs tab of the pod details page. - -|=== -..spec -Description:: - ConsoleExternalLogLinkSpec is the desired log link configuration. The log link will appear on the logs tab of the pod details page. - -Type:: - `object` - -Required:: - - `hrefTemplate` - - `text` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hrefTemplate` -| `string` -| hrefTemplate is an absolute secure URL (must use https) for the log link including variables to be replaced. Variables are specified in the URL with the format ${variableName}, for instance, ${containerName} and will be replaced with the corresponding values from the resource. Resource is a pod. Supported variables are: - ${resourceName} - name of the resource which containes the logs - ${resourceUID} - UID of the resource which contains the logs - e.g. `11111111-2222-3333-4444-555555555555` - ${containerName} - name of the resource's container that contains the logs - ${resourceNamespace} - namespace of the resource that contains the logs - ${resourceNamespaceUID} - namespace UID of the resource that contains the logs - ${podLabels} - JSON representation of labels matching the pod with the logs - e.g. `{"key1":"value1","key2":"value2"}` - e.g., https://example.com/logs?resourceName=${resourceName}&containerName=${containerName}&resourceNamespace=${resourceNamespace}&podLabels=${podLabels} - -| `namespaceFilter` -| `string` -| namespaceFilter is a regular expression used to restrict a log link to a matching set of namespaces (e.g., `^openshift-`). The string is converted into a regular expression using the JavaScript RegExp constructor. If not specified, links will be displayed for all the namespaces. - -| `text` -| `string` -| text is the display text for the link - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/console.openshift.io/v1/consoleexternalloglinks` -- `DELETE`: delete collection of ConsoleExternalLogLink -- `GET`: list objects of kind ConsoleExternalLogLink -- `POST`: create a ConsoleExternalLogLink -* `/apis/console.openshift.io/v1/consoleexternalloglinks/{name}` -- `DELETE`: delete a ConsoleExternalLogLink -- `GET`: read the specified ConsoleExternalLogLink -- `PATCH`: partially update the specified ConsoleExternalLogLink -- `PUT`: replace the specified ConsoleExternalLogLink -* `/apis/console.openshift.io/v1/consoleexternalloglinks/{name}/status` -- `GET`: read status of the specified ConsoleExternalLogLink -- `PATCH`: partially update status of the specified ConsoleExternalLogLink -- `PUT`: replace status of the specified ConsoleExternalLogLink - - -=== /apis/console.openshift.io/v1/consoleexternalloglinks - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#consoleexternalloglinklist-console-openshift-io-v1[`ConsoleExternalLogLinkList console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 202 - Accepted -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consoleexternalloglinks/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleExternalLogLink -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consoleexternalloglinks/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleExternalLogLink -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ConsoleExternalLogLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`ConsoleExternalLogLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc b/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc deleted file mode 100644 index 750c10122ee7..000000000000 --- a/rest_api/console_apis/consolelink-console-openshift-io-v1.adoc +++ /dev/null @@ -1,691 +0,0 @@ -[id="consolelink-console-openshift-io-v1"] -= ConsoleLink [console.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ConsoleLink is an extension for customizing OpenShift web console links. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ConsoleLinkSpec is the desired console link configuration. - -|=== -..spec -Description:: - ConsoleLinkSpec is the desired console link configuration. - -Type:: - `object` - -Required:: - - `href` - - `location` - - `text` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `applicationMenu` -| `object` -| applicationMenu holds information about section and icon used for the link in the application menu, and it is applicable only when location is set to ApplicationMenu. - -| `href` -| `string` -| href is the absolute secure URL for the link (must use https) - -| `location` -| `string` -| location determines which location in the console the link will be appended to (ApplicationMenu, HelpMenu, UserMenu, NamespaceDashboard). - -| `namespaceDashboard` -| `object` -| namespaceDashboard holds information about namespaces in which the dashboard link should appear, and it is applicable only when location is set to NamespaceDashboard. If not specified, the link will appear in all namespaces. - -| `text` -| `string` -| text is the display text for the link - -|=== -..spec.applicationMenu -Description:: - applicationMenu holds information about section and icon used for the link in the application menu, and it is applicable only when location is set to ApplicationMenu. - -Type:: - `object` - -Required:: - - `section` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `imageURL` -| `string` -| imageUrl is the URL for the icon used in front of the link in the application menu. The URL must be an HTTPS URL or a Data URI. The image should be square and will be shown at 24x24 pixels. - -| `section` -| `string` -| section is the section of the application menu in which the link should appear. This can be any text that will appear as a subheading in the application menu dropdown. A new section will be created if the text does not match text of an existing section. - -|=== -..spec.namespaceDashboard -Description:: - namespaceDashboard holds information about namespaces in which the dashboard link should appear, and it is applicable only when location is set to NamespaceDashboard. If not specified, the link will appear in all namespaces. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namespaceSelector` -| `object` -| namespaceSelector is used to select the Namespaces that should contain dashboard link by label. If the namespace labels match, dashboard link will be shown for the namespaces. - -| `namespaces` -| `array (string)` -| namespaces is an array of namespace names in which the dashboard link should appear. - -|=== -..spec.namespaceDashboard.namespaceSelector -Description:: - namespaceSelector is used to select the Namespaces that should contain dashboard link by label. If the namespace labels match, dashboard link will be shown for the namespaces. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.namespaceDashboard.namespaceSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.namespaceDashboard.namespaceSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/console.openshift.io/v1/consolelinks` -- `DELETE`: delete collection of ConsoleLink -- `GET`: list objects of kind ConsoleLink -- `POST`: create a ConsoleLink -* `/apis/console.openshift.io/v1/consolelinks/{name}` -- `DELETE`: delete a ConsoleLink -- `GET`: read the specified ConsoleLink -- `PATCH`: partially update the specified ConsoleLink -- `PUT`: replace the specified ConsoleLink -* `/apis/console.openshift.io/v1/consolelinks/{name}/status` -- `GET`: read status of the specified ConsoleLink -- `PATCH`: partially update status of the specified ConsoleLink -- `PUT`: replace status of the specified ConsoleLink - - -=== /apis/console.openshift.io/v1/consolelinks - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#consolelinklist-console-openshift-io-v1[`ConsoleLinkList console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 202 - Accepted -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consolelinks/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleLink -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consolelinks/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleLink -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ConsoleLink - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`ConsoleLink console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/console_apis/consolenotification-console-openshift-io-v1.adoc b/rest_api/console_apis/consolenotification-console-openshift-io-v1.adoc deleted file mode 100644 index 9a00500bf84b..000000000000 --- a/rest_api/console_apis/consolenotification-console-openshift-io-v1.adoc +++ /dev/null @@ -1,600 +0,0 @@ -[id="consolenotification-console-openshift-io-v1"] -= ConsoleNotification [console.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ConsoleNotification is the extension for configuring openshift web console notifications. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ConsoleNotificationSpec is the desired console notification configuration. - -|=== -..spec -Description:: - ConsoleNotificationSpec is the desired console notification configuration. - -Type:: - `object` - -Required:: - - `text` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `backgroundColor` -| `string` -| backgroundColor is the color of the background for the notification as CSS data type color. - -| `color` -| `string` -| color is the color of the text for the notification as CSS data type color. - -| `link` -| `object` -| link is an object that holds notification link details. - -| `location` -| `string` -| location is the location of the notification in the console. Valid values are: "BannerTop", "BannerBottom", "BannerTopBottom". - -| `text` -| `string` -| text is the visible text of the notification. - -|=== -..spec.link -Description:: - link is an object that holds notification link details. - -Type:: - `object` - -Required:: - - `href` - - `text` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `href` -| `string` -| href is the absolute secure URL for the link (must use https) - -| `text` -| `string` -| text is the display text for the link - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/console.openshift.io/v1/consolenotifications` -- `DELETE`: delete collection of ConsoleNotification -- `GET`: list objects of kind ConsoleNotification -- `POST`: create a ConsoleNotification -* `/apis/console.openshift.io/v1/consolenotifications/{name}` -- `DELETE`: delete a ConsoleNotification -- `GET`: read the specified ConsoleNotification -- `PATCH`: partially update the specified ConsoleNotification -- `PUT`: replace the specified ConsoleNotification -* `/apis/console.openshift.io/v1/consolenotifications/{name}/status` -- `GET`: read status of the specified ConsoleNotification -- `PATCH`: partially update status of the specified ConsoleNotification -- `PUT`: replace status of the specified ConsoleNotification - - -=== /apis/console.openshift.io/v1/consolenotifications - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#consolenotificationlist-console-openshift-io-v1[`ConsoleNotificationList console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 202 - Accepted -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consolenotifications/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleNotification -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consolenotifications/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleNotification -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ConsoleNotification - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`ConsoleNotification console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/console_apis/consolequickstart-console-openshift-io-v1.adoc b/rest_api/console_apis/consolequickstart-console-openshift-io-v1.adoc deleted file mode 100644 index 41599b08d212..000000000000 --- a/rest_api/console_apis/consolequickstart-console-openshift-io-v1.adoc +++ /dev/null @@ -1,627 +0,0 @@ -[id="consolequickstart-console-openshift-io-v1"] -= ConsoleQuickStart [console.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ConsoleQuickStart is an extension for guiding user through various workflows in the OpenShift web console. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ConsoleQuickStartSpec is the desired quick start configuration. - -|=== -..spec -Description:: - ConsoleQuickStartSpec is the desired quick start configuration. - -Type:: - `object` - -Required:: - - `description` - - `displayName` - - `durationMinutes` - - `introduction` - - `tasks` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessReviewResources` -| `array` -| accessReviewResources contains a list of resources that the user's access will be reviewed against in order for the user to complete the Quick Start. The Quick Start will be hidden if any of the access reviews fail. - -| `accessReviewResources[]` -| `object` -| ResourceAttributes includes the authorization attributes available for resource requests to the Authorizer interface - -| `conclusion` -| `string` -| conclusion sums up the Quick Start and suggests the possible next steps. (includes markdown) - -| `description` -| `string` -| description is the description of the Quick Start. (includes markdown) - -| `displayName` -| `string` -| displayName is the display name of the Quick Start. - -| `durationMinutes` -| `integer` -| durationMinutes describes approximately how many minutes it will take to complete the Quick Start. - -| `icon` -| `string` -| icon is a base64 encoded image that will be displayed beside the Quick Start display name. The icon should be an vector image for easy scaling. The size of the icon should be 40x40. - -| `introduction` -| `string` -| introduction describes the purpose of the Quick Start. (includes markdown) - -| `nextQuickStart` -| `array (string)` -| nextQuickStart is a list of the following Quick Starts, suggested for the user to try. - -| `prerequisites` -| `array (string)` -| prerequisites contains all prerequisites that need to be met before taking a Quick Start. (includes markdown) - -| `tags` -| `array (string)` -| tags is a list of strings that describe the Quick Start. - -| `tasks` -| `array` -| tasks is the list of steps the user has to perform to complete the Quick Start. - -| `tasks[]` -| `object` -| ConsoleQuickStartTask is a single step in a Quick Start. - -|=== -..spec.accessReviewResources -Description:: - accessReviewResources contains a list of resources that the user's access will be reviewed against in order for the user to complete the Quick Start. The Quick Start will be hidden if any of the access reviews fail. - -Type:: - `array` - - - - -..spec.accessReviewResources[] -Description:: - ResourceAttributes includes the authorization attributes available for resource requests to the Authorizer interface - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group is the API Group of the Resource. "*" means all. - -| `name` -| `string` -| Name is the name of the resource being requested for a "get" or deleted for a "delete". "" (empty) means all. - -| `namespace` -| `string` -| Namespace is the namespace of the action being requested. Currently, there is no distinction between no namespace and all namespaces "" (empty) is defaulted for LocalSubjectAccessReviews "" (empty) is empty for cluster-scoped resources "" (empty) means "all" for namespace scoped resources from a SubjectAccessReview or SelfSubjectAccessReview - -| `resource` -| `string` -| Resource is one of the existing resource types. "*" means all. - -| `subresource` -| `string` -| Subresource is one of the existing resource types. "" means none. - -| `verb` -| `string` -| Verb is a kubernetes resource API verb, like: get, list, watch, create, update, delete, proxy. "*" means all. - -| `version` -| `string` -| Version is the API Version of the Resource. "*" means all. - -|=== -..spec.tasks -Description:: - tasks is the list of steps the user has to perform to complete the Quick Start. - -Type:: - `array` - - - - -..spec.tasks[] -Description:: - ConsoleQuickStartTask is a single step in a Quick Start. - -Type:: - `object` - -Required:: - - `description` - - `title` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| description describes the steps needed to complete the task. (includes markdown) - -| `review` -| `object` -| review contains instructions to validate the task is complete. The user will select 'Yes' or 'No'. using a radio button, which indicates whether the step was completed successfully. - -| `summary` -| `object` -| summary contains information about the passed step. - -| `title` -| `string` -| title describes the task and is displayed as a step heading. - -|=== -..spec.tasks[].review -Description:: - review contains instructions to validate the task is complete. The user will select 'Yes' or 'No'. using a radio button, which indicates whether the step was completed successfully. - -Type:: - `object` - -Required:: - - `failedTaskHelp` - - `instructions` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `failedTaskHelp` -| `string` -| failedTaskHelp contains suggestions for a failed task review and is shown at the end of task. (includes markdown) - -| `instructions` -| `string` -| instructions contains steps that user needs to take in order to validate his work after going through a task. (includes markdown) - -|=== -..spec.tasks[].summary -Description:: - summary contains information about the passed step. - -Type:: - `object` - -Required:: - - `failed` - - `success` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `failed` -| `string` -| failed briefly describes the unsuccessfully passed task. (includes markdown) - -| `success` -| `string` -| success describes the succesfully passed task. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/console.openshift.io/v1/consolequickstarts` -- `DELETE`: delete collection of ConsoleQuickStart -- `GET`: list objects of kind ConsoleQuickStart -- `POST`: create a ConsoleQuickStart -* `/apis/console.openshift.io/v1/consolequickstarts/{name}` -- `DELETE`: delete a ConsoleQuickStart -- `GET`: read the specified ConsoleQuickStart -- `PATCH`: partially update the specified ConsoleQuickStart -- `PUT`: replace the specified ConsoleQuickStart - - -=== /apis/console.openshift.io/v1/consolequickstarts - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ConsoleQuickStart - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ConsoleQuickStart - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#consolequickstartlist-console-openshift-io-v1[`ConsoleQuickStartList console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ConsoleQuickStart - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| 202 - Accepted -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consolequickstarts/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleQuickStart -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ConsoleQuickStart - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ConsoleQuickStart - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ConsoleQuickStart - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ConsoleQuickStart - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`ConsoleQuickStart console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/console_apis/consoleyamlsample-console-openshift-io-v1.adoc b/rest_api/console_apis/consoleyamlsample-console-openshift-io-v1.adoc deleted file mode 100644 index 4820b11b5c71..000000000000 --- a/rest_api/console_apis/consoleyamlsample-console-openshift-io-v1.adoc +++ /dev/null @@ -1,469 +0,0 @@ -[id="consoleyamlsample-console-openshift-io-v1"] -= ConsoleYAMLSample [console.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ConsoleYAMLSample is an extension for customizing OpenShift web console YAML samples. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ConsoleYAMLSampleSpec is the desired YAML sample configuration. Samples will appear with their descriptions in a samples sidebar when creating a resources in the web console. - -|=== -..spec -Description:: - ConsoleYAMLSampleSpec is the desired YAML sample configuration. Samples will appear with their descriptions in a samples sidebar when creating a resources in the web console. - -Type:: - `object` - -Required:: - - `description` - - `targetResource` - - `title` - - `yaml` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| description of the YAML sample. - -| `snippet` -| `boolean` -| snippet indicates that the YAML sample is not the full YAML resource definition, but a fragment that can be inserted into the existing YAML document at the user's cursor. - -| `targetResource` -| `object` -| targetResource contains apiVersion and kind of the resource YAML sample is representating. - -| `title` -| `string` -| title of the YAML sample. - -| `yaml` -| `string` -| yaml is the YAML sample to display. - -|=== -..spec.targetResource -Description:: - targetResource contains apiVersion and kind of the resource YAML sample is representating. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/console.openshift.io/v1/consoleyamlsamples` -- `DELETE`: delete collection of ConsoleYAMLSample -- `GET`: list objects of kind ConsoleYAMLSample -- `POST`: create a ConsoleYAMLSample -* `/apis/console.openshift.io/v1/consoleyamlsamples/{name}` -- `DELETE`: delete a ConsoleYAMLSample -- `GET`: read the specified ConsoleYAMLSample -- `PATCH`: partially update the specified ConsoleYAMLSample -- `PUT`: replace the specified ConsoleYAMLSample - - -=== /apis/console.openshift.io/v1/consoleyamlsamples - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ConsoleYAMLSample - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ConsoleYAMLSample - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#consoleyamlsamplelist-console-openshift-io-v1[`ConsoleYAMLSampleList console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ConsoleYAMLSample - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| 202 - Accepted -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/console.openshift.io/v1/consoleyamlsamples/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConsoleYAMLSample -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ConsoleYAMLSample - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ConsoleYAMLSample - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ConsoleYAMLSample - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ConsoleYAMLSample - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| 201 - Created -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`ConsoleYAMLSample console.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/extension_apis/apiservice-apiregistration-k8s-io-v1.adoc b/rest_api/extension_apis/apiservice-apiregistration-k8s-io-v1.adoc deleted file mode 100644 index e57e330b1340..000000000000 --- a/rest_api/extension_apis/apiservice-apiregistration-k8s-io-v1.adoc +++ /dev/null @@ -1,692 +0,0 @@ -[id="apiservice-apiregistration-k8s-io-v1"] -= APIService [apiregistration.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - APIService represents a server for a particular GroupVersion. Name must be "version.group". - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| APIServiceSpec contains information for locating and communicating with a server. Only https is supported, though you are able to disable certificate verification. - -| `status` -| `object` -| APIServiceStatus contains derived information about an API server - -|=== -..spec -Description:: - APIServiceSpec contains information for locating and communicating with a server. Only https is supported, though you are able to disable certificate verification. - -Type:: - `object` - -Required:: - - `groupPriorityMinimum` - - `versionPriority` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `caBundle` -| `string` -| CABundle is a PEM encoded CA bundle which will be used to validate an API server's serving certificate. If unspecified, system trust roots on the apiserver are used. - -| `group` -| `string` -| Group is the API group name this server hosts - -| `groupPriorityMinimum` -| `integer` -| GroupPriorityMininum is the priority this group should have at least. Higher priority means that the group is preferred by clients over lower priority ones. Note that other versions of this group might specify even higher GroupPriorityMininum values such that the whole group gets a higher priority. The primary sort is based on GroupPriorityMinimum, ordered highest number to lowest (20 before 10). The secondary sort is based on the alphabetical comparison of the name of the object. (v1.bar before v1.foo) We'd recommend something like: *.k8s.io (except extensions) at 18000 and PaaSes (OpenShift, Deis) are recommended to be in the 2000s - -| `insecureSkipTLSVerify` -| `boolean` -| InsecureSkipTLSVerify disables TLS certificate verification when communicating with this server. This is strongly discouraged. You should use the CABundle instead. - -| `service` -| `object` -| ServiceReference holds a reference to Service.legacy.k8s.io - -| `version` -| `string` -| Version is the API version this server hosts. For example, "v1" - -| `versionPriority` -| `integer` -| VersionPriority controls the ordering of this API version inside of its group. Must be greater than zero. The primary sort is based on VersionPriority, ordered highest to lowest (20 before 10). Since it's inside of a group, the number can be small, probably in the 10s. In case of equal version priorities, the version string will be used to compute the order inside a group. If the version string is "kube-like", it will sort above non "kube-like" version strings, which are ordered lexicographically. "Kube-like" versions start with a "v", then are followed by a number (the major version), then optionally the string "alpha" or "beta" and another number (the minor version). These are sorted first by GA > beta > alpha (where GA is a version with no suffix such as beta or alpha), and then by comparing major version, then minor version. An example sorted list of versions: v10, v2, v1, v11beta2, v10beta3, v3beta1, v12alpha1, v11alpha2, foo1, foo10. - -|=== -..spec.service -Description:: - ServiceReference holds a reference to Service.legacy.k8s.io - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the name of the service - -| `namespace` -| `string` -| Namespace is the namespace of the service - -| `port` -| `integer` -| If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. `port` should be a valid port number (1-65535, inclusive). - -|=== -..status -Description:: - APIServiceStatus contains derived information about an API server - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| Current service state of apiService. - -| `conditions[]` -| `object` -| APIServiceCondition describes the state of an APIService at a particular point - -|=== -..status.conditions -Description:: - Current service state of apiService. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - APIServiceCondition describes the state of an APIService at a particular point - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| Human-readable message indicating details about last transition. - -| `reason` -| `string` -| Unique, one-word, CamelCase reason for the condition's last transition. - -| `status` -| `string` -| Status is the status of the condition. Can be True, False, Unknown. - -| `type` -| `string` -| Type is the type of the condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/apiregistration.k8s.io/v1/apiservices` -- `DELETE`: delete collection of APIService -- `GET`: list or watch objects of kind APIService -- `POST`: create an APIService -* `/apis/apiregistration.k8s.io/v1/apiservices/{name}` -- `DELETE`: delete an APIService -- `GET`: read the specified APIService -- `PATCH`: partially update the specified APIService -- `PUT`: replace the specified APIService -* `/apis/apiregistration.k8s.io/v1/apiservices/{name}/status` -- `GET`: read status of the specified APIService -- `PATCH`: partially update status of the specified APIService -- `PUT`: replace status of the specified APIService - - -=== /apis/apiregistration.k8s.io/v1/apiservices - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#apiservicelist-apiregistration-k8s-io-v1[`APIServiceList apiregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 202 - Accepted -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apiregistration.k8s.io/v1/apiservices/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the APIService -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apiregistration.k8s.io/v1/apiservices/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the APIService -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified APIService - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified APIService - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`APIService apiregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc b/rest_api/extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc deleted file mode 100644 index c5e049a6bcac..000000000000 --- a/rest_api/extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc +++ /dev/null @@ -1,1083 +0,0 @@ -[id="customresourcedefinition-apiextensions-k8s-io-v1"] -= CustomResourceDefinition [apiextensions.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CustomResourceDefinition represents a resource that should be exposed on the API server. Its name MUST be in the format <.spec.name>.<.spec.group>. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| CustomResourceDefinitionSpec describes how a user wants their resource to appear - -| `status` -| `object` -| CustomResourceDefinitionStatus indicates the state of the CustomResourceDefinition - -|=== -..spec -Description:: - CustomResourceDefinitionSpec describes how a user wants their resource to appear - -Type:: - `object` - -Required:: - - `group` - - `names` - - `scope` - - `versions` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conversion` -| `object` -| CustomResourceConversion describes how to convert different versions of a CR. - -| `group` -| `string` -| group is the API group of the defined custom resource. The custom resources are served under `/apis/<group>/...`. Must match the name of the CustomResourceDefinition (in the form `<names.plural>.<group>`). - -| `names` -| `object` -| CustomResourceDefinitionNames indicates the names to serve this CustomResourceDefinition - -| `preserveUnknownFields` -| `boolean` -| preserveUnknownFields indicates that object fields which are not specified in the OpenAPI schema should be preserved when persisting to storage. apiVersion, kind, metadata and known fields inside metadata are always preserved. This field is deprecated in favor of setting `x-preserve-unknown-fields` to true in `spec.versions[*].schema.openAPIV3Schema`. See https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#pruning-versus-preserving-unknown-fields for details. - -| `scope` -| `string` -| scope indicates whether the defined custom resource is cluster- or namespace-scoped. Allowed values are `Cluster` and `Namespaced`. - -| `versions` -| `array` -| versions is the list of all API versions of the defined custom resource. Version names are used to compute the order in which served versions are listed in API discovery. If the version string is "kube-like", it will sort above non "kube-like" version strings, which are ordered lexicographically. "Kube-like" versions start with a "v", then are followed by a number (the major version), then optionally the string "alpha" or "beta" and another number (the minor version). These are sorted first by GA > beta > alpha (where GA is a version with no suffix such as beta or alpha), and then by comparing major version, then minor version. An example sorted list of versions: v10, v2, v1, v11beta2, v10beta3, v3beta1, v12alpha1, v11alpha2, foo1, foo10. - -| `versions[]` -| `object` -| CustomResourceDefinitionVersion describes a version for CRD. - -|=== -..spec.conversion -Description:: - CustomResourceConversion describes how to convert different versions of a CR. - -Type:: - `object` - -Required:: - - `strategy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `strategy` -| `string` -| strategy specifies how custom resources are converted between versions. Allowed values are: - `None`: The converter only change the apiVersion and would not touch any other field in the custom resource. - `Webhook`: API Server will call to an external webhook to do the conversion. Additional information - is needed for this option. This requires spec.preserveUnknownFields to be false, and spec.conversion.webhook to be set. - -| `webhook` -| `object` -| WebhookConversion describes how to call a conversion webhook - -|=== -..spec.conversion.webhook -Description:: - WebhookConversion describes how to call a conversion webhook - -Type:: - `object` - -Required:: - - `conversionReviewVersions` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clientConfig` -| `object` -| WebhookClientConfig contains the information to make a TLS connection with the webhook. - -| `conversionReviewVersions` -| `array (string)` -| conversionReviewVersions is an ordered list of preferred `ConversionReview` versions the Webhook expects. The API server will use the first version in the list which it supports. If none of the versions specified in this list are supported by API server, conversion will fail for the custom resource. If a persisted Webhook configuration specifies allowed versions and does not include any versions known to the API Server, calls to the webhook will fail. - -|=== -..spec.conversion.webhook.clientConfig -Description:: - WebhookClientConfig contains the information to make a TLS connection with the webhook. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `caBundle` -| `string` -| caBundle is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. - -| `service` -| `object` -| ServiceReference holds a reference to Service.legacy.k8s.io - -| `url` -| `string` -| url gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. - -The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. - -Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installs are likely to be non-portable, i.e., not easy to turn up in a new cluster. - -The scheme must be "https"; the URL must begin with "https://". - -A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. - -Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. - -|=== -..spec.conversion.webhook.clientConfig.service -Description:: - ServiceReference holds a reference to Service.legacy.k8s.io - -Type:: - `object` - -Required:: - - `namespace` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the name of the service. Required - -| `namespace` -| `string` -| namespace is the namespace of the service. Required - -| `path` -| `string` -| path is an optional URL path at which the webhook will be contacted. - -| `port` -| `integer` -| port is an optional service port at which the webhook will be contacted. `port` should be a valid port number (1-65535, inclusive). Defaults to 443 for backward compatibility. - -|=== -..spec.names -Description:: - CustomResourceDefinitionNames indicates the names to serve this CustomResourceDefinition - -Type:: - `object` - -Required:: - - `plural` - - `kind` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `categories` -| `array (string)` -| categories is a list of grouped resources this custom resource belongs to (e.g. 'all'). This is published in API discovery documents, and used by clients to support invocations like `kubectl get all`. - -| `kind` -| `string` -| kind is the serialized kind of the resource. It is normally CamelCase and singular. Custom resource instances will use this value as the `kind` attribute in API calls. - -| `listKind` -| `string` -| listKind is the serialized kind of the list for this resource. Defaults to "`kind`List". - -| `plural` -| `string` -| plural is the plural name of the resource to serve. The custom resources are served under `/apis/<group>/<version>/.../<plural>`. Must match the name of the CustomResourceDefinition (in the form `<names.plural>.<group>`). Must be all lowercase. - -| `shortNames` -| `array (string)` -| shortNames are short names for the resource, exposed in API discovery documents, and used by clients to support invocations like `kubectl get <shortname>`. It must be all lowercase. - -| `singular` -| `string` -| singular is the singular name of the resource. It must be all lowercase. Defaults to lowercased `kind`. - -|=== -..spec.versions -Description:: - versions is the list of all API versions of the defined custom resource. Version names are used to compute the order in which served versions are listed in API discovery. If the version string is "kube-like", it will sort above non "kube-like" version strings, which are ordered lexicographically. "Kube-like" versions start with a "v", then are followed by a number (the major version), then optionally the string "alpha" or "beta" and another number (the minor version). These are sorted first by GA > beta > alpha (where GA is a version with no suffix such as beta or alpha), and then by comparing major version, then minor version. An example sorted list of versions: v10, v2, v1, v11beta2, v10beta3, v3beta1, v12alpha1, v11alpha2, foo1, foo10. - -Type:: - `array` - - - - -..spec.versions[] -Description:: - CustomResourceDefinitionVersion describes a version for CRD. - -Type:: - `object` - -Required:: - - `name` - - `served` - - `storage` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalPrinterColumns` -| `array` -| additionalPrinterColumns specifies additional columns returned in Table output. See https://kubernetes.io/docs/reference/using-api/api-concepts/#receiving-resources-as-tables for details. If no columns are specified, a single column displaying the age of the custom resource is used. - -| `additionalPrinterColumns[]` -| `object` -| CustomResourceColumnDefinition specifies a column for server side printing. - -| `deprecated` -| `boolean` -| deprecated indicates this version of the custom resource API is deprecated. When set to true, API requests to this version receive a warning header in the server response. Defaults to false. - -| `deprecationWarning` -| `string` -| deprecationWarning overrides the default warning returned to API clients. May only be set when `deprecated` is true. The default warning indicates this version is deprecated and recommends use of the newest served version of equal or greater stability, if one exists. - -| `name` -| `string` -| name is the version name, e.g. “v1”, “v2beta1”, etc. The custom resources are served under this version at `/apis/<group>/<version>/...` if `served` is true. - -| `schema` -| `object` -| CustomResourceValidation is a list of validation methods for CustomResources. - -| `served` -| `boolean` -| served is a flag enabling/disabling this version from being served via REST APIs - -| `storage` -| `boolean` -| storage indicates this version should be used when persisting custom resources to storage. There must be exactly one version with storage=true. - -| `subresources` -| `object` -| CustomResourceSubresources defines the status and scale subresources for CustomResources. - -|=== -..spec.versions[].additionalPrinterColumns -Description:: - additionalPrinterColumns specifies additional columns returned in Table output. See https://kubernetes.io/docs/reference/using-api/api-concepts/#receiving-resources-as-tables for details. If no columns are specified, a single column displaying the age of the custom resource is used. - -Type:: - `array` - - - - -..spec.versions[].additionalPrinterColumns[] -Description:: - CustomResourceColumnDefinition specifies a column for server side printing. - -Type:: - `object` - -Required:: - - `name` - - `type` - - `jsonPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| description is a human readable description of this column. - -| `format` -| `string` -| format is an optional OpenAPI type definition for this column. The 'name' format is applied to the primary identifier column to assist in clients identifying column is the resource name. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for details. - -| `jsonPath` -| `string` -| jsonPath is a simple JSON path (i.e. with array notation) which is evaluated against each custom resource to produce the value for this column. - -| `name` -| `string` -| name is a human readable name for the column. - -| `priority` -| `integer` -| priority is an integer defining the relative importance of this column compared to others. Lower numbers are considered higher priority. Columns that may be omitted in limited space scenarios should be given a priority greater than 0. - -| `type` -| `string` -| type is an OpenAPI type definition for this column. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types for details. - -|=== -..spec.versions[].schema -Description:: - CustomResourceValidation is a list of validation methods for CustomResources. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `openAPIV3Schema` -| `` -| openAPIV3Schema is the OpenAPI v3 schema to use for validation and pruning. - -|=== -..spec.versions[].subresources -Description:: - CustomResourceSubresources defines the status and scale subresources for CustomResources. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `scale` -| `object` -| CustomResourceSubresourceScale defines how to serve the scale subresource for CustomResources. - -| `status` -| `object` -| CustomResourceSubresourceStatus defines how to serve the status subresource for CustomResources. Status is represented by the `.status` JSON path inside of a CustomResource. When set, * exposes a /status subresource for the custom resource * PUT requests to the /status subresource take a custom resource object, and ignore changes to anything except the status stanza * PUT/POST/PATCH requests to the custom resource ignore changes to the status stanza - -|=== -..spec.versions[].subresources.scale -Description:: - CustomResourceSubresourceScale defines how to serve the scale subresource for CustomResources. - -Type:: - `object` - -Required:: - - `specReplicasPath` - - `statusReplicasPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelectorPath` -| `string` -| labelSelectorPath defines the JSON path inside of a custom resource that corresponds to Scale `status.selector`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.status` or `.spec`. Must be set to work with HorizontalPodAutoscaler. The field pointed by this JSON path must be a string field (not a complex selector struct) which contains a serialized label selector in string form. More info: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions#scale-subresource If there is no value under the given path in the custom resource, the `status.selector` value in the `/scale` subresource will default to the empty string. - -| `specReplicasPath` -| `string` -| specReplicasPath defines the JSON path inside of a custom resource that corresponds to Scale `spec.replicas`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.spec`. If there is no value under the given path in the custom resource, the `/scale` subresource will return an error on GET. - -| `statusReplicasPath` -| `string` -| statusReplicasPath defines the JSON path inside of a custom resource that corresponds to Scale `status.replicas`. Only JSON paths without the array notation are allowed. Must be a JSON Path under `.status`. If there is no value under the given path in the custom resource, the `status.replicas` value in the `/scale` subresource will default to 0. - -|=== -..spec.versions[].subresources.status -Description:: - CustomResourceSubresourceStatus defines how to serve the status subresource for CustomResources. Status is represented by the `.status` JSON path inside of a CustomResource. When set, * exposes a /status subresource for the custom resource * PUT requests to the /status subresource take a custom resource object, and ignore changes to anything except the status stanza * PUT/POST/PATCH requests to the custom resource ignore changes to the status stanza - -Type:: - `object` - - - - -..status -Description:: - CustomResourceDefinitionStatus indicates the state of the CustomResourceDefinition - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `acceptedNames` -| `object` -| CustomResourceDefinitionNames indicates the names to serve this CustomResourceDefinition - -| `conditions` -| `array` -| conditions indicate state for particular aspects of a CustomResourceDefinition - -| `conditions[]` -| `object` -| CustomResourceDefinitionCondition contains details for the current condition of this pod. - -| `storedVersions` -| `array (string)` -| storedVersions lists all versions of CustomResources that were ever persisted. Tracking these versions allows a migration path for stored versions in etcd. The field is mutable so a migration controller can finish a migration to another version (ensuring no old objects are left in storage), and then remove the rest of the versions from this list. Versions may not be removed from `spec.versions` while they exist in this list. - -|=== -..status.acceptedNames -Description:: - CustomResourceDefinitionNames indicates the names to serve this CustomResourceDefinition - -Type:: - `object` - -Required:: - - `plural` - - `kind` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `categories` -| `array (string)` -| categories is a list of grouped resources this custom resource belongs to (e.g. 'all'). This is published in API discovery documents, and used by clients to support invocations like `kubectl get all`. - -| `kind` -| `string` -| kind is the serialized kind of the resource. It is normally CamelCase and singular. Custom resource instances will use this value as the `kind` attribute in API calls. - -| `listKind` -| `string` -| listKind is the serialized kind of the list for this resource. Defaults to "`kind`List". - -| `plural` -| `string` -| plural is the plural name of the resource to serve. The custom resources are served under `/apis/<group>/<version>/.../<plural>`. Must match the name of the CustomResourceDefinition (in the form `<names.plural>.<group>`). Must be all lowercase. - -| `shortNames` -| `array (string)` -| shortNames are short names for the resource, exposed in API discovery documents, and used by clients to support invocations like `kubectl get <shortname>`. It must be all lowercase. - -| `singular` -| `string` -| singular is the singular name of the resource. It must be all lowercase. Defaults to lowercased `kind`. - -|=== -..status.conditions -Description:: - conditions indicate state for particular aspects of a CustomResourceDefinition - -Type:: - `array` - - - - -..status.conditions[] -Description:: - CustomResourceDefinitionCondition contains details for the current condition of this pod. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| lastTransitionTime last time the condition transitioned from one status to another. - -| `message` -| `string` -| message is a human-readable message indicating details about last transition. - -| `reason` -| `string` -| reason is a unique, one-word, CamelCase reason for the condition's last transition. - -| `status` -| `string` -| status is the status of the condition. Can be True, False, Unknown. - -| `type` -| `string` -| type is the type of the condition. Types include Established, NamesAccepted and Terminating. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/apiextensions.k8s.io/v1/customresourcedefinitions` -- `DELETE`: delete collection of CustomResourceDefinition -- `GET`: list or watch objects of kind CustomResourceDefinition -- `POST`: create a CustomResourceDefinition -* `/apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}` -- `DELETE`: delete a CustomResourceDefinition -- `GET`: read the specified CustomResourceDefinition -- `PATCH`: partially update the specified CustomResourceDefinition -- `PUT`: replace the specified CustomResourceDefinition -* `/apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}/status` -- `GET`: read status of the specified CustomResourceDefinition -- `PATCH`: partially update status of the specified CustomResourceDefinition -- `PUT`: replace status of the specified CustomResourceDefinition - - -=== /apis/apiextensions.k8s.io/v1/customresourcedefinitions - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#customresourcedefinitionlist-apiextensions-k8s-io-v1[`CustomResourceDefinitionList apiextensions.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 202 - Accepted -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CustomResourceDefinition -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CustomResourceDefinition -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified CustomResourceDefinition - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified CustomResourceDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`CustomResourceDefinition apiextensions.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/extension_apis/extension-apis-index.adoc b/rest_api/extension_apis/extension-apis-index.adoc deleted file mode 100644 index 6a0ec6bb85b8..000000000000 --- a/rest_api/extension_apis/extension-apis-index.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="extension-apis"] -= Extension APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== APIService [apiregistration.k8s.io/v1] - -Description:: - APIService represents a server for a particular GroupVersion. Name must be "version.group". - -Type:: - `object` - -== CustomResourceDefinition [apiextensions.k8s.io/v1] - -Description:: - CustomResourceDefinition represents a resource that should be exposed on the API server. Its name MUST be in the format <.spec.name>.<.spec.group>. - -Type:: - `object` - -== MutatingWebhookConfiguration [admissionregistration.k8s.io/v1] - -Description:: - MutatingWebhookConfiguration describes the configuration of and admission webhook that accept or reject and may change the object. - -Type:: - `object` - -== ValidatingWebhookConfiguration [admissionregistration.k8s.io/v1] - -Description:: - ValidatingWebhookConfiguration describes the configuration of and admission webhook that accept or reject and object without changing it. - -Type:: - `object` - diff --git a/rest_api/extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc b/rest_api/extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc deleted file mode 100644 index d408114e1b20..000000000000 --- a/rest_api/extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc +++ /dev/null @@ -1,667 +0,0 @@ -[id="mutatingwebhookconfiguration-admissionregistration-k8s-io-v1"] -= MutatingWebhookConfiguration [admissionregistration.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - MutatingWebhookConfiguration describes the configuration of and admission webhook that accept or reject and may change the object. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object metadata; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata. - -| `webhooks` -| `array` -| Webhooks is a list of webhooks and the affected resources and operations. - -| `webhooks[]` -| `object` -| MutatingWebhook describes an admission webhook and the resources and operations it applies to. - -|=== -..webhooks -Description:: - Webhooks is a list of webhooks and the affected resources and operations. - -Type:: - `array` - - - - -..webhooks[] -Description:: - MutatingWebhook describes an admission webhook and the resources and operations it applies to. - -Type:: - `object` - -Required:: - - `name` - - `clientConfig` - - `sideEffects` - - `admissionReviewVersions` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `admissionReviewVersions` -| `array (string)` -| AdmissionReviewVersions is an ordered list of preferred `AdmissionReview` versions the Webhook expects. API server will try to use first version in the list which it supports. If none of the versions specified in this list supported by API server, validation will fail for this object. If a persisted webhook configuration specifies allowed versions and does not include any versions known to the API Server, calls to the webhook will fail and be subject to the failure policy. - -| `clientConfig` -| `object` -| WebhookClientConfig contains the information to make a TLS connection with the webhook - -| `failurePolicy` -| `string` -| FailurePolicy defines how unrecognized errors from the admission endpoint are handled - allowed values are Ignore or Fail. Defaults to Fail. - -| `matchPolicy` -| `string` -| matchPolicy defines how the "rules" list is used to match incoming requests. Allowed values are "Exact" or "Equivalent". - -- Exact: match a request only if it exactly matches a specified rule. For example, if deployments can be modified via apps/v1, apps/v1beta1, and extensions/v1beta1, but "rules" only included `apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]`, a request to apps/v1beta1 or extensions/v1beta1 would not be sent to the webhook. - -- Equivalent: match a request if modifies a resource listed in rules, even via another API group or version. For example, if deployments can be modified via apps/v1, apps/v1beta1, and extensions/v1beta1, and "rules" only included `apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]`, a request to apps/v1beta1 or extensions/v1beta1 would be converted to apps/v1 and sent to the webhook. - -Defaults to "Equivalent" - -| `name` -| `string` -| The name of the admission webhook. Name should be fully qualified, e.g., imagepolicy.kubernetes.io, where "imagepolicy" is the name of the webhook, and kubernetes.io is the name of the organization. Required. - -| `namespaceSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| NamespaceSelector decides whether to run the webhook on an object based on whether the namespace for that object matches the selector. If the object itself is a namespace, the matching is performed on object.metadata.labels. If the object is another cluster scoped resource, it never skips the webhook. - -For example, to run the webhook on any objects whose namespace is not associated with "runlevel" of "0" or "1"; you will set the selector as follows: "namespaceSelector": { - "matchExpressions": [ - { - "key": "runlevel", - "operator": "NotIn", - "values": [ - "0", - "1" - ] - } - ] -} - -If instead you want to only run the webhook on any objects whose namespace is associated with the "environment" of "prod" or "staging"; you will set the selector as follows: "namespaceSelector": { - "matchExpressions": [ - { - "key": "environment", - "operator": "In", - "values": [ - "prod", - "staging" - ] - } - ] -} - -See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more examples of label selectors. - -Default to the empty LabelSelector, which matches everything. - -| `objectSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| ObjectSelector decides whether to run the webhook based on if the object has matching labels. objectSelector is evaluated against both the oldObject and newObject that would be sent to the webhook, and is considered to match if either object matches the selector. A null object (oldObject in the case of create, or newObject in the case of delete) or an object that cannot have labels (like a DeploymentRollback or a PodProxyOptions object) is not considered to match. Use the object selector only if the webhook is opt-in, because end users may skip the admission webhook by setting the labels. Default to the empty LabelSelector, which matches everything. - -| `reinvocationPolicy` -| `string` -| reinvocationPolicy indicates whether this webhook should be called multiple times as part of a single admission evaluation. Allowed values are "Never" and "IfNeeded". - -Never: the webhook will not be called more than once in a single admission evaluation. - -IfNeeded: the webhook will be called at least one additional time as part of the admission evaluation if the object being admitted is modified by other admission plugins after the initial webhook call. Webhooks that specify this option *must* be idempotent, able to process objects they previously admitted. Note: * the number of additional invocations is not guaranteed to be exactly one. * if additional invocations result in further modifications to the object, webhooks are not guaranteed to be invoked again. * webhooks that use this option may be reordered to minimize the number of additional invocations. * to validate an object after all mutations are guaranteed complete, use a validating admission webhook instead. - -Defaults to "Never". - -| `rules` -| `array` -| Rules describes what operations on what resources/subresources the webhook cares about. The webhook cares about an operation if it matches _any_ Rule. However, in order to prevent ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks from putting the cluster in a state which cannot be recovered from without completely disabling the plugin, ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks are never called on admission requests for ValidatingWebhookConfiguration and MutatingWebhookConfiguration objects. - -| `rules[]` -| `object` -| RuleWithOperations is a tuple of Operations and Resources. It is recommended to make sure that all the tuple expansions are valid. - -| `sideEffects` -| `string` -| SideEffects states whether this webhook has side effects. Acceptable values are: None, NoneOnDryRun (webhooks created via v1beta1 may also specify Some or Unknown). Webhooks with side effects MUST implement a reconciliation system, since a request may be rejected by a future step in the admission change and the side effects therefore need to be undone. Requests with the dryRun attribute will be auto-rejected if they match a webhook with sideEffects == Unknown or Some. - -| `timeoutSeconds` -| `integer` -| TimeoutSeconds specifies the timeout for this webhook. After the timeout passes, the webhook call will be ignored or the API call will fail based on the failure policy. The timeout value must be between 1 and 30 seconds. Default to 10 seconds. - -|=== -..webhooks[].clientConfig -Description:: - WebhookClientConfig contains the information to make a TLS connection with the webhook - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `caBundle` -| `string` -| `caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. - -| `service` -| `object` -| ServiceReference holds a reference to Service.legacy.k8s.io - -| `url` -| `string` -| `url` gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. - -The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. - -Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installs are likely to be non-portable, i.e., not easy to turn up in a new cluster. - -The scheme must be "https"; the URL must begin with "https://". - -A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. - -Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. - -|=== -..webhooks[].clientConfig.service -Description:: - ServiceReference holds a reference to Service.legacy.k8s.io - -Type:: - `object` - -Required:: - - `namespace` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| `name` is the name of the service. Required - -| `namespace` -| `string` -| `namespace` is the namespace of the service. Required - -| `path` -| `string` -| `path` is an optional URL path which will be sent in any request to this service. - -| `port` -| `integer` -| If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. `port` should be a valid port number (1-65535, inclusive). - -|=== -..webhooks[].rules -Description:: - Rules describes what operations on what resources/subresources the webhook cares about. The webhook cares about an operation if it matches _any_ Rule. However, in order to prevent ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks from putting the cluster in a state which cannot be recovered from without completely disabling the plugin, ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks are never called on admission requests for ValidatingWebhookConfiguration and MutatingWebhookConfiguration objects. - -Type:: - `array` - - - - -..webhooks[].rules[] -Description:: - RuleWithOperations is a tuple of Operations and Resources. It is recommended to make sure that all the tuple expansions are valid. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the API groups the resources belong to. '*' is all groups. If '*' is present, the length of the slice must be one. Required. - -| `apiVersions` -| `array (string)` -| APIVersions is the API versions the resources belong to. '*' is all versions. If '*' is present, the length of the slice must be one. Required. - -| `operations` -| `array (string)` -| Operations is the operations the admission hook cares about - CREATE, UPDATE, DELETE, CONNECT or * for all of those operations and any future admission operations that are added. If '*' is present, the length of the slice must be one. Required. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. - -For example: 'pods' means pods. 'pods/log' means the log subresource of pods. '*' means all resources, but not subresources. 'pods/*' means all subresources of pods. '*/scale' means all scale subresources. '*/*' means all resources and their subresources. - -If wildcard is present, the validation rule will ensure resources do not overlap with each other. - -Depending on the enclosing object, subresources might not be allowed. Required. - -| `scope` -| `string` -| scope specifies the scope of this rule. Valid values are "Cluster", "Namespaced", and "*" "Cluster" means that only cluster-scoped resources will match this rule. Namespace API objects are cluster-scoped. "Namespaced" means that only namespaced resources will match this rule. "*" means that there are no scope restrictions. Subresources match the scope of their parent resource. Default is "*". - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations` -- `DELETE`: delete collection of MutatingWebhookConfiguration -- `GET`: list or watch objects of kind MutatingWebhookConfiguration -- `POST`: create a MutatingWebhookConfiguration -* `/apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}` -- `DELETE`: delete a MutatingWebhookConfiguration -- `GET`: read the specified MutatingWebhookConfiguration -- `PATCH`: partially update the specified MutatingWebhookConfiguration -- `PUT`: replace the specified MutatingWebhookConfiguration - - -=== /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of MutatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind MutatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#mutatingwebhookconfigurationlist-admissionregistration-k8s-io-v1[`MutatingWebhookConfigurationList admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a MutatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 202 - Accepted -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MutatingWebhookConfiguration -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a MutatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified MutatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified MutatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified MutatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`MutatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc b/rest_api/extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc deleted file mode 100644 index a21ed260ef96..000000000000 --- a/rest_api/extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc +++ /dev/null @@ -1,657 +0,0 @@ -[id="validatingwebhookconfiguration-admissionregistration-k8s-io-v1"] -= ValidatingWebhookConfiguration [admissionregistration.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ValidatingWebhookConfiguration describes the configuration of and admission webhook that accept or reject and object without changing it. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object metadata; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata. - -| `webhooks` -| `array` -| Webhooks is a list of webhooks and the affected resources and operations. - -| `webhooks[]` -| `object` -| ValidatingWebhook describes an admission webhook and the resources and operations it applies to. - -|=== -..webhooks -Description:: - Webhooks is a list of webhooks and the affected resources and operations. - -Type:: - `array` - - - - -..webhooks[] -Description:: - ValidatingWebhook describes an admission webhook and the resources and operations it applies to. - -Type:: - `object` - -Required:: - - `name` - - `clientConfig` - - `sideEffects` - - `admissionReviewVersions` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `admissionReviewVersions` -| `array (string)` -| AdmissionReviewVersions is an ordered list of preferred `AdmissionReview` versions the Webhook expects. API server will try to use first version in the list which it supports. If none of the versions specified in this list supported by API server, validation will fail for this object. If a persisted webhook configuration specifies allowed versions and does not include any versions known to the API Server, calls to the webhook will fail and be subject to the failure policy. - -| `clientConfig` -| `object` -| WebhookClientConfig contains the information to make a TLS connection with the webhook - -| `failurePolicy` -| `string` -| FailurePolicy defines how unrecognized errors from the admission endpoint are handled - allowed values are Ignore or Fail. Defaults to Fail. - -| `matchPolicy` -| `string` -| matchPolicy defines how the "rules" list is used to match incoming requests. Allowed values are "Exact" or "Equivalent". - -- Exact: match a request only if it exactly matches a specified rule. For example, if deployments can be modified via apps/v1, apps/v1beta1, and extensions/v1beta1, but "rules" only included `apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]`, a request to apps/v1beta1 or extensions/v1beta1 would not be sent to the webhook. - -- Equivalent: match a request if modifies a resource listed in rules, even via another API group or version. For example, if deployments can be modified via apps/v1, apps/v1beta1, and extensions/v1beta1, and "rules" only included `apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"]`, a request to apps/v1beta1 or extensions/v1beta1 would be converted to apps/v1 and sent to the webhook. - -Defaults to "Equivalent" - -| `name` -| `string` -| The name of the admission webhook. Name should be fully qualified, e.g., imagepolicy.kubernetes.io, where "imagepolicy" is the name of the webhook, and kubernetes.io is the name of the organization. Required. - -| `namespaceSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| NamespaceSelector decides whether to run the webhook on an object based on whether the namespace for that object matches the selector. If the object itself is a namespace, the matching is performed on object.metadata.labels. If the object is another cluster scoped resource, it never skips the webhook. - -For example, to run the webhook on any objects whose namespace is not associated with "runlevel" of "0" or "1"; you will set the selector as follows: "namespaceSelector": { - "matchExpressions": [ - { - "key": "runlevel", - "operator": "NotIn", - "values": [ - "0", - "1" - ] - } - ] -} - -If instead you want to only run the webhook on any objects whose namespace is associated with the "environment" of "prod" or "staging"; you will set the selector as follows: "namespaceSelector": { - "matchExpressions": [ - { - "key": "environment", - "operator": "In", - "values": [ - "prod", - "staging" - ] - } - ] -} - -See https://kubernetes.io/docs/concepts/overview/working-with-objects/labels for more examples of label selectors. - -Default to the empty LabelSelector, which matches everything. - -| `objectSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| ObjectSelector decides whether to run the webhook based on if the object has matching labels. objectSelector is evaluated against both the oldObject and newObject that would be sent to the webhook, and is considered to match if either object matches the selector. A null object (oldObject in the case of create, or newObject in the case of delete) or an object that cannot have labels (like a DeploymentRollback or a PodProxyOptions object) is not considered to match. Use the object selector only if the webhook is opt-in, because end users may skip the admission webhook by setting the labels. Default to the empty LabelSelector, which matches everything. - -| `rules` -| `array` -| Rules describes what operations on what resources/subresources the webhook cares about. The webhook cares about an operation if it matches _any_ Rule. However, in order to prevent ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks from putting the cluster in a state which cannot be recovered from without completely disabling the plugin, ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks are never called on admission requests for ValidatingWebhookConfiguration and MutatingWebhookConfiguration objects. - -| `rules[]` -| `object` -| RuleWithOperations is a tuple of Operations and Resources. It is recommended to make sure that all the tuple expansions are valid. - -| `sideEffects` -| `string` -| SideEffects states whether this webhook has side effects. Acceptable values are: None, NoneOnDryRun (webhooks created via v1beta1 may also specify Some or Unknown). Webhooks with side effects MUST implement a reconciliation system, since a request may be rejected by a future step in the admission change and the side effects therefore need to be undone. Requests with the dryRun attribute will be auto-rejected if they match a webhook with sideEffects == Unknown or Some. - -| `timeoutSeconds` -| `integer` -| TimeoutSeconds specifies the timeout for this webhook. After the timeout passes, the webhook call will be ignored or the API call will fail based on the failure policy. The timeout value must be between 1 and 30 seconds. Default to 10 seconds. - -|=== -..webhooks[].clientConfig -Description:: - WebhookClientConfig contains the information to make a TLS connection with the webhook - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `caBundle` -| `string` -| `caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used. - -| `service` -| `object` -| ServiceReference holds a reference to Service.legacy.k8s.io - -| `url` -| `string` -| `url` gives the location of the webhook, in standard URL form (`scheme://host:port/path`). Exactly one of `url` or `service` must be specified. - -The `host` should not refer to a service running in the cluster; use the `service` field instead. The host might be resolved via external DNS in some apiservers (e.g., `kube-apiserver` cannot resolve in-cluster DNS as that would be a layering violation). `host` may also be an IP address. - -Please note that using `localhost` or `127.0.0.1` as a `host` is risky unless you take great care to run this webhook on all hosts which run an apiserver which might need to make calls to this webhook. Such installs are likely to be non-portable, i.e., not easy to turn up in a new cluster. - -The scheme must be "https"; the URL must begin with "https://". - -A path is optional, and if present may be any string permissible in a URL. You may use the path to pass an arbitrary string to the webhook, for example, a cluster identifier. - -Attempting to use a user or basic auth e.g. "user:password@" is not allowed. Fragments ("#...") and query parameters ("?...") are not allowed, either. - -|=== -..webhooks[].clientConfig.service -Description:: - ServiceReference holds a reference to Service.legacy.k8s.io - -Type:: - `object` - -Required:: - - `namespace` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| `name` is the name of the service. Required - -| `namespace` -| `string` -| `namespace` is the namespace of the service. Required - -| `path` -| `string` -| `path` is an optional URL path which will be sent in any request to this service. - -| `port` -| `integer` -| If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. `port` should be a valid port number (1-65535, inclusive). - -|=== -..webhooks[].rules -Description:: - Rules describes what operations on what resources/subresources the webhook cares about. The webhook cares about an operation if it matches _any_ Rule. However, in order to prevent ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks from putting the cluster in a state which cannot be recovered from without completely disabling the plugin, ValidatingAdmissionWebhooks and MutatingAdmissionWebhooks are never called on admission requests for ValidatingWebhookConfiguration and MutatingWebhookConfiguration objects. - -Type:: - `array` - - - - -..webhooks[].rules[] -Description:: - RuleWithOperations is a tuple of Operations and Resources. It is recommended to make sure that all the tuple expansions are valid. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the API groups the resources belong to. '*' is all groups. If '*' is present, the length of the slice must be one. Required. - -| `apiVersions` -| `array (string)` -| APIVersions is the API versions the resources belong to. '*' is all versions. If '*' is present, the length of the slice must be one. Required. - -| `operations` -| `array (string)` -| Operations is the operations the admission hook cares about - CREATE, UPDATE, DELETE, CONNECT or * for all of those operations and any future admission operations that are added. If '*' is present, the length of the slice must be one. Required. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. - -For example: 'pods' means pods. 'pods/log' means the log subresource of pods. '*' means all resources, but not subresources. 'pods/*' means all subresources of pods. '*/scale' means all scale subresources. '*/*' means all resources and their subresources. - -If wildcard is present, the validation rule will ensure resources do not overlap with each other. - -Depending on the enclosing object, subresources might not be allowed. Required. - -| `scope` -| `string` -| scope specifies the scope of this rule. Valid values are "Cluster", "Namespaced", and "*" "Cluster" means that only cluster-scoped resources will match this rule. Namespace API objects are cluster-scoped. "Namespaced" means that only namespaced resources will match this rule. "*" means that there are no scope restrictions. Subresources match the scope of their parent resource. Default is "*". - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations` -- `DELETE`: delete collection of ValidatingWebhookConfiguration -- `GET`: list or watch objects of kind ValidatingWebhookConfiguration -- `POST`: create a ValidatingWebhookConfiguration -* `/apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name}` -- `DELETE`: delete a ValidatingWebhookConfiguration -- `GET`: read the specified ValidatingWebhookConfiguration -- `PATCH`: partially update the specified ValidatingWebhookConfiguration -- `PUT`: replace the specified ValidatingWebhookConfiguration - - -=== /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ValidatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ValidatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#validatingwebhookconfigurationlist-admissionregistration-k8s-io-v1[`ValidatingWebhookConfigurationList admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ValidatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 202 - Accepted -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ValidatingWebhookConfiguration -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ValidatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ValidatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ValidatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ValidatingWebhookConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 201 - Created -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`ValidatingWebhookConfiguration admissionregistration.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/image_apis/image-apis-index.adoc b/rest_api/image_apis/image-apis-index.adoc deleted file mode 100644 index da2ba0ba521f..000000000000 --- a/rest_api/image_apis/image-apis-index.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[id="image-apis"] -= Image APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== Image [image.openshift.io/v1] - -Description:: - Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -Type:: - `object` - -== ImageSignature [image.openshift.io/v1] - -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -== ImageStreamImage [image.openshift.io/v1] - -Description:: - ImageStreamImage represents an Image that is retrieved by image name from an ImageStream. User interfaces and regular users can use this resource to access the metadata details of a tagged image in the image stream history for viewing, since Image resources are not directly accessible to end users. A not found error will be returned if no such image is referenced by a tag within the ImageStream. Images are created when spec tags are set on an image stream that represent an image in an external registry, when pushing to the integrated registry, or when tagging an existing image from one image stream to another. The name of an image stream image is in the form "<STREAM>@<DIGEST>", where the digest is the content addressible identifier for the image (sha256:xxxxx...). You can use ImageStreamImages as the from.kind of an image stream spec tag to reference an image exactly. The only operations supported on the imagestreamimage endpoint are retrieving the image. - -Type:: - `object` - -== ImageStreamImport [image.openshift.io/v1] - -Description:: - The image stream import resource provides an easy way for a user to find and import container images from other container image registries into the server. Individual images or an entire image repository may be imported, and users may choose to see the results of the import prior to tagging the resulting images into the specified image stream. - -This API is intended for end-user tools that need to see the metadata of the image prior to import (for instance, to generate an application from it). Clients that know the desired image can continue to create spec.tags directly into their image streams. - -Type:: - `object` - -== ImageStreamMapping [image.openshift.io/v1] - -Description:: - ImageStreamMapping represents a mapping from a single image stream tag to a container image as well as the reference to the container image stream the image came from. This resource is used by privileged integrators to create an image resource and to associate it with an image stream in the status tags field. Creating an ImageStreamMapping will allow any user who can view the image stream to tag or pull that image, so only create mappings where the user has proven they have access to the image contents directly. The only operation supported for this resource is create and the metadata name and namespace should be set to the image stream containing the tag that should be updated. - -Type:: - `object` - -== ImageStream [image.openshift.io/v1] - -Description:: - An ImageStream stores a mapping of tags to images, metadata overrides that are applied when images are tagged in a stream, and an optional reference to a container image repository on a registry. Users typically update the spec.tags field to point to external images which are imported from container registries using credentials in your namespace with the pull secret type, or to existing image stream tags and images which are immediately accessible for tagging or pulling. The history of images applied to a tag is visible in the status.tags field and any user who can view an image stream is allowed to tag that image into their own image streams. Access to pull images from the integrated registry is granted by having the "get imagestreams/layers" permission on a given image stream. Users may remove a tag by deleting the imagestreamtag resource, which causes both spec and status for that tag to be removed. Image stream history is retained until an administrator runs the prune operation, which removes references that are no longer in use. To preserve a historical image, ensure there is a tag in spec pointing to that image by its digest. - -Type:: - `object` - -== ImageStreamTag [image.openshift.io/v1] - -Description:: - ImageStreamTag represents an Image that is retrieved by tag name from an ImageStream. Use this resource to interact with the tags and images in an image stream by tag, or to see the image details for a particular tag. The image associated with this resource is the most recently successfully tagged, imported, or pushed image (as described in the image stream status.tags.items list for this tag). If an import is in progress or has failed the previous image will be shown. Deleting an image stream tag clears both the status and spec fields of an image stream. If no image can be retrieved for a given tag, a not found error will be returned. - -Type:: - `object` - -== ImageTag [image.openshift.io/v1] - -Description:: - ImageTag represents a single tag within an image stream and includes the spec, the status history, and the currently referenced image (if any) of the provided tag. This type replaces the ImageStreamTag by providing a full view of the tag. ImageTags are returned for every spec or status tag present on the image stream. If no tag exists in either form a not found error will be returned by the API. A create operation will succeed if no spec tag has already been defined and the spec field is set. Delete will remove both spec and status elements from the image stream. - -Type:: - `object` - diff --git a/rest_api/image_apis/image-image-openshift-io-v1.adoc b/rest_api/image_apis/image-image-openshift-io-v1.adoc deleted file mode 100644 index 660bedfabd5c..000000000000 --- a/rest_api/image_apis/image-image-openshift-io-v1.adoc +++ /dev/null @@ -1,684 +0,0 @@ -[id="image-image-openshift-io-v1"] -= Image [image.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -Type:: - `object` - -Required:: - - `dockerImageLayers` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dockerImageConfig` -| `string` -| DockerImageConfig is a JSON blob that the runtime uses to set up the container. This is a part of manifest schema v2. - -| `dockerImageLayers` -| `array` -| DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -| `dockerImageLayers[]` -| `object` -| ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -| `dockerImageManifest` -| `string` -| DockerImageManifest is the raw JSON of the manifest - -| `dockerImageManifestMediaType` -| `string` -| DockerImageManifestMediaType specifies the mediaType of manifest. This is a part of manifest schema v2. - -| `dockerImageMetadata` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| DockerImageMetadata contains metadata about this image - -| `dockerImageMetadataVersion` -| `string` -| DockerImageMetadataVersion conveys the version of the object, which if empty defaults to "1.0" - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image. - -| `dockerImageSignatures` -| `array (string)` -| DockerImageSignatures provides the signatures as opaque blobs. This is a part of manifest schema v1. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signatures` -| `array` -| Signatures holds all signatures of the image. - -| `signatures[]` -| `object` -| ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -|=== -..dockerImageLayers -Description:: - DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -Type:: - `array` - - - - -..dockerImageLayers[] -Description:: - ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -Type:: - `object` - -Required:: - - `name` - - `size` - - `mediaType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mediaType` -| `string` -| MediaType of the referenced object. - -| `name` -| `string` -| Name of the layer as defined by the underlying store. - -| `size` -| `integer` -| Size of the layer in bytes as defined by the underlying store. - -|=== -..signatures -Description:: - Signatures holds all signatures of the image. - -Type:: - `array` - - - - -..signatures[] -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -Required:: - - `type` - - `content` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| Conditions represent the latest available observations of a signature's current state. - -| `conditions[]` -| `object` -| SignatureCondition describes an image signature condition of particular kind at particular probe time. - -| `content` -| `string` -| Required: An opaque binary string which is an image's signature. - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| If specified, it is the time of signature's creation. - -| `imageIdentity` -| `string` -| A human readable string representing image's identity. It could be a product name and version, or an image pull spec (e.g. "registry.access.redhat.com/rhel7/rhel:7.2"). - -| `issuedBy` -| `object` -| SignatureIssuer holds information about an issuer of signing certificate or key. - -| `issuedTo` -| `object` -| SignatureSubject holds information about a person or entity who created the signature. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signedClaims` -| `object (string)` -| Contains claims from the signature. - -| `type` -| `string` -| Required: Describes a type of stored blob. - -|=== -..signatures[].conditions -Description:: - Conditions represent the latest available observations of a signature's current state. - -Type:: - `array` - - - - -..signatures[].conditions[] -Description:: - SignatureCondition describes an image signature condition of particular kind at particular probe time. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of signature condition, Complete or Failed. - -|=== -..signatures[].issuedBy -Description:: - SignatureIssuer holds information about an issuer of signing certificate or key. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -|=== -..signatures[].issuedTo -Description:: - SignatureSubject holds information about a person or entity who created the signature. - -Type:: - `object` - -Required:: - - `publicKeyID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -| `publicKeyID` -| `string` -| If present, it is a human readable key id of public key belonging to the subject used to verify image signature. It should contain at least 64 lowest bits of public key's fingerprint (e.g. 0x685ebe62bf278440). - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/image.openshift.io/v1/images` -- `DELETE`: delete collection of Image -- `GET`: list or watch objects of kind Image -- `POST`: create an Image -* `/apis/image.openshift.io/v1/images/{name}` -- `DELETE`: delete an Image -- `GET`: read the specified Image -- `PATCH`: partially update the specified Image -- `PUT`: replace the specified Image - - -=== /apis/image.openshift.io/v1/images - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagelist-image-openshift-io-v1[`ImageList image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| 202 - Accepted -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/images/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Image -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Image - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`Image image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/image_apis/imagesignature-image-openshift-io-v1.adoc b/rest_api/image_apis/imagesignature-image-openshift-io-v1.adoc deleted file mode 100644 index 08e77bf11ef6..000000000000 --- a/rest_api/image_apis/imagesignature-image-openshift-io-v1.adoc +++ /dev/null @@ -1,302 +0,0 @@ -[id="imagesignature-image-openshift-io-v1"] -= ImageSignature [image.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -Required:: - - `type` - - `content` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| Conditions represent the latest available observations of a signature's current state. - -| `conditions[]` -| `object` -| SignatureCondition describes an image signature condition of particular kind at particular probe time. - -| `content` -| `string` -| Required: An opaque binary string which is an image's signature. - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| If specified, it is the time of signature's creation. - -| `imageIdentity` -| `string` -| A human readable string representing image's identity. It could be a product name and version, or an image pull spec (e.g. "registry.access.redhat.com/rhel7/rhel:7.2"). - -| `issuedBy` -| `object` -| SignatureIssuer holds information about an issuer of signing certificate or key. - -| `issuedTo` -| `object` -| SignatureSubject holds information about a person or entity who created the signature. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signedClaims` -| `object (string)` -| Contains claims from the signature. - -| `type` -| `string` -| Required: Describes a type of stored blob. - -|=== -..conditions -Description:: - Conditions represent the latest available observations of a signature's current state. - -Type:: - `array` - - - - -..conditions[] -Description:: - SignatureCondition describes an image signature condition of particular kind at particular probe time. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of signature condition, Complete or Failed. - -|=== -..issuedBy -Description:: - SignatureIssuer holds information about an issuer of signing certificate or key. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -|=== -..issuedTo -Description:: - SignatureSubject holds information about a person or entity who created the signature. - -Type:: - `object` - -Required:: - - `publicKeyID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -| `publicKeyID` -| `string` -| If present, it is a human readable key id of public key belonging to the subject used to verify image signature. It should contain at least 64 lowest bits of public key's fingerprint (e.g. 0x685ebe62bf278440). - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/image.openshift.io/v1/imagesignatures` -- `POST`: create an ImageSignature -* `/apis/image.openshift.io/v1/imagesignatures/{name}` -- `DELETE`: delete an ImageSignature - - -=== /apis/image.openshift.io/v1/imagesignatures - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create an ImageSignature - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagesignature-image-openshift-io-v1.adoc#imagesignature-image-openshift-io-v1[`ImageSignature image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagesignature-image-openshift-io-v1.adoc#imagesignature-image-openshift-io-v1[`ImageSignature image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagesignature-image-openshift-io-v1.adoc#imagesignature-image-openshift-io-v1[`ImageSignature image.openshift.io/v1`] -| 202 - Accepted -| xref:../image_apis/imagesignature-image-openshift-io-v1.adoc#imagesignature-image-openshift-io-v1[`ImageSignature image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/imagesignatures/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageSignature -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an ImageSignature - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/image_apis/imagestream-image-openshift-io-v1.adoc b/rest_api/image_apis/imagestream-image-openshift-io-v1.adoc deleted file mode 100644 index 88961f773259..000000000000 --- a/rest_api/image_apis/imagestream-image-openshift-io-v1.adoc +++ /dev/null @@ -1,1081 +0,0 @@ -[id="imagestream-image-openshift-io-v1"] -= ImageStream [image.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - An ImageStream stores a mapping of tags to images, metadata overrides that are applied when images are tagged in a stream, and an optional reference to a container image repository on a registry. Users typically update the spec.tags field to point to external images which are imported from container registries using credentials in your namespace with the pull secret type, or to existing image stream tags and images which are immediately accessible for tagging or pulling. The history of images applied to a tag is visible in the status.tags field and any user who can view an image stream is allowed to tag that image into their own image streams. Access to pull images from the integrated registry is granted by having the "get imagestreams/layers" permission on a given image stream. Users may remove a tag by deleting the imagestreamtag resource, which causes both spec and status for that tag to be removed. Image stream history is retained until an administrator runs the prune operation, which removes references that are no longer in use. To preserve a historical image, ensure there is a tag in spec pointing to that image by its digest. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| ImageStreamSpec represents options for ImageStreams. - -| `status` -| `object` -| ImageStreamStatus contains information about the state of this image stream. - -|=== -..spec -Description:: - ImageStreamSpec represents options for ImageStreams. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `dockerImageRepository` -| `string` -| dockerImageRepository is optional, if specified this stream is backed by a container repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead. - -| `lookupPolicy` -| `object` -| ImageLookupPolicy describes how an image stream can be used to override the image references used by pods, builds, and other resources in a namespace. - -| `tags` -| `array` -| tags map arbitrary string values to specific image locators - -| `tags[]` -| `object` -| TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track. - -|=== -..spec.lookupPolicy -Description:: - ImageLookupPolicy describes how an image stream can be used to override the image references used by pods, builds, and other resources in a namespace. - -Type:: - `object` - -Required:: - - `local` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `local` -| `boolean` -| local will change the docker short image references (like "mysql" or "php:latest") on objects in this namespace to the image ID whenever they match this image stream, instead of reaching out to a remote registry. The name will be fully qualified to an image ID if found. The tag's referencePolicy is taken into account on the replaced value. Only works within the current namespace. - -|=== -..spec.tags -Description:: - tags map arbitrary string values to specific image locators - -Type:: - `array` - - - - -..spec.tags[] -Description:: - TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage. ImageStreamTag references can only reference a tag within this same ImageStream. - -| `generation` -| `integer` -| Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation. - -| `importPolicy` -| `object` -| TagImportPolicy controls how images related to this tag will be imported. - -| `name` -| `string` -| Name of the tag - -| `reference` -| `boolean` -| Reference states if the tag will be imported. Default value is false, which means the tag will be imported. - -| `referencePolicy` -| `object` -| TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -|=== -..spec.tags[].importPolicy -Description:: - TagImportPolicy controls how images related to this tag will be imported. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `insecure` -| `boolean` -| Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import. - -| `scheduled` -| `boolean` -| Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported - -|=== -..spec.tags[].referencePolicy -Description:: - TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `type` -| `string` -| Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated container image registry and leverage the registry's ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream's namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable. - -|=== -..status -Description:: - ImageStreamStatus contains information about the state of this image stream. - -Type:: - `object` - -Required:: - - `dockerImageRepository` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `dockerImageRepository` -| `string` -| DockerImageRepository represents the effective location this stream may be accessed at. May be empty until the server determines where the repository is located - -| `publicDockerImageRepository` -| `string` -| PublicDockerImageRepository represents the public location from where the image can be pulled outside the cluster. This field may be empty if the administrator has not exposed the integrated registry externally. - -| `tags` -| `array` -| Tags are a historical record of images associated with each tag. The first entry in the TagEvent array is the currently tagged image. - -| `tags[]` -| `object` -| NamedTagEventList relates a tag to its image history. - -|=== -..status.tags -Description:: - Tags are a historical record of images associated with each tag. The first entry in the TagEvent array is the currently tagged image. - -Type:: - `array` - - - - -..status.tags[] -Description:: - NamedTagEventList relates a tag to its image history. - -Type:: - `object` - -Required:: - - `tag` - - `items` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| Conditions is an array of conditions that apply to the tag event list. - -| `conditions[]` -| `object` -| TagEventCondition contains condition information for a tag event. - -| `items` -| `array` -| Standard object's metadata. - -| `items[]` -| `object` -| TagEvent is used by ImageStreamStatus to keep a historical record of images associated with a tag. - -| `tag` -| `string` -| Tag is the tag for which the history is recorded - -|=== -..status.tags[].conditions -Description:: - Conditions is an array of conditions that apply to the tag event list. - -Type:: - `array` - - - - -..status.tags[].conditions[] -Description:: - TagEventCondition contains condition information for a tag event. - -Type:: - `object` - -Required:: - - `type` - - `status` - - `generation` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `generation` -| `integer` -| Generation is the spec tag generation that this status corresponds to - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| LastTransitionTIme is the time the condition transitioned from one status to another. - -| `message` -| `string` -| Message is a human readable description of the details about last transition, complementing reason. - -| `reason` -| `string` -| Reason is a brief machine readable explanation for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of tag event condition, currently only ImportSuccess - -|=== -..status.tags[].items -Description:: - Standard object's metadata. - -Type:: - `array` - - - - -..status.tags[].items[] -Description:: - TagEvent is used by ImageStreamStatus to keep a historical record of images associated with a tag. - -Type:: - `object` - -Required:: - - `created` - - `dockerImageReference` - - `image` - - `generation` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Created holds the time the TagEvent was created - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image - -| `generation` -| `integer` -| Generation is the spec tag generation that resulted in this tag being updated - -| `image` -| `string` -| Image is the image - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/image.openshift.io/v1/imagestreams` -- `GET`: list or watch objects of kind ImageStream -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams` -- `DELETE`: delete collection of ImageStream -- `GET`: list or watch objects of kind ImageStream -- `POST`: create an ImageStream -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams/{name}` -- `DELETE`: delete an ImageStream -- `GET`: read the specified ImageStream -- `PATCH`: partially update the specified ImageStream -- `PUT`: replace the specified ImageStream -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams/{name}/layers` -- `GET`: read layers of the specified ImageStream -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams/{name}/status` -- `GET`: read status of the specified ImageStream -- `PATCH`: partially update status of the specified ImageStream -- `PUT`: replace status of the specified ImageStream -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams/{name}/secrets` -- `GET`: read secrets of the specified ImageStream - - -=== /apis/image.openshift.io/v1/imagestreams - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ImageStream - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagestreamlist-image-openshift-io-v1[`ImageStreamList image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagestreamlist-image-openshift-io-v1[`ImageStreamList image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 202 - Accepted -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageStream -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams/{name}/layers - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageStreamLayers -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read layers of the specified ImageStream - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagestreamlayers-image-openshift-io-v1[`ImageStreamLayers image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageStream -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ImageStream - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ImageStream - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`ImageStream image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreams/{name}/secrets - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the SecretList -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - read secrets of the specified ImageStream - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#secretlist-image-openshift-io-v1[`SecretList image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/image_apis/imagestreamimage-image-openshift-io-v1.adoc b/rest_api/image_apis/imagestreamimage-image-openshift-io-v1.adoc deleted file mode 100644 index 0ba7aead96f1..000000000000 --- a/rest_api/image_apis/imagestreamimage-image-openshift-io-v1.adoc +++ /dev/null @@ -1,386 +0,0 @@ -[id="imagestreamimage-image-openshift-io-v1"] -= ImageStreamImage [image.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ImageStreamImage represents an Image that is retrieved by image name from an ImageStream. User interfaces and regular users can use this resource to access the metadata details of a tagged image in the image stream history for viewing, since Image resources are not directly accessible to end users. A not found error will be returned if no such image is referenced by a tag within the ImageStream. Images are created when spec tags are set on an image stream that represent an image in an external registry, when pushing to the integrated registry, or when tagging an existing image from one image stream to another. The name of an image stream image is in the form "<STREAM>@<DIGEST>", where the digest is the content addressible identifier for the image (sha256:xxxxx...). You can use ImageStreamImages as the from.kind of an image stream spec tag to reference an image exactly. The only operations supported on the imagestreamimage endpoint are retrieving the image. - -Type:: - `object` - -Required:: - - `image` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `image` -| `object` -| Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -|=== -..image -Description:: - Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -Type:: - `object` - -Required:: - - `dockerImageLayers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dockerImageConfig` -| `string` -| DockerImageConfig is a JSON blob that the runtime uses to set up the container. This is a part of manifest schema v2. - -| `dockerImageLayers` -| `array` -| DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -| `dockerImageLayers[]` -| `object` -| ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -| `dockerImageManifest` -| `string` -| DockerImageManifest is the raw JSON of the manifest - -| `dockerImageManifestMediaType` -| `string` -| DockerImageManifestMediaType specifies the mediaType of manifest. This is a part of manifest schema v2. - -| `dockerImageMetadata` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| DockerImageMetadata contains metadata about this image - -| `dockerImageMetadataVersion` -| `string` -| DockerImageMetadataVersion conveys the version of the object, which if empty defaults to "1.0" - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image. - -| `dockerImageSignatures` -| `array (string)` -| DockerImageSignatures provides the signatures as opaque blobs. This is a part of manifest schema v1. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signatures` -| `array` -| Signatures holds all signatures of the image. - -| `signatures[]` -| `object` -| ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -|=== -..image.dockerImageLayers -Description:: - DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -Type:: - `array` - - - - -..image.dockerImageLayers[] -Description:: - ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -Type:: - `object` - -Required:: - - `name` - - `size` - - `mediaType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mediaType` -| `string` -| MediaType of the referenced object. - -| `name` -| `string` -| Name of the layer as defined by the underlying store. - -| `size` -| `integer` -| Size of the layer in bytes as defined by the underlying store. - -|=== -..image.signatures -Description:: - Signatures holds all signatures of the image. - -Type:: - `array` - - - - -..image.signatures[] -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -Required:: - - `type` - - `content` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| Conditions represent the latest available observations of a signature's current state. - -| `conditions[]` -| `object` -| SignatureCondition describes an image signature condition of particular kind at particular probe time. - -| `content` -| `string` -| Required: An opaque binary string which is an image's signature. - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| If specified, it is the time of signature's creation. - -| `imageIdentity` -| `string` -| A human readable string representing image's identity. It could be a product name and version, or an image pull spec (e.g. "registry.access.redhat.com/rhel7/rhel:7.2"). - -| `issuedBy` -| `object` -| SignatureIssuer holds information about an issuer of signing certificate or key. - -| `issuedTo` -| `object` -| SignatureSubject holds information about a person or entity who created the signature. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signedClaims` -| `object (string)` -| Contains claims from the signature. - -| `type` -| `string` -| Required: Describes a type of stored blob. - -|=== -..image.signatures[].conditions -Description:: - Conditions represent the latest available observations of a signature's current state. - -Type:: - `array` - - - - -..image.signatures[].conditions[] -Description:: - SignatureCondition describes an image signature condition of particular kind at particular probe time. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of signature condition, Complete or Failed. - -|=== -..image.signatures[].issuedBy -Description:: - SignatureIssuer holds information about an issuer of signing certificate or key. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -|=== -..image.signatures[].issuedTo -Description:: - SignatureSubject holds information about a person or entity who created the signature. - -Type:: - `object` - -Required:: - - `publicKeyID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -| `publicKeyID` -| `string` -| If present, it is a human readable key id of public key belonging to the subject used to verify image signature. It should contain at least 64 lowest bits of public key's fingerprint (e.g. 0x685ebe62bf278440). - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreamimages/{name}` -- `GET`: read the specified ImageStreamImage - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreamimages/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageStreamImage -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ImageStreamImage - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestreamimage-image-openshift-io-v1.adoc#imagestreamimage-image-openshift-io-v1[`ImageStreamImage image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/image_apis/imagestreamimport-image-openshift-io-v1.adoc b/rest_api/image_apis/imagestreamimport-image-openshift-io-v1.adoc deleted file mode 100644 index b3b7bcfb815f..000000000000 --- a/rest_api/image_apis/imagestreamimport-image-openshift-io-v1.adoc +++ /dev/null @@ -1,1411 +0,0 @@ -[id="imagestreamimport-image-openshift-io-v1"] -= ImageStreamImport [image.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - The image stream import resource provides an easy way for a user to find and import container images from other container image registries into the server. Individual images or an entire image repository may be imported, and users may choose to see the results of the import prior to tagging the resulting images into the specified image stream. - -This API is intended for end-user tools that need to see the metadata of the image prior to import (for instance, to generate an application from it). Clients that know the desired image can continue to create spec.tags directly into their image streams. - -Type:: - `object` - -Required:: - - `spec` - - `status` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| ImageStreamImportSpec defines what images should be imported. - -| `status` -| `object` -| ImageStreamImportStatus contains information about the status of an image stream import. - -|=== -..spec -Description:: - ImageStreamImportSpec defines what images should be imported. - -Type:: - `object` - -Required:: - - `import` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `images` -| `array` -| Images are a list of individual images to import. - -| `images[]` -| `object` -| ImageImportSpec describes a request to import a specific image. - -| `import` -| `boolean` -| Import indicates whether to perform an import - if so, the specified tags are set on the spec and status of the image stream defined by the type meta. - -| `repository` -| `object` -| RepositoryImportSpec describes a request to import images from a container image repository. - -|=== -..spec.images -Description:: - Images are a list of individual images to import. - -Type:: - `array` - - - - -..spec.images[] -Description:: - ImageImportSpec describes a request to import a specific image. - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| From is the source of an image to import; only kind DockerImage is allowed - -| `importPolicy` -| `object` -| TagImportPolicy controls how images related to this tag will be imported. - -| `includeManifest` -| `boolean` -| IncludeManifest determines if the manifest for each image is returned in the response - -| `referencePolicy` -| `object` -| TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -| `to` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| To is a tag in the current image stream to assign the imported image to, if name is not specified the default tag from from.name will be used - -|=== -..spec.images[].importPolicy -Description:: - TagImportPolicy controls how images related to this tag will be imported. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `insecure` -| `boolean` -| Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import. - -| `scheduled` -| `boolean` -| Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported - -|=== -..spec.images[].referencePolicy -Description:: - TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `type` -| `string` -| Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated container image registry and leverage the registry's ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream's namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable. - -|=== -..spec.repository -Description:: - RepositoryImportSpec describes a request to import images from a container image repository. - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| From is the source for the image repository to import; only kind DockerImage and a name of a container image repository is allowed - -| `importPolicy` -| `object` -| TagImportPolicy controls how images related to this tag will be imported. - -| `includeManifest` -| `boolean` -| IncludeManifest determines if the manifest for each image is returned in the response - -| `referencePolicy` -| `object` -| TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -|=== -..spec.repository.importPolicy -Description:: - TagImportPolicy controls how images related to this tag will be imported. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `insecure` -| `boolean` -| Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import. - -| `scheduled` -| `boolean` -| Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported - -|=== -..spec.repository.referencePolicy -Description:: - TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `type` -| `string` -| Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated container image registry and leverage the registry's ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream's namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable. - -|=== -..status -Description:: - ImageStreamImportStatus contains information about the status of an image stream import. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `images` -| `array` -| Images is set with the result of importing spec.images - -| `images[]` -| `object` -| ImageImportStatus describes the result of an image import. - -| `import` -| `object` -| An ImageStream stores a mapping of tags to images, metadata overrides that are applied when images are tagged in a stream, and an optional reference to a container image repository on a registry. Users typically update the spec.tags field to point to external images which are imported from container registries using credentials in your namespace with the pull secret type, or to existing image stream tags and images which are immediately accessible for tagging or pulling. The history of images applied to a tag is visible in the status.tags field and any user who can view an image stream is allowed to tag that image into their own image streams. Access to pull images from the integrated registry is granted by having the "get imagestreams/layers" permission on a given image stream. Users may remove a tag by deleting the imagestreamtag resource, which causes both spec and status for that tag to be removed. Image stream history is retained until an administrator runs the prune operation, which removes references that are no longer in use. To preserve a historical image, ensure there is a tag in spec pointing to that image by its digest. - -| `repository` -| `object` -| RepositoryImportStatus describes the result of an image repository import - -|=== -..status.images -Description:: - Images is set with the result of importing spec.images - -Type:: - `array` - - - - -..status.images[] -Description:: - ImageImportStatus describes the result of an image import. - -Type:: - `object` - -Required:: - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `image` -| `object` -| Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -| `status` -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| Status is the status of the image import, including errors encountered while retrieving the image - -| `tag` -| `string` -| Tag is the tag this image was located under, if any - -|=== -..status.images[].image -Description:: - Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -Type:: - `object` - -Required:: - - `dockerImageLayers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dockerImageConfig` -| `string` -| DockerImageConfig is a JSON blob that the runtime uses to set up the container. This is a part of manifest schema v2. - -| `dockerImageLayers` -| `array` -| DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -| `dockerImageLayers[]` -| `object` -| ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -| `dockerImageManifest` -| `string` -| DockerImageManifest is the raw JSON of the manifest - -| `dockerImageManifestMediaType` -| `string` -| DockerImageManifestMediaType specifies the mediaType of manifest. This is a part of manifest schema v2. - -| `dockerImageMetadata` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| DockerImageMetadata contains metadata about this image - -| `dockerImageMetadataVersion` -| `string` -| DockerImageMetadataVersion conveys the version of the object, which if empty defaults to "1.0" - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image. - -| `dockerImageSignatures` -| `array (string)` -| DockerImageSignatures provides the signatures as opaque blobs. This is a part of manifest schema v1. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signatures` -| `array` -| Signatures holds all signatures of the image. - -| `signatures[]` -| `object` -| ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -|=== -..status.images[].image.dockerImageLayers -Description:: - DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -Type:: - `array` - - - - -..status.images[].image.dockerImageLayers[] -Description:: - ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -Type:: - `object` - -Required:: - - `name` - - `size` - - `mediaType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mediaType` -| `string` -| MediaType of the referenced object. - -| `name` -| `string` -| Name of the layer as defined by the underlying store. - -| `size` -| `integer` -| Size of the layer in bytes as defined by the underlying store. - -|=== -..status.images[].image.signatures -Description:: - Signatures holds all signatures of the image. - -Type:: - `array` - - - - -..status.images[].image.signatures[] -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -Required:: - - `type` - - `content` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| Conditions represent the latest available observations of a signature's current state. - -| `conditions[]` -| `object` -| SignatureCondition describes an image signature condition of particular kind at particular probe time. - -| `content` -| `string` -| Required: An opaque binary string which is an image's signature. - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| If specified, it is the time of signature's creation. - -| `imageIdentity` -| `string` -| A human readable string representing image's identity. It could be a product name and version, or an image pull spec (e.g. "registry.access.redhat.com/rhel7/rhel:7.2"). - -| `issuedBy` -| `object` -| SignatureIssuer holds information about an issuer of signing certificate or key. - -| `issuedTo` -| `object` -| SignatureSubject holds information about a person or entity who created the signature. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signedClaims` -| `object (string)` -| Contains claims from the signature. - -| `type` -| `string` -| Required: Describes a type of stored blob. - -|=== -..status.images[].image.signatures[].conditions -Description:: - Conditions represent the latest available observations of a signature's current state. - -Type:: - `array` - - - - -..status.images[].image.signatures[].conditions[] -Description:: - SignatureCondition describes an image signature condition of particular kind at particular probe time. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of signature condition, Complete or Failed. - -|=== -..status.images[].image.signatures[].issuedBy -Description:: - SignatureIssuer holds information about an issuer of signing certificate or key. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -|=== -..status.images[].image.signatures[].issuedTo -Description:: - SignatureSubject holds information about a person or entity who created the signature. - -Type:: - `object` - -Required:: - - `publicKeyID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -| `publicKeyID` -| `string` -| If present, it is a human readable key id of public key belonging to the subject used to verify image signature. It should contain at least 64 lowest bits of public key's fingerprint (e.g. 0x685ebe62bf278440). - -|=== -..status.import -Description:: - An ImageStream stores a mapping of tags to images, metadata overrides that are applied when images are tagged in a stream, and an optional reference to a container image repository on a registry. Users typically update the spec.tags field to point to external images which are imported from container registries using credentials in your namespace with the pull secret type, or to existing image stream tags and images which are immediately accessible for tagging or pulling. The history of images applied to a tag is visible in the status.tags field and any user who can view an image stream is allowed to tag that image into their own image streams. Access to pull images from the integrated registry is granted by having the "get imagestreams/layers" permission on a given image stream. Users may remove a tag by deleting the imagestreamtag resource, which causes both spec and status for that tag to be removed. Image stream history is retained until an administrator runs the prune operation, which removes references that are no longer in use. To preserve a historical image, ensure there is a tag in spec pointing to that image by its digest. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| ImageStreamSpec represents options for ImageStreams. - -| `status` -| `object` -| ImageStreamStatus contains information about the state of this image stream. - -|=== -..status.import.spec -Description:: - ImageStreamSpec represents options for ImageStreams. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `dockerImageRepository` -| `string` -| dockerImageRepository is optional, if specified this stream is backed by a container repository on this server Deprecated: This field is deprecated as of v3.7 and will be removed in a future release. Specify the source for the tags to be imported in each tag via the spec.tags.from reference instead. - -| `lookupPolicy` -| `object` -| ImageLookupPolicy describes how an image stream can be used to override the image references used by pods, builds, and other resources in a namespace. - -| `tags` -| `array` -| tags map arbitrary string values to specific image locators - -| `tags[]` -| `object` -| TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track. - -|=== -..status.import.spec.lookupPolicy -Description:: - ImageLookupPolicy describes how an image stream can be used to override the image references used by pods, builds, and other resources in a namespace. - -Type:: - `object` - -Required:: - - `local` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `local` -| `boolean` -| local will change the docker short image references (like "mysql" or "php:latest") on objects in this namespace to the image ID whenever they match this image stream, instead of reaching out to a remote registry. The name will be fully qualified to an image ID if found. The tag's referencePolicy is taken into account on the replaced value. Only works within the current namespace. - -|=== -..status.import.spec.tags -Description:: - tags map arbitrary string values to specific image locators - -Type:: - `array` - - - - -..status.import.spec.tags[] -Description:: - TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage. ImageStreamTag references can only reference a tag within this same ImageStream. - -| `generation` -| `integer` -| Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation. - -| `importPolicy` -| `object` -| TagImportPolicy controls how images related to this tag will be imported. - -| `name` -| `string` -| Name of the tag - -| `reference` -| `boolean` -| Reference states if the tag will be imported. Default value is false, which means the tag will be imported. - -| `referencePolicy` -| `object` -| TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -|=== -..status.import.spec.tags[].importPolicy -Description:: - TagImportPolicy controls how images related to this tag will be imported. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `insecure` -| `boolean` -| Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import. - -| `scheduled` -| `boolean` -| Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported - -|=== -..status.import.spec.tags[].referencePolicy -Description:: - TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `type` -| `string` -| Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated container image registry and leverage the registry's ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream's namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable. - -|=== -..status.import.status -Description:: - ImageStreamStatus contains information about the state of this image stream. - -Type:: - `object` - -Required:: - - `dockerImageRepository` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `dockerImageRepository` -| `string` -| DockerImageRepository represents the effective location this stream may be accessed at. May be empty until the server determines where the repository is located - -| `publicDockerImageRepository` -| `string` -| PublicDockerImageRepository represents the public location from where the image can be pulled outside the cluster. This field may be empty if the administrator has not exposed the integrated registry externally. - -| `tags` -| `array` -| Tags are a historical record of images associated with each tag. The first entry in the TagEvent array is the currently tagged image. - -| `tags[]` -| `object` -| NamedTagEventList relates a tag to its image history. - -|=== -..status.import.status.tags -Description:: - Tags are a historical record of images associated with each tag. The first entry in the TagEvent array is the currently tagged image. - -Type:: - `array` - - - - -..status.import.status.tags[] -Description:: - NamedTagEventList relates a tag to its image history. - -Type:: - `object` - -Required:: - - `tag` - - `items` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| Conditions is an array of conditions that apply to the tag event list. - -| `conditions[]` -| `object` -| TagEventCondition contains condition information for a tag event. - -| `items` -| `array` -| Standard object's metadata. - -| `items[]` -| `object` -| TagEvent is used by ImageStreamStatus to keep a historical record of images associated with a tag. - -| `tag` -| `string` -| Tag is the tag for which the history is recorded - -|=== -..status.import.status.tags[].conditions -Description:: - Conditions is an array of conditions that apply to the tag event list. - -Type:: - `array` - - - - -..status.import.status.tags[].conditions[] -Description:: - TagEventCondition contains condition information for a tag event. - -Type:: - `object` - -Required:: - - `type` - - `status` - - `generation` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `generation` -| `integer` -| Generation is the spec tag generation that this status corresponds to - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| LastTransitionTIme is the time the condition transitioned from one status to another. - -| `message` -| `string` -| Message is a human readable description of the details about last transition, complementing reason. - -| `reason` -| `string` -| Reason is a brief machine readable explanation for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of tag event condition, currently only ImportSuccess - -|=== -..status.import.status.tags[].items -Description:: - Standard object's metadata. - -Type:: - `array` - - - - -..status.import.status.tags[].items[] -Description:: - TagEvent is used by ImageStreamStatus to keep a historical record of images associated with a tag. - -Type:: - `object` - -Required:: - - `created` - - `dockerImageReference` - - `image` - - `generation` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Created holds the time the TagEvent was created - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image - -| `generation` -| `integer` -| Generation is the spec tag generation that resulted in this tag being updated - -| `image` -| `string` -| Image is the image - -|=== -..status.repository -Description:: - RepositoryImportStatus describes the result of an image repository import - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalTags` -| `array (string)` -| AdditionalTags are tags that exist in the repository but were not imported because a maximum limit of automatic imports was applied. - -| `images` -| `array` -| Images is a list of images successfully retrieved by the import of the repository. - -| `images[]` -| `object` -| ImageImportStatus describes the result of an image import. - -| `status` -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| Status reflects whether any failure occurred during import - -|=== -..status.repository.images -Description:: - Images is a list of images successfully retrieved by the import of the repository. - -Type:: - `array` - - - - -..status.repository.images[] -Description:: - ImageImportStatus describes the result of an image import. - -Type:: - `object` - -Required:: - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `image` -| `object` -| Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -| `status` -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| Status is the status of the image import, including errors encountered while retrieving the image - -| `tag` -| `string` -| Tag is the tag this image was located under, if any - -|=== -..status.repository.images[].image -Description:: - Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -Type:: - `object` - -Required:: - - `dockerImageLayers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dockerImageConfig` -| `string` -| DockerImageConfig is a JSON blob that the runtime uses to set up the container. This is a part of manifest schema v2. - -| `dockerImageLayers` -| `array` -| DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -| `dockerImageLayers[]` -| `object` -| ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -| `dockerImageManifest` -| `string` -| DockerImageManifest is the raw JSON of the manifest - -| `dockerImageManifestMediaType` -| `string` -| DockerImageManifestMediaType specifies the mediaType of manifest. This is a part of manifest schema v2. - -| `dockerImageMetadata` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| DockerImageMetadata contains metadata about this image - -| `dockerImageMetadataVersion` -| `string` -| DockerImageMetadataVersion conveys the version of the object, which if empty defaults to "1.0" - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image. - -| `dockerImageSignatures` -| `array (string)` -| DockerImageSignatures provides the signatures as opaque blobs. This is a part of manifest schema v1. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signatures` -| `array` -| Signatures holds all signatures of the image. - -| `signatures[]` -| `object` -| ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -|=== -..status.repository.images[].image.dockerImageLayers -Description:: - DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -Type:: - `array` - - - - -..status.repository.images[].image.dockerImageLayers[] -Description:: - ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -Type:: - `object` - -Required:: - - `name` - - `size` - - `mediaType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mediaType` -| `string` -| MediaType of the referenced object. - -| `name` -| `string` -| Name of the layer as defined by the underlying store. - -| `size` -| `integer` -| Size of the layer in bytes as defined by the underlying store. - -|=== -..status.repository.images[].image.signatures -Description:: - Signatures holds all signatures of the image. - -Type:: - `array` - - - - -..status.repository.images[].image.signatures[] -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -Required:: - - `type` - - `content` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| Conditions represent the latest available observations of a signature's current state. - -| `conditions[]` -| `object` -| SignatureCondition describes an image signature condition of particular kind at particular probe time. - -| `content` -| `string` -| Required: An opaque binary string which is an image's signature. - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| If specified, it is the time of signature's creation. - -| `imageIdentity` -| `string` -| A human readable string representing image's identity. It could be a product name and version, or an image pull spec (e.g. "registry.access.redhat.com/rhel7/rhel:7.2"). - -| `issuedBy` -| `object` -| SignatureIssuer holds information about an issuer of signing certificate or key. - -| `issuedTo` -| `object` -| SignatureSubject holds information about a person or entity who created the signature. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signedClaims` -| `object (string)` -| Contains claims from the signature. - -| `type` -| `string` -| Required: Describes a type of stored blob. - -|=== -..status.repository.images[].image.signatures[].conditions -Description:: - Conditions represent the latest available observations of a signature's current state. - -Type:: - `array` - - - - -..status.repository.images[].image.signatures[].conditions[] -Description:: - SignatureCondition describes an image signature condition of particular kind at particular probe time. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of signature condition, Complete or Failed. - -|=== -..status.repository.images[].image.signatures[].issuedBy -Description:: - SignatureIssuer holds information about an issuer of signing certificate or key. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -|=== -..status.repository.images[].image.signatures[].issuedTo -Description:: - SignatureSubject holds information about a person or entity who created the signature. - -Type:: - `object` - -Required:: - - `publicKeyID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -| `publicKeyID` -| `string` -| If present, it is a human readable key id of public key belonging to the subject used to verify image signature. It should contain at least 64 lowest bits of public key's fingerprint (e.g. 0x685ebe62bf278440). - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreamimports` -- `POST`: create an ImageStreamImport - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreamimports - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create an ImageStreamImport - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagestreamimport-image-openshift-io-v1.adoc#imagestreamimport-image-openshift-io-v1[`ImageStreamImport image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestreamimport-image-openshift-io-v1.adoc#imagestreamimport-image-openshift-io-v1[`ImageStreamImport image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagestreamimport-image-openshift-io-v1.adoc#imagestreamimport-image-openshift-io-v1[`ImageStreamImport image.openshift.io/v1`] -| 202 - Accepted -| xref:../image_apis/imagestreamimport-image-openshift-io-v1.adoc#imagestreamimport-image-openshift-io-v1[`ImageStreamImport image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/image_apis/imagestreammapping-image-openshift-io-v1.adoc b/rest_api/image_apis/imagestreammapping-image-openshift-io-v1.adoc deleted file mode 100644 index 7db03a533060..000000000000 --- a/rest_api/image_apis/imagestreammapping-image-openshift-io-v1.adoc +++ /dev/null @@ -1,408 +0,0 @@ -[id="imagestreammapping-image-openshift-io-v1"] -= ImageStreamMapping [image.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ImageStreamMapping represents a mapping from a single image stream tag to a container image as well as the reference to the container image stream the image came from. This resource is used by privileged integrators to create an image resource and to associate it with an image stream in the status tags field. Creating an ImageStreamMapping will allow any user who can view the image stream to tag or pull that image, so only create mappings where the user has proven they have access to the image contents directly. The only operation supported for this resource is create and the metadata name and namespace should be set to the image stream containing the tag that should be updated. - -Type:: - `object` - -Required:: - - `image` - - `tag` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `image` -| `object` -| Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `tag` -| `string` -| Tag is a string value this image can be located with inside the stream. - -|=== -..image -Description:: - Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -Type:: - `object` - -Required:: - - `dockerImageLayers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dockerImageConfig` -| `string` -| DockerImageConfig is a JSON blob that the runtime uses to set up the container. This is a part of manifest schema v2. - -| `dockerImageLayers` -| `array` -| DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -| `dockerImageLayers[]` -| `object` -| ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -| `dockerImageManifest` -| `string` -| DockerImageManifest is the raw JSON of the manifest - -| `dockerImageManifestMediaType` -| `string` -| DockerImageManifestMediaType specifies the mediaType of manifest. This is a part of manifest schema v2. - -| `dockerImageMetadata` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| DockerImageMetadata contains metadata about this image - -| `dockerImageMetadataVersion` -| `string` -| DockerImageMetadataVersion conveys the version of the object, which if empty defaults to "1.0" - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image. - -| `dockerImageSignatures` -| `array (string)` -| DockerImageSignatures provides the signatures as opaque blobs. This is a part of manifest schema v1. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signatures` -| `array` -| Signatures holds all signatures of the image. - -| `signatures[]` -| `object` -| ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -|=== -..image.dockerImageLayers -Description:: - DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -Type:: - `array` - - - - -..image.dockerImageLayers[] -Description:: - ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -Type:: - `object` - -Required:: - - `name` - - `size` - - `mediaType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mediaType` -| `string` -| MediaType of the referenced object. - -| `name` -| `string` -| Name of the layer as defined by the underlying store. - -| `size` -| `integer` -| Size of the layer in bytes as defined by the underlying store. - -|=== -..image.signatures -Description:: - Signatures holds all signatures of the image. - -Type:: - `array` - - - - -..image.signatures[] -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -Required:: - - `type` - - `content` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| Conditions represent the latest available observations of a signature's current state. - -| `conditions[]` -| `object` -| SignatureCondition describes an image signature condition of particular kind at particular probe time. - -| `content` -| `string` -| Required: An opaque binary string which is an image's signature. - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| If specified, it is the time of signature's creation. - -| `imageIdentity` -| `string` -| A human readable string representing image's identity. It could be a product name and version, or an image pull spec (e.g. "registry.access.redhat.com/rhel7/rhel:7.2"). - -| `issuedBy` -| `object` -| SignatureIssuer holds information about an issuer of signing certificate or key. - -| `issuedTo` -| `object` -| SignatureSubject holds information about a person or entity who created the signature. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signedClaims` -| `object (string)` -| Contains claims from the signature. - -| `type` -| `string` -| Required: Describes a type of stored blob. - -|=== -..image.signatures[].conditions -Description:: - Conditions represent the latest available observations of a signature's current state. - -Type:: - `array` - - - - -..image.signatures[].conditions[] -Description:: - SignatureCondition describes an image signature condition of particular kind at particular probe time. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of signature condition, Complete or Failed. - -|=== -..image.signatures[].issuedBy -Description:: - SignatureIssuer holds information about an issuer of signing certificate or key. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -|=== -..image.signatures[].issuedTo -Description:: - SignatureSubject holds information about a person or entity who created the signature. - -Type:: - `object` - -Required:: - - `publicKeyID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -| `publicKeyID` -| `string` -| If present, it is a human readable key id of public key belonging to the subject used to verify image signature. It should contain at least 64 lowest bits of public key's fingerprint (e.g. 0x685ebe62bf278440). - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreammappings` -- `POST`: create an ImageStreamMapping - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreammappings - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create an ImageStreamMapping - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagestreammapping-image-openshift-io-v1.adoc#imagestreammapping-image-openshift-io-v1[`ImageStreamMapping image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestreammapping-image-openshift-io-v1.adoc#imagestreammapping-image-openshift-io-v1[`ImageStreamMapping image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagestreammapping-image-openshift-io-v1.adoc#imagestreammapping-image-openshift-io-v1[`ImageStreamMapping image.openshift.io/v1`] -| 202 - Accepted -| xref:../image_apis/imagestreammapping-image-openshift-io-v1.adoc#imagestreammapping-image-openshift-io-v1[`ImageStreamMapping image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/image_apis/imagestreamtag-image-openshift-io-v1.adoc b/rest_api/image_apis/imagestreamtag-image-openshift-io-v1.adoc deleted file mode 100644 index 214705ee14e8..000000000000 --- a/rest_api/image_apis/imagestreamtag-image-openshift-io-v1.adoc +++ /dev/null @@ -1,894 +0,0 @@ -[id="imagestreamtag-image-openshift-io-v1"] -= ImageStreamTag [image.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ImageStreamTag represents an Image that is retrieved by tag name from an ImageStream. Use this resource to interact with the tags and images in an image stream by tag, or to see the image details for a particular tag. The image associated with this resource is the most recently successfully tagged, imported, or pushed image (as described in the image stream status.tags.items list for this tag). If an import is in progress or has failed the previous image will be shown. Deleting an image stream tag clears both the status and spec fields of an image stream. If no image can be retrieved for a given tag, a not found error will be returned. - -Type:: - `object` - -Required:: - - `tag` - - `generation` - - `lookupPolicy` - - `image` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| conditions is an array of conditions that apply to the image stream tag. - -| `conditions[]` -| `object` -| TagEventCondition contains condition information for a tag event. - -| `generation` -| `integer` -| generation is the current generation of the tagged image - if tag is provided and this value is not equal to the tag generation, a user has requested an import that has not completed, or conditions will be filled out indicating any error. - -| `image` -| `object` -| Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `lookupPolicy` -| `object` -| ImageLookupPolicy describes how an image stream can be used to override the image references used by pods, builds, and other resources in a namespace. - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `tag` -| `object` -| TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track. - -|=== -..conditions -Description:: - conditions is an array of conditions that apply to the image stream tag. - -Type:: - `array` - - - - -..conditions[] -Description:: - TagEventCondition contains condition information for a tag event. - -Type:: - `object` - -Required:: - - `type` - - `status` - - `generation` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `generation` -| `integer` -| Generation is the spec tag generation that this status corresponds to - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| LastTransitionTIme is the time the condition transitioned from one status to another. - -| `message` -| `string` -| Message is a human readable description of the details about last transition, complementing reason. - -| `reason` -| `string` -| Reason is a brief machine readable explanation for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of tag event condition, currently only ImportSuccess - -|=== -..image -Description:: - Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -Type:: - `object` - -Required:: - - `dockerImageLayers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dockerImageConfig` -| `string` -| DockerImageConfig is a JSON blob that the runtime uses to set up the container. This is a part of manifest schema v2. - -| `dockerImageLayers` -| `array` -| DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -| `dockerImageLayers[]` -| `object` -| ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -| `dockerImageManifest` -| `string` -| DockerImageManifest is the raw JSON of the manifest - -| `dockerImageManifestMediaType` -| `string` -| DockerImageManifestMediaType specifies the mediaType of manifest. This is a part of manifest schema v2. - -| `dockerImageMetadata` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| DockerImageMetadata contains metadata about this image - -| `dockerImageMetadataVersion` -| `string` -| DockerImageMetadataVersion conveys the version of the object, which if empty defaults to "1.0" - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image. - -| `dockerImageSignatures` -| `array (string)` -| DockerImageSignatures provides the signatures as opaque blobs. This is a part of manifest schema v1. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signatures` -| `array` -| Signatures holds all signatures of the image. - -| `signatures[]` -| `object` -| ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -|=== -..image.dockerImageLayers -Description:: - DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -Type:: - `array` - - - - -..image.dockerImageLayers[] -Description:: - ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -Type:: - `object` - -Required:: - - `name` - - `size` - - `mediaType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mediaType` -| `string` -| MediaType of the referenced object. - -| `name` -| `string` -| Name of the layer as defined by the underlying store. - -| `size` -| `integer` -| Size of the layer in bytes as defined by the underlying store. - -|=== -..image.signatures -Description:: - Signatures holds all signatures of the image. - -Type:: - `array` - - - - -..image.signatures[] -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -Required:: - - `type` - - `content` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| Conditions represent the latest available observations of a signature's current state. - -| `conditions[]` -| `object` -| SignatureCondition describes an image signature condition of particular kind at particular probe time. - -| `content` -| `string` -| Required: An opaque binary string which is an image's signature. - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| If specified, it is the time of signature's creation. - -| `imageIdentity` -| `string` -| A human readable string representing image's identity. It could be a product name and version, or an image pull spec (e.g. "registry.access.redhat.com/rhel7/rhel:7.2"). - -| `issuedBy` -| `object` -| SignatureIssuer holds information about an issuer of signing certificate or key. - -| `issuedTo` -| `object` -| SignatureSubject holds information about a person or entity who created the signature. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signedClaims` -| `object (string)` -| Contains claims from the signature. - -| `type` -| `string` -| Required: Describes a type of stored blob. - -|=== -..image.signatures[].conditions -Description:: - Conditions represent the latest available observations of a signature's current state. - -Type:: - `array` - - - - -..image.signatures[].conditions[] -Description:: - SignatureCondition describes an image signature condition of particular kind at particular probe time. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of signature condition, Complete or Failed. - -|=== -..image.signatures[].issuedBy -Description:: - SignatureIssuer holds information about an issuer of signing certificate or key. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -|=== -..image.signatures[].issuedTo -Description:: - SignatureSubject holds information about a person or entity who created the signature. - -Type:: - `object` - -Required:: - - `publicKeyID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -| `publicKeyID` -| `string` -| If present, it is a human readable key id of public key belonging to the subject used to verify image signature. It should contain at least 64 lowest bits of public key's fingerprint (e.g. 0x685ebe62bf278440). - -|=== -..lookupPolicy -Description:: - ImageLookupPolicy describes how an image stream can be used to override the image references used by pods, builds, and other resources in a namespace. - -Type:: - `object` - -Required:: - - `local` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `local` -| `boolean` -| local will change the docker short image references (like "mysql" or "php:latest") on objects in this namespace to the image ID whenever they match this image stream, instead of reaching out to a remote registry. The name will be fully qualified to an image ID if found. The tag's referencePolicy is taken into account on the replaced value. Only works within the current namespace. - -|=== -..tag -Description:: - TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage. ImageStreamTag references can only reference a tag within this same ImageStream. - -| `generation` -| `integer` -| Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation. - -| `importPolicy` -| `object` -| TagImportPolicy controls how images related to this tag will be imported. - -| `name` -| `string` -| Name of the tag - -| `reference` -| `boolean` -| Reference states if the tag will be imported. Default value is false, which means the tag will be imported. - -| `referencePolicy` -| `object` -| TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -|=== -..tag.importPolicy -Description:: - TagImportPolicy controls how images related to this tag will be imported. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `insecure` -| `boolean` -| Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import. - -| `scheduled` -| `boolean` -| Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported - -|=== -..tag.referencePolicy -Description:: - TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `type` -| `string` -| Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated container image registry and leverage the registry's ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream's namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/image.openshift.io/v1/imagestreamtags` -- `GET`: list objects of kind ImageStreamTag -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreamtags` -- `GET`: list objects of kind ImageStreamTag -- `POST`: create an ImageStreamTag -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagestreamtags/{name}` -- `DELETE`: delete an ImageStreamTag -- `GET`: read the specified ImageStreamTag -- `PATCH`: partially update the specified ImageStreamTag -- `PUT`: replace the specified ImageStreamTag - - -=== /apis/image.openshift.io/v1/imagestreamtags - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ImageStreamTag - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagestreamtaglist-image-openshift-io-v1[`ImageStreamTagList image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreamtags - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ImageStreamTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagestreamtaglist-image-openshift-io-v1[`ImageStreamTagList image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an ImageStreamTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| 202 - Accepted -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagestreamtags/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageStreamTag -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an ImageStreamTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ImageStreamTag - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ImageStreamTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ImageStreamTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`ImageStreamTag image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/image_apis/imagetag-image-openshift-io-v1.adoc b/rest_api/image_apis/imagetag-image-openshift-io-v1.adoc deleted file mode 100644 index 6e822d179851..000000000000 --- a/rest_api/image_apis/imagetag-image-openshift-io-v1.adoc +++ /dev/null @@ -1,944 +0,0 @@ -[id="imagetag-image-openshift-io-v1"] -= ImageTag [image.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ImageTag represents a single tag within an image stream and includes the spec, the status history, and the currently referenced image (if any) of the provided tag. This type replaces the ImageStreamTag by providing a full view of the tag. ImageTags are returned for every spec or status tag present on the image stream. If no tag exists in either form a not found error will be returned by the API. A create operation will succeed if no spec tag has already been defined and the spec field is set. Delete will remove both spec and status elements from the image stream. - -Type:: - `object` - -Required:: - - `spec` - - `status` - - `image` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `image` -| `object` -| Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track. - -| `status` -| `object` -| NamedTagEventList relates a tag to its image history. - -|=== -..image -Description:: - Image is an immutable representation of a container image and metadata at a point in time. Images are named by taking a hash of their contents (metadata and content) and any change in format, content, or metadata results in a new name. The images resource is primarily for use by cluster administrators and integrations like the cluster image registry - end users instead access images via the imagestreamtags or imagestreamimages resources. While image metadata is stored in the API, any integration that implements the container image registry API must provide its own storage for the raw manifest data, image config, and layer contents. - -Type:: - `object` - -Required:: - - `dockerImageLayers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dockerImageConfig` -| `string` -| DockerImageConfig is a JSON blob that the runtime uses to set up the container. This is a part of manifest schema v2. - -| `dockerImageLayers` -| `array` -| DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -| `dockerImageLayers[]` -| `object` -| ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -| `dockerImageManifest` -| `string` -| DockerImageManifest is the raw JSON of the manifest - -| `dockerImageManifestMediaType` -| `string` -| DockerImageManifestMediaType specifies the mediaType of manifest. This is a part of manifest schema v2. - -| `dockerImageMetadata` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| DockerImageMetadata contains metadata about this image - -| `dockerImageMetadataVersion` -| `string` -| DockerImageMetadataVersion conveys the version of the object, which if empty defaults to "1.0" - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image. - -| `dockerImageSignatures` -| `array (string)` -| DockerImageSignatures provides the signatures as opaque blobs. This is a part of manifest schema v1. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signatures` -| `array` -| Signatures holds all signatures of the image. - -| `signatures[]` -| `object` -| ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -|=== -..image.dockerImageLayers -Description:: - DockerImageLayers represents the layers in the image. May not be set if the image does not define that data. - -Type:: - `array` - - - - -..image.dockerImageLayers[] -Description:: - ImageLayer represents a single layer of the image. Some images may have multiple layers. Some may have none. - -Type:: - `object` - -Required:: - - `name` - - `size` - - `mediaType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mediaType` -| `string` -| MediaType of the referenced object. - -| `name` -| `string` -| Name of the layer as defined by the underlying store. - -| `size` -| `integer` -| Size of the layer in bytes as defined by the underlying store. - -|=== -..image.signatures -Description:: - Signatures holds all signatures of the image. - -Type:: - `array` - - - - -..image.signatures[] -Description:: - ImageSignature holds a signature of an image. It allows to verify image identity and possibly other claims as long as the signature is trusted. Based on this information it is possible to restrict runnable images to those matching cluster-wide policy. Mandatory fields should be parsed by clients doing image verification. The others are parsed from signature's content by the server. They serve just an informative purpose. - -Type:: - `object` - -Required:: - - `type` - - `content` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| `array` -| Conditions represent the latest available observations of a signature's current state. - -| `conditions[]` -| `object` -| SignatureCondition describes an image signature condition of particular kind at particular probe time. - -| `content` -| `string` -| Required: An opaque binary string which is an image's signature. - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| If specified, it is the time of signature's creation. - -| `imageIdentity` -| `string` -| A human readable string representing image's identity. It could be a product name and version, or an image pull spec (e.g. "registry.access.redhat.com/rhel7/rhel:7.2"). - -| `issuedBy` -| `object` -| SignatureIssuer holds information about an issuer of signing certificate or key. - -| `issuedTo` -| `object` -| SignatureSubject holds information about a person or entity who created the signature. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `signedClaims` -| `object (string)` -| Contains claims from the signature. - -| `type` -| `string` -| Required: Describes a type of stored blob. - -|=== -..image.signatures[].conditions -Description:: - Conditions represent the latest available observations of a signature's current state. - -Type:: - `array` - - - - -..image.signatures[].conditions[] -Description:: - SignatureCondition describes an image signature condition of particular kind at particular probe time. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of signature condition, Complete or Failed. - -|=== -..image.signatures[].issuedBy -Description:: - SignatureIssuer holds information about an issuer of signing certificate or key. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -|=== -..image.signatures[].issuedTo -Description:: - SignatureSubject holds information about a person or entity who created the signature. - -Type:: - `object` - -Required:: - - `publicKeyID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| Common name (e.g. openshift-signing-service). - -| `organization` -| `string` -| Organization name. - -| `publicKeyID` -| `string` -| If present, it is a human readable key id of public key belonging to the subject used to verify image signature. It should contain at least 64 lowest bits of public key's fingerprint (e.g. 0x685ebe62bf278440). - -|=== -..spec -Description:: - TagReference specifies optional annotations for images using this tag and an optional reference to an ImageStreamTag, ImageStreamImage, or DockerImage this tag should track. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Optional; if specified, annotations that are applied to images retrieved via ImageStreamTags. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| Optional; if specified, a reference to another image that this tag should point to. Valid values are ImageStreamTag, ImageStreamImage, and DockerImage. ImageStreamTag references can only reference a tag within this same ImageStream. - -| `generation` -| `integer` -| Generation is a counter that tracks mutations to the spec tag (user intent). When a tag reference is changed the generation is set to match the current stream generation (which is incremented every time spec is changed). Other processes in the system like the image importer observe that the generation of spec tag is newer than the generation recorded in the status and use that as a trigger to import the newest remote tag. To trigger a new import, clients may set this value to zero which will reset the generation to the latest stream generation. Legacy clients will send this value as nil which will be merged with the current tag generation. - -| `importPolicy` -| `object` -| TagImportPolicy controls how images related to this tag will be imported. - -| `name` -| `string` -| Name of the tag - -| `reference` -| `boolean` -| Reference states if the tag will be imported. Default value is false, which means the tag will be imported. - -| `referencePolicy` -| `object` -| TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -|=== -..spec.importPolicy -Description:: - TagImportPolicy controls how images related to this tag will be imported. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `insecure` -| `boolean` -| Insecure is true if the server may bypass certificate verification or connect directly over HTTP during image import. - -| `scheduled` -| `boolean` -| Scheduled indicates to the server that this tag should be periodically checked to ensure it is up to date, and imported - -|=== -..spec.referencePolicy -Description:: - TagReferencePolicy describes how pull-specs for images in this image stream tag are generated when image change triggers in deployment configs or builds are resolved. This allows the image stream author to control how images are accessed. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `type` -| `string` -| Type determines how the image pull spec should be transformed when the image stream tag is used in deployment config triggers or new builds. The default value is `Source`, indicating the original location of the image should be used (if imported). The user may also specify `Local`, indicating that the pull spec should point to the integrated container image registry and leverage the registry's ability to proxy the pull to an upstream registry. `Local` allows the credentials used to pull this image to be managed from the image stream's namespace, so others on the platform can access a remote image but have no access to the remote secret. It also allows the image layers to be mirrored into the local registry which the images can still be pulled even if the upstream registry is unavailable. - -|=== -..status -Description:: - NamedTagEventList relates a tag to its image history. - -Type:: - `object` - -Required:: - - `tag` - - `items` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| Conditions is an array of conditions that apply to the tag event list. - -| `conditions[]` -| `object` -| TagEventCondition contains condition information for a tag event. - -| `items` -| `array` -| Standard object's metadata. - -| `items[]` -| `object` -| TagEvent is used by ImageStreamStatus to keep a historical record of images associated with a tag. - -| `tag` -| `string` -| Tag is the tag for which the history is recorded - -|=== -..status.conditions -Description:: - Conditions is an array of conditions that apply to the tag event list. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - TagEventCondition contains condition information for a tag event. - -Type:: - `object` - -Required:: - - `type` - - `status` - - `generation` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `generation` -| `integer` -| Generation is the spec tag generation that this status corresponds to - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| LastTransitionTIme is the time the condition transitioned from one status to another. - -| `message` -| `string` -| Message is a human readable description of the details about last transition, complementing reason. - -| `reason` -| `string` -| Reason is a brief machine readable explanation for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of tag event condition, currently only ImportSuccess - -|=== -..status.items -Description:: - Standard object's metadata. - -Type:: - `array` - - - - -..status.items[] -Description:: - TagEvent is used by ImageStreamStatus to keep a historical record of images associated with a tag. - -Type:: - `object` - -Required:: - - `created` - - `dockerImageReference` - - `image` - - `generation` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `created` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Created holds the time the TagEvent was created - -| `dockerImageReference` -| `string` -| DockerImageReference is the string that can be used to pull this image - -| `generation` -| `integer` -| Generation is the spec tag generation that resulted in this tag being updated - -| `image` -| `string` -| Image is the image - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/image.openshift.io/v1/imagetags` -- `GET`: list objects of kind ImageTag -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagetags` -- `GET`: list objects of kind ImageTag -- `POST`: create an ImageTag -* `/apis/image.openshift.io/v1/namespaces/{namespace}/imagetags/{name}` -- `DELETE`: delete an ImageTag -- `GET`: read the specified ImageTag -- `PATCH`: partially update the specified ImageTag -- `PUT`: replace the specified ImageTag - - -=== /apis/image.openshift.io/v1/imagetags - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ImageTag - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagetaglist-image-openshift-io-v1[`ImageTagList image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagetags - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ImageTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagetaglist-image-openshift-io-v1[`ImageTagList image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an ImageTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| 202 - Accepted -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/image.openshift.io/v1/namespaces/{namespace}/imagetags/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageTag -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an ImageTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ImageTag - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ImageTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ImageTag - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| 201 - Created -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`ImageTag image.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/index.adoc b/rest_api/index.adoc deleted file mode 100644 index d5aa045db697..000000000000 --- a/rest_api/index.adoc +++ /dev/null @@ -1,389 +0,0 @@ -// Automatically generated by 'openshift-apidocs-gen'. Do not edit. -[id="api-index"] -= API index -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -[cols="1,1",options="header"] -|=== -^| API ^| API group -| xref:./monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[Alertmanager] -| monitoring.coreos.com/v1 -| xref:./monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[AlertmanagerConfig] -| monitoring.coreos.com/v1alpha1 -| xref:./config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[APIServer] -| config.openshift.io/v1 -| xref:./extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[APIService] -| apiregistration.k8s.io/v1 -| xref:./schedule_and_quota_apis/appliedclusterresourcequota-quota-openshift-io-v1.adoc#appliedclusterresourcequota-quota-openshift-io-v1[AppliedClusterResourceQuota] -| quota.openshift.io/v1 -| xref:./config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[Authentication] -| config.openshift.io/v1 -| xref:./operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[Authentication] -| operator.openshift.io/v1 -| xref:./provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[BareMetalHost] -| metal3.io/v1alpha1 -| xref:./metadata_apis/binding-core-v1.adoc#binding-core-v1[Binding] -| core/v1 -| xref:./template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[BrokerTemplateInstance] -| template.openshift.io/v1 -| xref:./workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[Build] -| build.openshift.io/v1 -| xref:./config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[Build] -| config.openshift.io/v1 -| xref:./workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[BuildConfig] -| build.openshift.io/v1 -| xref:./operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[CatalogSource] -| operators.coreos.com/v1alpha1 -| xref:./security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[CertificateSigningRequest] -| certificates.k8s.io/v1 -| xref:./operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[CloudCredential] -| operator.openshift.io/v1 -| xref:./autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[ClusterAutoscaler] -| autoscaling.openshift.io/v1 -| xref:./operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[ClusterCSIDriver] -| operator.openshift.io/v1 -| xref:./network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[ClusterNetwork] -| network.openshift.io/v1 -| xref:./config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[ClusterOperator] -| config.openshift.io/v1 -| xref:./schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[ClusterResourceQuota] -| quota.openshift.io/v1 -| xref:./role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[ClusterRole] -| authorization.openshift.io/v1 -| xref:./rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[ClusterRole] -| rbac.authorization.k8s.io/v1 -| xref:./role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[ClusterRoleBinding] -| authorization.openshift.io/v1 -| xref:./rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[ClusterRoleBinding] -| rbac.authorization.k8s.io/v1 -| xref:./operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[ClusterServiceVersion] -| operators.coreos.com/v1alpha1 -| xref:./config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[ClusterVersion] -| config.openshift.io/v1 -| xref:./metadata_apis/componentstatus-core-v1.adoc#componentstatus-core-v1[ComponentStatus] -| core/v1 -| xref:./operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[Config] -| imageregistry.operator.openshift.io/v1 -| xref:./operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[Config] -| operator.openshift.io/v1 -| xref:./operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[Config] -| samples.operator.openshift.io/v1 -| xref:./metadata_apis/configmap-core-v1.adoc#configmap-core-v1[ConfigMap] -| core/v1 -| xref:./config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[Console] -| config.openshift.io/v1 -| xref:./operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[Console] -| operator.openshift.io/v1 -| xref:./console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[ConsoleCLIDownload] -| console.openshift.io/v1 -| xref:./console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[ConsoleExternalLogLink] -| console.openshift.io/v1 -| xref:./console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[ConsoleLink] -| console.openshift.io/v1 -| xref:./console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[ConsoleNotification] -| console.openshift.io/v1 -| xref:./console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[ConsoleQuickStart] -| console.openshift.io/v1 -| xref:./console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[ConsoleYAMLSample] -| console.openshift.io/v1 -| xref:./machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[ContainerRuntimeConfig] -| machineconfiguration.openshift.io/v1 -| xref:./machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[ControllerConfig] -| machineconfiguration.openshift.io/v1 -| xref:./metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[ControllerRevision] -| apps/v1 -| xref:./security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[CredentialsRequest] -| cloudcredential.openshift.io/v1 -| xref:./workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[CronJob] -| batch/v1beta1 -| xref:./storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[CSIDriver] -| storage.k8s.io/v1 -| xref:./storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[CSINode] -| storage.k8s.io/v1 -| xref:./operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[CSISnapshotController] -| operator.openshift.io/v1 -| xref:./extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[CustomResourceDefinition] -| apiextensions.k8s.io/v1 -| xref:./workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[DaemonSet] -| apps/v1 -| xref:./workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[Deployment] -| apps/v1 -| xref:./workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[DeploymentConfig] -| apps.openshift.io/v1 -| xref:./config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[DNS] -| config.openshift.io/v1 -| xref:./operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[DNS] -| operator.openshift.io/v1 -| xref:./operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[DNSRecord] -| ingress.operator.openshift.io/v1 -| xref:./network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[EgressNetworkPolicy] -| network.openshift.io/v1 -| xref:./network_apis/endpoints-core-v1.adoc#endpoints-core-v1[Endpoints] -| core/v1 -| xref:./network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[EndpointSlice] -| discovery.k8s.io/v1beta1 -| xref:./operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[Etcd] -| operator.openshift.io/v1 -| xref:./metadata_apis/event-core-v1.adoc#event-core-v1[Event] -| core/v1 -| xref:./metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[Event] -| events.k8s.io/v1 -| xref:./config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[FeatureGate] -| config.openshift.io/v1 -| xref:./schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[FlowSchema] -| flowcontrol.apiserver.k8s.io/v1alpha1 -| xref:./user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[Group] -| user.openshift.io/v1 -| xref:./config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[HelmChartRepository] -| helm.openshift.io/v1beta1 -| xref:./autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[HorizontalPodAutoscaler] -| autoscaling/v1 -| xref:./network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[HostSubnet] -| network.openshift.io/v1 -| xref:./user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[Identity] -| user.openshift.io/v1 -| xref:./config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[Image] -| config.openshift.io/v1 -| xref:./image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[Image] -| image.openshift.io/v1 -| xref:./operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[ImageContentSourcePolicy] -| operator.openshift.io/v1alpha1 -| xref:./operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[ImagePruner] -| imageregistry.operator.openshift.io/v1 -| xref:./image_apis/imagesignature-image-openshift-io-v1.adoc#imagesignature-image-openshift-io-v1[ImageSignature] -| image.openshift.io/v1 -| xref:./image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[ImageStream] -| image.openshift.io/v1 -| xref:./image_apis/imagestreamimage-image-openshift-io-v1.adoc#imagestreamimage-image-openshift-io-v1[ImageStreamImage] -| image.openshift.io/v1 -| xref:./image_apis/imagestreamimport-image-openshift-io-v1.adoc#imagestreamimport-image-openshift-io-v1[ImageStreamImport] -| image.openshift.io/v1 -| xref:./image_apis/imagestreammapping-image-openshift-io-v1.adoc#imagestreammapping-image-openshift-io-v1[ImageStreamMapping] -| image.openshift.io/v1 -| xref:./image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[ImageStreamTag] -| image.openshift.io/v1 -| xref:./image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[ImageTag] -| image.openshift.io/v1 -| xref:./config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[Infrastructure] -| config.openshift.io/v1 -| xref:./config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[Ingress] -| config.openshift.io/v1 -| xref:./network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[Ingress] -| networking.k8s.io/v1 -| xref:./network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[IngressClass] -| networking.k8s.io/v1 -| xref:./operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[IngressController] -| operator.openshift.io/v1 -| xref:./operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[InstallPlan] -| operators.coreos.com/v1alpha1 -| xref:./network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[IPPool] -| whereabouts.cni.cncf.io/v1alpha1 -| xref:./workloads_apis/job-batch-v1.adoc#job-batch-v1[Job] -| batch/v1 -| xref:./operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[KubeAPIServer] -| operator.openshift.io/v1 -| xref:./operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[KubeControllerManager] -| operator.openshift.io/v1 -| xref:./machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[KubeletConfig] -| machineconfiguration.openshift.io/v1 -| xref:./operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[KubeScheduler] -| operator.openshift.io/v1 -| xref:./operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[KubeStorageVersionMigrator] -| operator.openshift.io/v1 -| xref:./metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[Lease] -| coordination.k8s.io/v1 -| xref:./schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[LimitRange] -| core/v1 -| xref:./authorization_apis/localresourceaccessreview-authorization-openshift-io-v1.adoc#localresourceaccessreview-authorization-openshift-io-v1[LocalResourceAccessReview] -| authorization.openshift.io/v1 -| xref:./authorization_apis/localsubjectaccessreview-authorization-k8s-io-v1.adoc#localsubjectaccessreview-authorization-k8s-io-v1[LocalSubjectAccessReview] -| authorization.k8s.io/v1 -| xref:./authorization_apis/localsubjectaccessreview-authorization-openshift-io-v1.adoc#localsubjectaccessreview-authorization-openshift-io-v1[LocalSubjectAccessReview] -| authorization.openshift.io/v1 -| xref:./machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[Machine] -| machine.openshift.io/v1beta1 -| xref:./autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[MachineAutoscaler] -| autoscaling.openshift.io/v1beta1 -| xref:./machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[MachineConfig] -| machineconfiguration.openshift.io/v1 -| xref:./machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[MachineConfigPool] -| machineconfiguration.openshift.io/v1 -| xref:./machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[MachineHealthCheck] -| machine.openshift.io/v1beta1 -| xref:./machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[MachineSet] -| machine.openshift.io/v1beta1 -| xref:./extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[MutatingWebhookConfiguration] -| admissionregistration.k8s.io/v1 -| xref:./metadata_apis/namespace-core-v1.adoc#namespace-core-v1[Namespace] -| core/v1 -| xref:./network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[NetNamespace] -| network.openshift.io/v1 -| xref:./config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[Network] -| config.openshift.io/v1 -| xref:./operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[Network] -| operator.openshift.io/v1 -| xref:./network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[NetworkAttachmentDefinition] -| k8s.cni.cncf.io/v1 -| xref:./network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[NetworkPolicy] -| networking.k8s.io/v1 -| xref:./node_apis/node-core-v1.adoc#node-core-v1[Node] -| core/v1 -| xref:./config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[OAuth] -| config.openshift.io/v1 -| xref:./oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[OAuthAccessToken] -| oauth.openshift.io/v1 -| xref:./oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[OAuthAuthorizeToken] -| oauth.openshift.io/v1 -| xref:./oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[OAuthClient] -| oauth.openshift.io/v1 -| xref:./oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[OAuthClientAuthorization] -| oauth.openshift.io/v1 -| xref:./operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[OpenShiftAPIServer] -| operator.openshift.io/v1 -| xref:./operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[OpenShiftControllerManager] -| operator.openshift.io/v1 -| xref:./operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[Operator] -| operators.coreos.com/v1 -| xref:./operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[OperatorCondition] -| operators.coreos.com/v1 -| xref:./operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[OperatorGroup] -| operators.coreos.com/v1 -| xref:./config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[OperatorHub] -| config.openshift.io/v1 -| xref:./operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[OperatorPKI] -| network.operator.openshift.io/v1 -| xref:./operatorhub_apis/packagemanifest-packages-operators-coreos-com-v1.adoc#packagemanifest-packages-operators-coreos-com-v1[PackageManifest] -| packages.operators.coreos.com/v1 -| xref:./workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[PersistentVolume] -| core/v1 -| xref:./storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[PersistentVolumeClaim] -| core/v1 -| xref:./workloads_apis/pod-core-v1.adoc#pod-core-v1[Pod] -| core/v1 -| xref:./policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[PodDisruptionBudget] -| policy/v1beta1 -| xref:./monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[PodMonitor] -| monitoring.coreos.com/v1 -| xref:./network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[PodNetworkConnectivityCheck] -| controlplane.operator.openshift.io/v1alpha1 -| xref:./security_apis/podsecuritypolicyreview-security-openshift-io-v1.adoc#podsecuritypolicyreview-security-openshift-io-v1[PodSecurityPolicyReview] -| security.openshift.io/v1 -| xref:./security_apis/podsecuritypolicyselfsubjectreview-security-openshift-io-v1.adoc#podsecuritypolicyselfsubjectreview-security-openshift-io-v1[PodSecurityPolicySelfSubjectReview] -| security.openshift.io/v1 -| xref:./security_apis/podsecuritypolicysubjectreview-security-openshift-io-v1.adoc#podsecuritypolicysubjectreview-security-openshift-io-v1[PodSecurityPolicySubjectReview] -| security.openshift.io/v1 -| xref:./template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[PodTemplate] -| core/v1 -| xref:./schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[PriorityClass] -| scheduling.k8s.io/v1 -| xref:./schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[PriorityLevelConfiguration] -| flowcontrol.apiserver.k8s.io/v1alpha1 -| xref:./monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[Probe] -| monitoring.coreos.com/v1 -| xref:./node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[Profile] -| tuned.openshift.io/v1 -| xref:./config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[Project] -| config.openshift.io/v1 -| xref:./project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[Project] -| project.openshift.io/v1 -| xref:./project_apis/projectrequest-project-openshift-io-v1.adoc#projectrequest-project-openshift-io-v1[ProjectRequest] -| project.openshift.io/v1 -| xref:./monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[Prometheus] -| monitoring.coreos.com/v1 -| xref:./monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[PrometheusRule] -| monitoring.coreos.com/v1 -| xref:./provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[Provisioning] -| metal3.io/v1alpha1 -| xref:./config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[Proxy] -| config.openshift.io/v1 -| xref:./security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[RangeAllocation] -| security.openshift.io/v1 -| xref:./workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[ReplicaSet] -| apps/v1 -| xref:./workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[ReplicationController] -| core/v1 -| xref:./authorization_apis/resourceaccessreview-authorization-openshift-io-v1.adoc#resourceaccessreview-authorization-openshift-io-v1[ResourceAccessReview] -| authorization.openshift.io/v1 -| xref:./schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[ResourceQuota] -| core/v1 -| xref:./role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[Role] -| authorization.openshift.io/v1 -| xref:./rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[Role] -| rbac.authorization.k8s.io/v1 -| xref:./role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[RoleBinding] -| authorization.openshift.io/v1 -| xref:./rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[RoleBinding] -| rbac.authorization.k8s.io/v1 -| xref:./role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[RoleBindingRestriction] -| authorization.openshift.io/v1 -| xref:./network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[Route] -| route.openshift.io/v1 -| xref:./node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[RuntimeClass] -| node.k8s.io/v1 -| xref:./config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[Scheduler] -| config.openshift.io/v1 -| xref:./security_apis/secret-core-v1.adoc#secret-core-v1[Secret] -| core/v1 -| xref:./security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[SecurityContextConstraints] -| security.openshift.io/v1 -| xref:./authorization_apis/selfsubjectaccessreview-authorization-k8s-io-v1.adoc#selfsubjectaccessreview-authorization-k8s-io-v1[SelfSubjectAccessReview] -| authorization.k8s.io/v1 -| xref:./authorization_apis/selfsubjectrulesreview-authorization-k8s-io-v1.adoc#selfsubjectrulesreview-authorization-k8s-io-v1[SelfSubjectRulesReview] -| authorization.k8s.io/v1 -| xref:./authorization_apis/selfsubjectrulesreview-authorization-openshift-io-v1.adoc#selfsubjectrulesreview-authorization-openshift-io-v1[SelfSubjectRulesReview] -| authorization.openshift.io/v1 -| xref:./network_apis/service-core-v1.adoc#service-core-v1[Service] -| core/v1 -| xref:./security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[ServiceAccount] -| core/v1 -| xref:./operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[ServiceCA] -| operator.openshift.io/v1 -| xref:./monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[ServiceMonitor] -| monitoring.coreos.com/v1 -| xref:./workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[StatefulSet] -| apps/v1 -| xref:./operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[Storage] -| operator.openshift.io/v1 -| xref:./storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[StorageClass] -| storage.k8s.io/v1 -| xref:./storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[StorageState] -| migration.k8s.io/v1alpha1 -| xref:./storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[StorageVersionMigration] -| migration.k8s.io/v1alpha1 -| xref:./authorization_apis/subjectaccessreview-authorization-k8s-io-v1.adoc#subjectaccessreview-authorization-k8s-io-v1[SubjectAccessReview] -| authorization.k8s.io/v1 -| xref:./authorization_apis/subjectaccessreview-authorization-openshift-io-v1.adoc#subjectaccessreview-authorization-openshift-io-v1[SubjectAccessReview] -| authorization.openshift.io/v1 -| xref:./authorization_apis/subjectrulesreview-authorization-openshift-io-v1.adoc#subjectrulesreview-authorization-openshift-io-v1[SubjectRulesReview] -| authorization.openshift.io/v1 -| xref:./operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[Subscription] -| operators.coreos.com/v1alpha1 -| xref:./template_apis/template-template-openshift-io-v1.adoc#template-template-openshift-io-v1[Template] -| template.openshift.io/v1 -| xref:./template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[TemplateInstance] -| template.openshift.io/v1 -| xref:./monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[ThanosRuler] -| monitoring.coreos.com/v1 -| xref:./authorization_apis/tokenreview-authentication-k8s-io-v1.adoc#tokenreview-authentication-k8s-io-v1[TokenReview] -| authentication.k8s.io/v1 -| xref:./node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[Tuned] -| tuned.openshift.io/v1 -| xref:./user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[User] -| user.openshift.io/v1 -| xref:./user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[UserIdentityMapping] -| user.openshift.io/v1 -| xref:./oauth_apis/useroauthaccesstoken-oauth-openshift-io-v1.adoc#useroauthaccesstoken-oauth-openshift-io-v1[UserOAuthAccessToken] -| oauth.openshift.io/v1 -| xref:./extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[ValidatingWebhookConfiguration] -| admissionregistration.k8s.io/v1 -| xref:./storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[VolumeAttachment] -| storage.k8s.io/v1 -| xref:./storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[VolumeSnapshot] -| snapshot.storage.k8s.io/v1 -| xref:./storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[VolumeSnapshotClass] -| snapshot.storage.k8s.io/v1 -| xref:./storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[VolumeSnapshotContent] -| snapshot.storage.k8s.io/v1 -|=== diff --git a/rest_api/machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc deleted file mode 100644 index a646eaafa12e..000000000000 --- a/rest_api/machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc +++ /dev/null @@ -1,736 +0,0 @@ -[id="containerruntimeconfig-machineconfiguration-openshift-io-v1"] -= ContainerRuntimeConfig [machineconfiguration.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ContainerRuntimeConfig describes a customized Container Runtime configuration. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ContainerRuntimeConfigSpec defines the desired state of ContainerRuntimeConfig - -| `status` -| `object` -| ContainerRuntimeConfigStatus defines the observed state of a ContainerRuntimeConfig - -|=== -..spec -Description:: - ContainerRuntimeConfigSpec defines the desired state of ContainerRuntimeConfig - -Type:: - `object` - -Required:: - - `containerRuntimeConfig` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerRuntimeConfig` -| `object` -| ContainerRuntimeConfiguration defines the tuneables of the container runtime - -| `machineConfigPoolSelector` -| `object` -| A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. - -|=== -..spec.containerRuntimeConfig -Description:: - ContainerRuntimeConfiguration defines the tuneables of the container runtime - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel specifies the verbosity of the logs based on the level it is set to. Options are fatal, panic, error, warn, info, and debug. - -| `logSizeMax` -| `string` -| logSizeMax specifies the Maximum size allowed for the container log file. Negative numbers indicate that no size limit is imposed. If it is positive, it must be >= 8192 to match/exceed conmon's read buffer. - -| `overlaySize` -| `string` -| overlaySize specifies the maximum size of a container image. This flag can be used to set quota on the size of container images. (default: 10GB) - -| `pidsLimit` -| `integer` -| pidsLimit specifies the maximum number of processes allowed in a container - -|=== -..spec.machineConfigPoolSelector -Description:: - A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.machineConfigPoolSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.machineConfigPoolSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..status -Description:: - ContainerRuntimeConfigStatus defines the observed state of a ContainerRuntimeConfig - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions represents the latest available observations of current state. - -| `conditions[]` -| `object` -| ContainerRuntimeConfigCondition defines the state of the ContainerRuntimeConfig - -| `observedGeneration` -| `integer` -| observedGeneration represents the generation observed by the controller. - -|=== -..status.conditions -Description:: - conditions represents the latest available observations of current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - ContainerRuntimeConfigCondition defines the state of the ContainerRuntimeConfig - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `` -| lastTransitionTime is the time of the last update to the current status object. - -| `message` -| `string` -| message provides additional information about the current condition. This is only to be consumed by humans. - -| `reason` -| `string` -| reason is the reason for the condition's last transition. Reasons are PascalCase - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type specifies the state of the operator's reconciliation functionality. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/machineconfiguration.openshift.io/v1/containerruntimeconfigs` -- `DELETE`: delete collection of ContainerRuntimeConfig -- `GET`: list objects of kind ContainerRuntimeConfig -- `POST`: create a ContainerRuntimeConfig -* `/apis/machineconfiguration.openshift.io/v1/containerruntimeconfigs/{name}` -- `DELETE`: delete a ContainerRuntimeConfig -- `GET`: read the specified ContainerRuntimeConfig -- `PATCH`: partially update the specified ContainerRuntimeConfig -- `PUT`: replace the specified ContainerRuntimeConfig -* `/apis/machineconfiguration.openshift.io/v1/containerruntimeconfigs/{name}/status` -- `GET`: read status of the specified ContainerRuntimeConfig -- `PATCH`: partially update status of the specified ContainerRuntimeConfig -- `PUT`: replace status of the specified ContainerRuntimeConfig - - -=== /apis/machineconfiguration.openshift.io/v1/containerruntimeconfigs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#containerruntimeconfiglist-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfigList machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 202 - Accepted -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/containerruntimeconfigs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ContainerRuntimeConfig -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/containerruntimeconfigs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ContainerRuntimeConfig -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ContainerRuntimeConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`ContainerRuntimeConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc deleted file mode 100644 index 88cb4278a97b..000000000000 --- a/rest_api/machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc +++ /dev/null @@ -1,733 +0,0 @@ -[id="controllerconfig-machineconfiguration-openshift-io-v1"] -= ControllerConfig [machineconfiguration.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ControllerConfig describes configuration for MachineConfigController. This is currently only used to drive the MachineConfig objects generated by the TemplateController. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ControllerConfigSpec is the spec for ControllerConfig resource. - -| `status` -| `object` -| ControllerConfigStatus is the status for ControllerConfig - -|=== -..spec -Description:: - ControllerConfigSpec is the spec for ControllerConfig resource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalTrustBundle` -| `` -| additionalTrustBundle is a certificate bundle that will be added to the nodes trusted certificate store. - -| `cloudProviderCAData` -| `` -| cloudProvider specifies the cloud provider CA data - -| `cloudProviderConfig` -| `string` -| cloudProviderConfig is the configuration for the given cloud provider - -| `clusterDNSIP` -| `string` -| clusterDNSIP is the cluster DNS IP address - -| `dns` -| `` -| dns holds the cluster dns details - -| `etcdDiscoveryDomain` -| `string` -| etcdDiscoveryDomain is deprecated, use infra.status.etcdDiscoveryDomain instead - -| `images` -| `object (string)` -| images is map of images that are used by the controller to render templates under ./templates/ - -| `infra` -| `` -| infra holds the infrastructure details - -| `kubeAPIServerServingCAData` -| `string` -| kubeAPIServerServingCAData managed Kubelet to API Server Cert... Rotated automatically - -| `kubeletIPv6` -| `boolean` -| kubeletIPv6 is true to force a single-stack IPv6 kubelet config - -| `networkType` -| `string` -| networkType holds the type of network the cluster is using - -| `osImageURL` -| `string` -| osImageURL is the location of the container image that contains the OS update payload. Its value is taken from the data.osImageURL field on the machine-config-osimageurl ConfigMap. - -| `platform` -| `string` -| platform is deprecated. Use infra.status.platformStatus.type instead - -| `proxy` -| `` -| proxy holds the current proxy configuration for the nodes - -| `pullSecret` -| `object` -| pullSecret is the default pull secret that needs to be installed on all machines. - -| `rootCAData` -| `string` -| rootCAData specifies the root CA data - -|=== -..spec.pullSecret -Description:: - pullSecret is the default pull secret that needs to be installed on all machines. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status -Description:: - ControllerConfigStatus is the status for ControllerConfig - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions represents the latest available observations of current state. - -| `conditions[]` -| `object` -| ControllerConfigStatusCondition contains condition information for ControllerConfigStatus - -| `observedGeneration` -| `integer` -| observedGeneration represents the generation observed by the controller. - -|=== -..status.conditions -Description:: - conditions represents the latest available observations of current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - ControllerConfigStatusCondition contains condition information for ControllerConfigStatus - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `` -| lastTransitionTime is the time of the last update to the current status object. - -| `message` -| `string` -| message provides additional information about the current condition. This is only to be consumed by humans. - -| `reason` -| `string` -| reason is the reason for the condition's last transition. Reasons are PascalCase - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type specifies the state of the operator's reconciliation functionality. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/machineconfiguration.openshift.io/v1/controllerconfigs` -- `DELETE`: delete collection of ControllerConfig -- `GET`: list objects of kind ControllerConfig -- `POST`: create a ControllerConfig -* `/apis/machineconfiguration.openshift.io/v1/controllerconfigs/{name}` -- `DELETE`: delete a ControllerConfig -- `GET`: read the specified ControllerConfig -- `PATCH`: partially update the specified ControllerConfig -- `PUT`: replace the specified ControllerConfig -* `/apis/machineconfiguration.openshift.io/v1/controllerconfigs/{name}/status` -- `GET`: read status of the specified ControllerConfig -- `PATCH`: partially update status of the specified ControllerConfig -- `PUT`: replace status of the specified ControllerConfig - - -=== /apis/machineconfiguration.openshift.io/v1/controllerconfigs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#controllerconfiglist-machineconfiguration-openshift-io-v1[`ControllerConfigList machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 202 - Accepted -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/controllerconfigs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ControllerConfig -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/controllerconfigs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ControllerConfig -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ControllerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`ControllerConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc deleted file mode 100644 index fa7c8a32faf8..000000000000 --- a/rest_api/machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc +++ /dev/null @@ -1,707 +0,0 @@ -[id="kubeletconfig-machineconfiguration-openshift-io-v1"] -= KubeletConfig [machineconfiguration.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - KubeletConfig describes a customized Kubelet configuration. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| KubeletConfigSpec defines the desired state of KubeletConfig - -| `status` -| `object` -| KubeletConfigStatus defines the observed state of a KubeletConfig - -|=== -..spec -Description:: - KubeletConfigSpec defines the desired state of KubeletConfig - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kubeletConfig` -| `` -| The fields of the kubelet configuration are defined in kubernetes upstream. Please refer to the types defined in the version/commit used by OpenShift of the upstream kubernetes. - -| `logLevel` -| `integer` -| logLevel defines the log level of the Kubelet - -| `machineConfigPoolSelector` -| `object` -| A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. - -|=== -..spec.machineConfigPoolSelector -Description:: - A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.machineConfigPoolSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.machineConfigPoolSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..status -Description:: - KubeletConfigStatus defines the observed state of a KubeletConfig - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions represents the latest available observations of current state. - -| `conditions[]` -| `object` -| KubeletConfigCondition defines the state of the KubeletConfig - -| `observedGeneration` -| `integer` -| observedGeneration represents the generation observed by the controller. - -|=== -..status.conditions -Description:: - conditions represents the latest available observations of current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - KubeletConfigCondition defines the state of the KubeletConfig - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `` -| lastTransitionTime is the time of the last update to the current status object. - -| `message` -| `string` -| message provides additional information about the current condition. This is only to be consumed by humans. - -| `reason` -| `string` -| reason is the reason for the condition's last transition. Reasons are PascalCase - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type specifies the state of the operator's reconciliation functionality. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/machineconfiguration.openshift.io/v1/kubeletconfigs` -- `DELETE`: delete collection of KubeletConfig -- `GET`: list objects of kind KubeletConfig -- `POST`: create a KubeletConfig -* `/apis/machineconfiguration.openshift.io/v1/kubeletconfigs/{name}` -- `DELETE`: delete a KubeletConfig -- `GET`: read the specified KubeletConfig -- `PATCH`: partially update the specified KubeletConfig -- `PUT`: replace the specified KubeletConfig -* `/apis/machineconfiguration.openshift.io/v1/kubeletconfigs/{name}/status` -- `GET`: read status of the specified KubeletConfig -- `PATCH`: partially update status of the specified KubeletConfig -- `PUT`: replace status of the specified KubeletConfig - - -=== /apis/machineconfiguration.openshift.io/v1/kubeletconfigs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#kubeletconfiglist-machineconfiguration-openshift-io-v1[`KubeletConfigList machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 202 - Accepted -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/kubeletconfigs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeletConfig -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/kubeletconfigs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeletConfig -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified KubeletConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`KubeletConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/machine_apis/machine-apis-index.adoc b/rest_api/machine_apis/machine-apis-index.adoc deleted file mode 100644 index 731fc4480213..000000000000 --- a/rest_api/machine_apis/machine-apis-index.adoc +++ /dev/null @@ -1,72 +0,0 @@ -[id="machine-apis"] -= Machine APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== ContainerRuntimeConfig [machineconfiguration.openshift.io/v1] - -Description:: - ContainerRuntimeConfig describes a customized Container Runtime configuration. - -Type:: - `object` - -== ControllerConfig [machineconfiguration.openshift.io/v1] - -Description:: - ControllerConfig describes configuration for MachineConfigController. This is currently only used to drive the MachineConfig objects generated by the TemplateController. - -Type:: - `object` - -== KubeletConfig [machineconfiguration.openshift.io/v1] - -Description:: - KubeletConfig describes a customized Kubelet configuration. - -Type:: - `object` - -== MachineConfigPool [machineconfiguration.openshift.io/v1] - -Description:: - MachineConfigPool describes a pool of MachineConfigs. - -Type:: - `object` - -== MachineConfig [machineconfiguration.openshift.io/v1] - -Description:: - MachineConfig defines the configuration for a machine - -Type:: - `object` - -== MachineHealthCheck [machine.openshift.io/v1beta1] - -Description:: - MachineHealthCheck is the Schema for the machinehealthchecks API - -Type:: - `object` - -== Machine [machine.openshift.io/v1beta1] - -Description:: - Machine is the Schema for the machines API - -Type:: - `object` - -== MachineSet [machine.openshift.io/v1beta1] - -Description:: - MachineSet ensures that a specified number of machines replicas are running at any given time. - -Type:: - `object` - diff --git a/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc b/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc deleted file mode 100644 index c2561423dbe3..000000000000 --- a/rest_api/machine_apis/machine-machine-openshift-io-v1beta1.adoc +++ /dev/null @@ -1,983 +0,0 @@ -[id="machine-machine-openshift-io-v1beta1"] -= Machine [machine.openshift.io/v1beta1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Machine is the Schema for the machines API - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| MachineSpec defines the desired state of Machine - -| `status` -| `object` -| MachineStatus defines the observed state of Machine - -|=== -..spec -Description:: - MachineSpec defines the desired state of Machine - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| `object` -| ObjectMeta will autopopulate the Node created. Use this to indicate what labels, annotations, name prefix, etc., should be used when creating the Node. - -| `providerID` -| `string` -| ProviderID is the identification ID of the machine provided by the provider. This field must match the provider ID as seen on the node object corresponding to this machine. This field is required by higher level consumers of cluster-api. Example use case is cluster autoscaler with cluster-api as provider. Clean-up logic in the autoscaler compares machines to nodes to find out machines at provider which could not get registered as Kubernetes nodes. With cluster-api as a generic out-of-tree provider for autoscaler, this field is required by autoscaler to be able to have a provider view of the list of machines. Another list of nodes is queried from the k8s apiserver and then a comparison is done to find out unregistered machines and are marked for delete. This field will be set by the actuators and consumed by higher level entities like autoscaler that will be interfacing with cluster-api as generic provider. - -| `providerSpec` -| `object` -| ProviderSpec details Provider-specific configuration to use during node creation. - -| `taints` -| `array` -| The list of the taints to be applied to the corresponding Node in additive manner. This list will not overwrite any other taints added to the Node on an ongoing basis by other entities. These taints should be actively reconciled e.g. if you ask the machine controller to apply a taint and then manually remove the taint the machine controller will put it back) but not have the machine controller remove any taints - -| `taints[]` -| `object` -| The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint. - -|=== -..spec.metadata -Description:: - ObjectMeta will autopopulate the Node created. Use this to indicate what labels, annotations, name prefix, etc., should be used when creating the Node. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `generateName` -| `string` -| GenerateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. The provided value has the same validation rules as the Name field, and may be truncated by the length of the suffix required to make the value unique on the server. - If this field is specified and the generated name exists, the server will NOT return a 409 - instead, it will either return 201 Created or 500 with Reason ServerTimeout indicating a unique name could not be found in the time allotted, and the client should retry (optionally after the time indicated in the Retry-After header). - Applied only if Name is not specified. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#idempotency - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `namespace` -| `string` -| Namespace defines the space within each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. - Must be a DNS_LABEL. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/namespaces - -| `ownerReferences` -| `array` -| List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. - -| `ownerReferences[]` -| `object` -| OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field. - -|=== -..spec.metadata.ownerReferences -Description:: - List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. - -Type:: - `array` - - - - -..spec.metadata.ownerReferences[] -Description:: - OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field. - -Type:: - `object` - -Required:: - - `apiVersion` - - `kind` - - `name` - - `uid` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `blockOwnerDeletion` -| `boolean` -| If true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed. Defaults to false. To set this field, a user needs "delete" permission of the owner, otherwise 422 (Unprocessable Entity) will be returned. - -| `controller` -| `boolean` -| If true, this reference points to the managing controller. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `uid` -| `string` -| UID of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#uids - -|=== -..spec.providerSpec -Description:: - ProviderSpec details Provider-specific configuration to use during node creation. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `value` -| `` -| Value is an inlined, serialized representation of the resource configuration. It is recommended that providers maintain their own versioned API types that should be serialized/deserialized from this field, akin to component config. - -|=== -..spec.taints -Description:: - The list of the taints to be applied to the corresponding Node in additive manner. This list will not overwrite any other taints added to the Node on an ongoing basis by other entities. These taints should be actively reconciled e.g. if you ask the machine controller to apply a taint and then manually remove the taint the machine controller will put it back) but not have the machine controller remove any taints - -Type:: - `array` - - - - -..spec.taints[] -Description:: - The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint. - -Type:: - `object` - -Required:: - - `effect` - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Required. The effect of the taint on pods that do not tolerate the taint. Valid effects are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Required. The taint key to be applied to a node. - -| `timeAdded` -| `string` -| TimeAdded represents the time at which the taint was added. It is only written for NoExecute taints. - -| `value` -| `string` -| The taint value corresponding to the taint key. - -|=== -..status -Description:: - MachineStatus defines the observed state of Machine - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `addresses` -| `array` -| Addresses is a list of addresses assigned to the machine. Queried from cloud provider, if available. - -| `addresses[]` -| `object` -| NodeAddress contains information for the node's address. - -| `errorMessage` -| `string` -| ErrorMessage will be set in the event that there is a terminal problem reconciling the Machine and will contain a more verbose string suitable for logging and human consumption. - This field should not be set for transitive errors that a controller faces that are expected to be fixed automatically over time (like service outages), but instead indicate that something is fundamentally wrong with the Machine's spec or the configuration of the controller, and that manual intervention is required. Examples of terminal errors would be invalid combinations of settings in the spec, values that are unsupported by the controller, or the responsible controller itself being critically misconfigured. - Any transient errors that occur during the reconciliation of Machines can be added as events to the Machine object and/or logged in the controller's output. - -| `errorReason` -| `string` -| ErrorReason will be set in the event that there is a terminal problem reconciling the Machine and will contain a succinct value suitable for machine interpretation. - This field should not be set for transitive errors that a controller faces that are expected to be fixed automatically over time (like service outages), but instead indicate that something is fundamentally wrong with the Machine's spec or the configuration of the controller, and that manual intervention is required. Examples of terminal errors would be invalid combinations of settings in the spec, values that are unsupported by the controller, or the responsible controller itself being critically misconfigured. - Any transient errors that occur during the reconciliation of Machines can be added as events to the Machine object and/or logged in the controller's output. - -| `lastOperation` -| `object` -| LastOperation describes the last-operation performed by the machine-controller. This API should be useful as a history in terms of the latest operation performed on the specific machine. It should also convey the state of the latest-operation for example if it is still on-going, failed or completed successfully. - -| `lastUpdated` -| `string` -| LastUpdated identifies when this status was last observed. - -| `nodeRef` -| `object` -| NodeRef will point to the corresponding Node if it exists. - -| `phase` -| `string` -| Phase represents the current phase of machine actuation. One of: Failed, Provisioning, Provisioned, Running, Deleting - -| `providerStatus` -| `` -| ProviderStatus details a Provider-specific status. It is recommended that providers maintain their own versioned API types that should be serialized/deserialized from this field. - -|=== -..status.addresses -Description:: - Addresses is a list of addresses assigned to the machine. Queried from cloud provider, if available. - -Type:: - `array` - - - - -..status.addresses[] -Description:: - NodeAddress contains information for the node's address. - -Type:: - `object` - -Required:: - - `address` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `address` -| `string` -| The node address. - -| `type` -| `string` -| Node address type, one of Hostname, ExternalIP or InternalIP. - -|=== -..status.lastOperation -Description:: - LastOperation describes the last-operation performed by the machine-controller. This API should be useful as a history in terms of the latest operation performed on the specific machine. It should also convey the state of the latest-operation for example if it is still on-going, failed or completed successfully. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| Description is the human-readable description of the last operation. - -| `lastUpdated` -| `string` -| LastUpdated is the timestamp at which LastOperation API was last-updated. - -| `state` -| `string` -| State is the current status of the last performed operation. E.g. Processing, Failed, Successful etc - -| `type` -| `string` -| Type is the type of operation which was last performed. E.g. Create, Delete, Update etc - -|=== -..status.nodeRef -Description:: - NodeRef will point to the corresponding Node if it exists. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/machine.openshift.io/v1beta1/machines` -- `GET`: list objects of kind Machine -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machines` -- `DELETE`: delete collection of Machine -- `GET`: list objects of kind Machine -- `POST`: create a Machine -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machines/{name}` -- `DELETE`: delete a Machine -- `GET`: read the specified Machine -- `PATCH`: partially update the specified Machine -- `PUT`: replace the specified Machine -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machines/{name}/status` -- `GET`: read status of the specified Machine -- `PATCH`: partially update status of the specified Machine -- `PUT`: replace status of the specified Machine - - -=== /apis/machine.openshift.io/v1beta1/machines - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Machine - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machinelist-machine-openshift-io-v1beta1[`MachineList machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machines - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machinelist-machine-openshift-io-v1beta1[`MachineList machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 202 - Accepted -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machines/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Machine -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machines/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Machine -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Machine - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`Machine machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc deleted file mode 100644 index c6d286c38579..000000000000 --- a/rest_api/machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc +++ /dev/null @@ -1,442 +0,0 @@ -[id="machineconfig-machineconfiguration-openshift-io-v1"] -= MachineConfig [machineconfiguration.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - MachineConfig defines the configuration for a machine - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| MachineConfigSpec is the spec for MachineConfig - -|=== -..spec -Description:: - MachineConfigSpec is the spec for MachineConfig - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `config` -| `` -| Config is a Ignition Config object. - -| `extensions` -| `` -| List of additional features that can be enabled on host - -| `fips` -| `boolean` -| FIPS controls FIPS mode - -| `kernelArguments` -| `` -| KernelArguments contains a list of kernel arguments to be added - -| `kernelType` -| `string` -| Contains which kernel we want to be running like default (traditional), realtime - -| `osImageURL` -| `string` -| OSImageURL specifies the remote location that will be used to fetch the OS to fetch the OS. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/machineconfiguration.openshift.io/v1/machineconfigs` -- `DELETE`: delete collection of MachineConfig -- `GET`: list objects of kind MachineConfig -- `POST`: create a MachineConfig -* `/apis/machineconfiguration.openshift.io/v1/machineconfigs/{name}` -- `DELETE`: delete a MachineConfig -- `GET`: read the specified MachineConfig -- `PATCH`: partially update the specified MachineConfig -- `PUT`: replace the specified MachineConfig - - -=== /apis/machineconfiguration.openshift.io/v1/machineconfigs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of MachineConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind MachineConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machineconfiglist-machineconfiguration-openshift-io-v1[`MachineConfigList machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a MachineConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| 202 - Accepted -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/machineconfigs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineConfig -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a MachineConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified MachineConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified MachineConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified MachineConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`MachineConfig machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc b/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc deleted file mode 100644 index 0c546bdcc9d8..000000000000 --- a/rest_api/machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc +++ /dev/null @@ -1,1012 +0,0 @@ -[id="machineconfigpool-machineconfiguration-openshift-io-v1"] -= MachineConfigPool [machineconfiguration.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - MachineConfigPool describes a pool of MachineConfigs. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| MachineConfigPoolSpec is the spec for MachineConfigPool resource. - -| `status` -| `object` -| MachineConfigPoolStatus is the status for MachineConfigPool resource. - -|=== -..spec -Description:: - MachineConfigPoolSpec is the spec for MachineConfigPool resource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configuration` -| `object` -| The targeted MachineConfig object for the machine config pool. - -| `machineConfigSelector` -| `object` -| machineConfigSelector specifies a label selector for MachineConfigs. Refer https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ on how label and selectors work. - -| `maxUnavailable` -| `integer-or-string` -| maxUnavailable specifies the percentage or constant number of machines that can be updating at any given time. default is 1. - -| `nodeSelector` -| `object` -| nodeSelector specifies a label selector for Machines - -| `paused` -| `boolean` -| paused specifies whether or not changes to this machine config pool should be stopped. This includes generating new desiredMachineConfig and update of machines. - -|=== -..spec.configuration -Description:: - The targeted MachineConfig object for the machine config pool. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `source` -| `array` -| source is the list of MachineConfig objects that were used to generate the single MachineConfig object specified in `content`. - -| `source[]` -| `object` -| ObjectReference contains enough information to let you inspect or modify the referred object. - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..spec.configuration.source -Description:: - source is the list of MachineConfig objects that were used to generate the single MachineConfig object specified in `content`. - -Type:: - `array` - - - - -..spec.configuration.source[] -Description:: - ObjectReference contains enough information to let you inspect or modify the referred object. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..spec.machineConfigSelector -Description:: - machineConfigSelector specifies a label selector for MachineConfigs. Refer https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ on how label and selectors work. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.machineConfigSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.machineConfigSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.nodeSelector -Description:: - nodeSelector specifies a label selector for Machines - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.nodeSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.nodeSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..status -Description:: - MachineConfigPoolStatus is the status for MachineConfigPool resource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions represents the latest available observations of current state. - -| `conditions[]` -| `object` -| MachineConfigPoolCondition contains condition information for an MachineConfigPool. - -| `configuration` -| `object` -| configuration represents the current MachineConfig object for the machine config pool. - -| `degradedMachineCount` -| `integer` -| degradedMachineCount represents the total number of machines marked degraded (or unreconcilable). A node is marked degraded if applying a configuration failed.. - -| `machineCount` -| `integer` -| machineCount represents the total number of machines in the machine config pool. - -| `observedGeneration` -| `integer` -| observedGeneration represents the generation observed by the controller. - -| `readyMachineCount` -| `integer` -| readyMachineCount represents the total number of ready machines targeted by the pool. - -| `unavailableMachineCount` -| `integer` -| unavailableMachineCount represents the total number of unavailable (non-ready) machines targeted by the pool. A node is marked unavailable if it is in updating state or NodeReady condition is false. - -| `updatedMachineCount` -| `integer` -| updatedMachineCount represents the total number of machines targeted by the pool that have the CurrentMachineConfig as their config. - -|=== -..status.conditions -Description:: - conditions represents the latest available observations of current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - MachineConfigPoolCondition contains condition information for an MachineConfigPool. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `` -| lastTransitionTime is the timestamp corresponding to the last status change of this condition. - -| `message` -| `string` -| message is a human readable description of the details of the last transition, complementing reason. - -| `reason` -| `string` -| reason is a brief machine readable explanation for the condition's last transition. - -| `status` -| `string` -| status of the condition, one of ('True', 'False', 'Unknown'). - -| `type` -| `string` -| type of the condition, currently ('Done', 'Updating', 'Failed'). - -|=== -..status.configuration -Description:: - configuration represents the current MachineConfig object for the machine config pool. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `source` -| `array` -| source is the list of MachineConfig objects that were used to generate the single MachineConfig object specified in `content`. - -| `source[]` -| `object` -| ObjectReference contains enough information to let you inspect or modify the referred object. - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status.configuration.source -Description:: - source is the list of MachineConfig objects that were used to generate the single MachineConfig object specified in `content`. - -Type:: - `array` - - - - -..status.configuration.source[] -Description:: - ObjectReference contains enough information to let you inspect or modify the referred object. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/machineconfiguration.openshift.io/v1/machineconfigpools` -- `DELETE`: delete collection of MachineConfigPool -- `GET`: list objects of kind MachineConfigPool -- `POST`: create a MachineConfigPool -* `/apis/machineconfiguration.openshift.io/v1/machineconfigpools/{name}` -- `DELETE`: delete a MachineConfigPool -- `GET`: read the specified MachineConfigPool -- `PATCH`: partially update the specified MachineConfigPool -- `PUT`: replace the specified MachineConfigPool -* `/apis/machineconfiguration.openshift.io/v1/machineconfigpools/{name}/status` -- `GET`: read status of the specified MachineConfigPool -- `PATCH`: partially update status of the specified MachineConfigPool -- `PUT`: replace status of the specified MachineConfigPool - - -=== /apis/machineconfiguration.openshift.io/v1/machineconfigpools - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machineconfigpoollist-machineconfiguration-openshift-io-v1[`MachineConfigPoolList machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 202 - Accepted -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/machineconfigpools/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineConfigPool -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machineconfiguration.openshift.io/v1/machineconfigpools/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineConfigPool -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified MachineConfigPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 201 - Created -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`MachineConfigPool machineconfiguration.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc b/rest_api/machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc deleted file mode 100644 index ee0565df0e61..000000000000 --- a/rest_api/machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc +++ /dev/null @@ -1,856 +0,0 @@ -[id="machinehealthcheck-machine-openshift-io-v1beta1"] -= MachineHealthCheck [machine.openshift.io/v1beta1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - MachineHealthCheck is the Schema for the machinehealthchecks API - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of machine health check policy - -| `status` -| `object` -| Most recently observed status of MachineHealthCheck resource - -|=== -..spec -Description:: - Specification of machine health check policy - -Type:: - `object` - -Required:: - - `selector` - - `unhealthyConditions` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxUnhealthy` -| `integer-or-string` -| Any farther remediation is only allowed if at most "MaxUnhealthy" machines selected by "selector" are not healthy. Expects either a postive integer value or a percentage value. Percentage values must be positive whole numbers and are capped at 100%. Both 0 and 0% are valid and will block all remediation. - -| `nodeStartupTimeout` -| `string` -| Machines older than this duration without a node will be considered to have failed and will be remediated. Expects an unsigned duration string of decimal numbers each with optional fraction and a unit suffix, eg "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". - -| `selector` -| `object` -| Label selector to match machines whose health will be exercised. Note: An empty selector will match all machines. - -| `unhealthyConditions` -| `array` -| UnhealthyConditions contains a list of the conditions that determine whether a node is considered unhealthy. The conditions are combined in a logical OR, i.e. if any of the conditions is met, the node is unhealthy. - -| `unhealthyConditions[]` -| `object` -| UnhealthyCondition represents a Node condition type and value with a timeout specified as a duration. When the named condition has been in the given status for at least the timeout value, a node is considered unhealthy. - -|=== -..spec.selector -Description:: - Label selector to match machines whose health will be exercised. Note: An empty selector will match all machines. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.unhealthyConditions -Description:: - UnhealthyConditions contains a list of the conditions that determine whether a node is considered unhealthy. The conditions are combined in a logical OR, i.e. if any of the conditions is met, the node is unhealthy. - -Type:: - `array` - - - - -..spec.unhealthyConditions[] -Description:: - UnhealthyCondition represents a Node condition type and value with a timeout specified as a duration. When the named condition has been in the given status for at least the timeout value, a node is considered unhealthy. - -Type:: - `object` - -Required:: - - `status` - - `timeout` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `status` -| `string` -| - -| `timeout` -| `string` -| Expects an unsigned duration string of decimal numbers each with optional fraction and a unit suffix, eg "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". - -| `type` -| `string` -| - -|=== -..status -Description:: - Most recently observed status of MachineHealthCheck resource - -Type:: - `object` - -Required:: - - `currentHealthy` - - `expectedMachines` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| Conditions defines the current state of the MachineHealthCheck - -| `conditions[]` -| `object` -| Condition defines an observation of a Machine API resource operational state. - -| `currentHealthy` -| `integer` -| total number of machines counted by this machine health check - -| `expectedMachines` -| `integer` -| total number of machines counted by this machine health check - -| `remediationsAllowed` -| `integer` -| RemediationsAllowed is the number of further remediations allowed by this machine health check before maxUnhealthy short circuiting will be applied - -|=== -..status.conditions -Description:: - Conditions defines the current state of the MachineHealthCheck - -Type:: - `array` - - - - -..status.conditions[] -Description:: - Condition defines an observation of a Machine API resource operational state. - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| Last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. - -| `message` -| `string` -| A human readable message indicating details about the transition. This field may be empty. - -| `reason` -| `string` -| The reason for the condition's last transition in CamelCase. The specific API may choose whether or not this field is considered a guaranteed API. This field may not be empty. - -| `severity` -| `string` -| Severity provides an explicit classification of Reason code, so the users or machines can immediately understand the current situation and act accordingly. The Severity field MUST be set only when Status=False. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/machine.openshift.io/v1beta1/machinehealthchecks` -- `GET`: list objects of kind MachineHealthCheck -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinehealthchecks` -- `DELETE`: delete collection of MachineHealthCheck -- `GET`: list objects of kind MachineHealthCheck -- `POST`: create a MachineHealthCheck -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinehealthchecks/{name}` -- `DELETE`: delete a MachineHealthCheck -- `GET`: read the specified MachineHealthCheck -- `PATCH`: partially update the specified MachineHealthCheck -- `PUT`: replace the specified MachineHealthCheck -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinehealthchecks/{name}/status` -- `GET`: read status of the specified MachineHealthCheck -- `PATCH`: partially update status of the specified MachineHealthCheck -- `PUT`: replace status of the specified MachineHealthCheck - - -=== /apis/machine.openshift.io/v1beta1/machinehealthchecks - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind MachineHealthCheck - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machinehealthchecklist-machine-openshift-io-v1beta1[`MachineHealthCheckList machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinehealthchecks - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machinehealthchecklist-machine-openshift-io-v1beta1[`MachineHealthCheckList machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 202 - Accepted -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinehealthchecks/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineHealthCheck -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinehealthchecks/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineHealthCheck -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified MachineHealthCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`MachineHealthCheck machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc b/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc deleted file mode 100644 index 2632b45656ab..000000000000 --- a/rest_api/machine_apis/machineset-machine-openshift-io-v1beta1.adoc +++ /dev/null @@ -1,1227 +0,0 @@ -[id="machineset-machine-openshift-io-v1beta1"] -= MachineSet [machine.openshift.io/v1beta1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - MachineSet ensures that a specified number of machines replicas are running at any given time. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| MachineSetSpec defines the desired state of MachineSet - -| `status` -| `object` -| MachineSetStatus defines the observed state of MachineSet - -|=== -..spec -Description:: - MachineSetSpec defines the desired state of MachineSet - -Type:: - `object` - -Required:: - - `selector` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `deletePolicy` -| `string` -| DeletePolicy defines the policy used to identify nodes to delete when downscaling. Defaults to "Random". Valid values are "Random, "Newest", "Oldest" - -| `minReadySeconds` -| `integer` -| MinReadySeconds is the minimum number of seconds for which a newly created machine should be ready. Defaults to 0 (machine will be considered available as soon as it is ready) - -| `replicas` -| `integer` -| Replicas is the number of desired replicas. This is a pointer to distinguish between explicit zero and unspecified. Defaults to 1. - -| `selector` -| `object` -| Selector is a label query over machines that should match the replica count. Label keys and values that must match in order to be controlled by this MachineSet. It must match the machine template's labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors - -| `template` -| `object` -| Template is the object that describes the machine that will be created if insufficient replicas are detected. - -|=== -..spec.selector -Description:: - Selector is a label query over machines that should match the replica count. Label keys and values that must match in order to be controlled by this MachineSet. It must match the machine template's labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.template -Description:: - Template is the object that describes the machine that will be created if insufficient replicas are detected. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| `object` -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of the desired behavior of the machine. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -|=== -..spec.template.metadata -Description:: - Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `generateName` -| `string` -| GenerateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. The provided value has the same validation rules as the Name field, and may be truncated by the length of the suffix required to make the value unique on the server. - If this field is specified and the generated name exists, the server will NOT return a 409 - instead, it will either return 201 Created or 500 with Reason ServerTimeout indicating a unique name could not be found in the time allotted, and the client should retry (optionally after the time indicated in the Retry-After header). - Applied only if Name is not specified. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#idempotency - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `namespace` -| `string` -| Namespace defines the space within each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. - Must be a DNS_LABEL. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/namespaces - -| `ownerReferences` -| `array` -| List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. - -| `ownerReferences[]` -| `object` -| OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field. - -|=== -..spec.template.metadata.ownerReferences -Description:: - List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. - -Type:: - `array` - - - - -..spec.template.metadata.ownerReferences[] -Description:: - OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field. - -Type:: - `object` - -Required:: - - `apiVersion` - - `kind` - - `name` - - `uid` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `blockOwnerDeletion` -| `boolean` -| If true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed. Defaults to false. To set this field, a user needs "delete" permission of the owner, otherwise 422 (Unprocessable Entity) will be returned. - -| `controller` -| `boolean` -| If true, this reference points to the managing controller. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `uid` -| `string` -| UID of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#uids - -|=== -..spec.template.spec -Description:: - Specification of the desired behavior of the machine. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| `object` -| ObjectMeta will autopopulate the Node created. Use this to indicate what labels, annotations, name prefix, etc., should be used when creating the Node. - -| `providerID` -| `string` -| ProviderID is the identification ID of the machine provided by the provider. This field must match the provider ID as seen on the node object corresponding to this machine. This field is required by higher level consumers of cluster-api. Example use case is cluster autoscaler with cluster-api as provider. Clean-up logic in the autoscaler compares machines to nodes to find out machines at provider which could not get registered as Kubernetes nodes. With cluster-api as a generic out-of-tree provider for autoscaler, this field is required by autoscaler to be able to have a provider view of the list of machines. Another list of nodes is queried from the k8s apiserver and then a comparison is done to find out unregistered machines and are marked for delete. This field will be set by the actuators and consumed by higher level entities like autoscaler that will be interfacing with cluster-api as generic provider. - -| `providerSpec` -| `object` -| ProviderSpec details Provider-specific configuration to use during node creation. - -| `taints` -| `array` -| The list of the taints to be applied to the corresponding Node in additive manner. This list will not overwrite any other taints added to the Node on an ongoing basis by other entities. These taints should be actively reconciled e.g. if you ask the machine controller to apply a taint and then manually remove the taint the machine controller will put it back) but not have the machine controller remove any taints - -| `taints[]` -| `object` -| The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint. - -|=== -..spec.template.spec.metadata -Description:: - ObjectMeta will autopopulate the Node created. Use this to indicate what labels, annotations, name prefix, etc., should be used when creating the Node. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `generateName` -| `string` -| GenerateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. The provided value has the same validation rules as the Name field, and may be truncated by the length of the suffix required to make the value unique on the server. - If this field is specified and the generated name exists, the server will NOT return a 409 - instead, it will either return 201 Created or 500 with Reason ServerTimeout indicating a unique name could not be found in the time allotted, and the client should retry (optionally after the time indicated in the Retry-After header). - Applied only if Name is not specified. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#idempotency - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `namespace` -| `string` -| Namespace defines the space within each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. - Must be a DNS_LABEL. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/namespaces - -| `ownerReferences` -| `array` -| List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. - -| `ownerReferences[]` -| `object` -| OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field. - -|=== -..spec.template.spec.metadata.ownerReferences -Description:: - List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. - -Type:: - `array` - - - - -..spec.template.spec.metadata.ownerReferences[] -Description:: - OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field. - -Type:: - `object` - -Required:: - - `apiVersion` - - `kind` - - `name` - - `uid` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `blockOwnerDeletion` -| `boolean` -| If true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed. Defaults to false. To set this field, a user needs "delete" permission of the owner, otherwise 422 (Unprocessable Entity) will be returned. - -| `controller` -| `boolean` -| If true, this reference points to the managing controller. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `uid` -| `string` -| UID of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#uids - -|=== -..spec.template.spec.providerSpec -Description:: - ProviderSpec details Provider-specific configuration to use during node creation. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `value` -| `` -| Value is an inlined, serialized representation of the resource configuration. It is recommended that providers maintain their own versioned API types that should be serialized/deserialized from this field, akin to component config. - -|=== -..spec.template.spec.taints -Description:: - The list of the taints to be applied to the corresponding Node in additive manner. This list will not overwrite any other taints added to the Node on an ongoing basis by other entities. These taints should be actively reconciled e.g. if you ask the machine controller to apply a taint and then manually remove the taint the machine controller will put it back) but not have the machine controller remove any taints - -Type:: - `array` - - - - -..spec.template.spec.taints[] -Description:: - The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint. - -Type:: - `object` - -Required:: - - `effect` - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Required. The effect of the taint on pods that do not tolerate the taint. Valid effects are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Required. The taint key to be applied to a node. - -| `timeAdded` -| `string` -| TimeAdded represents the time at which the taint was added. It is only written for NoExecute taints. - -| `value` -| `string` -| The taint value corresponding to the taint key. - -|=== -..status -Description:: - MachineSetStatus defines the observed state of MachineSet - -Type:: - `object` - -Required:: - - `replicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| The number of available replicas (ready for at least minReadySeconds) for this MachineSet. - -| `errorMessage` -| `string` -| - -| `errorReason` -| `string` -| In the event that there is a terminal problem reconciling the replicas, both ErrorReason and ErrorMessage will be set. ErrorReason will be populated with a succinct value suitable for machine interpretation, while ErrorMessage will contain a more verbose string suitable for logging and human consumption. - These fields should not be set for transitive errors that a controller faces that are expected to be fixed automatically over time (like service outages), but instead indicate that something is fundamentally wrong with the MachineTemplate's spec or the configuration of the machine controller, and that manual intervention is required. Examples of terminal errors would be invalid combinations of settings in the spec, values that are unsupported by the machine controller, or the responsible machine controller itself being critically misconfigured. - Any transient errors that occur during the reconciliation of Machines can be added as events to the MachineSet object and/or logged in the controller's output. - -| `fullyLabeledReplicas` -| `integer` -| The number of replicas that have labels matching the labels of the machine template of the MachineSet. - -| `observedGeneration` -| `integer` -| ObservedGeneration reflects the generation of the most recently observed MachineSet. - -| `readyReplicas` -| `integer` -| The number of ready replicas for this MachineSet. A machine is considered ready when the node has been created and is "Ready". - -| `replicas` -| `integer` -| Replicas is the most recently observed number of replicas. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/machine.openshift.io/v1beta1/machinesets` -- `GET`: list objects of kind MachineSet -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinesets` -- `DELETE`: delete collection of MachineSet -- `GET`: list objects of kind MachineSet -- `POST`: create a MachineSet -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinesets/{name}` -- `DELETE`: delete a MachineSet -- `GET`: read the specified MachineSet -- `PATCH`: partially update the specified MachineSet -- `PUT`: replace the specified MachineSet -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinesets/{name}/scale` -- `GET`: read scale of the specified MachineSet -- `PATCH`: partially update scale of the specified MachineSet -- `PUT`: replace scale of the specified MachineSet -* `/apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinesets/{name}/status` -- `GET`: read status of the specified MachineSet -- `PATCH`: partially update status of the specified MachineSet -- `PUT`: replace status of the specified MachineSet - - -=== /apis/machine.openshift.io/v1beta1/machinesets - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind MachineSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machinesetlist-machine-openshift-io-v1beta1[`MachineSetList machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinesets - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#machinesetlist-machine-openshift-io-v1beta1[`MachineSetList machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 202 - Accepted -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinesets/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinesets/{name}/scale - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read scale of the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update scale of the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace scale of the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| 201 - Created -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/machine.openshift.io/v1beta1/namespaces/{namespace}/machinesets/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the MachineSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified MachineSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 201 - Created -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`MachineSet machine.openshift.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/metadata_apis/binding-core-v1.adoc b/rest_api/metadata_apis/binding-core-v1.adoc deleted file mode 100644 index 2a1bff5b006a..000000000000 --- a/rest_api/metadata_apis/binding-core-v1.adoc +++ /dev/null @@ -1,109 +0,0 @@ -[id="binding-core-v1"] -= Binding [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Binding ties one object to another; for example, a pod is bound to a node by a scheduler. Deprecated in 1.7, please use the bindings subresource of pods instead. - -Type:: - `object` - -Required:: - - `target` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `target` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| The target object that you want to bind to the standard object. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/namespaces/{namespace}/bindings` -- `POST`: create a Binding - - -=== /api/v1/namespaces/{namespace}/bindings - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a Binding - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/binding-core-v1.adoc#binding-core-v1[`Binding core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/binding-core-v1.adoc#binding-core-v1[`Binding core/v1`] -| 201 - Created -| xref:../metadata_apis/binding-core-v1.adoc#binding-core-v1[`Binding core/v1`] -| 202 - Accepted -| xref:../metadata_apis/binding-core-v1.adoc#binding-core-v1[`Binding core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/metadata_apis/componentstatus-core-v1.adoc b/rest_api/metadata_apis/componentstatus-core-v1.adoc deleted file mode 100644 index b553d6b378f9..000000000000 --- a/rest_api/metadata_apis/componentstatus-core-v1.adoc +++ /dev/null @@ -1,154 +0,0 @@ -[id="componentstatus-core-v1"] -= ComponentStatus [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ComponentStatus (and ComponentStatusList) holds the cluster validation info. Deprecated: This API is deprecated in v1.19+ - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `conditions` -| xref:../objects/index.adoc#componentcondition-core-v1[`array (ComponentCondition core/v1)`] -| List of component conditions observed - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/componentstatuses` -- `GET`: list objects of kind ComponentStatus -* `/api/v1/componentstatuses/{name}` -- `GET`: read the specified ComponentStatus - - -=== /api/v1/componentstatuses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ComponentStatus - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#componentstatuslist-core-v1[`ComponentStatusList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/componentstatuses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ComponentStatus -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ComponentStatus - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/componentstatus-core-v1.adoc#componentstatus-core-v1[`ComponentStatus core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/metadata_apis/configmap-core-v1.adoc b/rest_api/metadata_apis/configmap-core-v1.adoc deleted file mode 100644 index 2db55e11fe3e..000000000000 --- a/rest_api/metadata_apis/configmap-core-v1.adoc +++ /dev/null @@ -1,507 +0,0 @@ -[id="configmap-core-v1"] -= ConfigMap [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ConfigMap holds configuration data for pods to consume. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `binaryData` -| `object (string)` -| BinaryData contains the binary data. Each key must consist of alphanumeric characters, '-', '_' or '.'. BinaryData can contain byte sequences that are not in the UTF-8 range. The keys stored in BinaryData must not overlap with the ones in the Data field, this is enforced during validation process. Using this field will require 1.10+ apiserver and kubelet. - -| `data` -| `object (string)` -| Data contains the configuration data. Each key must consist of alphanumeric characters, '-', '_' or '.'. Values with non-UTF-8 byte sequences must use the BinaryData field. The keys stored in Data must not overlap with the keys in the BinaryData field, this is enforced during validation process. - -| `immutable` -| `boolean` -| Immutable, if set to true, ensures that data stored in the ConfigMap cannot be updated (only object metadata can be modified). If not set to true, the field can be modified at any time. Defaulted to nil. This is a beta field enabled by ImmutableEphemeralVolumes feature gate. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/configmaps` -- `GET`: list or watch objects of kind ConfigMap -* `/api/v1/namespaces/{namespace}/configmaps` -- `DELETE`: delete collection of ConfigMap -- `GET`: list or watch objects of kind ConfigMap -- `POST`: create a ConfigMap -* `/api/v1/namespaces/{namespace}/configmaps/{name}` -- `DELETE`: delete a ConfigMap -- `GET`: read the specified ConfigMap -- `PATCH`: partially update the specified ConfigMap -- `PUT`: replace the specified ConfigMap - - -=== /api/v1/configmaps - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ConfigMap - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#configmaplist-core-v1[`ConfigMapList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/configmaps - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ConfigMap - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ConfigMap - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#configmaplist-core-v1[`ConfigMapList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ConfigMap - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| 201 - Created -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| 202 - Accepted -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/configmaps/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ConfigMap -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ConfigMap - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ConfigMap - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ConfigMap - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ConfigMap - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| 201 - Created -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`ConfigMap core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/metadata_apis/controllerrevision-apps-v1.adoc b/rest_api/metadata_apis/controllerrevision-apps-v1.adoc deleted file mode 100644 index 459c4361c378..000000000000 --- a/rest_api/metadata_apis/controllerrevision-apps-v1.adoc +++ /dev/null @@ -1,505 +0,0 @@ -[id="controllerrevision-apps-v1"] -= ControllerRevision [apps/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ControllerRevision implements an immutable snapshot of state data. Clients are responsible for serializing and deserializing the objects that contain their internal state. Once a ControllerRevision has been successfully created, it can not be updated. The API Server will fail validation of all requests that attempt to mutate the Data field. ControllerRevisions may, however, be deleted. Note that, due to its use by both the DaemonSet and StatefulSet controllers for update and rollback, this object is beta. However, it may be subject to name and representation changes in future releases, and clients should not depend on its stability. It is primarily for internal use by controllers. - -Type:: - `object` - -Required:: - - `revision` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `data` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| Data is the serialized representation of the state. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `revision` -| `integer` -| Revision indicates the revision of the state represented by Data. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/apps/v1/controllerrevisions` -- `GET`: list or watch objects of kind ControllerRevision -* `/apis/apps/v1/namespaces/{namespace}/controllerrevisions` -- `DELETE`: delete collection of ControllerRevision -- `GET`: list or watch objects of kind ControllerRevision -- `POST`: create a ControllerRevision -* `/apis/apps/v1/namespaces/{namespace}/controllerrevisions/{name}` -- `DELETE`: delete a ControllerRevision -- `GET`: read the specified ControllerRevision -- `PATCH`: partially update the specified ControllerRevision -- `PUT`: replace the specified ControllerRevision - - -=== /apis/apps/v1/controllerrevisions - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ControllerRevision - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#controllerrevisionlist-apps-v1[`ControllerRevisionList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/controllerrevisions - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ControllerRevision - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ControllerRevision - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#controllerrevisionlist-apps-v1[`ControllerRevisionList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ControllerRevision - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| 201 - Created -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| 202 - Accepted -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/controllerrevisions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ControllerRevision -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ControllerRevision - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ControllerRevision - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ControllerRevision - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ControllerRevision - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| 201 - Created -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`ControllerRevision apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/metadata_apis/event-core-v1.adoc b/rest_api/metadata_apis/event-core-v1.adoc deleted file mode 100644 index 2f870dcf0244..000000000000 --- a/rest_api/metadata_apis/event-core-v1.adoc +++ /dev/null @@ -1,554 +0,0 @@ -[id="event-core-v1"] -= Event [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Event is a report of an event somewhere in the cluster. Events have a limited retention time and triggers and messages may evolve with time. Event consumers should not rely on the timing of an event with a given Reason reflecting a consistent underlying trigger, or the continued existence of events with that Reason. Events should be treated as informative, best-effort, supplemental data. - -Type:: - `object` - -Required:: - - `metadata` - - `involvedObject` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `action` -| `string` -| What action was taken/failed regarding to the Regarding object. - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `count` -| `integer` -| The number of times this event has occurred. - -| `eventTime` -| xref:../objects/index.adoc#microtime-meta-v1[`MicroTime meta/v1`] -| Time when this Event was first observed. - -| `firstTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The time at which the event was first recorded. (Time of server receipt is in TypeMeta.) - -| `involvedObject` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| The object that this event is about. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `lastTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The time at which the most recent occurrence of this event was recorded. - -| `message` -| `string` -| A human-readable description of the status of this operation. - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `reason` -| `string` -| This should be a short, machine understandable string that gives the reason for the transition into the object's current status. - -| `related` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| Optional secondary object for more complex actions. - -| `reportingComponent` -| `string` -| Name of the controller that emitted this Event, e.g. `kubernetes.io/kubelet`. - -| `reportingInstance` -| `string` -| ID of the controller instance, e.g. `kubelet-xyzf`. - -| `series` -| xref:../objects/index.adoc#eventseries-core-v1[`EventSeries core/v1`] -| Data about the Event series this event represents or nil if it's a singleton Event. - -| `source` -| xref:../objects/index.adoc#eventsource-core-v1[`EventSource core/v1`] -| The component reporting this event. Should be a short machine understandable string. - -| `type` -| `string` -| Type of this event (Normal, Warning), new types could be added in the future - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/events` -- `GET`: list or watch objects of kind Event -* `/api/v1/namespaces/{namespace}/events` -- `DELETE`: delete collection of Event -- `GET`: list or watch objects of kind Event -- `POST`: create an Event -* `/api/v1/namespaces/{namespace}/events/{name}` -- `DELETE`: delete an Event -- `GET`: read the specified Event -- `PATCH`: partially update the specified Event -- `PUT`: replace the specified Event - - -=== /api/v1/events - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Event - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#eventlist-core-v1[`EventList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/events - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#eventlist-core-v1[`EventList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| 201 - Created -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| 202 - Accepted -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/events/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Event -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| 201 - Created -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`Event core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/metadata_apis/event-events-k8s-io-v1.adoc b/rest_api/metadata_apis/event-events-k8s-io-v1.adoc deleted file mode 100644 index 98c260466559..000000000000 --- a/rest_api/metadata_apis/event-events-k8s-io-v1.adoc +++ /dev/null @@ -1,580 +0,0 @@ -[id="event-events-k8s-io-v1"] -= Event [events.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Event is a report of an event somewhere in the cluster. It generally denotes some state change in the system. Events have a limited retention time and triggers and messages may evolve with time. Event consumers should not rely on the timing of an event with a given Reason reflecting a consistent underlying trigger, or the continued existence of events with that Reason. Events should be treated as informative, best-effort, supplemental data. - -Type:: - `object` - -Required:: - - `metadata` - - `eventTime` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `action` -| `string` -| action is what action was taken/failed regarding to the regarding object. It is machine-readable. This field cannot be empty for new Events and it can have at most 128 characters. - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `deprecatedCount` -| `integer` -| deprecatedCount is the deprecated field assuring backward compatibility with core.v1 Event type. - -| `deprecatedFirstTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| deprecatedFirstTimestamp is the deprecated field assuring backward compatibility with core.v1 Event type. - -| `deprecatedLastTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| deprecatedLastTimestamp is the deprecated field assuring backward compatibility with core.v1 Event type. - -| `deprecatedSource` -| xref:../objects/index.adoc#eventsource-core-v1[`EventSource core/v1`] -| deprecatedSource is the deprecated field assuring backward compatibility with core.v1 Event type. - -| `eventTime` -| xref:../objects/index.adoc#microtime-meta-v1[`MicroTime meta/v1`] -| eventTime is the time when this Event was first observed. It is required. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `note` -| `string` -| note is a human-readable description of the status of this operation. Maximal length of the note is 1kB, but libraries should be prepared to handle values up to 64kB. - -| `reason` -| `string` -| reason is why the action was taken. It is human-readable. This field cannot be empty for new Events and it can have at most 128 characters. - -| `regarding` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| regarding contains the object this Event is about. In most cases it's an Object reporting controller implements, e.g. ReplicaSetController implements ReplicaSets and this event is emitted because it acts on some changes in a ReplicaSet object. - -| `related` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| related is the optional secondary object for more complex actions. E.g. when regarding object triggers a creation or deletion of related object. - -| `reportingController` -| `string` -| reportingController is the name of the controller that emitted this Event, e.g. `kubernetes.io/kubelet`. This field cannot be empty for new Events. - -| `reportingInstance` -| `string` -| reportingInstance is the ID of the controller instance, e.g. `kubelet-xyzf`. This field cannot be empty for new Events and it can have at most 128 characters. - -| `series` -| `object` -| EventSeries contain information on series of events, i.e. thing that was/is happening continuously for some time. How often to update the EventSeries is up to the event reporters. The default event reporter in "k8s.io/client-go/tools/events/event_broadcaster.go" shows how this struct is updated on heartbeats and can guide customized reporter implementations. - -| `type` -| `string` -| type is the type of this event (Normal, Warning), new types could be added in the future. It is machine-readable. This field cannot be empty for new Events. - -|=== -..series -Description:: - EventSeries contain information on series of events, i.e. thing that was/is happening continuously for some time. How often to update the EventSeries is up to the event reporters. The default event reporter in "k8s.io/client-go/tools/events/event_broadcaster.go" shows how this struct is updated on heartbeats and can guide customized reporter implementations. - -Type:: - `object` - -Required:: - - `count` - - `lastObservedTime` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `count` -| `integer` -| count is the number of occurrences in this series up to the last heartbeat time. - -| `lastObservedTime` -| xref:../objects/index.adoc#microtime-meta-v1[`MicroTime meta/v1`] -| lastObservedTime is the time when last Event from the series was seen before last heartbeat. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/events.k8s.io/v1/events` -- `GET`: list or watch objects of kind Event -* `/apis/events.k8s.io/v1/namespaces/{namespace}/events` -- `DELETE`: delete collection of Event -- `GET`: list or watch objects of kind Event -- `POST`: create an Event -* `/apis/events.k8s.io/v1/namespaces/{namespace}/events/{name}` -- `DELETE`: delete an Event -- `GET`: read the specified Event -- `PATCH`: partially update the specified Event -- `PUT`: replace the specified Event - - -=== /apis/events.k8s.io/v1/events - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Event - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#eventlist-events-k8s-io-v1[`EventList events.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/events.k8s.io/v1/namespaces/{namespace}/events - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#eventlist-events-k8s-io-v1[`EventList events.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| 201 - Created -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| 202 - Accepted -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/events.k8s.io/v1/namespaces/{namespace}/events/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Event -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Event - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| 201 - Created -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`Event events.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/metadata_apis/lease-coordination-k8s-io-v1.adoc b/rest_api/metadata_apis/lease-coordination-k8s-io-v1.adoc deleted file mode 100644 index 1e67bab547d5..000000000000 --- a/rest_api/metadata_apis/lease-coordination-k8s-io-v1.adoc +++ /dev/null @@ -1,534 +0,0 @@ -[id="lease-coordination-k8s-io-v1"] -= Lease [coordination.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Lease defines a lease concept. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| LeaseSpec is a specification of a Lease. - -|=== -..spec -Description:: - LeaseSpec is a specification of a Lease. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `acquireTime` -| xref:../objects/index.adoc#microtime-meta-v1[`MicroTime meta/v1`] -| acquireTime is a time when the current lease was acquired. - -| `holderIdentity` -| `string` -| holderIdentity contains the identity of the holder of a current lease. - -| `leaseDurationSeconds` -| `integer` -| leaseDurationSeconds is a duration that candidates for a lease need to wait to force acquire it. This is measure against time of last observed RenewTime. - -| `leaseTransitions` -| `integer` -| leaseTransitions is the number of transitions of a lease between holders. - -| `renewTime` -| xref:../objects/index.adoc#microtime-meta-v1[`MicroTime meta/v1`] -| renewTime is a time when the current holder of a lease has last updated the lease. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/coordination.k8s.io/v1/leases` -- `GET`: list or watch objects of kind Lease -* `/apis/coordination.k8s.io/v1/namespaces/{namespace}/leases` -- `DELETE`: delete collection of Lease -- `GET`: list or watch objects of kind Lease -- `POST`: create a Lease -* `/apis/coordination.k8s.io/v1/namespaces/{namespace}/leases/{name}` -- `DELETE`: delete a Lease -- `GET`: read the specified Lease -- `PATCH`: partially update the specified Lease -- `PUT`: replace the specified Lease - - -=== /apis/coordination.k8s.io/v1/leases - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Lease - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#leaselist-coordination-k8s-io-v1[`LeaseList coordination.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/coordination.k8s.io/v1/namespaces/{namespace}/leases - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Lease - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Lease - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#leaselist-coordination-k8s-io-v1[`LeaseList coordination.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Lease - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| 201 - Created -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| 202 - Accepted -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/coordination.k8s.io/v1/namespaces/{namespace}/leases/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Lease -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Lease - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Lease - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Lease - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Lease - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| 201 - Created -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`Lease coordination.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/metadata_apis/metadata-apis-index.adoc b/rest_api/metadata_apis/metadata-apis-index.adoc deleted file mode 100644 index 225b8041ab7f..000000000000 --- a/rest_api/metadata_apis/metadata-apis-index.adoc +++ /dev/null @@ -1,72 +0,0 @@ -[id="metadata-apis"] -= Metadata APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== Binding [core/v1] - -Description:: - Binding ties one object to another; for example, a pod is bound to a node by a scheduler. Deprecated in 1.7, please use the bindings subresource of pods instead. - -Type:: - `object` - -== ComponentStatus [core/v1] - -Description:: - ComponentStatus (and ComponentStatusList) holds the cluster validation info. Deprecated: This API is deprecated in v1.19+ - -Type:: - `object` - -== ConfigMap [core/v1] - -Description:: - ConfigMap holds configuration data for pods to consume. - -Type:: - `object` - -== ControllerRevision [apps/v1] - -Description:: - ControllerRevision implements an immutable snapshot of state data. Clients are responsible for serializing and deserializing the objects that contain their internal state. Once a ControllerRevision has been successfully created, it can not be updated. The API Server will fail validation of all requests that attempt to mutate the Data field. ControllerRevisions may, however, be deleted. Note that, due to its use by both the DaemonSet and StatefulSet controllers for update and rollback, this object is beta. However, it may be subject to name and representation changes in future releases, and clients should not depend on its stability. It is primarily for internal use by controllers. - -Type:: - `object` - -== Event [events.k8s.io/v1] - -Description:: - Event is a report of an event somewhere in the cluster. It generally denotes some state change in the system. Events have a limited retention time and triggers and messages may evolve with time. Event consumers should not rely on the timing of an event with a given Reason reflecting a consistent underlying trigger, or the continued existence of events with that Reason. Events should be treated as informative, best-effort, supplemental data. - -Type:: - `object` - -== Event [core/v1] - -Description:: - Event is a report of an event somewhere in the cluster. Events have a limited retention time and triggers and messages may evolve with time. Event consumers should not rely on the timing of an event with a given Reason reflecting a consistent underlying trigger, or the continued existence of events with that Reason. Events should be treated as informative, best-effort, supplemental data. - -Type:: - `object` - -== Lease [coordination.k8s.io/v1] - -Description:: - Lease defines a lease concept. - -Type:: - `object` - -== Namespace [core/v1] - -Description:: - Namespace provides a scope for Names. Use of multiple namespaces is optional. - -Type:: - `object` - diff --git a/rest_api/metadata_apis/namespace-core-v1.adoc b/rest_api/metadata_apis/namespace-core-v1.adoc deleted file mode 100644 index 0406bfeb696e..000000000000 --- a/rest_api/metadata_apis/namespace-core-v1.adoc +++ /dev/null @@ -1,574 +0,0 @@ -[id="namespace-core-v1"] -= Namespace [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Namespace provides a scope for Names. Use of multiple namespaces is optional. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| NamespaceSpec describes the attributes on a Namespace. - -| `status` -| `object` -| NamespaceStatus is information about the current status of a Namespace. - -|=== -..spec -Description:: - NamespaceSpec describes the attributes on a Namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `finalizers` -| `array (string)` -| Finalizers is an opaque list of values that must be empty to permanently remove object from storage. More info: https://kubernetes.io/docs/tasks/administer-cluster/namespaces/ - -|=== -..status -Description:: - NamespaceStatus is information about the current status of a Namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| xref:../objects/index.adoc#namespacecondition-core-v1[`array (NamespaceCondition core/v1)`] -| Represents the latest available observations of a namespace's current state. - -| `phase` -| `string` -| Phase is the current lifecycle phase of the namespace. More info: https://kubernetes.io/docs/tasks/administer-cluster/namespaces/ - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/namespaces` -- `GET`: list or watch objects of kind Namespace -- `POST`: create a Namespace -* `/api/v1/namespaces/{name}` -- `DELETE`: delete a Namespace -- `GET`: read the specified Namespace -- `PATCH`: partially update the specified Namespace -- `PUT`: replace the specified Namespace -* `/api/v1/namespaces/{name}/status` -- `GET`: read status of the specified Namespace -- `PATCH`: partially update status of the specified Namespace -- `PUT`: replace status of the specified Namespace -* `/api/v1/namespaces/{name}/finalize` -- `PUT`: replace finalize of the specified Namespace - - -=== /api/v1/namespaces - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Namespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#namespacelist-core-v1[`NamespaceList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Namespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 201 - Created -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 202 - Accepted -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Namespace -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Namespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Namespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Namespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Namespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 201 - Created -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Namespace -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Namespace - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Namespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Namespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 201 - Created -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{name}/finalize - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Namespace -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `PUT` - -Description:: - replace finalize of the specified Namespace - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 201 - Created -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`Namespace core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc deleted file mode 100644 index b2415f73bb24..000000000000 --- a/rest_api/monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc +++ /dev/null @@ -1,7357 +0,0 @@ -[id="alertmanager-monitoring-coreos-com-v1"] -= Alertmanager [monitoring.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Alertmanager describes an Alertmanager cluster. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of the desired behavior of the Alertmanager cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -| `status` -| `object` -| Most recent observed status of the Alertmanager cluster. Read-only. Not included when requesting from the apiserver, only from the Prometheus Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -|=== -..spec -Description:: - Specification of the desired behavior of the Alertmanager cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalPeers` -| `array (string)` -| AdditionalPeers allows injecting a set of additional Alertmanagers to peer with to form a highly available cluster. - -| `affinity` -| `object` -| If specified, the pod's scheduling constraints. - -| `alertmanagerConfigNamespaceSelector` -| `object` -| Namespaces to be selected for AlertmanagerConfig discovery. If nil, only check own namespace. - -| `alertmanagerConfigSelector` -| `object` -| AlertmanagerConfigs to be selected for to merge and configure Alertmanager with. - -| `baseImage` -| `string` -| Base image that is used to deploy pods, without tag. Deprecated: use 'image' instead - -| `clusterAdvertiseAddress` -| `string` -| ClusterAdvertiseAddress is the explicit address to advertise in cluster. Needs to be provided for non RFC1918 [1] (public) addresses. [1] RFC1918: https://tools.ietf.org/html/rfc1918 - -| `clusterGossipInterval` -| `string` -| Interval between gossip attempts. - -| `clusterPeerTimeout` -| `string` -| Timeout for cluster peering. - -| `clusterPushpullInterval` -| `string` -| Interval between pushpull attempts. - -| `configMaps` -| `array (string)` -| ConfigMaps is a list of ConfigMaps in the same namespace as the Alertmanager object, which shall be mounted into the Alertmanager Pods. The ConfigMaps are mounted into /etc/alertmanager/configmaps/<configmap-name>. - -| `configSecret` -| `string` -| ConfigSecret is the name of a Kubernetes Secret in the same namespace as the Alertmanager object, which contains configuration for this Alertmanager instance. Defaults to 'alertmanager-<alertmanager-name>' The secret is mounted into /etc/alertmanager/config. - -| `containers` -| `array` -| Containers allows injecting additional containers. This is meant to allow adding an authentication proxy to an Alertmanager pod. Containers described here modify an operator generated container if they share the same name and modifications are done via a strategic merge patch. The current container names are: `alertmanager` and `config-reloader`. Overriding containers is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -| `containers[]` -| `object` -| A single application container that you want to run within a pod. - -| `externalUrl` -| `string` -| The external URL the Alertmanager instances will be available under. This is necessary to generate correct URLs. This is necessary if Alertmanager is not served from root of a DNS name. - -| `forceEnableClusterMode` -| `boolean` -| ForceEnableClusterMode ensures Alertmanager does not deactivate the cluster mode when running with a single replica. Use case is e.g. spanning an Alertmanager cluster across Kubernetes clusters with a single replica in each. - -| `image` -| `string` -| Image if specified has precedence over baseImage, tag and sha combinations. Specifying the version is still necessary to ensure the Prometheus Operator knows what version of Alertmanager is being configured. - -| `imagePullSecrets` -| `array` -| An optional list of references to secrets in the same namespace to use for pulling prometheus and alertmanager images from registries see http://kubernetes.io/docs/user-guide/images#specifying-imagepullsecrets-on-a-pod - -| `imagePullSecrets[]` -| `object` -| LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -| `initContainers` -| `array` -| InitContainers allows adding initContainers to the pod definition. Those can be used to e.g. fetch secrets for injection into the Alertmanager configuration from external sources. Any errors during the execution of an initContainer will lead to a restart of the Pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ Using initContainers for any use case other then secret fetching is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -| `initContainers[]` -| `object` -| A single application container that you want to run within a pod. - -| `listenLocal` -| `boolean` -| ListenLocal makes the Alertmanager server listen on loopback, so that it does not bind against the Pod IP. Note this is only for the Alertmanager UI, not the gossip communication. - -| `logFormat` -| `string` -| Log format for Alertmanager to be configured with. - -| `logLevel` -| `string` -| Log level for Alertmanager to be configured with. - -| `nodeSelector` -| `object (string)` -| Define which Nodes the Pods are scheduled on. - -| `paused` -| `boolean` -| If set to true all actions on the underlying managed objects are not goint to be performed, except for delete actions. - -| `podMetadata` -| `object` -| PodMetadata configures Labels and Annotations which are propagated to the alertmanager pods. - -| `portName` -| `string` -| Port name used for the pods and governing service. This defaults to web - -| `priorityClassName` -| `string` -| Priority class assigned to the Pods - -| `replicas` -| `integer` -| Size is the expected size of the alertmanager cluster. The controller will eventually make the size of the running cluster equal to the expected size. - -| `resources` -| `object` -| Define resources requests and limits for single Pods. - -| `retention` -| `string` -| Time duration Alertmanager shall retain data for. Default is '120h', and must match the regular expression `[0-9]+(ms\|s\|m\|h)` (milliseconds seconds minutes hours). - -| `routePrefix` -| `string` -| The route prefix Alertmanager registers HTTP handlers for. This is useful, if using ExternalURL and a proxy is rewriting HTTP routes of a request, and the actual ExternalURL is still true, but the server serves requests under a different route prefix. For example for use with `kubectl proxy`. - -| `secrets` -| `array (string)` -| Secrets is a list of Secrets in the same namespace as the Alertmanager object, which shall be mounted into the Alertmanager Pods. The Secrets are mounted into /etc/alertmanager/secrets/<secret-name>. - -| `securityContext` -| `object` -| SecurityContext holds pod-level security attributes and common container settings. This defaults to the default PodSecurityContext. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the name of the ServiceAccount to use to run the Prometheus Pods. - -| `sha` -| `string` -| SHA of Alertmanager container image to be deployed. Defaults to the value of `version`. Similar to a tag, but the SHA explicitly deploys an immutable container image. Version and Tag are ignored if SHA is set. Deprecated: use 'image' instead. The image digest can be specified as part of the image URL. - -| `storage` -| `object` -| Storage is the definition of how storage will be used by the Alertmanager instances. - -| `tag` -| `string` -| Tag of Alertmanager container image to be deployed. Defaults to the value of `version`. Version is ignored if Tag is set. Deprecated: use 'image' instead. The image tag can be specified as part of the image URL. - -| `tolerations` -| `array` -| If specified, the pod's tolerations. - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -| `topologySpreadConstraints` -| `array` -| If specified, the pod's topology spread constraints. - -| `topologySpreadConstraints[]` -| `object` -| TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -| `version` -| `string` -| Version the cluster should be on. - -| `volumeMounts` -| `array` -| VolumeMounts allows configuration of additional VolumeMounts on the output StatefulSet definition. VolumeMounts specified will be appended to other VolumeMounts in the alertmanager container, that are generated as a result of StorageSpec objects. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `volumes` -| `array` -| Volumes allows configuration of additional volumes on the output StatefulSet definition. Volumes specified will be appended to other volumes that are generated as a result of StorageSpec objects. - -| `volumes[]` -| `object` -| Volume represents a named volume in a pod that may be accessed by any container in the pod. - -|=== -..spec.affinity -Description:: - If specified, the pod's scheduling constraints. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeAffinity` -| `object` -| Describes node affinity scheduling rules for the pod. - -| `podAffinity` -| `object` -| Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -| `podAntiAffinity` -| `object` -| Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -|=== -..spec.affinity.nodeAffinity -Description:: - Describes node affinity scheduling rules for the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `object` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -Type:: - `object` - -Required:: - - `preference` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preference` -| `object` -| A node selector term, associated with the corresponding weight. - -| `weight` -| `integer` -| Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference -Description:: - A node selector term, associated with the corresponding weight. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -Type:: - `object` - -Required:: - - `nodeSelectorTerms` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelectorTerms` -| `array` -| Required. A list of node selector terms. The terms are ORed. - -| `nodeSelectorTerms[]` -| `object` -| A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms -Description:: - Required. A list of node selector terms. The terms are ORed. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[] -Description:: - A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity -Description:: - Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity -Description:: - Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.alertmanagerConfigNamespaceSelector -Description:: - Namespaces to be selected for AlertmanagerConfig discovery. If nil, only check own namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.alertmanagerConfigNamespaceSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.alertmanagerConfigNamespaceSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.alertmanagerConfigSelector -Description:: - AlertmanagerConfigs to be selected for to merge and configure Alertmanager with. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.alertmanagerConfigSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.alertmanagerConfigSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.containers -Description:: - Containers allows injecting additional containers. This is meant to allow adding an authentication proxy to an Alertmanager pod. Containers described here modify an operator generated container if they share the same name and modifications are done via a strategic merge patch. The current container names are: `alertmanager` and `config-reloader`. Overriding containers is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -Type:: - `array` - - - - -..spec.containers[] -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| `object` -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| `array` -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| `object` -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| `object` -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| `object` -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.containers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.containers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.containers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.containers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.containers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.containers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.containers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.containers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.containers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.containers[].lifecycle -Description:: - Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.containers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.containers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.containers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].livenessProbe -Description:: - Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].ports -Description:: - List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.containers[].readinessProbe -Description:: - Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].resources -Description:: - Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.containers[].securityContext -Description:: - Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.containers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.containers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.containers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.containers[].startupProbe -Description:: - StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.containers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.containers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.imagePullSecrets -Description:: - An optional list of references to secrets in the same namespace to use for pulling prometheus and alertmanager images from registries see http://kubernetes.io/docs/user-guide/images#specifying-imagepullsecrets-on-a-pod - -Type:: - `array` - - - - -..spec.imagePullSecrets[] -Description:: - LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.initContainers -Description:: - InitContainers allows adding initContainers to the pod definition. Those can be used to e.g. fetch secrets for injection into the Alertmanager configuration from external sources. Any errors during the execution of an initContainer will lead to a restart of the Pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ Using initContainers for any use case other then secret fetching is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -Type:: - `array` - - - - -..spec.initContainers[] -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| `object` -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| `array` -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| `object` -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| `object` -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| `object` -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.initContainers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.initContainers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.initContainers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.initContainers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.initContainers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.initContainers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.initContainers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.initContainers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.initContainers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.initContainers[].lifecycle -Description:: - Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.initContainers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.initContainers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.initContainers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].livenessProbe -Description:: - Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].ports -Description:: - List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.initContainers[].readinessProbe -Description:: - Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].resources -Description:: - Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.initContainers[].securityContext -Description:: - Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.initContainers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.initContainers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.initContainers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.initContainers[].startupProbe -Description:: - StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.initContainers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.initContainers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.podMetadata -Description:: - PodMetadata configures Labels and Annotations which are propagated to the alertmanager pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -|=== -..spec.resources -Description:: - Define resources requests and limits for single Pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.securityContext -Description:: - SecurityContext holds pod-level security attributes and common container settings. This defaults to the default PodSecurityContext. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsGroup` -| `integer` -| A special supplemental group that applies to all containers in a pod. Some volume types allow the Kubelet to change the ownership of that volume to be owned by the pod: - 1. The owning GID will be the FSGroup 2. The setgid bit is set (new files created in the volume will be owned by FSGroup) 3. The permission bits are OR'd with rw-rw---- - If unset, the Kubelet will not modify the ownership and permissions of any volume. - -| `fsGroupChangePolicy` -| `string` -| fsGroupChangePolicy defines behavior of changing ownership and permission of the volume before being exposed inside Pod. This field will only apply to volume types which support fsGroup based ownership(and permissions). It will have no effect on ephemeral volume types such as: secret, configmaps and emptydir. Valid values are "OnRootMismatch" and "Always". If not specified defaults to "Always". - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `supplementalGroups` -| `array (integer)` -| A list of groups applied to the first process run in each container, in addition to the container's primary GID. If unspecified, no groups will be added to any container. - -| `sysctls` -| `array` -| Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -| `sysctls[]` -| `object` -| Sysctl defines a kernel parameter to be set - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.securityContext.sysctls -Description:: - Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -Type:: - `array` - - - - -..spec.securityContext.sysctls[] -Description:: - Sysctl defines a kernel parameter to be set - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of a property to set - -| `value` -| `string` -| Value of a property to set - -|=== -..spec.securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.storage -Description:: - Storage is the definition of how storage will be used by the Alertmanager instances. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `disableMountSubPath` -| `boolean` -| Deprecated: subPath usage will be disabled by default in a future release, this option will become unnecessary. DisableMountSubPath allows to remove any subPath usage in volume mounts. - -| `emptyDir` -| `object` -| EmptyDirVolumeSource to be used by the Prometheus StatefulSets. If specified, used in place of any volumeClaimTemplate. More info: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir - -| `volumeClaimTemplate` -| `object` -| A PVC spec to be used by the Prometheus StatefulSets. - -|=== -..spec.storage.emptyDir -Description:: - EmptyDirVolumeSource to be used by the Prometheus StatefulSets. If specified, used in place of any volumeClaimTemplate. More info: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| `integer-or-string` -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== -..spec.storage.volumeClaimTemplate -Description:: - A PVC spec to be used by the Prometheus StatefulSets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| `object` -| EmbeddedMetadata contains metadata relevant to an EmbeddedResource. - -| `spec` -| `object` -| Spec defines the desired characteristics of a volume requested by a pod author. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `status` -| `object` -| Status represents the current information/status of a persistent volume claim. Read-only. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -|=== -..spec.storage.volumeClaimTemplate.metadata -Description:: - EmbeddedMetadata contains metadata relevant to an EmbeddedResource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -|=== -..spec.storage.volumeClaimTemplate.spec -Description:: - Spec defines the desired characteristics of a volume requested by a pod author. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `dataSource` -| `object` -| This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot - Beta) * An existing PVC (PersistentVolumeClaim) * An existing custom resource/object that implements data population (Alpha) In order to use VolumeSnapshot object types, the appropriate feature gate must be enabled (VolumeSnapshotDataSource or AnyVolumeDataSource) If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. If the specified data source is not supported, the volume will not be created and the failure will be reported as an event. In the future, we plan to support more data source types and the behavior of the provisioner may change. - -| `resources` -| `object` -| Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -| `selector` -| `object` -| A label query over volumes to consider for binding. - -| `storageClassName` -| `string` -| Name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 - -| `volumeMode` -| `string` -| volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. - -| `volumeName` -| `string` -| VolumeName is the binding reference to the PersistentVolume backing this claim. - -|=== -..spec.storage.volumeClaimTemplate.spec.dataSource -Description:: - This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot - Beta) * An existing PVC (PersistentVolumeClaim) * An existing custom resource/object that implements data population (Alpha) In order to use VolumeSnapshot object types, the appropriate feature gate must be enabled (VolumeSnapshotDataSource or AnyVolumeDataSource) If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. If the specified data source is not supported, the volume will not be created and the failure will be reported as an event. In the future, we plan to support more data source types and the behavior of the provisioner may change. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required. - -| `kind` -| `string` -| Kind is the type of resource being referenced - -| `name` -| `string` -| Name is the name of resource being referenced - -|=== -..spec.storage.volumeClaimTemplate.spec.resources -Description:: - Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.storage.volumeClaimTemplate.spec.selector -Description:: - A label query over volumes to consider for binding. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.storage.volumeClaimTemplate.spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.storage.volumeClaimTemplate.spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.storage.volumeClaimTemplate.status -Description:: - Status represents the current information/status of a persistent volume claim. Read-only. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the actual access modes the volume backing the PVC has. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `capacity` -| `integer-or-string` -| Represents the actual resources of the underlying volume. - -| `conditions` -| `array` -| Current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'. - -| `conditions[]` -| `object` -| PersistentVolumeClaimCondition contails details about state of pvc - -| `phase` -| `string` -| Phase represents the current phase of PersistentVolumeClaim. - -|=== -..spec.storage.volumeClaimTemplate.status.conditions -Description:: - Current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'. - -Type:: - `array` - - - - -..spec.storage.volumeClaimTemplate.status.conditions[] -Description:: - PersistentVolumeClaimCondition contails details about state of pvc - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| `string` -| Last time we probed the condition. - -| `lastTransitionTime` -| `string` -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| Human-readable message indicating details about last transition. - -| `reason` -| `string` -| Unique, this should be a short, machine understandable string that gives the reason for condition's last transition. If it reports "ResizeStarted" that means the underlying persistent volume is being resized. - -| `status` -| `string` -| - -| `type` -| `string` -| PersistentVolumeClaimConditionType is a valid value of PersistentVolumeClaimCondition.Type - -|=== -..spec.tolerations -Description:: - If specified, the pod's tolerations. - -Type:: - `array` - - - - -..spec.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== -..spec.topologySpreadConstraints -Description:: - If specified, the pod's topology spread constraints. - -Type:: - `array` - - - - -..spec.topologySpreadConstraints[] -Description:: - TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -Type:: - `object` - -Required:: - - `maxSkew` - - `topologyKey` - - `whenUnsatisfiable` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -| `maxSkew` -| `integer` -| MaxSkew describes the degree to which pods may be unevenly distributed. It's the maximum permitted difference between the number of matching pods in any two topology domains of a given topology type. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: \| zone1 \| zone2 \| zone3 \| \| P \| P \| \| - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. It's a required field. Default value is 1 and 0 is not allowed. - -| `topologyKey` -| `string` -| TopologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. We consider each <key, value> as a "bucket", and try to put balanced number of pods into each bucket. It's a required field. - -| `whenUnsatisfiable` -| `string` -| WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it - ScheduleAnyway tells the scheduler to still schedule it It's considered as "Unsatisfiable" if and only if placing incoming pod on any topology violates "MaxSkew". For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: \| zone1 \| zone2 \| zone3 \| \| P P P \| P \| P \| If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field. - -|=== -..spec.topologySpreadConstraints[].labelSelector -Description:: - LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.topologySpreadConstraints[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.topologySpreadConstraints[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.volumeMounts -Description:: - VolumeMounts allows configuration of additional VolumeMounts on the output StatefulSet definition. VolumeMounts specified will be appended to other VolumeMounts in the alertmanager container, that are generated as a result of StorageSpec objects. - -Type:: - `array` - - - - -..spec.volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.volumes -Description:: - Volumes allows configuration of additional volumes on the output StatefulSet definition. Volumes specified will be appended to other volumes that are generated as a result of StorageSpec objects. - -Type:: - `array` - - - - -..spec.volumes[] -Description:: - Volume represents a named volume in a pod that may be accessed by any container in the pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `awsElasticBlockStore` -| `object` -| AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `azureDisk` -| `object` -| AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -| `azureFile` -| `object` -| AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -| `cephfs` -| `object` -| CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -| `cinder` -| `object` -| Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `configMap` -| `object` -| ConfigMap represents a configMap that should populate this volume - -| `csi` -| `object` -| CSI (Container Storage Interface) represents storage that is handled by an external CSI driver (Alpha feature). - -| `downwardAPI` -| `object` -| DownwardAPI represents downward API about the pod that should populate this volume - -| `emptyDir` -| `object` -| EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `fc` -| `object` -| FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -| `flexVolume` -| `object` -| FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -| `flocker` -| `object` -| Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -| `gcePersistentDisk` -| `object` -| GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `gitRepo` -| `object` -| GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -| `glusterfs` -| `object` -| Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -| `hostPath` -| `object` -| HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -| `iscsi` -| `object` -| ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -| `name` -| `string` -| Volume's name. Must be a DNS_LABEL and unique within the pod. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `nfs` -| `object` -| NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `persistentVolumeClaim` -| `object` -| PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `photonPersistentDisk` -| `object` -| PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -| `portworxVolume` -| `object` -| PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -| `projected` -| `object` -| Items for all in one resources secrets, configmaps, and downward API - -| `quobyte` -| `object` -| Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -| `rbd` -| `object` -| RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -| `scaleIO` -| `object` -| ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -| `secret` -| `object` -| Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -| `storageos` -| `object` -| StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -| `vsphereVolume` -| `object` -| VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -|=== -..spec.volumes[].awsElasticBlockStore -Description:: - AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). - -| `readOnly` -| `boolean` -| Specify "true" to force and set the ReadOnly property in VolumeMounts to "true". If omitted, the default is "false". More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `volumeID` -| `string` -| Unique ID of the persistent disk resource in AWS (Amazon EBS volume). More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -|=== -..spec.volumes[].azureDisk -Description:: - AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `diskName` - - `diskURI` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cachingMode` -| `string` -| Host Caching mode: None, Read Only, Read Write. - -| `diskName` -| `string` -| The Name of the data disk in the blob storage - -| `diskURI` -| `string` -| The URI the data disk in the blob storage - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `kind` -| `string` -| Expected values Shared: multiple blob disks per storage account Dedicated: single blob disk per storage account Managed: azure managed data disk (only in managed availability set). defaults to shared - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -|=== -..spec.volumes[].azureFile -Description:: - AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `secretName` - - `shareName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretName` -| `string` -| the name of secret that contains Azure Storage Account Name and Key - -| `shareName` -| `string` -| Share Name - -|=== -..spec.volumes[].cephfs -Description:: - CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `monitors` -| `array (string)` -| Required: Monitors is a collection of Ceph monitors More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `path` -| `string` -| Optional: Used as the mounted root, rather than the full Ceph tree, default is / - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretFile` -| `string` -| Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `user` -| `string` -| Optional: User is the rados user name, default is admin More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -|=== -..spec.volumes[].cephfs.secretRef -Description:: - Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].cinder -Description:: - Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `secretRef` -| `object` -| Optional: points to a secret object containing parameters used to connect to OpenStack. - -| `volumeID` -| `string` -| volume id used to identify the volume in cinder. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -|=== -..spec.volumes[].cinder.secretRef -Description:: - Optional: points to a secret object containing parameters used to connect to OpenStack. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].configMap -Description:: - ConfigMap represents a configMap that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.volumes[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].csi -Description:: - CSI (Container Storage Interface) represents storage that is handled by an external CSI driver (Alpha feature). - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the CSI driver that handles this volume. Consult with your admin for the correct name as registered in the cluster. - -| `fsType` -| `string` -| Filesystem type to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. - -| `nodePublishSecretRef` -| `object` -| NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeAttributes` -| `object (string)` -| VolumeAttributes stores driver-specific properties that are passed to the CSI driver. Consult your driver's documentation for supported values. - -|=== -..spec.volumes[].csi.nodePublishSecretRef -Description:: - NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].downwardAPI -Description:: - DownwardAPI represents downward API about the pod that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| Items is a list of downward API volume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.volumes[].downwardAPI.items -Description:: - Items is a list of downward API volume file - -Type:: - `array` - - - - -..spec.volumes[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.volumes[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.volumes[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.volumes[].emptyDir -Description:: - EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| `integer-or-string` -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== -..spec.volumes[].fc -Description:: - FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. TODO: how do we prevent errors in the filesystem from compromising the machine - -| `lun` -| `integer` -| Optional: FC target lun number - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `targetWWNs` -| `array (string)` -| Optional: FC target worldwide names (WWNs) - -| `wwids` -| `array (string)` -| Optional: FC volume world wide identifiers (wwids) Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously. - -|=== -..spec.volumes[].flexVolume -Description:: - FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the driver to use for this volume. - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script. - -| `options` -| `object (string)` -| Optional: Extra command options if any. - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -|=== -..spec.volumes[].flexVolume.secretRef -Description:: - Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].flocker -Description:: - Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `datasetName` -| `string` -| Name of the dataset stored as metadata -> name on the dataset for Flocker should be considered as deprecated - -| `datasetUUID` -| `string` -| UUID of the dataset. This is unique identifier of a Flocker dataset - -|=== -..spec.volumes[].gcePersistentDisk -Description:: - GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -Type:: - `object` - -Required:: - - `pdName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `pdName` -| `string` -| Unique name of the PD resource in GCE. Used to identify the disk in GCE. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -|=== -..spec.volumes[].gitRepo -Description:: - GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -Type:: - `object` - -Required:: - - `repository` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `directory` -| `string` -| Target directory name. Must not contain or start with '..'. If '.' is supplied, the volume directory will be the git repository. Otherwise, if specified, the volume will contain the git repository in the subdirectory with the given name. - -| `repository` -| `string` -| Repository URL - -| `revision` -| `string` -| Commit hash for the specified revision. - -|=== -..spec.volumes[].glusterfs -Description:: - Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -Type:: - `object` - -Required:: - - `endpoints` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `endpoints` -| `string` -| EndpointsName is the endpoint name that details Glusterfs topology. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `path` -| `string` -| Path is the Glusterfs volume path. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `readOnly` -| `boolean` -| ReadOnly here will force the Glusterfs volume to be mounted with read-only permissions. Defaults to false. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -|=== -..spec.volumes[].hostPath -Description:: - HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path of the directory on the host. If the path is a symlink, it will follow the link to the real path. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `type` -| `string` -| Type for HostPath Volume Defaults to "" More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -|=== -..spec.volumes[].iscsi -Description:: - ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -Type:: - `object` - -Required:: - - `iqn` - - `lun` - - `targetPortal` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `chapAuthDiscovery` -| `boolean` -| whether support iSCSI Discovery CHAP authentication - -| `chapAuthSession` -| `boolean` -| whether support iSCSI Session CHAP authentication - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi TODO: how do we prevent errors in the filesystem from compromising the machine - -| `initiatorName` -| `string` -| Custom iSCSI Initiator Name. If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface <target portal>:<volume name> will be created for the connection. - -| `iqn` -| `string` -| Target iSCSI Qualified Name. - -| `iscsiInterface` -| `string` -| iSCSI Interface Name that uses an iSCSI transport. Defaults to 'default' (tcp). - -| `lun` -| `integer` -| iSCSI Target Lun number. - -| `portals` -| `array (string)` -| iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. - -| `secretRef` -| `object` -| CHAP Secret for iSCSI target and initiator authentication - -| `targetPortal` -| `string` -| iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -|=== -..spec.volumes[].iscsi.secretRef -Description:: - CHAP Secret for iSCSI target and initiator authentication - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].nfs -Description:: - NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -Type:: - `object` - -Required:: - - `path` - - `server` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path that is exported by the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `readOnly` -| `boolean` -| ReadOnly here will force the NFS export to be mounted with read-only permissions. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `server` -| `string` -| Server is the hostname or IP address of the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -|=== -..spec.volumes[].persistentVolumeClaim -Description:: - PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - -Required:: - - `claimName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `claimName` -| `string` -| ClaimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `readOnly` -| `boolean` -| Will force the ReadOnly setting in VolumeMounts. Default false. - -|=== -..spec.volumes[].photonPersistentDisk -Description:: - PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `pdID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `pdID` -| `string` -| ID that identifies Photon Controller persistent disk - -|=== -..spec.volumes[].portworxVolume -Description:: - PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| FSType represents the filesystem type to mount Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `volumeID` -| `string` -| VolumeID uniquely identifies a Portworx volume - -|=== -..spec.volumes[].projected -Description:: - Items for all in one resources secrets, configmaps, and downward API - -Type:: - `object` - -Required:: - - `sources` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Mode bits to use on created files by default. Must be a value between 0 and 0777. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `sources` -| `array` -| list of volume projections - -| `sources[]` -| `object` -| Projection that may be projected along with other supported volume types - -|=== -..spec.volumes[].projected.sources -Description:: - list of volume projections - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[] -Description:: - Projection that may be projected along with other supported volume types - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| information about the configMap data to project - -| `downwardAPI` -| `object` -| information about the downwardAPI data to project - -| `secret` -| `object` -| information about the secret data to project - -| `serviceAccountToken` -| `object` -| information about the serviceAccountToken data to project - -|=== -..spec.volumes[].projected.sources[].configMap -Description:: - information about the configMap data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.volumes[].projected.sources[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].projected.sources[].downwardAPI -Description:: - information about the downwardAPI data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| Items is a list of DownwardAPIVolume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items -Description:: - Items is a list of DownwardAPIVolume file - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.volumes[].projected.sources[].secret -Description:: - information about the secret data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.volumes[].projected.sources[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].projected.sources[].serviceAccountToken -Description:: - information about the serviceAccountToken data to project - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audience` -| `string` -| Audience is the intended audience of the token. A recipient of a token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. The audience defaults to the identifier of the apiserver. - -| `expirationSeconds` -| `integer` -| ExpirationSeconds is the requested duration of validity of the service account token. As the token approaches expiration, the kubelet volume plugin will proactively rotate the service account token. The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.Defaults to 1 hour and must be at least 10 minutes. - -| `path` -| `string` -| Path is the path relative to the mount point of the file to project the token into. - -|=== -..spec.volumes[].quobyte -Description:: - Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `registry` - - `volume` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group to map volume access to Default is no group - -| `readOnly` -| `boolean` -| ReadOnly here will force the Quobyte volume to be mounted with read-only permissions. Defaults to false. - -| `registry` -| `string` -| Registry represents a single or multiple Quobyte Registry services specified as a string as host:port pair (multiple entries are separated with commas) which acts as the central registry for volumes - -| `tenant` -| `string` -| Tenant owning the given Quobyte volume in the Backend Used with dynamically provisioned Quobyte volumes, value is set by the plugin - -| `user` -| `string` -| User to map volume access to Defaults to serivceaccount user - -| `volume` -| `string` -| Volume is a string that references an already created Quobyte volume by name. - -|=== -..spec.volumes[].rbd -Description:: - RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -Type:: - `object` - -Required:: - - `image` - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd TODO: how do we prevent errors in the filesystem from compromising the machine - -| `image` -| `string` -| The rados image name. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `keyring` -| `string` -| Keyring is the path to key ring for RBDUser. Default is /etc/ceph/keyring. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `monitors` -| `array (string)` -| A collection of Ceph monitors. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `pool` -| `string` -| The rados pool name. Default is rbd. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `secretRef` -| `object` -| SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `user` -| `string` -| The rados user name. Default is admin. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -|=== -..spec.volumes[].rbd.secretRef -Description:: - SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].scaleIO -Description:: - ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - -Required:: - - `gateway` - - `secretRef` - - `system` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Default is "xfs". - -| `gateway` -| `string` -| The host address of the ScaleIO API Gateway. - -| `protectionDomain` -| `string` -| The name of the ScaleIO Protection Domain for the configured storage. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -| `sslEnabled` -| `boolean` -| Flag to enable/disable SSL communication with Gateway, default false - -| `storageMode` -| `string` -| Indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned. Default is ThinProvisioned. - -| `storagePool` -| `string` -| The ScaleIO Storage Pool associated with the protection domain. - -| `system` -| `string` -| The name of the storage system as configured in ScaleIO. - -| `volumeName` -| `string` -| The name of a volume already created in the ScaleIO system that is associated with this volume source. - -|=== -..spec.volumes[].scaleIO.secretRef -Description:: - SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].secret -Description:: - Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `optional` -| `boolean` -| Specify whether the Secret or its keys must be defined - -| `secretName` -| `string` -| Name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -|=== -..spec.volumes[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].storageos -Description:: - StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -| `volumeName` -| `string` -| VolumeName is the human-readable name of the StorageOS volume. Volume names are only unique within a namespace. - -| `volumeNamespace` -| `string` -| VolumeNamespace specifies the scope of the volume within StorageOS. If no namespace is specified then the Pod's namespace will be used. This allows the Kubernetes name scoping to be mirrored within StorageOS for tighter integration. Set VolumeName to any name to override the default behaviour. Set to "default" if you are not using namespaces within StorageOS. Namespaces that do not pre-exist within StorageOS will be created. - -|=== -..spec.volumes[].storageos.secretRef -Description:: - SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].vsphereVolume -Description:: - VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumePath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `storagePolicyID` -| `string` -| Storage Policy Based Management (SPBM) profile ID associated with the StoragePolicyName. - -| `storagePolicyName` -| `string` -| Storage Policy Based Management (SPBM) profile name. - -| `volumePath` -| `string` -| Path that identifies vSphere volume vmdk - -|=== -..status -Description:: - Most recent observed status of the Alertmanager cluster. Read-only. Not included when requesting from the apiserver, only from the Prometheus Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -Type:: - `object` - -Required:: - - `availableReplicas` - - `paused` - - `replicas` - - `unavailableReplicas` - - `updatedReplicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| Total number of available pods (ready for at least minReadySeconds) targeted by this Alertmanager cluster. - -| `paused` -| `boolean` -| Represents whether any actions on the underlying managed objects are being performed. Only delete actions will be performed. - -| `replicas` -| `integer` -| Total number of non-terminated pods targeted by this Alertmanager cluster (their labels match the selector). - -| `unavailableReplicas` -| `integer` -| Total number of unavailable pods targeted by this Alertmanager cluster. - -| `updatedReplicas` -| `integer` -| Total number of non-terminated pods targeted by this Alertmanager cluster that have the desired version spec. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/monitoring.coreos.com/v1/alertmanagers` -- `GET`: list objects of kind Alertmanager -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/alertmanagers` -- `DELETE`: delete collection of Alertmanager -- `GET`: list objects of kind Alertmanager -- `POST`: create an Alertmanager -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/alertmanagers/{name}` -- `DELETE`: delete an Alertmanager -- `GET`: read the specified Alertmanager -- `PATCH`: partially update the specified Alertmanager -- `PUT`: replace the specified Alertmanager - - -=== /apis/monitoring.coreos.com/v1/alertmanagers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Alertmanager - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#alertmanagerlist-monitoring-coreos-com-v1[`AlertmanagerList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/alertmanagers - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Alertmanager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Alertmanager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#alertmanagerlist-monitoring-coreos-com-v1[`AlertmanagerList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Alertmanager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| 202 - Accepted -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/alertmanagers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Alertmanager -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Alertmanager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Alertmanager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Alertmanager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Alertmanager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`Alertmanager monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc b/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc deleted file mode 100644 index ad9e513b891b..000000000000 --- a/rest_api/monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc +++ /dev/null @@ -1,4887 +0,0 @@ -[id="alertmanagerconfig-monitoring-coreos-com-v1alpha1"] -= AlertmanagerConfig [monitoring.coreos.com/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - AlertmanagerConfig defines a namespaced AlertmanagerConfig to be aggregated across multiple namespaces configuring one Alertmanager cluster. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| AlertmanagerConfigSpec is a specification of the desired behavior of the Alertmanager configuration. By definition, the Alertmanager configuration only applies to alerts for which the `namespace` label is equal to the namespace of the AlertmanagerConfig resource. - -|=== -..spec -Description:: - AlertmanagerConfigSpec is a specification of the desired behavior of the Alertmanager configuration. By definition, the Alertmanager configuration only applies to alerts for which the `namespace` label is equal to the namespace of the AlertmanagerConfig resource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `inhibitRules` -| `array` -| List of inhibition rules. The rules will only apply to alerts matching the resource’s namespace. - -| `inhibitRules[]` -| `object` -| InhibitRule defines an inhibition rule that allows to mute alerts when other alerts are already firing. See https://prometheus.io/docs/alerting/latest/configuration/#inhibit_rule - -| `receivers` -| `array` -| List of receivers. - -| `receivers[]` -| `object` -| Receiver defines one or more notification integrations. - -| `route` -| `object` -| The Alertmanager route definition for alerts matching the resource’s namespace. It will be added to the generated Alertmanager configuration as a first-level route. - -|=== -..spec.inhibitRules -Description:: - List of inhibition rules. The rules will only apply to alerts matching the resource’s namespace. - -Type:: - `array` - - - - -..spec.inhibitRules[] -Description:: - InhibitRule defines an inhibition rule that allows to mute alerts when other alerts are already firing. See https://prometheus.io/docs/alerting/latest/configuration/#inhibit_rule - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `equal` -| `array (string)` -| Labels that must have an equal value in the source and target alert for the inhibition to take effect. - -| `sourceMatch` -| `array` -| Matchers for which one or more alerts have to exist for the inhibition to take effect. The operator enforces that the alert matches the resource’s namespace. - -| `sourceMatch[]` -| `object` -| Matcher defines how to match on alert's labels. - -| `targetMatch` -| `array` -| Matchers that have to be fulfilled in the alerts to be muted. The operator enforces that the alert matches the resource’s namespace. - -| `targetMatch[]` -| `object` -| Matcher defines how to match on alert's labels. - -|=== -..spec.inhibitRules[].sourceMatch -Description:: - Matchers for which one or more alerts have to exist for the inhibition to take effect. The operator enforces that the alert matches the resource’s namespace. - -Type:: - `array` - - - - -..spec.inhibitRules[].sourceMatch[] -Description:: - Matcher defines how to match on alert's labels. - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Label to match. - -| `regex` -| `boolean` -| Whether to match on equality (false) or regular-expression (true). - -| `value` -| `string` -| Label value to match. - -|=== -..spec.inhibitRules[].targetMatch -Description:: - Matchers that have to be fulfilled in the alerts to be muted. The operator enforces that the alert matches the resource’s namespace. - -Type:: - `array` - - - - -..spec.inhibitRules[].targetMatch[] -Description:: - Matcher defines how to match on alert's labels. - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Label to match. - -| `regex` -| `boolean` -| Whether to match on equality (false) or regular-expression (true). - -| `value` -| `string` -| Label value to match. - -|=== -..spec.receivers -Description:: - List of receivers. - -Type:: - `array` - - - - -..spec.receivers[] -Description:: - Receiver defines one or more notification integrations. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `emailConfigs` -| `array` -| List of Email configurations. - -| `emailConfigs[]` -| `object` -| EmailConfig configures notifications via Email. - -| `name` -| `string` -| Name of the receiver. Must be unique across all items from the list. - -| `opsgenieConfigs` -| `array` -| List of OpsGenie configurations. - -| `opsgenieConfigs[]` -| `object` -| OpsGenieConfig configures notifications via OpsGenie. See https://prometheus.io/docs/alerting/latest/configuration/#opsgenie_config - -| `pagerdutyConfigs` -| `array` -| List of PagerDuty configurations. - -| `pagerdutyConfigs[]` -| `object` -| PagerDutyConfig configures notifications via PagerDuty. See https://prometheus.io/docs/alerting/latest/configuration/#pagerduty_config - -| `pushoverConfigs` -| `array` -| List of Pushover configurations. - -| `pushoverConfigs[]` -| `object` -| PushoverConfig configures notifications via Pushover. See https://prometheus.io/docs/alerting/latest/configuration/#pushover_config - -| `slackConfigs` -| `array` -| List of Slack configurations. - -| `slackConfigs[]` -| `object` -| SlackConfig configures notifications via Slack. See https://prometheus.io/docs/alerting/latest/configuration/#slack_config - -| `victoropsConfigs` -| `array` -| List of VictorOps configurations. - -| `victoropsConfigs[]` -| `object` -| VictorOpsConfig configures notifications via VictorOps. See https://prometheus.io/docs/alerting/latest/configuration/#victorops_config - -| `webhookConfigs` -| `array` -| List of webhook configurations. - -| `webhookConfigs[]` -| `object` -| WebhookConfig configures notifications via a generic receiver supporting the webhook payload. See https://prometheus.io/docs/alerting/latest/configuration/#webhook_config - -| `wechatConfigs` -| `array` -| List of WeChat configurations. - -| `wechatConfigs[]` -| `object` -| WeChatConfig configures notifications via WeChat. See https://prometheus.io/docs/alerting/latest/configuration/#wechat_config - -|=== -..spec.receivers[].emailConfigs -Description:: - List of Email configurations. - -Type:: - `array` - - - - -..spec.receivers[].emailConfigs[] -Description:: - EmailConfig configures notifications via Email. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `authIdentity` -| `string` -| - -| `authPassword` -| `object` -| SecretKeySelector selects a key of a Secret. - -| `authSecret` -| `object` -| SecretKeySelector selects a key of a Secret. - -| `authUsername` -| `string` -| SMTP authentication information. - -| `from` -| `string` -| The sender address. - -| `headers` -| `array` -| Further headers email header key/value pairs. Overrides any headers previously set by the notification implementation. - -| `headers[]` -| `object` -| KeyValue defines a (key, value) tuple. - -| `hello` -| `string` -| The hostname to identify to the SMTP server. - -| `html` -| `string` -| The HTML body of the email notification. - -| `requireTLS` -| `boolean` -| The SMTP TLS requirement. Note that Go does not support unencrypted connections to remote SMTP endpoints. - -| `sendResolved` -| `boolean` -| Whether or not to notify about resolved alerts. - -| `smarthost` -| `string` -| The SMTP host through which emails are sent. - -| `text` -| `string` -| The text body of the email notification. - -| `tlsConfig` -| `object` -| TLS configuration - -| `to` -| `string` -| The email address to send notifications to. - -|=== -..spec.receivers[].emailConfigs[].authPassword -Description:: - SecretKeySelector selects a key of a Secret. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].emailConfigs[].authSecret -Description:: - SecretKeySelector selects a key of a Secret. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].emailConfigs[].headers -Description:: - Further headers email header key/value pairs. Overrides any headers previously set by the notification implementation. - -Type:: - `array` - - - - -..spec.receivers[].emailConfigs[].headers[] -Description:: - KeyValue defines a (key, value) tuple. - -Type:: - `object` - -Required:: - - `key` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| Key of the tuple. - -| `value` -| `string` -| Value of the tuple. - -|=== -..spec.receivers[].emailConfigs[].tlsConfig -Description:: - TLS configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.receivers[].emailConfigs[].tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].emailConfigs[].tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].emailConfigs[].tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].emailConfigs[].tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].emailConfigs[].tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].emailConfigs[].tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].emailConfigs[].tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs -Description:: - List of OpsGenie configurations. - -Type:: - `array` - - - - -..spec.receivers[].opsgenieConfigs[] -Description:: - OpsGenieConfig configures notifications via OpsGenie. See https://prometheus.io/docs/alerting/latest/configuration/#opsgenie_config - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiKey` -| `object` -| The secret's key that contains the OpsGenie API key. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `apiURL` -| `string` -| The URL to send OpsGenie API requests to. - -| `description` -| `string` -| Description of the incident. - -| `details` -| `array` -| A set of arbitrary key/value pairs that provide further detail about the incident. - -| `details[]` -| `object` -| KeyValue defines a (key, value) tuple. - -| `httpConfig` -| `object` -| HTTP client configuration. - -| `message` -| `string` -| Alert text limited to 130 characters. - -| `note` -| `string` -| Additional alert note. - -| `priority` -| `string` -| Priority level of alert. Possible values are P1, P2, P3, P4, and P5. - -| `responders` -| `array` -| List of responders responsible for notifications. - -| `responders[]` -| `object` -| OpsGenieConfigResponder defines a responder to an incident. One of id, name or username has to be defined. - -| `sendResolved` -| `boolean` -| Whether or not to notify about resolved alerts. - -| `source` -| `string` -| Backlink to the sender of the notification. - -| `tags` -| `string` -| Comma separated list of tags attached to the notifications. - -|=== -..spec.receivers[].opsgenieConfigs[].apiKey -Description:: - The secret's key that contains the OpsGenie API key. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].details -Description:: - A set of arbitrary key/value pairs that provide further detail about the incident. - -Type:: - `array` - - - - -..spec.receivers[].opsgenieConfigs[].details[] -Description:: - KeyValue defines a (key, value) tuple. - -Type:: - `object` - -Required:: - - `key` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| Key of the tuple. - -| `value` -| `string` -| Value of the tuple. - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig -Description:: - HTTP client configuration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the client. - -| `bearerTokenSecret` -| `object` -| The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `proxyURL` -| `string` -| Optional proxy URL. - -| `tlsConfig` -| `object` -| TLS configuration for the client. - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.basicAuth -Description:: - BasicAuth for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.bearerTokenSecret -Description:: - The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.tlsConfig -Description:: - TLS configuration for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].httpConfig.tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].opsgenieConfigs[].responders -Description:: - List of responders responsible for notifications. - -Type:: - `array` - - - - -..spec.receivers[].opsgenieConfigs[].responders[] -Description:: - OpsGenieConfigResponder defines a responder to an incident. One of id, name or username has to be defined. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `id` -| `string` -| ID of the responder. - -| `name` -| `string` -| Name of the responder. - -| `type` -| `string` -| Type of responder. - -| `username` -| `string` -| Username of the responder. - -|=== -..spec.receivers[].pagerdutyConfigs -Description:: - List of PagerDuty configurations. - -Type:: - `array` - - - - -..spec.receivers[].pagerdutyConfigs[] -Description:: - PagerDutyConfig configures notifications via PagerDuty. See https://prometheus.io/docs/alerting/latest/configuration/#pagerduty_config - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `class` -| `string` -| The class/type of the event. - -| `client` -| `string` -| Client identification. - -| `clientURL` -| `string` -| Backlink to the sender of notification. - -| `component` -| `string` -| The part or component of the affected system that is broken. - -| `description` -| `string` -| Description of the incident. - -| `details` -| `array` -| Arbitrary key/value pairs that provide further detail about the incident. - -| `details[]` -| `object` -| KeyValue defines a (key, value) tuple. - -| `group` -| `string` -| A cluster or grouping of sources. - -| `httpConfig` -| `object` -| HTTP client configuration. - -| `routingKey` -| `object` -| The secret's key that contains the PagerDuty integration key (when using Events API v2). Either this field or `serviceKey` needs to be defined. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `sendResolved` -| `boolean` -| Whether or not to notify about resolved alerts. - -| `serviceKey` -| `object` -| The secret's key that contains the PagerDuty service key (when using integration type "Prometheus"). Either this field or `routingKey` needs to be defined. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `severity` -| `string` -| Severity of the incident. - -| `url` -| `string` -| The URL to send requests to. - -|=== -..spec.receivers[].pagerdutyConfigs[].details -Description:: - Arbitrary key/value pairs that provide further detail about the incident. - -Type:: - `array` - - - - -..spec.receivers[].pagerdutyConfigs[].details[] -Description:: - KeyValue defines a (key, value) tuple. - -Type:: - `object` - -Required:: - - `key` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| Key of the tuple. - -| `value` -| `string` -| Value of the tuple. - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig -Description:: - HTTP client configuration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the client. - -| `bearerTokenSecret` -| `object` -| The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `proxyURL` -| `string` -| Optional proxy URL. - -| `tlsConfig` -| `object` -| TLS configuration for the client. - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.basicAuth -Description:: - BasicAuth for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.bearerTokenSecret -Description:: - The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.tlsConfig -Description:: - TLS configuration for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].httpConfig.tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].routingKey -Description:: - The secret's key that contains the PagerDuty integration key (when using Events API v2). Either this field or `serviceKey` needs to be defined. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pagerdutyConfigs[].serviceKey -Description:: - The secret's key that contains the PagerDuty service key (when using integration type "Prometheus"). Either this field or `routingKey` needs to be defined. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs -Description:: - List of Pushover configurations. - -Type:: - `array` - - - - -..spec.receivers[].pushoverConfigs[] -Description:: - PushoverConfig configures notifications via Pushover. See https://prometheus.io/docs/alerting/latest/configuration/#pushover_config - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `expire` -| `string` -| How long your notification will continue to be retried for, unless the user acknowledges the notification. - -| `html` -| `boolean` -| Whether notification message is HTML or plain text. - -| `httpConfig` -| `object` -| HTTP client configuration. - -| `message` -| `string` -| Notification message. - -| `priority` -| `string` -| Priority, see https://pushover.net/api#priority - -| `retry` -| `string` -| How often the Pushover servers will send the same notification to the user. Must be at least 30 seconds. - -| `sendResolved` -| `boolean` -| Whether or not to notify about resolved alerts. - -| `sound` -| `string` -| The name of one of the sounds supported by device clients to override the user's default sound choice - -| `title` -| `string` -| Notification title. - -| `token` -| `object` -| Your registered application’s API token, see https://pushover.net/apps - -| `url` -| `string` -| A supplementary URL shown alongside the message. - -| `urlTitle` -| `string` -| A title for supplementary URL, otherwise just the URL is shown - -| `userKey` -| `object` -| The recipient user’s user key. - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig -Description:: - HTTP client configuration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the client. - -| `bearerTokenSecret` -| `object` -| The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `proxyURL` -| `string` -| Optional proxy URL. - -| `tlsConfig` -| `object` -| TLS configuration for the client. - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.basicAuth -Description:: - BasicAuth for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.bearerTokenSecret -Description:: - The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.tlsConfig -Description:: - TLS configuration for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].httpConfig.tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].token -Description:: - Your registered application’s API token, see https://pushover.net/apps - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].pushoverConfigs[].userKey -Description:: - The recipient user’s user key. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].slackConfigs -Description:: - List of Slack configurations. - -Type:: - `array` - - - - -..spec.receivers[].slackConfigs[] -Description:: - SlackConfig configures notifications via Slack. See https://prometheus.io/docs/alerting/latest/configuration/#slack_config - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actions` -| `array` -| A list of Slack actions that are sent with each notification. - -| `actions[]` -| `object` -| SlackAction configures a single Slack action that is sent with each notification. See https://api.slack.com/docs/message-attachments#action_fields and https://api.slack.com/docs/message-buttons for more information. - -| `apiURL` -| `object` -| The secret's key that contains the Slack webhook URL. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `callbackId` -| `string` -| - -| `channel` -| `string` -| The channel or user to send notifications to. - -| `color` -| `string` -| - -| `fallback` -| `string` -| - -| `fields` -| `array` -| A list of Slack fields that are sent with each notification. - -| `fields[]` -| `object` -| SlackField configures a single Slack field that is sent with each notification. Each field must contain a title, value, and optionally, a boolean value to indicate if the field is short enough to be displayed next to other fields designated as short. See https://api.slack.com/docs/message-attachments#fields for more information. - -| `footer` -| `string` -| - -| `httpConfig` -| `object` -| HTTP client configuration. - -| `iconEmoji` -| `string` -| - -| `iconURL` -| `string` -| - -| `imageURL` -| `string` -| - -| `linkNames` -| `boolean` -| - -| `mrkdwnIn` -| `array (string)` -| - -| `pretext` -| `string` -| - -| `sendResolved` -| `boolean` -| Whether or not to notify about resolved alerts. - -| `shortFields` -| `boolean` -| - -| `text` -| `string` -| - -| `thumbURL` -| `string` -| - -| `title` -| `string` -| - -| `titleLink` -| `string` -| - -| `username` -| `string` -| - -|=== -..spec.receivers[].slackConfigs[].actions -Description:: - A list of Slack actions that are sent with each notification. - -Type:: - `array` - - - - -..spec.receivers[].slackConfigs[].actions[] -Description:: - SlackAction configures a single Slack action that is sent with each notification. See https://api.slack.com/docs/message-attachments#action_fields and https://api.slack.com/docs/message-buttons for more information. - -Type:: - `object` - -Required:: - - `text` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `confirm` -| `object` -| SlackConfirmationField protect users from destructive actions or particularly distinguished decisions by asking them to confirm their button click one more time. See https://api.slack.com/docs/interactive-message-field-guide#confirmation_fields for more information. - -| `name` -| `string` -| - -| `style` -| `string` -| - -| `text` -| `string` -| - -| `type` -| `string` -| - -| `url` -| `string` -| - -| `value` -| `string` -| - -|=== -..spec.receivers[].slackConfigs[].actions[].confirm -Description:: - SlackConfirmationField protect users from destructive actions or particularly distinguished decisions by asking them to confirm their button click one more time. See https://api.slack.com/docs/interactive-message-field-guide#confirmation_fields for more information. - -Type:: - `object` - -Required:: - - `text` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `dismissText` -| `string` -| - -| `okText` -| `string` -| - -| `text` -| `string` -| - -| `title` -| `string` -| - -|=== -..spec.receivers[].slackConfigs[].apiURL -Description:: - The secret's key that contains the Slack webhook URL. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].slackConfigs[].fields -Description:: - A list of Slack fields that are sent with each notification. - -Type:: - `array` - - - - -..spec.receivers[].slackConfigs[].fields[] -Description:: - SlackField configures a single Slack field that is sent with each notification. Each field must contain a title, value, and optionally, a boolean value to indicate if the field is short enough to be displayed next to other fields designated as short. See https://api.slack.com/docs/message-attachments#fields for more information. - -Type:: - `object` - -Required:: - - `title` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `short` -| `boolean` -| - -| `title` -| `string` -| - -| `value` -| `string` -| - -|=== -..spec.receivers[].slackConfigs[].httpConfig -Description:: - HTTP client configuration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the client. - -| `bearerTokenSecret` -| `object` -| The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `proxyURL` -| `string` -| Optional proxy URL. - -| `tlsConfig` -| `object` -| TLS configuration for the client. - -|=== -..spec.receivers[].slackConfigs[].httpConfig.basicAuth -Description:: - BasicAuth for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.receivers[].slackConfigs[].httpConfig.basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].slackConfigs[].httpConfig.basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].slackConfigs[].httpConfig.bearerTokenSecret -Description:: - The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].slackConfigs[].httpConfig.tlsConfig -Description:: - TLS configuration for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.receivers[].slackConfigs[].httpConfig.tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].slackConfigs[].httpConfig.tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].slackConfigs[].httpConfig.tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].slackConfigs[].httpConfig.tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].slackConfigs[].httpConfig.tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].slackConfigs[].httpConfig.tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].slackConfigs[].httpConfig.tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs -Description:: - List of VictorOps configurations. - -Type:: - `array` - - - - -..spec.receivers[].victoropsConfigs[] -Description:: - VictorOpsConfig configures notifications via VictorOps. See https://prometheus.io/docs/alerting/latest/configuration/#victorops_config - -Type:: - `object` - -Required:: - - `routingKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiKey` -| `object` -| The API key to use when talking to the VictorOps API. - -| `apiUrl` -| `string` -| The VictorOps API URL. - -| `customFields` -| `array` -| Additional custom fields for notification. - -| `customFields[]` -| `object` -| KeyValue defines a (key, value) tuple. - -| `entityDisplayName` -| `string` -| Contains summary of the alerted problem. - -| `httpConfig` -| `object` -| The HTTP client's configuration. - -| `messageType` -| `string` -| Describes the behavior of the alert (CRITICAL, WARNING, INFO). - -| `monitoringTool` -| `string` -| The monitoring tool the state message is from. - -| `routingKey` -| `string` -| A key used to map the alert to a team. - -| `sendResolved` -| `boolean` -| Whether or not to notify about resolved alerts. - -| `stateMessage` -| `string` -| Contains long explanation of the alerted problem. - -|=== -..spec.receivers[].victoropsConfigs[].apiKey -Description:: - The API key to use when talking to the VictorOps API. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs[].customFields -Description:: - Additional custom fields for notification. - -Type:: - `array` - - - - -..spec.receivers[].victoropsConfigs[].customFields[] -Description:: - KeyValue defines a (key, value) tuple. - -Type:: - `object` - -Required:: - - `key` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| Key of the tuple. - -| `value` -| `string` -| Value of the tuple. - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig -Description:: - The HTTP client's configuration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the client. - -| `bearerTokenSecret` -| `object` -| The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `proxyURL` -| `string` -| Optional proxy URL. - -| `tlsConfig` -| `object` -| TLS configuration for the client. - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.basicAuth -Description:: - BasicAuth for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.bearerTokenSecret -Description:: - The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.tlsConfig -Description:: - TLS configuration for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].victoropsConfigs[].httpConfig.tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].webhookConfigs -Description:: - List of webhook configurations. - -Type:: - `array` - - - - -..spec.receivers[].webhookConfigs[] -Description:: - WebhookConfig configures notifications via a generic receiver supporting the webhook payload. See https://prometheus.io/docs/alerting/latest/configuration/#webhook_config - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `httpConfig` -| `object` -| HTTP client configuration. - -| `maxAlerts` -| `integer` -| Maximum number of alerts to be sent per webhook message. - -| `sendResolved` -| `boolean` -| Whether or not to notify about resolved alerts. - -| `url` -| `string` -| The URL to send HTTP POST requests to. `urlSecret` takes precedence over `url`. One of `urlSecret` and `url` should be defined. - -| `urlSecret` -| `object` -| The secret's key that contains the webhook URL to send HTTP requests to. `urlSecret` takes precedence over `url`. One of `urlSecret` and `url` should be defined. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -|=== -..spec.receivers[].webhookConfigs[].httpConfig -Description:: - HTTP client configuration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the client. - -| `bearerTokenSecret` -| `object` -| The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `proxyURL` -| `string` -| Optional proxy URL. - -| `tlsConfig` -| `object` -| TLS configuration for the client. - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.basicAuth -Description:: - BasicAuth for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.bearerTokenSecret -Description:: - The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.tlsConfig -Description:: - TLS configuration for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].webhookConfigs[].httpConfig.tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].webhookConfigs[].urlSecret -Description:: - The secret's key that contains the webhook URL to send HTTP requests to. `urlSecret` takes precedence over `url`. One of `urlSecret` and `url` should be defined. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].wechatConfigs -Description:: - List of WeChat configurations. - -Type:: - `array` - - - - -..spec.receivers[].wechatConfigs[] -Description:: - WeChatConfig configures notifications via WeChat. See https://prometheus.io/docs/alerting/latest/configuration/#wechat_config - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `agentID` -| `string` -| - -| `apiSecret` -| `object` -| The secret's key that contains the WeChat API key. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `apiURL` -| `string` -| The WeChat API URL. - -| `corpID` -| `string` -| The corp id for authentication. - -| `httpConfig` -| `object` -| HTTP client configuration. - -| `message` -| `string` -| API request data as defined by the WeChat API. - -| `messageType` -| `string` -| - -| `sendResolved` -| `boolean` -| Whether or not to notify about resolved alerts. - -| `toParty` -| `string` -| - -| `toTag` -| `string` -| - -| `toUser` -| `string` -| - -|=== -..spec.receivers[].wechatConfigs[].apiSecret -Description:: - The secret's key that contains the WeChat API key. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].wechatConfigs[].httpConfig -Description:: - HTTP client configuration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the client. - -| `bearerTokenSecret` -| `object` -| The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -| `proxyURL` -| `string` -| Optional proxy URL. - -| `tlsConfig` -| `object` -| TLS configuration for the client. - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.basicAuth -Description:: - BasicAuth for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.bearerTokenSecret -Description:: - The secret's key that contains the bearer token to be used by the client for authentication. The secret needs to be in the same namespace as the AlertmanagerConfig object and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.tlsConfig -Description:: - TLS configuration for the client. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.receivers[].wechatConfigs[].httpConfig.tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.route -Description:: - The Alertmanager route definition for alerts matching the resource’s namespace. It will be added to the generated Alertmanager configuration as a first-level route. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `continue` -| `boolean` -| Boolean indicating whether an alert should continue matching subsequent sibling nodes. It will always be overridden to true for the first-level route by the Prometheus operator. - -| `groupBy` -| `array (string)` -| List of labels to group by. - -| `groupInterval` -| `string` -| How long to wait before sending an updated notification. Must match the regular expression `[0-9]+(ms\|s\|m\|h)` (milliseconds seconds minutes hours). - -| `groupWait` -| `string` -| How long to wait before sending the initial notification. Must match the regular expression `[0-9]+(ms\|s\|m\|h)` (milliseconds seconds minutes hours). - -| `matchers` -| `array` -| List of matchers that the alert’s labels should match. For the first level route, the operator removes any existing equality and regexp matcher on the `namespace` label and adds a `namespace: <object namespace>` matcher. - -| `matchers[]` -| `object` -| Matcher defines how to match on alert's labels. - -| `receiver` -| `string` -| Name of the receiver for this route. If present, it should be listed in the `receivers` field. The field can be omitted only for nested routes otherwise it is mandatory. - -| `repeatInterval` -| `string` -| How long to wait before repeating the last notification. Must match the regular expression `[0-9]+(ms\|s\|m\|h)` (milliseconds seconds minutes hours). - -| `routes` -| `array (undefined)` -| Child routes. - -|=== -..spec.route.matchers -Description:: - List of matchers that the alert’s labels should match. For the first level route, the operator removes any existing equality and regexp matcher on the `namespace` label and adds a `namespace: <object namespace>` matcher. - -Type:: - `array` - - - - -..spec.route.matchers[] -Description:: - Matcher defines how to match on alert's labels. - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Label to match. - -| `regex` -| `boolean` -| Whether to match on equality (false) or regular-expression (true). - -| `value` -| `string` -| Label value to match. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/monitoring.coreos.com/v1alpha1/alertmanagerconfigs` -- `GET`: list objects of kind AlertmanagerConfig -* `/apis/monitoring.coreos.com/v1alpha1/namespaces/{namespace}/alertmanagerconfigs` -- `DELETE`: delete collection of AlertmanagerConfig -- `GET`: list objects of kind AlertmanagerConfig -- `POST`: create an AlertmanagerConfig -* `/apis/monitoring.coreos.com/v1alpha1/namespaces/{namespace}/alertmanagerconfigs/{name}` -- `DELETE`: delete an AlertmanagerConfig -- `GET`: read the specified AlertmanagerConfig -- `PATCH`: partially update the specified AlertmanagerConfig -- `PUT`: replace the specified AlertmanagerConfig - - -=== /apis/monitoring.coreos.com/v1alpha1/alertmanagerconfigs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind AlertmanagerConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#alertmanagerconfiglist-monitoring-coreos-com-v1alpha1[`AlertmanagerConfigList monitoring.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1alpha1/namespaces/{namespace}/alertmanagerconfigs - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of AlertmanagerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind AlertmanagerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#alertmanagerconfiglist-monitoring-coreos-com-v1alpha1[`AlertmanagerConfigList monitoring.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an AlertmanagerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| 201 - Created -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| 202 - Accepted -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1alpha1/namespaces/{namespace}/alertmanagerconfigs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the AlertmanagerConfig -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an AlertmanagerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified AlertmanagerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified AlertmanagerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified AlertmanagerConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| 201 - Created -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`AlertmanagerConfig monitoring.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/monitoring_apis/monitoring-apis-index.adoc b/rest_api/monitoring_apis/monitoring-apis-index.adoc deleted file mode 100644 index e9a7b9bcd69b..000000000000 --- a/rest_api/monitoring_apis/monitoring-apis-index.adoc +++ /dev/null @@ -1,72 +0,0 @@ -[id="monitoring-apis"] -= Monitoring APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== Alertmanager [monitoring.coreos.com/v1] - -Description:: - Alertmanager describes an Alertmanager cluster. - -Type:: - `object` - -== AlertmanagerConfig [monitoring.coreos.com/v1alpha1] - -Description:: - AlertmanagerConfig defines a namespaced AlertmanagerConfig to be aggregated across multiple namespaces configuring one Alertmanager cluster. - -Type:: - `object` - -== PodMonitor [monitoring.coreos.com/v1] - -Description:: - PodMonitor defines monitoring for a set of pods. - -Type:: - `object` - -== Probe [monitoring.coreos.com/v1] - -Description:: - Probe defines monitoring for a set of static targets or ingresses. - -Type:: - `object` - -== Prometheus [monitoring.coreos.com/v1] - -Description:: - Prometheus defines a Prometheus deployment. - -Type:: - `object` - -== PrometheusRule [monitoring.coreos.com/v1] - -Description:: - PrometheusRule defines recording and alerting rules for a Prometheus instance - -Type:: - `object` - -== ServiceMonitor [monitoring.coreos.com/v1] - -Description:: - ServiceMonitor defines monitoring for a set of services. - -Type:: - `object` - -== ThanosRuler [monitoring.coreos.com/v1] - -Description:: - ThanosRuler defines a ThanosRuler deployment. - -Type:: - `object` - diff --git a/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc deleted file mode 100644 index 74f87c41d6ba..000000000000 --- a/rest_api/monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc +++ /dev/null @@ -1,1172 +0,0 @@ -[id="podmonitor-monitoring-coreos-com-v1"] -= PodMonitor [monitoring.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PodMonitor defines monitoring for a set of pods. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of desired Pod selection for target discovery by Prometheus. - -|=== -..spec -Description:: - Specification of desired Pod selection for target discovery by Prometheus. - -Type:: - `object` - -Required:: - - `podMetricsEndpoints` - - `selector` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `jobLabel` -| `string` -| The label to use to retrieve the job name from. - -| `namespaceSelector` -| `object` -| Selector to select which namespaces the Endpoints objects are discovered from. - -| `podMetricsEndpoints` -| `array` -| A list of endpoints allowed as part of this PodMonitor. - -| `podMetricsEndpoints[]` -| `object` -| PodMetricsEndpoint defines a scrapeable endpoint of a Kubernetes Pod serving Prometheus metrics. - -| `podTargetLabels` -| `array (string)` -| PodTargetLabels transfers labels on the Kubernetes Pod onto the target. - -| `sampleLimit` -| `integer` -| SampleLimit defines per-scrape limit on number of scraped samples that will be accepted. - -| `selector` -| `object` -| Selector to select Pod objects. - -| `targetLimit` -| `integer` -| TargetLimit defines a limit on the number of scraped targets that will be accepted. - -|=== -..spec.namespaceSelector -Description:: - Selector to select which namespaces the Endpoints objects are discovered from. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `any` -| `boolean` -| Boolean describing whether all namespaces are selected in contrast to a list restricting them. - -| `matchNames` -| `array (string)` -| List of namespace names. - -|=== -..spec.podMetricsEndpoints -Description:: - A list of endpoints allowed as part of this PodMonitor. - -Type:: - `array` - - - - -..spec.podMetricsEndpoints[] -Description:: - PodMetricsEndpoint defines a scrapeable endpoint of a Kubernetes Pod serving Prometheus metrics. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth allow an endpoint to authenticate over basic authentication. More info: https://prometheus.io/docs/operating/configuration/#endpoint - -| `bearerTokenSecret` -| `object` -| Secret to mount to read bearer token for scraping targets. The secret needs to be in the same namespace as the pod monitor and accessible by the Prometheus Operator. - -| `honorLabels` -| `boolean` -| HonorLabels chooses the metric's labels on collisions with target labels. - -| `honorTimestamps` -| `boolean` -| HonorTimestamps controls whether Prometheus respects the timestamps present in scraped data. - -| `interval` -| `string` -| Interval at which metrics should be scraped - -| `metricRelabelings` -| `array` -| MetricRelabelConfigs to apply to samples before ingestion. - -| `metricRelabelings[]` -| `object` -| RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -| `params` -| `object` -| Optional HTTP URL parameters - -| `params{}` -| `array (string)` -| - -| `path` -| `string` -| HTTP path to scrape for metrics. - -| `port` -| `string` -| Name of the pod port this endpoint refers to. Mutually exclusive with targetPort. - -| `proxyUrl` -| `string` -| ProxyURL eg http://proxyserver:2195 Directs scrapes to proxy through this endpoint. - -| `relabelings` -| `array` -| RelabelConfigs to apply to samples before ingestion. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config - -| `relabelings[]` -| `object` -| RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -| `scheme` -| `string` -| HTTP scheme to use for scraping. - -| `scrapeTimeout` -| `string` -| Timeout after which the scrape is ended - -| `targetPort` -| `integer-or-string` -| Deprecated: Use 'port' instead. - -| `tlsConfig` -| `object` -| TLS configuration to use when scraping the endpoint. - -|=== -..spec.podMetricsEndpoints[].basicAuth -Description:: - BasicAuth allow an endpoint to authenticate over basic authentication. More info: https://prometheus.io/docs/operating/configuration/#endpoint - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.podMetricsEndpoints[].basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.podMetricsEndpoints[].basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.podMetricsEndpoints[].bearerTokenSecret -Description:: - Secret to mount to read bearer token for scraping targets. The secret needs to be in the same namespace as the pod monitor and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.podMetricsEndpoints[].metricRelabelings -Description:: - MetricRelabelConfigs to apply to samples before ingestion. - -Type:: - `array` - - - - -..spec.podMetricsEndpoints[].metricRelabelings[] -Description:: - RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `action` -| `string` -| Action to perform based on regex matching. Default is 'replace' - -| `modulus` -| `integer` -| Modulus to take of the hash of the source label values. - -| `regex` -| `string` -| Regular expression against which the extracted value is matched. Default is '(.*)' - -| `replacement` -| `string` -| Replacement value against which a regex replace is performed if the regular expression matches. Regex capture groups are available. Default is '$1' - -| `separator` -| `string` -| Separator placed between concatenated source label values. default is ';'. - -| `sourceLabels` -| `array (string)` -| The source labels select values from existing labels. Their content is concatenated using the configured separator and matched against the configured regular expression for the replace, keep, and drop actions. - -| `targetLabel` -| `string` -| Label to which the resulting value is written in a replace action. It is mandatory for replace actions. Regex capture groups are available. - -|=== -..spec.podMetricsEndpoints[].params -Description:: - Optional HTTP URL parameters - -Type:: - `object` - - - - -..spec.podMetricsEndpoints[].relabelings -Description:: - RelabelConfigs to apply to samples before ingestion. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config - -Type:: - `array` - - - - -..spec.podMetricsEndpoints[].relabelings[] -Description:: - RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `action` -| `string` -| Action to perform based on regex matching. Default is 'replace' - -| `modulus` -| `integer` -| Modulus to take of the hash of the source label values. - -| `regex` -| `string` -| Regular expression against which the extracted value is matched. Default is '(.*)' - -| `replacement` -| `string` -| Replacement value against which a regex replace is performed if the regular expression matches. Regex capture groups are available. Default is '$1' - -| `separator` -| `string` -| Separator placed between concatenated source label values. default is ';'. - -| `sourceLabels` -| `array (string)` -| The source labels select values from existing labels. Their content is concatenated using the configured separator and matched against the configured regular expression for the replace, keep, and drop actions. - -| `targetLabel` -| `string` -| Label to which the resulting value is written in a replace action. It is mandatory for replace actions. Regex capture groups are available. - -|=== -..spec.podMetricsEndpoints[].tlsConfig -Description:: - TLS configuration to use when scraping the endpoint. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.podMetricsEndpoints[].tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.podMetricsEndpoints[].tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.podMetricsEndpoints[].tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.podMetricsEndpoints[].tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.podMetricsEndpoints[].tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.podMetricsEndpoints[].tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.podMetricsEndpoints[].tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.selector -Description:: - Selector to select Pod objects. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/monitoring.coreos.com/v1/podmonitors` -- `GET`: list objects of kind PodMonitor -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/podmonitors` -- `DELETE`: delete collection of PodMonitor -- `GET`: list objects of kind PodMonitor -- `POST`: create a PodMonitor -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/podmonitors/{name}` -- `DELETE`: delete a PodMonitor -- `GET`: read the specified PodMonitor -- `PATCH`: partially update the specified PodMonitor -- `PUT`: replace the specified PodMonitor - - -=== /apis/monitoring.coreos.com/v1/podmonitors - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind PodMonitor - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#podmonitorlist-monitoring-coreos-com-v1[`PodMonitorList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/podmonitors - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PodMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind PodMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#podmonitorlist-monitoring-coreos-com-v1[`PodMonitorList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PodMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| 202 - Accepted -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/podmonitors/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodMonitor -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PodMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PodMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PodMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PodMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`PodMonitor monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc deleted file mode 100644 index 78e1a34e79e6..000000000000 --- a/rest_api/monitoring_apis/probe-monitoring-coreos-com-v1.adoc +++ /dev/null @@ -1,771 +0,0 @@ -[id="probe-monitoring-coreos-com-v1"] -= Probe [monitoring.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Probe defines monitoring for a set of static targets or ingresses. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of desired Ingress selection for target discovery by Prometheus. - -|=== -..spec -Description:: - Specification of desired Ingress selection for target discovery by Prometheus. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `interval` -| `string` -| Interval at which targets are probed using the configured prober. If not specified Prometheus' global scrape interval is used. - -| `jobName` -| `string` -| The job name assigned to scraped metrics by default. - -| `module` -| `string` -| The module to use for probing specifying how to probe the target. Example module configuring in the blackbox exporter: https://github.com/prometheus/blackbox_exporter/blob/master/example.yml - -| `prober` -| `object` -| Specification for the prober to use for probing targets. The prober.URL parameter is required. Targets cannot be probed if left empty. - -| `scrapeTimeout` -| `string` -| Timeout for scraping metrics from the Prometheus exporter. - -| `targets` -| `object` -| Targets defines a set of static and/or dynamically discovered targets to be probed using the prober. - -|=== -..spec.prober -Description:: - Specification for the prober to use for probing targets. The prober.URL parameter is required. Targets cannot be probed if left empty. - -Type:: - `object` - -Required:: - - `url` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path to collect metrics from. Defaults to `/probe`. - -| `scheme` -| `string` -| HTTP scheme to use for scraping. Defaults to `http`. - -| `url` -| `string` -| Mandatory URL of the prober. - -|=== -..spec.targets -Description:: - Targets defines a set of static and/or dynamically discovered targets to be probed using the prober. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ingress` -| `object` -| Ingress defines the set of dynamically discovered ingress objects which hosts are considered for probing. - -| `staticConfig` -| `object` -| StaticConfig defines static targets which are considers for probing. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#static_config. - -|=== -..spec.targets.ingress -Description:: - Ingress defines the set of dynamically discovered ingress objects which hosts are considered for probing. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namespaceSelector` -| `object` -| Select Ingress objects by namespace. - -| `relabelingConfigs` -| `array` -| RelabelConfigs to apply to samples before ingestion. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config - -| `relabelingConfigs[]` -| `object` -| RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -| `selector` -| `object` -| Select Ingress objects by labels. - -|=== -..spec.targets.ingress.namespaceSelector -Description:: - Select Ingress objects by namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `any` -| `boolean` -| Boolean describing whether all namespaces are selected in contrast to a list restricting them. - -| `matchNames` -| `array (string)` -| List of namespace names. - -|=== -..spec.targets.ingress.relabelingConfigs -Description:: - RelabelConfigs to apply to samples before ingestion. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config - -Type:: - `array` - - - - -..spec.targets.ingress.relabelingConfigs[] -Description:: - RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `action` -| `string` -| Action to perform based on regex matching. Default is 'replace' - -| `modulus` -| `integer` -| Modulus to take of the hash of the source label values. - -| `regex` -| `string` -| Regular expression against which the extracted value is matched. Default is '(.*)' - -| `replacement` -| `string` -| Replacement value against which a regex replace is performed if the regular expression matches. Regex capture groups are available. Default is '$1' - -| `separator` -| `string` -| Separator placed between concatenated source label values. default is ';'. - -| `sourceLabels` -| `array (string)` -| The source labels select values from existing labels. Their content is concatenated using the configured separator and matched against the configured regular expression for the replace, keep, and drop actions. - -| `targetLabel` -| `string` -| Label to which the resulting value is written in a replace action. It is mandatory for replace actions. Regex capture groups are available. - -|=== -..spec.targets.ingress.selector -Description:: - Select Ingress objects by labels. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.targets.ingress.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.targets.ingress.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.targets.staticConfig -Description:: - StaticConfig defines static targets which are considers for probing. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#static_config. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labels` -| `object (string)` -| Labels assigned to all metrics scraped from the targets. - -| `static` -| `array (string)` -| Targets is a list of URLs to probe using the configured prober. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/monitoring.coreos.com/v1/probes` -- `GET`: list objects of kind Probe -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/probes` -- `DELETE`: delete collection of Probe -- `GET`: list objects of kind Probe -- `POST`: create a Probe -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/probes/{name}` -- `DELETE`: delete a Probe -- `GET`: read the specified Probe -- `PATCH`: partially update the specified Probe -- `PUT`: replace the specified Probe - - -=== /apis/monitoring.coreos.com/v1/probes - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Probe - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#probelist-monitoring-coreos-com-v1[`ProbeList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/probes - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Probe - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Probe - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#probelist-monitoring-coreos-com-v1[`ProbeList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Probe - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| 202 - Accepted -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/probes/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Probe -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Probe - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Probe - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Probe - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Probe - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`Probe monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc deleted file mode 100644 index 822796bc7d91..000000000000 --- a/rest_api/monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc +++ /dev/null @@ -1,10087 +0,0 @@ -[id="prometheus-monitoring-coreos-com-v1"] -= Prometheus [monitoring.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Prometheus defines a Prometheus deployment. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of the desired behavior of the Prometheus cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -| `status` -| `object` -| Most recent observed status of the Prometheus cluster. Read-only. Not included when requesting from the apiserver, only from the Prometheus Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -|=== -..spec -Description:: - Specification of the desired behavior of the Prometheus cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalAlertManagerConfigs` -| `object` -| AdditionalAlertManagerConfigs allows specifying a key of a Secret containing additional Prometheus AlertManager configurations. AlertManager configurations specified are appended to the configurations generated by the Prometheus Operator. Job configurations specified must have the form as specified in the official Prometheus documentation: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alertmanager_config. As AlertManager configs are appended, the user is responsible to make sure it is valid. Note that using this feature may expose the possibility to break upgrades of Prometheus. It is advised to review Prometheus release notes to ensure that no incompatible AlertManager configs are going to break Prometheus after the upgrade. - -| `additionalAlertRelabelConfigs` -| `object` -| AdditionalAlertRelabelConfigs allows specifying a key of a Secret containing additional Prometheus alert relabel configurations. Alert relabel configurations specified are appended to the configurations generated by the Prometheus Operator. Alert relabel configurations specified must have the form as specified in the official Prometheus documentation: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alert_relabel_configs. As alert relabel configs are appended, the user is responsible to make sure it is valid. Note that using this feature may expose the possibility to break upgrades of Prometheus. It is advised to review Prometheus release notes to ensure that no incompatible alert relabel configs are going to break Prometheus after the upgrade. - -| `additionalScrapeConfigs` -| `object` -| AdditionalScrapeConfigs allows specifying a key of a Secret containing additional Prometheus scrape configurations. Scrape configurations specified are appended to the configurations generated by the Prometheus Operator. Job configurations specified must have the form as specified in the official Prometheus documentation: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config. As scrape configs are appended, the user is responsible to make sure it is valid. Note that using this feature may expose the possibility to break upgrades of Prometheus. It is advised to review Prometheus release notes to ensure that no incompatible scrape configs are going to break Prometheus after the upgrade. - -| `affinity` -| `object` -| If specified, the pod's scheduling constraints. - -| `alerting` -| `object` -| Define details regarding alerting. - -| `allowOverlappingBlocks` -| `boolean` -| AllowOverlappingBlocks enables vertical compaction and vertical query merge in Prometheus. This is still experimental in Prometheus so it may change in any upcoming release. - -| `apiserverConfig` -| `object` -| APIServerConfig allows specifying a host and auth methods to access apiserver. If left empty, Prometheus is assumed to run inside of the cluster and will discover API servers automatically and use the pod's CA certificate and bearer token file at /var/run/secrets/kubernetes.io/serviceaccount/. - -| `arbitraryFSAccessThroughSMs` -| `object` -| ArbitraryFSAccessThroughSMs configures whether configuration based on a service monitor can access arbitrary files on the file system of the Prometheus container e.g. bearer token files. - -| `baseImage` -| `string` -| Base image to use for a Prometheus deployment. Deprecated: use 'image' instead - -| `configMaps` -| `array (string)` -| ConfigMaps is a list of ConfigMaps in the same namespace as the Prometheus object, which shall be mounted into the Prometheus Pods. The ConfigMaps are mounted into /etc/prometheus/configmaps/<configmap-name>. - -| `containers` -| `array` -| Containers allows injecting additional containers or modifying operator generated containers. This can be used to allow adding an authentication proxy to a Prometheus pod or to change the behavior of an operator generated container. Containers described here modify an operator generated container if they share the same name and modifications are done via a strategic merge patch. The current container names are: `prometheus`, `config-reloader`, and `thanos-sidecar`. Overriding containers is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -| `containers[]` -| `object` -| A single application container that you want to run within a pod. - -| `disableCompaction` -| `boolean` -| Disable prometheus compaction. - -| `enableAdminAPI` -| `boolean` -| Enable access to prometheus web admin API. Defaults to the value of `false`. WARNING: Enabling the admin APIs enables mutating endpoints, to delete data, shutdown Prometheus, and more. Enabling this should be done with care and the user is advised to add additional authentication authorization via a proxy to ensure only clients authorized to perform these actions can do so. For more information see https://prometheus.io/docs/prometheus/latest/querying/api/#tsdb-admin-apis - -| `enforcedNamespaceLabel` -| `string` -| EnforcedNamespaceLabel enforces adding a namespace label of origin for each alert and metric that is user created. The label value will always be the namespace of the object that is being created. - -| `enforcedSampleLimit` -| `integer` -| EnforcedSampleLimit defines global limit on number of scraped samples that will be accepted. This overrides any SampleLimit set per ServiceMonitor or/and PodMonitor. It is meant to be used by admins to enforce the SampleLimit to keep overall number of samples/series under the desired limit. Note that if SampleLimit is lower that value will be taken instead. - -| `enforcedTargetLimit` -| `integer` -| EnforcedTargetLimit defines a global limit on the number of scraped targets. This overrides any TargetLimit set per ServiceMonitor or/and PodMonitor. It is meant to be used by admins to enforce the TargetLimit to keep overall number of targets under the desired limit. Note that if TargetLimit is higher that value will be taken instead. - -| `evaluationInterval` -| `string` -| Interval between consecutive evaluations. - -| `externalLabels` -| `object (string)` -| The labels to add to any time series or alerts when communicating with external systems (federation, remote storage, Alertmanager). - -| `externalUrl` -| `string` -| The external URL the Prometheus instances will be available under. This is necessary to generate correct URLs. This is necessary if Prometheus is not served from root of a DNS name. - -| `ignoreNamespaceSelectors` -| `boolean` -| IgnoreNamespaceSelectors if set to true will ignore NamespaceSelector settings from the podmonitor and servicemonitor configs, and they will only discover endpoints within their current namespace. Defaults to false. - -| `image` -| `string` -| Image if specified has precedence over baseImage, tag and sha combinations. Specifying the version is still necessary to ensure the Prometheus Operator knows what version of Prometheus is being configured. - -| `imagePullSecrets` -| `array` -| An optional list of references to secrets in the same namespace to use for pulling prometheus and alertmanager images from registries see http://kubernetes.io/docs/user-guide/images#specifying-imagepullsecrets-on-a-pod - -| `imagePullSecrets[]` -| `object` -| LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -| `initContainers` -| `array` -| InitContainers allows adding initContainers to the pod definition. Those can be used to e.g. fetch secrets for injection into the Prometheus configuration from external sources. Any errors during the execution of an initContainer will lead to a restart of the Pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ Using initContainers for any use case other then secret fetching is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -| `initContainers[]` -| `object` -| A single application container that you want to run within a pod. - -| `listenLocal` -| `boolean` -| ListenLocal makes the Prometheus server listen on loopback, so that it does not bind against the Pod IP. - -| `logFormat` -| `string` -| Log format for Prometheus to be configured with. - -| `logLevel` -| `string` -| Log level for Prometheus to be configured with. - -| `nodeSelector` -| `object (string)` -| Define which Nodes the Pods are scheduled on. - -| `overrideHonorLabels` -| `boolean` -| OverrideHonorLabels if set to true overrides all user configured honor_labels. If HonorLabels is set in ServiceMonitor or PodMonitor to true, this overrides honor_labels to false. - -| `overrideHonorTimestamps` -| `boolean` -| OverrideHonorTimestamps allows to globally enforce honoring timestamps in all scrape configs. - -| `paused` -| `boolean` -| When a Prometheus deployment is paused, no actions except for deletion will be performed on the underlying objects. - -| `podMetadata` -| `object` -| PodMetadata configures Labels and Annotations which are propagated to the prometheus pods. - -| `podMonitorNamespaceSelector` -| `object` -| Namespaces to be selected for PodMonitor discovery. If nil, only check own namespace. - -| `podMonitorSelector` -| `object` -| *Experimental* PodMonitors to be selected for target discovery. *Deprecated:* if neither this nor serviceMonitorSelector are specified, configuration is unmanaged. - -| `portName` -| `string` -| Port name used for the pods and governing service. This defaults to web - -| `priorityClassName` -| `string` -| Priority class assigned to the Pods - -| `probeNamespaceSelector` -| `object` -| *Experimental* Namespaces to be selected for Probe discovery. If nil, only check own namespace. - -| `probeSelector` -| `object` -| *Experimental* Probes to be selected for target discovery. - -| `prometheusExternalLabelName` -| `string` -| Name of Prometheus external label used to denote Prometheus instance name. Defaults to the value of `prometheus`. External label will _not_ be added when value is set to empty string (`""`). - -| `prometheusRulesExcludedFromEnforce` -| `array` -| PrometheusRulesExcludedFromEnforce - list of prometheus rules to be excluded from enforcing of adding namespace labels. Works only if enforcedNamespaceLabel set to true. Make sure both ruleNamespace and ruleName are set for each pair - -| `prometheusRulesExcludedFromEnforce[]` -| `object` -| PrometheusRuleExcludeConfig enables users to configure excluded PrometheusRule names and their namespaces to be ignored while enforcing namespace label for alerts and metrics. - -| `query` -| `object` -| QuerySpec defines the query command line flags when starting Prometheus. - -| `queryLogFile` -| `string` -| QueryLogFile specifies the file to which PromQL queries are logged. Note that this location must be writable, and can be persisted using an attached volume. Alternatively, the location can be set to a stdout location such as `/dev/stdout` to log querie information to the default Prometheus log stream. This is only available in versions of Prometheus >= 2.16.0. For more details, see the Prometheus docs (https://prometheus.io/docs/guides/query-log/) - -| `remoteRead` -| `array` -| If specified, the remote_read spec. This is an experimental feature, it may change in any upcoming release in a breaking way. - -| `remoteRead[]` -| `object` -| RemoteReadSpec defines the remote_read configuration for prometheus. - -| `remoteWrite` -| `array` -| If specified, the remote_write spec. This is an experimental feature, it may change in any upcoming release in a breaking way. - -| `remoteWrite[]` -| `object` -| RemoteWriteSpec defines the remote_write configuration for prometheus. - -| `replicaExternalLabelName` -| `string` -| Name of Prometheus external label used to denote replica name. Defaults to the value of `prometheus_replica`. External label will _not_ be added when value is set to empty string (`""`). - -| `replicas` -| `integer` -| Number of replicas of each shard to deploy for a Prometheus deployment. Number of replicas multiplied by shards is the total number of Pods created. - -| `resources` -| `object` -| Define resources requests and limits for single Pods. - -| `retention` -| `string` -| Time duration Prometheus shall retain data for. Default is '24h', and must match the regular expression `[0-9]+(ms\|s\|m\|h\|d\|w\|y)` (milliseconds seconds minutes hours days weeks years). - -| `retentionSize` -| `string` -| Maximum amount of disk space used by blocks. - -| `routePrefix` -| `string` -| The route prefix Prometheus registers HTTP handlers for. This is useful, if using ExternalURL and a proxy is rewriting HTTP routes of a request, and the actual ExternalURL is still true, but the server serves requests under a different route prefix. For example for use with `kubectl proxy`. - -| `ruleNamespaceSelector` -| `object` -| Namespaces to be selected for PrometheusRules discovery. If unspecified, only the same namespace as the Prometheus object is in is used. - -| `ruleSelector` -| `object` -| A selector to select which PrometheusRules to mount for loading alerting/recording rules from. Until (excluding) Prometheus Operator v0.24.0 Prometheus Operator will migrate any legacy rule ConfigMaps to PrometheusRule custom resources selected by RuleSelector. Make sure it does not match any config maps that you do not want to be migrated. - -| `rules` -| `object` -| /--rules.*/ command-line arguments. - -| `scrapeInterval` -| `string` -| Interval between consecutive scrapes. - -| `scrapeTimeout` -| `string` -| Number of seconds to wait for target to respond before erroring. - -| `secrets` -| `array (string)` -| Secrets is a list of Secrets in the same namespace as the Prometheus object, which shall be mounted into the Prometheus Pods. The Secrets are mounted into /etc/prometheus/secrets/<secret-name>. - -| `securityContext` -| `object` -| SecurityContext holds pod-level security attributes and common container settings. This defaults to the default PodSecurityContext. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the name of the ServiceAccount to use to run the Prometheus Pods. - -| `serviceMonitorNamespaceSelector` -| `object` -| Namespaces to be selected for ServiceMonitor discovery. If nil, only check own namespace. - -| `serviceMonitorSelector` -| `object` -| ServiceMonitors to be selected for target discovery. *Deprecated:* if neither this nor podMonitorSelector are specified, configuration is unmanaged. - -| `sha` -| `string` -| SHA of Prometheus container image to be deployed. Defaults to the value of `version`. Similar to a tag, but the SHA explicitly deploys an immutable container image. Version and Tag are ignored if SHA is set. Deprecated: use 'image' instead. The image digest can be specified as part of the image URL. - -| `shards` -| `integer` -| EXPERIMENTAL: Number of shards to distribute targets onto. Number of replicas multiplied by shards is the total number of Pods created. Note that scaling down shards will not reshard data onto remaining instances, it must be manually moved. Increasing shards will not reshard data either but it will continue to be available from the same instances. To query globally use Thanos sidecar and Thanos querier or remote write data to a central location. Sharding is done on the content of the `__address__` target meta-label. - -| `storage` -| `object` -| Storage spec to specify how storage shall be used. - -| `tag` -| `string` -| Tag of Prometheus container image to be deployed. Defaults to the value of `version`. Version is ignored if Tag is set. Deprecated: use 'image' instead. The image tag can be specified as part of the image URL. - -| `thanos` -| `object` -| Thanos configuration allows configuring various aspects of a Prometheus server in a Thanos environment. - This section is experimental, it may change significantly without deprecation notice in any release. - This is experimental and may change significantly without backward compatibility in any release. - -| `tolerations` -| `array` -| If specified, the pod's tolerations. - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -| `topologySpreadConstraints` -| `array` -| If specified, the pod's topology spread constraints. - -| `topologySpreadConstraints[]` -| `object` -| TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -| `version` -| `string` -| Version of Prometheus to be deployed. - -| `volumeMounts` -| `array` -| VolumeMounts allows configuration of additional VolumeMounts on the output StatefulSet definition. VolumeMounts specified will be appended to other VolumeMounts in the prometheus container, that are generated as a result of StorageSpec objects. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `volumes` -| `array` -| Volumes allows configuration of additional volumes on the output StatefulSet definition. Volumes specified will be appended to other volumes that are generated as a result of StorageSpec objects. - -| `volumes[]` -| `object` -| Volume represents a named volume in a pod that may be accessed by any container in the pod. - -| `walCompression` -| `boolean` -| Enable compression of the write-ahead log using Snappy. This flag is only available in versions of Prometheus >= 2.11.0. - -| `web` -| `object` -| WebSpec defines the web command line flags when starting Prometheus. - -|=== -..spec.additionalAlertManagerConfigs -Description:: - AdditionalAlertManagerConfigs allows specifying a key of a Secret containing additional Prometheus AlertManager configurations. AlertManager configurations specified are appended to the configurations generated by the Prometheus Operator. Job configurations specified must have the form as specified in the official Prometheus documentation: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alertmanager_config. As AlertManager configs are appended, the user is responsible to make sure it is valid. Note that using this feature may expose the possibility to break upgrades of Prometheus. It is advised to review Prometheus release notes to ensure that no incompatible AlertManager configs are going to break Prometheus after the upgrade. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.additionalAlertRelabelConfigs -Description:: - AdditionalAlertRelabelConfigs allows specifying a key of a Secret containing additional Prometheus alert relabel configurations. Alert relabel configurations specified are appended to the configurations generated by the Prometheus Operator. Alert relabel configurations specified must have the form as specified in the official Prometheus documentation: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#alert_relabel_configs. As alert relabel configs are appended, the user is responsible to make sure it is valid. Note that using this feature may expose the possibility to break upgrades of Prometheus. It is advised to review Prometheus release notes to ensure that no incompatible alert relabel configs are going to break Prometheus after the upgrade. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.additionalScrapeConfigs -Description:: - AdditionalScrapeConfigs allows specifying a key of a Secret containing additional Prometheus scrape configurations. Scrape configurations specified are appended to the configurations generated by the Prometheus Operator. Job configurations specified must have the form as specified in the official Prometheus documentation: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config. As scrape configs are appended, the user is responsible to make sure it is valid. Note that using this feature may expose the possibility to break upgrades of Prometheus. It is advised to review Prometheus release notes to ensure that no incompatible scrape configs are going to break Prometheus after the upgrade. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.affinity -Description:: - If specified, the pod's scheduling constraints. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeAffinity` -| `object` -| Describes node affinity scheduling rules for the pod. - -| `podAffinity` -| `object` -| Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -| `podAntiAffinity` -| `object` -| Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -|=== -..spec.affinity.nodeAffinity -Description:: - Describes node affinity scheduling rules for the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `object` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -Type:: - `object` - -Required:: - - `preference` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preference` -| `object` -| A node selector term, associated with the corresponding weight. - -| `weight` -| `integer` -| Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference -Description:: - A node selector term, associated with the corresponding weight. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -Type:: - `object` - -Required:: - - `nodeSelectorTerms` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelectorTerms` -| `array` -| Required. A list of node selector terms. The terms are ORed. - -| `nodeSelectorTerms[]` -| `object` -| A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms -Description:: - Required. A list of node selector terms. The terms are ORed. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[] -Description:: - A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity -Description:: - Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity -Description:: - Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.alerting -Description:: - Define details regarding alerting. - -Type:: - `object` - -Required:: - - `alertmanagers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `alertmanagers` -| `array` -| AlertmanagerEndpoints Prometheus should fire alerts against. - -| `alertmanagers[]` -| `object` -| AlertmanagerEndpoints defines a selection of a single Endpoints object containing alertmanager IPs to fire alerts against. - -|=== -..spec.alerting.alertmanagers -Description:: - AlertmanagerEndpoints Prometheus should fire alerts against. - -Type:: - `array` - - - - -..spec.alerting.alertmanagers[] -Description:: - AlertmanagerEndpoints defines a selection of a single Endpoints object containing alertmanager IPs to fire alerts against. - -Type:: - `object` - -Required:: - - `name` - - `namespace` - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the Alertmanager API that Prometheus uses to send alerts. It can be "v1" or "v2". - -| `bearerTokenFile` -| `string` -| BearerTokenFile to read from filesystem to use when authenticating to Alertmanager. - -| `name` -| `string` -| Name of Endpoints object in Namespace. - -| `namespace` -| `string` -| Namespace of Endpoints object. - -| `pathPrefix` -| `string` -| Prefix for the HTTP path alerts are pushed to. - -| `port` -| `integer-or-string` -| Port the Alertmanager API is exposed on. - -| `scheme` -| `string` -| Scheme to use when firing alerts. - -| `timeout` -| `string` -| Timeout is a per-target Alertmanager timeout when pushing alerts. - -| `tlsConfig` -| `object` -| TLS Config to use for alertmanager connection. - -|=== -..spec.alerting.alertmanagers[].tlsConfig -Description:: - TLS Config to use for alertmanager connection. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `caFile` -| `string` -| Path to the CA cert in the Prometheus container to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `certFile` -| `string` -| Path to the client cert file in the Prometheus container for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keyFile` -| `string` -| Path to the client key file in the Prometheus container for the targets. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.alerting.alertmanagers[].tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.alerting.alertmanagers[].tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.alerting.alertmanagers[].tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.alerting.alertmanagers[].tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.alerting.alertmanagers[].tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.alerting.alertmanagers[].tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.alerting.alertmanagers[].tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.apiserverConfig -Description:: - APIServerConfig allows specifying a host and auth methods to access apiserver. If left empty, Prometheus is assumed to run inside of the cluster and will discover API servers automatically and use the pod's CA certificate and bearer token file at /var/run/secrets/kubernetes.io/serviceaccount/. - -Type:: - `object` - -Required:: - - `host` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth allow an endpoint to authenticate over basic authentication - -| `bearerToken` -| `string` -| Bearer token for accessing apiserver. - -| `bearerTokenFile` -| `string` -| File to read bearer token for accessing apiserver. - -| `host` -| `string` -| Host of apiserver. A valid string consisting of a hostname or IP followed by an optional port number - -| `tlsConfig` -| `object` -| TLS Config to use for accessing apiserver. - -|=== -..spec.apiserverConfig.basicAuth -Description:: - BasicAuth allow an endpoint to authenticate over basic authentication - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.apiserverConfig.basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.apiserverConfig.basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.apiserverConfig.tlsConfig -Description:: - TLS Config to use for accessing apiserver. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `caFile` -| `string` -| Path to the CA cert in the Prometheus container to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `certFile` -| `string` -| Path to the client cert file in the Prometheus container for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keyFile` -| `string` -| Path to the client key file in the Prometheus container for the targets. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.apiserverConfig.tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.apiserverConfig.tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.apiserverConfig.tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.apiserverConfig.tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.apiserverConfig.tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.apiserverConfig.tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.apiserverConfig.tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.arbitraryFSAccessThroughSMs -Description:: - ArbitraryFSAccessThroughSMs configures whether configuration based on a service monitor can access arbitrary files on the file system of the Prometheus container e.g. bearer token files. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `deny` -| `boolean` -| - -|=== -..spec.containers -Description:: - Containers allows injecting additional containers or modifying operator generated containers. This can be used to allow adding an authentication proxy to a Prometheus pod or to change the behavior of an operator generated container. Containers described here modify an operator generated container if they share the same name and modifications are done via a strategic merge patch. The current container names are: `prometheus`, `config-reloader`, and `thanos-sidecar`. Overriding containers is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -Type:: - `array` - - - - -..spec.containers[] -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| `object` -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| `array` -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| `object` -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| `object` -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| `object` -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.containers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.containers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.containers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.containers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.containers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.containers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.containers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.containers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.containers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.containers[].lifecycle -Description:: - Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.containers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.containers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.containers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].livenessProbe -Description:: - Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].ports -Description:: - List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.containers[].readinessProbe -Description:: - Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].resources -Description:: - Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.containers[].securityContext -Description:: - Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.containers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.containers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.containers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.containers[].startupProbe -Description:: - StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.containers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.containers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.imagePullSecrets -Description:: - An optional list of references to secrets in the same namespace to use for pulling prometheus and alertmanager images from registries see http://kubernetes.io/docs/user-guide/images#specifying-imagepullsecrets-on-a-pod - -Type:: - `array` - - - - -..spec.imagePullSecrets[] -Description:: - LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.initContainers -Description:: - InitContainers allows adding initContainers to the pod definition. Those can be used to e.g. fetch secrets for injection into the Prometheus configuration from external sources. Any errors during the execution of an initContainer will lead to a restart of the Pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ Using initContainers for any use case other then secret fetching is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -Type:: - `array` - - - - -..spec.initContainers[] -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| `object` -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| `array` -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| `object` -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| `object` -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| `object` -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.initContainers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.initContainers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.initContainers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.initContainers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.initContainers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.initContainers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.initContainers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.initContainers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.initContainers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.initContainers[].lifecycle -Description:: - Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.initContainers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.initContainers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.initContainers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].livenessProbe -Description:: - Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].ports -Description:: - List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.initContainers[].readinessProbe -Description:: - Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].resources -Description:: - Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.initContainers[].securityContext -Description:: - Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.initContainers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.initContainers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.initContainers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.initContainers[].startupProbe -Description:: - StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.initContainers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.initContainers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.podMetadata -Description:: - PodMetadata configures Labels and Annotations which are propagated to the prometheus pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -|=== -..spec.podMonitorNamespaceSelector -Description:: - Namespaces to be selected for PodMonitor discovery. If nil, only check own namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.podMonitorNamespaceSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.podMonitorNamespaceSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.podMonitorSelector -Description:: - *Experimental* PodMonitors to be selected for target discovery. *Deprecated:* if neither this nor serviceMonitorSelector are specified, configuration is unmanaged. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.podMonitorSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.podMonitorSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.probeNamespaceSelector -Description:: - *Experimental* Namespaces to be selected for Probe discovery. If nil, only check own namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.probeNamespaceSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.probeNamespaceSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.probeSelector -Description:: - *Experimental* Probes to be selected for target discovery. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.probeSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.probeSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.prometheusRulesExcludedFromEnforce -Description:: - PrometheusRulesExcludedFromEnforce - list of prometheus rules to be excluded from enforcing of adding namespace labels. Works only if enforcedNamespaceLabel set to true. Make sure both ruleNamespace and ruleName are set for each pair - -Type:: - `array` - - - - -..spec.prometheusRulesExcludedFromEnforce[] -Description:: - PrometheusRuleExcludeConfig enables users to configure excluded PrometheusRule names and their namespaces to be ignored while enforcing namespace label for alerts and metrics. - -Type:: - `object` - -Required:: - - `ruleName` - - `ruleNamespace` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ruleName` -| `string` -| RuleNamespace - name of excluded rule - -| `ruleNamespace` -| `string` -| RuleNamespace - namespace of excluded rule - -|=== -..spec.query -Description:: - QuerySpec defines the query command line flags when starting Prometheus. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lookbackDelta` -| `string` -| The delta difference allowed for retrieving metrics during expression evaluations. - -| `maxConcurrency` -| `integer` -| Number of concurrent queries that can be run at once. - -| `maxSamples` -| `integer` -| Maximum number of samples a single query can load into memory. Note that queries will fail if they would load more samples than this into memory, so this also limits the number of samples a query can return. - -| `timeout` -| `string` -| Maximum time a query may take before being aborted. - -|=== -..spec.remoteRead -Description:: - If specified, the remote_read spec. This is an experimental feature, it may change in any upcoming release in a breaking way. - -Type:: - `array` - - - - -..spec.remoteRead[] -Description:: - RemoteReadSpec defines the remote_read configuration for prometheus. - -Type:: - `object` - -Required:: - - `url` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the URL. - -| `bearerToken` -| `string` -| bearer token for remote read. - -| `bearerTokenFile` -| `string` -| File to read bearer token for remote read. - -| `name` -| `string` -| The name of the remote read queue, must be unique if specified. The name is used in metrics and logging in order to differentiate read configurations. Only valid in Prometheus versions 2.15.0 and newer. - -| `proxyUrl` -| `string` -| Optional ProxyURL - -| `readRecent` -| `boolean` -| Whether reads should be made for queries for time ranges that the local storage should have complete data for. - -| `remoteTimeout` -| `string` -| Timeout for requests to the remote read endpoint. - -| `requiredMatchers` -| `object (string)` -| An optional list of equality matchers which have to be present in a selector to query the remote read endpoint. - -| `tlsConfig` -| `object` -| TLS Config to use for remote read. - -| `url` -| `string` -| The URL of the endpoint to send samples to. - -|=== -..spec.remoteRead[].basicAuth -Description:: - BasicAuth for the URL. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.remoteRead[].basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteRead[].basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteRead[].tlsConfig -Description:: - TLS Config to use for remote read. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `caFile` -| `string` -| Path to the CA cert in the Prometheus container to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `certFile` -| `string` -| Path to the client cert file in the Prometheus container for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keyFile` -| `string` -| Path to the client key file in the Prometheus container for the targets. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.remoteRead[].tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.remoteRead[].tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.remoteRead[].tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteRead[].tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.remoteRead[].tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.remoteRead[].tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteRead[].tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteWrite -Description:: - If specified, the remote_write spec. This is an experimental feature, it may change in any upcoming release in a breaking way. - -Type:: - `array` - - - - -..spec.remoteWrite[] -Description:: - RemoteWriteSpec defines the remote_write configuration for prometheus. - -Type:: - `object` - -Required:: - - `url` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth for the URL. - -| `bearerToken` -| `string` -| File to read bearer token for remote write. - -| `bearerTokenFile` -| `string` -| File to read bearer token for remote write. - -| `name` -| `string` -| The name of the remote write queue, must be unique if specified. The name is used in metrics and logging in order to differentiate queues. Only valid in Prometheus versions 2.15.0 and newer. - -| `proxyUrl` -| `string` -| Optional ProxyURL - -| `queueConfig` -| `object` -| QueueConfig allows tuning of the remote write queue parameters. - -| `remoteTimeout` -| `string` -| Timeout for requests to the remote write endpoint. - -| `tlsConfig` -| `object` -| TLS Config to use for remote write. - -| `url` -| `string` -| The URL of the endpoint to send samples to. - -| `writeRelabelConfigs` -| `array` -| The list of remote write relabel configurations. - -| `writeRelabelConfigs[]` -| `object` -| RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -|=== -..spec.remoteWrite[].basicAuth -Description:: - BasicAuth for the URL. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.remoteWrite[].basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteWrite[].basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteWrite[].queueConfig -Description:: - QueueConfig allows tuning of the remote write queue parameters. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `batchSendDeadline` -| `string` -| BatchSendDeadline is the maximum time a sample will wait in buffer. - -| `capacity` -| `integer` -| Capacity is the number of samples to buffer per shard before we start dropping them. - -| `maxBackoff` -| `string` -| MaxBackoff is the maximum retry delay. - -| `maxRetries` -| `integer` -| MaxRetries is the maximum number of times to retry a batch on recoverable errors. - -| `maxSamplesPerSend` -| `integer` -| MaxSamplesPerSend is the maximum number of samples per send. - -| `maxShards` -| `integer` -| MaxShards is the maximum number of shards, i.e. amount of concurrency. - -| `minBackoff` -| `string` -| MinBackoff is the initial retry delay. Gets doubled for every retry. - -| `minShards` -| `integer` -| MinShards is the minimum number of shards, i.e. amount of concurrency. - -|=== -..spec.remoteWrite[].tlsConfig -Description:: - TLS Config to use for remote write. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `caFile` -| `string` -| Path to the CA cert in the Prometheus container to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `certFile` -| `string` -| Path to the client cert file in the Prometheus container for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keyFile` -| `string` -| Path to the client key file in the Prometheus container for the targets. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.remoteWrite[].tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.remoteWrite[].tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.remoteWrite[].tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteWrite[].tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.remoteWrite[].tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.remoteWrite[].tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteWrite[].tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.remoteWrite[].writeRelabelConfigs -Description:: - The list of remote write relabel configurations. - -Type:: - `array` - - - - -..spec.remoteWrite[].writeRelabelConfigs[] -Description:: - RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `action` -| `string` -| Action to perform based on regex matching. Default is 'replace' - -| `modulus` -| `integer` -| Modulus to take of the hash of the source label values. - -| `regex` -| `string` -| Regular expression against which the extracted value is matched. Default is '(.*)' - -| `replacement` -| `string` -| Replacement value against which a regex replace is performed if the regular expression matches. Regex capture groups are available. Default is '$1' - -| `separator` -| `string` -| Separator placed between concatenated source label values. default is ';'. - -| `sourceLabels` -| `array (string)` -| The source labels select values from existing labels. Their content is concatenated using the configured separator and matched against the configured regular expression for the replace, keep, and drop actions. - -| `targetLabel` -| `string` -| Label to which the resulting value is written in a replace action. It is mandatory for replace actions. Regex capture groups are available. - -|=== -..spec.resources -Description:: - Define resources requests and limits for single Pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.ruleNamespaceSelector -Description:: - Namespaces to be selected for PrometheusRules discovery. If unspecified, only the same namespace as the Prometheus object is in is used. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.ruleNamespaceSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.ruleNamespaceSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.ruleSelector -Description:: - A selector to select which PrometheusRules to mount for loading alerting/recording rules from. Until (excluding) Prometheus Operator v0.24.0 Prometheus Operator will migrate any legacy rule ConfigMaps to PrometheusRule custom resources selected by RuleSelector. Make sure it does not match any config maps that you do not want to be migrated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.ruleSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.ruleSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.rules -Description:: - /--rules.*/ command-line arguments. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `alert` -| `object` -| /--rules.alert.*/ command-line arguments - -|=== -..spec.rules.alert -Description:: - /--rules.alert.*/ command-line arguments - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `forGracePeriod` -| `string` -| Minimum duration between alert and restored 'for' state. This is maintained only for alerts with configured 'for' time greater than grace period. - -| `forOutageTolerance` -| `string` -| Max time to tolerate prometheus outage for restoring 'for' state of alert. - -| `resendDelay` -| `string` -| Minimum amount of time to wait before resending an alert to Alertmanager. - -|=== -..spec.securityContext -Description:: - SecurityContext holds pod-level security attributes and common container settings. This defaults to the default PodSecurityContext. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsGroup` -| `integer` -| A special supplemental group that applies to all containers in a pod. Some volume types allow the Kubelet to change the ownership of that volume to be owned by the pod: - 1. The owning GID will be the FSGroup 2. The setgid bit is set (new files created in the volume will be owned by FSGroup) 3. The permission bits are OR'd with rw-rw---- - If unset, the Kubelet will not modify the ownership and permissions of any volume. - -| `fsGroupChangePolicy` -| `string` -| fsGroupChangePolicy defines behavior of changing ownership and permission of the volume before being exposed inside Pod. This field will only apply to volume types which support fsGroup based ownership(and permissions). It will have no effect on ephemeral volume types such as: secret, configmaps and emptydir. Valid values are "OnRootMismatch" and "Always". If not specified defaults to "Always". - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `supplementalGroups` -| `array (integer)` -| A list of groups applied to the first process run in each container, in addition to the container's primary GID. If unspecified, no groups will be added to any container. - -| `sysctls` -| `array` -| Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -| `sysctls[]` -| `object` -| Sysctl defines a kernel parameter to be set - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.securityContext.sysctls -Description:: - Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -Type:: - `array` - - - - -..spec.securityContext.sysctls[] -Description:: - Sysctl defines a kernel parameter to be set - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of a property to set - -| `value` -| `string` -| Value of a property to set - -|=== -..spec.securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.serviceMonitorNamespaceSelector -Description:: - Namespaces to be selected for ServiceMonitor discovery. If nil, only check own namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.serviceMonitorNamespaceSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.serviceMonitorNamespaceSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.serviceMonitorSelector -Description:: - ServiceMonitors to be selected for target discovery. *Deprecated:* if neither this nor podMonitorSelector are specified, configuration is unmanaged. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.serviceMonitorSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.serviceMonitorSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.storage -Description:: - Storage spec to specify how storage shall be used. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `disableMountSubPath` -| `boolean` -| Deprecated: subPath usage will be disabled by default in a future release, this option will become unnecessary. DisableMountSubPath allows to remove any subPath usage in volume mounts. - -| `emptyDir` -| `object` -| EmptyDirVolumeSource to be used by the Prometheus StatefulSets. If specified, used in place of any volumeClaimTemplate. More info: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir - -| `volumeClaimTemplate` -| `object` -| A PVC spec to be used by the Prometheus StatefulSets. - -|=== -..spec.storage.emptyDir -Description:: - EmptyDirVolumeSource to be used by the Prometheus StatefulSets. If specified, used in place of any volumeClaimTemplate. More info: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| `integer-or-string` -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== -..spec.storage.volumeClaimTemplate -Description:: - A PVC spec to be used by the Prometheus StatefulSets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| `object` -| EmbeddedMetadata contains metadata relevant to an EmbeddedResource. - -| `spec` -| `object` -| Spec defines the desired characteristics of a volume requested by a pod author. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `status` -| `object` -| Status represents the current information/status of a persistent volume claim. Read-only. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -|=== -..spec.storage.volumeClaimTemplate.metadata -Description:: - EmbeddedMetadata contains metadata relevant to an EmbeddedResource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -|=== -..spec.storage.volumeClaimTemplate.spec -Description:: - Spec defines the desired characteristics of a volume requested by a pod author. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `dataSource` -| `object` -| This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot - Beta) * An existing PVC (PersistentVolumeClaim) * An existing custom resource/object that implements data population (Alpha) In order to use VolumeSnapshot object types, the appropriate feature gate must be enabled (VolumeSnapshotDataSource or AnyVolumeDataSource) If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. If the specified data source is not supported, the volume will not be created and the failure will be reported as an event. In the future, we plan to support more data source types and the behavior of the provisioner may change. - -| `resources` -| `object` -| Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -| `selector` -| `object` -| A label query over volumes to consider for binding. - -| `storageClassName` -| `string` -| Name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 - -| `volumeMode` -| `string` -| volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. - -| `volumeName` -| `string` -| VolumeName is the binding reference to the PersistentVolume backing this claim. - -|=== -..spec.storage.volumeClaimTemplate.spec.dataSource -Description:: - This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot - Beta) * An existing PVC (PersistentVolumeClaim) * An existing custom resource/object that implements data population (Alpha) In order to use VolumeSnapshot object types, the appropriate feature gate must be enabled (VolumeSnapshotDataSource or AnyVolumeDataSource) If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. If the specified data source is not supported, the volume will not be created and the failure will be reported as an event. In the future, we plan to support more data source types and the behavior of the provisioner may change. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required. - -| `kind` -| `string` -| Kind is the type of resource being referenced - -| `name` -| `string` -| Name is the name of resource being referenced - -|=== -..spec.storage.volumeClaimTemplate.spec.resources -Description:: - Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.storage.volumeClaimTemplate.spec.selector -Description:: - A label query over volumes to consider for binding. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.storage.volumeClaimTemplate.spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.storage.volumeClaimTemplate.spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.storage.volumeClaimTemplate.status -Description:: - Status represents the current information/status of a persistent volume claim. Read-only. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the actual access modes the volume backing the PVC has. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `capacity` -| `integer-or-string` -| Represents the actual resources of the underlying volume. - -| `conditions` -| `array` -| Current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'. - -| `conditions[]` -| `object` -| PersistentVolumeClaimCondition contails details about state of pvc - -| `phase` -| `string` -| Phase represents the current phase of PersistentVolumeClaim. - -|=== -..spec.storage.volumeClaimTemplate.status.conditions -Description:: - Current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'. - -Type:: - `array` - - - - -..spec.storage.volumeClaimTemplate.status.conditions[] -Description:: - PersistentVolumeClaimCondition contails details about state of pvc - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| `string` -| Last time we probed the condition. - -| `lastTransitionTime` -| `string` -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| Human-readable message indicating details about last transition. - -| `reason` -| `string` -| Unique, this should be a short, machine understandable string that gives the reason for condition's last transition. If it reports "ResizeStarted" that means the underlying persistent volume is being resized. - -| `status` -| `string` -| - -| `type` -| `string` -| PersistentVolumeClaimConditionType is a valid value of PersistentVolumeClaimCondition.Type - -|=== -..spec.thanos -Description:: - Thanos configuration allows configuring various aspects of a Prometheus server in a Thanos environment. - This section is experimental, it may change significantly without deprecation notice in any release. - This is experimental and may change significantly without backward compatibility in any release. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `baseImage` -| `string` -| Thanos base image if other than default. Deprecated: use 'image' instead - -| `grpcServerTlsConfig` -| `object` -| GRPCServerTLSConfig configures the gRPC server from which Thanos Querier reads recorded rule data. Note: Currently only the CAFile, CertFile, and KeyFile fields are supported. Maps to the '--grpc-server-tls-*' CLI args. - -| `image` -| `string` -| Image if specified has precedence over baseImage, tag and sha combinations. Specifying the version is still necessary to ensure the Prometheus Operator knows what version of Thanos is being configured. - -| `listenLocal` -| `boolean` -| ListenLocal makes the Thanos sidecar listen on loopback, so that it does not bind against the Pod IP. - -| `logFormat` -| `string` -| LogFormat for Thanos sidecar to be configured with. - -| `logLevel` -| `string` -| LogLevel for Thanos sidecar to be configured with. - -| `minTime` -| `string` -| MinTime for Thanos sidecar to be configured with. Option can be a constant time in RFC3339 format or time duration relative to current time, such as -1d or 2h45m. Valid duration units are ms, s, m, h, d, w, y. - -| `objectStorageConfig` -| `object` -| ObjectStorageConfig configures object storage in Thanos. Alternative to ObjectStorageConfigFile, and lower order priority. - -| `objectStorageConfigFile` -| `string` -| ObjectStorageConfigFile specifies the path of the object storage configuration file. When used alongside with ObjectStorageConfig, ObjectStorageConfigFile takes precedence. - -| `resources` -| `object` -| Resources defines the resource requirements for the Thanos sidecar. If not provided, no requests/limits will be set - -| `sha` -| `string` -| SHA of Thanos container image to be deployed. Defaults to the value of `version`. Similar to a tag, but the SHA explicitly deploys an immutable container image. Version and Tag are ignored if SHA is set. Deprecated: use 'image' instead. The image digest can be specified as part of the image URL. - -| `tag` -| `string` -| Tag of Thanos sidecar container image to be deployed. Defaults to the value of `version`. Version is ignored if Tag is set. Deprecated: use 'image' instead. The image tag can be specified as part of the image URL. - -| `tracingConfig` -| `object` -| TracingConfig configures tracing in Thanos. This is an experimental feature, it may change in any upcoming release in a breaking way. - -| `version` -| `string` -| Version describes the version of Thanos to use. - -|=== -..spec.thanos.grpcServerTlsConfig -Description:: - GRPCServerTLSConfig configures the gRPC server from which Thanos Querier reads recorded rule data. Note: Currently only the CAFile, CertFile, and KeyFile fields are supported. Maps to the '--grpc-server-tls-*' CLI args. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `caFile` -| `string` -| Path to the CA cert in the Prometheus container to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `certFile` -| `string` -| Path to the client cert file in the Prometheus container for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keyFile` -| `string` -| Path to the client key file in the Prometheus container for the targets. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.thanos.grpcServerTlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.thanos.grpcServerTlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.thanos.grpcServerTlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.thanos.grpcServerTlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.thanos.grpcServerTlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.thanos.grpcServerTlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.thanos.grpcServerTlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.thanos.objectStorageConfig -Description:: - ObjectStorageConfig configures object storage in Thanos. Alternative to ObjectStorageConfigFile, and lower order priority. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.thanos.resources -Description:: - Resources defines the resource requirements for the Thanos sidecar. If not provided, no requests/limits will be set - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.thanos.tracingConfig -Description:: - TracingConfig configures tracing in Thanos. This is an experimental feature, it may change in any upcoming release in a breaking way. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.tolerations -Description:: - If specified, the pod's tolerations. - -Type:: - `array` - - - - -..spec.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== -..spec.topologySpreadConstraints -Description:: - If specified, the pod's topology spread constraints. - -Type:: - `array` - - - - -..spec.topologySpreadConstraints[] -Description:: - TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -Type:: - `object` - -Required:: - - `maxSkew` - - `topologyKey` - - `whenUnsatisfiable` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -| `maxSkew` -| `integer` -| MaxSkew describes the degree to which pods may be unevenly distributed. It's the maximum permitted difference between the number of matching pods in any two topology domains of a given topology type. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: \| zone1 \| zone2 \| zone3 \| \| P \| P \| \| - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. It's a required field. Default value is 1 and 0 is not allowed. - -| `topologyKey` -| `string` -| TopologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. We consider each <key, value> as a "bucket", and try to put balanced number of pods into each bucket. It's a required field. - -| `whenUnsatisfiable` -| `string` -| WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it - ScheduleAnyway tells the scheduler to still schedule it It's considered as "Unsatisfiable" if and only if placing incoming pod on any topology violates "MaxSkew". For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: \| zone1 \| zone2 \| zone3 \| \| P P P \| P \| P \| If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field. - -|=== -..spec.topologySpreadConstraints[].labelSelector -Description:: - LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.topologySpreadConstraints[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.topologySpreadConstraints[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.volumeMounts -Description:: - VolumeMounts allows configuration of additional VolumeMounts on the output StatefulSet definition. VolumeMounts specified will be appended to other VolumeMounts in the prometheus container, that are generated as a result of StorageSpec objects. - -Type:: - `array` - - - - -..spec.volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.volumes -Description:: - Volumes allows configuration of additional volumes on the output StatefulSet definition. Volumes specified will be appended to other volumes that are generated as a result of StorageSpec objects. - -Type:: - `array` - - - - -..spec.volumes[] -Description:: - Volume represents a named volume in a pod that may be accessed by any container in the pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `awsElasticBlockStore` -| `object` -| AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `azureDisk` -| `object` -| AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -| `azureFile` -| `object` -| AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -| `cephfs` -| `object` -| CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -| `cinder` -| `object` -| Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `configMap` -| `object` -| ConfigMap represents a configMap that should populate this volume - -| `csi` -| `object` -| CSI (Container Storage Interface) represents storage that is handled by an external CSI driver (Alpha feature). - -| `downwardAPI` -| `object` -| DownwardAPI represents downward API about the pod that should populate this volume - -| `emptyDir` -| `object` -| EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `fc` -| `object` -| FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -| `flexVolume` -| `object` -| FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -| `flocker` -| `object` -| Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -| `gcePersistentDisk` -| `object` -| GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `gitRepo` -| `object` -| GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -| `glusterfs` -| `object` -| Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -| `hostPath` -| `object` -| HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -| `iscsi` -| `object` -| ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -| `name` -| `string` -| Volume's name. Must be a DNS_LABEL and unique within the pod. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `nfs` -| `object` -| NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `persistentVolumeClaim` -| `object` -| PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `photonPersistentDisk` -| `object` -| PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -| `portworxVolume` -| `object` -| PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -| `projected` -| `object` -| Items for all in one resources secrets, configmaps, and downward API - -| `quobyte` -| `object` -| Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -| `rbd` -| `object` -| RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -| `scaleIO` -| `object` -| ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -| `secret` -| `object` -| Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -| `storageos` -| `object` -| StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -| `vsphereVolume` -| `object` -| VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -|=== -..spec.volumes[].awsElasticBlockStore -Description:: - AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). - -| `readOnly` -| `boolean` -| Specify "true" to force and set the ReadOnly property in VolumeMounts to "true". If omitted, the default is "false". More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `volumeID` -| `string` -| Unique ID of the persistent disk resource in AWS (Amazon EBS volume). More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -|=== -..spec.volumes[].azureDisk -Description:: - AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `diskName` - - `diskURI` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cachingMode` -| `string` -| Host Caching mode: None, Read Only, Read Write. - -| `diskName` -| `string` -| The Name of the data disk in the blob storage - -| `diskURI` -| `string` -| The URI the data disk in the blob storage - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `kind` -| `string` -| Expected values Shared: multiple blob disks per storage account Dedicated: single blob disk per storage account Managed: azure managed data disk (only in managed availability set). defaults to shared - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -|=== -..spec.volumes[].azureFile -Description:: - AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `secretName` - - `shareName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretName` -| `string` -| the name of secret that contains Azure Storage Account Name and Key - -| `shareName` -| `string` -| Share Name - -|=== -..spec.volumes[].cephfs -Description:: - CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `monitors` -| `array (string)` -| Required: Monitors is a collection of Ceph monitors More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `path` -| `string` -| Optional: Used as the mounted root, rather than the full Ceph tree, default is / - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretFile` -| `string` -| Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `user` -| `string` -| Optional: User is the rados user name, default is admin More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -|=== -..spec.volumes[].cephfs.secretRef -Description:: - Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].cinder -Description:: - Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `secretRef` -| `object` -| Optional: points to a secret object containing parameters used to connect to OpenStack. - -| `volumeID` -| `string` -| volume id used to identify the volume in cinder. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -|=== -..spec.volumes[].cinder.secretRef -Description:: - Optional: points to a secret object containing parameters used to connect to OpenStack. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].configMap -Description:: - ConfigMap represents a configMap that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.volumes[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].csi -Description:: - CSI (Container Storage Interface) represents storage that is handled by an external CSI driver (Alpha feature). - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the CSI driver that handles this volume. Consult with your admin for the correct name as registered in the cluster. - -| `fsType` -| `string` -| Filesystem type to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. - -| `nodePublishSecretRef` -| `object` -| NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeAttributes` -| `object (string)` -| VolumeAttributes stores driver-specific properties that are passed to the CSI driver. Consult your driver's documentation for supported values. - -|=== -..spec.volumes[].csi.nodePublishSecretRef -Description:: - NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].downwardAPI -Description:: - DownwardAPI represents downward API about the pod that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| Items is a list of downward API volume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.volumes[].downwardAPI.items -Description:: - Items is a list of downward API volume file - -Type:: - `array` - - - - -..spec.volumes[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.volumes[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.volumes[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.volumes[].emptyDir -Description:: - EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| `integer-or-string` -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== -..spec.volumes[].fc -Description:: - FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. TODO: how do we prevent errors in the filesystem from compromising the machine - -| `lun` -| `integer` -| Optional: FC target lun number - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `targetWWNs` -| `array (string)` -| Optional: FC target worldwide names (WWNs) - -| `wwids` -| `array (string)` -| Optional: FC volume world wide identifiers (wwids) Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously. - -|=== -..spec.volumes[].flexVolume -Description:: - FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the driver to use for this volume. - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script. - -| `options` -| `object (string)` -| Optional: Extra command options if any. - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -|=== -..spec.volumes[].flexVolume.secretRef -Description:: - Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].flocker -Description:: - Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `datasetName` -| `string` -| Name of the dataset stored as metadata -> name on the dataset for Flocker should be considered as deprecated - -| `datasetUUID` -| `string` -| UUID of the dataset. This is unique identifier of a Flocker dataset - -|=== -..spec.volumes[].gcePersistentDisk -Description:: - GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -Type:: - `object` - -Required:: - - `pdName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `pdName` -| `string` -| Unique name of the PD resource in GCE. Used to identify the disk in GCE. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -|=== -..spec.volumes[].gitRepo -Description:: - GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -Type:: - `object` - -Required:: - - `repository` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `directory` -| `string` -| Target directory name. Must not contain or start with '..'. If '.' is supplied, the volume directory will be the git repository. Otherwise, if specified, the volume will contain the git repository in the subdirectory with the given name. - -| `repository` -| `string` -| Repository URL - -| `revision` -| `string` -| Commit hash for the specified revision. - -|=== -..spec.volumes[].glusterfs -Description:: - Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -Type:: - `object` - -Required:: - - `endpoints` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `endpoints` -| `string` -| EndpointsName is the endpoint name that details Glusterfs topology. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `path` -| `string` -| Path is the Glusterfs volume path. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `readOnly` -| `boolean` -| ReadOnly here will force the Glusterfs volume to be mounted with read-only permissions. Defaults to false. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -|=== -..spec.volumes[].hostPath -Description:: - HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path of the directory on the host. If the path is a symlink, it will follow the link to the real path. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `type` -| `string` -| Type for HostPath Volume Defaults to "" More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -|=== -..spec.volumes[].iscsi -Description:: - ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -Type:: - `object` - -Required:: - - `iqn` - - `lun` - - `targetPortal` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `chapAuthDiscovery` -| `boolean` -| whether support iSCSI Discovery CHAP authentication - -| `chapAuthSession` -| `boolean` -| whether support iSCSI Session CHAP authentication - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi TODO: how do we prevent errors in the filesystem from compromising the machine - -| `initiatorName` -| `string` -| Custom iSCSI Initiator Name. If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface <target portal>:<volume name> will be created for the connection. - -| `iqn` -| `string` -| Target iSCSI Qualified Name. - -| `iscsiInterface` -| `string` -| iSCSI Interface Name that uses an iSCSI transport. Defaults to 'default' (tcp). - -| `lun` -| `integer` -| iSCSI Target Lun number. - -| `portals` -| `array (string)` -| iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. - -| `secretRef` -| `object` -| CHAP Secret for iSCSI target and initiator authentication - -| `targetPortal` -| `string` -| iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -|=== -..spec.volumes[].iscsi.secretRef -Description:: - CHAP Secret for iSCSI target and initiator authentication - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].nfs -Description:: - NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -Type:: - `object` - -Required:: - - `path` - - `server` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path that is exported by the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `readOnly` -| `boolean` -| ReadOnly here will force the NFS export to be mounted with read-only permissions. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `server` -| `string` -| Server is the hostname or IP address of the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -|=== -..spec.volumes[].persistentVolumeClaim -Description:: - PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - -Required:: - - `claimName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `claimName` -| `string` -| ClaimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `readOnly` -| `boolean` -| Will force the ReadOnly setting in VolumeMounts. Default false. - -|=== -..spec.volumes[].photonPersistentDisk -Description:: - PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `pdID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `pdID` -| `string` -| ID that identifies Photon Controller persistent disk - -|=== -..spec.volumes[].portworxVolume -Description:: - PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| FSType represents the filesystem type to mount Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `volumeID` -| `string` -| VolumeID uniquely identifies a Portworx volume - -|=== -..spec.volumes[].projected -Description:: - Items for all in one resources secrets, configmaps, and downward API - -Type:: - `object` - -Required:: - - `sources` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Mode bits to use on created files by default. Must be a value between 0 and 0777. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `sources` -| `array` -| list of volume projections - -| `sources[]` -| `object` -| Projection that may be projected along with other supported volume types - -|=== -..spec.volumes[].projected.sources -Description:: - list of volume projections - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[] -Description:: - Projection that may be projected along with other supported volume types - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| information about the configMap data to project - -| `downwardAPI` -| `object` -| information about the downwardAPI data to project - -| `secret` -| `object` -| information about the secret data to project - -| `serviceAccountToken` -| `object` -| information about the serviceAccountToken data to project - -|=== -..spec.volumes[].projected.sources[].configMap -Description:: - information about the configMap data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.volumes[].projected.sources[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].projected.sources[].downwardAPI -Description:: - information about the downwardAPI data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| Items is a list of DownwardAPIVolume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items -Description:: - Items is a list of DownwardAPIVolume file - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.volumes[].projected.sources[].secret -Description:: - information about the secret data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.volumes[].projected.sources[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].projected.sources[].serviceAccountToken -Description:: - information about the serviceAccountToken data to project - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audience` -| `string` -| Audience is the intended audience of the token. A recipient of a token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. The audience defaults to the identifier of the apiserver. - -| `expirationSeconds` -| `integer` -| ExpirationSeconds is the requested duration of validity of the service account token. As the token approaches expiration, the kubelet volume plugin will proactively rotate the service account token. The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.Defaults to 1 hour and must be at least 10 minutes. - -| `path` -| `string` -| Path is the path relative to the mount point of the file to project the token into. - -|=== -..spec.volumes[].quobyte -Description:: - Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `registry` - - `volume` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group to map volume access to Default is no group - -| `readOnly` -| `boolean` -| ReadOnly here will force the Quobyte volume to be mounted with read-only permissions. Defaults to false. - -| `registry` -| `string` -| Registry represents a single or multiple Quobyte Registry services specified as a string as host:port pair (multiple entries are separated with commas) which acts as the central registry for volumes - -| `tenant` -| `string` -| Tenant owning the given Quobyte volume in the Backend Used with dynamically provisioned Quobyte volumes, value is set by the plugin - -| `user` -| `string` -| User to map volume access to Defaults to serivceaccount user - -| `volume` -| `string` -| Volume is a string that references an already created Quobyte volume by name. - -|=== -..spec.volumes[].rbd -Description:: - RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -Type:: - `object` - -Required:: - - `image` - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd TODO: how do we prevent errors in the filesystem from compromising the machine - -| `image` -| `string` -| The rados image name. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `keyring` -| `string` -| Keyring is the path to key ring for RBDUser. Default is /etc/ceph/keyring. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `monitors` -| `array (string)` -| A collection of Ceph monitors. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `pool` -| `string` -| The rados pool name. Default is rbd. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `secretRef` -| `object` -| SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `user` -| `string` -| The rados user name. Default is admin. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -|=== -..spec.volumes[].rbd.secretRef -Description:: - SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].scaleIO -Description:: - ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - -Required:: - - `gateway` - - `secretRef` - - `system` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Default is "xfs". - -| `gateway` -| `string` -| The host address of the ScaleIO API Gateway. - -| `protectionDomain` -| `string` -| The name of the ScaleIO Protection Domain for the configured storage. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -| `sslEnabled` -| `boolean` -| Flag to enable/disable SSL communication with Gateway, default false - -| `storageMode` -| `string` -| Indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned. Default is ThinProvisioned. - -| `storagePool` -| `string` -| The ScaleIO Storage Pool associated with the protection domain. - -| `system` -| `string` -| The name of the storage system as configured in ScaleIO. - -| `volumeName` -| `string` -| The name of a volume already created in the ScaleIO system that is associated with this volume source. - -|=== -..spec.volumes[].scaleIO.secretRef -Description:: - SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].secret -Description:: - Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `optional` -| `boolean` -| Specify whether the Secret or its keys must be defined - -| `secretName` -| `string` -| Name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -|=== -..spec.volumes[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].storageos -Description:: - StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -| `volumeName` -| `string` -| VolumeName is the human-readable name of the StorageOS volume. Volume names are only unique within a namespace. - -| `volumeNamespace` -| `string` -| VolumeNamespace specifies the scope of the volume within StorageOS. If no namespace is specified then the Pod's namespace will be used. This allows the Kubernetes name scoping to be mirrored within StorageOS for tighter integration. Set VolumeName to any name to override the default behaviour. Set to "default" if you are not using namespaces within StorageOS. Namespaces that do not pre-exist within StorageOS will be created. - -|=== -..spec.volumes[].storageos.secretRef -Description:: - SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].vsphereVolume -Description:: - VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumePath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `storagePolicyID` -| `string` -| Storage Policy Based Management (SPBM) profile ID associated with the StoragePolicyName. - -| `storagePolicyName` -| `string` -| Storage Policy Based Management (SPBM) profile name. - -| `volumePath` -| `string` -| Path that identifies vSphere volume vmdk - -|=== -..spec.web -Description:: - WebSpec defines the web command line flags when starting Prometheus. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `pageTitle` -| `string` -| The prometheus web page title - -|=== -..status -Description:: - Most recent observed status of the Prometheus cluster. Read-only. Not included when requesting from the apiserver, only from the Prometheus Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -Type:: - `object` - -Required:: - - `availableReplicas` - - `paused` - - `replicas` - - `unavailableReplicas` - - `updatedReplicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| Total number of available pods (ready for at least minReadySeconds) targeted by this Prometheus deployment. - -| `paused` -| `boolean` -| Represents whether any actions on the underlying managed objects are being performed. Only delete actions will be performed. - -| `replicas` -| `integer` -| Total number of non-terminated pods targeted by this Prometheus deployment (their labels match the selector). - -| `unavailableReplicas` -| `integer` -| Total number of unavailable pods targeted by this Prometheus deployment. - -| `updatedReplicas` -| `integer` -| Total number of non-terminated pods targeted by this Prometheus deployment that have the desired version spec. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/monitoring.coreos.com/v1/prometheuses` -- `GET`: list objects of kind Prometheus -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/prometheuses` -- `DELETE`: delete collection of Prometheus -- `GET`: list objects of kind Prometheus -- `POST`: create Prometheus -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/prometheuses/{name}` -- `DELETE`: delete Prometheus -- `GET`: read the specified Prometheus -- `PATCH`: partially update the specified Prometheus -- `PUT`: replace the specified Prometheus - - -=== /apis/monitoring.coreos.com/v1/prometheuses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Prometheus - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#prometheuslist-monitoring-coreos-com-v1[`PrometheusList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/prometheuses - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Prometheus - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Prometheus - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#prometheuslist-monitoring-coreos-com-v1[`PrometheusList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create Prometheus - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| 202 - Accepted -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/prometheuses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Prometheus -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete Prometheus - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Prometheus - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Prometheus - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Prometheus - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`Prometheus monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc deleted file mode 100644 index ef01b4431bfe..000000000000 --- a/rest_api/monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc +++ /dev/null @@ -1,605 +0,0 @@ -[id="prometheusrule-monitoring-coreos-com-v1"] -= PrometheusRule [monitoring.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PrometheusRule defines recording and alerting rules for a Prometheus instance - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of desired alerting rule definitions for Prometheus. - -|=== -..spec -Description:: - Specification of desired alerting rule definitions for Prometheus. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `groups` -| `array` -| Content of Prometheus rule file - -| `groups[]` -| `object` -| RuleGroup is a list of sequentially evaluated recording and alerting rules. Note: PartialResponseStrategy is only used by ThanosRuler and will be ignored by Prometheus instances. Valid values for this field are 'warn' or 'abort'. More info: https://github.com/thanos-io/thanos/blob/master/docs/components/rule.md#partial-response - -|=== -..spec.groups -Description:: - Content of Prometheus rule file - -Type:: - `array` - - - - -..spec.groups[] -Description:: - RuleGroup is a list of sequentially evaluated recording and alerting rules. Note: PartialResponseStrategy is only used by ThanosRuler and will be ignored by Prometheus instances. Valid values for this field are 'warn' or 'abort'. More info: https://github.com/thanos-io/thanos/blob/master/docs/components/rule.md#partial-response - -Type:: - `object` - -Required:: - - `name` - - `rules` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `interval` -| `string` -| - -| `name` -| `string` -| - -| `partial_response_strategy` -| `string` -| - -| `rules` -| `array` -| - -| `rules[]` -| `object` -| Rule describes an alerting or recording rule. - -|=== -..spec.groups[].rules -Description:: - - -Type:: - `array` - - - - -..spec.groups[].rules[] -Description:: - Rule describes an alerting or recording rule. - -Type:: - `object` - -Required:: - - `expr` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `alert` -| `string` -| - -| `annotations` -| `object (string)` -| - -| `expr` -| `integer-or-string` -| - -| `for` -| `string` -| - -| `labels` -| `object (string)` -| - -| `record` -| `string` -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/monitoring.coreos.com/v1/prometheusrules` -- `GET`: list objects of kind PrometheusRule -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/prometheusrules` -- `DELETE`: delete collection of PrometheusRule -- `GET`: list objects of kind PrometheusRule -- `POST`: create a PrometheusRule -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/prometheusrules/{name}` -- `DELETE`: delete a PrometheusRule -- `GET`: read the specified PrometheusRule -- `PATCH`: partially update the specified PrometheusRule -- `PUT`: replace the specified PrometheusRule - - -=== /apis/monitoring.coreos.com/v1/prometheusrules - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind PrometheusRule - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#prometheusrulelist-monitoring-coreos-com-v1[`PrometheusRuleList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/prometheusrules - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PrometheusRule - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind PrometheusRule - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#prometheusrulelist-monitoring-coreos-com-v1[`PrometheusRuleList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PrometheusRule - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| 202 - Accepted -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/prometheusrules/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PrometheusRule -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PrometheusRule - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PrometheusRule - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PrometheusRule - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PrometheusRule - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`PrometheusRule monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc deleted file mode 100644 index e086d1282f06..000000000000 --- a/rest_api/monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc +++ /dev/null @@ -1,1192 +0,0 @@ -[id="servicemonitor-monitoring-coreos-com-v1"] -= ServiceMonitor [monitoring.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ServiceMonitor defines monitoring for a set of services. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of desired Service selection for target discovery by Prometheus. - -|=== -..spec -Description:: - Specification of desired Service selection for target discovery by Prometheus. - -Type:: - `object` - -Required:: - - `endpoints` - - `selector` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `endpoints` -| `array` -| A list of endpoints allowed as part of this ServiceMonitor. - -| `endpoints[]` -| `object` -| Endpoint defines a scrapeable endpoint serving Prometheus metrics. - -| `jobLabel` -| `string` -| The label to use to retrieve the job name from. - -| `namespaceSelector` -| `object` -| Selector to select which namespaces the Endpoints objects are discovered from. - -| `podTargetLabels` -| `array (string)` -| PodTargetLabels transfers labels on the Kubernetes Pod onto the target. - -| `sampleLimit` -| `integer` -| SampleLimit defines per-scrape limit on number of scraped samples that will be accepted. - -| `selector` -| `object` -| Selector to select Endpoints objects. - -| `targetLabels` -| `array (string)` -| TargetLabels transfers labels on the Kubernetes Service onto the target. - -| `targetLimit` -| `integer` -| TargetLimit defines a limit on the number of scraped targets that will be accepted. - -|=== -..spec.endpoints -Description:: - A list of endpoints allowed as part of this ServiceMonitor. - -Type:: - `array` - - - - -..spec.endpoints[] -Description:: - Endpoint defines a scrapeable endpoint serving Prometheus metrics. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `basicAuth` -| `object` -| BasicAuth allow an endpoint to authenticate over basic authentication More info: https://prometheus.io/docs/operating/configuration/#endpoints - -| `bearerTokenFile` -| `string` -| File to read bearer token for scraping targets. - -| `bearerTokenSecret` -| `object` -| Secret to mount to read bearer token for scraping targets. The secret needs to be in the same namespace as the service monitor and accessible by the Prometheus Operator. - -| `honorLabels` -| `boolean` -| HonorLabels chooses the metric's labels on collisions with target labels. - -| `honorTimestamps` -| `boolean` -| HonorTimestamps controls whether Prometheus respects the timestamps present in scraped data. - -| `interval` -| `string` -| Interval at which metrics should be scraped - -| `metricRelabelings` -| `array` -| MetricRelabelConfigs to apply to samples before ingestion. - -| `metricRelabelings[]` -| `object` -| RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -| `params` -| `object` -| Optional HTTP URL parameters - -| `params{}` -| `array (string)` -| - -| `path` -| `string` -| HTTP path to scrape for metrics. - -| `port` -| `string` -| Name of the service port this endpoint refers to. Mutually exclusive with targetPort. - -| `proxyUrl` -| `string` -| ProxyURL eg http://proxyserver:2195 Directs scrapes to proxy through this endpoint. - -| `relabelings` -| `array` -| RelabelConfigs to apply to samples before scraping. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config - -| `relabelings[]` -| `object` -| RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -| `scheme` -| `string` -| HTTP scheme to use for scraping. - -| `scrapeTimeout` -| `string` -| Timeout after which the scrape is ended - -| `targetPort` -| `integer-or-string` -| Name or number of the target port of the Pod behind the Service, the port must be specified with container port property. Mutually exclusive with port. - -| `tlsConfig` -| `object` -| TLS configuration to use when scraping the endpoint - -|=== -..spec.endpoints[].basicAuth -Description:: - BasicAuth allow an endpoint to authenticate over basic authentication More info: https://prometheus.io/docs/operating/configuration/#endpoints - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `password` -| `object` -| The secret in the service monitor namespace that contains the password for authentication. - -| `username` -| `object` -| The secret in the service monitor namespace that contains the username for authentication. - -|=== -..spec.endpoints[].basicAuth.password -Description:: - The secret in the service monitor namespace that contains the password for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.endpoints[].basicAuth.username -Description:: - The secret in the service monitor namespace that contains the username for authentication. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.endpoints[].bearerTokenSecret -Description:: - Secret to mount to read bearer token for scraping targets. The secret needs to be in the same namespace as the service monitor and accessible by the Prometheus Operator. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.endpoints[].metricRelabelings -Description:: - MetricRelabelConfigs to apply to samples before ingestion. - -Type:: - `array` - - - - -..spec.endpoints[].metricRelabelings[] -Description:: - RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `action` -| `string` -| Action to perform based on regex matching. Default is 'replace' - -| `modulus` -| `integer` -| Modulus to take of the hash of the source label values. - -| `regex` -| `string` -| Regular expression against which the extracted value is matched. Default is '(.*)' - -| `replacement` -| `string` -| Replacement value against which a regex replace is performed if the regular expression matches. Regex capture groups are available. Default is '$1' - -| `separator` -| `string` -| Separator placed between concatenated source label values. default is ';'. - -| `sourceLabels` -| `array (string)` -| The source labels select values from existing labels. Their content is concatenated using the configured separator and matched against the configured regular expression for the replace, keep, and drop actions. - -| `targetLabel` -| `string` -| Label to which the resulting value is written in a replace action. It is mandatory for replace actions. Regex capture groups are available. - -|=== -..spec.endpoints[].params -Description:: - Optional HTTP URL parameters - -Type:: - `object` - - - - -..spec.endpoints[].relabelings -Description:: - RelabelConfigs to apply to samples before scraping. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config - -Type:: - `array` - - - - -..spec.endpoints[].relabelings[] -Description:: - RelabelConfig allows dynamic rewriting of the label set, being applied to samples before ingestion. It defines `<metric_relabel_configs>`-section of Prometheus configuration. More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#metric_relabel_configs - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `action` -| `string` -| Action to perform based on regex matching. Default is 'replace' - -| `modulus` -| `integer` -| Modulus to take of the hash of the source label values. - -| `regex` -| `string` -| Regular expression against which the extracted value is matched. Default is '(.*)' - -| `replacement` -| `string` -| Replacement value against which a regex replace is performed if the regular expression matches. Regex capture groups are available. Default is '$1' - -| `separator` -| `string` -| Separator placed between concatenated source label values. default is ';'. - -| `sourceLabels` -| `array (string)` -| The source labels select values from existing labels. Their content is concatenated using the configured separator and matched against the configured regular expression for the replace, keep, and drop actions. - -| `targetLabel` -| `string` -| Label to which the resulting value is written in a replace action. It is mandatory for replace actions. Regex capture groups are available. - -|=== -..spec.endpoints[].tlsConfig -Description:: - TLS configuration to use when scraping the endpoint - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `caFile` -| `string` -| Path to the CA cert in the Prometheus container to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `certFile` -| `string` -| Path to the client cert file in the Prometheus container for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keyFile` -| `string` -| Path to the client key file in the Prometheus container for the targets. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.endpoints[].tlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.endpoints[].tlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.endpoints[].tlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.endpoints[].tlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.endpoints[].tlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.endpoints[].tlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.endpoints[].tlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.namespaceSelector -Description:: - Selector to select which namespaces the Endpoints objects are discovered from. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `any` -| `boolean` -| Boolean describing whether all namespaces are selected in contrast to a list restricting them. - -| `matchNames` -| `array (string)` -| List of namespace names. - -|=== -..spec.selector -Description:: - Selector to select Endpoints objects. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/monitoring.coreos.com/v1/servicemonitors` -- `GET`: list objects of kind ServiceMonitor -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/servicemonitors` -- `DELETE`: delete collection of ServiceMonitor -- `GET`: list objects of kind ServiceMonitor -- `POST`: create a ServiceMonitor -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/servicemonitors/{name}` -- `DELETE`: delete a ServiceMonitor -- `GET`: read the specified ServiceMonitor -- `PATCH`: partially update the specified ServiceMonitor -- `PUT`: replace the specified ServiceMonitor - - -=== /apis/monitoring.coreos.com/v1/servicemonitors - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ServiceMonitor - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#servicemonitorlist-monitoring-coreos-com-v1[`ServiceMonitorList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/servicemonitors - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ServiceMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ServiceMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#servicemonitorlist-monitoring-coreos-com-v1[`ServiceMonitorList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ServiceMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| 202 - Accepted -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/servicemonitors/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ServiceMonitor -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ServiceMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ServiceMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ServiceMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ServiceMonitor - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`ServiceMonitor monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc b/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc deleted file mode 100644 index 31b21482919b..000000000000 --- a/rest_api/monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc +++ /dev/null @@ -1,7695 +0,0 @@ -[id="thanosruler-monitoring-coreos-com-v1"] -= ThanosRuler [monitoring.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ThanosRuler defines a ThanosRuler deployment. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of the desired behavior of the ThanosRuler cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -| `status` -| `object` -| Most recent observed status of the ThanosRuler cluster. Read-only. Not included when requesting from the apiserver, only from the ThanosRuler Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -|=== -..spec -Description:: - Specification of the desired behavior of the ThanosRuler cluster. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `affinity` -| `object` -| If specified, the pod's scheduling constraints. - -| `alertDropLabels` -| `array (string)` -| AlertDropLabels configure the label names which should be dropped in ThanosRuler alerts. If `labels` field is not provided, `thanos_ruler_replica` will be dropped in alerts by default. - -| `alertQueryUrl` -| `string` -| The external Query URL the Thanos Ruler will set in the 'Source' field of all alerts. Maps to the '--alert.query-url' CLI arg. - -| `alertmanagersConfig` -| `object` -| Define configuration for connecting to alertmanager. Only available with thanos v0.10.0 and higher. Maps to the `alertmanagers.config` arg. - -| `alertmanagersUrl` -| `array (string)` -| Define URLs to send alerts to Alertmanager. For Thanos v0.10.0 and higher, AlertManagersConfig should be used instead. Note: this field will be ignored if AlertManagersConfig is specified. Maps to the `alertmanagers.url` arg. - -| `containers` -| `array` -| Containers allows injecting additional containers or modifying operator generated containers. This can be used to allow adding an authentication proxy to a ThanosRuler pod or to change the behavior of an operator generated container. Containers described here modify an operator generated container if they share the same name and modifications are done via a strategic merge patch. The current container names are: `thanos-ruler` and `config-reloader`. Overriding containers is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -| `containers[]` -| `object` -| A single application container that you want to run within a pod. - -| `enforcedNamespaceLabel` -| `string` -| EnforcedNamespaceLabel enforces adding a namespace label of origin for each alert and metric that is user created. The label value will always be the namespace of the object that is being created. - -| `evaluationInterval` -| `string` -| Interval between consecutive evaluations. - -| `externalPrefix` -| `string` -| The external URL the Thanos Ruler instances will be available under. This is necessary to generate correct URLs. This is necessary if Thanos Ruler is not served from root of a DNS name. - -| `grpcServerTlsConfig` -| `object` -| GRPCServerTLSConfig configures the gRPC server from which Thanos Querier reads recorded rule data. Note: Currently only the CAFile, CertFile, and KeyFile fields are supported. Maps to the '--grpc-server-tls-*' CLI args. - -| `image` -| `string` -| Thanos container image URL. - -| `imagePullSecrets` -| `array` -| An optional list of references to secrets in the same namespace to use for pulling thanos images from registries see http://kubernetes.io/docs/user-guide/images#specifying-imagepullsecrets-on-a-pod - -| `imagePullSecrets[]` -| `object` -| LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -| `initContainers` -| `array` -| InitContainers allows adding initContainers to the pod definition. Those can be used to e.g. fetch secrets for injection into the ThanosRuler configuration from external sources. Any errors during the execution of an initContainer will lead to a restart of the Pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ Using initContainers for any use case other then secret fetching is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -| `initContainers[]` -| `object` -| A single application container that you want to run within a pod. - -| `labels` -| `object (string)` -| Labels configure the external label pairs to ThanosRuler. If not provided, default replica label `thanos_ruler_replica` will be added as a label and be dropped in alerts. - -| `listenLocal` -| `boolean` -| ListenLocal makes the Thanos ruler listen on loopback, so that it does not bind against the Pod IP. - -| `logFormat` -| `string` -| Log format for ThanosRuler to be configured with. - -| `logLevel` -| `string` -| Log level for ThanosRuler to be configured with. - -| `nodeSelector` -| `object (string)` -| Define which Nodes the Pods are scheduled on. - -| `objectStorageConfig` -| `object` -| ObjectStorageConfig configures object storage in Thanos. Alternative to ObjectStorageConfigFile, and lower order priority. - -| `objectStorageConfigFile` -| `string` -| ObjectStorageConfigFile specifies the path of the object storage configuration file. When used alongside with ObjectStorageConfig, ObjectStorageConfigFile takes precedence. - -| `paused` -| `boolean` -| When a ThanosRuler deployment is paused, no actions except for deletion will be performed on the underlying objects. - -| `podMetadata` -| `object` -| PodMetadata contains Labels and Annotations gets propagated to the thanos ruler pods. - -| `portName` -| `string` -| Port name used for the pods and governing service. This defaults to web - -| `priorityClassName` -| `string` -| Priority class assigned to the Pods - -| `prometheusRulesExcludedFromEnforce` -| `array` -| PrometheusRulesExcludedFromEnforce - list of Prometheus rules to be excluded from enforcing of adding namespace labels. Works only if enforcedNamespaceLabel set to true. Make sure both ruleNamespace and ruleName are set for each pair - -| `prometheusRulesExcludedFromEnforce[]` -| `object` -| PrometheusRuleExcludeConfig enables users to configure excluded PrometheusRule names and their namespaces to be ignored while enforcing namespace label for alerts and metrics. - -| `queryConfig` -| `object` -| Define configuration for connecting to thanos query instances. If this is defined, the QueryEndpoints field will be ignored. Maps to the `query.config` CLI argument. Only available with thanos v0.11.0 and higher. - -| `queryEndpoints` -| `array (string)` -| QueryEndpoints defines Thanos querier endpoints from which to query metrics. Maps to the --query flag of thanos ruler. - -| `replicas` -| `integer` -| Number of thanos ruler instances to deploy. - -| `resources` -| `object` -| Resources defines the resource requirements for single Pods. If not provided, no requests/limits will be set - -| `retention` -| `string` -| Time duration ThanosRuler shall retain data for. Default is '24h', and must match the regular expression `[0-9]+(ms\|s\|m\|h\|d\|w\|y)` (milliseconds seconds minutes hours days weeks years). - -| `routePrefix` -| `string` -| The route prefix ThanosRuler registers HTTP handlers for. This allows thanos UI to be served on a sub-path. - -| `ruleNamespaceSelector` -| `object` -| Namespaces to be selected for Rules discovery. If unspecified, only the same namespace as the ThanosRuler object is in is used. - -| `ruleSelector` -| `object` -| A label selector to select which PrometheusRules to mount for alerting and recording. - -| `securityContext` -| `object` -| SecurityContext holds pod-level security attributes and common container settings. This defaults to the default PodSecurityContext. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the name of the ServiceAccount to use to run the Thanos Ruler Pods. - -| `storage` -| `object` -| Storage spec to specify how storage shall be used. - -| `tolerations` -| `array` -| If specified, the pod's tolerations. - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -| `topologySpreadConstraints` -| `array` -| If specified, the pod's topology spread constraints. - -| `topologySpreadConstraints[]` -| `object` -| TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -| `tracingConfig` -| `object` -| TracingConfig configures tracing in Thanos. This is an experimental feature, it may change in any upcoming release in a breaking way. - -| `volumes` -| `array` -| Volumes allows configuration of additional volumes on the output StatefulSet definition. Volumes specified will be appended to other volumes that are generated as a result of StorageSpec objects. - -| `volumes[]` -| `object` -| Volume represents a named volume in a pod that may be accessed by any container in the pod. - -|=== -..spec.affinity -Description:: - If specified, the pod's scheduling constraints. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeAffinity` -| `object` -| Describes node affinity scheduling rules for the pod. - -| `podAffinity` -| `object` -| Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -| `podAntiAffinity` -| `object` -| Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -|=== -..spec.affinity.nodeAffinity -Description:: - Describes node affinity scheduling rules for the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `object` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -Type:: - `object` - -Required:: - - `preference` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preference` -| `object` -| A node selector term, associated with the corresponding weight. - -| `weight` -| `integer` -| Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference -Description:: - A node selector term, associated with the corresponding weight. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -Type:: - `object` - -Required:: - - `nodeSelectorTerms` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelectorTerms` -| `array` -| Required. A list of node selector terms. The terms are ORed. - -| `nodeSelectorTerms[]` -| `object` -| A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms -Description:: - Required. A list of node selector terms. The terms are ORed. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[] -Description:: - A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity -Description:: - Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity -Description:: - Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.alertmanagersConfig -Description:: - Define configuration for connecting to alertmanager. Only available with thanos v0.10.0 and higher. Maps to the `alertmanagers.config` arg. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.containers -Description:: - Containers allows injecting additional containers or modifying operator generated containers. This can be used to allow adding an authentication proxy to a ThanosRuler pod or to change the behavior of an operator generated container. Containers described here modify an operator generated container if they share the same name and modifications are done via a strategic merge patch. The current container names are: `thanos-ruler` and `config-reloader`. Overriding containers is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -Type:: - `array` - - - - -..spec.containers[] -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| `object` -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| `array` -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| `object` -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| `object` -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| `object` -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.containers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.containers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.containers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.containers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.containers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.containers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.containers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.containers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.containers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.containers[].lifecycle -Description:: - Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.containers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.containers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.containers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].livenessProbe -Description:: - Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].ports -Description:: - List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.containers[].readinessProbe -Description:: - Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].resources -Description:: - Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.containers[].securityContext -Description:: - Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.containers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.containers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.containers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.containers[].startupProbe -Description:: - StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.containers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.containers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.containers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.containers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.containers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.containers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.containers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.containers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.containers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.grpcServerTlsConfig -Description:: - GRPCServerTLSConfig configures the gRPC server from which Thanos Querier reads recorded rule data. Note: Currently only the CAFile, CertFile, and KeyFile fields are supported. Maps to the '--grpc-server-tls-*' CLI args. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ca` -| `object` -| Struct containing the CA cert to use for the targets. - -| `caFile` -| `string` -| Path to the CA cert in the Prometheus container to use for the targets. - -| `cert` -| `object` -| Struct containing the client cert file for the targets. - -| `certFile` -| `string` -| Path to the client cert file in the Prometheus container for the targets. - -| `insecureSkipVerify` -| `boolean` -| Disable target certificate validation. - -| `keyFile` -| `string` -| Path to the client key file in the Prometheus container for the targets. - -| `keySecret` -| `object` -| Secret containing the client key file for the targets. - -| `serverName` -| `string` -| Used to verify the hostname for the targets. - -|=== -..spec.grpcServerTlsConfig.ca -Description:: - Struct containing the CA cert to use for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.grpcServerTlsConfig.ca.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.grpcServerTlsConfig.ca.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.grpcServerTlsConfig.cert -Description:: - Struct containing the client cert file for the targets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| ConfigMap containing data to use for the targets. - -| `secret` -| `object` -| Secret containing data to use for the targets. - -|=== -..spec.grpcServerTlsConfig.cert.configMap -Description:: - ConfigMap containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.grpcServerTlsConfig.cert.secret -Description:: - Secret containing data to use for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.grpcServerTlsConfig.keySecret -Description:: - Secret containing the client key file for the targets. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.imagePullSecrets -Description:: - An optional list of references to secrets in the same namespace to use for pulling thanos images from registries see http://kubernetes.io/docs/user-guide/images#specifying-imagepullsecrets-on-a-pod - -Type:: - `array` - - - - -..spec.imagePullSecrets[] -Description:: - LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.initContainers -Description:: - InitContainers allows adding initContainers to the pod definition. Those can be used to e.g. fetch secrets for injection into the ThanosRuler configuration from external sources. Any errors during the execution of an initContainer will lead to a restart of the Pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ Using initContainers for any use case other then secret fetching is entirely outside the scope of what the maintainers will support and by doing so, you accept that this behaviour may break at any time without notice. - -Type:: - `array` - - - - -..spec.initContainers[] -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| `object` -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| `array` -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| `object` -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| `object` -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| `object` -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.initContainers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.initContainers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.initContainers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.initContainers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels, metadata.annotations, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.initContainers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.initContainers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.initContainers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.initContainers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.initContainers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.initContainers[].lifecycle -Description:: - Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.initContainers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.initContainers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.initContainers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].livenessProbe -Description:: - Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].ports -Description:: - List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.initContainers[].readinessProbe -Description:: - Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].resources -Description:: - Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.initContainers[].securityContext -Description:: - Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.initContainers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.initContainers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.initContainers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.initContainers[].startupProbe -Description:: - StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. This is a beta feature enabled by the StartupProbe feature flag. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.initContainers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.initContainers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.initContainers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.initContainers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.initContainers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.initContainers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.initContainers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.initContainers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.initContainers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.objectStorageConfig -Description:: - ObjectStorageConfig configures object storage in Thanos. Alternative to ObjectStorageConfigFile, and lower order priority. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.podMetadata -Description:: - PodMetadata contains Labels and Annotations gets propagated to the thanos ruler pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -|=== -..spec.prometheusRulesExcludedFromEnforce -Description:: - PrometheusRulesExcludedFromEnforce - list of Prometheus rules to be excluded from enforcing of adding namespace labels. Works only if enforcedNamespaceLabel set to true. Make sure both ruleNamespace and ruleName are set for each pair - -Type:: - `array` - - - - -..spec.prometheusRulesExcludedFromEnforce[] -Description:: - PrometheusRuleExcludeConfig enables users to configure excluded PrometheusRule names and their namespaces to be ignored while enforcing namespace label for alerts and metrics. - -Type:: - `object` - -Required:: - - `ruleName` - - `ruleNamespace` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ruleName` -| `string` -| RuleNamespace - name of excluded rule - -| `ruleNamespace` -| `string` -| RuleNamespace - namespace of excluded rule - -|=== -..spec.queryConfig -Description:: - Define configuration for connecting to thanos query instances. If this is defined, the QueryEndpoints field will be ignored. Maps to the `query.config` CLI argument. Only available with thanos v0.11.0 and higher. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.resources -Description:: - Resources defines the resource requirements for single Pods. If not provided, no requests/limits will be set - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.ruleNamespaceSelector -Description:: - Namespaces to be selected for Rules discovery. If unspecified, only the same namespace as the ThanosRuler object is in is used. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.ruleNamespaceSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.ruleNamespaceSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.ruleSelector -Description:: - A label selector to select which PrometheusRules to mount for alerting and recording. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.ruleSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.ruleSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.securityContext -Description:: - SecurityContext holds pod-level security attributes and common container settings. This defaults to the default PodSecurityContext. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsGroup` -| `integer` -| A special supplemental group that applies to all containers in a pod. Some volume types allow the Kubelet to change the ownership of that volume to be owned by the pod: - 1. The owning GID will be the FSGroup 2. The setgid bit is set (new files created in the volume will be owned by FSGroup) 3. The permission bits are OR'd with rw-rw---- - If unset, the Kubelet will not modify the ownership and permissions of any volume. - -| `fsGroupChangePolicy` -| `string` -| fsGroupChangePolicy defines behavior of changing ownership and permission of the volume before being exposed inside Pod. This field will only apply to volume types which support fsGroup based ownership(and permissions). It will have no effect on ephemeral volume types such as: secret, configmaps and emptydir. Valid values are "OnRootMismatch" and "Always". If not specified defaults to "Always". - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `supplementalGroups` -| `array (integer)` -| A list of groups applied to the first process run in each container, in addition to the container's primary GID. If unspecified, no groups will be added to any container. - -| `sysctls` -| `array` -| Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -| `sysctls[]` -| `object` -| Sysctl defines a kernel parameter to be set - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.securityContext.sysctls -Description:: - Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -Type:: - `array` - - - - -..spec.securityContext.sysctls[] -Description:: - Sysctl defines a kernel parameter to be set - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of a property to set - -| `value` -| `string` -| Value of a property to set - -|=== -..spec.securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.storage -Description:: - Storage spec to specify how storage shall be used. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `disableMountSubPath` -| `boolean` -| Deprecated: subPath usage will be disabled by default in a future release, this option will become unnecessary. DisableMountSubPath allows to remove any subPath usage in volume mounts. - -| `emptyDir` -| `object` -| EmptyDirVolumeSource to be used by the Prometheus StatefulSets. If specified, used in place of any volumeClaimTemplate. More info: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir - -| `volumeClaimTemplate` -| `object` -| A PVC spec to be used by the Prometheus StatefulSets. - -|=== -..spec.storage.emptyDir -Description:: - EmptyDirVolumeSource to be used by the Prometheus StatefulSets. If specified, used in place of any volumeClaimTemplate. More info: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| `integer-or-string` -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== -..spec.storage.volumeClaimTemplate -Description:: - A PVC spec to be used by the Prometheus StatefulSets. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| `object` -| EmbeddedMetadata contains metadata relevant to an EmbeddedResource. - -| `spec` -| `object` -| Spec defines the desired characteristics of a volume requested by a pod author. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `status` -| `object` -| Status represents the current information/status of a persistent volume claim. Read-only. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -|=== -..spec.storage.volumeClaimTemplate.metadata -Description:: - EmbeddedMetadata contains metadata relevant to an EmbeddedResource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -|=== -..spec.storage.volumeClaimTemplate.spec -Description:: - Spec defines the desired characteristics of a volume requested by a pod author. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `dataSource` -| `object` -| This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot - Beta) * An existing PVC (PersistentVolumeClaim) * An existing custom resource/object that implements data population (Alpha) In order to use VolumeSnapshot object types, the appropriate feature gate must be enabled (VolumeSnapshotDataSource or AnyVolumeDataSource) If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. If the specified data source is not supported, the volume will not be created and the failure will be reported as an event. In the future, we plan to support more data source types and the behavior of the provisioner may change. - -| `resources` -| `object` -| Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -| `selector` -| `object` -| A label query over volumes to consider for binding. - -| `storageClassName` -| `string` -| Name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 - -| `volumeMode` -| `string` -| volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. - -| `volumeName` -| `string` -| VolumeName is the binding reference to the PersistentVolume backing this claim. - -|=== -..spec.storage.volumeClaimTemplate.spec.dataSource -Description:: - This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot - Beta) * An existing PVC (PersistentVolumeClaim) * An existing custom resource/object that implements data population (Alpha) In order to use VolumeSnapshot object types, the appropriate feature gate must be enabled (VolumeSnapshotDataSource or AnyVolumeDataSource) If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. If the specified data source is not supported, the volume will not be created and the failure will be reported as an event. In the future, we plan to support more data source types and the behavior of the provisioner may change. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required. - -| `kind` -| `string` -| Kind is the type of resource being referenced - -| `name` -| `string` -| Name is the name of resource being referenced - -|=== -..spec.storage.volumeClaimTemplate.spec.resources -Description:: - Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.storage.volumeClaimTemplate.spec.selector -Description:: - A label query over volumes to consider for binding. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.storage.volumeClaimTemplate.spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.storage.volumeClaimTemplate.spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.storage.volumeClaimTemplate.status -Description:: - Status represents the current information/status of a persistent volume claim. Read-only. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the actual access modes the volume backing the PVC has. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `capacity` -| `integer-or-string` -| Represents the actual resources of the underlying volume. - -| `conditions` -| `array` -| Current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'. - -| `conditions[]` -| `object` -| PersistentVolumeClaimCondition contails details about state of pvc - -| `phase` -| `string` -| Phase represents the current phase of PersistentVolumeClaim. - -|=== -..spec.storage.volumeClaimTemplate.status.conditions -Description:: - Current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'. - -Type:: - `array` - - - - -..spec.storage.volumeClaimTemplate.status.conditions[] -Description:: - PersistentVolumeClaimCondition contails details about state of pvc - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| `string` -| Last time we probed the condition. - -| `lastTransitionTime` -| `string` -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| Human-readable message indicating details about last transition. - -| `reason` -| `string` -| Unique, this should be a short, machine understandable string that gives the reason for condition's last transition. If it reports "ResizeStarted" that means the underlying persistent volume is being resized. - -| `status` -| `string` -| - -| `type` -| `string` -| PersistentVolumeClaimConditionType is a valid value of PersistentVolumeClaimCondition.Type - -|=== -..spec.tolerations -Description:: - If specified, the pod's tolerations. - -Type:: - `array` - - - - -..spec.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== -..spec.topologySpreadConstraints -Description:: - If specified, the pod's topology spread constraints. - -Type:: - `array` - - - - -..spec.topologySpreadConstraints[] -Description:: - TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -Type:: - `object` - -Required:: - - `maxSkew` - - `topologyKey` - - `whenUnsatisfiable` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -| `maxSkew` -| `integer` -| MaxSkew describes the degree to which pods may be unevenly distributed. It's the maximum permitted difference between the number of matching pods in any two topology domains of a given topology type. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: \| zone1 \| zone2 \| zone3 \| \| P \| P \| \| - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. It's a required field. Default value is 1 and 0 is not allowed. - -| `topologyKey` -| `string` -| TopologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. We consider each <key, value> as a "bucket", and try to put balanced number of pods into each bucket. It's a required field. - -| `whenUnsatisfiable` -| `string` -| WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it - ScheduleAnyway tells the scheduler to still schedule it It's considered as "Unsatisfiable" if and only if placing incoming pod on any topology violates "MaxSkew". For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: \| zone1 \| zone2 \| zone3 \| \| P P P \| P \| P \| If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field. - -|=== -..spec.topologySpreadConstraints[].labelSelector -Description:: - LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.topologySpreadConstraints[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.topologySpreadConstraints[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.tracingConfig -Description:: - TracingConfig configures tracing in Thanos. This is an experimental feature, it may change in any upcoming release in a breaking way. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.volumes -Description:: - Volumes allows configuration of additional volumes on the output StatefulSet definition. Volumes specified will be appended to other volumes that are generated as a result of StorageSpec objects. - -Type:: - `array` - - - - -..spec.volumes[] -Description:: - Volume represents a named volume in a pod that may be accessed by any container in the pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `awsElasticBlockStore` -| `object` -| AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `azureDisk` -| `object` -| AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -| `azureFile` -| `object` -| AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -| `cephfs` -| `object` -| CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -| `cinder` -| `object` -| Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `configMap` -| `object` -| ConfigMap represents a configMap that should populate this volume - -| `csi` -| `object` -| CSI (Container Storage Interface) represents storage that is handled by an external CSI driver (Alpha feature). - -| `downwardAPI` -| `object` -| DownwardAPI represents downward API about the pod that should populate this volume - -| `emptyDir` -| `object` -| EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `fc` -| `object` -| FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -| `flexVolume` -| `object` -| FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -| `flocker` -| `object` -| Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -| `gcePersistentDisk` -| `object` -| GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `gitRepo` -| `object` -| GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -| `glusterfs` -| `object` -| Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -| `hostPath` -| `object` -| HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -| `iscsi` -| `object` -| ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -| `name` -| `string` -| Volume's name. Must be a DNS_LABEL and unique within the pod. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `nfs` -| `object` -| NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `persistentVolumeClaim` -| `object` -| PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `photonPersistentDisk` -| `object` -| PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -| `portworxVolume` -| `object` -| PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -| `projected` -| `object` -| Items for all in one resources secrets, configmaps, and downward API - -| `quobyte` -| `object` -| Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -| `rbd` -| `object` -| RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -| `scaleIO` -| `object` -| ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -| `secret` -| `object` -| Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -| `storageos` -| `object` -| StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -| `vsphereVolume` -| `object` -| VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -|=== -..spec.volumes[].awsElasticBlockStore -Description:: - AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). - -| `readOnly` -| `boolean` -| Specify "true" to force and set the ReadOnly property in VolumeMounts to "true". If omitted, the default is "false". More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `volumeID` -| `string` -| Unique ID of the persistent disk resource in AWS (Amazon EBS volume). More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -|=== -..spec.volumes[].azureDisk -Description:: - AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `diskName` - - `diskURI` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cachingMode` -| `string` -| Host Caching mode: None, Read Only, Read Write. - -| `diskName` -| `string` -| The Name of the data disk in the blob storage - -| `diskURI` -| `string` -| The URI the data disk in the blob storage - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `kind` -| `string` -| Expected values Shared: multiple blob disks per storage account Dedicated: single blob disk per storage account Managed: azure managed data disk (only in managed availability set). defaults to shared - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -|=== -..spec.volumes[].azureFile -Description:: - AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `secretName` - - `shareName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretName` -| `string` -| the name of secret that contains Azure Storage Account Name and Key - -| `shareName` -| `string` -| Share Name - -|=== -..spec.volumes[].cephfs -Description:: - CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `monitors` -| `array (string)` -| Required: Monitors is a collection of Ceph monitors More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `path` -| `string` -| Optional: Used as the mounted root, rather than the full Ceph tree, default is / - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretFile` -| `string` -| Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `user` -| `string` -| Optional: User is the rados user name, default is admin More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -|=== -..spec.volumes[].cephfs.secretRef -Description:: - Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].cinder -Description:: - Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `secretRef` -| `object` -| Optional: points to a secret object containing parameters used to connect to OpenStack. - -| `volumeID` -| `string` -| volume id used to identify the volume in cinder. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -|=== -..spec.volumes[].cinder.secretRef -Description:: - Optional: points to a secret object containing parameters used to connect to OpenStack. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].configMap -Description:: - ConfigMap represents a configMap that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.volumes[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].csi -Description:: - CSI (Container Storage Interface) represents storage that is handled by an external CSI driver (Alpha feature). - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the CSI driver that handles this volume. Consult with your admin for the correct name as registered in the cluster. - -| `fsType` -| `string` -| Filesystem type to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. - -| `nodePublishSecretRef` -| `object` -| NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeAttributes` -| `object (string)` -| VolumeAttributes stores driver-specific properties that are passed to the CSI driver. Consult your driver's documentation for supported values. - -|=== -..spec.volumes[].csi.nodePublishSecretRef -Description:: - NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].downwardAPI -Description:: - DownwardAPI represents downward API about the pod that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| Items is a list of downward API volume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.volumes[].downwardAPI.items -Description:: - Items is a list of downward API volume file - -Type:: - `array` - - - - -..spec.volumes[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.volumes[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.volumes[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.volumes[].emptyDir -Description:: - EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| `integer-or-string` -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== -..spec.volumes[].fc -Description:: - FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. TODO: how do we prevent errors in the filesystem from compromising the machine - -| `lun` -| `integer` -| Optional: FC target lun number - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `targetWWNs` -| `array (string)` -| Optional: FC target worldwide names (WWNs) - -| `wwids` -| `array (string)` -| Optional: FC volume world wide identifiers (wwids) Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously. - -|=== -..spec.volumes[].flexVolume -Description:: - FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the driver to use for this volume. - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script. - -| `options` -| `object (string)` -| Optional: Extra command options if any. - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -|=== -..spec.volumes[].flexVolume.secretRef -Description:: - Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].flocker -Description:: - Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `datasetName` -| `string` -| Name of the dataset stored as metadata -> name on the dataset for Flocker should be considered as deprecated - -| `datasetUUID` -| `string` -| UUID of the dataset. This is unique identifier of a Flocker dataset - -|=== -..spec.volumes[].gcePersistentDisk -Description:: - GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -Type:: - `object` - -Required:: - - `pdName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `pdName` -| `string` -| Unique name of the PD resource in GCE. Used to identify the disk in GCE. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -|=== -..spec.volumes[].gitRepo -Description:: - GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -Type:: - `object` - -Required:: - - `repository` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `directory` -| `string` -| Target directory name. Must not contain or start with '..'. If '.' is supplied, the volume directory will be the git repository. Otherwise, if specified, the volume will contain the git repository in the subdirectory with the given name. - -| `repository` -| `string` -| Repository URL - -| `revision` -| `string` -| Commit hash for the specified revision. - -|=== -..spec.volumes[].glusterfs -Description:: - Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -Type:: - `object` - -Required:: - - `endpoints` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `endpoints` -| `string` -| EndpointsName is the endpoint name that details Glusterfs topology. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `path` -| `string` -| Path is the Glusterfs volume path. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `readOnly` -| `boolean` -| ReadOnly here will force the Glusterfs volume to be mounted with read-only permissions. Defaults to false. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -|=== -..spec.volumes[].hostPath -Description:: - HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path of the directory on the host. If the path is a symlink, it will follow the link to the real path. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `type` -| `string` -| Type for HostPath Volume Defaults to "" More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -|=== -..spec.volumes[].iscsi -Description:: - ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -Type:: - `object` - -Required:: - - `iqn` - - `lun` - - `targetPortal` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `chapAuthDiscovery` -| `boolean` -| whether support iSCSI Discovery CHAP authentication - -| `chapAuthSession` -| `boolean` -| whether support iSCSI Session CHAP authentication - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi TODO: how do we prevent errors in the filesystem from compromising the machine - -| `initiatorName` -| `string` -| Custom iSCSI Initiator Name. If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface <target portal>:<volume name> will be created for the connection. - -| `iqn` -| `string` -| Target iSCSI Qualified Name. - -| `iscsiInterface` -| `string` -| iSCSI Interface Name that uses an iSCSI transport. Defaults to 'default' (tcp). - -| `lun` -| `integer` -| iSCSI Target Lun number. - -| `portals` -| `array (string)` -| iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. - -| `secretRef` -| `object` -| CHAP Secret for iSCSI target and initiator authentication - -| `targetPortal` -| `string` -| iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -|=== -..spec.volumes[].iscsi.secretRef -Description:: - CHAP Secret for iSCSI target and initiator authentication - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].nfs -Description:: - NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -Type:: - `object` - -Required:: - - `path` - - `server` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path that is exported by the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `readOnly` -| `boolean` -| ReadOnly here will force the NFS export to be mounted with read-only permissions. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `server` -| `string` -| Server is the hostname or IP address of the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -|=== -..spec.volumes[].persistentVolumeClaim -Description:: - PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - -Required:: - - `claimName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `claimName` -| `string` -| ClaimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `readOnly` -| `boolean` -| Will force the ReadOnly setting in VolumeMounts. Default false. - -|=== -..spec.volumes[].photonPersistentDisk -Description:: - PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `pdID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `pdID` -| `string` -| ID that identifies Photon Controller persistent disk - -|=== -..spec.volumes[].portworxVolume -Description:: - PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| FSType represents the filesystem type to mount Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `volumeID` -| `string` -| VolumeID uniquely identifies a Portworx volume - -|=== -..spec.volumes[].projected -Description:: - Items for all in one resources secrets, configmaps, and downward API - -Type:: - `object` - -Required:: - - `sources` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Mode bits to use on created files by default. Must be a value between 0 and 0777. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `sources` -| `array` -| list of volume projections - -| `sources[]` -| `object` -| Projection that may be projected along with other supported volume types - -|=== -..spec.volumes[].projected.sources -Description:: - list of volume projections - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[] -Description:: - Projection that may be projected along with other supported volume types - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| information about the configMap data to project - -| `downwardAPI` -| `object` -| information about the downwardAPI data to project - -| `secret` -| `object` -| information about the secret data to project - -| `serviceAccountToken` -| `object` -| information about the serviceAccountToken data to project - -|=== -..spec.volumes[].projected.sources[].configMap -Description:: - information about the configMap data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.volumes[].projected.sources[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].projected.sources[].downwardAPI -Description:: - information about the downwardAPI data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| Items is a list of DownwardAPIVolume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items -Description:: - Items is a list of DownwardAPIVolume file - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.volumes[].projected.sources[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.volumes[].projected.sources[].secret -Description:: - information about the secret data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.volumes[].projected.sources[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].projected.sources[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].projected.sources[].serviceAccountToken -Description:: - information about the serviceAccountToken data to project - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audience` -| `string` -| Audience is the intended audience of the token. A recipient of a token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. The audience defaults to the identifier of the apiserver. - -| `expirationSeconds` -| `integer` -| ExpirationSeconds is the requested duration of validity of the service account token. As the token approaches expiration, the kubelet volume plugin will proactively rotate the service account token. The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.Defaults to 1 hour and must be at least 10 minutes. - -| `path` -| `string` -| Path is the path relative to the mount point of the file to project the token into. - -|=== -..spec.volumes[].quobyte -Description:: - Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `registry` - - `volume` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group to map volume access to Default is no group - -| `readOnly` -| `boolean` -| ReadOnly here will force the Quobyte volume to be mounted with read-only permissions. Defaults to false. - -| `registry` -| `string` -| Registry represents a single or multiple Quobyte Registry services specified as a string as host:port pair (multiple entries are separated with commas) which acts as the central registry for volumes - -| `tenant` -| `string` -| Tenant owning the given Quobyte volume in the Backend Used with dynamically provisioned Quobyte volumes, value is set by the plugin - -| `user` -| `string` -| User to map volume access to Defaults to serivceaccount user - -| `volume` -| `string` -| Volume is a string that references an already created Quobyte volume by name. - -|=== -..spec.volumes[].rbd -Description:: - RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -Type:: - `object` - -Required:: - - `image` - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd TODO: how do we prevent errors in the filesystem from compromising the machine - -| `image` -| `string` -| The rados image name. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `keyring` -| `string` -| Keyring is the path to key ring for RBDUser. Default is /etc/ceph/keyring. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `monitors` -| `array (string)` -| A collection of Ceph monitors. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `pool` -| `string` -| The rados pool name. Default is rbd. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `secretRef` -| `object` -| SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `user` -| `string` -| The rados user name. Default is admin. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -|=== -..spec.volumes[].rbd.secretRef -Description:: - SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].scaleIO -Description:: - ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - -Required:: - - `gateway` - - `secretRef` - - `system` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Default is "xfs". - -| `gateway` -| `string` -| The host address of the ScaleIO API Gateway. - -| `protectionDomain` -| `string` -| The name of the ScaleIO Protection Domain for the configured storage. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -| `sslEnabled` -| `boolean` -| Flag to enable/disable SSL communication with Gateway, default false - -| `storageMode` -| `string` -| Indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned. Default is ThinProvisioned. - -| `storagePool` -| `string` -| The ScaleIO Storage Pool associated with the protection domain. - -| `system` -| `string` -| The name of the storage system as configured in ScaleIO. - -| `volumeName` -| `string` -| The name of a volume already created in the ScaleIO system that is associated with this volume source. - -|=== -..spec.volumes[].scaleIO.secretRef -Description:: - SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].secret -Description:: - Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a value between 0 and 0777. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `optional` -| `boolean` -| Specify whether the Secret or its keys must be defined - -| `secretName` -| `string` -| Name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -|=== -..spec.volumes[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.volumes[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits to use on this file, must be a value between 0 and 0777. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.volumes[].storageos -Description:: - StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -| `volumeName` -| `string` -| VolumeName is the human-readable name of the StorageOS volume. Volume names are only unique within a namespace. - -| `volumeNamespace` -| `string` -| VolumeNamespace specifies the scope of the volume within StorageOS. If no namespace is specified then the Pod's namespace will be used. This allows the Kubernetes name scoping to be mirrored within StorageOS for tighter integration. Set VolumeName to any name to override the default behaviour. Set to "default" if you are not using namespaces within StorageOS. Namespaces that do not pre-exist within StorageOS will be created. - -|=== -..spec.volumes[].storageos.secretRef -Description:: - SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.volumes[].vsphereVolume -Description:: - VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumePath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `storagePolicyID` -| `string` -| Storage Policy Based Management (SPBM) profile ID associated with the StoragePolicyName. - -| `storagePolicyName` -| `string` -| Storage Policy Based Management (SPBM) profile name. - -| `volumePath` -| `string` -| Path that identifies vSphere volume vmdk - -|=== -..status -Description:: - Most recent observed status of the ThanosRuler cluster. Read-only. Not included when requesting from the apiserver, only from the ThanosRuler Operator API itself. More info: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -Type:: - `object` - -Required:: - - `availableReplicas` - - `paused` - - `replicas` - - `unavailableReplicas` - - `updatedReplicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| Total number of available pods (ready for at least minReadySeconds) targeted by this ThanosRuler deployment. - -| `paused` -| `boolean` -| Represents whether any actions on the underlying managed objects are being performed. Only delete actions will be performed. - -| `replicas` -| `integer` -| Total number of non-terminated pods targeted by this ThanosRuler deployment (their labels match the selector). - -| `unavailableReplicas` -| `integer` -| Total number of unavailable pods targeted by this ThanosRuler deployment. - -| `updatedReplicas` -| `integer` -| Total number of non-terminated pods targeted by this ThanosRuler deployment that have the desired version spec. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/monitoring.coreos.com/v1/thanosrulers` -- `GET`: list objects of kind ThanosRuler -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/thanosrulers` -- `DELETE`: delete collection of ThanosRuler -- `GET`: list objects of kind ThanosRuler -- `POST`: create a ThanosRuler -* `/apis/monitoring.coreos.com/v1/namespaces/{namespace}/thanosrulers/{name}` -- `DELETE`: delete a ThanosRuler -- `GET`: read the specified ThanosRuler -- `PATCH`: partially update the specified ThanosRuler -- `PUT`: replace the specified ThanosRuler - - -=== /apis/monitoring.coreos.com/v1/thanosrulers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ThanosRuler - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#thanosrulerlist-monitoring-coreos-com-v1[`ThanosRulerList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/thanosrulers - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ThanosRuler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ThanosRuler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#thanosrulerlist-monitoring-coreos-com-v1[`ThanosRulerList monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ThanosRuler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| 202 - Accepted -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/monitoring.coreos.com/v1/namespaces/{namespace}/thanosrulers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ThanosRuler -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ThanosRuler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ThanosRuler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ThanosRuler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ThanosRuler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| 201 - Created -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`ThanosRuler monitoring.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/clusternetwork-network-openshift-io-v1.adoc b/rest_api/network_apis/clusternetwork-network-openshift-io-v1.adoc deleted file mode 100644 index 72a967661107..000000000000 --- a/rest_api/network_apis/clusternetwork-network-openshift-io-v1.adoc +++ /dev/null @@ -1,470 +0,0 @@ -[id="clusternetwork-network-openshift-io-v1"] -= ClusterNetwork [network.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterNetwork describes the cluster network. There is normally only one object of this type, named "default", which is created by the SDN network plugin based on the master configuration when the cluster is brought up for the first time. - -Type:: - `object` - -Required:: - - `clusterNetworks` - - `serviceNetwork` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `clusterNetworks` -| `array` -| ClusterNetworks is a list of ClusterNetwork objects that defines the global overlay network's L3 space by specifying a set of CIDR and netmasks that the SDN can allocate addresses from. - -| `clusterNetworks[]` -| `object` -| ClusterNetworkEntry defines an individual cluster network. The CIDRs cannot overlap with other cluster network CIDRs, CIDRs reserved for external ips, CIDRs reserved for service networks, and CIDRs reserved for ingress ips. - -| `hostsubnetlength` -| `integer` -| HostSubnetLength is the number of bits of network to allocate to each node. eg, 8 would mean that each node would have a /24 slice of the overlay network for its pods - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `mtu` -| `integer` -| MTU is the MTU for the overlay network. This should be 50 less than the MTU of the network connecting the nodes. It is normally autodetected by the cluster network operator. - -| `network` -| `string` -| Network is a CIDR string specifying the global overlay network's L3 space - -| `pluginName` -| `string` -| PluginName is the name of the network plugin being used - -| `serviceNetwork` -| `string` -| ServiceNetwork is the CIDR range that Service IP addresses are allocated from - -| `vxlanPort` -| `integer` -| VXLANPort sets the VXLAN destination port used by the cluster. It is set by the master configuration file on startup and cannot be edited manually. Valid values for VXLANPort are integers 1-65535 inclusive and if unset defaults to 4789. Changing VXLANPort allows users to resolve issues between openshift SDN and other software trying to use the same VXLAN destination port. - -|=== -..clusterNetworks -Description:: - ClusterNetworks is a list of ClusterNetwork objects that defines the global overlay network's L3 space by specifying a set of CIDR and netmasks that the SDN can allocate addresses from. - -Type:: - `array` - - - - -..clusterNetworks[] -Description:: - ClusterNetworkEntry defines an individual cluster network. The CIDRs cannot overlap with other cluster network CIDRs, CIDRs reserved for external ips, CIDRs reserved for service networks, and CIDRs reserved for ingress ips. - -Type:: - `object` - -Required:: - - `CIDR` - - `hostSubnetLength` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `CIDR` -| `string` -| CIDR defines the total range of a cluster networks address space. - -| `hostSubnetLength` -| `integer` -| HostSubnetLength is the number of bits of the accompanying CIDR address to allocate to each node. eg, 8 would mean that each node would have a /24 slice of the overlay network for its pods. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/network.openshift.io/v1/clusternetworks` -- `DELETE`: delete collection of ClusterNetwork -- `GET`: list objects of kind ClusterNetwork -- `POST`: create a ClusterNetwork -* `/apis/network.openshift.io/v1/clusternetworks/{name}` -- `DELETE`: delete a ClusterNetwork -- `GET`: read the specified ClusterNetwork -- `PATCH`: partially update the specified ClusterNetwork -- `PUT`: replace the specified ClusterNetwork - - -=== /apis/network.openshift.io/v1/clusternetworks - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterNetwork - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterNetwork - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusternetworklist-network-openshift-io-v1[`ClusterNetworkList network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterNetwork - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| 202 - Accepted -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/network.openshift.io/v1/clusternetworks/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterNetwork -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterNetwork - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterNetwork - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterNetwork - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterNetwork - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`ClusterNetwork network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc b/rest_api/network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc deleted file mode 100644 index ced0672a7358..000000000000 --- a/rest_api/network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc +++ /dev/null @@ -1,567 +0,0 @@ -[id="egressnetworkpolicy-network-openshift-io-v1"] -= EgressNetworkPolicy [network.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - EgressNetworkPolicy describes the current egress network policy for a Namespace. When using the 'redhat/openshift-ovs-multitenant' network plugin, traffic from a pod to an IP address outside the cluster will be checked against each EgressNetworkPolicyRule in the pod's namespace's EgressNetworkPolicy, in order. If no rule matches (or no EgressNetworkPolicy is present) then the traffic will be allowed by default. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the current egress network policy - -|=== -..spec -Description:: - spec is the specification of the current egress network policy - -Type:: - `object` - -Required:: - - `egress` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `egress` -| `array` -| egress contains the list of egress policy rules - -| `egress[]` -| `object` -| EgressNetworkPolicyRule contains a single egress network policy rule - -|=== -..spec.egress -Description:: - egress contains the list of egress policy rules - -Type:: - `array` - - - - -..spec.egress[] -Description:: - EgressNetworkPolicyRule contains a single egress network policy rule - -Type:: - `object` - -Required:: - - `to` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `to` -| `object` -| to is the target that traffic is allowed/denied to - -| `type` -| `string` -| type marks this as an "Allow" or "Deny" rule - -|=== -..spec.egress[].to -Description:: - to is the target that traffic is allowed/denied to - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cidrSelector` -| `string` -| cidrSelector is the CIDR range to allow/deny traffic to. If this is set, dnsName must be unset - -| `dnsName` -| `string` -| dnsName is the domain name to allow/deny traffic to. If this is set, cidrSelector must be unset - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/network.openshift.io/v1/egressnetworkpolicies` -- `GET`: list objects of kind EgressNetworkPolicy -* `/apis/network.openshift.io/v1/namespaces/{namespace}/egressnetworkpolicies` -- `DELETE`: delete collection of EgressNetworkPolicy -- `GET`: list objects of kind EgressNetworkPolicy -- `POST`: create an EgressNetworkPolicy -* `/apis/network.openshift.io/v1/namespaces/{namespace}/egressnetworkpolicies/{name}` -- `DELETE`: delete an EgressNetworkPolicy -- `GET`: read the specified EgressNetworkPolicy -- `PATCH`: partially update the specified EgressNetworkPolicy -- `PUT`: replace the specified EgressNetworkPolicy - - -=== /apis/network.openshift.io/v1/egressnetworkpolicies - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind EgressNetworkPolicy - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#egressnetworkpolicylist-network-openshift-io-v1[`EgressNetworkPolicyList network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/network.openshift.io/v1/namespaces/{namespace}/egressnetworkpolicies - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of EgressNetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind EgressNetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#egressnetworkpolicylist-network-openshift-io-v1[`EgressNetworkPolicyList network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an EgressNetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| 202 - Accepted -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/network.openshift.io/v1/namespaces/{namespace}/egressnetworkpolicies/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the EgressNetworkPolicy -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an EgressNetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified EgressNetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified EgressNetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified EgressNetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`EgressNetworkPolicy network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/endpoints-core-v1.adoc b/rest_api/network_apis/endpoints-core-v1.adoc deleted file mode 100644 index 0ddfe2e234b9..000000000000 --- a/rest_api/network_apis/endpoints-core-v1.adoc +++ /dev/null @@ -1,510 +0,0 @@ -[id="endpoints-core-v1"] -= Endpoints [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Endpoints is a collection of endpoints that implement the actual service. Example: - Name: "mysvc", - Subsets: [ - { - Addresses: [{"ip": "10.10.1.1"}, {"ip": "10.10.2.2"}], - Ports: [{"name": "a", "port": 8675}, {"name": "b", "port": 309}] - }, - { - Addresses: [{"ip": "10.10.3.3"}], - Ports: [{"name": "a", "port": 93}, {"name": "b", "port": 76}] - }, - ] - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `subsets` -| xref:../objects/index.adoc#endpointsubset-core-v1[`array (EndpointSubset core/v1)`] -| The set of all endpoints is the union of all subsets. Addresses are placed into subsets according to the IPs they share. A single address with multiple ports, some of which are ready and some of which are not (because they come from different containers) will result in the address being displayed in different subsets for the different ports. No address will appear in both Addresses and NotReadyAddresses in the same subset. Sets of addresses and ports that comprise a service. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/endpoints` -- `GET`: list or watch objects of kind Endpoints -* `/api/v1/namespaces/{namespace}/endpoints` -- `DELETE`: delete collection of Endpoints -- `GET`: list or watch objects of kind Endpoints -- `POST`: create Endpoints -* `/api/v1/namespaces/{namespace}/endpoints/{name}` -- `DELETE`: delete Endpoints -- `GET`: read the specified Endpoints -- `PATCH`: partially update the specified Endpoints -- `PUT`: replace the specified Endpoints - - -=== /api/v1/endpoints - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Endpoints - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#endpointslist-core-v1[`EndpointsList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/endpoints - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Endpoints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Endpoints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#endpointslist-core-v1[`EndpointsList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create Endpoints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| 201 - Created -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| 202 - Accepted -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/endpoints/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Endpoints -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete Endpoints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Endpoints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Endpoints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Endpoints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| 201 - Created -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`Endpoints core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc b/rest_api/network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc deleted file mode 100644 index 6ce229611de5..000000000000 --- a/rest_api/network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc +++ /dev/null @@ -1,644 +0,0 @@ -[id="endpointslice-discovery-k8s-io-v1beta1"] -= EndpointSlice [discovery.k8s.io/v1beta1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - EndpointSlice represents a subset of the endpoints that implement a service. For a given service there may be multiple EndpointSlice objects, selected by labels, which must be joined to produce the full set of endpoints. - -Type:: - `object` - -Required:: - - `addressType` - - `endpoints` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `addressType` -| `string` -| addressType specifies the type of address carried by this EndpointSlice. All addresses in this slice must be the same type. This field is immutable after creation. The following address types are currently supported: * IPv4: Represents an IPv4 Address. * IPv6: Represents an IPv6 Address. * FQDN: Represents a Fully Qualified Domain Name. - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `endpoints` -| `array` -| endpoints is a list of unique endpoints in this slice. Each slice may include a maximum of 1000 endpoints. - -| `endpoints[]` -| `object` -| Endpoint represents a single logical "backend" implementing a service. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. - -| `ports` -| `array` -| ports specifies the list of network ports exposed by each endpoint in this slice. Each port must have a unique name. When ports is empty, it indicates that there are no defined ports. When a port is defined with a nil port value, it indicates "all ports". Each slice may include a maximum of 100 ports. - -| `ports[]` -| `object` -| EndpointPort represents a Port used by an EndpointSlice - -|=== -..endpoints -Description:: - endpoints is a list of unique endpoints in this slice. Each slice may include a maximum of 1000 endpoints. - -Type:: - `array` - - - - -..endpoints[] -Description:: - Endpoint represents a single logical "backend" implementing a service. - -Type:: - `object` - -Required:: - - `addresses` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `addresses` -| `array (string)` -| addresses of this endpoint. The contents of this field are interpreted according to the corresponding EndpointSlice addressType field. Consumers must handle different types of addresses in the context of their own capabilities. This must contain at least one address but no more than 100. - -| `conditions` -| `object` -| EndpointConditions represents the current condition of an endpoint. - -| `hostname` -| `string` -| hostname of this endpoint. This field may be used by consumers of endpoints to distinguish endpoints from each other (e.g. in DNS names). Multiple endpoints which use the same hostname should be considered fungible (e.g. multiple A values in DNS). Must be lowercase and pass DNS Label (RFC 1123) validation. - -| `nodeName` -| `string` -| nodeName represents the name of the Node hosting this endpoint. This can be used to determine endpoints local to a Node. This field can be enabled with the EndpointSliceNodeName feature gate. - -| `targetRef` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| targetRef is a reference to a Kubernetes object that represents this endpoint. - -| `topology` -| `object (string)` -| topology contains arbitrary topology information associated with the endpoint. These key/value pairs must conform with the label format. https://kubernetes.io/docs/concepts/overview/working-with-objects/labels Topology may include a maximum of 16 key/value pairs. This includes, but is not limited to the following well known keys: * kubernetes.io/hostname: the value indicates the hostname of the node - where the endpoint is located. This should match the corresponding - node label. -* topology.kubernetes.io/zone: the value indicates the zone where the - endpoint is located. This should match the corresponding node label. -* topology.kubernetes.io/region: the value indicates the region where the - endpoint is located. This should match the corresponding node label. -This field is deprecated and will be removed in future api versions. - -|=== -..endpoints[].conditions -Description:: - EndpointConditions represents the current condition of an endpoint. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ready` -| `boolean` -| ready indicates that this endpoint is prepared to receive traffic, according to whatever system is managing the endpoint. A nil value indicates an unknown state. In most cases consumers should interpret this unknown state as ready. For compatibility reasons, ready should never be "true" for terminating endpoints. - -| `serving` -| `boolean` -| serving is identical to ready except that it is set regardless of the terminating state of endpoints. This condition should be set to true for a ready endpoint that is terminating. If nil, consumers should defer to the ready condition. This field can be enabled with the EndpointSliceTerminatingCondition feature gate. - -| `terminating` -| `boolean` -| terminating indicates that this endpoint is terminating. A nil value indicates an unknown state. Consumers should interpret this unknown state to mean that the endpoint is not terminating. This field can be enabled with the EndpointSliceTerminatingCondition feature gate. - -|=== -..ports -Description:: - ports specifies the list of network ports exposed by each endpoint in this slice. Each port must have a unique name. When ports is empty, it indicates that there are no defined ports. When a port is defined with a nil port value, it indicates "all ports". Each slice may include a maximum of 100 ports. - -Type:: - `array` - - - - -..ports[] -Description:: - EndpointPort represents a Port used by an EndpointSlice - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `appProtocol` -| `string` -| The application protocol for this port. This field follows standard Kubernetes label syntax. Un-prefixed names are reserved for IANA standard service names (as per RFC-6335 and http://www.iana.org/assignments/service-names). Non-standard protocols should use prefixed names such as mycompany.com/my-custom-protocol. - -| `name` -| `string` -| The name of this port. All ports in an EndpointSlice must have a unique name. If the EndpointSlice is dervied from a Kubernetes service, this corresponds to the Service.ports[].name. Name must either be an empty string or pass DNS_LABEL validation: * must be no more than 63 characters long. * must consist of lower case alphanumeric characters or '-'. * must start and end with an alphanumeric character. Default is empty string. - -| `port` -| `integer` -| The port number of the endpoint. If this is not specified, ports are not restricted and must be interpreted in the context of the specific consumer. - -| `protocol` -| `string` -| The IP protocol for this port. Must be UDP, TCP, or SCTP. Default is TCP. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/discovery.k8s.io/v1beta1/endpointslices` -- `GET`: list or watch objects of kind EndpointSlice -* `/apis/discovery.k8s.io/v1beta1/namespaces/{namespace}/endpointslices` -- `DELETE`: delete collection of EndpointSlice -- `GET`: list or watch objects of kind EndpointSlice -- `POST`: create an EndpointSlice -* `/apis/discovery.k8s.io/v1beta1/namespaces/{namespace}/endpointslices/{name}` -- `DELETE`: delete an EndpointSlice -- `GET`: read the specified EndpointSlice -- `PATCH`: partially update the specified EndpointSlice -- `PUT`: replace the specified EndpointSlice - - -=== /apis/discovery.k8s.io/v1beta1/endpointslices - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind EndpointSlice - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#endpointslicelist-discovery-k8s-io-v1beta1[`EndpointSliceList discovery.k8s.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/discovery.k8s.io/v1beta1/namespaces/{namespace}/endpointslices - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of EndpointSlice - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind EndpointSlice - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#endpointslicelist-discovery-k8s-io-v1beta1[`EndpointSliceList discovery.k8s.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an EndpointSlice - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| 201 - Created -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| 202 - Accepted -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/discovery.k8s.io/v1beta1/namespaces/{namespace}/endpointslices/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the EndpointSlice -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an EndpointSlice - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified EndpointSlice - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified EndpointSlice - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified EndpointSlice - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| 201 - Created -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`EndpointSlice discovery.k8s.io/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/hostsubnet-network-openshift-io-v1.adoc b/rest_api/network_apis/hostsubnet-network-openshift-io-v1.adoc deleted file mode 100644 index 82408b303c6a..000000000000 --- a/rest_api/network_apis/hostsubnet-network-openshift-io-v1.adoc +++ /dev/null @@ -1,422 +0,0 @@ -[id="hostsubnet-network-openshift-io-v1"] -= HostSubnet [network.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - HostSubnet describes the container subnet network on a node. The HostSubnet object must have the same name as the Node object it corresponds to. - -Type:: - `object` - -Required:: - - `host` - - `hostIP` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `egressCIDRs` -| `array (string)` -| EgressCIDRs is the list of CIDR ranges available for automatically assigning egress IPs to this node from. If this field is set then EgressIPs should be treated as read-only. - -| `egressIPs` -| `array (string)` -| EgressIPs is the list of automatic egress IP addresses currently hosted by this node. If EgressCIDRs is empty, this can be set by hand; if EgressCIDRs is set then the master will overwrite the value here with its own allocation of egress IPs. - -| `host` -| `string` -| Host is the name of the node. (This is the same as the object's name, but both fields must be set.) - -| `hostIP` -| `string` -| HostIP is the IP address to be used as a VTEP by other nodes in the overlay network - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `subnet` -| `string` -| Subnet is the CIDR range of the overlay network assigned to the node for its pods - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/network.openshift.io/v1/hostsubnets` -- `DELETE`: delete collection of HostSubnet -- `GET`: list objects of kind HostSubnet -- `POST`: create a HostSubnet -* `/apis/network.openshift.io/v1/hostsubnets/{name}` -- `DELETE`: delete a HostSubnet -- `GET`: read the specified HostSubnet -- `PATCH`: partially update the specified HostSubnet -- `PUT`: replace the specified HostSubnet - - -=== /apis/network.openshift.io/v1/hostsubnets - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of HostSubnet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind HostSubnet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#hostsubnetlist-network-openshift-io-v1[`HostSubnetList network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a HostSubnet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| 202 - Accepted -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/network.openshift.io/v1/hostsubnets/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the HostSubnet -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a HostSubnet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified HostSubnet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified HostSubnet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified HostSubnet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`HostSubnet network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/ingress-networking-k8s-io-v1.adoc b/rest_api/network_apis/ingress-networking-k8s-io-v1.adoc deleted file mode 100644 index 3d5751a32b5f..000000000000 --- a/rest_api/network_apis/ingress-networking-k8s-io-v1.adoc +++ /dev/null @@ -1,976 +0,0 @@ -[id="ingress-networking-k8s-io-v1"] -= Ingress [networking.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Ingress is a collection of rules that allow inbound connections to reach the endpoints defined by a backend. An Ingress can be configured to give services externally-reachable urls, load balance traffic, terminate SSL, offer name based virtual hosting etc. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| IngressSpec describes the Ingress the user wishes to exist. - -| `status` -| `object` -| IngressStatus describe the current state of the Ingress. - -|=== -..spec -Description:: - IngressSpec describes the Ingress the user wishes to exist. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultBackend` -| `object` -| IngressBackend describes all endpoints for a given service and port. - -| `ingressClassName` -| `string` -| IngressClassName is the name of the IngressClass cluster resource. The associated IngressClass defines which controller will implement the resource. This replaces the deprecated `kubernetes.io/ingress.class` annotation. For backwards compatibility, when that annotation is set, it must be given precedence over this field. The controller may emit a warning if the field and annotation have different values. Implementations of this API should ignore Ingresses without a class specified. An IngressClass resource may be marked as default, which can be used to set a default value for this field. For more information, refer to the IngressClass documentation. - -| `rules` -| `array` -| A list of host rules used to configure the Ingress. If unspecified, or no rule matches, all traffic is sent to the default backend. - -| `rules[]` -| `object` -| IngressRule represents the rules mapping the paths under a specified host to the related backend services. Incoming requests are first evaluated for a host match, then routed to the backend associated with the matching IngressRuleValue. - -| `tls` -| `array` -| TLS configuration. Currently the Ingress only supports a single TLS port, 443. If multiple members of this list specify different hosts, they will be multiplexed on the same port according to the hostname specified through the SNI TLS extension, if the ingress controller fulfilling the ingress supports SNI. - -| `tls[]` -| `object` -| IngressTLS describes the transport layer security associated with an Ingress. - -|=== -..spec.defaultBackend -Description:: - IngressBackend describes all endpoints for a given service and port. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `resource` -| xref:../objects/index.adoc#typedlocalobjectreference-core-v1[`TypedLocalObjectReference core/v1`] -| Resource is an ObjectRef to another Kubernetes resource in the namespace of the Ingress object. If resource is specified, a service.Name and service.Port must not be specified. This is a mutually exclusive setting with "Service". - -| `service` -| `object` -| IngressServiceBackend references a Kubernetes Service as a Backend. - -|=== -..spec.defaultBackend.service -Description:: - IngressServiceBackend references a Kubernetes Service as a Backend. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the referenced service. The service must exist in the same namespace as the Ingress object. - -| `port` -| `object` -| ServiceBackendPort is the service port being referenced. - -|=== -..spec.defaultBackend.service.port -Description:: - ServiceBackendPort is the service port being referenced. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the name of the port on the Service. This is a mutually exclusive setting with "Number". - -| `number` -| `integer` -| Number is the numerical port number (e.g. 80) on the Service. This is a mutually exclusive setting with "Name". - -|=== -..spec.rules -Description:: - A list of host rules used to configure the Ingress. If unspecified, or no rule matches, all traffic is sent to the default backend. - -Type:: - `array` - - - - -..spec.rules[] -Description:: - IngressRule represents the rules mapping the paths under a specified host to the related backend services. Incoming requests are first evaluated for a host match, then routed to the backend associated with the matching IngressRuleValue. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host is the fully qualified domain name of a network host, as defined by RFC 3986. Note the following deviations from the "host" part of the URI as defined in RFC 3986: 1. IPs are not allowed. Currently an IngressRuleValue can only apply to - the IP in the Spec of the parent Ingress. -2. The `:` delimiter is not respected because ports are not allowed. - Currently the port of an Ingress is implicitly :80 for http and - :443 for https. -Both these may change in the future. Incoming requests are matched against the host before the IngressRuleValue. If the host is unspecified, the Ingress routes all traffic based on the specified IngressRuleValue. - -Host can be "precise" which is a domain name without the terminating dot of a network host (e.g. "foo.bar.com") or "wildcard", which is a domain name prefixed with a single wildcard label (e.g. "*.foo.com"). The wildcard character '*' must appear by itself as the first DNS label and matches only a single label. You cannot have a wildcard label by itself (e.g. Host == "*"). Requests will be matched against the Host field in the following way: 1. If Host is precise, the request matches this rule if the http host header is equal to Host. 2. If Host is a wildcard, then the request matches this rule if the http host header is to equal to the suffix (removing the first label) of the wildcard rule. - -| `http` -| `object` -| HTTPIngressRuleValue is a list of http selectors pointing to backends. In the example: http://<host>/<path>?<searchpart> -> backend where where parts of the url correspond to RFC 3986, this resource will be used to match against everything after the last '/' and before the first '?' or '#'. - -|=== -..spec.rules[].http -Description:: - HTTPIngressRuleValue is a list of http selectors pointing to backends. In the example: http://<host>/<path>?<searchpart> -> backend where where parts of the url correspond to RFC 3986, this resource will be used to match against everything after the last '/' and before the first '?' or '#'. - -Type:: - `object` - -Required:: - - `paths` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `paths` -| `array` -| A collection of paths that map requests to backends. - -| `paths[]` -| `object` -| HTTPIngressPath associates a path with a backend. Incoming urls matching the path are forwarded to the backend. - -|=== -..spec.rules[].http.paths -Description:: - A collection of paths that map requests to backends. - -Type:: - `array` - - - - -..spec.rules[].http.paths[] -Description:: - HTTPIngressPath associates a path with a backend. Incoming urls matching the path are forwarded to the backend. - -Type:: - `object` - -Required:: - - `backend` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `backend` -| `object` -| IngressBackend describes all endpoints for a given service and port. - -| `path` -| `string` -| Path is matched against the path of an incoming request. Currently it can contain characters disallowed from the conventional "path" part of a URL as defined by RFC 3986. Paths must begin with a '/'. When unspecified, all paths from incoming requests are matched. - -| `pathType` -| `string` -| PathType determines the interpretation of the Path matching. PathType can be one of the following values: * Exact: Matches the URL path exactly. * Prefix: Matches based on a URL path prefix split by '/'. Matching is - done on a path element by element basis. A path element refers is the - list of labels in the path split by the '/' separator. A request is a - match for path p if every p is an element-wise prefix of p of the - request path. Note that if the last element of the path is a substring - of the last element in request path, it is not a match (e.g. /foo/bar - matches /foo/bar/baz, but does not match /foo/barbaz). -* ImplementationSpecific: Interpretation of the Path matching is up to - the IngressClass. Implementations can treat this as a separate PathType - or treat it identically to Prefix or Exact path types. -Implementations are required to support all path types. - -|=== -..spec.rules[].http.paths[].backend -Description:: - IngressBackend describes all endpoints for a given service and port. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `resource` -| xref:../objects/index.adoc#typedlocalobjectreference-core-v1[`TypedLocalObjectReference core/v1`] -| Resource is an ObjectRef to another Kubernetes resource in the namespace of the Ingress object. If resource is specified, a service.Name and service.Port must not be specified. This is a mutually exclusive setting with "Service". - -| `service` -| `object` -| IngressServiceBackend references a Kubernetes Service as a Backend. - -|=== -..spec.rules[].http.paths[].backend.service -Description:: - IngressServiceBackend references a Kubernetes Service as a Backend. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the referenced service. The service must exist in the same namespace as the Ingress object. - -| `port` -| `object` -| ServiceBackendPort is the service port being referenced. - -|=== -..spec.rules[].http.paths[].backend.service.port -Description:: - ServiceBackendPort is the service port being referenced. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the name of the port on the Service. This is a mutually exclusive setting with "Number". - -| `number` -| `integer` -| Number is the numerical port number (e.g. 80) on the Service. This is a mutually exclusive setting with "Name". - -|=== -..spec.tls -Description:: - TLS configuration. Currently the Ingress only supports a single TLS port, 443. If multiple members of this list specify different hosts, they will be multiplexed on the same port according to the hostname specified through the SNI TLS extension, if the ingress controller fulfilling the ingress supports SNI. - -Type:: - `array` - - - - -..spec.tls[] -Description:: - IngressTLS describes the transport layer security associated with an Ingress. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hosts` -| `array (string)` -| Hosts are a list of hosts included in the TLS certificate. The values in this list must match the name/s used in the tlsSecret. Defaults to the wildcard host setting for the loadbalancer controller fulfilling this Ingress, if left unspecified. - -| `secretName` -| `string` -| SecretName is the name of the secret used to terminate TLS traffic on port 443. Field is left optional to allow TLS routing based on SNI hostname alone. If the SNI host in a listener conflicts with the "Host" header field used by an IngressRule, the SNI host is used for termination and value of the Host header is used for routing. - -|=== -..status -Description:: - IngressStatus describe the current state of the Ingress. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `loadBalancer` -| xref:../objects/index.adoc#loadbalancerstatus-core-v1[`LoadBalancerStatus core/v1`] -| LoadBalancer contains the current status of the load-balancer. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/networking.k8s.io/v1/ingresses` -- `GET`: list or watch objects of kind Ingress -* `/apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses` -- `DELETE`: delete collection of Ingress -- `GET`: list or watch objects of kind Ingress -- `POST`: create an Ingress -* `/apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}` -- `DELETE`: delete an Ingress -- `GET`: read the specified Ingress -- `PATCH`: partially update the specified Ingress -- `PUT`: replace the specified Ingress -* `/apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}/status` -- `GET`: read status of the specified Ingress -- `PATCH`: partially update status of the specified Ingress -- `PUT`: replace status of the specified Ingress - - -=== /apis/networking.k8s.io/v1/ingresses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Ingress - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#ingresslist-networking-k8s-io-v1[`IngressList networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#ingresslist-networking-k8s-io-v1[`IngressList networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 201 - Created -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 202 - Accepted -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Ingress -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 201 - Created -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Ingress -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Ingress - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Ingress - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 201 - Created -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`Ingress networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/ingressclass-networking-k8s-io-v1.adoc b/rest_api/network_apis/ingressclass-networking-k8s-io-v1.adoc deleted file mode 100644 index 514693129b9f..000000000000 --- a/rest_api/network_apis/ingressclass-networking-k8s-io-v1.adoc +++ /dev/null @@ -1,444 +0,0 @@ -[id="ingressclass-networking-k8s-io-v1"] -= IngressClass [networking.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - IngressClass represents the class of the Ingress, referenced by the Ingress Spec. The `ingressclass.kubernetes.io/is-default-class` annotation can be used to indicate that an IngressClass should be considered default. When a single IngressClass resource has this annotation set to true, new Ingress resources without a class specified will be assigned this default class. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| IngressClassSpec provides information about the class of an Ingress. - -|=== -..spec -Description:: - IngressClassSpec provides information about the class of an Ingress. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `controller` -| `string` -| Controller refers to the name of the controller that should handle this class. This allows for different "flavors" that are controlled by the same controller. For example, you may have different Parameters for the same implementing controller. This should be specified as a domain-prefixed path no more than 250 characters in length, e.g. "acme.io/ingress-controller". This field is immutable. - -| `parameters` -| xref:../objects/index.adoc#typedlocalobjectreference-core-v1[`TypedLocalObjectReference core/v1`] -| Parameters is a link to a custom resource containing additional configuration for the controller. This is optional if the controller does not require extra parameters. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/networking.k8s.io/v1/ingressclasses` -- `DELETE`: delete collection of IngressClass -- `GET`: list or watch objects of kind IngressClass -- `POST`: create an IngressClass -* `/apis/networking.k8s.io/v1/ingressclasses/{name}` -- `DELETE`: delete an IngressClass -- `GET`: read the specified IngressClass -- `PATCH`: partially update the specified IngressClass -- `PUT`: replace the specified IngressClass - - -=== /apis/networking.k8s.io/v1/ingressclasses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of IngressClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind IngressClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#ingressclasslist-networking-k8s-io-v1[`IngressClassList networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an IngressClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| 201 - Created -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| 202 - Accepted -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/networking.k8s.io/v1/ingressclasses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the IngressClass -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an IngressClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified IngressClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified IngressClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified IngressClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| 201 - Created -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`IngressClass networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc b/rest_api/network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc deleted file mode 100644 index 9a1d818335e1..000000000000 --- a/rest_api/network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc +++ /dev/null @@ -1,542 +0,0 @@ -[id="ippool-whereabouts-cni-cncf-io-v1alpha1"] -= IPPool [whereabouts.cni.cncf.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - IPPool is the Schema for Whereabouts for IP address allocation - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| IPPoolSpec defines the desired state of IPPool - -|=== -..spec -Description:: - IPPoolSpec defines the desired state of IPPool - -Type:: - `object` - -Required:: - - `allocations` - - `range` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allocations` -| `object` -| Allocations is the set of allocated IPs for the given range. Its indices are a direct mapping to the IP with the same index/offset for the pool's range. - -| `allocations{}` -| `object` -| IPAllocation represents metadata about the pod/container owner of a specific IP - -| `range` -| `string` -| Range is a RFC 4632/4291-style string that represents an IP address and prefix length in CIDR notation - -|=== -..spec.allocations -Description:: - Allocations is the set of allocated IPs for the given range. Its indices are a direct mapping to the IP with the same index/offset for the pool's range. - -Type:: - `object` - - - - -..spec.allocations{} -Description:: - IPAllocation represents metadata about the pod/container owner of a specific IP - -Type:: - `object` - -Required:: - - `id` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `id` -| `string` -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/whereabouts.cni.cncf.io/v1alpha1/ippools` -- `GET`: list objects of kind IPPool -* `/apis/whereabouts.cni.cncf.io/v1alpha1/namespaces/{namespace}/ippools` -- `DELETE`: delete collection of IPPool -- `GET`: list objects of kind IPPool -- `POST`: create an IPPool -* `/apis/whereabouts.cni.cncf.io/v1alpha1/namespaces/{namespace}/ippools/{name}` -- `DELETE`: delete an IPPool -- `GET`: read the specified IPPool -- `PATCH`: partially update the specified IPPool -- `PUT`: replace the specified IPPool - - -=== /apis/whereabouts.cni.cncf.io/v1alpha1/ippools - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind IPPool - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#ippoollist-whereabouts-cni-cncf-io-v1alpha1[`IPPoolList whereabouts.cni.cncf.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/whereabouts.cni.cncf.io/v1alpha1/namespaces/{namespace}/ippools - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of IPPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind IPPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#ippoollist-whereabouts-cni-cncf-io-v1alpha1[`IPPoolList whereabouts.cni.cncf.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an IPPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| 201 - Created -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| 202 - Accepted -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/whereabouts.cni.cncf.io/v1alpha1/namespaces/{namespace}/ippools/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the IPPool -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an IPPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified IPPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified IPPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified IPPool - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| 201 - Created -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`IPPool whereabouts.cni.cncf.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/netnamespace-network-openshift-io-v1.adoc b/rest_api/network_apis/netnamespace-network-openshift-io-v1.adoc deleted file mode 100644 index c49a5042c63c..000000000000 --- a/rest_api/network_apis/netnamespace-network-openshift-io-v1.adoc +++ /dev/null @@ -1,414 +0,0 @@ -[id="netnamespace-network-openshift-io-v1"] -= NetNamespace [network.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - NetNamespace describes a single isolated network. When using the redhat/openshift-ovs-multitenant plugin, every Namespace will have a corresponding NetNamespace object with the same name. (When using redhat/openshift-ovs-subnet, NetNamespaces are not used.) - -Type:: - `object` - -Required:: - - `netid` - - `netname` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `egressIPs` -| `array (string)` -| EgressIPs is a list of reserved IPs that will be used as the source for external traffic coming from pods in this namespace. (If empty, external traffic will be masqueraded to Node IPs.) - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `netid` -| `integer` -| NetID is the network identifier of the network namespace assigned to each overlay network packet. This can be manipulated with the "oc adm pod-network" commands. - -| `netname` -| `string` -| NetName is the name of the network namespace. (This is the same as the object's name, but both fields must be set.) - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/network.openshift.io/v1/netnamespaces` -- `DELETE`: delete collection of NetNamespace -- `GET`: list objects of kind NetNamespace -- `POST`: create a NetNamespace -* `/apis/network.openshift.io/v1/netnamespaces/{name}` -- `DELETE`: delete a NetNamespace -- `GET`: read the specified NetNamespace -- `PATCH`: partially update the specified NetNamespace -- `PUT`: replace the specified NetNamespace - - -=== /apis/network.openshift.io/v1/netnamespaces - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of NetNamespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind NetNamespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#netnamespacelist-network-openshift-io-v1[`NetNamespaceList network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a NetNamespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| 202 - Accepted -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/network.openshift.io/v1/netnamespaces/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the NetNamespace -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a NetNamespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified NetNamespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified NetNamespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified NetNamespace - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`NetNamespace network.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/network-apis-index.adoc b/rest_api/network_apis/network-apis-index.adoc deleted file mode 100644 index 40d0fb54881f..000000000000 --- a/rest_api/network_apis/network-apis-index.adoc +++ /dev/null @@ -1,139 +0,0 @@ -[id="network-apis"] -= Network APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== ClusterNetwork [network.openshift.io/v1] - -Description:: - ClusterNetwork describes the cluster network. There is normally only one object of this type, named "default", which is created by the SDN network plugin based on the master configuration when the cluster is brought up for the first time. - -Type:: - `object` - -== Endpoints [core/v1] - -Description:: - Endpoints is a collection of endpoints that implement the actual service. Example: - Name: "mysvc", - Subsets: [ - { - Addresses: [{"ip": "10.10.1.1"}, {"ip": "10.10.2.2"}], - Ports: [{"name": "a", "port": 8675}, {"name": "b", "port": 309}] - }, - { - Addresses: [{"ip": "10.10.3.3"}], - Ports: [{"name": "a", "port": 93}, {"name": "b", "port": 76}] - }, - ] - -Type:: - `object` - -== EndpointSlice [discovery.k8s.io/v1beta1] - -Description:: - EndpointSlice represents a subset of the endpoints that implement a service. For a given service there may be multiple EndpointSlice objects, selected by labels, which must be joined to produce the full set of endpoints. - -Type:: - `object` - -== EgressNetworkPolicy [network.openshift.io/v1] - -Description:: - EgressNetworkPolicy describes the current egress network policy for a Namespace. When using the 'redhat/openshift-ovs-multitenant' network plugin, traffic from a pod to an IP address outside the cluster will be checked against each EgressNetworkPolicyRule in the pod's namespace's EgressNetworkPolicy, in order. If no rule matches (or no EgressNetworkPolicy is present) then the traffic will be allowed by default. - -Type:: - `object` - -== HostSubnet [network.openshift.io/v1] - -Description:: - HostSubnet describes the container subnet network on a node. The HostSubnet object must have the same name as the Node object it corresponds to. - -Type:: - `object` - -== Ingress [networking.k8s.io/v1] - -Description:: - Ingress is a collection of rules that allow inbound connections to reach the endpoints defined by a backend. An Ingress can be configured to give services externally-reachable urls, load balance traffic, terminate SSL, offer name based virtual hosting etc. - -Type:: - `object` - -== IngressClass [networking.k8s.io/v1] - -Description:: - IngressClass represents the class of the Ingress, referenced by the Ingress Spec. The `ingressclass.kubernetes.io/is-default-class` annotation can be used to indicate that an IngressClass should be considered default. When a single IngressClass resource has this annotation set to true, new Ingress resources without a class specified will be assigned this default class. - -Type:: - `object` - -== IPPool [whereabouts.cni.cncf.io/v1alpha1] - -Description:: - IPPool is the Schema for Whereabouts for IP address allocation - -Type:: - `object` - -== NetNamespace [network.openshift.io/v1] - -Description:: - NetNamespace describes a single isolated network. When using the redhat/openshift-ovs-multitenant plugin, every Namespace will have a corresponding NetNamespace object with the same name. (When using redhat/openshift-ovs-subnet, NetNamespaces are not used.) - -Type:: - `object` - -== NetworkAttachmentDefinition [k8s.cni.cncf.io/v1] - -Description:: - NetworkAttachmentDefinition is a CRD schema specified by the Network Plumbing Working Group to express the intent for attaching pods to one or more logical or physical networks. More information available at: https://github.com/k8snetworkplumbingwg/multi-net-spec - -Type:: - `object` - -== NetworkPolicy [networking.k8s.io/v1] - -Description:: - NetworkPolicy describes what network traffic is allowed for a set of Pods - -Type:: - `object` - -== PodNetworkConnectivityCheck [controlplane.operator.openshift.io/v1alpha1] - -Description:: - PodNetworkConnectivityCheck - -Type:: - `object` - -== Route [route.openshift.io/v1] - -Description:: - A route allows developers to expose services through an HTTP(S) aware load balancing and proxy layer via a public DNS entry. The route may further specify TLS options and a certificate, or specify a public CNAME that the router should also accept for HTTP and HTTPS traffic. An administrator typically configures their router to be visible outside the cluster firewall, and may also add additional security, caching, or traffic controls on the service content. Routers usually talk directly to the service endpoints. - -Once a route is created, the `host` field may not be changed. Generally, routers use the oldest route with a given host when resolving conflicts. - -Routers are subject to additional customization and may support additional controls via the annotations field. - -Because administrators may configure multiple routers, the route status field is used to return information to clients about the names and states of the route under each router. If a client chooses a duplicate name, for instance, the route status conditions are used to indicate the route cannot be chosen. - -To enable HTTP/2 ALPN on a route it requires a custom (non-wildcard) certificate. This prevents connection coalescing by clients, notably web browsers. We do not support HTTP/2 ALPN on routes that use the default certificate because of the risk of connection re-use/coalescing. Routes that do not have their own custom certificate will not be HTTP/2 ALPN-enabled on either the frontend or the backend. - -Type:: - `object` - -== Service [core/v1] - -Description:: - Service is a named abstraction of software service (for example, mysql) consisting of local port (for example 3306) that the proxy listens on, and the selector that determines which pods will answer requests sent through the proxy. - -Type:: - `object` - diff --git a/rest_api/network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc b/rest_api/network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc deleted file mode 100644 index 017dd60a6844..000000000000 --- a/rest_api/network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc +++ /dev/null @@ -1,500 +0,0 @@ -[id="networkattachmentdefinition-k8s-cni-cncf-io-v1"] -= NetworkAttachmentDefinition [k8s.cni.cncf.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - NetworkAttachmentDefinition is a CRD schema specified by the Network Plumbing Working Group to express the intent for attaching pods to one or more logical or physical networks. More information available at: https://github.com/k8snetworkplumbingwg/multi-net-spec - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| NetworkAttachmentDefinition spec defines the desired state of a network attachment - -|=== -..spec -Description:: - NetworkAttachmentDefinition spec defines the desired state of a network attachment - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `config` -| `string` -| NetworkAttachmentDefinition config is a JSON-formatted CNI configuration - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/k8s.cni.cncf.io/v1/network-attachment-definitions` -- `GET`: list objects of kind NetworkAttachmentDefinition -* `/apis/k8s.cni.cncf.io/v1/namespaces/{namespace}/network-attachment-definitions` -- `DELETE`: delete collection of NetworkAttachmentDefinition -- `GET`: list objects of kind NetworkAttachmentDefinition -- `POST`: create a NetworkAttachmentDefinition -* `/apis/k8s.cni.cncf.io/v1/namespaces/{namespace}/network-attachment-definitions/{name}` -- `DELETE`: delete a NetworkAttachmentDefinition -- `GET`: read the specified NetworkAttachmentDefinition -- `PATCH`: partially update the specified NetworkAttachmentDefinition -- `PUT`: replace the specified NetworkAttachmentDefinition - - -=== /apis/k8s.cni.cncf.io/v1/network-attachment-definitions - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind NetworkAttachmentDefinition - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#networkattachmentdefinitionlist-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinitionList k8s.cni.cncf.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/k8s.cni.cncf.io/v1/namespaces/{namespace}/network-attachment-definitions - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of NetworkAttachmentDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind NetworkAttachmentDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#networkattachmentdefinitionlist-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinitionList k8s.cni.cncf.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a NetworkAttachmentDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| 201 - Created -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| 202 - Accepted -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/k8s.cni.cncf.io/v1/namespaces/{namespace}/network-attachment-definitions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the NetworkAttachmentDefinition -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a NetworkAttachmentDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified NetworkAttachmentDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified NetworkAttachmentDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified NetworkAttachmentDefinition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| 201 - Created -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`NetworkAttachmentDefinition k8s.cni.cncf.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/networkpolicy-networking-k8s-io-v1.adoc b/rest_api/network_apis/networkpolicy-networking-k8s-io-v1.adoc deleted file mode 100644 index 71b060327294..000000000000 --- a/rest_api/network_apis/networkpolicy-networking-k8s-io-v1.adoc +++ /dev/null @@ -1,820 +0,0 @@ -[id="networkpolicy-networking-k8s-io-v1"] -= NetworkPolicy [networking.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - NetworkPolicy describes what network traffic is allowed for a set of Pods - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| NetworkPolicySpec provides the specification of a NetworkPolicy - -|=== -..spec -Description:: - NetworkPolicySpec provides the specification of a NetworkPolicy - -Type:: - `object` - -Required:: - - `podSelector` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `egress` -| `array` -| List of egress rules to be applied to the selected pods. Outgoing traffic is allowed if there are no NetworkPolicies selecting the pod (and cluster policy otherwise allows the traffic), OR if the traffic matches at least one egress rule across all of the NetworkPolicy objects whose podSelector matches the pod. If this field is empty then this NetworkPolicy limits all outgoing traffic (and serves solely to ensure that the pods it selects are isolated by default). This field is beta-level in 1.8 - -| `egress[]` -| `object` -| NetworkPolicyEgressRule describes a particular set of traffic that is allowed out of pods matched by a NetworkPolicySpec's podSelector. The traffic must match both ports and to. This type is beta-level in 1.8 - -| `ingress` -| `array` -| List of ingress rules to be applied to the selected pods. Traffic is allowed to a pod if there are no NetworkPolicies selecting the pod (and cluster policy otherwise allows the traffic), OR if the traffic source is the pod's local node, OR if the traffic matches at least one ingress rule across all of the NetworkPolicy objects whose podSelector matches the pod. If this field is empty then this NetworkPolicy does not allow any traffic (and serves solely to ensure that the pods it selects are isolated by default) - -| `ingress[]` -| `object` -| NetworkPolicyIngressRule describes a particular set of traffic that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The traffic must match both ports and from. - -| `podSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| Selects the pods to which this NetworkPolicy object applies. The array of ingress rules is applied to any pods selected by this field. Multiple network policies can select the same set of pods. In this case, the ingress rules for each are combined additively. This field is NOT optional and follows standard label selector semantics. An empty podSelector matches all pods in this namespace. - -| `policyTypes` -| `array (string)` -| List of rule types that the NetworkPolicy relates to. Valid options are "Ingress", "Egress", or "Ingress,Egress". If this field is not specified, it will default based on the existence of Ingress or Egress rules; policies that contain an Egress section are assumed to affect Egress, and all policies (whether or not they contain an Ingress section) are assumed to affect Ingress. If you want to write an egress-only policy, you must explicitly specify policyTypes [ "Egress" ]. Likewise, if you want to write a policy that specifies that no egress is allowed, you must specify a policyTypes value that include "Egress" (since such a policy would not include an Egress section and would otherwise default to just [ "Ingress" ]). This field is beta-level in 1.8 - -|=== -..spec.egress -Description:: - List of egress rules to be applied to the selected pods. Outgoing traffic is allowed if there are no NetworkPolicies selecting the pod (and cluster policy otherwise allows the traffic), OR if the traffic matches at least one egress rule across all of the NetworkPolicy objects whose podSelector matches the pod. If this field is empty then this NetworkPolicy limits all outgoing traffic (and serves solely to ensure that the pods it selects are isolated by default). This field is beta-level in 1.8 - -Type:: - `array` - - - - -..spec.egress[] -Description:: - NetworkPolicyEgressRule describes a particular set of traffic that is allowed out of pods matched by a NetworkPolicySpec's podSelector. The traffic must match both ports and to. This type is beta-level in 1.8 - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ports` -| `array` -| List of destination ports for outgoing traffic. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list. - -| `ports[]` -| `object` -| NetworkPolicyPort describes a port to allow traffic on - -| `to` -| `array` -| List of destinations for outgoing traffic of pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all destinations (traffic not restricted by destination). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the to list. - -| `to[]` -| `object` -| NetworkPolicyPeer describes a peer to allow traffic to/from. Only certain combinations of fields are allowed - -|=== -..spec.egress[].ports -Description:: - List of destination ports for outgoing traffic. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list. - -Type:: - `array` - - - - -..spec.egress[].ports[] -Description:: - NetworkPolicyPort describes a port to allow traffic on - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `port` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. - -| `protocol` -| `string` -| The protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP. - -|=== -..spec.egress[].to -Description:: - List of destinations for outgoing traffic of pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all destinations (traffic not restricted by destination). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the to list. - -Type:: - `array` - - - - -..spec.egress[].to[] -Description:: - NetworkPolicyPeer describes a peer to allow traffic to/from. Only certain combinations of fields are allowed - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ipBlock` -| `object` -| IPBlock describes a particular CIDR (Ex. "192.168.1.1/24","2001:db9::/64") that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs that should not be included within this rule. - -| `namespaceSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| Selects Namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces. - -If PodSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects all Pods in the Namespaces selected by NamespaceSelector. - -| `podSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| This is a label selector which selects Pods. This field follows standard label selector semantics; if present but empty, it selects all pods. - -If NamespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the Pods matching PodSelector in the policy's own Namespace. - -|=== -..spec.egress[].to[].ipBlock -Description:: - IPBlock describes a particular CIDR (Ex. "192.168.1.1/24","2001:db9::/64") that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs that should not be included within this rule. - -Type:: - `object` - -Required:: - - `cidr` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cidr` -| `string` -| CIDR is a string representing the IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" - -| `except` -| `array (string)` -| Except is a slice of CIDRs that should not be included within an IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" Except values will be rejected if they are outside the CIDR range - -|=== -..spec.ingress -Description:: - List of ingress rules to be applied to the selected pods. Traffic is allowed to a pod if there are no NetworkPolicies selecting the pod (and cluster policy otherwise allows the traffic), OR if the traffic source is the pod's local node, OR if the traffic matches at least one ingress rule across all of the NetworkPolicy objects whose podSelector matches the pod. If this field is empty then this NetworkPolicy does not allow any traffic (and serves solely to ensure that the pods it selects are isolated by default) - -Type:: - `array` - - - - -..spec.ingress[] -Description:: - NetworkPolicyIngressRule describes a particular set of traffic that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The traffic must match both ports and from. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `from` -| `array` -| List of sources which should be able to access the pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all sources (traffic not restricted by source). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the from list. - -| `from[]` -| `object` -| NetworkPolicyPeer describes a peer to allow traffic to/from. Only certain combinations of fields are allowed - -| `ports` -| `array` -| List of ports which should be made accessible on the pods selected for this rule. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list. - -| `ports[]` -| `object` -| NetworkPolicyPort describes a port to allow traffic on - -|=== -..spec.ingress[].from -Description:: - List of sources which should be able to access the pods selected for this rule. Items in this list are combined using a logical OR operation. If this field is empty or missing, this rule matches all sources (traffic not restricted by source). If this field is present and contains at least one item, this rule allows traffic only if the traffic matches at least one item in the from list. - -Type:: - `array` - - - - -..spec.ingress[].from[] -Description:: - NetworkPolicyPeer describes a peer to allow traffic to/from. Only certain combinations of fields are allowed - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ipBlock` -| `object` -| IPBlock describes a particular CIDR (Ex. "192.168.1.1/24","2001:db9::/64") that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs that should not be included within this rule. - -| `namespaceSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| Selects Namespaces using cluster-scoped labels. This field follows standard label selector semantics; if present but empty, it selects all namespaces. - -If PodSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects all Pods in the Namespaces selected by NamespaceSelector. - -| `podSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| This is a label selector which selects Pods. This field follows standard label selector semantics; if present but empty, it selects all pods. - -If NamespaceSelector is also set, then the NetworkPolicyPeer as a whole selects the Pods matching PodSelector in the Namespaces selected by NamespaceSelector. Otherwise it selects the Pods matching PodSelector in the policy's own Namespace. - -|=== -..spec.ingress[].from[].ipBlock -Description:: - IPBlock describes a particular CIDR (Ex. "192.168.1.1/24","2001:db9::/64") that is allowed to the pods matched by a NetworkPolicySpec's podSelector. The except entry describes CIDRs that should not be included within this rule. - -Type:: - `object` - -Required:: - - `cidr` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cidr` -| `string` -| CIDR is a string representing the IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" - -| `except` -| `array (string)` -| Except is a slice of CIDRs that should not be included within an IP Block Valid examples are "192.168.1.1/24" or "2001:db9::/64" Except values will be rejected if they are outside the CIDR range - -|=== -..spec.ingress[].ports -Description:: - List of ports which should be made accessible on the pods selected for this rule. Each item in this list is combined using a logical OR. If this field is empty or missing, this rule matches all ports (traffic not restricted by port). If this field is present and contains at least one item, then this rule allows traffic only if the traffic matches at least one port in the list. - -Type:: - `array` - - - - -..spec.ingress[].ports[] -Description:: - NetworkPolicyPort describes a port to allow traffic on - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `port` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| The port on the given protocol. This can either be a numerical or named port on a pod. If this field is not provided, this matches all port names and numbers. - -| `protocol` -| `string` -| The protocol (TCP, UDP, or SCTP) which traffic must match. If not specified, this field defaults to TCP. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/networking.k8s.io/v1/networkpolicies` -- `GET`: list or watch objects of kind NetworkPolicy -* `/apis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies` -- `DELETE`: delete collection of NetworkPolicy -- `GET`: list or watch objects of kind NetworkPolicy -- `POST`: create a NetworkPolicy -* `/apis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies/{name}` -- `DELETE`: delete a NetworkPolicy -- `GET`: read the specified NetworkPolicy -- `PATCH`: partially update the specified NetworkPolicy -- `PUT`: replace the specified NetworkPolicy - - -=== /apis/networking.k8s.io/v1/networkpolicies - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind NetworkPolicy - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#networkpolicylist-networking-k8s-io-v1[`NetworkPolicyList networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of NetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind NetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#networkpolicylist-networking-k8s-io-v1[`NetworkPolicyList networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a NetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| 201 - Created -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| 202 - Accepted -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the NetworkPolicy -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a NetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified NetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified NetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified NetworkPolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| 201 - Created -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`NetworkPolicy networking.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc b/rest_api/network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc deleted file mode 100644 index d6ea037414d4..000000000000 --- a/rest_api/network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc +++ /dev/null @@ -1,1009 +0,0 @@ -[id="podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1"] -= PodNetworkConnectivityCheck [controlplane.operator.openshift.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PodNetworkConnectivityCheck - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Spec defines the source and target of the connectivity check - -| `status` -| `object` -| Status contains the observed status of the connectivity check - -|=== -..spec -Description:: - Spec defines the source and target of the connectivity check - -Type:: - `object` - -Required:: - - `sourcePod` - - `targetEndpoint` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `sourcePod` -| `string` -| SourcePod names the pod from which the condition will be checked - -| `targetEndpoint` -| `string` -| EndpointAddress to check. A TCP address of the form host:port. Note that if host is a DNS name, then the check would fail if the DNS name cannot be resolved. Specify an IP address for host to bypass DNS name lookup. - -| `tlsClientCert` -| `object` -| TLSClientCert, if specified, references a kubernetes.io/tls type secret with 'tls.crt' and 'tls.key' entries containing an optional TLS client certificate and key to be used when checking endpoints that require a client certificate in order to gracefully preform the scan without causing excessive logging in the endpoint process. The secret must exist in the same namespace as this resource. - -|=== -..spec.tlsClientCert -Description:: - TLSClientCert, if specified, references a kubernetes.io/tls type secret with 'tls.crt' and 'tls.key' entries containing an optional TLS client certificate and key to be used when checking endpoints that require a client certificate in order to gracefully preform the scan without causing excessive logging in the endpoint process. The secret must exist in the same namespace as this resource. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..status -Description:: - Status contains the observed status of the connectivity check - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| Conditions summarize the status of the check - -| `conditions[]` -| `object` -| PodNetworkConnectivityCheckCondition represents the overall status of the pod network connectivity. - -| `failures` -| `array` -| Failures contains logs of unsuccessful check actions - -| `failures[]` -| `object` -| LogEntry records events - -| `outages` -| `array` -| Outages contains logs of time periods of outages - -| `outages[]` -| `object` -| OutageEntry records time period of an outage - -| `successes` -| `array` -| Successes contains logs successful check actions - -| `successes[]` -| `object` -| LogEntry records events - -|=== -..status.conditions -Description:: - Conditions summarize the status of the check - -Type:: - `array` - - - - -..status.conditions[] -Description:: - PodNetworkConnectivityCheckCondition represents the overall status of the pod network connectivity. - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `` -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| Message indicating details about last transition in a human readable format. - -| `reason` -| `string` -| Reason for the condition's last status transition in a machine readable format. - -| `status` -| `string` -| Status of the condition - -| `type` -| `string` -| Type of the condition - -|=== -..status.failures -Description:: - Failures contains logs of unsuccessful check actions - -Type:: - `array` - - - - -..status.failures[] -Description:: - LogEntry records events - -Type:: - `object` - -Required:: - - `success` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `latency` -| `` -| Latency records how long the action mentioned in the entry took. - -| `message` -| `string` -| Message explaining status in a human readable format. - -| `reason` -| `string` -| Reason for status in a machine readable format. - -| `success` -| `boolean` -| Success indicates if the log entry indicates a success or failure. - -| `time` -| `` -| Start time of check action. - -|=== -..status.outages -Description:: - Outages contains logs of time periods of outages - -Type:: - `array` - - - - -..status.outages[] -Description:: - OutageEntry records time period of an outage - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `end` -| `` -| End of outage detected - -| `endLogs` -| `array` -| EndLogs contains log entries related to the end of this outage. Should contain the success entry that resolved the outage and possibly a few of the failure log entries that preceded it. - -| `endLogs[]` -| `object` -| LogEntry records events - -| `message` -| `string` -| Message summarizes outage details in a human readable format. - -| `start` -| `` -| Start of outage detected - -| `startLogs` -| `array` -| StartLogs contains log entries related to the start of this outage. Should contain the original failure, any entries where the failure mode changed. - -| `startLogs[]` -| `object` -| LogEntry records events - -|=== -..status.outages[].endLogs -Description:: - EndLogs contains log entries related to the end of this outage. Should contain the success entry that resolved the outage and possibly a few of the failure log entries that preceded it. - -Type:: - `array` - - - - -..status.outages[].endLogs[] -Description:: - LogEntry records events - -Type:: - `object` - -Required:: - - `success` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `latency` -| `` -| Latency records how long the action mentioned in the entry took. - -| `message` -| `string` -| Message explaining status in a human readable format. - -| `reason` -| `string` -| Reason for status in a machine readable format. - -| `success` -| `boolean` -| Success indicates if the log entry indicates a success or failure. - -| `time` -| `` -| Start time of check action. - -|=== -..status.outages[].startLogs -Description:: - StartLogs contains log entries related to the start of this outage. Should contain the original failure, any entries where the failure mode changed. - -Type:: - `array` - - - - -..status.outages[].startLogs[] -Description:: - LogEntry records events - -Type:: - `object` - -Required:: - - `success` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `latency` -| `` -| Latency records how long the action mentioned in the entry took. - -| `message` -| `string` -| Message explaining status in a human readable format. - -| `reason` -| `string` -| Reason for status in a machine readable format. - -| `success` -| `boolean` -| Success indicates if the log entry indicates a success or failure. - -| `time` -| `` -| Start time of check action. - -|=== -..status.successes -Description:: - Successes contains logs successful check actions - -Type:: - `array` - - - - -..status.successes[] -Description:: - LogEntry records events - -Type:: - `object` - -Required:: - - `success` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `latency` -| `` -| Latency records how long the action mentioned in the entry took. - -| `message` -| `string` -| Message explaining status in a human readable format. - -| `reason` -| `string` -| Reason for status in a machine readable format. - -| `success` -| `boolean` -| Success indicates if the log entry indicates a success or failure. - -| `time` -| `` -| Start time of check action. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/controlplane.operator.openshift.io/v1alpha1/podnetworkconnectivitychecks` -- `GET`: list objects of kind PodNetworkConnectivityCheck -* `/apis/controlplane.operator.openshift.io/v1alpha1/namespaces/{namespace}/podnetworkconnectivitychecks` -- `DELETE`: delete collection of PodNetworkConnectivityCheck -- `GET`: list objects of kind PodNetworkConnectivityCheck -- `POST`: create a PodNetworkConnectivityCheck -* `/apis/controlplane.operator.openshift.io/v1alpha1/namespaces/{namespace}/podnetworkconnectivitychecks/{name}` -- `DELETE`: delete a PodNetworkConnectivityCheck -- `GET`: read the specified PodNetworkConnectivityCheck -- `PATCH`: partially update the specified PodNetworkConnectivityCheck -- `PUT`: replace the specified PodNetworkConnectivityCheck -* `/apis/controlplane.operator.openshift.io/v1alpha1/namespaces/{namespace}/podnetworkconnectivitychecks/{name}/status` -- `GET`: read status of the specified PodNetworkConnectivityCheck -- `PATCH`: partially update status of the specified PodNetworkConnectivityCheck -- `PUT`: replace status of the specified PodNetworkConnectivityCheck - - -=== /apis/controlplane.operator.openshift.io/v1alpha1/podnetworkconnectivitychecks - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind PodNetworkConnectivityCheck - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#podnetworkconnectivitychecklist-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheckList controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/controlplane.operator.openshift.io/v1alpha1/namespaces/{namespace}/podnetworkconnectivitychecks - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#podnetworkconnectivitychecklist-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheckList controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 201 - Created -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 202 - Accepted -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/controlplane.operator.openshift.io/v1alpha1/namespaces/{namespace}/podnetworkconnectivitychecks/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodNetworkConnectivityCheck -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 201 - Created -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/controlplane.operator.openshift.io/v1alpha1/namespaces/{namespace}/podnetworkconnectivitychecks/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodNetworkConnectivityCheck -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified PodNetworkConnectivityCheck - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 201 - Created -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/route-route-openshift-io-v1.adoc b/rest_api/network_apis/route-route-openshift-io-v1.adoc deleted file mode 100644 index 28e21b487239..000000000000 --- a/rest_api/network_apis/route-route-openshift-io-v1.adoc +++ /dev/null @@ -1,954 +0,0 @@ -[id="route-route-openshift-io-v1"] -= Route [route.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - A route allows developers to expose services through an HTTP(S) aware load balancing and proxy layer via a public DNS entry. The route may further specify TLS options and a certificate, or specify a public CNAME that the router should also accept for HTTP and HTTPS traffic. An administrator typically configures their router to be visible outside the cluster firewall, and may also add additional security, caching, or traffic controls on the service content. Routers usually talk directly to the service endpoints. - -Once a route is created, the `host` field may not be changed. Generally, routers use the oldest route with a given host when resolving conflicts. - -Routers are subject to additional customization and may support additional controls via the annotations field. - -Because administrators may configure multiple routers, the route status field is used to return information to clients about the names and states of the route under each router. If a client chooses a duplicate name, for instance, the route status conditions are used to indicate the route cannot be chosen. - -To enable HTTP/2 ALPN on a route it requires a custom (non-wildcard) certificate. This prevents connection coalescing by clients, notably web browsers. We do not support HTTP/2 ALPN on routes that use the default certificate because of the risk of connection re-use/coalescing. Routes that do not have their own custom certificate will not be HTTP/2 ALPN-enabled on either the frontend or the backend. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| RouteSpec describes the hostname or path the route exposes, any security information, and one to four backends (services) the route points to. Requests are distributed among the backends depending on the weights assigned to each backend. When using roundrobin scheduling the portion of requests that go to each backend is the backend weight divided by the sum of all of the backend weights. When the backend has more than one endpoint the requests that end up on the backend are roundrobin distributed among the endpoints. Weights are between 0 and 256 with default 100. Weight 0 causes no requests to the backend. If all weights are zero the route will be considered to have no backends and return a standard 503 response. - -The `tls` field is optional and allows specific certificates or behavior for the route. Routers typically configure a default certificate on a wildcard domain to terminate routes without explicit certificates, but custom hostnames usually must choose passthrough (send traffic directly to the backend via the TLS Server-Name- Indication field) or provide a certificate. - -| `status` -| `object` -| RouteStatus provides relevant info about the status of a route, including which routers acknowledge it. - -|=== -..spec -Description:: - RouteSpec describes the hostname or path the route exposes, any security information, and one to four backends (services) the route points to. Requests are distributed among the backends depending on the weights assigned to each backend. When using roundrobin scheduling the portion of requests that go to each backend is the backend weight divided by the sum of all of the backend weights. When the backend has more than one endpoint the requests that end up on the backend are roundrobin distributed among the endpoints. Weights are between 0 and 256 with default 100. Weight 0 causes no requests to the backend. If all weights are zero the route will be considered to have no backends and return a standard 503 response. - -The `tls` field is optional and allows specific certificates or behavior for the route. Routers typically configure a default certificate on a wildcard domain to terminate routes without explicit certificates, but custom hostnames usually must choose passthrough (send traffic directly to the backend via the TLS Server-Name- Indication field) or provide a certificate. - -Type:: - `object` - -Required:: - - `to` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `alternateBackends` -| `array` -| alternateBackends allows up to 3 additional backends to be assigned to the route. Only the Service kind is allowed, and it will be defaulted to Service. Use the weight field in RouteTargetReference object to specify relative preference. - -| `alternateBackends[]` -| `object` -| RouteTargetReference specifies the target that resolve into endpoints. Only the 'Service' kind is allowed. Use 'weight' field to emphasize one over others. - -| `host` -| `string` -| host is an alias/DNS that points to the service. Optional. If not specified a route name will typically be automatically chosen. Must follow DNS952 subdomain conventions. - -| `path` -| `string` -| path that the router watches for, to route traffic for to the service. Optional - -| `port` -| `object` -| RoutePort defines a port mapping from a router to an endpoint in the service endpoints. - -| `subdomain` -| `string` -| subdomain is a DNS subdomain that is requested within the ingress controller's domain (as a subdomain). If host is set this field is ignored. An ingress controller may choose to ignore this suggested name, in which case the controller will report the assigned name in the status.ingress array or refuse to admit the route. If this value is set and the server does not support this field host will be populated automatically. Otherwise host is left empty. The field may have multiple parts separated by a dot, but not all ingress controllers may honor the request. This field may not be changed after creation except by a user with the update routes/custom-host permission. - -Example: subdomain `frontend` automatically receives the router subdomain `apps.mycluster.com` to have a full hostname `frontend.apps.mycluster.com`. - -| `tls` -| `object` -| TLSConfig defines config used to secure a route and provide termination - -| `to` -| `object` -| RouteTargetReference specifies the target that resolve into endpoints. Only the 'Service' kind is allowed. Use 'weight' field to emphasize one over others. - -| `wildcardPolicy` -| `string` -| Wildcard policy if any for the route. Currently only 'Subdomain' or 'None' is allowed. - -|=== -..spec.alternateBackends -Description:: - alternateBackends allows up to 3 additional backends to be assigned to the route. Only the Service kind is allowed, and it will be defaulted to Service. Use the weight field in RouteTargetReference object to specify relative preference. - -Type:: - `array` - - - - -..spec.alternateBackends[] -Description:: - RouteTargetReference specifies the target that resolve into endpoints. Only the 'Service' kind is allowed. Use 'weight' field to emphasize one over others. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| The kind of target that the route is referring to. Currently, only 'Service' is allowed - -| `name` -| `string` -| name of the service/target that is being referred to. e.g. name of the service - -| `weight` -| `integer` -| weight as an integer between 0 and 256, default 100, that specifies the target's relative weight against other target reference objects. 0 suppresses requests to this backend. - -|=== -..spec.port -Description:: - RoutePort defines a port mapping from a router to an endpoint in the service endpoints. - -Type:: - `object` - -Required:: - - `targetPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `targetPort` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| The target port on pods selected by the service this route points to. If this is a string, it will be looked up as a named port in the target endpoints port list. Required - -|=== -..spec.tls -Description:: - TLSConfig defines config used to secure a route and provide termination - -Type:: - `object` - -Required:: - - `termination` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `caCertificate` -| `string` -| caCertificate provides the cert authority certificate contents - -| `certificate` -| `string` -| certificate provides certificate contents - -| `destinationCACertificate` -| `string` -| destinationCACertificate provides the contents of the ca certificate of the final destination. When using reencrypt termination this file should be provided in order to have routers use it for health checks on the secure connection. If this field is not specified, the router may provide its own destination CA and perform hostname validation using the short service name (service.namespace.svc), which allows infrastructure generated certificates to automatically verify. - -| `insecureEdgeTerminationPolicy` -| `string` -| insecureEdgeTerminationPolicy indicates the desired behavior for insecure connections to a route. While each router may make its own decisions on which ports to expose, this is normally port 80. - -* Allow - traffic is sent to the server on the insecure port (default) * Disable - no traffic is allowed on the insecure port. * Redirect - clients are redirected to the secure port. - -| `key` -| `string` -| key provides key file contents - -| `termination` -| `string` -| termination indicates termination type. - -* edge - TLS termination is done by the router and http is used to communicate with the backend (default) * passthrough - Traffic is sent straight to the destination without the router providing TLS termination * reencrypt - TLS termination is done by the router and https is used to communicate with the backend - -|=== -..spec.to -Description:: - RouteTargetReference specifies the target that resolve into endpoints. Only the 'Service' kind is allowed. Use 'weight' field to emphasize one over others. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| The kind of target that the route is referring to. Currently, only 'Service' is allowed - -| `name` -| `string` -| name of the service/target that is being referred to. e.g. name of the service - -| `weight` -| `integer` -| weight as an integer between 0 and 256, default 100, that specifies the target's relative weight against other target reference objects. 0 suppresses requests to this backend. - -|=== -..status -Description:: - RouteStatus provides relevant info about the status of a route, including which routers acknowledge it. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ingress` -| `array` -| ingress describes the places where the route may be exposed. The list of ingress points may contain duplicate Host or RouterName values. Routes are considered live once they are `Ready` - -| `ingress[]` -| `object` -| RouteIngress holds information about the places where a route is exposed. - -|=== -..status.ingress -Description:: - ingress describes the places where the route may be exposed. The list of ingress points may contain duplicate Host or RouterName values. Routes are considered live once they are `Ready` - -Type:: - `array` - - - - -..status.ingress[] -Description:: - RouteIngress holds information about the places where a route is exposed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| Conditions is the state of the route, may be empty. - -| `conditions[]` -| `object` -| RouteIngressCondition contains details for the current condition of this route on a particular router. - -| `host` -| `string` -| Host is the host string under which the route is exposed; this value is required - -| `routerCanonicalHostname` -| `string` -| CanonicalHostname is the external host name for the router that can be used as a CNAME for the host requested for this route. This value is optional and may not be set in all cases. - -| `routerName` -| `string` -| Name is a name chosen by the router to identify itself; this value is required - -| `wildcardPolicy` -| `string` -| Wildcard policy is the wildcard policy that was allowed where this route is exposed. - -|=== -..status.ingress[].conditions -Description:: - Conditions is the state of the route, may be empty. - -Type:: - `array` - - - - -..status.ingress[].conditions[] -Description:: - RouteIngressCondition contains details for the current condition of this route on a particular router. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| RFC 3339 date and time when this condition last transitioned - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition, and is usually a machine and human readable constant - -| `status` -| `string` -| Status is the status of the condition. Can be True, False, Unknown. - -| `type` -| `string` -| Type is the type of the condition. Currently only Ready. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/route.openshift.io/v1/routes` -- `GET`: list or watch objects of kind Route -* `/apis/route.openshift.io/v1/namespaces/{namespace}/routes` -- `DELETE`: delete collection of Route -- `GET`: list or watch objects of kind Route -- `POST`: create a Route -* `/apis/route.openshift.io/v1/namespaces/{namespace}/routes/{name}` -- `DELETE`: delete a Route -- `GET`: read the specified Route -- `PATCH`: partially update the specified Route -- `PUT`: replace the specified Route -* `/apis/route.openshift.io/v1/namespaces/{namespace}/routes/{name}/status` -- `GET`: read status of the specified Route -- `PATCH`: partially update status of the specified Route -- `PUT`: replace status of the specified Route - - -=== /apis/route.openshift.io/v1/routes - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Route - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#routelist-route-openshift-io-v1[`RouteList route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/route.openshift.io/v1/namespaces/{namespace}/routes - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#routelist-route-openshift-io-v1[`RouteList route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 202 - Accepted -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/route.openshift.io/v1/namespaces/{namespace}/routes/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Route -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/route.openshift.io/v1/namespaces/{namespace}/routes/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Route -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Route - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Route - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 201 - Created -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`Route route.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/network_apis/service-core-v1.adoc b/rest_api/network_apis/service-core-v1.adoc deleted file mode 100644 index ff30af233e49..000000000000 --- a/rest_api/network_apis/service-core-v1.adoc +++ /dev/null @@ -1,993 +0,0 @@ -[id="service-core-v1"] -= Service [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Service is a named abstraction of software service (for example, mysql) consisting of local port (for example 3306) that the proxy listens on, and the selector that determines which pods will answer requests sent through the proxy. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ServiceSpec describes the attributes that a user creates on a service. - -| `status` -| `object` -| ServiceStatus represents the current status of a service. - -|=== -..spec -Description:: - ServiceSpec describes the attributes that a user creates on a service. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allocateLoadBalancerNodePorts` -| `boolean` -| allocateLoadBalancerNodePorts defines if NodePorts will be automatically allocated for services with type LoadBalancer. Default is "true". It may be set to "false" if the cluster load-balancer does not rely on NodePorts. allocateLoadBalancerNodePorts may only be set for services with type LoadBalancer and will be cleared if the type is changed to any other type. This field is alpha-level and is only honored by servers that enable the ServiceLBNodePortControl feature. - -| `clusterIP` -| `string` -| clusterIP is the IP address of the service and is usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be blank) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are "None", empty string (""), or a valid IP address. Setting this to "None" makes a "headless service" (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies - -| `clusterIPs` -| `array (string)` -| ClusterIPs is a list of IP addresses assigned to this service, and are usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be empty) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are "None", empty string (""), or a valid IP address. Setting this to "None" makes a "headless service" (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. If this field is not specified, it will be initialized from the clusterIP field. If this field is specified, clients must ensure that clusterIPs[0] and clusterIP have the same value. - -Unless the "IPv6DualStack" feature gate is enabled, this field is limited to one value, which must be the same as the clusterIP field. If the feature gate is enabled, this field may hold a maximum of two entries (dual-stack IPs, in either order). These IPs must correspond to the values of the ipFamilies field. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies - -| `externalIPs` -| `array (string)` -| externalIPs is a list of IP addresses for which nodes in the cluster will also accept traffic for this service. These IPs are not managed by Kubernetes. The user is responsible for ensuring that traffic arrives at a node with this IP. A common example is external load-balancers that are not part of the Kubernetes system. - -| `externalName` -| `string` -| externalName is the external reference that discovery mechanisms will return as an alias for this service (e.g. a DNS CNAME record). No proxying will be involved. Must be a lowercase RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires Type to be - -| `externalTrafficPolicy` -| `string` -| externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. "Local" preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. "Cluster" obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading. - -| `healthCheckNodePort` -| `integer` -| healthCheckNodePort specifies the healthcheck nodePort for the service. This only applies when type is set to LoadBalancer and externalTrafficPolicy is set to Local. If a value is specified, is in-range, and is not in use, it will be used. If not specified, a value will be automatically allocated. External systems (e.g. load-balancers) can use this port to determine if a given node holds endpoints for this service or not. If this field is specified when creating a Service which does not need it, creation will fail. This field will be wiped when updating a Service to no longer need it (e.g. changing type). - -| `ipFamilies` -| `array (string)` -| IPFamilies is a list of IP families (e.g. IPv4, IPv6) assigned to this service, and is gated by the "IPv6DualStack" feature gate. This field is usually assigned automatically based on cluster configuration and the ipFamilyPolicy field. If this field is specified manually, the requested family is available in the cluster, and ipFamilyPolicy allows it, it will be used; otherwise creation of the service will fail. This field is conditionally mutable: it allows for adding or removing a secondary IP family, but it does not allow changing the primary IP family of the Service. Valid values are "IPv4" and "IPv6". This field only applies to Services of types ClusterIP, NodePort, and LoadBalancer, and does apply to "headless" services. This field will be wiped when updating a Service to type ExternalName. - -This field may hold a maximum of two entries (dual-stack families, in either order). These families must correspond to the values of the clusterIPs field, if specified. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. - -| `ipFamilyPolicy` -| `string` -| IPFamilyPolicy represents the dual-stack-ness requested or required by this Service, and is gated by the "IPv6DualStack" feature gate. If there is no value provided, then this field will be set to SingleStack. Services can be "SingleStack" (a single IP family), "PreferDualStack" (two IP families on dual-stack configured clusters or a single IP family on single-stack clusters), or "RequireDualStack" (two IP families on dual-stack configured clusters, otherwise fail). The ipFamilies and clusterIPs fields depend on the value of this field. This field will be wiped when updating a service to type ExternalName. - -| `loadBalancerIP` -| `string` -| Only applies to Service Type: LoadBalancer LoadBalancer will get created with the IP specified in this field. This feature depends on whether the underlying cloud-provider supports specifying the loadBalancerIP when a load balancer is created. This field will be ignored if the cloud-provider does not support the feature. - -| `loadBalancerSourceRanges` -| `array (string)` -| If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature." More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/ - -| `ports` -| xref:../objects/index.adoc#serviceport-core-v1[`array (ServicePort core/v1)`] -| The list of ports that are exposed by this service. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies - -| `publishNotReadyAddresses` -| `boolean` -| publishNotReadyAddresses indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready. The primary use case for setting this field is for a StatefulSet's Headless Service to propagate SRV DNS records for its Pods for the purpose of peer discovery. The Kubernetes controllers that generate Endpoints and EndpointSlice resources for Services interpret this to mean that all endpoints are considered "ready" even if the Pods themselves are not. Agents which consume only Kubernetes generated endpoints through the Endpoints or EndpointSlice resources can safely assume this behavior. - -| `selector` -| `object (string)` -| Route service traffic to pods with label keys and values matching this selector. If empty or not present, the service is assumed to have an external process managing its endpoints, which Kubernetes will not modify. Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/ - -| `sessionAffinity` -| `string` -| Supports "ClientIP" and "None". Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies - -| `sessionAffinityConfig` -| xref:../objects/index.adoc#sessionaffinityconfig-core-v1[`SessionAffinityConfig core/v1`] -| sessionAffinityConfig contains the configurations of session affinity. - -| `topologyKeys` -| `array (string)` -| topologyKeys is a preference-order list of topology keys which implementations of services should use to preferentially sort endpoints when accessing this Service, it can not be used at the same time as externalTrafficPolicy=Local. Topology keys must be valid label keys and at most 16 keys may be specified. Endpoints are chosen based on the first topology key with available backends. If this field is specified and all entries have no backends that match the topology of the client, the service has no backends for that client and connections should fail. The special value "*" may be used to mean "any topology". This catch-all value, if used, only makes sense as the last value in the list. If this is not specified or empty, no topology constraints will be applied. This field is alpha-level and is only honored by servers that enable the ServiceTopology feature. - -| `type` -| `string` -| type determines how the Service is exposed. Defaults to ClusterIP. Valid options are ExternalName, ClusterIP, NodePort, and LoadBalancer. "ClusterIP" allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, by manual construction of an Endpoints object or EndpointSlice objects. If clusterIP is "None", no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a virtual IP. "NodePort" builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP. "LoadBalancer" builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP. "ExternalName" aliases this service to the specified externalName. Several other fields do not apply to ExternalName services. More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types - -|=== -..status -Description:: - ServiceStatus represents the current status of a service. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| xref:../objects/index.adoc#condition-meta-v1[`array (Condition meta/v1)`] -| Current service state - -| `loadBalancer` -| `object` -| LoadBalancerStatus represents the status of a load-balancer. - -|=== -..status.loadBalancer -Description:: - LoadBalancerStatus represents the status of a load-balancer. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ingress` -| xref:../objects/index.adoc#loadbalanceringress-core-v1[`array (LoadBalancerIngress core/v1)`] -| Ingress is a list containing ingress points for the load-balancer. Traffic intended for the service should be sent to these ingress points. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/services` -- `GET`: list or watch objects of kind Service -* `/api/v1/namespaces/{namespace}/services` -- `GET`: list or watch objects of kind Service -- `POST`: create a Service -* `/api/v1/namespaces/{namespace}/services/{name}` -- `DELETE`: delete a Service -- `GET`: read the specified Service -- `PATCH`: partially update the specified Service -- `PUT`: replace the specified Service -* `/api/v1/namespaces/{namespace}/services/{name}/proxy` -- `DELETE`: connect DELETE requests to proxy of Service -- `GET`: connect GET requests to proxy of Service -- `HEAD`: connect HEAD requests to proxy of Service -- `OPTIONS`: connect OPTIONS requests to proxy of Service -- `PATCH`: connect PATCH requests to proxy of Service -- `POST`: connect POST requests to proxy of Service -- `PUT`: connect PUT requests to proxy of Service -* `/api/v1/namespaces/{namespace}/services/{name}/status` -- `GET`: read status of the specified Service -- `PATCH`: partially update status of the specified Service -- `PUT`: replace status of the specified Service -* `/api/v1/namespaces/{namespace}/services/{name}/proxy/{path}` -- `DELETE`: connect DELETE requests to proxy of Service -- `GET`: connect GET requests to proxy of Service -- `HEAD`: connect HEAD requests to proxy of Service -- `OPTIONS`: connect OPTIONS requests to proxy of Service -- `PATCH`: connect PATCH requests to proxy of Service -- `POST`: connect POST requests to proxy of Service -- `PUT`: connect PUT requests to proxy of Service - - -=== /api/v1/services - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#servicelist-core-v1[`ServiceList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/services - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Service - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#servicelist-core-v1[`ServiceList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Service - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 201 - Created -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 202 - Accepted -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/services/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Service -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Service - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Service - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Service - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Service - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 201 - Created -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/services/{name}/proxy - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ServiceProxyOptions -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `path` -| `string` -| Path is the part of URLs that include service endpoints, suffixes, and parameters to use for the current proxy request to service. For example, the whole request URL is http://localhost/api/v1/namespaces/kube-system/services/elasticsearch-logging/_search?q&#x3D;user:kimchy. Path is _search?q&#x3D;user:kimchy. -|=== - -HTTP method:: - `DELETE` - -Description:: - connect DELETE requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `HEAD` - -Description:: - connect HEAD requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `OPTIONS` - -Description:: - connect OPTIONS requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - connect PATCH requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - connect PUT requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/services/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Service -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Service - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Service - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 201 - Created -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`Service core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/services/{name}/proxy/{path} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ServiceProxyOptions -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -| `path` -| `string` -| path to the resource -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `path` -| `string` -| Path is the part of URLs that include service endpoints, suffixes, and parameters to use for the current proxy request to service. For example, the whole request URL is http://localhost/api/v1/namespaces/kube-system/services/elasticsearch-logging/_search?q&#x3D;user:kimchy. Path is _search?q&#x3D;user:kimchy. -|=== - -HTTP method:: - `DELETE` - -Description:: - connect DELETE requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `HEAD` - -Description:: - connect HEAD requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `OPTIONS` - -Description:: - connect OPTIONS requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - connect PATCH requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - connect PUT requests to proxy of Service - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/node_apis/node-apis-index.adoc b/rest_api/node_apis/node-apis-index.adoc deleted file mode 100644 index 8ce69b7c6fe1..000000000000 --- a/rest_api/node_apis/node-apis-index.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="node-apis"] -= Node APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== Node [core/v1] - -Description:: - Node is a worker node in Kubernetes. Each node will have a unique identifier in the cache (i.e. in etcd). - -Type:: - `object` - -== Profile [tuned.openshift.io/v1] - -Description:: - Profile is a specification for a Profile resource - -Type:: - `object` - -== RuntimeClass [node.k8s.io/v1] - -Description:: - RuntimeClass defines a class of container runtime supported in the cluster. The RuntimeClass is used to determine which container runtime is used to run all containers in a pod. RuntimeClasses are manually defined by a user or cluster provisioner, and referenced in the PodSpec. The Kubelet is responsible for resolving the RuntimeClassName reference before running the pod. For more details, see https://kubernetes.io/docs/concepts/containers/runtime-class/ - -Type:: - `object` - -== Tuned [tuned.openshift.io/v1] - -Description:: - Tuned is a collection of rules that allows cluster-wide deployment of node-level sysctls and more flexibility to add custom tuning specified by user needs. These rules are translated and passed to all containerized Tuned daemons running in the cluster in the format that the daemons understand. The responsibility for applying the node-level tuning then lies with the containerized Tuned daemons. More info: https://github.com/openshift/cluster-node-tuning-operator - -Type:: - `object` - diff --git a/rest_api/node_apis/node-core-v1.adoc b/rest_api/node_apis/node-core-v1.adoc deleted file mode 100644 index 5ba087d656f6..000000000000 --- a/rest_api/node_apis/node-core-v1.adoc +++ /dev/null @@ -1,980 +0,0 @@ -[id="node-core-v1"] -= Node [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Node is a worker node in Kubernetes. Each node will have a unique identifier in the cache (i.e. in etcd). - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| NodeSpec describes the attributes that a node is created with. - -| `status` -| `object` -| NodeStatus is information about the current status of a node. - -|=== -..spec -Description:: - NodeSpec describes the attributes that a node is created with. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configSource` -| xref:../objects/index.adoc#nodeconfigsource-core-v1[`NodeConfigSource core/v1`] -| If specified, the source to get node configuration from The DynamicKubeletConfig feature gate must be enabled for the Kubelet to use this field - -| `externalID` -| `string` -| Deprecated. Not all kubelets will set this field. Remove field after 1.13. see: https://issues.k8s.io/61966 - -| `podCIDR` -| `string` -| PodCIDR represents the pod IP range assigned to the node. - -| `podCIDRs` -| `array (string)` -| podCIDRs represents the IP ranges assigned to the node for usage by Pods on that node. If this field is specified, the 0th entry must match the podCIDR field. It may contain at most 1 value for each of IPv4 and IPv6. - -| `providerID` -| `string` -| ID of the node assigned by the cloud provider in the format: <ProviderName>://<ProviderSpecificNodeID> - -| `taints` -| xref:../objects/index.adoc#taint-core-v1[`array (Taint core/v1)`] -| If specified, the node's taints. - -| `unschedulable` -| `boolean` -| Unschedulable controls node schedulability of new pods. By default, node is schedulable. More info: https://kubernetes.io/docs/concepts/nodes/node/#manual-node-administration - -|=== -..status -Description:: - NodeStatus is information about the current status of a node. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `addresses` -| xref:../objects/index.adoc#nodeaddress-core-v1[`array (NodeAddress core/v1)`] -| List of addresses reachable to the node. Queried from cloud provider, if available. More info: https://kubernetes.io/docs/concepts/nodes/node/#addresses Note: This field is declared as mergeable, but the merge key is not sufficiently unique, which can cause data corruption when it is merged. Callers should instead use a full-replacement patch. See http://pr.k8s.io/79391 for an example. - -| `allocatable` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Allocatable represents the resources of a node that are available for scheduling. Defaults to Capacity. - -| `capacity` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Capacity represents the total resources of a node. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#capacity - -| `conditions` -| xref:../objects/index.adoc#nodecondition-core-v1[`array (NodeCondition core/v1)`] -| Conditions is an array of current observed node conditions. More info: https://kubernetes.io/docs/concepts/nodes/node/#condition - -| `config` -| `object` -| NodeConfigStatus describes the status of the config assigned by Node.Spec.ConfigSource. - -| `daemonEndpoints` -| xref:../objects/index.adoc#nodedaemonendpoints-core-v1[`NodeDaemonEndpoints core/v1`] -| Endpoints of daemons running on the Node. - -| `images` -| xref:../objects/index.adoc#containerimage-core-v1[`array (ContainerImage core/v1)`] -| List of container images on this node - -| `nodeInfo` -| xref:../objects/index.adoc#nodesysteminfo-core-v1[`NodeSystemInfo core/v1`] -| Set of ids/uuids to uniquely identify the node. More info: https://kubernetes.io/docs/concepts/nodes/node/#info - -| `phase` -| `string` -| NodePhase is the recently observed lifecycle phase of the node. More info: https://kubernetes.io/docs/concepts/nodes/node/#phase The field is never populated, and now is deprecated. - -| `volumesAttached` -| xref:../objects/index.adoc#attachedvolume-core-v1[`array (AttachedVolume core/v1)`] -| List of volumes that are attached to the node. - -| `volumesInUse` -| `array (string)` -| List of attachable volumes in use (mounted) by the node. - -|=== -..status.config -Description:: - NodeConfigStatus describes the status of the config assigned by Node.Spec.ConfigSource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `active` -| xref:../objects/index.adoc#nodeconfigsource-core-v1[`NodeConfigSource core/v1`] -| Active reports the checkpointed config the node is actively using. Active will represent either the current version of the Assigned config, or the current LastKnownGood config, depending on whether attempting to use the Assigned config results in an error. - -| `assigned` -| xref:../objects/index.adoc#nodeconfigsource-core-v1[`NodeConfigSource core/v1`] -| Assigned reports the checkpointed config the node will try to use. When Node.Spec.ConfigSource is updated, the node checkpoints the associated config payload to local disk, along with a record indicating intended config. The node refers to this record to choose its config checkpoint, and reports this record in Assigned. Assigned only updates in the status after the record has been checkpointed to disk. When the Kubelet is restarted, it tries to make the Assigned config the Active config by loading and validating the checkpointed payload identified by Assigned. - -| `error` -| `string` -| Error describes any problems reconciling the Spec.ConfigSource to the Active config. Errors may occur, for example, attempting to checkpoint Spec.ConfigSource to the local Assigned record, attempting to checkpoint the payload associated with Spec.ConfigSource, attempting to load or validate the Assigned config, etc. Errors may occur at different points while syncing config. Earlier errors (e.g. download or checkpointing errors) will not result in a rollback to LastKnownGood, and may resolve across Kubelet retries. Later errors (e.g. loading or validating a checkpointed config) will result in a rollback to LastKnownGood. In the latter case, it is usually possible to resolve the error by fixing the config assigned in Spec.ConfigSource. You can find additional information for debugging by searching the error message in the Kubelet log. Error is a human-readable description of the error state; machines can check whether or not Error is empty, but should not rely on the stability of the Error text across Kubelet versions. - -| `lastKnownGood` -| xref:../objects/index.adoc#nodeconfigsource-core-v1[`NodeConfigSource core/v1`] -| LastKnownGood reports the checkpointed config the node will fall back to when it encounters an error attempting to use the Assigned config. The Assigned config becomes the LastKnownGood config when the node determines that the Assigned config is stable and correct. This is currently implemented as a 10-minute soak period starting when the local record of Assigned config is updated. If the Assigned config is Active at the end of this period, it becomes the LastKnownGood. Note that if Spec.ConfigSource is reset to nil (use local defaults), the LastKnownGood is also immediately reset to nil, because the local default config is always assumed good. You should not make assumptions about the node's method of determining config stability and correctness, as this may change or become configurable in the future. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/nodes` -- `DELETE`: delete collection of Node -- `GET`: list or watch objects of kind Node -- `POST`: create a Node -* `/api/v1/nodes/{name}` -- `DELETE`: delete a Node -- `GET`: read the specified Node -- `PATCH`: partially update the specified Node -- `PUT`: replace the specified Node -* `/api/v1/nodes/{name}/proxy` -- `DELETE`: connect DELETE requests to proxy of Node -- `GET`: connect GET requests to proxy of Node -- `HEAD`: connect HEAD requests to proxy of Node -- `OPTIONS`: connect OPTIONS requests to proxy of Node -- `PATCH`: connect PATCH requests to proxy of Node -- `POST`: connect POST requests to proxy of Node -- `PUT`: connect PUT requests to proxy of Node -* `/api/v1/nodes/{name}/status` -- `GET`: read status of the specified Node -- `PATCH`: partially update status of the specified Node -- `PUT`: replace status of the specified Node -* `/api/v1/nodes/{name}/proxy/{path}` -- `DELETE`: connect DELETE requests to proxy of Node -- `GET`: connect GET requests to proxy of Node -- `HEAD`: connect HEAD requests to proxy of Node -- `OPTIONS`: connect OPTIONS requests to proxy of Node -- `PATCH`: connect PATCH requests to proxy of Node -- `POST`: connect POST requests to proxy of Node -- `PUT`: connect PUT requests to proxy of Node - - -=== /api/v1/nodes - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#nodelist-core-v1[`NodeList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 201 - Created -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 202 - Accepted -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/nodes/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Node -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 201 - Created -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/nodes/{name}/proxy - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the NodeProxyOptions -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `path` -| `string` -| Path is the URL path to use for the current proxy request to node. -|=== - -HTTP method:: - `DELETE` - -Description:: - connect DELETE requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `HEAD` - -Description:: - connect HEAD requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `OPTIONS` - -Description:: - connect OPTIONS requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - connect PATCH requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - connect PUT requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/nodes/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Node -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Node - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 201 - Created -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`Node core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/nodes/{name}/proxy/{path} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the NodeProxyOptions -| `path` -| `string` -| path to the resource -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `path` -| `string` -| Path is the URL path to use for the current proxy request to node. -|=== - -HTTP method:: - `DELETE` - -Description:: - connect DELETE requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `HEAD` - -Description:: - connect HEAD requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `OPTIONS` - -Description:: - connect OPTIONS requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - connect PATCH requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - connect PUT requests to proxy of Node - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/node_apis/profile-tuned-openshift-io-v1.adoc b/rest_api/node_apis/profile-tuned-openshift-io-v1.adoc deleted file mode 100644 index c5af55a179dc..000000000000 --- a/rest_api/node_apis/profile-tuned-openshift-io-v1.adoc +++ /dev/null @@ -1,554 +0,0 @@ -[id="profile-tuned-openshift-io-v1"] -= Profile [tuned.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Profile is a specification for a Profile resource - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| - -| `status` -| `object` -| ProfileStatus is the status for a Profile resource; the status is for internal use only and its fields may be changed/removed in the future. - -|=== -..spec -Description:: - - -Type:: - `object` - -Required:: - - `config` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `config` -| `object` -| - -|=== -..spec.config -Description:: - - -Type:: - `object` - -Required:: - - `tunedProfile` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `debug` -| `boolean` -| option to debug Tuned daemon execution - -| `tunedProfile` -| `string` -| Tuned profile to apply - -|=== -..status -Description:: - ProfileStatus is the status for a Profile resource; the status is for internal use only and its fields may be changed/removed in the future. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bootcmdline` -| `string` -| kernel parameters calculated by tuned for the active Tuned profile - -| `stalld` -| `boolean` -| deploy stall daemon: https://github.com/bristot/stalld/ - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/tuned.openshift.io/v1/profiles` -- `GET`: list objects of kind Profile -* `/apis/tuned.openshift.io/v1/namespaces/{namespace}/profiles` -- `DELETE`: delete collection of Profile -- `GET`: list objects of kind Profile -- `POST`: create a Profile -* `/apis/tuned.openshift.io/v1/namespaces/{namespace}/profiles/{name}` -- `DELETE`: delete a Profile -- `GET`: read the specified Profile -- `PATCH`: partially update the specified Profile -- `PUT`: replace the specified Profile - - -=== /apis/tuned.openshift.io/v1/profiles - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Profile - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#profilelist-tuned-openshift-io-v1[`ProfileList tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/tuned.openshift.io/v1/namespaces/{namespace}/profiles - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Profile - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Profile - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#profilelist-tuned-openshift-io-v1[`ProfileList tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Profile - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| 201 - Created -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| 202 - Accepted -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/tuned.openshift.io/v1/namespaces/{namespace}/profiles/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Profile -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Profile - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Profile - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Profile - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Profile - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| 201 - Created -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`Profile tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/node_apis/runtimeclass-node-k8s-io-v1.adoc b/rest_api/node_apis/runtimeclass-node-k8s-io-v1.adoc deleted file mode 100644 index ae7a6fc5689c..000000000000 --- a/rest_api/node_apis/runtimeclass-node-k8s-io-v1.adoc +++ /dev/null @@ -1,473 +0,0 @@ -[id="runtimeclass-node-k8s-io-v1"] -= RuntimeClass [node.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - RuntimeClass defines a class of container runtime supported in the cluster. The RuntimeClass is used to determine which container runtime is used to run all containers in a pod. RuntimeClasses are manually defined by a user or cluster provisioner, and referenced in the PodSpec. The Kubelet is responsible for resolving the RuntimeClassName reference before running the pod. For more details, see https://kubernetes.io/docs/concepts/containers/runtime-class/ - -Type:: - `object` - -Required:: - - `handler` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `handler` -| `string` -| Handler specifies the underlying runtime and configuration that the CRI implementation will use to handle pods of this class. The possible values are specific to the node & CRI configuration. It is assumed that all handlers are available on every node, and handlers of the same name are equivalent on every node. For example, a handler called "runc" might specify that the runc OCI runtime (using native Linux containers) will be used to run the containers in a pod. The Handler must be lowercase, conform to the DNS Label (RFC 1123) requirements, and is immutable. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `overhead` -| `object` -| Overhead structure represents the resource overhead associated with running a pod. - -| `scheduling` -| `object` -| Scheduling specifies the scheduling constraints for nodes supporting a RuntimeClass. - -|=== -..overhead -Description:: - Overhead structure represents the resource overhead associated with running a pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podFixed` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| PodFixed represents the fixed resource overhead associated with running a pod. - -|=== -..scheduling -Description:: - Scheduling specifies the scheduling constraints for nodes supporting a RuntimeClass. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelector` -| `object (string)` -| nodeSelector lists labels that must be present on nodes that support this RuntimeClass. Pods using this RuntimeClass can only be scheduled to a node matched by this selector. The RuntimeClass nodeSelector is merged with a pod's existing nodeSelector. Any conflicts will cause the pod to be rejected in admission. - -| `tolerations` -| xref:../objects/index.adoc#toleration-core-v1[`array (Toleration core/v1)`] -| tolerations are appended (excluding duplicates) to pods running with this RuntimeClass during admission, effectively unioning the set of nodes tolerated by the pod and the RuntimeClass. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/node.k8s.io/v1/runtimeclasses` -- `DELETE`: delete collection of RuntimeClass -- `GET`: list or watch objects of kind RuntimeClass -- `POST`: create a RuntimeClass -* `/apis/node.k8s.io/v1/runtimeclasses/{name}` -- `DELETE`: delete a RuntimeClass -- `GET`: read the specified RuntimeClass -- `PATCH`: partially update the specified RuntimeClass -- `PUT`: replace the specified RuntimeClass - - -=== /apis/node.k8s.io/v1/runtimeclasses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of RuntimeClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind RuntimeClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#runtimeclasslist-node-k8s-io-v1[`RuntimeClassList node.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a RuntimeClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| 201 - Created -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| 202 - Accepted -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/node.k8s.io/v1/runtimeclasses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the RuntimeClass -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a RuntimeClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified RuntimeClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified RuntimeClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified RuntimeClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| 201 - Created -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`RuntimeClass node.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/node_apis/tuned-tuned-openshift-io-v1.adoc b/rest_api/node_apis/tuned-tuned-openshift-io-v1.adoc deleted file mode 100644 index f5220d1050ad..000000000000 --- a/rest_api/node_apis/tuned-tuned-openshift-io-v1.adoc +++ /dev/null @@ -1,685 +0,0 @@ -[id="tuned-tuned-openshift-io-v1"] -= Tuned [tuned.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Tuned is a collection of rules that allows cluster-wide deployment of node-level sysctls and more flexibility to add custom tuning specified by user needs. These rules are translated and passed to all containerized Tuned daemons running in the cluster in the format that the daemons understand. The responsibility for applying the node-level tuning then lies with the containerized Tuned daemons. More info: https://github.com/openshift/cluster-node-tuning-operator - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of Tuned. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status - -| `status` -| `object` -| TunedStatus is the status for a Tuned resource - -|=== -..spec -Description:: - spec is the specification of the desired behavior of Tuned. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status - -Type:: - `object` - -Required:: - - `profile` - - `recommend` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `managementState` -| `string` -| managementState indicates whether the registry instance represented by this config instance is under operator management or not. Valid values are Force, Managed, Unmanaged, and Removed. - -| `profile` -| `array` -| Tuned profiles. - -| `profile[]` -| `object` -| A Tuned profile. - -| `recommend` -| `array` -| Selection logic for all Tuned profiles. - -| `recommend[]` -| `object` -| Selection logic for a single Tuned profile. - -|=== -..spec.profile -Description:: - Tuned profiles. - -Type:: - `array` - - - - -..spec.profile[] -Description:: - A Tuned profile. - -Type:: - `object` - -Required:: - - `data` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `data` -| `string` -| Specification of the Tuned profile to be consumed by the Tuned daemon. - -| `name` -| `string` -| Name of the Tuned profile to be used in the recommend section. - -|=== -..spec.recommend -Description:: - Selection logic for all Tuned profiles. - -Type:: - `array` - - - - -..spec.recommend[] -Description:: - Selection logic for a single Tuned profile. - -Type:: - `object` - -Required:: - - `priority` - - `profile` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `machineConfigLabels` -| `object (string)` -| MachineConfigLabels specifies the labels for a MachineConfig. The MachineConfig is created automatically to apply additional host settings (e.g. kernel boot parameters) profile 'Profile' needs and can only be applied by creating a MachineConfig. This involves finding all MachineConfigPools with machineConfigSelector matching the MachineConfigLabels and setting the profile 'Profile' on all nodes that match the MachineConfigPools' nodeSelectors. - -| `match` -| `array` -| Rules governing application of a Tuned profile connected by logical OR operator. - -| `match[]` -| `object` -| Rules governing application of a Tuned profile. - -| `operand` -| `object` -| Optional operand configuration. - -| `priority` -| `integer` -| Tuned profile priority. Highest priority is 0. - -| `profile` -| `string` -| Name of the Tuned profile to recommend. - -|=== -..spec.recommend[].match -Description:: - Rules governing application of a Tuned profile connected by logical OR operator. - -Type:: - `array` - - - - -..spec.recommend[].match[] -Description:: - Rules governing application of a Tuned profile. - -Type:: - `object` - -Required:: - - `label` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `label` -| `string` -| Node or Pod label name. - -| `match` -| `array (undefined)` -| Additional rules governing application of the tuned profile connected by logical AND operator. - -| `type` -| `string` -| Match type: [node/pod]. If omitted, "node" is assumed. - -| `value` -| `string` -| Node or Pod label value. If omitted, the presence of label name is enough to match. - -|=== -..spec.recommend[].operand -Description:: - Optional operand configuration. - -Type:: - `object` - -Required:: - - `debug` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `debug` -| `boolean` -| turn debugging on/off for the Tuned daemon: true/false (default is false) - -|=== -..status -Description:: - TunedStatus is the status for a Tuned resource - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/tuned.openshift.io/v1/tuneds` -- `GET`: list objects of kind Tuned -* `/apis/tuned.openshift.io/v1/namespaces/{namespace}/tuneds` -- `DELETE`: delete collection of Tuned -- `GET`: list objects of kind Tuned -- `POST`: create a Tuned -* `/apis/tuned.openshift.io/v1/namespaces/{namespace}/tuneds/{name}` -- `DELETE`: delete a Tuned -- `GET`: read the specified Tuned -- `PATCH`: partially update the specified Tuned -- `PUT`: replace the specified Tuned - - -=== /apis/tuned.openshift.io/v1/tuneds - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Tuned - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#tunedlist-tuned-openshift-io-v1[`TunedList tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/tuned.openshift.io/v1/namespaces/{namespace}/tuneds - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Tuned - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Tuned - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#tunedlist-tuned-openshift-io-v1[`TunedList tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Tuned - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| 201 - Created -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| 202 - Accepted -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/tuned.openshift.io/v1/namespaces/{namespace}/tuneds/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Tuned -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Tuned - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Tuned - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Tuned - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Tuned - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| 201 - Created -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`Tuned tuned.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/oauth_apis/oauth-apis-index.adoc b/rest_api/oauth_apis/oauth-apis-index.adoc deleted file mode 100644 index 5460f9807f0c..000000000000 --- a/rest_api/oauth_apis/oauth-apis-index.adoc +++ /dev/null @@ -1,48 +0,0 @@ -[id="oauth-apis"] -= OAuth APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== OAuthAccessToken [oauth.openshift.io/v1] - -Description:: - OAuthAccessToken describes an OAuth access token - -Type:: - `object` - -== OAuthAuthorizeToken [oauth.openshift.io/v1] - -Description:: - OAuthAuthorizeToken describes an OAuth authorization token - -Type:: - `object` - -== OAuthClientAuthorization [oauth.openshift.io/v1] - -Description:: - OAuthClientAuthorization describes an authorization created by an OAuth client - -Type:: - `object` - -== OAuthClient [oauth.openshift.io/v1] - -Description:: - OAuthClient describes an OAuth client - -Type:: - `object` - -== UserOAuthAccessToken [oauth.openshift.io/v1] - -Description:: - UserOAuthAccessToken is a virtual resource to mirror OAuthAccessTokens to the user the access token was issued for - -Type:: - `object` - diff --git a/rest_api/oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc b/rest_api/oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc deleted file mode 100644 index e3b967dd5576..000000000000 --- a/rest_api/oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc +++ /dev/null @@ -1,453 +0,0 @@ -[id="oauthaccesstoken-oauth-openshift-io-v1"] -= OAuthAccessToken [oauth.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OAuthAccessToken describes an OAuth access token - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `authorizeToken` -| `string` -| AuthorizeToken contains the token that authorized this token - -| `clientName` -| `string` -| ClientName references the client that created this token. - -| `expiresIn` -| `integer` -| ExpiresIn is the seconds from CreationTime before this token expires. - -| `inactivityTimeoutSeconds` -| `integer` -| InactivityTimeoutSeconds is the value in seconds, from the CreationTimestamp, after which this token can no longer be used. The value is automatically incremented when the token is used. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `redirectURI` -| `string` -| RedirectURI is the redirection associated with the token. - -| `refreshToken` -| `string` -| RefreshToken is the value by which this token can be renewed. Can be blank. - -| `scopes` -| `array (string)` -| Scopes is an array of the requested scopes. - -| `userName` -| `string` -| UserName is the user name associated with this token - -| `userUID` -| `string` -| UserUID is the unique UID associated with this token - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/oauth.openshift.io/v1/oauthaccesstokens` -- `DELETE`: delete collection of OAuthAccessToken -- `GET`: list or watch objects of kind OAuthAccessToken -- `POST`: create an OAuthAccessToken -* `/apis/oauth.openshift.io/v1/oauthaccesstokens/{name}` -- `DELETE`: delete an OAuthAccessToken -- `GET`: read the specified OAuthAccessToken -- `PATCH`: partially update the specified OAuthAccessToken -- `PUT`: replace the specified OAuthAccessToken - - -=== /apis/oauth.openshift.io/v1/oauthaccesstokens - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OAuthAccessToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind OAuthAccessToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#oauthaccesstokenlist-oauth-openshift-io-v1[`OAuthAccessTokenList oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OAuthAccessToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| 201 - Created -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| 202 - Accepted -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/oauth.openshift.io/v1/oauthaccesstokens/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OAuthAccessToken -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OAuthAccessToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OAuthAccessToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OAuthAccessToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OAuthAccessToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| 201 - Created -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`OAuthAccessToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc b/rest_api/oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc deleted file mode 100644 index cc18037c9019..000000000000 --- a/rest_api/oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc +++ /dev/null @@ -1,453 +0,0 @@ -[id="oauthauthorizetoken-oauth-openshift-io-v1"] -= OAuthAuthorizeToken [oauth.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OAuthAuthorizeToken describes an OAuth authorization token - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `clientName` -| `string` -| ClientName references the client that created this token. - -| `codeChallenge` -| `string` -| CodeChallenge is the optional code_challenge associated with this authorization code, as described in rfc7636 - -| `codeChallengeMethod` -| `string` -| CodeChallengeMethod is the optional code_challenge_method associated with this authorization code, as described in rfc7636 - -| `expiresIn` -| `integer` -| ExpiresIn is the seconds from CreationTime before this token expires. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `redirectURI` -| `string` -| RedirectURI is the redirection associated with the token. - -| `scopes` -| `array (string)` -| Scopes is an array of the requested scopes. - -| `state` -| `string` -| State data from request - -| `userName` -| `string` -| UserName is the user name associated with this token - -| `userUID` -| `string` -| UserUID is the unique UID associated with this token. UserUID and UserName must both match for this token to be valid. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/oauth.openshift.io/v1/oauthauthorizetokens` -- `DELETE`: delete collection of OAuthAuthorizeToken -- `GET`: list or watch objects of kind OAuthAuthorizeToken -- `POST`: create an OAuthAuthorizeToken -* `/apis/oauth.openshift.io/v1/oauthauthorizetokens/{name}` -- `DELETE`: delete an OAuthAuthorizeToken -- `GET`: read the specified OAuthAuthorizeToken -- `PATCH`: partially update the specified OAuthAuthorizeToken -- `PUT`: replace the specified OAuthAuthorizeToken - - -=== /apis/oauth.openshift.io/v1/oauthauthorizetokens - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OAuthAuthorizeToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind OAuthAuthorizeToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#oauthauthorizetokenlist-oauth-openshift-io-v1[`OAuthAuthorizeTokenList oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OAuthAuthorizeToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| 201 - Created -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| 202 - Accepted -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/oauth.openshift.io/v1/oauthauthorizetokens/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OAuthAuthorizeToken -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OAuthAuthorizeToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OAuthAuthorizeToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OAuthAuthorizeToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OAuthAuthorizeToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| 201 - Created -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`OAuthAuthorizeToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/oauth_apis/oauthclient-oauth-openshift-io-v1.adoc b/rest_api/oauth_apis/oauthclient-oauth-openshift-io-v1.adoc deleted file mode 100644 index cd0b3bae9c8b..000000000000 --- a/rest_api/oauth_apis/oauthclient-oauth-openshift-io-v1.adoc +++ /dev/null @@ -1,519 +0,0 @@ -[id="oauthclient-oauth-openshift-io-v1"] -= OAuthClient [oauth.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OAuthClient describes an OAuth client - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessTokenInactivityTimeoutSeconds` -| `integer` -| AccessTokenInactivityTimeoutSeconds overrides the default token inactivity timeout for tokens granted to this client. The value represents the maximum amount of time that can occur between consecutive uses of the token. Tokens become invalid if they are not used within this temporal window. The user will need to acquire a new token to regain access once a token times out. This value needs to be set only if the default set in configuration is not appropriate for this client. Valid values are: - 0: Tokens for this client never time out - X: Tokens time out if there is no activity for X seconds The current minimum allowed value for X is 300 (5 minutes) - -| `accessTokenMaxAgeSeconds` -| `integer` -| AccessTokenMaxAgeSeconds overrides the default access token max age for tokens granted to this client. 0 means no expiration. - -| `additionalSecrets` -| `array (string)` -| AdditionalSecrets holds other secrets that may be used to identify the client. This is useful for rotation and for service account token validation - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `grantMethod` -| `string` -| GrantMethod is a required field which determines how to handle grants for this client. Valid grant handling methods are: - - auto: always approves grant requests, useful for trusted clients - - prompt: prompts the end user for approval of grant requests, useful for third-party clients - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `redirectURIs` -| `array (string)` -| RedirectURIs is the valid redirection URIs associated with a client - -| `respondWithChallenges` -| `boolean` -| RespondWithChallenges indicates whether the client wants authentication needed responses made in the form of challenges instead of redirects - -| `scopeRestrictions` -| `array` -| ScopeRestrictions describes which scopes this client can request. Each requested scope is checked against each restriction. If any restriction matches, then the scope is allowed. If no restriction matches, then the scope is denied. - -| `scopeRestrictions[]` -| `object` -| ScopeRestriction describe one restriction on scopes. Exactly one option must be non-nil. - -| `secret` -| `string` -| Secret is the unique secret associated with a client - -|=== -..scopeRestrictions -Description:: - ScopeRestrictions describes which scopes this client can request. Each requested scope is checked against each restriction. If any restriction matches, then the scope is allowed. If no restriction matches, then the scope is denied. - -Type:: - `array` - - - - -..scopeRestrictions[] -Description:: - ScopeRestriction describe one restriction on scopes. Exactly one option must be non-nil. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clusterRole` -| `object` -| ClusterRoleScopeRestriction describes restrictions on cluster role scopes - -| `literals` -| `array (string)` -| ExactValues means the scope has to match a particular set of strings exactly - -|=== -..scopeRestrictions[].clusterRole -Description:: - ClusterRoleScopeRestriction describes restrictions on cluster role scopes - -Type:: - `object` - -Required:: - - `roleNames` - - `namespaces` - - `allowEscalation` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowEscalation` -| `boolean` -| AllowEscalation indicates whether you can request roles and their escalating resources - -| `namespaces` -| `array (string)` -| Namespaces is the list of namespaces that can be referenced. * means any of them (including *) - -| `roleNames` -| `array (string)` -| RoleNames is the list of cluster roles that can referenced. * means anything - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/oauth.openshift.io/v1/oauthclients` -- `DELETE`: delete collection of OAuthClient -- `GET`: list or watch objects of kind OAuthClient -- `POST`: create an OAuthClient -* `/apis/oauth.openshift.io/v1/oauthclients/{name}` -- `DELETE`: delete an OAuthClient -- `GET`: read the specified OAuthClient -- `PATCH`: partially update the specified OAuthClient -- `PUT`: replace the specified OAuthClient - - -=== /apis/oauth.openshift.io/v1/oauthclients - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OAuthClient - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind OAuthClient - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#oauthclientlist-oauth-openshift-io-v1[`OAuthClientList oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OAuthClient - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| 201 - Created -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| 202 - Accepted -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/oauth.openshift.io/v1/oauthclients/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OAuthClient -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OAuthClient - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OAuthClient - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OAuthClient - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OAuthClient - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| 201 - Created -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`OAuthClient oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc b/rest_api/oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc deleted file mode 100644 index 00744ac54647..000000000000 --- a/rest_api/oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc +++ /dev/null @@ -1,433 +0,0 @@ -[id="oauthclientauthorization-oauth-openshift-io-v1"] -= OAuthClientAuthorization [oauth.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OAuthClientAuthorization describes an authorization created by an OAuth client - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `clientName` -| `string` -| ClientName references the client that created this authorization - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `scopes` -| `array (string)` -| Scopes is an array of the granted scopes. - -| `userName` -| `string` -| UserName is the user name that authorized this client - -| `userUID` -| `string` -| UserUID is the unique UID associated with this authorization. UserUID and UserName must both match for this authorization to be valid. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/oauth.openshift.io/v1/oauthclientauthorizations` -- `DELETE`: delete collection of OAuthClientAuthorization -- `GET`: list or watch objects of kind OAuthClientAuthorization -- `POST`: create an OAuthClientAuthorization -* `/apis/oauth.openshift.io/v1/oauthclientauthorizations/{name}` -- `DELETE`: delete an OAuthClientAuthorization -- `GET`: read the specified OAuthClientAuthorization -- `PATCH`: partially update the specified OAuthClientAuthorization -- `PUT`: replace the specified OAuthClientAuthorization - - -=== /apis/oauth.openshift.io/v1/oauthclientauthorizations - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OAuthClientAuthorization - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind OAuthClientAuthorization - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#oauthclientauthorizationlist-oauth-openshift-io-v1[`OAuthClientAuthorizationList oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OAuthClientAuthorization - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| 201 - Created -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| 202 - Accepted -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/oauth.openshift.io/v1/oauthclientauthorizations/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OAuthClientAuthorization -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OAuthClientAuthorization - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OAuthClientAuthorization - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OAuthClientAuthorization - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OAuthClientAuthorization - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| 201 - Created -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`OAuthClientAuthorization oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/oauth_apis/useroauthaccesstoken-oauth-openshift-io-v1.adoc b/rest_api/oauth_apis/useroauthaccesstoken-oauth-openshift-io-v1.adoc deleted file mode 100644 index dbdb769aa730..000000000000 --- a/rest_api/oauth_apis/useroauthaccesstoken-oauth-openshift-io-v1.adoc +++ /dev/null @@ -1,233 +0,0 @@ -[id="useroauthaccesstoken-oauth-openshift-io-v1"] -= UserOAuthAccessToken [oauth.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - UserOAuthAccessToken is a virtual resource to mirror OAuthAccessTokens to the user the access token was issued for - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `authorizeToken` -| `string` -| AuthorizeToken contains the token that authorized this token - -| `clientName` -| `string` -| ClientName references the client that created this token. - -| `expiresIn` -| `integer` -| ExpiresIn is the seconds from CreationTime before this token expires. - -| `inactivityTimeoutSeconds` -| `integer` -| InactivityTimeoutSeconds is the value in seconds, from the CreationTimestamp, after which this token can no longer be used. The value is automatically incremented when the token is used. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `redirectURI` -| `string` -| RedirectURI is the redirection associated with the token. - -| `refreshToken` -| `string` -| RefreshToken is the value by which this token can be renewed. Can be blank. - -| `scopes` -| `array (string)` -| Scopes is an array of the requested scopes. - -| `userName` -| `string` -| UserName is the user name associated with this token - -| `userUID` -| `string` -| UserUID is the unique UID associated with this token - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/oauth.openshift.io/v1/useroauthaccesstokens` -- `GET`: list or watch objects of kind UserOAuthAccessToken -* `/apis/oauth.openshift.io/v1/useroauthaccesstokens/{name}` -- `DELETE`: delete an UserOAuthAccessToken -- `GET`: read the specified UserOAuthAccessToken - - -=== /apis/oauth.openshift.io/v1/useroauthaccesstokens - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind UserOAuthAccessToken - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#useroauthaccesstokenlist-oauth-openshift-io-v1[`UserOAuthAccessTokenList oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/oauth.openshift.io/v1/useroauthaccesstokens/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the UserOAuthAccessToken -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an UserOAuthAccessToken - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified UserOAuthAccessToken - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../oauth_apis/useroauthaccesstoken-oauth-openshift-io-v1.adoc#useroauthaccesstoken-oauth-openshift-io-v1[`UserOAuthAccessToken oauth.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/objects/index.adoc b/rest_api/objects/index.adoc deleted file mode 100644 index a1efeb7f1e6a..000000000000 --- a/rest_api/objects/index.adoc +++ /dev/null @@ -1,13591 +0,0 @@ -[id="api-object-reference"] -= Common object reference -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -[id="affinity-core-v1"] -== Affinity [core/v1] - - -Description:: - Affinity is a group of affinity scheduling rules. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeAffinity` -| xref:../objects/index.adoc#nodeaffinity-core-v1[`NodeAffinity core/v1`] -| Describes node affinity scheduling rules for the pod. - -| `podAffinity` -| xref:../objects/index.adoc#podaffinity-core-v1[`PodAffinity core/v1`] -| Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -| `podAntiAffinity` -| xref:../objects/index.adoc#podantiaffinity-core-v1[`PodAntiAffinity core/v1`] -| Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -|=== - -[id="aggregationrule-rbac-authorization-k8s-io-v1"] -== AggregationRule [rbac.authorization.k8s.io/v1] - - -Description:: - AggregationRule describes how to locate ClusterRoles to aggregate into the ClusterRole - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clusterRoleSelectors` -| xref:../objects/index.adoc#labelselector-meta-v1[`array (LabelSelector meta/v1)`] -| ClusterRoleSelectors holds a list of selectors which will be used to find ClusterRoles and create the rules. If any of the selectors match, then the ClusterRole's permissions will be added - -|=== - -[id="alertmanagerconfiglist-monitoring-coreos-com-v1alpha1"] -== AlertmanagerConfigList [monitoring.coreos.com/v1alpha1] - - -Description:: - AlertmanagerConfigList is a list of AlertmanagerConfig - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../monitoring_apis/alertmanagerconfig-monitoring-coreos-com-v1alpha1.adoc#alertmanagerconfig-monitoring-coreos-com-v1alpha1[`array (AlertmanagerConfig monitoring.coreos.com/v1alpha1)`] -| List of alertmanagerconfigs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="alertmanagerlist-monitoring-coreos-com-v1"] -== AlertmanagerList [monitoring.coreos.com/v1] - - -Description:: - AlertmanagerList is a list of Alertmanager - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../monitoring_apis/alertmanager-monitoring-coreos-com-v1.adoc#alertmanager-monitoring-coreos-com-v1[`array (Alertmanager monitoring.coreos.com/v1)`] -| List of alertmanagers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="apiserverlist-config-openshift-io-v1"] -== APIServerList [config.openshift.io/v1] - - -Description:: - APIServerList is a list of APIServer - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/apiserver-config-openshift-io-v1.adoc#apiserver-config-openshift-io-v1[`array (APIServer config.openshift.io/v1)`] -| List of apiservers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="apiservicelist-apiregistration-k8s-io-v1"] -== APIServiceList [apiregistration.k8s.io/v1] - - -Description:: - APIServiceList is a list of APIService objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../extension_apis/apiservice-apiregistration-k8s-io-v1.adoc#apiservice-apiregistration-k8s-io-v1[`array (APIService apiregistration.k8s.io/v1)`] -| - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="appliedclusterresourcequotalist-quota-openshift-io-v1"] -== AppliedClusterResourceQuotaList [quota.openshift.io/v1] - - -Description:: - AppliedClusterResourceQuotaList is a collection of AppliedClusterResourceQuotas - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../schedule_and_quota_apis/appliedclusterresourcequota-quota-openshift-io-v1.adoc#appliedclusterresourcequota-quota-openshift-io-v1[`array (AppliedClusterResourceQuota quota.openshift.io/v1)`] -| Items is a list of AppliedClusterResourceQuota - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="attachedvolume-core-v1"] -== AttachedVolume [core/v1] - - -Description:: - AttachedVolume describes a volume attached to a node - -Type:: - `object` - -Required:: - - `name` - - `devicePath` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| DevicePath represents the device path where the volume should be available - -| `name` -| `string` -| Name of the attached volume - -|=== - -[id="authenticationlist-config-openshift-io-v1"] -== AuthenticationList [config.openshift.io/v1] - - -Description:: - AuthenticationList is a list of Authentication - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/authentication-config-openshift-io-v1.adoc#authentication-config-openshift-io-v1[`array (Authentication config.openshift.io/v1)`] -| List of authentications. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="authenticationlist-operator-openshift-io-v1"] -== AuthenticationList [operator.openshift.io/v1] - - -Description:: - AuthenticationList is a list of Authentication - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`array (Authentication operator.openshift.io/v1)`] -| List of authentications. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="awselasticblockstorevolumesource-core-v1"] -== AWSElasticBlockStoreVolumeSource [core/v1] - - -Description:: - Represents a Persistent Disk resource in AWS. - -An AWS EBS disk must exist before mounting to a container. The disk must also be in the same AWS zone as the kubelet. An AWS EBS disk can only be mounted as read/write once. AWS EBS volumes support ownership management and SELinux relabeling. - -Type:: - `object` - -Required:: - - `volumeID` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). - -| `readOnly` -| `boolean` -| Specify "true" to force and set the ReadOnly property in VolumeMounts to "true". If omitted, the default is "false". More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `volumeID` -| `string` -| Unique ID of the persistent disk resource in AWS (Amazon EBS volume). More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -|=== - -[id="azurediskvolumesource-core-v1"] -== AzureDiskVolumeSource [core/v1] - - -Description:: - AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `diskName` - - `diskURI` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cachingMode` -| `string` -| Host Caching mode: None, Read Only, Read Write. - -| `diskName` -| `string` -| The Name of the data disk in the blob storage - -| `diskURI` -| `string` -| The URI the data disk in the blob storage - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `kind` -| `string` -| Expected values Shared: multiple blob disks per storage account Dedicated: single blob disk per storage account Managed: azure managed data disk (only in managed availability set). defaults to shared - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -|=== - -[id="azurefilepersistentvolumesource-core-v1"] -== AzureFilePersistentVolumeSource [core/v1] - - -Description:: - AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `secretName` - - `shareName` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretName` -| `string` -| the name of secret that contains Azure Storage Account Name and Key - -| `secretNamespace` -| `string` -| the namespace of the secret that contains Azure Storage Account Name and Key default is the same as the Pod - -| `shareName` -| `string` -| Share Name - -|=== - -[id="azurefilevolumesource-core-v1"] -== AzureFileVolumeSource [core/v1] - - -Description:: - AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `secretName` - - `shareName` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretName` -| `string` -| the name of secret that contains Azure Storage Account Name and Key - -| `shareName` -| `string` -| Share Name - -|=== - -[id="baremetalhostlist-metal3-io-v1alpha1"] -== BareMetalHostList [metal3.io/v1alpha1] - - -Description:: - BareMetalHostList is a list of BareMetalHost - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`array (BareMetalHost metal3.io/v1alpha1)`] -| List of baremetalhosts. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="brokertemplateinstancelist-template-openshift-io-v1"] -== BrokerTemplateInstanceList [template.openshift.io/v1] - - -Description:: - BrokerTemplateInstanceList is a list of BrokerTemplateInstance objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`array (BrokerTemplateInstance template.openshift.io/v1)`] -| items is a list of BrokerTemplateInstances - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="buildconfiglist-build-openshift-io-v1"] -== BuildConfigList [build.openshift.io/v1] - - -Description:: - BuildConfigList is a collection of BuildConfigs. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`array (BuildConfig build.openshift.io/v1)`] -| items is a list of build configs - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="buildlist-build-openshift-io-v1"] -== BuildList [build.openshift.io/v1] - - -Description:: - BuildList is a collection of Builds. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`array (Build build.openshift.io/v1)`] -| items is a list of builds - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="buildlist-config-openshift-io-v1"] -== BuildList [config.openshift.io/v1] - - -Description:: - BuildList is a list of Build - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/build-config-openshift-io-v1.adoc#build-config-openshift-io-v1[`array (Build config.openshift.io/v1)`] -| List of builds. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="buildlog-build-openshift-io-v1"] -== BuildLog [build.openshift.io/v1] - - -Description:: - BuildLog is the (unused) resource associated with the build log redirector - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="buildrequest-build-openshift-io-v1"] -== BuildRequest [build.openshift.io/v1] - - -Description:: - BuildRequest is the resource used to pass parameters to build generator - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `binary` -| xref:../objects/index.adoc#binarybuildsource-build-openshift-io-v1[`BinaryBuildSource build.openshift.io/v1`] -| binary indicates a request to build from a binary provided to the builder - -| `dockerStrategyOptions` -| xref:../objects/index.adoc#dockerstrategyoptions-build-openshift-io-v1[`DockerStrategyOptions build.openshift.io/v1`] -| DockerStrategyOptions contains additional docker-strategy specific options for the build - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a builder container. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is the reference to the ImageStreamTag that triggered the build. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `lastVersion` -| `integer` -| lastVersion (optional) is the LastVersion of the BuildConfig that was used to generate the build. If the BuildConfig in the generator doesn't match, a build will not be generated. - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `revision` -| xref:../objects/index.adoc#sourcerevision-build-openshift-io-v1[`SourceRevision build.openshift.io/v1`] -| revision is the information from the source for a specific repo snapshot. - -| `sourceStrategyOptions` -| xref:../objects/index.adoc#sourcestrategyoptions-build-openshift-io-v1[`SourceStrategyOptions build.openshift.io/v1`] -| SourceStrategyOptions contains additional source-strategy specific options for the build - -| `triggeredBy` -| xref:../objects/index.adoc#buildtriggercause-build-openshift-io-v1[`array (BuildTriggerCause build.openshift.io/v1)`] -| triggeredBy describes which triggers started the most recent update to the build configuration and contains information about those triggers. - -| `triggeredByImage` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| triggeredByImage is the Image that triggered this build. - -|=== - -[id="capabilities-core-v1"] -== Capabilities [core/v1] - - -Description:: - Adds and removes POSIX capabilities from running containers. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== - -[id="catalogsourcelist-operators-coreos-com-v1alpha1"] -== CatalogSourceList [operators.coreos.com/v1alpha1] - - -Description:: - CatalogSourceList is a list of CatalogSource - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`array (CatalogSource operators.coreos.com/v1alpha1)`] -| List of catalogsources. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="cephfspersistentvolumesource-core-v1"] -== CephFSPersistentVolumeSource [core/v1] - - -Description:: - Represents a Ceph Filesystem mount that lasts the lifetime of a pod Cephfs volumes do not support ownership management or SELinux relabeling. - -Type:: - `object` - -Required:: - - `monitors` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `monitors` -| `array (string)` -| Required: Monitors is a collection of Ceph monitors More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `path` -| `string` -| Optional: Used as the mounted root, rather than the full Ceph tree, default is / - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretFile` -| `string` -| Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `user` -| `string` -| Optional: User is the rados user name, default is admin More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -|=== - -[id="cephfsvolumesource-core-v1"] -== CephFSVolumeSource [core/v1] - - -Description:: - Represents a Ceph Filesystem mount that lasts the lifetime of a pod Cephfs volumes do not support ownership management or SELinux relabeling. - -Type:: - `object` - -Required:: - - `monitors` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `monitors` -| `array (string)` -| Required: Monitors is a collection of Ceph monitors More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `path` -| `string` -| Optional: Used as the mounted root, rather than the full Ceph tree, default is / - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretFile` -| `string` -| Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretRef` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `user` -| `string` -| Optional: User is the rados user name, default is admin More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -|=== - -[id="certificatesigningrequestlist-certificates-k8s-io-v1"] -== CertificateSigningRequestList [certificates.k8s.io/v1] - - -Description:: - CertificateSigningRequestList is a collection of CertificateSigningRequest objects - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`array (CertificateSigningRequest certificates.k8s.io/v1)`] -| items is a collection of CertificateSigningRequest objects - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="cinderpersistentvolumesource-core-v1"] -== CinderPersistentVolumeSource [core/v1] - - -Description:: - Represents a cinder volume resource in Openstack. A Cinder volume must exist before mounting to a container. The volume must also be in the same region as the kubelet. Cinder volumes support ownership management and SELinux relabeling. - -Type:: - `object` - -Required:: - - `volumeID` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `secretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| Optional: points to a secret object containing parameters used to connect to OpenStack. - -| `volumeID` -| `string` -| volume id used to identify the volume in cinder. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -|=== - -[id="cindervolumesource-core-v1"] -== CinderVolumeSource [core/v1] - - -Description:: - Represents a cinder volume resource in Openstack. A Cinder volume must exist before mounting to a container. The volume must also be in the same region as the kubelet. Cinder volumes support ownership management and SELinux relabeling. - -Type:: - `object` - -Required:: - - `volumeID` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `secretRef` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| Optional: points to a secret object containing parameters used to connect to OpenStack. - -| `volumeID` -| `string` -| volume id used to identify the volume in cinder. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -|=== - -[id="clientipconfig-core-v1"] -== ClientIPConfig [core/v1] - - -Description:: - ClientIPConfig represents the configurations of Client IP based session affinity. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `timeoutSeconds` -| `integer` -| timeoutSeconds specifies the seconds of ClientIP type session sticky time. The value must be >0 && <=86400(for 1 day) if ServiceAffinity == "ClientIP". Default value is 10800(for 3 hours). - -|=== - -[id="cloudcredentiallist-operator-openshift-io-v1"] -== CloudCredentialList [operator.openshift.io/v1] - - -Description:: - CloudCredentialList is a list of CloudCredential - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`array (CloudCredential operator.openshift.io/v1)`] -| List of cloudcredentials. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="clusterautoscalerlist-autoscaling-openshift-io-v1"] -== ClusterAutoscalerList [autoscaling.openshift.io/v1] - - -Description:: - ClusterAutoscalerList is a list of ClusterAutoscaler - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../autoscale_apis/clusterautoscaler-autoscaling-openshift-io-v1.adoc#clusterautoscaler-autoscaling-openshift-io-v1[`array (ClusterAutoscaler autoscaling.openshift.io/v1)`] -| List of clusterautoscalers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="clustercsidriverlist-operator-openshift-io-v1"] -== ClusterCSIDriverList [operator.openshift.io/v1] - - -Description:: - ClusterCSIDriverList is a list of ClusterCSIDriver - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`array (ClusterCSIDriver operator.openshift.io/v1)`] -| List of clustercsidrivers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="clusternetworklist-network-openshift-io-v1"] -== ClusterNetworkList [network.openshift.io/v1] - - -Description:: - ClusterNetworkList is a list of ClusterNetwork - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/clusternetwork-network-openshift-io-v1.adoc#clusternetwork-network-openshift-io-v1[`array (ClusterNetwork network.openshift.io/v1)`] -| List of clusternetworks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="clusteroperatorlist-config-openshift-io-v1"] -== ClusterOperatorList [config.openshift.io/v1] - - -Description:: - ClusterOperatorList is a list of ClusterOperator - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/clusteroperator-config-openshift-io-v1.adoc#clusteroperator-config-openshift-io-v1[`array (ClusterOperator config.openshift.io/v1)`] -| List of clusteroperators. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="clusterresourcequotalist-quota-openshift-io-v1"] -== ClusterResourceQuotaList [quota.openshift.io/v1] - - -Description:: - ClusterResourceQuotaList is a list of ClusterResourceQuota - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`array (ClusterResourceQuota quota.openshift.io/v1)`] -| List of clusterresourcequotas. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="clusterrolebindinglist-authorization-openshift-io-v1"] -== ClusterRoleBindingList [authorization.openshift.io/v1] - - -Description:: - ClusterRoleBindingList is a collection of ClusterRoleBindings - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`array (ClusterRoleBinding authorization.openshift.io/v1)`] -| Items is a list of ClusterRoleBindings - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="clusterrolebindinglist-rbac-authorization-k8s-io-v1"] -== ClusterRoleBindingList [rbac.authorization.k8s.io/v1] - - -Description:: - ClusterRoleBindingList is a collection of ClusterRoleBindings - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`array (ClusterRoleBinding rbac.authorization.k8s.io/v1)`] -| Items is a list of ClusterRoleBindings - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard object's metadata. - -|=== - -[id="clusterrolelist-authorization-openshift-io-v1"] -== ClusterRoleList [authorization.openshift.io/v1] - - -Description:: - ClusterRoleList is a collection of ClusterRoles - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`array (ClusterRole authorization.openshift.io/v1)`] -| Items is a list of ClusterRoles - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="clusterrolelist-rbac-authorization-k8s-io-v1"] -== ClusterRoleList [rbac.authorization.k8s.io/v1] - - -Description:: - ClusterRoleList is a collection of ClusterRoles - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`array (ClusterRole rbac.authorization.k8s.io/v1)`] -| Items is a list of ClusterRoles - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard object's metadata. - -|=== - -[id="clusterserviceversionlist-operators-coreos-com-v1alpha1"] -== ClusterServiceVersionList [operators.coreos.com/v1alpha1] - - -Description:: - ClusterServiceVersionList is a list of ClusterServiceVersion - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`array (ClusterServiceVersion operators.coreos.com/v1alpha1)`] -| List of clusterserviceversions. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="clusterversionlist-config-openshift-io-v1"] -== ClusterVersionList [config.openshift.io/v1] - - -Description:: - ClusterVersionList is a list of ClusterVersion - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/clusterversion-config-openshift-io-v1.adoc#clusterversion-config-openshift-io-v1[`array (ClusterVersion config.openshift.io/v1)`] -| List of clusterversions. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="componentcondition-core-v1"] -== ComponentCondition [core/v1] - - -Description:: - Information about the condition of a component. - -Type:: - `object` - -Required:: - - `type` - - `status` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `error` -| `string` -| Condition error code for a component. For example, a health check error code. - -| `message` -| `string` -| Message about the condition for a component. For example, information about a health check. - -| `status` -| `string` -| Status of the condition for a component. Valid values for "Healthy": "True", "False", or "Unknown". - -| `type` -| `string` -| Type of condition for a component. Valid value: "Healthy" - -|=== - -[id="componentstatuslist-core-v1"] -== ComponentStatusList [core/v1] - - -Description:: - Status of all the conditions for the component as a list of ComponentStatus objects. Deprecated: This API is deprecated in v1.19+ - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../metadata_apis/componentstatus-core-v1.adoc#componentstatus-core-v1[`array (ComponentStatus core/v1)`] -| List of ComponentStatus objects. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="condition-meta-v1"] -== Condition [meta/v1] - - -Description:: - Condition contains details for one aspect of the current state of this API Resource. - -Type:: - `object` - -Required:: - - `type` - - `status` - - `lastTransitionTime` - - `reason` - - `message` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. - -| `message` -| `string` -| message is a human readable message indicating details about the transition. This may be an empty string. - -| `observedGeneration` -| `integer` -| observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. - -| `reason` -| `string` -| reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type of condition in CamelCase or in foo.example.com/CamelCase. - -|=== - -[id="configlist-imageregistry-operator-openshift-io-v1"] -== ConfigList [imageregistry.operator.openshift.io/v1] - - -Description:: - ConfigList is a list of Config - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`array (Config imageregistry.operator.openshift.io/v1)`] -| List of configs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="configlist-operator-openshift-io-v1"] -== ConfigList [operator.openshift.io/v1] - - -Description:: - ConfigList is a list of Config - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`array (Config operator.openshift.io/v1)`] -| List of configs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="configlist-samples-operator-openshift-io-v1"] -== ConfigList [samples.operator.openshift.io/v1] - - -Description:: - ConfigList is a list of Config - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`array (Config samples.operator.openshift.io/v1)`] -| List of configs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="configmapenvsource-core-v1"] -== ConfigMapEnvSource [core/v1] - - -Description:: - ConfigMapEnvSource selects a ConfigMap to populate the environment variables with. - -The contents of the target ConfigMap's Data field will represent the key-value pairs as environment variables. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== - -[id="configmapkeyselector-core-v1"] -== ConfigMapKeySelector [core/v1] - - -Description:: - Selects a key from a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== - -[id="configmaplist-core-v1"] -== ConfigMapList [core/v1] - - -Description:: - ConfigMapList is a resource containing a list of ConfigMap objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../metadata_apis/configmap-core-v1.adoc#configmap-core-v1[`array (ConfigMap core/v1)`] -| Items is the list of ConfigMaps. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="configmapnodeconfigsource-core-v1"] -== ConfigMapNodeConfigSource [core/v1] - - -Description:: - ConfigMapNodeConfigSource contains the information to reference a ConfigMap as a config source for the Node. - -Type:: - `object` - -Required:: - - `namespace` - - `name` - - `kubeletConfigKey` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kubeletConfigKey` -| `string` -| KubeletConfigKey declares which key of the referenced ConfigMap corresponds to the KubeletConfiguration structure This field is required in all cases. - -| `name` -| `string` -| Name is the metadata.name of the referenced ConfigMap. This field is required in all cases. - -| `namespace` -| `string` -| Namespace is the metadata.namespace of the referenced ConfigMap. This field is required in all cases. - -| `resourceVersion` -| `string` -| ResourceVersion is the metadata.ResourceVersion of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - -| `uid` -| `string` -| UID is the metadata.UID of the referenced ConfigMap. This field is forbidden in Node.Spec, and required in Node.Status. - -|=== - -[id="configmapprojection-core-v1"] -== ConfigMapProjection [core/v1] - - -Description:: - Adapts a ConfigMap into a projected volume. - -The contents of the target ConfigMap's Data field will be presented in a projected volume as files using the keys in the Data field as the file names, unless the items element is populated with specific mappings of keys to paths. Note that this is identical to a configmap volume source without the default mode. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| xref:../objects/index.adoc#keytopath-core-v1[`array (KeyToPath core/v1)`] -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== - -[id="configmapvolumesource-core-v1"] -== ConfigMapVolumeSource [core/v1] - - -Description:: - Adapts a ConfigMap into a volume. - -The contents of the target ConfigMap's Data field will be presented in a volume as files using the keys in the Data field as the file names, unless the items element is populated with specific mappings of keys to paths. ConfigMap volumes support ownership management and SELinux relabeling. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| xref:../objects/index.adoc#keytopath-core-v1[`array (KeyToPath core/v1)`] -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== - -[id="consoleclidownloadlist-console-openshift-io-v1"] -== ConsoleCLIDownloadList [console.openshift.io/v1] - - -Description:: - ConsoleCLIDownloadList is a list of ConsoleCLIDownload - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../console_apis/consoleclidownload-console-openshift-io-v1.adoc#consoleclidownload-console-openshift-io-v1[`array (ConsoleCLIDownload console.openshift.io/v1)`] -| List of consoleclidownloads. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="consoleexternalloglinklist-console-openshift-io-v1"] -== ConsoleExternalLogLinkList [console.openshift.io/v1] - - -Description:: - ConsoleExternalLogLinkList is a list of ConsoleExternalLogLink - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../console_apis/consoleexternalloglink-console-openshift-io-v1.adoc#consoleexternalloglink-console-openshift-io-v1[`array (ConsoleExternalLogLink console.openshift.io/v1)`] -| List of consoleexternalloglinks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="consolelinklist-console-openshift-io-v1"] -== ConsoleLinkList [console.openshift.io/v1] - - -Description:: - ConsoleLinkList is a list of ConsoleLink - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../console_apis/consolelink-console-openshift-io-v1.adoc#consolelink-console-openshift-io-v1[`array (ConsoleLink console.openshift.io/v1)`] -| List of consolelinks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="consolelist-config-openshift-io-v1"] -== ConsoleList [config.openshift.io/v1] - - -Description:: - ConsoleList is a list of Console - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/console-config-openshift-io-v1.adoc#console-config-openshift-io-v1[`array (Console config.openshift.io/v1)`] -| List of consoles. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="consolelist-operator-openshift-io-v1"] -== ConsoleList [operator.openshift.io/v1] - - -Description:: - ConsoleList is a list of Console - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`array (Console operator.openshift.io/v1)`] -| List of consoles. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="consolenotificationlist-console-openshift-io-v1"] -== ConsoleNotificationList [console.openshift.io/v1] - - -Description:: - ConsoleNotificationList is a list of ConsoleNotification - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../console_apis/consolenotification-console-openshift-io-v1.adoc#consolenotification-console-openshift-io-v1[`array (ConsoleNotification console.openshift.io/v1)`] -| List of consolenotifications. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="consolequickstartlist-console-openshift-io-v1"] -== ConsoleQuickStartList [console.openshift.io/v1] - - -Description:: - ConsoleQuickStartList is a list of ConsoleQuickStart - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../console_apis/consolequickstart-console-openshift-io-v1.adoc#consolequickstart-console-openshift-io-v1[`array (ConsoleQuickStart console.openshift.io/v1)`] -| List of consolequickstarts. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="consoleyamlsamplelist-console-openshift-io-v1"] -== ConsoleYAMLSampleList [console.openshift.io/v1] - - -Description:: - ConsoleYAMLSampleList is a list of ConsoleYAMLSample - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../console_apis/consoleyamlsample-console-openshift-io-v1.adoc#consoleyamlsample-console-openshift-io-v1[`array (ConsoleYAMLSample console.openshift.io/v1)`] -| List of consoleyamlsamples. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="container-core-v1"] -== Container [core/v1] - - -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| List of environment variables to set in the container. Cannot be updated. - -| `envFrom` -| xref:../objects/index.adoc#envfromsource-core-v1[`array (EnvFromSource core/v1)`] -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| xref:../objects/index.adoc#lifecycle-core-v1[`Lifecycle core/v1`] -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| xref:../objects/index.adoc#probe-core-v1[`Probe core/v1`] -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| xref:../objects/index.adoc#containerport-core-v1[`array (ContainerPort core/v1)`] -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `readinessProbe` -| xref:../objects/index.adoc#probe-core-v1[`Probe core/v1`] -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| xref:../objects/index.adoc#resourcerequirements-core-v1[`ResourceRequirements core/v1`] -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| xref:../objects/index.adoc#securitycontext-core-v1[`SecurityContext core/v1`] -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| xref:../objects/index.adoc#probe-core-v1[`Probe core/v1`] -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| xref:../objects/index.adoc#volumedevice-core-v1[`array (VolumeDevice core/v1)`] -| volumeDevices is the list of block devices to be used by the container. - -| `volumeMounts` -| xref:../objects/index.adoc#volumemount-core-v1[`array (VolumeMount core/v1)`] -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== - -[id="containerimage-core-v1"] -== ContainerImage [core/v1] - - -Description:: - Describe a container image - -Type:: - `object` - -Required:: - - `names` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `names` -| `array (string)` -| Names by which this image is known. e.g. ["k8s.gcr.io/hyperkube:v1.0.7", "dockerhub.io/google_containers/hyperkube:v1.0.7"] - -| `sizeBytes` -| `integer` -| The size of the image in bytes. - -|=== - -[id="containerport-core-v1"] -== ContainerPort [core/v1] - - -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== - -[id="containerruntimeconfiglist-machineconfiguration-openshift-io-v1"] -== ContainerRuntimeConfigList [machineconfiguration.openshift.io/v1] - - -Description:: - ContainerRuntimeConfigList is a list of ContainerRuntimeConfig - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../machine_apis/containerruntimeconfig-machineconfiguration-openshift-io-v1.adoc#containerruntimeconfig-machineconfiguration-openshift-io-v1[`array (ContainerRuntimeConfig machineconfiguration.openshift.io/v1)`] -| List of containerruntimeconfigs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="containerstate-core-v1"] -== ContainerState [core/v1] - - -Description:: - ContainerState holds a possible state of container. Only one of its members may be specified. If none of them is specified, the default one is ContainerStateWaiting. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `running` -| xref:../objects/index.adoc#containerstaterunning-core-v1[`ContainerStateRunning core/v1`] -| Details about a running container - -| `terminated` -| xref:../objects/index.adoc#containerstateterminated-core-v1[`ContainerStateTerminated core/v1`] -| Details about a terminated container - -| `waiting` -| xref:../objects/index.adoc#containerstatewaiting-core-v1[`ContainerStateWaiting core/v1`] -| Details about a waiting container - -|=== - -[id="containerstaterunning-core-v1"] -== ContainerStateRunning [core/v1] - - -Description:: - ContainerStateRunning is a running state of a container. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `startedAt` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Time at which the container was last (re-)started - -|=== - -[id="containerstateterminated-core-v1"] -== ContainerStateTerminated [core/v1] - - -Description:: - ContainerStateTerminated is a terminated state of a container. - -Type:: - `object` - -Required:: - - `exitCode` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerID` -| `string` -| Container's ID in the format 'docker://<container_id>' - -| `exitCode` -| `integer` -| Exit status from the last termination of the container - -| `finishedAt` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Time at which the container last terminated - -| `message` -| `string` -| Message regarding the last termination of the container - -| `reason` -| `string` -| (brief) reason from the last termination of the container - -| `signal` -| `integer` -| Signal from the last termination of the container - -| `startedAt` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Time at which previous execution of the container started - -|=== - -[id="containerstatewaiting-core-v1"] -== ContainerStateWaiting [core/v1] - - -Description:: - ContainerStateWaiting is a waiting state of a container. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `message` -| `string` -| Message regarding why the container is not yet running. - -| `reason` -| `string` -| (brief) reason the container is not yet running. - -|=== - -[id="controllerconfiglist-machineconfiguration-openshift-io-v1"] -== ControllerConfigList [machineconfiguration.openshift.io/v1] - - -Description:: - ControllerConfigList is a list of ControllerConfig - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../machine_apis/controllerconfig-machineconfiguration-openshift-io-v1.adoc#controllerconfig-machineconfiguration-openshift-io-v1[`array (ControllerConfig machineconfiguration.openshift.io/v1)`] -| List of controllerconfigs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="controllerrevisionlist-apps-v1"] -== ControllerRevisionList [apps/v1] - - -Description:: - ControllerRevisionList is a resource containing a list of ControllerRevision objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../metadata_apis/controllerrevision-apps-v1.adoc#controllerrevision-apps-v1[`array (ControllerRevision apps/v1)`] -| Items is the list of ControllerRevisions - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="credentialsrequestlist-cloudcredential-openshift-io-v1"] -== CredentialsRequestList [cloudcredential.openshift.io/v1] - - -Description:: - CredentialsRequestList is a list of CredentialsRequest - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`array (CredentialsRequest cloudcredential.openshift.io/v1)`] -| List of credentialsrequests. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="cronjoblist-batch-v1beta1"] -== CronJobList [batch/v1beta1] - - -Description:: - CronJobList is a collection of cron jobs. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`array (CronJob batch/v1beta1)`] -| items is the list of CronJobs. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="csidriverlist-storage-k8s-io-v1"] -== CSIDriverList [storage.k8s.io/v1] - - -Description:: - CSIDriverList is a collection of CSIDriver objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`array (CSIDriver storage.k8s.io/v1)`] -| items is the list of CSIDriver - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="csinodelist-storage-k8s-io-v1"] -== CSINodeList [storage.k8s.io/v1] - - -Description:: - CSINodeList is a collection of CSINode objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`array (CSINode storage.k8s.io/v1)`] -| items is the list of CSINode - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="csipersistentvolumesource-core-v1"] -== CSIPersistentVolumeSource [core/v1] - - -Description:: - Represents storage that is managed by an external CSI volume driver (Beta feature) - -Type:: - `object` - -Required:: - - `driver` - - `volumeHandle` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `controllerExpandSecretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| ControllerExpandSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI ControllerExpandVolume call. This is an alpha field and requires enabling ExpandCSIVolumes feature gate. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. - -| `controllerPublishSecretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| ControllerPublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI ControllerPublishVolume and ControllerUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. - -| `driver` -| `string` -| Driver is the name of the driver to use for this volume. Required. - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". - -| `nodePublishSecretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. - -| `nodeStageSecretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| NodeStageSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodeStageVolume and NodeStageVolume and NodeUnstageVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secrets are passed. - -| `readOnly` -| `boolean` -| Optional: The value to pass to ControllerPublishVolumeRequest. Defaults to false (read/write). - -| `volumeAttributes` -| `object (string)` -| Attributes of the volume to publish. - -| `volumeHandle` -| `string` -| VolumeHandle is the unique volume name returned by the CSI volume plugin’s CreateVolume to refer to the volume on all subsequent calls. Required. - -|=== - -[id="csisnapshotcontrollerlist-operator-openshift-io-v1"] -== CSISnapshotControllerList [operator.openshift.io/v1] - - -Description:: - CSISnapshotControllerList is a list of CSISnapshotController - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`array (CSISnapshotController operator.openshift.io/v1)`] -| List of csisnapshotcontrollers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="csivolumesource-core-v1"] -== CSIVolumeSource [core/v1] - - -Description:: - Represents a source location of a volume to mount, managed by an external CSI driver - -Type:: - `object` - -Required:: - - `driver` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the CSI driver that handles this volume. Consult with your admin for the correct name as registered in the cluster. - -| `fsType` -| `string` -| Filesystem type to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. - -| `nodePublishSecretRef` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeAttributes` -| `object (string)` -| VolumeAttributes stores driver-specific properties that are passed to the CSI driver. Consult your driver's documentation for supported values. - -|=== - -[id="customresourcedefinitionlist-apiextensions-k8s-io-v1"] -== CustomResourceDefinitionList [apiextensions.k8s.io/v1] - - -Description:: - CustomResourceDefinitionList is a list of CustomResourceDefinition objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../extension_apis/customresourcedefinition-apiextensions-k8s-io-v1.adoc#customresourcedefinition-apiextensions-k8s-io-v1[`array (CustomResourceDefinition apiextensions.k8s.io/v1)`] -| items list individual CustomResourceDefinition objects - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="daemonendpoint-core-v1"] -== DaemonEndpoint [core/v1] - - -Description:: - DaemonEndpoint contains information about a single Daemon endpoint. - -Type:: - `object` - -Required:: - - `Port` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `Port` -| `integer` -| Port number of the given endpoint. - -|=== - -[id="daemonsetlist-apps-v1"] -== DaemonSetList [apps/v1] - - -Description:: - DaemonSetList is a collection of daemon sets. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`array (DaemonSet apps/v1)`] -| A list of daemon sets. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="deleteoptions-meta-v1"] -== DeleteOptions [meta/v1] - - -Description:: - DeleteOptions may be provided when deleting an API object. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dryRun` -| `array (string)` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed - -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object's finalizers list. Either this field or PropagationPolicy may be set, but not both. - -| `preconditions` -| xref:../objects/index.adoc#preconditions-meta-v1[`Preconditions meta/v1`] -| Must be fulfilled before a deletion is carried out. If not possible, a 409 Conflict status will be returned. - -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground. - -|=== - -[id="deleteoptions_v2-meta-v1"] -== DeleteOptions_v2 [meta/v1] - - -Description:: - DeleteOptions may be provided when deleting an API object. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `dryRun` -| `array (string)` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed - -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the "orphan" finalizer will be added to/removed from the object's finalizers list. Either this field or PropagationPolicy may be set, but not both. - -| `preconditions` -| xref:../objects/index.adoc#preconditions-meta-v1[`Preconditions meta/v1`] -| Must be fulfilled before a deletion is carried out. If not possible, a 409 Conflict status will be returned. - -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: 'Orphan' - orphan the dependents; 'Background' - allow the garbage collector to delete the dependents in the background; 'Foreground' - a cascading policy that deletes all dependents in the foreground. - -|=== - -[id="deploymentconfiglist-apps-openshift-io-v1"] -== DeploymentConfigList [apps.openshift.io/v1] - - -Description:: - DeploymentConfigList is a collection of deployment configs. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`array (DeploymentConfig apps.openshift.io/v1)`] -| Items is a list of deployment configs - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="deploymentconfigrollback-apps-openshift-io-v1"] -== DeploymentConfigRollback [apps.openshift.io/v1] - - -Description:: - DeploymentConfigRollback provides the input to rollback generation. - -Type:: - `object` - -Required:: - - `name` - - `spec` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the deployment config that will be rolled back. - -| `spec` -| xref:../objects/index.adoc#deploymentconfigrollbackspec-apps-openshift-io-v1[`DeploymentConfigRollbackSpec apps.openshift.io/v1`] -| Spec defines the options to rollback generation. - -| `updatedAnnotations` -| `object (string)` -| UpdatedAnnotations is a set of new annotations that will be added in the deployment config. - -|=== - -[id="deploymentlist-apps-v1"] -== DeploymentList [apps/v1] - - -Description:: - DeploymentList is a list of Deployments. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`array (Deployment apps/v1)`] -| Items is the list of Deployments. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. - -|=== - -[id="deploymentlog-apps-openshift-io-v1"] -== DeploymentLog [apps.openshift.io/v1] - - -Description:: - DeploymentLog represents the logs for a deployment - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="deploymentrequest-apps-openshift-io-v1"] -== DeploymentRequest [apps.openshift.io/v1] - - -Description:: - DeploymentRequest is a request to a deployment config for a new deployment. - -Type:: - `object` - -Required:: - - `name` - - `latest` - - `force` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `excludeTriggers` -| `array (string)` -| ExcludeTriggers instructs the instantiator to avoid processing the specified triggers. This field overrides the triggers from latest and allows clients to control specific logic. This field is ignored if not specified. - -| `force` -| `boolean` -| Force will try to force a new deployment to run. If the deployment config is paused, then setting this to true will return an Invalid error. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `latest` -| `boolean` -| Latest will update the deployment config with the latest state from all triggers. - -| `name` -| `string` -| Name of the deployment config for requesting a new deployment. - -|=== - -[id="dnslist-config-openshift-io-v1"] -== DNSList [config.openshift.io/v1] - - -Description:: - DNSList is a list of DNS - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/dns-config-openshift-io-v1.adoc#dns-config-openshift-io-v1[`array (DNS config.openshift.io/v1)`] -| List of dnses. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="dnslist-operator-openshift-io-v1"] -== DNSList [operator.openshift.io/v1] - - -Description:: - DNSList is a list of DNS - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`array (DNS operator.openshift.io/v1)`] -| List of dnses. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="dnsrecordlist-ingress-operator-openshift-io-v1"] -== DNSRecordList [ingress.operator.openshift.io/v1] - - -Description:: - DNSRecordList is a list of DNSRecord - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`array (DNSRecord ingress.operator.openshift.io/v1)`] -| List of dnsrecords. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="downwardapiprojection-core-v1"] -== DownwardAPIProjection [core/v1] - - -Description:: - Represents downward API info for projecting into a projected volume. Note that this is identical to a downwardAPI volume source without the default mode. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| xref:../objects/index.adoc#downwardapivolumefile-core-v1[`array (DownwardAPIVolumeFile core/v1)`] -| Items is a list of DownwardAPIVolume file - -|=== - -[id="downwardapivolumefile-core-v1"] -== DownwardAPIVolumeFile [core/v1] - - -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| xref:../objects/index.adoc#objectfieldselector-core-v1[`ObjectFieldSelector core/v1`] -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file, must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| xref:../objects/index.adoc#resourcefieldselector-core-v1[`ResourceFieldSelector core/v1`] -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== - -[id="downwardapivolumesource-core-v1"] -== DownwardAPIVolumeSource [core/v1] - - -Description:: - DownwardAPIVolumeSource represents a volume containing downward API info. Downward API volumes support ownership management and SELinux relabeling. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| xref:../objects/index.adoc#downwardapivolumefile-core-v1[`array (DownwardAPIVolumeFile core/v1)`] -| Items is a list of downward API volume file - -|=== - -[id="egressnetworkpolicylist-network-openshift-io-v1"] -== EgressNetworkPolicyList [network.openshift.io/v1] - - -Description:: - EgressNetworkPolicyList is a list of EgressNetworkPolicy - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/egressnetworkpolicy-network-openshift-io-v1.adoc#egressnetworkpolicy-network-openshift-io-v1[`array (EgressNetworkPolicy network.openshift.io/v1)`] -| List of egressnetworkpolicies. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="emptydirvolumesource-core-v1"] -== EmptyDirVolumeSource [core/v1] - - -Description:: - Represents an empty directory for a pod. Empty directory volumes support ownership management and SELinux relabeling. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| xref:../objects/index.adoc#quantity-api-resource[`Quantity api/resource`] -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== - -[id="endpointaddress-core-v1"] -== EndpointAddress [core/v1] - - -Description:: - EndpointAddress is a tuple that describes single IP address. - -Type:: - `object` - -Required:: - - `ip` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hostname` -| `string` -| The Hostname of this endpoint - -| `ip` -| `string` -| The IP of this endpoint. May not be loopback (127.0.0.0/8), link-local (169.254.0.0/16), or link-local multicast ((224.0.0.0/24). IPv6 is also accepted but not fully supported on all platforms. Also, certain kubernetes components, like kube-proxy, are not IPv6 ready. - -| `nodeName` -| `string` -| Optional: Node hosting this endpoint. This can be used to determine endpoints local to a node. - -| `targetRef` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| Reference to object providing the endpoint. - -|=== - -[id="endpointport-core-v1"] -== EndpointPort [core/v1] - - -Description:: - EndpointPort is a tuple that describes a single port. - -Type:: - `object` - -Required:: - - `port` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `appProtocol` -| `string` -| The application protocol for this port. This field follows standard Kubernetes label syntax. Un-prefixed names are reserved for IANA standard service names (as per RFC-6335 and http://www.iana.org/assignments/service-names). Non-standard protocols should use prefixed names such as mycompany.com/my-custom-protocol. This is a beta field that is guarded by the ServiceAppProtocol feature gate and enabled by default. - -| `name` -| `string` -| The name of this port. This must match the 'name' field in the corresponding ServicePort. Must be a DNS_LABEL. Optional only if one port is defined. - -| `port` -| `integer` -| The port number of the endpoint. - -| `protocol` -| `string` -| The IP protocol for this port. Must be UDP, TCP, or SCTP. Default is TCP. - -|=== - -[id="endpointslicelist-discovery-k8s-io-v1beta1"] -== EndpointSliceList [discovery.k8s.io/v1beta1] - - -Description:: - EndpointSliceList represents a list of endpoint slices - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/endpointslice-discovery-k8s-io-v1beta1.adoc#endpointslice-discovery-k8s-io-v1beta1[`array (EndpointSlice discovery.k8s.io/v1beta1)`] -| List of endpoint slices - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. - -|=== - -[id="endpointslist-core-v1"] -== EndpointsList [core/v1] - - -Description:: - EndpointsList is a list of endpoints. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/endpoints-core-v1.adoc#endpoints-core-v1[`array (Endpoints core/v1)`] -| List of endpoints. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="endpointsubset-core-v1"] -== EndpointSubset [core/v1] - - -Description:: - EndpointSubset is a group of addresses with a common set of ports. The expanded set of endpoints is the Cartesian product of Addresses x Ports. For example, given: - { - Addresses: [{"ip": "10.10.1.1"}, {"ip": "10.10.2.2"}], - Ports: [{"name": "a", "port": 8675}, {"name": "b", "port": 309}] - } -The resulting set of endpoints can be viewed as: - a: [ 10.10.1.1:8675, 10.10.2.2:8675 ], - b: [ 10.10.1.1:309, 10.10.2.2:309 ] - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `addresses` -| xref:../objects/index.adoc#endpointaddress-core-v1[`array (EndpointAddress core/v1)`] -| IP addresses which offer the related ports that are marked as ready. These endpoints should be considered safe for load balancers and clients to utilize. - -| `notReadyAddresses` -| xref:../objects/index.adoc#endpointaddress-core-v1[`array (EndpointAddress core/v1)`] -| IP addresses which offer the related ports but are not currently marked as ready because they have not yet finished starting, have recently failed a readiness check, or have recently failed a liveness check. - -| `ports` -| xref:../objects/index.adoc#endpointport-core-v1[`array (EndpointPort core/v1)`] -| Port numbers available on the related IP addresses. - -|=== - -[id="envfromsource-core-v1"] -== EnvFromSource [core/v1] - - -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| xref:../objects/index.adoc#configmapenvsource-core-v1[`ConfigMapEnvSource core/v1`] -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| xref:../objects/index.adoc#secretenvsource-core-v1[`SecretEnvSource core/v1`] -| The Secret to select from - -|=== - -[id="envvar-core-v1"] -== EnvVar [core/v1] - - -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| xref:../objects/index.adoc#envvarsource-core-v1[`EnvVarSource core/v1`] -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== - -[id="envvarsource-core-v1"] -== EnvVarSource [core/v1] - - -Description:: - EnvVarSource represents a source for the value of an EnvVar. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| xref:../objects/index.adoc#configmapkeyselector-core-v1[`ConfigMapKeySelector core/v1`] -| Selects a key of a ConfigMap. - -| `fieldRef` -| xref:../objects/index.adoc#objectfieldselector-core-v1[`ObjectFieldSelector core/v1`] -| Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| xref:../objects/index.adoc#resourcefieldselector-core-v1[`ResourceFieldSelector core/v1`] -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| xref:../objects/index.adoc#secretkeyselector-core-v1[`SecretKeySelector core/v1`] -| Selects a key of a secret in the pod's namespace - -|=== - -[id="ephemeralcontainer-core-v1"] -== EphemeralContainer [core/v1] - - -Description:: - An EphemeralContainer is a container that may be added temporarily to an existing pod for user-initiated activities such as debugging. Ephemeral containers have no resource or scheduling guarantees, and they will not be restarted when they exit or when a pod is removed or restarted. If an ephemeral container causes a pod to exceed its resource allocation, the pod may be evicted. Ephemeral containers may not be added by directly updating the pod spec. They must be added via the pod's ephemeralcontainers subresource, and they will appear in the pod spec once added. This is an alpha feature enabled by the EphemeralContainers feature flag. - -Type:: - `object` - -Required:: - - `name` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| List of environment variables to set in the container. Cannot be updated. - -| `envFrom` -| xref:../objects/index.adoc#envfromsource-core-v1[`array (EnvFromSource core/v1)`] -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| xref:../objects/index.adoc#lifecycle-core-v1[`Lifecycle core/v1`] -| Lifecycle is not allowed for ephemeral containers. - -| `livenessProbe` -| xref:../objects/index.adoc#probe-core-v1[`Probe core/v1`] -| Probes are not allowed for ephemeral containers. - -| `name` -| `string` -| Name of the ephemeral container specified as a DNS_LABEL. This name must be unique among all containers, init containers and ephemeral containers. - -| `ports` -| xref:../objects/index.adoc#containerport-core-v1[`array (ContainerPort core/v1)`] -| Ports are not allowed for ephemeral containers. - -| `readinessProbe` -| xref:../objects/index.adoc#probe-core-v1[`Probe core/v1`] -| Probes are not allowed for ephemeral containers. - -| `resources` -| xref:../objects/index.adoc#resourcerequirements-core-v1[`ResourceRequirements core/v1`] -| Resources are not allowed for ephemeral containers. Ephemeral containers use spare resources already allocated to the pod. - -| `securityContext` -| xref:../objects/index.adoc#securitycontext-core-v1[`SecurityContext core/v1`] -| SecurityContext is not allowed for ephemeral containers. - -| `startupProbe` -| xref:../objects/index.adoc#probe-core-v1[`Probe core/v1`] -| Probes are not allowed for ephemeral containers. - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `targetContainerName` -| `string` -| If set, the name of the container from PodSpec that this ephemeral container targets. The ephemeral container will be run in the namespaces (IPC, PID, etc) of this container. If not set then the ephemeral container is run in whatever namespaces are shared for the pod. Note that the container runtime must support this feature. - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| xref:../objects/index.adoc#volumedevice-core-v1[`array (VolumeDevice core/v1)`] -| volumeDevices is the list of block devices to be used by the container. - -| `volumeMounts` -| xref:../objects/index.adoc#volumemount-core-v1[`array (VolumeMount core/v1)`] -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== - -[id="ephemeralvolumesource-core-v1"] -== EphemeralVolumeSource [core/v1] - - -Description:: - Represents an ephemeral volume that is handled by a normal storage driver. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeClaimTemplate` -| xref:../objects/index.adoc#persistentvolumeclaimtemplate-core-v1[`PersistentVolumeClaimTemplate core/v1`] -| Will be used to create a stand-alone PVC to provision the volume. The pod in which this EphemeralVolumeSource is embedded will be the owner of the PVC, i.e. the PVC will be deleted together with the pod. The name of the PVC will be `<pod name>-<volume name>` where `<volume name>` is the name from the `PodSpec.Volumes` array entry. Pod validation will reject the pod if the concatenated name is not valid for a PVC (for example, too long). - -An existing PVC with that name that is not owned by the pod will *not* be used for the pod to avoid using an unrelated volume by mistake. Starting the pod is then blocked until the unrelated PVC is removed. If such a pre-created PVC is meant to be used by the pod, the PVC has to updated with an owner reference to the pod once the pod exists. Normally this should not be necessary, but it may be useful when manually reconstructing a broken cluster. - -This field is read-only and no changes will be made by Kubernetes to the PVC after it has been created. - -Required, must not be nil. - -|=== - -[id="etcdlist-operator-openshift-io-v1"] -== EtcdList [operator.openshift.io/v1] - - -Description:: - EtcdList is a list of Etcd - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`array (Etcd operator.openshift.io/v1)`] -| List of etcds. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="eventlist-core-v1"] -== EventList [core/v1] - - -Description:: - EventList is a list of events. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../metadata_apis/event-core-v1.adoc#event-core-v1[`array (Event core/v1)`] -| List of events - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="eventlist-events-k8s-io-v1"] -== EventList [events.k8s.io/v1] - - -Description:: - EventList is a list of Event objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../metadata_apis/event-events-k8s-io-v1.adoc#event-events-k8s-io-v1[`array (Event events.k8s.io/v1)`] -| items is a list of schema objects. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="eventseries-core-v1"] -== EventSeries [core/v1] - - -Description:: - EventSeries contain information on series of events, i.e. thing that was/is happening continuously for some time. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `count` -| `integer` -| Number of occurrences in this series up to the last heartbeat time - -| `lastObservedTime` -| xref:../objects/index.adoc#microtime-meta-v1[`MicroTime meta/v1`] -| Time of the last occurrence observed - -|=== - -[id="eventsource-core-v1"] -== EventSource [core/v1] - - -Description:: - EventSource contains information for an event. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `component` -| `string` -| Component from which the event is generated. - -| `host` -| `string` -| Node name on which the event is generated. - -|=== - -[id="eviction-policy-v1beta1"] -== Eviction [policy/v1beta1] - - -Description:: - Eviction evicts a pod from its node subject to certain policies and safety constraints. This is a subresource of Pod. A request to cause such an eviction is created by POSTing to .../pods/<pod name>/evictions. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `deleteOptions` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| DeleteOptions may be provided - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| ObjectMeta describes the pod that is being evicted. - -|=== - -[id="execaction-core-v1"] -== ExecAction [core/v1] - - -Description:: - ExecAction describes a "run in container" action. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== - -[id="fcvolumesource-core-v1"] -== FCVolumeSource [core/v1] - - -Description:: - Represents a Fibre Channel volume. Fibre Channel volumes can only be mounted as read/write once. Fibre Channel volumes support ownership management and SELinux relabeling. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `lun` -| `integer` -| Optional: FC target lun number - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `targetWWNs` -| `array (string)` -| Optional: FC target worldwide names (WWNs) - -| `wwids` -| `array (string)` -| Optional: FC volume world wide identifiers (wwids) Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously. - -|=== - -[id="featuregatelist-config-openshift-io-v1"] -== FeatureGateList [config.openshift.io/v1] - - -Description:: - FeatureGateList is a list of FeatureGate - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/featuregate-config-openshift-io-v1.adoc#featuregate-config-openshift-io-v1[`array (FeatureGate config.openshift.io/v1)`] -| List of featuregates. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="fieldsv1-meta-v1"] -== FieldsV1 [meta/v1] - - -Description:: - FieldsV1 stores a set of fields in a data structure like a Trie, in JSON format. - -Each key is either a '.' representing the field itself, and will always map to an empty set, or a string representing a sub-field or item. The string will follow one of these four formats: 'f:<name>', where <name> is the name of a field in a struct, or key in a map 'v:<value>', where <value> is the exact json formatted value of a list item 'i:<index>', where <index> is position of a item in a list 'k:<keys>', where <keys> is a map of a list item's key fields to their unique values If a key maps to an empty Fields value, the field that key represents is part of the set. - -The exact format is defined in sigs.k8s.io/structured-merge-diff - -Type:: - `object` - - - -[id="flexpersistentvolumesource-core-v1"] -== FlexPersistentVolumeSource [core/v1] - - -Description:: - FlexPersistentVolumeSource represents a generic persistent volume resource that is provisioned/attached using an exec based plugin. - -Type:: - `object` - -Required:: - - `driver` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the driver to use for this volume. - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script. - -| `options` -| `object (string)` -| Optional: Extra command options if any. - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -|=== - -[id="flexvolumesource-core-v1"] -== FlexVolumeSource [core/v1] - - -Description:: - FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -Type:: - `object` - -Required:: - - `driver` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the driver to use for this volume. - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script. - -| `options` -| `object (string)` -| Optional: Extra command options if any. - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -|=== - -[id="flockervolumesource-core-v1"] -== FlockerVolumeSource [core/v1] - - -Description:: - Represents a Flocker volume mounted by the Flocker agent. One and only one of datasetName and datasetUUID should be set. Flocker volumes do not support ownership management or SELinux relabeling. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `datasetName` -| `string` -| Name of the dataset stored as metadata -> name on the dataset for Flocker should be considered as deprecated - -| `datasetUUID` -| `string` -| UUID of the dataset. This is unique identifier of a Flocker dataset - -|=== - -[id="flowschemalist-flowcontrol-apiserver-k8s-io-v1alpha1"] -== FlowSchemaList [flowcontrol.apiserver.k8s.io/v1alpha1] - - -Description:: - FlowSchemaList is a list of FlowSchema objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`array (FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1)`] -| `items` is a list of FlowSchemas. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| `metadata` is the standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="gcepersistentdiskvolumesource-core-v1"] -== GCEPersistentDiskVolumeSource [core/v1] - - -Description:: - Represents a Persistent Disk resource in Google Compute Engine. - -A GCE PD must exist before mounting to a container. The disk must also be in the same GCE project and zone as the kubelet. A GCE PD can only be mounted as read/write once or read-only many times. GCE PDs support ownership management and SELinux relabeling. - -Type:: - `object` - -Required:: - - `pdName` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `pdName` -| `string` -| Unique name of the PD resource in GCE. Used to identify the disk in GCE. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -|=== - -[id="gitrepovolumesource-core-v1"] -== GitRepoVolumeSource [core/v1] - - -Description:: - Represents a volume that is populated with the contents of a git repository. Git repo volumes do not support ownership management. Git repo volumes support SELinux relabeling. - -DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -Type:: - `object` - -Required:: - - `repository` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `directory` -| `string` -| Target directory name. Must not contain or start with '..'. If '.' is supplied, the volume directory will be the git repository. Otherwise, if specified, the volume will contain the git repository in the subdirectory with the given name. - -| `repository` -| `string` -| Repository URL - -| `revision` -| `string` -| Commit hash for the specified revision. - -|=== - -[id="glusterfspersistentvolumesource-core-v1"] -== GlusterfsPersistentVolumeSource [core/v1] - - -Description:: - Represents a Glusterfs mount that lasts the lifetime of a pod. Glusterfs volumes do not support ownership management or SELinux relabeling. - -Type:: - `object` - -Required:: - - `endpoints` - - `path` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `endpoints` -| `string` -| EndpointsName is the endpoint name that details Glusterfs topology. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `endpointsNamespace` -| `string` -| EndpointsNamespace is the namespace that contains Glusterfs endpoint. If this field is empty, the EndpointNamespace defaults to the same namespace as the bound PVC. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `path` -| `string` -| Path is the Glusterfs volume path. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `readOnly` -| `boolean` -| ReadOnly here will force the Glusterfs volume to be mounted with read-only permissions. Defaults to false. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -|=== - -[id="glusterfsvolumesource-core-v1"] -== GlusterfsVolumeSource [core/v1] - - -Description:: - Represents a Glusterfs mount that lasts the lifetime of a pod. Glusterfs volumes do not support ownership management or SELinux relabeling. - -Type:: - `object` - -Required:: - - `endpoints` - - `path` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `endpoints` -| `string` -| EndpointsName is the endpoint name that details Glusterfs topology. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `path` -| `string` -| Path is the Glusterfs volume path. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `readOnly` -| `boolean` -| ReadOnly here will force the Glusterfs volume to be mounted with read-only permissions. Defaults to false. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -|=== - -[id="grouplist-user-openshift-io-v1"] -== GroupList [user.openshift.io/v1] - - -Description:: - GroupList is a collection of Groups - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`array (Group user.openshift.io/v1)`] -| Items is the list of groups - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="groupversionkind-meta-v1"] -== GroupVersionKind [meta/v1] - - -Description:: - GroupVersionKind unambiguously identifies a kind. It doesn't anonymously include GroupVersion to avoid automatic coersion. It doesn't use a GroupVersion to avoid custom marshalling - -Type:: - `object` - -Required:: - - `group` - - `version` - - `kind` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `version` -| `string` -| - -|=== - -[id="handler-core-v1"] -== Handler [core/v1] - - -Description:: - Handler defines a specific action that should be taken - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| xref:../objects/index.adoc#execaction-core-v1[`ExecAction core/v1`] -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| xref:../objects/index.adoc#httpgetaction-core-v1[`HTTPGetAction core/v1`] -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| xref:../objects/index.adoc#tcpsocketaction-core-v1[`TCPSocketAction core/v1`] -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported - -|=== - -[id="helmchartrepositorylist-helm-openshift-io-v1beta1"] -== HelmChartRepositoryList [helm.openshift.io/v1beta1] - - -Description:: - HelmChartRepositoryList is a list of HelmChartRepository - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/helmchartrepository-helm-openshift-io-v1beta1.adoc#helmchartrepository-helm-openshift-io-v1beta1[`array (HelmChartRepository helm.openshift.io/v1beta1)`] -| List of helmchartrepositories. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="horizontalpodautoscalerlist-autoscaling-v1"] -== HorizontalPodAutoscalerList [autoscaling/v1] - - -Description:: - list of horizontal pod autoscaler objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../autoscale_apis/horizontalpodautoscaler-autoscaling-v1.adoc#horizontalpodautoscaler-autoscaling-v1[`array (HorizontalPodAutoscaler autoscaling/v1)`] -| list of horizontal pod autoscaler objects. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. - -|=== - -[id="hostalias-core-v1"] -== HostAlias [core/v1] - - -Description:: - HostAlias holds the mapping between IP and hostnames that will be injected as an entry in the pod's hosts file. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hostnames` -| `array (string)` -| Hostnames for the above IP address. - -| `ip` -| `string` -| IP address of the host file entry. - -|=== - -[id="hostpathvolumesource-core-v1"] -== HostPathVolumeSource [core/v1] - - -Description:: - Represents a host path mapped into a pod. Host path volumes do not support ownership management or SELinux relabeling. - -Type:: - `object` - -Required:: - - `path` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path of the directory on the host. If the path is a symlink, it will follow the link to the real path. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `type` -| `string` -| Type for HostPath Volume Defaults to "" More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -|=== - -[id="hostsubnetlist-network-openshift-io-v1"] -== HostSubnetList [network.openshift.io/v1] - - -Description:: - HostSubnetList is a list of HostSubnet - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/hostsubnet-network-openshift-io-v1.adoc#hostsubnet-network-openshift-io-v1[`array (HostSubnet network.openshift.io/v1)`] -| List of hostsubnets. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="httpgetaction-core-v1"] -== HTTPGetAction [core/v1] - - -Description:: - HTTPGetAction describes an action based on HTTP Get requests. - -Type:: - `object` - -Required:: - - `port` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| xref:../objects/index.adoc#httpheader-core-v1[`array (HTTPHeader core/v1)`] -| Custom headers to set in the request. HTTP allows repeated headers. - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== - -[id="httpheader-core-v1"] -== HTTPHeader [core/v1] - - -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== - -[id="identitylist-user-openshift-io-v1"] -== IdentityList [user.openshift.io/v1] - - -Description:: - IdentityList is a collection of Identities - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`array (Identity user.openshift.io/v1)`] -| Items is the list of identities - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="imagecontentsourcepolicylist-operator-openshift-io-v1alpha1"] -== ImageContentSourcePolicyList [operator.openshift.io/v1alpha1] - - -Description:: - ImageContentSourcePolicyList is a list of ImageContentSourcePolicy - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`array (ImageContentSourcePolicy operator.openshift.io/v1alpha1)`] -| List of imagecontentsourcepolicies. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="imagelist-config-openshift-io-v1"] -== ImageList [config.openshift.io/v1] - - -Description:: - ImageList is a list of Image - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/image-config-openshift-io-v1.adoc#image-config-openshift-io-v1[`array (Image config.openshift.io/v1)`] -| List of images. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="imagelist-image-openshift-io-v1"] -== ImageList [image.openshift.io/v1] - - -Description:: - ImageList is a list of Image objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../image_apis/image-image-openshift-io-v1.adoc#image-image-openshift-io-v1[`array (Image image.openshift.io/v1)`] -| Items is a list of images - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="imageprunerlist-imageregistry-operator-openshift-io-v1"] -== ImagePrunerList [imageregistry.operator.openshift.io/v1] - - -Description:: - ImagePrunerList is a list of ImagePruner - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`array (ImagePruner imageregistry.operator.openshift.io/v1)`] -| List of imagepruners. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="imagestreamlayers-image-openshift-io-v1"] -== ImageStreamLayers [image.openshift.io/v1] - - -Description:: - ImageStreamLayers describes information about the layers referenced by images in this image stream. - -Type:: - `object` - -Required:: - - `blobs` - - `images` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `blobs` -| xref:../objects/index.adoc#imagelayerdata-image-openshift-io-v1[`object (ImageLayerData image.openshift.io/v1)`] -| blobs is a map of blob name to metadata about the blob. - -| `images` -| xref:../objects/index.adoc#imageblobreferences-image-openshift-io-v1[`object (ImageBlobReferences image.openshift.io/v1)`] -| images is a map between an image name and the names of the blobs and config that comprise the image. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -|=== - -[id="imagestreamlist-image-openshift-io-v1"] -== ImageStreamList [image.openshift.io/v1] - - -Description:: - ImageStreamList is a list of ImageStream objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../image_apis/imagestream-image-openshift-io-v1.adoc#imagestream-image-openshift-io-v1[`array (ImageStream image.openshift.io/v1)`] -| Items is a list of imageStreams - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="imagestreamtaglist-image-openshift-io-v1"] -== ImageStreamTagList [image.openshift.io/v1] - - -Description:: - ImageStreamTagList is a list of ImageStreamTag objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../image_apis/imagestreamtag-image-openshift-io-v1.adoc#imagestreamtag-image-openshift-io-v1[`array (ImageStreamTag image.openshift.io/v1)`] -| Items is the list of image stream tags - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="imagetaglist-image-openshift-io-v1"] -== ImageTagList [image.openshift.io/v1] - - -Description:: - ImageTagList is a list of ImageTag objects. When listing image tags, the image field is not populated. Tags are returned in alphabetical order by image stream and then tag. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../image_apis/imagetag-image-openshift-io-v1.adoc#imagetag-image-openshift-io-v1[`array (ImageTag image.openshift.io/v1)`] -| Items is the list of image stream tags - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="infrastructurelist-config-openshift-io-v1"] -== InfrastructureList [config.openshift.io/v1] - - -Description:: - InfrastructureList is a list of Infrastructure - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/infrastructure-config-openshift-io-v1.adoc#infrastructure-config-openshift-io-v1[`array (Infrastructure config.openshift.io/v1)`] -| List of infrastructures. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="ingressclasslist-networking-k8s-io-v1"] -== IngressClassList [networking.k8s.io/v1] - - -Description:: - IngressClassList is a collection of IngressClasses. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/ingressclass-networking-k8s-io-v1.adoc#ingressclass-networking-k8s-io-v1[`array (IngressClass networking.k8s.io/v1)`] -| Items is the list of IngressClasses. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. - -|=== - -[id="ingresscontrollerlist-operator-openshift-io-v1"] -== IngressControllerList [operator.openshift.io/v1] - - -Description:: - IngressControllerList is a list of IngressController - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`array (IngressController operator.openshift.io/v1)`] -| List of ingresscontrollers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="ingresslist-config-openshift-io-v1"] -== IngressList [config.openshift.io/v1] - - -Description:: - IngressList is a list of Ingress - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/ingress-config-openshift-io-v1.adoc#ingress-config-openshift-io-v1[`array (Ingress config.openshift.io/v1)`] -| List of ingresses. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="ingresslist-networking-k8s-io-v1"] -== IngressList [networking.k8s.io/v1] - - -Description:: - IngressList is a collection of Ingress. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/ingress-networking-k8s-io-v1.adoc#ingress-networking-k8s-io-v1[`array (Ingress networking.k8s.io/v1)`] -| Items is the list of Ingress. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="installplanlist-operators-coreos-com-v1alpha1"] -== InstallPlanList [operators.coreos.com/v1alpha1] - - -Description:: - InstallPlanList is a list of InstallPlan - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`array (InstallPlan operators.coreos.com/v1alpha1)`] -| List of installplans. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="intorstring-util-intstr"] -== IntOrString [util/intstr] - - -Description:: - IntOrString is a type that can hold an int32 or a string. When used in JSON or YAML marshalling and unmarshalling, it produces or consumes the inner type. This allows you to have, for example, a JSON field that can accept a name or number. - -Type:: - `string` - - - -[id="ippoollist-whereabouts-cni-cncf-io-v1alpha1"] -== IPPoolList [whereabouts.cni.cncf.io/v1alpha1] - - -Description:: - IPPoolList is a list of IPPool - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/ippool-whereabouts-cni-cncf-io-v1alpha1.adoc#ippool-whereabouts-cni-cncf-io-v1alpha1[`array (IPPool whereabouts.cni.cncf.io/v1alpha1)`] -| List of ippools. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="iscsipersistentvolumesource-core-v1"] -== ISCSIPersistentVolumeSource [core/v1] - - -Description:: - ISCSIPersistentVolumeSource represents an ISCSI disk. ISCSI volumes can only be mounted as read/write once. ISCSI volumes support ownership management and SELinux relabeling. - -Type:: - `object` - -Required:: - - `targetPortal` - - `iqn` - - `lun` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `chapAuthDiscovery` -| `boolean` -| whether support iSCSI Discovery CHAP authentication - -| `chapAuthSession` -| `boolean` -| whether support iSCSI Session CHAP authentication - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi - -| `initiatorName` -| `string` -| Custom iSCSI Initiator Name. If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface <target portal>:<volume name> will be created for the connection. - -| `iqn` -| `string` -| Target iSCSI Qualified Name. - -| `iscsiInterface` -| `string` -| iSCSI Interface Name that uses an iSCSI transport. Defaults to 'default' (tcp). - -| `lun` -| `integer` -| iSCSI Target Lun number. - -| `portals` -| `array (string)` -| iSCSI Target Portal List. The Portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. - -| `secretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| CHAP Secret for iSCSI target and initiator authentication - -| `targetPortal` -| `string` -| iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -|=== - -[id="iscsivolumesource-core-v1"] -== ISCSIVolumeSource [core/v1] - - -Description:: - Represents an ISCSI disk. ISCSI volumes can only be mounted as read/write once. ISCSI volumes support ownership management and SELinux relabeling. - -Type:: - `object` - -Required:: - - `targetPortal` - - `iqn` - - `lun` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `chapAuthDiscovery` -| `boolean` -| whether support iSCSI Discovery CHAP authentication - -| `chapAuthSession` -| `boolean` -| whether support iSCSI Session CHAP authentication - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi - -| `initiatorName` -| `string` -| Custom iSCSI Initiator Name. If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface <target portal>:<volume name> will be created for the connection. - -| `iqn` -| `string` -| Target iSCSI Qualified Name. - -| `iscsiInterface` -| `string` -| iSCSI Interface Name that uses an iSCSI transport. Defaults to 'default' (tcp). - -| `lun` -| `integer` -| iSCSI Target Lun number. - -| `portals` -| `array (string)` -| iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. - -| `secretRef` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| CHAP Secret for iSCSI target and initiator authentication - -| `targetPortal` -| `string` -| iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -|=== - -[id="joblist-batch-v1"] -== JobList [batch/v1] - - -Description:: - JobList is a collection of jobs. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`array (Job batch/v1)`] -| items is the list of Jobs. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="keytopath-core-v1"] -== KeyToPath [core/v1] - - -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== - -[id="kubeapiserverlist-operator-openshift-io-v1"] -== KubeAPIServerList [operator.openshift.io/v1] - - -Description:: - KubeAPIServerList is a list of KubeAPIServer - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`array (KubeAPIServer operator.openshift.io/v1)`] -| List of kubeapiservers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="kubecontrollermanagerlist-operator-openshift-io-v1"] -== KubeControllerManagerList [operator.openshift.io/v1] - - -Description:: - KubeControllerManagerList is a list of KubeControllerManager - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`array (KubeControllerManager operator.openshift.io/v1)`] -| List of kubecontrollermanagers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="kubeletconfiglist-machineconfiguration-openshift-io-v1"] -== KubeletConfigList [machineconfiguration.openshift.io/v1] - - -Description:: - KubeletConfigList is a list of KubeletConfig - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../machine_apis/kubeletconfig-machineconfiguration-openshift-io-v1.adoc#kubeletconfig-machineconfiguration-openshift-io-v1[`array (KubeletConfig machineconfiguration.openshift.io/v1)`] -| List of kubeletconfigs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="kubeschedulerlist-operator-openshift-io-v1"] -== KubeSchedulerList [operator.openshift.io/v1] - - -Description:: - KubeSchedulerList is a list of KubeScheduler - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`array (KubeScheduler operator.openshift.io/v1)`] -| List of kubeschedulers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="kubestorageversionmigratorlist-operator-openshift-io-v1"] -== KubeStorageVersionMigratorList [operator.openshift.io/v1] - - -Description:: - KubeStorageVersionMigratorList is a list of KubeStorageVersionMigrator - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`array (KubeStorageVersionMigrator operator.openshift.io/v1)`] -| List of kubestorageversionmigrators. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="labelselector-meta-v1"] -== LabelSelector [meta/v1] - - -Description:: - A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| xref:../objects/index.adoc#labelselectorrequirement-meta-v1[`array (LabelSelectorRequirement meta/v1)`] -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== - -[id="labelselector_v2-meta-v1"] -== LabelSelector_v2 [meta/v1] - - -Description:: - A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| xref:../objects/index.adoc#labelselectorrequirement-meta-v1[`array (LabelSelectorRequirement meta/v1)`] -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== - -[id="labelselectorrequirement-meta-v1"] -== LabelSelectorRequirement [meta/v1] - - -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== - -[id="leaselist-coordination-k8s-io-v1"] -== LeaseList [coordination.k8s.io/v1] - - -Description:: - LeaseList is a list of Lease objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../metadata_apis/lease-coordination-k8s-io-v1.adoc#lease-coordination-k8s-io-v1[`array (Lease coordination.k8s.io/v1)`] -| Items is a list of schema objects. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="lifecycle-core-v1"] -== Lifecycle [core/v1] - - -Description:: - Lifecycle describes actions that the management system should take in response to container lifecycle events. For the PostStart and PreStop lifecycle handlers, management of the container blocks until the action is complete, unless the container process fails, in which case the handler is aborted. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| xref:../objects/index.adoc#handler-core-v1[`Handler core/v1`] -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| xref:../objects/index.adoc#handler-core-v1[`Handler core/v1`] -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== - -[id="limitrangeitem-core-v1"] -== LimitRangeItem [core/v1] - - -Description:: - LimitRangeItem defines a min/max usage limit for any resource that matches on kind. - -Type:: - `object` - -Required:: - - `type` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `default` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Default resource requirement limit value by resource name if resource limit is omitted. - -| `defaultRequest` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| DefaultRequest is the default resource requirement request value by resource name if resource request is omitted. - -| `max` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Max usage constraints on this kind by resource name. - -| `maxLimitRequestRatio` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| MaxLimitRequestRatio if specified, the named resource must have a request and limit that are both non-zero where limit divided by request is less than or equal to the enumerated value; this represents the max burst for the named resource. - -| `min` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Min usage constraints on this kind by resource name. - -| `type` -| `string` -| Type of resource that this limit applies to. - -|=== - -[id="limitrangelist-core-v1"] -== LimitRangeList [core/v1] - - -Description:: - LimitRangeList is a list of LimitRange items. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`array (LimitRange core/v1)`] -| Items is a list of LimitRange objects. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="listmeta-meta-v1"] -== ListMeta [meta/v1] - - -Description:: - ListMeta describes metadata that synthetic resources must have, including lists and various status objects. A resource may have only one of {ObjectMeta, ListMeta}. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `continue` -| `string` -| continue may be set if the user set a limit on the number of items returned, and indicates that the server has more data available. The value is opaque and may be used to issue another request to the endpoint that served this list to retrieve the next set of available objects. Continuing a consistent list may not be possible if the server configuration has changed or more than a few minutes have passed. The resourceVersion field returned when using this continue value will be identical to the value in the first response, unless you have received this token from an error message. - -| `remainingItemCount` -| `integer` -| remainingItemCount is the number of subsequent items in the list which are not included in this list response. If the list request contained label or field selectors, then the number of remaining items is unknown and the field will be left unset and omitted during serialization. If the list is complete (either because it is not chunking or because this is the last chunk), then there are no more remaining items and this field will be left unset and omitted during serialization. Servers older than v1.15 do not set this field. The intended use of the remainingItemCount is *estimating* the size of a collection. Clients should not rely on the remainingItemCount to be set or to be exact. - -| `resourceVersion` -| `string` -| String that identifies the server's internal version of this object that can be used by clients to determine when objects have changed. Value must be treated as opaque by clients and passed unmodified back to the server. Populated by the system. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `selfLink` -| `string` -| selfLink is a URL representing this object. Populated by the system. Read-only. - -DEPRECATED Kubernetes will stop propagating this field in 1.20 release and the field is planned to be removed in 1.21 release. - -|=== - -[id="loadbalanceringress-core-v1"] -== LoadBalancerIngress [core/v1] - - -Description:: - LoadBalancerIngress represents the status of a load-balancer ingress point: traffic intended for the service should be sent to an ingress point. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hostname` -| `string` -| Hostname is set for load-balancer ingress points that are DNS based (typically AWS load-balancers) - -| `ip` -| `string` -| IP is set for load-balancer ingress points that are IP based (typically GCE or OpenStack load-balancers) - -| `ports` -| xref:../objects/index.adoc#portstatus-core-v1[`array (PortStatus core/v1)`] -| Ports is a list of records of service ports If used, every port defined in the service should have an entry in it - -|=== - -[id="loadbalancerstatus-core-v1"] -== LoadBalancerStatus [core/v1] - - -Description:: - LoadBalancerStatus represents the status of a load-balancer. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ingress` -| xref:../objects/index.adoc#loadbalanceringress-core-v1[`array (LoadBalancerIngress core/v1)`] -| Ingress is a list containing ingress points for the load-balancer. Traffic intended for the service should be sent to these ingress points. - -|=== - -[id="localobjectreference-core-v1"] -== LocalObjectReference [core/v1] - - -Description:: - LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -|=== - -[id="localvolumesource-core-v1"] -== LocalVolumeSource [core/v1] - - -Description:: - Local represents directly-attached storage with node affinity (Beta feature) - -Type:: - `object` - -Required:: - - `path` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. It applies only when the Path is a block device. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". The default value is to auto-select a fileystem if unspecified. - -| `path` -| `string` -| The full path to the volume on the node. It can be either a directory or block device (disk, partition, ...). - -|=== - -[id="machineautoscalerlist-autoscaling-openshift-io-v1beta1"] -== MachineAutoscalerList [autoscaling.openshift.io/v1beta1] - - -Description:: - MachineAutoscalerList is a list of MachineAutoscaler - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../autoscale_apis/machineautoscaler-autoscaling-openshift-io-v1beta1.adoc#machineautoscaler-autoscaling-openshift-io-v1beta1[`array (MachineAutoscaler autoscaling.openshift.io/v1beta1)`] -| List of machineautoscalers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="machineconfiglist-machineconfiguration-openshift-io-v1"] -== MachineConfigList [machineconfiguration.openshift.io/v1] - - -Description:: - MachineConfigList is a list of MachineConfig - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../machine_apis/machineconfig-machineconfiguration-openshift-io-v1.adoc#machineconfig-machineconfiguration-openshift-io-v1[`array (MachineConfig machineconfiguration.openshift.io/v1)`] -| List of machineconfigs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="machineconfigpoollist-machineconfiguration-openshift-io-v1"] -== MachineConfigPoolList [machineconfiguration.openshift.io/v1] - - -Description:: - MachineConfigPoolList is a list of MachineConfigPool - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../machine_apis/machineconfigpool-machineconfiguration-openshift-io-v1.adoc#machineconfigpool-machineconfiguration-openshift-io-v1[`array (MachineConfigPool machineconfiguration.openshift.io/v1)`] -| List of machineconfigpools. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="machinehealthchecklist-machine-openshift-io-v1beta1"] -== MachineHealthCheckList [machine.openshift.io/v1beta1] - - -Description:: - MachineHealthCheckList is a list of MachineHealthCheck - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../machine_apis/machinehealthcheck-machine-openshift-io-v1beta1.adoc#machinehealthcheck-machine-openshift-io-v1beta1[`array (MachineHealthCheck machine.openshift.io/v1beta1)`] -| List of machinehealthchecks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="machinelist-machine-openshift-io-v1beta1"] -== MachineList [machine.openshift.io/v1beta1] - - -Description:: - MachineList is a list of Machine - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../machine_apis/machine-machine-openshift-io-v1beta1.adoc#machine-machine-openshift-io-v1beta1[`array (Machine machine.openshift.io/v1beta1)`] -| List of machines. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="machinesetlist-machine-openshift-io-v1beta1"] -== MachineSetList [machine.openshift.io/v1beta1] - - -Description:: - MachineSetList is a list of MachineSet - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../machine_apis/machineset-machine-openshift-io-v1beta1.adoc#machineset-machine-openshift-io-v1beta1[`array (MachineSet machine.openshift.io/v1beta1)`] -| List of machinesets. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="managedfieldsentry-meta-v1"] -== ManagedFieldsEntry [meta/v1] - - -Description:: - ManagedFieldsEntry is a workflow-id, a FieldSet and the group version of the resource that the fieldset applies to. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the version of this resource that this field set applies to. The format is "group/version" just like the top-level APIVersion field. It is necessary to track the version of a field set because it cannot be automatically converted. - -| `fieldsType` -| `string` -| FieldsType is the discriminator for the different fields format and version. There is currently only one possible value: "FieldsV1" - -| `fieldsV1` -| xref:../objects/index.adoc#fieldsv1-meta-v1[`FieldsV1 meta/v1`] -| FieldsV1 holds the first JSON version format as described in the "FieldsV1" type. - -| `manager` -| `string` -| Manager is an identifier of the workflow managing these fields. - -| `operation` -| `string` -| Operation is the type of operation which lead to this ManagedFieldsEntry being created. The only valid values for this field are 'Apply' and 'Update'. - -| `time` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Time is timestamp of when these fields were set. It should always be empty if Operation is 'Apply' - -|=== - -[id="microtime-meta-v1"] -== MicroTime [meta/v1] - - -Description:: - MicroTime is version of Time with microsecond level precision. - -Type:: - `string` - - - -[id="mutatingwebhookconfigurationlist-admissionregistration-k8s-io-v1"] -== MutatingWebhookConfigurationList [admissionregistration.k8s.io/v1] - - -Description:: - MutatingWebhookConfigurationList is a list of MutatingWebhookConfiguration. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../extension_apis/mutatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#mutatingwebhookconfiguration-admissionregistration-k8s-io-v1[`array (MutatingWebhookConfiguration admissionregistration.k8s.io/v1)`] -| List of MutatingWebhookConfiguration. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="namespacecondition-core-v1"] -== NamespaceCondition [core/v1] - - -Description:: - NamespaceCondition contains details about state of namespace. - -Type:: - `object` - -Required:: - - `type` - - `status` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of namespace controller condition. - -|=== - -[id="namespacelist-core-v1"] -== NamespaceList [core/v1] - - -Description:: - NamespaceList is a list of Namespaces. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../metadata_apis/namespace-core-v1.adoc#namespace-core-v1[`array (Namespace core/v1)`] -| Items is the list of Namespace objects in the list. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="netnamespacelist-network-openshift-io-v1"] -== NetNamespaceList [network.openshift.io/v1] - - -Description:: - NetNamespaceList is a list of NetNamespace - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/netnamespace-network-openshift-io-v1.adoc#netnamespace-network-openshift-io-v1[`array (NetNamespace network.openshift.io/v1)`] -| List of netnamespaces. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="networkattachmentdefinitionlist-k8s-cni-cncf-io-v1"] -== NetworkAttachmentDefinitionList [k8s.cni.cncf.io/v1] - - -Description:: - NetworkAttachmentDefinitionList is a list of NetworkAttachmentDefinition - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/networkattachmentdefinition-k8s-cni-cncf-io-v1.adoc#networkattachmentdefinition-k8s-cni-cncf-io-v1[`array (NetworkAttachmentDefinition k8s.cni.cncf.io/v1)`] -| List of network-attachment-definitions. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="networklist-config-openshift-io-v1"] -== NetworkList [config.openshift.io/v1] - - -Description:: - NetworkList is a list of Network - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/network-config-openshift-io-v1.adoc#network-config-openshift-io-v1[`array (Network config.openshift.io/v1)`] -| List of networks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="networklist-operator-openshift-io-v1"] -== NetworkList [operator.openshift.io/v1] - - -Description:: - NetworkList is a list of Network - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`array (Network operator.openshift.io/v1)`] -| List of networks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="networkpolicylist-networking-k8s-io-v1"] -== NetworkPolicyList [networking.k8s.io/v1] - - -Description:: - NetworkPolicyList is a list of NetworkPolicy objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/networkpolicy-networking-k8s-io-v1.adoc#networkpolicy-networking-k8s-io-v1[`array (NetworkPolicy networking.k8s.io/v1)`] -| Items is a list of schema objects. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="nfsvolumesource-core-v1"] -== NFSVolumeSource [core/v1] - - -Description:: - Represents an NFS mount that lasts the lifetime of a pod. NFS volumes do not support ownership management or SELinux relabeling. - -Type:: - `object` - -Required:: - - `server` - - `path` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path that is exported by the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `readOnly` -| `boolean` -| ReadOnly here will force the NFS export to be mounted with read-only permissions. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `server` -| `string` -| Server is the hostname or IP address of the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -|=== - -[id="nodeaddress-core-v1"] -== NodeAddress [core/v1] - - -Description:: - NodeAddress contains information for the node's address. - -Type:: - `object` - -Required:: - - `type` - - `address` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `address` -| `string` -| The node address. - -| `type` -| `string` -| Node address type, one of Hostname, ExternalIP or InternalIP. - -|=== - -[id="nodeaffinity-core-v1"] -== NodeAffinity [core/v1] - - -Description:: - Node affinity is a group of node affinity scheduling rules. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| xref:../objects/index.adoc#preferredschedulingterm-core-v1[`array (PreferredSchedulingTerm core/v1)`] -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -| `requiredDuringSchedulingIgnoredDuringExecution` -| xref:../objects/index.adoc#nodeselector-core-v1[`NodeSelector core/v1`] -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -|=== - -[id="nodecondition-core-v1"] -== NodeCondition [core/v1] - - -Description:: - NodeCondition contains condition information for a node. - -Type:: - `object` - -Required:: - - `type` - - `status` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastHeartbeatTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time we got an update on a given condition. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of node condition. - -|=== - -[id="nodeconfigsource-core-v1"] -== NodeConfigSource [core/v1] - - -Description:: - NodeConfigSource specifies a source of node configuration. Exactly one subfield (excluding metadata) must be non-nil. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| xref:../objects/index.adoc#configmapnodeconfigsource-core-v1[`ConfigMapNodeConfigSource core/v1`] -| ConfigMap is a reference to a Node's ConfigMap - -|=== - -[id="nodedaemonendpoints-core-v1"] -== NodeDaemonEndpoints [core/v1] - - -Description:: - NodeDaemonEndpoints lists ports opened by daemons running on the Node. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kubeletEndpoint` -| xref:../objects/index.adoc#daemonendpoint-core-v1[`DaemonEndpoint core/v1`] -| Endpoint on which Kubelet is listening. - -|=== - -[id="nodelist-core-v1"] -== NodeList [core/v1] - - -Description:: - NodeList is the whole list of all Nodes which have been registered with master. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../node_apis/node-core-v1.adoc#node-core-v1[`array (Node core/v1)`] -| List of nodes - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="nodeselector-core-v1"] -== NodeSelector [core/v1] - - -Description:: - A node selector represents the union of the results of one or more label queries over a set of nodes; that is, it represents the OR of the selectors represented by the node selector terms. - -Type:: - `object` - -Required:: - - `nodeSelectorTerms` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelectorTerms` -| xref:../objects/index.adoc#nodeselectorterm-core-v1[`array (NodeSelectorTerm core/v1)`] -| Required. A list of node selector terms. The terms are ORed. - -|=== - -[id="nodeselectorrequirement-core-v1"] -== NodeSelectorRequirement [core/v1] - - -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== - -[id="nodeselectorterm-core-v1"] -== NodeSelectorTerm [core/v1] - - -Description:: - A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| xref:../objects/index.adoc#nodeselectorrequirement-core-v1[`array (NodeSelectorRequirement core/v1)`] -| A list of node selector requirements by node's labels. - -| `matchFields` -| xref:../objects/index.adoc#nodeselectorrequirement-core-v1[`array (NodeSelectorRequirement core/v1)`] -| A list of node selector requirements by node's fields. - -|=== - -[id="nodesysteminfo-core-v1"] -== NodeSystemInfo [core/v1] - - -Description:: - NodeSystemInfo is a set of ids/uuids to uniquely identify the node. - -Type:: - `object` - -Required:: - - `machineID` - - `systemUUID` - - `bootID` - - `kernelVersion` - - `osImage` - - `containerRuntimeVersion` - - `kubeletVersion` - - `kubeProxyVersion` - - `operatingSystem` - - `architecture` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `architecture` -| `string` -| The Architecture reported by the node - -| `bootID` -| `string` -| Boot ID reported by the node. - -| `containerRuntimeVersion` -| `string` -| ContainerRuntime Version reported by the node through runtime remote API (e.g. docker://1.5.0). - -| `kernelVersion` -| `string` -| Kernel Version reported by the node from 'uname -r' (e.g. 3.16.0-0.bpo.4-amd64). - -| `kubeProxyVersion` -| `string` -| KubeProxy Version reported by the node. - -| `kubeletVersion` -| `string` -| Kubelet Version reported by the node. - -| `machineID` -| `string` -| MachineID reported by the node. For unique machine identification in the cluster this field is preferred. Learn more from man(5) machine-id: http://man7.org/linux/man-pages/man5/machine-id.5.html - -| `operatingSystem` -| `string` -| The Operating System reported by the node - -| `osImage` -| `string` -| OS Image reported by the node from /etc/os-release (e.g. Debian GNU/Linux 7 (wheezy)). - -| `systemUUID` -| `string` -| SystemUUID reported by the node. For unique machine identification MachineID is preferred. This field is specific to Red Hat hosts https://access.redhat.com/documentation/en-us/red_hat_subscription_management/1/html/rhsm/uuid - -|=== - -[id="oauthaccesstokenlist-oauth-openshift-io-v1"] -== OAuthAccessTokenList [oauth.openshift.io/v1] - - -Description:: - OAuthAccessTokenList is a collection of OAuth access tokens - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../oauth_apis/oauthaccesstoken-oauth-openshift-io-v1.adoc#oauthaccesstoken-oauth-openshift-io-v1[`array (OAuthAccessToken oauth.openshift.io/v1)`] -| Items is the list of OAuth access tokens - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="oauthauthorizetokenlist-oauth-openshift-io-v1"] -== OAuthAuthorizeTokenList [oauth.openshift.io/v1] - - -Description:: - OAuthAuthorizeTokenList is a collection of OAuth authorization tokens - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../oauth_apis/oauthauthorizetoken-oauth-openshift-io-v1.adoc#oauthauthorizetoken-oauth-openshift-io-v1[`array (OAuthAuthorizeToken oauth.openshift.io/v1)`] -| Items is the list of OAuth authorization tokens - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="oauthclientauthorizationlist-oauth-openshift-io-v1"] -== OAuthClientAuthorizationList [oauth.openshift.io/v1] - - -Description:: - OAuthClientAuthorizationList is a collection of OAuth client authorizations - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../oauth_apis/oauthclientauthorization-oauth-openshift-io-v1.adoc#oauthclientauthorization-oauth-openshift-io-v1[`array (OAuthClientAuthorization oauth.openshift.io/v1)`] -| Items is the list of OAuth client authorizations - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="oauthclientlist-oauth-openshift-io-v1"] -== OAuthClientList [oauth.openshift.io/v1] - - -Description:: - OAuthClientList is a collection of OAuth clients - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[`array (OAuthClient oauth.openshift.io/v1)`] -| Items is the list of OAuth clients - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="oauthlist-config-openshift-io-v1"] -== OAuthList [config.openshift.io/v1] - - -Description:: - OAuthList is a list of OAuth - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/oauth-config-openshift-io-v1.adoc#oauth-config-openshift-io-v1[`array (OAuth config.openshift.io/v1)`] -| List of oauths. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="objectfieldselector-core-v1"] -== ObjectFieldSelector [core/v1] - - -Description:: - ObjectFieldSelector selects an APIVersioned field of an object. - -Type:: - `object` - -Required:: - - `fieldPath` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== - -[id="objectmeta-meta-v1"] -== ObjectMeta [meta/v1] - - -Description:: - ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `clusterName` -| `string` -| The name of the cluster which the object belongs to. This is used to distinguish resources with same name and namespace in different clusters. This field is not set anywhere right now and apiserver is going to ignore it if set in create or update request. - -| `creationTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| CreationTimestamp is a timestamp representing the server time when this object was created. It is not guaranteed to be set in happens-before order across separate operations. Clients may not set this value. It is represented in RFC3339 form and is in UTC. - -Populated by the system. Read-only. Null for lists. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `deletionGracePeriodSeconds` -| `integer` -| Number of seconds allowed for this object to gracefully terminate before it will be removed from the system. Only set when deletionTimestamp is also set. May only be shortened. Read-only. - -| `deletionTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| DeletionTimestamp is RFC 3339 date and time at which this resource will be deleted. This field is set by the server when a graceful deletion is requested by the user, and is not directly settable by a client. The resource is expected to be deleted (no longer visible from resource lists, and not reachable by name) after the time in this field, once the finalizers list is empty. As long as the finalizers list contains items, deletion is blocked. Once the deletionTimestamp is set, this value may not be unset or be set further into the future, although it may be shortened or the resource may be deleted prior to this time. For example, a user may request that a pod is deleted in 30 seconds. The Kubelet will react by sending a graceful termination signal to the containers in the pod. After that 30 seconds, the Kubelet will send a hard termination signal (SIGKILL) to the container and after cleanup, remove the pod from the API. In the presence of network partitions, this object may still exist after this timestamp, until an administrator or automated process can determine the resource is fully terminated. If not set, graceful deletion of the object has not been requested. - -Populated by the system when a graceful deletion is requested. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `finalizers` -| `array (string)` -| Must be empty before the object is deleted from the registry. Each entry is an identifier for the responsible component that will remove the entry from the list. If the deletionTimestamp of the object is non-nil, entries in this list can only be removed. Finalizers may be processed and removed in any order. Order is NOT enforced because it introduces significant risk of stuck finalizers. finalizers is a shared field, any actor with permission can reorder it. If the finalizer list is processed in order, then this can lead to a situation in which the component responsible for the first finalizer in the list is waiting for a signal (field value, external system, or other) produced by a component responsible for a finalizer later in the list, resulting in a deadlock. Without enforced ordering finalizers are free to order amongst themselves and are not vulnerable to ordering changes in the list. - -| `generateName` -| `string` -| GenerateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. The provided value has the same validation rules as the Name field, and may be truncated by the length of the suffix required to make the value unique on the server. - -If this field is specified and the generated name exists, the server will NOT return a 409 - instead, it will either return 201 Created or 500 with Reason ServerTimeout indicating a unique name could not be found in the time allotted, and the client should retry (optionally after the time indicated in the Retry-After header). - -Applied only if Name is not specified. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#idempotency - -| `generation` -| `integer` -| A sequence number representing a specific generation of the desired state. Populated by the system. Read-only. - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `managedFields` -| xref:../objects/index.adoc#managedfieldsentry-meta-v1[`array (ManagedFieldsEntry meta/v1)`] -| ManagedFields maps workflow-id and version to the set of fields that are managed by that workflow. This is mostly for internal housekeeping, and users typically shouldn't need to set or understand this field. A workflow can be the user's name, a controller's name, or the name of a specific apply path like "ci-cd". The set of fields is always in the version that the workflow used when modifying the object. - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `namespace` -| `string` -| Namespace defines the space within which each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. - -Must be a DNS_LABEL. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/namespaces - -| `ownerReferences` -| xref:../objects/index.adoc#ownerreference-meta-v1[`array (OwnerReference meta/v1)`] -| List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. - -| `resourceVersion` -| `string` -| An opaque value that represents the internal version of this object that can be used by clients to determine when objects have changed. May be used for optimistic concurrency, change detection, and the watch operation on a resource or set of resources. Clients must treat these values as opaque and passed unmodified back to the server. They may only be valid for a particular resource or set of resources. - -Populated by the system. Read-only. Value must be treated as opaque by clients and . More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `selfLink` -| `string` -| SelfLink is a URL representing this object. Populated by the system. Read-only. - -DEPRECATED Kubernetes will stop propagating this field in 1.20 release and the field is planned to be removed in 1.21 release. - -| `uid` -| `string` -| UID is the unique in time and space value for this object. It is typically generated by the server on successful creation of a resource and is not allowed to change on PUT operations. - -Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-guide/identifiers#uids - -|=== - -[id="objectmeta_v2-meta-v1"] -== ObjectMeta_v2 [meta/v1] - - -Description:: - ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations - -| `clusterName` -| `string` -| The name of the cluster which the object belongs to. This is used to distinguish resources with same name and namespace in different clusters. This field is not set anywhere right now and apiserver is going to ignore it if set in create or update request. - -| `creationTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| CreationTimestamp is a timestamp representing the server time when this object was created. It is not guaranteed to be set in happens-before order across separate operations. Clients may not set this value. It is represented in RFC3339 form and is in UTC. - -Populated by the system. Read-only. Null for lists. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `deletionGracePeriodSeconds` -| `integer` -| Number of seconds allowed for this object to gracefully terminate before it will be removed from the system. Only set when deletionTimestamp is also set. May only be shortened. Read-only. - -| `deletionTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| DeletionTimestamp is RFC 3339 date and time at which this resource will be deleted. This field is set by the server when a graceful deletion is requested by the user, and is not directly settable by a client. The resource is expected to be deleted (no longer visible from resource lists, and not reachable by name) after the time in this field, once the finalizers list is empty. As long as the finalizers list contains items, deletion is blocked. Once the deletionTimestamp is set, this value may not be unset or be set further into the future, although it may be shortened or the resource may be deleted prior to this time. For example, a user may request that a pod is deleted in 30 seconds. The Kubelet will react by sending a graceful termination signal to the containers in the pod. After that 30 seconds, the Kubelet will send a hard termination signal (SIGKILL) to the container and after cleanup, remove the pod from the API. In the presence of network partitions, this object may still exist after this timestamp, until an administrator or automated process can determine the resource is fully terminated. If not set, graceful deletion of the object has not been requested. - -Populated by the system when a graceful deletion is requested. Read-only. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `finalizers` -| `array (string)` -| Must be empty before the object is deleted from the registry. Each entry is an identifier for the responsible component that will remove the entry from the list. If the deletionTimestamp of the object is non-nil, entries in this list can only be removed. Finalizers may be processed and removed in any order. Order is NOT enforced because it introduces significant risk of stuck finalizers. finalizers is a shared field, any actor with permission can reorder it. If the finalizer list is processed in order, then this can lead to a situation in which the component responsible for the first finalizer in the list is waiting for a signal (field value, external system, or other) produced by a component responsible for a finalizer later in the list, resulting in a deadlock. Without enforced ordering finalizers are free to order amongst themselves and are not vulnerable to ordering changes in the list. - -| `generateName` -| `string` -| GenerateName is an optional prefix, used by the server, to generate a unique name ONLY IF the Name field has not been provided. If this field is used, the name returned to the client will be different than the name passed. This value will also be combined with a unique suffix. The provided value has the same validation rules as the Name field, and may be truncated by the length of the suffix required to make the value unique on the server. - -If this field is specified and the generated name exists, the server will NOT return a 409 - instead, it will either return 201 Created or 500 with Reason ServerTimeout indicating a unique name could not be found in the time allotted, and the client should retry (optionally after the time indicated in the Retry-After header). - -Applied only if Name is not specified. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#idempotency - -| `generation` -| `integer` -| A sequence number representing a specific generation of the desired state. Populated by the system. Read-only. - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels - -| `managedFields` -| xref:../objects/index.adoc#managedfieldsentry-meta-v1[`array (ManagedFieldsEntry meta/v1)`] -| ManagedFields maps workflow-id and version to the set of fields that are managed by that workflow. This is mostly for internal housekeeping, and users typically shouldn't need to set or understand this field. A workflow can be the user's name, a controller's name, or the name of a specific apply path like "ci-cd". The set of fields is always in the version that the workflow used when modifying the object. - -| `name` -| `string` -| Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `namespace` -| `string` -| Namespace defines the space within which each name must be unique. An empty namespace is equivalent to the "default" namespace, but "default" is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. - -Must be a DNS_LABEL. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/namespaces - -| `ownerReferences` -| xref:../objects/index.adoc#ownerreference_v2-meta-v1[`array (OwnerReference_v2 meta/v1)`] -| List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller. - -| `resourceVersion` -| `string` -| An opaque value that represents the internal version of this object that can be used by clients to determine when objects have changed. May be used for optimistic concurrency, change detection, and the watch operation on a resource or set of resources. Clients must treat these values as opaque and passed unmodified back to the server. They may only be valid for a particular resource or set of resources. - -Populated by the system. Read-only. Value must be treated as opaque by clients and . More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `selfLink` -| `string` -| SelfLink is a URL representing this object. Populated by the system. Read-only. - -DEPRECATED Kubernetes will stop propagating this field in 1.20 release and the field is planned to be removed in 1.21 release. - -| `uid` -| `string` -| UID is the unique in time and space value for this object. It is typically generated by the server on successful creation of a resource and is not allowed to change on PUT operations. - -Populated by the system. Read-only. More info: http://kubernetes.io/docs/user-guide/identifiers#uids - -|=== - -[id="objectreference-core-v1"] -== ObjectReference [core/v1] - - -Description:: - ObjectReference contains enough information to let you inspect or modify the referred object. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== - -[id="openshiftapiserverlist-operator-openshift-io-v1"] -== OpenShiftAPIServerList [operator.openshift.io/v1] - - -Description:: - OpenShiftAPIServerList is a list of OpenShiftAPIServer - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`array (OpenShiftAPIServer operator.openshift.io/v1)`] -| List of openshiftapiservers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="openshiftcontrollermanagerlist-operator-openshift-io-v1"] -== OpenShiftControllerManagerList [operator.openshift.io/v1] - - -Description:: - OpenShiftControllerManagerList is a list of OpenShiftControllerManager - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`array (OpenShiftControllerManager operator.openshift.io/v1)`] -| List of openshiftcontrollermanagers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="operatorconditionlist-operators-coreos-com-v1"] -== OperatorConditionList [operators.coreos.com/v1] - - -Description:: - OperatorConditionList is a list of OperatorCondition - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`array (OperatorCondition operators.coreos.com/v1)`] -| List of operatorconditions. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="operatorgrouplist-operators-coreos-com-v1"] -== OperatorGroupList [operators.coreos.com/v1] - - -Description:: - OperatorGroupList is a list of OperatorGroup - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`array (OperatorGroup operators.coreos.com/v1)`] -| List of operatorgroups. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="operatorhublist-config-openshift-io-v1"] -== OperatorHubList [config.openshift.io/v1] - - -Description:: - OperatorHubList is a list of OperatorHub - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/operatorhub-config-openshift-io-v1.adoc#operatorhub-config-openshift-io-v1[`array (OperatorHub config.openshift.io/v1)`] -| List of operatorhubs. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="operatorlist-operators-coreos-com-v1"] -== OperatorList [operators.coreos.com/v1] - - -Description:: - OperatorList is a list of Operator - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`array (Operator operators.coreos.com/v1)`] -| List of operators. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="operatorpkilist-network-operator-openshift-io-v1"] -== OperatorPKIList [network.operator.openshift.io/v1] - - -Description:: - OperatorPKIList is a list of OperatorPKI - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`array (OperatorPKI network.operator.openshift.io/v1)`] -| List of operatorpkis. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="ownerreference-meta-v1"] -== OwnerReference [meta/v1] - - -Description:: - OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field. - -Type:: - `object` - -Required:: - - `apiVersion` - - `kind` - - `name` - - `uid` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `blockOwnerDeletion` -| `boolean` -| If true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed. Defaults to false. To set this field, a user needs "delete" permission of the owner, otherwise 422 (Unprocessable Entity) will be returned. - -| `controller` -| `boolean` -| If true, this reference points to the managing controller. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `uid` -| `string` -| UID of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#uids - -|=== - -[id="ownerreference_v2-meta-v1"] -== OwnerReference_v2 [meta/v1] - - -Description:: - OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field. - -Type:: - `object` - -Required:: - - `apiVersion` - - `kind` - - `name` - - `uid` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `blockOwnerDeletion` -| `boolean` -| If true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed. Defaults to false. To set this field, a user needs "delete" permission of the owner, otherwise 422 (Unprocessable Entity) will be returned. - -| `controller` -| `boolean` -| If true, this reference points to the managing controller. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#names - -| `uid` -| `string` -| UID of the referent. More info: http://kubernetes.io/docs/user-guide/identifiers#uids - -|=== - -[id="packagemanifestlist-packages-operators-coreos-com-v1"] -== PackageManifestList [packages.operators.coreos.com/v1] - - -Description:: - PackageManifestList is a list of PackageManifest objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operatorhub_apis/packagemanifest-packages-operators-coreos-com-v1.adoc#packagemanifest-packages-operators-coreos-com-v1[`array (PackageManifest packages.operators.coreos.com/v1)`] -| - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="patch-meta-v1"] -== Patch [meta/v1] - - -Description:: - Patch is provided to give a concrete name and type to the Kubernetes PATCH request body. - -Type:: - `object` - - - -[id="persistentvolumeclaim-core-v1"] -== PersistentVolumeClaim [core/v1] - - -Description:: - PersistentVolumeClaim is a user's request for and claim to a persistent volume - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| PersistentVolumeClaimSpec describes the common attributes of storage devices and allows a Source for provider-specific attributes - -| `status` -| `object` -| PersistentVolumeClaimStatus is the current status of a persistent volume claim. - -|=== -..spec -Description:: - PersistentVolumeClaimSpec describes the common attributes of storage devices and allows a Source for provider-specific attributes - -Type:: - `object` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `dataSource` -| xref:../objects/index.adoc#typedlocalobjectreference-core-v1[`TypedLocalObjectReference core/v1`] -| This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) * An existing PVC (PersistentVolumeClaim) * An existing custom resource that implements data population (Alpha) In order to use custom resource types that implement data population, the AnyVolumeDataSource feature gate must be enabled. If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. - -| `resources` -| xref:../objects/index.adoc#resourcerequirements-core-v1[`ResourceRequirements core/v1`] -| Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| A label query over volumes to consider for binding. - -| `storageClassName` -| `string` -| Name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 - -| `volumeMode` -| `string` -| volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. - -| `volumeName` -| `string` -| VolumeName is the binding reference to the PersistentVolume backing this claim. - -|=== -..status -Description:: - PersistentVolumeClaimStatus is the current status of a persistent volume claim. - -Type:: - `object` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the actual access modes the volume backing the PVC has. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `capacity` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Represents the actual resources of the underlying volume. - -| `conditions` -| xref:../objects/index.adoc#persistentvolumeclaimcondition-core-v1[`array (PersistentVolumeClaimCondition core/v1)`] -| Current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'. - -| `phase` -| `string` -| Phase represents the current phase of PersistentVolumeClaim. - -|=== - -[id="persistentvolumeclaimcondition-core-v1"] -== PersistentVolumeClaimCondition [core/v1] - - -Description:: - PersistentVolumeClaimCondition contails details about state of pvc - -Type:: - `object` - -Required:: - - `type` - - `status` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time we probed the condition. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| Human-readable message indicating details about last transition. - -| `reason` -| `string` -| Unique, this should be a short, machine understandable string that gives the reason for condition's last transition. If it reports "ResizeStarted" that means the underlying persistent volume is being resized. - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== - -[id="persistentvolumeclaimlist-core-v1"] -== PersistentVolumeClaimList [core/v1] - - -Description:: - PersistentVolumeClaimList is a list of PersistentVolumeClaim items. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`array (PersistentVolumeClaim core/v1)`] -| A list of persistent volume claims. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="persistentvolumeclaimspec-core-v1"] -== PersistentVolumeClaimSpec [core/v1] - - -Description:: - PersistentVolumeClaimSpec describes the common attributes of storage devices and allows a Source for provider-specific attributes - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `dataSource` -| xref:../objects/index.adoc#typedlocalobjectreference-core-v1[`TypedLocalObjectReference core/v1`] -| This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) * An existing PVC (PersistentVolumeClaim) * An existing custom resource that implements data population (Alpha) In order to use custom resource types that implement data population, the AnyVolumeDataSource feature gate must be enabled. If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. - -| `resources` -| xref:../objects/index.adoc#resourcerequirements-core-v1[`ResourceRequirements core/v1`] -| Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| A label query over volumes to consider for binding. - -| `storageClassName` -| `string` -| Name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 - -| `volumeMode` -| `string` -| volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. - -| `volumeName` -| `string` -| VolumeName is the binding reference to the PersistentVolume backing this claim. - -|=== - -[id="persistentvolumeclaimtemplate-core-v1"] -== PersistentVolumeClaimTemplate [core/v1] - - -Description:: - PersistentVolumeClaimTemplate is used to produce PersistentVolumeClaim objects as part of an EphemeralVolumeSource. - -Type:: - `object` - -Required:: - - `spec` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| May contain labels and annotations that will be copied into the PVC when creating it. No other fields are allowed and will be rejected during validation. - -| `spec` -| xref:../objects/index.adoc#persistentvolumeclaimspec-core-v1[`PersistentVolumeClaimSpec core/v1`] -| The specification for the PersistentVolumeClaim. The entire content is copied unchanged into the PVC that gets created from this template. The same fields as in a PersistentVolumeClaim are also valid here. - -|=== - -[id="persistentvolumeclaimvolumesource-core-v1"] -== PersistentVolumeClaimVolumeSource [core/v1] - - -Description:: - PersistentVolumeClaimVolumeSource references the user's PVC in the same namespace. This volume finds the bound PV and mounts that volume for the pod. A PersistentVolumeClaimVolumeSource is, essentially, a wrapper around another type of volume that is owned by someone else (the system). - -Type:: - `object` - -Required:: - - `claimName` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `claimName` -| `string` -| ClaimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `readOnly` -| `boolean` -| Will force the ReadOnly setting in VolumeMounts. Default false. - -|=== - -[id="persistentvolumelist-core-v1"] -== PersistentVolumeList [core/v1] - - -Description:: - PersistentVolumeList is a list of PersistentVolume items. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`array (PersistentVolume core/v1)`] -| List of persistent volumes. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="persistentvolumespec-core-v1"] -== PersistentVolumeSpec [core/v1] - - -Description:: - PersistentVolumeSpec is the specification of a persistent volume. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains all ways the volume can be mounted. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes - -| `awsElasticBlockStore` -| xref:../objects/index.adoc#awselasticblockstorevolumesource-core-v1[`AWSElasticBlockStoreVolumeSource core/v1`] -| AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `azureDisk` -| xref:../objects/index.adoc#azurediskvolumesource-core-v1[`AzureDiskVolumeSource core/v1`] -| AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -| `azureFile` -| xref:../objects/index.adoc#azurefilepersistentvolumesource-core-v1[`AzureFilePersistentVolumeSource core/v1`] -| AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -| `capacity` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| A description of the persistent volume's resources and capacity. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#capacity - -| `cephfs` -| xref:../objects/index.adoc#cephfspersistentvolumesource-core-v1[`CephFSPersistentVolumeSource core/v1`] -| CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -| `cinder` -| xref:../objects/index.adoc#cinderpersistentvolumesource-core-v1[`CinderPersistentVolumeSource core/v1`] -| Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `claimRef` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| ClaimRef is part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound. claim.VolumeName is the authoritative bind between PV and PVC. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#binding - -| `csi` -| xref:../objects/index.adoc#csipersistentvolumesource-core-v1[`CSIPersistentVolumeSource core/v1`] -| CSI represents storage that is handled by an external CSI driver (Beta feature). - -| `fc` -| xref:../objects/index.adoc#fcvolumesource-core-v1[`FCVolumeSource core/v1`] -| FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -| `flexVolume` -| xref:../objects/index.adoc#flexpersistentvolumesource-core-v1[`FlexPersistentVolumeSource core/v1`] -| FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -| `flocker` -| xref:../objects/index.adoc#flockervolumesource-core-v1[`FlockerVolumeSource core/v1`] -| Flocker represents a Flocker volume attached to a kubelet's host machine and exposed to the pod for its usage. This depends on the Flocker control service being running - -| `gcePersistentDisk` -| xref:../objects/index.adoc#gcepersistentdiskvolumesource-core-v1[`GCEPersistentDiskVolumeSource core/v1`] -| GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. Provisioned by an admin. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `glusterfs` -| xref:../objects/index.adoc#glusterfspersistentvolumesource-core-v1[`GlusterfsPersistentVolumeSource core/v1`] -| Glusterfs represents a Glusterfs volume that is attached to a host and exposed to the pod. Provisioned by an admin. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -| `hostPath` -| xref:../objects/index.adoc#hostpathvolumesource-core-v1[`HostPathVolumeSource core/v1`] -| HostPath represents a directory on the host. Provisioned by a developer or tester. This is useful for single-node development and testing only! On-host storage is not supported in any way and WILL NOT WORK in a multi-node cluster. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `iscsi` -| xref:../objects/index.adoc#iscsipersistentvolumesource-core-v1[`ISCSIPersistentVolumeSource core/v1`] -| ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. Provisioned by an admin. - -| `local` -| xref:../objects/index.adoc#localvolumesource-core-v1[`LocalVolumeSource core/v1`] -| Local represents directly-attached storage with node affinity - -| `mountOptions` -| `array (string)` -| A list of mount options, e.g. ["ro", "soft"]. Not validated - mount will simply fail if one is invalid. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#mount-options - -| `nfs` -| xref:../objects/index.adoc#nfsvolumesource-core-v1[`NFSVolumeSource core/v1`] -| NFS represents an NFS mount on the host. Provisioned by an admin. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `nodeAffinity` -| xref:../objects/index.adoc#volumenodeaffinity-core-v1[`VolumeNodeAffinity core/v1`] -| NodeAffinity defines constraints that limit what nodes this volume can be accessed from. This field influences the scheduling of pods that use this volume. - -| `persistentVolumeReclaimPolicy` -| `string` -| What happens to a persistent volume when released from its claim. Valid options are Retain (default for manually created PersistentVolumes), Delete (default for dynamically provisioned PersistentVolumes), and Recycle (deprecated). Recycle must be supported by the volume plugin underlying this PersistentVolume. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#reclaiming - -| `photonPersistentDisk` -| xref:../objects/index.adoc#photonpersistentdiskvolumesource-core-v1[`PhotonPersistentDiskVolumeSource core/v1`] -| PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -| `portworxVolume` -| xref:../objects/index.adoc#portworxvolumesource-core-v1[`PortworxVolumeSource core/v1`] -| PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -| `quobyte` -| xref:../objects/index.adoc#quobytevolumesource-core-v1[`QuobyteVolumeSource core/v1`] -| Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -| `rbd` -| xref:../objects/index.adoc#rbdpersistentvolumesource-core-v1[`RBDPersistentVolumeSource core/v1`] -| RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -| `scaleIO` -| xref:../objects/index.adoc#scaleiopersistentvolumesource-core-v1[`ScaleIOPersistentVolumeSource core/v1`] -| ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -| `storageClassName` -| `string` -| Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass. - -| `storageos` -| xref:../objects/index.adoc#storageospersistentvolumesource-core-v1[`StorageOSPersistentVolumeSource core/v1`] -| StorageOS represents a StorageOS volume that is attached to the kubelet's host machine and mounted into the pod More info: https://examples.k8s.io/volumes/storageos/README.md - -| `volumeMode` -| `string` -| volumeMode defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec. - -| `vsphereVolume` -| xref:../objects/index.adoc#vspherevirtualdiskvolumesource-core-v1[`VsphereVirtualDiskVolumeSource core/v1`] -| VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -|=== - -[id="photonpersistentdiskvolumesource-core-v1"] -== PhotonPersistentDiskVolumeSource [core/v1] - - -Description:: - Represents a Photon Controller persistent disk resource. - -Type:: - `object` - -Required:: - - `pdID` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `pdID` -| `string` -| ID that identifies Photon Controller persistent disk - -|=== - -[id="podaffinity-core-v1"] -== PodAffinity [core/v1] - - -Description:: - Pod affinity is a group of inter pod affinity scheduling rules. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| xref:../objects/index.adoc#weightedpodaffinityterm-core-v1[`array (WeightedPodAffinityTerm core/v1)`] -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `requiredDuringSchedulingIgnoredDuringExecution` -| xref:../objects/index.adoc#podaffinityterm-core-v1[`array (PodAffinityTerm core/v1)`] -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -|=== - -[id="podaffinityterm-core-v1"] -== PodAffinityTerm [core/v1] - - -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== - -[id="podantiaffinity-core-v1"] -== PodAntiAffinity [core/v1] - - -Description:: - Pod anti affinity is a group of inter pod anti affinity scheduling rules. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| xref:../objects/index.adoc#weightedpodaffinityterm-core-v1[`array (WeightedPodAffinityTerm core/v1)`] -| The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `requiredDuringSchedulingIgnoredDuringExecution` -| xref:../objects/index.adoc#podaffinityterm-core-v1[`array (PodAffinityTerm core/v1)`] -| If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -|=== - -[id="podcondition-core-v1"] -== PodCondition [core/v1] - - -Description:: - PodCondition contains details for the current condition of this pod. - -Type:: - `object` - -Required:: - - `type` - - `status` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time we probed the condition. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| Human-readable message indicating details about last transition. - -| `reason` -| `string` -| Unique, one-word, CamelCase reason for the condition's last transition. - -| `status` -| `string` -| Status is the status of the condition. Can be True, False, Unknown. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-conditions - -| `type` -| `string` -| Type is the type of the condition. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-conditions - -|=== - -[id="poddisruptionbudgetlist-policy-v1beta1"] -== PodDisruptionBudgetList [policy/v1beta1] - - -Description:: - PodDisruptionBudgetList is a collection of PodDisruptionBudgets. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`array (PodDisruptionBudget policy/v1beta1)`] -| - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="poddnsconfig-core-v1"] -== PodDNSConfig [core/v1] - - -Description:: - PodDNSConfig defines the DNS parameters of a pod in addition to those generated from DNSPolicy. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nameservers` -| `array (string)` -| A list of DNS name server IP addresses. This will be appended to the base nameservers generated from DNSPolicy. Duplicated nameservers will be removed. - -| `options` -| xref:../objects/index.adoc#poddnsconfigoption-core-v1[`array (PodDNSConfigOption core/v1)`] -| A list of DNS resolver options. This will be merged with the base options generated from DNSPolicy. Duplicated entries will be removed. Resolution options given in Options will override those that appear in the base DNSPolicy. - -| `searches` -| `array (string)` -| A list of DNS search domains for host-name lookup. This will be appended to the base search paths generated from DNSPolicy. Duplicated search paths will be removed. - -|=== - -[id="poddnsconfigoption-core-v1"] -== PodDNSConfigOption [core/v1] - - -Description:: - PodDNSConfigOption defines DNS resolver options of a pod. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Required. - -| `value` -| `string` -| - -|=== - -[id="podip-core-v1"] -== PodIP [core/v1] - - -Description:: - IP address information for entries in the (plural) PodIPs field. Each entry includes: - IP: An IP address allocated to the pod. Routable at least within the cluster. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ip` -| `string` -| ip is an IP address (IPv4 or IPv6) assigned to the pod - -|=== - -[id="podlist-core-v1"] -== PodList [core/v1] - - -Description:: - PodList is a list of Pods. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`array (Pod core/v1)`] -| List of pods. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="podmonitorlist-monitoring-coreos-com-v1"] -== PodMonitorList [monitoring.coreos.com/v1] - - -Description:: - PodMonitorList is a list of PodMonitor - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../monitoring_apis/podmonitor-monitoring-coreos-com-v1.adoc#podmonitor-monitoring-coreos-com-v1[`array (PodMonitor monitoring.coreos.com/v1)`] -| List of podmonitors. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="podnetworkconnectivitychecklist-controlplane-operator-openshift-io-v1alpha1"] -== PodNetworkConnectivityCheckList [controlplane.operator.openshift.io/v1alpha1] - - -Description:: - PodNetworkConnectivityCheckList is a list of PodNetworkConnectivityCheck - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1.adoc#podnetworkconnectivitycheck-controlplane-operator-openshift-io-v1alpha1[`array (PodNetworkConnectivityCheck controlplane.operator.openshift.io/v1alpha1)`] -| List of podnetworkconnectivitychecks. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="podreadinessgate-core-v1"] -== PodReadinessGate [core/v1] - - -Description:: - PodReadinessGate contains the reference to a pod condition - -Type:: - `object` - -Required:: - - `conditionType` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditionType` -| `string` -| ConditionType refers to a condition in the pod's condition list with matching type. - -|=== - -[id="podsecuritycontext-core-v1"] -== PodSecurityContext [core/v1] - - -Description:: - PodSecurityContext holds pod-level security attributes and common container settings. Some fields are also present in container.securityContext. Field values of container.securityContext take precedence over field values of PodSecurityContext. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsGroup` -| `integer` -| A special supplemental group that applies to all containers in a pod. Some volume types allow the Kubelet to change the ownership of that volume to be owned by the pod: - -1. The owning GID will be the FSGroup 2. The setgid bit is set (new files created in the volume will be owned by FSGroup) 3. The permission bits are OR'd with rw-rw---- - -If unset, the Kubelet will not modify the ownership and permissions of any volume. - -| `fsGroupChangePolicy` -| `string` -| fsGroupChangePolicy defines behavior of changing ownership and permission of the volume before being exposed inside Pod. This field will only apply to volume types which support fsGroup based ownership(and permissions). It will have no effect on ephemeral volume types such as: secret, configmaps and emptydir. Valid values are "OnRootMismatch" and "Always". If not specified, "Always" is used. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `seLinuxOptions` -| xref:../objects/index.adoc#selinuxoptions-core-v1[`SELinuxOptions core/v1`] -| The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `seccompProfile` -| xref:../objects/index.adoc#seccompprofile-core-v1[`SeccompProfile core/v1`] -| The seccomp options to use by the containers in this pod. - -| `supplementalGroups` -| `array (integer)` -| A list of groups applied to the first process run in each container, in addition to the container's primary GID. If unspecified, no groups will be added to any container. - -| `sysctls` -| xref:../objects/index.adoc#sysctl-core-v1[`array (Sysctl core/v1)`] -| Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -| `windowsOptions` -| xref:../objects/index.adoc#windowssecuritycontextoptions-core-v1[`WindowsSecurityContextOptions core/v1`] -| The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== - -[id="podspec-core-v1"] -== PodSpec [core/v1] - - -Description:: - PodSpec is a description of a pod. - -Type:: - `object` - -Required:: - - `containers` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `activeDeadlineSeconds` -| `integer` -| Optional duration in seconds the pod may be active on the node relative to StartTime before the system will actively try to mark it failed and kill associated containers. Value must be a positive integer. - -| `affinity` -| xref:../objects/index.adoc#affinity-core-v1[`Affinity core/v1`] -| If specified, the pod's scheduling constraints - -| `automountServiceAccountToken` -| `boolean` -| AutomountServiceAccountToken indicates whether a service account token should be automatically mounted. - -| `containers` -| xref:../objects/index.adoc#container-core-v1[`array (Container core/v1)`] -| List of containers belonging to the pod. Containers cannot currently be added or removed. There must be at least one container in a Pod. Cannot be updated. - -| `dnsConfig` -| xref:../objects/index.adoc#poddnsconfig-core-v1[`PodDNSConfig core/v1`] -| Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy. - -| `dnsPolicy` -| `string` -| Set DNS policy for the pod. Defaults to "ClusterFirst". Valid values are 'ClusterFirstWithHostNet', 'ClusterFirst', 'Default' or 'None'. DNS parameters given in DNSConfig will be merged with the policy selected with DNSPolicy. To have DNS options set along with hostNetwork, you have to specify DNS policy explicitly to 'ClusterFirstWithHostNet'. - -| `enableServiceLinks` -| `boolean` -| EnableServiceLinks indicates whether information about services should be injected into pod's environment variables, matching the syntax of Docker links. Optional: Defaults to true. - -| `ephemeralContainers` -| xref:../objects/index.adoc#ephemeralcontainer-core-v1[`array (EphemeralContainer core/v1)`] -| List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing pod to perform user-initiated actions such as debugging. This list cannot be specified when creating a pod, and it cannot be modified by updating the pod spec. In order to add an ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource. This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature. - -| `hostAliases` -| xref:../objects/index.adoc#hostalias-core-v1[`array (HostAlias core/v1)`] -| HostAliases is an optional list of hosts and IPs that will be injected into the pod's hosts file if specified. This is only valid for non-hostNetwork pods. - -| `hostIPC` -| `boolean` -| Use the host's ipc namespace. Optional: Default to false. - -| `hostNetwork` -| `boolean` -| Host networking requested for this pod. Use the host's network namespace. If this option is set, the ports that will be used must be specified. Default to false. - -| `hostPID` -| `boolean` -| Use the host's pid namespace. Optional: Default to false. - -| `hostname` -| `string` -| Specifies the hostname of the Pod If not specified, the pod's hostname will be set to a system-defined value. - -| `imagePullSecrets` -| xref:../objects/index.adoc#localobjectreference-core-v1[`array (LocalObjectReference core/v1)`] -| ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. For example, in the case of docker, only DockerConfig type secrets are honored. More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod - -| `initContainers` -| xref:../objects/index.adoc#container-core-v1[`array (Container core/v1)`] -| List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. Init containers cannot currently be added or removed. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ - -| `nodeName` -| `string` -| NodeName is a request to schedule this pod onto a specific node. If it is non-empty, the scheduler simply schedules this pod onto that node, assuming that it fits resource requirements. - -| `nodeSelector` -| `object (string)` -| NodeSelector is a selector which must be true for the pod to fit on a node. Selector which must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ - -| `overhead` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Overhead represents the resource overhead associated with running a pod for a given RuntimeClass. This field will be autopopulated at admission time by the RuntimeClass admission controller. If the RuntimeClass admission controller is enabled, overhead must not be set in Pod create requests. The RuntimeClass admission controller will reject Pod create requests which have the overhead already set. If RuntimeClass is configured and selected in the PodSpec, Overhead will be set to the value defined in the corresponding RuntimeClass, otherwise it will remain unset and treated as zero. More info: https://git.k8s.io/enhancements/keps/sig-node/20190226-pod-overhead.md This field is alpha-level as of Kubernetes v1.16, and is only honored by servers that enable the PodOverhead feature. - -| `preemptionPolicy` -| `string` -| PreemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset. This field is beta-level, gated by the NonPreemptingPriority feature-gate. - -| `priority` -| `integer` -| The priority value. Various system components use this field to find the priority of the pod. When Priority Admission Controller is enabled, it prevents users from setting this field. The admission controller populates this field from PriorityClassName. The higher the value, the higher the priority. - -| `priorityClassName` -| `string` -| If specified, indicates the pod's priority. "system-node-critical" and "system-cluster-critical" are two special keywords which indicate the highest priorities with the former being the highest priority. Any other name must be defined by creating a PriorityClass object with that name. If not specified, the pod priority will be default or zero if there is no default. - -| `readinessGates` -| xref:../objects/index.adoc#podreadinessgate-core-v1[`array (PodReadinessGate core/v1)`] -| If specified, all readiness gates will be evaluated for pod readiness. A pod is ready when all its containers are ready AND all conditions specified in the readiness gates have status equal to "True" More info: https://git.k8s.io/enhancements/keps/sig-network/0007-pod-ready%2B%2B.md - -| `restartPolicy` -| `string` -| Restart policy for all containers within the pod. One of Always, OnFailure, Never. Default to Always. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy - -| `runtimeClassName` -| `string` -| RuntimeClassName refers to a RuntimeClass object in the node.k8s.io group, which should be used to run this pod. If no RuntimeClass resource matches the named class, the pod will not be run. If unset or empty, the "legacy" RuntimeClass will be used, which is an implicit class with an empty definition that uses the default runtime handler. More info: https://git.k8s.io/enhancements/keps/sig-node/runtime-class.md This is a beta feature as of Kubernetes v1.14. - -| `schedulerName` -| `string` -| If specified, the pod will be dispatched by specified scheduler. If not specified, the pod will be dispatched by default scheduler. - -| `securityContext` -| xref:../objects/index.adoc#podsecuritycontext-core-v1[`PodSecurityContext core/v1`] -| SecurityContext holds pod-level security attributes and common container settings. Optional: Defaults to empty. See type description for default values of each field. - -| `serviceAccount` -| `string` -| DeprecatedServiceAccount is a depreciated alias for ServiceAccountName. Deprecated: Use serviceAccountName instead. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the name of the ServiceAccount to use to run this pod. More info: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ - -| `setHostnameAsFQDN` -| `boolean` -| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. - -| `shareProcessNamespace` -| `boolean` -| Share a single process namespace between all of the containers in a pod. When this is set containers will be able to view and signal processes from other containers in the same pod, and the first process in each container will not be assigned PID 1. HostPID and ShareProcessNamespace cannot both be set. Optional: Default to false. - -| `subdomain` -| `string` -| If specified, the fully qualified Pod hostname will be "<hostname>.<subdomain>.<pod namespace>.svc.<cluster domain>". If not specified, the pod will not have a domainname at all. - -| `terminationGracePeriodSeconds` -| `integer` -| Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds. - -| `tolerations` -| xref:../objects/index.adoc#toleration-core-v1[`array (Toleration core/v1)`] -| If specified, the pod's tolerations. - -| `topologySpreadConstraints` -| xref:../objects/index.adoc#topologyspreadconstraint-core-v1[`array (TopologySpreadConstraint core/v1)`] -| TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. - -| `volumes` -| xref:../objects/index.adoc#volume-core-v1[`array (Volume core/v1)`] -| List of volumes that can be mounted by containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes - -|=== - -[id="podtemplatelist-core-v1"] -== PodTemplateList [core/v1] - - -Description:: - PodTemplateList is a list of PodTemplates. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`array (PodTemplate core/v1)`] -| List of pod templates - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="podtemplatespec-core-v1"] -== PodTemplateSpec [core/v1] - - -Description:: - PodTemplateSpec describes the data a pod should have when created from a template - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| xref:../objects/index.adoc#podspec-core-v1[`PodSpec core/v1`] -| Specification of the desired behavior of the pod. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -|=== - -[id="portstatus-core-v1"] -== PortStatus [core/v1] - - -Description:: - - -Type:: - `object` - -Required:: - - `port` - - `protocol` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `error` -| `string` -| Error is to record the problem with the service port The format of the error shall comply with the following rules: - built-in error values shall be specified in this file and those shall use - CamelCase names -- cloud provider specific error values must have names that comply with the - format foo.example.com/CamelCase. - -| `port` -| `integer` -| Port is the port number of the service port of which status is recorded here - -| `protocol` -| `string` -| Protocol is the protocol of the service port of which status is recorded here The supported values are: "TCP", "UDP", "SCTP" - -|=== - -[id="portworxvolumesource-core-v1"] -== PortworxVolumeSource [core/v1] - - -Description:: - PortworxVolumeSource represents a Portworx volume resource. - -Type:: - `object` - -Required:: - - `volumeID` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| FSType represents the filesystem type to mount Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `volumeID` -| `string` -| VolumeID uniquely identifies a Portworx volume - -|=== - -[id="preferredschedulingterm-core-v1"] -== PreferredSchedulingTerm [core/v1] - - -Description:: - An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -Type:: - `object` - -Required:: - - `weight` - - `preference` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preference` -| xref:../objects/index.adoc#nodeselectorterm-core-v1[`NodeSelectorTerm core/v1`] -| A node selector term, associated with the corresponding weight. - -| `weight` -| `integer` -| Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. - -|=== - -[id="priorityclasslist-scheduling-k8s-io-v1"] -== PriorityClassList [scheduling.k8s.io/v1] - - -Description:: - PriorityClassList is a collection of priority classes. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`array (PriorityClass scheduling.k8s.io/v1)`] -| items is the list of PriorityClasses - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="prioritylevelconfigurationlist-flowcontrol-apiserver-k8s-io-v1alpha1"] -== PriorityLevelConfigurationList [flowcontrol.apiserver.k8s.io/v1alpha1] - - -Description:: - PriorityLevelConfigurationList is a list of PriorityLevelConfiguration objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`array (PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1)`] -| `items` is a list of request-priorities. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| `metadata` is the standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="probe-core-v1"] -== Probe [core/v1] - - -Description:: - Probe describes a health check to be performed against a container to determine whether it is alive or ready to receive traffic. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| xref:../objects/index.adoc#execaction-core-v1[`ExecAction core/v1`] -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| xref:../objects/index.adoc#httpgetaction-core-v1[`HTTPGetAction core/v1`] -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| xref:../objects/index.adoc#tcpsocketaction-core-v1[`TCPSocketAction core/v1`] -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== - -[id="probelist-monitoring-coreos-com-v1"] -== ProbeList [monitoring.coreos.com/v1] - - -Description:: - ProbeList is a list of Probe - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../monitoring_apis/probe-monitoring-coreos-com-v1.adoc#probe-monitoring-coreos-com-v1[`array (Probe monitoring.coreos.com/v1)`] -| List of probes. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="profilelist-tuned-openshift-io-v1"] -== ProfileList [tuned.openshift.io/v1] - - -Description:: - ProfileList is a list of Profile - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../node_apis/profile-tuned-openshift-io-v1.adoc#profile-tuned-openshift-io-v1[`array (Profile tuned.openshift.io/v1)`] -| List of profiles. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="projectedvolumesource-core-v1"] -== ProjectedVolumeSource [core/v1] - - -Description:: - Represents a projected volume source - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `sources` -| xref:../objects/index.adoc#volumeprojection-core-v1[`array (VolumeProjection core/v1)`] -| list of volume projections - -|=== - -[id="projectlist-config-openshift-io-v1"] -== ProjectList [config.openshift.io/v1] - - -Description:: - ProjectList is a list of Project - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/project-config-openshift-io-v1.adoc#project-config-openshift-io-v1[`array (Project config.openshift.io/v1)`] -| List of projects. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="projectlist-project-openshift-io-v1"] -== ProjectList [project.openshift.io/v1] - - -Description:: - ProjectList is a list of Project objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`array (Project project.openshift.io/v1)`] -| Items is the list of projects - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="prometheuslist-monitoring-coreos-com-v1"] -== PrometheusList [monitoring.coreos.com/v1] - - -Description:: - PrometheusList is a list of Prometheus - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../monitoring_apis/prometheus-monitoring-coreos-com-v1.adoc#prometheus-monitoring-coreos-com-v1[`array (Prometheus monitoring.coreos.com/v1)`] -| List of prometheuses. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="prometheusrulelist-monitoring-coreos-com-v1"] -== PrometheusRuleList [monitoring.coreos.com/v1] - - -Description:: - PrometheusRuleList is a list of PrometheusRule - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../monitoring_apis/prometheusrule-monitoring-coreos-com-v1.adoc#prometheusrule-monitoring-coreos-com-v1[`array (PrometheusRule monitoring.coreos.com/v1)`] -| List of prometheusrules. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="provisioninglist-metal3-io-v1alpha1"] -== ProvisioningList [metal3.io/v1alpha1] - - -Description:: - ProvisioningList is a list of Provisioning - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`array (Provisioning metal3.io/v1alpha1)`] -| List of provisionings. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="proxylist-config-openshift-io-v1"] -== ProxyList [config.openshift.io/v1] - - -Description:: - ProxyList is a list of Proxy - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/proxy-config-openshift-io-v1.adoc#proxy-config-openshift-io-v1[`array (Proxy config.openshift.io/v1)`] -| List of proxies. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="quantity-api-resource"] -== Quantity [api/resource] - - -Description:: - Quantity is a fixed-point representation of a number. It provides convenient marshaling/unmarshaling in JSON and YAML, in addition to String() and AsInt64() accessors. - -The serialization format is: - -<quantity> ::= <signedNumber><suffix> - (Note that <suffix> may be empty, from the "" case in <decimalSI>.) -<digit> ::= 0 | 1 | ... | 9 <digits> ::= <digit> | <digit><digits> <number> ::= <digits> | <digits>.<digits> | <digits>. | .<digits> <sign> ::= "+" | "-" <signedNumber> ::= <number> | <sign><number> <suffix> ::= <binarySI> | <decimalExponent> | <decimalSI> <binarySI> ::= Ki | Mi | Gi | Ti | Pi | Ei - (International System of units; See: http://physics.nist.gov/cuu/Units/binary.html) -<decimalSI> ::= m | "" | k | M | G | T | P | E - (Note that 1024 = 1Ki but 1000 = 1k; I didn't choose the capitalization.) -<decimalExponent> ::= "e" <signedNumber> | "E" <signedNumber> - -No matter which of the three exponent forms is used, no quantity may represent a number greater than 2^63-1 in magnitude, nor may it have more than 3 decimal places. Numbers larger or more precise will be capped or rounded up. (E.g.: 0.1m will rounded up to 1m.) This may be extended in the future if we require larger or smaller quantities. - -When a Quantity is parsed from a string, it will remember the type of suffix it had, and will use the same type again when it is serialized. - -Before serializing, Quantity will be put in "canonical form". This means that Exponent/suffix will be adjusted up or down (with a corresponding increase or decrease in Mantissa) such that: - a. No precision is lost - b. No fractional digits will be emitted - c. The exponent (or suffix) is as large as possible. -The sign will be omitted unless the number is negative. - -Examples: - 1.5 will be serialized as "1500m" - 1.5Gi will be serialized as "1536Mi" - -Note that the quantity will NEVER be internally represented by a floating point number. That is the whole point of this exercise. - -Non-canonical values will still parse as long as they are well formed, but will be re-emitted in their canonical form. (So always use canonical form, or don't diff.) - -This format is intended to make it difficult to use these numbers without writing some sort of special handling code in the hopes that that will cause implementors to also use a fixed point implementation. - -Type:: - `string` - - - -[id="quobytevolumesource-core-v1"] -== QuobyteVolumeSource [core/v1] - - -Description:: - Represents a Quobyte mount that lasts the lifetime of a pod. Quobyte volumes do not support ownership management or SELinux relabeling. - -Type:: - `object` - -Required:: - - `registry` - - `volume` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group to map volume access to Default is no group - -| `readOnly` -| `boolean` -| ReadOnly here will force the Quobyte volume to be mounted with read-only permissions. Defaults to false. - -| `registry` -| `string` -| Registry represents a single or multiple Quobyte Registry services specified as a string as host:port pair (multiple entries are separated with commas) which acts as the central registry for volumes - -| `tenant` -| `string` -| Tenant owning the given Quobyte volume in the Backend Used with dynamically provisioned Quobyte volumes, value is set by the plugin - -| `user` -| `string` -| User to map volume access to Defaults to serivceaccount user - -| `volume` -| `string` -| Volume is a string that references an already created Quobyte volume by name. - -|=== - -[id="rangeallocationlist-security-openshift-io-v1"] -== RangeAllocationList [security.openshift.io/v1] - - -Description:: - RangeAllocationList is a list of RangeAllocations objects - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`array (RangeAllocation security.openshift.io/v1)`] -| List of RangeAllocations. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="rawextension-pkg-runtime"] -== RawExtension [pkg/runtime] - - -Description:: - RawExtension is used to hold extensions in external versions. - -To use this, make a field which has RawExtension as its type in your external, versioned struct, and Object in your internal struct. You also need to register your various plugin types. - -// Internal package: type MyAPIObject struct { - runtime.TypeMeta `json:",inline"` - MyPlugin runtime.Object `json:"myPlugin"` -} type PluginA struct { - AOption string `json:"aOption"` -} - -// External package: type MyAPIObject struct { - runtime.TypeMeta `json:",inline"` - MyPlugin runtime.RawExtension `json:"myPlugin"` -} type PluginA struct { - AOption string `json:"aOption"` -} - -// On the wire, the JSON will look something like this: { - "kind":"MyAPIObject", - "apiVersion":"v1", - "myPlugin": { - "kind":"PluginA", - "aOption":"foo", - }, -} - -So what happens? Decode first uses json or yaml to unmarshal the serialized data into your external MyAPIObject. That causes the raw JSON to be stored, but not unpacked. The next step is to copy (using pkg/conversion) into the internal struct. The runtime package's DefaultScheme has conversion functions installed which will unpack the JSON stored in RawExtension, turning it into the correct object type, and storing it in the Object. (TODO: In the case where the object is of an unknown type, a runtime.Unknown object will be created and stored.) - -Type:: - `object` - - - -[id="rbdpersistentvolumesource-core-v1"] -== RBDPersistentVolumeSource [core/v1] - - -Description:: - Represents a Rados Block Device mount that lasts the lifetime of a pod. RBD volumes support ownership management and SELinux relabeling. - -Type:: - `object` - -Required:: - - `monitors` - - `image` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd - -| `image` -| `string` -| The rados image name. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `keyring` -| `string` -| Keyring is the path to key ring for RBDUser. Default is /etc/ceph/keyring. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `monitors` -| `array (string)` -| A collection of Ceph monitors. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `pool` -| `string` -| The rados pool name. Default is rbd. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `secretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `user` -| `string` -| The rados user name. Default is admin. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -|=== - -[id="rbdvolumesource-core-v1"] -== RBDVolumeSource [core/v1] - - -Description:: - Represents a Rados Block Device mount that lasts the lifetime of a pod. RBD volumes support ownership management and SELinux relabeling. - -Type:: - `object` - -Required:: - - `monitors` - - `image` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd - -| `image` -| `string` -| The rados image name. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `keyring` -| `string` -| Keyring is the path to key ring for RBDUser. Default is /etc/ceph/keyring. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `monitors` -| `array (string)` -| A collection of Ceph monitors. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `pool` -| `string` -| The rados pool name. Default is rbd. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `secretRef` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `user` -| `string` -| The rados user name. Default is admin. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -|=== - -[id="replicasetlist-apps-v1"] -== ReplicaSetList [apps/v1] - - -Description:: - ReplicaSetList is a collection of ReplicaSets. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`array (ReplicaSet apps/v1)`] -| List of ReplicaSets. More info: https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="replicationcontrollercondition-core-v1"] -== ReplicationControllerCondition [core/v1] - - -Description:: - ReplicationControllerCondition describes the state of a replication controller at a certain point. - -Type:: - `object` - -Required:: - - `type` - - `status` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The last time the condition transitioned from one status to another. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of replication controller condition. - -|=== - -[id="replicationcontrollerlist-core-v1"] -== ReplicationControllerList [core/v1] - - -Description:: - ReplicationControllerList is a collection of replication controllers. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`array (ReplicationController core/v1)`] -| List of replication controllers. More info: https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="resourcefieldselector-core-v1"] -== ResourceFieldSelector [core/v1] - - -Description:: - ResourceFieldSelector represents container resources (cpu, memory) and their output format - -Type:: - `object` - -Required:: - - `resource` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| xref:../objects/index.adoc#quantity-api-resource[`Quantity api/resource`] -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== - -[id="resourcequotalist-core-v1"] -== ResourceQuotaList [core/v1] - - -Description:: - ResourceQuotaList is a list of ResourceQuota items. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`array (ResourceQuota core/v1)`] -| Items is a list of ResourceQuota objects. More info: https://kubernetes.io/docs/concepts/policy/resource-quotas/ - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="resourcequotaspec-core-v1"] -== ResourceQuotaSpec [core/v1] - - -Description:: - ResourceQuotaSpec defines the desired hard limits to enforce for Quota. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hard` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| hard is the set of desired hard limits for each named resource. More info: https://kubernetes.io/docs/concepts/policy/resource-quotas/ - -| `scopeSelector` -| xref:../objects/index.adoc#scopeselector-core-v1[`ScopeSelector core/v1`] -| scopeSelector is also a collection of filters like scopes that must match each object tracked by a quota but expressed using ScopeSelectorOperator in combination with possible values. For a resource to match, both scopes AND scopeSelector (if specified in spec), must be matched. - -| `scopes` -| `array (string)` -| A collection of filters that must match each object tracked by a quota. If not specified, the quota matches all objects. - -|=== - -[id="resourcequotastatus-core-v1"] -== ResourceQuotaStatus [core/v1] - - -Description:: - ResourceQuotaStatus defines the enforced hard limits and observed use. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hard` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Hard is the set of enforced hard limits for each named resource. More info: https://kubernetes.io/docs/concepts/policy/resource-quotas/ - -| `used` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Used is the current observed total usage of the resource in the namespace. - -|=== - -[id="resourcerequirements-core-v1"] -== ResourceRequirements [core/v1] - - -Description:: - ResourceRequirements describes the compute resource requirements. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== - -[id="rolebindinglist-authorization-openshift-io-v1"] -== RoleBindingList [authorization.openshift.io/v1] - - -Description:: - RoleBindingList is a collection of RoleBindings - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`array (RoleBinding authorization.openshift.io/v1)`] -| Items is a list of RoleBindings - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="rolebindinglist-rbac-authorization-k8s-io-v1"] -== RoleBindingList [rbac.authorization.k8s.io/v1] - - -Description:: - RoleBindingList is a collection of RoleBindings - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`array (RoleBinding rbac.authorization.k8s.io/v1)`] -| Items is a list of RoleBindings - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard object's metadata. - -|=== - -[id="rolebindingrestrictionlist-authorization-openshift-io-v1"] -== RoleBindingRestrictionList [authorization.openshift.io/v1] - - -Description:: - RoleBindingRestrictionList is a list of RoleBindingRestriction - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`array (RoleBindingRestriction authorization.openshift.io/v1)`] -| List of rolebindingrestrictions. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="rolelist-authorization-openshift-io-v1"] -== RoleList [authorization.openshift.io/v1] - - -Description:: - RoleList is a collection of Roles - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`array (Role authorization.openshift.io/v1)`] -| Items is a list of Roles - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="rolelist-rbac-authorization-k8s-io-v1"] -== RoleList [rbac.authorization.k8s.io/v1] - - -Description:: - RoleList is a collection of Roles - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`array (Role rbac.authorization.k8s.io/v1)`] -| Items is a list of Roles - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard object's metadata. - -|=== - -[id="routelist-route-openshift-io-v1"] -== RouteList [route.openshift.io/v1] - - -Description:: - RouteList is a collection of Routes. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/route-route-openshift-io-v1.adoc#route-route-openshift-io-v1[`array (Route route.openshift.io/v1)`] -| items is a list of routes - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="runtimeclasslist-node-k8s-io-v1"] -== RuntimeClassList [node.k8s.io/v1] - - -Description:: - RuntimeClassList is a list of RuntimeClass objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../node_apis/runtimeclass-node-k8s-io-v1.adoc#runtimeclass-node-k8s-io-v1[`array (RuntimeClass node.k8s.io/v1)`] -| Items is a list of schema objects. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="scale-autoscaling-v1"] -== Scale [autoscaling/v1] - - -Description:: - Scale represents a scaling request for a resource. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object metadata; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata. - -| `spec` -| xref:../objects/index.adoc#scalespec-autoscaling-v1[`ScaleSpec autoscaling/v1`] -| defines the behavior of the scale. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. - -| `status` -| xref:../objects/index.adoc#scalestatus-autoscaling-v1[`ScaleStatus autoscaling/v1`] -| current status of the scale. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. Read-only. - -|=== - -[id="scale-extensions-v1beta1"] -== Scale [extensions/v1beta1] - - -Description:: - represents a scaling request for a resource. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object metadata; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata. - -| `spec` -| xref:../objects/index.adoc#scalespec-extensions-v1beta1[`ScaleSpec extensions/v1beta1`] -| defines the behavior of the scale. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. - -| `status` -| xref:../objects/index.adoc#scalestatus-extensions-v1beta1[`ScaleStatus extensions/v1beta1`] -| current status of the scale. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. Read-only. - -|=== - -[id="scale_v2-autoscaling-v1"] -== Scale_v2 [autoscaling/v1] - - -Description:: - Scale represents a scaling request for a resource. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object metadata; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata. - -| `spec` -| xref:../objects/index.adoc#scalespec-autoscaling-v1[`ScaleSpec autoscaling/v1`] -| defines the behavior of the scale. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. - -| `status` -| xref:../objects/index.adoc#scalestatus-autoscaling-v1[`ScaleStatus autoscaling/v1`] -| current status of the scale. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status. Read-only. - -|=== - -[id="scaleiopersistentvolumesource-core-v1"] -== ScaleIOPersistentVolumeSource [core/v1] - - -Description:: - ScaleIOPersistentVolumeSource represents a persistent ScaleIO volume - -Type:: - `object` - -Required:: - - `gateway` - - `system` - - `secretRef` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Default is "xfs" - -| `gateway` -| `string` -| The host address of the ScaleIO API Gateway. - -| `protectionDomain` -| `string` -| The name of the ScaleIO Protection Domain for the configured storage. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| xref:../objects/index.adoc#secretreference-core-v1[`SecretReference core/v1`] -| SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -| `sslEnabled` -| `boolean` -| Flag to enable/disable SSL communication with Gateway, default false - -| `storageMode` -| `string` -| Indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned. Default is ThinProvisioned. - -| `storagePool` -| `string` -| The ScaleIO Storage Pool associated with the protection domain. - -| `system` -| `string` -| The name of the storage system as configured in ScaleIO. - -| `volumeName` -| `string` -| The name of a volume already created in the ScaleIO system that is associated with this volume source. - -|=== - -[id="scaleiovolumesource-core-v1"] -== ScaleIOVolumeSource [core/v1] - - -Description:: - ScaleIOVolumeSource represents a persistent ScaleIO volume - -Type:: - `object` - -Required:: - - `gateway` - - `system` - - `secretRef` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Default is "xfs". - -| `gateway` -| `string` -| The host address of the ScaleIO API Gateway. - -| `protectionDomain` -| `string` -| The name of the ScaleIO Protection Domain for the configured storage. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -| `sslEnabled` -| `boolean` -| Flag to enable/disable SSL communication with Gateway, default false - -| `storageMode` -| `string` -| Indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned. Default is ThinProvisioned. - -| `storagePool` -| `string` -| The ScaleIO Storage Pool associated with the protection domain. - -| `system` -| `string` -| The name of the storage system as configured in ScaleIO. - -| `volumeName` -| `string` -| The name of a volume already created in the ScaleIO system that is associated with this volume source. - -|=== - -[id="schedulerlist-config-openshift-io-v1"] -== SchedulerList [config.openshift.io/v1] - - -Description:: - SchedulerList is a list of Scheduler - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../config_apis/scheduler-config-openshift-io-v1.adoc#scheduler-config-openshift-io-v1[`array (Scheduler config.openshift.io/v1)`] -| List of schedulers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="scopedresourceselectorrequirement-core-v1"] -== ScopedResourceSelectorRequirement [core/v1] - - -Description:: - A scoped-resource selector requirement is a selector that contains values, a scope name, and an operator that relates the scope name and values. - -Type:: - `object` - -Required:: - - `scopeName` - - `operator` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `operator` -| `string` -| Represents a scope's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. - -| `scopeName` -| `string` -| The name of the scope that the selector applies to. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== - -[id="scopeselector-core-v1"] -== ScopeSelector [core/v1] - - -Description:: - A scope selector represents the AND of the selectors represented by the scoped-resource selector requirements. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| xref:../objects/index.adoc#scopedresourceselectorrequirement-core-v1[`array (ScopedResourceSelectorRequirement core/v1)`] -| A list of scope selector requirements by scope of the resources. - -|=== - -[id="seccompprofile-core-v1"] -== SeccompProfile [core/v1] - - -Description:: - SeccompProfile defines a pod/container's seccomp profile settings. Only one profile source may be set. - -Type:: - `object` - -Required:: - - `type` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `localhostProfile` -| `string` -| localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". - -| `type` -| `string` -| type indicates which kind of seccomp profile will be applied. Valid options are: - -Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. - -|=== - -[id="secretenvsource-core-v1"] -== SecretEnvSource [core/v1] - - -Description:: - SecretEnvSource selects a Secret to populate the environment variables with. - -The contents of the target Secret's Data field will represent the key-value pairs as environment variables. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== - -[id="secretkeyselector-core-v1"] -== SecretKeySelector [core/v1] - - -Description:: - SecretKeySelector selects a key of a Secret. - -Type:: - `object` - -Required:: - - `key` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== - -[id="secretlist-core-v1"] -== SecretList [core/v1] - - -Description:: - SecretList is a list of Secret. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`array (Secret core/v1)`] -| Items is a list of secret objects. More info: https://kubernetes.io/docs/concepts/configuration/secret - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="secretlist-image-openshift-io-v1"] -== SecretList [image.openshift.io/v1] - - -Description:: - SecretList is a list of Secret. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`array (Secret core/v1)`] -| Items is a list of secret objects. More info: https://kubernetes.io/docs/concepts/configuration/secret - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="secretprojection-core-v1"] -== SecretProjection [core/v1] - - -Description:: - Adapts a secret into a projected volume. - -The contents of the target Secret's Data field will be presented in a projected volume as files using the keys in the Data field as the file names. Note that this is identical to a secret volume source without the default mode. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| xref:../objects/index.adoc#keytopath-core-v1[`array (KeyToPath core/v1)`] -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== - -[id="secretreference-core-v1"] -== SecretReference [core/v1] - - -Description:: - SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is unique within a namespace to reference a secret resource. - -| `namespace` -| `string` -| Namespace defines the space within which the secret name must be unique. - -|=== - -[id="secretvolumesource-core-v1"] -== SecretVolumeSource [core/v1] - - -Description:: - Adapts a Secret into a volume. - -The contents of the target Secret's Data field will be presented in a volume as files using the keys in the Data field as the file names. Secret volumes support ownership management and SELinux relabeling. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| xref:../objects/index.adoc#keytopath-core-v1[`array (KeyToPath core/v1)`] -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `optional` -| `boolean` -| Specify whether the Secret or its keys must be defined - -| `secretName` -| `string` -| Name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -|=== - -[id="securitycontext-core-v1"] -== SecurityContext [core/v1] - - -Description:: - SecurityContext holds security configuration that will be applied to a container. Some fields are present in both SecurityContext and PodSecurityContext. When both are set, the values in SecurityContext take precedence. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| xref:../objects/index.adoc#capabilities-core-v1[`Capabilities core/v1`] -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| xref:../objects/index.adoc#selinuxoptions-core-v1[`SELinuxOptions core/v1`] -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seccompProfile` -| xref:../objects/index.adoc#seccompprofile-core-v1[`SeccompProfile core/v1`] -| The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. - -| `windowsOptions` -| xref:../objects/index.adoc#windowssecuritycontextoptions-core-v1[`WindowsSecurityContextOptions core/v1`] -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== - -[id="securitycontextconstraintslist-security-openshift-io-v1"] -== SecurityContextConstraintsList [security.openshift.io/v1] - - -Description:: - SecurityContextConstraintsList is a list of SecurityContextConstraints - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`array (SecurityContextConstraints security.openshift.io/v1)`] -| List of securitycontextconstraints. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="selinuxoptions-core-v1"] -== SELinuxOptions [core/v1] - - -Description:: - SELinuxOptions are the labels to be applied to the container - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== - -[id="serviceaccountlist-core-v1"] -== ServiceAccountList [core/v1] - - -Description:: - ServiceAccountList is a list of ServiceAccount objects - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`array (ServiceAccount core/v1)`] -| List of ServiceAccounts. More info: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="serviceaccounttokenprojection-core-v1"] -== ServiceAccountTokenProjection [core/v1] - - -Description:: - ServiceAccountTokenProjection represents a projected service account token volume. This projection can be used to insert a service account token into the pods runtime filesystem for use against APIs (Kubernetes API Server or otherwise). - -Type:: - `object` - -Required:: - - `path` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audience` -| `string` -| Audience is the intended audience of the token. A recipient of a token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. The audience defaults to the identifier of the apiserver. - -| `expirationSeconds` -| `integer` -| ExpirationSeconds is the requested duration of validity of the service account token. As the token approaches expiration, the kubelet volume plugin will proactively rotate the service account token. The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.Defaults to 1 hour and must be at least 10 minutes. - -| `path` -| `string` -| Path is the path relative to the mount point of the file to project the token into. - -|=== - -[id="servicecalist-operator-openshift-io-v1"] -== ServiceCAList [operator.openshift.io/v1] - - -Description:: - ServiceCAList is a list of ServiceCA - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`array (ServiceCA operator.openshift.io/v1)`] -| List of servicecas. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="servicelist-core-v1"] -== ServiceList [core/v1] - - -Description:: - ServiceList holds a list of services. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../network_apis/service-core-v1.adoc#service-core-v1[`array (Service core/v1)`] -| List of services - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="servicemonitorlist-monitoring-coreos-com-v1"] -== ServiceMonitorList [monitoring.coreos.com/v1] - - -Description:: - ServiceMonitorList is a list of ServiceMonitor - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../monitoring_apis/servicemonitor-monitoring-coreos-com-v1.adoc#servicemonitor-monitoring-coreos-com-v1[`array (ServiceMonitor monitoring.coreos.com/v1)`] -| List of servicemonitors. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="serviceport-core-v1"] -== ServicePort [core/v1] - - -Description:: - ServicePort contains information on service's port. - -Type:: - `object` - -Required:: - - `port` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `appProtocol` -| `string` -| The application protocol for this port. This field follows standard Kubernetes label syntax. Un-prefixed names are reserved for IANA standard service names (as per RFC-6335 and http://www.iana.org/assignments/service-names). Non-standard protocols should use prefixed names such as mycompany.com/my-custom-protocol. This is a beta field that is guarded by the ServiceAppProtocol feature gate and enabled by default. - -| `name` -| `string` -| The name of this port within the service. This must be a DNS_LABEL. All ports within a ServiceSpec must have unique names. When considering the endpoints for a Service, this must match the 'name' field in the EndpointPort. Optional if only one ServicePort is defined on this service. - -| `nodePort` -| `integer` -| The port on each node on which this service is exposed when type is NodePort or LoadBalancer. Usually assigned by the system. If a value is specified, in-range, and not in use it will be used, otherwise the operation will fail. If not specified, a port will be allocated if this Service requires one. If this field is specified when creating a Service which does not need it, creation will fail. This field will be wiped when updating a Service to no longer need it (e.g. changing type from NodePort to ClusterIP). More info: https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport - -| `port` -| `integer` -| The port that will be exposed by this service. - -| `protocol` -| `string` -| The IP protocol for this port. Supports "TCP", "UDP", and "SCTP". Default is TCP. - -| `targetPort` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| Number or name of the port to access on the pods targeted by the service. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. If this is a string, it will be looked up as a named port in the target Pod's container ports. If this is not specified, the value of the 'port' field is used (an identity map). This field is ignored for services with clusterIP=None, and should be omitted or set equal to the 'port' field. More info: https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service - -|=== - -[id="sessionaffinityconfig-core-v1"] -== SessionAffinityConfig [core/v1] - - -Description:: - SessionAffinityConfig represents the configurations of session affinity. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clientIP` -| xref:../objects/index.adoc#clientipconfig-core-v1[`ClientIPConfig core/v1`] -| clientIP contains the configurations of Client IP based session affinity. - -|=== - -[id="statefulsetlist-apps-v1"] -== StatefulSetList [apps/v1] - - -Description:: - StatefulSetList is a collection of StatefulSets. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`array (StatefulSet apps/v1)`] -| - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="status-meta-v1"] -== Status [meta/v1] - - -Description:: - Status is a return value for calls that don't return other objects. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `code` -| `integer` -| Suggested HTTP return code for this status, 0 if not set. - -| `details` -| xref:../objects/index.adoc#statusdetails-meta-v1[`StatusDetails meta/v1`] -| Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `message` -| `string` -| A human-readable description of the status of this operation. - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `reason` -| `string` -| A machine-readable description of why this operation is in the "Failure" status. If this value is empty there is no information available. A Reason clarifies an HTTP status code but does not override it. - -| `status` -| `string` -| Status of the operation. One of: "Success" or "Failure". More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -|=== - -[id="status_v2-meta-v1"] -== Status_v2 [meta/v1] - - -Description:: - Status is a return value for calls that don't return other objects. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `code` -| `integer` -| Suggested HTTP return code for this status, 0 if not set. - -| `details` -| xref:../objects/index.adoc#statusdetails_v2-meta-v1[`StatusDetails_v2 meta/v1`] -| Extended data associated with the reason. Each reason may define its own extended details. This field is optional and the data returned is not guaranteed to conform to any schema except that defined by the reason type. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `message` -| `string` -| A human-readable description of the status of this operation. - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `reason` -| `string` -| A machine-readable description of why this operation is in the "Failure" status. If this value is empty there is no information available. A Reason clarifies an HTTP status code but does not override it. - -| `status` -| `string` -| Status of the operation. One of: "Success" or "Failure". More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -|=== - -[id="statuscause-meta-v1"] -== StatusCause [meta/v1] - - -Description:: - StatusCause provides more information about an api.Status failure, including cases when multiple errors are encountered. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `field` -| `string` -| The field of the resource that has caused this error, as named by its JSON serialization. May include dot and postfix notation for nested attributes. Arrays are zero-indexed. Fields may appear more than once in an array of causes due to fields having multiple errors. Optional. - -Examples: - "name" - the field "name" on the current resource - "items[0].name" - the field "name" on the first array entry in "items" - -| `message` -| `string` -| A human-readable description of the cause of the error. This field may be presented as-is to a reader. - -| `reason` -| `string` -| A machine-readable description of the cause of the error. If this value is empty there is no information available. - -|=== - -[id="statusdetails-meta-v1"] -== StatusDetails [meta/v1] - - -Description:: - StatusDetails is a set of additional properties that MAY be set by the server to provide additional information about a response. The Reason field of a Status object defines what attributes will be set. Clients must ignore fields that do not match the defined type of each attribute, and should assume that any attribute may be empty, invalid, or under defined. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `causes` -| xref:../objects/index.adoc#statuscause-meta-v1[`array (StatusCause meta/v1)`] -| The Causes array includes more details associated with the StatusReason failure. Not all StatusReasons may provide detailed causes. - -| `group` -| `string` -| The group attribute of the resource associated with the status StatusReason. - -| `kind` -| `string` -| The kind attribute of the resource associated with the status StatusReason. On some operations may differ from the requested resource Kind. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| The name attribute of the resource associated with the status StatusReason (when there is a single name which can be described). - -| `retryAfterSeconds` -| `integer` -| If specified, the time in seconds before the operation should be retried. Some errors may indicate the client must take an alternate action - for those errors this field may indicate how long to wait before taking the alternate action. - -| `uid` -| `string` -| UID of the resource. (when there is a single resource which can be described). More info: http://kubernetes.io/docs/user-guide/identifiers#uids - -|=== - -[id="storageclasslist-storage-k8s-io-v1"] -== StorageClassList [storage.k8s.io/v1] - - -Description:: - StorageClassList is a collection of storage classes. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`array (StorageClass storage.k8s.io/v1)`] -| Items is the list of StorageClasses - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="storagelist-operator-openshift-io-v1"] -== StorageList [operator.openshift.io/v1] - - -Description:: - StorageList is a list of Storage - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`array (Storage operator.openshift.io/v1)`] -| List of storages. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="storageospersistentvolumesource-core-v1"] -== StorageOSPersistentVolumeSource [core/v1] - - -Description:: - Represents a StorageOS persistent volume resource. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -| `volumeName` -| `string` -| VolumeName is the human-readable name of the StorageOS volume. Volume names are only unique within a namespace. - -| `volumeNamespace` -| `string` -| VolumeNamespace specifies the scope of the volume within StorageOS. If no namespace is specified then the Pod's namespace will be used. This allows the Kubernetes name scoping to be mirrored within StorageOS for tighter integration. Set VolumeName to any name to override the default behaviour. Set to "default" if you are not using namespaces within StorageOS. Namespaces that do not pre-exist within StorageOS will be created. - -|=== - -[id="storageosvolumesource-core-v1"] -== StorageOSVolumeSource [core/v1] - - -Description:: - Represents a StorageOS persistent volume resource. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -| `volumeName` -| `string` -| VolumeName is the human-readable name of the StorageOS volume. Volume names are only unique within a namespace. - -| `volumeNamespace` -| `string` -| VolumeNamespace specifies the scope of the volume within StorageOS. If no namespace is specified then the Pod's namespace will be used. This allows the Kubernetes name scoping to be mirrored within StorageOS for tighter integration. Set VolumeName to any name to override the default behaviour. Set to "default" if you are not using namespaces within StorageOS. Namespaces that do not pre-exist within StorageOS will be created. - -|=== - -[id="storagestatelist-migration-k8s-io-v1alpha1"] -== StorageStateList [migration.k8s.io/v1alpha1] - - -Description:: - StorageStateList is a list of StorageState - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`array (StorageState migration.k8s.io/v1alpha1)`] -| List of storagestates. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="storageversionmigrationlist-migration-k8s-io-v1alpha1"] -== StorageVersionMigrationList [migration.k8s.io/v1alpha1] - - -Description:: - StorageVersionMigrationList is a list of StorageVersionMigration - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`array (StorageVersionMigration migration.k8s.io/v1alpha1)`] -| List of storageversionmigrations. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="subscriptionlist-operators-coreos-com-v1alpha1"] -== SubscriptionList [operators.coreos.com/v1alpha1] - - -Description:: - SubscriptionList is a list of Subscription - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`array (Subscription operators.coreos.com/v1alpha1)`] -| List of subscriptions. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="sysctl-core-v1"] -== Sysctl [core/v1] - - -Description:: - Sysctl defines a kernel parameter to be set - -Type:: - `object` - -Required:: - - `name` - - `value` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of a property to set - -| `value` -| `string` -| Value of a property to set - -|=== - -[id="taint-core-v1"] -== Taint [core/v1] - - -Description:: - The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint. - -Type:: - `object` - -Required:: - - `key` - - `effect` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Required. The effect of the taint on pods that do not tolerate the taint. Valid effects are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Required. The taint key to be applied to a node. - -| `timeAdded` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| TimeAdded represents the time at which the taint was added. It is only written for NoExecute taints. - -| `value` -| `string` -| The taint value corresponding to the taint key. - -|=== - -[id="tcpsocketaction-core-v1"] -== TCPSocketAction [core/v1] - - -Description:: - TCPSocketAction describes an action based on opening a socket - -Type:: - `object` - -Required:: - - `port` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== - -[id="templateinstancelist-template-openshift-io-v1"] -== TemplateInstanceList [template.openshift.io/v1] - - -Description:: - TemplateInstanceList is a list of TemplateInstance objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`array (TemplateInstance template.openshift.io/v1)`] -| items is a list of Templateinstances - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="thanosrulerlist-monitoring-coreos-com-v1"] -== ThanosRulerList [monitoring.coreos.com/v1] - - -Description:: - ThanosRulerList is a list of ThanosRuler - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../monitoring_apis/thanosruler-monitoring-coreos-com-v1.adoc#thanosruler-monitoring-coreos-com-v1[`array (ThanosRuler monitoring.coreos.com/v1)`] -| List of thanosrulers. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="time-meta-v1"] -== Time [meta/v1] - - -Description:: - Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON. Wrappers are provided for many of the factory methods that the time package offers. - -Type:: - `string` - - - -[id="tokenrequest-authentication-k8s-io-v1"] -== TokenRequest [authentication.k8s.io/v1] - - -Description:: - TokenRequest requests a token for a given service account. - -Type:: - `object` - -Required:: - - `spec` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| xref:../objects/index.adoc#tokenrequestspec-authentication-k8s-io-v1[`TokenRequestSpec authentication.k8s.io/v1`] -| - -| `status` -| xref:../objects/index.adoc#tokenrequeststatus-authentication-k8s-io-v1[`TokenRequestStatus authentication.k8s.io/v1`] -| - -|=== - -[id="toleration-core-v1"] -== Toleration [core/v1] - - -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== - -[id="topologyselectorlabelrequirement-core-v1"] -== TopologySelectorLabelRequirement [core/v1] - - -Description:: - A topology selector requirement is a selector that matches given label. This is an alpha feature and may change in the future. - -Type:: - `object` - -Required:: - - `key` - - `values` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `values` -| `array (string)` -| An array of string values. One value must match the label to be selected. Each entry in Values is ORed. - -|=== - -[id="topologyselectorterm-core-v1"] -== TopologySelectorTerm [core/v1] - - -Description:: - A topology selector term represents the result of label queries. A null or empty topology selector term matches no objects. The requirements of them are ANDed. It provides a subset of functionality as NodeSelectorTerm. This is an alpha feature and may change in the future. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchLabelExpressions` -| xref:../objects/index.adoc#topologyselectorlabelrequirement-core-v1[`array (TopologySelectorLabelRequirement core/v1)`] -| A list of topology selector requirements by labels. - -|=== - -[id="topologyspreadconstraint-core-v1"] -== TopologySpreadConstraint [core/v1] - - -Description:: - TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -Type:: - `object` - -Required:: - - `maxSkew` - - `topologyKey` - - `whenUnsatisfiable` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -| `maxSkew` -| `integer` -| MaxSkew describes the degree to which pods may be unevenly distributed. When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference between the number of matching pods in the target topology and the global minimum. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: \| zone1 \| zone2 \| zone3 \| \| P \| P \| \| - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence to topologies that satisfy it. It's a required field. Default value is 1 and 0 is not allowed. - -| `topologyKey` -| `string` -| TopologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. We consider each <key, value> as a "bucket", and try to put balanced number of pods into each bucket. It's a required field. - -| `whenUnsatisfiable` -| `string` -| WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it. - ScheduleAnyway tells the scheduler to schedule the pod in any location, - but giving higher precedence to topologies that would help reduce the - skew. -A constraint is considered "Unsatisfiable" for an incoming pod if and only if every possible node assigment for that pod would violate "MaxSkew" on some topology. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: \| zone1 \| zone2 \| zone3 \| \| P P P \| P \| P \| If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field. - -|=== - -[id="tunedlist-tuned-openshift-io-v1"] -== TunedList [tuned.openshift.io/v1] - - -Description:: - TunedList is a list of Tuned - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../node_apis/tuned-tuned-openshift-io-v1.adoc#tuned-tuned-openshift-io-v1[`array (Tuned tuned.openshift.io/v1)`] -| List of tuneds. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="typedlocalobjectreference-core-v1"] -== TypedLocalObjectReference [core/v1] - - -Description:: - TypedLocalObjectReference contains enough information to let you locate the typed referenced object inside the same namespace. - -Type:: - `object` - -Required:: - - `kind` - - `name` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required. - -| `kind` -| `string` -| Kind is the type of resource being referenced - -| `name` -| `string` -| Name is the name of resource being referenced - -|=== - -[id="userlist-user-openshift-io-v1"] -== UserList [user.openshift.io/v1] - - -Description:: - UserList is a collection of Users - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`array (User user.openshift.io/v1)`] -| Items is the list of users - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="useroauthaccesstokenlist-oauth-openshift-io-v1"] -== UserOAuthAccessTokenList [oauth.openshift.io/v1] - - -Description:: - UserOAuthAccessTokenList is a collection of access tokens issued on behalf of the requesting user - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../oauth_apis/useroauthaccesstoken-oauth-openshift-io-v1.adoc#useroauthaccesstoken-oauth-openshift-io-v1[`array (UserOAuthAccessToken oauth.openshift.io/v1)`] -| - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| - -|=== - -[id="validatingwebhookconfigurationlist-admissionregistration-k8s-io-v1"] -== ValidatingWebhookConfigurationList [admissionregistration.k8s.io/v1] - - -Description:: - ValidatingWebhookConfigurationList is a list of ValidatingWebhookConfiguration. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../extension_apis/validatingwebhookconfiguration-admissionregistration-k8s-io-v1.adoc#validatingwebhookconfiguration-admissionregistration-k8s-io-v1[`array (ValidatingWebhookConfiguration admissionregistration.k8s.io/v1)`] -| List of ValidatingWebhookConfiguration. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="volume-core-v1"] -== Volume [core/v1] - - -Description:: - Volume represents a named volume in a pod that may be accessed by any container in the pod. - -Type:: - `object` - -Required:: - - `name` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `awsElasticBlockStore` -| xref:../objects/index.adoc#awselasticblockstorevolumesource-core-v1[`AWSElasticBlockStoreVolumeSource core/v1`] -| AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `azureDisk` -| xref:../objects/index.adoc#azurediskvolumesource-core-v1[`AzureDiskVolumeSource core/v1`] -| AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -| `azureFile` -| xref:../objects/index.adoc#azurefilevolumesource-core-v1[`AzureFileVolumeSource core/v1`] -| AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -| `cephfs` -| xref:../objects/index.adoc#cephfsvolumesource-core-v1[`CephFSVolumeSource core/v1`] -| CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -| `cinder` -| xref:../objects/index.adoc#cindervolumesource-core-v1[`CinderVolumeSource core/v1`] -| Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `configMap` -| xref:../objects/index.adoc#configmapvolumesource-core-v1[`ConfigMapVolumeSource core/v1`] -| ConfigMap represents a configMap that should populate this volume - -| `csi` -| xref:../objects/index.adoc#csivolumesource-core-v1[`CSIVolumeSource core/v1`] -| CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). - -| `downwardAPI` -| xref:../objects/index.adoc#downwardapivolumesource-core-v1[`DownwardAPIVolumeSource core/v1`] -| DownwardAPI represents downward API about the pod that should populate this volume - -| `emptyDir` -| xref:../objects/index.adoc#emptydirvolumesource-core-v1[`EmptyDirVolumeSource core/v1`] -| EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `ephemeral` -| xref:../objects/index.adoc#ephemeralvolumesource-core-v1[`EphemeralVolumeSource core/v1`] -| Ephemeral represents a volume that is handled by a cluster storage driver (Alpha feature). The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts, and deleted when the pod is removed. - -Use this if: a) the volume is only needed while the pod runs, b) features of normal volumes like restoring from snapshot or capacity - tracking are needed, -c) the storage driver is specified through a storage class, and d) the storage driver supports dynamic volume provisioning through - a PersistentVolumeClaim (see EphemeralVolumeSource for more - information on the connection between this volume type - and PersistentVolumeClaim). - -Use PersistentVolumeClaim or one of the vendor-specific APIs for volumes that persist for longer than the lifecycle of an individual pod. - -Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to be used that way - see the documentation of the driver for more information. - -A pod can use both types of ephemeral volumes and persistent volumes at the same time. - -| `fc` -| xref:../objects/index.adoc#fcvolumesource-core-v1[`FCVolumeSource core/v1`] -| FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -| `flexVolume` -| xref:../objects/index.adoc#flexvolumesource-core-v1[`FlexVolumeSource core/v1`] -| FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -| `flocker` -| xref:../objects/index.adoc#flockervolumesource-core-v1[`FlockerVolumeSource core/v1`] -| Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -| `gcePersistentDisk` -| xref:../objects/index.adoc#gcepersistentdiskvolumesource-core-v1[`GCEPersistentDiskVolumeSource core/v1`] -| GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `gitRepo` -| xref:../objects/index.adoc#gitrepovolumesource-core-v1[`GitRepoVolumeSource core/v1`] -| GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -| `glusterfs` -| xref:../objects/index.adoc#glusterfsvolumesource-core-v1[`GlusterfsVolumeSource core/v1`] -| Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -| `hostPath` -| xref:../objects/index.adoc#hostpathvolumesource-core-v1[`HostPathVolumeSource core/v1`] -| HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `iscsi` -| xref:../objects/index.adoc#iscsivolumesource-core-v1[`ISCSIVolumeSource core/v1`] -| ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -| `name` -| `string` -| Volume's name. Must be a DNS_LABEL and unique within the pod. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `nfs` -| xref:../objects/index.adoc#nfsvolumesource-core-v1[`NFSVolumeSource core/v1`] -| NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `persistentVolumeClaim` -| xref:../objects/index.adoc#persistentvolumeclaimvolumesource-core-v1[`PersistentVolumeClaimVolumeSource core/v1`] -| PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `photonPersistentDisk` -| xref:../objects/index.adoc#photonpersistentdiskvolumesource-core-v1[`PhotonPersistentDiskVolumeSource core/v1`] -| PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -| `portworxVolume` -| xref:../objects/index.adoc#portworxvolumesource-core-v1[`PortworxVolumeSource core/v1`] -| PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -| `projected` -| xref:../objects/index.adoc#projectedvolumesource-core-v1[`ProjectedVolumeSource core/v1`] -| Items for all in one resources secrets, configmaps, and downward API - -| `quobyte` -| xref:../objects/index.adoc#quobytevolumesource-core-v1[`QuobyteVolumeSource core/v1`] -| Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -| `rbd` -| xref:../objects/index.adoc#rbdvolumesource-core-v1[`RBDVolumeSource core/v1`] -| RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -| `scaleIO` -| xref:../objects/index.adoc#scaleiovolumesource-core-v1[`ScaleIOVolumeSource core/v1`] -| ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -| `secret` -| xref:../objects/index.adoc#secretvolumesource-core-v1[`SecretVolumeSource core/v1`] -| Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -| `storageos` -| xref:../objects/index.adoc#storageosvolumesource-core-v1[`StorageOSVolumeSource core/v1`] -| StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -| `vsphereVolume` -| xref:../objects/index.adoc#vspherevirtualdiskvolumesource-core-v1[`VsphereVirtualDiskVolumeSource core/v1`] -| VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -|=== - -[id="volumeattachmentlist-storage-k8s-io-v1"] -== VolumeAttachmentList [storage.k8s.io/v1] - - -Description:: - VolumeAttachmentList is a collection of VolumeAttachment objects. - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`array (VolumeAttachment storage.k8s.io/v1)`] -| Items is the list of VolumeAttachments - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -|=== - -[id="volumedevice-core-v1"] -== VolumeDevice [core/v1] - - -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `name` - - `devicePath` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== - -[id="volumemount-core-v1"] -== VolumeMount [core/v1] - - -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `name` - - `mountPath` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== - -[id="volumenodeaffinity-core-v1"] -== VolumeNodeAffinity [core/v1] - - -Description:: - VolumeNodeAffinity defines constraints that limit what nodes this volume can be accessed from. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `required` -| xref:../objects/index.adoc#nodeselector-core-v1[`NodeSelector core/v1`] -| Required specifies hard node constraints that must be met. - -|=== - -[id="volumeprojection-core-v1"] -== VolumeProjection [core/v1] - - -Description:: - Projection that may be projected along with other supported volume types - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| xref:../objects/index.adoc#configmapprojection-core-v1[`ConfigMapProjection core/v1`] -| information about the configMap data to project - -| `downwardAPI` -| xref:../objects/index.adoc#downwardapiprojection-core-v1[`DownwardAPIProjection core/v1`] -| information about the downwardAPI data to project - -| `secret` -| xref:../objects/index.adoc#secretprojection-core-v1[`SecretProjection core/v1`] -| information about the secret data to project - -| `serviceAccountToken` -| xref:../objects/index.adoc#serviceaccounttokenprojection-core-v1[`ServiceAccountTokenProjection core/v1`] -| information about the serviceAccountToken data to project - -|=== - -[id="volumesnapshotclasslist-snapshot-storage-k8s-io-v1"] -== VolumeSnapshotClassList [snapshot.storage.k8s.io/v1] - - -Description:: - VolumeSnapshotClassList is a list of VolumeSnapshotClass - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`array (VolumeSnapshotClass snapshot.storage.k8s.io/v1)`] -| List of volumesnapshotclasses. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="volumesnapshotcontentlist-snapshot-storage-k8s-io-v1"] -== VolumeSnapshotContentList [snapshot.storage.k8s.io/v1] - - -Description:: - VolumeSnapshotContentList is a list of VolumeSnapshotContent - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`array (VolumeSnapshotContent snapshot.storage.k8s.io/v1)`] -| List of volumesnapshotcontents. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="volumesnapshotlist-snapshot-storage-k8s-io-v1"] -== VolumeSnapshotList [snapshot.storage.k8s.io/v1] - - -Description:: - VolumeSnapshotList is a list of VolumeSnapshot - -Type:: - `object` - -Required:: - - `items` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `items` -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`array (VolumeSnapshot snapshot.storage.k8s.io/v1)`] -| List of volumesnapshots. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#listmeta-meta-v1[`ListMeta meta/v1`] -| Standard list metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -|=== - -[id="vspherevirtualdiskvolumesource-core-v1"] -== VsphereVirtualDiskVolumeSource [core/v1] - - -Description:: - Represents a vSphere volume resource. - -Type:: - `object` - -Required:: - - `volumePath` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `storagePolicyID` -| `string` -| Storage Policy Based Management (SPBM) profile ID associated with the StoragePolicyName. - -| `storagePolicyName` -| `string` -| Storage Policy Based Management (SPBM) profile name. - -| `volumePath` -| `string` -| Path that identifies vSphere volume vmdk - -|=== - -[id="weightedpodaffinityterm-core-v1"] -== WeightedPodAffinityTerm [core/v1] - - -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `weight` - - `podAffinityTerm` - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| xref:../objects/index.adoc#podaffinityterm-core-v1[`PodAffinityTerm core/v1`] -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== - -[id="windowssecuritycontextoptions-core-v1"] -== WindowsSecurityContextOptions [core/v1] - - -Description:: - WindowsSecurityContextOptions contain Windows-specific options and credentials. - -Type:: - `object` - - -[discrete] -=== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== - diff --git a/rest_api/operator_apis/authentication-operator-openshift-io-v1.adoc b/rest_api/operator_apis/authentication-operator-openshift-io-v1.adoc deleted file mode 100644 index 827fc895531e..000000000000 --- a/rest_api/operator_apis/authentication-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,742 +0,0 @@ -[id="authentication-operator-openshift-io-v1"] -= Authentication [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Authentication provides information to configure an operator to manage authentication. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| - -| `status` -| `object` -| - -|=== -..spec -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `managingOAuthAPIServer` -| `boolean` -| ManagingOAuthAPIServer indicates whether this operator is managing OAuth related APIs. Setting this field to true will cause OAS-O to step down. Note that this field will be removed in the future releases, once https://github.com/openshift/enhancements/blob/master/enhancements/authentication/separate-oauth-resources.md is fully implemented - -| `oauthAPIServer` -| `object` -| OAuthAPIServer holds status specific only to oauth-apiserver - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== -..status.oauthAPIServer -Description:: - OAuthAPIServer holds status specific only to oauth-apiserver - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `latestAvailableRevision` -| `integer` -| LatestAvailableRevision is the latest revision used as suffix of revisioned secrets like encryption-config. A new revision causes a new deployment of pods. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/authentications` -- `DELETE`: delete collection of Authentication -- `GET`: list objects of kind Authentication -- `POST`: create an Authentication -* `/apis/operator.openshift.io/v1/authentications/{name}` -- `DELETE`: delete an Authentication -- `GET`: read the specified Authentication -- `PATCH`: partially update the specified Authentication -- `PUT`: replace the specified Authentication -* `/apis/operator.openshift.io/v1/authentications/{name}/status` -- `GET`: read status of the specified Authentication -- `PATCH`: partially update status of the specified Authentication -- `PUT`: replace status of the specified Authentication - - -=== /apis/operator.openshift.io/v1/authentications - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#authenticationlist-operator-openshift-io-v1[`AuthenticationList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/authentications/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Authentication -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/authentications/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Authentication -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Authentication - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/authentication-operator-openshift-io-v1.adoc#authentication-operator-openshift-io-v1[`Authentication operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/cloudcredential-operator-openshift-io-v1.adoc b/rest_api/operator_apis/cloudcredential-operator-openshift-io-v1.adoc deleted file mode 100644 index 4c876405fc1e..000000000000 --- a/rest_api/operator_apis/cloudcredential-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,719 +0,0 @@ -[id="cloudcredential-operator-openshift-io-v1"] -= CloudCredential [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CloudCredential provides a means to configure an operator to manage CredentialsRequests. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| CloudCredentialSpec is the specification of the desired behavior of the cloud-credential-operator. - -| `status` -| `object` -| CloudCredentialStatus defines the observed status of the cloud-credential-operator. - -|=== -..spec -Description:: - CloudCredentialSpec is the specification of the desired behavior of the cloud-credential-operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `credentialsMode` -| `string` -| CredentialsMode allows informing CCO that it should not attempt to dynamically determine the root cloud credentials capabilities, and it should just run in the specified mode. It also allows putting the operator into "manual" mode if desired. Leaving the field in default mode runs CCO so that the cluster's cloud credentials will be dynamically probed for capabilities (on supported clouds/platforms). - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - CloudCredentialStatus defines the observed status of the cloud-credential-operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/cloudcredentials` -- `DELETE`: delete collection of CloudCredential -- `GET`: list objects of kind CloudCredential -- `POST`: create a CloudCredential -* `/apis/operator.openshift.io/v1/cloudcredentials/{name}` -- `DELETE`: delete a CloudCredential -- `GET`: read the specified CloudCredential -- `PATCH`: partially update the specified CloudCredential -- `PUT`: replace the specified CloudCredential -* `/apis/operator.openshift.io/v1/cloudcredentials/{name}/status` -- `GET`: read status of the specified CloudCredential -- `PATCH`: partially update status of the specified CloudCredential -- `PUT`: replace status of the specified CloudCredential - - -=== /apis/operator.openshift.io/v1/cloudcredentials - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#cloudcredentiallist-operator-openshift-io-v1[`CloudCredentialList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/cloudcredentials/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CloudCredential -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/cloudcredentials/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CloudCredential -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified CloudCredential - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/cloudcredential-operator-openshift-io-v1.adoc#cloudcredential-operator-openshift-io-v1[`CloudCredential operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc b/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc deleted file mode 100644 index 7fff81a68353..000000000000 --- a/rest_api/operator_apis/clustercsidriver-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,715 +0,0 @@ -[id="clustercsidriver-operator-openshift-io-v1"] -= ClusterCSIDriver [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterCSIDriver object allows management and configuration of a CSI driver operator installed by default in OpenShift. Name of the object must be name of the CSI driver it operates. See CSIDriverName type for list of allowed values. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/clustercsidrivers` -- `DELETE`: delete collection of ClusterCSIDriver -- `GET`: list objects of kind ClusterCSIDriver -- `POST`: create a ClusterCSIDriver -* `/apis/operator.openshift.io/v1/clustercsidrivers/{name}` -- `DELETE`: delete a ClusterCSIDriver -- `GET`: read the specified ClusterCSIDriver -- `PATCH`: partially update the specified ClusterCSIDriver -- `PUT`: replace the specified ClusterCSIDriver -* `/apis/operator.openshift.io/v1/clustercsidrivers/{name}/status` -- `GET`: read status of the specified ClusterCSIDriver -- `PATCH`: partially update status of the specified ClusterCSIDriver -- `PUT`: replace status of the specified ClusterCSIDriver - - -=== /apis/operator.openshift.io/v1/clustercsidrivers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clustercsidriverlist-operator-openshift-io-v1[`ClusterCSIDriverList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/clustercsidrivers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterCSIDriver -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/clustercsidrivers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterCSIDriver -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ClusterCSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/clustercsidriver-operator-openshift-io-v1.adoc#clustercsidriver-operator-openshift-io-v1[`ClusterCSIDriver operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/config-imageregistry-operator-openshift-io-v1.adoc b/rest_api/operator_apis/config-imageregistry-operator-openshift-io-v1.adoc deleted file mode 100644 index eec293fb7e1b..000000000000 --- a/rest_api/operator_apis/config-imageregistry-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,2462 +0,0 @@ -[id="config-imageregistry-operator-openshift-io-v1"] -= Config [imageregistry.operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Config is the configuration object for a registry instance managed by the registry operator - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ImageRegistrySpec defines the specs for the running registry. - -| `status` -| `object` -| ImageRegistryStatus reports image registry operational status. - -|=== -..spec -Description:: - ImageRegistrySpec defines the specs for the running registry. - -Type:: - `object` - -Required:: - - `managementState` - - `replicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `affinity` -| `object` -| affinity is a group of node affinity scheduling rules for the image registry pod(s). - -| `defaultRoute` -| `boolean` -| defaultRoute indicates whether an external facing route for the registry should be created using the default generated hostname. - -| `disableRedirect` -| `boolean` -| disableRedirect controls whether to route all data through the Registry, rather than redirecting to the backend. - -| `httpSecret` -| `string` -| httpSecret is the value needed by the registry to secure uploads, generated by default. - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `logging` -| `integer` -| logging is deprecated, use logLevel instead. - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `nodeSelector` -| `object (string)` -| nodeSelector defines the node selection constraints for the registry pod. - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `proxy` -| `object` -| proxy defines the proxy to be used when calling master api, upstream registries, etc. - -| `readOnly` -| `boolean` -| readOnly indicates whether the registry instance should reject attempts to push new images or delete existing ones. - -| `replicas` -| `integer` -| replicas determines the number of registry instances to run. - -| `requests` -| `object` -| requests controls how many parallel requests a given registry instance will handle before queuing additional requests. - -| `resources` -| `object` -| resources defines the resource requests+limits for the registry pod. - -| `rolloutStrategy` -| `string` -| rolloutStrategy defines rollout strategy for the image registry deployment. - -| `routes` -| `array` -| routes defines additional external facing routes which should be created for the registry. - -| `routes[]` -| `object` -| ImageRegistryConfigRoute holds information on external route access to image registry. - -| `storage` -| `object` -| storage details for configuring registry storage, e.g. S3 bucket coordinates. - -| `tolerations` -| `array` -| tolerations defines the tolerations for the registry pod. - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..spec.affinity -Description:: - affinity is a group of node affinity scheduling rules for the image registry pod(s). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeAffinity` -| `object` -| Describes node affinity scheduling rules for the pod. - -| `podAffinity` -| `object` -| Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -| `podAntiAffinity` -| `object` -| Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -|=== -..spec.affinity.nodeAffinity -Description:: - Describes node affinity scheduling rules for the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `object` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -Type:: - `object` - -Required:: - - `preference` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preference` -| `object` -| A node selector term, associated with the corresponding weight. - -| `weight` -| `integer` -| Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference -Description:: - A node selector term, associated with the corresponding weight. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -Type:: - `object` - -Required:: - - `nodeSelectorTerms` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelectorTerms` -| `array` -| Required. A list of node selector terms. The terms are ORed. - -| `nodeSelectorTerms[]` -| `object` -| A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms -Description:: - Required. A list of node selector terms. The terms are ORed. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[] -Description:: - A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity -Description:: - Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity -Description:: - Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.proxy -Description:: - proxy defines the proxy to be used when calling master api, upstream registries, etc. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `http` -| `string` -| http defines the proxy to be used by the image registry when accessing HTTP endpoints. - -| `https` -| `string` -| https defines the proxy to be used by the image registry when accessing HTTPS endpoints. - -| `noProxy` -| `string` -| noProxy defines a comma-separated list of host names that shouldn't go through any proxy. - -|=== -..spec.requests -Description:: - requests controls how many parallel requests a given registry instance will handle before queuing additional requests. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `read` -| `object` -| read defines limits for image registry's reads. - -| `write` -| `object` -| write defines limits for image registry's writes. - -|=== -..spec.requests.read -Description:: - read defines limits for image registry's reads. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxInQueue` -| `integer` -| maxInQueue sets the maximum queued api requests to the registry. - -| `maxRunning` -| `integer` -| maxRunning sets the maximum in flight api requests to the registry. - -| `maxWaitInQueue` -| `string` -| maxWaitInQueue sets the maximum time a request can wait in the queue before being rejected. - -|=== -..spec.requests.write -Description:: - write defines limits for image registry's writes. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxInQueue` -| `integer` -| maxInQueue sets the maximum queued api requests to the registry. - -| `maxRunning` -| `integer` -| maxRunning sets the maximum in flight api requests to the registry. - -| `maxWaitInQueue` -| `string` -| maxWaitInQueue sets the maximum time a request can wait in the queue before being rejected. - -|=== -..spec.resources -Description:: - resources defines the resource requests+limits for the registry pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.routes -Description:: - routes defines additional external facing routes which should be created for the registry. - -Type:: - `array` - - - - -..spec.routes[] -Description:: - ImageRegistryConfigRoute holds information on external route access to image registry. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hostname` -| `string` -| hostname for the route. - -| `name` -| `string` -| name of the route to be created. - -| `secretName` -| `string` -| secretName points to secret containing the certificates to be used by the route. - -|=== -..spec.storage -Description:: - storage details for configuring registry storage, e.g. S3 bucket coordinates. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `azure` -| `object` -| azure represents configuration that uses Azure Blob Storage. - -| `emptyDir` -| `object` -| emptyDir represents ephemeral storage on the pod's host node. WARNING: this storage cannot be used with more than 1 replica and is not suitable for production use. When the pod is removed from a node for any reason, the data in the emptyDir is deleted forever. - -| `gcs` -| `object` -| gcs represents configuration that uses Google Cloud Storage. - -| `managementState` -| `string` -| managementState indicates if the operator manages the underlying storage unit. If Managed the operator will remove the storage when this operator gets Removed. - -| `pvc` -| `object` -| pvc represents configuration that uses a PersistentVolumeClaim. - -| `s3` -| `object` -| s3 represents configuration that uses Amazon Simple Storage Service. - -| `swift` -| `object` -| swift represents configuration that uses OpenStack Object Storage. - -|=== -..spec.storage.azure -Description:: - azure represents configuration that uses Azure Blob Storage. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accountName` -| `string` -| accountName defines the account to be used by the registry. - -| `cloudName` -| `string` -| cloudName is the name of the Azure cloud environment to be used by the registry. If empty, the operator will set it based on the infrastructure object. - -| `container` -| `string` -| container defines Azure's container to be used by registry. - -|=== -..spec.storage.emptyDir -Description:: - emptyDir represents ephemeral storage on the pod's host node. WARNING: this storage cannot be used with more than 1 replica and is not suitable for production use. When the pod is removed from a node for any reason, the data in the emptyDir is deleted forever. - -Type:: - `object` - - - - -..spec.storage.gcs -Description:: - gcs represents configuration that uses Google Cloud Storage. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bucket` -| `string` -| bucket is the bucket name in which you want to store the registry's data. Optional, will be generated if not provided. - -| `keyID` -| `string` -| keyID is the KMS key ID to use for encryption. Optional, buckets are encrypted by default on GCP. This allows for the use of a custom encryption key. - -| `projectID` -| `string` -| projectID is the Project ID of the GCP project that this bucket should be associated with. - -| `region` -| `string` -| region is the GCS location in which your bucket exists. Optional, will be set based on the installed GCS Region. - -|=== -..spec.storage.pvc -Description:: - pvc represents configuration that uses a PersistentVolumeClaim. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `claim` -| `string` -| claim defines the Persisent Volume Claim's name to be used. - -|=== -..spec.storage.s3 -Description:: - s3 represents configuration that uses Amazon Simple Storage Service. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bucket` -| `string` -| bucket is the bucket name in which you want to store the registry's data. Optional, will be generated if not provided. - -| `cloudFront` -| `object` -| cloudFront configures Amazon Cloudfront as the storage middleware in a registry. - -| `encrypt` -| `boolean` -| encrypt specifies whether the registry stores the image in encrypted format or not. Optional, defaults to false. - -| `keyID` -| `string` -| keyID is the KMS key ID to use for encryption. Optional, Encrypt must be true, or this parameter is ignored. - -| `region` -| `string` -| region is the AWS region in which your bucket exists. Optional, will be set based on the installed AWS Region. - -| `regionEndpoint` -| `string` -| regionEndpoint is the endpoint for S3 compatible storage services. Optional, defaults based on the Region that is provided. - -| `virtualHostedStyle` -| `boolean` -| virtualHostedStyle enables using S3 virtual hosted style bucket paths with a custom RegionEndpoint Optional, defaults to false. - -|=== -..spec.storage.s3.cloudFront -Description:: - cloudFront configures Amazon Cloudfront as the storage middleware in a registry. - -Type:: - `object` - -Required:: - - `baseURL` - - `keypairID` - - `privateKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `baseURL` -| `string` -| baseURL contains the SCHEME://HOST[/PATH] at which Cloudfront is served. - -| `duration` -| `string` -| duration is the duration of the Cloudfront session. - -| `keypairID` -| `string` -| keypairID is key pair ID provided by AWS. - -| `privateKey` -| `object` -| privateKey points to secret containing the private key, provided by AWS. - -|=== -..spec.storage.s3.cloudFront.privateKey -Description:: - privateKey points to secret containing the private key, provided by AWS. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.storage.swift -Description:: - swift represents configuration that uses OpenStack Object Storage. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `authURL` -| `string` -| authURL defines the URL for obtaining an authentication token. - -| `authVersion` -| `string` -| authVersion specifies the OpenStack Auth's version. - -| `container` -| `string` -| container defines the name of Swift container where to store the registry's data. - -| `domain` -| `string` -| domain specifies Openstack's domain name for Identity v3 API. - -| `domainID` -| `string` -| domainID specifies Openstack's domain id for Identity v3 API. - -| `regionName` -| `string` -| regionName defines Openstack's region in which container exists. - -| `tenant` -| `string` -| tenant defines Openstack tenant name to be used by registry. - -| `tenantID` -| `string` -| tenant defines Openstack tenant id to be used by registry. - -|=== -..spec.tolerations -Description:: - tolerations defines the tolerations for the registry pod. - -Type:: - `array` - - - - -..spec.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== -..status -Description:: - ImageRegistryStatus reports image registry operational status. - -Type:: - `object` - -Required:: - - `storage` - - `storageManaged` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `storage` -| `object` -| storage indicates the current applied storage configuration of the registry. - -| `storageManaged` -| `boolean` -| storageManaged is deprecated, please refer to Storage.managementState - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== -..status.storage -Description:: - storage indicates the current applied storage configuration of the registry. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `azure` -| `object` -| azure represents configuration that uses Azure Blob Storage. - -| `emptyDir` -| `object` -| emptyDir represents ephemeral storage on the pod's host node. WARNING: this storage cannot be used with more than 1 replica and is not suitable for production use. When the pod is removed from a node for any reason, the data in the emptyDir is deleted forever. - -| `gcs` -| `object` -| gcs represents configuration that uses Google Cloud Storage. - -| `managementState` -| `string` -| managementState indicates if the operator manages the underlying storage unit. If Managed the operator will remove the storage when this operator gets Removed. - -| `pvc` -| `object` -| pvc represents configuration that uses a PersistentVolumeClaim. - -| `s3` -| `object` -| s3 represents configuration that uses Amazon Simple Storage Service. - -| `swift` -| `object` -| swift represents configuration that uses OpenStack Object Storage. - -|=== -..status.storage.azure -Description:: - azure represents configuration that uses Azure Blob Storage. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accountName` -| `string` -| accountName defines the account to be used by the registry. - -| `cloudName` -| `string` -| cloudName is the name of the Azure cloud environment to be used by the registry. If empty, the operator will set it based on the infrastructure object. - -| `container` -| `string` -| container defines Azure's container to be used by registry. - -|=== -..status.storage.emptyDir -Description:: - emptyDir represents ephemeral storage on the pod's host node. WARNING: this storage cannot be used with more than 1 replica and is not suitable for production use. When the pod is removed from a node for any reason, the data in the emptyDir is deleted forever. - -Type:: - `object` - - - - -..status.storage.gcs -Description:: - gcs represents configuration that uses Google Cloud Storage. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bucket` -| `string` -| bucket is the bucket name in which you want to store the registry's data. Optional, will be generated if not provided. - -| `keyID` -| `string` -| keyID is the KMS key ID to use for encryption. Optional, buckets are encrypted by default on GCP. This allows for the use of a custom encryption key. - -| `projectID` -| `string` -| projectID is the Project ID of the GCP project that this bucket should be associated with. - -| `region` -| `string` -| region is the GCS location in which your bucket exists. Optional, will be set based on the installed GCS Region. - -|=== -..status.storage.pvc -Description:: - pvc represents configuration that uses a PersistentVolumeClaim. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `claim` -| `string` -| claim defines the Persisent Volume Claim's name to be used. - -|=== -..status.storage.s3 -Description:: - s3 represents configuration that uses Amazon Simple Storage Service. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bucket` -| `string` -| bucket is the bucket name in which you want to store the registry's data. Optional, will be generated if not provided. - -| `cloudFront` -| `object` -| cloudFront configures Amazon Cloudfront as the storage middleware in a registry. - -| `encrypt` -| `boolean` -| encrypt specifies whether the registry stores the image in encrypted format or not. Optional, defaults to false. - -| `keyID` -| `string` -| keyID is the KMS key ID to use for encryption. Optional, Encrypt must be true, or this parameter is ignored. - -| `region` -| `string` -| region is the AWS region in which your bucket exists. Optional, will be set based on the installed AWS Region. - -| `regionEndpoint` -| `string` -| regionEndpoint is the endpoint for S3 compatible storage services. Optional, defaults based on the Region that is provided. - -| `virtualHostedStyle` -| `boolean` -| virtualHostedStyle enables using S3 virtual hosted style bucket paths with a custom RegionEndpoint Optional, defaults to false. - -|=== -..status.storage.s3.cloudFront -Description:: - cloudFront configures Amazon Cloudfront as the storage middleware in a registry. - -Type:: - `object` - -Required:: - - `baseURL` - - `keypairID` - - `privateKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `baseURL` -| `string` -| baseURL contains the SCHEME://HOST[/PATH] at which Cloudfront is served. - -| `duration` -| `string` -| duration is the duration of the Cloudfront session. - -| `keypairID` -| `string` -| keypairID is key pair ID provided by AWS. - -| `privateKey` -| `object` -| privateKey points to secret containing the private key, provided by AWS. - -|=== -..status.storage.s3.cloudFront.privateKey -Description:: - privateKey points to secret containing the private key, provided by AWS. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..status.storage.swift -Description:: - swift represents configuration that uses OpenStack Object Storage. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `authURL` -| `string` -| authURL defines the URL for obtaining an authentication token. - -| `authVersion` -| `string` -| authVersion specifies the OpenStack Auth's version. - -| `container` -| `string` -| container defines the name of Swift container where to store the registry's data. - -| `domain` -| `string` -| domain specifies Openstack's domain name for Identity v3 API. - -| `domainID` -| `string` -| domainID specifies Openstack's domain id for Identity v3 API. - -| `regionName` -| `string` -| regionName defines Openstack's region in which container exists. - -| `tenant` -| `string` -| tenant defines Openstack tenant name to be used by registry. - -| `tenantID` -| `string` -| tenant defines Openstack tenant id to be used by registry. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/imageregistry.operator.openshift.io/v1/configs` -- `DELETE`: delete collection of Config -- `GET`: list objects of kind Config -- `POST`: create a Config -* `/apis/imageregistry.operator.openshift.io/v1/configs/{name}` -- `DELETE`: delete a Config -- `GET`: read the specified Config -- `PATCH`: partially update the specified Config -- `PUT`: replace the specified Config -* `/apis/imageregistry.operator.openshift.io/v1/configs/{name}/status` -- `GET`: read status of the specified Config -- `PATCH`: partially update status of the specified Config -- `PUT`: replace status of the specified Config - - -=== /apis/imageregistry.operator.openshift.io/v1/configs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#configlist-imageregistry-operator-openshift-io-v1[`ConfigList imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/imageregistry.operator.openshift.io/v1/configs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Config -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/imageregistry.operator.openshift.io/v1/configs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Config -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-imageregistry-operator-openshift-io-v1.adoc#config-imageregistry-operator-openshift-io-v1[`Config imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/config-operator-openshift-io-v1.adoc b/rest_api/operator_apis/config-operator-openshift-io-v1.adoc deleted file mode 100644 index b5599a9702e3..000000000000 --- a/rest_api/operator_apis/config-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,715 +0,0 @@ -[id="config-operator-openshift-io-v1"] -= Config [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Config provides information to configure the config operator. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of the Config Operator. - -| `status` -| `object` -| status defines the observed status of the Config Operator. - -|=== -..spec -Description:: - spec is the specification of the desired behavior of the Config Operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status defines the observed status of the Config Operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/configs` -- `DELETE`: delete collection of Config -- `GET`: list objects of kind Config -- `POST`: create a Config -* `/apis/operator.openshift.io/v1/configs/{name}` -- `DELETE`: delete a Config -- `GET`: read the specified Config -- `PATCH`: partially update the specified Config -- `PUT`: replace the specified Config -* `/apis/operator.openshift.io/v1/configs/{name}/status` -- `GET`: read status of the specified Config -- `PATCH`: partially update status of the specified Config -- `PUT`: replace status of the specified Config - - -=== /apis/operator.openshift.io/v1/configs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#configlist-operator-openshift-io-v1[`ConfigList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/configs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Config -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/configs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Config -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-operator-openshift-io-v1.adoc#config-operator-openshift-io-v1[`Config operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/config-samples-operator-openshift-io-v1.adoc b/rest_api/operator_apis/config-samples-operator-openshift-io-v1.adoc deleted file mode 100644 index 7b142a8fe0cb..000000000000 --- a/rest_api/operator_apis/config-samples-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,676 +0,0 @@ -[id="config-samples-operator-openshift-io-v1"] -= Config [samples.operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Config contains the configuration and detailed condition status for the Samples Operator. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ConfigSpec contains the desired configuration and state for the Samples Operator, controlling various behavior around the imagestreams and templates it creates/updates in the openshift namespace. - -| `status` -| `object` -| ConfigStatus contains the actual configuration in effect, as well as various details that describe the state of the Samples Operator. - -|=== -..spec -Description:: - ConfigSpec contains the desired configuration and state for the Samples Operator, controlling various behavior around the imagestreams and templates it creates/updates in the openshift namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `architectures` -| `array (string)` -| architectures determine which hardware architecture(s) to install, where x86_64, ppc64le, and s390x are the only supported choices currently. - -| `managementState` -| `string` -| managementState is top level on/off type of switch for all operators. When "Managed", this operator processes config and manipulates the samples accordingly. When "Unmanaged", this operator ignores any updates to the resources it watches. When "Removed", it reacts that same wasy as it does if the Config object is deleted, meaning any ImageStreams or Templates it manages (i.e. it honors the skipped lists) and the registry secret are deleted, along with the ConfigMap in the operator's namespace that represents the last config used to manipulate the samples, - -| `samplesRegistry` -| `string` -| samplesRegistry allows for the specification of which registry is accessed by the ImageStreams for their image content. Defaults on the content in https://github.com/openshift/library that are pulled into this github repository, but based on our pulling only ocp content it typically defaults to registry.redhat.io. - -| `skippedImagestreams` -| `array (string)` -| skippedImagestreams specifies names of image streams that should NOT be created/updated. Admins can use this to allow them to delete content they don’t want. They will still have to manually delete the content but the operator will not recreate(or update) anything listed here. - -| `skippedTemplates` -| `array (string)` -| skippedTemplates specifies names of templates that should NOT be created/updated. Admins can use this to allow them to delete content they don’t want. They will still have to manually delete the content but the operator will not recreate(or update) anything listed here. - -|=== -..status -Description:: - ConfigStatus contains the actual configuration in effect, as well as various details that describe the state of the Samples Operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `architectures` -| `array (string)` -| architectures determine which hardware architecture(s) to install, where x86_64 and ppc64le are the supported choices. - -| `conditions` -| `array` -| conditions represents the available maintenance status of the sample imagestreams and templates. - -| `conditions[]` -| `object` -| ConfigCondition captures various conditions of the Config as entries are processed. - -| `managementState` -| `string` -| managementState reflects the current operational status of the on/off switch for the operator. This operator compares the ManagementState as part of determining that we are turning the operator back on (i.e. "Managed") when it was previously "Unmanaged". - -| `samplesRegistry` -| `string` -| samplesRegistry allows for the specification of which registry is accessed by the ImageStreams for their image content. Defaults on the content in https://github.com/openshift/library that are pulled into this github repository, but based on our pulling only ocp content it typically defaults to registry.redhat.io. - -| `skippedImagestreams` -| `array (string)` -| skippedImagestreams specifies names of image streams that should NOT be created/updated. Admins can use this to allow them to delete content they don’t want. They will still have to manually delete the content but the operator will not recreate(or update) anything listed here. - -| `skippedTemplates` -| `array (string)` -| skippedTemplates specifies names of templates that should NOT be created/updated. Admins can use this to allow them to delete content they don’t want. They will still have to manually delete the content but the operator will not recreate(or update) anything listed here. - -| `version` -| `string` -| version is the value of the operator's payload based version indicator when it was last successfully processed - -|=== -..status.conditions -Description:: - conditions represents the available maintenance status of the sample imagestreams and templates. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - ConfigCondition captures various conditions of the Config as entries are processed. - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| lastTransitionTime is the last time the condition transitioned from one status to another. - -| `lastUpdateTime` -| `string` -| lastUpdateTime is the last time this condition was updated. - -| `message` -| `string` -| message is a human readable message indicating details about the transition. - -| `reason` -| `string` -| reason is what caused the condition's last transition. - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type of condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/samples.operator.openshift.io/v1/configs` -- `DELETE`: delete collection of Config -- `GET`: list objects of kind Config -- `POST`: create a Config -* `/apis/samples.operator.openshift.io/v1/configs/{name}` -- `DELETE`: delete a Config -- `GET`: read the specified Config -- `PATCH`: partially update the specified Config -- `PUT`: replace the specified Config -* `/apis/samples.operator.openshift.io/v1/configs/{name}/status` -- `GET`: read status of the specified Config -- `PATCH`: partially update status of the specified Config -- `PUT`: replace status of the specified Config - - -=== /apis/samples.operator.openshift.io/v1/configs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#configlist-samples-operator-openshift-io-v1[`ConfigList samples.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/samples.operator.openshift.io/v1/configs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Config -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/samples.operator.openshift.io/v1/configs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Config -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Config - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/config-samples-operator-openshift-io-v1.adoc#config-samples-operator-openshift-io-v1[`Config samples.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/console-operator-openshift-io-v1.adoc b/rest_api/operator_apis/console-operator-openshift-io-v1.adoc deleted file mode 100644 index 83c0ca4dad51..000000000000 --- a/rest_api/operator_apis/console-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,978 +0,0 @@ -[id="console-operator-openshift-io-v1"] -= Console [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Console provides a means to configure an operator to manage the console. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ConsoleSpec is the specification of the desired behavior of the Console. - -| `status` -| `object` -| ConsoleStatus defines the observed status of the Console. - -|=== -..spec -Description:: - ConsoleSpec is the specification of the desired behavior of the Console. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `customization` -| `object` -| customization is used to optionally provide a small set of customization options to the web console. - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `providers` -| `object` -| providers contains configuration for using specific service providers. - -| `route` -| `object` -| route contains hostname and secret reference that contains the serving certificate. If a custom route is specified, a new route will be created with the provided hostname, under which console will be available. In case of custom hostname uses the default routing suffix of the cluster, the Secret specification for a serving certificate will not be needed. In case of custom hostname points to an arbitrary domain, manual DNS configurations steps are necessary. The default console route will be maintained to reserve the default hostname for console if the custom route is removed. If not specified, default route will be used. - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..spec.customization -Description:: - customization is used to optionally provide a small set of customization options to the web console. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `brand` -| `string` -| brand is the default branding of the web console which can be overridden by providing the brand field. There is a limited set of specific brand options. This field controls elements of the console such as the logo. Invalid value will prevent a console rollout. - -| `customLogoFile` -| `object` -| customLogoFile replaces the default OpenShift logo in the masthead and about dialog. It is a reference to a ConfigMap in the openshift-config namespace. This can be created with a command like 'oc create configmap custom-logo --from-file=/path/to/file -n openshift-config'. Image size must be less than 1 MB due to constraints on the ConfigMap size. The ConfigMap key should include a file extension so that the console serves the file with the correct MIME type. Recommended logo specifications: Dimensions: Max height of 68px and max width of 200px SVG format preferred - -| `customProductName` -| `string` -| customProductName is the name that will be displayed in page titles, logo alt text, and the about dialog instead of the normal OpenShift product name. - -| `developerCatalog` -| `object` -| developerCatalog allows to configure the shown developer catalog categories. - -| `documentationBaseURL` -| `string` -| documentationBaseURL links to external documentation are shown in various sections of the web console. Providing documentationBaseURL will override the default documentation URL. Invalid value will prevent a console rollout. - -|=== -..spec.customization.customLogoFile -Description:: - customLogoFile replaces the default OpenShift logo in the masthead and about dialog. It is a reference to a ConfigMap in the openshift-config namespace. This can be created with a command like 'oc create configmap custom-logo --from-file=/path/to/file -n openshift-config'. Image size must be less than 1 MB due to constraints on the ConfigMap size. The ConfigMap key should include a file extension so that the console serves the file with the correct MIME type. Recommended logo specifications: Dimensions: Max height of 68px and max width of 200px SVG format preferred - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| Key allows pointing to a specific key/value inside of the configmap. This is useful for logical file references. - -| `name` -| `string` -| - -|=== -..spec.customization.developerCatalog -Description:: - developerCatalog allows to configure the shown developer catalog categories. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `categories` -| `array` -| categories which are shown in the developer catalog. - -| `categories[]` -| `object` -| DeveloperConsoleCatalogCategory for the developer console catalog. - -|=== -..spec.customization.developerCatalog.categories -Description:: - categories which are shown in the developer catalog. - -Type:: - `array` - - - - -..spec.customization.developerCatalog.categories[] -Description:: - DeveloperConsoleCatalogCategory for the developer console catalog. - -Type:: - `object` - -Required:: - - `id` - - `label` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `id` -| `string` -| ID is an identifier used in the URL to enable deep linking in console. ID is required and must have 1-32 URL safe (A-Z, a-z, 0-9, - and _) characters. - -| `label` -| `string` -| label defines a category display label. It is required and must have 1-64 characters. - -| `subcategories` -| `array` -| subcategories defines a list of child categories. - -| `subcategories[]` -| `object` -| DeveloperConsoleCatalogCategoryMeta are the key identifiers of a developer catalog category. - -| `tags` -| `array (string)` -| tags is a list of strings that will match the category. A selected category show all items which has at least one overlapping tag between category and item. - -|=== -..spec.customization.developerCatalog.categories[].subcategories -Description:: - subcategories defines a list of child categories. - -Type:: - `array` - - - - -..spec.customization.developerCatalog.categories[].subcategories[] -Description:: - DeveloperConsoleCatalogCategoryMeta are the key identifiers of a developer catalog category. - -Type:: - `object` - -Required:: - - `id` - - `label` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `id` -| `string` -| ID is an identifier used in the URL to enable deep linking in console. ID is required and must have 1-32 URL safe (A-Z, a-z, 0-9, - and _) characters. - -| `label` -| `string` -| label defines a category display label. It is required and must have 1-64 characters. - -| `tags` -| `array (string)` -| tags is a list of strings that will match the category. A selected category show all items which has at least one overlapping tag between category and item. - -|=== -..spec.providers -Description:: - providers contains configuration for using specific service providers. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `statuspage` -| `object` -| statuspage contains ID for statuspage.io page that provides status info about. - -|=== -..spec.providers.statuspage -Description:: - statuspage contains ID for statuspage.io page that provides status info about. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `pageID` -| `string` -| pageID is the unique ID assigned by Statuspage for your page. This must be a public page. - -|=== -..spec.route -Description:: - route contains hostname and secret reference that contains the serving certificate. If a custom route is specified, a new route will be created with the provided hostname, under which console will be available. In case of custom hostname uses the default routing suffix of the cluster, the Secret specification for a serving certificate will not be needed. In case of custom hostname points to an arbitrary domain, manual DNS configurations steps are necessary. The default console route will be maintained to reserve the default hostname for console if the custom route is removed. If not specified, default route will be used. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hostname` -| `string` -| hostname is the desired custom domain under which console will be available. - -| `secret` -| `object` -| secret points to secret in the openshift-config namespace that contains custom certificate and key and needs to be created manually by the cluster admin. Referenced Secret is required to contain following key value pairs: - "tls.crt" - to specifies custom certificate - "tls.key" - to specifies private key of the custom certificate If the custom hostname uses the default routing suffix of the cluster, the Secret specification for a serving certificate will not be needed. - -|=== -..spec.route.secret -Description:: - secret points to secret in the openshift-config namespace that contains custom certificate and key and needs to be created manually by the cluster admin. Referenced Secret is required to contain following key value pairs: - "tls.crt" - to specifies custom certificate - "tls.key" - to specifies private key of the custom certificate If the custom hostname uses the default routing suffix of the cluster, the Secret specification for a serving certificate will not be needed. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the metadata.name of the referenced secret - -|=== -..status -Description:: - ConsoleStatus defines the observed status of the Console. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/consoles` -- `DELETE`: delete collection of Console -- `GET`: list objects of kind Console -- `POST`: create a Console -* `/apis/operator.openshift.io/v1/consoles/{name}` -- `DELETE`: delete a Console -- `GET`: read the specified Console -- `PATCH`: partially update the specified Console -- `PUT`: replace the specified Console -* `/apis/operator.openshift.io/v1/consoles/{name}/status` -- `GET`: read status of the specified Console -- `PATCH`: partially update status of the specified Console -- `PUT`: replace status of the specified Console - - -=== /apis/operator.openshift.io/v1/consoles - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#consolelist-operator-openshift-io-v1[`ConsoleList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/consoles/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Console -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/consoles/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Console -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Console - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/console-operator-openshift-io-v1.adoc#console-operator-openshift-io-v1[`Console operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc b/rest_api/operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc deleted file mode 100644 index d0fbcf904bf2..000000000000 --- a/rest_api/operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,715 +0,0 @@ -[id="csisnapshotcontroller-operator-openshift-io-v1"] -= CSISnapshotController [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CSISnapshotController provides a means to configure an operator to manage the CSI snapshots. `cluster` is the canonical name. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/csisnapshotcontrollers` -- `DELETE`: delete collection of CSISnapshotController -- `GET`: list objects of kind CSISnapshotController -- `POST`: create a CSISnapshotController -* `/apis/operator.openshift.io/v1/csisnapshotcontrollers/{name}` -- `DELETE`: delete a CSISnapshotController -- `GET`: read the specified CSISnapshotController -- `PATCH`: partially update the specified CSISnapshotController -- `PUT`: replace the specified CSISnapshotController -* `/apis/operator.openshift.io/v1/csisnapshotcontrollers/{name}/status` -- `GET`: read status of the specified CSISnapshotController -- `PATCH`: partially update status of the specified CSISnapshotController -- `PUT`: replace status of the specified CSISnapshotController - - -=== /apis/operator.openshift.io/v1/csisnapshotcontrollers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#csisnapshotcontrollerlist-operator-openshift-io-v1[`CSISnapshotControllerList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/csisnapshotcontrollers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CSISnapshotController -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/csisnapshotcontrollers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CSISnapshotController -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified CSISnapshotController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/csisnapshotcontroller-operator-openshift-io-v1.adoc#csisnapshotcontroller-operator-openshift-io-v1[`CSISnapshotController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/dns-operator-openshift-io-v1.adoc b/rest_api/operator_apis/dns-operator-openshift-io-v1.adoc deleted file mode 100644 index 0ce577503871..000000000000 --- a/rest_api/operator_apis/dns-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,712 +0,0 @@ -[id="dns-operator-openshift-io-v1"] -= DNS [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - DNS manages the CoreDNS component to provide a name resolution service for pods and services in the cluster. - This supports the DNS-based service discovery specification: https://github.com/kubernetes/dns/blob/master/docs/specification.md - More details: https://kubernetes.io/docs/tasks/administer-cluster/coredns - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of the DNS. - -| `status` -| `object` -| status is the most recently observed status of the DNS. - -|=== -..spec -Description:: - spec is the specification of the desired behavior of the DNS. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `servers` -| `array` -| servers is a list of DNS resolvers that provide name query delegation for one or more subdomains outside the scope of the cluster domain. If servers consists of more than one Server, longest suffix match will be used to determine the Server. - For example, if there are two Servers, one for "foo.com" and another for "a.foo.com", and the name query is for "www.a.foo.com", it will be routed to the Server with Zone "a.foo.com". - If this field is nil, no servers are created. - -| `servers[]` -| `object` -| Server defines the schema for a server that runs per instance of CoreDNS. - -|=== -..spec.servers -Description:: - servers is a list of DNS resolvers that provide name query delegation for one or more subdomains outside the scope of the cluster domain. If servers consists of more than one Server, longest suffix match will be used to determine the Server. - For example, if there are two Servers, one for "foo.com" and another for "a.foo.com", and the name query is for "www.a.foo.com", it will be routed to the Server with Zone "a.foo.com". - If this field is nil, no servers are created. - -Type:: - `array` - - - - -..spec.servers[] -Description:: - Server defines the schema for a server that runs per instance of CoreDNS. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `forwardPlugin` -| `object` -| forwardPlugin defines a schema for configuring CoreDNS to proxy DNS messages to upstream resolvers. - -| `name` -| `string` -| name is required and specifies a unique name for the server. Name must comply with the Service Name Syntax of rfc6335. - -| `zones` -| `array (string)` -| zones is required and specifies the subdomains that Server is authoritative for. Zones must conform to the rfc1123 definition of a subdomain. Specifying the cluster domain (i.e., "cluster.local") is invalid. - -|=== -..spec.servers[].forwardPlugin -Description:: - forwardPlugin defines a schema for configuring CoreDNS to proxy DNS messages to upstream resolvers. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `upstreams` -| `array (string)` -| upstreams is a list of resolvers to forward name queries for subdomains of Zones. Upstreams are randomized when more than 1 upstream is specified. Each instance of CoreDNS performs health checking of Upstreams. When a healthy upstream returns an error during the exchange, another resolver is tried from Upstreams. Each upstream is represented by an IP address or IP:port if the upstream listens on a port other than 53. - A maximum of 15 upstreams is allowed per ForwardPlugin. - -|=== -..status -Description:: - status is the most recently observed status of the DNS. - -Type:: - `object` - -Required:: - - `clusterDomain` - - `clusterIP` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clusterDomain` -| `string` -| clusterDomain is the local cluster DNS domain suffix for DNS services. This will be a subdomain as defined in RFC 1034, section 3.5: https://tools.ietf.org/html/rfc1034#section-3.5 Example: "cluster.local" - More info: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service - -| `clusterIP` -| `string` -| clusterIP is the service IP through which this DNS is made available. - In the case of the default DNS, this will be a well known IP that is used as the default nameserver for pods that are using the default ClusterFirst DNS policy. - In general, this IP can be specified in a pod's spec.dnsConfig.nameservers list or used explicitly when performing name resolution from within the cluster. Example: dig foo.com @<service IP> - More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies - -| `conditions` -| `array` -| conditions provide information about the state of the DNS on the cluster. - These are the supported DNS conditions: - * Available - True if the following conditions are met: * DNS controller daemonset is available. - False if any of those conditions are unsatisfied. - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -|=== -..status.conditions -Description:: - conditions provide information about the state of the DNS on the cluster. - These are the supported DNS conditions: - * Available - True if the following conditions are met: * DNS controller daemonset is available. - False if any of those conditions are unsatisfied. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/dnses` -- `DELETE`: delete collection of DNS -- `GET`: list objects of kind DNS -- `POST`: create a DNS -* `/apis/operator.openshift.io/v1/dnses/{name}` -- `DELETE`: delete a DNS -- `GET`: read the specified DNS -- `PATCH`: partially update the specified DNS -- `PUT`: replace the specified DNS -* `/apis/operator.openshift.io/v1/dnses/{name}/status` -- `GET`: read status of the specified DNS -- `PATCH`: partially update status of the specified DNS -- `PUT`: replace status of the specified DNS - - -=== /apis/operator.openshift.io/v1/dnses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#dnslist-operator-openshift-io-v1[`DNSList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/dnses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DNS -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/dnses/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DNS -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified DNS - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/dns-operator-openshift-io-v1.adoc#dns-operator-openshift-io-v1[`DNS operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc b/rest_api/operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc deleted file mode 100644 index 68f37f881848..000000000000 --- a/rest_api/operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,798 +0,0 @@ -[id="dnsrecord-ingress-operator-openshift-io-v1"] -= DNSRecord [ingress.operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - DNSRecord is a DNS record managed in the zones defined by dns.config.openshift.io/cluster .spec.publicZone and .spec.privateZone. - Cluster admin manipulation of this resource is not supported. This resource is only for internal communication of OpenShift operators. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of the dnsecord. - -| `status` -| `object` -| status is the most recently observed status of the dnsRecord. - -|=== -..spec -Description:: - spec is the specification of the desired behavior of the dnsecord. - -Type:: - `object` - -Required:: - - `dnsName` - - `recordTTL` - - `recordType` - - `targets` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `dnsName` -| `string` -| dnsName is the hostname of the DNS record - -| `recordTTL` -| `integer` -| recordTTL is the record TTL in seconds. If zero, the default is 30. RecordTTL will not be used in AWS regions Alias targets, but will be used in CNAME targets, per AWS API contract. - -| `recordType` -| `string` -| recordType is the DNS record type. For example, "A" or "CNAME". - -| `targets` -| `array (string)` -| targets are record targets. - -|=== -..status -Description:: - status is the most recently observed status of the dnsRecord. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `observedGeneration` -| `integer` -| observedGeneration is the most recently observed generation of the DNSRecord. When the DNSRecord is updated, the controller updates the corresponding record in each managed zone. If an update for a particular zone fails, that failure is recorded in the status condition for the zone so that the controller can determine that it needs to retry the update for that specific zone. - -| `zones` -| `array` -| zones are the status of the record in each zone. - -| `zones[]` -| `object` -| DNSZoneStatus is the status of a record within a specific zone. - -|=== -..status.zones -Description:: - zones are the status of the record in each zone. - -Type:: - `array` - - - - -..status.zones[] -Description:: - DNSZoneStatus is the status of a record within a specific zone. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions are any conditions associated with the record in the zone. - If publishing the record fails, the "Failed" condition will be set with a reason and message describing the cause of the failure. - -| `conditions[]` -| `object` -| DNSZoneCondition is just the standard condition fields. - -| `dnsZone` -| `object` -| dnsZone is the zone where the record is published. - -|=== -..status.zones[].conditions -Description:: - conditions are any conditions associated with the record in the zone. - If publishing the record fails, the "Failed" condition will be set with a reason and message describing the cause of the failure. - -Type:: - `array` - - - - -..status.zones[].conditions[] -Description:: - DNSZoneCondition is just the standard condition fields. - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.zones[].dnsZone -Description:: - dnsZone is the zone where the record is published. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `id` -| `string` -| id is the identifier that can be used to find the DNS hosted zone. - on AWS zone can be fetched using `ID` as id in [1] on Azure zone can be fetched using `ID` as a pre-determined name in [2], on GCP zone can be fetched using `ID` as a pre-determined name in [3]. - [1]: https://docs.aws.amazon.com/cli/latest/reference/route53/get-hosted-zone.html#options [2]: https://docs.microsoft.com/en-us/cli/azure/network/dns/zone?view=azure-cli-latest#az-network-dns-zone-show [3]: https://cloud.google.com/dns/docs/reference/v1/managedZones/get - -| `tags` -| `object (string)` -| tags can be used to query the DNS hosted zone. - on AWS, resourcegroupstaggingapi [1] can be used to fetch a zone using `Tags` as tag-filters, - [1]: https://docs.aws.amazon.com/cli/latest/reference/resourcegroupstaggingapi/get-resources.html#options - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/ingress.operator.openshift.io/v1/dnsrecords` -- `GET`: list objects of kind DNSRecord -* `/apis/ingress.operator.openshift.io/v1/namespaces/{namespace}/dnsrecords` -- `DELETE`: delete collection of DNSRecord -- `GET`: list objects of kind DNSRecord -- `POST`: create a DNSRecord -* `/apis/ingress.operator.openshift.io/v1/namespaces/{namespace}/dnsrecords/{name}` -- `DELETE`: delete a DNSRecord -- `GET`: read the specified DNSRecord -- `PATCH`: partially update the specified DNSRecord -- `PUT`: replace the specified DNSRecord -* `/apis/ingress.operator.openshift.io/v1/namespaces/{namespace}/dnsrecords/{name}/status` -- `GET`: read status of the specified DNSRecord -- `PATCH`: partially update status of the specified DNSRecord -- `PUT`: replace status of the specified DNSRecord - - -=== /apis/ingress.operator.openshift.io/v1/dnsrecords - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind DNSRecord - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#dnsrecordlist-ingress-operator-openshift-io-v1[`DNSRecordList ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/ingress.operator.openshift.io/v1/namespaces/{namespace}/dnsrecords - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#dnsrecordlist-ingress-operator-openshift-io-v1[`DNSRecordList ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/ingress.operator.openshift.io/v1/namespaces/{namespace}/dnsrecords/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DNSRecord -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/ingress.operator.openshift.io/v1/namespaces/{namespace}/dnsrecords/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DNSRecord -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified DNSRecord - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/dnsrecord-ingress-operator-openshift-io-v1.adoc#dnsrecord-ingress-operator-openshift-io-v1[`DNSRecord ingress.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc b/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc deleted file mode 100644 index f353860851eb..000000000000 --- a/rest_api/operator_apis/etcd-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,788 +0,0 @@ -[id="etcd-operator-openshift-io-v1"] -= Etcd [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Etcd provides information to configure an operator to manage kube-apiserver. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| - -| `status` -| `object` -| - -|=== -..spec -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `failedRevisionLimit` -| `integer` -| failedRevisionLimit is the number of failed static pod installer revisions to keep on disk and in the api -1 = unlimited, 0 or unset = 5 (default) - -| `forceRedeploymentReason` -| `string` -| forceRedeploymentReason can be used to force the redeployment of the operand by providing a unique string. This provides a mechanism to kick a previously failed deployment and provide a reason why you think it will work this time instead of failing again on the same config. - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `succeededRevisionLimit` -| `integer` -| succeededRevisionLimit is the number of successful static pod installer revisions to keep on disk and in the api -1 = unlimited, 0 or unset = 5 (default) - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `latestAvailableRevision` -| `integer` -| latestAvailableRevision is the deploymentID of the most recent deployment - -| `latestAvailableRevisionReason` -| `string` -| latestAvailableRevisionReason describe the detailed reason for the most recent deployment - -| `nodeStatuses` -| `array` -| nodeStatuses track the deployment values and errors across individual nodes - -| `nodeStatuses[]` -| `object` -| NodeStatus provides information about the current state of a particular node managed by this operator. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== -..status.nodeStatuses -Description:: - nodeStatuses track the deployment values and errors across individual nodes - -Type:: - `array` - - - - -..status.nodeStatuses[] -Description:: - NodeStatus provides information about the current state of a particular node managed by this operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `currentRevision` -| `integer` -| currentRevision is the generation of the most recently successful deployment - -| `lastFailedRevision` -| `integer` -| lastFailedRevision is the generation of the deployment we tried and failed to deploy. - -| `lastFailedRevisionErrors` -| `array (string)` -| lastFailedRevisionErrors is a list of the errors during the failed deployment referenced in lastFailedRevision - -| `nodeName` -| `string` -| nodeName is the name of the node - -| `targetRevision` -| `integer` -| targetRevision is the generation of the deployment we're trying to apply - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/etcds` -- `DELETE`: delete collection of Etcd -- `GET`: list objects of kind Etcd -- `POST`: create an Etcd -* `/apis/operator.openshift.io/v1/etcds/{name}` -- `DELETE`: delete an Etcd -- `GET`: read the specified Etcd -- `PATCH`: partially update the specified Etcd -- `PUT`: replace the specified Etcd -* `/apis/operator.openshift.io/v1/etcds/{name}/status` -- `GET`: read status of the specified Etcd -- `PATCH`: partially update status of the specified Etcd -- `PUT`: replace status of the specified Etcd - - -=== /apis/operator.openshift.io/v1/etcds - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#etcdlist-operator-openshift-io-v1[`EtcdList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/etcds/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Etcd -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/etcds/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Etcd -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Etcd - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/etcd-operator-openshift-io-v1.adoc#etcd-operator-openshift-io-v1[`Etcd operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc b/rest_api/operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc deleted file mode 100644 index c68c45fc3500..000000000000 --- a/rest_api/operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc +++ /dev/null @@ -1,599 +0,0 @@ -[id="imagecontentsourcepolicy-operator-openshift-io-v1alpha1"] -= ImageContentSourcePolicy [operator.openshift.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ImageContentSourcePolicy holds cluster-wide information about how to handle registry mirror rules. When multiple policies are defined, the outcome of the behavior is defined on each field. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `repositoryDigestMirrors` -| `array` -| repositoryDigestMirrors allows images referenced by image digests in pods to be pulled from alternative mirrored repository locations. The image pull specification provided to the pod will be compared to the source locations described in RepositoryDigestMirrors and the image may be pulled down from any of the mirrors in the list instead of the specified repository allowing administrators to choose a potentially faster mirror. Only image pull specifications that have an image disgest will have this behavior applied to them - tags will continue to be pulled from the specified repository in the pull spec. - Each “source” repository is treated independently; configurations for different “source” repositories don’t interact. - When multiple policies are defined for the same “source” repository, the sets of defined mirrors will be merged together, preserving the relative order of the mirrors, if possible. For example, if policy A has mirrors `a, b, c` and policy B has mirrors `c, d, e`, the mirrors will be used in the order `a, b, c, d, e`. If the orders of mirror entries conflict (e.g. `a, b` vs. `b, a`) the configuration is not rejected but the resulting order is unspecified. - -| `repositoryDigestMirrors[]` -| `object` -| RepositoryDigestMirrors holds cluster-wide information about how to handle mirros in the registries config. Note: the mirrors only work when pulling the images that are referenced by their digests. - -|=== -..spec.repositoryDigestMirrors -Description:: - repositoryDigestMirrors allows images referenced by image digests in pods to be pulled from alternative mirrored repository locations. The image pull specification provided to the pod will be compared to the source locations described in RepositoryDigestMirrors and the image may be pulled down from any of the mirrors in the list instead of the specified repository allowing administrators to choose a potentially faster mirror. Only image pull specifications that have an image disgest will have this behavior applied to them - tags will continue to be pulled from the specified repository in the pull spec. - Each “source” repository is treated independently; configurations for different “source” repositories don’t interact. - When multiple policies are defined for the same “source” repository, the sets of defined mirrors will be merged together, preserving the relative order of the mirrors, if possible. For example, if policy A has mirrors `a, b, c` and policy B has mirrors `c, d, e`, the mirrors will be used in the order `a, b, c, d, e`. If the orders of mirror entries conflict (e.g. `a, b` vs. `b, a`) the configuration is not rejected but the resulting order is unspecified. - -Type:: - `array` - - - - -..spec.repositoryDigestMirrors[] -Description:: - RepositoryDigestMirrors holds cluster-wide information about how to handle mirros in the registries config. Note: the mirrors only work when pulling the images that are referenced by their digests. - -Type:: - `object` - -Required:: - - `source` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mirrors` -| `array (string)` -| mirrors is one or more repositories that may also contain the same images. The order of mirrors in this list is treated as the user's desired priority, while source is by default considered lower priority than all mirrors. Other cluster configuration, including (but not limited to) other repositoryDigestMirrors objects, may impact the exact order mirrors are contacted in, or some mirrors may be contacted in parallel, so this should be considered a preference rather than a guarantee of ordering. - -| `source` -| `string` -| source is the repository that users refer to, e.g. in image pull specifications. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1alpha1/imagecontentsourcepolicies` -- `DELETE`: delete collection of ImageContentSourcePolicy -- `GET`: list objects of kind ImageContentSourcePolicy -- `POST`: create an ImageContentSourcePolicy -* `/apis/operator.openshift.io/v1alpha1/imagecontentsourcepolicies/{name}` -- `DELETE`: delete an ImageContentSourcePolicy -- `GET`: read the specified ImageContentSourcePolicy -- `PATCH`: partially update the specified ImageContentSourcePolicy -- `PUT`: replace the specified ImageContentSourcePolicy -* `/apis/operator.openshift.io/v1alpha1/imagecontentsourcepolicies/{name}/status` -- `GET`: read status of the specified ImageContentSourcePolicy -- `PATCH`: partially update status of the specified ImageContentSourcePolicy -- `PUT`: replace status of the specified ImageContentSourcePolicy - - -=== /apis/operator.openshift.io/v1alpha1/imagecontentsourcepolicies - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imagecontentsourcepolicylist-operator-openshift-io-v1alpha1[`ImageContentSourcePolicyList operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 201 - Created -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 202 - Accepted -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1alpha1/imagecontentsourcepolicies/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageContentSourcePolicy -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 201 - Created -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1alpha1/imagecontentsourcepolicies/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImageContentSourcePolicy -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ImageContentSourcePolicy - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 201 - Created -| xref:../operator_apis/imagecontentsourcepolicy-operator-openshift-io-v1alpha1.adoc#imagecontentsourcepolicy-operator-openshift-io-v1alpha1[`ImageContentSourcePolicy operator.openshift.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc b/rest_api/operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc deleted file mode 100644 index 5633d643de04..000000000000 --- a/rest_api/operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,1639 +0,0 @@ -[id="imagepruner-imageregistry-operator-openshift-io-v1"] -= ImagePruner [imageregistry.operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ImagePruner is the configuration object for an image registry pruner managed by the registry operator. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ImagePrunerSpec defines the specs for the running image pruner. - -| `status` -| `object` -| ImagePrunerStatus reports image pruner operational status. - -|=== -..spec -Description:: - ImagePrunerSpec defines the specs for the running image pruner. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `affinity` -| `object` -| affinity is a group of node affinity scheduling rules for the image pruner pod. - -| `failedJobsHistoryLimit` -| `integer` -| failedJobsHistoryLimit specifies how many failed image pruner jobs to retain. Defaults to 3 if not set. - -| `ignoreInvalidImageReferences` -| `boolean` -| ignoreInvalidImageReferences indicates whether the pruner can ignore errors while parsing image references. - -| `keepTagRevisions` -| `integer` -| keepTagRevisions specifies the number of image revisions for a tag in an image stream that will be preserved. Defaults to 3. - -| `keepYoungerThan` -| `integer` -| keepYoungerThan specifies the minimum age in nanoseconds of an image and its referrers for it to be considered a candidate for pruning. DEPRECATED: This field is deprecated in favor of keepYoungerThanDuration. If both are set, this field is ignored and keepYoungerThanDuration takes precedence. - -| `keepYoungerThanDuration` -| `string` -| keepYoungerThanDuration specifies the minimum age of an image and its referrers for it to be considered a candidate for pruning. Defaults to 60m (60 minutes). - -| `logLevel` -| `string` -| logLevel sets the level of log output for the pruner job. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `nodeSelector` -| `object (string)` -| nodeSelector defines the node selection constraints for the image pruner pod. - -| `resources` -| `object` -| resources defines the resource requests and limits for the image pruner pod. - -| `schedule` -| `string` -| schedule specifies when to execute the job using standard cronjob syntax: https://wikipedia.org/wiki/Cron. Defaults to `0 0 * * *`. - -| `successfulJobsHistoryLimit` -| `integer` -| successfulJobsHistoryLimit specifies how many successful image pruner jobs to retain. Defaults to 3 if not set. - -| `suspend` -| `boolean` -| suspend specifies whether or not to suspend subsequent executions of this cronjob. Defaults to false. - -| `tolerations` -| `array` -| tolerations defines the node tolerations for the image pruner pod. - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -|=== -..spec.affinity -Description:: - affinity is a group of node affinity scheduling rules for the image pruner pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeAffinity` -| `object` -| Describes node affinity scheduling rules for the pod. - -| `podAffinity` -| `object` -| Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -| `podAntiAffinity` -| `object` -| Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -|=== -..spec.affinity.nodeAffinity -Description:: - Describes node affinity scheduling rules for the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `object` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -Type:: - `object` - -Required:: - - `preference` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preference` -| `object` -| A node selector term, associated with the corresponding weight. - -| `weight` -| `integer` -| Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference -Description:: - A node selector term, associated with the corresponding weight. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -Type:: - `object` - -Required:: - - `nodeSelectorTerms` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelectorTerms` -| `array` -| Required. A list of node selector terms. The terms are ORed. - -| `nodeSelectorTerms[]` -| `object` -| A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms -Description:: - Required. A list of node selector terms. The terms are ORed. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[] -Description:: - A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity -Description:: - Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity -Description:: - Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.resources -Description:: - resources defines the resource requests and limits for the image pruner pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.tolerations -Description:: - tolerations defines the node tolerations for the image pruner pod. - -Type:: - `array` - - - - -..spec.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== -..status -Description:: - ImagePrunerStatus reports image pruner operational status. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status. - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change that has been applied. - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/imageregistry.operator.openshift.io/v1/imagepruners` -- `DELETE`: delete collection of ImagePruner -- `GET`: list objects of kind ImagePruner -- `POST`: create an ImagePruner -* `/apis/imageregistry.operator.openshift.io/v1/imagepruners/{name}` -- `DELETE`: delete an ImagePruner -- `GET`: read the specified ImagePruner -- `PATCH`: partially update the specified ImagePruner -- `PUT`: replace the specified ImagePruner -* `/apis/imageregistry.operator.openshift.io/v1/imagepruners/{name}/status` -- `GET`: read status of the specified ImagePruner -- `PATCH`: partially update status of the specified ImagePruner -- `PUT`: replace status of the specified ImagePruner - - -=== /apis/imageregistry.operator.openshift.io/v1/imagepruners - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#imageprunerlist-imageregistry-operator-openshift-io-v1[`ImagePrunerList imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/imageregistry.operator.openshift.io/v1/imagepruners/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImagePruner -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/imageregistry.operator.openshift.io/v1/imagepruners/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ImagePruner -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ImagePruner - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/imagepruner-imageregistry-operator-openshift-io-v1.adoc#imagepruner-imageregistry-operator-openshift-io-v1[`ImagePruner imageregistry.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc b/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc deleted file mode 100644 index a569ba91cbe6..000000000000 --- a/rest_api/operator_apis/ingresscontroller-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,1965 +0,0 @@ -[id="ingresscontroller-operator-openshift-io-v1"] -= IngressController [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - IngressController describes a managed ingress controller for the cluster. The controller can service OpenShift Route and Kubernetes Ingress resources. - When an IngressController is created, a new ingress controller deployment is created to allow external traffic to reach the services that expose Ingress or Route resources. Updating this resource may lead to disruption for public facing network connections as a new ingress controller revision may be rolled out. - https://kubernetes.io/docs/concepts/services-networking/ingress-controllers - Whenever possible, sensible defaults for the platform are used. See each field for more details. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of the IngressController. - -| `status` -| `object` -| status is the most recently observed status of the IngressController. - -|=== -..spec -Description:: - spec is the specification of the desired behavior of the IngressController. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultCertificate` -| `object` -| defaultCertificate is a reference to a secret containing the default certificate served by the ingress controller. When Routes don't specify their own certificate, defaultCertificate is used. - The secret must contain the following keys and data: - tls.crt: certificate file contents tls.key: key file contents - If unset, a wildcard certificate is automatically generated and used. The certificate is valid for the ingress controller domain (and subdomains) and the generated certificate's CA will be automatically integrated with the cluster's trust store. - If a wildcard certificate is used and shared by multiple HTTP/2 enabled routes (which implies ALPN) then clients (i.e., notably browsers) are at liberty to reuse open connections. This means a client can reuse a connection to another route and that is likely to fail. This behaviour is generally known as connection coalescing. - The in-use certificate (whether generated or user-specified) will be automatically integrated with OpenShift's built-in OAuth server. - -| `domain` -| `string` -| domain is a DNS name serviced by the ingress controller and is used to configure multiple features: - * For the LoadBalancerService endpoint publishing strategy, domain is used to configure DNS records. See endpointPublishingStrategy. - * When using a generated default certificate, the certificate will be valid for domain and its subdomains. See defaultCertificate. - * The value is published to individual Route statuses so that end-users know where to target external DNS records. - domain must be unique among all IngressControllers, and cannot be updated. - If empty, defaults to ingress.config.openshift.io/cluster .spec.domain. - -| `endpointPublishingStrategy` -| `object` -| endpointPublishingStrategy is used to publish the ingress controller endpoints to other networks, enable load balancer integrations, etc. - If unset, the default is based on infrastructure.config.openshift.io/cluster .status.platform: - AWS: LoadBalancerService (with External scope) Azure: LoadBalancerService (with External scope) GCP: LoadBalancerService (with External scope) IBMCloud: LoadBalancerService (with External scope) Libvirt: HostNetwork - Any other platform types (including None) default to HostNetwork. - endpointPublishingStrategy cannot be updated. - -| `httpHeaders` -| `object` -| httpHeaders defines policy for HTTP headers. - If this field is empty, the default values are used. - -| `logging` -| `object` -| logging defines parameters for what should be logged where. If this field is empty, operational logs are enabled but access logs are disabled. - -| `namespaceSelector` -| `object` -| namespaceSelector is used to filter the set of namespaces serviced by the ingress controller. This is useful for implementing shards. - If unset, the default is no filtering. - -| `nodePlacement` -| `object` -| nodePlacement enables explicit control over the scheduling of the ingress controller. - If unset, defaults are used. See NodePlacement for more details. - -| `replicas` -| `integer` -| replicas is the desired number of ingress controller replicas. If unset, defaults to 2. - -| `routeAdmission` -| `object` -| routeAdmission defines a policy for handling new route claims (for example, to allow or deny claims across namespaces). - If empty, defaults will be applied. See specific routeAdmission fields for details about their defaults. - -| `routeSelector` -| `object` -| routeSelector is used to filter the set of Routes serviced by the ingress controller. This is useful for implementing shards. - If unset, the default is no filtering. - -| `tlsSecurityProfile` -| `object` -| tlsSecurityProfile specifies settings for TLS connections for ingresscontrollers. - If unset, the default is based on the apiservers.config.openshift.io/cluster resource. - Note that when using the Old, Intermediate, and Modern profile types, the effective profile configuration is subject to change between releases. For example, given a specification to use the Intermediate profile deployed on release X.Y.Z, an upgrade to release X.Y.Z+1 may cause a new profile configuration to be applied to the ingress controller, resulting in a rollout. - Note that the minimum TLS version for ingress controllers is 1.1, and the maximum TLS version is 1.2. An implication of this restriction is that the Modern TLS profile type cannot be used because it requires TLS 1.3. - -|=== -..spec.defaultCertificate -Description:: - defaultCertificate is a reference to a secret containing the default certificate served by the ingress controller. When Routes don't specify their own certificate, defaultCertificate is used. - The secret must contain the following keys and data: - tls.crt: certificate file contents tls.key: key file contents - If unset, a wildcard certificate is automatically generated and used. The certificate is valid for the ingress controller domain (and subdomains) and the generated certificate's CA will be automatically integrated with the cluster's trust store. - If a wildcard certificate is used and shared by multiple HTTP/2 enabled routes (which implies ALPN) then clients (i.e., notably browsers) are at liberty to reuse open connections. This means a client can reuse a connection to another route and that is likely to fail. This behaviour is generally known as connection coalescing. - The in-use certificate (whether generated or user-specified) will be automatically integrated with OpenShift's built-in OAuth server. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.endpointPublishingStrategy -Description:: - endpointPublishingStrategy is used to publish the ingress controller endpoints to other networks, enable load balancer integrations, etc. - If unset, the default is based on infrastructure.config.openshift.io/cluster .status.platform: - AWS: LoadBalancerService (with External scope) Azure: LoadBalancerService (with External scope) GCP: LoadBalancerService (with External scope) IBMCloud: LoadBalancerService (with External scope) Libvirt: HostNetwork - Any other platform types (including None) default to HostNetwork. - endpointPublishingStrategy cannot be updated. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hostNetwork` -| `object` -| hostNetwork holds parameters for the HostNetwork endpoint publishing strategy. Present only if type is HostNetwork. - -| `loadBalancer` -| `object` -| loadBalancer holds parameters for the load balancer. Present only if type is LoadBalancerService. - -| `nodePort` -| `object` -| nodePort holds parameters for the NodePortService endpoint publishing strategy. Present only if type is NodePortService. - -| `private` -| `object` -| private holds parameters for the Private endpoint publishing strategy. Present only if type is Private. - -| `type` -| `string` -| type is the publishing strategy to use. Valid values are: - * LoadBalancerService - Publishes the ingress controller using a Kubernetes LoadBalancer Service. - In this configuration, the ingress controller deployment uses container networking. A LoadBalancer Service is created to publish the deployment. - See: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer - If domain is set, a wildcard DNS record will be managed to point at the LoadBalancer Service's external name. DNS records are managed only in DNS zones defined by dns.config.openshift.io/cluster .spec.publicZone and .spec.privateZone. - Wildcard DNS management is currently supported only on the AWS, Azure, and GCP platforms. - * HostNetwork - Publishes the ingress controller on node ports where the ingress controller is deployed. - In this configuration, the ingress controller deployment uses host networking, bound to node ports 80 and 443. The user is responsible for configuring an external load balancer to publish the ingress controller via the node ports. - * Private - Does not publish the ingress controller. - In this configuration, the ingress controller deployment uses container networking, and is not explicitly published. The user must manually publish the ingress controller. - * NodePortService - Publishes the ingress controller using a Kubernetes NodePort Service. - In this configuration, the ingress controller deployment uses container networking. A NodePort Service is created to publish the deployment. The specific node ports are dynamically allocated by OpenShift; however, to support static port allocations, user changes to the node port field of the managed NodePort Service will preserved. - -|=== -..spec.endpointPublishingStrategy.hostNetwork -Description:: - hostNetwork holds parameters for the HostNetwork endpoint publishing strategy. Present only if type is HostNetwork. - -Type:: - `object` - - - - -..spec.endpointPublishingStrategy.loadBalancer -Description:: - loadBalancer holds parameters for the load balancer. Present only if type is LoadBalancerService. - -Type:: - `object` - -Required:: - - `scope` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `providerParameters` -| `object` -| providerParameters holds desired load balancer information specific to the underlying infrastructure provider. - If empty, defaults will be applied. See specific providerParameters fields for details about their defaults. - -| `scope` -| `string` -| scope indicates the scope at which the load balancer is exposed. Possible values are "External" and "Internal". - -|=== -..spec.endpointPublishingStrategy.loadBalancer.providerParameters -Description:: - providerParameters holds desired load balancer information specific to the underlying infrastructure provider. - If empty, defaults will be applied. See specific providerParameters fields for details about their defaults. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `aws` -| `object` -| aws provides configuration settings that are specific to AWS load balancers. - If empty, defaults will be applied. See specific aws fields for details about their defaults. - -| `type` -| `string` -| type is the underlying infrastructure provider for the load balancer. Allowed values are "AWS", "Azure", "BareMetal", "GCP", "OpenStack", and "VSphere". - -|=== -..spec.endpointPublishingStrategy.loadBalancer.providerParameters.aws -Description:: - aws provides configuration settings that are specific to AWS load balancers. - If empty, defaults will be applied. See specific aws fields for details about their defaults. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `classicLoadBalancer` -| `object` -| classicLoadBalancerParameters holds configuration parameters for an AWS classic load balancer. Present only if type is Classic. - -| `networkLoadBalancer` -| `object` -| networkLoadBalancerParameters holds configuration parameters for an AWS network load balancer. Present only if type is NLB. - -| `type` -| `string` -| type is the type of AWS load balancer to instantiate for an ingresscontroller. - Valid values are: - * "Classic": A Classic Load Balancer that makes routing decisions at either the transport layer (TCP/SSL) or the application layer (HTTP/HTTPS). See the following for additional details: - https://docs.aws.amazon.com/AmazonECS/latest/developerguide/load-balancer-types.html#clb - * "NLB": A Network Load Balancer that makes routing decisions at the transport layer (TCP/SSL). See the following for additional details: - https://docs.aws.amazon.com/AmazonECS/latest/developerguide/load-balancer-types.html#nlb - -|=== -..spec.endpointPublishingStrategy.loadBalancer.providerParameters.aws.classicLoadBalancer -Description:: - classicLoadBalancerParameters holds configuration parameters for an AWS classic load balancer. Present only if type is Classic. - -Type:: - `object` - - - - -..spec.endpointPublishingStrategy.loadBalancer.providerParameters.aws.networkLoadBalancer -Description:: - networkLoadBalancerParameters holds configuration parameters for an AWS network load balancer. Present only if type is NLB. - -Type:: - `object` - - - - -..spec.endpointPublishingStrategy.nodePort -Description:: - nodePort holds parameters for the NodePortService endpoint publishing strategy. Present only if type is NodePortService. - -Type:: - `object` - - - - -..spec.endpointPublishingStrategy.private -Description:: - private holds parameters for the Private endpoint publishing strategy. Present only if type is Private. - -Type:: - `object` - - - - -..spec.httpHeaders -Description:: - httpHeaders defines policy for HTTP headers. - If this field is empty, the default values are used. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `forwardedHeaderPolicy` -| `string` -| forwardedHeaderPolicy specifies when and how the IngressController sets the Forwarded, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto, and X-Forwarded-Proto-Version HTTP headers. The value may be one of the following: - * "Append", which specifies that the IngressController appends the headers, preserving existing headers. - * "Replace", which specifies that the IngressController sets the headers, replacing any existing Forwarded or X-Forwarded-* headers. - * "IfNone", which specifies that the IngressController sets the headers if they are not already set. - * "Never", which specifies that the IngressController never sets the headers, preserving any existing headers. - By default, the policy is "Append". - -| `headerNameCaseAdjustments` -| `` -| headerNameCaseAdjustments specifies case adjustments that can be applied to HTTP header names. Each adjustment is specified as an HTTP header name with the desired capitalization. For example, specifying "X-Forwarded-For" indicates that the "x-forwarded-for" HTTP header should be adjusted to have the specified capitalization. - These adjustments are only applied to cleartext, edge-terminated, and re-encrypt routes, and only when using HTTP/1. - For request headers, these adjustments are applied only for routes that have the haproxy.router.openshift.io/h1-adjust-case=true annotation. For response headers, these adjustments are applied to all HTTP responses. - If this field is empty, no request headers are adjusted. - -| `uniqueId` -| `object` -| uniqueId describes configuration for a custom HTTP header that the ingress controller should inject into incoming HTTP requests. Typically, this header is configured to have a value that is unique to the HTTP request. The header can be used by applications or included in access logs to facilitate tracing individual HTTP requests. - If this field is empty, no such header is injected into requests. - -|=== -..spec.httpHeaders.uniqueId -Description:: - uniqueId describes configuration for a custom HTTP header that the ingress controller should inject into incoming HTTP requests. Typically, this header is configured to have a value that is unique to the HTTP request. The header can be used by applications or included in access logs to facilitate tracing individual HTTP requests. - If this field is empty, no such header is injected into requests. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `format` -| `string` -| format specifies the format for the injected HTTP header's value. This field has no effect unless name is specified. For the HAProxy-based ingress controller implementation, this format uses the same syntax as the HTTP log format. If the field is empty, the default value is "%{+X}o\\ %ci:%cp_%fi:%fp_%Ts_%rt:%pid"; see the corresponding HAProxy documentation: http://cbonte.github.io/haproxy-dconv/2.0/configuration.html#8.2.3 - -| `name` -| `string` -| name specifies the name of the HTTP header (for example, "unique-id") that the ingress controller should inject into HTTP requests. The field's value must be a valid HTTP header name as defined in RFC 2616 section 4.2. If the field is empty, no header is injected. - -|=== -..spec.logging -Description:: - logging defines parameters for what should be logged where. If this field is empty, operational logs are enabled but access logs are disabled. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `access` -| `object` -| access describes how the client requests should be logged. - If this field is empty, access logging is disabled. - -|=== -..spec.logging.access -Description:: - access describes how the client requests should be logged. - If this field is empty, access logging is disabled. - -Type:: - `object` - -Required:: - - `destination` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `destination` -| `object` -| destination is where access logs go. - -| `httpCaptureCookies` -| `` -| httpCaptureCookies specifies HTTP cookies that should be captured in access logs. If this field is empty, no cookies are captured. - -| `httpCaptureHeaders` -| `object` -| httpCaptureHeaders defines HTTP headers that should be captured in access logs. If this field is empty, no headers are captured. - Note that this option only applies to cleartext HTTP connections and to secure HTTP connections for which the ingress controller terminates encryption (that is, edge-terminated or reencrypt connections). Headers cannot be captured for TLS passthrough connections. - -| `httpLogFormat` -| `string` -| httpLogFormat specifies the format of the log message for an HTTP request. - If this field is empty, log messages use the implementation's default HTTP log format. For HAProxy's default HTTP log format, see the HAProxy documentation: http://cbonte.github.io/haproxy-dconv/2.0/configuration.html#8.2.3 - Note that this format only applies to cleartext HTTP connections and to secure HTTP connections for which the ingress controller terminates encryption (that is, edge-terminated or reencrypt connections). It does not affect the log format for TLS passthrough connections. - -|=== -..spec.logging.access.destination -Description:: - destination is where access logs go. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `container` -| `object` -| container holds parameters for the Container logging destination. Present only if type is Container. - -| `syslog` -| `object` -| syslog holds parameters for a syslog endpoint. Present only if type is Syslog. - -| `type` -| `string` -| type is the type of destination for logs. It must be one of the following: - * Container - The ingress operator configures the sidecar container named "logs" on the ingress controller pod and configures the ingress controller to write logs to the sidecar. The logs are then available as container logs. The expectation is that the administrator configures a custom logging solution that reads logs from this sidecar. Note that using container logs means that logs may be dropped if the rate of logs exceeds the container runtime's or the custom logging solution's capacity. - * Syslog - Logs are sent to a syslog endpoint. The administrator must specify an endpoint that can receive syslog messages. The expectation is that the administrator has configured a custom syslog instance. - -|=== -..spec.logging.access.destination.container -Description:: - container holds parameters for the Container logging destination. Present only if type is Container. - -Type:: - `object` - - - - -..spec.logging.access.destination.syslog -Description:: - syslog holds parameters for a syslog endpoint. Present only if type is Syslog. - -Type:: - `object` - -Required:: - - `address` - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `address` -| `string` -| address is the IP address of the syslog endpoint that receives log messages. - -| `facility` -| `string` -| facility specifies the syslog facility of log messages. - If this field is empty, the facility is "local1". - -| `port` -| `integer` -| port is the UDP port number of the syslog endpoint that receives log messages. - -|=== -..spec.logging.access.httpCaptureHeaders -Description:: - httpCaptureHeaders defines HTTP headers that should be captured in access logs. If this field is empty, no headers are captured. - Note that this option only applies to cleartext HTTP connections and to secure HTTP connections for which the ingress controller terminates encryption (that is, edge-terminated or reencrypt connections). Headers cannot be captured for TLS passthrough connections. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `request` -| `` -| request specifies which HTTP request headers to capture. - If this field is empty, no request headers are captured. - -| `response` -| `` -| response specifies which HTTP response headers to capture. - If this field is empty, no response headers are captured. - -|=== -..spec.namespaceSelector -Description:: - namespaceSelector is used to filter the set of namespaces serviced by the ingress controller. This is useful for implementing shards. - If unset, the default is no filtering. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.namespaceSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.namespaceSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.nodePlacement -Description:: - nodePlacement enables explicit control over the scheduling of the ingress controller. - If unset, defaults are used. See NodePlacement for more details. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelector` -| `object` -| nodeSelector is the node selector applied to ingress controller deployments. - If unset, the default is: - beta.kubernetes.io/os: linux node-role.kubernetes.io/worker: '' - If set, the specified selector is used and replaces the default. - -| `tolerations` -| `array` -| tolerations is a list of tolerations applied to ingress controller deployments. - The default is an empty list. - See https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/ - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -|=== -..spec.nodePlacement.nodeSelector -Description:: - nodeSelector is the node selector applied to ingress controller deployments. - If unset, the default is: - beta.kubernetes.io/os: linux node-role.kubernetes.io/worker: '' - If set, the specified selector is used and replaces the default. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.nodePlacement.nodeSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.nodePlacement.nodeSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.nodePlacement.tolerations -Description:: - tolerations is a list of tolerations applied to ingress controller deployments. - The default is an empty list. - See https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/ - -Type:: - `array` - - - - -..spec.nodePlacement.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== -..spec.routeAdmission -Description:: - routeAdmission defines a policy for handling new route claims (for example, to allow or deny claims across namespaces). - If empty, defaults will be applied. See specific routeAdmission fields for details about their defaults. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namespaceOwnership` -| `string` -| namespaceOwnership describes how host name claims across namespaces should be handled. - Value must be one of: - - Strict: Do not allow routes in different namespaces to claim the same host. - - InterNamespaceAllowed: Allow routes to claim different paths of the same host name across namespaces. - If empty, the default is Strict. - -| `wildcardPolicy` -| `string` -| wildcardPolicy describes how routes with wildcard policies should be handled for the ingress controller. WildcardPolicy controls use of routes [1] exposed by the ingress controller based on the route's wildcard policy. - [1] https://github.com/openshift/api/blob/master/route/v1/types.go - Note: Updating WildcardPolicy from WildcardsAllowed to WildcardsDisallowed will cause admitted routes with a wildcard policy of Subdomain to stop working. These routes must be updated to a wildcard policy of None to be readmitted by the ingress controller. - WildcardPolicy supports WildcardsAllowed and WildcardsDisallowed values. - If empty, defaults to "WildcardsDisallowed". - -|=== -..spec.routeSelector -Description:: - routeSelector is used to filter the set of Routes serviced by the ingress controller. This is useful for implementing shards. - If unset, the default is no filtering. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.routeSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.routeSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.tlsSecurityProfile -Description:: - tlsSecurityProfile specifies settings for TLS connections for ingresscontrollers. - If unset, the default is based on the apiservers.config.openshift.io/cluster resource. - Note that when using the Old, Intermediate, and Modern profile types, the effective profile configuration is subject to change between releases. For example, given a specification to use the Intermediate profile deployed on release X.Y.Z, an upgrade to release X.Y.Z+1 may cause a new profile configuration to be applied to the ingress controller, resulting in a rollout. - Note that the minimum TLS version for ingress controllers is 1.1, and the maximum TLS version is 1.2. An implication of this restriction is that the Modern TLS profile type cannot be used because it requires TLS 1.3. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `custom` -| `` -| custom is a user-defined TLS security profile. Be extremely careful using a custom profile as invalid configurations can be catastrophic. An example custom profile looks like this: - ciphers: - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 minTLSVersion: TLSv1.1 - -| `intermediate` -| `` -| intermediate is a TLS security profile based on: - https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29 - and looks like this (yaml): - ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - DHE-RSA-AES128-GCM-SHA256 - DHE-RSA-AES256-GCM-SHA384 minTLSVersion: TLSv1.2 - -| `modern` -| `` -| modern is a TLS security profile based on: - https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility - and looks like this (yaml): - ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 minTLSVersion: TLSv1.3 - NOTE: Currently unsupported. - -| `old` -| `` -| old is a TLS security profile based on: - https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility - and looks like this (yaml): - ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 - ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 - DHE-RSA-AES128-GCM-SHA256 - DHE-RSA-AES256-GCM-SHA384 - DHE-RSA-CHACHA20-POLY1305 - ECDHE-ECDSA-AES128-SHA256 - ECDHE-RSA-AES128-SHA256 - ECDHE-ECDSA-AES128-SHA - ECDHE-RSA-AES128-SHA - ECDHE-ECDSA-AES256-SHA384 - ECDHE-RSA-AES256-SHA384 - ECDHE-ECDSA-AES256-SHA - ECDHE-RSA-AES256-SHA - DHE-RSA-AES128-SHA256 - DHE-RSA-AES256-SHA256 - AES128-GCM-SHA256 - AES256-GCM-SHA384 - AES128-SHA256 - AES256-SHA256 - AES128-SHA - AES256-SHA - DES-CBC3-SHA minTLSVersion: TLSv1.0 - -| `type` -| `string` -| type is one of Old, Intermediate, Modern or Custom. Custom provides the ability to specify individual TLS security profile parameters. Old, Intermediate and Modern are TLS security profiles based on: - https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations - The profiles are intent based, so they may change over time as new ciphers are developed and existing ciphers are found to be insecure. Depending on precisely which ciphers are available to a process, the list may be reduced. - Note that the Modern profile is currently not supported because it is not yet well adopted by common software libraries. - -|=== -..status -Description:: - status is the most recently observed status of the IngressController. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| availableReplicas is number of observed available replicas according to the ingress controller deployment. - -| `conditions` -| `array` -| conditions is a list of conditions and their status. - Available means the ingress controller deployment is available and servicing route and ingress resources (i.e, .status.availableReplicas equals .spec.replicas) - There are additional conditions which indicate the status of other ingress controller features and capabilities. - * LoadBalancerManaged - True if the following conditions are met: * The endpoint publishing strategy requires a service load balancer. - False if any of those conditions are unsatisfied. - * LoadBalancerReady - True if the following conditions are met: * A load balancer is managed. * The load balancer is ready. - False if any of those conditions are unsatisfied. - * DNSManaged - True if the following conditions are met: * The endpoint publishing strategy and platform support DNS. * The ingress controller domain is set. * dns.config.openshift.io/cluster configures DNS zones. - False if any of those conditions are unsatisfied. - * DNSReady - True if the following conditions are met: * DNS is managed. * DNS records have been successfully created. - False if any of those conditions are unsatisfied. - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `domain` -| `string` -| domain is the actual domain in use. - -| `endpointPublishingStrategy` -| `object` -| endpointPublishingStrategy is the actual strategy in use. - -| `observedGeneration` -| `integer` -| observedGeneration is the most recent generation observed. - -| `selector` -| `string` -| selector is a label selector, in string format, for ingress controller pods corresponding to the IngressController. The number of matching pods should equal the value of availableReplicas. - -| `tlsProfile` -| `object` -| tlsProfile is the TLS connection configuration that is in effect. - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status. - Available means the ingress controller deployment is available and servicing route and ingress resources (i.e, .status.availableReplicas equals .spec.replicas) - There are additional conditions which indicate the status of other ingress controller features and capabilities. - * LoadBalancerManaged - True if the following conditions are met: * The endpoint publishing strategy requires a service load balancer. - False if any of those conditions are unsatisfied. - * LoadBalancerReady - True if the following conditions are met: * A load balancer is managed. * The load balancer is ready. - False if any of those conditions are unsatisfied. - * DNSManaged - True if the following conditions are met: * The endpoint publishing strategy and platform support DNS. * The ingress controller domain is set. * dns.config.openshift.io/cluster configures DNS zones. - False if any of those conditions are unsatisfied. - * DNSReady - True if the following conditions are met: * DNS is managed. * DNS records have been successfully created. - False if any of those conditions are unsatisfied. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.endpointPublishingStrategy -Description:: - endpointPublishingStrategy is the actual strategy in use. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hostNetwork` -| `object` -| hostNetwork holds parameters for the HostNetwork endpoint publishing strategy. Present only if type is HostNetwork. - -| `loadBalancer` -| `object` -| loadBalancer holds parameters for the load balancer. Present only if type is LoadBalancerService. - -| `nodePort` -| `object` -| nodePort holds parameters for the NodePortService endpoint publishing strategy. Present only if type is NodePortService. - -| `private` -| `object` -| private holds parameters for the Private endpoint publishing strategy. Present only if type is Private. - -| `type` -| `string` -| type is the publishing strategy to use. Valid values are: - * LoadBalancerService - Publishes the ingress controller using a Kubernetes LoadBalancer Service. - In this configuration, the ingress controller deployment uses container networking. A LoadBalancer Service is created to publish the deployment. - See: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer - If domain is set, a wildcard DNS record will be managed to point at the LoadBalancer Service's external name. DNS records are managed only in DNS zones defined by dns.config.openshift.io/cluster .spec.publicZone and .spec.privateZone. - Wildcard DNS management is currently supported only on the AWS, Azure, and GCP platforms. - * HostNetwork - Publishes the ingress controller on node ports where the ingress controller is deployed. - In this configuration, the ingress controller deployment uses host networking, bound to node ports 80 and 443. The user is responsible for configuring an external load balancer to publish the ingress controller via the node ports. - * Private - Does not publish the ingress controller. - In this configuration, the ingress controller deployment uses container networking, and is not explicitly published. The user must manually publish the ingress controller. - * NodePortService - Publishes the ingress controller using a Kubernetes NodePort Service. - In this configuration, the ingress controller deployment uses container networking. A NodePort Service is created to publish the deployment. The specific node ports are dynamically allocated by OpenShift; however, to support static port allocations, user changes to the node port field of the managed NodePort Service will preserved. - -|=== -..status.endpointPublishingStrategy.hostNetwork -Description:: - hostNetwork holds parameters for the HostNetwork endpoint publishing strategy. Present only if type is HostNetwork. - -Type:: - `object` - - - - -..status.endpointPublishingStrategy.loadBalancer -Description:: - loadBalancer holds parameters for the load balancer. Present only if type is LoadBalancerService. - -Type:: - `object` - -Required:: - - `scope` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `providerParameters` -| `object` -| providerParameters holds desired load balancer information specific to the underlying infrastructure provider. - If empty, defaults will be applied. See specific providerParameters fields for details about their defaults. - -| `scope` -| `string` -| scope indicates the scope at which the load balancer is exposed. Possible values are "External" and "Internal". - -|=== -..status.endpointPublishingStrategy.loadBalancer.providerParameters -Description:: - providerParameters holds desired load balancer information specific to the underlying infrastructure provider. - If empty, defaults will be applied. See specific providerParameters fields for details about their defaults. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `aws` -| `object` -| aws provides configuration settings that are specific to AWS load balancers. - If empty, defaults will be applied. See specific aws fields for details about their defaults. - -| `type` -| `string` -| type is the underlying infrastructure provider for the load balancer. Allowed values are "AWS", "Azure", "BareMetal", "GCP", "OpenStack", and "VSphere". - -|=== -..status.endpointPublishingStrategy.loadBalancer.providerParameters.aws -Description:: - aws provides configuration settings that are specific to AWS load balancers. - If empty, defaults will be applied. See specific aws fields for details about their defaults. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `classicLoadBalancer` -| `object` -| classicLoadBalancerParameters holds configuration parameters for an AWS classic load balancer. Present only if type is Classic. - -| `networkLoadBalancer` -| `object` -| networkLoadBalancerParameters holds configuration parameters for an AWS network load balancer. Present only if type is NLB. - -| `type` -| `string` -| type is the type of AWS load balancer to instantiate for an ingresscontroller. - Valid values are: - * "Classic": A Classic Load Balancer that makes routing decisions at either the transport layer (TCP/SSL) or the application layer (HTTP/HTTPS). See the following for additional details: - https://docs.aws.amazon.com/AmazonECS/latest/developerguide/load-balancer-types.html#clb - * "NLB": A Network Load Balancer that makes routing decisions at the transport layer (TCP/SSL). See the following for additional details: - https://docs.aws.amazon.com/AmazonECS/latest/developerguide/load-balancer-types.html#nlb - -|=== -..status.endpointPublishingStrategy.loadBalancer.providerParameters.aws.classicLoadBalancer -Description:: - classicLoadBalancerParameters holds configuration parameters for an AWS classic load balancer. Present only if type is Classic. - -Type:: - `object` - - - - -..status.endpointPublishingStrategy.loadBalancer.providerParameters.aws.networkLoadBalancer -Description:: - networkLoadBalancerParameters holds configuration parameters for an AWS network load balancer. Present only if type is NLB. - -Type:: - `object` - - - - -..status.endpointPublishingStrategy.nodePort -Description:: - nodePort holds parameters for the NodePortService endpoint publishing strategy. Present only if type is NodePortService. - -Type:: - `object` - - - - -..status.endpointPublishingStrategy.private -Description:: - private holds parameters for the Private endpoint publishing strategy. Present only if type is Private. - -Type:: - `object` - - - - -..status.tlsProfile -Description:: - tlsProfile is the TLS connection configuration that is in effect. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ciphers` -| `array (string)` -| ciphers is used to specify the cipher algorithms that are negotiated during the TLS handshake. Operators may remove entries their operands do not support. For example, to use DES-CBC3-SHA (yaml): - ciphers: - DES-CBC3-SHA - -| `minTLSVersion` -| `string` -| minTLSVersion is used to specify the minimal version of the TLS protocol that is negotiated during the TLS handshake. For example, to use TLS versions 1.1, 1.2 and 1.3 (yaml): - minTLSVersion: TLSv1.1 - NOTE: currently the highest minTLSVersion allowed is VersionTLS12 - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/ingresscontrollers` -- `GET`: list objects of kind IngressController -* `/apis/operator.openshift.io/v1/namespaces/{namespace}/ingresscontrollers` -- `DELETE`: delete collection of IngressController -- `GET`: list objects of kind IngressController -- `POST`: create an IngressController -* `/apis/operator.openshift.io/v1/namespaces/{namespace}/ingresscontrollers/{name}` -- `DELETE`: delete an IngressController -- `GET`: read the specified IngressController -- `PATCH`: partially update the specified IngressController -- `PUT`: replace the specified IngressController -* `/apis/operator.openshift.io/v1/namespaces/{namespace}/ingresscontrollers/{name}/scale` -- `GET`: read scale of the specified IngressController -- `PATCH`: partially update scale of the specified IngressController -- `PUT`: replace scale of the specified IngressController -* `/apis/operator.openshift.io/v1/namespaces/{namespace}/ingresscontrollers/{name}/status` -- `GET`: read status of the specified IngressController -- `PATCH`: partially update status of the specified IngressController -- `PUT`: replace status of the specified IngressController - - -=== /apis/operator.openshift.io/v1/ingresscontrollers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind IngressController - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#ingresscontrollerlist-operator-openshift-io-v1[`IngressControllerList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/namespaces/{namespace}/ingresscontrollers - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#ingresscontrollerlist-operator-openshift-io-v1[`IngressControllerList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/namespaces/{namespace}/ingresscontrollers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the IngressController -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/namespaces/{namespace}/ingresscontrollers/{name}/scale - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the IngressController -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read scale of the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update scale of the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace scale of the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| 201 - Created -| xref:../objects/index.adoc#scale_v2-autoscaling-v1[`Scale_v2 autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/namespaces/{namespace}/ingresscontrollers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the IngressController -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified IngressController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/ingresscontroller-operator-openshift-io-v1.adoc#ingresscontroller-operator-openshift-io-v1[`IngressController operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc b/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc deleted file mode 100644 index 4bc7b814ad32..000000000000 --- a/rest_api/operator_apis/kubeapiserver-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,788 +0,0 @@ -[id="kubeapiserver-operator-openshift-io-v1"] -= KubeAPIServer [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - KubeAPIServer provides information to configure an operator to manage kube-apiserver. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of the Kubernetes API Server - -| `status` -| `object` -| status is the most recently observed status of the Kubernetes API Server - -|=== -..spec -Description:: - spec is the specification of the desired behavior of the Kubernetes API Server - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `failedRevisionLimit` -| `integer` -| failedRevisionLimit is the number of failed static pod installer revisions to keep on disk and in the api -1 = unlimited, 0 or unset = 5 (default) - -| `forceRedeploymentReason` -| `string` -| forceRedeploymentReason can be used to force the redeployment of the operand by providing a unique string. This provides a mechanism to kick a previously failed deployment and provide a reason why you think it will work this time instead of failing again on the same config. - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `succeededRevisionLimit` -| `integer` -| succeededRevisionLimit is the number of successful static pod installer revisions to keep on disk and in the api -1 = unlimited, 0 or unset = 5 (default) - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status is the most recently observed status of the Kubernetes API Server - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `latestAvailableRevision` -| `integer` -| latestAvailableRevision is the deploymentID of the most recent deployment - -| `latestAvailableRevisionReason` -| `string` -| latestAvailableRevisionReason describe the detailed reason for the most recent deployment - -| `nodeStatuses` -| `array` -| nodeStatuses track the deployment values and errors across individual nodes - -| `nodeStatuses[]` -| `object` -| NodeStatus provides information about the current state of a particular node managed by this operator. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== -..status.nodeStatuses -Description:: - nodeStatuses track the deployment values and errors across individual nodes - -Type:: - `array` - - - - -..status.nodeStatuses[] -Description:: - NodeStatus provides information about the current state of a particular node managed by this operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `currentRevision` -| `integer` -| currentRevision is the generation of the most recently successful deployment - -| `lastFailedRevision` -| `integer` -| lastFailedRevision is the generation of the deployment we tried and failed to deploy. - -| `lastFailedRevisionErrors` -| `array (string)` -| lastFailedRevisionErrors is a list of the errors during the failed deployment referenced in lastFailedRevision - -| `nodeName` -| `string` -| nodeName is the name of the node - -| `targetRevision` -| `integer` -| targetRevision is the generation of the deployment we're trying to apply - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/kubeapiservers` -- `DELETE`: delete collection of KubeAPIServer -- `GET`: list objects of kind KubeAPIServer -- `POST`: create a KubeAPIServer -* `/apis/operator.openshift.io/v1/kubeapiservers/{name}` -- `DELETE`: delete a KubeAPIServer -- `GET`: read the specified KubeAPIServer -- `PATCH`: partially update the specified KubeAPIServer -- `PUT`: replace the specified KubeAPIServer -* `/apis/operator.openshift.io/v1/kubeapiservers/{name}/status` -- `GET`: read status of the specified KubeAPIServer -- `PATCH`: partially update status of the specified KubeAPIServer -- `PUT`: replace status of the specified KubeAPIServer - - -=== /apis/operator.openshift.io/v1/kubeapiservers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#kubeapiserverlist-operator-openshift-io-v1[`KubeAPIServerList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/kubeapiservers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeAPIServer -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/kubeapiservers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeAPIServer -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified KubeAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubeapiserver-operator-openshift-io-v1.adoc#kubeapiserver-operator-openshift-io-v1[`KubeAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc b/rest_api/operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc deleted file mode 100644 index 3021f07776be..000000000000 --- a/rest_api/operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,788 +0,0 @@ -[id="kubecontrollermanager-operator-openshift-io-v1"] -= KubeControllerManager [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - KubeControllerManager provides information to configure an operator to manage kube-controller-manager. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of the Kubernetes Controller Manager - -| `status` -| `object` -| status is the most recently observed status of the Kubernetes Controller Manager - -|=== -..spec -Description:: - spec is the specification of the desired behavior of the Kubernetes Controller Manager - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `failedRevisionLimit` -| `integer` -| failedRevisionLimit is the number of failed static pod installer revisions to keep on disk and in the api -1 = unlimited, 0 or unset = 5 (default) - -| `forceRedeploymentReason` -| `string` -| forceRedeploymentReason can be used to force the redeployment of the operand by providing a unique string. This provides a mechanism to kick a previously failed deployment and provide a reason why you think it will work this time instead of failing again on the same config. - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `succeededRevisionLimit` -| `integer` -| succeededRevisionLimit is the number of successful static pod installer revisions to keep on disk and in the api -1 = unlimited, 0 or unset = 5 (default) - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status is the most recently observed status of the Kubernetes Controller Manager - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `latestAvailableRevision` -| `integer` -| latestAvailableRevision is the deploymentID of the most recent deployment - -| `latestAvailableRevisionReason` -| `string` -| latestAvailableRevisionReason describe the detailed reason for the most recent deployment - -| `nodeStatuses` -| `array` -| nodeStatuses track the deployment values and errors across individual nodes - -| `nodeStatuses[]` -| `object` -| NodeStatus provides information about the current state of a particular node managed by this operator. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== -..status.nodeStatuses -Description:: - nodeStatuses track the deployment values and errors across individual nodes - -Type:: - `array` - - - - -..status.nodeStatuses[] -Description:: - NodeStatus provides information about the current state of a particular node managed by this operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `currentRevision` -| `integer` -| currentRevision is the generation of the most recently successful deployment - -| `lastFailedRevision` -| `integer` -| lastFailedRevision is the generation of the deployment we tried and failed to deploy. - -| `lastFailedRevisionErrors` -| `array (string)` -| lastFailedRevisionErrors is a list of the errors during the failed deployment referenced in lastFailedRevision - -| `nodeName` -| `string` -| nodeName is the name of the node - -| `targetRevision` -| `integer` -| targetRevision is the generation of the deployment we're trying to apply - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/kubecontrollermanagers` -- `DELETE`: delete collection of KubeControllerManager -- `GET`: list objects of kind KubeControllerManager -- `POST`: create a KubeControllerManager -* `/apis/operator.openshift.io/v1/kubecontrollermanagers/{name}` -- `DELETE`: delete a KubeControllerManager -- `GET`: read the specified KubeControllerManager -- `PATCH`: partially update the specified KubeControllerManager -- `PUT`: replace the specified KubeControllerManager -* `/apis/operator.openshift.io/v1/kubecontrollermanagers/{name}/status` -- `GET`: read status of the specified KubeControllerManager -- `PATCH`: partially update status of the specified KubeControllerManager -- `PUT`: replace status of the specified KubeControllerManager - - -=== /apis/operator.openshift.io/v1/kubecontrollermanagers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#kubecontrollermanagerlist-operator-openshift-io-v1[`KubeControllerManagerList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/kubecontrollermanagers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeControllerManager -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/kubecontrollermanagers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeControllerManager -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified KubeControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubecontrollermanager-operator-openshift-io-v1.adoc#kubecontrollermanager-operator-openshift-io-v1[`KubeControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/kubescheduler-operator-openshift-io-v1.adoc b/rest_api/operator_apis/kubescheduler-operator-openshift-io-v1.adoc deleted file mode 100644 index e1460b701df5..000000000000 --- a/rest_api/operator_apis/kubescheduler-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,788 +0,0 @@ -[id="kubescheduler-operator-openshift-io-v1"] -= KubeScheduler [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - KubeScheduler provides information to configure an operator to manage scheduler. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of the Kubernetes Scheduler - -| `status` -| `object` -| status is the most recently observed status of the Kubernetes Scheduler - -|=== -..spec -Description:: - spec is the specification of the desired behavior of the Kubernetes Scheduler - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `failedRevisionLimit` -| `integer` -| failedRevisionLimit is the number of failed static pod installer revisions to keep on disk and in the api -1 = unlimited, 0 or unset = 5 (default) - -| `forceRedeploymentReason` -| `string` -| forceRedeploymentReason can be used to force the redeployment of the operand by providing a unique string. This provides a mechanism to kick a previously failed deployment and provide a reason why you think it will work this time instead of failing again on the same config. - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `succeededRevisionLimit` -| `integer` -| succeededRevisionLimit is the number of successful static pod installer revisions to keep on disk and in the api -1 = unlimited, 0 or unset = 5 (default) - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status is the most recently observed status of the Kubernetes Scheduler - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `latestAvailableRevision` -| `integer` -| latestAvailableRevision is the deploymentID of the most recent deployment - -| `latestAvailableRevisionReason` -| `string` -| latestAvailableRevisionReason describe the detailed reason for the most recent deployment - -| `nodeStatuses` -| `array` -| nodeStatuses track the deployment values and errors across individual nodes - -| `nodeStatuses[]` -| `object` -| NodeStatus provides information about the current state of a particular node managed by this operator. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== -..status.nodeStatuses -Description:: - nodeStatuses track the deployment values and errors across individual nodes - -Type:: - `array` - - - - -..status.nodeStatuses[] -Description:: - NodeStatus provides information about the current state of a particular node managed by this operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `currentRevision` -| `integer` -| currentRevision is the generation of the most recently successful deployment - -| `lastFailedRevision` -| `integer` -| lastFailedRevision is the generation of the deployment we tried and failed to deploy. - -| `lastFailedRevisionErrors` -| `array (string)` -| lastFailedRevisionErrors is a list of the errors during the failed deployment referenced in lastFailedRevision - -| `nodeName` -| `string` -| nodeName is the name of the node - -| `targetRevision` -| `integer` -| targetRevision is the generation of the deployment we're trying to apply - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/kubeschedulers` -- `DELETE`: delete collection of KubeScheduler -- `GET`: list objects of kind KubeScheduler -- `POST`: create a KubeScheduler -* `/apis/operator.openshift.io/v1/kubeschedulers/{name}` -- `DELETE`: delete a KubeScheduler -- `GET`: read the specified KubeScheduler -- `PATCH`: partially update the specified KubeScheduler -- `PUT`: replace the specified KubeScheduler -* `/apis/operator.openshift.io/v1/kubeschedulers/{name}/status` -- `GET`: read status of the specified KubeScheduler -- `PATCH`: partially update status of the specified KubeScheduler -- `PUT`: replace status of the specified KubeScheduler - - -=== /apis/operator.openshift.io/v1/kubeschedulers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#kubeschedulerlist-operator-openshift-io-v1[`KubeSchedulerList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/kubeschedulers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeScheduler -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/kubeschedulers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeScheduler -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified KubeScheduler - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubescheduler-operator-openshift-io-v1.adoc#kubescheduler-operator-openshift-io-v1[`KubeScheduler operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc b/rest_api/operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc deleted file mode 100644 index 4da559e81e8d..000000000000 --- a/rest_api/operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,715 +0,0 @@ -[id="kubestorageversionmigrator-operator-openshift-io-v1"] -= KubeStorageVersionMigrator [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - KubeStorageVersionMigrator provides information to configure an operator to manage kube-storage-version-migrator. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| - -| `status` -| `object` -| - -|=== -..spec -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/kubestorageversionmigrators` -- `DELETE`: delete collection of KubeStorageVersionMigrator -- `GET`: list objects of kind KubeStorageVersionMigrator -- `POST`: create a KubeStorageVersionMigrator -* `/apis/operator.openshift.io/v1/kubestorageversionmigrators/{name}` -- `DELETE`: delete a KubeStorageVersionMigrator -- `GET`: read the specified KubeStorageVersionMigrator -- `PATCH`: partially update the specified KubeStorageVersionMigrator -- `PUT`: replace the specified KubeStorageVersionMigrator -* `/apis/operator.openshift.io/v1/kubestorageversionmigrators/{name}/status` -- `GET`: read status of the specified KubeStorageVersionMigrator -- `PATCH`: partially update status of the specified KubeStorageVersionMigrator -- `PUT`: replace status of the specified KubeStorageVersionMigrator - - -=== /apis/operator.openshift.io/v1/kubestorageversionmigrators - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#kubestorageversionmigratorlist-operator-openshift-io-v1[`KubeStorageVersionMigratorList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/kubestorageversionmigrators/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeStorageVersionMigrator -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/kubestorageversionmigrators/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the KubeStorageVersionMigrator -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified KubeStorageVersionMigrator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/kubestorageversionmigrator-operator-openshift-io-v1.adoc#kubestorageversionmigrator-operator-openshift-io-v1[`KubeStorageVersionMigrator operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/network-operator-openshift-io-v1.adoc b/rest_api/operator_apis/network-operator-openshift-io-v1.adoc deleted file mode 100644 index 6ed3a567082e..000000000000 --- a/rest_api/operator_apis/network-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,1132 +0,0 @@ -[id="network-operator-openshift-io-v1"] -= Network [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Network describes the cluster's desired network configuration. It is consumed by the cluster-network-operator. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| NetworkSpec is the top-level network configuration object. - -| `status` -| `object` -| NetworkStatus is detailed operator status, which is distilled up to the Network clusteroperator object. - -|=== -..spec -Description:: - NetworkSpec is the top-level network configuration object. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `additionalNetworks` -| `array` -| additionalNetworks is a list of extra networks to make available to pods when multiple networks are enabled. - -| `additionalNetworks[]` -| `object` -| AdditionalNetworkDefinition configures an extra network that is available but not created by default. Instead, pods must request them by name. type must be specified, along with exactly one "Config" that matches the type. - -| `clusterNetwork` -| `array` -| clusterNetwork is the IP address pool to use for pod IPs. Some network providers, e.g. OpenShift SDN, support multiple ClusterNetworks. Others only support one. This is equivalent to the cluster-cidr. - -| `clusterNetwork[]` -| `object` -| ClusterNetworkEntry is a subnet from which to allocate PodIPs. A network of size HostPrefix (in CIDR notation) will be allocated when nodes join the cluster. If the HostPrefix field is not used by the plugin, it can be left unset. Not all network providers support multiple ClusterNetworks - -| `defaultNetwork` -| `object` -| defaultNetwork is the "default" network that all pods will receive - -| `deployKubeProxy` -| `boolean` -| deployKubeProxy specifies whether or not a standalone kube-proxy should be deployed by the operator. Some network providers include kube-proxy or similar functionality. If unset, the plugin will attempt to select the correct value, which is false when OpenShift SDN and ovn-kubernetes are used and true otherwise. - -| `disableMultiNetwork` -| `boolean` -| disableMultiNetwork specifies whether or not multiple pod network support should be disabled. If unset, this property defaults to 'false' and multiple network support is enabled. - -| `disableNetworkDiagnostics` -| `boolean` -| disableNetworkDiagnostics specifies whether or not PodNetworkConnectivityCheck CRs from a test pod to every node, apiserver and LB should be disabled or not. If unset, this property defaults to 'false' and network diagnostics is enabled. Setting this to 'true' would reduce the additional load of the pods performing the checks. - -| `kubeProxyConfig` -| `object` -| kubeProxyConfig lets us configure desired proxy configuration. If not specified, sensible defaults will be chosen by OpenShift directly. Not consumed by all network providers - currently only openshift-sdn. - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `serviceNetwork` -| `array (string)` -| serviceNetwork is the ip address pool to use for Service IPs Currently, all existing network providers only support a single value here, but this is an array to allow for growth. - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..spec.additionalNetworks -Description:: - additionalNetworks is a list of extra networks to make available to pods when multiple networks are enabled. - -Type:: - `array` - - - - -..spec.additionalNetworks[] -Description:: - AdditionalNetworkDefinition configures an extra network that is available but not created by default. Instead, pods must request them by name. type must be specified, along with exactly one "Config" that matches the type. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the name of the network. This will be populated in the resulting CRD This must be unique. - -| `namespace` -| `string` -| namespace is the namespace of the network. This will be populated in the resulting CRD If not given the network will be created in the default namespace. - -| `rawCNIConfig` -| `string` -| rawCNIConfig is the raw CNI configuration json to create in the NetworkAttachmentDefinition CRD - -| `simpleMacvlanConfig` -| `object` -| SimpleMacvlanConfig configures the macvlan interface in case of type:NetworkTypeSimpleMacvlan - -| `type` -| `string` -| type is the type of network The supported values are NetworkTypeRaw, NetworkTypeSimpleMacvlan - -|=== -..spec.additionalNetworks[].simpleMacvlanConfig -Description:: - SimpleMacvlanConfig configures the macvlan interface in case of type:NetworkTypeSimpleMacvlan - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ipamConfig` -| `object` -| IPAMConfig configures IPAM module will be used for IP Address Management (IPAM). - -| `master` -| `string` -| master is the host interface to create the macvlan interface from. If not specified, it will be default route interface - -| `mode` -| `string` -| mode is the macvlan mode: bridge, private, vepa, passthru. The default is bridge - -| `mtu` -| `integer` -| mtu is the mtu to use for the macvlan interface. if unset, host's kernel will select the value. - -|=== -..spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig -Description:: - IPAMConfig configures IPAM module will be used for IP Address Management (IPAM). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `staticIPAMConfig` -| `object` -| StaticIPAMConfig configures the static IP address in case of type:IPAMTypeStatic - -| `type` -| `string` -| Type is the type of IPAM module will be used for IP Address Management(IPAM). The supported values are IPAMTypeDHCP, IPAMTypeStatic - -|=== -..spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig.staticIPAMConfig -Description:: - StaticIPAMConfig configures the static IP address in case of type:IPAMTypeStatic - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `addresses` -| `array` -| Addresses configures IP address for the interface - -| `addresses[]` -| `object` -| StaticIPAMAddresses provides IP address and Gateway for static IPAM addresses - -| `dns` -| `object` -| DNS configures DNS for the interface - -| `routes` -| `array` -| Routes configures IP routes for the interface - -| `routes[]` -| `object` -| StaticIPAMRoutes provides Destination/Gateway pairs for static IPAM routes - -|=== -..spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig.staticIPAMConfig.addresses -Description:: - Addresses configures IP address for the interface - -Type:: - `array` - - - - -..spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig.staticIPAMConfig.addresses[] -Description:: - StaticIPAMAddresses provides IP address and Gateway for static IPAM addresses - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `address` -| `string` -| Address is the IP address in CIDR format - -| `gateway` -| `string` -| Gateway is IP inside of subnet to designate as the gateway - -|=== -..spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig.staticIPAMConfig.dns -Description:: - DNS configures DNS for the interface - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `domain` -| `string` -| Domain configures the domainname the local domain used for short hostname lookups - -| `nameservers` -| `array (string)` -| Nameservers points DNS servers for IP lookup - -| `search` -| `array (string)` -| Search configures priority ordered search domains for short hostname lookups - -|=== -..spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig.staticIPAMConfig.routes -Description:: - Routes configures IP routes for the interface - -Type:: - `array` - - - - -..spec.additionalNetworks[].simpleMacvlanConfig.ipamConfig.staticIPAMConfig.routes[] -Description:: - StaticIPAMRoutes provides Destination/Gateway pairs for static IPAM routes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `destination` -| `string` -| Destination points the IP route destination - -| `gateway` -| `string` -| Gateway is the route's next-hop IP address If unset, a default gateway is assumed (as determined by the CNI plugin). - -|=== -..spec.clusterNetwork -Description:: - clusterNetwork is the IP address pool to use for pod IPs. Some network providers, e.g. OpenShift SDN, support multiple ClusterNetworks. Others only support one. This is equivalent to the cluster-cidr. - -Type:: - `array` - - - - -..spec.clusterNetwork[] -Description:: - ClusterNetworkEntry is a subnet from which to allocate PodIPs. A network of size HostPrefix (in CIDR notation) will be allocated when nodes join the cluster. If the HostPrefix field is not used by the plugin, it can be left unset. Not all network providers support multiple ClusterNetworks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cidr` -| `string` -| - -| `hostPrefix` -| `integer` -| - -|=== -..spec.defaultNetwork -Description:: - defaultNetwork is the "default" network that all pods will receive - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kuryrConfig` -| `object` -| KuryrConfig configures the kuryr plugin - -| `openshiftSDNConfig` -| `object` -| openShiftSDNConfig configures the openshift-sdn plugin - -| `ovnKubernetesConfig` -| `object` -| oVNKubernetesConfig configures the ovn-kubernetes plugin. This is currently not implemented. - -| `type` -| `string` -| type is the type of network All NetworkTypes are supported except for NetworkTypeRaw - -|=== -..spec.defaultNetwork.kuryrConfig -Description:: - KuryrConfig configures the kuryr plugin - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `controllerProbesPort` -| `integer` -| The port kuryr-controller will listen for readiness and liveness requests. - -| `daemonProbesPort` -| `integer` -| The port kuryr-daemon will listen for readiness and liveness requests. - -| `enablePortPoolsPrepopulation` -| `boolean` -| enablePortPoolsPrepopulation when true will make Kuryr prepopulate each newly created port pool with a minimum number of ports. Kuryr uses Neutron port pooling to fight the fact that it takes a significant amount of time to create one. Instead of creating it when pod is being deployed, Kuryr keeps a number of ports ready to be attached to pods. By default port prepopulation is disabled. - -| `openStackServiceNetwork` -| `string` -| openStackServiceNetwork contains the CIDR of network from which to allocate IPs for OpenStack Octavia's Amphora VMs. Please note that with Amphora driver Octavia uses two IPs from that network for each loadbalancer - one given by OpenShift and second for VRRP connections. As the first one is managed by OpenShift's and second by Neutron's IPAMs, those need to come from different pools. Therefore `openStackServiceNetwork` needs to be at least twice the size of `serviceNetwork`, and whole `serviceNetwork` must be overlapping with `openStackServiceNetwork`. cluster-network-operator will then make sure VRRP IPs are taken from the ranges inside `openStackServiceNetwork` that are not overlapping with `serviceNetwork`, effectivly preventing conflicts. If not set cluster-network-operator will use `serviceNetwork` expanded by decrementing the prefix size by 1. - -| `poolBatchPorts` -| `integer` -| poolBatchPorts sets a number of ports that should be created in a single batch request to extend the port pool. The default is 3. For more information about port pools see enablePortPoolsPrepopulation setting. - -| `poolMaxPorts` -| `integer` -| poolMaxPorts sets a maximum number of free ports that are being kept in a port pool. If the number of ports exceeds this setting, free ports will get deleted. Setting 0 will disable this upper bound, effectively preventing pools from shrinking and this is the default value. For more information about port pools see enablePortPoolsPrepopulation setting. - -| `poolMinPorts` -| `integer` -| poolMinPorts sets a minimum number of free ports that should be kept in a port pool. If the number of ports is lower than this setting, new ports will get created and added to pool. The default is 1. For more information about port pools see enablePortPoolsPrepopulation setting. - -|=== -..spec.defaultNetwork.openshiftSDNConfig -Description:: - openShiftSDNConfig configures the openshift-sdn plugin - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `enableUnidling` -| `boolean` -| enableUnidling controls whether or not the service proxy will support idling and unidling of services. By default, unidling is enabled. - -| `mode` -| `string` -| mode is one of "Multitenant", "Subnet", or "NetworkPolicy" - -| `mtu` -| `integer` -| mtu is the mtu to use for the tunnel interface. Defaults to 1450 if unset. This must be 50 bytes smaller than the machine's uplink. - -| `useExternalOpenvswitch` -| `boolean` -| useExternalOpenvswitch tells the operator not to install openvswitch, because it will be provided separately. If set, you must provide it yourself. - -| `vxlanPort` -| `integer` -| vxlanPort is the port to use for all vxlan packets. The default is 4789. - -|=== -..spec.defaultNetwork.ovnKubernetesConfig -Description:: - oVNKubernetesConfig configures the ovn-kubernetes plugin. This is currently not implemented. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `genevePort` -| `integer` -| geneve port is the UDP port to be used by geneve encapulation. Default is 6081 - -| `hybridOverlayConfig` -| `object` -| HybridOverlayConfig configures an additional overlay network for peers that are not using OVN. - -| `ipsecConfig` -| `object` -| ipsecConfig enables and configures IPsec for pods on the pod network within the cluster. - -| `mtu` -| `integer` -| mtu is the MTU to use for the tunnel interface. This must be 100 bytes smaller than the uplink mtu. Default is 1400 - -|=== -..spec.defaultNetwork.ovnKubernetesConfig.hybridOverlayConfig -Description:: - HybridOverlayConfig configures an additional overlay network for peers that are not using OVN. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hybridClusterNetwork` -| `array` -| HybridClusterNetwork defines a network space given to nodes on an additional overlay network. - -| `hybridClusterNetwork[]` -| `object` -| ClusterNetworkEntry is a subnet from which to allocate PodIPs. A network of size HostPrefix (in CIDR notation) will be allocated when nodes join the cluster. If the HostPrefix field is not used by the plugin, it can be left unset. Not all network providers support multiple ClusterNetworks - -| `hybridOverlayVXLANPort` -| `integer` -| HybridOverlayVXLANPort defines the VXLAN port number to be used by the additional overlay network. Default is 4789 - -|=== -..spec.defaultNetwork.ovnKubernetesConfig.hybridOverlayConfig.hybridClusterNetwork -Description:: - HybridClusterNetwork defines a network space given to nodes on an additional overlay network. - -Type:: - `array` - - - - -..spec.defaultNetwork.ovnKubernetesConfig.hybridOverlayConfig.hybridClusterNetwork[] -Description:: - ClusterNetworkEntry is a subnet from which to allocate PodIPs. A network of size HostPrefix (in CIDR notation) will be allocated when nodes join the cluster. If the HostPrefix field is not used by the plugin, it can be left unset. Not all network providers support multiple ClusterNetworks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cidr` -| `string` -| - -| `hostPrefix` -| `integer` -| - -|=== -..spec.defaultNetwork.ovnKubernetesConfig.ipsecConfig -Description:: - ipsecConfig enables and configures IPsec for pods on the pod network within the cluster. - -Type:: - `object` - - - - -..spec.kubeProxyConfig -Description:: - kubeProxyConfig lets us configure desired proxy configuration. If not specified, sensible defaults will be chosen by OpenShift directly. Not consumed by all network providers - currently only openshift-sdn. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bindAddress` -| `string` -| The address to "bind" on Defaults to 0.0.0.0 - -| `iptablesSyncPeriod` -| `string` -| An internal kube-proxy parameter. In older releases of OCP, this sometimes needed to be adjusted in large clusters for performance reasons, but this is no longer necessary, and there is no reason to change this from the default value. Default: 30s - -| `proxyArguments` -| `object` -| Any additional arguments to pass to the kubeproxy process - -| `proxyArguments{}` -| `array (string)` -| ProxyArgumentList is a list of arguments to pass to the kubeproxy process - -|=== -..spec.kubeProxyConfig.proxyArguments -Description:: - Any additional arguments to pass to the kubeproxy process - -Type:: - `object` - - - - -..status -Description:: - NetworkStatus is detailed operator status, which is distilled up to the Network clusteroperator object. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/networks` -- `DELETE`: delete collection of Network -- `GET`: list objects of kind Network -- `POST`: create a Network -* `/apis/operator.openshift.io/v1/networks/{name}` -- `DELETE`: delete a Network -- `GET`: read the specified Network -- `PATCH`: partially update the specified Network -- `PUT`: replace the specified Network - - -=== /apis/operator.openshift.io/v1/networks - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#networklist-operator-openshift-io-v1[`NetworkList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/networks/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Network -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Network - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/network-operator-openshift-io-v1.adoc#network-operator-openshift-io-v1[`Network operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc b/rest_api/operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc deleted file mode 100644 index 4ecc8b081e55..000000000000 --- a/rest_api/operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,719 +0,0 @@ -[id="openshiftapiserver-operator-openshift-io-v1"] -= OpenShiftAPIServer [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OpenShiftAPIServer provides information to configure an operator to manage openshift-apiserver. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec is the specification of the desired behavior of the OpenShift API Server. - -| `status` -| `object` -| status defines the observed status of the OpenShift API Server. - -|=== -..spec -Description:: - spec is the specification of the desired behavior of the OpenShift API Server. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status defines the observed status of the OpenShift API Server. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `latestAvailableRevision` -| `integer` -| latestAvailableRevision is the latest revision used as suffix of revisioned secrets like encryption-config. A new revision causes a new deployment of pods. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/openshiftapiservers` -- `DELETE`: delete collection of OpenShiftAPIServer -- `GET`: list objects of kind OpenShiftAPIServer -- `POST`: create an OpenShiftAPIServer -* `/apis/operator.openshift.io/v1/openshiftapiservers/{name}` -- `DELETE`: delete an OpenShiftAPIServer -- `GET`: read the specified OpenShiftAPIServer -- `PATCH`: partially update the specified OpenShiftAPIServer -- `PUT`: replace the specified OpenShiftAPIServer -* `/apis/operator.openshift.io/v1/openshiftapiservers/{name}/status` -- `GET`: read status of the specified OpenShiftAPIServer -- `PATCH`: partially update status of the specified OpenShiftAPIServer -- `PUT`: replace status of the specified OpenShiftAPIServer - - -=== /apis/operator.openshift.io/v1/openshiftapiservers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#openshiftapiserverlist-operator-openshift-io-v1[`OpenShiftAPIServerList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/openshiftapiservers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OpenShiftAPIServer -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/openshiftapiservers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OpenShiftAPIServer -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified OpenShiftAPIServer - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/openshiftapiserver-operator-openshift-io-v1.adoc#openshiftapiserver-operator-openshift-io-v1[`OpenShiftAPIServer operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc b/rest_api/operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc deleted file mode 100644 index a4292943c5ca..000000000000 --- a/rest_api/operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,715 +0,0 @@ -[id="openshiftcontrollermanager-operator-openshift-io-v1"] -= OpenShiftControllerManager [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OpenShiftControllerManager provides information to configure an operator to manage openshift-controller-manager. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| - -| `status` -| `object` -| - -|=== -..spec -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/openshiftcontrollermanagers` -- `DELETE`: delete collection of OpenShiftControllerManager -- `GET`: list objects of kind OpenShiftControllerManager -- `POST`: create an OpenShiftControllerManager -* `/apis/operator.openshift.io/v1/openshiftcontrollermanagers/{name}` -- `DELETE`: delete an OpenShiftControllerManager -- `GET`: read the specified OpenShiftControllerManager -- `PATCH`: partially update the specified OpenShiftControllerManager -- `PUT`: replace the specified OpenShiftControllerManager -* `/apis/operator.openshift.io/v1/openshiftcontrollermanagers/{name}/status` -- `GET`: read status of the specified OpenShiftControllerManager -- `PATCH`: partially update status of the specified OpenShiftControllerManager -- `PUT`: replace status of the specified OpenShiftControllerManager - - -=== /apis/operator.openshift.io/v1/openshiftcontrollermanagers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#openshiftcontrollermanagerlist-operator-openshift-io-v1[`OpenShiftControllerManagerList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/openshiftcontrollermanagers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OpenShiftControllerManager -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/openshiftcontrollermanagers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OpenShiftControllerManager -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified OpenShiftControllerManager - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/openshiftcontrollermanager-operator-openshift-io-v1.adoc#openshiftcontrollermanager-operator-openshift-io-v1[`OpenShiftControllerManager operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/operator-apis-index.adoc b/rest_api/operator_apis/operator-apis-index.adoc deleted file mode 100644 index ce4dcd610c75..000000000000 --- a/rest_api/operator_apis/operator-apis-index.adoc +++ /dev/null @@ -1,209 +0,0 @@ -[id="operator-apis"] -= Operator APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== Authentication [operator.openshift.io/v1] - -Description:: - Authentication provides information to configure an operator to manage authentication. - -Type:: - `object` - -== CloudCredential [operator.openshift.io/v1] - -Description:: - CloudCredential provides a means to configure an operator to manage CredentialsRequests. - -Type:: - `object` - -== ClusterCSIDriver [operator.openshift.io/v1] - -Description:: - ClusterCSIDriver object allows management and configuration of a CSI driver operator installed by default in OpenShift. Name of the object must be name of the CSI driver it operates. See CSIDriverName type for list of allowed values. - -Type:: - `object` - -== Console [operator.openshift.io/v1] - -Description:: - Console provides a means to configure an operator to manage the console. - -Type:: - `object` - -== Config [operator.openshift.io/v1] - -Description:: - Config provides information to configure the config operator. - -Type:: - `object` - -== Config [imageregistry.operator.openshift.io/v1] - -Description:: - Config is the configuration object for a registry instance managed by the registry operator - -Type:: - `object` - -== Config [samples.operator.openshift.io/v1] - -Description:: - Config contains the configuration and detailed condition status for the Samples Operator. - -Type:: - `object` - -== CSISnapshotController [operator.openshift.io/v1] - -Description:: - CSISnapshotController provides a means to configure an operator to manage the CSI snapshots. `cluster` is the canonical name. - -Type:: - `object` - -== DNS [operator.openshift.io/v1] - -Description:: - DNS manages the CoreDNS component to provide a name resolution service for pods and services in the cluster. - This supports the DNS-based service discovery specification: https://github.com/kubernetes/dns/blob/master/docs/specification.md - More details: https://kubernetes.io/docs/tasks/administer-cluster/coredns - -Type:: - `object` - -== DNSRecord [ingress.operator.openshift.io/v1] - -Description:: - DNSRecord is a DNS record managed in the zones defined by dns.config.openshift.io/cluster .spec.publicZone and .spec.privateZone. - Cluster admin manipulation of this resource is not supported. This resource is only for internal communication of OpenShift operators. - -Type:: - `object` - -== Etcd [operator.openshift.io/v1] - -Description:: - Etcd provides information to configure an operator to manage kube-apiserver. - -Type:: - `object` - -== ImageContentSourcePolicy [operator.openshift.io/v1alpha1] - -Description:: - ImageContentSourcePolicy holds cluster-wide information about how to handle registry mirror rules. When multiple policies are defined, the outcome of the behavior is defined on each field. - -Type:: - `object` - -== ImagePruner [imageregistry.operator.openshift.io/v1] - -Description:: - ImagePruner is the configuration object for an image registry pruner managed by the registry operator. - -Type:: - `object` - -== IngressController [operator.openshift.io/v1] - -Description:: - IngressController describes a managed ingress controller for the cluster. The controller can service OpenShift Route and Kubernetes Ingress resources. - When an IngressController is created, a new ingress controller deployment is created to allow external traffic to reach the services that expose Ingress or Route resources. Updating this resource may lead to disruption for public facing network connections as a new ingress controller revision may be rolled out. - https://kubernetes.io/docs/concepts/services-networking/ingress-controllers - Whenever possible, sensible defaults for the platform are used. See each field for more details. - -Type:: - `object` - -== KubeAPIServer [operator.openshift.io/v1] - -Description:: - KubeAPIServer provides information to configure an operator to manage kube-apiserver. - -Type:: - `object` - -== KubeControllerManager [operator.openshift.io/v1] - -Description:: - KubeControllerManager provides information to configure an operator to manage kube-controller-manager. - -Type:: - `object` - -== KubeScheduler [operator.openshift.io/v1] - -Description:: - KubeScheduler provides information to configure an operator to manage scheduler. - -Type:: - `object` - -== KubeStorageVersionMigrator [operator.openshift.io/v1] - -Description:: - KubeStorageVersionMigrator provides information to configure an operator to manage kube-storage-version-migrator. - -Type:: - `object` - -== Network [operator.openshift.io/v1] - -Description:: - Network describes the cluster's desired network configuration. It is consumed by the cluster-network-operator. - -Type:: - `object` - -== OpenShiftAPIServer [operator.openshift.io/v1] - -Description:: - OpenShiftAPIServer provides information to configure an operator to manage openshift-apiserver. - -Type:: - `object` - -== OpenShiftControllerManager [operator.openshift.io/v1] - -Description:: - OpenShiftControllerManager provides information to configure an operator to manage openshift-controller-manager. - -Type:: - `object` - -== OperatorPKI [network.operator.openshift.io/v1] - -Description:: - OperatorPKI is a simple certificate authority. It is not intended for external use - rather, it is internal to the network operator. The CNO creates a CA and a certificate signed by that CA. The certificate has both ClientAuth and ServerAuth extended usages enabled. - More specifically, given an OperatorPKI with <name>, the CNO will manage: - A Secret called <name>-ca with two data keys: - tls.key - the private key - tls.crt - the CA certificate - A ConfigMap called <name>-ca with a single data key: - cabundle.crt - the CA certificate(s) - A Secret called <name>-cert with two data keys: - tls.key - the private key - tls.crt - the certificate, signed by the CA - The CA certificate will have a validity of 10 years, rotated after 9. The target certificate will have a validity of 6 months, rotated after 3 - The CA certificate will have a CommonName of "<namespace>_<name>-ca@<timestamp>", where <timestamp> is the last rotation time. - -Type:: - `object` - -== ServiceCA [operator.openshift.io/v1] - -Description:: - ServiceCA provides information to configure an operator to manage the service cert controllers - -Type:: - `object` - -== Storage [operator.openshift.io/v1] - -Description:: - Storage provides a means to configure an operator to manage the cluster storage operator. `cluster` is the canonical name. - -Type:: - `object` - diff --git a/rest_api/operator_apis/operatorpki-network-operator-openshift-io-v1.adoc b/rest_api/operator_apis/operatorpki-network-operator-openshift-io-v1.adoc deleted file mode 100644 index 2609ed49989f..000000000000 --- a/rest_api/operator_apis/operatorpki-network-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,542 +0,0 @@ -[id="operatorpki-network-operator-openshift-io-v1"] -= OperatorPKI [network.operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OperatorPKI is a simple certificate authority. It is not intended for external use - rather, it is internal to the network operator. The CNO creates a CA and a certificate signed by that CA. The certificate has both ClientAuth and ServerAuth extended usages enabled. - More specifically, given an OperatorPKI with <name>, the CNO will manage: - A Secret called <name>-ca with two data keys: - tls.key - the private key - tls.crt - the CA certificate - A ConfigMap called <name>-ca with a single data key: - cabundle.crt - the CA certificate(s) - A Secret called <name>-cert with two data keys: - tls.key - the private key - tls.crt - the certificate, signed by the CA - The CA certificate will have a validity of 10 years, rotated after 9. The target certificate will have a validity of 6 months, rotated after 3 - The CA certificate will have a CommonName of "<namespace>_<name>-ca@<timestamp>", where <timestamp> is the last rotation time. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| OperatorPKISpec is the PKI configuration. - -| `status` -| `object` -| OperatorPKIStatus is not implemented. - -|=== -..spec -Description:: - OperatorPKISpec is the PKI configuration. - -Type:: - `object` - -Required:: - - `targetCert` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `targetCert` -| `object` -| targetCert configures the certificate signed by the CA. It will have both ClientAuth and ServerAuth enabled - -|=== -..spec.targetCert -Description:: - targetCert configures the certificate signed by the CA. It will have both ClientAuth and ServerAuth enabled - -Type:: - `object` - -Required:: - - `commonName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `commonName` -| `string` -| commonName is the value in the certificate's CN - -|=== -..status -Description:: - OperatorPKIStatus is not implemented. - -Type:: - `object` - - - - - -== API endpoints - -The following API endpoints are available: - -* `/apis/network.operator.openshift.io/v1/operatorpkis` -- `GET`: list objects of kind OperatorPKI -* `/apis/network.operator.openshift.io/v1/namespaces/{namespace}/operatorpkis` -- `DELETE`: delete collection of OperatorPKI -- `GET`: list objects of kind OperatorPKI -- `POST`: create an OperatorPKI -* `/apis/network.operator.openshift.io/v1/namespaces/{namespace}/operatorpkis/{name}` -- `DELETE`: delete an OperatorPKI -- `GET`: read the specified OperatorPKI -- `PATCH`: partially update the specified OperatorPKI -- `PUT`: replace the specified OperatorPKI - - -=== /apis/network.operator.openshift.io/v1/operatorpkis - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OperatorPKI - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#operatorpkilist-network-operator-openshift-io-v1[`OperatorPKIList network.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/network.operator.openshift.io/v1/namespaces/{namespace}/operatorpkis - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OperatorPKI - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OperatorPKI - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#operatorpkilist-network-operator-openshift-io-v1[`OperatorPKIList network.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OperatorPKI - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/network.operator.openshift.io/v1/namespaces/{namespace}/operatorpkis/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OperatorPKI -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OperatorPKI - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OperatorPKI - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OperatorPKI - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OperatorPKI - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/operatorpki-network-operator-openshift-io-v1.adoc#operatorpki-network-operator-openshift-io-v1[`OperatorPKI network.operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/serviceca-operator-openshift-io-v1.adoc b/rest_api/operator_apis/serviceca-operator-openshift-io-v1.adoc deleted file mode 100644 index 864b279c631e..000000000000 --- a/rest_api/operator_apis/serviceca-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,715 +0,0 @@ -[id="serviceca-operator-openshift-io-v1"] -= ServiceCA [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ServiceCA provides information to configure an operator to manage the service cert controllers - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/servicecas` -- `DELETE`: delete collection of ServiceCA -- `GET`: list objects of kind ServiceCA -- `POST`: create a ServiceCA -* `/apis/operator.openshift.io/v1/servicecas/{name}` -- `DELETE`: delete a ServiceCA -- `GET`: read the specified ServiceCA -- `PATCH`: partially update the specified ServiceCA -- `PUT`: replace the specified ServiceCA -* `/apis/operator.openshift.io/v1/servicecas/{name}/status` -- `GET`: read status of the specified ServiceCA -- `PATCH`: partially update status of the specified ServiceCA -- `PUT`: replace status of the specified ServiceCA - - -=== /apis/operator.openshift.io/v1/servicecas - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#servicecalist-operator-openshift-io-v1[`ServiceCAList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/servicecas/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ServiceCA -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/servicecas/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ServiceCA -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ServiceCA - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/serviceca-operator-openshift-io-v1.adoc#serviceca-operator-openshift-io-v1[`ServiceCA operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operator_apis/storage-operator-openshift-io-v1.adoc b/rest_api/operator_apis/storage-operator-openshift-io-v1.adoc deleted file mode 100644 index c35fd9fdea3e..000000000000 --- a/rest_api/operator_apis/storage-operator-openshift-io-v1.adoc +++ /dev/null @@ -1,715 +0,0 @@ -[id="storage-operator-openshift-io-v1"] -= Storage [operator.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Storage provides a means to configure an operator to manage the cluster storage operator. `cluster` is the canonical name. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec holds user settable values for configuration - -| `status` -| `object` -| status holds observed values from the cluster. They may not be overridden. - -|=== -..spec -Description:: - spec holds user settable values for configuration - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `logLevel` -| `string` -| logLevel is an intent based logging for an overall component. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for their operands. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `managementState` -| `string` -| managementState indicates whether and how the operator should manage the component - -| `observedConfig` -| `` -| observedConfig holds a sparse config that controller has observed from the cluster state. It exists in spec because it is an input to the level for the operator - -| `operatorLogLevel` -| `string` -| operatorLogLevel is an intent based logging for the operator itself. It does not give fine grained control, but it is a simple way to manage coarse grained logging choices that operators have to interpret for themselves. - Valid values are: "Normal", "Debug", "Trace", "TraceAll". Defaults to "Normal". - -| `unsupportedConfigOverrides` -| `` -| unsupportedConfigOverrides holds a sparse config that will override any previously set options. It only needs to be the fields to override it will end up overlaying in the following order: 1. hardcoded defaults 2. observedConfig 3. unsupportedConfigOverrides - -|=== -..status -Description:: - status holds observed values from the cluster. They may not be overridden. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operator.openshift.io/v1/storages` -- `DELETE`: delete collection of Storage -- `GET`: list objects of kind Storage -- `POST`: create a Storage -* `/apis/operator.openshift.io/v1/storages/{name}` -- `DELETE`: delete a Storage -- `GET`: read the specified Storage -- `PATCH`: partially update the specified Storage -- `PUT`: replace the specified Storage -* `/apis/operator.openshift.io/v1/storages/{name}/status` -- `GET`: read status of the specified Storage -- `PATCH`: partially update status of the specified Storage -- `PUT`: replace status of the specified Storage - - -=== /apis/operator.openshift.io/v1/storages - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#storagelist-operator-openshift-io-v1[`StorageList operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 202 - Accepted -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/storages/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Storage -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operator.openshift.io/v1/storages/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Storage -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Storage - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 201 - Created -| xref:../operator_apis/storage-operator-openshift-io-v1.adoc#storage-operator-openshift-io-v1[`Storage operator.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc b/rest_api/operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc deleted file mode 100644 index 0671475c06a3..000000000000 --- a/rest_api/operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc +++ /dev/null @@ -1,889 +0,0 @@ -[id="catalogsource-operators-coreos-com-v1alpha1"] -= CatalogSource [operators.coreos.com/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CatalogSource is a repository of CSVs, CRDs, and operator packages. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| - -| `status` -| `object` -| - -|=== -..spec -Description:: - - -Type:: - `object` - -Required:: - - `sourceType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `address` -| `string` -| Address is a host that OLM can use to connect to a pre-existing registry. Format: <registry-host or ip>:<port> Only used when SourceType = SourceTypeGrpc. Ignored when the Image field is set. - -| `configMap` -| `string` -| ConfigMap is the name of the ConfigMap to be used to back a configmap-server registry. Only used when SourceType = SourceTypeConfigmap or SourceTypeInternal. - -| `description` -| `string` -| - -| `displayName` -| `string` -| Metadata - -| `icon` -| `object` -| - -| `image` -| `string` -| Image is an operator-registry container image to instantiate a registry-server with. Only used when SourceType = SourceTypeGrpc. If present, the address field is ignored. - -| `priority` -| `integer` -| Priority field assigns a weight to the catalog source to prioritize them so that it can be consumed by the dependency resolver. Usage: Higher weight indicates that this catalog source is preferred over lower weighted catalog sources during dependency resolution. The range of the priority value can go from positive to negative in the range of int32. The default value to a catalog source with unassigned priority would be 0. The catalog source with the same priority values will be ranked lexicographically based on its name. - -| `publisher` -| `string` -| - -| `secrets` -| `array (string)` -| Secrets represent set of secrets that can be used to access the contents of the catalog. It is best to keep this list small, since each will need to be tried for every catalog entry. - -| `sourceType` -| `string` -| SourceType is the type of source - -| `updateStrategy` -| `object` -| UpdateStrategy defines how updated catalog source images can be discovered Consists of an interval that defines polling duration and an embedded strategy type - -|=== -..spec.icon -Description:: - - -Type:: - `object` - -Required:: - - `base64data` - - `mediatype` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `base64data` -| `string` -| - -| `mediatype` -| `string` -| - -|=== -..spec.updateStrategy -Description:: - UpdateStrategy defines how updated catalog source images can be discovered Consists of an interval that defines polling duration and an embedded strategy type - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `registryPoll` -| `object` -| - -|=== -..spec.updateStrategy.registryPoll -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `interval` -| `string` -| Interval is used to determine the time interval between checks of the latest catalog source version. The catalog operator polls to see if a new version of the catalog source is available. If available, the latest image is pulled and gRPC traffic is directed to the latest catalog source. - -|=== -..status -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapReference` -| `object` -| - -| `connectionState` -| `object` -| - -| `latestImageRegistryPoll` -| `string` -| The last time the CatalogSource image registry has been polled to ensure the image is up-to-date - -| `message` -| `string` -| A human readable message indicating details about why the CatalogSource is in this condition. - -| `reason` -| `string` -| Reason is the reason the CatalogSource was transitioned to its current state. - -| `registryService` -| `object` -| - -|=== -..status.configMapReference -Description:: - - -Type:: - `object` - -Required:: - - `name` - - `namespace` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastUpdateTime` -| `string` -| - -| `name` -| `string` -| - -| `namespace` -| `string` -| - -| `resourceVersion` -| `string` -| - -| `uid` -| `string` -| UID is a type that holds unique ID values, including UUIDs. Because we don't ONLY use UUIDs, this is an alias to string. Being a type captures intent and helps make sure that UIDs and names do not get conflated. - -|=== -..status.connectionState -Description:: - - -Type:: - `object` - -Required:: - - `lastObservedState` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `address` -| `string` -| - -| `lastConnect` -| `string` -| - -| `lastObservedState` -| `string` -| - -|=== -..status.registryService -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `createdAt` -| `string` -| - -| `port` -| `string` -| - -| `protocol` -| `string` -| - -| `serviceName` -| `string` -| - -| `serviceNamespace` -| `string` -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operators.coreos.com/v1alpha1/catalogsources` -- `GET`: list objects of kind CatalogSource -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/catalogsources` -- `DELETE`: delete collection of CatalogSource -- `GET`: list objects of kind CatalogSource -- `POST`: create a CatalogSource -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/catalogsources/{name}` -- `DELETE`: delete a CatalogSource -- `GET`: read the specified CatalogSource -- `PATCH`: partially update the specified CatalogSource -- `PUT`: replace the specified CatalogSource -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/catalogsources/{name}/status` -- `GET`: read status of the specified CatalogSource -- `PATCH`: partially update status of the specified CatalogSource -- `PUT`: replace status of the specified CatalogSource - - -=== /apis/operators.coreos.com/v1alpha1/catalogsources - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind CatalogSource - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#catalogsourcelist-operators-coreos-com-v1alpha1[`CatalogSourceList operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/catalogsources - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#catalogsourcelist-operators-coreos-com-v1alpha1[`CatalogSourceList operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 202 - Accepted -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/catalogsources/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CatalogSource -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/catalogsources/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CatalogSource -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified CatalogSource - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/catalogsource-operators-coreos-com-v1alpha1.adoc#catalogsource-operators-coreos-com-v1alpha1[`CatalogSource operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc b/rest_api/operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc deleted file mode 100644 index f73b32dc568a..000000000000 --- a/rest_api/operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc +++ /dev/null @@ -1,11284 +0,0 @@ -[id="clusterserviceversion-operators-coreos-com-v1alpha1"] -= ClusterServiceVersion [operators.coreos.com/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterServiceVersion is a Custom Resource of type `ClusterServiceVersionSpec`. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ClusterServiceVersionSpec declarations tell OLM how to install an operator that can manage apps for a given version. - -| `status` -| `object` -| ClusterServiceVersionStatus represents information about the status of a pod. Status may trail the actual state of a system. - -|=== -..spec -Description:: - ClusterServiceVersionSpec declarations tell OLM how to install an operator that can manage apps for a given version. - -Type:: - `object` - -Required:: - - `displayName` - - `install` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. - -| `apiservicedefinitions` -| `object` -| APIServiceDefinitions declares all of the extension apis managed or required by an operator being ran by ClusterServiceVersion. - -| `customresourcedefinitions` -| `object` -| CustomResourceDefinitions declares all of the CRDs managed or required by an operator being ran by ClusterServiceVersion. - If the CRD is present in the Owned list, it is implicitly required. - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `icon` -| `array` -| - -| `icon[]` -| `object` -| - -| `install` -| `object` -| NamedInstallStrategy represents the block of an ClusterServiceVersion resource where the install strategy is specified. - -| `installModes` -| `array` -| InstallModes specify supported installation types - -| `installModes[]` -| `object` -| InstallMode associates an InstallModeType with a flag representing if the CSV supports it - -| `keywords` -| `array (string)` -| - -| `labels` -| `object (string)` -| Map of string keys and values that can be used to organize and categorize (scope and select) objects. - -| `links` -| `array` -| - -| `links[]` -| `object` -| - -| `maintainers` -| `array` -| - -| `maintainers[]` -| `object` -| - -| `maturity` -| `string` -| - -| `minKubeVersion` -| `string` -| - -| `nativeAPIs` -| `array` -| - -| `nativeAPIs[]` -| `object` -| GroupVersionKind unambiguously identifies a kind. It doesn't anonymously include GroupVersion to avoid automatic coersion. It doesn't use a GroupVersion to avoid custom marshalling - -| `provider` -| `object` -| - -| `replaces` -| `string` -| The name of a CSV this one replaces. Should match the `metadata.Name` field of the old CSV. - -| `selector` -| `object` -| Label selector for related resources. - -| `version` -| `string` -| OperatorVersion is a wrapper around semver.Version which supports correct marshaling to YAML and JSON. - -| `webhookdefinitions` -| `array` -| - -| `webhookdefinitions[]` -| `object` -| WebhookDescription provides details to OLM about required webhooks - -|=== -..spec.apiservicedefinitions -Description:: - APIServiceDefinitions declares all of the extension apis managed or required by an operator being ran by ClusterServiceVersion. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `owned` -| `array` -| - -| `owned[]` -| `object` -| APIServiceDescription provides details to OLM about apis provided via aggregation - -| `required` -| `array` -| - -| `required[]` -| `object` -| APIServiceDescription provides details to OLM about apis provided via aggregation - -|=== -..spec.apiservicedefinitions.owned -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.owned[] -Description:: - APIServiceDescription provides details to OLM about apis provided via aggregation - -Type:: - `object` - -Required:: - - `group` - - `kind` - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actionDescriptors` -| `array` -| - -| `actionDescriptors[]` -| `object` -| ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -| `containerPort` -| `integer` -| - -| `deploymentName` -| `string` -| - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `resources` -| `array` -| - -| `resources[]` -| `object` -| APIResourceReference is a Kubernetes resource type used by a custom resource - -| `specDescriptors` -| `array` -| - -| `specDescriptors[]` -| `object` -| SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -| `statusDescriptors` -| `array` -| - -| `statusDescriptors[]` -| `object` -| StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -| `version` -| `string` -| - -|=== -..spec.apiservicedefinitions.owned[].actionDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.owned[].actionDescriptors[] -Description:: - ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.apiservicedefinitions.owned[].resources -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.owned[].resources[] -Description:: - APIResourceReference is a Kubernetes resource type used by a custom resource - -Type:: - `object` - -Required:: - - `kind` - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `version` -| `string` -| - -|=== -..spec.apiservicedefinitions.owned[].specDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.owned[].specDescriptors[] -Description:: - SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.apiservicedefinitions.owned[].statusDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.owned[].statusDescriptors[] -Description:: - StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.apiservicedefinitions.required -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.required[] -Description:: - APIServiceDescription provides details to OLM about apis provided via aggregation - -Type:: - `object` - -Required:: - - `group` - - `kind` - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actionDescriptors` -| `array` -| - -| `actionDescriptors[]` -| `object` -| ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -| `containerPort` -| `integer` -| - -| `deploymentName` -| `string` -| - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `resources` -| `array` -| - -| `resources[]` -| `object` -| APIResourceReference is a Kubernetes resource type used by a custom resource - -| `specDescriptors` -| `array` -| - -| `specDescriptors[]` -| `object` -| SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -| `statusDescriptors` -| `array` -| - -| `statusDescriptors[]` -| `object` -| StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -| `version` -| `string` -| - -|=== -..spec.apiservicedefinitions.required[].actionDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.required[].actionDescriptors[] -Description:: - ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.apiservicedefinitions.required[].resources -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.required[].resources[] -Description:: - APIResourceReference is a Kubernetes resource type used by a custom resource - -Type:: - `object` - -Required:: - - `kind` - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `version` -| `string` -| - -|=== -..spec.apiservicedefinitions.required[].specDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.required[].specDescriptors[] -Description:: - SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.apiservicedefinitions.required[].statusDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.apiservicedefinitions.required[].statusDescriptors[] -Description:: - StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.customresourcedefinitions -Description:: - CustomResourceDefinitions declares all of the CRDs managed or required by an operator being ran by ClusterServiceVersion. - If the CRD is present in the Owned list, it is implicitly required. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `owned` -| `array` -| - -| `owned[]` -| `object` -| CRDDescription provides details to OLM about the CRDs - -| `required` -| `array` -| - -| `required[]` -| `object` -| CRDDescription provides details to OLM about the CRDs - -|=== -..spec.customresourcedefinitions.owned -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.owned[] -Description:: - CRDDescription provides details to OLM about the CRDs - -Type:: - `object` - -Required:: - - `kind` - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actionDescriptors` -| `array` -| - -| `actionDescriptors[]` -| `object` -| ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `resources` -| `array` -| - -| `resources[]` -| `object` -| APIResourceReference is a Kubernetes resource type used by a custom resource - -| `specDescriptors` -| `array` -| - -| `specDescriptors[]` -| `object` -| SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -| `statusDescriptors` -| `array` -| - -| `statusDescriptors[]` -| `object` -| StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -| `version` -| `string` -| - -|=== -..spec.customresourcedefinitions.owned[].actionDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.owned[].actionDescriptors[] -Description:: - ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.customresourcedefinitions.owned[].resources -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.owned[].resources[] -Description:: - APIResourceReference is a Kubernetes resource type used by a custom resource - -Type:: - `object` - -Required:: - - `kind` - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `version` -| `string` -| - -|=== -..spec.customresourcedefinitions.owned[].specDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.owned[].specDescriptors[] -Description:: - SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.customresourcedefinitions.owned[].statusDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.owned[].statusDescriptors[] -Description:: - StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.customresourcedefinitions.required -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.required[] -Description:: - CRDDescription provides details to OLM about the CRDs - -Type:: - `object` - -Required:: - - `kind` - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actionDescriptors` -| `array` -| - -| `actionDescriptors[]` -| `object` -| ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `resources` -| `array` -| - -| `resources[]` -| `object` -| APIResourceReference is a Kubernetes resource type used by a custom resource - -| `specDescriptors` -| `array` -| - -| `specDescriptors[]` -| `object` -| SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -| `statusDescriptors` -| `array` -| - -| `statusDescriptors[]` -| `object` -| StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -| `version` -| `string` -| - -|=== -..spec.customresourcedefinitions.required[].actionDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.required[].actionDescriptors[] -Description:: - ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.customresourcedefinitions.required[].resources -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.required[].resources[] -Description:: - APIResourceReference is a Kubernetes resource type used by a custom resource - -Type:: - `object` - -Required:: - - `kind` - - `name` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `version` -| `string` -| - -|=== -..spec.customresourcedefinitions.required[].specDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.required[].specDescriptors[] -Description:: - SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.customresourcedefinitions.required[].statusDescriptors -Description:: - - -Type:: - `array` - - - - -..spec.customresourcedefinitions.required[].statusDescriptors[] -Description:: - StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| RawMessage is a raw encoded JSON value. It implements Marshaler and Unmarshaler and can be used to delay JSON decoding or precompute a JSON encoding. - -| `x-descriptors` -| `array (string)` -| - -|=== -..spec.icon -Description:: - - -Type:: - `array` - - - - -..spec.icon[] -Description:: - - -Type:: - `object` - -Required:: - - `base64data` - - `mediatype` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `base64data` -| `string` -| - -| `mediatype` -| `string` -| - -|=== -..spec.install -Description:: - NamedInstallStrategy represents the block of an ClusterServiceVersion resource where the install strategy is specified. - -Type:: - `object` - -Required:: - - `strategy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `spec` -| `object` -| StrategyDetailsDeployment represents the parsed details of a Deployment InstallStrategy. - -| `strategy` -| `string` -| - -|=== -..spec.install.spec -Description:: - StrategyDetailsDeployment represents the parsed details of a Deployment InstallStrategy. - -Type:: - `object` - -Required:: - - `deployments` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clusterPermissions` -| `array` -| - -| `clusterPermissions[]` -| `object` -| StrategyDeploymentPermissions describe the rbac rules and service account needed by the install strategy - -| `deployments` -| `array` -| - -| `deployments[]` -| `object` -| StrategyDeploymentSpec contains the name, spec and labels for the deployment ALM should create - -| `permissions` -| `array` -| - -| `permissions[]` -| `object` -| StrategyDeploymentPermissions describe the rbac rules and service account needed by the install strategy - -|=== -..spec.install.spec.clusterPermissions -Description:: - - -Type:: - `array` - - - - -..spec.install.spec.clusterPermissions[] -Description:: - StrategyDeploymentPermissions describe the rbac rules and service account needed by the install strategy - -Type:: - `object` - -Required:: - - `rules` - - `serviceAccountName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `rules` -| `array` -| - -| `rules[]` -| `object` -| PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -| `serviceAccountName` -| `string` -| - -|=== -..spec.install.spec.clusterPermissions[].rules -Description:: - - -Type:: - `array` - - - - -..spec.install.spec.clusterPermissions[].rules[] -Description:: - PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -Type:: - `object` - -Required:: - - `verbs` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against one of the enumerated resources in any API group will be allowed. - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path Since non-resource URLs are not namespaced, this field is only applicable for ClusterRoles referenced from a ClusterRoleBinding. Rules can either apply to API resources (such as "pods" or "secrets") or non-resource URL paths (such as "/api"), but not both. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. ResourceAll represents all resources. - -| `verbs` -| `array (string)` -| Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule. VerbAll represents all kinds. - -|=== -..spec.install.spec.deployments -Description:: - - -Type:: - `array` - - - - -..spec.install.spec.deployments[] -Description:: - StrategyDeploymentSpec contains the name, spec and labels for the deployment ALM should create - -Type:: - `object` - -Required:: - - `name` - - `spec` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `label` -| `object (string)` -| Set is a map of label:value. It implements Labels. - -| `name` -| `string` -| - -| `spec` -| `object` -| DeploymentSpec is the specification of the desired behavior of the Deployment. - -|=== -..spec.install.spec.deployments[].spec -Description:: - DeploymentSpec is the specification of the desired behavior of the Deployment. - -Type:: - `object` - -Required:: - - `selector` - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `minReadySeconds` -| `integer` -| Minimum number of seconds for which a newly created pod should be ready without any of its container crashing, for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready) - -| `paused` -| `boolean` -| Indicates that the deployment is paused. - -| `progressDeadlineSeconds` -| `integer` -| The maximum time in seconds for a deployment to make progress before it is considered to be failed. The deployment controller will continue to process failed deployments and a condition with a ProgressDeadlineExceeded reason will be surfaced in the deployment status. Note that progress will not be estimated during the time a deployment is paused. Defaults to 600s. - -| `replicas` -| `integer` -| Number of desired pods. This is a pointer to distinguish between explicit zero and not specified. Defaults to 1. - -| `revisionHistoryLimit` -| `integer` -| The number of old ReplicaSets to retain to allow rollback. This is a pointer to distinguish between explicit zero and not specified. Defaults to 10. - -| `selector` -| `object` -| Label selector for pods. Existing ReplicaSets whose pods are selected by this will be the ones affected by this deployment. It must match the pod template's labels. - -| `strategy` -| `object` -| The deployment strategy to use to replace existing pods with new ones. - -| `template` -| `object` -| Template describes the pods that will be created. - -|=== -..spec.install.spec.deployments[].spec.selector -Description:: - Label selector for pods. Existing ReplicaSets whose pods are selected by this will be the ones affected by this deployment. It must match the pod template's labels. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.install.spec.deployments[].spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.strategy -Description:: - The deployment strategy to use to replace existing pods with new ones. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `rollingUpdate` -| `object` -| Rolling update config params. Present only if DeploymentStrategyType = RollingUpdate. --- TODO: Update this to follow our convention for oneOf, whatever we decide it to be. - -| `type` -| `string` -| Type of deployment. Can be "Recreate" or "RollingUpdate". Default is RollingUpdate. - -|=== -..spec.install.spec.deployments[].spec.strategy.rollingUpdate -Description:: - Rolling update config params. Present only if DeploymentStrategyType = RollingUpdate. --- TODO: Update this to follow our convention for oneOf, whatever we decide it to be. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxSurge` -| `integer-or-string` -| The maximum number of pods that can be scheduled above the desired number of pods. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). This can not be 0 if MaxUnavailable is 0. Absolute number is calculated from percentage by rounding up. Defaults to 25%. Example: when this is set to 30%, the new ReplicaSet can be scaled up immediately when the rolling update starts, such that the total number of old and new pods do not exceed 130% of desired pods. Once old pods have been killed, new ReplicaSet can be scaled up further, ensuring that total number of pods running at any time during the update is at most 130% of desired pods. - -| `maxUnavailable` -| `integer-or-string` -| The maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). Absolute number is calculated from percentage by rounding down. This can not be 0 if MaxSurge is 0. Defaults to 25%. Example: when this is set to 30%, the old ReplicaSet can be scaled down to 70% of desired pods immediately when the rolling update starts. Once new pods are ready, old ReplicaSet can be scaled down further, followed by scaling up the new ReplicaSet, ensuring that the total number of pods available at all times during the update is at least 70% of desired pods. - -|=== -..spec.install.spec.deployments[].spec.template -Description:: - Template describes the pods that will be created. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| `` -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of the desired behavior of the pod. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -|=== -..spec.install.spec.deployments[].spec.template.spec -Description:: - Specification of the desired behavior of the pod. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -Type:: - `object` - -Required:: - - `containers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `activeDeadlineSeconds` -| `integer` -| Optional duration in seconds the pod may be active on the node relative to StartTime before the system will actively try to mark it failed and kill associated containers. Value must be a positive integer. - -| `affinity` -| `object` -| If specified, the pod's scheduling constraints - -| `automountServiceAccountToken` -| `boolean` -| AutomountServiceAccountToken indicates whether a service account token should be automatically mounted. - -| `containers` -| `array` -| List of containers belonging to the pod. Containers cannot currently be added or removed. There must be at least one container in a Pod. Cannot be updated. - -| `containers[]` -| `object` -| A single application container that you want to run within a pod. - -| `dnsConfig` -| `object` -| Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy. - -| `dnsPolicy` -| `string` -| Set DNS policy for the pod. Defaults to "ClusterFirst". Valid values are 'ClusterFirstWithHostNet', 'ClusterFirst', 'Default' or 'None'. DNS parameters given in DNSConfig will be merged with the policy selected with DNSPolicy. To have DNS options set along with hostNetwork, you have to specify DNS policy explicitly to 'ClusterFirstWithHostNet'. - -| `enableServiceLinks` -| `boolean` -| EnableServiceLinks indicates whether information about services should be injected into pod's environment variables, matching the syntax of Docker links. Optional: Defaults to true. - -| `ephemeralContainers` -| `array` -| List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing pod to perform user-initiated actions such as debugging. This list cannot be specified when creating a pod, and it cannot be modified by updating the pod spec. In order to add an ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource. This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature. - -| `ephemeralContainers[]` -| `object` -| An EphemeralContainer is a container that may be added temporarily to an existing pod for user-initiated activities such as debugging. Ephemeral containers have no resource or scheduling guarantees, and they will not be restarted when they exit or when a pod is removed or restarted. If an ephemeral container causes a pod to exceed its resource allocation, the pod may be evicted. Ephemeral containers may not be added by directly updating the pod spec. They must be added via the pod's ephemeralcontainers subresource, and they will appear in the pod spec once added. This is an alpha feature enabled by the EphemeralContainers feature flag. - -| `hostAliases` -| `array` -| HostAliases is an optional list of hosts and IPs that will be injected into the pod's hosts file if specified. This is only valid for non-hostNetwork pods. - -| `hostAliases[]` -| `object` -| HostAlias holds the mapping between IP and hostnames that will be injected as an entry in the pod's hosts file. - -| `hostIPC` -| `boolean` -| Use the host's ipc namespace. Optional: Default to false. - -| `hostNetwork` -| `boolean` -| Host networking requested for this pod. Use the host's network namespace. If this option is set, the ports that will be used must be specified. Default to false. - -| `hostPID` -| `boolean` -| Use the host's pid namespace. Optional: Default to false. - -| `hostname` -| `string` -| Specifies the hostname of the Pod If not specified, the pod's hostname will be set to a system-defined value. - -| `imagePullSecrets` -| `array` -| ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. For example, in the case of docker, only DockerConfig type secrets are honored. More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod - -| `imagePullSecrets[]` -| `object` -| LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -| `initContainers` -| `array` -| List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. Init containers cannot currently be added or removed. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ - -| `initContainers[]` -| `object` -| A single application container that you want to run within a pod. - -| `nodeName` -| `string` -| NodeName is a request to schedule this pod onto a specific node. If it is non-empty, the scheduler simply schedules this pod onto that node, assuming that it fits resource requirements. - -| `nodeSelector` -| `object (string)` -| NodeSelector is a selector which must be true for the pod to fit on a node. Selector which must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ - -| `overhead` -| `integer-or-string` -| Overhead represents the resource overhead associated with running a pod for a given RuntimeClass. This field will be autopopulated at admission time by the RuntimeClass admission controller. If the RuntimeClass admission controller is enabled, overhead must not be set in Pod create requests. The RuntimeClass admission controller will reject Pod create requests which have the overhead already set. If RuntimeClass is configured and selected in the PodSpec, Overhead will be set to the value defined in the corresponding RuntimeClass, otherwise it will remain unset and treated as zero. More info: https://git.k8s.io/enhancements/keps/sig-node/20190226-pod-overhead.md This field is alpha-level as of Kubernetes v1.16, and is only honored by servers that enable the PodOverhead feature. - -| `preemptionPolicy` -| `string` -| PreemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset. This field is beta-level, gated by the NonPreemptingPriority feature-gate. - -| `priority` -| `integer` -| The priority value. Various system components use this field to find the priority of the pod. When Priority Admission Controller is enabled, it prevents users from setting this field. The admission controller populates this field from PriorityClassName. The higher the value, the higher the priority. - -| `priorityClassName` -| `string` -| If specified, indicates the pod's priority. "system-node-critical" and "system-cluster-critical" are two special keywords which indicate the highest priorities with the former being the highest priority. Any other name must be defined by creating a PriorityClass object with that name. If not specified, the pod priority will be default or zero if there is no default. - -| `readinessGates` -| `array` -| If specified, all readiness gates will be evaluated for pod readiness. A pod is ready when all its containers are ready AND all conditions specified in the readiness gates have status equal to "True" More info: https://git.k8s.io/enhancements/keps/sig-network/0007-pod-ready%2B%2B.md - -| `readinessGates[]` -| `object` -| PodReadinessGate contains the reference to a pod condition - -| `restartPolicy` -| `string` -| Restart policy for all containers within the pod. One of Always, OnFailure, Never. Default to Always. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy - -| `runtimeClassName` -| `string` -| RuntimeClassName refers to a RuntimeClass object in the node.k8s.io group, which should be used to run this pod. If no RuntimeClass resource matches the named class, the pod will not be run. If unset or empty, the "legacy" RuntimeClass will be used, which is an implicit class with an empty definition that uses the default runtime handler. More info: https://git.k8s.io/enhancements/keps/sig-node/runtime-class.md This is a beta feature as of Kubernetes v1.14. - -| `schedulerName` -| `string` -| If specified, the pod will be dispatched by specified scheduler. If not specified, the pod will be dispatched by default scheduler. - -| `securityContext` -| `object` -| SecurityContext holds pod-level security attributes and common container settings. Optional: Defaults to empty. See type description for default values of each field. - -| `serviceAccount` -| `string` -| DeprecatedServiceAccount is a depreciated alias for ServiceAccountName. Deprecated: Use serviceAccountName instead. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the name of the ServiceAccount to use to run this pod. More info: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ - -| `setHostnameAsFQDN` -| `boolean` -| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\Tcpip\\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. - -| `shareProcessNamespace` -| `boolean` -| Share a single process namespace between all of the containers in a pod. When this is set containers will be able to view and signal processes from other containers in the same pod, and the first process in each container will not be assigned PID 1. HostPID and ShareProcessNamespace cannot both be set. Optional: Default to false. - -| `subdomain` -| `string` -| If specified, the fully qualified Pod hostname will be "<hostname>.<subdomain>.<pod namespace>.svc.<cluster domain>". If not specified, the pod will not have a domainname at all. - -| `terminationGracePeriodSeconds` -| `integer` -| Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds. - -| `tolerations` -| `array` -| If specified, the pod's tolerations. - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -| `topologySpreadConstraints` -| `array` -| TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. - -| `topologySpreadConstraints[]` -| `object` -| TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -| `volumes` -| `array` -| List of volumes that can be mounted by containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes - -| `volumes[]` -| `object` -| Volume represents a named volume in a pod that may be accessed by any container in the pod. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity -Description:: - If specified, the pod's scheduling constraints - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeAffinity` -| `object` -| Describes node affinity scheduling rules for the pod. - -| `podAffinity` -| `object` -| Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -| `podAntiAffinity` -| `object` -| Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity -Description:: - Describes node affinity scheduling rules for the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `object` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node matches the corresponding matchExpressions; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - An empty preferred scheduling term matches all objects with implicit weight 0 (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op). - -Type:: - `object` - -Required:: - - `preference` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preference` -| `object` -| A node selector term, associated with the corresponding weight. - -| `weight` -| `integer` -| Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference -Description:: - A node selector term, associated with the corresponding weight. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[].preference.matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to an update), the system may or may not try to eventually evict the pod from its node. - -Type:: - `object` - -Required:: - - `nodeSelectorTerms` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nodeSelectorTerms` -| `array` -| Required. A list of node selector terms. The terms are ORed. - -| `nodeSelectorTerms[]` -| `object` -| A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms -Description:: - Required. A list of node selector terms. The terms are ORed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[] -Description:: - A null or empty node selector term matches no objects. The requirements of them are ANDed. The TopologySelectorTerm type implements a subset of the NodeSelectorTerm. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of node selector requirements by node's labels. - -| `matchExpressions[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchFields` -| `array` -| A list of node selector requirements by node's fields. - -| `matchFields[]` -| `object` -| A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions -Description:: - A list of node selector requirements by node's labels. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchExpressions[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields -Description:: - A list of node selector requirements by node's fields. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.nodeAffinity.requiredDuringSchedulingIgnoredDuringExecution.nodeSelectorTerms[].matchFields[] -Description:: - A node selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The label key that the selector applies to. - -| `operator` -| `string` -| Represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. If the operator is Gt or Lt, the values array must have a single element, which will be interpreted as an integer. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity -Description:: - Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.podAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity -Description:: - Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `preferredDuringSchedulingIgnoredDuringExecution` -| `array` -| The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -| `preferredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -| `requiredDuringSchedulingIgnoredDuringExecution` -| `array` -| If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -| `requiredDuringSchedulingIgnoredDuringExecution[]` -| `object` -| Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution -Description:: - The scheduler will prefer to schedule pods to nodes that satisfy the anti-affinity expressions specified by this field, but it may choose a node that violates one or more of the expressions. The node that is most preferred is the one with the greatest sum of weights, i.e. for each node that meets all of the scheduling requirements (resource request, requiredDuringScheduling anti-affinity expressions, etc.), compute a sum by iterating through the elements of this field and adding "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the node(s) with the highest sum are the most preferred. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[] -Description:: - The weights of all of the matched WeightedPodAffinityTerm fields are added per-node to find the most preferred node(s) - -Type:: - `object` - -Required:: - - `podAffinityTerm` - - `weight` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podAffinityTerm` -| `object` -| Required. A pod affinity term, associated with the corresponding weight. - -| `weight` -| `integer` -| weight associated with matching the corresponding podAffinityTerm, in the range 1-100. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm -Description:: - Required. A pod affinity term, associated with the corresponding weight. - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.preferredDuringSchedulingIgnoredDuringExecution[].podAffinityTerm.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution -Description:: - If the anti-affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the anti-affinity requirements specified by this field cease to be met at some point during pod execution (e.g. due to a pod label update), the system may or may not try to eventually evict the pod from its node. When there are multiple elements, the lists of nodes corresponding to each podAffinityTerm are intersected, i.e. all terms must be satisfied. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[] -Description:: - Defines a set of pods (namely those matching the labelSelector relative to the given namespace(s)) that this pod should be co-located (affinity) or not co-located (anti-affinity) with, where co-located is defined as running on a node whose value of the label with key <topologyKey> matches that of any node on which a pod of the set of pods is running - -Type:: - `object` - -Required:: - - `topologyKey` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| A label query over a set of resources, in this case pods. - -| `namespaces` -| `array (string)` -| namespaces specifies which namespaces the labelSelector applies to (matches against); null or empty list means "this pod's namespace" - -| `topologyKey` -| `string` -| This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching the labelSelector in the specified namespaces, where co-located is defined as running on a node whose value of the label with key topologyKey matches that of any node on which any of the selected pods is running. Empty topologyKey is not allowed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector -Description:: - A label query over a set of resources, in this case pods. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.affinity.podAntiAffinity.requiredDuringSchedulingIgnoredDuringExecution[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers -Description:: - List of containers belonging to the pod. Containers cannot currently be added or removed. There must be at least one container in a Pod. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[] -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| `object` -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| `array` -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| `object` -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| `object` -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| `object` -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle -Description:: - Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].livenessProbe -Description:: - Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].ports -Description:: - List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].readinessProbe -Description:: - Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].resources -Description:: - Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].securityContext -Description:: - Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seccompProfile` -| `object` -| The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].securityContext.seccompProfile -Description:: - The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `localhostProfile` -| `string` -| localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". - -| `type` -| `string` -| type indicates which kind of seccomp profile will be applied. Valid options are: - Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].startupProbe -Description:: - StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.install.spec.deployments[].spec.template.spec.containers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.containers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.install.spec.deployments[].spec.template.spec.dnsConfig -Description:: - Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nameservers` -| `array (string)` -| A list of DNS name server IP addresses. This will be appended to the base nameservers generated from DNSPolicy. Duplicated nameservers will be removed. - -| `options` -| `array` -| A list of DNS resolver options. This will be merged with the base options generated from DNSPolicy. Duplicated entries will be removed. Resolution options given in Options will override those that appear in the base DNSPolicy. - -| `options[]` -| `object` -| PodDNSConfigOption defines DNS resolver options of a pod. - -| `searches` -| `array (string)` -| A list of DNS search domains for host-name lookup. This will be appended to the base search paths generated from DNSPolicy. Duplicated search paths will be removed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.dnsConfig.options -Description:: - A list of DNS resolver options. This will be merged with the base options generated from DNSPolicy. Duplicated entries will be removed. Resolution options given in Options will override those that appear in the base DNSPolicy. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.dnsConfig.options[] -Description:: - PodDNSConfigOption defines DNS resolver options of a pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Required. - -| `value` -| `string` -| - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers -Description:: - List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing pod to perform user-initiated actions such as debugging. This list cannot be specified when creating a pod, and it cannot be modified by updating the pod spec. In order to add an ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource. This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[] -Description:: - An EphemeralContainer is a container that may be added temporarily to an existing pod for user-initiated activities such as debugging. Ephemeral containers have no resource or scheduling guarantees, and they will not be restarted when they exit or when a pod is removed or restarted. If an ephemeral container causes a pod to exceed its resource allocation, the pod may be evicted. Ephemeral containers may not be added by directly updating the pod spec. They must be added via the pod's ephemeralcontainers subresource, and they will appear in the pod spec once added. This is an alpha feature enabled by the EphemeralContainers feature flag. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Lifecycle is not allowed for ephemeral containers. - -| `livenessProbe` -| `object` -| Probes are not allowed for ephemeral containers. - -| `name` -| `string` -| Name of the ephemeral container specified as a DNS_LABEL. This name must be unique among all containers, init containers and ephemeral containers. - -| `ports` -| `array` -| Ports are not allowed for ephemeral containers. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Probes are not allowed for ephemeral containers. - -| `resources` -| `object` -| Resources are not allowed for ephemeral containers. Ephemeral containers use spare resources already allocated to the pod. - -| `securityContext` -| `object` -| SecurityContext is not allowed for ephemeral containers. - -| `startupProbe` -| `object` -| Probes are not allowed for ephemeral containers. - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `targetContainerName` -| `string` -| If set, the name of the container from PodSpec that this ephemeral container targets. The ephemeral container will be run in the namespaces (IPC, PID, etc) of this container. If not set then the ephemeral container is run in whatever namespaces are shared for the pod. Note that the container runtime must support this feature. - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle -Description:: - Lifecycle is not allowed for ephemeral containers. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].livenessProbe -Description:: - Probes are not allowed for ephemeral containers. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].ports -Description:: - Ports are not allowed for ephemeral containers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].readinessProbe -Description:: - Probes are not allowed for ephemeral containers. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].resources -Description:: - Resources are not allowed for ephemeral containers. Ephemeral containers use spare resources already allocated to the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].securityContext -Description:: - SecurityContext is not allowed for ephemeral containers. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seccompProfile` -| `object` -| The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].securityContext.seccompProfile -Description:: - The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `localhostProfile` -| `string` -| localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". - -| `type` -| `string` -| type indicates which kind of seccomp profile will be applied. Valid options are: - Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].startupProbe -Description:: - Probes are not allowed for ephemeral containers. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.ephemeralContainers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.install.spec.deployments[].spec.template.spec.hostAliases -Description:: - HostAliases is an optional list of hosts and IPs that will be injected into the pod's hosts file if specified. This is only valid for non-hostNetwork pods. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.hostAliases[] -Description:: - HostAlias holds the mapping between IP and hostnames that will be injected as an entry in the pod's hosts file. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hostnames` -| `array (string)` -| Hostnames for the above IP address. - -| `ip` -| `string` -| IP address of the host file entry. - -|=== -..spec.install.spec.deployments[].spec.template.spec.imagePullSecrets -Description:: - ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. For example, in the case of docker, only DockerConfig type secrets are honored. More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.imagePullSecrets[] -Description:: - LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers -Description:: - List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. Init containers cannot currently be added or removed. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[] -Description:: - A single application container that you want to run within a pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `command` -| `array (string)` -| Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell - -| `env` -| `array` -| List of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `image` -| `string` -| Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets. - -| `imagePullPolicy` -| `string` -| Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images - -| `lifecycle` -| `object` -| Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -| `livenessProbe` -| `object` -| Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `name` -| `string` -| Name of the container specified as a DNS_LABEL. Each container in a pod must have a unique name (DNS_LABEL). Cannot be updated. - -| `ports` -| `array` -| List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -| `ports[]` -| `object` -| ContainerPort represents a network port in a single container. - -| `readinessProbe` -| `object` -| Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `resources` -| `object` -| Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `securityContext` -| `object` -| Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -| `startupProbe` -| `object` -| StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `stdin` -| `boolean` -| Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. - -| `stdinOnce` -| `boolean` -| Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false - -| `terminationMessagePath` -| `string` -| Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated. - -| `terminationMessagePolicy` -| `string` -| Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the container status message on both success and failure. FallbackToLogsOnError will use the last chunk of container log output if the termination message file is empty and the container exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated. - -| `tty` -| `boolean` -| Whether this container should allocate a TTY for itself, also requires 'stdin' to be true. Default is false. - -| `volumeDevices` -| `array` -| volumeDevices is the list of block devices to be used by the container. - -| `volumeDevices[]` -| `object` -| volumeDevice describes a mapping of a raw block device within a container. - -| `volumeMounts` -| `array` -| Pod volumes to mount into the container's filesystem. Cannot be updated. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `workingDir` -| `string` -| Container's working directory. If not specified, the container runtime's default will be used, which might be configured in the container image. Cannot be updated. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].env -Description:: - List of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].envFrom -Description:: - List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle -Description:: - Actions that the management system should take in response to container lifecycle events. Cannot be updated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `postStart` -| `object` -| PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -| `preStop` -| `object` -| PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.postStart -Description:: - PostStart is called immediately after a container is created. If the handler fails, the container is terminated and restarted according to its restart policy. Other management of the container blocks until the hook completes. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.postStart.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.postStart.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.postStart.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.postStart.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.postStart.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.preStop -Description:: - PreStop is called immediately before a container is terminated due to an API request or management event such as liveness/startup probe failure, preemption, resource contention, etc. The handler is not called if the container crashes or exits. The reason for termination is passed to the handler. The Pod's termination grace period countdown begins before the PreStop hooked is executed. Regardless of the outcome of the handler, the container will eventually terminate within the Pod's termination grace period. Other management of the container blocks until the hook completes or until the termination grace period is reached. More info: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.preStop.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.preStop.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.preStop.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.preStop.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].lifecycle.preStop.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].livenessProbe -Description:: - Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].livenessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].livenessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].livenessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].livenessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].livenessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].ports -Description:: - List of ports to expose from the container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default "0.0.0.0" address inside a container will be accessible from the network. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].ports[] -Description:: - ContainerPort represents a network port in a single container. - -Type:: - `object` - -Required:: - - `containerPort` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerPort` -| `integer` -| Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536. - -| `hostIP` -| `string` -| What host IP to bind the external port to. - -| `hostPort` -| `integer` -| Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536. If HostNetwork is specified, this must match ContainerPort. Most containers do not need this. - -| `name` -| `string` -| If specified, this must be an IANA_SVC_NAME and unique within the pod. Each named port in a pod must have a unique name. Name for the port that can be referred to by services. - -| `protocol` -| `string` -| Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP". - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].readinessProbe -Description:: - Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].readinessProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].readinessProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].readinessProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].readinessProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].readinessProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].resources -Description:: - Compute Resources required by this container. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].securityContext -Description:: - Security options the pod should run with. More info: https://kubernetes.io/docs/concepts/policy/security-context/ More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowPrivilegeEscalation` -| `boolean` -| AllowPrivilegeEscalation controls whether a process can gain more privileges than its parent process. This bool directly controls if the no_new_privs flag will be set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged 2) has CAP_SYS_ADMIN - -| `capabilities` -| `object` -| The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -| `privileged` -| `boolean` -| Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. Defaults to false. - -| `procMount` -| `string` -| procMount denotes the type of proc mount to use for the containers. The default is DefaultProcMount which uses the container runtime defaults for readonly paths and masked paths. This requires the ProcMountType feature flag to be enabled. - -| `readOnlyRootFilesystem` -| `boolean` -| Whether this container has a read-only root filesystem. Default is false. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `seccompProfile` -| `object` -| The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].securityContext.capabilities -Description:: - The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `add` -| `array (string)` -| Added capabilities - -| `drop` -| `array (string)` -| Removed capabilities - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to the container. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].securityContext.seccompProfile -Description:: - The seccomp options to use by this container. If seccomp options are provided at both the pod & container level, the container options override the pod options. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `localhostProfile` -| `string` -| localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". - -| `type` -| `string` -| type indicates which kind of seccomp profile will be applied. Valid options are: - Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options from the PodSecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].startupProbe -Description:: - StartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod's lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `exec` -| `object` -| One and only one of the following should be specified. Exec specifies the action to take. - -| `failureThreshold` -| `integer` -| Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. - -| `httpGet` -| `object` -| HTTPGet specifies the http request to perform. - -| `initialDelaySeconds` -| `integer` -| Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -| `periodSeconds` -| `integer` -| How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. - -| `successThreshold` -| `integer` -| Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. - -| `tcpSocket` -| `object` -| TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -| `timeoutSeconds` -| `integer` -| Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].startupProbe.exec -Description:: - One and only one of the following should be specified. Exec specifies the action to take. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the command line to execute inside the container, the working directory for the command is root ('/') in the container's filesystem. The command is simply exec'd, it is not run inside a shell, so traditional shell instructions ('\|', etc) won't work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].startupProbe.httpGet -Description:: - HTTPGet specifies the http request to perform. - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Host name to connect to, defaults to the pod IP. You probably want to set "Host" in httpHeaders instead. - -| `httpHeaders` -| `array` -| Custom headers to set in the request. HTTP allows repeated headers. - -| `httpHeaders[]` -| `object` -| HTTPHeader describes a custom header to be used in HTTP probes - -| `path` -| `string` -| Path to access on the HTTP server. - -| `port` -| `integer-or-string` -| Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -| `scheme` -| `string` -| Scheme to use for connecting to the host. Defaults to HTTP. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].startupProbe.httpGet.httpHeaders -Description:: - Custom headers to set in the request. HTTP allows repeated headers. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].startupProbe.httpGet.httpHeaders[] -Description:: - HTTPHeader describes a custom header to be used in HTTP probes - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| The header field name - -| `value` -| `string` -| The header field value - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].startupProbe.tcpSocket -Description:: - TCPSocket specifies an action involving a TCP port. TCP hooks not yet supported TODO: implement a realistic TCP lifecycle hook - -Type:: - `object` - -Required:: - - `port` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `host` -| `string` -| Optional: Host name to connect to, defaults to the pod IP. - -| `port` -| `integer-or-string` -| Number or name of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].volumeDevices -Description:: - volumeDevices is the list of block devices to be used by the container. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].volumeDevices[] -Description:: - volumeDevice describes a mapping of a raw block device within a container. - -Type:: - `object` - -Required:: - - `devicePath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `devicePath` -| `string` -| devicePath is the path inside of the container that the device will be mapped to. - -| `name` -| `string` -| name must match the name of a persistentVolumeClaim in the pod - -|=== -..spec.install.spec.deployments[].spec.template.spec.initContainers[].volumeMounts -Description:: - Pod volumes to mount into the container's filesystem. Cannot be updated. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.initContainers[].volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.install.spec.deployments[].spec.template.spec.readinessGates -Description:: - If specified, all readiness gates will be evaluated for pod readiness. A pod is ready when all its containers are ready AND all conditions specified in the readiness gates have status equal to "True" More info: https://git.k8s.io/enhancements/keps/sig-network/0007-pod-ready%2B%2B.md - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.readinessGates[] -Description:: - PodReadinessGate contains the reference to a pod condition - -Type:: - `object` - -Required:: - - `conditionType` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditionType` -| `string` -| ConditionType refers to a condition in the pod's condition list with matching type. - -|=== -..spec.install.spec.deployments[].spec.template.spec.securityContext -Description:: - SecurityContext holds pod-level security attributes and common container settings. Optional: Defaults to empty. See type description for default values of each field. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsGroup` -| `integer` -| A special supplemental group that applies to all containers in a pod. Some volume types allow the Kubelet to change the ownership of that volume to be owned by the pod: - 1. The owning GID will be the FSGroup 2. The setgid bit is set (new files created in the volume will be owned by FSGroup) 3. The permission bits are OR'd with rw-rw---- - If unset, the Kubelet will not modify the ownership and permissions of any volume. - -| `fsGroupChangePolicy` -| `string` -| fsGroupChangePolicy defines behavior of changing ownership and permission of the volume before being exposed inside Pod. This field will only apply to volume types which support fsGroup based ownership(and permissions). It will have no effect on ephemeral volume types such as: secret, configmaps and emptydir. Valid values are "OnRootMismatch" and "Always". If not specified, "Always" is used. - -| `runAsGroup` -| `integer` -| The GID to run the entrypoint of the container process. Uses runtime default if unset. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `runAsNonRoot` -| `boolean` -| Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -| `runAsUser` -| `integer` -| The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `seLinuxOptions` -| `object` -| The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -| `seccompProfile` -| `object` -| The seccomp options to use by the containers in this pod. - -| `supplementalGroups` -| `array (integer)` -| A list of groups applied to the first process run in each container, in addition to the container's primary GID. If unspecified, no groups will be added to any container. - -| `sysctls` -| `array` -| Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -| `sysctls[]` -| `object` -| Sysctl defines a kernel parameter to be set - -| `windowsOptions` -| `object` -| The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.install.spec.deployments[].spec.template.spec.securityContext.seLinuxOptions -Description:: - The SELinux context to be applied to all containers. If unspecified, the container runtime will allocate a random SELinux context for each container. May also be set in SecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence for that container. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `level` -| `string` -| Level is SELinux level label that applies to the container. - -| `role` -| `string` -| Role is a SELinux role label that applies to the container. - -| `type` -| `string` -| Type is a SELinux type label that applies to the container. - -| `user` -| `string` -| User is a SELinux user label that applies to the container. - -|=== -..spec.install.spec.deployments[].spec.template.spec.securityContext.seccompProfile -Description:: - The seccomp options to use by the containers in this pod. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `localhostProfile` -| `string` -| localhostProfile indicates a profile defined in a file on the node should be used. The profile must be preconfigured on the node to work. Must be a descending path, relative to the kubelet's configured seccomp profile location. Must only be set if type is "Localhost". - -| `type` -| `string` -| type indicates which kind of seccomp profile will be applied. Valid options are: - Localhost - a profile defined in a file on the node should be used. RuntimeDefault - the container runtime default profile should be used. Unconfined - no profile should be applied. - -|=== -..spec.install.spec.deployments[].spec.template.spec.securityContext.sysctls -Description:: - Sysctls hold a list of namespaced sysctls used for the pod. Pods with unsupported sysctls (by the container runtime) might fail to launch. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.securityContext.sysctls[] -Description:: - Sysctl defines a kernel parameter to be set - -Type:: - `object` - -Required:: - - `name` - - `value` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of a property to set - -| `value` -| `string` -| Value of a property to set - -|=== -..spec.install.spec.deployments[].spec.template.spec.securityContext.windowsOptions -Description:: - The Windows specific settings applied to all containers. If unspecified, the options within a container's SecurityContext will be used. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `gmsaCredentialSpec` -| `string` -| GMSACredentialSpec is where the GMSA admission webhook (https://github.com/kubernetes-sigs/windows-gmsa) inlines the contents of the GMSA credential spec named by the GMSACredentialSpecName field. - -| `gmsaCredentialSpecName` -| `string` -| GMSACredentialSpecName is the name of the GMSA credential spec to use. - -| `runAsUserName` -| `string` -| The UserName in Windows to run the entrypoint of the container process. Defaults to the user specified in image metadata if unspecified. May also be set in PodSecurityContext. If set in both SecurityContext and PodSecurityContext, the value specified in SecurityContext takes precedence. - -|=== -..spec.install.spec.deployments[].spec.template.spec.tolerations -Description:: - If specified, the pod's tolerations. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== -..spec.install.spec.deployments[].spec.template.spec.topologySpreadConstraints -Description:: - TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.topologySpreadConstraints[] -Description:: - TopologySpreadConstraint specifies how to spread matching pods among the given topology. - -Type:: - `object` - -Required:: - - `maxSkew` - - `topologyKey` - - `whenUnsatisfiable` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -| `maxSkew` -| `integer` -| MaxSkew describes the degree to which pods may be unevenly distributed. When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference between the number of matching pods in the target topology and the global minimum. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 1/1/0: \| zone1 \| zone2 \| zone3 \| \| P \| P \| \| - if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 1/1/1; scheduling it onto zone1(zone2) would make the ActualSkew(2-0) on zone1(zone2) violate MaxSkew(1). - if MaxSkew is 2, incoming pod can be scheduled onto any zone. When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence to topologies that satisfy it. It's a required field. Default value is 1 and 0 is not allowed. - -| `topologyKey` -| `string` -| TopologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. We consider each <key, value> as a "bucket", and try to put balanced number of pods into each bucket. It's a required field. - -| `whenUnsatisfiable` -| `string` -| WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy the spread constraint. - DoNotSchedule (default) tells the scheduler not to schedule it. - ScheduleAnyway tells the scheduler to schedule the pod in any location, but giving higher precedence to topologies that would help reduce the skew. A constraint is considered "Unsatisfiable" for an incoming pod if and only if every possible node assigment for that pod would violate "MaxSkew" on some topology. For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same labelSelector spread as 3/1/1: \| zone1 \| zone2 \| zone3 \| \| P P P \| P \| P \| If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler won't make it *more* imbalanced. It's a required field. - -|=== -..spec.install.spec.deployments[].spec.template.spec.topologySpreadConstraints[].labelSelector -Description:: - LabelSelector is used to find matching pods. Pods that match this label selector are counted to determine the number of pods in their corresponding topology domain. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.topologySpreadConstraints[].labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.topologySpreadConstraints[].labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes -Description:: - List of volumes that can be mounted by containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[] -Description:: - Volume represents a named volume in a pod that may be accessed by any container in the pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `awsElasticBlockStore` -| `object` -| AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `azureDisk` -| `object` -| AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -| `azureFile` -| `object` -| AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -| `cephfs` -| `object` -| CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -| `cinder` -| `object` -| Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `configMap` -| `object` -| ConfigMap represents a configMap that should populate this volume - -| `csi` -| `object` -| CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). - -| `downwardAPI` -| `object` -| DownwardAPI represents downward API about the pod that should populate this volume - -| `emptyDir` -| `object` -| EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `ephemeral` -| `object` -| Ephemeral represents a volume that is handled by a cluster storage driver (Alpha feature). The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts, and deleted when the pod is removed. - Use this if: a) the volume is only needed while the pod runs, b) features of normal volumes like restoring from snapshot or capacity tracking are needed, c) the storage driver is specified through a storage class, and d) the storage driver supports dynamic volume provisioning through a PersistentVolumeClaim (see EphemeralVolumeSource for more information on the connection between this volume type and PersistentVolumeClaim). - Use PersistentVolumeClaim or one of the vendor-specific APIs for volumes that persist for longer than the lifecycle of an individual pod. - Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to be used that way - see the documentation of the driver for more information. - A pod can use both types of ephemeral volumes and persistent volumes at the same time. - -| `fc` -| `object` -| FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -| `flexVolume` -| `object` -| FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -| `flocker` -| `object` -| Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -| `gcePersistentDisk` -| `object` -| GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `gitRepo` -| `object` -| GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -| `glusterfs` -| `object` -| Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -| `hostPath` -| `object` -| HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -| `iscsi` -| `object` -| ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -| `name` -| `string` -| Volume's name. Must be a DNS_LABEL and unique within the pod. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `nfs` -| `object` -| NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `persistentVolumeClaim` -| `object` -| PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `photonPersistentDisk` -| `object` -| PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -| `portworxVolume` -| `object` -| PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -| `projected` -| `object` -| Items for all in one resources secrets, configmaps, and downward API - -| `quobyte` -| `object` -| Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -| `rbd` -| `object` -| RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -| `scaleIO` -| `object` -| ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -| `secret` -| `object` -| Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -| `storageos` -| `object` -| StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -| `vsphereVolume` -| `object` -| VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].awsElasticBlockStore -Description:: - AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). - -| `readOnly` -| `boolean` -| Specify "true" to force and set the ReadOnly property in VolumeMounts to "true". If omitted, the default is "false". More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `volumeID` -| `string` -| Unique ID of the persistent disk resource in AWS (Amazon EBS volume). More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].azureDisk -Description:: - AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `diskName` - - `diskURI` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cachingMode` -| `string` -| Host Caching mode: None, Read Only, Read Write. - -| `diskName` -| `string` -| The Name of the data disk in the blob storage - -| `diskURI` -| `string` -| The URI the data disk in the blob storage - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `kind` -| `string` -| Expected values Shared: multiple blob disks per storage account Dedicated: single blob disk per storage account Managed: azure managed data disk (only in managed availability set). defaults to shared - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].azureFile -Description:: - AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `secretName` - - `shareName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretName` -| `string` -| the name of secret that contains Azure Storage Account Name and Key - -| `shareName` -| `string` -| Share Name - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].cephfs -Description:: - CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `monitors` -| `array (string)` -| Required: Monitors is a collection of Ceph monitors More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `path` -| `string` -| Optional: Used as the mounted root, rather than the full Ceph tree, default is / - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretFile` -| `string` -| Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `user` -| `string` -| Optional: User is the rados user name, default is admin More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].cephfs.secretRef -Description:: - Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].cinder -Description:: - Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `secretRef` -| `object` -| Optional: points to a secret object containing parameters used to connect to OpenStack. - -| `volumeID` -| `string` -| volume id used to identify the volume in cinder. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].cinder.secretRef -Description:: - Optional: points to a secret object containing parameters used to connect to OpenStack. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].configMap -Description:: - ConfigMap represents a configMap that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].csi -Description:: - CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the CSI driver that handles this volume. Consult with your admin for the correct name as registered in the cluster. - -| `fsType` -| `string` -| Filesystem type to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. - -| `nodePublishSecretRef` -| `object` -| NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeAttributes` -| `object (string)` -| VolumeAttributes stores driver-specific properties that are passed to the CSI driver. Consult your driver's documentation for supported values. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].csi.nodePublishSecretRef -Description:: - NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].downwardAPI -Description:: - DownwardAPI represents downward API about the pod that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| Items is a list of downward API volume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].downwardAPI.items -Description:: - Items is a list of downward API volume file - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file, must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].emptyDir -Description:: - EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| `integer-or-string` -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral -Description:: - Ephemeral represents a volume that is handled by a cluster storage driver (Alpha feature). The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts, and deleted when the pod is removed. - Use this if: a) the volume is only needed while the pod runs, b) features of normal volumes like restoring from snapshot or capacity tracking are needed, c) the storage driver is specified through a storage class, and d) the storage driver supports dynamic volume provisioning through a PersistentVolumeClaim (see EphemeralVolumeSource for more information on the connection between this volume type and PersistentVolumeClaim). - Use PersistentVolumeClaim or one of the vendor-specific APIs for volumes that persist for longer than the lifecycle of an individual pod. - Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to be used that way - see the documentation of the driver for more information. - A pod can use both types of ephemeral volumes and persistent volumes at the same time. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeClaimTemplate` -| `object` -| Will be used to create a stand-alone PVC to provision the volume. The pod in which this EphemeralVolumeSource is embedded will be the owner of the PVC, i.e. the PVC will be deleted together with the pod. The name of the PVC will be `<pod name>-<volume name>` where `<volume name>` is the name from the `PodSpec.Volumes` array entry. Pod validation will reject the pod if the concatenated name is not valid for a PVC (for example, too long). - An existing PVC with that name that is not owned by the pod will *not* be used for the pod to avoid using an unrelated volume by mistake. Starting the pod is then blocked until the unrelated PVC is removed. If such a pre-created PVC is meant to be used by the pod, the PVC has to updated with an owner reference to the pod once the pod exists. Normally this should not be necessary, but it may be useful when manually reconstructing a broken cluster. - This field is read-only and no changes will be made by Kubernetes to the PVC after it has been created. - Required, must not be nil. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral.volumeClaimTemplate -Description:: - Will be used to create a stand-alone PVC to provision the volume. The pod in which this EphemeralVolumeSource is embedded will be the owner of the PVC, i.e. the PVC will be deleted together with the pod. The name of the PVC will be `<pod name>-<volume name>` where `<volume name>` is the name from the `PodSpec.Volumes` array entry. Pod validation will reject the pod if the concatenated name is not valid for a PVC (for example, too long). - An existing PVC with that name that is not owned by the pod will *not* be used for the pod to avoid using an unrelated volume by mistake. Starting the pod is then blocked until the unrelated PVC is removed. If such a pre-created PVC is meant to be used by the pod, the PVC has to updated with an owner reference to the pod once the pod exists. Normally this should not be necessary, but it may be useful when manually reconstructing a broken cluster. - This field is read-only and no changes will be made by Kubernetes to the PVC after it has been created. - Required, must not be nil. - -Type:: - `object` - -Required:: - - `spec` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| `object` -| May contain labels and annotations that will be copied into the PVC when creating it. No other fields are allowed and will be rejected during validation. - -| `spec` -| `object` -| The specification for the PersistentVolumeClaim. The entire content is copied unchanged into the PVC that gets created from this template. The same fields as in a PersistentVolumeClaim are also valid here. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral.volumeClaimTemplate.metadata -Description:: - May contain labels and annotations that will be copied into the PVC when creating it. No other fields are allowed and will be rejected during validation. - -Type:: - `object` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral.volumeClaimTemplate.spec -Description:: - The specification for the PersistentVolumeClaim. The entire content is copied unchanged into the PVC that gets created from this template. The same fields as in a PersistentVolumeClaim are also valid here. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `dataSource` -| `object` -| This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) * An existing PVC (PersistentVolumeClaim) * An existing custom resource that implements data population (Alpha) In order to use custom resource types that implement data population, the AnyVolumeDataSource feature gate must be enabled. If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. - -| `resources` -| `object` -| Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -| `selector` -| `object` -| A label query over volumes to consider for binding. - -| `storageClassName` -| `string` -| Name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 - -| `volumeMode` -| `string` -| volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. - -| `volumeName` -| `string` -| VolumeName is the binding reference to the PersistentVolume backing this claim. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral.volumeClaimTemplate.spec.dataSource -Description:: - This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) * An existing PVC (PersistentVolumeClaim) * An existing custom resource that implements data population (Alpha) In order to use custom resource types that implement data population, the AnyVolumeDataSource feature gate must be enabled. If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required. - -| `kind` -| `string` -| Kind is the type of resource being referenced - -| `name` -| `string` -| Name is the name of resource being referenced - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral.volumeClaimTemplate.spec.resources -Description:: - Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral.volumeClaimTemplate.spec.selector -Description:: - A label query over volumes to consider for binding. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral.volumeClaimTemplate.spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].ephemeral.volumeClaimTemplate.spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].fc -Description:: - FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. TODO: how do we prevent errors in the filesystem from compromising the machine - -| `lun` -| `integer` -| Optional: FC target lun number - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `targetWWNs` -| `array (string)` -| Optional: FC target worldwide names (WWNs) - -| `wwids` -| `array (string)` -| Optional: FC volume world wide identifiers (wwids) Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].flexVolume -Description:: - FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the driver to use for this volume. - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script. - -| `options` -| `object (string)` -| Optional: Extra command options if any. - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].flexVolume.secretRef -Description:: - Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].flocker -Description:: - Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `datasetName` -| `string` -| Name of the dataset stored as metadata -> name on the dataset for Flocker should be considered as deprecated - -| `datasetUUID` -| `string` -| UUID of the dataset. This is unique identifier of a Flocker dataset - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].gcePersistentDisk -Description:: - GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -Type:: - `object` - -Required:: - - `pdName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `pdName` -| `string` -| Unique name of the PD resource in GCE. Used to identify the disk in GCE. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].gitRepo -Description:: - GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -Type:: - `object` - -Required:: - - `repository` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `directory` -| `string` -| Target directory name. Must not contain or start with '..'. If '.' is supplied, the volume directory will be the git repository. Otherwise, if specified, the volume will contain the git repository in the subdirectory with the given name. - -| `repository` -| `string` -| Repository URL - -| `revision` -| `string` -| Commit hash for the specified revision. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].glusterfs -Description:: - Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -Type:: - `object` - -Required:: - - `endpoints` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `endpoints` -| `string` -| EndpointsName is the endpoint name that details Glusterfs topology. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `path` -| `string` -| Path is the Glusterfs volume path. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `readOnly` -| `boolean` -| ReadOnly here will force the Glusterfs volume to be mounted with read-only permissions. Defaults to false. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].hostPath -Description:: - HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path of the directory on the host. If the path is a symlink, it will follow the link to the real path. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `type` -| `string` -| Type for HostPath Volume Defaults to "" More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].iscsi -Description:: - ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -Type:: - `object` - -Required:: - - `iqn` - - `lun` - - `targetPortal` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `chapAuthDiscovery` -| `boolean` -| whether support iSCSI Discovery CHAP authentication - -| `chapAuthSession` -| `boolean` -| whether support iSCSI Session CHAP authentication - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi TODO: how do we prevent errors in the filesystem from compromising the machine - -| `initiatorName` -| `string` -| Custom iSCSI Initiator Name. If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface <target portal>:<volume name> will be created for the connection. - -| `iqn` -| `string` -| Target iSCSI Qualified Name. - -| `iscsiInterface` -| `string` -| iSCSI Interface Name that uses an iSCSI transport. Defaults to 'default' (tcp). - -| `lun` -| `integer` -| iSCSI Target Lun number. - -| `portals` -| `array (string)` -| iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. - -| `secretRef` -| `object` -| CHAP Secret for iSCSI target and initiator authentication - -| `targetPortal` -| `string` -| iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].iscsi.secretRef -Description:: - CHAP Secret for iSCSI target and initiator authentication - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].nfs -Description:: - NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -Type:: - `object` - -Required:: - - `path` - - `server` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path that is exported by the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `readOnly` -| `boolean` -| ReadOnly here will force the NFS export to be mounted with read-only permissions. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `server` -| `string` -| Server is the hostname or IP address of the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].persistentVolumeClaim -Description:: - PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - -Required:: - - `claimName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `claimName` -| `string` -| ClaimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `readOnly` -| `boolean` -| Will force the ReadOnly setting in VolumeMounts. Default false. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].photonPersistentDisk -Description:: - PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `pdID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `pdID` -| `string` -| ID that identifies Photon Controller persistent disk - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].portworxVolume -Description:: - PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| FSType represents the filesystem type to mount Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `volumeID` -| `string` -| VolumeID uniquely identifies a Portworx volume - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected -Description:: - Items for all in one resources secrets, configmaps, and downward API - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `sources` -| `array` -| list of volume projections - -| `sources[]` -| `object` -| Projection that may be projected along with other supported volume types - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources -Description:: - list of volume projections - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[] -Description:: - Projection that may be projected along with other supported volume types - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| information about the configMap data to project - -| `downwardAPI` -| `object` -| information about the downwardAPI data to project - -| `secret` -| `object` -| information about the secret data to project - -| `serviceAccountToken` -| `object` -| information about the serviceAccountToken data to project - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].configMap -Description:: - information about the configMap data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].downwardAPI -Description:: - information about the downwardAPI data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| Items is a list of DownwardAPIVolume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].downwardAPI.items -Description:: - Items is a list of DownwardAPIVolume file - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file, must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].secret -Description:: - information about the secret data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].projected.sources[].serviceAccountToken -Description:: - information about the serviceAccountToken data to project - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audience` -| `string` -| Audience is the intended audience of the token. A recipient of a token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. The audience defaults to the identifier of the apiserver. - -| `expirationSeconds` -| `integer` -| ExpirationSeconds is the requested duration of validity of the service account token. As the token approaches expiration, the kubelet volume plugin will proactively rotate the service account token. The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.Defaults to 1 hour and must be at least 10 minutes. - -| `path` -| `string` -| Path is the path relative to the mount point of the file to project the token into. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].quobyte -Description:: - Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `registry` - - `volume` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group to map volume access to Default is no group - -| `readOnly` -| `boolean` -| ReadOnly here will force the Quobyte volume to be mounted with read-only permissions. Defaults to false. - -| `registry` -| `string` -| Registry represents a single or multiple Quobyte Registry services specified as a string as host:port pair (multiple entries are separated with commas) which acts as the central registry for volumes - -| `tenant` -| `string` -| Tenant owning the given Quobyte volume in the Backend Used with dynamically provisioned Quobyte volumes, value is set by the plugin - -| `user` -| `string` -| User to map volume access to Defaults to serivceaccount user - -| `volume` -| `string` -| Volume is a string that references an already created Quobyte volume by name. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].rbd -Description:: - RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -Type:: - `object` - -Required:: - - `image` - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd TODO: how do we prevent errors in the filesystem from compromising the machine - -| `image` -| `string` -| The rados image name. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `keyring` -| `string` -| Keyring is the path to key ring for RBDUser. Default is /etc/ceph/keyring. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `monitors` -| `array (string)` -| A collection of Ceph monitors. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `pool` -| `string` -| The rados pool name. Default is rbd. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `secretRef` -| `object` -| SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `user` -| `string` -| The rados user name. Default is admin. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].rbd.secretRef -Description:: - SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].scaleIO -Description:: - ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - -Required:: - - `gateway` - - `secretRef` - - `system` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Default is "xfs". - -| `gateway` -| `string` -| The host address of the ScaleIO API Gateway. - -| `protectionDomain` -| `string` -| The name of the ScaleIO Protection Domain for the configured storage. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -| `sslEnabled` -| `boolean` -| Flag to enable/disable SSL communication with Gateway, default false - -| `storageMode` -| `string` -| Indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned. Default is ThinProvisioned. - -| `storagePool` -| `string` -| The ScaleIO Storage Pool associated with the protection domain. - -| `system` -| `string` -| The name of the storage system as configured in ScaleIO. - -| `volumeName` -| `string` -| The name of a volume already created in the ScaleIO system that is associated with this volume source. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].scaleIO.secretRef -Description:: - SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].secret -Description:: - Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `optional` -| `boolean` -| Specify whether the Secret or its keys must be defined - -| `secretName` -| `string` -| Name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.install.spec.deployments[].spec.template.spec.volumes[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].storageos -Description:: - StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -| `volumeName` -| `string` -| VolumeName is the human-readable name of the StorageOS volume. Volume names are only unique within a namespace. - -| `volumeNamespace` -| `string` -| VolumeNamespace specifies the scope of the volume within StorageOS. If no namespace is specified then the Pod's namespace will be used. This allows the Kubernetes name scoping to be mirrored within StorageOS for tighter integration. Set VolumeName to any name to override the default behaviour. Set to "default" if you are not using namespaces within StorageOS. Namespaces that do not pre-exist within StorageOS will be created. - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].storageos.secretRef -Description:: - SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.install.spec.deployments[].spec.template.spec.volumes[].vsphereVolume -Description:: - VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumePath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `storagePolicyID` -| `string` -| Storage Policy Based Management (SPBM) profile ID associated with the StoragePolicyName. - -| `storagePolicyName` -| `string` -| Storage Policy Based Management (SPBM) profile name. - -| `volumePath` -| `string` -| Path that identifies vSphere volume vmdk - -|=== -..spec.install.spec.permissions -Description:: - - -Type:: - `array` - - - - -..spec.install.spec.permissions[] -Description:: - StrategyDeploymentPermissions describe the rbac rules and service account needed by the install strategy - -Type:: - `object` - -Required:: - - `rules` - - `serviceAccountName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `rules` -| `array` -| - -| `rules[]` -| `object` -| PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -| `serviceAccountName` -| `string` -| - -|=== -..spec.install.spec.permissions[].rules -Description:: - - -Type:: - `array` - - - - -..spec.install.spec.permissions[].rules[] -Description:: - PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -Type:: - `object` - -Required:: - - `verbs` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against one of the enumerated resources in any API group will be allowed. - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path Since non-resource URLs are not namespaced, this field is only applicable for ClusterRoles referenced from a ClusterRoleBinding. Rules can either apply to API resources (such as "pods" or "secrets") or non-resource URL paths (such as "/api"), but not both. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. ResourceAll represents all resources. - -| `verbs` -| `array (string)` -| Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule. VerbAll represents all kinds. - -|=== -..spec.installModes -Description:: - InstallModes specify supported installation types - -Type:: - `array` - - - - -..spec.installModes[] -Description:: - InstallMode associates an InstallModeType with a flag representing if the CSV supports it - -Type:: - `object` - -Required:: - - `supported` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `supported` -| `boolean` -| - -| `type` -| `string` -| InstallModeType is a supported type of install mode for CSV installation - -|=== -..spec.links -Description:: - - -Type:: - `array` - - - - -..spec.links[] -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| - -| `url` -| `string` -| - -|=== -..spec.maintainers -Description:: - - -Type:: - `array` - - - - -..spec.maintainers[] -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| - -| `name` -| `string` -| - -|=== -..spec.nativeAPIs -Description:: - - -Type:: - `array` - - - - -..spec.nativeAPIs[] -Description:: - GroupVersionKind unambiguously identifies a kind. It doesn't anonymously include GroupVersion to avoid automatic coersion. It doesn't use a GroupVersion to avoid custom marshalling - -Type:: - `object` - -Required:: - - `group` - - `kind` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `version` -| `string` -| - -|=== -..spec.provider -Description:: - - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| - -| `url` -| `string` -| - -|=== -..spec.selector -Description:: - Label selector for related resources. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.webhookdefinitions -Description:: - - -Type:: - `array` - - - - -..spec.webhookdefinitions[] -Description:: - WebhookDescription provides details to OLM about required webhooks - -Type:: - `object` - -Required:: - - `admissionReviewVersions` - - `generateName` - - `sideEffects` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `admissionReviewVersions` -| `array (string)` -| - -| `containerPort` -| `integer` -| - -| `conversionCRDs` -| `array (string)` -| - -| `deploymentName` -| `string` -| - -| `failurePolicy` -| `string` -| - -| `generateName` -| `string` -| - -| `matchPolicy` -| `string` -| MatchPolicyType specifies the type of match policy - -| `objectSelector` -| `object` -| A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. - -| `reinvocationPolicy` -| `string` -| ReinvocationPolicyType specifies what type of policy the admission hook uses. - -| `rules` -| `array` -| - -| `rules[]` -| `object` -| RuleWithOperations is a tuple of Operations and Resources. It is recommended to make sure that all the tuple expansions are valid. - -| `sideEffects` -| `string` -| - -| `targetPort` -| `integer-or-string` -| - -| `timeoutSeconds` -| `integer` -| - -| `type` -| `string` -| WebhookAdmissionType is the type of admission webhooks supported by OLM - -| `webhookPath` -| `string` -| - -|=== -..spec.webhookdefinitions[].objectSelector -Description:: - A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.webhookdefinitions[].objectSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.webhookdefinitions[].objectSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.webhookdefinitions[].rules -Description:: - - -Type:: - `array` - - - - -..spec.webhookdefinitions[].rules[] -Description:: - RuleWithOperations is a tuple of Operations and Resources. It is recommended to make sure that all the tuple expansions are valid. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the API groups the resources belong to. '*' is all groups. If '*' is present, the length of the slice must be one. Required. - -| `apiVersions` -| `array (string)` -| APIVersions is the API versions the resources belong to. '*' is all versions. If '*' is present, the length of the slice must be one. Required. - -| `operations` -| `array (string)` -| Operations is the operations the admission hook cares about - CREATE, UPDATE, DELETE, CONNECT or * for all of those operations and any future admission operations that are added. If '*' is present, the length of the slice must be one. Required. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. - For example: 'pods' means pods. 'pods/log' means the log subresource of pods. '*' means all resources, but not subresources. 'pods/*' means all subresources of pods. '*/scale' means all scale subresources. '*/*' means all resources and their subresources. - If wildcard is present, the validation rule will ensure resources do not overlap with each other. - Depending on the enclosing object, subresources might not be allowed. Required. - -| `scope` -| `string` -| scope specifies the scope of this rule. Valid values are "Cluster", "Namespaced", and "*" "Cluster" means that only cluster-scoped resources will match this rule. Namespace API objects are cluster-scoped. "Namespaced" means that only namespaced resources will match this rule. "*" means that there are no scope restrictions. Subresources match the scope of their parent resource. Default is "*". - -|=== -..status -Description:: - ClusterServiceVersionStatus represents information about the status of a pod. Status may trail the actual state of a system. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `certsLastUpdated` -| `string` -| Last time the owned APIService certs were updated - -| `certsRotateAt` -| `string` -| Time the owned APIService certs will rotate next - -| `conditions` -| `array` -| List of conditions, a history of state transitions - -| `conditions[]` -| `object` -| Conditions appear in the status as a record of state transitions on the ClusterServiceVersion - -| `lastTransitionTime` -| `string` -| Last time the status transitioned from one status to another. - -| `lastUpdateTime` -| `string` -| Last time we updated the status - -| `message` -| `string` -| A human readable message indicating details about why the ClusterServiceVersion is in this condition. - -| `phase` -| `string` -| Current condition of the ClusterServiceVersion - -| `reason` -| `string` -| A brief CamelCase message indicating details about why the ClusterServiceVersion is in this state. e.g. 'RequirementsNotMet' - -| `requirementStatus` -| `array` -| The status of each requirement for this CSV - -| `requirementStatus[]` -| `object` -| - -|=== -..status.conditions -Description:: - List of conditions, a history of state transitions - -Type:: - `array` - - - - -..status.conditions[] -Description:: - Conditions appear in the status as a record of state transitions on the ClusterServiceVersion - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| Last time the status transitioned from one status to another. - -| `lastUpdateTime` -| `string` -| Last time we updated the status - -| `message` -| `string` -| A human readable message indicating details about why the ClusterServiceVersion is in this condition. - -| `phase` -| `string` -| Condition of the ClusterServiceVersion - -| `reason` -| `string` -| A brief CamelCase message indicating details about why the ClusterServiceVersion is in this state. e.g. 'RequirementsNotMet' - -|=== -..status.requirementStatus -Description:: - The status of each requirement for this CSV - -Type:: - `array` - - - - -..status.requirementStatus[] -Description:: - - -Type:: - `object` - -Required:: - - `group` - - `kind` - - `message` - - `name` - - `status` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `dependents` -| `array` -| - -| `dependents[]` -| `object` -| DependentStatus is the status for a dependent requirement (to prevent infinite nesting) - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `message` -| `string` -| - -| `name` -| `string` -| - -| `status` -| `string` -| StatusReason is a camelcased reason for the status of a RequirementStatus or DependentStatus - -| `uuid` -| `string` -| - -| `version` -| `string` -| - -|=== -..status.requirementStatus[].dependents -Description:: - - -Type:: - `array` - - - - -..status.requirementStatus[].dependents[] -Description:: - DependentStatus is the status for a dependent requirement (to prevent infinite nesting) - -Type:: - `object` - -Required:: - - `group` - - `kind` - - `status` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `message` -| `string` -| - -| `status` -| `string` -| StatusReason is a camelcased reason for the status of a RequirementStatus or DependentStatus - -| `uuid` -| `string` -| - -| `version` -| `string` -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operators.coreos.com/v1alpha1/clusterserviceversions` -- `GET`: list objects of kind ClusterServiceVersion -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/clusterserviceversions` -- `DELETE`: delete collection of ClusterServiceVersion -- `GET`: list objects of kind ClusterServiceVersion -- `POST`: create a ClusterServiceVersion -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/clusterserviceversions/{name}` -- `DELETE`: delete a ClusterServiceVersion -- `GET`: read the specified ClusterServiceVersion -- `PATCH`: partially update the specified ClusterServiceVersion -- `PUT`: replace the specified ClusterServiceVersion -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/clusterserviceversions/{name}/status` -- `GET`: read status of the specified ClusterServiceVersion -- `PATCH`: partially update status of the specified ClusterServiceVersion -- `PUT`: replace status of the specified ClusterServiceVersion - - -=== /apis/operators.coreos.com/v1alpha1/clusterserviceversions - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterServiceVersion - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterserviceversionlist-operators-coreos-com-v1alpha1[`ClusterServiceVersionList operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/clusterserviceversions - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterserviceversionlist-operators-coreos-com-v1alpha1[`ClusterServiceVersionList operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 202 - Accepted -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/clusterserviceversions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterServiceVersion -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/clusterserviceversions/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterServiceVersion -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ClusterServiceVersion - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/clusterserviceversion-operators-coreos-com-v1alpha1.adoc#clusterserviceversion-operators-coreos-com-v1alpha1[`ClusterServiceVersion operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc b/rest_api/operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc deleted file mode 100644 index 317791e8defd..000000000000 --- a/rest_api/operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc +++ /dev/null @@ -1,1058 +0,0 @@ -[id="installplan-operators-coreos-com-v1alpha1"] -= InstallPlan [operators.coreos.com/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - InstallPlan defines the installation of a set of operators. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| InstallPlanSpec defines a set of Application resources to be installed - -| `status` -| `object` -| InstallPlanStatus represents the information about the status of steps required to complete installation. - Status may trail the actual state of a system. - -|=== -..spec -Description:: - InstallPlanSpec defines a set of Application resources to be installed - -Type:: - `object` - -Required:: - - `approval` - - `approved` - - `clusterServiceVersionNames` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `approval` -| `string` -| Approval is the user approval policy for an InstallPlan. It must be one of "Automatic" or "Manual". - -| `approved` -| `boolean` -| - -| `clusterServiceVersionNames` -| `array (string)` -| - -| `generation` -| `integer` -| - -| `source` -| `string` -| - -| `sourceNamespace` -| `string` -| - -|=== -..status -Description:: - InstallPlanStatus represents the information about the status of steps required to complete installation. - Status may trail the actual state of a system. - -Type:: - `object` - -Required:: - - `catalogSources` - - `phase` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `attenuatedServiceAccountRef` -| `object` -| AttenuatedServiceAccountRef references the service account that is used to do scoped operator install. - -| `bundleLookups` -| `array` -| BundleLookups is the set of in-progress requests to pull and unpackage bundle content to the cluster. - -| `bundleLookups[]` -| `object` -| BundleLookup is a request to pull and unpackage the content of a bundle to the cluster. - -| `catalogSources` -| `array (string)` -| - -| `conditions` -| `array` -| - -| `conditions[]` -| `object` -| InstallPlanCondition represents the overall status of the execution of an InstallPlan. - -| `phase` -| `string` -| InstallPlanPhase is the current status of a InstallPlan as a whole. - -| `plan` -| `array` -| - -| `plan[]` -| `object` -| Step represents the status of an individual step in an InstallPlan. - -|=== -..status.attenuatedServiceAccountRef -Description:: - AttenuatedServiceAccountRef references the service account that is used to do scoped operator install. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status.bundleLookups -Description:: - BundleLookups is the set of in-progress requests to pull and unpackage bundle content to the cluster. - -Type:: - `array` - - - - -..status.bundleLookups[] -Description:: - BundleLookup is a request to pull and unpackage the content of a bundle to the cluster. - -Type:: - `object` - -Required:: - - `catalogSourceRef` - - `identifier` - - `path` - - `replaces` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `catalogSourceRef` -| `object` -| CatalogSourceRef is a reference to the CatalogSource the bundle path was resolved from. - -| `conditions` -| `array` -| Conditions represents the overall state of a BundleLookup. - -| `conditions[]` -| `object` -| - -| `identifier` -| `string` -| Identifier is the catalog-unique name of the operator (the name of the CSV for bundles that contain CSVs) - -| `path` -| `string` -| Path refers to the location of a bundle to pull. It's typically an image reference. - -| `properties` -| `string` -| The effective properties of the unpacked bundle. - -| `replaces` -| `string` -| Replaces is the name of the bundle to replace with the one found at Path. - -|=== -..status.bundleLookups[].catalogSourceRef -Description:: - CatalogSourceRef is a reference to the CatalogSource the bundle path was resolved from. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status.bundleLookups[].conditions -Description:: - Conditions represents the overall state of a BundleLookup. - -Type:: - `array` - - - - -..status.bundleLookups[].conditions[] -Description:: - - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| Last time the condition transitioned from one status to another. - -| `lastUpdateTime` -| `string` -| Last time the condition was probed. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of condition. - -|=== -..status.conditions -Description:: - - -Type:: - `array` - - - - -..status.conditions[] -Description:: - InstallPlanCondition represents the overall status of the execution of an InstallPlan. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `lastUpdateTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| ConditionReason is a camelcased reason for the state transition. - -| `status` -| `string` -| - -| `type` -| `string` -| InstallPlanConditionType describes the state of an InstallPlan at a certain point as a whole. - -|=== -..status.plan -Description:: - - -Type:: - `array` - - - - -..status.plan[] -Description:: - Step represents the status of an individual step in an InstallPlan. - -Type:: - `object` - -Required:: - - `resolving` - - `resource` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `resolving` -| `string` -| - -| `resource` -| `object` -| StepResource represents the status of a resource to be tracked by an InstallPlan. - -| `status` -| `string` -| StepStatus is the current status of a particular resource an in InstallPlan - -|=== -..status.plan[].resource -Description:: - StepResource represents the status of a resource to be tracked by an InstallPlan. - -Type:: - `object` - -Required:: - - `group` - - `kind` - - `name` - - `sourceName` - - `sourceNamespace` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `manifest` -| `string` -| - -| `name` -| `string` -| - -| `sourceName` -| `string` -| - -| `sourceNamespace` -| `string` -| - -| `version` -| `string` -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operators.coreos.com/v1alpha1/installplans` -- `GET`: list objects of kind InstallPlan -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/installplans` -- `DELETE`: delete collection of InstallPlan -- `GET`: list objects of kind InstallPlan -- `POST`: create an InstallPlan -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/installplans/{name}` -- `DELETE`: delete an InstallPlan -- `GET`: read the specified InstallPlan -- `PATCH`: partially update the specified InstallPlan -- `PUT`: replace the specified InstallPlan -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/installplans/{name}/status` -- `GET`: read status of the specified InstallPlan -- `PATCH`: partially update status of the specified InstallPlan -- `PUT`: replace status of the specified InstallPlan - - -=== /apis/operators.coreos.com/v1alpha1/installplans - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind InstallPlan - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#installplanlist-operators-coreos-com-v1alpha1[`InstallPlanList operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/installplans - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#installplanlist-operators-coreos-com-v1alpha1[`InstallPlanList operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 202 - Accepted -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/installplans/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the InstallPlan -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/installplans/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the InstallPlan -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified InstallPlan - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/installplan-operators-coreos-com-v1alpha1.adoc#installplan-operators-coreos-com-v1alpha1[`InstallPlan operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operatorhub_apis/operator-operators-coreos-com-v1.adoc b/rest_api/operatorhub_apis/operator-operators-coreos-com-v1.adoc deleted file mode 100644 index e25e97bf0566..000000000000 --- a/rest_api/operatorhub_apis/operator-operators-coreos-com-v1.adoc +++ /dev/null @@ -1,777 +0,0 @@ -[id="operator-operators-coreos-com-v1"] -= Operator [operators.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Operator represents a cluster operator. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| OperatorSpec defines the desired state of Operator - -| `status` -| `object` -| OperatorStatus defines the observed state of an Operator and its components - -|=== -..spec -Description:: - OperatorSpec defines the desired state of Operator - -Type:: - `object` - - - - -..status -Description:: - OperatorStatus defines the observed state of an Operator and its components - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `components` -| `object` -| Components describes resources that compose the operator. - -|=== -..status.components -Description:: - Components describes resources that compose the operator. - -Type:: - `object` - -Required:: - - `labelSelector` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `labelSelector` -| `object` -| LabelSelector is a label query over a set of resources used to select the operator's components - -| `refs` -| `array` -| Refs are a set of references to the operator's component resources, selected with LabelSelector. - -| `refs[]` -| `object` -| RichReference is a reference to a resource, enriched with its status conditions. - -|=== -..status.components.labelSelector -Description:: - LabelSelector is a label query over a set of resources used to select the operator's components - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..status.components.labelSelector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..status.components.labelSelector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..status.components.refs -Description:: - Refs are a set of references to the operator's component resources, selected with LabelSelector. - -Type:: - `array` - - - - -..status.components.refs[] -Description:: - RichReference is a reference to a resource, enriched with its status conditions. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `conditions` -| `array` -| Conditions represents the latest state of the component. - -| `conditions[]` -| `object` -| Condition represent the latest available observations of an component's state. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status.components.refs[].conditions -Description:: - Conditions represents the latest state of the component. - -Type:: - `array` - - - - -..status.components.refs[].conditions[] -Description:: - Condition represent the latest available observations of an component's state. - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| Last time the condition transitioned from one status to another. - -| `lastUpdateTime` -| `string` -| Last time the condition was probed - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operators.coreos.com/v1/operators` -- `DELETE`: delete collection of Operator -- `GET`: list objects of kind Operator -- `POST`: create an Operator -* `/apis/operators.coreos.com/v1/operators/{name}` -- `DELETE`: delete an Operator -- `GET`: read the specified Operator -- `PATCH`: partially update the specified Operator -- `PUT`: replace the specified Operator -* `/apis/operators.coreos.com/v1/operators/{name}/status` -- `GET`: read status of the specified Operator -- `PATCH`: partially update status of the specified Operator -- `PUT`: replace status of the specified Operator - - -=== /apis/operators.coreos.com/v1/operators - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#operatorlist-operators-coreos-com-v1[`OperatorList operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 202 - Accepted -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1/operators/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Operator -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1/operators/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Operator -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Operator - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operator-operators-coreos-com-v1.adoc#operator-operators-coreos-com-v1[`Operator operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc b/rest_api/operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc deleted file mode 100644 index 114baa77aa62..000000000000 --- a/rest_api/operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc +++ /dev/null @@ -1,789 +0,0 @@ -[id="operatorcondition-operators-coreos-com-v1"] -= OperatorCondition [operators.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OperatorCondition is a Custom Resource of type `OperatorCondition` which is used to convey information to OLM about the state of an operator. - -Type:: - `object` - -Required:: - - `metadata` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| OperatorConditionSpec allows a cluster admin to convey information about the state of an operator to OLM, potentially overriding state reported by the operator. - -| `status` -| `object` -| OperatorConditionStatus allows an operator to convey information its state to OLM. The status may trail the actual state of a system. - -|=== -..spec -Description:: - OperatorConditionSpec allows a cluster admin to convey information about the state of an operator to OLM, potentially overriding state reported by the operator. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `deployments` -| `array (string)` -| - -| `overrides` -| `array` -| - -| `overrides[]` -| `object` -| Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo's current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` - // other fields } - -| `serviceAccounts` -| `array (string)` -| - -|=== -..spec.overrides -Description:: - - -Type:: - `array` - - - - -..spec.overrides[] -Description:: - Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo's current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` - // other fields } - -Type:: - `object` - -Required:: - - `message` - - `reason` - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. - -| `message` -| `string` -| message is a human readable message indicating details about the transition. This may be an empty string. - -| `observedGeneration` -| `integer` -| observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. - -| `reason` -| `string` -| reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt) - -|=== -..status -Description:: - OperatorConditionStatus allows an operator to convey information its state to OLM. The status may trail the actual state of a system. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| - -| `conditions[]` -| `object` -| Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo's current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` - // other fields } - -|=== -..status.conditions -Description:: - - -Type:: - `array` - - - - -..status.conditions[] -Description:: - Condition contains details for one aspect of the current state of this API Resource. --- This struct is intended for direct use as an array at the field path .status.conditions. For example, type FooStatus struct{ // Represents the observations of a foo's current state. // Known .status.conditions.type are: "Available", "Progressing", and "Degraded" // +patchMergeKey=type // +patchStrategy=merge // +listType=map // +listMapKey=type Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"` - // other fields } - -Type:: - `object` - -Required:: - - `lastTransitionTime` - - `message` - - `reason` - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. - -| `message` -| `string` -| message is a human readable message indicating details about the transition. This may be an empty string. - -| `observedGeneration` -| `integer` -| observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. - -| `reason` -| `string` -| reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt) - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operators.coreos.com/v1/operatorconditions` -- `GET`: list objects of kind OperatorCondition -* `/apis/operators.coreos.com/v1/namespaces/{namespace}/operatorconditions` -- `DELETE`: delete collection of OperatorCondition -- `GET`: list objects of kind OperatorCondition -- `POST`: create an OperatorCondition -* `/apis/operators.coreos.com/v1/namespaces/{namespace}/operatorconditions/{name}` -- `DELETE`: delete an OperatorCondition -- `GET`: read the specified OperatorCondition -- `PATCH`: partially update the specified OperatorCondition -- `PUT`: replace the specified OperatorCondition -* `/apis/operators.coreos.com/v1/namespaces/{namespace}/operatorconditions/{name}/status` -- `GET`: read status of the specified OperatorCondition -- `PATCH`: partially update status of the specified OperatorCondition -- `PUT`: replace status of the specified OperatorCondition - - -=== /apis/operators.coreos.com/v1/operatorconditions - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OperatorCondition - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#operatorconditionlist-operators-coreos-com-v1[`OperatorConditionList operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1/namespaces/{namespace}/operatorconditions - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#operatorconditionlist-operators-coreos-com-v1[`OperatorConditionList operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 202 - Accepted -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1/namespaces/{namespace}/operatorconditions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OperatorCondition -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1/namespaces/{namespace}/operatorconditions/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OperatorCondition -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified OperatorCondition - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operatorcondition-operators-coreos-com-v1.adoc#operatorcondition-operators-coreos-com-v1[`OperatorCondition operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc b/rest_api/operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc deleted file mode 100644 index 7b815cf90c97..000000000000 --- a/rest_api/operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc +++ /dev/null @@ -1,792 +0,0 @@ -[id="operatorgroup-operators-coreos-com-v1"] -= OperatorGroup [operators.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - OperatorGroup is the unit of multitenancy for OLM managed operators. It constrains the installation of operators in its namespace to a specified set of target namespaces. - -Type:: - `object` - -Required:: - - `metadata` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| OperatorGroupSpec is the spec for an OperatorGroup resource. - -| `status` -| `object` -| OperatorGroupStatus is the status for an OperatorGroupResource. - -|=== -..spec -Description:: - OperatorGroupSpec is the spec for an OperatorGroup resource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `selector` -| `object` -| Selector selects the OperatorGroup's target namespaces. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the admin specified service account which will be used to deploy operator(s) in this operator group. - -| `staticProvidedAPIs` -| `boolean` -| Static tells OLM not to update the OperatorGroup's providedAPIs annotation - -| `targetNamespaces` -| `array (string)` -| TargetNamespaces is an explicit set of namespaces to target. If it is set, Selector is ignored. - -|=== -..spec.selector -Description:: - Selector selects the OperatorGroup's target namespaces. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..status -Description:: - OperatorGroupStatus is the status for an OperatorGroupResource. - -Type:: - `object` - -Required:: - - `lastUpdated` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastUpdated` -| `string` -| LastUpdated is a timestamp of the last time the OperatorGroup's status was Updated. - -| `namespaces` -| `array (string)` -| Namespaces is the set of target namespaces for the OperatorGroup. - -| `serviceAccountRef` -| `object` -| ServiceAccountRef references the service account object specified. - -|=== -..status.serviceAccountRef -Description:: - ServiceAccountRef references the service account object specified. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operators.coreos.com/v1/operatorgroups` -- `GET`: list objects of kind OperatorGroup -* `/apis/operators.coreos.com/v1/namespaces/{namespace}/operatorgroups` -- `DELETE`: delete collection of OperatorGroup -- `GET`: list objects of kind OperatorGroup -- `POST`: create an OperatorGroup -* `/apis/operators.coreos.com/v1/namespaces/{namespace}/operatorgroups/{name}` -- `DELETE`: delete an OperatorGroup -- `GET`: read the specified OperatorGroup -- `PATCH`: partially update the specified OperatorGroup -- `PUT`: replace the specified OperatorGroup -* `/apis/operators.coreos.com/v1/namespaces/{namespace}/operatorgroups/{name}/status` -- `GET`: read status of the specified OperatorGroup -- `PATCH`: partially update status of the specified OperatorGroup -- `PUT`: replace status of the specified OperatorGroup - - -=== /apis/operators.coreos.com/v1/operatorgroups - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OperatorGroup - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#operatorgrouplist-operators-coreos-com-v1[`OperatorGroupList operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1/namespaces/{namespace}/operatorgroups - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#operatorgrouplist-operators-coreos-com-v1[`OperatorGroupList operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 202 - Accepted -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1/namespaces/{namespace}/operatorgroups/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OperatorGroup -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1/namespaces/{namespace}/operatorgroups/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the OperatorGroup -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified OperatorGroup - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 201 - Created -| xref:../operatorhub_apis/operatorgroup-operators-coreos-com-v1.adoc#operatorgroup-operators-coreos-com-v1[`OperatorGroup operators.coreos.com/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/operatorhub_apis/operatorhub-apis-index.adoc b/rest_api/operatorhub_apis/operatorhub-apis-index.adoc deleted file mode 100644 index 8cae5937f04b..000000000000 --- a/rest_api/operatorhub_apis/operatorhub-apis-index.adoc +++ /dev/null @@ -1,72 +0,0 @@ -[id="operatorhub-apis"] -= OperatorHub APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== CatalogSource [operators.coreos.com/v1alpha1] - -Description:: - CatalogSource is a repository of CSVs, CRDs, and operator packages. - -Type:: - `object` - -== ClusterServiceVersion [operators.coreos.com/v1alpha1] - -Description:: - ClusterServiceVersion is a Custom Resource of type `ClusterServiceVersionSpec`. - -Type:: - `object` - -== InstallPlan [operators.coreos.com/v1alpha1] - -Description:: - InstallPlan defines the installation of a set of operators. - -Type:: - `object` - -== Operator [operators.coreos.com/v1] - -Description:: - Operator represents a cluster operator. - -Type:: - `object` - -== OperatorCondition [operators.coreos.com/v1] - -Description:: - OperatorCondition is a Custom Resource of type `OperatorCondition` which is used to convey information to OLM about the state of an operator. - -Type:: - `object` - -== OperatorGroup [operators.coreos.com/v1] - -Description:: - OperatorGroup is the unit of multitenancy for OLM managed operators. It constrains the installation of operators in its namespace to a specified set of target namespaces. - -Type:: - `object` - -== PackageManifest [packages.operators.coreos.com/v1] - -Description:: - PackageManifest holds information about a package, which is a reference to one (or more) channels under a single package. - -Type:: - `object` - -== Subscription [operators.coreos.com/v1alpha1] - -Description:: - Subscription keeps operators up to date by tracking changes to Catalogs. - -Type:: - `object` - diff --git a/rest_api/operatorhub_apis/packagemanifest-packages-operators-coreos-com-v1.adoc b/rest_api/operatorhub_apis/packagemanifest-packages-operators-coreos-com-v1.adoc deleted file mode 100644 index e8a7cae0a686..000000000000 --- a/rest_api/operatorhub_apis/packagemanifest-packages-operators-coreos-com-v1.adoc +++ /dev/null @@ -1,1760 +0,0 @@ -[id="packagemanifest-packages-operators-coreos-com-v1"] -= PackageManifest [packages.operators.coreos.com/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PackageManifest holds information about a package, which is a reference to one (or more) channels under a single package. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| PackageManifestSpec defines the desired state of PackageManifest - -| `status` -| `object` -| PackageManifestStatus represents the current status of the PackageManifest - -|=== -..spec -Description:: - PackageManifestSpec defines the desired state of PackageManifest - -Type:: - `object` - - - - -..status -Description:: - PackageManifestStatus represents the current status of the PackageManifest - -Type:: - `object` - -Required:: - - `catalogSource` - - `catalogSourceDisplayName` - - `catalogSourcePublisher` - - `catalogSourceNamespace` - - `packageName` - - `channels` - - `defaultChannel` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `catalogSource` -| `string` -| CatalogSource is the name of the CatalogSource this package belongs to - -| `catalogSourceDisplayName` -| `string` -| - -| `catalogSourceNamespace` -| `string` -| - CatalogSourceNamespace is the namespace of the owning CatalogSource - -| `catalogSourcePublisher` -| `string` -| - -| `channels` -| `array` -| Channels are the declared channels for the package, ala `stable` or `alpha`. - -| `channels[]` -| `object` -| PackageChannel defines a single channel under a package, pointing to a version of that package. - -| `defaultChannel` -| `string` -| DefaultChannel is, if specified, the name of the default channel for the package. The default channel will be installed if no other channel is explicitly given. If the package has a single channel, then that channel is implicitly the default. - -| `packageName` -| `string` -| PackageName is the name of the overall package, ala `etcd`. - -| `provider` -| `object` -| AppLink defines a link to an application - -|=== -..status.channels -Description:: - Channels are the declared channels for the package, ala `stable` or `alpha`. - -Type:: - `array` - - - - -..status.channels[] -Description:: - PackageChannel defines a single channel under a package, pointing to a version of that package. - -Type:: - `object` - -Required:: - - `name` - - `currentCSV` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `currentCSV` -| `string` -| CurrentCSV defines a reference to the CSV holding the version of this package currently for the channel. - -| `currentCSVDesc` -| `object` -| CSVDescription defines a description of a CSV - -| `name` -| `string` -| Name is the name of the channel, e.g. `alpha` or `stable` - -|=== -..status.channels[].currentCSVDesc -Description:: - CSVDescription defines a description of a CSV - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| - -| `apiservicedefinitions` -| `object` -| APIServiceDefinitions declares all of the extension apis managed or required by an operator being ran by ClusterServiceVersion. - -| `customresourcedefinitions` -| `object` -| CustomResourceDefinitions declares all of the CRDs managed or required by an operator being ran by ClusterServiceVersion. - -If the CRD is present in the Owned list, it is implicitly required. - -| `description` -| `string` -| LongDescription is the CSV's description - -| `displayName` -| `string` -| DisplayName is the CSV's display name - -| `icon` -| `array` -| Icon is the CSV's base64 encoded icon - -| `icon[]` -| `object` -| Icon defines a base64 encoded icon and media type - -| `installModes` -| `array` -| InstallModes specify supported installation types - -| `installModes[]` -| `object` -| InstallMode associates an InstallModeType with a flag representing if the CSV supports it - -| `keywords` -| `array (string)` -| - -| `links` -| `array` -| - -| `links[]` -| `object` -| AppLink defines a link to an application - -| `maintainers` -| `array` -| - -| `maintainers[]` -| `object` -| Maintainer defines a project maintainer - -| `maturity` -| `string` -| - -| `minKubeVersion` -| `string` -| Minimum Kubernetes version for operator installation - -| `nativeApis` -| xref:../objects/index.adoc#groupversionkind-meta-v1[`array (GroupVersionKind meta/v1)`] -| - -| `provider` -| `object` -| AppLink defines a link to an application - -| `relatedImages` -| `array (string)` -| List of related images - -| `version` -| `string` -| OperatorVersion is a wrapper around semver.Version which supports correct marshaling to YAML and JSON. - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions -Description:: - APIServiceDefinitions declares all of the extension apis managed or required by an operator being ran by ClusterServiceVersion. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `owned` -| `array` -| - -| `owned[]` -| `object` -| APIServiceDescription provides details to OLM about apis provided via aggregation - -| `required` -| `array` -| - -| `required[]` -| `object` -| APIServiceDescription provides details to OLM about apis provided via aggregation - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.owned -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[] -Description:: - APIServiceDescription provides details to OLM about apis provided via aggregation - -Type:: - `object` - -Required:: - - `name` - - `group` - - `version` - - `kind` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actionDescriptors` -| `array` -| - -| `actionDescriptors[]` -| `object` -| ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -| `containerPort` -| `integer` -| - -| `deploymentName` -| `string` -| - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `resources` -| `array` -| - -| `resources[]` -| `object` -| APIResourceReference is a Kubernetes resource type used by a custom resource - -| `specDescriptors` -| `array` -| - -| `specDescriptors[]` -| `object` -| SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -| `statusDescriptors` -| `array` -| - -| `statusDescriptors[]` -| `object` -| StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -| `version` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[].actionDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[].actionDescriptors[] -Description:: - ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[].resources -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[].resources[] -Description:: - APIResourceReference is a Kubernetes resource type used by a custom resource - -Type:: - `object` - -Required:: - - `name` - - `kind` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `version` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[].specDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[].specDescriptors[] -Description:: - SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[].statusDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.owned[].statusDescriptors[] -Description:: - StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.required -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.required[] -Description:: - APIServiceDescription provides details to OLM about apis provided via aggregation - -Type:: - `object` - -Required:: - - `name` - - `group` - - `version` - - `kind` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actionDescriptors` -| `array` -| - -| `actionDescriptors[]` -| `object` -| ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -| `containerPort` -| `integer` -| - -| `deploymentName` -| `string` -| - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `group` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `resources` -| `array` -| - -| `resources[]` -| `object` -| APIResourceReference is a Kubernetes resource type used by a custom resource - -| `specDescriptors` -| `array` -| - -| `specDescriptors[]` -| `object` -| SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -| `statusDescriptors` -| `array` -| - -| `statusDescriptors[]` -| `object` -| StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -| `version` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.required[].actionDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.required[].actionDescriptors[] -Description:: - ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.required[].resources -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.required[].resources[] -Description:: - APIResourceReference is a Kubernetes resource type used by a custom resource - -Type:: - `object` - -Required:: - - `name` - - `kind` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `version` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.required[].specDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.required[].specDescriptors[] -Description:: - SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.apiservicedefinitions.required[].statusDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.apiservicedefinitions.required[].statusDescriptors[] -Description:: - StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions -Description:: - CustomResourceDefinitions declares all of the CRDs managed or required by an operator being ran by ClusterServiceVersion. - -If the CRD is present in the Owned list, it is implicitly required. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `owned` -| `array` -| - -| `owned[]` -| `object` -| CRDDescription provides details to OLM about the CRDs - -| `required` -| `array` -| - -| `required[]` -| `object` -| CRDDescription provides details to OLM about the CRDs - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.owned -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[] -Description:: - CRDDescription provides details to OLM about the CRDs - -Type:: - `object` - -Required:: - - `name` - - `version` - - `kind` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actionDescriptors` -| `array` -| - -| `actionDescriptors[]` -| `object` -| ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `resources` -| `array` -| - -| `resources[]` -| `object` -| APIResourceReference is a Kubernetes resource type used by a custom resource - -| `specDescriptors` -| `array` -| - -| `specDescriptors[]` -| `object` -| SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -| `statusDescriptors` -| `array` -| - -| `statusDescriptors[]` -| `object` -| StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -| `version` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[].actionDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[].actionDescriptors[] -Description:: - ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[].resources -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[].resources[] -Description:: - APIResourceReference is a Kubernetes resource type used by a custom resource - -Type:: - `object` - -Required:: - - `name` - - `kind` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `version` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[].specDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[].specDescriptors[] -Description:: - SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[].statusDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.owned[].statusDescriptors[] -Description:: - StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.required -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.required[] -Description:: - CRDDescription provides details to OLM about the CRDs - -Type:: - `object` - -Required:: - - `name` - - `version` - - `kind` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `actionDescriptors` -| `array` -| - -| `actionDescriptors[]` -| `object` -| ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `resources` -| `array` -| - -| `resources[]` -| `object` -| APIResourceReference is a Kubernetes resource type used by a custom resource - -| `specDescriptors` -| `array` -| - -| `specDescriptors[]` -| `object` -| SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -| `statusDescriptors` -| `array` -| - -| `statusDescriptors[]` -| `object` -| StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -| `version` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.required[].actionDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.required[].actionDescriptors[] -Description:: - ActionDescriptor describes a declarative action that can be performed on a custom resource instance - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.required[].resources -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.required[].resources[] -Description:: - APIResourceReference is a Kubernetes resource type used by a custom resource - -Type:: - `object` - -Required:: - - `name` - - `kind` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `version` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.required[].specDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.required[].specDescriptors[] -Description:: - SpecDescriptor describes a field in a spec block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.customresourcedefinitions.required[].statusDescriptors -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.customresourcedefinitions.required[].statusDescriptors[] -Description:: - StatusDescriptor describes a field in a status block of a CRD so that OLM can consume it - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| - -| `displayName` -| `string` -| - -| `path` -| `string` -| - -| `value` -| `string` -| - -| `x-descriptors` -| `array (string)` -| - -|=== -..status.channels[].currentCSVDesc.icon -Description:: - Icon is the CSV's base64 encoded icon - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.icon[] -Description:: - Icon defines a base64 encoded icon and media type - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `base64data` -| `string` -| - -| `mediatype` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.installModes -Description:: - InstallModes specify supported installation types - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.installModes[] -Description:: - InstallMode associates an InstallModeType with a flag representing if the CSV supports it - -Type:: - `object` - -Required:: - - `type` - - `supported` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `supported` -| `boolean` -| - -| `type` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.links -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.links[] -Description:: - AppLink defines a link to an application - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| - -| `url` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.maintainers -Description:: - - -Type:: - `array` - - - - -..status.channels[].currentCSVDesc.maintainers[] -Description:: - Maintainer defines a project maintainer - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| - -| `name` -| `string` -| - -|=== -..status.channels[].currentCSVDesc.provider -Description:: - AppLink defines a link to an application - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| - -| `url` -| `string` -| - -|=== -..status.provider -Description:: - AppLink defines a link to an application - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| - -| `url` -| `string` -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/packages.operators.coreos.com/v1/packagemanifests` -- `GET`: list objects of kind PackageManifest -* `/apis/packages.operators.coreos.com/v1/namespaces/{namespace}/packagemanifests` -- `GET`: list objects of kind PackageManifest -* `/apis/packages.operators.coreos.com/v1/namespaces/{namespace}/packagemanifests/{name}` -- `GET`: read the specified PackageManifest - - -=== /apis/packages.operators.coreos.com/v1/packagemanifests - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind PackageManifest - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#packagemanifestlist-packages-operators-coreos-com-v1[`PackageManifestList packages.operators.coreos.com/v1`] -|=== - - -=== /apis/packages.operators.coreos.com/v1/namespaces/{namespace}/packagemanifests - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind PackageManifest - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#packagemanifestlist-packages-operators-coreos-com-v1[`PackageManifestList packages.operators.coreos.com/v1`] -|=== - - -=== /apis/packages.operators.coreos.com/v1/namespaces/{namespace}/packagemanifests/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PackageManifest -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PackageManifest - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/packagemanifest-packages-operators-coreos-com-v1.adoc#packagemanifest-packages-operators-coreos-com-v1[`PackageManifest packages.operators.coreos.com/v1`] -|=== - - diff --git a/rest_api/operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc b/rest_api/operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc deleted file mode 100644 index 373b2399dbde..000000000000 --- a/rest_api/operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc +++ /dev/null @@ -1,3478 +0,0 @@ -[id="subscription-operators-coreos-com-v1alpha1"] -= Subscription [operators.coreos.com/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Subscription keeps operators up to date by tracking changes to Catalogs. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| SubscriptionSpec defines an Application that can be installed - -| `status` -| `object` -| - -|=== -..spec -Description:: - SubscriptionSpec defines an Application that can be installed - -Type:: - `object` - -Required:: - - `name` - - `source` - - `sourceNamespace` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `channel` -| `string` -| - -| `config` -| `object` -| SubscriptionConfig contains configuration specified for a subscription. - -| `installPlanApproval` -| `string` -| Approval is the user approval policy for an InstallPlan. It must be one of "Automatic" or "Manual". - -| `name` -| `string` -| - -| `source` -| `string` -| - -| `sourceNamespace` -| `string` -| - -| `startingCSV` -| `string` -| - -|=== -..spec.config -Description:: - SubscriptionConfig contains configuration specified for a subscription. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `env` -| `array` -| Env is a list of environment variables to set in the container. Cannot be updated. - -| `env[]` -| `object` -| EnvVar represents an environment variable present in a Container. - -| `envFrom` -| `array` -| EnvFrom is a list of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Immutable. - -| `envFrom[]` -| `object` -| EnvFromSource represents the source of a set of ConfigMaps - -| `nodeSelector` -| `object (string)` -| NodeSelector is a selector which must be true for the pod to fit on a node. Selector which must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ - -| `resources` -| `object` -| Resources represents compute resources required by this container. Immutable. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `selector` -| `object` -| Selector is the label selector for pods to be configured. Existing ReplicaSets whose pods are selected by this will be the ones affected by this deployment. It must match the pod template's labels. - -| `tolerations` -| `array` -| Tolerations are the pod's tolerations. - -| `tolerations[]` -| `object` -| The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -| `volumeMounts` -| `array` -| List of VolumeMounts to set in the container. - -| `volumeMounts[]` -| `object` -| VolumeMount describes a mounting of a Volume within a container. - -| `volumes` -| `array` -| List of Volumes to set in the podSpec. - -| `volumes[]` -| `object` -| Volume represents a named volume in a pod that may be accessed by any container in the pod. - -|=== -..spec.config.env -Description:: - Env is a list of environment variables to set in the container. Cannot be updated. - -Type:: - `array` - - - - -..spec.config.env[] -Description:: - EnvVar represents an environment variable present in a Container. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the environment variable. Must be a C_IDENTIFIER. - -| `value` -| `string` -| Variable references $(VAR_NAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to "". - -| `valueFrom` -| `object` -| Source for the environment variable's value. Cannot be used if value is not empty. - -|=== -..spec.config.env[].valueFrom -Description:: - Source for the environment variable's value. Cannot be used if value is not empty. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapKeyRef` -| `object` -| Selects a key of a ConfigMap. - -| `fieldRef` -| `object` -| Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -| `secretKeyRef` -| `object` -| Selects a key of a secret in the pod's namespace - -|=== -..spec.config.env[].valueFrom.configMapKeyRef -Description:: - Selects a key of a ConfigMap. - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to select. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its key must be defined - -|=== -..spec.config.env[].valueFrom.fieldRef -Description:: - Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.config.env[].valueFrom.resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.config.env[].valueFrom.secretKeyRef -Description:: - Selects a key of a secret in the pod's namespace - -Type:: - `object` - -Required:: - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key of the secret to select from. Must be a valid secret key. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.config.envFrom -Description:: - EnvFrom is a list of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Immutable. - -Type:: - `array` - - - - -..spec.config.envFrom[] -Description:: - EnvFromSource represents the source of a set of ConfigMaps - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMapRef` -| `object` -| The ConfigMap to select from - -| `prefix` -| `string` -| An optional identifier to prepend to each key in the ConfigMap. Must be a C_IDENTIFIER. - -| `secretRef` -| `object` -| The Secret to select from - -|=== -..spec.config.envFrom[].configMapRef -Description:: - The ConfigMap to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap must be defined - -|=== -..spec.config.envFrom[].secretRef -Description:: - The Secret to select from - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret must be defined - -|=== -..spec.config.resources -Description:: - Resources represents compute resources required by this container. Immutable. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.config.selector -Description:: - Selector is the label selector for pods to be configured. Existing ReplicaSets whose pods are selected by this will be the ones affected by this deployment. It must match the pod template's labels. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.config.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.config.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.config.tolerations -Description:: - Tolerations are the pod's tolerations. - -Type:: - `array` - - - - -..spec.config.tolerations[] -Description:: - The pod this Toleration is attached to tolerates any taint that matches the triple <key,value,effect> using the matching operator <operator>. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. - -| `operator` -| `string` -| Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. - -| `tolerationSeconds` -| `integer` -| TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. - -| `value` -| `string` -| Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. - -|=== -..spec.config.volumeMounts -Description:: - List of VolumeMounts to set in the container. - -Type:: - `array` - - - - -..spec.config.volumeMounts[] -Description:: - VolumeMount describes a mounting of a Volume within a container. - -Type:: - `object` - -Required:: - - `mountPath` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| Path within the container at which the volume should be mounted. Must not contain ':'. - -| `mountPropagation` -| `string` -| mountPropagation determines how mounts are propagated from the host to container and the other way around. When not set, MountPropagationNone is used. This field is beta in 1.10. - -| `name` -| `string` -| This must match the Name of a Volume. - -| `readOnly` -| `boolean` -| Mounted read-only if true, read-write otherwise (false or unspecified). Defaults to false. - -| `subPath` -| `string` -| Path within the volume from which the container's volume should be mounted. Defaults to "" (volume's root). - -| `subPathExpr` -| `string` -| Expanded path within the volume from which the container's volume should be mounted. Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment. Defaults to "" (volume's root). SubPathExpr and SubPath are mutually exclusive. - -|=== -..spec.config.volumes -Description:: - List of Volumes to set in the podSpec. - -Type:: - `array` - - - - -..spec.config.volumes[] -Description:: - Volume represents a named volume in a pod that may be accessed by any container in the pod. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `awsElasticBlockStore` -| `object` -| AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `azureDisk` -| `object` -| AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -| `azureFile` -| `object` -| AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -| `cephfs` -| `object` -| CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -| `cinder` -| `object` -| Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `configMap` -| `object` -| ConfigMap represents a configMap that should populate this volume - -| `csi` -| `object` -| CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). - -| `downwardAPI` -| `object` -| DownwardAPI represents downward API about the pod that should populate this volume - -| `emptyDir` -| `object` -| EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `ephemeral` -| `object` -| Ephemeral represents a volume that is handled by a cluster storage driver (Alpha feature). The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts, and deleted when the pod is removed. - Use this if: a) the volume is only needed while the pod runs, b) features of normal volumes like restoring from snapshot or capacity tracking are needed, c) the storage driver is specified through a storage class, and d) the storage driver supports dynamic volume provisioning through a PersistentVolumeClaim (see EphemeralVolumeSource for more information on the connection between this volume type and PersistentVolumeClaim). - Use PersistentVolumeClaim or one of the vendor-specific APIs for volumes that persist for longer than the lifecycle of an individual pod. - Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to be used that way - see the documentation of the driver for more information. - A pod can use both types of ephemeral volumes and persistent volumes at the same time. - -| `fc` -| `object` -| FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -| `flexVolume` -| `object` -| FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -| `flocker` -| `object` -| Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -| `gcePersistentDisk` -| `object` -| GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `gitRepo` -| `object` -| GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -| `glusterfs` -| `object` -| Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -| `hostPath` -| `object` -| HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -| `iscsi` -| `object` -| ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -| `name` -| `string` -| Volume's name. Must be a DNS_LABEL and unique within the pod. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `nfs` -| `object` -| NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `persistentVolumeClaim` -| `object` -| PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `photonPersistentDisk` -| `object` -| PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -| `portworxVolume` -| `object` -| PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -| `projected` -| `object` -| Items for all in one resources secrets, configmaps, and downward API - -| `quobyte` -| `object` -| Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -| `rbd` -| `object` -| RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -| `scaleIO` -| `object` -| ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -| `secret` -| `object` -| Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -| `storageos` -| `object` -| StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -| `vsphereVolume` -| `object` -| VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -|=== -..spec.config.volumes[].awsElasticBlockStore -Description:: - AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). - -| `readOnly` -| `boolean` -| Specify "true" to force and set the ReadOnly property in VolumeMounts to "true". If omitted, the default is "false". More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `volumeID` -| `string` -| Unique ID of the persistent disk resource in AWS (Amazon EBS volume). More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -|=== -..spec.config.volumes[].azureDisk -Description:: - AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `diskName` - - `diskURI` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cachingMode` -| `string` -| Host Caching mode: None, Read Only, Read Write. - -| `diskName` -| `string` -| The Name of the data disk in the blob storage - -| `diskURI` -| `string` -| The URI the data disk in the blob storage - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `kind` -| `string` -| Expected values Shared: multiple blob disks per storage account Dedicated: single blob disk per storage account Managed: azure managed data disk (only in managed availability set). defaults to shared - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -|=== -..spec.config.volumes[].azureFile -Description:: - AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -Type:: - `object` - -Required:: - - `secretName` - - `shareName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretName` -| `string` -| the name of secret that contains Azure Storage Account Name and Key - -| `shareName` -| `string` -| Share Name - -|=== -..spec.config.volumes[].cephfs -Description:: - CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `monitors` -| `array (string)` -| Required: Monitors is a collection of Ceph monitors More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `path` -| `string` -| Optional: Used as the mounted root, rather than the full Ceph tree, default is / - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretFile` -| `string` -| Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -| `user` -| `string` -| Optional: User is the rados user name, default is admin More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -|=== -..spec.config.volumes[].cephfs.secretRef -Description:: - Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.config.volumes[].cinder -Description:: - Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `secretRef` -| `object` -| Optional: points to a secret object containing parameters used to connect to OpenStack. - -| `volumeID` -| `string` -| volume id used to identify the volume in cinder. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -|=== -..spec.config.volumes[].cinder.secretRef -Description:: - Optional: points to a secret object containing parameters used to connect to OpenStack. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.config.volumes[].configMap -Description:: - ConfigMap represents a configMap that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.config.volumes[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.config.volumes[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.config.volumes[].csi -Description:: - CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature). - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the CSI driver that handles this volume. Consult with your admin for the correct name as registered in the cluster. - -| `fsType` -| `string` -| Filesystem type to mount. Ex. "ext4", "xfs", "ntfs". If not provided, the empty value is passed to the associated CSI driver which will determine the default filesystem to apply. - -| `nodePublishSecretRef` -| `object` -| NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeAttributes` -| `object (string)` -| VolumeAttributes stores driver-specific properties that are passed to the CSI driver. Consult your driver's documentation for supported values. - -|=== -..spec.config.volumes[].csi.nodePublishSecretRef -Description:: - NodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.config.volumes[].downwardAPI -Description:: - DownwardAPI represents downward API about the pod that should populate this volume - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits to use on created files by default. Must be a Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| Items is a list of downward API volume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.config.volumes[].downwardAPI.items -Description:: - Items is a list of downward API volume file - -Type:: - `array` - - - - -..spec.config.volumes[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file, must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.config.volumes[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.config.volumes[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.config.volumes[].emptyDir -Description:: - EmptyDir represents a temporary directory that shares a pod's lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `medium` -| `string` -| What type of storage medium should back this directory. The default is "" which means to use the node's default medium. Must be an empty string (default) or Memory. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir - -| `sizeLimit` -| `integer-or-string` -| Total amount of local storage required for this EmptyDir volume. The size limit is also applicable for memory medium. The maximum usage on memory medium EmptyDir would be the minimum value between the SizeLimit specified here and the sum of memory limits of all containers in a pod. The default is nil which means that the limit is undefined. More info: http://kubernetes.io/docs/user-guide/volumes#emptydir - -|=== -..spec.config.volumes[].ephemeral -Description:: - Ephemeral represents a volume that is handled by a cluster storage driver (Alpha feature). The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts, and deleted when the pod is removed. - Use this if: a) the volume is only needed while the pod runs, b) features of normal volumes like restoring from snapshot or capacity tracking are needed, c) the storage driver is specified through a storage class, and d) the storage driver supports dynamic volume provisioning through a PersistentVolumeClaim (see EphemeralVolumeSource for more information on the connection between this volume type and PersistentVolumeClaim). - Use PersistentVolumeClaim or one of the vendor-specific APIs for volumes that persist for longer than the lifecycle of an individual pod. - Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to be used that way - see the documentation of the driver for more information. - A pod can use both types of ephemeral volumes and persistent volumes at the same time. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `readOnly` -| `boolean` -| Specifies a read-only configuration for the volume. Defaults to false (read/write). - -| `volumeClaimTemplate` -| `object` -| Will be used to create a stand-alone PVC to provision the volume. The pod in which this EphemeralVolumeSource is embedded will be the owner of the PVC, i.e. the PVC will be deleted together with the pod. The name of the PVC will be `<pod name>-<volume name>` where `<volume name>` is the name from the `PodSpec.Volumes` array entry. Pod validation will reject the pod if the concatenated name is not valid for a PVC (for example, too long). - An existing PVC with that name that is not owned by the pod will *not* be used for the pod to avoid using an unrelated volume by mistake. Starting the pod is then blocked until the unrelated PVC is removed. If such a pre-created PVC is meant to be used by the pod, the PVC has to updated with an owner reference to the pod once the pod exists. Normally this should not be necessary, but it may be useful when manually reconstructing a broken cluster. - This field is read-only and no changes will be made by Kubernetes to the PVC after it has been created. - Required, must not be nil. - -|=== -..spec.config.volumes[].ephemeral.volumeClaimTemplate -Description:: - Will be used to create a stand-alone PVC to provision the volume. The pod in which this EphemeralVolumeSource is embedded will be the owner of the PVC, i.e. the PVC will be deleted together with the pod. The name of the PVC will be `<pod name>-<volume name>` where `<volume name>` is the name from the `PodSpec.Volumes` array entry. Pod validation will reject the pod if the concatenated name is not valid for a PVC (for example, too long). - An existing PVC with that name that is not owned by the pod will *not* be used for the pod to avoid using an unrelated volume by mistake. Starting the pod is then blocked until the unrelated PVC is removed. If such a pre-created PVC is meant to be used by the pod, the PVC has to updated with an owner reference to the pod once the pod exists. Normally this should not be necessary, but it may be useful when manually reconstructing a broken cluster. - This field is read-only and no changes will be made by Kubernetes to the PVC after it has been created. - Required, must not be nil. - -Type:: - `object` - -Required:: - - `spec` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| `object` -| May contain labels and annotations that will be copied into the PVC when creating it. No other fields are allowed and will be rejected during validation. - -| `spec` -| `object` -| The specification for the PersistentVolumeClaim. The entire content is copied unchanged into the PVC that gets created from this template. The same fields as in a PersistentVolumeClaim are also valid here. - -|=== -..spec.config.volumes[].ephemeral.volumeClaimTemplate.metadata -Description:: - May contain labels and annotations that will be copied into the PVC when creating it. No other fields are allowed and will be rejected during validation. - -Type:: - `object` - - - - -..spec.config.volumes[].ephemeral.volumeClaimTemplate.spec -Description:: - The specification for the PersistentVolumeClaim. The entire content is copied unchanged into the PVC that gets created from this template. The same fields as in a PersistentVolumeClaim are also valid here. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `dataSource` -| `object` -| This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) * An existing PVC (PersistentVolumeClaim) * An existing custom resource that implements data population (Alpha) In order to use custom resource types that implement data population, the AnyVolumeDataSource feature gate must be enabled. If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. - -| `resources` -| `object` -| Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -| `selector` -| `object` -| A label query over volumes to consider for binding. - -| `storageClassName` -| `string` -| Name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 - -| `volumeMode` -| `string` -| volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. - -| `volumeName` -| `string` -| VolumeName is the binding reference to the PersistentVolume backing this claim. - -|=== -..spec.config.volumes[].ephemeral.volumeClaimTemplate.spec.dataSource -Description:: - This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) * An existing PVC (PersistentVolumeClaim) * An existing custom resource that implements data population (Alpha) In order to use custom resource types that implement data population, the AnyVolumeDataSource feature gate must be enabled. If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required. - -| `kind` -| `string` -| Kind is the type of resource being referenced - -| `name` -| `string` -| Name is the name of resource being referenced - -|=== -..spec.config.volumes[].ephemeral.volumeClaimTemplate.spec.resources -Description:: - Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| `integer-or-string` -| Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -| `requests` -| `integer-or-string` -| Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. More info: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ - -|=== -..spec.config.volumes[].ephemeral.volumeClaimTemplate.spec.selector -Description:: - A label query over volumes to consider for binding. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| matchExpressions is a list of label selector requirements. The requirements are ANDed. - -| `matchExpressions[]` -| `object` -| A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -| `matchLabels` -| `object (string)` -| matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is "key", the operator is "In", and the values array contains only "value". The requirements are ANDed. - -|=== -..spec.config.volumes[].ephemeral.volumeClaimTemplate.spec.selector.matchExpressions -Description:: - matchExpressions is a list of label selector requirements. The requirements are ANDed. - -Type:: - `array` - - - - -..spec.config.volumes[].ephemeral.volumeClaimTemplate.spec.selector.matchExpressions[] -Description:: - A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values. - -Type:: - `object` - -Required:: - - `key` - - `operator` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| key is the label key that the selector applies to. - -| `operator` -| `string` -| operator represents a key's relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist. - -| `values` -| `array (string)` -| values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.config.volumes[].fc -Description:: - FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. TODO: how do we prevent errors in the filesystem from compromising the machine - -| `lun` -| `integer` -| Optional: FC target lun number - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `targetWWNs` -| `array (string)` -| Optional: FC target worldwide names (WWNs) - -| `wwids` -| `array (string)` -| Optional: FC volume world wide identifiers (wwids) Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously. - -|=== -..spec.config.volumes[].flexVolume -Description:: - FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -Type:: - `object` - -Required:: - - `driver` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `driver` -| `string` -| Driver is the name of the driver to use for this volume. - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script. - -| `options` -| `object (string)` -| Optional: Extra command options if any. - -| `readOnly` -| `boolean` -| Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -|=== -..spec.config.volumes[].flexVolume.secretRef -Description:: - Optional: SecretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.config.volumes[].flocker -Description:: - Flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `datasetName` -| `string` -| Name of the dataset stored as metadata -> name on the dataset for Flocker should be considered as deprecated - -| `datasetUUID` -| `string` -| UUID of the dataset. This is unique identifier of a Flocker dataset - -|=== -..spec.config.volumes[].gcePersistentDisk -Description:: - GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -Type:: - `object` - -Required:: - - `pdName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk TODO: how do we prevent errors in the filesystem from compromising the machine - -| `partition` -| `integer` -| The partition in the volume that you want to mount. If omitted, the default is to mount by volume name. Examples: For volume /dev/sda1, you specify the partition as "1". Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty). More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `pdName` -| `string` -| Unique name of the PD resource in GCE. Used to identify the disk in GCE. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -|=== -..spec.config.volumes[].gitRepo -Description:: - GitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod's container. - -Type:: - `object` - -Required:: - - `repository` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `directory` -| `string` -| Target directory name. Must not contain or start with '..'. If '.' is supplied, the volume directory will be the git repository. Otherwise, if specified, the volume will contain the git repository in the subdirectory with the given name. - -| `repository` -| `string` -| Repository URL - -| `revision` -| `string` -| Commit hash for the specified revision. - -|=== -..spec.config.volumes[].glusterfs -Description:: - Glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -Type:: - `object` - -Required:: - - `endpoints` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `endpoints` -| `string` -| EndpointsName is the endpoint name that details Glusterfs topology. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `path` -| `string` -| Path is the Glusterfs volume path. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -| `readOnly` -| `boolean` -| ReadOnly here will force the Glusterfs volume to be mounted with read-only permissions. Defaults to false. More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod - -|=== -..spec.config.volumes[].hostPath -Description:: - HostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath --- TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write. - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path of the directory on the host. If the path is a symlink, it will follow the link to the real path. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `type` -| `string` -| Type for HostPath Volume Defaults to "" More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -|=== -..spec.config.volumes[].iscsi -Description:: - ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md - -Type:: - `object` - -Required:: - - `iqn` - - `lun` - - `targetPortal` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `chapAuthDiscovery` -| `boolean` -| whether support iSCSI Discovery CHAP authentication - -| `chapAuthSession` -| `boolean` -| whether support iSCSI Session CHAP authentication - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi TODO: how do we prevent errors in the filesystem from compromising the machine - -| `initiatorName` -| `string` -| Custom iSCSI Initiator Name. If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface <target portal>:<volume name> will be created for the connection. - -| `iqn` -| `string` -| Target iSCSI Qualified Name. - -| `iscsiInterface` -| `string` -| iSCSI Interface Name that uses an iSCSI transport. Defaults to 'default' (tcp). - -| `lun` -| `integer` -| iSCSI Target Lun number. - -| `portals` -| `array (string)` -| iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. - -| `secretRef` -| `object` -| CHAP Secret for iSCSI target and initiator authentication - -| `targetPortal` -| `string` -| iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port is other than default (typically TCP ports 860 and 3260). - -|=== -..spec.config.volumes[].iscsi.secretRef -Description:: - CHAP Secret for iSCSI target and initiator authentication - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.config.volumes[].nfs -Description:: - NFS represents an NFS mount on the host that shares a pod's lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -Type:: - `object` - -Required:: - - `path` - - `server` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `path` -| `string` -| Path that is exported by the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `readOnly` -| `boolean` -| ReadOnly here will force the NFS export to be mounted with read-only permissions. Defaults to false. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `server` -| `string` -| Server is the hostname or IP address of the NFS server. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -|=== -..spec.config.volumes[].persistentVolumeClaim -Description:: - PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -Type:: - `object` - -Required:: - - `claimName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `claimName` -| `string` -| ClaimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims - -| `readOnly` -| `boolean` -| Will force the ReadOnly setting in VolumeMounts. Default false. - -|=== -..spec.config.volumes[].photonPersistentDisk -Description:: - PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `pdID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `pdID` -| `string` -| ID that identifies Photon Controller persistent disk - -|=== -..spec.config.volumes[].portworxVolume -Description:: - PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| FSType represents the filesystem type to mount Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `volumeID` -| `string` -| VolumeID uniquely identifies a Portworx volume - -|=== -..spec.config.volumes[].projected -Description:: - Items for all in one resources secrets, configmaps, and downward API - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `sources` -| `array` -| list of volume projections - -| `sources[]` -| `object` -| Projection that may be projected along with other supported volume types - -|=== -..spec.config.volumes[].projected.sources -Description:: - list of volume projections - -Type:: - `array` - - - - -..spec.config.volumes[].projected.sources[] -Description:: - Projection that may be projected along with other supported volume types - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| `object` -| information about the configMap data to project - -| `downwardAPI` -| `object` -| information about the downwardAPI data to project - -| `secret` -| `object` -| information about the secret data to project - -| `serviceAccountToken` -| `object` -| information about the serviceAccountToken data to project - -|=== -..spec.config.volumes[].projected.sources[].configMap -Description:: - information about the configMap data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the ConfigMap or its keys must be defined - -|=== -..spec.config.volumes[].projected.sources[].configMap.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced ConfigMap will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the ConfigMap, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.config.volumes[].projected.sources[].configMap.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.config.volumes[].projected.sources[].downwardAPI -Description:: - information about the downwardAPI data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| Items is a list of DownwardAPIVolume file - -| `items[]` -| `object` -| DownwardAPIVolumeFile represents information to create the file containing the pod field - -|=== -..spec.config.volumes[].projected.sources[].downwardAPI.items -Description:: - Items is a list of DownwardAPIVolume file - -Type:: - `array` - - - - -..spec.config.volumes[].projected.sources[].downwardAPI.items[] -Description:: - DownwardAPIVolumeFile represents information to create the file containing the pod field - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fieldRef` -| `object` -| Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file, must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| Required: Path is the relative path name of the file to be created. Must not be absolute or contain the '..' path. Must be utf-8 encoded. The first item of the relative path must not start with '..' - -| `resourceFieldRef` -| `object` -| Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -|=== -..spec.config.volumes[].projected.sources[].downwardAPI.items[].fieldRef -Description:: - Required: Selects a field of the pod: only annotations, labels, name and namespace are supported. - -Type:: - `object` - -Required:: - - `fieldPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| Version of the schema the FieldPath is written in terms of, defaults to "v1". - -| `fieldPath` -| `string` -| Path of the field to select in the specified API version. - -|=== -..spec.config.volumes[].projected.sources[].downwardAPI.items[].resourceFieldRef -Description:: - Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| Container name: required for volumes, optional for env vars - -| `divisor` -| `integer-or-string` -| Specifies the output format of the exposed resources, defaults to "1" - -| `resource` -| `string` -| Required: resource to select - -|=== -..spec.config.volumes[].projected.sources[].secret -Description:: - information about the secret data to project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -| `optional` -| `boolean` -| Specify whether the Secret or its key must be defined - -|=== -..spec.config.volumes[].projected.sources[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.config.volumes[].projected.sources[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.config.volumes[].projected.sources[].serviceAccountToken -Description:: - information about the serviceAccountToken data to project - -Type:: - `object` - -Required:: - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audience` -| `string` -| Audience is the intended audience of the token. A recipient of a token must identify itself with an identifier specified in the audience of the token, and otherwise should reject the token. The audience defaults to the identifier of the apiserver. - -| `expirationSeconds` -| `integer` -| ExpirationSeconds is the requested duration of validity of the service account token. As the token approaches expiration, the kubelet volume plugin will proactively rotate the service account token. The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours.Defaults to 1 hour and must be at least 10 minutes. - -| `path` -| `string` -| Path is the path relative to the mount point of the file to project the token into. - -|=== -..spec.config.volumes[].quobyte -Description:: - Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -Type:: - `object` - -Required:: - - `registry` - - `volume` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| Group to map volume access to Default is no group - -| `readOnly` -| `boolean` -| ReadOnly here will force the Quobyte volume to be mounted with read-only permissions. Defaults to false. - -| `registry` -| `string` -| Registry represents a single or multiple Quobyte Registry services specified as a string as host:port pair (multiple entries are separated with commas) which acts as the central registry for volumes - -| `tenant` -| `string` -| Tenant owning the given Quobyte volume in the Backend Used with dynamically provisioned Quobyte volumes, value is set by the plugin - -| `user` -| `string` -| User to map volume access to Defaults to serivceaccount user - -| `volume` -| `string` -| Volume is a string that references an already created Quobyte volume by name. - -|=== -..spec.config.volumes[].rbd -Description:: - RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -Type:: - `object` - -Required:: - - `image` - - `monitors` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type of the volume that you want to mount. Tip: Ensure that the filesystem type is supported by the host operating system. Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd TODO: how do we prevent errors in the filesystem from compromising the machine - -| `image` -| `string` -| The rados image name. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `keyring` -| `string` -| Keyring is the path to key ring for RBDUser. Default is /etc/ceph/keyring. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `monitors` -| `array (string)` -| A collection of Ceph monitors. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `pool` -| `string` -| The rados pool name. Default is rbd. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `readOnly` -| `boolean` -| ReadOnly here will force the ReadOnly setting in VolumeMounts. Defaults to false. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `secretRef` -| `object` -| SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -| `user` -| `string` -| The rados user name. Default is admin. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -|=== -..spec.config.volumes[].rbd.secretRef -Description:: - SecretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.config.volumes[].scaleIO -Description:: - ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - -Required:: - - `gateway` - - `secretRef` - - `system` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Default is "xfs". - -| `gateway` -| `string` -| The host address of the ScaleIO API Gateway. - -| `protectionDomain` -| `string` -| The name of the ScaleIO Protection Domain for the configured storage. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -| `sslEnabled` -| `boolean` -| Flag to enable/disable SSL communication with Gateway, default false - -| `storageMode` -| `string` -| Indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned. Default is ThinProvisioned. - -| `storagePool` -| `string` -| The ScaleIO Storage Pool associated with the protection domain. - -| `system` -| `string` -| The name of the storage system as configured in ScaleIO. - -| `volumeName` -| `string` -| The name of a volume already created in the ScaleIO system that is associated with this volume source. - -|=== -..spec.config.volumes[].scaleIO.secretRef -Description:: - SecretRef references to the secret for ScaleIO user and other sensitive information. If this is not provided, Login operation will fail. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.config.volumes[].secret -Description:: - Secret represents a secret that should populate this volume. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `defaultMode` -| `integer` -| Optional: mode bits used to set permissions on created files by default. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644. Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `items` -| `array` -| If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -| `items[]` -| `object` -| Maps a string key to a path within a volume. - -| `optional` -| `boolean` -| Specify whether the Secret or its keys must be defined - -| `secretName` -| `string` -| Name of the secret in the pod's namespace to use. More info: https://kubernetes.io/docs/concepts/storage/volumes#secret - -|=== -..spec.config.volumes[].secret.items -Description:: - If unspecified, each key-value pair in the Data field of the referenced Secret will be projected into the volume as a file whose name is the key and content is the value. If specified, the listed keys will be projected into the specified paths, and unlisted keys will not be present. If a key is specified which is not present in the Secret, the volume setup will error unless it is marked optional. Paths must be relative and may not contain the '..' path or start with '..'. - -Type:: - `array` - - - - -..spec.config.volumes[].secret.items[] -Description:: - Maps a string key to a path within a volume. - -Type:: - `object` - -Required:: - - `key` - - `path` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `key` -| `string` -| The key to project. - -| `mode` -| `integer` -| Optional: mode bits used to set permissions on this file. Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. If not specified, the volume defaultMode will be used. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set. - -| `path` -| `string` -| The relative path of the file to map the key to. May not be an absolute path. May not contain the path element '..'. May not start with the string '..'. - -|=== -..spec.config.volumes[].storageos -Description:: - StorageOS represents a StorageOS volume attached and mounted on Kubernetes nodes. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `readOnly` -| `boolean` -| Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts. - -| `secretRef` -| `object` -| SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -| `volumeName` -| `string` -| VolumeName is the human-readable name of the StorageOS volume. Volume names are only unique within a namespace. - -| `volumeNamespace` -| `string` -| VolumeNamespace specifies the scope of the volume within StorageOS. If no namespace is specified then the Pod's namespace will be used. This allows the Kubernetes name scoping to be mirrored within StorageOS for tighter integration. Set VolumeName to any name to override the default behaviour. Set to "default" if you are not using namespaces within StorageOS. Namespaces that do not pre-exist within StorageOS will be created. - -|=== -..spec.config.volumes[].storageos.secretRef -Description:: - SecretRef specifies the secret to use for obtaining the StorageOS API credentials. If not specified, default values will be attempted. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names TODO: Add other useful fields. apiVersion, kind, uid? - -|=== -..spec.config.volumes[].vsphereVolume -Description:: - VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -Type:: - `object` - -Required:: - - `volumePath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fsType` -| `string` -| Filesystem type to mount. Must be a filesystem type supported by the host operating system. Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified. - -| `storagePolicyID` -| `string` -| Storage Policy Based Management (SPBM) profile ID associated with the StoragePolicyName. - -| `storagePolicyName` -| `string` -| Storage Policy Based Management (SPBM) profile name. - -| `volumePath` -| `string` -| Path that identifies vSphere volume vmdk - -|=== -..status -Description:: - - -Type:: - `object` - -Required:: - - `lastUpdated` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `catalogHealth` -| `array` -| CatalogHealth contains the Subscription's view of its relevant CatalogSources' status. It is used to determine SubscriptionStatusConditions related to CatalogSources. - -| `catalogHealth[]` -| `object` -| SubscriptionCatalogHealth describes the health of a CatalogSource the Subscription knows about. - -| `conditions` -| `array` -| Conditions is a list of the latest available observations about a Subscription's current state. - -| `conditions[]` -| `object` -| SubscriptionCondition represents the latest available observations of a Subscription's state. - -| `currentCSV` -| `string` -| CurrentCSV is the CSV the Subscription is progressing to. - -| `installPlanGeneration` -| `integer` -| InstallPlanGeneration is the current generation of the installplan - -| `installPlanRef` -| `object` -| InstallPlanRef is a reference to the latest InstallPlan that contains the Subscription's current CSV. - -| `installedCSV` -| `string` -| InstalledCSV is the CSV currently installed by the Subscription. - -| `installplan` -| `object` -| Install is a reference to the latest InstallPlan generated for the Subscription. DEPRECATED: InstallPlanRef - -| `lastUpdated` -| `string` -| LastUpdated represents the last time that the Subscription status was updated. - -| `reason` -| `string` -| Reason is the reason the Subscription was transitioned to its current state. - -| `state` -| `string` -| State represents the current state of the Subscription - -|=== -..status.catalogHealth -Description:: - CatalogHealth contains the Subscription's view of its relevant CatalogSources' status. It is used to determine SubscriptionStatusConditions related to CatalogSources. - -Type:: - `array` - - - - -..status.catalogHealth[] -Description:: - SubscriptionCatalogHealth describes the health of a CatalogSource the Subscription knows about. - -Type:: - `object` - -Required:: - - `catalogSourceRef` - - `healthy` - - `lastUpdated` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `catalogSourceRef` -| `object` -| CatalogSourceRef is a reference to a CatalogSource. - -| `healthy` -| `boolean` -| Healthy is true if the CatalogSource is healthy; false otherwise. - -| `lastUpdated` -| `string` -| LastUpdated represents the last time that the CatalogSourceHealth changed - -|=== -..status.catalogHealth[].catalogSourceRef -Description:: - CatalogSourceRef is a reference to a CatalogSource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status.conditions -Description:: - Conditions is a list of the latest available observations about a Subscription's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - SubscriptionCondition represents the latest available observations of a Subscription's state. - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastHeartbeatTime` -| `string` -| LastHeartbeatTime is the last time we got an update on a given condition - -| `lastTransitionTime` -| `string` -| LastTransitionTime is the last time the condition transit from one status to another - -| `message` -| `string` -| Message is a human-readable message indicating details about last transition. - -| `reason` -| `string` -| Reason is a one-word CamelCase reason for the condition's last transition. - -| `status` -| `string` -| Status is the status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type is the type of Subscription condition. - -|=== -..status.installPlanRef -Description:: - InstallPlanRef is a reference to the latest InstallPlan that contains the Subscription's current CSV. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status.installplan -Description:: - Install is a reference to the latest InstallPlan generated for the Subscription. DEPRECATED: InstallPlanRef - -Type:: - `object` - -Required:: - - `apiVersion` - - `kind` - - `name` - - `uuid` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| - -| `kind` -| `string` -| - -| `name` -| `string` -| - -| `uuid` -| `string` -| UID is a type that holds unique ID values, including UUIDs. Because we don't ONLY use UUIDs, this is an alias to string. Being a type captures intent and helps make sure that UIDs and names do not get conflated. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/operators.coreos.com/v1alpha1/subscriptions` -- `GET`: list objects of kind Subscription -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/subscriptions` -- `DELETE`: delete collection of Subscription -- `GET`: list objects of kind Subscription -- `POST`: create a Subscription -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/subscriptions/{name}` -- `DELETE`: delete a Subscription -- `GET`: read the specified Subscription -- `PATCH`: partially update the specified Subscription -- `PUT`: replace the specified Subscription -* `/apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/subscriptions/{name}/status` -- `GET`: read status of the specified Subscription -- `PATCH`: partially update status of the specified Subscription -- `PUT`: replace status of the specified Subscription - - -=== /apis/operators.coreos.com/v1alpha1/subscriptions - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Subscription - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#subscriptionlist-operators-coreos-com-v1alpha1[`SubscriptionList operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/subscriptions - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#subscriptionlist-operators-coreos-com-v1alpha1[`SubscriptionList operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 202 - Accepted -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/subscriptions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Subscription -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/operators.coreos.com/v1alpha1/namespaces/{namespace}/subscriptions/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Subscription -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Subscription - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 201 - Created -| xref:../operatorhub_apis/subscription-operators-coreos-com-v1alpha1.adoc#subscription-operators-coreos-com-v1alpha1[`Subscription operators.coreos.com/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/policy_apis/poddisruptionbudget-policy-v1beta1.adoc b/rest_api/policy_apis/poddisruptionbudget-policy-v1beta1.adoc deleted file mode 100644 index 0d630e5c223f..000000000000 --- a/rest_api/policy_apis/poddisruptionbudget-policy-v1beta1.adoc +++ /dev/null @@ -1,700 +0,0 @@ -[id="poddisruptionbudget-policy-v1beta1"] -= PodDisruptionBudget [policy/v1beta1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PodDisruptionBudget is an object to define the max disruption that can be caused to a collection of pods - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| PodDisruptionBudgetSpec is a description of a PodDisruptionBudget. - -| `status` -| `object` -| PodDisruptionBudgetStatus represents information about the status of a PodDisruptionBudget. Status may trail the actual state of a system. - -|=== -..spec -Description:: - PodDisruptionBudgetSpec is a description of a PodDisruptionBudget. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxUnavailable` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| An eviction is allowed if at most "maxUnavailable" pods selected by "selector" are unavailable after the eviction, i.e. even in absence of the evicted pod. For example, one can prevent all voluntary evictions by specifying 0. This is a mutually exclusive setting with "minAvailable". - -| `minAvailable` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| An eviction is allowed if at least "minAvailable" pods selected by "selector" will still be available after the eviction, i.e. even in the absence of the evicted pod. So for example you can prevent all voluntary evictions by specifying "100%". - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| Label query over pods whose evictions are managed by the disruption budget. - -|=== -..status -Description:: - PodDisruptionBudgetStatus represents information about the status of a PodDisruptionBudget. Status may trail the actual state of a system. - -Type:: - `object` - -Required:: - - `disruptionsAllowed` - - `currentHealthy` - - `desiredHealthy` - - `expectedPods` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `currentHealthy` -| `integer` -| current number of healthy pods - -| `desiredHealthy` -| `integer` -| minimum desired number of healthy pods - -| `disruptedPods` -| xref:../objects/index.adoc#time-meta-v1[`object (Time meta/v1)`] -| DisruptedPods contains information about pods whose eviction was processed by the API server eviction subresource handler but has not yet been observed by the PodDisruptionBudget controller. A pod will be in this map from the time when the API server processed the eviction request to the time when the pod is seen by PDB controller as having been marked for deletion (or after a timeout). The key in the map is the name of the pod and the value is the time when the API server processed the eviction request. If the deletion didn't occur and a pod is still there it will be removed from the list automatically by PodDisruptionBudget controller after some time. If everything goes smooth this map should be empty for the most of the time. Large number of entries in the map may indicate problems with pod deletions. - -| `disruptionsAllowed` -| `integer` -| Number of pod disruptions that are currently allowed. - -| `expectedPods` -| `integer` -| total number of pods counted by this disruption budget - -| `observedGeneration` -| `integer` -| Most recent generation observed when updating this PDB status. DisruptionsAllowed and other status information is valid only if observedGeneration equals to PDB's object generation. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/policy/v1beta1/poddisruptionbudgets` -- `GET`: list or watch objects of kind PodDisruptionBudget -* `/apis/policy/v1beta1/namespaces/{namespace}/poddisruptionbudgets` -- `DELETE`: delete collection of PodDisruptionBudget -- `GET`: list or watch objects of kind PodDisruptionBudget -- `POST`: create a PodDisruptionBudget -* `/apis/policy/v1beta1/namespaces/{namespace}/poddisruptionbudgets/{name}` -- `DELETE`: delete a PodDisruptionBudget -- `GET`: read the specified PodDisruptionBudget -- `PATCH`: partially update the specified PodDisruptionBudget -- `PUT`: replace the specified PodDisruptionBudget -* `/apis/policy/v1beta1/namespaces/{namespace}/poddisruptionbudgets/{name}/status` -- `GET`: read status of the specified PodDisruptionBudget -- `PATCH`: partially update status of the specified PodDisruptionBudget -- `PUT`: replace status of the specified PodDisruptionBudget - - -=== /apis/policy/v1beta1/poddisruptionbudgets - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PodDisruptionBudget - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#poddisruptionbudgetlist-policy-v1beta1[`PodDisruptionBudgetList policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/policy/v1beta1/namespaces/{namespace}/poddisruptionbudgets - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#poddisruptionbudgetlist-policy-v1beta1[`PodDisruptionBudgetList policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 201 - Created -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 202 - Accepted -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/policy/v1beta1/namespaces/{namespace}/poddisruptionbudgets/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodDisruptionBudget -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 201 - Created -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/policy/v1beta1/namespaces/{namespace}/poddisruptionbudgets/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodDisruptionBudget -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified PodDisruptionBudget - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified PodDisruptionBudget - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 201 - Created -| xref:../policy_apis/poddisruptionbudget-policy-v1beta1.adoc#poddisruptionbudget-policy-v1beta1[`PodDisruptionBudget policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/policy_apis/policy-apis-index.adoc b/rest_api/policy_apis/policy-apis-index.adoc deleted file mode 100644 index ac9b61fb26e2..000000000000 --- a/rest_api/policy_apis/policy-apis-index.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="policy-apis"] -= Policy APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== PodDisruptionBudget [policy/v1beta1] - -Description:: - PodDisruptionBudget is an object to define the max disruption that can be caused to a collection of pods - -Type:: - `object` - diff --git a/rest_api/project_apis/project-apis-index.adoc b/rest_api/project_apis/project-apis-index.adoc deleted file mode 100644 index f79057ddd504..000000000000 --- a/rest_api/project_apis/project-apis-index.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="project-apis"] -= Project APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== Project [project.openshift.io/v1] - -Description:: - Projects are the unit of isolation and collaboration in OpenShift. A project has one or more members, a quota on the resources that the project may consume, and the security controls on the resources in the project. Within a project, members may have different roles - project administrators can set membership, editors can create and manage the resources, and viewers can see but not access running containers. In a normal cluster project administrators are not able to alter their quotas - that is restricted to cluster administrators. - -Listing or watching projects will return only projects the user has the reader role on. - -An OpenShift project is an alternative representation of a Kubernetes namespace. Projects are exposed as editable to end users while namespaces are not. Direct creation of a project is typically restricted to administrators, while end users should use the requestproject resource. - -Type:: - `object` - -== ProjectRequest [project.openshift.io/v1] - -Description:: - ProjecRequest is the set of options necessary to fully qualify a project request - -Type:: - `object` - diff --git a/rest_api/project_apis/project-project-openshift-io-v1.adoc b/rest_api/project_apis/project-project-openshift-io-v1.adoc deleted file mode 100644 index 2ea0332ce4a3..000000000000 --- a/rest_api/project_apis/project-project-openshift-io-v1.adoc +++ /dev/null @@ -1,384 +0,0 @@ -[id="project-project-openshift-io-v1"] -= Project [project.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Projects are the unit of isolation and collaboration in OpenShift. A project has one or more members, a quota on the resources that the project may consume, and the security controls on the resources in the project. Within a project, members may have different roles - project administrators can set membership, editors can create and manage the resources, and viewers can see but not access running containers. In a normal cluster project administrators are not able to alter their quotas - that is restricted to cluster administrators. - -Listing or watching projects will return only projects the user has the reader role on. - -An OpenShift project is an alternative representation of a Kubernetes namespace. Projects are exposed as editable to end users while namespaces are not. Direct creation of a project is typically restricted to administrators, while end users should use the requestproject resource. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| ProjectSpec describes the attributes on a Project - -| `status` -| `object` -| ProjectStatus is information about the current status of a Project - -|=== -..spec -Description:: - ProjectSpec describes the attributes on a Project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `finalizers` -| `array (string)` -| Finalizers is an opaque list of values that must be empty to permanently remove object from storage - -|=== -..status -Description:: - ProjectStatus is information about the current status of a Project - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| xref:../objects/index.adoc#namespacecondition-core-v1[`array (NamespaceCondition core/v1)`] -| Represents the latest available observations of the project current state. - -| `phase` -| `string` -| Phase is the current lifecycle phase of the project - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/project.openshift.io/v1/projects` -- `GET`: list or watch objects of kind Project -- `POST`: create a Project -* `/apis/project.openshift.io/v1/projects/{name}` -- `DELETE`: delete a Project -- `GET`: read the specified Project -- `PATCH`: partially update the specified Project -- `PUT`: replace the specified Project - - -=== /apis/project.openshift.io/v1/projects - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#projectlist-project-openshift-io-v1[`ProjectList project.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| 201 - Created -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| 202 - Accepted -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/project.openshift.io/v1/projects/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Project -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Project - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Project - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| 201 - Created -| xref:../project_apis/project-project-openshift-io-v1.adoc#project-project-openshift-io-v1[`Project project.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/project_apis/projectrequest-project-openshift-io-v1.adoc b/rest_api/project_apis/projectrequest-project-openshift-io-v1.adoc deleted file mode 100644 index 2d4a5e4bad0d..000000000000 --- a/rest_api/project_apis/projectrequest-project-openshift-io-v1.adoc +++ /dev/null @@ -1,168 +0,0 @@ -[id="projectrequest-project-openshift-io-v1"] -= ProjectRequest [project.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ProjecRequest is the set of options necessary to fully qualify a project request - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `description` -| `string` -| Description is the description to apply to a project - -| `displayName` -| `string` -| DisplayName is the display name to apply to a project - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/project.openshift.io/v1/projectrequests` -- `GET`: list objects of kind ProjectRequest -- `POST`: create a ProjectRequest - - -=== /apis/project.openshift.io/v1/projectrequests - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ProjectRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ProjectRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../project_apis/projectrequest-project-openshift-io-v1.adoc#projectrequest-project-openshift-io-v1[`ProjectRequest project.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../project_apis/projectrequest-project-openshift-io-v1.adoc#projectrequest-project-openshift-io-v1[`ProjectRequest project.openshift.io/v1`] -| 201 - Created -| xref:../project_apis/projectrequest-project-openshift-io-v1.adoc#projectrequest-project-openshift-io-v1[`ProjectRequest project.openshift.io/v1`] -| 202 - Accepted -| xref:../project_apis/projectrequest-project-openshift-io-v1.adoc#projectrequest-project-openshift-io-v1[`ProjectRequest project.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc b/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc deleted file mode 100644 index 4c18fb77f8fe..000000000000 --- a/rest_api/provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc +++ /dev/null @@ -1,1742 +0,0 @@ -[id="baremetalhost-metal3-io-v1alpha1"] -= BareMetalHost [metal3.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - BareMetalHost is the Schema for the baremetalhosts API - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| BareMetalHostSpec defines the desired state of BareMetalHost - -| `status` -| `object` -| BareMetalHostStatus defines the observed state of BareMetalHost - -|=== -..spec -Description:: - BareMetalHostSpec defines the desired state of BareMetalHost - -Type:: - `object` - -Required:: - - `online` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bmc` -| `object` -| How do we connect to the BMC? - -| `bootMACAddress` -| `string` -| Which MAC address will PXE boot? This is optional for some types, but required for libvirt VMs driven by vbmc. - -| `bootMode` -| `string` -| Select the method of initializing the hardware during boot. Defaults to UEFI. - -| `consumerRef` -| `object` -| ConsumerRef can be used to store information about something that is using a host. When it is not empty, the host is considered "in use". - -| `description` -| `string` -| Description is a human-entered text used to help identify the host - -| `externallyProvisioned` -| `boolean` -| ExternallyProvisioned means something else is managing the image running on the host and the operator should only manage the power status and hardware inventory inspection. If the Image field is filled in, this field is ignored. - -| `hardwareProfile` -| `string` -| What is the name of the hardware profile for this host? It should only be necessary to set this when inspection cannot automatically determine the profile. - -| `image` -| `object` -| Image holds the details of the image to be provisioned. - -| `metaData` -| `object` -| MetaData holds the reference to the Secret containing host metadata (e.g. meta_data.json which is passed to Config Drive). - -| `networkData` -| `object` -| NetworkData holds the reference to the Secret containing network configuration (e.g content of network_data.json which is passed to Config Drive). - -| `online` -| `boolean` -| Should the server be online? - -| `rootDeviceHints` -| `object` -| Provide guidance about how to choose the device for the image being provisioned. - -| `taints` -| `array` -| Taints is the full, authoritative list of taints to apply to the corresponding Machine. This list will overwrite any modifications made to the Machine on an ongoing basis. - -| `taints[]` -| `object` -| The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint. - -| `userData` -| `object` -| UserData holds the reference to the Secret containing the user data to be passed to the host before it boots. - -|=== -..spec.bmc -Description:: - How do we connect to the BMC? - -Type:: - `object` - -Required:: - - `address` - - `credentialsName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `address` -| `string` -| Address holds the URL for accessing the controller on the network. - -| `credentialsName` -| `string` -| The name of the secret containing the BMC credentials (requires keys "username" and "password"). - -| `disableCertificateVerification` -| `boolean` -| DisableCertificateVerification disables verification of server certificates when using HTTPS to connect to the BMC. This is required when the server certificate is self-signed, but is insecure because it allows a man-in-the-middle to intercept the connection. - -|=== -..spec.consumerRef -Description:: - ConsumerRef can be used to store information about something that is using a host. When it is not empty, the host is considered "in use". - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..spec.image -Description:: - Image holds the details of the image to be provisioned. - -Type:: - `object` - -Required:: - - `checksum` - - `url` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `checksum` -| `string` -| Checksum is the checksum for the image. - -| `checksumType` -| `string` -| ChecksumType is the checksum algorithm for the image. e.g md5, sha256, sha512 - -| `format` -| `string` -| DiskFormat contains the format of the image (raw, qcow2, ...) Needs to be set to raw for raw images streaming - -| `url` -| `string` -| URL is a location of an image to deploy. - -|=== -..spec.metaData -Description:: - MetaData holds the reference to the Secret containing host metadata (e.g. meta_data.json which is passed to Config Drive). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is unique within a namespace to reference a secret resource. - -| `namespace` -| `string` -| Namespace defines the space within which the secret name must be unique. - -|=== -..spec.networkData -Description:: - NetworkData holds the reference to the Secret containing network configuration (e.g content of network_data.json which is passed to Config Drive). - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is unique within a namespace to reference a secret resource. - -| `namespace` -| `string` -| Namespace defines the space within which the secret name must be unique. - -|=== -..spec.rootDeviceHints -Description:: - Provide guidance about how to choose the device for the image being provisioned. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `deviceName` -| `string` -| A Linux device name like "/dev/vda". The hint must match the actual value exactly. - -| `hctl` -| `string` -| A SCSI bus address like 0:0:0:0. The hint must match the actual value exactly. - -| `minSizeGigabytes` -| `integer` -| The minimum size of the device in Gigabytes. - -| `model` -| `string` -| A vendor-specific device identifier. The hint can be a substring of the actual value. - -| `rotational` -| `boolean` -| True if the device should use spinning media, false otherwise. - -| `serialNumber` -| `string` -| Device serial number. The hint must match the actual value exactly. - -| `vendor` -| `string` -| The name of the vendor or manufacturer of the device. The hint can be a substring of the actual value. - -| `wwn` -| `string` -| Unique storage identifier. The hint must match the actual value exactly. - -| `wwnVendorExtension` -| `string` -| Unique vendor storage identifier. The hint must match the actual value exactly. - -| `wwnWithExtension` -| `string` -| Unique storage identifier with the vendor extension appended. The hint must match the actual value exactly. - -|=== -..spec.taints -Description:: - Taints is the full, authoritative list of taints to apply to the corresponding Machine. This list will overwrite any modifications made to the Machine on an ongoing basis. - -Type:: - `array` - - - - -..spec.taints[] -Description:: - The node this Taint is attached to has the "effect" on any pod that does not tolerate the Taint. - -Type:: - `object` - -Required:: - - `effect` - - `key` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `effect` -| `string` -| Required. The effect of the taint on pods that do not tolerate the taint. Valid effects are NoSchedule, PreferNoSchedule and NoExecute. - -| `key` -| `string` -| Required. The taint key to be applied to a node. - -| `timeAdded` -| `string` -| TimeAdded represents the time at which the taint was added. It is only written for NoExecute taints. - -| `value` -| `string` -| Required. The taint value corresponding to the taint key. - -|=== -..spec.userData -Description:: - UserData holds the reference to the Secret containing the user data to be passed to the host before it boots. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is unique within a namespace to reference a secret resource. - -| `namespace` -| `string` -| Namespace defines the space within which the secret name must be unique. - -|=== -..status -Description:: - BareMetalHostStatus defines the observed state of BareMetalHost - -Type:: - `object` - -Required:: - - `errorCount` - - `errorMessage` - - `hardwareProfile` - - `operationHistory` - - `operationalStatus` - - `poweredOn` - - `provisioning` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `errorCount` -| `integer` -| ErrorCount records how many times the host has encoutered an error since the last successful operation - -| `errorMessage` -| `string` -| the last error message reported by the provisioning subsystem - -| `errorType` -| `string` -| ErrorType indicates the type of failure encountered when the OperationalStatus is OperationalStatusError - -| `goodCredentials` -| `object` -| the last credentials we were able to validate as working - -| `hardware` -| `object` -| The hardware discovered to exist on the host. - -| `hardwareProfile` -| `string` -| The name of the profile matching the hardware details. - -| `lastUpdated` -| `string` -| LastUpdated identifies when this status was last observed. - -| `operationHistory` -| `object` -| OperationHistory holds information about operations performed on this host. - -| `operationalStatus` -| `string` -| OperationalStatus holds the status of the host - -| `poweredOn` -| `boolean` -| indicator for whether or not the host is powered on - -| `provisioning` -| `object` -| Information tracked by the provisioner. - -| `triedCredentials` -| `object` -| the last credentials we sent to the provisioning backend - -|=== -..status.goodCredentials -Description:: - the last credentials we were able to validate as working - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `credentials` -| `object` -| SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace - -| `credentialsVersion` -| `string` -| - -|=== -..status.goodCredentials.credentials -Description:: - SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is unique within a namespace to reference a secret resource. - -| `namespace` -| `string` -| Namespace defines the space within which the secret name must be unique. - -|=== -..status.hardware -Description:: - The hardware discovered to exist on the host. - -Type:: - `object` - -Required:: - - `cpu` - - `firmware` - - `hostname` - - `nics` - - `ramMebibytes` - - `storage` - - `systemVendor` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cpu` -| `object` -| CPU describes one processor on the host. - -| `firmware` -| `object` -| Firmware describes the firmware on the host. - -| `hostname` -| `string` -| - -| `nics` -| `array` -| - -| `nics[]` -| `object` -| NIC describes one network interface on the host. - -| `ramMebibytes` -| `integer` -| - -| `storage` -| `array` -| - -| `storage[]` -| `object` -| Storage describes one storage device (disk, SSD, etc.) on the host. - -| `systemVendor` -| `object` -| HardwareSystemVendor stores details about the whole hardware system. - -|=== -..status.hardware.cpu -Description:: - CPU describes one processor on the host. - -Type:: - `object` - -Required:: - - `arch` - - `clockMegahertz` - - `count` - - `flags` - - `model` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `arch` -| `string` -| - -| `clockMegahertz` -| `number` -| ClockSpeed is a clock speed in MHz - -| `count` -| `integer` -| - -| `flags` -| `array (string)` -| - -| `model` -| `string` -| - -|=== -..status.hardware.firmware -Description:: - Firmware describes the firmware on the host. - -Type:: - `object` - -Required:: - - `bios` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bios` -| `object` -| The BIOS for this firmware - -|=== -..status.hardware.firmware.bios -Description:: - The BIOS for this firmware - -Type:: - `object` - -Required:: - - `date` - - `vendor` - - `version` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `date` -| `string` -| The release/build date for this BIOS - -| `vendor` -| `string` -| The vendor name for this BIOS - -| `version` -| `string` -| The version of the BIOS - -|=== -..status.hardware.nics -Description:: - - -Type:: - `array` - - - - -..status.hardware.nics[] -Description:: - NIC describes one network interface on the host. - -Type:: - `object` - -Required:: - - `ip` - - `mac` - - `model` - - `name` - - `pxe` - - `speedGbps` - - `vlanId` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ip` -| `string` -| The IP address of the device - -| `mac` -| `string` -| The device MAC addr - -| `model` -| `string` -| The name of the model, e.g. "virt-io" - -| `name` -| `string` -| The name of the NIC, e.g. "nic-1" - -| `pxe` -| `boolean` -| Whether the NIC is PXE Bootable - -| `speedGbps` -| `integer` -| The speed of the device - -| `vlanId` -| `integer` -| The untagged VLAN ID - -| `vlans` -| `array` -| The VLANs available - -| `vlans[]` -| `object` -| VLAN represents the name and ID of a VLAN - -|=== -..status.hardware.nics[].vlans -Description:: - The VLANs available - -Type:: - `array` - - - - -..status.hardware.nics[].vlans[] -Description:: - VLAN represents the name and ID of a VLAN - -Type:: - `object` - -Required:: - - `id` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `id` -| `integer` -| VLANID is a 12-bit 802.1Q VLAN identifier - -| `name` -| `string` -| - -|=== -..status.hardware.storage -Description:: - - -Type:: - `array` - - - - -..status.hardware.storage[] -Description:: - Storage describes one storage device (disk, SSD, etc.) on the host. - -Type:: - `object` - -Required:: - - `name` - - `rotational` - - `serialNumber` - - `sizeBytes` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hctl` -| `string` -| The SCSI location of the device - -| `model` -| `string` -| Hardware model - -| `name` -| `string` -| A name for the disk, e.g. "disk 1 (boot)" - -| `rotational` -| `boolean` -| Whether this disk represents rotational storage - -| `serialNumber` -| `string` -| The serial number of the device - -| `sizeBytes` -| `integer` -| The size of the disk in Bytes - -| `vendor` -| `string` -| The name of the vendor of the device - -| `wwn` -| `string` -| The WWN of the device - -| `wwnVendorExtension` -| `string` -| The WWN Vendor extension of the device - -| `wwnWithExtension` -| `string` -| The WWN with the extension - -|=== -..status.hardware.systemVendor -Description:: - HardwareSystemVendor stores details about the whole hardware system. - -Type:: - `object` - -Required:: - - `manufacturer` - - `productName` - - `serialNumber` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `manufacturer` -| `string` -| - -| `productName` -| `string` -| - -| `serialNumber` -| `string` -| - -|=== -..status.operationHistory -Description:: - OperationHistory holds information about operations performed on this host. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `deprovision` -| `object` -| OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics. - -| `inspect` -| `object` -| OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics. - -| `provision` -| `object` -| OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics. - -| `register` -| `object` -| OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics. - -|=== -..status.operationHistory.deprovision -Description:: - OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `end` -| `` -| - -| `start` -| `` -| - -|=== -..status.operationHistory.inspect -Description:: - OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `end` -| `` -| - -| `start` -| `` -| - -|=== -..status.operationHistory.provision -Description:: - OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `end` -| `` -| - -| `start` -| `` -| - -|=== -..status.operationHistory.register -Description:: - OperationMetric contains metadata about an operation (inspection, provisioning, etc.) used for tracking metrics. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `end` -| `` -| - -| `start` -| `` -| - -|=== -..status.provisioning -Description:: - Information tracked by the provisioner. - -Type:: - `object` - -Required:: - - `ID` - - `state` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ID` -| `string` -| The machine's UUID from the underlying provisioning tool - -| `bootMode` -| `string` -| BootMode indicates the boot mode used to provision the node - -| `image` -| `object` -| Image holds the details of the last image successfully provisioned to the host. - -| `rootDeviceHints` -| `object` -| The RootDevicehints set by the user - -| `state` -| `string` -| An indiciator for what the provisioner is doing with the host. - -|=== -..status.provisioning.image -Description:: - Image holds the details of the last image successfully provisioned to the host. - -Type:: - `object` - -Required:: - - `checksum` - - `url` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `checksum` -| `string` -| Checksum is the checksum for the image. - -| `checksumType` -| `string` -| ChecksumType is the checksum algorithm for the image. e.g md5, sha256, sha512 - -| `format` -| `string` -| DiskFormat contains the format of the image (raw, qcow2, ...) Needs to be set to raw for raw images streaming - -| `url` -| `string` -| URL is a location of an image to deploy. - -|=== -..status.provisioning.rootDeviceHints -Description:: - The RootDevicehints set by the user - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `deviceName` -| `string` -| A Linux device name like "/dev/vda". The hint must match the actual value exactly. - -| `hctl` -| `string` -| A SCSI bus address like 0:0:0:0. The hint must match the actual value exactly. - -| `minSizeGigabytes` -| `integer` -| The minimum size of the device in Gigabytes. - -| `model` -| `string` -| A vendor-specific device identifier. The hint can be a substring of the actual value. - -| `rotational` -| `boolean` -| True if the device should use spinning media, false otherwise. - -| `serialNumber` -| `string` -| Device serial number. The hint must match the actual value exactly. - -| `vendor` -| `string` -| The name of the vendor or manufacturer of the device. The hint can be a substring of the actual value. - -| `wwn` -| `string` -| Unique storage identifier. The hint must match the actual value exactly. - -| `wwnVendorExtension` -| `string` -| Unique vendor storage identifier. The hint must match the actual value exactly. - -| `wwnWithExtension` -| `string` -| Unique storage identifier with the vendor extension appended. The hint must match the actual value exactly. - -|=== -..status.triedCredentials -Description:: - the last credentials we sent to the provisioning backend - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `credentials` -| `object` -| SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace - -| `credentialsVersion` -| `string` -| - -|=== -..status.triedCredentials.credentials -Description:: - SecretReference represents a Secret Reference. It has enough information to retrieve secret in any namespace - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is unique within a namespace to reference a secret resource. - -| `namespace` -| `string` -| Namespace defines the space within which the secret name must be unique. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/metal3.io/v1alpha1/baremetalhosts` -- `GET`: list objects of kind BareMetalHost -* `/apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts` -- `DELETE`: delete collection of BareMetalHost -- `GET`: list objects of kind BareMetalHost -- `POST`: create a BareMetalHost -* `/apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts/{name}` -- `DELETE`: delete a BareMetalHost -- `GET`: read the specified BareMetalHost -- `PATCH`: partially update the specified BareMetalHost -- `PUT`: replace the specified BareMetalHost -* `/apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts/{name}/status` -- `GET`: read status of the specified BareMetalHost -- `PATCH`: partially update status of the specified BareMetalHost -- `PUT`: replace status of the specified BareMetalHost - - -=== /apis/metal3.io/v1alpha1/baremetalhosts - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind BareMetalHost - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#baremetalhostlist-metal3-io-v1alpha1[`BareMetalHostList metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#baremetalhostlist-metal3-io-v1alpha1[`BareMetalHostList metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 201 - Created -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 202 - Accepted -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the BareMetalHost -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 201 - Created -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/metal3.io/v1alpha1/namespaces/{namespace}/baremetalhosts/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the BareMetalHost -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified BareMetalHost - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 201 - Created -| xref:../provisioning_apis/baremetalhost-metal3-io-v1alpha1.adoc#baremetalhost-metal3-io-v1alpha1[`BareMetalHost metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/provisioning_apis/provisioning-apis-index.adoc b/rest_api/provisioning_apis/provisioning-apis-index.adoc deleted file mode 100644 index 988d040e580b..000000000000 --- a/rest_api/provisioning_apis/provisioning-apis-index.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="provisioning-apis"] -= Provisioning APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== BareMetalHost [metal3.io/v1alpha1] - -Description:: - BareMetalHost is the Schema for the baremetalhosts API - -Type:: - `object` - -== Provisioning [metal3.io/v1alpha1] - -Description:: - Provisioning contains configuration used by the Provisioning service (Ironic) to provision baremetal hosts. Provisioning is created by the OpenShift installer using admin or user provided information about the provisioning network and the NIC on the server that can be used to PXE boot it. This CR is a singleton, created by the installer and currently only consumed by the cluster-baremetal-operator to bring up and update containers in a metal3 cluster. - -Type:: - `object` - diff --git a/rest_api/provisioning_apis/provisioning-metal3-io-v1alpha1.adoc b/rest_api/provisioning_apis/provisioning-metal3-io-v1alpha1.adoc deleted file mode 100644 index 086362b6c710..000000000000 --- a/rest_api/provisioning_apis/provisioning-metal3-io-v1alpha1.adoc +++ /dev/null @@ -1,719 +0,0 @@ -[id="provisioning-metal3-io-v1alpha1"] -= Provisioning [metal3.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Provisioning contains configuration used by the Provisioning service (Ironic) to provision baremetal hosts. Provisioning is created by the OpenShift installer using admin or user provided information about the provisioning network and the NIC on the server that can be used to PXE boot it. This CR is a singleton, created by the installer and currently only consumed by the cluster-baremetal-operator to bring up and update containers in a metal3 cluster. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ProvisioningSpec defines the desired state of Provisioning - -| `status` -| `object` -| ProvisioningStatus defines the observed state of Provisioning - -|=== -..spec -Description:: - ProvisioningSpec defines the desired state of Provisioning - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `provisioningDHCPExternal` -| `boolean` -| ProvisioningDHCPExternal indicates whether the DHCP server for IP addresses in the provisioning DHCP range is present within the metal3 cluster or external to it. This field is being deprecated in favor of provisioningNetwork. - -| `provisioningDHCPRange` -| `string` -| ProvisioningDHCPRange needs to be interpreted along with ProvisioningDHCPExternal. If the value of provisioningDHCPExternal is set to False, then ProvisioningDHCPRange represents the range of IP addresses that the DHCP server running within the metal3 cluster can use while provisioning baremetal servers. If the value of ProvisioningDHCPExternal is set to True, then the value of ProvisioningDHCPRange will be ignored. When the value of ProvisioningDHCPExternal is set to False, indicating an internal DHCP server and the value of ProvisioningDHCPRange is not set, then the DHCP range is taken to be the default range which goes from .10 to .100 of the ProvisioningNetworkCIDR. This is the only value in all of the Provisioning configuration that can be changed after the installer has created the CR. This value needs to be two comma sererated IP addresses within the ProvisioningNetworkCIDR where the 1st address represents the start of the range and the 2nd address represents the last usable address in the range. - -| `provisioningIP` -| `string` -| ProvisioningIP is the IP address assigned to the provisioningInterface of the baremetal server. This IP address should be within the provisioning subnet, and outside of the DHCP range. - -| `provisioningInterface` -| `string` -| ProvisioningInterface is the name of the network interface on a baremetal server to the provisioning network. It can have values like eth1 or ens3. - -| `provisioningNetwork` -| `string` -| ProvisioningNetwork provides a way to indicate the state of the underlying network configuration for the provisioning network. This field can have one of the following values - `Managed`- when the provisioning network is completely managed by the Baremetal IPI solution. `Unmanaged`- when the provsioning network is present and used but the user is responsible for managing DHCP. Virtual media provisioning is recommended but PXE is still available if required. `Disabled`- when the provisioning network is fully disabled. User can bring up the baremetal cluster using virtual media or assisted installation. If using metal3 for power management, BMCs must be accessible from the machine networks. User should provide two IPs on the external network that would be used for provisioning services. - -| `provisioningNetworkCIDR` -| `string` -| ProvisioningNetworkCIDR is the network on which the baremetal nodes are provisioned. The provisioningIP and the IPs in the dhcpRange all come from within this network. - -| `provisioningOSDownloadURL` -| `string` -| ProvisioningOSDownloadURL is the location from which the OS Image used to boot baremetal host machines can be downloaded by the metal3 cluster. - -|=== -..status -Description:: - ProvisioningStatus defines the observed state of Provisioning - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions is a list of conditions and their status - -| `conditions[]` -| `object` -| OperatorCondition is just the standard condition fields. - -| `generations` -| `array` -| generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -| `generations[]` -| `object` -| GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -| `observedGeneration` -| `integer` -| observedGeneration is the last generation change you've dealt with - -| `readyReplicas` -| `integer` -| readyReplicas indicates how many replicas are ready and at the desired state - -| `version` -| `string` -| version is the level this availability applies to - -|=== -..status.conditions -Description:: - conditions is a list of conditions and their status - -Type:: - `array` - - - - -..status.conditions[] -Description:: - OperatorCondition is just the standard condition fields. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| `string` -| - -| `message` -| `string` -| - -| `reason` -| `string` -| - -| `status` -| `string` -| - -| `type` -| `string` -| - -|=== -..status.generations -Description:: - generations are used to determine when an item needs to be reconciled or has changed in a way that needs a reaction. - -Type:: - `array` - - - - -..status.generations[] -Description:: - GenerationStatus keeps track of the generation for a given resource so that decisions about forced updates can be made. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| group is the group of the thing you're tracking - -| `hash` -| `string` -| hash is an optional field set for resources without generation that are content sensitive like secrets and configmaps - -| `lastGeneration` -| `integer` -| lastGeneration is the last generation of the workload controller involved - -| `name` -| `string` -| name is the name of the thing you're tracking - -| `namespace` -| `string` -| namespace is where the thing you're tracking is - -| `resource` -| `string` -| resource is the resource type of the thing you're tracking - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/metal3.io/v1alpha1/provisionings` -- `DELETE`: delete collection of Provisioning -- `GET`: list objects of kind Provisioning -- `POST`: create a Provisioning -* `/apis/metal3.io/v1alpha1/provisionings/{name}` -- `DELETE`: delete a Provisioning -- `GET`: read the specified Provisioning -- `PATCH`: partially update the specified Provisioning -- `PUT`: replace the specified Provisioning -* `/apis/metal3.io/v1alpha1/provisionings/{name}/status` -- `GET`: read status of the specified Provisioning -- `PATCH`: partially update status of the specified Provisioning -- `PUT`: replace status of the specified Provisioning - - -=== /apis/metal3.io/v1alpha1/provisionings - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#provisioninglist-metal3-io-v1alpha1[`ProvisioningList metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 201 - Created -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 202 - Accepted -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/metal3.io/v1alpha1/provisionings/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Provisioning -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 201 - Created -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/metal3.io/v1alpha1/provisionings/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Provisioning -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Provisioning - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 201 - Created -| xref:../provisioning_apis/provisioning-metal3-io-v1alpha1.adoc#provisioning-metal3-io-v1alpha1[`Provisioning metal3.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc b/rest_api/rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc deleted file mode 100644 index 8bd3ed4d4651..000000000000 --- a/rest_api/rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc +++ /dev/null @@ -1,482 +0,0 @@ -[id="clusterrole-rbac-authorization-k8s-io-v1"] -= ClusterRole [rbac.authorization.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterRole is a cluster level, logical grouping of PolicyRules that can be referenced as a unit by a RoleBinding or ClusterRoleBinding. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `aggregationRule` -| `object` -| AggregationRule describes how to locate ClusterRoles to aggregate into the ClusterRole - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. - -| `rules` -| `array` -| Rules holds all the PolicyRules for this ClusterRole - -| `rules[]` -| `object` -| PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -|=== -..aggregationRule -Description:: - AggregationRule describes how to locate ClusterRoles to aggregate into the ClusterRole - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `clusterRoleSelectors` -| xref:../objects/index.adoc#labelselector-meta-v1[`array (LabelSelector meta/v1)`] -| ClusterRoleSelectors holds a list of selectors which will be used to find ClusterRoles and create the rules. If any of the selectors match, then the ClusterRole's permissions will be added - -|=== -..rules -Description:: - Rules holds all the PolicyRules for this ClusterRole - -Type:: - `array` - - - - -..rules[] -Description:: - PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -Type:: - `object` - -Required:: - - `verbs` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against one of the enumerated resources in any API group will be allowed. - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path Since non-resource URLs are not namespaced, this field is only applicable for ClusterRoles referenced from a ClusterRoleBinding. Rules can either apply to API resources (such as "pods" or "secrets") or non-resource URL paths (such as "/api"), but not both. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. ResourceAll represents all resources. - -| `verbs` -| `array (string)` -| Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule. VerbAll represents all kinds. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/rbac.authorization.k8s.io/v1/clusterroles` -- `DELETE`: delete collection of ClusterRole -- `GET`: list or watch objects of kind ClusterRole -- `POST`: create a ClusterRole -* `/apis/rbac.authorization.k8s.io/v1/clusterroles/{name}` -- `DELETE`: delete a ClusterRole -- `GET`: read the specified ClusterRole -- `PATCH`: partially update the specified ClusterRole -- `PUT`: replace the specified ClusterRole - - -=== /apis/rbac.authorization.k8s.io/v1/clusterroles - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterrolelist-rbac-authorization-k8s-io-v1[`ClusterRoleList rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| 201 - Created -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| 202 - Accepted -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/rbac.authorization.k8s.io/v1/clusterroles/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterRole -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterRole - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| 201 - Created -| xref:../rbac_apis/clusterrole-rbac-authorization-k8s-io-v1.adoc#clusterrole-rbac-authorization-k8s-io-v1[`ClusterRole rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc b/rest_api/rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc deleted file mode 100644 index 13e5e88e2d0d..000000000000 --- a/rest_api/rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc +++ /dev/null @@ -1,493 +0,0 @@ -[id="clusterrolebinding-rbac-authorization-k8s-io-v1"] -= ClusterRoleBinding [rbac.authorization.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterRoleBinding references a ClusterRole, but not contain it. It can reference a ClusterRole in the global namespace, and adds who information via Subject. - -Type:: - `object` - -Required:: - - `roleRef` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. - -| `roleRef` -| `object` -| RoleRef contains information that points to the role being used - -| `subjects` -| `array` -| Subjects holds references to the objects the role applies to. - -| `subjects[]` -| `object` -| Subject contains a reference to the object or user identities a role binding applies to. This can either hold a direct API object reference, or a value for non-objects such as user and group names. - -|=== -..roleRef -Description:: - RoleRef contains information that points to the role being used - -Type:: - `object` - -Required:: - - `apiGroup` - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup is the group for the resource being referenced - -| `kind` -| `string` -| Kind is the type of resource being referenced - -| `name` -| `string` -| Name is the name of resource being referenced - -|=== -..subjects -Description:: - Subjects holds references to the objects the role applies to. - -Type:: - `array` - - - - -..subjects[] -Description:: - Subject contains a reference to the object or user identities a role binding applies to. This can either hold a direct API object reference, or a value for non-objects such as user and group names. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup holds the API group of the referenced subject. Defaults to "" for ServiceAccount subjects. Defaults to "rbac.authorization.k8s.io" for User and Group subjects. - -| `kind` -| `string` -| Kind of object being referenced. Values defined by this API group are "User", "Group", and "ServiceAccount". If the Authorizer does not recognized the kind value, the Authorizer should report an error. - -| `name` -| `string` -| Name of the object being referenced. - -| `namespace` -| `string` -| Namespace of the referenced object. If the object kind is non-namespace, such as "User" or "Group", and this value is not empty the Authorizer should report an error. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/rbac.authorization.k8s.io/v1/clusterrolebindings` -- `DELETE`: delete collection of ClusterRoleBinding -- `GET`: list or watch objects of kind ClusterRoleBinding -- `POST`: create a ClusterRoleBinding -* `/apis/rbac.authorization.k8s.io/v1/clusterrolebindings/{name}` -- `DELETE`: delete a ClusterRoleBinding -- `GET`: read the specified ClusterRoleBinding -- `PATCH`: partially update the specified ClusterRoleBinding -- `PUT`: replace the specified ClusterRoleBinding - - -=== /apis/rbac.authorization.k8s.io/v1/clusterrolebindings - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterrolebindinglist-rbac-authorization-k8s-io-v1[`ClusterRoleBindingList rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| 201 - Created -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| 202 - Accepted -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/rbac.authorization.k8s.io/v1/clusterrolebindings/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterRoleBinding -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterRoleBinding - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| 201 - Created -| xref:../rbac_apis/clusterrolebinding-rbac-authorization-k8s-io-v1.adoc#clusterrolebinding-rbac-authorization-k8s-io-v1[`ClusterRoleBinding rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/rbac_apis/rbac-apis-index.adoc b/rest_api/rbac_apis/rbac-apis-index.adoc deleted file mode 100644 index 2c9c11149e1f..000000000000 --- a/rest_api/rbac_apis/rbac-apis-index.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="rbac-apis"] -= RBAC APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== ClusterRoleBinding [rbac.authorization.k8s.io/v1] - -Description:: - ClusterRoleBinding references a ClusterRole, but not contain it. It can reference a ClusterRole in the global namespace, and adds who information via Subject. - -Type:: - `object` - -== ClusterRole [rbac.authorization.k8s.io/v1] - -Description:: - ClusterRole is a cluster level, logical grouping of PolicyRules that can be referenced as a unit by a RoleBinding or ClusterRoleBinding. - -Type:: - `object` - -== RoleBinding [rbac.authorization.k8s.io/v1] - -Description:: - RoleBinding references a role, but does not contain it. It can reference a Role in the same namespace or a ClusterRole in the global namespace. It adds who information via Subjects and namespace information by which namespace it exists in. RoleBindings in a given namespace only have effect in that namespace. - -Type:: - `object` - -== Role [rbac.authorization.k8s.io/v1] - -Description:: - Role is a namespaced, logical grouping of PolicyRules that can be referenced as a unit by a RoleBinding. - -Type:: - `object` - diff --git a/rest_api/rbac_apis/role-rbac-authorization-k8s-io-v1.adoc b/rest_api/rbac_apis/role-rbac-authorization-k8s-io-v1.adoc deleted file mode 100644 index 9d3d1725c247..000000000000 --- a/rest_api/rbac_apis/role-rbac-authorization-k8s-io-v1.adoc +++ /dev/null @@ -1,537 +0,0 @@ -[id="role-rbac-authorization-k8s-io-v1"] -= Role [rbac.authorization.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Role is a namespaced, logical grouping of PolicyRules that can be referenced as a unit by a RoleBinding. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. - -| `rules` -| `array` -| Rules holds all the PolicyRules for this Role - -| `rules[]` -| `object` -| PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -|=== -..rules -Description:: - Rules holds all the PolicyRules for this Role - -Type:: - `array` - - - - -..rules[] -Description:: - PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -Type:: - `object` - -Required:: - - `verbs` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If multiple API groups are specified, any action requested against one of the enumerated resources in any API group will be allowed. - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path Since non-resource URLs are not namespaced, this field is only applicable for ClusterRoles referenced from a ClusterRoleBinding. Rules can either apply to API resources (such as "pods" or "secrets") or non-resource URL paths (such as "/api"), but not both. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. ResourceAll represents all resources. - -| `verbs` -| `array (string)` -| Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule. VerbAll represents all kinds. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/rbac.authorization.k8s.io/v1/roles` -- `GET`: list or watch objects of kind Role -* `/apis/rbac.authorization.k8s.io/v1/namespaces/{namespace}/roles` -- `DELETE`: delete collection of Role -- `GET`: list or watch objects of kind Role -- `POST`: create a Role -* `/apis/rbac.authorization.k8s.io/v1/namespaces/{namespace}/roles/{name}` -- `DELETE`: delete a Role -- `GET`: read the specified Role -- `PATCH`: partially update the specified Role -- `PUT`: replace the specified Role - - -=== /apis/rbac.authorization.k8s.io/v1/roles - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Role - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolelist-rbac-authorization-k8s-io-v1[`RoleList rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/rbac.authorization.k8s.io/v1/namespaces/{namespace}/roles - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolelist-rbac-authorization-k8s-io-v1[`RoleList rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| 201 - Created -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| 202 - Accepted -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/rbac.authorization.k8s.io/v1/namespaces/{namespace}/roles/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Role -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Role - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| 201 - Created -| xref:../rbac_apis/role-rbac-authorization-k8s-io-v1.adoc#role-rbac-authorization-k8s-io-v1[`Role rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc b/rest_api/rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc deleted file mode 100644 index 441b794ea581..000000000000 --- a/rest_api/rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc +++ /dev/null @@ -1,571 +0,0 @@ -[id="rolebinding-rbac-authorization-k8s-io-v1"] -= RoleBinding [rbac.authorization.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - RoleBinding references a role, but does not contain it. It can reference a Role in the same namespace or a ClusterRole in the global namespace. It adds who information via Subjects and namespace information by which namespace it exists in. RoleBindings in a given namespace only have effect in that namespace. - -Type:: - `object` - -Required:: - - `roleRef` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. - -| `roleRef` -| `object` -| RoleRef contains information that points to the role being used - -| `subjects` -| `array` -| Subjects holds references to the objects the role applies to. - -| `subjects[]` -| `object` -| Subject contains a reference to the object or user identities a role binding applies to. This can either hold a direct API object reference, or a value for non-objects such as user and group names. - -|=== -..roleRef -Description:: - RoleRef contains information that points to the role being used - -Type:: - `object` - -Required:: - - `apiGroup` - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup is the group for the resource being referenced - -| `kind` -| `string` -| Kind is the type of resource being referenced - -| `name` -| `string` -| Name is the name of resource being referenced - -|=== -..subjects -Description:: - Subjects holds references to the objects the role applies to. - -Type:: - `array` - - - - -..subjects[] -Description:: - Subject contains a reference to the object or user identities a role binding applies to. This can either hold a direct API object reference, or a value for non-objects such as user and group names. - -Type:: - `object` - -Required:: - - `kind` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroup` -| `string` -| APIGroup holds the API group of the referenced subject. Defaults to "" for ServiceAccount subjects. Defaults to "rbac.authorization.k8s.io" for User and Group subjects. - -| `kind` -| `string` -| Kind of object being referenced. Values defined by this API group are "User", "Group", and "ServiceAccount". If the Authorizer does not recognized the kind value, the Authorizer should report an error. - -| `name` -| `string` -| Name of the object being referenced. - -| `namespace` -| `string` -| Namespace of the referenced object. If the object kind is non-namespace, such as "User" or "Group", and this value is not empty the Authorizer should report an error. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/rbac.authorization.k8s.io/v1/rolebindings` -- `GET`: list or watch objects of kind RoleBinding -* `/apis/rbac.authorization.k8s.io/v1/namespaces/{namespace}/rolebindings` -- `DELETE`: delete collection of RoleBinding -- `GET`: list or watch objects of kind RoleBinding -- `POST`: create a RoleBinding -* `/apis/rbac.authorization.k8s.io/v1/namespaces/{namespace}/rolebindings/{name}` -- `DELETE`: delete a RoleBinding -- `GET`: read the specified RoleBinding -- `PATCH`: partially update the specified RoleBinding -- `PUT`: replace the specified RoleBinding - - -=== /apis/rbac.authorization.k8s.io/v1/rolebindings - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind RoleBinding - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolebindinglist-rbac-authorization-k8s-io-v1[`RoleBindingList rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/rbac.authorization.k8s.io/v1/namespaces/{namespace}/rolebindings - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolebindinglist-rbac-authorization-k8s-io-v1[`RoleBindingList rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| 201 - Created -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| 202 - Accepted -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/rbac.authorization.k8s.io/v1/namespaces/{namespace}/rolebindings/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the RoleBinding -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified RoleBinding - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| 201 - Created -| xref:../rbac_apis/rolebinding-rbac-authorization-k8s-io-v1.adoc#rolebinding-rbac-authorization-k8s-io-v1[`RoleBinding rbac.authorization.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/role_apis/clusterrole-authorization-openshift-io-v1.adoc b/rest_api/role_apis/clusterrole-authorization-openshift-io-v1.adoc deleted file mode 100644 index e7283c1ded86..000000000000 --- a/rest_api/role_apis/clusterrole-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,396 +0,0 @@ -[id="clusterrole-authorization-openshift-io-v1"] -= ClusterRole [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterRole is a logical grouping of PolicyRules that can be referenced as a unit by ClusterRoleBindings. - -Type:: - `object` - -Required:: - - `rules` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `aggregationRule` -| xref:../objects/index.adoc#aggregationrule-rbac-authorization-k8s-io-v1[`AggregationRule rbac.authorization.k8s.io/v1`] -| AggregationRule is an optional field that describes how to build the Rules for this ClusterRole. If AggregationRule is set, then the Rules are controller managed and direct changes to Rules will be stomped by the controller. - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `rules` -| `array` -| Rules holds all the PolicyRules for this ClusterRole - -| `rules[]` -| `object` -| PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -|=== -..rules -Description:: - Rules holds all the PolicyRules for this ClusterRole - -Type:: - `array` - - - - -..rules[] -Description:: - PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -Type:: - `object` - -Required:: - - `verbs` - - `resources` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If this field is empty, then both kubernetes and origin API groups are assumed. That means that if an action is requested against one of the enumerated resources in either the kubernetes or the origin API group, the request will be allowed - -| `attributeRestrictions` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| AttributeRestrictions will vary depending on what the Authorizer/AuthorizationAttributeBuilder pair supports. If the Authorizer does not recognize how to handle the AttributeRestrictions, the Authorizer should report an error. - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLsSlice is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path This name is intentionally different than the internal type so that the DefaultConvert works nicely and because the ordering may be different. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. ResourceAll represents all resources. - -| `verbs` -| `array (string)` -| Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule. VerbAll represents all kinds. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/clusterroles` -- `GET`: list objects of kind ClusterRole -- `POST`: create a ClusterRole -* `/apis/authorization.openshift.io/v1/clusterroles/{name}` -- `DELETE`: delete a ClusterRole -- `GET`: read the specified ClusterRole -- `PATCH`: partially update the specified ClusterRole -- `PUT`: replace the specified ClusterRole - - -=== /apis/authorization.openshift.io/v1/clusterroles - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterrolelist-authorization-openshift-io-v1[`ClusterRoleList authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/authorization.openshift.io/v1/clusterroles/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterRole -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterRole - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterRole - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/clusterrole-authorization-openshift-io-v1.adoc#clusterrole-authorization-openshift-io-v1[`ClusterRole authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc b/rest_api/role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc deleted file mode 100644 index e62ab3dd840f..000000000000 --- a/rest_api/role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,349 +0,0 @@ -[id="clusterrolebinding-authorization-openshift-io-v1"] -= ClusterRoleBinding [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterRoleBinding references a ClusterRole, but not contain it. It can reference any ClusterRole in the same namespace or in the global namespace. It adds who information via (Users and Groups) OR Subjects and namespace information by which namespace it exists in. ClusterRoleBindings in a given namespace only have effect in that namespace (excepting the master namespace which has power in all namespaces). - -Type:: - `object` - -Required:: - - `subjects` - - `roleRef` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `groupNames` -| `array (string)` -| GroupNames holds all the groups directly bound to the role. This field should only be specified when supporting legacy clients and servers. See Subjects for further details. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `roleRef` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| RoleRef can only reference the current namespace and the global namespace. If the ClusterRoleRef cannot be resolved, the Authorizer must return an error. Since Policy is a singleton, this is sufficient knowledge to locate a role. - -| `subjects` -| xref:../objects/index.adoc#objectreference-core-v1[`array (ObjectReference core/v1)`] -| Subjects hold object references to authorize with this rule. This field is ignored if UserNames or GroupNames are specified to support legacy clients and servers. Thus newer clients that do not need to support backwards compatibility should send only fully qualified Subjects and should omit the UserNames and GroupNames fields. Clients that need to support backwards compatibility can use this field to build the UserNames and GroupNames. - -| `userNames` -| `array (string)` -| UserNames holds all the usernames directly bound to the role. This field should only be specified when supporting legacy clients and servers. See Subjects for further details. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/clusterrolebindings` -- `GET`: list objects of kind ClusterRoleBinding -- `POST`: create a ClusterRoleBinding -* `/apis/authorization.openshift.io/v1/clusterrolebindings/{name}` -- `DELETE`: delete a ClusterRoleBinding -- `GET`: read the specified ClusterRoleBinding -- `PATCH`: partially update the specified ClusterRoleBinding -- `PUT`: replace the specified ClusterRoleBinding - - -=== /apis/authorization.openshift.io/v1/clusterrolebindings - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterrolebindinglist-authorization-openshift-io-v1[`ClusterRoleBindingList authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/authorization.openshift.io/v1/clusterrolebindings/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterRoleBinding -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterRoleBinding - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterRoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/clusterrolebinding-authorization-openshift-io-v1.adoc#clusterrolebinding-authorization-openshift-io-v1[`ClusterRoleBinding authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/role_apis/role-apis-index.adoc b/rest_api/role_apis/role-apis-index.adoc deleted file mode 100644 index c0c31bd89030..000000000000 --- a/rest_api/role_apis/role-apis-index.adoc +++ /dev/null @@ -1,48 +0,0 @@ -[id="role-apis"] -= Role APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== ClusterRoleBinding [authorization.openshift.io/v1] - -Description:: - ClusterRoleBinding references a ClusterRole, but not contain it. It can reference any ClusterRole in the same namespace or in the global namespace. It adds who information via (Users and Groups) OR Subjects and namespace information by which namespace it exists in. ClusterRoleBindings in a given namespace only have effect in that namespace (excepting the master namespace which has power in all namespaces). - -Type:: - `object` - -== ClusterRole [authorization.openshift.io/v1] - -Description:: - ClusterRole is a logical grouping of PolicyRules that can be referenced as a unit by ClusterRoleBindings. - -Type:: - `object` - -== RoleBindingRestriction [authorization.openshift.io/v1] - -Description:: - RoleBindingRestriction is an object that can be matched against a subject (user, group, or service account) to determine whether rolebindings on that subject are allowed in the namespace to which the RoleBindingRestriction belongs. If any one of those RoleBindingRestriction objects matches a subject, rolebindings on that subject in the namespace are allowed. - -Type:: - `object` - -== RoleBinding [authorization.openshift.io/v1] - -Description:: - RoleBinding references a Role, but not contain it. It can reference any Role in the same namespace or in the global namespace. It adds who information via (Users and Groups) OR Subjects and namespace information by which namespace it exists in. RoleBindings in a given namespace only have effect in that namespace (excepting the master namespace which has power in all namespaces). - -Type:: - `object` - -== Role [authorization.openshift.io/v1] - -Description:: - Role is a logical grouping of PolicyRules that can be referenced as a unit by RoleBindings. - -Type:: - `object` - diff --git a/rest_api/role_apis/role-authorization-openshift-io-v1.adoc b/rest_api/role_apis/role-authorization-openshift-io-v1.adoc deleted file mode 100644 index 168a838be825..000000000000 --- a/rest_api/role_apis/role-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,470 +0,0 @@ -[id="role-authorization-openshift-io-v1"] -= Role [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Role is a logical grouping of PolicyRules that can be referenced as a unit by RoleBindings. - -Type:: - `object` - -Required:: - - `rules` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `rules` -| `array` -| Rules holds all the PolicyRules for this Role - -| `rules[]` -| `object` -| PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -|=== -..rules -Description:: - Rules holds all the PolicyRules for this Role - -Type:: - `array` - - - - -..rules[] -Description:: - PolicyRule holds information that describes a policy rule, but does not contain information about who the rule applies to or which namespace the rule applies to. - -Type:: - `object` - -Required:: - - `verbs` - - `resources` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| APIGroups is the name of the APIGroup that contains the resources. If this field is empty, then both kubernetes and origin API groups are assumed. That means that if an action is requested against one of the enumerated resources in either the kubernetes or the origin API group, the request will be allowed - -| `attributeRestrictions` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`RawExtension pkg/runtime`] -| AttributeRestrictions will vary depending on what the Authorizer/AuthorizationAttributeBuilder pair supports. If the Authorizer does not recognize how to handle the AttributeRestrictions, the Authorizer should report an error. - -| `nonResourceURLs` -| `array (string)` -| NonResourceURLsSlice is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path This name is intentionally different than the internal type so that the DefaultConvert works nicely and because the ordering may be different. - -| `resourceNames` -| `array (string)` -| ResourceNames is an optional white list of names that the rule applies to. An empty set means that everything is allowed. - -| `resources` -| `array (string)` -| Resources is a list of resources this rule applies to. ResourceAll represents all resources. - -| `verbs` -| `array (string)` -| Verbs is a list of Verbs that apply to ALL the ResourceKinds and AttributeRestrictions contained in this rule. VerbAll represents all kinds. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/roles` -- `GET`: list objects of kind Role -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/roles` -- `GET`: list objects of kind Role -- `POST`: create a Role -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/roles/{name}` -- `DELETE`: delete a Role -- `GET`: read the specified Role -- `PATCH`: partially update the specified Role -- `PUT`: replace the specified Role - - -=== /apis/authorization.openshift.io/v1/roles - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Role - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolelist-authorization-openshift-io-v1[`RoleList authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/roles - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolelist-authorization-openshift-io-v1[`RoleList authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/roles/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Role -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Role - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Role - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/role-authorization-openshift-io-v1.adoc#role-authorization-openshift-io-v1[`Role authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/role_apis/rolebinding-authorization-openshift-io-v1.adoc b/rest_api/role_apis/rolebinding-authorization-openshift-io-v1.adoc deleted file mode 100644 index d18e038e7145..000000000000 --- a/rest_api/role_apis/rolebinding-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,427 +0,0 @@ -[id="rolebinding-authorization-openshift-io-v1"] -= RoleBinding [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - RoleBinding references a Role, but not contain it. It can reference any Role in the same namespace or in the global namespace. It adds who information via (Users and Groups) OR Subjects and namespace information by which namespace it exists in. RoleBindings in a given namespace only have effect in that namespace (excepting the master namespace which has power in all namespaces). - -Type:: - `object` - -Required:: - - `subjects` - - `roleRef` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `groupNames` -| `array (string)` -| GroupNames holds all the groups directly bound to the role. This field should only be specified when supporting legacy clients and servers. See Subjects for further details. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `roleRef` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| RoleRef can only reference the current namespace and the global namespace. If the RoleRef cannot be resolved, the Authorizer must return an error. Since Policy is a singleton, this is sufficient knowledge to locate a role. - -| `subjects` -| xref:../objects/index.adoc#objectreference-core-v1[`array (ObjectReference core/v1)`] -| Subjects hold object references to authorize with this rule. This field is ignored if UserNames or GroupNames are specified to support legacy clients and servers. Thus newer clients that do not need to support backwards compatibility should send only fully qualified Subjects and should omit the UserNames and GroupNames fields. Clients that need to support backwards compatibility can use this field to build the UserNames and GroupNames. - -| `userNames` -| `array (string)` -| UserNames holds all the usernames directly bound to the role. This field should only be specified when supporting legacy clients and servers. See Subjects for further details. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/rolebindings` -- `GET`: list objects of kind RoleBinding -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/rolebindings` -- `GET`: list objects of kind RoleBinding -- `POST`: create a RoleBinding -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/rolebindings/{name}` -- `DELETE`: delete a RoleBinding -- `GET`: read the specified RoleBinding -- `PATCH`: partially update the specified RoleBinding -- `PUT`: replace the specified RoleBinding - - -=== /apis/authorization.openshift.io/v1/rolebindings - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind RoleBinding - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolebindinglist-authorization-openshift-io-v1[`RoleBindingList authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/rolebindings - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolebindinglist-authorization-openshift-io-v1[`RoleBindingList authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/rolebindings/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the RoleBinding -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified RoleBinding - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified RoleBinding - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/rolebinding-authorization-openshift-io-v1.adoc#rolebinding-authorization-openshift-io-v1[`RoleBinding authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc b/rest_api/role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc deleted file mode 100644 index 432f530e21d2..000000000000 --- a/rest_api/role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc +++ /dev/null @@ -1,508 +0,0 @@ -[id="rolebindingrestriction-authorization-openshift-io-v1"] -= RoleBindingRestriction [authorization.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - RoleBindingRestriction is an object that can be matched against a subject (user, group, or service account) to determine whether rolebindings on that subject are allowed in the namespace to which the RoleBindingRestriction belongs. If any one of those RoleBindingRestriction objects matches a subject, rolebindings on that subject in the namespace are allowed. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Spec defines the matcher. - -|=== -..spec -Description:: - Spec defines the matcher. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `grouprestriction` -| `` -| GroupRestriction matches against group subjects. - -| `serviceaccountrestriction` -| `` -| ServiceAccountRestriction matches against service-account subjects. - -| `userrestriction` -| `` -| UserRestriction matches against user subjects. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/authorization.openshift.io/v1/rolebindingrestrictions` -- `GET`: list objects of kind RoleBindingRestriction -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/rolebindingrestrictions` -- `DELETE`: delete collection of RoleBindingRestriction -- `GET`: list objects of kind RoleBindingRestriction -- `POST`: create a RoleBindingRestriction -* `/apis/authorization.openshift.io/v1/namespaces/{namespace}/rolebindingrestrictions/{name}` -- `DELETE`: delete a RoleBindingRestriction -- `GET`: read the specified RoleBindingRestriction -- `PATCH`: partially update the specified RoleBindingRestriction -- `PUT`: replace the specified RoleBindingRestriction - - -=== /apis/authorization.openshift.io/v1/rolebindingrestrictions - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind RoleBindingRestriction - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolebindingrestrictionlist-authorization-openshift-io-v1[`RoleBindingRestrictionList authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/rolebindingrestrictions - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of RoleBindingRestriction - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind RoleBindingRestriction - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rolebindingrestrictionlist-authorization-openshift-io-v1[`RoleBindingRestrictionList authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a RoleBindingRestriction - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| 202 - Accepted -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/authorization.openshift.io/v1/namespaces/{namespace}/rolebindingrestrictions/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the RoleBindingRestriction -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a RoleBindingRestriction - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified RoleBindingRestriction - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified RoleBindingRestriction - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified RoleBindingRestriction - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| 201 - Created -| xref:../role_apis/rolebindingrestriction-authorization-openshift-io-v1.adoc#rolebindingrestriction-authorization-openshift-io-v1[`RoleBindingRestriction authorization.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/schedule_and_quota_apis/appliedclusterresourcequota-quota-openshift-io-v1.adoc b/rest_api/schedule_and_quota_apis/appliedclusterresourcequota-quota-openshift-io-v1.adoc deleted file mode 100644 index 848ad27e25cc..000000000000 --- a/rest_api/schedule_and_quota_apis/appliedclusterresourcequota-quota-openshift-io-v1.adoc +++ /dev/null @@ -1,353 +0,0 @@ -[id="appliedclusterresourcequota-quota-openshift-io-v1"] -= AppliedClusterResourceQuota [quota.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - AppliedClusterResourceQuota mirrors ClusterResourceQuota at a project scope, for projection into a project. It allows a project-admin to know which ClusterResourceQuotas are applied to his project and their associated usage. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| ClusterResourceQuotaSpec defines the desired quota restrictions - -| `status` -| `object` -| ClusterResourceQuotaStatus defines the actual enforced quota and its current usage - -|=== -..spec -Description:: - ClusterResourceQuotaSpec defines the desired quota restrictions - -Type:: - `object` - -Required:: - - `selector` - - `quota` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `quota` -| xref:../objects/index.adoc#resourcequotaspec-core-v1[`ResourceQuotaSpec core/v1`] -| Quota defines the desired quota - -| `selector` -| `object` -| ClusterResourceQuotaSelector is used to select projects. At least one of LabelSelector or AnnotationSelector must present. If only one is present, it is the only selection criteria. If both are specified, the project must match both restrictions. - -|=== -..spec.selector -Description:: - ClusterResourceQuotaSelector is used to select projects. At least one of LabelSelector or AnnotationSelector must present. If only one is present, it is the only selection criteria. If both are specified, the project must match both restrictions. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `object (string)` -| AnnotationSelector is used to select projects by annotation. - -| `labels` -| xref:../objects/index.adoc#labelselector_v2-meta-v1[`LabelSelector_v2 meta/v1`] -| LabelSelector is used to select projects by label. - -|=== -..status -Description:: - ClusterResourceQuotaStatus defines the actual enforced quota and its current usage - -Type:: - `object` - -Required:: - - `total` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namespaces` -| `array` -| Namespaces slices the usage by project. This division allows for quick resolution of deletion reconciliation inside of a single project without requiring a recalculation across all projects. This can be used to pull the deltas for a given project. - -| `namespaces[]` -| `object` -| ResourceQuotaStatusByNamespace gives status for a particular project - -| `total` -| xref:../objects/index.adoc#resourcequotastatus-core-v1[`ResourceQuotaStatus core/v1`] -| Total defines the actual enforced quota and its current usage across all projects - -|=== -..status.namespaces -Description:: - Namespaces slices the usage by project. This division allows for quick resolution of deletion reconciliation inside of a single project without requiring a recalculation across all projects. This can be used to pull the deltas for a given project. - -Type:: - `array` - - - - -..status.namespaces[] -Description:: - ResourceQuotaStatusByNamespace gives status for a particular project - -Type:: - `object` - -Required:: - - `namespace` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namespace` -| `string` -| Namespace the project this status applies to - -| `status` -| xref:../objects/index.adoc#resourcequotastatus-core-v1[`ResourceQuotaStatus core/v1`] -| Status indicates how many resources have been consumed by this project - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/quota.openshift.io/v1/appliedclusterresourcequotas` -- `GET`: list objects of kind AppliedClusterResourceQuota -* `/apis/quota.openshift.io/v1/namespaces/{namespace}/appliedclusterresourcequotas` -- `GET`: list objects of kind AppliedClusterResourceQuota -* `/apis/quota.openshift.io/v1/namespaces/{namespace}/appliedclusterresourcequotas/{name}` -- `GET`: read the specified AppliedClusterResourceQuota - - -=== /apis/quota.openshift.io/v1/appliedclusterresourcequotas - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind AppliedClusterResourceQuota - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#appliedclusterresourcequotalist-quota-openshift-io-v1[`AppliedClusterResourceQuotaList quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/quota.openshift.io/v1/namespaces/{namespace}/appliedclusterresourcequotas - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind AppliedClusterResourceQuota - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#appliedclusterresourcequotalist-quota-openshift-io-v1[`AppliedClusterResourceQuotaList quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/quota.openshift.io/v1/namespaces/{namespace}/appliedclusterresourcequotas/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the AppliedClusterResourceQuota -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read the specified AppliedClusterResourceQuota - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/appliedclusterresourcequota-quota-openshift-io-v1.adoc#appliedclusterresourcequota-quota-openshift-io-v1[`AppliedClusterResourceQuota quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc b/rest_api/schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc deleted file mode 100644 index a780f9f4747a..000000000000 --- a/rest_api/schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc +++ /dev/null @@ -1,729 +0,0 @@ -[id="clusterresourcequota-quota-openshift-io-v1"] -= ClusterResourceQuota [quota.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ClusterResourceQuota mirrors ResourceQuota at a cluster scope. This object is easily convertible to synthetic ResourceQuota object to allow quota evaluation re-use. - -Type:: - `object` - -Required:: - - `metadata` - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Spec defines the desired quota - -| `status` -| `object` -| Status defines the actual enforced quota and its current usage - -|=== -..spec -Description:: - Spec defines the desired quota - -Type:: - `object` - -Required:: - - `quota` - - `selector` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `quota` -| `object` -| Quota defines the desired quota - -| `selector` -| `object` -| Selector is the selector used to match projects. It should only select active projects on the scale of dozens (though it can select many more less active projects). These projects will contend on object creation through this resource. - -|=== -..spec.quota -Description:: - Quota defines the desired quota - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hard` -| `integer-or-string` -| hard is the set of desired hard limits for each named resource. More info: https://kubernetes.io/docs/concepts/policy/resource-quotas/ - -| `scopeSelector` -| `object` -| scopeSelector is also a collection of filters like scopes that must match each object tracked by a quota but expressed using ScopeSelectorOperator in combination with possible values. For a resource to match, both scopes AND scopeSelector (if specified in spec), must be matched. - -| `scopes` -| `array (string)` -| A collection of filters that must match each object tracked by a quota. If not specified, the quota matches all objects. - -|=== -..spec.quota.scopeSelector -Description:: - scopeSelector is also a collection of filters like scopes that must match each object tracked by a quota but expressed using ScopeSelectorOperator in combination with possible values. For a resource to match, both scopes AND scopeSelector (if specified in spec), must be matched. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `matchExpressions` -| `array` -| A list of scope selector requirements by scope of the resources. - -| `matchExpressions[]` -| `object` -| A scoped-resource selector requirement is a selector that contains values, a scope name, and an operator that relates the scope name and values. - -|=== -..spec.quota.scopeSelector.matchExpressions -Description:: - A list of scope selector requirements by scope of the resources. - -Type:: - `array` - - - - -..spec.quota.scopeSelector.matchExpressions[] -Description:: - A scoped-resource selector requirement is a selector that contains values, a scope name, and an operator that relates the scope name and values. - -Type:: - `object` - -Required:: - - `operator` - - `scopeName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `operator` -| `string` -| Represents a scope's relationship to a set of values. Valid operators are In, NotIn, Exists, DoesNotExist. - -| `scopeName` -| `string` -| The name of the scope that the selector applies to. - -| `values` -| `array (string)` -| An array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. - -|=== -..spec.selector -Description:: - Selector is the selector used to match projects. It should only select active projects on the scale of dozens (though it can select many more less active projects). These projects will contend on object creation through this resource. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `annotations` -| `undefined (string)` -| AnnotationSelector is used to select projects by annotation. - -| `labels` -| `` -| LabelSelector is used to select projects by label. - -|=== -..status -Description:: - Status defines the actual enforced quota and its current usage - -Type:: - `object` - -Required:: - - `total` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `namespaces` -| `` -| Namespaces slices the usage by project. This division allows for quick resolution of deletion reconciliation inside of a single project without requiring a recalculation across all projects. This can be used to pull the deltas for a given project. - -| `total` -| `object` -| Total defines the actual enforced quota and its current usage across all projects - -|=== -..status.total -Description:: - Total defines the actual enforced quota and its current usage across all projects - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hard` -| `integer-or-string` -| Hard is the set of enforced hard limits for each named resource. More info: https://kubernetes.io/docs/concepts/policy/resource-quotas/ - -| `used` -| `integer-or-string` -| Used is the current observed total usage of the resource in the namespace. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/quota.openshift.io/v1/clusterresourcequotas` -- `DELETE`: delete collection of ClusterResourceQuota -- `GET`: list objects of kind ClusterResourceQuota -- `POST`: create a ClusterResourceQuota -* `/apis/quota.openshift.io/v1/clusterresourcequotas/{name}` -- `DELETE`: delete a ClusterResourceQuota -- `GET`: read the specified ClusterResourceQuota -- `PATCH`: partially update the specified ClusterResourceQuota -- `PUT`: replace the specified ClusterResourceQuota -* `/apis/quota.openshift.io/v1/clusterresourcequotas/{name}/status` -- `GET`: read status of the specified ClusterResourceQuota -- `PATCH`: partially update status of the specified ClusterResourceQuota -- `PUT`: replace status of the specified ClusterResourceQuota - - -=== /apis/quota.openshift.io/v1/clusterresourcequotas - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#clusterresourcequotalist-quota-openshift-io-v1[`ClusterResourceQuotaList quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 202 - Accepted -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/quota.openshift.io/v1/clusterresourcequotas/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterResourceQuota -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/quota.openshift.io/v1/clusterresourcequotas/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ClusterResourceQuota -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ClusterResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/clusterresourcequota-quota-openshift-io-v1.adoc#clusterresourcequota-quota-openshift-io-v1[`ClusterResourceQuota quota.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc b/rest_api/schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc deleted file mode 100644 index 052c4fdec0e1..000000000000 --- a/rest_api/schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc +++ /dev/null @@ -1,948 +0,0 @@ -[id="flowschema-flowcontrol-apiserver-k8s-io-v1alpha1"] -= FlowSchema [flowcontrol.apiserver.k8s.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - FlowSchema defines the schema of a group of flows. Note that a flow is made up of a set of inbound API requests with similar attributes and is identified by a pair of strings: the name of the FlowSchema and a "flow distinguisher". - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| `metadata` is the standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| FlowSchemaSpec describes how the FlowSchema's specification looks like. - -| `status` -| `object` -| FlowSchemaStatus represents the current state of a FlowSchema. - -|=== -..spec -Description:: - FlowSchemaSpec describes how the FlowSchema's specification looks like. - -Type:: - `object` - -Required:: - - `priorityLevelConfiguration` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `distinguisherMethod` -| `object` -| FlowDistinguisherMethod specifies the method of a flow distinguisher. - -| `matchingPrecedence` -| `integer` -| `matchingPrecedence` is used to choose among the FlowSchemas that match a given request. The chosen FlowSchema is among those with the numerically lowest (which we take to be logically highest) MatchingPrecedence. Each MatchingPrecedence value must be ranged in [1,10000]. Note that if the precedence is not specified, it will be set to 1000 as default. - -| `priorityLevelConfiguration` -| `object` -| PriorityLevelConfigurationReference contains information that points to the "request-priority" being used. - -| `rules` -| `array` -| `rules` describes which requests will match this flow schema. This FlowSchema matches a request if and only if at least one member of rules matches the request. if it is an empty slice, there will be no requests matching the FlowSchema. - -| `rules[]` -| `object` -| PolicyRulesWithSubjects prescribes a test that applies to a request to an apiserver. The test considers the subject making the request, the verb being requested, and the resource to be acted upon. This PolicyRulesWithSubjects matches a request if and only if both (a) at least one member of subjects matches the request and (b) at least one member of resourceRules or nonResourceRules matches the request. - -|=== -..spec.distinguisherMethod -Description:: - FlowDistinguisherMethod specifies the method of a flow distinguisher. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `type` -| `string` -| `type` is the type of flow distinguisher method The supported types are "ByUser" and "ByNamespace". Required. - -|=== -..spec.priorityLevelConfiguration -Description:: - PriorityLevelConfigurationReference contains information that points to the "request-priority" being used. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| `name` is the name of the priority level configuration being referenced Required. - -|=== -..spec.rules -Description:: - `rules` describes which requests will match this flow schema. This FlowSchema matches a request if and only if at least one member of rules matches the request. if it is an empty slice, there will be no requests matching the FlowSchema. - -Type:: - `array` - - - - -..spec.rules[] -Description:: - PolicyRulesWithSubjects prescribes a test that applies to a request to an apiserver. The test considers the subject making the request, the verb being requested, and the resource to be acted upon. This PolicyRulesWithSubjects matches a request if and only if both (a) at least one member of subjects matches the request and (b) at least one member of resourceRules or nonResourceRules matches the request. - -Type:: - `object` - -Required:: - - `subjects` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nonResourceRules` -| `array` -| `nonResourceRules` is a list of NonResourcePolicyRules that identify matching requests according to their verb and the target non-resource URL. - -| `nonResourceRules[]` -| `object` -| NonResourcePolicyRule is a predicate that matches non-resource requests according to their verb and the target non-resource URL. A NonResourcePolicyRule matches a request if and only if both (a) at least one member of verbs matches the request and (b) at least one member of nonResourceURLs matches the request. - -| `resourceRules` -| `array` -| `resourceRules` is a slice of ResourcePolicyRules that identify matching requests according to their verb and the target resource. At least one of `resourceRules` and `nonResourceRules` has to be non-empty. - -| `resourceRules[]` -| `object` -| ResourcePolicyRule is a predicate that matches some resource requests, testing the request's verb and the target resource. A ResourcePolicyRule matches a resource request if and only if: (a) at least one member of verbs matches the request, (b) at least one member of apiGroups matches the request, (c) at least one member of resources matches the request, and (d) least one member of namespaces matches the request. - -| `subjects` -| `array` -| subjects is the list of normal user, serviceaccount, or group that this rule cares about. There must be at least one member in this slice. A slice that includes both the system:authenticated and system:unauthenticated user groups matches every request. Required. - -| `subjects[]` -| `object` -| Subject matches the originator of a request, as identified by the request authentication system. There are three ways of matching an originator; by user, group, or service account. - -|=== -..spec.rules[].nonResourceRules -Description:: - `nonResourceRules` is a list of NonResourcePolicyRules that identify matching requests according to their verb and the target non-resource URL. - -Type:: - `array` - - - - -..spec.rules[].nonResourceRules[] -Description:: - NonResourcePolicyRule is a predicate that matches non-resource requests according to their verb and the target non-resource URL. A NonResourcePolicyRule matches a request if and only if both (a) at least one member of verbs matches the request and (b) at least one member of nonResourceURLs matches the request. - -Type:: - `object` - -Required:: - - `verbs` - - `nonResourceURLs` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `nonResourceURLs` -| `array (string)` -| `nonResourceURLs` is a set of url prefixes that a user should have access to and may not be empty. For example: - - "/healthz" is legal - - "/hea*" is illegal - - "/hea" is legal but matches nothing - - "/hea/*" also matches nothing - - "/healthz/*" matches all per-component health checks. -"*" matches all non-resource urls. if it is present, it must be the only entry. Required. - -| `verbs` -| `array (string)` -| `verbs` is a list of matching verbs and may not be empty. "*" matches all verbs. If it is present, it must be the only entry. Required. - -|=== -..spec.rules[].resourceRules -Description:: - `resourceRules` is a slice of ResourcePolicyRules that identify matching requests according to their verb and the target resource. At least one of `resourceRules` and `nonResourceRules` has to be non-empty. - -Type:: - `array` - - - - -..spec.rules[].resourceRules[] -Description:: - ResourcePolicyRule is a predicate that matches some resource requests, testing the request's verb and the target resource. A ResourcePolicyRule matches a resource request if and only if: (a) at least one member of verbs matches the request, (b) at least one member of apiGroups matches the request, (c) at least one member of resources matches the request, and (d) least one member of namespaces matches the request. - -Type:: - `object` - -Required:: - - `verbs` - - `apiGroups` - - `resources` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiGroups` -| `array (string)` -| `apiGroups` is a list of matching API groups and may not be empty. "*" matches all API groups and, if present, must be the only entry. Required. - -| `clusterScope` -| `boolean` -| `clusterScope` indicates whether to match requests that do not specify a namespace (which happens either because the resource is not namespaced or the request targets all namespaces). If this field is omitted or false then the `namespaces` field must contain a non-empty list. - -| `namespaces` -| `array (string)` -| `namespaces` is a list of target namespaces that restricts matches. A request that specifies a target namespace matches only if either (a) this list contains that target namespace or (b) this list contains "*". Note that "*" matches any specified namespace but does not match a request that _does not specify_ a namespace (see the `clusterScope` field for that). This list may be empty, but only if `clusterScope` is true. - -| `resources` -| `array (string)` -| `resources` is a list of matching resources (i.e., lowercase and plural) with, if desired, subresource. For example, [ "services", "nodes/status" ]. This list may not be empty. "*" matches all resources and, if present, must be the only entry. Required. - -| `verbs` -| `array (string)` -| `verbs` is a list of matching verbs and may not be empty. "*" matches all verbs and, if present, must be the only entry. Required. - -|=== -..spec.rules[].subjects -Description:: - subjects is the list of normal user, serviceaccount, or group that this rule cares about. There must be at least one member in this slice. A slice that includes both the system:authenticated and system:unauthenticated user groups matches every request. Required. - -Type:: - `array` - - - - -..spec.rules[].subjects[] -Description:: - Subject matches the originator of a request, as identified by the request authentication system. There are three ways of matching an originator; by user, group, or service account. - -Type:: - `object` - -Required:: - - `kind` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `object` -| GroupSubject holds detailed information for group-kind subject. - -| `kind` -| `string` -| Required - -| `serviceAccount` -| `object` -| ServiceAccountSubject holds detailed information for service-account-kind subject. - -| `user` -| `object` -| UserSubject holds detailed information for user-kind subject. - -|=== -..spec.rules[].subjects[].group -Description:: - GroupSubject holds detailed information for group-kind subject. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name is the user group that matches, or "*" to match all user groups. See https://github.com/kubernetes/apiserver/blob/master/pkg/authentication/user/user.go for some well-known group names. Required. - -|=== -..spec.rules[].subjects[].serviceAccount -Description:: - ServiceAccountSubject holds detailed information for service-account-kind subject. - -Type:: - `object` - -Required:: - - `namespace` - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| `name` is the name of matching ServiceAccount objects, or "*" to match regardless of name. Required. - -| `namespace` -| `string` -| `namespace` is the namespace of matching ServiceAccount objects. Required. - -|=== -..spec.rules[].subjects[].user -Description:: - UserSubject holds detailed information for user-kind subject. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| `name` is the username that matches, or "*" to match all usernames. Required. - -|=== -..status -Description:: - FlowSchemaStatus represents the current state of a FlowSchema. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| `conditions` is a list of the current states of FlowSchema. - -| `conditions[]` -| `object` -| FlowSchemaCondition describes conditions for a FlowSchema. - -|=== -..status.conditions -Description:: - `conditions` is a list of the current states of FlowSchema. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - FlowSchemaCondition describes conditions for a FlowSchema. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| `lastTransitionTime` is the last time the condition transitioned from one status to another. - -| `message` -| `string` -| `message` is a human-readable message indicating details about last transition. - -| `reason` -| `string` -| `reason` is a unique, one-word, CamelCase reason for the condition's last transition. - -| `status` -| `string` -| `status` is the status of the condition. Can be True, False, Unknown. Required. - -| `type` -| `string` -| `type` is the type of the condition. Required. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/flowcontrol.apiserver.k8s.io/v1alpha1/flowschemas` -- `DELETE`: delete collection of FlowSchema -- `GET`: list or watch objects of kind FlowSchema -- `POST`: create a FlowSchema -* `/apis/flowcontrol.apiserver.k8s.io/v1alpha1/flowschemas/{name}` -- `DELETE`: delete a FlowSchema -- `GET`: read the specified FlowSchema -- `PATCH`: partially update the specified FlowSchema -- `PUT`: replace the specified FlowSchema -* `/apis/flowcontrol.apiserver.k8s.io/v1alpha1/flowschemas/{name}/status` -- `GET`: read status of the specified FlowSchema -- `PATCH`: partially update status of the specified FlowSchema -- `PUT`: replace status of the specified FlowSchema - - -=== /apis/flowcontrol.apiserver.k8s.io/v1alpha1/flowschemas - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#flowschemalist-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchemaList flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 201 - Created -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 202 - Accepted -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/flowcontrol.apiserver.k8s.io/v1alpha1/flowschemas/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the FlowSchema -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 201 - Created -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/flowcontrol.apiserver.k8s.io/v1alpha1/flowschemas/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the FlowSchema -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified FlowSchema - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified FlowSchema - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 201 - Created -| xref:../schedule_and_quota_apis/flowschema-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#flowschema-flowcontrol-apiserver-k8s-io-v1alpha1[`FlowSchema flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/schedule_and_quota_apis/limitrange-core-v1.adoc b/rest_api/schedule_and_quota_apis/limitrange-core-v1.adoc deleted file mode 100644 index eb25c279a6eb..000000000000 --- a/rest_api/schedule_and_quota_apis/limitrange-core-v1.adoc +++ /dev/null @@ -1,520 +0,0 @@ -[id="limitrange-core-v1"] -= LimitRange [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - LimitRange sets resource usage limits for each kind of resource in a Namespace. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| LimitRangeSpec defines a min/max usage limit for resources that match on kind. - -|=== -..spec -Description:: - LimitRangeSpec defines a min/max usage limit for resources that match on kind. - -Type:: - `object` - -Required:: - - `limits` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limits` -| xref:../objects/index.adoc#limitrangeitem-core-v1[`array (LimitRangeItem core/v1)`] -| Limits is the list of LimitRangeItem objects that are enforced. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/limitranges` -- `GET`: list or watch objects of kind LimitRange -* `/api/v1/namespaces/{namespace}/limitranges` -- `DELETE`: delete collection of LimitRange -- `GET`: list or watch objects of kind LimitRange -- `POST`: create a LimitRange -* `/api/v1/namespaces/{namespace}/limitranges/{name}` -- `DELETE`: delete a LimitRange -- `GET`: read the specified LimitRange -- `PATCH`: partially update the specified LimitRange -- `PUT`: replace the specified LimitRange - - -=== /api/v1/limitranges - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind LimitRange - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#limitrangelist-core-v1[`LimitRangeList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/limitranges - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of LimitRange - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind LimitRange - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#limitrangelist-core-v1[`LimitRangeList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a LimitRange - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| 202 - Accepted -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/limitranges/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the LimitRange -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a LimitRange - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified LimitRange - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified LimitRange - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified LimitRange - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/limitrange-core-v1.adoc#limitrange-core-v1[`LimitRange core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc b/rest_api/schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc deleted file mode 100644 index 1150b4093759..000000000000 --- a/rest_api/schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc +++ /dev/null @@ -1,435 +0,0 @@ -[id="priorityclass-scheduling-k8s-io-v1"] -= PriorityClass [scheduling.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PriorityClass defines mapping from a priority class name to the priority integer value. The value can be any valid integer. - -Type:: - `object` - -Required:: - - `value` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `description` -| `string` -| description is an arbitrary string that usually provides guidelines on when this priority class should be used. - -| `globalDefault` -| `boolean` -| globalDefault specifies whether this PriorityClass should be considered as the default priority for pods that do not have any priority class. Only one PriorityClass can be marked as `globalDefault`. However, if more than one PriorityClasses exists with their `globalDefault` field set to true, the smallest value of such global default PriorityClasses will be used as the default priority. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `preemptionPolicy` -| `string` -| PreemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset. This field is beta-level, gated by the NonPreemptingPriority feature-gate. - -| `value` -| `integer` -| The value of this priority class. This is the actual priority that pods receive when they have the name of this class in their pod spec. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/scheduling.k8s.io/v1/priorityclasses` -- `DELETE`: delete collection of PriorityClass -- `GET`: list or watch objects of kind PriorityClass -- `POST`: create a PriorityClass -* `/apis/scheduling.k8s.io/v1/priorityclasses/{name}` -- `DELETE`: delete a PriorityClass -- `GET`: read the specified PriorityClass -- `PATCH`: partially update the specified PriorityClass -- `PUT`: replace the specified PriorityClass - - -=== /apis/scheduling.k8s.io/v1/priorityclasses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PriorityClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PriorityClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#priorityclasslist-scheduling-k8s-io-v1[`PriorityClassList scheduling.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PriorityClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| 202 - Accepted -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/scheduling.k8s.io/v1/priorityclasses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PriorityClass -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PriorityClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PriorityClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PriorityClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PriorityClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/priorityclass-scheduling-k8s-io-v1.adoc#priorityclass-scheduling-k8s-io-v1[`PriorityClass scheduling.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc b/rest_api/schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc deleted file mode 100644 index ce193fc80ef8..000000000000 --- a/rest_api/schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc +++ /dev/null @@ -1,724 +0,0 @@ -[id="prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1"] -= PriorityLevelConfiguration [flowcontrol.apiserver.k8s.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PriorityLevelConfiguration represents the configuration of a priority level. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| `metadata` is the standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| PriorityLevelConfigurationSpec specifies the configuration of a priority level. - -| `status` -| `object` -| PriorityLevelConfigurationStatus represents the current state of a "request-priority". - -|=== -..spec -Description:: - PriorityLevelConfigurationSpec specifies the configuration of a priority level. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `limited` -| `object` -| LimitedPriorityLevelConfiguration specifies how to handle requests that are subject to limits. It addresses two issues: - * How are requests for this priority level limited? - * What should be done with requests that exceed the limit? - -| `type` -| `string` -| `type` indicates whether this priority level is subject to limitation on request execution. A value of `"Exempt"` means that requests of this priority level are not subject to a limit (and thus are never queued) and do not detract from the capacity made available to other priority levels. A value of `"Limited"` means that (a) requests of this priority level _are_ subject to limits and (b) some of the server's limited capacity is made available exclusively to this priority level. Required. - -|=== -..spec.limited -Description:: - LimitedPriorityLevelConfiguration specifies how to handle requests that are subject to limits. It addresses two issues: - * How are requests for this priority level limited? - * What should be done with requests that exceed the limit? - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `assuredConcurrencyShares` -| `integer` -| `assuredConcurrencyShares` (ACS) configures the execution limit, which is a limit on the number of requests of this priority level that may be exeucting at a given time. ACS must be a positive number. The server's concurrency limit (SCL) is divided among the concurrency-controlled priority levels in proportion to their assured concurrency shares. This produces the assured concurrency value (ACV) --- the number of requests that may be executing at a time --- for each such priority level: - - ACV(l) = ceil( SCL * ACS(l) / ( sum[priority levels k] ACS(k) ) ) - -bigger numbers of ACS mean more reserved concurrent requests (at the expense of every other PL). This field has a default value of 30. - -| `limitResponse` -| `object` -| LimitResponse defines how to handle requests that can not be executed right now. - -|=== -..spec.limited.limitResponse -Description:: - LimitResponse defines how to handle requests that can not be executed right now. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `queuing` -| `object` -| QueuingConfiguration holds the configuration parameters for queuing - -| `type` -| `string` -| `type` is "Queue" or "Reject". "Queue" means that requests that can not be executed upon arrival are held in a queue until they can be executed or a queuing limit is reached. "Reject" means that requests that can not be executed upon arrival are rejected. Required. - -|=== -..spec.limited.limitResponse.queuing -Description:: - QueuingConfiguration holds the configuration parameters for queuing - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `handSize` -| `integer` -| `handSize` is a small positive number that configures the shuffle sharding of requests into queues. When enqueuing a request at this priority level the request's flow identifier (a string pair) is hashed and the hash value is used to shuffle the list of queues and deal a hand of the size specified here. The request is put into one of the shortest queues in that hand. `handSize` must be no larger than `queues`, and should be significantly smaller (so that a few heavy flows do not saturate most of the queues). See the user-facing documentation for more extensive guidance on setting this field. This field has a default value of 8. - -| `queueLengthLimit` -| `integer` -| `queueLengthLimit` is the maximum number of requests allowed to be waiting in a given queue of this priority level at a time; excess requests are rejected. This value must be positive. If not specified, it will be defaulted to 50. - -| `queues` -| `integer` -| `queues` is the number of queues for this priority level. The queues exist independently at each apiserver. The value must be positive. Setting it to 1 effectively precludes shufflesharding and thus makes the distinguisher method of associated flow schemas irrelevant. This field has a default value of 64. - -|=== -..status -Description:: - PriorityLevelConfigurationStatus represents the current state of a "request-priority". - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| `conditions` is the current state of "request-priority". - -| `conditions[]` -| `object` -| PriorityLevelConfigurationCondition defines the condition of priority level. - -|=== -..status.conditions -Description:: - `conditions` is the current state of "request-priority". - -Type:: - `array` - - - - -..status.conditions[] -Description:: - PriorityLevelConfigurationCondition defines the condition of priority level. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| `lastTransitionTime` is the last time the condition transitioned from one status to another. - -| `message` -| `string` -| `message` is a human-readable message indicating details about last transition. - -| `reason` -| `string` -| `reason` is a unique, one-word, CamelCase reason for the condition's last transition. - -| `status` -| `string` -| `status` is the status of the condition. Can be True, False, Unknown. Required. - -| `type` -| `string` -| `type` is the type of the condition. Required. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/flowcontrol.apiserver.k8s.io/v1alpha1/prioritylevelconfigurations` -- `DELETE`: delete collection of PriorityLevelConfiguration -- `GET`: list or watch objects of kind PriorityLevelConfiguration -- `POST`: create a PriorityLevelConfiguration -* `/apis/flowcontrol.apiserver.k8s.io/v1alpha1/prioritylevelconfigurations/{name}` -- `DELETE`: delete a PriorityLevelConfiguration -- `GET`: read the specified PriorityLevelConfiguration -- `PATCH`: partially update the specified PriorityLevelConfiguration -- `PUT`: replace the specified PriorityLevelConfiguration -* `/apis/flowcontrol.apiserver.k8s.io/v1alpha1/prioritylevelconfigurations/{name}/status` -- `GET`: read status of the specified PriorityLevelConfiguration -- `PATCH`: partially update status of the specified PriorityLevelConfiguration -- `PUT`: replace status of the specified PriorityLevelConfiguration - - -=== /apis/flowcontrol.apiserver.k8s.io/v1alpha1/prioritylevelconfigurations - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#prioritylevelconfigurationlist-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfigurationList flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 201 - Created -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 202 - Accepted -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/flowcontrol.apiserver.k8s.io/v1alpha1/prioritylevelconfigurations/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PriorityLevelConfiguration -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 201 - Created -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/flowcontrol.apiserver.k8s.io/v1alpha1/prioritylevelconfigurations/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PriorityLevelConfiguration -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified PriorityLevelConfiguration - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified PriorityLevelConfiguration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 201 - Created -| xref:../schedule_and_quota_apis/prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1.adoc#prioritylevelconfiguration-flowcontrol-apiserver-k8s-io-v1alpha1[`PriorityLevelConfiguration flowcontrol.apiserver.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/schedule_and_quota_apis/resourcequota-core-v1.adoc b/rest_api/schedule_and_quota_apis/resourcequota-core-v1.adoc deleted file mode 100644 index 89df3cc5ba6e..000000000000 --- a/rest_api/schedule_and_quota_apis/resourcequota-core-v1.adoc +++ /dev/null @@ -1,679 +0,0 @@ -[id="resourcequota-core-v1"] -= ResourceQuota [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ResourceQuota sets aggregate quota restrictions enforced per namespace - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ResourceQuotaSpec defines the desired hard limits to enforce for Quota. - -| `status` -| `object` -| ResourceQuotaStatus defines the enforced hard limits and observed use. - -|=== -..spec -Description:: - ResourceQuotaSpec defines the desired hard limits to enforce for Quota. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hard` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| hard is the set of desired hard limits for each named resource. More info: https://kubernetes.io/docs/concepts/policy/resource-quotas/ - -| `scopeSelector` -| xref:../objects/index.adoc#scopeselector-core-v1[`ScopeSelector core/v1`] -| scopeSelector is also a collection of filters like scopes that must match each object tracked by a quota but expressed using ScopeSelectorOperator in combination with possible values. For a resource to match, both scopes AND scopeSelector (if specified in spec), must be matched. - -| `scopes` -| `array (string)` -| A collection of filters that must match each object tracked by a quota. If not specified, the quota matches all objects. - -|=== -..status -Description:: - ResourceQuotaStatus defines the enforced hard limits and observed use. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `hard` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Hard is the set of enforced hard limits for each named resource. More info: https://kubernetes.io/docs/concepts/policy/resource-quotas/ - -| `used` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Used is the current observed total usage of the resource in the namespace. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/resourcequotas` -- `GET`: list or watch objects of kind ResourceQuota -* `/api/v1/namespaces/{namespace}/resourcequotas` -- `DELETE`: delete collection of ResourceQuota -- `GET`: list or watch objects of kind ResourceQuota -- `POST`: create a ResourceQuota -* `/api/v1/namespaces/{namespace}/resourcequotas/{name}` -- `DELETE`: delete a ResourceQuota -- `GET`: read the specified ResourceQuota -- `PATCH`: partially update the specified ResourceQuota -- `PUT`: replace the specified ResourceQuota -* `/api/v1/namespaces/{namespace}/resourcequotas/{name}/status` -- `GET`: read status of the specified ResourceQuota -- `PATCH`: partially update status of the specified ResourceQuota -- `PUT`: replace status of the specified ResourceQuota - - -=== /api/v1/resourcequotas - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ResourceQuota - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#resourcequotalist-core-v1[`ResourceQuotaList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/resourcequotas - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#resourcequotalist-core-v1[`ResourceQuotaList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 202 - Accepted -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/resourcequotas/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ResourceQuota -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 202 - Accepted -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/resourcequotas/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ResourceQuota -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ResourceQuota - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ResourceQuota - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 201 - Created -| xref:../schedule_and_quota_apis/resourcequota-core-v1.adoc#resourcequota-core-v1[`ResourceQuota core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/schedule_and_quota_apis/schedule-and-quota-apis-index.adoc b/rest_api/schedule_and_quota_apis/schedule-and-quota-apis-index.adoc deleted file mode 100644 index c218c40c54e3..000000000000 --- a/rest_api/schedule_and_quota_apis/schedule-and-quota-apis-index.adoc +++ /dev/null @@ -1,64 +0,0 @@ -[id="schedule-and-quota-apis"] -= Schedule and quota APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== AppliedClusterResourceQuota [quota.openshift.io/v1] - -Description:: - AppliedClusterResourceQuota mirrors ClusterResourceQuota at a project scope, for projection into a project. It allows a project-admin to know which ClusterResourceQuotas are applied to his project and their associated usage. - -Type:: - `object` - -== ClusterResourceQuota [quota.openshift.io/v1] - -Description:: - ClusterResourceQuota mirrors ResourceQuota at a cluster scope. This object is easily convertible to synthetic ResourceQuota object to allow quota evaluation re-use. - -Type:: - `object` - -== FlowSchema [flowcontrol.apiserver.k8s.io/v1alpha1] - -Description:: - FlowSchema defines the schema of a group of flows. Note that a flow is made up of a set of inbound API requests with similar attributes and is identified by a pair of strings: the name of the FlowSchema and a "flow distinguisher". - -Type:: - `object` - -== LimitRange [core/v1] - -Description:: - LimitRange sets resource usage limits for each kind of resource in a Namespace. - -Type:: - `object` - -== PriorityClass [scheduling.k8s.io/v1] - -Description:: - PriorityClass defines mapping from a priority class name to the priority integer value. The value can be any valid integer. - -Type:: - `object` - -== PriorityLevelConfiguration [flowcontrol.apiserver.k8s.io/v1alpha1] - -Description:: - PriorityLevelConfiguration represents the configuration of a priority level. - -Type:: - `object` - -== ResourceQuota [core/v1] - -Description:: - ResourceQuota sets aggregate quota restrictions enforced per namespace - -Type:: - `object` - diff --git a/rest_api/security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc b/rest_api/security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc deleted file mode 100644 index f226fe8c0ae5..000000000000 --- a/rest_api/security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc +++ /dev/null @@ -1,882 +0,0 @@ -[id="certificatesigningrequest-certificates-k8s-io-v1"] -= CertificateSigningRequest [certificates.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CertificateSigningRequest objects provide a mechanism to obtain x509 certificates by submitting a certificate signing request, and having it asynchronously approved and issued. - -Kubelets use this API to obtain: - 1. client certificates to authenticate to kube-apiserver (with the "kubernetes.io/kube-apiserver-client-kubelet" signerName). - 2. serving certificates for TLS endpoints kube-apiserver can connect to securely (with the "kubernetes.io/kubelet-serving" signerName). - -This API can be used to request client certificates to authenticate to kube-apiserver (with the "kubernetes.io/kube-apiserver-client" signerName), or to obtain certificates from custom non-Kubernetes signers. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| CertificateSigningRequestSpec contains the certificate request. - -| `status` -| `object` -| CertificateSigningRequestStatus contains conditions used to indicate approved/denied/failed status of the request, and the issued certificate. - -|=== -..spec -Description:: - CertificateSigningRequestSpec contains the certificate request. - -Type:: - `object` - -Required:: - - `request` - - `signerName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `extra` -| `object` -| extra contains extra attributes of the user that created the CertificateSigningRequest. Populated by the API server on creation and immutable. - -| `extra{}` -| `array (string)` -| - -| `groups` -| `array (string)` -| groups contains group membership of the user that created the CertificateSigningRequest. Populated by the API server on creation and immutable. - -| `request` -| `string` -| request contains an x509 certificate signing request encoded in a "CERTIFICATE REQUEST" PEM block. When serialized as JSON or YAML, the data is additionally base64-encoded. - -| `signerName` -| `string` -| signerName indicates the requested signer, and is a qualified name. - -List/watch requests for CertificateSigningRequests can filter on this field using a "spec.signerName=NAME" fieldSelector. - -Well-known Kubernetes signers are: - 1. "kubernetes.io/kube-apiserver-client": issues client certificates that can be used to authenticate to kube-apiserver. - Requests for this signer are never auto-approved by kube-controller-manager, can be issued by the "csrsigning" controller in kube-controller-manager. - 2. "kubernetes.io/kube-apiserver-client-kubelet": issues client certificates that kubelets use to authenticate to kube-apiserver. - Requests for this signer can be auto-approved by the "csrapproving" controller in kube-controller-manager, and can be issued by the "csrsigning" controller in kube-controller-manager. - 3. "kubernetes.io/kubelet-serving" issues serving certificates that kubelets use to serve TLS endpoints, which kube-apiserver can connect to securely. - Requests for this signer are never auto-approved by kube-controller-manager, and can be issued by the "csrsigning" controller in kube-controller-manager. - -More details are available at https://k8s.io/docs/reference/access-authn-authz/certificate-signing-requests/#kubernetes-signers - -Custom signerNames can also be specified. The signer defines: - 1. Trust distribution: how trust (CA bundles) are distributed. - 2. Permitted subjects: and behavior when a disallowed subject is requested. - 3. Required, permitted, or forbidden x509 extensions in the request (including whether subjectAltNames are allowed, which types, restrictions on allowed values) and behavior when a disallowed extension is requested. - 4. Required, permitted, or forbidden key usages / extended key usages. - 5. Expiration/certificate lifetime: whether it is fixed by the signer, configurable by the admin. - 6. Whether or not requests for CA certificates are allowed. - -| `uid` -| `string` -| uid contains the uid of the user that created the CertificateSigningRequest. Populated by the API server on creation and immutable. - -| `usages` -| `array (string)` -| usages specifies a set of key usages requested in the issued certificate. - -Requests for TLS client certificates typically request: "digital signature", "key encipherment", "client auth". - -Requests for TLS serving certificates typically request: "key encipherment", "digital signature", "server auth". - -Valid values are: - "signing", "digital signature", "content commitment", - "key encipherment", "key agreement", "data encipherment", - "cert sign", "crl sign", "encipher only", "decipher only", "any", - "server auth", "client auth", - "code signing", "email protection", "s/mime", - "ipsec end system", "ipsec tunnel", "ipsec user", - "timestamping", "ocsp signing", "microsoft sgc", "netscape sgc" - -| `username` -| `string` -| username contains the name of the user that created the CertificateSigningRequest. Populated by the API server on creation and immutable. - -|=== -..spec.extra -Description:: - extra contains extra attributes of the user that created the CertificateSigningRequest. Populated by the API server on creation and immutable. - -Type:: - `object` - - - - -..status -Description:: - CertificateSigningRequestStatus contains conditions used to indicate approved/denied/failed status of the request, and the issued certificate. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `certificate` -| `string` -| certificate is populated with an issued certificate by the signer after an Approved condition is present. This field is set via the /status subresource. Once populated, this field is immutable. - -If the certificate signing request is denied, a condition of type "Denied" is added and this field remains empty. If the signer cannot issue the certificate, a condition of type "Failed" is added and this field remains empty. - -Validation requirements: - 1. certificate must contain one or more PEM blocks. - 2. All PEM blocks must have the "CERTIFICATE" label, contain no headers, and the encoded data - must be a BER-encoded ASN.1 Certificate structure as described in section 4 of RFC5280. - 3. Non-PEM content may appear before or after the "CERTIFICATE" PEM blocks and is unvalidated, - to allow for explanatory text as described in section 5.2 of RFC7468. - -If more than one PEM block is present, and the definition of the requested spec.signerName does not indicate otherwise, the first block is the issued certificate, and subsequent blocks should be treated as intermediate certificates and presented in TLS handshakes. - -The certificate is encoded in PEM format. - -When serialized as JSON or YAML, the data is additionally base64-encoded, so it consists of: - - base64( - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - ) - -| `conditions` -| `array` -| conditions applied to the request. Known conditions are "Approved", "Denied", and "Failed". - -| `conditions[]` -| `object` -| CertificateSigningRequestCondition describes a condition of a CertificateSigningRequest object - -|=== -..status.conditions -Description:: - conditions applied to the request. Known conditions are "Approved", "Denied", and "Failed". - -Type:: - `array` - - - - -..status.conditions[] -Description:: - CertificateSigningRequestCondition describes a condition of a CertificateSigningRequest object - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| lastTransitionTime is the time the condition last transitioned from one status to another. If unset, when a new condition type is added or an existing condition's status is changed, the server defaults this to the current time. - -| `lastUpdateTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| lastUpdateTime is the time of the last update to this condition - -| `message` -| `string` -| message contains a human readable message with details about the request state - -| `reason` -| `string` -| reason indicates a brief reason for the request state - -| `status` -| `string` -| status of the condition, one of True, False, Unknown. Approved, Denied, and Failed conditions may not be "False" or "Unknown". - -| `type` -| `string` -| type of the condition. Known conditions are "Approved", "Denied", and "Failed". - -An "Approved" condition is added via the /approval subresource, indicating the request was approved and should be issued by the signer. - -A "Denied" condition is added via the /approval subresource, indicating the request was denied and should not be issued by the signer. - -A "Failed" condition is added via the /status subresource, indicating the signer failed to issue the certificate. - -Approved and Denied conditions are mutually exclusive. Approved, Denied, and Failed conditions cannot be removed once added. - -Only one condition of a given type is allowed. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/certificates.k8s.io/v1/certificatesigningrequests` -- `DELETE`: delete collection of CertificateSigningRequest -- `GET`: list or watch objects of kind CertificateSigningRequest -- `POST`: create a CertificateSigningRequest -* `/apis/certificates.k8s.io/v1/certificatesigningrequests/{name}` -- `DELETE`: delete a CertificateSigningRequest -- `GET`: read the specified CertificateSigningRequest -- `PATCH`: partially update the specified CertificateSigningRequest -- `PUT`: replace the specified CertificateSigningRequest -* `/apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/status` -- `GET`: read status of the specified CertificateSigningRequest -- `PATCH`: partially update status of the specified CertificateSigningRequest -- `PUT`: replace status of the specified CertificateSigningRequest -* `/apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/approval` -- `GET`: read approval of the specified CertificateSigningRequest -- `PATCH`: partially update approval of the specified CertificateSigningRequest -- `PUT`: replace approval of the specified CertificateSigningRequest - - -=== /apis/certificates.k8s.io/v1/certificatesigningrequests - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#certificatesigningrequestlist-certificates-k8s-io-v1[`CertificateSigningRequestList certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 201 - Created -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 202 - Accepted -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/certificates.k8s.io/v1/certificatesigningrequests/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CertificateSigningRequest -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 201 - Created -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CertificateSigningRequest -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified CertificateSigningRequest - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 201 - Created -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/certificates.k8s.io/v1/certificatesigningrequests/{name}/approval - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CertificateSigningRequest -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read approval of the specified CertificateSigningRequest - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update approval of the specified CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace approval of the specified CertificateSigningRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 201 - Created -| xref:../security_apis/certificatesigningrequest-certificates-k8s-io-v1.adoc#certificatesigningrequest-certificates-k8s-io-v1[`CertificateSigningRequest certificates.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc b/rest_api/security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc deleted file mode 100644 index 0835cedd05b7..000000000000 --- a/rest_api/security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc +++ /dev/null @@ -1,788 +0,0 @@ -[id="credentialsrequest-cloudcredential-openshift-io-v1"] -= CredentialsRequest [cloudcredential.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CredentialsRequest is the Schema for the credentialsrequests API - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| CredentialsRequestSpec defines the desired state of CredentialsRequest - -| `status` -| `object` -| CredentialsRequestStatus defines the observed state of CredentialsRequest - -|=== -..spec -Description:: - CredentialsRequestSpec defines the desired state of CredentialsRequest - -Type:: - `object` - -Required:: - - `secretRef` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `providerSpec` -| `` -| ProviderSpec contains the cloud provider specific credentials specification. - -| `secretRef` -| `object` -| SecretRef points to the secret where the credentials should be stored once generated. - -|=== -..spec.secretRef -Description:: - SecretRef points to the secret where the credentials should be stored once generated. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status -Description:: - CredentialsRequestStatus defines the observed state of CredentialsRequest - -Type:: - `object` - -Required:: - - `lastSyncGeneration` - - `provisioned` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| Conditions includes detailed status for the CredentialsRequest - -| `conditions[]` -| `object` -| CredentialsRequestCondition contains details for any of the conditions on a CredentialsRequest object - -| `lastSyncCloudCredsSecretResourceVersion` -| `string` -| LastSyncCloudCredsSecretResourceVersion is the resource version of the cloud credentials secret resource when the credentials request resource was last synced. Used to determine if the the cloud credentials have been updated since the last sync. - -| `lastSyncGeneration` -| `integer` -| LastSyncGeneration is the generation of the credentials request resource that was last synced. Used to determine if the object has changed and requires a sync. - -| `lastSyncTimestamp` -| `string` -| LastSyncTimestamp is the time that the credentials were last synced. - -| `providerStatus` -| `` -| ProviderStatus contains cloud provider specific status. - -| `provisioned` -| `boolean` -| Provisioned is true once the credentials have been initially provisioned. - -|=== -..status.conditions -Description:: - Conditions includes detailed status for the CredentialsRequest - -Type:: - `array` - - - - -..status.conditions[] -Description:: - CredentialsRequestCondition contains details for any of the conditions on a CredentialsRequest object - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| `string` -| LastProbeTime is the last time we probed the condition - -| `lastTransitionTime` -| `string` -| LastTransitionTime is the last time the condition transitioned from one status to another. - -| `message` -| `string` -| Message is a human-readable message indicating details about the last transition - -| `reason` -| `string` -| Reason is a unique, one-word, CamelCase reason for the condition's last transition - -| `status` -| `string` -| Status is the status of the condition - -| `type` -| `string` -| Type is the specific type of the condition - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/cloudcredential.openshift.io/v1/credentialsrequests` -- `GET`: list objects of kind CredentialsRequest -* `/apis/cloudcredential.openshift.io/v1/namespaces/{namespace}/credentialsrequests` -- `DELETE`: delete collection of CredentialsRequest -- `GET`: list objects of kind CredentialsRequest -- `POST`: create a CredentialsRequest -* `/apis/cloudcredential.openshift.io/v1/namespaces/{namespace}/credentialsrequests/{name}` -- `DELETE`: delete a CredentialsRequest -- `GET`: read the specified CredentialsRequest -- `PATCH`: partially update the specified CredentialsRequest -- `PUT`: replace the specified CredentialsRequest -* `/apis/cloudcredential.openshift.io/v1/namespaces/{namespace}/credentialsrequests/{name}/status` -- `GET`: read status of the specified CredentialsRequest -- `PATCH`: partially update status of the specified CredentialsRequest -- `PUT`: replace status of the specified CredentialsRequest - - -=== /apis/cloudcredential.openshift.io/v1/credentialsrequests - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind CredentialsRequest - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#credentialsrequestlist-cloudcredential-openshift-io-v1[`CredentialsRequestList cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/cloudcredential.openshift.io/v1/namespaces/{namespace}/credentialsrequests - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#credentialsrequestlist-cloudcredential-openshift-io-v1[`CredentialsRequestList cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 202 - Accepted -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/cloudcredential.openshift.io/v1/namespaces/{namespace}/credentialsrequests/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CredentialsRequest -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/cloudcredential.openshift.io/v1/namespaces/{namespace}/credentialsrequests/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CredentialsRequest -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified CredentialsRequest - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/credentialsrequest-cloudcredential-openshift-io-v1.adoc#credentialsrequest-cloudcredential-openshift-io-v1[`CredentialsRequest cloudcredential.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/security_apis/podsecuritypolicyreview-security-openshift-io-v1.adoc b/rest_api/security_apis/podsecuritypolicyreview-security-openshift-io-v1.adoc deleted file mode 100644 index 1328e63b51c2..000000000000 --- a/rest_api/security_apis/podsecuritypolicyreview-security-openshift-io-v1.adoc +++ /dev/null @@ -1,202 +0,0 @@ -[id="podsecuritypolicyreview-security-openshift-io-v1"] -= PodSecurityPolicyReview [security.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PodSecurityPolicyReview checks which service accounts (not users, since that would be cluster-wide) can create the `PodTemplateSpec` in question. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `spec` -| `object` -| PodSecurityPolicyReviewSpec defines specification for PodSecurityPolicyReview - -| `status` -| `object` -| PodSecurityPolicyReviewStatus represents the status of PodSecurityPolicyReview. - -|=== -..spec -Description:: - PodSecurityPolicyReviewSpec defines specification for PodSecurityPolicyReview - -Type:: - `object` - -Required:: - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `serviceAccountNames` -| `array (string)` -| serviceAccountNames is an optional set of ServiceAccounts to run the check with. If serviceAccountNames is empty, the template.spec.serviceAccountName is used, unless it's empty, in which case "default" is used instead. If serviceAccountNames is specified, template.spec.serviceAccountName is ignored. - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| template is the PodTemplateSpec to check. The template.spec.serviceAccountName field is used if serviceAccountNames is empty, unless the template.spec.serviceAccountName is empty, in which case "default" is used. If serviceAccountNames is specified, template.spec.serviceAccountName is ignored. - -|=== -..status -Description:: - PodSecurityPolicyReviewStatus represents the status of PodSecurityPolicyReview. - -Type:: - `object` - -Required:: - - `allowedServiceAccounts` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowedServiceAccounts` -| `array` -| allowedServiceAccounts returns the list of service accounts in *this* namespace that have the power to create the PodTemplateSpec. - -| `allowedServiceAccounts[]` -| `object` -| ServiceAccountPodSecurityPolicyReviewStatus represents ServiceAccount name and related review status - -|=== -..status.allowedServiceAccounts -Description:: - allowedServiceAccounts returns the list of service accounts in *this* namespace that have the power to create the PodTemplateSpec. - -Type:: - `array` - - - - -..status.allowedServiceAccounts[] -Description:: - ServiceAccountPodSecurityPolicyReviewStatus represents ServiceAccount name and related review status - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowedBy` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| allowedBy is a reference to the rule that allows the PodTemplateSpec. A rule can be a SecurityContextConstraint or a PodSecurityPolicy A `nil`, indicates that it was denied. - -| `name` -| `string` -| name contains the allowed and the denied ServiceAccount name - -| `reason` -| `string` -| A machine-readable description of why this operation is in the "Failure" status. If this value is empty there is no information available. - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| template is the PodTemplateSpec after the defaulting is applied. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/security.openshift.io/v1/namespaces/{namespace}/podsecuritypolicyreviews` -- `POST`: create a PodSecurityPolicyReview - - -=== /apis/security.openshift.io/v1/namespaces/{namespace}/podsecuritypolicyreviews - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a PodSecurityPolicyReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/podsecuritypolicyreview-security-openshift-io-v1.adoc#podsecuritypolicyreview-security-openshift-io-v1[`PodSecurityPolicyReview security.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/podsecuritypolicyreview-security-openshift-io-v1.adoc#podsecuritypolicyreview-security-openshift-io-v1[`PodSecurityPolicyReview security.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/podsecuritypolicyreview-security-openshift-io-v1.adoc#podsecuritypolicyreview-security-openshift-io-v1[`PodSecurityPolicyReview security.openshift.io/v1`] -| 202 - Accepted -| xref:../security_apis/podsecuritypolicyreview-security-openshift-io-v1.adoc#podsecuritypolicyreview-security-openshift-io-v1[`PodSecurityPolicyReview security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/security_apis/podsecuritypolicyselfsubjectreview-security-openshift-io-v1.adoc b/rest_api/security_apis/podsecuritypolicyselfsubjectreview-security-openshift-io-v1.adoc deleted file mode 100644 index 1a91b9d1fe3f..000000000000 --- a/rest_api/security_apis/podsecuritypolicyselfsubjectreview-security-openshift-io-v1.adoc +++ /dev/null @@ -1,157 +0,0 @@ -[id="podsecuritypolicyselfsubjectreview-security-openshift-io-v1"] -= PodSecurityPolicySelfSubjectReview [security.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PodSecurityPolicySelfSubjectReview checks whether this user/SA tuple can create the PodTemplateSpec - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `spec` -| `object` -| PodSecurityPolicySelfSubjectReviewSpec contains specification for PodSecurityPolicySelfSubjectReview. - -| `status` -| `object` -| PodSecurityPolicySubjectReviewStatus contains information/status for PodSecurityPolicySubjectReview. - -|=== -..spec -Description:: - PodSecurityPolicySelfSubjectReviewSpec contains specification for PodSecurityPolicySelfSubjectReview. - -Type:: - `object` - -Required:: - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| template is the PodTemplateSpec to check. - -|=== -..status -Description:: - PodSecurityPolicySubjectReviewStatus contains information/status for PodSecurityPolicySubjectReview. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowedBy` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| allowedBy is a reference to the rule that allows the PodTemplateSpec. A rule can be a SecurityContextConstraint or a PodSecurityPolicy A `nil`, indicates that it was denied. - -| `reason` -| `string` -| A machine-readable description of why this operation is in the "Failure" status. If this value is empty there is no information available. - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| template is the PodTemplateSpec after the defaulting is applied. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/security.openshift.io/v1/namespaces/{namespace}/podsecuritypolicyselfsubjectreviews` -- `POST`: create a PodSecurityPolicySelfSubjectReview - - -=== /apis/security.openshift.io/v1/namespaces/{namespace}/podsecuritypolicyselfsubjectreviews - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a PodSecurityPolicySelfSubjectReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/podsecuritypolicyselfsubjectreview-security-openshift-io-v1.adoc#podsecuritypolicyselfsubjectreview-security-openshift-io-v1[`PodSecurityPolicySelfSubjectReview security.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/podsecuritypolicyselfsubjectreview-security-openshift-io-v1.adoc#podsecuritypolicyselfsubjectreview-security-openshift-io-v1[`PodSecurityPolicySelfSubjectReview security.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/podsecuritypolicyselfsubjectreview-security-openshift-io-v1.adoc#podsecuritypolicyselfsubjectreview-security-openshift-io-v1[`PodSecurityPolicySelfSubjectReview security.openshift.io/v1`] -| 202 - Accepted -| xref:../security_apis/podsecuritypolicyselfsubjectreview-security-openshift-io-v1.adoc#podsecuritypolicyselfsubjectreview-security-openshift-io-v1[`PodSecurityPolicySelfSubjectReview security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/security_apis/podsecuritypolicysubjectreview-security-openshift-io-v1.adoc b/rest_api/security_apis/podsecuritypolicysubjectreview-security-openshift-io-v1.adoc deleted file mode 100644 index 0d76d57e082b..000000000000 --- a/rest_api/security_apis/podsecuritypolicysubjectreview-security-openshift-io-v1.adoc +++ /dev/null @@ -1,165 +0,0 @@ -[id="podsecuritypolicysubjectreview-security-openshift-io-v1"] -= PodSecurityPolicySubjectReview [security.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PodSecurityPolicySubjectReview checks whether a particular user/SA tuple can create the PodTemplateSpec. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `spec` -| `object` -| PodSecurityPolicySubjectReviewSpec defines specification for PodSecurityPolicySubjectReview - -| `status` -| `object` -| PodSecurityPolicySubjectReviewStatus contains information/status for PodSecurityPolicySubjectReview. - -|=== -..spec -Description:: - PodSecurityPolicySubjectReviewSpec defines specification for PodSecurityPolicySubjectReview - -Type:: - `object` - -Required:: - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `groups` -| `array (string)` -| groups is the groups you're testing for. - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| template is the PodTemplateSpec to check. If template.spec.serviceAccountName is empty it will not be defaulted. If its non-empty, it will be checked. - -| `user` -| `string` -| user is the user you're testing for. If you specify "user" but not "group", then is it interpreted as "What if user were not a member of any groups. If user and groups are empty, then the check is performed using *only* the serviceAccountName in the template. - -|=== -..status -Description:: - PodSecurityPolicySubjectReviewStatus contains information/status for PodSecurityPolicySubjectReview. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowedBy` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| allowedBy is a reference to the rule that allows the PodTemplateSpec. A rule can be a SecurityContextConstraint or a PodSecurityPolicy A `nil`, indicates that it was denied. - -| `reason` -| `string` -| A machine-readable description of why this operation is in the "Failure" status. If this value is empty there is no information available. - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| template is the PodTemplateSpec after the defaulting is applied. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/security.openshift.io/v1/namespaces/{namespace}/podsecuritypolicysubjectreviews` -- `POST`: create a PodSecurityPolicySubjectReview - - -=== /apis/security.openshift.io/v1/namespaces/{namespace}/podsecuritypolicysubjectreviews - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a PodSecurityPolicySubjectReview - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/podsecuritypolicysubjectreview-security-openshift-io-v1.adoc#podsecuritypolicysubjectreview-security-openshift-io-v1[`PodSecurityPolicySubjectReview security.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/podsecuritypolicysubjectreview-security-openshift-io-v1.adoc#podsecuritypolicysubjectreview-security-openshift-io-v1[`PodSecurityPolicySubjectReview security.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/podsecuritypolicysubjectreview-security-openshift-io-v1.adoc#podsecuritypolicysubjectreview-security-openshift-io-v1[`PodSecurityPolicySubjectReview security.openshift.io/v1`] -| 202 - Accepted -| xref:../security_apis/podsecuritypolicysubjectreview-security-openshift-io-v1.adoc#podsecuritypolicysubjectreview-security-openshift-io-v1[`PodSecurityPolicySubjectReview security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/security_apis/rangeallocation-security-openshift-io-v1.adoc b/rest_api/security_apis/rangeallocation-security-openshift-io-v1.adoc deleted file mode 100644 index 0ceb3556dfeb..000000000000 --- a/rest_api/security_apis/rangeallocation-security-openshift-io-v1.adoc +++ /dev/null @@ -1,428 +0,0 @@ -[id="rangeallocation-security-openshift-io-v1"] -= RangeAllocation [security.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - RangeAllocation is used so we can easily expose a RangeAllocation typed for security group - -Type:: - `object` - -Required:: - - `range` - - `data` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `data` -| `string` -| data is a byte array representing the serialized state of a range allocation. It is a bitmap with each bit set to one to represent a range is taken. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `range` -| `string` -| range is a string representing a unique label for a range of uids, "1000000000-2000000000/10000". - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/security.openshift.io/v1/rangeallocations` -- `DELETE`: delete collection of RangeAllocation -- `GET`: list or watch objects of kind RangeAllocation -- `POST`: create a RangeAllocation -* `/apis/security.openshift.io/v1/rangeallocations/{name}` -- `DELETE`: delete a RangeAllocation -- `GET`: read the specified RangeAllocation -- `PATCH`: partially update the specified RangeAllocation -- `PUT`: replace the specified RangeAllocation - - -=== /apis/security.openshift.io/v1/rangeallocations - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of RangeAllocation - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind RangeAllocation - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#rangeallocationlist-security-openshift-io-v1[`RangeAllocationList security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a RangeAllocation - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| 202 - Accepted -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/security.openshift.io/v1/rangeallocations/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the RangeAllocation -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a RangeAllocation - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified RangeAllocation - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified RangeAllocation - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified RangeAllocation - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/rangeallocation-security-openshift-io-v1.adoc#rangeallocation-security-openshift-io-v1[`RangeAllocation security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/security_apis/secret-core-v1.adoc b/rest_api/security_apis/secret-core-v1.adoc deleted file mode 100644 index 602477541bbf..000000000000 --- a/rest_api/security_apis/secret-core-v1.adoc +++ /dev/null @@ -1,511 +0,0 @@ -[id="secret-core-v1"] -= Secret [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Secret holds secret data of a certain type. The total bytes of the values in the Data field must be less than MaxSecretSize bytes. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `data` -| `object (string)` -| Data contains the secret data. Each key must consist of alphanumeric characters, '-', '_' or '.'. The serialized form of the secret data is a base64 encoded string, representing the arbitrary (possibly non-string) data value here. Described in https://tools.ietf.org/html/rfc4648#section-4 - -| `immutable` -| `boolean` -| Immutable, if set to true, ensures that data stored in the Secret cannot be updated (only object metadata can be modified). If not set to true, the field can be modified at any time. Defaulted to nil. This is a beta field enabled by ImmutableEphemeralVolumes feature gate. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `stringData` -| `object (string)` -| stringData allows specifying non-binary secret data in string form. It is provided as a write-only convenience method. All keys and values are merged into the data field on write, overwriting any existing values. It is never output when reading from the API. - -| `type` -| `string` -| Used to facilitate programmatic handling of secret data. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/secrets` -- `GET`: list or watch objects of kind Secret -* `/api/v1/namespaces/{namespace}/secrets` -- `DELETE`: delete collection of Secret -- `GET`: list or watch objects of kind Secret -- `POST`: create a Secret -* `/api/v1/namespaces/{namespace}/secrets/{name}` -- `DELETE`: delete a Secret -- `GET`: read the specified Secret -- `PATCH`: partially update the specified Secret -- `PUT`: replace the specified Secret - - -=== /api/v1/secrets - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Secret - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#secretlist-core-v1[`SecretList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/secrets - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Secret - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Secret - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#secretlist-core-v1[`SecretList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Secret - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| 201 - Created -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| 202 - Accepted -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/secrets/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Secret -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Secret - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Secret - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Secret - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Secret - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| 201 - Created -| xref:../security_apis/secret-core-v1.adoc#secret-core-v1[`Secret core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/security_apis/security-apis-index.adoc b/rest_api/security_apis/security-apis-index.adoc deleted file mode 100644 index bf07478fb0c5..000000000000 --- a/rest_api/security_apis/security-apis-index.adoc +++ /dev/null @@ -1,86 +0,0 @@ -[id="security-apis"] -= Security APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== CertificateSigningRequest [certificates.k8s.io/v1] - -Description:: - CertificateSigningRequest objects provide a mechanism to obtain x509 certificates by submitting a certificate signing request, and having it asynchronously approved and issued. - -Kubelets use this API to obtain: - 1. client certificates to authenticate to kube-apiserver (with the "kubernetes.io/kube-apiserver-client-kubelet" signerName). - 2. serving certificates for TLS endpoints kube-apiserver can connect to securely (with the "kubernetes.io/kubelet-serving" signerName). - -This API can be used to request client certificates to authenticate to kube-apiserver (with the "kubernetes.io/kube-apiserver-client" signerName), or to obtain certificates from custom non-Kubernetes signers. - -Type:: - `object` - -== CredentialsRequest [cloudcredential.openshift.io/v1] - -Description:: - CredentialsRequest is the Schema for the credentialsrequests API - -Type:: - `object` - -== PodSecurityPolicyReview [security.openshift.io/v1] - -Description:: - PodSecurityPolicyReview checks which service accounts (not users, since that would be cluster-wide) can create the `PodTemplateSpec` in question. - -Type:: - `object` - -== PodSecurityPolicySelfSubjectReview [security.openshift.io/v1] - -Description:: - PodSecurityPolicySelfSubjectReview checks whether this user/SA tuple can create the PodTemplateSpec - -Type:: - `object` - -== PodSecurityPolicySubjectReview [security.openshift.io/v1] - -Description:: - PodSecurityPolicySubjectReview checks whether a particular user/SA tuple can create the PodTemplateSpec. - -Type:: - `object` - -== RangeAllocation [security.openshift.io/v1] - -Description:: - RangeAllocation is used so we can easily expose a RangeAllocation typed for security group - -Type:: - `object` - -== Secret [core/v1] - -Description:: - Secret holds secret data of a certain type. The total bytes of the values in the Data field must be less than MaxSecretSize bytes. - -Type:: - `object` - -== SecurityContextConstraints [security.openshift.io/v1] - -Description:: - SecurityContextConstraints governs the ability to make requests that affect the SecurityContext that will be applied to a container. For historical reasons SCC was exposed under the core Kubernetes API group. That exposure is deprecated and will be removed in a future release - users should instead use the security.openshift.io group to manage SecurityContextConstraints. - -Type:: - `object` - -== ServiceAccount [core/v1] - -Description:: - ServiceAccount binds together: * a name, understood by users, and perhaps by peripheral systems, for an identity * a principal that can be authenticated and authorized * a set of secrets - -Type:: - `object` - diff --git a/rest_api/security_apis/securitycontextconstraints-security-openshift-io-v1.adoc b/rest_api/security_apis/securitycontextconstraints-security-openshift-io-v1.adoc deleted file mode 100644 index f56e2f5df5c8..000000000000 --- a/rest_api/security_apis/securitycontextconstraints-security-openshift-io-v1.adoc +++ /dev/null @@ -1,505 +0,0 @@ -[id="securitycontextconstraints-security-openshift-io-v1"] -= SecurityContextConstraints [security.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - SecurityContextConstraints governs the ability to make requests that affect the SecurityContext that will be applied to a container. For historical reasons SCC was exposed under the core Kubernetes API group. That exposure is deprecated and will be removed in a future release - users should instead use the security.openshift.io group to manage SecurityContextConstraints. - -Type:: - `object` - -Required:: - - `allowHostDirVolumePlugin` - - `allowHostIPC` - - `allowHostNetwork` - - `allowHostPID` - - `allowHostPorts` - - `allowPrivilegedContainer` - - `readOnlyRootFilesystem` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowHostDirVolumePlugin` -| `boolean` -| AllowHostDirVolumePlugin determines if the policy allow containers to use the HostDir volume plugin - -| `allowHostIPC` -| `boolean` -| AllowHostIPC determines if the policy allows host ipc in the containers. - -| `allowHostNetwork` -| `boolean` -| AllowHostNetwork determines if the policy allows the use of HostNetwork in the pod spec. - -| `allowHostPID` -| `boolean` -| AllowHostPID determines if the policy allows host pid in the containers. - -| `allowHostPorts` -| `boolean` -| AllowHostPorts determines if the policy allows host ports in the containers. - -| `allowPrivilegeEscalation` -| `` -| AllowPrivilegeEscalation determines if a pod can request to allow privilege escalation. If unspecified, defaults to true. - -| `allowPrivilegedContainer` -| `boolean` -| AllowPrivilegedContainer determines if a container can request to be run as privileged. - -| `allowedCapabilities` -| `` -| AllowedCapabilities is a list of capabilities that can be requested to add to the container. Capabilities in this field maybe added at the pod author's discretion. You must not list a capability in both AllowedCapabilities and RequiredDropCapabilities. To allow all capabilities you may use '*'. - -| `allowedFlexVolumes` -| `` -| AllowedFlexVolumes is a whitelist of allowed Flexvolumes. Empty or nil indicates that all Flexvolumes may be used. This parameter is effective only when the usage of the Flexvolumes is allowed in the "Volumes" field. - -| `allowedUnsafeSysctls` -| `` -| AllowedUnsafeSysctls is a list of explicitly allowed unsafe sysctls, defaults to none. Each entry is either a plain sysctl name or ends in "*" in which case it is considered as a prefix of allowed sysctls. Single * means all unsafe sysctls are allowed. Kubelet has to whitelist all allowed unsafe sysctls explicitly to avoid rejection. - Examples: e.g. "foo/*" allows "foo/bar", "foo/baz", etc. e.g. "foo.*" allows "foo.bar", "foo.baz", etc. - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `defaultAddCapabilities` -| `` -| DefaultAddCapabilities is the default set of capabilities that will be added to the container unless the pod spec specifically drops the capability. You may not list a capabiility in both DefaultAddCapabilities and RequiredDropCapabilities. - -| `defaultAllowPrivilegeEscalation` -| `` -| DefaultAllowPrivilegeEscalation controls the default setting for whether a process can gain more privileges than its parent process. - -| `forbiddenSysctls` -| `` -| ForbiddenSysctls is a list of explicitly forbidden sysctls, defaults to none. Each entry is either a plain sysctl name or ends in "*" in which case it is considered as a prefix of forbidden sysctls. Single * means all sysctls are forbidden. - Examples: e.g. "foo/*" forbids "foo/bar", "foo/baz", etc. e.g. "foo.*" forbids "foo.bar", "foo.baz", etc. - -| `fsGroup` -| `` -| FSGroup is the strategy that will dictate what fs group is used by the SecurityContext. - -| `groups` -| `` -| The groups that have permission to use this security context constraints - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `priority` -| `` -| Priority influences the sort order of SCCs when evaluating which SCCs to try first for a given pod request based on access in the Users and Groups fields. The higher the int, the higher priority. An unset value is considered a 0 priority. If scores for multiple SCCs are equal they will be sorted from most restrictive to least restrictive. If both priorities and restrictions are equal the SCCs will be sorted by name. - -| `readOnlyRootFilesystem` -| `boolean` -| ReadOnlyRootFilesystem when set to true will force containers to run with a read only root file system. If the container specifically requests to run with a non-read only root file system the SCC should deny the pod. If set to false the container may run with a read only root file system if it wishes but it will not be forced to. - -| `requiredDropCapabilities` -| `` -| RequiredDropCapabilities are the capabilities that will be dropped from the container. These are required to be dropped and cannot be added. - -| `runAsUser` -| `` -| RunAsUser is the strategy that will dictate what RunAsUser is used in the SecurityContext. - -| `seLinuxContext` -| `` -| SELinuxContext is the strategy that will dictate what labels will be set in the SecurityContext. - -| `seccompProfiles` -| `` -| SeccompProfiles lists the allowed profiles that may be set for the pod or container's seccomp annotations. An unset (nil) or empty value means that no profiles may be specifid by the pod or container. The wildcard '*' may be used to allow all profiles. When used to generate a value for a pod the first non-wildcard profile will be used as the default. - -| `supplementalGroups` -| `` -| SupplementalGroups is the strategy that will dictate what supplemental groups are used by the SecurityContext. - -| `users` -| `` -| The users who have permissions to use this security context constraints - -| `volumes` -| `` -| Volumes is a white list of allowed volume plugins. FSType corresponds directly with the field names of a VolumeSource (azureFile, configMap, emptyDir). To allow all volumes you may use "*". To allow no volumes, set to ["none"]. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/security.openshift.io/v1/securitycontextconstraints` -- `DELETE`: delete collection of SecurityContextConstraints -- `GET`: list objects of kind SecurityContextConstraints -- `POST`: create SecurityContextConstraints -* `/apis/security.openshift.io/v1/securitycontextconstraints/{name}` -- `DELETE`: delete SecurityContextConstraints -- `GET`: read the specified SecurityContextConstraints -- `PATCH`: partially update the specified SecurityContextConstraints -- `PUT`: replace the specified SecurityContextConstraints - - -=== /apis/security.openshift.io/v1/securitycontextconstraints - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of SecurityContextConstraints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind SecurityContextConstraints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#securitycontextconstraintslist-security-openshift-io-v1[`SecurityContextConstraintsList security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create SecurityContextConstraints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| 202 - Accepted -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/security.openshift.io/v1/securitycontextconstraints/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the SecurityContextConstraints -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete SecurityContextConstraints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified SecurityContextConstraints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified SecurityContextConstraints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified SecurityContextConstraints - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| 201 - Created -| xref:../security_apis/securitycontextconstraints-security-openshift-io-v1.adoc#securitycontextconstraints-security-openshift-io-v1[`SecurityContextConstraints security.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/security_apis/serviceaccount-core-v1.adoc b/rest_api/security_apis/serviceaccount-core-v1.adoc deleted file mode 100644 index 840b231a47f4..000000000000 --- a/rest_api/security_apis/serviceaccount-core-v1.adoc +++ /dev/null @@ -1,570 +0,0 @@ -[id="serviceaccount-core-v1"] -= ServiceAccount [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ServiceAccount binds together: * a name, understood by users, and perhaps by peripheral systems, for an identity * a principal that can be authenticated and authorized * a set of secrets - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `automountServiceAccountToken` -| `boolean` -| AutomountServiceAccountToken indicates whether pods running as this service account should have an API token automatically mounted. Can be overridden at the pod level. - -| `imagePullSecrets` -| xref:../objects/index.adoc#localobjectreference-core-v1[`array (LocalObjectReference core/v1)`] -| ImagePullSecrets is a list of references to secrets in the same namespace to use for pulling any images in pods that reference this ServiceAccount. ImagePullSecrets are distinct from Secrets because Secrets can be mounted in the pod, but ImagePullSecrets are only accessed by the kubelet. More info: https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `secrets` -| xref:../objects/index.adoc#objectreference-core-v1[`array (ObjectReference core/v1)`] -| Secrets is the list of secrets allowed to be used by pods running using this ServiceAccount. More info: https://kubernetes.io/docs/concepts/configuration/secret - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/serviceaccounts` -- `GET`: list or watch objects of kind ServiceAccount -* `/api/v1/namespaces/{namespace}/serviceaccounts` -- `DELETE`: delete collection of ServiceAccount -- `GET`: list or watch objects of kind ServiceAccount -- `POST`: create a ServiceAccount -* `/api/v1/namespaces/{namespace}/serviceaccounts/{name}` -- `DELETE`: delete a ServiceAccount -- `GET`: read the specified ServiceAccount -- `PATCH`: partially update the specified ServiceAccount -- `PUT`: replace the specified ServiceAccount -* `/api/v1/namespaces/{namespace}/serviceaccounts/{name}/token` -- `POST`: create token of a ServiceAccount - - -=== /api/v1/serviceaccounts - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ServiceAccount - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#serviceaccountlist-core-v1[`ServiceAccountList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/serviceaccounts - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ServiceAccount - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ServiceAccount - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#serviceaccountlist-core-v1[`ServiceAccountList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ServiceAccount - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 201 - Created -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 202 - Accepted -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/serviceaccounts/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ServiceAccount -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ServiceAccount - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 202 - Accepted -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ServiceAccount - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ServiceAccount - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ServiceAccount - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 201 - Created -| xref:../security_apis/serviceaccount-core-v1.adoc#serviceaccount-core-v1[`ServiceAccount core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/serviceaccounts/{name}/token - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the TokenRequest -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create token of a ServiceAccount - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#tokenrequest-authentication-k8s-io-v1[`TokenRequest authentication.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#tokenrequest-authentication-k8s-io-v1[`TokenRequest authentication.k8s.io/v1`] -| 201 - Created -| xref:../objects/index.adoc#tokenrequest-authentication-k8s-io-v1[`TokenRequest authentication.k8s.io/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#tokenrequest-authentication-k8s-io-v1[`TokenRequest authentication.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/csidriver-storage-k8s-io-v1.adoc b/rest_api/storage_apis/csidriver-storage-k8s-io-v1.adoc deleted file mode 100644 index 804fc80610ba..000000000000 --- a/rest_api/storage_apis/csidriver-storage-k8s-io-v1.adoc +++ /dev/null @@ -1,538 +0,0 @@ -[id="csidriver-storage-k8s-io-v1"] -= CSIDriver [storage.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CSIDriver captures information about a Container Storage Interface (CSI) volume driver deployed on the cluster. Kubernetes attach detach controller uses this object to determine whether attach is required. Kubelet uses this object to determine whether pod information needs to be passed on mount. CSIDriver objects are non-namespaced. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object metadata. metadata.Name indicates the name of the CSI driver that this object refers to; it MUST be the same name returned by the CSI GetPluginName() call for that driver. The driver name must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), dots (.), and alphanumerics between. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| CSIDriverSpec is the specification of a CSIDriver. - -|=== -..spec -Description:: - CSIDriverSpec is the specification of a CSIDriver. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `attachRequired` -| `boolean` -| attachRequired indicates this CSI volume driver requires an attach operation (because it implements the CSI ControllerPublishVolume() method), and that the Kubernetes attach detach controller should call the attach volume interface which checks the volumeattachment status and waits until the volume is attached before proceeding to mounting. The CSI external-attacher coordinates with CSI volume driver and updates the volumeattachment status when the attach operation is complete. If the CSIDriverRegistry feature gate is enabled and the value is specified to false, the attach operation will be skipped. Otherwise the attach operation will be called. - -| `fsGroupPolicy` -| `string` -| Defines if the underlying volume supports changing ownership and permission of the volume before being mounted. Refer to the specific FSGroupPolicy values for additional details. This field is alpha-level, and is only honored by servers that enable the CSIVolumeFSGroupPolicy feature gate. - -| `podInfoOnMount` -| `boolean` -| If set to true, podInfoOnMount indicates this CSI volume driver requires additional pod information (like podName, podUID, etc.) during mount operations. If set to false, pod information will not be passed on mount. Default is false. The CSI driver specifies podInfoOnMount as part of driver deployment. If true, Kubelet will pass pod information as VolumeContext in the CSI NodePublishVolume() calls. The CSI driver is responsible for parsing and validating the information passed in as VolumeContext. The following VolumeConext will be passed if podInfoOnMount is set to true. This list might grow, but the prefix will be used. "csi.storage.k8s.io/pod.name": pod.Name "csi.storage.k8s.io/pod.namespace": pod.Namespace "csi.storage.k8s.io/pod.uid": string(pod.UID) "csi.storage.k8s.io/ephemeral": "true" iff the volume is an ephemeral inline volume - defined by a CSIVolumeSource, otherwise "false" - -"csi.storage.k8s.io/ephemeral" is a new feature in Kubernetes 1.16. It is only required for drivers which support both the "Persistent" and "Ephemeral" VolumeLifecycleMode. Other drivers can leave pod info disabled and/or ignore this field. As Kubernetes 1.15 doesn't support this field, drivers can only support one mode when deployed on such a cluster and the deployment determines which mode that is, for example via a command line parameter of the driver. - -| `requiresRepublish` -| `boolean` -| RequiresRepublish indicates the CSI driver wants `NodePublishVolume` being periodically called to reflect any possible change in the mounted volume. This field defaults to false. - -Note: After a successful initial NodePublishVolume call, subsequent calls to NodePublishVolume should only update the contents of the volume. New mount points will not be seen by a running container. - -This is an alpha feature and only available when the CSIServiceAccountToken feature is enabled. - -| `storageCapacity` -| `boolean` -| If set to true, storageCapacity indicates that the CSI volume driver wants pod scheduling to consider the storage capacity that the driver deployment will report by creating CSIStorageCapacity objects with capacity information. - -The check can be enabled immediately when deploying a driver. In that case, provisioning new volumes with late binding will pause until the driver deployment has published some suitable CSIStorageCapacity object. - -Alternatively, the driver can be deployed with the field unset or false and it can be flipped later when storage capacity information has been published. - -This is an alpha field and only available when the CSIStorageCapacity feature is enabled. The default is false. - -| `tokenRequests` -| `array` -| TokenRequests indicates the CSI driver needs pods' service account tokens it is mounting volume for to do necessary authentication. Kubelet will pass the tokens in VolumeContext in the CSI NodePublishVolume calls. The CSI driver should parse and validate the following VolumeContext: "csi.storage.k8s.io/serviceAccount.tokens": { - "<audience>": { - "token": <token>, - "expirationTimestamp": <expiration timestamp in RFC3339>, - }, - ... -} - -Note: Audience in each TokenRequest should be different and at most one token is empty string. To receive a new token after expiry, RequiresRepublish can be used to trigger NodePublishVolume periodically. - -This is an alpha feature and only available when the CSIServiceAccountToken feature is enabled. - -| `tokenRequests[]` -| `object` -| TokenRequest contains parameters of a service account token. - -| `volumeLifecycleModes` -| `array (string)` -| volumeLifecycleModes defines what kind of volumes this CSI volume driver supports. The default if the list is empty is "Persistent", which is the usage defined by the CSI specification and implemented in Kubernetes via the usual PV/PVC mechanism. The other mode is "Ephemeral". In this mode, volumes are defined inline inside the pod spec with CSIVolumeSource and their lifecycle is tied to the lifecycle of that pod. A driver has to be aware of this because it is only going to get a NodePublishVolume call for such a volume. For more information about implementing this mode, see https://kubernetes-csi.github.io/docs/ephemeral-local-volumes.html A driver can support one or more of these modes and more modes may be added in the future. This field is beta. - -|=== -..spec.tokenRequests -Description:: - TokenRequests indicates the CSI driver needs pods' service account tokens it is mounting volume for to do necessary authentication. Kubelet will pass the tokens in VolumeContext in the CSI NodePublishVolume calls. The CSI driver should parse and validate the following VolumeContext: "csi.storage.k8s.io/serviceAccount.tokens": { - "<audience>": { - "token": <token>, - "expirationTimestamp": <expiration timestamp in RFC3339>, - }, - ... -} - -Note: Audience in each TokenRequest should be different and at most one token is empty string. To receive a new token after expiry, RequiresRepublish can be used to trigger NodePublishVolume periodically. - -This is an alpha feature and only available when the CSIServiceAccountToken feature is enabled. - -Type:: - `array` - - - - -..spec.tokenRequests[] -Description:: - TokenRequest contains parameters of a service account token. - -Type:: - `object` - -Required:: - - `audience` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `audience` -| `string` -| Audience is the intended audience of the token in "TokenRequestSpec". It will default to the audiences of kube apiserver. - -| `expirationSeconds` -| `integer` -| ExpirationSeconds is the duration of validity of the token in "TokenRequestSpec". It has the same default value of "ExpirationSeconds" in "TokenRequestSpec". - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/storage.k8s.io/v1/csidrivers` -- `DELETE`: delete collection of CSIDriver -- `GET`: list or watch objects of kind CSIDriver -- `POST`: create a CSIDriver -* `/apis/storage.k8s.io/v1/csidrivers/{name}` -- `DELETE`: delete a CSIDriver -- `GET`: read the specified CSIDriver -- `PATCH`: partially update the specified CSIDriver -- `PUT`: replace the specified CSIDriver - - -=== /apis/storage.k8s.io/v1/csidrivers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind CSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#csidriverlist-storage-k8s-io-v1[`CSIDriverList storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/storage.k8s.io/v1/csidrivers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CSIDriver -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CSIDriver - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/csidriver-storage-k8s-io-v1.adoc#csidriver-storage-k8s-io-v1[`CSIDriver storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/csinode-storage-k8s-io-v1.adoc b/rest_api/storage_apis/csinode-storage-k8s-io-v1.adoc deleted file mode 100644 index ade45924eb43..000000000000 --- a/rest_api/storage_apis/csinode-storage-k8s-io-v1.adoc +++ /dev/null @@ -1,511 +0,0 @@ -[id="csinode-storage-k8s-io-v1"] -= CSINode [storage.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CSINode holds information about all CSI drivers installed on a node. CSI drivers do not need to create the CSINode object directly. As long as they use the node-driver-registrar sidecar container, the kubelet will automatically populate the CSINode object for the CSI driver as part of kubelet plugin registration. CSINode has the same name as a node. If the object is missing, it means either there are no CSI Drivers available on the node, or the Kubelet version is low enough that it doesn't create this object. CSINode has an OwnerReference that points to the corresponding node object. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| metadata.name must be the Kubernetes node name. - -| `spec` -| `object` -| CSINodeSpec holds information about the specification of all CSI drivers installed on a node - -|=== -..spec -Description:: - CSINodeSpec holds information about the specification of all CSI drivers installed on a node - -Type:: - `object` - -Required:: - - `drivers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `drivers` -| `array` -| drivers is a list of information of all CSI Drivers existing on a node. If all drivers in the list are uninstalled, this can become empty. - -| `drivers[]` -| `object` -| CSINodeDriver holds information about the specification of one CSI driver installed on a node - -|=== -..spec.drivers -Description:: - drivers is a list of information of all CSI Drivers existing on a node. If all drivers in the list are uninstalled, this can become empty. - -Type:: - `array` - - - - -..spec.drivers[] -Description:: - CSINodeDriver holds information about the specification of one CSI driver installed on a node - -Type:: - `object` - -Required:: - - `name` - - `nodeID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allocatable` -| `object` -| VolumeNodeResources is a set of resource limits for scheduling of volumes. - -| `name` -| `string` -| This is the name of the CSI driver that this object refers to. This MUST be the same name returned by the CSI GetPluginName() call for that driver. - -| `nodeID` -| `string` -| nodeID of the node from the driver point of view. This field enables Kubernetes to communicate with storage systems that do not share the same nomenclature for nodes. For example, Kubernetes may refer to a given node as "node1", but the storage system may refer to the same node as "nodeA". When Kubernetes issues a command to the storage system to attach a volume to a specific node, it can use this field to refer to the node name using the ID that the storage system will understand, e.g. "nodeA" instead of "node1". This field is required. - -| `topologyKeys` -| `array (string)` -| topologyKeys is the list of keys supported by the driver. When a driver is initialized on a cluster, it provides a set of topology keys that it understands (e.g. "company.com/zone", "company.com/region"). When a driver is initialized on a node, it provides the same topology keys along with values. Kubelet will expose these topology keys as labels on its own node object. When Kubernetes does topology aware provisioning, it can use this list to determine which labels it should retrieve from the node object and pass back to the driver. It is possible for different nodes to use different topology keys. This can be empty if driver does not support topology. - -|=== -..spec.drivers[].allocatable -Description:: - VolumeNodeResources is a set of resource limits for scheduling of volumes. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `count` -| `integer` -| Maximum number of unique volumes managed by the CSI driver that can be used on a node. A volume that is both attached and mounted on a node is considered to be used once, not twice. The same rule applies for a unique volume that is shared among multiple pods on the same node. If this field is not specified, then the supported number of volumes on this node is unbounded. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/storage.k8s.io/v1/csinodes` -- `DELETE`: delete collection of CSINode -- `GET`: list or watch objects of kind CSINode -- `POST`: create a CSINode -* `/apis/storage.k8s.io/v1/csinodes/{name}` -- `DELETE`: delete a CSINode -- `GET`: read the specified CSINode -- `PATCH`: partially update the specified CSINode -- `PUT`: replace the specified CSINode - - -=== /apis/storage.k8s.io/v1/csinodes - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CSINode - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind CSINode - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#csinodelist-storage-k8s-io-v1[`CSINodeList storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CSINode - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/storage.k8s.io/v1/csinodes/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CSINode -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CSINode - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CSINode - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CSINode - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CSINode - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/csinode-storage-k8s-io-v1.adoc#csinode-storage-k8s-io-v1[`CSINode storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/persistentvolumeclaim-core-v1.adoc b/rest_api/storage_apis/persistentvolumeclaim-core-v1.adoc deleted file mode 100644 index 2a298ba45066..000000000000 --- a/rest_api/storage_apis/persistentvolumeclaim-core-v1.adoc +++ /dev/null @@ -1,703 +0,0 @@ -[id="persistentvolumeclaim-core-v1"] -= PersistentVolumeClaim [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PersistentVolumeClaim is a user's request for and claim to a persistent volume - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| PersistentVolumeClaimSpec describes the common attributes of storage devices and allows a Source for provider-specific attributes - -| `status` -| `object` -| PersistentVolumeClaimStatus is the current status of a persistent volume claim. - -|=== -..spec -Description:: - PersistentVolumeClaimSpec describes the common attributes of storage devices and allows a Source for provider-specific attributes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `dataSource` -| xref:../objects/index.adoc#typedlocalobjectreference-core-v1[`TypedLocalObjectReference core/v1`] -| This field can be used to specify either: * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot) * An existing PVC (PersistentVolumeClaim) * An existing custom resource that implements data population (Alpha) In order to use custom resource types that implement data population, the AnyVolumeDataSource feature gate must be enabled. If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. - -| `resources` -| xref:../objects/index.adoc#resourcerequirements-core-v1[`ResourceRequirements core/v1`] -| Resources represents the minimum resources the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| A label query over volumes to consider for binding. - -| `storageClassName` -| `string` -| Name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1 - -| `volumeMode` -| `string` -| volumeMode defines what type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. - -| `volumeName` -| `string` -| VolumeName is the binding reference to the PersistentVolume backing this claim. - -|=== -..status -Description:: - PersistentVolumeClaimStatus is the current status of a persistent volume claim. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains the actual access modes the volume backing the PVC has. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1 - -| `capacity` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Represents the actual resources of the underlying volume. - -| `conditions` -| xref:../objects/index.adoc#persistentvolumeclaimcondition-core-v1[`array (PersistentVolumeClaimCondition core/v1)`] -| Current Condition of persistent volume claim. If underlying persistent volume is being resized then the Condition will be set to 'ResizeStarted'. - -| `phase` -| `string` -| Phase represents the current phase of PersistentVolumeClaim. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/persistentvolumeclaims` -- `GET`: list or watch objects of kind PersistentVolumeClaim -* `/api/v1/namespaces/{namespace}/persistentvolumeclaims` -- `DELETE`: delete collection of PersistentVolumeClaim -- `GET`: list or watch objects of kind PersistentVolumeClaim -- `POST`: create a PersistentVolumeClaim -* `/api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}` -- `DELETE`: delete a PersistentVolumeClaim -- `GET`: read the specified PersistentVolumeClaim -- `PATCH`: partially update the specified PersistentVolumeClaim -- `PUT`: replace the specified PersistentVolumeClaim -* `/api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status` -- `GET`: read status of the specified PersistentVolumeClaim -- `PATCH`: partially update status of the specified PersistentVolumeClaim -- `PUT`: replace status of the specified PersistentVolumeClaim - - -=== /api/v1/persistentvolumeclaims - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PersistentVolumeClaim - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#persistentvolumeclaimlist-core-v1[`PersistentVolumeClaimList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/persistentvolumeclaims - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#persistentvolumeclaimlist-core-v1[`PersistentVolumeClaimList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 201 - Created -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 202 - Accepted -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PersistentVolumeClaim -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 202 - Accepted -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 201 - Created -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/persistentvolumeclaims/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PersistentVolumeClaim -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified PersistentVolumeClaim - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified PersistentVolumeClaim - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 201 - Created -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`PersistentVolumeClaim core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/storage-apis-index.adoc b/rest_api/storage_apis/storage-apis-index.adoc deleted file mode 100644 index 4da06bdc60dd..000000000000 --- a/rest_api/storage_apis/storage-apis-index.adoc +++ /dev/null @@ -1,92 +0,0 @@ -[id="storage-apis"] -= Storage APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== CSIDriver [storage.k8s.io/v1] - -Description:: - CSIDriver captures information about a Container Storage Interface (CSI) volume driver deployed on the cluster. Kubernetes attach detach controller uses this object to determine whether attach is required. Kubelet uses this object to determine whether pod information needs to be passed on mount. CSIDriver objects are non-namespaced. - -Type:: - `object` - -== CSINode [storage.k8s.io/v1] - -Description:: - CSINode holds information about all CSI drivers installed on a node. CSI drivers do not need to create the CSINode object directly. As long as they use the node-driver-registrar sidecar container, the kubelet will automatically populate the CSINode object for the CSI driver as part of kubelet plugin registration. CSINode has the same name as a node. If the object is missing, it means either there are no CSI Drivers available on the node, or the Kubelet version is low enough that it doesn't create this object. CSINode has an OwnerReference that points to the corresponding node object. - -Type:: - `object` - -== PersistentVolumeClaim [core/v1] - -Description:: - PersistentVolumeClaim is a user's request for and claim to a persistent volume - -Type:: - `object` - -== StorageClass [storage.k8s.io/v1] - -Description:: - StorageClass describes the parameters for a class of storage for which PersistentVolumes can be dynamically provisioned. - -StorageClasses are non-namespaced; the name of the storage class according to etcd is in ObjectMeta.Name. - -Type:: - `object` - -== StorageState [migration.k8s.io/v1alpha1] - -Description:: - The state of the storage of a specific resource. - -Type:: - `object` - -== StorageVersionMigration [migration.k8s.io/v1alpha1] - -Description:: - StorageVersionMigration represents a migration of stored data to the latest storage version. - -Type:: - `object` - -== VolumeAttachment [storage.k8s.io/v1] - -Description:: - VolumeAttachment captures the intent to attach or detach the specified volume to/from the specified node. - -VolumeAttachment objects are non-namespaced. - -Type:: - `object` - -== VolumeSnapshot [snapshot.storage.k8s.io/v1] - -Description:: - VolumeSnapshot is a user's request for either creating a point-in-time snapshot of a persistent volume, or binding to a pre-existing snapshot. - -Type:: - `object` - -== VolumeSnapshotClass [snapshot.storage.k8s.io/v1] - -Description:: - VolumeSnapshotClass specifies parameters that a underlying storage system uses when creating a volume snapshot. A specific VolumeSnapshotClass is used by specifying its name in a VolumeSnapshot object. VolumeSnapshotClasses are non-namespaced - -Type:: - `object` - -== VolumeSnapshotContent [snapshot.storage.k8s.io/v1] - -Description:: - VolumeSnapshotContent represents the actual "on-disk" snapshot object in the underlying storage system - -Type:: - `object` - diff --git a/rest_api/storage_apis/storageclass-storage-k8s-io-v1.adoc b/rest_api/storage_apis/storageclass-storage-k8s-io-v1.adoc deleted file mode 100644 index 23043a0a8c3e..000000000000 --- a/rest_api/storage_apis/storageclass-storage-k8s-io-v1.adoc +++ /dev/null @@ -1,449 +0,0 @@ -[id="storageclass-storage-k8s-io-v1"] -= StorageClass [storage.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - StorageClass describes the parameters for a class of storage for which PersistentVolumes can be dynamically provisioned. - -StorageClasses are non-namespaced; the name of the storage class according to etcd is in ObjectMeta.Name. - -Type:: - `object` - -Required:: - - `provisioner` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowVolumeExpansion` -| `boolean` -| AllowVolumeExpansion shows whether the storage class allow volume expand - -| `allowedTopologies` -| xref:../objects/index.adoc#topologyselectorterm-core-v1[`array (TopologySelectorTerm core/v1)`] -| Restrict the node topologies where volumes can be dynamically provisioned. Each volume plugin defines its own supported topology specifications. An empty TopologySelectorTerm list means there is no topology restriction. This field is only honored by servers that enable the VolumeScheduling feature. - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `mountOptions` -| `array (string)` -| Dynamically provisioned PersistentVolumes of this storage class are created with these mountOptions, e.g. ["ro", "soft"]. Not validated - mount of the PVs will simply fail if one is invalid. - -| `parameters` -| `object (string)` -| Parameters holds the parameters for the provisioner that should create volumes of this storage class. - -| `provisioner` -| `string` -| Provisioner indicates the type of the provisioner. - -| `reclaimPolicy` -| `string` -| Dynamically provisioned PersistentVolumes of this storage class are created with this reclaimPolicy. Defaults to Delete. - -| `volumeBindingMode` -| `string` -| VolumeBindingMode indicates how PersistentVolumeClaims should be provisioned and bound. When unset, VolumeBindingImmediate is used. This field is only honored by servers that enable the VolumeScheduling feature. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/storage.k8s.io/v1/storageclasses` -- `DELETE`: delete collection of StorageClass -- `GET`: list or watch objects of kind StorageClass -- `POST`: create a StorageClass -* `/apis/storage.k8s.io/v1/storageclasses/{name}` -- `DELETE`: delete a StorageClass -- `GET`: read the specified StorageClass -- `PATCH`: partially update the specified StorageClass -- `PUT`: replace the specified StorageClass - - -=== /apis/storage.k8s.io/v1/storageclasses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of StorageClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind StorageClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#storageclasslist-storage-k8s-io-v1[`StorageClassList storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a StorageClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/storage.k8s.io/v1/storageclasses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the StorageClass -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a StorageClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified StorageClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified StorageClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified StorageClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/storageclass-storage-k8s-io-v1.adoc#storageclass-storage-k8s-io-v1[`StorageClass storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc b/rest_api/storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc deleted file mode 100644 index 4b7100f740f8..000000000000 --- a/rest_api/storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc +++ /dev/null @@ -1,608 +0,0 @@ -[id="storagestate-migration-k8s-io-v1alpha1"] -= StorageState [migration.k8s.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - The state of the storage of a specific resource. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of the storage state. - -| `status` -| `object` -| Status of the storage state. - -|=== -..spec -Description:: - Specification of the storage state. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `resource` -| `object` -| The resource this storageState is about. - -|=== -..spec.resource -Description:: - The resource this storageState is about. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| The name of the group. - -| `resource` -| `string` -| The name of the resource. - -|=== -..status -Description:: - Status of the storage state. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `currentStorageVersionHash` -| `string` -| The hash value of the current storage version, as shown in the discovery document served by the API server. Storage Version is the version to which objects are converted to before persisted. - -| `lastHeartbeatTime` -| `string` -| LastHeartbeatTime is the last time the storage migration triggering controller checks the storage version hash of this resource in the discovery document and updates this field. - -| `persistedStorageVersionHashes` -| `array (string)` -| The hash values of storage versions that persisted instances of spec.resource might still be encoded in. "Unknown" is a valid value in the list, and is the default value. It is not safe to upgrade or downgrade to an apiserver binary that does not support all versions listed in this field, or if "Unknown" is listed. Once the storage version migration for this resource has completed, the value of this field is refined to only contain the currentStorageVersionHash. Once the apiserver has changed the storage version, the new storage version is appended to the list. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/migration.k8s.io/v1alpha1/storagestates` -- `DELETE`: delete collection of StorageState -- `GET`: list objects of kind StorageState -- `POST`: create a StorageState -* `/apis/migration.k8s.io/v1alpha1/storagestates/{name}` -- `DELETE`: delete a StorageState -- `GET`: read the specified StorageState -- `PATCH`: partially update the specified StorageState -- `PUT`: replace the specified StorageState -* `/apis/migration.k8s.io/v1alpha1/storagestates/{name}/status` -- `GET`: read status of the specified StorageState -- `PATCH`: partially update status of the specified StorageState -- `PUT`: replace status of the specified StorageState - - -=== /apis/migration.k8s.io/v1alpha1/storagestates - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#storagestatelist-migration-k8s-io-v1alpha1[`StorageStateList migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 201 - Created -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 202 - Accepted -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/migration.k8s.io/v1alpha1/storagestates/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the StorageState -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 201 - Created -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/migration.k8s.io/v1alpha1/storagestates/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the StorageState -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified StorageState - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 201 - Created -| xref:../storage_apis/storagestate-migration-k8s-io-v1alpha1.adoc#storagestate-migration-k8s-io-v1alpha1[`StorageState migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc b/rest_api/storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc deleted file mode 100644 index 967969fafb1b..000000000000 --- a/rest_api/storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc +++ /dev/null @@ -1,662 +0,0 @@ -[id="storageversionmigration-migration-k8s-io-v1alpha1"] -= StorageVersionMigration [migration.k8s.io/v1alpha1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - StorageVersionMigration represents a migration of stored data to the latest storage version. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| Specification of the migration. - -| `status` -| `object` -| Status of the migration. - -|=== -..spec -Description:: - Specification of the migration. - -Type:: - `object` - -Required:: - - `resource` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `continueToken` -| `string` -| The token used in the list options to get the next chunk of objects to migrate. When the .status.conditions indicates the migration is "Running", users can use this token to check the progress of the migration. - -| `resource` -| `object` -| The resource that is being migrated. The migrator sends requests to the endpoint serving the resource. Immutable. - -|=== -..spec.resource -Description:: - The resource that is being migrated. The migrator sends requests to the endpoint serving the resource. Immutable. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `group` -| `string` -| The name of the group. - -| `resource` -| `string` -| The name of the resource. - -| `version` -| `string` -| The name of the version. - -|=== -..status -Description:: - Status of the migration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| The latest available observations of the migration's current state. - -| `conditions[]` -| `object` -| Describes the state of a migration at a certain point. - -|=== -..status.conditions -Description:: - The latest available observations of the migration's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - Describes the state of a migration at a certain point. - -Type:: - `object` - -Required:: - - `status` - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastUpdateTime` -| `string` -| The last time this condition was updated. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of the condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/migration.k8s.io/v1alpha1/storageversionmigrations` -- `DELETE`: delete collection of StorageVersionMigration -- `GET`: list objects of kind StorageVersionMigration -- `POST`: create a StorageVersionMigration -* `/apis/migration.k8s.io/v1alpha1/storageversionmigrations/{name}` -- `DELETE`: delete a StorageVersionMigration -- `GET`: read the specified StorageVersionMigration -- `PATCH`: partially update the specified StorageVersionMigration -- `PUT`: replace the specified StorageVersionMigration -* `/apis/migration.k8s.io/v1alpha1/storageversionmigrations/{name}/status` -- `GET`: read status of the specified StorageVersionMigration -- `PATCH`: partially update status of the specified StorageVersionMigration -- `PUT`: replace status of the specified StorageVersionMigration - - -=== /apis/migration.k8s.io/v1alpha1/storageversionmigrations - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#storageversionmigrationlist-migration-k8s-io-v1alpha1[`StorageVersionMigrationList migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 201 - Created -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 202 - Accepted -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/migration.k8s.io/v1alpha1/storageversionmigrations/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the StorageVersionMigration -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 201 - Created -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/migration.k8s.io/v1alpha1/storageversionmigrations/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the StorageVersionMigration -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified StorageVersionMigration - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 201 - Created -| xref:../storage_apis/storageversionmigration-migration-k8s-io-v1alpha1.adoc#storageversionmigration-migration-k8s-io-v1alpha1[`StorageVersionMigration migration.k8s.io/v1alpha1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/volumeattachment-storage-k8s-io-v1.adoc b/rest_api/storage_apis/volumeattachment-storage-k8s-io-v1.adoc deleted file mode 100644 index ad9a0c7eefae..000000000000 --- a/rest_api/storage_apis/volumeattachment-storage-k8s-io-v1.adoc +++ /dev/null @@ -1,685 +0,0 @@ -[id="volumeattachment-storage-k8s-io-v1"] -= VolumeAttachment [storage.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - VolumeAttachment captures the intent to attach or detach the specified volume to/from the specified node. - -VolumeAttachment objects are non-namespaced. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| VolumeAttachmentSpec is the specification of a VolumeAttachment request. - -| `status` -| `object` -| VolumeAttachmentStatus is the status of a VolumeAttachment request. - -|=== -..spec -Description:: - VolumeAttachmentSpec is the specification of a VolumeAttachment request. - -Type:: - `object` - -Required:: - - `attacher` - - `source` - - `nodeName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `attacher` -| `string` -| Attacher indicates the name of the volume driver that MUST handle this request. This is the name returned by GetPluginName(). - -| `nodeName` -| `string` -| The node that the volume should be attached to. - -| `source` -| `object` -| VolumeAttachmentSource represents a volume that should be attached. Right now only PersistenVolumes can be attached via external attacher, in future we may allow also inline volumes in pods. Exactly one member can be set. - -|=== -..spec.source -Description:: - VolumeAttachmentSource represents a volume that should be attached. Right now only PersistenVolumes can be attached via external attacher, in future we may allow also inline volumes in pods. Exactly one member can be set. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `inlineVolumeSpec` -| xref:../objects/index.adoc#persistentvolumespec-core-v1[`PersistentVolumeSpec core/v1`] -| inlineVolumeSpec contains all the information necessary to attach a persistent volume defined by a pod's inline VolumeSource. This field is populated only for the CSIMigration feature. It contains translated fields from a pod's inline VolumeSource to a PersistentVolumeSpec. This field is alpha-level and is only honored by servers that enabled the CSIMigration feature. - -| `persistentVolumeName` -| `string` -| Name of the persistent volume to attach. - -|=== -..status -Description:: - VolumeAttachmentStatus is the status of a VolumeAttachment request. - -Type:: - `object` - -Required:: - - `attached` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `attachError` -| `object` -| VolumeError captures an error encountered during a volume operation. - -| `attached` -| `boolean` -| Indicates the volume is successfully attached. This field must only be set by the entity completing the attach operation, i.e. the external-attacher. - -| `attachmentMetadata` -| `object (string)` -| Upon successful attach, this field is populated with any information returned by the attach operation that must be passed into subsequent WaitForAttach or Mount calls. This field must only be set by the entity completing the attach operation, i.e. the external-attacher. - -| `detachError` -| `object` -| VolumeError captures an error encountered during a volume operation. - -|=== -..status.attachError -Description:: - VolumeError captures an error encountered during a volume operation. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `message` -| `string` -| String detailing the error encountered during Attach or Detach operation. This string may be logged, so it should not contain sensitive information. - -| `time` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Time the error was encountered. - -|=== -..status.detachError -Description:: - VolumeError captures an error encountered during a volume operation. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `message` -| `string` -| String detailing the error encountered during Attach or Detach operation. This string may be logged, so it should not contain sensitive information. - -| `time` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Time the error was encountered. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/storage.k8s.io/v1/volumeattachments` -- `DELETE`: delete collection of VolumeAttachment -- `GET`: list or watch objects of kind VolumeAttachment -- `POST`: create a VolumeAttachment -* `/apis/storage.k8s.io/v1/volumeattachments/{name}` -- `DELETE`: delete a VolumeAttachment -- `GET`: read the specified VolumeAttachment -- `PATCH`: partially update the specified VolumeAttachment -- `PUT`: replace the specified VolumeAttachment -* `/apis/storage.k8s.io/v1/volumeattachments/{name}/status` -- `GET`: read status of the specified VolumeAttachment -- `PATCH`: partially update status of the specified VolumeAttachment -- `PUT`: replace status of the specified VolumeAttachment - - -=== /apis/storage.k8s.io/v1/volumeattachments - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#volumeattachmentlist-storage-k8s-io-v1[`VolumeAttachmentList storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/storage.k8s.io/v1/volumeattachments/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the VolumeAttachment -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/storage.k8s.io/v1/volumeattachments/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the VolumeAttachment -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified VolumeAttachment - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified VolumeAttachment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumeattachment-storage-k8s-io-v1.adoc#volumeattachment-storage-k8s-io-v1[`VolumeAttachment storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc b/rest_api/storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc deleted file mode 100644 index 71c43395c716..000000000000 --- a/rest_api/storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc +++ /dev/null @@ -1,728 +0,0 @@ -[id="volumesnapshot-snapshot-storage-k8s-io-v1"] -= VolumeSnapshot [snapshot.storage.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - VolumeSnapshot is a user's request for either creating a point-in-time snapshot of a persistent volume, or binding to a pre-existing snapshot. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec defines the desired characteristics of a snapshot requested by a user. More info: https://kubernetes.io/docs/concepts/storage/volume-snapshots#volumesnapshots Required. - -| `status` -| `object` -| status represents the current information of a snapshot. Consumers must verify binding between VolumeSnapshot and VolumeSnapshotContent objects is successful (by validating that both VolumeSnapshot and VolumeSnapshotContent point at each other) before using this object. - -|=== -..spec -Description:: - spec defines the desired characteristics of a snapshot requested by a user. More info: https://kubernetes.io/docs/concepts/storage/volume-snapshots#volumesnapshots Required. - -Type:: - `object` - -Required:: - - `source` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `source` -| `object` -| source specifies where a snapshot will be created from. This field is immutable after creation. Required. - -| `volumeSnapshotClassName` -| `string` -| VolumeSnapshotClassName is the name of the VolumeSnapshotClass requested by the VolumeSnapshot. VolumeSnapshotClassName may be left nil to indicate that the default SnapshotClass should be used. A given cluster may have multiple default Volume SnapshotClasses: one default per CSI Driver. If a VolumeSnapshot does not specify a SnapshotClass, VolumeSnapshotSource will be checked to figure out what the associated CSI Driver is, and the default VolumeSnapshotClass associated with that CSI Driver will be used. If more than one VolumeSnapshotClass exist for a given CSI Driver and more than one have been marked as default, CreateSnapshot will fail and generate an event. Empty string is not allowed for this field. - -|=== -..spec.source -Description:: - source specifies where a snapshot will be created from. This field is immutable after creation. Required. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `persistentVolumeClaimName` -| `string` -| persistentVolumeClaimName specifies the name of the PersistentVolumeClaim object representing the volume from which a snapshot should be created. This PVC is assumed to be in the same namespace as the VolumeSnapshot object. This field should be set if the snapshot does not exists, and needs to be created. This field is immutable. - -| `volumeSnapshotContentName` -| `string` -| volumeSnapshotContentName specifies the name of a pre-existing VolumeSnapshotContent object representing an existing volume snapshot. This field should be set if the snapshot already exists and only needs a representation in Kubernetes. This field is immutable. - -|=== -..status -Description:: - status represents the current information of a snapshot. Consumers must verify binding between VolumeSnapshot and VolumeSnapshotContent objects is successful (by validating that both VolumeSnapshot and VolumeSnapshotContent point at each other) before using this object. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `boundVolumeSnapshotContentName` -| `string` -| boundVolumeSnapshotContentName is the name of the VolumeSnapshotContent object to which this VolumeSnapshot object intends to bind to. If not specified, it indicates that the VolumeSnapshot object has not been successfully bound to a VolumeSnapshotContent object yet. NOTE: To avoid possible security issues, consumers must verify binding between VolumeSnapshot and VolumeSnapshotContent objects is successful (by validating that both VolumeSnapshot and VolumeSnapshotContent point at each other) before using this object. - -| `creationTime` -| `string` -| creationTime is the timestamp when the point-in-time snapshot is taken by the underlying storage system. In dynamic snapshot creation case, this field will be filled in by the snapshot controller with the "creation_time" value returned from CSI "CreateSnapshot" gRPC call. For a pre-existing snapshot, this field will be filled with the "creation_time" value returned from the CSI "ListSnapshots" gRPC call if the driver supports it. If not specified, it may indicate that the creation time of the snapshot is unknown. - -| `error` -| `object` -| error is the last observed error during snapshot creation, if any. This field could be helpful to upper level controllers(i.e., application controller) to decide whether they should continue on waiting for the snapshot to be created based on the type of error reported. The snapshot controller will keep retrying when an error occurrs during the snapshot creation. Upon success, this error field will be cleared. - -| `readyToUse` -| `boolean` -| readyToUse indicates if the snapshot is ready to be used to restore a volume. In dynamic snapshot creation case, this field will be filled in by the snapshot controller with the "ready_to_use" value returned from CSI "CreateSnapshot" gRPC call. For a pre-existing snapshot, this field will be filled with the "ready_to_use" value returned from the CSI "ListSnapshots" gRPC call if the driver supports it, otherwise, this field will be set to "True". If not specified, it means the readiness of a snapshot is unknown. - -| `restoreSize` -| `integer-or-string` -| restoreSize represents the minimum size of volume required to create a volume from this snapshot. In dynamic snapshot creation case, this field will be filled in by the snapshot controller with the "size_bytes" value returned from CSI "CreateSnapshot" gRPC call. For a pre-existing snapshot, this field will be filled with the "size_bytes" value returned from the CSI "ListSnapshots" gRPC call if the driver supports it. When restoring a volume from this snapshot, the size of the volume MUST NOT be smaller than the restoreSize if it is specified, otherwise the restoration will fail. If not specified, it indicates that the size is unknown. - -|=== -..status.error -Description:: - error is the last observed error during snapshot creation, if any. This field could be helpful to upper level controllers(i.e., application controller) to decide whether they should continue on waiting for the snapshot to be created based on the type of error reported. The snapshot controller will keep retrying when an error occurrs during the snapshot creation. Upon success, this error field will be cleared. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `message` -| `string` -| message is a string detailing the encountered error during snapshot creation if specified. NOTE: message may be logged, and it should not contain sensitive information. - -| `time` -| `string` -| time is the timestamp when the error was encountered. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/snapshot.storage.k8s.io/v1/volumesnapshots` -- `GET`: list objects of kind VolumeSnapshot -* `/apis/snapshot.storage.k8s.io/v1/namespaces/{namespace}/volumesnapshots` -- `DELETE`: delete collection of VolumeSnapshot -- `GET`: list objects of kind VolumeSnapshot -- `POST`: create a VolumeSnapshot -* `/apis/snapshot.storage.k8s.io/v1/namespaces/{namespace}/volumesnapshots/{name}` -- `DELETE`: delete a VolumeSnapshot -- `GET`: read the specified VolumeSnapshot -- `PATCH`: partially update the specified VolumeSnapshot -- `PUT`: replace the specified VolumeSnapshot -* `/apis/snapshot.storage.k8s.io/v1/namespaces/{namespace}/volumesnapshots/{name}/status` -- `GET`: read status of the specified VolumeSnapshot -- `PATCH`: partially update status of the specified VolumeSnapshot -- `PUT`: replace status of the specified VolumeSnapshot - - -=== /apis/snapshot.storage.k8s.io/v1/volumesnapshots - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind VolumeSnapshot - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#volumesnapshotlist-snapshot-storage-k8s-io-v1[`VolumeSnapshotList snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/snapshot.storage.k8s.io/v1/namespaces/{namespace}/volumesnapshots - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#volumesnapshotlist-snapshot-storage-k8s-io-v1[`VolumeSnapshotList snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/snapshot.storage.k8s.io/v1/namespaces/{namespace}/volumesnapshots/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the VolumeSnapshot -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/snapshot.storage.k8s.io/v1/namespaces/{namespace}/volumesnapshots/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the VolumeSnapshot -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified VolumeSnapshot - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumesnapshot-snapshot-storage-k8s-io-v1.adoc#volumesnapshot-snapshot-storage-k8s-io-v1[`VolumeSnapshot snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc b/rest_api/storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc deleted file mode 100644 index 45b337950b88..000000000000 --- a/rest_api/storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc +++ /dev/null @@ -1,414 +0,0 @@ -[id="volumesnapshotclass-snapshot-storage-k8s-io-v1"] -= VolumeSnapshotClass [snapshot.storage.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - VolumeSnapshotClass specifies parameters that a underlying storage system uses when creating a volume snapshot. A specific VolumeSnapshotClass is used by specifying its name in a VolumeSnapshot object. VolumeSnapshotClasses are non-namespaced - -Type:: - `object` - -Required:: - - `deletionPolicy` - - `driver` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `deletionPolicy` -| `string` -| deletionPolicy determines whether a VolumeSnapshotContent created through the VolumeSnapshotClass should be deleted when its bound VolumeSnapshot is deleted. Supported values are "Retain" and "Delete". "Retain" means that the VolumeSnapshotContent and its physical snapshot on underlying storage system are kept. "Delete" means that the VolumeSnapshotContent and its physical snapshot on underlying storage system are deleted. Required. - -| `driver` -| `string` -| driver is the name of the storage driver that handles this VolumeSnapshotClass. Required. - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `parameters` -| `object (string)` -| parameters is a key-value map with storage driver specific parameters for creating snapshots. These values are opaque to Kubernetes. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/snapshot.storage.k8s.io/v1/volumesnapshotclasses` -- `DELETE`: delete collection of VolumeSnapshotClass -- `GET`: list objects of kind VolumeSnapshotClass -- `POST`: create a VolumeSnapshotClass -* `/apis/snapshot.storage.k8s.io/v1/volumesnapshotclasses/{name}` -- `DELETE`: delete a VolumeSnapshotClass -- `GET`: read the specified VolumeSnapshotClass -- `PATCH`: partially update the specified VolumeSnapshotClass -- `PUT`: replace the specified VolumeSnapshotClass - - -=== /apis/snapshot.storage.k8s.io/v1/volumesnapshotclasses - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of VolumeSnapshotClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind VolumeSnapshotClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#volumesnapshotclasslist-snapshot-storage-k8s-io-v1[`VolumeSnapshotClassList snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a VolumeSnapshotClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/snapshot.storage.k8s.io/v1/volumesnapshotclasses/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the VolumeSnapshotClass -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a VolumeSnapshotClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified VolumeSnapshotClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified VolumeSnapshotClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified VolumeSnapshotClass - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumesnapshotclass-snapshot-storage-k8s-io-v1.adoc#volumesnapshotclass-snapshot-storage-k8s-io-v1[`VolumeSnapshotClass snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc b/rest_api/storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc deleted file mode 100644 index 1415c5a917fa..000000000000 --- a/rest_api/storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc +++ /dev/null @@ -1,705 +0,0 @@ -[id="volumesnapshotcontent-snapshot-storage-k8s-io-v1"] -= VolumeSnapshotContent [snapshot.storage.k8s.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - VolumeSnapshotContent represents the actual "on-disk" snapshot object in the underlying storage system - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta_v2-meta-v1[`ObjectMeta_v2 meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| spec defines properties of a VolumeSnapshotContent created by the underlying storage system. Required. - -| `status` -| `object` -| status represents the current information of a snapshot. - -|=== -..spec -Description:: - spec defines properties of a VolumeSnapshotContent created by the underlying storage system. Required. - -Type:: - `object` - -Required:: - - `deletionPolicy` - - `driver` - - `source` - - `volumeSnapshotRef` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `deletionPolicy` -| `string` -| deletionPolicy determines whether this VolumeSnapshotContent and its physical snapshot on the underlying storage system should be deleted when its bound VolumeSnapshot is deleted. Supported values are "Retain" and "Delete". "Retain" means that the VolumeSnapshotContent and its physical snapshot on underlying storage system are kept. "Delete" means that the VolumeSnapshotContent and its physical snapshot on underlying storage system are deleted. For dynamically provisioned snapshots, this field will automatically be filled in by the CSI snapshotter sidecar with the "DeletionPolicy" field defined in the corresponding VolumeSnapshotClass. For pre-existing snapshots, users MUST specify this field when creating the VolumeSnapshotContent object. Required. - -| `driver` -| `string` -| driver is the name of the CSI driver used to create the physical snapshot on the underlying storage system. This MUST be the same as the name returned by the CSI GetPluginName() call for that driver. Required. - -| `source` -| `object` -| source specifies whether the snapshot is (or should be) dynamically provisioned or already exists, and just requires a Kubernetes object representation. This field is immutable after creation. Required. - -| `volumeSnapshotClassName` -| `string` -| name of the VolumeSnapshotClass from which this snapshot was (or will be) created. Note that after provisioning, the VolumeSnapshotClass may be deleted or recreated with different set of values, and as such, should not be referenced post-snapshot creation. - -| `volumeSnapshotRef` -| `object` -| volumeSnapshotRef specifies the VolumeSnapshot object to which this VolumeSnapshotContent object is bound. VolumeSnapshot.Spec.VolumeSnapshotContentName field must reference to this VolumeSnapshotContent's name for the bidirectional binding to be valid. For a pre-existing VolumeSnapshotContent object, name and namespace of the VolumeSnapshot object MUST be provided for binding to happen. This field is immutable after creation. Required. - -|=== -..spec.source -Description:: - source specifies whether the snapshot is (or should be) dynamically provisioned or already exists, and just requires a Kubernetes object representation. This field is immutable after creation. Required. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `snapshotHandle` -| `string` -| snapshotHandle specifies the CSI "snapshot_id" of a pre-existing snapshot on the underlying storage system for which a Kubernetes object representation was (or should be) created. This field is immutable. - -| `volumeHandle` -| `string` -| volumeHandle specifies the CSI "volume_id" of the volume from which a snapshot should be dynamically taken from. This field is immutable. - -|=== -..spec.volumeSnapshotRef -Description:: - volumeSnapshotRef specifies the VolumeSnapshot object to which this VolumeSnapshotContent object is bound. VolumeSnapshot.Spec.VolumeSnapshotContentName field must reference to this VolumeSnapshotContent's name for the bidirectional binding to be valid. For a pre-existing VolumeSnapshotContent object, name and namespace of the VolumeSnapshot object MUST be provided for binding to happen. This field is immutable after creation. Required. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| API version of the referent. - -| `fieldPath` -| `string` -| If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object. TODO: this design is not final and this field is subject to change in the future. - -| `kind` -| `string` -| Kind of the referent. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `name` -| `string` -| Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names - -| `namespace` -| `string` -| Namespace of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/ - -| `resourceVersion` -| `string` -| Specific resourceVersion to which this reference is made, if any. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency - -| `uid` -| `string` -| UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids - -|=== -..status -Description:: - status represents the current information of a snapshot. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `creationTime` -| `integer` -| creationTime is the timestamp when the point-in-time snapshot is taken by the underlying storage system. In dynamic snapshot creation case, this field will be filled in by the CSI snapshotter sidecar with the "creation_time" value returned from CSI "CreateSnapshot" gRPC call. For a pre-existing snapshot, this field will be filled with the "creation_time" value returned from the CSI "ListSnapshots" gRPC call if the driver supports it. If not specified, it indicates the creation time is unknown. The format of this field is a Unix nanoseconds time encoded as an int64. On Unix, the command `date +%s%N` returns the current time in nanoseconds since 1970-01-01 00:00:00 UTC. - -| `error` -| `object` -| error is the last observed error during snapshot creation, if any. Upon success after retry, this error field will be cleared. - -| `readyToUse` -| `boolean` -| readyToUse indicates if a snapshot is ready to be used to restore a volume. In dynamic snapshot creation case, this field will be filled in by the CSI snapshotter sidecar with the "ready_to_use" value returned from CSI "CreateSnapshot" gRPC call. For a pre-existing snapshot, this field will be filled with the "ready_to_use" value returned from the CSI "ListSnapshots" gRPC call if the driver supports it, otherwise, this field will be set to "True". If not specified, it means the readiness of a snapshot is unknown. - -| `restoreSize` -| `integer` -| restoreSize represents the complete size of the snapshot in bytes. In dynamic snapshot creation case, this field will be filled in by the CSI snapshotter sidecar with the "size_bytes" value returned from CSI "CreateSnapshot" gRPC call. For a pre-existing snapshot, this field will be filled with the "size_bytes" value returned from the CSI "ListSnapshots" gRPC call if the driver supports it. When restoring a volume from this snapshot, the size of the volume MUST NOT be smaller than the restoreSize if it is specified, otherwise the restoration will fail. If not specified, it indicates that the size is unknown. - -| `snapshotHandle` -| `string` -| snapshotHandle is the CSI "snapshot_id" of a snapshot on the underlying storage system. If not specified, it indicates that dynamic snapshot creation has either failed or it is still in progress. - -|=== -..status.error -Description:: - error is the last observed error during snapshot creation, if any. Upon success after retry, this error field will be cleared. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `message` -| `string` -| message is a string detailing the encountered error during snapshot creation if specified. NOTE: message may be logged, and it should not contain sensitive information. - -| `time` -| `string` -| time is the timestamp when the error was encountered. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/snapshot.storage.k8s.io/v1/volumesnapshotcontents` -- `DELETE`: delete collection of VolumeSnapshotContent -- `GET`: list objects of kind VolumeSnapshotContent -- `POST`: create a VolumeSnapshotContent -* `/apis/snapshot.storage.k8s.io/v1/volumesnapshotcontents/{name}` -- `DELETE`: delete a VolumeSnapshotContent -- `GET`: read the specified VolumeSnapshotContent -- `PATCH`: partially update the specified VolumeSnapshotContent -- `PUT`: replace the specified VolumeSnapshotContent -* `/apis/snapshot.storage.k8s.io/v1/volumesnapshotcontents/{name}/status` -- `GET`: read status of the specified VolumeSnapshotContent -- `PATCH`: partially update status of the specified VolumeSnapshotContent -- `PUT`: replace status of the specified VolumeSnapshotContent - - -=== /apis/snapshot.storage.k8s.io/v1/volumesnapshotcontents - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list objects of kind VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#volumesnapshotcontentlist-snapshot-storage-k8s-io-v1[`VolumeSnapshotContentList snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 202 - Accepted -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/snapshot.storage.k8s.io/v1/volumesnapshotcontents/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the VolumeSnapshotContent -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions_v2-meta-v1[`DeleteOptions_v2 meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status_v2-meta-v1[`Status_v2 meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/snapshot.storage.k8s.io/v1/volumesnapshotcontents/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the VolumeSnapshotContent -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified VolumeSnapshotContent - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 201 - Created -| xref:../storage_apis/volumesnapshotcontent-snapshot-storage-k8s-io-v1.adoc#volumesnapshotcontent-snapshot-storage-k8s-io-v1[`VolumeSnapshotContent snapshot.storage.k8s.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/template_apis/brokertemplateinstance-template-openshift-io-v1.adoc b/rest_api/template_apis/brokertemplateinstance-template-openshift-io-v1.adoc deleted file mode 100644 index 088a7e516909..000000000000 --- a/rest_api/template_apis/brokertemplateinstance-template-openshift-io-v1.adoc +++ /dev/null @@ -1,453 +0,0 @@ -[id="brokertemplateinstance-template-openshift-io-v1"] -= BrokerTemplateInstance [template.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - BrokerTemplateInstance holds the service broker-related state associated with a TemplateInstance. BrokerTemplateInstance is part of an experimental API. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| BrokerTemplateInstanceSpec describes the state of a BrokerTemplateInstance. - -|=== -..spec -Description:: - BrokerTemplateInstanceSpec describes the state of a BrokerTemplateInstance. - -Type:: - `object` - -Required:: - - `templateInstance` - - `secret` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bindingIDs` -| `array (string)` -| bindingids is a list of 'binding_id's provided during successive bind calls to the template service broker. - -| `secret` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| secret is a reference to a Secret object residing in a namespace, containing the necessary template parameters. - -| `templateInstance` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| templateinstance is a reference to a TemplateInstance object residing in a namespace. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/template.openshift.io/v1/brokertemplateinstances` -- `DELETE`: delete collection of BrokerTemplateInstance -- `GET`: list or watch objects of kind BrokerTemplateInstance -- `POST`: create a BrokerTemplateInstance -* `/apis/template.openshift.io/v1/brokertemplateinstances/{name}` -- `DELETE`: delete a BrokerTemplateInstance -- `GET`: read the specified BrokerTemplateInstance -- `PATCH`: partially update the specified BrokerTemplateInstance -- `PUT`: replace the specified BrokerTemplateInstance - - -=== /apis/template.openshift.io/v1/brokertemplateinstances - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of BrokerTemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind BrokerTemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#brokertemplateinstancelist-template-openshift-io-v1[`BrokerTemplateInstanceList template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a BrokerTemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| 201 - Created -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| 202 - Accepted -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/template.openshift.io/v1/brokertemplateinstances/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the BrokerTemplateInstance -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a BrokerTemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified BrokerTemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified BrokerTemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified BrokerTemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| 201 - Created -| xref:../template_apis/brokertemplateinstance-template-openshift-io-v1.adoc#brokertemplateinstance-template-openshift-io-v1[`BrokerTemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/template_apis/podtemplate-core-v1.adoc b/rest_api/template_apis/podtemplate-core-v1.adoc deleted file mode 100644 index c721517ddafd..000000000000 --- a/rest_api/template_apis/podtemplate-core-v1.adoc +++ /dev/null @@ -1,679 +0,0 @@ -[id="podtemplate-core-v1"] -= PodTemplate [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PodTemplate describes a template for creating copies of a predefined pod. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `template` -| `object` -| PodTemplateSpec describes the data a pod should have when created from a template - -|=== -..template -Description:: - PodTemplateSpec describes the data a pod should have when created from a template - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| PodSpec is a description of a pod. - -|=== -..template.spec -Description:: - PodSpec is a description of a pod. - -Type:: - `object` - -Required:: - - `containers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `activeDeadlineSeconds` -| `integer` -| Optional duration in seconds the pod may be active on the node relative to StartTime before the system will actively try to mark it failed and kill associated containers. Value must be a positive integer. - -| `affinity` -| xref:../objects/index.adoc#affinity-core-v1[`Affinity core/v1`] -| If specified, the pod's scheduling constraints - -| `automountServiceAccountToken` -| `boolean` -| AutomountServiceAccountToken indicates whether a service account token should be automatically mounted. - -| `containers` -| xref:../objects/index.adoc#container-core-v1[`array (Container core/v1)`] -| List of containers belonging to the pod. Containers cannot currently be added or removed. There must be at least one container in a Pod. Cannot be updated. - -| `dnsConfig` -| xref:../objects/index.adoc#poddnsconfig-core-v1[`PodDNSConfig core/v1`] -| Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy. - -| `dnsPolicy` -| `string` -| Set DNS policy for the pod. Defaults to "ClusterFirst". Valid values are 'ClusterFirstWithHostNet', 'ClusterFirst', 'Default' or 'None'. DNS parameters given in DNSConfig will be merged with the policy selected with DNSPolicy. To have DNS options set along with hostNetwork, you have to specify DNS policy explicitly to 'ClusterFirstWithHostNet'. - -| `enableServiceLinks` -| `boolean` -| EnableServiceLinks indicates whether information about services should be injected into pod's environment variables, matching the syntax of Docker links. Optional: Defaults to true. - -| `ephemeralContainers` -| xref:../objects/index.adoc#ephemeralcontainer-core-v1[`array (EphemeralContainer core/v1)`] -| List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing pod to perform user-initiated actions such as debugging. This list cannot be specified when creating a pod, and it cannot be modified by updating the pod spec. In order to add an ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource. This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature. - -| `hostAliases` -| xref:../objects/index.adoc#hostalias-core-v1[`array (HostAlias core/v1)`] -| HostAliases is an optional list of hosts and IPs that will be injected into the pod's hosts file if specified. This is only valid for non-hostNetwork pods. - -| `hostIPC` -| `boolean` -| Use the host's ipc namespace. Optional: Default to false. - -| `hostNetwork` -| `boolean` -| Host networking requested for this pod. Use the host's network namespace. If this option is set, the ports that will be used must be specified. Default to false. - -| `hostPID` -| `boolean` -| Use the host's pid namespace. Optional: Default to false. - -| `hostname` -| `string` -| Specifies the hostname of the Pod If not specified, the pod's hostname will be set to a system-defined value. - -| `imagePullSecrets` -| xref:../objects/index.adoc#localobjectreference-core-v1[`array (LocalObjectReference core/v1)`] -| ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. For example, in the case of docker, only DockerConfig type secrets are honored. More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod - -| `initContainers` -| xref:../objects/index.adoc#container-core-v1[`array (Container core/v1)`] -| List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. Init containers cannot currently be added or removed. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ - -| `nodeName` -| `string` -| NodeName is a request to schedule this pod onto a specific node. If it is non-empty, the scheduler simply schedules this pod onto that node, assuming that it fits resource requirements. - -| `nodeSelector` -| `object (string)` -| NodeSelector is a selector which must be true for the pod to fit on a node. Selector which must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ - -| `overhead` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Overhead represents the resource overhead associated with running a pod for a given RuntimeClass. This field will be autopopulated at admission time by the RuntimeClass admission controller. If the RuntimeClass admission controller is enabled, overhead must not be set in Pod create requests. The RuntimeClass admission controller will reject Pod create requests which have the overhead already set. If RuntimeClass is configured and selected in the PodSpec, Overhead will be set to the value defined in the corresponding RuntimeClass, otherwise it will remain unset and treated as zero. More info: https://git.k8s.io/enhancements/keps/sig-node/20190226-pod-overhead.md This field is alpha-level as of Kubernetes v1.16, and is only honored by servers that enable the PodOverhead feature. - -| `preemptionPolicy` -| `string` -| PreemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset. This field is beta-level, gated by the NonPreemptingPriority feature-gate. - -| `priority` -| `integer` -| The priority value. Various system components use this field to find the priority of the pod. When Priority Admission Controller is enabled, it prevents users from setting this field. The admission controller populates this field from PriorityClassName. The higher the value, the higher the priority. - -| `priorityClassName` -| `string` -| If specified, indicates the pod's priority. "system-node-critical" and "system-cluster-critical" are two special keywords which indicate the highest priorities with the former being the highest priority. Any other name must be defined by creating a PriorityClass object with that name. If not specified, the pod priority will be default or zero if there is no default. - -| `readinessGates` -| xref:../objects/index.adoc#podreadinessgate-core-v1[`array (PodReadinessGate core/v1)`] -| If specified, all readiness gates will be evaluated for pod readiness. A pod is ready when all its containers are ready AND all conditions specified in the readiness gates have status equal to "True" More info: https://git.k8s.io/enhancements/keps/sig-network/0007-pod-ready%2B%2B.md - -| `restartPolicy` -| `string` -| Restart policy for all containers within the pod. One of Always, OnFailure, Never. Default to Always. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy - -| `runtimeClassName` -| `string` -| RuntimeClassName refers to a RuntimeClass object in the node.k8s.io group, which should be used to run this pod. If no RuntimeClass resource matches the named class, the pod will not be run. If unset or empty, the "legacy" RuntimeClass will be used, which is an implicit class with an empty definition that uses the default runtime handler. More info: https://git.k8s.io/enhancements/keps/sig-node/runtime-class.md This is a beta feature as of Kubernetes v1.14. - -| `schedulerName` -| `string` -| If specified, the pod will be dispatched by specified scheduler. If not specified, the pod will be dispatched by default scheduler. - -| `securityContext` -| xref:../objects/index.adoc#podsecuritycontext-core-v1[`PodSecurityContext core/v1`] -| SecurityContext holds pod-level security attributes and common container settings. Optional: Defaults to empty. See type description for default values of each field. - -| `serviceAccount` -| `string` -| DeprecatedServiceAccount is a depreciated alias for ServiceAccountName. Deprecated: Use serviceAccountName instead. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the name of the ServiceAccount to use to run this pod. More info: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ - -| `setHostnameAsFQDN` -| `boolean` -| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. - -| `shareProcessNamespace` -| `boolean` -| Share a single process namespace between all of the containers in a pod. When this is set containers will be able to view and signal processes from other containers in the same pod, and the first process in each container will not be assigned PID 1. HostPID and ShareProcessNamespace cannot both be set. Optional: Default to false. - -| `subdomain` -| `string` -| If specified, the fully qualified Pod hostname will be "<hostname>.<subdomain>.<pod namespace>.svc.<cluster domain>". If not specified, the pod will not have a domainname at all. - -| `terminationGracePeriodSeconds` -| `integer` -| Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds. - -| `tolerations` -| xref:../objects/index.adoc#toleration-core-v1[`array (Toleration core/v1)`] -| If specified, the pod's tolerations. - -| `topologySpreadConstraints` -| xref:../objects/index.adoc#topologyspreadconstraint-core-v1[`array (TopologySpreadConstraint core/v1)`] -| TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. - -| `volumes` -| xref:../objects/index.adoc#volume-core-v1[`array (Volume core/v1)`] -| List of volumes that can be mounted by containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/podtemplates` -- `GET`: list or watch objects of kind PodTemplate -* `/api/v1/namespaces/{namespace}/podtemplates` -- `DELETE`: delete collection of PodTemplate -- `GET`: list or watch objects of kind PodTemplate -- `POST`: create a PodTemplate -* `/api/v1/namespaces/{namespace}/podtemplates/{name}` -- `DELETE`: delete a PodTemplate -- `GET`: read the specified PodTemplate -- `PATCH`: partially update the specified PodTemplate -- `PUT`: replace the specified PodTemplate - - -=== /api/v1/podtemplates - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PodTemplate - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#podtemplatelist-core-v1[`PodTemplateList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/podtemplates - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PodTemplate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PodTemplate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#podtemplatelist-core-v1[`PodTemplateList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PodTemplate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 201 - Created -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 202 - Accepted -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/podtemplates/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodTemplate -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PodTemplate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 202 - Accepted -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PodTemplate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PodTemplate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PodTemplate - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 201 - Created -| xref:../template_apis/podtemplate-core-v1.adoc#podtemplate-core-v1[`PodTemplate core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/template_apis/template-apis-index.adoc b/rest_api/template_apis/template-apis-index.adoc deleted file mode 100644 index 82c3cb8dfd47..000000000000 --- a/rest_api/template_apis/template-apis-index.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="template-apis"] -= Template APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== BrokerTemplateInstance [template.openshift.io/v1] - -Description:: - BrokerTemplateInstance holds the service broker-related state associated with a TemplateInstance. BrokerTemplateInstance is part of an experimental API. - -Type:: - `object` - -== PodTemplate [core/v1] - -Description:: - PodTemplate describes a template for creating copies of a predefined pod. - -Type:: - `object` - -== Template [template.openshift.io/v1] - -Description:: - Template contains the inputs needed to produce a Config. - -Type:: - `object` - -== TemplateInstance [template.openshift.io/v1] - -Description:: - TemplateInstance requests and records the instantiation of a Template. TemplateInstance is part of an experimental API. - -Type:: - `object` - diff --git a/rest_api/template_apis/template-template-openshift-io-v1.adoc b/rest_api/template_apis/template-template-openshift-io-v1.adoc deleted file mode 100644 index 00fe01f98cf7..000000000000 --- a/rest_api/template_apis/template-template-openshift-io-v1.adoc +++ /dev/null @@ -1,186 +0,0 @@ -[id="template-template-openshift-io-v1"] -= Template [template.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Template contains the inputs needed to produce a Config. - -Type:: - `object` - -Required:: - - `objects` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `labels` -| `object (string)` -| labels is a optional set of labels that are applied to every object during the Template to Config transformation. - -| `message` -| `string` -| message is an optional instructional message that will be displayed when this template is instantiated. This field should inform the user how to utilize the newly created resources. Parameter substitution will be performed on the message before being displayed so that generated credentials and other parameters can be included in the output. - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `objects` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`array (RawExtension pkg/runtime)`] -| objects is an array of resources to include in this template. If a namespace value is hardcoded in the object, it will be removed during template instantiation, however if the namespace value is, or contains, a ${PARAMETER_REFERENCE}, the resolved value after parameter substitution will be respected and the object will be created in that namespace. - -| `parameters` -| `array` -| parameters is an optional array of Parameters used during the Template to Config transformation. - -| `parameters[]` -| `object` -| Parameter defines a name/value variable that is to be processed during the Template to Config transformation. - -|=== -..parameters -Description:: - parameters is an optional array of Parameters used during the Template to Config transformation. - -Type:: - `array` - - - - -..parameters[] -Description:: - Parameter defines a name/value variable that is to be processed during the Template to Config transformation. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| Description of a parameter. Optional. - -| `displayName` -| `string` -| Optional: The name that will show in UI instead of parameter 'Name' - -| `from` -| `string` -| From is an input value for the generator. Optional. - -| `generate` -| `string` -| generate specifies the generator to be used to generate random string from an input value specified by From field. The result string is stored into Value field. If empty, no generator is being used, leaving the result Value untouched. Optional. - -The only supported generator is "expression", which accepts a "from" value in the form of a simple regular expression containing the range expression "[a-zA-Z0-9]", and the length expression "a{length}". - -Examples: - -from \| value ----------------------------- "test[0-9]{1}x" \| "test7x" "[0-1]{8}" \| "01001100" "0x[A-F0-9]{4}" \| "0xB3AF" "[a-zA-Z0-9]{8}" \| "hW4yQU5i" - -| `name` -| `string` -| Name must be set and it can be referenced in Template Items using ${PARAMETER_NAME}. Required. - -| `required` -| `boolean` -| Optional: Indicates the parameter must have a value. Defaults to false. - -| `value` -| `string` -| Value holds the Parameter data. If specified, the generator will be ignored. The value replaces all occurrences of the Parameter ${Name} expression during the Template to Config transformation. Optional. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/template.openshift.io/v1/namespaces/{namespace}/processedtemplates` -- `POST`: create a Template - - -=== /apis/template.openshift.io/v1/namespaces/{namespace}/processedtemplates - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create a Template - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../template_apis/template-template-openshift-io-v1.adoc#template-template-openshift-io-v1[`Template template.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/template-template-openshift-io-v1.adoc#template-template-openshift-io-v1[`Template template.openshift.io/v1`] -| 201 - Created -| xref:../template_apis/template-template-openshift-io-v1.adoc#template-template-openshift-io-v1[`Template template.openshift.io/v1`] -| 202 - Accepted -| xref:../template_apis/template-template-openshift-io-v1.adoc#template-template-openshift-io-v1[`Template template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/template_apis/templateinstance-template-openshift-io-v1.adoc b/rest_api/template_apis/templateinstance-template-openshift-io-v1.adoc deleted file mode 100644 index e31e9eabff8e..000000000000 --- a/rest_api/template_apis/templateinstance-template-openshift-io-v1.adoc +++ /dev/null @@ -1,926 +0,0 @@ -[id="templateinstance-template-openshift-io-v1"] -= TemplateInstance [template.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - TemplateInstance requests and records the instantiation of a Template. TemplateInstance is part of an experimental API. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| TemplateInstanceSpec describes the desired state of a TemplateInstance. - -| `status` -| `object` -| TemplateInstanceStatus describes the current state of a TemplateInstance. - -|=== -..spec -Description:: - TemplateInstanceSpec describes the desired state of a TemplateInstance. - -Type:: - `object` - -Required:: - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `requester` -| `object` -| TemplateInstanceRequester holds the identity of an agent requesting a template instantiation. - -| `secret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| secret is a reference to a Secret object containing the necessary template parameters. - -| `template` -| `object` -| Template contains the inputs needed to produce a Config. - -|=== -..spec.requester -Description:: - TemplateInstanceRequester holds the identity of an agent requesting a template instantiation. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `extra` -| `object` -| extra holds additional information provided by the authenticator. - -| `extra{}` -| `array (string)` -| - -| `groups` -| `array (string)` -| groups represent the groups this user is a part of. - -| `uid` -| `string` -| uid is a unique value that identifies this user across time; if this user is deleted and another user by the same name is added, they will have different UIDs. - -| `username` -| `string` -| username uniquely identifies this user among all active users. - -|=== -..spec.requester.extra -Description:: - extra holds additional information provided by the authenticator. - -Type:: - `object` - - - - -..spec.template -Description:: - Template contains the inputs needed to produce a Config. - -Type:: - `object` - -Required:: - - `objects` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `labels` -| `object (string)` -| labels is a optional set of labels that are applied to every object during the Template to Config transformation. - -| `message` -| `string` -| message is an optional instructional message that will be displayed when this template is instantiated. This field should inform the user how to utilize the newly created resources. Parameter substitution will be performed on the message before being displayed so that generated credentials and other parameters can be included in the output. - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `objects` -| xref:../objects/index.adoc#rawextension-pkg-runtime[`array (RawExtension pkg/runtime)`] -| objects is an array of resources to include in this template. If a namespace value is hardcoded in the object, it will be removed during template instantiation, however if the namespace value is, or contains, a ${PARAMETER_REFERENCE}, the resolved value after parameter substitution will be respected and the object will be created in that namespace. - -| `parameters` -| `array` -| parameters is an optional array of Parameters used during the Template to Config transformation. - -| `parameters[]` -| `object` -| Parameter defines a name/value variable that is to be processed during the Template to Config transformation. - -|=== -..spec.template.parameters -Description:: - parameters is an optional array of Parameters used during the Template to Config transformation. - -Type:: - `array` - - - - -..spec.template.parameters[] -Description:: - Parameter defines a name/value variable that is to be processed during the Template to Config transformation. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `description` -| `string` -| Description of a parameter. Optional. - -| `displayName` -| `string` -| Optional: The name that will show in UI instead of parameter 'Name' - -| `from` -| `string` -| From is an input value for the generator. Optional. - -| `generate` -| `string` -| generate specifies the generator to be used to generate random string from an input value specified by From field. The result string is stored into Value field. If empty, no generator is being used, leaving the result Value untouched. Optional. - -The only supported generator is "expression", which accepts a "from" value in the form of a simple regular expression containing the range expression "[a-zA-Z0-9]", and the length expression "a{length}". - -Examples: - -from \| value ----------------------------- "test[0-9]{1}x" \| "test7x" "[0-1]{8}" \| "01001100" "0x[A-F0-9]{4}" \| "0xB3AF" "[a-zA-Z0-9]{8}" \| "hW4yQU5i" - -| `name` -| `string` -| Name must be set and it can be referenced in Template Items using ${PARAMETER_NAME}. Required. - -| `required` -| `boolean` -| Optional: Indicates the parameter must have a value. Defaults to false. - -| `value` -| `string` -| Value holds the Parameter data. If specified, the generator will be ignored. The value replaces all occurrences of the Parameter ${Name} expression during the Template to Config transformation. Optional. - -|=== -..status -Description:: - TemplateInstanceStatus describes the current state of a TemplateInstance. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| `array` -| conditions represent the latest available observations of a TemplateInstance's current state. - -| `conditions[]` -| `object` -| TemplateInstanceCondition contains condition information for a TemplateInstance. - -| `objects` -| `array` -| Objects references the objects created by the TemplateInstance. - -| `objects[]` -| `object` -| TemplateInstanceObject references an object created by a TemplateInstance. - -|=== -..status.conditions -Description:: - conditions represent the latest available observations of a TemplateInstance's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - TemplateInstanceCondition contains condition information for a TemplateInstance. - -Type:: - `object` - -Required:: - - `type` - - `status` - - `lastTransitionTime` - - `reason` - - `message` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| LastTransitionTime is the last time a condition status transitioned from one state to another. - -| `message` -| `string` -| Message is a human readable description of the details of the last transition, complementing reason. - -| `reason` -| `string` -| Reason is a brief machine readable explanation for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False or Unknown. - -| `type` -| `string` -| Type of the condition, currently Ready or InstantiateFailure. - -|=== -..status.objects -Description:: - Objects references the objects created by the TemplateInstance. - -Type:: - `array` - - - - -..status.objects[] -Description:: - TemplateInstanceObject references an object created by a TemplateInstance. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `ref` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| ref is a reference to the created object. When used under .spec, only name and namespace are used; these can contain references to parameters which will be substituted following the usual rules. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/template.openshift.io/v1/templateinstances` -- `GET`: list or watch objects of kind TemplateInstance -* `/apis/template.openshift.io/v1/namespaces/{namespace}/templateinstances` -- `DELETE`: delete collection of TemplateInstance -- `GET`: list or watch objects of kind TemplateInstance -- `POST`: create a TemplateInstance -* `/apis/template.openshift.io/v1/namespaces/{namespace}/templateinstances/{name}` -- `DELETE`: delete a TemplateInstance -- `GET`: read the specified TemplateInstance -- `PATCH`: partially update the specified TemplateInstance -- `PUT`: replace the specified TemplateInstance -* `/apis/template.openshift.io/v1/namespaces/{namespace}/templateinstances/{name}/status` -- `GET`: read status of the specified TemplateInstance -- `PATCH`: partially update status of the specified TemplateInstance -- `PUT`: replace status of the specified TemplateInstance - - -=== /apis/template.openshift.io/v1/templateinstances - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind TemplateInstance - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#templateinstancelist-template-openshift-io-v1[`TemplateInstanceList template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/template.openshift.io/v1/namespaces/{namespace}/templateinstances - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#templateinstancelist-template-openshift-io-v1[`TemplateInstanceList template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 201 - Created -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 202 - Accepted -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/template.openshift.io/v1/namespaces/{namespace}/templateinstances/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the TemplateInstance -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 201 - Created -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/template.openshift.io/v1/namespaces/{namespace}/templateinstances/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the TemplateInstance -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified TemplateInstance - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified TemplateInstance - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 201 - Created -| xref:../template_apis/templateinstance-template-openshift-io-v1.adoc#templateinstance-template-openshift-io-v1[`TemplateInstance template.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/user_and_group_apis/group-user-openshift-io-v1.adoc b/rest_api/user_and_group_apis/group-user-openshift-io-v1.adoc deleted file mode 100644 index 1c6150eb1be8..000000000000 --- a/rest_api/user_and_group_apis/group-user-openshift-io-v1.adoc +++ /dev/null @@ -1,423 +0,0 @@ -[id="group-user-openshift-io-v1"] -= Group [user.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Group represents a referenceable set of Users - -Type:: - `object` - -Required:: - - `users` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `users` -| `array (string)` -| Users is the list of users in this group. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/user.openshift.io/v1/groups` -- `DELETE`: delete collection of Group -- `GET`: list or watch objects of kind Group -- `POST`: create a Group -* `/apis/user.openshift.io/v1/groups/{name}` -- `DELETE`: delete a Group -- `GET`: read the specified Group -- `PATCH`: partially update the specified Group -- `PUT`: replace the specified Group - - -=== /apis/user.openshift.io/v1/groups - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Group - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Group - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#grouplist-user-openshift-io-v1[`GroupList user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Group - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| 201 - Created -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| 202 - Accepted -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/user.openshift.io/v1/groups/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Group -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Group - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Group - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Group - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Group - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| 201 - Created -| xref:../user_and_group_apis/group-user-openshift-io-v1.adoc#group-user-openshift-io-v1[`Group user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/user_and_group_apis/identity-user-openshift-io-v1.adoc b/rest_api/user_and_group_apis/identity-user-openshift-io-v1.adoc deleted file mode 100644 index 88a2fd346974..000000000000 --- a/rest_api/user_and_group_apis/identity-user-openshift-io-v1.adoc +++ /dev/null @@ -1,437 +0,0 @@ -[id="identity-user-openshift-io-v1"] -= Identity [user.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Identity records a successful authentication of a user with an identity provider. The information about the source of authentication is stored on the identity, and the identity is then associated with a single user object. Multiple identities can reference a single user. Information retrieved from the authentication provider is stored in the extra field using a schema determined by the provider. - -Type:: - `object` - -Required:: - - `providerName` - - `providerUserName` - - `user` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `extra` -| `object (string)` -| Extra holds extra information about this identity - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `providerName` -| `string` -| ProviderName is the source of identity information - -| `providerUserName` -| `string` -| ProviderUserName uniquely represents this identity in the scope of the provider - -| `user` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| User is a reference to the user this identity is associated with Both Name and UID must be set - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/user.openshift.io/v1/identities` -- `DELETE`: delete collection of Identity -- `GET`: list or watch objects of kind Identity -- `POST`: create an Identity -* `/apis/user.openshift.io/v1/identities/{name}` -- `DELETE`: delete an Identity -- `GET`: read the specified Identity -- `PATCH`: partially update the specified Identity -- `PUT`: replace the specified Identity - - -=== /apis/user.openshift.io/v1/identities - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Identity - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Identity - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#identitylist-user-openshift-io-v1[`IdentityList user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an Identity - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| 201 - Created -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| 202 - Accepted -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/user.openshift.io/v1/identities/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Identity -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an Identity - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Identity - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Identity - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Identity - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| 201 - Created -| xref:../user_and_group_apis/identity-user-openshift-io-v1.adoc#identity-user-openshift-io-v1[`Identity user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/user_and_group_apis/user-and-group-apis-index.adoc b/rest_api/user_and_group_apis/user-and-group-apis-index.adoc deleted file mode 100644 index a4cf5994cc2c..000000000000 --- a/rest_api/user_and_group_apis/user-and-group-apis-index.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="user-and-group-apis"] -= User and group APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== Group [user.openshift.io/v1] - -Description:: - Group represents a referenceable set of Users - -Type:: - `object` - -== Identity [user.openshift.io/v1] - -Description:: - Identity records a successful authentication of a user with an identity provider. The information about the source of authentication is stored on the identity, and the identity is then associated with a single user object. Multiple identities can reference a single user. Information retrieved from the authentication provider is stored in the extra field using a schema determined by the provider. - -Type:: - `object` - -== UserIdentityMapping [user.openshift.io/v1] - -Description:: - UserIdentityMapping maps a user to an identity - -Type:: - `object` - -== User [user.openshift.io/v1] - -Description:: - Upon log in, every user of the system receives a User and Identity resource. Administrators may directly manipulate the attributes of the users for their own tracking, or set groups via the API. The user name is unique and is chosen based on the value provided by the identity provider - if a user already exists with the incoming name, the user name may have a number appended to it depending on the configuration of the system. - -Type:: - `object` - diff --git a/rest_api/user_and_group_apis/user-user-openshift-io-v1.adoc b/rest_api/user_and_group_apis/user-user-openshift-io-v1.adoc deleted file mode 100644 index 94d9f8faabce..000000000000 --- a/rest_api/user_and_group_apis/user-user-openshift-io-v1.adoc +++ /dev/null @@ -1,432 +0,0 @@ -[id="user-user-openshift-io-v1"] -= User [user.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Upon log in, every user of the system receives a User and Identity resource. Administrators may directly manipulate the attributes of the users for their own tracking, or set groups via the API. The user name is unique and is chosen based on the value provided by the identity provider - if a user already exists with the incoming name, the user name may have a number appended to it depending on the configuration of the system. - -Type:: - `object` - -Required:: - - `identities` - - `groups` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `fullName` -| `string` -| FullName is the full name of user - -| `groups` -| `array (string)` -| Groups specifies group names this user is a member of. This field is deprecated and will be removed in a future release. Instead, create a Group object containing the name of this User. - -| `identities` -| `array (string)` -| Identities are the identities associated with this user - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/user.openshift.io/v1/users` -- `DELETE`: delete collection of User -- `GET`: list or watch objects of kind User -- `POST`: create an User -* `/apis/user.openshift.io/v1/users/{name}` -- `DELETE`: delete an User -- `GET`: read the specified User -- `PATCH`: partially update the specified User -- `PUT`: replace the specified User - - -=== /apis/user.openshift.io/v1/users - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of User - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind User - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#userlist-user-openshift-io-v1[`UserList user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create an User - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| 201 - Created -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| 202 - Accepted -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/user.openshift.io/v1/users/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the User -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an User - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified User - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified User - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified User - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| 201 - Created -| xref:../user_and_group_apis/user-user-openshift-io-v1.adoc#user-user-openshift-io-v1[`User user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc b/rest_api/user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc deleted file mode 100644 index 70884bfedc6c..000000000000 --- a/rest_api/user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc +++ /dev/null @@ -1,273 +0,0 @@ -[id="useridentitymapping-user-openshift-io-v1"] -= UserIdentityMapping [user.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - UserIdentityMapping maps a user to an identity - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `identity` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| Identity is a reference to an identity - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `user` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| User is a reference to a user - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/user.openshift.io/v1/useridentitymappings` -- `POST`: create an UserIdentityMapping -* `/apis/user.openshift.io/v1/useridentitymappings/{name}` -- `DELETE`: delete an UserIdentityMapping -- `GET`: read the specified UserIdentityMapping -- `PATCH`: partially update the specified UserIdentityMapping -- `PUT`: replace the specified UserIdentityMapping - - -=== /apis/user.openshift.io/v1/useridentitymappings - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create an UserIdentityMapping - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| 201 - Created -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| 202 - Accepted -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/user.openshift.io/v1/useridentitymappings/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the UserIdentityMapping -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete an UserIdentityMapping - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified UserIdentityMapping - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified UserIdentityMapping - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified UserIdentityMapping - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| 201 - Created -| xref:../user_and_group_apis/useridentitymapping-user-openshift-io-v1.adoc#useridentitymapping-user-openshift-io-v1[`UserIdentityMapping user.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/build-build-openshift-io-v1.adoc b/rest_api/workloads_apis/build-build-openshift-io-v1.adoc deleted file mode 100644 index 5e59afcd5008..000000000000 --- a/rest_api/workloads_apis/build-build-openshift-io-v1.adoc +++ /dev/null @@ -1,2402 +0,0 @@ -[id="build-build-openshift-io-v1"] -= Build [build.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Build encapsulates the inputs needed to produce a new deployable image, as well as the status of the execution and a reference to the Pod which executed the build. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| BuildSpec has the information to represent a build and also additional information about a build - -| `status` -| `object` -| BuildStatus contains the status of a build - -|=== -..spec -Description:: - BuildSpec has the information to represent a build and also additional information about a build - -Type:: - `object` - -Required:: - - `strategy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `completionDeadlineSeconds` -| `integer` -| completionDeadlineSeconds is an optional duration in seconds, counted from the time when a build pod gets scheduled in the system, that the build may be active on a node before the system actively tries to terminate the build; value must be positive integer - -| `nodeSelector` -| `object (string)` -| nodeSelector is a selector which must be true for the build pod to fit on a node If nil, it can be overridden by default build nodeselector values for the cluster. If set to an empty map or a map with any values, default build nodeselector values are ignored. - -| `output` -| `object` -| BuildOutput is input to a build strategy and describes the container image that the strategy should produce. - -| `postCommit` -| `object` -| A BuildPostCommitSpec holds a build post commit hook specification. The hook executes a command in a temporary container running the build output image, immediately after the last layer of the image is committed and before the image is pushed to a registry. The command is executed with the current working directory ($PWD) set to the image's WORKDIR. - -The build will be marked as failed if the hook execution fails. It will fail if the script or command return a non-zero exit code, or if there is any other error related to starting the temporary container. - -There are five different ways to configure the hook. As an example, all forms below are equivalent and will execute `rake test --verbose`. - -1. Shell script: - - "postCommit": { - "script": "rake test --verbose", - } - - The above is a convenient form which is equivalent to: - - "postCommit": { - "command": ["/bin/sh", "-ic"], - "args": ["rake test --verbose"] - } - -2. A command as the image entrypoint: - - "postCommit": { - "commit": ["rake", "test", "--verbose"] - } - - Command overrides the image entrypoint in the exec form, as documented in - Docker: https://docs.docker.com/engine/reference/builder/#entrypoint. - -3. Pass arguments to the default entrypoint: - - "postCommit": { - "args": ["rake", "test", "--verbose"] - } - - This form is only useful if the image entrypoint can handle arguments. - -4. Shell script with arguments: - - "postCommit": { - "script": "rake test $1", - "args": ["--verbose"] - } - - This form is useful if you need to pass arguments that would otherwise be - hard to quote properly in the shell script. In the script, $0 will be - "/bin/sh" and $1, $2, etc, are the positional arguments from Args. - -5. Command with arguments: - - "postCommit": { - "command": ["rake", "test"], - "args": ["--verbose"] - } - - This form is equivalent to appending the arguments to the Command slice. - -It is invalid to provide both Script and Command simultaneously. If none of the fields are specified, the hook is not executed. - -| `resources` -| xref:../objects/index.adoc#resourcerequirements-core-v1[`ResourceRequirements core/v1`] -| resources computes resource requirements to execute the build. - -| `revision` -| `object` -| SourceRevision is the revision or commit information from the source for the build - -| `serviceAccount` -| `string` -| serviceAccount is the name of the ServiceAccount to use to run the pod created by this build. The pod will be allowed to use secrets referenced by the ServiceAccount - -| `source` -| `object` -| BuildSource is the SCM used for the build. - -| `strategy` -| `object` -| BuildStrategy contains the details of how to perform a build. - -| `triggeredBy` -| `array` -| triggeredBy describes which triggers started the most recent update to the build configuration and contains information about those triggers. - -| `triggeredBy[]` -| `object` -| BuildTriggerCause holds information about a triggered build. It is used for displaying build trigger data for each build and build configuration in oc describe. It is also used to describe which triggers led to the most recent update in the build configuration. - -|=== -..spec.output -Description:: - BuildOutput is input to a build strategy and describes the container image that the strategy should produce. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `imageLabels` -| `array` -| imageLabels define a list of labels that are applied to the resulting image. If there are multiple labels with the same name then the last one in the list is used. - -| `imageLabels[]` -| `object` -| ImageLabel represents a label applied to the resulting image. - -| `pushSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| PushSecret is the name of a Secret that would be used for setting up the authentication for executing the Docker push to authentication enabled Docker Registry (or Docker Hub). - -| `to` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| to defines an optional location to push the output of this build to. Kind must be one of 'ImageStreamTag' or 'DockerImage'. This value will be used to look up a container image repository to push to. In the case of an ImageStreamTag, the ImageStreamTag will be looked for in the namespace of the build unless Namespace is specified. - -|=== -..spec.output.imageLabels -Description:: - imageLabels define a list of labels that are applied to the resulting image. If there are multiple labels with the same name then the last one in the list is used. - -Type:: - `array` - - - - -..spec.output.imageLabels[] -Description:: - ImageLabel represents a label applied to the resulting image. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name defines the name of the label. It must have non-zero length. - -| `value` -| `string` -| value defines the literal value of the label. - -|=== -..spec.postCommit -Description:: - A BuildPostCommitSpec holds a build post commit hook specification. The hook executes a command in a temporary container running the build output image, immediately after the last layer of the image is committed and before the image is pushed to a registry. The command is executed with the current working directory ($PWD) set to the image's WORKDIR. - -The build will be marked as failed if the hook execution fails. It will fail if the script or command return a non-zero exit code, or if there is any other error related to starting the temporary container. - -There are five different ways to configure the hook. As an example, all forms below are equivalent and will execute `rake test --verbose`. - -1. Shell script: - - "postCommit": { - "script": "rake test --verbose", - } - - The above is a convenient form which is equivalent to: - - "postCommit": { - "command": ["/bin/sh", "-ic"], - "args": ["rake test --verbose"] - } - -2. A command as the image entrypoint: - - "postCommit": { - "commit": ["rake", "test", "--verbose"] - } - - Command overrides the image entrypoint in the exec form, as documented in - Docker: https://docs.docker.com/engine/reference/builder/#entrypoint. - -3. Pass arguments to the default entrypoint: - - "postCommit": { - "args": ["rake", "test", "--verbose"] - } - - This form is only useful if the image entrypoint can handle arguments. - -4. Shell script with arguments: - - "postCommit": { - "script": "rake test $1", - "args": ["--verbose"] - } - - This form is useful if you need to pass arguments that would otherwise be - hard to quote properly in the shell script. In the script, $0 will be - "/bin/sh" and $1, $2, etc, are the positional arguments from Args. - -5. Command with arguments: - - "postCommit": { - "command": ["rake", "test"], - "args": ["--verbose"] - } - - This form is equivalent to appending the arguments to the Command slice. - -It is invalid to provide both Script and Command simultaneously. If none of the fields are specified, the hook is not executed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| args is a list of arguments that are provided to either Command, Script or the container image's default entrypoint. The arguments are placed immediately after the command to be run. - -| `command` -| `array (string)` -| command is the command to run. It may not be specified with Script. This might be needed if the image doesn't have `/bin/sh`, or if you do not want to use a shell. In all other cases, using Script might be more convenient. - -| `script` -| `string` -| script is a shell script to be run with `/bin/sh -ic`. It may not be specified with Command. Use Script when a shell script is appropriate to execute the post build hook, for example for running unit tests with `rake test`. If you need control over the image entrypoint, or if the image does not have `/bin/sh`, use Command and/or Args. The `-i` flag is needed to support CentOS and RHEL images that use Software Collections (SCL), in order to have the appropriate collections enabled in the shell. E.g., in the Ruby image, this is necessary to make `ruby`, `bundle` and other binaries available in the PATH. - -|=== -..spec.revision -Description:: - SourceRevision is the revision or commit information from the source for the build - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `git` -| `object` -| GitSourceRevision is the commit information from a git source for a build - -| `type` -| `string` -| type of the build source, may be one of 'Source', 'Dockerfile', 'Binary', or 'Images' - -|=== -..spec.revision.git -Description:: - GitSourceRevision is the commit information from a git source for a build - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `author` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `commit` -| `string` -| commit is the commit hash identifying a specific commit - -| `committer` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `message` -| `string` -| message is the description of a specific commit - -|=== -..spec.revision.git.author -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.revision.git.committer -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.source -Description:: - BuildSource is the SCM used for the build. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `binary` -| `object` -| BinaryBuildSource describes a binary file to be used for the Docker and Source build strategies, where the file will be extracted and used as the build source. - -| `configMaps` -| `array` -| configMaps represents a list of configMaps and their destinations that will be used for the build. - -| `configMaps[]` -| `object` -| ConfigMapBuildSource describes a configmap and its destination directory that will be used only at the build time. The content of the configmap referenced here will be copied into the destination directory instead of mounting. - -| `contextDir` -| `string` -| contextDir specifies the sub-directory where the source code for the application exists. This allows to have buildable sources in directory other than root of repository. - -| `dockerfile` -| `string` -| dockerfile is the raw contents of a Dockerfile which should be built. When this option is specified, the FROM may be modified based on your strategy base image and additional ENV stanzas from your strategy environment will be added after the FROM, but before the rest of your Dockerfile stanzas. The Dockerfile source type may be used with other options like git - in those cases the Git repo will have any innate Dockerfile replaced in the context dir. - -| `git` -| `object` -| GitBuildSource defines the parameters of a Git SCM - -| `images` -| `array` -| images describes a set of images to be used to provide source for the build - -| `images[]` -| `object` -| ImageSource is used to describe build source that will be extracted from an image or used during a multi stage build. A reference of type ImageStreamTag, ImageStreamImage or DockerImage may be used. A pull secret can be specified to pull the image from an external registry or override the default service account secret if pulling from the internal registry. Image sources can either be used to extract content from an image and place it into the build context along with the repository source, or used directly during a multi-stage container image build to allow content to be copied without overwriting the contents of the repository source (see the 'paths' and 'as' fields). - -| `secrets` -| `array` -| secrets represents a list of secrets and their destinations that will be used only for the build. - -| `secrets[]` -| `object` -| SecretBuildSource describes a secret and its destination directory that will be used only at the build time. The content of the secret referenced here will be copied into the destination directory instead of mounting. - -| `sourceSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| sourceSecret is the name of a Secret that would be used for setting up the authentication for cloning private repository. The secret contains valid credentials for remote repository, where the data's key represent the authentication method to be used and value is the base64 encoded credentials. Supported auth methods are: ssh-privatekey. - -| `type` -| `string` -| type of build input to accept - -|=== -..spec.source.binary -Description:: - BinaryBuildSource describes a binary file to be used for the Docker and Source build strategies, where the file will be extracted and used as the build source. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `asFile` -| `string` -| asFile indicates that the provided binary input should be considered a single file within the build input. For example, specifying "webapp.war" would place the provided binary as `/webapp.war` for the builder. If left empty, the Docker and Source build strategies assume this file is a zip, tar, or tar.gz file and extract it as the source. The custom strategy receives this binary as standard input. This filename may not contain slashes or be '..' or '.'. - -|=== -..spec.source.configMaps -Description:: - configMaps represents a list of configMaps and their destinations that will be used for the build. - -Type:: - `array` - - - - -..spec.source.configMaps[] -Description:: - ConfigMapBuildSource describes a configmap and its destination directory that will be used only at the build time. The content of the configmap referenced here will be copied into the destination directory instead of mounting. - -Type:: - `object` - -Required:: - - `configMap` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| configMap is a reference to an existing configmap that you want to use in your build. - -| `destinationDir` -| `string` -| destinationDir is the directory where the files from the configmap should be available for the build time. For the Source build strategy, these will be injected into a container where the assemble script runs. For the container image build strategy, these will be copied into the build directory, where the Dockerfile is located, so users can ADD or COPY them during container image build. - -|=== -..spec.source.git -Description:: - GitBuildSource defines the parameters of a Git SCM - -Type:: - `object` - -Required:: - - `uri` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `httpProxy` -| `string` -| httpProxy is a proxy used to reach the git repository over http - -| `httpsProxy` -| `string` -| httpsProxy is a proxy used to reach the git repository over https - -| `noProxy` -| `string` -| noProxy is the list of domains for which the proxy should not be used - -| `ref` -| `string` -| ref is the branch/tag/ref to build. - -| `uri` -| `string` -| uri points to the source that will be built. The structure of the source will depend on the type of build to run - -|=== -..spec.source.images -Description:: - images describes a set of images to be used to provide source for the build - -Type:: - `array` - - - - -..spec.source.images[] -Description:: - ImageSource is used to describe build source that will be extracted from an image or used during a multi stage build. A reference of type ImageStreamTag, ImageStreamImage or DockerImage may be used. A pull secret can be specified to pull the image from an external registry or override the default service account secret if pulling from the internal registry. Image sources can either be used to extract content from an image and place it into the build context along with the repository source, or used directly during a multi-stage container image build to allow content to be copied without overwriting the contents of the repository source (see the 'paths' and 'as' fields). - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `as` -| `array (string)` -| A list of image names that this source will be used in place of during a multi-stage container image build. For instance, a Dockerfile that uses "COPY --from=nginx:latest" will first check for an image source that has "nginx:latest" in this field before attempting to pull directly. If the Dockerfile does not reference an image source it is ignored. This field and paths may both be set, in which case the contents will be used twice. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is a reference to an ImageStreamTag, ImageStreamImage, or DockerImage to copy source from. - -| `paths` -| `array` -| paths is a list of source and destination paths to copy from the image. This content will be copied into the build context prior to starting the build. If no paths are set, the build context will not be altered. - -| `paths[]` -| `object` -| ImageSourcePath describes a path to be copied from a source image and its destination within the build directory. - -| `pullSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| pullSecret is a reference to a secret to be used to pull the image from a registry If the image is pulled from the OpenShift registry, this field does not need to be set. - -|=== -..spec.source.images[].paths -Description:: - paths is a list of source and destination paths to copy from the image. This content will be copied into the build context prior to starting the build. If no paths are set, the build context will not be altered. - -Type:: - `array` - - - - -..spec.source.images[].paths[] -Description:: - ImageSourcePath describes a path to be copied from a source image and its destination within the build directory. - -Type:: - `object` - -Required:: - - `sourcePath` - - `destinationDir` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `destinationDir` -| `string` -| destinationDir is the relative directory within the build directory where files copied from the image are placed. - -| `sourcePath` -| `string` -| sourcePath is the absolute path of the file or directory inside the image to copy to the build directory. If the source path ends in /. then the content of the directory will be copied, but the directory itself will not be created at the destination. - -|=== -..spec.source.secrets -Description:: - secrets represents a list of secrets and their destinations that will be used only for the build. - -Type:: - `array` - - - - -..spec.source.secrets[] -Description:: - SecretBuildSource describes a secret and its destination directory that will be used only at the build time. The content of the secret referenced here will be copied into the destination directory instead of mounting. - -Type:: - `object` - -Required:: - - `secret` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `destinationDir` -| `string` -| destinationDir is the directory where the files from the secret should be available for the build time. For the Source build strategy, these will be injected into a container where the assemble script runs. Later, when the script finishes, all files injected will be truncated to zero length. For the container image build strategy, these will be copied into the build directory, where the Dockerfile is located, so users can ADD or COPY them during container image build. - -| `secret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| secret is a reference to an existing secret that you want to use in your build. - -|=== -..spec.strategy -Description:: - BuildStrategy contains the details of how to perform a build. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `customStrategy` -| `object` -| CustomBuildStrategy defines input parameters specific to Custom build. - -| `dockerStrategy` -| `object` -| DockerBuildStrategy defines input parameters specific to container image build. - -| `jenkinsPipelineStrategy` -| `object` -| JenkinsPipelineBuildStrategy holds parameters specific to a Jenkins Pipeline build. Deprecated: use OpenShift Pipelines - -| `sourceStrategy` -| `object` -| SourceBuildStrategy defines input parameters specific to an Source build. - -| `type` -| `string` -| type is the kind of build strategy. - -|=== -..spec.strategy.customStrategy -Description:: - CustomBuildStrategy defines input parameters specific to Custom build. - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `buildAPIVersion` -| `string` -| buildAPIVersion is the requested API version for the Build object serialized and passed to the custom builder - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a builder container. - -| `exposeDockerSocket` -| `boolean` -| exposeDockerSocket will allow running Docker commands (and build container images) from inside the container. - -| `forcePull` -| `boolean` -| forcePull describes if the controller should configure the build pod to always pull the images for the builder or only pull if it is not present locally - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is reference to an DockerImage, ImageStreamTag, or ImageStreamImage from which the container image should be pulled - -| `pullSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| pullSecret is the name of a Secret that would be used for setting up the authentication for pulling the container images from the private Docker registries - -| `secrets` -| `array` -| secrets is a list of additional secrets that will be included in the build pod - -| `secrets[]` -| `object` -| SecretSpec specifies a secret to be included in a build pod and its corresponding mount point - -|=== -..spec.strategy.customStrategy.secrets -Description:: - secrets is a list of additional secrets that will be included in the build pod - -Type:: - `array` - - - - -..spec.strategy.customStrategy.secrets[] -Description:: - SecretSpec specifies a secret to be included in a build pod and its corresponding mount point - -Type:: - `object` - -Required:: - - `secretSource` - - `mountPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| mountPath is the path at which to mount the secret - -| `secretSource` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| secretSource is a reference to the secret - -|=== -..spec.strategy.dockerStrategy -Description:: - DockerBuildStrategy defines input parameters specific to container image build. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `buildArgs` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| buildArgs contains build arguments that will be resolved in the Dockerfile. See https://docs.docker.com/engine/reference/builder/#/arg for more details. - -| `dockerfilePath` -| `string` -| dockerfilePath is the path of the Dockerfile that will be used to build the container image, relative to the root of the context (contextDir). Defaults to `Dockerfile` if unset. - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a builder container. - -| `forcePull` -| `boolean` -| forcePull describes if the builder should pull the images from registry prior to building. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is a reference to an DockerImage, ImageStreamTag, or ImageStreamImage which overrides the FROM image in the Dockerfile for the build. If the Dockerfile uses multi-stage builds, this will replace the image in the last FROM directive of the file. - -| `imageOptimizationPolicy` -| `string` -| imageOptimizationPolicy describes what optimizations the system can use when building images to reduce the final size or time spent building the image. The default policy is 'None' which means the final build image will be equivalent to an image created by the container image build API. The experimental policy 'SkipLayers' will avoid commiting new layers in between each image step, and will fail if the Dockerfile cannot provide compatibility with the 'None' policy. An additional experimental policy 'SkipLayersAndWarn' is the same as 'SkipLayers' but simply warns if compatibility cannot be preserved. - -| `noCache` -| `boolean` -| noCache if set to true indicates that the container image build must be executed with the --no-cache=true flag - -| `pullSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| pullSecret is the name of a Secret that would be used for setting up the authentication for pulling the container images from the private Docker registries - -|=== -..spec.strategy.jenkinsPipelineStrategy -Description:: - JenkinsPipelineBuildStrategy holds parameters specific to a Jenkins Pipeline build. Deprecated: use OpenShift Pipelines - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a build pipeline. - -| `jenkinsfile` -| `string` -| Jenkinsfile defines the optional raw contents of a Jenkinsfile which defines a Jenkins pipeline build. - -| `jenkinsfilePath` -| `string` -| JenkinsfilePath is the optional path of the Jenkinsfile that will be used to configure the pipeline relative to the root of the context (contextDir). If both JenkinsfilePath & Jenkinsfile are both not specified, this defaults to Jenkinsfile in the root of the specified contextDir. - -|=== -..spec.strategy.sourceStrategy -Description:: - SourceBuildStrategy defines input parameters specific to an Source build. - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a builder container. - -| `forcePull` -| `boolean` -| forcePull describes if the builder should pull the images from registry prior to building. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is reference to an DockerImage, ImageStreamTag, or ImageStreamImage from which the container image should be pulled - -| `incremental` -| `boolean` -| incremental flag forces the Source build to do incremental builds if true. - -| `pullSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| pullSecret is the name of a Secret that would be used for setting up the authentication for pulling the container images from the private Docker registries - -| `scripts` -| `string` -| scripts is the location of Source scripts - -|=== -..spec.triggeredBy -Description:: - triggeredBy describes which triggers started the most recent update to the build configuration and contains information about those triggers. - -Type:: - `array` - - - - -..spec.triggeredBy[] -Description:: - BuildTriggerCause holds information about a triggered build. It is used for displaying build trigger data for each build and build configuration in oc describe. It is also used to describe which triggers led to the most recent update in the build configuration. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bitbucketWebHook` -| `object` -| BitbucketWebHookCause has information about a Bitbucket webhook that triggered a build. - -| `genericWebHook` -| `object` -| GenericWebHookCause holds information about a generic WebHook that triggered a build. - -| `githubWebHook` -| `object` -| GitHubWebHookCause has information about a GitHub webhook that triggered a build. - -| `gitlabWebHook` -| `object` -| GitLabWebHookCause has information about a GitLab webhook that triggered a build. - -| `imageChangeBuild` -| `object` -| ImageChangeCause contains information about the image that triggered a build - -| `message` -| `string` -| message is used to store a human readable message for why the build was triggered. E.g.: "Manually triggered by user", "Configuration change",etc. - -|=== -..spec.triggeredBy[].bitbucketWebHook -Description:: - BitbucketWebHookCause has information about a Bitbucket webhook that triggered a build. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `revision` -| `object` -| SourceRevision is the revision or commit information from the source for the build - -| `secret` -| `string` -| Secret is the obfuscated webhook secret that triggered a build. - -|=== -..spec.triggeredBy[].bitbucketWebHook.revision -Description:: - SourceRevision is the revision or commit information from the source for the build - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `git` -| `object` -| GitSourceRevision is the commit information from a git source for a build - -| `type` -| `string` -| type of the build source, may be one of 'Source', 'Dockerfile', 'Binary', or 'Images' - -|=== -..spec.triggeredBy[].bitbucketWebHook.revision.git -Description:: - GitSourceRevision is the commit information from a git source for a build - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `author` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `commit` -| `string` -| commit is the commit hash identifying a specific commit - -| `committer` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `message` -| `string` -| message is the description of a specific commit - -|=== -..spec.triggeredBy[].bitbucketWebHook.revision.git.author -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.triggeredBy[].bitbucketWebHook.revision.git.committer -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.triggeredBy[].genericWebHook -Description:: - GenericWebHookCause holds information about a generic WebHook that triggered a build. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `revision` -| `object` -| SourceRevision is the revision or commit information from the source for the build - -| `secret` -| `string` -| secret is the obfuscated webhook secret that triggered a build. - -|=== -..spec.triggeredBy[].genericWebHook.revision -Description:: - SourceRevision is the revision or commit information from the source for the build - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `git` -| `object` -| GitSourceRevision is the commit information from a git source for a build - -| `type` -| `string` -| type of the build source, may be one of 'Source', 'Dockerfile', 'Binary', or 'Images' - -|=== -..spec.triggeredBy[].genericWebHook.revision.git -Description:: - GitSourceRevision is the commit information from a git source for a build - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `author` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `commit` -| `string` -| commit is the commit hash identifying a specific commit - -| `committer` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `message` -| `string` -| message is the description of a specific commit - -|=== -..spec.triggeredBy[].genericWebHook.revision.git.author -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.triggeredBy[].genericWebHook.revision.git.committer -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.triggeredBy[].githubWebHook -Description:: - GitHubWebHookCause has information about a GitHub webhook that triggered a build. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `revision` -| `object` -| SourceRevision is the revision or commit information from the source for the build - -| `secret` -| `string` -| secret is the obfuscated webhook secret that triggered a build. - -|=== -..spec.triggeredBy[].githubWebHook.revision -Description:: - SourceRevision is the revision or commit information from the source for the build - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `git` -| `object` -| GitSourceRevision is the commit information from a git source for a build - -| `type` -| `string` -| type of the build source, may be one of 'Source', 'Dockerfile', 'Binary', or 'Images' - -|=== -..spec.triggeredBy[].githubWebHook.revision.git -Description:: - GitSourceRevision is the commit information from a git source for a build - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `author` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `commit` -| `string` -| commit is the commit hash identifying a specific commit - -| `committer` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `message` -| `string` -| message is the description of a specific commit - -|=== -..spec.triggeredBy[].githubWebHook.revision.git.author -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.triggeredBy[].githubWebHook.revision.git.committer -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.triggeredBy[].gitlabWebHook -Description:: - GitLabWebHookCause has information about a GitLab webhook that triggered a build. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `revision` -| `object` -| SourceRevision is the revision or commit information from the source for the build - -| `secret` -| `string` -| Secret is the obfuscated webhook secret that triggered a build. - -|=== -..spec.triggeredBy[].gitlabWebHook.revision -Description:: - SourceRevision is the revision or commit information from the source for the build - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `git` -| `object` -| GitSourceRevision is the commit information from a git source for a build - -| `type` -| `string` -| type of the build source, may be one of 'Source', 'Dockerfile', 'Binary', or 'Images' - -|=== -..spec.triggeredBy[].gitlabWebHook.revision.git -Description:: - GitSourceRevision is the commit information from a git source for a build - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `author` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `commit` -| `string` -| commit is the commit hash identifying a specific commit - -| `committer` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `message` -| `string` -| message is the description of a specific commit - -|=== -..spec.triggeredBy[].gitlabWebHook.revision.git.author -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.triggeredBy[].gitlabWebHook.revision.git.committer -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.triggeredBy[].imageChangeBuild -Description:: - ImageChangeCause contains information about the image that triggered a build - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `fromRef` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| fromRef contains detailed information about an image that triggered a build. - -| `imageID` -| `string` -| imageID is the ID of the image that triggered a a new build. - -|=== -..status -Description:: - BuildStatus contains the status of a build - -Type:: - `object` - -Required:: - - `phase` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `cancelled` -| `boolean` -| cancelled describes if a cancel event was triggered for the build. - -| `completionTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| completionTimestamp is a timestamp representing the server time when this Build was finished, whether that build failed or succeeded. It reflects the time at which the Pod running the Build terminated. It is represented in RFC3339 form and is in UTC. - -| `conditions` -| `array` -| Conditions represents the latest available observations of a build's current state. - -| `conditions[]` -| `object` -| BuildCondition describes the state of a build at a certain point. - -| `config` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| config is an ObjectReference to the BuildConfig this Build is based on. - -| `duration` -| `integer` -| duration contains time.Duration object describing build time. - -| `logSnippet` -| `string` -| logSnippet is the last few lines of the build log. This value is only set for builds that failed. - -| `message` -| `string` -| message is a human-readable message indicating details about why the build has this status. - -| `output` -| `object` -| BuildStatusOutput contains the status of the built image. - -| `outputDockerImageReference` -| `string` -| outputDockerImageReference contains a reference to the container image that will be built by this build. Its value is computed from Build.Spec.Output.To, and should include the registry address, so that it can be used to push and pull the image. - -| `phase` -| `string` -| phase is the point in the build lifecycle. Possible values are "New", "Pending", "Running", "Complete", "Failed", "Error", and "Cancelled". - -| `reason` -| `string` -| reason is a brief CamelCase string that describes any failure and is meant for machine parsing and tidy display in the CLI. - -| `stages` -| `array` -| stages contains details about each stage that occurs during the build including start time, duration (in milliseconds), and the steps that occured within each stage. - -| `stages[]` -| `object` -| StageInfo contains details about a build stage. - -| `startTimestamp` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| startTimestamp is a timestamp representing the server time when this Build started running in a Pod. It is represented in RFC3339 form and is in UTC. - -|=== -..status.conditions -Description:: - Conditions represents the latest available observations of a build's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - BuildCondition describes the state of a build at a certain point. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The last time the condition transitioned from one status to another. - -| `lastUpdateTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The last time this condition was updated. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of build condition. - -|=== -..status.output -Description:: - BuildStatusOutput contains the status of the built image. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `to` -| `object` -| BuildStatusOutputTo describes the status of the built image with regards to image registry to which it was supposed to be pushed. - -|=== -..status.output.to -Description:: - BuildStatusOutputTo describes the status of the built image with regards to image registry to which it was supposed to be pushed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `imageDigest` -| `string` -| imageDigest is the digest of the built container image. The digest uniquely identifies the image in the registry to which it was pushed. - -Please note that this field may not always be set even if the push completes successfully - e.g. when the registry returns no digest or returns it in a format that the builder doesn't understand. - -|=== -..status.stages -Description:: - stages contains details about each stage that occurs during the build including start time, duration (in milliseconds), and the steps that occured within each stage. - -Type:: - `array` - - - - -..status.stages[] -Description:: - StageInfo contains details about a build stage. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `durationMilliseconds` -| `integer` -| durationMilliseconds identifies how long the stage took to complete in milliseconds. Note: the duration of a stage can exceed the sum of the duration of the steps within the stage as not all actions are accounted for in explicit build steps. - -| `name` -| `string` -| name is a unique identifier for each build stage that occurs. - -| `startTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| startTime is a timestamp representing the server time when this Stage started. It is represented in RFC3339 form and is in UTC. - -| `steps` -| `array` -| steps contains details about each step that occurs during a build stage including start time and duration in milliseconds. - -| `steps[]` -| `object` -| StepInfo contains details about a build step. - -|=== -..status.stages[].steps -Description:: - steps contains details about each step that occurs during a build stage including start time and duration in milliseconds. - -Type:: - `array` - - - - -..status.stages[].steps[] -Description:: - StepInfo contains details about a build step. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `durationMilliseconds` -| `integer` -| durationMilliseconds identifies how long the step took to complete in milliseconds. - -| `name` -| `string` -| name is a unique identifier for each build step. - -| `startTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| startTime is a timestamp representing the server time when this Step started. it is represented in RFC3339 form and is in UTC. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/build.openshift.io/v1/builds` -- `GET`: list or watch objects of kind Build -* `/apis/build.openshift.io/v1/namespaces/{namespace}/builds` -- `DELETE`: delete collection of Build -- `GET`: list or watch objects of kind Build -- `POST`: create a Build -* `/apis/build.openshift.io/v1/namespaces/{namespace}/builds/{name}` -- `DELETE`: delete a Build -- `GET`: read the specified Build -- `PATCH`: partially update the specified Build -- `PUT`: replace the specified Build -* `/apis/build.openshift.io/v1/namespaces/{namespace}/builds/{name}/log` -- `GET`: read log of the specified Build -* `/apis/build.openshift.io/v1/namespaces/{namespace}/builds/{name}/clone` -- `POST`: create clone of a Build -* `/apis/build.openshift.io/v1/namespaces/{namespace}/builds/{name}/details` -- `PUT`: replace details of the specified Build - - -=== /apis/build.openshift.io/v1/builds - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Build - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#buildlist-build-openshift-io-v1[`BuildList build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/builds - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#buildlist-build-openshift-io-v1[`BuildList build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 202 - Accepted -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/builds/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Build -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Build - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/builds/{name}/log - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the BuildLog -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `container` -| `string` -| cointainer for which to stream logs. Defaults to only container if there is one container in the pod. -| `follow` -| `boolean` -| follow if true indicates that the build log should be streamed until the build terminates. -| `insecureSkipTLSVerifyBackend` -| `boolean` -| insecureSkipTLSVerifyBackend indicates that the apiserver should not confirm the validity of the serving certificate of the backend it is connecting to. This will make the HTTPS connection between the apiserver and the backend insecure. This means the apiserver cannot verify the log data it is receiving came from the real kubelet. If the kubelet is configured to verify the apiserver&#x27;s TLS credentials, it does not mean the connection to the real kubelet is vulnerable to a man in the middle attack (e.g. an attacker could not intercept the actual log data coming from the real kubelet). -| `limitBytes` -| `integer` -| limitBytes, If set, is the number of bytes to read from the server before terminating the log output. This may not display a complete final line of logging, and may return slightly more or slightly less than the specified limit. -| `nowait` -| `boolean` -| noWait if true causes the call to return immediately even if the build is not available yet. Otherwise the server will wait until the build has started. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `previous` -| `boolean` -| previous returns previous build logs. Defaults to false. -| `sinceSeconds` -| `integer` -| sinceSeconds is a relative time in seconds before the current time from which to show logs. If this value precedes the time a pod was started, only logs since the pod start will be returned. If this value is in the future, no logs will be returned. Only one of sinceSeconds or sinceTime may be specified. -| `tailLines` -| `integer` -| tailLines, If set, is the number of lines from the end of the logs to show. If not specified, logs are shown from the creation of the container or sinceSeconds or sinceTime -| `timestamps` -| `boolean` -| timestamps, If true, add an RFC3339 or RFC3339Nano timestamp at the beginning of every line of log output. Defaults to false. -| `version` -| `integer` -| version of the build for which to view logs. -|=== - -HTTP method:: - `GET` - -Description:: - read log of the specified Build - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#buildlog-build-openshift-io-v1[`BuildLog build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/builds/{name}/clone - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the BuildRequest -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create clone of a Build - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#buildrequest-build-openshift-io-v1[`BuildRequest build.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#buildrequest-build-openshift-io-v1[`BuildRequest build.openshift.io/v1`] -| 201 - Created -| xref:../objects/index.adoc#buildrequest-build-openshift-io-v1[`BuildRequest build.openshift.io/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#buildrequest-build-openshift-io-v1[`BuildRequest build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/builds/{name}/details - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Build -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `PUT` - -Description:: - replace details of the specified Build - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/buildconfig-build-openshift-io-v1.adoc b/rest_api/workloads_apis/buildconfig-build-openshift-io-v1.adoc deleted file mode 100644 index 6aef96e8e6e9..000000000000 --- a/rest_api/workloads_apis/buildconfig-build-openshift-io-v1.adoc +++ /dev/null @@ -1,1902 +0,0 @@ -[id="buildconfig-build-openshift-io-v1"] -= BuildConfig [build.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Build configurations define a build process for new container images. There are three types of builds possible - a container image build using a Dockerfile, a Source-to-Image build that uses a specially prepared base image that accepts source code that it can make runnable, and a custom build that can run // arbitrary container images as a base and accept the build parameters. Builds run on the cluster and on completion are pushed to the container image registry specified in the "output" section. A build can be triggered via a webhook, when the base image changes, or when a user manually requests a new build be // created. - -Each build created by a build configuration is numbered and refers back to its parent configuration. Multiple builds can be triggered at once. Builds that do not have "output" set can be used to test code or run a verification build. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| BuildConfigSpec describes when and how builds are created - -| `status` -| `object` -| BuildConfigStatus contains current state of the build config object. - -|=== -..spec -Description:: - BuildConfigSpec describes when and how builds are created - -Type:: - `object` - -Required:: - - `strategy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `completionDeadlineSeconds` -| `integer` -| completionDeadlineSeconds is an optional duration in seconds, counted from the time when a build pod gets scheduled in the system, that the build may be active on a node before the system actively tries to terminate the build; value must be positive integer - -| `failedBuildsHistoryLimit` -| `integer` -| failedBuildsHistoryLimit is the number of old failed builds to retain. When a BuildConfig is created, the 5 most recent failed builds are retained unless this value is set. If removed after the BuildConfig has been created, all failed builds are retained. - -| `nodeSelector` -| `object (string)` -| nodeSelector is a selector which must be true for the build pod to fit on a node If nil, it can be overridden by default build nodeselector values for the cluster. If set to an empty map or a map with any values, default build nodeselector values are ignored. - -| `output` -| `object` -| BuildOutput is input to a build strategy and describes the container image that the strategy should produce. - -| `postCommit` -| `object` -| A BuildPostCommitSpec holds a build post commit hook specification. The hook executes a command in a temporary container running the build output image, immediately after the last layer of the image is committed and before the image is pushed to a registry. The command is executed with the current working directory ($PWD) set to the image's WORKDIR. - -The build will be marked as failed if the hook execution fails. It will fail if the script or command return a non-zero exit code, or if there is any other error related to starting the temporary container. - -There are five different ways to configure the hook. As an example, all forms below are equivalent and will execute `rake test --verbose`. - -1. Shell script: - - "postCommit": { - "script": "rake test --verbose", - } - - The above is a convenient form which is equivalent to: - - "postCommit": { - "command": ["/bin/sh", "-ic"], - "args": ["rake test --verbose"] - } - -2. A command as the image entrypoint: - - "postCommit": { - "commit": ["rake", "test", "--verbose"] - } - - Command overrides the image entrypoint in the exec form, as documented in - Docker: https://docs.docker.com/engine/reference/builder/#entrypoint. - -3. Pass arguments to the default entrypoint: - - "postCommit": { - "args": ["rake", "test", "--verbose"] - } - - This form is only useful if the image entrypoint can handle arguments. - -4. Shell script with arguments: - - "postCommit": { - "script": "rake test $1", - "args": ["--verbose"] - } - - This form is useful if you need to pass arguments that would otherwise be - hard to quote properly in the shell script. In the script, $0 will be - "/bin/sh" and $1, $2, etc, are the positional arguments from Args. - -5. Command with arguments: - - "postCommit": { - "command": ["rake", "test"], - "args": ["--verbose"] - } - - This form is equivalent to appending the arguments to the Command slice. - -It is invalid to provide both Script and Command simultaneously. If none of the fields are specified, the hook is not executed. - -| `resources` -| xref:../objects/index.adoc#resourcerequirements-core-v1[`ResourceRequirements core/v1`] -| resources computes resource requirements to execute the build. - -| `revision` -| `object` -| SourceRevision is the revision or commit information from the source for the build - -| `runPolicy` -| `string` -| RunPolicy describes how the new build created from this build configuration will be scheduled for execution. This is optional, if not specified we default to "Serial". - -| `serviceAccount` -| `string` -| serviceAccount is the name of the ServiceAccount to use to run the pod created by this build. The pod will be allowed to use secrets referenced by the ServiceAccount - -| `source` -| `object` -| BuildSource is the SCM used for the build. - -| `strategy` -| `object` -| BuildStrategy contains the details of how to perform a build. - -| `successfulBuildsHistoryLimit` -| `integer` -| successfulBuildsHistoryLimit is the number of old successful builds to retain. When a BuildConfig is created, the 5 most recent successful builds are retained unless this value is set. If removed after the BuildConfig has been created, all successful builds are retained. - -| `triggers` -| `array` -| triggers determine how new Builds can be launched from a BuildConfig. If no triggers are defined, a new build can only occur as a result of an explicit client build creation. - -| `triggers[]` -| `object` -| BuildTriggerPolicy describes a policy for a single trigger that results in a new Build. - -|=== -..spec.output -Description:: - BuildOutput is input to a build strategy and describes the container image that the strategy should produce. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `imageLabels` -| `array` -| imageLabels define a list of labels that are applied to the resulting image. If there are multiple labels with the same name then the last one in the list is used. - -| `imageLabels[]` -| `object` -| ImageLabel represents a label applied to the resulting image. - -| `pushSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| PushSecret is the name of a Secret that would be used for setting up the authentication for executing the Docker push to authentication enabled Docker Registry (or Docker Hub). - -| `to` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| to defines an optional location to push the output of this build to. Kind must be one of 'ImageStreamTag' or 'DockerImage'. This value will be used to look up a container image repository to push to. In the case of an ImageStreamTag, the ImageStreamTag will be looked for in the namespace of the build unless Namespace is specified. - -|=== -..spec.output.imageLabels -Description:: - imageLabels define a list of labels that are applied to the resulting image. If there are multiple labels with the same name then the last one in the list is used. - -Type:: - `array` - - - - -..spec.output.imageLabels[] -Description:: - ImageLabel represents a label applied to the resulting image. - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| name defines the name of the label. It must have non-zero length. - -| `value` -| `string` -| value defines the literal value of the label. - -|=== -..spec.postCommit -Description:: - A BuildPostCommitSpec holds a build post commit hook specification. The hook executes a command in a temporary container running the build output image, immediately after the last layer of the image is committed and before the image is pushed to a registry. The command is executed with the current working directory ($PWD) set to the image's WORKDIR. - -The build will be marked as failed if the hook execution fails. It will fail if the script or command return a non-zero exit code, or if there is any other error related to starting the temporary container. - -There are five different ways to configure the hook. As an example, all forms below are equivalent and will execute `rake test --verbose`. - -1. Shell script: - - "postCommit": { - "script": "rake test --verbose", - } - - The above is a convenient form which is equivalent to: - - "postCommit": { - "command": ["/bin/sh", "-ic"], - "args": ["rake test --verbose"] - } - -2. A command as the image entrypoint: - - "postCommit": { - "commit": ["rake", "test", "--verbose"] - } - - Command overrides the image entrypoint in the exec form, as documented in - Docker: https://docs.docker.com/engine/reference/builder/#entrypoint. - -3. Pass arguments to the default entrypoint: - - "postCommit": { - "args": ["rake", "test", "--verbose"] - } - - This form is only useful if the image entrypoint can handle arguments. - -4. Shell script with arguments: - - "postCommit": { - "script": "rake test $1", - "args": ["--verbose"] - } - - This form is useful if you need to pass arguments that would otherwise be - hard to quote properly in the shell script. In the script, $0 will be - "/bin/sh" and $1, $2, etc, are the positional arguments from Args. - -5. Command with arguments: - - "postCommit": { - "command": ["rake", "test"], - "args": ["--verbose"] - } - - This form is equivalent to appending the arguments to the Command slice. - -It is invalid to provide both Script and Command simultaneously. If none of the fields are specified, the hook is not executed. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `args` -| `array (string)` -| args is a list of arguments that are provided to either Command, Script or the container image's default entrypoint. The arguments are placed immediately after the command to be run. - -| `command` -| `array (string)` -| command is the command to run. It may not be specified with Script. This might be needed if the image doesn't have `/bin/sh`, or if you do not want to use a shell. In all other cases, using Script might be more convenient. - -| `script` -| `string` -| script is a shell script to be run with `/bin/sh -ic`. It may not be specified with Command. Use Script when a shell script is appropriate to execute the post build hook, for example for running unit tests with `rake test`. If you need control over the image entrypoint, or if the image does not have `/bin/sh`, use Command and/or Args. The `-i` flag is needed to support CentOS and RHEL images that use Software Collections (SCL), in order to have the appropriate collections enabled in the shell. E.g., in the Ruby image, this is necessary to make `ruby`, `bundle` and other binaries available in the PATH. - -|=== -..spec.revision -Description:: - SourceRevision is the revision or commit information from the source for the build - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `git` -| `object` -| GitSourceRevision is the commit information from a git source for a build - -| `type` -| `string` -| type of the build source, may be one of 'Source', 'Dockerfile', 'Binary', or 'Images' - -|=== -..spec.revision.git -Description:: - GitSourceRevision is the commit information from a git source for a build - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `author` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `commit` -| `string` -| commit is the commit hash identifying a specific commit - -| `committer` -| `object` -| SourceControlUser defines the identity of a user of source control - -| `message` -| `string` -| message is the description of a specific commit - -|=== -..spec.revision.git.author -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.revision.git.committer -Description:: - SourceControlUser defines the identity of a user of source control - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `email` -| `string` -| email of the source control user - -| `name` -| `string` -| name of the source control user - -|=== -..spec.source -Description:: - BuildSource is the SCM used for the build. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `binary` -| `object` -| BinaryBuildSource describes a binary file to be used for the Docker and Source build strategies, where the file will be extracted and used as the build source. - -| `configMaps` -| `array` -| configMaps represents a list of configMaps and their destinations that will be used for the build. - -| `configMaps[]` -| `object` -| ConfigMapBuildSource describes a configmap and its destination directory that will be used only at the build time. The content of the configmap referenced here will be copied into the destination directory instead of mounting. - -| `contextDir` -| `string` -| contextDir specifies the sub-directory where the source code for the application exists. This allows to have buildable sources in directory other than root of repository. - -| `dockerfile` -| `string` -| dockerfile is the raw contents of a Dockerfile which should be built. When this option is specified, the FROM may be modified based on your strategy base image and additional ENV stanzas from your strategy environment will be added after the FROM, but before the rest of your Dockerfile stanzas. The Dockerfile source type may be used with other options like git - in those cases the Git repo will have any innate Dockerfile replaced in the context dir. - -| `git` -| `object` -| GitBuildSource defines the parameters of a Git SCM - -| `images` -| `array` -| images describes a set of images to be used to provide source for the build - -| `images[]` -| `object` -| ImageSource is used to describe build source that will be extracted from an image or used during a multi stage build. A reference of type ImageStreamTag, ImageStreamImage or DockerImage may be used. A pull secret can be specified to pull the image from an external registry or override the default service account secret if pulling from the internal registry. Image sources can either be used to extract content from an image and place it into the build context along with the repository source, or used directly during a multi-stage container image build to allow content to be copied without overwriting the contents of the repository source (see the 'paths' and 'as' fields). - -| `secrets` -| `array` -| secrets represents a list of secrets and their destinations that will be used only for the build. - -| `secrets[]` -| `object` -| SecretBuildSource describes a secret and its destination directory that will be used only at the build time. The content of the secret referenced here will be copied into the destination directory instead of mounting. - -| `sourceSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| sourceSecret is the name of a Secret that would be used for setting up the authentication for cloning private repository. The secret contains valid credentials for remote repository, where the data's key represent the authentication method to be used and value is the base64 encoded credentials. Supported auth methods are: ssh-privatekey. - -| `type` -| `string` -| type of build input to accept - -|=== -..spec.source.binary -Description:: - BinaryBuildSource describes a binary file to be used for the Docker and Source build strategies, where the file will be extracted and used as the build source. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `asFile` -| `string` -| asFile indicates that the provided binary input should be considered a single file within the build input. For example, specifying "webapp.war" would place the provided binary as `/webapp.war` for the builder. If left empty, the Docker and Source build strategies assume this file is a zip, tar, or tar.gz file and extract it as the source. The custom strategy receives this binary as standard input. This filename may not contain slashes or be '..' or '.'. - -|=== -..spec.source.configMaps -Description:: - configMaps represents a list of configMaps and their destinations that will be used for the build. - -Type:: - `array` - - - - -..spec.source.configMaps[] -Description:: - ConfigMapBuildSource describes a configmap and its destination directory that will be used only at the build time. The content of the configmap referenced here will be copied into the destination directory instead of mounting. - -Type:: - `object` - -Required:: - - `configMap` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `configMap` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| configMap is a reference to an existing configmap that you want to use in your build. - -| `destinationDir` -| `string` -| destinationDir is the directory where the files from the configmap should be available for the build time. For the Source build strategy, these will be injected into a container where the assemble script runs. For the container image build strategy, these will be copied into the build directory, where the Dockerfile is located, so users can ADD or COPY them during container image build. - -|=== -..spec.source.git -Description:: - GitBuildSource defines the parameters of a Git SCM - -Type:: - `object` - -Required:: - - `uri` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `httpProxy` -| `string` -| httpProxy is a proxy used to reach the git repository over http - -| `httpsProxy` -| `string` -| httpsProxy is a proxy used to reach the git repository over https - -| `noProxy` -| `string` -| noProxy is the list of domains for which the proxy should not be used - -| `ref` -| `string` -| ref is the branch/tag/ref to build. - -| `uri` -| `string` -| uri points to the source that will be built. The structure of the source will depend on the type of build to run - -|=== -..spec.source.images -Description:: - images describes a set of images to be used to provide source for the build - -Type:: - `array` - - - - -..spec.source.images[] -Description:: - ImageSource is used to describe build source that will be extracted from an image or used during a multi stage build. A reference of type ImageStreamTag, ImageStreamImage or DockerImage may be used. A pull secret can be specified to pull the image from an external registry or override the default service account secret if pulling from the internal registry. Image sources can either be used to extract content from an image and place it into the build context along with the repository source, or used directly during a multi-stage container image build to allow content to be copied without overwriting the contents of the repository source (see the 'paths' and 'as' fields). - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `as` -| `array (string)` -| A list of image names that this source will be used in place of during a multi-stage container image build. For instance, a Dockerfile that uses "COPY --from=nginx:latest" will first check for an image source that has "nginx:latest" in this field before attempting to pull directly. If the Dockerfile does not reference an image source it is ignored. This field and paths may both be set, in which case the contents will be used twice. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is a reference to an ImageStreamTag, ImageStreamImage, or DockerImage to copy source from. - -| `paths` -| `array` -| paths is a list of source and destination paths to copy from the image. This content will be copied into the build context prior to starting the build. If no paths are set, the build context will not be altered. - -| `paths[]` -| `object` -| ImageSourcePath describes a path to be copied from a source image and its destination within the build directory. - -| `pullSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| pullSecret is a reference to a secret to be used to pull the image from a registry If the image is pulled from the OpenShift registry, this field does not need to be set. - -|=== -..spec.source.images[].paths -Description:: - paths is a list of source and destination paths to copy from the image. This content will be copied into the build context prior to starting the build. If no paths are set, the build context will not be altered. - -Type:: - `array` - - - - -..spec.source.images[].paths[] -Description:: - ImageSourcePath describes a path to be copied from a source image and its destination within the build directory. - -Type:: - `object` - -Required:: - - `sourcePath` - - `destinationDir` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `destinationDir` -| `string` -| destinationDir is the relative directory within the build directory where files copied from the image are placed. - -| `sourcePath` -| `string` -| sourcePath is the absolute path of the file or directory inside the image to copy to the build directory. If the source path ends in /. then the content of the directory will be copied, but the directory itself will not be created at the destination. - -|=== -..spec.source.secrets -Description:: - secrets represents a list of secrets and their destinations that will be used only for the build. - -Type:: - `array` - - - - -..spec.source.secrets[] -Description:: - SecretBuildSource describes a secret and its destination directory that will be used only at the build time. The content of the secret referenced here will be copied into the destination directory instead of mounting. - -Type:: - `object` - -Required:: - - `secret` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `destinationDir` -| `string` -| destinationDir is the directory where the files from the secret should be available for the build time. For the Source build strategy, these will be injected into a container where the assemble script runs. Later, when the script finishes, all files injected will be truncated to zero length. For the container image build strategy, these will be copied into the build directory, where the Dockerfile is located, so users can ADD or COPY them during container image build. - -| `secret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| secret is a reference to an existing secret that you want to use in your build. - -|=== -..spec.strategy -Description:: - BuildStrategy contains the details of how to perform a build. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `customStrategy` -| `object` -| CustomBuildStrategy defines input parameters specific to Custom build. - -| `dockerStrategy` -| `object` -| DockerBuildStrategy defines input parameters specific to container image build. - -| `jenkinsPipelineStrategy` -| `object` -| JenkinsPipelineBuildStrategy holds parameters specific to a Jenkins Pipeline build. Deprecated: use OpenShift Pipelines - -| `sourceStrategy` -| `object` -| SourceBuildStrategy defines input parameters specific to an Source build. - -| `type` -| `string` -| type is the kind of build strategy. - -|=== -..spec.strategy.customStrategy -Description:: - CustomBuildStrategy defines input parameters specific to Custom build. - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `buildAPIVersion` -| `string` -| buildAPIVersion is the requested API version for the Build object serialized and passed to the custom builder - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a builder container. - -| `exposeDockerSocket` -| `boolean` -| exposeDockerSocket will allow running Docker commands (and build container images) from inside the container. - -| `forcePull` -| `boolean` -| forcePull describes if the controller should configure the build pod to always pull the images for the builder or only pull if it is not present locally - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is reference to an DockerImage, ImageStreamTag, or ImageStreamImage from which the container image should be pulled - -| `pullSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| pullSecret is the name of a Secret that would be used for setting up the authentication for pulling the container images from the private Docker registries - -| `secrets` -| `array` -| secrets is a list of additional secrets that will be included in the build pod - -| `secrets[]` -| `object` -| SecretSpec specifies a secret to be included in a build pod and its corresponding mount point - -|=== -..spec.strategy.customStrategy.secrets -Description:: - secrets is a list of additional secrets that will be included in the build pod - -Type:: - `array` - - - - -..spec.strategy.customStrategy.secrets[] -Description:: - SecretSpec specifies a secret to be included in a build pod and its corresponding mount point - -Type:: - `object` - -Required:: - - `secretSource` - - `mountPath` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mountPath` -| `string` -| mountPath is the path at which to mount the secret - -| `secretSource` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| secretSource is a reference to the secret - -|=== -..spec.strategy.dockerStrategy -Description:: - DockerBuildStrategy defines input parameters specific to container image build. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `buildArgs` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| buildArgs contains build arguments that will be resolved in the Dockerfile. See https://docs.docker.com/engine/reference/builder/#/arg for more details. - -| `dockerfilePath` -| `string` -| dockerfilePath is the path of the Dockerfile that will be used to build the container image, relative to the root of the context (contextDir). Defaults to `Dockerfile` if unset. - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a builder container. - -| `forcePull` -| `boolean` -| forcePull describes if the builder should pull the images from registry prior to building. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is a reference to an DockerImage, ImageStreamTag, or ImageStreamImage which overrides the FROM image in the Dockerfile for the build. If the Dockerfile uses multi-stage builds, this will replace the image in the last FROM directive of the file. - -| `imageOptimizationPolicy` -| `string` -| imageOptimizationPolicy describes what optimizations the system can use when building images to reduce the final size or time spent building the image. The default policy is 'None' which means the final build image will be equivalent to an image created by the container image build API. The experimental policy 'SkipLayers' will avoid commiting new layers in between each image step, and will fail if the Dockerfile cannot provide compatibility with the 'None' policy. An additional experimental policy 'SkipLayersAndWarn' is the same as 'SkipLayers' but simply warns if compatibility cannot be preserved. - -| `noCache` -| `boolean` -| noCache if set to true indicates that the container image build must be executed with the --no-cache=true flag - -| `pullSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| pullSecret is the name of a Secret that would be used for setting up the authentication for pulling the container images from the private Docker registries - -|=== -..spec.strategy.jenkinsPipelineStrategy -Description:: - JenkinsPipelineBuildStrategy holds parameters specific to a Jenkins Pipeline build. Deprecated: use OpenShift Pipelines - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a build pipeline. - -| `jenkinsfile` -| `string` -| Jenkinsfile defines the optional raw contents of a Jenkinsfile which defines a Jenkins pipeline build. - -| `jenkinsfilePath` -| `string` -| JenkinsfilePath is the optional path of the Jenkinsfile that will be used to configure the pipeline relative to the root of the context (contextDir). If both JenkinsfilePath & Jenkinsfile are both not specified, this defaults to Jenkinsfile in the root of the specified contextDir. - -|=== -..spec.strategy.sourceStrategy -Description:: - SourceBuildStrategy defines input parameters specific to an Source build. - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| env contains additional environment variables you want to pass into a builder container. - -| `forcePull` -| `boolean` -| forcePull describes if the builder should pull the images from registry prior to building. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is reference to an DockerImage, ImageStreamTag, or ImageStreamImage from which the container image should be pulled - -| `incremental` -| `boolean` -| incremental flag forces the Source build to do incremental builds if true. - -| `pullSecret` -| xref:../objects/index.adoc#localobjectreference-core-v1[`LocalObjectReference core/v1`] -| pullSecret is the name of a Secret that would be used for setting up the authentication for pulling the container images from the private Docker registries - -| `scripts` -| `string` -| scripts is the location of Source scripts - -|=== -..spec.triggers -Description:: - triggers determine how new Builds can be launched from a BuildConfig. If no triggers are defined, a new build can only occur as a result of an explicit client build creation. - -Type:: - `array` - - - - -..spec.triggers[] -Description:: - BuildTriggerPolicy describes a policy for a single trigger that results in a new Build. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `bitbucket` -| `object` -| WebHookTrigger is a trigger that gets invoked using a webhook type of post - -| `generic` -| `object` -| WebHookTrigger is a trigger that gets invoked using a webhook type of post - -| `github` -| `object` -| WebHookTrigger is a trigger that gets invoked using a webhook type of post - -| `gitlab` -| `object` -| WebHookTrigger is a trigger that gets invoked using a webhook type of post - -| `imageChange` -| `object` -| ImageChangeTrigger allows builds to be triggered when an ImageStream changes - -| `type` -| `string` -| type is the type of build trigger - -|=== -..spec.triggers[].bitbucket -Description:: - WebHookTrigger is a trigger that gets invoked using a webhook type of post - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowEnv` -| `boolean` -| allowEnv determines whether the webhook can set environment variables; can only be set to true for GenericWebHook. - -| `secret` -| `string` -| secret used to validate requests. Deprecated: use SecretReference instead. - -| `secretReference` -| `object` -| SecretLocalReference contains information that points to the local secret being used - -|=== -..spec.triggers[].bitbucket.secretReference -Description:: - SecretLocalReference contains information that points to the local secret being used - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the name of the resource in the same namespace being referenced - -|=== -..spec.triggers[].generic -Description:: - WebHookTrigger is a trigger that gets invoked using a webhook type of post - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowEnv` -| `boolean` -| allowEnv determines whether the webhook can set environment variables; can only be set to true for GenericWebHook. - -| `secret` -| `string` -| secret used to validate requests. Deprecated: use SecretReference instead. - -| `secretReference` -| `object` -| SecretLocalReference contains information that points to the local secret being used - -|=== -..spec.triggers[].generic.secretReference -Description:: - SecretLocalReference contains information that points to the local secret being used - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the name of the resource in the same namespace being referenced - -|=== -..spec.triggers[].github -Description:: - WebHookTrigger is a trigger that gets invoked using a webhook type of post - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowEnv` -| `boolean` -| allowEnv determines whether the webhook can set environment variables; can only be set to true for GenericWebHook. - -| `secret` -| `string` -| secret used to validate requests. Deprecated: use SecretReference instead. - -| `secretReference` -| `object` -| SecretLocalReference contains information that points to the local secret being used - -|=== -..spec.triggers[].github.secretReference -Description:: - SecretLocalReference contains information that points to the local secret being used - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the name of the resource in the same namespace being referenced - -|=== -..spec.triggers[].gitlab -Description:: - WebHookTrigger is a trigger that gets invoked using a webhook type of post - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `allowEnv` -| `boolean` -| allowEnv determines whether the webhook can set environment variables; can only be set to true for GenericWebHook. - -| `secret` -| `string` -| secret used to validate requests. Deprecated: use SecretReference instead. - -| `secretReference` -| `object` -| SecretLocalReference contains information that points to the local secret being used - -|=== -..spec.triggers[].gitlab.secretReference -Description:: - SecretLocalReference contains information that points to the local secret being used - -Type:: - `object` - -Required:: - - `name` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `name` -| `string` -| Name is the name of the resource in the same namespace being referenced - -|=== -..spec.triggers[].imageChange -Description:: - ImageChangeTrigger allows builds to be triggered when an ImageStream changes - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| from is a reference to an ImageStreamTag that will trigger a build when updated It is optional. If no From is specified, the From image from the build strategy will be used. Only one ImageChangeTrigger with an empty From reference is allowed in a build configuration. - -| `lastTriggeredImageID` -| `string` -| lastTriggeredImageID is used internally by the ImageChangeController to save last used image ID for build - -| `paused` -| `boolean` -| paused is true if this trigger is temporarily disabled. Optional. - -|=== -..status -Description:: - BuildConfigStatus contains current state of the build config object. - -Type:: - `object` - -Required:: - - `lastVersion` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastVersion` -| `integer` -| lastVersion is used to inform about number of last triggered build. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/build.openshift.io/v1/buildconfigs` -- `GET`: list or watch objects of kind BuildConfig -* `/apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs` -- `DELETE`: delete collection of BuildConfig -- `GET`: list or watch objects of kind BuildConfig -- `POST`: create a BuildConfig -* `/apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}` -- `DELETE`: delete a BuildConfig -- `GET`: read the specified BuildConfig -- `PATCH`: partially update the specified BuildConfig -- `PUT`: replace the specified BuildConfig -* `/apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/webhooks` -- `POST`: connect POST requests to webhooks of BuildConfig -* `/apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/instantiate` -- `POST`: create instantiate of a BuildConfig -* `/apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/webhooks/{path}` -- `POST`: connect POST requests to webhooks of BuildConfig -* `/apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/instantiatebinary` -- `POST`: connect POST requests to instantiatebinary of BuildConfig - - -=== /apis/build.openshift.io/v1/buildconfigs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind BuildConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#buildconfiglist-build-openshift-io-v1[`BuildConfigList build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of BuildConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind BuildConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#buildconfiglist-build-openshift-io-v1[`BuildConfigList build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a BuildConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| 202 - Accepted -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the BuildConfig -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a BuildConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified BuildConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified BuildConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified BuildConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/buildconfig-build-openshift-io-v1.adoc#buildconfig-build-openshift-io-v1[`BuildConfig build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/webhooks - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Build -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `path` -| `string` -| Path is the URL path to use for the current proxy request to pod. -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to webhooks of BuildConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/instantiate - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the BuildRequest -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create instantiate of a BuildConfig - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#buildrequest-build-openshift-io-v1[`BuildRequest build.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 202 - Accepted -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/webhooks/{path} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Build -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -| `path` -| `string` -| path to the resource -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `path` -| `string` -| Path is the URL path to use for the current proxy request to pod. -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to webhooks of BuildConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/instantiatebinary - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the BinaryBuildRequestOptions -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `asFile` -| `string` -| asFile determines if the binary should be created as a file within the source rather than extracted as an archive -| `revision.authorEmail` -| `string` -| revision.authorEmail of the source control user -| `revision.authorName` -| `string` -| revision.authorName of the source control user -| `revision.commit` -| `string` -| revision.commit is the value identifying a specific commit -| `revision.committerEmail` -| `string` -| revision.committerEmail of the source control user -| `revision.committerName` -| `string` -| revision.committerName of the source control user -| `revision.message` -| `string` -| revision.message is the description of a specific commit -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to instantiatebinary of BuildConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/build-build-openshift-io-v1.adoc#build-build-openshift-io-v1[`Build build.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/cronjob-batch-v1beta1.adoc b/rest_api/workloads_apis/cronjob-batch-v1beta1.adoc deleted file mode 100644 index 0fd74978772d..000000000000 --- a/rest_api/workloads_apis/cronjob-batch-v1beta1.adoc +++ /dev/null @@ -1,770 +0,0 @@ -[id="cronjob-batch-v1beta1"] -= CronJob [batch/v1beta1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - CronJob represents the configuration of a single cron job. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| CronJobSpec describes how the job execution will look like and when it will actually run. - -| `status` -| `object` -| CronJobStatus represents the current state of a cron job. - -|=== -..spec -Description:: - CronJobSpec describes how the job execution will look like and when it will actually run. - -Type:: - `object` - -Required:: - - `schedule` - - `jobTemplate` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `concurrencyPolicy` -| `string` -| Specifies how to treat concurrent executions of a Job. Valid values are: - "Allow" (default): allows CronJobs to run concurrently; - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet; - "Replace": cancels currently running job and replaces it with a new one - -| `failedJobsHistoryLimit` -| `integer` -| The number of failed finished jobs to retain. This is a pointer to distinguish between explicit zero and not specified. Defaults to 1. - -| `jobTemplate` -| `object` -| JobTemplateSpec describes the data a Job should have when created from a template - -| `schedule` -| `string` -| The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron. - -| `startingDeadlineSeconds` -| `integer` -| Optional deadline in seconds for starting the job if it misses scheduled time for any reason. Missed jobs executions will be counted as failed ones. - -| `successfulJobsHistoryLimit` -| `integer` -| The number of successful finished jobs to retain. This is a pointer to distinguish between explicit zero and not specified. Defaults to 3. - -| `suspend` -| `boolean` -| This flag tells the controller to suspend subsequent executions, it does not apply to already started executions. Defaults to false. - -|=== -..spec.jobTemplate -Description:: - JobTemplateSpec describes the data a Job should have when created from a template - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata of the jobs created from this template. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| JobSpec describes how the job execution will look like. - -|=== -..spec.jobTemplate.spec -Description:: - JobSpec describes how the job execution will look like. - -Type:: - `object` - -Required:: - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `activeDeadlineSeconds` -| `integer` -| Specifies the duration in seconds relative to the startTime that the job may be active before the system tries to terminate it; value must be positive integer - -| `backoffLimit` -| `integer` -| Specifies the number of retries before marking this job failed. Defaults to 6 - -| `completions` -| `integer` -| Specifies the desired number of successfully finished pods the job should be run with. Setting to nil means that the success of any pod signals the success of all pods, and allows parallelism to have any positive value. Setting to 1 means that parallelism is limited to 1 and the success of that pod signals the success of the job. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ - -| `manualSelector` -| `boolean` -| manualSelector controls generation of pod labels and pod selectors. Leave `manualSelector` unset unless you are certain what you are doing. When false or unset, the system pick labels unique to this job and appends those labels to the pod template. When true, the user is responsible for picking unique labels and specifying the selector. Failure to pick a unique label may cause this and other jobs to not function correctly. However, You may see `manualSelector=true` in jobs that were created with the old `extensions/v1beta1` API. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/#specifying-your-own-pod-selector - -| `parallelism` -| `integer` -| Specifies the maximum desired number of pods the job should run at any given time. The actual number of pods running in steady state will be less than this number when ((.spec.completions - .status.successful) < .spec.parallelism), i.e. when the work left to do is less than max parallelism. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| A label query over pods that should match the pod count. Normally, the system sets this field for you. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| Describes the pod that will be created when executing a job. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ - -| `ttlSecondsAfterFinished` -| `integer` -| ttlSecondsAfterFinished limits the lifetime of a Job that has finished execution (either Complete or Failed). If this field is set, ttlSecondsAfterFinished after the Job finishes, it is eligible to be automatically deleted. When the Job is being deleted, its lifecycle guarantees (e.g. finalizers) will be honored. If this field is unset, the Job won't be automatically deleted. If this field is set to zero, the Job becomes eligible to be deleted immediately after it finishes. This field is alpha-level and is only honored by servers that enable the TTLAfterFinished feature. - -|=== -..status -Description:: - CronJobStatus represents the current state of a cron job. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `active` -| xref:../objects/index.adoc#objectreference-core-v1[`array (ObjectReference core/v1)`] -| A list of pointers to currently running jobs. - -| `lastScheduleTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Information when was the last time the job was successfully scheduled. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/batch/v1beta1/cronjobs` -- `GET`: list or watch objects of kind CronJob -* `/apis/batch/v1beta1/namespaces/{namespace}/cronjobs` -- `DELETE`: delete collection of CronJob -- `GET`: list or watch objects of kind CronJob -- `POST`: create a CronJob -* `/apis/batch/v1beta1/namespaces/{namespace}/cronjobs/{name}` -- `DELETE`: delete a CronJob -- `GET`: read the specified CronJob -- `PATCH`: partially update the specified CronJob -- `PUT`: replace the specified CronJob -* `/apis/batch/v1beta1/namespaces/{namespace}/cronjobs/{name}/status` -- `GET`: read status of the specified CronJob -- `PATCH`: partially update status of the specified CronJob -- `PUT`: replace status of the specified CronJob - - -=== /apis/batch/v1beta1/cronjobs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind CronJob - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#cronjoblist-batch-v1beta1[`CronJobList batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/batch/v1beta1/namespaces/{namespace}/cronjobs - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#cronjoblist-batch-v1beta1[`CronJobList batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 201 - Created -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 202 - Accepted -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/batch/v1beta1/namespaces/{namespace}/cronjobs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CronJob -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 201 - Created -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/batch/v1beta1/namespaces/{namespace}/cronjobs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the CronJob -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified CronJob - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified CronJob - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 201 - Created -| xref:../workloads_apis/cronjob-batch-v1beta1.adoc#cronjob-batch-v1beta1[`CronJob batch/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/daemonset-apps-v1.adoc b/rest_api/workloads_apis/daemonset-apps-v1.adoc deleted file mode 100644 index e9a2387757c1..000000000000 --- a/rest_api/workloads_apis/daemonset-apps-v1.adoc +++ /dev/null @@ -1,821 +0,0 @@ -[id="daemonset-apps-v1"] -= DaemonSet [apps/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - DaemonSet represents the configuration of a daemon set. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| DaemonSetSpec is the specification of a daemon set. - -| `status` -| `object` -| DaemonSetStatus represents the current status of a daemon set. - -|=== -..spec -Description:: - DaemonSetSpec is the specification of a daemon set. - -Type:: - `object` - -Required:: - - `selector` - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `minReadySeconds` -| `integer` -| The minimum number of seconds for which a newly created DaemonSet pod should be ready without any of its container crashing, for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready). - -| `revisionHistoryLimit` -| `integer` -| The number of old history to retain to allow rollback. This is a pointer to distinguish between explicit zero and not specified. Defaults to 10. - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| A label query over pods that are managed by the daemon set. Must match in order to be controlled. It must match the pod template's labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| An object that describes the pod that will be created. The DaemonSet will create exactly one copy of this pod on every node that matches the template's node selector (or on every node if no node selector is specified). More info: https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller#pod-template - -| `updateStrategy` -| `object` -| DaemonSetUpdateStrategy is a struct used to control the update strategy for a DaemonSet. - -|=== -..spec.updateStrategy -Description:: - DaemonSetUpdateStrategy is a struct used to control the update strategy for a DaemonSet. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `rollingUpdate` -| `object` -| Spec to control the desired behavior of daemon set rolling update. - -| `type` -| `string` -| Type of daemon set update. Can be "RollingUpdate" or "OnDelete". Default is RollingUpdate. - -|=== -..spec.updateStrategy.rollingUpdate -Description:: - Spec to control the desired behavior of daemon set rolling update. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxUnavailable` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| The maximum number of DaemonSet pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of total number of DaemonSet pods at the start of the update (ex: 10%). Absolute number is calculated from percentage by rounding up. This cannot be 0. Default value is 1. Example: when this is set to 30%, at most 30% of the total number of nodes that should be running the daemon pod (i.e. status.desiredNumberScheduled) can have their pods stopped for an update at any given time. The update starts by stopping at most 30% of those DaemonSet pods and then brings up new DaemonSet pods in their place. Once the new pods are available, it then proceeds onto other DaemonSet pods, thus ensuring that at least 70% of original number of DaemonSet pods are available at all times during the update. - -|=== -..status -Description:: - DaemonSetStatus represents the current status of a daemon set. - -Type:: - `object` - -Required:: - - `currentNumberScheduled` - - `numberMisscheduled` - - `desiredNumberScheduled` - - `numberReady` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `collisionCount` -| `integer` -| Count of hash collisions for the DaemonSet. The DaemonSet controller uses this field as a collision avoidance mechanism when it needs to create the name for the newest ControllerRevision. - -| `conditions` -| `array` -| Represents the latest available observations of a DaemonSet's current state. - -| `conditions[]` -| `object` -| DaemonSetCondition describes the state of a DaemonSet at a certain point. - -| `currentNumberScheduled` -| `integer` -| The number of nodes that are running at least 1 daemon pod and are supposed to run the daemon pod. More info: https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/ - -| `desiredNumberScheduled` -| `integer` -| The total number of nodes that should be running the daemon pod (including nodes correctly running the daemon pod). More info: https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/ - -| `numberAvailable` -| `integer` -| The number of nodes that should be running the daemon pod and have one or more of the daemon pod running and available (ready for at least spec.minReadySeconds) - -| `numberMisscheduled` -| `integer` -| The number of nodes that are running the daemon pod, but are not supposed to run the daemon pod. More info: https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/ - -| `numberReady` -| `integer` -| The number of nodes that should be running the daemon pod and have one or more of the daemon pod running and ready. - -| `numberUnavailable` -| `integer` -| The number of nodes that should be running the daemon pod and have none of the daemon pod running and available (ready for at least spec.minReadySeconds) - -| `observedGeneration` -| `integer` -| The most recent generation observed by the daemon set controller. - -| `updatedNumberScheduled` -| `integer` -| The total number of nodes that are running updated daemon pod - -|=== -..status.conditions -Description:: - Represents the latest available observations of a DaemonSet's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - DaemonSetCondition describes the state of a DaemonSet at a certain point. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of DaemonSet condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/apps/v1/daemonsets` -- `GET`: list or watch objects of kind DaemonSet -* `/apis/apps/v1/namespaces/{namespace}/daemonsets` -- `DELETE`: delete collection of DaemonSet -- `GET`: list or watch objects of kind DaemonSet -- `POST`: create a DaemonSet -* `/apis/apps/v1/namespaces/{namespace}/daemonsets/{name}` -- `DELETE`: delete a DaemonSet -- `GET`: read the specified DaemonSet -- `PATCH`: partially update the specified DaemonSet -- `PUT`: replace the specified DaemonSet -* `/apis/apps/v1/namespaces/{namespace}/daemonsets/{name}/status` -- `GET`: read status of the specified DaemonSet -- `PATCH`: partially update status of the specified DaemonSet -- `PUT`: replace status of the specified DaemonSet - - -=== /apis/apps/v1/daemonsets - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind DaemonSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#daemonsetlist-apps-v1[`DaemonSetList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/daemonsets - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#daemonsetlist-apps-v1[`DaemonSetList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 202 - Accepted -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/daemonsets/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DaemonSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/daemonsets/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DaemonSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified DaemonSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified DaemonSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/daemonset-apps-v1.adoc#daemonset-apps-v1[`DaemonSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/deployment-apps-v1.adoc b/rest_api/workloads_apis/deployment-apps-v1.adoc deleted file mode 100644 index 4fc631e9d328..000000000000 --- a/rest_api/workloads_apis/deployment-apps-v1.adoc +++ /dev/null @@ -1,954 +0,0 @@ -[id="deployment-apps-v1"] -= Deployment [apps/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Deployment enables declarative updates for Pods and ReplicaSets. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object metadata. - -| `spec` -| `object` -| DeploymentSpec is the specification of the desired behavior of the Deployment. - -| `status` -| `object` -| DeploymentStatus is the most recently observed status of the Deployment. - -|=== -..spec -Description:: - DeploymentSpec is the specification of the desired behavior of the Deployment. - -Type:: - `object` - -Required:: - - `selector` - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `minReadySeconds` -| `integer` -| Minimum number of seconds for which a newly created pod should be ready without any of its container crashing, for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready) - -| `paused` -| `boolean` -| Indicates that the deployment is paused. - -| `progressDeadlineSeconds` -| `integer` -| The maximum time in seconds for a deployment to make progress before it is considered to be failed. The deployment controller will continue to process failed deployments and a condition with a ProgressDeadlineExceeded reason will be surfaced in the deployment status. Note that progress will not be estimated during the time a deployment is paused. Defaults to 600s. - -| `replicas` -| `integer` -| Number of desired pods. This is a pointer to distinguish between explicit zero and not specified. Defaults to 1. - -| `revisionHistoryLimit` -| `integer` -| The number of old ReplicaSets to retain to allow rollback. This is a pointer to distinguish between explicit zero and not specified. Defaults to 10. - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| Label selector for pods. Existing ReplicaSets whose pods are selected by this will be the ones affected by this deployment. It must match the pod template's labels. - -| `strategy` -| `object` -| DeploymentStrategy describes how to replace existing pods with new ones. - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| Template describes the pods that will be created. - -|=== -..spec.strategy -Description:: - DeploymentStrategy describes how to replace existing pods with new ones. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `rollingUpdate` -| `object` -| Spec to control the desired behavior of rolling update. - -| `type` -| `string` -| Type of deployment. Can be "Recreate" or "RollingUpdate". Default is RollingUpdate. - -|=== -..spec.strategy.rollingUpdate -Description:: - Spec to control the desired behavior of rolling update. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `maxSurge` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| The maximum number of pods that can be scheduled above the desired number of pods. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). This can not be 0 if MaxUnavailable is 0. Absolute number is calculated from percentage by rounding up. Defaults to 25%. Example: when this is set to 30%, the new ReplicaSet can be scaled up immediately when the rolling update starts, such that the total number of old and new pods do not exceed 130% of desired pods. Once old pods have been killed, new ReplicaSet can be scaled up further, ensuring that total number of pods running at any time during the update is at most 130% of desired pods. - -| `maxUnavailable` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| The maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). Absolute number is calculated from percentage by rounding down. This can not be 0 if MaxSurge is 0. Defaults to 25%. Example: when this is set to 30%, the old ReplicaSet can be scaled down to 70% of desired pods immediately when the rolling update starts. Once new pods are ready, old ReplicaSet can be scaled down further, followed by scaling up the new ReplicaSet, ensuring that the total number of pods available at all times during the update is at least 70% of desired pods. - -|=== -..status -Description:: - DeploymentStatus is the most recently observed status of the Deployment. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| Total number of available pods (ready for at least minReadySeconds) targeted by this deployment. - -| `collisionCount` -| `integer` -| Count of hash collisions for the Deployment. The Deployment controller uses this field as a collision avoidance mechanism when it needs to create the name for the newest ReplicaSet. - -| `conditions` -| `array` -| Represents the latest available observations of a deployment's current state. - -| `conditions[]` -| `object` -| DeploymentCondition describes the state of a deployment at a certain point. - -| `observedGeneration` -| `integer` -| The generation observed by the deployment controller. - -| `readyReplicas` -| `integer` -| Total number of ready pods targeted by this deployment. - -| `replicas` -| `integer` -| Total number of non-terminated pods targeted by this deployment (their labels match the selector). - -| `unavailableReplicas` -| `integer` -| Total number of unavailable pods targeted by this deployment. This is the total number of pods that are still required for the deployment to have 100% available capacity. They may either be pods that are running but not yet available or pods that still have not been created. - -| `updatedReplicas` -| `integer` -| Total number of non-terminated pods targeted by this deployment that have the desired template spec. - -|=== -..status.conditions -Description:: - Represents the latest available observations of a deployment's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - DeploymentCondition describes the state of a deployment at a certain point. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transitioned from one status to another. - -| `lastUpdateTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The last time this condition was updated. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of deployment condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/apps/v1/deployments` -- `GET`: list or watch objects of kind Deployment -* `/apis/apps/v1/namespaces/{namespace}/deployments` -- `DELETE`: delete collection of Deployment -- `GET`: list or watch objects of kind Deployment -- `POST`: create a Deployment -* `/apis/apps/v1/namespaces/{namespace}/deployments/{name}` -- `DELETE`: delete a Deployment -- `GET`: read the specified Deployment -- `PATCH`: partially update the specified Deployment -- `PUT`: replace the specified Deployment -* `/apis/apps/v1/namespaces/{namespace}/deployments/{name}/scale` -- `GET`: read scale of the specified Deployment -- `PATCH`: partially update scale of the specified Deployment -- `PUT`: replace scale of the specified Deployment -* `/apis/apps/v1/namespaces/{namespace}/deployments/{name}/status` -- `GET`: read status of the specified Deployment -- `PATCH`: partially update status of the specified Deployment -- `PUT`: replace status of the specified Deployment - - -=== /apis/apps/v1/deployments - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Deployment - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#deploymentlist-apps-v1[`DeploymentList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/deployments - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#deploymentlist-apps-v1[`DeploymentList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 201 - Created -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 202 - Accepted -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/deployments/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Deployment -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 201 - Created -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/deployments/{name}/scale - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Scale -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read scale of the specified Deployment - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update scale of the specified Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace scale of the specified Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 201 - Created -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/deployments/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Deployment -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Deployment - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Deployment - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 201 - Created -| xref:../workloads_apis/deployment-apps-v1.adoc#deployment-apps-v1[`Deployment apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc b/rest_api/workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc deleted file mode 100644 index 284d6b50d587..000000000000 --- a/rest_api/workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc +++ /dev/null @@ -1,1946 +0,0 @@ -[id="deploymentconfig-apps-openshift-io-v1"] -= DeploymentConfig [apps.openshift.io/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Deployment Configs define the template for a pod and manages deploying new images or configuration changes. A single deployment configuration is usually analogous to a single micro-service. Can support many different deployment patterns, including full restart, customizable rolling updates, and fully custom behaviors, as well as pre- and post- deployment hooks. Each individual deployment is represented as a replication controller. - -A deployment is "triggered" when its configuration is changed or a tag in an Image Stream is changed. Triggers can be disabled to allow manual control over a deployment. The "strategy" determines how the deployment is carried out and may be changed at any time. The `latestVersion` field is updated when a new deployment is triggered by any means. - -Type:: - `object` - -Required:: - - `spec` - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| DeploymentConfigSpec represents the desired state of the deployment. - -| `status` -| `object` -| DeploymentConfigStatus represents the current deployment state. - -|=== -..spec -Description:: - DeploymentConfigSpec represents the desired state of the deployment. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `minReadySeconds` -| `integer` -| MinReadySeconds is the minimum number of seconds for which a newly created pod should be ready without any of its container crashing, for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready) - -| `paused` -| `boolean` -| Paused indicates that the deployment config is paused resulting in no new deployments on template changes or changes in the template caused by other triggers. - -| `replicas` -| `integer` -| Replicas is the number of desired replicas. - -| `revisionHistoryLimit` -| `integer` -| RevisionHistoryLimit is the number of old ReplicationControllers to retain to allow for rollbacks. This field is a pointer to allow for differentiation between an explicit zero and not specified. Defaults to 10. (This only applies to DeploymentConfigs created via the new group API resource, not the legacy resource.) - -| `selector` -| `object (string)` -| Selector is a label query over pods that should match the Replicas count. - -| `strategy` -| `object` -| DeploymentStrategy describes how to perform a deployment. - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| Template is the object that describes the pod that will be created if insufficient replicas are detected. - -| `test` -| `boolean` -| Test ensures that this deployment config will have zero replicas except while a deployment is running. This allows the deployment config to be used as a continuous deployment test - triggering on images, running the deployment, and then succeeding or failing. Post strategy hooks and After actions can be used to integrate successful deployment with an action. - -| `triggers` -| `array` -| Triggers determine how updates to a DeploymentConfig result in new deployments. If no triggers are defined, a new deployment can only occur as a result of an explicit client update to the DeploymentConfig with a new LatestVersion. If null, defaults to having a config change trigger. - -| `triggers[]` -| `object` -| DeploymentTriggerPolicy describes a policy for a single trigger that results in a new deployment. - -|=== -..spec.strategy -Description:: - DeploymentStrategy describes how to perform a deployment. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `activeDeadlineSeconds` -| `integer` -| ActiveDeadlineSeconds is the duration in seconds that the deployer pods for this deployment config may be active on a node before the system actively tries to terminate them. - -| `annotations` -| `object (string)` -| Annotations is a set of key, value pairs added to custom deployer and lifecycle pre/post hook pods. - -| `customParams` -| `object` -| CustomDeploymentStrategyParams are the input to the Custom deployment strategy. - -| `labels` -| `object (string)` -| Labels is a set of key, value pairs added to custom deployer and lifecycle pre/post hook pods. - -| `recreateParams` -| `object` -| RecreateDeploymentStrategyParams are the input to the Recreate deployment strategy. - -| `resources` -| xref:../objects/index.adoc#resourcerequirements-core-v1[`ResourceRequirements core/v1`] -| Resources contains resource requirements to execute the deployment and any hooks. - -| `rollingParams` -| `object` -| RollingDeploymentStrategyParams are the input to the Rolling deployment strategy. - -| `type` -| `string` -| Type is the name of a deployment strategy. - -|=== -..spec.strategy.customParams -Description:: - CustomDeploymentStrategyParams are the input to the Custom deployment strategy. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is optional and overrides CMD in the container Image. - -| `environment` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| Environment holds the environment which will be given to the container for Image. - -| `image` -| `string` -| Image specifies a container image which can carry out a deployment. - -|=== -..spec.strategy.recreateParams -Description:: - RecreateDeploymentStrategyParams are the input to the Recreate deployment strategy. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `mid` -| `object` -| LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -| `post` -| `object` -| LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -| `pre` -| `object` -| LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -| `timeoutSeconds` -| `integer` -| TimeoutSeconds is the time to wait for updates before giving up. If the value is nil, a default will be used. - -|=== -..spec.strategy.recreateParams.mid -Description:: - LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -Type:: - `object` - -Required:: - - `failurePolicy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `execNewPod` -| `object` -| ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -| `failurePolicy` -| `string` -| FailurePolicy specifies what action to take if the hook fails. - -| `tagImages` -| `array` -| TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -| `tagImages[]` -| `object` -| TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -|=== -..spec.strategy.recreateParams.mid.execNewPod -Description:: - ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -Type:: - `object` - -Required:: - - `command` - - `containerName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the action command and its arguments. - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment pod template whose container image will be used for the hook pod's container. - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| Env is a set of environment variables to supply to the hook pod's container. - -| `volumes` -| `array (string)` -| Volumes is a list of named volumes from the pod template which should be copied to the hook pod. Volumes names not found in pod spec are ignored. An empty list means no volumes will be copied. - -|=== -..spec.strategy.recreateParams.mid.tagImages -Description:: - TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -Type:: - `array` - - - - -..spec.strategy.recreateParams.mid.tagImages[] -Description:: - TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -Type:: - `object` - -Required:: - - `containerName` - - `to` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment config whose image value will be used as the source of the tag. If there is only a single container this value will be defaulted to the name of that container. - -| `to` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| To is the target ImageStreamTag to set the container's image onto. - -|=== -..spec.strategy.recreateParams.post -Description:: - LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -Type:: - `object` - -Required:: - - `failurePolicy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `execNewPod` -| `object` -| ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -| `failurePolicy` -| `string` -| FailurePolicy specifies what action to take if the hook fails. - -| `tagImages` -| `array` -| TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -| `tagImages[]` -| `object` -| TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -|=== -..spec.strategy.recreateParams.post.execNewPod -Description:: - ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -Type:: - `object` - -Required:: - - `command` - - `containerName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the action command and its arguments. - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment pod template whose container image will be used for the hook pod's container. - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| Env is a set of environment variables to supply to the hook pod's container. - -| `volumes` -| `array (string)` -| Volumes is a list of named volumes from the pod template which should be copied to the hook pod. Volumes names not found in pod spec are ignored. An empty list means no volumes will be copied. - -|=== -..spec.strategy.recreateParams.post.tagImages -Description:: - TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -Type:: - `array` - - - - -..spec.strategy.recreateParams.post.tagImages[] -Description:: - TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -Type:: - `object` - -Required:: - - `containerName` - - `to` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment config whose image value will be used as the source of the tag. If there is only a single container this value will be defaulted to the name of that container. - -| `to` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| To is the target ImageStreamTag to set the container's image onto. - -|=== -..spec.strategy.recreateParams.pre -Description:: - LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -Type:: - `object` - -Required:: - - `failurePolicy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `execNewPod` -| `object` -| ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -| `failurePolicy` -| `string` -| FailurePolicy specifies what action to take if the hook fails. - -| `tagImages` -| `array` -| TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -| `tagImages[]` -| `object` -| TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -|=== -..spec.strategy.recreateParams.pre.execNewPod -Description:: - ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -Type:: - `object` - -Required:: - - `command` - - `containerName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the action command and its arguments. - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment pod template whose container image will be used for the hook pod's container. - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| Env is a set of environment variables to supply to the hook pod's container. - -| `volumes` -| `array (string)` -| Volumes is a list of named volumes from the pod template which should be copied to the hook pod. Volumes names not found in pod spec are ignored. An empty list means no volumes will be copied. - -|=== -..spec.strategy.recreateParams.pre.tagImages -Description:: - TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -Type:: - `array` - - - - -..spec.strategy.recreateParams.pre.tagImages[] -Description:: - TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -Type:: - `object` - -Required:: - - `containerName` - - `to` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment config whose image value will be used as the source of the tag. If there is only a single container this value will be defaulted to the name of that container. - -| `to` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| To is the target ImageStreamTag to set the container's image onto. - -|=== -..spec.strategy.rollingParams -Description:: - RollingDeploymentStrategyParams are the input to the Rolling deployment strategy. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `intervalSeconds` -| `integer` -| IntervalSeconds is the time to wait between polling deployment status after update. If the value is nil, a default will be used. - -| `maxSurge` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| MaxSurge is the maximum number of pods that can be scheduled above the original number of pods. Value can be an absolute number (ex: 5) or a percentage of total pods at the start of the update (ex: 10%). Absolute number is calculated from percentage by rounding up. - -This cannot be 0 if MaxUnavailable is 0. By default, 25% is used. - -Example: when this is set to 30%, the new RC can be scaled up by 30% immediately when the rolling update starts. Once old pods have been killed, new RC can be scaled up further, ensuring that total number of pods running at any time during the update is atmost 130% of original pods. - -| `maxUnavailable` -| xref:../objects/index.adoc#intorstring-util-intstr[`IntOrString util/intstr`] -| MaxUnavailable is the maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of total pods at the start of update (ex: 10%). Absolute number is calculated from percentage by rounding down. - -This cannot be 0 if MaxSurge is 0. By default, 25% is used. - -Example: when this is set to 30%, the old RC can be scaled down by 30% immediately when the rolling update starts. Once new pods are ready, old RC can be scaled down further, followed by scaling up the new RC, ensuring that at least 70% of original number of pods are available at all times during the update. - -| `post` -| `object` -| LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -| `pre` -| `object` -| LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -| `timeoutSeconds` -| `integer` -| TimeoutSeconds is the time to wait for updates before giving up. If the value is nil, a default will be used. - -| `updatePeriodSeconds` -| `integer` -| UpdatePeriodSeconds is the time to wait between individual pod updates. If the value is nil, a default will be used. - -|=== -..spec.strategy.rollingParams.post -Description:: - LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -Type:: - `object` - -Required:: - - `failurePolicy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `execNewPod` -| `object` -| ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -| `failurePolicy` -| `string` -| FailurePolicy specifies what action to take if the hook fails. - -| `tagImages` -| `array` -| TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -| `tagImages[]` -| `object` -| TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -|=== -..spec.strategy.rollingParams.post.execNewPod -Description:: - ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -Type:: - `object` - -Required:: - - `command` - - `containerName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the action command and its arguments. - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment pod template whose container image will be used for the hook pod's container. - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| Env is a set of environment variables to supply to the hook pod's container. - -| `volumes` -| `array (string)` -| Volumes is a list of named volumes from the pod template which should be copied to the hook pod. Volumes names not found in pod spec are ignored. An empty list means no volumes will be copied. - -|=== -..spec.strategy.rollingParams.post.tagImages -Description:: - TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -Type:: - `array` - - - - -..spec.strategy.rollingParams.post.tagImages[] -Description:: - TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -Type:: - `object` - -Required:: - - `containerName` - - `to` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment config whose image value will be used as the source of the tag. If there is only a single container this value will be defaulted to the name of that container. - -| `to` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| To is the target ImageStreamTag to set the container's image onto. - -|=== -..spec.strategy.rollingParams.pre -Description:: - LifecycleHook defines a specific deployment lifecycle action. Only one type of action may be specified at any time. - -Type:: - `object` - -Required:: - - `failurePolicy` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `execNewPod` -| `object` -| ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -| `failurePolicy` -| `string` -| FailurePolicy specifies what action to take if the hook fails. - -| `tagImages` -| `array` -| TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -| `tagImages[]` -| `object` -| TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -|=== -..spec.strategy.rollingParams.pre.execNewPod -Description:: - ExecNewPodHook is a hook implementation which runs a command in a new pod based on the specified container which is assumed to be part of the deployment template. - -Type:: - `object` - -Required:: - - `command` - - `containerName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `command` -| `array (string)` -| Command is the action command and its arguments. - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment pod template whose container image will be used for the hook pod's container. - -| `env` -| xref:../objects/index.adoc#envvar-core-v1[`array (EnvVar core/v1)`] -| Env is a set of environment variables to supply to the hook pod's container. - -| `volumes` -| `array (string)` -| Volumes is a list of named volumes from the pod template which should be copied to the hook pod. Volumes names not found in pod spec are ignored. An empty list means no volumes will be copied. - -|=== -..spec.strategy.rollingParams.pre.tagImages -Description:: - TagImages instructs the deployer to tag the current image referenced under a container onto an image stream tag. - -Type:: - `array` - - - - -..spec.strategy.rollingParams.pre.tagImages[] -Description:: - TagImageHook is a request to tag the image in a particular container onto an ImageStreamTag. - -Type:: - `object` - -Required:: - - `containerName` - - `to` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerName` -| `string` -| ContainerName is the name of a container in the deployment config whose image value will be used as the source of the tag. If there is only a single container this value will be defaulted to the name of that container. - -| `to` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| To is the target ImageStreamTag to set the container's image onto. - -|=== -..spec.triggers -Description:: - Triggers determine how updates to a DeploymentConfig result in new deployments. If no triggers are defined, a new deployment can only occur as a result of an explicit client update to the DeploymentConfig with a new LatestVersion. If null, defaults to having a config change trigger. - -Type:: - `array` - - - - -..spec.triggers[] -Description:: - DeploymentTriggerPolicy describes a policy for a single trigger that results in a new deployment. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `imageChangeParams` -| `object` -| DeploymentTriggerImageChangeParams represents the parameters to the ImageChange trigger. - -| `type` -| `string` -| Type of the trigger - -|=== -..spec.triggers[].imageChangeParams -Description:: - DeploymentTriggerImageChangeParams represents the parameters to the ImageChange trigger. - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `automatic` -| `boolean` -| Automatic means that the detection of a new tag value should result in an image update inside the pod template. - -| `containerNames` -| `array (string)` -| ContainerNames is used to restrict tag updates to the specified set of container names in a pod. If multiple triggers point to the same containers, the resulting behavior is undefined. Future API versions will make this a validation error. If ContainerNames does not point to a valid container, the trigger will be ignored. Future API versions will make this a validation error. - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| From is a reference to an image stream tag to watch for changes. From.Name is the only required subfield - if From.Namespace is blank, the namespace of the current deployment trigger will be used. - -| `lastTriggeredImage` -| `string` -| LastTriggeredImage is the last image to be triggered. - -|=== -..status -Description:: - DeploymentConfigStatus represents the current deployment state. - -Type:: - `object` - -Required:: - - `latestVersion` - - `observedGeneration` - - `replicas` - - `updatedReplicas` - - `availableReplicas` - - `unavailableReplicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| AvailableReplicas is the total number of available pods targeted by this deployment config. - -| `conditions` -| `array` -| Conditions represents the latest available observations of a deployment config's current state. - -| `conditions[]` -| `object` -| DeploymentCondition describes the state of a deployment config at a certain point. - -| `details` -| `object` -| DeploymentDetails captures information about the causes of a deployment. - -| `latestVersion` -| `integer` -| LatestVersion is used to determine whether the current deployment associated with a deployment config is out of sync. - -| `observedGeneration` -| `integer` -| ObservedGeneration is the most recent generation observed by the deployment config controller. - -| `readyReplicas` -| `integer` -| Total number of ready pods targeted by this deployment. - -| `replicas` -| `integer` -| Replicas is the total number of pods targeted by this deployment config. - -| `unavailableReplicas` -| `integer` -| UnavailableReplicas is the total number of unavailable pods targeted by this deployment config. - -| `updatedReplicas` -| `integer` -| UpdatedReplicas is the total number of non-terminated pods targeted by this deployment config that have the desired template spec. - -|=== -..status.conditions -Description:: - Conditions represents the latest available observations of a deployment config's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - DeploymentCondition describes the state of a deployment config at a certain point. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The last time the condition transitioned from one status to another. - -| `lastUpdateTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The last time this condition was updated. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of deployment condition. - -|=== -..status.details -Description:: - DeploymentDetails captures information about the causes of a deployment. - -Type:: - `object` - -Required:: - - `causes` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `causes` -| `array` -| Causes are extended data associated with all the causes for creating a new deployment - -| `causes[]` -| `object` -| DeploymentCause captures information about a particular cause of a deployment. - -| `message` -| `string` -| Message is the user specified change message, if this deployment was triggered manually by the user - -|=== -..status.details.causes -Description:: - Causes are extended data associated with all the causes for creating a new deployment - -Type:: - `array` - - - - -..status.details.causes[] -Description:: - DeploymentCause captures information about a particular cause of a deployment. - -Type:: - `object` - -Required:: - - `type` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `imageTrigger` -| `object` -| DeploymentCauseImageTrigger represents details about the cause of a deployment originating from an image change trigger - -| `type` -| `string` -| Type of the trigger that resulted in the creation of a new deployment - -|=== -..status.details.causes[].imageTrigger -Description:: - DeploymentCauseImageTrigger represents details about the cause of a deployment originating from an image change trigger - -Type:: - `object` - -Required:: - - `from` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `from` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| From is a reference to the changed object which triggered a deployment. The field may have the kinds DockerImage, ImageStreamTag, or ImageStreamImage. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/apps.openshift.io/v1/deploymentconfigs` -- `GET`: list or watch objects of kind DeploymentConfig -* `/apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs` -- `DELETE`: delete collection of DeploymentConfig -- `GET`: list or watch objects of kind DeploymentConfig -- `POST`: create a DeploymentConfig -* `/apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}` -- `DELETE`: delete a DeploymentConfig -- `GET`: read the specified DeploymentConfig -- `PATCH`: partially update the specified DeploymentConfig -- `PUT`: replace the specified DeploymentConfig -* `/apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/log` -- `GET`: read log of the specified DeploymentConfig -* `/apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/scale` -- `GET`: read scale of the specified DeploymentConfig -- `PATCH`: partially update scale of the specified DeploymentConfig -- `PUT`: replace scale of the specified DeploymentConfig -* `/apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/status` -- `GET`: read status of the specified DeploymentConfig -- `PATCH`: partially update status of the specified DeploymentConfig -- `PUT`: replace status of the specified DeploymentConfig -* `/apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/rollback` -- `POST`: create rollback of a DeploymentConfig -* `/apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/instantiate` -- `POST`: create instantiate of a DeploymentConfig - - -=== /apis/apps.openshift.io/v1/deploymentconfigs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind DeploymentConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#deploymentconfiglist-apps-openshift-io-v1[`DeploymentConfigList apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#deploymentconfiglist-apps-openshift-io-v1[`DeploymentConfigList apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 202 - Accepted -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DeploymentConfig -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/log - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DeploymentLog -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `container` -| `string` -| The container for which to stream logs. Defaults to only container if there is one container in the pod. -| `follow` -| `boolean` -| Follow if true indicates that the build log should be streamed until the build terminates. -| `limitBytes` -| `integer` -| If set, the number of bytes to read from the server before terminating the log output. This may not display a complete final line of logging, and may return slightly more or slightly less than the specified limit. -| `nowait` -| `boolean` -| NoWait if true causes the call to return immediately even if the deployment is not available yet. Otherwise the server will wait until the deployment has started. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `previous` -| `boolean` -| Return previous deployment logs. Defaults to false. -| `sinceSeconds` -| `integer` -| A relative time in seconds before the current time from which to show logs. If this value precedes the time a pod was started, only logs since the pod start will be returned. If this value is in the future, no logs will be returned. Only one of sinceSeconds or sinceTime may be specified. -| `tailLines` -| `integer` -| If set, the number of lines from the end of the logs to show. If not specified, logs are shown from the creation of the container or sinceSeconds or sinceTime -| `timestamps` -| `boolean` -| If true, add an RFC3339 or RFC3339Nano timestamp at the beginning of every line of log output. Defaults to false. -| `version` -| `integer` -| Version of the deployment for which to view logs. -|=== - -HTTP method:: - `GET` - -Description:: - read log of the specified DeploymentConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#deploymentlog-apps-openshift-io-v1[`DeploymentLog apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/scale - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Scale -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read scale of the specified DeploymentConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-extensions-v1beta1[`Scale extensions/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update scale of the specified DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-extensions-v1beta1[`Scale extensions/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace scale of the specified DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#scale-extensions-v1beta1[`Scale extensions/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-extensions-v1beta1[`Scale extensions/v1beta1`] -| 201 - Created -| xref:../objects/index.adoc#scale-extensions-v1beta1[`Scale extensions/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DeploymentConfig -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified DeploymentConfig - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified DeploymentConfig - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 201 - Created -| xref:../workloads_apis/deploymentconfig-apps-openshift-io-v1.adoc#deploymentconfig-apps-openshift-io-v1[`DeploymentConfig apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/rollback - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DeploymentConfigRollback -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create rollback of a DeploymentConfig - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deploymentconfigrollback-apps-openshift-io-v1[`DeploymentConfigRollback apps.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#deploymentconfigrollback-apps-openshift-io-v1[`DeploymentConfigRollback apps.openshift.io/v1`] -| 201 - Created -| xref:../objects/index.adoc#deploymentconfigrollback-apps-openshift-io-v1[`DeploymentConfigRollback apps.openshift.io/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#deploymentconfigrollback-apps-openshift-io-v1[`DeploymentConfigRollback apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps.openshift.io/v1/namespaces/{namespace}/deploymentconfigs/{name}/instantiate - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the DeploymentRequest -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create instantiate of a DeploymentConfig - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deploymentrequest-apps-openshift-io-v1[`DeploymentRequest apps.openshift.io/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#deploymentrequest-apps-openshift-io-v1[`DeploymentRequest apps.openshift.io/v1`] -| 201 - Created -| xref:../objects/index.adoc#deploymentrequest-apps-openshift-io-v1[`DeploymentRequest apps.openshift.io/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#deploymentrequest-apps-openshift-io-v1[`DeploymentRequest apps.openshift.io/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/job-batch-v1.adoc b/rest_api/workloads_apis/job-batch-v1.adoc deleted file mode 100644 index d36842b5c145..000000000000 --- a/rest_api/workloads_apis/job-batch-v1.adoc +++ /dev/null @@ -1,773 +0,0 @@ -[id="job-batch-v1"] -= Job [batch/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Job represents the configuration of a single job. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| JobSpec describes how the job execution will look like. - -| `status` -| `object` -| JobStatus represents the current state of a Job. - -|=== -..spec -Description:: - JobSpec describes how the job execution will look like. - -Type:: - `object` - -Required:: - - `template` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `activeDeadlineSeconds` -| `integer` -| Specifies the duration in seconds relative to the startTime that the job may be active before the system tries to terminate it; value must be positive integer - -| `backoffLimit` -| `integer` -| Specifies the number of retries before marking this job failed. Defaults to 6 - -| `completions` -| `integer` -| Specifies the desired number of successfully finished pods the job should be run with. Setting to nil means that the success of any pod signals the success of all pods, and allows parallelism to have any positive value. Setting to 1 means that parallelism is limited to 1 and the success of that pod signals the success of the job. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ - -| `manualSelector` -| `boolean` -| manualSelector controls generation of pod labels and pod selectors. Leave `manualSelector` unset unless you are certain what you are doing. When false or unset, the system pick labels unique to this job and appends those labels to the pod template. When true, the user is responsible for picking unique labels and specifying the selector. Failure to pick a unique label may cause this and other jobs to not function correctly. However, You may see `manualSelector=true` in jobs that were created with the old `extensions/v1beta1` API. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/#specifying-your-own-pod-selector - -| `parallelism` -| `integer` -| Specifies the maximum desired number of pods the job should run at any given time. The actual number of pods running in steady state will be less than this number when ((.spec.completions - .status.successful) < .spec.parallelism), i.e. when the work left to do is less than max parallelism. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| A label query over pods that should match the pod count. Normally, the system sets this field for you. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| Describes the pod that will be created when executing a job. More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ - -| `ttlSecondsAfterFinished` -| `integer` -| ttlSecondsAfterFinished limits the lifetime of a Job that has finished execution (either Complete or Failed). If this field is set, ttlSecondsAfterFinished after the Job finishes, it is eligible to be automatically deleted. When the Job is being deleted, its lifecycle guarantees (e.g. finalizers) will be honored. If this field is unset, the Job won't be automatically deleted. If this field is set to zero, the Job becomes eligible to be deleted immediately after it finishes. This field is alpha-level and is only honored by servers that enable the TTLAfterFinished feature. - -|=== -..status -Description:: - JobStatus represents the current state of a Job. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `active` -| `integer` -| The number of actively running pods. - -| `completionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Represents time when the job was completed. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC. The completion time is only set when the job finishes successfully. - -| `conditions` -| `array` -| The latest available observations of an object's current state. When a job fails, one of the conditions will have type == "Failed". More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ - -| `conditions[]` -| `object` -| JobCondition describes current state of a job. - -| `failed` -| `integer` -| The number of pods which reached phase Failed. - -| `startTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Represents time when the job was acknowledged by the job controller. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC. - -| `succeeded` -| `integer` -| The number of pods which reached phase Succeeded. - -|=== -..status.conditions -Description:: - The latest available observations of an object's current state. When a job fails, one of the conditions will have type == "Failed". More info: https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/ - -Type:: - `array` - - - - -..status.conditions[] -Description:: - JobCondition describes current state of a job. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastProbeTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition was checked. - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transit from one status to another. - -| `message` -| `string` -| Human readable message indicating details about last transition. - -| `reason` -| `string` -| (brief) reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of job condition, Complete or Failed. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/batch/v1/jobs` -- `GET`: list or watch objects of kind Job -* `/apis/batch/v1/namespaces/{namespace}/jobs` -- `DELETE`: delete collection of Job -- `GET`: list or watch objects of kind Job -- `POST`: create a Job -* `/apis/batch/v1/namespaces/{namespace}/jobs/{name}` -- `DELETE`: delete a Job -- `GET`: read the specified Job -- `PATCH`: partially update the specified Job -- `PUT`: replace the specified Job -* `/apis/batch/v1/namespaces/{namespace}/jobs/{name}/status` -- `GET`: read status of the specified Job -- `PATCH`: partially update status of the specified Job -- `PUT`: replace status of the specified Job - - -=== /apis/batch/v1/jobs - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Job - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#joblist-batch-v1[`JobList batch/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/batch/v1/namespaces/{namespace}/jobs - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#joblist-batch-v1[`JobList batch/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 201 - Created -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 202 - Accepted -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/batch/v1/namespaces/{namespace}/jobs/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Job -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 201 - Created -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/batch/v1/namespaces/{namespace}/jobs/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Job -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Job - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Job - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 201 - Created -| xref:../workloads_apis/job-batch-v1.adoc#job-batch-v1[`Job batch/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/persistentvolume-core-v1.adoc b/rest_api/workloads_apis/persistentvolume-core-v1.adoc deleted file mode 100644 index f82cea81d7a2..000000000000 --- a/rest_api/workloads_apis/persistentvolume-core-v1.adoc +++ /dev/null @@ -1,710 +0,0 @@ -[id="persistentvolume-core-v1"] -= PersistentVolume [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - PersistentVolume (PV) is a storage resource provisioned by an administrator. It is analogous to a node. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| PersistentVolumeSpec is the specification of a persistent volume. - -| `status` -| `object` -| PersistentVolumeStatus is the current status of a persistent volume. - -|=== -..spec -Description:: - PersistentVolumeSpec is the specification of a persistent volume. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `accessModes` -| `array (string)` -| AccessModes contains all ways the volume can be mounted. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes - -| `awsElasticBlockStore` -| xref:../objects/index.adoc#awselasticblockstorevolumesource-core-v1[`AWSElasticBlockStoreVolumeSource core/v1`] -| AWSElasticBlockStore represents an AWS Disk resource that is attached to a kubelet's host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore - -| `azureDisk` -| xref:../objects/index.adoc#azurediskvolumesource-core-v1[`AzureDiskVolumeSource core/v1`] -| AzureDisk represents an Azure Data Disk mount on the host and bind mount to the pod. - -| `azureFile` -| xref:../objects/index.adoc#azurefilepersistentvolumesource-core-v1[`AzureFilePersistentVolumeSource core/v1`] -| AzureFile represents an Azure File Service mount on the host and bind mount to the pod. - -| `capacity` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| A description of the persistent volume's resources and capacity. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#capacity - -| `cephfs` -| xref:../objects/index.adoc#cephfspersistentvolumesource-core-v1[`CephFSPersistentVolumeSource core/v1`] -| CephFS represents a Ceph FS mount on the host that shares a pod's lifetime - -| `cinder` -| xref:../objects/index.adoc#cinderpersistentvolumesource-core-v1[`CinderPersistentVolumeSource core/v1`] -| Cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md - -| `claimRef` -| xref:../objects/index.adoc#objectreference-core-v1[`ObjectReference core/v1`] -| ClaimRef is part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound. claim.VolumeName is the authoritative bind between PV and PVC. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#binding - -| `csi` -| xref:../objects/index.adoc#csipersistentvolumesource-core-v1[`CSIPersistentVolumeSource core/v1`] -| CSI represents storage that is handled by an external CSI driver (Beta feature). - -| `fc` -| xref:../objects/index.adoc#fcvolumesource-core-v1[`FCVolumeSource core/v1`] -| FC represents a Fibre Channel resource that is attached to a kubelet's host machine and then exposed to the pod. - -| `flexVolume` -| xref:../objects/index.adoc#flexpersistentvolumesource-core-v1[`FlexPersistentVolumeSource core/v1`] -| FlexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin. - -| `flocker` -| xref:../objects/index.adoc#flockervolumesource-core-v1[`FlockerVolumeSource core/v1`] -| Flocker represents a Flocker volume attached to a kubelet's host machine and exposed to the pod for its usage. This depends on the Flocker control service being running - -| `gcePersistentDisk` -| xref:../objects/index.adoc#gcepersistentdiskvolumesource-core-v1[`GCEPersistentDiskVolumeSource core/v1`] -| GCEPersistentDisk represents a GCE Disk resource that is attached to a kubelet's host machine and then exposed to the pod. Provisioned by an admin. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk - -| `glusterfs` -| xref:../objects/index.adoc#glusterfspersistentvolumesource-core-v1[`GlusterfsPersistentVolumeSource core/v1`] -| Glusterfs represents a Glusterfs volume that is attached to a host and exposed to the pod. Provisioned by an admin. More info: https://examples.k8s.io/volumes/glusterfs/README.md - -| `hostPath` -| xref:../objects/index.adoc#hostpathvolumesource-core-v1[`HostPathVolumeSource core/v1`] -| HostPath represents a directory on the host. Provisioned by a developer or tester. This is useful for single-node development and testing only! On-host storage is not supported in any way and WILL NOT WORK in a multi-node cluster. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath - -| `iscsi` -| xref:../objects/index.adoc#iscsipersistentvolumesource-core-v1[`ISCSIPersistentVolumeSource core/v1`] -| ISCSI represents an ISCSI Disk resource that is attached to a kubelet's host machine and then exposed to the pod. Provisioned by an admin. - -| `local` -| xref:../objects/index.adoc#localvolumesource-core-v1[`LocalVolumeSource core/v1`] -| Local represents directly-attached storage with node affinity - -| `mountOptions` -| `array (string)` -| A list of mount options, e.g. ["ro", "soft"]. Not validated - mount will simply fail if one is invalid. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#mount-options - -| `nfs` -| xref:../objects/index.adoc#nfsvolumesource-core-v1[`NFSVolumeSource core/v1`] -| NFS represents an NFS mount on the host. Provisioned by an admin. More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs - -| `nodeAffinity` -| xref:../objects/index.adoc#volumenodeaffinity-core-v1[`VolumeNodeAffinity core/v1`] -| NodeAffinity defines constraints that limit what nodes this volume can be accessed from. This field influences the scheduling of pods that use this volume. - -| `persistentVolumeReclaimPolicy` -| `string` -| What happens to a persistent volume when released from its claim. Valid options are Retain (default for manually created PersistentVolumes), Delete (default for dynamically provisioned PersistentVolumes), and Recycle (deprecated). Recycle must be supported by the volume plugin underlying this PersistentVolume. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#reclaiming - -| `photonPersistentDisk` -| xref:../objects/index.adoc#photonpersistentdiskvolumesource-core-v1[`PhotonPersistentDiskVolumeSource core/v1`] -| PhotonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine - -| `portworxVolume` -| xref:../objects/index.adoc#portworxvolumesource-core-v1[`PortworxVolumeSource core/v1`] -| PortworxVolume represents a portworx volume attached and mounted on kubelets host machine - -| `quobyte` -| xref:../objects/index.adoc#quobytevolumesource-core-v1[`QuobyteVolumeSource core/v1`] -| Quobyte represents a Quobyte mount on the host that shares a pod's lifetime - -| `rbd` -| xref:../objects/index.adoc#rbdpersistentvolumesource-core-v1[`RBDPersistentVolumeSource core/v1`] -| RBD represents a Rados Block Device mount on the host that shares a pod's lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md - -| `scaleIO` -| xref:../objects/index.adoc#scaleiopersistentvolumesource-core-v1[`ScaleIOPersistentVolumeSource core/v1`] -| ScaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes. - -| `storageClassName` -| `string` -| Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass. - -| `storageos` -| xref:../objects/index.adoc#storageospersistentvolumesource-core-v1[`StorageOSPersistentVolumeSource core/v1`] -| StorageOS represents a StorageOS volume that is attached to the kubelet's host machine and mounted into the pod More info: https://examples.k8s.io/volumes/storageos/README.md - -| `volumeMode` -| `string` -| volumeMode defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec. - -| `vsphereVolume` -| xref:../objects/index.adoc#vspherevirtualdiskvolumesource-core-v1[`VsphereVirtualDiskVolumeSource core/v1`] -| VsphereVolume represents a vSphere volume attached and mounted on kubelets host machine - -|=== -..status -Description:: - PersistentVolumeStatus is the current status of a persistent volume. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `message` -| `string` -| A human-readable message indicating details about why the volume is in this state. - -| `phase` -| `string` -| Phase indicates if a volume is available, bound to a claim, or released by a claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#phase - -| `reason` -| `string` -| Reason is a brief CamelCase string that describes any failure and is meant for machine parsing and tidy display in the CLI. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/persistentvolumes` -- `DELETE`: delete collection of PersistentVolume -- `GET`: list or watch objects of kind PersistentVolume -- `POST`: create a PersistentVolume -* `/api/v1/persistentvolumes/{name}` -- `DELETE`: delete a PersistentVolume -- `GET`: read the specified PersistentVolume -- `PATCH`: partially update the specified PersistentVolume -- `PUT`: replace the specified PersistentVolume -* `/api/v1/persistentvolumes/{name}/status` -- `GET`: read status of the specified PersistentVolume -- `PATCH`: partially update status of the specified PersistentVolume -- `PUT`: replace status of the specified PersistentVolume - - -=== /api/v1/persistentvolumes - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#persistentvolumelist-core-v1[`PersistentVolumeList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 201 - Created -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 202 - Accepted -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/persistentvolumes/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PersistentVolume -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 202 - Accepted -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 201 - Created -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/persistentvolumes/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PersistentVolume -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified PersistentVolume - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified PersistentVolume - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 201 - Created -| xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/pod-core-v1.adoc b/rest_api/workloads_apis/pod-core-v1.adoc deleted file mode 100644 index d40d69ad2fce..000000000000 --- a/rest_api/workloads_apis/pod-core-v1.adoc +++ /dev/null @@ -1,1778 +0,0 @@ -[id="pod-core-v1"] -= Pod [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - Pod is a collection of containers that can run on a host. This resource is created by clients and scheduled onto hosts. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| PodSpec is a description of a pod. - -| `status` -| `object` -| PodStatus represents information about the status of a pod. Status may trail the actual state of a system, especially if the node that hosts the pod cannot contact the control plane. - -|=== -..spec -Description:: - PodSpec is a description of a pod. - -Type:: - `object` - -Required:: - - `containers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `activeDeadlineSeconds` -| `integer` -| Optional duration in seconds the pod may be active on the node relative to StartTime before the system will actively try to mark it failed and kill associated containers. Value must be a positive integer. - -| `affinity` -| xref:../objects/index.adoc#affinity-core-v1[`Affinity core/v1`] -| If specified, the pod's scheduling constraints - -| `automountServiceAccountToken` -| `boolean` -| AutomountServiceAccountToken indicates whether a service account token should be automatically mounted. - -| `containers` -| xref:../objects/index.adoc#container-core-v1[`array (Container core/v1)`] -| List of containers belonging to the pod. Containers cannot currently be added or removed. There must be at least one container in a Pod. Cannot be updated. - -| `dnsConfig` -| xref:../objects/index.adoc#poddnsconfig-core-v1[`PodDNSConfig core/v1`] -| Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy. - -| `dnsPolicy` -| `string` -| Set DNS policy for the pod. Defaults to "ClusterFirst". Valid values are 'ClusterFirstWithHostNet', 'ClusterFirst', 'Default' or 'None'. DNS parameters given in DNSConfig will be merged with the policy selected with DNSPolicy. To have DNS options set along with hostNetwork, you have to specify DNS policy explicitly to 'ClusterFirstWithHostNet'. - -| `enableServiceLinks` -| `boolean` -| EnableServiceLinks indicates whether information about services should be injected into pod's environment variables, matching the syntax of Docker links. Optional: Defaults to true. - -| `ephemeralContainers` -| xref:../objects/index.adoc#ephemeralcontainer-core-v1[`array (EphemeralContainer core/v1)`] -| List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing pod to perform user-initiated actions such as debugging. This list cannot be specified when creating a pod, and it cannot be modified by updating the pod spec. In order to add an ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource. This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature. - -| `hostAliases` -| xref:../objects/index.adoc#hostalias-core-v1[`array (HostAlias core/v1)`] -| HostAliases is an optional list of hosts and IPs that will be injected into the pod's hosts file if specified. This is only valid for non-hostNetwork pods. - -| `hostIPC` -| `boolean` -| Use the host's ipc namespace. Optional: Default to false. - -| `hostNetwork` -| `boolean` -| Host networking requested for this pod. Use the host's network namespace. If this option is set, the ports that will be used must be specified. Default to false. - -| `hostPID` -| `boolean` -| Use the host's pid namespace. Optional: Default to false. - -| `hostname` -| `string` -| Specifies the hostname of the Pod If not specified, the pod's hostname will be set to a system-defined value. - -| `imagePullSecrets` -| xref:../objects/index.adoc#localobjectreference-core-v1[`array (LocalObjectReference core/v1)`] -| ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. For example, in the case of docker, only DockerConfig type secrets are honored. More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod - -| `initContainers` -| xref:../objects/index.adoc#container-core-v1[`array (Container core/v1)`] -| List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. Init containers cannot currently be added or removed. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ - -| `nodeName` -| `string` -| NodeName is a request to schedule this pod onto a specific node. If it is non-empty, the scheduler simply schedules this pod onto that node, assuming that it fits resource requirements. - -| `nodeSelector` -| `object (string)` -| NodeSelector is a selector which must be true for the pod to fit on a node. Selector which must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ - -| `overhead` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Overhead represents the resource overhead associated with running a pod for a given RuntimeClass. This field will be autopopulated at admission time by the RuntimeClass admission controller. If the RuntimeClass admission controller is enabled, overhead must not be set in Pod create requests. The RuntimeClass admission controller will reject Pod create requests which have the overhead already set. If RuntimeClass is configured and selected in the PodSpec, Overhead will be set to the value defined in the corresponding RuntimeClass, otherwise it will remain unset and treated as zero. More info: https://git.k8s.io/enhancements/keps/sig-node/20190226-pod-overhead.md This field is alpha-level as of Kubernetes v1.16, and is only honored by servers that enable the PodOverhead feature. - -| `preemptionPolicy` -| `string` -| PreemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset. This field is beta-level, gated by the NonPreemptingPriority feature-gate. - -| `priority` -| `integer` -| The priority value. Various system components use this field to find the priority of the pod. When Priority Admission Controller is enabled, it prevents users from setting this field. The admission controller populates this field from PriorityClassName. The higher the value, the higher the priority. - -| `priorityClassName` -| `string` -| If specified, indicates the pod's priority. "system-node-critical" and "system-cluster-critical" are two special keywords which indicate the highest priorities with the former being the highest priority. Any other name must be defined by creating a PriorityClass object with that name. If not specified, the pod priority will be default or zero if there is no default. - -| `readinessGates` -| xref:../objects/index.adoc#podreadinessgate-core-v1[`array (PodReadinessGate core/v1)`] -| If specified, all readiness gates will be evaluated for pod readiness. A pod is ready when all its containers are ready AND all conditions specified in the readiness gates have status equal to "True" More info: https://git.k8s.io/enhancements/keps/sig-network/0007-pod-ready%2B%2B.md - -| `restartPolicy` -| `string` -| Restart policy for all containers within the pod. One of Always, OnFailure, Never. Default to Always. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy - -| `runtimeClassName` -| `string` -| RuntimeClassName refers to a RuntimeClass object in the node.k8s.io group, which should be used to run this pod. If no RuntimeClass resource matches the named class, the pod will not be run. If unset or empty, the "legacy" RuntimeClass will be used, which is an implicit class with an empty definition that uses the default runtime handler. More info: https://git.k8s.io/enhancements/keps/sig-node/runtime-class.md This is a beta feature as of Kubernetes v1.14. - -| `schedulerName` -| `string` -| If specified, the pod will be dispatched by specified scheduler. If not specified, the pod will be dispatched by default scheduler. - -| `securityContext` -| xref:../objects/index.adoc#podsecuritycontext-core-v1[`PodSecurityContext core/v1`] -| SecurityContext holds pod-level security attributes and common container settings. Optional: Defaults to empty. See type description for default values of each field. - -| `serviceAccount` -| `string` -| DeprecatedServiceAccount is a depreciated alias for ServiceAccountName. Deprecated: Use serviceAccountName instead. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the name of the ServiceAccount to use to run this pod. More info: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ - -| `setHostnameAsFQDN` -| `boolean` -| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. - -| `shareProcessNamespace` -| `boolean` -| Share a single process namespace between all of the containers in a pod. When this is set containers will be able to view and signal processes from other containers in the same pod, and the first process in each container will not be assigned PID 1. HostPID and ShareProcessNamespace cannot both be set. Optional: Default to false. - -| `subdomain` -| `string` -| If specified, the fully qualified Pod hostname will be "<hostname>.<subdomain>.<pod namespace>.svc.<cluster domain>". If not specified, the pod will not have a domainname at all. - -| `terminationGracePeriodSeconds` -| `integer` -| Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds. - -| `tolerations` -| xref:../objects/index.adoc#toleration-core-v1[`array (Toleration core/v1)`] -| If specified, the pod's tolerations. - -| `topologySpreadConstraints` -| xref:../objects/index.adoc#topologyspreadconstraint-core-v1[`array (TopologySpreadConstraint core/v1)`] -| TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. - -| `volumes` -| xref:../objects/index.adoc#volume-core-v1[`array (Volume core/v1)`] -| List of volumes that can be mounted by containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes - -|=== -..status -Description:: - PodStatus represents information about the status of a pod. Status may trail the actual state of a system, especially if the node that hosts the pod cannot contact the control plane. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `conditions` -| xref:../objects/index.adoc#podcondition-core-v1[`array (PodCondition core/v1)`] -| Current service state of pod. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-conditions - -| `containerStatuses` -| `array` -| The list has one entry per container in the manifest. Each entry is currently the output of `docker inspect`. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status - -| `containerStatuses[]` -| `object` -| ContainerStatus contains details for the current status of this container. - -| `ephemeralContainerStatuses` -| `array` -| Status for any ephemeral containers that have run in this pod. This field is alpha-level and is only populated by servers that enable the EphemeralContainers feature. - -| `ephemeralContainerStatuses[]` -| `object` -| ContainerStatus contains details for the current status of this container. - -| `hostIP` -| `string` -| IP address of the host to which the pod is assigned. Empty if not yet scheduled. - -| `initContainerStatuses` -| `array` -| The list has one entry per init container in the manifest. The most recent successful init container will have ready = true, the most recently started container will have startTime set. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status - -| `initContainerStatuses[]` -| `object` -| ContainerStatus contains details for the current status of this container. - -| `message` -| `string` -| A human readable message indicating details about why the pod is in this condition. - -| `nominatedNodeName` -| `string` -| nominatedNodeName is set only when this pod preempts other pods on the node, but it cannot be scheduled right away as preemption victims receive their graceful termination periods. This field does not guarantee that the pod will be scheduled on this node. Scheduler may decide to place the pod elsewhere if other nodes become available sooner. Scheduler may also decide to give the resources on this node to a higher priority pod that is created after preemption. As a result, this field may be different than PodSpec.nodeName when the pod is scheduled. - -| `phase` -| `string` -| The phase of a Pod is a simple, high-level summary of where the Pod is in its lifecycle. The conditions array, the reason and message fields, and the individual container status arrays contain more detail about the pod's status. There are five possible phase values: - -Pending: The pod has been accepted by the Kubernetes system, but one or more of the container images has not been created. This includes time before being scheduled as well as time spent downloading images over the network, which could take a while. Running: The pod has been bound to a node, and all of the containers have been created. At least one container is still running, or is in the process of starting or restarting. Succeeded: All containers in the pod have terminated in success, and will not be restarted. Failed: All containers in the pod have terminated, and at least one container has terminated in failure. The container either exited with non-zero status or was terminated by the system. Unknown: For some reason the state of the pod could not be obtained, typically due to an error in communicating with the host of the pod. - -More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-phase - -| `podIP` -| `string` -| IP address allocated to the pod. Routable at least within the cluster. Empty if not yet allocated. - -| `podIPs` -| xref:../objects/index.adoc#podip-core-v1[`array (PodIP core/v1)`] -| podIPs holds the IP addresses allocated to the pod. If this field is specified, the 0th entry must match the podIP field. Pods may be allocated at most 1 value for each of IPv4 and IPv6. This list is empty if no IPs have been allocated yet. - -| `qosClass` -| `string` -| The Quality of Service (QOS) classification assigned to the pod based on resource requirements See PodQOSClass type for available QOS classes More info: https://git.k8s.io/community/contributors/design-proposals/node/resource-qos.md - -| `reason` -| `string` -| A brief CamelCase message indicating details about why the pod is in this state. e.g. 'Evicted' - -| `startTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| RFC 3339 date and time at which the object was acknowledged by the Kubelet. This is before the Kubelet pulled the container image(s) for the pod. - -|=== -..status.containerStatuses -Description:: - The list has one entry per container in the manifest. Each entry is currently the output of `docker inspect`. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status - -Type:: - `array` - - - - -..status.containerStatuses[] -Description:: - ContainerStatus contains details for the current status of this container. - -Type:: - `object` - -Required:: - - `name` - - `ready` - - `restartCount` - - `image` - - `imageID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerID` -| `string` -| Container's ID in the format 'docker://<container_id>'. - -| `image` -| `string` -| The image the container is running. More info: https://kubernetes.io/docs/concepts/containers/images - -| `imageID` -| `string` -| ImageID of the container's image. - -| `lastState` -| xref:../objects/index.adoc#containerstate-core-v1[`ContainerState core/v1`] -| Details about the container's last termination condition. - -| `name` -| `string` -| This must be a DNS_LABEL. Each container in a pod must have a unique name. Cannot be updated. - -| `ready` -| `boolean` -| Specifies whether the container has passed its readiness probe. - -| `restartCount` -| `integer` -| The number of times the container has been restarted, currently based on the number of dead containers that have not yet been removed. Note that this is calculated from dead containers. But those containers are subject to garbage collection. This value will get capped at 5 by GC. - -| `started` -| `boolean` -| Specifies whether the container has passed its startup probe. Initialized as false, becomes true after startupProbe is considered successful. Resets to false when the container is restarted, or if kubelet loses state temporarily. Is always true when no startupProbe is defined. - -| `state` -| xref:../objects/index.adoc#containerstate-core-v1[`ContainerState core/v1`] -| Details about the container's current condition. - -|=== -..status.ephemeralContainerStatuses -Description:: - Status for any ephemeral containers that have run in this pod. This field is alpha-level and is only populated by servers that enable the EphemeralContainers feature. - -Type:: - `array` - - - - -..status.ephemeralContainerStatuses[] -Description:: - ContainerStatus contains details for the current status of this container. - -Type:: - `object` - -Required:: - - `name` - - `ready` - - `restartCount` - - `image` - - `imageID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerID` -| `string` -| Container's ID in the format 'docker://<container_id>'. - -| `image` -| `string` -| The image the container is running. More info: https://kubernetes.io/docs/concepts/containers/images - -| `imageID` -| `string` -| ImageID of the container's image. - -| `lastState` -| xref:../objects/index.adoc#containerstate-core-v1[`ContainerState core/v1`] -| Details about the container's last termination condition. - -| `name` -| `string` -| This must be a DNS_LABEL. Each container in a pod must have a unique name. Cannot be updated. - -| `ready` -| `boolean` -| Specifies whether the container has passed its readiness probe. - -| `restartCount` -| `integer` -| The number of times the container has been restarted, currently based on the number of dead containers that have not yet been removed. Note that this is calculated from dead containers. But those containers are subject to garbage collection. This value will get capped at 5 by GC. - -| `started` -| `boolean` -| Specifies whether the container has passed its startup probe. Initialized as false, becomes true after startupProbe is considered successful. Resets to false when the container is restarted, or if kubelet loses state temporarily. Is always true when no startupProbe is defined. - -| `state` -| xref:../objects/index.adoc#containerstate-core-v1[`ContainerState core/v1`] -| Details about the container's current condition. - -|=== -..status.initContainerStatuses -Description:: - The list has one entry per init container in the manifest. The most recent successful init container will have ready = true, the most recently started container will have startTime set. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#pod-and-container-status - -Type:: - `array` - - - - -..status.initContainerStatuses[] -Description:: - ContainerStatus contains details for the current status of this container. - -Type:: - `object` - -Required:: - - `name` - - `ready` - - `restartCount` - - `image` - - `imageID` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `containerID` -| `string` -| Container's ID in the format 'docker://<container_id>'. - -| `image` -| `string` -| The image the container is running. More info: https://kubernetes.io/docs/concepts/containers/images - -| `imageID` -| `string` -| ImageID of the container's image. - -| `lastState` -| xref:../objects/index.adoc#containerstate-core-v1[`ContainerState core/v1`] -| Details about the container's last termination condition. - -| `name` -| `string` -| This must be a DNS_LABEL. Each container in a pod must have a unique name. Cannot be updated. - -| `ready` -| `boolean` -| Specifies whether the container has passed its readiness probe. - -| `restartCount` -| `integer` -| The number of times the container has been restarted, currently based on the number of dead containers that have not yet been removed. Note that this is calculated from dead containers. But those containers are subject to garbage collection. This value will get capped at 5 by GC. - -| `started` -| `boolean` -| Specifies whether the container has passed its startup probe. Initialized as false, becomes true after startupProbe is considered successful. Resets to false when the container is restarted, or if kubelet loses state temporarily. Is always true when no startupProbe is defined. - -| `state` -| xref:../objects/index.adoc#containerstate-core-v1[`ContainerState core/v1`] -| Details about the container's current condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/pods` -- `GET`: list or watch objects of kind Pod -* `/api/v1/namespaces/{namespace}/pods` -- `DELETE`: delete collection of Pod -- `GET`: list or watch objects of kind Pod -- `POST`: create a Pod -* `/api/v1/namespaces/{namespace}/pods/{name}` -- `DELETE`: delete a Pod -- `GET`: read the specified Pod -- `PATCH`: partially update the specified Pod -- `PUT`: replace the specified Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/log` -- `GET`: read log of the specified Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/exec` -- `GET`: connect GET requests to exec of Pod -- `POST`: connect POST requests to exec of Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/proxy` -- `DELETE`: connect DELETE requests to proxy of Pod -- `GET`: connect GET requests to proxy of Pod -- `HEAD`: connect HEAD requests to proxy of Pod -- `OPTIONS`: connect OPTIONS requests to proxy of Pod -- `PATCH`: connect PATCH requests to proxy of Pod -- `POST`: connect POST requests to proxy of Pod -- `PUT`: connect PUT requests to proxy of Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/attach` -- `GET`: connect GET requests to attach of Pod -- `POST`: connect POST requests to attach of Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/status` -- `GET`: read status of the specified Pod -- `PATCH`: partially update status of the specified Pod -- `PUT`: replace status of the specified Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/binding` -- `POST`: create binding of a Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/eviction` -- `POST`: create eviction of a Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/portforward` -- `GET`: connect GET requests to portforward of Pod -- `POST`: connect POST requests to portforward of Pod -* `/api/v1/namespaces/{namespace}/pods/{name}/proxy/{path}` -- `DELETE`: connect DELETE requests to proxy of Pod -- `GET`: connect GET requests to proxy of Pod -- `HEAD`: connect HEAD requests to proxy of Pod -- `OPTIONS`: connect OPTIONS requests to proxy of Pod -- `PATCH`: connect PATCH requests to proxy of Pod -- `POST`: connect POST requests to proxy of Pod -- `PUT`: connect PUT requests to proxy of Pod - - -=== /api/v1/pods - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#podlist-core-v1[`PodList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#podlist-core-v1[`PodList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 201 - Created -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 202 - Accepted -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Pod -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 202 - Accepted -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 201 - Created -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/log - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Pod -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `container` -| `string` -| The container for which to stream logs. Defaults to only container if there is one container in the pod. -| `follow` -| `boolean` -| Follow the log stream of the pod. Defaults to false. -| `insecureSkipTLSVerifyBackend` -| `boolean` -| insecureSkipTLSVerifyBackend indicates that the apiserver should not confirm the validity of the serving certificate of the backend it is connecting to. This will make the HTTPS connection between the apiserver and the backend insecure. This means the apiserver cannot verify the log data it is receiving came from the real kubelet. If the kubelet is configured to verify the apiserver&#x27;s TLS credentials, it does not mean the connection to the real kubelet is vulnerable to a man in the middle attack (e.g. an attacker could not intercept the actual log data coming from the real kubelet). -| `limitBytes` -| `integer` -| If set, the number of bytes to read from the server before terminating the log output. This may not display a complete final line of logging, and may return slightly more or slightly less than the specified limit. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `previous` -| `boolean` -| Return previous terminated container logs. Defaults to false. -| `sinceSeconds` -| `integer` -| A relative time in seconds before the current time from which to show logs. If this value precedes the time a pod was started, only logs since the pod start will be returned. If this value is in the future, no logs will be returned. Only one of sinceSeconds or sinceTime may be specified. -| `tailLines` -| `integer` -| If set, the number of lines from the end of the logs to show. If not specified, logs are shown from the creation of the container or sinceSeconds or sinceTime -| `timestamps` -| `boolean` -| If true, add an RFC3339 or RFC3339Nano timestamp at the beginning of every line of log output. Defaults to false. -|=== - -HTTP method:: - `GET` - -Description:: - read log of the specified Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/exec - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodExecOptions -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `command` -| `string` -| Command is the remote command to execute. argv array. Not executed within a shell. -| `container` -| `string` -| Container in which to execute the command. Defaults to only container if there is only one container in the pod. -| `stderr` -| `boolean` -| Redirect the standard error stream of the pod for this call. Defaults to true. -| `stdin` -| `boolean` -| Redirect the standard input stream of the pod for this call. Defaults to false. -| `stdout` -| `boolean` -| Redirect the standard output stream of the pod for this call. Defaults to true. -| `tty` -| `boolean` -| TTY if true indicates that a tty will be allocated for the exec call. Defaults to false. -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to exec of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to exec of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/proxy - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodProxyOptions -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `path` -| `string` -| Path is the URL path to use for the current proxy request to pod. -|=== - -HTTP method:: - `DELETE` - -Description:: - connect DELETE requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `HEAD` - -Description:: - connect HEAD requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `OPTIONS` - -Description:: - connect OPTIONS requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - connect PATCH requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - connect PUT requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/attach - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodAttachOptions -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `container` -| `string` -| The container in which to execute the command. Defaults to only container if there is only one container in the pod. -| `stderr` -| `boolean` -| Stderr if true indicates that stderr is to be redirected for the attach call. Defaults to true. -| `stdin` -| `boolean` -| Stdin if true, redirects the standard input stream of the pod for this call. Defaults to false. -| `stdout` -| `boolean` -| Stdout if true indicates that stdout is to be redirected for the attach call. Defaults to true. -| `tty` -| `boolean` -| TTY if true indicates that a tty will be allocated for the attach call. This is passed through the container runtime so the tty is allocated on the worker node by the container runtime. Defaults to false. -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to attach of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to attach of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Pod -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified Pod - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 201 - Created -| xref:../workloads_apis/pod-core-v1.adoc#pod-core-v1[`Pod core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/binding - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Binding -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create binding of a Pod - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../metadata_apis/binding-core-v1.adoc#binding-core-v1[`Binding core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../metadata_apis/binding-core-v1.adoc#binding-core-v1[`Binding core/v1`] -| 201 - Created -| xref:../metadata_apis/binding-core-v1.adoc#binding-core-v1[`Binding core/v1`] -| 202 - Accepted -| xref:../metadata_apis/binding-core-v1.adoc#binding-core-v1[`Binding core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/eviction - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Eviction -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `POST` - -Description:: - create eviction of a Pod - - - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#eviction-policy-v1beta1[`Eviction policy/v1beta1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#eviction-policy-v1beta1[`Eviction policy/v1beta1`] -| 201 - Created -| xref:../objects/index.adoc#eviction-policy-v1beta1[`Eviction policy/v1beta1`] -| 202 - Accepted -| xref:../objects/index.adoc#eviction-policy-v1beta1[`Eviction policy/v1beta1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/portforward - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodPortForwardOptions -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `ports` -| `integer` -| List of ports to forward Required when using WebSockets -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to portforward of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to portforward of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/pods/{name}/proxy/{path} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the PodProxyOptions -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -| `path` -| `string` -| path to the resource -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `path` -| `string` -| Path is the URL path to use for the current proxy request to pod. -|=== - -HTTP method:: - `DELETE` - -Description:: - connect DELETE requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - connect GET requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `HEAD` - -Description:: - connect HEAD requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `OPTIONS` - -Description:: - connect OPTIONS requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - connect PATCH requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - connect POST requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - connect PUT requests to proxy of Pod - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| `string` -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/replicaset-apps-v1.adoc b/rest_api/workloads_apis/replicaset-apps-v1.adoc deleted file mode 100644 index 010f90e8c144..000000000000 --- a/rest_api/workloads_apis/replicaset-apps-v1.adoc +++ /dev/null @@ -1,881 +0,0 @@ -[id="replicaset-apps-v1"] -= ReplicaSet [apps/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ReplicaSet ensures that a specified number of pod replicas are running at any given time. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| If the Labels of a ReplicaSet are empty, they are defaulted to be the same as the Pod(s) that the ReplicaSet manages. Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ReplicaSetSpec is the specification of a ReplicaSet. - -| `status` -| `object` -| ReplicaSetStatus represents the current status of a ReplicaSet. - -|=== -..spec -Description:: - ReplicaSetSpec is the specification of a ReplicaSet. - -Type:: - `object` - -Required:: - - `selector` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `minReadySeconds` -| `integer` -| Minimum number of seconds for which a newly created pod should be ready without any of its container crashing, for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready) - -| `replicas` -| `integer` -| Replicas is the number of desired replicas. This is a pointer to distinguish between explicit zero and unspecified. Defaults to 1. More info: https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/#what-is-a-replicationcontroller - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| Selector is a label query over pods that should match the replica count. Label keys and values that must match in order to be controlled by this replica set. It must match the pod template's labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| Template is the object that describes the pod that will be created if insufficient replicas are detected. More info: https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller#pod-template - -|=== -..status -Description:: - ReplicaSetStatus represents the current status of a ReplicaSet. - -Type:: - `object` - -Required:: - - `replicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| The number of available replicas (ready for at least minReadySeconds) for this replica set. - -| `conditions` -| `array` -| Represents the latest available observations of a replica set's current state. - -| `conditions[]` -| `object` -| ReplicaSetCondition describes the state of a replica set at a certain point. - -| `fullyLabeledReplicas` -| `integer` -| The number of pods that have labels matching the labels of the pod template of the replicaset. - -| `observedGeneration` -| `integer` -| ObservedGeneration reflects the generation of the most recently observed ReplicaSet. - -| `readyReplicas` -| `integer` -| The number of ready replicas for this replica set. - -| `replicas` -| `integer` -| Replicas is the most recently oberved number of replicas. More info: https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/#what-is-a-replicationcontroller - -|=== -..status.conditions -Description:: - Represents the latest available observations of a replica set's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - ReplicaSetCondition describes the state of a replica set at a certain point. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| The last time the condition transitioned from one status to another. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of replica set condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/apps/v1/replicasets` -- `GET`: list or watch objects of kind ReplicaSet -* `/apis/apps/v1/namespaces/{namespace}/replicasets` -- `DELETE`: delete collection of ReplicaSet -- `GET`: list or watch objects of kind ReplicaSet -- `POST`: create a ReplicaSet -* `/apis/apps/v1/namespaces/{namespace}/replicasets/{name}` -- `DELETE`: delete a ReplicaSet -- `GET`: read the specified ReplicaSet -- `PATCH`: partially update the specified ReplicaSet -- `PUT`: replace the specified ReplicaSet -* `/apis/apps/v1/namespaces/{namespace}/replicasets/{name}/scale` -- `GET`: read scale of the specified ReplicaSet -- `PATCH`: partially update scale of the specified ReplicaSet -- `PUT`: replace scale of the specified ReplicaSet -* `/apis/apps/v1/namespaces/{namespace}/replicasets/{name}/status` -- `GET`: read status of the specified ReplicaSet -- `PATCH`: partially update status of the specified ReplicaSet -- `PUT`: replace status of the specified ReplicaSet - - -=== /apis/apps/v1/replicasets - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ReplicaSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#replicasetlist-apps-v1[`ReplicaSetList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/replicasets - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#replicasetlist-apps-v1[`ReplicaSetList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 202 - Accepted -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/replicasets/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ReplicaSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/replicasets/{name}/scale - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Scale -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read scale of the specified ReplicaSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update scale of the specified ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace scale of the specified ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 201 - Created -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/replicasets/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ReplicaSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ReplicaSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ReplicaSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/replicaset-apps-v1.adoc#replicaset-apps-v1[`ReplicaSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/replicationcontroller-core-v1.adoc b/rest_api/workloads_apis/replicationcontroller-core-v1.adoc deleted file mode 100644 index 18278555c504..000000000000 --- a/rest_api/workloads_apis/replicationcontroller-core-v1.adoc +++ /dev/null @@ -1,1007 +0,0 @@ -[id="replicationcontroller-core-v1"] -= ReplicationController [core/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - ReplicationController represents the configuration of a replication controller. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| If the Labels of a ReplicationController are empty, they are defaulted to be the same as the Pod(s) that the replication controller manages. Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| ReplicationControllerSpec is the specification of a replication controller. - -| `status` -| `object` -| ReplicationControllerStatus represents the current status of a replication controller. - -|=== -..spec -Description:: - ReplicationControllerSpec is the specification of a replication controller. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `minReadySeconds` -| `integer` -| Minimum number of seconds for which a newly created pod should be ready without any of its container crashing, for it to be considered available. Defaults to 0 (pod will be considered available as soon as it is ready) - -| `replicas` -| `integer` -| Replicas is the number of desired replicas. This is a pointer to distinguish between explicit zero and unspecified. Defaults to 1. More info: https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller#what-is-a-replicationcontroller - -| `selector` -| `object (string)` -| Selector is a label query over pods that should match the Replicas count. If Selector is empty, it is defaulted to the labels present on the Pod template. Label keys and values that must match in order to be controlled by this replication controller, if empty defaulted to labels on Pod template. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors - -| `template` -| `object` -| PodTemplateSpec describes the data a pod should have when created from a template - -|=== -..spec.template -Description:: - PodTemplateSpec describes the data a pod should have when created from a template - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata - -| `spec` -| `object` -| PodSpec is a description of a pod. - -|=== -..spec.template.spec -Description:: - PodSpec is a description of a pod. - -Type:: - `object` - -Required:: - - `containers` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `activeDeadlineSeconds` -| `integer` -| Optional duration in seconds the pod may be active on the node relative to StartTime before the system will actively try to mark it failed and kill associated containers. Value must be a positive integer. - -| `affinity` -| xref:../objects/index.adoc#affinity-core-v1[`Affinity core/v1`] -| If specified, the pod's scheduling constraints - -| `automountServiceAccountToken` -| `boolean` -| AutomountServiceAccountToken indicates whether a service account token should be automatically mounted. - -| `containers` -| xref:../objects/index.adoc#container-core-v1[`array (Container core/v1)`] -| List of containers belonging to the pod. Containers cannot currently be added or removed. There must be at least one container in a Pod. Cannot be updated. - -| `dnsConfig` -| xref:../objects/index.adoc#poddnsconfig-core-v1[`PodDNSConfig core/v1`] -| Specifies the DNS parameters of a pod. Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy. - -| `dnsPolicy` -| `string` -| Set DNS policy for the pod. Defaults to "ClusterFirst". Valid values are 'ClusterFirstWithHostNet', 'ClusterFirst', 'Default' or 'None'. DNS parameters given in DNSConfig will be merged with the policy selected with DNSPolicy. To have DNS options set along with hostNetwork, you have to specify DNS policy explicitly to 'ClusterFirstWithHostNet'. - -| `enableServiceLinks` -| `boolean` -| EnableServiceLinks indicates whether information about services should be injected into pod's environment variables, matching the syntax of Docker links. Optional: Defaults to true. - -| `ephemeralContainers` -| xref:../objects/index.adoc#ephemeralcontainer-core-v1[`array (EphemeralContainer core/v1)`] -| List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing pod to perform user-initiated actions such as debugging. This list cannot be specified when creating a pod, and it cannot be modified by updating the pod spec. In order to add an ephemeral container to an existing pod, use the pod's ephemeralcontainers subresource. This field is alpha-level and is only honored by servers that enable the EphemeralContainers feature. - -| `hostAliases` -| xref:../objects/index.adoc#hostalias-core-v1[`array (HostAlias core/v1)`] -| HostAliases is an optional list of hosts and IPs that will be injected into the pod's hosts file if specified. This is only valid for non-hostNetwork pods. - -| `hostIPC` -| `boolean` -| Use the host's ipc namespace. Optional: Default to false. - -| `hostNetwork` -| `boolean` -| Host networking requested for this pod. Use the host's network namespace. If this option is set, the ports that will be used must be specified. Default to false. - -| `hostPID` -| `boolean` -| Use the host's pid namespace. Optional: Default to false. - -| `hostname` -| `string` -| Specifies the hostname of the Pod If not specified, the pod's hostname will be set to a system-defined value. - -| `imagePullSecrets` -| xref:../objects/index.adoc#localobjectreference-core-v1[`array (LocalObjectReference core/v1)`] -| ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec. If specified, these secrets will be passed to individual puller implementations for them to use. For example, in the case of docker, only DockerConfig type secrets are honored. More info: https://kubernetes.io/docs/concepts/containers/images#specifying-imagepullsecrets-on-a-pod - -| `initContainers` -| xref:../objects/index.adoc#container-core-v1[`array (Container core/v1)`] -| List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy. The name for an init container or normal container must be unique among all containers. Init containers may not have Lifecycle actions, Readiness probes, Liveness probes, or Startup probes. The resourceRequirements of an init container are taken into account during scheduling by finding the highest request/limit for each resource type, and then using the max of of that value or the sum of the normal containers. Limits are applied to init containers in a similar fashion. Init containers cannot currently be added or removed. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ - -| `nodeName` -| `string` -| NodeName is a request to schedule this pod onto a specific node. If it is non-empty, the scheduler simply schedules this pod onto that node, assuming that it fits resource requirements. - -| `nodeSelector` -| `object (string)` -| NodeSelector is a selector which must be true for the pod to fit on a node. Selector which must match a node's labels for the pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/ - -| `overhead` -| xref:../objects/index.adoc#quantity-api-resource[`object (Quantity api/resource)`] -| Overhead represents the resource overhead associated with running a pod for a given RuntimeClass. This field will be autopopulated at admission time by the RuntimeClass admission controller. If the RuntimeClass admission controller is enabled, overhead must not be set in Pod create requests. The RuntimeClass admission controller will reject Pod create requests which have the overhead already set. If RuntimeClass is configured and selected in the PodSpec, Overhead will be set to the value defined in the corresponding RuntimeClass, otherwise it will remain unset and treated as zero. More info: https://git.k8s.io/enhancements/keps/sig-node/20190226-pod-overhead.md This field is alpha-level as of Kubernetes v1.16, and is only honored by servers that enable the PodOverhead feature. - -| `preemptionPolicy` -| `string` -| PreemptionPolicy is the Policy for preempting pods with lower priority. One of Never, PreemptLowerPriority. Defaults to PreemptLowerPriority if unset. This field is beta-level, gated by the NonPreemptingPriority feature-gate. - -| `priority` -| `integer` -| The priority value. Various system components use this field to find the priority of the pod. When Priority Admission Controller is enabled, it prevents users from setting this field. The admission controller populates this field from PriorityClassName. The higher the value, the higher the priority. - -| `priorityClassName` -| `string` -| If specified, indicates the pod's priority. "system-node-critical" and "system-cluster-critical" are two special keywords which indicate the highest priorities with the former being the highest priority. Any other name must be defined by creating a PriorityClass object with that name. If not specified, the pod priority will be default or zero if there is no default. - -| `readinessGates` -| xref:../objects/index.adoc#podreadinessgate-core-v1[`array (PodReadinessGate core/v1)`] -| If specified, all readiness gates will be evaluated for pod readiness. A pod is ready when all its containers are ready AND all conditions specified in the readiness gates have status equal to "True" More info: https://git.k8s.io/enhancements/keps/sig-network/0007-pod-ready%2B%2B.md - -| `restartPolicy` -| `string` -| Restart policy for all containers within the pod. One of Always, OnFailure, Never. Default to Always. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy - -| `runtimeClassName` -| `string` -| RuntimeClassName refers to a RuntimeClass object in the node.k8s.io group, which should be used to run this pod. If no RuntimeClass resource matches the named class, the pod will not be run. If unset or empty, the "legacy" RuntimeClass will be used, which is an implicit class with an empty definition that uses the default runtime handler. More info: https://git.k8s.io/enhancements/keps/sig-node/runtime-class.md This is a beta feature as of Kubernetes v1.14. - -| `schedulerName` -| `string` -| If specified, the pod will be dispatched by specified scheduler. If not specified, the pod will be dispatched by default scheduler. - -| `securityContext` -| xref:../objects/index.adoc#podsecuritycontext-core-v1[`PodSecurityContext core/v1`] -| SecurityContext holds pod-level security attributes and common container settings. Optional: Defaults to empty. See type description for default values of each field. - -| `serviceAccount` -| `string` -| DeprecatedServiceAccount is a depreciated alias for ServiceAccountName. Deprecated: Use serviceAccountName instead. - -| `serviceAccountName` -| `string` -| ServiceAccountName is the name of the ServiceAccount to use to run this pod. More info: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ - -| `setHostnameAsFQDN` -| `boolean` -| If true the pod's hostname will be configured as the pod's FQDN, rather than the leaf name (the default). In Linux containers, this means setting the FQDN in the hostname field of the kernel (the nodename field of struct utsname). In Windows containers, this means setting the registry value of hostname for the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters to FQDN. If a pod does not have FQDN, this has no effect. Default to false. - -| `shareProcessNamespace` -| `boolean` -| Share a single process namespace between all of the containers in a pod. When this is set containers will be able to view and signal processes from other containers in the same pod, and the first process in each container will not be assigned PID 1. HostPID and ShareProcessNamespace cannot both be set. Optional: Default to false. - -| `subdomain` -| `string` -| If specified, the fully qualified Pod hostname will be "<hostname>.<subdomain>.<pod namespace>.svc.<cluster domain>". If not specified, the pod will not have a domainname at all. - -| `terminationGracePeriodSeconds` -| `integer` -| Optional duration in seconds the pod needs to terminate gracefully. May be decreased in delete request. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period will be used instead. The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process. Defaults to 30 seconds. - -| `tolerations` -| xref:../objects/index.adoc#toleration-core-v1[`array (Toleration core/v1)`] -| If specified, the pod's tolerations. - -| `topologySpreadConstraints` -| xref:../objects/index.adoc#topologyspreadconstraint-core-v1[`array (TopologySpreadConstraint core/v1)`] -| TopologySpreadConstraints describes how a group of pods ought to spread across topology domains. Scheduler will schedule pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed. - -| `volumes` -| xref:../objects/index.adoc#volume-core-v1[`array (Volume core/v1)`] -| List of volumes that can be mounted by containers belonging to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes - -|=== -..status -Description:: - ReplicationControllerStatus represents the current status of a replication controller. - -Type:: - `object` - -Required:: - - `replicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `availableReplicas` -| `integer` -| The number of available replicas (ready for at least minReadySeconds) for this replication controller. - -| `conditions` -| xref:../objects/index.adoc#replicationcontrollercondition-core-v1[`array (ReplicationControllerCondition core/v1)`] -| Represents the latest available observations of a replication controller's current state. - -| `fullyLabeledReplicas` -| `integer` -| The number of pods that have labels matching the labels of the pod template of the replication controller. - -| `observedGeneration` -| `integer` -| ObservedGeneration reflects the generation of the most recently observed replication controller. - -| `readyReplicas` -| `integer` -| The number of ready replicas for this replication controller. - -| `replicas` -| `integer` -| Replicas is the most recently oberved number of replicas. More info: https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller#what-is-a-replicationcontroller - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/api/v1/replicationcontrollers` -- `GET`: list or watch objects of kind ReplicationController -* `/api/v1/namespaces/{namespace}/replicationcontrollers` -- `DELETE`: delete collection of ReplicationController -- `GET`: list or watch objects of kind ReplicationController -- `POST`: create a ReplicationController -* `/api/v1/namespaces/{namespace}/replicationcontrollers/{name}` -- `DELETE`: delete a ReplicationController -- `GET`: read the specified ReplicationController -- `PATCH`: partially update the specified ReplicationController -- `PUT`: replace the specified ReplicationController -* `/api/v1/namespaces/{namespace}/replicationcontrollers/{name}/scale` -- `GET`: read scale of the specified ReplicationController -- `PATCH`: partially update scale of the specified ReplicationController -- `PUT`: replace scale of the specified ReplicationController -* `/api/v1/namespaces/{namespace}/replicationcontrollers/{name}/status` -- `GET`: read status of the specified ReplicationController -- `PATCH`: partially update status of the specified ReplicationController -- `PUT`: replace status of the specified ReplicationController - - -=== /api/v1/replicationcontrollers - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ReplicationController - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#replicationcontrollerlist-core-v1[`ReplicationControllerList core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/replicationcontrollers - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#replicationcontrollerlist-core-v1[`ReplicationControllerList core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 201 - Created -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 202 - Accepted -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/replicationcontrollers/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ReplicationController -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 201 - Created -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/replicationcontrollers/{name}/scale - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Scale -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read scale of the specified ReplicationController - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update scale of the specified ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace scale of the specified ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 201 - Created -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /api/v1/namespaces/{namespace}/replicationcontrollers/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the ReplicationController -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified ReplicationController - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified ReplicationController - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 201 - Created -| xref:../workloads_apis/replicationcontroller-core-v1.adoc#replicationcontroller-core-v1[`ReplicationController core/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/statefulset-apps-v1.adoc b/rest_api/workloads_apis/statefulset-apps-v1.adoc deleted file mode 100644 index 0ab755ad8b6f..000000000000 --- a/rest_api/workloads_apis/statefulset-apps-v1.adoc +++ /dev/null @@ -1,956 +0,0 @@ -[id="statefulset-apps-v1"] -= StatefulSet [apps/v1] -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - - -Description:: - StatefulSet represents a set of pods with consistent identities. Identities are defined as: - - Network: A single stable DNS and hostname. - - Storage: As many VolumeClaims as requested. -The StatefulSet guarantees that a given network identity will always map to the same storage identity. - -Type:: - `object` - - - -== Specification - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `apiVersion` -| `string` -| APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -| `kind` -| `string` -| Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -| `metadata` -| xref:../objects/index.adoc#objectmeta-meta-v1[`ObjectMeta meta/v1`] -| - -| `spec` -| `object` -| A StatefulSetSpec is the specification of a StatefulSet. - -| `status` -| `object` -| StatefulSetStatus represents the current state of a StatefulSet. - -|=== -..spec -Description:: - A StatefulSetSpec is the specification of a StatefulSet. - -Type:: - `object` - -Required:: - - `selector` - - `template` - - `serviceName` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `podManagementPolicy` -| `string` -| podManagementPolicy controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. The default policy is `OrderedReady`, where pods are created in increasing order (pod-0, then pod-1, etc) and the controller will wait until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order. The alternative policy is `Parallel` which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once. - -| `replicas` -| `integer` -| replicas is the desired number of replicas of the given Template. These are replicas in the sense that they are instantiations of the same Template, but individual replicas also have a consistent identity. If unspecified, defaults to 1. - -| `revisionHistoryLimit` -| `integer` -| revisionHistoryLimit is the maximum number of revisions that will be maintained in the StatefulSet's revision history. The revision history consists of all revisions not represented by a currently applied StatefulSetSpec version. The default value is 10. - -| `selector` -| xref:../objects/index.adoc#labelselector-meta-v1[`LabelSelector meta/v1`] -| selector is a label query over pods that should match the replica count. It must match the pod template's labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors - -| `serviceName` -| `string` -| serviceName is the name of the service that governs this StatefulSet. This service must exist before the StatefulSet, and is responsible for the network identity of the set. Pods get DNS/hostnames that follow the pattern: pod-specific-string.serviceName.default.svc.cluster.local where "pod-specific-string" is managed by the StatefulSet controller. - -| `template` -| xref:../objects/index.adoc#podtemplatespec-core-v1[`PodTemplateSpec core/v1`] -| template is the object that describes the pod that will be created if insufficient replicas are detected. Each pod stamped out by the StatefulSet will fulfill this Template, but have a unique identity from the rest of the StatefulSet. - -| `updateStrategy` -| `object` -| StatefulSetUpdateStrategy indicates the strategy that the StatefulSet controller will use to perform updates. It includes any additional parameters necessary to perform the update for the indicated strategy. - -| `volumeClaimTemplates` -| xref:../storage_apis/persistentvolumeclaim-core-v1.adoc#persistentvolumeclaim-core-v1[`array (PersistentVolumeClaim core/v1)`] -| volumeClaimTemplates is a list of claims that pods are allowed to reference. The StatefulSet controller is responsible for mapping network identities to claims in a way that maintains the identity of a pod. Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name. - -|=== -..spec.updateStrategy -Description:: - StatefulSetUpdateStrategy indicates the strategy that the StatefulSet controller will use to perform updates. It includes any additional parameters necessary to perform the update for the indicated strategy. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `rollingUpdate` -| `object` -| RollingUpdateStatefulSetStrategy is used to communicate parameter for RollingUpdateStatefulSetStrategyType. - -| `type` -| `string` -| Type indicates the type of the StatefulSetUpdateStrategy. Default is RollingUpdate. - -|=== -..spec.updateStrategy.rollingUpdate -Description:: - RollingUpdateStatefulSetStrategy is used to communicate parameter for RollingUpdateStatefulSetStrategyType. - -Type:: - `object` - - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `partition` -| `integer` -| Partition indicates the ordinal at which the StatefulSet should be partitioned. Default value is 0. - -|=== -..status -Description:: - StatefulSetStatus represents the current state of a StatefulSet. - -Type:: - `object` - -Required:: - - `replicas` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `collisionCount` -| `integer` -| collisionCount is the count of hash collisions for the StatefulSet. The StatefulSet controller uses this field as a collision avoidance mechanism when it needs to create the name for the newest ControllerRevision. - -| `conditions` -| `array` -| Represents the latest available observations of a statefulset's current state. - -| `conditions[]` -| `object` -| StatefulSetCondition describes the state of a statefulset at a certain point. - -| `currentReplicas` -| `integer` -| currentReplicas is the number of Pods created by the StatefulSet controller from the StatefulSet version indicated by currentRevision. - -| `currentRevision` -| `string` -| currentRevision, if not empty, indicates the version of the StatefulSet used to generate Pods in the sequence [0,currentReplicas). - -| `observedGeneration` -| `integer` -| observedGeneration is the most recent generation observed for this StatefulSet. It corresponds to the StatefulSet's generation, which is updated on mutation by the API Server. - -| `readyReplicas` -| `integer` -| readyReplicas is the number of Pods created by the StatefulSet controller that have a Ready Condition. - -| `replicas` -| `integer` -| replicas is the number of Pods created by the StatefulSet controller. - -| `updateRevision` -| `string` -| updateRevision, if not empty, indicates the version of the StatefulSet used to generate Pods in the sequence [replicas-updatedReplicas,replicas) - -| `updatedReplicas` -| `integer` -| updatedReplicas is the number of Pods created by the StatefulSet controller from the StatefulSet version indicated by updateRevision. - -|=== -..status.conditions -Description:: - Represents the latest available observations of a statefulset's current state. - -Type:: - `array` - - - - -..status.conditions[] -Description:: - StatefulSetCondition describes the state of a statefulset at a certain point. - -Type:: - `object` - -Required:: - - `type` - - `status` - - - -[cols="1,1,1",options="header"] -|=== -| Property | Type | Description - -| `lastTransitionTime` -| xref:../objects/index.adoc#time-meta-v1[`Time meta/v1`] -| Last time the condition transitioned from one status to another. - -| `message` -| `string` -| A human readable message indicating details about the transition. - -| `reason` -| `string` -| The reason for the condition's last transition. - -| `status` -| `string` -| Status of the condition, one of True, False, Unknown. - -| `type` -| `string` -| Type of statefulset condition. - -|=== - -== API endpoints - -The following API endpoints are available: - -* `/apis/apps/v1/statefulsets` -- `GET`: list or watch objects of kind StatefulSet -* `/apis/apps/v1/namespaces/{namespace}/statefulsets` -- `DELETE`: delete collection of StatefulSet -- `GET`: list or watch objects of kind StatefulSet -- `POST`: create a StatefulSet -* `/apis/apps/v1/namespaces/{namespace}/statefulsets/{name}` -- `DELETE`: delete a StatefulSet -- `GET`: read the specified StatefulSet -- `PATCH`: partially update the specified StatefulSet -- `PUT`: replace the specified StatefulSet -* `/apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/scale` -- `GET`: read scale of the specified StatefulSet -- `PATCH`: partially update scale of the specified StatefulSet -- `PUT`: replace scale of the specified StatefulSet -* `/apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/status` -- `GET`: read status of the specified StatefulSet -- `PATCH`: partially update status of the specified StatefulSet -- `PUT`: replace status of the specified StatefulSet - - -=== /apis/apps/v1/statefulsets - - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind StatefulSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#statefulsetlist-apps-v1[`StatefulSetList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/statefulsets - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete collection of StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - list or watch objects of kind StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `allowWatchBookmarks` -| `boolean` -| allowWatchBookmarks requests watch events with type &quot;BOOKMARK&quot;. Servers that do not implement bookmarks may ignore this flag and bookmarks are sent at the server&#x27;s discretion. Clients should not assume bookmarks are returned at any specific interval, nor may they assume the server will send any BOOKMARK event during a session. If this is not a watch, this field is ignored. If the feature gate WatchBookmarks is not enabled in apiserver, this field is ignored. -| `continue` -| `string` -| The continue option should be set when retrieving more results from the server. Since this value is server defined, clients may only use the continue value from a previous query result with identical query parameters (except for the value of continue) and the server may reject a continue value it does not recognize. If the specified continue value is no longer valid whether due to expiration (generally five to fifteen minutes) or a configuration change on the server, the server will respond with a 410 ResourceExpired error together with a continue token. If the client needs a consistent list, it must restart their list without the continue field. Otherwise, the client may send another list request with the token received with the 410 error, the server will respond with a list starting from the next key, but from the latest snapshot, which is inconsistent from the previous list results - objects that are created, modified, or deleted after the first list request will be included in the response, as long as their keys are after the &quot;next key&quot;. - -This field is not supported when watch is true. Clients may start a watch from the last resourceVersion value returned by the server and not miss any modifications. -| `fieldSelector` -| `string` -| A selector to restrict the list of returned objects by their fields. Defaults to everything. -| `labelSelector` -| `string` -| A selector to restrict the list of returned objects by their labels. Defaults to everything. -| `limit` -| `integer` -| limit is a maximum number of responses to return for a list call. If more items exist, the server will set the &#x60;continue&#x60; field on the list metadata to a value that can be used with the same initial query to retrieve the next set of results. Setting a limit may return fewer than the requested amount of items (up to zero items) in the event all requested objects are filtered out and clients should only use the presence of the continue field to determine whether more results are available. Servers may choose not to support the limit argument and will return all of the available results. If limit is specified and the continue field is empty, clients may assume that no more results are available. This field is not supported if watch is true. - -The server guarantees that the objects returned when using continue will be identical to issuing a single list call without a limit - that is, no objects created, modified, or deleted after the first request is issued will be included in any subsequent continued requests. This is sometimes referred to as a consistent snapshot, and ensures that a client that is using limit to receive smaller chunks of a very large result can ensure they see all possible objects. If objects are updated during a chunked list the version of the object that was present at the time the first list result was calculated is returned. -| `resourceVersion` -| `string` -| resourceVersion sets a constraint on what resource versions a request may be served from. See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `resourceVersionMatch` -| `string` -| resourceVersionMatch determines how resourceVersion is applied to list calls. It is highly recommended that resourceVersionMatch be set for list calls where resourceVersion is set See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions for details. - -Defaults to unset -| `timeoutSeconds` -| `integer` -| Timeout for the list/watch call. This limits the duration of the call, regardless of any activity or inactivity. -| `watch` -| `boolean` -| Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#statefulsetlist-apps-v1[`StatefulSetList apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `POST` - -Description:: - create a StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 202 - Accepted -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/statefulsets/{name} - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the StatefulSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `DELETE` - -Description:: - delete a StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `gracePeriodSeconds` -| `integer` -| The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used. Defaults to a per object value if not specified. zero means delete immediately. -| `orphanDependents` -| `boolean` -| Deprecated: please use the PropagationPolicy, this field will be deprecated in 1.7. Should the dependent objects be orphaned. If true/false, the &quot;orphan&quot; finalizer will be added to/removed from the object&#x27;s finalizers list. Either this field or PropagationPolicy may be set, but not both. -| `propagationPolicy` -| `string` -| Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are: &#x27;Orphan&#x27; - orphan the dependents; &#x27;Background&#x27; - allow the garbage collector to delete the dependents in the background; &#x27;Foreground&#x27; - a cascading policy that deletes all dependents in the foreground. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 202 - Accepted -| xref:../objects/index.adoc#status-meta-v1[`Status meta/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `GET` - -Description:: - read the specified StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `exact` -| `boolean` -| Should the export be exact. Exact export maintains cluster-specific fields like &#x27;Namespace&#x27;. Deprecated. Planned for removal in 1.18. -| `export` -| `boolean` -| Should this value be exported. Export strips fields that a user can not specify. Deprecated. Planned for removal in 1.18. -|=== - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update the specified StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace the specified StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/scale - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the Scale -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read scale of the specified StatefulSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update scale of the specified StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace scale of the specified StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 201 - Created -| xref:../objects/index.adoc#scale-autoscaling-v1[`Scale autoscaling/v1`] -| 401 - Unauthorized -| Empty -|=== - - -=== /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/status - -.Global path parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `name` -| `string` -| name of the StatefulSet -| `namespace` -| `string` -| object name and auth scope, such as for teams and projects -|=== - -.Global guery parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `pretty` -| `string` -| If &#x27;true&#x27;, then the output is pretty printed. -|=== - -HTTP method:: - `GET` - -Description:: - read status of the specified StatefulSet - - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PATCH` - -Description:: - partially update status of the specified StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. This field is required for apply requests (application/apply-patch) but optional for non-apply patch types (JsonPatch, MergePatch, StrategicMergePatch). -| `force` -| `boolean` -| Force is going to &quot;force&quot; Apply requests. It means user will re-acquire conflicting fields owned by other people. Force flag must be unset for non-apply patch requests. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - -HTTP method:: - `PUT` - -Description:: - replace status of the specified StatefulSet - - -.Query parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `dryRun` -| `string` -| When present, indicates that modifications should not be persisted. An invalid or unrecognized dryRun directive will result in an error response and no further processing of the request. Valid values are: - All: all dry run stages will be processed -| `fieldManager` -| `string` -| fieldManager is a name associated with the actor or entity that is making these changes. The value must be less than or 128 characters long, and only contain printable characters, as defined by https://golang.org/pkg/unicode/#IsPrint. -|=== - -.Body parameters -[cols="1,1,2",options="header"] -|=== -| Parameter | Type | Description -| `body` -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| -|=== - -.HTTP responses -[cols="1,1",options="header"] -|=== -| HTTP code | Reponse body -| 200 - OK -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 201 - Created -| xref:../workloads_apis/statefulset-apps-v1.adoc#statefulset-apps-v1[`StatefulSet apps/v1`] -| 401 - Unauthorized -| Empty -|=== - - diff --git a/rest_api/workloads_apis/workloads-apis-index.adoc b/rest_api/workloads_apis/workloads-apis-index.adoc deleted file mode 100644 index ab03b5423834..000000000000 --- a/rest_api/workloads_apis/workloads-apis-index.adoc +++ /dev/null @@ -1,111 +0,0 @@ -[id="workloads-apis"] -= Workloads APIs -ifdef::product-title[] -include::modules/common-attributes.adoc[] -endif::[] - -toc::[] - -== BuildConfig [build.openshift.io/v1] - -Description:: - Build configurations define a build process for new container images. There are three types of builds possible - a container image build using a Dockerfile, a Source-to-Image build that uses a specially prepared base image that accepts source code that it can make runnable, and a custom build that can run // arbitrary container images as a base and accept the build parameters. Builds run on the cluster and on completion are pushed to the container image registry specified in the "output" section. A build can be triggered via a webhook, when the base image changes, or when a user manually requests a new build be // created. - -Each build created by a build configuration is numbered and refers back to its parent configuration. Multiple builds can be triggered at once. Builds that do not have "output" set can be used to test code or run a verification build. - -Type:: - `object` - -== Build [build.openshift.io/v1] - -Description:: - Build encapsulates the inputs needed to produce a new deployable image, as well as the status of the execution and a reference to the Pod which executed the build. - -Type:: - `object` - -== CronJob [batch/v1beta1] - -Description:: - CronJob represents the configuration of a single cron job. - -Type:: - `object` - -== DaemonSet [apps/v1] - -Description:: - DaemonSet represents the configuration of a daemon set. - -Type:: - `object` - -== Deployment [apps/v1] - -Description:: - Deployment enables declarative updates for Pods and ReplicaSets. - -Type:: - `object` - -== DeploymentConfig [apps.openshift.io/v1] - -Description:: - Deployment Configs define the template for a pod and manages deploying new images or configuration changes. A single deployment configuration is usually analogous to a single micro-service. Can support many different deployment patterns, including full restart, customizable rolling updates, and fully custom behaviors, as well as pre- and post- deployment hooks. Each individual deployment is represented as a replication controller. - -A deployment is "triggered" when its configuration is changed or a tag in an Image Stream is changed. Triggers can be disabled to allow manual control over a deployment. The "strategy" determines how the deployment is carried out and may be changed at any time. The `latestVersion` field is updated when a new deployment is triggered by any means. - -Type:: - `object` - -== Job [batch/v1] - -Description:: - Job represents the configuration of a single job. - -Type:: - `object` - -== Pod [core/v1] - -Description:: - Pod is a collection of containers that can run on a host. This resource is created by clients and scheduled onto hosts. - -Type:: - `object` - -== ReplicationController [core/v1] - -Description:: - ReplicationController represents the configuration of a replication controller. - -Type:: - `object` - -== PersistentVolume [core/v1] - -Description:: - PersistentVolume (PV) is a storage resource provisioned by an administrator. It is analogous to a node. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes - -Type:: - `object` - -== ReplicaSet [apps/v1] - -Description:: - ReplicaSet ensures that a specified number of pod replicas are running at any given time. - -Type:: - `object` - -== StatefulSet [apps/v1] - -Description:: - StatefulSet represents a set of pods with consistent identities. Identities are defined as: - - Network: A single stable DNS and hostname. - - Storage: As many VolumeClaims as requested. -The StatefulSet guarantees that a given network identity will always map to the same storage identity. - -Type:: - `object` - diff --git a/router/PLACEHOLDER b/router/PLACEHOLDER deleted file mode 100644 index 4020393e57eb..000000000000 --- a/router/PLACEHOLDER +++ /dev/null @@ -1,2 +0,0 @@ -Please delete this file once you have assemblies here. - diff --git a/router/images b/router/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/router/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/router/modules b/router/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/router/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/sandboxed_containers/deploying-sandboxed-container-workloads.adoc b/sandboxed_containers/deploying-sandboxed-container-workloads.adoc deleted file mode 100644 index 3443ccaa433f..000000000000 --- a/sandboxed_containers/deploying-sandboxed-container-workloads.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="deploying-sandboxed-containers-workloads"] -= Deploying OpenShift sandboxed containers workloads -include::modules/common-attributes.adoc[] -:context: deploying-sandboxed-containers - -toc::[] - -include::modules/sandboxed-containers-installing-operator.adoc[leveloffset=+1] -include::modules/sandboxed-containers-preparing-openshift-cluster.adoc[leveloffset=+2] -include::modules/sandboxed-containers-installing-operator-web-console.adoc[leveloffset=+2] -include::modules/sandboxed-containers-installing-operator-cli.adoc[leveloffset=+2] -include::modules/sandboxed-containers-triggering-installation-kata-runtime.adoc[leveloffset=+2] -include::modules/sandboxed-containers-selecting-nodes.adoc[leveloffset=+2] -include::modules/sandboxed-containers-scheduling-workloads.adoc[leveloffset=+1] -include::modules/sandboxed-containers-viewing-workloads-from-web-console.adoc[leveloffset=+1] -include::modules/sandboxed-containers-viewing-workloads-from-cli.adoc[leveloffset=+1] diff --git a/sandboxed_containers/disabling-sandboxed-container-workloads.adoc b/sandboxed_containers/disabling-sandboxed-container-workloads.adoc deleted file mode 100644 index cc531e7a6353..000000000000 --- a/sandboxed_containers/disabling-sandboxed-container-workloads.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="disabling-sandboxed-containers-workloads"] -= Disabling OpenShift sandboxed containers workloads -include::modules/common-attributes.adoc[] -:context: disabling-sandboxed-containers - -toc::[] - -include::modules/sandboxed-containers-uninstalling-kata-runtime.adoc[leveloffset=+1] diff --git a/sandboxed_containers/modules b/sandboxed_containers/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/sandboxed_containers/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/sandboxed_containers/understanding-sandboxed-containers.adoc b/sandboxed_containers/understanding-sandboxed-containers.adoc deleted file mode 100644 index 1d10eb4056f4..000000000000 --- a/sandboxed_containers/understanding-sandboxed-containers.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="understanding-sandboxed-containers"] -= Understanding OpenShift sandboxed containers -include::modules/common-attributes.adoc[] - -:context: understanding-sandboxed-containers - -toc::[] - -[role="_abstract"] - -{sandboxed-containers-first} support for {product-title} provides users with built-in support for running Kata Containers as an additional optional runtime. This is particularly useful for users who are wanting to perform the following tasks: - -- Run privileged or untrusted workloads. -- Ensure kernel isolation for each workload. -- Share the same workload across tenants. -- Ensure proper isolation and sandboxing for testing software. -- Ensure default resource containment through VM boundaries. - -Furthermore, {sandboxed-containers-first} provide an additional option for users to choose from the type of workload they want to run to cover a wide variety of use cases. - -Sandboxed containers are only supported on bare metal. - -{op-system-first} is the only supported operating system for {product-title} 4.8. - -include::modules/sandboxed-containers-about-sandboxing.adoc[leveloffset=+1] -include::modules/sandboxed-containers-building-blocks.adoc[leveloffset=+1] -include::modules/sandboxed-containers-os-extensions.adoc[leveloffset=+1] -include::modules/sandboxed-containers-limitations.adoc[leveloffset=+1] diff --git a/scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc b/scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc deleted file mode 100644 index ae54a5b024d8..000000000000 --- a/scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc +++ /dev/null @@ -1,54 +0,0 @@ -[id="cnf-performance-addon-operator-for-low-latency-nodes"] -= Performance Addon Operator for low latency nodes -include::modules/common-attributes.adoc[] -:context: cnf-master - -toc::[] - -include::modules/cnf-understanding-low-latency.adoc[leveloffset=+1] - -include::modules/cnf-about_hyperthreading_for_low_latency_and_real_time_applications.adoc[leveloffset=+2] - -.Additional resources - -* xref:../scalability_and_performance/cnf-performance-addon-operator-for-low-latency-nodes.adoc#configuring_hyperthreading_for_a_cluster_{context}[Configuring hyperthreading for a cluster] - -include::modules/cnf-installing-the-performance-addon-operator.adoc[leveloffset=+1] - -include::modules/cnf-upgrading-performance-addon-operator.adoc[leveloffset=+1] - -include::modules/cnf-provisioning-real-time-and-low-latency-workloads.adoc[leveloffset=+1] - -include::modules/cnf-managing-device-interrupt-processing-for-guaranteed-pod-isolated-cpus.adoc[leveloffset=+2] - -include::modules/cnf-use-device-interrupt-processing-for-isolated-cpus.adoc[leveloffset=+2] - -include::modules/cnf-configure_for_irq_dynamic_load_balancing.adoc[leveloffset=+2] - -include::modules/configuring_hyperthreading_for_a_cluster.adoc[leveloffset=+2] - -include::modules/cnf-configuring-huge-pages.adoc[leveloffset=+1] - -include::modules/cnf-allocating-multiple-huge-page-sizes.adoc[leveloffset=+1] - -include::modules/cnf-tuning-nodes-for-low-latency-via-performanceprofile.adoc[leveloffset=+1] - -include::modules/cnf-performing-end-to-end-tests-for-platform-verification.adoc[leveloffset=+1] - -include::modules/cnf-debugging-low-latency-cnf-tuning-status.adoc[leveloffset=+1] - -include::modules/cnf-collecting-low-latency-tuning-debugging-data-for-red-hat-support.adoc[leveloffset=+1] - -.Additional resources - -* For more information about MachineConfig and KubeletConfig, -see xref:../nodes/nodes/nodes-nodes-managing.adoc#nodes-nodes-managing[Managing nodes]. - -* For more information about the Node Tuning Operator, -see xref:../scalability_and_performance/using-node-tuning-operator.adoc#using-node-tuning-operator[Using the Node Tuning Operator]. - -* For more information about the PerformanceProfile, -see xref:../scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc#configuring-huge-pages_huge-pages[Configuring huge pages]. - -* For more information about consuming huge pages from your containers, -see xref:../scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc#how-huge-pages-are-consumed-by-apps_huge-pages[How huge pages are consumed by apps]. diff --git a/scalability_and_performance/cnf-provisioning-and-deploying-a-distributed-unit.adoc b/scalability_and_performance/cnf-provisioning-and-deploying-a-distributed-unit.adoc deleted file mode 100644 index e6f15f672650..000000000000 --- a/scalability_and_performance/cnf-provisioning-and-deploying-a-distributed-unit.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="cnf-provisioning-and-deploying-a-distributed-unit"] -= Provisioning and deploying a distributed unit (DU) -include::modules/common-attributes.adoc[] -:context: deploying-du - -[NOTE] -==== -The features described in this document are for Developer Preview purposes and are not supported by Red Hat at this time. -==== - -toc::[] - -include::modules/cnf-provisioning-deploying-a-distributed-unit-manually.adoc[leveloffset=+1] - -include::modules/cnf-installing-the-operators.adoc[leveloffset=+1] - -include::modules/cnf-deploying-the-du-infrastructure-profile.adoc[leveloffset=+1] - -include::modules/cnf-modifying-and-applying-the-default-profile.adoc[leveloffset=+1] diff --git a/scalability_and_performance/images b/scalability_and_performance/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/scalability_and_performance/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/scalability_and_performance/modules b/scalability_and_performance/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/scalability_and_performance/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/scalability_and_performance/optimizing-networking.adoc b/scalability_and_performance/optimizing-networking.adoc deleted file mode 100644 index 60e460e196e2..000000000000 --- a/scalability_and_performance/optimizing-networking.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="optimizing-networking"] -= Optimizing networking -include::modules/common-attributes.adoc[] -:context: optimizing-networking - -toc::[] - -The xref:../networking/openshift_sdn/about-openshift-sdn.adoc#about-openshift-sdn[OpenShift SDN] uses OpenvSwitch, virtual extensible LAN (VXLAN) tunnels, OpenFlow rules, and iptables. This network can be tuned by using jumbo frames, network interface cards (NIC) offloads, multi-queue, and ethtool settings. - -xref:../networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc#about-ovn-kubernetes[OVN-Kubernetes] uses Geneve (Generic Network Virtualization Encapsulation) instead of VXLAN as the tunnel protocol. - -VXLAN provides benefits over VLANs, such as an increase in networks from 4096 to over 16 million, and layer 2 connectivity across physical networks. This allows for all pods behind a service to communicate with each other, even if they are running on different systems. - -VXLAN encapsulates all tunneled traffic in user datagram protocol (UDP) packets. However, this leads to increased CPU utilization. Both these outer- and -inner-packets are subject to normal checksumming rules to guarantee data is not corrupted during transit. Depending on CPU performance, this additional -processing overhead can cause a reduction in throughput and increased latency when compared to traditional, non-overlay networks. - -Cloud, VM, and bare metal CPU performance can be capable of handling much more than one Gbps network throughput. When using higher bandwidth links such as 10 or 40 Gbps, reduced performance can occur. This is a known issue in VXLAN-based environments and is not specific to containers or {product-title}. Any network that relies on VXLAN tunnels will perform similarly because of the VXLAN implementation. - -If you are looking to push beyond one Gbps, you can: - -* Evaluate network plug-ins that implement different routing techniques, such as border gateway protocol (BGP). -* Use VXLAN-offload capable network adapters. VXLAN-offload moves the packet checksum calculation and associated CPU overhead off of the system CPU and onto dedicated hardware on the network adapter. This frees up CPU cycles for use by pods and applications, and allows users to utilize the full bandwidth of their network infrastructure. - -VXLAN-offload does not reduce latency. However, CPU utilization is reduced even in latency tests. - -include::modules/optimizing-mtu-networking.adoc[leveloffset=+1] - -include::modules/recommended-install-practices.adoc[leveloffset=+1] - -include::modules/ipsec-impact-networking.adoc[leveloffset=+1] - -.Additional resources - -* xref:../installing/installing_aws/installing-aws-network-customizations.adoc#modifying-nwoperator-config-startup_installing-aws-network-customizations[Modifying advanced network configuration parameters] -* xref:../networking/cluster-network-operator.adoc#nw-operator-configuration-parameters-for-ovn-sdn_cluster-network-operator[Configuration parameters for the OVN-Kubernetes default CNI network provider] -* xref:../networking/cluster-network-operator.adoc#nw-operator-configuration-parameters-for-openshift-sdn_cluster-network-operator[Configuration parameters for the OpenShift SDN default CNI network provider] diff --git a/scalability_and_performance/optimizing-storage.adoc b/scalability_and_performance/optimizing-storage.adoc deleted file mode 100644 index e4a67f251a10..000000000000 --- a/scalability_and_performance/optimizing-storage.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="optimizing-storage"] -= Optimizing storage -include::modules/common-attributes.adoc[] -:gluster: GlusterFS -:gluster-native: Containerized GlusterFS -:gluster-external: External GlusterFS -:gluster-install-link: https://docs.gluster.org/en/latest/Install-Guide/Overview/ -:gluster-admin-link: https://docs.gluster.org/en/latest/Administrator%20Guide/overview/ -:gluster-role-link: https://github.com/openshift/openshift-ansible/tree/master/roles/openshift_storage_glusterfs -ifdef::openshift-enterprise,openshift-webscale[] -:gluster: Red Hat Gluster Storage -:gluster-native: converged mode -:gluster-external: independent mode -:gluster-install-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/installation_guide/ -:gluster-admin-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/administration_guide/ -:cns-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/container-native_storage_for_openshift_container_platform/ -endif::[] -:context: persistent-storage - -toc::[] - -Optimizing storage helps to minimize storage use across all resources. By -optimizing storage, administrators help ensure that existing storage resources -are working in an efficient manner. - -include::modules/available-persistent-storage-options.adoc[leveloffset=+1] - -include::modules/recommended-configurable-storage-technology.adoc[leveloffset=+1] - -include::modules/data-storage-management.adoc[leveloffset=+1] diff --git a/scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc b/scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc deleted file mode 100644 index 6ff96488f66c..000000000000 --- a/scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="planning-your-environment-according-to-object-maximums"] -= Planning your environment according to object maximums -include::modules/common-attributes.adoc[] -:context: object-limits - -toc::[] - -Consider the following tested object maximums when you plan your {product-title} cluster. - -These guidelines are based on the largest possible cluster. For smaller -clusters, the maximums are lower. There are many factors that -influence the stated thresholds, including the etcd version or storage data -format. - -In most cases, exceeding these numbers results in lower overall performance. It -does not necessarily mean that the cluster will fail. - -include::modules/openshift-cluster-maximums-major-releases.adoc[leveloffset=+1] - -include::modules/openshift-cluster-maximums.adoc[leveloffset=+1] - -include::modules/openshift-cluster-maximums-environment.adoc[leveloffset=+1] - -include::modules/how-to-plan-your-environment-according-to-cluster-maximums.adoc[leveloffset=+1] - -include::modules/how-to-plan-your-environment-according-to-application-requirements.adoc[leveloffset=+1] diff --git a/scalability_and_performance/recommended-cluster-scaling-practices.adoc b/scalability_and_performance/recommended-cluster-scaling-practices.adoc deleted file mode 100644 index 1b65e2f8011b..000000000000 --- a/scalability_and_performance/recommended-cluster-scaling-practices.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="recommended-cluster-scaling-practices"] -= Recommended cluster scaling practices -include::modules/common-attributes.adoc[] -:context: cluster-scaling - -toc::[] - - -[IMPORTANT] -==== -The guidance in this section is only relevant for installations with cloud provider integration. -==== - -Apply the following best practices to scale the number of worker machines in your {product-title} cluster. You scale the worker machines by increasing or decreasing the number of replicas that are defined in the worker machine set. - -include::modules/recommended-scale-practices.adoc[leveloffset=+1] - -include::modules/machineset-modifying.adoc[leveloffset=+1] - -include::modules/machine-health-checks-about.adoc[leveloffset=+1] - -include::modules/machine-health-checks-resource.adoc[leveloffset=+1] - -include::modules/machine-health-checks-creating.adoc[leveloffset=+1] diff --git a/scalability_and_performance/recommended-host-practices.adoc b/scalability_and_performance/recommended-host-practices.adoc deleted file mode 100644 index 79ece2bc949f..000000000000 --- a/scalability_and_performance/recommended-host-practices.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="recommended-host-practices"] -= Recommended host practices -include::modules/common-attributes.adoc[] -:context: - -toc::[] - -This topic provides recommended host practices for {product-title}. - -include::modules/recommended-node-host-practices.adoc[leveloffset=+1] - -include::modules/create-a-kubeletconfig-crd-to-edit-kubelet-parameters.adoc[leveloffset=+1] - -include::modules/modify-unavailable-workers.adoc[leveloffset=+1] - -include::modules/master-node-sizing.adoc[leveloffset=+1] - -include::modules/recommended-etcd-practices.adoc[leveloffset=+1] - -include::modules/etcd-defrag.adoc[leveloffset=+1] - -include::modules/infrastructure-components.adoc[leveloffset=+1] - -include::modules/infrastructure-moving-monitoring.adoc[leveloffset=+1] - -include::modules/infrastructure-moving-registry.adoc[leveloffset=+1] - -include::modules/infrastructure-moving-router.adoc[leveloffset=+1] - -include::modules/infrastructure-node-sizing.adoc[leveloffset=+1] - -== Additional resources - -* xref:../scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc#planning-your-environment-according-to-object-maximums[{product-title} -cluster maximums] diff --git a/scalability_and_performance/recommended-install-practices.adoc b/scalability_and_performance/recommended-install-practices.adoc deleted file mode 100644 index f45579117756..000000000000 --- a/scalability_and_performance/recommended-install-practices.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="recommended-cluster-install-practices"] -= Recommended practices for installing large clusters -include::modules/common-attributes.adoc[] -:context: cluster-install - -toc::[] - -Apply the following practices when installing large clusters or scaling clusters -to larger node counts. - -include::modules/recommended-install-practices.adoc[leveloffset=+1] diff --git a/scalability_and_performance/routing-optimization.adoc b/scalability_and_performance/routing-optimization.adoc deleted file mode 100644 index 270f79c12a3f..000000000000 --- a/scalability_and_performance/routing-optimization.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="routing-optimization"] -= Optimizing routing -include::modules/common-attributes.adoc[] -:context: routing-optimization - -toc::[] - -The {product-title} HAProxy router scales to optimize performance. - -include::modules/baseline-router-performance.adoc[leveloffset=+1] - -For more information on Ingress sharding, see xref:../networking/ingress-operator.adoc#nw-ingress-sharding-route-labels_configuring-ingress[Configuring Ingress Controller sharding by using route labels] and xref:../networking/ingress-operator.adoc#nw-ingress-sharding-namespace-labels_configuring-ingress[Configuring Ingress Controller sharding by using namespace labels]. - -include::modules/router-performance-optimizations.adoc[leveloffset=+1] diff --git a/scalability_and_performance/scaling-cluster-monitoring-operator.adoc b/scalability_and_performance/scaling-cluster-monitoring-operator.adoc deleted file mode 100644 index ceca4ad2f0ae..000000000000 --- a/scalability_and_performance/scaling-cluster-monitoring-operator.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="scaling-cluster-monitoring-operator"] -= Scaling the Cluster Monitoring Operator -include::modules/common-attributes.adoc[] -:context: cluster-monitoring-operator - -toc::[] - -{product-title} exposes metrics that the Cluster Monitoring Operator collects and stores in the Prometheus-based monitoring stack. As an administrator, you can view system resources, containers and components metrics in one dashboard interface, Grafana. - -[IMPORTANT] -==== -If you are running cluster monitoring with an attached PVC for Prometheus, you might experience OOM kills during cluster upgrade. When persistent storage is in use for Prometheus, Prometheus memory usage doubles during cluster upgrade and for several hours after upgrade is complete. To avoid the OOM kill issue, allow worker nodes with double the size of memory that was available prior to the upgrade. For example, if you are running monitoring on the minimum recommended nodes, which is 2 cores with 8 GB of RAM, increase memory to 16 GB. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1925061[BZ#1925061]. -==== - -include::modules/prometheus-database-storage-requirements.adoc[leveloffset=+1] - -include::modules/configuring-cluster-monitoring.adoc[leveloffset=+1] diff --git a/scalability_and_performance/using-cluster-loader.adoc b/scalability_and_performance/using-cluster-loader.adoc deleted file mode 100644 index 9e70ecda48f6..000000000000 --- a/scalability_and_performance/using-cluster-loader.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="using_cluster_loader_{context}"] -= Using Cluster Loader -include::modules/common-attributes.adoc[] -:context: - -toc::[] - -Cluster Loader is a tool that deploys large numbers of various objects to a cluster, which creates user-defined cluster objects. Build, configure, and run Cluster Loader to measure performance metrics of your {product-title} deployment at various cluster states. - -include::modules/installing-cluster-loader.adoc[leveloffset=+1] - -include::modules/running-cluster-loader.adoc[leveloffset=+1] - -include::modules/configuring-cluster-loader.adoc[leveloffset=+1] - - -== Known issues - -* Cluster Loader fails when called without configuration. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1761925[*BZ#1761925*]) - -* If the `IDENTIFIER` parameter is not defined in user templates, template creation fails with `error: unknown parameter name "IDENTIFIER"`. If you deploy templates, add this parameter to your template to avoid this error: -+ -[source,yaml] ----- -{ - "name": "IDENTIFIER", - "description": "Number to append to the name of resources", - "value": "1" -} ----- -+ -If you deploy pods, adding the parameter is unnecessary. diff --git a/scalability_and_performance/using-cpu-manager.adoc b/scalability_and_performance/using-cpu-manager.adoc deleted file mode 100644 index d665e0a9f4ff..000000000000 --- a/scalability_and_performance/using-cpu-manager.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id='using-cpu-manager'] -= Using CPU Manager -include::modules/common-attributes.adoc[] -:context: using-cpu-manager - -toc::[] - -CPU Manager manages groups of CPUs and constrains workloads to specific CPUs. - -CPU Manager is useful for workloads that have some of these attributes: - -* Require as much CPU time as possible. -* Are sensitive to processor cache misses. -* Are low-latency network applications. -* Coordinate with other processes and benefit from sharing a single processor -cache. - -include::modules/setting-up-cpu-manager.adoc[leveloffset=+1] diff --git a/scalability_and_performance/using-node-tuning-operator.adoc b/scalability_and_performance/using-node-tuning-operator.adoc deleted file mode 100644 index 556900bb2211..000000000000 --- a/scalability_and_performance/using-node-tuning-operator.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="using-node-tuning-operator"] -= Using the Node Tuning Operator -include::modules/common-attributes.adoc[] -:context: node-tuning-operator - -toc::[] - -Learn about the Node Tuning Operator and how you can use it to manage node-level -tuning by orchestrating the tuned daemon. - -include::modules/node-tuning-operator.adoc[leveloffset=+1] - -include::modules/accessing-an-example-cluster-node-tuning-operator-specification.adoc[leveloffset=+1] - -include::modules/cluster-node-tuning-operator-default-profiles-set.adoc[leveloffset=+1] - -include::modules/cluster-node-tuning-operator-verify-profiles.adoc[leveloffset=+1] - -include::modules/custom-tuning-specification.adoc[leveloffset=+1] - -include::modules/custom-tuning-example.adoc[leveloffset=+1] - -include::modules/node-tuning-operator-supported-tuned-daemon-plug-ins.adoc[leveloffset=+1] diff --git a/scalability_and_performance/using-topology-manager.adoc b/scalability_and_performance/using-topology-manager.adoc deleted file mode 100644 index 768319a91845..000000000000 --- a/scalability_and_performance/using-topology-manager.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="using-topology-manager"] -= Using Topology Manager -include::modules/common-attributes.adoc[] -:context: using-topology-manager - -toc::[] - -Topology Manager collects hints from the CPU Manager, Device Manager, and other Hint Providers to align pod resources, such as CPU, SR-IOV VFs, -and other device resources, for all Quality of Service (QoS) classes on the same non-uniform memory access (NUMA) node. - -Topology Manager uses topology information from collected hints to decide if -a pod can be accepted or rejected on a node, based on the configured Topology -Manager policy and Pod resources requested. - -Topology Manager is useful for workloads that use hardware accelerators -to support latency-critical execution and high throughput parallel computation. - -[NOTE] -==== -To use Topology Manager you must use the CPU Manager with the `static` policy. For more information on CPU Manager, see xref:../scalability_and_performance/using-cpu-manager.adoc#using-cpu-manager[Using CPU Manager]. -==== - -include::modules/topology-manager-policies.adoc[leveloffset=+1] -include::modules/setting-up-topology-manager.adoc[leveloffset=+1] - -.Additional resources -For more information on CPU Manager, see xref:../scalability_and_performance/using-cpu-manager.adoc#using-cpu-manager[Using CPU Manager]. - -include::modules/pod-interactions-with-topology-manager.adoc[leveloffset=+1] diff --git a/scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc b/scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc deleted file mode 100644 index c6ec9c496526..000000000000 --- a/scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id='what-huge-pages-do-and-how-they-are-consumed'] -= What huge pages do and how they are consumed by applications -include::modules/common-attributes.adoc[] -:context: huge-pages - -toc::[] - -include::modules/what-huge-pages-do.adoc[leveloffset=+1] - -include::modules/how-huge-pages-are-consumed-by-apps.adoc[leveloffset=+1] - -include::modules/configuring-huge-pages.adoc[leveloffset=+1] diff --git a/scripts/analytics_fix.sh b/scripts/analytics_fix.sh index ff9baf10ade7..513858880b57 100644 --- a/scripts/analytics_fix.sh +++ b/scripts/analytics_fix.sh @@ -6,8 +6,8 @@ GREEN='\033[0;32m' # Download analytics related files and move them to correct folders echo -e "${GREEN}==== Download files with removed analytics ====${NC}" -wget https://raw.githubusercontent.com/openshift/openshift-docs/master/scripts/ocpdocs/_analytics_other.html -O _templates/_analytics_other.html -wget https://raw.githubusercontent.com/openshift/openshift-docs/master/scripts/ocpdocs/_footer_other.html.erb -O _templates/_footer_other.html.erb -wget https://raw.githubusercontent.com/openshift/openshift-docs/master/scripts/ocpdocs/_topnav_other.html -O _templates/_topnav_other.html -wget https://raw.githubusercontent.com/openshift/openshift-docs/master/scripts/ocpdocs/index-commercial.html -O index-commercial.html -wget https://raw.githubusercontent.com/openshift/openshift-docs/master/scripts/ocpdocs/search-commercial.html -O search-commercial.html +wget https://raw.githubusercontent.com/openshift/openshift-docs/main/scripts/ocpdocs/_analytics_other.html -O _templates/_analytics_other.html +wget https://raw.githubusercontent.com/openshift/openshift-docs/main/scripts/ocpdocs/_footer_other.html.erb -O _templates/_footer_other.html.erb +wget https://raw.githubusercontent.com/openshift/openshift-docs/main/scripts/ocpdocs/_topnav_other.html -O _templates/_topnav_other.html +wget https://raw.githubusercontent.com/openshift/openshift-docs/main/scripts/ocpdocs/index-commercial.html -O index-commercial.html +wget https://raw.githubusercontent.com/openshift/openshift-docs/main/scripts/ocpdocs/search-commercial.html -O search-commercial.html diff --git a/scripts/check-asciidoctor-build.sh b/scripts/check-asciidoctor-build.sh new file mode 100755 index 000000000000..f23a5b359cb6 --- /dev/null +++ b/scripts/check-asciidoctor-build.sh @@ -0,0 +1,86 @@ +#!/bin/bash + +# ensure asciidoctor is installed +if ! command -v asciidoctor &>/dev/null ; +then + echo "Asciidoctor is not installed. Please install it and try again. 👻" + exit 127 +fi + +# get the *.adoc modules and assemblies in the pull request +FILES=$(git diff --name-only HEAD~1 HEAD --diff-filter=d "*.adoc" ':(exclude)_unused_topics/*') +REPO_PATH=$(git rev-parse --show-toplevel) + +# get the modules in the PR, search for assemblies that include them, and concat with any updated assemblies files +check_updated_assemblies () { + MODULES=$(echo "$FILES" | awk '/modules\/(.*)\.adoc/') + if [ "${MODULES}" ] + then + # $UPDATED_ASSEMBLIES is the list of assemblies that contains changed modules + UPDATED_ASSEMBLIES=$(grep -rnwl "$REPO_PATH" --include=\*.adoc --exclude-dir={snippets,modules} -e "$MODULES") + # Exit 0 if there are no modified assemblies + if [[ -z "${UPDATED_ASSEMBLIES}" ]] + then + echo "No updated assemblies found! ✅" + exit 0 + fi + update_log + # subtract $REPO_PATH from path with bash substring replacement + UPDATED_ASSEMBLIES=${UPDATED_ASSEMBLIES//"$REPO_PATH/"/} + fi + # $ASSEMBLIES is the list of modifed assemblies + ASSEMBLIES=$(echo "$FILES" | awk '!/modules\/(.*)\.adoc/') + # concatenate both lists and remove dupe entries + ALL_ASSEMBLIES=$(echo "$UPDATED_ASSEMBLIES $ASSEMBLIES" | tr ' ' '\n' | sort -u) + # check that assemblies are in a topic_map + for ASSEMBLY in ${ALL_ASSEMBLIES}; do + # get the page name to search the topic_map + # search for files only, not folders + PAGE="File: $(basename "$ASSEMBLY" .adoc)" + # don't validate the assembly if it is not in a topic map + if grep -rq "$PAGE" --include "*.yml" _topic_maps ; then + # validate the assembly + echo "Validating $ASSEMBLY ..." + RED='\033[0;31m' + NC='\033[0m' + OUTPUT=$(asciidoctor "$ASSEMBLY" -a source-highlighter=rouge -a icons! -o /tmp/out.html -v --failure-level WARN --trace 2>&1) + # check assemblies and fail if errors are reported + if [[ $? != 0 ]]; + then + echo -e "${RED}$OUTPUT${NC}" + ERRORS=true + else + echo "No errors found for $ASSEMBLY! ✅" + fi + else + echo "$ASSEMBLY is not in a topic_map, skipping validation... 😙" + fi + done + if [ "$ERRORS" = true ]; then + echo "Validation errors found! ❌" + exit 1 + fi +} + +update_log () { + echo "" + echo "****************************************************************************" + echo "" + echo "Validating all AsciiDoc assemblies that are modifed by the pull request. 🕵" + echo "All assemblies that include modifed modules are validated. 🙀" + echo "This might include assemblies that are not in the pull request! 🤬" + echo "Validation will fail with FAILED, ERROR, or WARNING messages. ❌" + echo "Correct all reported AsciiDoc errors to pass the validation build. 🤟" + echo "" + echo "****************************************************************************" + echo "" +} + +# check assemblies and fail if errors are reported +if [ -n "${FILES}" ] ; +then + check_updated_assemblies +else + echo "No modified AsciiDoc files found! 🥳" + exit 0 +fi diff --git a/scripts/check-rn-link-perms.sh b/scripts/check-rn-link-perms.sh new file mode 100755 index 000000000000..c49baa02206f --- /dev/null +++ b/scripts/check-rn-link-perms.sh @@ -0,0 +1,30 @@ +#!/bin/bash +# Report errors for links to Red Hat JIRA bugs that are behind a login + +# Get modifed lines, remove deleted lines from the diff +git_diff=$(git diff --unified=0 --stat --diff-filter=AM HEAD~1 HEAD "*release-notes*.adoc" ':(exclude)_unused_topics/*' | grep '^+' | grep -Ev '^(\+\+\+ a/ b/)') + +# Exit zero if there are no release-notes changes +if [ -z "${git_diff}" ]; then + exit 0 +fi + +# Remove all multi-line comments and single line comments +git_diff=$(echo "${git_diff}" | sed '\|^+////|,\|^+////|c\\' | sed '\|^+//| s|.*|//|') + +# Search the git diff for links +link_regex='https://issues/.redhat/.com/browse/[A-Z]+-[0-9]+' +links=$(echo "${git_diff}" | grep -o -E "$link_regex" | sort -u) + +for link in ${links}; do + # Check for links that require a login + response=$(curl -I "${link}" 2>&1) + if echo "${response}" | grep -q "permissionViolation"; then + errors=true + echo -e "\e[31mERROR: Do not include links to JIRA issues that require a login (${link})\n" + fi +done + +if [ "$errors" = true ]; then + exit 1 +fi diff --git a/scripts/check-with-vale.sh b/scripts/check-with-vale.sh new file mode 100755 index 000000000000..6e09beedcec8 --- /dev/null +++ b/scripts/check-with-vale.sh @@ -0,0 +1,24 @@ +#!/bin/bash + +set -e + +# list of *.adoc files excluding files in /rest_api, generated files, and deleted files +FILES=$(git diff --name-only HEAD~1 HEAD --diff-filter=d "*.adoc" ':(exclude)rest_api/*' ':(exclude)modules/example-content.adoc' ':(exclude)modules/oc-adm-by-example-content.adoc') + +if [ -n "${FILES}" ] ; + then + echo "Validating language usage in added or modified asciidoc files with $(vale -v)" + echo "" + echo "===============================================================================================================================" + echo "Read about the error terms that cause the build to fail at https://redhat-documentation.github.io/vale-at-red-hat/docs/reference-guide/termserrors/" + echo "===============================================================================================================================" + if [ "$TRAVIS" = true ] ; then + #clean out conditional markup in Travis CI + sed -i -e 's/ifdef::.*\|ifndef::.*\|ifeval::.*\|endif::.*/ /' ${FILES} + vale ${FILES} --glob='*.adoc' --minAlertLevel=error + else + vale ${FILES} --glob='*.adoc' --minAlertLevel=suggestion + fi + else + echo "No asciidoc files added or modified." +fi diff --git a/scripts/find_unused.py b/scripts/find_unused.py index dde54d290b3c..029682d3f184 100755 --- a/scripts/find_unused.py +++ b/scripts/find_unused.py @@ -6,8 +6,14 @@ __author__ = "Christian Huffman" __version__ = "1 July, 2019" + +Updated September 2022 to run with Python 3. + +Run with `python scripts/find_unused.py .` at the repo root level to run against the entire repo. """ +from __future__ import print_function + from os.path import join import argparse import os @@ -48,7 +54,7 @@ def process(self): self.move_files(self.args.path,remaining_modules) else: for filename in remaining_modules: - print remaining_modules[filename] + print(remaining_modules[filename]) def check_assemblies(self,assemblies,modules): """ @@ -79,7 +85,7 @@ def move_files(self,root,remaining_modules): try: for key in remaining_modules: os.rename(remaining_modules[key],root + "/" + self.unused_directory + "/" + key) - print "Moved %d files" % len(remaining_modules) + print("Moved %d files" % len(remaining_modules)) except OSError as err: print("Unable to move files: {0}".format(err)) print("Target destination: " + self.unused_directory) diff --git a/scripts/fix_discrete.sh b/scripts/fix_discrete.sh new file mode 100755 index 000000000000..48db3186f504 --- /dev/null +++ b/scripts/fix_discrete.sh @@ -0,0 +1,68 @@ +#!/bin/bash + +# Spinner function +spinner() { + local pid=$1 + local delay=0.1 + local spinstr='|/-\' + while kill -0 $pid 2>/dev/null; do + local temp=${spinstr#?} + printf " [%c] " "$spinstr" + spinstr=$temp${spinstr%"$temp"} + sleep $delay + printf "\b\b\b\b\b\b" + done + printf " \b\b\b\b" +} + +# Ask user for the base directory +read -rp "Enter the path to the base directory: " BASE_DIR + +# Validate directory +if [[ ! -d "$BASE_DIR" ]]; then + echo "Error: $BASE_DIR is not a valid directory." + exit 1 +fi + +echo "Processing directory: $BASE_DIR" + +FILES=$(find "$BASE_DIR" -type f -name "*.adoc") +TOTAL_COUNT=$(echo "$FILES" | wc -l | tr -d ' ') + +CURRENT=0 +echo "Found $TOTAL_COUNT .adoc files." + +# Process files +echo +for FILE in $FILES; do + CURRENT=$((CURRENT+1)) + printf "Processing file %d/%d: %s" "$CURRENT" "$TOTAL_COUNT" "$FILE" + + ( + REPLACEMENTS=$(awk ' + BEGIN { count=0 } + # Remove [discrete] and prevent blank line + /^\[discrete\]$/ { count++; next } + { print } + END { print "###REPLACEMENTS###" count } + ' "$FILE") + + COUNT=$(echo "$REPLACEMENTS" | tail -n1 | sed 's/###REPLACEMENTS###//') + + if [[ "$COUNT" -gt 0 ]]; then + echo "$REPLACEMENTS" | sed '/###REPLACEMENTS###/d' > "${FILE}.tmp" && mv "${FILE}.tmp" "$FILE" + echo "###SUMMARY### $COUNT" + fi + ) & + spinner $! + RESULT=$(wait $! 2>/dev/null; true) + + COUNT=$(echo "$RESULT" | grep "###SUMMARY###" | awk '{print $2}') + + if [[ -n "$COUNT" && "$COUNT" -gt 0 ]]; then + echo " -> Modified ($COUNT [discrete] removed)" + else + echo -ne "\r\033[K" + fi +done + diff --git a/scripts/get-updated-distros.sh b/scripts/get-updated-distros.sh new file mode 100755 index 000000000000..00b97d8b25d3 --- /dev/null +++ b/scripts/get-updated-distros.sh @@ -0,0 +1,44 @@ +#!/bin/bash +# Returns a list of updated _topic_map.yml files. +# The list includes any topic maps that are themselves modified, and indirectly modifed topic maps where incldued AsciiDoc files have been updated. + +# Get the *.adoc and distro maps files in the pull request +FILES=$(git diff --name-only HEAD~1 HEAD --diff-filter=AMRD "*.yml" "*.adoc" ':(exclude)_unused_topics/*') + +REPO_PATH=$(git rev-parse --show-toplevel) + +# Init an empty array +DISTROS=() + +# Get the modules in the PR, search for assemblies that include them, and concat with any updated assemblies files +MODULES=$(echo "$FILES" | awk '/modules\/(.*)\.adoc/') +if [ "${MODULES}" ] +then + # $UPDATED_ASSEMBLIES is the list of assemblies that contains changed modules + UPDATED_ASSEMBLIES=$(grep -rnwl "$REPO_PATH" --include=\*.adoc --exclude-dir={snippets,modules} -e "$MODULES") + + # Subtract $REPO_PATH from path with bash substring replacement + UPDATED_ASSEMBLIES=${UPDATED_ASSEMBLIES//"$REPO_PATH/"/} +fi + +# ASSEMBLIES is the list of modifed assemblies +ASSEMBLIES=$(echo "$FILES" | awk '!/modules\/(.*)\.adoc/') +# Concatenate both lists and remove dupe entries +ALL_ASSEMBLIES=$(echo "$UPDATED_ASSEMBLIES $ASSEMBLIES" | tr ' ' '\n' | sort -u) +# Check that assemblies are in a topic_map +for ASSEMBLY in $ALL_ASSEMBLIES; do + # Get the page name to search the topic_map + # Search for files only, not folders + PAGE="File: $(basename "$ASSEMBLY" .adoc)" + # Don't include the assembly if it is not in a topic map + if grep -rq "$PAGE" --include "*.yml" _topic_maps ; then + DISTROS+=("$(grep -rl "$PAGE" _topic_maps/*.yml)") + fi +done + +# Handle modified topic maps +UPDATED_DISTROS=$(echo "$FILES" | awk '/_topic_maps\/(.*)\.yml/') +# Concat all the updated topic maps +DISTROS+=("${UPDATED_DISTROS}") +# Clean up and remove duplicates +echo "${DISTROS[@]}" | tr ' ' '\n' | sort | uniq diff --git a/scripts/get-updated-preview-urls.sh b/scripts/get-updated-preview-urls.sh new file mode 100755 index 000000000000..49d377e09c5e --- /dev/null +++ b/scripts/get-updated-preview-urls.sh @@ -0,0 +1,61 @@ +#!/bin/bash +# Returns a list of page preview URLs +# To run locally, clean the _preview folder and do a new asciibinder build before running the script +# To run in Prow CI, run with +# ./get-updated-preview-urls.sh $PULL_NUMBER + +# Check if jq is installed +hash jq 2>/dev/null || { echo >&2 "Error: jq is not installed"; exit 1; } + +# Set $pull_number if it is not passed as variable +if [ $# -eq 0 ]; then +commit_id=$(git log -n 1 --pretty=format:"%H") +pull_number="$(curl -s "https://api.github.com/search/issues?q=$commit_id" | jq '.items[0].number')" +pr_branch="$(git rev-parse --abbrev-ref HEAD)" +else + pull_number=$1 + pr_branch="latest" +fi + +preview_url_slug="ocpdocs-pr" +preview_url="https://${pull_number}--${preview_url_slug}.netlify.app/" +assemblies=() +pages=() +files=$(git diff --name-only HEAD~1 HEAD --diff-filter=AMRD "*.adoc" ':(exclude)_unused_topics/*') + +# Get the full list of HTML build files +if [ -e "_preview" ]; then + built_pages=$(find _preview -type f -name "*.html" -printf "%P\n") +else + echo "_preview output folder not found" + exit 1 +fi + +# Search for $file references in all *.adoc files that are not in a folder called modules/, snippets/, or _unused_topics/ +for file in $files; do + include_ref="include::$file" + found_file=$(grep -rl --include='*.adoc' --exclude-dir={modules,snippets,_unused_topics} "^$include_ref") + # Add the found updated assemblies, not directly included in PR + assemblies+=("$found_file") + # If not found, then it is a directly updated assembly file + if [ -z "$found_file" ]; then + assemblies+=("$file") + fi +done + +# Make the HTML URL slugs +if [ ${#assemblies[@]} -gt 0 ]; then + for assembly in "${assemblies[@]}"; do + updated_pages+=$(echo "$assembly" | sed 's/\.adoc$/.html/' | tr '\n' ' ') + done +fi + +# Search built_pages for every entry in updated_pages and add to pages array when it is found +for updated_page in $updated_pages; do + # sed s/$pr_branch/latest to match the Prow build URL + found_page=$(echo "${built_pages}" | grep "${updated_page}" | sed "s|/$pr_branch/|/latest/|") + pages+=("${found_page}") +done + +#Echo the results, prepending the $preview_url to every line +echo "${pages[@]}" | tr ' ' '\n' | sort | uniq | sed "s|^|$preview_url/|" diff --git a/scripts/lint-topicmaps.sh b/scripts/lint-topicmaps.sh new file mode 100755 index 000000000000..5cf6cdd0a9aa --- /dev/null +++ b/scripts/lint-topicmaps.sh @@ -0,0 +1,32 @@ +#!/bin/bash + +# Use yamllint to lint and report errors for modified topic_map.yml files + +# Ensure yamllint is installed +if ! command -v yamllint &>/dev/null; then + echo "yamllint is not installed. Please install it and try again 👻" + exit 127 +fi + +# List of modified topic_map files +FILES=$(git diff --name-only HEAD~1 HEAD --diff-filter=d "./_topic_maps/*.yml") + +if [ -n "${FILES}" ]; then + has_errors=0 + for FILE in ${FILES[@]}; do + if ! yamllint "$FILE"; then + echo "YAML error(s) found in $FILE 😥" + has_errors=1 + fi + done + + if [ $has_errors -eq 1 ]; then + exit 1 + else + echo "No YAML errors found 🥳" + exit 0 + fi +else + echo "No updated topic_maps... 😙" + exit 0 +fi diff --git a/scripts/manualpreview.sh b/scripts/manualpreview.sh new file mode 100755 index 000000000000..f959e28ed33f --- /dev/null +++ b/scripts/manualpreview.sh @@ -0,0 +1,67 @@ +#!/bin/bash + +set -e + +git_root=$(git rev-parse --show-toplevel) + +# Exit if Travis is not being used +if [ -f "${git_root}/.travis.yml.old" ]; then + echo "Travis CI is not in use. Exiting..." + exit 0 +fi + +# Check if jq is installed +hash jq 2>/dev/null || { echo >&2 "Error: jq is not installed. Please install jq before running this script."; exit 1; } + +# Check if gh is installed +hash gh 2>/dev/null || { echo >&2 "Error: GitHub CLI (gh) is not installed. Please install gh before running this script."; exit 1; } + +# Check if inside a repository +if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then + echo "ERROR: you must execute this script from the OpenShift Git repository." 1>&2 + exit 1 +fi + +PR_BRANCH="$(git rev-parse --abbrev-ref HEAD)" +PR_NUMBER="$(gh pr list -H "$PR_BRANCH" --json number | jq -r '.[0].number')" +PR_COUNT="$(gh pr list -H $PR_BRANCH -s open | wc -l)" +AUTHOR="$(gh pr view $PR_NUMBER --json author | jq -r '.author.login')" +BASE_REF="$(gh pr view $PR_NUMBER --json baseRefName | jq -r '.baseRefName')" +SHA=$(git rev-parse HEAD) + +# Check if there are more than one PRs associated with the branch +if [ "$PR_COUNT" -gt 1 ]; then + echo "ERROR: there are multiple PRs referencing your working branch." >&2 + exit 1 +fi + +# Function to create the data to send +generate_pr_data() +{ + cat <<EOF + { + "PR_BRANCH": "$PR_BRANCH", + "BASE_REPO": "openshift/openshift-docs", + "PR_NUMBER": "$PR_NUMBER", + "USER_NAME": "$AUTHOR", + "BASE_REF": "$BASE_REF", + "REPO_NAME": "$AUTHOR/openshift-docs", + "SHA": "$SHA" + } +EOF +} + + +# Send the curl request +if response=$(curl -s -X POST -H "Content-Type: application/json" -d "$(generate_pr_data)" https://eoa6vg2jiwjbnh6.m.pipedream.net); then + if echo "$response" | grep -q -e "✅ Success! 🤖 Building the preview"; then + echo "Preview build started successfully" + echo "$response" + else + echo "Curl request failed: Invalid data!" + exit 1 + fi +else + echo "Curl request failed: $response" + exit 1 +fi diff --git a/scripts/ocp_preview.sh b/scripts/ocp_preview.sh index 6b811505f158..45a63c70399b 100644 --- a/scripts/ocp_preview.sh +++ b/scripts/ocp_preview.sh @@ -2,13 +2,13 @@ set -ev # Download the preview page -wget https://raw.githubusercontent.com/openshift/openshift-docs/master/scripts/ocpdocs/_previewpage +wget https://raw.githubusercontent.com/openshift/openshift-docs/main/scripts/ocpdocs/_previewpage # Copy preview page into the _preview folder cp --verbose _previewpage _preview/index.html #Download robots.txt -wget https://raw.githubusercontent.com/openshift/openshift-docs/master/scripts/ocpdocs/robots_preview.txt +wget https://raw.githubusercontent.com/openshift/openshift-docs/main/scripts/ocpdocs/robots_preview.txt # Copy robots into the _preview folder cp --verbose robots_preview.txt _preview/robots.txt diff --git a/scripts/ocpdocs/_previewpage b/scripts/ocpdocs/_previewpage index 4b24f750d874..75951574d617 100644 --- a/scripts/ocpdocs/_previewpage +++ b/scripts/ocpdocs/_previewpage @@ -1,64 +1,211 @@ <!DOCTYPE html> <html class="js flexbox flexboxlegacy canvas canvastext webgl no-touch geolocation postmessage no-websqldatabase indexeddb hashchange history draganddrop websockets rgba hsla multiplebgs backgroundsize borderimage borderradius boxshadow textshadow opacity cssanimations csscolumns cssgradients no-cssreflections csstransforms csstransforms3d csstransitions fontface generatedcontent video audio localstorage sessionstorage webworkers applicationcache svg inlinesvg smil svgclippaths"> - -<head> - <meta name="viewport" content="width=device-width, initial-scale=1.0"> - <meta http-equiv="X-UA-Compatible" content="IE=edge"> - <meta charset="utf-8"> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="X-UA-Compatible" content="IE=edge" /> + <meta charset="utf-8" /> <title>OpenShift Docs PR Review</title> - <link href="https://assets.openshift.net/content/subdomain.css" rel="stylesheet" media="screen, print"> - <link href="https://github.com/openshift-enterprise/latest/_stylesheets/commercial-home.css" rel="stylesheet"> + <link + href="https://assets.openshift.net/content/subdomain.css" + rel="stylesheet" + media="screen, print" + /> + <link + href="https://github.com/openshift-enterprise/latest/_stylesheets/commercial-home.css" + rel="stylesheet" + /> + </head> + <body> <header class="masthead masthead-docs text-center"> - <div class="container"> - <div class="title-inner"> - <h1>OpenShift Docs PR Preview</h1> - </div> + <div class="container"> + <div class="title-inner"> + <h1>OpenShift Docs PR Preview</h1> </div> + </div> </header> <div class="landing"> - <div class="container"> - <div class="row"> - <div class="col-md-10 col-centered"> - <div class="row"> - <div class="col-sm-3 text-center"> - <h2>OpenShift Container Platform</h2> - <div class="list-group"> - <p> - <a role="button" class="btn btn-primary" href="https://github.com/openshift-enterprise/latest/welcome/index.html"> - <i class="fa fa-arrow-circle-o-right"></i> Enterprise</a> - </p> - <p class="list-group-item-text">Red Hat's private, on-premise cloud application deployment and hosting platform.</p> - - </div> - </div> - <div class="col-sm-3 text-center"> - <h2>OpenShift Dedicated</h2> - <div class="list-group"> - <p> - <a role="button" class="btn btn-primary" href="https://github.com/openshift-dedicated/latest/welcome/index.html"> - <i class="fa fa-arrow-circle-o-right"></i> Dedicated</a> - </p> - <p class="list-group-item-text">Red Hat's managed public cloud application deployment and hosting service.</p> - - </div> - </div> - <div class="col-sm-3 text-center"> - <h2>OpenShift ROSA</h2> - <div class="list-group"> - <p> - <a role="button" class="btn btn-primary" href="https://github.com/openshift-rosa/latest/welcome/index.html"> - <i class="fa fa-arrow-circle-o-right"></i> ROSA</a> - </p> - <p class="list-group-item-text">Managed OpenShift in the AWS cloud.</p> - - </div> - </div> - - </div> - </div> + <div class="container"> + <div class="row"> + <div class="col-sm-6 text-center"> + <h2>OpenShift Container Platform</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-enterprise/latest/welcome/index.html" + > + <i class="fa fa-arrow-circle-o-right"></i> Enterprise</a + > + </p> + <p class="list-group-item-text"> + Red Hat's private, on-premise cloud application deployment and + hosting platform. + </p> + </div> + </div> + <div class="col-sm-6 text-center"> + <h2>OpenShift Dedicated</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-dedicated/latest/welcome/index.html" + > + <i class="fa fa-arrow-circle-o-right"></i> Dedicated</a + > + </p> + <p class="list-group-item-text"> + Red Hat's managed public cloud application deployment and + hosting service. + </p> + </div> + </div> + </div> + <div class="row"> + <div class="col-sm-6 text-center"> + <h2>OpenShift ROSA</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-rosa/latest/welcome/index.html" + > + <i class="fa fa-arrow-circle-o-right"></i> ROSA</a + > + </p> + <p class="list-group-item-text"> + Managed OpenShift in the AWS cloud. + </p> + </div> + </div> + <div class="col-sm-6 text-center"> + <h2>Red Hat Advanced Cluster Security for Kubernetes</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-acs/latest/welcome/index.html" + > + <i class="fa fa-arrow-circle-o-right"></i> RHACS</a + > + </p> + <p class="list-group-item-text"> + An enterprise-ready, Kubernetes-native container security + solution that enables you to securely build, deploy, and run + cloud-native applications anywhere. + </p> + </div> + </div> + <div class="col-sm-6 text-center"> + <h2>MicroShift</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/microshift/latest/microshift_welcome/index.html" + > + <i class="fa fa-arrow-circle-o-right"></i> MicroShift</a + > + </p> + <p class="list-group-item-text"> + MicroShift is a distribution of OpenShift Container Platform designed for optimizing small form factors and edge computing. + </p> + </div> + </div> + <div class="col-sm-6 text-center"> + <h2>Red Hat Device Edge</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-rhde/latest/overview/rhde-overview.html" + > + <i class="fa fa-arrow-circle-o-right"></i> RHDE </a + > + </p> + <p class="list-group-item-text"> + Red Hat Device Edge delivers an enterprise-ready and supported distribution of MicroShift, the Red Hat-led open source community project. + </p> + </div> + </div> + </div> + <div class="row"> + <div class="col-sm-6 text-center"> + <h2>OpenShift Serverless</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-serverless/latest/install/serverless-kafka-admin.html" + > + <i class="fa fa-arrow-circle-o-right"></i> Serverless</a + > + </p> + <p class="list-group-item-text"> + Standalone OpenShift Serverless documentation. + </p> + </div> + </div> + <div class="col-sm-6 text-center"> + <h2>OpenShift Pipelines</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-pipelines/latest/about/understanding-openshift-pipelines.html" + > + <i class="fa fa-arrow-circle-o-right"></i> Pipelines</a + > + </p> + <p class="list-group-item-text"> + Standalone OpenShift Pipelines documentation. + </p> + </div> + </div> + <div class="col-sm-6 text-center"> + <h2>OpenShift Builds</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-builds/latest/about/overview-openshift-builds.html" + > + <i class="fa fa-arrow-circle-o-right"></i> Builds</a + > + </p> + <p class="list-group-item-text"> + Standalone OpenShift Builds documentation. + </p> + </div> + </div> + <div class="col-sm-6 text-center"> + <h2>OpenShift GitOps</h2> + <div class="list-group"> + <p> + <a + role="button" + class="btn btn-primary" + href="https://github.com/openshift-gitops/latest/understanding_openshift_gitops/what-is-gitops.html" + > + <i class="fa fa-arrow-circle-o-right"></i> GitOps</a + > + </p> + <p class="list-group-item-text"> + Standalone OpenShift GitOps documentation. + </p> </div> + </div> </div> + </div> </div> - </body> - + </body> </html> diff --git a/scripts/ocpdocs/_topnav_other.html b/scripts/ocpdocs/_topnav_other.html index b78d42eb0933..e7c0bf7fd066 100644 --- a/scripts/ocpdocs/_topnav_other.html +++ b/scripts/ocpdocs/_topnav_other.html @@ -109,7 +109,7 @@ <li><a class="nav-sign-up" target="_blank" href="https://www.openshift.com/trial/">Free Trial</a></li> - <li><a target="_blank" href="https://manage.openshift.com/" class="nav-log-in">Sign In <span class="fa fa-angle-right"></span></a></li> + <li><a target="_blank" href="https://console.redhat.com/openshift" class="nav-log-in">Sign In <span class="fa fa-angle-right"></span></a></li> </ul> </div> diff --git a/scripts/ocpdocs/index-commercial.html b/scripts/ocpdocs/index-commercial.html index e664f5289106..405b9fba5a47 100644 --- a/scripts/ocpdocs/index-commercial.html +++ b/scripts/ocpdocs/index-commercial.html @@ -147,7 +147,7 @@ <li><a class="nav-sign-up" target="_blank" href="https://www.openshift.com/trial/">Free Trial</a></li> - <li><a target="_blank" href="https://manage.openshift.com/" class="nav-log-in">Sign In <span class="fa fa-angle-right"></span></a></li> + <li><a target="_blank" href="https://console.redhat.com/openshift" class="nav-log-in">Sign In <span class="fa fa-angle-right"></span></a></li> </ul> </div> diff --git a/scripts/ocpdocs/search-commercial.html b/scripts/ocpdocs/search-commercial.html index c1be7fe5e610..8a1ea6a42eab 100644 --- a/scripts/ocpdocs/search-commercial.html +++ b/scripts/ocpdocs/search-commercial.html @@ -147,7 +147,7 @@ <li><a class="nav-sign-up" target="_blank" href="https://www.openshift.com/trial/">Free Trial</a></li> - <li><a target="_blank" href="https://manage.openshift.com/" class="nav-log-in">Sign In <span class="fa fa-angle-right"></span></a></li> + <li><a target="_blank" href="https://console.redhat.com/openshift" class="nav-log-in">Sign In <span class="fa fa-angle-right"></span></a></li> </ul> </div> diff --git a/scripts/process-apidocs-for-pantheon.sh b/scripts/process-apidocs-for-pantheon.sh new file mode 100755 index 000000000000..5c8e2e40e03f --- /dev/null +++ b/scripts/process-apidocs-for-pantheon.sh @@ -0,0 +1,118 @@ +#!/bin/bash + +# Define color codes +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[0;33m' +BLUE='\033[0;34m' +CYAN='\033[0;36m' +NC='\033[0m' # No Color + +echo -e "${YELLOW}==========================================================================${NC}" + +echo -e "${CYAN}Only run this script after you've generated the drupal-build directory.${NC}" + +echo -e "${YELLOW}==========================================================================${NC}" + +echo -e "${BLUE}Press Enter to continue or Ctrl+C to exit.${NC}" +read -r + +BASE_DIR="./drupal-build/openshift-acs/rest_api" + +if [[ ! -d "$BASE_DIR" ]]; then + echo -e "${RED}Error: Directory '$BASE_DIR' does not exist.${NC}" + exit 1 +fi + +echo -e "${BLUE}Enter the product version number, for example: 4.6 ${NC}" +read -r PRODUCT_VERSION + +if [[ -z "$PRODUCT_VERSION" ]]; then + echo -e "${RED}Error: Product version cannot be empty.${NC}" + exit 1 +fi + +total_folders=0 +folders_with_files=0 +folders_without_files=0 +total_generated_files=0 + +camel_to_space() { + echo "$1" | sed -r 's/([a-z])([A-Z])/\1 \2/g; s/([A-Z]+)([A-Z][a-z])/\1 \2/g' +} + +for dir in "$BASE_DIR"/*/; do + if [[ ! -d "$dir" ]]; then + echo -e "${YELLOW}Warning: '$dir' is not a directory.${NC}" + continue + fi + + folder_name=$(basename "$dir") + if [[ "$folder_name" == "images" ]]; then + echo -e "${YELLOW}Skipping 'images' directory.${NC}" + continue + fi + + total_folders=$((total_folders + 1)) + folder_name=$(basename "$dir") + master_file="$dir/master.adoc" + docinfo_file="$dir/docinfo.xml" + + if [[ -f "$master_file" && -f "$docinfo_file" ]]; then + folders_with_files=$((folders_with_files + 1)) + continue + fi + + folders_without_files=$((folders_without_files + 1)) + + # Create master.adoc + echo -e "${GREEN}Creating master.adoc in $dir${NC}" + title=$(camel_to_space "$folder_name") + includes="" + + for adoc_file in "$dir"/*.adoc; do + if [[ ! -f "$adoc_file" ]]; then + echo -e "${YELLOW}Warning: No .adoc files found in '$dir'.${NC}" + continue + fi + + if [[ "$adoc_file" != "$master_file" && "$adoc_file" != "$docinfo_file" ]]; then + includes+="include::$(basename "$adoc_file")[leveloffset=+1]\n\n" + fi + done + + { + echo "= $title" + echo ":product-author: Red Hat OpenShift Documentation Team" + echo ":product-title: Red Hat Advanced Cluster Security for Kubernetes" + echo ":product-version: $PRODUCT_VERSION" + echo ":openshift-acs:" + echo ":imagesdir: images" + echo ":idseparator: -" + echo "" + echo -e "$includes" + } > "$master_file" + total_generated_files=$((total_generated_files + 1)) + + # Create docinfo.xml + echo -e "${GREEN}Creating docinfo.xml in $dir${NC}" + { + echo "<title>$title</title>" + echo "<productname>Red Hat Advanced Cluster Security for Kubernetes</productname>" + echo "<productnumber>$PRODUCT_VERSION</productnumber>" + echo "<subtitle>Reference guide for $title.</subtitle>" + echo "<abstract>" + echo " <para>This document describes the Red Hat Advanced Cluster Security for Kubernetes API objects and their detailed specifications.</para>" + echo "</abstract>" + echo "<authorgroup>" + echo " <orgname>Red Hat OpenShift Documentation Team</orgname>" + echo "</authorgroup>" + echo "<xi:include href=\"Common_Content/Legal_Notice.xml\" xmlns:xi=\"http://www.w3.org/2001/XInclude/" />" + } > "$docinfo_file" + total_generated_files=$((total_generated_files + 1)) +done + +echo -e "${BLUE}Total folders checked: $total_folders${NC}" +echo -e "${BLUE}Folders with master.adoc and docinfo.xml: $folders_with_files${NC}" +echo -e "${BLUE}Folders without files (created files): $folders_without_files${NC}" +echo -e "${BLUE}Total generated files: $total_generated_files${NC}" diff --git a/scripts/prow-smoke-test.sh b/scripts/prow-smoke-test.sh new file mode 100755 index 000000000000..6d5ce759ed4e --- /dev/null +++ b/scripts/prow-smoke-test.sh @@ -0,0 +1,112 @@ +#!/bin/bash +#================================================================ +# HEADER +#================================================================ +#% +#%OVERVIEW 📑 +#+ ./scripts/prow-smoke-test.sh [--validate --preview] +#% +#%DESCRIPTION 💡 +#% Validates openshift-docs AsciiDoc source files using the same tools that run in the Prow CI +#% +#%OPTIONS ⚙️ +#% -v, --validate $DISTRO Validate the AsciiDoc source. Use --validate to run with default options +#% -a, --validate-incl-api-book Validate the AsciiDoc source and include the REST API books +#% -l, --lint-topicmaps Lint topic-map YAML +#% -p, --preview $DISTRO "$PRODUCT_NAME" $VERSION Use --preview to run with default options +#% -h, --help Print this help +#% +#%EXAMPLES 🤔 +#% ./scripts/prow-smoke-test.sh --validate +#% ./scripts/prow-smoke-test.sh --validate openshift-rosa +#% ./scripts/prow-smoke-test.sh --validate-incl-api-book +#% ./scripts/prow-smoke-test.sh --lint-topicmaps +#% ./scripts/prow-smoke-test.sh --preview +#% ./scripts/prow-smoke-test.sh --preview openshift-rosa +#% ./scripts/prow-smoke-test.sh --preview openshift-pipelines "Red Hat OpenShift Pipelines" 1.14 +#================================================================ +# END_OF_HEADER +#================================================================ + +set -e + +TEST=$1 +DISTRO=$2 +PRODUCT_NAME=$3 +VERSION=$4 +ARCH=$(uname -m) +TAG=latest # Default tag +SELINUX_LABEL=":Z" +if [[ $ARCH == "aarch64" || $ARCH == "arm64" ]]; then + TAG=multiarch + SELINUX_LABEL="" +fi +CONTAINER_IMAGE="quay.io/redhat-docs/openshift-docs-asciidoc:$TAG" +SCRIPT_HEADSIZE=$(head -30 ${0} |grep -n "^# END_OF_HEADER" | cut -f1 -d:) + +if [[ "$1" == "--help" || "$1" == "-h" ]]; then + usage +fi + +# Assign default variables +: ${PRODUCT_NAME:="OpenShift Container Platform"} +: ${VERSION:="4.16"} +: ${DISTRO:="openshift-enterprise"} + +# Allow podman or docker +if hash podman 2>/dev/null; then + CONTAINER_ENGINE=podman +elif hash docker 2>/dev/null; then + CONTAINER_ENGINE=docker +else + echo >&2 "Container engine not installed. Install Podman or Docker and run the script again." + exit 1 +fi + +echo "CONTAINER_ENGINE=$CONTAINER_ENGINE 🐳" +echo "CONTAINER_IMAGE=$CONTAINER_IMAGE" + +# Get the default container $WORKDIR +CONTAINER_WORKDIR=$($CONTAINER_ENGINE run --rm $CONTAINER_IMAGE /bin/bash -c 'echo $PWD') + +# Grep the commented script preamble and return it as help +display_help() { head -${SCRIPT_HEADSIZE:-99} ${0} | grep -e "^#[%+-]" | sed -e "s/^#[%+-]//g" ; } + +# Exit and show the help if no parameters are passed +if [ $# -eq 0 ]; then + display_help +fi + +if [[ "$TEST" == "--preview" || "$TEST" == "-p" ]] && [[ -z "$DISTRO" ]]; then + # Clean output folder + rm -rf ./_preview + echo "" + echo "🚧 Building with openshift-enterprise distro..." + $CONTAINER_ENGINE run --rm -it -v "$(pwd)":${CONTAINER_WORKDIR}${SELINUX_LABEL} $CONTAINER_IMAGE asciibinder build -d "$DISTRO" + +elif [[ "$TEST" == "--preview" || "$TEST" == "-p" ]] && [[ -n "$DISTRO" ]]; then + # Clean output folder + rm -rf ./_preview + echo "" + echo "🚧 Building $DISTRO distro..." + $CONTAINER_ENGINE run --rm -it -v "$(pwd)":${CONTAINER_WORKDIR}${SELINUX_LABEL} $CONTAINER_IMAGE asciibinder build -d "$DISTRO" + +elif [[ "$TEST" == "--validate" || "$TEST" == "-v" ]]; then + # Clean output folder + rm -rf ./drupal-build + echo "" + echo "🚧 Validating the docs..." + $CONTAINER_ENGINE run --rm -it -v "$(pwd)":${CONTAINER_WORKDIR}${SELINUX_LABEL} $CONTAINER_IMAGE sh -c 'scripts/check-asciidoctor-build.sh && python3 build_for_portal.py --distro '${DISTRO}' --product "'"${PRODUCT_NAME}"'" --version '${VERSION}' --no-upstream-fetch && python3 makeBuild.py' + +elif [[ "$TEST" == "--validate-incl-api-book" || "$TEST" == "-a" ]]; then + # Clean output folder + rm -rf ./drupal-build + echo "" + echo "🚧 Validating the docs..." + $CONTAINER_ENGINE run --rm -it -v "$(pwd)":${CONTAINER_WORKDIR}${SELINUX_LABEL} $CONTAINER_IMAGE sh -c 'scripts/check-asciidoctor-build.sh && python3 build_for_portal.py --distro '${DISTRO}' --product "'"${PRODUCT_NAME}"'" --version '${VERSION}' --no-upstream-fetch && python3 makeBuild.py --include-api-book' + +elif [[ "$TEST" == "--lint-topicmaps" || "$TEST" == "-l" ]]; then + echo "" + echo "🚧 Linting the topicmap YAML..." + $CONTAINER_ENGINE run --rm -it -v "$(pwd)":${CONTAINER_WORKDIR}${SELINUX_LABEL} $CONTAINER_IMAGE sh -c 'yamllint _topic_maps' +fi diff --git a/scripts/prow-vale-review.sh b/scripts/prow-vale-review.sh new file mode 100755 index 000000000000..fcf8cc7ca609 --- /dev/null +++ b/scripts/prow-vale-review.sh @@ -0,0 +1,126 @@ +#!/bin/bash +# This runs Vale on updated files in last commit, checks if the Vale alerts are on new/modified lines, and if so, builds curl request +# for GitHub review comment API. Also checks if a commment already exists before posting. +# To test locally, create a Github personal access token and export a $GITHUB_AUTH_TOKEN environmental variable to use the token + +# Check if jq is installed +hash jq 2>/dev/null || { echo >&2 "Error: jq is not installed"; exit 1; } + +# Set $PULL_NUMBER and $COMMIT_ID for local testing. Otherwise use variables passed by Prow +if [ $# -eq 0 ]; then + COMMIT_ID=$(git log -n 1 --pretty=format:"%H") + PULL_NUMBER=$(curl -s "https://api.github.com/search/issues?q=$COMMIT_ID" | jq '.items[0].number') +else + PULL_NUMBER=$1 + COMMIT_ID=$2 +fi + +FILES=$(git diff --name-only HEAD~1 HEAD --diff-filter=d "*.adoc" ':(exclude)_unused_topics/*' ':(exclude)rest_api/*' ':(exclude)microshift_rest_api/*' ':(exclude)modules/virt-runbook-*' ':(exclude)modules/oc-by-example-content.adoc' ':(exclude)modules/oc-adm-by-example-content.adoc' ':(exclude)monitoring/config-map-reference-for-the-cluster-monitoring-operator.adoc' ':(exclude)modules/microshift-oc-adm-by-example-content.adoc' ':(exclude)modules/microshift-oc-by-example-content.adoc') + +function post_review_comment { + + LINE_NUMBER=$3 + BODY=$1 + FILENAME=$2 + echo "Sending review comment curl request..." + curl -L -X POST -H "Accept: application/vnd.github+json" -H "Authorization: Bearer $GITHUB_AUTH_TOKEN" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/repos/openshift/openshift-docs/pulls/$PULL_NUMBER/comments -d '{"body":"'"$BODY"'","commit_id":"'"$COMMIT_ID"'","path":"'"$FILENAME"'","line":'"$LINE_NUMBER"',"side":"RIGHT"}' + +} + +function get_vale_errors { + echo "Getting the Vale errors and PR comments and filtering out existing comments..." + local vale_json="$1" + local pull_comments_json="$2" + + # jq map and filter to retain only Vale alerts that don't already have a corresponding review comment on the PR + updated_vale_json=$(jq -n --argjson vale "$vale_json" --argjson comments "$pull_comments_json" '$vale | map(select(. as $v | $comments | any(.path == $v.path and .line == $v.line and .body == $v.body) | not))' | jq) + + export updated_vale_json + +} + +# Run vale with the custom template on updated files and determine if a review comment should be posted +for FILE in ${FILES}; +do + # Clean out conditional markup in place and parse for vale errors + sed -i 's/ifdef::.*\|ifndef::.*\|ifeval::.*\|endif::.*/ /' "$FILE" + vale_json=$(vale --minAlertLevel=error --output=.vale/templates/bot-comment-output.tmpl "$FILE" | jq) + + # Check if there are Vale errors before processing the file further. + if [[ "$vale_json" != "[]" ]]; then + echo "Vale errors found in the file..." + + #Check if Vale review comments already exist in the PR + pull_comments_json=$(curl -L -H "Accept: application/vnd.github+json" -H "Authorization: Bearer $GITHUB_AUTH_TOKEN" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/repos/openshift/openshift-docs/pulls/$PULL_NUMBER/comments | jq) + + # If there are existing comments in the response, compare with Vale errors, otherwise proceed with existing Vale errors + if [[ "$pull_comments_json" != "[]" ]]; then + get_vale_errors "$vale_json" "$pull_comments_json" + else + echo "No existing comments found..." + updated_vale_json="$vale_json" + fi + else + echo "No Vale errors found in the file, moving to next file..." + continue # move to next file + fi + + # Following logic checks if the line number is a part of the git diff. If it's not part of the diff it will be discarded. + # We only want to check new/modified content, plus the GitHub API only accepts comments within the diff for the review comments endpoint. + if [[ "$updated_vale_json" == "[]" ]]; then + echo "All Vale alerts already have existing comments, moving to next file..." + continue # move to next file + else + echo "Checking if Vale alerts without existing comments are part of added or modified content..." + fi + + # Iterate through $updated_vale_json and post a comment if required + jq -c '.[]' <<< "$updated_vale_json" | while IFS= read -r object; do + BODY=$(echo "$object" | jq -r '.body') + FILENAME=$(echo "$object" | jq -r '.path') + LINE_NUMBER=$(echo "$object" | jq -r '.line') + + # Check the unified file diff for the alert and file + file_diff=$(git diff --unified=0 --stat --diff-filter=AM HEAD~1 HEAD "${FILENAME}" ':(exclude)_unused_topics/*') + + # Iterate through each line to find the line diff info and check if the alert is in the diff + while read -r line; do + # Check if the line contains the hunk beginning with @@ + if [[ $line =~ @@ ]]; then + + # Valid: + # @@ -35 +31 @@ + # @@ -35 +31,5 @@ + + # Check if there is a comma in the number pairing before @@ + if [[ $line =~ \+.*\,.*\ @@ ]]; then + # There are comma separated numbers before closing @@. Grab the number before the comma as the diff_start_line, after the comma is the added_lines. + added_lines=$(echo "$line" | grep -oP '\d+\s+@@' | grep -oP '\d+') + diff_start_line=$(echo "$line" | awk -F'+' '{print $2}' | awk -F',' '{print $1}') + else + # There are no comma seperated numbers. Consider the number after the plus as diff_start_line with no added lines - this means there's a modification on a single line + added_lines=0 + diff_start_line=$(echo "$line" | grep -oP '\+\d+\s+@@' | grep -oP '\d+') + fi + + # If the last_number is 0, disregard the hunk and move to the next hunk as zero lines were modified (deletions only) + if [ "$diff_start_line" -eq 0 ]; then + continue + fi + + # Check if the LINE_NUMBER falls within the range (diff_start_line) to (diff_start_line + added_lines) + if (( LINE_NUMBER >= diff_start_line && LINE_NUMBER <= diff_start_line + added_lines )); then + + post_review_comment "$BODY" "$FILENAME" "$LINE_NUMBER" + + break # Exit the loop since the alert is within the diff, move on to the next JSON object + else + echo "Vale error alert not part of the file's added/modified content..." + fi + fi + + done <<< "$file_diff" + + done + +done \ No newline at end of file diff --git a/scripts/prow/README.adoc b/scripts/prow/README.adoc new file mode 100644 index 000000000000..70b4cf907e7f --- /dev/null +++ b/scripts/prow/README.adoc @@ -0,0 +1,71 @@ += Creating Prow jobs for openshift-docs branches + +Use the `add-new-prow-config.sh` script to populate the `$HOME/release/ci-operator/config/openshift/openshift-docs` directory with a new Prow job branch configuration. +The script uses the `./openshift-openshift-docs-BRANCH.yaml` template file to create the new job config. +After you create the job config, you run the CI make jobs to create the Prow jobs. +Then, open a pull request against the link:git@github.com:openshift/release.git[openshift/release] repository to make the Prow job live for that branch. + +To add a new job to Prow CI, do the following: + +. Install link:https://podman.io/docs/installation[podman]. + +. Fork and clone the link:git@github.com:openshift/release.git[openshift/release] repository to `$HOME/release`. + +. Create the new branch config by running the `add-new-prow-config.sh` script passing the `$VERSION`, `$BRANCH` and `$DISTROS` variables. +Open a shell prompt in the `openshift-docs/` directory, and run the script passing in the required variables, for example: ++ +[source,terminal] +---- +./scripts/prow/add-new-prow-config.sh 4.15 enterprise-4.15 "openshift-enterprise openshift-rosa openshift-dedicated microshift" +---- ++ +[NOTE] +==== +Quote multiple distros to include them as a single item in the build config. +==== ++ +The script copies the new job YAML to the ci-operator config folder in the `$HOME/release` directory. ++ +[IMPORTANT] +==== +`openshift-rosa` and `openshift-osd` distros should be included in main, current, and future enterprise branch builds only. +When you add a new enterprise branch, remember to remove `openshift-rosa` and `openshift-osd` distros from the most recent enterprise branch. + +For example, when the current version is 4.15, and you create a enterprise-4.16 branch, remove `openshift-rosa` and `openshift-osd` distros from the enterprise-4.15 branch build. +==== + +. Change to the `$HOME/release` directory and verify that the new build config has been added. For example: ++ +[source,text] +---- +$HOME/release/ci-operator/config/openshift/openshift-docs/openshift-openshift-docs-enterprise-4.15.yaml +---- + +. Run the following commands from the root of the `$HOME/release` repository to generate the rest of the Prow build configuration: ++ +[source,terminal] +---- +make prow-config CONTAINER_ENGINE=podman WHAT=openshift/openshift-docs + +make CONTAINER_ENGINE=podman ci-operator-config WHAT=openshift/openshift-docs + +make jobs CONTAINER_ENGINE=podman WHAT=openshift/openshift-docs +---- + +. Open a PR against the link:https://github.com/openshift/release[openshift/release] `master` branch. +Ensure that all Prow CI tests pass. Add a `/pj-rehearse` comment in the pull request to verify the new build. + +. Get an `/lgtm` approval from someone in the openshift-docs link:https://github.com/openshift/release/blob/master/ci-operator/config/openshift/openshift-docs/OWNERS[OWNERS] file. + +. When you want to schedule the job for merge, add a `/pj-rehearse ack` comment to the pull request. +The PR is merged automatically when all required approvals are provided and the PR passes all the required CI jobs. +When the PR is merged, the job goes live on the relevant openshift-docs branch PRs. ++ +[NOTE] +==== +Rebase often on the release branch when you open a pull request. +The repository is very busy and the underlying infrastructure changes daily. +Every time you rebase, rerun the CI make jobs. +==== + +For more information, see: link:https://docs.ci.openshift.org/docs/how-tos/contributing-openshift-release/[Contributing CI configuration to the openshift/release repository] diff --git a/scripts/prow/add-new-prow-config.sh b/scripts/prow/add-new-prow-config.sh new file mode 100755 index 000000000000..478874a714c1 --- /dev/null +++ b/scripts/prow/add-new-prow-config.sh @@ -0,0 +1,47 @@ +#!/bin/bash + +# Script to update Prow configuration + +# Check if required parameters are provided +if [ $# -lt 3 ]; then + echo "Provide values for \$VERSION \$BRANCH \$DISTROS" + exit 1 +fi + +# Assign input parameters to variables +VERSION=$1 +BRANCH=$2 +DISTROS=$3 + +# Export variables for use in subshells +export VERSION BRANCH DISTROS + +# Define folder path +folder="$(git rev-parse --show-toplevel)/scripts/prow" + +# Check if the scripts/prow directory exists +if [ ! -d "$folder" ]; then + echo "The scripts/prow directory does not exist. Make sure your repository structure is correct." + exit 1 +fi + +# Define template and new Prow config paths +template="${folder}/openshift-openshift-docs-BRANCH.yaml" +new_prow_config="${folder}/openshift-openshift-docs-${BRANCH}.yaml" + +# Check if the release directory exists +if [ -d "$HOME/release" ]; then + # Create a new Prow config using environment variables + envsubst < "$template" > "$new_prow_config" + + # Copy the new Prow config to the release directory + cp "$new_prow_config" "$HOME/release/ci-operator/config/openshift/openshift-docs/" + + # Remove the temporary Prow config file + rm "$new_prow_config" + + echo "New Prow job created: $HOME/release/ci-operator/config/openshift/openshift-docs/$(basename "$new_prow_config")" +else + echo "Fork and clone the git@github.com:openshift/release.git repo to $HOME/release and run the script again" + exit 1 +fi diff --git a/scripts/prow/openshift-openshift-docs-BRANCH.yaml b/scripts/prow/openshift-openshift-docs-BRANCH.yaml new file mode 100644 index 000000000000..fbc922b6a473 --- /dev/null +++ b/scripts/prow/openshift-openshift-docs-BRANCH.yaml @@ -0,0 +1,36 @@ +build_root: + image_stream_tag: + name: openshift-docs-asciidoc + namespace: ocp + tag: latest + use_build_cache: true +resources: + '*': + limits: + memory: 4Gi + requests: + cpu: 200m + memory: 400Mi +tests: +- as: deploy-preview + steps: + env: + DISTROS: ${DISTROS} + PREVIEW_SITE: ocpdocs-pr + test: + - ref: openshift-docs-build-docs + - ref: openshift-docs-preview-comment +- as: validate-asciidoc + steps: + env: + BUILD: build.py + DISTROS: ${DISTROS} + VERSION: "${VERSION}" + test: + - ref: openshift-docs-asciidoctor + - ref: openshift-docs-lint-topicmaps + - ref: openshift-docs-portal +zz_generated_metadata: + branch: ${BRANCH} + org: openshift + repo: openshift-docs \ No newline at end of file diff --git a/security/allowing-javascript-access-api-server.adoc b/security/allowing-javascript-access-api-server.adoc deleted file mode 100644 index b53c0c56395b..000000000000 --- a/security/allowing-javascript-access-api-server.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="allowing-javascript-based-access-api-server"] -= Allowing JavaScript-based access to the API server from additional hosts -include::modules/common-attributes.adoc[] -:context: auth-allowed-origins - -toc::[] - -include::modules/auth-allowing-javascript-access-api-server.adoc[leveloffset=+1] diff --git a/security/audit-log-policy-config.adoc b/security/audit-log-policy-config.adoc deleted file mode 100644 index b5140dfc8cd6..000000000000 --- a/security/audit-log-policy-config.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="audit-log-policy-config"] -= Configuring the audit log policy -include::modules/common-attributes.adoc[] -:context: audit-log-policy-config - -toc::[] - -You can control the amount of information that is logged to the API server audit logs by choosing the audit log policy profile to use. - -// About audit log profiles -include::modules/nodes-nodes-audit-config-about.adoc[leveloffset=+1] - -// Configuring the audit log policy -include::modules/nodes-nodes-audit-policy.adoc[leveloffset=+1] diff --git a/security/audit-log-view.adoc b/security/audit-log-view.adoc deleted file mode 100644 index 9efd7bcd2b7f..000000000000 --- a/security/audit-log-view.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="audit-log-view"] -= Viewing audit logs -include::modules/common-attributes.adoc[] -:context: audit-log-view - -toc::[] - -Audit provides a security-relevant chronological set of records documenting the sequence of activities that have affected the system by individual users, administrators, or other components of the system. - -// About the API audit log -include::modules/nodes-nodes-audit-log-basic.adoc[leveloffset=+1] - -// Viewing the audit log -include::modules/nodes-nodes-audit-log-basic-viewing.adoc[leveloffset=+1] - -// Filtering audit logs -include::modules/security-audit-log-filtering.adoc[leveloffset=+1] - -[id="viewing-audit-logs-additional-resources"] -== Additional resources - -* link:https://github.com/kubernetes/apiserver/blob/master/pkg/apis/audit/v1/types.go#L72[API audit log event structure] -* xref:../security/audit-log-policy-config.adoc#audit-log-policy-config[Configuring the audit log policy] diff --git a/security/certificate_types_descriptions/bootstrap-certificates.adoc b/security/certificate_types_descriptions/bootstrap-certificates.adoc deleted file mode 100644 index a483a5d6d02b..000000000000 --- a/security/certificate_types_descriptions/bootstrap-certificates.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="cert-types-bootstrap-certificates"] -= Bootstrap certificates -include::modules/common-attributes.adoc[] -:context: cert-types-bootstrap-certificates - -toc::[] - -== Purpose - -The kubelet, in {product-title} 4 and later, uses the bootstrap certificate located in `/etc/kubernetes/kubeconfig` to initially bootstrap. This is followed by the link:https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/#bootstrap-initialization[bootstrap initialization process] and link:https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/#authorize-kubelet-to-create-csr[authorization of the kubelet to create a CSR]. - -In that process, the kubelet generates a CSR while communicating over the bootstrap channel. The controller manager signs the CSR, resulting in a certificate that the kubelet manages. - -== Management - -These certificates are managed by the system and not the user. - -== Expiration -This bootstrap CA is valid for 10 years. - -The kubelet-managed certificate is valid for one year and rotates automatically at around the 80 percent mark of that one year. - -== Customization - -You cannot customize the bootstrap certificates. diff --git a/security/certificate_types_descriptions/certificate-types-descriptions-index.adoc b/security/certificate_types_descriptions/certificate-types-descriptions-index.adoc deleted file mode 100644 index 56475460e795..000000000000 --- a/security/certificate_types_descriptions/certificate-types-descriptions-index.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="ocp-certificates"] -= Certificate types and descriptions -include::modules/common-attributes.adoc[] -:context: ocp-certificates - -toc::[] - -== Certificate validation - -{product-title} monitors certificates for proper validity, for the cluster certificates it issues and manages. The {product-title} alerting framework has rules to help identify when a certificate issue is about to occur. These rules consist of the following checks: - -* API server client certificate expiration is less than five minutes. diff --git a/security/certificate_types_descriptions/control-plane-certificates.adoc b/security/certificate_types_descriptions/control-plane-certificates.adoc deleted file mode 100644 index fbf52a463012..000000000000 --- a/security/certificate_types_descriptions/control-plane-certificates.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="cert-types-control-plane-certificates"] -= Control plane certificates -include::modules/common-attributes.adoc[] -:context: cert-types-control-plane-certificates - -toc::[] - -== Location - -Control plane certificates are included in these namespaces: - -* openshift-config-managed -* openshift-kube-apiserver -* openshift-kube-apiserver-operator -* openshift-kube-controller-manager -* openshift-kube-controller-manager-operator -* openshift-kube-scheduler - -== Management - -Control plane certificates are managed by the system and rotated automatically. - -In the rare case that your control plane certificates expired, see xref:../../backup_and_restore/disaster_recovery/scenario-3-expired-certs.adoc#dr-recovering-expired-certs[Recovering from expired control plane certificates] diff --git a/security/certificate_types_descriptions/etcd-certificates.adoc b/security/certificate_types_descriptions/etcd-certificates.adoc deleted file mode 100644 index c21f6727d161..000000000000 --- a/security/certificate_types_descriptions/etcd-certificates.adoc +++ /dev/null @@ -1,32 +0,0 @@ -[id="cert-types-etcd-certificates"] -= etcd certificates -include::modules/common-attributes.adoc[] -:context: cert-types-etcd-certificates - -toc::[] - -== Purpose - -etcd certificates are signed by the etcd-signer; they come from a certificate authority (CA) that is generated by the bootstrap process. - -== Expiration - -The CA certificates are valid for 10 years. The peer, client, and server certificates are valid for three years. - -== Management - -These certificates are managed by the system and not the user. - -== Services - -etcd certificates are used for encrypted communication between etcd member peers, as well as encrypted client traffic. The following certificates are generated and used by etcd and other processes that communicate with etcd: - -* Peer certificates: Used for communication between etcd members. -* Client certificates: Used for encrypted server-client communication. Client certificates are currently used by the API server only, and no other service should connect to etcd directly except for the proxy. Client secrets (`etcd-client`, `etcd-metric-client`, `etcd-metric-signer`, and `etcd-signer`) are added to the `openshift-config`, `openshift-monitoring`, and `openshift-kube-apiserver` namespaces. -* Server certificates: Used by the etcd server for authenticating client requests. -* Metric certificates: All metric consumers connect to proxy with metric-client certificates. - -[discrete] -=== Additional resources - -* xref:../../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[Restoring to a previous cluster state] diff --git a/security/certificate_types_descriptions/images b/security/certificate_types_descriptions/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/security/certificate_types_descriptions/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/security/certificate_types_descriptions/ingress-certificates.adoc b/security/certificate_types_descriptions/ingress-certificates.adoc deleted file mode 100644 index 448b7f74758a..000000000000 --- a/security/certificate_types_descriptions/ingress-certificates.adoc +++ /dev/null @@ -1,91 +0,0 @@ -[id="cert-types-ingress-certificates"] -= Ingress certificates -include::modules/common-attributes.adoc[] -:context: cert-types-ingress-certificates - -toc::[] - -== Purpose - -The Ingress Operator uses certificates for: - -* Securing access to metrics for Prometheus. -* Securing access to routes. - -== Location - -To secure access to Ingress Operator and Ingress Controller metrics, the Ingress Operator uses service serving certificates. The Operator requests a certificate from the `service-ca` controller for its own metrics, and the `service-ca` controller puts the certificate in a secret named `metrics-tls` in the `openshift-ingress-operator` namespace. Additionally, the Ingress Operator requests a certificate for each Ingress Controller, and the `service-ca` controller puts the certificate in a secret named `router-metrics-certs-<name>`, where `<name>` is the name of the Ingress Controller, in the `openshift-ingress` namespace. - -Each Ingress Controller has a default certificate that it uses for secured routes that do not specify their own certificates. Unless you specify a custom certificate, the Operator uses a self-signed certificate by default. The Operator uses its own self-signed signing certificate to sign any default certificate that it generates. The Operator generates this signing certificate and puts it in a secret named `router-ca` in the `openshift-ingress-operator` namespace. When the Operator generates a default certificate, it puts the default certificate in a secret named `router-certs-<name>` (where `<name>` is the name of the Ingress Controller) in the `openshift-ingress` namespace. - -[WARNING] -==== -The Ingress Operator generates a default certificate for an Ingress Controller to serve as a placeholder until you configure a custom default certificate. Do not use Operator-generated default certificates in production clusters. -==== - -== Workflow - -.Custom certificate workflow - -image::custom_4.5.svg[custom ingress certificate workflow] - - -.Default certificate workflow - -image::default_4.5.svg[default ingress certificate workflow] - -image:darkcircle-0.png[20,20] An empty `defaultCertificate` field causes the Ingress Operator to use its self-signed CA to generate a serving certificate for the specified domain. - -image:darkcircle-1.png[20,20] The default CA certificate and key generated by the Ingress Operator. Used to sign Operator-generated default serving certificates. - -image:darkcircle-2.png[20,20] In the default workflow, the wildcard default serving certificate, created by the Ingress Operator and signed using the generated default CA certificate. In the custom workflow, this is the user-provided certificate. - -image:darkcircle-3.png[20,20] The router deployment. Uses the certificate in `secrets/router-certs-default` as its default front-end server certificate. - -image:darkcircle-4.png[20,20] In the default workflow, the contents of the wildcard default serving certificate (public and private parts) are copied here to enable OAuth integration. In the custom workflow, this is the user-provided certificate. - -image:darkcircle-5.png[20,20] The public (certificate) part of the default serving certificate. Replaces the `configmaps/router-ca` resource. - -image:darkcircle-6.png[20,20] The user updates the cluster proxy configuration with the CA certificate that signed the `ingresscontroller` serving certificate. This enables components like `auth`, `console`, and the registry to trust the serving certificate. - -image:darkcircle-7.png[20,20] The cluster-wide trusted CA bundle containing the combined {op-system-first} and user-provided CA bundles or an {op-system}-only bundle if a user bundle is not provided. - -image:darkcircle-8.png[20,20] The custom CA certificate bundle, which instructs other components (for example, `auth` and `console`) to trust an `ingresscontroller` configured with a custom certificate. - -image:darkcircle-9.png[20,20] The `trustedCA` field is used to reference the user-provided CA bundle. - -image:darkcircle-10.png[20,20] The Cluster Network Operator injects the trusted CA bundle into the `proxy-ca` config map. - -image:darkcircle-11.png[20,20] {product-title} {product-version} and newer use `default-ingress-cert`. - -== Expiration - -The expiration terms for the Ingress Operator's certificates are as follows: - -* The expiration date for metrics certificates that the `service-ca` controller creates is two years after the date of creation. -* The expiration date for the Operator's signing certificate is two years after the date of creation. -* The expiration date for default certificates that the Operator generates is two years after the date of creation. - -You cannot specify custom expiration terms on certificates that the Ingress Operator or `service-ca` controller creates. - -You cannot specify expiration terms when installing {product-title} for certificates that the Ingress Operator or `service-ca` controller creates. - -== Services - -Prometheus uses the certificates that secure metrics. - -The Ingress Operator uses its signing certificate to sign default certificates that it generates for Ingress Controllers for which you do not set custom default certificates. - -Cluster components that use secured routes may use the default Ingress Controller's default certificate. - -Ingress to the cluster via a secured route uses the default certificate of the Ingress Controller by which the route is accessed unless the route specifies its own certificate. - -== Management - -Ingress certificates are managed by the user. See xref:../../security/certificates/replacing-default-ingress-certificate.adoc#replacing-default-ingress[Replacing the default ingress certificate] for more information. - -== Renewal - -The `service-ca` controller automatically rotates the certificates that it issues. However, it is possible to use `oc delete secret <secret>` to manually rotate service serving certificates. - -The Ingress Operator does not rotate its own signing certificate or the default certificates that it generates. Operator-generated default certificates are intended as placeholders for custom default certificates that you configure. diff --git a/security/certificate_types_descriptions/modules b/security/certificate_types_descriptions/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/security/certificate_types_descriptions/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/security/certificate_types_descriptions/monitoring-and-cluster-logging-operator-component-certificates.adoc b/security/certificate_types_descriptions/monitoring-and-cluster-logging-operator-component-certificates.adoc deleted file mode 100644 index f5ca461b3cf4..000000000000 --- a/security/certificate_types_descriptions/monitoring-and-cluster-logging-operator-component-certificates.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="cert-types-monitoring-and-cluster-logging-operator-component-certificates"] -= Monitoring and Cluster Logging Operator component certificates -include::modules/common-attributes.adoc[] -:context: cert-types-monitoring-and-cluster-logging-operator-component-certificates - -toc::[] - -== Expiration - -Monitoring components secure their traffic with service CA certificates. These certificates are valid for 2 years and are replaced automatically on rotation of the service CA, which is every 13 months. - -If the certificate lives in the `openshift-monitoring` or `openshift-logging` namespace, it is system managed and rotated automatically. - -== Management - -These certificates are managed by the system and not the user. diff --git a/security/certificate_types_descriptions/node-certificates.adoc b/security/certificate_types_descriptions/node-certificates.adoc deleted file mode 100644 index a6519ee0ad2d..000000000000 --- a/security/certificate_types_descriptions/node-certificates.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="cert-types-node-certificates"] -= Node certificates -include::modules/common-attributes.adoc[] -:context: cert-types-node-certificates - -toc::[] - -== Purpose - -Node certificates are signed by the cluster; they come from a certificate authority (CA) that is generated by the bootstrap process. Once the cluster is installed, the node certificates are auto-rotated. - -== Management - -These certificates are managed by the system and not the user. - -[discrete] -=== Additional resources - -* xref:../../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-working[Working with nodes] diff --git a/security/certificate_types_descriptions/olm-certificates.adoc b/security/certificate_types_descriptions/olm-certificates.adoc deleted file mode 100644 index a6229bcbf4d8..000000000000 --- a/security/certificate_types_descriptions/olm-certificates.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="cert-types-olm-certificates"] -= OLM certificates -include::modules/common-attributes.adoc[] -:context: cert-types-olm-certificates - -toc::[] - -== Management - -All certificates for OpenShift Lifecycle Manager (OLM) components (`olm-operator`, `catalog-operator`, `packageserver`, and `marketplace-operator`) are managed by the system. - -When installing Operators that include webhooks or API services in their `ClusterServiceVersion` (CSV) object, OLM creates and rotates the certificates for these resources. Certificates for resources in the `openshift-operator-lifecycle-manager` namespace are managed by OLM. - -OLM will not update the certificates of Operators that it manages in proxy environments. These certificates must be managed by the user using the subscription config. diff --git a/security/certificate_types_descriptions/proxy-certificates.adoc b/security/certificate_types_descriptions/proxy-certificates.adoc deleted file mode 100644 index 69a8a244ebc3..000000000000 --- a/security/certificate_types_descriptions/proxy-certificates.adoc +++ /dev/null @@ -1,129 +0,0 @@ -[id="cert-types-proxy-certificates"] -= Proxy certificates -include::modules/common-attributes.adoc[] -:context: cert-types-proxy-certificates - -toc::[] - -== Purpose - -Proxy certificates allow users to specify one or more custom certificate authority (CA) certificates used by platform components when making egress connections. - -The `trustedCA` field of the Proxy object is a reference to a config map that contains a user-provided trusted certificate authority (CA) bundle. This bundle is merged with the {op-system-first} trust bundle and injected into the trust store of platform components that make egress HTTPS calls. For example, `image-registry-operator` calls an external image registry to download images. If `trustedCA` is not specified, only the {op-system} trust bundle is used for proxied HTTPS connections. Provide custom CA certificates to the {op-system} trust bundle if you want to use your own certificate infrastructure. - -The `trustedCA` field should only be consumed by a proxy validator. The validator is responsible for reading the certificate bundle from required key `ca-bundle.crt` and copying it to a config map named `trusted-ca-bundle` in the `openshift-config-managed` namespace. The namespace for the config map referenced by `trustedCA` is `openshift-config`: - -[source,yaml] ----- -apiVersion: v1 -kind: ConfigMap -metadata: - name: user-ca-bundle - namespace: openshift-config -data: - ca-bundle.crt: | - -----BEGIN CERTIFICATE----- - Custom CA certificate bundle. - -----END CERTIFICATE----- ----- - -[discrete] -=== Additional resources - -* xref:../../networking/enable-cluster-wide-proxy.adoc#enable-cluster-wide-proxy[Configuring the cluster-wide proxy] - -== Managing proxy certificates during installation - -The `additionalTrustBundle` value of the installer configuration is used to specify any proxy-trusted CA certificates during installation. For example: - -[source,terminal] ----- -$ cat install-config.yaml ----- - -.Example output -[source,terminal] ----- -... -proxy: - httpProxy: http://<https://username:password@proxy.example.com:123/> - httpsProxy: https://<https://username:password@proxy.example.com:123/> - noProxy: <123.example.com,10.88.0.0/16> -additionalTrustBundle: | - -----BEGIN CERTIFICATE----- - <MY_HTTPS_PROXY_TRUSTED_CA_CERT> - -----END CERTIFICATE----- -... ----- - -== Location - -The user-provided trust bundle is represented as a config map. The config map is mounted into the file system of platform components that make egress HTTPS calls. Typically, Operators mount the config map to `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem`, but this is not required by the proxy. A proxy can modify or inspect the HTTPS connection. In either case, the proxy must generate and sign a new certificate for the connection. - -Complete proxy support means connecting to the specified proxy and trusting any signatures it has generated. Therefore, it is necessary to let the user specify a trusted root, such that any certificate chain connected to that trusted root is also trusted. - -If using the RHCOS trust bundle, place CA certificates in `/etc/pki/ca-trust/source/anchors`. - -See link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-shared-system-certificates_security-hardening[Using shared system certificates] in the Red Hat Enterprise Linux documentation for more information. - -== Expiration - -The user sets the expiration term of the user-provided trust bundle. - -The default expiration term is defined by the CA certificate itself. It is up to the CA administrator to configure this for the certificate before it can be used by {product-title} or {op-system}. - -[NOTE] -==== -Red Hat does not monitor for when CAs expire. However, due to the long life of CAs, this is generally not an issue. However, you might need to periodically update the trust bundle. -==== - -== Services - -By default, all platform components that make egress HTTPS calls will use the {op-system} trust bundle. If `trustedCA` is defined, it will also be used. - -Any service that is running on the {op-system} node is able to use the trust bundle of the node. - -== Management - -These certificates are managed by the system and not the user. - -== Customization - -Updating the user-provided trust bundle consists of either: - -* updating the PEM-encoded certificates in the config map referenced by `trustedCA,` or -* creating a config map in the namespace `openshift-config` that contains the new trust bundle and updating `trustedCA` to reference the name of the new config map. - -The mechanism for writing CA certificates to the {op-system} trust bundle is exactly the same as writing any other file to {op-system}, which is done through the use of machine configs. When the Machine Config Operator (MCO) applies the new machine config that contains the new CA certificates, the node is rebooted. During the next boot, the service `coreos-update-ca-trust.service` runs on the {op-system} nodes, which automatically update the trust bundle with the new CA certificates. For example: - -[source,yaml] ----- -apiVersion: machineconfiguration.openshift.io/v1 -kind: MachineConfig -metadata: - labels: - machineconfiguration.openshift.io/role: worker - name: 50-examplecorp-ca-cert -spec: - config: - ignition: - version: 3.1.0 - storage: - files: - - contents: - source: data:text/plain;charset=utf-8;base64,LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVORENDQXh5Z0F3SUJBZ0lKQU51bkkwRDY2MmNuTUEwR0NTcUdTSWIzRFFFQkN3VUFNSUdsTVFzd0NRWUQKV1FRR0V3SlZVekVYTUJVR0ExVUVDQXdPVG05eWRHZ2dRMkZ5YjJ4cGJtRXhFREFPQmdOVkJBY01CMUpoYkdWcApBMmd4RmpBVUJnTlZCQW9NRFZKbFpDQklZWFFzSUVsdVl5NHhFekFSQmdOVkJBc01DbEpsWkNCSVlYUWdTVlF4Ckh6QVpCZ05WQkFNTUVsSmxaQ0JJWVhRZ1NWUWdVbTl2ZENCRFFURWhNQjhHQ1NxR1NJYjNEUUVKQVJZU2FXNW0KWGpDQnBURUxNQWtHQTFVRUJoTUNWVk14RnpBVkJnTlZCQWdNRGs1dmNuUm9JRU5oY205c2FXNWhNUkF3RGdZRApXUVFIREFkU1lXeGxhV2RvTVJZd0ZBWURWUVFLREExU1pXUWdTR0YwTENCSmJtTXVNUk13RVFZRFZRUUxEQXBTCkFXUWdTR0YwSUVsVU1Sc3dHUVlEVlFRRERCSlNaV1FnU0dGMElFbFVJRkp2YjNRZ1EwRXhJVEFmQmdrcWhraUcKMHcwQkNRRVdFbWx1Wm05elpXTkFjbVZrYUdGMExtTnZiVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUApCRENDQVFvQ2dnRUJBTFF0OU9KUWg2R0M1TFQxZzgwcU5oMHU1MEJRNHNaL3laOGFFVHh0KzVsblBWWDZNSEt6CmQvaTdsRHFUZlRjZkxMMm55VUJkMmZRRGsxQjBmeHJza2hHSUlaM2lmUDFQczRsdFRrdjhoUlNvYjNWdE5xU28KSHhrS2Z2RDJQS2pUUHhEUFdZeXJ1eTlpckxaaW9NZmZpM2kvZ0N1dDBaV3RBeU8zTVZINXFXRi9lbkt3Z1BFUwpZOXBvK1RkQ3ZSQi9SVU9iQmFNNzYxRWNyTFNNMUdxSE51ZVNmcW5obzNBakxRNmRCblBXbG82MzhabTFWZWJLCkNFTHloa0xXTVNGa0t3RG1uZTBqUTAyWTRnMDc1dkNLdkNzQ0F3RUFBYU5qTUdFd0hRWURWUjBPQkJZRUZIN1IKNXlDK1VlaElJUGV1TDhacXczUHpiZ2NaTUI4R0ExVWRJd1FZTUJhQUZIN1I0eUMrVWVoSUlQZXVMOFpxdzNQegpjZ2NaTUE4R0ExVWRFd0VCL3dRRk1BTUJBZjh3RGdZRFZSMFBBUUgvQkFRREFnR0dNQTBHQ1NxR1NJYjNEUUVCCkR3VUFBNElCQVFCRE52RDJWbTlzQTVBOUFsT0pSOCtlbjVYejloWGN4SkI1cGh4Y1pROGpGb0cwNFZzaHZkMGUKTUVuVXJNY2ZGZ0laNG5qTUtUUUNNNFpGVVBBaWV5THg0ZjUySHVEb3BwM2U1SnlJTWZXK0tGY05JcEt3Q3NhawpwU29LdElVT3NVSks3cUJWWnhjckl5ZVFWMnFjWU9lWmh0UzV3QnFJd09BaEZ3bENFVDdaZTU4UUhtUzQ4c2xqCjVlVGtSaml2QWxFeHJGektjbGpDNGF4S1Fsbk92VkF6eitHbTMyVTB4UEJGNEJ5ZVBWeENKVUh3MVRzeVRtZWwKU3hORXA3eUhvWGN3bitmWG5hK3Q1SldoMWd4VVp0eTMKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo= - mode: 0644 - overwrite: true - path: /etc/pki/ca-trust/source/anchors/examplecorp-ca.crt ----- - -The trust store of machines must also support updating the trust store of nodes. - -== Renewal - -There are no Operators that can auto-renew certificates on the {op-system} nodes. - -[NOTE] -==== -Red Hat does not monitor for when CAs expire. However, due to the long life of CAs, this is generally not an issue. However, you might need to periodically update the trust bundle. -==== diff --git a/security/certificate_types_descriptions/service-ca-certificates.adoc b/security/certificate_types_descriptions/service-ca-certificates.adoc deleted file mode 100644 index a6fd8131eb55..000000000000 --- a/security/certificate_types_descriptions/service-ca-certificates.adoc +++ /dev/null @@ -1,61 +0,0 @@ -[id="cert-types-service-ca-certificates"] -= Service CA certificates -include::modules/common-attributes.adoc[] -:context: cert-types-service-ca-certificates - -toc::[] - -== Purpose - -`service-ca` is an Operator that creates a self-signed CA when an {product-title} cluster is deployed. - -== Expiration - -A custom expiration term is not supported. The self-signed CA is stored in a secret with qualified name `service-ca/signing-key` in fields `tls.crt` (certificate(s)), `tls.key` (private key), and `ca-bundle.crt` (CA bundle). - -Other services can request a service serving certificate by annotating a service resource with `service.beta.openshift.io/serving-cert-secret-name: <secret name>`. In response, the Operator generates a new certificate, as `tls.crt`, and private key, as `tls.key` to the named secret. The certificate is valid for two years. - -Other services can request that the CA bundle for the service CA be injected into API service or config map resources by annotating with `service.beta.openshift.io/inject-cabundle: true` to support validating certificates generated from the service CA. In response, the Operator writes its current CA bundle to the `CABundle` field of an API service or as `service-ca.crt` to a config map. - -As of {product-title} 4.3.5, automated rotation is supported and is backported to some 4.2.z and 4.3.z releases. For any release supporting automated rotation, the service CA is valid for 26 months and is automatically refreshed when there is less than 13 months validity left. If necessary, you can manually refresh the service CA. - -The service CA expiration of 26 months is longer than the expected upgrade interval for a supported {product-title} cluster, such that non-control plane consumers of service CA certificates will be refreshed after CA rotation and prior to the expiration of the pre-rotation CA. - -[WARNING] -==== -A manually-rotated service CA does not maintain trust with the previous service CA. You might experience a temporary service disruption until the Pods in the cluster are restarted, which ensures that Pods are using service serving certificates issued by the new service CA. -==== - -== Management - -These certificates are managed by the system and not the user. - -== Services - -Services that use service CA certificates include: - -* cluster-autoscaler-operator -* cluster-monitoring-operator -* cluster-authentication-operator -* cluster-image-registry-operator -* cluster-ingress-operator -* cluster-kube-apiserver-operator -* cluster-kube-controller-manager-operator -* cluster-kube-scheduler-operator -* cluster-networking-operator -* cluster-openshift-apiserver-operator -* cluster-openshift-controller-manager-operator -* cluster-samples-operator -* machine-config-operator -* console-operator -* insights-operator -* machine-api-operator -* operator-lifecycle-manager - -This is not a comprehensive list. - -[discrete] -=== Additional resources - -* xref:../../security/certificates/service-serving-certificate.adoc#add-service-serving[Manually rotate service serving certificates] -* xref:../../security/certificates/service-serving-certificate.adoc#add-service-serving[Securing service traffic using service serving certificate secrets] diff --git a/security/certificate_types_descriptions/user-provided-certificates-for-api-server.adoc b/security/certificate_types_descriptions/user-provided-certificates-for-api-server.adoc deleted file mode 100644 index 06d8109f9843..000000000000 --- a/security/certificate_types_descriptions/user-provided-certificates-for-api-server.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[id="cert-types-user-provided-certificates-for-the-api-server"] -= User-provided certificates for the API server -include::modules/common-attributes.adoc[] -:context: cert-types-user-provided-certificates-for-the-api-server - -toc::[] - -== Purpose - -The API server is accessible by clients external to the cluster at `api.<cluster_name>.<base_domain>`. You might want clients to access the API server at a different host name or without the need to distribute the cluster-managed certificate authority (CA) certificates to the clients. The administrator must set a custom default certificate to be used by the API server when serving content. - -== Location - -The user-provided certificates must be provided in a `kubernetes.io/tls` type `Secret` in the `openshift-config` namespace. Update the API server cluster configuration, the `apiserver/cluster` resource, to enable the use of the user-provided certificate. - -== Management - -User-provided certificates are managed by the user. - -== Expiration - -API server client certificate expiration is less than five minutes. - -User-provided certificates are managed by the user. - -== Customization - -Update the secret containing the user-managed certificate as needed. - -[discrete] -=== Additional resources - -* xref:../../security/certificates/api-server.adoc#api-server-certificates[Adding API server certificates] diff --git a/security/certificate_types_descriptions/user-provided-certificates-for-default-ingress.adoc b/security/certificate_types_descriptions/user-provided-certificates-for-default-ingress.adoc deleted file mode 100644 index c15f5814f157..000000000000 --- a/security/certificate_types_descriptions/user-provided-certificates-for-default-ingress.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="cert-types-user-provided-certificates-for-default-ingress"] -= User-provided certificates for default ingress -include::modules/common-attributes.adoc[] -:context: cert-types-user-provided-certificates-for-default-ingress - -toc::[] - -== Purpose - -Applications are usually exposed at `<route_name>.apps.<cluster_name>.<base_domain>`. The `<cluster_name>` and `<base_domain>` come from the installation config file. `<route_name>` is the host field of the route, if specified, or the route name. For example, `hello-openshift-default.apps.username.devcluster.openshift.com`. `hello-openshift` is the name of the route and the route is in the default namespace. You might want clients to access the applications without the need to distribute the cluster-managed CA certificates to the clients. The administrator must set a custom default certificate when serving application content. - -[WARNING] -==== -The Ingress Operator generates a default certificate for an Ingress Controller to serve as a placeholder until you configure a custom default certificate. Do not use operator-generated default certificates in production clusters. -==== - -== Location - -The user-provided certificates must be provided in a `tls` type `Secret` resource in the `openshift-ingress` namespace. Update the `IngressController` CR in the `openshift-ingress-operator` namespace to enable the use of the user-provided certificate. For more information on this process, see xref:../../networking/ingress-operator.adoc#nw-ingress-setting-a-custom-default-certificate_configuring-ingress[Setting a custom default certificate]. - -== Management - -User-provided certificates are managed by the user. - -== Expiration - -User-provided certificates are managed by the user. - -== Services - -Applications deployed on the cluster use user-provided certificates for default ingress. - -== Customization - -Update the secret containing the user-managed certificate as needed. - -[discrete] -=== Additional resources - -* xref:../../security/certificates/replacing-default-ingress-certificate.adoc#replacing-default-ingress[Replacing the default ingress certificate] diff --git a/security/certificates/api-server.adoc b/security/certificates/api-server.adoc deleted file mode 100644 index 5c6603814902..000000000000 --- a/security/certificates/api-server.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="api-server-certificates"] -= Adding API server certificates -include::modules/common-attributes.adoc[] -:context: api-server-certificates - -toc::[] - -The default API server certificate is issued by an internal {product-title} -cluster CA. Clients outside of the cluster will not be able to verify the -API server's certificate by default. This certificate can be replaced -by one that is issued by a CA that clients trust. - -include::modules/customize-certificates-api-add-named.adoc[leveloffset=+1] diff --git a/security/certificates/replacing-default-ingress-certificate.adoc b/security/certificates/replacing-default-ingress-certificate.adoc deleted file mode 100644 index 6f24f8ac7006..000000000000 --- a/security/certificates/replacing-default-ingress-certificate.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="replacing-default-ingress"] -= Replacing the default ingress certificate -include::modules/common-attributes.adoc[] -:context: replacing-default-ingress - -toc::[] - -include::modules/customize-certificates-understanding-default-router.adoc[leveloffset=+1] - -include::modules/customize-certificates-replace-default-router.adoc[leveloffset=+1] diff --git a/security/certificates/service-serving-certificate.adoc b/security/certificates/service-serving-certificate.adoc deleted file mode 100644 index 4bf2e2a775d8..000000000000 --- a/security/certificates/service-serving-certificate.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="add-service-serving"] -= Securing service traffic using service serving certificate secrets -include::modules/common-attributes.adoc[] -:context: service-serving-certificate - -toc::[] - -include::modules/customize-certificates-understanding-service-serving.adoc[leveloffset=+1] - -include::modules/customize-certificates-add-service-serving.adoc[leveloffset=+1] - -include::modules/customize-certificates-add-service-serving-configmap.adoc[leveloffset=+1] - -include::modules/customize-certificates-add-service-serving-apiservice.adoc[leveloffset=+1] - -include::modules/customize-certificates-add-service-serving-crd.adoc[leveloffset=+1] - -include::modules/customize-certificates-add-service-serving-mutating-webhook.adoc[leveloffset=+1] - -include::modules/customize-certificates-add-service-serving-validating-webhook.adoc[leveloffset=+1] - -include::modules/customize-certificates-rotate-service-serving.adoc[leveloffset=+1] - -include::modules/customize-certificates-manually-rotate-service-ca.adoc[leveloffset=+1] diff --git a/security/compliance_operator/compliance-operator-advanced.adoc b/security/compliance_operator/compliance-operator-advanced.adoc deleted file mode 100644 index c0b8d5a76273..000000000000 --- a/security/compliance_operator/compliance-operator-advanced.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="compliance-operator-advanced"] -= Performing advanced Compliance Operator tasks -include::modules/common-attributes.adoc[] -:context: compliance-advanced - -toc::[] - -The Compliance Operator includes options for advanced users for the purpose of debugging or integration with existing tooling. - -include::modules/compliance-objects.adoc[leveloffset=+1] - -include::modules/compliance-raw-tailored.adoc[leveloffset=+1] - -include::modules/compliance-rescan.adoc[leveloffset=+1] - -include::modules/compliance-custom-storage.adoc[leveloffset=+1] - -include::modules/compliance-apply-remediations-from-scans.adoc[leveloffset=+1] - -include::modules/compliance-auto-update-remediations.adoc[leveloffset=+1] diff --git a/security/compliance_operator/compliance-operator-installation.adoc b/security/compliance_operator/compliance-operator-installation.adoc deleted file mode 100644 index 4b07273a0b05..000000000000 --- a/security/compliance_operator/compliance-operator-installation.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="compliance-operator-installation"] -= Installing the Compliance Operator -include::modules/common-attributes.adoc[] -:context: compliance-operator-installation - -toc::[] - -Before you can use the Compliance Operator, you must ensure it is deployed in the cluster. - -include::modules/compliance-operator-console-installation.adoc[leveloffset=+1] - -include::modules/compliance-operator-cli-installation.adoc[leveloffset=+1] diff --git a/security/compliance_operator/compliance-operator-manage.adoc b/security/compliance_operator/compliance-operator-manage.adoc deleted file mode 100644 index 335ae0c4572a..000000000000 --- a/security/compliance_operator/compliance-operator-manage.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="compliance-operator-understanding"] -= Managing the Compliance Operator -include::modules/common-attributes.adoc[] -:context: managing-compliance - -toc::[] - -This section describes the lifecycle of security content, including how to use an updated version of compliance content and how to create a custom `ProfileBundle` object. - -include::modules/compliance-update.adoc[leveloffset=+1] - -include::modules/compliance-imagestreams.adoc[leveloffset=+1] - -include::modules/compliance-profilebundle.adoc[leveloffset=+1] - -[id="additional-resources_managing-the-compliance-operator"] -== Additional resources - -* The Compliance Operator is supported in a restricted network environment. For more information, see xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks]. diff --git a/security/compliance_operator/compliance-operator-raw-results.adoc b/security/compliance_operator/compliance-operator-raw-results.adoc deleted file mode 100644 index 8c9bc9d67698..000000000000 --- a/security/compliance_operator/compliance-operator-raw-results.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[id="compliance-operator-raw-results"] -= Retrieving Compliance Operator raw results -include::modules/common-attributes.adoc[] -:context: compliance-raw-results - -When proving compliance for your {product-title} cluster, you might need to provide the scan results for auditing purposes. - -include::modules/compliance-results.adoc[leveloffset=+1] diff --git a/security/compliance_operator/compliance-operator-remediation.adoc b/security/compliance_operator/compliance-operator-remediation.adoc deleted file mode 100644 index 2cfbcd19f80c..000000000000 --- a/security/compliance_operator/compliance-operator-remediation.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="compliance-operator-remediation"] -= Managing Compliance Operator remediation -include::modules/common-attributes.adoc[] -:context: compliance-remediation - -toc::[] - -Each `ComplianceCheckResult` represents a result of one compliance rule check. If the rule can be remediated automatically, a `ComplianceRemediation` object with the same name, owned by the `ComplianceCheckResult` is created. Unless requested, the remediations are not applied automatically, which gives an {product-title} administrator the opportunity to review what the remediation does and only apply a remediation once it has been verified. - -include::modules/compliance-review.adoc[leveloffset=+1] - -include::modules/compliance-applying.adoc[leveloffset=+1] - -include::modules/compliance-manual.adoc[leveloffset=+1] - -include::modules/compliance-updating.adoc[leveloffset=+1] - -include::modules/compliance-unapplying.adoc[leveloffset=+1] - -include::modules/compliance-inconsistent.adoc[leveloffset=+1] - -include::modules/compliance-filtering-failed-results.adoc[leveloffset=+1] diff --git a/security/compliance_operator/compliance-operator-tailor.adoc b/security/compliance_operator/compliance-operator-tailor.adoc deleted file mode 100644 index 12d029680251..000000000000 --- a/security/compliance_operator/compliance-operator-tailor.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="compliance-operator-tailor"] -= Tailoring the Compliance Operator -include::modules/common-attributes.adoc[] -:context: compliance-tailor - -While the Compliance Operator comes with ready-to-use profiles, they must be modified to fit the organizations’ needs and requirements. The process of modifying a profile is called _tailoring_. - -The Compliance Operator provides an object to easily tailor profiles called a `TailoredProfile`. This assumes that you are extending a pre-existing profile, and allows you to enable and disable rules and values which come from the `ProfileBundle`. - -[NOTE] -==== -You will only be able to use rules and variables that are available as part of the `ProfileBundle` that the profile you want to extend belongs to. -==== - -include::modules/compliance-tailored-profiles.adoc[leveloffset=+1] diff --git a/security/compliance_operator/compliance-operator-troubleshooting.adoc b/security/compliance_operator/compliance-operator-troubleshooting.adoc deleted file mode 100644 index d9a9ab172286..000000000000 --- a/security/compliance_operator/compliance-operator-troubleshooting.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id="compliance-operator-troubleshooting"] -= Troubleshooting the Compliance Operator -include::modules/common-attributes.adoc[] -:context: compliance-troubleshooting - -toc::[] - -This section describes how to troubleshoot the Compliance Operator. The information can be useful either to diagnose a problem or provide information in a bug report. Some general tips: - -* The Compliance Operator emits Kubernetes events when something important happens. You can either view all events in the cluster using the command: -+ -[source,terminal] ----- - $ oc get events -n openshift-compliance ----- -+ -Or view events for an object like a scan using the command: -+ -[source,terminal] ----- -$ oc describe compliancescan/<scan_name> ----- - -* The Compliance Operator consists of several controllers, approximately one per API object. It could be useful to filter only those controllers that correspond to the API object having issues. If a `ComplianceRemediation` cannot be applied, view the messages from the `remediationctrl` controller. You can filter the messages from a single controller by parsing with `jq`: -+ -[source,terminal] ----- -$ oc logs compliance-operator-775d7bddbd-gj58f | jq -c 'select(.logger == "profilebundlectrl")' ----- - -* The timestamps are logged as seconds since UNIX epoch in UTC. To convert them to a human-readable date, use `date -d @timestamp --utc`, for example: -+ -[source,terminal] ----- -$ date -d @1596184628.955853 --utc ----- - -* Many custom resources, most importantly `ComplianceSuite` and `ScanSetting`, allow the `debug` option to be set. Enabling this option increases verbosity of the OpenSCAP scanner pods, as well as some other helper pods. - -* If a single rule is passing or failing unexpectedly, it could be helpful to run a single scan or a suite with only that rule to find the rule ID from the corresponding `ComplianceCheckResult` object and use it as the `rule` attribute value in a `Scan` CR. Then, together with the `debug` option enabled, the `scanner` container logs in the scanner pod would show the raw OpenSCAP logs. - -include::modules/compliance-anatomy.adoc[leveloffset=+1] - -include::modules/support.adoc[leveloffset=+1] diff --git a/security/compliance_operator/compliance-operator-understanding.adoc b/security/compliance_operator/compliance-operator-understanding.adoc deleted file mode 100644 index a77065fa5960..000000000000 --- a/security/compliance_operator/compliance-operator-understanding.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="understanding-compliance-operator"] -= Understanding the Compliance Operator -include::modules/common-attributes.adoc[] -:context: understanding-compliance - -toc::[] - -The Compliance Operator lets {product-title} administrators describe the desired compliance state of a cluster and provides them with an overview of gaps and ways to remediate them. The Compliance Operator assesses compliance of both the Kubernetes API resources of {product-title}, as well as the nodes running the cluster. The Compliance Operator uses OpenSCAP, a NIST-certified tool, to scan and enforce security policies provided by the content. - -[IMPORTANT] -==== -The Compliance Operator is available for {op-system-first} deployments only. -==== - -include::modules/compliance-profiles.adoc[leveloffset=+1] diff --git a/security/compliance_operator/compliance-scans.adoc b/security/compliance_operator/compliance-scans.adoc deleted file mode 100644 index 4bf1ee69783c..000000000000 --- a/security/compliance_operator/compliance-scans.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="compliance-operator-scans"] -= Compliance Operator scans -include::modules/common-attributes.adoc[] -:context: compliance-operator-scans - -toc::[] - -The `ScanSetting` and `ScanSettingBinding` APIs are recommended to run compliance scans with the Compliance Operator. For more information on these API objects, run: - -[source,terminal] ----- -$ oc explain scansettings ----- - -or - -[source,terminal] ----- -$ oc explain scansettingbindings ----- - -include::modules/running-compliance-scans.adoc[leveloffset=+1] diff --git a/security/container_security/images b/security/container_security/images deleted file mode 120000 index 847b03ed0541..000000000000 --- a/security/container_security/images +++ /dev/null @@ -1 +0,0 @@ -../../images/ \ No newline at end of file diff --git a/security/container_security/modules b/security/container_security/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/security/container_security/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/security/container_security/security-build.adoc b/security/container_security/security-build.adoc deleted file mode 100644 index 7962147175d6..000000000000 --- a/security/container_security/security-build.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="security-build"] -= Securing the build process -include::modules/common-attributes.adoc[] -:context: security-build - -toc::[] - -In a container environment, the software build process is the stage in the life -cycle where application code is integrated with the required runtime libraries. -Managing this build process is key to securing the software stack. - -// Build once, deploy everywhere -include::modules/security-build-once.adoc[leveloffset=+1] - -// Build management and security -include::modules/security-build-management.adoc[leveloffset=+1] - -// Securing inputs during builds -include::modules/security-build-inputs.adoc[leveloffset=+1] - -// Designing your build process -include::modules/security-build-designing.adoc[leveloffset=+1] - -// Knative builds -include::modules/security-build-knative.adoc[leveloffset=+1] -.Additional resources -* xref:../../cicd/builds/understanding-image-builds.adoc#understanding-image-builds[Understanding image builds] -* xref:../../cicd/builds/triggering-builds-build-hooks.adoc#triggering-builds-build-hooks[Triggering and modifying builds] -* xref:../../cicd/builds/creating-build-inputs.adoc#creating-build-inputs[Creating build inputs] -* xref:../../cicd/builds/creating-build-inputs.adoc#builds-input-secrets-configmaps_creating-build-inputs[Input secrets and config maps] -ifndef::openshift-origin[] -// **This section is being moved, update the link once content is in.* add link here[The CI/CD methodology and practice] -* xref:../../serverless/architecture/serverless-serving-architecture.adoc#serverless-serving-architecture[Knative Serving architecture] -endif::[] -* xref:../../applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc#odc-viewing-application-composition-using-topology-view[Viewing application composition using the Topology view] diff --git a/security/container_security/security-compliance.adoc b/security/container_security/security-compliance.adoc deleted file mode 100644 index 463f244c1d66..000000000000 --- a/security/container_security/security-compliance.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="security-compliance"] -= Understanding compliance -include::modules/common-attributes.adoc[] -:context: security-compliance - -toc::[] - -For many {product-title} customers, regulatory readiness, or compliance, on -some level is required before any systems can be put into production. -That regulatory readiness can be imposed by national standards, industry -standards or the organization's corporate governance framework. - -// Compliance and the NIST risk management model -include::modules/security-compliance-nist.adoc[leveloffset=+1] -ifndef::openshift-origin[] -.Additional resources -* xref:../../installing/installing-fips.adoc#installing-fips-mode_installing-fips[Installing a cluster in FIPS mode] -endif::[] diff --git a/security/container_security/security-container-content.adoc b/security/container_security/security-container-content.adoc deleted file mode 100644 index 7ffcdb13eb39..000000000000 --- a/security/container_security/security-container-content.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="security-container-content"] -= Securing container content -include::modules/common-attributes.adoc[] -:context: security-container-content - -toc::[] - -To ensure the security of the content inside your containers -you need to start with trusted base images, such as Red Hat -Universal Base Images, and add trusted software. To check the -ongoing security of your container images, there are both -Red Hat and third-party tools for scanning images. - -// Security inside the container -include::modules/security-container-content-inside.adoc[leveloffset=+1] - -// Red Hat Universal Base Images -include::modules/security-container-content-universal.adoc[leveloffset=+1] - -// Container content scanning -include::modules/security-container-content-scanning.adoc[leveloffset=+1] - -// Integrating external scanning tools with OpenShift -include::modules/security-container-content-external-scanning.adoc[leveloffset=+1] -.Additional resources -* xref:../../openshift_images/images-understand.adoc#images-imagestream-use_images-understand[Image stream objects] -// * xref::../../rest_api/index.adoc#rest-api[{product-title} {product-version} REST APIs] diff --git a/security/container_security/security-deploy.adoc b/security/container_security/security-deploy.adoc deleted file mode 100644 index ed3e33731aaf..000000000000 --- a/security/container_security/security-deploy.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="security-deploy"] -= Deploying containers -include::modules/common-attributes.adoc[] -:context: security-deploy - -toc::[] - -You can use a variety of techniques to make sure that the containers you -deploy hold the latest production-quality content and that they have not -been tampered with. These techniques include setting up build triggers to -incorporate the latest code and using signatures to ensure that the container -comes from a trusted source and has not been modified. - -// Controlling container deployments with triggers -include::modules/security-deploy-trigger.adoc[leveloffset=+1] - -// Controlling what image sources can be deployed -include::modules/security-deploy-image-sources.adoc[leveloffset=+1] - -// Signature transports -include::modules/security-deploy-signature.adoc[leveloffset=+1] - -// Secrets and ConfigMaps -include::modules/security-deploy-secrets.adoc[leveloffset=+1] - -// Continuous deployment tooling -include::modules/security-deploy-continuous.adoc[leveloffset=+1] -.Additional resources -* xref:../../cicd/builds/creating-build-inputs.adoc#builds-input-secrets-configmaps_creating-build-inputs[Input secrets and config maps] diff --git a/security/container_security/security-hardening.adoc b/security/container_security/security-hardening.adoc deleted file mode 100644 index c2913f0adedd..000000000000 --- a/security/container_security/security-hardening.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[id="security-hardening"] -= Hardening {op-system} -include::modules/common-attributes.adoc[] -:context: security-hardening - -toc::[] - -{op-system} was created and tuned to be deployed in {product-title} with -few if any changes needed to {op-system} nodes. -Every organization adopting {product-title} has its own requirements for -system hardening. As a {op-system-base} system with OpenShift-specific modifications and -features added (such as Ignition, ostree, and a read-only `/usr` to provide -limited immutability), -{op-system} can be hardened just as you would any {op-system-base} system. -Differences lie in the ways you manage the hardening. - -A key feature of {product-title} and its Kubernetes engine is to be able -to quickly scale applications and infrastructure up and down as needed. -Unless it is unavoidable, you do not want to make direct changes to {op-system} by -logging into a host and adding software or changing settings. You want -to have the {product-title} installer and control plane manage changes -to {op-system} so new nodes can be spun up without manual intervention. - -So, if you are setting out to harden {op-system} nodes in {product-title} to meet -your security needs, you should consider both what to harden -and how to go about doing that hardening. - -// Choosing what to harden in {op-system} -include::modules/security-hardening-what.adoc[leveloffset=+1] - -// Choosing how to harden {op-system} -include::modules/security-hardening-how.adoc[leveloffset=+1] -.Additional resources -* link:https://access.redhat.com/articles/5059881[OpenShift Security Guide] -* xref:../../architecture/architecture-rhcos.adoc#rhcos-deployed_architecture-rhcos[Choosing how to configure {op-system}] -* xref:../../nodes/nodes/nodes-nodes-managing.adoc#nodes-nodes-managing[Modifying Nodes] -* xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installation-initializing-manual_installing-bare-metal[Manually creating the installation configuration file] -* xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installation-user-infra-generate-k8s-manifest-ignition_installing-bare-metal[Creating the Kubernetes manifest and Ignition config files] -* xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installation-user-infra-machines-iso_installing-bare-metal[Creating {op-system-first} machines using an ISO image] -* xref:../../installing/install_config/installing-customizing.adoc#installing-customizing[Customizing nodes] -* xref:../../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-kernel-arguments_nodes-nodes-working[Adding kernel arguments to Nodes] -ifndef::openshift-origin[] -* xref:../../installing/installing_aws/installing-aws-customizations.adoc#installation-configuration-parameters_installing-aws-customizations[Installation configuration parameters] - see `fips` -* xref:../../installing/installing-fips.adoc#installing-fips[Support for FIPS cryptography] -* link:https://access.redhat.com/articles/3359851[{op-system-base} core crypto components] -endif::[] diff --git a/security/container_security/security-hosts-vms.adoc b/security/container_security/security-hosts-vms.adoc deleted file mode 100644 index d9ac27be4051..000000000000 --- a/security/container_security/security-hosts-vms.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="security-hosts-vms"] -= Understanding host and VM security -include::modules/common-attributes.adoc[] -:context: security-hosts-vms - -toc::[] - -Both containers and virtual machines provide ways of separating -applications running on a host from the operating system itself. -Understanding {op-system}, which is the operating system used by -{product-title}, will help you see how the host -systems protect containers and hosts from each other. - - -// How containers are secured on {op-system} -include::modules/security-hosts-vms-rhcos.adoc[leveloffset=+1] -.Additional resources -* xref:../../nodes/nodes/nodes-nodes-resources-configuring.adoc#allocate-node-enforcement_nodes-nodes-resources-configuring[How nodes enforce resource constraints] -* xref:../../authentication/managing-security-context-constraints.adoc#managing-pod-security-policies[Managing security context constraints] -* xref:../../architecture/architecture-installation.adoc#supported-platforms-for-openshift-clusters_architecture-installation[Supported platforms for OpenShift clusters] -* xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installation-requirements-user-infra_installing-bare-metal[Machine requirements for a cluster with user-provisioned infrastructure] -* xref:../../architecture/architecture-rhcos.adoc#rhcos-configured_architecture-rhcos[Choosing how to configure {op-system}] -* xref:../../architecture/architecture-rhcos.adoc#rhcos-about-ignition_architecture-rhcos[Ignition] -* xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-kargs_installing-customizing[Kernel arguments] -* xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-kmod_installing-customizing[Kernel modules] -ifndef::openshift-origin[] -* xref:../../installing/installing-fips.adoc#installing-fips[FIPS cryptography] -endif::[] -* xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-encrypt-disk_installing-customizing[Disk encryption] -* xref:../../installing/install_config/installing-customizing.adoc#installation-special-config-chrony_installing-customizing[Chrony time service] -* xref:../../updating/updating-cluster-between-minor.adoc#update-service-overview_updating-cluster-between-minor[{product-title} cluster updates] - -// Virtualization versus containers -include::modules/security-hosts-vms-vs-containers.adoc[leveloffset=+1] - -// Securing OpenShift -include::modules/security-hosts-vms-openshift.adoc[leveloffset=+1] diff --git a/security/container_security/security-monitoring.adoc b/security/container_security/security-monitoring.adoc deleted file mode 100644 index 85b2c7cb2721..000000000000 --- a/security/container_security/security-monitoring.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="security-monitoring"] -= Monitoring cluster events and logs -include::modules/common-attributes.adoc[] -:context: security-monitoring - -toc::[] - -The ability to monitor and audit an {product-title} cluster is an -important part of safeguarding the cluster and its users against -inappropriate usage. - -There are two main sources of cluster-level information that -are useful for this purpose: events and logging. - -// Cluster events -include::modules/security-monitoring-events.adoc[leveloffset=+1] - -// Logging -include::modules/security-monitoring-cluster-logging.adoc[leveloffset=+1] - -// Audit logging -include::modules/security-monitoring-audit-logging.adoc[leveloffset=+1] - -.Additional resources -* xref:../../nodes/clusters/nodes-containers-events.adoc#nodes-containers-events[List of system events] -* xref:../../logging/cluster-logging.adoc#cluster-logging[Understanding OpenShift Logging] -* xref:../../security/audit-log-view.adoc#audit-log-view[Viewing audit logs] diff --git a/security/container_security/security-network.adoc b/security/container_security/security-network.adoc deleted file mode 100644 index 6ae2e3dadb02..000000000000 --- a/security/container_security/security-network.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="security-network"] -= Securing networks -include::modules/common-attributes.adoc[] -:context: security-network - -toc::[] - -Network security can be managed at several levels. At the pod level, -network namespaces can prevent containers from seeing other pods or -the host system by restricting network access. Network policies -give you control over allowing and rejecting connections. -You can manage ingress and egress traffic to and from your -containerized applications. - -// Network namespaces -include::modules/security-network-namespaces.adoc[leveloffset=+1] - -// Network policies -include::modules/security-network-policies.adoc[leveloffset=+1] -.Additional resources -* xref:../../networking/network_policy/about-network-policy.adoc#about-network-policy[About network policy] - -// Multiple pod networks -include::modules/security-network-multiple-pod.adoc[leveloffset=+1] -.Additional resources -* xref:../../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Using multiple networks] - -// Isolating applications -include::modules/security-network-isolating.adoc[leveloffset=+1] -.Additional resources -* xref:../../networking/openshift_sdn/multitenant-isolation.adoc#configuring-multitenant-isolation[Configuring network isolation using OpenShiftSDN] - -// Ingress traffic -include::modules/security-network-ingress.adoc[leveloffset=+1] -.Additional resources -* xref:../../networking/configuring_ingress_cluster_traffic/configuring-ingress-cluster-traffic-ingress-controller.adoc#configuring-ingress-cluster-traffic-ingress-controller[Configuring ingress cluster traffic] - -// Egress traffic -include::modules/security-network-egress.adoc[leveloffset=+1] -.Additional resources -* xref:../../networking/openshift_sdn/configuring-egress-firewall.adoc#configuring-egress-firewall[Configuring an egress firewall to control access to external IP addresses] -* xref:../../networking/openshift_sdn/assigning-egress-ips.adoc#assigning-egress-ips[Configuring egress IPs for a project] diff --git a/security/container_security/security-platform.adoc b/security/container_security/security-platform.adoc deleted file mode 100644 index 1558da488dc2..000000000000 --- a/security/container_security/security-platform.adoc +++ /dev/null @@ -1,50 +0,0 @@ -[id="security-platform"] -= Securing the container platform -include::modules/common-attributes.adoc[] -:context: security-platform - -toc::[] - -{product-title} and Kubernetes APIs are key to automating container management at scale. APIs are used to: - -* Validate and configure the data for pods, services, and replication controllers. -* Perform project validation on incoming requests and invoke triggers on other -major system components. - -Security-related features in {product-title} that are based on Kubernetes include: - -* Multitenancy, which combines Role-Based Access Controls and network policies -to isolate containers at multiple levels. -* Admission plug-ins, which form boundaries between an API and those -making requests to the API. - -{product-title} uses Operators to automate and simplify the management of -Kubernetes-level security features. - -// Multitenancy -include::modules/security-platform-multi-tenancy.adoc[leveloffset=+1] - -// Admission plug-ins -include::modules/security-platform-admission.adoc[leveloffset=+1] - -// Authentication and authorization -include::modules/security-platform-authentication.adoc[leveloffset=+1] - -// Managing certificates for the platform -include::modules/security-platform-certificates.adoc[leveloffset=+1] - -.Additional resources -* xref:../../architecture/architecture.adoc#architecture-platform-introduction_architecture[Introduction to {product-title}] -* xref:../../authentication/using-rbac.adoc#using-rbac[Using RBAC to define and apply permissions] - -ifndef::openshift-origin[] -* xref:../../architecture/admission-plug-ins.adoc#admission-plug-ins[About admission plug-ins] -endif::[] - -* xref:../../authentication/managing-security-context-constraints.adoc#managing-pod-security-policies[Managing security context constraints] -* xref:../../authentication/managing-security-context-constraints.adoc#security-context-constraints-command-reference_configuring-internal-oauth[SCC reference commands] -* xref:../../authentication/understanding-and-creating-service-accounts.adoc#service-accounts-granting-roles_understanding-service-accounts[Examples of granting roles to service accounts] -* xref:../../authentication/configuring-internal-oauth.adoc#configuring-internal-oauth[Configuring the internal OAuth server] -* xref:../../authentication/understanding-identity-provider.adoc#understanding-identity-provider[Understanding identity provider configuration] -* xref:../certificate_types_descriptions/user-provided-certificates-for-api-server.adoc#cert-types-user-provided-certificates-for-the-api-server[Certificate types and descriptions] -* xref:../certificate_types_descriptions/proxy-certificates.adoc#cert-types-proxy-certificates[Proxy certificates] diff --git a/security/container_security/security-registries.adoc b/security/container_security/security-registries.adoc deleted file mode 100644 index a175a7446fe6..000000000000 --- a/security/container_security/security-registries.adoc +++ /dev/null @@ -1,47 +0,0 @@ -[id="security-registries"] -= Using container registries securely -include::modules/common-attributes.adoc[] -:context: security-registries - -toc::[] - -Container registries store container images to: - -* Make images accessible to others -* Organize images into repositories that can include multiple versions of an image -* Optionally limit access to images, based on different authentication methods, or -make them publicly available - -There are public container registries, such as Quay.io and Docker Hub -where many people and organizations share their images. -The Red Hat Registry offers supported Red Hat and partner images, -while the Red Hat Ecosystem Catalog offers detailed descriptions -and health checks for those images. -To manage your own registry, you could purchase a container -registry such as -link:https://access.redhat.com/products/red-hat-quay[Red Hat Quay]. - -From a security standpoint, some registries provide special features to -check and improve the health of your containers. -For example, Red Hat Quay offers container vulnerability scanning -with Clair security scanner, build triggers to automatically rebuild -images when source code changes in GitHub and other locations, and -the ability to use role-based access control (RBAC) to -secure access to images. - -// Where do your containers come from? -include::modules/security-registries-where.adoc[leveloffset=+1] - -// Immutable and certified containers -include::modules/security-registries-immutable.adoc[leveloffset=+1] - -// Red Hat Registry and Red Hat Ecosystem (Container) Catalog -include::modules/security-registries-ecosystem.adoc[leveloffset=+1] - -// OpenShift Container Registry -include::modules/security-registries-openshift.adoc[leveloffset=+1] -.Additional resources -* xref:../../registry/architecture-component-imageregistry.adoc#architecture-component-imageregistry[Integrated {product-title} registry] - -// Quay Container Registry -include::modules/security-registries-quay.adoc[leveloffset=+1] diff --git a/security/container_security/security-storage.adoc b/security/container_security/security-storage.adoc deleted file mode 100644 index 250b4a593719..000000000000 --- a/security/container_security/security-storage.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="security-storage"] -= Securing attached storage -include::modules/common-attributes.adoc[] -:context: security-storage - -toc::[] - -{product-title} supports multiple types of storage, both -for on-premise and cloud providers. In particular, -{product-title} can use storage types that support the Container -Storage Interface. - -// Persistent volume plug-ins -include::modules/security-storage-persistent.adoc[leveloffset=+1] - -// Shared storage -include::modules/security-storage-shared.adoc[leveloffset=+1] - -// Block storage -include::modules/security-storage-block.adoc[leveloffset=+1] - -.Additional resources -* xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage] -* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-using-csi[Configuring CSI volumes] -* xref:../../storage/dynamic-provisioning.adoc#dynamic-provisioning[Dynamic provisioning] -* xref:../../storage/persistent_storage/persistent-storage-nfs.adoc#persistent-storage-using-nfs[Persistent storage using NFS] -* xref:../../storage/persistent_storage/persistent-storage-aws.adoc#persistent-storage-using-aws-ebs[Persistent storage using AWS Elastic Block Store] -* xref:../../storage/persistent_storage/persistent-storage-gce.adoc#persistent-storage-using-gce[Persistent storage using GCE Persistent Disk] diff --git a/security/container_security/security-understanding.adoc b/security/container_security/security-understanding.adoc deleted file mode 100644 index f5c964589470..000000000000 --- a/security/container_security/security-understanding.adoc +++ /dev/null @@ -1,65 +0,0 @@ -[id="security-understanding"] -= Understanding container security -include::modules/common-attributes.adoc[] -:context: security-understanding - -toc::[] - -Securing a containerized application relies on multiple levels of security: - -* Container security begins with a trusted base container image and continues -through the container build process as it moves through your CI/CD pipeline. -+ -[IMPORTANT] -==== -Image streams by default do not automatically update. This default behavior might create a security issue because security updates to images referenced by an image stream do not automatically occur. -For information about how to override this default behavior, see xref:../../openshift_images/image-streams-manage.adoc#images-imagestreams-import_image-streams-managing[Configuring periodic importing of imagestreamtags]. -==== -* When a container is deployed, its security depends on it running -on secure operating systems and networks, and -establishing firm boundaries between the container itself and -the users and hosts that interact with it. -* Continued security relies on being able to scan container images for -vulnerabilities and having an efficient way to correct and -replace vulnerable images. - -Beyond what a platform such as {product-title} offers out of the box, -your organization will likely have its own security demands. Some level -of compliance verification might be needed before you can even bring -{product-title} into your data center. - -Likewise, you may need to add your own agents, specialized hardware drivers, -or encryption features to {product-title}, before it can meet your -organization's security standards. - -This guide provides a high-level walkthrough of the container security measures -available in {product-title}, including solutions for the host layer, the -container and orchestration layer, and the build and application layer. -It then points you to specific OpenShift Container Platform documentation to -help you achieve those security measures. - -This guide contains the following information: - -* Why container security is important and how it compares with existing security standards. -* Which container security measures are provided by the host ({op-system} and {op-system-base}) layer and -which are provided by {product-title}. -* How to evaluate your container content and sources for vulnerabilities. -* How to design your build and deployment process to proactively check container content. -* How to control access to containers through authentication and authorization. -* How networking and attached storage are secured in {product-title}. -* Containerized solutions for API management and SSO. - -The goal of this guide is to understand the incredible security benefits of -using {product-title} for your containerized workloads and how the entire -Red Hat ecosystem plays a part in making and keeping containers secure. -It will also help you understand how you can engage with the {product-title} -to achieve your organization's security goals. - -// What are containers? -include::modules/security-understanding-containers.adoc[leveloffset=+1] - -// What is OpenShift? -include::modules/security-understanding-openshift.adoc[leveloffset=+1] -.Additional resources -* xref:../../architecture/architecture.adoc#architecture[{product-title} architecture] -* link:https://access.redhat.com/articles/5059881[OpenShift Security Guide] diff --git a/security/encrypting-etcd.adoc b/security/encrypting-etcd.adoc deleted file mode 100644 index edd541e2ac36..000000000000 --- a/security/encrypting-etcd.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="encrypting-etcd"] -= Encrypting etcd data -include::modules/common-attributes.adoc[] -:context: encrypting-etcd - -toc::[] - -// About etcd encryption -include::modules/about-etcd-encryption.adoc[leveloffset=+1] - -// Enabling etcd encryption -include::modules/enabling-etcd-encryption.adoc[leveloffset=+1] - -// Disabling etcd encryption -include::modules/disabling-etcd-encryption.adoc[leveloffset=+1] diff --git a/security/file_integrity_operator/file-integrity-operator-advanced-usage.adoc b/security/file_integrity_operator/file-integrity-operator-advanced-usage.adoc deleted file mode 100644 index d556ae5a682e..000000000000 --- a/security/file_integrity_operator/file-integrity-operator-advanced-usage.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="file-integrity-operator-advanced-usage"] -= Performing advanced Custom File Integrity Operator tasks -include::modules/common-attributes.adoc[] -:context: file-integrity-operator - -toc::[] - -include::modules/file-integrity-operator-reinitializing-database.adoc[leveloffset=+1] - -include::modules/file-integrity-operator-machine-config-integration.adoc[leveloffset=+1] - -include::modules/file-integrity-operator-exploring-daemon-sets.adoc[leveloffset=+1] diff --git a/security/file_integrity_operator/file-integrity-operator-configuring.adoc b/security/file_integrity_operator/file-integrity-operator-configuring.adoc deleted file mode 100644 index 27e9e691ffcb..000000000000 --- a/security/file_integrity_operator/file-integrity-operator-configuring.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="configuring-file-integrity-operator"] -= Configuring the Custom File Integrity Operator -include::modules/common-attributes.adoc[] -:context: file-integrity-operator - -toc::[] - - -include::modules/file-integrity-operator-viewing-attributes.adoc[leveloffset=+1] - -include::modules/file-integrity-important-attributes.adoc[leveloffset=+1] - -include::modules/file-integrity-examine-default-config.adoc[leveloffset=+1] - -include::modules/file-integrity-understanding-default-config.adoc[leveloffset=+1] - -include::modules/file-integrity-supplying-custom-aide-config.adoc[leveloffset=+1] - -include::modules/file-integrity-operator-defining-custom-config.adoc[leveloffset=+1] - -include::modules/file-integrity-operator-changing-custom-config.adoc[leveloffset=+1] diff --git a/security/file_integrity_operator/file-integrity-operator-troubleshooting.adoc b/security/file_integrity_operator/file-integrity-operator-troubleshooting.adoc deleted file mode 100644 index fa03392ce5ce..000000000000 --- a/security/file_integrity_operator/file-integrity-operator-troubleshooting.adoc +++ /dev/null @@ -1,66 +0,0 @@ -[id="troubleshooting-file-integrity-operator"] -= Troubleshooting the File Integrity Operator -include::modules/common-attributes.adoc[] -:context: file-integrity-operator - -toc::[] - -== General troubleshooting - -Issue:: -You want to generally troubleshoot issues with the File Integrity Operator. - -Resolution:: -Enable the debug flag in the `FileIntegrity` object. The `debug` flag increases -the verbosity of the daemons that run in the `DaemonSet` pods and run the AIDE -checks. - -== Checking the AIDE configuration - -Issue:: -You want to check the AIDE configuration. - -Resolution:: -The AIDE configuration is stored in a config map with the same name as the -`FileIntegrity` object. All AIDE configuration config maps are labeled -with `file-integrity.openshift.io/aide-conf`. - -== Determining the `FileIntegrity` object's phase - -Issue:: -You want to determine if the `FileIntegrity` object exists and see its current -status. - -Resolution:: -To see the `FileIntegrity` object's current status, run: -+ -[source,terminal] ----- -$ oc get fileintegrities/worker-fileintegrity -o jsonpath="{ .status }" ----- -+ -Once the `FileIntegrity` object and the backing daemon set are created, the status -should switch to `Active`. If it does not, check the Operator pod logs. - -== Determining that the daemon set's pods are running on the expected nodes - -Issue:: -You want to confirm that the daemon set exists and that its pods are running on -the nodes you expect them to run on. - -Resolution:: -Run: -+ -[source,terminal] ----- -$ oc get pods -lapp=aide-ds-$(<FIO_NAME>) ----- -+ --- -* `FIO_NAME` is the name of the `FileIntegrity` object to get a list of the pods. -* Adding `-owide` adds the IP address of the node the pod is running on. --- -+ -To check the logs of the daemon pods, run `oc logs` -+ -Check the return value of the AIDE command to see if the check passed or failed. diff --git a/security/file_integrity_operator/file-integrity-operator-understanding.adoc b/security/file_integrity_operator/file-integrity-operator-understanding.adoc deleted file mode 100644 index ae67ea5232a8..000000000000 --- a/security/file_integrity_operator/file-integrity-operator-understanding.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="understanding-file-integrity-operator"] -= Understanding the File Integrity Operator -include::modules/common-attributes.adoc[] -:context: file-integrity-operator - -toc::[] - -The File Integrity Operator is an {product-title} Operator that continually runs -file integrity checks on the cluster nodes. It deploys a daemon set that -initializes and runs privileged advanced intrusion detection environment (AIDE) -containers on each node, providing a status object with a log of files that are -modified during the initial run of the daemon set pods. - -[IMPORTANT] -==== -Currently, only {op-system-first} nodes are supported. -==== - -include::modules/file-integrity-understanding-file-integrity-cr.adoc[leveloffset=+1] -include::modules/checking-file-intergrity-cr-status.adoc[leveloffset=+1] -include::modules/file-integrity-CR-phases.adoc[leveloffset=+1] -include::modules/file-integrity-understanding-file-integrity-node-statuses-object.adoc[leveloffset=+1] -include::modules/file-integrity-node-status.adoc[leveloffset=+1] -include::modules/file-integrity-node-status-success.adoc[leveloffset=+2] -include::modules/file-integrity-node-status-failure.adoc[leveloffset=+2] diff --git a/security/images b/security/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/security/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/security/modules b/security/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/security/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/security/pod-vulnerability-scan.adoc b/security/pod-vulnerability-scan.adoc deleted file mode 100644 index 71853c6a5397..000000000000 --- a/security/pod-vulnerability-scan.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="pod-vulnerability-scan"] -= Scanning pods for vulnerabilities -include::modules/common-attributes.adoc[] -:context: pod-vulnerability-scan - -toc::[] - -Using the Container Security Operator (CSO), you can access vulnerability -scan results from the {product-title} web console for container images -used in active pods on the cluster. The CSO: - -* Watches containers associated with pods on all or specified namespaces -* Queries the container registry where the containers came from for -vulnerability information, provided an image’s registry is running image -scanning (such as -link:https://quay.io[Quay.io] or a -link:https://access.redhat.com/products/red-hat-quay[Red Hat Quay] registry with Clair scanning) -* Exposes vulnerabilities via the `ImageManifestVuln` object in the Kubernetes API - -Using the instructions here, the CSO is installed in the `openshift-operators` -namespace, so it is available to all namespaces on your OpenShift cluster. - -// -include::modules/security-pod-scan-cso.adoc[leveloffset=+1] - -// -include::modules/security-pod-scan-query-cli.adoc[leveloffset=+1] diff --git a/serverless/admin_guide/images b/serverless/admin_guide/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/admin_guide/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/admin_guide/installing-knative-eventing.adoc b/serverless/admin_guide/installing-knative-eventing.adoc deleted file mode 100644 index 86e29bf7f0c9..000000000000 --- a/serverless/admin_guide/installing-knative-eventing.adoc +++ /dev/null @@ -1,27 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="installing-knative-eventing"] -= Installing Knative Eventing -include::modules/common-attributes.adoc[] -:context: installing-knative-eventing - -toc::[] - -After you install the {ServerlessOperatorName}, you can install Knative Eventing by following the procedures described in this guide. - -This guide provides information about installing Knative Eventing using the default settings. -// However, you can configure more advanced settings in the KnativeEventing custom resource definition. - -// For more information about configuration options for the KnativeEventing custom resource definition, see xref:../../serverless/admin_guide/serverless-install-config-options.adoc#serverless-install-config-options[Advanced installation configuration options]. - -[id="installing-knative-eventing-prerequisites"] -== Prerequisites -* You have access to an {product-title} account with cluster administrator access. -* You have installed {ServerlessOperatorName}. - -include::modules/serverless-install-eventing-web-console.adoc[leveloffset=+1] -include::modules/serverless-install-eventing-yaml.adoc[leveloffset=+1] - -[id="installing-knative-eventing-next-steps"] -== Next steps - -* Install the Knative CLI to use `kn` commands with Knative Eventing. For example, `kn source` commands. See xref:../../serverless/installing-kn.adoc#installing-kn[Installing the Knative CLI]. diff --git a/serverless/admin_guide/installing-knative-serving.adoc b/serverless/admin_guide/installing-knative-serving.adoc deleted file mode 100644 index 665b30108859..000000000000 --- a/serverless/admin_guide/installing-knative-serving.adoc +++ /dev/null @@ -1,25 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="installing-knative-serving"] -= Installing Knative Serving -include::modules/common-attributes.adoc[] -:context: installing-knative-serving - -toc::[] - -After you install the {ServerlessOperatorName}, you can install Knative Serving. -This guide provides information about installing Knative Serving using the default settings. However, you can configure more advanced settings in the `KnativeServing` custom resource definition (CRD). -For more information about configuration options for the `KnativeServing` CRD, see xref:../../serverless/admin_guide/serverless-install-config-options.adoc#serverless-install-config-options[Advanced installation configuration options]. - -[id="installing-knative-serving-prerequisites"] -== Prerequisites -* You have access to an {product-title} account with cluster administrator access. -* You have installed the {ServerlessOperatorName}. - -include::modules/serverless-install-serving-web-console.adoc[leveloffset=+1] -include::modules/serverless-install-serving-yaml.adoc[leveloffset=+1] - -[id="installing-knative-serving-next-steps"] -== Next steps - -* For cloud events functionality on {ServerlessProductName}, you can install the Knative Eventing component. See the documentation on xref:../../serverless/admin_guide/installing-knative-eventing.adoc#installing-knative-eventing[Installing Knative Eventing]. -* Install the Knative CLI to use `kn` commands with Knative Serving. For example, `kn service` commands. See the documentation on xref:../../serverless/installing-kn#installing-kn[Installing the Knative CLI (`kn`)]. diff --git a/serverless/admin_guide/installing-openshift-serverless.adoc b/serverless/admin_guide/installing-openshift-serverless.adoc deleted file mode 100644 index a57ee8d4454e..000000000000 --- a/serverless/admin_guide/installing-openshift-serverless.adoc +++ /dev/null @@ -1,44 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="installing-openshift-serverless"] -= Installing {ServerlessProductName} -include::modules/common-attributes.adoc[] -:context: installing-openshift-serverless - -toc::[] - -This guide walks cluster administrators through installing the {ServerlessOperatorName} to an {product-title} cluster. - -[NOTE] -==== -{ServerlessProductName} is supported for installation in a restricted network environment. For more information, see xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks]. -==== - -[IMPORTANT] -==== -Before upgrading to the latest Serverless release, you must remove the community Knative Eventing Operator if you have previously installed it. Having the Knative Eventing Operator installed will prevent you from being able to install the latest version of Knative Eventing using the {ServerlessOperatorName}. -==== - -include::modules/serverless-cluster-sizing-req.adoc[leveloffset=+1] - -[id="installing-openshift-serverless-advanced-reqs"] -== Additional requirements for advanced use cases - -For more advanced use cases such as logging or metering on {product-title}, you must deploy more resources. Recommended requirements for such use cases are 24 CPUs and 96GB of memory. - -If you have high availability (HA) enabled on your cluster, this requires between 0.5 - 1.5 cores and between 200MB - 2GB of memory for each replica of the Knative Serving control plane. -HA is enabled for some Knative Serving components by default. You can disable HA by following the documentation on xref:../../serverless/serverless-HA.adoc#serverless-HA[Configuring high availability replicas on {ServerlessProductName}]. - -[id="installing-openshift-serverless-scaling-with-machinesets"] -== Scaling your cluster using machine sets - -You can use the {product-title} `MachineSet` API to manually scale your cluster up to the desired size. -The minimum requirements usually mean that you must scale up one of the default machine sets by two additional machines. -See xref:../../machine_management/manually-scaling-machineset.adoc#manually-scaling-machineset[Manually scaling a machine set]. - -include::modules/serverless-install-web-console.adoc[leveloffset=+1] - -[id="installing-openshift-serverless-next-steps"] -== Next steps - -* After the {ServerlessOperatorName} is installed, you can install the Knative Serving component. See the documentation on xref:../../serverless/admin_guide/installing-knative-serving.adoc#installing-knative-serving[Installing Knative Serving]. -* After the {ServerlessOperatorName} is installed, you can install the Knative Eventing component. See the documentation on xref:../../serverless/admin_guide/installing-knative-eventing.adoc#installing-knative-eventing[Installing Knative Eventing]. diff --git a/serverless/admin_guide/modules b/serverless/admin_guide/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/admin_guide/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/admin_guide/removing-openshift-serverless.adoc b/serverless/admin_guide/removing-openshift-serverless.adoc deleted file mode 100644 index 77ca3b07c792..000000000000 --- a/serverless/admin_guide/removing-openshift-serverless.adoc +++ /dev/null @@ -1,46 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="removing-openshift-serverless"] -= Removing {ServerlessProductName} -include::modules/common-attributes.adoc[] -:context: removing-openshift-serverless - -toc::[] - -This guide provides details of how to remove the {ServerlessOperatorName} and other {ServerlessProductName} components. - -[NOTE] -==== -Before you can remove the {ServerlessOperatorName}, you must remove Knative Serving and Knative Eventing. -==== - -// Uninstalling Knative Serving -include::modules/serverless-uninstalling-knative-serving.adoc[leveloffset=+1] -// Uninstalling Knative Eventing -include::modules/serverless-uninstalling-knative-eventing.adoc[leveloffset=+1] - -[id="removing-the-operator"] -== Removing the {ServerlessOperatorName} - -You can remove the {ServerlessOperatorName} from the host cluster by following the documentation on xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster]. - -[id="deleting-serverless-CRDs"] -== Deleting {ServerlessProductName} custom resource definitions - -After uninstalling the {ServerlessProductName}, the Operator and API custom resource definitions (CRDs) remain on the cluster. -You can use the following procedure to remove the remaining CRDs. - -[IMPORTANT] -==== -Removing the Operator and API CRDs also removes all resources that were defined using them, including Knative services. -==== - -== Prerequisites -* You uninstalled Knative Serving and removed the {ServerlessOperatorName}. - -.Procedure -* To delete the remaining {ServerlessProductName} CRDs, enter the following command: -+ -[source,terminal] ----- -$ oc get crd -oname | grep 'knative.dev' | xargs oc delete ----- diff --git a/serverless/admin_guide/serverless-cluster-admin-eventing.adoc b/serverless/admin_guide/serverless-cluster-admin-eventing.adoc deleted file mode 100644 index 03a43c54a7e9..000000000000 --- a/serverless/admin_guide/serverless-cluster-admin-eventing.adoc +++ /dev/null @@ -1,33 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-cluster-admin-eventing"] -= Creating Eventing components as a cluster administrator -include::modules/common-attributes.adoc[] -:context: serverless-cluster-admin-eventing - -toc::[] - -If you have cluster administrator permissions on a {product-title} cluster, you can create Knative Eventing components with {ServerlessProductName} in the *Administrator* perspective of the web console or by using the `kn` and `oc` CLIs. - -// Event sources -include::modules/serverless-creating-event-source-admin-web-console.adoc[leveloffset=+1] - -See xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[Getting started with event sources] for more information on which event source types are supported and can be created using by {ServerlessProductName}. - -// Brokers -include::modules/serverless-creating-broker-admin-web-console.adoc[leveloffset=+1] -include::modules/serverless-creating-broker-admin.adoc[leveloffset=+1] -include::modules/serverless-deleting-broker-admin.adoc[leveloffset=+1] -// Trigger -include::modules/serverless-creating-trigger-admin-web-console.adoc[leveloffset=+1] -// Channel -include::modules/serverless-creating-channel-admin-web-console.adoc[leveloffset=+1] -// Subscription -include::modules/serverless-creating-subscription-admin-web-console.adoc[leveloffset=+1] - -[id="serverless-cluster-admin-eventing-additional-resources"] -== Additional resources - -* See xref:../../serverless/event_workflows/serverless-using-brokers.adoc#serverless-using-brokers[Event delivery workflows using brokers and triggers]. -* See xref:../../serverless/event_workflows/serverless-channels.adoc#serverless-channels[Event delivery workflows using channels]. -* For information about using Apache Kafka components, see xref:../../serverless/serverless-kafka.adoc#serverless-kafka[ -Using Apache Kafka with {ServerlessProductName}]. diff --git a/serverless/admin_guide/serverless-cluster-admin-serving.adoc b/serverless/admin_guide/serverless-cluster-admin-serving.adoc deleted file mode 100644 index 567050ffd357..000000000000 --- a/serverless/admin_guide/serverless-cluster-admin-serving.adoc +++ /dev/null @@ -1,15 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-cluster-admin-serving"] -= Creating Serving components as a cluster administrator -include::modules/common-attributes.adoc[] -:context: serverless-cluster-admin-serving - -toc::[] - -If you have cluster administrator permissions on a {product-title} cluster, you can create Knative Serving components with {ServerlessProductName} in the *Administrator* perspective of the web console or by using the `kn` and `oc` CLIs. - -// Create services as an admin -include::modules/creating-serverless-apps-admin-console.adoc[leveloffset=+1] - -// [id="serverless-cluster-admin-serving-additional-resources"] -// == Additional resources diff --git a/serverless/admin_guide/serverless-install-config-options.adoc b/serverless/admin_guide/serverless-install-config-options.adoc deleted file mode 100644 index 5a602d584779..000000000000 --- a/serverless/admin_guide/serverless-install-config-options.adoc +++ /dev/null @@ -1,19 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-install-config-options"] -= Advanced installation configuration options -include::modules/common-attributes.adoc[] -:context: serverless-install-config-options - -toc::[] - -This guide provides information for cluster administrators about advanced installation configuration options for {ServerlessProductName} components. - -include::modules/knative-serving-advanced-config.adoc[leveloffset=+1] - -// == Knative Eventing supported installation configuration options -// image::eventing-form-view.png[Create Knative Eventing form] -// TODO: Add when there's more information for eventing. - -[id="serverless-install-config-options-additional-resources"] -== Additional resources -* For more information about configuring high availability, see xref:../../serverless/serverless-HA.adoc#serverless-HA[High availability on {ServerlessProductName}]. diff --git a/serverless/admin_guide/serverless-metering.adoc b/serverless/admin_guide/serverless-metering.adoc deleted file mode 100644 index 5d9ae49c3483..000000000000 --- a/serverless/admin_guide/serverless-metering.adoc +++ /dev/null @@ -1,19 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="metering-serverless"] -= Using metering with {ServerlessProductName} -:context: metering-serverless -include::modules/common-attributes.adoc[] - -toc::[] - -As a cluster administrator, you can use metering to analyze what is happening in your {ServerlessProductName} cluster. - -For more information about metering on {product-title}, see xref:../../metering/metering-about-metering.adoc#about-metering[About metering]. - -[id="installing-metering-serverless_{context}"] -== Installing metering -For information about installing metering on {product-title}, see xref:../../metering/metering-installing-metering.adoc#installing-metering[Installing Metering]. - -include::modules/serverless-metering-datasources.adoc[leveloffset=+1] -include::modules/serverless-metering-queries.adoc[leveloffset=+1] -include::modules/serverless-metering-reports.adoc[leveloffset=+1] diff --git a/serverless/admin_guide/upgrading-serverless.adoc b/serverless/admin_guide/upgrading-serverless.adoc deleted file mode 100644 index 3ba89f068a6a..000000000000 --- a/serverless/admin_guide/upgrading-serverless.adoc +++ /dev/null @@ -1,16 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="upgrading-serverless"] -= Upgrading {ServerlessProductName} -include::modules/common-attributes.adoc[] -:context: upgrading-serverless - -toc::[] - -If you have installed a previous version of {ServerlessProductName}, follow the instructions in this guide to upgrade to the latest version. - -[IMPORTANT] -==== -Before upgrading to the latest Serverless release, you must remove the community Knative Eventing Operator if you have previously installed it. Having the Knative Eventing Operator installed will prevent you from being able to install the latest version of Knative Eventing. -==== - -include::modules/serverless-upgrade-sub-channel.adoc[leveloffset=+1] diff --git a/serverless/architecture/images b/serverless/architecture/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/architecture/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/architecture/modules b/serverless/architecture/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/architecture/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/architecture/serverless-event-architecture.adoc b/serverless/architecture/serverless-event-architecture.adoc deleted file mode 100644 index b42cb00d2a35..000000000000 --- a/serverless/architecture/serverless-event-architecture.adoc +++ /dev/null @@ -1,36 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-event-architecture"] -= Knative Eventing architecture -:context: serverless-event-architecture -include::modules/common-attributes.adoc[] - -toc::[] - -Knative Eventing on {product-title} enables developers to use an link:https://www.redhat.com/en/topics/integration/what-is-event-driven-architecture[event-driven architecture] with serverless applications. -An event-driven architecture is based on the concept of decoupled relationships between event producers that create events, and event _sinks_, or consumers, that receive them. - -Knative Eventing uses standard HTTP POST requests to send and receive events between event producers and consumers. -These events conform to the link:https://cloudevents.io[CloudEvents specifications], which enables creating, parsing, sending, and receiving events in any programming language. - -You can propagate an event from an xref:../event_sources/knative-event-sources.adoc#knative-event-sources[event source] to multiple event sinks by using: - -* xref:../event_workflows/serverless-channels.adoc#serverless-channels[channels] and subscriptions, or -* xref:../event_workflows/serverless-using-brokers.adoc#serverless-using-brokers[brokers] and triggers. - -Events are buffered if the destination sink is unavailable. -// For more information about creating an Event delivery system, see -// Add link to getting started or tutorial landing page for eventing -Knative Eventing supports the following scenarios: - -Publish an event without creating a consumer:: You can send events to a broker as an HTTP POST, and use a SinkBinding to decouple the destination configuration from your application that is producing events. -Consume an event without creating a publisher:: You can use a trigger to consume events from a broker based on event attributes. Your application will receive events as an HTTP POST. -// Use Channels and Subscriptions to define complex message-passing topologies:: For simple pipelines, the Sequence automates construction of Channels and Subscriptions between each stage. -// Knative also supports some additional patterns such as Parallel fanout of events, and routing response events from both Channels and Brokers - -[id="serverless-event-architecture-sinks"] -== Event sinks - -To enable delivery to multiple types of sinks, Knative Eventing defines the following generic interfaces that can be implemented by multiple Kubernetes resources: - -Addressable objects:: Able to receive and acknowledge an event delivered over HTTP to an address defined in the event's `status.address.url` field. The Kubernetes Service object also satisfies the addressable interface. -Callable objects:: Able to receive an event delivered over HTTP and transform it, returning 0 or 1 new events in the HTTP response payload. These returned events may be further processed in the same way that events from an external event source are processed. diff --git a/serverless/architecture/serverless-serving-architecture.adoc b/serverless/architecture/serverless-serving-architecture.adoc deleted file mode 100644 index ca984ce3fe5b..000000000000 --- a/serverless/architecture/serverless-serving-architecture.adoc +++ /dev/null @@ -1,32 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-serving-architecture"] -= Knative Serving architecture -:context: serverless-serving-architecture -include::modules/common-attributes.adoc[] - -toc::[] - -Knative Serving on {product-title} enables developers to write link:https://www.redhat.com/en/topics/cloud-native-apps[cloud-native applications] using link:https://www.redhat.com/en/topics/cloud-native-apps/what-is-serverless[serverless architecture]. -Serverless is a cloud computing model where application developers don't need to provision servers or manage scaling for their applications. These routine tasks are abstracted away by the platform, allowing developers to push code to production much faster than in traditional models. - -Knative Serving supports deploying and managing cloud-native applications by providing a set of objects as Kubernetes custom resource definitions (CRDs) that define and control the behavior of serverless workloads on an {product-title} cluster. For more information about CRDs, see xref:../../operators/understanding/crds/crd-extending-api-with-crds.adoc#crd-extending-api-with-crds[Extending the Kubernetes API with custom resource definitions]. - -Developers use these CRDs to create custom resource (CR) instances that can be used as building blocks to address complex use cases. For example: - -* Rapidly deploying serverless containers. -* Automatically scaling pods. -// TODO: Add other use cases, more advanced tutorials? - -For more information about CRs, see xref:../../operators/understanding/crds/crd-managing-resources-from-crds.adoc#crd-managing-resources-from-crds[Managing resources from Custom Resource Definitions]. - -[id="serverless-serving-architecture-custom-resources"] -== Knative Serving custom resource definitions -// TODO: Request a good Serving arch diagram - -Service:: The `service.serving.knative.dev` CRD automatically manages the life cycle of your workload to ensure that the application is deployed and reachable through the network. It creates a route, a configuration, and a new revision for each change to a user created service, or custom resource. Most developer interactions in Knative are carried out by modifying services. - -Revision:: The `revision.serving.knative.dev` CRD is a point-in-time snapshot of the code and configuration for each modification made to the workload. Revisions are immutable objects and can be retained for as long as necessary. - -Route:: The `route.serving.knative.dev` CRD maps a network endpoint to one or more revisions. You can manage the traffic in several ways, including fractional traffic and named routes. - -Configuration:: The `configuration.serving.knative.dev` CRD maintains the desired state for your deployment. It provides a clean separation between code and configuration. Modifying a configuration creates a new revision. diff --git a/serverless/event_sources/images b/serverless/event_sources/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/event_sources/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/event_sources/knative-event-sources.adoc b/serverless/event_sources/knative-event-sources.adoc deleted file mode 100644 index 6b12bd2d41f1..000000000000 --- a/serverless/event_sources/knative-event-sources.adoc +++ /dev/null @@ -1,31 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="knative-event-sources"] -= Getting started with event sources -include::modules/common-attributes.adoc[] -:context: knative-event-sources - -toc::[] - -An _event source_ is an object that links an event producer with an event _sink_, or consumer. A sink can be a Knative service, channel, or broker that receives events from an event source. - -Currently, {ServerlessProductName} supports the following event source types: - -API server source:: Connects a sink to the Kubernetes API server. -Ping source:: Periodically sends ping events with a constant payload. It can be used as a timer. -Sink binding:: Allows you to connect core Kubernetes resource objects, such as `Deployment`, `Job`, or `StatefulSet` objects, with a sink. -Apache Kafka source:: Connect a Kafka cluster to a sink as an event source. - -:FeatureName: Apache Kafka on {ServerlessProductName} -include::modules/technology-preview.adoc[leveloffset=+2] - -You can create and manage Knative event sources using the **Developer** perspective in the {product-title} web console, the `kn` CLI, or by applying YAML files. - -* Create an xref:../../serverless/event_sources/serverless-apiserversource.adoc#serverless-apiserversource[API server source]. -* Create an xref:../../serverless/event_sources/serverless-pingsource.adoc#serverless-pingsource[ping source]. -* Create a xref:../../serverless/event_sources/serverless-sinkbinding.adoc#serverless-sinkbinding[sink binding]. -* Create a xref:../../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Kafka source]. - -[id="knative-event-sources-additional-resources"] -== Additional resources -* For more information about eventing workflows using {ServerlessProductName}, see xref:../../serverless/architecture/serverless-event-architecture.adoc#serverless-event-architecture[Knative Eventing architecture]. -* For more information about using Kafka event sources, see xref:../../serverless/serverless-kafka.adoc#serverless-kafka[Using Apache Kafka with {ServerlessProductName}]. diff --git a/serverless/event_sources/modules b/serverless/event_sources/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/event_sources/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/event_sources/serverless-apiserversource.adoc b/serverless/event_sources/serverless-apiserversource.adoc deleted file mode 100644 index 7059ed279bda..000000000000 --- a/serverless/event_sources/serverless-apiserversource.adoc +++ /dev/null @@ -1,32 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-apiserversource"] -= Using the API server source -include::modules/common-attributes.adoc[] -:context: serverless-apiserversource - -toc::[] - -The API server source is an event source that can be used to connect an event sink, such as a Knative service, to the Kubernetes API server. -The API server source watches for Kubernetes events and forwards them to the Knative Eventing broker. - -[id="serverless-apiserversource-prerequisites"] -== Prerequisites - -* You must have a current installation of xref:../../serverless/admin_guide/installing-openshift-serverless.adoc#serverless-install-web-console_installing-openshift-serverless[{ServerlessProductName}], including Knative Serving and Eventing, in your {product-title} cluster. This can be installed by a cluster administrator. -* Event sources need a service to use as an event _sink_. The sink is the service or application that events are sent to from the event source. -* You must create or update a service account, role and role binding for the event source. - -[NOTE] -==== -Some of the following procedures require you to create YAML files. - -If you change the names of the YAML files from those used in the examples, you must ensure that you also update the corresponding CLI commands. -==== - -include::modules/serverless-service-ac-event-sources.adoc[leveloffset=+1] -include::modules/odc-creating-apiserversource.adoc[leveloffset=+1] -include::modules/odc-deleting-apiserversource.adoc[leveloffset=+1] -include::modules/apiserversource-kn.adoc[leveloffset=+1] -include::modules/apiserversource-kn-delete.adoc[leveloffset=+1] -include::modules/apiserversource-yaml.adoc[leveloffset=+1] -include::modules/apiserversource-yaml-delete.adoc[leveloffset=+1] diff --git a/serverless/event_sources/serverless-kafka-source.adoc b/serverless/event_sources/serverless-kafka-source.adoc deleted file mode 100644 index b4515e3608f4..000000000000 --- a/serverless/event_sources/serverless-kafka-source.adoc +++ /dev/null @@ -1,21 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-kafka-source"] -= Using a Kafka source -include::modules/common-attributes.adoc[] -:context: serverless-kafka-source - -toc::[] - -:FeatureName: Apache Kafka on {ServerlessProductName} -include::modules/technology-preview.adoc[leveloffset=+2] - -The Apache Kafka event source brings messages into Knative. It reads events from an Apache Kafka cluster and passes these events to an event sink so that they can be consumed. You can use the `KafkaSource` event source with {ServerlessProductName}. - -include::modules/serverless-kafka-source-odc.adoc[leveloffset=+1] -include::modules/serverless-kafka-source-kn.adoc[leveloffset=+1] -include::modules/serverless-kafka-source-yaml.adoc[leveloffset=+1] - -[id="serverless-kafka-source-additional-resources"] -== Additional resources - -* See the link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/amq_streams_on_openshift_overview/kafka-concepts_str#kafka-concepts-key_str[Red Hat AMQ Streams] documentation for more information about Kafka concepts. diff --git a/serverless/event_sources/serverless-listing-event-sources.adoc b/serverless/event_sources/serverless-listing-event-sources.adoc deleted file mode 100644 index e085608edbdd..000000000000 --- a/serverless/event_sources/serverless-listing-event-sources.adoc +++ /dev/null @@ -1,27 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-listing-event-sources"] -= Listing event sources and event source types -include::modules/common-attributes.adoc[] -:context: serverless-listing-event-sources - -toc::[] - -You can use the `kn` CLI or the *Developer* perspective in the {product-title} web console to list and manage available event sources or event source types. - -Currently, {ServerlessProductName} supports the following event source types: - -API server source:: Connects a sink to the Kubernetes API server. -Ping source:: Periodically sends ping events with a constant payload. It can be used as a timer. -Sink binding:: Allows you to connect core Kubernetes resource objects, such as `Deployment`, `Job`, or `StatefulSet` objects, with a sink. -Apache Kafka source:: Connect a Kafka cluster to a sink as an event source. - -:FeatureName: Apache Kafka on {ServerlessProductName} -include::modules/technology-preview.adoc[leveloffset=+2] - -// Additional sources can be added by the cluster administrator. For example, {ServerlessProductName} can be used with Kafka and Camel K event sources, which are installed using the Operator Hub in the {product-title} web console. -// For more information about adding event source types as a cluster administrator, see -// xref:../knative-client.adoc#knative-client[Installing Knative Client]. - -include::modules/serverless-list-source-types-kn.adoc[leveloffset=+1] -include::modules/serverless-list-source-types-odc.adoc[leveloffset=+1] -include::modules/serverless-list-source.adoc[leveloffset=+1] diff --git a/serverless/event_sources/serverless-pingsource.adoc b/serverless/event_sources/serverless-pingsource.adoc deleted file mode 100644 index bc56b72bb0ed..000000000000 --- a/serverless/event_sources/serverless-pingsource.adoc +++ /dev/null @@ -1,38 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-pingsource"] -= Using a ping source -:context: serverless-pingsource -include::modules/common-attributes.adoc[] - -toc::[] - -A ping source is used to periodically send ping events with a constant payload to an event consumer. - -A ping source can be used to schedule sending events, similar to a timer. - -.Example ping source YAML -[source,yaml] ----- -apiVersion: sources.knative.dev/v1alpha2 -kind: PingSource -metadata: - name: test-ping-source -spec: - schedule: "*/2 * * * *" <1> - jsonData: '{"message": "Hello world!"}' <2> - sink: <3> - ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display ----- - -<1> The schedule of the event specified using https://kubernetes.io/docs/tasks/job/automated-tasks-with-cron-jobs/#schedule[CRON expression]. -<2> The event message body expressed as a JSON encoded data string. -<3> These are the details of the event consumer. In this example, we are using a Knative service named `event-display`. - -include::modules/serverless-pingsource-odc.adoc[leveloffset=+1] -include::modules/serverless-pingsource-kn.adoc[leveloffset=+1] -include::modules/deleting-pingsource-kn.adoc[leveloffset=+1] -include::modules/serverless-pingsource-yaml.adoc[leveloffset=+1] -include::modules/deleting-pingsource-yaml.adoc[leveloffset=+1] diff --git a/serverless/event_sources/serverless-sinkbinding.adoc b/serverless/event_sources/serverless-sinkbinding.adoc deleted file mode 100644 index 3d30c3406320..000000000000 --- a/serverless/event_sources/serverless-sinkbinding.adoc +++ /dev/null @@ -1,23 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-sinkbinding"] -= Using sink binding -include::modules/common-attributes.adoc[] -:context: serverless-sinkbinding - -toc::[] - -Sink binding is used to connect event producers, or _event sources_, to an event consumer, or _event sink_, for example, a Knative service or application. - -[IMPORTANT] -==== -Before developers can use sink binding, cluster administrators must label the namespace that will be configured for sink binding with `bindings.knative.dev/include:"true"`: - -[source,terminal] ----- -$ oc label namespace <namespace> bindings.knative.dev/include=true ----- - -==== - -include::modules/serverless-sinkbinding-kn.adoc[leveloffset=+1] -include::modules/serverless-sinkbinding-yaml.adoc[leveloffset=+1] diff --git a/serverless/event_workflows/images b/serverless/event_workflows/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/event_workflows/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/event_workflows/modules b/serverless/event_workflows/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/event_workflows/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/event_workflows/serverless-channels.adoc b/serverless/event_workflows/serverless-channels.adoc deleted file mode 100644 index 00b402bfea46..000000000000 --- a/serverless/event_workflows/serverless-channels.adoc +++ /dev/null @@ -1,48 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-channels"] -= Channel workflows -include::modules/common-attributes.adoc[] -:context: serverless-channels - -toc::[] - -Channels are custom resources that define a single event-forwarding and persistence layer. - -image::serverless-event-channel-workflow.png[Channel workflow overview] - -After events have been sent to a channel from an event source or producer, these events can be sent to multiple Knative services, or other sinks, by using a subscription. - -`InMemoryChannel` and `KafkaChannel` channel implementations can be used with {ServerlessProductName} for development use. - -The following are limitations of `InMemoryChannel` type channels: - -* No event persistence is available. If a pod goes down, events on that pod are lost. -* `InMemoryChannel` channels do not implement event ordering, so two events that are received in the channel at the same time can be delivered to a subscriber in any order. -* If a subscriber rejects an event, there are no re-delivery attempts by default. You can configure re-delivery attempts by modifying the `delivery` spec in the `Subscription` object. - -:FeatureName: Apache Kafka on {ServerlessProductName} -include::modules/technology-preview.adoc[leveloffset=+2] - -include::modules/serverless-channel-default.adoc[leveloffset=+1] -include::modules/serverless-channels-creating-intro.adoc[leveloffset=+1] - -include::modules/serverless-create-channel-odc.adoc[leveloffset=+2] -include::modules/serverless-create-channel-kn.adoc[leveloffset=+2] -include::modules/serverless-create-default-channel-yaml.adoc[leveloffset=+2] -include::modules/serverless-create-kafka-channel-yaml.adoc[leveloffset=+2] - -[id="serverless-channels-connecting-sources"] -== Connecting a channel to an event source - -Connecting a channel to an event source allows the channel to receive events from that source. -These events can then be forwarded to an event sink by using subscriptions. - -include::modules/serverless-connect-channel-source-odc.adoc[leveloffset=+2] - -// deleting channels -include::modules/serverless-delete-channel-kn.adoc[leveloffset=+1] - -[id="serverless-channels-next-steps"] -== Next steps - -* After you have created a channel, see xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs[Using subscriptions] for information about creating and using subscriptions for event delivery. diff --git a/serverless/event_workflows/serverless-event-delivery.adoc b/serverless/event_workflows/serverless-event-delivery.adoc deleted file mode 100644 index 16d30a0352fd..000000000000 --- a/serverless/event_workflows/serverless-event-delivery.adoc +++ /dev/null @@ -1,33 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-event-delivery"] -= Event delivery -include::modules/common-attributes.adoc[] -:context: serverless-event-delivery - -toc::[] - -You can configure event delivery parameters for Knative Eventing that are applied in cases where an event fails to be delivered by a xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs[subscription]. Event delivery parameters are configured individually per subscription. -// TODO: Update docs to add triggers once this is implemented. - -include::modules/serverless-event-delivery-component-behaviors.adoc[leveloffset=+1] - -[id="serverless-event-delivery-parameters"] -== Configurable parameters - -The following parameters can be configured for event delivery. - -Dead letter sink:: You can configure the `deadLetterSink` delivery parameter so that if an event fails to be delivered it is sent to the specified event sink. - -Retries:: You can set a minimum number of times that the delivery must be retried before the event is sent to the dead letter sink, by configuring the `retry` delivery parameter with an integer value. - -Back off delay:: You can set the `backoffDelay` delivery parameter to specify the time delay before an event delivery retry is attempted after a failure. The duration of the `backoffDelay` parameter is specified using the https://en.wikipedia.org/wiki/ISO_8601#Durations[ISO 8601] format. - -Back off policy:: The `backoffPolicy` delivery parameter can be used to specify the retry back off policy. The policy can be specified as either `linear` or `exponential`. When using the `linear` back off policy, the back off delay is the time interval specified between retries. When using the `exponential` backoff policy, the back off delay is equal to `backoffDelay*2^<numberOfRetries>`. - -include::modules/serverless-subscription-event-delivery-config.adoc[leveloffset=+1] - -[id="serverless-event-delivery-additional-resources"] -== Additional resources - -* See xref:../../serverless/event_workflows/serverless-channels.adoc#serverless-channels[Knative Eventing workflows using channels] for more information about subscriptions. -* See xref:../../serverless/event_workflows/serverless-subs.adoc#serverless-subs-creating-subs[Creating subscriptions]. diff --git a/serverless/event_workflows/serverless-subs.adoc b/serverless/event_workflows/serverless-subs.adoc deleted file mode 100644 index 4d56d336fc00..000000000000 --- a/serverless/event_workflows/serverless-subs.adoc +++ /dev/null @@ -1,32 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-subs"] -= Using subscriptions -include::modules/common-attributes.adoc[] -:context: serverless-subs - -toc::[] - -After events have been sent to a channel from an event source or producer, these events can be sent to multiple Knative services, or other sinks, by using a subscription. - -image::serverless-event-channel-workflow.png[Channel workflow overview] - -If a subscriber rejects an event, there are no re-delivery attempts by default. Developers can configure xref:../../serverless/event_workflows/serverless-event-delivery.adoc#serverless-event-delivery[re-delivery attempts] by modifying the `delivery` spec in a `Subscription` object. - -[id="serverless-subs-creating-subs"] -== Creating subscriptions - -Developers can create subscriptions that allow event sinks to subscribe to channels and receive events. - -include::modules/serverless-creating-subscriptions-odc.adoc[leveloffset=+2] -include::modules/serverless-creating-subscriptions-kn.adoc[leveloffset=+2] -include::modules/serverless-creating-subscriptions-yaml.adoc[leveloffset=+2] -// config event delivery -include::modules/serverless-subscription-event-delivery-config.adoc[leveloffset=+1] -// describe subs -include::modules/serverless-describe-subs-kn.adoc[leveloffset=+1] -// list subs -include::modules/serverless-list-subs-kn.adoc[leveloffset=+1] -// update subs -include::modules/serverless-update-subscriptions-kn.adoc[leveloffset=+1] -// delete subs -include::modules/serverless-deleting-subscriptions-kn.adoc[leveloffset=+1] diff --git a/serverless/event_workflows/serverless-using-brokers.adoc b/serverless/event_workflows/serverless-using-brokers.adoc deleted file mode 100644 index 6a793e45a72b..000000000000 --- a/serverless/event_workflows/serverless-using-brokers.adoc +++ /dev/null @@ -1,64 +0,0 @@ -[id="serverless-using-brokers"] -= Broker and trigger workflows -include::modules/common-attributes.adoc[] -include::modules/serverless-document-attributes.adoc[] -:context: serverless-using-brokers - -toc::[] - -Brokers can be used in combination with xref:../../serverless/event_workflows/serverless-using-brokers.adoc#serverless-using-brokers-triggers[triggers] to deliver events from an xref:../../serverless/event_sources/knative-event-sources.adoc#knative-event-sources[event source] to an event sink. - -image::serverless-event-broker-workflow.png[Broker event delivery overview] - -Events can be sent from an event source to a broker as an HTTP POST request. - -After events have entered the broker, they can be filtered by https://github.com/cloudevents/spec/blob/v1.0/spec.md#context-attributes[CloudEvent attributes] using triggers, and sent as an HTTP POST request to an event sink. - -[id="serverless-using-brokers-creating-brokers"] -== Creating a broker - -{ServerlessProductName} provides a `default` Knative broker that can be created by using the Knative CLI. -You can also create the `default` broker by adding the `eventing.knative.dev/injection: enabled` annotation to a trigger. - -[IMPORTANT] -==== -Although both developers and cluster administrators can add a broker by injection, only cluster administrators can permanently delete brokers that were created using this method. -==== - -include::modules/serverless-create-broker-kn.adoc[leveloffset=+2] -include::modules/serverless-creating-broker-annotation.adoc[leveloffset=+2] - -[id="serverless-using-brokers-managing-brokers"] -== Managing brokers - -The `kn` CLI provides commands that can be used to list, describe, update, and delete brokers. - -include::modules/serverless-list-broker-kn.adoc[leveloffset=+2] -include::modules/serverless-describe-broker-kn.adoc[leveloffset=+2] - -[id="serverless-using-brokers-triggers"] -== Filtering events using triggers - -Using triggers enables you to filter events from the broker for delivery to event sinks. - -.Prerequisites - -Before you can use triggers, you will need: - -* Knative Eventing and `kn` installed. -* An available broker, either the `default` broker or one that you have created. -+ -You can create the `default` broker either by following the instructions on xref:../serverless-using-brokers.adoc#serverless-using-brokers[Using brokers with Knative Eventing], or by using the `--inject-broker` flag while creating a trigger. Use of this flag is described later in this section. -* An available event consumer, such as a Knative service. - -// ODC -include::modules/serverless-create-trigger-odc.adoc[leveloffset=+2] -include::modules/serverless-delete-trigger-odc.adoc[leveloffset=+2] - -// kn trigger -include::modules/serverless-create-kn-trigger.adoc[leveloffset=+2] -include::modules/kn-trigger-list.adoc[leveloffset=+2] -include::modules/kn-trigger-describe.adoc[leveloffset=+2] -include::modules/kn-trigger-filtering.adoc[leveloffset=+2] -include::modules/kn-trigger-update.adoc[leveloffset=+2] -include::modules/delete-kn-trigger.adoc[leveloffset=+2] diff --git a/serverless/images b/serverless/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/installing-kn.adoc b/serverless/installing-kn.adoc deleted file mode 100644 index 27adcf26af1e..000000000000 --- a/serverless/installing-kn.adoc +++ /dev/null @@ -1,28 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="installing-kn"] -= Installing the Knative CLI (`kn`) -:context: installing-kn -include::modules/common-attributes.adoc[] - -toc::[] - -[NOTE] -==== -`kn` does not have its own login mechanism. To log in to the cluster, you must install the `oc` CLI and use `oc` login. - -Installation options for the `oc` CLI will vary depending on your operating system. - -For more information on installing the `oc` CLI for your operating system and logging in with `oc`, see the xref:../cli_reference/openshift_cli/getting-started-cli.adoc#cli-getting-started[OpenShift CLI getting started] documentation. -==== - -include::modules/serverless-installing-cli-web-console.adoc[leveloffset=+1] -include::modules/serverless-installing-cli-linux-rpm.adoc[leveloffset=+1] -include::modules/serverless-installing-cli-linux.adoc[leveloffset=+1] -include::modules/serverless-installing-cli-macos.adoc[leveloffset=+1] -include::modules/serverless-installing-cli-windows.adoc[leveloffset=+1] -include::modules/serverless-kn-cli-plugins.adoc[leveloffset=+1] - -== Additional resources - -* For instructions on using the Kafka source `kn` plug-in, see xref:../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Creating a Kafka event source using the `kn` CLI]. -// * For information on {ServerlessProductName} Functions, see link:https://openshift-knative.github.io/docs/docs/functions/about-functions.html[About OpenShift Serverless Functions]. diff --git a/serverless/integrations/gpu-resources.adoc b/serverless/integrations/gpu-resources.adoc deleted file mode 100644 index 67e773b5d9a0..000000000000 --- a/serverless/integrations/gpu-resources.adoc +++ /dev/null @@ -1,44 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="gpu-resources"] -= Using NVIDIA GPU resources with serverless applications -:context: gpu-resources -include::modules/common-attributes.adoc[] - -toc::[] - -NVIDIA supports experimental use of GPU resources on {product-title}. -See link:https://docs.nvidia.com/datacenter/kubernetes/openshift-on-gpu-install-guide/index.html[{product-title} on NVIDIA GPU accelerated clusters] for more information about setting up GPU resources on {product-title}. - -After GPU resources are enabled for your {product-title} cluster, you can specify GPU requirements for a Knative service using the `kn` CLI. - -.Procedure - -You can specify a GPU resource requirement when you create a Knative service using `kn`. - -. Create a service. -. Set the GPU resource requirement limit to `1` by using `nvidia.com/gpu=1`: -+ - -[source,terminal] ----- -$ kn service create hello --image docker.io/knativesamples/hellocuda-go --limit nvidia.com/gpu=1 ----- - -+ -A GPU resource requirement limit of `1` means that the service has 1 GPU resource dedicated. -Services do not share GPU resources. Any other services that require GPU resources must wait until the GPU resource is no longer in use. -+ -A limit of 1 GPU also means that applications exceeding usage of 1 GPU resource are restricted. -If a service requests more than 1 GPU resource, it is deployed on a node where the GPU resource requirements can be met. - -.Updating GPU requirements for a Knative service using `kn` - -* Update the service. Change the GPU resource requirement limit to `3` by using `nvidia.com/gpu=3`: - -[source,terminal] ----- -$ kn service update hello --limit nvidia.com/gpu=3 ----- - -== Additional resources -* For more information about limits, see xref:../../applications/quotas/quotas-setting-per-project.adoc[Setting resource quotas for extended resources]. diff --git a/serverless/integrations/images b/serverless/integrations/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/integrations/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/integrations/modules b/serverless/integrations/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/integrations/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/knative_serving/cluster-logging-serverless.adoc b/serverless/knative_serving/cluster-logging-serverless.adoc deleted file mode 100644 index 55aa624461ff..000000000000 --- a/serverless/knative_serving/cluster-logging-serverless.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="cluster-logging-serverless"] -= Using OpenShift Logging -include::modules/common-attributes.adoc[] -include::modules/serverless-document-attributes.adoc[] -:context: cluster-logging-serverless - -toc::[] - -include::modules/cluster-logging-about.adoc[leveloffset=+1] -include::modules/cluster-logging-deploying-about.adoc[leveloffset=+1] -// serverless specific -include::modules/serverless-using-cluster-logging-find-logs-knative-serving-components.adoc[leveloffset=+1] -include::modules/serverless-using-cluster-logging-find-logs-services-deployed.adoc[leveloffset=+1] diff --git a/serverless/knative_serving/configuring-knative-serving-autoscaling.adoc b/serverless/knative_serving/configuring-knative-serving-autoscaling.adoc deleted file mode 100644 index 1ee2317bde50..000000000000 --- a/serverless/knative_serving/configuring-knative-serving-autoscaling.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="configuring-knative-serving-autoscaling"] -= Configuring Knative Serving autoscaling -include::modules/common-attributes.adoc[] -include::modules/serverless-document-attributes.adoc[] -:context: configuring-knative-serving-autoscaling - -toc::[] - -{ServerlessProductName} provides capabilities for automatic pod scaling, including scaling inactive pods to zero. -To enable autoscaling for Knative Serving, you must configure concurrency and scale bounds in the revision template. - -[NOTE] -Any limits or targets set in the revision template are measured against a single instance of your application. For example, setting the `target` annotation to `50` will configure the autoscaler to scale the application so that each revision will handle 50 requests at a time. - -// Autoscaling -include::modules/serverless-workflow-autoscaling-kn.adoc[leveloffset=+1] -include::modules/knative-serving-concurrent-autoscaling-requests.adoc[leveloffset=+1] -include::modules/configuring-scale-bounds-knative.adoc[leveloffset=+1] diff --git a/serverless/knative_serving/images b/serverless/knative_serving/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/knative_serving/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/knative_serving/modules b/serverless/knative_serving/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/knative_serving/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/knative_serving/splitting-traffic-between-revisions-knative.adoc b/serverless/knative_serving/splitting-traffic-between-revisions-knative.adoc deleted file mode 100644 index 9c44fd53b822..000000000000 --- a/serverless/knative_serving/splitting-traffic-between-revisions-knative.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="splitting-traffic-between-revisions-knative"] -= Mapping and splitting traffic for different revisions of a service -include::modules/common-attributes.adoc[] -include::modules/serverless-document-attributes.adoc[] -:context: splitting-traffic-between-revisions-knative - -With each update to the configuration of a service, a new revision for the service is created. The service route points all traffic to the latest ready revision by default. You can change this behavior by defining which revisions gets a portion of the traffic. - -Knative services allow for traffic mapping, which means that revisions of a service can be mapped to an allocated portion of traffic. Traffic mapping also provides an option to create unique URLs for particular revisions. - -// ODC -include::modules/odc-splitting-traffic-between-revisions-using-developer-perspective.adoc[leveloffset=+1] -// Srvls specific -include::modules/traffic-splitting-kn.adoc[leveloffset=+1] -include::modules/serverless-workflow-tag-revisions-assign.adoc[leveloffset=+2] -include::modules/serverless-workflow-tag-revisions-unassign.adoc[leveloffset=+2] -include::modules/serverless-workflow-traffic-flag-operation-precedence.adoc[leveloffset=+2] -include::modules/serverless-workflow-traffic-splitting-flags.adoc[leveloffset=+2] diff --git a/serverless/modules b/serverless/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/monitoring/images b/serverless/monitoring/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/monitoring/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/monitoring/modules b/serverless/monitoring/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/monitoring/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/monitoring/serverless-monitoring.adoc b/serverless/monitoring/serverless-monitoring.adoc deleted file mode 100644 index c416a7388c8b..000000000000 --- a/serverless/monitoring/serverless-monitoring.adoc +++ /dev/null @@ -1,15 +0,0 @@ -// This assembly is included in the following assemblies: -// -// <List assemblies here, each on a new line> -include::modules/serverless-document-attributes.adoc[] -[id="serverless-monitoring"] -= Monitoring serverless components -:context: serverless-monitoring -include::modules/common-attributes.adoc[] - -toc::[] - -You can use {product-title} monitoring dashboards to view health checks and metrics for {ServerlessProductName} components. - -include::modules/serverless-monitoring-health-status.adoc[leveloffset=+1] -include::modules/serverless-monitoring-serving-cpu-memory.adoc[leveloffset=+1] diff --git a/serverless/networking/images b/serverless/networking/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/networking/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/networking/modules b/serverless/networking/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/networking/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/networking/serverless-configuring-routes.adoc b/serverless/networking/serverless-configuring-routes.adoc deleted file mode 100644 index e78b239af4c4..000000000000 --- a/serverless/networking/serverless-configuring-routes.adoc +++ /dev/null @@ -1,15 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-configuring-routes"] -= Configuring routes for Knative services -:context: serverless-configuring-routes -include::modules/common-attributes.adoc[] - -toc::[] - -Knative leverages {product-title} TLS termination to provide routing for Knative services. When a Knative service is created, a {product-title} route is automatically created for the service. This route is managed by the {ServerlessOperatorName}. The {product-title} route exposes the Knative service through the same domain as the {product-title} cluster. - -You can disable Operator control of {product-title} routing so that you can configure a Knative route to directly use your TLS certificates instead. - -Knative routes can also be used alongside the {product-title} route to provide additional fine-grained routing capabilities, such as traffic splitting. - -include::modules/serverless-openshift-routes.adoc[leveloffset=+1] diff --git a/serverless/networking/serverless-domain-mapping.adoc b/serverless/networking/serverless-domain-mapping.adoc deleted file mode 100644 index 3a273e833a79..000000000000 --- a/serverless/networking/serverless-domain-mapping.adoc +++ /dev/null @@ -1,13 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-domain-mapping"] -= Mapping a custom domain name to a Knative service -:context: serverless-domain-mapping -include::modules/common-attributes.adoc[] - -toc::[] - -Knative services are automatically assigned a default domain name based on your cluster configuration. For example, `<service_name>.<namespace>.example.com`. -You can map a custom domain name that you own to a Knative service by creating a `DomainMapping` custom resource (CR) for the service. -You can also create multiple CRs to map multiple domains and subdomains to a single service. - -include::modules/serverless-create-domain-mapping.adoc[leveloffset=+1] diff --git a/serverless/networking/serverless-ossm-custom-domains.adoc b/serverless/networking/serverless-ossm-custom-domains.adoc deleted file mode 100644 index 3ebfda850e89..000000000000 --- a/serverless/networking/serverless-ossm-custom-domains.adoc +++ /dev/null @@ -1,30 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -include::modules/ossm-document-attributes.adoc[] -[id="serverless-ossm-custom-domains"] -= Using custom domains for Knative services with {ProductShortName} -:context: serverless-ossm-custom-domains -include::modules/common-attributes.adoc[] - -toc::[] - -By default, Knative services have a fixed domain format: - -[source,terminal] ----- - <application_name>-<namespace>.<openshift_cluster_domain> ----- - -You can customize the domain for your Knative service by configuring the service as a private service and creating the required {ProductShortName} resources. - -.Prerequisites -* Install the xref:../../serverless/admin_guide/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessOperatorName}] and xref:../../serverless/admin_guide/installing-knative-serving.adoc#installing-knative-serving[Knative Serving]. -* Install xref:../../service_mesh/v1x/preparing-ossm-installation.adoc#preparing-ossm-installation-v1x[{ProductName}]. -* Complete the configuration steps in xref:../../serverless/networking/serverless-ossm.adoc#serverless-ossm[Using {ProductShortName} with {ServerlessProductName}]. -* You can configure a custom domain for an existing Knative service, or create a new sample service. To create a new service, see xref:../../serverless/serving-creating-managing-apps.adoc#serving-creating-managing-apps[Creating and managing serverless applications]. - -include::modules/knative-service-cluster-local.adoc[leveloffset=+1] -include::modules/serverless-service-mesh-resources.adoc[leveloffset=+1] -include::modules/serverless-access-custom-domain.adoc[leveloffset=+1] - -== Additional resources -* For more information about {ProductName}, see xref:../../service_mesh/v1x/ossm-architecture.adoc#ossm-architecture-v1x[Understanding {ProductName}]. diff --git a/serverless/networking/serverless-ossm-jwt.adoc b/serverless/networking/serverless-ossm-jwt.adoc deleted file mode 100644 index 4ceb6ba23c02..000000000000 --- a/serverless/networking/serverless-ossm-jwt.adoc +++ /dev/null @@ -1,25 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -include::modules/ossm-document-attributes.adoc[] -[id="serverless-ossm-jwt"] -= Using JSON Web Token authentication with {ProductShortName} and {ServerlessProductName} -:context: serverless-ossm-jwt -include::modules/common-attributes.adoc[] - -toc::[] - -You can enable JSON Web Token (JWT) authentication for Knative services. - -[id="serverless-ossm-jwt-prerequisites"] -== Prerequisites - -* Install xref:../../serverless/admin_guide/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessProductName}]. -* Install {ProductName}. {ServerlessProductName} is supported for use with both {ProductName} version xref:../../service_mesh/v1x/installing-ossm.adoc#installing-ossm[1.x] and version xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[2.x]. -* Configure xref:../../serverless/networking/serverless-ossm.adoc#serverless-ossm[{ProductShortName} with {ServerlessProductName}], including enabling sidecar injection for your Knative services. - -[IMPORTANT] -==== -Adding sidecar injection to pods in system namespaces such as `knative-serving` and `knative-serving-ingress` is not supported. -==== - -include::modules/serverless-ossm-v2x-jwt.adoc[leveloffset=+1] -include::modules/serverless-ossm-v1x-jwt.adoc[leveloffset=+1] diff --git a/serverless/networking/serverless-ossm-tls.adoc b/serverless/networking/serverless-ossm-tls.adoc deleted file mode 100644 index cc08b49c9a64..000000000000 --- a/serverless/networking/serverless-ossm-tls.adoc +++ /dev/null @@ -1,37 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -include::modules/ossm-document-attributes.adoc[] -[id="serverless-ossm-tls"] -= Configuring Transport Layer Security for a custom domain using {ProductName} -:context: serverless-ossm-tls -include::modules/common-attributes.adoc[] - -toc::[] - -You can create a Transport Layer Security (TLS) key and certificates for a custom domain and subdomain using {ProductName}. - -[NOTE] -==== -{ServerlessProductName} is compatible only with full implementations of either {ProductName} 1.x or 2.x. {ServerlessProductName} does not support custom usage of some 1.x resources and some 2.x resources in the same deployment. For example, upgrading to 2.x while still using the control plane `maistra.io/v1` spec is not supported. -==== - -[id="serverless-ossm-tls-prereqs"] -== Prerequisites - -* Install xref:../../serverless/admin_guide/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessProductName}]. -* Install {ProductName} xref:../../service_mesh/v1x/installing-ossm.adoc#installing-ossm-v1x[1.x] or xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm-v2x[2.x]. -* Complete the configuration steps in xref:../../serverless/networking/serverless-ossm.adoc#serverless-ossm[Using Service Mesh with OpenShift Serverless]. -* Configure a custom domain. See xref:../../serverless/networking/serverless-ossm-custom-domains.adoc#serverless-ossm-custom-domains[Using custom domains for Knative services with Service Mesh]. -* In this example, `openssl` is used to generate certificates, but you can use any certificate generation tool to create these. - -[IMPORTANT] -==== -This example uses the `example.com` domain. -The example certificate for this domain is used as a certificate authority (CA) that signs the subdomain certificate. - -To complete and verify this procedure in your deployment, you need either a certificate signed by a widely trusted public CA, or a CA provided by your organization. - -Example commands must be adjusted according to your domain, subdomain and CA. -==== - -include::modules/serverless-ossm-v2x-tls.adoc[leveloffset=+1] -include::modules/serverless-ossm-v1x-tls.adoc[leveloffset=+1] diff --git a/serverless/networking/serverless-ossm.adoc b/serverless/networking/serverless-ossm.adoc deleted file mode 100644 index bc3ec2f277d6..000000000000 --- a/serverless/networking/serverless-ossm.adoc +++ /dev/null @@ -1,20 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -include::modules/ossm-document-attributes.adoc[] -[id="serverless-ossm"] -= Using {ProductShortName} with {ServerlessProductName} -:context: serverless-ossm -include::modules/common-attributes.adoc[] - -toc::[] - -Using {ProductShortName} with {ServerlessProductName} enables developers to configure additional networking and routing options that are not supported when using {ServerlessProductName} with the default Kourier implementation. -These options include setting custom domains, using TLS certificates, and using JSON Web Token authentication. - -[id="serverless-ossm-prerequisites"] -== Prerequisites - -* Install the xref:../../serverless/admin_guide/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessOperatorName}] and xref:../../serverless/admin_guide/installing-knative-serving.adoc#installing-knative-serving[Knative Serving]. -* Install {ProductName}. {ServerlessProductName} is supported for use with both {ProductName} version xref:../../service_mesh/v1x/installing-ossm.adoc#installing-ossm[1.x] and version xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[2.x]. - -include::modules/serverless-ossm-setup.adoc[leveloffset=+1] -include::modules/serverless-service-mesh-enable-sidecar-injection.adoc[leveloffset=+1] diff --git a/serverless/serverless-HA.adoc b/serverless/serverless-HA.adoc deleted file mode 100644 index 8ac9157a6b44..000000000000 --- a/serverless/serverless-HA.adoc +++ /dev/null @@ -1,18 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-HA"] -= High availability on {ServerlessProductName} -include::modules/common-attributes.adoc[] -:context: serverless-HA - -toc::[] - -High availability (HA) is a standard feature of Kubernetes APIs that helps to ensure that APIs stay operational if a disruption occurs. -In an HA deployment, if an active controller crashes or is deleted, another controller is available to take over processing of the APIs that were being serviced by the controller that is now unavailable. - -HA in {ServerlessProductName} is available through leader election, which is enabled by default after the Knative Serving control plane is installed. - -When using a leader election HA pattern, instances of controllers are already scheduled and running inside the cluster before they are required. -These controller instances compete to use a shared resource, known as the leader election lock. -The instance of the controller that has access to the leader election lock resource at any given time is referred to as the leader. - -include::modules/serverless-config-replicas.adoc[leveloffset=+1] diff --git a/serverless/serverless-getting-started.adoc b/serverless/serverless-getting-started.adoc deleted file mode 100644 index 3ffd48bbcc1e..000000000000 --- a/serverless/serverless-getting-started.adoc +++ /dev/null @@ -1,29 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-getting-started"] -= Getting started with {ServerlessProductName} -:context: serverless-getting-started -include::modules/common-attributes.adoc[] - -toc::[] - -{ServerlessProductName} simplifies the process of delivering code from development into production by reducing the need for infrastructure set up or back-end development by developers. - -[id="serverless-getting-started-how-it-works"] -== How {ServerlessProductName} works - -Developers on {ServerlessProductName} can use the provided Kubernetes native APIs, as well as familiar languages and frameworks, to deploy applications and container workloads. - -{ServerlessProductName} on {product-title} enables stateless, serverless workloads to all run on a single multi-cloud container platform with automated operations. Developers can use a single platform for hosting their microservices, legacy, and serverless applications. - -{ServerlessProductName} is based on the open source Knative project, which provides portability and consistency across hybrid and multi-cloud environments by enabling an enterprise-grade serverless platform. - -[id="serverless-getting-started-supported-configs"] -== Supported configurations - -The set of supported features, configurations, and integrations for {ServerlessProductName}, current and past versions, are available at the link:https://access.redhat.com/articles/4912821[Supported Configurations page]. - -[id="serverless-getting-started-next-steps"] -== Next steps - -* Install the xref:../serverless/admin_guide/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessOperatorName}] on your {product-title} cluster to get started. -* View the xref:../serverless/serverless-release-notes.adoc#serverless-release-notes[{ServerlessProductName} release notes]. diff --git a/serverless/serverless-kafka.adoc b/serverless/serverless-kafka.adoc deleted file mode 100644 index 8cac6135d63e..000000000000 --- a/serverless/serverless-kafka.adoc +++ /dev/null @@ -1,56 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-kafka"] -= Using Apache Kafka with {ServerlessProductName} -include::modules/common-attributes.adoc[] -:context: serverless-kafka - -toc::[] - -:FeatureName: Apache Kafka on {ServerlessProductName} -include::modules/technology-preview.adoc[leveloffset=+2] - -You can use the `KafkaChannel` channel type and `KafkaSource` event source with {ServerlessProductName}. -To do this, you must install the Knative Kafka components, and configure the integration between {ServerlessProductName} and a supported link:https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/amq_streams_on_openshift_overview/index[Red Hat AMQ Streams] cluster. - -The {ServerlessOperatorName} provides the Knative Kafka API that can be used to create a `KnativeKafka` custom resource: - -.Example `KnativeKafka` custom resource -[source,yaml] ----- -apiVersion: operator.serverless.openshift.io/v1alpha1 -kind: KnativeKafka -metadata: - name: knative-kafka - namespace: knative-eventing -spec: - channel: - enabled: true <1> - bootstrapServers: <bootstrap_server> <2> - source: - enabled: true <3> ----- -<1> Enables developers to use the `KafkaChannel` channel type in the cluster. -<2> A comma-separated list of bootstrap servers from your AMQ Streams cluster. -<3> Enables developers to use the `KafkaSource` event source type in the cluster. - -// Install Kafka -include::modules/serverless-install-kafka-odc.adoc[leveloffset=+1] - -// Configure TLS and SASL for Kafka -== Configuring authentication for Kafka - -In production, Kafka clusters are often secured using the TLS or SASL authentication methods. This section shows how to configure the Kafka channel to work against a protected Red Hat AMQ Streams (Kafka) cluster using TLS or SASL. - -[NOTE] -==== -If you choose to enable SASL, Red Hat recommends to also enable TLS. -==== - -include::modules/serverless-kafka-tls.adoc[leveloffset=+2] -include::modules/serverless-kafka-sasl.adoc[leveloffset=+2] - -[id="serverless-kafka-next-steps"] -== Next steps - -* Create a xref:../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Kafka event source]. -* Create a xref:../serverless/event_workflows/serverless-channels.adoc#serverless-channels[Kafka channel]. diff --git a/serverless/serverless-release-notes.adoc b/serverless/serverless-release-notes.adoc deleted file mode 100644 index 32388a9b93b8..000000000000 --- a/serverless/serverless-release-notes.adoc +++ /dev/null @@ -1,26 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-release-notes"] -= {ServerlessProductName} Release Notes -:context: serverless-release-notes -include::modules/common-attributes.adoc[] - -toc::[] - -For an overview of {ServerlessProductName} functionality, see xref:../serverless/serverless-getting-started.adoc#serverless-getting-started[Getting started with OpenShift Serverless]. - -// Modules included, most to least recent -include::modules/serverless-rn-1-13-0.adoc[leveloffset=+1] -include::modules/serverless-rn-1-12-0.adoc[leveloffset=+1] -include::modules/serverless-rn-1-11-0.adoc[leveloffset=+1] -include::modules/serverless-rn-1-10-0.adoc[leveloffset=+1] - -[id="additional-resources"] -== Additional resources - -{ServerlessProductName} is based on the open source Knative project. - -* For details about the latest Knative Serving release, see the link:https://github.com/knative/serving/releases[Knative Serving releases page]. -* For details about the latest Knative Serving Operator release, see the link:https://github.com/knative/serving-operator/releases[Knative Serving Operator releases page]. -* For details about the latest Knative CLI release, see the link:https://github.com/knative/client/releases[Knative CLI releases page]. -* For details about the latest Knative Eventing release, see the link:https://github.com/knative/eventing/releases[Knative Eventing releases page]. -* link:https://openshift-knative.github.io/docs/docs/functions/about-functions.html[{ServerlessProductName} Functions Developer Preview documentation]. diff --git a/serverless/serverless-support.adoc b/serverless/serverless-support.adoc deleted file mode 100644 index 09fd3d6acee8..000000000000 --- a/serverless/serverless-support.adoc +++ /dev/null @@ -1,25 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-support"] -= {ServerlessProductName} support -:context: serverless-support -include::modules/common-attributes.adoc[] - -toc::[] - -include::modules/serverless-getting-support.adoc[leveloffset=+1] - -[id="serverless-support-gather-info_{context}"] -== Gathering diagnostic information for support - -When opening a support case, it is helpful to provide debugging -information about your cluster to Red Hat Support. - -The `must-gather` tool enables you to collect diagnostic information about your -{product-title} cluster, including data related to -{ServerlessProductName}. - -For prompt support, supply diagnostic information for both {product-title} -and {ServerlessProductName}. - -include::modules/about-must-gather.adoc[leveloffset=+2] -include::modules/serverless-about-collecting-data.adoc[leveloffset=+2] diff --git a/serverless/serverless-tracing.adoc b/serverless/serverless-tracing.adoc deleted file mode 100644 index b39ec1db9ad8..000000000000 --- a/serverless/serverless-tracing.adoc +++ /dev/null @@ -1,21 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-tracing"] -= Tracing requests using Jaeger -:context: serverless-tracing -include::modules/common-attributes.adoc[] - -toc::[] - -Using Jaeger with {ServerlessProductName} allows you to enable _distributed tracing_ for your serverless applications on {product-title}. - -Distributed tracing records the path of a request through the various services that make up an application. - -It is used to tie information about different units of work together, to understand a whole chain of events in a distributed transaction. -The units of work might be executed in different processes or hosts. - -Developers can visualize call flows in large architectures with distributed tracing. which is useful for understanding serialization, parallelism, and sources of latency. - -For more information about Jaeger, see xref:../jaeger/jaeger_arch/rhbjaeger-architecture.adoc#rhbjaeger-architecture[Jaeger architecture] and xref:../jaeger/jaeger_install/rhbjaeger-installation.adoc#rhbjaeger-installation[Installing Jaeger]. - -// Serverless specific modules -include::modules/serverless-jaeger-config.adoc[leveloffset=+1] diff --git a/serverless/serving-creating-managing-apps.adoc b/serverless/serving-creating-managing-apps.adoc deleted file mode 100644 index 11bf68d0e0f7..000000000000 --- a/serverless/serving-creating-managing-apps.adoc +++ /dev/null @@ -1,20 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serving-creating-managing-apps"] -= Creating and managing serverless applications -include::modules/common-attributes.adoc[] -:context: serving-creating-managing-apps - -toc::[] - -include::modules/serverless-apps-intro.adoc[leveloffset=+1] - -[id="serving-creating-managing-apps-ODC"] -== Creating serverless applications using the Developer perspective - -For more information about creating applications using the *Developer* perspective in {product-title}, see the documentation on xref:../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating applications using the Developer perspective]. - -include::modules/creating-serverless-apps-kn.adoc[leveloffset=+1] -include::modules/creating-serverless-apps-yaml.adoc[leveloffset=+1] - -include::modules/verifying-serverless-app-deployment.adoc[leveloffset=+1] -include::modules/interacting-serverless-apps-http2-gRPC.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/customizing-installation-ossm.adoc b/service_mesh/v1x/customizing-installation-ossm.adoc deleted file mode 100644 index 4bd9506aa427..000000000000 --- a/service_mesh/v1x/customizing-installation-ossm.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="customize-installation-ossm-v1x"] -= Customizing the {ProductName} installation -include::modules/ossm-document-attributes-1x.adoc[] -:context: customizing-installation-ossm-v1x - -toc::[] - -After your default `ServiceMeshControlPlane` resource is deployed, you can configure the resource to suit your environment. - -== Resources for configuring your `ServiceMeshControlPlane` resource - -Read more about how to configure your `ServiceMeshControlPlane` resource further, or skip ahead to Updating the `ServiceMeshControlPlane`. - -* See xref:../../service_mesh/v2x/ossm-observability.adoc#ossm-observability[Data visualization and observability] for more information about Kiali and visualizing your data. -* See xref:../../service_mesh/v2x/ossm-security.adoc#ossm-security[Security] for configuring mTLS, cipher suites, and external certificate authorities. -* See xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-routing-traffic[Traffic management] to configure your routing. -* See xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-custom-resources[Custom resources] for more information about all the configurable fields in your `ServiceMeshControlPlane` resource. - -include::modules/ossm-updating-smcp.adoc[leveloffset=+1] - -== Next steps - -* xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm-v1x[Prepare to deploy applications] on {ProductName}. - -// point to the reference topic diff --git a/service_mesh/v1x/images b/service_mesh/v1x/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/service_mesh/v1x/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/service_mesh/v1x/installing-ossm.adoc b/service_mesh/v1x/installing-ossm.adoc deleted file mode 100644 index 198f4fd4fefd..000000000000 --- a/service_mesh/v1x/installing-ossm.adoc +++ /dev/null @@ -1,62 +0,0 @@ -[id="installing-ossm-v1x"] -= Installing {ProductName} -include::modules/ossm-document-attributes-1x.adoc[] -:context: installing-ossm-v1x - -toc::[] - -Installing the {ProductShortName} involves installing the OpenShift Elasticsearch, Jaeger, Kiali and {ProductShortName} Operators, creating and managing a `ServiceMeshControlPlane` resource to deploy the control plane, and creating a `ServiceMeshMemberRoll` resource to specify the namespaces associated with the {ProductShortName}. - -[NOTE] -==== -Mixer’s policy enforcement is disabled by default. You must enable it to run policy tasks. See xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-mixer-policy-1x_deploying-applications-ossm-v1x[Update Mixer policy enforcement] for instructions on enabling Mixer policy enforcement. -==== - -[NOTE] -==== -Multi-tenant control plane installations are the default configuration starting with {ProductName} 1.0. -==== - -[NOTE] -==== -The {ProductShortName} documentation uses `istio-system` as the example project, but you may deploy the service mesh to any project. -==== - -== Prerequisites -* Follow the xref:../../service_mesh/v1x/preparing-ossm-installation.adoc#preparing-ossm-installation-v1x[Preparing to install {ProductName}] process. -* An account with the `cluster-admin` role. - -The {ProductShortName} installation process uses the link:https://operatorhub.io/[OperatorHub] to install the `ServiceMeshControlPlane` custom resource definition within the `openshift-operators` project. The {ProductName} defines and monitors the `ServiceMeshControlPlane` related to the deployment, update, and deletion of the control plane. - -Starting with {ProductName} {ProductVersion}, you must install the OpenShift Elasticsearch Operator, the Jaeger Operator, and the Kiali Operator before the {ProductName} Operator can install the control plane. - -include::modules/jaeger-install-elasticsearch.adoc[leveloffset=+1] - -include::modules/jaeger-install.adoc[leveloffset=+1] - -include::modules/ossm-install-kiali.adoc[leveloffset=+1] - -include::modules/ossm-install-ossm-operator.adoc[leveloffset=+1] - -include::modules/ossm-control-plane-deploy-1x.adoc[leveloffset=+1] - -For a multitenant installation, {ProductName} supports multiple independent control planes within the cluster. You can create reusable configurations with `ServiceMeshControlPlane` templates. For more information, see xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-control-plane-templates-1x_deploying-applications-ossm-v1x[Creating control plane templates]. - -include::modules/ossm-member-roll-create.adoc[leveloffset=+1] - -include::modules/ossm-member-roll-modify.adoc[leveloffset=+1] - -== Manual updates - -If you choose to update manually, the Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. OLM runs by default in {product-title}. -OLM uses CatalogSources, which use the Operator Registry API, to query for available Operators as well as upgrades for installed Operators. - -* For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-overview_olm-understanding-olm[Operator Lifecycle Manager] documentation. - -include::modules/ossm-update-app-sidecar.adoc[leveloffset=+2] - -== Next steps - -* xref:../../service_mesh/v1x/customizing-installation-ossm.adoc#customize-installation-ossm-v1x[Customize the {ProductName} installation]. - -* xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm-v1x[Prepare to deploy applications] on {ProductName}. diff --git a/service_mesh/v1x/modules b/service_mesh/v1x/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/service_mesh/v1x/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/service_mesh/v1x/ossm-architecture.adoc b/service_mesh/v1x/ossm-architecture.adoc deleted file mode 100644 index 476e209b1e25..000000000000 --- a/service_mesh/v1x/ossm-architecture.adoc +++ /dev/null @@ -1,47 +0,0 @@ -[id="ossm-architecture-v1x"] -= Understanding {ProductName} -include::modules/ossm-document-attributes-1x.adoc[] -:context: ossm-architecture-v1x - -toc::[] - -{ProductName} provides a platform for behavioral insight and operational control over your networked microservices in a service mesh. With {ProductName}, you can connect, secure, and monitor microservices in your {product-title} environment. - -include::modules/ossm-understanding-service-mesh.adoc[leveloffset=+1] - -include::modules/ossm-architecture-1x.adoc[leveloffset=+1] - -== Understanding Kiali - -Kiali provides visibility into your service mesh by showing you the microservices in your service mesh, and how they are connected. - -include::modules/ossm-kiali-overview.adoc[leveloffset=+2] - -include::modules/ossm-kiali-architecture.adoc[leveloffset=+2] - -include::modules/ossm-kiali-features.adoc[leveloffset=+2] - -== Understanding Jaeger - -Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate to produce a response. -The path of this request is a distributed transaction. -Jaeger lets you perform distributed tracing, which follows the path of a request through various microservices that make up an application. - -*Distributed tracing* is a technique that is used to tie the information about different units of work together—usually executed in different processes or hosts—to understand a whole chain of events in a distributed transaction. -Distributed tracing lets developers visualize call flows in large service oriented architectures. -It can be invaluable in understanding serialization, parallelism, and sources of latency. - -Jaeger records the execution of individual requests across the whole stack of microservices, and presents them as traces. A *trace* is a data/execution path through the system. An end-to-end trace is comprised of one or more spans. - -A *span* represents a logical unit of work in Jaeger that has an operation name, the start time of the operation, and the duration. Spans may be nested and ordered to model causal relationships. - -include::modules/jaeger-product-overview.adoc[leveloffset=+2] - -include::modules/jaeger-architecture.adoc[leveloffset=+2] - -include::modules/jaeger-features.adoc[leveloffset=+2] - - -== Next steps - -* xref:../../service_mesh/v1x/preparing-ossm-installation.adoc#preparing-ossm-installation-v1x[Prepare to install {ProductName}] in your {product-title} environment. diff --git a/service_mesh/v1x/ossm-custom-resources.adoc b/service_mesh/v1x/ossm-custom-resources.adoc deleted file mode 100644 index 333a43e84c49..000000000000 --- a/service_mesh/v1x/ossm-custom-resources.adoc +++ /dev/null @@ -1,41 +0,0 @@ -[id="ossm-custom-resources-v1x"] -= Custom resources -include::modules/ossm-document-attributes.adoc[] -:context: ossm-controler-items-v1x - -toc::[] - -You can customize your {ProductName} by modifying the default {ProductShortName} custom resource or by creating a new custom resource. - -== Prerequisites -* An account with the `cluster-admin` role. -* Completed the xref:../../service_mesh/v1x/preparing-ossm-installation.adoc#preparing-ossm-installation-v1x[Preparing to install {ProductName}] process. -* Have installed the operators. - -include::modules/ossm-cr-example-1x.adoc[leveloffset=+1] - -include::modules/ossm-cr-parameters.adoc[leveloffset=+1] - -include::modules/ossm-cr-istio-global.adoc[leveloffset=+2] - -include::modules/ossm-cr-gateway.adoc[leveloffset=+2] - -Cluster administrators can refer to xref:../../networking/ingress-operator.html#using-wildcard-routes_configuring-ingress[Using wildcard routes] for instructions on how to enable subdomains. - -include::modules/ossm-cr-mixer.adoc[leveloffset=+2] - -include::modules/ossm-cr-pilot.adoc[leveloffset=+2] - -include::modules/ossm-configuring-kiali.adoc[leveloffset=+1] - -include::modules/ossm-configuring-jaeger-v1x.adoc[leveloffset=+1] - -include::modules/ossm-configuring-jaeger-existing-v1x.adoc[leveloffset=+2] - -include::modules/ossm-jaeger-config-elasticsearch-v1x.adoc[leveloffset=+2] - -include::modules/ossm-jaeger-config-es-cleaner-v1x.adoc[leveloffset=+2] - -For more information about configuring Elasticsearch with {product-title}, see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store]. - -include::modules/ossm-cr-threescale.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/ossm-observability.adoc b/service_mesh/v1x/ossm-observability.adoc deleted file mode 100644 index 950cf49500ce..000000000000 --- a/service_mesh/v1x/ossm-observability.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="ossm-observability-v1x"] -= Data visualization and observability -include::modules/ossm-document-attributes-1x.adoc[] -:context: observability-v1x - -toc::[] - -You can view your application's topology, health and metrics in the Kiali console. If your service is having issues, the Kiali console offers ways to visualize the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. It also provides an interactive graph view of your namespace in real time. - -You can observe the data flow through your application if you have one installed. If you don't have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm-v1x[Bookinfo sample application]. - -After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command a few times: - ----- -$ curl http://$GATEWAY_URL/productpage ----- - -If your sample application is configured correctly, this command simulates a user visiting the `productpage` microservice of the application. - -include::modules/ossm-observability-access.adoc[leveloffset=+1] - -include::modules/ossm-observability-visual.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/ossm-security.adoc b/service_mesh/v1x/ossm-security.adoc deleted file mode 100644 index b7fa001bfded..000000000000 --- a/service_mesh/v1x/ossm-security.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="ossm-security-v1x"] -= Customizing security in a Service Mesh -include::modules/ossm-document-attributes-1x.adoc[] -:context: ossm-security-v1x - -toc::[] - -If your service mesh application is constructed with a complex array of microservices, you can use {ProductName} to customize the security of the communication between those services. The infrastructure of {product-title} along with the traffic management features of {ProductShortName} can help you manage the complexity of your applications and provide service and identity security for microservices. - -include::modules/ossm-security-mtls-1x.adoc[leveloffset=+1] - -include::modules/ossm-security-cipher.adoc[leveloffset=+1] - -include::modules/ossm-security-cert-manage.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/ossm-traffic-manage.adoc b/service_mesh/v1x/ossm-traffic-manage.adoc deleted file mode 100644 index b9b6d6ad719e..000000000000 --- a/service_mesh/v1x/ossm-traffic-manage.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="ossm-routing-traffic-v1x"] -= Traffic management -include::modules/ossm-document-attributes-1x.adoc[] -:context: routing-traffic-v1x - -toc::[] - -You can control the flow of traffic and API calls between services in {ProductName}. For example, some services in your service mesh may need to communicate within the mesh and others may need to be hidden. Manage the traffic to hide specific backend services, expose services, create testing or versioning deployments, or add a security layer on a set of services. - -This guide references the Bookinfo sample application to provide examples of routing in an example application. Install the xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm-v1x[Bookinfo application] to learn how these routing examples work. - -include::modules/ossm-routing.adoc[leveloffset=+1] - -include::modules/ossm-routing-ingress.adoc[leveloffset=+1] - -include::modules/ossm-routing-bookinfo-example.adoc[leveloffset=+1] - -include::modules/ossm-auto-route-1x.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/ossm-vs-community.adoc b/service_mesh/v1x/ossm-vs-community.adoc deleted file mode 100644 index df230a84dd60..000000000000 --- a/service_mesh/v1x/ossm-vs-community.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="ossm-vs-community-v1x"] -= Service Mesh and Istio differences -include::modules/ossm-document-attributes-1x.adoc[] -:context: ossm-vs-istio-v1x - -toc::[] - -An installation of {ProductName} differs from upstream Istio community installations in multiple ways. The modifications to {ProductName} are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on {product-title}. - -The current release of {ProductName} differs from the current upstream Istio community release in the following ways: - -// The following include statements pull in the module files that comprise the assembly. - -include::modules/ossm-multitenant.adoc[leveloffset=+1] - -include::modules/ossm-vs-istio-1x.adoc[leveloffset=+1] -[discrete] -[id="additional-resources_ossm-vs-istio-v1x"] -==== Additional resources - -* xref:../../service_mesh/v1x/ossm-traffic-manage.html#ossm-auto-route_routing-traffic-v1x[Automatic route creation] - -include::modules/ossm-kiali-service-mesh.adoc[leveloffset=+1] - -include::modules/ossm-jaeger-service-mesh.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc b/service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc deleted file mode 100644 index 50da4199a5c2..000000000000 --- a/service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc +++ /dev/null @@ -1,38 +0,0 @@ -[id="deploying-applications-ossm-v1x"] -= Deploying applications on {ProductName} -include::modules/ossm-document-attributes.adoc[] -:context: deploying-applications-ossm-v1x - -toc::[] - -When you deploy an application into the {ProductShortName}, there are several differences between the behavior of applications in the upstream community version of Istio and the behavior of applications within a {ProductName} installation. - -== Prerequisites - -* Review xref:../../service_mesh/v1x/ossm-vs-community.adoc#ossm-vs-community-v1x[Comparing {ProductName} and upstream Istio community installations] - -* Review xref:../../service_mesh/v1x/installing-ossm.adoc#installing-ossm-v1x[Installing {ProductName}] - -include::modules/ossm-control-plane-templates-1x.adoc[leveloffset=+1] - -include::modules/ossm-sidecar-injection.adoc[leveloffset=+1] - -include::modules/ossm-automatic-sidecar-injection.adoc[leveloffset=+2] - -include::modules/ossm-mixer-policy-1x.adoc[leveloffset=+1] - -include::modules/ossm-config-network-policy.adoc[leveloffset=+1] - - -include::modules/ossm-tutorial-bookinfo-overview.adoc[leveloffset=+1] - -include::modules/ossm-tutorial-bookinfo-install.adoc[leveloffset=+2] - -include::modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc[leveloffset=+2] - -include::modules/ossm-tutorial-bookinfo-verify-install.adoc[leveloffset=+2] - -include::modules/ossm-tutorial-bookinfo-removing.adoc[leveloffset=+2] - - -include::modules/ossm-tutorial-jaeger-generating-traces.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/preparing-ossm-installation.adoc b/service_mesh/v1x/preparing-ossm-installation.adoc deleted file mode 100644 index 0d6d229abd36..000000000000 --- a/service_mesh/v1x/preparing-ossm-installation.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="preparing-ossm-installation-v1x"] -= Preparing to install {ProductName} -include::modules/ossm-document-attributes-1x.adoc[] -:context: preparing-ossm-installation-v1x - -toc::[] - -Before you can install {ProductName}, review the installation activities, ensure that you meet the prerequisites: - -== Prerequisites - -* Possess an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information. -* Review the xref:../../architecture/architecture-installation.adoc#installation-overview_architecture-installation[{product-title} {product-version} overview]. -* Install {product-title} {product-version}. -** xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Install {product-title} {product-version} on AWS] -** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Install {product-title} {product-version} on user-provisioned AWS] -** xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install {product-title} {product-version} on bare metal] -** xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Install {product-title} {product-version} on vSphere] -+ -[NOTE] -==== -If you are installing {ProductName} on a xref:../../installing/installing-preparing.adoc#supported-installation-methods-for-different-platforms[restricted network], follow the instructions for your chosen {product-title} infrastructure. -==== -+ -* Install the version of the {product-title} command line utility (the `oc` client tool) that matches your {product-title} version and add it to your path. -** If you are using {product-title} {product-version}, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-about-cli_cli-developer-commands[About the OpenShift CLI]. - -include::modules/ossm-supported-configurations-v1x.adoc[leveloffset=+1] - -include::modules/ossm-installation-activities.adoc[leveloffset=+1] - -[WARNING] -==== -Please see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] for details on configuring the default Jaeger parameters for Elasticsearch in a production environment. -==== - -== Next steps - -* xref:../../service_mesh/v1x/installing-ossm.adoc#installing-ossm-v1x[Install {ProductName}] in your {product-title} environment. diff --git a/service_mesh/v1x/removing-ossm.adoc b/service_mesh/v1x/removing-ossm.adoc deleted file mode 100644 index 5d5e1e52ac37..000000000000 --- a/service_mesh/v1x/removing-ossm.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="removing-ossm-v1x"] -= Removing {ProductName} -include::modules/ossm-document-attributes-1x.adoc[] -:context: removing-ossm-v1x - -toc::[] - -This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. - -include::modules/ossm-member-roll-delete.adoc[leveloffset=+1] - -include::modules/ossm-control-plane-remove.adoc[leveloffset=+1] - -include::modules/ossm-remove-operators.adoc[leveloffset=+1] - -include::modules/ossm-remove-cleanup-1x.adoc[leveloffset=+2] diff --git a/service_mesh/v1x/servicemesh-release-notes.adoc b/service_mesh/v1x/servicemesh-release-notes.adoc deleted file mode 100644 index 51cf4ac68399..000000000000 --- a/service_mesh/v1x/servicemesh-release-notes.adoc +++ /dev/null @@ -1,48 +0,0 @@ -[id="service-mesh-release-notes-v1x"] -= Service Mesh Release Notes -include::modules/ossm-document-attributes-1x.adoc[] -:context: ossm-release-notes-v1x - -toc::[] - -// The following include statements pull in the module files that comprise 1.x release notes. - -include::modules/ossm-servicemesh-overview.adoc[leveloffset=+1] - -include::modules/support.adoc[leveloffset=+1] - -When opening a support case, it is helpful to provide debugging -information about your cluster to Red Hat Support. - -The `must-gather` tool enables you to collect diagnostic information about your -{product-title} cluster, including virtual machines and other data related to -{ProductName}. - -For prompt support, supply diagnostic information for both {product-title} -and {ProductName}. - -include::modules/about-must-gather.adoc[leveloffset=+2] - -=== Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -* The {product-title} CLI (`oc`) installed. - -include::modules/ossm-about-collecting-ossm-data.adoc[leveloffset=+2] - -include::modules/ossm-supported-configurations-v1x.adoc[leveloffset=+1] - -include::modules/ossm-rn-new-features-1x.adoc[leveloffset=+1] - -include::modules/ossm-rn-deprecated-features-1x.adoc[leveloffset=+1] - -include::modules/ossm-rn-known-issues-1x.adoc[leveloffset=+1] - -include::modules/jaeger-rn-known-issues.adoc[leveloffset=+2] - -include::modules/ossm-rn-fixed-issues-1x.adoc[leveloffset=+1] - -include::modules/jaeger-rn-fixed-issues.adoc[leveloffset=+2] - -//include::modules/jaeger-rn-fixed-issues.adoc[leveloffset=+2] diff --git a/service_mesh/v1x/threescale-adapter.adoc b/service_mesh/v1x/threescale-adapter.adoc deleted file mode 100644 index 0341b9d2d20e..000000000000 --- a/service_mesh/v1x/threescale-adapter.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="threescale-adapter-v1x"] -= Using the 3scale Istio adapter -include::modules/ossm-document-attributes-1x.adoc[] -:context: threescale-adapter-v1x - -toc::[] - -The 3scale Istio Adapter is an optional adapter that allows you to label a service running within the {ProductName} and integrate that service with the 3scale API Management solution. -It is not required for {ProductName}. - - -include::modules/ossm-threescale-integrate-1x.adoc[leveloffset=+1] - -include::modules/ossm-threescale-cr.adoc[leveloffset=+2] - -include::modules/ossm-threescale-templates.adoc[leveloffset=+3] - -include::modules/ossm-threescale-manifests.adoc[leveloffset=+2] - -include::modules/ossm-threescale-routing.adoc[leveloffset=+2] - -include::modules/ossm-threescale-integration-settings.adoc[leveloffset=+1] - -include::modules/ossm-threescale-caching.adoc[leveloffset=+1] - -include::modules/ossm-threescale-authentication.adoc[leveloffset=+1] - -include::modules/ossm-threescale-metrics-1x.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/customizing-installation-ossm.adoc b/service_mesh/v2x/customizing-installation-ossm.adoc deleted file mode 100644 index 3667725d4c6d..000000000000 --- a/service_mesh/v2x/customizing-installation-ossm.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="customize-installation-ossm-v2x"] -= Configuring the {ProductName} installation -include::modules/ossm-document-attributes.adoc[] -:context: customizing-installation-ossm-v2x - -toc::[] - -After your default `ServiceMeshControlPlane` resource is deployed, you must configure the resource to suit your environment. Note that the default Jaeger deployment must be changed, as the default `allinone` deployment does not supply persistent memory. - -== Resources for configuring your `ServiceMeshControlPlane` resource - -Read more about how to configure your `ServiceMeshControlPlane` resource further, or skip ahead to Updating the `ServiceMeshControlPlane`. - -* See xref:../../service_mesh/v2x/ossm-observability.adoc#ossm-observability[Data visualization and observability] for more information about Kiali and visualizing your data. -* See xref:../../service_mesh/v2x/ossm-security.adoc#ossm-security[Security] for configuring mTLS, cipher suites, and external certificate authorities. -* See xref:../../service_mesh/v2x/ossm-traffic-manage.adoc#ossm-routing-traffic[Traffic management] to configure your routing. -* See xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-custom-resources[Custom resources] for more information about all the configurable fields in your `ServiceMeshControlPlane` resource. - -include::modules/ossm-updating-smcp.adoc[leveloffset=+1] - -== Next steps - -* xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm[Prepare to deploy applications] on {ProductName}. diff --git a/service_mesh/v2x/images b/service_mesh/v2x/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/service_mesh/v2x/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/service_mesh/v2x/installing-ossm.adoc b/service_mesh/v2x/installing-ossm.adoc deleted file mode 100644 index 103bdbaac62f..000000000000 --- a/service_mesh/v2x/installing-ossm.adoc +++ /dev/null @@ -1,62 +0,0 @@ -[id="installing-ossm"] -= Installing {ProductName} -include::modules/ossm-document-attributes.adoc[] -:context: installing-ossm - -toc::[] - -Installing the {ProductShortName} involves installing the OpenShift Elasticsearch, Jaeger, Kiali and {ProductShortName} Operators, creating and managing a `ServiceMeshControlPlane` resource to deploy the control plane, and creating a `ServiceMeshMemberRoll` resource to specify the namespaces associated with the {ProductShortName}. - -[NOTE] -==== -Multi-tenant control plane installations are the default configuration starting with {ProductName} 1.0. -==== - -[NOTE] -==== -The {ProductShortName} documentation uses `istio-system` as the example project, but you may deploy the service mesh to any project. -==== - -== Prerequisites -* Follow the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Preparing to install {ProductName}] process. -* An account with the `cluster-admin` role. - -The {ProductShortName} installation process uses the link:https://operatorhub.io/[OperatorHub] to install the `ServiceMeshControlPlane` custom resource definition within the `openshift-operators` project. The {ProductName} defines and monitors the `ServiceMeshControlPlane` related to the deployment, update, and deletion of the control plane. - -Starting with {ProductName} {ProductVersion}, you must install the OpenShift Elasticsearch Operator, the Jaeger Operator, and the Kiali Operator before the {ProductName} Operator can install the control plane. - -include::modules/jaeger-install-elasticsearch.adoc[leveloffset=+1] - -include::modules/jaeger-install.adoc[leveloffset=+1] - -include::modules/ossm-install-kiali.adoc[leveloffset=+1] - -include::modules/ossm-install-ossm-operator.adoc[leveloffset=+1] - -include::modules/ossm-control-plane-deploy.adoc[leveloffset=+1] - -For a multitenant installation, {ProductName} supports multiple independent control planes within the cluster. You can create reusable configurations with `ServiceMeshControlPlane` profiles. For more information, see xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-control-plane-profiles_deploying-applications-ossm[Creating control plane profiles]. - -include::modules/ossm-member-roll-create.adoc[leveloffset=+1] - -include::modules/ossm-member-roll-modify.adoc[leveloffset=+1] - -== Manual updates - -If you choose to update manually, the Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. OLM runs by default in {product-title}. -OLM uses CatalogSources, which use the Operator Registry API, to query for available Operators as well as upgrades for installed Operators. - -* For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-overview_olm-understanding-olm[Operator Lifecycle Manager] documentation. - -include::modules/ossm-update-app-sidecar.adoc[leveloffset=+2] - -== Next steps - -[NOTE] -==== -The default `ServiceMeshControlPlane` settings are not intended for production use; they are designed to install successfully on a default OpenShift installation, which is an extremely resource limited environment. After you have verified a successful SMCP installation, you should modify the settings defined within the SMCP to suit your environment. -==== - -* xref:../../service_mesh/v2x/customizing-installation-ossm.adoc#customize-installation-ossm-v2x[Customize the {ProductName} installation]. - -* xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#deploying-applications-ossm[Prepare to deploy applications] on {ProductName}. diff --git a/service_mesh/v2x/modules b/service_mesh/v2x/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/service_mesh/v2x/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/service_mesh/v2x/ossm-architecture.adoc b/service_mesh/v2x/ossm-architecture.adoc deleted file mode 100644 index e354f4e7e074..000000000000 --- a/service_mesh/v2x/ossm-architecture.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[id="ossm-architecture"] -include::modules/ossm-document-attributes.adoc[] -= Understanding {ProductName} -:context: ossm-architecture - -toc::[] - -{ProductName} provides a platform for behavioral insight and operational control over your networked microservices in a service mesh. With {ProductName}, you can connect, secure, and monitor microservices in your {product-title} environment. - -include::modules/ossm-understanding-service-mesh.adoc[leveloffset=+1] - -include::modules/ossm-architecture.adoc[leveloffset=+1] - -== Understanding Kiali - -Kiali provides visibility into your service mesh by showing you the microservices in your service mesh, and how they are connected. - -include::modules/ossm-kiali-overview.adoc[leveloffset=+2] - -include::modules/ossm-kiali-architecture.adoc[leveloffset=+2] - -include::modules/ossm-kiali-features.adoc[leveloffset=+2] - -== Understanding Jaeger - -Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate to produce a response. -The path of this request is a distributed transaction. -Jaeger lets you perform distributed tracing, which follows the path of a request through various microservices that make up an application. - -*Distributed tracing* is a technique that is used to tie the information about different units of work together—usually executed in different processes or hosts—to understand a whole chain of events in a distributed transaction. -Distributed tracing lets developers visualize call flows in large service oriented architectures. -It can be invaluable in understanding serialization, parallelism, and sources of latency. - -Jaeger records the execution of individual requests across the whole stack of microservices, and presents them as traces. A *trace* is a data/execution path through the system. An end-to-end trace is comprised of one or more spans. - -A *span* represents a logical unit of work in Jaeger that has an operation name, the start time of the operation, and the duration. Spans may be nested and ordered to model causal relationships. - -include::modules/jaeger-product-overview.adoc[leveloffset=+2] - -include::modules/jaeger-architecture.adoc[leveloffset=+2] - -include::modules/jaeger-features.adoc[leveloffset=+2] - -== Next steps - -* xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Prepare to install {ProductName}] in your {product-title} environment. diff --git a/service_mesh/v2x/ossm-custom-resources.adoc b/service_mesh/v2x/ossm-custom-resources.adoc deleted file mode 100644 index 79c42f939381..000000000000 --- a/service_mesh/v2x/ossm-custom-resources.adoc +++ /dev/null @@ -1,48 +0,0 @@ -[id="ossm-custom-resources"] -= Custom resources -include::modules/ossm-document-attributes.adoc[] -:context: ossm-custom-resources-v2x - -toc::[] - -You can configure your {ProductName} by modifying the default {ProductShortName} custom resource or by creating a new custom resource. - -== Prerequisites -* An account with the `cluster-admin` role. -* Completed the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Preparing to install {ProductName}] process. -* Have installed the operators. - -include::modules/ossm-cr-example.adoc[leveloffset=+1] - -include::modules/ossm-cr-parameters.adoc[leveloffset=+1] - -include::modules/ossm-cr-istio-global.adoc[leveloffset=+2] - -include::modules/ossm-cr-gateway.adoc[leveloffset=+2] - -Cluster administrators can refer to xref:../../networking/ingress-operator.html#using-wildcard-routes_configuring-ingress[Using wildcard routes] for instructions on how to enable subdomains. - -include::modules/ossm-cr-mixer.adoc[leveloffset=+2] - -include::modules/ossm-cr-pilot.adoc[leveloffset=+2] - -include::modules/ossm-configuring-kiali.adoc[leveloffset=+1] - - -== Configuring Distributed Tracing - -When the {ProductShortName} Operator creates the `ServiceMeshControlPlane` resource it can also create the resources for distributed tracing. {ProductShortName} uses Jaeger for distributed tracing. - -include::modules/ossm-enabling-jaeger.adoc[leveloffset=+2] - -include::modules/ossm-configuring-jaeger.adoc[leveloffset=+2] - -For example Jaeger resources, see xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc[Configuring and deploying Jaeger]. - -include::modules/ossm-deploying-jaeger.adoc[leveloffset=+2] - -For more detailed information about customizing your Jaeger configuration, see xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc[Configuring and deploying Jaeger]. - -For more information about configuring Elasticsearch with {product-title}, see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] or xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc[Configuring and deploying Jaeger]. - -include::modules/ossm-cr-threescale.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-extensions.adoc b/service_mesh/v2x/ossm-extensions.adoc deleted file mode 100644 index de93a21a8f91..000000000000 --- a/service_mesh/v2x/ossm-extensions.adoc +++ /dev/null @@ -1,155 +0,0 @@ -[id="ossm-extensions"] -= Extensions -include::modules/ossm-document-attributes.adoc[] -:context: ossm-extensions - -toc::[] - -You can use WebAssembly extensions to add new features directly into the {ProductName} proxies, allowing you to move even more common functionality out of your applications, and implement them in a single language that compiles to WebAssembly bytecode. - -== WebAssembly extensions - -WebAssembly modules can be run on many platforms, including proxies, and has broad language support, fast execution and a sandboxed-by-default security model. - -.Extension Capabilities - -{ProductName} extensions are link:https://www.envoyproxy.io/docs/envoy/v1.16.0/intro/arch_overview/http/http_filters#arch-overview-http-filters[Envoy HTTP Filters], giving them a wide range of capabilities: - -* Manipulating the body and headers of requests and responses -* Out-of-band HTTP requests to services not in the request path, such as authentication or policy checking -* Side-channel data storage and queues for filters to communicate with each other - -There are two parts to writing a {ProductName} extension: you'll have to write your extension using an SDK that exposes the link:https://github.com/proxy-wasm/spec[proxy-wasm API] and compile it to a WebAssembly module, and then package it into a container. - -.Supported languages - -You can use any language that compiles to WebAssembly bytecode to write a {ProductName} extension, but the following languages have existing SDKs that expose the proxy-wasm API so that it can be consumed directly. - -.Supported languages -|=== -| Language | Maintainer | Repository - -| AssemblyScript -| solo.io -| link:https://github.com/solo-io/proxy-runtime[solo-io/proxy-runtime] - -| C++ -| proxy-wasm team (Istio Community) -| link:https://github.com/proxy-wasm/proxy-wasm-cpp-sdk[proxy-wasm/proxy-wasm-cpp-sdk] - -| Go -| tetrate.io -| link:https://github.com/tetratelabs/proxy-wasm-go-sdk[tetratelabs/proxy-wasm-go-sdk] - -| Rust -| proxy-wasm team (Istio Community) -| link:https://github.com/proxy-wasm/proxy-wasm-rust-sdk[proxy-wasm/proxy-wasm-rust-sdk] -|=== - -=== Container Format - -You must have a `.wasm` file containing the bytecode of your WebAssembly module, and a `manifest.yaml` file in the root of the container filesystem to make your container image a valid extension image. - -.manifest.yaml -[source,yaml] ----- -schemaVersion: 1 - -name: <your-extension> -description: <description> -version: 1.0.0 -phase: PreAuthZ -priority: 100 -module: extension.wasm ----- - -.manifest.yml Field Reference -|=== -| Field | Description - -|schemaVersion -|Used for versioning of the manifest schema. Currently the only possible value is `1`. - -|name -|The name of your extension. This field is just metadata and currently unused. - -|description -|The description of your extension. This field is just metadata and currently unused. - -|version -|The version of your extension. This field is just metadata and currently unused. - -|phase -|The default execution phase of your extension. This is a required field. - -|priority -|The default priority of your extension. This is a required field. - -|module -|The relative path from the container filesystem's root to your WebAssembly module. This is a required field. -|=== - -=== Example Rust extension - -For a complete example that was built using the Rust SDK, take a look at the link:https://github.com/maistra/header-append-filter[header-append-filter]. It is a very simple filter that appends a header, `custom-header`, to all responses, with the value depending on its configuration. - -=== Enabling WebAssembly extension support - -Support for WebAssembly extensions to {ProductName} is currently in Tech Preview, so it must be explicitly enabled for your `ServiceMeshControlPlane`. Set `spec.techPreview.wasmExtensions.enabled` in your SMCPv2 to `true`. Here's an example: - -[source,yaml] ----- -apiVersion: maistra.io/v2 -kind: ServiceMeshControlPlane -metadata: - name: openid-connect - namespace: istio-system -spec: - techPreview: - wasmExtensions: - enabled: true ----- - -=== Deploying extensions - -{ProductName} extensions can be enabled using the `ServiceMeshExtension` resource. The following snippet is an example resource. - -[source,yaml] ----- -apiVersion: maistra.io/v1alpha1 -kind: ServiceMeshExtension -metadata: - name: header-append - namespace: istio-system -spec: - workloadSelector: - labels: - app: httpbin - config: test - image: quay.io/maistra-dev/header-append-filter:latest - phase: PostAuthZ - priority: 100 ----- - -.ServiceMeshExtension Field Reference -|=== -| Field | Description - -|metadata.namespace -|The `metadata.namespace` of a `ServiceMeshExtension` source has a special semantic: if it equals the Control Plane Namespace, the extension will be applied to all workloads in the Service Mesh that match its `workloadSelector`. When deployed to any other Mesh Namespace, it will only be applied to workloads in that same Namespace. - -|spec.workloadSelector -|The `spec.workloadSelector` field has the same semantic as the `spec.selector` field of the link:https://istio.io/v1.6/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource]. It will match a workload based on its Pod labels. If no `workloadSelector` is specified, the extension will be applied to all workloads in the namespace. - -|spec.config -|This is a pass-through string field that will be handed over to the extension, so syntax and semantics are dependant on the extension you're deploying. - -|spec.image -|A container image URI pointing to the image that holds the extension. - -|spec.phase -|This field defaults to the value set in the `manifest.yaml` of the extension, but can be overwritten by the user. The phase determines where in the filter chain the extension is injected, in relation to existing Istio functionality like Authentication, Authorization and metrics generation. Valid values are: PreAuthN, PostAuthN, PreAuthZ, PostAuthZ, PreStats, PostStats. This field defaults to the value set in the `manifest.yaml` of the extension, but can be overwritten by the user. - -|spec.priority -|If multiple extensions with the same `spec.phase` are applied to the same workload instance, the `spec.priority` determines the ordering of execution. Extensions with higher priority will be executed first. This allows for inter-dependent extensions. This field defaults to the value set in the `manifest.yaml` of the extension, but can be overwritten by the user. -|=== diff --git a/service_mesh/v2x/ossm-observability.adoc b/service_mesh/v2x/ossm-observability.adoc deleted file mode 100644 index acb6d0d30c93..000000000000 --- a/service_mesh/v2x/ossm-observability.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="ossm-observability"] -= Data visualization and observability -include::modules/ossm-document-attributes.adoc[] -:context: observability - -toc::[] - -You can view your application's topology, health and metrics in the Kiali console. If your service is having issues, the Kiali console offers ways to visualize the data flow through your service. You can view insights about the mesh components at different levels, including abstract applications, services, and workloads. It also provides an interactive graph view of your namespace in real time. - -You can observe the data flow through your application if you have one installed. If you don't have your own application installed, you can see how observability works in {ProductName} by installing the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm[Bookinfo sample application]. - -After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command a few times: - ----- -$ curl http://$GATEWAY_URL/productpage ----- - -If your sample application is configured correctly, this command simulates a user visiting the `productpage` microservice of the application. - -include::modules/ossm-observability-access.adoc[leveloffset=+1] - -include::modules/ossm-observability-visual.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-performance-scalability.adoc b/service_mesh/v2x/ossm-performance-scalability.adoc deleted file mode 100644 index 4c20cee0750d..000000000000 --- a/service_mesh/v2x/ossm-performance-scalability.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="ossm-performance-scalability"] -= Performance and scalability -:context: performance-scalability - -toc::[] - -The default `ServiceMeshControlPlane` settings are not intended for production use; they are designed to install successfully on a default OpenShift installation, which is an extremely resource limited environment. After you have verified a successful SMCP installation, you should modify the settings defined within the SMCP to suit your environment. This section provides guidance for configuring {ProductName} for production use. - -See xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-custom-resources[Custom resources] for more information about the configurable fields in the `ServiceMeshControlPlane` resource. - -// The following include statements pull in the module files that comprise the assembly. - -include::modules/ossm-recommended-resources.adoc[leveloffset=+1] - -include::modules/ossm-load-test-results.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-security.adoc b/service_mesh/v2x/ossm-security.adoc deleted file mode 100644 index 727b121828b1..000000000000 --- a/service_mesh/v2x/ossm-security.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="ossm-security"] -= Customizing security in a Service Mesh -include::modules/ossm-document-attributes.adoc[] -:context: ossm-security - -toc::[] - -If your service mesh application is constructed with a complex array of microservices, you can use {ProductName} to customize the security of the communication between those services. The infrastructure of {product-title} along with the traffic management features of {ProductShortName} can help you manage the complexity of your applications and provide service and identity security for microservices. - -.Before you begin - -If you have a project, add your project to the xref:../../service_mesh/v2x/installing-ossm.adoc#ossm-member-roll-modify_installing-ossm[`ServiceMeshMemberRoll` resource]. - -[NOTE] -==== -After you add the namespace to the `ServiceMeshMemberRoll`, access to services or pods in that namespace will not be accessible to callers outside the mesh. -==== - -If you don't have a project, install the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm[Bookinfo sample application] and add it to the `ServiceMeshMemberRoll` resource. The sample application helps illustrate security concepts. - -include::modules/ossm-security-mtls.adoc[leveloffset=+1] - -include::modules/ossm-security-auth-policy.adoc[leveloffset=+1] - -include::modules/ossm-security-cipher.adoc[leveloffset=+1] - -include::modules/ossm-security-cert-manage.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-traffic-manage.adoc b/service_mesh/v2x/ossm-traffic-manage.adoc deleted file mode 100644 index 1eea5f7e7bbb..000000000000 --- a/service_mesh/v2x/ossm-traffic-manage.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="ossm-routing-traffic"] -= Traffic management -include::modules/ossm-document-attributes.adoc[] -:context: routing-traffic - -toc::[] - -You can control the flow of traffic and API calls between services in {ProductName}. For example, some services in your service mesh may need to communicate within the mesh and others may need to be hidden. Manage the traffic to hide specific backend services, expose services, create testing or versioning deployments, or add a security layer on a set of services. - -This guide references the Bookinfo sample application to provide examples of routing in an example application. Install the xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-tutorial-bookinfo-overview_deploying-applications-ossm[Bookinfo application] to learn how these routing examples work. - -include::modules/ossm-routing.adoc[leveloffset=+1] - -include::modules/ossm-routing-ingress.adoc[leveloffset=+1] - -include::modules/ossm-routing-bookinfo-example.adoc[leveloffset=+1] - -include::modules/ossm-auto-route.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-vs-community.adoc b/service_mesh/v2x/ossm-vs-community.adoc deleted file mode 100644 index 944d0c120872..000000000000 --- a/service_mesh/v2x/ossm-vs-community.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="ossm-vs-community"] -= Service Mesh and Istio differences -include::modules/ossm-document-attributes.adoc[] -:context: ossm-vs-istio - -toc::[] - -An installation of {ProductName} differs from upstream Istio community installations in multiple ways. The modifications to {ProductName} are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on {product-title}. - -The current release of {ProductName} differs from the current upstream Istio community release in the following ways: - -// The following include statements pull in the module files that comprise the assembly. - -include::modules/ossm-multitenant.adoc[leveloffset=+1] - -include::modules/ossm-vs-istio.adoc[leveloffset=+1] -[discrete] -[id="additional-resources_ossm-vs-istio-v2x"] -==== Additional resources - -* xref:../../service_mesh/v2x/ossm-traffic-manage.html#ossm-auto-route_routing-traffic[Automatic route creation] - -include::modules/ossm-kiali-service-mesh.adoc[leveloffset=+1] - -include::modules/ossm-jaeger-service-mesh.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc b/service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc deleted file mode 100644 index 917570c8606e..000000000000 --- a/service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="deploying-applications-ossm"] -= Deploying applications on {ProductName} -include::modules/ossm-document-attributes.adoc[] -:context: deploying-applications-ossm - -toc::[] - -When you deploy an application into the {ProductShortName}, there are several differences between the behavior of applications in the upstream community version of Istio and the behavior of applications within a {ProductName} installation. - -[NOTE] -==== -Do not deploy applications within the {ProductShortName} control plane namespace. The control plane (service mesh Operators, Istiod, and `ServiceMeshControlPlane`) and data plane (applications and Envoy proxy) must be in separate namespaces. -==== - -== Prerequisites - -* Review xref:../../service_mesh/v2x/ossm-vs-community.adoc#ossm-vs-community[{ProductName} and Istio differences] - -* Review xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[Installing {ProductName}] - - -include::modules/ossm-control-plane-profiles.adoc[leveloffset=+1] - -include::modules/ossm-sidecar-injection.adoc[leveloffset=+1] - -include::modules/ossm-automatic-sidecar-injection.adoc[leveloffset=+2] - -include::modules/ossm-config-network-policy.adoc[leveloffset=+1] - -include::modules/ossm-tutorial-bookinfo-overview.adoc[leveloffset=+1] - -include::modules/ossm-tutorial-bookinfo-install.adoc[leveloffset=+2] - -include::modules/ossm-tutorial-bookinfo-adding-destination-rules.adoc[leveloffset=+2] - -include::modules/ossm-tutorial-bookinfo-verify-install.adoc[leveloffset=+2] - -include::modules/ossm-tutorial-bookinfo-removing.adoc[leveloffset=+2] - -include::modules/ossm-tutorial-jaeger-generating-traces.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/preparing-ossm-installation.adoc b/service_mesh/v2x/preparing-ossm-installation.adoc deleted file mode 100644 index db2a1035cc09..000000000000 --- a/service_mesh/v2x/preparing-ossm-installation.adoc +++ /dev/null @@ -1,41 +0,0 @@ -[id="preparing-ossm-installation"] -= Preparing to install {ProductName} -include::modules/ossm-document-attributes.adoc[] -:context: preparing-ossm-installation - -toc::[] - -Before you can install {ProductName}, review the installation activities, ensure that you meet the prerequisites: - -== Prerequisites - -* Possess an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information. -* Review the xref:../../architecture/architecture-installation.adoc#installation-overview_architecture-installation[{product-title} {product-version} overview]. -* Install {product-title} {product-version}. -** xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Install {product-title} {product-version} on AWS] -** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Install {product-title} {product-version} on user-provisioned AWS] -** xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install {product-title} {product-version} on bare metal] -** xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Install {product-title} {product-version} on vSphere] -** xref:../../installing/installing_ibm_z/installing-ibm-z.adoc#installing-ibm-z[Install {product-title} 4.6 on IBM Z and LinuxONE] -** xref:../../installing/installing_ibm_power/installing-ibm-power.adoc#installing-ibm-power[Install {product-title} 4.6 on IBM Power Systems] -+ -[NOTE] -==== -If you are installing {ProductName} on a xref:../../installing/installing-preparing.adoc#supported-installation-methods-for-different-platforms[restricted network], follow the instructions for your chosen {product-title} infrastructure. -==== -+ -* Install the version of the {product-title} command line utility (the `oc` client tool) that matches your {product-title} version and add it to your path. -** If you are using {product-title} {product-version}, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-about-cli_cli-developer-commands[About the OpenShift CLI]. - -include::modules/ossm-supported-configurations.adoc[leveloffset=+1] - -include::modules/ossm-installation-activities.adoc[leveloffset=+1] - -[WARNING] -==== -Please see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] for details on configuring the default Jaeger parameters for Elasticsearch in a production environment. -==== - -== Next steps - -* xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[Install {ProductName}] in your {product-title} environment. diff --git a/service_mesh/v2x/removing-ossm.adoc b/service_mesh/v2x/removing-ossm.adoc deleted file mode 100644 index 946a2e5641c0..000000000000 --- a/service_mesh/v2x/removing-ossm.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="removing-ossm"] -= Removing {ProductName} -include::modules/ossm-document-attributes.adoc[] -:context: removing-ossm - -toc::[] - -This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. - -include::modules/ossm-member-roll-delete.adoc[leveloffset=+1] - -include::modules/ossm-control-plane-remove.adoc[leveloffset=+1] - -include::modules/ossm-remove-operators.adoc[leveloffset=+1] - -include::modules/ossm-remove-cleanup.adoc[leveloffset=+2] diff --git a/service_mesh/v2x/servicemesh-release-notes.adoc b/service_mesh/v2x/servicemesh-release-notes.adoc deleted file mode 100644 index 04f642040a49..000000000000 --- a/service_mesh/v2x/servicemesh-release-notes.adoc +++ /dev/null @@ -1,50 +0,0 @@ -[id="service-mesh-release-notes"] -= Service Mesh Release Notes -include::modules/ossm-document-attributes.adoc[] -:context: ossm-release-notes - -toc::[] - -// The following include statements pull in the module files that comprise 2.x release notes. - -include::modules/ossm-servicemesh-overview.adoc[leveloffset=+1] - -include::modules/support.adoc[leveloffset=+1] - -When opening a support case, it is helpful to provide debugging -information about your cluster to Red Hat Support. - -The `must-gather` tool enables you to collect diagnostic information about your -{product-title} cluster, including virtual machines and other data related to -{ProductName}. - -For prompt support, supply diagnostic information for both {product-title} -and {ProductName}. - -include::modules/about-must-gather.adoc[leveloffset=+2] - -=== Prerequisites - -* Access to the cluster as a user with the `cluster-admin` role. - -* The {product-title} CLI (`oc`) installed. - -include::modules/ossm-about-collecting-ossm-data.adoc[leveloffset=+2] - -include::modules/ossm-supported-configurations.adoc[leveloffset=+1] - -include::modules/ossm-rn-new-features.adoc[leveloffset=+1] - -include::modules/ossm-rn-technology-preview.adoc[leveloffset=+1] - -For more information about WebAssembly extensions, see xref:../../service_mesh/v2x/ossm-extensions.adoc#ossm-extensions[Extensions]. - -include::modules/ossm-rn-deprecated-features.adoc[leveloffset=+1] - -include::modules/ossm-rn-known-issues.adoc[leveloffset=+1] - -include::modules/jaeger-rn-known-issues.adoc[leveloffset=+2] - -include::modules/ossm-rn-fixed-issues.adoc[leveloffset=+1] - -include::modules/jaeger-rn-fixed-issues.adoc[leveloffset=+2] diff --git a/service_mesh/v2x/threescale-adapter.adoc b/service_mesh/v2x/threescale-adapter.adoc deleted file mode 100644 index fd2ad312f29b..000000000000 --- a/service_mesh/v2x/threescale-adapter.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="threescale-adapter"] -= Using the 3scale Istio adapter -include::modules/ossm-document-attributes.adoc[] -:context: threescale-adapter - -toc::[] - -The 3scale Istio Adapter is an optional adapter that allows you to label a service running within the {ProductName} and integrate that service with the 3scale API Management solution. -It is not required for {ProductName}. - -[IMPORTANT] -==== -If you want to enable 3scale backend cache with the 3scale Istio adapter, you must also enable Mixer policy and Mixer telemetry. See xref:../../service_mesh/v2x/installing-ossm.adoc#ossm-control-plane-deploy_installing-ossm[Deploying the Red Hat OpenShift Service Mesh control plane]. -==== - -include::modules/ossm-threescale-integrate.adoc[leveloffset=+1] - -include::modules/ossm-threescale-cr.adoc[leveloffset=+2] - -include::modules/ossm-threescale-templates.adoc[leveloffset=+3] - -include::modules/ossm-threescale-manifests.adoc[leveloffset=+2] - -include::modules/ossm-threescale-routing.adoc[leveloffset=+2] - -include::modules/ossm-threescale-integration-settings.adoc[leveloffset=+1] - -include::modules/ossm-threescale-caching.adoc[leveloffset=+1] - -include::modules/ossm-threescale-authentication.adoc[leveloffset=+1] - -include::modules/ossm-threescale-metrics.adoc[leveloffset=+1] - -include::modules/threescale-backend-cache.adoc[leveloffset=+1] - -include::modules/threescale-istio-adapter-apicast.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/upgrading-ossm.adoc b/service_mesh/v2x/upgrading-ossm.adoc deleted file mode 100644 index 25f2e63c021b..000000000000 --- a/service_mesh/v2x/upgrading-ossm.adoc +++ /dev/null @@ -1,524 +0,0 @@ -[id="upgrading-ossm"] -= Upgrading {ProductName} from version 1.1 to version 2.0 -include::modules/ossm-document-attributes.adoc[] -:context: upgrading-ossm - -toc::[] - -To access the most current features of {ProductName}, upgrade to the current version, 2.0. Upgrading from version 1.1 to 2.0 requires manual steps that migrate your workloads and apps to a new instance of {ProductName} running the new version. - -.Prerequisites - -* You must upgrade to {product-title} 4.7. before you upgrade to {ProductName} 2.0. -* You must have {ProductName} version 2.0 operator. If you selected the *automatic* upgrade path, the operator automatically downloads the latest information. However, there are steps you must take to use the features in {ProductName} version 2.0. - -[id="ossm-upgrading-upgrade_{context}"] -== Upgrading {ProductName} - -To upgrade {ProductName}, you must create an instance of {ProductName} `ServiceMeshControlPlane` v2 resource in a new namespace. Then, once it's configured, move your microservice applications and workloads from your old mesh to the new service mesh. - -.Procedure - -. Check your v1 `ServiceMeshControlPlane` resource configuration to make sure it is valid. -+ -.. Run the following command to view your `ServiceMeshControlPlane` resource as a v2 resource. -+ -[source,terminal] ----- -$ oc get smcp -o yaml ----- -+ -.. Check the `spec.techPreview.errored.message` field in the output for information about any invalid fields. -+ -.. If there are invalid fields in your v1 resource, the resource is not reconciled and cannot be edited as a v2 resource. All updates to v2 fields will be overridden by the original v1 settings. To fix the invalid fields, you can replace, patch, or edit the v1 version of the resource. You can also delete the resource without fixing it. After the resource has been fixed, it can be reconciled, and you can to modify or view the v2 version of the resource. -+ -.. To fix the resource by editing a file, use `oc get` to retrieve the resource, edit the text file locally, and replace the resource with the file you edited. -+ -[source,terminal] ----- -$ oc get smcp.v1.maistra.io <smcp_name> > smcp-resource.yaml -#Edit the smcp-resource.yaml file. -$ oc replace -f smcp-resource.yaml ----- -+ -.. To fix the resource using patching, use `oc patch`. -+ -[source,terminal] ----- -$ oc patch smcp.v1.maistra.io <smcp_name> --type json --patch '[{"op": "replace","path":"/spec/path/to/bad/setting","value":"corrected-value"}]' ----- -+ -.. To fix the resource by editing with command line tools, use `oc edit`. -+ -[source,terminal] ----- -$ oc edit smcp.v1.maistra.io <smcp_name> ----- -+ -. Back up your control plane configuration. Switch to the project that contains your `ServiceMeshControlPlane` resource. -+ -[source,terminal] ----- -$ oc project istio-system ----- -+ -. Enter the following command to retrieve the current configuration. Your <smcp_name> is specified in the metadata of your `ServiceMeshControlPlane` resource, for example `basic-install` or `full-install`. -+ -[source,terminal] ----- -$ oc get servicemeshcontrolplanes.v1.maistra.io <smcp_name> -o yaml > <smcp_name>.v1.yaml ----- -+ -. Convert your `ServiceMeshControlPlane` to a v2 control plane version that contains information about your configuration as a starting point. -+ -[source,terminal] ----- -$ oc get smcp <smcp_name> -o yaml > <smcp_name>.v2.yaml ----- -+ -. Create a project. In the {product-title} console Project menu, click `New Project` and enter a name for your project, `istio-system-upgrade`, for example. Or, you can run this command from the CLI. -+ -[source,terminal] ----- -$ oc new-project istio-system-upgrade ----- -+ -. Update the `metadata.namespace` field in your v2 `ServiceMeshControlPlane` with your new project name. In this example, use `istio-system-upgrade`. -+ -. Update the `version` field from 1.1 to 2.0 or remove it in your v2 `ServiceMeshControlPlane`. -+ -. Create a `ServiceMeshControlPlane` in the new namespace. On the command line, run the following command to deploy the control plane with the v2 version of the `ServiceMeshControlPlane` that you retrieved. In this example, replace `<smcp_name.v2> `with the path to your file. -+ -[source,terminal] ----- -$ oc create -n istio-system-upgrade -f <smcp_name>.v2.yaml ----- -+ -Alternatively, you can use the console to create the control plane. In the {product-title} web console, click *Project*. Then, select the project name you just entered. -+ -.. Click *Operators* -> *Installed Operators*. -.. Click *Create ServiceMeshControlPlane*. -.. Select *YAML view* and paste text of the YAML file you retrieved into the field. Check that the `apiVersion` field is set to `maistra.io/v2` and modify the `metadata.namespace` field to use the new namespace, for example `istio-system-upgrade`. -.. Click *Create*. - -[id="ossm-upgrading-differences_{context}"] -== Configuring the 2.0 `ServiceMeshControlPlane` - -The `ServiceMeshControlPlane` resource has been changed for {ProductName} version 2.0. After you created a v2 version of the `ServiceMeshControlPlane` resource, modify it to take advantage of the new features and to fit your deployment. Consider the following changes to the specification and behavior of {ProductName} 2.0 as you're modifying your `ServiceMeshControlPlane` resource. You can also refer to the {ProductName} 2.0 product documentation for new information to features you use. The v2 resource must be used for {ProductName} 2.0 installations. - -[id="ossm-upgrading-differences-arch_{context}"] -=== Architecture changes - -The architectural units used by previous versions have been replaced by Istiod. In 2.0 the control plane components Mixer, Pilot, Citadel, Galley, and the sidecar injector functionality have been combined into a single component, Istiod. - -Although Mixer is no longer supported as a control plane component, Mixer policy and telemetry plugins are now supported through WASM extensions in Istiod. Mixer can be enabled for policy and telemetry if you need to integrate legacy Mixer plugins. - -Secret Discovery Service (SDS) is used to distribute certificates and keys to sidecars directly from Istiod. In {ProductName} version 1.1, secrets were generated by Citadel, which were used by the proxies to retrieve their client certificates and keys. - -[id="ossm-upgrading-differences-annotation_{context}"] -=== Annotation changes - -The following annotations are no longer supported in v2.0. If you are using one of these annotations, you must update your workload before moving it to a v2.0 control plane. - -* `sidecar.maistra.io/proxyCPULimit` has been replaced with `sidecar.istio.io/proxyCPULimit`. If you were using `sidecar.maistra.io` annotations on your workloads, you must modify those workloads to use `sidecar.istio.io` equivalents instead. -* `sidecar.maistra.io/proxyMemoryLimit` has been replaced with `sidecar.istio.io/proxyMemoryLimit` -* `sidecar.istio.io/discoveryAddress` is no longer supported. Also, the default discovery address has moved from `pilot.<control_plane_namespace>.svc:15010` (or port 15011, if mtls is enabled) to `istiod-<smcp_name>.<control_plane_namespace>.svc:15012`. -* The health status port is no longer configurable and is hard-coded to 15021. * If you were defining a custom status port, for example, `status.sidecar.istio.io/port`, you must remove the override before moving the workload to a v2.0 control plane. Readiness checks can still be disabled by setting the status port to `0`. -* Kubernetes Secret resources are no longer used to distribute client certificates for sidecars. Certificates are now distributed through Istiod’s SDS service. If you were relying on mounted secrets, they are longer available for workloads in v2.0 control planes. - -[id="ossm-upgrading-differences-behavior_{context}"] -=== Behavioral changes - -Some features in {ProductName} 2.0 work differently than they did in previous versions. - -* The readiness port on gateways has moved from `15020` to `15021`. -* The target host visibility includes VirtualService, as well as ServiceEntry resources. It includes any restrictions applied through Sidecar resources. -* Automatic mutual TLS is enabled by default. Proxy to proxy communication is automatically configured to use mTLS, regardless of global PeerAuthentication policies in place. -* Secure connections are always used when proxies communicate with the control plane regardless of `spec.security.controlPlane.mtls` setting. The `spec.security.controlPlane.mtls` setting is only used when configuring connections for Mixer telemetry or policy. - -[id="ossm-upgrading-mig-unsupp_{context}"] -=== Migration details for unsupported resources - -.Policy (authentication.istio.io/v1alpha1) - -Policy resources must be migrated to new resource types for use with v2.0 control planes, PeerAuthentication and RequestAuthentication. Depending on the specific configuration in your Policy resource, you may have to configure multiple resources to achieve the same effect. - -.Mutual TLS - -Mutual TLS enforcement is accomplished using the `security.istio.io/v1beta1` PeerAuthentication resource. The legacy `spec.peers.mtls.mode` field maps directly to the new resource’s `spec.mtls.mode` field. Selection criteria has changed from specifying a service name in `spec.targets[x].name` to a label selector in `spec.selector.matchLabels`. In PeerAuthentication, the labels must match the selector on the services named in the targets list. Any port-specific settings will need to be mapped into `spec.portLevelMtls`. - -.Authentication - -Additional authentication methods specified in `spec.origins`, must be mapped into a `security.istio.io/v1beta1` RequestAuthentication resource. `spec.selector.matchLabels` must be configured similarly to the same field on PeerAuthentication. Configuration specific to JWT principals from `spec.origins.jwt` items map to similar fields in `spec.rules` items. - -* `spec.origins[x].jwt.triggerRules` specified in the Policy must be mapped into one or more `security.istio.io/v1beta1` AuthorizationPolicy resources. Any `spec.selector.labels` must be configured similarly to the same field on RequestAuthentication. -* `spec.origins[x].jwt.triggerRules.excludedPaths` must be mapped into an AuthorizationPolicy whose spec.action is set to ALLOW, with `spec.rules[x].to.operation.path` entries matching the excluded paths. -* `spec.origins[x].jwt.triggerRules.includedPaths` must be mapped into a separate AuthorizationPolicy whose `spec.action` is set to `ALLOW`, with `spec.rules[x].to.operation.path` entries matching the included paths, and `spec.rules.[x].from.source.requestPrincipals` entries that align with the `specified spec.origins[x].jwt.issuer` in the Policy resource. - -.ServiceMeshPolicy (maistra.io/v1) - -ServiceMeshPolicy was configured automatically for the control plane through the `spec.istio.global.mtls.enabled` in the v1 resource or `spec.security.dataPlane.mtls` in the v2 resource setting. For v2 control planes, a functionally equivalent PeerAuthentication resource is created during installation. This feature is deprecated in {ProductName} version 2.0 - -.RbacConfig, ServiceRole, ServiceRoleBinding (rbac.istio.io/v1alpha1) - -These resources were replaced by the `security.istio.io/v1beta1` AuthorizationPolicy resource. - -Mimicking RbacConfig behavior requires writing a default AuthorizationPolicy whose settings depend on the spec.mode specified in the RbacConfig. - -* When `spec.mode` is set to `OFF`, no resource is required as the default policy is ALLOW, unless an AuthorizationPolicy applies to the request. -* When `spec.mode` is set to ON, set `spec: {}`. You must create AuthorizationPolicy policies for all services in the mesh. -* `spec.mode` is set to `ON_WITH_INCLUSION`, must create an AuthorizationPolicy with `spec: {}` in each included namespace. Inclusion of individual services is not supported by AuthorizationPolicy. However, as soon as any AuthorizationPolicy is created that applies to the workloads for the service, all other requests not explicitly allowed will be denied. -* When `spec.mode` is set to `ON_WITH_EXCLUSION`, it is not supported by AuthorizationPolicy. A global DENY policy can be created, but an AuthorizationPolicy must be created for every workload in the mesh because there is no allow-all policy that can be applied to either a namespace or a workload. - -AuthorizationPolicy includes configuration for both the selector to which the configuration applies, which is similar to the function ServiceRoleBinding provides and the rules which should be applied, which is similar to the function ServiceRole provides. - -.ServiceMeshRbacConfig (maistra.io/v1) - -This resource is replaced by using a `security.istio.io/v1beta1` AuthorizationPolicy resource with an empty spec.selector in the control plane’s namespace. This policy will be the default authorization policy applied to all workloads in the mesh. For specific migration details, see RbacConfig above. - -[id="ossm-upgrading-mig-mixer_{context}"] -=== Mixer plugins - -Mixer components are disabled by default in version 2.0. If you rely on Mixer plugins for your workload, you must configure your version 2.0 `ServiceMeshControlPlane` to include the Mixer components. - -To enable the Mixer policy components, add the following snippet to your `ServiceMeshControlPlane`. - -[source,yaml] ----- -spec: - policy: - type: Mixer ----- - -To enable the Mixer telemetry components, add the following snippet to your `ServiceMeshControlPlane`. - -[source,yaml] ----- -spec: - telemetry: - type: Mixer ----- - -Legacy mixer plugins can also be migrated to WASM and integrated using the new ServiceMeshExtension (maistra.io/v1alpha1) custom resource. - -Built-in WASM filters included in the upstream Istio distribution are not available in {ProductName} 2.0. - -[id="ossm-upgrading-mig-mtls_{context}"] -=== Mutual TLS changes - -When using mTLS with workload specific PeerAuthentication policies, a corresponding DestinationRule is required to allow traffic if the workload policy differs from the namespace/global policy. - -Auto mTLS is enabled by default, but can be disabled by setting `spec.security.dataPlane.automtls` to false in the `ServiceMeshControlPlane` resource. When disabling auto mTLS, DestinationRules may be required for proper communication between services. For example, setting PeerAuthentication to `STRICT` for one namespace may prevent services in other namespaces from accessing them, unless a DestinationRule configures TLS mode for the services in the namespace. - -For information about mTLS, see xref:../../service_mesh/v2x/ossm-security.adoc#ossm-security-mtls_ossm-security[Enabling mutual Transport Layer Security (mTLS)] - -==== Other mTLS Examples - -To disable mTLS For productpage service in the bookinfo sample application, your Policy resource was configured the following way for {ProductName} v1.1. - -.Example Policy resource -[source,yaml] ----- -apiVersion: authentication.istio.io/v1alpha1 -kind: Policy -metadata: - name: productpage-mTLS-disable - namespace: <namespace> -spec: - targets: - - name: productpage ----- - -To disable mTLS For productpage service in the bookinfo sample application, use the following example to configure your PeerAuthentication resource for {ProductName} v2.0. - -.Example PeerAuthentication resource -[source,yaml] ----- -apiVersion: security.istio.io/v1beta1 -kind: PeerAuthentication -metadata: - name: productpage-mTLS-disable - namespace: <namespace> -spec: - mtls: - mode: DISABLE - selector: - matchLabels: - # this should match the selector for the "productpage" service - app: productpage ----- - -To enable mTLS With JWT authentication for the `productpage` service in the bookinfo sample application, your Policy resource was configured the following way for {ProductName} v1.1. - -.Example Policy resource -[source,yaml] ----- -apiVersion: authentication.istio.io/v1alpha1 -kind: Policy -metadata: - name: productpage-mTLS-with-JWT - namespace: <namespace> -spec: - targets: - - name: productpage - ports: - - number: 9000 - peers: - - mtls: - origins: - - jwt: - issuer: "https://securetoken.google.com/" - audiences: - - "productpage" - jwksUri: "https://www.googleapis.com/oauth2/v1/certs" - jwtHeaders: - - "x-goog-iap-jwt-assertion" - triggerRules: - - excludedPaths: - - exact: /health_check - principalBinding: USE_ORIGIN ----- - -To enable mTLS With JWT authentication for the productpage service in the bookinfo sample application, use the following example to configure your PeerAuthentication resource for {ProductName} v2.0. - -.Example PeerAuthentication resource -[source,yaml] ----- -#require mtls for productpage:9000 -apiVersion: security.istio.io/v1beta1 -kind: PeerAuthentication -metadata: - name: productpage-mTLS-with-JWT - namespace: <namespace> -spec: - selector: - matchLabels: - # this should match the selector for the "productpage" service - app: productpage - portLevelMtls: - 9000: - mode: STRICT -... -#JWT authentication for productpage -apiVersion: security.istio.io/v1beta1 -kind: RequestAuthentication -metadata: - name: productpage-mTLS-with-JWT - namespace: <namespace> -spec: - selector: - matchLabels: - # this should match the selector for the "productpage" service - app: productpage - jwtRules: - - issuer: "https://securetoken.google.com/" - audiences: - - "productpage" - jwksUri: "https://www.googleapis.com/oauth2/v1/certs" - fromHeaders: - - name: "x-goog-iap-jwt-assertion" -... -#Require JWT token to access product page service from -#any client to all paths except /health_check -apiVersion: security.istio.io/v1beta1 -kind: AuthorizationPolicy -metadata: - name: productpage-mTLS-with-JWT - namespace: <namespace> -spec: - action: ALLOW - selector: - matchLabels: - # this should match the selector for the "productpage" service - app: productpage - rules: - - to: # require JWT token to access all other paths - - operation: - notPaths: - - /health_check - from: - - source: - # if using principalBinding: USE_PEER in the Policy, - # then use principals, e.g. - # principals: - # - “*” - requestPrincipals: - - “*” - - to: # no JWT token required to access health_check - - operation: - paths: - - /health_check ----- - -[id="ossm-upgrading-config-recipes_{context}"] -== Configuration recipes - -You can configure the following items with these configuration recipes. - -[id="ossm-upgrading-config-mtls_{context}"] -=== Mutual TLS in a data plane - -Mutual TLS for data plane communication is configured through `spec.security.dataPlane.mtls` in the `ServiceMeshControlPlane` resource, which is `false` by default. - -[id="ossm-upgrading-config-sign-key_{context}"] -=== Custom signing key - -Istiod manages client certificates and private keys used by service proxies. By default, Istiod uses a self-signed certificate for signing, but you can configure a custom certificate and private key. For more information about how to configure signing keys, see xref:../../service_mesh/v2x/ossm-security.html#ossm-cert-manage_ossm-security[Adding an external certificate authority key and certificate] - -[id="ossm-upgrading-config-tracing_{context}"] -=== Tracing - -_Tracing_ is configured under `spec.tracing`. Currently, the only type of tracer that is supported is `Jaeger`. Sampling is a scaled integer representing 0.01% increments, for example, 1 is 0.01% and 10000 is 100%. The tracing implementation and sampling rate can be specified: - -[source,yaml] ----- -spec: - tracing: - sampling: 100 # 1% - type: Jaeger ----- - -_Jaeger_ is configured under the addons section of the SMCP spec. - -[source,yaml] ----- -spec: - addons: - jaeger: - name: jaeger - install: - storage: - type: Memory # or Elasticsearch for production mode - memory: - maxTraces: 100000 - elasticsearch: # the following values only apply if storage:type:=Elasticsearch - storage: # specific storageclass configuration for the Jaeger Elasticsearch (optional) - size: "100G" - storageClassName: "storageclass" - nodeCount: 3 - redundancyPolicy: SingleRedundancy - runtime: - components: - tracing.jaeger: {} # general Jaeger specific runtime configuration (optional) - tracing.jaeger.elasticsearch: #runtime configuration for Jaeger Elasticsearch deployment (optional) - container: - resources: - requests: - memory: "1Gi" - cpu: "500m" - limits: - memory: "1Gi" ----- - -The Jaeger installation can be customized with the `install` field. Container configuration, such as resource limits is configured in `spec.runtime.components.jaeger` related fields. If a Jaeger resource matching the value of `spec.addons.jaeger.name` exists, the control plane will be configured to use the existing installation. Use an existing Jaeger resource to fully customize your Jaeger installation. - -[id="ossm-upgrading-config-vis_{context}"] -=== Visualization - -Kiali and Grafana are configured under the addons section of the `ServiceMeshControlPlane` resource. - -[source,yaml] ----- -spec: - addons: - grafana: - enabled: true - install: {} # customize install - kiali: - enabled: true - name: kiali - install: {} # customize install ----- - -The Grafana and Kiali installations can be somewhat customized through their respective `install` fields. Container customization, such as resource limits, is configured in `spec.runtime.components.kiali` and `spec.runtime.components.grafana`. If an existing Kiali resource matching the value of name exists, the control plane configures the Kiali resource for use with the control plane. Some fields in the Kiali resource are overridden, such as the `accessible_namespaces` list, as well as the endpoints for Grafana, Prometheus, and tracing. Use an existing resource to fully customize your Kiali installation. - -=== Resource utilization and scheduling - -Resources are configured under `spec.runtime.<component>`. The following component names are supported. - -|=== -|Component |Description |Versions supported - -|security -|Citadel container -|v1.0/1.1 - -|galley -|Galley container -|v1.0/1.1 - -|pilot -|Pilot/Istiod container -|v1.0/1.1/2.0 - -|mixer -|istio-telemetry and istio-policy containers -|v1.0/1.1 - -|`mixer.policy` -|istio-policy container -|v2.0 - -|`mixer.telemetry` -|istio-telemetry container -|v2.0 - -|`global.ouathproxy` -|oauth-proxy container used with various addons -|v1.0/1.1/2.0 - -|`sidecarInjectorWebhook` -|sidecar injector webhook container -|v1.0/1.1 - -|`tracing.jaeger` -|general Jaeger container - not all settings may be applied. Complete customization of Jaeger installation is supported by specifying an existing Jaeger resource in the control plane configuration. -|v1.0/1.1/2.0 - -|`tracing.jaeger.agent` -|settings specific to Jaeger agent -|v1.0/1.1/2.0 - -|`tracing.jaeger.allInOne` -|settings specific to Jaeger allInOne -|v1.0/1.1/2.0 - -|`tracing.jaeger.collector` -|settings specific to Jaeger collector -|v1.0/1.1/2.0 - -|`tracing.jaeger.elasticsearch` -|settings specific to Jaeger elasticsearch deployment -|v1.0/1.1/2.0 - -|`tracing.jaeger.query` -|settings specific to Jaeger query -|v1.0/1.1/2.0 - -|prometheus -|prometheus container -|v1.0/1.1/2.0 - -|kiali -|Kiali container - complete customization of Kiali installation is supported by specifying an existing Kiali resource in the control plane configuration. -|v1.0/1.1/2.0 - -|grafana -|Grafana container -|v1.0/1.1/2.0 - -|3scale -|3scale container -|v1.0/1.1/2.0 - -|`wasmExtensions.cacher` -|WASM extensions cacher container -|v2.0 - tech preview -|=== - -For an example, of how to configure Pilot resource scheduling see xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-cr-pilot_ossm-custom-resources-v2x[Istio Pilot configuration] - -[id="ossm-upgrading-mig-apps_{context}"] -== Next steps for migrating your applications and workflows - -Move the application workload to the new mesh and remove the old instances to complete your upgrade. diff --git a/snippets/central-components.adoc b/snippets/central-components.adoc new file mode 100644 index 000000000000..09b6d675bb85 --- /dev/null +++ b/snippets/central-components.adoc @@ -0,0 +1,20 @@ +// Text snippet included in the following modules: +// * acs-central-services-overview.adoc +// * acscs-central-overview.adoc +// + +:_mod-docs-content-type: SNIPPET + +* *Central*: Central is the {product-title-short} application management interface and services. +It handles API interactions and user interface ({product-title-short} Portal) access. +You can use the same Central instance to secure multiple {ocp} or Kubernetes clusters. +* *Central DB*: Central DB is the database for {product-title-short} and handles all data persistence. It is currently based on PostgreSQL 13. +* *Scanner V4*: Beginning with version 4.4, {product-title-short} contains the Scanner V4 vulnerability scanner for scanning container images. Scanner V4 is built on link:https://github.com/quay/claircore[Claircore], which also powers the link:https://github.com/quay/clair[Clair] scanner. Scanner V4 supports language and OS-specific image components, node, and platform scanning. Scanner V4 contains the Indexer, Matcher, and DB components. +** *Scanner V4 Indexer*: The Scanner V4 Indexer performs image indexing, previously known as image analysis. Given an image and registry credentials, the Indexer pulls the image from the registry, finds the base operating system, if it exists, and looks for packages. The Indexer then stores and outputs an index report, which contains the findings for the given image. +** *Scanner V4 Matcher*: The Scanner V4 Matcher performs vulnerability matching. If the Indexer that is installed in Central indexed the image, then the Matcher fetches the index report from the Indexer and matches the report with the vulnerabilities stored in the Scanner V4 database. If the Indexer that is installed in a Secured Cluster performed the indexing, then the Matcher uses the index report that was sent from that Indexer, and then matches against vulnerabilities. The Matcher also fetches vulnerability data and updates the Scanner V4 database with the latest vulnerability data. The Scanner V4 Matcher outputs a vulnerability report, which contains the final results of an image. +** *Scanner V4 DB*: This database stores information for Scanner V4, including all vulnerability data and index reports. A persistent volume claim (PVC) is required for Scanner V4 DB on the cluster where Central is installed. +* *StackRox Scanner*: The StackRox Scanner originates from a fork of the Clair v2 open source scanner and was the default scanner for {product-title-short} before Scanner V4. +//If we are deprecating, this would be announced in release notes. +* *Scanner-DB*: This database contains data for the StackRox Scanner. + +The {product-title-short} scanner analyzes each image layer to determine the base operating system and identify programming language packages and packages that were installed by the operating system package manager. It matches the findings against known vulnerabilities from various vulnerability sources. In addition, it identifies vulnerabilities in the node's operating system and platform. \ No newline at end of file diff --git a/snippets/cluster-registration-secrets.adoc b/snippets/cluster-registration-secrets.adoc new file mode 100644 index 000000000000..efb7ac1b8b17 --- /dev/null +++ b/snippets/cluster-registration-secrets.adoc @@ -0,0 +1,13 @@ +// Snippets included in the following assemblies and modules: +// +// * installing/installing_ocp/init-bundle-ocp.adoc +// * installing/installing_other/init-bundle-other.adoc +// + +:_mod-docs-content-type: SNIPPET + +Cluster registration secrets (CRSes) offer improved security and are easier to use. CRSes contain a single token that can be used when installing {product-title-short} by using both Operator and Helm installation methods. + +CRSes provide better security because they are only used for registering a new secured cluster. If leaked, the certificates and keys in an init bundle can be used to impersonate services running on a secured cluster. By contrast, the certificate and key in a CRS can only be used for _registering_ a new cluster. + +After the cluster is set up by using the CRS, service-specific certificates are issued by Central and sent to the new secured cluster. These service certificates are used for communication between Central and secured clusters. Therefore, a CRS can be revoked after the cluster is registered without disconnecting secured clusters. diff --git a/snippets/field-trial.adoc b/snippets/field-trial.adoc new file mode 100644 index 000000000000..f47d066cd08f --- /dev/null +++ b/snippets/field-trial.adoc @@ -0,0 +1,11 @@ +// When including this file, ensure that {FeatureName} is set immediately before +// the include. Otherwise it will result in an incorrect replacement. + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} is available as a Field Trial release. A Field Trial provides approved customers access to {product-title-managed} for trial purposes. For more information, contact link:https://www.redhat.com/en/contact[Red{nbsp}Hat Sales]. + +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: \ No newline at end of file diff --git a/snippets/note-about-creating-tokens.adoc b/snippets/note-about-creating-tokens.adoc new file mode 100644 index 000000000000..8a7dbd80fadc --- /dev/null +++ b/snippets/note-about-creating-tokens.adoc @@ -0,0 +1,17 @@ +// Snippets included in the following assemblies and modules: +// +// * configuration/configure-api-token.adoc +// * cli/using-the-roxctl-cli.adoc +// * rbac-resource-definitions.adoc +// * operating/manage-user-access/configure-short-lived-access.adoc + +:_mod-docs-content-type: SNIPPET + +[NOTE] +==== +* To prevent privilege escalation, when you create a new token, your role's permissions limit the permission you can assign to that token. For example, if you only have `read` permission for the Integration resource, you cannot create a token with `write` permission. +* If you want a custom role to create tokens for other users to use, you must assign the required permissions to that custom role. +* Use short-lived tokens for machine-to-machine communication, such as CI/CD pipelines, scripts, and other automation. Also, use the `roxctl central login` command for human-to-machine communication, such as `roxctl` CLI or API access. +* The majority of cloud service providers support OIDC identity tokens, for example, Microsoft Entra ID, Google Cloud Identity Platform, and AWS Cognito. OIDC identity tokens issued by these services can be used for {product-title-short} short-lived access. +* Third-party OIDC identity tokens can also be used directly to access the API endpoint, without an exchange, if a machine-to-machine configuration exists for the token issuer. +==== diff --git a/snippets/scannerv4-default-secured-clusters.adoc b/snippets/scannerv4-default-secured-clusters.adoc new file mode 100644 index 000000000000..9986768c6d00 --- /dev/null +++ b/snippets/scannerv4-default-secured-clusters.adoc @@ -0,0 +1,8 @@ +// Text snippet included in the following modules: +// * acs-architecture-overview.adoc +// * acscs-architecture-overview.adoc +// + +:_mod-docs-content-type: SNIPPET + +When you install {product-title-short} on {ocp} by using the {product-title-short} Operator, or on {ocp} or any supported Kubernetes system by using Helm with the `secured-cluster-services` Helm chart, {product-title-short} installs the StackRox Scanner and Scanner V4 components on every secured cluster. This enables the scanning of images in the integrated OpenShift image registry or in any registry that {product-title-short} integrates with when delegated scanning is enabled. You can choose to not install the StackRox Scanner or Scanner V4 on the secured clusters and install them only on the cluster where Central is installed. For more information, see "Enabling Scanner V4". diff --git a/snippets/technology-preview.adoc b/snippets/technology-preview.adoc new file mode 100644 index 000000000000..dcf0471dda81 --- /dev/null +++ b/snippets/technology-preview.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: SNIPPET + +// When including this file, ensure that {FeatureName} is set immediately before +// the include. Otherwise it will result in an incorrect replacement. + +[IMPORTANT] +==== +[subs="attributes+"] +{FeatureName} is a Technology Preview feature only. Technology Preview features +are not supported with Red{nbsp}Hat production service level agreements (SLAs) and +might not be functionally complete. Red{nbsp}Hat does not recommend using them +in production. These features provide early access to upcoming product +features, enabling customers to test functionality and provide feedback during +the development process. + +For more information about the support scope of Red{nbsp}Hat Technology Preview +features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. +==== +// Undefine {FeatureName} attribute, so that any mistakes are easily spotted +:!FeatureName: \ No newline at end of file diff --git a/storage/container_storage_interface/ephemeral-storage-csi-inline.adoc b/storage/container_storage_interface/ephemeral-storage-csi-inline.adoc deleted file mode 100644 index 169780835d55..000000000000 --- a/storage/container_storage_interface/ephemeral-storage-csi-inline.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="ephemeral-storage-csi-inline"] -= CSI inline ephemeral volumes -include::modules/common-attributes.adoc[] -:context: ephemeral-storage-csi-inline - -toc::[] - -Container Storage Interface (CSI) inline ephemeral volumes allow you to define a `Pod` spec that creates inline ephemeral volumes when a pod is deployed and delete them when a pod is destroyed. - -This feature is only available with supported Container Storage Interface (CSI) drivers. - -:FeatureName: CSI inline ephemeral volumes - -include::modules/technology-preview.adoc[leveloffset=+0] - -include::modules/ephemeral-storage-csi-inline-overview.adoc[leveloffset=+1] - -include::modules/ephemeral-storage-csi-inline-pod.adoc[leveloffset=+1] diff --git a/storage/container_storage_interface/images b/storage/container_storage_interface/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/storage/container_storage_interface/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/storage/container_storage_interface/persistent-storage-csi-cinder.adoc b/storage/container_storage_interface/persistent-storage-csi-cinder.adoc deleted file mode 100644 index 13fa22a0010a..000000000000 --- a/storage/container_storage_interface/persistent-storage-csi-cinder.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="persistent-storage-csi-cinder"] -= OpenStack Cinder CSI Driver Operator -include::modules/common-attributes.adoc[] -:context: persistent-storage-csi-cinder - -toc::[] - -== Overview - -{product-title} is capable of provisioning persistent volumes (PVs) using the Container Storage Interface (CSI) driver for OpenStack Cinder. - -Familiarity with xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] and xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[configuring CSI volumes] is recommended when working with a Container Storage Interface (CSI) Operator and driver. - -To create CSI-provisioned PVs that mount to OpenStack Cinder storage assets, {product-title} installs the OpenStack Cinder CSI Driver Operator and the OpenStack Cinder CSI driver in the `openshift-cluster-csi-drivers` namespace. - -* The _OpenStack Cinder CSI Driver Operator_ provides a CSI storage class that you can use to create PVCs. - -* The _OpenStack Cinder CSI driver_ enables you to create and mount OpenStack Cinder PVs. - -include::modules/persistent-storage-csi-about.adoc[leveloffset=+1] -include::modules/persistent-storage-csi-cinder-storage-class.adoc[leveloffset=+1] - -.Additional resources -* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes] diff --git a/storage/container_storage_interface/persistent-storage-csi-cloning.adoc b/storage/container_storage_interface/persistent-storage-csi-cloning.adoc deleted file mode 100644 index a366ba82268d..000000000000 --- a/storage/container_storage_interface/persistent-storage-csi-cloning.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="persistent-storage-csi-cloning"] -= CSI volume cloning -include::modules/common-attributes.adoc[] -:context: persistent-storage-csi-cloning - -toc::[] - -Volume cloning duplicates an existing persistent volume to help protect against data loss in {product-title}. This feature is only available with supported Container Storage Interface (CSI) drivers. You should be familiar with xref:../../storage/understanding-persistent-storage.adoc#persistent-volumes_understanding-persistent-storage[persistent volumes] before you provision a CSI volume clone. - -include::modules/persistent-storage-csi-cloning-overview.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-cloning-provisioning.adoc[leveloffset=+1] diff --git a/storage/container_storage_interface/persistent-storage-csi-ebs.adoc b/storage/container_storage_interface/persistent-storage-csi-ebs.adoc deleted file mode 100644 index 967490011e66..000000000000 --- a/storage/container_storage_interface/persistent-storage-csi-ebs.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="persistent-storage-csi-ebs"] -= AWS Elastic Block Store CSI Driver Operator -include::modules/common-attributes.adoc[] -:context: persistent-storage-csi-ebs - -toc::[] - -== Overview - -{product-title} is capable of provisioning persistent volumes (PVs) using the Container Storage Interface (CSI) driver for AWS Elastic Block Store (EBS). - -:FeatureName: AWS EBS CSI Driver Operator -include::modules/technology-preview.adoc[leveloffset=+1] - -Familiarity with xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] and xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[configuring CSI volumes] is recommended when working with a Container Storage Interface (CSI) Operator and driver. - -To create CSI-provisioned PVs that mount to AWS EBS storage assets, {product-title} installs the AWS EBS CSI Driver Operator and the AWS EBS CSI driver by default in the `openshift-cluster-csi-drivers` namespace. - -* The _AWS EBS CSI Driver Operator_ provides a StorageClass by default that you can use to create PVCs. You also have the option to create the AWS EBS StorageClass as described in xref:../../storage/persistent_storage/persistent-storage-aws.adoc#persistent-storage-aws[Persistent storage using AWS Elastic Block Store]. - -* The _AWS EBS CSI driver_ enables you to create and mount AWS EBS PVs. - -[NOTE] -==== -If you installed the AWS EBS CSI Operator and driver on a {product-title} 4.5 cluster, you must uninstall the 4.5 Operator and driver before you update to {product-title} {product-version}. -==== - -include::modules/persistent-storage-csi-about.adoc[leveloffset=+1] - -[IMPORTANT] -==== -{product-title} defaults to using an in-tree, or non-CSI, driver to provision AWS EBS storage. This in-tree driver will be removed in a subsequent update of {product-title}. Volumes provisioned using the existing in-tree driver are planned for migration to the CSI driver at that time. -==== - -For information about dynamically provisioning AWS EBS persistent volumes in {product-title}, see xref:../../storage/persistent_storage/persistent-storage-aws.adoc#persistent-storage-aws[Persistent storage using AWS Elastic Block Store]. - -.Additional resources -* xref:../../storage/persistent_storage/persistent-storage-aws.adoc#persistent-storage-aws[Persistent storage using AWS Elastic Block Store] -* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes] diff --git a/storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc b/storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc deleted file mode 100644 index 137d7a6b32cf..000000000000 --- a/storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="persistent-storage-csi-gcp-pd"] -= GCP PD CSI Driver Operator -include::modules/common-attributes.adoc[] -:context: persistent-storage-csi-gcp-pd - -toc::[] - -== Overview - -{product-title} can provision persistent volumes (PVs) using the Container Storage Interface (CSI) driver for Google Cloud Platform (GCP) persistent disk (PD) storage. - -:FeatureName: GCP PD CSI Driver Operator -include::modules/technology-preview.adoc[leveloffset=+1] - -Familiarity with xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] and xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[configuring CSI volumes] is recommended when working with a Container Storage Interface (CSI) Operator and driver. - -To create CSI-provisioned persistent volumes (PVs) that mount to GCP PD storage assets, {product-title} installs the GCP PD CSI Driver Operator and the GCP PD CSI driver by default in the `openshift-cluster-csi-drivers` namespace. - -* *GCP PD CSI Driver Operator*: By default, the Operator provides a storage class that you can use to create PVCs. You also have the option to create the GCP PD storage class as described in xref:../../storage/persistent_storage/persistent-storage-gce.adoc#persistent-storage-using-gce[Persistent storage using GCE Persistent Disk]. - -* *GCP PD driver*: The driver enables you to create and mount GCP PD PVs. - -[IMPORTANT] -==== -{product-title} defaults to using an in-tree, or non-CSI, driver to provision GCP PD storage. This in-tree driver will be removed in a subsequent update of {product-title}. Volumes provisioned using the existing in-tree driver are planned for migration to the CSI driver at that time. -==== - -include::modules/persistent-storage-csi-about.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-gcp-pd-storage-class-ref.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-gcp-pd-encrypted-pv.adoc[leveloffset=+1] - -.Additional resources -* xref:../../storage/persistent_storage/persistent-storage-gce.adoc#persistent-storage-using-gce[Persistent storage using GCE Persistent Disk] -* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes] diff --git a/storage/container_storage_interface/persistent-storage-csi-manila.adoc b/storage/container_storage_interface/persistent-storage-csi-manila.adoc deleted file mode 100644 index 763c2c3b42f1..000000000000 --- a/storage/container_storage_interface/persistent-storage-csi-manila.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="persistent-storage-csi-manila"] -= OpenStack Manila CSI Driver Operator -include::modules/common-attributes.adoc[] -:context: persistent-storage-csi-manila - -toc::[] - -== Overview - -{product-title} is capable of provisioning persistent volumes (PVs) using the Container Storage Interface (CSI) driver for the link:https://wiki.openstack.org/wiki/Manila[OpenStack Manila] shared file system service. - -Familiarity with xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] and xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[configuring CSI volumes] is recommended when working with a Container Storage Interface (CSI) Operator and driver. - -To create CSI-provisioned PVs that mount to Manila storage assets, {product-title} installs the Manila CSI Driver Operator and the Manila CSI driver by default on any OpenStack cluster that has the Manila service enabled. - -* The _Manila CSI Driver Operator_ creates the required storage class that is needed to create PVCs for all available Manila share types. The Operator is installed in the `openshift-cluster-csi-drivers` namespace. - -* The _Manila CSI driver_ enables you to create and mount Manila PVs. The driver is installed in the `openshift-manila-csi-driver` namespace. - -include::modules/persistent-storage-csi-about.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-manila-dynamic-provisioning.adoc[leveloffset=+1] - -.Additional resources -* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes] diff --git a/storage/container_storage_interface/persistent-storage-csi-ovirt.adoc b/storage/container_storage_interface/persistent-storage-csi-ovirt.adoc deleted file mode 100644 index 9b1a6064560e..000000000000 --- a/storage/container_storage_interface/persistent-storage-csi-ovirt.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="persistent-storage-csi-ovirt"] -= Red Hat Virtualization CSI Driver Operator -include::modules/common-attributes.adoc[] -:context: persistent-storage-csi-ovirt - -toc::[] - -== Overview - -{product-title} is capable of provisioning persistent volumes (PVs) using the Container Storage Interface (CSI) driver for {rh-virtualization-first}. - -Familiarity with xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] and xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[configuring CSI volumes] is recommended when working with a Container Storage Interface (CSI) Operator and driver. - -To create CSI-provisioned PVs that mount to {rh-virtualization} storage assets, {product-title} installs the oVirt CSI Driver Operator and the oVirt CSI driver by default in the `openshift-cluster-csi-drivers` namespace. - -* The _oVirt CSI Driver Operator_ provides a default `StorageClass` object that you can use to create Persistent Volume Claims (PVCs). - -* The _oVirt CSI driver_ enables you to create and mount oVirt PVs. - -include::modules/persistent-storage-csi-about.adoc[leveloffset=+1] -include::modules/ovirt-csi-driver-storage-class.adoc[leveloffset=+1] -include::modules/persistent-storage-rhv.adoc[leveloffset=+1] - -.Additional resources -* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes] -* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#csi-dynamic-provisioning_persistent-storage-csi[Dynamic Provisioning] diff --git a/storage/container_storage_interface/persistent-storage-csi-snapshots.adoc b/storage/container_storage_interface/persistent-storage-csi-snapshots.adoc deleted file mode 100644 index ae919db93d16..000000000000 --- a/storage/container_storage_interface/persistent-storage-csi-snapshots.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="persistent-storage-csi-snapshots"] -= CSI volume snapshots -include::modules/common-attributes.adoc[] -:context: persistent-storage-csi-snapshots - -toc::[] - -This document describes how to use volume snapshots with supported Container Storage Interface (CSI) drivers to help protect against data loss in {product-title}. Familiarity with xref:../../storage/understanding-persistent-storage.adoc#persistent-volumes_understanding-persistent-storage[persistent volumes] is suggested. - -include::modules/persistent-storage-csi-snapshots-overview.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-snapshots-controller-sidecar.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-snapshots-operator.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-snapshots-provision.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-snapshots-create.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-snapshots-delete.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-snapshots-restore.adoc[leveloffset=+1] diff --git a/storage/container_storage_interface/persistent-storage-csi.adoc b/storage/container_storage_interface/persistent-storage-csi.adoc deleted file mode 100644 index 152b86ab1e52..000000000000 --- a/storage/container_storage_interface/persistent-storage-csi.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="persistent-storage-csi"] -= Configuring CSI volumes -include::modules/common-attributes.adoc[] -:context: persistent-storage-csi - -toc::[] - -The Container Storage Interface (CSI) allows {product-title} to consume -storage from storage back ends that implement the -link:https://github.com/container-storage-interface/spec[CSI interface] -as persistent storage. - -include::modules/persistent-storage-csi-architecture.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-external-controllers.adoc[leveloffset=+2] - -include::modules/persistent-storage-csi-driver-daemonset.adoc[leveloffset=+2] - -include::modules/persistent-storage-csi-drivers-supported.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-dynamic-provisioning.adoc[leveloffset=+1] - -include::modules/persistent-storage-csi-mysql-example.adoc[leveloffset=+1] diff --git a/storage/dynamic-provisioning.adoc b/storage/dynamic-provisioning.adoc deleted file mode 100644 index dcdcd7848e68..000000000000 --- a/storage/dynamic-provisioning.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="dynamic-provisioning"] -= Dynamic provisioning -include::modules/common-attributes.adoc[] -:context: dynamic-provisioning - -toc::[] - -include::modules/dynamic-provisioning-about.adoc[leveloffset=+1] - -include::modules/dynamic-provisioning-available-plugins.adoc[leveloffset=+1] - -include::modules/dynamic-provisioning-defining-storage-class.adoc[leveloffset=+1] - -include::modules/dynamic-provisioning-storage-class-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-annotations.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-cinder-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-manila-csi-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-aws-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-azure-disk-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-azure-file-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-azure-file-considerations.adoc[leveloffset=+3] - -include::modules/dynamic-provisioning-gce-definition.adoc[leveloffset=+2] - -// include::modules/dynamic-provisioning-gluster-definition.adoc[leveloffset=+2] - -// include::modules/dynamic-provisioning-ceph-rbd-definition.adoc[leveloffset=+2] - -include::modules/dynamic-provisioning-vsphere-definition.adoc[leveloffset=+2] - - -include::modules/dynamic-provisioning-change-default-class.adoc[leveloffset=+1] diff --git a/storage/expanding-persistent-volumes.adoc b/storage/expanding-persistent-volumes.adoc deleted file mode 100644 index b0c6bfbdf171..000000000000 --- a/storage/expanding-persistent-volumes.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="expanding-persistent-volumes"] -= Expanding persistent volumes -include::modules/common-attributes.adoc[] -:context: expanding-persistent-volumes - -toc::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/storage-expanding-add-volume-expansion.adoc[leveloffset=+1] - -include::modules/storage-expanding-csi-volumes.adoc[leveloffset=+1] - -:FeatureName: Expanding CSI volumes - -include::modules/technology-preview.adoc[leveloffset=+1] - -include::modules/storage-expanding-flexvolume.adoc[leveloffset=+1] - -include::modules/storage-expanding-filesystem-pvc.adoc[leveloffset=+1] - -include::modules/storage-expanding-recovering-failure.adoc[leveloffset=+1] -endif::openshift-enterprise,openshift-webscale,openshift-origin[] - -ifdef::openshift-dedicated[] -include::modules/dedicated-storage-expanding-filesystem-pvc.adoc[leveloffset=+1] -endif::openshift-dedicated[] diff --git a/storage/images b/storage/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/storage/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/storage/modules b/storage/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/storage/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/storage/persistent_storage/images b/storage/persistent_storage/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/storage/persistent_storage/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/storage/persistent_storage/persistent-storage-aws.adoc b/storage/persistent_storage/persistent-storage-aws.adoc deleted file mode 100644 index 677caa86d0b9..000000000000 --- a/storage/persistent_storage/persistent-storage-aws.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="persistent-storage-aws"] -= Persistent storage using AWS Elastic Block Store -include::modules/common-attributes.adoc[] -:context: persistent-storage-aws - -toc::[] - -{product-title} supports AWS Elastic Block Store volumes (EBS). You can -provision your {product-title} cluster with persistent storage by using link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/concepts.html[Amazon EC2]. -Some familiarity with Kubernetes and AWS is assumed. - -The Kubernetes persistent volume framework allows administrators to provision a -cluster with persistent storage and gives users a way to request those -resources without having any knowledge of the underlying infrastructure. -AWS Elastic Block Store volumes can be provisioned dynamically. -Persistent volumes are not bound to a single project or namespace; they can be -shared across the {product-title} cluster. -Persistent volume claims are specific to a project or namespace and can be -requested by users. - -[IMPORTANT] -==== -High-availability of storage in the infrastructure is left to the underlying -storage provider. -==== - -== Additional resources - -* See xref:../../storage/container_storage_interface/persistent-storage-csi-ebs.adoc#persistent-storage-csi-ebs[AWS Elastic Block Store CSI Driver Operator] for information about accessing additional storage options, such as volume snapshots, that are not possible with in-tree volume plug-ins. - -// Defining attributes required by the next module -:StorageClass: EBS -:Provisioner: kubernetes.io/aws-ebs - -include::modules/storage-create-storage-class.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-creating-volume-claim.adoc[leveloffset=+1] - -:provider: AWS -include::modules/storage-persistent-storage-volume-format.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-aws-maximum-volumes.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-azure-file.adoc b/storage/persistent_storage/persistent-storage-azure-file.adoc deleted file mode 100644 index 8cb306540fdc..000000000000 --- a/storage/persistent_storage/persistent-storage-azure-file.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="persistent-storage-using-azure-file"] -= Persistent storage using Azure File -include::modules/common-attributes.adoc[] -:context: persistent-storage-azure-file - -toc::[] - -{product-title} supports Microsoft Azure File volumes. You can -provision your {product-title} cluster with persistent storage using Azure. -Some familiarity with Kubernetes and Azure is assumed. - -The Kubernetes persistent volume framework allows administrators to provision a -cluster with persistent storage and gives users a way to request those -resources without having any knowledge of the underlying infrastructure. -Azure File volumes can be provisioned dynamically. - -Persistent volumes are not bound to a single project or namespace; they can be -shared across the {product-title} cluster. -Persistent volume claims are specific to a project or namespace and can be -requested by users for use in applications. - -[IMPORTANT] -==== -High availability of storage in the infrastructure is left to the underlying -storage provider. -==== - -.Additional resources - -* link:https://azure.microsoft.com/en-us/services/storage/files/[Azure Files] - -include::modules/storage-persistent-storage-azure-file.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-azure-file-pod.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-azure.adoc b/storage/persistent_storage/persistent-storage-azure.adoc deleted file mode 100644 index bc0ce88c4b68..000000000000 --- a/storage/persistent_storage/persistent-storage-azure.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="persistent-storage-using-azure"] -= Persistent storage using Azure -include::modules/common-attributes.adoc[] -:context: persistent-storage-azure - -toc::[] - -{product-title} supports Microsoft Azure Disk volumes. You can -provision your {product-title} cluster with persistent storage using Azure. -Some familiarity with Kubernetes and Azure is assumed. -The Kubernetes persistent volume framework allows administrators to provision a -cluster with persistent storage and gives users a way to request those -resources without having any knowledge of the underlying infrastructure. -Azure Disk volumes can be provisioned dynamically. -Persistent volumes are not bound to a single project or namespace; they can be -shared across the {product-title} cluster. -Persistent volume claims are specific to a project or namespace and can be -requested by users. - -[IMPORTANT] -==== -High availability of storage in the infrastructure is left to the underlying -storage provider. -==== - -.Additional resources - -* link:https://azure.microsoft.com/en-us/services/storage/disks[Microsoft Azure Disk] - -include::modules/storage-azure-create-storage-class.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-creating-volume-claim.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-azure-volume-format.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-cinder.adoc b/storage/persistent_storage/persistent-storage-cinder.adoc deleted file mode 100644 index ce5fb050d8a7..000000000000 --- a/storage/persistent_storage/persistent-storage-cinder.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="persistent-storage-cinder"] -= Persistent storage using Cinder -include::modules/common-attributes.adoc[] -:context: persistent-storage-cinder - -toc::[] - -{product-title} supports OpenStack Cinder. Some familiarity with Kubernetes and OpenStack is assumed. - -Cinder volumes can be provisioned dynamically. -Persistent volumes are not bound to a single project or namespace; they can be -shared across the {product-title} cluster. -Persistent volume claims are specific to a project or namespace and can be -requested by users. - -.Additional resources -* For more information about how OpenStack Block Storage provides persistent block storage management for virtual hard drives, see link:https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/8/html-single/architecture_guide/index#comp-cinder[OpenStack Cinder]. - -include::modules/persistent-storage-cinder-provisioning.adoc[leveloffset=+1] - -include::modules/persistent-storage-cinder-creating-pv.adoc[leveloffset=+2] - -include::modules/persistent-storage-cinder-pv-format.adoc[leveloffset=+2] - -include::modules/persistent-storage-cinder-volume-security.adoc[leveloffset=+2] diff --git a/storage/persistent_storage/persistent-storage-efs.adoc b/storage/persistent_storage/persistent-storage-efs.adoc deleted file mode 100644 index b15313f56ff9..000000000000 --- a/storage/persistent_storage/persistent-storage-efs.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id="persistent-storage-using-aws-efs"] -= Persistent storage using AWS Elastic File System -include::modules/common-attributes.adoc[] -:context: persistent-storage-efs - -toc::[] - -{product-title} allows use of Amazon Web Services (AWS) Elastic File System -volumes (EFS). You can provision your {product-title} cluster with persistent -storage using AWS EC2. Some familiarity with Kubernetes and AWS is assumed. - -:FeatureName: Elastic File System -include::modules/technology-preview.adoc[leveloffset=+0] - -The Kubernetes persistent volume framework allows administrators to provision a -cluster with persistent storage and gives users a way to request those -resources without having any knowledge of the underlying infrastructure. -AWS Elastic File System volumes can be provisioned dynamically. -Persistent volumes are not bound to a single project or namespace; they can be -shared across the {product-title} cluster. -Persistent volume claims are specific to a project or namespace and can be -requested by users. - -== Prerequisites -* Configure the AWS security groups to allow inbound NFS traffic -from the EFS volume's security group. -* Configure the AWS EFS volume to allow incoming SSH traffic from any host. - -.Additional resources - -* link:https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html[Amazon -EFS] -* link:https://docs.aws.amazon.com/efs/latest/ug/security-considerations.html#network-access[Amazon -security groups for EFS] - -include::modules/storage-persistent-storage-efs-configmap.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-efs-authorization.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-efs-storage-class.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-efs-provisioner.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-efs-pvc.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-fibre.adoc b/storage/persistent_storage/persistent-storage-fibre.adoc deleted file mode 100644 index 582a4c7a1624..000000000000 --- a/storage/persistent_storage/persistent-storage-fibre.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="persistent-storage-using-fibre"] -= Persistent storage using Fibre Channel -include::modules/common-attributes.adoc[] -:context: persistent-storage-fibre - -toc::[] - -{product-title} supports Fibre Channel, allowing you to provision your -{product-title} cluster with persistent storage using Fibre channel volumes. -Some familiarity with Kubernetes and Fibre Channel is assumed. - -The Kubernetes persistent volume framework allows administrators to provision a -cluster with persistent storage and gives users a way to request those -resources without having any knowledge of the underlying infrastructure. -Persistent volumes are not bound to a single project or namespace; they can be -shared across the {product-title} cluster. -Persistent volume claims are specific to a project or namespace and can be -requested by users. - -[IMPORTANT] -==== -High availability of storage in the infrastructure is left to the underlying -storage provider. -==== - -.Additional resources - -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_storage_devices/using-fibre-channel-devices_managing-storage-devices[Using Fibre Channel devices] - -include::modules/persistent-storage-fibre-provisioning.adoc[leveloffset=+1] - -include::modules/persistent-storage-fibre-disk-quotas.adoc[leveloffset=+2] - -include::modules/persistent-storage-fibre-volume-security.adoc[leveloffset=+2] diff --git a/storage/persistent_storage/persistent-storage-flexvolume.adoc b/storage/persistent_storage/persistent-storage-flexvolume.adoc deleted file mode 100644 index 7c916152266a..000000000000 --- a/storage/persistent_storage/persistent-storage-flexvolume.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="persistent-storage-using-flexvolume"] -= Persistent storage using FlexVolume -include::modules/common-attributes.adoc[] -:context: persistent-storage-flexvolume - -toc::[] - -{product-title} supports FlexVolume, an out-of-tree plug-in that uses an executable model to interface with drivers. - -To use storage from a back-end that does not have a built-in plug-in, you can extend {product-title} through FlexVolume drivers and provide persistent storage to applications. - -Pods interact with FlexVolume drivers through the `flexvolume` in-tree plugin. - -.Additional resources - -* xref:../../storage/expanding-persistent-volumes.adoc#expanding-persistent-volumes[Expanding persistent volumes] - -include::modules/persistent-storage-flexvolume-drivers.adoc[leveloffset=+1] - -include::modules/persistent-storage-flexvolume-driver-example.adoc[leveloffset=+1] - -include::modules/persistent-storage-flexvolume-installing.adoc[leveloffset=+1] - -include::modules/persistent-storage-flexvolume-consuming.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-gce.adoc b/storage/persistent_storage/persistent-storage-gce.adoc deleted file mode 100644 index 640ddd1466ca..000000000000 --- a/storage/persistent_storage/persistent-storage-gce.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id="persistent-storage-using-gce"] -= Persistent storage using GCE Persistent Disk -include::modules/common-attributes.adoc[] -:context: persistent-storage-gce - -toc::[] - -{product-title} supports GCE Persistent Disk volumes (gcePD). -You can provision your {product-title} cluster with persistent storage -using GCE. -Some familiarity with Kubernetes and GCE is assumed. - -The Kubernetes persistent volume framework allows administrators to -provision a cluster with persistent storage and gives users a way to -request those resources without having any knowledge of the underlying -infrastructure. - -GCE Persistent Disk volumes can be provisioned dynamically. - -Persistent volumes are not bound to a single project or namespace; -they can be shared across the {product-title} cluster. -Persistent volume claims are specific to a project or namespace and can be -requested by users. - -[IMPORTANT] -==== -High availability of storage in the infrastructure is left to the underlying -storage provider. -==== - -.Additional resources - -* link:https://cloud.google.com/compute/docs/disks/[GCE Persistent Disk] - -// Defining attributes required by the next module -:StorageClass: GCE -:Provisioner: kubernetes.io/gce-pd - -include::modules/storage-create-storage-class.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-creating-volume-claim.adoc[leveloffset=+1] - -:provider: GCE -include::modules/storage-persistent-storage-volume-format.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-hostpath.adoc b/storage/persistent_storage/persistent-storage-hostpath.adoc deleted file mode 100644 index 74a05bc328e7..000000000000 --- a/storage/persistent_storage/persistent-storage-hostpath.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="persistent-storage-using-hostpath"] -= Persistent storage using hostPath -include::modules/common-attributes.adoc[] -:context: persistent-storage-hostpath - -toc::[] - -A hostPath volume in an {product-title} cluster mounts a file or directory from the host node’s filesystem into your pod. Most pods will not need a hostPath volume, but it does offer a quick option for testing should an application require it. - -[IMPORTANT] -==== -The cluster administrator must configure pods to run as privileged. This grants access to pods in the same node. -==== - -include::modules/persistent-storage-hostpath-about.adoc[leveloffset=+1] -include::modules/persistent-storage-hostpath-static-provisioning.adoc[leveloffset=+1] -include::modules/persistent-storage-hostpath-pod.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-iscsi.adoc b/storage/persistent_storage/persistent-storage-iscsi.adoc deleted file mode 100644 index 0b56b8800e4e..000000000000 --- a/storage/persistent_storage/persistent-storage-iscsi.adoc +++ /dev/null @@ -1,47 +0,0 @@ -[id="persistent-storage-using-iscsi"] -= Persistent storage using iSCSI -include::modules/common-attributes.adoc[] -:context: persistent-storage-iscsi - -toc::[] - -You can provision your {product-title} cluster with -persistent storage using -https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Storage_Administration_Guide/ch-iscsi.html[iSCSI]. -Some familiarity with Kubernetes and iSCSI is assumed. - -The Kubernetes persistent volume framework allows administrators to -provision a cluster with persistent storage and gives users a way to -request those resources without having any knowledge of the -underlying infrastructure. - -[IMPORTANT] -==== -High-availability of storage in the infrastructure is left to the underlying -storage provider. -==== - -[IMPORTANT] -==== -When you use iSCSI on Amazon Web Services, you must update the default -security policy to include TCP traffic between nodes on the iSCSI ports. -By default, they are ports `860` and `3260`. -==== - -[IMPORTANT] -==== -OpenShift assumes that all nodes in the cluster have already configured iSCSI -initator, i.e. have installed `iscsi-initiator-utils` package and configured -their initiator name in `/etc/iscsi/initiatorname.iscsi`. See Storage -Administration Guide linked above. -==== - -include::modules/storage-persistent-storage-iscsi-provisioning.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-iscsi-volume-security.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-iscsi-multipath.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-iscsi-custom-initiator.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-local.adoc b/storage/persistent_storage/persistent-storage-local.adoc deleted file mode 100644 index 61769711f7ae..000000000000 --- a/storage/persistent_storage/persistent-storage-local.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="persistent-storage-using-local-volume"] -= Persistent storage using local volumes -include::modules/common-attributes.adoc[] -:context: persistent-storage-local - -toc::[] - -{product-title} can be provisioned with persistent storage by using -local volumes. Local persistent volumes allow you to access local storage -devices, such as a disk or partition, by using the standard -persistent volume claim interface. - -Local volumes can be used without manually scheduling pods to nodes -because the system is aware of the volume node constraints. However, -local volumes are still subject to the availability of the underlying node -and are not suitable for all applications. - -[NOTE] -==== -Local volumes can only be used as a statically created persistent volume. -==== - -include::modules/persistent-storage-local-install.adoc[leveloffset=+1] - -include::modules/persistent-storage-local-create-cr.adoc[leveloffset=+1] - -include::modules/persistent-storage-local-pvc.adoc[leveloffset=+1] - -include::modules/persistent-storage-local-pod.adoc[leveloffset=+1] - -include::modules/persistent-storage-local-discovery.adoc[leveloffset=+1] - -include::modules/persistent-storage-local-tolerations.adoc[leveloffset=+1] - -== Deleting the Local Storage Operator resources - -include::modules/persistent-storage-local-removing-devices.adoc[leveloffset=+2] - -include::modules/persistent-storage-local-uninstall-operator.adoc[leveloffset=+2] diff --git a/storage/persistent_storage/persistent-storage-nfs.adoc b/storage/persistent_storage/persistent-storage-nfs.adoc deleted file mode 100644 index 39ec3793a2dd..000000000000 --- a/storage/persistent_storage/persistent-storage-nfs.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="persistent-storage-using-nfs"] -= Persistent storage using NFS -include::modules/common-attributes.adoc[] -:context: persistent-storage-nfs - -toc::[] - -{product-title} clusters can be provisioned with persistent storage -using NFS. Persistent volumes (PVs) and persistent volume claims (PVCs) -provide a convenient method for sharing a volume across a project. While the -NFS-specific information contained in a PV definition could also be defined -directly in a `Pod` definition, doing so does not create the volume as a -distinct cluster resource, making the volume more susceptible to conflicts. - -.Additional resources - -* https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-nfs[Network File System (NFS)] - -include::modules/storage-persistent-storage-nfs-provisioning.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-nfs-enforcing-disk-quota.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-nfs-volume-security.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-nfs-group-ids.adoc[leveloffset=+2] - -include::modules/storage-persistent-storage-nfs-user-ids.adoc[leveloffset=+2] - -include::modules/storage-persistent-storage-nfs-selinux.adoc[leveloffset=+2] - -include::modules/storage-persistent-storage-nfs-export-settings.adoc[leveloffset=+2] - -include::modules/storage-persistent-storage-nfs-reclaiming-resources.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-nfs-additional-configuration.adoc[leveloffset=+1] diff --git a/storage/persistent_storage/persistent-storage-ocs.adoc b/storage/persistent_storage/persistent-storage-ocs.adoc deleted file mode 100644 index 31f481e2db93..000000000000 --- a/storage/persistent_storage/persistent-storage-ocs.adoc +++ /dev/null @@ -1,92 +0,0 @@ -[id="red-hat-openshift-container-storage"] -= Red Hat OpenShift Container Storage -include::modules/common-attributes.adoc[] -:context: persistent-storage-ocs - -toc::[] - -Red Hat OpenShift Container Storage is a provider of agnostic persistent storage for {product-title} supporting file, block, and object storage, either in-house or in hybrid clouds. As a Red Hat storage solution, Red Hat OpenShift Container Storage is completely integrated with {product-title} for deployment, management, and monitoring. - -Red Hat OpenShift Container Storage provides its own documentation library. The complete set of Red Hat OpenShift Container Storage documentation identified below is available at https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/ - -[IMPORTANT] -==== -OpenShift Container Storage on top of Red Hat Hyperconverged Infrastructure (RHHI) for Virtualization, which uses hyperconverged nodes that host virtual machines installed with {product-title}, is not a supported configuration. For more information about supported platforms, see the link:https://access.redhat.com/articles/4731161[Red Hat OpenShift Container Storage Supportability and Interoperability Guide]. -==== - -[options="header",cols="1,1"] -|=== - -|If you are looking for Red Hat OpenShift Container Storage information about... -|See the following Red Hat OpenShift Container Storage documentation: - -2+^| *Planning* - -|What’s new, known issues, notable bug fixes, and Technology Previews -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/4.6_release_notes/[Red Hat OpenShift Container Storage 4.6 Release Notes] - -|Supported workloads, layouts, hardware and software requirements, sizing and scaling recommendations -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/planning_your_deployment/index[Planning your Red Hat OpenShift Container Storage 4.6 deployment] - -2+^| *Deploying* - -|Preparing to deploy when your environment is not directly connected to the Internet -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/preparing_to_deploy_in_a_disconnected_environment/[Preparing to deploy OpenShift Container Storage 4.6 in a disconnected environment] - -|Deploying Red Hat OpenShift Container Storage using Amazon Web Services for local or cloud storage -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/deploying_openshift_container_storage_using_amazon_web_services/[Deploying OpenShift Container Storage 4.6 using Amazon Web Services] - -|Deploying Red Hat OpenShift Container Storage to local storage on bare metal infrastructure -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/deploying_openshift_container_storage_using_bare_metal_infrastructure//[Deploying OpenShift Container Storage 4.6 using bare metal infrastructure] - -|Deploying Red Hat OpenShift Container Storage to use an external Red Hat Ceph Storage cluster -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/deploying_openshift_container_storage_in_external_mode/[Deploying OpenShift Container Storage 4.6 in external mode] - -|Deploying and managing Red Hat OpenShift Container Storage on existing Google Cloud clusters -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/deploying_and_managing_openshift_container_storage_using_google_cloud/[Deploying and managing OpenShift Container Storage 4.6 using Google Cloud] - -|Deploying and managing Red Hat OpenShift Container Storage to use local storage on IBM Z infrastructure -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/deploying_and_managing_openshift_container_storage_using_ibm_z/[Deploying and managing OpenShift Container Storage using IBM Z] - -|Deploying and managing Red Hat OpenShift Container Storage on IBM Power Systems -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html-single/deploying_and_managing_openshift_container_storage_using_ibm_power_systems/[Deploying and managing OpenShift Container Storage using IBM Power Systems] - -|Deploying and managing Red Hat OpenShift Container Storage on {rh-openstack-first} -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/deploying_and_managing_openshift_container_storage_using_red_hat_openstack_platform/[Deploying and managing OpenShift Container Storage 4.6 using Red Hat OpenStack Platform] - -|Deploying and managing Red Hat OpenShift Container Storage on {rh-virtualization-first} -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/deploying_and_managing_openshift_container_storage_using_red_hat_virtualization_platform/[Deploying and managing OpenShift Container Storage 4.6 using Red Hat Virtualization Platform] - -|Deploying Red Hat OpenShift Container Storage on VMware vSphere clusters -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/deploying_openshift_container_storage_on_vmware_vsphere/[Deploying OpenShift Container Storage 4.6 on VMware vSphere] - -|Updating Red Hat OpenShift Container Storage to the latest version -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/updating_openshift_container_storage/[Updating OpenShift Container Storage] - -2+^| *Managing* - -|Allocating storage to core services and hosted applications in Red Hat OpenShift Container Storage, including snapshot and clone -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/managing_and_allocating_storage_resources/[Managing and allocating resources] - -|Managing storage resources across a hybrid cloud or multicloud environment using the Multicloud Object Gateway (NooBaa) -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/managing_hybrid_and_multicloud_resources/[Managing hybrid and multicloud resources] - -|Safely replacing storage devices for Red Hat OpenShift Container Storage -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/replacing_devices/[Replacing devices] - -|Safely replacing a node in a Red Hat OpenShift Container Storage cluster -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/replacing_nodes/[Replacing nodes] - -|Scaling operations in Red Hat OpenShift Container Storage -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/scaling_storage/[Scaling storage] - -|Monitoring a Red Hat OpenShift Container Storage 4.6 cluster -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/monitoring_openshift_container_storage/[Monitoring OpenShift Container Storage 4.6] - -|Troubleshooting errors and issues -|link:https://access.redhat.com/documentation/en-us/red_hat_openshift_container_storage/4.6/html/troubleshooting_openshift_container_storage/[Troubleshooting OpenShift Container Storage 4.6] - -|Migrating your {product-title} cluster from version 3 to version 4 -|link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.6/html/migration_toolkit_for_containers/[Migration Toolkit for Containers] - -|=== diff --git a/storage/persistent_storage/persistent-storage-vsphere.adoc b/storage/persistent_storage/persistent-storage-vsphere.adoc deleted file mode 100644 index faba6780cf79..000000000000 --- a/storage/persistent_storage/persistent-storage-vsphere.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[id="persistent-storage-using-vsphere"] -= Persistent storage using VMware vSphere volumes -include::modules/common-attributes.adoc[] -:context: persistent-storage-efs - -toc::[] - -{product-title} allows use of VMware vSphere’s Virtual Machine Disk (VMDK) volumes. You can provision your {product-title} cluster with persistent storage using VMware vSphere. Some familiarity with Kubernetes and VMware vSphere is assumed. - -VMware vSphere volumes can be provisioned dynamically. {product-title} creates the disk in vSphere and attaches this disk to the correct image. - -The Kubernetes persistent volume framework allows administrators to provision a -cluster with persistent storage and gives users a way to request those -resources without having any knowledge of the underlying infrastructure. - -Persistent volumes are not bound to a single project or namespace; they can be -shared across the {product-title} cluster. -Persistent volume claims are specific to a project or namespace and can be -requested by users. - -.Additional resources - -* link:https://www.vmware.com/au/products/vsphere.html[VMware vSphere] - -== Dynamically provisioning VMware vSphere volumes - -Dynamically provisioning VMware vSphere volumes is the recommended method. - -== Prerequisites -* An {product-title} cluster installed on a VMware vSphere version that meets the requirements for the components that you use. See xref:../../installing/installing_vsphere/installing-vsphere.adoc[Installing a cluster on vSphere] for information about vSphere version support. - -You can use either of the following procedures to dynamically provision these volumes using the default storage class. - -include::modules/persistent-storage-vsphere-dynamic-provisioning.adoc[leveloffset=+2] - -include::modules/persistent-storage-vsphere-dynamic-provisioning-cli.adoc[leveloffset=+2] - -include::modules/persistent-storage-vsphere-static-provisioning.adoc[leveloffset=+1] - -include::modules/persistent-storage-vsphere-formatting.adoc[leveloffset=+2] - -include::modules/persistent-storage-vsphere-backup.adoc[leveloffset=+1] diff --git a/storage/understanding-ephemeral-storage.adoc b/storage/understanding-ephemeral-storage.adoc deleted file mode 100644 index 15850103bc9e..000000000000 --- a/storage/understanding-ephemeral-storage.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="understanding-ephemeral-storage"] -= Understanding ephemeral storage -include::modules/common-attributes.adoc[] -:context: understanding-ephemeral-storage - -toc::[] - -include::modules/storage-ephemeral-storage-overview.adoc[leveloffset=+1] - -include::modules/storage-ephemeral-storage-types.adoc[leveloffset=+1] - -include::modules/storage-ephemeral-storage-manage.adoc[leveloffset=+1] - -include::modules/storage-ephemeral-storage-monitoring.adoc[leveloffset=+1] diff --git a/storage/understanding-persistent-storage.adoc b/storage/understanding-persistent-storage.adoc deleted file mode 100644 index a6b477fec621..000000000000 --- a/storage/understanding-persistent-storage.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="understanding-persistent-storage"] -= Understanding persistent storage -include::modules/common-attributes.adoc[] -:context: understanding-persistent-storage - -toc::[] - -include::modules/storage-persistent-storage-overview.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-lifecycle.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-reclaim-manual.adoc[leveloffset=+2] - -include::modules/storage-persistent-storage-reclaim.adoc[leveloffset=+2] - -include::modules/storage-persistent-storage-pv.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-pvc.adoc[leveloffset=+1] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -include::modules/storage-persistent-storage-block-volume.adoc[leveloffset=+1] - -// As these volumes have transitioned to being tech preview per plug-in, -// this notice has been included in the previous module. -// :FeatureName: Support for raw block volumes in the volume plug-ins listed above -// include::modules/technology-preview.adoc[leveloffset=+1] - -include::modules/storage-persistent-storage-block-volume-examples.adoc[leveloffset=+2] -endif::openshift-enterprise,openshift-webscale,openshift-origin[] diff --git a/support/gathering-cluster-data.adoc b/support/gathering-cluster-data.adoc deleted file mode 100644 index b01d0658b1e4..000000000000 --- a/support/gathering-cluster-data.adoc +++ /dev/null @@ -1,56 +0,0 @@ -[id="gathering-cluster-data"] -= Gathering data about your cluster -include::modules/common-attributes.adoc[] -include::modules/virt-document-attributes.adoc[] -:context: gathering-cluster-data - -toc::[] - -When opening a support case, it is helpful to provide debugging -information about your cluster to Red Hat Support. - -It is recommended to provide: - -* xref:../support/gathering-cluster-data.adoc#support_gathering_data_gathering-cluster-data[Data gathered using the `oc adm must-gather` command] -* The xref:../support/gathering-cluster-data.adoc#support-get-cluster-id_gathering-cluster-data[unique cluster ID] - -// About the must-gather tool -include::modules/about-must-gather.adoc[leveloffset=+1] - -// Gathering data about your cluster for Red Hat Support -include::modules/support-gather-data.adoc[leveloffset=+1] - -// Gathering data about specific features -include::modules/gathering-data-specific-features.adoc[leveloffset=+1] - -// Obtain your cluster identifier -include::modules/support-get-cluster-id.adoc[leveloffset=+1] - -// About `sosreport` -include::modules/about-sosreport.adoc[leveloffset=+1] - -// Generating a `sosreport` archive for an {product-title} cluster node -include::modules/support-generating-a-sosreport-archive.adoc[leveloffset=+1] - -// Querying bootstrap node journal logs -include::modules/querying-bootstrap-node-journal-logs.adoc[leveloffset=+1] - -// Querying cluster node journal logs -include::modules/querying-cluster-node-journal-logs.adoc[leveloffset=+1] - -// Collecting a network trace from an {product-title} node or container -include::modules/support-collecting-network-trace.adoc[leveloffset=+1] - -// Providing diagnostic data to Red Hat Support -include::modules/support-providing-diagnostic-data-to-red-hat.adoc[leveloffset=+1] - -// About `toolbox` -include::modules/about-toolbox.adoc[leveloffset=+1] - -// Installing packages to a toolbox container -[discrete] -include::modules/support-installing-packages-to-a-toolbox-container.adoc[leveloffset=+2] - -// Starting an alternative image with toolbox -[discrete] -include::modules/support-starting-an-alternative-image-with-toolbox.adoc[leveloffset=+2] diff --git a/support/getting-support.adoc b/support/getting-support.adoc index 3b0c509c04ba..c242917f9767 100644 --- a/support/getting-support.adoc +++ b/support/getting-support.adoc @@ -1,20 +1,38 @@ +:_mod-docs-content-type: ASSEMBLY [id="getting-support"] -= Getting support += Getting support for Red Hat Advanced Cluster Security for Kubernetes include::modules/common-attributes.adoc[] :context: getting-support toc::[] -// Getting support -ifdef::openshift-enterprise,openshift-webscale,openshift-dedicated,openshift-origin[] +This topic provides information about the technical support for {product-title}. + +If you experience difficulty with a procedure described in this documentation, or with {product-title} in general, visit the link:http://access.redhat.com[Red{nbsp}Hat Customer Portal]. From the Customer Portal, you can: + +* Search or browse through the Red{nbsp}Hat Knowledgebase of articles and solutions relating to Red{nbsp}Hat products. +* Submit a support case to Red{nbsp}Hat Support. +* Access other product documentation. + +If you have a suggestion for improving the documentation or have identified an error, create a link:https://red.ht/rhacsdocsissue[Jira issue] against the +*{product-title}* product for the *Documentation* component. +Ensure that you include specific details such as the section name and the version of {product-title} for us to manage your feedback effectively. -include::modules/support.adoc[leveloffset=+1] include::modules/support-knowledgebase-about.adoc[leveloffset=+1] include::modules/support-knowledgebase-search.adoc[leveloffset=+1] -include::modules/support-submitting-a-case.adoc[leveloffset=+1] -endif::openshift-enterprise,openshift-webscale,openshift-dedicated,openshift-origin[] +[id="generating-a-diagnostic-bundle"] +== Generating a diagnostic bundle +You can generate a diagnostic bundle and send that data to enable the support team to provide insights into the status and health of {product-title} components. -== Additional resources +[NOTE] +==== +The diagnostic bundle is unencrypted, and depending upon the number of clusters in your environment, the bundle size is between 100 KB and 1 MB. +==== -* For details about identifying issues with your cluster, see xref:../support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc#using-insights-to-identify-issues-with-your-cluster[Using Insights to identify issues with your cluster]. +include::modules/generate-diagnostic-bundle-using-acs-portal.adoc[leveloffset=+2] + +include::modules/generate-diagnostic-bundle-using-roxctl-cli.adoc[leveloffset=+2] + + +include::modules/support-submitting-a-case.adoc[leveloffset=+1] diff --git a/support/index.adoc b/support/index.adoc deleted file mode 120000 index 16a2bfca1482..000000000000 --- a/support/index.adoc +++ /dev/null @@ -1 +0,0 @@ -getting-support.adoc \ No newline at end of file diff --git a/support/remote_health_monitoring/about-remote-health-monitoring.adoc b/support/remote_health_monitoring/about-remote-health-monitoring.adoc deleted file mode 100644 index 51335bdb9ad8..000000000000 --- a/support/remote_health_monitoring/about-remote-health-monitoring.adoc +++ /dev/null @@ -1,95 +0,0 @@ -[id="about-remote-health-monitoring"] -= About remote health monitoring -include::modules/common-attributes.adoc[] -:context: about-remote-health-monitoring - -toc::[] - -{product-title} collects telemetry and configuration data about your cluster and reports it to Red Hat by using the Telemeter Client and the Insights Operator. The data that is provided to Red Hat enables the benefits outlined in this document. - -A cluster that reports data to Red Hat through Telemetry and the Insights Operator is considered a _connected cluster_. - -*Telemetry* is the term that Red Hat uses to describe the information being sent to Red Hat by the {product-title} Telemeter Client. Lightweight attributes are sent from connected clusters to Red Hat to enable subscription management automation, monitor the health of clusters, assist with support, and improve customer experience. - -The *Insights Operator* gathers {product-title} configuration data and sends it to Red Hat. The data is used to produce insights about potential issues that a cluster might be exposed to. These insights are communicated to cluster administrators on link:https://cloud.redhat.com/openshift[cloud.redhat.com/openshift]. - -More information is provided in this document about these two processes. - -.Telemetry and Insights Operator benefits - -Telemetry and the Insights Operator enable the following benefits for end-users: - -* *Enhanced identification and resolution of issues*. Events that might seem normal to an end-user can be observed by Red Hat from a broader perspective across a fleet of clusters. Some issues can be more rapidly identified from this point of view and resolved without an end-user needing to open a support case or file a Bugzilla. - -* *Advanced release management*. {product-title} offers the `candidate`, `fast`, and `stable` release channels, which enable you to choose an update strategy. The graduation of a release from `fast` to `stable` is dependent on the success rate of updates and on the events seen during upgrades. With the information provided by connected clusters, Red Hat can improve the quality of releases to `stable` channels and react more rapidly to issues found in the `fast` channels. - -* *Targeted prioritization of new features and functionality*. The data collected provides insights about which areas of {product-title} are used most. With this information, Red Hat can focus on developing the new features and functionality that have the greatest impact for our customers. - -* *A streamlined support experience*. You can provide a cluster ID for a connected cluster when creating a support ticket on the link:https://access.redhat.com/support/[Red Hat Customer Portal]. This enables Red Hat to deliver a streamlined support experience that is specific to your cluster, by using the connected information. This document provides more information about that enhanced support experience. - -* *Predictive analytics*. The insights displayed for your cluster on link:https://cloud.redhat.com/openshift/[cloud.redhat.com/openshift] are enabled by the information collected from connected clusters. Red Hat is investing in applying deep learning, machine learning, and artificial intelligence automation to help identify issues that {product-title} clusters are exposed to. - -ifdef::openshift-origin[] -{product-title} may be installed without a pull secret received at cloud.redhat.com. In this case default imagestreams will not be imported and telemetry data will not be sent. -endif::[] - -include::modules/telemetry-about-telemetry.adoc[leveloffset=+1] - -.Additional resources - -* See the xref:../../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[{product-title} update documentation] for more information about updating or upgrading a cluster. - -include::modules/telemetry-what-information-is-collected.adoc[leveloffset=+2] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#showing-data-collected-from-the-cluster_showing-data-collected-by-remote-health-monitoring[Showing data collected by Telemetry] for details about how to list the attributes that Telemetry gathers from Prometheus in {product-title}. - -* See the link:https://github.com/openshift/cluster-monitoring-operator/blob/master/manifests/0000_50_cluster-monitoring-operator_04-config.yaml[upstream cluster-monitoring-operator source code] for a list of the attributes that Telemetry gathers from Prometheus. - -* Telemetry is installed and enabled by default. If you need to opt out of remote health reporting, see xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting[Opting out of remote health reporting]. - -include::modules/insights-operator-about.adoc[leveloffset=+1] - -.Additional resources - -* The Insights Operator is installed and enabled by default. If you need to opt out of remote health reporting, see xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting[Opting out of remote health reporting]. - -include::modules/insights-operator-what-information-is-collected.adoc[leveloffset=+2] - -.Additional resources - -* See xref:../../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.html#insights-operator-showing-data-collected-from-the-cluster_showing-data-collected-by-remote-health-monitoring[Showing data collected by the Insights Operator] for details about how to review the data that is collected by the Insights Operator. - -* The Insights Operator source code is available for review and contribution. See the link:https://github.com/openshift/insights-operator/blob/master/docs/gathered-data.md[Insights Operator upstream project] for a list of the items collected by the Insights Operator. - -include::modules/understanding-telemetry-and-insights-operator-data-flow.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack_understanding-the-monitoring-stack[Understanding the monitoring stack] for more information about the {product-title} monitoring stack. - -* See xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[Configuring your firewall] for details about configuring a firewall and enabling endpoints for Telemetry and Insights - -[id="additional-details-about-how-remote-health-monitoring-data-is-used"] -== Additional details about how remote health monitoring data is used - -The information collected to enable remote health monitoring is detailed in xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#what-information-is-collected_about-remote-health-monitoring[Information collected by Telemetry] and xref:../../support/remote_health_monitoring/about-remote-health-monitoring.adoc#insights-operator-what-information-is-collected_about-remote-health-monitoring[Information collected by the Insights Operator]. - -As further described in the preceding sections of this document, Red Hat collects data about your use of the Red Hat Product(s) for purposes such as providing support and upgrades, optimizing performance or configuration, minimizing service impacts, identifying and remediating threats, troubleshooting, improving the offerings and user experience, responding to issues, and for billing purposes if applicable. - -.Collection safeguards - -Red Hat employs technical and organizational measures designed to protect the telemetry and configuration data. - -.Sharing - -Red Hat may share the data collected through Telemetry and the Insights Operator internally within Red Hat to improve your user experience. Red Hat may share telemetry and configuration data with its business partners in an aggregated form that does not identify customers to help the partners better understand their markets and their customers’ use of Red Hat offerings or to ensure the successful integration of products jointly supported by those partners. - -.Third party service providers - -Red Hat may engage certain service providers to assist in the collection and storage of the telemetry and configuration data. - -.User control / enabling and disabling telemetry and configuration data collection - -You may disable {product-title} Telemetry and the Insights Operator by following the instructions in xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#opting-out-remote-health-reporting[Opting out of remote health reporting]. diff --git a/support/remote_health_monitoring/images b/support/remote_health_monitoring/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/support/remote_health_monitoring/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/support/remote_health_monitoring/modules b/support/remote_health_monitoring/modules deleted file mode 120000 index 8b0e8540076d..000000000000 --- a/support/remote_health_monitoring/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules \ No newline at end of file diff --git a/support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc b/support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc deleted file mode 100644 index 4d37e6513fd2..000000000000 --- a/support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="opting-out-remote-health-reporting"] -= Opting out of remote health reporting -include::modules/common-attributes.adoc[] -:context: opting-out-remote-health-reporting - -toc::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -You may choose to opt out of reporting health and usage data for your cluster. -endif::[] - -ifdef::openshift-dedicated[] -On {product-title}, remote health reporting is always enabled. You cannot opt out. -endif::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] - -To opt out of remote health reporting, you must: - -. xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#insights-operator-new-pull-secret_opting-out-remote-health-reporting[Modify the global cluster pull secret] to disable remote health reporting. -. xref:../../support/remote_health_monitoring/opting-out-of-remote-health-reporting.adoc#images-update-global-pull-secret_opting-out-remote-health-reporting[Update the cluster] to use this modified pull secret. - -include::modules/telemetry-consequences-of-disabling-telemetry.adoc[leveloffset=+1] - -include::modules/insights-operator-new-pull-secret-disabled.adoc[leveloffset=+1] - -include::modules/images-update-global-pull-secret.adoc[leveloffset=+1] - -endif::[] diff --git a/support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc b/support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc deleted file mode 100644 index 814a9d4e0c38..000000000000 --- a/support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="showing-data-collected-by-remote-health-monitoring"] -= Showing data collected by remote health monitoring -include::modules/common-attributes.adoc[] -:context: showing-data-collected-by-remote-health-monitoring - -toc::[] - -As an administrator, you can review the metrics collected by Telemetry and the Insights Operator. - -include::modules/telemetry-showing-data-collected-from-the-cluster.adoc[leveloffset=+1] - -include::modules/insights-operator-showing-data-collected-from-the-cluster.adoc[leveloffset=+1] diff --git a/support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc b/support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc deleted file mode 100644 index 6ebca03f858c..000000000000 --- a/support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="using-insights-to-identify-issues-with-your-cluster"] -= Using Insights to identify issues with your cluster -include::modules/common-attributes.adoc[] -:context: using-insights-to-identify-issues-with-your-cluster - -toc::[] - -Insights repeatedly analyzes the data Insights Operator sends. Users of {product-title} can display the report on the *Insights* tab of each cluster in {cloud-redhat-com}. - -include::modules/displaying-potential-issues-with-your-cluster.adoc[leveloffset=+1] -include::modules/displaying-the-insights-status-in-the-web-console.adoc[leveloffset=+1] diff --git a/support/snippets b/support/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/support/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/support/summarizing-cluster-specifications.adoc b/support/summarizing-cluster-specifications.adoc deleted file mode 100644 index ac73da5571e2..000000000000 --- a/support/summarizing-cluster-specifications.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="summarizing-cluster-specifications"] -= Summarizing cluster specifications -include::modules/common-attributes.adoc[] -:context: summarizing-cluster-specifications - -toc::[] - -// Summarizing cluster specifications through `clusterversion` -include::modules/summarizing-cluster-specifications-through-clusterversion.adoc[leveloffset=+1] diff --git a/support/troubleshooting/diagnosing-oc-issues.adoc b/support/troubleshooting/diagnosing-oc-issues.adoc deleted file mode 100644 index cacbdd6cb6b3..000000000000 --- a/support/troubleshooting/diagnosing-oc-issues.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="diagnosing-oc-issues"] -= Diagnosing OpenShift CLI (`oc`) issues -include::modules/common-attributes.adoc[] -:context: diagnosing-oc-issues - -toc::[] - -// Understanding OpenShift CLI (`oc`) log levels -include::modules/understanding-oc-log-levels.adoc[leveloffset=+1] - -// Specifying OpenShift CLI (`oc`) log levels -include::modules/specifying-oc-log-levels.adoc[leveloffset=+1] diff --git a/support/troubleshooting/investigating-monitoring-issues.adoc b/support/troubleshooting/investigating-monitoring-issues.adoc deleted file mode 100644 index 3cfda1067bd0..000000000000 --- a/support/troubleshooting/investigating-monitoring-issues.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="investigating-monitoring-issues"] -= Investigating monitoring issues -include::modules/common-attributes.adoc[] -:context: investigating-monitoring-issues - -toc::[] - -{product-title} includes a pre-configured, pre-installed, and self-updating monitoring stack that provides monitoring for core platform components. In {product-title} {product-version}, cluster administrators can optionally enable monitoring for user-defined projects. - -// Note - please update the following sentence if you add further modules to this assembly. -You can follow these procedures if your own metrics are unavailable or if Prometheus is consuming a lot of disk space. - -// Investigating why user-defined metrics are unavailable -include::modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc[leveloffset=+1] - -.Additional resources - -* xref:../../monitoring/configuring-the-monitoring-stack.adoc#creating-user-defined-workload-monitoring-configmap_configuring-the-monitoring-stack[Creating a user-defined workload monitoring config map] -* See xref:../../monitoring/managing-metrics.adoc#specifying-how-a-service-is-monitored_managing-metrics[Specifying how a service is monitored] for details on how to create a service monitor or pod monitor - -// Determining why Prometheus is consuming a lot of disk space -include::modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc[leveloffset=+1] - -.Additional resources - -* See xref:../../monitoring/configuring-the-monitoring-stack.adoc#setting-a-scrape-sample-limit-for-user-defined-projects_configuring-the-monitoring-stack[Setting a scrape sample limit for user-defined projects] for details on how to set a scrape sample limit and create related alerting rules diff --git a/support/troubleshooting/investigating-pod-issues.adoc b/support/troubleshooting/investigating-pod-issues.adoc deleted file mode 100644 index ed38beb6fe4f..000000000000 --- a/support/troubleshooting/investigating-pod-issues.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="investigating-pod-issues"] -= Investigating pod issues -include::modules/common-attributes.adoc[] -:context: investigating-pod-issues - -toc::[] - -{product-title} leverages the Kubernetes concept of a pod, which is one or more containers deployed together on one host. A pod is the smallest compute unit that can be defined, deployed, and managed on {product-title} {product-version}. - -After a pod is defined, it is assigned to run on a node until its containers exit, or until it is removed. Depending on policy and exit code, Pods are either removed after exiting or retained so that their logs can be accessed. - -The first thing to check when pod issues arise is the pod's status. If an explicit pod failure has occurred, observe the pod's error state to identify specific image, container, or pod network issues. Focus diagnostic data collection according to the error state. Review pod event messages, as well as pod and container log information. Diagnose issues dynamically by accessing running Pods on the command line, or start a debug pod with root access based on a problematic pod's deployment configuration. - -// Understanding pod error states -include::modules/understanding-pod-error-states.adoc[leveloffset=+1] - -// Reviewing pod status -include::modules/reviewing-pod-status.adoc[leveloffset=+1] - -// Inspecting pod and container logs -include::modules/inspecting-pod-and-container-logs.adoc[leveloffset=+1] - -// Accessing running pods -include::modules/accessing-running-pods.adoc[leveloffset=+1] - -// Starting debug pods with root access -include::modules/starting-debug-pods-with-root-access.adoc[leveloffset=+1] - -// Copying files to and from pods and containers -include::modules/copying-files-pods-and-containers.adoc[leveloffset=+1] diff --git a/support/troubleshooting/troubleshooting-crio-issues.adoc b/support/troubleshooting/troubleshooting-crio-issues.adoc deleted file mode 100644 index 6ca794a07d77..000000000000 --- a/support/troubleshooting/troubleshooting-crio-issues.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="troubleshooting-crio-issues"] -= Troubleshooting CRI-O container runtime issues -include::modules/common-attributes.adoc[] -:context: troubleshooting-crio-issues - -toc::[] - -// About CRI-O container runtime engine -include::modules/about-crio.adoc[leveloffset=+1] - -// Verifying CRI-O runtime engine status -include::modules/verifying-crio-status.adoc[leveloffset=+1] - -// Gathering CRI-O journald unit logs -include::modules/gathering-crio-logs.adoc[leveloffset=+1] diff --git a/support/troubleshooting/troubleshooting-installations.adoc b/support/troubleshooting/troubleshooting-installations.adoc deleted file mode 100644 index 8844b5807d31..000000000000 --- a/support/troubleshooting/troubleshooting-installations.adoc +++ /dev/null @@ -1,51 +0,0 @@ -[id="troubleshooting-installations"] -= Troubleshooting installations -include::modules/common-attributes.adoc[] -:context: troubleshooting-installations - -toc::[] - -// Determining where installation issues occur -include::modules/determining-where-installation-issues-occur.adoc[leveloffset=+1] - -// User-provisioned infrastructure installation considerations -include::modules/upi-installation-considerations.adoc[leveloffset=+1] - -// Checking load balancer configuration before {product-title} installation -include::modules/checking-load-balancer-configuration.adoc[leveloffset=+1] - -// Specifying {product-title} installer log levels -include::modules/specifying-openshift-installer-log-levels.adoc[leveloffset=+1] - -// Troubleshooting `openshift-install` command issues -include::modules/troubleshooting-openshift-install-command-issues.adoc[leveloffset=+1] - -// Monitoring installation progress -include::modules/monitoring-installation-progress.adoc[leveloffset=+1] - -// Gathering bootstrap node diagnostic data -include::modules/gathering-bootstrap-diagnostic-data.adoc[leveloffset=+1] - -// Investigating master node installation issues -include::modules/investigating-master-node-installation-issues.adoc[leveloffset=+1] - -// Investigating etcd installation issues -include::modules/investigating-etcd-installation-issues.adoc[leveloffset=+1] - -// Investigating master node kubelet and API server issues -include::modules/investigating-kubelet-api-installation-issues.adoc[leveloffset=+1] - -// Investigating worker node installation issues -include::modules/investigating-worker-node-installation-issues.adoc[leveloffset=+1] - -// Querying Operator status after installation -include::modules/querying-operator-status-after-installation.adoc[leveloffset=+1] - -// Gathering logs from a failed installation -include::modules/installation-bootstrap-gather.adoc[leveloffset=+1] - -== Additional resources - -* See xref:../../architecture/architecture-installation.adoc#installation-process_architecture-installation[Installation process] for more details on {product-title} installation types and process. - -// TODO: xref to UPI recommendations for respective versions, with ifdefs. diff --git a/support/troubleshooting/troubleshooting-operating-system-issues.adoc b/support/troubleshooting/troubleshooting-operating-system-issues.adoc deleted file mode 100644 index f647ff2d993e..000000000000 --- a/support/troubleshooting/troubleshooting-operating-system-issues.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="troubleshooting-operating-system-issues"] -= Troubleshooting operating system issues -include::modules/common-attributes.adoc[] -:context: troubleshooting-operating-system-issues - -toc::[] - -{product-title} runs on {op-system}. You can follow these procedures to troubleshoot problems related to the operating system. - -// Investigating kernel crashes -include::modules/investigating-kernel-crashes.adoc[leveloffset=+1] diff --git a/support/troubleshooting/troubleshooting-operator-issues.adoc b/support/troubleshooting/troubleshooting-operator-issues.adoc deleted file mode 100644 index 01638e722877..000000000000 --- a/support/troubleshooting/troubleshooting-operator-issues.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="troubleshooting-operator-issues"] -= Troubleshooting Operator issues -include::modules/common-attributes.adoc[] -:context: troubleshooting-operator-issues - -toc::[] - -Operators are a method of packaging, deploying, and managing an {product-title} application. They act like an extension of the software vendor’s engineering team, watching over an {product-title} environment and using its current state to make decisions in real time. Operators are designed to handle upgrades seamlessly, react to failures automatically, and not take shortcuts, such as skipping a software backup process to save time. - -{product-title} {product-version} includes a default set of Operators that are required for proper functioning of the cluster. These default Operators are managed by the Cluster Version Operator (CVO). - -As a cluster administrator, you can install application Operators from the OperatorHub using the {product-title} web console or the CLI. You can then subscribe the Operator to one or more namespaces to make it available for developers on your cluster. Application Operators are managed by Operator Lifecycle Manager (OLM). - -If you experience Operator issues, verify Operator subscription status. Check Operator pod health across the cluster and gather Operator logs for diagnosis. - -// Operator Subscription condition types -include::modules/olm-status-conditions.adoc[leveloffset=+1] - -// Viewing Operator Subscription status using the CLI -include::modules/olm-status-viewing-cli.adoc[leveloffset=+1] - -// Querying Operator Pod status -include::modules/querying-operator-pod-status.adoc[leveloffset=+1] - -// Gathering Operator logs -include::modules/gathering-operator-logs.adoc[leveloffset=+1] - -// Disabling Machine Config Operator from autorebooting -include::modules/troubleshooting-disabling-autoreboot-mco.adoc[leveloffset=+1] -include::modules/troubleshooting-disabling-autoreboot-mco-console.adoc[leveloffset=+2] -include::modules/troubleshooting-disabling-autoreboot-mco-cli.adoc[leveloffset=+2] - -// Refreshing failing subscriptions -include::modules/olm-refresh-subs.adoc[leveloffset=+1] - diff --git a/support/troubleshooting/troubleshooting-s2i.adoc b/support/troubleshooting/troubleshooting-s2i.adoc deleted file mode 100644 index cb03cf5a27f8..000000000000 --- a/support/troubleshooting/troubleshooting-s2i.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="troubleshooting-s2i"] -= Troubleshooting the Source-to-Image process -include::modules/common-attributes.adoc[] -:context: troubleshooting-s2i - -toc::[] - -// Strategies for Source-to-Image troubleshooting -include::modules/strategies-for-s2i-troubleshooting.adoc[leveloffset=+1] - -// Gathering Source-to-Image diagnostic data -include::modules/gathering-s2i-diagnostic-data.adoc[leveloffset=+1] - -// Gathering application diagnostic data to investigate application failures -include::modules/gathering-application-diagnostic-data.adoc[leveloffset=+1] - -== Additional resources - -* See xref:../../cicd/builds/build-strategies.adoc#build-strategy-s2i_build-strategies[Source-to-Image (S2I) build] for more details about the S2I build strategy. diff --git a/support/troubleshooting/troubleshooting-storage-issues.adoc b/support/troubleshooting/troubleshooting-storage-issues.adoc deleted file mode 100644 index 6339b930b8e8..000000000000 --- a/support/troubleshooting/troubleshooting-storage-issues.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[id="troubleshooting-storage-issues"] -= Troubleshooting storage issues -include::modules/common-attributes.adoc[] -:context: troubleshooting-storage-issues - -toc::[] - -// Multi-attach error resolution -include::modules/storage-multi-attach-error.adoc[leveloffset=+1] diff --git a/support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc b/support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc deleted file mode 100644 index 9f16a6909794..000000000000 --- a/support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="troubleshooting-windows-container-workload-issues"] -= Troubleshooting Windows container workload issues -include::modules/common-attributes.adoc[] -:context: troubleshooting-windows-container-workload-issues - -toc::[] - -include::modules/wmco-does-not-install.adoc[leveloffset=+1] - -For more information, see xref:../../networking/ovn_kubernetes_network_provider/configuring-hybrid-networking.adoc#configuring-hybrid-ovnkubernetes[Configuring hybrid networking]. - -include::modules/investigating-why-windows-machine-compute-node.adoc[leveloffset=+1] - -[id="accessing-windows-node"] -== Accessing a Windows node - -Windows nodes cannot be accessed using the `oc debug node` command; the command requires running a privileged pod on the node, which is not yet supported for Windows. Instead, a Windows node can be accessed using a secure shell (SSH) or Remote Desktop Protocol (RDP). An SSH bastion is required for both methods. - -include::modules/accessing-windows-node-using-ssh.adoc[leveloffset=+2] -include::modules/accessing-windows-node-using-rdp.adoc[leveloffset=+2] - -include::modules/collecting-kube-node-logs-windows.adoc[leveloffset=+1] -include::modules/collecting-windows-application-event-logs.adoc[leveloffset=+1] -include::modules/collecting-docker-logs-windows.adoc[leveloffset=+1] - -== Additional resources - -* link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/troubleshooting[Containers on Windows troubleshooting] -* link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/update-containers#troubleshoot-host-and-container-image-mismatches[Troubleshoot host and container image mismatches] -* link:https://docs.docker.com/docker-for-windows/troubleshoot/[Docker for Windows troubleshooting] -* link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/kubernetes/common-problems[Common Kubernetes problems with Windows] diff --git a/support/troubleshooting/verifying-node-health.adoc b/support/troubleshooting/verifying-node-health.adoc deleted file mode 100644 index 1df50aea9fd2..000000000000 --- a/support/troubleshooting/verifying-node-health.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="verifying-node-health"] -= Verifying node health -include::modules/common-attributes.adoc[] -:context: verifying-node-health - -toc::[] - -// Reviewing node status, resource usage, and configuration -include::modules/reviewing-node-status-usage-and-configuration.adoc[leveloffset=+1] - -// Querying the kubelet's status on a node -include::modules/querying-kubelet-status-on-a-node.adoc[leveloffset=+1] - -// Querying node journal logs -include::modules/querying-cluster-node-journal-logs.adoc[leveloffset=+1] diff --git a/telemetry/about-telemetry.adoc b/telemetry/about-telemetry.adoc new file mode 100644 index 000000000000..afed16ff74c5 --- /dev/null +++ b/telemetry/about-telemetry.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: ASSEMBLY +[id="about-telemetry"] += About Telemetry +include::modules/common-attributes.adoc[] +:context: about-telemetry + +toc::[] + + +[role="_abstract"] +{rh-rhacs-first} collects anonymized aggregated information about product usage and product configuration. +It helps Red{nbsp}Hat understand how everyone uses the product and identify areas to prioritize for improvements. +In addition, Red{nbsp}Hat uses this information to improve the user experience. + +include::modules/information-collected-by-telemetry.adoc[leveloffset=+1] + diff --git a/telemetry/attributes b/telemetry/attributes new file mode 120000 index 000000000000..f27fd275ea6b --- /dev/null +++ b/telemetry/attributes @@ -0,0 +1 @@ +../_attributes/ \ No newline at end of file diff --git a/openshift_images/images b/telemetry/images similarity index 100% rename from openshift_images/images rename to telemetry/images diff --git a/metering/modules b/telemetry/modules similarity index 100% rename from metering/modules rename to telemetry/modules diff --git a/telemetry/opting-out-of-telemetry.adoc b/telemetry/opting-out-of-telemetry.adoc new file mode 100644 index 000000000000..53ef25e47826 --- /dev/null +++ b/telemetry/opting-out-of-telemetry.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY +[id="opting-out-of-telemetry"] += Opting out of Telemetry +include::modules/common-attributes.adoc[] +:context: opting-out-telemetry + +toc::[] + +[role="_abstract"] +The decision to opt out of telemetry should be based on your specific needs and requirements, as well as any applicable regulations or policies that you need to comply with. + +include::modules/consequences-of-disabling-telemetry.adoc[leveloffset=+1] + +include::modules/disabling-telemetry.adoc[leveloffset=+1] diff --git a/telemetry/snippets b/telemetry/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/telemetry/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/troubleshooting/attributes b/troubleshooting/attributes new file mode 120000 index 000000000000..f27fd275ea6b --- /dev/null +++ b/troubleshooting/attributes @@ -0,0 +1 @@ +../_attributes/ \ No newline at end of file diff --git a/troubleshooting/commonly-occurring-error-conditions.adoc b/troubleshooting/commonly-occurring-error-conditions.adoc new file mode 100644 index 000000000000..c09e6e7f78ab --- /dev/null +++ b/troubleshooting/commonly-occurring-error-conditions.adoc @@ -0,0 +1,43 @@ +:_mod-docs-content-type: ASSEMBLY +[id="commonly-occurring-error-conditions"] += Commonly occurring error conditions +include::modules/common-attributes.adoc[] +:context: error-conditions + +toc::[] + + +[role="_abstract"] +Most errors occur during Collector startup when Collector configures itself and loads eBPF probe into the system. + +Collector startup process involves the following stages: + +* Parse Configuration +* Analyze Host +* Connecting to Sensor +* Loading eBPF probe + +Failure at any step is considered fatal. If any part of the startup +procedure fails, the logs display a diagnostic summary with details about which steps +succeeded or failed. + +The following log file example shows a successful startup: + +[source,terminal] +---- +[INFO 2025/07/24 10:05:54] == Collector Startup Diagnostics: == +[INFO 2025/07/24 10:05:54] Connected to Sensor? false +[INFO 2025/07/24 10:05:54] Kernel driver candidates: +[INFO 2025/07/24 10:05:54] core_bpf (available) +[INFO 2025/07/24 10:05:54] Driver loaded into kernel: core_bpf +[INFO 2025/07/24 10:05:54] ==================================== +---- + +The log output confirms that Collector connected to Sensor and loaded the eBPF probe. +You can use this log to check for the successful startup of Collector. + + +include::modules/unable-to-connect-to-the-sensor.adoc[leveloffset=+1] + +include::modules/failing-to-load-the-ebpf-probe.adoc[leveloffset=+1] + diff --git a/post_installation_configuration/images b/troubleshooting/images similarity index 100% rename from post_installation_configuration/images rename to troubleshooting/images diff --git a/monitoring/modules b/troubleshooting/modules similarity index 100% rename from monitoring/modules rename to troubleshooting/modules diff --git a/troubleshooting/retrieving-and-analyzing-the-collector-logs-and-pod-status.adoc b/troubleshooting/retrieving-and-analyzing-the-collector-logs-and-pod-status.adoc new file mode 100644 index 000000000000..8aa673216319 --- /dev/null +++ b/troubleshooting/retrieving-and-analyzing-the-collector-logs-and-pod-status.adoc @@ -0,0 +1,24 @@ +:_mod-docs-content-type: ASSEMBLY +[id="retrieving-and-analyzing-the-collector-logs-and-pod-status"] += Retrieving and analyzing the Collector logs and pod status +include::modules/common-attributes.adoc[] +:context: logs-and-pod-status + +toc::[] + +[role="_abstract"] +The first step in troubleshooting is to retrieve the logs and pods status. +The logs allow you to identify the root cause of an error. +In addition, examining the pod's most recent status can provide information about failure messages. + + +include::modules/retrieving-the-collector-logs.adoc[leveloffset=+1] + +include::modules/retrieving-the-logs-with-the-oc-or-kubectl-command.adoc[leveloffset=+2] + +[id="retrieving-logs-from-a-rhacs-diagnostic-bundle_{context}"] +=== Retrieving logs from a {product-title-short} diagnostic bundle + +You can also access Collector logs by downloading a diagnostic bundle from the {product-title} ({product-title-short}) user interface. Once you have downloaded the diagnostic bundle, you can inspect the logs for all the Collector pods. For more information, see xref:../configuration/generate-diagnostic-bundle.adoc[Generating a diagnostic bundle]. + +include::modules/analyzing-the-collector-pod-status.adoc[leveloffset=+1] diff --git a/troubleshooting/snippets b/troubleshooting/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/troubleshooting/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/troubleshooting_central/attributes b/troubleshooting_central/attributes new file mode 120000 index 000000000000..f27fd275ea6b --- /dev/null +++ b/troubleshooting_central/attributes @@ -0,0 +1 @@ +../_attributes/ \ No newline at end of file diff --git a/troubleshooting_central/backing-up-central-database-by-using-the-roxctl-cli.adoc b/troubleshooting_central/backing-up-central-database-by-using-the-roxctl-cli.adoc new file mode 100644 index 000000000000..b3223c73f675 --- /dev/null +++ b/troubleshooting_central/backing-up-central-database-by-using-the-roxctl-cli.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: ASSEMBLY +[id="backing-up-central-database-by-using-the-roxctl-cli"] += Backing up Central database by using the roxctl CLI +include::modules/common-attributes.adoc[] +:context: backing-up-central-database-by-using-the-roxctl-cli + +toc::[] + +[role="_abstract"] +Central stores information about the following: + +* Activity observed in your clusters +* Information retrieved from integrated image registries or Scanners +* {rh-rhacs-first} configuration + +Backing up the Central database is critical to ensure data integrity and system reliability. Regular backups of the database, which contain the necessary configurations, resources, events, and certificates, protect against database failures, corruption, and accidental data loss. + +You can use the `roxctl` CLI to back up and restore the Central database by using the `backup` command. This command requires an API token or your administrator password. + +include::modules/on-demand-backups-roxctl-api.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage-user-access/manage-role-based-access-control-3630.adoc#rbac-system-roles-3630_manage-role-based-access-control[System roles] + +include::modules/on-demand-backups-roxctl-admin-pass.adoc[leveloffset=+1] diff --git a/virt/images b/troubleshooting_central/images similarity index 100% rename from virt/images rename to troubleshooting_central/images diff --git a/post_installation_configuration/modules b/troubleshooting_central/modules similarity index 100% rename from post_installation_configuration/modules rename to troubleshooting_central/modules diff --git a/troubleshooting_central/restoring-central-database-by-using-the-roxctl-cli.adoc b/troubleshooting_central/restoring-central-database-by-using-the-roxctl-cli.adoc new file mode 100644 index 000000000000..c325b67c28f7 --- /dev/null +++ b/troubleshooting_central/restoring-central-database-by-using-the-roxctl-cli.adoc @@ -0,0 +1,16 @@ +:_mod-docs-content-type: ASSEMBLY +[id="restoring-central-database-by-using-the-roxctl-cli"] += Restoring Central database by using the roxctl CLI +include::modules/common-attributes.adoc[] +:context: restoring-central-database-by-using-the-roxctl-cli + +toc::[] + +[role="_abstract"] +You can use the `roxctl` CLI to restore {rh-rhacs-first} by using the `restore` command. This command requires an API token or your administrator password. + +include::modules/restore-acs-roxctl-api.adoc[leveloffset=+1] + +include::modules/restore-acs-roxctl-admin-pass.adoc[leveloffset=+1] + +include::modules/resume-acs-restore.adoc[leveloffset=+1] \ No newline at end of file diff --git a/troubleshooting_central/snippets b/troubleshooting_central/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/troubleshooting_central/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/updating/images b/updating/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/updating/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/updating/modules b/updating/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/updating/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/updating/understanding-the-update-service.adoc b/updating/understanding-the-update-service.adoc deleted file mode 100644 index 92393c64789b..000000000000 --- a/updating/understanding-the-update-service.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="understanding-the-update-service"] -= Understanding the update service -include::modules/common-attributes.adoc[] -:context: understanding-the-update-service - -toc::[] - -include::modules/update-service-overview.adoc[leveloffset=+1] - -include::modules/unmanaged-operators.adoc[leveloffset=+1] diff --git a/updating/updating-cluster-between-minor.adoc b/updating/updating-cluster-between-minor.adoc deleted file mode 100644 index 008e13d66eb0..000000000000 --- a/updating/updating-cluster-between-minor.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="updating-cluster-between-minor"] -= Updating a cluster between minor versions -include::modules/common-attributes.adoc[] -:context: updating-cluster-between-minor - -toc::[] - -You can update, or upgrade, an {product-title} cluster between minor versions. - -[NOTE] -==== -Because of the difficulty of changing update channels by using `oc`, use the web console to change the update channel. It is recommended to complete the update process within the web console. You can follow the steps in xref:../updating/updating-cluster-cli.adoc#updating-cluster-cli[Updating a cluster within a minor version by using the CLI] to complete the update after you change to a {product-version} channel. -==== - -== Prerequisites - -* Have access to the cluster as a user with `admin` privileges. -See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. -* Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. -* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid upgrade path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster upgrade. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information. -* If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. - -[IMPORTANT] -==== -Using the `unsupportedConfigOverrides` section to modify the configuration of an Operator is unsupported and might block cluster upgrades. You must remove this setting before you can upgrade your cluster. -==== - -[IMPORTANT] -==== -If you are running cluster monitoring with an attached PVC for Prometheus, you might experience OOM kills during cluster upgrade. When persistent storage is in use for Prometheus, Prometheus memory usage doubles during cluster upgrade and for several hours after upgrade is complete. To avoid the OOM kill issue, allow worker nodes with double the size of memory that was available prior to the upgrade. For example, if you are running monitoring on the minimum recommended nodes, which is 2 cores with 8 GB of RAM, increase memory to 16 GB. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1925061[BZ#1925061]. -==== - -include::modules/update-service-overview.adoc[leveloffset=+1] -.Additional resources - -* xref:../architecture/architecture-installation.adoc#unmanaged-operators_architecture-installation[Support policy for unmanaged Operators] - -include::modules/understanding-upgrade-channels.adoc[leveloffset=+1] - -include::modules/update-upgrading-web.adoc[leveloffset=+1] diff --git a/updating/updating-cluster-cli.adoc b/updating/updating-cluster-cli.adoc deleted file mode 100644 index 04b18952e89f..000000000000 --- a/updating/updating-cluster-cli.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="updating-cluster-cli"] -= Updating a cluster within a minor version by using the CLI -include::modules/common-attributes.adoc[] -:context: updating-cluster-cli - -toc::[] - -You can update, or upgrade, an {product-title} cluster within a minor version by using the OpenShift CLI (`oc`). - -== Prerequisites - -* Have access to the cluster as a user with `admin` privileges. -See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. -* Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. -* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid upgrade path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster upgrade. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information. -* If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. - -[IMPORTANT] -==== -Using the `unsupportedConfigOverrides` section to modify the configuration of an Operator is unsupported and might block cluster upgrades. You must remove this setting before you can upgrade your cluster. -==== - -[IMPORTANT] -==== -If you are running cluster monitoring with an attached PVC for Prometheus, you might experience OOM kills during cluster upgrade. When persistent storage is in use for Prometheus, Prometheus memory usage doubles during cluster upgrade and for several hours after upgrade is complete. To avoid the OOM kill issue, allow worker nodes with double the size of memory that was available prior to the upgrade. For example, if you are running monitoring on the minimum recommended nodes, which is 2 cores with 8 GB of RAM, increase memory to 16 GB. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1925061[BZ#1925061]. -==== - -include::modules/update-service-overview.adoc[leveloffset=+1] -.Additional resources - -* xref:../architecture/architecture-installation.adoc#unmanaged-operators_architecture-installation[Support policy for unmanaged Operators] - -include::modules/understanding-upgrade-channels.adoc[leveloffset=+1] - -include::modules/update-upgrading-cli.adoc[leveloffset=+1] diff --git a/updating/updating-cluster-rhel-compute.adoc b/updating/updating-cluster-rhel-compute.adoc deleted file mode 100644 index 722f5b47ed84..000000000000 --- a/updating/updating-cluster-rhel-compute.adoc +++ /dev/null @@ -1,45 +0,0 @@ -[id="updating-cluster-rhel-compute"] -= Updating a cluster that includes RHEL compute machines -include::modules/common-attributes.adoc[] -:context: updating-cluster-rhel-compute - -toc::[] - -You can update, or upgrade, an {product-title} cluster. If your cluster contains -Red Hat Enterprise Linux (RHEL) machines, you must perform more steps to update -those machines. - -== Prerequisites - -* Have access to the cluster as a user with `admin` privileges. -See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. -* Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. -* If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. - -[IMPORTANT] -==== -If you are running cluster monitoring with an attached PVC for Prometheus, you might experience OOM kills during cluster upgrade. When persistent storage is in use for Prometheus, Prometheus memory usage doubles during cluster upgrade and for several hours after upgrade is complete. To avoid the OOM kill issue, allow worker nodes with double the size of memory that was available prior to the upgrade. For example, if you are running monitoring on the minimum recommended nodes, which is 2 cores with 8 GB of RAM, increase memory to 16 GB. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1925061[BZ#1925061]. -==== - -include::modules/update-service-overview.adoc[leveloffset=+1] -.Additional resources - -* xref:../architecture/architecture-installation.adoc#unmanaged-operators_architecture-installation[Support policy for unmanaged Operators] - -include::modules/understanding-upgrade-channels.adoc[leveloffset=+1] - -include::modules/update-upgrading-web.adoc[leveloffset=+1] - -[id="updating-cluster-rhel-compute-hooks"] -== Optional: Adding hooks to perform Ansible tasks on RHEL machines - -You can use _hooks_ to run Ansible tasks on the RHEL compute machines during -the {product-title} update. - -include::modules/rhel-compute-about-hooks.adoc[leveloffset=+2] - -include::modules/rhel-compute-using-hooks.adoc[leveloffset=+2] - -include::modules/rhel-compute-available-hooks.adoc[leveloffset=+2] - -include::modules/rhel-compute-updating.adoc[leveloffset=+1] diff --git a/updating/updating-cluster.adoc b/updating/updating-cluster.adoc deleted file mode 100644 index 21396296f63c..000000000000 --- a/updating/updating-cluster.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="updating-cluster"] -= Updating a cluster within a minor version from the web console -include::modules/common-attributes.adoc[] -:context: updating-cluster - -toc::[] - -You can update, or upgrade, an {product-title} cluster by using the web console. - -== Prerequisites - -* Have access to the cluster as a user with `admin` privileges. -See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. -* Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. -* If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. - -[IMPORTANT] -==== -If you are running cluster monitoring with an attached PVC for Prometheus, you might experience OOM kills during cluster upgrade. When persistent storage is in use for Prometheus, Prometheus memory usage doubles during cluster upgrade and for several hours after upgrade is complete. To avoid the OOM kill issue, allow worker nodes with double the size of memory that was available prior to the upgrade. For example, if you are running monitoring on the minimum recommended nodes, which is 2 cores with 8 GB of RAM, increase memory to 16 GB. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1925061[BZ#1925061]. -==== - -include::modules/update-service-overview.adoc[leveloffset=+1] -.Additional resources - -* xref:../architecture/architecture-installation.adoc#unmanaged-operators_architecture-installation[Support policy for unmanaged Operators] - -include::modules/understanding-upgrade-channels.adoc[leveloffset=+1] - -include::modules/update-upgrading-web.adoc[leveloffset=+1] diff --git a/updating/updating-restricted-network-cluster.adoc b/updating/updating-restricted-network-cluster.adoc deleted file mode 100644 index 0ee8e9b3aa7b..000000000000 --- a/updating/updating-restricted-network-cluster.adoc +++ /dev/null @@ -1,56 +0,0 @@ -[id="updating-restricted-network-cluster"] -= Updating a restricted network cluster -include::modules/common-attributes.adoc[] -:context: updating-restricted-network-cluster - -toc::[] - -You can upgrade a restricted network {product-title} cluster by using the `oc` command-line interface (CLI). - -A restricted network environment is the one in which your cluster nodes cannot access the internet. For this reason, you must populate a registry with the installation images. If your registry host cannot access both the internet and the cluster, you can mirror the images to a file system that disconnected from that environment and then bring that host or removable media across that gap. If the local container registry and the cluster are connected to the mirror registry's host, you can directly push the release images to the local registry. - -If multiple clusters are present within the restricted network, mirror the required release images to a single container image registry and use that registry to update all the clusters. - -== Prerequisites - -* Have access to the internet to obtain the necessary container images. -* Have write access to a container registry in the restricted-network environment to push and pull images. The container registry must be compatible with Docker registry API v2. -* You must have the `oc` command-line interface (CLI) tool installed. -* Have access to the cluster as a user with `admin` privileges. -See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. -* Have a recent xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your upgrade fails and you must xref:../backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. -* If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP]. - -[IMPORTANT] -==== -If you are running cluster monitoring with an attached PVC for Prometheus, you might experience OOM kills during cluster upgrade. When persistent storage is in use for Prometheus, Prometheus memory usage doubles during cluster upgrade and for several hours after upgrade is complete. To avoid the OOM kill issue, allow worker nodes with double the size of memory that was available prior to the upgrade. For example, if you are running monitoring on the minimum recommended nodes, which is 2 cores with 8 GB of RAM, increase memory to 16 GB. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=1925061[BZ#1925061]. -==== - -[id="updating-restricted-network-mirror-host"] -== Preparing your mirror host - -Before you perform the mirror procedure, you must prepare the host to retrieve content -and push it to the remote location. - -include::modules/cli-installing-cli.adoc[leveloffset=+2] - -// this file doesn't exist, so I'm including the one that should pick up more changes from Clayton's PR - modules/installation-adding-mirror-registry-pull-secret.adoc[leveloffset=+1] - -include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+1] - -include::modules/update-mirror-repository.adoc[leveloffset=+1] - -[id="updating-restricted-network-image-signature-configmap"] -== Creating the image signature config map - -Before you update your cluster, you must manually create a config map that contains the signatures of the release images that you use. This signature allows the Cluster Version Operator (CVO) to verify that the release images have not been modified by comparing the expected and actual image signatures. - -If you are upgrading from version 4.4.8 or later, you can use the `oc` CLI to create the config map. If you are upgrading from an earlier version, you must use the manual method. - -include::modules/update-oc-configmap-signature-verification.adoc[leveloffset=+2] - -include::modules/update-configuring-image-signature.adoc[leveloffset=+2] - -include::modules/update-restricted.adoc[leveloffset=+1] - -include::modules/images-configuration-registry-mirror.adoc[leveloffset=+1] diff --git a/updating/updating-troubleshooting.adoc b/updating/updating-troubleshooting.adoc deleted file mode 100644 index 87b7b1ee3af8..000000000000 --- a/updating/updating-troubleshooting.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="updating-troubleshooting"] -= Troubleshooting an update -include::modules/common-attributes.adoc[] -:context: updating-troubleshooting - -toc::[] - -In some situations, you can recover from a failed update of {product-title}. - -[IMPORTANT] -==== -If an update fails at any other point, you must contact Red Hat support. Rolling -your cluster back to a previous version is not supported. -==== - -include::modules/updating-clear.adoc[leveloffset=+1] diff --git a/applications/images b/upgrading/images similarity index 100% rename from applications/images rename to upgrading/images diff --git a/applications/projects/modules b/upgrading/modules similarity index 100% rename from applications/projects/modules rename to upgrading/modules diff --git a/upgrading/snippets b/upgrading/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/upgrading/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/upgrading/upgrade-helm.adoc b/upgrading/upgrade-helm.adoc new file mode 100644 index 000000000000..fc952ab961c8 --- /dev/null +++ b/upgrading/upgrade-helm.adoc @@ -0,0 +1,48 @@ +:_mod-docs-content-type: ASSEMBLY +[id="upgrade-helm"] += Upgrading using Helm charts +include::modules/common-attributes.adoc[] +:context: upgrade-helm + +toc::[] + +[role="_abstract"] +You must follow a specific upgrade path for {product-title-short} depending on the release of {product-title-short} that you are running. You must also back up your Central database before updating the Helm chart and performing the upgrade. + +If you have installed {product-title-short} by using Helm charts, to upgrade to the latest version of {product-title-short} perform the following steps: + +. Back up the Central database. +. Optionally, optimize Central's database and Persistent Volume Claims (PVC). +. Optionally, generate a `values-private.yaml` configuration file containing root certificates for the central-services Helm chart. +. Update the Helm chart. +. Run the `helm upgrade` command. + +[IMPORTANT] +==== +* To ensure optimal functionality, use the same version for your secured-cluster-services Helm chart and central-services Helm chart. +* To upgrade to {product-title-short} 4.8, which includes an upgrade to PostgreSQL 15, you must free up disk space. +Before beginning the upgrade, ensure you have free disk space that is at least double the size of your existing database. +==== + +include::modules/back-up-central-database.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../backup_and_restore/backing-up-acs.adoc#on-demand-backups-roxctl[On-demand backups by using the roxctl CLI] +* xref:../cli/installing-the-roxctl-cli.adoc#installing-the-roxctl-cli[Installing the roxctl CLI] + +include::modules/helm-optimize-central-db-and-pvc.adoc[leveloffset=+1] + +include::modules/helm-generate-root-certificates.adoc[leveloffset=+1] + +include::modules/updating-helm-repository.adoc[leveloffset=+1] + +[role="_additional-resources"] +== Additional resources +* xref:../installing/installing_ocp/install-central-ocp.adoc#install-using-helm-no-customizations-ocp[Installing Central using Helm charts] +* xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#installing-sc-helm[Installing {product-title-short} on secured clusters by using Helm charts] + +include::modules/upgrade-crd-helm.adoc[leveloffset=+1] +include::modules/upgrade-helm-chart.adoc[leveloffset=+1] + +include::modules/rollback-helm-upgrade.adoc[leveloffset=+1] diff --git a/upgrading/upgrade-operator.adoc b/upgrading/upgrade-operator.adoc new file mode 100644 index 000000000000..27fc5b225b1f --- /dev/null +++ b/upgrading/upgrade-operator.adoc @@ -0,0 +1,76 @@ +:_mod-docs-content-type: ASSEMBLY +[id="upgrade-operator"] += Upgrading by using the Operator +include::modules/common-attributes.adoc[] +:context: upgrade-operator + +toc::[] + +[role="_abstract"] +Upgrades through the {rh-rhacs-first} Operator are performed automatically or manually, depending on the *Update approval* option you chose at installation. + +Follow these guidelines when upgrading: + +* If the version for Central is earlier than 3.74, you must upgrade to 3.74 before upgrading to a 4.x version. For upgrading Central to version 3.74, see the link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_security_for_kubernetes/3.74/html/upgrading/index[upgrade documentation for version 3.74]. +* When upgrading Operator-based Central deployments from version 3.74, first ensure the Operator upgrade mode is set to `Manual`. Then, upgrade the Operator to version 4.0 following the procedure in the link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_security_for_kubernetes/4.0/html/upgrading/upgrade-operator[upgrade documentation for version 4.0] and ensure that Central is online. After the upgrade to version 4.0 is complete, Red{nbsp}Hat recommends upgrading Central to the latest version for full functionality. + +[IMPORTANT] +==== +To upgrade to {product-title-short} 4.8, which includes an upgrade to PostgreSQL 15, you must free up disk space. +Before beginning the upgrade, ensure you have free disk space that is at least double the size of your existing database. +==== + +include::modules/prepare-operator-upgrades.adoc[leveloffset=+1] +include::modules/change-collection-method.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* link:https://docs.openshift.com/container-platform/latest/operators/admin/olm-upgrading-operators.html[Updating installed Operators] +* xref:../backup_and_restore/backing-up-acs.adoc#backing-up-acs[Backing up {product-title}] + +include::modules/operator-upgrade-modify-central-custom-resource.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../backup_and_restore/backing-up-acs.adoc#backing-up-acs[Backing up {product-title}] +* xref:../backup_and_restore/restore-acs.adoc#restore-acs[Restoring from a backup] + +include::modules/operator-upgrade-modify-central-custom-resource-external-db.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../installing/installing_ocp/install-central-ocp.adoc#provision-postgresql-database_install-central-ocp[Provisioning a database in your PostgreSQL instance] + +include::modules/operator-upgrade-change-subscription-channel.adoc[leveloffset=+1] + +[id="rollback-operator-upgrade"] +== Rolling back an Operator upgrade + +To roll back an Operator upgrade, you must perform the steps described in one of the following sections. You can roll back an Operator upgrade by using the CLI or the {ocp} web console. + +[NOTE] +==== +* If you are rolling back from {product-title-short} 4.0, you can only roll back to the latest patch release version of {product-title-short} 3.74. +* If you are rolling back from {product-title-short} 4.8 or newer, you can only roll back to the latest patch release version of {product-title-short} 4.8. +==== + +include::modules/rollback-operator-upgrades-cli.adoc[leveloffset=+2] +include::modules/rollback-operator-upgrades-console.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources +* xref:../installing/installing_ocp/install-central-ocp.adoc#install-central-operator_install-central-ocp[Installing Central using the Operator method] +* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.15/html/operators/understanding-operators#olm-workflow[Operator Lifecycle Manager workflow] +* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.15/html/operators/administrator-tasks#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator update] + +[id="operator-upgrade-troubleshooting_{context}"] +== Troubleshooting Operator upgrade issues + +[role="_abstract"] +Follow these instructions to investigate and resolve upgrade-related issues for the {product-title-short} Operator. + +include::modules/operator-upgrade-centraldb-cannot-be-scheduled.adoc[leveloffset=+2] + +include::modules/operator-upgrade-fail-to-deploy.adoc[leveloffset=+2] diff --git a/upgrading/upgrade-roxctl.adoc b/upgrading/upgrade-roxctl.adoc new file mode 100644 index 000000000000..95926ab0ccda --- /dev/null +++ b/upgrading/upgrade-roxctl.adoc @@ -0,0 +1,119 @@ +:_mod-docs-content-type: ASSEMBLY +[id="upgrade-roxctl"] += Manually upgrading using the `roxctl` CLI +include::modules/common-attributes.adoc[] +:context: upgrade-roxctl + +toc::[] + +[role="_abstract"] +You can upgrade to the latest version of {rh-rhacs-first} from a supported older version. + +[IMPORTANT] +==== +* You need to perform the manual upgrade procedure only if you used the `roxctl` CLI to install {product-title-short}. +* There are manual steps for each version upgrade that must be followed, for example, from version 3.74 to version 4.0, and from version 4.0 to version 4.1. Therefore, Red{nbsp}Hat recommends upgrading first from 3.74 to 4.0, then from 4.0 to 4.1, then 4.1 to 4.2, until the selected version is installed. For full functionality, Red{nbsp}Hat recommends upgrading to the most recent version. +* Upgrading to {product-title-short} 4.8 includes an upgrade to PostgreSQL 15 and it requires additional free space on your disk. +Before starting the upgrade, ensure you have enough free disk space, ideally almost double the size of your existing database. +==== + +To upgrade {product-title-short} to the latest version, perform the following steps: + +. xref:../upgrading/upgrade-roxctl.adoc#back-up-central-database_upgrade-roxctl[Backup the Central database] +. xref:../upgrading/upgrade-roxctl.adoc#upgrade-roxctl-cli[Upgrade the `roxctl` CLI] +. xref:../upgrading/upgrade-roxctl.adoc#upgrade-central-cluster[Upgrade the Central cluster] +. xref:../upgrading/upgrade-roxctl.adoc#upgrade-secured-clusters[Upgrade all secured clusters] + +// include::modules/set-rox-scanner-init-db-env-variable.adoc[leveloffset=+1] + +include::modules/back-up-central-database.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../cli/using-the-roxctl-cli.adoc#authenticating-by-using-the-roxctl-cli_using-roxctl-cli[Authenticating by using the roxctl CLI] + +[id="upgrade-roxctl-cli"] +== Upgrading the `roxctl` CLI + +To upgrade the `roxctl` CLI to the latest version you must uninstall the existing version of `roxctl` CLI and then install the latest version of the `roxctl` CLI. + +include::modules/uninstall-roxctl-cli.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+2] + +[id="upgrade-central-cluster"] +== Upgrading the Central cluster + +After you have created a backup of the Central database and generated the necessary resources by using the provisioning bundle, the next step is to upgrade the Central cluster. This process requires upgrading the `SecurityPolicy` custom resource definition (CRD), Central, and Scanner. + +include::modules/upgrade-central-cluster-crds.adoc[leveloffset=+2] + +include::modules/upgrade-central-cluster-central.adoc[leveloffset=+2] + +include::modules/upgrade-central-cluster-scanner.adoc[leveloffset=+2] + +include::modules/verify-central-cluster-upgrade.adoc[leveloffset=+2] + +[id="upgrade-secured-clusters"] +== Upgrading all secured clusters + +After upgrading Central services, you must upgrade all secured clusters. + +[IMPORTANT] +==== +* If you are using automatic upgrades: +** Update all your secured clusters by using automatic upgrades. +** For information about troubleshooting problems with the automatic cluster upgrader, see xref:../upgrading/upgrade-roxctl.adoc#troubleshooting-upgrader_{context}[Troubleshooting the cluster upgrader]. +** Skip the instructions in this section and follow the instructions in the xref:../upgrading/upgrade-roxctl.adoc#verify-upgrades_{context}[Verify upgrades] and xref:../upgrading/upgrade-roxctl.adoc#revoke-the-api-token_{context}[Revoking the API token] sections. +* If you are not using automatic upgrades, you must run the instructions in this section on all secured clusters including the Central cluster. +** To ensure optimal functionality, use the same {product-title-short} version for your secured clusters and the cluster on which Central is installed. +==== + +To complete manual upgrades of each secured cluster running Sensor, Collector, and Admission controller, follow the instructions in this section. + +include::modules/update-other-images.adoc[leveloffset=+2] + +include::modules/add-pod-namespace-to-sensor-and-admission-control.adoc[leveloffset=+2] + +.Next steps +* xref:../upgrading/upgrade-roxctl.adoc#verify-secured-cluster-upgrade_upgrade-roxctl[Verifying secured cluster upgrade] + +[role="_additional-resources"] +.Additional resources +* xref:../upgrading/upgrade-roxctl.adoc#migrating-sccs-during-the-manual-upgrade_upgrade-roxctl[Migrating SCCs during the manual upgrade] + +include::modules/migrating-sccs-during-the-manual-upgrade.adoc[leveloffset=+2] + +include::modules/verify-secured-cluster-upgrade.adoc[leveloffset=+3] + +include::modules/rhcos-enable-node-scan.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage-vulnerabilities/scan-rhcos-node-host.adoc#scan-rhcos-node-host[Scanning {op-system} node hosts] + +[id="rollback-central"] +== Rolling back Central + +You can roll back to a previous version of Central if the upgrade to a new version is unsuccessful. + +include::modules/rollback-central-normal.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../installing/installing_ocp/install-central-config-options-ocp.adoc#adding-an-environment-variable-to-a-deployment_install-central-config-options-ocp[Injecting an environment variable into the Central deployment] + +include::modules/rollback-central-forced.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../installing/installing_ocp/install-central-config-options-ocp.adoc#adding-an-environment-variable-to-a-deployment_install-central-config-options-ocp[Injecting an environment variable into the Central deployment] + +include::modules/verify-upgrades.adoc[leveloffset=+1] + +include::modules/revoke-the-api-token.adoc[leveloffset=+1] + +include::modules/troubleshooting-cluster-upgrader.adoc[leveloffset=+1] diff --git a/virt/about-virt.adoc b/virt/about-virt.adoc deleted file mode 100644 index 5d3274b7d390..000000000000 --- a/virt/about-virt.adoc +++ /dev/null @@ -1,16 +0,0 @@ -include::modules/virt-document-attributes.adoc[] -[id="about-virt"] -= About {VirtProductName} -:context: about-virt - -toc::[] - -Learn about {VirtProductName}'s capabilities and support scope. - -include::modules/virt-what-you-can-do-with-virt.adoc[leveloffset=+1] - -// This line is attached to the above `virt-what-you-can-do-with-virt` module. -// It is included here in the assembly because of the xref ban. -You can use {VirtProductName} with either the xref:../networking/ovn_kubernetes_network_provider/about-ovn-kubernetes.adoc#about-ovn-kubernetes[OVN-Kubernetes] or the xref:../networking/openshift_sdn/about-openshift-sdn.adoc#about-openshift-sdn[OpenShiftSDN] default Container Network Interface (CNI) network provider. - -include::modules/virt-supported-cluster-version.adoc[leveloffset=+2] diff --git a/virt/install/images b/virt/install/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/virt/install/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/virt/install/installing-virt-cli.adoc b/virt/install/installing-virt-cli.adoc deleted file mode 100644 index da350ba6e854..000000000000 --- a/virt/install/installing-virt-cli.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="installing-virt-cli"] -= Installing {VirtProductName} using the CLI -include::modules/virt-document-attributes.adoc[] -:context: installing-virt-cli - -toc::[] - -Install {VirtProductName} to add virtualization functionality to your {product-title} -cluster. You can subscribe to and deploy the {VirtProductName} Operators by -using the command line to apply manifests to your cluster. - -[NOTE] -==== -To specify the nodes where you want {VirtProductName} to install its components, xref:../../virt/install/virt-specifying-nodes-for-virtualization-components.adoc#virt-specifying-nodes-for-virtualization-components[configure node placement rules]. -==== - -[id="prerequisites_{context}"] -== Prerequisites -* Install {product-title} {product-version} on your cluster. -* Install the OpenShift CLI (`oc`). -* Log in as a user with `cluster-admin` privileges. - -include::modules/virt-subscribing-cli.adoc[leveloffset=+1] - -include::modules/virt-deploying-operator-cli.adoc[leveloffset=+1] - -== Next steps - -You might want to additionally configure the following components: - -* The _KubeMacPool_ component provides a MAC address pool service for virtual machine NICs in designated namespaces. xref:../../virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc#virt-about-kubemacpool_virt-using-mac-address-pool-for-vms[Enable a MAC address pool in a namespace] by applying the KubeMacPool label to that namespace. - -* The xref:../../virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc#virt-about-hostpath-provisioner_virt-configuring-local-storage-for-vms[hostpath provisioner] is a local storage provisioner designed for {VirtProductName}. If you want to configure local storage for virtual machines, you must enable the hostpath provisioner first. - diff --git a/virt/install/installing-virt-web.adoc b/virt/install/installing-virt-web.adoc deleted file mode 100644 index 22140d42a0c5..000000000000 --- a/virt/install/installing-virt-web.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="installing-virt-web"] -= Installing {VirtProductName} using the web console -include::modules/virt-document-attributes.adoc[] -:context: installing-virt-web - -toc::[] - -Install {VirtProductName} to add virtualization functionality to your {product-title} cluster. - -You can use the {product-title} {product-version} -xref:../../web_console/web-console.adoc#web-console-overview_web-console[web console] to subscribe to and deploy the {VirtProductName} Operators. - -include::modules/virt-installing-virt-operator.adoc[leveloffset=+1] - -[id="installing-virt-web-next-steps"] -== Next steps - -You might want to additionally configure the following components: - -* The _KubeMacPool_ component provides a MAC address pool service for virtual machine NICs in designated namespaces. xref:../../virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc#virt-about-kubemacpool_virt-using-mac-address-pool-for-vms[Enable a MAC address pool in a namespace] by applying the KubeMacPool label to that namespace. - -* The xref:../../virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc#virt-about-hostpath-provisioner_virt-configuring-local-storage-for-vms[hostpath provisioner] is a local storage provisioner designed for {VirtProductName}. If you want to configure local storage for virtual machines, you must enable the hostpath provisioner first. diff --git a/virt/install/modules b/virt/install/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/virt/install/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/virt/install/preparing-cluster-for-virt.adoc b/virt/install/preparing-cluster-for-virt.adoc deleted file mode 100644 index dea85a7ac3d6..000000000000 --- a/virt/install/preparing-cluster-for-virt.adoc +++ /dev/null @@ -1,50 +0,0 @@ -[id="preparing-cluster-for-virt"] -= Configuring your cluster for {VirtProductName} -include::modules/virt-document-attributes.adoc[] -:context: preparing-cluster-for-virt - -toc::[] - -Before you install {VirtProductName}, ensure that your {product-title} cluster meets the following requirements: - -* Your cluster must be installed on -xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[bare metal] infrastructure with Red Hat Enterprise Linux CoreOS (RHCOS) workers. You can use any installation method including user-provisioned, installer-provisioned, or assisted installer to deploy your cluster. - -[NOTE] -==== -{VirtProductName} only supports RHCOS worker nodes. RHEL 7 or RHEL 8 nodes are not supported. -==== - -* Additionally, there are two options to maintain high availability (HA) of virtual machines: - -** Use xref:../../installing/installing_bare_metal_ipi/ipi-install-overview.adoc#ipi-install-overview[installer-provisioned infrastructure] and xref:../../machine_management/deploying-machine-health-checks.adoc#machine-health-checks-about_deploying-machine-health-checks[deploy machine health checks]. -+ -[NOTE] -==== -In {VirtProductName} clusters installed using installer-provisioned infrastructure and with MachineHealthCheck properly configured, if a node fails the MachineHealthCheck and becomes unavailable to the cluster, it is recycled. What happens next with VMs that ran on the failed node depends on a series of conditions. See xref:../../virt/virtual_machines/virt-create-vms.adoc#virt-about-runstrategies-vms_virt-create-vms[About RunStrategies for virtual machines] for more detailed information about the potential outcomes and how RunStrategies affect those outcomes. -==== - -** If you are not using installer-provisioned infrastructure, use either a monitoring system or a qualified human to monitor node availability. When a node is lost, shut it down and run `oc adm delete node <lost_node>`. -+ -[NOTE] -==== -Without an external monitoring system or a qualified human monitoring node health, virtual machines lose high availability. -==== - -* You must manage your Compute nodes according to the number and size of the virtual machines that you want to host in the cluster. - -* To deploy {VirtProductName} in a disconnected environment, you must xref:../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[configure Operator Lifecycle Manager on restricted networks]. - -* To use proxy with {VirtProductName}, you must xref:../../operators/admin/olm-configuring-proxy-support.adoc#olm-configuring-proxy-support[configure proxy support in Operator Lifecycle Manager]. - -{VirtProductName} works with {product-title} by default, but the following installation configurations are recommended: - -* Configure xref:../../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[monitoring] in the cluster. - -[NOTE] -==== -To obtain an evaluation version of {product-title}, download a trial -from the {product-title} home page. -==== - -include::modules/virt-cluster-resource-requirements.adoc[leveloffset=+1] diff --git a/virt/install/uninstalling-virt-cli.adoc b/virt/install/uninstalling-virt-cli.adoc deleted file mode 100644 index ed72182ddc00..000000000000 --- a/virt/install/uninstalling-virt-cli.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="uninstalling-virt-cli"] -= Uninstalling {VirtProductName} using the CLI -include::modules/virt-document-attributes.adoc[] -:context: uninstalling-virt-cli - -toc::[] - -You can uninstall {VirtProductName} by using the {product-title} -xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-getting-started[CLI]. - -[id="uninstalling-virt-cli-prereqs"] -== Prerequisites - -* You must have {VirtProductName} {VirtVersion} installed. - -* You must delete all xref:../../virt/virtual_machines/virt-delete-vms.adoc#virt-delete-vm-web_virt-delete-vms[virtual machines], -xref:../../virt/virtual_machines/virt-manage-vmis.adoc#virt-deleting-vmis-cli_virt-manage-vmis[virtual machine instances], -and xref:../../virt/virtual_machines/virtual_disks/virt-deleting-datavolumes.adoc#virt-deleting-dvs_virt-deleting-datavolumes[data volumes]. -+ -[IMPORTANT] -==== -Attempting to uninstall {VirtProductName} without deleting these objects -results in failure. -==== - -include::modules/virt-deleting-virt-cli.adoc[leveloffset=+1] diff --git a/virt/install/uninstalling-virt-web.adoc b/virt/install/uninstalling-virt-web.adoc deleted file mode 100644 index f85b1da18ff6..000000000000 --- a/virt/install/uninstalling-virt-web.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[id="uninstalling-virt-web"] -= Uninstalling {VirtProductName} using the web console -include::modules/virt-document-attributes.adoc[] -:context: uninstalling-virt-web - -toc::[] - -You can uninstall {VirtProductName} by using the {product-title} -xref:../../web_console/web-console.adoc#web-console-overview_web-console[web console]. - -== Prerequisites - -* You must have {VirtProductName} {VirtVersion} installed. -* You must delete all xref:../../virt/virtual_machines/virt-delete-vms.adoc#virt-delete-vm-web_virt-delete-vms[virtual machines], -xref:../../virt/virtual_machines/virt-manage-vmis.adoc#virt-deleting-vmis-cli_virt-manage-vmis[virtual machine instances], -and xref:../../virt/virtual_machines/virtual_disks/virt-deleting-datavolumes.adoc#virt-deleting-dvs_virt-deleting-datavolumes[data volumes]. -+ -[IMPORTANT] -==== -Attempting to uninstall {VirtProductName} without deleting these objects -results in failure. -==== - -include::modules/virt-deleting-deployment-custom-resource.adoc[leveloffset=+1] - -include::modules/virt-deleting-catalog-subscription.adoc[leveloffset=+1] - -[NOTE] -==== -You can now delete the `openshift-cnv` namespace. -==== - -include::modules/deleting-a-namespace-using-the-web-console.adoc[leveloffset=+1] diff --git a/virt/install/virt-installing-virtctl.adoc b/virt/install/virt-installing-virtctl.adoc deleted file mode 100644 index d1837f1a805f..000000000000 --- a/virt/install/virt-installing-virtctl.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="virt-installing-virtctl"] -= Installing the `virtctl` client -include::modules/virt-document-attributes.adoc[] -:context: virt-installing-virtctl - -toc::[] - -The `virtctl` client is a command-line utility for managing {VirtProductName} -resources. It is available for Linux, macOS, and Windows distributions. - -You can install the `virtctl` client from the {VirtProductName} web console or by enabling the {VirtProductName} repository and installing the `kubevirt-virtctl` package. - -include::modules/virt-installing-virtctl-client-web.adoc[leveloffset=+1] - -include::modules/virt-enabling-virt-repos.adoc[leveloffset=+1] - -include::modules/virt-installing-virtctl-client.adoc[leveloffset=+1] - -[id="virt-installing-virtctl-addtl-resources"] -== Additional resources -xref:../../virt/virt-using-the-cli-tools.adoc#virt-using-the-cli-tools[Using the CLI tools] for {VirtProductName}. diff --git a/virt/install/virt-specifying-nodes-for-virtualization-components.adoc b/virt/install/virt-specifying-nodes-for-virtualization-components.adoc deleted file mode 100644 index 29d64f99f385..000000000000 --- a/virt/install/virt-specifying-nodes-for-virtualization-components.adoc +++ /dev/null @@ -1,57 +0,0 @@ -[id="virt-specifying-nodes-for-virtualization-components"] -= Specifying nodes for {VirtProductName} components -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-specifying-nodes-for-virtualization-components - -toc::[] - -Specify the nodes where you want to deploy {VirtProductName} Operators, workloads, and controllers by configuring node placement rules. - -[NOTE] -==== -You can configure node placement for some components after installing {VirtProductName}, but there must not be virtual machines present if you want to configure node placement for workloads. -==== - -include::modules/virt-about-node-placement-virtualization-components.adoc[leveloffset=+1] - -[id="additional-resources_{context}"] -=== Additional resources - -[id="node-placement-resources_{context}"] -==== Node placement rules -* xref:../../nodes/scheduling/nodes-scheduler-node-selectors.html#nodes-scheduler-node-selectors[Placing pods on specific nodes using node selectors] -* xref:../../nodes/scheduling/nodes-scheduler-node-affinity.adoc#nodes-scheduler-node-affinity[Controlling pod placement on nodes using node affinity rules] -* xref:../../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations[Controlling pod placement using node taints] - -[id="installation-resources_{context}"] -==== Installing {VirtProductName} -* xref:../../virt/install/installing-virt-cli.adoc#installing-virt-cli[Installing {VirtProductName} using the CLI] -* xref:../../virt/install/installing-virt-web.adoc#installing-virt-web[Installing {VirtProductName} using the web console] - -[id="hostpath-provisioner-resources_{context}"] -==== Configuring the hostpath provisioner -* xref:../../virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc#virt-configuring-local-storage-for-vms[Configuring local storage for virtual machines] - -[id="example-manifests_{context}"] -== Example manifests - -The following example YAML files use `nodePlacement`, `affinity`, and `tolerations` objects to customize node placement for {VirtProductName} components. - -[id="olm-subscription-examples_{context}"] -=== Operator Lifecycle Manager Subscription object - -include::modules/virt-example-node-placement-node-selector-olm-subscription.adoc[leveloffset=+3] -include::modules/virt-example-node-placement-tolerations-olm-subscription.adoc[leveloffset=+3] - -[id="hyperconverged-cluster-cr-examples_{context}"] -=== HyperConverged object - -include::modules/virt-example-node-placement-node-selector-hyperconverged-cr.adoc[leveloffset=+3] -include::modules/virt-example-node-placement-affinity-hyperconverged-cr.adoc[leveloffset=+3] -include::modules/virt-example-node-placement-tolerations-hyperconverged-cr.adoc[leveloffset=+3] - -[id="hpp-object-examples_{context}"] -=== HostPathProvisioner object - -include::modules/virt-example-node-placement-node-selector-hpp.adoc[leveloffset=+3] diff --git a/virt/live_migration/images b/virt/live_migration/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/virt/live_migration/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/virt/live_migration/modules b/virt/live_migration/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/virt/live_migration/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/virt/live_migration/virt-cancel-vmi-migration.adoc b/virt/live_migration/virt-cancel-vmi-migration.adoc deleted file mode 100644 index 47ee5916729e..000000000000 --- a/virt/live_migration/virt-cancel-vmi-migration.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="virt-cancel-vmi-migration"] -= Cancelling the live migration of a virtual machine instance -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-cancel-vmi-migration - -toc::[] - -Cancel the live migration so that the virtual machine instance remains -on the original node. - -You can cancel a live migration from either the web console or the CLI. - -include::modules/virt-cancelling-vm-migration-web.adoc[leveloffset=+1] -include::modules/virt-cancelling-vm-migration-cli.adoc[leveloffset=+1] - diff --git a/virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc b/virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc deleted file mode 100644 index a88aabfd81bf..000000000000 --- a/virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="virt-configuring-vmi-eviction-strategy"] -= Configuring virtual machine eviction strategy -include::modules/virt-document-attributes.adoc[] -:context: virt-configuring-vmi-eviction-strategy - -toc::[] - -The `LiveMigrate` eviction strategy ensures that a virtual machine instance is -not interrupted if the node is placed into maintenance or drained. -Virtual machines instances with this eviction strategy will be live migrated to -another node. - -include::modules/virt-configuring-vm-live-migration-cli.adoc[leveloffset=+1] diff --git a/virt/live_migration/virt-live-migration-limits.adoc b/virt/live_migration/virt-live-migration-limits.adoc deleted file mode 100644 index 027dc7a4936c..000000000000 --- a/virt/live_migration/virt-live-migration-limits.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="virt-live-migration-limits"] -= Live migration limits and timeouts -include::modules/virt-document-attributes.adoc[] -:context: virt-live-migration-limits - -toc::[] - -Live migration limits and timeouts are applied so that migration processes do -not overwhelm the cluster. Configure these settings by editing the -`kubevirt-config` configuration file. - -include::modules/virt-configuring-live-migration-limits.adoc[leveloffset=+1] -include::modules/virt-live-migration-limits-reftable.adoc[leveloffset=+1] - - diff --git a/virt/live_migration/virt-live-migration.adoc b/virt/live_migration/virt-live-migration.adoc deleted file mode 100644 index 969ac7df4237..000000000000 --- a/virt/live_migration/virt-live-migration.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="virt-live-migration"] -= Virtual machine live migration -include::modules/virt-document-attributes.adoc[] -:context: virt-live-migration - -toc::[] - -include::modules/virt-understanding-live-migration.adoc[leveloffset=+1] -include::modules/virt-updating-access-mode-for-live-migration.adoc[leveloffset=+1] - -.Additional resources: - -* xref:../../virt/live_migration/virt-migrate-vmi.adoc#virt-migrate-vmi[Migrating a virtual machine instance to another node] -* xref:../../virt/node_maintenance/virt-node-maintenance.adoc#virt-node-maintenance[Node maintenance mode] -* xref:../../virt/live_migration/virt-live-migration-limits.adoc#virt-live-migration-limits[Live migration limiting] -* xref:../../virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc#virt-storage-defaults-for-datavolumes[Storage defaults for data volumes] diff --git a/virt/live_migration/virt-migrate-vmi.adoc b/virt/live_migration/virt-migrate-vmi.adoc deleted file mode 100644 index fa262ab83feb..000000000000 --- a/virt/live_migration/virt-migrate-vmi.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="virt-migrate-vmi"] -= Migrating a virtual machine instance to another node -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-migrate-vmi - -toc::[] - -Manually initiate a live migration of a virtual machine instance to another node using either the web console or the CLI. - -include::modules/virt-initiating-vm-migration-web.adoc[leveloffset=+1] -include::modules/virt-initiating-vm-migration-cli.adoc[leveloffset=+1] - -.Additional resources: - -* xref:../../virt/live_migration/virt-monitor-vmi-migration.adoc#virt-monitor-vmi-migration[Monitoring live migration of a virtual machine instance] -* xref:../../virt/live_migration/virt-cancel-vmi-migration.adoc#virt-cancel-vmi-migration[Cancelling the live migration of a virtual machine instance] - diff --git a/virt/live_migration/virt-monitor-vmi-migration.adoc b/virt/live_migration/virt-monitor-vmi-migration.adoc deleted file mode 100644 index 6aafec079235..000000000000 --- a/virt/live_migration/virt-monitor-vmi-migration.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="virt-monitor-vmi-migration"] -= Monitoring live migration of a virtual machine instance -include::modules/virt-document-attributes.adoc[] -:context: virt-monitor-vmi-migration - -toc::[] - -You can monitor the progress of a live migration of a virtual machine instance from either the web console or the CLI. - -include::modules/virt-monitoring-vm-migration-web.adoc[leveloffset=+1] -include::modules/virt-monitoring-vm-migration-cli.adoc[leveloffset=+1] - diff --git a/virt/logging_events_monitoring/images b/virt/logging_events_monitoring/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/virt/logging_events_monitoring/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/virt/logging_events_monitoring/modules b/virt/logging_events_monitoring/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/virt/logging_events_monitoring/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/virt/logging_events_monitoring/virt-collecting-virt-data.adoc b/virt/logging_events_monitoring/virt-collecting-virt-data.adoc deleted file mode 100644 index 8a923be29006..000000000000 --- a/virt/logging_events_monitoring/virt-collecting-virt-data.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="virt-collecting-virt-data"] -= Collecting {VirtProductName} data for Red Hat Support -include::modules/virt-document-attributes.adoc[] -:context: virt-collecting-virt-data - -toc::[] - -When opening a support case, it is helpful to provide debugging -information about your cluster to Red Hat Support. - -The `must-gather` tool enables you to collect diagnostic information about your -{product-title} cluster, including virtual machines and other data related to -{VirtProductName}. - -For prompt support, supply diagnostic information for both {product-title} -and {VirtProductName}. - -include::modules/about-must-gather.adoc[leveloffset=+1] - -include::modules/virt-about-collecting-virt-data.adoc[leveloffset=+1] - -include::modules/gathering-data-specific-features.adoc[leveloffset=+1] diff --git a/virt/logging_events_monitoring/virt-diagnosing-datavolumes-using-events-and-conditions.adoc b/virt/logging_events_monitoring/virt-diagnosing-datavolumes-using-events-and-conditions.adoc deleted file mode 100644 index 6ac1d8c89562..000000000000 --- a/virt/logging_events_monitoring/virt-diagnosing-datavolumes-using-events-and-conditions.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="virt-diagnosing-datavolumes-using-events-and-conditions"] -= Diagnosing data volumes using events and conditions -include::modules/virt-document-attributes.adoc[] -:context: virt-diagnosing-datavolumes-using-events-and-conditions - -toc::[] - -Use the `oc describe` command to analyze and help resolve issues with data volumes. - -include::modules/virt-about-conditions-and-events.adoc[leveloffset=+1] -include::modules/virt-analyzing-datavolume-conditions-and-events.adoc[leveloffset=+1] diff --git a/virt/logging_events_monitoring/virt-events.adoc b/virt/logging_events_monitoring/virt-events.adoc deleted file mode 100644 index 1ab543f9df8f..000000000000 --- a/virt/logging_events_monitoring/virt-events.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="virt-events"] -= Viewing events -include::modules/virt-document-attributes.adoc[] -:context: virt-events - -toc::[] - -include::modules/virt-understanding-events.adoc[leveloffset=+1] - -See also: -xref:../../nodes/clusters/nodes-containers-events.adoc#nodes-containers-events[Viewing system event information in an {product-title} cluster]. - -include::modules/virt-viewing-vm-events-web.adoc[leveloffset=+1] - -include::modules/virt-viewing-namespace-events-cli.adoc[leveloffset=+1] - -include::modules/virt-viewing-resource-events-cli.adoc[leveloffset=+1] - diff --git a/virt/logging_events_monitoring/virt-logs.adoc b/virt/logging_events_monitoring/virt-logs.adoc deleted file mode 100644 index 8500b09910d9..000000000000 --- a/virt/logging_events_monitoring/virt-logs.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="virt-logs"] -= Viewing virtual machine logs -include::modules/virt-document-attributes.adoc[] -:context: virt-logs - -toc::[] - -include::modules/virt-understanding-logs.adoc[leveloffset=+1] - -include::modules/virt-viewing-virtual-machine-logs-cli.adoc[leveloffset=+1] - -include::modules/virt-viewing-virtual-machine-logs-web.adoc[leveloffset=+1] diff --git a/virt/logging_events_monitoring/virt-monitoring-vm-health.adoc b/virt/logging_events_monitoring/virt-monitoring-vm-health.adoc deleted file mode 100644 index 272f2e15a876..000000000000 --- a/virt/logging_events_monitoring/virt-monitoring-vm-health.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="virt-monitoring-vm-health"] -= Monitoring virtual machine health -include::modules/virt-document-attributes.adoc[] -:context: virt-monitoring-vm-health - -toc::[] - -Use this procedure to create liveness and readiness probes -to monitor virtual machine health. - -include::modules/virt-about-liveness-readiness-probes.adoc[leveloffset=+1] -include::modules/virt-define-http-liveness-probe.adoc[leveloffset=+1] -include::modules/virt-define-tcp-liveness-probe.adoc[leveloffset=+1] -include::modules/virt-define-readiness-probe.adoc[leveloffset=+1] diff --git a/virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc b/virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc deleted file mode 100644 index dfba6d619d6b..000000000000 --- a/virt/logging_events_monitoring/virt-openshift-cluster-monitoring.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="virt-openshift-cluster-monitoring"] -= {product-title} cluster monitoring, logging, and Telemetry -include::modules/virt-document-attributes.adoc[] -:context: virt-openshift-cluster-monitoring - -toc::[] - -{product-title} provides various resources for monitoring at the cluster level. - -// Cluster monitoring -include::modules/monitoring-about-cluster-monitoring.adoc[leveloffset=+1] - -// OpenShift Logging -include::modules/cluster-logging-about-components.adoc[leveloffset=+1] - -For more information on OpenShift Logging, see the xref:../../logging/cluster-logging.adoc#cluster-logging[OpenShift Logging] documentation. - -// Telemetry -include::modules/telemetry-about-telemetry.adoc[leveloffset=+1] -include::modules/telemetry-what-information-is-collected.adoc[leveloffset=+2] - -== CLI troubleshooting and debugging commands - -For a list of the `oc` client troubleshooting and debugging commands, see the xref:../../cli_reference/openshift_cli/developer-cli-commands.adoc#cli-troubleshooting-commands_cli-developer-commands[{product-title} CLI tools] documentation. diff --git a/virt/logging_events_monitoring/virt-using-dashboard-to-get-cluster-info.adoc b/virt/logging_events_monitoring/virt-using-dashboard-to-get-cluster-info.adoc deleted file mode 100644 index bec35be12482..000000000000 --- a/virt/logging_events_monitoring/virt-using-dashboard-to-get-cluster-info.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="virt-using-dashboard-to-get-cluster-info"] -= Using the {product-title} dashboard to get cluster information -include::modules/virt-document-attributes.adoc[] -:context: virt-using-dashboard-to-get-cluster-info - -toc::[] - -Access the {product-title} dashboard, which captures high-level information about the cluster, by clicking *Home > Dashboards > Overview* from the {product-title} web console. - -The {product-title} dashboard provides various cluster information, captured in individual dashboard _cards_. - -include::modules/virt-about-the-overview-dashboard.adoc[leveloffset=+1] diff --git a/virt/logging_events_monitoring/virt-viewing-information-about-vm-workloads.adoc b/virt/logging_events_monitoring/virt-viewing-information-about-vm-workloads.adoc deleted file mode 100644 index 545d1074bc9f..000000000000 --- a/virt/logging_events_monitoring/virt-viewing-information-about-vm-workloads.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="virt-viewing-information-about-vm-workloads"] -= Viewing information about virtual machine workloads -include::modules/virt-document-attributes.adoc[] -:context: virt-viewing-information-about-vm-workloads - -toc::[] - -You can view high-level information about your virtual machines by using the *Virtual Machines* dashboard in the {product-title} web console. - -include::modules/virt-about-the-vm-dashboard.adoc[leveloffset=+1] diff --git a/virt/modules b/virt/modules deleted file mode 120000 index 43aab75b53c9..000000000000 --- a/virt/modules +++ /dev/null @@ -1 +0,0 @@ -../modules/ \ No newline at end of file diff --git a/virt/node_maintenance/images b/virt/node_maintenance/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/virt/node_maintenance/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/virt/node_maintenance/modules b/virt/node_maintenance/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/virt/node_maintenance/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/virt/node_maintenance/virt-automatic-certificates.adoc b/virt/node_maintenance/virt-automatic-certificates.adoc deleted file mode 100644 index aba16296eaf4..000000000000 --- a/virt/node_maintenance/virt-automatic-certificates.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="virt-automatic-certificates"] -= Automatic renewal of TLS certificates -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-automatic-certificates - -toc::[] - -All TLS certificates for {VirtProductName} components are renewed and rotated automatically. You are not required to refresh them manually. - -include::modules/virt-automatic-certificates-renewal.adoc[leveloffset=+1] diff --git a/virt/node_maintenance/virt-managing-node-labeling-obsolete-cpu-models.adoc b/virt/node_maintenance/virt-managing-node-labeling-obsolete-cpu-models.adoc deleted file mode 100644 index fdc3b03b1f94..000000000000 --- a/virt/node_maintenance/virt-managing-node-labeling-obsolete-cpu-models.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="virt-managing-node-labeling-obsolete-cpu-models"] -= Managing node labeling for obsolete CPU models -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-managing-node-labeling-obsolete-cpu-models - -toc::[] - -You can schedule a virtual machine (VM) on a node where the CPU model and policy attribute of the VM are compatible with the CPU models and policy attributes that the node supports. By specifying a list of obsolete CPU models in a xref:../../authentication/configmaps.adoc#authentication-configmap-overview_builds-configmaps[config map], you can exclude them from the list of labels created for CPU models. - -include::modules/virt-understanding-node-labeling-obsolete-cpu-models.adoc[leveloffset=+1] -include::modules/virt-configuring-configmap-for-obsolete-cpu-models.adoc[leveloffset=+1] diff --git a/virt/node_maintenance/virt-node-maintenance.adoc b/virt/node_maintenance/virt-node-maintenance.adoc deleted file mode 100644 index 23901001eb07..000000000000 --- a/virt/node_maintenance/virt-node-maintenance.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="virt-node-maintenance"] -= Node maintenance mode -include::modules/virt-document-attributes.adoc[] -:context: virt-node-maintenance - -toc::[] - -include::modules/virt-understanding-node-maintenance.adoc[leveloffset=+1] - -.Additional resources: - -* xref:../../virt/live_migration/virt-live-migration.adoc#virt-live-migration[Virtual machine live migration] -* xref:../../virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc#virt-configuring-vmi-eviction-strategy[Configuring virtual machine eviction strategy] diff --git a/virt/node_maintenance/virt-refresh-certificates.adoc b/virt/node_maintenance/virt-refresh-certificates.adoc deleted file mode 100644 index 4b79a95beea3..000000000000 --- a/virt/node_maintenance/virt-refresh-certificates.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="virt-refresh-certificates"] -= Manually refreshing TLS certificates -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-refresh-certificates - -toc::[] - -The TLS certificates for {VirtProductName} components are created at the time -of installation and are valid for one year. You must manually refresh -these certificates before they expire. - -include::modules/virt-refreshing-certificates.adoc[leveloffset=+1] diff --git a/virt/node_maintenance/virt-resuming-node.adoc b/virt/node_maintenance/virt-resuming-node.adoc deleted file mode 100644 index 0876fd1088f8..000000000000 --- a/virt/node_maintenance/virt-resuming-node.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="virt-resuming-node"] -= Resuming a node from maintenance mode -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-resuming-node - -toc::[] - -Resuming a node brings it out of maintenance mode and schedulable again. - -Resume a node from maintenance from either the web console or the CLI. - -include::modules/virt-resuming-node-maintenance-web.adoc[leveloffset=+1] -include::modules/virt-resuming-node-maintenance-cli.adoc[leveloffset=+1] - diff --git a/virt/node_maintenance/virt-setting-node-maintenance.adoc b/virt/node_maintenance/virt-setting-node-maintenance.adoc deleted file mode 100644 index db47b32372b9..000000000000 --- a/virt/node_maintenance/virt-setting-node-maintenance.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="virt-setting-node-maintenance"] -= Setting a node to maintenance mode -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-setting-node-maintenance - -toc::[] - -include::modules/virt-understanding-node-maintenance.adoc[leveloffset=+1] - -Place a node into maintenance from either the web console or the CLI. - -include::modules/virt-setting-node-maintenance-web.adoc[leveloffset=+1] -include::modules/virt-setting-node-maintenance-cli.adoc[leveloffset=+1] - -.Additional resources: - -* xref:../../virt/node_maintenance/virt-resuming-node.adoc#virt-resuming-node[Resuming a node from maintenance mode] - diff --git a/virt/node_network/images b/virt/node_network/images deleted file mode 120000 index 847b03ed0541..000000000000 --- a/virt/node_network/images +++ /dev/null @@ -1 +0,0 @@ -../../images/ \ No newline at end of file diff --git a/virt/node_network/modules b/virt/node_network/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/virt/node_network/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/virt/node_network/virt-observing-node-network-state.adoc b/virt/node_network/virt-observing-node-network-state.adoc deleted file mode 100644 index 842000e5d001..000000000000 --- a/virt/node_network/virt-observing-node-network-state.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="virt-observing-node-network-state"] -= Observing node network state -include::modules/virt-document-attributes.adoc[] -:context: virt-observing-node-network-state - -toc::[] - -Node network state is the network configuration for all nodes in the cluster. - -include::modules/virt-about-nmstate.adoc[leveloffset=+1] - -include::modules/virt-viewing-network-state-of-node.adoc[leveloffset=+1] - - - diff --git a/virt/node_network/virt-troubleshooting-node-network.adoc b/virt/node_network/virt-troubleshooting-node-network.adoc deleted file mode 100644 index b66b81930b52..000000000000 --- a/virt/node_network/virt-troubleshooting-node-network.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="virt-troubleshooting-node-network"] -= Troubleshooting node network configuration -include::modules/virt-document-attributes.adoc[] -:context: virt-troubleshooting-node-network - -toc::[] - -If the node network configuration encounters an issue, the policy is automatically rolled back and the enactments report failure. -This includes issues such as: - -* The configuration fails to be applied on the host. -* The host loses connection to the default gateway. -* The host loses connection to the API server. - -include::modules/virt-troubleshooting-incorrect-policy-config.adoc[leveloffset=+1] - diff --git a/virt/node_network/virt-updating-node-network-config.adoc b/virt/node_network/virt-updating-node-network-config.adoc deleted file mode 100644 index be064f7bc143..000000000000 --- a/virt/node_network/virt-updating-node-network-config.adoc +++ /dev/null @@ -1,40 +0,0 @@ -[id="virt-updating-node-network-config"] -= Updating node network configuration -include::modules/virt-document-attributes.adoc[] -:context: virt-updating-node-network-config - -toc::[] - -You can update the node network configuration, such as adding or removing interfaces -from nodes, by applying `NodeNetworkConfigurationPolicy` manifests to the cluster. - -include::modules/virt-about-nmstate.adoc[leveloffset=+1] - -include::modules/virt-creating-interface-on-nodes.adoc[leveloffset=+1] - -[discrete] -== Additional resources -* xref:virt-nmstate-example-policy-configurations[Example policy configurations for different interfaces] -* xref:virt-example-nmstate-multiple-interfaces_virt-updating-node-network-config[Example for creating multiple interfaces in the same policy] -* xref:virt-example-nmstate-IP-management_virt-updating-node-network-config[Examples of different IP management methods in policies] - -include::modules/virt-confirming-policy-updates-on-nodes.adoc[leveloffset=+1] - -include::modules/virt-removing-interface-from-nodes.adoc[leveloffset=+1] - -[id="virt-nmstate-example-policy-configurations"] -== Example policy configurations for different interfaces - -include::modules/virt-example-bridge-nncp.adoc[leveloffset=+2] - -include::modules/virt-example-vlan-nncp.adoc[leveloffset=+2] - -include::modules/virt-example-bond-nncp.adoc[leveloffset=+2] - -include::modules/virt-example-ethernet-nncp.adoc[leveloffset=+2] - -include::modules/virt-example-nmstate-multiple-interfaces.adoc[leveloffset=+2] - -// Dropping offset by one again -include::modules/virt-example-nmstate-IP-management.adoc[leveloffset=+1] - diff --git a/virt/upgrading-virt.adoc b/virt/upgrading-virt.adoc deleted file mode 100644 index 9252f4331cec..000000000000 --- a/virt/upgrading-virt.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="upgrading-virt"] -= Upgrading {VirtProductName} -include::modules/virt-document-attributes.adoc[] -:context: upgrading-virt - -toc::[] - -You can manually upgrade to the next minor version of {VirtProductName} and -monitor the status of an update by using the web console. - -include::modules/virt-about-upgrading-virt.adoc[leveloffset=+1] - -//include::modules/virt-upgrade-pathways.adoc[leveloffset=+1] - -include::modules/virt-upgrading-virt.adoc[leveloffset=+1] - -include::modules/virt-monitoring-upgrade-status.adoc[leveloffset=+1] - -== Additional resources - -* xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-csv_olm-understanding-olm[Cluster service versions (CSVs)] - -* xref:../virt/live_migration/virt-configuring-vmi-eviction-strategy.adoc#virt-configuring-vmi-eviction-strategy[Configuring virtual machine eviction strategy] diff --git a/virt/virt-2-3-release-notes.adoc b/virt/virt-2-3-release-notes.adoc deleted file mode 100644 index a1e0ab0b7931..000000000000 --- a/virt/virt-2-3-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="virt-2-3-release-notes"] -= {RN_BookName} -include::modules/virt-document-attributes.adoc[] -:context: virt-release-notes - -toc::[] - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -This file is here to allow builds to work. diff --git a/virt/virt-2-4-release-notes.adoc b/virt/virt-2-4-release-notes.adoc deleted file mode 100644 index 2a1b23ba6408..000000000000 --- a/virt/virt-2-4-release-notes.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="virt-2-4-release-notes"] -= {RN_BookName} -include::modules/virt-document-attributes.adoc[] -:context: virt-2-4-release-notes - -toc::[] - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -This file is here to allow builds to work. - diff --git a/virt/virt-2-5-release-notes.adoc b/virt/virt-2-5-release-notes.adoc deleted file mode 100644 index 423f55377071..000000000000 --- a/virt/virt-2-5-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="virt-2-5-release-notes"] -= {RN_BookName} -include::modules/virt-document-attributes.adoc[] -:context: virt-2-5-release-notes - -toc::[] - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -This file is here to allow builds to work. diff --git a/virt/virt-2-6-release-notes.adoc b/virt/virt-2-6-release-notes.adoc deleted file mode 100644 index 7d2e99ddd3ae..000000000000 --- a/virt/virt-2-6-release-notes.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="virt-2-6-release-notes"] -= {RN_BookName} -include::modules/virt-document-attributes.adoc[] -:context: virt-2-6-release-notes - -toc::[] - -Do not add or edit release notes here. Edit release notes directly in the branch -that they are relevant for. - -This file is here to allow builds to work. diff --git a/virt/virt-additional-security-privileges-controller-and-launcher.adoc b/virt/virt-additional-security-privileges-controller-and-launcher.adoc deleted file mode 100644 index 73f2e444b1f0..000000000000 --- a/virt/virt-additional-security-privileges-controller-and-launcher.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="virt-additional-security-privileges-controller-and-launcher"] -= Additional security privileges granted for kubevirt-controller and virt-launcher -include::modules/virt-document-attributes.adoc[] -:context: virt-additional-security-privileges-controller-and-launcher - -toc::[] - -The `kubevirt-controller` and virt-launcher pods are granted some SELinux policies and Security Context Constraints privileges that are in addition to typical pod owners. These privileges enable virtual machines to use {VirtProductName} features. - -include::modules/virt-extended-selinux-policies-for-virt-launcher.adoc[leveloffset=+1] - -include::modules/virt-additional-scc-for-kubevirt-controller.adoc[leveloffset=+1] - -== Additional resources - -* The Red Hat Enterprise Linux Virtualization Tuning and Optimization Guide has more information on link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/virtualization_tuning_and_optimization_guide/sect-virtualization_tuning_optimization_guide-networking-techniques#mult[network multi-queue] -and -link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/virtualization_tuning_and_optimization_guide/sect-virtualization_tuning_optimization_guide-memory-tuning#sect-Virtualization_Tuning_Optimization_Guide-Memory-Huge_Pages[huge pages]. - -* The `capabilities` man page has more information on the Linux capabilities. - -* The `sysfs(5)` man page has more information on sysfs. - -* The {product-title} Authentication guide has more information on -xref:../authentication/managing-security-context-constraints.adoc#security-context-constraints-about_configuring-internal-oauth[Security Context Constraints]. diff --git a/virt/virt-using-the-cli-tools.adoc b/virt/virt-using-the-cli-tools.adoc deleted file mode 100644 index 757f9bdf4643..000000000000 --- a/virt/virt-using-the-cli-tools.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="virt-using-the-cli-tools"] -= Using the CLI tools -include::modules/virt-document-attributes.adoc[] -:context: virt-using-the-cli-tools - -toc::[] - -The two primary CLI tools used for managing resources in the cluster are: - -* The {VirtProductName} `virtctl` client -* The {product-title} `oc` client - -== Prerequisites - -* You must xref:../virt/install/virt-installing-virtctl.adoc#virt-installing-virtctl[install the `virtctl` client]. - -include::modules/virt-virtctl-commands.adoc[leveloffset=+1] -include::modules/virt-openshift-client-commands.adoc[leveloffset=+1] - -For more comprehensive information on `oc` client commands, see the -xref:../cli_reference/openshift_cli/developer-cli-commands.adoc#cli_reference[{product-title} CLI tools] documentation. diff --git a/virt/virtual_machines/advanced_vm_management/images b/virt/virtual_machines/advanced_vm_management/images deleted file mode 120000 index 4dd3347de19a..000000000000 --- a/virt/virtual_machines/advanced_vm_management/images +++ /dev/null @@ -1 +0,0 @@ -../../../images \ No newline at end of file diff --git a/virt/virtual_machines/advanced_vm_management/modules b/virt/virtual_machines/advanced_vm_management/modules deleted file mode 120000 index 5be29a99c161..000000000000 --- a/virt/virtual_machines/advanced_vm_management/modules +++ /dev/null @@ -1 +0,0 @@ -../../../modules \ No newline at end of file diff --git a/virt/virtual_machines/advanced_vm_management/virt-automating-management-tasks.adoc b/virt/virtual_machines/advanced_vm_management/virt-automating-management-tasks.adoc deleted file mode 100644 index ff3be44b2e6f..000000000000 --- a/virt/virtual_machines/advanced_vm_management/virt-automating-management-tasks.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="virt-automating-management-tasks"] -= Automating management tasks -include::modules/virt-document-attributes.adoc[] -:context: virt-automating-management-tasks - -toc::[] - -You can automate {VirtProductName} management tasks by using Red Hat Ansible -Automation Platform. Learn the basics by using an Ansible Playbook to create a new -virtual machine. - -include::modules/virt-about-red-hat-ansible-automation.adoc[leveloffset=+1] - -include::modules/virt-automating-virtual-machine-creation-with-ansible.adoc[leveloffset=+1] - -To verify that the virtual machine was created, try to -xref:../../../virt/virtual_machines/virt-accessing-vm-consoles.adoc#virt-accessing-vm-consoles[access the VM console]. - -include::modules/virt-example-ansible-playbook-creating-vms.adoc[leveloffset=+1] - diff --git a/virt/virtual_machines/advanced_vm_management/virt-configuring-pxe-booting.adoc b/virt/virtual_machines/advanced_vm_management/virt-configuring-pxe-booting.adoc deleted file mode 100644 index 9432b6639435..000000000000 --- a/virt/virtual_machines/advanced_vm_management/virt-configuring-pxe-booting.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="configuring-pxe-booting"] -= Configuring PXE booting for virtual machines -include::modules/virt-document-attributes.adoc[] -:context: pxe-booting - -toc::[] - -PXE booting, or network booting, is available in {VirtProductName}. -Network booting allows a computer to boot and load an -operating system or other program without requiring a locally attached -storage device. For example, you can use it to choose your desired OS -image from a PXE server when deploying a new host. - -== Prerequisites - -* A Linux bridge must be xref:../../../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#attaching-to-multiple-networks[connected]. - -* The PXE server must be connected to the same VLAN as the bridge. - -include::modules/virt-networking-glossary.adoc[leveloffset=+1] - -include::modules/virt-pxe-booting-with-mac-address.adoc[leveloffset=+1] - -include::modules/virt-template-vmi-pxe-config.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/advanced_vm_management/virt-dedicated-resources-vm.adoc b/virt/virtual_machines/advanced_vm_management/virt-dedicated-resources-vm.adoc deleted file mode 100644 index 57a87e84ec0c..000000000000 --- a/virt/virtual_machines/advanced_vm_management/virt-dedicated-resources-vm.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="virt-dedicated-resources-vm"] -= Enabling dedicated resources for virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-dedicated-resources-vm - -toc::[] - -To improve performance, you can dedicate node resources, such as CPU, to a virtual machine. - -include::modules/virt-about-dedicated-resources.adoc[leveloffset=+1] - -== Prerequisites - -* The xref:../../../scalability_and_performance/using-cpu-manager.adoc[CPU Manager] must be configured on the node. Verify that the node has the `cpumanager = true` label before scheduling virtual machine workloads. - -* The virtual machine must be powered off. - -include::modules/virt-enabling-dedicated-resources.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/advanced_vm_management/virt-efi-mode-for-vms.adoc b/virt/virtual_machines/advanced_vm_management/virt-efi-mode-for-vms.adoc deleted file mode 100644 index d51825bf51b7..000000000000 --- a/virt/virtual_machines/advanced_vm_management/virt-efi-mode-for-vms.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="virt-efi-mode-for-vms"] -= Using EFI mode for virtual machines -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-efi-mode-for-vms - -toc::[] - -You can boot a virtual machine (VM) in Extensible Firmware Interface (EFI) mode. - -include::modules/virt-about-efi-mode-for-vms.adoc[leveloffset=+1] -include::modules/virt-booting-efi-mode.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/advanced_vm_management/virt-managing-guest-memory.adoc b/virt/virtual_machines/advanced_vm_management/virt-managing-guest-memory.adoc deleted file mode 100644 index 9160a4ef3e09..000000000000 --- a/virt/virtual_machines/advanced_vm_management/virt-managing-guest-memory.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="virt-managing-guest-memory"] -= Managing guest memory -include::modules/virt-document-attributes.adoc[] -:context: virt-managing-guest-memory - -toc::[] - -If you want to adjust guest memory settings to suit a specific use case, you can do so by editing the guest's YAML configuration file. {VirtProductName} allows you to configure guest memory overcommitment and disable guest memory overhead accounting. - -[WARNING] -==== -The following procedures increase the chance that virtual machine processes will be killed due to memory pressure. Proceed only if you understand the risks. -==== - -include::modules/virt-configuring-guest-memory-overcommitment.adoc[leveloffset=+1] - -include::modules/virt-disabling-guest-memory-overhead-accounting.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/advanced_vm_management/virt-schedule-vms.adoc b/virt/virtual_machines/advanced_vm_management/virt-schedule-vms.adoc deleted file mode 100644 index c767dbe921ff..000000000000 --- a/virt/virtual_machines/advanced_vm_management/virt-schedule-vms.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="virt-schedule-vms"] -= Scheduling virtual machines -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-schedule-vms - -toc::[] - -You can schedule a virtual machine (VM) on a node by ensuring that the VM's CPU model and policy attribute are matched for compatibility with the CPU models and policy attributes supported by the node. - -include::modules/virt-understanding-policy-attributes.adoc[leveloffset=+1] -include::modules/virt-setting-policy-attributes.adoc[leveloffset=+1] -include::modules/virt-schedule-supported-cpu-model-vms.adoc[leveloffset=+1] -include::modules/virt-schedule-cpu-host-model-vms.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/advanced_vm_management/virt-using-huge-pages-with-vms.adoc b/virt/virtual_machines/advanced_vm_management/virt-using-huge-pages-with-vms.adoc deleted file mode 100644 index dbddb1452f14..000000000000 --- a/virt/virtual_machines/advanced_vm_management/virt-using-huge-pages-with-vms.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="virt-using-huge-pages-with-vms"] -= Using huge pages with virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-using-huge-pages-with-vms - -toc::[] - -You can use huge pages as backing memory for virtual machines in your cluster. - -== Prerequisites - -* Nodes must have xref:../../../scalability_and_performance/what-huge-pages-do-and-how-they-are-consumed-by-apps.adoc#configuring-huge-pages_huge-pages[pre-allocated huge pages configured]. - - -include::modules/what-huge-pages-do.adoc[leveloffset=+1] - -include::modules/virt-configuring-huge-pages-for-vms.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/cloning_vms/images b/virt/virtual_machines/cloning_vms/images deleted file mode 120000 index 4dd3347de19a..000000000000 --- a/virt/virtual_machines/cloning_vms/images +++ /dev/null @@ -1 +0,0 @@ -../../../images \ No newline at end of file diff --git a/virt/virtual_machines/cloning_vms/modules b/virt/virtual_machines/cloning_vms/modules deleted file mode 120000 index 5be29a99c161..000000000000 --- a/virt/virtual_machines/cloning_vms/modules +++ /dev/null @@ -1 +0,0 @@ -../../../modules \ No newline at end of file diff --git a/virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc b/virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc deleted file mode 100644 index a08ae0987889..000000000000 --- a/virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume-block.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="virt-cloning-vm-disk-into-new-datavolume-block"] -= Cloning a virtual machine disk into a new block storage data volume -include::modules/virt-document-attributes.adoc[] -:context: virt-cloning-vm-disk-into-new-datavolume-block - -toc::[] - -You can clone the persistent volume claim (PVC) of a virtual machine disk into -a new block data volume by referencing the source PVC in your data volume configuration -file. - -[WARNING] -==== -Cloning operations between different volume modes are not supported. The `volumeMode` values must match in both the source and target specifications. - -For example, if you attempt to clone from a persistent volume (PV) with `volumeMode: Block` to a PV with `volumeMode: Filesystem`, the operation fails with an error message. -==== - -== Prerequisites - -* Users need xref:../../../virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc#virt-enabling-user-permissions-to-clone-datavolumes[additional permissions] to clone the PVC of a virtual machine disk into another namespace. - -:blockstorage: -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-about-block-pvs.adoc[leveloffset=+1] - -include::modules/virt-creating-local-block-pv.adoc[leveloffset=+1] - -include::modules/virt-cloning-pvc-of-vm-disk-into-new-datavolume.adoc[leveloffset=+1] - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] - -:blockstorage!: - diff --git a/virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc b/virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc deleted file mode 100644 index 66ea80e766cd..000000000000 --- a/virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="virt-cloning-vm-disk-into-new-datavolume"] -= Cloning a virtual machine disk into a new data volume -include::modules/virt-document-attributes.adoc[] -:context: virt-cloning-vm-disk-into-new-datavolume - -toc::[] - -You can clone the persistent volume claim (PVC) of a virtual machine disk into -a new data volume by referencing the source PVC in your data volume configuration -file. - -[WARNING] -==== -Cloning operations between different volume modes are not supported. The `volumeMode` values must match in both the source and target specifications. - -For example, if you attempt to clone from a persistent volume (PV) with `volumeMode: Block` to a PV with `volumeMode: Filesystem`, the operation fails with an error message. -==== - -== Prerequisites - -* Users need xref:../../../virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc#virt-enabling-user-permissions-to-clone-datavolumes[additional permissions] to clone the PVC of a virtual machine disk into another namespace. - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-cloning-pvc-of-vm-disk-into-new-datavolume.adoc[leveloffset=+1] - -include::modules/virt-template-datavolume-clone.adoc[leveloffset=+1] - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] - diff --git a/virt/virtual_machines/cloning_vms/virt-cloning-vm-using-datavolumetemplate.adoc b/virt/virtual_machines/cloning_vms/virt-cloning-vm-using-datavolumetemplate.adoc deleted file mode 100644 index fdee594eeb75..000000000000 --- a/virt/virtual_machines/cloning_vms/virt-cloning-vm-using-datavolumetemplate.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="virt-cloning-vm-using-datavolumetemplate"] -= Cloning a virtual machine by using a data volume template -include::modules/virt-document-attributes.adoc[] -:context: virt-cloning-vm-using-datavolumetemplate - -toc::[] - -You can create a new virtual machine by cloning the persistent volume claim (PVC) of -an existing VM. By including a `dataVolumeTemplate` in your virtual machine -configuration file, you create a new data volume from the original PVC. - -[WARNING] -==== -Cloning operations between different volume modes are not supported. The `volumeMode` values must match in both the source and target specifications. - -For example, if you attempt to clone from a persistent volume (PV) with `volumeMode: Block` to a PV with `volumeMode: Filesystem`, the operation fails with an error message. -==== - -== Prerequisites - -* Users need xref:../../../virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc#virt-enabling-user-permissions-to-clone-datavolumes[additional permissions] to clone the PVC of a virtual machine disk into another namespace. - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-creating-new-vm-from-cloned-pvc-using-datavolumetemplate.adoc[leveloffset=+1] - -include::modules/virt-template-datavolume-vm.adoc[leveloffset=+1] - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc b/virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc deleted file mode 100644 index 5ef84fb4d391..000000000000 --- a/virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[id="virt-enabling-user-permissions-to-clone-datavolumes"] -= Enabling user permissions to clone data volumes across namespaces -include::modules/virt-document-attributes.adoc[] -:context: virt-enabling-user-permissions-to-clone-datavolumes - -toc::[] - -The isolating nature of namespaces means that users cannot by default -clone resources between namespaces. - -To enable a user to clone a virtual machine to another namespace, a -user with the `cluster-admin` role must create a new cluster role. Bind -this cluster role to a user to enable them to clone virtual machines -to the destination namespace. - -== Prerequisites - -* Only a user with the xref:../../../authentication/using-rbac.adoc#default-roles_using-rbac[`cluster-admin`] -role can create cluster roles. - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-creating-rbac-cloning-dvs.adoc[leveloffset=+1] - - diff --git a/virt/virtual_machines/images b/virt/virtual_machines/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/virt/virtual_machines/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/virt/virtual_machines/importing_vms/images b/virt/virtual_machines/importing_vms/images deleted file mode 120000 index 4dd3347de19a..000000000000 --- a/virt/virtual_machines/importing_vms/images +++ /dev/null @@ -1 +0,0 @@ -../../../images \ No newline at end of file diff --git a/virt/virtual_machines/importing_vms/modules b/virt/virtual_machines/importing_vms/modules deleted file mode 120000 index 5be29a99c161..000000000000 --- a/virt/virtual_machines/importing_vms/modules +++ /dev/null @@ -1 +0,0 @@ -../../../modules \ No newline at end of file diff --git a/virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc b/virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc deleted file mode 100644 index bb811dc0d64c..000000000000 --- a/virt/virtual_machines/importing_vms/virt-importing-rhv-vm.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="virt-importing-rhv-vm"] -= Importing a single Red Hat Virtualization virtual machine -include::modules/virt-document-attributes.adoc[] -:context: virt-importing-rhv-vm -:virt-importing-rhv-vm: - -toc::[] - -You can import a single Red Hat Virtualization (RHV) virtual machine into {VirtProductName} by using the VM Import wizard or the CLI. - -include::modules/virt-features-for-storage-matrix.adoc[leveloffset=+1] -include::modules/virt-importing-vm-prerequisites.adoc[leveloffset=+1] -include::modules/virt-importing-vm-wizard.adoc[leveloffset=+1] -:!virt-importing-rhv-vm: - -:virtualmachine: -[discrete] -include::modules/virt-vm-wizard-fields-web.adoc[leveloffset=+2] -[discrete] -include::modules/virt-networking-wizard-fields-web.adoc[leveloffset=+2] -[discrete] -include::modules/virt-storage-wizard-fields-web.adoc[leveloffset=+2] -:virtualmachine!: - -:virt-importing-rhv-vm: -include::modules/virt-importing-vm-cli.adoc[leveloffset=+1] -include::modules/virt-creating-configmap.adoc[leveloffset=+2] -include::modules/virt-troubleshooting-vm-import.adoc[leveloffset=+1] -:!virt-importing-rhv-vm: diff --git a/virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc b/virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc deleted file mode 100644 index 17324bb7a27b..000000000000 --- a/virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes-block.adoc +++ /dev/null @@ -1,44 +0,0 @@ -[id="virt-importing-virtual-machine-images-datavolumes-block"] -= Importing virtual machine images to block storage with data volumes -include::modules/virt-document-attributes.adoc[] -:context: virt-importing-virtual-machine-images-datavolumes-block - -toc::[] - -You can import an existing virtual machine image into your {product-title} -cluster. {VirtProductName} uses data volumes to automate the import of data and the -creation of an underlying persistent volume claim (PVC). - -[IMPORTANT] -==== -When you import a disk image into a PVC, the disk image is -expanded to use the full storage capacity that is requested in the PVC. To use -this space, the disk partitions and file system(s) in the virtual machine -might need to be expanded. - -The resizing procedure varies based on the operating system that is installed on the virtual machine. -Refer to the operating system documentation for details. -==== - -== Prerequisites - -* If you require scratch space according to the -xref:#virt-cdi-supported-operations-matrix_virt-importing-virtual-machine-images-datavolumes-block[CDI supported operations matrix], you must first -xref:../../../virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc#virt-defining-storageclass-in-cdi_virt-preparing-cdi-scratch-space[define a storage class or prepare CDI scratch space] -for this operation to complete successfully. - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-about-block-pvs.adoc[leveloffset=+1] - -include::modules/virt-creating-local-block-pv.adoc[leveloffset=+1] - -include::modules/virt-importing-vm-to-block-pv.adoc[leveloffset=+1] - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] - -[id="{context}_additional-resources"] -== Additional resources - -* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations. - diff --git a/virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc b/virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc deleted file mode 100644 index f98ad8134024..000000000000 --- a/virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc +++ /dev/null @@ -1,46 +0,0 @@ -[id="virt-importing-virtual-machine-images-datavolumes"] -= Importing virtual machine images with data volumes -include::modules/virt-document-attributes.adoc[] -:context: virt-importing-virtual-machine-images-datavolumes - -toc::[] - -Use the Containerized Data Importer (CDI) to import a virtual machine image into a persistent volume claim (PVC) by using a data volume. You can attach a data volume to a virtual machine for persistent storage. - -The virtual machine image can be hosted at an HTTP or HTTPS endpoint, or built into a container disk and stored in a container registry. - -[IMPORTANT] -==== -When you import a disk image into a PVC, the disk image is expanded to use the full storage capacity that is requested in the PVC. To use this space, the disk partitions and file system(s) in the virtual machine might need to be expanded. - -The resizing procedure varies based on the operating system installed on the virtual machine. Refer to the operating system documentation for details. -==== - -== Prerequisites - -* If the endpoint requires a TLS certificate, the certificate must be -xref:../../../virt/virtual_machines/importing_vms/virt-tls-certificates-for-dv-imports.adoc#virt-adding-tls-certificates-for-authenticating-dv-imports_virt-tls-certificates-for-dv-imports[included in a config map] -in the same namespace as the data volume and referenced in the data volume configuration. - -* To import a container disk: -** You might need to xref:../../../virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc#virt-preparing-container-disk-for-vms_virt-using-container-disks-with-vms[prepare a container disk from a virtual machine image] and store it in your container registry before importing it. -** If the container registry does not have TLS, you must xref:../../../virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc#virt-disabling-tls-for-registry_virt-using-container-disks-with-vms[add the registry to the `cdi-insecure-registries` config map] before you can import a container disk from it. - -* You might need to xref:../../../virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc#virt-defining-storageclass-in-cdi_virt-preparing-cdi-scratch-space[define a storage class or prepare CDI scratch space] -for this operation to complete successfully. - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-importing-vm-datavolume.adoc[leveloffset=+1] - -// commenting out these as their value without maintenance plan seems questionable at this stage -// include::modules/virt-template-datavolume-vm.adoc[leveloffset=+1] - -// include::modules/virt-template-datavolume-import.adoc[leveloffset=+1] - -[id="{context}_additional-resources"] -== Additional resources - -* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations. diff --git a/virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc b/virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc deleted file mode 100644 index 05bc763901c0..000000000000 --- a/virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc +++ /dev/null @@ -1,74 +0,0 @@ -[id="virt-importing-vmware-vm"] -= Importing a single VMware virtual machine or template -include::modules/virt-document-attributes.adoc[] -:context: virt-importing-vmware-vm -:virt-importing-vmware-vm: - -toc::[] - -You can import a VMware vSphere 6.5, 6.7, or 7.0 VM or VM template into {VirtProductName} by using the VM Import wizard. - -If you import a VM template, {VirtProductName} creates a virtual machine based on the template. - -include::modules/virt-features-for-storage-matrix.adoc[leveloffset=+1] - -[id="preparing-a-vddk-image_{context}"] -== Preparing a VDDK image - -The import process uses the VMware Virtual Disk Development Kit (VDDK) to copy the VMware virtual disk. - -You can download the VDDK SDK, create a VDDK image, upload the image to an image registry, and add it to the `v2v-vmware` config map. - -You can configure either an internal {product-title} image registry or a secure external image registry for the VDDK image. The registry must be accessible to your {VirtProductName} environment. - -[NOTE] -==== -Storing the VDDK image in a public registry might violate the terms of the VMware license. -==== - -[id="configuring-an-internal-image-registry_{context}"] -=== Configuring an internal image registry - -You can configure the internal {product-title} image registry on bare metal by updating the Image Registry Operator configuration. - -You can access the registry directly, from within the {product-title} cluster, or externally, by exposing the registry with a route. - -[discrete] -include::modules/registry-change-management-state.adoc[leveloffset=+3] -[discrete] -include::modules/registry-configuring-storage-baremetal.adoc[leveloffset=+3] -[discrete] -include::modules/registry-accessing-directly.adoc[leveloffset=+3] -[discrete] -include::modules/registry-exposing-secure-registry-manually.adoc[leveloffset=+3] - -[id="configuring-an-external-image-registry_{context}"] -=== Configuring an external image registry - -If you use an external image registry for the VDDK image, you can add the external image registry's certificate authorities to the {product-title} cluster. - -Optionally, you can create a pull secret from your Docker credentials and add it to your service account. - -[discrete] -include::modules/configmap-adding-ca.adoc[leveloffset=+3] -[discrete] -include::modules/images-allow-pods-to-reference-images-from-secure-registries.adoc[leveloffset=+3] - -include::modules/virt-creating-vddk-image.adoc[leveloffset=+2] - -include::modules/virt-importing-vm-wizard.adoc[leveloffset=+1] -:!virt-importing-vmware-vm: -:virtualmachine: -[discrete] -include::modules/virt-vm-wizard-fields-web.adoc[leveloffset=+2] -[discrete] -include::modules/virt-cloud-init-fields-web.adoc[leveloffset=+2] -[discrete] -include::modules/virt-networking-wizard-fields-web.adoc[leveloffset=+2] -[discrete] -include::modules/virt-storage-wizard-fields-web.adoc[leveloffset=+2] -:virtualmachine!: -:virt-importing-vmware-vm: -include::modules/virt-updating-imported-vm-network-name.adoc[leveloffset=+2] -include::modules/virt-troubleshooting-vm-import.adoc[leveloffset=+1] -:!virt-importing-vmware-vm: diff --git a/virt/virtual_machines/importing_vms/virt-tls-certificates-for-dv-imports.adoc b/virt/virtual_machines/importing_vms/virt-tls-certificates-for-dv-imports.adoc deleted file mode 100644 index 8a159822d77f..000000000000 --- a/virt/virtual_machines/importing_vms/virt-tls-certificates-for-dv-imports.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="virt-tls-certificates-for-dv-imports"] -= TLS certificates for data volume imports -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-tls-certificates-for-dv-imports - -toc::[] - -include::modules/virt-adding-tls-certificates-for-authenticating-dv-imports.adoc[leveloffset=+1] -include::modules/virt-example-configmap-tls-certificate.adoc[leveloffset=+1] - - diff --git a/virt/virtual_machines/modules b/virt/virtual_machines/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/virt/virtual_machines/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/virt/virtual_machines/virt-accessing-vm-consoles.adoc b/virt/virtual_machines/virt-accessing-vm-consoles.adoc deleted file mode 100644 index c38fff0e1df8..000000000000 --- a/virt/virtual_machines/virt-accessing-vm-consoles.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="virt-accessing-vm-consoles"] -= Accessing virtual machine consoles -include::modules/virt-document-attributes.adoc[] -:context: virt-accessing-vm-consoles - -toc::[] - -{VirtProductName} provides different virtual machine consoles that you can -use to accomplish different product tasks. You can access these consoles through -the web console and by using CLI commands. - -include::modules/virt-about-vm-console-sessions.adoc[leveloffset=+1] - -[id="virt-accessing-vm-consoles-web"] -== Connecting to the virtual machine with the web console - -include::modules/virt-connecting-to-the-terminal.adoc[leveloffset=+2] - -include::modules/virt-vm-serial-console-web.adoc[leveloffset=+2] - -include::modules/virt-connecting-vnc-console.adoc[leveloffset=+2] - -include::modules/virt-vm-rdp-console-web.adoc[leveloffset=+2] - -[id="virt-accessing-vm-consoles-cli"] -== Accessing virtual machine consoles by using CLI commands - -include::modules/virt-accessing-vmi-ssh.adoc[leveloffset=+2] - -include::modules/virt-accessing-serial-console.adoc[leveloffset=+2] - -include::modules/virt-accessing-vnc-console.adoc[leveloffset=+2] - -include::modules/virt-accessing-rdp-console.adoc[leveloffset=+2] diff --git a/virt/virtual_machines/virt-controlling-vm-states.adoc b/virt/virtual_machines/virt-controlling-vm-states.adoc deleted file mode 100644 index c5f36b8401b8..000000000000 --- a/virt/virtual_machines/virt-controlling-vm-states.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="virt-controlling-vm-states"] -= Controlling virtual machine states -include::modules/virt-document-attributes.adoc[] -:context: virt-controlling-vm-states - -toc::[] - -You can stop, start, restart, and unpause virtual machines from the web console. - -[NOTE] -==== -To control virtual machines from the command-line interface (CLI), use the -xref:../../virt/virt-using-the-cli-tools.html#virt-using-the-cli-tools[`virtctl` client]. -==== - -include::modules/virt-starting-vm-web.adoc[leveloffset=+1] - -include::modules/virt-restarting-vm-web.adoc[leveloffset=+1] - -include::modules/virt-stopping-vm-web.adoc[leveloffset=+1] - -include::modules/virt-unpausing-vm-web.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virt-create-vms.adoc b/virt/virtual_machines/virt-create-vms.adoc deleted file mode 100644 index 21e750228765..000000000000 --- a/virt/virtual_machines/virt-create-vms.adoc +++ /dev/null @@ -1,62 +0,0 @@ -[id="virt-create-vms"] -= Creating virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-create-vms - -toc::[] - - -Use one of these procedures to create a virtual machine: - -* Quick Start guided tour -* Running the wizard -* Pasting a pre-configured YAML file with the virtual machine wizard -* Using the CLI -* xref:../../virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc#virt-importing-vmware-vm[Importing a VMware virtual machine or template with the virtual machine wizard] - -[WARNING] -==== -Do not create virtual machines in `openshift-*` namespaces. -Instead, create a new namespace or use an existing namespace without the `openshift` prefix. -==== - -When you create virtual machines from the web console, select a virtual machine template that is configured with a boot source. Virtual machine templates with a boot source are labeled as *Available boot source* or they display a customized label text. Using templates with an available boot source expedites the process of creating virtual machines. - -Templates without a boot source are labeled as *Boot source required*. You can use these templates if you complete the steps for xref:../../virt/vm_templates/virt-creating-vm-template.adoc#virt-adding-a-boot-source-web_virt-creating-vm-template[adding a boot source to the virtual machine]. - -include::modules/virt-creating-vm-quick-start-web.adoc[leveloffset=+1] -include::modules/virt-creating-vm-wizard-web.adoc[leveloffset=+1] - -Refer to the virtual machine wizard fields section when running the web console wizard. - -:virtualmachine: -include::modules/virt-vm-wizard-fields-web.adoc[leveloffset=+2] -include::modules/virt-networking-wizard-fields-web.adoc[leveloffset=+2] -include::modules/virt-storage-wizard-fields-web.adoc[leveloffset=+2] -include::modules/virt-cloud-init-fields-web.adoc[leveloffset=+2] - -For more information on the `kubevirt-storage-class-defaults` config map, see xref:../../virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc#virt-storage-defaults-for-datavolumes[ -Storage defaults for data volumes]. - -include::modules/virt-creating-vm-yaml-web.adoc[leveloffset=+1] -include::modules/virt-creating-vm.adoc[leveloffset=+1] - -:virtualmachine!: - -include::modules/virt-vm-storage-volume-types.adoc[leveloffset=+1] -include::modules/virt-about-runstrategies-vms.adoc[leveloffset=+1] - -== Additional resources - -* The `VirtualMachineSpec` definition in the link:https://kubevirt.io/api-reference/{KubeVirtVersion}/definitions.html#_v1_virtualmachinespec[KubeVirt {KubeVirtVersion} API Reference] provides broader context for the parameters and hierarchy of the virtual machine specification. - -+ -[NOTE] -==== -The KubeVirt API Reference is the upstream project reference and might contain parameters that are not supported in {VirtProductName}. -==== - -* xref:../../virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc#virt-using-container-disks-with-vms[Prepare a container disk] before adding it to a virtual machine as a `containerDisk` volume. -* See xref:../../machine_management/deploying-machine-health-checks.adoc#machine-health-checks-about_deploying-machine-health-checks[Deploying machine health checks] for further details on deploying and enabling machine health checks. -* See xref:../../installing/installing_bare_metal_ipi/ipi-install-overview.adoc#ipi-install-overview[Installer-provisioned infrastructure overview] for further details on installer-provisioned infrastructure. -* See xref:../../virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc#virt-configuring-sriov-device-for-vms[Configuring the SR-IOV Network Operator] for further details on the SR-IOV Network Operator. diff --git a/virt/virtual_machines/virt-delete-vms.adoc b/virt/virtual_machines/virt-delete-vms.adoc deleted file mode 100644 index 6009059a5e4d..000000000000 --- a/virt/virtual_machines/virt-delete-vms.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="virt-delete-vms"] -= Deleting virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-delete-vms - -toc::[] - -You can delete a virtual machine from the web console or by using the `oc` command line interface. - -include::modules/virt-delete-vm-web.adoc[leveloffset=+1] -include::modules/virt-deleting-vms.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virt-edit-boot-order.adoc b/virt/virtual_machines/virt-edit-boot-order.adoc deleted file mode 100644 index 6bf2d9fe1316..000000000000 --- a/virt/virtual_machines/virt-edit-boot-order.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="virt-edit-boot-order"] -= Editing boot order -include::modules/virt-document-attributes.adoc[] -:context: virt-edit-boot-order - -toc::[] - -You can update the values for a boot order list by using the web console or the CLI. - -With *Boot Order* in the *Virtual Machine Overview* page, you can: - -* Select a disk or network interface card (NIC) and add it to the boot order list. -* Edit the order of the disks or NICs in the boot order list. -* Remove a disk or NIC from the boot order list, and return it back to the inventory of bootable sources. - -include::modules/virt-add-boot-order-web.adoc[leveloffset=+1] -include::modules/virt-edit-boot-order-web.adoc[leveloffset=+1] -include::modules/virt-edit-boot-order-yaml-web.adoc[leveloffset=+1] -include::modules/virt-remove-boot-order-item-web.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virt-edit-vms.adoc b/virt/virtual_machines/virt-edit-vms.adoc deleted file mode 100644 index bfcb24406e2c..000000000000 --- a/virt/virtual_machines/virt-edit-vms.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="virt-edit-vms"] -= Editing virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-edit-vms - -toc::[] - -You can update a virtual machine configuration using either the YAML editor in the web console or the OpenShift client on the command line. You can also update a subset of the parameters in the *Virtual Machine Details* screen. - -include::modules/virt-editing-vm-web.adoc[leveloffset=+1] -include::modules/virt-editing-vm-yaml-web.adoc[leveloffset=+1] -include::modules/virt-editing-vm-cli.adoc[leveloffset=+1] -include::modules/virt-add-disk-to-vm.adoc[leveloffset=+1] - -For more information on the `kubevirt-storage-class-defaults` config map, see xref:../../virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc#virt-storage-defaults-for-datavolumes[ -Storage defaults for data volumes]. - -include::modules/virt-storage-wizard-fields-web.adoc[leveloffset=+2] -include::modules/virt-add-nic-to-vm.adoc[leveloffset=+1] -include::modules/virt-networking-wizard-fields-web.adoc[leveloffset=+2] -include::modules/virt-edit-cdrom-vm.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virt-installing-qemu-guest-agent.adoc b/virt/virtual_machines/virt-installing-qemu-guest-agent.adoc deleted file mode 100644 index 44ff631e7962..000000000000 --- a/virt/virtual_machines/virt-installing-qemu-guest-agent.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="virt-installing-qemu-guest-agent"] -= Installing the QEMU guest agent on virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-installing-qemu-guest-agent - -toc::[] - -The xref:../../virt/virtual_machines/virt-viewing-qemu-guest-agent-web.adoc#virt-viewing-qemu-guest-agent-web[QEMU guest agent] is a daemon that runs on the virtual machine and passes information to the host about the virtual machine, users, file systems, and secondary networks. - -include::modules/virt-installing-qemu-guest-agent-on-linux-vm.adoc[leveloffset=+1] - -You can also install and start the QEMU guest agent by using the -*custom script* field in the *cloud-init* section of the wizard when creating either -virtual machines or virtual machines templates in the web console. - -include::modules/virt-installing-qemu-guest-agent-on-windows-vm.adoc[leveloffset=+1] - -include::modules/virt-installing-virtio-drivers-existing-windows.adoc[leveloffset=+2] - -include::modules/virt-installing-virtio-drivers-installing-windows.adoc[leveloffset=+2] diff --git a/virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc b/virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc deleted file mode 100644 index f64622fd083e..000000000000 --- a/virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="virt-installing-virtio-drivers-on-existing-windows-vm"] -= Installing VirtIO driver on an existing Windows virtual machine -include::modules/virt-document-attributes.adoc[] -:context: virt-installing-virtio-drivers-on-existing-windows-vm - -toc::[] - -include::modules/virt-understanding-virtio-drivers.adoc[leveloffset=+1] - -See also: xref:../../virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc#virt-installing-virtio-drivers-on-new-windows-vm[Installing Virtio drivers on a new Windows virtual machine]. - -include::modules/virt-supported-virtio-drivers.adoc[leveloffset=+1] - -include::modules/virt-adding-virtio-drivers-vm-yaml.adoc[leveloffset=+1] - -include::modules/virt-installing-virtio-drivers-existing-windows.adoc[leveloffset=+1] - -include::modules/virt-removing-virtio-disk-from-vm.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc b/virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc deleted file mode 100644 index f94143746a56..000000000000 --- a/virt/virtual_machines/virt-installing-virtio-drivers-on-new-windows-vm.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="virt-installing-virtio-drivers-on-new-windows-vm"] -= Installing VirtIO driver on a new Windows virtual machine -include::modules/virt-document-attributes.adoc[] -:context: virt-installing-virtio-drivers-on-new-windows-vm" - -toc::[] - -== Prerequisites - -* Windows installation media accessible by the virtual machine, such as -xref:../../virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc#virt-importing-vm-datavolume_virt-importing-virtual-machine-images-datavolumes[importing an ISO into a data volume] -and attaching it to the virtual machine. - -include::modules/virt-understanding-virtio-drivers.adoc[leveloffset=+1] - -See also: xref:../../virt/virtual_machines/virt-installing-virtio-drivers-on-existing-windows-vm.adoc#virt-installing-virtio-drivers-on-existing-windows-vm[Installing VirtIO driver on an existing Windows virtual machine]. - -include::modules/virt-supported-virtio-drivers.adoc[leveloffset=+1] - -include::modules/virt-adding-virtio-drivers-vm-yaml.adoc[leveloffset=+1] - -include::modules/virt-installing-virtio-drivers-installing-windows.adoc[leveloffset=+1] - -include::modules/virt-removing-virtio-disk-from-vm.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virt-manage-vmis.adoc b/virt/virtual_machines/virt-manage-vmis.adoc deleted file mode 100644 index 035d29d13920..000000000000 --- a/virt/virtual_machines/virt-manage-vmis.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="virt-manage-vmis"] -= Managing virtual machine instances -include::modules/virt-document-attributes.adoc[] -:context: virt-manage-vmis - -toc::[] - -If you have standalone virtual machine instances (VMIs) that were created independently outside of the {VirtProductName} environment, you can manage them by using the web console or the command-line interface (CLI). - -include::modules/virt-about-vmis.adoc[leveloffset=+1] -include::modules/virt-listing-vmis-cli.adoc[leveloffset=+1] -include::modules/virt-listing-vmis-web.adoc[leveloffset=+1] -include::modules/virt-editing-vmis-web.adoc[leveloffset=+1] -include::modules/virt-deleting-vmis-cli.adoc[leveloffset=+1] -include::modules/virt-deleting-vmis-web.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virt-managing-configmaps-secrets-service-accounts.adoc b/virt/virtual_machines/virt-managing-configmaps-secrets-service-accounts.adoc deleted file mode 100644 index 5333b9f74e51..000000000000 --- a/virt/virtual_machines/virt-managing-configmaps-secrets-service-accounts.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="virt-managing-configmaps-secrets-service-accounts"] -= Managing config maps, secrets, and service accounts in virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-managing-configmaps-secrets-service-accounts - -toc::[] - -You can use secrets, config maps, and service accounts to pass configuration data to virtual machines. For example, you can: - -* Give a virtual machine access to a service that requires credentials by adding a secret to the virtual machine. -* Store non-confidential configuration data in a config map so that a pod or another object can consume the data. -* Allow a component to access the API server by associating a service account with that component. - -[NOTE] -==== -{VirtProductName} exposes secrets, config maps, and service accounts as virtual machine disks so that you can use them across platforms without additional overhead. -==== - -include::modules/virt-adding-secret-configmap-service-account-to-vm.adoc[leveloffset=+1] - -include::modules/virt-removing-secret-configmap-service-account-vm.adoc[leveloffset=+1] - - -== Additional resources - -* xref:../../nodes/pods/nodes-pods-secrets.adoc#nodes-pods-secrets-about[Providing sensitive data to pods] - -* xref:../../authentication/understanding-and-creating-service-accounts.adoc#service-accounts-overview[Understanding and creating service accounts] - -* xref:../../authentication/configmaps.adoc#authentication-configmap-overview_builds-configmaps[Understanding config maps] diff --git a/virt/virtual_machines/virt-triggering-vm-failover-resolving-failed-node.adoc b/virt/virtual_machines/virt-triggering-vm-failover-resolving-failed-node.adoc deleted file mode 100644 index 42b0a4bf2ee3..000000000000 --- a/virt/virtual_machines/virt-triggering-vm-failover-resolving-failed-node.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[id="virt-triggering-vm-failover-resolving-failed-node"] -= Triggering virtual machine failover by resolving a failed node -include::modules/virt-document-attributes.adoc[] -include::modules/common-attributes.adoc[] -:context: virt-triggering-vm-failover-resolving-failed-node - -toc::[] - -If a node fails and xref:../../machine_management/deploying-machine-health-checks.adoc#machine-health-checks-about_deploying-machine-health-checks[machine health checks] are not deployed on your cluster, virtual machines (VMs) with `RunStrategy: Always` configured are not automatically relocated to healthy nodes. To trigger VM failover, you must manually delete the `Node` object. - -[NOTE] -==== -If you installed your cluster by using xref:../../installing/installing_bare_metal_ipi/ipi-install-overview.adoc#ipi-install-overview[installer-provisioned infrastructure] and you properly configured machine health checks: - -* Failed nodes are automatically recycled. -* Virtual machines with xref:../../virt/virtual_machines/virt-create-vms.adoc#virt-about-runstrategies-vms_virt-create-vms[`RunStrategy`] set to `Always` or `RerunOnFailure` are automatically scheduled on healthy nodes. -==== - -[id="prerequisites_{context}"] -== Prerequisites - -* A node where a virtual machine was running has the `NotReady` xref:../../nodes/nodes/nodes-nodes-viewing.adoc#nodes-nodes-viewing-listing_nodes-nodes-viewing[condition]. -* The virtual machine that was running on the failed node has `RunStrategy` set to `Always`. -* You have installed the OpenShift CLI (`oc`). - -include::modules/nodes-nodes-working-deleting-bare-metal.adoc[leveloffset=+1] - -[id="verifying-vm-failover_{context}"] -== Verifying virtual machine failover - -After all resources are terminated on the unhealthy node, a new virtual machine instance (VMI) is automatically created on a healthy node for each relocated VM. To confirm that the VMI was created, view all VMIs by using the `oc` CLI. - -include::modules/virt-listing-vmis-cli.adoc[leveloffset=+2] diff --git a/virt/virtual_machines/virt-viewing-qemu-guest-agent-web.adoc b/virt/virtual_machines/virt-viewing-qemu-guest-agent-web.adoc deleted file mode 100644 index 6d3f6fecb160..000000000000 --- a/virt/virtual_machines/virt-viewing-qemu-guest-agent-web.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="virt-viewing-qemu-guest-agent-web"] -= Viewing the QEMU guest agent information for virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-viewing-qemu-guest-agent-web - -toc::[] - -When the QEMU guest agent runs on the virtual machine, you can use the web console to view information about the virtual machine, users, file systems, and secondary networks. - -== Prerequisites - -* Install the xref:../../virt/virtual_machines/virt-installing-qemu-guest-agent.adoc#virt-installing-qemu-guest-agent[QEMU guest agent] on the virtual machine. - -include::modules/virt-about-qemu-guest-agent-web.adoc[leveloffset=+1] - -include::modules/virt-viewing-qemu-guest-agent-information-web.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virtual_disks/images b/virt/virtual_machines/virtual_disks/images deleted file mode 120000 index 4dd3347de19a..000000000000 --- a/virt/virtual_machines/virtual_disks/images +++ /dev/null @@ -1 +0,0 @@ -../../../images \ No newline at end of file diff --git a/virt/virtual_machines/virtual_disks/modules b/virt/virtual_machines/virtual_disks/modules deleted file mode 120000 index 5be29a99c161..000000000000 --- a/virt/virtual_machines/virtual_disks/modules +++ /dev/null @@ -1 +0,0 @@ -../../../modules \ No newline at end of file diff --git a/virt/virtual_machines/virtual_disks/virt-cloning-a-datavolume-using-smart-cloning.adoc b/virt/virtual_machines/virtual_disks/virt-cloning-a-datavolume-using-smart-cloning.adoc deleted file mode 100644 index 792ddad69514..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-cloning-a-datavolume-using-smart-cloning.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="virt-cloning-a-datavolume-using-smart-cloning"] -= Cloning a data volume using smart-cloning -include::modules/virt-document-attributes.adoc[] -:context: virt-cloning-a-datavolume-using-smart-cloning - -toc::[] - -Smart-cloning is a built-in feature of {product-title} Storage (OCS), -designed to enhance performance of the cloning process. Clones created with smart-cloning are faster and more efficient than host-assisted cloning. - -You do not need to perform any action to enable smart-cloning, but you need to ensure your storage environment is compatible with smart-cloning to use this feature. - -When you create a data volume with a persistent volume claim (PVC) source, you automatically initiate the cloning process. You always receive a clone of the data volume, if your environment supports smart-cloning or not. However, you will only receive the performance benefits of smart cloning if you storage provider supports smart-cloning. - -include::modules/virt-understanding-smart-cloning.adoc[leveloffset=+1] - -include::modules/virt-cloning-a-datavolume.adoc[leveloffset=+1] - -[id="{context}_additional-resources"] -== Additional resources - -* xref:../../../virt/virtual_machines/cloning_vms/virt-cloning-vm-disk-into-new-datavolume.adoc#virt-cloning-pvc-of-vm-disk-into-new-datavolume_virt-cloning-vm-disk-into-new-datavolume[Cloning the persistent volume claim of a virtual machine disk into a new data volume] - -* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations. diff --git a/virt/virtual_machines/virtual_disks/virt-configuring-cdi-for-namespace-resourcequota.adoc b/virt/virtual_machines/virtual_disks/virt-configuring-cdi-for-namespace-resourcequota.adoc deleted file mode 100644 index d4121b6d9884..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-configuring-cdi-for-namespace-resourcequota.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="virt-configuring-cdi-for-namespace-resourcequota"] -= Configuring CDI to work with namespaces that have a compute resource quota -include::modules/virt-document-attributes.adoc[] -:context: virt-configuring-cdi-for-namespace-resourcequota - -toc::[] - -You can use the Containerized Data Importer (CDI) to import, upload, and clone virtual machine disks into namespaces that are subject to CPU and memory resource restrictions. - -include::modules/virt-about-cpu-and-memory-quota-namespace.adoc[leveloffset=+1] - -include::modules/virt-editing-cdi-cpu-and-memory-defaults.adoc[leveloffset=+1] - -== Additional resources - -* xref:../../../applications/quotas/quotas-setting-per-project.adoc#quotas-setting-per-project[Resource quotas per project] diff --git a/virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc b/virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc deleted file mode 100644 index b684f2dbf746..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="virt-configuring-local-storage-for-vms"] -= Configuring local storage for virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-configuring-local-storage-for-vms - -toc::[] - -You can configure local storage for your virtual machines by using the hostpath -provisioner feature. - -include::modules/virt-about-hostpath-provisioner.adoc[leveloffset=+1] - -include::modules/virt-configuring-selinux-hpp-on-rhcos8.adoc[leveloffset=+1] - -include::modules/virt-using-hostpath-provisioner.adoc[leveloffset=+1] - -[id="virt-local-storage-resources"] -=== Additional resources -* xref:../../../virt/install/virt-specifying-nodes-for-virtualization-components.adoc#virt-specifying-nodes-for-virtualization-components[Specifying nodes for virtualization components] - -include::modules/virt-creating-storage-class.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virtual_disks/virt-creating-and-using-boot-sources.adoc b/virt/virtual_machines/virtual_disks/virt-creating-and-using-boot-sources.adoc deleted file mode 100644 index 6e8754509abb..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-creating-and-using-boot-sources.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[id="virt-creating-and-using-boot-sources"] -= Creating and using boot sources -include::modules/virt-document-attributes.adoc[] -:context: virt-creating-and-using-boot-sources - -toc::[] - -A _boot source_ contains a bootable operating system (OS) and all of the configuration settings for the OS, such as drivers. - -You use a boot source to create virtual machine templates with specific configurations. These templates can be used to create any number of available virtual machines. - -.Prerequisites -* To add a boot source, you must be logged in as a user with the `os-images.kubevirt.io:edit` RBAC role or as an administrator. You do not need special privileges to create a virtual machine from a template with a boot source attached. - -[NOTE] -==== -For information about requirements for Microsoft Windows, refer to link:https://www.openshift.com/blog/creating-an-operating-system-image-using-the-microsoft-windows-installation-media-with-openshift-virtualization[Creating installation media for Windows boot sources]. -==== - -// Commenting this module with list of supported DV names for 2.6. It is relevant only to 2.6.1 when the CLI flow is introduced -// include::modules/virt-using-supported-boot-source-names.adoc[leveloffset=+1] - -include::modules/virt-adding-a-boot-source-web.adoc[leveloffset=+1] - -include::modules/virt-creating-a-vm-from-a-template-with-an-attached-boot-source.adoc[leveloffset=+1] - -== Additional resources -* xref:../../../virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-web.adoc#virt-uploading-local-disk-images-web[Uploading local disk images] diff --git a/virt/virtual_machines/virtual_disks/virt-deleting-datavolumes.adoc b/virt/virtual_machines/virtual_disks/virt-deleting-datavolumes.adoc deleted file mode 100644 index 8ad3faeccd9c..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-deleting-datavolumes.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="virt-deleting-datavolumes"] -= Deleting data volumes -include::modules/virt-document-attributes.adoc[] -:context: virt-deleting-datavolumes - -toc::[] - -You can manually delete a data volume by using the `oc` command-line interface. + -[NOTE] -==== -When you delete a virtual machine, the data volume it uses is automatically deleted. -==== - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] -include::modules/virt-listing-dvs.adoc[leveloffset=+1] -include::modules/virt-deleting-dvs.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virtual_disks/virt-expanding-virtual-storage-with-blank-disk-images.adoc b/virt/virtual_machines/virtual_disks/virt-expanding-virtual-storage-with-blank-disk-images.adoc deleted file mode 100644 index 5c19f6b9e716..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-expanding-virtual-storage-with-blank-disk-images.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="virt-expanding-virtual-storage-with-blank-disk-images"] -= Expanding virtual storage by adding blank disk images -include::modules/virt-document-attributes.adoc[] -:context: virt-expanding-virtual-storage-with-blank-disk-images - -toc::[] - -You can increase your storage capacity or create new data partitions by adding -blank disk images to {VirtProductName}. - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-creating-blank-disk-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-template-blank-disk-datavolume.adoc[leveloffset=+1] - -[id="{context}_additional-resources"] -== Additional resources - -* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations. diff --git a/virt/virtual_machines/virtual_disks/virt-features-for-storage.adoc b/virt/virtual_machines/virtual_disks/virt-features-for-storage.adoc deleted file mode 100644 index d7c9cc180ec9..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-features-for-storage.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="virt-features-for-storage"] -= Storage features -include::modules/virt-document-attributes.adoc[] -:context: virt-features-for-storage -:virt-features-for-storage: - -toc::[] - -Use the following table to determine feature availability for local and shared -persistent storage in {VirtProductName}. - -include::modules/virt-features-for-storage-matrix.adoc[leveloffset=+1] -:virt-features-for-storage!: diff --git a/virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc b/virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc deleted file mode 100644 index 71502a3aa198..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-managing-offline-vm-snapshots.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="virt-managing-offline-vm-snapshots"] -= Managing offline virtual machine snapshots -include::modules/virt-document-attributes.adoc[] -:context: virt-managing-offline-vm-snapshots - -toc::[] - -You can create, restore, and delete virtual machine (VM) snapshots for VMs that are powered off (offline). {VirtProductName} supports -offline VM snapshots on: - -* Red Hat OpenShift Container Storage -* Any other storage provider with the Container Storage Interface (CSI) driver that supports the Kubernetes Volume Snapshot API - -include::modules/virt-about-vm-snapshots.adoc[leveloffset=+1] - -include::modules/virt-creating-offline-vm-snapshot-web.adoc[leveloffset=+1] - -include::modules/virt-creating-offline-vm-snapshot-cli.adoc[leveloffset=+1] - -include::modules/virt-restoring-vm-from-snapshot-web.adoc[leveloffset=+1] - -include::modules/virt-restoring-vm-from-snapshot-cli.adoc[leveloffset=+1] - -include::modules/virt-deleting-vm-snapshot-web.adoc[leveloffset=+1] - -include::modules/virt-deleting-vm-snapshot-cli.adoc[leveloffset=+1] - -== Additional resources - -* xref:../../../storage/container_storage_interface/persistent-storage-csi-snapshots.adoc#persistent-storage-csi-snapshots[CSI Volume Snapshots] diff --git a/virt/virtual_machines/virtual_disks/virt-moving-local-vm-disk-to-different-node.adoc b/virt/virtual_machines/virtual_disks/virt-moving-local-vm-disk-to-different-node.adoc deleted file mode 100644 index 26ed914c161f..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-moving-local-vm-disk-to-different-node.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="virt-moving-local-vm-disk-to-different-node"] -= Moving a local virtual machine disk to a different node -include::modules/virt-document-attributes.adoc[] -:context: virt-moving-local-vm-disk-to-different-node - -toc::[] - -Virtual machines that use local volume storage can be moved so that they run on a specific node. - -You might want to move the virtual machine to a specific node for the following reasons: - -* The current node has limitations to the local storage configuration. -* The new node is better optimized for the workload of that virtual machine. - -To move a virtual machine that uses local storage, you must clone the underlying volume by using a data volume. After the cloning operation is complete, you can xref:../../../virt/virtual_machines/virt-edit-vms.adoc#virt-edit-vms[edit the virtual machine configuration] so that it uses the new data volume, or xref:../../../virt/virtual_machines/virt-edit-vms.adoc#virt-vm-add-disk_virt-edit-vms[add the new data volume to another virtual machine]. - -[NOTE] -==== -Users without the `cluster-admin` role require xref:../../../virt/virtual_machines/cloning_vms/virt-enabling-user-permissions-to-clone-datavolumes.adoc#virt-enabling-user-permissions-to-clone-datavolumes[additional user permissions] to clone volumes across namespaces. -==== - -include::modules/virt-cloning-local-volume-to-another-node.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc b/virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc deleted file mode 100644 index c11f5514632d..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="virt-preparing-cdi-scratch-space"] -= Preparing CDI scratch space -include::modules/virt-document-attributes.adoc[] -:context: virt-preparing-cdi-scratch-space - -toc::[] - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-understanding-scratch-space.adoc[leveloffset=+1] - -include::modules/virt-operations-requiring-scratch-space.adoc[leveloffset=+1] - -include::modules/virt-defining-storageclass-in-cdi.adoc[leveloffset=+1] - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] - -.Additional resources - -* See the xref:../../../storage/dynamic-provisioning.adoc#about_dynamic-provisioning[Dynamic provisioning] section for more information on storage classes and how these are defined in the cluster. diff --git a/virt/virtual_machines/virtual_disks/virt-reserving-pvc-space-fs-overhead.adoc b/virt/virtual_machines/virtual_disks/virt-reserving-pvc-space-fs-overhead.adoc deleted file mode 100644 index 3e414b829704..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-reserving-pvc-space-fs-overhead.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="virt-reserving-pvc-space-fs-overhead"] -= Reserving PVC space for file system overhead -include::modules/virt-document-attributes.adoc[] -:context: virt-reserving-pvc-space-fs-overhead - -toc::[] - -By default, the Containerized Data Importer (CDI) reserves space for file system overhead data in persistent volume claims (PVCs) that use the `Filesystem` volume mode. You can set the percentage that CDI reserves for this purpose globally and for specific storage classes. - -include::modules/virt-how-fs-overhead-affects-space-vm-disks.adoc[leveloffset=+1] - -include::modules/virt-overriding-default-fs-overhead-value.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virtual_disks/virt-reusing-statically-provisioned-persistent-volumes.adoc b/virt/virtual_machines/virtual_disks/virt-reusing-statically-provisioned-persistent-volumes.adoc deleted file mode 100644 index 61a597800bbc..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-reusing-statically-provisioned-persistent-volumes.adoc +++ /dev/null @@ -1,18 +0,0 @@ -[id="virt-reusing-persistent-volumes"] -= Re-using persistent volumes -include::modules/virt-document-attributes.adoc[] -:context: virt-reusing-statically-provisioned-persistent-volumes - -toc::[] - -To re-use a statically provisioned persistent volume (PV), you must first reclaim the volume. -This involves deleting the PV so that the storage configuration can be re-used. - -include::modules/virt-about-reclaiming-statically-provisioned-persistent-volumes.adoc[leveloffset=+1] -include::modules/virt-reclaiming-statically-provisioned-persistent-volumes.adoc[leveloffset=+1] - -.Additional Resources - -* xref:../../../virt/virtual_machines/virtual_disks/virt-configuring-local-storage-for-vms.adoc#virt-configuring-local-storage-for-vms[Configuring local storage for virtual machines] - -* The {product-title} Storage documentation has more information on xref:../../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Persistent Storage]. diff --git a/virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc b/virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc deleted file mode 100644 index fa8aca53a8ca..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-storage-defaults-for-datavolumes.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="virt-storage-defaults-for-datavolumes"] -= Storage defaults for data volumes -include::modules/virt-document-attributes.adoc[] -:context: virt-storage-defaults-for-datavolumes - -toc::[] - -The `kubevirt-storage-class-defaults` config map provides _access mode_ and _volume mode_ defaults for data volumes. You can edit or add storage class defaults to the config map to create data volumes in the web console that better match the underlying storage. - -include::modules/virt-about-storage-setting-for-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-editing-kubevirtstorageclassdefaults-web.adoc[leveloffset=+1] - -include::modules/virt-editing-kubevirtstorageclassdefaults-cli.adoc[leveloffset=+1] - -include::modules/virt-example-kubevirtstorageclassdefaults.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc b/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc deleted file mode 100644 index 54ce6cd0e37d..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-block.adoc +++ /dev/null @@ -1,43 +0,0 @@ -[id="virt-uploading-local-disk-images-block"] -= Uploading a local disk image to a block storage data volume -include::modules/virt-document-attributes.adoc[] -:context: virt-uploading-local-disk-images-block - -toc::[] - -You can upload a local disk image into a block data volume by using the -`virtctl` command-line utility. - -In this workflow, you create a local block device to use as a persistent volume, -associate this block volume with an `upload` data volume, and use `virtctl` -to upload the local disk image into the data volume. - -== Prerequisites - -* xref:../../../virt/install/virt-installing-virtctl.adoc#virt-installing-virtctl[Install] -the `kubevirt-virtctl` package. -* If you require scratch space according to the -xref:#virt-cdi-supported-operations-matrix_virt-uploading-local-disk-images-block[CDI supported operations matrix], you must first -xref:../../../virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc#virt-defining-storageclass-in-cdi_virt-preparing-cdi-scratch-space[define a storage class or prepare CDI scratch space] -for this operation to complete successfully. - -:blockstorage: -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-about-block-pvs.adoc[leveloffset=+1] - -include::modules/virt-creating-local-block-pv.adoc[leveloffset=+1] - -include::modules/virt-creating-an-upload-dv.adoc[leveloffset=+1] - -include::modules/virt-uploading-local-disk-image-dv.adoc[leveloffset=+1] - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] - -:blockstorage!: - -[id="{context}_additional-resources"] -== Additional resources - -* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations. - diff --git a/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-virtctl.adoc b/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-virtctl.adoc deleted file mode 100644 index a33bfe0aaf97..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-virtctl.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[id="virt-uploading-local-disk-images-virtctl"] -= Uploading local disk images by using the virtctl tool -include::modules/virt-document-attributes.adoc[] -:context: virt-uploading-local-disk-images-virtctl - -toc::[] - -You can upload a locally stored disk image to a new or existing data volume by using the -`virtctl` command-line utility. - -== Prerequisites - -* xref:../../../virt/install/virt-installing-virtctl.adoc#virt-installing-virtctl[Install] -the `kubevirt-virtctl` package. - -* If you require scratch space according to the -xref:#virt-cdi-supported-operations-matrix_virt-cloning-vm-disk-into-new-datavolume-block[CDI supported operations matrix], you must first -xref:../../../virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc#virt-defining-storageclass-in-cdi_virt-preparing-cdi-scratch-space[define a storage class or prepare CDI scratch space] -for this operation to complete successfully. - -include::modules/virt-about-datavolumes.adoc[leveloffset=+1] - -include::modules/virt-creating-an-upload-dv.adoc[leveloffset=+1] - -include::modules/virt-uploading-local-disk-image-dv.adoc[leveloffset=+1] - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] - -[id="{context}_additional-resources"] -== Additional resources - -* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations. - diff --git a/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-web.adoc b/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-web.adoc deleted file mode 100644 index 06477f1ccc05..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-web.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="virt-uploading-local-disk-images-web"] -= Uploading local disk images by using the web console -include::modules/virt-document-attributes.adoc[] -:context: virt-uploading-local-disk-images-web - -toc::[] - -You can upload a locally stored disk image file by using the web console. - -== Prerequisites - -* You must have a virtual machine image file in IMG, ISO, or QCOW2 format. - -* If you require scratch space according to the -xref:../../../virt/virtual_machines/virtual_disks/virt-uploading-local-disk-images-web.adoc#virt-cdi-supported-operations-matrix_virt-uploading-local-disk-images-web[CDI supported operations matrix], you must first -xref:../../../virt/virtual_machines/virtual_disks/virt-preparing-cdi-scratch-space.adoc#virt-defining-storageclass-in-cdi_virt-preparing-cdi-scratch-space[define a storage class or prepare CDI scratch space] -for this operation to complete successfully. - -include::modules/virt-cdi-supported-operations-matrix.adoc[leveloffset=+1] - -include::modules/virt-uploading-image-web.adoc[leveloffset=+1] - -[id="{context}_additional-resources"] -== Additional resources - -* xref:../../../virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc#virt-using-preallocation-for-datavolumes[Configure preallocation mode] to improve write performance for data volume operations. - diff --git a/virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc b/virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc deleted file mode 100644 index 9f0960303b64..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-using-container-disks-with-vms.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[id="virt-using-container-disks-with-vms"] -= Using container disks with virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-using-container-disks-with-vms - -toc::[] - -You can build a virtual machine image into a container disk and store it in your container registry. You can then import the container disk into persistent storage for a virtual machine or attach it directly to the virtual machine for ephemeral storage. - -include::modules/virt-about-container-disks.adoc[leveloffset=+1] -include::modules/virt-preparing-container-disk-for-vms.adoc[leveloffset=+1] - -If your container registry does not have TLS you must add it as an insecure registry before you can import container disks into persistent storage. - -include::modules/virt-disabling-tls-for-registry.adoc[leveloffset=+1] - -== Next steps - -* xref:../../../virt/virtual_machines/importing_vms/virt-importing-virtual-machine-images-datavolumes.adoc#virt-importing-virtual-machine-images-datavolumes[Import the container disk into persistent storage for a virtual machine]. - -* xref:../../../virt/virtual_machines/virt-create-vms.adoc#virt-create-vms[Create a virtual machine] that uses -a `containerDisk` volume for ephemeral storage. diff --git a/virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc b/virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc deleted file mode 100644 index 12611c9f681c..000000000000 --- a/virt/virtual_machines/virtual_disks/virt-using-preallocation-for-datavolumes.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="virt-using-preallocation-for-datavolumes"] -= Using preallocation for data volumes -include::modules/virt-document-attributes.adoc[] -:context: virt-using-preallocation-for-datavolumes - -toc::[] - -The Containerized Data Importer can preallocate disk space to improve write performance when creating data volumes. - -You can enable preallocation globally for the cluster or for specific data volumes. - -include::modules/virt-about-preallocation.adoc[leveloffset=+1] -include::modules/virt-enabling-preallocation-globally.adoc[leveloffset=+1] -include::modules/virt-enabling-preallocation-for-dv.adoc[leveloffset=+1] - diff --git a/virt/virtual_machines/vm_networking/images b/virt/virtual_machines/vm_networking/images deleted file mode 120000 index 4dd3347de19a..000000000000 --- a/virt/virtual_machines/vm_networking/images +++ /dev/null @@ -1 +0,0 @@ -../../../images \ No newline at end of file diff --git a/virt/virtual_machines/vm_networking/modules b/virt/virtual_machines/vm_networking/modules deleted file mode 120000 index 5be29a99c161..000000000000 --- a/virt/virtual_machines/vm_networking/modules +++ /dev/null @@ -1 +0,0 @@ -../../../modules \ No newline at end of file diff --git a/virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc b/virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc deleted file mode 100644 index edb9fb66af37..000000000000 --- a/virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc +++ /dev/null @@ -1,53 +0,0 @@ -[id="attaching-to-multiple-networks"] -= Attaching a virtual machine to multiple networks -include::modules/virt-document-attributes.adoc[] -:context: virt-attaching-multiple-networks - -toc::[] - -{VirtProductName} provides layer-2 networking capabilities that allow you to connect -virtual machines to multiple networks. You can import virtual machines with -existing workloads that depend on access to multiple interfaces. You can also -configure a PXE network so that you can boot machines over the network. - -To get started, a network administrator configures a bridge network attachment definition -for a namespace in the web console or CLI. Users can then create a NIC to attach pods and virtual machines in that namespace to the bridge network. - -[NOTE] -==== -The _KubeMacPool_ component provides a MAC address pool service for virtual machine NICs in designated namespaces. It is not enabled by default. xref:../../../virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc#virt-about-kubemacpool_virt-using-mac-address-pool-for-vms[Enable a MAC address pool in a namespace] by applying the KubeMacPool label to that namespace. -==== - -include::modules/virt-networking-glossary.adoc[leveloffset=+1] - -== Creating a network attachment definition - -== Prerequisites - -* A Linux bridge must be configured and attached on every node. -See the xref:../../../virt/node_network/virt-updating-node-network-config.adoc#virt-about-nmstate_virt-updating-node-network-config[node networking] section for more information. - -[WARNING] -==== -Configuring ipam in a network attachment definition for virtual machines is not supported. -==== - -include::modules/virt-creating-bridge-nad-web.adoc[leveloffset=+2] - -include::modules/virt-creating-bridge-nad-cli.adoc[leveloffset=+2] - -[NOTE] -==== -When defining the NIC in the next section, ensure that the *NETWORK* value is -the bridge network name from the network attachment definition you created -in the previous section. -==== - -include::modules/virt-vm-create-nic-web.adoc[leveloffset=+1] - -include::modules/virt-networking-wizard-fields-web.adoc[leveloffset=+1] - -[id="{context}_additional-resources"] -== Additional resources - -* xref:../../../virt/virtual_machines/vm_networking/virt-configuring-ip-for-vms.adoc#virt-configuring-ip-for-vms[Configuring IP addresses for virtual machines] diff --git a/virt/virtual_machines/vm_networking/virt-attaching-vm-to-sriov-network.adoc b/virt/virtual_machines/vm_networking/virt-attaching-vm-to-sriov-network.adoc deleted file mode 100644 index 46057b636987..000000000000 --- a/virt/virtual_machines/vm_networking/virt-attaching-vm-to-sriov-network.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[id="virt-attaching-vm-to-sriov-network"] -= Attaching a virtual machine to an SR-IOV network -include::modules/virt-document-attributes.adoc[] -:context: virt-attaching-vm-to-sriov-network - -toc::[] - -You can attach a virtual machine to use a Single Root I/O Virtualization (SR-IOV) network as a secondary network. - -== Prerequisites - -* You must have xref:../../../virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc#virt-configuring-sriov-device-for-vms[configured an SR-IOV device for virtual machines]. - -* You must have xref:../../../virt/virtual_machines/vm_networking/virt-defining-an-sriov-network.adoc#virt-defining-an-sriov-network[defined an SR-IOV network]. - -include::modules/virt-attaching-vm-to-sriov-network.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/vm_networking/virt-configuring-ip-for-vms.adoc b/virt/virtual_machines/vm_networking/virt-configuring-ip-for-vms.adoc deleted file mode 100644 index 30026e7dcb9f..000000000000 --- a/virt/virtual_machines/vm_networking/virt-configuring-ip-for-vms.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[id="virt-configuring-ip-for-vms"] -= Configuring IP addresses for virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-configuring-ip-for-vms - -toc::[] - -You can configure either dynamically or statically provisioned IP addresses for virtual machines. - -.Prerequisites - -* The virtual machine can connect to a xref:../../../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#attaching-to-multiple-networks[secondary network] - -* To configure a dynamic IP for the virtual machine, you must have a DHCP server available on the secondary network. - -include::modules/virt-configuring-ip-for-new-vm-cloud-init.adoc[leveloffset=+1] - diff --git a/virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc b/virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc deleted file mode 100644 index f3b9e4adfb42..000000000000 --- a/virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="virt-configuring-sriov-device-for-vms"] -= Configuring an SR-IOV network device for virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-configuring-sriov-device-for-vms - -toc::[] - -You can configure a Single Root I/O Virtualization (SR-IOV) device for virtual machines in your cluster. -This process is similar but not identical to configuring an SR-IOV device for {product-title}. - -[NOTE] -==== -Live migration is not supported for virtual machines that are attached to an SR-IOV network interface. -==== - -== Prerequisites -* You must have xref:../../../networking/hardware_networks/installing-sriov-operator.adoc#installing-sriov-operator[installed the SR-IOV Operator.] - -* You must have xref:../../../networking/hardware_networks/configuring-sriov-operator.adoc#configuring-sriov-operator[configured the SR-IOV Operator.] - -include::modules/nw-sriov-device-discovery.adoc[leveloffset=+1] -include::modules/nw-sriov-configuring-device.adoc[leveloffset=+1] - -== Next steps - -* xref:../../../virt/virtual_machines/vm_networking/virt-defining-an-sriov-network.adoc#virt-defining-an-sriov-network[Configuring an SR-IOV network attachment for virtual machines] - diff --git a/virt/virtual_machines/vm_networking/virt-defining-an-sriov-network.adoc b/virt/virtual_machines/vm_networking/virt-defining-an-sriov-network.adoc deleted file mode 100644 index b2c0721e0d43..000000000000 --- a/virt/virtual_machines/vm_networking/virt-defining-an-sriov-network.adoc +++ /dev/null @@ -1,21 +0,0 @@ -[id="virt-defining-an-sriov-network"] -= Defining an SR-IOV network -include::modules/virt-document-attributes.adoc[] -:context: virt-defining-an-sriov-network - -toc::[] - -You can create a network attachment for a Single Root I/O Virtualization (SR-IOV) device for virtual machines. - -After the network is defined, you can attach virtual machines to the SR-IOV network. - -== Prerequisites - -* You must have xref:../../../virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc#virt-configuring-sriov-device-for-vms[configured an SR-IOV device for virtual machines]. - -include::modules/nw-sriov-network-attachment.adoc[leveloffset=+1] - -== Next steps - -* xref:../../../virt/virtual_machines/vm_networking/virt-attaching-vm-to-sriov-network.adoc#virt-attaching-vm-to-sriov-network[Attaching a virtual machine to an SR-IOV network.] - diff --git a/virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc b/virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc deleted file mode 100644 index b05c0079c12c..000000000000 --- a/virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="virt-using-mac-address-pool-for-vms"] -= Using a MAC address pool for virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-using-mac-address-pool-for-vms - -toc::[] - -The _KubeMacPool_ component provides a MAC address pool service for virtual machine NICs in designated namespaces. Enable a MAC address pool in a namespace by applying the KubeMacPool label to that namespace. - -include::modules/virt-about-kubemacpool.adoc[leveloffset=+1] - -include::modules/virt-enabling-mac-address-pool-for-namespace-cli.adoc[leveloffset=+1] - -include::modules/virt-disabling-mac-address-pool-for-namespace-cli.adoc[leveloffset=+1] diff --git a/virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc b/virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc deleted file mode 100644 index 3d9d259aea4a..000000000000 --- a/virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc +++ /dev/null @@ -1,39 +0,0 @@ -[id="virt-using-the-default-pod-network-with-virt"] -= Using the default pod network for virtual machines -include::modules/virt-document-attributes.adoc[] -:context: virt-using-the-default-pod-network-with-virt - -toc::[] - -You can use the default pod network with {VirtProductName}. To do so, -you must use the `masquerade` binding method. It is the only recommended -binding method for use with the default pod network. Do not use -`masquerade` mode with non-default networks. - -xref:../../../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#attaching-to-multiple-networks[For secondary networks], use the `bridge` binding method. - -[NOTE] -==== -The _KubeMacPool_ component provides a MAC address pool service for virtual machine NICs in designated namespaces. It is not enabled by default. xref:../../../virt/virtual_machines/vm_networking/virt-using-mac-address-pool-for-vms.adoc#virt-about-kubemacpool_virt-using-mac-address-pool-for-vms[Enable a MAC address pool in a namespace] by applying the KubeMacPool label to that namespace. -==== - -include::modules/virt-configuring-masquerade-mode-cli.adoc[leveloffset=+1] - -[id="virt-selecting-binding-method"] -== Selecting binding method - -If you create a virtual machine from the {VirtProductName} -xref:../../../virt/virtual_machines/virt-create-vms.adoc#virt-create-vms[web console wizard], -select the required binding method from the *Networking* screen. - -include::modules/virt-networking-wizard-fields-web.adoc[leveloffset=+2] - -== Virtual machine configuration examples for the default network - -include::modules/virt-template-vm-config.adoc[leveloffset=+2] - -include::modules/virt-template-windows-vmi.adoc[leveloffset=+2] - -include::modules/virt-creating-a-service-from-a-virtual-machine.adoc[leveloffset=+1] -.Additional resources -* xref:../../../networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc#configuring-externalip[Configuring external IPs] diff --git a/virt/virtual_machines/vm_networking/virt-viewing-ip-of-vm-nic.adoc b/virt/virtual_machines/vm_networking/virt-viewing-ip-of-vm-nic.adoc deleted file mode 100644 index a9f68b85932c..000000000000 --- a/virt/virtual_machines/vm_networking/virt-viewing-ip-of-vm-nic.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[id="virt-viewing-ip-of-vm-nic"] -= Viewing the IP address of NICs on a virtual machine -include::modules/virt-document-attributes.adoc[] -:context: virt-viewing-ip-of-vm-vnic - -toc::[] - -You can view the IP address for a network interface card (NIC) by using the web console or the `oc` client. The xref:../../../virt/virtual_machines/virt-installing-qemu-guest-agent.adoc#virt-installing-qemu-guest-agent[QEMU guest agent] displays additional information about the virtual machine's secondary networks. - -include::modules/virt-viewing-vmi-ip-cli.adoc[leveloffset=+1] -include::modules/virt-viewing-vmi-ip-web.adoc[leveloffset=+1] diff --git a/virt/vm_templates/images b/virt/vm_templates/images deleted file mode 120000 index 5fa6987088da..000000000000 --- a/virt/vm_templates/images +++ /dev/null @@ -1 +0,0 @@ -../../images \ No newline at end of file diff --git a/virt/vm_templates/modules b/virt/vm_templates/modules deleted file mode 120000 index 36719b9de743..000000000000 --- a/virt/vm_templates/modules +++ /dev/null @@ -1 +0,0 @@ -../../modules/ \ No newline at end of file diff --git a/virt/vm_templates/virt-creating-vm-template.adoc b/virt/vm_templates/virt-creating-vm-template.adoc deleted file mode 100644 index de7fdb0e1f50..000000000000 --- a/virt/vm_templates/virt-creating-vm-template.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[id="virt-creating-vm-template"] -= Creating virtual machine templates -include::modules/virt-document-attributes.adoc[] -:context: virt-creating-vm-template - -toc::[] - -include::modules/virt-about-vm-templates.adoc[leveloffset=+1] -include::modules/virt-adding-a-boot-source-web.adoc[leveloffset=+1] -include::modules/virt-template-fields-for-boot-source.adoc[leveloffset=+2] -include::modules/virt-marking-vm-templates-favorites.adoc[leveloffset=+1] -include::modules/virt-filtering-vm-templates.adoc[leveloffset=+1] -include::modules/virt-creating-template-wizard-web.adoc[leveloffset=+1] - -[id="virt-template-wizard-fields"] -== Virtual machine template wizard fields - -The following tables describe the fields for the *General*, *Networking*, -*Storage*, and *Advanced* steps in the *Create Virtual Machine Template* wizard. - -:vmtemplate: -include::modules/virt-vm-wizard-fields-web.adoc[leveloffset=+2] -include::modules/virt-networking-wizard-fields-web.adoc[leveloffset=+2] -include::modules/virt-storage-wizard-fields-web.adoc[leveloffset=+2] -include::modules/virt-cloud-init-fields-web.adoc[leveloffset=+2] -:vmtemplate!: - -== Additional Resources - -* See xref:../../virt/virtual_machines/vm_networking/virt-configuring-sriov-device-for-vms.adoc#virt-configuring-sriov-device-for-vms[Configuring the SR-IOV Network Operator] for further details on the SR-IOV Network Operator. diff --git a/virt/vm_templates/virt-dedicated-resources-vm-template.adoc b/virt/vm_templates/virt-dedicated-resources-vm-template.adoc deleted file mode 100644 index 47bfc47c25a7..000000000000 --- a/virt/vm_templates/virt-dedicated-resources-vm-template.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[id="virt-dedicated-resources-vm-template"] -= Enabling dedicated resources for virtual machine templates -include::modules/virt-document-attributes.adoc[] -:context: virt-dedicated-resources-vm-template - -toc::[] - -Virtual machines can have resources of a node, such as CPU, -dedicated to them to improve performance. - -include::modules/virt-about-dedicated-resources.adoc[leveloffset=+1] - -== Prerequisites - -* The -xref:../../scalability_and_performance/using-cpu-manager.adoc[CPU Manager] must -be configured on the node. Verify that the node has the `cpumanager` = `true` -label before scheduling virtual machine workloads. - -include::modules/virt-enabling-dedicated-resources.adoc[leveloffset=+1] diff --git a/virt/vm_templates/virt-deleting-vm-template.adoc b/virt/vm_templates/virt-deleting-vm-template.adoc deleted file mode 100644 index 550848ffb111..000000000000 --- a/virt/vm_templates/virt-deleting-vm-template.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[id="virt-deleting-vm-template"] -= Deleting a virtual machine template -include::modules/virt-document-attributes.adoc[] -:context: virt-deleting-vm-template - -toc::[] - -Red Hat virtual machine templates cannot be deleted. You can use the web console to delete: - -* Virtual machine templates created from Red Hat templates -* Custom virtual machine templates that were created by using the *Create Virtual Machine Template* wizard. - -include::modules/virt-deleting-template-web.adoc[leveloffset=+1] diff --git a/virt/vm_templates/virt-editing-vm-template.adoc b/virt/vm_templates/virt-editing-vm-template.adoc deleted file mode 100644 index e31efbac8cfe..000000000000 --- a/virt/vm_templates/virt-editing-vm-template.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="virt-editing-vm-template"] -= Editing virtual machine templates -include::modules/virt-document-attributes.adoc[] -:context: virt-editing-vm-template - -toc::[] - -You can update a virtual machine template in the web console, either by editing -the full configuration in the YAML editor or by selecting a custom template in the *Templates* tab and modifying the editable items. - -include::modules/virt-editing-vm-web.adoc[leveloffset=+1] -include::modules/virt-editing-template-yaml-web.adoc[leveloffset=+1] -include::modules/virt-add-disk-to-vm.adoc[leveloffset=+1] -include::modules/virt-add-nic-to-vm.adoc[leveloffset=+1] -include::modules/virt-edit-cdrom-vm.adoc[leveloffset=+1] diff --git a/web_console/configuring-web-console.adoc b/web_console/configuring-web-console.adoc deleted file mode 100644 index 16c62b13ee2f..000000000000 --- a/web_console/configuring-web-console.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="configuring-web-console"] -= Configuring the web console in {product-title} -include::modules/common-attributes.adoc[] -:context: configuring-web-console - -toc::[] - -You can modify the {product-title} web console to set a logout redirect URL -or disable the console. - -== Prerequisites - -* Deploy an {product-title} cluster. - -include::modules/web-console-configuration.adoc[leveloffset=+1] diff --git a/web_console/creating-quick-start-tutorials.adoc b/web_console/creating-quick-start-tutorials.adoc deleted file mode 100644 index 6ff90e628b96..000000000000 --- a/web_console/creating-quick-start-tutorials.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[id="creating-quick-start-tutorials"] -= Creating quick start tutorials in the web console -include::modules/common-attributes.adoc[] -:context: creating-quick-start-tutorials - -toc::[] - -If you are creating quick start tutorials for the {product-title} web console, follow these guidelines to maintain a consistent user experience across all quick starts. - -include::modules/understanding-quick-starts.adoc[leveloffset=+1] - -include::modules/quick-start-user-workflow.adoc[leveloffset=+1] - -include::modules/quick-start-components.adoc[leveloffset=+1] - -include::modules/contributing-quick-starts.adoc[leveloffset=+1] - -include::modules/understanding-quick-start-elements.adoc[leveloffset=+2] - -include::modules/quick-start-adding-custom-icon.adoc[leveloffset=+2] - -include::modules/quick-start-limiting-access.adoc[leveloffset=+2] - -include::modules/quick-starts-linking-to-others.adoc[leveloffset=+2] - -include::modules/quick-starts-supported-tags.adoc[leveloffset=+2] - -include::modules/quick-start-content-guidelines.adoc[leveloffset=+1] - -[id="quick-start-tutorials-additional-resources"] -== Additional resources - -* For voice and tone requirements, refer to link:https://www.patternfly.org/v4/ux-writing/brand-voice-and-tone[PatternFly’s brand voice and tone guidelines]. -* For other UX content guidance, refer to all areas of link:https://www.patternfly.org/v4/ux-writing/about[PatternFly’s UX writing style guide]. diff --git a/web_console/customizing-the-web-console.adoc b/web_console/customizing-the-web-console.adoc deleted file mode 100644 index c8b821b3c6e2..000000000000 --- a/web_console/customizing-the-web-console.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="customizing-web-console"] -= Customizing the web console in {product-title} -include::modules/common-attributes.adoc[] -:context: customizing-web-console - -toc::[] - -You can customize the {product-title} web console to set a custom logo, -product name, links, notifications, and command line downloads. This is -especially helpful if you need to tailor the web console to meet specific -corporate or government requirements. - -include::modules/adding-a-custom-logo.adoc[leveloffset=+1] - -include::modules/creating-custom-links.adoc[leveloffset=+1] - -include::modules/customizing-the-web-console-URL.adoc[leveloffset=+1] - -include::modules/customizing-the-login-page.adoc[leveloffset=+1] - -include::modules/defining-template-for-external-log-link.adoc[leveloffset=+1] - -include::modules/adding-custom-notification-banners.adoc[leveloffset=+1] - -include::modules/customizing-cli-downloads.adoc[leveloffset=+1] - -include::modules/adding-yaml-examples-to-kube-resources.adoc[leveloffset=+1] diff --git a/web_console/disabling-web-console.adoc b/web_console/disabling-web-console.adoc deleted file mode 100644 index 76a405cb3966..000000000000 --- a/web_console/disabling-web-console.adoc +++ /dev/null @@ -1,14 +0,0 @@ -[id="disabling-web-console"] -= Disabling the web console in {product-title} -include::modules/common-attributes.adoc[] -:context: disabling-web-console - -toc::[] - -You can disable the {product-title} web console. - -== Prerequisites - -* Deploy an {product-title} cluster. - -include::modules/web-console-disable.adoc[leveloffset=+1] diff --git a/web_console/images b/web_console/images deleted file mode 120000 index e4c5bd02a10a..000000000000 --- a/web_console/images +++ /dev/null @@ -1 +0,0 @@ -../images/ \ No newline at end of file diff --git a/web_console/modules b/web_console/modules deleted file mode 120000 index 43aab75b53c9..000000000000 --- a/web_console/modules +++ /dev/null @@ -1 +0,0 @@ -../modules/ \ No newline at end of file diff --git a/web_console/odc-about-developer-perspective.adoc b/web_console/odc-about-developer-perspective.adoc deleted file mode 100644 index d4876bbb350b..000000000000 --- a/web_console/odc-about-developer-perspective.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[id="odc-about-developer-perspective"] -= About the Developer perspective in the web console -include::modules/common-attributes.adoc[] -:context: odc-about-developer-perspective - -toc::[] - -The {product-title} web console provides two perspectives; the *Administrator* perspective and the *Developer* perspective. -[NOTE] -==== -The default web console perspective that is shown depends on the role of the user. The *Developer* perspective is displayed by default if the user is recognised as a developer. -==== - -The *Developer* perspective provides workflows specific to developer use cases, such as the ability to: - -* Create and deploy applications on {product-title} by importing existing codebases, images, and dockerfiles. -* Visually interact with applications, components, and services associated with them within a project and monitor their deployment and build status. -* Group components within an application and connect the components within and across applications. -* Integrate serverless capabilities (Technology Preview). -* Create workspaces to edit your application code using Eclipse Che. - -== Prerequisites - -To access the *Developer* perspective, ensure that you have logged in to the web console. - -include::modules/odc-accessing-developer-perspective.adoc[leveloffset=+1] - -.Additional resources - -* xref:../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating and deploying applications on {product-title} using the *Developer* perspective] -* xref:../applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc#odc-viewing-application-composition-using-topology-view[Viewing the applications in your project, verifying their deployment status, and interacting with them in the *Topology* view] diff --git a/web_console/odc-about-web-terminal.adoc b/web_console/odc-about-web-terminal.adoc deleted file mode 100644 index e0892ee5993e..000000000000 --- a/web_console/odc-about-web-terminal.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[id="odc-about-web-terminal"] -= About the web terminal in the web console -include::modules/common-attributes.adoc[] -:context: odc-about-web-terminal - -toc::[] - -You can launch an embedded command line terminal instance in the OpenShift web console. You must first install the Web Terminal Operator to use the web terminal. - -[NOTE] -==== -Cluster administrators can access the web terminal in {product-title} 4.7 and later. -==== - -This terminal instance is preinstalled with common CLI tools for interacting with the cluster, such as `oc`, `kubectl`,`odo`, `kn`, `tkn`, `helm`, `kubens`, and `kubectx`. It also has the context of the project you are working on and automatically logs you in using your credentials. - -:FeatureName: Web terminal -include::modules/technology-preview.adoc[leveloffset=+1] - -include::modules/odc-installing-web-terminal.adoc[leveloffset=+1] - -include::modules/odc-using-web-terminal.adoc[leveloffset=+1] - -include::modules/odc-uninstalling-web-terminal.adoc[leveloffset=+1] diff --git a/web_console/using-dashboard-to-get-cluster-information.adoc b/web_console/using-dashboard-to-get-cluster-information.adoc deleted file mode 100644 index 3360cc684d4a..000000000000 --- a/web_console/using-dashboard-to-get-cluster-information.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[id="using-dashboard-to-get-cluster-info"] -= Using the {product-title} dashboard to get cluster information -include::modules/common-attributes.adoc[] -:context: using-dashboard-to-get-cluster-info - -toc::[] - -Access the {product-title} dashboard, which captures high-level information -about the cluster, by navigating to *Home* -> *Dashboards* -> *Overview* from -the {product-title} web console. - -The {product-title} dashboard provides various cluster information, captured in -individual dashboard cards. - -include::modules/virt-about-the-overview-dashboard.adoc[leveloffset=+1] diff --git a/web_console/web-console.adoc b/web_console/web-console.adoc deleted file mode 100644 index ad81f98b4fe6..000000000000 --- a/web_console/web-console.adoc +++ /dev/null @@ -1,22 +0,0 @@ - -[id="web-console"] -= Accessing the web console -include::modules/common-attributes.adoc[] -:context: web-console - -toc::[] - -The {product-title} web console is a user interface accessible from a web browser. -Developers can use the web console to visualize, browse, and manage the contents -of projects. - -== Prerequisites - -* JavaScript must be enabled to use the web console. For the best experience, use -a web browser that supports -link:http://caniuse.com/#feat=websockets[WebSockets]. -* Review the link:https://access.redhat.com/articles/4128421[OpenShift Container -Platform 4.x Tested Integrations] page before you create the supporting -infrastructure for your cluster. - -include::modules/web-console-overview.adoc[leveloffset=+1] diff --git a/welcome/index.adoc b/welcome/index.adoc index 92784797e296..b4139a0b45a9 100644 --- a/welcome/index.adoc +++ b/welcome/index.adoc @@ -1,291 +1,41 @@ +:_mod-docs-content-type: ASSEMBLY :context: welcome-index [id="welcome-index"] -= {product-title} {product-version} Documentation += Red Hat Advanced Cluster Security for Kubernetes {product-version} Documentation include::modules/common-attributes.adoc[] [.lead] -Welcome to the official {product-title} {product-version} documentation, where you can find information to help you learn about {product-title} and start exploring its features. +Welcome to the official {product-title} documentation, where you can learn about {product-title} and start exploring its features. -To navigate the {product-title} {product-version} documentation, you can either +To go to the {product-title} documentation, you can use one of the following methods: -* Use the left navigation bar to browse the documentation or -* Select the activity that interests you from the contents of this Welcome page +* Use the left navigation bar to browse the documentation. +* Select the task that interests you from the contents of this Welcome page. -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -You can start with xref:../architecture/architecture.adoc#architecture-overview-architecture[Architecture] and -xref:../security/container_security/security-understanding.adoc#understanding-security[Security and compliance]. -ifdef::openshift-enterprise,openshift-webscale[] -Then, see -xref:../release_notes/ocp-4-8-release-notes.adoc#ocp-4-8-release-notes[Release notes]. -endif::[] -endif::[] +== Installation activities -ifdef::openshift-dedicated,openshift-online,openshift-aro[] -You can start with **xref:../architecture/architecture.adoc#architecture-overview-architecture[Architecture]**. -endif::[] +- *xref:../installing/acs-high-level-overview.adoc#install-platforms-methods_acs-high-level-overview[Understanding installation methods for different platforms]*: Determine the best installation method for your product and platform. -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -== Cluster installer activities -As someone setting out to install an {product-title} {product-version} cluster, this documentation helps you: -- **xref:../installing/index.adoc#ocp-installation-overview[{product-title} installation overview]**: You can install {product-title} on installer-provisioned or user-provisioned infrastructure. The {product-title} installation program provides the flexibility to deploy {product-title} on a range of different platforms. +== Operating {product-title} +Explore various activities you can perform by using {product-title}: -- **xref:../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Install a cluster on AWS]**: You have the most installation options when you deploy a cluster on Amazon Web Services (AWS). You can deploy clusters with xref:../installing/installing_aws/installing-aws-default.adoc#installing-aws-default[default settings] or xref:../installing/installing_aws/installing-aws-customizations.adoc#installing-aws-customizations[custom AWS settings]. -You can also deploy a cluster on AWS infrastructure that you provisioned yourself. You can modify the provided xref:../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[AWS CloudFormation templates] to meet your needs. +- *xref:../operating/view-dashboard.adoc#view-dashboard[Viewing the dashboard]*: Find information about the {product-title} real-time interactive dashboard. Learn how to use it to view key metrics from all your hosts, containers, and services. +- *xref:../operating/manage-compliance/compliance-feature-overview.adoc#compliance-feature-overview[Compliance feature overview]*: Understand how to run automated checks and validate compliance based on industry standards, including CIS, NIST, PCI, and HIPAA. +- *xref:../operating/manage-vulnerabilities/vulnerability-management.adoc#manage-vulnerabilities[Managing vulnerabilities]*: Learn how to identify and prioritize vulnerabilities for remediation. +- *xref:../operating/respond-to-violations.adoc#respond-to-violations[Responding to violations]*: Learn how to view policy violations, drill down to the actual cause of the violation, and take corrective actions. -- **Install a cluster on Azure**: You can deploy clusters with xref:../installing/installing_azure/installing-azure-default.adoc#installing-azure-default[default settings], xref:../installing/installing_azure/installing-azure-customizations.adoc#installing-azure-customizations[custom Azure settings], or xref:../installing/installing_azure/installing-azure-network-customizations.adoc#installing-azure-network-customizations[custom networking settings] in Microsoft Azure. You can also provision {product-title} into an xref:../installing/installing_azure/installing-azure-vnet.adoc#installing-azure-vnet[Azure Virtual Network] or use xref:../installing/installing_azure/installing-azure-user-infra.adoc#installing-azure-user-infra[Azure Resource Manager Templates] to provision your own infrastructure. +== Configuring {product-title} +Explore the following typical configuration tasks in {product-title}: -- **Install a cluster on GCP**: You can deploy clusters with xref:../installing/installing_gcp/installing-gcp-default.adoc#installing-gcp-default[default settings] or xref:../installing/installing_gcp/installing-gcp-customizations.adoc#installing-gcp-customizations[custom GCP settings] on Google Cloud Platform (GCP). You can also perform a GCP installation where you provision your own infrastructure. +- *xref:../configuration/add-custom-certificates.adoc#add-custom-certificates[Adding custom certificates]*: Learn how to use a custom TLS certificate with {product-title}. After you set up a certificate, users and API clients do not have to bypass the certificate security warnings. +- *xref:../backup_and_restore/backing-up-acs.adoc#configure-authentication[Backing up {product-title}]*: Learn how to perform manual and automated data backups for {product-title} and use these backups for data restoration in the case of an infrastructure disaster or corrupt data. +- *xref:../configuration/configure-automatic-upgrades.adoc#configure-automatic-upgrades[Configuring automatic upgrades for secured clusters]*: Stay up to date by automating the upgrade process for each secured cluster. -- **xref:../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Install a cluster on VMware vSphere]**: You can install {product-title} on supported versions of vSphere. +== Integrating with other products +Learn how to integrate {product-title} with the following products: -- **xref:../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install a cluster on bare metal]**: If none of the available platform and cloud providers meet your needs, you can install {product-title} on bare metal. - -- **xref:../installing/installing_bare_metal_ipi/ipi-install-overview.adoc#ipi-install-overview[Install an installer-provisioned cluster on bare metal]**: You can install {product-title} on bare metal with an installer-provisioned architecture. - -- **xref:../installing/installing_bare_metal/installing-bare-metal.adoc#creating-machines-bare-metal[Create {op-system-first} machines on bare metal]**: You can install {op-system} machines using ISO or PXE in a fully live environment and configure them with kernel arguments, Ignition configs, or the `coreos-installer` command. - -- **Install a cluster on {rh-openstack-first}**: You can install a cluster on -xref:../installing/installing_openstack/installing-openstack-installer-custom.adoc#installing-openstack-installer-custom[{rh-openstack} with customizations]. - -//// -You can configure an external load balancer for -xref:../installing/installing_openstack/installing-openstack-load-balancing.adoc#installing-openstack-load-balancing[load balancing deployments on OpenStack]. -To troubleshoot OpenStack installation issues, you can -xref:../installing/installing_openstack/installing-openstack-troubleshooting.adoc#installing-openstack-troubleshooting[view instance logs and ssh to an instance]. -//// - -- **Install a cluster on {rh-virtualization-first}**: You can deploy clusters on {rh-virtualization-first} with a -xref:../installing/installing_rhv/installing-rhv-default.adoc#installing-rhv-default[quick install] or an -xref:../installing/installing_rhv/installing-rhv-customizations.adoc#installing-rhv-customizations[install with customizations]. - -- **Install a cluster in a restricted network**: If your cluster that uses -user-provisioned infrastructure on -xref:../installing/installing_aws/installing-restricted-networks-aws.adoc#installing-restricted-networks-aws[AWS], -GCP, -xref:../installing/installing_vsphere/installing-restricted-networks-vsphere.adoc#installing-restricted-networks-vsphere[vSphere], -or -xref:../installing/installing_bare_metal/installing-restricted-networks-bare-metal.adoc#installing-restricted-networks-bare-metal[bare metal] -does not have full access to the internet, you can -xref:../installing/install_config/installing-restricted-networks-preparations.adoc#installing-restricted-networks-preparations[mirror the {product-title} installation images] -and install a cluster in a restricted network. - -- **Install a cluster in an existing network**: If you use an existing Virtual Private Cloud (VPC) in -xref:../installing/installing_aws/installing-aws-vpc.adoc#installing-aws-vpc[AWS] or -xref:../installing/installing_gcp/installing-gcp-vpc.adoc#installing-gcp-vpc[GCP] or an existing -xref:../installing/installing_azure/installing-azure-vnet.adoc#installing-azure-vnet[VNet] -on Azure, you can install a cluster. - -- **Install a private cluster**: If your cluster does not require external -internet access, you can install a private cluster on -xref:../installing/installing_aws/installing-aws-private.adoc#installing-aws-private[AWS], -xref:../installing/installing_azure/installing-azure-private.adoc#installing-aws-private[Azure], or -xref:../installing/installing_gcp/installing-gcp-private.adoc#installing-gcp-private[GCP]. -Internet access is still required to access the cloud APIs and installation media. - -- **xref:../installing/installing-troubleshooting.adoc#installing-troubleshooting[Check installation logs]**: Access installation logs to evaluate issues that occur during {product-title} {product-version} installation. - -- **xref:../web_console/web-console.adoc#web-console[Access {product-title}]**: Use credentials output at the end of the installation process to log in to the {product-title} cluster from the command line or web console. - -- **xref:../storage/persistent_storage/persistent-storage-ocs.adoc#red-hat-openshift-container-storage[Install Red Hat OpenShift Container Storage]**: You can install Red Hat OpenShift Container Storage as an Operator to provide highly integrated and simplified persistent storage management for containers. -endif::[] - -== Developer activities -Ultimately, {product-title} is a platform for developing and deploying containerized applications. As an application developer, {product-title} documentation helps you: - -- **xref:../architecture/understanding-development.adoc#understanding-development[Understand {product-title} development]**: Learn the different types of -containerized applications, from simple containers to advanced Kubernetes deployments and Operators. - -- **xref:../applications/projects/working-with-projects.adoc#working-with-projects[Work with projects]**: Create projects from the web console or CLI to organize and share the software you develop. - -- **xref:../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Work with applications]**: -Use the xref:../web_console/odc-about-developer-perspective.adoc#odc-about-developer-perspective[Developer perspective] in the {product-title} web console to easily -xref:../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[create and deploy applications]. -Use the -xref:../applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc#odc-viewing-application-composition-using-topology-view[Topology view] -to visually interact with your applications, monitor -status, connect and group components, -and modify your code base. - -- ** xref:../cli_reference/developer_cli_odo/understanding-odo.adoc#understanding-odo[Use the developer CLI tool (odo)]**: -The odo CLI tool lets developers create single or multi-component applications -easily and automates deployment, build, and service route configurations. -It abstracts complex Kubernetes and {product-title} concepts, allowing developers to focus on developing their applications. - -- **xref:../cicd/pipelines/understanding-openshift-pipelines.adoc#op-key-features[Create CI/CD Pipelines]**: Pipelines are serverless, cloud-native, continuous integration and continuous deployment systems that run in isolated containers. -They use standard Tekton custom resources to automate deployments and are designed for decentralized teams that work on microservices-based architecture. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -- **Deploy Helm charts**: -xref:../cli_reference/helm_cli/getting-started-with-helm-on-openshift-container-platform.adoc#getting-started-with-helm-on-openshift[Helm 3] -is a package manager that helps developers define, install, and update -application packages on Kubernetes. A Helm chart is a packaging format that -describes an application that can be deployed using the Helm CLI. -endif::[] - -- **xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Understand Operators]**: Operators are the preferred method for creating on-cluster applications for {product-title} {product-version}. Learn about the Operator Framework and how to deploy applications using installed Operators into your projects. - -- **xref:../cicd/builds/understanding-image-builds.adoc#understanding-image-builds[Understand image builds]**: Choose from different build strategies (Docker, S2I, custom, and pipeline) that can include different kinds of source materials (from places like Git repositories, local binary inputs, and external artifacts). Then, follow examples of build types from basic builds to advanced builds. - -- **xref:../openshift_images/images-understand.adoc#understanding-images[Create container images]**: A container image is the most basic building block in {product-title} (and Kubernetes) applications. Defining image streams lets you gather multiple versions of an image in one place as you continue its development. S2I containers let you insert your source code into a base container that is set up to run code of a particular type (such as Ruby, Node.js, or Python). - -- **xref:../applications/deployments/what-deployments-are.adoc#what-deployments-are[Create deployments]**: Use `Deployment` and `DeploymentConfig` objects to exert fine-grained management over applications. -Use the Workloads page or `oc` CLI to xref:../applications/deployments/managing-deployment-processes.adoc#deployment-operations[manage deployments]. Learn xref:../applications/deployments/deployment-strategies.adoc#deployment-strategies[rolling, recreate, and custom] deployment strategies. - -- **xref:../openshift_images/using-templates.adoc#using-templates[Create templates]**: Use existing templates or create your own templates that describe how an application is built or deployed. A template can combine images with descriptions, parameters, replicas, exposed ports and other content that defines how an application can be run or built. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -- **xref:../operators/operator_sdk/osdk-about.adoc#osdk-about[Develop Operators]**: Operators are the preferred method for creating on-cluster applications for {product-title} {product-version}. Learn the workflow for building, testing, and deploying Operators. Then create your own Operators based on xref:../operators/operator_sdk/ansible/osdk-ansible-support.adoc#osdk-ansible-support[Ansible] or -xref:../operators/operator_sdk/helm/osdk-helm-support.adoc#osdk-helm-support[Helm], or configure xref:../operators/operator_sdk/osdk-monitoring-prometheus.adoc#osdk-monitoring-prometheus[built-in Prometheus monitoring] using the Operator SDK. - -- **xref:../rest_api/index.adoc#api-index[REST API reference]**: Lists {product-title} application programming interface endpoints. -endif::[] - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -== Cluster administrator activities - -Ongoing tasks on your {product-title} {product-version} cluster -include various activities for managing machines, providing -services to users, and following monitoring and logging features -that watch over the cluster. As a cluster administrator, this -documentation helps you: - -- **xref:../architecture/architecture.adoc#architecture-overview-architecture[Understand {product-title} management]**: Learn about components -of the {product-title} {product-version} control plane. See how {product-title} masters and workers are managed and updated through the xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#machine-api-overview_creating-machineset-aws[Machine API] and xref:../architecture/control-plane.adoc#operators-overview_control-plane[Operators]. - -=== Manage cluster components - -- **Manage machines**: Manage machines in your cluster on -xref:../machine_management/creating_machinesets/creating-machineset-aws.adoc#creating-machineset-aws[AWS], -xref:../machine_management/creating_machinesets/creating-machineset-azure.adoc#creating-machineset-azure[Azure], -or -xref:../machine_management/creating_machinesets/creating-machineset-gcp.adoc#creating-machineset-gcp[GCP] -by xref:../machine_management/deploying-machine-health-checks.adoc#deploying-machine-health-checks[deploying health checks] and xref:../machine_management/applying-autoscaling.adoc#applying-autoscaling[applying autoscaling to machines]. - -- **xref:../registry/registry-options.adoc#registry-options[Manage container registries]**: Each {product-title} cluster includes a built-in container registry for storing its images. You can also configure a separate link:https://access.redhat.com/documentation/en-us/red_hat_quay/[Red Hat Quay] registry to use with {product-title}. The link:https://quay.io[Quay.io] web site provides a public container registry that stores {product-title} containers and Operators. - -- **xref:../authentication/understanding-authentication.adoc#understanding-authentication[Manage users and groups]**: Add users and groups that have different levels of permissions to use or modify clusters. - -- **xref:../authentication/understanding-authentication.adoc#understanding-authentication[Manage authentication]**: Learn how user, group, and API authentication -works in {product-title}. {product-title} supports multiple -identity providers, including -xref:../authentication/identity_providers/configuring-htpasswd-identity-provider.adoc#configuring-htpasswd-identity-provider[HTPasswd], -xref:../authentication/identity_providers/configuring-keystone-identity-provider.adoc#configuring-keystone-identity-provider[Keystone], -xref:../authentication/identity_providers/configuring-ldap-identity-provider.adoc#configuring-ldap-identity-provider[LDAP], -xref:../authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc#configuring-basic-authentication-identity-provider[basic authentication], -xref:../authentication/identity_providers/configuring-request-header-identity-provider.adoc#configuring-request-header-identity-provider[request header], -xref:../authentication/identity_providers/configuring-github-identity-provider.adoc#configuring-github-identity-provider[GitHub], -xref:../authentication/identity_providers/configuring-gitlab-identity-provider.adoc#configuring-gitlab-identity-provider[GitLab], -xref:../authentication/identity_providers/configuring-google-identity-provider.adoc#configuring-google-identity-provider[Google], -and -xref:../authentication/identity_providers/configuring-oidc-identity-provider.adoc#configuring-oidc-identity-provider[OpenID]. - -- **Manage xref:../security/certificates/replacing-default-ingress-certificate.adoc#replacing-default-ingress[ingress], xref:../security/certificates/api-server.adoc#api-server-certificates[API server], and xref:../security/certificates/service-serving-certificate.adoc#add-service-serving[service] certificates**: {product-title} creates certificates -by default for the Ingress Operator, the API server, and for -services needed by complex middleware applications that require -encryption. At some point, you might need to change, add, or -rotate these certificates. - -- **xref:../networking/understanding-networking.adoc#understanding-networking[Manage networking]**: Networking in {product-title} is managed by -the xref:../networking/cluster-network-operator.adoc#cluster-network-operator[Cluster Network Operator] (CNO). -The CNO uses iptables rules in xref:../networking/openshift_sdn/configuring-kube-proxy.adoc#configuring-kube-proxy[kube-proxy] to -direct traffic between nodes and pods running on those nodes. -The Multus Container Network Interface -adds the capability to attach xref:../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[multiple network interfaces] to a pod. Using -xref:../networking/network_policy/about-network-policy.adoc#about-network-policy[network policy] features, you can isolate your pods or permit selected traffic. - -- **xref:../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Manage storage]**: {product-title} allows cluster administrators to -configure persistent storage using -xref:../storage/persistent_storage/persistent-storage-ocs.adoc#red-hat-openshift-container-storage[Red Hat OpenShift Container Storage], -xref:../storage/persistent_storage/persistent-storage-aws.adoc#persistent-storage-using-aws-ebs[AWS Elastic Block Store], -xref:../storage/persistent_storage/persistent-storage-nfs.adoc#persistent-storage-using-nfs[NFS], -xref:../storage/persistent_storage/persistent-storage-iscsi.adoc#persistent-storage-using-iscsi[iSCSI], -xref:../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-using-csi[Container Storage Interface (CSI)], -and more. -As needed, you can -xref:../storage/expanding-persistent-volumes.adoc#expanding-persistent-volumes[expand persistent volumes], -configure xref:../storage/dynamic-provisioning.adoc#dynamic-provisioning[dynamic provisioning], and use CSI to -xref:../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-using-csi[configure], -xref:../storage/container_storage_interface/persistent-storage-csi-cloning.adoc#persistent-storage-csi-cloning[clone], and use xref:../storage/container_storage_interface/persistent-storage-csi-snapshots.adoc#persistent-storage-csi-snapshots[snapshots] of -persistent storage. - -- **xref:../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Manage Operators]**: Lists of Red Hat, ISV, and community Operators can -be reviewed by cluster administrators and xref:../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[installed on their clusters]. Once installed, you can xref:../operators/user/olm-creating-apps-from-installed-operators.adoc#olm-creating-apps-from-installed-operators[run], xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[upgrade], back up or otherwise manage the Operator on your cluster. - -=== Change cluster components - -- **xref:../operators/understanding/crds/crd-extending-api-with-crds.adoc#crd-extending-api-with-crds[Use custom resource definitions (CRDs) to modify the cluster]**: Cluster features that are implemented with Operators, can be modified with CRDs. Learn to xref:../operators/understanding/crds/crd-extending-api-with-crds.adoc#crd-creating-custom-resources-definition_crd-extending-api-with-crds[create a CRD] and xref:../operators/understanding/crds/crd-managing-resources-from-crds.adoc#crd-managing-resources-from-crds[manage resources from CRDs]. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] -- **xref:../applications/quotas/quotas-setting-per-project.adoc#quotas-setting-per-project[Set resource quotas]**: Choose from CPU, memory and other system resources to xref:../applications/quotas/quotas-setting-per-project.adoc#quotas-setting-per-project[set quotas]. -endif::[] - -- **xref:../applications/pruning-objects.adoc#pruning-objects[Prune and reclaim resources]**: You can reclaim space by pruning unneeded Operators, groups, deployments, builds, images, registries, and cron jobs. - -- **xref:../scalability_and_performance/scaling-cluster-monitoring-operator.adoc#scaling-cluster-monitoring-operator[Scale] and xref:../scalability_and_performance/using-node-tuning-operator.adoc#using-node-tuning-operator[tune] clusters**: Set cluster limits, tune nodes, scale cluster monitoring, and optimize networking, storage, and routes for your environment. - -- **Update a cluster**: -To upgrade your {product-title} to a later version, use the Cluster Version Operator (CVO). -If an update is available from the Container Platform update service, you apply that cluster update from either the xref:../updating/updating-cluster.adoc#updating-cluster[web console] or the xref:../updating/updating-cluster-cli.adoc#updating-cluster-cli[CLI]. - -//// -There is a separate process for -xref:../updating/updating-disconnected-cluster.adoc#updating-disconnected-cluster[updating a cluster on a restricted network]. -//// - -=== Monitor the cluster - -- **xref:../logging/cluster-logging.adoc#cluster-logging[Work with OpenShift Logging]**: Learn about OpenShift Logging and configure different OpenShift Logging types, such as Elasticsearch, Fluentd, Kibana, and Curator. - -- **xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Monitor clusters]**: -Learn to xref:../monitoring/configuring-the-monitoring-stack.adoc#configuring-the-monitoring-stack[configure the monitoring stack]. -Once your monitoring is configured, use the Web UI to access xref:../monitoring/reviewing-monitoring-dashboards.adoc#reviewing-monitoring-dashboards[monitoring dashboards]. -In addition to infrastructure metrics, you can also scrape and view metrics for your own services. - -- **xref:../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring_about-remote-health-monitoring[Remote health monitoring]**: {product-title} collects anonymized aggregated information about your cluster and reports it to Red Hat via Telemetry and the Insights Operator. This information allows Red Hat to improve {product-title} and to react to issues that impact customers more quickly. You can view the xref:../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#showing-data-collected-by-remote-health-monitoring_showing-data-collected-by-remote-health-monitoring[data collected by remote health monitoring]. -endif::[] - -ifdef::openshift-dedicated[] -== Cluster administrator activities - -While cluster maintenance and host configuration is performed by the {product-title} -Operations Team, other ongoing tasks on your {product-title} {product-version} -cluster can be performed by {product-title} cluster administrators. As a -{product-title} cluster administrator, this documentation helps you: - -- **xref:../administering_a_cluster/dedicated-admin-role.adoc#dedicated-administrator-role[Understand the `dedicated-admin` role]**: Learn about the elevated privileges provided to {product-title} cluster administrators. - -//// -- **xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Manage Operators]**: Lists of Red Hat, ISV, and community Operators can -be reviewed by cluster administrators and xref:../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[installed on their clusters]. Once installed, you can xref:../operators/user/olm-creating-apps-from-installed-operators.adoc#olm-creating-apps-from-installed-operators[run], upgrade, back up or otherwise manage the Operator on your cluster (based on what the Operator is designed to do). -//// - -- **xref:../administering_a_cluster/dedicated-admin-role.adoc#dedicated-managing-administrators_dedicated-administrator[Manage RBAC authorizations]**: Grant permissions to users or groups and manage service accounts. - -ifdef::openshift-enterprise,openshift-webscale,openshift-origin[] - -- **xref:../applications/quotas/quotas-setting-per-project.adoc#quotas-setting-per-project[Set resource quotas]**: Choose from CPU, memory and other system resources to set quotas. - -endif::[] - -//// -- **xref:../operators/understanding/crds/crd-managing-resources-from-crds.adoc#crd-managing-resources-from-crds[Manage resources from Custom Resource Definition (CRDs)]**: Learn about how {product-title} cluster administrators and project administrators can use CRDs to manage custom resources in non-default namespaces. -//// - - -//// -- **xref:../applications/pruning-objects.adoc#pruning-objects[Prune and reclaim resources]**: You can reclaim spaceby pruning unneeded Operators, groups, deployments, builds, images, registries, and cron jobs. - -- **xref:../logging/cluster-logging.adoc#cluster-logging[Work with OpenShift Logging]**: -Learn about how to deploy and use a cluster to aggregate logs for a range of {product-title} -services. OpenShift Logging collects, stores, and visualizes logging data from hosts and -applications, whether coming from multiple containers or even deleted pods. - -- **xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Monitor clusters]**: Learn to -xref:../monitoring/configuring-the-monitoring-stack.adoc#configuring-the-monitoring-stack[configure the monitoring stack]. -Once your monitoring is configured, use the web UI to xref:../monitoring/reviewing-monitoring-dashboards.adoc#reviewing-monitoring-dashboards[monitoring dashboards]. -In addition to infrastructure metrics, you can also scrape and view metrics for your own services. - -- **xref:../support/remote_health_monitoring/about-remote-health-monitoring.adoc#about-remote-health-monitoring_about-remote-health-monitoring[Remote health monitoring]**: {product-title} collects anonymized aggregated information about your cluster and reports it to Red Hat via Telemetry and the Insights Operator. This information allows Red Hat to improve {product-title} and to react to issues that impact customers more quickly. You can view the xref:../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#showing-data-collected-by-remote-health-monitoring_showing-data-collected-by-remote-health-monitoring[data collected by remote health monitoring]. -//// -endif::[] +- *xref:../integration/integrate-with-pagerduty.adoc#integrate-with-pagerduty[Integrating with PagerDuty]*: Learn how to integrate with PagerDuty and forward alerts from {product-title} to PagerDuty. +- *xref:../integration/integrate-with-slack.adoc#integrate-with-slack[Integrating with Slack]*: Learn how to integrate with Slack and forward alerts from {product-title} to Slack. +- *xref:../integration/integrate-with-sumologic.adoc#integrate-with-sumologic[Integrating with Sumo Logic]*: Learn how to integrate with Sumo Logic and forward alerts from {product-title} to Sumo Logic. +- *xref:../integration/integrate-using-syslog-protocol.adoc#integrate-with-syslog[Integrating by using the syslog protocol]*: Learn how to integrate with a security information and event management (SIEM) system or a syslog collector for data retention and security investigations. \ No newline at end of file diff --git a/welcome/learn_more_about_openshift.adoc b/welcome/learn_more_about_openshift.adoc deleted file mode 100644 index 8b2017d18c48..000000000000 --- a/welcome/learn_more_about_openshift.adoc +++ /dev/null @@ -1,130 +0,0 @@ -[id="learn_more_about_openshift"] -= Learn more about {product-title} -include::modules/common-attributes.adoc[] -:context: welcome-personas - -toc::[] - -Use the following sections to find content to help you learn about and use {product-title}. - -[id="architect"] -== Architect - -[options="header",cols="3*"] -|=== -| Learn about {product-title} |Plan an {product-title} deployment |Additional resources - -| link:https://www.openshift.com/blog/enterprise-kubernetes-with-openshift-part-one?extIdCarryOver=true&sc_cid=701f2000001Css5AAC[Enterprise Kubernetes with OpenShift] -| link:https://access.redhat.com/articles/4128421[Tested platforms] -| link:https://www.openshift.com/blog?hsLang=en-us[Openshift blog] - -| xref:../architecture/architecture.adoc#architecture[Architecture] -| xref:../security/container_security/security-understanding.adoc#understanding-security[Security and compliance] -| link:https://www.openshift.com/learn/whats-new[What's new in {product-title}] - -| -| xref:../networking/understanding-networking.adoc#understanding-networking[Networking] -| link:https://access.redhat.com/support/policy/updates/openshift#ocp4_phases[{product-title} life cycle] - -| -| xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[Backup and restore] -| - -| -| xref:../scalability_and_performance/recommended-install-practices.adoc#recommended-cluster-install-practices[Performance and scalability] -|=== - - -[id="cluster-administrator"] -== Cluster Administrator - -[options="header",cols="4*"] -|=== -|Learn about {product-title} |Deploy {product-title} |Manage {product-title} |Additional resources - -| link:https://www.openshift.com/blog/enterprise-kubernetes-with-openshift-part-one?extIdCarryOver=true&sc_cid=701f2000001Css5AAC[Enterprise Kubernetes with OpenShift] -| xref:../installing/installing-preparing.adoc#installing-preparing[Installing {product-title}] -| xref:../support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc#using-insights-to-identify-issues-with-your-cluster[Using Insights to identify issues with your cluster] -| xref:../support/getting-support.adoc#getting-support[Getting Support] - -| xref:../architecture/architecture.adoc#architecture[Architecture] -| xref:../post_installation_configuration/machine-configuration-tasks.adoc#post-install-machine-configuration-tasks[Post installation configuration] -| xref:../logging/cluster-logging.adoc#cluster-logging[Logging] -| link:https://access.redhat.com/articles/4217411[OpenShift Knowledgebase articles] - -| link:https://learn.openshift.com/?extIdCarryOver=true&sc_cid=701f2000001Css5AAC[OpenShift Interactive Learning Portal] -| xref:../networking/understanding-networking.adoc#understanding-networking[Networking] -| xref:../monitoring/understanding-the-monitoring-stack.#understanding-the-monitoring-stack[Monitoring] -| link:https://access.redhat.com/support/policy/updates/openshift#ocp4_phases[{product-title} Life Cycle] - -| -| xref:../storage/understanding-ephemeral-storage.adoc#understanding-ephemeral-storage[Storage] -| -| - -| -| xref:../backup_and_restore/backing-up-etcd.adoc#backup-etcd[Backup and restore] -| -| - -| -| xref:../updating/updating-cluster-between-minor.adoc#updating-cluster-between-minor[Updating a cluster] -| -| - -|=== - -[id="application_site_reliability_engineer"] -== Application Site Reliability Engineer (App SRE) - -[options="header",cols="3*"] -|=== -|Learn about {product-title} |Deploy and manage applications |Additional resources - -| link:https://learn.openshift.com/?extIdCarryOver=true&sc_cid=701f2000001Css5AAC[OpenShift Interactive Learning Portal] -| xref:../applications/projects/working-with-projects.adoc#working-with-projects[Projects] -| xref:../support/getting-support.adoc#getting-support[Getting Support] - -| xref:../architecture/architecture.adoc#architecture[Architecture] -| xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Operators] -| link:https://access.redhat.com/articles/4217411[OpenShift Knowledgebase articles] - -| -| xref:../logging/cluster-logging.adoc#cluster-logging[Logging] -| link:https://access.redhat.com/support/policy/updates/openshift#ocp4_phases[{product-title} Life Cycle] - -| -| link:https://www.openshift.com/blog/tag/logging[Blogs about logging] -| - -| -| xref:../monitoring/understanding-the-monitoring-stack.adoc#understanding-the-monitoring-stack[Monitoring] -| - -| -|=== - -[id="Developer"] -== Developer - -[options="header",cols="2*"] -|=== -|Learn about application development in {product-title} |Deploy applications - -| link:https://developers.redhat.com/products/openshift/getting-started#assembly-field-sections-13455[Getting started with OpenShift for developers (interactive tutorial)] -| xref:../applications/application_life_cycle_management/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating applications] - -| link:https://developers.redhat.com/[Red Hat Developers site] -| xref:../cicd/builds/understanding-image-builds.adoc#understanding-image-builds[Builds] - -| link:https://developers.redhat.com/products/codeready-workspaces/overview[Red Hat CodeReady Workspaces] -| xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Operators] - -| -| xref:../openshift_images/images-understand.adoc#understanding-images[Images] - -| -| xref:../cli_reference/developer_cli_odo/understanding-odo.adoc#understanding-odo[Developer-focused CLI] - -| -|=== diff --git a/welcome/legal-notice.adoc b/welcome/legal-notice.adoc deleted file mode 100644 index 5cea7ea04efa..000000000000 --- a/welcome/legal-notice.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[id="legal-notice"] -= Legal notice -include::modules/common-attributes.adoc[] -:context: legal-notice - -[.lead] -Copyright © 2021 Red Hat, Inc. - -OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0). - -Modified versions must remove all Red Hat trademarks. - -Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat. - -Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. - -Linux® is the registered trademark of Linus Torvalds in the United States and other countries. - -Java® is a registered trademark of Oracle and/or its affiliates. - -XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. - -MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries. - -Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. - -The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. - -All other trademarks are the property of their respective owners. diff --git a/welcome/oce_about.adoc b/welcome/oce_about.adoc deleted file mode 100644 index 8a2bafb604af..000000000000 --- a/welcome/oce_about.adoc +++ /dev/null @@ -1,407 +0,0 @@ -[[about_oce]] -= About {oce} -{product-author} -{product-version} -:oce: OpenShift Container Engine -:data-uri: -:icons: -:experimental: -:toc: macro -:toc-title:a - - -Red Hat {oce} is a new product offering from Red Hat -that lets you use {product-title} as a production platform for launching -containers. You download and install {oce} in the same way as {product-title}, -but {oce} offers a subset of the features that {product-title} does. - -[[about_oce_similarities_and_differences]] -== Similarities and differences -You can see the similarities and differences between {oce} -and {product-title} in the following table: - -.Product comparison for {oce} and {product-title} -|=== -2+| |{oce} |{product-title} - -2+h|Core Kubernetes and container orchestration -| Yes -| Yes - -2+h|Enterprise-ready configurations -| Yes -| Yes - -2+h|Standard infrastructure services -| Yes -| Yes - -2+h|Core user experience -| Yes -| Yes - -2+h|Maintained and curated content -| Yes -| Yes - -2+h|OpenShift Container Storage compatible -| Yes -| Yes - -2+h|Red Hat Middleware compatible -| Yes -| Yes - -2+h|Serverless Cloud Functions compatible -| Yes -| Yes - -2+h|Quay integration compatible -| Yes -| Yes - -2+h|OpenShift Virtualization for virtual machines compatible -| Yes -| Yes - -2+h|Advanced cluster management -| -| Yes - -2+h|Advanced networking -| -| Yes - -2+h|Developer experience -| -| Yes - -|=== - -[[about_oce_core_kubernetes_and_container_orchestration]] -=== Core Kubernetes and container orchestration -{oce} offers full access to an enterprise-ready Kubernetes environment that is -easy to install and offers an extensive compatibility test matrix with many of -the software elements that you might use in your data center. - -{oce} offers the same service level agreements, bug fixes, and common -vulnerabilities and errors protection as {product-title}. {oce} includes a -Red Hat Enterprise Linux Virtual Datacenter and Red Hat CoreOS entitlement that -allows you to use an integrated Linux operating system with container runtime -from the same provider. - -{oce} is compatible with Windows Containers from Microsoft. - -[[about_oce_enterprise_ready_configurations]] -=== Enterprise-ready configurations -{oce} uses the same security options and default settings as the {product-title}. -Default security context constraints, pod security policies, best practice -network and storage settings, service account configuration, SELinux integration, -HAproxy edge routing configuration, and all other standard protections that -{product-title} offers are available in {oce}. {oce} offers full access to the -integrated monitoring solution that {product-title} uses, which is based on -Prometheus and offers deep coverage and alerting for common Kubernetes issues. - -{oce} uses the same installation and upgrade automation as {product-title}. - -[[about_oce_standard_infrastructure_services]] -=== Standard infrastructure services -With an {oce} subscription, you receive support for all storage plug-ins that -{product-title} supports. - -In terms of networking, {oce} offers full and -supported access to the Kubernetes Container Network Interface (CNI) and -therefore allows you to use any third-party SDN that supports {product-title}. -It also allows you to use the included Open vSwitch to establish a flat, -non-project (Kubernetes namespace) segmented network for the Kubernetes cluster. -{oce} allows customers to use a Kubernetes Network Policy to create -microsegmentation between deployed application services on the cluster. - -You can also use the route API objects that are found in {product-title}, -including its sophisticated integration with the HAproxy edge routing layer. - -[[about_oce_core_user_experience]] -=== Core user experience -{oce} users have full access to Kubernetes Operators, pod deployment strategies, -Helm, and {product-title} templates. {oce} users can use both the `oc` and -`kubectl` command line interfaces. {oce} also offers an administrator web-based -console that shows all aspects of the deployed container services and offers a -container-as-a service experience. {oce} grants access to the Operator Life -Cycle Manager that helps you control access to content on the cluster and life -cycle operator-enabled services that you use. With an {oce} subscription, you -receive access to the Kubernetes namespace, the OpenShift Project API object, -and both cluster-level and tenant-level Prometheus monitoring metrics and events. - -=== Maintained and curated content -With an {oce} subscription, you receive access to the {product-title} entitled -content from the Red Hat Ecosystem Catalog and Red Hat Connect ISV marketplace. -You can access all maintained and curated content that the {product-title} -eco-system offers either for free, such as the Red Hat Software Collections, -or through additional purchases. The Kubernetes service broker, service catalog, -and all {product-title} service broker offerings are supported with an -{oce} subscription. - -=== OpenShift Container Storage compatible -{oce} is compatible and supported with OpenShift Container Storage. - -=== Red Hat Middleware compatible -{oce} is compatible and supported with Red Hat Middleware product solutions. - -=== Serverless Cloud Functions compatible -{oce} is compatible and supported with future Red Hat Cloud Functions products, -such as function based and serverless container services. - -=== Quay Integration compatible -{oce} is compatible and supported with Red Hat Quay. - -=== OpenShift virtualization compatible -{oce} is compatible and supported with Red Hat product offerings derived from -the kubevirt.io open source project. - -=== Advanced cluster management -A {oce} subscription does not offer a cluster-wide log aggregation -solution or support Elasticsearch, Fluentd, Kibana based logging solutions. -Similarly the chargeback features found in {product-title} and Red Hat Service -Mesh capabilities derived from the open source Istio.io and kiali.io projects -that offers OpenTracing observability for containerized services on -{product-title} are not supported. - -=== Advanced networking -The standard networking solutions in {product-title} are not supported with an -{oce} subscription. {product-title}’s Kubernetes CNI plug-in for automation of -multi-tenant network segmentation between {product-title} projects is not -entitled for use with {oce}. {product-title} offers more granular control of the -source IP addresses that are used by application services on the cluster. -Those egress IP address controls are not entitled for use with {oce}. -{product-title} offers ingress routing to on cluster services that use -non-standard ports when no public cloud provider is in use via the VIP pods -found in {product-title}. That ingress solution is not supported in {oce}. -{oce} users are supported for the Kubernetes ingress control object, which -offers integrations with public cloud providers. Red Hat Service Mesh, which is -derived from the istio.io open source project, is not supported in {oce}. - -=== Developer experience -With {oce}, the following capabilities are not supported: - -* The developer experience utilities and tools. -* {product-title}’s pipeline feature that integrates a streamlined, -Kubernetes-enabled Jenkins experience in the user’s project space. -* The {product-title}’s source-to-image feature, which allows you to easily -deploy source code, dockerfiles, or container images across the cluster. -* Build strategies, builder pods, or imagestreams for end user container -deployments. -* The `odo` developer command line. -* The developer persona in the {product-title} web console. - -=== Feature summary - -The following table is a summary of the feature availability in {oce} and -{product-title}. - -.Features in {oce} and {product-title} -|=== -2+| |{oce} |{product-title} - -2+h|Core Kubernetes and container orchestration -h| Yes -h| Yes - -.3+| -| Enterprise-class Kubernetes -| Yes -| Yes - -| Red Hat Enterprise Linux for Virtual Datacenters and Red Hat CoreOS -| Yes -| Yes - -| Windows containers compatible -| Yes -| Yes - -2+h|Enterprise-ready configurations -h| Yes -h| Yes - -.3+| -| Complete life-cycle automation of platform -| Yes -| Yes - - -| Management, monitoring, alerting, and remedy through Prometheus -| Yes -| Yes - - -| Enterprise-ready security -| Yes -| Yes - -2+h|Standard infrastructure services -h| Yes -h| Yes - -.3+| -| Edge routing -| Yes -| Yes - - -| Flat networking -| Yes -| Yes - - -| Kubernetes storage plug-ins -| Yes -| Yes - -2+h|Core user experience -h| Yes -h| Yes - -.6+| -| Application deployments, deployment configuration, templates, and Operators -| Yes -| Yes - -| Administrator console -| Yes -| Yes - -| Operator life cycle management -| Yes -| Yes - -| kubectl command line -| Yes -| Yes - -| Developer projects -| Yes -| Yes - -| Prometheus metrics -| Yes -| Yes - -2+h|Maintained and curated content -h| Yes -h| Yes - -.3+| -| Red Hat Ecosystem Catalog access -| Yes -| Yes - -| Independent Software Vendor and partner Operator access -| Yes -| Yes - -| Service Catalog and Brokers for cloud content -| Yes -| Yes - -2+h|Red Hat add-ons -h| -h| Yes - -.6+| -| OpenShift Container Storage compatible -| Yes -| Yes - -| Red Hat Middleware compatible -| Yes -| Yes - -| Serverless Cloud Functions compatible -| Yes -| Yes - -| Istio runtime launchers compatible -| -| Yes - -| Quay integration compatible -| Yes -| Yes - -| OpenShift Virtualization for virtual machines compatible -| Yes -| Yes - -2+h|Advanced cluster management -h| -h| Yes - -.3+| -| Logging -| -| Yes - -| Chargeback -| -| Yes - -| Kiali (Jaeger and OpenTracing) -| -| Yes - -2+h|Advanced networking -h| -h| Yes - -.5+| -| Egress per pod or namespace -| -| Yes - -| Ingress for non-standard ports -| -| Yes - -| Multi-tenant SDN -| -| Yes - -| Red Hat Service Mesh (Istio) -| -| Yes - -| Single Root I/O Virtualization (SR-IOV) -| -| Yes - -2+h|Developer experience -h| -h| Yes - -.4+| -| Integrated CI/CD pipelines -| -| Yes - -| Source-to-Image Container factory -| -| Yes - -| odo command line -| -| Yes - -| Developer console -| -| Yes - -|=== - - -== Subscription Limitations - -{oce} is a subscription offering that provides {product-title} with a limited set -of supported features at a lower list price. {oce} and {product-title} are the -same product and, therefore, all software and features are delivered in both. -There is only one download, {product-title}. {oce} uses the {product-title} -documentation and support services and bug errata for this reason. diff --git a/welcome/oke_about.adoc b/welcome/oke_about.adoc deleted file mode 100644 index 9b790f8d97d9..000000000000 --- a/welcome/oke_about.adoc +++ /dev/null @@ -1,497 +0,0 @@ -:context: oke-about -:oke: OpenShift Kubernetes Engine -[id="oke-about"] -= About {oke} -include::modules/common-attributes.adoc[] - -As of 27 April 2020, Red Hat has decided to rename Red Hat OpenShift Container Engine to Red Hat {oke} -to better communicate what value the product offering delivers. - -image::oke-about.png[Red Hat {oke}] - -Red Hat {oke} is a product offering from Red Hat that lets -you use an enterprise class Kubernetes platform as a production platform for -launching containers. You download and install {oke} the same way as {product-title} -as they are the same binary distribution, but {oke} offers a subset of the -features that {product-title} offers. - -[[about_oke_similarities_and_differences]] -== Similarities and differences -You can see the similarities and differences between {oke} -and {product-title} in the following table: - -.Product comparison for {oke} and {product-title} -|=== -2+| |{oke} |{product-title} - -2+h|Fully Automated Installers -| Yes -| Yes - -2+h|Over the Air Smart Upgrades -| Yes -| Yes - -2+h|Enterprise Secured Kubernetes -| Yes -| Yes - -2+h|Kubectl and oc automated command line -| Yes -| Yes - -2+h|Operator Lifecycle Manager (OLM) -| Yes -| Yes - -2+h|Administrator Web console -| Yes -| Yes - -2+h|OpenShift Virtualization -| Yes -| Yes - -2+h|User Workload Monitoring -| -| Yes - -2+h|Metering and Cost Management SaaS Service -| -| Yes - -2+h|Platform Logging -| -| Yes - -2+h|Developer Web Console -| -| Yes - -2+h|Developer Application Catalog -| -| Yes - -2+h|Source to Image and Builder Automation (Tekton) -| -| Yes - -2+h|OpenShift Service Mesh (Kiali, Jaeger, and OpenTracing) -| -| Yes - -2+h|OpenShift Serverless (Knative) -| -| Yes - -2+h|OpenShift Pipelines (Jenkins and Tekton) -| -| Yes - -2+h|Embedded Component of IBM Cloud Pak and RHT MW Bundles -| -| Yes - -|=== - -[[about_oke_core_kubernetes_and_container_orchestration]] -=== Core Kubernetes and container orchestration -{oke} offers full access to an enterprise-ready Kubernetes environment that is -easy to install and offers an extensive compatibility test matrix with many of -the software elements that you might use in your data center. - -{oke} offers the same service level agreements, bug fixes, and common -vulnerabilities and errors protection as {product-title}. {oke} includes a -Red Hat Enterprise Linux Virtual Datacenter and Red Hat CoreOS entitlement that -allows you to use an integrated Linux operating system with container runtime -from the same technology provider. - -{oke} is subscription compatible with Windows Containers from Microsoft. - -[[about_oke_enterprise_ready_configurations]] -=== Enterprise-ready configurations -{oke} uses the same security options and default settings as the {product-title}. -Default security context constraints, pod security policies, best practice -network and storage settings, service account configuration, SELinux integration, -HAproxy edge routing configuration, and all other standard protections that -{product-title} offers are available in {oke}. {oke} offers full access to the -integrated monitoring solution that {product-title} uses, which is based on -Prometheus and offers deep coverage and alerting for common Kubernetes issues. - -{oke} uses the same installation and upgrade automation as {product-title}. - -[[about_oke_standard_infrastructure_services]] -=== Standard infrastructure services -With an {oke} subscription, you receive support for all storage plug-ins that -{product-title} supports. - -In terms of networking, {oke} offers full and -supported access to the Kubernetes Container Network Interface (CNI) and -therefore allows you to use any third-party SDN that supports {product-title}. -It also allows you to use the included Open vSwitch software defined network to -its fullest extent. {oke} allows you to take full advantage of the OVN -Kubernetes overlay, Multus, and Multus plug-ins that are supported on -{product-title}. {oke} allows customers to use a Kubernetes Network Policy to -create microsegmentation between deployed application services on the cluster. - -You can also use the `Route` API objects that are found in {product-title}, -including its sophisticated integration with the HAproxy edge routing layer as an -out of the box Kubernetes ingress controller. - -[[about_oke_core_user_experience]] -=== Core user experience -{oke} users have full access to Kubernetes Operators, pod deployment strategies, -Helm, and {product-title} templates. {oke} users can use both the `oc` and -`kubectl` command line interfaces. {oke} also offers an administrator web-based -console that shows all aspects of the deployed container services and offers a -container-as-a service experience. {oke} grants access to the Operator Life -Cycle Manager that helps you control access to content on the cluster and life -cycle operator-enabled services that you use. With an {oke} subscription, you -receive access to the Kubernetes namespace, the OpenShift `Project` API object, -and cluster-level Prometheus monitoring metrics and events. - -=== Maintained and curated content -With an {oke} subscription, you receive access to the {product-title} -content from the Red Hat Ecosystem Catalog and Red Hat Connect ISV marketplace. -You can access all maintained and curated content that the {product-title} -eco-system offers. - -=== OpenShift Container Storage compatible -{oke} is compatible and supported with your purchase of OpenShift Container Storage. - -=== Red Hat Middleware compatible -{oke} is compatible and supported with individual Red Hat Middleware product solutions. -Red Hat Middleware Bundles that include OpenShift embedded in them only contain -{product-title}. - -=== OpenShift Serverless -{oke} does not include OpenShift Serverless support. Please use {product-title} -for this support. - -=== Quay Integration compatible -{oke} is compatible and supported with a Red Hat Quay purchase. - -=== OpenShift Virtualization -{oke} includes support for the Red Hat product offerings derived from -the kubevirt.io open source project. - -=== Advanced cluster management -{oke} is compatible with your additional purchase of Red Hat Advanced Cluster -Manager for Kubernetes. An {oke} subscription does not offer a cluster-wide log -aggregation solution or support Elasticsearch, Fluentd, or Kibana based logging solutions. -Similarly, the chargeback features found in {product-title} or the cloud.redhat.com -Cost Management SaaS service are not supported with {oke}. Red Hat Service Mesh -capabilities derived from the open source istio.io and kiali.io projects that -offer OpenTracing observability for containerized services on {product-title} are -not supported in {oke}. - -=== Advanced networking -The standard networking solutions in {product-title} are supported with an -{oke} subscription. {product-title}’s Kubernetes CNI plug-in for automation of -multi-tenant network segmentation between {product-title} projects is -entitled for use with {oke}. {oke} offers all the granular control of the -source IP addresses that are used by application services on the cluster. -Those egress IP address controls are entitled for use with {oke}. -{product-title} offers ingress routing to on cluster services that use -non-standard ports when no public cloud provider is in use via the VIP pods -found in {product-title}. That ingress solution is supported in {oke}. -{oke} users are supported for the Kubernetes ingress control object, which -offers integrations with public cloud providers. Red Hat Service Mesh, which is -derived from the istio.io open source project, is not supported in {oke}. Also, -the Kourier ingress controller found in OpenShift Serverless is not supported -on {oke}. - -=== Developer experience -With {oke}, the following capabilities are not supported: - -* The CodeReady developer experience utilities and tools, such as CodeReady Workspaces. -* {product-title}’s pipeline feature that integrates a streamlined, -Kubernetes-enabled Jenkins and Tekton experience in the user’s project space. -* The {product-title}’s source-to-image feature, which allows you to easily -deploy source code, dockerfiles, or container images across the cluster. -* Build strategies, builder pods, or Tekton for end user container -deployments. -* The `odo` developer command line. -* The developer persona in the {product-title} web console. - -=== Feature summary - -The following table is a summary of the feature availability in {oke} and -{product-title}. - -.Features in {oke} and {product-title} -|=== -2+| |{oke} |{product-title} - -2+h|Life Cycle and Kubernetes -h| -h| - -.11+| -| Fully Automated Installers (IPI) -| Yes -| Yes - -| Customizable Installers (UPI) -| Yes -| Yes - -| Disconnect Installation -| Yes -| Yes - -| RHEL or CoreOS entitlement -| Yes -| Yes - -| Automated Operating System Management (CoreOS) -| Yes -| Yes - -| Existing RHEL manual attach to cluster (BYO) -| Yes -| Yes - -| CRIO Runtime -| Yes -| Yes - -| OpenShift Virtualization -| Yes -| Yes - -| Enterprise Secured Kubernetes -| Yes -| Yes - -| Auth Integrations, RBAC, SCC, Multi-Tenancy Admission Controller -| Yes -| Yes - -| Kubectl and oc automated command line -| Yes -| Yes - -2+h|Day 2 Management -h| -h| - -.13+| -| Operator Enabled Platform (CVO) -| Yes -| Yes - -| Operator Lifecycle Manager (OLM) -| Yes -| Yes - -| Cluster Monitoring (Prometheus) -| Yes -| Yes - -| User Workload Monitoring -| -| Yes - -| Device Manager (i.e., GPU) -| Yes -| Yes - -| EFK Logging (ElasticSearch and Kibana) -| -| Yes - -| Log Pipelines (fluentd forwarding) -| Yes -| Yes - -| Administrator Web Console -| Yes -| Yes - -| Service Mesh (Kiali, Jaeger, and OpenTracing) -| -| Yes - -| Over the Air Smart Upgrades -| Yes -| Yes - -| Telemeter and Insights Connected Experience -| Yes -| Yes - -| Metering and Cost Management SaaS Service -| -| Yes - -| OCM SaaS Service -| Yes -| Yes - -2+h|Network and Storage -h| -h| - -.15+| -| OVS and OVN SDN -| Yes -| Yes - -| HAProxy Ingress Controller -| Yes -| Yes - -| Kourier Ingress Controller -| -| Yes - -| OpenStack Kuryr Integration -| Yes -| Yes - -| Ingress Cluster-wide Firewall -| Yes -| Yes - -| Egress Pod and Namespace Granular Control -| Yes -| Yes - -| Ingress Non-Standard Ports -| Yes -| Yes - -| Service Mesh (Istio and Envoy) -| -| Yes - -| Multus and Available Multus Plugins -| Yes -| Yes - -| Network Policies -| Yes -| Yes - -| IPv6 Single and Dual Stack (primary interface) -| -| - -| IPv6 Single and Dual Stack (Multus secondary interfaces) -| Yes -| Yes - -| CNI Plugin ISV Compatibility -| Yes -| Yes - -| OpenShift Container Storage Sub Compatibility (not included in OCP or {oke}) -| Yes -| Yes - -| CSI Plugin ISV Compatibility -| Yes -| Yes - -2+h|Application Services -h| -h| - -.10+| -| RHT Middleware Bundles Sub Compatibility (not included in OCP) -| -| Yes - -| IBM Cloud Pak Sub Compatibility (not included in OCP) -| -| Yes - -| RHT and IBM middleware a la carte purchases (not included in OCP) -| Yes -| Yes - -| ISV or Partner Operator and Container Compatibility (not included in OCP or {oke}) -| Yes -| Yes - -| Embedded OperatorHub -| Yes -| Yes - -| Embedded Marketplace -| Yes -| Yes - -| Developer Application Catalog -| -| Yes - -| Quay Compatibility (not included) -| Yes -| Yes - -| RHEL Software Collections and RHT SSO Common Service (included) -| Yes -| Yes - -| OpenShift Serverless -| -| Yes - -2+h|Developer Experience -h| -h| - -.10+| -| Embedded Registry -| Yes -| Yes - -| CodeReady Containers -| -| Yes - -| CodeReady Workspaces -| -| Yes - -| Developer Web Console -| -| Yes - -| Helm -| Yes -| Yes - -| OpenShift Pipelines (Jenkins and Tekton) -| -| Yes - -| odo -| -| Yes - -| Source to Image and Tekton Builders -| -| Yes - -| OpenShift Serverless FaaS -| -| Yes - -| IDE Integrations -| -| Yes - - -|=== - - -== Subscription Limitations - -{oke} is a subscription offering that provides {product-title} with a limited set -of supported features at a lower list price. {oke} and {product-title} are the -same product and, therefore, all software and features are delivered in both. -There is only one download, {product-title}. {oke} uses the {product-title} -documentation and support services and bug errata for this reason. diff --git a/welcome/snippets b/welcome/snippets new file mode 120000 index 000000000000..9d58b92e5058 --- /dev/null +++ b/welcome/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/whats_new/deprecated-features.adoc b/whats_new/deprecated-features.adoc deleted file mode 100644 index 3ec4bd217116..000000000000 --- a/whats_new/deprecated-features.adoc +++ /dev/null @@ -1,93 +0,0 @@ -:context: deprecated-features -[id="deprecated-features"] -= Deprecated features -include::modules/common-attributes.adoc[] - -toc::[] - -Large changes to the underlying architecture and installation process are -applied in {product-title} v4, and many features from {product-title} v3 are -now deprecated. - -[id="deprecated"] -== Features deprecated in {product-title} v4 - -.Features Deprecated in {product-version} -[cols="2",options="header"] -|==== -|Feature |Justification - -|Hawkular -|Replaced by cluster monitoring. - -|Cassandra -|Replaced by cluster monitoring. - -|Heapster -|Replaced by Prometheus adapter. - -|Atomic Host -|Replaced by Red Hat Enterprise Linux CoreOS. - -|System containers -|Replaced by Red Hat Enterprise Linux CoreOS. - -|`projectatomic/docker-1.13` additional search registries -|CRI-O is the default container runtime for OpenShift v4 on RHCOS and Red -Hat Enterprise Linux. - -|`oc adm diagnostics` -|Operator-based diagnostics. - -|`oc adm registry` -|Replaced by the Image Registry Operator. - -|Custom strategy builds using Docker -|If you want to continue using custom builds, you should replace your Docker -invocations with Podman or Buildah. The custom build strategy will not be -removed, but the functionality changed significantly in OpenShift v4. - -|Cockpit -|Improved OpenShift v4 web console. - -|Stand-alone registry installations -|Quay is Red Hat's enterprise container image registry. - -|DNSmasq -|CoreDNS is the default. - -|External etcd nodes -|etcd is always on the cluster in OpenShift v4. - -|CloudForms OpenShift Provider and Podified CloudForms -|Replaced by built-in management tooling. - -|Volume Provisioning via installer -|Replaced by dynamic volumes or, if NFS is required, NFS provisioner. - -|Blue-green installation method -|Ease of upgrade is a core value of OpenShift v4. - -|OpenShift Service Broker and Service Catalog -|The Service Catalog and the OpenShift service brokers are being replaced over -the course of several future OpenShift v4 releases. Reference the Operator -Framework and Operator Lifecycle Manager (OLM) to continue providing your -applications to OpenShift v4 clusters. These new technologies provide many -benefits around complete management of the lifecycle of your application. - -|`oc adm ca` -|Certificates are managed by Operators internally. - -|`oc adm create-api-client-config` -.2+.^|Functions are managed by Operators internally. - -|`oc adm create-bootstrap-policy-file` - -|`oc adm policy reconcile-sccs` -|Functions are managed by `openshift-apiserver` internally. - -|Web console -|The web console from OpenShift v3 has been replaced by a new web -console in OpenShift v4. - -|==== diff --git a/whats_new/modules b/whats_new/modules deleted file mode 120000 index 43aab75b53c9..000000000000 --- a/whats_new/modules +++ /dev/null @@ -1 +0,0 @@ -../modules/ \ No newline at end of file diff --git a/whats_new/new-features.adoc b/whats_new/new-features.adoc deleted file mode 100644 index f66b45f002f5..000000000000 --- a/whats_new/new-features.adoc +++ /dev/null @@ -1,282 +0,0 @@ -:context: new-features -[id="new-features"] -= New features and enhancements -include::modules/common-attributes.adoc[] - -toc::[] - -This release adds improvements related to the following components and concepts. - -See the link:https://github.com/openshift/okd/releases[*Releases*] page in the -*openshift/okd* project repository for information on the latest OKD releases. - -[id="ocp-operators"] -== Operators - -xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Operators] -are pieces of software that ease the operational complexity of running another -piece of software. They act like an extension of the software vendor’s -engineering team, watching over a Kubernetes environment (such as -{product-title}) and using its current state to make decisions in real time. -Advanced Operators are designed to handle upgrades seamlessly, react to failures -automatically, and not take shortcuts, like skipping a software backup process -to save time. - -[id="ocp-operator-lifecycle-manager"] -=== Operator Lifecycle Manager (OLM) - -This feature is now fully supported in OpenShift v4. - -The OLM aids cluster administrators in installing, upgrading, and granting -access to Operators running on their cluster: - -* Includes a catalog of curated Operators, with the ability to load other Operators into the cluster -* Handles rolling updates of all Operators to new versions -* Supports role-based access control (RBAC) for certain teams to use certain Operators - -See -xref:../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Understanding the Operator Lifecycle Manager (OLM)] for more information. - -[id="ocp-installation-and-upgrade"] -== Installation and upgrade - -Red Hat OpenShift v4 has an installer-provisioned infrastructure, where -the installation program controls all areas of the installation process. -Installer-provisioned infrastructure also provides an opinionated best practices -deployment of OpenShift v4 for AWS instances only. This provides a -slimmer default installation, with incremental feature buy-in through -OperatorHub. - -You can also install with a user-provided infrastructure on -AWS, bare metal, or vSphere hosts. If you use the installer-provisioned -infrastructure installation, the cluster provisions and manages all of the -cluster infrastructure for you. - -Upgrading from 3.x to 4 is currently not available. You must perform a new -installation of OpenShift v4. - -Easy, over-the-air upgrades for asynchronous z-stream releases of -OpenShift v4 is available. Cluster administrators can upgrade using the -*Cluster Settings* tab in the web console. -See -xref:../updating/updating-cluster.adoc#updating-cluster[Updating a cluster] -for more information. - -[id="ocp-operator-hub"] -=== OperatorHub - -OperatorHub is available to administrators and helps with easy discovery and -installation of all optional components and applications. It includes offerings -from Red Hat products, Red Hat partners, and the community. - -.Features provided with base installation and OperatorHub -[cols="3",options="header"] -|=== -|Feature |New installer |OperatorHub - -|Console and authentication -|* [x] -| - - -|Prometheus cluster monitoring -|* [x] -| - - -|Over-the-air updates -|* [x] -| - - -|Machine management -|* [x] -| - - -|Optional service brokers -| - -|* [x] - -|Optional {product-title} components -| - -|* [x] - -|Red Hat product Operators -| - -|* [x] - -|Red Hat partner Operators -| - -|* [x] - -|Community Operators -| - -|* [x] - -|=== - -See -xref:../operators/understanding/olm-understanding-operatorhub.adoc#olm-understanding-operatorhub[Understanding the OperatorHub] for more information. - -[id="ocp-storage"] -== Storage - -Storage support in OpenShift v4 is the same as OpenShift v3 with -the exception of the following available in Technology Preview: EFS (CSI Driver -handled via Amazon), Manila provisioner/operator, and Snapshot. - -[id="ocp-scale"] -== Scale - -[id="ocp-scale-cluster-limits"] -=== Cluster maximums - -Updated guidance around -xref:../scalability_and_performance/planning-your-environment-according-to-object-maximums.adoc#planning-your-environment-according-to-object-maximums[Cluster -maximums] for OpenShift v4 is now available. - -Use the link:https://access.redhat.com/labs/ocplimitscalculator/[{product-title} -Limit Calculator] to estimate cluster limits for your environment. - -[id="ocp-node-tuning-operator"] -=== Node Tuning Operator - -The -xref:../scalability_and_performance/using-node-tuning-operator.adoc#using-node-tuning-operator[Node -Tuning Operator] is now part of a standard {product-title} installation in -OpenShift v4. - -The Node Tuning Operator helps you manage node-level tuning by orchestrating the -tuned daemon. The majority of high-performance applications require some level -of kernel tuning. The Node Tuning Operator provides a unified management -interface to users of node-level sysctls and more flexibility to add custom -tuning, which is currently a Technology Preview feature, specified by user -needs. The Operator manages the containerized tuned daemon for OpenShift -Container Platform as a Kubernetes DaemonSet. It ensures the custom tuning -specification is passed to all containerized tuned daemons running in the -cluster in the format that the daemons understand. The daemons run on all nodes -in the cluster, one per node. - -[id="ocp-cluster-monitoring"] -== Cluster monitoring - -[id="ocp-autoscale-pods-horizontally-based-on-custom-metrics-api"] -=== Autoscale pods horizontally based on the custom metrics API (Technology Preview) - -This feature, currently in Technology Preview, enables you to configure -horizontal pod autoscaling (HPA) based on the custom metrics API. As part of -this Technology Preview, a Prometheus Adapter component can be deployed to -provide any app metrics for the custom metrics API. - -Limitations: - -* The adapter only connects to a single Prometheus instance (or a set of -load-balanced replicas, using Kubernetes services). -* Manually deploying adapter and configuring it to use Prometheus. -* Syntax for the Prometheus Adapter configuration could change in the future. -* The `APIService` configuration to wire Kubernetes' API aggregation to the -instance of the custom metrics adapter will be overwritten in future releases, -if {product-title} ships an out-of-the-box custom metrics adapter. - -[id="ocp-cluster-monitoring-alerting-UI"] -=== New alerting user interface - -An alerting UI is now natively integrated into the {product-title} web console. -You can now view cluster-level alerts and alerting rules from a single place, as -well as configure silences. - -[id="ocp-cluster-monitoring-telemeter"] -=== Telemeter - -Telemeter collects anonymized cluster-related metrics to proactively help -customers with their {product-title} clusters. This helps: - -* Gather crucial health metrics of {product-title} installations. -* Enable a viable feedback loop of {product-title} upgrades. -* Gather the cluster's number of nodes per cluster and their size (CPU cores and -RAM). -* Gather the size of etcd. -* Gather details about the health condition and status for any OpenShift framework -component installed on an OpenShift cluster. - -[id="ocp-cluster-monitoring-autoscale"] -=== Autoscale pods horizontally based on the resource metrics API - -By default, OpenShift Cluster Monitoring exposes CPU and Memory utilization -through the Kubernetes resource metrics API. There is no longer a requirement to -install a separate metrics server. - -[id="ocp-developer-experience"] -== Developer experience - -[id="ocp-multistage-builds"] -=== Multi-stage Dockerfile Builds Generally Available - -Multi-stage Dockerfiles are now supported in all `Docker` strategy builds. - -[id="ocp-registry"] -== Registry - -[id="ocp-registry-managed-by-operator"] -=== The registry is now managed by an Operator - -The registry is now managed by an Operator instead of `oc adm registry`. - -[id="ocp-networking"] -== Networking - -[id="ocp-cno"] -=== Cluster Network Operator (CNO) - -The cluster network is now configured and managed by an Operator. The Operator -upgrades and monitors the cluster network. - -[id="ocp-openshift-sdn"] -=== OpenShift SDN - -The default mode is now `NetworkPolicy`. - -[id="ocp-multus"] -=== Multus - -Multus is a meta plug-in for Kubernetes Container Network Interface (CNI), which -enables a user to create multiple network interfaces per pod. - -[id="ocp-sriov"] -=== SR-IOV - -OpenShift v4 includes the Technical Preview capability to use specific -SR-IOV hardware on {product-title} nodes, which enables the user to -attach SR-IOV virtual function (VF) interfaces to Pods in addition to other -network interfaces. - -[id="ocp-f5"] -=== F5 router plug-in support - -F5 router plug-in is no longer supported as part of {product-title} directly. -However, F5 has developed a container connector that replaces the functionality. -It is recommended to work with F5 support to implement their solution. - -[id="ocp-web-console"] -== Web console - -[id="ocp-developer-catalog"] -=== Developer Catalog - -OpenShift v4 features a redesigned Developer Catalog that brings all of -the new Operators and existing broker services together, with new ways to -discover, sort, and understand how to best use each type of offering. The -Developer Catalog is the entry point for a developer to access all services -available to them. It merges all capabilities from Operators, the Service -Catalog, brokers, and Source-to-Image (S2I). - -[id="ocp-new-management-screens"] -=== New management screens - -New management screens in OpenShift v4 support automated operations. -Examples include the management of machine sets and machines, taints, -tolerations, and cluster settings. - -[id="ocp-security"] -== Security - -In OpenShift v4, Operators are utilized to install, configure, and -manage the various certificate signing servers. Certificates are managed -as secrets stored within the cluster itself. diff --git a/windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.adoc b/windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.adoc deleted file mode 100644 index 7f7bb9ec8390..000000000000 --- a/windows_containers/creating_windows_machinesets/creating-windows-machineset-aws.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="creating-windows-machineset-aws"] -= Creating a Windows `MachineSet` object on AWS -include::modules/common-attributes.adoc[] -:context: creating-windows-machineset-aws - -toc::[] - -You can create a Windows `MachineSet` object to serve a specific purpose in your {product-title} cluster on Amazon Web Services (AWS). For example, you might create infrastructure Windows machine sets and related machines so that you can move supporting Windows workloads to the new Windows machines. - -[discrete] -== Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You are using a supported Windows Server as the operating system image with the Docker-formatted container runtime add-on enabled. - -[IMPORTANT] -==== -Currently, the Docker-formatted container runtime is used in Windows nodes. Kubernetes is deprecating Docker as a container runtime; you can reference the Kubernetes documentation for more information in link:https://kubernetes.io/blog/2020/12/02/dont-panic-kubernetes-and-docker/[Docker deprecation]. Containerd will be the new supported container runtime for Windows nodes in a future release of Kubernetes. -==== - -include::modules/machine-api-overview.adoc[leveloffset=+1] -include::modules/windows-machineset-aws.adoc[leveloffset=+1] -include::modules/machineset-creating.adoc[leveloffset=+1] - -== Additional resources - -* For more information on managing machine sets, see the _Machine management_ section. diff --git a/windows_containers/creating_windows_machinesets/creating-windows-machineset-azure.adoc b/windows_containers/creating_windows_machinesets/creating-windows-machineset-azure.adoc deleted file mode 100644 index fec8d1513dfb..000000000000 --- a/windows_containers/creating_windows_machinesets/creating-windows-machineset-azure.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="creating-windows-machineset-azure"] -= Creating a Windows `MachineSet` object on Azure -include::modules/common-attributes.adoc[] -:context: creating-windows-machineset-azure - -toc::[] - -You can create a Windows `MachineSet` object to serve a specific purpose in your {product-title} cluster on Microsoft Azure. For example, you might create infrastructure Windows machine sets and related machines so that you can move supporting Windows workloads to the new Windows machines. - -[discrete] -== Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You are using a supported Windows Server as the operating system image with the Docker-formatted container runtime add-on enabled. - -[IMPORTANT] -==== -Currently, the Docker-formatted container runtime is used in Windows nodes. Kubernetes is deprecating Docker as a container runtime; you can reference the Kubernetes documentation for more information in link:https://kubernetes.io/blog/2020/12/02/dont-panic-kubernetes-and-docker/[Docker deprecation]. Containerd will be the new supported container runtime for Windows nodes in a future release of Kubernetes. -==== - -include::modules/machine-api-overview.adoc[leveloffset=+1] -include::modules/windows-machineset-azure.adoc[leveloffset=+1] -include::modules/machineset-creating.adoc[leveloffset=+1] - -== Additional resources - -* For more information on managing machine sets, see the _Machine management_ section. diff --git a/windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc b/windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc deleted file mode 100644 index 2b9a7b740599..000000000000 --- a/windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[id="creating-windows-machineset-vsphere"] -= Creating a Windows MachineSet object on vSphere -include::modules/common-attributes.adoc[] -:context: creating-windows-machineset-vsphere - -toc::[] - -You can create a Windows `MachineSet` object to serve a specific purpose in your {product-title} cluster on VMware vSphere. For example, you might create infrastructure Windows machine sets and related machines so that you can move supporting Windows workloads to the new Windows machines. - -[discrete] -== Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You are using a supported Windows Server as the operating system image with the Docker-formatted container runtime add-on enabled. - -[IMPORTANT] -==== -Currently, the Docker-formatted container runtime is used in Windows nodes. Kubernetes is deprecating Docker as a container runtime; you can reference the Kubernetes documentation for more information on link:https://kubernetes.io/blog/2020/12/02/dont-panic-kubernetes-and-docker/[Docker deprecation]. Containerd will be the new supported container runtime for Windows nodes in a future release of Kubernetes. -==== - -include::modules/machine-api-overview.adoc[leveloffset=+1] - -[id="preparing-vsphere-for-windows-containers"] -== Preparing your vSphere environment for Windows container workloads - -You must prepare your vSphere environment for Windows container workloads by creating the vSphere Windows VM golden image and enabling communication with the internal API server for the WMCO. - -include::modules/creating-the-vsphere-windows-vm-golden-image.adoc[leveloffset=+2] -include::modules/enabling-internal-api-server-vsphere.adoc[leveloffset=+2] - -include::modules/windows-machineset-vsphere.adoc[leveloffset=+1] -include::modules/machineset-creating.adoc[leveloffset=+1] - -== Additional resources - -* For more information on managing machine sets, see the _Machine management_ section. diff --git a/windows_containers/disabling-windows-container-workloads.adoc b/windows_containers/disabling-windows-container-workloads.adoc deleted file mode 100644 index 8f597a800520..000000000000 --- a/windows_containers/disabling-windows-container-workloads.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[id="disabling-windows-container-workloads"] -= Disabling Windows container workloads -include::modules/common-attributes.adoc[] -:context: disabling-windows-container-workloads - -toc::[] - -You can disable the capability to run Windows container workloads by uninstalling the Windows Machine Config Operator (WMCO) and deleting the namespace that was added by default when you installed the WMCO. - -include::modules/uninstalling-wmco.adoc[leveloffset=+1] - -include::modules/deleting-wmco-namespace.adoc[leveloffset=+1] - -[discrete] -== Additional Resources - -* xref:../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster] - -* xref:../windows_containers/removing-windows-nodes.adoc#removing-windows-nodes[Removing Windows nodes]. diff --git a/windows_containers/enabling-windows-container-workloads.adoc b/windows_containers/enabling-windows-container-workloads.adoc deleted file mode 100644 index a06f6c88dcc3..000000000000 --- a/windows_containers/enabling-windows-container-workloads.adoc +++ /dev/null @@ -1,37 +0,0 @@ -[id="enabling-windows-container-workloads"] -= Enabling Windows container workloads -include::modules/common-attributes.adoc[] -:context: enabling-windows-container-workloads - -toc::[] - -Before adding Windows workloads to your cluster, you must install the Windows Machine Config Operator (WMCO), which is available in the {product-title} OperatorHub. The WMCO orchestrates the process of deploying and managing Windows workloads on a cluster. - -[discrete] -== Prerequisites - -* You have access to an {product-title} cluster using an account with `cluster-admin` permissions. - -* You have installed the OpenShift CLI (`oc`). - -* You have installed your cluster using installer-provisioned infrastructure. Clusters installed with user-provisioned infrastructure are not supported for Windows container workloads. - -* You have configured hybrid networking with OVN-Kubernetes for your cluster. This must be completed during the installation of your cluster. For more information, see xref:../networking/ovn_kubernetes_network_provider/configuring-hybrid-networking.adoc#configuring-hybrid-ovnkubernetes[Configuring hybrid networking]. - -* You are running an {product-title} cluster version 4.6.8 or later. - -[id="installing-the-wmco"] -== Installing the Windows Machine Config Operator - -You can install the Windows Machine Config Operator using either the web console or OpenShift CLI (`oc`). - -include::modules/installing-wmco-using-web-console.adoc[leveloffset=+2] -include::modules/installing-wmco-using-cli.adoc[leveloffset=+2] - -include::modules/configuring-secret-for-wmco.adoc[leveloffset=+1] - -[discrete] -== Additional Resources - -* xref:../installing/installing_azure/installing-azure-default.adoc#ssh-agent-using_installing-azure-default[Generating an SSH private key and adding it to the agent] -* xref:../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[Adding Operators to a cluster]. diff --git a/windows_containers/images b/windows_containers/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/windows_containers/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/windows_containers/modules b/windows_containers/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/windows_containers/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/windows_containers/removing-windows-nodes.adoc b/windows_containers/removing-windows-nodes.adoc deleted file mode 100644 index a28bdaa70eca..000000000000 --- a/windows_containers/removing-windows-nodes.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[id="removing-windows-nodes"] -= Removing Windows nodes -include::modules/common-attributes.adoc[] -:context: removing-windows-nodes - -toc::[] - -You can remove a Windows node by deleting its host Windows machine. - -include::modules/machine-delete.adoc[leveloffset=+1] diff --git a/windows_containers/scheduling-windows-workloads.adoc b/windows_containers/scheduling-windows-workloads.adoc deleted file mode 100644 index 81481b15343b..000000000000 --- a/windows_containers/scheduling-windows-workloads.adoc +++ /dev/null @@ -1,35 +0,0 @@ -[id="scheduling-windows-workloads"] -= Scheduling Windows container workloads -include::modules/common-attributes.adoc[] -:context: scheduling-windows-workloads - -toc::[] - -You can schedule Windows workloads to Windows compute nodes. - -[discrete] -== Prerequisites - -* You installed the Windows Machine Config Operator (WMCO) using Operator Lifecycle Manager (OLM). -* You are using a Windows container as the OS image with the Docker-formatted container runtime add-on enabled. -* You have created a Windows machine set. - -[IMPORTANT] -==== -Currently, the Docker-formatted container runtime is used in Windows nodes. Kubernetes is deprecating Docker as a container runtime; you can reference the Kubernetes documentation for more information in link:https://kubernetes.io/blog/2020/12/02/dont-panic-kubernetes-and-docker/[Docker deprecation]. Containerd will be the new supported container runtime for Windows nodes in a future release of Kubernetes. -==== - -include::modules/windows-pod-placement.adoc[leveloffset=+1] - -[discrete] -=== Additional resources - -* xref:../nodes/scheduling/nodes-scheduler-about.adoc#nodes-scheduler-about[Controlling pod placement using the scheduler] -* xref:../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations[Controlling pod placement using node taints] -* xref:../nodes/scheduling/nodes-scheduler-node-selectors.adoc#nodes-scheduler-node-selectors[Placing pods on specific nodes using node selectors] - -include::modules/creating-runtimeclass.adoc[leveloffset=+1] - -include::modules/sample-windows-workload-deployment.adoc[leveloffset=+1] - -include::modules/machineset-manually-scaling.adoc[leveloffset=+1] diff --git a/windows_containers/understanding-windows-container-workloads.adoc b/windows_containers/understanding-windows-container-workloads.adoc deleted file mode 100644 index dc4340736cff..000000000000 --- a/windows_containers/understanding-windows-container-workloads.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[id="understanding-windows-container-workloads"] -= Understanding Windows container workloads -include::modules/common-attributes.adoc[] -:context: understanding-windows-container-workloads - -toc::[] - -Windows Container Support for Red Hat OpenShift provides built-in support for running Microsoft Windows Server containers on {product-title}. For those that administer heterogeneous environments with a mix of Linux and Windows workloads, {product-title} allows you to deploy Windows workloads running on Windows Server containers while also providing traditional Linux workloads hosted on {op-system-first} or {op-system-base-full}. - -Windows container workloads are supported for clusters running on the following cloud providers: - -* Amazon Web Services (AWS) -* Microsoft Azure -* VMware vSphere - -The following Windows Server operating systems are supported for {product-title} {product-version}: - -* Windows Server Long-Term Servicing Channel (LTSC): Windows Server 2019 - -For more information, see Microsoft's documentation on link:https://docs.microsoft.com/en-us/windows-server/get-started-19/servicing-channels-19[Windows Server channels]. - -[NOTE] -==== -Multi-tenancy for clusters that have Windows nodes is not supported. Hostile multi-tenant usage introduces security concerns in all Kubernetes environments. Additional security features like link:https://kubernetes.io/docs/concepts/policy/pod-security-policy/[pod security policies], or more fine-grained role-based access control (RBAC) for nodes, make exploits more difficult. However, if you choose to run hostile multi-tenant workloads, a hypervisor is the only security option you should use. The security domain for Kubernetes encompasses the entire cluster, not an individual node. For these types of hostile multi-tenant workloads, you should use physically isolated clusters. - -Windows Server Containers provide resource isolation using a shared kernel but are not intended to be used in hostile multitenancy scenarios. Scenarios that involve hostile multitenancy should use Hyper-V Isolated Containers to strongly isolate tenants. -==== - -include::modules/windows-workload-management.adoc[leveloffset=+1] - -include::modules/windows-node-services.adoc[leveloffset=+1] - -//modules/windows-linux-containers-differences.adoc[leveloffset=+1] diff --git a/windows_containers/windows-containers-release-notes-2-x.adoc b/windows_containers/windows-containers-release-notes-2-x.adoc deleted file mode 100644 index dde30843b08d..000000000000 --- a/windows_containers/windows-containers-release-notes-2-x.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[id="windows-containers-release-notes-2-x"] -= Windows Container Support for Red Hat OpenShift release notes -include::modules/common-attributes.adoc[] -:context: windows-containers-release-notes - -toc::[] - -[id="about-windows-containers"] -== About Windows Container Support for Red Hat OpenShift - -Windows Container Support for Red Hat OpenShift is a feature providing the ability to run Windows compute nodes in an {product-title} cluster. This is possible by using the Red Hat Windows Machine Config Operator (WMCO) to install and manage Windows nodes. With Windows nodes available, you can run Windows container workloads in {product-title}. - -The release notes for Red Hat OpenShift for Windows Containers tracks the development of the WMCO, which provides all Windows container workload capabilities in {product-title}. - -[id="getting-support"] -== Getting support - -You must have a subscription to receive support for the Red Hat WMCO. Deploying Windows container workloads in production clusters is not supported without a subscription. If you do not have a subscription, you can use the community WMCO, a distribution that lacks official support. Request support through the link:http://access.redhat.com/[Red Hat Customer Portal]. - -[id="wmco-2-0-0"] -== Release notes for Red Hat Windows Machine Config Operator 2.0.0 - -This release of the WMCO provides bug fixes and enhancements for running Windows compute nodes in an {product-title} cluster. The components of the WMCO 2.0.0 were released in link:https://access.redhat.com/errata/RHBA-2021:0440[RHBA-2021:0440]. - -WMCO supports self-managed clusters built using installer-provisioned infrastructure running on the following cloud providers: - -* Amazon Web Services (AWS) -* Microsoft Azure -* VMware vSphere - -The following Windows Server operating systems are supported in this release of the WMCO, depending on which platform your cluster is installed on: - -[cols="1,4",options="header"] -|=== - -|WMCO platform -|Windows Server version - -|AWS -|Windows Server Long-Term Servicing Channel (LTSC): Windows Server 2019 - -|Azure -|Windows Server Long-Term Servicing Channel (LTSC): Windows Server 2019 - -|vSphere -|Windows Server Semi-Annual Channel (SAC): Windows Server 1909 with link:https://support.microsoft.com/en-us/help/4565351/windows-10-update-kb4565351[Microsoft patch KB4565351] - -|=== - -[IMPORTANT] -==== -Running Windows container workloads is not supported for clusters in a restricted network or disconnected environment. -==== - -Version 2.x of the WMCO is only compatible with {product-title} 4.7. - -[id="wmco-2-0-0-improvements"] -=== New features and improvements - -This release adds the following new features and improvements. - -[id="wmco-2-0-0-vsphere-support"] -==== Support for clusters running on VMware vSphere - -You can now run Windows nodes on a cluster installed on VMware vSphere version 6.5, 6.7, or 7.0. You can create a Windows `MachineSet` object on vSphere to host Windows Server compute nodes. For more information, see xref:../windows_containers/creating_windows_machinesets/creating-windows-machineset-vsphere.adoc#creating-windows-machineset-vsphere[Creating a Windows `MachineSet` object on vSphere]. - -[id="wmco-2-0-0-monitoring"] -==== Enhanced Windows node monitoring - -Windows nodes are now fully integrated with most of the monitoring capabilities provided by the web console. However, it is not possible to view workload graphs for pods running on Windows nodes in this release. - -[id="wmco-2-0-0-known-issues"] -=== Known issues - -* The filesystem graphs available in the web console do not display for Windows nodes. This is caused by changes in the filesystem queries. This will be fixed in a future release of WMCO. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1930347[*BZ#1930347*]) - -* The Prometheus windows_exporter used by the WMCO currently collects metrics through HTTP, so it is considered unsafe. You must ensure that only trusted users can retrieve metrics from the endpoint. The windows_exporter feature recently added support for HTTPS configuration, but this configuration has not been implemented for WMCO. Support for HTTPS configuration in the WMCO will be added in a future release. - -* The kube-proxy service terminates unexpectedly after the load balancer is created if you create the load balancer after the Windows pods begin running. To avoid this issue, you must create the load balancer before the Windows pods status transitions to `Running`. (link:https://bugzilla.redhat.com/show_bug.cgi?id=1939968[*BZ#1939968*]) \ No newline at end of file diff --git a/windows_containers/windows-node-upgrades.adoc b/windows_containers/windows-node-upgrades.adoc deleted file mode 100644 index f68cdfa6efc2..000000000000 --- a/windows_containers/windows-node-upgrades.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="windows-node-upgrades"] -= Windows node upgrades -include::modules/common-attributes.adoc[] -:context: windows-node-upgrades - -toc::[] - -You can ensure your Windows nodes have the latest updates by upgrading the Windows Machine Config Operator (WMCO). - -include::modules/wmco-upgrades.adoc[leveloffset=+1] - -For more information on Operator upgrades using the Operator Lifecycle Manager (OLM), see xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators].